foottrace 1.1.0 → 1.2.0

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

@@ -0,0 +1,24 @@
+import type { CommitBundle } from '../memory/types.js';
+import type { AddRecordGap, PreparedRecordScope, RecordIdentity, RecordLoadFailure, 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(): {
+    gaps: Gap[];
+    addGap: AddRecordGap;
+};
+/** 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[];
+/** 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. */
+export declare function writtenKeysForNode(bundle: CommitBundle, identity: RecordIdentity): string[];
+/** Immediate adjacency caps affect graph coverage even when the caller asks only for parents. */
+export declare function collectForwardCoverage(scope: PreparedRecordScope, identity: RecordIdentity, commitIndex: number, firstCommitIndex: number, maximumEdges: number, addGap: AddRecordGap): void;
+/** Exact attribution requires captured per-write provenance or a validated read-only key context. */
+export declare function readAttributionIsPrecise(scope: PreparedRecordScope, identity: RecordIdentity, bundle: CommitBundle): boolean;
+/** Distinguish conservative attribution from missing collection without marking a proven empty leaf. */
+export declare function collectReadCoverage(scope: PreparedRecordScope, identity: RecordIdentity, precise: boolean, addGap: AddRecordGap): void;
+/** Forward absence is trustworthy only when every potentially consuming execution collected its reads. */
+export declare function allStageReadsCollected(scope: PreparedRecordScope): boolean;

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

@@ -0,0 +1,87 @@
+import { relation } from '../memory/keyPaths.js';
+import { forwardSliceForKey } from '../slice/forwardSliceForKey.js';
+import { collectControlChildCoverage } from './recordControl.js';
+import { readKeysForStage } from './recordScope.js';
+/** Preserve first-observed coverage order while collapsing repeated codes from different evidence paths. */
+export function recordGapCollector() {
+    const gaps = [];
+    return {
+        gaps,
+        addGap: (code) => {
+            if (!gaps.some((gap) => gap.code === code))
+                gaps.push({ code, evidence: [] });
+        },
+    };
+}
+/** Failed loading exposes a fixed category, never the host error or an apparently complete empty graph. */
+export function gapForRecordFailure(code) {
+    return [{ code, evidence: [] }];
+}
+/** 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) ?? [];
+}
+/** Emit host and capture gaps before query-derived gaps so existing evidence order stays stable. */
+export 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');
+}
+/** A read-only identity has no new value life; unqualified executions retain written-key encounter order. */
+export function writtenKeysForNode(bundle, identity) {
+    return identity.read
+        ? []
+        : identity.key === undefined
+            ? [...new Set(bundle.trace.map((entry) => entry.path))]
+            : [identity.key];
+}
+/** Immediate adjacency caps affect graph coverage even when the caller asks only for parents. */
+export function collectForwardCoverage(scope, identity, commitIndex, firstCommitIndex, maximumEdges, addGap) {
+    const neighbors = new Set();
+    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,
+        });
+        // 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]));
+    }
+    collectControlChildCoverage(scope, identity, firstCommitIndex, neighbors, addGap);
+    if (neighbors.size > maximumEdges)
+        addGap('edge-limit');
+}
+/** Exact attribution requires captured per-write provenance or a validated read-only key context. */
+export function readAttributionIsPrecise(scope, identity, bundle) {
+    const relevant = identity.key === undefined
+        ? bundle.trace
+        : bundle.trace.filter((entry) => relation(entry.path, identity.key) !== undefined);
+    return identity.read === true
+        ? identity.key !== undefined && readKeysForStage(scope, identity.runtimeStageId).includes(identity.key)
+        : identity.key !== undefined && relevant.length > 0 && relevant.every((entry) => entry.readKeys !== undefined);
+}
+/** Distinguish conservative attribution from missing collection without marking a proven empty leaf. */
+export function collectReadCoverage(scope, identity, precise, addGap) {
+    if (!precise && (identity.key !== undefined || readKeysForStage(scope, identity.runtimeStageId).length > 0))
+        addGap('conservative');
+    if (!scope.reads?.has(identity.runtimeStageId) && !precise)
+        addGap('not-collected');
+}
+/** Forward absence is trustworthy only when every potentially consuming execution collected its reads. */
+export function allStageReadsCollected(scope) {
+    return !scope.log.some((bundle) => !scope.reads?.has(bundle.runtimeStageId) &&
+        (bundle.trace.length === 0 || bundle.trace.some((entry) => entry.readKeys === undefined)));
+}

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

@@ -0,0 +1,9 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { GraphContext, NodeId } from './types.js';
+import type { RecordIdentity, RecordLoadFailure, RecordNode, RecordScopeLoader, ResolvedRecordNode } from './recordTypes.js';
+/** Parse only the bounded identity encoding; payload fields never become graph addresses. */
+export declare function readNodeIdentity(nodeId: string): RecordIdentity;
+/** Stable field order preserves existing address/execution/key IDs across storage and memory readers. */
+export declare function nodeIdFor(addressInput: LogAddress, node: RecordNode, read?: true): NodeId;
+/** An admitted ID must also match captured evidence before it can introduce a dependency. */
+export declare function resolveRecordNode(nodeId: NodeId, context: GraphContext, loader: RecordScopeLoader): Promise<ResolvedRecordNode | RecordLoadFailure>;

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

@@ -0,0 +1,67 @@
+import { readKeysForStage } from './recordScope.js';
+import { addressOf, name, own, 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:'))
+        throw new RecordRefusal();
+    let fields;
+    try {
+        fields = JSON.parse(nodeId.slice(7));
+    }
+    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');
+    if (commitIndex !== undefined && (!Number.isSafeInteger(commitIndex) || commitIndex < 0))
+        throw new RecordRefusal();
+    if ((read !== undefined && read !== true) || (read === true && key === undefined))
+        throw new RecordRefusal();
+    return {
+        address,
+        runtimeStageId,
+        ...(commitIndex === undefined ? {} : { commitIdx: commitIndex }),
+        ...(key === undefined ? {} : { key: name(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');
+        if (commitIndex !== undefined && (!Number.isSafeInteger(commitIndex) || commitIndex < 0))
+            throw new RecordRefusal();
+        const nodeId = 'record:' +
+            JSON.stringify({
+                address,
+                runtimeStageId,
+                ...(commitIndex === undefined ? {} : { commitIdx: commitIndex }),
+                ...(key === undefined ? {} : { key: name(key, true) }),
+                ...(read ? { read: true } : {}),
+            });
+        return nodeId.length <= 2048 ? nodeId : 'record:invalid';
+    }
+    catch {
+        return 'record:invalid';
+    }
+}
+/** An admitted ID must also match captured evidence before it can introduce a dependency. */
+export 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 RecordRefusal();
+        // A qualified read is a captured fact, never a caller-supplied request to invent a dependency.
+        if (identity.read &&
+            (identity.key === undefined || !readKeysForStage(scope, identity.runtimeStageId).includes(identity.key)))
+            throw new RecordRefusal();
+        return { scope, identity, commitIndex };
+    }
+    catch (error) {
+        return { failure: error instanceof RecordRefusal ? error.code : 'invalid-data' };
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { GraphContext, NodeId } from './types.js';
+import type { RecordGraphOptions, RecordScopeHost, RecordScopeLoader } from './recordTypes.js';
+/** Bound caller waiting independently of host cooperation without sharing cancellation between requests. */
+export declare function createRecordScopeLoader(hostLoad: RecordScopeHost, limits: Required<RecordGraphOptions>): RecordScopeLoader;
+/** Discovery must distinguish an unavailable scope from a successfully loaded empty record. */
+export declare function openRecordScope(addressInput: LogAddress, context: GraphContext, loader: RecordScopeLoader): Promise<readonly NodeId[]>;

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

@@ -0,0 +1,116 @@
+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';
+/** 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 = prepareRecordScope(own(result, 'scope'), request.address, limits.maxCommits, limits.maxFields);
+        const extra = list(own(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));
+    }
+    catch (error) {
+        throw error instanceof RecordRefusal ? error : new 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 = projectLoaded(() => {
+        if (request.controller.signal.aborted)
+            throw new 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 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. */
+export 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 = 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),
+    };
+}
+/** Discovery must distinguish an unavailable scope from a successfully loaded empty record. */
+export async function openRecordScope(addressInput, context, loader) {
+    let address;
+    try {
+        address = addressOf(addressInput);
+    }
+    catch {
+        throw new RecordRefusal();
+    }
+    const scope = await loader.loadScope(address, context);
+    if ('failure' in scope)
+        throw new 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 RecordRefusal('not-collected');
+    return scope.log.map((bundle, commitIndex) => nodeIdFor(address, { runtimeStageId: bundle.runtimeStageId, commitIdx: commitIndex }));
+}

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

@@ -0,0 +1,4 @@
+import type { RecordInspection, ResolvedRecordNode } from './recordTypes.js';
+import type { Gap } from './types.js';
+/** Derive parent adjacency and its ordered gaps together from the same bounded canonical query. */
+export declare function inspectRecordNode(node: ResolvedRecordNode, maximumEdges: number, extraGapCodes: readonly Gap['code'][] | undefined): RecordInspection;

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

@@ -0,0 +1,86 @@
+import { causalChain } from '../memory/backtrack.js';
+import { findLastWriter } from '../memory/commitLogUtils.js';
+import { sliceForKey } from '../slice/sliceForKey.js';
+import { collectControlParentCoverage, controlParentLookup } from './recordControl.js';
+import { collectForwardCoverage, collectReadCoverage, collectScopeCoverage, readAttributionIsPrecise, recordGapCollector, } from './recordCoverage.js';
+import { nodeIdFor } from './recordIdentity.js';
+import { readKeysForStage } from './recordScope.js';
+/** Anchor writers before the execution so later commits cannot rewrite the recorded causal edge. */
+function projectParentEdges(scope, parentEdges, firstCommitIndex, precise, maximumEdges, addGap) {
+    const edges = [];
+    for (const edge of parentEdges) {
+        if (edges.length >= maximumEdges) {
+            addGap('edge-limit');
+            break;
+        }
+        const writer = edge.kind === 'data' && edge.key
+            ? findLastWriter(scope.log, edge.key, firstCommitIndex)
+            : scope.log.find((bundle) => bundle.runtimeStageId === edge.parent.runtimeStageId);
+        if (!writer) {
+            addGap('untracked-input');
+            continue;
+        }
+        const writerIndex = scope.log.indexOf(writer);
+        edges.push({
+            nodeId: nodeIdFor(scope.address, {
+                runtimeStageId: writer.runtimeStageId,
+                commitIdx: writerIndex,
+                ...(edge.kind === 'data' && edge.key ? { key: edge.key } : {}),
+            }),
+            kind: edge.kind,
+            attribution: edge.kind === 'control' ? 'recorded-control' : precise ? 'per-write' : 'stage',
+            evidence: ['commit:' + writerIndex],
+        });
+        if (edge.basis)
+            addGap('conservative');
+    }
+    return edges;
+}
+/** Derive parent adjacency and its ordered gaps together from the same bounded canonical query. */
+export function inspectRecordNode(node, maximumEdges, extraGapCodes) {
+    const { scope, identity, commitIndex } = node;
+    const bundle = scope.log[commitIndex], firstCommitIndex = scope.log.findIndex((entry) => entry.runtimeStageId === identity.runtimeStageId), coverage = recordGapCollector();
+    collectScopeCoverage(scope, bundle, extraGapCodes, coverage.addGap);
+    const lookup = (runtimeStageId) => readKeysForStage(scope, runtimeStageId);
+    collectForwardCoverage(scope, identity, commitIndex, firstCommitIndex, maximumEdges, coverage.addGap);
+    const precise = readAttributionIsPrecise(scope, identity, bundle);
+    collectReadCoverage(scope, identity, precise, coverage.addGap);
+    collectControlParentCoverage(scope, identity, firstCommitIndex, coverage.addGap);
+    const control = controlParentLookup(scope);
+    const slice = identity.key === undefined || identity.read
+        ? undefined
+        : sliceForKey(scope.log, identity.key, lookup, {
+            before: commitIndex + 1,
+            maxDepth: 1,
+            maxNodes: maximumEdges + 1,
+            controlDeps: control,
+        });
+    if (identity.key !== undefined &&
+        !identity.read &&
+        (!slice?.writer || scope.log.indexOf(slice.writer) !== commitIndex)) {
+        coverage.addGap('invalid-data');
+        return { adjacency: { edges: [], complete: false }, gaps: coverage.gaps };
+    }
+    // Read-only identities retain both the read's data writer and the execution's recorded control parent.
+    const root = identity.read && identity.key !== undefined
+        ? causalChain(scope.log, identity.runtimeStageId, (runtimeStageId) => (runtimeStageId === identity.runtimeStageId ? [identity.key] : lookup(runtimeStageId)), { maxDepth: 1, maxNodes: maximumEdges + 1, controlDeps: control })
+        : slice?.root ??
+            (identity.key === undefined
+                ? causalChain(scope.log, identity.runtimeStageId, lookup, {
+                    maxDepth: 1,
+                    maxNodes: maximumEdges + 1,
+                    controlDeps: control,
+                })
+                : undefined);
+    if (root?.preRunReads?.keys.length)
+        coverage.addGap('untracked-input');
+    if (root?.truncated?.byNodes)
+        coverage.addGap('edge-limit');
+    for (const note of slice?.notes ?? [])
+        if (note.code === 'redacted')
+            coverage.addGap('redacted');
+        else if (note.code === 'nested-rows' || note.code === 'from-initial-state')
+            coverage.addGap('conservative');
+    const edges = projectParentEdges(scope, root?.parentEdges ?? [], firstCommitIndex, precise, maximumEdges, coverage.addGap);
+    return { adjacency: { edges, complete: coverage.gaps.length === 0 }, gaps: coverage.gaps };
+}

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

@@ -0,0 +1,8 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { PreparedRecordScope, RecordGraphOptions, RecordScope } from './recordTypes.js';
+/** Read configuration as data so option accessors cannot execute during adapter construction. */
+export declare function recordOptions(options: RecordGraphOptions): Required<RecordGraphOptions>;
+/** Spend one shared field budget before canonical readers see any untrusted scope data. */
+export declare function prepareRecordScope(value: RecordScope, address: LogAddress, maximumCommits: number, maximumFields: number): PreparedRecordScope;
+/** Preserve both stage reads and stronger per-write prefixes, including their original encounter order. */
+export declare function readKeysForStage(scope: PreparedRecordScope, runtimeStageId: string): string[];

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

@@ -0,0 +1,60 @@
+import { addressKey, addressOf, bundleOf, list, mapOf, marksOf, name, names, own, 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;
+    if (typeof configuredValue !== 'number' ||
+        !Number.isSafeInteger(configuredValue) ||
+        configuredValue < 1 ||
+        configuredValue > maximum)
+        throw new TypeError('cause: invalid record configuration');
+    return configuredValue;
+}
+/** Read configuration as data so option accessors cannot execute during adapter construction. */
+export function recordOptions(options) {
+    try {
+        const prototype = Object.getPrototypeOf(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),
+        });
+    }
+    catch {
+        throw new TypeError('cause: invalid record configuration');
+    }
+}
+/** 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))
+        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 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 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 };
+}
+/** Preserve both stage reads and stronger per-write prefixes, including their original encounter order. */
+export function readKeysForStage(scope, runtimeStageId) {
+    // Captured per-write prefixes remain evidence even when a supplied stage-read map omits them.
+    return [
+        ...new Set([
+            ...(scope.reads?.get(runtimeStageId) ?? []),
+            ...scope.log
+                .filter((bundle) => bundle.runtimeStageId === runtimeStageId)
+                .flatMap((bundle) => bundle.trace.flatMap((entry) => entry.readKeys ?? [])),
+        ]),
+    ];
+}

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

@@ -0,0 +1,67 @@
+import type { ControlDependency } from '../memory/backtrack.js';
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { CommitBundle } from '../memory/types.js';
+import type { Adjacency, Attention, CauseGraph, Gap, GraphContext, NodeId } from './types.js';
+/** Explicit complete maps record absence too; an omitted map means it was not collected. */
+export interface RecordScope {
+    readonly address: LogAddress;
+    readonly commitLog: readonly unknown[];
+    readonly reads?: Readonly<Record<string, readonly string[]>>;
+    readonly controlDeps?: Readonly<Record<string, {
+        readonly deciderId: string;
+    }>>;
+    readonly attention?: Readonly<Record<string, readonly Attention[]>>;
+    readonly complete?: boolean;
+}
+export interface RecordNode {
+    readonly runtimeStageId: string;
+    readonly commitIdx?: number;
+    readonly key?: string;
+}
+export interface RecordGraphOptions {
+    readonly maxCommits?: number;
+    readonly maxFields?: number;
+    readonly maxEdges?: number;
+    readonly maxScopes?: number;
+    readonly loadTimeoutMs?: number;
+}
+export interface RecordCauseGraph extends CauseGraph {
+    nodeId(address: LogAddress, node: RecordNode): NodeId;
+    /** Rejects with fixed message/code on discovery failure; never reports an unavailable scope as empty. */
+    openScope(address: LogAddress, context: GraphContext): Promise<readonly NodeId[]>;
+}
+export interface RecordLoaderResult {
+    readonly scope: RecordScope;
+    readonly gaps?: readonly Gap['code'][];
+}
+export interface RecordIdentity extends RecordNode {
+    readonly address: LogAddress;
+    readonly read?: true;
+}
+export interface PreparedRecordScope {
+    address: LogAddress;
+    log: CommitBundle[];
+    reads?: Map<string, string[]>;
+    control?: Map<string, ControlDependency>;
+    marks?: Map<string, readonly Attention[]>;
+    complete: boolean;
+}
+export interface RecordLoadFailure {
+    failure: Gap['code'];
+}
+export type LoadedRecordScope = PreparedRecordScope | RecordLoadFailure;
+export interface ResolvedRecordNode {
+    scope: PreparedRecordScope;
+    identity: RecordIdentity;
+    commitIndex: number;
+}
+export interface RecordInspection {
+    adjacency: Adjacency;
+    gaps: readonly Gap[];
+}
+export type RecordScopeHost = (address: LogAddress, context: GraphContext) => RecordLoaderResult | Promise<RecordLoaderResult>;
+export interface RecordScopeLoader {
+    loadScope(address: LogAddress, context: GraphContext): Promise<LoadedRecordScope>;
+    extraGapCodes(scope: PreparedRecordScope): readonly Gap['code'][] | undefined;
+}
+export type AddRecordGap = (code: Gap['code']) => void;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,33 @@
+/** Admission before the existing readers touch untrusted record fields. Payloads never leave this module's graph. */
+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';
+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 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 addressOf(value: unknown): LogAddress;
+export declare function spend(budget: {
+    left: number;
+}, count: number): void;
+export declare const addressKey: (a: LogAddress) => string;
+/** Iterative bounded copy: data descriptors only, no getters/toJSON/prototypes or opaque class instances. */
+export declare function dataCopy(value: unknown, budget: {
+    left: number;
+}): unknown;
+export declare function bundleOf(value: unknown, idx: number, budget: {
+    left: number;
+}): CommitBundle;
+export declare function mapOf<T>(value: unknown, limit: number, read: (v: unknown) => T, budget?: {
+    left: number;
+}): Map<string, T> | undefined;
+/** Observe native promises by intrinsic without assimilating a data object's then accessor. */
+export declare function projectLoaded<T, R>(work: () => T | Promise<T>, project: (value: T) => R): Promise<R>;