foottrace 1.1.0 → 1.3.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 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,31 @@ 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).
 
+## Evidence requirements — 1.3.0
+
+`RequirementResult` and `readRequirementResults(unknown)` on the root door carry
+one producer-issued requirement result per finding/window, the claims it
+`affects`, explicit unresolved `RequirementReason` codes, check/evidence/attempt
+references and available action references. Domain details are namespaced IDs;
+raw subjects, payloads, credentials and executable actions do not enter this
+contract. The bounded reader rejects malformed or oversized batches atomically
+and returns detached frozen records. It works through the root ESM and CommonJS
+doors without loading the optional cause reader.
+
+`RequirementReason` is the twelve-code domain-evidence subset of the single
+`GapCode` registry. Result and check reasons refuse trace-walk codes such as
+`cycle` and `node-limit`; generic cause gaps and typed admission errors retain
+their broader vocabulary.
+
+Structural admission never authenticates a producer or establishes that a
+`satisfied` assertion is true. The host verifies current query, run, caller scope,
+artifact provenance and domain validity before rendering each claim. An unresolved
+requirement blocks only its affected conclusions; independently supported facts
+can remain. Valid-time and learned-time references are separate, and missing
+validity is unknown. Action references resolve through a host-owned closed
+registry, with permissions checked again at execution. See the [contract and
+limits](src/lib/evidence/README.md) and [reference-only example](examples/post-execution/time-travel/08-evidence-requirements.ts).
+
 ## 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.
@@ -111,3 +137,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
+
+`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. The cause reader shipped in 1.2.0; 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

@@ -28,3 +28,9 @@ 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';
+/** Reference-only requirement records: structural admission never grants authority or verifies domain truth. */
+export type { RequirementReason } from './lib/evidence/codes.js';
+export type { RequirementCheck, RequirementCheckDisposition, RequirementResult, } from './lib/evidence/requirementTypes.js';
+export { readRequirementResults, RequirementValidationError, REQUIREMENT_RESULT_LIMITS, } from './lib/evidence/requirements.js';

package/dist/esm/index.js

@@ -11,3 +11,4 @@ export { CommitRangeIndex } from './lib/recorder/CommitRangeIndex.js';
 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';
+export { readRequirementResults, RequirementValidationError, REQUIREMENT_RESULT_LIMITS, } from './lib/evidence/requirements.js';

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, graphName, nodeIds, graphOwn, 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 = {}) {
+    graphName(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 = graphOwn(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 = graphOwn(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 = graphOwn(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 = graphOwn(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(graphOwn(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/queryMemo.d.ts

@@ -0,0 +1,18 @@
+import type { GraphContext } from './types.js';
+/** Share bounded derived work within one query without retaining it in the graph's storage cache. */
+declare class QueryMemo {
+    private readonly maximumEntries;
+    private readonly owners;
+    private entries;
+    private closed;
+    constructor(maximumEntries: number);
+    remember<T>(owner: object, key: unknown, create: () => T): T;
+    close(): void;
+}
+/** Reserve one resolution and one inspection per admitted node, shared across all adapter owners. */
+export declare function beginQueryMemo(context: GraphContext, maximumNodes: number): void;
+/** Direct graph calls have no managed query lifetime and deliberately remain uncached. */
+export declare function queryMemo(context: GraphContext): QueryMemo | undefined;
+/** Clear synchronously without aborting an otherwise successful query's public signal. */
+export declare function endQueryMemo(context: GraphContext): void;
+export {};

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

@@ -0,0 +1,46 @@
+/** Share bounded derived work within one query without retaining it in the graph's storage cache. */
+class QueryMemo {
+    maximumEntries;
+    owners = new Map();
+    entries = 0;
+    closed = false;
+    constructor(maximumEntries) {
+        this.maximumEntries = maximumEntries;
+    }
+    remember(owner, key, create) {
+        const previous = this.owners.get(owner);
+        if (previous?.has(key))
+            return previous.get(key);
+        if (this.closed || this.entries >= this.maximumEntries)
+            return create();
+        const value = create();
+        // Creation can finish after disposal or re-enter other readers; neither may refill a closed/full memo.
+        if (!this.closed && this.entries < this.maximumEntries) {
+            const bucket = this.owners.get(owner) ?? new Map();
+            if (!bucket.has(key))
+                this.entries++;
+            bucket.set(key, value);
+            this.owners.set(owner, bucket);
+        }
+        return value;
+    }
+    close() {
+        this.closed = true;
+        this.owners.clear();
+        this.entries = 0;
+    }
+}
+const queries = new WeakMap();
+/** Reserve one resolution and one inspection per admitted node, shared across all adapter owners. */
+export function beginQueryMemo(context, maximumNodes) {
+    queries.set(context, new QueryMemo(maximumNodes * 2));
+}
+/** Direct graph calls have no managed query lifetime and deliberately remain uncached. */
+export function queryMemo(context) {
+    return queries.get(context);
+}
+/** Clear synchronously without aborting an otherwise successful query's public signal. */
+export function endQueryMemo(context) {
+    queries.get(context)?.close();
+    queries.delete(context);
+}

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,42 @@
+import { childrenForRecordNode } from './recordChildren.js';
+import { attentionForRecordNode, gapForRecordFailure } from './recordCoverage.js';
+import { nodeIdFor } from './recordIdentity.js';
+import { createRecordScopeLoader, openRecordScope } from './recordLoading.js';
+import { createRecordQuery, whenResolved } from './recordQuery.js';
+import { recordOptions } from './recordScope.js';
+import { addressKey, addressOf, recordList, recordOwn, RecordRefusal } from './recordValidation.js';
+/** Give each failed port its own incomplete page rather than sharing a mutable edge array. */
+const unavailableAdjacency = () => ({ edges: [], complete: false });
+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 query = createRecordQuery(loader, limits.maxEdges);
+    return Object.freeze({
+        nodeId: (address, node) => nodeIdFor(address, node),
+        openScope: (address, context) => openRecordScope(address, context, loader),
+        async parents(nodeId, context) {
+            return whenResolved(await query.resolve(nodeId, context), (node) => query.inspect(node, context).adjacency, unavailableAdjacency);
+        },
+        async gaps(nodeId, context) {
+            return whenResolved(await query.resolve(nodeId, context), (node) => query.inspect(node, context).gaps, (failure) => gapForRecordFailure(failure.failure));
+        },
+        async attention(nodeId, context) {
+            return whenResolved(await query.resolve(nodeId, context), attentionForRecordNode, () => []);
+        },
+        async children(nodeId, context) {
+            return whenResolved(await query.resolve(nodeId, context), (node) => childrenForRecordNode(node, limits.maxEdges, query.inspect(node, context)), unavailableAdjacency);
+        },
+    });
+}
+/** 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 recordList(scopes, limits.maxScopes)) {
+            if (addressKey(addressOf(recordOwn(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 { RecordInspection, ResolvedRecordNode } from './recordTypes.js';
+import type { Adjacency } 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, inspection: RecordInspection): Adjacency;

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

@@ -0,0 +1,78 @@
+import { forwardSliceForKey } from '../slice/forwardSliceForKey.js';
+import { appendControlChildren } from './recordControl.js';
+import { allStageReadsCollected, writtenKeysForNode } from './recordCoverage.js';
+import { nodeIdFor } from './recordIdentity.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, inspection) {
+    const { scope, identity, commitIndex } = node;
+    const edges = [];
+    let complete = inspection.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 };
+}

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

@@ -0,0 +1,13 @@
+import type { ControlDependency } from '../memory/backtrack.js';
+import type { AddRecordGap, PreparedRecordScope, RecordIdentity } from './recordTypes.js';
+import type { GraphEdge } from './types.js';
+/** Only an execution or captured read may govern control flow; a written key alone cannot. */
+export declare function controlChildren(scope: PreparedRecordScope, identity: RecordIdentity): Iterable<readonly [string, ControlDependency]>;
+/** Canonical slicing receives only control parents that existed before the dependent execution. */
+export declare function controlParentLookup(scope: PreparedRecordScope): ((runtimeStageId: string) => ControlDependency | undefined) | undefined;
+/** Keep missing or future deciders visible rather than silently dropping their recorded dependency. */
+export declare function collectControlParentCoverage(scope: PreparedRecordScope, identity: RecordIdentity, firstCommitIndex: number, addGap: AddRecordGap): void;
+/** Include control fan-out in the same immediate-neighbor cap used for data adjacency. */
+export declare function collectControlChildCoverage(scope: PreparedRecordScope, identity: RecordIdentity, firstCommitIndex: number, neighbors: Set<string>, addGap: AddRecordGap): void;
+/** Preserve recorded control order and coverage when a dependent execution is absent or capped. */
+export declare function appendControlChildren(scope: PreparedRecordScope, identity: RecordIdentity, commitIndex: number, maximumEdges: number, edges: GraphEdge[]): boolean;

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

@@ -0,0 +1,66 @@
+import { nodeIdFor } from './recordIdentity.js';
+/** Only an execution or captured read may govern control flow; a written key alone cannot. */
+export function controlChildren(scope, identity) {
+    // A read-only execution may govern later work; a particular written key is not itself a decision.
+    return identity.key === undefined || identity.read ? scope.control ?? [] : [];
+}
+/** Canonical slicing receives only control parents that existed before the dependent execution. */
+export function controlParentLookup(scope) {
+    return scope.control === undefined
+        ? undefined
+        : (runtimeStageId) => {
+            const dependency = scope.control.get(runtimeStageId);
+            if (!dependency)
+                return undefined;
+            const parentIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === dependency.deciderId), childIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === runtimeStageId);
+            return parentIndex >= 0 && parentIndex < childIndex ? dependency : undefined;
+        };
+}
+/** Keep missing or future deciders visible rather than silently dropping their recorded dependency. */
+export function collectControlParentCoverage(scope, identity, firstCommitIndex, addGap) {
+    const dependency = scope.control?.get(identity.runtimeStageId);
+    if (!dependency)
+        return;
+    const parentIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === dependency.deciderId);
+    if (parentIndex < 0)
+        addGap('scope-boundary');
+    else if (parentIndex >= firstCommitIndex)
+        addGap('invalid-data');
+}
+/** Include control fan-out in the same immediate-neighbor cap used for data adjacency. */
+export function collectControlChildCoverage(scope, identity, firstCommitIndex, neighbors, addGap) {
+    for (const [childStageId, dependency] of controlChildren(scope, identity))
+        if (dependency.deciderId === identity.runtimeStageId) {
+            const childIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === childStageId);
+            if (childIndex < 0)
+                addGap('scope-boundary');
+            else if (childIndex <= firstCommitIndex)
+                addGap('invalid-data');
+            else
+                neighbors.add(JSON.stringify(['control', childStageId]));
+        }
+}
+/** Preserve recorded control order and coverage when a dependent execution is absent or capped. */
+export function appendControlChildren(scope, identity, commitIndex, maximumEdges, edges) {
+    let complete = true;
+    for (const [childStageId, dependency] of controlChildren(scope, identity)) {
+        if (dependency.deciderId !== identity.runtimeStageId)
+            continue;
+        const childIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === childStageId);
+        if (childIndex <= commitIndex) {
+            complete = false;
+            continue;
+        }
+        if (edges.length >= maximumEdges) {
+            complete = false;
+            break;
+        }
+        edges.push({
+            nodeId: nodeIdFor(scope.address, { runtimeStageId: childStageId, commitIdx: childIndex }),
+            kind: 'control',
+            attribution: 'recorded-control',
+            evidence: ['commit:' + childIndex],
+        });
+    }
+    return complete;
+}