foottrace 1.1.0 → 1.3.0

package/dist/esm/lib/evidence/requirements.js

@@ -0,0 +1,185 @@
+import { boundedList, boundedName, EvidenceRefusal, ownData, spendFields } from './admission.js';
+import { isRequirementReason } from './codes.js';
+/** Fixed per-call ceilings; characters are UTF-16 code units, not serialized transport bytes. */
+export const 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. */
+export class RequirementValidationError extends EvidenceRefusal {
+    constructor(code = 'invalid-data') {
+        super(code, 'REQUIREMENT_RESULTS_INVALID');
+    }
+}
+const refuse = (code) => new RequirementValidationError(code);
+const descriptors = { translateTrapErrors: true, requireOwnValue: true };
+const own = (value, key) => 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();
+    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();
+    spendFields(budget, length + 1, refuse);
+    return boundedList(value, maximum, read, {
+        refuse,
+        overflow: 'node-limit',
+        freeze: true,
+        descriptors,
+        expectedLength: length,
+        translateArrayErrors: true,
+    });
+}
+function name(value, budget) {
+    const result = boundedName(value, 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 = REQUIREMENT_RESULT_LIMITS.refs) {
+    return unique(list(value, maximum, (item) => name(item, budget), budget), (item) => item);
+}
+function reason(value) {
+    if (!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, REQUIREMENT_RESULT_LIMITS.affects);
+    if (!affects.length)
+        throw refuse();
+    const evidenceRefs = refs(own(value, 'evidenceRefs'), budget), checks = unique(list(own(value, 'checks'), 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.
+ */
+export function readRequirementResults(value) {
+    const budget = { left: REQUIREMENT_RESULT_LIMITS.fields, characters: REQUIREMENT_RESULT_LIMITS.characters };
+    return unique(list(value, REQUIREMENT_RESULT_LIMITS.results, (item) => result(item, budget), budget), (item) => item.id);
+}

package/dist/esm/lib/memory/types.d.ts

@@ -2,10 +2,11 @@
  * 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.
  */
+import type { Attention } from '../cause/types.js';
 /** A flat key-value bag representing a state patch (overwrite or merge). */
 export interface MemoryPatch {
     [key: string]: any;
@@ -194,6 +195,8 @@ export type CommitValuesMode = 'full' | 'delta';
  * ```
  */
 export interface ExecutionTree {
+    /** Optional recorded business attention; absence does not assert health. */
+    readonly attention?: readonly Attention[];
     /** The stage's id (prefixed inside a subflow). `commitStops` reads the root's to place a subflow's seed. */
     readonly id?: string;
     /** `[subflowPath/]stageId#executionIndex` — what a reader keys on. A node without one is not a stage. */

package/dist/esm/lib/memory/types.js

@@ -2,7 +2,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/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.idPathSegments = exports.joinPath = exports.isExecutionKey = exports.PATH_DELIMITER = exports.EXECUTION_DELIMITER = exports.CommitRangeIndex = exports.HONESTY_CODES = exports.sliceToJSON = exports.sliceForKey = exports.resolveKeysReadSource = exports.keyTimeline = exports.keysReadFromMap = exports.keysReadFromExecutionTree = exports.forwardSliceToJSON = exports.forwardSliceForKey = exports.formatTimeline = exports.formatSlice = exports.formatForwardSlice = exports.elementProvenance = exports.arrayProvenance = exports.formatCausalChain = exports.flattenCausalDAG = exports.causalChain = exports.timeTravel = exports.tagStops = exports.stateAt = exports.splitAxis = exports.readStoredRecord = exports.isCommitBundle = exports.filterStops = exports.commitStopsStrategy = exports.commitStops = exports.recordsPhases = exports.inferLegacyPhases = exports.findLastWriterWithBasis = exports.findLastWriter = exports.findCommits = exports.findCommit = exports.commitValueAtWithBasis = exports.commitValueAt = exports.commitIndexOf = exports.buildCommitIndex = exports.applySmartMerge = exports.UnknownVerbError = exports.parseAttemptId = exports.buildAttemptId = exports.splitStageId = exports.parseRuntimeStageId = exports.createExecutionCounter = exports.buildRuntimeStageId = void 0;
-exports.serveRecord = exports.deepEqual = exports.subflowSegmentsOf = exports.stageIdOf = void 0;
+exports.REQUIREMENT_RESULT_LIMITS = exports.RequirementValidationError = exports.readRequirementResults = exports.serveRecord = exports.deepEqual = exports.subflowSegmentsOf = exports.stageIdOf = void 0;
 var runtimeStageId_js_1 = require("./lib/ids/runtimeStageId.js");
 Object.defineProperty(exports, "buildRuntimeStageId", { enumerable: true, get: function () { return runtimeStageId_js_1.buildRuntimeStageId; } });
 Object.defineProperty(exports, "createExecutionCounter", { enumerable: true, get: function () { return runtimeStageId_js_1.createExecutionCounter; } });
@@ -69,3 +69,7 @@ var equality_js_1 = require("./lib/memory/equality.js");
 Object.defineProperty(exports, "deepEqual", { enumerable: true, get: function () { return equality_js_1.deepEqual; } });
 var freeze_js_1 = require("./lib/capture/freeze.js");
 Object.defineProperty(exports, "serveRecord", { enumerable: true, get: function () { return freeze_js_1.serveRecord; } });
+var requirements_js_1 = require("./lib/evidence/requirements.js");
+Object.defineProperty(exports, "readRequirementResults", { enumerable: true, get: function () { return requirements_js_1.readRequirementResults; } });
+Object.defineProperty(exports, "RequirementValidationError", { enumerable: true, get: function () { return requirements_js_1.RequirementValidationError; } });
+Object.defineProperty(exports, "REQUIREMENT_RESULT_LIMITS", { enumerable: true, get: function () { return requirements_js_1.REQUIREMENT_RESULT_LIMITS; } });

package/dist/lib/cause/explain.js

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

package/dist/lib/cause/queryMemo.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.endQueryMemo = exports.queryMemo = exports.beginQueryMemo = void 0;
+/** Share bounded derived work within one query without retaining it in the graph's storage cache. */
+class QueryMemo {
+    maximumEntries;
+    owners = new Map();
+    entries = 0;
+    closed = false;
+    constructor(maximumEntries) {
+        this.maximumEntries = maximumEntries;
+    }
+    remember(owner, key, create) {
+        const previous = this.owners.get(owner);
+        if (previous?.has(key))
+            return previous.get(key);
+        if (this.closed || this.entries >= this.maximumEntries)
+            return create();
+        const value = create();
+        // Creation can finish after disposal or re-enter other readers; neither may refill a closed/full memo.
+        if (!this.closed && this.entries < this.maximumEntries) {
+            const bucket = this.owners.get(owner) ?? new Map();
+            if (!bucket.has(key))
+                this.entries++;
+            bucket.set(key, value);
+            this.owners.set(owner, bucket);
+        }
+        return value;
+    }
+    close() {
+        this.closed = true;
+        this.owners.clear();
+        this.entries = 0;
+    }
+}
+const queries = new WeakMap();
+/** Reserve one resolution and one inspection per admitted node, shared across all adapter owners. */
+function beginQueryMemo(context, maximumNodes) {
+    queries.set(context, new QueryMemo(maximumNodes * 2));
+}
+exports.beginQueryMemo = beginQueryMemo;
+/** Direct graph calls have no managed query lifetime and deliberately remain uncached. */
+function queryMemo(context) {
+    return queries.get(context);
+}
+exports.queryMemo = queryMemo;
+/** Clear synchronously without aborting an otherwise successful query's public signal. */
+function endQueryMemo(context) {
+    queries.get(context)?.close();
+    queries.delete(context);
+}
+exports.endQueryMemo = endQueryMemo;

package/dist/lib/cause/ranking.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.admitRanking = void 0;
+const validation_js_1 = require("./validation.js");
+/** Strategies may only select admitted nodes; impact ranking must preserve the full set. */
+function admitRanking(raw, allowed, options) {
+    const ids = (0, validation_js_1.nodeIds)(raw, options.maximum);
+    if ((options.exactPermutation && ids.length !== allowed.size) ||
+        new Set(ids).size !== ids.length ||
+        ids.some((id) => !allowed.has(id)))
+        throw new TypeError();
+    return ids;
+}
+exports.admitRanking = admitRanking;

package/dist/lib/cause/recordAdapter.js

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

package/dist/lib/cause/recordChildren.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.childrenForRecordNode = void 0;
+const forwardSliceForKey_js_1 = require("../slice/forwardSliceForKey.js");
+const recordControl_js_1 = require("./recordControl.js");
+const recordCoverage_js_1 = require("./recordCoverage.js");
+const recordIdentity_js_1 = require("./recordIdentity.js");
+const recordScope_js_1 = require("./recordScope.js");
+/** Keep per-write and conservative fed edges distinct while retaining existing cap and deduplication order. */
+function appendFedChildren(scope, root, maximumEdges, edges) {
+    let complete = true;
+    for (const edge of root.fedEdges) {
+        const child = edge.child;
+        if (child.commitIdx === undefined || !child.runtimeStageId) {
+            complete = false;
+            continue;
+        }
+        if (edges.length >= maximumEdges) {
+            complete = false;
+            break;
+        }
+        const nodeId = (0, recordIdentity_js_1.nodeIdFor)(scope.address, {
+            runtimeStageId: child.runtimeStageId,
+            commitIdx: child.commitIdx,
+            key: child.key,
+        });
+        if (!edges.some((existing) => existing.nodeId === nodeId))
+            edges.push({ nodeId, kind: 'data', attribution: edge.basis, evidence: ['commit:' + child.commitIdx] });
+        if (edge.basis === 'stage')
+            complete = false;
+    }
+    return complete;
+}
+/** A consumer with no writes still needs a qualified node so its recorded control flow remains reachable. */
+function appendReadOnlyChildren(scope, root, key, maximumEdges, edges) {
+    let complete = true;
+    for (const read of root.reads) {
+        if (scope.log[read.commitIdx]?.trace.length)
+            continue;
+        if (edges.length >= maximumEdges) {
+            complete = false;
+            break;
+        }
+        const nodeId = (0, recordIdentity_js_1.nodeIdFor)(scope.address, { runtimeStageId: read.runtimeStageId, commitIdx: read.commitIdx, key }, true);
+        if (!edges.some((existing) => existing.nodeId === nodeId))
+            edges.push({ nodeId, kind: 'data', attribution: 'per-write', evidence: ['commit:' + read.commitIdx] });
+    }
+    return complete;
+}
+/** Query each written value at its original commit boundary instead of the value's latest writer. */
+function appendDataChildren(scope, identity, commitIndex, maximumEdges, edges) {
+    let complete = true;
+    const lookup = (runtimeStageId) => (0, recordScope_js_1.readKeysForStage)(scope, runtimeStageId);
+    for (const key of (0, recordCoverage_js_1.writtenKeysForNode)(scope.log[commitIndex], identity)) {
+        const forward = (0, forwardSliceForKey_js_1.forwardSliceForKey)(scope.log, key, lookup, {
+            before: commitIndex + 1,
+            maxDepth: 1,
+            maxNodes: maximumEdges + 1,
+        });
+        if (forward.root?.truncated?.byNodes)
+            complete = false;
+        if (forward.root?.commitIdx !== commitIndex) {
+            complete = false;
+            continue;
+        }
+        complete = appendFedChildren(scope, forward.root, maximumEdges, edges) && complete;
+        complete = appendReadOnlyChildren(scope, forward.root, key, maximumEdges, edges) && complete;
+    }
+    return complete;
+}
+/** Share parent-side coverage checks before appending data then control children in their established order. */
+function childrenForRecordNode(node, maximumEdges, inspection) {
+    const { scope, identity, commitIndex } = node;
+    const edges = [];
+    let complete = inspection.gaps.length === 0;
+    if (!(0, recordCoverage_js_1.allStageReadsCollected)(scope))
+        complete = false;
+    complete = appendDataChildren(scope, identity, commitIndex, maximumEdges, edges) && complete;
+    complete = (0, recordControl_js_1.appendControlChildren)(scope, identity, commitIndex, maximumEdges, edges) && complete;
+    return { edges, complete };
+}
+exports.childrenForRecordNode = childrenForRecordNode;

package/dist/lib/cause/recordControl.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendControlChildren = exports.collectControlChildCoverage = exports.collectControlParentCoverage = exports.controlParentLookup = exports.controlChildren = void 0;
+const recordIdentity_js_1 = require("./recordIdentity.js");
+/** Only an execution or captured read may govern control flow; a written key alone cannot. */
+function controlChildren(scope, identity) {
+    // A read-only execution may govern later work; a particular written key is not itself a decision.
+    return identity.key === undefined || identity.read ? scope.control ?? [] : [];
+}
+exports.controlChildren = controlChildren;
+/** Canonical slicing receives only control parents that existed before the dependent execution. */
+function controlParentLookup(scope) {
+    return scope.control === undefined
+        ? undefined
+        : (runtimeStageId) => {
+            const dependency = scope.control.get(runtimeStageId);
+            if (!dependency)
+                return undefined;
+            const parentIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === dependency.deciderId), childIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === runtimeStageId);
+            return parentIndex >= 0 && parentIndex < childIndex ? dependency : undefined;
+        };
+}
+exports.controlParentLookup = controlParentLookup;
+/** Keep missing or future deciders visible rather than silently dropping their recorded dependency. */
+function collectControlParentCoverage(scope, identity, firstCommitIndex, addGap) {
+    const dependency = scope.control?.get(identity.runtimeStageId);
+    if (!dependency)
+        return;
+    const parentIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === dependency.deciderId);
+    if (parentIndex < 0)
+        addGap('scope-boundary');
+    else if (parentIndex >= firstCommitIndex)
+        addGap('invalid-data');
+}
+exports.collectControlParentCoverage = collectControlParentCoverage;
+/** Include control fan-out in the same immediate-neighbor cap used for data adjacency. */
+function collectControlChildCoverage(scope, identity, firstCommitIndex, neighbors, addGap) {
+    for (const [childStageId, dependency] of controlChildren(scope, identity))
+        if (dependency.deciderId === identity.runtimeStageId) {
+            const childIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === childStageId);
+            if (childIndex < 0)
+                addGap('scope-boundary');
+            else if (childIndex <= firstCommitIndex)
+                addGap('invalid-data');
+            else
+                neighbors.add(JSON.stringify(['control', childStageId]));
+        }
+}
+exports.collectControlChildCoverage = collectControlChildCoverage;
+/** Preserve recorded control order and coverage when a dependent execution is absent or capped. */
+function appendControlChildren(scope, identity, commitIndex, maximumEdges, edges) {
+    let complete = true;
+    for (const [childStageId, dependency] of controlChildren(scope, identity)) {
+        if (dependency.deciderId !== identity.runtimeStageId)
+            continue;
+        const childIndex = scope.log.findIndex((bundle) => bundle.runtimeStageId === childStageId);
+        if (childIndex <= commitIndex) {
+            complete = false;
+            continue;
+        }
+        if (edges.length >= maximumEdges) {
+            complete = false;
+            break;
+        }
+        edges.push({
+            nodeId: (0, recordIdentity_js_1.nodeIdFor)(scope.address, { runtimeStageId: childStageId, commitIdx: childIndex }),
+            kind: 'control',
+            attribution: 'recorded-control',
+            evidence: ['commit:' + childIndex],
+        });
+    }
+    return complete;
+}
+exports.appendControlChildren = appendControlChildren;