foottrace 1.1.0 → 1.3.0

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

@@ -0,0 +1,117 @@
+import { boundedList, boundedName, EvidenceRefusal, ownData } from '../evidence/admission.js';
+import { isGapCode } from '../evidence/codes.js';
+/** Graph-port refusals carry their code through Session; loader refusals are handled at the record boundary. */
+export class AdmissionError extends EvidenceRefusal {
+    code;
+    constructor(code = 'invalid-data') {
+        super(code, 'Invalid cause evidence');
+        this.code = code;
+    }
+}
+/**
+ * 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 function observePromise(raw, accept, reject) {
+    if (!raw || typeof raw !== 'object' || Object.getPrototypeOf(raw) !== Promise.prototype)
+        return false;
+    if (Object.getOwnPropertyDescriptor(raw, 'constructor'))
+        throw new AdmissionError();
+    try {
+        Promise.prototype.then.call(raw, accept, reject);
+    }
+    catch {
+        throw new AdmissionError();
+    }
+    return true;
+}
+const refuseGraph = (code) => new AdmissionError(code);
+const graphDescriptors = { translateTrapErrors: false, requireOwnValue: false };
+export function graphOwn(value, key) {
+    return ownData(value, key, refuseGraph, graphDescriptors);
+}
+export function plain(value) {
+    if (!value || typeof value !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new AdmissionError();
+}
+export function graphName(value, maximum = 2048) {
+    return boundedName(value, maximum, refuseGraph);
+}
+export function graphList(value, maximum, read, overflow = 'invalid-data') {
+    return boundedList(value, maximum, read, {
+        refuse: refuseGraph,
+        overflow,
+        freeze: true,
+        descriptors: graphDescriptors,
+    });
+}
+const reasons = new Set([
+    'ERROR_RECORDED',
+    'UNKNOWN_EFFECT_RECORDED',
+    'RETRY_STOP_RECORDED',
+    'TIMEOUT_RECORDED',
+    'RETRY_RECORDED',
+    'QUALITY_DROP_RECORDED',
+    'EVIDENCE_NOT_COLLECTED',
+    'OUTLIER_RECORDED',
+    'BUSINESS_RULE_MATCHED',
+]);
+export const refs = (value) => graphList(value, 16, (item) => graphName(item, 512));
+export function attention(value) {
+    return graphList(value, 32, (item) => {
+        plain(item);
+        const kind = graphOwn(item, 'kind'), reason = graphOwn(item, 'reason');
+        if (typeof kind !== 'string' ||
+            !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(kind) ||
+            typeof reason !== 'string' ||
+            !reasons.has(reason))
+            throw new AdmissionError();
+        const evidence = refs(graphOwn(item, 'evidence'));
+        if (kind !== 'not-collected' && evidence.length === 0)
+            throw new AdmissionError();
+        return Object.freeze({ kind, reason: reason, evidence });
+    });
+}
+export function gaps(value) {
+    return graphList(value, 32, (item) => {
+        plain(item);
+        const code = graphOwn(item, 'code'), nodeId = graphOwn(item, 'nodeId');
+        if (!isGapCode(code))
+            throw new AdmissionError();
+        return Object.freeze({
+            code: code,
+            ...(nodeId === undefined ? {} : { nodeId: graphName(nodeId) }),
+            evidence: refs(graphOwn(item, 'evidence')),
+        });
+    });
+}
+export function adjacency(value, maximum) {
+    plain(value);
+    const complete = graphOwn(value, 'complete');
+    if (typeof complete !== 'boolean')
+        throw new AdmissionError();
+    const edges = graphList(graphOwn(value, 'edges'), maximum, (item) => {
+        plain(item);
+        const nodeId = graphName(graphOwn(item, 'nodeId')), kind = graphOwn(item, 'kind'), attribution = graphOwn(item, 'attribution');
+        if ((kind !== 'data' && kind !== 'control') ||
+            (attribution !== 'per-write' && attribution !== 'stage' && attribution !== 'recorded-control') ||
+            (kind === 'control' && attribution !== 'recorded-control') ||
+            (kind === 'data' && attribution === 'recorded-control'))
+            throw new AdmissionError();
+        return Object.freeze({ nodeId, kind, attribution, evidence: refs(graphOwn(item, 'evidence')) });
+    }, 'edge-limit');
+    return Object.freeze({ edges, complete });
+}
+export const nodeIds = (value, max) => graphList(value, max, (item) => graphName(item), 'node-limit');
+export const gap = (code, nodeId) => Object.freeze({ code, ...(nodeId === undefined ? {} : { nodeId }), evidence: Object.freeze([]) });
+export function uniqueGaps(items) {
+    const seen = new Set();
+    return Object.freeze(items.filter((item) => {
+        const key = JSON.stringify(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }));
+}

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

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

@@ -0,0 +1,174 @@
+import { adjacency, attention, gap, gaps, uniqueGaps } from './validation.js';
+/** BFS discovers the shallowest arrival; a repeated diamond node is not a cycle. */
+export 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, 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(gap('not-collected', id));
+        }
+        const coverage = await session.read('gaps', id, gaps);
+        if (coverage.gap)
+            missing.push(coverage.gap);
+        if (coverage.value)
+            missing.push(...coverage.value);
+        const page = await session.read(direction, id, (raw) => adjacency(raw, session.limits.maxEdges));
+        if (page.gap) {
+            missing.push(page.gap);
+            continue;
+        }
+        if (!page.value)
+            continue;
+        if (!page.value.complete)
+            missing.push(gap('not-collected', id));
+        if (depth >= session.limits.maxDepth) {
+            if (page.value.edges.length)
+                missing.push(gap('depth-limit', id));
+            continue;
+        }
+        for (const edge of page.value.edges) {
+            if (session.edges >= session.limits.maxEdges) {
+                missing.push(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(gap('conservative', id));
+            enqueue(edge.nodeId, depth + 1);
+        }
+    }
+    if (hasCycle(edges))
+        missing.push(gap('cycle'));
+    return Object.freeze({
+        nodes: Object.freeze(queue.map((row) => row[0])),
+        marked: Object.freeze(marks),
+        edges: Object.freeze(edges),
+        gaps: uniqueGaps(missing),
+    });
+}
+/** 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;
+}
+export 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));
+}
+export 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());
+}

package/dist/esm/lib/evidence/admission.d.ts

@@ -0,0 +1,31 @@
+import type { GapCode } from './codes.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;
+    /** Optional prior shape inspection must refer to the same admitted length. */
+    readonly expectedLength?: number;
+    /** New boundaries may normalize revoked-array errors without changing existing reader policy. */
+    readonly translateArrayErrors?: boolean;
+}): 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/esm/lib/evidence/admission.js

@@ -0,0 +1,72 @@
+/** One refusal representation; subclasses preserve the graph-port and record-loader boundaries. */
+export class EvidenceRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Read data descriptors only; each boundary keeps its existing treatment of proxy traps. */
+export 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;
+}
+/** Names share one grammar, with explicit limits and the record path separator exception. */
+export 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;
+}
+/** Bound iteration before reading entries, without invoking element accessors. */
+export 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;
+}
+/** Charge retained fields against the same mutable allowance across admission helpers. */
+export function spendFields(budget, count, refuse) {
+    budget.left -= count;
+    if (budget.left < 0)
+        throw refuse('node-limit');
+}

package/dist/esm/lib/evidence/codes.d.ts

@@ -0,0 +1,33 @@
+/** One vocabulary; true marks a domain evidence reason, false a trace/admission gap only. */
+export declare const GAP_CODES: Readonly<{
+    readonly 'not-collected': true;
+    readonly 'untracked-input': false;
+    readonly redacted: true;
+    readonly conservative: false;
+    readonly 'scope-boundary': false;
+    readonly 'invalid-data': true;
+    readonly unavailable: true;
+    readonly timeout: true;
+    readonly cancelled: false;
+    readonly cycle: false;
+    readonly 'node-limit': false;
+    readonly 'depth-limit': false;
+    readonly 'edge-limit': false;
+    readonly 'call-limit': false;
+    readonly truncated: false;
+    readonly 'strategy-failed': false;
+    readonly 'not-checked': true;
+    readonly 'no-match': true;
+    readonly ambiguous: true;
+    readonly stale: true;
+    readonly incompatible: true;
+    readonly unsupported: true;
+    readonly 'not-permitted': true;
+}>;
+export type GapCode = keyof typeof GAP_CODES;
+/** Producer-asserted evidence reasons, excluding traversal and admission bounds. */
+export type RequirementReason = {
+    [Code in GapCode]: (typeof GAP_CODES)[Code] extends true ? Code : never;
+}[GapCode];
+export declare const isGapCode: (value: unknown) => value is "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" | "not-checked" | "no-match" | "ambiguous" | "stale" | "incompatible" | "unsupported" | "not-permitted";
+export declare const isRequirementReason: (value: unknown) => value is RequirementReason;

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

@@ -0,0 +1,28 @@
+/** One vocabulary; true marks a domain evidence reason, false a trace/admission gap only. */
+export const 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,
+});
+export const isGapCode = (value) => typeof value === 'string' && Object.hasOwn(GAP_CODES, value);
+export const isRequirementReason = (value) => isGapCode(value) && GAP_CODES[value];

package/dist/esm/lib/evidence/requirementTypes.d.ts

@@ -0,0 +1,46 @@
+import type { RequirementReason } from './codes.js';
+/**
+ * Existing check wire words; a disposition records a producer assertion, not authorization.
+ * `unreachable` means the check could not run; its reason identifies why.
+ */
+export type RequirementCheckDisposition = 'checked-pass' | 'checked-fail' | 'unreachable' | 'not-applicable';
+/** References to a real check and its retained evidence. No synthetic attempt is required or invented. */
+export interface RequirementCheck {
+    readonly checkRef: string;
+    readonly disposition: RequirementCheckDisposition;
+    readonly reason?: RequirementReason;
+    /** A namespaced adapter detail ID, never a message, subject or payload. */
+    readonly detail?: string;
+    readonly evidenceRefs: readonly string[];
+    readonly attemptRefs: readonly string[];
+}
+interface RequirementBinding {
+    /** This result's identity, not the enclosing artifact reference minted by storage. */
+    readonly id: string;
+    /** Reference to the requirement definition or policy. */
+    readonly requirementRef: string;
+    readonly findingRef: string;
+    readonly windowRef: string;
+    readonly affects: readonly string[];
+    readonly evidenceRefs: readonly string[];
+    readonly checks: readonly RequirementCheck[];
+    /** References into a host-owned closed action registry; never executable tool names or arguments. */
+    readonly actionRefs: readonly string[];
+    /** A namespaced adapter detail ID, never a message, subject or payload. */
+    readonly detail?: string;
+    /** Source validity and learned time are separate opaque references; no freshness inference is made. */
+    readonly validTimeRef?: string;
+    readonly learnedTimeRef?: string;
+}
+/**
+ * A producer assertion. Structural admission does not verify its source, scope, bindings, validity or truth.
+ * Hosts must verify those facts and must not let a satisfied record override an unresolved affected claim.
+ */
+export type RequirementResult = RequirementBinding & ({
+    readonly state: 'satisfied';
+    readonly reason?: never;
+} | {
+    readonly state: 'unresolved';
+    readonly reason: RequirementReason;
+});
+export {};

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

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

package/dist/esm/lib/evidence/requirements.d.ts

@@ -0,0 +1,24 @@
+import { EvidenceRefusal } from './admission.js';
+import { type GapCode } from './codes.js';
+import type { RequirementResult } from './requirementTypes.js';
+/** Fixed per-call ceilings; characters are UTF-16 code units, not serialized transport bytes. */
+export declare const REQUIREMENT_RESULT_LIMITS: Readonly<{
+    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 declare class RequirementValidationError extends EvidenceRefusal {
+    constructor(code?: GapCode);
+}
+/**
+ * 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 declare function readRequirementResults(value: unknown): readonly RequirementResult[];