@lostgradient/weft 0.23.1 → 0.24.1

package/dist/server/operations/workflow-catalog-operation-helpers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared validation and fault mapping for the five `weft.workflows.revisions.*`
+ * / `weft.workflows.active.*` operations (WFT-11): `install-workflow-revision.ts`,
+ * `activate-workflow-revision.ts`, `get-workflow-revision.ts`,
+ * `list-workflow-revisions.ts`, `get-active-workflow-revision.ts`.
+ *
+ * @module server/operations/workflow-catalog-operation-helpers
+ */
+import { type WorkflowCatalogActivationResult } from '../../core/catalog/index.ts';
+import type { WorkflowCompatibilityPolicy } from '../../core/contract/compatibility.ts';
+import type { WorkflowRevisionManifest } from '../../core/contract/types.ts';
+import type { AccessPolicy } from '../authorization.ts';
+import type { OperationFault } from '../operation-fault.ts';
+import type { RestInputContext } from '../rest-binding.ts';
+/** `workflows:admin` — required by `install` and `activate` (mutating). */
+export declare const workflowsAdminAccess: AccessPolicy;
+/** `workflows:read` — required by `get`/`list`/`active.get` (read-only). */
+export declare const workflowsReadAccess: AccessPolicy;
+/**
+ * Validate one `name` field per the wire-safe name grammar, raising the
+ * same `InvalidParams` fault both REST and JSON-RPC callers see for every
+ * other malformed identifier in this operation family. Bounded by
+ * `validateWorkflowOrActivityName` itself (`MAX_CONTRACT_IDENTIFIER_BYTES`).
+ */
+export declare function validateWorkflowNameField(name: unknown): string;
+/** Validate one `revision` field: a non-empty, bounded opaque string. */
+export declare function validateWorkflowRevisionField(revision: unknown): string;
+/** Validate an optional `expectedGeneration` field: a non-negative safe integer. */
+export declare function validateExpectedGenerationField(value: unknown): number | undefined;
+/** Validate an optional `policy` field against the one tunable compatibility axis. */
+export declare function validatePolicyField(value: unknown): WorkflowCompatibilityPolicy | undefined;
+/**
+ * Validate an untrusted `manifest` field via {@link parseWorkflowRevisionManifest} —
+ * the same hostile-input validation path (bounded sizes, recomputed
+ * `contractHash`) every other manifest consumer in this codebase uses.
+ */
+export declare function validateManifestField(value: unknown): Promise<WorkflowRevisionManifest>;
+/**
+ * Map one `applied: false` {@link WorkflowCatalogActivationResult} variant to
+ * the canonical `Conflict` fault. Exhaustive over all four refusal reasons —
+ * adding a fifth is a compile error here, forcing a deliberate wire mapping.
+ */
+export declare function activationRefusalToFault(result: Extract<WorkflowCatalogActivationResult, {
+    applied: false;
+}>): OperationFault;
+/**
+ * Map an error thrown by `engine.workflows.install()`/`activate()` to the
+ * canonical operation fault, or rethrow unchanged when it is neither typed
+ * error this family can produce (letting the operation pipeline's generic
+ * `EngineFailure` wrapping handle anything else).
+ */
+export declare function throwWorkflowCatalogOperationFault(error: unknown): never;
+/**
+ * Read a REST request body as a JSON object, raising `InvalidParams` for
+ * malformed JSON or a non-object top-level value — shared by
+ * `install-workflow-revision.ts` (body-only) and
+ * `activate-workflow-revision.ts` (path `name` plus body fields).
+ */
+export declare function readWorkflowCatalogRestBody(request: Request, context: RestInputContext): Promise<Record<string, unknown>>;

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

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import {
+  WorkflowCatalogConflictError,
+  WorkflowRevisionNotInstalledError
+} 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";
+export const workflowsAdminAccess = {
+  kind: "scoped",
+  scopes: { kind: "anyOf", scopes: ["workflows:admin"] }
+}, workflowsReadAccess = {
+  kind: "scoped",
+  scopes: { kind: "anyOf", scopes: ["workflows:read"] }
+};
+export function validateWorkflowNameField(name) {
+  if (typeof name !== "string" || name.length === 0)
+    throw invalidParamsFault('Field "name" must be a non-empty string');
+  try {
+    validateWorkflowOrActivityName(name, "workflow");
+  } catch (error) {
+    throw invalidParamsFault(error instanceof Error ? error.message : String(error));
+  }
+  return name;
+}
+export function validateWorkflowRevisionField(revision) {
+  if (typeof revision !== "string" || revision.length === 0)
+    throw invalidParamsFault('Field "revision" must be a non-empty string');
+  if (new TextEncoder().encode(revision).byteLength > MAX_CONTRACT_IDENTIFIER_BYTES)
+    throw invalidParamsFault(`Field "revision" exceeds the maximum identifier size of ${String(MAX_CONTRACT_IDENTIFIER_BYTES)} bytes`);
+  return revision;
+}
+export function validateExpectedGenerationField(value) {
+  if (value === void 0)
+    return;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+    throw invalidParamsFault('Field "expectedGeneration" must be a non-negative integer');
+  return value;
+}
+const compatibilityPolicyShape = z.object({ requireExactRevision: z.boolean().optional() }).strict();
+export function validatePolicyField(value) {
+  if (value === void 0)
+    return;
+  const parsed = compatibilityPolicyShape.safeParse(value);
+  if (!parsed.success)
+    throw invalidParamsFault('Field "policy" must be an object with an optional boolean "requireExactRevision"');
+  return parsed.data.requireExactRevision === void 0 ? {} : { requireExactRevision: parsed.data.requireExactRevision };
+}
+export async function validateManifestField(value) {
+  const result = await parseWorkflowRevisionManifest(value);
+  if (!result.ok)
+    throw manifestValidationFailureFault(result);
+  return result.manifest;
+}
+function manifestValidationFailureFault(failure) {
+  return {
+    code: "InvalidParams",
+    message: failure.message,
+    data: {
+      issues: [
+        {
+          path: failure.path === void 0 ? [] : failure.path.split("."),
+          message: failure.message,
+          code: failure.reason
+        }
+      ]
+    }
+  };
+}
+export function activationRefusalToFault(result) {
+  switch (result.reason) {
+    case "incompatible": {
+      const { verdict } = result, reasons = verdict.compatible ? [] : verdict.reasons;
+      return {
+        code: "Conflict",
+        message: `Candidate revision is incompatible with the currently active revision: ${reasons.join(", ")}`,
+        data: { reason: result.reason, compatibilityReasons: reasons }
+      };
+    }
+    case "stale-generation":
+      return {
+        code: "Conflict",
+        message: `Stale expectedGeneration: the current durable generation is ${String(result.currentGeneration)}`,
+        data: { reason: result.reason, currentGeneration: result.currentGeneration }
+      };
+    case "expected-generation-required":
+      return {
+        code: "Conflict",
+        message: "expectedGeneration is required once a workflow has an active revision \u2014 current " + `generation is ${String(result.currentGeneration)}`,
+        data: { reason: result.reason, currentGeneration: result.currentGeneration }
+      };
+    case "conflict":
+      return {
+        code: "Conflict",
+        message: "Activation lost a concurrent write race; re-read the active pointer and retry",
+        data: { reason: result.reason }
+      };
+    default:
+      throw Error(`Unknown activation refusal reason: ${JSON.stringify(result)}`);
+  }
+}
+export function throwWorkflowCatalogOperationFault(error) {
+  if (error instanceof WorkflowRevisionNotInstalledError)
+    throw {
+      code: "NotFound",
+      message: error.message,
+      data: {
+        resource: "workflow-revision",
+        identifier: `${error.workflowName}:${error.revision}`,
+        weftCode: error.code
+      }
+    };
+  if (error instanceof WorkflowNotRegisteredError)
+    throw invalidParamsFault(error.message, error.code);
+  if (error instanceof WorkflowCatalogConflictError)
+    throw {
+      code: "Conflict",
+      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) {
+  const body = await readRestJsonBody(request, context).catch((error) => {
+    if (isOperationFault(error))
+      throw error;
+    return null;
+  });
+  if (typeof body !== "object" || body === null || Array.isArray(body))
+    throw invalidParamsFault("Request body must be a JSON object.");
+  return body;
+}

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 {

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

@@ -58,7 +58,8 @@ function validateTaskResultBody(body) {
     workerId: typeof body.workerId === "string" ? body.workerId : void 0,
     value: body.value,
     error: typeof body.error === "string" ? body.error : void 0,
-    attemptToken: rawAttemptToken
+    attemptToken: rawAttemptToken,
+    workflowRevision: typeof body.workflowRevision === "string" ? body.workflowRevision : void 0
   };
 }
 function isLongPollCompletionAuthorized(record, validated) {
@@ -68,7 +69,11 @@ function isLongPollCompletionAuthorized(record, validated) {
     return !1;
   if (validated.workerId === void 0 || record.workerSessionId !== validated.workerId)
     return !1;
-  return validated.attemptToken === record.attemptToken;
+  if (validated.attemptToken !== record.attemptToken)
+    return !1;
+  if (record.workflowRevision !== void 0 && validated.workflowRevision !== record.workflowRevision)
+    return !1;
+  return !0;
 }
 async function applyTaskResult(context, options, result) {
   const { operationId, status, value, error } = result, committed = await commitTaskLedgerCompletion(options.engine.storage, {
@@ -155,7 +160,8 @@ export async function handleTaskPollRequest(context, options, request, url, prin
       attemptToken: claim.attemptToken,
       ...task.workflowExecutionToken !== void 0 && {
         workflowExecutionToken: task.workflowExecutionToken
-      }
+      },
+      ...task.workflowRevision !== void 0 && { workflowRevision: task.workflowRevision }
     });
   }
   return new Response(null, { status: 204 });

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

@@ -65,7 +65,8 @@ export function taskDispatchFromLedgerRecord(record) {
     input: record.input,
     queue: record.queue,
     visibilityTimeout: record.visibilityTimeoutMilliseconds,
-    workflowExecutionToken: record.workflowExecutionToken
+    workflowExecutionToken: record.workflowExecutionToken,
+    workflowRevision: record.workflowRevision
   };
   if (record.workflowId !== void 0)
     taskDispatch.workflowId = record.workflowId;

package/dist/server/runtime/websocket-upgrade.js

@@ -69,6 +69,8 @@ function upgradeScope(connectionType) {
     case "generic":
     case void 0:
       return null;
+    default:
+      throw Error(`Unknown WebSocket connection type: ${JSON.stringify(connectionType)}`);
   }
 }
 export function handleWebSocketUpgrade(server, context, options, request, url, authContext) {

package/dist/server/runtime/websocket-worker.js

@@ -47,6 +47,15 @@ function onTaskResultMessage(context, options, ws, message, cleanupWorkflowIndex
     });
     return;
   }
+  const inFlightTask = context.registry.getTask(operationId);
+  if (inFlightTask?.workflowRevision !== void 0 && message.workflowRevision !== inFlightTask.workflowRevision) {
+    sendWorkerProtocolMessage(ws, {
+      type: "protocolError",
+      code: "invalid_message",
+      message: `taskResult for operation "${operationId}" rejected \u2014 revision mismatch`
+    });
+    return;
+  }
   const resolvedStatus = resolveTaskResultStatus(message), payloadError = taskResultPayloadSizeError({
     status: resolvedStatus,
     ...message.status === "completed" ? { value: message.value } : { error: message.error }

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

@@ -15,6 +15,15 @@
  * @module server/task-ledger-codec
  */
 import type { RemoteTaskCancelling, RemoteTaskCompleting, RemoteTaskDeadLettered, RemoteTaskLeased, RemoteTaskQueued, RemoteTaskRecord, RemoteTaskTerminal, RemoteTaskTerminalCancelled, RemoteTaskTerminalResolved, RemoteTaskTerminalRetryExhausted } from './task-ledger-types.ts';
+/**
+ * Whether `value` is a valid `workflowRevision` per the durable task
+ * ledger's non-empty, bounded identifier contract — the same contract
+ * `decodeRemoteTaskRecord` enforces on read. Exported so dispatch-time
+ * callers (`task-dispatch.ts`) can reject an invalid caller-supplied
+ * revision before it reaches a ledger write, instead of writing a record
+ * that later fails to decode.
+ */
+export declare function isValidWorkflowRevision(value: unknown): value is string;
 /** Bounded header map: at most {@link MAX_TASK_HEADER_COUNT} entries, each key/value at most {@link MAX_TASK_HEADER_VALUE_BYTES}. */
 export declare function isValidTaskHeaders(value: unknown): value is Readonly<Record<string, string>>;
 export declare function isRemoteTaskQueued(value: unknown): value is RemoteTaskQueued;

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

@@ -14,6 +14,9 @@ function isRecord(value) {
 function isBoundedIdentifier(value, maxBytes = MAX_TASK_IDENTIFIER_BYTES) {
   return typeof value === "string" && value.length > 0 && utf8ByteLength(value) <= maxBytes;
 }
+export function isValidWorkflowRevision(value) {
+  return isBoundedIdentifier(value);
+}
 function isBoundedOptionalIdentifier(value, maxBytes = MAX_TASK_IDENTIFIER_BYTES) {
   return value === void 0 || isBoundedIdentifier(value, maxBytes);
 }
@@ -86,7 +89,7 @@ function isOptionalExecutionIdentity(value) {
   return value === void 0 || isValidExecutionIdentity(value);
 }
 function isValidTaskIdentityFields(value) {
-  return value.recordVersion === 1 && isBoundedIdentifier(value.operationId) && isBoundedOptionalIdentifier(value.workflowId) && isBoundedIdentifier(value.workflowType) && isBoundedOptionalIdentifier(value.workflowExecutionToken) && isBoundedIdentifier(value.activityName) && isBoundedIdentifier(value.queue);
+  return value.recordVersion === 1 && isBoundedIdentifier(value.operationId) && isBoundedOptionalIdentifier(value.workflowId) && isBoundedIdentifier(value.workflowType) && isBoundedOptionalIdentifier(value.workflowExecutionToken) && isBoundedOptionalIdentifier(value.workflowRevision) && isBoundedIdentifier(value.activityName) && isBoundedIdentifier(value.queue);
 }
 function isValidTaskRoutingFields(value) {
   return isOptionalFiniteNumber(value.priority) && isBoundedOptionalIdentifier(value.fairShareKey) && isBoundedOptionalIdentifier(value.stickyWorkflowId) && isValidExecutionRequirement(value.executionRequirement);

package/dist/server/task-ledger-transition-helpers.js

@@ -5,6 +5,7 @@ export function pickBase(record) {
     ...record.workflowId !== void 0 ? { workflowId: record.workflowId } : {},
     workflowType: record.workflowType,
     ...record.workflowExecutionToken !== void 0 ? { workflowExecutionToken: record.workflowExecutionToken } : {},
+    ...record.workflowRevision !== void 0 ? { workflowRevision: record.workflowRevision } : {},
     activityName: record.activityName,
     queue: record.queue,
     input: record.input,

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

@@ -48,6 +48,15 @@ export type RemoteTaskBase = Readonly<{
     workflowId?: string;
     workflowType: string;
     workflowExecutionToken?: string;
+    /**
+     * The dispatching workflow run's persisted revision (WFT-20), when the
+     * `TaskDispatch` caller supplied one. Same optionality rationale as
+     * `workflowExecutionToken` above — NOT the same field as
+     * `executionRequirement.workflowRevision` (a client-declared routing
+     * constraint carried by `WorkerExecutionRequirementInput`, unrelated to
+     * this plain wire echo/validation field).
+     */
+    workflowRevision?: string;
     activityName: string;
     queue: string;
     input: JSONValue;

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

@@ -10,7 +10,7 @@
  *
  * @module server/task-ledger
  */
-export { decodeRemoteTaskRecord, encodeRemoteTaskRecord, isRemoteTaskCancelling, isRemoteTaskCompleting, isRemoteTaskDeadLettered, isRemoteTaskLeased, isRemoteTaskQueued, isRemoteTaskRecord, isRemoteTaskTerminal, isRemoteTaskTerminalCancelled, isRemoteTaskTerminalResolved, isRemoteTaskTerminalRetryExhausted, isValidTaskHeaders, } from './task-ledger-codec.ts';
+export { decodeRemoteTaskRecord, encodeRemoteTaskRecord, isRemoteTaskCancelling, isRemoteTaskCompleting, isRemoteTaskDeadLettered, isRemoteTaskLeased, isRemoteTaskQueued, isRemoteTaskRecord, isRemoteTaskTerminal, isRemoteTaskTerminalCancelled, isRemoteTaskTerminalResolved, isRemoteTaskTerminalRetryExhausted, isValidTaskHeaders, isValidWorkflowRevision, } from './task-ledger-codec.ts';
 export { taskLedgerKey } from './task-ledger-keys.ts';
 export { MAX_TASK_HEADER_COUNT, MAX_TASK_HEADER_VALUE_BYTES, MAX_TASK_IDENTIFIER_BYTES, MAX_TASK_REASON_BYTES, utf8ByteLength, } from './task-ledger-limits.ts';
 export { REMOTE_TASK_RECORD_VERSION } from './task-ledger-types.ts';