@btravstack/amqp-worker 0.11.0 → 0.13.0

package/README.md

@@ -156,7 +156,7 @@ 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)({ inject: { name: Dep }, ...arm })` mints a provider for ONE consumer or
+`AmqpHandler(contract, key)({ inject: { name: Dep }, unit, sync })` 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
@@ -167,6 +167,16 @@ two slices claiming one key type-check together. It is di's duplicate-provider
 defect at build once **both** pieces are discharged as providers in one graph
 — wire in only one and the other's handler is silently never registered.
 
+A piece's `unit` names the ports its handler reads off `context.unit`, resolved
+out of the per-delivery fork of the module bound on `unit.message` — which is
+seeded with the validated message on `AmqpMessage(contract)`, so a unit module
+derives a tenant from the delivery rather than from an ambient record. The
+record arm above takes the same `unit:` — one record for every entry in it — so
+a worker that has not outgrown one function reaches `context.unit` without
+slicing first. The root is checked against what was declared either way: bind a
+module that does not export one of those ports and `AmqpModule` refuses it,
+naming the port.
+
 Its own test suite needs a **Docker daemon**: the specs run against the shared
 `rabbitmq` container `internal/test-infra` starts once per machine and every
 workspace reuses. Nothing else here does.
@@ -186,6 +196,7 @@ provider on its own port, which is how the composition root supplies it:
 | `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`       | pins `AMQP_CONNECT_TIMEOUT_MS` — how long startup waits before an unreachable broker is a `RuntimeStartFailed` (default `5000`) |
+| `unit`                   | `{ message }` — the module the worker forks per delivery, seeded with the message on `AmqpMessage(contract)`                    |
 
 The full table — required/optional, defaults, and the reasoning — lives on
 [the reference page](https://btravstack.github.io/btravstack/reference/amqp-worker),

package/dist/index.cjs

@@ -5,7 +5,73 @@ let _btravstack_config = require("@btravstack/config");
 let _btravstack_core = require("@btravstack/core");
 let unthrown = require("unthrown");
 let node_crypto = require("node:crypto");
+//#region src/unit.ts
+/**
+* Where `messageUnits` leaves the forked context for the piece wrappers to read.
+* A symbol rather than a name: the dispatcher merges it into the context every
+* handler sees, and a string key would appear on the record a handler written
+* against the `{ inject, sync }` arm destructures.
+*/
+const UNIT_SCOPE = Symbol("@btravstack/amqp-worker/unit-scope");
+/**
+* The declared record, as a getter per name resolved on read out of the fork.
+* Neither writable nor configurable — a handler reads what the fork holds, and
+* cannot reshape the record under the next delivery. With no `unit.message`
+* bound there is nothing to resolve from, so the record is empty whatever was
+* declared.
+*/
+const unitRecordOf = (forked, record) => {
+	const unit = {};
+	if (forked === void 0) return unit;
+	for (const [name, port] of Object.entries(record)) Object.defineProperty(unit, name, {
+		enumerable: true,
+		get: () => forked.get(port)
+	});
+	return unit;
+};
+/**
+* One handler entry — a function, or `[handler, options]` — with its piece's
+* declared record put on `context.unit`. Applied once per piece as di
+* constructs it, so a delivery costs one record and one context object.
+*/
+const withUnit = (record, entry) => {
+	const wrap = (handler) => (helpers, message) => {
+		const { [UNIT_SCOPE]: forked, ...rest } = helpers.context ?? {};
+		return handler({
+			...helpers,
+			context: {
+				...rest,
+				unit: unitRecordOf(forked, record)
+			}
+		}, message);
+	};
+	return Array.isArray(entry) ? [wrap(entry[0]), entry[1]] : wrap(entry);
+};
+//#endregion
 //#region src/handler.ts
+/** One id, declared once, so no contract instantiating it warns about a duplicate. */
+const AmqpMessagePort = (0, _btravstack_di.Port)("AmqpMessage");
+/**
+* The validated delivery as a port: the one thing the worker seeds the fork
+* with, so a `unit.message` module derives a tenant — or anything else — from
+* the message rather than from an ambient record.
+*
+* ```ts
+* const Message = AmqpMessage(orderContract);
+* const MessageUnit = Module("MessageUnit")({
+*   needs: [Message],
+*   provides: [Provider(Tenant)({ inject: { message: Message }, sync: ({ message }) => message.payload.tenantId })],
+*   exports: [Tenant],
+* });
+* ```
+*
+* `contract` is read for its TYPE only. One `Port(...)` call fixed per contract
+* at the type level, the move `AmqpHandlersPort` makes, so a module built for
+* one contract cannot read another's message.
+*/
+const AmqpMessage = (contract) => {
+	return AmqpMessagePort;
+};
 /** The prefix a piece's port id carries; the composing form strips it to recover the key. */
 const HANDLER_PREFIX = "AmqpHandler:";
 /**
@@ -17,30 +83,49 @@ const HANDLER_PREFIX = "AmqpHandler:";
 * 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.
+*
+* `unit` declares the ports the handler reads off `context.unit`, resolved out
+* of the fork the delivery opened; the root's `unit.message` module must export
+* every one of them.
 */
 const AmqpHandler = (contract, key) => {
 	const port = class extends (0, _btravstack_di.Port)(`${HANDLER_PREFIX}${key}`) {};
-	return (0, _btravstack_di.Provider)(port);
+	return (options) => {
+		const record = options.unit ?? {};
+		return Object.assign((0, _btravstack_di.Provider)(port)({
+			inject: options.inject,
+			sync: (services) => withUnit(record, options.sync(services))
+		}), { unit: record });
+	};
 };
 //#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.
+* Open one kernel unit per delivery, forking `unit` — when one is bound — after
+* the message is validated, before the handler runs; the fork is torn down
+* when the unit closes. It is seeded with the validated delivery on
+* `AmqpMessage(contract)`, so a unit module derives a tenant from the message
+* rather than reading one off an ambient record. With no `unit` bound, `next()`
+* runs unchanged, so the ambient `currentUnit()` record is what the unit leaves
+* for the adapters that read it.
+*
+* The forked context rides the dispatcher's context under {@link UNIT_SCOPE},
+* where each piece's own wrapper turns it into the typed `context.unit` record
+* that piece declared — the records live with the pieces, so a hand-composed
+* `amqp()` gets them without threading a second option through the starter.
 *
 * **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, observers) => (args, next) => {
+const messageUnits = (host, observers, unit) => (args, next) => {
 	const settle = (0, _btravstack_core.observe)(observers, {
 		component: "amqp",
 		name: "delivery",
 		attributes: { handler: args.handlerName }
 	});
-	return host.run(metaFor(args.rawMessage), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+	return host.run(metaFor(args.rawMessage), (scope) => unit === void 0 ? next() : scope.fork(unit, [[AmqpMessagePort, args.message]]).flatMap((forked) => next({ context: { [UNIT_SCOPE]: forked } }))).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
 		outcome: "error",
 		cause: failure.tag === "Err" ? failure.error : failure.cause
 	}));
@@ -62,7 +147,7 @@ const messageUnits = (host, observers) => (args, next) => {
 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 fromParent = typeof parent === "string" ? (0, _btravstack_core.traceIdOfTraceparent)(parent) : void 0;
 	const inbound = [raw.properties.messageId, raw.properties.correlationId].map((value) => value?.trim() ?? "").find((value) => value !== "");
 	return {
 		kind: "delivery",
@@ -70,17 +155,6 @@ const metaFor = (raw) => {
 		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
 /**
@@ -155,12 +229,12 @@ const amqp = (options) => {
 * AmqpHandlers(orderContract)([orderNotifications, orderAudit])
 * ```
 *
-* The first is di's own `Provider(port)` on the starter's handlers port
-* typed for the contract. The second 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.
+* The first is `{ inject, unit?, sync }`, whose `sync` hands back the whole
+* handlers record — one `unit:` record for every entry in it. The second 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);
@@ -168,7 +242,14 @@ const AmqpHandlers = (contract) => {
 		inject: Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(12), piece.port])),
 		sync: (services) => services
 	});
-	return ((first) => Array.isArray(first) ? compose(first) : build(first));
+	const whole = (options) => {
+		const record = options.unit ?? {};
+		return build({
+			inject: options.inject,
+			sync: (services) => Object.fromEntries(Object.entries(options.sync(services)).map(([key, entry]) => [key, withUnit(record, entry)]))
+		});
+	};
+	return ((first) => Array.isArray(first) ? compose(first) : whole(first));
 };
 const startFailed = (cause) => new _btravstack_core.RuntimeStartFailed({
 	runtime: "amqp",
@@ -186,7 +267,7 @@ const queuesOf = (contract) => [...new Set(Object.values({
 const createWorker = (host, config, options, handlers, observers) => _amqp_contract_worker.TypedAmqpWorker.create({
 	contract: options.contract,
 	handlers,
-	middleware: messageUnits(host, observers),
+	middleware: messageUnits(host, observers, options.unit?.message),
 	urls: [config.url],
 	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
 	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
@@ -241,6 +322,7 @@ const AmqpModule = (name) => (options) => {
 exports.AmqpConfig = AmqpConfig;
 exports.AmqpHandler = AmqpHandler;
 exports.AmqpHandlers = AmqpHandlers;
+exports.AmqpMessage = AmqpMessage;
 exports.AmqpModule = AmqpModule;
 exports.AmqpRuntime = AmqpRuntime;
 exports.amqp = amqp;

package/dist/index.d.cts

@@ -1,10 +1,59 @@
 import { ConfigInvalid, Env } from "@btravstack/config";
-import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider } from "@btravstack/di";
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope, ServiceOf } from "@btravstack/di";
 import { ConsumerOptions, TypedAmqpWorker, WorkerInferHandlers } from "@amqp-contract/worker";
 import { Runtime, RuntimePort } from "@btravstack/core";
+//#region src/unit.d.ts
+/** What a bound unit module exports — the port instances a handler of that kind may read. */
+type UnitExportsOf<M> = M extends Module<infer X, never, unknown> ? X : never;
+/** The declared `unit:` record, as the services a handler reads off `context.unit`. */
+type UnitRecordOf<U extends Readonly<Record<string, AnyPort>>> = { readonly [N in keyof U]: ServiceOf<InstanceType<U[N]>>; };
+/**
+ * A piece injecting a port the bound `unit.message` module does not export.
+ * `unknown` when every declared port is covered — including the empty case, so
+ * a worker whose pieces declare no `unit:` is gated on nothing.
+ */
+type UnitGate<Unit, Declared> = [Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>] extends [never] ? unknown : {
+  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>;
+};
+//#endregion
 //#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 validated delivery, typed by the contract: the union of every consumer's
+ * and rpc's own consumed message. Reached through the handler's own second
+ * parameter, since `@amqp-contract/worker` exports
+ * `WorkerInferConsumedMessage` but not the `InferConsumerNames` constraint it
+ * takes — the same by-index route {@link AnyAmqpContract} travels.
+ */
+type AmqpMessageOf<C extends AnyAmqpContract> = Parameters<Extract<WorkerInferHandlers<C>[HandlerKeyOf<C>], (...args: never) => unknown>>[1];
+/** The seeded port's class, typed for `C`: what `AmqpMessage(contract)` answers. */
+type AmqpMessagePortOf<C extends AnyAmqpContract> = PortClassOf<"AmqpMessage", AmqpMessageOf<C>>;
+/**
+ * The seed's port instance, as it appears in a needs union — subtracted from
+ * what a bound `unit.message` module still owes, since the fork is what
+ * discharges it.
+ */
+type AmqpMessageInstance = PortInstance<"AmqpMessage", unknown>;
+/**
+ * The validated delivery as a port: the one thing the worker seeds the fork
+ * with, so a `unit.message` module derives a tenant — or anything else — from
+ * the message rather than from an ambient record.
+ *
+ * ```ts
+ * const Message = AmqpMessage(orderContract);
+ * const MessageUnit = Module("MessageUnit")({
+ *   needs: [Message],
+ *   provides: [Provider(Tenant)({ inject: { message: Message }, sync: ({ message }) => message.payload.tenantId })],
+ *   exports: [Tenant],
+ * });
+ * ```
+ *
+ * `contract` is read for its TYPE only. One `Port(...)` call fixed per contract
+ * at the type level, the move `AmqpHandlersPort` makes, so a module built for
+ * one contract cannot read another's message.
+ */
+declare const AmqpMessage: <C extends AnyAmqpContract>(contract: C) => AmqpMessagePortOf<C>;
 /**
  * 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
@@ -13,6 +62,14 @@ type HandlerKeyOf<C extends AnyAmqpContract> = keyof WorkerInferHandlers<C> & st
 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:";
+/** What a minted piece returns. */
+type MintedHandler<C extends AnyAmqpContract, K extends HandlerKeyOf<C>, N, U extends Readonly<Record<string, AnyPort>>> = Provider<InstanceType<HandlerPortOf<C, K>>, never, N> & {
+  readonly port: HandlerPortOf<C, K>;
+  /** The declared `unit:` record, which `AmqpHandlers`'s array arm reads back off the piece. */
+  readonly unit: U;
+  /** Phantom: the ports this piece injects, which the root's `unit.message` must export. */
+  readonly _declared?: InstanceType<U[keyof U]>;
+};
 /**
  * One consumer or rpc of a contract, as a provider on a port of its own.
  *
@@ -22,8 +79,21 @@ declare const HANDLER_PREFIX = "AmqpHandler:";
  * 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.
+ *
+ * `unit` declares the ports the handler reads off `context.unit`, resolved out
+ * of the fork the delivery opened; the root's `unit.message` module must export
+ * every one of them.
  */
-declare const AmqpHandler: <C extends AnyAmqpContract, const K extends HandlerKeyOf<C>>(contract: C, key: K) => ReturnType<typeof Provider<HandlerPortOf<C, K>>>;
+declare const AmqpHandler: <C extends AnyAmqpContract, const K extends HandlerKeyOf<C>>(contract: C, key: K) => <const D extends Readonly<Record<string, AnyPort>>, const U extends Readonly<Record<string, AnyPort>> = Record<never, never>>(options: {
+  readonly inject: D;
+  /** The unit-scoped ports this handler reads off `context.unit`. */
+  readonly unit?: U;
+  readonly sync: (services: { readonly [N in keyof D]: ServiceOf<InstanceType<D[N]>>; }) => WorkerInferHandlers<C, {
+    readonly unit: UnitRecordOf<U>;
+  }>[K & keyof WorkerInferHandlers<C, {
+    readonly unit: UnitRecordOf<U>;
+  }>];
+}) => MintedHandler<C, K, InstanceType<D[keyof D]>, U>;
 //#endregion
 //#region src/amqp-runtime.d.ts
 /** What the worker publishes once it is consuming, read back through `RunningApp.runtimeInfo()`. */
@@ -44,6 +114,22 @@ declare class AmqpConfig extends AmqpConfig_base<{
 }> {}
 /** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
 declare class AmqpRuntime extends RuntimePort<Runtime<never, AmqpInfo>> {}
+/**
+ * A module `unit.message` may bind, as the upper bound `amqp()` constrains its
+ * own `Unit` type parameter to. `Module`'s `_exports` channel is contravariant,
+ * so `Exports = never` — never `unknown` — is what makes a REAL module's own
+ * (necessarily narrower) export type assignable to this bound: `(x: Concrete)
+ * => void` is assignable to `(x: never) => void`, not to `(x: unknown) =>
+ * void`.
+ */
+type AnyUnitModule = Module<never, never, unknown>;
+/**
+ * The needs a bound `unit.message` module still owes, or `never` when none is
+ * bound. `Scope` is excluded, since nothing can ever provide it — the same
+ * exemption `NeedsGate` itself carries — and so is the delivery, which the
+ * fork's own seed discharges.
+ */
+type UnitNeedsOf<Unit> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | AmqpMessageInstance> : never;
 /**
  * The contract type `TypedAmqpWorker.create` accepts, extracted rather than
  * imported by name so `@amqp-contract/contract` stays out of the peer range.
@@ -60,20 +146,20 @@ type AmqpConnectionOptions = NonNullable<Parameters<typeof TypedAmqpWorker.creat
 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> = {
+type AmqpOptions<TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined = undefined> = {
   /**
    * 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;
-} & AmqpTuning;
+} & AmqpTuning<Unit>;
 /**
  * What an AMQP deployment tunes, shared verbatim by `amqp()` and `AmqpModule` —
  * spelled once so the two cannot drift, which is what a second copy of an
  * option list always eventually does.
  */
-type AmqpTuning = {
+type AmqpTuning<Unit extends AnyUnitModule | undefined = undefined> = {
   /** Pins `AmqpConfig.url` 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. */
@@ -88,6 +174,15 @@ type AmqpTuning = {
    * `connectionOptions`, where setting it is silently inert.
    */
   readonly connectTimeoutMs?: number;
+  /**
+   * The unit module the worker forks around every delivery it dispatches,
+   * seeded with the validated message on `AmqpMessage(contract)`. Built after
+   * the message is validated, torn down when the unit closes; what it exports
+   * is what a piece may declare on its own `unit:` record.
+   */
+  readonly unit?: {
+    readonly message?: Unit;
+  };
 };
 /**
  * The AMQP starter: a module providing the runtime and its configuration (bound
@@ -97,11 +192,17 @@ type AmqpTuning = {
  *
  * 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>>;
+declare const amqp: <TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined = undefined>(options: AmqpOptions<TContract, Unit>) => Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract> | UnitNeedsOf<Unit>>;
 /** 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>;
+  /** Phantom, carrying the ports the piece injects off `context.unit`. */
+  readonly _declared?: unknown;
 }; }[HandlerKeyOf<C>];
+/** Every port the pieces in `T` inject off `context.unit` — what the root's `unit.message` must export. */
+type DeclaredOf<T extends readonly {
+  readonly _declared?: unknown;
+}[]> = NonNullable<T[number]["_declared"]>;
 /** The key a piece carries, read back off its port id. */
 type KeyOfPiece<P> = P extends {
   readonly port: {
@@ -123,6 +224,29 @@ type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exc
  * hand.
  */
 type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
+/**
+ * The record arm: the whole handlers record from one `sync`, with one `unit:`
+ * record shared by every entry in it.
+ *
+ * It is `{ inject, unit?, sync }` — di's other arms are gone — for PARITY, not
+ * for a type-system reason: `value` could have carried the record just as well,
+ * since `U` infers from `unit` and never from the arm. `@btravstack/http-server`'s
+ * `api.OrpcRouter(contract)` is `{ inject, unit?, sync }` and so are all three
+ * packages' piece factories, so one arm across the family is one surface to
+ * learn and one to keep.
+ */
+type Whole<C extends AnyAmqpContract> = <const D extends Readonly<Record<string, AnyPort>>, const U extends Readonly<Record<string, AnyPort>> = Record<never, never>>(options: {
+  readonly inject: D;
+  /** The unit-scoped ports every handler in the record reads off `context.unit`. */
+  readonly unit?: U;
+  readonly sync: (services: { readonly [N in keyof D]: ServiceOf<InstanceType<D[N]>>; }) => WorkerInferHandlers<C, {
+    readonly unit: UnitRecordOf<U>;
+  }>;
+}) => Provider<HandlersInstanceOf<C>, never, InstanceType<D[keyof D]>> & {
+  readonly port: HandlersPortOf<C>;
+  /** Phantom: the declared ports, which `AmqpModule` gates `unit.message` against. */
+  readonly _declaredUnit?: InstanceType<U[keyof U]>;
+};
 /**
  * The composing arm. Declared LAST in the intersection below on purpose:
  * TypeScript reports the last overload's failure, so a non-covering array is
@@ -134,6 +258,8 @@ type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T ext
  */
 type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : Refuse<T, "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>;
+  /** Phantom: the union of every piece's declared ports, which `AmqpModule` gates `unit.message` against. */
+  readonly _declaredUnit?: DeclaredOf<T>;
 };
 /**
  * The handlers as a provider, from the contract. Two call forms, one port.
@@ -143,26 +269,33 @@ type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]
  * AmqpHandlers(orderContract)([orderNotifications, orderAudit])
  * ```
  *
- * The first is di's own `Provider(port)` on the starter's handlers port
- * typed for the contract. The second 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>;
+ * The first is `{ inject, unit?, sync }`, whose `sync` hands back the whole
+ * handlers record — one `unit:` record for every entry in it. The second 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) => Whole<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>>;
+type AmqpStarter<TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined> = Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract> | UnitNeedsOf<Unit>>;
 /** 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>];
+type Imports<I extends readonly AnyModule[], TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined> = readonly [...I, AmqpStarter<TContract, Unit>];
 /** 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[]> = AmqpTuning & {
+type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, Declared, Unit extends AnyUnitModule | undefined, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = AmqpTuning<Unit> & {
   readonly contract: TContract;
-  /** The application's handlers — what `AmqpHandlers(contract)(…)` returns for THIS contract. */
-  readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>;
+  /**
+   * The application's handlers — what `AmqpHandlers(contract)(…)` returns for
+   * THIS contract. Its `_declaredUnit` phantom carries every port its pieces
+   * read off `context.unit`, which is what {@link UnitGate} checks `unit.message`
+   * against.
+   */
+  readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds> & {
+    readonly _declaredUnit?: Declared;
+  };
   readonly imports?: I;
   readonly provides?: P;
   /** The application's own exports; `AmqpRuntime` is added, since `start` resolves it. */
@@ -172,7 +305,7 @@ type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, Handler
    * 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>;
+} & NeedsGate<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>, N> & UnitGate<Unit, Declared>;
 /**
  * `Module(name)({...})` for an AMQP deployment: everything a di module takes,
  * plus the contract and the handlers provider. The sugar imports the starter,
@@ -189,6 +322,6 @@ type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, Handler
  * 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]>>;
+declare const AmqpModule: <const Name extends string>(name: Name) => <TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, Declared = never, Unit extends AnyUnitModule | undefined = undefined, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>>[] = [], const N extends readonly AnyPort[] = []>(options: AmqpModuleOptions<TContract, HandlersError, HandlersNeeds, Declared, Unit, 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, Unit>])[number] extends (infer T_2) ? T_2 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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 };
+export { AmqpConfig, type AmqpConnectionOptions, AmqpHandler, AmqpHandlers, type AmqpInfo, AmqpMessage, type AmqpMessageOf, type AmqpMessagePortOf, AmqpModule, type AmqpModuleOptions, type AmqpOptions, AmqpRuntime, type HandlerPortOf, type HandlersInstanceOf, type HandlersPortOf, amqp };

package/dist/index.d.mts

@@ -1,10 +1,59 @@
-import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider } from "@btravstack/di";
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope, ServiceOf } 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/unit.d.ts
+/** What a bound unit module exports — the port instances a handler of that kind may read. */
+type UnitExportsOf<M> = M extends Module<infer X, never, unknown> ? X : never;
+/** The declared `unit:` record, as the services a handler reads off `context.unit`. */
+type UnitRecordOf<U extends Readonly<Record<string, AnyPort>>> = { readonly [N in keyof U]: ServiceOf<InstanceType<U[N]>>; };
+/**
+ * A piece injecting a port the bound `unit.message` module does not export.
+ * `unknown` when every declared port is covered — including the empty case, so
+ * a worker whose pieces declare no `unit:` is gated on nothing.
+ */
+type UnitGate<Unit, Declared> = [Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>] extends [never] ? unknown : {
+  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>;
+};
+//#endregion
 //#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 validated delivery, typed by the contract: the union of every consumer's
+ * and rpc's own consumed message. Reached through the handler's own second
+ * parameter, since `@amqp-contract/worker` exports
+ * `WorkerInferConsumedMessage` but not the `InferConsumerNames` constraint it
+ * takes — the same by-index route {@link AnyAmqpContract} travels.
+ */
+type AmqpMessageOf<C extends AnyAmqpContract> = Parameters<Extract<WorkerInferHandlers<C>[HandlerKeyOf<C>], (...args: never) => unknown>>[1];
+/** The seeded port's class, typed for `C`: what `AmqpMessage(contract)` answers. */
+type AmqpMessagePortOf<C extends AnyAmqpContract> = PortClassOf<"AmqpMessage", AmqpMessageOf<C>>;
+/**
+ * The seed's port instance, as it appears in a needs union — subtracted from
+ * what a bound `unit.message` module still owes, since the fork is what
+ * discharges it.
+ */
+type AmqpMessageInstance = PortInstance<"AmqpMessage", unknown>;
+/**
+ * The validated delivery as a port: the one thing the worker seeds the fork
+ * with, so a `unit.message` module derives a tenant — or anything else — from
+ * the message rather than from an ambient record.
+ *
+ * ```ts
+ * const Message = AmqpMessage(orderContract);
+ * const MessageUnit = Module("MessageUnit")({
+ *   needs: [Message],
+ *   provides: [Provider(Tenant)({ inject: { message: Message }, sync: ({ message }) => message.payload.tenantId })],
+ *   exports: [Tenant],
+ * });
+ * ```
+ *
+ * `contract` is read for its TYPE only. One `Port(...)` call fixed per contract
+ * at the type level, the move `AmqpHandlersPort` makes, so a module built for
+ * one contract cannot read another's message.
+ */
+declare const AmqpMessage: <C extends AnyAmqpContract>(contract: C) => AmqpMessagePortOf<C>;
 /**
  * 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
@@ -13,6 +62,14 @@ type HandlerKeyOf<C extends AnyAmqpContract> = keyof WorkerInferHandlers<C> & st
 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:";
+/** What a minted piece returns. */
+type MintedHandler<C extends AnyAmqpContract, K extends HandlerKeyOf<C>, N, U extends Readonly<Record<string, AnyPort>>> = Provider<InstanceType<HandlerPortOf<C, K>>, never, N> & {
+  readonly port: HandlerPortOf<C, K>;
+  /** The declared `unit:` record, which `AmqpHandlers`'s array arm reads back off the piece. */
+  readonly unit: U;
+  /** Phantom: the ports this piece injects, which the root's `unit.message` must export. */
+  readonly _declared?: InstanceType<U[keyof U]>;
+};
 /**
  * One consumer or rpc of a contract, as a provider on a port of its own.
  *
@@ -22,8 +79,21 @@ declare const HANDLER_PREFIX = "AmqpHandler:";
  * 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.
+ *
+ * `unit` declares the ports the handler reads off `context.unit`, resolved out
+ * of the fork the delivery opened; the root's `unit.message` module must export
+ * every one of them.
  */
-declare const AmqpHandler: <C extends AnyAmqpContract, const K extends HandlerKeyOf<C>>(contract: C, key: K) => ReturnType<typeof Provider<HandlerPortOf<C, K>>>;
+declare const AmqpHandler: <C extends AnyAmqpContract, const K extends HandlerKeyOf<C>>(contract: C, key: K) => <const D extends Readonly<Record<string, AnyPort>>, const U extends Readonly<Record<string, AnyPort>> = Record<never, never>>(options: {
+  readonly inject: D;
+  /** The unit-scoped ports this handler reads off `context.unit`. */
+  readonly unit?: U;
+  readonly sync: (services: { readonly [N in keyof D]: ServiceOf<InstanceType<D[N]>>; }) => WorkerInferHandlers<C, {
+    readonly unit: UnitRecordOf<U>;
+  }>[K & keyof WorkerInferHandlers<C, {
+    readonly unit: UnitRecordOf<U>;
+  }>];
+}) => MintedHandler<C, K, InstanceType<D[keyof D]>, U>;
 //#endregion
 //#region src/amqp-runtime.d.ts
 /** What the worker publishes once it is consuming, read back through `RunningApp.runtimeInfo()`. */
@@ -44,6 +114,22 @@ declare class AmqpConfig extends AmqpConfig_base<{
 }> {}
 /** The runtime's port: what `amqp()` provides, and what the module `start` boots must export. */
 declare class AmqpRuntime extends RuntimePort<Runtime<never, AmqpInfo>> {}
+/**
+ * A module `unit.message` may bind, as the upper bound `amqp()` constrains its
+ * own `Unit` type parameter to. `Module`'s `_exports` channel is contravariant,
+ * so `Exports = never` — never `unknown` — is what makes a REAL module's own
+ * (necessarily narrower) export type assignable to this bound: `(x: Concrete)
+ * => void` is assignable to `(x: never) => void`, not to `(x: unknown) =>
+ * void`.
+ */
+type AnyUnitModule = Module<never, never, unknown>;
+/**
+ * The needs a bound `unit.message` module still owes, or `never` when none is
+ * bound. `Scope` is excluded, since nothing can ever provide it — the same
+ * exemption `NeedsGate` itself carries — and so is the delivery, which the
+ * fork's own seed discharges.
+ */
+type UnitNeedsOf<Unit> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | AmqpMessageInstance> : never;
 /**
  * The contract type `TypedAmqpWorker.create` accepts, extracted rather than
  * imported by name so `@amqp-contract/contract` stays out of the peer range.
@@ -60,20 +146,20 @@ type AmqpConnectionOptions = NonNullable<Parameters<typeof TypedAmqpWorker.creat
 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> = {
+type AmqpOptions<TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined = undefined> = {
   /**
    * 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;
-} & AmqpTuning;
+} & AmqpTuning<Unit>;
 /**
  * What an AMQP deployment tunes, shared verbatim by `amqp()` and `AmqpModule` —
  * spelled once so the two cannot drift, which is what a second copy of an
  * option list always eventually does.
  */
-type AmqpTuning = {
+type AmqpTuning<Unit extends AnyUnitModule | undefined = undefined> = {
   /** Pins `AmqpConfig.url` 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. */
@@ -88,6 +174,15 @@ type AmqpTuning = {
    * `connectionOptions`, where setting it is silently inert.
    */
   readonly connectTimeoutMs?: number;
+  /**
+   * The unit module the worker forks around every delivery it dispatches,
+   * seeded with the validated message on `AmqpMessage(contract)`. Built after
+   * the message is validated, torn down when the unit closes; what it exports
+   * is what a piece may declare on its own `unit:` record.
+   */
+  readonly unit?: {
+    readonly message?: Unit;
+  };
 };
 /**
  * The AMQP starter: a module providing the runtime and its configuration (bound
@@ -97,11 +192,17 @@ type AmqpTuning = {
  *
  * 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>>;
+declare const amqp: <TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined = undefined>(options: AmqpOptions<TContract, Unit>) => Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract> | UnitNeedsOf<Unit>>;
 /** 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>;
+  /** Phantom, carrying the ports the piece injects off `context.unit`. */
+  readonly _declared?: unknown;
 }; }[HandlerKeyOf<C>];
+/** Every port the pieces in `T` inject off `context.unit` — what the root's `unit.message` must export. */
+type DeclaredOf<T extends readonly {
+  readonly _declared?: unknown;
+}[]> = NonNullable<T[number]["_declared"]>;
 /** The key a piece carries, read back off its port id. */
 type KeyOfPiece<P> = P extends {
   readonly port: {
@@ -123,6 +224,29 @@ type Uncovered<C extends AnyAmqpContract, T extends readonly PieceOf<C>[]> = Exc
  * hand.
  */
 type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
+/**
+ * The record arm: the whole handlers record from one `sync`, with one `unit:`
+ * record shared by every entry in it.
+ *
+ * It is `{ inject, unit?, sync }` — di's other arms are gone — for PARITY, not
+ * for a type-system reason: `value` could have carried the record just as well,
+ * since `U` infers from `unit` and never from the arm. `@btravstack/http-server`'s
+ * `api.OrpcRouter(contract)` is `{ inject, unit?, sync }` and so are all three
+ * packages' piece factories, so one arm across the family is one surface to
+ * learn and one to keep.
+ */
+type Whole<C extends AnyAmqpContract> = <const D extends Readonly<Record<string, AnyPort>>, const U extends Readonly<Record<string, AnyPort>> = Record<never, never>>(options: {
+  readonly inject: D;
+  /** The unit-scoped ports every handler in the record reads off `context.unit`. */
+  readonly unit?: U;
+  readonly sync: (services: { readonly [N in keyof D]: ServiceOf<InstanceType<D[N]>>; }) => WorkerInferHandlers<C, {
+    readonly unit: UnitRecordOf<U>;
+  }>;
+}) => Provider<HandlersInstanceOf<C>, never, InstanceType<D[keyof D]>> & {
+  readonly port: HandlersPortOf<C>;
+  /** Phantom: the declared ports, which `AmqpModule` gates `unit.message` against. */
+  readonly _declaredUnit?: InstanceType<U[keyof U]>;
+};
 /**
  * The composing arm. Declared LAST in the intersection below on purpose:
  * TypeScript reports the last overload's failure, so a non-covering array is
@@ -134,6 +258,8 @@ type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T ext
  */
 type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : Refuse<T, "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>;
+  /** Phantom: the union of every piece's declared ports, which `AmqpModule` gates `unit.message` against. */
+  readonly _declaredUnit?: DeclaredOf<T>;
 };
 /**
  * The handlers as a provider, from the contract. Two call forms, one port.
@@ -143,26 +269,33 @@ type Compose<C extends AnyAmqpContract> = <const T extends readonly PieceOf<C>[]
  * AmqpHandlers(orderContract)([orderNotifications, orderAudit])
  * ```
  *
- * The first is di's own `Provider(port)` on the starter's handlers port
- * typed for the contract. The second 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>;
+ * The first is `{ inject, unit?, sync }`, whose `sync` hands back the whole
+ * handlers record — one `unit:` record for every entry in it. The second 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) => Whole<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>>;
+type AmqpStarter<TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined> = Module<AmqpRuntime | AmqpConfig, ConfigInvalid, Env | HandlersInstanceOf<TContract> | UnitNeedsOf<Unit>>;
 /** 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>];
+type Imports<I extends readonly AnyModule[], TContract extends AnyAmqpContract, Unit extends AnyUnitModule | undefined> = readonly [...I, AmqpStarter<TContract, Unit>];
 /** 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[]> = AmqpTuning & {
+type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, Declared, Unit extends AnyUnitModule | undefined, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>>[], N extends readonly AnyPort[]> = AmqpTuning<Unit> & {
   readonly contract: TContract;
-  /** The application's handlers — what `AmqpHandlers(contract)(…)` returns for THIS contract. */
-  readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds>;
+  /**
+   * The application's handlers — what `AmqpHandlers(contract)(…)` returns for
+   * THIS contract. Its `_declaredUnit` phantom carries every port its pieces
+   * read off `context.unit`, which is what {@link UnitGate} checks `unit.message`
+   * against.
+   */
+  readonly handlers: Provider<HandlersInstanceOf<TContract>, HandlersError, HandlersNeeds> & {
+    readonly _declaredUnit?: Declared;
+  };
   readonly imports?: I;
   readonly provides?: P;
   /** The application's own exports; `AmqpRuntime` is added, since `start` resolves it. */
@@ -172,7 +305,7 @@ type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, Handler
    * 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>;
+} & NeedsGate<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>, N> & UnitGate<Unit, Declared>;
 /**
  * `Module(name)({...})` for an AMQP deployment: everything a di module takes,
  * plus the contract and the handlers provider. The sugar imports the starter,
@@ -189,6 +322,6 @@ type AmqpModuleOptions<TContract extends AnyAmqpContract, HandlersError, Handler
  * 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]>>;
+declare const AmqpModule: <const Name extends string>(name: Name) => <TContract extends AnyAmqpContract, HandlersError, HandlersNeeds, Declared = never, Unit extends AnyUnitModule | undefined = undefined, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, TContract, Unit>, Provides<P, TContract, HandlersError, HandlersNeeds>>[] = [], const N extends readonly AnyPort[] = []>(options: AmqpModuleOptions<TContract, HandlersError, HandlersNeeds, Declared, Unit, 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, Unit>])[number] extends (infer T_2) ? T_2 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, AmqpStarter<TContract, Unit>])[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 };
+export { AmqpConfig, type AmqpConnectionOptions, AmqpHandler, AmqpHandlers, type AmqpInfo, AmqpMessage, type AmqpMessageOf, type AmqpMessagePortOf, AmqpModule, type AmqpModuleOptions, type AmqpOptions, AmqpRuntime, type HandlerPortOf, type HandlersInstanceOf, type HandlersPortOf, amqp };

package/dist/index.mjs

@@ -1,10 +1,76 @@
 import { Module, Port, Provider } from "@btravstack/di";
 import { TypedAmqpWorker } from "@amqp-contract/worker";
 import { Config, Env } from "@btravstack/config";
-import { Observers, RuntimePort, RuntimeStartFailed, noObserver, observe, releasedBy } from "@btravstack/core";
+import { Observers, RuntimePort, RuntimeStartFailed, noObserver, observe, releasedBy, traceIdOfTraceparent } from "@btravstack/core";
 import { P } from "unthrown";
 import { randomUUID } from "node:crypto";
+//#region src/unit.ts
+/**
+* Where `messageUnits` leaves the forked context for the piece wrappers to read.
+* A symbol rather than a name: the dispatcher merges it into the context every
+* handler sees, and a string key would appear on the record a handler written
+* against the `{ inject, sync }` arm destructures.
+*/
+const UNIT_SCOPE = Symbol("@btravstack/amqp-worker/unit-scope");
+/**
+* The declared record, as a getter per name resolved on read out of the fork.
+* Neither writable nor configurable — a handler reads what the fork holds, and
+* cannot reshape the record under the next delivery. With no `unit.message`
+* bound there is nothing to resolve from, so the record is empty whatever was
+* declared.
+*/
+const unitRecordOf = (forked, record) => {
+	const unit = {};
+	if (forked === void 0) return unit;
+	for (const [name, port] of Object.entries(record)) Object.defineProperty(unit, name, {
+		enumerable: true,
+		get: () => forked.get(port)
+	});
+	return unit;
+};
+/**
+* One handler entry — a function, or `[handler, options]` — with its piece's
+* declared record put on `context.unit`. Applied once per piece as di
+* constructs it, so a delivery costs one record and one context object.
+*/
+const withUnit = (record, entry) => {
+	const wrap = (handler) => (helpers, message) => {
+		const { [UNIT_SCOPE]: forked, ...rest } = helpers.context ?? {};
+		return handler({
+			...helpers,
+			context: {
+				...rest,
+				unit: unitRecordOf(forked, record)
+			}
+		}, message);
+	};
+	return Array.isArray(entry) ? [wrap(entry[0]), entry[1]] : wrap(entry);
+};
+//#endregion
 //#region src/handler.ts
+/** One id, declared once, so no contract instantiating it warns about a duplicate. */
+const AmqpMessagePort = Port("AmqpMessage");
+/**
+* The validated delivery as a port: the one thing the worker seeds the fork
+* with, so a `unit.message` module derives a tenant — or anything else — from
+* the message rather than from an ambient record.
+*
+* ```ts
+* const Message = AmqpMessage(orderContract);
+* const MessageUnit = Module("MessageUnit")({
+*   needs: [Message],
+*   provides: [Provider(Tenant)({ inject: { message: Message }, sync: ({ message }) => message.payload.tenantId })],
+*   exports: [Tenant],
+* });
+* ```
+*
+* `contract` is read for its TYPE only. One `Port(...)` call fixed per contract
+* at the type level, the move `AmqpHandlersPort` makes, so a module built for
+* one contract cannot read another's message.
+*/
+const AmqpMessage = (contract) => {
+	return AmqpMessagePort;
+};
 /** The prefix a piece's port id carries; the composing form strips it to recover the key. */
 const HANDLER_PREFIX = "AmqpHandler:";
 /**
@@ -16,30 +82,49 @@ const HANDLER_PREFIX = "AmqpHandler:";
 * 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.
+*
+* `unit` declares the ports the handler reads off `context.unit`, resolved out
+* of the fork the delivery opened; the root's `unit.message` module must export
+* every one of them.
 */
 const AmqpHandler = (contract, key) => {
 	const port = class extends Port(`${HANDLER_PREFIX}${key}`) {};
-	return Provider(port);
+	return (options) => {
+		const record = options.unit ?? {};
+		return Object.assign(Provider(port)({
+			inject: options.inject,
+			sync: (services) => withUnit(record, options.sync(services))
+		}), { unit: record });
+	};
 };
 //#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.
+* Open one kernel unit per delivery, forking `unit` — when one is bound — after
+* the message is validated, before the handler runs; the fork is torn down
+* when the unit closes. It is seeded with the validated delivery on
+* `AmqpMessage(contract)`, so a unit module derives a tenant from the message
+* rather than reading one off an ambient record. With no `unit` bound, `next()`
+* runs unchanged, so the ambient `currentUnit()` record is what the unit leaves
+* for the adapters that read it.
+*
+* The forked context rides the dispatcher's context under {@link UNIT_SCOPE},
+* where each piece's own wrapper turns it into the typed `context.unit` record
+* that piece declared — the records live with the pieces, so a hand-composed
+* `amqp()` gets them without threading a second option through the starter.
 *
 * **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, observers) => (args, next) => {
+const messageUnits = (host, observers, unit) => (args, next) => {
 	const settle = observe(observers, {
 		component: "amqp",
 		name: "delivery",
 		attributes: { handler: args.handlerName }
 	});
-	return host.run(metaFor(args.rawMessage), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+	return host.run(metaFor(args.rawMessage), (scope) => unit === void 0 ? next() : scope.fork(unit, [[AmqpMessagePort, args.message]]).flatMap((forked) => next({ context: { [UNIT_SCOPE]: forked } }))).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
 		outcome: "error",
 		cause: failure.tag === "Err" ? failure.error : failure.cause
 	}));
@@ -69,17 +154,6 @@ const metaFor = (raw) => {
 		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
 /**
@@ -154,12 +228,12 @@ const amqp = (options) => {
 * AmqpHandlers(orderContract)([orderNotifications, orderAudit])
 * ```
 *
-* The first is di's own `Provider(port)` on the starter's handlers port
-* typed for the contract. The second 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.
+* The first is `{ inject, unit?, sync }`, whose `sync` hands back the whole
+* handlers record — one `unit:` record for every entry in it. The second 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);
@@ -167,7 +241,14 @@ const AmqpHandlers = (contract) => {
 		inject: Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(12), piece.port])),
 		sync: (services) => services
 	});
-	return ((first) => Array.isArray(first) ? compose(first) : build(first));
+	const whole = (options) => {
+		const record = options.unit ?? {};
+		return build({
+			inject: options.inject,
+			sync: (services) => Object.fromEntries(Object.entries(options.sync(services)).map(([key, entry]) => [key, withUnit(record, entry)]))
+		});
+	};
+	return ((first) => Array.isArray(first) ? compose(first) : whole(first));
 };
 const startFailed = (cause) => new RuntimeStartFailed({
 	runtime: "amqp",
@@ -185,7 +266,7 @@ const queuesOf = (contract) => [...new Set(Object.values({
 const createWorker = (host, config, options, handlers, observers) => TypedAmqpWorker.create({
 	contract: options.contract,
 	handlers,
-	middleware: messageUnits(host, observers),
+	middleware: messageUnits(host, observers, options.unit?.message),
 	urls: [config.url],
 	...options.connectionOptions === void 0 ? {} : { connectionOptions: options.connectionOptions },
 	...options.defaultConsumerOptions === void 0 ? {} : { defaultConsumerOptions: options.defaultConsumerOptions },
@@ -237,4 +318,4 @@ const AmqpModule = (name) => (options) => {
 	});
 };
 //#endregion
-export { AmqpConfig, AmqpHandler, AmqpHandlers, AmqpModule, AmqpRuntime, amqp };
+export { AmqpConfig, AmqpHandler, AmqpHandlers, AmqpMessage, AmqpModule, AmqpRuntime, amqp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/amqp-worker",
-  "version": "0.11.0",
+  "version": "0.13.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",
@@ -47,7 +47,7 @@
     "@amqp-contract/contract": "3.0.0-beta.7",
     "@amqp-contract/testing": "3.0.0-beta.7",
     "@amqp-contract/worker": "3.0.0-beta.7",
-    "@btravstack/tsconfig": "0.2.0",
+    "@btravstack/tsconfig": "0.4.0",
     "@opentelemetry/api": "1.9.1",
     "@types/node": "26.4.0",
     "@unthrown/vitest": "5.7.0",
@@ -57,19 +57,19 @@
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
     "zod": "4.5.3",
-    "@btravstack/config": "0.11.0",
-    "@btravstack/core": "0.11.0",
-    "@btravstack/di": "0.11.0",
+    "@btravstack/config": "0.13.0",
+    "@btravstack/core": "0.13.0",
+    "@btravstack/di": "0.13.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/testing": "0.11.0"
+    "@btravstack/testing": "0.13.0"
   },
   "peerDependencies": {
     "@amqp-contract/worker": "^3.0.0-beta.7",
     "@opentelemetry/api": "^1",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.11.0",
-    "@btravstack/core": "^0.11.0",
-    "@btravstack/di": "^0.11.0"
+    "@btravstack/config": "^0.13.0",
+    "@btravstack/core": "^0.13.0",
+    "@btravstack/di": "^0.13.0"
   },
   "engines": {
     "node": ">=22"