foottrace 1.0.3 → 1.2.0

package/README.md

@@ -6,15 +6,16 @@ This package extracts FootPrint's established record layer. It does not introduc
 
 Foottrace owns the record layer used by footprintjs 10. Older stored records remain readable without installing their original engine.
 
-## Three entry points
+## Four entry points
 
 | Import | Responsibility |
 | --- | --- |
-| `foottrace` | Record types, runtime IDs, replay, time-travel cursors, causal and variable slices, honesty codes |
-| `foottrace/write` | `SharedMemory`, `EventLog`, `RecordFrame`, encoding and write types, writer-owned freezing |
+| `foottrace` | Record types, runtime and attempt IDs, replay, time-travel cursors, causal and variable slices, honesty codes, the stored-record reader |
+| `foottrace/write` | `SharedMemory`, `EventLog`, `RecordFrame`, encoding and write types, writer-owned freezing, the record sink port and `memorySink` |
 | `foottrace/paths` | Record-path encoding/decoding, nested access and safe diagnostic writes |
+| `foottrace/cause` (ESM) | Optional bounded attention, cause and impact queries; in-memory and lazily loaded stored-record adapters |
 
-Every declaration has one public entry point. There are no public deep imports or `/testing` entry point. FootPrint's engine, observer channels, recorders and stores remain in `footprintjs`.
+Every declaration has one public entry point. Producer-facing `Attention` and `AttentionKind` are type-only root exports; the cause algorithms live only on `/cause`. Existing root, `/write` and `/paths` imports retain their ESM and CommonJS doors. There are no public deep imports or `/testing` entry point. FootPrint's engine, observer channels, recorders and stores remain in `footprintjs`.
 
 ## Write and replay
 
@@ -42,6 +43,45 @@ Writers record during execution. Readers query what was recorded; they do not re
 
 See the [record contract](docs/guides/record-contract.md), [time-travel contract](src/lib/time-travel/README.md), and [slice contract](src/lib/slice/README.md).
 
+## A record that survives the run
+
+A log can also hand every entry to a sink **as it lands**, so a run that is killed still leaves its record behind. The sink sees four entries — `opened` (the base), `commit` (each bundle, after it is frozen), `note` (anything the writer wants kept beside the log, as it happens) and `closed` (how the log ended) — and `memorySink` is the reference adapter. Write your own for a file, a bucket or a table by implementing those four methods.
+
+```ts
+import { readStoredRecord, timeTravel } from 'foottrace';
+import { EventLog, RecordFrame, SharedMemory, memorySink } from 'foottrace/write';
+
+const sink = memorySink();
+const state = new SharedMemory(undefined, { count: 0 });
+const log = new EventLog(state.getState(), { sink, address: { logRunId: 'run-1', drillPath: [] } });
+const frame = new RecordFrame(state, log);
+frame.write(frame.at([], 'count'), 1, 'set');
+frame.commit(() => ({ stage: 'Increment', stageId: 'increment', runtimeStageId: 'increment#0' }));
+log.note('attempt', { attempt: 1, outcome: 'timeout' });
+// … the process dies here: no log.close('ok') …
+
+const run = readStoredRecord(sink.entries).root('run-1')!;
+run.complete; // false — the log never closed
+run.notes; // [{ kind: 'attempt', at, data: { attempt: 1, outcome: 'timeout' } }]
+timeTravel(run.source()).last(); // the cursor over what landed
+```
+
+A failing sink never stops the writer: a throw or a rejected promise is counted (`log.sinkFailures`) and reported to `sink.onFailure`. The reader treats what storage gives back as untrusted (`Iterable<unknown>`) and checks each entry: one it does not read into a log is listed in `unread` by name, and a commit sits at its own index, so a commit the store lost is a gap the fold reports by index — never a shifted log. `complete` means the writer closed the log and the reader read it all. Its work is bounded by four documented limits (`StoredRecordLimits`, raised per call). A sink adds nothing to the log's bytes; `meta` and a note's data are opaque, stored and handed back, never read. See [time travel](src/lib/time-travel/README.md#6-a-stored-record-reads-back--even-a-run-that-never-ended-110) and the [record contract](docs/guides/record-contract.md#a-stored-record).
+
+## Attempt IDs
+
+An attempt under a stage execution has its own ID: `charge#4@2` is attempt 2 of `charge#4`, and `charge#4@2.1@3` is attempt 3 of the first call that stage attempt made. Counts start at 1.
+
+```ts
+import { buildAttemptId, parseAttemptId } from 'foottrace';
+
+buildAttemptId('charge#4', 2, { ordinal: 1, attempt: 3 }); // 'charge#4@2.1@3'
+parseAttemptId('charge#4@2'); // { runtimeStageId: 'charge#4', attempt: 2 }
+parseAttemptId('charge#4'); // undefined — a stage execution, not an attempt
+```
+
+The parser reads from the right, so a stage ID may contain `@` or `.` and no character is newly reserved. See [ids/](src/lib/ids/README.md#attempt-ids-110).
+
 ## Paths are not interchangeable
 
 - `idPathSegments` (root entry) splits runtime IDs on `/` and drops empty segments. `isExecutionKey` detects `#`; it is not a complete validator.
@@ -72,3 +112,96 @@ No engine is installed in this package's test environment. Engine integration an
 Record bytes are part of the versioning promise: refactors never re-pin; a named law fix requires a documented minor release; any other byte change requires a major. See the [fixture policy](test/fixtures/README.md).
 
 MIT license. Contact: sanjay@footprintjs.dev.
+
+
+## Cause and impact — 1.2.0 candidate
+
+`foottrace/cause` reads recorded dependencies; it never reruns business code, calls a model, or accesses storage by itself. An application supplies a graph or a stored-record host. `explain(graph, nodeId)` walks the selected node's recorded data and control dependencies, identifies the earliest marked ancestors in that dependency order, and walks forward to report impact. Independent candidates remain `alternatives`; timestamps and ID order never break a causal tie. A missing or cut backward dependency withholds `rootCause`; missing evidence in either direction returns `confidence: 'incomplete'` with fixed gap codes. Confidence describes evidence coverage, not proof of a provider's internal failure.
+
+**For precise per-write cause queries, enable `writeProvenance: 'reads-prefix'` when recording the flow.** Step-level data edges can add false ancestors; the record adapter marks that fallback `conservative`, so those queries return incomplete evidence and alternatives rather than a definite root. This setting cannot restore provenance in old records and does not guarantee a root: complete recorded read/control and attention coverage, one supported candidate and no backward gaps are still required. Other graph adapters can provide their own precise dependency evidence.
+
+**Module compatibility:** `/cause` has an `import` export condition only. CommonJS consumers must use native `import('foottrace/cause')`; `require('foottrace/cause')` is not exported, even on Node versions that support requiring ESM. Preserve native `import()` in the compiled CommonJS loader: compilers that rewrite it to `require()` need a dedicated import-preserving bridge. Existing root, `/write` and `/paths` CommonJS imports remain supported.
+
+```ts
+import type { Attention } from 'foottrace';
+import { attentionList, explain, type CauseGraph } from 'foottrace/cause';
+
+// The host owns authentication, storage, graph identities and attention rules.
+// Each method receives a cancellation signal and may load only the requested node.
+declare const graph: CauseGraph;
+declare const selectedNodeId: string;
+const marked = await attentionList(graph, {
+  nodeIds: [selectedNodeId], maxNodes: 50, maxCalls: 100, timeoutMs: 500,
+});
+const finding = await explain(graph, selectedNodeId, {
+  maxNodes: 50, maxDepth: 10, maxEdges: 100, maxCalls: 200, timeoutMs: 500,
+});
+// Display finding.attention, rootCause or alternatives, path, impact and gaps.
+// An LLM can phrase these validated findings without inventing a cause.
+```
+
+Attention marks contain a fixed reason code and evidence references, never a raw error or state value. Every mark needs a proof reference except `not-collected`, which records absence. The application decides which business conditions deserve a mark. `error`, `unknown-effect`, `gave-up`, `timeout`, `retried`, `quality-drop`, `not-collected` and `outlier` are standard kinds; future bounded kind names remain readable. An absent mark does not prove a node was healthy. `largestDrop(scores)` and `mostAffected(scores)` return optional root strategies over host-supplied, already recorded numeric scores; equal best scores remain tied and missing scores become gaps. The default uses the earliest marked ancestor, with no scoring model. An optional `rankImpact(nodes, context)` may reorder the discovered descendants, but cannot add, omit or duplicate references; failed ranking preserves the unranked references and reports a gap.
+
+The default earliest-ancestor rule does not restrict a custom `rankRoots`: that callback receives all supported marked nodes in the backward walk, including a marked selected node, and may select a subset containing a nearer ancestor. It cannot introduce foreign or duplicate identities. This differs from `rankImpact`, which must return an exact permutation of every discovered descendant. Name the chosen root strategy when presenting its findings; a custom choice is not the default earliest-ancestor conclusion.
+
+Query defaults are 100 nodes, depth 20, 1,000 edges, 1,000 calls and one second. Hard ceilings are 10,000 nodes, depth 1,000, 100,000 edges/calls and 30 seconds. The same budget covers both directions and ranking. Callbacks are trusted executable code: asynchronous waiting is bounded and receives an abort signal, while synchronous callbacks must cooperate. A late synchronous result is rejected after it returns. Hosts must use non-secret node and evidence IDs; the reader does not classify arbitrary ID strings for personal information.
+
+Async hosts must return ordinary current-realm native Promises with no own `constructor`; promise wrappers are trusted host control objects, while their resolved data is untrusted. Custom thenables, subclasses and constructor/species overrides are outside this contract and the host must handle their rejections itself. The reader never mutates a promise to observe it. Ordinary native rejections are consumed and become fixed gaps; synchronous data objects' `then` accessors are never invoked.
+
+### Per-write provenance recipe
+
+For precise edges between individual writes, configure the producer's record encoding with `writeProvenance: 'reads-prefix'`. `RecordFrame` captures the reads that preceded each write. For an execution that reads `a`, writes `x`, then reads `b` and writes `y`, the `x` query uses its recorded read prefix; the `y` query uses the later prefix. Without per-write provenance, the reader must conservatively consider all reads of that stage for either value and report that fallback. Later reads cannot be retroactively assigned to an earlier write. An overwritten version is distinct from the newer value, so impact follows the selected write rather than every later use of the same key name.
+
+```ts
+import { EventLog, RecordFrame, SharedMemory } from 'foottrace/write';
+const state = new SharedMemory(undefined, { a: 1, b: 2 });
+const log = new EventLog(state.getState());
+const frame = new RecordFrame(state, log);
+frame.useEncoding({ commitValues: 'full', writeProvenance: 'reads-prefix' });
+frame.noteRead([], 'a');
+frame.write(frame.at([], 'x'), 1, 'set');
+frame.noteRead([], 'b');
+frame.write(frame.at([], 'y'), 3, 'set');
+frame.commit(() => ({ stage: 'Derive', stageId: 'derive', runtimeStageId: 'derive#0' }));
+frame.release();
+```
+
+A stored host can expose one authorized log at a time:
+
+```ts
+import { createStoredRecordGraph, explain, type StoredRecordHost } from 'foottrace/cause';
+
+// loadLog(address, { signal }) returns native entries for exactly that address,
+// plus recorded read/control/attention maps when available. It checks access.
+declare const host: StoredRecordHost;
+const graph = createStoredRecordGraph(host, {
+  maxScopes: 8, maxCommits: 256, maxFields: 20_000, maxEdges: 64, loadTimeoutMs: 500,
+});
+const address = { logRunId: 'run-1', drillPath: [] };
+const selected = graph.nodeId(address, { runtimeStageId: 'derive#0', commitIdx: 0, key: 'y' });
+const finding = await explain(graph, selected, { timeoutMs: 750, maxNodes: 50 });
+// Only the requested scope is loaded; a different subflow is opened on demand.
+```
+
+The stored adapter loads a requested log through the host, reuses `readStoredRecord`, and retains incomplete-record and gap evidence. A graph instance caches admitted scope snapshots; create a new instance to refresh a record that is still being written. Bind each host/graph/cache to one authorization domain or authorize before every query: a cache hit does not call `loadLog` again. Never share a global graph whose loader consults a changing request identity. Subflow containment is a navigation relationship, not automatically a causal dependency. Scope, execution, write position and optional key qualify node identities. The host must authorize each storage scope; cross-service and cross-run causal stitching remain outside this candidate. Lazy loading is real only when the host loader fetches a requested scope: expanding a cursor over an already loaded snapshot is an in-memory drill.
+
+### Established algorithms
+
+Foundations: [Weiser, *Program slicing* (1981)](https://dl.acm.org/doi/10.5555/800078.802557), [Korel and Laski, *Dynamic program slicing* (1988)](https://doi.org/10.1016/0020-0190(88)90054-3), [Agrawal and Horgan, *Dynamic program slicing* (1990)](https://doi.org/10.1145/93542.93576), [Ferrante, Ottenstein and Warren, *The program dependence graph and its use in optimization* (1987)](https://doi.org/10.1145/24039.24041), and [Buneman, Khanna and Tan, *Why and Where: A Characterization of Data Provenance* (2001)](https://www.pure.ed.ac.uk/ws/files/16509989/Why_and_Where_A_Characterization_of_Data_Provenance.pdf). These are the historical techniques; this reader applies them only to dependencies present in a recording.
+
+| Query | Established name |
+| --- | --- |
+| Recorded ancestors influencing a value or node | **Backward dynamic program slicing** (Weiser, 1981; Korel and Laski, 1988; Agrawal and Horgan, 1990) |
+| Recorded data plus decision/control edges | **Program dependence graph** (Ferrante, Ottenstein and Warren, 1987) |
+| Recorded downstream effects | **Forward slicing**, or change-impact analysis |
+| Why a value exists and where it came from | **Why- and where-provenance** (Buneman, Khanna and Tan, 2001) |
+| Loading only queried graph nodes/scopes | **Demand-driven, or lazy, graph traversal** |
+| Default candidate selection | **Root-cause localisation on a dependency DAG**, using the earliest anomalous ancestor |
+
+These names describe the techniques, not a claim of complete language-level instrumentation. Findings are bounded by the dependencies the producer recorded. Cause queries share one deadline and node/edge/call budget across reverse traversal, ranking and forward impact; limits, cancellation and unavailable reads become gaps. Output carries references and fixed codes, never a serialized DAG or business payload. `/cause` is ESM-only and `sideEffects: false`; its unused-import browser bundle is tested to match a bundle without the import. The package has no runtime dependencies. This is an unpublished candidate; later engine stamping, viewer integration and agent tools are separate changes.
+
+Direct `graph.openScope(address, { signal })` discovery rejects with a fixed `cause: record unavailable` error and a gap `code` on failure; an unavailable scope is never reported as an empty successful log. Public `explain` and `attentionList` queries turn unavailable reads into bounded incomplete findings.
+
+Record-adapter coverage is conservative: its shared scope gaps can withhold a cause when a local forward edge cap is reached, even if the visible backward path is covered. A withheld cause is unknown under those bounds; it is not proof that no cause exists.
+
+Package verification retains strict automatic entrypoint discovery for every door except `/cause`, then checks only `/cause` with Are the Types Wrong’s `esm-only` profile. No resolution error is ignored globally; the regression test fixes that exception to this one ESM-only subpath.

package/dist/cause.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStoredRecordGraph = exports.createRecordGraph = exports.mostAffected = exports.largestDrop = exports.attentionList = exports.explain = void 0;
+/** Optional read-only cause and impact queries over recorded dependency graphs. */
+var explain_js_1 = require("./lib/cause/explain.js");
+Object.defineProperty(exports, "explain", { enumerable: true, get: function () { return explain_js_1.explain; } });
+Object.defineProperty(exports, "attentionList", { enumerable: true, get: function () { return explain_js_1.attentionList; } });
+var strategies_js_1 = require("./lib/cause/strategies.js");
+Object.defineProperty(exports, "largestDrop", { enumerable: true, get: function () { return strategies_js_1.largestDrop; } });
+Object.defineProperty(exports, "mostAffected", { enumerable: true, get: function () { return strategies_js_1.mostAffected; } });
+var recordAdapter_js_1 = require("./lib/cause/recordAdapter.js");
+Object.defineProperty(exports, "createRecordGraph", { enumerable: true, get: function () { return recordAdapter_js_1.createRecordGraph; } });
+var storedRecordAdapter_js_1 = require("./lib/cause/storedRecordAdapter.js");
+Object.defineProperty(exports, "createStoredRecordGraph", { enumerable: true, get: function () { return storedRecordAdapter_js_1.createStoredRecordGraph; } });

package/dist/esm/cause.d.ts

@@ -0,0 +1,8 @@
+/** Optional read-only cause and impact queries over recorded dependency graphs. */
+export { explain, attentionList } from './lib/cause/explain.js';
+export { largestDrop, mostAffected } from './lib/cause/strategies.js';
+export { createRecordGraph } from './lib/cause/recordAdapter.js';
+export { createStoredRecordGraph } from './lib/cause/storedRecordAdapter.js';
+export type { Adjacency, AttentionListOptions, AttentionListResult, AttentionReason, CauseGraph, CauseResult, Confidence, ExplainOptions, Gap, GapCode, GraphContext, GraphEdge, ImpactResult, ImpactStrategy, MarkedNode, MaybePromise, NodeId, RootStrategy, TraversedEdge, WalkLimits, } from './lib/cause/types.js';
+export type { RecordScope, RecordGraphOptions, RecordCauseGraph, RecordNode } from './lib/cause/recordAdapter.js';
+export type { StoredRecordScope, StoredRecordHost } from './lib/cause/storedRecordAdapter.js';

package/dist/esm/cause.js

@@ -0,0 +1,5 @@
+/** Optional read-only cause and impact queries over recorded dependency graphs. */
+export { explain, attentionList } from './lib/cause/explain.js';
+export { largestDrop, mostAffected } from './lib/cause/strategies.js';
+export { createRecordGraph } from './lib/cause/recordAdapter.js';
+export { createStoredRecordGraph } from './lib/cause/storedRecordAdapter.js';

package/dist/esm/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';
@@ -25,3 +28,5 @@ export type { EmitSourcePosition, LogAddress } from './lib/memory/eventPosition.
 export { EXECUTION_DELIMITER, PATH_DELIMITER, isExecutionKey, joinPath, pathSegments as idPathSegments, stageIdOf, subflowSegmentsOf, } from './lib/ids/runtimeStageId.js';
 export { deepEqual } from './lib/memory/equality.js';
 export { serveRecord } from './lib/capture/freeze.js';
+/** Record attention types are shared with producers; the optional cause reader has its own door. */
+export type { Attention, AttentionKind } from './lib/cause/types.js';

package/dist/esm/index.js

@@ -1,8 +1,9 @@
 export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId, splitStageId, } from './lib/ids/runtimeStageId.js';
+export { buildAttemptId, parseAttemptId } from './lib/ids/attemptId.js';
 export { UnknownVerbError } from './lib/memory/verbs.js';
 export { applySmartMerge } from './lib/memory/verbs.js';
 export { buildCommitIndex, commitIndexOf, commitValueAt, commitValueAtWithBasis, findCommit, findCommits, findLastWriter, findLastWriterWithBasis, inferLegacyPhases, recordsPhases, } from './lib/memory/commitLogUtils.js';
-export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
+export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, readStoredRecord, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
 export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';
 export { arrayProvenance, elementProvenance, formatForwardSlice, formatSlice, formatTimeline, forwardSliceForKey, forwardSliceToJSON, keysReadFromExecutionTree, keysReadFromMap, keyTimeline, resolveKeysReadSource, sliceForKey, sliceToJSON, } from './lib/slice/index.js';
 export { HONESTY_CODES } from './lib/memory/honesty.js';

package/dist/esm/lib/cause/admission.d.ts

@@ -0,0 +1,27 @@
+import type { GapCode } from './types.js';
+/** One refusal representation; subclasses preserve the graph-port and record-loader boundaries. */
+export declare class EvidenceRefusal extends Error {
+    readonly code: GapCode;
+    constructor(code: GapCode, message: string);
+}
+export type RefuseEvidence = (code?: GapCode) => Error;
+interface DescriptorPolicy {
+    readonly translateTrapErrors: boolean;
+    readonly requireOwnValue: boolean;
+}
+/** Read data descriptors only; each boundary keeps its existing treatment of proxy traps. */
+export declare function ownData(value: unknown, key: string, refuse: RefuseEvidence, policy: DescriptorPolicy): unknown;
+/** Names share one grammar, with explicit limits and the record path separator exception. */
+export declare function boundedName(value: unknown, maximum: number, refuse: RefuseEvidence, path?: boolean): string;
+/** Bound iteration before reading entries, without invoking element accessors. */
+export declare function boundedList<T>(value: unknown, maximum: number, read: (item: unknown) => T, options: {
+    readonly refuse: RefuseEvidence;
+    readonly overflow: GapCode;
+    readonly freeze: boolean;
+    readonly descriptors: DescriptorPolicy;
+}): readonly T[];
+/** Charge retained fields against the same mutable allowance across admission helpers. */
+export declare function spendFields(budget: {
+    left: number;
+}, count: number, refuse: RefuseEvidence): void;
+export {};

package/dist/esm/lib/cause/admission.js

@@ -0,0 +1,59 @@
+/** One refusal representation; subclasses preserve the graph-port and record-loader boundaries. */
+export class EvidenceRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Read data descriptors only; each boundary keeps its existing treatment of proxy traps. */
+export function ownData(value, key, refuse, policy) {
+    if (!value || typeof value !== 'object')
+        throw refuse();
+    let descriptor;
+    if (policy.translateTrapErrors) {
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(value, key);
+        }
+        catch {
+            throw refuse();
+        }
+    }
+    else
+        descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor)
+        return undefined;
+    if (policy.requireOwnValue ? !Object.hasOwn(descriptor, 'value') : !('value' in descriptor))
+        throw refuse();
+    return descriptor.value;
+}
+/** Names share one grammar, with explicit limits and the record path separator exception. */
+export function boundedName(value, maximum, refuse, path = false) {
+    if (typeof value !== 'string' ||
+        !value.length ||
+        value.length > maximum ||
+        (path ? /[\u0000-\u001e\u007f-\u009f]/ : /[\u0000-\u001f\u007f-\u009f]/).test(value))
+        throw refuse();
+    return value;
+}
+/** Bound iteration before reading entries, without invoking element accessors. */
+export function boundedList(value, maximum, read, options) {
+    const { refuse, overflow, freeze, descriptors } = options;
+    if (!Array.isArray(value))
+        throw refuse();
+    const length = ownData(value, 'length', refuse, descriptors);
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+        throw refuse();
+    if (length > maximum)
+        throw refuse(overflow);
+    const result = [];
+    for (let index = 0; index < length; index++)
+        result.push(read(ownData(value, String(index), refuse, descriptors)));
+    return freeze ? Object.freeze(result) : result;
+}
+/** Charge retained fields against the same mutable allowance across admission helpers. */
+export function spendFields(budget, count, refuse) {
+    budget.left -= count;
+    if (budget.left < 0)
+        throw refuse('node-limit');
+}

package/dist/esm/lib/cause/explain.d.ts

@@ -0,0 +1,5 @@
+import type { AttentionListOptions, AttentionListResult, CauseGraph, CauseResult, ExplainOptions, NodeId } from './types.js';
+/** Read-only deterministic cause localisation and impact. No inference from timestamps or structural ancestry. */
+export declare function explain(graph: CauseGraph, nodeId: NodeId, options?: ExplainOptions): Promise<CauseResult>;
+/** Discover only bounded host seeds; this is not a global scan of arbitrary storage. */
+export declare function attentionList(graph: CauseGraph, options?: AttentionListOptions): Promise<AttentionListResult>;

package/dist/esm/lib/cause/explain.js

@@ -0,0 +1,114 @@
+import { Session } from './session.js';
+import { frontier, pathTo, walk } from './walk.js';
+import { gap, name, nodeIds, own, uniqueGaps } from './validation.js';
+import { admitRanking } from './ranking.js';
+/** Read-only deterministic cause localisation and impact. No inference from timestamps or structural ancestry. */
+export async function explain(graph, nodeId, options = {}) {
+    name(nodeId);
+    const session = new Session(graph, options);
+    try {
+        const backward = await walk(session, [nodeId], 'parents');
+        const missing = [...backward.gaps];
+        let candidates = frontier(backward).map((item) => item.nodeId);
+        const rank = own(options, 'rankRoots');
+        if (rank !== undefined) {
+            if (typeof rank !== 'function')
+                throw new TypeError('CAUSE_CONFIGURATION_INVALID');
+            const eligible = backward.marked.filter((item) => item.attention.some((mark) => mark.kind !== 'not-collected'));
+            const selection = await session.invoke(undefined, () => rank(Object.freeze(eligible), session.context), (raw) => admitRanking(raw, new Set(eligible.map((item) => item.nodeId)), {
+                exactPermutation: false,
+                maximum: session.limits.maxNodes,
+            }));
+            if (selection.gap)
+                missing.push(selection.gap, gap('strategy-failed'));
+            else
+                candidates = [...(selection.value ?? [])];
+        }
+        const stopped = session.stopGap(nodeId);
+        if (stopped)
+            missing.push(stopped);
+        const causeComplete = missing.length === 0;
+        const rootCause = causeComplete && candidates.length === 1 ? candidates[0] : undefined;
+        const forward = await walk(session, [nodeId], 'children');
+        let impactNodes = Object.freeze(forward.nodes.filter((id) => id !== nodeId));
+        const impactGaps = [...forward.gaps], rankImpact = own(options, 'rankImpact');
+        if (typeof rankImpact === 'function') {
+            const selection = await session.invoke(undefined, () => rankImpact(impactNodes, session.context), (raw) => admitRanking(raw, new Set(impactNodes), {
+                exactPermutation: true,
+                maximum: session.limits.maxNodes,
+            }));
+            if (selection.gap)
+                impactGaps.push(selection.gap, gap('strategy-failed'));
+            else
+                impactNodes = selection.value ?? impactNodes;
+        }
+        const impact = Object.freeze({
+            nodes: impactNodes,
+            edges: forward.edges,
+            confidence: impactGaps.length ? 'incomplete' : 'complete',
+            gaps: uniqueGaps(impactGaps),
+        });
+        const allGaps = uniqueGaps([...missing, ...impactGaps]);
+        return Object.freeze({
+            nodeId,
+            attention: backward.marked.find((item) => item.nodeId === nodeId)?.attention ?? Object.freeze([]),
+            ...(rootCause ? { rootCause } : {}),
+            path: rootCause ? pathTo(backward.edges, nodeId, rootCause) : Object.freeze([]),
+            alternatives: Object.freeze(rootCause ? [] : candidates),
+            impact,
+            confidence: allGaps.length ? 'incomplete' : 'complete',
+            gaps: allGaps,
+        });
+    }
+    finally {
+        session.dispose();
+    }
+}
+/** Discover only bounded host seeds; this is not a global scan of arbitrary storage. */
+export async function attentionList(graph, options = {}) {
+    const session = new Session(graph, options);
+    try {
+        let seeds = [], missing = [];
+        const requested = own(options, 'nodeIds');
+        const admitSeeds = (raw) => {
+            // Only inspect the bounded prefix; the unread tail is explicitly incomplete.
+            if (!Array.isArray(raw))
+                return nodeIds(raw, session.limits.maxNodes);
+            const length = own(raw, 'length');
+            if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+                return nodeIds(raw, session.limits.maxNodes);
+            if (length > session.limits.maxNodes)
+                missing.push(gap('node-limit'));
+            const prefix = [];
+            for (let i = 0; i < Math.min(length, session.limits.maxNodes); i++)
+                prefix.push(own(raw, String(i)));
+            return nodeIds(prefix, session.limits.maxNodes);
+        };
+        if (requested !== undefined) {
+            const read = await session.invoke(undefined, () => requested, admitSeeds);
+            if (read.gap)
+                missing.push(read.gap);
+            else
+                seeds = read.value ?? [];
+        }
+        else if (session.hasRoots()) {
+            const read = await session.read('roots', undefined, admitSeeds);
+            if (read.gap)
+                missing.push(read.gap);
+            else
+                seeds = read.value ?? [];
+        }
+        else
+            missing.push(gap('not-collected'));
+        const result = await walk(session, seeds, 'children');
+        missing = [...missing, ...result.gaps];
+        return Object.freeze({
+            nodes: result.marked,
+            confidence: missing.length ? 'incomplete' : 'complete',
+            gaps: uniqueGaps(missing),
+        });
+    }
+    finally {
+        session.dispose();
+    }
+}

package/dist/esm/lib/cause/ranking.d.ts

@@ -0,0 +1,6 @@
+import type { NodeId } from './types.js';
+/** Strategies may only select admitted nodes; impact ranking must preserve the full set. */
+export declare function admitRanking(raw: unknown, allowed: ReadonlySet<NodeId>, options: {
+    readonly exactPermutation: boolean;
+    readonly maximum: number;
+}): readonly NodeId[];

package/dist/esm/lib/cause/ranking.js

@@ -0,0 +1,10 @@
+import { nodeIds } from './validation.js';
+/** Strategies may only select admitted nodes; impact ranking must preserve the full set. */
+export function admitRanking(raw, allowed, options) {
+    const ids = nodeIds(raw, options.maximum);
+    if ((options.exactPermutation && ids.length !== allowed.size) ||
+        new Set(ids).size !== ids.length ||
+        ids.some((id) => !allowed.has(id)))
+        throw new TypeError();
+    return ids;
+}

package/dist/esm/lib/cause/recordAdapter.d.ts

@@ -0,0 +1,9 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { RecordCauseGraph, RecordGraphOptions, RecordLoaderResult, RecordScope } from './recordTypes.js';
+import type { GraphContext } from './types.js';
+export type { RecordCauseGraph, RecordGraphOptions, RecordLoaderResult, RecordNode, RecordScope, } from './recordTypes.js';
+export { recordOptions } from './recordScope.js';
+/** Common engine for memory and one-scope-at-a-time host storage. Loader functions are trusted executable code. */
+export declare function createLazyRecordGraph(load: (address: LogAddress, context: GraphContext) => RecordLoaderResult | Promise<RecordLoaderResult>, options?: RecordGraphOptions): RecordCauseGraph;
+/** A finished record already in memory; payload admission is lazy per requested scope. */
+export declare function createRecordGraph(scopes: readonly RecordScope[], options?: RecordGraphOptions): RecordCauseGraph;

package/dist/esm/lib/cause/recordAdapter.js

@@ -0,0 +1,49 @@
+import { childrenForRecordNode } from './recordChildren.js';
+import { attentionForRecordNode, gapForRecordFailure } from './recordCoverage.js';
+import { nodeIdFor, resolveRecordNode } from './recordIdentity.js';
+import { createRecordScopeLoader, openRecordScope } from './recordLoading.js';
+import { inspectRecordNode } from './recordParents.js';
+import { recordOptions } from './recordScope.js';
+import { addressKey, addressOf, list, own, RecordRefusal } from './recordValidation.js';
+export { recordOptions } from './recordScope.js';
+/** Common engine for memory and one-scope-at-a-time host storage. Loader functions are trusted executable code. */
+export function createLazyRecordGraph(load, options = {}) {
+    const limits = recordOptions(options), loader = createRecordScopeLoader(load, limits);
+    const resolve = (nodeId, context) => resolveRecordNode(nodeId, context, loader);
+    return Object.freeze({
+        nodeId: (address, node) => nodeIdFor(address, node),
+        openScope: (address, context) => openRecordScope(address, context, loader),
+        async parents(nodeId, context) {
+            const node = await resolve(nodeId, context);
+            return 'failure' in node
+                ? { edges: [], complete: false }
+                : inspectRecordNode(node, limits.maxEdges, loader.extraGapCodes(node.scope)).adjacency;
+        },
+        async gaps(nodeId, context) {
+            const node = await resolve(nodeId, context);
+            return 'failure' in node
+                ? gapForRecordFailure(node.failure)
+                : inspectRecordNode(node, limits.maxEdges, loader.extraGapCodes(node.scope)).gaps;
+        },
+        async attention(nodeId, context) {
+            return attentionForRecordNode(await resolve(nodeId, context));
+        },
+        async children(nodeId, context) {
+            const node = await resolve(nodeId, context);
+            return 'failure' in node
+                ? { edges: [], complete: false }
+                : childrenForRecordNode(node, limits.maxEdges, loader.extraGapCodes(node.scope));
+        },
+    });
+}
+/** A finished record already in memory; payload admission is lazy per requested scope. */
+export function createRecordGraph(scopes, options = {}) {
+    const limits = recordOptions(options);
+    return createLazyRecordGraph((address) => {
+        for (const raw of list(scopes, limits.maxScopes)) {
+            if (addressKey(addressOf(own(raw, 'address'))) === addressKey(address))
+                return { scope: raw };
+        }
+        throw new RecordRefusal('unavailable');
+    }, limits);
+}

package/dist/esm/lib/cause/recordChildren.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedRecordNode } from './recordTypes.js';
+import type { Adjacency, Gap } from './types.js';
+/** Share parent-side coverage checks before appending data then control children in their established order. */
+export declare function childrenForRecordNode(node: ResolvedRecordNode, maximumEdges: number, extraGapCodes: readonly Gap['code'][] | undefined): Adjacency;

package/dist/esm/lib/cause/recordChildren.js

@@ -0,0 +1,79 @@
+import { forwardSliceForKey } from '../slice/forwardSliceForKey.js';
+import { appendControlChildren } from './recordControl.js';
+import { allStageReadsCollected, writtenKeysForNode } from './recordCoverage.js';
+import { nodeIdFor } from './recordIdentity.js';
+import { inspectRecordNode } from './recordParents.js';
+import { readKeysForStage } from './recordScope.js';
+/** Keep per-write and conservative fed edges distinct while retaining existing cap and deduplication order. */
+function appendFedChildren(scope, root, maximumEdges, edges) {
+    let complete = true;
+    for (const edge of root.fedEdges) {
+        const child = edge.child;
+        if (child.commitIdx === undefined || !child.runtimeStageId) {
+            complete = false;
+            continue;
+        }
+        if (edges.length >= maximumEdges) {
+            complete = false;
+            break;
+        }
+        const nodeId = nodeIdFor(scope.address, {
+            runtimeStageId: child.runtimeStageId,
+            commitIdx: child.commitIdx,
+            key: child.key,
+        });
+        if (!edges.some((existing) => existing.nodeId === nodeId))
+            edges.push({ nodeId, kind: 'data', attribution: edge.basis, evidence: ['commit:' + child.commitIdx] });
+        if (edge.basis === 'stage')
+            complete = false;
+    }
+    return complete;
+}
+/** A consumer with no writes still needs a qualified node so its recorded control flow remains reachable. */
+function appendReadOnlyChildren(scope, root, key, maximumEdges, edges) {
+    let complete = true;
+    for (const read of root.reads) {
+        if (scope.log[read.commitIdx]?.trace.length)
+            continue;
+        if (edges.length >= maximumEdges) {
+            complete = false;
+            break;
+        }
+        const nodeId = nodeIdFor(scope.address, { runtimeStageId: read.runtimeStageId, commitIdx: read.commitIdx, key }, true);
+        if (!edges.some((existing) => existing.nodeId === nodeId))
+            edges.push({ nodeId, kind: 'data', attribution: 'per-write', evidence: ['commit:' + read.commitIdx] });
+    }
+    return complete;
+}
+/** Query each written value at its original commit boundary instead of the value's latest writer. */
+function appendDataChildren(scope, identity, commitIndex, maximumEdges, edges) {
+    let complete = true;
+    const lookup = (runtimeStageId) => readKeysForStage(scope, runtimeStageId);
+    for (const key of writtenKeysForNode(scope.log[commitIndex], identity)) {
+        const forward = forwardSliceForKey(scope.log, key, lookup, {
+            before: commitIndex + 1,
+            maxDepth: 1,
+            maxNodes: maximumEdges + 1,
+        });
+        if (forward.root?.truncated?.byNodes)
+            complete = false;
+        if (forward.root?.commitIdx !== commitIndex) {
+            complete = false;
+            continue;
+        }
+        complete = appendFedChildren(scope, forward.root, maximumEdges, edges) && complete;
+        complete = appendReadOnlyChildren(scope, forward.root, key, maximumEdges, edges) && complete;
+    }
+    return complete;
+}
+/** Share parent-side coverage checks before appending data then control children in their established order. */
+export function childrenForRecordNode(node, maximumEdges, extraGapCodes) {
+    const { scope, identity, commitIndex } = node;
+    const base = inspectRecordNode(node, maximumEdges, extraGapCodes), edges = [];
+    let complete = base.gaps.length === 0;
+    if (!allStageReadsCollected(scope))
+        complete = false;
+    complete = appendDataChildren(scope, identity, commitIndex, maximumEdges, edges) && complete;
+    complete = appendControlChildren(scope, identity, commitIndex, maximumEdges, edges) && complete;
+    return { edges, complete };
+}