@btravstack/temporal-worker 0.9.0 → 0.11.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`.
@@ -23,14 +23,32 @@ All nine are peer dependencies — install them. Node `>=22`.
 <!-- 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 { Module, Port, type AnyModule } from "@btravstack/di";
+import { TaggedError, type AsyncResult } from "unthrown";
 import { observability } from "@btravstack/observability";
 import { otel } from "@btravstack/observability/otel";
 import { z } from "zod";
 
+// The application's own layers, declared here so this sample stands on the
+// published packages alone: the use case, its errors and its tenant id are
+// yours, not this package's.
+class DuplicateOrder extends TaggedError("DuplicateOrder")<{ readonly id: string }> {}
+class InvalidOrderId extends TaggedError("InvalidOrderId")<{ readonly id: string }> {}
+class InvalidQuantity extends TaggedError("InvalidQuantity")<{ readonly id: string }> {}
+declare const TenantId: (value: string) => string;
+class PlaceOrder extends Port("PlaceOrder")<{
+  readonly execute: (
+    tenantId: string,
+    id: string,
+    quantity: number,
+  ) => AsyncResult<
+    { readonly id: string },
+    DuplicateOrder | InvalidOrderId | InvalidQuantity
+  >;
+}> {}
+declare const OrderApplicationModule: Module<PlaceOrder, never, never>;
+declare const OrderPersistenceModule: AnyModule;
+
 // The contract this README's worker serves — one workflow, one activity, one
 // modeled contract error.
 const contract = defineContract({
@@ -58,7 +76,7 @@ const contract = defineContract({
 
 const AppModule = Module("App")({
   imports: [OrderApplicationModule, OrderPersistenceModule, observability(), otel()],
-  exports: [PlaceOrder, OrderRepository, Outbox, Logger],
+  exports: [PlaceOrder, Logger],
 });
 -->
 
@@ -78,9 +96,9 @@ const orderActivities = TemporalActivities(contract)({
   inject: { place: PlaceOrder },
   sync: ({ place }) => ({
     placeOrder: {
-      place: (args, { errors }) =>
+      place: ({ errors, input }) =>
         place
-          .execute(TenantId(args.tenantId), args.orderId, args.quantity)
+          .execute(TenantId(input.tenantId), input.orderId, input.quantity)
           .mapErrCases((matcher) =>
             matcher
               .with(P.tag("DuplicateOrder"), (error) =>
@@ -128,9 +146,26 @@ 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.
+the pieces' ports, not what they close over. A workflow's activities belong to exactly
+one slice, and the compiler holds only half of that: coverage is checked,
+injectivity is not, so two slices claiming one key type-check together. It is
+di's duplicate-provider defect at build once **both** pieces are discharged as
+providers in one graph — wire in only one and the other's implementation is
+silently never registered.
+
+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
 

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
@@ -119,16 +129,21 @@ const temporal = (options) => {
 				})),
 				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)({
 				inject: {
 					connection: TemporalConnection,
 					config: TemporalConfig,
-					activities
+					activities,
+					observers: _btravstack_core.Observers
 				},
-				sync: ({ connection, config: bound, activities: impls }) => ({
+				sync: ({ connection, config: bound, activities: impls, observers }) => ({
 					name: "temporal",
 					resolves: [],
-					start: (host) => createWorker(host, connection, bound, impls, options)
+					start: (host) => createWorker(host, connection, bound, impls, options, observers)
 				})
 			})
 		],
@@ -144,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,

package/dist/index.d.cts

@@ -200,6 +200,19 @@ type KeyOfPiece<P> = P extends {
 } ? 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]>>;
+/**
+ * A refused array: as long as the array the caller wrote, its head the caller's
+ * own elements — which match — and its LAST element the marker paired with what
+ * is wrong.
+ *
+ * TypeScript compares two equal-length tuples element by element, so the extra
+ * diagnostic it reports lands on the trailing element and carries both the
+ * sentence and the missing key. A fixed two-element tuple named the key only
+ * when the array happened to be two elements long; every other arity was a
+ * length mismatch, and the developer diffed the contract against the array by
+ * hand.
+ */
+type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
 /**
  * The composing arm. Declared LAST in the intersection below on purpose:
  * TypeScript reports the last overload's failure, so a non-covering array is
@@ -209,7 +222,7 @@ type Uncovered<C extends ContractDefinition, T extends readonly PieceOf<C>[]> =
  * 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"]>> & {
+type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : Refuse<T, "UNCOVERED ACTIVITIES — the contract declares a workflow this array does not cover", Uncovered<C, T>>) => Provider<ActivitiesInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
   readonly port: ActivitiesPortOf<C>;
 };
 /**

package/dist/index.d.mts

@@ -200,6 +200,19 @@ type KeyOfPiece<P> = P extends {
 } ? 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]>>;
+/**
+ * A refused array: as long as the array the caller wrote, its head the caller's
+ * own elements — which match — and its LAST element the marker paired with what
+ * is wrong.
+ *
+ * TypeScript compares two equal-length tuples element by element, so the extra
+ * diagnostic it reports lands on the trailing element and carries both the
+ * sentence and the missing key. A fixed two-element tuple named the key only
+ * when the array happened to be two elements long; every other arity was a
+ * length mismatch, and the developer diffed the contract against the array by
+ * hand.
+ */
+type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
 /**
  * The composing arm. Declared LAST in the intersection below on purpose:
  * TypeScript reports the last overload's failure, so a non-covering array is
@@ -209,7 +222,7 @@ type Uncovered<C extends ContractDefinition, T extends readonly PieceOf<C>[]> =
  * 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"]>> & {
+type Compose<C extends ContractDefinition> = <const T extends readonly PieceOf<C>[]>(pieces: [Uncovered<C, T>] extends [never] ? T : Refuse<T, "UNCOVERED ACTIVITIES — the contract declares a workflow this array does not cover", Uncovered<C, T>>) => Provider<ActivitiesInstanceOf<C>, never, InstanceType<T[number]["port"]>> & {
   readonly port: ActivitiesPortOf<C>;
 };
 /**

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
@@ -118,16 +128,21 @@ const temporal = (options) => {
 				})),
 				release: (connection) => connection.close().catch((cause) => heldByWorker(cause) ? void 0 : Promise.reject(cause))
 			}),
+			Provider.member(Observers)({
+				inject: {},
+				value: noObserver
+			}),
 			Provider(TemporalRuntime)({
 				inject: {
 					connection: TemporalConnection,
 					config: TemporalConfig,
-					activities
+					activities,
+					observers: Observers
 				},
-				sync: ({ connection, config: bound, activities: impls }) => ({
+				sync: ({ connection, config: bound, activities: impls, observers }) => ({
 					name: "temporal",
 					resolves: [],
-					start: (host) => createWorker(host, connection, bound, impls, options)
+					start: (host) => createWorker(host, connection, bound, impls, options, observers)
 				})
 			})
 		],
@@ -143,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,

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.9.0",
+  "version": "0.11.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.9.0",
-    "@btravstack/core": "0.9.0",
-    "@btravstack/di": "0.9.0",
+    "zod": "4.5.3",
+    "@btravstack/config": "0.11.0",
+    "@btravstack/core": "0.11.0",
+    "@btravstack/di": "0.11.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/testing": "0.9.0"
+    "@btravstack/testing": "0.11.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.9.0",
-    "@btravstack/core": "^0.9.0",
-    "@btravstack/di": "^0.9.0"
+    "@btravstack/config": "^0.11.0",
+    "@btravstack/core": "^0.11.0",
+    "@btravstack/di": "^0.11.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"