feat(start-amqp): the AMQP consumer runtime

[btravers]

The last deferred runtime package, and the fourth deployment of the order example consuming through it. Deferred, deliberately loses its first entry.

Why this package exists

TypedAmqpWorker.close() is the whole of an AMQP worker's shutdown — cancel every consumer, drain in-flight handlers so their acks land on a still-open channel, then close — and its drain budget is a parameter, not a constructor setting. So this runtime does something -temporal cannot: it passes drainTimeoutMs: null and races the kernel's own AbortSignal against it.

The kernel's drainTimeoutMs is the only deadline in the process. -temporal's README has to warn you to keep forceAfter at or below it and raise them together; this package has no such warning to give, because there is no second number.

The integration, in full

start(OrderAmqpModule, {
  runtime: amqpRuntime({
    urls: [env.AMQP_URL],
    contract: orderContract,
    needs: [PlaceOrder, Logger],
    handlers: (host) => ({ placeOrder: placeHandler(orderContract) }),
    middleware: (host) => messageUnits<AmqpNeeds>(host),
  }),
});

One line — the middleware — is what an amqp-contract user adds. @amqp-contract/contract stays out of the published type surface: MessageMiddleware is declared structurally in our own source.

Four things the wave learned that the spec had wrong

Each was found by an implementer or reviewer reading the installed library rather than trusting the plan, and each is now in the docs:

1. @amqp-contract/worker had to become a peer. A value import of TypedAmqpWorker was being inlined — 344 KB of dist and a second private copy of amqplib in any app that also uses amqp-contract, which every consumer of this package does by construction. Now ~5 KB. The spec's "devDependency, never a peer" was a bad analogy from -temporal, which only borrows a type from its contract library.
2. A Defect is NOT retried by the library. dispatchMessage nacks it once with requeue: false — straight to the DLQ, never touching the queue's retry config. So an infrastructure failure would be parked on its first attempt exactly like a permanent domain error unless the handler recovers it into a RetryableError. Two agents confirmed this independently from the dispatch source. Every consumer would have hit it; CLAUDE.md's Thesis fix: audit dropped Results, and document two runtime contracts #3 now records the three-way split — the library's, the handler's, and never the kernel's.
3. "The broker redelivers an abandoned delivery" was an overclaim. At the kernel's deadline nothing is dropped — close() holds the connection open — so nothing is redelivered. That only happens if the process actually dies, which no in-process test can observe. The test that claimed it in its title now claims what it proves.
4. maxRetries: 3 means four total attempts, where Temporal's maximumAttempts: 3 means three.

What shipped

• packages/start-amqp — amqpRuntime, messageUnits, AmqpInfo (queues derived from the contract, so Serving.info cannot disagree with what the worker consumes), the deadline race, 8 specs at 100% lines/functions.
• examples/order-amqp-contract — exchange, queue with a dead-letter exchange and ttl-backoff retry, publisher, consumer, layering.test-d.ts.
• examples/order-amqp — the fourth deployment: the same ApplicationModule, the mapErrCases triage into NonRetryableError/RetryableError, 9 specs against a real broker.
• Package README + CLAUDE.md, root CLAUDE.md, examples/README.md (eleven workspaces), and a changeset.

Testing needs Docker, and that is now the rule

@amqp-contract/testing is testcontainers-based; there is no in-process AMQP broker the way Temporal ships a time-skipping binary, and a hand-written channel double would test our own fake rather than the drain. 1c2e724 replaced the repo's no-Docker ban with a positive rule — reach for the cheapest fixture that tests the real behaviour — and rewrote the three sentences that cited the ban as their reason.

Unverified: whether CI's runner has a Docker socket. .github/workflows/ci.yml delegates wholly to btravstack/config's reusable workflow, which cannot be read or modified from here. GitHub-hosted Ubuntu runners ship a daemon, so this should work with no workflow change — if it does not, the fix is an input added upstream, not here. Watch this PR's first CI run.

Follow-up, deliberately not in this PR

packages/start-amqp/tsconfig.json does not exclude src/**/*.test-d.ts, where packages/start and examples/order-amqp both do. Harmless today — the file compiles clean under the stricter config — but a future type test with an intentionally-unused parameter would fail the main tsc run for the reason the relaxed config exists to avoid. One line, surfaced rather than folded into a second fix wave.

Process

Eight tasks, each implemented by a fresh subagent and reviewed by another; three plan defects were caught mid-flight and corrected, and a final whole-branch review raised three Important findings — a handler map typed loosely enough to accept a typo'd key, builders throwing outside the qualified chain (exit 70 where the sibling deliberately exits 1), and a changeset that stated a false peer-dependency fact. All fixed and re-verified, blocker B by reproducing its mutation independently.

Local suite: 219 tests across 16 workspaces, green except packages/start's documented binds 9000, which is a proxy on the author's machine.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds the missing AMQP consumer runtime to the @btravstack/start ecosystem (packages/start-amqp) and extends the order example with a fourth deployment (examples/order-amqp) plus its standalone transport contract (examples/order-amqp-contract). The change fits the repo’s “one process, one runtime” model by providing the last runtime kind and proving it end-to-end via a real broker-backed example and tests.

Changes:

• Introduces @btravstack/start-amqp (amqpRuntime, messageUnits, AmqpInfo) with drain semantics that race the kernel deadline against an indefinite worker close.
• Adds order-amqp and order-amqp-contract example workspaces (runtime + contract split) with Docker-backed integration tests via @amqp-contract/testing.
• Updates repo docs/specs and workspace catalog pins to reflect the new runtime and required beta dependencies.

Reviewed changes

Copilot reviewed 43 out of 47 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Updates runtime map/docs to include start-amqp and the 4th example deployment.
pnpm-workspace.yaml	Pins @amqp-contract/* beta versions and adds required catalog entries (incl. @opentelemetry/api).
packages/start-amqp/vitest.config.ts	New Vitest config for runtime package (container-backed global setup + 100% coverage thresholds).
packages/start-amqp/tsconfig.test-d.json	Adds relaxed type-test tsconfig for *.test-d.ts.
packages/start-amqp/tsconfig.json	New TS config for building/typechecking the runtime package.
packages/start-amqp/src/vitest.d.ts	Registers @unthrown/vitest type augmentations for this workspace tests.
packages/start-amqp/src/test-fixtures.ts	Test fixtures wiring a real TypedAmqpWorker into start(...) for runtime specs.
packages/start-amqp/src/message-units.ts	Implements middleware that opens one kernel unit per delivery and injects DI context.
packages/start-amqp/src/index.ts	Public exports for amqpRuntime, messageUnits, and types.
packages/start-amqp/src/amqp-runtime.ts	Runtime implementation: worker creation, info publishing, and deadline race during drain/stop.
packages/start-amqp/src/amqp-runtime.test-d.ts	Type-level gate asserting handlers are checked against the contract keys.
packages/start-amqp/src/amqp-runtime.spec.ts	Runtime behavior specs: startup error channeling, unit boundary, drain deadline behavior.
packages/start-amqp/README.md	Package README documenting usage, drain semantics, and transport boundary responsibilities.
packages/start-amqp/package.json	New published-package manifest: peers, scripts, and ESM/CJS exports layout.
packages/start-amqp/LICENSE	Adds MIT license file for the new package.
packages/start-amqp/CLAUDE.md	Package-local public-surface and invariants documentation for start-amqp.
examples/README.md	Updates examples index to eleven workspaces / four deployments and the new contract/runtime split.
examples/order-temporal/README.md	Adjusts Docker/testcontainers wording to match updated integration-test policy.
examples/order-amqp/vitest.config.ts	New Vitest config for AMQP deployment example (global RabbitMQ container).
examples/order-amqp/tsconfig.test-d.json	Adds type-test tsconfig for *.test-d.ts in AMQP example.
examples/order-amqp/tsconfig.json	New TS config for AMQP example workspace.
examples/order-amqp/src/vitest.d.ts	Registers @unthrown/vitest matchers for AMQP example tests.
examples/order-amqp/src/test-fixtures.ts	Example fixtures to boot the real AMQP deployment and observe behavior via broker round-trips.
examples/order-amqp/src/needs-gate.test-d.ts	Type-level proof of start runtime-needs gate for the new deployment.
examples/order-amqp/src/module.ts	New OrderAmqpModule composition root (same app graph, different runtime).
examples/order-amqp/src/main.ts	Entry point wiring readEnv + start + runMain for the AMQP worker process.
examples/order-amqp/src/index.ts	Exports the deployment module and runtime builder.
examples/order-amqp/src/env.ts	Adds AMQP deployment env schema + readEnv() returning a Result.
examples/order-amqp/src/env.spec.ts	Validates AMQP deployment env behavior (defaults + empty-string rejection).
examples/order-amqp/src/amqp-runtime.ts	Example’s runtime “application half”: contract + handler triage into retryable/nonretryable.
examples/order-amqp/src/amqp-runtime.spec.ts	Integration specs proving retry/DLQ semantics and per-delivery unit/trace IDs.
examples/order-amqp/README.md	Deployment README: explains the 4th transport semantics, triage, and why Docker is needed.
examples/order-amqp/package.json	New example workspace manifest, depending on start-amqp and the AMQP contract.
examples/order-amqp-contract/vitest.config.ts	New Vitest config for the AMQP contract workspace.
examples/order-amqp-contract/tsconfig.test-d.json	Adds type-test tsconfig for contract workspace.
examples/order-amqp-contract/tsconfig.json	New TS config for contract workspace.
examples/order-amqp-contract/src/vitest.d.ts	Registers @unthrown/vitest matchers for contract tests.
examples/order-amqp-contract/src/test-fixtures.ts	Contract fixtures: expose contract and payload validator (contract-only proof).
examples/order-amqp-contract/src/layering.test-d.ts	Compile-time enforcement that the contract package cannot depend on its worker.
examples/order-amqp-contract/src/index.ts	Exports the AMQP contract and its type.
examples/order-amqp-contract/src/contract.ts	Defines exchange/queue/retry+DLX policy and the placement message contract.
examples/order-amqp-contract/src/contract.spec.ts	Tests contract routing config and schema validation behavior.
examples/order-amqp-contract/README.md	Contract README: explains why it is separate and how it enforces layering.
examples/order-amqp-contract/package.json	New contract workspace manifest with minimal runtime deps (zod, contract lib).
CLAUDE.md	Updates root spec to include start-amqp, AMQP example, and revised integration-test policy.
.changeset/start-amqp.md	Adds changeset for publishing @btravstack/start-amqp as a minor release.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.