foottrace 1.0.1 → 1.0.3

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/time-travel/bundles.d.ts

@@ -41,6 +41,10 @@ export declare function readTree(value: unknown): ExecutionTree | undefined;
  *   `changedSince` reads its paths), so a row without one is not a bundle the
  *   fold can survive — it is the crash a gap exists to prevent. `CommitBundle`
  *   declares it required, so no live log is affected.
+ * - Each trace entry needs a known verb and a string `path`. Readers use
+ *   string path operations; accepting a number can silently lose a causal
+ *   writer in a short log and crash the indexed lookup in a longer one.
+ *   Empty strings and historical path spellings remain valid strings.
  * - `updates` / `overwrite`, when present, must be plain objects. They are
  *   read only AT THE PATHS THE TRACE NAMES, so an absent one is harmless and
  *   is tolerated, exactly as the fold tolerates an absent `redactedPaths`.

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

@@ -63,6 +63,10 @@ export function readTree(value) {
  *   `changedSince` reads its paths), so a row without one is not a bundle the
  *   fold can survive — it is the crash a gap exists to prevent. `CommitBundle`
  *   declares it required, so no live log is affected.
+ * - Each trace entry needs a known verb and a string `path`. Readers use
+ *   string path operations; accepting a number can silently lose a causal
+ *   writer in a short log and crash the indexed lookup in a longer one.
+ *   Empty strings and historical path spellings remain valid strings.
  * - `updates` / `overwrite`, when present, must be plain objects. They are
  *   read only AT THE PATHS THE TRACE NAMES, so an absent one is harmless and
  *   is tolerated, exactly as the fold tolerates an absent `redactedPaths`.
@@ -95,6 +99,11 @@ export function bundleRefusal(row) {
         if (!isVerb(verb)) {
             return `trace[${i}].verb is ${verb === undefined ? 'missing' : JSON.stringify(verb)}, not ${VERBS.join(' | ')}`;
         }
+        const path = isPlainish(entry) ? entry.path : undefined;
+        if (typeof path !== 'string') {
+            const kind = path === undefined ? 'missing' : path === null ? 'null' : Array.isArray(path) ? 'an array' : `a ${typeof path}`;
+            return `trace[${i}].path is ${kind}, not a string`;
+        }
     }
     return undefined;
 }

package/dist/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/time-travel/bundles.js

@@ -68,6 +68,10 @@ exports.readTree = readTree;
  *   `changedSince` reads its paths), so a row without one is not a bundle the
  *   fold can survive — it is the crash a gap exists to prevent. `CommitBundle`
  *   declares it required, so no live log is affected.
+ * - Each trace entry needs a known verb and a string `path`. Readers use
+ *   string path operations; accepting a number can silently lose a causal
+ *   writer in a short log and crash the indexed lookup in a longer one.
+ *   Empty strings and historical path spellings remain valid strings.
  * - `updates` / `overwrite`, when present, must be plain objects. They are
  *   read only AT THE PATHS THE TRACE NAMES, so an absent one is harmless and
  *   is tolerated, exactly as the fold tolerates an absent `redactedPaths`.
@@ -100,6 +104,11 @@ function bundleRefusal(row) {
         if (!(0, verbs_js_1.isVerb)(verb)) {
             return `trace[${i}].verb is ${verb === undefined ? 'missing' : JSON.stringify(verb)}, not ${verbs_js_1.VERBS.join(' | ')}`;
         }
+        const path = isPlainish(entry) ? entry.path : undefined;
+        if (typeof path !== 'string') {
+            const kind = path === undefined ? 'missing' : path === null ? 'null' : Array.isArray(path) ? 'an array' : `a ${typeof path}`;
+            return `trace[${i}].path is ${kind}, not a string`;
+        }
     }
     return undefined;
 }

package/dist/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/dist/types/lib/time-travel/bundles.d.ts

@@ -41,6 +41,10 @@ export declare function readTree(value: unknown): ExecutionTree | undefined;
  *   `changedSince` reads its paths), so a row without one is not a bundle the
  *   fold can survive — it is the crash a gap exists to prevent. `CommitBundle`
  *   declares it required, so no live log is affected.
+ * - Each trace entry needs a known verb and a string `path`. Readers use
+ *   string path operations; accepting a number can silently lose a causal
+ *   writer in a short log and crash the indexed lookup in a longer one.
+ *   Empty strings and historical path spellings remain valid strings.
  * - `updates` / `overwrite`, when present, must be plain objects. They are
  *   read only AT THE PATHS THE TRACE NAMES, so an absent one is harmless and
  *   is tolerated, exactly as the fold tolerates an absent `redactedPaths`.

package/package.json

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