foottrace 1.2.0 → 1.3.0

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

@@ -1,4 +1,5 @@
-import { AdmissionError, gap, name, observePromise, own, plain } from './validation.js';
+import { AdmissionError, gap, graphName, observePromise, graphOwn, plain } from './validation.js';
+import { beginQueryMemo, endQueryMemo } from './queryMemo.js';
 const defaults = { maxNodes: 100, maxDepth: 20, maxEdges: 1000, maxCalls: 1000, timeoutMs: 1000 };
 const ceilings = { maxNodes: 10000, maxDepth: 1000, maxEdges: 100000, maxCalls: 100000, timeoutMs: 30000 };
 /** One deadline, memo table and work budget per public query, never per graph or store. */
@@ -21,7 +22,7 @@ export class Session {
             plain(options);
             const limits = { ...defaults };
             for (const key of Object.keys(defaults)) {
-                const value = own(options, key);
+                const value = graphOwn(options, key);
                 if (value !== undefined) {
                     if (typeof value !== 'number' ||
                         !Number.isSafeInteger(value) ||
@@ -32,13 +33,13 @@ export class Session {
                 }
             }
             this.limits = Object.freeze(limits);
-            const rank = own(options, 'rankRoots');
+            const rank = graphOwn(options, 'rankRoots');
             if (rank !== undefined && typeof rank !== 'function')
                 throw new TypeError();
-            const impactRank = own(options, 'rankImpact');
+            const impactRank = graphOwn(options, 'rankImpact');
             if (impactRank !== undefined && typeof impactRank !== 'function')
                 throw new TypeError();
-            const signal = own(options, 'signal');
+            const signal = graphOwn(options, 'signal');
             if (signal !== undefined && !(signal instanceof AbortSignal))
                 throw new TypeError();
             this.external = signal;
@@ -71,8 +72,10 @@ export class Session {
             this.timedOut = true;
             this.controller.abort();
         }, this.limits.timeoutMs);
+        beginQueryMemo(this.context, this.limits.maxNodes);
     }
     dispose() {
+        endQueryMemo(this.context);
         clearTimeout(this.timer);
         this.external?.removeEventListener('abort', this.onAbort);
     }
@@ -85,7 +88,7 @@ export class Session {
         return this.controller.signal.aborted ? gap(this.timedOut ? 'timeout' : 'cancelled', id) : undefined;
     }
     admit(id) {
-        name(id);
+        graphName(id);
         if (this.nodes.has(id))
             return undefined;
         if (this.nodes.size >= this.limits.maxNodes)

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

@@ -1,31 +1,37 @@
 import { readStoredRecord } from '../time-travel/storedRecord.js';
 import { createLazyRecordGraph, recordOptions, } from './recordAdapter.js';
-import { addressKey, addressOf, bundleOf, dataCopy, list, own, projectLoaded, RecordRefusal, } from './recordValidation.js';
+import { addressKey, addressOf, bundleOf, dataCopy, recordList, recordOwn, projectLoaded, RecordRefusal, } from './recordValidation.js';
 /** Load one address only. The host owns auth/storage; cancellation is forwarded and waiting is independently bounded. */
 export function createStoredRecordGraph(host, options = {}) {
     const limits = recordOptions(options);
     return createLazyRecordGraph((address, context) => projectLoaded(() => host.loadLog(address, context), (loaded) => {
         const max = limits.maxCommits, budget = { left: limits.maxFields };
-        const raw = list(own(loaded, 'entries'), max * 4 + 16), entries = [];
+        const raw = recordList(recordOwn(loaded, 'entries'), max * 4 + 16), entries = [];
         for (let i = 0; i < raw.length; i++) {
             if (context.signal.aborted)
                 throw new RecordRefusal('cancelled');
-            const entry = own(raw, String(i)), a = addressOf(own(entry, 'address'));
+            const entry = recordOwn(raw, String(i)), a = addressOf(recordOwn(entry, 'address'));
             if (addressKey(a) !== addressKey(address))
                 throw new RecordRefusal();
-            const kind = own(entry, 'kind'), at = own(entry, 'at');
+            const kind = recordOwn(entry, 'kind'), at = recordOwn(entry, 'at');
             if (typeof at !== 'number' || !Number.isFinite(at))
                 throw new RecordRefusal();
             if (kind === 'commit') {
-                const b = own(entry, 'bundle'), idx = own(b, 'idx');
+                const b = recordOwn(entry, 'bundle'), idx = recordOwn(b, 'idx');
                 if (!Number.isSafeInteger(idx) || idx < 0 || idx >= max)
                     throw new RecordRefusal('node-limit');
                 entries.push({ kind, address: a, at, bundle: bundleOf(b, idx, budget) });
             }
             else if (kind === 'opened')
-                entries.push({ kind, address: a, at, initialState: dataCopy(own(entry, 'initialState'), budget) });
+                entries.push({ kind, address: a, at, initialState: dataCopy(recordOwn(entry, 'initialState'), budget) });
             else if (kind === 'closed')
-                entries.push({ kind, address: a, at, outcome: own(entry, 'outcome'), commits: own(entry, 'commits') });
+                entries.push({
+                    kind,
+                    address: a,
+                    at,
+                    outcome: recordOwn(entry, 'outcome'),
+                    commits: recordOwn(entry, 'commits'),
+                });
             else if (kind === 'note') {
                 /* opaque note bodies never enter dependency projection */
             }
@@ -46,9 +52,9 @@ export function createStoredRecordGraph(host, options = {}) {
             scope: {
                 address,
                 commitLog: log.commitLog,
-                reads: own(loaded, 'reads'),
-                controlDeps: own(loaded, 'controlDeps'),
-                attention: own(loaded, 'attention'),
+                reads: recordOwn(loaded, 'reads'),
+                controlDeps: recordOwn(loaded, 'controlDeps'),
+                attention: recordOwn(loaded, 'attention'),
                 complete: log.complete,
             },
             gaps: record.unread.length || log.gaps.length ? ['not-collected'] : [],

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

@@ -1,3 +1,5 @@
+import type { GapCode } from '../evidence/codes.js';
+export type { GapCode } from '../evidence/codes.js';
 /** 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 & {});
@@ -8,7 +10,6 @@ export interface Attention {
     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;

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

@@ -1,5 +1,5 @@
 import type { Adjacency, Attention, Gap, GapCode, NodeId } from './types.js';
-import { EvidenceRefusal } from './admission.js';
+import { EvidenceRefusal } from '../evidence/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;
@@ -11,10 +11,10 @@ export declare class AdmissionError extends EvidenceRefusal {
  * 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 graphOwn(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 function graphName(value: unknown, maximum?: number): string;
+export declare function graphList<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[];

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

@@ -1,4 +1,5 @@
-import { boundedList, boundedName, EvidenceRefusal, ownData } from './admission.js';
+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;
@@ -27,17 +28,17 @@ export function observePromise(raw, accept, reject) {
 }
 const refuseGraph = (code) => new AdmissionError(code);
 const graphDescriptors = { translateTrapErrors: false, requireOwnValue: false };
-export function own(value, key) {
+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 name(value, maximum = 2048) {
+export function graphName(value, maximum = 2048) {
     return boundedName(value, maximum, refuseGraph);
 }
-export function list(value, maximum, read, overflow = 'invalid-data') {
+export function graphList(value, maximum, read, overflow = 'invalid-data') {
     return boundedList(value, maximum, read, {
         refuse: refuseGraph,
         overflow,
@@ -56,71 +57,53 @@ const reasons = new Set([
     'OUTLIER_RECORDED',
     'BUSINESS_RULE_MATCHED',
 ]);
-const codes = new Set([
-    '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 const refs = (value) => list(value, 16, (item) => name(item, 512));
+export const refs = (value) => graphList(value, 16, (item) => graphName(item, 512));
 export function attention(value) {
-    return list(value, 32, (item) => {
+    return graphList(value, 32, (item) => {
         plain(item);
-        const kind = own(item, 'kind'), reason = own(item, 'reason');
+        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(own(item, 'evidence'));
+        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 list(value, 32, (item) => {
+    return graphList(value, 32, (item) => {
         plain(item);
-        const code = own(item, 'code'), nodeId = own(item, 'nodeId');
-        if (typeof code !== 'string' || !codes.has(code))
+        const code = graphOwn(item, 'code'), nodeId = graphOwn(item, 'nodeId');
+        if (!isGapCode(code))
             throw new AdmissionError();
         return Object.freeze({
             code: code,
-            ...(nodeId === undefined ? {} : { nodeId: name(nodeId) }),
-            evidence: refs(own(item, 'evidence')),
+            ...(nodeId === undefined ? {} : { nodeId: graphName(nodeId) }),
+            evidence: refs(graphOwn(item, 'evidence')),
         });
     });
 }
 export function adjacency(value, maximum) {
     plain(value);
-    const complete = own(value, 'complete');
+    const complete = graphOwn(value, 'complete');
     if (typeof complete !== 'boolean')
         throw new AdmissionError();
-    const edges = list(own(value, 'edges'), maximum, (item) => {
+    const edges = graphList(graphOwn(value, 'edges'), maximum, (item) => {
         plain(item);
-        const nodeId = name(own(item, 'nodeId')), kind = own(item, 'kind'), attribution = own(item, 'attribution');
+        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(own(item, 'evidence')) });
+        return Object.freeze({ nodeId, kind, attribution, evidence: refs(graphOwn(item, 'evidence')) });
     }, 'edge-limit');
     return Object.freeze({ edges, complete });
 }
-export const nodeIds = (value, max) => list(value, max, (item) => name(item), 'node-limit');
+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();

package/dist/esm/lib/{cause → evidence}/admission.d.ts

@@ -1,4 +1,4 @@
-import type { GapCode } from './types.js';
+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;
@@ -19,6 +19,10 @@ export declare function boundedList<T>(value: unknown, maximum: number, read: (i
     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: {

package/dist/esm/lib/{cause → evidence}/admission.js

@@ -39,11 +39,24 @@ export function boundedName(value, maximum, refuse, path = false) {
 /** Bound iteration before reading entries, without invoking element accessors. */
 export function boundedList(value, maximum, read, options) {
     const { refuse, overflow, freeze, descriptors } = options;
-    if (!Array.isArray(value))
+    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 = [];

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

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/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; } });