foottrace 1.1.0 → 1.3.0

package/dist/lib/cause/walk.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathTo = exports.frontier = exports.walk = void 0;
+const validation_js_1 = require("./validation.js");
+/** BFS discovers the shallowest arrival; a repeated diamond node is not a cycle. */
+async function walk(session, seeds, direction) {
+    const queue = [], seen = new Set(), marks = [], edges = [], missing = [];
+    const enqueue = (id, depth) => {
+        if (seen.has(id))
+            return;
+        const refusal = session.admit(id);
+        if (refusal) {
+            missing.push(refusal);
+            return;
+        }
+        seen.add(id);
+        queue.push([id, depth]);
+    };
+    for (const id of seeds)
+        enqueue(id, 0);
+    for (let index = 0; index < queue.length; index++) {
+        const [id, depth] = queue[index], stopped = session.stopGap(id);
+        if (stopped) {
+            missing.push(stopped);
+            break;
+        }
+        const marked = await session.read('attention', id, validation_js_1.attention);
+        if (marked.gap)
+            missing.push(marked.gap);
+        if (marked.value?.length) {
+            marks.push(Object.freeze({ nodeId: id, attention: marked.value }));
+            if (marked.value.some((item) => item.kind === 'not-collected'))
+                missing.push((0, validation_js_1.gap)('not-collected', id));
+        }
+        const coverage = await session.read('gaps', id, validation_js_1.gaps);
+        if (coverage.gap)
+            missing.push(coverage.gap);
+        if (coverage.value)
+            missing.push(...coverage.value);
+        const page = await session.read(direction, id, (raw) => (0, validation_js_1.adjacency)(raw, session.limits.maxEdges));
+        if (page.gap) {
+            missing.push(page.gap);
+            continue;
+        }
+        if (!page.value)
+            continue;
+        if (!page.value.complete)
+            missing.push((0, validation_js_1.gap)('not-collected', id));
+        if (depth >= session.limits.maxDepth) {
+            if (page.value.edges.length)
+                missing.push((0, validation_js_1.gap)('depth-limit', id));
+            continue;
+        }
+        for (const edge of page.value.edges) {
+            if (session.edges >= session.limits.maxEdges) {
+                missing.push((0, validation_js_1.gap)('edge-limit', id));
+                break;
+            }
+            session.edges++;
+            const refusal = session.admit(edge.nodeId);
+            if (refusal) {
+                missing.push(refusal);
+                continue;
+            }
+            edges.push(Object.freeze({
+                from: id,
+                to: edge.nodeId,
+                kind: edge.kind,
+                attribution: edge.attribution,
+                evidence: edge.evidence,
+            }));
+            if (edge.attribution === 'stage')
+                missing.push((0, validation_js_1.gap)('conservative', id));
+            enqueue(edge.nodeId, depth + 1);
+        }
+    }
+    if (hasCycle(edges))
+        missing.push((0, validation_js_1.gap)('cycle'));
+    return Object.freeze({
+        nodes: Object.freeze(queue.map((row) => row[0])),
+        marked: Object.freeze(marks),
+        edges: Object.freeze(edges),
+        gaps: (0, validation_js_1.uniqueGaps)(missing),
+    });
+}
+exports.walk = walk;
+/** Iterative three-colour walk; shared nodes remain distinguishable from back edges. */
+function hasCycle(edges) {
+    const next = new Map();
+    for (const edge of edges) {
+        if (!next.has(edge.from))
+            next.set(edge.from, []);
+        next.get(edge.from).push(edge.to);
+    }
+    const state = new Map();
+    for (const seed of next.keys()) {
+        if (state.has(seed))
+            continue;
+        const stack = [[seed, 0]];
+        state.set(seed, 1);
+        while (stack.length) {
+            const frame = stack[stack.length - 1], children = next.get(frame[0]) ?? [];
+            if (frame[1] >= children.length) {
+                state.set(frame[0], 2);
+                stack.pop();
+                continue;
+            }
+            const child = children[frame[1]++];
+            if (state.get(child) === 1)
+                return true;
+            if (!state.has(child)) {
+                state.set(child, 1);
+                stack.push([child, 0]);
+            }
+        }
+    }
+    return false;
+}
+function frontier(result) {
+    const marked = new Set(result.marked
+        .filter((item) => item.attention.some((mark) => mark.kind !== 'not-collected'))
+        .map((item) => item.nodeId));
+    const pending = new Map(result.nodes.map((id) => [id, 0]));
+    const dependents = new Map();
+    for (const edge of result.edges) {
+        pending.set(edge.from, (pending.get(edge.from) ?? 0) + 1);
+        if (!dependents.has(edge.to))
+            dependents.set(edge.to, []);
+        dependents.get(edge.to).push(edge.from);
+    }
+    // Process causal ancestors first, propagating one boolean through the DAG.
+    // This is O(nodes + edges), rather than a fresh ancestry scan per marked node.
+    const queue = [...pending].filter(([, count]) => count === 0).map(([id]) => id);
+    const earlierMark = new Set(), eligible = new Set();
+    for (let i = 0; i < queue.length; i++) {
+        const id = queue[i];
+        if (marked.has(id) && !earlierMark.has(id))
+            eligible.add(id);
+        for (const dependent of dependents.get(id) ?? []) {
+            if (marked.has(id) || earlierMark.has(id))
+                earlierMark.add(dependent);
+            const count = pending.get(dependent) - 1;
+            pending.set(dependent, count);
+            if (count === 0)
+                queue.push(dependent);
+        }
+    }
+    // Nodes left in a cycle cannot supply a validated earliest ancestor.
+    return result.marked.filter((item) => eligible.has(item.nodeId));
+}
+exports.frontier = frontier;
+function pathTo(edges, start, target) {
+    const queue = [start], previous = new Map([[start, undefined]]);
+    const next = new Map();
+    for (const edge of edges) {
+        if (!next.has(edge.from))
+            next.set(edge.from, []);
+        next.get(edge.from).push(edge.to);
+    }
+    for (let i = 0; i < queue.length; i++) {
+        const id = queue[i];
+        if (id === target)
+            break;
+        for (const child of next.get(id) ?? [])
+            if (!previous.has(child)) {
+                previous.set(child, id);
+                queue.push(child);
+            }
+    }
+    if (!previous.has(target))
+        return Object.freeze([]);
+    const path = [];
+    let id = target;
+    while (id !== undefined) {
+        path.push(id);
+        id = previous.get(id);
+    }
+    return Object.freeze(path.reverse());
+}
+exports.pathTo = pathTo;

package/dist/lib/evidence/admission.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spendFields = exports.boundedList = exports.boundedName = exports.ownData = exports.EvidenceRefusal = void 0;
+/** One refusal representation; subclasses preserve the graph-port and record-loader boundaries. */
+class EvidenceRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+exports.EvidenceRefusal = EvidenceRefusal;
+/** Read data descriptors only; each boundary keeps its existing treatment of proxy traps. */
+function ownData(value, key, refuse, policy) {
+    if (!value || typeof value !== 'object')
+        throw refuse();
+    let descriptor;
+    if (policy.translateTrapErrors) {
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(value, key);
+        }
+        catch {
+            throw refuse();
+        }
+    }
+    else
+        descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor)
+        return undefined;
+    if (policy.requireOwnValue ? !Object.hasOwn(descriptor, 'value') : !('value' in descriptor))
+        throw refuse();
+    return descriptor.value;
+}
+exports.ownData = ownData;
+/** Names share one grammar, with explicit limits and the record path separator exception. */
+function boundedName(value, maximum, refuse, path = false) {
+    if (typeof value !== 'string' ||
+        !value.length ||
+        value.length > maximum ||
+        (path ? /[\u0000-\u001e\u007f-\u009f]/ : /[\u0000-\u001f\u007f-\u009f]/).test(value))
+        throw refuse();
+    return value;
+}
+exports.boundedName = boundedName;
+/** Bound iteration before reading entries, without invoking element accessors. */
+function boundedList(value, maximum, read, options) {
+    const { refuse, overflow, freeze, descriptors } = options;
+    let array;
+    if (options.translateArrayErrors) {
+        try {
+            array = Array.isArray(value);
+        }
+        catch {
+            throw refuse();
+        }
+    }
+    else
+        array = Array.isArray(value);
+    if (!array)
+        throw refuse();
+    const length = ownData(value, 'length', refuse, descriptors);
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+        throw refuse();
+    if (options.expectedLength !== undefined && length !== options.expectedLength)
+        throw refuse();
+    if (length > maximum)
+        throw refuse(overflow);
+    const result = [];
+    for (let index = 0; index < length; index++)
+        result.push(read(ownData(value, String(index), refuse, descriptors)));
+    return freeze ? Object.freeze(result) : result;
+}
+exports.boundedList = boundedList;
+/** Charge retained fields against the same mutable allowance across admission helpers. */
+function spendFields(budget, count, refuse) {
+    budget.left -= count;
+    if (budget.left < 0)
+        throw refuse('node-limit');
+}
+exports.spendFields = spendFields;

package/dist/lib/evidence/codes.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRequirementReason = exports.isGapCode = exports.GAP_CODES = void 0;
+/** One vocabulary; true marks a domain evidence reason, false a trace/admission gap only. */
+exports.GAP_CODES = Object.freeze({
+    'not-collected': true,
+    'untracked-input': false,
+    redacted: true,
+    conservative: false,
+    'scope-boundary': false,
+    'invalid-data': true,
+    unavailable: true,
+    timeout: true,
+    cancelled: false,
+    cycle: false,
+    'node-limit': false,
+    'depth-limit': false,
+    'edge-limit': false,
+    'call-limit': false,
+    truncated: false,
+    'strategy-failed': false,
+    'not-checked': true,
+    'no-match': true,
+    ambiguous: true,
+    stale: true,
+    incompatible: true,
+    unsupported: true,
+    'not-permitted': true,
+});
+const isGapCode = (value) => typeof value === 'string' && Object.hasOwn(exports.GAP_CODES, value);
+exports.isGapCode = isGapCode;
+const isRequirementReason = (value) => (0, exports.isGapCode)(value) && exports.GAP_CODES[value];
+exports.isRequirementReason = isRequirementReason;

package/dist/lib/evidence/requirementTypes.js

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

package/dist/lib/evidence/requirements.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRequirementResults = exports.RequirementValidationError = exports.REQUIREMENT_RESULT_LIMITS = void 0;
+const admission_js_1 = require("./admission.js");
+const codes_js_1 = require("./codes.js");
+/** Fixed per-call ceilings; characters are UTF-16 code units, not serialized transport bytes. */
+exports.REQUIREMENT_RESULT_LIMITS = Object.freeze({
+    results: 512,
+    checks: 16,
+    affects: 32,
+    refs: 16,
+    name: 512,
+    fields: 32768,
+    characters: 1048576,
+});
+/** No input, field value or originating exception is retained on a refusal. */
+class RequirementValidationError extends admission_js_1.EvidenceRefusal {
+    constructor(code = 'invalid-data') {
+        super(code, 'REQUIREMENT_RESULTS_INVALID');
+    }
+}
+exports.RequirementValidationError = RequirementValidationError;
+const refuse = (code) => new RequirementValidationError(code);
+const descriptors = { translateTrapErrors: true, requireOwnValue: true };
+const own = (value, key) => (0, admission_js_1.ownData)(value, key, refuse, descriptors);
+const resultKeys = new Set([
+    'id',
+    'requirementRef',
+    'findingRef',
+    'windowRef',
+    'affects',
+    'state',
+    'reason',
+    'detail',
+    'evidenceRefs',
+    'checks',
+    'actionRefs',
+    'validTimeRef',
+    'learnedTimeRef',
+]);
+const checkKeys = new Set(['checkRef', 'disposition', 'reason', 'detail', 'evidenceRefs', 'attemptRefs']);
+const dispositions = new Set([
+    'checked-pass',
+    'checked-fail',
+    'unreachable',
+    'not-applicable',
+]);
+/** Closed objects expose no unknown payloads. Never invoke data accessors, iterators or toJSON. */
+function object(value, keys, budget) {
+    if (!value || typeof value !== 'object')
+        throw refuse();
+    let prototype;
+    let fields;
+    try {
+        prototype = Object.getPrototypeOf(value);
+        fields = Reflect.ownKeys(value);
+    }
+    catch {
+        throw refuse();
+    }
+    if (prototype !== Object.prototype && prototype !== null)
+        throw refuse();
+    if (fields.length > keys.size || fields.some((field) => typeof field !== 'string' || !keys.has(field)))
+        throw refuse();
+    (0, admission_js_1.spendFields)(budget, fields.length, refuse);
+    // Including optional own fields: an own accessor is never treated as an absent field.
+    for (const field of fields)
+        own(value, field);
+}
+function list(value, maximum, read, budget) {
+    try {
+        if (!Array.isArray(value))
+            throw refuse();
+    }
+    catch {
+        throw refuse();
+    }
+    const length = own(value, 'length');
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+        throw refuse();
+    if (length > maximum)
+        throw refuse('node-limit');
+    let prototype;
+    let keys;
+    try {
+        prototype = Object.getPrototypeOf(value);
+        keys = Reflect.ownKeys(value);
+    }
+    catch {
+        throw refuse();
+    }
+    if (prototype !== Array.prototype)
+        throw refuse();
+    if (keys.length !== length + 1 ||
+        keys.some((key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= length)))
+        throw refuse();
+    (0, admission_js_1.spendFields)(budget, length + 1, refuse);
+    return (0, admission_js_1.boundedList)(value, maximum, read, {
+        refuse,
+        overflow: 'node-limit',
+        freeze: true,
+        descriptors,
+        expectedLength: length,
+        translateArrayErrors: true,
+    });
+}
+function name(value, budget) {
+    const result = (0, admission_js_1.boundedName)(value, exports.REQUIREMENT_RESULT_LIMITS.name, refuse);
+    if (/\s/u.test(result))
+        throw refuse();
+    budget.characters -= result.length;
+    if (budget.characters < 0)
+        throw refuse('node-limit');
+    return result;
+}
+function unique(items, key) {
+    if (new Set(items.map(key)).size !== items.length)
+        throw refuse();
+    return items;
+}
+function refs(value, budget, maximum = exports.REQUIREMENT_RESULT_LIMITS.refs) {
+    return unique(list(value, maximum, (item) => name(item, budget), budget), (item) => item);
+}
+function reason(value) {
+    if (!(0, codes_js_1.isRequirementReason)(value))
+        throw refuse();
+    return value;
+}
+function optionalName(value, key, budget) {
+    const raw = own(value, key);
+    return raw === undefined ? undefined : name(raw, budget);
+}
+function detail(value, budget) {
+    const id = optionalName(value, 'detail', budget);
+    if (id !== undefined && !/^[A-Za-z][A-Za-z0-9_.-]*:.+$/.test(id))
+        throw refuse();
+    return id;
+}
+function check(value, budget) {
+    object(value, checkKeys, budget);
+    const checkRef = name(own(value, 'checkRef'), budget), disposition = own(value, 'disposition');
+    if (typeof disposition !== 'string' || !dispositions.has(disposition))
+        throw refuse();
+    const rawReason = own(value, 'reason'), detailId = detail(value, budget);
+    return Object.freeze({
+        checkRef,
+        disposition: disposition,
+        ...(rawReason === undefined ? {} : { reason: reason(rawReason) }),
+        ...(detailId === undefined ? {} : { detail: detailId }),
+        evidenceRefs: refs(own(value, 'evidenceRefs'), budget),
+        attemptRefs: refs(own(value, 'attemptRefs'), budget),
+    });
+}
+function result(value, budget) {
+    object(value, resultKeys, budget);
+    const id = name(own(value, 'id'), budget), requirementRef = name(own(value, 'requirementRef'), budget), findingRef = name(own(value, 'findingRef'), budget), windowRef = name(own(value, 'windowRef'), budget), state = own(value, 'state'), rawReason = own(value, 'reason');
+    if (state !== 'satisfied' && state !== 'unresolved')
+        throw refuse();
+    if (state === 'satisfied' && rawReason !== undefined)
+        throw refuse();
+    const affects = refs(own(value, 'affects'), budget, exports.REQUIREMENT_RESULT_LIMITS.affects);
+    if (!affects.length)
+        throw refuse();
+    const evidenceRefs = refs(own(value, 'evidenceRefs'), budget), checks = unique(list(own(value, 'checks'), exports.REQUIREMENT_RESULT_LIMITS.checks, (item) => check(item, budget), budget), (item) => item.checkRef), actionRefs = refs(own(value, 'actionRefs'), budget), detailId = detail(value, budget), validTimeRef = optionalName(value, 'validTimeRef', budget), learnedTimeRef = optionalName(value, 'learnedTimeRef', budget);
+    const binding = {
+        id,
+        requirementRef,
+        findingRef,
+        windowRef,
+        affects,
+        evidenceRefs,
+        checks,
+        actionRefs,
+        ...(detailId === undefined ? {} : { detail: detailId }),
+        ...(validTimeRef === undefined ? {} : { validTimeRef }),
+        ...(learnedTimeRef === undefined ? {} : { learnedTimeRef }),
+    };
+    return Object.freeze(state === 'unresolved' ? { ...binding, state, reason: reason(rawReason) } : { ...binding, state });
+}
+/**
+ * Atomically project detached, frozen reference-only records. This is structural admission only.
+ * The host must authenticate producers, resolve authorized artifacts, verify current query/run/scope and
+ * domain validity, and enforce every unresolved affects reference before rendering any factual claim.
+ * Identifier grammar does not classify secrets; producers must supply non-secret identifiers only.
+ */
+function readRequirementResults(value) {
+    const budget = { left: exports.REQUIREMENT_RESULT_LIMITS.fields, characters: exports.REQUIREMENT_RESULT_LIMITS.characters };
+    return unique(list(value, exports.REQUIREMENT_RESULT_LIMITS.results, (item) => result(item, budget), budget), (item) => item.id);
+}
+exports.readRequirementResults = readRequirementResults;

package/dist/lib/memory/types.js

@@ -3,7 +3,7 @@
  * types.ts — the record's types: a bundle, its rows, its patches, its encoding, and the
  * execution tree as the record's readers read it.
  *
- * Imports nothing. The standalone record names nothing outside itself: the engine's frame
+ * Imports only the record's leaf attention type. The record names nothing outside itself: the engine's frame
  * types — the stage snapshot, flow messages and retention dials — remain in FootPrint's
  * `frameTypes.ts`. The closed record graph is enforced by scripts/check-layering.mjs.
  */

package/dist/types/cause.d.ts

@@ -0,0 +1,8 @@
+/** Optional read-only cause and impact queries over recorded dependency graphs. */
+export { explain, attentionList } from './lib/cause/explain.js';
+export { largestDrop, mostAffected } from './lib/cause/strategies.js';
+export { createRecordGraph } from './lib/cause/recordAdapter.js';
+export { createStoredRecordGraph } from './lib/cause/storedRecordAdapter.js';
+export type { Adjacency, AttentionListOptions, AttentionListResult, AttentionReason, CauseGraph, CauseResult, Confidence, ExplainOptions, Gap, GapCode, GraphContext, GraphEdge, ImpactResult, ImpactStrategy, MarkedNode, MaybePromise, NodeId, RootStrategy, TraversedEdge, WalkLimits, } from './lib/cause/types.js';
+export type { RecordScope, RecordGraphOptions, RecordCauseGraph, RecordNode } from './lib/cause/recordAdapter.js';
+export type { StoredRecordScope, StoredRecordHost } from './lib/cause/storedRecordAdapter.js';

package/dist/types/index.d.ts

@@ -28,3 +28,9 @@ export type { EmitSourcePosition, LogAddress } from './lib/memory/eventPosition.
 export { EXECUTION_DELIMITER, PATH_DELIMITER, isExecutionKey, joinPath, pathSegments as idPathSegments, stageIdOf, subflowSegmentsOf, } from './lib/ids/runtimeStageId.js';
 export { deepEqual } from './lib/memory/equality.js';
 export { serveRecord } from './lib/capture/freeze.js';
+/** Record attention types are shared with producers; the optional cause reader has its own door. */
+export type { Attention, AttentionKind } from './lib/cause/types.js';
+/** Reference-only requirement records: structural admission never grants authority or verifies domain truth. */
+export type { RequirementReason } from './lib/evidence/codes.js';
+export type { RequirementCheck, RequirementCheckDisposition, RequirementResult, } from './lib/evidence/requirementTypes.js';
+export { readRequirementResults, RequirementValidationError, REQUIREMENT_RESULT_LIMITS, } from './lib/evidence/requirements.js';

package/dist/types/lib/cause/explain.d.ts

@@ -0,0 +1,5 @@
+import type { AttentionListOptions, AttentionListResult, CauseGraph, CauseResult, ExplainOptions, NodeId } from './types.js';
+/** Read-only deterministic cause localisation and impact. No inference from timestamps or structural ancestry. */
+export declare function explain(graph: CauseGraph, nodeId: NodeId, options?: ExplainOptions): Promise<CauseResult>;
+/** Discover only bounded host seeds; this is not a global scan of arbitrary storage. */
+export declare function attentionList(graph: CauseGraph, options?: AttentionListOptions): Promise<AttentionListResult>;

package/dist/types/lib/cause/queryMemo.d.ts

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

package/dist/types/lib/cause/ranking.d.ts

@@ -0,0 +1,6 @@
+import type { NodeId } from './types.js';
+/** Strategies may only select admitted nodes; impact ranking must preserve the full set. */
+export declare function admitRanking(raw: unknown, allowed: ReadonlySet<NodeId>, options: {
+    readonly exactPermutation: boolean;
+    readonly maximum: number;
+}): readonly NodeId[];

package/dist/types/lib/cause/recordAdapter.d.ts

@@ -0,0 +1,9 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { RecordCauseGraph, RecordGraphOptions, RecordLoaderResult, RecordScope } from './recordTypes.js';
+import type { GraphContext } from './types.js';
+export type { RecordCauseGraph, RecordGraphOptions, RecordLoaderResult, RecordNode, RecordScope, } from './recordTypes.js';
+export { recordOptions } from './recordScope.js';
+/** Common engine for memory and one-scope-at-a-time host storage. Loader functions are trusted executable code. */
+export declare function createLazyRecordGraph(load: (address: LogAddress, context: GraphContext) => RecordLoaderResult | Promise<RecordLoaderResult>, options?: RecordGraphOptions): RecordCauseGraph;
+/** A finished record already in memory; payload admission is lazy per requested scope. */
+export declare function createRecordGraph(scopes: readonly RecordScope[], options?: RecordGraphOptions): RecordCauseGraph;

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

@@ -0,0 +1,4 @@
+import type { RecordInspection, ResolvedRecordNode } from './recordTypes.js';
+import type { Adjacency } from './types.js';
+/** Share parent-side coverage checks before appending data then control children in their established order. */
+export declare function childrenForRecordNode(node: ResolvedRecordNode, maximumEdges: number, inspection: RecordInspection): Adjacency;

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

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

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

@@ -0,0 +1,24 @@
+import type { CommitBundle } from '../memory/types.js';
+import type { AddRecordGap, PreparedRecordScope, RecordIdentity, ResolvedRecordNode } from './recordTypes.js';
+import type { Attention, Gap } from './types.js';
+/** Preserve first-observed coverage order while collapsing repeated codes from different evidence paths. */
+export declare function recordGapCollector(): {
+    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): 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/types/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/types/lib/cause/recordInspection.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/types/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/types/lib/cause/recordQuery.d.ts

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

package/dist/types/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[];