@btravstack/temporal-worker 0.8.0 → 0.10.0

package/README.md

@@ -13,7 +13,7 @@
 ```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
+  @temporal-contract/worker@^8.0.0-beta.7 @temporal-contract/contract@^8.0.0-beta.7
 ```
 
 All nine are peer dependencies — install them. Node `>=22`.
@@ -74,30 +74,28 @@ import { P } from "unthrown";
 // 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 }),
-                ),
-            ),
-      },
-    }),
-  },
-);
+const orderActivities = TemporalActivities(contract)({
+  inject: { place: PlaceOrder },
+  sync: ({ place }) => ({
+    placeOrder: {
+      place: ({ errors, input }) =>
+        place
+          .execute(TenantId(input.tenantId), input.orderId, input.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.
@@ -124,7 +122,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)({ name: Dep }, arm)` mints a
+record: `TemporalWorkflowActivities(contract, key)({ inject: { 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
@@ -134,6 +132,20 @@ 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.
 
+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.
+
+## Schedules
+
+`@btravstack/temporal-worker/schedule` exports `ensureSchedule` — the typed
+schedule client's `create`, made idempotent, so a deploy that runs again
+updates the schedule instead of failing on `ScheduleAlreadyExistsError`.
+`@temporal-contract/client` is an optional peer reached only through that
+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).
+
 ## Options
 
 `TemporalModule(name)({...})` takes `temporal()`'s options plus `activities`

package/dist/index.cjs

@@ -20,7 +20,17 @@ let _temporalio_activity = require("@temporalio/activity");
 * 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());
+const activityUnits = (host, observers) => (_invocation, next) => {
+	const settle = (0, _btravstack_core.observe)(observers, {
+		component: "temporal",
+		name: "attempt",
+		attributes: { activity: (0, _temporalio_activity.activityInfo)().activityType }
+	});
+	return host.run(metaFor(), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+		outcome: "error",
+		cause: failure.tag === "Err" ? failure.error : failure.cause
+	}));
+};
 /**
 * `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
@@ -111,22 +121,31 @@ const temporal = (options) => {
 		needs: [_btravstack_config.Env, activities],
 		provides: [
 			config,
-			(0, _btravstack_di.Provider)(TemporalConnection)({ config: TemporalConfig }, {
+			(0, _btravstack_di.Provider)(TemporalConnection)({
+				inject: { 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))
 			}),
+			_btravstack_di.Provider.member(_btravstack_core.Observers)({
+				inject: {},
+				value: _btravstack_core.noObserver
+			}),
 			(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)
-			}) })
+				inject: {
+					connection: TemporalConnection,
+					config: TemporalConfig,
+					activities,
+					observers: _btravstack_core.Observers
+				},
+				sync: ({ connection, config: bound, activities: impls, observers }) => ({
+					name: "temporal",
+					resolves: [],
+					start: (host) => createWorker(host, connection, bound, impls, options, observers)
+				})
+			})
 		],
 		exports: [
 			TemporalRuntime,
@@ -140,12 +159,12 @@ const startFailed = (cause) => new _btravstack_core.RuntimeStartFailed({
 	cause
 });
 const heldByWorker = (cause) => cause instanceof Error && cause.name === "IllegalStateError";
-const createWorker = (host, connection, config, activities, options) => {
+const createWorker = (host, connection, config, activities, options, observers) => {
 	const { taskQueue } = options.contract;
 	const { namespace } = config;
 	return (0, unthrown.fromThrowable)(() => (0, _temporal_contract_worker_activity.declareActivitiesHandler)({
 		contract: options.contract,
-		middleware: activityUnits(host),
+		middleware: activityUnits(host, observers),
 		activities
 	}), startFailed)().toAsync().flatMap((handler) => (0, unthrown.fromPromise)(_temporalio_worker.Worker.create({
 		connection,
@@ -237,15 +256,15 @@ const TemporalModule = (name) => (options) => {
 	});
 };
 /**
-* The activities as a provider, from the contract. Three call forms, one port.
+* The activities as a provider, from the contract. Two call forms, one port.
 *
 * ```ts
-* TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+* TemporalActivities(orderContract)({ inject: { 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
+* The first is di's own `Provider(port)` on the starter's activities port
+* typed for the contract. The second takes the pieces
 * `TemporalWorkflowActivities(contract, key)` builds: they are the provider's
 * deps, keyed by the contract key each piece's port id carries, so the services
 * record IS the activities record. Every key must be covered, and two slices
@@ -253,8 +272,11 @@ const TemporalModule = (name) => (options) => {
 */
 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));
+	const compose = (pieces) => build({
+		inject: Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(27), piece.port])),
+		sync: (services) => services
+	});
+	return ((first) => Array.isArray(first) ? compose(first) : build(first));
 };
 //#endregion
 exports.TemporalActivities = TemporalActivities;

package/dist/index.d.cts

@@ -213,15 +213,15 @@ type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C
   readonly port: ActivitiesPortOf<C>;
 };
 /**
- * The activities as a provider, from the contract. Three call forms, one port.
+ * The activities as a provider, from the contract. Two call forms, one port.
  *
  * ```ts
- * TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+ * TemporalActivities(orderContract)({ inject: { 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
+ * The first is di's own `Provider(port)` on the starter's activities port
+ * typed for the contract. The second takes the pieces
  * `TemporalWorkflowActivities(contract, key)` builds: they are the provider's
  * deps, keyed by the contract key each piece's port id carries, so the services
  * record IS the activities record. Every key must be covered, and two slices

package/dist/index.d.mts

@@ -213,15 +213,15 @@ type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C
   readonly port: ActivitiesPortOf<C>;
 };
 /**
- * The activities as a provider, from the contract. Three call forms, one port.
+ * The activities as a provider, from the contract. Two call forms, one port.
  *
  * ```ts
- * TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+ * TemporalActivities(orderContract)({ inject: { 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
+ * The first is di's own `Provider(port)` on the starter's activities port
+ * typed for the contract. The second takes the pieces
  * `TemporalWorkflowActivities(contract, key)` builds: they are the provider's
  * deps, keyed by the contract key each piece's port id carries, so the services
  * record IS the activities record. Every key must be covered, and two slices

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { Module, Port, Provider } from "@btravstack/di";
 import { Config, Env } from "@btravstack/config";
-import { RuntimePort, RuntimeStartFailed, releasedBy } from "@btravstack/core";
+import { Observers, RuntimePort, RuntimeStartFailed, noObserver, observe, releasedBy } from "@btravstack/core";
 import { declareActivitiesHandler } from "@temporal-contract/worker/activity";
 import { msToNumber } from "@temporalio/common";
 import { NativeConnection, Worker } from "@temporalio/worker";
@@ -19,7 +19,17 @@ import { activityInfo } from "@temporalio/activity";
 * No `Result`-unwrapping boundary, deliberately: `declareActivitiesHandler` owns
 * the mapping from a settled `Result` to an activity failure.
 */
-const activityUnits = (host) => (_invocation, next) => host.run(metaFor(), () => next());
+const activityUnits = (host, observers) => (_invocation, next) => {
+	const settle = observe(observers, {
+		component: "temporal",
+		name: "attempt",
+		attributes: { activity: activityInfo().activityType }
+	});
+	return host.run(metaFor(), () => next()).tap(() => settle({ outcome: "ok" })).tapFailure((failure) => settle({
+		outcome: "error",
+		cause: failure.tag === "Err" ? failure.error : failure.cause
+	}));
+};
 /**
 * `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
@@ -110,22 +120,31 @@ const temporal = (options) => {
 		needs: [Env, activities],
 		provides: [
 			config,
-			Provider(TemporalConnection)({ config: TemporalConfig }, {
+			Provider(TemporalConnection)({
+				inject: { 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.member(Observers)({
+				inject: {},
+				value: noObserver
+			}),
 			Provider(TemporalRuntime)({
-				connection: TemporalConnection,
-				config: TemporalConfig,
-				activities
-			}, { sync: ({ connection, config: bound, activities: impls }) => ({
-				name: "temporal",
-				resolves: [],
-				start: (host) => createWorker(host, connection, bound, impls, options)
-			}) })
+				inject: {
+					connection: TemporalConnection,
+					config: TemporalConfig,
+					activities,
+					observers: Observers
+				},
+				sync: ({ connection, config: bound, activities: impls, observers }) => ({
+					name: "temporal",
+					resolves: [],
+					start: (host) => createWorker(host, connection, bound, impls, options, observers)
+				})
+			})
 		],
 		exports: [
 			TemporalRuntime,
@@ -139,12 +158,12 @@ const startFailed = (cause) => new RuntimeStartFailed({
 	cause
 });
 const heldByWorker = (cause) => cause instanceof Error && cause.name === "IllegalStateError";
-const createWorker = (host, connection, config, activities, options) => {
+const createWorker = (host, connection, config, activities, options, observers) => {
 	const { taskQueue } = options.contract;
 	const { namespace } = config;
 	return fromThrowable(() => declareActivitiesHandler({
 		contract: options.contract,
-		middleware: activityUnits(host),
+		middleware: activityUnits(host, observers),
 		activities
 	}), startFailed)().toAsync().flatMap((handler) => fromPromise(Worker.create({
 		connection,
@@ -236,15 +255,15 @@ const TemporalModule = (name) => (options) => {
 	});
 };
 /**
-* The activities as a provider, from the contract. Three call forms, one port.
+* The activities as a provider, from the contract. Two call forms, one port.
 *
 * ```ts
-* TemporalActivities(orderContract)({ place: PlaceOrder }, { sync: ({ place }) => ({ fulfillOrder: { … } }) })
+* TemporalActivities(orderContract)({ inject: { 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
+* The first is di's own `Provider(port)` on the starter's activities port
+* typed for the contract. The second takes the pieces
 * `TemporalWorkflowActivities(contract, key)` builds: they are the provider's
 * deps, keyed by the contract key each piece's port id carries, so the services
 * record IS the activities record. Every key must be covered, and two slices
@@ -252,8 +271,11 @@ const TemporalModule = (name) => (options) => {
 */
 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));
+	const compose = (pieces) => build({
+		inject: Object.fromEntries(pieces.map((piece) => [piece.port.portId.slice(27), piece.port])),
+		sync: (services) => services
+	});
+	return ((first) => Array.isArray(first) ? compose(first) : build(first));
 };
 //#endregion
 export { TemporalActivities, TemporalConfig, TemporalConnection, TemporalModule, TemporalRuntime, TemporalUnreachable, TemporalWorkflowActivities, temporal };

package/dist/schedule.cjs

@@ -0,0 +1,51 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let unthrown = require("unthrown");
+let _temporal_contract_client = require("@temporal-contract/client");
+//#region src/schedule.ts
+/**
+* Register a schedule, idempotently.
+*
+* `TypedScheduleClient.create` answers `ScheduleAlreadyExistsError` for a
+* schedule id already in use, which is correct and is also the wrong shape for
+* the one place schedules are actually registered: a **deploy**, which runs
+* again on every release. So the second run of a correct deploy script fails,
+* and the usual repair is a `try`/ignore that also swallows the case where the
+* schedule exists with the WRONG spec — a cron nobody notices has stopped
+* matching what the code says.
+*
+* This recovers exactly that one error into an `update`. Every other error
+* stays on the channel, still typed.
+*
+* **`spec` is the only field reconciled**, and the rest of an existing
+* schedule is left as it stands. Two different reasons, and they are worth
+* telling apart:
+*
+* - **`state` is deliberately preserved.** A schedule an operator paused stays
+*   paused across a deploy, because unpausing it is a decision a person made
+*   and a deploy is not the place to reverse it.
+* - **`args` and the rest of the action are preserved because this cannot
+*   reconcile them SAFELY.** `create` validates `args` against the workflow's
+*   input schema; the handle's `update` takes Temporal's own
+*   `ScheduleUpdateOptions` and validates nothing, so writing them here would
+*   push unvalidated input at the server through a door the typed client keeps
+*   shut. A deploy that changes what a schedule RUNS — its args, its workflow,
+*   its policies — should say so explicitly: delete the schedule and create it,
+*   or reach `getHandle(id).update(...)` directly and own the shape.
+*
+* So: after this call the schedule FIRES when the arguments say. What it fires
+* with is whatever it already fired with.
+*
+* ```ts
+* await ensureSchedule(client.for(orderContract).schedule, "sweepStaleOrders", {
+*   scheduleId: "sweep-stale-orders",
+*   spec: { cronExpressions: ["0 3 * * *"] },
+*   args: [{ olderThanDays: 30 }],
+* });
+* ```
+*/
+const ensureSchedule = (schedules, workflow, options) => schedules.create(workflow, options).map(() => "created").flatMapErrCases((matcher) => matcher.with(unthrown.P.tag(_temporal_contract_client.SCHEDULE_ALREADY_EXISTS_ERROR_TAG), () => schedules.getHandle(options.scheduleId).update((previous) => ({
+	...previous,
+	spec: options.spec
+})).map(() => "updated")).with(unthrown.P.tag("@temporal-contract/WorkflowNotInContractError"), (error) => (0, unthrown.ErrAsync)(error)).with(unthrown.P.tag("@temporal-contract/WorkflowValidationError"), (error) => (0, unthrown.ErrAsync)(error)));
+//#endregion
+exports.ensureSchedule = ensureSchedule;

package/dist/schedule.d.cts

@@ -0,0 +1,50 @@
+import { ContractDefinition } from "@temporal-contract/contract";
+import { ScheduleNotFoundError, TypedScheduleClient, TypedScheduleCreateOptions, WorkflowNotInContractError, WorkflowValidationError } from "@temporal-contract/client";
+import { AsyncResult } from "unthrown";
+//#region src/schedule.d.ts
+/** Whether the schedule had to be created, or was already there and had its spec reconciled. */
+type ScheduleOutcome = "created" | "updated";
+/**
+ * Register a schedule, idempotently.
+ *
+ * `TypedScheduleClient.create` answers `ScheduleAlreadyExistsError` for a
+ * schedule id already in use, which is correct and is also the wrong shape for
+ * the one place schedules are actually registered: a **deploy**, which runs
+ * again on every release. So the second run of a correct deploy script fails,
+ * and the usual repair is a `try`/ignore that also swallows the case where the
+ * schedule exists with the WRONG spec — a cron nobody notices has stopped
+ * matching what the code says.
+ *
+ * This recovers exactly that one error into an `update`. Every other error
+ * stays on the channel, still typed.
+ *
+ * **`spec` is the only field reconciled**, and the rest of an existing
+ * schedule is left as it stands. Two different reasons, and they are worth
+ * telling apart:
+ *
+ * - **`state` is deliberately preserved.** A schedule an operator paused stays
+ *   paused across a deploy, because unpausing it is a decision a person made
+ *   and a deploy is not the place to reverse it.
+ * - **`args` and the rest of the action are preserved because this cannot
+ *   reconcile them SAFELY.** `create` validates `args` against the workflow's
+ *   input schema; the handle's `update` takes Temporal's own
+ *   `ScheduleUpdateOptions` and validates nothing, so writing them here would
+ *   push unvalidated input at the server through a door the typed client keeps
+ *   shut. A deploy that changes what a schedule RUNS — its args, its workflow,
+ *   its policies — should say so explicitly: delete the schedule and create it,
+ *   or reach `getHandle(id).update(...)` directly and own the shape.
+ *
+ * So: after this call the schedule FIRES when the arguments say. What it fires
+ * with is whatever it already fired with.
+ *
+ * ```ts
+ * await ensureSchedule(client.for(orderContract).schedule, "sweepStaleOrders", {
+ *   scheduleId: "sweep-stale-orders",
+ *   spec: { cronExpressions: ["0 3 * * *"] },
+ *   args: [{ olderThanDays: 30 }],
+ * });
+ * ```
+ */
+declare const ensureSchedule: <C extends ContractDefinition, W extends keyof C["workflows"] & string>(schedules: TypedScheduleClient<C>, workflow: W, options: TypedScheduleCreateOptions<C, W>) => AsyncResult<ScheduleOutcome, WorkflowNotInContractError | WorkflowValidationError | ScheduleNotFoundError>;
+//#endregion
+export { ScheduleOutcome, ensureSchedule };

package/dist/schedule.d.mts

@@ -0,0 +1,50 @@
+import { AsyncResult } from "unthrown";
+import { ScheduleNotFoundError, TypedScheduleClient, TypedScheduleCreateOptions, WorkflowNotInContractError, WorkflowValidationError } from "@temporal-contract/client";
+import { ContractDefinition } from "@temporal-contract/contract";
+//#region src/schedule.d.ts
+/** Whether the schedule had to be created, or was already there and had its spec reconciled. */
+type ScheduleOutcome = "created" | "updated";
+/**
+ * Register a schedule, idempotently.
+ *
+ * `TypedScheduleClient.create` answers `ScheduleAlreadyExistsError` for a
+ * schedule id already in use, which is correct and is also the wrong shape for
+ * the one place schedules are actually registered: a **deploy**, which runs
+ * again on every release. So the second run of a correct deploy script fails,
+ * and the usual repair is a `try`/ignore that also swallows the case where the
+ * schedule exists with the WRONG spec — a cron nobody notices has stopped
+ * matching what the code says.
+ *
+ * This recovers exactly that one error into an `update`. Every other error
+ * stays on the channel, still typed.
+ *
+ * **`spec` is the only field reconciled**, and the rest of an existing
+ * schedule is left as it stands. Two different reasons, and they are worth
+ * telling apart:
+ *
+ * - **`state` is deliberately preserved.** A schedule an operator paused stays
+ *   paused across a deploy, because unpausing it is a decision a person made
+ *   and a deploy is not the place to reverse it.
+ * - **`args` and the rest of the action are preserved because this cannot
+ *   reconcile them SAFELY.** `create` validates `args` against the workflow's
+ *   input schema; the handle's `update` takes Temporal's own
+ *   `ScheduleUpdateOptions` and validates nothing, so writing them here would
+ *   push unvalidated input at the server through a door the typed client keeps
+ *   shut. A deploy that changes what a schedule RUNS — its args, its workflow,
+ *   its policies — should say so explicitly: delete the schedule and create it,
+ *   or reach `getHandle(id).update(...)` directly and own the shape.
+ *
+ * So: after this call the schedule FIRES when the arguments say. What it fires
+ * with is whatever it already fired with.
+ *
+ * ```ts
+ * await ensureSchedule(client.for(orderContract).schedule, "sweepStaleOrders", {
+ *   scheduleId: "sweep-stale-orders",
+ *   spec: { cronExpressions: ["0 3 * * *"] },
+ *   args: [{ olderThanDays: 30 }],
+ * });
+ * ```
+ */
+declare const ensureSchedule: <C extends ContractDefinition, W extends keyof C["workflows"] & string>(schedules: TypedScheduleClient<C>, workflow: W, options: TypedScheduleCreateOptions<C, W>) => AsyncResult<ScheduleOutcome, WorkflowNotInContractError | WorkflowValidationError | ScheduleNotFoundError>;
+//#endregion
+export { ScheduleOutcome, ensureSchedule };

package/dist/schedule.mjs

@@ -0,0 +1,50 @@
+import { ErrAsync, P } from "unthrown";
+import { SCHEDULE_ALREADY_EXISTS_ERROR_TAG } from "@temporal-contract/client";
+//#region src/schedule.ts
+/**
+* Register a schedule, idempotently.
+*
+* `TypedScheduleClient.create` answers `ScheduleAlreadyExistsError` for a
+* schedule id already in use, which is correct and is also the wrong shape for
+* the one place schedules are actually registered: a **deploy**, which runs
+* again on every release. So the second run of a correct deploy script fails,
+* and the usual repair is a `try`/ignore that also swallows the case where the
+* schedule exists with the WRONG spec — a cron nobody notices has stopped
+* matching what the code says.
+*
+* This recovers exactly that one error into an `update`. Every other error
+* stays on the channel, still typed.
+*
+* **`spec` is the only field reconciled**, and the rest of an existing
+* schedule is left as it stands. Two different reasons, and they are worth
+* telling apart:
+*
+* - **`state` is deliberately preserved.** A schedule an operator paused stays
+*   paused across a deploy, because unpausing it is a decision a person made
+*   and a deploy is not the place to reverse it.
+* - **`args` and the rest of the action are preserved because this cannot
+*   reconcile them SAFELY.** `create` validates `args` against the workflow's
+*   input schema; the handle's `update` takes Temporal's own
+*   `ScheduleUpdateOptions` and validates nothing, so writing them here would
+*   push unvalidated input at the server through a door the typed client keeps
+*   shut. A deploy that changes what a schedule RUNS — its args, its workflow,
+*   its policies — should say so explicitly: delete the schedule and create it,
+*   or reach `getHandle(id).update(...)` directly and own the shape.
+*
+* So: after this call the schedule FIRES when the arguments say. What it fires
+* with is whatever it already fired with.
+*
+* ```ts
+* await ensureSchedule(client.for(orderContract).schedule, "sweepStaleOrders", {
+*   scheduleId: "sweep-stale-orders",
+*   spec: { cronExpressions: ["0 3 * * *"] },
+*   args: [{ olderThanDays: 30 }],
+* });
+* ```
+*/
+const ensureSchedule = (schedules, workflow, options) => schedules.create(workflow, options).map(() => "created").flatMapErrCases((matcher) => matcher.with(P.tag(SCHEDULE_ALREADY_EXISTS_ERROR_TAG), () => schedules.getHandle(options.scheduleId).update((previous) => ({
+	...previous,
+	spec: options.spec
+})).map(() => "updated")).with(P.tag("@temporal-contract/WorkflowNotInContractError"), (error) => ErrAsync(error)).with(P.tag("@temporal-contract/WorkflowValidationError"), (error) => ErrAsync(error)));
+//#endregion
+export { ensureSchedule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/temporal-worker",
-  "version": "0.8.0",
+  "version": "0.10.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",
@@ -41,12 +41,23 @@
         "default": "./dist/index.cjs"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./schedule": {
+      "import": {
+        "types": "./dist/schedule.d.mts",
+        "default": "./dist/schedule.mjs"
+      },
+      "require": {
+        "types": "./dist/schedule.d.cts",
+        "default": "./dist/schedule.cjs"
+      }
+    }
   },
   "devDependencies": {
     "@btravstack/tsconfig": "0.2.0",
-    "@temporal-contract/contract": "8.0.0-beta.5",
-    "@temporal-contract/worker": "8.0.0-beta.5",
+    "@temporal-contract/client": "8.0.0-beta.7",
+    "@temporal-contract/contract": "8.0.0-beta.7",
+    "@temporal-contract/worker": "8.0.0-beta.7",
     "@temporalio/activity": "1.23.0",
     "@temporalio/client": "1.23.0",
     "@temporalio/common": "1.23.0",
@@ -59,30 +70,36 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "zod": "4.5.1",
-    "@btravstack/config": "0.8.0",
-    "@btravstack/core": "0.8.0",
-    "@btravstack/di": "0.8.0",
-    "@btravstack/testing": "0.8.0",
-    "@btravstack/internal-test-infra": "0.0.0"
+    "zod": "4.5.3",
+    "@btravstack/config": "0.10.0",
+    "@btravstack/core": "0.10.0",
+    "@btravstack/di": "0.10.0",
+    "@btravstack/internal-test-infra": "0.0.0",
+    "@btravstack/testing": "0.10.0"
   },
   "peerDependencies": {
-    "@temporal-contract/contract": "^8.0.0-beta",
-    "@temporal-contract/worker": "^8.0.0-beta",
+    "@temporal-contract/client": "^8.0.0-beta.7",
+    "@temporal-contract/contract": "^8.0.0-beta.7",
+    "@temporal-contract/worker": "^8.0.0-beta.7",
     "@temporalio/activity": "^1.22.0",
     "@temporalio/common": "^1.22.0",
     "@temporalio/worker": "^1.22.0",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.8.0",
-    "@btravstack/core": "^0.8.0",
-    "@btravstack/di": "^0.8.0"
+    "@btravstack/config": "^0.10.0",
+    "@btravstack/core": "^0.10.0",
+    "@btravstack/di": "^0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@temporal-contract/client": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsdown src/index.ts src/schedule.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts src/schedule.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"