foottrace 1.0.3 → 1.2.0

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;