@lostgradient/weft 0.2.0

package/dist/core/engine/errors.d.ts

@@ -0,0 +1,215 @@
+import { WeftError } from '../weft-error.ts';
+/**
+ * Thrown by {@link Engine.start} when a workflow with the requested ID already
+ * exists in storage. Inspect the `workflowId` property to identify the
+ * conflict. To allow deduplication semantics instead of an error, pass
+ * `idempotencyKey` in {@link StartOptions}.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, WorkflowAlreadyExistsError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ *
+ * await engine.start('ping', null, { id: 'my-ping' });
+ * try {
+ *   await engine.start('ping', null, { id: 'my-ping' });
+ * } catch (err) {
+ *   if (err instanceof WorkflowAlreadyExistsError) {
+ *     console.error('already running:', err.workflowId);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowAlreadyExistsError extends WeftError<'WorkflowAlreadyExistsError'> {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
+/**
+ * Thrown by {@link Engine.deleteAll} when the supplied filter would match
+ * non-terminal workflows. Narrow the filter to completed, failed, cancelled,
+ * or timed-out workflows before deleting in bulk.
+ *
+ * @example
+ * ```ts
+ * import { BulkDeleteRequiresTerminalWorkflowsError } from '@lostgradient/weft';
+ *
+ * function shouldShowTerminalOnlyMessage(error: unknown): boolean {
+ *   return error instanceof BulkDeleteRequiresTerminalWorkflowsError;
+ * }
+ * ```
+ */
+export declare class BulkDeleteRequiresTerminalWorkflowsError extends WeftError<'BulkDeleteRequiresTerminalWorkflowsError'> {
+    constructor();
+}
+/**
+ * Thrown by committed bulk operations when the supplied confirmation token no
+ * longer matches the current dry-run scope. Run a fresh preview and commit
+ * with the returned token.
+ *
+ * @example
+ * ```ts
+ * import { BulkOperationConfirmationError } from '@lostgradient/weft';
+ *
+ * function needsFreshBulkPreview(error: unknown): boolean {
+ *   return error instanceof BulkOperationConfirmationError;
+ * }
+ * ```
+ */
+export declare class BulkOperationConfirmationError extends WeftError<'BulkOperationConfirmationError'> {
+    constructor();
+}
+export type MissingWorkflowSample = {
+    readonly type: string;
+    readonly workflowId: string;
+};
+/**
+ * Thrown by {@link Engine.create} and {@link Engine.recoverAll} when storage
+ * contains running workflows whose workflow type has not been registered on
+ * the engine. The structured sample list is capped so logs remain bounded,
+ * while `missingTypes` and `registeredTypes` carry the full sorted type lists.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowTypeNotRegisteredForRecoveryError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.recoverAll();
+ * } catch (error) {
+ *   if (error instanceof WorkflowTypeNotRegisteredForRecoveryError) {
+ *     console.error('missing workflow types:', error.missingTypes);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowTypeNotRegisteredForRecoveryError extends WeftError<'WorkflowTypeNotRegisteredForRecoveryError'> {
+    readonly registeredTypes: readonly string[];
+    readonly missingTypes: readonly string[];
+    readonly missingWorkflowSamples: ReadonlyArray<MissingWorkflowSample>;
+    readonly missingWorkflowCount: number;
+    readonly samplesTruncated: boolean;
+    constructor(parameters: {
+        registeredTypes: Iterable<string>;
+        missingWorkflows: ReadonlyArray<MissingWorkflowSample>;
+    });
+}
+/**
+ * Thrown by {@link Engine.create} when a definition map key does not match the
+ * definition's runtime `name`. The factory uses map keys for type inference,
+ * so mismatches are rejected before registration to keep the inferred type and
+ * runtime registry aligned.
+ *
+ * @example
+ * ```ts
+ * import { activity, Engine, EngineCreateNameMismatchError } from '@lostgradient/weft';
+ *
+ * const farewell = activity({ name: 'farewell', execute: async () => 'bye' });
+ * try {
+ *   await Engine.create({ activities: { greet: farewell } });
+ * } catch (error) {
+ *   if (error instanceof EngineCreateNameMismatchError) {
+ *     console.error(error.expectedName, error.actualName);
+ *   }
+ * }
+ * ```
+ */
+export declare class EngineCreateNameMismatchError extends WeftError<'EngineCreateNameMismatchError'> {
+    readonly definitionKind: 'workflow' | 'activity';
+    readonly expectedName: string;
+    readonly actualName: string;
+    constructor(definitionKind: 'workflow' | 'activity', expectedName: string, actualName: string);
+}
+/**
+ * Thrown to settle a pending `handle.result()` promise when the engine is
+ * disposed while the workflow is still in flight. Disposing the engine tears
+ * down the machinery that would eventually resolve the result, so awaiting
+ * callers receive this rejection instead of a promise that never settles.
+ *
+ * @example
+ * ```ts
+ * import { EngineDisposedError } from '@lostgradient/weft';
+ *
+ * function isShutdownDuringResult(error: unknown): boolean {
+ *   return error instanceof EngineDisposedError;
+ * }
+ * ```
+ */
+export declare class EngineDisposedError extends WeftError<'EngineDisposedError'> {
+    constructor();
+}
+/**
+ * Thrown by engine APIs that need a workflow to be present in storage but
+ * cannot find one with the given ID. Inspect `workflowId` to identify the
+ * missing record.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowNotFoundError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.cancel('does-not-exist');
+ * } catch (err) {
+ *   if (err instanceof WorkflowNotFoundError) {
+ *     console.error('cannot cancel — no such workflow:', err.workflowId);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowNotFoundError extends WeftError<'WorkflowNotFoundError'> {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
+/**
+ * Thrown by {@link Engine.start} and other registry-driven entry points when
+ * the caller asks for a workflow type that was never registered. Distinct
+ * from `WorkflowNotFoundError`, which signals an unknown workflow ID at
+ * runtime.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowNotRegisteredError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.start('checkout', { orderId: 'order-1' });
+ * } catch (err) {
+ *   if (err instanceof WorkflowNotRegisteredError) {
+ *     console.error('register the workflow first:', err.workflowType);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowNotRegisteredError extends WeftError<'WorkflowNotRegisteredError'> {
+    readonly workflowType: string;
+    constructor(workflowType: string);
+}
+/**
+ * Thrown when the engine cannot resolve an activity name to a registered
+ * function during dispatch. The per-workflow {@link ActivityRegistry} (built
+ * from `workflow(...).activities({...})`) is consulted first; if the workflow
+ * type is unknown or the activity name is missing there, the engine falls back
+ * to the global registry. When neither resolves, this error is raised with the
+ * (bounded) workflow type and activity name so logs and operator surfaces can
+ * pin the misconfiguration without leaking high-cardinality detail.
+ *
+ * Replaces the prior unstructured `Error("No activity registered with name X")`
+ * thrown deep in `resolveActivityFunction`.
+ *
+ * @example
+ * ```ts
+ * import { workflow, ActivityResolutionError } from '@lostgradient/weft';
+ *
+ * function isMissingActivity(error: unknown): boolean {
+ *   return error instanceof ActivityResolutionError;
+ * }
+ * ```
+ */
+export declare class ActivityResolutionError extends WeftError<'ActivityResolutionError'> {
+    readonly workflowType: string;
+    readonly activityName: string;
+    constructor(workflowType: string, activityName: string);
+}
+export { PersistedDataIncompatibleError } from '../persisted-data-incompatible-error.ts';

package/dist/core/engine/errors.js

@@ -0,0 +1,90 @@
+import { WeftError } from "../weft-error.js";
+
+export class WorkflowAlreadyExistsError extends WeftError {
+  workflowId;
+  constructor(workflowId) {
+    super("WorkflowAlreadyExistsError", `Workflow with id "${workflowId}" already exists`);
+    this.workflowId = workflowId;
+  }
+}
+
+export class BulkDeleteRequiresTerminalWorkflowsError extends WeftError {
+  constructor() {
+    super("BulkDeleteRequiresTerminalWorkflowsError", "Bulk delete matches non-terminal workflows");
+  }
+}
+
+export class BulkOperationConfirmationError extends WeftError {
+  constructor() {
+    super("BulkOperationConfirmationError", "Bulk confirmation token does not match the current dry-run scope");
+  }
+}
+const MISSING_WORKFLOW_SAMPLE_LIMIT = 20, MISSING_TYPE_MESSAGE_LIMIT = 10;
+function summarizeMissingWorkflowTypes(missingTypes) {
+  const visibleTypes = missingTypes.slice(0, MISSING_TYPE_MESSAGE_LIMIT), hiddenTypeCount = missingTypes.length - visibleTypes.length;
+  return hiddenTypeCount > 0 ? `${visibleTypes.join(", ")} (+${hiddenTypeCount} more)` : visibleTypes.join(", ");
+}
+
+export class WorkflowTypeNotRegisteredForRecoveryError extends WeftError {
+  registeredTypes;
+  missingTypes;
+  missingWorkflowSamples;
+  missingWorkflowCount;
+  samplesTruncated;
+  constructor(parameters) {
+    const missingWorkflowCount = parameters.missingWorkflows.length, missingTypes = [
+      ...new Set(parameters.missingWorkflows.map((workflow) => workflow.type))
+    ].toSorted(), registeredTypes = [...parameters.registeredTypes].toSorted(), summarizedTypes = summarizeMissingWorkflowTypes(missingTypes);
+    super("WorkflowTypeNotRegisteredForRecoveryError", `Cannot recover ${missingWorkflowCount} running workflow(s): workflow type(s) not registered: ${summarizedTypes}. Register the missing workflow types before calling \`recoverAll()\`, or pass ` + "`{ acknowledgeUnknownWorkflowTypes: true }` (dangerous \u2014 see migration docs).");
+    this.registeredTypes = registeredTypes;
+    this.missingTypes = missingTypes;
+    this.missingWorkflowSamples = parameters.missingWorkflows.slice(0, MISSING_WORKFLOW_SAMPLE_LIMIT).map((workflow) => ({ ...workflow }));
+    this.missingWorkflowCount = missingWorkflowCount;
+    this.samplesTruncated = missingWorkflowCount > MISSING_WORKFLOW_SAMPLE_LIMIT;
+  }
+}
+
+export class EngineCreateNameMismatchError extends WeftError {
+  definitionKind;
+  expectedName;
+  actualName;
+  constructor(definitionKind, expectedName, actualName) {
+    super("EngineCreateNameMismatchError", `Engine.create() ${definitionKind} definition key "${expectedName}" does not match definition name "${actualName}"`);
+    this.definitionKind = definitionKind;
+    this.expectedName = expectedName;
+    this.actualName = actualName;
+  }
+}
+
+export class EngineDisposedError extends WeftError {
+  constructor() {
+    super("EngineDisposedError", "Engine was disposed before the workflow completed");
+  }
+}
+
+export class WorkflowNotFoundError extends WeftError {
+  workflowId;
+  constructor(workflowId) {
+    super("WorkflowNotFoundError", `Workflow "${workflowId}" not found`);
+    this.workflowId = workflowId;
+  }
+}
+
+export class WorkflowNotRegisteredError extends WeftError {
+  workflowType;
+  constructor(workflowType) {
+    super("WorkflowNotRegisteredError", `No workflow registered with name "${workflowType}"`);
+    this.workflowType = workflowType;
+  }
+}
+
+export class ActivityResolutionError extends WeftError {
+  workflowType;
+  activityName;
+  constructor(workflowType, activityName) {
+    super("ActivityResolutionError", `No activity registered with name "${activityName}" for workflow type "${workflowType}". Register the activity via \`workflow({ name }).activities({ ... })\` on the workflow that runs it, or via \`engine.register(activityDefinition)\` for the legacy global registry.`);
+    this.workflowType = workflowType;
+    this.activityName = activityName;
+  }
+}
+export { PersistedDataIncompatibleError } from "../persisted-data-incompatible-error.js";

package/dist/core/engine/event-log-compaction.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Event-log compaction: truncate old hash-chained event-log records behind a
+ * confirmed checkpoint to reclaim storage on long-running workflows.
+ *
+ * The canonical checkpoint at `KEYS.checkpoint` already holds the compacted
+ * execution state, and resume rebuilds from that checkpoint alone (never from
+ * event replay), so deleting records below a retention window does not affect
+ * resume correctness. To keep {@link EventLog.verify} from falsely reporting a
+ * broken hash chain after truncation, compaction writes an atomic **watermark**
+ * record in the SAME storage batch as the deletes: `verify()` seeds its chain
+ * walk from the watermark instead of genesis.
+ *
+ * Compaction is folded into the checkpoint commit batch (see
+ * `checkpoint-io.ts`), so the deletes and the watermark commit atomically with
+ * the new checkpoint — there is never a committed state where records are gone
+ * but the watermark is absent.
+ *
+ * @module core/engine/event-log-compaction
+ */
+import type { BatchOperation, Storage } from '../../storage/interface.ts';
+/**
+ * Upper bound on event-log records deleted in a single compaction (one
+ * checkpoint commit). A workflow that enables `retentionWindow` with a large
+ * pre-existing backlog compacts incrementally across successive checkpoints —
+ * the watermark advances by at most this many records per commit — rather than
+ * emitting one unbounded batch that could exceed storage batch limits, stall the
+ * execution path, or load the whole backlog into memory at once.
+ */
+export declare const MAX_COMPACTION_BATCH = 1000;
+/**
+ * The compaction watermark stored at `ev:{id}:watermark`. Marks where the live
+ * (post-compaction) event-log prefix begins so {@link EventLog.verify} can walk
+ * the surviving chain without a genesis predecessor.
+ *
+ * Internal: the shape is a storage implementation detail and is intentionally
+ * not exported from the package barrel.
+ */
+export type EventLogWatermark = {
+    type: 'event-log-watermark';
+    version: 1;
+    /** Lowest SURVIVING sequence; all records with `sequence < this` are deleted. */
+    sequence: number;
+    /**
+     * `hashBytes` of the raw stored bytes of the last deleted record
+     * (`sequence - 1`). Equals the surviving record `sequence`'s own `prevHash`
+     * field, so `verify()` validates the first surviving link from this seed.
+     */
+    prevHash: string;
+    /**
+     * Highest sequence deleted across ALL compactions (`sequence - 1`). Since the
+     * watermark only advances forward, `[0, deletedThrough]` is the complete
+     * deleted prefix — unambiguous across incremental batches.
+     */
+    deletedThrough: number;
+};
+/**
+ * Narrow an unknown decoded value to {@link EventLogWatermark}, rejecting
+ * internally inconsistent or out-of-range records (negative/non-integer
+ * sequences, `deletedThrough` that is not `sequence - 1`, empty `prevHash`) so a
+ * corrupt or hand-tampered watermark is never treated as authoritative.
+ */
+export declare function isEventLogWatermark(value: unknown): value is EventLogWatermark;
+/** Read and decode the watermark for a workflow, or `null` when absent/invalid. */
+export declare function readEventLogWatermark(storage: Storage, workflowId: string): Promise<EventLogWatermark | null>;
+/** Outcome of a compaction that contributed operations to a checkpoint batch. */
+export type CompactionResult = {
+    /** The watermark written in this batch. */
+    watermark: EventLogWatermark;
+    /** Raw stored bytes of the deleted records, in ascending sequence order. */
+    deletedEntries: Uint8Array[];
+    /** Inclusive sequence bounds of the records deleted in this batch. */
+    deletedRange: {
+        from: number;
+        to: number;
+    };
+};
+/**
+ * Append the delete + watermark operations for one compaction pass onto
+ * `operations`, to be committed atomically alongside a checkpoint batch.
+ *
+ * Returns `null` (a no-op — `operations` is left untouched) when:
+ * - compaction is disabled (`retentionWindow` is `null`);
+ * - there is nothing new to delete (`batchFirstSurviving <= currentFloor`);
+ * - the last-deleted record (`batchFirstSurviving - 1`) is missing — we cannot
+ *   derive a valid `prevHash`, so we abort rather than write an unvalidatable
+ *   watermark, leaving any pre-existing corruption visible to `verify()`;
+ * - the delete range is non-contiguous (a gap already exists) — aborting keeps
+ *   compaction from advancing the watermark past pre-existing corruption.
+ *
+ * @param retentionWindow  Keep at most this many most-recent records, or `null`
+ *   to disable compaction (a no-op).
+ * @param headSequence  The event-log head sequence AFTER the current
+ *   checkpoint append (`newHead.sequence`). The retention window is measured
+ *   against this, NOT `checkpoint.step`, so step/sequence need not stay coupled.
+ */
+export declare function appendCompactionOperations(storage: Storage, workflowId: string, headSequence: number, retentionWindow: number | null, operations: BatchOperation[]): Promise<CompactionResult | null>;
+/**
+ * Serialize the raw stored bytes of a deleted event-log range for an
+ * {@link import('../types/archive-adapter.ts').ArchiveAdapter}. Round-trips via
+ * the codec: `decode()` on the result yields the original `Uint8Array[]`.
+ */
+export declare function serializeDeletedEntries(entries: Uint8Array[]): Uint8Array;

package/dist/core/engine/event-log-compaction.js

@@ -0,0 +1,76 @@
+import { hashBytes } from "../../runtime/portable.js";
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { isWorkflowLogEntry } from "../event-log-shared.js";
+export const MAX_COMPACTION_BATCH = 1000;
+export function isEventLogWatermark(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const record = value;
+  if (record.type !== "event-log-watermark" || record.version !== 1)
+    return !1;
+  const prevHash = record.prevHash;
+  if (typeof prevHash !== "string" || prevHash.length === 0)
+    return !1;
+  return isConsistentWatermarkBounds(record.sequence, record.deletedThrough);
+}
+function isConsistentWatermarkBounds(sequence, deletedThrough) {
+  return typeof sequence === "number" && Number.isSafeInteger(sequence) && sequence > 0 && deletedThrough === sequence - 1;
+}
+export async function readEventLogWatermark(storage, workflowId) {
+  const bytes = await storage.get(KEYS.eventWatermark(workflowId));
+  if (bytes === null)
+    return null;
+  const decoded = decode(bytes);
+  return isEventLogWatermark(decoded) ? decoded : null;
+}
+export async function appendCompactionOperations(storage, workflowId, headSequence, retentionWindow, operations) {
+  if (retentionWindow === null)
+    return null;
+  const targetFirstSurviving = Math.max(0, headSequence - retentionWindow + 1), currentFloor = (await readEventLogWatermark(storage, workflowId))?.sequence ?? 0, batchFirstSurviving = Math.min(targetFirstSurviving, currentFloor + MAX_COMPACTION_BATCH);
+  if (batchFirstSurviving <= currentFloor)
+    return null;
+  const collected = await collectDeleteRange(storage, workflowId, currentFloor, batchFirstSurviving);
+  if (collected === null)
+    return null;
+  const prevHash = hashBytes(collected.lastDeletedBytes), watermark = {
+    type: "event-log-watermark",
+    version: 1,
+    sequence: batchFirstSurviving,
+    prevHash,
+    deletedThrough: batchFirstSurviving - 1
+  };
+  for (let sequence = currentFloor;sequence < batchFirstSurviving; sequence += 1)
+    operations.push({ type: "delete", key: KEYS.event(workflowId, sequence) });
+  operations.push({
+    type: "put",
+    key: KEYS.eventWatermark(workflowId),
+    value: encode(watermark)
+  });
+  return {
+    watermark,
+    deletedEntries: collected.deletedEntries,
+    deletedRange: { from: currentFloor, to: batchFirstSurviving - 1 }
+  };
+}
+async function collectDeleteRange(storage, workflowId, currentFloor, batchFirstSurviving) {
+  const deletedEntries = [];
+  let expected = currentFloor;
+  const prefix = KEYS.eventPrefix(workflowId), gte = KEYS.event(workflowId, currentFloor), lt = KEYS.event(workflowId, batchFirstSurviving);
+  for await (const [, bytes] of storage.scan(prefix, { gte, lt })) {
+    const decoded = decode(bytes);
+    if (!isWorkflowLogEntry(decoded) || decoded.sequence !== expected)
+      return null;
+    deletedEntries.push(bytes);
+    expected += 1;
+  }
+  if (expected !== batchFirstSurviving || deletedEntries.length === 0)
+    return null;
+  const lastDeletedBytes = deletedEntries[deletedEntries.length - 1];
+  if (lastDeletedBytes === void 0)
+    return null;
+  return { deletedEntries, lastDeletedBytes };
+}
+export function serializeDeletedEntries(entries) {
+  return encode(entries);
+}

package/dist/core/engine/guards.d.ts

@@ -0,0 +1,17 @@
+import type { WorkflowStatus } from '../types.ts';
+import { type UpdateResponse } from '../updates.ts';
+import type { EngineInternals } from './internals.ts';
+export declare const TERMINAL_STATUSES: ReadonlySet<WorkflowStatus>;
+export type GuardCallbacks = {
+    deleteRequestIfUnconsumed: (workflowId: string, updateId: string) => Promise<UpdateResponse | null>;
+    getUpdateResponse: (updateId: string) => Promise<UpdateResponse | null>;
+};
+/** Throw {@link WorkflowTerminalError} if the workflow is in a terminal state. */
+export declare function guardTerminalWorkflow(internals: EngineInternals, workflowId: string, _callbacks: GuardCallbacks): Promise<void>;
+/**
+ * Re-check terminal state after persisting a coordinated update request.
+ * This closes the race where the workflow completes between the preflight
+ * guard and request creation, which would otherwise leave the caller
+ * waiting for a response that can never arrive.
+ */
+export declare function guardTerminalWorkflowAfterCoordinatedRequest(internals: EngineInternals, workflowId: string, updateId: string, callbacks: GuardCallbacks): Promise<void>;

package/dist/core/engine/guards.js

@@ -0,0 +1,43 @@
+import { sleep } from "../../runtime/portable.js";
+import { KEYS } from "../../storage/interface.js";
+import { WorkflowTerminalError } from "../updates.js";
+import { decodeWorkflowState } from "./validation.js";
+const COORDINATED_UPDATE_CONSUMPTION_RETRY_ATTEMPTS = 5, COORDINATED_UPDATE_CONSUMPTION_RETRY_DELAY_MS = 5;
+export const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "timed-out"
+]);
+export async function guardTerminalWorkflow(internals, workflowId, _callbacks) {
+  const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  if (!stateBytes)
+    return;
+  const state = decodeWorkflowState(stateBytes);
+  if (TERMINAL_STATUSES.has(state.status))
+    throw new WorkflowTerminalError(workflowId, state.status);
+}
+async function coordinatedUpdateWasConsumed(internals, workflowId, updateId, callbacks) {
+  for (let attempt = 0;attempt < COORDINATED_UPDATE_CONSUMPTION_RETRY_ATTEMPTS; attempt++) {
+    if (await callbacks.getUpdateResponse(updateId) !== null)
+      return !0;
+    if (await internals.storage.get(KEYS.update(workflowId, updateId)) === null)
+      return !0;
+    if (attempt < COORDINATED_UPDATE_CONSUMPTION_RETRY_ATTEMPTS - 1)
+      await sleep(COORDINATED_UPDATE_CONSUMPTION_RETRY_DELAY_MS);
+  }
+  return !1;
+}
+export async function guardTerminalWorkflowAfterCoordinatedRequest(internals, workflowId, updateId, callbacks) {
+  try {
+    await guardTerminalWorkflow(internals, workflowId, callbacks);
+  } catch (error) {
+    if (error instanceof WorkflowTerminalError) {
+      if (await coordinatedUpdateWasConsumed(internals, workflowId, updateId, callbacks))
+        return;
+      if (await callbacks.deleteRequestIfUnconsumed(workflowId, updateId) !== null)
+        return;
+    }
+    throw error;
+  }
+}

package/dist/core/engine/handle-iteration.d.ts

@@ -0,0 +1,2 @@
+import type { WorkflowState } from '../types.ts';
+export declare function createWorkflowHandleEventIterator(handle: EventTarget, loadWorkflowState: () => Promise<WorkflowState | null>, synthesizeTerminalEvent: (state: WorkflowState) => Event | null): AsyncIterableIterator<Event>;

package/dist/core/engine/handle-iteration.js

@@ -0,0 +1,59 @@
+import { WORKFLOW_TERMINAL_EVENT_TYPES } from "../events/workflow-events.js";
+const WORKFLOW_HANDLE_NON_TERMINAL_EVENT_TYPES = [
+  "activity:started",
+  "activity:completed",
+  "signal:received"
+], WORKFLOW_HANDLE_TERMINAL_EVENT_TYPES = WORKFLOW_TERMINAL_EVENT_TYPES;
+export async function* createWorkflowHandleEventIterator(handle, loadWorkflowState, synthesizeTerminalEvent) {
+  const queue = { events: [], resolver: void 0 }, state = { done: !1 }, removeListeners = addWorkflowHandleIteratorListeners(handle, queue, state);
+  try {
+    if (!state.done)
+      synthesizeIteratorTerminalEvent(queue, state, await loadWorkflowState(), synthesizeTerminalEvent);
+    while (!state.done || queue.events.length > 0) {
+      if (queue.events.length === 0)
+        await waitForWorkflowHandleIteratorEvent(queue);
+      while (queue.events.length > 0)
+        yield queue.events.shift();
+    }
+  } finally {
+    removeListeners();
+  }
+}
+function addWorkflowHandleIteratorListeners(handle, queue, state) {
+  const listener = enqueueWorkflowHandleEvent.bind(void 0, queue), terminal = finishWorkflowHandleIteration.bind(void 0, state, queue);
+  for (const type of WORKFLOW_HANDLE_NON_TERMINAL_EVENT_TYPES)
+    handle.addEventListener(type, listener);
+  for (const type of WORKFLOW_HANDLE_TERMINAL_EVENT_TYPES)
+    handle.addEventListener(type, terminal);
+  return () => {
+    for (const type of WORKFLOW_HANDLE_NON_TERMINAL_EVENT_TYPES)
+      handle.removeEventListener(type, listener);
+    for (const type of WORKFLOW_HANDLE_TERMINAL_EVENT_TYPES)
+      handle.removeEventListener(type, terminal);
+  };
+}
+function enqueueWorkflowHandleEvent(queue, event) {
+  queue.events.push(event);
+  queue.resolver?.();
+}
+function finishWorkflowHandleIteration(state, queue, event) {
+  if (state.done)
+    return;
+  state.done = !0;
+  enqueueWorkflowHandleEvent(queue, event);
+}
+function synthesizeIteratorTerminalEvent(queue, state, persisted, synthesizeTerminalEvent) {
+  if (!persisted || state.done)
+    return;
+  const synthetic = synthesizeTerminalEvent(persisted);
+  if (!synthetic)
+    return;
+  queue.events.push(synthetic);
+  state.done = !0;
+}
+async function waitForWorkflowHandleIteratorEvent(queue) {
+  const { promise, resolve } = Promise.withResolvers();
+  queue.resolver = resolve;
+  await promise;
+  queue.resolver = void 0;
+}

package/dist/core/engine/handle-result.d.ts

@@ -0,0 +1,8 @@
+import type { WorkflowResultWaiter } from './engine-internal-types.ts';
+import { WorkflowHandle } from './handles.ts';
+import type { EngineInternals } from './internals.ts';
+export declare function createWorkflowHandleWithResultPromise(internals: EngineInternals, workflowId: string): WorkflowHandle;
+export declare function createWorkflowResultWaiter(internals: EngineInternals, workflowId: string): WorkflowResultWaiter;
+export declare function getWorkflowResultPromise(internals: EngineInternals, workflowId: string): Promise<unknown>;
+export declare function bootstrapWorkflowResultResolver(internals: EngineInternals, workflowId: string, waiter: WorkflowResultWaiter): Promise<void>;
+export declare function cacheHandle(internals: EngineInternals, workflowId: string, handle: WorkflowHandle): void;