@lostgradient/weft 0.24.0 → 0.24.2

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,14 @@ import {
 } from "../task-ledger-transitions.js";
 import {
   decodeRemoteTaskRecord,
-  REMOTE_TASK_RECORD_VERSION,
   taskLedgerKey
 } from "../task-ledger.js";
+import {
+  assertFreshDispatchOperationIdAdmissible,
+  awaitTaskLedgerRecoveryReady,
+  buildCreateQueuedInput
+} from "./task-dispatch-envelope.js";
+import { assertDispatchTargetsFreshRevision } from "./task-dispatch-revision.js";
 import { commitTaskLedgerTransition } from "./task-ledger-runtime.js";
 import {
   recordTaskBacklogMetric,
@@ -27,7 +31,7 @@ export function scheduleDelayedDispatch(context, options, task, delay) {
     return;
   const timer = setTimeout(() => {
     context.pendingTimers.delete(timer);
-    dispatchTaskImpl(context, options, task).catch((err) => console.error(`[weft] Delayed redispatch failed for "${task.operationId}":`, err));
+    dispatchTaskImpl(context, options, task, { redispatch: !0 }).catch((err) => console.error(`[weft] Delayed redispatch failed for "${task.operationId}":`, err));
   }, delay);
   context.pendingTimers.add(timer);
 }
@@ -65,33 +69,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 +91,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 +105,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 +113,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 +136,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 +147,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 +172,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,
@@ -206,23 +185,20 @@ async function enqueueTaskForLongPoll(context, options, task, queue, visibilityT
   recordTaskBacklogMetric(context.metricsCollector, context.taskQueue);
   return enqueued;
 }
-export async function dispatchTaskImpl(context, options, 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 async function dispatchTaskImpl(context, options, task, { redispatch = !1 } = {}) {
+  await awaitTaskLedgerRecoveryReady(context, task);
+  assertFreshDispatchOperationIdAdmissible(task, redispatch);
   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-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,34 @@
  * @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;
+/**
+ * Whether `value` is a valid caller-facing task `operationId` — a non-empty,
+ * bounded identifier per the ledger's own contract, and not the exact string
+ * `.` or `..` (WFT-95). WHATWG URL path normalization collapses `.`/`..`
+ * path segments (and their percent-encoded forms) before `handleRequest()`
+ * ever sees `url.pathname`, so a REST route with a single trailing
+ * `:operationId` segment (e.g. `weft.tasks.get`'s
+ * `/v1/tasks/detail/:operationId`) can never address a record whose
+ * operationId is literally `.` or `..`. Exported so fresh-dispatch admission
+ * (`task-dispatch.ts`'s `dispatchTaskImpl`) can reject an invalid
+ * caller-supplied `operationId` before it ever reaches a ledger write,
+ * closing that URL-normalization quirk as an enforced admission-time
+ * guarantee instead of an assumption. Deliberately NOT applied when
+ * redispatching an already-decoded, previously persisted ledger record —
+ * see `dispatchTaskImpl`'s `redispatch` option — since such an id was valid
+ * under the pre-WFT-95 decode contract and may already be durably
+ * persisted. Does not reject an id that merely contains a dot character.
+ */
+export declare function isValidOperationId(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,12 @@ 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);
+}
+export function isValidOperationId(value) {
+  return isBoundedIdentifier(value) && value !== "." && value !== "..";
+}
 function isBoundedOptionalIdentifier(value, maxBytes = MAX_TASK_IDENTIFIER_BYTES) {
   return value === void 0 || isBoundedIdentifier(value, maxBytes);
 }
@@ -86,7 +92,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, isValidOperationId, 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';

package/dist/server/task-ledger.js

@@ -11,7 +11,9 @@ export {
   isRemoteTaskTerminalCancelled,
   isRemoteTaskTerminalResolved,
   isRemoteTaskTerminalRetryExhausted,
-  isValidTaskHeaders
+  isValidOperationId,
+  isValidTaskHeaders,
+  isValidWorkflowRevision
 } from "./task-ledger-codec.js";
 export { taskLedgerKey } from "./task-ledger-keys.js";
 export {

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

@@ -15,6 +15,8 @@ export interface PendingTask extends TaskLifecycleFields {
     workflowId?: string | undefined;
     /** Durable token for the workflow run that dispatched this activity, when known. */
     workflowExecutionToken?: string | undefined;
+    /** The dispatching workflow run's persisted revision (WFT-20), when known. */
+    workflowRevision?: string | undefined;
     /**
      * Task priority. Higher values are dequeued first. Tasks with equal priority
      * maintain FIFO order. Default: 0. Agent workflow tasks use priority 10.