@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/source/validate.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The validation pipeline that turns a resolved-but-untrusted module value
+ * into an installable {@link WorkflowRevisionManifest}, or a bounded,
+ * structured rejection. Engine-agnostic and pure(-ish): no `Engine`
+ * instance, no storage, no catalog access — every check here operates only
+ * on the descriptor and the loaded module value, so it can be unit-tested
+ * (`validate.test.ts`) without constructing an engine.
+ *
+ * @module core/source/validate
+ */
+import type { ActivityRegistry } from '../activity-registry.ts';
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { WorkflowDefinition } from '../types.ts';
+import type { RegisteredWorkflowDefinition } from '../types/workflow-registry.ts';
+import type { WorkflowSourceRejectionReason } from './errors.ts';
+import type { WorkflowSourceDescriptor } from './types.ts';
+/**
+ * The outcome of {@link validateResolvedWorkflowSource}: either every check
+ * passed and this is an installable revision, or validation failed with the
+ * complete, ordered list of every applicable
+ * {@link WorkflowSourceRejectionReason} — never just the first one found.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowSourceValidationOutcome } from './validate.ts';
+ *
+ * const outcome: WorkflowSourceValidationOutcome = { ok: false, reasons: ['missing-export'] };
+ * console.log(outcome.ok);
+ * ```
+ */
+export type WorkflowSourceValidationOutcome = Readonly<{
+    ok: true;
+    manifest: WorkflowRevisionManifest;
+    definition: RegisteredWorkflowDefinition;
+    activityRegistry: ActivityRegistry;
+    loadedDefinition: WorkflowDefinition;
+}> | Readonly<{
+    ok: false;
+    reasons: readonly WorkflowSourceRejectionReason[];
+}>;
+/**
+ * Build the synthetic "expected" manifest `checkWorkflowCompatibility`
+ * compares `actual` against: `name`/`revision` always overridden to the
+ * descriptor's values (the whole point — an actual revision that
+ * legitimately differs from what the descriptor expected must be reported
+ * as `artifact-revision-mismatch`, never silently accepted), and
+ * `workflowVersion`/`contractHash` overridden ONLY when the descriptor pins
+ * them, otherwise copied from `actual` so an unpinned field can never
+ * produce a false-positive mismatch.
+ *
+ * Exported (not just used internally by {@link validateResolvedWorkflowSource})
+ * so `core/engine/source-resolution.ts`'s catalog fast path can run the
+ * identical pin check against an already-cached manifest — a registered
+ * handle that pins `workflowVersion`/`contractHash` must reject a cached
+ * manifest that contradicts those pins exactly as a fresh load-and-validate
+ * would, never silently returning mismatched cached data.
+ */
+export declare function buildExpectedManifest(descriptor: WorkflowSourceDescriptor, actual: WorkflowRevisionManifest): WorkflowRevisionManifest;
+/**
+ * Validate a resolved-but-untrusted `moduleValue` (the raw value a
+ * {@link import('./resolvers.ts').resolveSourceModule} call produced)
+ * against `descriptor`'s expectations, in order:
+ *
+ * 1. `moduleValue` must be a plain record and must own `descriptor.exportName` — else `missing-export`.
+ * 2. The export must not itself be an ES module namespace object (an `export * as x` barrel) — else `ambiguous-export`.
+ * 3. The export must be a builder-produced `WorkflowDefinition` — else `invalid-definition` (covers the removed bare-handler shape).
+ * 4. The export's `name` must pass the wire-safe name grammar — else `invalid-definition`.
+ * 5. The export's activities/signals/updates/queries must normalize without error — else `invalid-definition`.
+ * 6. A `WorkflowRevisionManifest` must build from the normalized definition without exceeding a WFT-5 hostile-input limit — else `manifest-build-failed`.
+ * 7. The built manifest must be compatible with the descriptor's expectations via `checkWorkflowCompatibility` — else the returned `WorkflowCompatibilityReason`s.
+ *
+ * Every applicable reason at whichever step first fails is returned;
+ * later steps never run once an earlier step already failed, since each
+ * step's output feeds the next (there is nothing left to check once, say,
+ * the export cannot even be found).
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowSourceDescriptor } from '@lostgradient/weft';
+ *
+ * const descriptor: WorkflowSourceDescriptor = {
+ *   kind: 'module',
+ *   name: 'checkout',
+ *   location: './checkout.ts',
+ *   exportName: 'checkout',
+ *   revision: 'r1',
+ * };
+ * console.log(descriptor.exportName);
+ * ```
+ */
+export declare function validateResolvedWorkflowSource(descriptor: WorkflowSourceDescriptor, moduleValue: unknown): Promise<WorkflowSourceValidationOutcome>;

package/dist/core/source/validate.js

@@ -0,0 +1,62 @@
+import { isRecord } from "../../worker/manifest/is-record.js";
+import {
+  DEFAULT_WORKFLOW_COMPATIBILITY_POLICY,
+  checkWorkflowCompatibility
+} from "../contract/compatibility.js";
+import { copyWorkflowDefinition } from "../engine/construction.js";
+import {
+  buildPerWorkflowActivityRegistry,
+  buildRegistrationEntry,
+  isBuilderWorkflowDefinition
+} from "../engine/registration.js";
+import { buildWorkflowManifestFromDefinition } from "../registry-workflow-manifest.js";
+import { validateWorkflowOrActivityName } from "../types/name-grammar.js";
+function readOwnExport(moduleValue, exportName) {
+  return Object.hasOwn(moduleValue, exportName) ? moduleValue[exportName] : void 0;
+}
+export function buildExpectedManifest(descriptor, actual) {
+  return {
+    ...actual,
+    name: descriptor.name,
+    revision: descriptor.revision,
+    ...descriptor.workflowVersion === void 0 ? {} : { workflowVersion: descriptor.workflowVersion },
+    ...descriptor.contractHash === void 0 ? {} : { contractHash: descriptor.contractHash }
+  };
+}
+export async function validateResolvedWorkflowSource(descriptor, moduleValue) {
+  if (!isRecord(moduleValue))
+    return { ok: !1, reasons: ["missing-export"] };
+  const exportValue = readOwnExport(moduleValue, descriptor.exportName);
+  if (exportValue === void 0)
+    return { ok: !1, reasons: ["missing-export"] };
+  if (Object.prototype.toString.call(exportValue) === "[object Module]")
+    return { ok: !1, reasons: ["ambiguous-export"] };
+  if (!isBuilderWorkflowDefinition(exportValue))
+    return { ok: !1, reasons: ["invalid-definition"] };
+  const loadedDefinition = exportValue;
+  let entry, activityRegistry;
+  try {
+    validateWorkflowOrActivityName(loadedDefinition.name, "workflow");
+    entry = buildRegistrationEntry(loadedDefinition.name, loadedDefinition);
+    activityRegistry = buildPerWorkflowActivityRegistry(exportValue.activities);
+  } catch {
+    return { ok: !1, reasons: ["invalid-definition"] };
+  }
+  const registeredDefinition = copyWorkflowDefinition(loadedDefinition.name, entry);
+  let actualManifest;
+  try {
+    actualManifest = await buildWorkflowManifestFromDefinition(registeredDefinition, activityRegistry.listDefinitions());
+  } catch {
+    return { ok: !1, reasons: ["manifest-build-failed"] };
+  }
+  const expectedManifest = buildExpectedManifest(descriptor, actualManifest), verdict = checkWorkflowCompatibility(expectedManifest, actualManifest, DEFAULT_WORKFLOW_COMPATIBILITY_POLICY);
+  if (!verdict.compatible)
+    return { ok: !1, reasons: verdict.reasons };
+  return {
+    ok: !0,
+    manifest: actualManifest,
+    definition: registeredDefinition,
+    activityRegistry,
+    loadedDefinition
+  };
+}

package/dist/core/source/workflow-source.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `workflowSource()` — the typed factory pairing a serializable
+ * {@link WorkflowSourceDescriptor} with a host-side loader capability.
+ *
+ * @module core/source/workflow-source
+ */
+import type { InputOf, IsAny, ModuleWorkflowDefinition, NameOf, OutputOf, ServicesOf, WorkflowSourceDescriptorInput, WorkflowSourceHandle } from './types.ts';
+/**
+ * Build a typed {@link WorkflowSourceHandle} from a `descriptor` and a
+ * `loader` capability. The loader is stored on the returned handle
+ * unchanged (identity, not wrapped) and is never invoked by this function —
+ * `workflowSource()` is pure construction, matching `engine.registerSource()`'s
+ * own "records a candidate, never imports" contract one level up.
+ *
+ * `loader` must be a literal `() => import('./x.ts')` (or an equivalent
+ * statically-typed async function) for `TInput`/`TOutput`/`TName`/`TServices`
+ * to infer from the module's real export types. A dynamic import
+ * (`() => import(pathVariable)`, typed `Promise<any>`) is rejected at the
+ * type level via `descriptor`'s `IsAny<TModule> extends true ? never : ...`
+ * guard — see `workflow-source.test-d.ts`.
+ *
+ * `descriptor.location` is carried verbatim into the returned handle and
+ * never read, parsed, or concatenated by this function or any other
+ * `core/source/**` module — there is no timestamp-query-string or
+ * cache-busting mechanism anywhere in this package; single-flight
+ * deduplication in `resolveWorkflowSource` is keyed by `(name, revision)`,
+ * not by `location`.
+ *
+ * @example
+ * ```ts
+ * import { workflowSource } from '@lostgradient/weft';
+ *
+ * declare const loadCheckout: () => Promise<{
+ *   checkout: import('@lostgradient/weft').WorkflowDefinition<{ orderId: string }, { shipped: boolean }, 'checkout'>;
+ * }>;
+ * const source = workflowSource(
+ *   { name: 'checkout', location: './workflows/checkout.ts', exportName: 'checkout', revision: 'r1' },
+ *   loadCheckout,
+ * );
+ * console.log(source.descriptor.kind);
+ * ```
+ */
+export declare function workflowSource<TModule extends Record<string, unknown>, TExportName extends keyof TModule & string>(descriptor: IsAny<TModule> extends true ? never : WorkflowSourceDescriptorInput<TExportName>, loader: () => Promise<TModule>): WorkflowSourceHandle<InputOf<ModuleWorkflowDefinition<TModule, TExportName>>, OutputOf<ModuleWorkflowDefinition<TModule, TExportName>>, NameOf<ModuleWorkflowDefinition<TModule, TExportName>>, ServicesOf<ModuleWorkflowDefinition<TModule, TExportName>>>;

package/dist/core/source/workflow-source.js

@@ -0,0 +1,16 @@
+const DEFAULT_WORKFLOW_SOURCE_KIND = "module";
+export function workflowSource(descriptor, loader) {
+  const input = descriptor;
+  return Object.freeze({
+    descriptor: Object.freeze({
+      kind: input.kind ?? DEFAULT_WORKFLOW_SOURCE_KIND,
+      name: input.name,
+      location: input.location,
+      exportName: input.exportName,
+      revision: input.revision,
+      ...input.workflowVersion === void 0 ? {} : { workflowVersion: input.workflowVersion },
+      ...input.contractHash === void 0 ? {} : { contractHash: input.contractHash }
+    }),
+    load: loader
+  });
+}

package/dist/core/types/checkpoint.d.ts

@@ -199,6 +199,14 @@ export type WorkerInboundMessage = {
     maxProtocolMessageBytes?: number;
     workflowId: WorkflowId;
     workflowExecutionToken?: string;
+    /**
+     * The dispatching run's persisted `WorkflowState.revision` (WFT-20),
+     * when known. Captured worker-side and re-stamped on every outbound
+     * message for this workflow's remaining turns (including `resume`
+     * turns, which never resend this field) — see
+     * `workers/workflow-runner.ts`'s `workflowRevisions` map.
+     */
+    workflowRevision?: string;
     workflowType: string;
     checkpoint: ArrayBuffer;
     input: unknown;
@@ -236,12 +244,16 @@ export type WorkerOutboundMessage = {
     workflowId: WorkflowId;
     checkpoint: ArrayBuffer;
     operationRequest: OperationRequest | ContextOperationRequest;
+    /** Echo of the captured `run.workflowRevision` (WFT-20) — see that field's doc. */
+    workflowRevision?: string;
 } | {
     type: 'completed';
     protocolVersion?: number;
     turnId?: number;
     workflowId: WorkflowId;
     result: unknown;
+    /** Echo of the captured `run.workflowRevision` (WFT-20) — see that field's doc. */
+    workflowRevision?: string;
 } | {
     type: 'failed';
     protocolVersion?: number;
@@ -251,6 +263,8 @@ export type WorkerOutboundMessage = {
     errorStack?: string;
     /** Populated when the execution strategy can classify the failure cause. */
     failureCategory?: FailureCategory;
+    /** Echo of the captured `run.workflowRevision` (WFT-20) — see that field's doc. */
+    workflowRevision?: string;
 } | {
     /**
      * A `ctx.log` record forwarded from a worker to the engine host's

package/dist/core/types/schedules.d.ts

@@ -23,6 +23,27 @@ export type ScheduleStatus = 'active' | 'paused' | 'cancelled';
  * ```
  */
 export type ScheduleOverlapPolicy = 'skip' | 'queue' | 'cancel-running' | 'allow';
+/**
+ * Which persisted workflow revision a schedule's future occurrences resolve
+ * against (WFT-20). `'active-at-fire'` (the default) resolves whatever
+ * revision is currently active at the moment each occurrence fires — this is
+ * the schedule's pre-WFT-20 behavior, unchanged. `'pinned'` captures the
+ * revision that would run right now at create/update time
+ * ({@link ScheduleMetadata.pinnedRevision}) and forces every future
+ * occurrence to resolve against exactly that revision, pausing the schedule
+ * (see `guides/workflow-versioning.md`'s "Schedule revision policy" section)
+ * if that revision later becomes unavailable rather than silently falling
+ * back to whatever is active.
+ *
+ * @example
+ * ```ts
+ * import type { ScheduleRevisionPolicy } from '@lostgradient/weft';
+ *
+ * const policy: ScheduleRevisionPolicy = 'pinned';
+ * void policy;
+ * ```
+ */
+export type ScheduleRevisionPolicy = 'active-at-fire' | 'pinned';
 /**
  * One occurrence waiting behind the active run of a `queue` overlap schedule.
  * `workflowId` is reserved when the occurrence enters the durable queue and is
@@ -117,12 +138,27 @@ export interface ScheduleOptions {
      * pre-jitter occurrence timestamp.
      */
     jitter?: Duration;
+    /**
+     * Which revision future occurrences resolve against. Defaults to
+     * `'active-at-fire'`. Passing `'pinned'` captures the revision that would
+     * run right now — see {@link ScheduleRevisionPolicy}. This is a
+     * per-schedule revision override; `StartOptions` (a one-shot
+     * `engine.start()` call) has no equivalent per-call revision override.
+     */
+    revisionPolicy?: ScheduleRevisionPolicy;
 }
 /**
  * Mutable options accepted when updating an existing schedule. Omitted fields
  * retain their persisted values. Schedule identity, workflow type, and input
  * are intentionally excluded.
  *
+ * Omitting `revisionPolicy` preserves the schedule's current policy AND its
+ * captured {@link ScheduleMetadata.pinnedRevision} unchanged. Passing
+ * `revisionPolicy: 'pinned'` — even when the schedule is already pinned —
+ * always RE-resolves and re-captures the pin against the revision active
+ * right now; it is never a no-op. Passing `revisionPolicy: 'active-at-fire'`
+ * clears any previously captured pin.
+ *
  * @example
  * ```ts
  * import { Engine, workflow, type ScheduleUpdateOptions } from '@lostgradient/weft';
@@ -135,7 +171,7 @@ export interface ScheduleOptions {
  * engine[Symbol.dispose]();
  * ```
  */
-export type ScheduleUpdateOptions = Pick<ScheduleOptions, 'description' | 'overlap' | 'backfill' | 'jitter'>;
+export type ScheduleUpdateOptions = Pick<ScheduleOptions, 'description' | 'overlap' | 'backfill' | 'jitter' | 'revisionPolicy'>;
 /**
  * Declarative recurring schedule definition returned by {@link schedule}. Supply
  * exactly one of `cron` (cron cadence) or `every` (fixed interval).
@@ -168,6 +204,7 @@ export type ScheduleDefinition<TInput = unknown> = ScheduleSpec & {
     overlapPolicy?: ScheduleOverlapPolicy;
     backfill?: boolean;
     jitter?: Duration;
+    revisionPolicy?: ScheduleRevisionPolicy;
 };
 /**
  * Create a recurring schedule definition for `engine.schedule(definition)`.
@@ -206,6 +243,20 @@ export interface ScheduleMetadata {
     backfill: boolean;
     /** Normalized deterministic jitter window in milliseconds. */
     jitterMs?: number;
+    /**
+     * Which revision future occurrences resolve against. Required on every
+     * record this package writes; a legacy record persisted before WFT-20
+     * decodes as `'active-at-fire'` (see `validation/schedule-revision.ts`) —
+     * absence never means "unset," it means "pre-pinning."
+     */
+    revisionPolicy: ScheduleRevisionPolicy;
+    /**
+     * The exact revision every future occurrence resolves against, captured at
+     * the moment this schedule was created or last switched to (or re-pinned
+     * under) `revisionPolicy: 'pinned'`. Present only when `revisionPolicy ===
+     * 'pinned'`.
+     */
+    pinnedRevision?: string;
     createdAt: number;
     updatedAt: number;
     /** Most recent occurrence that started a scheduled workflow. */

package/dist/core/types/state.d.ts

@@ -53,6 +53,20 @@ export interface WorkflowState {
      * detect version drift.
      */
     versionTuple: WorkflowVersionTuple;
+    /**
+     * The exact executable artifact this run started against — the revision
+     * of the code actually loaded in this process at admission time (an
+     * eager registration's `registeredCatalogRevisions` entry, or a dynamic
+     * source's resolved candidate revision), NOT the catalog's cached active
+     * pointer. Sibling to {@link versionTuple}: `revision` answers "which
+     * artifact" for identity, diagnostics, and pinning; `versionTuple` remains
+     * the sole semantic-compatibility axis recovery checks. Every fresh start
+     * from this release forward sets it; `undefined` only on a record
+     * persisted before this field existed (a pre-upgrade run) — recovery
+     * treats that absence as a bounded, explicitly-classified legacy case
+     * rather than falling back to the currently active revision.
+     */
+    revision?: string;
     /**
      * Durable token identifying this concrete workflow run. It changes when a
      * stable workflow id is reused with `onTerminalConflict: 'start-new'`, and
@@ -291,6 +305,8 @@ export interface WorkflowSummary {
     status: WorkflowStatus;
     tags?: string[];
     version: string;
+    /** The exact executable artifact this run started against. See {@link WorkflowState.revision}. */
+    revision?: string;
     createdAt: number;
     updatedAt: number;
     /** Execution deadline (ms epoch) if set on the workflow. */

package/dist/core/types/workflow-registries.d.ts

@@ -5,6 +5,13 @@ import type { StepWorkflowFunction, WorkflowDefinition, WorkflowFunction } from
  * `input` and `output` fields to make `engine.register`, `engine.start`, and
  * `WorkflowHandle.result()` type-safe for string workflow names.
  *
+ * `weft codegen`-generated entries additionally carry `revision`/
+ * `workflowVersion` string-literal fields for compile-time introspection —
+ * see `documentation/reference/cli.md#codegen` for the generated shape.
+ * Neither is required here: {@link WorkflowInput}/{@link WorkflowOutput}
+ * read only `input`/`output`, so a hand-authored entry (as below) never
+ * needs to supply them.
+ *
  * @example
  * ```ts
  * import type { WorkflowRegistry } from '@lostgradient/weft';

package/dist/core/types/workflow-registry.d.ts

@@ -38,4 +38,16 @@ export interface RegisteredWorkflowDefinition<TInput = unknown, TOutput = unknow
     searchAttributes?: SearchAttributeSchema;
     /** Optional start admission policy for this workflow type. */
     concurrency?: WorkflowConcurrencyOptions<TInput>;
+    /**
+     * Schema-only metadata for the workflow's definition-level finalizer
+     * activity ({@link WorkflowDefinition.finalizer}), when registered. Carries
+     * only `name`/`inputSchema`/`outputSchema` — never the finalizer's
+     * `execute` handler — matching this interface's read-only introspection
+     * contract (the workflow's own handler is likewise never exposed here).
+     */
+    finalizer?: Readonly<{
+        name: string;
+        inputSchema?: DefinitionSchema;
+        outputSchema?: DefinitionSchema;
+    }>;
 }

package/dist/core/versioning.js

@@ -45,6 +45,8 @@ ${diffs.map((diff) => {
         return `  - field \`${diff.field}\` was removed (was: ${diff.oldType})`;
       case "type-changed":
         return `  - field \`${diff.field}\` changed type: ${diff.oldType} \u2192 ${diff.newType}`;
+      default:
+        throw Error(`Unknown field diff change: ${JSON.stringify(diff)}`);
     }
   }).join(`
 `)}`;

package/dist/core/weft-error.d.ts

@@ -25,7 +25,7 @@
  * }
  * ```
  */
-export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'EngineDisposalError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'WorkflowConcurrencyLimitExceededError' | 'WorkflowSuspendNotSupportedError' | 'ActivityResolutionError' | 'BranchTopologyChangedError' | 'PersistedDataIncompatibleError' | 'PersistedDataCorruptError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'DurableActivityScopeError' | 'DurableActivityUnsupportedError' | 'AsyncActivityTokenNotFoundError' | 'ActivityScheduleToCloseTimeoutError' | 'ActivityPerAttemptTimeoutError' | 'PayloadSizeExceededError' | 'StartOrSignalConflictError' | 'WorkflowTeardownPendingError' | 'IdempotencyKeyPurgedError' | 'WorkerManifestBuildError' | 'OwnershipModeMismatchError';
+export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'EngineDisposalError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'WorkflowConcurrencyLimitExceededError' | 'WorkflowSuspendNotSupportedError' | 'ActivityResolutionError' | 'BranchTopologyChangedError' | 'PersistedDataIncompatibleError' | 'PersistedDataCorruptError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'DurableActivityScopeError' | 'DurableActivityUnsupportedError' | 'AsyncActivityTokenNotFoundError' | 'ActivityScheduleToCloseTimeoutError' | 'ActivityPerAttemptTimeoutError' | 'PayloadSizeExceededError' | 'StartOrSignalConflictError' | 'WorkflowTeardownPendingError' | 'IdempotencyKeyPurgedError' | 'WorkerManifestBuildError' | 'OwnershipModeMismatchError' | 'ApplicationCommandValidationError' | 'MailboxContentionError' | 'ApplicationDeliveryValidationError' | 'OutboxContentionError' | 'WaitBudgetElapsedError' | 'WorkflowCatalogConflictError' | 'WorkflowRevisionNotInstalledError' | 'WorkflowSourceValidationError' | 'WorkflowSourceNotRegisteredError' | 'DynamicWorkflowSourceUnavailableError' | 'WorkflowRevisionUnavailableError';
 /**
  * Generic abstract base for all Weft library errors. The `TCode` parameter
  * makes each subclass's `code` its own literal type; the exported base surface

package/dist/core/weft-error.js

@@ -47,7 +47,18 @@ const publicWeftErrorCodeMap = {
   WorkflowTeardownPendingError: !0,
   IdempotencyKeyPurgedError: !0,
   WorkerManifestBuildError: !0,
-  OwnershipModeMismatchError: !0
+  OwnershipModeMismatchError: !0,
+  ApplicationCommandValidationError: !0,
+  MailboxContentionError: !0,
+  ApplicationDeliveryValidationError: !0,
+  OutboxContentionError: !0,
+  WaitBudgetElapsedError: !0,
+  WorkflowCatalogConflictError: !0,
+  WorkflowRevisionNotInstalledError: !0,
+  WorkflowSourceValidationError: !0,
+  WorkflowSourceNotRegisteredError: !0,
+  DynamicWorkflowSourceUnavailableError: !0,
+  WorkflowRevisionUnavailableError: !0
 }, PUBLIC_WEFT_ERROR_CODES = new Set(Object.keys(publicWeftErrorCodeMap));
 export function isWeftError(value) {
   return value instanceof WeftError;

package/dist/core/worker-execution-strategy.d.ts

@@ -11,6 +11,7 @@ export declare class WorkerExecutionStrategy implements ExecutionStrategy {
     startWorkflow(parameters: {
         workflowId: string;
         workflowExecutionToken?: string;
+        revision?: string;
         workflowType: string;
         input: unknown;
         checkpoint: ArrayBuffer;

package/dist/core/worker-execution-strategy.js

@@ -45,6 +45,7 @@ export class WorkerExecutionStrategy {
   #messageHandler;
   #disposed;
   #nextTurnId;
+  #workflowRevisions;
   constructor(pool, options) {
     const {
       workflowTurnTimeoutMs,
@@ -58,6 +59,7 @@ export class WorkerExecutionStrategy {
     } = options ?? {};
     this.#pool = pool;
     this.#ownership = new WorkerExecutionOwnership;
+    this.#workflowRevisions = new Map;
     this.#workerListeners = new WorkerListenerRegistry;
     this.#checkpointResumeState = new WorkerCheckpointResumeState;
     this.#workflowTurnTimeoutMs = workflowTurnTimeoutMs;
@@ -81,6 +83,9 @@ export class WorkerExecutionStrategy {
       pool: this.#pool,
       emit: (message) => {
         this.#emit(message);
+      },
+      forgetWorkflowRevision: (workflowId) => {
+        this.#workflowRevisions.delete(workflowId);
       }
     });
     this.#dispatcher = new WorkerExecutionDispatcher({
@@ -97,7 +102,7 @@ export class WorkerExecutionStrategy {
       },
       ensureRealmReady: (worker, workflowId) => this.#ensureRealmReady(worker, workflowId),
       beginTurn: (worker, workflowId, turnId, kind) => {
-        this.#turnWatchdog.begin(worker, workflowId, turnId, kind);
+        this.#turnWatchdog.begin(worker, workflowId, turnId, kind, void 0, this.#workflowRevisions.get(workflowId));
       },
       clearTurn: (worker) => {
         this.#turnWatchdog.clear(worker);
@@ -132,6 +137,10 @@ export class WorkerExecutionStrategy {
   startWorkflow(parameters) {
     this.#ownership.resetWorkflow(parameters.workflowId);
     this.#checkpointResumeState.resetWorkflow(parameters.workflowId);
+    if (parameters.revision !== void 0)
+      this.#workflowRevisions.set(parameters.workflowId, parameters.revision);
+    else
+      this.#workflowRevisions.delete(parameters.workflowId);
     const message = buildRunMessage(parameters, this.#inboundMessageContext());
     if (!this.#faultHandler.assertHostToWorkerMessageWithinLimit(parameters.workflowId, message))
       return;
@@ -185,6 +194,7 @@ export class WorkerExecutionStrategy {
     };
   }
   cancelWorkflow(workflowId) {
+    this.#workflowRevisions.delete(workflowId);
     const worker = this.#ownership.getActiveWorker(workflowId);
     if (worker) {
       this.#ownership.markCancelled(workflowId);
@@ -246,6 +256,7 @@ export class WorkerExecutionStrategy {
     this.#workerListeners.detachAll();
     this.#ownership.clear();
     this.#checkpointResumeState.clear();
+    this.#workflowRevisions.clear();
     this.#messageHandler = null;
   }
   async#handleWorkerMessage(worker, message) {
@@ -279,6 +290,7 @@ export class WorkerExecutionStrategy {
       return !1;
     this.#ownership.consumeCancelled(message.workflowId);
     this.#ownership.deleteParked(message.workflowId);
+    this.#workflowRevisions.delete(message.workflowId);
     this.#releaseActiveWorker(message.workflowId);
     this.#detachWorkerListenersIfIdle(worker);
     this.#checkpointResumeState.forgetWorkflowIfClosed(message.workflowId, this.#ownership.isWorkflowClosed(message.workflowId));

package/dist/core/worker-fault-handling.d.ts

@@ -17,6 +17,16 @@ export interface WorkerFaultHandlerDependencies {
     protocolGuard: WorkerProtocolGuard;
     pool: WorkerPool;
     emit: (message: WorkerOutboundMessage) => void;
+    /**
+     * Forget a workflow's captured revision (WFT-20), mirroring
+     * `#settleTerminalWorkerMessage`'s real-terminal-message cleanup. Every
+     * fault path here (protocol violation, turn timeout, worker crash, log
+     * abuse, realm-ready failure) synthesizes a `failed` message directly
+     * rather than routing through that settle path, so without this callback
+     * `WorkerExecutionStrategy#workflowRevisions` would keep an entry per
+     * faulted workflow ID for the life of the strategy.
+     */
+    forgetWorkflowRevision: (workflowId: string) => void;
 }
 export interface WorkerDiscardOptions {
     targetWorkflowId?: string;

package/dist/core/worker-fault-handling.js

@@ -71,6 +71,7 @@ export class WorkerFaultHandler {
     const { ownership, checkpointResumeState } = this.#dependencies;
     ownership.forgetWorkflow(workflowId);
     checkpointResumeState.forgetWorkflowIfClosed(workflowId, !0);
+    this.#dependencies.forgetWorkflowRevision(workflowId);
     if (isTarget && options.skipTarget)
       return;
     this.#dependencies.emit({

package/dist/core/worker-inbound-message.d.ts

@@ -20,6 +20,7 @@ export interface WorkerInboundMessageContext {
 export declare function buildRunMessage(parameters: {
     workflowId: string;
     workflowExecutionToken?: string;
+    revision?: string;
     workflowType: string;
     input: unknown;
     checkpoint: ArrayBuffer;

package/dist/core/worker-inbound-message.js

@@ -8,6 +8,7 @@ export function buildRunMessage(parameters, context) {
     ...parameters.workflowExecutionToken !== void 0 && {
       workflowExecutionToken: parameters.workflowExecutionToken
     },
+    ...parameters.revision !== void 0 && { workflowRevision: parameters.revision },
     workflowType: parameters.workflowType,
     checkpoint: parameters.checkpoint,
     input: parameters.input,

package/dist/core/worker-protocol-guard.js

@@ -51,6 +51,10 @@ export class WorkerProtocolGuard {
       throw new WorkerProtocolError("Worker message arrived outside an active turn");
     if ((message.type === "log" ? void 0 : message.turnId) !== turn.turnId || message.workflowId !== turn.workflowId)
       throw new WorkerProtocolError("Worker message did not match the active turn");
+    if (turn.revision !== void 0) {
+      if ((message.type === "log" ? void 0 : message.workflowRevision) !== turn.revision)
+        throw new WorkerProtocolError("Worker message revision did not match the active turn");
+    }
   }
 }
 function protocolFailure(error, options) {

package/dist/core/worker-protocol.d.ts

@@ -59,6 +59,13 @@ export declare function createBoundedWorkerFailureMessage(parameters: {
     error: string;
     failureCategory: FailureCategory;
     turnId?: number;
+    /**
+     * Echo of the active turn's captured revision (WFT-20). Required whenever the
+     * caller has one, so a bounded fallback for an oversized checkpoint/terminal
+     * message still passes the host's strict revision check instead of being
+     * discarded as a protocol violation.
+     */
+    workflowRevision?: string;
 }): WorkerOutboundMessage;
 export declare function estimateWorkerProtocolMessageBytes(message: unknown): number;
 export declare function assertWorkerProtocolMessageWithinLimit(message: unknown, maxBytes: number | undefined): number;

package/dist/core/worker-protocol.js

@@ -65,7 +65,8 @@ export function createBoundedWorkerFailureMessage(parameters) {
     ...parameters.turnId === void 0 ? {} : { turnId: parameters.turnId },
     workflowId: parameters.workflowId,
     error: truncateForProtocol(parameters.error),
-    failureCategory: parameters.failureCategory
+    failureCategory: parameters.failureCategory,
+    ...parameters.workflowRevision === void 0 ? {} : { workflowRevision: parameters.workflowRevision }
   };
 }
 export function estimateWorkerProtocolMessageBytes(message) {

package/dist/core/worker-turn-watchdog.d.ts

@@ -4,12 +4,19 @@ export interface WorkerTurnState {
     turnId: number;
     kind: 'run' | 'resume';
     timeoutMs: number | undefined;
+    /**
+     * The workflow's captured revision (WFT-20), when known — carried forward
+     * on every turn for this workflow (including `resume`, which never
+     * re-supplies it), for `WorkerProtocolGuard` to validate the outbound
+     * echo against.
+     */
+    revision?: string;
 }
 export type WorkerTurnTimeoutResolverForTesting = (turn: Pick<WorkerTurnState, 'workflowId' | 'kind'>) => number;
 export declare class WorkerTurnWatchdog {
     #private;
     constructor(timeoutMs: number | undefined, onTimeout: (turn: WorkerTurnState) => void);
-    begin(worker: Worker, workflowId: string, turnId: number, kind: WorkerTurnState['kind'], timeoutMs?: number | undefined): void;
+    begin(worker: Worker, workflowId: string, turnId: number, kind: WorkerTurnState['kind'], timeoutMs?: number | undefined, revision?: string): void;
     setTimeoutResolverForTesting(resolver: WorkerTurnTimeoutResolverForTesting): void;
     clear(worker: Worker): void;
     clearAll(): void;