@lostgradient/weft 0.24.0 → 0.24.2

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/start-workflow-validation.d.ts

@@ -14,6 +14,21 @@ export declare class StartWorkflowValidationError extends WeftError<'StartWorkfl
 }
 export declare const assertExclusiveStartWorkflowOptions: (startAt: unknown, startAfter: unknown) => void;
 export declare const coerceStartWorkflowId: (value: unknown, fieldName: string) => string;
+/**
+ * Coerce a caller-supplied `options.id` for an internal REPLAY of a start
+ * that was already accepted once before (WFT-95). Deliberately uses the
+ * decode-compatible {@link assertDecodableWorkflowId}, not the strict
+ * `.`/`..`-rejecting {@link assertValidWorkflowId} that
+ * {@link coerceStartWorkflowId} enforces: this path exists only for the three
+ * internal callers that replay an id which was already durably admitted
+ * before strict admission existed (a drained schedule queued-run, a bulk
+ * failed-workflow retry rebuilding from persisted input, or a child-workflow
+ * crash-reattach) — see `startWorkflow`'s `skipAdmissionIdCheck` parameter.
+ * It must never be reachable from a public start surface (REST, JSON-RPC,
+ * `engine.start`, `ctx.startChild`), because that would let a genuinely
+ * fresh caller admit `.`/`..` again.
+ */
+export declare const coerceReplayWorkflowId: (value: unknown, fieldName: string) => string;
 /**
  * Coerce a transport-supplied idempotency key to a non-empty string. The key is
  * a caller-chosen dedup token (it becomes part of a `start-idem:` storage key),

package/dist/core/start-workflow-validation.js

@@ -1,6 +1,6 @@
 import { parseDuration } from "./scheduler.js";
 import { WeftError } from "./weft-error.js";
-import { assertValidWorkflowId } from "./workflow-identifiers.js";
+import { assertDecodableWorkflowId, assertValidWorkflowId } from "./workflow-identifiers.js";
 export const MAX_WORKFLOW_TAGS = 32, MAX_WORKFLOW_TAG_BYTES = 128, MAX_IDEMPOTENCY_KEY_BYTES = 117;
 const textEncoder = new TextEncoder, EXCLUSIVE_START_WORKFLOW_OPTIONS_ERROR = "Provide only one of startAt or startAfter";
 
@@ -22,6 +22,16 @@ export const assertExclusiveStartWorkflowOptions = (startAt, startAfter) => {
     const message = error instanceof Error ? error.message : String(error);
     throw new StartWorkflowValidationError(message);
   }
+}, coerceReplayWorkflowId = (value, fieldName) => {
+  if (typeof value !== "string")
+    throw new StartWorkflowValidationError(`${fieldName} must be a string`);
+  try {
+    assertDecodableWorkflowId(value, fieldName);
+    return value;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new StartWorkflowValidationError(message);
+  }
 }, coerceStartWorkflowIdempotencyKey = (value, fieldName) => {
   if (typeof value !== "string")
     throw new StartWorkflowValidationError(`${fieldName} must be a string`);

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/core/workflow-identifiers.d.ts

@@ -1 +1,38 @@
+/**
+ * Assert every workflow-id constraint that predates WFT-95: a string,
+ * non-empty, at most {@link MAX_WORKFLOW_ID_LENGTH} characters, and free of
+ * control characters. Deliberately does NOT reject the exact strings `.` or
+ * `..` — those were valid workflow ids before WFT-95 and may already be
+ * durably persisted (a schedule id, a persisted `currentWorkflowId`, a
+ * queued run's `workflowId`, schedule-run metadata, an `executionStateOwnerId`
+ * or `parentWorkflowId`/`restartedFrom.workflowId` on a decoded
+ * `WorkflowState`). Decode and schedule-control (lookup, pause, resume,
+ * cancel, update) paths must keep accepting them so an upgrade doesn't
+ * strand pre-existing data or make a pre-existing schedule/workflow
+ * unmanageable; only fresh admission ({@link assertValidWorkflowId}) adds
+ * the `.`/`..` rejection.
+ *
+ * Takes `unknown`, not `string` (WFT-95 review): every caller passes an
+ * already-decoded field whose static `WorkflowState`/`ScheduleState` type
+ * says `string` but whose runtime shape is untrusted — the storage record
+ * could be corrupted. Without an explicit `typeof` guard here, a decoded
+ * array of strings would pass (`.length`, iteration, and
+ * `containsControlCharacter()`'s per-element `codePointAt()` all succeed on
+ * an array too), silently accepting a malformed field instead of dropping
+ * it — the same guard `coerceStartWorkflowId()` performed before this
+ * predicate existed.
+ */
+export declare function assertDecodableWorkflowId(id: unknown, fieldName?: string): asserts id is string;
+/** Whether `id` satisfies {@link assertDecodableWorkflowId}. */
+export declare function isDecodableWorkflowId(id: unknown): boolean;
+/**
+ * Whether `id` is exactly `.` or `..` — the two literals
+ * {@link assertValidWorkflowId} rejects at fresh admission (WFT-95). Exported
+ * so callers that need to recognize "this id is the one strict admission
+ * would reject" without re-running the full assertion (for example, to
+ * decide whether a caller-facing id MIGHT be a legacy pre-WFT-95 record
+ * worth checking storage for) share one definition instead of re-deriving
+ * the literal comparison.
+ */
+export declare function isReservedWorkflowIdLiteral(id: string): boolean;
 export declare function assertValidWorkflowId(id: string, fieldName?: string): void;

package/dist/core/workflow-identifiers.js

@@ -9,7 +9,9 @@ function containsControlCharacter(value) {
   }
   return !1;
 }
-export function assertValidWorkflowId(id, fieldName = "options.id") {
+export function assertDecodableWorkflowId(id, fieldName = "options.id") {
+  if (typeof id !== "string")
+    throw Error(`${fieldName} must be a string`);
   if (id.length === 0)
     throw Error(`${fieldName} must not be an empty string`);
   if (id.length > MAX_WORKFLOW_ID_LENGTH)
@@ -17,3 +19,19 @@ export function assertValidWorkflowId(id, fieldName = "options.id") {
   if (containsControlCharacter(id))
     throw Error(`${fieldName} must not contain control characters`);
 }
+export function isDecodableWorkflowId(id) {
+  try {
+    assertDecodableWorkflowId(id);
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+export function isReservedWorkflowIdLiteral(id) {
+  return id === "." || id === "..";
+}
+export function assertValidWorkflowId(id, fieldName = "options.id") {
+  if (isReservedWorkflowIdLiteral(id))
+    throw Error(`${fieldName} must not be "." or ".."`);
+  assertDecodableWorkflowId(id, fieldName);
+}

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`.