# Worker runtime contract map

`docs/design.md` Appendix A is the authoritative contract for the governed worker runtime.
This file is a navigation map: it adds no rule, defines no term, and repeats no clause. Where
anything here disagrees with `docs/design.md`, `docs/design.md` wins and this map is wrong.

This is a navigation aid, not a second index of the design. Most Contract cells reuse a design
section title; some name a concept that the linked section covers without giving it a heading of
its own. Read the linked section for the rule. Each row also names the type or function that owns
the fact, the implementation file, and a fault-sensitive test that would fail if the
implementation drifted from the section.

## Boundary and capability surface

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Verdict and revised product boundary | [§A.1](../design.md#a1-verdict-and-revised-product-boundary) | `PiWorkerRuntime` | `extension/worker-runtime.ts` | `test/worker-runtime-policy.test.ts` |
| A-prime topology and atomic capability surface | [§A.2](../design.md#a2-a-prime-topology-and-atomic-capability-surface) | `registerWorkerTools` | `extension/worker-tools.ts` | `test/worker-tools.test.ts`, `test/extension-registration.test.ts` |
| Named role declarations | [§A.2](../design.md#a2-a-prime-topology-and-atomic-capability-surface) | `WorkerRolePresetCatalog`, `parseWorkerRolePreset` | `workflow/worker-role-presets.ts`, `roles/` | `test/worker-role-presets.test.ts` |
| Model catalog guidance and ordered fallback | [§A.2](../design.md#a2-a-prime-topology-and-atomic-capability-surface) | `selectWorkerModel`, `classifyProviderFallbackFailure` | `workflow/worker-model-catalog.ts`, `workflow/model-fallback.ts` | `test/worker-model-catalog.test.ts` |
| `confirm_spawns` launch gate | [§A.2](../design.md#a2-a-prime-topology-and-atomic-capability-surface) | `LaunchPreviewCoordinator`, `LaunchPreviewModel` | `workflow/spawn-confirmation.ts`, `integration/launch-preview.ts` | `test/spawn-confirmation.test.ts`, `test/launch-preview.test.ts` |
| Immutable worker prompt capsule | [§A.2](../design.md#a2-a-prime-topology-and-atomic-capability-surface) | `canonicalWorkerCapsule`, `assertWorkerCapsuleMirrored` | `workflow/worker-prompt-capsule.ts` | `test/worker-prompt-capsule.test.ts` |
| The minimal declarative corner | [§A.3](../design.md#a3-the-minimal-declarative-corner) | `WorkerRolePresetCatalog`, `reportMatchesSchema` | `workflow/worker-role-presets.ts`, `workflow/worker-gate.ts` | `test/worker-role-presets.test.ts`, `test/worker-gate.test.ts` |
| What is lost, and why it does not justify a script engine | [§A.3.1](../design.md#a31-what-is-lost-and-why-it-does-not-justify-a-script-engine) | `registerWorkerTools` (no `pipeline`, `parallel`, `judge`, `loop` tool) | `extension/worker-tools.ts` | `test/extension-registration.test.ts` — "factory registers lifecycle, typed tools, flags, and operator commands without activation" |

## Ledger, authority, and recovery

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Namespace and authority | [§A.5.1](../design.md#a51-namespace-and-authority) | `workflowNamespaceDirectory`, `WorkflowLeaseManager` | `workflow/workspace-paths.ts`, `workflow/workflow-lease.ts` | `test/workflow-lease.test.ts`, `test/workflow-domain-isolation.test.ts` — "[appendix 38] AMQ correlation never cross-replays or cross-mutates persistence owners" |
| In-process reload adoption | [§A.5.1](../design.md#a51-namespace-and-authority) | `PiWorkerRuntime`, process-global runtime registry | `extension/worker-runtime.ts` | `test/worker-runtime-reload.test.ts` — replacement preserves live list/steer/cancel control and detaches old UI subscribers; missing or mismatched ownership fails closed |
| Ledger projection schema | [§A.5.2](../design.md#a52-ledger-projection-schema) | `WorkflowRunStore` | `workflow/run-store.ts`, `workflow/atomic-storage.ts` | `test/workflow-run-store.test.ts` |
| Run and worker budgets | [§A.5.2](../design.md#a52-ledger-projection-schema) | `limited`, `parseBudgetLimit`, `budgetExceeded` | `workflow/budget.ts` | `test/budget.test.ts` |
| Lifecycle and recovery rules | [§A.5.3](../design.md#a53-lifecycle-and-recovery-rules) | `evaluateRunTransition`, `evaluateWorkerAttemptTransition` | `workflow/run-gate.ts`, `workflow/worker-gate.ts` | `test/run-gate.test.ts`, `test/worker-gate.test.ts` |
| Completion notices | [§A.5.3](../design.md#a53-lifecycle-and-recovery-rules) | `WorkerCompletionNotifier` | `integration/worker-completion-notifier.ts` | `test/worker-completion-notifier.test.ts` |
| Implemented W2 process-supervision boundary | [§A.5.4](../design.md#a54-implemented-w2-process-supervision-boundary) | `WorkerProcessSupervisor`, `NodePiProcessFactory` | `workflow/worker-process-supervisor.ts` | `test/worker-process-supervisor.test.ts`, `test/node-pi-process-factory.test.ts` |
| Exact send-only child launch contract | [§A.5.4](../design.md#a54-implemented-w2-process-supervision-boundary) | `parseWorkerLaunchContract`, `parseWorkerLaunchContractV2`, `resolveWorkerLaunch`, `validateWorkerChildContext` | `workflow/worker-launch.ts`, `workflow/worker-child-extension.ts` | `test/worker-launch-contract.test.ts`, `test/stock-worker-protocol-integration.test.ts` — schema-1 historical read compatibility plus real Pi JSON/RPC fd-4 and fail-closed descriptor evidence |
| Worker session fork source | [§A.5.4](../design.md#a54-implemented-w2-process-supervision-boundary) | `describeCurrentPiSessionFork`, `NodePiSessionForker` | `workflow/pi-session-fork.ts` | `test/pi-session-fork.test.ts` |
| Supervisor process identity | [§A.5.4](../design.md#a54-implemented-w2-process-supervision-boundary) | `SystemProcessIdentityInspector` — the only owner outside the receiver lease's own inspector | `workflow/system-process-inspector.ts` | `test/system-process-inspector.test.ts` — see [deferred findings](deferred-findings.md) |

## Guidance and observability

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Coordination guidance surface | [§A.6](../design.md#a6-coordination-guidance-surface) | `WORKER_TEAM_DOCTRINE`, `appendWorkerTeamDoctrine` | `extension/guidance.ts`, `skills/coordination-patterns` | `test/guidance.test.ts`, `test/coordination-skill.test.ts` |
| Worker lifecycle observability via AMQ adapter contract | [§A.6.1](../design.md#a61-worker-lifecycle-observability-via-amq-adapter-contract) | `projectWorkerLifecycle` | `workflow/lifecycle-projection.ts` | `test/lifecycle-projection.test.ts` |
| Worker inspection ladder and below-editor FleetView | [§A.6.2](../design.md#a62-worker-inspection-ladder-and-below-editor-fleetview) | `FleetListModel`, `handleFleetInput`, `renderFleetDetail` | `integration/fleet-view.ts` | `test/fleet-view.test.ts` |

## W3 primitive and Gate amendment

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| W3 primitive and Gate amendment | [§A.9](../design.md#a9-w3-primitive-and-gate-amendment) | `WorkflowRunStore`, `effectiveWorkerContract` | `workflow/run-store.ts` | `test/workflow-run-store.test.ts` |
| Shared run artifact directory | [§A.9](../design.md#a9-w3-primitive-and-gate-amendment) | `runArtifactDirectory`, `withRunArtifactContext` | `workflow/run-artifacts.ts` | `test/run-artifacts.test.ts` |
| Directional peer messaging and correlated waits | [§A.9](../design.md#a9-w3-primitive-and-gate-amendment) | `WorkerProcessSupervisor`, `WorkflowRunStore` | `workflow/worker-process-supervisor.ts`, `workflow/run-store.ts` | `test/worker-process-supervisor.test.ts`, `test/workflow-run-store.test.ts` |
| Audited supervisor-fenced cleanup | [§A.9](../design.md#a9-w3-primitive-and-gate-amendment) | `WorkflowRunCleanup`, `parseCleanupAge` | `workflow/run-cleanup.ts` | `test/run-cleanup.test.ts` |
| Read-only workflow doctor | [§A.9](../design.md#a9-w3-primitive-and-gate-amendment) | `WorkflowDoctor` | `workflow/workflow-doctor.ts` | `test/workflow-doctor.test.ts` |