foottrace 1.1.0 → 1.2.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/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,5 @@ 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';

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

@@ -0,0 +1,27 @@
+import type { GapCode } from './types.js';
+/** One refusal representation; subclasses preserve the graph-port and record-loader boundaries. */
+export declare class EvidenceRefusal extends Error {
+    readonly code: GapCode;
+    constructor(code: GapCode, message: string);
+}
+export type RefuseEvidence = (code?: GapCode) => Error;
+interface DescriptorPolicy {
+    readonly translateTrapErrors: boolean;
+    readonly requireOwnValue: boolean;
+}
+/** Read data descriptors only; each boundary keeps its existing treatment of proxy traps. */
+export declare function ownData(value: unknown, key: string, refuse: RefuseEvidence, policy: DescriptorPolicy): unknown;
+/** Names share one grammar, with explicit limits and the record path separator exception. */
+export declare function boundedName(value: unknown, maximum: number, refuse: RefuseEvidence, path?: boolean): string;
+/** Bound iteration before reading entries, without invoking element accessors. */
+export declare function boundedList<T>(value: unknown, maximum: number, read: (item: unknown) => T, options: {
+    readonly refuse: RefuseEvidence;
+    readonly overflow: GapCode;
+    readonly freeze: boolean;
+    readonly descriptors: DescriptorPolicy;
+}): readonly T[];
+/** Charge retained fields against the same mutable allowance across admission helpers. */
+export declare function spendFields(budget: {
+    left: number;
+}, count: number, refuse: RefuseEvidence): void;
+export {};

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/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 { ResolvedRecordNode } from './recordTypes.js';
+import type { Adjacency, Gap } from './types.js';
+/** Share parent-side coverage checks before appending data then control children in their established order. */
+export declare function childrenForRecordNode(node: ResolvedRecordNode, maximumEdges: number, extraGapCodes: readonly Gap['code'][] | undefined): Adjacency;

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, 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/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/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/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/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[];

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

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

@@ -0,0 +1,30 @@
+import type { CauseGraph, ExplainOptions, Gap, GraphContext, NodeId, WalkLimits } from './types.js';
+export interface Read<T> {
+    readonly value?: T;
+    readonly gap?: Gap;
+}
+type Method = 'parents' | 'children' | 'attention' | 'gaps' | 'roots';
+/** One deadline, memo table and work budget per public query, never per graph or store. */
+export declare class Session {
+    readonly limits: Required<WalkLimits>;
+    readonly context: GraphContext;
+    readonly nodes: Set<string>;
+    readonly controller: AbortController;
+    private readonly cache;
+    private calls;
+    edges: number;
+    private timedOut;
+    private readonly deadline;
+    private readonly timer;
+    private readonly external?;
+    private readonly onAbort;
+    private readonly methods;
+    constructor(graph: CauseGraph, options?: ExplainOptions);
+    dispose(): void;
+    stopGap(id?: NodeId): Gap | undefined;
+    admit(id: NodeId): Gap | undefined;
+    hasRoots(): boolean;
+    read<T>(method: Method, id: NodeId | undefined, project: (raw: unknown) => T): Promise<Read<T>>;
+    invoke<T>(id: NodeId | undefined, work: () => unknown, project: (raw: unknown) => T): Promise<Read<T>>;
+}
+export {};

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

@@ -0,0 +1,11 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import { type RecordCauseGraph, type RecordGraphOptions, type RecordScope } from './recordAdapter.js';
+import type { GraphContext, MaybePromise } from './types.js';
+export interface StoredRecordScope extends Omit<RecordScope, 'address' | 'commitLog' | 'complete'> {
+    readonly entries: readonly unknown[];
+}
+export interface StoredRecordHost {
+    loadLog(address: LogAddress, context: GraphContext): MaybePromise<StoredRecordScope>;
+}
+/** Load one address only. The host owns auth/storage; cancellation is forwarded and waiting is independently bounded. */
+export declare function createStoredRecordGraph(host: StoredRecordHost, options?: RecordGraphOptions): RecordCauseGraph;

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

@@ -0,0 +1,3 @@
+import type { NodeId, RootStrategy } from './types.js';
+export declare const largestDrop: (scores: ReadonlyMap<NodeId, number>) => RootStrategy;
+export declare const mostAffected: (counts: ReadonlyMap<NodeId, number>) => RootStrategy;

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

@@ -0,0 +1,90 @@
+/** Names and evidence references only. No state values, messages, credentials or business payloads. */
+export type NodeId = string;
+export type AttentionKind = 'error' | 'unknown-effect' | 'gave-up' | 'timeout' | 'retried' | 'quality-drop' | 'not-collected' | 'outlier' | (string & {});
+export type AttentionReason = 'ERROR_RECORDED' | 'UNKNOWN_EFFECT_RECORDED' | 'RETRY_STOP_RECORDED' | 'TIMEOUT_RECORDED' | 'RETRY_RECORDED' | 'QUALITY_DROP_RECORDED' | 'EVIDENCE_NOT_COLLECTED' | 'OUTLIER_RECORDED' | 'BUSINESS_RULE_MATCHED';
+export interface Attention {
+    readonly kind: AttentionKind;
+    readonly reason: AttentionReason;
+    readonly evidence: readonly string[];
+}
+export type Confidence = 'complete' | 'incomplete';
+export type GapCode = 'not-collected' | 'untracked-input' | 'redacted' | 'conservative' | 'scope-boundary' | 'invalid-data' | 'unavailable' | 'timeout' | 'cancelled' | 'cycle' | 'node-limit' | 'depth-limit' | 'edge-limit' | 'call-limit' | 'truncated' | 'strategy-failed';
+export interface Gap {
+    readonly code: GapCode;
+    readonly nodeId?: NodeId;
+    readonly evidence: readonly string[];
+}
+export interface GraphEdge {
+    readonly nodeId: NodeId;
+    readonly kind: 'data' | 'control';
+    readonly attribution: 'per-write' | 'stage' | 'recorded-control';
+    readonly evidence: readonly string[];
+}
+export interface Adjacency {
+    readonly edges: readonly GraphEdge[];
+    readonly complete: boolean;
+}
+export interface GraphContext {
+    readonly signal: AbortSignal;
+}
+export type MaybePromise<T> = T | Promise<T>;
+/** A host owns storage, authentication and service resolution. A node may represent a key-qualified write. */
+export interface CauseGraph {
+    parents(id: NodeId, context: GraphContext): MaybePromise<Adjacency>;
+    children(id: NodeId, context: GraphContext): MaybePromise<Adjacency>;
+    attention(id: NodeId, context: GraphContext): MaybePromise<readonly Attention[]>;
+    gaps(id: NodeId, context: GraphContext): MaybePromise<readonly Gap[]>;
+    /** Optional, bounded discovery seeds; attentionList can instead receive explicit nodeIds. */
+    roots?(context: GraphContext): MaybePromise<readonly NodeId[]>;
+}
+export interface TraversedEdge extends Omit<GraphEdge, 'nodeId'> {
+    readonly from: NodeId;
+    readonly to: NodeId;
+}
+export interface MarkedNode {
+    readonly nodeId: NodeId;
+    readonly attention: readonly Attention[];
+}
+export interface ImpactResult {
+    readonly nodes: readonly NodeId[];
+    readonly edges: readonly TraversedEdge[];
+    readonly confidence: Confidence;
+    readonly gaps: readonly Gap[];
+}
+export interface CauseResult {
+    readonly nodeId: NodeId;
+    readonly attention: readonly Attention[];
+    /** Present only for one supported candidate and complete backward coverage. Not provider-internal proof. */
+    readonly rootCause?: NodeId;
+    /** Selected node → candidate, following recorded dependency edges. */
+    readonly path: readonly NodeId[];
+    readonly alternatives: readonly NodeId[];
+    readonly impact: ImpactResult;
+    readonly confidence: Confidence;
+    readonly gaps: readonly Gap[];
+}
+export interface AttentionListResult {
+    readonly nodes: readonly MarkedNode[];
+    readonly confidence: Confidence;
+    readonly gaps: readonly Gap[];
+}
+export interface WalkLimits {
+    readonly maxNodes?: number;
+    readonly maxDepth?: number;
+    readonly maxEdges?: number;
+    readonly maxCalls?: number;
+    readonly timeoutMs?: number;
+}
+/** A strategy selects a tied best tier of already recorded marked nodes; it cannot introduce identities. */
+export type RootStrategy = (candidates: readonly MarkedNode[], context: GraphContext) => MaybePromise<readonly NodeId[]>;
+/** Reorder all already discovered impact references; never inject or drop evidence. */
+export type ImpactStrategy = (nodes: readonly NodeId[], context: GraphContext) => MaybePromise<readonly NodeId[]>;
+export interface ExplainOptions extends WalkLimits {
+    readonly signal?: AbortSignal;
+    readonly rankRoots?: RootStrategy;
+    readonly rankImpact?: ImpactStrategy;
+}
+export interface AttentionListOptions extends WalkLimits {
+    readonly signal?: AbortSignal;
+    readonly nodeIds?: readonly NodeId[];
+}

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

@@ -0,0 +1,24 @@
+import type { Adjacency, Attention, Gap, GapCode, NodeId } from './types.js';
+import { EvidenceRefusal } from './admission.js';
+/** Graph-port refusals carry their code through Session; loader refusals are handled at the record boundary. */
+export declare class AdmissionError extends EvidenceRefusal {
+    readonly code: GapCode;
+    constructor(code?: GapCode);
+}
+/**
+ * Only ordinary native promise wrappers belong to the async host contract.
+ * An own constructor could run an accessor/species during intrinsic then().
+ * Exotic wrappers remain the trusted host's responsibility, including rejection handling.
+ */
+export declare function observePromise(raw: unknown, accept: (raw: unknown) => void, reject: (reason: unknown) => void): boolean;
+export declare function own(value: unknown, key: string): unknown;
+export declare function plain(value: unknown): void;
+export declare function name(value: unknown, maximum?: number): string;
+export declare function list<T>(value: unknown, maximum: number, read: (item: unknown) => T, overflow?: GapCode): readonly T[];
+export declare const refs: (value: unknown) => readonly string[];
+export declare function attention(value: unknown): readonly Attention[];
+export declare function gaps(value: unknown): readonly Gap[];
+export declare function adjacency(value: unknown, maximum: number): Adjacency;
+export declare const nodeIds: (value: unknown, max: number) => readonly NodeId[];
+export declare const gap: (code: GapCode, nodeId?: NodeId) => Gap;
+export declare function uniqueGaps(items: readonly Gap[]): readonly Gap[];

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

@@ -0,0 +1,12 @@
+import type { Gap, MarkedNode, NodeId, TraversedEdge } from './types.js';
+import { Session } from './session.js';
+export interface Walk {
+    readonly nodes: readonly NodeId[];
+    readonly marked: readonly MarkedNode[];
+    readonly edges: readonly TraversedEdge[];
+    readonly gaps: readonly Gap[];
+}
+/** BFS discovers the shallowest arrival; a repeated diamond node is not a cycle. */
+export declare function walk(session: Session, seeds: readonly NodeId[], direction: 'parents' | 'children'): Promise<Walk>;
+export declare function frontier(result: Walk): readonly MarkedNode[];
+export declare function pathTo(edges: readonly TraversedEdge[], start: NodeId, target: NodeId): readonly NodeId[];