foottrace 1.0.3 → 1.2.0

package/dist/lib/cause/explain.js

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

package/dist/lib/cause/ranking.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.admitRanking = void 0;
+const validation_js_1 = require("./validation.js");
+/** Strategies may only select admitted nodes; impact ranking must preserve the full set. */
+function admitRanking(raw, allowed, options) {
+    const ids = (0, validation_js_1.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;
+}
+exports.admitRanking = admitRanking;

package/dist/lib/cause/recordAdapter.js

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

package/dist/lib/cause/recordChildren.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.childrenForRecordNode = void 0;
+const forwardSliceForKey_js_1 = require("../slice/forwardSliceForKey.js");
+const recordControl_js_1 = require("./recordControl.js");
+const recordCoverage_js_1 = require("./recordCoverage.js");
+const recordIdentity_js_1 = require("./recordIdentity.js");
+const recordParents_js_1 = require("./recordParents.js");
+const recordScope_js_1 = require("./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 = (0, recordIdentity_js_1.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 = (0, recordIdentity_js_1.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) => (0, recordScope_js_1.readKeysForStage)(scope, runtimeStageId);
+    for (const key of (0, recordCoverage_js_1.writtenKeysForNode)(scope.log[commitIndex], identity)) {
+        const forward = (0, forwardSliceForKey_js_1.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. */
+function childrenForRecordNode(node, maximumEdges, extraGapCodes) {
+    const { scope, identity, commitIndex } = node;
+    const base = (0, recordParents_js_1.inspectRecordNode)(node, maximumEdges, extraGapCodes), edges = [];
+    let complete = base.gaps.length === 0;
+    if (!(0, recordCoverage_js_1.allStageReadsCollected)(scope))
+        complete = false;
+    complete = appendDataChildren(scope, identity, commitIndex, maximumEdges, edges) && complete;
+    complete = (0, recordControl_js_1.appendControlChildren)(scope, identity, commitIndex, maximumEdges, edges) && complete;
+    return { edges, complete };
+}
+exports.childrenForRecordNode = childrenForRecordNode;

package/dist/lib/cause/recordControl.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendControlChildren = exports.collectControlChildCoverage = exports.collectControlParentCoverage = exports.controlParentLookup = exports.controlChildren = void 0;
+const recordIdentity_js_1 = require("./recordIdentity.js");
+/** Only an execution or captured read may govern control flow; a written key alone cannot. */
+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 ?? [] : [];
+}
+exports.controlChildren = controlChildren;
+/** Canonical slicing receives only control parents that existed before the dependent execution. */
+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;
+        };
+}
+exports.controlParentLookup = controlParentLookup;
+/** Keep missing or future deciders visible rather than silently dropping their recorded dependency. */
+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');
+}
+exports.collectControlParentCoverage = collectControlParentCoverage;
+/** Include control fan-out in the same immediate-neighbor cap used for data adjacency. */
+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]));
+        }
+}
+exports.collectControlChildCoverage = collectControlChildCoverage;
+/** Preserve recorded control order and coverage when a dependent execution is absent or capped. */
+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: (0, recordIdentity_js_1.nodeIdFor)(scope.address, { runtimeStageId: childStageId, commitIdx: childIndex }),
+            kind: 'control',
+            attribution: 'recorded-control',
+            evidence: ['commit:' + childIndex],
+        });
+    }
+    return complete;
+}
+exports.appendControlChildren = appendControlChildren;

package/dist/lib/cause/recordCoverage.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allStageReadsCollected = exports.collectReadCoverage = exports.readAttributionIsPrecise = exports.collectForwardCoverage = exports.writtenKeysForNode = exports.collectScopeCoverage = exports.attentionForRecordNode = exports.gapForRecordFailure = exports.recordGapCollector = void 0;
+const keyPaths_js_1 = require("../memory/keyPaths.js");
+const forwardSliceForKey_js_1 = require("../slice/forwardSliceForKey.js");
+const recordControl_js_1 = require("./recordControl.js");
+const recordScope_js_1 = require("./recordScope.js");
+/** Preserve first-observed coverage order while collapsing repeated codes from different evidence paths. */
+function recordGapCollector() {
+    const gaps = [];
+    return {
+        gaps,
+        addGap: (code) => {
+            if (!gaps.some((gap) => gap.code === code))
+                gaps.push({ code, evidence: [] });
+        },
+    };
+}
+exports.recordGapCollector = recordGapCollector;
+/** Failed loading exposes a fixed category, never the host error or an apparently complete empty graph. */
+function gapForRecordFailure(code) {
+    return [{ code, evidence: [] }];
+}
+exports.gapForRecordFailure = gapForRecordFailure;
+/** Return captured mark references without treating an omitted attention map as collected evidence. */
+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) ?? [];
+}
+exports.attentionForRecordNode = attentionForRecordNode;
+/** Emit host and capture gaps before query-derived gaps so existing evidence order stays stable. */
+function collectScopeCoverage(scope, bundle, extraGapCodes, addGap) {
+    for (const code of extraGapCodes ?? [])
+        addGap(code);
+    if (!scope.complete || scope.control === undefined || scope.marks === undefined)
+        addGap('not-collected');
+    if (bundle.untrackedSources?.length)
+        addGap('untracked-input');
+    if (bundle.redactedPaths.length)
+        addGap('redacted');
+}
+exports.collectScopeCoverage = collectScopeCoverage;
+/** A read-only identity has no new value life; unqualified executions retain written-key encounter order. */
+function writtenKeysForNode(bundle, identity) {
+    return identity.read
+        ? []
+        : identity.key === undefined
+            ? [...new Set(bundle.trace.map((entry) => entry.path))]
+            : [identity.key];
+}
+exports.writtenKeysForNode = writtenKeysForNode;
+/** Immediate adjacency caps affect graph coverage even when the caller asks only for parents. */
+function collectForwardCoverage(scope, identity, commitIndex, firstCommitIndex, maximumEdges, addGap) {
+    const neighbors = new Set();
+    const lookup = (runtimeStageId) => (0, recordScope_js_1.readKeysForStage)(scope, runtimeStageId);
+    for (const key of writtenKeysForNode(scope.log[commitIndex], identity)) {
+        const forward = (0, forwardSliceForKey_js_1.forwardSliceForKey)(scope.log, key, lookup, {
+            before: commitIndex + 1,
+            maxDepth: 1,
+            maxNodes: maximumEdges + 1,
+        });
+        // A one-hop query intentionally stops at depth one; only a node cap hides immediate adjacency.
+        if (forward.root?.truncated?.byNodes)
+            addGap('edge-limit');
+        for (const edge of forward.root?.fedEdges ?? [])
+            neighbors.add(JSON.stringify(['data', edge.child.commitIdx, edge.child.key]));
+        for (const read of forward.root?.reads ?? [])
+            if (!scope.log[read.commitIdx]?.trace.length)
+                neighbors.add(JSON.stringify(['read', read.commitIdx, key]));
+    }
+    (0, recordControl_js_1.collectControlChildCoverage)(scope, identity, firstCommitIndex, neighbors, addGap);
+    if (neighbors.size > maximumEdges)
+        addGap('edge-limit');
+}
+exports.collectForwardCoverage = collectForwardCoverage;
+/** Exact attribution requires captured per-write provenance or a validated read-only key context. */
+function readAttributionIsPrecise(scope, identity, bundle) {
+    const relevant = identity.key === undefined
+        ? bundle.trace
+        : bundle.trace.filter((entry) => (0, keyPaths_js_1.relation)(entry.path, identity.key) !== undefined);
+    return identity.read === true
+        ? identity.key !== undefined && (0, recordScope_js_1.readKeysForStage)(scope, identity.runtimeStageId).includes(identity.key)
+        : identity.key !== undefined && relevant.length > 0 && relevant.every((entry) => entry.readKeys !== undefined);
+}
+exports.readAttributionIsPrecise = readAttributionIsPrecise;
+/** Distinguish conservative attribution from missing collection without marking a proven empty leaf. */
+function collectReadCoverage(scope, identity, precise, addGap) {
+    if (!precise && (identity.key !== undefined || (0, recordScope_js_1.readKeysForStage)(scope, identity.runtimeStageId).length > 0))
+        addGap('conservative');
+    if (!scope.reads?.has(identity.runtimeStageId) && !precise)
+        addGap('not-collected');
+}
+exports.collectReadCoverage = collectReadCoverage;
+/** Forward absence is trustworthy only when every potentially consuming execution collected its reads. */
+function allStageReadsCollected(scope) {
+    return !scope.log.some((bundle) => !scope.reads?.has(bundle.runtimeStageId) &&
+        (bundle.trace.length === 0 || bundle.trace.some((entry) => entry.readKeys === undefined)));
+}
+exports.allStageReadsCollected = allStageReadsCollected;

package/dist/lib/cause/recordIdentity.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRecordNode = exports.nodeIdFor = exports.readNodeIdentity = void 0;
+const recordScope_js_1 = require("./recordScope.js");
+const recordValidation_js_1 = require("./recordValidation.js");
+/** Parse only the bounded identity encoding; payload fields never become graph addresses. */
+function readNodeIdentity(nodeId) {
+    if (typeof nodeId !== 'string' || nodeId.length > 2048 || !nodeId.startsWith('record:'))
+        throw new recordValidation_js_1.RecordRefusal();
+    let fields;
+    try {
+        fields = JSON.parse(nodeId.slice(7));
+    }
+    catch {
+        throw new recordValidation_js_1.RecordRefusal();
+    }
+    const address = (0, recordValidation_js_1.addressOf)((0, recordValidation_js_1.own)(fields, 'address')), runtimeStageId = (0, recordValidation_js_1.name)((0, recordValidation_js_1.own)(fields, 'runtimeStageId')), commitIndex = (0, recordValidation_js_1.own)(fields, 'commitIdx'), key = (0, recordValidation_js_1.own)(fields, 'key'), read = (0, recordValidation_js_1.own)(fields, 'read');
+    if (commitIndex !== undefined && (!Number.isSafeInteger(commitIndex) || commitIndex < 0))
+        throw new recordValidation_js_1.RecordRefusal();
+    if ((read !== undefined && read !== true) || (read === true && key === undefined))
+        throw new recordValidation_js_1.RecordRefusal();
+    return {
+        address,
+        runtimeStageId,
+        ...(commitIndex === undefined ? {} : { commitIdx: commitIndex }),
+        ...(key === undefined ? {} : { key: (0, recordValidation_js_1.name)(key, true) }),
+        ...(read === true ? { read: true } : {}),
+    };
+}
+exports.readNodeIdentity = readNodeIdentity;
+/** Stable field order preserves existing address/execution/key IDs across storage and memory readers. */
+function nodeIdFor(addressInput, node, read) {
+    try {
+        const address = (0, recordValidation_js_1.addressOf)(addressInput), runtimeStageId = (0, recordValidation_js_1.name)((0, recordValidation_js_1.own)(node, 'runtimeStageId')), commitIndex = (0, recordValidation_js_1.own)(node, 'commitIdx'), key = (0, recordValidation_js_1.own)(node, 'key');
+        if (commitIndex !== undefined && (!Number.isSafeInteger(commitIndex) || commitIndex < 0))
+            throw new recordValidation_js_1.RecordRefusal();
+        const nodeId = 'record:' +
+            JSON.stringify({
+                address,
+                runtimeStageId,
+                ...(commitIndex === undefined ? {} : { commitIdx: commitIndex }),
+                ...(key === undefined ? {} : { key: (0, recordValidation_js_1.name)(key, true) }),
+                ...(read ? { read: true } : {}),
+            });
+        return nodeId.length <= 2048 ? nodeId : 'record:invalid';
+    }
+    catch {
+        return 'record:invalid';
+    }
+}
+exports.nodeIdFor = nodeIdFor;
+/** An admitted ID must also match captured evidence before it can introduce a dependency. */
+async function resolveRecordNode(nodeId, context, loader) {
+    try {
+        const identity = readNodeIdentity(nodeId), scope = await loader.loadScope(identity.address, context);
+        if ('failure' in scope)
+            return scope;
+        const commitIndex = identity.commitIdx ?? scope.log.findIndex((bundle) => bundle.runtimeStageId === identity.runtimeStageId);
+        if (commitIndex < 0 ||
+            commitIndex >= scope.log.length ||
+            scope.log[commitIndex].runtimeStageId !== identity.runtimeStageId)
+            throw new recordValidation_js_1.RecordRefusal();
+        // A qualified read is a captured fact, never a caller-supplied request to invent a dependency.
+        if (identity.read &&
+            (identity.key === undefined || !(0, recordScope_js_1.readKeysForStage)(scope, identity.runtimeStageId).includes(identity.key)))
+            throw new recordValidation_js_1.RecordRefusal();
+        return { scope, identity, commitIndex };
+    }
+    catch (error) {
+        return { failure: error instanceof recordValidation_js_1.RecordRefusal ? error.code : 'invalid-data' };
+    }
+}
+exports.resolveRecordNode = resolveRecordNode;

package/dist/lib/cause/recordLoading.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openRecordScope = exports.createRecordScopeLoader = void 0;
+const validation_js_1 = require("./validation.js");
+const recordIdentity_js_1 = require("./recordIdentity.js");
+const recordScope_js_1 = require("./recordScope.js");
+const recordValidation_js_1 = require("./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) {
+        request.controller.abort();
+        return { failure: request.context.signal.aborted ? 'cancelled' : 'timeout' };
+    }
+    let prepared;
+    try {
+        prepared = (0, recordScope_js_1.prepareRecordScope)((0, recordValidation_js_1.own)(result, 'scope'), request.address, limits.maxCommits, limits.maxFields);
+        const extra = (0, recordValidation_js_1.list)((0, recordValidation_js_1.own)(result, 'gaps') ?? [], 32);
+        // Coverage belongs to this admitted object, so cached scopes retain the same gap ordering and ownership.
+        state.extraGaps.set(prepared, (0, validation_js_1.gaps)(extra.map((code) => ({ code, evidence: [] }))).map((gap) => gap.code));
+    }
+    catch (error) {
+        throw error instanceof recordValidation_js_1.RecordRefusal ? error : new recordValidation_js_1.RecordRefusal();
+    }
+    if (performance.now() >= request.deadline) {
+        request.controller.abort();
+        return { failure: 'timeout' };
+    }
+    if (state.cache.size >= limits.maxScopes && !state.cache.has(request.cacheKey))
+        return { failure: 'node-limit' };
+    state.cache.set(request.cacheKey, prepared);
+    return prepared;
+}
+/** Host failures become fixed gaps while unfinished host work continues to occupy its bounded slot. */
+function startScopeWork(hostLoad, request, limits, state) {
+    const work = (0, recordValidation_js_1.projectLoaded)(() => {
+        if (request.controller.signal.aborted)
+            throw new recordValidation_js_1.RecordRefusal(request.context.signal.aborted ? 'cancelled' : 'timeout');
+        return hostLoad(request.address, { signal: request.controller.signal });
+    }, (result) => admitLoadedScope(result, request, limits, state)).catch((error) => {
+        if (request.context.signal.aborted)
+            return { failure: 'cancelled' };
+        if (performance.now() >= request.deadline) {
+            request.controller.abort();
+            return { failure: 'timeout' };
+        }
+        return { failure: error instanceof recordValidation_js_1.RecordRefusal ? error.code : 'unavailable' };
+    });
+    // A timed-out host operation retains its slot until it settles; repeated timeouts cannot grow an unbounded I/O pool.
+    void work.then(() => {
+        state.activeLoads--;
+    }, () => {
+        state.activeLoads--;
+    });
+    return work;
+}
+/** Bound caller waiting independently of host cooperation without sharing cancellation between requests. */
+function createRecordScopeLoader(hostLoad, limits) {
+    const state = { activeLoads: 0, cache: new Map(), extraGaps: new WeakMap() };
+    return {
+        async loadScope(address, context) {
+            if (context.signal.aborted)
+                return { failure: 'cancelled' };
+            const cacheKey = (0, recordValidation_js_1.addressKey)(address);
+            const cached = state.cache.get(cacheKey);
+            if (cached)
+                return cached;
+            if (state.cache.size + state.activeLoads >= limits.maxScopes)
+                return { failure: 'node-limit' };
+            state.activeLoads++;
+            const deadline = performance.now() + limits.loadTimeoutMs;
+            const controller = new AbortController();
+            let timer;
+            let finish;
+            const interrupted = new Promise((resolve) => {
+                finish = resolve;
+            });
+            const cancel = () => {
+                controller.abort();
+                finish?.({ failure: 'cancelled' });
+            };
+            context.signal.addEventListener('abort', cancel, { once: true });
+            timer = setTimeout(() => {
+                controller.abort();
+                finish?.({ failure: 'timeout' });
+            }, limits.loadTimeoutMs);
+            try {
+                const work = startScopeWork(hostLoad, { address, context, controller, deadline, cacheKey }, limits, state);
+                return await Promise.race([work, interrupted]);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                context.signal.removeEventListener('abort', cancel);
+            }
+        },
+        extraGapCodes: (scope) => state.extraGaps.get(scope),
+    };
+}
+exports.createRecordScopeLoader = createRecordScopeLoader;
+/** Discovery must distinguish an unavailable scope from a successfully loaded empty record. */
+async function openRecordScope(addressInput, context, loader) {
+    let address;
+    try {
+        address = (0, recordValidation_js_1.addressOf)(addressInput);
+    }
+    catch {
+        throw new recordValidation_js_1.RecordRefusal();
+    }
+    const scope = await loader.loadScope(address, context);
+    if ('failure' in scope)
+        throw new recordValidation_js_1.RecordRefusal(scope.failure);
+    // Empty unfinished evidence has no node on which to report its gap; discovery must reject instead.
+    if (!scope.log.length &&
+        (!scope.complete ||
+            scope.control === undefined ||
+            scope.marks === undefined ||
+            (loader.extraGapCodes(scope)?.length ?? 0) > 0))
+        throw new recordValidation_js_1.RecordRefusal('not-collected');
+    return scope.log.map((bundle, commitIndex) => (0, recordIdentity_js_1.nodeIdFor)(address, { runtimeStageId: bundle.runtimeStageId, commitIdx: commitIndex }));
+}
+exports.openRecordScope = openRecordScope;