foottrace 1.0.0 → 1.0.2

package/README.md

@@ -4,7 +4,7 @@ Execution records and the tools to read them: replay, time travel, slices, and e
 
 This package extracts FootPrint's established record layer. It does not introduce a second writer or a different replay law. The first release preserves the frozen record fixtures from footprintjs 9.48.1 and includes the coordinated 9.48.2 copy-safety correction: an own `__proto__` payload field stays data, never the copy's prototype. See the [changelog](CHANGELOG.md) for the limited rich-value behavior change.
 
-**Release status:** extraction candidate. Version 1.0.0 is not ready to publish until review and release checks are complete.
+Foottrace owns the record layer used by footprintjs 10. Older stored records remain readable without installing their original engine.
 
 ## Three entry points
 

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

@@ -257,6 +257,12 @@ export type KeysReadLookup = (runtimeStageId: string) => string[];
  * @returns Root CausalNode with .parents forming the DAG, or undefined if startId not found
  */
 export declare function causalChain(commitLog: CommitBundle[], startId: string, getKeysRead: KeysReadLookup, options?: CausalChainOptions): CausalNode | undefined;
+/**
+ * Internal slice composition: keep the actual bundle selected by the writer
+ * query (including a nonempty continuation). This is not a public entry point.
+ * The read position still belongs to the execution's first commit.
+ */
+export declare function causalChainFromCommit(commitLog: CommitBundle[], writer: CommitBundle, getKeysRead: KeysReadLookup, options?: CausalChainOptions): CausalNode | undefined;
 /**
  * Flatten the causal DAG into a BFS-ordered list of nodes.
  * Each node appears exactly once (first occurrence by BFS order).

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

@@ -56,7 +56,7 @@
  * console.log(formatCausalChain(dag));     // human-readable
  * ```
  */
-import { findLastWriter } from './commitLogUtils.js';
+import { buildCommitIndex, findLastWriter } from './commitLogUtils.js';
 import { queryWork, relation, writesOnlyInside } from './keyPaths.js';
 import { logModel } from './logModel.js';
 // ── Staged optimization: writer lookup strategies ──────────────────────
@@ -148,6 +148,17 @@ function incompleteSourcesFragment(commit) {
  * @returns Root CausalNode with .parents forming the DAG, or undefined if startId not found
  */
 export function causalChain(commitLog, startId, getKeysRead, options) {
+    return buildCausalChain(commitLog, startId, getKeysRead, options);
+}
+/**
+ * Internal slice composition: keep the actual bundle selected by the writer
+ * query (including a nonempty continuation). This is not a public entry point.
+ * The read position still belongs to the execution's first commit.
+ */
+export function causalChainFromCommit(commitLog, writer, getKeysRead, options) {
+    return buildCausalChain(commitLog, writer.runtimeStageId, getKeysRead, options, writer);
+}
+function buildCausalChain(commitLog, startId, getKeysRead, options, selectedWriter) {
     const maxDepth = options?.maxDepth ?? 20;
     const maxNodes = options?.maxNodes ?? 100;
     const controlDeps = options?.controlDeps;
@@ -158,16 +169,15 @@ export function causalChain(commitLog, startId, getKeysRead, options) {
     // never mistake a truncated slice for a complete one.
     let truncatedByDepth = false;
     let truncatedByNodes = false;
-    // Build position index: runtimeStageId → array position (O(n) once)
-    const idxMap = new Map();
-    for (let i = 0; i < commitLog.length; i++) {
-        idxMap.set(commitLog[i].runtimeStageId, i);
-    }
+    // A continuation may write more data, but it is not another execution of
+    // the stage's reads. Use the shared FIRST-commit rule for every read cutoff;
+    // keep writer bundles separately for their write metadata and read prefixes.
+    const idxMap = buildCommitIndex(commitLog);
     queryWork.units += commitLog.length;
     const startIdx = idxMap.get(startId);
     if (startIdx === undefined)
         return undefined;
-    const startCommit = commitLog[startIdx];
+    const startCommit = selectedWriter ?? commitLog[startIdx];
     // Pick writer lookup strategy based on log size
     const findWriter = createWriterLookup(commitLog);
     // Node dedup map: runtimeStageId → CausalNode (ensures DAG, not tree)

package/dist/esm/lib/slice/keysReadSources.d.ts

@@ -9,7 +9,6 @@
  * the call site instead: `(id) => recorder.getByKey(id)?.keysRead ?? []`.
  */
 import type { KeysReadLookup } from '../memory/backtrack.js';
-import type { ExecutionTree } from '../memory/types.js';
 import type { KeysReadSource } from './types.js';
 /**
  * Post-hoc reads from a finished run's execution tree — ZERO setup.
@@ -36,8 +35,17 @@ import type { KeysReadSource } from './types.js';
  * 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.
+ *
+ * A live {@link ExecutionTree} or unknown saved JSON uses this same traversal.
+ * Malformed reader fields throw a TypeError naming their source path; no partial
+ * reads strategy is returned. Optional fields may be absent or undefined, but
+ * null nodes, sparse arrays and wrongly shaped fields are not missing evidence
+ * to silently skip. Only read-map KEYS are inspected, never their stored values.
+ * Cycles/shared objects are visited once; existing traversal order is retained.
+ * Coverage counts observed nodes and nonempty read sets, not capture completeness.
+ * This is an ordinary-data boundary, not a sandbox for hostile proxies/accessors.
  */
-export declare function keysReadFromExecutionTree(tree: ExecutionTree | readonly ExecutionTree[]): KeysReadSource;
+export declare function keysReadFromExecutionTree(tree: unknown): KeysReadSource;
 /**
  * Reads from a prebuilt map — e.g. collected live from
  * `ScopeRecorder.onRead` events, or deserialized from a stored trace.

package/dist/esm/lib/slice/keysReadSources.js

@@ -8,6 +8,10 @@
  * drag this leaf library up the dependency DAG. The adapter is a one-liner at
  * the call site instead: `(id) => recorder.getByKey(id)?.keysRead ?? []`.
  */
+/** Narrow only the object shape this reader uses; stored values stay opaque. */
+function isReadTreeObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Post-hoc reads from a finished run's execution tree — ZERO setup.
  *
@@ -33,33 +37,63 @@
  * 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.
+ *
+ * A live {@link ExecutionTree} or unknown saved JSON uses this same traversal.
+ * Malformed reader fields throw a TypeError naming their source path; no partial
+ * reads strategy is returned. Optional fields may be absent or undefined, but
+ * null nodes, sparse arrays and wrongly shaped fields are not missing evidence
+ * to silently skip. Only read-map KEYS are inspected, never their stored values.
+ * Cycles/shared objects are visited once; existing traversal order is retained.
+ * Coverage counts observed nodes and nonempty read sets, not capture completeness.
+ * This is an ordinary-data boundary, not a sandbox for hostile proxies/accessors.
  */
 export 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
+    // also handed CONSUMER-provided data — a visited set makes a cycle in a
     // 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
+    const stack = [];
+    if (Array.isArray(tree)) {
+        // Indexing retains holes as invalid evidence, unlike flat()/map().
+        for (let i = 0; i < tree.length; i++)
+            stack.push({ node: tree[i], path: `$[${i}]` });
+    }
+    else {
+        stack.push({ node: tree, path: '$' });
+    }
     while (stack.length > 0) {
-        const node = stack.pop();
+        const { node, path } = stack.pop();
+        if (!isReadTreeObject(node))
+            throw new TypeError(`keysReadFromExecutionTree: ${path} must be an object`);
         if (visited.has(node))
             continue;
         visited.add(node);
-        if (node.runtimeStageId) {
+        const { runtimeStageId, stageReads, next, children } = node;
+        if (runtimeStageId !== undefined && typeof runtimeStageId !== 'string') {
+            throw new TypeError(`keysReadFromExecutionTree: ${path}.runtimeStageId must be a string when present`);
+        }
+        if (stageReads !== undefined && !isReadTreeObject(stageReads)) {
+            throw new TypeError(`keysReadFromExecutionTree: ${path}.stageReads must be an object when present`);
+        }
+        if (children !== undefined && !Array.isArray(children)) {
+            throw new TypeError(`keysReadFromExecutionTree: ${path}.children must be an array when present`);
+        }
+        if (runtimeStageId) {
             steps++;
-            if (node.stageReads) {
-                const keys = Object.keys(node.stageReads);
+            if (stageReads !== undefined) {
+                const keys = Object.keys(stageReads);
                 if (keys.length > 0)
-                    byStep.set(node.runtimeStageId, keys);
+                    byStep.set(runtimeStageId, keys);
             }
         }
-        if (node.next)
-            stack.push(node.next);
-        if (node.children)
-            for (const c of node.children)
-                stack.push(c);
+        if (next !== undefined)
+            stack.push({ node: next, path: `${path}.next` });
+        if (children !== undefined) {
+            for (let i = 0; i < children.length; i++)
+                stack.push({ node: children[i], path: `${path}.children[${i}]` });
+        }
     }
     return {
         kind: 'execution-tree',

package/dist/esm/lib/slice/sliceForKey.js

@@ -12,7 +12,7 @@
  * it, every surface hand-rolls the anchor step differently and their answers
  * disagree. The value of this function is that they can't.
  */
-import { causalChain } from '../memory/backtrack.js';
+import { causalChainFromCommit } from '../memory/backtrack.js';
 import { commitValueAtWithBasis, findLastWriterWithBasis } from '../memory/commitLogUtils.js';
 import { normaliseStateKey } from '../memory/paths.js';
 import { fromInitialStateNote, nestedRowsNote, redactedValueNote } from './keyIndex.js';
@@ -69,7 +69,9 @@ export function sliceForKey(commitLog, key, keysRead, options) {
     // without `TraceEntry.readKeys` (the writeProvenance dial off) fall back
     // to stage-level expansion per node, byte-identically. Consumers can force
     // 'stage' via options.
-    const root = causalChain(commitLog, writer.runtimeStageId, source.lookup, {
+    // Preserve this exact writer's metadata/read prefix, even when it is a
+    // continuation. Causal expansion separately uses the execution's first commit.
+    const root = causalChainFromCommit(commitLog, writer, source.lookup, {
         ...options,
         edgeAttribution: options?.edgeAttribution ?? 'per-write',
         rootLinkKeys: options?.rootLinkKeys ?? [normalisedKey],

package/dist/lib/memory/backtrack.js

@@ -58,7 +58,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._REVERSE_INDEX_THRESHOLD = exports.formatCausalChain = exports.flattenCausalDAG = exports.causalChain = void 0;
+exports._REVERSE_INDEX_THRESHOLD = exports.formatCausalChain = exports.flattenCausalDAG = exports.causalChainFromCommit = exports.causalChain = void 0;
 const commitLogUtils_js_1 = require("./commitLogUtils.js");
 const keyPaths_js_1 = require("./keyPaths.js");
 const logModel_js_1 = require("./logModel.js");
@@ -151,6 +151,19 @@ function incompleteSourcesFragment(commit) {
  * @returns Root CausalNode with .parents forming the DAG, or undefined if startId not found
  */
 function causalChain(commitLog, startId, getKeysRead, options) {
+    return buildCausalChain(commitLog, startId, getKeysRead, options);
+}
+exports.causalChain = causalChain;
+/**
+ * Internal slice composition: keep the actual bundle selected by the writer
+ * query (including a nonempty continuation). This is not a public entry point.
+ * The read position still belongs to the execution's first commit.
+ */
+function causalChainFromCommit(commitLog, writer, getKeysRead, options) {
+    return buildCausalChain(commitLog, writer.runtimeStageId, getKeysRead, options, writer);
+}
+exports.causalChainFromCommit = causalChainFromCommit;
+function buildCausalChain(commitLog, startId, getKeysRead, options, selectedWriter) {
     const maxDepth = options?.maxDepth ?? 20;
     const maxNodes = options?.maxNodes ?? 100;
     const controlDeps = options?.controlDeps;
@@ -161,16 +174,15 @@ function causalChain(commitLog, startId, getKeysRead, options) {
     // never mistake a truncated slice for a complete one.
     let truncatedByDepth = false;
     let truncatedByNodes = false;
-    // Build position index: runtimeStageId → array position (O(n) once)
-    const idxMap = new Map();
-    for (let i = 0; i < commitLog.length; i++) {
-        idxMap.set(commitLog[i].runtimeStageId, i);
-    }
+    // A continuation may write more data, but it is not another execution of
+    // the stage's reads. Use the shared FIRST-commit rule for every read cutoff;
+    // keep writer bundles separately for their write metadata and read prefixes.
+    const idxMap = (0, commitLogUtils_js_1.buildCommitIndex)(commitLog);
     keyPaths_js_1.queryWork.units += commitLog.length;
     const startIdx = idxMap.get(startId);
     if (startIdx === undefined)
         return undefined;
-    const startCommit = commitLog[startIdx];
+    const startCommit = selectedWriter ?? commitLog[startIdx];
     // Pick writer lookup strategy based on log size
     const findWriter = createWriterLookup(commitLog);
     // Node dedup map: runtimeStageId → CausalNode (ensures DAG, not tree)
@@ -374,7 +386,6 @@ function causalChain(commitLog, startId, getKeysRead, options) {
     }
     return root;
 }
-exports.causalChain = causalChain;
 // ── Utilities ──────────────────────────────────────────────────────────
 /**
  * Flatten the causal DAG into a BFS-ordered list of nodes.

package/dist/lib/slice/keysReadSources.js

@@ -11,6 +11,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveKeysReadSource = exports.keysReadFromMap = exports.keysReadFromExecutionTree = void 0;
+/** Narrow only the object shape this reader uses; stored values stay opaque. */
+function isReadTreeObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Post-hoc reads from a finished run's execution tree — ZERO setup.
  *
@@ -36,33 +40,63 @@ exports.resolveKeysReadSource = exports.keysReadFromMap = exports.keysReadFromEx
  * 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.
+ *
+ * A live {@link ExecutionTree} or unknown saved JSON uses this same traversal.
+ * Malformed reader fields throw a TypeError naming their source path; no partial
+ * reads strategy is returned. Optional fields may be absent or undefined, but
+ * null nodes, sparse arrays and wrongly shaped fields are not missing evidence
+ * to silently skip. Only read-map KEYS are inspected, never their stored values.
+ * Cycles/shared objects are visited once; existing traversal order is retained.
+ * Coverage counts observed nodes and nonempty read sets, not capture completeness.
+ * This is an ordinary-data boundary, not a sandbox for hostile proxies/accessors.
  */
 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
+    // also handed CONSUMER-provided data — a visited set makes a cycle in a
     // 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
+    const stack = [];
+    if (Array.isArray(tree)) {
+        // Indexing retains holes as invalid evidence, unlike flat()/map().
+        for (let i = 0; i < tree.length; i++)
+            stack.push({ node: tree[i], path: `$[${i}]` });
+    }
+    else {
+        stack.push({ node: tree, path: '$' });
+    }
     while (stack.length > 0) {
-        const node = stack.pop();
+        const { node, path } = stack.pop();
+        if (!isReadTreeObject(node))
+            throw new TypeError(`keysReadFromExecutionTree: ${path} must be an object`);
         if (visited.has(node))
             continue;
         visited.add(node);
-        if (node.runtimeStageId) {
+        const { runtimeStageId, stageReads, next, children } = node;
+        if (runtimeStageId !== undefined && typeof runtimeStageId !== 'string') {
+            throw new TypeError(`keysReadFromExecutionTree: ${path}.runtimeStageId must be a string when present`);
+        }
+        if (stageReads !== undefined && !isReadTreeObject(stageReads)) {
+            throw new TypeError(`keysReadFromExecutionTree: ${path}.stageReads must be an object when present`);
+        }
+        if (children !== undefined && !Array.isArray(children)) {
+            throw new TypeError(`keysReadFromExecutionTree: ${path}.children must be an array when present`);
+        }
+        if (runtimeStageId) {
             steps++;
-            if (node.stageReads) {
-                const keys = Object.keys(node.stageReads);
+            if (stageReads !== undefined) {
+                const keys = Object.keys(stageReads);
                 if (keys.length > 0)
-                    byStep.set(node.runtimeStageId, keys);
+                    byStep.set(runtimeStageId, keys);
             }
         }
-        if (node.next)
-            stack.push(node.next);
-        if (node.children)
-            for (const c of node.children)
-                stack.push(c);
+        if (next !== undefined)
+            stack.push({ node: next, path: `${path}.next` });
+        if (children !== undefined) {
+            for (let i = 0; i < children.length; i++)
+                stack.push({ node: children[i], path: `${path}.children[${i}]` });
+        }
     }
     return {
         kind: 'execution-tree',

package/dist/lib/slice/sliceForKey.js

@@ -72,7 +72,9 @@ function sliceForKey(commitLog, key, keysRead, options) {
     // without `TraceEntry.readKeys` (the writeProvenance dial off) fall back
     // to stage-level expansion per node, byte-identically. Consumers can force
     // 'stage' via options.
-    const root = (0, backtrack_js_1.causalChain)(commitLog, writer.runtimeStageId, source.lookup, {
+    // Preserve this exact writer's metadata/read prefix, even when it is a
+    // continuation. Causal expansion separately uses the execution's first commit.
+    const root = (0, backtrack_js_1.causalChainFromCommit)(commitLog, writer, source.lookup, {
         ...options,
         edgeAttribution: options?.edgeAttribution ?? 'per-write',
         rootLinkKeys: options?.rootLinkKeys ?? [normalisedKey],

package/dist/types/lib/memory/backtrack.d.ts

@@ -257,6 +257,12 @@ export type KeysReadLookup = (runtimeStageId: string) => string[];
  * @returns Root CausalNode with .parents forming the DAG, or undefined if startId not found
  */
 export declare function causalChain(commitLog: CommitBundle[], startId: string, getKeysRead: KeysReadLookup, options?: CausalChainOptions): CausalNode | undefined;
+/**
+ * Internal slice composition: keep the actual bundle selected by the writer
+ * query (including a nonempty continuation). This is not a public entry point.
+ * The read position still belongs to the execution's first commit.
+ */
+export declare function causalChainFromCommit(commitLog: CommitBundle[], writer: CommitBundle, getKeysRead: KeysReadLookup, options?: CausalChainOptions): CausalNode | undefined;
 /**
  * Flatten the causal DAG into a BFS-ordered list of nodes.
  * Each node appears exactly once (first occurrence by BFS order).

package/dist/types/lib/slice/keysReadSources.d.ts

@@ -9,7 +9,6 @@
  * the call site instead: `(id) => recorder.getByKey(id)?.keysRead ?? []`.
  */
 import type { KeysReadLookup } from '../memory/backtrack.js';
-import type { ExecutionTree } from '../memory/types.js';
 import type { KeysReadSource } from './types.js';
 /**
  * Post-hoc reads from a finished run's execution tree — ZERO setup.
@@ -36,8 +35,17 @@ import type { KeysReadSource } from './types.js';
  * 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.
+ *
+ * A live {@link ExecutionTree} or unknown saved JSON uses this same traversal.
+ * Malformed reader fields throw a TypeError naming their source path; no partial
+ * reads strategy is returned. Optional fields may be absent or undefined, but
+ * null nodes, sparse arrays and wrongly shaped fields are not missing evidence
+ * to silently skip. Only read-map KEYS are inspected, never their stored values.
+ * Cycles/shared objects are visited once; existing traversal order is retained.
+ * Coverage counts observed nodes and nonempty read sets, not capture completeness.
+ * This is an ordinary-data boundary, not a sandbox for hostile proxies/accessors.
  */
-export declare function keysReadFromExecutionTree(tree: ExecutionTree | readonly ExecutionTree[]): KeysReadSource;
+export declare function keysReadFromExecutionTree(tree: unknown): KeysReadSource;
 /**
  * Reads from a prebuilt map — e.g. collected live from
  * `ScopeRecorder.onRead` events, or deserialized from a stored trace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foottrace",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "commonjs",
   "description": "Execution records, replay, time travel and honest attribution — independent of the engine that produced them",
   "license": "MIT",