foottrace 1.0.0 → 1.0.1

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/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/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/package.json

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