@btravstack/amqp-worker 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# @btravstack/amqp-worker
+
+> The **consuming half** of AMQP for [`@btravstack/core`](../core) — publishing
+> belongs to `@amqp-contract/client`, which the outbox relay in
+> `examples/order-amqp-worker` uses directly. An
+> [`amqp-contract`](https://github.com/btravstack/amqp-contract) worker under
+> the kernel's lifecycle — one unit per delivery, and a drain with exactly one
+> deadline, the kernel's own.
+
+📖 **[Documentation](https://btravstack.github.io/btravstack/how-to/consume-amqp-messages)** ·
+[Reference](https://btravstack.github.io/btravstack/reference/amqp-worker) ·
+[API Reference](https://btravstack.github.io/btravstack/api/amqp-worker/)
+
+```sh
+pnpm add @btravstack/amqp-worker @btravstack/core @btravstack/config @btravstack/di unthrown \
+  @amqp-contract/worker @opentelemetry/api
+```
+
+All six are peer dependencies — install them (`@opentelemetry/api` because
+`@amqp-contract/worker` itself peers on it). Node `>=20`.
+
+## A worked example
+
+<!-- doctest: prelude
+import { NonRetryableError, RetryableError } from "@amqp-contract/worker";
+import { orderContract } from "@btravstack/example-order-amqp-contract";
+import { PlaceOrder } from "@btravstack/example-order-application";
+import { TenantId } from "@btravstack/example-order-domain";
+import { Module } from "@btravstack/di";
+import { OrderApplicationModule, OrderRepository, Outbox } from "@btravstack/example-order-application";
+import { OrderPersistenceModule } from "@btravstack/example-order-infrastructure";
+import { observability } from "@btravstack/observability";
+
+// The application module the README's composition imports — the orders
+// vertical plus its persistence, as an application would compose it.
+const AppModule = Module("App")({
+  imports: [OrderApplicationModule, OrderPersistenceModule, observability()],
+  exports: [PlaceOrder, OrderRepository, Outbox, Logger],
+});
+-->
+
+```ts
+import { Env } from "@btravstack/config";
+import { AmqpHandlers, AmqpModule } from "@btravstack/amqp-worker";
+import { runMain, Logger } from "@btravstack/core";
+import { ErrAsync, OkAsync, P } from "unthrown";
+
+// The handlers, as a service: one entry per consumer the contract declares,
+// built by di from the use cases it lists — no injected context — on the
+// starter's own handlers port, typed by the contract (a consumer serves one
+// handlers record, so there is nothing to name).
+const orderHandlers = AmqpHandlers(orderContract)(
+  { placeOrder: PlaceOrder },
+  {
+    sync: ({ placeOrder }) => ({
+      orderNotifications: (message) =>
+        placeOrder
+          .execute(
+            TenantId(message.payload.tenantId),
+            message.payload.id,
+            message.payload.payload?.quantity ?? 0,
+          )
+          .map(() => undefined)
+          // A modeled domain error is permanent: dead-letter it, no retry.
+          .mapErrCases((matcher) =>
+            matcher.with(
+              P.tag("InvalidQuantity"),
+              P.tag("InvalidOrderId"),
+              P.tag("DuplicateOrder"),
+              (error) => new NonRetryableError(error._tag, error),
+            ),
+          )
+          // Infrastructure failing is not: recover the defect into a retry.
+          .recoverDefect((cause) =>
+            ErrAsync(new RetryableError("placing the order failed", cause)),
+          ),
+      // Every consumer the contract declares must be covered — an uncovered
+      // key is refused at this call, not on the first delivery.
+      orderAudit: () => OkAsync(undefined),
+    }),
+  },
+);
+
+const Worker = AmqpModule("Worker")({
+  needs: [Env],
+  contract: orderContract,
+  handlers: orderHandlers,
+  imports: [AppModule],
+});
+
+await runMain(Worker);
+```
+
+`AmqpModule` imports the starter — `AmqpRuntime`, `AmqpConfig` bound from
+`AMQP_URL` (default `amqp://127.0.0.1:5672`) — provides the handlers and
+exports the runtime port; the handlers are checked against the contract at the
+call, not on the first delivery. `runtimeInfo()` reads `{ queues }` back once
+consuming.
+
+A worker with several consumers can be several slices instead of one record:
+`AmqpHandler(contract, key)({ name: Dep }, arm)` mints a provider for ONE consumer or
+rpc, typed by the key alone, and `AmqpHandlers(contract)([...])` composes an
+array of them into the same handlers provider `AmqpModule` takes — the array
+must cover every key the contract declares, and each piece's own port must
+still be discharged (`provides`), since the composed provider's deps are the
+pieces' ports, not what they close over. Two slices claiming one key are di's
+duplicate-provider defect at build, which is the point: a consumer belongs to
+exactly one slice.
+
+## Options
+
+`AmqpModule(name)({...})` takes `amqp()`'s options plus `handlers` and the
+module lists (`imports`, `provides`, `exports`, `needs`). The `amqp()`
+primitive does not take `handlers` as an option — it **needs** the handlers
+provider on its own port, which is how the composition root supplies it:
+
+| Option                   | What it is                                                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `contract`               | the `amqp-contract` contract; the queues consumed are read off it                                               |
+| `handlers`               | the handlers provider — what `AmqpHandlers(contract)(...)` returns for this contract                            |
+| `url`                    | pins the broker instead of reading `AMQP_URL` (default `amqp://127.0.0.1:5672`) — a test's container            |
+| `connectionOptions`      | `AmqpConnectionOptions`, the library's own connection tuning: heartbeat, reconnect interval, `findServers`, TLS |
+| `defaultConsumerOptions` | the library's `ConsumerOptions`, applied to every handler: `prefetch` (the throughput knob), `priority`, …      |
+| `connectTimeoutMs`       | how long startup waits before an unreachable broker is a `RuntimeStartFailed` (the library defaults to 30 s)    |
+
+The full table — required/optional, defaults, and the reasoning — lives on
+[the reference page](https://btravstack.github.io/btravstack/reference/amqp-worker),
+which is this list's one detailed home.
+
+## What it decides, and what it does not
+
+`Result` → ack / retry / dead-letter is a **three-way** split and none of it is
+this package's: a `RetryableError` / `NonRetryableError` is routed by
+`amqp-contract`'s own dispatch against the queue's `retry` config, and a
+`Defect` is nacked once, straight to the dead-letter queue, never touching that
+budget — which is why the handler above recovers its own defects into a
+`RetryableError`. The drain calls `worker.close({ drainTimeoutMs: null })`
+raced against the kernel's deadline: the library is told to wait forever, so
+there is no second timeout in the process to keep in step. Each delivery is one
+unit, `traceId` the publisher's `messageId`. The rest is on the
+[documentation site](https://btravstack.github.io/btravstack/reference/amqp-worker).
+
+## License
+
+[MIT](./LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -0,0 +1,215 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_di = require("@btravstack/di");
+let _amqp_contract_worker = require("@amqp-contract/worker");
+let _btravstack_config = require("@btravstack/config");
+let _btravstack_core = require("@btravstack/core");
+let unthrown = require("unthrown");
+let node_crypto = require("node:crypto");
+//#region src/handler.ts
+/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
+const HANDLER_PREFIX = "AmqpHandler:";
+/**
+* One consumer or rpc of a contract, as a provider on a port of its own.
+*
+* A worker with several consumers is several pieces, each declaring the services
+* its own handler calls; `AmqpHandlers(contract)([...])` composes them.
+* `contract` is read for its TYPE only, and types both `key` and the handler —
+* so a consumer the contract does not declare is a compile error here.
+*
+* There is no name to give: the contract key IS the port's name.
+*/
+const AmqpHandler = (contract, key) => {
+	const port = class extends (0, _btravstack_di.Port)(`${HANDLER_PREFIX}${key}`) {};
+	return (0, _btravstack_di.Provider)(port);
+};
+//#endregion
+//#region src/message-units.ts
+/**
+* Open one kernel unit per delivery. It injects nothing — `next()` unchanged is
+* the whole of the chain — so the ambient `currentUnit()` record is what the
+* unit leaves for the adapters that read it.
+*
+* **The kernel's per-unit `AbortSignal` rides that record too**, and it is the
+* only route to it here: a handler has no parameter to receive one through. A
+* handler that must stop when the kernel stops waiting reads
+* `currentUnit()?.signal`.
+*/
+const messageUnits = (host) => (args, next) => host.run(metaFor(args.rawMessage), () => next());
+/**
+* `UnitMeta.id` must be unique per unit, and a **delivery tag is not one**: tags
+* are per-channel and restart at `1` after a reconnect, which
+* amqp-connection-manager performs silently underneath this worker.
+* `consumerTag + deliveryTag` almost fixes it, until `ConsumerOptions` lets a
+* caller pin `consumerTag`. Minting is the only form the rule survives.
+*
+* A W3C `traceparent` header wins when the publisher sends one; otherwise
+* `messageId`, with `correlationId` as the RPC-shaped fallback.
+*
+* Only a NON-BLANK id is adopted, and the trim is load-bearing: `??` guards
+* nullish alone, so a publisher setting `messageId: ""` would give every
+* delivery the same blank trace id.
+*/
+const metaFor = (raw) => {
+	const id = (0, node_crypto.randomUUID)();
+	const parent = raw.properties.headers?.["traceparent"];
+	const fromParent = typeof parent === "string" ? traceIdOfTraceparent(parent) : void 0;
+	const inbound = [raw.properties.messageId, raw.properties.correlationId].map((value) => value?.trim() ?? "").find((value) => value !== "");
+	return {
+		kind: "delivery",
+		id,
+		traceId: fromParent ?? inbound ?? id
+	};
+};
+/**
+* The trace id inside a W3C `traceparent` header, which outranks `messageId`
+* because it is the one value minted to span processes. Only the trace-id field
+* is taken: `traceId` is a correlation id, not a span context, so the parent's
+* span id is dropped rather than half-carried. The all-zero id is the spec's own
+* "invalid" and is refused like a malformed header.
+*/
+const traceIdOfTraceparent = (header) => {
+	const traceId = /^[\da-f]{2}-([\da-f]{32})-[\da-f]{16}-[\da-f]{2}$/.exec(header.trim())?.[1];
+	return traceId === void 0 || /^0{32}$/.test(traceId) ? void 0 : traceId;
+};
+//#endregion
+//#region src/amqp-runtime.ts
+/**
+* The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
+* `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
+* read it — a publisher sharing the consumer's broker, say.
+*/
+var AmqpConfig = class extends (0, _btravstack_di.Port)("AmqpConfig") {};
+/** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
+var AmqpRuntime = class extends _btravstack_core.RuntimePort {};
+/**
+* The handlers' port — one id, the starter's own, which an application never
+* names. Generic at the value level (one `Port(...)` call, so no duplicate-id
+* warning however many contracts instantiate it) and fixed per contract at the
+* type level through `HandlersPortOf<C>`, so a provider built for one contract
+* cannot be handed to a module declaring another. Exported for this package's
+* tests, not from `index.ts`.
+*/
+const AmqpHandlersPort = (0, _btravstack_di.Port)("AmqpHandlers");
+/**
+* The AMQP starter: a module providing the runtime and its configuration (bound
+* from `AMQP_URL` unless pinned), built over the handlers the application
+* provides on the starter's own handlers port — the module's one need. Import
+* it next to the application, provide the handlers, export `AmqpRuntime`.
+*
+* With `url` pinned the module reads nothing from the environment.
+*/
+const amqp = (options) => {
+	const config = options.url === void 0 ? _btravstack_config.Config.provider(AmqpConfig)(_btravstack_config.Config.object({ url: _btravstack_config.Config.string("AMQP_URL", { default: "amqp://127.0.0.1:5672" }) })) : (0, _btravstack_di.Provider)(AmqpConfig)({ value: { url: options.url } });
+	return (0, _btravstack_di.Module)("Amqp")({
+		needs: [_btravstack_config.Env, AmqpHandlersPort],
+		provides: [config, (0, _btravstack_di.Provider)(AmqpRuntime)({
+			config: AmqpConfig,
+			handlers: AmqpHandlersPort
+		}, { sync: ({ config: bound, handlers }) => ({
+			name: "amqp",
+			resolves: [],
+			start: (host) => createWorker(host, bound, options, handlers)
+		}) })],
+		exports: [AmqpRuntime, AmqpConfig]
+	});
+};
+/**
+* The handlers as a provider, from the contract. Three call forms, one port.
+*
+* ```ts
+* AmqpHandlers(orderContract)({ logger: Logger }, { sync: ({ logger }) => ({ orderNotifications: (m) => … }) })
+* AmqpHandlers(orderContract)([orderNotifications, orderAudit])
+* ```
+*
+* The first two are di's own `Provider(port)` on the starter's handlers port
+* typed for the contract. The third takes the pieces `AmqpHandler(contract,
+* key)` builds: they are the provider's deps, keyed by the contract key each
+* piece's port id carries, so the services record IS the handlers record. Every
+* declared key must be covered, and two slices claiming one key are di's
+* duplicate-provider defect at build.
+*/
+const AmqpHandlers = (contract) => {
+	const build = (0, _btravstack_di.Provider)(AmqpHandlersPort);
+	const compose = (pieces) => build(Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(12), piece.port])), { sync: (services) => services });
+	return ((first, second) => second === void 0 && Array.isArray(first) ? compose(first) : build(first, second));
+};
+const startFailed = (cause) => new _btravstack_core.RuntimeStartFailed({
+	runtime: "amqp",
+	cause
+});
+/**
+* Every queue the contract's consumers and RPCs drain, sorted and
+* de-duplicated. Derived rather than configured, so `Serving.info` cannot
+* disagree with what the worker actually consumes.
+*/
+const queuesOf = (contract) => [...new Set(Object.values({
+	...contract.consumers,
+	...contract.rpcs
+}).map((entry) => entry.queue.name))].sort();
+const createWorker = (host, config, options, handlers) => _amqp_contract_worker.TypedAmqpWorker.create({
+	contract: options.contract,
+	handlers,
+	middleware: messageUnits(host),
+	urls: [config.url],
+	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
+	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
+	...options.connectTimeoutMs === void 0 ? {} : { connectTimeoutMs: options.connectTimeoutMs }
+}).map((worker) => consume(worker, queuesOf(options.contract))).recoverDefect((cause) => (0, unthrown.ErrAsync)(startFailed(cause)));
+const consume = (worker, queues) => {
+	let closing;
+	const beginClose = () => closing ??= worker.close({ drainTimeoutMs: null });
+	let deadline;
+	const stopped = () => deadline === void 0 ? beginClose() : (0, _btravstack_core.releasedBy)(deadline, beginClose());
+	return {
+		info: { queues },
+		drain: (signal) => {
+			deadline = signal;
+			return stopped();
+		},
+		stop: () => stopped()
+	};
+};
+//#endregion
+//#region src/amqp-module.ts
+/**
+* `Module(name)({...})` for an AMQP deployment: everything a di module takes,
+* plus the contract and the handlers provider. The sugar imports the starter,
+* provides the handlers and exports `AmqpRuntime`, handing back exactly the
+* module `Module(...)` would have declared over the augmented tuples.
+*
+* ```ts
+* export const OrderAmqpWorker = AmqpModule("OrderAmqpWorker")({
+*   contract: orderContract,
+*   handlers: orderHandlers,
+*   imports: [OrderApplicationModule, OrderPersistenceModule],
+*   exports: [Logger],
+* });
+* await runMain(OrderAmqpWorker);
+* ```
+*/
+const AmqpModule = (name) => (options) => {
+	const { contract, handlers, url, connectionOptions, defaultConsumerOptions, connectTimeoutMs } = options;
+	const imports = options.imports ?? [];
+	const provides = options.provides ?? [];
+	const exports = options.exports ?? [];
+	const starter = amqp({
+		contract,
+		...url === void 0 ? {} : { url },
+		...connectionOptions === void 0 ? {} : { connectionOptions },
+		...defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions },
+		...connectTimeoutMs === void 0 ? {} : { connectTimeoutMs }
+	});
+	return (0, _btravstack_di.Module)(name)({
+		imports: [...imports, starter],
+		provides: [handlers, ...provides],
+		exports: [AmqpRuntime, ...exports],
+		needs: options.needs ?? []
+	});
+};
+//#endregion
+exports.AmqpConfig = AmqpConfig;
+exports.AmqpHandler = AmqpHandler;
+exports.AmqpHandlers = AmqpHandlers;
+exports.AmqpModule = AmqpModule;
+exports.AmqpRuntime = AmqpRuntime;
+exports.amqp = amqp;

package/dist/index.d.cts

@@ -0,0 +1,178 @@
+import { ConsumerOptions, TypedAmqpWorker, WorkerInferHandlers } from "@amqp-contract/worker";
+import { ConfigInvalid, Env } from "@btravstack/config";
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider } from "@btravstack/di";
+import { Runtime, RuntimePort } from "@btravstack/core";
+//#region src/handler.d.ts
+/** The consumer and rpc names `C` declares — the keys of its handlers record. */
+type HandlerKeyOf<C extends AnyAmqpContract> = keyof WorkerInferHandlers<C> & string;
+/**
+ * The port one piece targets. Its id carries the contract key, which is what
+ * makes two slices claiming one consumer di's duplicate-provider defect rather
+ * than a silent merge.
+ */
+type HandlerPortOf<C extends AnyAmqpContract, K extends HandlerKeyOf<C>> = PortClassOf<`${typeof HANDLER_PREFIX}${K}`, WorkerInferHandlers<C>[K]>;
+/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
+declare const HANDLER_PREFIX = "AmqpHandler:";
+/**
+ * One consumer or rpc of a contract, as a provider on a port of its own.
+ *
+ * A worker with several consumers is several pieces, each declaring the services
+ * its own handler calls; `AmqpHandlers(contract)([...])` composes them.
+ * `contract` is read for its TYPE only, and types both `key` and the handler —
+ * so a consumer the contract does not declare is a compile error here.
+ *
+ * There is no name to give: the contract key IS the port's name.
+ */
+declare const AmqpHandler: <C extends AnyAmqpContract, const K extends HandlerKeyOf<C>>(contract: C, key: K) => ReturnType<typeof Provider<HandlerPortOf<C, K>>>;
+//#endregion
+//#region src/amqp-runtime.d.ts
+/** What the worker publishes once it is consuming, read back through `RunningApp.runtimeInfo()`. */
+type AmqpInfo = {
+  readonly queues: readonly string[];
+};
+declare const AmqpConfig_base: import("@btravstack/di").PortClass<"AmqpConfig">;
+/**
+ * The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
+ * `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
+ * read it — a publisher sharing the consumer's broker, say.
+ */
+declare class AmqpConfig extends AmqpConfig_base<{
+  readonly url: string;
+}> {}
+/** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
+declare class AmqpRuntime extends RuntimePort<Runtime<never, AmqpInfo>> {}
+/**
+ * The contract type `TypedAmqpWorker.create` accepts, extracted rather than
+ * imported by name so `@amqp-contract/contract` stays out of the peer range.
+ */
+type AnyAmqpContract = Parameters<typeof TypedAmqpWorker.create>[0]["contract"];
+/**
+ * The connection tuning `TypedAmqpWorker.create` accepts — heartbeat,
+ * reconnect interval, `findServers`, TLS/socket options. The library declares
+ * it (`AmqpConnectionManagerOptions`) without exporting it by name, so it is
+ * reached by index for the same reason {@link AnyAmqpContract} is.
+ */
+type AmqpConnectionOptions = NonNullable<Parameters<typeof TypedAmqpWorker.create>[0]["connectionOptions"]>;
+/** The handlers port class, typed for `C`: what `AmqpHandlers(contract)(…).port` is. */
+type HandlersPortOf<C extends AnyAmqpContract> = PortClassOf<"AmqpHandlers", WorkerInferHandlers<C>>;
+/** The handlers port's instance for `C` — the module's one need. */
+type HandlersInstanceOf<C extends AnyAmqpContract> = PortInstance<"AmqpHandlers", WorkerInferHandlers<C>>;
+type AmqpOptions<TContract extends AnyAmqpContract> = {
+  /**
+   * The contract; the handlers port is typed by it — one handler per
+   * `consumers` / `rpcs` key, with no injected context, since a handler is
+   * built by di from the services it declares.
+   */
+  readonly contract: TContract;
+  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
+  readonly url?: string;
+  /** Connection tuning, `@amqp-contract/worker`'s own type: heartbeat, reconnect interval, `findServers`, TLS/socket options. */
+  readonly connectionOptions?: AmqpConnectionOptions;
+  /** Consumer defaults applied to every handler, the library's own type: `prefetch`, `priority`, `arguments`, `consumerTag`, `exclusive`. */
+  readonly defaultConsumerOptions?: ConsumerOptions;
+  /**
+   * How long `create` waits for the connection before failing. Passed straight
+   * through — it is a top-level `CreateWorkerOptions` field, NOT nested under
+   * `connectionOptions`, where setting it is silently inert. Without it an
+   * unreachable broker takes the library's 30s default to report.
+   */
+  readonly connectTimeoutMs?: number;
+};
+/**
+ * The AMQP starter: a module providing the runtime and its configuration (bound
+ * from `AMQP_URL` unless pinned), built over the handlers the application
+ * provides on the starter's own handlers port — the module's one need. Import
+ * it next to the application, provide the handlers, export `AmqpRuntime`.
+ *
+ * With `url` pinned the module reads nothing from the environment.
+ */
+declare const amqp: <TContract extends AnyAmqpContract>(options: AmqpOptions<TContract>) => Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract>>;
+/** One piece of the handlers record — what `AmqpHandler(contract, key)(…)` returns, as the composing form consumes it. */
+type PieceOf<C extends AnyAmqpContract> = { readonly [K in HandlerKeyOf<C>]: {
+  readonly port: HandlerPortOf<C, K>;
+}; }[HandlerKeyOf<C>];
+/** The key a piece carries, read back off its port id. */
+type KeyOfPiece<P> = P extends {
+  readonly port: {
+    readonly portId: `${typeof HANDLER_PREFIX}${infer K}`;
+  };
+} ? K : never;
+/** The consumers and rpcs no piece in `T` covers. */
+type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exclude<HandlerKeyOf<C>, KeyOfPiece<T[number]>>;
+/**
+ * The composing arm. Declared LAST in the intersection below on purpose:
+ * TypeScript reports the last overload's failure, so a non-covering array is
+ * refused against the `"UNCOVERED HANDLERS — …"` marker rather than degrading
+ * to di's `Qualification`, which names nothing.
+ *
+ * The marker is a sentence rather than a bare label because it prints last,
+ * after the caller's own several-hundred-character piece type.
+ */
+type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : readonly ["UNCOVERED HANDLERS — the contract declares a consumer this array does not cover", Uncovered<C, T>]) => Provider<HandlersInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
+  readonly port: HandlersPortOf<C>;
+};
+/**
+ * The handlers as a provider, from the contract. Three call forms, one port.
+ *
+ * ```ts
+ * AmqpHandlers(orderContract)({ logger: Logger }, { sync: ({ logger }) => ({ orderNotifications: (m) => … }) })
+ * AmqpHandlers(orderContract)([orderNotifications, orderAudit])
+ * ```
+ *
+ * The first two are di's own `Provider(port)` on the starter's handlers port
+ * typed for the contract. The third takes the pieces `AmqpHandler(contract,
+ * key)` builds: they are the provider's deps, keyed by the contract key each
+ * piece's port id carries, so the services record IS the handlers record. Every
+ * declared key must be covered, and two slices claiming one key are di's
+ * duplicate-provider defect at build.
+ */
+declare const AmqpHandlers: <C extends AnyAmqpContract>(contract: C) => ReturnType<typeof Provider<HandlersPortOf<C>>> & Compose<C>;
+//#endregion
+//#region src/amqp-module.d.ts
+/** The starter's own module, as the sugar adds it to the application's imports. */
+type AmqpStarter<TContract extends AnyAmqpContract> = Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract>>;
+/** The application's imports plus the starter — the tuple `Module(name)` is handed. */
+type Imports<I extends readonly AnyModule[], TContract extends AnyAmqpContract> = readonly [...I, AmqpStarter<TContract>];
+/** The handlers provider plus the application's own — the tuple `Module(name)` is handed. */
+type Provides<P extends readonly AnyProvider[], TContract extends AnyAmqpContract, HandlersError, HandlersNeeds> = readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P];
+type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = {
+  readonly contract: TContract;
+  /** The application's handlers — what `AmqpHandlers(contract)(…)` returns for THIS contract. */
+  readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>;
+  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
+  readonly url?: string;
+  /** See `AmqpOptions.connectionOptions`. */
+  readonly connectionOptions?: AmqpConnectionOptions;
+  /** See `AmqpOptions.defaultConsumerOptions`. */
+  readonly defaultConsumerOptions?: ConsumerOptions;
+  /** See `AmqpOptions.connectTimeoutMs`. */
+  readonly connectTimeoutMs?: number;
+  readonly imports?: I;
+  readonly provides?: P;
+  /** The application's own exports; `AmqpRuntime` is added, since `start` resolves it. */
+  readonly exports?: X;
+  /**
+   * What this root's OWN providers expect from outside. di's gate is re-stated
+   * over the augmented tuples below, so forgetting one is an error at THIS call.
+   */
+  readonly needs?: N;
+} & NeedsGate<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>, N>;
+/**
+ * `Module(name)({...})` for an AMQP deployment: everything a di module takes,
+ * plus the contract and the handlers provider. The sugar imports the starter,
+ * provides the handlers and exports `AmqpRuntime`, handing back exactly the
+ * module `Module(...)` would have declared over the augmented tuples.
+ *
+ * ```ts
+ * export const OrderAmqpWorker = AmqpModule("OrderAmqpWorker")({
+ *   contract: orderContract,
+ *   handlers: orderHandlers,
+ *   imports: [OrderApplicationModule, OrderPersistenceModule],
+ *   exports: [Logger],
+ * });
+ * await runMain(OrderAmqpWorker);
+ * ```
+ */
+declare const AmqpModule: <const Name extends string>(name: Name) => <TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[] = [], const N extends readonly AnyPort[] = []>(options: AmqpModuleOptions<TContract, HandlersError, HandlersNeeds, I, P, X, N>) => Module<(Extract<(readonly [typeof AmqpRuntime, ...X])[number], AnyModule> extends (infer T) ? T extends Extract<(readonly [typeof AmqpRuntime, ...X])[number], AnyModule> ? T extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[0] | ((readonly [typeof AmqpRuntime, ...X])[number] extends (infer E_1) ? E_1 extends AnyPort ? InstanceType<E_1> : E_1 extends AnyProvider ? InstanceType<E_1["port"]> : never : never), ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[1] | ((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_2) ? T_2 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_2 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[1], Exclude<((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_4 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]> | Exclude<((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_4 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_4 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]>>;
+//#endregion
+export { AmqpConfig, type AmqpConnectionOptions, AmqpHandler, AmqpHandlers, type AmqpInfo, AmqpModule, type AmqpModuleOptions, type AmqpOptions, AmqpRuntime, type HandlerPortOf, type HandlersInstanceOf, type HandlersPortOf, amqp };

package/dist/index.d.mts

@@ -0,0 +1,178 @@
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider } from "@btravstack/di";
+import { ConsumerOptions, TypedAmqpWorker, WorkerInferHandlers } from "@amqp-contract/worker";
+import { ConfigInvalid, Env } from "@btravstack/config";
+import { Runtime, RuntimePort } from "@btravstack/core";
+//#region src/handler.d.ts
+/** The consumer and rpc names `C` declares — the keys of its handlers record. */
+type HandlerKeyOf<C extends AnyAmqpContract> = keyof WorkerInferHandlers<C> & string;
+/**
+ * The port one piece targets. Its id carries the contract key, which is what
+ * makes two slices claiming one consumer di's duplicate-provider defect rather
+ * than a silent merge.
+ */
+type HandlerPortOf<C extends AnyAmqpContract, K extends HandlerKeyOf<C>> = PortClassOf<`${typeof HANDLER_PREFIX}${K}`, WorkerInferHandlers<C>[K]>;
+/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
+declare const HANDLER_PREFIX = "AmqpHandler:";
+/**
+ * One consumer or rpc of a contract, as a provider on a port of its own.
+ *
+ * A worker with several consumers is several pieces, each declaring the services
+ * its own handler calls; `AmqpHandlers(contract)([...])` composes them.
+ * `contract` is read for its TYPE only, and types both `key` and the handler —
+ * so a consumer the contract does not declare is a compile error here.
+ *
+ * There is no name to give: the contract key IS the port's name.
+ */
+declare const AmqpHandler: <C extends AnyAmqpContract, const K extends HandlerKeyOf<C>>(contract: C, key: K) => ReturnType<typeof Provider<HandlerPortOf<C, K>>>;
+//#endregion
+//#region src/amqp-runtime.d.ts
+/** What the worker publishes once it is consuming, read back through `RunningApp.runtimeInfo()`. */
+type AmqpInfo = {
+  readonly queues: readonly string[];
+};
+declare const AmqpConfig_base: import("@btravstack/di").PortClass<"AmqpConfig">;
+/**
+ * The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
+ * `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
+ * read it — a publisher sharing the consumer's broker, say.
+ */
+declare class AmqpConfig extends AmqpConfig_base<{
+  readonly url: string;
+}> {}
+/** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
+declare class AmqpRuntime extends RuntimePort<Runtime<never, AmqpInfo>> {}
+/**
+ * The contract type `TypedAmqpWorker.create` accepts, extracted rather than
+ * imported by name so `@amqp-contract/contract` stays out of the peer range.
+ */
+type AnyAmqpContract = Parameters<typeof TypedAmqpWorker.create>[0]["contract"];
+/**
+ * The connection tuning `TypedAmqpWorker.create` accepts — heartbeat,
+ * reconnect interval, `findServers`, TLS/socket options. The library declares
+ * it (`AmqpConnectionManagerOptions`) without exporting it by name, so it is
+ * reached by index for the same reason {@link AnyAmqpContract} is.
+ */
+type AmqpConnectionOptions = NonNullable<Parameters<typeof TypedAmqpWorker.create>[0]["connectionOptions"]>;
+/** The handlers port class, typed for `C`: what `AmqpHandlers(contract)(…).port` is. */
+type HandlersPortOf<C extends AnyAmqpContract> = PortClassOf<"AmqpHandlers", WorkerInferHandlers<C>>;
+/** The handlers port's instance for `C` — the module's one need. */
+type HandlersInstanceOf<C extends AnyAmqpContract> = PortInstance<"AmqpHandlers", WorkerInferHandlers<C>>;
+type AmqpOptions<TContract extends AnyAmqpContract> = {
+  /**
+   * The contract; the handlers port is typed by it — one handler per
+   * `consumers` / `rpcs` key, with no injected context, since a handler is
+   * built by di from the services it declares.
+   */
+  readonly contract: TContract;
+  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
+  readonly url?: string;
+  /** Connection tuning, `@amqp-contract/worker`'s own type: heartbeat, reconnect interval, `findServers`, TLS/socket options. */
+  readonly connectionOptions?: AmqpConnectionOptions;
+  /** Consumer defaults applied to every handler, the library's own type: `prefetch`, `priority`, `arguments`, `consumerTag`, `exclusive`. */
+  readonly defaultConsumerOptions?: ConsumerOptions;
+  /**
+   * How long `create` waits for the connection before failing. Passed straight
+   * through — it is a top-level `CreateWorkerOptions` field, NOT nested under
+   * `connectionOptions`, where setting it is silently inert. Without it an
+   * unreachable broker takes the library's 30s default to report.
+   */
+  readonly connectTimeoutMs?: number;
+};
+/**
+ * The AMQP starter: a module providing the runtime and its configuration (bound
+ * from `AMQP_URL` unless pinned), built over the handlers the application
+ * provides on the starter's own handlers port — the module's one need. Import
+ * it next to the application, provide the handlers, export `AmqpRuntime`.
+ *
+ * With `url` pinned the module reads nothing from the environment.
+ */
+declare const amqp: <TContract extends AnyAmqpContract>(options: AmqpOptions<TContract>) => Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract>>;
+/** One piece of the handlers record — what `AmqpHandler(contract, key)(…)` returns, as the composing form consumes it. */
+type PieceOf<C extends AnyAmqpContract> = { readonly [K in HandlerKeyOf<C>]: {
+  readonly port: HandlerPortOf<C, K>;
+}; }[HandlerKeyOf<C>];
+/** The key a piece carries, read back off its port id. */
+type KeyOfPiece<P> = P extends {
+  readonly port: {
+    readonly portId: `${typeof HANDLER_PREFIX}${infer K}`;
+  };
+} ? K : never;
+/** The consumers and rpcs no piece in `T` covers. */
+type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exclude<HandlerKeyOf<C>, KeyOfPiece<T[number]>>;
+/**
+ * The composing arm. Declared LAST in the intersection below on purpose:
+ * TypeScript reports the last overload's failure, so a non-covering array is
+ * refused against the `"UNCOVERED HANDLERS — …"` marker rather than degrading
+ * to di's `Qualification`, which names nothing.
+ *
+ * The marker is a sentence rather than a bare label because it prints last,
+ * after the caller's own several-hundred-character piece type.
+ */
+type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : readonly ["UNCOVERED HANDLERS — the contract declares a consumer this array does not cover", Uncovered<C, T>]) => Provider<HandlersInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
+  readonly port: HandlersPortOf<C>;
+};
+/**
+ * The handlers as a provider, from the contract. Three call forms, one port.
+ *
+ * ```ts
+ * AmqpHandlers(orderContract)({ logger: Logger }, { sync: ({ logger }) => ({ orderNotifications: (m) => … }) })
+ * AmqpHandlers(orderContract)([orderNotifications, orderAudit])
+ * ```
+ *
+ * The first two are di's own `Provider(port)` on the starter's handlers port
+ * typed for the contract. The third takes the pieces `AmqpHandler(contract,
+ * key)` builds: they are the provider's deps, keyed by the contract key each
+ * piece's port id carries, so the services record IS the handlers record. Every
+ * declared key must be covered, and two slices claiming one key are di's
+ * duplicate-provider defect at build.
+ */
+declare const AmqpHandlers: <C extends AnyAmqpContract>(contract: C) => ReturnType<typeof Provider<HandlersPortOf<C>>> & Compose<C>;
+//#endregion
+//#region src/amqp-module.d.ts
+/** The starter's own module, as the sugar adds it to the application's imports. */
+type AmqpStarter<TContract extends AnyAmqpContract> = Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract>>;
+/** The application's imports plus the starter — the tuple `Module(name)` is handed. */
+type Imports<I extends readonly AnyModule[], TContract extends AnyAmqpContract> = readonly [...I, AmqpStarter<TContract>];
+/** The handlers provider plus the application's own — the tuple `Module(name)` is handed. */
+type Provides<P extends readonly AnyProvider[], TContract extends AnyAmqpContract, HandlersError, HandlersNeeds> = readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P];
+type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = {
+  readonly contract: TContract;
+  /** The application's handlers — what `AmqpHandlers(contract)(…)` returns for THIS contract. */
+  readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>;
+  /** Pins the broker instead of reading `AMQP_URL` — a test's container. */
+  readonly url?: string;
+  /** See `AmqpOptions.connectionOptions`. */
+  readonly connectionOptions?: AmqpConnectionOptions;
+  /** See `AmqpOptions.defaultConsumerOptions`. */
+  readonly defaultConsumerOptions?: ConsumerOptions;
+  /** See `AmqpOptions.connectTimeoutMs`. */
+  readonly connectTimeoutMs?: number;
+  readonly imports?: I;
+  readonly provides?: P;
+  /** The application's own exports; `AmqpRuntime` is added, since `start` resolves it. */
+  readonly exports?: X;
+  /**
+   * What this root's OWN providers expect from outside. di's gate is re-stated
+   * over the augmented tuples below, so forgetting one is an error at THIS call.
+   */
+  readonly needs?: N;
+} & NeedsGate<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>, N>;
+/**
+ * `Module(name)({...})` for an AMQP deployment: everything a di module takes,
+ * plus the contract and the handlers provider. The sugar imports the starter,
+ * provides the handlers and exports `AmqpRuntime`, handing back exactly the
+ * module `Module(...)` would have declared over the augmented tuples.
+ *
+ * ```ts
+ * export const OrderAmqpWorker = AmqpModule("OrderAmqpWorker")({
+ *   contract: orderContract,
+ *   handlers: orderHandlers,
+ *   imports: [OrderApplicationModule, OrderPersistenceModule],
+ *   exports: [Logger],
+ * });
+ * await runMain(OrderAmqpWorker);
+ * ```
+ */
+declare const AmqpModule: <const Name extends string>(name: Name) => <TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, TContract>, Provides<P, TContract, HandlersError, HandlersNeeds>>[] = [], const N extends readonly AnyPort[] = []>(options: AmqpModuleOptions<TContract, HandlersError, HandlersNeeds, I, P, X, N>) => Module<(Extract<(readonly [typeof AmqpRuntime, ...X])[number], AnyModule> extends (infer T) ? T extends Extract<(readonly [typeof AmqpRuntime, ...X])[number], AnyModule> ? T extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[0] | ((readonly [typeof AmqpRuntime, ...X])[number] extends (infer E_1) ? E_1 extends AnyPort ? InstanceType<E_1> : E_1 extends AnyProvider ? InstanceType<E_1["port"]> : never : never), ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_1 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[1] | ((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_2) ? T_2 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_2 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[1], Exclude<((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_4 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]> | Exclude<((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_4 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[2], ((readonly [...I, AmqpStarter<TContract>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract>])[number] ? T_4 extends Module<infer X_1, infer E, infer N_1> ? readonly [X_1, E, N_1] : never : never : never)[0] | ((readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>, ...P])[number] ? T_3 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]>>;
+//#endregion
+export { AmqpConfig, type AmqpConnectionOptions, AmqpHandler, AmqpHandlers, type AmqpInfo, AmqpModule, type AmqpModuleOptions, type AmqpOptions, AmqpRuntime, type HandlerPortOf, type HandlersInstanceOf, type HandlersPortOf, amqp };

package/dist/index.mjs

@@ -0,0 +1,209 @@
+import { Module, Port, Provider } from "@btravstack/di";
+import { TypedAmqpWorker } from "@amqp-contract/worker";
+import { Config, Env } from "@btravstack/config";
+import { RuntimePort, RuntimeStartFailed, releasedBy } from "@btravstack/core";
+import { ErrAsync } from "unthrown";
+import { randomUUID } from "node:crypto";
+//#region src/handler.ts
+/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
+const HANDLER_PREFIX = "AmqpHandler:";
+/**
+* One consumer or rpc of a contract, as a provider on a port of its own.
+*
+* A worker with several consumers is several pieces, each declaring the services
+* its own handler calls; `AmqpHandlers(contract)([...])` composes them.
+* `contract` is read for its TYPE only, and types both `key` and the handler —
+* so a consumer the contract does not declare is a compile error here.
+*
+* There is no name to give: the contract key IS the port's name.
+*/
+const AmqpHandler = (contract, key) => {
+	const port = class extends Port(`${HANDLER_PREFIX}${key}`) {};
+	return Provider(port);
+};
+//#endregion
+//#region src/message-units.ts
+/**
+* Open one kernel unit per delivery. It injects nothing — `next()` unchanged is
+* the whole of the chain — so the ambient `currentUnit()` record is what the
+* unit leaves for the adapters that read it.
+*
+* **The kernel's per-unit `AbortSignal` rides that record too**, and it is the
+* only route to it here: a handler has no parameter to receive one through. A
+* handler that must stop when the kernel stops waiting reads
+* `currentUnit()?.signal`.
+*/
+const messageUnits = (host) => (args, next) => host.run(metaFor(args.rawMessage), () => next());
+/**
+* `UnitMeta.id` must be unique per unit, and a **delivery tag is not one**: tags
+* are per-channel and restart at `1` after a reconnect, which
+* amqp-connection-manager performs silently underneath this worker.
+* `consumerTag + deliveryTag` almost fixes it, until `ConsumerOptions` lets a
+* caller pin `consumerTag`. Minting is the only form the rule survives.
+*
+* A W3C `traceparent` header wins when the publisher sends one; otherwise
+* `messageId`, with `correlationId` as the RPC-shaped fallback.
+*
+* Only a NON-BLANK id is adopted, and the trim is load-bearing: `??` guards
+* nullish alone, so a publisher setting `messageId: ""` would give every
+* delivery the same blank trace id.
+*/
+const metaFor = (raw) => {
+	const id = randomUUID();
+	const parent = raw.properties.headers?.["traceparent"];
+	const fromParent = typeof parent === "string" ? traceIdOfTraceparent(parent) : void 0;
+	const inbound = [raw.properties.messageId, raw.properties.correlationId].map((value) => value?.trim() ?? "").find((value) => value !== "");
+	return {
+		kind: "delivery",
+		id,
+		traceId: fromParent ?? inbound ?? id
+	};
+};
+/**
+* The trace id inside a W3C `traceparent` header, which outranks `messageId`
+* because it is the one value minted to span processes. Only the trace-id field
+* is taken: `traceId` is a correlation id, not a span context, so the parent's
+* span id is dropped rather than half-carried. The all-zero id is the spec's own
+* "invalid" and is refused like a malformed header.
+*/
+const traceIdOfTraceparent = (header) => {
+	const traceId = /^[\da-f]{2}-([\da-f]{32})-[\da-f]{16}-[\da-f]{2}$/.exec(header.trim())?.[1];
+	return traceId === void 0 || /^0{32}$/.test(traceId) ? void 0 : traceId;
+};
+//#endregion
+//#region src/amqp-runtime.ts
+/**
+* The broker, as a service: `amqp()` binds it from `AMQP_URL` (default
+* `amqp://127.0.0.1:5672`) unless pinned, and anything else in the graph may
+* read it — a publisher sharing the consumer's broker, say.
+*/
+var AmqpConfig = class extends Port("AmqpConfig") {};
+/** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
+var AmqpRuntime = class extends RuntimePort {};
+/**
+* The handlers' port — one id, the starter's own, which an application never
+* names. Generic at the value level (one `Port(...)` call, so no duplicate-id
+* warning however many contracts instantiate it) and fixed per contract at the
+* type level through `HandlersPortOf<C>`, so a provider built for one contract
+* cannot be handed to a module declaring another. Exported for this package's
+* tests, not from `index.ts`.
+*/
+const AmqpHandlersPort = Port("AmqpHandlers");
+/**
+* The AMQP starter: a module providing the runtime and its configuration (bound
+* from `AMQP_URL` unless pinned), built over the handlers the application
+* provides on the starter's own handlers port — the module's one need. Import
+* it next to the application, provide the handlers, export `AmqpRuntime`.
+*
+* With `url` pinned the module reads nothing from the environment.
+*/
+const amqp = (options) => {
+	const config = options.url === void 0 ? Config.provider(AmqpConfig)(Config.object({ url: Config.string("AMQP_URL", { default: "amqp://127.0.0.1:5672" }) })) : Provider(AmqpConfig)({ value: { url: options.url } });
+	return Module("Amqp")({
+		needs: [Env, AmqpHandlersPort],
+		provides: [config, Provider(AmqpRuntime)({
+			config: AmqpConfig,
+			handlers: AmqpHandlersPort
+		}, { sync: ({ config: bound, handlers }) => ({
+			name: "amqp",
+			resolves: [],
+			start: (host) => createWorker(host, bound, options, handlers)
+		}) })],
+		exports: [AmqpRuntime, AmqpConfig]
+	});
+};
+/**
+* The handlers as a provider, from the contract. Three call forms, one port.
+*
+* ```ts
+* AmqpHandlers(orderContract)({ logger: Logger }, { sync: ({ logger }) => ({ orderNotifications: (m) => … }) })
+* AmqpHandlers(orderContract)([orderNotifications, orderAudit])
+* ```
+*
+* The first two are di's own `Provider(port)` on the starter's handlers port
+* typed for the contract. The third takes the pieces `AmqpHandler(contract,
+* key)` builds: they are the provider's deps, keyed by the contract key each
+* piece's port id carries, so the services record IS the handlers record. Every
+* declared key must be covered, and two slices claiming one key are di's
+* duplicate-provider defect at build.
+*/
+const AmqpHandlers = (contract) => {
+	const build = Provider(AmqpHandlersPort);
+	const compose = (pieces) => build(Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(12), piece.port])), { sync: (services) => services });
+	return ((first, second) => second === void 0 && Array.isArray(first) ? compose(first) : build(first, second));
+};
+const startFailed = (cause) => new RuntimeStartFailed({
+	runtime: "amqp",
+	cause
+});
+/**
+* Every queue the contract's consumers and RPCs drain, sorted and
+* de-duplicated. Derived rather than configured, so `Serving.info` cannot
+* disagree with what the worker actually consumes.
+*/
+const queuesOf = (contract) => [...new Set(Object.values({
+	...contract.consumers,
+	...contract.rpcs
+}).map((entry) => entry.queue.name))].sort();
+const createWorker = (host, config, options, handlers) => TypedAmqpWorker.create({
+	contract: options.contract,
+	handlers,
+	middleware: messageUnits(host),
+	urls: [config.url],
+	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
+	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
+	...options.connectTimeoutMs === void 0 ? {} : { connectTimeoutMs: options.connectTimeoutMs }
+}).map((worker) => consume(worker, queuesOf(options.contract))).recoverDefect((cause) => ErrAsync(startFailed(cause)));
+const consume = (worker, queues) => {
+	let closing;
+	const beginClose = () => closing ??= worker.close({ drainTimeoutMs: null });
+	let deadline;
+	const stopped = () => deadline === void 0 ? beginClose() : releasedBy(deadline, beginClose());
+	return {
+		info: { queues },
+		drain: (signal) => {
+			deadline = signal;
+			return stopped();
+		},
+		stop: () => stopped()
+	};
+};
+//#endregion
+//#region src/amqp-module.ts
+/**
+* `Module(name)({...})` for an AMQP deployment: everything a di module takes,
+* plus the contract and the handlers provider. The sugar imports the starter,
+* provides the handlers and exports `AmqpRuntime`, handing back exactly the
+* module `Module(...)` would have declared over the augmented tuples.
+*
+* ```ts
+* export const OrderAmqpWorker = AmqpModule("OrderAmqpWorker")({
+*   contract: orderContract,
+*   handlers: orderHandlers,
+*   imports: [OrderApplicationModule, OrderPersistenceModule],
+*   exports: [Logger],
+* });
+* await runMain(OrderAmqpWorker);
+* ```
+*/
+const AmqpModule = (name) => (options) => {
+	const { contract, handlers, url, connectionOptions, defaultConsumerOptions, connectTimeoutMs } = options;
+	const imports = options.imports ?? [];
+	const provides = options.provides ?? [];
+	const exports = options.exports ?? [];
+	const starter = amqp({
+		contract,
+		...url === void 0 ? {} : { url },
+		...connectionOptions === void 0 ? {} : { connectionOptions },
+		...defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions },
+		...connectTimeoutMs === void 0 ? {} : { connectTimeoutMs }
+	});
+	return Module(name)({
+		imports: [...imports, starter],
+		provides: [handlers, ...provides],
+		exports: [AmqpRuntime, ...exports],
+		needs: options.needs ?? []
+	});
+};
+//#endregion
+export { AmqpConfig, AmqpHandler, AmqpHandlers, AmqpModule, AmqpRuntime, amqp };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@btravstack/amqp-worker",
+  "version": "0.3.0",
+  "description": "The AMQP starter for @btravstack/core: the handlers as a port, one unit per delivery, and a drain the kernel's deadline releases",
+  "keywords": [
+    "amqp",
+    "graceful-shutdown",
+    "lifecycle",
+    "rabbitmq",
+    "runtime",
+    "typescript",
+    "unthrown"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/amqp-worker"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@amqp-contract/contract": "3.0.0-beta.6",
+    "@amqp-contract/testing": "3.0.0-beta.6",
+    "@amqp-contract/worker": "3.0.0-beta.6",
+    "@btravstack/tsconfig": "0.2.0",
+    "@opentelemetry/api": "1.9.1",
+    "@types/node": "26.2.0",
+    "@unthrown/vitest": "5.7.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "unthrown": "5.7.0",
+    "vitest": "4.1.11",
+    "zod": "4.4.3",
+    "@btravstack/config": "0.3.0",
+    "@btravstack/core": "0.3.0",
+    "@btravstack/internal-test-infra": "0.0.0",
+    "@btravstack/testing": "0.3.0",
+    "@btravstack/di": "0.3.0"
+  },
+  "peerDependencies": {
+    "@amqp-contract/worker": "^3.0.0-beta.6",
+    "@opentelemetry/api": "^1",
+    "unthrown": "^5.0.0",
+    "@btravstack/config": "^0.3.0",
+    "@btravstack/core": "^0.3.0",
+    "@btravstack/di": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "test:types": "tsc --noEmit -p tsconfig.test-d.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
+  }
+}