foottrace 1.0.3 → 1.1.0

package/dist/lib/time-travel/storedRecord.js

@@ -0,0 +1,498 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStoredRecord = exports.DEFAULT_LIMITS = void 0;
+const runtimeStageId_js_1 = require("../ids/runtimeStageId.js");
+const sink_js_1 = require("../memory/sink.js");
+const bundles_js_1 = require("./bundles.js");
+/** The defaults — internal to the package; documented on {@link StoredRecordLimits}. */
+exports.DEFAULT_LIMITS = Object.freeze({
+    entries: 2 ** 24,
+    missingCommits: 2 ** 20,
+    drillDepth: 1024,
+    addressLength: 65_536,
+});
+/** The limits to read with: each a non-negative integer or `Infinity`, or a `RangeError` naming it. */
+function limitsOf(given) {
+    if (given === undefined)
+        return exports.DEFAULT_LIMITS;
+    const limits = { ...exports.DEFAULT_LIMITS };
+    for (const name of Object.keys(exports.DEFAULT_LIMITS)) {
+        const value = given[name];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'number' || !(value === Infinity || (Number.isSafeInteger(value) && value >= 0))) {
+            throw new RangeError(`readStoredRecord: limits.${name} must be a non-negative integer or Infinity`);
+        }
+        limits[name] = value;
+    }
+    return limits;
+}
+/** What an index holds when the record has no readable commit for it. */
+const NO_COMMIT = (0, bundles_js_1.absentRow)('no readable commit entry for this index');
+const KINDS = ['opened', 'commit', 'note', 'closed'];
+/** A value as a reason names it: `missing`, `null`, `an array`, a short quoted string, a number, or `a <type>`. */
+function described(value) {
+    if (value === undefined)
+        return 'missing';
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value === 'string')
+        return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
+    if (typeof value === 'number')
+        return String(value);
+    return `a ${typeof value}`;
+}
+/** A position or a count: a non-negative safe integer. */
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * The address an entry names, as a fresh frozen copy — or why it is not one the reader takes. Bounded
+ * and iterator-free: the drill path's length is read once and checked before any segment; segments are
+ * read by index, checked and copied in one pass that stops at the first one past the length limit.
+ */
+function readAddress(address, limits) {
+    if (!(0, bundles_js_1.isPlainish)(address))
+        return `address is ${described(address)}, not a log address`;
+    const { logRunId, drillPath } = address;
+    if (typeof logRunId !== 'string')
+        return `address.logRunId is ${described(logRunId)}, not a string`;
+    if (!Array.isArray(drillPath))
+        return 'address.drillPath is not an array of strings';
+    const depth = drillPath.length;
+    if (depth > limits.drillDepth) {
+        return `address.drillPath has ${depth} segments, past the reader's limit of ${limits.drillDepth}`;
+    }
+    const tooLong = `address is longer than the reader's limit of ${limits.addressLength} characters`;
+    let length = logRunId.length;
+    if (length > limits.addressLength)
+        return tooLong;
+    const segments = [];
+    for (let i = 0; i < depth; i++) {
+        const segment = drillPath[i];
+        if (typeof segment !== 'string')
+            return 'address.drillPath is not an array of strings';
+        length += segment.length;
+        if (length > limits.addressLength)
+            return tooLong;
+        segments.push(segment);
+    }
+    return Object.freeze({ logRunId, drillPath: Object.freeze(segments) });
+}
+/** Why an optional `meta` field cannot be read, or `undefined`. */
+function metaRefusal(meta) {
+    return meta === undefined || (0, bundles_js_1.isPlainish)(meta) ? undefined : `meta is ${described(meta)}, not a plain object`;
+}
+/**
+ * What the reader keeps of the fields only one kind carries — each field it computes with read ONCE
+ * (a commit's bundle and index, a close's length) — or why they cannot be read.
+ */
+function payloadOf(row) {
+    switch (row.kind) {
+        case 'opened': {
+            if (!(0, bundles_js_1.isPlainish)(row.initialState))
+                return `initialState is ${described(row.initialState)}, not a plain object`;
+            return metaRefusal(row.meta) ?? { count: 0 };
+        }
+        case 'commit': {
+            const bundle = row.bundle;
+            if (!(0, bundles_js_1.isPlainish)(bundle))
+                return `bundle is ${described(bundle)}, not an object`;
+            const idx = bundle.idx;
+            return isCount(idx) ? { count: idx, bundle } : `bundle.idx is ${described(idx)}, not a commit index`;
+        }
+        case 'note':
+            if (typeof row.note !== 'string')
+                return `note is ${described(row.note)}, not a string`;
+            return (0, bundles_js_1.isPlainish)(row.data) ? { count: 0 } : `data is ${described(row.data)}, not a plain object`;
+        default: {
+            if (!sink_js_1.LOG_OUTCOMES.includes(row.outcome)) {
+                return `outcome is ${described(row.outcome)}, not ${sink_js_1.LOG_OUTCOMES.join(' | ')}`;
+            }
+            const commits = row.commits;
+            if (!isCount(commits))
+                return `commits is ${described(commits)}, not a commit count`;
+            return metaRefusal(row.meta) ?? { count: commits };
+        }
+    }
+}
+/** Read one stored entry, or say why not: what the reader keeps of it, and its address (the reader's own copy). */
+function readEntry(row, index, limits) {
+    if (!(0, bundles_js_1.isPlainish)(row))
+        return `not an object (${row === null ? 'null' : Array.isArray(row) ? 'array' : typeof row})`;
+    if (typeof row.kind !== 'string' || !KINDS.includes(row.kind)) {
+        return `kind is ${described(row.kind)}, not ${KINDS.join(' | ')}`;
+    }
+    const address = readAddress(row.address, limits);
+    if (typeof address === 'string')
+        return address;
+    if (typeof row.at !== 'number' || !Number.isFinite(row.at))
+        return `at is ${described(row.at)}, not a finite number`;
+    const payload = payloadOf(row);
+    if (typeof payload === 'string')
+        return payload;
+    const entry = row;
+    const kind = row.kind;
+    const { count, bundle } = payload;
+    if (bundle === undefined)
+        return { item: { entry, index, kind, count }, address };
+    const refusal = (0, bundles_js_1.bundleRefusal)(bundle);
+    const item = refusal === undefined ? { entry, index, kind, count, bundle } : { entry, index, kind, count, bundle, refusal };
+    return { item, address };
+}
+/** The key a log is filed under: its address as a JSON array — one spelling per address, whatever the ids hold. */
+function keyOf(logRunId, drillPath) {
+    return JSON.stringify([logRunId, ...drillPath]);
+}
+/** The close that covers `last`: the one with the largest `commits` past it (the latest of equals). */
+function coveringClose(closes, last) {
+    let best;
+    for (const close of closes) {
+        if (close.count > last && (best === undefined || close.count >= best.count))
+            best = close;
+    }
+    return best;
+}
+/** One place, one entry: the first readable commit for an index, the first opened. The rest is unread. */
+function groupOf(key, address, arrival, placed, unread) {
+    let opened;
+    const commits = new Map();
+    const closes = [];
+    const dropped = new Set();
+    for (const item of placed) {
+        if (item.kind === 'opened') {
+            if (opened === undefined)
+                opened = item;
+            else {
+                dropped.add(item);
+                unread.push({
+                    index: item.index,
+                    reason: `a second opened entry for this log — the one at ${opened.index} stands`,
+                });
+            }
+        }
+        else if (item.kind === 'commit') {
+            const held = commits.get(item.count);
+            if (held === undefined)
+                commits.set(item.count, item);
+            else if (held.refusal !== undefined && item.refusal === undefined) {
+                // A torn first delivery yields to a readable redelivery.
+                commits.set(item.count, item);
+                dropped.add(held);
+            }
+            else
+                dropped.add(item);
+        }
+        else if (item.kind === 'closed')
+            closes.push(item);
+    }
+    // Each commit entry not placed is named against the entry that holds its index in the end.
+    for (const item of dropped) {
+        if (item.kind !== 'commit')
+            continue;
+        const holder = commits.get(item.count);
+        const reason = item.refusal !== undefined && holder.refusal === undefined
+            ? `an unreadable commit entry for index ${item.count} — the readable one at ${holder.index} stands`
+            : `a second commit entry for index ${item.count} — the one at ${holder.index} stands`;
+        unread.push({ index: item.index, reason });
+    }
+    const present = [...commits.keys()].sort((a, b) => a - b);
+    const last = present.length > 0 ? present[present.length - 1] : -1;
+    const close = coveringClose(closes, last);
+    const wanted = close !== undefined ? close.count : last + 1;
+    return { key, address, arrival, placed, opened, commits, closes, dropped, present, wanted };
+}
+/**
+ * The longest prefix of a log the gap budget can hold: with `present` (the stored indices, ascending)
+ * below it, a length `n` needs `n - (stored indices below n)` gaps. Returns the longest `n ≤ wanted`
+ * whose gaps fit in `budget` — one pass over the stored indices.
+ */
+function lengthWithin(wanted, present, budget) {
+    for (let i = 0; i < present.length; i++) {
+        // Below present[i] lie i stored indices and present[i] - i gaps: it fits while those gaps do.
+        if (present[i] - i > budget)
+            return Math.min(wanted, budget + i);
+    }
+    return Math.min(wanted, budget + present.length);
+}
+/**
+ * Spend the record's gap budget on one log and read it: a log that asks for more rows than the budget
+ * holds is cut — what lies past the cut is unread, by name, and the log is not complete.
+ */
+function readGroup(group, limits, budget, stopped, unread) {
+    const { commits, closes, present, wanted } = group;
+    const left = budget.missing;
+    const fits = lengthWithin(wanted, present, left);
+    const past = new Set();
+    if (fits < wanted) {
+        const limit = `the reader's limit of ${limits.missingCommits} missing commits for the record (${left} were left for this log)`;
+        for (const [idx, item] of commits) {
+            if (idx < fits)
+                continue;
+            past.add(item);
+            commits.delete(idx);
+            unread.push({ index: item.index, reason: `bundle.idx is ${idx}, past ${limit}` });
+        }
+        for (const close of closes) {
+            const count = close.count;
+            if (count <= fits)
+                continue;
+            past.add(close);
+            unread.push({ index: close.index, reason: `commits is ${count}, past ${limit}` });
+        }
+    }
+    const stillPresent = past.size === 0 ? present : present.filter((idx) => idx < fits);
+    const lastKept = stillPresent.length > 0 ? stillPresent[stillPresent.length - 1] : -1;
+    const closing = coveringClose(past.size === 0 ? closes : closes.filter((close) => !past.has(close)), lastKept);
+    const length = closing !== undefined ? closing.count : lastKept + 1;
+    budget.missing -= length - stillPresent.length;
+    const rows = [];
+    for (let idx = 0; idx < length; idx++) {
+        const item = commits.get(idx);
+        if (item === undefined)
+            rows.push(NO_COMMIT);
+        else if (item.refusal !== undefined)
+            rows.push((0, bundles_js_1.absentRow)(item.refusal));
+        else
+            rows.push(item.bundle);
+    }
+    Object.freeze(rows);
+    const { log, gaps } = (0, bundles_js_1.readLog)(rows);
+    const inLog = [];
+    const notes = [];
+    for (const item of group.placed) {
+        if (group.dropped.has(item) || past.has(item))
+            continue;
+        inLog.push(item.entry);
+        if (item.entry.kind === 'note') {
+            notes.push(Object.freeze({ kind: item.entry.note, at: item.entry.at, data: item.entry.data }));
+        }
+    }
+    // Complete only when the writer closed it AND the reader read it whole.
+    const ended = closing !== undefined && past.size === 0 && !stopped ? closing.entry : undefined;
+    const opened = group.opened?.entry;
+    const meta = {};
+    if (opened?.meta !== undefined)
+        meta.opened = opened.meta;
+    if (ended?.meta !== undefined)
+        meta.closed = ended.meta;
+    return {
+        key: group.key,
+        address: group.address,
+        rows,
+        fields: {
+            ...(opened ? { initialState: opened.initialState } : {}),
+            commitLog: Object.freeze(log),
+            gaps,
+            notes: Object.freeze(notes),
+            complete: ended !== undefined,
+            ...(ended ? { outcome: ended.outcome } : {}),
+            meta: Object.freeze(meta),
+            entries: Object.freeze(inLog),
+        },
+    };
+}
+/**
+ * The mount logs of one run leg, as a live snapshot's `subflowResults` reads to the cursor: keyed by
+ * each mount's runtimeStageId (the last segment of its drill path), ONE flat map for the whole leg —
+ * so `drill` reaches a nested mount from any cursor of the leg. Built once per leg, in one pass; the
+ * first log stored for a mount id holds it. `undefined` when the leg stored no mount log.
+ */
+function mountsOf(groups) {
+    let results;
+    for (const group of groups) {
+        const { drillPath } = group.address;
+        if (drillPath.length === 0)
+            continue;
+        const mount = drillPath[drillPath.length - 1];
+        // A null-prototype map: a stored drill segment is a key, never a prototype.
+        results ??= Object.create(null);
+        if (results[mount] !== undefined)
+            continue;
+        const { initialState } = group.fields;
+        results[mount] = Object.freeze({
+            subflowId: (0, runtimeStageId_js_1.stageIdOf)(mount),
+            treeContext: Object.freeze({ history: group.rows, ...(initialState ? { initialState } : {}) }),
+        });
+    }
+    return results && Object.freeze(results);
+}
+/**
+ * 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
+ * ```
+ */
+function readStoredRecord(entries, limits) {
+    const bounds = limitsOf(limits);
+    const unread = [];
+    const byKey = new Map();
+    const seen = new Map();
+    let stopped = false;
+    let index = 0;
+    for (const row of entries) {
+        if (index >= bounds.entries) {
+            stopped = true;
+            unread.push({ index, reason: `entries from here on are past the reader's limit of ${bounds.entries}; not read` });
+            break;
+        }
+        let read;
+        try {
+            read = readEntry(row, index, bounds);
+        }
+        catch {
+            read = 'the entry threw when it was read';
+        }
+        if (typeof read === 'string') {
+            unread.push({ index, reason: read });
+        }
+        else if (seen.has(row)) {
+            unread.push({ index, reason: `the same entry as at ${seen.get(row)}` });
+        }
+        else {
+            seen.set(row, index);
+            // One address per log: an entry's own copy is kept only by the first entry of its log.
+            const key = keyOf(read.address.logRunId, read.address.drillPath);
+            const log = byKey.get(key);
+            if (log === undefined)
+                byKey.set(key, { address: read.address, placed: [read.item] });
+            else
+                log.placed.push(read.item);
+        }
+        index++;
+    }
+    // Group, then spend the gap budget on the logs that need the fewest gaps first.
+    let arrival = 0;
+    const grouped = [];
+    for (const [key, { address, placed }] of byKey)
+        grouped.push(groupOf(key, address, arrival++, placed, unread));
+    const byNeed = [...grouped].sort((a, b) => a.wanted - a.present.length - (b.wanted - b.present.length) || a.arrival - b.arrival);
+    const budget = { missing: bounds.missingCommits };
+    const read = new Map();
+    for (const group of byNeed)
+        read.set(group, readGroup(group, bounds, budget, stopped, unread));
+    const groups = grouped.map((group) => read.get(group));
+    const legs = new Map();
+    for (const group of groups) {
+        const leg = legs.get(group.address.logRunId);
+        if (leg === undefined)
+            legs.set(group.address.logRunId, [group]);
+        else
+            leg.push(group);
+    }
+    const mountsByLeg = new Map();
+    const logs = new Map();
+    for (const group of groups) {
+        const { logRunId } = group.address;
+        const { initialState } = group.fields;
+        let cached;
+        const log = Object.freeze({
+            address: group.address,
+            ...group.fields,
+            source() {
+                if (cached === undefined) {
+                    if (!mountsByLeg.has(logRunId))
+                        mountsByLeg.set(logRunId, mountsOf(legs.get(logRunId)));
+                    const subflowResults = mountsByLeg.get(logRunId);
+                    cached = Object.freeze({
+                        commitLog: group.rows,
+                        ...(initialState ? { initialState } : {}),
+                        ...(subflowResults ? { subflowResults } : {}),
+                    });
+                }
+                return cached;
+            },
+        });
+        logs.set(group.key, log);
+    }
+    unread.sort((a, b) => a.index - b.index);
+    return Object.freeze({
+        logs,
+        root: (logRunId) => (typeof logRunId === 'string' ? logs.get(keyOf(logRunId, [])) : undefined),
+        log: (address) => {
+            const own = readAddress(address, bounds);
+            return typeof own === 'string' ? undefined : logs.get(keyOf(own.logRunId, own.drillPath));
+        },
+        unread: Object.freeze(unread.map((item) => Object.freeze({ index: item.index, reason: item.reason }))),
+    });
+}
+exports.readStoredRecord = readStoredRecord;

package/dist/lib/time-travel/timeTravel.js

@@ -231,6 +231,13 @@ class Cursor {
     }
     // ── Drilling (law 1: a separate cursor, not a second position) ───────────
     drill(mountRuntimeStageId) {
+        // Never back into the mount this cursor is, or one it was drilled out of: a stored or hand-built
+        // log can name one (a mount id is unique in a sound run), and a viewer that opens every mount
+        // would loop. The walk is as deep as the drill.
+        for (let at = this; at !== undefined; at = at.parent) {
+            if (at.mountRuntimeStageId === mountRuntimeStageId)
+                return undefined;
+        }
         // On a chain, the mount is looked for in every leg — a subflow that ran
         // before the pause is in the first snapshot's results, one that ran after
         // is in the second's. Ids are unique across a sound chain (chain.ts
@@ -252,6 +259,10 @@ class Cursor {
         const tree = result?.treeContext;
         if (!results || !result || !tree || !Array.isArray(tree.history))
             return undefined;
+        // … nor into the log this cursor already reads (a mount log opened on its own knows no mount id).
+        if (this.sources.some((source) => source.commitLog === tree.history || source.history === tree.history)) {
+            return undefined;
+        }
         // `path` is the subflow PATH — the same string for every iteration of a
         // mount inside a loop. `mountRuntimeStageId` is the iteration actually
         // opened, so a UI can label and key three drill panels over `sfx#2`,

package/dist/types/index.d.ts

@@ -1,6 +1,8 @@
 /** Read a recorded execution: replay, time travel, slicing and attribution. */
 export type { CommitIdx, ExecutionCounter, ExecutionIndex, RuntimeStageId } from './lib/ids/runtimeStageId.js';
 export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId, splitStageId, } from './lib/ids/runtimeStageId.js';
+export type { AttemptId } from './lib/ids/attemptId.js';
+export { buildAttemptId, parseAttemptId } from './lib/ids/attemptId.js';
 export { UnknownVerbError } from './lib/memory/verbs.js';
 export type { CommitBundle, MemoryPatch, TraceEntry } from './lib/memory/types.js';
 export type { ExecutionTree } from './lib/memory/types.js';
@@ -8,8 +10,9 @@ export { applySmartMerge } from './lib/memory/verbs.js';
 export type { ValueBasis, ValueBasisOptions, ValueWithBasis, WriterBasis, WriterWithBasis, } from './lib/memory/commitLogUtils.js';
 export { buildCommitIndex, commitIndexOf, commitValueAt, commitValueAtWithBasis, findCommit, findCommits, findLastWriter, findLastWriterWithBasis, inferLegacyPhases, recordsPhases, } from './lib/memory/commitLogUtils.js';
 export type { CommitPhase } from './lib/memory/types.js';
-export type { AxisRefusal, AxisSplit, BookendedAxis, FoldBasis, FoldedState, FoldSource, LogGap, Mark, Move, MoveRefusal, Stop, StopFilter, StopKind, TimeTravel, TimeTravelOptions, TimeTravelSource, TimeTravelStrategy, } from './lib/time-travel/index.js';
-export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
+export type { AxisRefusal, AxisSplit, BookendedAxis, FoldBasis, FoldedState, FoldSource, LogGap, Mark, Move, MoveRefusal, Stop, StopFilter, StopKind, StoredLog, StoredNote, StoredRecord, StoredRecordLimits, TimeTravel, TimeTravelOptions, TimeTravelSource, TimeTravelStrategy, } from './lib/time-travel/index.js';
+export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, readStoredRecord, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
+export type { LogOutcome, Meta } from './lib/memory/sink.js';
 export type { CausalChainOptions, CausalEdge, CausalNode, ControlDependency, ControlDepLookup, EdgeWeigher, KeysReadLookup, } from './lib/memory/backtrack.js';
 export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';
 export type { UntrackedSource } from './lib/memory/types.js';

package/dist/types/lib/ids/attemptId.d.ts

@@ -0,0 +1,63 @@
+/**
+ * attemptId — the address of one attempt under a stage execution.
+ *
+ * Format:
+ *   <runtimeStageId>@<n>              attempt n of the stage execution      'charge#4@2'
+ *   <runtimeStageId>@<n>.<k>@<m>      attempt m of the k-th call made        'charge#4@2.1@3'
+ *                                     during stage attempt n
+ *
+ * Every number after the runtimeStageId is a positive integer, counted from 1: attempt 1 is the first
+ * try, call 1 the first call the stage attempt made. Written without leading zeros, so one attempt has
+ * one spelling and an id is a safe join key.
+ *
+ * PARSED FROM THE RIGHT. A runtimeStageId always ends in `#<execution index>`, and the suffix grammar
+ * holds no `#`, so the LAST `#` of an attempt id is its execution delimiter whatever the stage id
+ * contains — `@`, `.` and `~` stay legal in stage ids, and no byte is newly reserved (the id doors'
+ * refusal, FootPrint's `refuseReservedId`, is untouched). The delimiter is read from the grammar's one
+ * owner, `runtimeStageId.ts`.
+ *
+ * Imports nothing but the runtime-ID grammar: a leaf of the record, checked by the package fence.
+ *
+ * @example
+ * ```typescript
+ * buildAttemptId('charge#4', 2);                              // 'charge#4@2'
+ * buildAttemptId('charge#4', 2, { ordinal: 1, attempt: 3 });  // 'charge#4@2.1@3'
+ * parseAttemptId('sf/v1.2@x#7@3'); // { runtimeStageId: 'sf/v1.2@x#7', attempt: 3 }
+ * parseAttemptId('charge#4');      // undefined — a stage execution, not an attempt
+ * ```
+ */
+import { type RuntimeStageId } from './runtimeStageId.js';
+declare const ATTEMPT_ID: unique symbol;
+/** A `<runtimeStageId>@<n>[.<k>@<m>]` string the grammar produced. Assignable to `string`. */
+export type AttemptId = string & {
+    readonly [ATTEMPT_ID]: true;
+};
+/**
+ * Build the id of one attempt.
+ *
+ * @param runtimeStageId The stage execution the attempt belongs to (`[subflowPath/]stageId#index`).
+ * @param attempt The stage attempt, from 1.
+ * @param call For an attempt of a call made inside the stage attempt: the call's `ordinal` (1 for the
+ *   first call that stage attempt made) and its own `attempt` (from 1).
+ * @throws TypeError when `runtimeStageId` does not end in `#<execution index>`, and RangeError when a
+ *   count is not a positive integer — what `parseAttemptId` could not give back is never written.
+ */
+export declare function buildAttemptId(runtimeStageId: string, attempt: number, call?: {
+    readonly ordinal: number;
+    readonly attempt: number;
+}): AttemptId;
+/**
+ * Parse an attempt id into its parts, or `undefined` when `id` is not one (a bare runtimeStageId, a
+ * count of 0, a leading zero, a missing part). Never throws.
+ *
+ * `parseAttemptId(buildAttemptId(...parts))` gives the parts back, whatever the stage id contains.
+ */
+export declare function parseAttemptId(id: string): {
+    runtimeStageId: RuntimeStageId;
+    attempt: number;
+    call?: {
+        ordinal: number;
+        attempt: number;
+    };
+} | undefined;
+export {};