foottrace 1.2.0 → 1.3.0

package/dist/lib/cause/validation.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.uniqueGaps = exports.gap = exports.nodeIds = exports.adjacency = exports.gaps = exports.attention = exports.refs = exports.list = exports.name = exports.plain = exports.own = exports.observePromise = exports.AdmissionError = void 0;
-const admission_js_1 = require("./admission.js");
+exports.uniqueGaps = exports.gap = exports.nodeIds = exports.adjacency = exports.gaps = exports.attention = exports.refs = exports.graphList = exports.graphName = exports.plain = exports.graphOwn = exports.observePromise = exports.AdmissionError = void 0;
+const admission_js_1 = require("../evidence/admission.js");
+const codes_js_1 = require("../evidence/codes.js");
 /** Graph-port refusals carry their code through Session; loader refusals are handled at the record boundary. */
 class AdmissionError extends admission_js_1.EvidenceRefusal {
     code;
@@ -32,20 +33,20 @@ function observePromise(raw, accept, reject) {
 exports.observePromise = observePromise;
 const refuseGraph = (code) => new AdmissionError(code);
 const graphDescriptors = { translateTrapErrors: false, requireOwnValue: false };
-function own(value, key) {
+function graphOwn(value, key) {
     return (0, admission_js_1.ownData)(value, key, refuseGraph, graphDescriptors);
 }
-exports.own = own;
+exports.graphOwn = graphOwn;
 function plain(value) {
     if (!value || typeof value !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
         throw new AdmissionError();
 }
 exports.plain = plain;
-function name(value, maximum = 2048) {
+function graphName(value, maximum = 2048) {
     return (0, admission_js_1.boundedName)(value, maximum, refuseGraph);
 }
-exports.name = name;
-function list(value, maximum, read, overflow = 'invalid-data') {
+exports.graphName = graphName;
+function graphList(value, maximum, read, overflow = 'invalid-data') {
     return (0, admission_js_1.boundedList)(value, maximum, read, {
         refuse: refuseGraph,
         overflow,
@@ -53,7 +54,7 @@ function list(value, maximum, read, overflow = 'invalid-data') {
         descriptors: graphDescriptors,
     });
 }
-exports.list = list;
+exports.graphList = graphList;
 const reasons = new Set([
     'ERROR_RECORDED',
     'UNKNOWN_EFFECT_RECORDED',
@@ -65,36 +66,18 @@ 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',
-]);
-const refs = (value) => list(value, 16, (item) => name(item, 512));
+const refs = (value) => graphList(value, 16, (item) => graphName(item, 512));
 exports.refs = refs;
 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 = (0, exports.refs)(own(item, 'evidence'));
+        const evidence = (0, exports.refs)(graphOwn(item, 'evidence'));
         if (kind !== 'not-collected' && evidence.length === 0)
             throw new AdmissionError();
         return Object.freeze({ kind, reason: reason, evidence });
@@ -102,38 +85,38 @@ function attention(value) {
 }
 exports.attention = attention;
 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 (!(0, codes_js_1.isGapCode)(code))
             throw new AdmissionError();
         return Object.freeze({
             code: code,
-            ...(nodeId === undefined ? {} : { nodeId: name(nodeId) }),
-            evidence: (0, exports.refs)(own(item, 'evidence')),
+            ...(nodeId === undefined ? {} : { nodeId: graphName(nodeId) }),
+            evidence: (0, exports.refs)(graphOwn(item, 'evidence')),
         });
     });
 }
 exports.gaps = gaps;
 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: (0, exports.refs)(own(item, 'evidence')) });
+        return Object.freeze({ nodeId, kind, attribution, evidence: (0, exports.refs)(graphOwn(item, 'evidence')) });
     }, 'edge-limit');
     return Object.freeze({ edges, complete });
 }
 exports.adjacency = adjacency;
-const nodeIds = (value, max) => list(value, max, (item) => name(item), 'node-limit');
+const nodeIds = (value, max) => graphList(value, max, (item) => graphName(item), 'node-limit');
 exports.nodeIds = nodeIds;
 const gap = (code, nodeId) => Object.freeze({ code, ...(nodeId === undefined ? {} : { nodeId }), evidence: Object.freeze([]) });
 exports.gap = gap;

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

@@ -45,11 +45,24 @@ exports.boundedName = boundedName;
 /** Bound iteration before reading entries, without invoking element accessors. */
 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/lib/evidence/codes.js

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

package/dist/lib/evidence/requirementTypes.js

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

package/dist/lib/evidence/requirements.js

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

package/dist/types/index.d.ts

@@ -30,3 +30,7 @@ export { deepEqual } from './lib/memory/equality.js';
 export { serveRecord } from './lib/capture/freeze.js';
 /** Record attention types are shared with producers; the optional cause reader has its own door. */
 export type { Attention, AttentionKind } from './lib/cause/types.js';
+/** Reference-only requirement records: structural admission never grants authority or verifies domain truth. */
+export type { RequirementReason } from './lib/evidence/codes.js';
+export type { RequirementCheck, RequirementCheckDisposition, RequirementResult, } from './lib/evidence/requirementTypes.js';
+export { readRequirementResults, RequirementValidationError, REQUIREMENT_RESULT_LIMITS, } from './lib/evidence/requirements.js';

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

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

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

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

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

@@ -1,5 +1,5 @@
 import type { CommitBundle } from '../memory/types.js';
-import type { AddRecordGap, PreparedRecordScope, RecordIdentity, RecordLoadFailure, ResolvedRecordNode } from './recordTypes.js';
+import type { AddRecordGap, PreparedRecordScope, RecordIdentity, ResolvedRecordNode } from './recordTypes.js';
 import type { Attention, Gap } from './types.js';
 /** Preserve first-observed coverage order while collapsing repeated codes from different evidence paths. */
 export declare function recordGapCollector(): {
@@ -9,7 +9,7 @@ export declare function recordGapCollector(): {
 /** 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[];
+export declare function attentionForRecordNode(node: ResolvedRecordNode): readonly Attention[];
 /** Emit host and capture gaps before query-derived gaps so existing evidence order stays stable. */
 export declare function collectScopeCoverage(scope: PreparedRecordScope, bundle: CommitBundle, extraGapCodes: readonly Gap['code'][] | undefined, addGap: AddRecordGap): void;
 /** A read-only identity has no new value life; unqualified executions retain written-key encounter order. */

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

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

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

@@ -3,17 +3,17 @@ 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';
+import { EvidenceRefusal } from '../evidence/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 recordOwn(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 recordName(value: unknown, path?: boolean): string;
+export declare function recordList(value: unknown, maximum: number): readonly unknown[];
 export declare function addressOf(value: unknown): LogAddress;
 export declare function spend(budget: {
     left: number;

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

@@ -1,6 +1,6 @@
 {
   "name": "foottrace",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "commonjs",
   "description": "Execution records, replay, time travel and honest attribution \u2014 independent of the engine that produced them",
   "license": "MIT",