foottrace 1.1.0 → 1.3.0

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 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.recordOwn)(fields, 'address')), runtimeStageId = (0, recordValidation_js_1.recordName)((0, recordValidation_js_1.recordOwn)(fields, 'runtimeStageId')), commitIndex = (0, recordValidation_js_1.recordOwn)(fields, 'commitIdx'), key = (0, recordValidation_js_1.recordOwn)(fields, 'key'), read = (0, recordValidation_js_1.recordOwn)(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.recordName)(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.recordName)((0, recordValidation_js_1.recordOwn)(node, 'runtimeStageId')), commitIndex = (0, recordValidation_js_1.recordOwn)(node, 'commitIdx'), key = (0, recordValidation_js_1.recordOwn)(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.recordName)(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/recordInspection.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectRecordNode = void 0;
+const backtrack_js_1 = require("../memory/backtrack.js");
+const commitLogUtils_js_1 = require("../memory/commitLogUtils.js");
+const sliceForKey_js_1 = require("../slice/sliceForKey.js");
+const recordControl_js_1 = require("./recordControl.js");
+const recordCoverage_js_1 = require("./recordCoverage.js");
+const recordIdentity_js_1 = require("./recordIdentity.js");
+const recordScope_js_1 = require("./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
+            ? (0, commitLogUtils_js_1.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: (0, recordIdentity_js_1.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. */
+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 = (0, recordCoverage_js_1.recordGapCollector)();
+    (0, recordCoverage_js_1.collectScopeCoverage)(scope, bundle, extraGapCodes, coverage.addGap);
+    const lookup = (runtimeStageId) => (0, recordScope_js_1.readKeysForStage)(scope, runtimeStageId);
+    (0, recordCoverage_js_1.collectForwardCoverage)(scope, identity, commitIndex, firstCommitIndex, maximumEdges, coverage.addGap);
+    const precise = (0, recordCoverage_js_1.readAttributionIsPrecise)(scope, identity, bundle);
+    (0, recordCoverage_js_1.collectReadCoverage)(scope, identity, precise, coverage.addGap);
+    (0, recordControl_js_1.collectControlParentCoverage)(scope, identity, firstCommitIndex, coverage.addGap);
+    const control = (0, recordControl_js_1.controlParentLookup)(scope);
+    const slice = identity.key === undefined || identity.read
+        ? undefined
+        : (0, sliceForKey_js_1.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
+        ? (0, backtrack_js_1.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
+                ? (0, backtrack_js_1.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 };
+}
+exports.inspectRecordNode = inspectRecordNode;

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.recordOwn)(result, 'scope'), request.address, limits.maxCommits, limits.maxFields);
+        const extra = (0, recordValidation_js_1.recordList)((0, recordValidation_js_1.recordOwn)(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;

package/dist/lib/cause/recordQuery.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whenResolved = exports.createRecordQuery = void 0;
+const queryMemo_js_1 = require("./queryMemo.js");
+const recordIdentity_js_1 = require("./recordIdentity.js");
+const recordInspection_js_1 = require("./recordInspection.js");
+/** Both dependency directions share the same admitted node and canonical inspection within a query. */
+function createRecordQuery(loader, maximumEdges) {
+    const resolutionOwner = {}, inspectionOwner = {};
+    return {
+        resolve(nodeId, context) {
+            const resolve = () => (0, recordIdentity_js_1.resolveRecordNode)(nodeId, context, loader), memo = (0, queryMemo_js_1.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 = () => (0, recordInspection_js_1.inspectRecordNode)(node, maximumEdges, loader.extraGapCodes(node.scope));
+            return (0, queryMemo_js_1.queryMemo)(context)?.remember(inspectionOwner, node, inspect) ?? inspect();
+        },
+    };
+}
+exports.createRecordQuery = createRecordQuery;
+/** Every port maps the same fixed loading failure while projecting only admitted nodes. */
+function whenResolved(node, onNode, onFailure) {
+    return 'failure' in node ? onFailure(node) : onNode(node);
+}
+exports.whenResolved = whenResolved;

package/dist/lib/cause/recordScope.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readKeysForStage = exports.prepareRecordScope = exports.recordOptions = void 0;
+const recordValidation_js_1 = require("./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. */
+function recordOptions(options) {
+    try {
+        const prototype = Object.getPrototypeOf(options);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new TypeError();
+        return Object.freeze({
+            maxCommits: boundedOption((0, recordValidation_js_1.recordOwn)(options, 'maxCommits'), 256, 4096),
+            maxFields: boundedOption((0, recordValidation_js_1.recordOwn)(options, 'maxFields'), 20000, 1000000),
+            maxEdges: boundedOption((0, recordValidation_js_1.recordOwn)(options, 'maxEdges'), 64, 256),
+            maxScopes: boundedOption((0, recordValidation_js_1.recordOwn)(options, 'maxScopes'), 32, 256),
+            loadTimeoutMs: boundedOption((0, recordValidation_js_1.recordOwn)(options, 'loadTimeoutMs'), 1000, 30000),
+        });
+    }
+    catch {
+        throw new TypeError('cause: invalid record configuration');
+    }
+}
+exports.recordOptions = recordOptions;
+/** Spend one shared field budget before canonical readers see any untrusted scope data. */
+function prepareRecordScope(value, address, maximumCommits, maximumFields) {
+    if ((0, recordValidation_js_1.addressKey)((0, recordValidation_js_1.addressOf)((0, recordValidation_js_1.recordOwn)(value, 'address'))) !== (0, recordValidation_js_1.addressKey)(address))
+        throw new recordValidation_js_1.RecordRefusal();
+    const rawLog = (0, recordValidation_js_1.recordList)((0, recordValidation_js_1.recordOwn)(value, 'commitLog'), maximumCommits), budget = { left: maximumFields };
+    const log = rawLog.map((_, commitIndex) => (0, recordValidation_js_1.bundleOf)((0, recordValidation_js_1.recordOwn)(rawLog, String(commitIndex)), commitIndex, budget));
+    const reads = (0, recordValidation_js_1.mapOf)((0, recordValidation_js_1.recordOwn)(value, 'reads'), maximumCommits, (value) => {
+        const readKeys = (0, recordValidation_js_1.names)(value, 128, true);
+        (0, recordValidation_js_1.spend)(budget, readKeys.length);
+        return readKeys;
+    }, budget);
+    const control = (0, recordValidation_js_1.mapOf)((0, recordValidation_js_1.recordOwn)(value, 'controlDeps'), maximumCommits, (value) => ({ deciderId: (0, recordValidation_js_1.recordName)((0, recordValidation_js_1.recordOwn)(value, 'deciderId')) }), budget);
+    const marks = (0, recordValidation_js_1.mapOf)((0, recordValidation_js_1.recordOwn)(value, 'attention'), maximumCommits, (value) => {
+        const attention = (0, recordValidation_js_1.marksOf)(value);
+        (0, recordValidation_js_1.spend)(budget, attention.length + attention.reduce((count, mark) => count + mark.evidence.length, 0));
+        return attention;
+    }, budget);
+    return { address, log, reads, control, marks, complete: (0, recordValidation_js_1.recordOwn)(value, 'complete') === true };
+}
+exports.prepareRecordScope = prepareRecordScope;
+/** Preserve both stage reads and stronger per-write prefixes, including their original encounter order. */
+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 ?? [])),
+        ]),
+    ];
+}
+exports.readKeysForStage = readKeysForStage;

package/dist/lib/cause/recordTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });