@lostgradient/weft 0.2.1 → 0.4.0

package/dist/core/engine/callback-creators-core.js

@@ -18,7 +18,7 @@ import {
 import { resolveWorkflowTypeTarget } from "./registration.js";
 import { cleanupReviews } from "./reviews.js";
 import {
-  commitWorkflowStateOperations,
+  commitFencedWorkflowStateOperations,
   loadWorkflowState,
   runSerializedWorkflowStateWrite
 } from "./storage-io.js";
@@ -75,7 +75,8 @@ export function createLifecycleCallbacks(engine) {
     handleCleanupError: (source, error, workflowId) => createTerminationCallbacks(engine).handleCleanupError(source, error, workflowId),
     swallowPromiseRejection: (promise) => swallowPromiseRejection(promise),
     enforceHistoryCircuitBreaker: (workflowId) => terminateWorkflow(getInternals(engine), workflowId, "timed-out", createTerminationCallbacks(engine), HISTORY_CIRCUIT_BREAKER_REASON),
-    failWorkflowForUnavailableServices: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
+    failWorkflowForUnavailableServices: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
+    failWorkflowForCheckpointDecodeError: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
   };
 }
 export function createTerminationCallbacksWith(engine, handleScheduledWorkflowTerminal) {
@@ -91,7 +92,7 @@ export function createTerminationCallbacksWith(engine, handleScheduledWorkflowTe
     handleScheduledWorkflowTerminal,
     loadWorkflowState: (workflowId) => loadWorkflowState(getInternals(engine), workflowId),
     runSerializedWorkflowStateWrite: (workflowId, writeOperation) => runSerializedWorkflowStateWrite(getInternals(engine), workflowId, writeOperation),
-    commitWorkflowStateOperations: (state, operations) => commitWorkflowStateOperations(getInternals(engine), state, operations),
+    commitWorkflowStateOperations: (state, operations, options) => commitFencedWorkflowStateOperations(getInternals(engine), state, operations, options),
     cleanupReviews: (workflowId) => cleanupReviews(getInternals(engine), workflowId)
   };
 }
@@ -106,7 +107,8 @@ export function createTerminationCallbacks(engine) {
 }
 export function createRegistrationCallbacks(engine) {
   return {
-    ensureRetentionSweepInterval: () => ensureRetentionSweepIntervalCallable(engine)
+    ensureRetentionSweepInterval: () => ensureRetentionSweepIntervalCallable(engine),
+    dispatchEvent: (event) => engine.dispatchEvent(event)
   };
 }
 let retentionSweepIntervalCallable = () => {

package/dist/core/engine/callback-creators-router.js

@@ -1,6 +1,7 @@
 import {
   createActivityOperationCallbacks,
   createChildWorkflowOperationCallbacks,
+  createConditionOperationCallbacks,
   createCoordinationOperationCallbacks,
   createDataOperationCallbacks,
   createStateOperationCallbacks,
@@ -28,10 +29,12 @@ import {
   processMemoOperation,
   processOffloadOperation
 } from "./operations-data.js";
+import { completeOperation } from "./operations-router.js";
 import { processSpeculateOperation } from "./operations-speculate.js";
 import { processStateCommitOperation, processStateReadOperation } from "./operations-state.js";
 import { processStreamOperation } from "./operations-stream.js";
 import { processSleepOperation } from "./operations-time.js";
+import { processWaitConditionOperation } from "./operations-wait-condition.js";
 import { feedOperationResult } from "./strategy-helpers.js";
 import { processWaitReviewOperation } from "./sub-operation.js";
 import { finalizePendingTimelineEntry } from "./termination.js";
@@ -42,6 +45,13 @@ export function createOperationRouterCallbacks(engine) {
     processSleepOperation: (workflowId, operation) => processSleepOperation(getInternals(engine), workflowId, operation, createTimeOperationCallbacks(engine)),
     processWaitSignalOperation: (workflowId, operation) => processWaitSignalOperation(getInternals(engine), workflowId, operation, createCoordinationOperationCallbacks(engine)),
     processWaitUpdateOperation: (workflowId, operation) => processWaitUpdateOperation(getInternals(engine), workflowId, operation, createUpdateCallbacks(engine)),
+    processWaitConditionOperation: (workflowId, operation) => processWaitConditionOperation(getInternals(engine), workflowId, operation, createConditionOperationCallbacks(engine)),
+    processGetVersionOperation: async (workflowId, operation) => {
+      completeOperation(getInternals(engine), workflowId, operation.version, {
+        finalizePendingTimelineEntry: (id, status, value) => finalizePendingTimelineEntry(getInternals(engine), id, status, value),
+        feedOperationResult: (id, result, error) => feedOperationResult(getInternals(engine), id, result, error)
+      });
+    },
     processParallelOperation: (workflowId, operation) => processParallelOperation(getInternals(engine), workflowId, operation, createCoordinationOperationCallbacks(engine)),
     processRaceOperation: (workflowId, operation) => processRaceOperation(getInternals(engine), workflowId, operation, createCoordinationOperationCallbacks(engine)),
     processMemoOperation: (workflowId, operation) => processMemoOperation(getInternals(engine), workflowId, operation, createDataOperationCallbacks(engine)),

package/dist/core/engine/callback-creators-schedule.d.ts

@@ -6,8 +6,8 @@ export declare function createScheduleCallbacks<TWorkflows extends object, TActi
 export declare function createReviewOperationCallbacks<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): ReviewOperationCallbacks;
 export declare function createSubmitReviewCallbacks<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): SubmitReviewCallbacks;
 export declare function refreshScheduledWorkflowStateForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState): Promise<RefreshedScheduleState>;
-export declare function startScheduledRunForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState): Promise<string>;
-export declare function applyScheduleOccurrenceForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState): Promise<ScheduleState>;
+export declare function startScheduledRunForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState, occurrence?: number): Promise<string>;
+export declare function applyScheduleOccurrenceForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState, occurrence?: number): Promise<ScheduleState>;
 export declare function settleBackfillScheduleStateForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, state: ScheduleState): Promise<ScheduleState>;
 export declare function handleScheduleTimerForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, entry: TimerEntry): Promise<void>;
 export declare function handleScheduledWorkflowTerminalForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, workflowId: string): Promise<void>;

package/dist/core/engine/callback-creators-schedule.js

@@ -17,7 +17,7 @@ import {
 } from "./schedules.js";
 import { loadWorkflowState } from "./storage-io.js";
 import { feedOperationResult } from "./strategy-helpers.js";
-import { ensureTerminalCleanupTracked, failWorkflow } from "./termination.js";
+import { ensureTerminalCleanupTracked, failWorkflow, handleCleanupError } from "./termination.js";
 export function createScheduleCallbacks(engine) {
   return {
     startWorkflow: async (type, input, options, additionalStartOperations) => {
@@ -27,10 +27,14 @@ export function createScheduleCallbacks(engine) {
     cancelWorkflow: (workflowId) => engine.cancel(workflowId),
     getWorkflowResult: (workflowId) => engine.getHandle(workflowId).result(),
     refreshScheduledWorkflowState: (state) => refreshScheduledWorkflowStateForEngine(engine, state),
-    startScheduledRun: (state) => startScheduledRunForEngine(engine, state),
-    applyScheduleOccurrence: (state) => applyScheduleOccurrenceForEngine(engine, state),
+    startScheduledRun: (state, occurrence) => startScheduledRunForEngine(engine, state, occurrence),
+    applyScheduleOccurrence: (state, occurrence) => applyScheduleOccurrenceForEngine(engine, state, occurrence),
     settleBackfillScheduleState: (state) => settleBackfillScheduleStateForEngine(engine, state),
-    flushQueuedInlineWorkflowStartsDirectly: () => flushQueuedInlineWorkflowStartsDirectly(getInternals(engine), createInlineLaunchQueueCallbacks(engine))
+    flushQueuedInlineWorkflowStartsDirectly: () => flushQueuedInlineWorkflowStartsDirectly(getInternals(engine), createInlineLaunchQueueCallbacks(engine)),
+    failWorkflow: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine)),
+    handleCleanupError: (source, error, workflowId) => handleCleanupError(getInternals(engine), source, error, workflowId, {
+      dispatchEvent: (event) => engine.dispatchEvent(event)
+    })
   };
 }
 export function createReviewOperationCallbacks(engine) {
@@ -47,11 +51,11 @@ export function createSubmitReviewCallbacks(engine) {
 export async function refreshScheduledWorkflowStateForEngine(engine, state) {
   return refreshScheduledWorkflowState(getInternals(engine), state, createScheduleCallbacks(engine));
 }
-export async function startScheduledRunForEngine(engine, state) {
-  return startScheduledRun(getInternals(engine), state, createScheduleCallbacks(engine));
+export async function startScheduledRunForEngine(engine, state, occurrence) {
+  return startScheduledRun(getInternals(engine), state, createScheduleCallbacks(engine), occurrence);
 }
-export async function applyScheduleOccurrenceForEngine(engine, state) {
-  return applyScheduleOccurrence(getInternals(engine), state, createScheduleCallbacks(engine));
+export async function applyScheduleOccurrenceForEngine(engine, state, occurrence) {
+  return applyScheduleOccurrence(getInternals(engine), state, createScheduleCallbacks(engine), occurrence);
 }
 export async function settleBackfillScheduleStateForEngine(engine, state) {
   return settleBackfillScheduleState(getInternals(engine), state, createScheduleCallbacks(engine));

package/dist/core/engine/candidate-read-batching.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared bounded-concurrency size for materializing candidate workflow states.
+ * Keep this internal to engine query paths; it limits storage fan-out without
+ * changing result ordering.
+ */
+export declare const CONSTRAINED_ID_CHUNK_SIZE = 64;

package/dist/core/engine/candidate-read-batching.js

@@ -0,0 +1 @@
+export const CONSTRAINED_ID_CHUNK_SIZE = 64;

package/dist/core/engine/checkpoint-io.js

@@ -1,4 +1,4 @@
-import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import { KEYS } from "../../storage/interface.js";
 import {
   advanceCheckpoint,
   deserializeCheckpoint,
@@ -6,6 +6,7 @@ import {
   validateCheckpointRoundTrip
 } from "../checkpoint.js";
 import { encode } from "../codec.js";
+import { hasPendingAttributeChanges } from "../context/context-presence.js";
 import { EMPTY_EVENT_HEAD, EventLog } from "../event-log.js";
 import {
   AttributesChangedEvent,
@@ -17,10 +18,22 @@ import {
   getCommittedCheckpointBytes,
   rememberCommittedCheckpointBytes
 } from "./checkpoint-commit-snapshots.js";
+import {
+  attachTransientCheckpointReplayPayload,
+  createCheckpointEventPayload,
+  mergeCheckpointReplayPayloads,
+  pruneCheckpointReplayState,
+  readCheckpointReplayPayload
+} from "./checkpoint-replay.js";
+import {
+  clearPendingAtomicWorkflowCommitSideEffects,
+  takePendingAtomicWorkflowCommitSideEffects
+} from "./checkpoint-side-effects.js";
 import {
   appendCompactionOperations,
   serializeDeletedEntries
 } from "./event-log-compaction.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 import { getTimelineInputSummary, getTimelineOperationLabel } from "./state-utilities.js";
 import { buildPendingTimelineOperation } from "./termination.js";
 import { notifyWorkflowFeedCommit } from "./workflow-feed.js";
@@ -57,21 +70,21 @@ async function persistInlineCheckpoint(internals, workflowId, operation, callbac
   const current = internals.checkpoints.get(workflowId), context = internals.inlineStrategy?.getContext(workflowId);
   if (!current || !context)
     return;
-  const previousAttributes = { ...current.searchAttributes }, pendingAttributeChanges = context.checkpointPendingAttributeChanges, hasPendingAttributeChanges = context.hasPendingAttributeChanges, advanced = advanceCheckpoint(current, context.checkpointLocals, {
+  const previousAttributes = { ...current.searchAttributes }, pendingAttributeChanges = context.checkpointPendingAttributeChanges, hasPendingAttributeChangesValue = hasPendingAttributeChanges(context), advanced = advanceCheckpoint(current, context.checkpointLocals, {
     accumulatedResults: context.checkpointAccumulatedResults,
     now: internals.options.getNow(),
     ...pendingAttributeChanges !== void 0 ? { searchAttributes: pendingAttributeChanges } : {}
-  }), commit = createCheckpointCommit(internals, workflowId, advanced, serializeCheckpoint(advanced));
-  appendAttributeOperations(workflowId, commit, previousAttributes, pendingAttributeChanges, hasPendingAttributeChanges, callbacks);
+  }), pruned = pruneCheckpointReplayState(advanced, resolvePendingOperationStep(operation, context.stepIndex)), commit = createCheckpointCommit(internals, workflowId, pruned.checkpoint, serializeCheckpoint(attachTransientCheckpointReplayPayload(pruned.checkpoint, pruned.replayPayload)), pruned.replayPayload);
+  appendAttributeOperations(workflowId, commit, previousAttributes, pendingAttributeChanges, hasPendingAttributeChangesValue, callbacks);
   await commitCheckpoint(internals, workflowId, operation, commit, callbacks);
-  if (hasPendingAttributeChanges)
+  if (hasPendingAttributeChangesValue)
     callbacks.dispatchEvent(new AttributesChangedEvent(workflowId, { ...pendingAttributeChanges }));
 }
 async function persistWorkerCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks) {
-  const serialized = new Uint8Array(workerCheckpointBytes), checkpoint = deserializeCheckpoint(serialized);
-  await commitCheckpoint(internals, workflowId, operation, createCheckpointCommit(internals, workflowId, checkpoint, serialized), callbacks);
+  const serialized = new Uint8Array(workerCheckpointBytes), checkpoint = deserializeCheckpoint(serialized), workerReplayPayload = readCheckpointReplayPayload(checkpoint), pruned = pruneCheckpointReplayState(checkpoint, resolvePendingOperationStep(operation, checkpoint.step)), replayPayload = mergeCheckpointReplayPayloads(workerReplayPayload, pruned.replayPayload), prunedSerialized = serializeCheckpoint(attachTransientCheckpointReplayPayload(pruned.checkpoint, replayPayload));
+  await commitCheckpoint(internals, workflowId, operation, createCheckpointCommit(internals, workflowId, pruned.checkpoint, prunedSerialized, replayPayload), callbacks);
 }
-function createCheckpointCommit(internals, workflowId, checkpoint, serialized) {
+function createCheckpointCommit(internals, workflowId, checkpoint, serialized, replayPayload) {
   const operations = [
     { type: "put", key: KEYS.checkpoint(workflowId), value: serialized }
   ];
@@ -85,14 +98,15 @@ function createCheckpointCommit(internals, workflowId, checkpoint, serialized) {
   return {
     checkpoint,
     serialized,
+    ...replayPayload === void 0 ? {} : { replayPayload },
     ...expectedSerialized !== void 0 ? { expectedSerialized } : {},
     step: checkpoint.step,
     timestamp: checkpoint.createdAt,
     operations
   };
 }
-function appendAttributeOperations(workflowId, commit, previousAttributes, pendingAttributeChanges, hasPendingAttributeChanges, callbacks) {
-  if (!hasPendingAttributeChanges)
+function appendAttributeOperations(workflowId, commit, previousAttributes, pendingAttributeChanges, hasPendingAttributeChangesValue, callbacks) {
+  if (!hasPendingAttributeChangesValue)
     return;
   callbacks.validateAttributeValueSizes(pendingAttributeChanges ?? {});
   commit.operations.push({
@@ -104,11 +118,15 @@ function appendAttributeOperations(workflowId, commit, previousAttributes, pendi
 }
 async function commitCheckpoint(internals, workflowId, operation, commit, callbacks) {
   dispatchCheckpointSizeWarning(internals, workflowId, commit, callbacks);
-  const nextPendingTimelineEntry = callbacks.appendTimelineBatchOperations(workflowId, operation, commit.step, commit.timestamp, commit.operations), { newHead, timestamp } = appendCheckpointEventLog(internals, workflowId, commit), retentionWindow = internals.options.historyPolicy.retentionWindow, compaction = retentionWindow === null ? null : await appendCompactionOperations(internals.storage, workflowId, newHead.sequence, retentionWindow, commit.operations);
-  if (commit.expectedSerialized === void 0 || !internals.storage.capabilities().conditionalBatch)
-    await internals.storage.batch(commit.operations);
-  else
-    await writeCheckpointCommitBatch(internals, workflowId, commit, commit.expectedSerialized);
+  const nextPendingTimelineEntry = callbacks.appendTimelineBatchOperations(workflowId, operation, commit.step, commit.timestamp, commit.operations), { newHead, timestamp } = appendCheckpointEventLog(internals, workflowId, commit), retentionWindow = internals.options.historyPolicy.retentionWindow, compaction = retentionWindow === null ? null : await appendCompactionOperations(internals.storage, workflowId, newHead.sequence, retentionWindow, commit.operations), pendingSideEffects = takePendingAtomicWorkflowCommitSideEffects(internals, workflowId);
+  if (pendingSideEffects !== void 0)
+    commit.operations.push(...pendingSideEffects.operations);
+  const storageSupportsConditionalBatch = internals.storage.capabilities().conditionalBatch, sideEffectConditions = checkpointSideEffectConditions(pendingSideEffects, storageSupportsConditionalBatch), conditions = buildCheckpointCommitConditions(workflowId, commit, storageSupportsConditionalBatch, sideEffectConditions);
+  await commitFencedEngineWrite(internals, commit.operations, conditions, () => {
+    return Error(`Checkpoint commit for workflow "${workflowId}" lost its CAS race against a newer checkpoint.`);
+  });
+  if (pendingSideEffects !== void 0)
+    clearPendingAtomicWorkflowCommitSideEffects(internals, workflowId);
   if (commit.expectedSerialized !== void 0)
     rememberCommittedCheckpointBytes(internals, workflowId, commit.serialized);
   internals.pendingTimelineEntries.set(workflowId, nextPendingTimelineEntry);
@@ -128,15 +146,20 @@ async function commitCheckpoint(internals, workflowId, operation, commit, callba
   if (historyEventLimitBreached(internals, newHead.sequence))
     await callbacks.enforceHistoryCircuitBreaker(workflowId);
 }
-async function writeCheckpointCommitBatch(internals, workflowId, commit, expectedSerialized) {
-  const conditions = [
-    {
+function checkpointSideEffectConditions(pendingSideEffects, storageSupportsConditionalBatch) {
+  if (!storageSupportsConditionalBatch)
+    return [];
+  return pendingSideEffects?.conditions ?? [];
+}
+function buildCheckpointCommitConditions(workflowId, commit, includeCheckpointCondition, sideEffectConditions) {
+  const conditions = [];
+  if (includeCheckpointCondition && commit.expectedSerialized !== void 0)
+    conditions.push({
       key: KEYS.checkpoint(workflowId),
-      expectedValue: expectedSerialized
-    }
-  ];
-  if (!await storageConditionalBatch(internals.storage, conditions, commit.operations))
-    throw Error(`Checkpoint commit for workflow "${workflowId}" lost its CAS race against a newer checkpoint.`);
+      expectedValue: commit.expectedSerialized
+    });
+  conditions.push(...sideEffectConditions);
+  return conditions;
 }
 function historyEventLimitBreached(internals, sequence) {
   const maxEvents = internals.options.historyPolicy.maxEvents;
@@ -154,7 +177,16 @@ function dispatchCheckpointSizeWarning(internals, workflowId, commit, callbacks)
     callbacks.dispatchEvent(new CheckpointSizeWarningEvent(workflowId, commit.serialized.byteLength, commit.step));
 }
 function appendCheckpointEventLog(internals, workflowId, commit) {
-  return new EventLog(internals.storage, workflowId).appendToBatch({ type: "workflow:checkpoint", payload: { step: commit.step } }, commit.operations, internals.eventLogHeads.get(workflowId) ?? EMPTY_EVENT_HEAD, internals.workflowVersionTuples.get(workflowId));
+  return new EventLog(internals.storage, workflowId).appendToBatch({
+    type: "workflow:checkpoint",
+    payload: createCheckpointEventPayload(commit.step, commit.replayPayload)
+  }, commit.operations, internals.eventLogHeads.get(workflowId) ?? EMPTY_EVENT_HEAD, internals.workflowVersionTuples.get(workflowId));
+}
+function resolvePendingOperationStep(operation, fallbackStepIndex) {
+  const operationStep = "step" in operation ? operation.step : void 0;
+  if (typeof operationStep === "number" && Number.isSafeInteger(operationStep) && operationStep >= 0)
+    return operationStep;
+  return Math.max(0, fallbackStepIndex - 1);
 }
 export async function pruneCheckpointHistory(internals, workflowId, currentStep) {
   const limit = internals.options.checkpointHistory;
@@ -175,7 +207,11 @@ export function validateDevelopmentCheckpoint(internals, workflowId, callbacks)
   const step = context.stepIndex, current = internals.checkpoints.get(workflowId);
   if (!current)
     return;
-  const result = validateCheckpointRoundTrip(current);
+  const result = validateCheckpointRoundTrip({
+    ...current,
+    locals: context.checkpointLocals,
+    accumulatedResults: context.checkpointAccumulatedResults
+  });
   if (!result.valid) {
     const fieldPaths = result.divergences.map((divergence) => divergence.path), message = `Checkpoint at step ${step} has ${result.divergences.length} non-serializable field(s)`;
     callbacks.dispatchEvent(new DevelopmentWarningEvent(workflowId, message, fieldPaths));

package/dist/core/engine/checkpoint-reads.js

@@ -3,6 +3,7 @@ import { deserializeCheckpoint } from "../checkpoint.js";
 import { decode } from "../codec.js";
 import { sanitizeDebugValueForDisplay } from "../debug-output.js";
 import { EventLog } from "../event-log.js";
+import { hydrateCheckpointReplayState } from "./checkpoint-replay.js";
 import { readEventLogWatermark } from "./event-log-compaction.js";
 import {
   sanitizeCheckpointState,
@@ -41,7 +42,7 @@ export async function getCheckpointAt(internals, workflowId, step) {
   const bytes = await internals.storage.get(KEYS.checkpointHistory(workflowId, step));
   if (!bytes)
     return null;
-  const checkpoint = deserializeCheckpoint(bytes);
+  const checkpoint = await hydrateCheckpointReplayState(internals.storage, workflowId, deserializeCheckpoint(bytes));
   return sanitizeCheckpointState({
     step: checkpoint.step,
     locals: checkpoint.locals,
@@ -75,7 +76,7 @@ export async function replayTo(internals, workflowId, step) {
   const bytes = await internals.storage.get(KEYS.checkpointHistory(workflowId, step));
   if (!bytes)
     return null;
-  const checkpoint = deserializeCheckpoint(bytes), entries = await new EventLog(internals.storage, workflowId).replay(Math.max(step - 1, -1)), watermark = await readEventLogWatermark(internals.storage, workflowId);
+  const entries = await new EventLog(internals.storage, workflowId).replay(Math.max(step - 1, -1)), checkpoint = await hydrateCheckpointReplayState(internals.storage, workflowId, deserializeCheckpoint(bytes)), watermark = await readEventLogWatermark(internals.storage, workflowId);
   return {
     checkpoint: sanitizeCheckpointState({
       step: checkpoint.step,

package/dist/core/engine/checkpoint-replay.d.ts

@@ -0,0 +1,20 @@
+import { type Storage } from '../../storage/interface.ts';
+import type { Checkpoint, WorkerReplayOperationFailure, WorkerReplayOperationSignature } from '../types.ts';
+export declare const CHECKPOINT_REPLAY_PAYLOAD_KEY = "__weftCheckpointReplay";
+export type CheckpointReplayPayload = {
+    accumulatedResults?: Array<[number, unknown]>;
+    workerReplaySignatures?: Array<[number, WorkerReplayOperationSignature]>;
+    workerReplayFailures?: Array<[number, WorkerReplayOperationFailure]>;
+};
+export type PrunedCheckpointReplayState = {
+    checkpoint: Checkpoint;
+    replayPayload: CheckpointReplayPayload | undefined;
+};
+export declare function pruneCheckpointReplayState(checkpoint: Checkpoint, pendingOperationStep: number): PrunedCheckpointReplayState;
+export declare function hydrateCheckpointReplayState(storage: Storage, workflowId: string, checkpoint: Checkpoint): Promise<Checkpoint>;
+export declare function hydrateCheckpointReplayStateFromPayload(checkpoint: Checkpoint, replayPayload: CheckpointReplayPayload | undefined): Checkpoint;
+export declare function attachTransientCheckpointReplayPayload(checkpoint: Checkpoint, replayPayload: CheckpointReplayPayload | undefined): Checkpoint;
+export declare function createCheckpointEventPayload(checkpointStep: number, replayPayload: CheckpointReplayPayload | undefined): Record<string, unknown>;
+export declare function mergeCheckpointReplayPayloads(left: CheckpointReplayPayload | undefined, right: CheckpointReplayPayload | undefined): CheckpointReplayPayload | undefined;
+export declare function readCheckpointReplayPayload(payload: unknown): CheckpointReplayPayload | undefined;
+export declare function stripInternalCheckpointReplayPayload(payload: Record<string, unknown>): Record<string, unknown>;

package/dist/core/engine/checkpoint-replay.js

@@ -0,0 +1,242 @@
+import { KEYS } from "../../storage/interface.js";
+import { decode } from "../codec.js";
+import { isWorkflowLogEntry } from "../event-log-shared.js";
+import { WORKER_REPLAY_SIGNATURE_FORMAT } from "../types/checkpoint.js";
+export const CHECKPOINT_REPLAY_PAYLOAD_KEY = "__weftCheckpointReplay";
+const NO_REPLAY_WATERMARK = -1;
+export function pruneCheckpointReplayState(checkpoint, pendingOperationStep) {
+  const checkpointWithoutReplayPayload = stripTransientCheckpointReplayPayload(checkpoint), previousWatermark = checkpointWithoutReplayPayload.accumulatedResultReplayWatermark ?? NO_REPLAY_WATERMARK, consumedResults = entriesBeforeStep(checkpointWithoutReplayPayload.accumulatedResults, pendingOperationStep), consumedSignatures = entriesBeforeStep(checkpointWithoutReplayPayload.workerReplaySignatures ?? [], pendingOperationStep), consumedFailures = entriesBeforeStep(checkpointWithoutReplayPayload.workerReplayFailures ?? [], pendingOperationStep), replayPayload = buildReplayPayload({
+    accumulatedResults: entriesAfterWatermark(consumedResults, previousWatermark),
+    workerReplaySignatures: entriesAfterWatermark(consumedSignatures, previousWatermark),
+    workerReplayFailures: entriesAfterWatermark(consumedFailures, previousWatermark)
+  }), nextWatermark = resolveNextReplayWatermark(previousWatermark, replayPayload), retainedWorkerReplaySignatures = entriesAtOrAfterStep(checkpointWithoutReplayPayload.workerReplaySignatures ?? [], pendingOperationStep), retainedWorkerReplayFailures = entriesAtOrAfterStep(checkpointWithoutReplayPayload.workerReplayFailures ?? [], pendingOperationStep), prunedCheckpoint = {
+    ...checkpointWithoutReplayPayload,
+    accumulatedResults: entriesAtOrAfterStep(checkpointWithoutReplayPayload.accumulatedResults, pendingOperationStep),
+    ...nextWatermark === NO_REPLAY_WATERMARK ? {} : { accumulatedResultReplayWatermark: nextWatermark },
+    ...optionalEntries("workerReplaySignatures", retainedWorkerReplaySignatures),
+    ...optionalEntries("workerReplayFailures", retainedWorkerReplayFailures)
+  };
+  if (nextWatermark === NO_REPLAY_WATERMARK)
+    delete prunedCheckpoint.accumulatedResultReplayWatermark;
+  if (retainedWorkerReplaySignatures.length === 0)
+    delete prunedCheckpoint.workerReplaySignatures;
+  if (retainedWorkerReplayFailures.length === 0)
+    delete prunedCheckpoint.workerReplayFailures;
+  return {
+    checkpoint: prunedCheckpoint,
+    replayPayload
+  };
+}
+export async function hydrateCheckpointReplayState(storage, workflowId, checkpoint) {
+  const replayPayloads = [], checkpointReplayPayload = readCheckpointReplayPayload(checkpoint);
+  if (checkpointReplayPayload !== void 0)
+    replayPayloads.push(checkpointReplayPayload);
+  const compactedReplayPayload = await readCompactedCheckpointReplayPayload(storage, workflowId);
+  if (compactedReplayPayload !== void 0)
+    replayPayloads.push(compactedReplayPayload);
+  for await (const [, entryBytes] of storage.scan(KEYS.eventPrefix(workflowId))) {
+    const decoded = decode(entryBytes);
+    if (!isWorkflowLogEntry(decoded))
+      continue;
+    const entry = decoded, checkpointStep = getCheckpointEventStep(entry.payload);
+    if (checkpointStep === void 0)
+      continue;
+    if (checkpointStep > checkpoint.step)
+      break;
+    const replayPayload = readCheckpointReplayPayload(entry.payload);
+    if (replayPayload === void 0)
+      continue;
+    replayPayloads.push(replayPayload);
+  }
+  return hydrateCheckpointReplayStateFromPayloads(stripTransientCheckpointReplayPayload(checkpoint), replayPayloads);
+}
+export function hydrateCheckpointReplayStateFromPayload(checkpoint, replayPayload) {
+  return hydrateCheckpointReplayStateFromPayloads(stripTransientCheckpointReplayPayload(checkpoint), replayPayload === void 0 ? [] : [replayPayload]);
+}
+function hydrateCheckpointReplayStateFromPayloads(checkpoint, replayPayloads) {
+  const accumulatedResults = new Map, workerReplaySignatures = new Map, workerReplayFailures = new Map;
+  for (const replayPayload of replayPayloads)
+    mergeReplayPayload({
+      accumulatedResults,
+      workerReplaySignatures,
+      workerReplayFailures
+    }, replayPayload);
+  mergeEntries(accumulatedResults, checkpoint.accumulatedResults);
+  mergeEntries(workerReplaySignatures, checkpoint.workerReplaySignatures ?? []);
+  mergeEntries(workerReplayFailures, checkpoint.workerReplayFailures ?? []);
+  return {
+    ...checkpoint,
+    accumulatedResults: sortedEntries(accumulatedResults),
+    ...optionalEntries("workerReplaySignatures", sortedEntries(workerReplaySignatures)),
+    ...optionalEntries("workerReplayFailures", sortedEntries(workerReplayFailures))
+  };
+}
+export function attachTransientCheckpointReplayPayload(checkpoint, replayPayload) {
+  if (replayPayload === void 0)
+    return checkpoint;
+  return {
+    ...checkpoint,
+    [CHECKPOINT_REPLAY_PAYLOAD_KEY]: replayPayload
+  };
+}
+export function createCheckpointEventPayload(checkpointStep, replayPayload) {
+  return replayPayload === void 0 ? { step: checkpointStep } : { step: checkpointStep, [CHECKPOINT_REPLAY_PAYLOAD_KEY]: replayPayload };
+}
+export function mergeCheckpointReplayPayloads(left, right) {
+  if (left === void 0)
+    return right;
+  if (right === void 0)
+    return left;
+  return buildReplayPayload({
+    accumulatedResults: [...left.accumulatedResults ?? [], ...right.accumulatedResults ?? []],
+    workerReplaySignatures: [
+      ...left.workerReplaySignatures ?? [],
+      ...right.workerReplaySignatures ?? []
+    ],
+    workerReplayFailures: [
+      ...left.workerReplayFailures ?? [],
+      ...right.workerReplayFailures ?? []
+    ]
+  });
+}
+export function readCheckpointReplayPayload(payload) {
+  if (!isRecord(payload))
+    return;
+  const replayPayload = payload[CHECKPOINT_REPLAY_PAYLOAD_KEY];
+  if (!isRecord(replayPayload))
+    return;
+  return readCheckpointReplayPayloadRecord(replayPayload);
+}
+export function stripInternalCheckpointReplayPayload(payload) {
+  const { [CHECKPOINT_REPLAY_PAYLOAD_KEY]: _internalReplayPayload, ...publicPayload } = payload;
+  return publicPayload;
+}
+function buildReplayPayload(payload) {
+  const replayPayload = {}, accumulatedResults = payload.accumulatedResults, workerReplaySignatures = payload.workerReplaySignatures, workerReplayFailures = payload.workerReplayFailures;
+  if (accumulatedResults !== void 0 && accumulatedResults.length > 0)
+    replayPayload.accumulatedResults = accumulatedResults;
+  if (workerReplaySignatures !== void 0 && workerReplaySignatures.length > 0)
+    replayPayload.workerReplaySignatures = workerReplaySignatures;
+  if (workerReplayFailures !== void 0 && workerReplayFailures.length > 0)
+    replayPayload.workerReplayFailures = workerReplayFailures;
+  return Object.keys(replayPayload).length === 0 ? void 0 : replayPayload;
+}
+function resolveNextReplayWatermark(previousWatermark, replayPayload) {
+  if (replayPayload === void 0)
+    return previousWatermark;
+  let nextWatermark = previousWatermark;
+  for (const entries of [
+    replayPayload.accumulatedResults ?? [],
+    replayPayload.workerReplaySignatures ?? [],
+    replayPayload.workerReplayFailures ?? []
+  ])
+    for (const [step] of entries)
+      nextWatermark = Math.max(nextWatermark, step);
+  return nextWatermark;
+}
+function entriesBeforeStep(entries, step) {
+  return entries.filter(([entryStep]) => entryStep < step);
+}
+function entriesAtOrAfterStep(entries, step) {
+  return entries.filter(([entryStep]) => entryStep >= step);
+}
+function entriesAfterWatermark(entries, watermark) {
+  return entries.filter(([entryStep]) => entryStep > watermark);
+}
+function optionalEntries(key, entries) {
+  return entries.length === 0 ? {} : { [key]: entries };
+}
+function stripTransientCheckpointReplayPayload(checkpoint) {
+  const checkpointWithReplayPayload = checkpoint, { [CHECKPOINT_REPLAY_PAYLOAD_KEY]: _replayPayload, ...checkpointWithoutReplayPayload } = checkpointWithReplayPayload;
+  return checkpointWithoutReplayPayload;
+}
+function sortedEntries(entries) {
+  return [...entries.entries()].toSorted(([leftStep], [rightStep]) => leftStep - rightStep);
+}
+function mergeEntries(target, entries) {
+  for (const [step, value] of entries)
+    target.set(step, value);
+}
+function mergeReplayPayload(target, replayPayload) {
+  mergeEntries(target.accumulatedResults, replayPayload.accumulatedResults ?? []);
+  mergeEntries(target.workerReplaySignatures, replayPayload.workerReplaySignatures ?? []);
+  mergeEntries(target.workerReplayFailures, replayPayload.workerReplayFailures ?? []);
+}
+function getCheckpointEventStep(payload) {
+  if (!isRecord(payload))
+    return;
+  const step = payload.step;
+  return typeof step === "number" && Number.isSafeInteger(step) && step >= 0 ? step : void 0;
+}
+function readCheckpointReplayPayloadRecord(replayPayload) {
+  const accumulatedResults = readUnknownEntries(replayPayload.accumulatedResults), workerReplaySignatures = readWorkerReplaySignatureEntries(replayPayload.workerReplaySignatures), workerReplayFailures = readWorkerReplayFailureEntries(replayPayload.workerReplayFailures);
+  return buildReplayPayload({
+    ...accumulatedResults === void 0 ? {} : { accumulatedResults },
+    ...workerReplaySignatures === void 0 ? {} : { workerReplaySignatures },
+    ...workerReplayFailures === void 0 ? {} : { workerReplayFailures }
+  });
+}
+async function readCompactedCheckpointReplayPayload(storage, workflowId) {
+  const watermarkBytes = await storage.get(KEYS.eventWatermark(workflowId));
+  if (watermarkBytes === null)
+    return;
+  const watermark = decode(watermarkBytes);
+  if (!isRecord(watermark))
+    return;
+  const replayPayload = watermark.checkpointReplay;
+  return isRecord(replayPayload) ? readCheckpointReplayPayloadRecord(replayPayload) : void 0;
+}
+function readUnknownEntries(value) {
+  if (!Array.isArray(value))
+    return;
+  const entries = [];
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length !== 2 || !isReplayStep(entry[0]))
+      continue;
+    entries.push([entry[0], entry[1]]);
+  }
+  return entries;
+}
+function readWorkerReplaySignatureEntries(value) {
+  if (!Array.isArray(value))
+    return;
+  const entries = [];
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length !== 2 || !isReplayStep(entry[0]))
+      continue;
+    if (!isWorkerReplaySignature(entry[1]))
+      continue;
+    entries.push([entry[0], entry[1]]);
+  }
+  return entries;
+}
+function readWorkerReplayFailureEntries(value) {
+  if (!Array.isArray(value))
+    return;
+  const entries = [];
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length !== 2 || !isReplayStep(entry[0]))
+      continue;
+    if (!isWorkerReplayFailure(entry[1]))
+      continue;
+    entries.push([entry[0], entry[1]]);
+  }
+  return entries;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isReplayStep(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isWorkerReplaySignature(value) {
+  if (!isRecord(value))
+    return !1;
+  return value.format === WORKER_REPLAY_SIGNATURE_FORMAT && typeof value.operationType === "string" && typeof value.stableFieldsDigest === "string" && isReplayStep(value.stableFieldsByteLength);
+}
+function isWorkerReplayFailure(value) {
+  if (!isRecord(value))
+    return !1;
+  const failureCategory = value.failureCategory;
+  return value.status === "failed" && typeof value.error === "string" && (value.errorName === void 0 || typeof value.errorName === "string") && (failureCategory === void 0 || failureCategory === "application" || failureCategory === "cancellation" || failureCategory === "resource" || failureCategory === "system" || failureCategory === "timeout");
+}

package/dist/core/engine/checkpoint-side-effects.d.ts

@@ -0,0 +1,23 @@
+import type { BatchOperation, ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { EngineInternals } from './internals.ts';
+export type AtomicWorkflowCommitSideEffects = {
+    conditions: ConditionalBatchCondition[];
+    operations: BatchOperation[];
+};
+export declare function stageAtomicWorkflowCommitSideEffects(internals: EngineInternals, workflowId: string, sideEffects: AtomicWorkflowCommitSideEffects): void;
+export declare function takePendingAtomicWorkflowCommitSideEffects(internals: EngineInternals, workflowId: string): AtomicWorkflowCommitSideEffects | undefined;
+export declare function clearPendingAtomicWorkflowCommitSideEffects(internals: EngineInternals, workflowId: string): void;
+/**
+ * Non-destructively report whether a workflow's pending atomic side-effect buffer
+ * already stages a `put` to `key`. Unlike {@link takePendingAtomicWorkflowCommitSideEffects},
+ * this does NOT consume the buffer, so it is safe to call at a gate that runs before the
+ * commit that will flush those same side-effects.
+ *
+ * The terminal-transition path (#446) needs this: `ctx.setFinalizerState()` stages the
+ * `wf-finalizer-state:` put as a pending side-effect that the terminal batch flushes, but
+ * a pre-batch `storage.get()` cannot see a staged-but-unflushed write. Peeking the buffer
+ * lets the terminal batch stage its teardown marker atomically alongside that put — without
+ * it, a `setFinalizerState` with no intervening checkpoint would commit the resource state
+ * yet skip the teardown marker, silently leaking the external resource.
+ */
+export declare function pendingAtomicWorkflowCommitSideEffectsStagePut(internals: EngineInternals, workflowId: string, key: string): boolean;