@lostgradient/weft 0.24.0 → 0.24.1

package/dist/server/operations/get-task-diagnostics.d.ts

@@ -60,8 +60,8 @@ declare const taskDiagnosticItemSchema: z.ZodUnion<readonly [z.ZodObject<{
     }>;
     state: z.ZodEnum<{
         "dead-lettered": "dead-lettered";
-        queued: "queued";
         resolved: "resolved";
+        queued: "queued";
         inflight: "inflight";
         capacity: "capacity";
     }>;
@@ -122,8 +122,8 @@ declare const getTaskDiagnosticsOutput: z.ZodObject<{
         }>;
         state: z.ZodEnum<{
             "dead-lettered": "dead-lettered";
-            queued: "queued";
             resolved: "resolved";
+            queued: "queued";
             inflight: "inflight";
             capacity: "capacity";
         }>;
@@ -217,7 +217,7 @@ export declare function createGetTaskDiagnosticsOperation(options?: GetTaskDiagn
 }, {
     items: ({
         kind: "dead-lettered" | "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
-        state: "dead-lettered" | "queued" | "resolved" | "inflight" | "capacity";
+        state: "dead-lettered" | "resolved" | "queued" | "inflight" | "capacity";
         retryCount: number;
         requeueCount: number;
         evidence: string[];
@@ -279,7 +279,7 @@ export declare const getTaskDiagnosticsOperation: import("../operation-catalog.t
 }, {
     items: ({
         kind: "dead-lettered" | "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
-        state: "dead-lettered" | "queued" | "resolved" | "inflight" | "capacity";
+        state: "dead-lettered" | "resolved" | "queued" | "inflight" | "capacity";
         retryCount: number;
         requeueCount: number;
         evidence: string[];

package/dist/server/operations/preload-workflow-revision.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `weft.workflows.revisions.preload` operation + REST binding.
+ *
+ * Loads, validates, and installs one dynamic workflow source revision
+ * previously recorded via `engine.registerSource()` — a thin, documented
+ * exposure of `engine.workflows.preload()` (WFT-15/16). Modeled on
+ * `install-workflow-revision.ts` / `activate-workflow-revision.ts`.
+ *
+ * @module server/operations/preload-workflow-revision
+ */
+import { z } from 'zod';
+import type { WorkflowRevisionRecord } from '../../core/catalog/index.ts';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const preloadWorkflowRevisionInput: z.ZodObject<{
+    name: z.ZodUnknown;
+    revision: z.ZodUnknown;
+}, z.core.$strip>;
+export type PreloadWorkflowRevisionInput = z.infer<typeof preloadWorkflowRevisionInput>;
+export type PreloadWorkflowRevisionOutput = WorkflowRevisionRecord;
+export declare const preloadWorkflowRevisionOperation: import("../operation-catalog.ts").OperationDefinition<{
+    name: unknown;
+    revision: unknown;
+}, Readonly<{
+    manifest: import("../../index.ts").WorkflowRevisionManifest;
+    installedAt: number;
+}>, unknown>;
+export declare const preloadWorkflowRevisionRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/preload-workflow-revision.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { isWeftError } from "../../core/weft-error.js";
+import { defineOperation } from "../operation-registry.js";
+import {
+  readWorkflowCatalogRestBody,
+  throwWorkflowCatalogOperationFault,
+  validateWorkflowNameField,
+  validateWorkflowRevisionField,
+  workflowsAdminAccess
+} from "./workflow-catalog-operation-helpers.js";
+const preloadWorkflowRevisionInput = z.object({
+  name: z.unknown().describe("Workflow name. Runtime validation requires a wire-safe identifier."),
+  revision: z.unknown().describe("The registerSource()-registered revision to load, validate, and install. Runtime validation requires a non-empty string.")
+}), preloadWorkflowRevisionOutput = z.unknown();
+export const preloadWorkflowRevisionOperation = defineOperation({
+  name: "weft.workflows.revisions.preload",
+  mcpExposable: !1,
+  summary: "Load, validate, and install a registered dynamic workflow source revision",
+  description: "Load, validate, and install `(name, revision)` \u2014 previously recorded via " + "engine.registerSource() \u2014 durably into the workflow catalog. Faults NotFound when no " + "source was ever registered for this exact key, and Conflict when the load fails or the loaded module fails validation.",
+  destructive: !1,
+  tags: ["Workflow Catalog"],
+  inputSchema: preloadWorkflowRevisionInput,
+  outputSchema: preloadWorkflowRevisionOutput,
+  access: workflowsAdminAccess,
+  producibleFaults: ["InvalidParams", "NotFound", "Conflict"],
+  discoverable: !0,
+  transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    const e = engine, name = validateWorkflowNameField(input.name), revision = validateWorkflowRevisionField(input.revision);
+    try {
+      return await e.workflows.preload(name, revision);
+    } catch (error) {
+      if (!isWeftError(error))
+        throw {
+          code: "Conflict",
+          message: `Dynamic workflow source "${name}" revision "${revision}" failed to load.`,
+          data: { reason: "load-failed" }
+        };
+      return throwWorkflowCatalogOperationFault(error);
+    }
+  }
+}), preloadWorkflowRevisionRestBinding = {
+  method: "POST",
+  path: "/v1/registry/workflows/:name/preload",
+  pathParamNames: ["name"],
+  operationName: "weft.workflows.revisions.preload",
+  inputSources: {
+    name: { kind: "path", pathParam: "name" },
+    revision: { kind: "body-field", bodyField: "revision" }
+  },
+  extractInput: async (request, pathParams, context) => {
+    const body = await readWorkflowCatalogRestBody(request, context);
+    return {
+      name: pathParams.name ?? "",
+      revision: body.revision
+    };
+  },
+  success: { kind: "json", status: 200 }
+};

package/dist/server/operations/schedule-faults.d.ts

@@ -6,6 +6,7 @@ export type ScheduleMutableOptionsInput = {
     overlap?: unknown;
     backfill?: unknown;
     jitter?: unknown;
+    revisionPolicy?: unknown;
 };
 /** Validate the mutable schedule options shared by create and update. */
 export declare function validateScheduleMutableOptions(input: ScheduleMutableOptionsInput): ScheduleUpdateOptions;

package/dist/server/operations/schedule-faults.js

@@ -1,16 +1,19 @@
+import { WorkflowRevisionUnavailableError } from "../../core/engine/revision-errors.js";
 import {
   isValidScheduleOverlapPolicy,
+  isValidScheduleRevisionPolicy,
   normalizeScheduleUpdateOptions
 } from "../../core/engine/validation/schedule.js";
 import { invalidParamsFault } from "./operation-helpers.js";
 export { isOperationFault } from "./operation-helpers.js";
 export function validateScheduleMutableOptions(input) {
-  const description = validateScheduleDescription(input.description), overlap = validateScheduleOverlap(input.overlap), backfill = validateScheduleBackfill(input.backfill), jitter = validateScheduleJitter(input.jitter);
+  const description = validateScheduleDescription(input.description), overlap = validateScheduleOverlap(input.overlap), backfill = validateScheduleBackfill(input.backfill), jitter = validateScheduleJitter(input.jitter), revisionPolicy = validateScheduleRevisionPolicy(input.revisionPolicy);
   return {
     ...description !== void 0 ? { description } : {},
     ...overlap !== void 0 ? { overlap } : {},
     ...backfill !== void 0 ? { backfill } : {},
-    ...jitter !== void 0 ? { jitter } : {}
+    ...jitter !== void 0 ? { jitter } : {},
+    ...revisionPolicy !== void 0 ? { revisionPolicy } : {}
   };
 }
 function validateScheduleDescription(value) {
@@ -27,6 +30,13 @@ function validateScheduleOverlap(value) {
     throw invalidParamsFault('Field "overlap" must be one of skip, queue, cancel-running, allow');
   return value;
 }
+function validateScheduleRevisionPolicy(value) {
+  if (value === void 0)
+    return;
+  if (!isValidScheduleRevisionPolicy(value))
+    throw invalidParamsFault('Field "revisionPolicy" must be one of active-at-fire, pinned');
+  return value;
+}
 function validateScheduleBackfill(value) {
   if (value === void 0)
     return;
@@ -51,7 +61,25 @@ function formatJitterValidationMessage(message) {
   const enginePrefix = "Invalid options.jitter: ", hasEnginePrefix = message.startsWith(enginePrefix), wireDetail = (hasEnginePrefix ? message.slice(enginePrefix.length) : message).replaceAll("options.jitter", 'Field "jitter"');
   return hasEnginePrefix ? `Field "jitter" is invalid: ${wireDetail}` : wireDetail;
 }
+function mapRevisionUnavailableToFault(error) {
+  if (!(error instanceof WorkflowRevisionUnavailableError))
+    return;
+  return {
+    code: "Conflict",
+    message: error.message,
+    data: { reason: error.reason }
+  };
+}
+function isScheduleConflictMessage(normalizedMessage) {
+  return normalizedMessage.includes("already exists") || normalizedMessage.includes("cannot be resumed");
+}
+function isScheduleInvalidParamsMessage(message, normalizedMessage) {
+  return message.includes("Missing required field") || normalizedMessage.includes("must be") || normalizedMessage.includes("no workflow registered") || normalizedMessage.includes("cron") || normalizedMessage.includes("interval");
+}
 export function mapScheduleErrorToFault(scheduleId, error) {
+  const revisionFault = mapRevisionUnavailableToFault(error);
+  if (revisionFault !== void 0)
+    return revisionFault;
   const message = error instanceof Error ? error.message : String(error), normalizedMessage = message.toLowerCase();
   if (normalizedMessage.includes("not found"))
     return {
@@ -59,13 +87,13 @@ export function mapScheduleErrorToFault(scheduleId, error) {
       message,
       data: { resource: "schedule", identifier: scheduleId }
     };
-  if (normalizedMessage.includes("already exists") || normalizedMessage.includes("cannot be resumed"))
+  if (isScheduleConflictMessage(normalizedMessage))
     return {
       code: "Conflict",
       message,
       data: { reason: message }
     };
-  if (message.includes("Missing required field") || normalizedMessage.includes("must be") || normalizedMessage.includes("no workflow registered") || normalizedMessage.includes("cron") || normalizedMessage.includes("interval"))
+  if (isScheduleInvalidParamsMessage(message, normalizedMessage))
     return {
       code: "InvalidParams",
       message,

package/dist/server/operations/schedule-rest-body.d.ts

@@ -6,6 +6,7 @@ export type SharedScheduleRestFields = {
     readonly overlap: unknown;
     readonly backfill: unknown;
     readonly jitter: unknown;
+    readonly revisionPolicy: unknown;
 };
 export declare function parseScheduleRestBodyRequestRecord(request: Request, context?: RestInputContext): Promise<Record<string, unknown>>;
 export declare function extractSharedScheduleRestFields(record: Record<string, unknown>): SharedScheduleRestFields;

package/dist/server/operations/schedule-rest-body.js

@@ -23,6 +23,7 @@ export function extractSharedScheduleRestFields(record) {
     description: record.description,
     overlap: record.overlap,
     backfill: record.backfill,
-    jitter: record.jitter
+    jitter: record.jitter,
+    revisionPolicy: record.revisionPolicy
   };
 }

package/dist/server/operations/static-registrations.js

@@ -90,6 +90,10 @@ import {
 } from "./list-workflow-revisions.js";
 import { listWorkflowsOperation, listWorkflowsRestBinding } from "./list-workflows.js";
 import { pauseScheduleOperation, pauseScheduleRestBinding } from "./pause-schedule.js";
+import {
+  preloadWorkflowRevisionOperation,
+  preloadWorkflowRevisionRestBinding
+} from "./preload-workflow-revision.js";
 import { purgeWorkflowsOperation, purgeWorkflowsRestBinding } from "./purge-workflows.js";
 import {
   queryWorkflowOperation,
@@ -178,6 +182,7 @@ export const STATIC_REST_BINDINGS = [
   getRegistryRestBinding,
   installWorkflowRevisionRestBinding,
   activateWorkflowRevisionRestBinding,
+  preloadWorkflowRevisionRestBinding,
   getWorkflowRevisionRestBinding,
   listWorkflowRevisionsRestBinding,
   getActiveWorkflowRevisionRestBinding,
@@ -247,6 +252,7 @@ export const STATIC_REST_BINDINGS = [
   getRegistryOperation,
   installWorkflowRevisionOperation,
   activateWorkflowRevisionOperation,
+  preloadWorkflowRevisionOperation,
   getWorkflowRevisionOperation,
   listWorkflowRevisionsOperation,
   getActiveWorkflowRevisionOperation,

package/dist/server/operations/update-schedule.d.ts

@@ -8,6 +8,7 @@ declare const updateScheduleInput: z.ZodObject<{
     overlap: z.ZodOptional<z.ZodUnknown>;
     backfill: z.ZodOptional<z.ZodUnknown>;
     jitter: z.ZodOptional<z.ZodUnknown>;
+    revisionPolicy: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
 export type UpdateScheduleInput = z.infer<typeof updateScheduleInput>;
 export declare const updateScheduleOperation: import("../operation-catalog.ts").OperationDefinition<{
@@ -18,6 +19,7 @@ export declare const updateScheduleOperation: import("../operation-catalog.ts").
     overlap?: unknown;
     backfill?: unknown;
     jitter?: unknown;
+    revisionPolicy?: unknown;
 }, null, unknown>;
 export declare const updateScheduleRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/update-schedule.js

@@ -16,7 +16,8 @@ const updateScheduleInput = z.object({
   description: z.unknown().optional().describe("Operator-facing schedule description. Runtime validation requires a string."),
   overlap: z.unknown().optional(),
   backfill: z.unknown().optional(),
-  jitter: z.unknown().optional()
+  jitter: z.unknown().optional(),
+  revisionPolicy: z.unknown().optional().describe('Revision policy (WFT-20). Runtime validation requires "active-at-fire" or "pinned". Omitted preserves the current policy (and pin); "pinned" always re-resolves and re-captures the pin against the revision active right now.')
 });
 export const updateScheduleOperation = defineOperation({
   name: "weft.schedules.update",
@@ -52,7 +53,8 @@ export const updateScheduleOperation = defineOperation({
     description: { kind: "body-field", bodyField: "description" },
     overlap: { kind: "body-field", bodyField: "overlap" },
     backfill: { kind: "body-field", bodyField: "backfill" },
-    jitter: { kind: "body-field", bodyField: "jitter" }
+    jitter: { kind: "body-field", bodyField: "jitter" },
+    revisionPolicy: { kind: "body-field", bodyField: "revisionPolicy" }
   },
   extractInput: async (request, pathParams, context) => {
     const record = await parseScheduleRestBodyRequestRecord(request, context);

package/dist/server/operations/workflow-catalog-operation-helpers.js

@@ -5,7 +5,12 @@ import {
 } from "../../core/catalog/index.js";
 import { MAX_CONTRACT_IDENTIFIER_BYTES } from "../../core/contract/limits.js";
 import { parseWorkflowRevisionManifest } from "../../core/contract/manifest-parse.js";
+import {
+  DynamicWorkflowSourceUnavailableError,
+  WorkflowSourceNotRegisteredError
+} from "../../core/engine/dynamic-source-errors.js";
 import { WorkflowNotRegisteredError } from "../../core/engine/errors.js";
+import { WorkflowSourceValidationError } from "../../core/source/errors.js";
 import { validateWorkflowOrActivityName } from "../../core/types/name-grammar.js";
 import { readRestJsonBody } from "../rest-body.js";
 import { invalidParamsFault, isOperationFault } from "./operation-helpers.js";
@@ -121,6 +126,28 @@ export function throwWorkflowCatalogOperationFault(error) {
       message: error.message,
       data: { reason: "catalog-conflict", weftCode: error.code }
     };
+  if (error instanceof WorkflowSourceNotRegisteredError)
+    throw {
+      code: "NotFound",
+      message: error.message,
+      data: { resource: "workflow-source", identifier: error.workflowType, weftCode: error.code }
+    };
+  if (error instanceof DynamicWorkflowSourceUnavailableError)
+    throw {
+      code: "Conflict",
+      message: error.reason === "load-failed" ? `Dynamic workflow source "${error.workflowType}"${error.revision === void 0 ? "" : ` revision "${error.revision}"`} failed to load.` : error.message,
+      data: { reason: error.reason, weftCode: error.code }
+    };
+  if (error instanceof WorkflowSourceValidationError)
+    throw {
+      code: "Conflict",
+      message: error.message,
+      data: {
+        reason: "validation-failed",
+        sourceValidationReasons: error.reasons,
+        weftCode: error.code
+      }
+    };
   throw error;
 }
 export async function readWorkflowCatalogRestBody(request, context) {

package/dist/server/runtime/task-dispatch-envelope.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build the durable task-ledger envelope a fresh dispatch would create if no
+ * ledger record exists yet — split out of `task-dispatch.ts` purely to stay
+ * under this repository's 500-line-per-file ceiling, matching the existing
+ * `task-dispatch-revision.ts` precedent. There is no behavioral reason to
+ * import this module directly instead of `task-dispatch.ts`, which calls it
+ * from both `selectAndReserveWorker` and `enqueueTaskForLongPoll`.
+ *
+ * @module server/runtime/task-dispatch-envelope
+ */
+import type { TaskDispatch } from '../index.ts';
+import type { CreateQueuedInput } from '../task-ledger-transitions.ts';
+/** The durable envelope every fresh dispatch would create if no ledger record exists yet. */
+export declare function buildCreateQueuedInput(task: TaskDispatch, queue: string, visibilityTimeout: number): CreateQueuedInput;

package/dist/server/runtime/task-dispatch-envelope.js

@@ -0,0 +1,32 @@
+import { isJSONValue } from "../../core/json.js";
+import { isValidWorkflowRevision, REMOTE_TASK_RECORD_VERSION } from "../task-ledger.js";
+function buildOptionalCreateQueuedFields(task) {
+  return {
+    ...task.workflowId !== void 0 ? { workflowId: task.workflowId } : {},
+    ...task.workflowExecutionToken !== void 0 ? { workflowExecutionToken: task.workflowExecutionToken } : {},
+    ...task.workflowRevision !== void 0 ? { workflowRevision: task.workflowRevision } : {},
+    ...task.priority !== void 0 ? { priority: task.priority } : {},
+    ...task.fairShareKey !== void 0 ? { fairShareKey: task.fairShareKey } : {},
+    ...task.sticky && task.workflowId !== void 0 ? { stickyWorkflowId: task.workflowId } : {},
+    ...task.retryPolicy !== void 0 ? { retryPolicy: task.retryPolicy } : {}
+  };
+}
+export function buildCreateQueuedInput(task, queue, visibilityTimeout) {
+  const input = task.input === void 0 ? null : task.input;
+  if (!isJSONValue(input))
+    throw Error(`TaskDispatch for operation "${task.operationId}" has a non-JSON-serializable "input" \u2014 the durable task ledger requires JSON-safe input.`);
+  if (task.workflowRevision !== void 0 && !isValidWorkflowRevision(task.workflowRevision))
+    throw Error(`TaskDispatch for operation "${task.operationId}" has an invalid "workflowRevision" \u2014 it must be a non-empty, bounded identifier.`);
+  return {
+    recordVersion: REMOTE_TASK_RECORD_VERSION,
+    operationId: task.operationId,
+    workflowType: task.workflowType,
+    activityName: task.activityName,
+    queue,
+    input,
+    headers: task.headers ?? {},
+    visibilityTimeoutMilliseconds: visibilityTimeout,
+    createdAt: Date.now(),
+    ...buildOptionalCreateQueuedFields(task)
+  };
+}

package/dist/server/runtime/task-dispatch-revision.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Dispatch-time revision staleness gate (WFT-20) — split out of
+ * `task-dispatch.ts` purely to stay under this repository's 500-line-per-file
+ * ceiling; there is no behavioral reason to import this module directly
+ * instead of `task-dispatch.ts`, which calls it from `dispatchTaskImpl`.
+ *
+ * @module server/runtime/task-dispatch-revision
+ */
+import { type ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { ServeOptions, TaskDispatch } from '../index.ts';
+/**
+ * Reject a dispatch whose caller-supplied `workflowRevision` disagrees with
+ * `task.workflowId`'s persisted `WorkflowState.revision` — a bounded,
+ * structured failure BEFORE any worker reservation or ledger write. A no-op
+ * (never reads storage) unless BOTH `workflowId` and `workflowRevision` are
+ * supplied; a no-op when no persisted `WorkflowState` exists for `workflowId`
+ * yet (nothing to compare against — the caller opted into an extra read, not
+ * an extra existence requirement).
+ *
+ * Returns the `conditionalBatch` precondition(s) (empty when this check was a
+ * no-op) that fence the CALLER's own ledger commit on the exact workflow-state
+ * bytes just read here. This check alone is only a pre-commit read: a
+ * `start-new` restart could still displace the workflow to a different
+ * revision in the gap between this read and the caller's later ledger write.
+ * The caller MUST include the returned conditions in the SAME
+ * `conditionalBatch` call that commits the ledger record, so that gap closes
+ * atomically instead of merely being read-checked up front (WFT-20).
+ */
+export declare function assertDispatchTargetsFreshRevision(options: ServeOptions, task: TaskDispatch): Promise<ConditionalBatchCondition[]>;

package/dist/server/runtime/task-dispatch-revision.js

@@ -0,0 +1,13 @@
+import { decodeWorkflowState } from "../../core/engine/validation.js";
+import { KEYS } from "../../storage/interface.js";
+export async function assertDispatchTargetsFreshRevision(options, task) {
+  if (task.workflowId === void 0 || task.workflowRevision === void 0)
+    return [];
+  const workflowKey = KEYS.workflow(task.workflowId), persistedBytes = await options.engine.storage.get(workflowKey);
+  if (persistedBytes === null)
+    return [];
+  const persistedRevision = decodeWorkflowState(persistedBytes).revision;
+  if (persistedRevision !== task.workflowRevision)
+    throw Error(`TaskDispatch for operation "${task.operationId}" targets workflow "${task.workflowId}" at revision "${task.workflowRevision}", but the persisted run is pinned to revision ${persistedRevision === void 0 ? "undefined (a legacy, pre-pinning record)" : `"${persistedRevision}"`} ` + "\u2014 this dispatch is stale.");
+  return [{ key: workflowKey, expectedValue: persistedBytes }];
+}

package/dist/server/runtime/task-dispatch.js

@@ -1,4 +1,3 @@
-import { isJSONValue } from "../../core/json.js";
 import { buildWorkerExecutionIdentity } from "../../worker/manifest/execution-identity.js";
 import { evictOldestAffinityEntries } from "../runtime-helpers.js";
 import {
@@ -7,9 +6,10 @@ import {
 } from "../task-ledger-transitions.js";
 import {
   decodeRemoteTaskRecord,
-  REMOTE_TASK_RECORD_VERSION,
   taskLedgerKey
 } from "../task-ledger.js";
+import { buildCreateQueuedInput } from "./task-dispatch-envelope.js";
+import { assertDispatchTargetsFreshRevision } from "./task-dispatch-revision.js";
 import { commitTaskLedgerTransition } from "./task-ledger-runtime.js";
 import {
   recordTaskBacklogMetric,
@@ -65,33 +65,6 @@ function recordDispatchOutcome(context, task, workerId) {
   operationIds.add(task.operationId);
   context.operationToWorkflow.set(task.operationId, task.workflowId);
 }
-function buildOptionalCreateQueuedFields(task) {
-  return {
-    ...task.workflowId !== void 0 ? { workflowId: task.workflowId } : {},
-    ...task.workflowExecutionToken !== void 0 ? { workflowExecutionToken: task.workflowExecutionToken } : {},
-    ...task.priority !== void 0 ? { priority: task.priority } : {},
-    ...task.fairShareKey !== void 0 ? { fairShareKey: task.fairShareKey } : {},
-    ...task.sticky && task.workflowId !== void 0 ? { stickyWorkflowId: task.workflowId } : {},
-    ...task.retryPolicy !== void 0 ? { retryPolicy: task.retryPolicy } : {}
-  };
-}
-function buildCreateQueuedInput(task, queue, visibilityTimeout) {
-  const input = task.input === void 0 ? null : task.input;
-  if (!isJSONValue(input))
-    throw Error(`TaskDispatch for operation "${task.operationId}" has a non-JSON-serializable "input" \u2014 the durable task ledger requires JSON-safe input.`);
-  return {
-    recordVersion: REMOTE_TASK_RECORD_VERSION,
-    operationId: task.operationId,
-    workflowType: task.workflowType,
-    activityName: task.activityName,
-    queue,
-    input,
-    headers: task.headers ?? {},
-    visibilityTimeoutMilliseconds: visibilityTimeout,
-    createdAt: Date.now(),
-    ...buildOptionalCreateQueuedFields(task)
-  };
-}
 function buildCreateThenClaimTransition(createInput, claimInput) {
   return (current, now) => {
     let queuedRecord;
@@ -114,7 +87,7 @@ function bareActivityName(qualifiedActivityName) {
   const dotIndex = qualifiedActivityName.indexOf(".");
   return dotIndex === -1 ? qualifiedActivityName : qualifiedActivityName.slice(dotIndex + 1);
 }
-async function selectAndReserveWorker(context, options, task, queue, visibilityTimeout) {
+async function selectAndReserveWorker(context, options, task, queue, visibilityTimeout, revisionFenceConditions) {
   const routingOptions = buildRoutingOptions(context, task, queue), worker = context.registry.findWorker(task.activityName, routingOptions);
   if (!worker)
     return !1;
@@ -128,7 +101,7 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
     workflowType: task.workflowType,
     activityName: bareActivityName(task.activityName)
   });
-  context.registry.assignTask(worker.id, task.operationId, visibilityTimeout, task.fairShareKey, attemptToken);
+  context.registry.assignTask(worker.id, task.operationId, visibilityTimeout, task.fairShareKey, attemptToken, task.workflowRevision);
   let result;
   try {
     result = await commitTaskLedgerTransition(options.engine.storage, task.operationId, buildCreateThenClaimTransition(createInput, {
@@ -136,7 +109,7 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
       workerSessionId: worker.id,
       ...executionIdentity !== void 0 ? { executionIdentity } : {},
       leaseDurationMilliseconds: visibilityTimeout
-    }), 1);
+    }), 1, revisionFenceConditions);
   } catch (error) {
     context.registry.releaseReservation(task.operationId);
     throw error;
@@ -159,6 +132,7 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
     ...task.workflowExecutionToken !== void 0 && {
       workflowExecutionToken: task.workflowExecutionToken
     },
+    ...task.workflowRevision !== void 0 && { workflowRevision: task.workflowRevision },
     ...task.headers ? { headers: task.headers } : {}
   }));
   recordTaskQueueLatencyMetric(context.metricsCollector, {
@@ -169,11 +143,11 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
   recordDispatchOutcome(context, task, worker.id);
   return !0;
 }
-async function enqueueTaskForLongPoll(context, options, task, queue, visibilityTimeout, resolvedPriority) {
+async function enqueueTaskForLongPoll(context, options, task, queue, visibilityTimeout, resolvedPriority, revisionFenceConditions) {
   const storage = options.engine.storage, createInput = buildCreateQueuedInput(task, queue, visibilityTimeout), rawExisting = await storage.get(taskLedgerKey(task.operationId)), current = decodeRemoteTaskRecord(rawExisting);
   let queuedRecord;
   if (current === null) {
-    const result = await commitTaskLedgerTransition(storage, task.operationId, (freshCurrent, now) => createQueued(freshCurrent, createInput, now), 1);
+    const result = await commitTaskLedgerTransition(storage, task.operationId, (freshCurrent, now) => createQueued(freshCurrent, createInput, now), 1, revisionFenceConditions);
     if (!result.ok) {
       const raced = decodeRemoteTaskRecord(await storage.get(taskLedgerKey(task.operationId)));
       if (raced === null || raced.state !== "queued")
@@ -194,6 +168,7 @@ async function enqueueTaskForLongPoll(context, options, task, queue, visibilityT
     visibilityTimeout,
     workflowId: task.workflowId,
     workflowExecutionToken: task.workflowExecutionToken,
+    workflowRevision: queuedRecord.workflowRevision,
     firstQueuedAt: queuedRecord.firstQueuedAt,
     lastQueuedAt: queuedRecord.lastQueuedAt,
     lastDispatchedAt: queuedRecord.lastDispatchedAt,
@@ -214,15 +189,15 @@ export async function dispatchTaskImpl(context, options, task) {
   }
   if (!task.workflowType)
     throw Error(`TaskDispatch for operation "${task.operationId}" is missing required field "workflowType".`);
-  const dotIndex = task.activityName.indexOf(".");
+  const revisionFenceConditions = await assertDispatchTargetsFreshRevision(options, task), dotIndex = task.activityName.indexOf(".");
   if (dotIndex !== -1 && task.activityName.slice(0, dotIndex) !== task.workflowType)
     throw Error(`TaskDispatch for operation "${task.operationId}" has activityName "${task.activityName}" whose qualifier does not match workflowType "${task.workflowType}".`);
   const queue = task.queue ?? "default", visibilityTimeout = clampVisibilityTimeout(task.visibilityTimeout), resolvedPriority = resolveTaskPriority(context, options, task);
   if (!validateTaskEnvelope(context, task))
     return !1;
-  if (await selectAndReserveWorker(context, options, task, queue, visibilityTimeout))
+  if (await selectAndReserveWorker(context, options, task, queue, visibilityTimeout, revisionFenceConditions))
     return !0;
-  return enqueueTaskForLongPoll(context, options, task, queue, visibilityTimeout, resolvedPriority);
+  return enqueueTaskForLongPoll(context, options, task, queue, visibilityTimeout, resolvedPriority, revisionFenceConditions);
 }
 export function cancelTask(context, operationId) {
   const task = context.registry.getTask(operationId);

package/dist/server/runtime/task-ledger-recovery.js

@@ -16,7 +16,7 @@ function rebuildWorkflowIndex(context, operationId, workflowId) {
 }
 function rehydrateWorkerOwnership(context, record, now) {
   const remaining = Math.max(0, record.leaseDeadline - now);
-  context.registry.assignTask(record.workerSessionId, record.operationId, remaining, record.fairShareKey, record.attemptToken);
+  context.registry.assignTask(record.workerSessionId, record.operationId, remaining, record.fairShareKey, record.attemptToken, record.workflowRevision);
   const tracked = context.registry.getWorkerTasks(record.workerSessionId).find((task) => task.operationId === record.operationId);
   if (tracked)
     tracked.visibilityTimeout = record.visibilityTimeoutMilliseconds;

package/dist/server/runtime/task-ledger-runtime.d.ts

@@ -16,7 +16,7 @@
  *
  * @module server/runtime/task-ledger-runtime
  */
-import { type Storage } from '../../storage/interface.ts';
+import { type ConditionalBatchCondition, type Storage } from '../../storage/interface.ts';
 import type { TaskLedgerPreconditionResult, TaskLedgerTransitionResult } from '../task-ledger-transitions.ts';
 import { type RemoteTaskRecord } from '../task-ledger.ts';
 export type TaskLedgerCommitResult<T extends RemoteTaskRecord> = Readonly<{
@@ -46,7 +46,19 @@ export type TaskLedgerDeleteResult = Readonly<{
  * reflects reality and re-attempting the identical transition cannot change
  * the outcome.
  */
-export declare function commitTaskLedgerTransition<T extends RemoteTaskRecord>(storage: Storage, operationId: string, transitionFn: (current: RemoteTaskRecord | null, now: number) => TaskLedgerTransitionResult<T>, maxAttempts?: number): Promise<TaskLedgerCommitResult<T>>;
+export declare function commitTaskLedgerTransition<T extends RemoteTaskRecord>(storage: Storage, operationId: string, transitionFn: (current: RemoteTaskRecord | null, now: number) => TaskLedgerTransitionResult<T>, maxAttempts?: number, 
+/**
+ * Extra same-transaction preconditions to fence the commit on — for
+ * example, "the target workflow's persisted state is still exactly the
+ * bytes read at dispatch time" (WFT-20's revision-staleness gate). Checked
+ * in the SAME `conditionalBatch` call as the ledger key's own CAS, so a
+ * concurrent write to any of these keys between read and commit loses the
+ * whole batch atomically, closing the gap a standalone pre-check
+ * (read-then-later-write, with unrelated work in between) cannot close.
+ * Re-supplied by the caller on each retry attempt since the caller, not
+ * this loop, owns re-reading whatever these conditions guard.
+ */
+additionalConditions?: readonly ConditionalBatchCondition[]): Promise<TaskLedgerCommitResult<T>>;
 /**
  * Read the current ledger record, check a delete-only precondition (WFT-24
  * retention: {@link canDeleteRetainedTerminalTask}), and conditionally delete

package/dist/server/runtime/task-ledger-runtime.js

@@ -1,16 +1,18 @@
-import { storageConditionalBatch } from "../../storage/interface.js";
+import {
+  storageConditionalBatch
+} from "../../storage/interface.js";
 import {
   decodeRemoteTaskRecord,
   encodeRemoteTaskRecord,
   taskLedgerKey
 } from "../task-ledger.js";
-export async function commitTaskLedgerTransition(storage, operationId, transitionFn, maxAttempts = 1) {
+export async function commitTaskLedgerTransition(storage, operationId, transitionFn, maxAttempts = 1, additionalConditions = []) {
   const key = taskLedgerKey(operationId);
   for (let attempt = 1;attempt <= maxAttempts; attempt++) {
     const rawExisting = await storage.get(key), current = decodeRemoteTaskRecord(rawExisting), result = transitionFn(current, Date.now());
     if (!result.ok)
       return result;
-    if (await storageConditionalBatch(storage, [{ key, expectedValue: rawExisting }], [{ type: "put", key, value: encodeRemoteTaskRecord(result.nextRecord) }]))
+    if (await storageConditionalBatch(storage, [{ key, expectedValue: rawExisting }, ...additionalConditions], [{ type: "put", key, value: encodeRemoteTaskRecord(result.nextRecord) }]))
       return { ok: !0, record: result.nextRecord };
   }
   return {