foottrace 1.0.2 → 1.1.0

package/dist/esm/lib/memory/honesty.d.ts

@@ -23,10 +23,11 @@
  *     alias of `foottrace` that is a union of string literals: each one is inside the
  *     registry or is named, with its reason, as not an honesty vocabulary.
  *
- * NO OBJECT GAINS A FIELD from being registered. Three signals carry no code of their own — a
- * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`) and
- * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) — and a `truncated: { byDepth, byNodes }`
- * field means `'truncated'`; they are registered so a reader explains them from the same place.
+ * NO OBJECT GAINS A FIELD from being registered. Four signals carry no code of their own — a
+ * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`),
+ * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) and an entry of `StoredRecord.unread`
+ * (`'unread-entry'`, 1.1.0) — and a `truncated: { byDepth, byNodes }` field means `'truncated'`; they
+ * are registered so a reader explains them from the same place.
  *
  * NOT HERE: the two strings a redaction leaves where a value was. The engine writes those on every
  * redacted run; the log's lives in its own leaf, `memory/placeholders.ts` (the scope channel's with
@@ -75,6 +76,7 @@ export declare const HONESTY_CODES: Readonly<{
     'initial+log': string;
     'log-only': string;
     'log-gap': string;
+    'unread-entry': string;
     'incomplete-sources': string;
     redacted: string;
     deleted: string;

package/dist/esm/lib/memory/honesty.js

@@ -23,10 +23,11 @@
  *     alias of `foottrace` that is a union of string literals: each one is inside the
  *     registry or is named, with its reason, as not an honesty vocabulary.
  *
- * NO OBJECT GAINS A FIELD from being registered. Three signals carry no code of their own — a
- * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`) and
- * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) — and a `truncated: { byDepth, byNodes }`
- * field means `'truncated'`; they are registered so a reader explains them from the same place.
+ * NO OBJECT GAINS A FIELD from being registered. Four signals carry no code of their own — a
+ * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`),
+ * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) and an entry of `StoredRecord.unread`
+ * (`'unread-entry'`, 1.1.0) — and a `truncated: { byDepth, byNodes }` field means `'truncated'`; they
+ * are registered so a reader explains them from the same place.
  *
  * NOT HERE: the two strings a redaction leaves where a value was. The engine writes those on every
  * redacted run; the log's lives in its own leaf, `memory/placeholders.ts` (the scope channel's with
@@ -81,6 +82,8 @@ export const HONESTY_CODES = /* @__PURE__ */ Object.freeze({
     'log-only': 'No initialState travelled with this log (a snapshot stored before 9.17, a redacted snapshot or a hand-built log), so the fold started from an empty object: a key seeded before the run is whole only once a commit since wrote its whole value, and until then it holds just what its merges, appends and nested writes added, or nothing.',
     // ── a row of a stored log that is not a commit bundle — `LogGap` ──────────
     'log-gap': 'A row of the stored log could not be read as a commit bundle, so it keeps its index but contributes no state, and any fold that crosses it is missing whatever that row wrote.',
+    // ── an entry a sink stored that no log could hold — `StoredRecord.unread` (1.1.0) ─
+    'unread-entry': "An entry a sink stored was not read into any log (it could not be read as an opened, commit, note or closed entry, it lay past one of the reader's limits, or another entry holds its place), so whatever it said (a base, a commit, a note or how the log ended) is not in the record read back.",
     // ── untracked reads a stage also consumed — `CausalNode.incompleteSources` ─
     'incomplete-sources': 'The stage also consumed read paths that bypass read tracking (args, env or an unshadowed silent read), so a slice through it may be incomplete: those reads produce no read-to-write edge to follow.',
     // ── values scrubbed at write time — `FoldedState.redacted` / `redactedPaths`, a value basis ─

package/dist/esm/lib/memory/sink.d.ts

@@ -0,0 +1,148 @@
+/**
+ * sink.ts — the record's sink port: where a log's entries go AS THEY LAND, so a run that never ends
+ * still leaves its record behind.
+ *
+ * A log that is given a sink (`new EventLog(base, { sink, address })`) hands it four kinds of entry,
+ * each stamped with the log's address and the time it was written (`at`, epoch ms):
+ *
+ *   - `opened` — once, from the constructor: the fold base (`initialState`, the sink's own copy);
+ *   - `commit` — per `record()`, AFTER the bundle is frozen: the log's own bundle, as served;
+ *   - `note`   — per `note(kind, data)`: something the writer wants kept beside the log, as it happens;
+ *   - `closed` — per `close(outcome)`: how the log ended, and how many commits it held then (`commits`).
+ *
+ * These are RECORD facts. What the writer means by them rides `meta` (on `opened` / `closed`) and a
+ * note's `kind` and `data`: opaque here — stored and handed back, never read or interpreted. Nothing in
+ * this file names an engine.
+ *
+ * THE STORED FORM. A sink stores each entry as a {@link RecordEntry}: the method's entry plus the
+ * method's name as `kind`. A note's own kind cannot also be called `kind`, so it is stored as `note`.
+ * `memorySink` is the reference adapter; `readStoredRecord` (`foottrace`) reads the entries back.
+ *
+ * @example
+ * ```typescript
+ * import { EventLog, memorySink } from 'foottrace/write';
+ * import { readStoredRecord } from 'foottrace';
+ *
+ * const sink = memorySink();
+ * const log = new EventLog({ count: 0 }, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.note('attempt', { attempt: 1, outcome: 'failed' });
+ * // … the process dies here: no `closed` entry …
+ * readStoredRecord(sink.entries).root('run-1')?.complete; // false — and its note is still there
+ * ```
+ */
+import type { LogAddress } from './eventPosition.js';
+import type { CommitBundle } from './types.js';
+/**
+ * What a writer puts beside the record — on a log's `opened` / `closed` entry, or as a note's data.
+ * A plain object that survives `structuredClone`; opaque to foottrace: stored and returned, never read.
+ */
+export type Meta = Readonly<Record<string, unknown>>;
+/** How a log's writer said it ended. A pause ends this log; it is not a failure. */
+export type LogOutcome = 'ok' | 'failed' | 'paused';
+/** The outcomes a `closed` entry may carry, in one place for the writer's and the reader's checks. */
+export declare const LOG_OUTCOMES: readonly LogOutcome[];
+/**
+ * One stored entry: what a sink keeps per call, discriminated by `kind` (the method that received it).
+ * A note's own kind is stored as `note`.
+ */
+export type RecordEntry = {
+    readonly kind: 'opened';
+    readonly address: LogAddress;
+    readonly at: number;
+    /** The fold base — the state before the log's first commit. */
+    readonly initialState: Record<string, unknown>;
+    readonly meta?: Meta;
+} | {
+    readonly kind: 'commit';
+    readonly address: LogAddress;
+    readonly at: number;
+    /** The log's own bundle, frozen, its position stamped as `idx`. */
+    readonly bundle: CommitBundle;
+} | {
+    readonly kind: 'note';
+    readonly address: LogAddress;
+    readonly at: number;
+    /** The note's own kind, as the writer named it (`note('attempt', …)` → `'attempt'`). */
+    readonly note: string;
+    readonly data: Meta;
+} | {
+    readonly kind: 'closed';
+    readonly address: LogAddress;
+    readonly at: number;
+    readonly outcome: LogOutcome;
+    /** The log's length when it closed — how many commits the stored log must hold to be whole. */
+    readonly commits: number;
+    readonly meta?: Meta;
+};
+/**
+ * Where a log's entries go as they land — the port an adapter implements (memory, a file, S3, a table).
+ *
+ * Every method is called synchronously from the writer; an adapter that writes somewhere slow queues
+ * the entry and drains in `flush`. A method may throw, or return a promise that rejects: the log
+ * counts it (`EventLog · sinkFailures`), reports it to `onFailure`, and goes on — a failing sink never
+ * stops the writer. The entries an adapter is handed are its to keep: the bundle is frozen and shared
+ * with the log, everything else is the adapter's own copy.
+ */
+export interface RecordSink {
+    /** A log opened at `address` with its fold base. Called once, from the log's constructor. */
+    opened(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly initialState: Record<string, unknown>;
+        readonly meta?: Meta;
+    }): void;
+    /** A bundle landed in the log at `address` (its position is `bundle.idx`). */
+    commit(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly bundle: CommitBundle;
+    }): void;
+    /** The writer noted something beside the log — `kind` and `data` are opaque. */
+    note(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly kind: string;
+        readonly data: Meta;
+    }): void;
+    /** The log at `address` closed with `outcome`, holding `commits` bundles. */
+    closed(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly outcome: LogOutcome;
+        readonly commits: number;
+        readonly meta?: Meta;
+    }): void;
+    /** Drain whatever the adapter queued. The log never calls it; whoever owns the sink does. */
+    flush?(): Promise<void>;
+    /** Told of every entry this sink did not take — the entry and what went wrong. A throw here is ignored. */
+    onFailure?(failure: {
+        readonly entry: RecordEntry;
+        readonly error: unknown;
+    }): void;
+}
+/** A plain object — not null, not an array, not a primitive. */
+export declare function isEntryObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Hand `entry` to the sink's method for its kind, as that method's entry; returns what the method
+ * returned (a promise from an async adapter). Throws whatever the method throws — the log catches.
+ */
+export declare function sendEntry(sink: RecordSink, entry: RecordEntry): unknown;
+/**
+ * A sink that keeps every entry in memory, in arrival order — the reference adapter: what any adapter
+ * must give back for `readStoredRecord` to read the same record. `entries` is a new array on each read.
+ * What it keeps is frozen as far as freezing reaches — the base, `meta` and a note's `data` are the
+ * copies a log hands it, and the bundle is already frozen — so no reader can rewrite its containers. A
+ * Date's time, a Map's or Set's entries and a buffer's bytes are not sealed by freezing (`deepFreeze`'s
+ * stated limit). A caller that hands it objects directly hands them over: they are frozen in place.
+ *
+ * @example
+ * ```typescript
+ * const sink = memorySink();
+ * const log = new EventLog({}, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.close('ok');
+ * sink.entries.map((e) => e.kind); // ['opened', 'closed']
+ * ```
+ */
+export declare function memorySink(): RecordSink & {
+    readonly entries: readonly RecordEntry[];
+};

package/dist/esm/lib/memory/sink.js

@@ -0,0 +1,92 @@
+/**
+ * sink.ts — the record's sink port: where a log's entries go AS THEY LAND, so a run that never ends
+ * still leaves its record behind.
+ *
+ * A log that is given a sink (`new EventLog(base, { sink, address })`) hands it four kinds of entry,
+ * each stamped with the log's address and the time it was written (`at`, epoch ms):
+ *
+ *   - `opened` — once, from the constructor: the fold base (`initialState`, the sink's own copy);
+ *   - `commit` — per `record()`, AFTER the bundle is frozen: the log's own bundle, as served;
+ *   - `note`   — per `note(kind, data)`: something the writer wants kept beside the log, as it happens;
+ *   - `closed` — per `close(outcome)`: how the log ended, and how many commits it held then (`commits`).
+ *
+ * These are RECORD facts. What the writer means by them rides `meta` (on `opened` / `closed`) and a
+ * note's `kind` and `data`: opaque here — stored and handed back, never read or interpreted. Nothing in
+ * this file names an engine.
+ *
+ * THE STORED FORM. A sink stores each entry as a {@link RecordEntry}: the method's entry plus the
+ * method's name as `kind`. A note's own kind cannot also be called `kind`, so it is stored as `note`.
+ * `memorySink` is the reference adapter; `readStoredRecord` (`foottrace`) reads the entries back.
+ *
+ * @example
+ * ```typescript
+ * import { EventLog, memorySink } from 'foottrace/write';
+ * import { readStoredRecord } from 'foottrace';
+ *
+ * const sink = memorySink();
+ * const log = new EventLog({ count: 0 }, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.note('attempt', { attempt: 1, outcome: 'failed' });
+ * // … the process dies here: no `closed` entry …
+ * readStoredRecord(sink.entries).root('run-1')?.complete; // false — and its note is still there
+ * ```
+ */
+import { deepFreeze } from '../capture/freeze.js';
+/** The outcomes a `closed` entry may carry, in one place for the writer's and the reader's checks. */
+export const LOG_OUTCOMES = /* @__PURE__ */ Object.freeze(['ok', 'failed', 'paused']);
+/** A plain object — not null, not an array, not a primitive. */
+export function isEntryObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `{ meta }` when there is one, `{}` otherwise — an absent field stays absent. */
+function withMeta(meta) {
+    return meta === undefined ? {} : { meta };
+}
+/**
+ * Hand `entry` to the sink's method for its kind, as that method's entry; returns what the method
+ * returned (a promise from an async adapter). Throws whatever the method throws — the log catches.
+ */
+export function sendEntry(sink, entry) {
+    const { address, at } = entry;
+    switch (entry.kind) {
+        case 'opened':
+            return sink.opened({ address, at, initialState: entry.initialState, ...withMeta(entry.meta) });
+        case 'commit':
+            return sink.commit({ address, at, bundle: entry.bundle });
+        case 'note':
+            return sink.note({ address, at, kind: entry.note, data: entry.data });
+        case 'closed':
+            return sink.closed({ address, at, outcome: entry.outcome, commits: entry.commits, ...withMeta(entry.meta) });
+    }
+}
+/**
+ * A sink that keeps every entry in memory, in arrival order — the reference adapter: what any adapter
+ * must give back for `readStoredRecord` to read the same record. `entries` is a new array on each read.
+ * What it keeps is frozen as far as freezing reaches — the base, `meta` and a note's `data` are the
+ * copies a log hands it, and the bundle is already frozen — so no reader can rewrite its containers. A
+ * Date's time, a Map's or Set's entries and a buffer's bytes are not sealed by freezing (`deepFreeze`'s
+ * stated limit). A caller that hands it objects directly hands them over: they are frozen in place.
+ *
+ * @example
+ * ```typescript
+ * const sink = memorySink();
+ * const log = new EventLog({}, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.close('ok');
+ * sink.entries.map((e) => e.kind); // ['opened', 'closed']
+ * ```
+ */
+export function memorySink() {
+    const stored = [];
+    const keep = (entry) => {
+        stored.push(deepFreeze(entry));
+    };
+    return {
+        get entries() {
+            return stored.slice();
+        },
+        opened: ({ address, at, initialState, meta }) => keep({ kind: 'opened', address, at, initialState, ...withMeta(meta) }),
+        commit: ({ address, at, bundle }) => keep({ kind: 'commit', address, at, bundle }),
+        note: ({ address, at, kind, data }) => keep({ kind: 'note', address, at, note: kind, data }),
+        closed: ({ address, at, outcome, commits, meta }) => keep({ kind: 'closed', address, at, outcome, commits, ...withMeta(meta) }),
+        flush: () => Promise.resolve(),
+    };
+}

package/dist/esm/lib/time-travel/bundles.d.ts

@@ -19,6 +19,8 @@ import type { CommitBundle, ExecutionTree } from '../memory/types.js';
 import type { LogGap } from './types.js';
 /** A plain object — not null, not an array, not a primitive. */
 export declare function isPlainish(value: unknown): value is Record<string, unknown>;
+/** A row every reader refuses with `reason` — a gap that keeps its index. */
+export declare function absentRow(reason: string): object;
 /**
  * Read a source's `executionTree` as an {@link ExecutionTree}, or as absent.
  *
@@ -41,6 +43,10 @@ export declare function readTree(value: unknown): ExecutionTree | undefined;
  *   `changedSince` reads its paths), so a row without one is not a bundle the
  *   fold can survive — it is the crash a gap exists to prevent. `CommitBundle`
  *   declares it required, so no live log is affected.
+ * - Each trace entry needs a known verb and a string `path`. Readers use
+ *   string path operations; accepting a number can silently lose a causal
+ *   writer in a short log and crash the indexed lookup in a longer one.
+ *   Empty strings and historical path spellings remain valid strings.
  * - `updates` / `overwrite`, when present, must be plain objects. They are
  *   read only AT THE PATHS THE TRACE NAMES, so an absent one is harmless and
  *   is tolerated, exactly as the fold tolerates an absent `redactedPaths`.

package/dist/esm/lib/time-travel/bundles.js

@@ -39,6 +39,19 @@ const GAP_BUNDLE = Object.freeze({
 export function isPlainish(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Rows that hold an index for a commit the record does not have (1.1.0) — what a STORED log could not
+ * supply at a position: no readable commit entry (`storedRecord.ts`). Each
+ * carries the reason every reader then reports for its index, so the fold, the cursor and the stored
+ * log say the same thing about it. Kept by identity (a JSON copy of one is an ordinary unreadable row).
+ */
+const ABSENT_ROWS = new WeakMap();
+/** A row every reader refuses with `reason` — a gap that keeps its index. */
+export function absentRow(reason) {
+    const row = Object.freeze({});
+    ABSENT_ROWS.set(row, reason);
+    return row;
+}
 /**
  * Read a source's `executionTree` as an {@link ExecutionTree}, or as absent.
  *
@@ -63,6 +76,10 @@ export function readTree(value) {
  *   `changedSince` reads its paths), so a row without one is not a bundle the
  *   fold can survive — it is the crash a gap exists to prevent. `CommitBundle`
  *   declares it required, so no live log is affected.
+ * - Each trace entry needs a known verb and a string `path`. Readers use
+ *   string path operations; accepting a number can silently lose a causal
+ *   writer in a short log and crash the indexed lookup in a longer one.
+ *   Empty strings and historical path spellings remain valid strings.
  * - `updates` / `overwrite`, when present, must be plain objects. They are
  *   read only AT THE PATHS THE TRACE NAMES, so an absent one is harmless and
  *   is tolerated, exactly as the fold tolerates an absent `redactedPaths`.
@@ -72,6 +89,9 @@ export function readTree(value) {
  * compatibility break dressed up as validation.
  */
 export function bundleRefusal(row) {
+    const absent = typeof row === 'object' && row !== null ? ABSENT_ROWS.get(row) : undefined;
+    if (absent !== undefined)
+        return absent;
     if (!isPlainish(row)) {
         return `not an object (${row === null ? 'null' : Array.isArray(row) ? 'array' : typeof row})`;
     }
@@ -95,6 +115,11 @@ export function bundleRefusal(row) {
         if (!isVerb(verb)) {
             return `trace[${i}].verb is ${verb === undefined ? 'missing' : JSON.stringify(verb)}, not ${VERBS.join(' | ')}`;
         }
+        const path = isPlainish(entry) ? entry.path : undefined;
+        if (typeof path !== 'string') {
+            const kind = path === undefined ? 'missing' : path === null ? 'null' : Array.isArray(path) ? 'an array' : `a ${typeof path}`;
+            return `trace[${i}].path is ${kind}, not a string`;
+        }
     }
     return undefined;
 }

package/dist/esm/lib/time-travel/commitStops.js

@@ -10,6 +10,7 @@
  */
 import { isExecutionKey, isWithinSubflow, parseRuntimeStageId, stageIdOf } from '../ids/runtimeStageId.js';
 import { buildCommitIndex, inferLegacyPhases, recordsPhases } from '../memory/commitLogUtils.js';
+import { isPlainish } from './bundles.js';
 /**
  * Every `runtimeStageId` in the execution tree that the engine marked as a
  * subflow mount. Authoritative, as is a bundle's recorded `phase: 'exit'`
@@ -89,7 +90,7 @@ export function commitStops(commitLog, executionTree, subflowResults) {
     // the MOUNT's commit, made before any of them ran. It gets no stop of its
     // own; it belongs to the `'start'` bookend, which is where a reader looks
     // for "the input this chart began with" anyway. See {@link seedCommits}.
-    const seeds = seedCommits(commitLog, executionTree);
+    const seeds = seedCommits(commitLog, executionTree, subflowResults);
     const firsts = [];
     for (const [id, i] of buildCommitIndex(commitLog))
         if (id && i >= seeds)
@@ -159,6 +160,22 @@ function phasesOf(commitLog, haveTree) {
         return commitLog.map((bundle) => bundle.phase);
     return haveTree ? [] : inferLegacyPhases(commitLog);
 }
+/**
+ * True when the results map's entry for `head` IS this log — its history opens with this very bundle.
+ * The log is then that mount's own, and its head run is the mount's seed (R13: a seed carries its
+ * mount's runtimeStageId). This is what a TREE-LESS cursor over a mount log reads in place of the
+ * tree's root — a stored log read back by `readStoredRecord`, or a log whose stage after the seed was
+ * lost — so the seed opens `start` instead of standing as a stop (marked as its own mount).
+ */
+function opensOwnMount(subflowResults, head, first) {
+    if (!isPlainish(subflowResults))
+        return false;
+    const result = subflowResults[head];
+    if (!isPlainish(result) || !isPlainish(result.treeContext))
+        return false;
+    const history = result.treeContext.history;
+    return Array.isArray(history) && history[0] === first;
+}
 /** `commitStops` as a {@link TimeTravelStrategy} — the default for `timeTravel`. */
 export const commitStopsStrategy = { stopsFor: commitStops };
 /**
@@ -179,7 +196,7 @@ export const commitStopsStrategy = { stopsFor: commitStops };
  * whose id carries the same subflow path. Without a tree such a log reads as
  * one stop.
  */
-function seedCommits(commitLog, executionTree) {
+function seedCommits(commitLog, executionTree, subflowResults) {
     const head = commitLog[0]?.runtimeStageId;
     if (head === undefined)
         return 0;
@@ -192,6 +209,8 @@ function seedCommits(commitLog, executionTree) {
     let next = 1;
     while (next < commitLog.length && commitLog[next].runtimeStageId === head)
         next++;
+    if (executionTree === undefined && opensOwnMount(subflowResults, head, commitLog[0]))
+        return next;
     const address = stageIdOf(head);
     if (next >= commitLog.length) {
         const rootId = executionTree?.id;

package/dist/esm/lib/time-travel/index.d.ts

@@ -17,6 +17,8 @@ export { filterStops, splitAxis } from './axis.js';
 export { isCommitBundle } from './bundles.js';
 export { commitStops, commitStopsStrategy } from './commitStops.js';
 export { stateAt } from './stateAt.js';
+export type { StoredLog, StoredNote, StoredRecord, StoredRecordLimits } from './storedRecord.js';
+export { readStoredRecord } from './storedRecord.js';
 export { tagStops } from './tagStops.js';
 export { timeTravel } from './timeTravel.js';
 export type { AxisRefusal, AxisSplit, BookendedAxis, FoldBasis, FoldedState, FoldSource, LogGap, Mark, Move, MoveRefusal, Stop, StopKind, TimeTravel, TimeTravelOptions, TimeTravelSource, TimeTravelStrategy, } from './types.js';

package/dist/esm/lib/time-travel/index.js

@@ -16,5 +16,6 @@ export { filterStops, splitAxis } from './axis.js';
 export { isCommitBundle } from './bundles.js';
 export { commitStops, commitStopsStrategy } from './commitStops.js';
 export { stateAt } from './stateAt.js';
+export { readStoredRecord } from './storedRecord.js';
 export { tagStops } from './tagStops.js';
 export { timeTravel } from './timeTravel.js';

package/dist/esm/lib/time-travel/storedRecord.d.ts

@@ -0,0 +1,195 @@
+/**
+ * storedRecord.ts — reading back what a sink stored (1.1.0).
+ *
+ * WHY THIS FILE EXISTS. A log that writes to a `RecordSink` (`foottrace/write`) leaves its record in
+ * storage AS IT LANDS: an `opened` entry with the fold base, one `commit` entry per bundle, `note`
+ * entries, and a `closed` entry with how the log ended. A run that is killed never writes its
+ * `closed` entry. This reader turns stored entries back into logs a person or a model can read —
+ * and says, before any fold, which of them never finished (`complete: false`) and what each one is
+ * missing.
+ *
+ * WHAT IT READS. Entries come back from storage unvalidated (a parsed file, a table scan) — untrusted
+ * input — so it takes `Iterable<unknown>` and checks each one where it is read: the 9.18.0 law for
+ * stored recordings, no cast at the seam. An entry it does not read into a log is never dropped in
+ * silence: it is listed in `unread` with its position and the reason.
+ *
+ * THE LAWS IT KEEPS.
+ *   1. Grouped by address. Every entry names its log (`logRunId` + `drillPath`); entries of many
+ *      logs may arrive interleaved, and each log keeps its own entries in arrival order.
+ *   2. A commit sits at its own index. `EventLog · record` stamps `bundle.idx` before the sink sees
+ *      the bundle, so a commit lost on the way (a sink that failed once — the writer goes on) leaves a
+ *      GAP at its index instead of shifting every commit after it; so does a bundle that is not a
+ *      readable bundle. Every gap keeps its index, and the fold reports it (`skipped`) with the same
+ *      reason the stored log gives (`gaps`). One place, one entry: the first READABLE commit entry
+ *      for an index stands (a torn first delivery yields to a readable redelivery), the first
+ *      `opened` stands, and every other entry for a place already held — a redelivery or a conflict,
+ *      the very same object included — is listed in `unread`. Payloads are never compared, so no
+ *      stored value is walked.
+ *   3. Complete means the writer finished — and the reader read it all. A log is `complete` when a
+ *      `closed` entry covers every stored commit (`closed.commits` is past the last index); the
+ *      covering close with the largest `commits` gives the `outcome` and the length, so no loss an
+ *      earlier close showed can hide behind a later one. A log that was closed and then went on (a
+ *      later commit) is not complete until it is closed again. A closed log whose store lost commits
+ *      is complete AND has gaps (`closed.commits` makes even a lost LAST commit a gap). A log a limit
+ *      cut, and every log once reading stopped at the `entries` limit, is not complete: what the
+ *      reader did not read could have gone on.
+ *   4. Opaque stays opaque. `meta` and a note's `kind` and `data` are handed back as stored, never
+ *      read or merged.
+ *   5. Read, never touched. Nothing here copies, freezes or edits the entries it is given — not the
+ *      base, not `meta`: the stored log hands back their own values.
+ *   6. Bounded work (see {@link StoredRecordLimits}). Every walk is a loop over the input, never a
+ *      recursion, and never through an input's own iterator except the input itself; the work per
+ *      entry is bounded by the address limits; the rows a log holds are its stored commits plus gaps
+ *      from ONE budget for the whole record, spent on the logs that need the fewest gaps first (so a
+ *      corrupt log asking for the most is the one cut); and reading stops after `entries` entries. Whatever a
+ *      limit stops is listed in `unread` by name — never a hang, never a silent cut.
+ *
+ * Entries are data. An entry whose fields throw while it is checked (a getter, a revoked proxy) is
+ * listed in `unread`, and what the reader computes with — the kind, a commit's index and bundle, a
+ * close's length — is taken once, as checked. An in-memory accessor that changes or throws on a later
+ * read is out of contract, as everywhere in the record (docs/extraction.md): parsed JSON and structured
+ * clones carry none.
+ *
+ * DAG position: memory ← time-travel; this file is a reader beside `timeTravel` and imports only
+ * record files.
+ */
+import type { LogAddress } from '../memory/eventPosition.js';
+import { type LogOutcome, type Meta, type RecordEntry } from '../memory/sink.js';
+import type { CommitBundle } from '../memory/types.js';
+import type { LogGap, TimeTravelSource } from './types.js';
+/** A note the writer kept beside a log (`EventLog · note`), as stored. */
+export interface StoredNote {
+    /** The note's kind, as the writer named it. */
+    readonly kind: string;
+    /** When it was written (epoch ms). */
+    readonly at: number;
+    /** What the writer put in it — opaque. */
+    readonly data: Meta;
+}
+/** One log read back from a sink's entries. */
+export interface StoredLog {
+    /** Which log this is: the run leg that owned it and the mounts it sits under (root: `drillPath: []`). */
+    readonly address: LogAddress;
+    /** The fold base the `opened` entry carried; ABSENT when no readable `opened` entry was stored. */
+    readonly initialState?: Record<string, unknown>;
+    /**
+     * The bundles, each at its own index (`bundle.idx`). An index with no readable bundle holds an empty
+     * stand-in (it belongs to no stage and carries nothing) and is named in {@link gaps} — check `gaps`
+     * before a causal query, which takes the bundles as they are; fold {@link source}, not this, so the
+     * fold reports them.
+     */
+    readonly commitLog: readonly CommitBundle[];
+    /** Every index of {@link commitLog} that holds no readable bundle, with why — empty when the log is whole. */
+    readonly gaps: readonly LogGap[];
+    /**
+     * The notes, in arrival order. A store that delivers an entry twice as two copies repeats its note:
+     * payloads are never compared (the very same object twice is listed in `unread` instead).
+     */
+    readonly notes: readonly StoredNote[];
+    /**
+     * `true` when a `closed` entry covers every stored commit and the reader read the log whole: the
+     * writer said it ended. `false` for a log that never closed — a crashed run, or one still going —
+     * for one that went on after its last close, and for one the reader did not read whole (a limit
+     * cut it, or reading stopped at the `entries` limit — see `StoredRecord.unread`).
+     */
+    readonly complete: boolean;
+    /** How the covering `closed` entry said the log ended; ABSENT while the log is not complete. */
+    readonly outcome?: LogOutcome;
+    /**
+     * What the writer put on the `opened` entry and on the covering `closed` entry (present only while
+     * the log is complete) — opaque, never merged.
+     */
+    readonly meta: {
+        readonly opened?: Meta;
+        readonly closed?: Meta;
+    };
+    /**
+     * The entries this log was read from, in arrival order, as stored — the evidence the rest is read
+     * from (each entry's `at`, every `closed` entry). An entry listed in `StoredRecord.unread` is not
+     * here. A commit's bundle is the stored row: {@link gaps} names one that is not a readable bundle.
+     */
+    readonly entries: readonly RecordEntry[];
+    /**
+     * The log as `timeTravel` and `stateAt` read it: `{ commitLog, initialState?, subflowResults? }`. A
+     * gap is a row the fold refuses with the same reason {@link gaps} gives (`skipped`), so a fold that
+     * crosses one says so. `subflowResults` holds every stored mount log of the run leg — this one too,
+     * when it is a mount — keyed by each mount's runtimeStageId (the last segment of its `drillPath`):
+     * one flat map per leg, as a live snapshot's, so the cursor marks those stops as mounts and
+     * `drill(mountRuntimeStageId)` opens the mount's own stored log. A mount log's head commit stamped
+     * with its own mount id is its seed (it opens `start`, as on a live cursor). The same object on
+     * every call.
+     */
+    source(): TimeTravelSource;
+}
+/** Every log a sink's entries hold, and every entry no log holds. */
+export interface StoredRecord {
+    /** Every log, keyed by its address as a JSON array — `["<logRunId>", ...drillPath]` — in first-arrival order. */
+    readonly logs: ReadonlyMap<string, StoredLog>;
+    /** The root log of the run leg `logRunId` (`drillPath: []`), or `undefined` when none was stored. */
+    root(logRunId: string): StoredLog | undefined;
+    /** The log at `address`, or `undefined` when none was stored. */
+    log(address: LogAddress): StoredLog | undefined;
+    /**
+     * Entries not read into any log, by position in the input, with the reason: an entry that could not
+     * be read, one past a limit of the reader, or one for a place another entry holds (a second `opened`,
+     * a second commit for an index, the same entry again). In input order; empty when every entry was
+     * read. A commit that could not be read at all, or that a limit cut, leaves no row: its index is a
+     * gap only when a later stored commit or a close reaches past it.
+     */
+    readonly unread: readonly {
+        readonly index: number;
+        readonly reason: string;
+    }[];
+}
+/**
+ * The reader's limits — what bounds its work on untrusted input. Each defaults to the value below; a
+ * caller that reads larger records raises it. Whatever a limit stops is listed in `unread` by name.
+ */
+export interface StoredRecordLimits {
+    /**
+     * Entries read; past it, reading stops, one `unread` item says so, and no log reads complete.
+     * Default 16,777,216 (2^24).
+     */
+    readonly entries?: number;
+    /**
+     * Gaps held across the WHOLE record — rows for commits the store does not have — spent on the logs
+     * that need the fewest first. A commit (or a close) that would need more is unread. Default
+     * 1,048,576 (2^20). The other rows a log holds are its stored commits.
+     */
+    readonly missingCommits?: number;
+    /** Segments in an address's `drillPath`. Default 1,024. */
+    readonly drillDepth?: number;
+    /** Characters in an address — its `logRunId` and `drillPath` segments together. Default 65,536. */
+    readonly addressLength?: number;
+}
+/** The defaults — internal to the package; documented on {@link StoredRecordLimits}. */
+export declare const DEFAULT_LIMITS: Required<StoredRecordLimits>;
+/**
+ * Read a sink's stored entries back into logs.
+ *
+ * Bounded on untrusted input: no recursion, no payload walk, work per entry bounded by the address
+ * limits, at most `limits.missingCommits` gap rows across the record, and at most `limits.entries`
+ * entries read — whatever a limit stops is listed in `unread` by name.
+ *
+ * @param entries What a `RecordSink` stored (`memorySink().entries`, or entries parsed back from a
+ *   file or a table), in the order they were written — typed `unknown` because stored entries come
+ *   back unvalidated; each is checked here.
+ * @param limits Raise a default to read a larger record ({@link StoredRecordLimits}).
+ * @returns Every log by address, the run-leg roots, and every entry not read into a log.
+ * @throws RangeError when a limit is not a non-negative integer or `Infinity`; TypeError when
+ *   `entries` is not iterable; whatever the input's own iterator throws. Never for an entry that is
+ *   data (parsed JSON, a structured clone).
+ *
+ * @example
+ * ```typescript
+ * import { readStoredRecord, stateAt, timeTravel } from 'foottrace';
+ *
+ * const stored = readStoredRecord(entries);       // e.g. JSON lines read back after a crash
+ * const run = stored.root('run-1');
+ * run?.complete;                                   // false — it never closed
+ * run?.notes.map((n) => n.kind);                   // ['attempt', 'attempt'] — kept as they happened
+ * timeTravel(run!.source()).last();                // the cursor over what landed
+ * stateAt(run!.source(), run!.commitLog.length - 1).skipped; // a lost commit, by index and reason
+ * ```
+ */
+export declare function readStoredRecord(entries: Iterable<unknown>, limits?: StoredRecordLimits): StoredRecord;