@lostgradient/weft 0.3.0 → 0.4.0

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;

package/dist/core/engine/checkpoint-side-effects.js

@@ -0,0 +1,35 @@
+export function stageAtomicWorkflowCommitSideEffects(internals, workflowId, sideEffects) {
+  if (sideEffects.conditions.length === 0 && sideEffects.operations.length === 0)
+    return;
+  const pending = internals.pendingAtomicWorkflowCommitSideEffects.get(workflowId);
+  if (pending === void 0) {
+    internals.pendingAtomicWorkflowCommitSideEffects.set(workflowId, {
+      conditions: [...sideEffects.conditions],
+      operations: [...sideEffects.operations]
+    });
+    return;
+  }
+  pending.conditions.push(...sideEffects.conditions);
+  pending.operations.push(...sideEffects.operations);
+}
+export function takePendingAtomicWorkflowCommitSideEffects(internals, workflowId) {
+  const pending = internals.pendingAtomicWorkflowCommitSideEffects.get(workflowId);
+  if (pending === void 0)
+    return;
+  internals.pendingAtomicWorkflowCommitSideEffects.delete(workflowId);
+  if (pending.conditions.length === 0 && pending.operations.length === 0)
+    return;
+  return {
+    conditions: [...pending.conditions],
+    operations: [...pending.operations]
+  };
+}
+export function clearPendingAtomicWorkflowCommitSideEffects(internals, workflowId) {
+  internals.pendingAtomicWorkflowCommitSideEffects.delete(workflowId);
+}
+export function pendingAtomicWorkflowCommitSideEffectsStagePut(internals, workflowId, key) {
+  const pending = internals.pendingAtomicWorkflowCommitSideEffects.get(workflowId);
+  if (pending === void 0)
+    return !1;
+  return pending.operations.some((operation) => operation.type === "put" && operation.key === key);
+}

package/dist/core/engine/child-workflow-cancellation.d.ts

@@ -0,0 +1,10 @@
+import { type BatchOperation } from '../../storage/interface.ts';
+import type { WorkflowHandle } from './handles.ts';
+import type { EngineInternals } from './internals.ts';
+type ChildCancellationCallbacks = {
+    getHandle: (workflowId: string) => WorkflowHandle;
+};
+export declare function buildChildCancellationOperations(internals: EngineInternals, workflowId: string, childWorkflowId: string): BatchOperation[];
+export declare function registerChildCancellationHandler(internals: EngineInternals, workflowId: string, childWorkflowId: string, callbacks: ChildCancellationCallbacks): void;
+export declare function rehydrateChildCancellationHandlers(internals: EngineInternals, workflowId: string, callbacks: ChildCancellationCallbacks): Promise<void>;
+export {};

package/dist/core/engine/child-workflow-cancellation.js

@@ -0,0 +1,40 @@
+import { KEYS, decodeStorageKeyComponent } from "../../storage/interface.js";
+import { registerCancelHandler } from "./cancel-handlers.js";
+import { EMPTY_STORAGE_VALUE } from "./lifecycle/shared.js";
+export function buildChildCancellationOperations(internals, workflowId, childWorkflowId) {
+  const operations = [
+    {
+      type: "put",
+      key: KEYS.childCancellation(workflowId, childWorkflowId),
+      value: EMPTY_STORAGE_VALUE
+    }
+  ], needsCleanupMarker = !internals.workflowsNeedingTerminalCleanup.has(workflowId);
+  internals.workflowsNeedingTerminalCleanup.add(workflowId);
+  if (needsCleanupMarker)
+    operations.push({
+      type: "put",
+      key: KEYS.terminalCleanupNeeded(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    });
+  return operations;
+}
+export function registerChildCancellationHandler(internals, workflowId, childWorkflowId, callbacks) {
+  registerCancelHandler(internals, workflowId, () => callbacks.getHandle(childWorkflowId).cancel());
+}
+export async function rehydrateChildCancellationHandlers(internals, workflowId, callbacks) {
+  for await (const [key] of internals.storage.scan(KEYS.childCancellationPrefix(workflowId))) {
+    const childWorkflowId = decodeChildCancellationKey(workflowId, key);
+    if (childWorkflowId === null)
+      continue;
+    registerChildCancellationHandler(internals, workflowId, childWorkflowId, callbacks);
+  }
+}
+function decodeChildCancellationKey(workflowId, key) {
+  const prefix = KEYS.childCancellationPrefix(workflowId);
+  if (!key.startsWith(prefix))
+    return null;
+  const encodedChildWorkflowId = key.slice(prefix.length);
+  if (encodedChildWorkflowId.length === 0 || encodedChildWorkflowId.includes(":"))
+    return null;
+  return decodeStorageKeyComponent(encodedChildWorkflowId);
+}

package/dist/core/engine/child-workflow.js

@@ -1,3 +1,9 @@
+import { assertOnTerminalConflictUnsupported } from "../start-workflow-validation.js";
+import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
+import {
+  buildChildCancellationOperations,
+  registerChildCancellationHandler
+} from "./child-workflow-cancellation.js";
 import { WorkflowAlreadyExistsError } from "./errors.js";
 import { encodedValuesEqual } from "./state-utilities.js";
 export async function processChildWorkflowOperation(internals, workflowId, operation, callbacks) {
@@ -37,6 +43,7 @@ async function resolveCollisionChildHandle(childWorkflowId, operation, execution
   return callbacks.getHandle(childWorkflowId);
 }
 async function dispatchChildWorkflowStart(internals, childWorkflowId, operation, context, callbacks) {
+  assertOnTerminalConflictUnsupported(operation.options, "ctx.startChild");
   applyPendingChildExecutionContext(internals, context);
   try {
     return await callbacks.start(operation.workflowType, operation.input, {
@@ -45,19 +52,29 @@ async function dispatchChildWorkflowStart(internals, childWorkflowId, operation,
   } catch (error) {
     if (!(error instanceof WorkflowAlreadyExistsError))
       throw error;
-    return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId, error, callbacks);
+    return resolveCollisionChildHandle(childWorkflowId, operation, context.pendingExecutionStateOwnerId ?? void 0, error, callbacks);
   } finally {
     clearPendingChildExecutionContext(internals, context);
   }
 }
 export async function executeChildWorkflow(internals, workflowId, operation, currentDepth, callbacks) {
-  const rawId = operation.options?.id, childWorkflowId = typeof rawId === "string" ? rawId : crypto.randomUUID(), parentHeaders = internals.workflowHeaders.get(workflowId) ?? new Map, executionStateOwnerId = (await callbacks.loadWorkflowState(workflowId))?.executionStateOwnerId ?? workflowId, executeChild = async () => {
+  const rawId = operation.options?.id, childWorkflowId = typeof rawId === "string" ? rawId : crypto.randomUUID(), parentHeaders = internals.workflowHeaders.get(workflowId) ?? new Map, parentState = await callbacks.loadWorkflowState(workflowId), parentClosePolicy = resolveChildWorkflowParentClosePolicy(operation), executionStateOwnerId = parentClosePolicy === "abandon" ? null : parentState?.executionStateOwnerId ?? workflowId, executeChild = async () => {
     const context = {
       pendingNestingDepth: currentDepth + 1,
       pendingParentHeaders: internals.workflowHeaders.get(workflowId),
       pendingExecutionStateOwnerId: executionStateOwnerId
-    };
-    return (await dispatchChildWorkflowStart(internals, childWorkflowId, operation, context, callbacks)).result();
+    }, childHandle = await dispatchChildWorkflowStart(internals, childWorkflowId, operation, context, callbacks);
+    if (parentClosePolicy === "abandon")
+      return createChildWorkflowHandleReference(childHandle.id);
+    if (parentClosePolicy === "request-cancel") {
+      stageAtomicWorkflowCommitSideEffects(internals, workflowId, {
+        conditions: [],
+        operations: buildChildCancellationOperations(internals, workflowId, childHandle.id)
+      });
+      registerChildCancellationHandler(internals, workflowId, childHandle.id, callbacks);
+      return createChildWorkflowHandleReference(childHandle.id);
+    }
+    return childHandle.result();
   }, composedInterceptor = callbacks.getComposedWorkflowInterceptor();
   if (!composedInterceptor)
     return executeChild();
@@ -70,3 +87,9 @@ export async function executeChildWorkflow(internals, workflowId, operation, cur
     parentHeaders
   }, executeChild);
 }
+function resolveChildWorkflowParentClosePolicy(operation) {
+  return operation.options?.parentClosePolicy ?? "await";
+}
+function createChildWorkflowHandleReference(workflowId) {
+  return { id: workflowId };
+}

package/dist/core/engine/condition-waiters.d.ts

@@ -0,0 +1,14 @@
+import type { EngineInternals } from './internals.ts';
+/**
+ * Re-drive every in-process `ctx.waitUntil` waiter registered for a workflow.
+ * Called after an inline `onUpdate` handler runs (`tryInlineUpdateHandler`),
+ * since the handler may have mutated the workflow-local state a predicate reads.
+ * Each call wakes the parked `processWaitConditionOperation`, which re-evaluates
+ * its predicate against the (possibly mutated) state.
+ *
+ * Weft signals are pull-only (`ctx.waitForSignal`) and run no state-mutating
+ * handler, so signal delivery is intentionally NOT a re-drive trigger — `onUpdate`
+ * is the push path. Lives in its own module so `updates.ts` can call it without
+ * an import cycle through `operations-coordination.ts`.
+ */
+export declare function notifyConditionWaiters(internals: EngineInternals, workflowId: string): void;

package/dist/core/engine/condition-waiters.js

@@ -0,0 +1,5 @@
+export function notifyConditionWaiters(internals, workflowId) {
+  const resolve = internals.conditionWaiters.get(workflowId);
+  if (resolve)
+    resolve();
+}