@lostgradient/weft 0.2.0

package/dist/core/engine/workflow-visibility-queries.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Query helpers that read the workflow visibility indexes laid down by
+ * {@link buildWorkflowVisibilityIndexTransition} / backfill. Each helper
+ * produces a `Set<string>` of candidate workflow ids; the caller
+ * intersects sets across dimensions to narrow the slow-path scan.
+ *
+ * Every helper assumes the visibility-index watermark is `current` — the
+ * caller checks {@link getWorkflowVisibilityWatermark} once per query and
+ * falls back to the legacy scan path when it is `stale`.
+ *
+ * @module core/engine/workflow-visibility-queries
+ */
+import { type Storage } from '../../storage/interface.ts';
+import type { FailureCategory, WorkflowStatus } from '../types/identity.ts';
+import type { TimeRange } from '../types/options.ts';
+/**
+ * Match every workflow whose `status` appears in `statuses`. Empty input
+ * returns an empty set (intersection short-circuits to "no matches").
+ */
+export declare function queryWorkflowStatusIndex(storage: Storage, statuses: readonly WorkflowStatus[]): Promise<Set<string>>;
+/** Match every workflow with the given `type`. */
+export declare function queryWorkflowTypeIndex(storage: Storage, type: string): Promise<Set<string>>;
+/**
+ * Time-range scan over `wf-idx-{kind}:` (created, updated, or deadline).
+ * Returns the candidate ids the engine post-filter will refine.
+ */
+export declare function queryWorkflowTimeRangeIndex(storage: Storage, kind: 'created' | 'updated' | 'deadline', range: TimeRange): Promise<Set<string>>;
+/**
+ * Enumerate candidate workflow ids whose raw id starts with `idPrefix`.
+ * Uses the primary-key `wf:{enc(prefix)}` scan, which is sound because the
+ * encoder is identity + concatenation-preserving on the validated safe
+ * subset (see `src/storage/interface.test.ts`). The caller still re-checks
+ * `state.id.startsWith(idPrefix)` as a defensive post-filter.
+ */
+export declare function queryWorkflowIdPrefixCandidates(storage: Storage, idPrefix: string): Promise<Set<string>>;
+/**
+ * Re-export for callers that only need the failure-category value type.
+ * Keeps imports tidy at the call sites.
+ */
+export type { FailureCategory };

package/dist/core/engine/workflow-visibility-queries.js

@@ -0,0 +1,56 @@
+import {
+  encodeStorageKeyComponent,
+  tryDecodeStorageKeyComponent
+} from "../../storage/interface.js";
+function isFinitePositive(value) {
+  return Number.isFinite(value) && value >= 0;
+}
+function sortableTimestamp(value) {
+  return String(value).padStart(16, "0");
+}
+async function collectWorkflowIdsFromIndex(storage, prefix, options) {
+  const ids = new Set;
+  for await (const [key] of storage.scan(prefix, options)) {
+    const encoded = key.slice(key.lastIndexOf(":") + 1), workflowId = tryDecodeStorageKeyComponent(encoded);
+    if (workflowId !== null)
+      ids.add(workflowId);
+  }
+  return ids;
+}
+export async function queryWorkflowStatusIndex(storage, statuses) {
+  const ids = new Set;
+  for (const status of statuses) {
+    const prefix = `wf-idx-status:${encodeStorageKeyComponent(status)}:`;
+    for (const id of await collectWorkflowIdsFromIndex(storage, prefix))
+      ids.add(id);
+  }
+  return ids;
+}
+export async function queryWorkflowTypeIndex(storage, type) {
+  const prefix = `wf-idx-type:${encodeStorageKeyComponent(type)}:`;
+  return collectWorkflowIdsFromIndex(storage, prefix);
+}
+export async function queryWorkflowTimeRangeIndex(storage, kind, range) {
+  const prefix = `wf-idx-${kind}:`, scanOptions = {};
+  if (range.gte !== void 0 && isFinitePositive(range.gte))
+    scanOptions.gte = `${prefix}${sortableTimestamp(range.gte)}:`;
+  if (range.gt !== void 0 && isFinitePositive(range.gt))
+    scanOptions.gt = `${prefix}${sortableTimestamp(range.gt)}:\xFF`;
+  if (range.lte !== void 0 && isFinitePositive(range.lte))
+    scanOptions.lte = `${prefix}${sortableTimestamp(range.lte)}:\xFF`;
+  if (range.lt !== void 0 && isFinitePositive(range.lt))
+    scanOptions.lt = `${prefix}${sortableTimestamp(range.lt)}:`;
+  return collectWorkflowIdsFromIndex(storage, prefix, scanOptions);
+}
+export async function queryWorkflowIdPrefixCandidates(storage, idPrefix) {
+  const ids = new Set, prefix = `wf:${encodeStorageKeyComponent(idPrefix)}`;
+  for await (const [key] of storage.scan(prefix)) {
+    const idPart = key.slice(3);
+    if (idPart.includes(":"))
+      continue;
+    const workflowId = tryDecodeStorageKeyComponent(idPart);
+    if (workflowId !== null)
+      ids.add(workflowId);
+  }
+  return ids;
+}

package/dist/core/engine-helpers.d.ts

@@ -0,0 +1,56 @@
+import type { Storage as WeftStorage } from '../storage/interface.ts';
+/** Build a cleanup reporter that preserves the workflow identifier for downstream error handling. */
+export declare function createCleanupErrorReporter(onCleanupError: (source: string, error: unknown, workflowId: string) => void, workflowId: string): (source: string, error: unknown, _ignoredWorkflowId: string) => void;
+/** Create a finalizer callback that evicts only the stale handle entry that was actually finalized. */
+export declare function createHandleCacheFinalizer<TValue extends object>(handleCache: Map<string, {
+    ref: Pick<WeakRef<TValue>, 'deref'>;
+}>): (workflowId: string) => void;
+/** Create the periodic update-response cleanup callback used by the engine interval. */
+export declare function createExpiredResponseCleanupTick(updateCoordinator: {
+    cleanupExpiredResponses(): Promise<unknown>;
+}, onCleanupError: (source: string, error: unknown) => void): () => void;
+/** Delete partially written stream chunks and surface any cleanup failure through the callback. */
+export declare function cleanupPartialStreamChunks(storage: WeftStorage, workflowId: string, key: string, writtenKeys: string[], onCleanupError: (source: string, error: unknown, workflowId: string) => void): Promise<void>;
+/**
+ * Settled outcome for a single `ctx.runAll` branch. Returned by
+ * `executeRunAllBranchesSettled` so callers can record partial-failure
+ * state in the parent operation's cache entry before propagating the
+ * first rejection.
+ */
+export type RunAllBranchOutcome = {
+    status: 'fulfilled';
+    name: string;
+    value: unknown;
+} | {
+    status: 'rejected';
+    name: string;
+    reason: unknown;
+};
+/**
+ * Result of `executeRunAllBranchesSettled`. `firstError` carries the
+ * original rejection reason captured by settlement timing (matching
+ * native `Promise.all` behavior — whichever branch rejects first at
+ * runtime, not whichever appears first in branch insertion order).
+ * `hasFirstError` distinguishes "no rejection" from "rejected with
+ * `undefined`" (a workflow that threw `undefined` explicitly).
+ */
+export type RunAllSettledResult = {
+    outcomes: RunAllBranchOutcome[];
+    hasFirstError: boolean;
+    firstError: unknown;
+};
+export type RunAllBranch = readonly [fn: Function] | readonly [fn: Function, input: unknown];
+/**
+ * Execute every `ctx.runAll()` branch and return per-branch settled
+ * outcomes plus the first rejection captured by settlement timing.
+ * Never rejects: callers inspect the result and decide how to surface
+ * failure. Used by the top-level run-all dispatch path so fulfilled
+ * branches can be persisted before any rejection propagates.
+ *
+ * The first-rejection-by-settlement-timing contract is shared with
+ * `dispatchBranchesAllSettled` via the `FirstRejectionCapture` helper
+ * to keep both fan-out paths consistent.
+ */
+export declare function executeRunAllBranchesSettled(branches: Record<string, RunAllBranch>, callActivity: (fn: Function, input: unknown) => unknown): Promise<RunAllSettledResult>;
+/** Execute the `ctx.runAll()` branches and return a name-keyed result record. */
+export declare function executeRunAllBranches(branches: Record<string, RunAllBranch>, callActivity: (fn: Function, input: unknown) => unknown): Promise<Record<string, unknown>>;

package/dist/core/engine-helpers.js

@@ -0,0 +1,52 @@
+import { KEYS } from "../storage/interface.js";
+import { captureFirstRejection, createFirstRejectionCapture } from "./engine/parallel-dispatch.js";
+export function createCleanupErrorReporter(onCleanupError, workflowId) {
+  return (source, error) => {
+    onCleanupError(source, error, workflowId);
+  };
+}
+export function createHandleCacheFinalizer(handleCache) {
+  return (workflowId) => {
+    const entry = handleCache.get(workflowId);
+    if (!entry || entry.ref.deref() !== void 0)
+      return;
+    handleCache.delete(workflowId);
+  };
+}
+export function createExpiredResponseCleanupTick(updateCoordinator, onCleanupError) {
+  return () => {
+    updateCoordinator.cleanupExpiredResponses().catch((error) => {
+      onCleanupError("cleanupExpiredResponses", error);
+    });
+  };
+}
+export async function cleanupPartialStreamChunks(storage, workflowId, key, writtenKeys, onCleanupError) {
+  if (writtenKeys.length === 0)
+    return;
+  const deleteOperations = [
+    ...writtenKeys.map((writtenKey) => ({ type: "delete", key: writtenKey })),
+    { type: "delete", key: KEYS.streamMetadata(workflowId, key) }
+  ];
+  await storage.batch(deleteOperations).catch((deleteError) => {
+    onCleanupError("cleanupPartialStreamChunks", deleteError, workflowId);
+  });
+}
+export async function executeRunAllBranchesSettled(branches, callActivity) {
+  const entries = Object.entries(branches), capture = createFirstRejectionCapture();
+  return { outcomes: await Promise.all(entries.map(async ([name, [fn, input]]) => {
+    try {
+      const value = await callActivity(fn, input);
+      return { status: "fulfilled", name, value };
+    } catch (error) {
+      captureFirstRejection(capture, error);
+      return { status: "rejected", name, reason: error };
+    }
+  })), hasFirstError: capture.hasFirstError, firstError: capture.firstError };
+}
+export async function executeRunAllBranches(branches, callActivity) {
+  const results = {}, entries = Object.entries(branches);
+  await Promise.all(entries.map(async ([name, [fn, input]]) => {
+    results[name] = await callActivity(fn, input);
+  }));
+  return results;
+}

package/dist/core/engine.d.ts

@@ -0,0 +1 @@
+export * from './engine/index.ts';

package/dist/core/engine.js

@@ -0,0 +1 @@
+export * from "./engine/index.js";

package/dist/core/event-log-shared.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared primitives for the hash-chained event log: record shapes, the genesis
+ * hash, type guards, the byte hasher, and the head reader. Split out so both
+ * {@link EventLog} (`event-log.ts`) and the watermark-aware verifier
+ * (`event-log-verify.ts`) can depend on them without an import cycle.
+ *
+ * @module core/event-log-shared
+ */
+import type { Storage } from '../storage/interface.ts';
+import type { WorkflowVersionTuple } from './workflow-version-tuple.ts';
+/** Hash value used as `prevHash` for the very first entry in a log. */
+export declare const GENESIS_HASH = "0000000000000000";
+/** A single entry in the event log, as stored in the KV backend. */
+export interface WorkflowLogEntry {
+    /** Discriminates the entry type, e.g. `'workflow:checkpoint'`. */
+    type: string;
+    /** Workflow this entry belongs to. */
+    workflowId: string;
+    /** Zero-based monotonic sequence number. */
+    sequence: number;
+    /**
+     * wyhash (16 hex chars) of the *encoded bytes* of the previous entry.
+     * The first entry carries {@link GENESIS_HASH}.
+     */
+    prevHash: string;
+    /** Arbitrary event payload. */
+    payload: unknown;
+    /** Unix timestamp (ms) at the time of the append. */
+    timestamp: number;
+    /**
+     * Workflow, agent, and tool version tuple captured at the time of this
+     * entry. Only present when the caller passes a `versionTuple` argument.
+     * Absent for entries written by non-agent workflows or callers that opt out.
+     */
+    versionTuple?: WorkflowVersionTuple;
+}
+/**
+ * The head record stored at `ev:{workflowId}:head`.
+ * Tracks both the latest sequence number and the hash of the last committed
+ * entry so that subsequent appends can chain without a second storage read.
+ */
+export interface EventHeadRecord {
+    sequence: number;
+    lastHash: string;
+}
+/**
+ * The head state for a workflow with no committed entries.
+ * Used as the starting point when appending the first event.
+ * Frozen to prevent accidental mutation of the shared genesis sentinel.
+ */
+export declare const EMPTY_EVENT_HEAD: Readonly<EventHeadRecord>;
+/** Compute a 16-character hex hash of an arbitrary byte buffer. */
+export declare function hashBytes(bytes: Uint8Array): string;
+/** Narrow an unknown decoded value to {@link WorkflowLogEntry}. */
+export declare function isWorkflowLogEntry(value: unknown): value is WorkflowLogEntry;
+/** Narrow an unknown decoded value to {@link EventHeadRecord}. */
+export declare function isEventHeadRecord(value: unknown): value is EventHeadRecord;
+/**
+ * Read the current head record for a workflow from storage.
+ *
+ * Returns {@link EMPTY_EVENT_HEAD} (`sequence: -1`) when no head record exists
+ * (i.e., the log is empty). This lets the first append compute `sequence = 0`
+ * and `prevHash = GENESIS_HASH`.
+ */
+export declare function readEventHead(storage: Storage, workflowId: string): Promise<EventHeadRecord>;

package/dist/core/event-log-shared.js

@@ -0,0 +1,31 @@
+import { hashBytes as portableHashBytes } from "../runtime/portable.js";
+import { KEYS } from "../storage/interface.js";
+import { decode } from "./codec.js";
+export const GENESIS_HASH = "0000000000000000", EMPTY_EVENT_HEAD = Object.freeze({
+  sequence: -1,
+  lastHash: GENESIS_HASH
+});
+export function hashBytes(bytes) {
+  return portableHashBytes(bytes);
+}
+export function isWorkflowLogEntry(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const obj = value;
+  return typeof obj.type === "string" && typeof obj.workflowId === "string" && typeof obj.sequence === "number" && typeof obj.prevHash === "string" && typeof obj.timestamp === "number" && "payload" in obj;
+}
+export function isEventHeadRecord(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const obj = value;
+  return typeof obj.sequence === "number" && typeof obj.lastHash === "string";
+}
+export async function readEventHead(storage, workflowId) {
+  const bytes = await storage.get(KEYS.eventHead(workflowId));
+  if (bytes === null)
+    return { sequence: -1, lastHash: GENESIS_HASH };
+  const decoded = decode(bytes);
+  if (isEventHeadRecord(decoded))
+    return decoded;
+  return { sequence: -1, lastHash: GENESIS_HASH };
+}

package/dist/core/event-log-verify.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Watermark-aware hash-chain verification for the event log.
+ *
+ * Split out from `event-log.ts` so the (intricate) concurrent-compaction retry
+ * logic lives on its own. Depends only on the shared primitives in
+ * `event-log-shared.ts` and the watermark reader in `event-log-compaction.ts`,
+ * so there is no import cycle with `event-log.ts`.
+ *
+ * @module core/event-log-verify
+ */
+import type { Storage } from '../storage/interface.ts';
+/**
+ * Result of {@link verifyEventLog}. The `indeterminate` variant keeps
+ * `valid: false` so existing `if (result.valid)` callers never get a false
+ * positive, but signals that verification could not complete because the log
+ * was being compacted concurrently — it is NOT a corruption report (it carries
+ * no `firstInvalidSequence`).
+ */
+export type VerifyResult = {
+    valid: true;
+} | {
+    valid: false;
+    firstInvalidSequence: number;
+} | {
+    valid: false;
+    indeterminate: true;
+    reason: 'concurrent-compaction';
+};
+/**
+ * Walk a workflow's event log and verify hash-chain integrity.
+ *
+ * When event-log compaction has truncated the early records, a
+ * {@link EventLogWatermark} at `ev:{id}:watermark` marks where the surviving
+ * chain begins; verification seeds its walk from the watermark's `prevHash`
+ * instead of {@link GENESIS_HASH} so a compacted log does not look broken.
+ *
+ * A compaction can commit concurrently (before or during the scan); to avoid
+ * reporting a *false* chain break, the walk re-reads the watermark on any break
+ * and, only when the watermark has ACTUALLY ADVANCED past the snapshot the
+ * failing pass used, restarts — up to a small bound. A stable break is genuine
+ * corruption. If it never stabilizes, the result is flagged `indeterminate`.
+ *
+ * Corruption cases worth calling out: a watermark pointing at a first surviving
+ * record that is no longer present is reported at `watermark.sequence`; a tail
+ * record lost while the head still points past it is reported at the missing
+ * sequence (the tail is cross-checked against `ev:{id}:head`); and a compacted
+ * log whose watermark was removed (e.g. a code rollback) is reported broken at
+ * the expected genesis sequence rather than silently passing — compaction is
+ * one-way.
+ */
+export declare function verifyEventLog(storage: Storage, workflowId: string): Promise<VerifyResult>;

package/dist/core/event-log-verify.js

@@ -0,0 +1,64 @@
+import { KEYS } from "../storage/interface.js";
+import { decode } from "./codec.js";
+import { readEventLogWatermark } from "./engine/event-log-compaction.js";
+import {
+  EMPTY_EVENT_HEAD,
+  GENESIS_HASH,
+  hashBytes,
+  isWorkflowLogEntry,
+  readEventHead
+} from "./event-log-shared.js";
+export async function verifyEventLog(storage, workflowId) {
+  const MAX_ATTEMPTS = 5;
+  for (let attempt = 0;attempt < MAX_ATTEMPTS; attempt += 1) {
+    const watermark = await readEventLogWatermark(storage, workflowId), head = await readEventHead(storage, workflowId), result = await verifyAgainstSnapshot(storage, workflowId, watermark, head);
+    if (result.outcome === "ok")
+      return { valid: !0 };
+    const watermarkAfter = await readEventLogWatermark(storage, workflowId), headAfter = await readEventHead(storage, workflowId), watermarkMoved = (watermarkAfter?.sequence ?? -1) > (watermark?.sequence ?? -1), headMoved = headAfter.sequence !== head.sequence || headAfter.lastHash !== head.lastHash;
+    if (watermarkMoved || headMoved)
+      continue;
+    return { valid: !1, firstInvalidSequence: result.firstInvalidSequence };
+  }
+  return { valid: !1, indeterminate: !0, reason: "concurrent-compaction" };
+}
+async function verifyAgainstSnapshot(storage, workflowId, watermark, head) {
+  const seed = watermark?.prevHash ?? GENESIS_HASH, expectedFirstSequence = watermark?.sequence ?? 0, prefix = KEYS.eventPrefix(workflowId), options = watermark ? { gte: KEYS.event(workflowId, watermark.sequence) } : void 0, scan = await scanChain(storage, prefix, options, seed, expectedFirstSequence);
+  if (scan.outcome === "invalid")
+    return scan;
+  if (scan.entriesSeen === 0 && watermark !== null)
+    return { outcome: "invalid", firstInvalidSequence: watermark.sequence };
+  return verifyTailAgainstHead(scan, head);
+}
+function verifyTailAgainstHead(scan, head) {
+  if (head.sequence === EMPTY_EVENT_HEAD.sequence)
+    return scan.entriesSeen === 0 ? { outcome: "ok" } : { outcome: "invalid", firstInvalidSequence: 0 };
+  if (scan.entriesSeen === 0)
+    return { outcome: "invalid", firstInvalidSequence: head.sequence };
+  if (scan.lastSequence !== head.sequence)
+    return { outcome: "invalid", firstInvalidSequence: scan.lastSequence + 1 };
+  if (scan.lastHash !== head.lastHash)
+    return { outcome: "invalid", firstInvalidSequence: scan.lastSequence };
+  return { outcome: "ok" };
+}
+async function scanChain(storage, prefix, options, seed, expectedFirstSequence) {
+  let previousHash = seed, entriesSeen = 0, lastSequence = -1;
+  for await (const [, bytes] of storage.scan(prefix, options)) {
+    const decoded = decode(bytes);
+    if (!isWorkflowLogEntry(decoded))
+      continue;
+    const link = checkChainLink(decoded, previousHash, entriesSeen === 0, expectedFirstSequence);
+    if (link.outcome === "invalid")
+      return link;
+    entriesSeen += 1;
+    lastSequence = decoded.sequence;
+    previousHash = hashBytes(bytes);
+  }
+  return { outcome: "scanned", entriesSeen, lastSequence, lastHash: previousHash };
+}
+function checkChainLink(entry, previousHash, isFirst, expectedFirstSequence) {
+  if (isFirst && entry.sequence !== expectedFirstSequence)
+    return { outcome: "invalid", firstInvalidSequence: expectedFirstSequence };
+  if (entry.prevHash !== previousHash)
+    return { outcome: "invalid", firstInvalidSequence: entry.sequence };
+  return { outcome: "ok" };
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Hash-chained event log for durable workflow event sourcing.
+ *
+ * Each workflow accumulates an append-only log of `WorkflowLogEntry` records
+ * stored under `ev:{workflowId}:{sequence}`. A separate head record at
+ * `ev:{workflowId}:head` tracks the current sequence counter and the hash of
+ * the most recently committed entry.
+ *
+ * Entries are chained by a `prevHash` field (wyhash of the previous entry's
+ * encoded bytes), enabling tamper detection via {@link EventLog.verify}.
+ *
+ * Callers that hold a batch accumulator (e.g. the engine's checkpoint writer)
+ * pass it to {@link EventLog.append} so that the event write is included in
+ * the same atomic `storage.batch()` call as the checkpoint — the two can never
+ * diverge.
+ *
+ * @module core/event-log
+ */
+import type { BatchOperation, Storage } from '../storage/interface.ts';
+import { EMPTY_EVENT_HEAD, type EventHeadRecord, type WorkflowLogEntry } from './event-log-shared.ts';
+import { type VerifyResult } from './event-log-verify.ts';
+import type { WorkflowVersionTuple } from './workflow-version-tuple.ts';
+export { EMPTY_EVENT_HEAD };
+export type { EventHeadRecord, VerifyResult, WorkflowLogEntry };
+/**
+ * Result returned from `appendToBatch()`. Carries the updated head
+ * record AND the entry's wall-clock `timestamp` so post-commit
+ * listeners can emit the exact value written into the durable log
+ * without reaching for `Date.now()` a second time (which could
+ * produce a different value under a ticking `getNow` used in tests).
+ */
+export type AppendToBatchResult = {
+    readonly newHead: EventHeadRecord;
+    readonly timestamp: number;
+};
+/**
+ * Append-only, hash-chained event log scoped to a single workflow.
+ *
+ * All reads and writes go through the {@link Storage} interface so the log
+ * works with every backend (memory, SQLite, LMDB, Turso, IndexedDB).
+ */
+export declare class EventLog {
+    #private;
+    constructor(storage: Storage, workflowId: string);
+    /**
+     * Synchronously build the batch operations for a new event entry and push
+     * them onto `batchOperations`.
+     *
+     * This is the fast path used by the engine: no storage reads occur.
+     * The caller is responsible for supplying the current `head` (from an
+     * in-memory cache) and storing the returned `newHead` back into that cache
+     * after the batch is committed.
+     *
+     * @returns The updated head record to cache for the next call.
+     */
+    appendToBatch(event: {
+        type: string;
+        payload: unknown;
+    }, batchOperations: BatchOperation[], head: Readonly<EventHeadRecord>, versionTuple?: WorkflowVersionTuple): AppendToBatchResult;
+    /**
+     * Append a new event entry to the log.
+     *
+     * When `batchOperations` is supplied the writes are pushed onto it instead
+     * of being flushed immediately, enabling the caller to include them in the
+     * same atomic `storage.batch()` call as a checkpoint write.
+     *
+     * @returns The new sequence number, the hash of the appended entry, and the
+     *   updated head record that the caller should cache for the next append.
+     */
+    append(event: {
+        type: string;
+        payload: unknown;
+    }, batchOperations?: BatchOperation[], versionTuple?: WorkflowVersionTuple): Promise<{
+        sequence: number;
+        hash: string;
+        newHead: EventHeadRecord;
+    }>;
+    /**
+     * Iterate over all log entries in ascending sequence order.
+     *
+     * @param options.fromSequence  Start at this sequence number (inclusive). Defaults to 0.
+     */
+    scan(options?: {
+        fromSequence?: number;
+    }): AsyncIterable<WorkflowLogEntry>;
+    /**
+     * Return all entries up to and including `toStep`.
+     *
+     * "Step" here is the `sequence` field. Entries with `sequence > toStep`
+     * are excluded, so callers can reconstruct state as it was at any point.
+     */
+    replay(toStep: number): Promise<WorkflowLogEntry[]>;
+    /**
+     * Walk the log and verify hash-chain integrity, tolerating concurrent
+     * compaction and a compaction watermark. Delegates to {@link verifyEventLog};
+     * see that function for the full watermark-seeding, retry, and corruption
+     * semantics.
+     */
+    verify(): Promise<VerifyResult>;
+    /**
+     * Read the current head record from storage and return it.
+     *
+     * This is the async counterpart to the synchronous cache lookup in the
+     * engine. Call it when resuming a workflow after an engine restart so that
+     * the in-memory `#eventLogHeads` cache can be re-seeded before the next
+     * {@link appendToBatch} call.
+     *
+     * Returns `EMPTY_EVENT_HEAD` (sequence -1) when no head record exists
+     * (i.e., the log is empty or this workflow has never written an event).
+     */
+    loadHead(): Promise<EventHeadRecord>;
+}

package/dist/core/event-log.js

@@ -0,0 +1,81 @@
+import { KEYS } from "../storage/interface.js";
+import { decode, encode } from "./codec.js";
+import {
+  EMPTY_EVENT_HEAD,
+  hashBytes,
+  isWorkflowLogEntry,
+  readEventHead
+} from "./event-log-shared.js";
+import { verifyEventLog } from "./event-log-verify.js";
+
+export { EMPTY_EVENT_HEAD };
+
+export class EventLog {
+  #storage;
+  #workflowId;
+  constructor(storage, workflowId) {
+    this.#storage = storage;
+    this.#workflowId = workflowId;
+  }
+  appendToBatch(event, batchOperations, head, versionTuple) {
+    const { entry, encoded, newHead } = this.#buildEntry(event, head, versionTuple);
+    batchOperations.push({ type: "put", key: KEYS.event(this.#workflowId, newHead.sequence), value: encoded }, { type: "put", key: KEYS.eventHead(this.#workflowId), value: encode(newHead) });
+    return { newHead, timestamp: entry.timestamp };
+  }
+  async append(event, batchOperations, versionTuple) {
+    const head = await this.#readHead(), { encoded, hash, newHead } = this.#buildEntry(event, head, versionTuple), entryPut = {
+      type: "put",
+      key: KEYS.event(this.#workflowId, newHead.sequence),
+      value: encoded
+    }, headPut = {
+      type: "put",
+      key: KEYS.eventHead(this.#workflowId),
+      value: encode(newHead)
+    };
+    if (batchOperations)
+      batchOperations.push(entryPut, headPut);
+    else
+      await this.#storage.batch([entryPut, headPut]);
+    return { sequence: newHead.sequence, hash, newHead };
+  }
+  async* scan(options) {
+    const from = options?.fromSequence ?? 0, prefix = KEYS.eventPrefix(this.#workflowId), gte = KEYS.event(this.#workflowId, from);
+    for await (const [, bytes] of this.#storage.scan(prefix, { gte })) {
+      const decoded = decode(bytes);
+      if (isWorkflowLogEntry(decoded))
+        yield decoded;
+    }
+  }
+  async replay(toStep) {
+    const results = [];
+    for await (const entry of this.scan()) {
+      if (entry.sequence > toStep)
+        break;
+      results.push(entry);
+    }
+    return results;
+  }
+  async verify() {
+    return verifyEventLog(this.#storage, this.#workflowId);
+  }
+  async loadHead() {
+    return this.#readHead();
+  }
+  #buildEntry(event, head, versionTuple) {
+    const sequence = head.sequence + 1, prevHash = head.lastHash, entry = {
+      type: event.type,
+      workflowId: this.#workflowId,
+      sequence,
+      prevHash,
+      payload: event.payload,
+      timestamp: Date.now()
+    };
+    if (versionTuple !== void 0)
+      entry.versionTuple = versionTuple;
+    const encoded = encode(entry), hash = hashBytes(encoded);
+    return { entry, encoded, hash, newHead: { sequence, lastHash: hash } };
+  }
+  async#readHead() {
+    return readEventHead(this.#storage, this.#workflowId);
+  }
+}