Phase 3 Foundation Tracking: Mesh Contracts, Trust Modes, and Module CI Profile

[seldonrios]

Objective

Track the Phase 3 foundation scope after the v0.3.1 stabilization release so we can execute spec -> contract tests -> implementation without scope drift.

Scope Locks

• Mesh delegation failure contract test matrix:
  • missing token
  • bad signature
  • wrong scope
  • expired token
  • timeout fallback-to-local
• Marketplace trust-mode contract tests:
  • strict (fail closed)
  • warn
  • off
• External module certification CI profile refresh:
  • align workflow action versions with root repo standards
  • publish module-author quickstart flow scaffold -> validate -> certify

Deliverables

• Contract test definitions documented and linked from architecture docs.
• Automated test suites for mesh delegation auth/fallback behavior.
• Automated trust-mode behavior checks wired into CI.
• Updated external module CI profile and guidance.

Milestone Policy

This issue is planning + tracking only. Implementation PRs should be opened after v0.3.1 stabilization is released.

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The codebase is a TypeScript monorepo (pnpm workspaces, Node.js node:test runner). The two primary areas of concern are:

• packages/mesh/src/runtime.test.ts — already covers missing-token, wrong-scope, no-node, leader election, and heartbeat. Missing: bad signature, expired token, and timeout-fallback-to-local delegation failure cases.
• packages/cli/src/commands/marketplace.test.ts — already covers strict, warn, off, signed acceptance, and merge precedence. All five required trust-mode contract tests are already present.
• templates/module/community-module-ci.yml — uses actions/checkout@v4, pnpm/action-setup@v4, actions/setup-node@v4, while the root repo standard (.github/workflows/ci.yml, mesh-integration.yml, etc.) uses @v6/@v5. The quickstart scaffold flow is also absent from the template.
• Architecture docs (docs/architecture/mesh-protocol-v1.md, docs/architecture/marketplace-trust-contract-v1.md) exist but do not link to the test files.

---

Approach

The trust-mode contract tests are already complete, so no new test code is needed there. The work splits into three focused tracks: (1) add the three missing mesh delegation failure contract tests to runtime.test.ts, (2) update the external module CI template to match root repo action versions and add a quickstart scaffold step, and (3) link the test files from the architecture docs. This keeps scope tight and avoids touching already-passing tests.

---

Implementation Steps

Track 1 — Mesh Delegation Failure Contract Tests

Add three new test(...) blocks to file:packages/mesh/src/runtime.test.ts, following the same pattern as the existing tests (use node:test, node:assert/strict, MeshRpcServer, MeshRpcClient, JwtService):

1a. Bad signature (tampered/invalid JWT)

• Start a MeshRpcServer on a free port (e.g. 58031).
• Craft a raw Authorization: Bearer <garbage-token> header (not issued by JwtService) and POST to /rpc/goal-plan.
• Assert the response status is 401.
• Name the test: 'mesh rpc server rejects requests with bad jwt signature'.

1b. Expired token

• Start a MeshRpcServer on a free port (e.g. 58032).
• Use JwtService to issue a token, then manipulate the expiry — either by passing a very short TTL option if the service supports it, or by directly constructing a JWT with exp set to a past timestamp using the same HMAC secret read from LIFEOS_JWT_SECRET (check packages/security/src for the signing interface).
• POST to /rpc/goal-plan with the expired token.
• Assert the response status is 401.
• Name the test: 'mesh rpc server rejects expired jwt token'.

1c. Timeout fallback-to-local

• Write a mesh state file pointing to a node whose rpcUrl is an unreachable address (e.g. http://127.0.0.1:19999).
• Instantiate MeshCoordinator with LIFEOS_MESH_DELEGATION_TIMEOUT_MS set to a short value (e.g. '300').
• Call coordinator.delegateGoalPlan(...).
• Assert delegated.delegated === false and delegated.reason matches 'timeout' or 'rpc_error' (confirm the exact reason string from runtime.ts lines 486–700).
• Name the test: 'mesh coordinator falls back to local on rpc timeout'.

Note: Before writing the expired-token test, read packages/security/src/ to confirm whether JwtService.issue() accepts a TTL/expiry option or whether you need to construct the token manually.

---

Track 2 — External Module CI Profile Refresh

2a. Align action versions in file:templates/module/community-module-ci.yml

Update the three action pins to match the root repo standard:

Action	Current	Target
actions/checkout	@v4	@v6
pnpm/action-setup	@v4	@v5
actions/setup-node	@v4	@v6

Also change node-version: 20 → node-version: '20.19.0' to pin the exact version used across all root workflows.

2b. Add quickstart scaffold → validate → certify flow

Extend the validate-module job in file:templates/module/community-module-ci.yml with a comment block and additional steps that demonstrate the full author flow:

# Quickstart: scaffold -> validate -> certify
# Step 1: build is already covered above
# Step 2: validate manifest
- run: pnpm lifeos module validate --all
# Step 3: dry-run certification check (mirrors module-validate.yml)
- run: pnpm lifeos module certify --dry-run

This mirrors what file:.github/workflows/module-validate.yml already does and gives external authors a copy-paste starting point.

2c. Update file:docs/community/works-with-lifeos-checklist.md

Under the CI Validation Profile section, add a reference to the updated template path and the three-step flow:

• Point readers to templates/module/community-module-ci.yml as the canonical starting point.
• List the three commands: pnpm run build:modules, pnpm lifeos module validate --all, pnpm lifeos module certify --dry-run.

---

Track 3 — Link Contract Tests from Architecture Docs

3a. file:docs/architecture/mesh-protocol-v1.md

Under the existing Deterministic Test Coverage (Required) section, add a Test File subsection that links to:

• packages/mesh/src/runtime.test.ts — covering all auth reject paths, delegation, leader election, fallback, and trace propagation.
• packages/mesh/src/index.test.ts — covering registry join/resolve/persist.

List each test case name alongside the contract requirement it satisfies (e.g. "missing token → mesh rpc server rejects requests without auth token").

3b. file:docs/architecture/marketplace-trust-contract-v1.md

Under the existing Required Test Coverage section, add a Test File subsection linking to:

• packages/cli/src/commands/marketplace.test.ts — covering all five trust-mode contract cases.

List each test case name alongside the contract requirement it satisfies.

---

Sequence of Changes

sequenceDiagram
    participant Dev
    participant runtime.test.ts
    participant community-module-ci.yml
    participant works-with-lifeos-checklist.md
    participant mesh-protocol-v1.md
    participant marketplace-trust-contract-v1.md

    Dev->>runtime.test.ts: Add bad-signature test (58031)
    Dev->>runtime.test.ts: Add expired-token test (58032)
    Dev->>runtime.test.ts: Add timeout-fallback-to-local test (58033)
    Dev->>community-module-ci.yml: Bump action versions to v6/v5/v6
    Dev->>community-module-ci.yml: Add certify --dry-run step + comments
    Dev->>works-with-lifeos-checklist.md: Reference template + 3-step flow
    Dev->>mesh-protocol-v1.md: Link runtime.test.ts + index.test.ts with test-to-contract mapping
    Dev->>marketplace-trust-contract-v1.md: Link marketplace.test.ts with test-to-contract mapping

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is a TypeScript monorepo (pnpm workspaces, Node.js `node:test` runner). The two primary areas of concern are:

- **`packages/mesh/src/runtime.test.ts`** — already covers missing-token, wrong-scope, no-node, leader election, and heartbeat. **Missing**: bad signature, expired token, and timeout-fallback-to-local delegation failure cases.
- **`packages/cli/src/commands/marketplace.test.ts`** — already covers `strict`, `warn`, `off`, signed acceptance, and merge precedence. All five required trust-mode contract tests are **already present**.
- **`templates/module/community-module-ci.yml`** — uses `actions/checkout@v4`, `pnpm/action-setup@v4`, `actions/setup-node@v4`, while the root repo standard (`.github/workflows/ci.yml`, `mesh-integration.yml`, etc.) uses `@v6`/`@v5`. The quickstart scaffold flow is also absent from the template.
- Architecture docs (`docs/architecture/mesh-protocol-v1.md`, `docs/architecture/marketplace-trust-contract-v1.md`) exist but do not link to the test files.

---

## Approach

The trust-mode contract tests are already complete, so no new test code is needed there. The work splits into three focused tracks: (1) add the three missing mesh delegation failure contract tests to `runtime.test.ts`, (2) update the external module CI template to match root repo action versions and add a quickstart scaffold step, and (3) link the test files from the architecture docs. This keeps scope tight and avoids touching already-passing tests.

---

## Implementation Steps

### Track 1 — Mesh Delegation Failure Contract Tests

Add three new `test(...)` blocks to `file:packages/mesh/src/runtime.test.ts`, following the same pattern as the existing tests (use `node:test`, `node:assert/strict`, `MeshRpcServer`, `MeshRpcClient`, `JwtService`):

#### 1a. Bad signature (tampered/invalid JWT)

- Start a `MeshRpcServer` on a free port (e.g. `58031`).
- Craft a raw `Authorization: Bearer <garbage-token>` header (not issued by `JwtService`) and POST to `/rpc/goal-plan`.
- Assert the response status is `401`.
- Name the test: `'mesh rpc server rejects requests with bad jwt signature'`.

#### 1b. Expired token

- Start a `MeshRpcServer` on a free port (e.g. `58032`).
- Use `JwtService` to issue a token, then manipulate the expiry — either by passing a very short TTL option if the service supports it, or by directly constructing a JWT with `exp` set to a past timestamp using the same HMAC secret read from `LIFEOS_JWT_SECRET` (check `packages/security/src` for the signing interface).
- POST to `/rpc/goal-plan` with the expired token.
- Assert the response status is `401`.
- Name the test: `'mesh rpc server rejects expired jwt token'`.

#### 1c. Timeout fallback-to-local

- Write a mesh state file pointing to a node whose `rpcUrl` is an unreachable address (e.g. `http://127.0.0.1:19999`).
- Instantiate `MeshCoordinator` with `LIFEOS_MESH_DELEGATION_TIMEOUT_MS` set to a short value (e.g. `'300'`).
- Call `coordinator.delegateGoalPlan(...)`.
- Assert `delegated.delegated === false` and `delegated.reason` matches `'timeout'` or `'rpc_error'` (confirm the exact reason string from `runtime.ts` lines 486–700).
- Name the test: `'mesh coordinator falls back to local on rpc timeout'`.

> **Note:** Before writing the expired-token test, read `packages/security/src/` to confirm whether `JwtService.issue()` accepts a TTL/expiry option or whether you need to construct the token manually.

---

### Track 2 — External Module CI Profile Refresh

#### 2a. Align action versions in `file:templates/module/community-module-ci.yml`

Update the three action pins to match the root repo standard:

| Action | Current | Target |
|---|---|---|
| `actions/checkout` | `@v4` | `@v6` |
| `pnpm/action-setup` | `@v4` | `@v5` |
| `actions/setup-node` | `@v4` | `@v6` |

Also change `node-version: 20` → `node-version: '20.19.0'` to pin the exact version used across all root workflows.

#### 2b. Add quickstart scaffold → validate → certify flow

Extend the `validate-module` job in `file:templates/module/community-module-ci.yml` with a comment block and additional steps that demonstrate the full author flow:

```
# Quickstart: scaffold -> validate -> certify
# Step 1: build is already covered above
# Step 2: validate manifest
- run: pnpm lifeos module validate --all
# Step 3: dry-run certification check (mirrors module-validate.yml)
- run: pnpm lifeos module certify --dry-run
```

This mirrors what `file:.github/workflows/module-validate.yml` already does and gives external authors a copy-paste starting point.

#### 2c. Update `file:docs/community/works-with-lifeos-checklist.md`

Under the **CI Validation Profile** section, add a reference to the updated template path and the three-step flow:

- Point readers to `templates/module/community-module-ci.yml` as the canonical starting point.
- List the three commands: `pnpm run build:modules`, `pnpm lifeos module validate --all`, `pnpm lifeos module certify --dry-run`.

---

### Track 3 — Link Contract Tests from Architecture Docs

#### 3a. `file:docs/architecture/mesh-protocol-v1.md`

Under the existing **Deterministic Test Coverage (Required)** section, add a **Test File** subsection that links to:

- `packages/mesh/src/runtime.test.ts` — covering all auth reject paths, delegation, leader election, fallback, and trace propagation.
- `packages/mesh/src/index.test.ts` — covering registry join/resolve/persist.

List each test case name alongside the contract requirement it satisfies (e.g. "missing token → `mesh rpc server rejects requests without auth token`").

#### 3b. `file:docs/architecture/marketplace-trust-contract-v1.md`

Under the existing **Required Test Coverage** section, add a **Test File** subsection linking to:

- `packages/cli/src/commands/marketplace.test.ts` — covering all five trust-mode contract cases.

List each test case name alongside the contract requirement it satisfies.

---

### Sequence of Changes

```mermaid
sequenceDiagram
    participant Dev
    participant runtime.test.ts
    participant community-module-ci.yml
    participant works-with-lifeos-checklist.md
    participant mesh-protocol-v1.md
    participant marketplace-trust-contract-v1.md

    Dev->>runtime.test.ts: Add bad-signature test (58031)
    Dev->>runtime.test.ts: Add expired-token test (58032)
    Dev->>runtime.test.ts: Add timeout-fallback-to-local test (58033)
    Dev->>community-module-ci.yml: Bump action versions to v6/v5/v6
    Dev->>community-module-ci.yml: Add certify --dry-run step + comments
    Dev->>works-with-lifeos-checklist.md: Reference template + 3-step flow
    Dev->>mesh-protocol-v1.md: Link runtime.test.ts + index.test.ts with test-to-contract mapping
    Dev->>marketplace-trust-contract-v1.md: Link marketplace.test.ts with test-to-contract mapping
```

---

Execution Information

Branch: main
Commit: 48c6eeb

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.