@btravstack/temporal-worker 0.12.0 → 0.13.0

package/dist/index.d.mts

@@ -1,10 +1,119 @@
-import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope } from "@btravstack/di";
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope, ServiceOf } from "@btravstack/di";
 import { ConfigInvalid, Env } from "@btravstack/config";
 import { Runtime, RuntimePort } from "@btravstack/core";
-import { DeclareActivitiesHandlerOptions } from "@temporal-contract/worker/activity";
+import { DeclareActivitiesHandlerOptions, EmptyContext } from "@temporal-contract/worker/activity";
 import { Duration } from "@temporalio/common";
 import { NativeConnection, WorkflowBundleWithSourceMap } from "@temporalio/worker";
 import { ContractDefinition } from "@temporal-contract/contract";
+//#region src/unit.d.ts
+/** What a bound unit module exports — the port instances an activity of that kind may read. */
+type UnitExportsOf<M> = M extends Module<infer X, never, unknown> ? X : never;
+/** The declared `unit:` record, as the services an activity 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.activity` 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/workflow-activities.d.ts
+/**
+ * `ActivitiesOf<C, …>` is a `NoInfer`-wrapped conditional TypeScript refuses to
+ * index by a generic key. Routing it through `infer` resolves it to a plain
+ * object type first, which IS indexable.
+ */
+type ActivitiesRecordOf<C extends ContractDefinition, TContext extends Record<string, unknown> | EmptyContext = EmptyContext> = ActivitiesOf<C, TContext> extends (infer Resolved) ? Resolved : never;
+/** The top-level keys of `C`'s activities record: a workflow that declares activities, or a contract-global activity. */
+type ActivitiesKeyOf<C extends ContractDefinition> = keyof ActivitiesRecordOf<C> & string;
+/**
+ * One entry's validated input, reached through the implementation's own second
+ * parameter — a workflow key carries a record of implementations, a
+ * contract-global one carries the implementation itself. `WorkerInferInput` is
+ * declared by `@temporal-contract/worker` and exported from none of its
+ * subpaths, so the by-index route is the only one open.
+ */
+type InputOfEntry<V> = V extends ((helpers: never, input: infer I) => unknown) ? I : V extends Readonly<Record<string, unknown>> ? InputOfEntry<V[keyof V]> : never;
+/** The validated activity input, typed by the contract: the union of every activity's own input. */
+type ActivityInputOf<C extends ContractDefinition> = InputOfEntry<ActivitiesRecordOf<C>[ActivitiesKeyOf<C>]>;
+/** The seeded port's class, typed for `C`: what `ActivityInput(contract)` answers. */
+type ActivityInputPortOf<C extends ContractDefinition> = PortClassOf<"ActivityInput", ActivityInputOf<C>>;
+/**
+ * The seed's port instance, as it appears in a needs union — subtracted from
+ * what a bound `unit.activity` module still owes, since the fork is what
+ * discharges it.
+ */
+type ActivityInputInstance = PortInstance<"ActivityInput", unknown>;
+/**
+ * The validated activity input as a port: the one thing the worker seeds the
+ * fork with, so a `unit.activity` module derives a tenant — or anything else —
+ * from the invocation rather than from an ambient record.
+ *
+ * ```ts
+ * const Input = ActivityInput(orderContract);
+ * const ActivityUnit = Module("ActivityUnit")({
+ *   needs: [Input],
+ *   provides: [Provider(Tenant)({ inject: { input: Input }, sync: ({ input }) => input.tenantId })],
+ *   exports: [Tenant],
+ * });
+ * ```
+ *
+ * `contract` is read for its TYPE only. One `Port(...)` call fixed per contract
+ * at the type level, the move `TemporalActivitiesPort` makes, so a module built
+ * for one contract cannot read another's input.
+ */
+declare const ActivityInput: <C extends ContractDefinition>(contract: C) => ActivityInputPortOf<C>;
+/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
+declare const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
+/**
+ * The port one piece targets. Its id carries the key, which is what makes two
+ * slices claiming one workflow di's duplicate-provider defect rather than a
+ * silent merge.
+ */
+type WorkflowActivitiesPortOf<C extends ContractDefinition, K extends ActivitiesKeyOf<C>> = PortClassOf<`${typeof WORKFLOW_ACTIVITIES_PREFIX}${K}`, ActivitiesRecordOf<C>[K]>;
+/** What a minted piece returns. */
+type MintedActivities<C extends ContractDefinition, K extends ActivitiesKeyOf<C>, N, U extends Readonly<Record<string, AnyPort>>> = Provider<InstanceType<WorkflowActivitiesPortOf<C, K>>, never, N> & {
+  readonly port: WorkflowActivitiesPortOf<C, K>;
+  /** The declared `unit:` record, which the wrapper resolves against. */
+  readonly unit: U;
+  /** Phantom: the ports this piece injects, which the root's `unit.activity` must export. */
+  readonly _declared?: InstanceType<U[keyof U]>;
+};
+/** The activities `sync` hands back, typed by the record THIS piece declared. */
+type ScopedActivitiesOf<C extends ContractDefinition, K extends ActivitiesKeyOf<C>, U extends Readonly<Record<string, AnyPort>>> = ActivitiesRecordOf<C, {
+  readonly unit: UnitRecordOf<U>;
+}>[K & keyof ActivitiesRecordOf<C, {
+  readonly unit: UnitRecordOf<U>;
+}>];
+/**
+ * One workflow's activities, as a provider on a port of its own.
+ *
+ * A worker that polls one queue for several workflows is several pieces, each
+ * declaring the services its own activities call;
+ * `TemporalActivities(contract)([...])` composes them. `contract` is read for
+ * its TYPE only, and types both `key` and the record — so an activity the
+ * workflow does not declare is a compile error here rather than at startup.
+ *
+ * `key` is any top-level key of the activities record, which includes a
+ * contract-global activity as well as a workflow; the name is imprecise in that
+ * one case deliberately, since narrowing it would lock such a contract out of
+ * the split.
+ *
+ * There is no name to give: the key IS the port's name.
+ *
+ * `unit` declares the ports the activities read off `context.unit`, resolved
+ * out of the fork the attempt opened; the root's `unit.activity` module must
+ * export every one of them.
+ */
+declare const TemporalWorkflowActivities: <C extends ContractDefinition, const K extends ActivitiesKeyOf<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 these activities read off `context.unit`. */
+  readonly unit?: U;
+  readonly sync: (services: { readonly [N in keyof D]: ServiceOf<InstanceType<D[N]>>; }) => ScopedActivitiesOf<C, K, U>;
+}) => MintedActivities<C, K, InstanceType<D[keyof D]>, U>;
+//#endregion
 //#region src/temporal-runtime.d.ts
 /** What the worker publishes once it is polling, read back through `RunningApp.runtimeInfo()`. */
 type TemporalInfo = {
@@ -58,8 +167,29 @@ declare class TemporalUnreachable extends TemporalUnreachable_base<{
 }
 /** The runtime's port: what `temporal()` provides, and what the module `start` boots must export. */
 declare class TemporalRuntime extends RuntimePort<Runtime<never, TemporalInfo>> {}
-/** The activity implementations `declareActivitiesHandler` takes for `C`, with no injected context. */
-type ActivitiesOf<C extends ContractDefinition> = DeclareActivitiesHandlerOptions<C>["activities"];
+/**
+ * A module `unit.activity` may bind, as the upper bound `temporal()`
+ * 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.activity` 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 activity input, which
+ * the fork's own seed discharges.
+ */
+type UnitNeedsOf<Unit> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | ActivityInputInstance> : never;
+/**
+ * The activity implementations `declareActivitiesHandler` takes for `C`.
+ * `TContext` is what an implementation reads off `helpers.context` — left
+ * empty for the port the composed record lands on, and the declared
+ * `{ unit }` record for the piece that declared it.
+ */
+type ActivitiesOf<C extends ContractDefinition, TContext extends Record<string, unknown> | EmptyContext = EmptyContext> = DeclareActivitiesHandlerOptions<C, TContext>["activities"];
 /** The activities port class, typed for `C`: what `TemporalActivities(contract)(…).port` is. */
 type ActivitiesPortOf<C extends ContractDefinition> = PortClassOf<"TemporalActivities", ActivitiesOf<C>>;
 /** The activities port's instance for `C` — the module's one need. */
@@ -69,7 +199,7 @@ type ActivitiesInstanceOf<C extends ContractDefinition> = PortInstance<"Temporal
  * `TemporalModule` — spelled once so the two cannot drift, which is what a
  * second copy of an option list always eventually does.
  */
-type TemporalTuning = {
+type TemporalTuning<Unit extends AnyUnitModule | undefined = undefined> = {
   /** Pins `TemporalConfig.address` instead of reading `TEMPORAL_ADDRESS`. */
   readonly address?: string;
   /** Pins `TemporalConfig.namespace` instead of reading `TEMPORAL_NAMESPACE`. */
@@ -88,8 +218,17 @@ type TemporalTuning = {
    * `shutdownGraceTime`.
    */
   readonly gracePeriod?: Duration;
+  /**
+   * The unit module the worker forks around every activity attempt it
+   * dispatches, with no seed. Built after the activity is invoked, torn down
+   * when the unit closes — the point where a later phase seeds it with the
+   * workflow's tenant.
+   */
+  readonly unit?: {
+    readonly activity?: Unit;
+  };
 };
-type TemporalOptions<C extends ContractDefinition> = TemporalTuning & {
+type TemporalOptions<C extends ContractDefinition, Unit extends AnyUnitModule | undefined = undefined> = TemporalTuning<Unit> & {
   /**
    * The contract; the task queue this worker polls is read off it, and the
    * activities port is typed by it. The starter calls
@@ -110,56 +249,28 @@ type Provided = TemporalRuntime | TemporalConfig | TemporalConnection;
  * With both configuration fields pinned the module reads nothing from the
  * environment; pin only one and the other still comes from it.
  */
-declare const temporal: <C extends ContractDefinition>(options: TemporalOptions<C>) => Module<Provided, ConfigInvalid | TemporalUnreachable, Env | Scope | ActivitiesInstanceOf<C>>;
-//#endregion
-//#region src/workflow-activities.d.ts
-/**
- * `ActivitiesOf<C>` is a `NoInfer`-wrapped conditional TypeScript refuses to
- * index by a generic key. Routing it through `infer` resolves it to a plain
- * object type first, which IS indexable.
- */
-type ActivitiesRecordOf<C extends ContractDefinition> = ActivitiesOf<C> extends (infer Resolved) ? Resolved : never;
-/** The top-level keys of `C`'s activities record: a workflow that declares activities, or a contract-global activity. */
-type ActivitiesKeyOf<C extends ContractDefinition> = keyof ActivitiesRecordOf<C> & string;
-/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
-declare const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
-/**
- * The port one piece targets. Its id carries the key, which is what makes two
- * slices claiming one workflow di's duplicate-provider defect rather than a
- * silent merge.
- */
-type WorkflowActivitiesPortOf<C extends ContractDefinition, K extends ActivitiesKeyOf<C>> = PortClassOf<`${typeof WORKFLOW_ACTIVITIES_PREFIX}${K}`, ActivitiesRecordOf<C>[K]>;
-/**
- * One workflow's activities, as a provider on a port of its own.
- *
- * A worker that polls one queue for several workflows is several pieces, each
- * declaring the services its own activities call;
- * `TemporalActivities(contract)([...])` composes them. `contract` is read for
- * its TYPE only, and types both `key` and the record — so an activity the
- * workflow does not declare is a compile error here rather than at startup.
- *
- * `key` is any top-level key of the activities record, which includes a
- * contract-global activity as well as a workflow; the name is imprecise in that
- * one case deliberately, since narrowing it would lock such a contract out of
- * the split.
- *
- * There is no name to give: the key IS the port's name.
- */
-declare const TemporalWorkflowActivities: <C extends ContractDefinition, const K extends ActivitiesKeyOf<C>>(contract: C, key: K) => ReturnType<typeof Provider<WorkflowActivitiesPortOf<C, K>>>;
+declare const temporal: <C extends ContractDefinition, Unit extends AnyUnitModule | undefined = undefined>(options: TemporalOptions<C, Unit>) => Module<Provided, ConfigInvalid | TemporalUnreachable, Env | Scope | ActivitiesInstanceOf<C> | UnitNeedsOf<Unit>>;
 //#endregion
 //#region src/temporal-module.d.ts
 /** The starter's own module, as the sugar adds it to the application's imports. */
-type TemporalStarter<C extends ContractDefinition> = Module<TemporalRuntime | TemporalConfig | TemporalConnection, ConfigInvalid | TemporalUnreachable, Env | Scope | ActivitiesInstanceOf<C>>;
+type TemporalStarter<C extends ContractDefinition, Unit extends AnyUnitModule | undefined> = Module<TemporalRuntime | TemporalConfig | TemporalConnection, ConfigInvalid | TemporalUnreachable, Env | Scope | ActivitiesInstanceOf<C> | UnitNeedsOf<Unit>>;
 /** The application's imports plus the starter — the tuple `Module(name)` is handed. */
-type Imports<I extends readonly AnyModule[], C extends ContractDefinition> = readonly [...I, TemporalStarter<C>];
+type Imports<I extends readonly AnyModule[], C extends ContractDefinition, Unit extends AnyUnitModule | undefined> = readonly [...I, TemporalStarter<C, Unit>];
 /** The activities provider plus the application's own — the tuple `Module(name)` is handed. */
 type Provides<P extends readonly AnyProvider[], C extends ContractDefinition, ActivitiesError, ActivitiesNeeds> = readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P];
-type TemporalModuleOptions<C extends ContractDefinition, ActivitiesError, ActivitiesNeeds, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, C>, Provides<P, C, ActivitiesError, ActivitiesNeeds>>[], N extends readonly AnyPort[]> = TemporalTuning & {
+type TemporalModuleOptions<C extends ContractDefinition, ActivitiesError, ActivitiesNeeds, Declared, Unit extends AnyUnitModule | undefined, I extends readonly AnyModule[], P extends readonly AnyProvider[], X extends readonly Exportable<Imports<I, C, Unit>, Provides<P, C, ActivitiesError, ActivitiesNeeds>>[], N extends readonly AnyPort[]> = TemporalTuning<Unit> & {
   /** The `temporal-contract` contract; the task queue this worker polls is read off it. */
   readonly contract: C;
   readonly workflows: WorkflowSource;
-  /** The application's activity implementations — what `TemporalActivities(contract)(…)` returns. */
-  readonly activities: Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>;
+  /**
+   * The application's activity implementations — what
+   * `TemporalActivities(contract)(…)` returns. Its `_declaredUnit` phantom
+   * carries every port its pieces read off `context.unit`, which is what
+   * {@link UnitGate} checks `unit.activity` against.
+   */
+  readonly activities: Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds> & {
+    readonly _declaredUnit?: Declared;
+  };
   readonly imports?: I;
   readonly provides?: P;
   /** The application's own exports; `TemporalRuntime` is added, since `start` resolves it. */
@@ -169,7 +280,7 @@ type TemporalModuleOptions<C extends ContractDefinition, ActivitiesError, Activi
    * over the augmented tuples below, so forgetting one is an error at THIS call.
    */
   readonly needs?: N;
-} & NeedsGate<Imports<I, C>, Provides<P, C, ActivitiesError, ActivitiesNeeds>, N>;
+} & NeedsGate<Imports<I, C, Unit>, Provides<P, C, ActivitiesError, ActivitiesNeeds>, N> & UnitGate<Unit, Declared>;
 /**
  * `Module(name)({...})` for a Temporal worker deployment: everything a di module
  * takes, plus the contract, the activities provider and the workflow source. The
@@ -187,11 +298,17 @@ type TemporalModuleOptions<C extends ContractDefinition, ActivitiesError, Activi
  * await runMain(OrderTemporalWorker);
  * ```
  */
-declare const TemporalModule: <const Name extends string>(name: Name) => <C extends ContractDefinition, ActivitiesError, ActivitiesNeeds, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, C>, Provides<P, C, ActivitiesError, ActivitiesNeeds>>[] = [], const N extends readonly AnyPort[] = []>(options: TemporalModuleOptions<C, ActivitiesError, ActivitiesNeeds, I, P, X, N>) => Module<(Extract<(readonly [typeof TemporalRuntime, ...X])[number], AnyModule> extends (infer T) ? T extends Extract<(readonly [typeof TemporalRuntime, ...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 TemporalRuntime, ...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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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, TemporalStarter<C>])[number] extends (infer T_2) ? T_2 extends (readonly [...I, TemporalStarter<C>])[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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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, TemporalStarter<C>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, TemporalStarter<C>])[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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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, TemporalStarter<C>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, TemporalStarter<C>])[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, TemporalStarter<C>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, TemporalStarter<C>])[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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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 TemporalModule: <const Name extends string>(name: Name) => <C extends ContractDefinition, ActivitiesError, ActivitiesNeeds, Declared = never, Unit extends AnyUnitModule | undefined = undefined, const I extends readonly AnyModule[] = [], const P extends readonly AnyProvider[] = [], const X extends readonly Exportable<Imports<I, C, Unit>, Provides<P, C, ActivitiesError, ActivitiesNeeds>>[] = [], const N extends readonly AnyPort[] = []>(options: TemporalModuleOptions<C, ActivitiesError, ActivitiesNeeds, Declared, Unit, I, P, X, N>) => Module<(Extract<(readonly [typeof TemporalRuntime, ...X])[number], AnyModule> extends (infer T) ? T extends Extract<(readonly [typeof TemporalRuntime, ...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 TemporalRuntime, ...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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_1) ? T_1 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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, TemporalStarter<C, Unit>])[number] extends (infer T_2) ? T_2 extends (readonly [...I, TemporalStarter<C, 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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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, TemporalStarter<C, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, TemporalStarter<C, 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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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, TemporalStarter<C, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, TemporalStarter<C, 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, TemporalStarter<C, Unit>])[number] extends (infer T_4) ? T_4 extends (readonly [...I, TemporalStarter<C, 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<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_3) ? T_3 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...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]>>;
 /** One piece of the activities record — what `TemporalWorkflowActivities(contract, key)(…)` returns. */
 type PieceOf<C extends ContractDefinition> = { readonly [K in ActivitiesKeyOf<C>]: {
   readonly port: WorkflowActivitiesPortOf<C, K>;
+  /** Phantom, carrying the ports the piece injects off `context.unit`. */
+  readonly _declared?: unknown;
 }; }[ActivitiesKeyOf<C>];
+/** Every port the pieces in `T` inject off `context.unit` — what the root's `unit.activity` 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: {
@@ -213,6 +330,29 @@ type Uncovered<C extends ContractDefinition, T extends readonly PieceOf<C>[]> =
  * 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 activities 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 ContractDefinition> = <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 activity in the record reads off `context.unit`. */
+  readonly unit?: U;
+  readonly sync: (services: { readonly [N in keyof D]: ServiceOf<InstanceType<D[N]>>; }) => ActivitiesOf<C, {
+    readonly unit: UnitRecordOf<U>;
+  }>;
+}) => Provider<ActivitiesInstanceOf<C>, never, InstanceType<D[keyof D]>> & {
+  readonly port: ActivitiesPortOf<C>;
+  /** Phantom: the declared ports, which `TemporalModule` gates `unit.activity` 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
@@ -224,6 +364,8 @@ type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T ext
  */
 type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : Refuse<T, "UNCOVERED ACTIVITIES — the contract declares a workflow this array does not cover", Uncovered<C, T>>) => Provider<ActivitiesInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
   readonly port: ActivitiesPortOf<C>;
+  /** Phantom: the union of every piece's declared ports, which `TemporalModule` gates `unit.activity` against. */
+  readonly _declaredUnit?: DeclaredOf<T>;
 };
 /**
  * The activities as a provider, from the contract. Two call forms, one port.
@@ -233,13 +375,13 @@ type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C
  * TemporalActivities(orderContract)([fulfillOrder, chargeOrder])
  * ```
  *
- * The first is di's own `Provider(port)` on the starter's activities port
- * typed for the contract. The second takes the pieces
- * `TemporalWorkflowActivities(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 activities record. Every key must be covered, and two slices
- * claiming one key are di's duplicate-provider defect at build.
- */
-declare const TemporalActivities: <C extends ContractDefinition>(contract: C) => ReturnType<typeof Provider<ActivitiesPortOf<C>>> & Compose<C>;
+ * The first is `{ inject, unit?, sync }`, whose `sync` hands back the whole
+ * activities record — one `unit:` record for every entry in it. The second
+ * takes the pieces `TemporalWorkflowActivities(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 activities record. Every key must be covered,
+ * and two slices claiming one key are di's duplicate-provider defect at build.
+ */
+declare const TemporalActivities: <C extends ContractDefinition>(contract: C) => Whole<C> & Compose<C>;
 //#endregion
-export { type ActivitiesInstanceOf, type ActivitiesPortOf, TemporalActivities, TemporalConfig, TemporalConnection, type TemporalInfo, TemporalModule, type TemporalModuleOptions, type TemporalOptions, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, type WorkflowActivitiesPortOf, type WorkflowSource, temporal };
+export { type ActivitiesInstanceOf, type ActivitiesPortOf, ActivityInput, type ActivityInputOf, type ActivityInputPortOf, TemporalActivities, TemporalConfig, TemporalConnection, type TemporalInfo, TemporalModule, type TemporalModuleOptions, type TemporalOptions, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, type WorkflowActivitiesPortOf, type WorkflowSource, temporal };

package/dist/index.mjs

@@ -6,10 +6,123 @@ import { msToNumber } from "@temporalio/common";
 import { NativeConnection, Worker } from "@temporalio/worker";
 import { TaggedError, fromPromise, fromSafePromise, fromThrowable } from "unthrown";
 import { activityInfo } from "@temporalio/activity";
+//#region src/unit.ts
+/**
+* Where `activityUnits` leaves the forked context for the piece wrappers to
+* read. A symbol rather than a name: the middleware merges it into the context
+* every activity sees, and a string key would appear on the record an activity
+* written against the `{ inject, sync }` arm destructures.
+*/
+const UNIT_SCOPE = Symbol("@btravstack/temporal-worker/unit-scope");
+/**
+* The declared record, as a getter per name resolved on read out of the fork.
+* Neither writable nor configurable — an activity reads what the fork holds, and
+* cannot reshape the record under the next attempt. With no `unit.activity`
+* 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 entry of the activities record — a contract-global activity's own
+* implementation, or the record of them a workflow key carries — with its
+* piece's declared record put on `context.unit`. Applied once per piece as di
+* constructs it, so an attempt costs one record and one context object.
+*/
+const withUnit = (record, entry) => {
+	const wrap = (implementation) => (helpers, input) => {
+		const { [UNIT_SCOPE]: forked, ...rest } = helpers.context ?? {};
+		return implementation({
+			...helpers,
+			context: {
+				...rest,
+				unit: unitRecordOf(forked, record)
+			}
+		}, input);
+	};
+	return typeof entry === "function" ? wrap(entry) : Object.fromEntries(Object.entries(entry).map(([name, implementation]) => [name, wrap(implementation)]));
+};
+//#endregion
+//#region src/workflow-activities.ts
+/** One id, declared once, so no contract instantiating it warns about a duplicate. */
+const ActivityInputPort = Port("ActivityInput");
+/**
+* The validated activity input as a port: the one thing the worker seeds the
+* fork with, so a `unit.activity` module derives a tenant — or anything else —
+* from the invocation rather than from an ambient record.
+*
+* ```ts
+* const Input = ActivityInput(orderContract);
+* const ActivityUnit = Module("ActivityUnit")({
+*   needs: [Input],
+*   provides: [Provider(Tenant)({ inject: { input: Input }, sync: ({ input }) => input.tenantId })],
+*   exports: [Tenant],
+* });
+* ```
+*
+* `contract` is read for its TYPE only. One `Port(...)` call fixed per contract
+* at the type level, the move `TemporalActivitiesPort` makes, so a module built
+* for one contract cannot read another's input.
+*/
+const ActivityInput = (contract) => {
+	return ActivityInputPort;
+};
+/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
+const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
+/**
+* One workflow's activities, as a provider on a port of its own.
+*
+* A worker that polls one queue for several workflows is several pieces, each
+* declaring the services its own activities call;
+* `TemporalActivities(contract)([...])` composes them. `contract` is read for
+* its TYPE only, and types both `key` and the record — so an activity the
+* workflow does not declare is a compile error here rather than at startup.
+*
+* `key` is any top-level key of the activities record, which includes a
+* contract-global activity as well as a workflow; the name is imprecise in that
+* one case deliberately, since narrowing it would lock such a contract out of
+* the split.
+*
+* There is no name to give: the key IS the port's name.
+*
+* `unit` declares the ports the activities read off `context.unit`, resolved
+* out of the fork the attempt opened; the root's `unit.activity` module must
+* export every one of them.
+*/
+const TemporalWorkflowActivities = (contract, key) => {
+	const port = class extends Port(`${WORKFLOW_ACTIVITIES_PREFIX}${key}`) {};
+	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/activity-units.ts
 /**
-* Open one kernel unit per activity attempt. It injects nothing — `next()`
-* unchanged — so the ambient `currentUnit()` record is what an adapter reads.
+* Open one kernel unit per activity attempt, forking `unit` — when one is
+* bound — after the activity is invoked, before it runs; the fork is torn down
+* when the unit closes. It is seeded with the validated input on
+* `ActivityInput(contract)`, so a unit module derives a tenant from the
+* invocation rather than reading one off an ambient record. With no `unit`
+* bound, `next()` runs unchanged, so the ambient `currentUnit()` record is what
+* an adapter reads.
+*
+* The forked context rides the invocation'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
+* `temporal()` gets them without threading a second option through the starter,
+* and the middleware never has to map Temporal's FLAT activity name back to the
+* workflow key its piece was minted under.
 *
 * **That includes the kernel's per-unit `AbortSignal`**, and it is the only
 * route to it: an activity has no parameter to receive one through. Temporal's
@@ -19,13 +132,13 @@ import { activityInfo } from "@temporalio/activity";
 * No `Result`-unwrapping boundary, deliberately: `declareActivitiesHandler` owns
 * the mapping from a settled `Result` to an activity failure.
 */
-const activityUnits = (host, observers) => (_invocation, next) => {
+const activityUnits = (host, observers, unit) => (invocation, next) => {
 	const settle = observe(observers, {
 		component: "temporal",
 		name: "attempt",
 		attributes: { activity: activityInfo().activityType }
 	});
-	return host.run(metaFor(), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+	return host.run(metaFor(), (scope) => unit === void 0 ? next() : scope.fork(unit, [[ActivityInputPort, invocation.input]]).flatMap((forked) => next({ context: { [UNIT_SCOPE]: forked } }))).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
 		outcome: "error",
 		cause: failure.tag === "Err" ? failure.error : failure.cause
 	}));
@@ -163,7 +276,7 @@ const createWorker = (host, connection, config, activities, options, observers)
 	const { namespace } = config;
 	return fromThrowable(() => declareActivitiesHandler({
 		contract: options.contract,
-		middleware: activityUnits(host, observers),
+		middleware: activityUnits(host, observers, options.unit?.activity),
 		activities
 	}), startFailed)().toAsync().flatMap((handler) => fromPromise(Worker.create({
 		connection,
@@ -199,30 +312,6 @@ const poll = (worker, taskQueue, namespace) => {
 	};
 };
 //#endregion
-//#region src/workflow-activities.ts
-/** The prefix a piece's port id carries; the composing form strips it to recover the key. */
-const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
-/**
-* One workflow's activities, as a provider on a port of its own.
-*
-* A worker that polls one queue for several workflows is several pieces, each
-* declaring the services its own activities call;
-* `TemporalActivities(contract)([...])` composes them. `contract` is read for
-* its TYPE only, and types both `key` and the record — so an activity the
-* workflow does not declare is a compile error here rather than at startup.
-*
-* `key` is any top-level key of the activities record, which includes a
-* contract-global activity as well as a workflow; the name is imprecise in that
-* one case deliberately, since narrowing it would lock such a contract out of
-* the split.
-*
-* There is no name to give: the key IS the port's name.
-*/
-const TemporalWorkflowActivities = (contract, key) => {
-	const port = class extends Port(`${WORKFLOW_ACTIVITIES_PREFIX}${key}`) {};
-	return Provider(port);
-};
-//#endregion
 //#region src/temporal-module.ts
 /**
 * `Module(name)({...})` for a Temporal worker deployment: everything a di module
@@ -262,12 +351,12 @@ const TemporalModule = (name) => (options) => {
 * TemporalActivities(orderContract)([fulfillOrder, chargeOrder])
 * ```
 *
-* The first is di's own `Provider(port)` on the starter's activities port
-* typed for the contract. The second takes the pieces
-* `TemporalWorkflowActivities(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 activities record. Every 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
+* activities record — one `unit:` record for every entry in it. The second
+* takes the pieces `TemporalWorkflowActivities(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 activities record. Every key must be covered,
+* and two slices claiming one key are di's duplicate-provider defect at build.
 */
 const TemporalActivities = (contract) => {
 	const build = Provider(TemporalActivitiesPort);
@@ -275,7 +364,14 @@ const TemporalActivities = (contract) => {
 		inject: Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(27), 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));
 };
 //#endregion
-export { TemporalActivities, TemporalConfig, TemporalConnection, TemporalModule, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, temporal };
+export { ActivityInput, TemporalActivities, TemporalConfig, TemporalConnection, TemporalModule, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, temporal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/temporal-worker",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The Temporal worker runtime for @btravstack/core: one unit per activity attempt, and a drain that honours the kernel's deadline",
   "keywords": [
     "graceful-shutdown",
@@ -54,10 +54,10 @@
     }
   },
   "devDependencies": {
-    "@btravstack/tsconfig": "0.2.0",
-    "@temporal-contract/client": "8.0.0-beta.7",
-    "@temporal-contract/contract": "8.0.0-beta.7",
-    "@temporal-contract/worker": "8.0.0-beta.7",
+    "@btravstack/tsconfig": "0.4.0",
+    "@temporal-contract/client": "8.0.0-beta.9",
+    "@temporal-contract/contract": "8.0.0-beta.9",
+    "@temporal-contract/worker": "8.0.0-beta.9",
     "@temporalio/activity": "1.23.0",
     "@temporalio/client": "1.23.0",
     "@temporalio/common": "1.23.0",
@@ -71,23 +71,23 @@
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
     "zod": "4.5.3",
-    "@btravstack/config": "0.12.0",
-    "@btravstack/core": "0.12.0",
-    "@btravstack/di": "0.12.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.12.0"
+    "@btravstack/testing": "0.13.0"
   },
   "peerDependencies": {
-    "@temporal-contract/client": "^8.0.0-beta.7",
-    "@temporal-contract/contract": "^8.0.0-beta.7",
-    "@temporal-contract/worker": "^8.0.0-beta.7",
+    "@temporal-contract/client": "^8.0.0-beta.9",
+    "@temporal-contract/contract": "^8.0.0-beta.9",
+    "@temporal-contract/worker": "^8.0.0-beta.9",
     "@temporalio/activity": "^1.22.0",
     "@temporalio/common": "^1.22.0",
     "@temporalio/worker": "^1.22.0",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.12.0",
-    "@btravstack/core": "^0.12.0",
-    "@btravstack/di": "^0.12.0"
+    "@btravstack/config": "^0.13.0",
+    "@btravstack/core": "^0.13.0",
+    "@btravstack/di": "^0.13.0"
   },
   "peerDependenciesMeta": {
     "@temporal-contract/client": {