@lostgradient/weft 0.24.0 → 0.24.1

package/dist/core/events/index.js

@@ -7,3 +7,4 @@ export * from "./signal-events.js";
 export * from "./system-events.js";
 export * from "./update-events.js";
 export * from "./workflow-events.js";
+export * from "./workflow-source-events.js";

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

@@ -0,0 +1,102 @@
+import type { FailureCategory } from '../types/identity.ts';
+type WorkflowSourceKind = import('../source/index.ts').WorkflowSourceKind;
+/**
+ * Fired on the {@link Engine} when a dynamic workflow source's single-flight
+ * load for `(workflowType, revision)` starts — the loader is about to be
+ * invoked. Never fired for a cache hit (an already-installed revision
+ * `resolveWorkflowSource()` returns without invoking the loader).
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadStartedEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadStartedEvent.type, (event) => {
+ *   console.log('loading:', event.workflowType, event.revision);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadStartedEvent extends Event {
+    static readonly type: "workflow-source:load-started";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind);
+}
+/**
+ * Fired on the {@link Engine} when a dynamic workflow source's load for
+ * `(workflowType, revision)` completes successfully — the loader ran,
+ * validation passed, and the manifest is durably installed.
+ * `loadDurationMs` is measured via the engine's own injected clock.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadReadyEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadReadyEvent.type, (event) => {
+ *   console.log('ready:', event.workflowType, event.revision, event.loadDurationMs);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadReadyEvent extends Event {
+    static readonly type: "workflow-source:load-ready";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    readonly loadDurationMs: number;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind, loadDurationMs: number);
+}
+/**
+ * Fired on the {@link Engine} when a dynamic workflow source's load for
+ * `(workflowType, revision)` fails — the loader threw, validation rejected
+ * the loaded module, or the durable install failed. `failureCategory` is
+ * the closed, low-cardinality {@link FailureCategory} classification, safe
+ * to use as a metric label; the underlying error itself is never included.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadFailedEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadFailedEvent.type, (event) => {
+ *   console.log('failed:', event.workflowType, event.revision, event.failureCategory);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadFailedEvent extends Event {
+    static readonly type: "workflow-source:load-failed";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    readonly loadDurationMs: number;
+    readonly failureCategory: FailureCategory;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind, loadDurationMs: number, failureCategory: FailureCategory);
+}
+/**
+ * Fired on the {@link Engine} when the LAST outstanding
+ * `resolveWorkflowSource()` waiter for `(workflowType, revision)` releases
+ * (its own abort, or engine disposal) while the shared load is still
+ * unsettled. The shared load itself is never aborted — a fresh caller
+ * starting a new attempt for the same key re-fires
+ * {@link WorkflowSourceLoadStartedEvent}, not this event again for the
+ * orphaned attempt.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadCancelledEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadCancelledEvent.type, (event) => {
+ *   console.log('cancelled:', event.workflowType, event.revision);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadCancelledEvent extends Event {
+    static readonly type: "workflow-source:load-cancelled";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind);
+}
+export {};

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

@@ -0,0 +1,57 @@
+export class WorkflowSourceLoadStartedEvent extends Event {
+  static type = "workflow-source:load-started";
+  workflowType;
+  revision;
+  kind;
+  constructor(workflowType, revision, kind) {
+    super(WorkflowSourceLoadStartedEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.kind = kind;
+  }
+}
+
+export class WorkflowSourceLoadReadyEvent extends Event {
+  static type = "workflow-source:load-ready";
+  workflowType;
+  revision;
+  kind;
+  loadDurationMs;
+  constructor(workflowType, revision, kind, loadDurationMs) {
+    super(WorkflowSourceLoadReadyEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.kind = kind;
+    this.loadDurationMs = loadDurationMs;
+  }
+}
+
+export class WorkflowSourceLoadFailedEvent extends Event {
+  static type = "workflow-source:load-failed";
+  workflowType;
+  revision;
+  kind;
+  loadDurationMs;
+  failureCategory;
+  constructor(workflowType, revision, kind, loadDurationMs, failureCategory) {
+    super(WorkflowSourceLoadFailedEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.kind = kind;
+    this.loadDurationMs = loadDurationMs;
+    this.failureCategory = failureCategory;
+  }
+}
+
+export class WorkflowSourceLoadCancelledEvent extends Event {
+  static type = "workflow-source:load-cancelled";
+  workflowType;
+  revision;
+  kind;
+  constructor(workflowType, revision, kind) {
+    super(WorkflowSourceLoadCancelledEvent.type);
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.kind = kind;
+  }
+}

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

@@ -85,6 +85,13 @@ export interface ExecutionStrategy extends Disposable, AsyncDisposable {
     startWorkflow(parameters: {
         workflowId: string;
         workflowExecutionToken?: string;
+        /**
+         * The starting run's persisted `WorkflowState.revision` (WFT-20). Threaded
+         * through to the worker strategy's outbound echo/validation; an inline
+         * strategy accepts and ignores it — inline execution crosses no trust
+         * boundary this field needs to police.
+         */
+        revision?: string;
         workflowType: string;
         input: unknown;
         checkpoint: ArrayBuffer | Uint8Array;

package/dist/core/inline-execution-strategy.context-options.d.ts

@@ -11,7 +11,7 @@ import type { SearchAttributeSchema, WorkflowFunction } from './types.ts';
 import type { WorkflowLogRecord } from './types/workflow-log.ts';
 /** Capabilities the engine injects into the inline strategy at construction. */
 export interface InlineExecutionDependencies {
-    getRegistration: (workflowType: string) => {
+    getRegistration: (workflowType: string, workflowId: string) => {
         handler: WorkflowFunction;
         version: string;
         searchAttributes?: SearchAttributeSchema;

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

@@ -30,7 +30,7 @@ export class InlineExecutionStrategy {
     this.#messageHandler = handler;
   }
   startWorkflow(parameters) {
-    const registration = this.#dependencies.getRegistration(parameters.workflowType);
+    const registration = this.#dependencies.getRegistration(parameters.workflowType, parameters.workflowId);
     if (!registration) {
       this.#emit({
         type: "failed",

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/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' | 'ApplicationCommandValidationError' | 'MailboxContentionError' | 'ApplicationDeliveryValidationError' | 'OutboxContentionError' | 'WaitBudgetElapsedError' | 'WorkflowCatalogConflictError' | 'WorkflowRevisionNotInstalledError' | 'WorkflowSourceValidationError';
+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

@@ -55,7 +55,10 @@ const publicWeftErrorCodeMap = {
   WaitBudgetElapsedError: !0,
   WorkflowCatalogConflictError: !0,
   WorkflowRevisionNotInstalledError: !0,
-  WorkflowSourceValidationError: !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;

package/dist/core/worker-turn-watchdog.js

@@ -7,7 +7,7 @@ export class WorkerTurnWatchdog {
     this.#timeoutMs = timeoutMs;
     this.#onTimeout = onTimeout;
   }
-  begin(worker, workflowId, turnId, kind, timeoutMs = this.#timeoutMs) {
+  begin(worker, workflowId, turnId, kind, timeoutMs = this.#timeoutMs, revision) {
     this.clear(worker);
     const resolvedTimeoutMs = this.#timeoutResolverForTesting?.({ workflowId, kind }) ?? timeoutMs, turn = {
       worker,
@@ -15,7 +15,8 @@ export class WorkerTurnWatchdog {
       turnId,
       kind,
       timeoutMs: resolvedTimeoutMs,
-      timeout: null
+      timeout: null,
+      ...revision !== void 0 && { revision }
     };
     if (resolvedTimeoutMs !== void 0)
       turn.timeout = setTimeout(() => {

package/dist/diagnostics/format.js

@@ -95,6 +95,11 @@ export function formatVersionCheckReport(report) {
     lines.push(`${typeReport.type} (${typeReport.storedVersion} \u2192 ${typeReport.registeredVersion}):`);
     lines.push(`  ${typeReport.runningCount} running workflows`);
     lines.push(`  Compatibility: ${typeReport.compatibility}`);
+    const revisionEntries = Object.entries(typeReport.revisionCounts);
+    if (revisionEntries.length > 0 || typeReport.unpinnedRunningCount > 0) {
+      const revisionSummary = revisionEntries.map(([revision, count]) => `${revision} (${count})`).concat(typeReport.unpinnedRunningCount > 0 ? [`unpinned (${typeReport.unpinnedRunningCount})`] : []).join(", ");
+      lines.push(`  Revisions: ${revisionSummary}`);
+    }
     lines.push("");
   }
   switch (report.overallVerdict) {

package/dist/diagnostics/types.d.ts

@@ -148,6 +148,30 @@ export interface WorkflowTypeReport {
     registeredVersion: string;
     runningCount: number;
     compatibility: VersionCompatibility;
+    /**
+     * Count of active (running/pending) workflows for this type that carry a
+     * persisted `WorkflowState.revision`, broken down by that EXACT revision
+     * — the exact executable artifact each run started against, distinct
+     * from `storedVersion` (the semantic `versionTuple.workflowVersion`,
+     * which many revisions can share, e.g. a documentation-only redeploy).
+     *
+     * Deliberately holds only real, persisted revision values — a dynamic
+     * source's `revision` is any non-empty, bounded string with no reserved
+     * values, so folding "no persisted revision" into this same map under a
+     * sentinel key could collide with a genuinely pinned run that happens to
+     * use that literal string. A run with no persisted revision (a
+     * pre-revision-pinning record) is counted separately, in
+     * {@link WorkflowTypeReport.unpinnedRunningCount}.
+     */
+    revisionCounts: Record<string, number>;
+    /**
+     * Count of active (running/pending) workflows for this type with no
+     * persisted `WorkflowState.revision` — a record written before
+     * per-run revision pinning existed (WFT-17). Kept out of
+     * {@link WorkflowTypeReport.revisionCounts} so it can never collide with
+     * a genuinely pinned revision that happens to share the same string.
+     */
+    unpinnedRunningCount: number;
 }
 /**
  * Deployment-safety report produced by `weft version:check`.