@btravstack/temporal-worker 0.32.0 → 0.33.0

package/README.md

@@ -161,7 +161,7 @@ startup `Err`, not a defect. `runtimeInfo()` reads `{ taskQueue, namespace }`
 back once the worker is polling.
 
 A worker polling for several workflows can be several slices instead of one
-record: `TemporalWorkflowActivities(contract, key)({ inject: { name: Dep }, unit, sync })` mints a
+record: `TemporalWorkflowActivities(contract, key)({ inject: { name: Dep }, unit, fork, sync })` mints a
 provider for ONE workflow's activities (or a contract-global activity),
 typed by the key alone, and `TemporalActivities(contract)([...])` composes an
 array of them into the same activities provider `TemporalModule` takes — the
@@ -184,6 +184,14 @@ slicing first. The root is checked against what was declared either way: bind a
 module that does not export one of those ports and `TemporalModule` refuses it,
 naming the port.
 
+A piece whose activities carry a different scope from the rest names its own
+module on `fork`: its attempts fork THAT module, seeded the same way, instead of
+`unit.activity` — a listing activity with no tenant in its input beside a
+fan-out whose activities each act for one. The piece's `unit` is then checked
+against its own module at the piece's call, the module's unmet needs become the
+root's (named by `start`), and an override reaches it under the module's name:
+`overridden(root, providers, { unit: { TenantUnit: [...] } })`.
+
 Its own test suite needs a **Docker daemon**: the specs run against the shared
 `temporalio/auto-setup` container `internal/test-infra` starts once per machine and every
 workspace reuses. Nothing else here does.
@@ -198,13 +206,21 @@ subpath. Why scheduled work costs a cluster here, and when it should not be
 this stack at all:
 [Run something on a schedule](https://btravstack.github.io/btravstack/how-to/run-something-on-a-schedule).
 
+## Testing
+
+`@btravstack/temporal-worker/testing` runs a worker's specs against one real
+Temporal server per test run: `temporalServer` is the Vitest `globalSetup`
+(the entry's default export), and `temporalEnvironment(prefix)` a file-scoped
+fixture answering `{ TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE }` for a namespace of
+the spec file's own. It needs Docker, and `vitest` and `testcontainers` as
+optional peers. See
+[Test a Temporal worker](https://btravstack.github.io/btravstack/how-to/test-a-temporal-worker).
+
 ## Options
 
-`TemporalModule(name)({...})` takes `temporal()`'s options plus `activities`
-and the module lists (`imports`, `provides`, `exports`, `needs`). The
-`temporal()` primitive does not take `activities` as an option — it **needs**
-the activities provider on its own port, which is how the composition root
-supplies it:
+`TemporalModule(name)({...})` takes the starter's options plus `activities`
+and the module lists (`imports`, `provides`, `exports`, `needs`). It is the
+only way to compose the starter, which is not exported:
 
 | Option        | What it is                                                                                                              |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------- |

package/dist/index.d.mts

@@ -59,11 +59,15 @@ declare const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
  * 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> & {
+/**
+ * What a minted piece returns. A piece naming its own `fork` owes that
+ * module's unmet needs, and leaves nothing for the root's `unit.activity` to
+ * export — its declared ports were checked against its own module at the call.
+ */
+type MintedActivities<C extends ContractDefinition, K extends ActivitiesKeyOf<C>, N, U extends Readonly<Record<string, AnyPort>>, M extends AnyUnitModule | undefined> = Provider<InstanceType<WorkflowActivitiesPortOf<C, K>>, never, N | UnitNeedsOf$1<M>> & {
   readonly port: WorkflowActivitiesPortOf<C, K>;
   /** Phantom: the ports this piece injects, which the root's `unit.activity` must export. */
-  readonly _declared?: InstanceType<U[keyof U]>;
+  readonly _declared?: undefined extends M ? InstanceType<U[keyof U]> : never;
 };
 /** 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, {
@@ -90,15 +94,24 @@ type ScopedActivitiesOf<C extends ContractDefinition, K extends ActivitiesKeyOf<
  * `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.
+ *
+ * `fork` names the unit module THESE activities fork per attempt instead of
+ * the root's `unit.activity` — seeded with the validated input on
+ * `ActivityInput(contract)` the same way — for a worker whose activities do
+ * not all carry the same scope: a listing activity with no tenant in its
+ * input beside a fan-out whose activities each act for one. The ports `unit`
+ * declares are then checked against this module, here.
  */
-export declare const TemporalWorkflowActivities: <C extends ContractDefinition, const K extends ActivitiesKeyOf<C>>(contract: C, key: K) => <const D extends Readonly<Record<string, AnyPort>> = Record<never, never>, const U extends Readonly<Record<string, AnyPort>> = Record<never, never>>(options: {
+export declare const TemporalWorkflowActivities: <C extends ContractDefinition, const K extends ActivitiesKeyOf<C>>(contract: C, key: K) => <const D extends Readonly<Record<string, AnyPort>> = Record<never, never>, const U extends Readonly<Record<string, AnyPort>> = Record<never, never>, M extends AnyUnitModule | undefined = undefined>(options: {
   readonly inject?: D;
   /** The unit-scoped ports these activities read off `context.unit`. */
   readonly unit?: U;
+  /** The unit module these activities fork per attempt, in place of the root's `unit.activity`. */
+  readonly fork?: M;
   readonly sync: (services: { readonly [N in keyof D]: ServiceOf<InstanceType<D[N]>>; }) => ScopedActivitiesOf<C, K, U>;
 } & ([keyof D] extends [never] ? unknown : {
   readonly inject: D;
-})) => MintedActivities<C, K, InstanceType<D[keyof D]>, U>;
+}) & ([Exclude<M, undefined>] extends [never] ? unknown : UnitGate<Exclude<M, undefined>, InstanceType<U[keyof U]>>)) => MintedActivities<C, K, InstanceType<D[keyof D]>, U, M>;
 //#endregion
 //#region src/temporal-runtime.d.ts
 /** What the worker publishes once it is polling, read back through `RunningApp.runtimeInfo()`. */
@@ -119,7 +132,7 @@ type WorkflowSource = {
 };
 declare const TemporalConfig_base: import("@btravstack/di").PortClass<"TemporalConfig">;
 /**
- * Where the Temporal service is, as a service: `temporal()` binds it from the
+ * Where the Temporal service is, as a service: the starter binds it from the
  * environment — `TEMPORAL_ADDRESS` (default `127.0.0.1:7233`),
  * `TEMPORAL_NAMESPACE` (default `default`) and the shutdown budgets below —
  * unless pinned, and anything else in the graph may read it.
@@ -151,7 +164,7 @@ export declare class TemporalUnreachable extends TemporalUnreachable_base<{
 }> {
   message: string;
 }
-/** The runtime's port: what `temporal()` provides, and what the module `start` boots must export. */
+/** The runtime's port: what the starter provides, and what `TemporalModule` exports for `start` to boot. */
 export declare class TemporalRuntime extends RuntimePort<Runtime<never, TemporalInfo>> {}
 /** The needs a bound `unit.activity` module still owes, less the input the fork's seed discharges. */
 type UnitNeedsOf$1<Unit> = UnitNeedsOf<Unit, ActivityInputInstance>;
@@ -167,7 +180,7 @@ type ActivitiesPortOf<C extends ContractDefinition> = PortClassOf<"TemporalActiv
 /** The activities port's instance for `C` — the module's one need. */
 type ActivitiesInstanceOf<C extends ContractDefinition> = PortInstance<"TemporalActivities", ActivitiesOf<C>>;
 /**
- * What a Temporal deployment tunes, shared verbatim by `temporal()` and
+ * What a Temporal deployment tunes, shared verbatim by the starter and
  * `TemporalModule` — spelled once so the two cannot drift, which is what a
  * second copy of an option list always eventually does.
  */
@@ -210,19 +223,6 @@ type TemporalOptions<C extends ContractDefinition, Unit extends AnyUnitModule |
   readonly contract: C;
   readonly workflows: WorkflowSource;
 };
-type Provided = TemporalRuntime | TemporalConfig | TemporalConnection;
-/**
- * The Temporal starter: a module providing the runtime, its configuration
- * (bound from the `TEMPORAL_*` variables unless pinned) and the connection (a
- * resource opened with the scope and closed with it; a service that will not
- * answer is a modeled `TemporalUnreachable`). Import it next to the
- * application, export `TemporalRuntime`, provide the activities — the
- * activities port is a need of this module.
- *
- * Each configuration field is pinned on its own: a pinned field reads nothing
- * from the environment, and a field left unpinned still does.
- */
-export declare const temporal: <C extends ContractDefinition, Unit extends AnyUnitModule | undefined = undefined>(options: TemporalOptions<C, Unit>) => Module<Provided, ConfigInvalid | TemporalUnreachable, EnvReading<never, "TEMPORAL_ADDRESS" | "TEMPORAL_NAMESPACE" | "TEMPORAL_GRACE_PERIOD_MS" | "TEMPORAL_FORCE_AFTER_MS"> | Scope | ActivitiesInstanceOf<C> | UnitNeedsOf$1<Unit>>;
 //#endregion
 //#region src/temporal-module.d.ts
 /** The starter's own module, as the sugar adds it to the application's imports. */
@@ -231,7 +231,7 @@ type TemporalStarter<C extends ContractDefinition, Unit extends AnyUnitModule |
 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, 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> & {
+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[] | undefined> = TemporalTuning<Unit> & {
   /** The `temporal-contract` contract; the task queue this worker polls is read off it. */
   readonly contract: C;
   readonly workflows: WorkflowSource;
@@ -271,7 +271,7 @@ type TemporalModuleOptions<C extends ContractDefinition, ActivitiesError, Activi
  * await runMain(OrderTemporalWorker);
  * ```
  */
-export 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, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> extends (infer T_2) ? T_2 extends Extract<(readonly [typeof TemporalRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> ? T_2 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [typeof TemporalRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...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_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)[1] | ((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_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[1], Exclude<((readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] ? T_5 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_6) ? T_6 extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] ? T_5 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_6) ? T_6 extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[2], ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] ? T_5 extends Provider<infer P_1, infer E_2, infer N_2> ? readonly [P_1, E_2, N_2] : never : never : never)[0]>>;
+export 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[] | undefined = undefined>(options: TemporalModuleOptions<C, ActivitiesError, ActivitiesNeeds, Declared, Unit, I, P, X, N>) => Module<(Extract<(readonly [typeof TemporalRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> extends (infer T_2) ? T_2 extends Extract<(readonly [typeof TemporalRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...X])[number], AnyModule> ? T_2 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [typeof TemporalRuntime, ...((import("@btravstack/core").HealthChecks extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").HealthChecks : never) | (import("@btravstack/core").Logger extends ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T) ? T extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T extends Module<infer X_1, infer _E, infer _N> ? X_1 : never : 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 X_2, infer _E_1, infer _N_1> ? X_2 : never : never : never) ? typeof import("@btravstack/core").Logger : never))[], ...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_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)[1] | ((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_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[1], Exclude<((readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] ? T_5 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_6) ? T_6 extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] ? T_5 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_6) ? T_6 extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[2], ((readonly [...I, TemporalStarter<C, Unit>])[number] extends (infer T_6) ? T_6 extends (readonly [...I, TemporalStarter<C, Unit>])[number] ? T_6 extends Module<infer X_3, infer E, infer N_1> ? readonly [X_3, E, N_1] : never : never : never)[0] | ((readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] extends (infer T_5) ? T_5 extends (readonly [Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>, ...P])[number] ? T_5 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>;

package/dist/index.mjs

@@ -14,6 +14,21 @@ import { activityInfo } from "@temporalio/activity";
 * constructs it, so an attempt costs one record and one context object.
 */
 const withUnit = (record, entry) => typeof entry === "function" ? withUnitRecord(record, entry) : Object.fromEntries(Object.entries(entry).map(([name, implementation]) => [name, withUnitRecord(record, implementation)]));
+const PIECE_UNIT = Symbol("@btravstack/temporal-worker/piece-unit");
+const withFork = (entry, fork) => fork === void 0 ? entry : Object.defineProperty(entry, PIECE_UNIT, { value: fork });
+const forkOf = (entry) => entry?.[PIECE_UNIT];
+const unitsOf = (activity, activities) => {
+	const units = /* @__PURE__ */ new Map([["activity", activity]]);
+	for (const [key, entry] of Object.entries(activities)) {
+		const fork = forkOf(entry);
+		if (fork === void 0) continue;
+		if (fork === activity) throw new Error(`[temporal-worker] the "${key}" piece forks "${fork.name}", the module \`unit.activity\` already binds — drop the piece's \`fork\`, which adds nothing`);
+		const bound = units.get(fork.name);
+		if (bound !== void 0 && bound !== fork) throw new Error(`[temporal-worker] two unit modules named "${fork.name}" — an override keyed by that name could not tell them apart; rename one`);
+		units.set(fork.name, fork);
+	}
+	return Object.fromEntries(units);
+};
 //#endregion
 //#region src/workflow-activities.ts
 /** One id, declared once, so no contract instantiating it warns about a duplicate. */
@@ -60,17 +75,24 @@ const WORKFLOW_ACTIVITIES_PREFIX = "TemporalWorkflowActivities:";
 * `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.
+*
+* `fork` names the unit module THESE activities fork per attempt instead of
+* the root's `unit.activity` — seeded with the validated input on
+* `ActivityInput(contract)` the same way — for a worker whose activities do
+* not all carry the same scope: a listing activity with no tenant in its
+* input beside a fan-out whose activities each act for one. The ports `unit`
+* declares are then checked against this module, here.
 */
 const TemporalWorkflowActivities = (contract, key) => {
 	const port = class extends Port(`${WORKFLOW_ACTIVITIES_PREFIX}${key}`) {};
-	const mint = mintPiece(port, withUnit);
-	return (options) => mint(options);
+	return (options) => mintPiece(port, (record, entry) => withFork(withUnit(record, entry), options.fork))(options);
 };
 //#endregion
 //#region src/activity-units.ts
 /**
-* 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
+* Open one kernel unit per activity attempt, forking the module `unitFor`
+* answers for the attempt's contract key — the piece's own, else the
+* worker-wide one, when either 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`
@@ -91,7 +113,7 @@ const TemporalWorkflowActivities = (contract, key) => {
 * No `Result`-unwrapping boundary, deliberately: `declareActivitiesHandler` owns
 * the mapping from a settled `Result` to an activity failure.
 */
-const activityUnits = (host, observers, unit) => (invocation, next) => dispatchUnit({
+const activityUnits = (host, observers, unitFor) => (invocation, next) => dispatchUnit({
 	host,
 	observers,
 	operation: {
@@ -100,7 +122,7 @@ const activityUnits = (host, observers, unit) => (invocation, next) => dispatchU
 		attributes: { activity: activityInfo().activityType }
 	},
 	meta: metaFor(),
-	unit,
+	unit: unitFor(invocation.workflowName ?? invocation.activityName),
 	seed: [ActivityInputPort, invocation.input],
 	next
 });
@@ -134,7 +156,7 @@ const metaFor = () => {
 //#endregion
 //#region src/temporal-runtime.ts
 /**
-* Where the Temporal service is, as a service: `temporal()` binds it from the
+* Where the Temporal service is, as a service: the starter binds it from the
 * environment — `TEMPORAL_ADDRESS` (default `127.0.0.1:7233`),
 * `TEMPORAL_NAMESPACE` (default `default`) and the shutdown budgets below —
 * unless pinned, and anything else in the graph may read it.
@@ -154,7 +176,7 @@ var TemporalConnection = class extends Port("TemporalConnection") {};
 var TemporalUnreachable = class extends TaggedError("TemporalUnreachable") {
 	message = `the Temporal service at ${this.address} did not answer`;
 };
-/** The runtime's port: what `temporal()` provides, and what the module `start` boots must export. */
+/** The runtime's port: what the starter provides, and what `TemporalModule` exports for `start` to boot. */
 var TemporalRuntime = class extends RuntimePort {};
 /**
 * The activities' port — one id, the starter's own, which an application never
@@ -228,7 +250,7 @@ const temporal = (options) => {
 				sync: ({ connection, config: bound, activities: impls, observers }) => ({
 					name: "temporal",
 					resolves: [],
-					units: { activity: options.unit?.activity },
+					units: unitsOf(options.unit?.activity, impls),
 					start: (host) => createWorker(host, connection, bound, impls, options, observers)
 				})
 			})
@@ -250,7 +272,7 @@ const createWorker = (host, connection, config, activities, options, observers)
 	const { namespace } = config;
 	return fromThrowable(() => declareActivitiesHandler({
 		contract: options.contract,
-		middleware: activityUnits(host, observers, options.unit?.activity),
+		middleware: activityUnits(host, observers, (key) => forkOf(activities[key]) ?? options.unit?.activity),
 		activities
 	}), startFailed)().toAsync().flatMap((handler) => fromPromise(Worker.create({
 		connection,
@@ -356,4 +378,4 @@ const TemporalActivities = (contract) => {
 	return composeByPrefix(TemporalActivitiesPort, WORKFLOW_ACTIVITIES_PREFIX, withUnit);
 };
 //#endregion
-export { ActivityInput, TemporalActivities, TemporalConfig, TemporalConnection, TemporalModule, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, temporal };
+export { ActivityInput, TemporalActivities, TemporalConfig, TemporalConnection, TemporalModule, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities };

package/dist/testing.d.mts

@@ -0,0 +1,64 @@
+import { TestProject } from "vitest/node";
+//#region src/testing.d.ts
+declare module "vitest" {
+  interface ProvidedContext {
+    __BTRAVSTACK_TEMPORAL_ADDRESS__: string;
+  }
+}
+/** Options for {@link temporalServer}. */
+export type TemporalServerOptions = {
+  /**
+   * How long each container may take to report healthy, in milliseconds.
+   * `temporalio/auto-setup` creates its schemas on first boot, which a loaded
+   * Docker host can stretch well past a minute.
+   *
+   * @defaultValue `300_000`
+   */
+  readonly startupTimeoutMs?: number;
+};
+/** The environment a spec spreads into `start`'s `env`: the server, and a namespace of the spec file's own. */
+export type TemporalEnvironment = {
+  readonly TEMPORAL_ADDRESS: string;
+  readonly TEMPORAL_NAMESPACE: string;
+};
+/**
+ * A Vitest `globalSetup`: one PostgreSQL and one `temporalio/auto-setup`
+ * container for the whole run, started through `testcontainers` and stopped
+ * when the run ends. The package's `/testing` entry default-exports it with
+ * the default options, so `globalSetup: ["@btravstack/temporal-worker/testing"]`
+ * is the whole configuration.
+ *
+ * @example
+ * ```ts
+ * // temporal-setup.ts, for a host that needs a longer budget
+ * import { temporalServer } from "@btravstack/temporal-worker/testing";
+ *
+ * export default temporalServer({ startupTimeoutMs: 600_000 });
+ * ```
+ */
+export declare const temporalServer: ({ startupTimeoutMs }?: TemporalServerOptions) => ({ provide }: TestProject) => Promise<() => Promise<void>>;
+declare const _default: ({ provide }: TestProject) => Promise<() => Promise<void>>;
+/**
+ * A file-scoped Vitest fixture answering the {@link TemporalEnvironment} of a
+ * namespace registered for the spec file, on the server {@link temporalServer}
+ * started. The namespace is the isolation boundary: the starter reads its task
+ * queue off the contract, so two spec files polling the same queue are kept
+ * apart by namespace, and nothing is cleaned up — the run's end disposes.
+ *
+ * @example
+ * ```ts
+ * export const it = test.extend<{ temporal: TemporalEnvironment; boot: Boot }>({
+ *   temporal: temporalEnvironment("orders"),
+ *   boot: bootFixture(),
+ * });
+ *
+ * it("fulfils", async ({ temporal, boot }) => {
+ *   const app = boot(OrderWorker, { env: { ...temporal } });
+ * });
+ * ```
+ */
+export declare const temporalEnvironment: (prefix?: string) => [(context: object, use: (environment: TemporalEnvironment) => Promise<void>) => Promise<void>, {
+  scope: "file";
+}];
+//#endregion
+export { _default as default };

package/dist/testing.mjs

@@ -0,0 +1,126 @@
+import { msToTs } from "@temporalio/common";
+import { NativeConnection } from "@temporalio/worker";
+import { randomUUID } from "node:crypto";
+//#region src/testing.ts
+const POSTGRES_IMAGE = "postgres:18.1";
+const TEMPORAL_IMAGE = "temporalio/auto-setup:1.29.1";
+const NAMESPACE_READY_MS = 6e4;
+/**
+* A Vitest `globalSetup`: one PostgreSQL and one `temporalio/auto-setup`
+* container for the whole run, started through `testcontainers` and stopped
+* when the run ends. The package's `/testing` entry default-exports it with
+* the default options, so `globalSetup: ["@btravstack/temporal-worker/testing"]`
+* is the whole configuration.
+*
+* @example
+* ```ts
+* // temporal-setup.ts, for a host that needs a longer budget
+* import { temporalServer } from "@btravstack/temporal-worker/testing";
+*
+* export default temporalServer({ startupTimeoutMs: 600_000 });
+* ```
+*/
+const temporalServer = ({ startupTimeoutMs = 3e5 } = {}) => async ({ provide }) => {
+	const { GenericContainer, Network, Wait } = await import("testcontainers");
+	const healthCheck = {
+		interval: 1e3,
+		retries: Math.ceil(startupTimeoutMs / 1e3),
+		startPeriod: startupTimeoutMs,
+		timeout: 5e3
+	};
+	const password = randomUUID();
+	const started = [];
+	const stopAll = async () => {
+		const failures = [];
+		for (const resource of started.toReversed()) await resource.stop().then(void 0, (failure) => failures.push(failure));
+		return failures;
+	};
+	const teardown = async () => {
+		const failures = await stopAll();
+		if (failures.length > 0) throw new AggregateError(failures, "[temporal-worker] the Temporal test server did not stop cleanly");
+	};
+	try {
+		const network = await new Network().start();
+		started.push(network);
+		started.push(await new GenericContainer(POSTGRES_IMAGE).withNetwork(network).withNetworkAliases("postgres").withEnvironment({
+			POSTGRES_DB: "temporal",
+			POSTGRES_USER: "temporal",
+			POSTGRES_PASSWORD: password
+		}).withHealthCheck({
+			test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U temporal"],
+			...healthCheck
+		}).withWaitStrategy(Wait.forHealthCheck()).withStartupTimeout(startupTimeoutMs).start());
+		const temporal = await new GenericContainer(TEMPORAL_IMAGE).withNetwork(network).withExposedPorts(7233).withEnvironment({
+			DB: "postgres12",
+			DB_PORT: "5432",
+			POSTGRES_SEEDS: "postgres",
+			POSTGRES_USER: "temporal",
+			POSTGRES_PWD: password,
+			BIND_ON_IP: "0.0.0.0",
+			TEMPORAL_BROADCAST_ADDRESS: "127.0.0.1"
+		}).withHealthCheck({
+			test: ["CMD-SHELL", "tctl --address 127.0.0.1:7233 workflow list"],
+			...healthCheck
+		}).withWaitStrategy(Wait.forHealthCheck()).withStartupTimeout(startupTimeoutMs).start();
+		started.push(temporal);
+		provide("__BTRAVSTACK_TEMPORAL_ADDRESS__", `${temporal.getHost()}:${temporal.getMappedPort(7233)}`);
+		return teardown;
+	} catch (cause) {
+		const failures = await stopAll();
+		throw failures.length === 0 ? cause : new AggregateError([cause, ...failures], "[temporal-worker] the Temporal test server failed to start, and what had started did not stop cleanly");
+	}
+};
+var testing_default = temporalServer();
+/**
+* Registering a namespace is not the same as being able to use one: each
+* Temporal service refreshes its namespace registry on its own interval, so a
+* namespace-scoped read is retried until it answers, and its last error is
+* what a namespace that never becomes usable fails with.
+*/
+const registerNamespace = async (address, prefix) => {
+	const { vi } = await import("vitest");
+	const namespace = `${prefix}-${randomUUID()}`;
+	const connection = await NativeConnection.connect({ address });
+	try {
+		await connection.workflowService.registerNamespace({
+			namespace,
+			workflowExecutionRetentionPeriod: msToTs("1 day")
+		});
+		await vi.waitFor(() => connection.workflowService.countWorkflowExecutions({ namespace }), {
+			timeout: NAMESPACE_READY_MS,
+			interval: 250
+		});
+		return namespace;
+	} finally {
+		await connection.close();
+	}
+};
+/**
+* A file-scoped Vitest fixture answering the {@link TemporalEnvironment} of a
+* namespace registered for the spec file, on the server {@link temporalServer}
+* started. The namespace is the isolation boundary: the starter reads its task
+* queue off the contract, so two spec files polling the same queue are kept
+* apart by namespace, and nothing is cleaned up — the run's end disposes.
+*
+* @example
+* ```ts
+* export const it = test.extend<{ temporal: TemporalEnvironment; boot: Boot }>({
+*   temporal: temporalEnvironment("orders"),
+*   boot: bootFixture(),
+* });
+*
+* it("fulfils", async ({ temporal, boot }) => {
+*   const app = boot(OrderWorker, { env: { ...temporal } });
+* });
+* ```
+*/
+const temporalEnvironment = (prefix = "spec") => [async ({}, use) => {
+	const { inject } = await import("vitest");
+	const address = inject("__BTRAVSTACK_TEMPORAL_ADDRESS__");
+	await use({
+		TEMPORAL_ADDRESS: address,
+		TEMPORAL_NAMESPACE: await registerNamespace(address, prefix)
+	});
+}, { scope: "file" }];
+//#endregion
+export { testing_default as default, temporalEnvironment, temporalServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/temporal-worker",
-  "version": "0.32.0",
+  "version": "0.33.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",
@@ -43,14 +43,20 @@
         "types": "./dist/schedule.d.mts",
         "default": "./dist/schedule.mjs"
       }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing.d.mts",
+        "default": "./dist/testing.mjs"
+      }
     }
   },
   "devDependencies": {
-    "@btravstack/config": "0.32.0",
-    "@btravstack/core": "0.32.0",
-    "@btravstack/di": "0.32.0",
+    "@btravstack/config": "0.33.0",
+    "@btravstack/core": "0.33.0",
+    "@btravstack/di": "0.33.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/testing": "0.32.0",
+    "@btravstack/testing": "0.33.0",
     "@btravstack/tsconfig": "0.4.0",
     "@temporal-contract/client": "8.0.0-beta.11",
     "@temporal-contract/contract": "8.0.0-beta.11",
@@ -63,6 +69,7 @@
     "@types/node": "26.6.4",
     "@unthrown/vitest": "5.12.1",
     "@vitest/coverage-v8": "5.0.3",
+    "testcontainers": "12.2.0",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
     "typescript-consumer": "npm:typescript@5.9.3",
@@ -71,28 +78,36 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.32.0",
-    "@btravstack/core": "^0.32.0",
-    "@btravstack/di": "^0.32.0",
+    "@btravstack/config": "^0.33.0",
+    "@btravstack/core": "^0.33.0",
+    "@btravstack/di": "^0.33.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.22.0",
     "@temporalio/common": "^1.22.0",
     "@temporalio/worker": "^1.22.0",
-    "unthrown": "^5.7.0"
+    "testcontainers": "^12.0.0",
+    "unthrown": "^5.7.0",
+    "vitest": ">=3.2.0"
   },
   "peerDependenciesMeta": {
     "@temporal-contract/client": {
       "optional": true
+    },
+    "testcontainers": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "engines": {
     "node": ">=22.22"
   },
   "scripts": {
-    "build": "tsdown src/index.ts src/schedule.ts --format esm --dts --clean",
-    "dev": "tsdown src/index.ts src/schedule.ts --format esm --dts --watch",
+    "build": "tsdown src/index.ts src/schedule.ts src/testing.ts --format esm --dts --clean",
+    "dev": "tsdown src/index.ts src/schedule.ts src/testing.ts --format esm --dts --watch",
     "test": "vitest run --coverage",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json && node ./node_modules/typescript-consumer/bin/tsc --noEmit -p tsconfig.test-d.json"
   }