@btravstack/temporal-worker 0.3.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,172 @@
+# @btravstack/temporal-worker
+
+> The **worker half** of Temporal for [`@btravstack/core`](../core) — starting
+> workflows is a client's job, and belongs to `@temporal-contract/client`. One module
+> providing the runtime, its configuration and its connection; one unit per
+> activity attempt; and a drain that releases the kernel at the **kernel's**
+> deadline, not Temporal's `shutdownForceTime`.
+
+📖 **[Documentation](https://btravstack.github.io/btravstack/how-to/run-a-temporal-worker)** ·
+[Reference](https://btravstack.github.io/btravstack/reference/temporal-worker) ·
+[API Reference](https://btravstack.github.io/btravstack/api/temporal-worker/)
+
+```sh
+pnpm add @btravstack/temporal-worker @btravstack/core @btravstack/config @btravstack/di unthrown \
+  @temporalio/worker @temporalio/activity @temporalio/common \
+  @temporal-contract/worker @temporal-contract/contract
+```
+
+All nine are peer dependencies — install them. Node `>=20`.
+
+## A worked example
+
+<!-- doctest: prelude
+import { defineActivity, defineContract, defineWorkflow } from "@temporal-contract/contract";
+import { workflowsPathFromURL } from "@temporal-contract/worker/worker";
+import { Module } from "@btravstack/di";
+import { PlaceOrder, OrderRepository, Outbox, OrderApplicationModule } from "@btravstack/example-order-application";
+import { OrderPersistenceModule } from "@btravstack/example-order-infrastructure";
+import { TenantId } from "@btravstack/example-order-domain";
+import { observability } from "@btravstack/observability";
+import { z } from "zod";
+
+// The contract this README's worker serves — one workflow, one activity, one
+// modeled contract error.
+const contract = defineContract({
+  taskQueue: "orders",
+  workflows: {
+    placeOrder: defineWorkflow({
+      input: z.object({ tenantId: z.uuidv7(), orderId: z.uuidv7(), quantity: z.number() }),
+      output: z.object({ id: z.uuidv7() }),
+      idempotency: "allow-duplicate",
+      activities: {
+        place: defineActivity({
+          input: z.object({ tenantId: z.uuidv7(), orderId: z.uuidv7(), quantity: z.number() }),
+          output: z.object({ id: z.uuidv7() }),
+          errors: {
+            OrderAlreadyPlaced: { data: z.object({ id: z.uuidv7() }), nonRetryable: true },
+            InvalidOrderId: { data: z.object({ id: z.string() }), nonRetryable: true },
+            InvalidQuantity: { data: z.object({ id: z.uuidv7() }), nonRetryable: true },
+          },
+          activityOptions: { startToCloseTimeout: "30 seconds" },
+        }),
+      },
+    }),
+  },
+});
+
+const AppModule = Module("App")({
+  imports: [OrderApplicationModule, OrderPersistenceModule, observability()],
+  exports: [PlaceOrder, OrderRepository, Outbox, Logger],
+});
+-->
+
+```ts
+import { runMain, Logger } from "@btravstack/core";
+import {
+  TemporalActivities,
+  TemporalModule,
+} from "@btravstack/temporal-worker";
+import { P } from "unthrown";
+
+// The application's half: its activities, as a service built from the use
+// cases it declares — closures over them, no context read at call time — on
+// the starter's own activities port, typed by the contract (a worker serves
+// one activities record, so there is nothing to name).
+const orderActivities = TemporalActivities(contract)(
+  { place: PlaceOrder },
+  {
+    sync: ({ place }) => ({
+      placeOrder: {
+        place: (args, { errors }) =>
+          place
+            .execute(TenantId(args.tenantId), args.orderId, args.quantity)
+            .mapErrCases((matcher) =>
+              matcher
+                .with(P.tag("DuplicateOrder"), (error) =>
+                  errors.OrderAlreadyPlaced({ id: error.id }),
+                )
+                .with(P.tag("InvalidOrderId"), (error) =>
+                  errors.InvalidOrderId({ id: error.id }),
+                )
+                .with(P.tag("InvalidQuantity"), (error) =>
+                  errors.InvalidQuantity({ id: error.id }),
+                ),
+            ),
+      },
+    }),
+  },
+);
+
+// The composition root: a di module, plus the contract, the activities
+// provider and the workflow source — and nothing else to know.
+const OrderWorker = TemporalModule("OrderWorker")({
+  contract,
+  activities: orderActivities,
+  workflows: {
+    workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js"),
+  },
+  imports: [AppModule],
+});
+
+await runMain(OrderWorker);
+```
+
+`TemporalModule` imports the starter — `TemporalRuntime`, `TemporalConfig`
+bound from `TEMPORAL_ADDRESS` (default `127.0.0.1:7233`) and
+`TEMPORAL_NAMESPACE` (default `default`), `TemporalConnection` opened as a
+resource of the graph and closed on every exit path — provides the activities
+and exports the runtime port. A service that will not answer is a modeled
+`TemporalUnreachable`, exit `1`; the starter calls `declareActivitiesHandler`
+itself, inside its own error qualifier, so a contract it cannot satisfy is a
+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)({ name: Dep }, arm)` 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
+array must cover every key the contract declares, and each piece's own port
+must still be discharged (`provides`), since the composed provider's deps are
+the pieces' ports, not what they close over. Two slices claiming one key are
+di's duplicate-provider defect at build, which is the point: a workflow's
+activities belong to exactly one slice.
+
+## 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:
+
+| Option        | What it is                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| `contract`    | the `temporal-contract` contract; the task queue this worker polls is read off it                      |
+| `activities`  | the activities provider — what `TemporalActivities(contract)(...)` returns for this contract           |
+| `workflows`   | where the sandbox's code comes from: `{ workflowsPath }` or `{ workflowBundle }`                       |
+| `address`     | pins the service instead of reading `TEMPORAL_ADDRESS`                                                 |
+| `namespace`   | pins the namespace instead of reading `TEMPORAL_NAMESPACE`                                             |
+| `gracePeriod` | Temporal's `shutdownGraceTime`, a `Duration` (default `"10 seconds"`)                                  |
+| `forceAfter`  | Temporal's `shutdownForceTime`, a `Duration` (default `"15 seconds"`) — keep it under `drainTimeoutMs` |
+
+The full table — required/optional, defaults, and the reasoning — lives on
+[the reference page](https://btravstack.github.io/btravstack/reference/temporal-worker),
+which is this list's one detailed home.
+
+## The drain
+
+`worker.shutdown()` stops polling at once, but `run()` resolves only when the
+last in-flight activity has finished — on Temporal's own `shutdownForceTime`.
+`Serving.drain(signal)` races that wait against the kernel's deadline and
+returns at whichever comes first: the kernel gets its thread back on time, the
+work is reported `abandoned`, and the worker keeps winding down on Temporal's
+clock until the process exits. `@temporalio/worker` exposes no public forced
+shutdown, so "stop waiting" is the escalation. `Result` → activity failure is
+`declareActivitiesHandler`'s and is deliberately not duplicated here. The rest
+is on the [documentation site](https://btravstack.github.io/btravstack/reference/temporal-worker).
+
+## License
+
+[MIT](./LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -0,0 +1,261 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_di = require("@btravstack/di");
+let _btravstack_config = require("@btravstack/config");
+let _btravstack_core = require("@btravstack/core");
+let _temporal_contract_worker_activity = require("@temporal-contract/worker/activity");
+let _temporalio_worker = require("@temporalio/worker");
+let unthrown = require("unthrown");
+let _temporalio_activity = require("@temporalio/activity");
+//#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.
+*
+* **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
+* own `Context.current().cancellationSignal` is a DIFFERENT clock, so the two
+* are honoured together rather than one standing in for the other.
+*
+* No `Result`-unwrapping boundary, deliberately: `declareActivitiesHandler` owns
+* the mapping from a settled `Result` to an activity failure.
+*/
+const activityUnits = (host) => (_invocation, next) => host.run(metaFor(), () => next());
+/**
+* `UnitMeta.id` must be unique per unit, and a workflow id is **not** one: an
+* activity is retried under the same execution. A task token identifies one
+* attempt, so its uniqueness is Temporal's guarantee rather than ours.
+*
+* The workflow id becomes the `traceId` — minted outside this process and steady
+* across every retry, so all attempts join up in a log. An activity with no
+* workflow falls back to the activity id.
+*/
+const metaFor = () => {
+	const info = (0, _temporalio_activity.activityInfo)();
+	return {
+		kind: "activity",
+		id: info.base64TaskToken,
+		traceId: info.workflowExecution?.workflowId ?? info.activityId
+	};
+};
+//#endregion
+//#region src/temporal-runtime.ts
+/**
+* Where the Temporal service is, as a service: `temporal()` binds it from the
+* environment — `TEMPORAL_ADDRESS` (default `127.0.0.1:7233`) and
+* `TEMPORAL_NAMESPACE` (default `default`) — unless pinned, and anything else
+* in the graph may read it.
+*/
+var TemporalConfig = class extends (0, _btravstack_di.Port)("TemporalConfig") {};
+/**
+* The connection, as a resource of the graph: di opens it with the scope and
+* closes it on every exit path, startup failure included.
+*/
+var TemporalConnection = class extends (0, _btravstack_di.Port)("TemporalConnection") {};
+/**
+* The service at `TemporalConfig.address` did not answer. Modeled rather than
+* left a defect because an operator *can* act on it — the address is wrong or
+* the service is down, and neither is a bug in this code — so `runMain` exits
+* `1`, a startup `Err`, not the `70` a defect earns.
+*/
+var TemporalUnreachable = class extends (0, unthrown.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. */
+var TemporalRuntime = class extends _btravstack_core.RuntimePort {};
+/**
+* The activities' port — one id, the starter's own, which an application never
+* names. Generic at the value level (one `Port(...)` call, so no duplicate-id
+* warning however many contracts instantiate it) and fixed per contract at the
+* type level through `ActivitiesPortOf<C>`, so a provider built for one contract
+* cannot be handed to a module declaring another. Exported for this package's
+* tests, not from `index.ts`.
+*/
+const TemporalActivitiesPort = (0, _btravstack_di.Port)("TemporalActivities");
+const DEFAULT_GRACE = "10 seconds";
+const DEFAULT_FORCE = "15 seconds";
+/**
+* The Temporal starter: a module providing the runtime, its configuration
+* (bound from `TEMPORAL_ADDRESS` / `TEMPORAL_NAMESPACE` 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.
+*
+* With both configuration fields pinned the module reads nothing from the
+* environment; pin only one and the other still comes from it.
+*/
+const temporal = (options) => {
+	const { address, namespace } = options;
+	const activities = TemporalActivitiesPort;
+	const config = address !== void 0 && namespace !== void 0 ? (0, _btravstack_di.Provider)(TemporalConfig)({ value: {
+		address,
+		namespace
+	} }) : _btravstack_config.Config.provider(TemporalConfig)(_btravstack_config.Config.object({
+		address: _btravstack_config.Config.pinned(address, _btravstack_config.Config.string("TEMPORAL_ADDRESS", { default: "127.0.0.1:7233" })),
+		namespace: _btravstack_config.Config.pinned(namespace, _btravstack_config.Config.string("TEMPORAL_NAMESPACE", { default: "default" }))
+	}));
+	return (0, _btravstack_di.Module)("Temporal")({
+		needs: [_btravstack_config.Env, activities],
+		provides: [
+			config,
+			(0, _btravstack_di.Provider)(TemporalConnection)({ config: TemporalConfig }, {
+				acquire: ({ config: bound }) => (0, unthrown.fromPromise)(_temporalio_worker.NativeConnection.connect({ address: bound.address }), (cause) => new TemporalUnreachable({
+					address: bound.address,
+					cause
+				})),
+				release: (connection) => connection.close().catch((cause) => heldByWorker(cause) ? void 0 : Promise.reject(cause))
+			}),
+			(0, _btravstack_di.Provider)(TemporalRuntime)({
+				connection: TemporalConnection,
+				config: TemporalConfig,
+				activities
+			}, { sync: ({ connection, config: bound, activities: impls }) => ({
+				name: "temporal",
+				resolves: [],
+				start: (host) => createWorker(host, connection, bound, impls, options)
+			}) })
+		],
+		exports: [
+			TemporalRuntime,
+			TemporalConfig,
+			TemporalConnection
+		]
+	});
+};
+const startFailed = (cause) => new _btravstack_core.RuntimeStartFailed({
+	runtime: "temporal",
+	cause
+});
+const heldByWorker = (cause) => cause instanceof Error && cause.name === "IllegalStateError";
+const createWorker = (host, connection, config, activities, options) => {
+	const { taskQueue } = options.contract;
+	const { namespace } = config;
+	return (0, unthrown.fromThrowable)(() => (0, _temporal_contract_worker_activity.declareActivitiesHandler)({
+		contract: options.contract,
+		middleware: activityUnits(host),
+		activities
+	}), startFailed)().toAsync().flatMap((handler) => (0, unthrown.fromPromise)(_temporalio_worker.Worker.create({
+		connection,
+		namespace,
+		taskQueue,
+		...options.workflows,
+		activities: handler,
+		shutdownGraceTime: options.gracePeriod ?? DEFAULT_GRACE,
+		shutdownForceTime: options.forceAfter ?? DEFAULT_FORCE
+	}), startFailed)).map((worker) => poll(worker, taskQueue, namespace));
+};
+const poll = (worker, taskQueue, namespace) => {
+	const running = (0, unthrown.fromSafePromise)(worker.run());
+	const stopPolling = () => {
+		if (worker.getState() === "RUNNING") worker.shutdown();
+	};
+	let deadline;
+	const stopped = () => deadline === void 0 ? running : (0, _btravstack_core.releasedBy)(deadline, running);
+	return {
+		info: {
+			taskQueue,
+			namespace
+		},
+		drain: (signal) => {
+			deadline = signal;
+			stopPolling();
+			return stopped();
+		},
+		stop: () => {
+			stopPolling();
+			return stopped();
+		}
+	};
+};
+//#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 (0, _btravstack_di.Port)(`${WORKFLOW_ACTIVITIES_PREFIX}${key}`) {};
+	return (0, _btravstack_di.Provider)(port);
+};
+//#endregion
+//#region src/temporal-module.ts
+/**
+* `Module(name)({...})` for a Temporal worker deployment: everything a di module
+* takes, plus the contract, the activities provider and the workflow source. The
+* sugar imports the starter, provides the activities and exports
+* `TemporalRuntime`, handing back exactly the module `Module(...)` would have
+* declared over the augmented tuples.
+*
+* ```ts
+* export const OrderTemporalWorker = TemporalModule("OrderTemporalWorker")({
+*   contract: orderContract,
+*   activities: orderActivities,
+*   workflows: { workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js") },
+*   imports: [OrderApplicationModule, OrderPersistenceModule, FulfillmentModule],
+* });
+* await runMain(OrderTemporalWorker);
+* ```
+*/
+const TemporalModule = (name) => (options) => {
+	const { contract, activities, workflows, address, namespace, gracePeriod, forceAfter } = options;
+	const imports = options.imports ?? [];
+	const provides = options.provides ?? [];
+	const exports = options.exports ?? [];
+	const starter = temporal({
+		contract,
+		workflows,
+		...address === void 0 ? {} : { address },
+		...namespace === void 0 ? {} : { namespace },
+		...gracePeriod === void 0 ? {} : { gracePeriod },
+		...forceAfter === void 0 ? {} : { forceAfter }
+	});
+	return (0, _btravstack_di.Module)(name)({
+		imports: [...imports, starter],
+		provides: [activities, ...provides],
+		exports: [TemporalRuntime, ...exports],
+		needs: options.needs ?? []
+	});
+};
+/**
+* The activities as a provider, from the contract. Three call forms, one port.
+*
+* ```ts
+* TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+* TemporalActivities(orderContract)([fulfillOrder, chargeOrder])
+* ```
+*
+* The first two are di's own `Provider(port)` on the starter's activities port
+* typed for the contract. The third 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 = (0, _btravstack_di.Provider)(TemporalActivitiesPort);
+	const compose = (pieces) => build(Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(27), piece.port])), { sync: (services) => services });
+	return ((first, second) => second === void 0 && Array.isArray(first) ? compose(first) : build(first, second));
+};
+//#endregion
+exports.TemporalActivities = TemporalActivities;
+exports.TemporalConfig = TemporalConfig;
+exports.TemporalConnection = TemporalConnection;
+exports.TemporalModule = TemporalModule;
+exports.TemporalRuntime = TemporalRuntime;
+exports.TemporalUnreachable = TemporalUnreachable;
+exports.TemporalWorkflowActivities = TemporalWorkflowActivities;
+exports.temporal = temporal;

package/dist/index.d.cts

@@ -0,0 +1,219 @@
+import { ConfigInvalid, Env } from "@btravstack/config";
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope } from "@btravstack/di";
+import { ContractDefinition } from "@temporal-contract/contract";
+import { Duration } from "@temporalio/common";
+import { Runtime, RuntimePort } from "@btravstack/core";
+import { DeclareActivitiesHandlerOptions } from "@temporal-contract/worker/activity";
+import { NativeConnection, WorkflowBundleWithSourceMap } from "@temporalio/worker";
+//#region src/temporal-runtime.d.ts
+/** What the worker publishes once it is polling, read back through `RunningApp.runtimeInfo()`. */
+type TemporalInfo = {
+  readonly taskQueue: string;
+  readonly namespace: string;
+};
+/**
+ * Where the workflow sandbox's code comes from. Two arms because the two
+ * callers genuinely differ: a process points at the module and lets Temporal
+ * bundle it, while a spec hands over a bundle it built and memoised once —
+ * bundling per test is the most expensive thing a suite does.
+ */
+type WorkflowSource = {
+  readonly workflowsPath: string;
+} | {
+  readonly workflowBundle: WorkflowBundleWithSourceMap;
+};
+declare const TemporalConfig_base: import("@btravstack/di").PortClass<"TemporalConfig">;
+/**
+ * Where the Temporal service is, as a service: `temporal()` binds it from the
+ * environment — `TEMPORAL_ADDRESS` (default `127.0.0.1:7233`) and
+ * `TEMPORAL_NAMESPACE` (default `default`) — unless pinned, and anything else
+ * in the graph may read it.
+ */
+declare class TemporalConfig extends TemporalConfig_base<{
+  readonly address: string;
+  readonly namespace: string;
+}> {}
+declare const TemporalConnection_base: import("@btravstack/di").PortClass<"TemporalConnection">;
+/**
+ * The connection, as a resource of the graph: di opens it with the scope and
+ * closes it on every exit path, startup failure included.
+ */
+declare class TemporalConnection extends TemporalConnection_base<NativeConnection> {}
+declare const TemporalUnreachable_base: import("unthrown").TaggedErrorConstructor<"TemporalUnreachable">;
+/**
+ * The service at `TemporalConfig.address` did not answer. Modeled rather than
+ * left a defect because an operator *can* act on it — the address is wrong or
+ * the service is down, and neither is a bug in this code — so `runMain` exits
+ * `1`, a startup `Err`, not the `70` a defect earns.
+ */
+declare class TemporalUnreachable extends TemporalUnreachable_base<{
+  readonly address: string;
+  readonly cause: unknown;
+}> {
+  message: string;
+}
+/** 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"];
+/** 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. */
+type ActivitiesInstanceOf<C extends ContractDefinition> = PortInstance<"TemporalActivities", ActivitiesOf<C>>;
+type TemporalOptions<C extends ContractDefinition> = {
+  /**
+   * The contract; the task queue this worker polls is read off it, and the
+   * activities port is typed by it. The starter calls
+   * `declareActivitiesHandler` itself, with its unit middleware in place.
+   */
+  readonly contract: C;
+  readonly workflows: WorkflowSource;
+  /** Pins `TemporalConfig.address` instead of reading `TEMPORAL_ADDRESS`. */
+  readonly address?: string;
+  /** Pins `TemporalConfig.namespace` instead of reading `TEMPORAL_NAMESPACE`. */
+  readonly namespace?: string;
+  /** Temporal's `shutdownForceTime`. Default `15 seconds`. Keep it at or below the kernel's `drainTimeoutMs`. */
+  readonly forceAfter?: Duration;
+  /** Temporal's `shutdownGraceTime`. Default `10 seconds`. */
+  readonly gracePeriod?: Duration;
+};
+type Provided = TemporalRuntime | TemporalConfig | TemporalConnection;
+/**
+ * The Temporal starter: a module providing the runtime, its configuration
+ * (bound from `TEMPORAL_ADDRESS` / `TEMPORAL_NAMESPACE` 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.
+ *
+ * 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>>>;
+//#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>>;
+/** 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>];
+/** 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[]> = {
+  /** The `temporal-contract` contract; the task queue this worker polls is read off it. */
+  readonly contract: C;
+  /** The application's activity implementations — what `TemporalActivities(contract)(…)` returns. */
+  readonly activities: Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>;
+  readonly workflows: WorkflowSource;
+  /** Pins `TemporalConfig.address` instead of reading `TEMPORAL_ADDRESS`. */
+  readonly address?: string;
+  /** Pins `TemporalConfig.namespace` instead of reading `TEMPORAL_NAMESPACE`. */
+  readonly namespace?: string;
+  /** Temporal's `shutdownGraceTime`. Default `10 seconds`. */
+  readonly gracePeriod?: Duration;
+  /** Temporal's `shutdownForceTime`. Default `15 seconds`. Keep it at or below the kernel's `drainTimeoutMs`. */
+  readonly forceAfter?: Duration;
+  readonly imports?: I;
+  readonly provides?: P;
+  /** The application's own exports; `TemporalRuntime` is added, since `start` resolves it. */
+  readonly exports?: X;
+  /**
+   * What this root's OWN providers expect from outside. di's gate is re-stated
+   * over the augmented tuples below, so forgetting one is an error at THIS call.
+   */
+  readonly needs?: N;
+} & NeedsGate<Imports<I, C>, Provides<P, C, ActivitiesError, ActivitiesNeeds>, N>;
+/**
+ * `Module(name)({...})` for a Temporal worker deployment: everything a di module
+ * takes, plus the contract, the activities provider and the workflow source. The
+ * sugar imports the starter, provides the activities and exports
+ * `TemporalRuntime`, handing back exactly the module `Module(...)` would have
+ * declared over the augmented tuples.
+ *
+ * ```ts
+ * export const OrderTemporalWorker = TemporalModule("OrderTemporalWorker")({
+ *   contract: orderContract,
+ *   activities: orderActivities,
+ *   workflows: { workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js") },
+ *   imports: [OrderApplicationModule, OrderPersistenceModule, FulfillmentModule],
+ * });
+ * 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]>>;
+/** 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>;
+}; }[ActivitiesKeyOf<C>];
+/** The key a piece carries, read back off its port id. */
+type KeyOfPiece<P> = P extends {
+  readonly port: {
+    readonly portId: `${typeof WORKFLOW_ACTIVITIES_PREFIX}${infer K}`;
+  };
+} ? K : never;
+/** The record's top-level keys no piece in `T` covers. */
+type Uncovered<C extends ContractDefinition, T extends readonly PieceOf<C>[]> = Exclude<ActivitiesKeyOf<C>, KeyOfPiece<T[number]>>;
+/**
+ * The composing arm. Declared LAST in the intersection below on purpose:
+ * TypeScript reports the last overload's failure, so a non-covering array is
+ * refused against the `"UNCOVERED ACTIVITIES — …"` marker rather than degrading
+ * to di's `Qualification`, which names nothing.
+ *
+ * The marker is a sentence rather than a bare label because it prints last,
+ * after the caller's own several-hundred-character piece type.
+ */
+type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : readonly ["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>;
+};
+/**
+ * The activities as a provider, from the contract. Three call forms, one port.
+ *
+ * ```ts
+ * TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+ * TemporalActivities(orderContract)([fulfillOrder, chargeOrder])
+ * ```
+ *
+ * The first two are di's own `Provider(port)` on the starter's activities port
+ * typed for the contract. The third 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>;
+//#endregion
+export { type ActivitiesInstanceOf, type ActivitiesPortOf, TemporalActivities, TemporalConfig, TemporalConnection, type TemporalInfo, TemporalModule, type TemporalModuleOptions, type TemporalOptions, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, type WorkflowActivitiesPortOf, type WorkflowSource, temporal };

package/dist/index.d.mts

@@ -0,0 +1,219 @@
+import { AnyModule, AnyPort, AnyProvider, Exportable, Module, NeedsGate, PortClassOf, PortInstance, Provider, Scope } from "@btravstack/di";
+import { ConfigInvalid, Env } from "@btravstack/config";
+import { Runtime, RuntimePort } from "@btravstack/core";
+import { DeclareActivitiesHandlerOptions } from "@temporal-contract/worker/activity";
+import { NativeConnection, WorkflowBundleWithSourceMap } from "@temporalio/worker";
+import { ContractDefinition } from "@temporal-contract/contract";
+import { Duration } from "@temporalio/common";
+//#region src/temporal-runtime.d.ts
+/** What the worker publishes once it is polling, read back through `RunningApp.runtimeInfo()`. */
+type TemporalInfo = {
+  readonly taskQueue: string;
+  readonly namespace: string;
+};
+/**
+ * Where the workflow sandbox's code comes from. Two arms because the two
+ * callers genuinely differ: a process points at the module and lets Temporal
+ * bundle it, while a spec hands over a bundle it built and memoised once —
+ * bundling per test is the most expensive thing a suite does.
+ */
+type WorkflowSource = {
+  readonly workflowsPath: string;
+} | {
+  readonly workflowBundle: WorkflowBundleWithSourceMap;
+};
+declare const TemporalConfig_base: import("@btravstack/di").PortClass<"TemporalConfig">;
+/**
+ * Where the Temporal service is, as a service: `temporal()` binds it from the
+ * environment — `TEMPORAL_ADDRESS` (default `127.0.0.1:7233`) and
+ * `TEMPORAL_NAMESPACE` (default `default`) — unless pinned, and anything else
+ * in the graph may read it.
+ */
+declare class TemporalConfig extends TemporalConfig_base<{
+  readonly address: string;
+  readonly namespace: string;
+}> {}
+declare const TemporalConnection_base: import("@btravstack/di").PortClass<"TemporalConnection">;
+/**
+ * The connection, as a resource of the graph: di opens it with the scope and
+ * closes it on every exit path, startup failure included.
+ */
+declare class TemporalConnection extends TemporalConnection_base<NativeConnection> {}
+declare const TemporalUnreachable_base: import("unthrown").TaggedErrorConstructor<"TemporalUnreachable">;
+/**
+ * The service at `TemporalConfig.address` did not answer. Modeled rather than
+ * left a defect because an operator *can* act on it — the address is wrong or
+ * the service is down, and neither is a bug in this code — so `runMain` exits
+ * `1`, a startup `Err`, not the `70` a defect earns.
+ */
+declare class TemporalUnreachable extends TemporalUnreachable_base<{
+  readonly address: string;
+  readonly cause: unknown;
+}> {
+  message: string;
+}
+/** 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"];
+/** 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. */
+type ActivitiesInstanceOf<C extends ContractDefinition> = PortInstance<"TemporalActivities", ActivitiesOf<C>>;
+type TemporalOptions<C extends ContractDefinition> = {
+  /**
+   * The contract; the task queue this worker polls is read off it, and the
+   * activities port is typed by it. The starter calls
+   * `declareActivitiesHandler` itself, with its unit middleware in place.
+   */
+  readonly contract: C;
+  readonly workflows: WorkflowSource;
+  /** Pins `TemporalConfig.address` instead of reading `TEMPORAL_ADDRESS`. */
+  readonly address?: string;
+  /** Pins `TemporalConfig.namespace` instead of reading `TEMPORAL_NAMESPACE`. */
+  readonly namespace?: string;
+  /** Temporal's `shutdownForceTime`. Default `15 seconds`. Keep it at or below the kernel's `drainTimeoutMs`. */
+  readonly forceAfter?: Duration;
+  /** Temporal's `shutdownGraceTime`. Default `10 seconds`. */
+  readonly gracePeriod?: Duration;
+};
+type Provided = TemporalRuntime | TemporalConfig | TemporalConnection;
+/**
+ * The Temporal starter: a module providing the runtime, its configuration
+ * (bound from `TEMPORAL_ADDRESS` / `TEMPORAL_NAMESPACE` 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.
+ *
+ * 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>>>;
+//#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>>;
+/** 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>];
+/** 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[]> = {
+  /** The `temporal-contract` contract; the task queue this worker polls is read off it. */
+  readonly contract: C;
+  /** The application's activity implementations — what `TemporalActivities(contract)(…)` returns. */
+  readonly activities: Provider<ActivitiesInstanceOf<C>, ActivitiesError, ActivitiesNeeds>;
+  readonly workflows: WorkflowSource;
+  /** Pins `TemporalConfig.address` instead of reading `TEMPORAL_ADDRESS`. */
+  readonly address?: string;
+  /** Pins `TemporalConfig.namespace` instead of reading `TEMPORAL_NAMESPACE`. */
+  readonly namespace?: string;
+  /** Temporal's `shutdownGraceTime`. Default `10 seconds`. */
+  readonly gracePeriod?: Duration;
+  /** Temporal's `shutdownForceTime`. Default `15 seconds`. Keep it at or below the kernel's `drainTimeoutMs`. */
+  readonly forceAfter?: Duration;
+  readonly imports?: I;
+  readonly provides?: P;
+  /** The application's own exports; `TemporalRuntime` is added, since `start` resolves it. */
+  readonly exports?: X;
+  /**
+   * What this root's OWN providers expect from outside. di's gate is re-stated
+   * over the augmented tuples below, so forgetting one is an error at THIS call.
+   */
+  readonly needs?: N;
+} & NeedsGate<Imports<I, C>, Provides<P, C, ActivitiesError, ActivitiesNeeds>, N>;
+/**
+ * `Module(name)({...})` for a Temporal worker deployment: everything a di module
+ * takes, plus the contract, the activities provider and the workflow source. The
+ * sugar imports the starter, provides the activities and exports
+ * `TemporalRuntime`, handing back exactly the module `Module(...)` would have
+ * declared over the augmented tuples.
+ *
+ * ```ts
+ * export const OrderTemporalWorker = TemporalModule("OrderTemporalWorker")({
+ *   contract: orderContract,
+ *   activities: orderActivities,
+ *   workflows: { workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js") },
+ *   imports: [OrderApplicationModule, OrderPersistenceModule, FulfillmentModule],
+ * });
+ * 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]>>;
+/** 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>;
+}; }[ActivitiesKeyOf<C>];
+/** The key a piece carries, read back off its port id. */
+type KeyOfPiece<P> = P extends {
+  readonly port: {
+    readonly portId: `${typeof WORKFLOW_ACTIVITIES_PREFIX}${infer K}`;
+  };
+} ? K : never;
+/** The record's top-level keys no piece in `T` covers. */
+type Uncovered<C extends ContractDefinition, T extends readonly PieceOf<C>[]> = Exclude<ActivitiesKeyOf<C>, KeyOfPiece<T[number]>>;
+/**
+ * The composing arm. Declared LAST in the intersection below on purpose:
+ * TypeScript reports the last overload's failure, so a non-covering array is
+ * refused against the `"UNCOVERED ACTIVITIES — …"` marker rather than degrading
+ * to di's `Qualification`, which names nothing.
+ *
+ * The marker is a sentence rather than a bare label because it prints last,
+ * after the caller's own several-hundred-character piece type.
+ */
+type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : readonly ["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>;
+};
+/**
+ * The activities as a provider, from the contract. Three call forms, one port.
+ *
+ * ```ts
+ * TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+ * TemporalActivities(orderContract)([fulfillOrder, chargeOrder])
+ * ```
+ *
+ * The first two are di's own `Provider(port)` on the starter's activities port
+ * typed for the contract. The third 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>;
+//#endregion
+export { type ActivitiesInstanceOf, type ActivitiesPortOf, TemporalActivities, TemporalConfig, TemporalConnection, type TemporalInfo, TemporalModule, type TemporalModuleOptions, type TemporalOptions, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, type WorkflowActivitiesPortOf, type WorkflowSource, temporal };

package/dist/index.mjs

@@ -0,0 +1,253 @@
+import { Module, Port, Provider } from "@btravstack/di";
+import { Config, Env } from "@btravstack/config";
+import { RuntimePort, RuntimeStartFailed, releasedBy } from "@btravstack/core";
+import { declareActivitiesHandler } from "@temporal-contract/worker/activity";
+import { NativeConnection, Worker } from "@temporalio/worker";
+import { TaggedError, fromPromise, fromSafePromise, fromThrowable } from "unthrown";
+import { activityInfo } from "@temporalio/activity";
+//#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.
+*
+* **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
+* own `Context.current().cancellationSignal` is a DIFFERENT clock, so the two
+* are honoured together rather than one standing in for the other.
+*
+* No `Result`-unwrapping boundary, deliberately: `declareActivitiesHandler` owns
+* the mapping from a settled `Result` to an activity failure.
+*/
+const activityUnits = (host) => (_invocation, next) => host.run(metaFor(), () => next());
+/**
+* `UnitMeta.id` must be unique per unit, and a workflow id is **not** one: an
+* activity is retried under the same execution. A task token identifies one
+* attempt, so its uniqueness is Temporal's guarantee rather than ours.
+*
+* The workflow id becomes the `traceId` — minted outside this process and steady
+* across every retry, so all attempts join up in a log. An activity with no
+* workflow falls back to the activity id.
+*/
+const metaFor = () => {
+	const info = activityInfo();
+	return {
+		kind: "activity",
+		id: info.base64TaskToken,
+		traceId: info.workflowExecution?.workflowId ?? info.activityId
+	};
+};
+//#endregion
+//#region src/temporal-runtime.ts
+/**
+* Where the Temporal service is, as a service: `temporal()` binds it from the
+* environment — `TEMPORAL_ADDRESS` (default `127.0.0.1:7233`) and
+* `TEMPORAL_NAMESPACE` (default `default`) — unless pinned, and anything else
+* in the graph may read it.
+*/
+var TemporalConfig = class extends Port("TemporalConfig") {};
+/**
+* The connection, as a resource of the graph: di opens it with the scope and
+* closes it on every exit path, startup failure included.
+*/
+var TemporalConnection = class extends Port("TemporalConnection") {};
+/**
+* The service at `TemporalConfig.address` did not answer. Modeled rather than
+* left a defect because an operator *can* act on it — the address is wrong or
+* the service is down, and neither is a bug in this code — so `runMain` exits
+* `1`, a startup `Err`, not the `70` a defect earns.
+*/
+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. */
+var TemporalRuntime = class extends RuntimePort {};
+/**
+* The activities' port — one id, the starter's own, which an application never
+* names. Generic at the value level (one `Port(...)` call, so no duplicate-id
+* warning however many contracts instantiate it) and fixed per contract at the
+* type level through `ActivitiesPortOf<C>`, so a provider built for one contract
+* cannot be handed to a module declaring another. Exported for this package's
+* tests, not from `index.ts`.
+*/
+const TemporalActivitiesPort = Port("TemporalActivities");
+const DEFAULT_GRACE = "10 seconds";
+const DEFAULT_FORCE = "15 seconds";
+/**
+* The Temporal starter: a module providing the runtime, its configuration
+* (bound from `TEMPORAL_ADDRESS` / `TEMPORAL_NAMESPACE` 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.
+*
+* With both configuration fields pinned the module reads nothing from the
+* environment; pin only one and the other still comes from it.
+*/
+const temporal = (options) => {
+	const { address, namespace } = options;
+	const activities = TemporalActivitiesPort;
+	const config = address !== void 0 && namespace !== void 0 ? Provider(TemporalConfig)({ value: {
+		address,
+		namespace
+	} }) : Config.provider(TemporalConfig)(Config.object({
+		address: Config.pinned(address, Config.string("TEMPORAL_ADDRESS", { default: "127.0.0.1:7233" })),
+		namespace: Config.pinned(namespace, Config.string("TEMPORAL_NAMESPACE", { default: "default" }))
+	}));
+	return Module("Temporal")({
+		needs: [Env, activities],
+		provides: [
+			config,
+			Provider(TemporalConnection)({ config: TemporalConfig }, {
+				acquire: ({ config: bound }) => fromPromise(NativeConnection.connect({ address: bound.address }), (cause) => new TemporalUnreachable({
+					address: bound.address,
+					cause
+				})),
+				release: (connection) => connection.close().catch((cause) => heldByWorker(cause) ? void 0 : Promise.reject(cause))
+			}),
+			Provider(TemporalRuntime)({
+				connection: TemporalConnection,
+				config: TemporalConfig,
+				activities
+			}, { sync: ({ connection, config: bound, activities: impls }) => ({
+				name: "temporal",
+				resolves: [],
+				start: (host) => createWorker(host, connection, bound, impls, options)
+			}) })
+		],
+		exports: [
+			TemporalRuntime,
+			TemporalConfig,
+			TemporalConnection
+		]
+	});
+};
+const startFailed = (cause) => new RuntimeStartFailed({
+	runtime: "temporal",
+	cause
+});
+const heldByWorker = (cause) => cause instanceof Error && cause.name === "IllegalStateError";
+const createWorker = (host, connection, config, activities, options) => {
+	const { taskQueue } = options.contract;
+	const { namespace } = config;
+	return fromThrowable(() => declareActivitiesHandler({
+		contract: options.contract,
+		middleware: activityUnits(host),
+		activities
+	}), startFailed)().toAsync().flatMap((handler) => fromPromise(Worker.create({
+		connection,
+		namespace,
+		taskQueue,
+		...options.workflows,
+		activities: handler,
+		shutdownGraceTime: options.gracePeriod ?? DEFAULT_GRACE,
+		shutdownForceTime: options.forceAfter ?? DEFAULT_FORCE
+	}), startFailed)).map((worker) => poll(worker, taskQueue, namespace));
+};
+const poll = (worker, taskQueue, namespace) => {
+	const running = fromSafePromise(worker.run());
+	const stopPolling = () => {
+		if (worker.getState() === "RUNNING") worker.shutdown();
+	};
+	let deadline;
+	const stopped = () => deadline === void 0 ? running : releasedBy(deadline, running);
+	return {
+		info: {
+			taskQueue,
+			namespace
+		},
+		drain: (signal) => {
+			deadline = signal;
+			stopPolling();
+			return stopped();
+		},
+		stop: () => {
+			stopPolling();
+			return stopped();
+		}
+	};
+};
+//#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
+* takes, plus the contract, the activities provider and the workflow source. The
+* sugar imports the starter, provides the activities and exports
+* `TemporalRuntime`, handing back exactly the module `Module(...)` would have
+* declared over the augmented tuples.
+*
+* ```ts
+* export const OrderTemporalWorker = TemporalModule("OrderTemporalWorker")({
+*   contract: orderContract,
+*   activities: orderActivities,
+*   workflows: { workflowsPath: workflowsPathFromURL(import.meta.url, "./workflows.js") },
+*   imports: [OrderApplicationModule, OrderPersistenceModule, FulfillmentModule],
+* });
+* await runMain(OrderTemporalWorker);
+* ```
+*/
+const TemporalModule = (name) => (options) => {
+	const { contract, activities, workflows, address, namespace, gracePeriod, forceAfter } = options;
+	const imports = options.imports ?? [];
+	const provides = options.provides ?? [];
+	const exports = options.exports ?? [];
+	const starter = temporal({
+		contract,
+		workflows,
+		...address === void 0 ? {} : { address },
+		...namespace === void 0 ? {} : { namespace },
+		...gracePeriod === void 0 ? {} : { gracePeriod },
+		...forceAfter === void 0 ? {} : { forceAfter }
+	});
+	return Module(name)({
+		imports: [...imports, starter],
+		provides: [activities, ...provides],
+		exports: [TemporalRuntime, ...exports],
+		needs: options.needs ?? []
+	});
+};
+/**
+* The activities as a provider, from the contract. Three call forms, one port.
+*
+* ```ts
+* TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+* TemporalActivities(orderContract)([fulfillOrder, chargeOrder])
+* ```
+*
+* The first two are di's own `Provider(port)` on the starter's activities port
+* typed for the contract. The third 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);
+	const compose = (pieces) => build(Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(27), piece.port])), { sync: (services) => services });
+	return ((first, second) => second === void 0 && Array.isArray(first) ? compose(first) : build(first, second));
+};
+//#endregion
+export { TemporalActivities, TemporalConfig, TemporalConnection, TemporalModule, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, temporal };

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@btravstack/temporal-worker",
+  "version": "0.3.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",
+    "lifecycle",
+    "runtime",
+    "temporal",
+    "typescript",
+    "unthrown",
+    "worker"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/temporal-worker"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/tsconfig": "0.2.0",
+    "@temporal-contract/contract": "8.0.0-beta.5",
+    "@temporal-contract/worker": "8.0.0-beta.5",
+    "@temporalio/activity": "1.22.0",
+    "@temporalio/client": "1.22.0",
+    "@temporalio/common": "1.22.0",
+    "@temporalio/worker": "1.22.0",
+    "@temporalio/workflow": "1.22.0",
+    "@types/node": "26.2.0",
+    "@unthrown/vitest": "5.7.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "unthrown": "5.7.0",
+    "vitest": "4.1.11",
+    "zod": "4.4.3",
+    "@btravstack/core": "0.3.0",
+    "@btravstack/di": "0.3.0",
+    "@btravstack/testing": "0.3.0",
+    "@btravstack/config": "0.3.0",
+    "@btravstack/internal-test-infra": "0.0.0"
+  },
+  "peerDependencies": {
+    "@temporal-contract/contract": "^8.0.0-beta",
+    "@temporal-contract/worker": "^8.0.0-beta",
+    "@temporalio/activity": "^1.22.0",
+    "@temporalio/common": "^1.22.0",
+    "@temporalio/worker": "^1.22.0",
+    "unthrown": "^5.0.0",
+    "@btravstack/config": "^0.3.0",
+    "@btravstack/di": "^0.3.0",
+    "@btravstack/core": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "test:types": "tsc --noEmit -p tsconfig.test-d.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
+  }
+}