# Transport contract map

`docs/design.md` is the authoritative contract for the AMQ transport slice. 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 that owns the fact,
the implementation file, and a fault-sensitive test that would fail if the implementation drifted
from the section.

## Identity and binding

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Identity concepts | [§6.1](../design.md#61-identity-concepts) | `BindingResolver` | `transport/binding-resolver.ts` | `test/binding-resolver.test.ts` |
| Configuration precedence | [§6.2](../design.md#62-configuration-precedence) | `BindingResolver` | `transport/binding-resolver.ts` | `test/binding-resolver.test.ts` |
| Dormant to confirmed bind | [§6.3](../design.md#63-dormant-to-confirmed-bind) | `ConfirmedBindOnboarding` | `integration/confirmed-bind-onboarding.ts` | `test/confirmed-bind-onboarding.test.ts` |
| Persisted pi-session entry | [§6.4](../design.md#64-persisted-pi-session-entry) | `BindingResolver` (`PI_AMQ_BINDING_ENTRY_TYPE`) | `transport/binding-resolver.ts` | `test/binding-resolver.test.ts` |
| Reload, resume, new session, and fork | [§6.5](../design.md#65-reload-resume-new-session-and-fork) | `PiAmqRuntime` | `extension/runtime.ts` | `test/extension-lifecycle-integration.test.ts` |

## Lease and extension-owned persistence

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Receiver lease and extension-owned persistence | [§7](../design.md#7-receiver-lease-and-extension-owned-persistence) | `ReceiverLeaseManager` | `transport/receiver-lease.ts` | `test/receiver-lease.test.ts` |
| Lease behavior | [§7.1](../design.md#71-lease-behavior) | `ReceiverLeaseManager`, `LeaseFenceError` | `transport/receiver-lease.ts` | `test/receiver-lease.test.ts` |
| Minimal bridge journal | [§7.2](../design.md#72-minimal-bridge-journal) | `BridgeJournal` | `transport/bridge-journal.ts` | `test/bridge-journal.test.ts` |
| Process identity used by the receiver lease | [§7.1](../design.md#71-lease-behavior) | `LocalProcessIdentityInspector` | `transport/receiver-lease.ts` | `test/receiver-lease.test.ts` |

## Ingestion, priority, and delivery

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Incoming flow | [§8.1](../design.md#81-incoming-flow) | `InboxPump` | `transport/inbox-pump.ts` | `test/inbox-pump.test.ts` — "[doc 12,18] a cohort is journaled before exact reads, deduplicated, ordered, and DLQ-safe" |
| Priority mapping | [§8.2](../design.md#82-priority-mapping) | `PriorityDeliveryScheduler` | `transport/priority-delivery-scheduler.ts` | `test/priority-delivery-scheduler.test.ts` — "[doc 12] priority mapping and deterministic priority/created/ID order are exact" |
| Fresh-session dispatch | [§8.3](../design.md#83-fresh-session-dispatch) | `FreshSessionDispatcher`, `PiFreshSessionReplacementPort` | `integration/fresh-session-dispatcher.ts`, `extension/runtime.ts` | `test/fresh-session-dispatcher.test.ts`, `test/fresh-session-port.test.ts` |
| Envelope shape | [§8.4](../design.md#84-envelope-shape) | `PiAmqEnvelopeDetails` | `transport/priority-delivery-scheduler.ts` | `test/priority-delivery-scheduler.test.ts` — "[doc 16] every coalesced envelope retains immutable reply provenance" |
| Large bodies and context limits | [§8.5](../design.md#85-large-bodies-and-context-limits) | `PriorityDeliveryScheduler` | `transport/priority-delivery-scheduler.ts` | `test/priority-delivery-scheduler.test.ts` — "[doc 17] individual previews are 8 KiB, batches are 24 KiB, and truncation is explicit" |
| Consumption and receipt semantics | [§9](../design.md#9-consumption-and-receipt-semantics) | `AmqOperations`, `AmqDlqRetryAuditVerifier` | `transport/amq-operations.ts`, `transport/dlq-retry-audit.ts` | `test/amq-operations.test.ts`, `test/dlq-retry-audit.test.ts` |

## Addressing and delegation

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Default rule | [§10.1](../design.md#101-default-rule) | `PiAmqRuntime` tool activation | `extension/runtime.ts` | `test/stock-pi-integration.test.ts` — "[doc 9] stock print/json pi subprocesses inherit AM_ME, stay send-only, and emit one attributed send" |
| Sending from a subagent | [§10.2](../design.md#102-sending-from-a-subagent) | `PiAmqRuntime` tool activation | `extension/runtime.ts` | `test/stock-pi-integration.test.ts` |
| A subagent that must receive | [§10.3](../design.md#103-a-subagent-that-must-receive) | `ReceiverLeaseManager` | `transport/receiver-lease.ts` | `test/receiver-lease.test.ts` |
| Recipient semantics | [§11.1](../design.md#111-recipient-semantics) | `AmqOperations` | `transport/amq-operations.ts` | `test/amq-operations.test.ts` |
| Bcc-like requests | [§11.2](../design.md#112-bcc-like-requests) | `AmqOperations` | `transport/amq-operations.ts` | `test/amq-operations.test.ts` |
| Thread participation | [§11.3](../design.md#113-thread-participation) | `AmqOperations` | `transport/amq-operations.ts` | `test/amq-operations.test.ts` |
| Local visibility guarantee | [§11.4](../design.md#114-local-visibility-guarantee) | `AmqCliAdapter` | `transport/amq-cli-adapter.ts` | `test/stock-amq-integration.test.ts` |

## Session surface

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| LLM tools and operator commands | [§12](../design.md#12-llm-tools-and-operator-commands) | `registerAmqTools` | `extension/tools.ts` | `test/extension-registration.test.ts` |
| `before_agent_start` guidance | [§13](../design.md#13-before_agent_start-guidance) | `buildBeforeAgentGuidance`, `AMQ_MESSAGING_DOCTRINE` | `extension/guidance.ts` | `test/guidance.test.ts`, `test/extension-registration.test.ts` — "[doc 16] queued interactive input cannot clear or overwrite immutable per-envelope reply provenance" |
| Factory and startup | [§14.1](../design.md#141-factory-and-startup) | `PiAmqRuntime.register` | `extension/runtime.ts` | `test/extension-registration.test.ts` |
| During a run | [§14.2](../design.md#142-during-a-run) | `PresenceProjector`, `InboxStatusStore` | `transport/presence-projector.ts`, `transport/runtime-status.ts` | `test/presence-projector.test.ts`, `test/runtime-status.test.ts` |
| Shutdown and replacement | [§14.3](../design.md#143-shutdown-and-replacement) | `PiAmqRuntime` | `extension/runtime.ts` | `test/extension-lifecycle-integration.test.ts` |
| Compaction | [§14.4](../design.md#144-compaction) | `buildPendingProjection` | `extension/guidance.ts` | `test/guidance.test.ts` |

## Failure, trust, and compatibility

| Contract | Authority | Owner | Implementation | Fault-sensitive evidence |
| --- | --- | --- | --- | --- |
| Failure modes and required behavior | [§15](../design.md#15-failure-modes-and-required-behavior) | `InboxPump`, `BridgeJournal` | `transport/inbox-pump.ts`, `transport/bridge-journal.ts` | `test/inbox-pump.test.ts` — "[doc 2] a failed pending commit cannot consume, and the next pump finds the same ID" |
| Security and trust | [§16](../design.md#16-security-and-trust) | `resolveWorkerLaunch`, `isReceiverAuthorityEnvironmentKey` | `workflow/worker-launch.ts` | `test/worker-launch-contract.test.ts` |
| Versioning and compatibility | [§17](../design.md#17-versioning-and-compatibility) | `package.json#peerDependencies` | `package.json` | `test/package/packaged-artifact-smoke.test.ts` |
| Fresh-session automation compatibility amendment | [§17.1](../design.md#171-fresh-session-automation-compatibility-amendment) | `CommandContextFreshSessionCapability` | `integration/fresh-session-dispatcher.ts` | `test/fresh-session-port.test.ts`, `test/inbox-pump.test.ts` — "[doc 14] a not-yet-disk-visible fresh-session projection stays pending with its target set until reconciliation observes the flush" |