@lostgradient/weft 0.24.0 → 0.24.2

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

@@ -60,6 +60,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     adoptedAt?: number | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;
@@ -95,6 +96,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     adoptedAt?: number | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;
@@ -130,6 +132,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     adoptedAt?: number | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;
@@ -168,6 +171,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     lastRequeueReason?: string | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;
@@ -206,6 +210,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     lastRequeueReason?: string | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;
@@ -246,6 +251,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     lastRequeueReason?: string | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;
@@ -286,6 +292,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     lastRequeueReason?: string | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;
@@ -324,6 +331,7 @@ export declare const getTaskDetailOperation: import("../operation-catalog.ts").O
     lastRequeueReason?: string | undefined;
     workflowId?: string | undefined;
     workflowExecutionToken?: string | undefined;
+    workflowRevision?: string | undefined;
     priority?: number | undefined;
     retryPolicy?: {
         maxAttempts: number;

package/dist/server/operations/get-task-detail.js

@@ -38,6 +38,7 @@ function baseEnvelopeFields(record) {
     operationId: record.operationId,
     ...record.workflowId !== void 0 ? { workflowId: record.workflowId } : {},
     ...record.workflowExecutionToken !== void 0 ? { workflowExecutionToken: record.workflowExecutionToken } : {},
+    ...record.workflowRevision !== void 0 ? { workflowRevision: record.workflowRevision } : {},
     workflowType: record.workflowType,
     activityName: record.activityName,
     queue: record.queue,

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/rest-binding.d.ts

@@ -146,6 +146,17 @@ export type RestBinding<Input, Output> = {
  * path param would propagate to the engine as a confusingly-shaped
  * "missing" identifier, and surfacing the shape error at the router
  * (404) produces a cleaner wire response than a downstream 400.
+ *
+ * WHATWG URL path normalization collapses `.` and `..` path segments (and
+ * their percent-encoded forms) before `handleRequest()` ever sees
+ * `url.pathname` — this function never observes those segments as literal
+ * text, so a single trailing `:id`/`:operationId` segment can never match a
+ * resource whose id is literally `.` or `..`, no matter how it is encoded.
+ * This is no longer just a documented gap: `assertValidWorkflowId` (WFT-95)
+ * and `isValidOperationId` reject those exact strings at admission, so a
+ * caller-facing workflow or operation id can never legitimately be `.` or
+ * `..` in the first place — this URL-normalization quirk is closed by
+ * validation rather than left as something callers must work around.
  */
 export declare function bindingPathMatches(pattern: string, actualPath: string): Record<string, string> | null;
 /**

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

@@ -0,0 +1,41 @@
+/**
+ * Build the durable task-ledger envelope a fresh dispatch would create if no
+ * ledger record exists yet, and the fresh-dispatch admission checks
+ * `dispatchTaskImpl` runs before that — 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 `buildCreateQueuedInput` from both `selectAndReserveWorker` and
+ * `enqueueTaskForLongPoll`, and calls the admission helpers from
+ * `dispatchTaskImpl` itself.
+ *
+ * @module server/runtime/task-dispatch-envelope
+ */
+import type { TaskDispatch } from '../index.ts';
+import type { CreateQueuedInput } from '../task-ledger-transitions.ts';
+import type { ServerContext } from './context.ts';
+/**
+ * Wait for startup task-ledger recovery (WFT-23) — covers both the public
+ * `WeftServer.dispatchTask` entry point and `scheduleDelayedDispatch`'s timer
+ * callback, which also calls `dispatchTaskImpl` directly. A rejected gate
+ * means the recovery scan itself failed; propagate that failure loudly
+ * rather than silently returning false, which callers would read as an
+ * ordinary "no worker available" outcome.
+ */
+export declare function awaitTaskLedgerRecoveryReady(context: ServerContext, task: TaskDispatch): Promise<void>;
+/**
+ * Reject an invalid caller-supplied operationId before it reaches a ledger
+ * write (WFT-95). `dispatchTask()` is a public same-process API taking a
+ * caller-controlled operationId; an id equal to the exact string "." or
+ * ".." can never be addressed again over REST (a single trailing
+ * `:operationId` path segment is collapsed away by WHATWG URL path
+ * normalization before the route matcher ever sees it), so fresh-dispatch
+ * admission rejects it up front instead of writing a ledger record that
+ * becomes unreachable by id. Skipped for `redispatch` — reconstructing and
+ * redispatching an already-decoded, previously persisted ledger record
+ * (`scheduleDelayedDispatch`/`taskDispatchFromLedgerRecord`) must not
+ * re-apply an admission-only check to data that was valid when written.
+ */
+export declare function assertFreshDispatchOperationIdAdmissible(task: TaskDispatch, redispatch: boolean): void;
+/** 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,54 @@
+import { isJSONValue } from "../../core/json.js";
+import {
+  isValidOperationId,
+  isValidWorkflowRevision,
+  REMOTE_TASK_RECORD_VERSION
+} from "../task-ledger.js";
+export async function awaitTaskLedgerRecoveryReady(context, task) {
+  try {
+    await context.taskLedgerRecovery.ready;
+  } catch (error) {
+    throw Error(`Cannot dispatch task "${task.operationId}" \u2014 startup task-ledger recovery failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+export function assertFreshDispatchOperationIdAdmissible(task, redispatch) {
+  if (redispatch || isValidOperationId(task.operationId))
+    return;
+  let formattedOperationId;
+  try {
+    formattedOperationId = JSON.stringify(task.operationId) ?? String(task.operationId);
+  } catch {
+    formattedOperationId = `<${typeof task.operationId}>`;
+  }
+  throw Error(`TaskDispatch has an invalid "operationId" (${formattedOperationId}) \u2014 it must be a non-empty, bounded identifier other than "." or "..".`);
+}
+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.d.ts

@@ -9,6 +9,8 @@ import type { ServerContext } from './context.ts';
  */
 export declare function scheduleDelayedDispatch(context: ServerContext, options: ServeOptions, task: TaskDispatch, delay: number): void;
 export declare function resolveTaskPriority(_context: ServerContext, _options: ServeOptions, task: TaskDispatch): number | undefined;
-export declare function dispatchTaskImpl(context: ServerContext, options: ServeOptions, task: TaskDispatch): Promise<boolean>;
+export declare function dispatchTaskImpl(context: ServerContext, options: ServeOptions, task: TaskDispatch, { redispatch }?: {
+    redispatch?: boolean;
+}): Promise<boolean>;
 /** Send a cancel message to the worker handling a specific operation. */
 export declare function cancelTask(context: ServerContext, operationId: string): boolean;