foottrace 0.0.0-stage → 1.0.0

package/dist/lib/slice/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * slice/ — variable-first slicing, both directions (the triage query layer).
+ *
+ * One variable, one contract, every surface — asked identically by UI panels
+ * (explainable-ui / lens), LLM triage tools (trace toolpacks), and offline
+ * autopsy agents:
+ *
+ * - BACKWARD — "why is this VARIABLE what it is?" (`sliceForKey`,
+ *   `arrayProvenance` / `elementProvenance`).
+ * - FORWARD — "who READ it, and what did it FEED?" (`forwardSliceForKey`),
+ *   plus the flat chronological view (`keyTimeline`).
+ *
+ * See README.md for the algorithms (thin-slice composition, append-fold
+ * provenance, live-range walking), the honesty model, serialization rules,
+ * and the evolution path.
+ *
+ * DAG position: memory ← slice (leaf-adjacent; imports memory/ only).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normaliseStateKey = exports.sliceForKey = exports.sliceToJSON = exports.forwardSliceToJSON = exports.formatTimeline = exports.formatSlice = exports.formatForwardSlice = exports.keyTimeline = exports.resolveKeysReadSource = exports.keysReadFromMap = exports.keysReadFromExecutionTree = exports.forwardSliceForKey = exports.elementProvenance = exports.arrayProvenance = void 0;
+var elementProvenance_js_1 = require("./elementProvenance.js");
+Object.defineProperty(exports, "arrayProvenance", { enumerable: true, get: function () { return elementProvenance_js_1.arrayProvenance; } });
+Object.defineProperty(exports, "elementProvenance", { enumerable: true, get: function () { return elementProvenance_js_1.elementProvenance; } });
+var forwardSliceForKey_js_1 = require("./forwardSliceForKey.js");
+Object.defineProperty(exports, "forwardSliceForKey", { enumerable: true, get: function () { return forwardSliceForKey_js_1.forwardSliceForKey; } });
+var keysReadSources_js_1 = require("./keysReadSources.js");
+Object.defineProperty(exports, "keysReadFromExecutionTree", { enumerable: true, get: function () { return keysReadSources_js_1.keysReadFromExecutionTree; } });
+Object.defineProperty(exports, "keysReadFromMap", { enumerable: true, get: function () { return keysReadSources_js_1.keysReadFromMap; } });
+Object.defineProperty(exports, "resolveKeysReadSource", { enumerable: true, get: function () { return keysReadSources_js_1.resolveKeysReadSource; } });
+var keyTimeline_js_1 = require("./keyTimeline.js");
+Object.defineProperty(exports, "keyTimeline", { enumerable: true, get: function () { return keyTimeline_js_1.keyTimeline; } });
+var serialize_js_1 = require("./serialize.js");
+Object.defineProperty(exports, "formatForwardSlice", { enumerable: true, get: function () { return serialize_js_1.formatForwardSlice; } });
+Object.defineProperty(exports, "formatSlice", { enumerable: true, get: function () { return serialize_js_1.formatSlice; } });
+Object.defineProperty(exports, "formatTimeline", { enumerable: true, get: function () { return serialize_js_1.formatTimeline; } });
+Object.defineProperty(exports, "forwardSliceToJSON", { enumerable: true, get: function () { return serialize_js_1.forwardSliceToJSON; } });
+Object.defineProperty(exports, "sliceToJSON", { enumerable: true, get: function () { return serialize_js_1.sliceToJSON; } });
+var sliceForKey_js_1 = require("./sliceForKey.js");
+Object.defineProperty(exports, "sliceForKey", { enumerable: true, get: function () { return sliceForKey_js_1.sliceForKey; } });
+var paths_js_1 = require("../memory/paths.js");
+Object.defineProperty(exports, "normaliseStateKey", { enumerable: true, get: function () { return paths_js_1.normaliseStateKey; } });

package/dist/lib/slice/keyIndex.js

@@ -0,0 +1,312 @@
+"use strict";
+/**
+ * slice/keyIndex.ts — the one pass over the log both FORWARD queries share.
+ *
+ * WHY it exists: a backward slice only ever asks "who wrote key k before
+ * idx i" — `findLastWriter` answers that with a backward scan. A forward
+ * query asks the opposite, and the opposite is not symmetric: reads are NOT
+ * in the commit log, and `KeysReadSource` is a LOOKUP (runtimeStageId →
+ * keys), not an enumerable collection. So "who read k" cannot be looked up —
+ * it has to be inverted.
+ *
+ * THE INVERSION (and the law it rests on): the engine commits exactly ONE
+ * bundle per executed stage, so the commit log IS the list of execution
+ * steps. Calling the reads lookup once per bundle turns the strategy into a
+ * key → [commit indices that read it] index — and gives every read moment a
+ * commit position, the join key the whole library is addressed by.
+ *
+ * Consequence worth stating (documented, not silently absorbed): a reads
+ * provider naming a step that has no commit in THIS log contributes nothing.
+ * That is the same log↔reads pairing law the backward side has — a subflow
+ * runs in an isolated runtime, so its log and its tree must come from the
+ * same scope (see README.md § Subflow boundaries).
+ *
+ * Cost: one lookup call per bundle, once per query — O(N + total read keys).
+ * Both forward queries then run off sorted index arrays.
+ *
+ * DAG position: internal to slice/ (not exported from the barrel).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writtenPaths = exports.truncatedNote = exports.conservativeEdgesNote = exports.preRunOriginNote = exports.readsNotRecordedNote = exports.fromInitialStateNote = exports.redactedValueNote = exports.nestedRowsNote = exports.NESTED_WRITES_LISTED = exports.nestedOnlyWrites = exports.writeEntry = exports.lastTraceEntry = exports.firstIndexAfter = exports.lastIndexBefore = exports.indicesInRange = exports.hasRecordedReads = exports.unknownKeyNote = exports.buildKeyIndex = exports.KNOWN_KEYS_LISTED = void 0;
+const keyPaths_js_1 = require("../memory/keyPaths.js");
+const logModel_js_1 = require("../memory/logModel.js");
+const paths_js_1 = require("../memory/paths.js");
+/** How many known keys an unknown-key refusal lists before it says "+N more". */
+exports.KNOWN_KEYS_LISTED = 10;
+/** Push into a Map<string, number[]>, creating the bucket on first touch. */
+function push(map, key, idx) {
+    const arr = map.get(key);
+    if (arr)
+        arr.push(idx);
+    else
+        map.set(key, [idx]);
+}
+/**
+ * Build the index. Indices go in ascending order by construction (we iterate
+ * the log forwards), which is what lets every range query below be a pair of
+ * binary searches instead of a scan.
+ */
+function buildKeyIndex(commitLog, lookup) {
+    const model = (0, logModel_js_1.logModel)(commitLog);
+    const writers = model.index;
+    const readsByKey = new Map();
+    const readKeysByRoot = new Map();
+    for (let i = 0; i < commitLog.length; i++) {
+        const bundle = commitLog[i];
+        // Reads: one lookup per execution step (see THE INVERSION above).
+        // A provider that throws is a consumer bug, not a reason to lose the
+        // query — the same error-isolation posture recorder callbacks get.
+        let keys = [];
+        try {
+            keys = lookup(bundle.runtimeStageId) ?? [];
+        }
+        catch {
+            /* provider threw — treat this step as "no recorded reads" */
+        }
+        for (const k of new Set(keys)) {
+            if (!readsByKey.has(k)) {
+                const names = readKeysByRoot.get((0, keyPaths_js_1.rootOf)(k));
+                if (names)
+                    names.push(k);
+                else
+                    readKeysByRoot.set((0, keyPaths_js_1.rootOf)(k), [k]);
+            }
+            push(readsByKey, k, i);
+        }
+    }
+    const writesOf = (key) => model.writersOf(key);
+    const closing = new Map();
+    const closingWritesOf = (key) => {
+        let positions = closing.get(key);
+        if (positions === undefined) {
+            const nested = new Set(nestedOnlyWrites(commitLog, key, writesOf(key)));
+            positions = writesOf(key).filter((c) => !nested.has(c));
+            closing.set(key, positions);
+        }
+        return positions;
+    };
+    const reads = new Map();
+    const readsOf = (key) => {
+        let positions = reads.get(key);
+        if (positions === undefined) {
+            const names = readKeysByRoot.get((0, keyPaths_js_1.rootOf)(key)) ?? [];
+            positions = (0, keyPaths_js_1.ascendingUnion)(names.filter((name) => (0, keyPaths_js_1.relation)(name, key) !== undefined).map((name) => readsByKey.get(name)));
+            reads.set(key, positions);
+        }
+        return positions;
+    };
+    const knownKeys = new Set([...(0, keyPaths_js_1.pathsWritten)(writers), ...readsByKey.keys()]);
+    const isKnown = (key) => writesOf(key).length > 0 || readsOf(key).length > 0;
+    return { writers, writesOf, closingWritesOf, readsByKey, readsOf, knownKeys, isKnown };
+}
+exports.buildKeyIndex = buildKeyIndex;
+/**
+ * LAW — an unknown key is NAMED as unknown; it never renders as "no history".
+ *
+ * The failure this prevents: `forwardSliceForKey(log, 'recipId')` (typo) must
+ * not come back looking like a real variable that nothing happened to. The
+ * answer says so out loud AND lists the keys the log does know — bounded, so
+ * a 400-key agent state is a hint, not a wall.
+ *
+ * Why a NOTE and not a throw: the module's absence convention is a RESULT,
+ * not an exception (`VariableSlice.missing`) — one absence vocabulary across
+ * both doors. The loudness comes from the note + `missing: 'never-written'`,
+ * not from a stack trace a triage tool would have to catch.
+ */
+function unknownKeyNote(index, key) {
+    const all = [...index.knownKeys].sort();
+    const shown = all.slice(0, exports.KNOWN_KEYS_LISTED);
+    const more = all.length - shown.length;
+    const known = shown.length > 0 ? `${shown.join(', ')}${more > 0 ? ` (+${more} more)` : ''}` : '(none)';
+    return {
+        code: 'unknown-key',
+        detail: `unknown key '${key}' — this commit log has no write and no recorded read of it. ` +
+            `Known keys: ${known}. ` +
+            'If the key is real, check that the commit log and the reads provider come from the SAME scope ' +
+            '(a subflow has its own).',
+    };
+}
+exports.unknownKeyNote = unknownKeyNote;
+/**
+ * Does this log carry ANY recorded read? The provider-agnostic version of
+ * `ReadsCoverage.stepsWithReads > 0` (map / custom-fn strategies carry no
+ * coverage), and the switch that decides whether "nobody read it" is a
+ * FINDING or a BLIND SPOT.
+ */
+function hasRecordedReads(index) {
+    return index.readsByKey.size > 0;
+}
+exports.hasRecordedReads = hasRecordedReads;
+/** First position in the ascending array holding a value >= `value`. */
+function lowerBound(sorted, value) {
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] < value)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/**
+ * Ascending indices in the INCLUSIVE range [from, to]. `to === undefined`
+ * means "to the end of the log".
+ */
+function indicesInRange(sorted, from, to) {
+    if (!sorted || sorted.length === 0)
+        return [];
+    const start = lowerBound(sorted, from);
+    const end = to === undefined ? sorted.length : lowerBound(sorted, to + 1);
+    return sorted.slice(start, end);
+}
+exports.indicesInRange = indicesInRange;
+/** The largest index in the ascending array that is < `before`, or undefined. */
+function lastIndexBefore(sorted, before) {
+    if (!sorted || sorted.length === 0)
+        return undefined;
+    const end = before === undefined ? sorted.length : lowerBound(sorted, before);
+    return end > 0 ? sorted[end - 1] : undefined;
+}
+exports.lastIndexBefore = lastIndexBefore;
+/** The smallest index in the ascending array that is > `after`, or undefined. */
+function firstIndexAfter(sorted, after) {
+    if (!sorted || sorted.length === 0)
+        return undefined;
+    const at = lowerBound(sorted, after + 1);
+    return at < sorted.length ? sorted[at] : undefined;
+}
+exports.firstIndexAfter = firstIndexAfter;
+/**
+ * The LAST trace entry for `path` in a bundle — the one that decides both the
+ * committed verb and (under the writeProvenance dial) the widest read prefix.
+ * Full mode can record several ops on one path in one commit; read prefixes
+ * only grow during a stage, so the last entry is the honest one to attribute
+ * with.
+ */
+function lastTraceEntry(bundle, path) {
+    for (let i = bundle.trace.length - 1; i >= 0; i--) {
+        if (bundle.trace[i].path === path)
+            return bundle.trace[i];
+    }
+    return undefined;
+}
+exports.lastTraceEntry = lastTraceEntry;
+/**
+ * The trace entry that decides a WRITE of `key` in `bundle` — its verb, and the read prefix a
+ * fed edge is judged by: the LAST entry on the exact path when there is one (as before 9.33.0),
+ * otherwise the last entry inside or around the key (the commit wrote it through a nested row).
+ */
+function writeEntry(bundle, key) {
+    const exact = lastTraceEntry(bundle, key);
+    if (exact !== undefined)
+        return exact;
+    for (let i = bundle.trace.length - 1; i >= 0; i--) {
+        if ((0, keyPaths_js_1.relation)(bundle.trace[i].path, key) !== undefined)
+            return bundle.trace[i];
+    }
+    return undefined;
+}
+exports.writeEntry = writeEntry;
+/**
+ * The commits in `writes` that reached `key` ONLY through rows inside it — no row on the key and
+ * none around it — so each changed part of its value, not the whole. What a `'nested-rows'` note
+ * names.
+ */
+function nestedOnlyWrites(commitLog, key, writes) {
+    return writes.filter((i) => (0, keyPaths_js_1.writesOnlyInside)(commitLog[i], key));
+}
+exports.nestedOnlyWrites = nestedOnlyWrites;
+/** How many commit positions a `'nested-rows'` note lists before it says "+N more". */
+exports.NESTED_WRITES_LISTED = 5;
+/** A key as a person reads it: its segments, not the engine's delimiter. */
+function shownKey(key) {
+    return (0, paths_js_1.pathSegments)(key).join(' › ');
+}
+/** A write the answer rests on reached the key only through paths inside it. */
+function nestedRowsNote(key, commits) {
+    const shown = commits.slice(0, exports.NESTED_WRITES_LISTED);
+    const more = commits.length - shown.length;
+    const at = `commit${commits.length === 1 ? '' : 's'} ${shown.join(', ')}${more > 0 ? ` (+${more} more)` : ''}`;
+    return {
+        code: 'nested-rows',
+        detail: `'${shownKey(key)}' was written only through paths inside it at ${at} — such a write changed part of ` +
+            'its value, not the whole: earlier writes may account for the rest, and a reader of the key may ' +
+            'not have read the part it changed.',
+    };
+}
+exports.nestedRowsNote = nestedRowsNote;
+/** The value a backward slice explains holds, or lost the key under, the log's redaction placeholder. */
+function redactedValueNote(key) {
+    return {
+        code: 'redacted',
+        detail: `'${shownKey(key)}' was redacted when it was written — where its value shows the log's placeholder (or ` +
+            'the key is missing under a placeholder that replaced its container), the real value was never recorded.',
+    };
+}
+exports.redactedValueNote = redactedValueNote;
+/** No set or delete of the key, or of a container around it, is in range: the value rests on the pre-run state. */
+function fromInitialStateNote(key) {
+    return {
+        code: 'from-initial-state',
+        detail: `'${shownKey(key)}' has no write of its whole value in range — its value rests on what it held before the ` +
+            'run, which the commit log cannot see, so the writes here may be only part of it.',
+    };
+}
+exports.fromInitialStateNote = fromInitialStateNote;
+// ── Shared honesty notes (one sentence per code, one place) ───────────────
+//
+// LAW: every forward answer states what it could not see, in the SAME words
+// whichever query produced it. Codes are what a consumer branches on; the
+// detail is what a human or an LLM reads.
+/** The `readTracking: 'off'` signature — see the HonestyNoteCode docs. */
+function readsNotRecordedNote() {
+    return {
+        code: 'reads-not-recorded',
+        detail: "reads were not recorded (readTracking may be 'off') — 'nothing read this value' is " +
+            'UNKNOWABLE here, not true.',
+    };
+}
+exports.readsNotRecordedNote = readsNotRecordedNote;
+/** The value predates every write this log can see. */
+function preRunOriginNote(key) {
+    return {
+        code: 'pre-run-origin',
+        detail: `'${key}' has no write before this point — the value came from initial state, frozen run input ` +
+            '(args), or a closure. The reads listed did see it; who put it there is outside the commit log.',
+    };
+}
+exports.preRunOriginNote = preRunOriginNote;
+/** At least one fed edge rests on stage-level co-occurrence only. */
+function conservativeEdgesNote(key) {
+    return {
+        code: 'conservative-fed-edges',
+        detail: "some 'fed' edges are CONSERVATIVE (stage-level): those writes carry no per-write read provenance, " +
+            `so a stage that read '${key}' and wrote another key may not actually have used it. Run with ` +
+            "writeProvenance: 'reads-prefix' to get exact edges.",
+    };
+}
+exports.conservativeEdgesNote = conservativeEdgesNote;
+/** A budget cut the walk — stated, never silent. */
+function truncatedNote(byDepth, byNodes) {
+    const causes = [byDepth && 'maxDepth reached', byNodes && 'maxNodes reached'].filter(Boolean).join(', ');
+    return {
+        code: 'truncated',
+        detail: `walk truncated (${causes}) — more consumers of this value exist beyond this horizon.`,
+    };
+}
+exports.truncatedNote = truncatedNote;
+/** Distinct written paths of a bundle, in first-touch order. */
+function writtenPaths(bundle) {
+    const seen = new Set();
+    const out = [];
+    for (const t of bundle.trace) {
+        if (!seen.has(t.path)) {
+            seen.add(t.path);
+            out.push(t.path);
+        }
+    }
+    return out;
+}
+exports.writtenPaths = writtenPaths;

package/dist/lib/slice/keyTimeline.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * slice/keyTimeline.ts — the whole life of ONE key, in commit order.
+ *
+ * The flat companion to {@link forwardSliceForKey}: no graph, no budgets,
+ * no anchor — every write of the key and every recorded read of it, as one
+ * chronological list. This is what a UI timeline row and an LLM's "walk me
+ * through what happened to `total`" both want, and what makes a forward
+ * slice checkable: the same facts, unfolded instead of walked.
+ *
+ * Every moment carries BOTH universal join keys — `runtimeStageId` (to
+ * recorders, execution trees, UIs) and `commitIdx` (to the commit log).
+ *
+ * ### LAW — read attribution is the walk's, exactly
+ *
+ * A read moment's `fromWriteIdx` is the write whose live range it sits in:
+ * the last write at a STRICTLY earlier commit index. That is the same
+ * `(writeIdx, nextWriteIdx]` rule `forwardSliceForKey` walks (reads fire
+ * PRE-commit), so the two doors can never disagree about which value a read
+ * saw — pinned by a cross-door property test. A read before ANY write has no
+ * `fromWriteIdx` and raises the `'pre-run-origin'` note: it saw initial
+ * state, frozen run `input`, or a closure.
+ *
+ * DAG position: memory ← slice. Imports memory/ only (see README.md).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyTimeline = void 0;
+const keyIndex_js_1 = require("./keyIndex.js");
+const keysReadSources_js_1 = require("./keysReadSources.js");
+const paths_js_1 = require("../memory/paths.js");
+/**
+ * The life of one key as a chronological list of writes and reads.
+ *
+ * @param commitLog Ordered commit bundles — `getSnapshot().commitLog`.
+ * @param key A {@link StateKey} — normalised through the same
+ *   `normaliseStateKey` both slice doors use.
+ * @param keysRead A {@link KeysReadSource} or bare lookup (reads are not in
+ *   the commit log).
+ * @returns Always a {@link KeyTimeline}; absence carries its reason, and an
+ *   unknown key is NAMED as unknown with a bounded list of known keys.
+ */
+function keyTimeline(commitLog, key, keysRead, options) {
+    const source = (0, keysReadSources_js_1.resolveKeysReadSource)(keysRead);
+    const normalisedKey = (0, paths_js_1.normaliseStateKey)(key);
+    const base = {
+        key: normalisedKey,
+        ...(options?.before !== undefined && { before: options.before }),
+        keysReadKind: source.kind,
+        ...(source.coverage !== undefined && { readsCoverage: source.coverage }),
+    };
+    if (commitLog.length === 0)
+        return { ...base, missing: 'empty-log', notes: [] };
+    const index = (0, keyIndex_js_1.buildKeyIndex)(commitLog, source.lookup);
+    const readsRecorded = (0, keyIndex_js_1.hasRecordedReads)(index);
+    const notes = [];
+    // Same typo guard as the forward walk — one rule, both doors.
+    if (!index.isKnown(normalisedKey)) {
+        notes.push((0, keyIndex_js_1.unknownKeyNote)(index, normalisedKey));
+        if (readsRecorded)
+            return { ...base, missing: 'never-written', notes };
+    }
+    if (!readsRecorded)
+        notes.push((0, keyIndex_js_1.readsNotRecordedNote)());
+    const limit = options?.before ?? commitLog.length;
+    // Writes under the writer rule (on the key, inside it, or around it and
+    // changing it); reads on the key, inside it or around it (keyIndex.ts).
+    const allWrites = index.writesOf(normalisedKey);
+    const writes = allWrites.filter((i) => i < limit);
+    const reads = index.readsOf(normalisedKey).filter((i) => i < limit);
+    // Merge two ascending index lists. At the SAME commit index a read comes
+    // first: reads fire before their stage's commit (the engine's event order,
+    // and the reason the live range is closed at the next write).
+    const moments = [];
+    let w = 0;
+    let r = 0;
+    let sawPreRunRead = false;
+    while (w < writes.length || r < reads.length) {
+        const takeRead = r < reads.length && (w >= writes.length || reads[r] <= writes[w]);
+        if (takeRead) {
+            const idx = reads[r++];
+            const bundle = commitLog[idx];
+            // The live range this read sits in: the last write STRICTLY earlier.
+            const fromWriteIdx = (0, keyIndex_js_1.lastIndexBefore)(allWrites, idx);
+            if (fromWriteIdx === undefined)
+                sawPreRunRead = true;
+            moments.push({
+                kind: 'read',
+                commitIdx: idx,
+                runtimeStageId: bundle.runtimeStageId,
+                stageId: bundle.stageId,
+                stageName: bundle.stage,
+                ...(fromWriteIdx !== undefined && { fromWriteIdx }),
+            });
+        }
+        else {
+            const idx = writes[w++];
+            const bundle = commitLog[idx];
+            const entry = (0, keyIndex_js_1.writeEntry)(bundle, normalisedKey);
+            moments.push({
+                kind: 'write',
+                commitIdx: idx,
+                runtimeStageId: bundle.runtimeStageId,
+                stageId: bundle.stageId,
+                stageName: bundle.stage,
+                ...(entry !== undefined && { verb: entry.verb }),
+            });
+        }
+    }
+    if (sawPreRunRead)
+        notes.push((0, keyIndex_js_1.preRunOriginNote)(normalisedKey));
+    const nested = (0, keyIndex_js_1.nestedOnlyWrites)(commitLog, normalisedKey, writes);
+    if (nested.length > 0)
+        notes.push((0, keyIndex_js_1.nestedRowsNote)(normalisedKey, nested));
+    return { ...base, moments, notes };
+}
+exports.keyTimeline = keyTimeline;

package/dist/lib/slice/keysReadSources.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * slice/keysReadSources.ts — the shipped {@link KeysReadSource} strategies.
+ *
+ * The canonical strategy list and rationale live on the KeysReadSource type
+ * (types.ts) — the doc consumers hover. This file holds the implementations.
+ *
+ * Deliberately NOT here: a QualityRecorder adapter. Importing recorder/ would
+ * drag this leaf library up the dependency DAG. The adapter is a one-liner at
+ * the call site instead: `(id) => recorder.getByKey(id)?.keysRead ?? []`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveKeysReadSource = exports.keysReadFromMap = exports.keysReadFromExecutionTree = void 0;
+/**
+ * Post-hoc reads from a finished run's execution tree — ZERO setup.
+ *
+ * WHY this works: a stage's `stageReads` records the keys it
+ * tracked-read whenever the `readTracking` dial ≠ 'off' ('full' is the
+ * engine default; 'summary' replaces VALUES with markers but keeps the
+ * KEYS — and keys are all a slice needs). Under 'off' this source returns
+ * empty read-sets — detectable via `coverage.stepsWithReads === 0`, which
+ * `sliceForKey` copies onto the slice so tools can say "reads were not
+ * recorded" instead of the lie "no dependencies".
+ *
+ * SUBFLOW PAIRING (important): a subflow runs in an ISOLATED runtime — its
+ * commits live in `snapshot.subflowResults[sfId].commitLog`, its reads in
+ * `snapshot.subflowResults[sfId].executionTree`. Trees and logs must be
+ * paired from the SAME scope: to slice a key inside a subflow, re-anchor
+ * there —
+ *
+ * ```ts
+ * const sf = snapshot.subflowResults['sf-tools'];
+ * sliceForKey(sf.commitLog, key, keysReadFromExecutionTree(sf.executionTree));
+ * ```
+ *
+ * Passing multiple trees widens READ resolution only (useful when one log
+ * genuinely spans them); it does not let a root-log slice cross a subflow
+ * mount — see README.md § Subflow boundaries.
+ */
+function keysReadFromExecutionTree(tree) {
+    const byStep = new Map();
+    let steps = 0;
+    // The tree is acyclic by construction (next/children), but this walker is
+    // also handed CONSUMER-provided data — a visited set makes a malformed or
+    // hand-built tree a non-event instead of an infinite loop.
+    const visited = new Set();
+    const stack = [tree].flat(); // one root, or several (subflow trees); a hole is skipped
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (visited.has(node))
+            continue;
+        visited.add(node);
+        if (node.runtimeStageId) {
+            steps++;
+            if (node.stageReads) {
+                const keys = Object.keys(node.stageReads);
+                if (keys.length > 0)
+                    byStep.set(node.runtimeStageId, keys);
+            }
+        }
+        if (node.next)
+            stack.push(node.next);
+        if (node.children)
+            for (const c of node.children)
+                stack.push(c);
+    }
+    return {
+        kind: 'execution-tree',
+        lookup: (runtimeStageId) => byStep.get(runtimeStageId) ?? [],
+        coverage: { steps, stepsWithReads: byStep.size },
+    };
+}
+exports.keysReadFromExecutionTree = keysReadFromExecutionTree;
+/**
+ * Reads from a prebuilt map — e.g. collected live from
+ * `ScopeRecorder.onRead` events, or deserialized from a stored trace.
+ */
+function keysReadFromMap(map) {
+    // Own-property guard on the object form: runtimeStageIds are consumer-
+    // influenced strings; without it, an id like 'constructor' would read
+    // through the prototype chain (the same hardening posture as the engine's
+    // nativeGet/prototype-pollution guards).
+    const get = map instanceof Map
+        ? (id) => map.get(id)
+        : (id) => Object.prototype.hasOwnProperty.call(map, id) ? map[id] : undefined;
+    return {
+        kind: 'map',
+        lookup: (runtimeStageId) => [...(get(runtimeStageId) ?? [])],
+    };
+}
+exports.keysReadFromMap = keysReadFromMap;
+/**
+ * Normalize the ergonomic union: callers may pass a full strategy object or
+ * a bare lookup function (wrapped as kind 'custom-fn' so the honesty
+ * breadcrumb still says where reads came from).
+ */
+function resolveKeysReadSource(src) {
+    return typeof src === 'function' ? { kind: 'custom-fn', lookup: src } : src;
+}
+exports.resolveKeysReadSource = resolveKeysReadSource;