foottrace 1.2.0 → 1.4.0

package/README.md

@@ -13,7 +13,7 @@ Foottrace owns the record layer used by footprintjs 10. Older stored records rem
 | `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 |
+| `foottrace/cause` | Optional bounded attention, cause and impact queries; in-memory and lazily loaded stored-record adapters |
 
 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`.
 
@@ -43,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.
@@ -100,7 +125,7 @@ The parser reads from the right, so a stage ID may contain `@` or `.` and no cha
 
 ## Compatibility and development
 
-Node.js 22 or newer; develop with Node.js 24 and npm 11. Both CommonJS and ESM are provided. Browser-capable source uses no Node runtime APIs. Use one module format consistently in an application; CJS and ESM have separate module instances.
+Node.js 22 or newer; develop with Node.js 24 and npm 11. Both CommonJS and ESM are provided. Browser-capable source uses no Node runtime APIs. Use one module format consistently in an application; CJS and ESM have separate module instances. For a documented refusal such as `RequirementValidationError`, inspect the known operation's fixed `code` (and fixed `message` when distinguishing error kinds), rather than using `instanceof` across module formats.
 
 ```sh
 npm ci
@@ -114,13 +139,13 @@ Record bytes are part of the versioning promise: refactors never re-pin; a named
 MIT license. Contact: sanjay@footprintjs.dev.
 
 
-## Cause and impact — 1.2.0 candidate
+## 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.
+`foottrace/cause` answers bounded, read-only cause and impact queries from recorded data and control dependencies. It never reruns business code or calls a model. Findings carry evidence references, alternatives and gaps; incomplete backward evidence withholds a definite root. 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.
+Enable `writeProvenance: 'reads-prefix'` in the producer for precise per-write queries. Stage-level capture remains conservative, and a reader cannot restore missing provenance in old records.
 
-**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.
+The `/cause` door provides typed ESM and CommonJS exports. Use `import { explain } from 'foottrace/cause'` in ESM or `const { explain } = require('foottrace/cause')` in CommonJS. Native `import('foottrace/cause')` remains available for lazy loading.
 
 ```ts
 import type { Attention } from 'foottrace';
@@ -140,68 +165,4 @@ const finding = await explain(graph, selectedNodeId, {
 // 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.
+Follow the [cause and impact manual](https://github.com/footprintjs/foottrace/blob/main/docs/cause.md) to record per-write provenance, adapt an authorized stored record, run bounded queries and interpret roots, alternatives and gaps. A complete synthetic [record example](https://github.com/footprintjs/foottrace/blob/main/examples/cause-record.ts) demonstrates both in-memory and stored adapters.

package/dist/esm/index.d.ts

@@ -30,3 +30,7 @@ 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.js

@@ -1,16 +1,16 @@
 import { Session } from './session.js';
 import { frontier, pathTo, walk } from './walk.js';
-import { gap, name, nodeIds, own, uniqueGaps } from './validation.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 = {}) {
-    name(nodeId);
+    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 = own(options, 'rankRoots');
+        const rank = graphOwn(options, 'rankRoots');
         if (rank !== undefined) {
             if (typeof rank !== 'function')
                 throw new TypeError('CAUSE_CONFIGURATION_INVALID');
@@ -31,7 +31,7 @@ export async function explain(graph, nodeId, options = {}) {
         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');
+        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,
@@ -69,19 +69,19 @@ export async function attentionList(graph, options = {}) {
     const session = new Session(graph, options);
     try {
         let seeds = [], missing = [];
-        const requested = own(options, 'nodeIds');
+        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 = own(raw, 'length');
+            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(own(raw, String(i)));
+                prefix.push(graphOwn(raw, String(i)));
             return nodeIds(prefix, session.limits.maxNodes);
         };
         if (requested !== undefined) {

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/recordAdapter.js

@@ -1,38 +1,31 @@
 import { childrenForRecordNode } from './recordChildren.js';
 import { attentionForRecordNode, gapForRecordFailure } from './recordCoverage.js';
-import { nodeIdFor, resolveRecordNode } from './recordIdentity.js';
+import { nodeIdFor } from './recordIdentity.js';
 import { createRecordScopeLoader, openRecordScope } from './recordLoading.js';
-import { inspectRecordNode } from './recordParents.js';
+import { createRecordQuery, whenResolved } from './recordQuery.js';
 import { recordOptions } from './recordScope.js';
-import { addressKey, addressOf, list, own, RecordRefusal } from './recordValidation.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 resolve = (nodeId, context) => resolveRecordNode(nodeId, context, loader);
+    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) {
-            const node = await resolve(nodeId, context);
-            return 'failure' in node
-                ? { edges: [], complete: false }
-                : inspectRecordNode(node, limits.maxEdges, loader.extraGapCodes(node.scope)).adjacency;
+            return whenResolved(await query.resolve(nodeId, context), (node) => query.inspect(node, context).adjacency, unavailableAdjacency);
         },
         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;
+            return whenResolved(await query.resolve(nodeId, context), (node) => query.inspect(node, context).gaps, (failure) => gapForRecordFailure(failure.failure));
         },
         async attention(nodeId, context) {
-            return attentionForRecordNode(await resolve(nodeId, context));
+            return whenResolved(await query.resolve(nodeId, context), attentionForRecordNode, () => []);
         },
         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));
+            return whenResolved(await query.resolve(nodeId, context), (node) => childrenForRecordNode(node, limits.maxEdges, query.inspect(node, context)), unavailableAdjacency);
         },
     });
 }
@@ -40,8 +33,8 @@ export function createLazyRecordGraph(load, options = {}) {
 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))
+        for (const raw of recordList(scopes, limits.maxScopes)) {
+            if (addressKey(addressOf(recordOwn(raw, 'address'))) === addressKey(address))
                 return { scope: raw };
         }
         throw new RecordRefusal('unavailable');

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

@@ -1,4 +1,4 @@
-import type { ResolvedRecordNode } from './recordTypes.js';
-import type { Adjacency, Gap } from './types.js';
+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, extraGapCodes: readonly Gap['code'][] | undefined): Adjacency;
+export declare function childrenForRecordNode(node: ResolvedRecordNode, maximumEdges: number, inspection: RecordInspection): Adjacency;

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

@@ -2,7 +2,6 @@ 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) {
@@ -67,10 +66,10 @@ function appendDataChildren(scope, identity, commitIndex, maximumEdges, edges) {
     return complete;
 }
 /** Share parent-side coverage checks before appending data then control children in their established order. */
-export function childrenForRecordNode(node, maximumEdges, extraGapCodes) {
+export function childrenForRecordNode(node, maximumEdges, inspection) {
     const { scope, identity, commitIndex } = node;
-    const base = inspectRecordNode(node, maximumEdges, extraGapCodes), edges = [];
-    let complete = base.gaps.length === 0;
+    const edges = [];
+    let complete = inspection.gaps.length === 0;
     if (!allStageReadsCollected(scope))
         complete = false;
     complete = appendDataChildren(scope, identity, commitIndex, maximumEdges, edges) && complete;

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

@@ -1,5 +1,5 @@
 import type { CommitBundle } from '../memory/types.js';
-import type { AddRecordGap, PreparedRecordScope, RecordIdentity, RecordLoadFailure, ResolvedRecordNode } from './recordTypes.js';
+import type { AddRecordGap, PreparedRecordScope, RecordIdentity, ResolvedRecordNode } from './recordTypes.js';
 import type { Attention, Gap } from './types.js';
 /** Preserve first-observed coverage order while collapsing repeated codes from different evidence paths. */
 export declare function recordGapCollector(): {
@@ -9,7 +9,7 @@ export declare function recordGapCollector(): {
 /** Failed loading exposes a fixed category, never the host error or an apparently complete empty graph. */
 export declare function gapForRecordFailure(code: Gap['code']): readonly Gap[];
 /** Return captured mark references without treating an omitted attention map as collected evidence. */
-export declare function attentionForRecordNode(node: ResolvedRecordNode | RecordLoadFailure): readonly Attention[];
+export declare function attentionForRecordNode(node: ResolvedRecordNode): readonly Attention[];
 /** Emit host and capture gaps before query-derived gaps so existing evidence order stays stable. */
 export declare function collectScopeCoverage(scope: PreparedRecordScope, bundle: CommitBundle, extraGapCodes: readonly Gap['code'][] | undefined, addGap: AddRecordGap): void;
 /** A read-only identity has no new value life; unqualified executions retain written-key encounter order. */

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

@@ -20,7 +20,7 @@ export function gapForRecordFailure(code) {
 /** Return captured mark references without treating an omitted attention map as collected evidence. */
 export function attentionForRecordNode(node) {
     // An omitted map stays unknown coverage; it is never replaced by an affirmative empty map.
-    return 'failure' in node ? [] : node.scope.marks?.get(node.identity.runtimeStageId) ?? [];
+    return node.scope.marks?.get(node.identity.runtimeStageId) ?? [];
 }
 /** Emit host and capture gaps before query-derived gaps so existing evidence order stays stable. */
 export function collectScopeCoverage(scope, bundle, extraGapCodes, addGap) {

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

@@ -1,5 +1,5 @@
 import { readKeysForStage } from './recordScope.js';
-import { addressOf, name, own, RecordRefusal } from './recordValidation.js';
+import { addressOf, recordName, recordOwn, RecordRefusal } from './recordValidation.js';
 /** Parse only the bounded identity encoding; payload fields never become graph addresses. */
 export function readNodeIdentity(nodeId) {
     if (typeof nodeId !== 'string' || nodeId.length > 2048 || !nodeId.startsWith('record:'))
@@ -11,7 +11,7 @@ export function readNodeIdentity(nodeId) {
     catch {
         throw new RecordRefusal();
     }
-    const address = addressOf(own(fields, 'address')), runtimeStageId = name(own(fields, 'runtimeStageId')), commitIndex = own(fields, 'commitIdx'), key = own(fields, 'key'), read = own(fields, 'read');
+    const address = addressOf(recordOwn(fields, 'address')), runtimeStageId = recordName(recordOwn(fields, 'runtimeStageId')), commitIndex = recordOwn(fields, 'commitIdx'), key = recordOwn(fields, 'key'), read = recordOwn(fields, 'read');
     if (commitIndex !== undefined && (!Number.isSafeInteger(commitIndex) || commitIndex < 0))
         throw new RecordRefusal();
     if ((read !== undefined && read !== true) || (read === true && key === undefined))
@@ -20,14 +20,14 @@ export function readNodeIdentity(nodeId) {
         address,
         runtimeStageId,
         ...(commitIndex === undefined ? {} : { commitIdx: commitIndex }),
-        ...(key === undefined ? {} : { key: name(key, true) }),
+        ...(key === undefined ? {} : { key: recordName(key, true) }),
         ...(read === true ? { read: true } : {}),
     };
 }
 /** Stable field order preserves existing address/execution/key IDs across storage and memory readers. */
 export function nodeIdFor(addressInput, node, read) {
     try {
-        const address = addressOf(addressInput), runtimeStageId = name(own(node, 'runtimeStageId')), commitIndex = own(node, 'commitIdx'), key = own(node, 'key');
+        const address = addressOf(addressInput), runtimeStageId = recordName(recordOwn(node, 'runtimeStageId')), commitIndex = recordOwn(node, 'commitIdx'), key = recordOwn(node, 'key');
         if (commitIndex !== undefined && (!Number.isSafeInteger(commitIndex) || commitIndex < 0))
             throw new RecordRefusal();
         const nodeId = 'record:' +
@@ -35,7 +35,7 @@ export function nodeIdFor(addressInput, node, read) {
                 address,
                 runtimeStageId,
                 ...(commitIndex === undefined ? {} : { commitIdx: commitIndex }),
-                ...(key === undefined ? {} : { key: name(key, true) }),
+                ...(key === undefined ? {} : { key: recordName(key, true) }),
                 ...(read ? { read: true } : {}),
             });
         return nodeId.length <= 2048 ? nodeId : 'record:invalid';

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

@@ -1,7 +1,7 @@
 import { gaps as admitGaps } from './validation.js';
 import { nodeIdFor } from './recordIdentity.js';
 import { prepareRecordScope } from './recordScope.js';
-import { addressKey, addressOf, list, own, projectLoaded, RecordRefusal } from './recordValidation.js';
+import { addressKey, addressOf, recordList, recordOwn, projectLoaded, RecordRefusal } from './recordValidation.js';
 /** Admit before caching so a cache hit cannot bypass payload limits or lose scope-owned coverage. */
 function admitLoadedScope(result, request, limits, state) {
     if (request.controller.signal.aborted || performance.now() >= request.deadline) {
@@ -10,8 +10,8 @@ function admitLoadedScope(result, request, limits, state) {
     }
     let prepared;
     try {
-        prepared = prepareRecordScope(own(result, 'scope'), request.address, limits.maxCommits, limits.maxFields);
-        const extra = list(own(result, 'gaps') ?? [], 32);
+        prepared = prepareRecordScope(recordOwn(result, 'scope'), request.address, limits.maxCommits, limits.maxFields);
+        const extra = recordList(recordOwn(result, 'gaps') ?? [], 32);
         // Coverage belongs to this admitted object, so cached scopes retain the same gap ordering and ownership.
         state.extraGaps.set(prepared, admitGaps(extra.map((code) => ({ code, evidence: [] }))).map((gap) => gap.code));
     }

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

@@ -0,0 +1,9 @@
+import type { RecordLoadFailure, RecordScopeLoader, ResolvedRecordNode } from './recordTypes.js';
+import type { GraphContext, NodeId } from './types.js';
+/** Both dependency directions share the same admitted node and canonical inspection within a query. */
+export declare function createRecordQuery(loader: RecordScopeLoader, maximumEdges: number): {
+    resolve(nodeId: NodeId, context: GraphContext): Promise<RecordLoadFailure | ResolvedRecordNode>;
+    inspect(node: ResolvedRecordNode, context: GraphContext): import("./recordTypes.js").RecordInspection;
+};
+/** Every port maps the same fixed loading failure while projecting only admitted nodes. */
+export declare function whenResolved<T>(node: ResolvedRecordNode | RecordLoadFailure, onNode: (node: ResolvedRecordNode) => T, onFailure: (failure: RecordLoadFailure) => T): T;

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

@@ -0,0 +1,22 @@
+import { queryMemo } from './queryMemo.js';
+import { resolveRecordNode } from './recordIdentity.js';
+import { inspectRecordNode } from './recordInspection.js';
+/** Both dependency directions share the same admitted node and canonical inspection within a query. */
+export function createRecordQuery(loader, maximumEdges) {
+    const resolutionOwner = {}, inspectionOwner = {};
+    return {
+        resolve(nodeId, context) {
+            const resolve = () => resolveRecordNode(nodeId, context, loader), memo = queryMemo(context);
+            // A retained success must never bypass the loader's existing cancellation check.
+            return memo && !context.signal.aborted ? memo.remember(resolutionOwner, nodeId, resolve) : resolve();
+        },
+        inspect(node, context) {
+            const inspect = () => inspectRecordNode(node, maximumEdges, loader.extraGapCodes(node.scope));
+            return queryMemo(context)?.remember(inspectionOwner, node, inspect) ?? inspect();
+        },
+    };
+}
+/** Every port maps the same fixed loading failure while projecting only admitted nodes. */
+export function whenResolved(node, onNode, onFailure) {
+    return 'failure' in node ? onFailure(node) : onNode(node);
+}

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

@@ -1,4 +1,4 @@
-import { addressKey, addressOf, bundleOf, list, mapOf, marksOf, name, names, own, RecordRefusal, spend, } from './recordValidation.js';
+import { addressKey, addressOf, bundleOf, recordList, mapOf, marksOf, recordName, names, recordOwn, RecordRefusal, spend, } from './recordValidation.js';
 /** Refuse an invalid limit before loading a scope or allocating its preparation budget. */
 function boundedOption(value, defaultValue, maximum) {
     const configuredValue = value ?? defaultValue;
@@ -16,11 +16,11 @@ export function recordOptions(options) {
         if (prototype !== Object.prototype && prototype !== null)
             throw new TypeError();
         return Object.freeze({
-            maxCommits: boundedOption(own(options, 'maxCommits'), 256, 4096),
-            maxFields: boundedOption(own(options, 'maxFields'), 20000, 1000000),
-            maxEdges: boundedOption(own(options, 'maxEdges'), 64, 256),
-            maxScopes: boundedOption(own(options, 'maxScopes'), 32, 256),
-            loadTimeoutMs: boundedOption(own(options, 'loadTimeoutMs'), 1000, 30000),
+            maxCommits: boundedOption(recordOwn(options, 'maxCommits'), 256, 4096),
+            maxFields: boundedOption(recordOwn(options, 'maxFields'), 20000, 1000000),
+            maxEdges: boundedOption(recordOwn(options, 'maxEdges'), 64, 256),
+            maxScopes: boundedOption(recordOwn(options, 'maxScopes'), 32, 256),
+            loadTimeoutMs: boundedOption(recordOwn(options, 'loadTimeoutMs'), 1000, 30000),
         });
     }
     catch {
@@ -29,22 +29,22 @@ export function recordOptions(options) {
 }
 /** Spend one shared field budget before canonical readers see any untrusted scope data. */
 export function prepareRecordScope(value, address, maximumCommits, maximumFields) {
-    if (addressKey(addressOf(own(value, 'address'))) !== addressKey(address))
+    if (addressKey(addressOf(recordOwn(value, 'address'))) !== addressKey(address))
         throw new RecordRefusal();
-    const rawLog = list(own(value, 'commitLog'), maximumCommits), budget = { left: maximumFields };
-    const log = rawLog.map((_, commitIndex) => bundleOf(own(rawLog, String(commitIndex)), commitIndex, budget));
-    const reads = mapOf(own(value, 'reads'), maximumCommits, (value) => {
+    const rawLog = recordList(recordOwn(value, 'commitLog'), maximumCommits), budget = { left: maximumFields };
+    const log = rawLog.map((_, commitIndex) => bundleOf(recordOwn(rawLog, String(commitIndex)), commitIndex, budget));
+    const reads = mapOf(recordOwn(value, 'reads'), maximumCommits, (value) => {
         const readKeys = names(value, 128, true);
         spend(budget, readKeys.length);
         return readKeys;
     }, budget);
-    const control = mapOf(own(value, 'controlDeps'), maximumCommits, (value) => ({ deciderId: name(own(value, 'deciderId')) }), budget);
-    const marks = mapOf(own(value, 'attention'), maximumCommits, (value) => {
+    const control = mapOf(recordOwn(value, 'controlDeps'), maximumCommits, (value) => ({ deciderId: recordName(recordOwn(value, 'deciderId')) }), budget);
+    const marks = mapOf(recordOwn(value, 'attention'), maximumCommits, (value) => {
         const attention = marksOf(value);
         spend(budget, attention.length + attention.reduce((count, mark) => count + mark.evidence.length, 0));
         return attention;
     }, budget);
-    return { address, log, reads, control, marks, complete: own(value, 'complete') === true };
+    return { address, log, reads, control, marks, complete: recordOwn(value, 'complete') === true };
 }
 /** Preserve both stage reads and stronger per-write prefixes, including their original encounter order. */
 export function readKeysForStage(scope, runtimeStageId) {

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

@@ -3,17 +3,17 @@ import type { LogAddress } from '../memory/eventPosition.js';
 import type { CommitBundle } from '../memory/types.js';
 import type { GapCode } from './types.js';
 import { attention as marksOf } from './validation.js';
-import { EvidenceRefusal } from './admission.js';
+import { EvidenceRefusal } from '../evidence/admission.js';
 export { marksOf };
 /** Loader refusals stay distinct from graph-port refusals so a failed host load keeps its original classification. */
 export declare class RecordRefusal extends EvidenceRefusal {
     readonly code: GapCode;
     constructor(code?: GapCode);
 }
-export declare function own(value: unknown, key: string): unknown;
+export declare function recordOwn(value: unknown, key: string): unknown;
 export declare function names(value: unknown, maximum?: number, path?: boolean): string[];
-export declare function name(value: unknown, path?: boolean): string;
-export declare function list(value: unknown, maximum: number): readonly unknown[];
+export declare function recordName(value: unknown, path?: boolean): string;
+export declare function recordList(value: unknown, maximum: number): readonly unknown[];
 export declare function addressOf(value: unknown): LogAddress;
 export declare function spend(budget: {
     left: number;