foottrace 1.1.0 → 1.3.0

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

@@ -0,0 +1,198 @@
+import { attention as marksOf, AdmissionError, observePromise } from './validation.js';
+import { boundedList, boundedName, EvidenceRefusal, ownData, spendFields } from '../evidence/admission.js';
+export { marksOf };
+/** Loader refusals stay distinct from graph-port refusals so a failed host load keeps its original classification. */
+export class RecordRefusal extends EvidenceRefusal {
+    code;
+    constructor(code = 'invalid-data') {
+        super(code, 'cause: record unavailable');
+        this.code = code;
+    }
+}
+const refuseRecord = (code) => new RecordRefusal(code);
+const recordDescriptors = { translateTrapErrors: true, requireOwnValue: true };
+export function recordOwn(value, key) {
+    return ownData(value, key, refuseRecord, recordDescriptors);
+}
+export function names(value, maximum = 128, path = false) {
+    return recordList(value, maximum).map((item) => recordName(item, path));
+}
+export function recordName(value, path = false) {
+    return boundedName(value, 1024, refuseRecord, path);
+}
+export function recordList(value, maximum) {
+    return boundedList(value, maximum, (item) => item, {
+        refuse: refuseRecord,
+        overflow: 'node-limit',
+        freeze: false,
+        descriptors: recordDescriptors,
+    });
+}
+export function addressOf(value) {
+    const logRunId = recordName(recordOwn(value, 'logRunId')), drillPath = names(recordOwn(value, 'drillPath'), 16);
+    if (logRunId.length + drillPath.reduce((n, s) => n + s.length, 0) > 1536)
+        throw new RecordRefusal();
+    return Object.freeze({ logRunId, drillPath: Object.freeze(drillPath) });
+}
+export function spend(budget, count) {
+    spendFields(budget, count, refuseRecord);
+}
+export const addressKey = (a) => JSON.stringify([a.logRunId, ...a.drillPath]);
+/** Iterative bounded copy: data descriptors only, no getters/toJSON/prototypes or opaque class instances. */
+export function dataCopy(value, budget) {
+    const leaf = (v) => v === null || typeof v !== 'object';
+    const check = (v) => {
+        spend(budget, 1);
+        if (typeof v === 'function' || typeof v === 'symbol' || (typeof v === 'string' && v.length > 65536))
+            throw new RecordRefusal();
+    };
+    check(value);
+    if (leaf(value))
+        return value;
+    const make = (v) => {
+        let p;
+        try {
+            p = Object.getPrototypeOf(v);
+        }
+        catch {
+            throw new RecordRefusal();
+        }
+        if (!Array.isArray(v) && p !== Object.prototype && p !== null)
+            throw new RecordRefusal();
+        if (Array.isArray(v)) {
+            const length = recordOwn(v, 'length');
+            if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+                throw new RecordRefusal();
+            spend(budget, length);
+            const array = [];
+            array.length = length;
+            return array;
+        }
+        return Object.create(null);
+    };
+    const root = make(value), seen = new Set([value]), work = [{ from: value, to: root }];
+    while (work.length) {
+        const { from, to } = work.pop();
+        let keys;
+        try {
+            keys = Object.keys(from);
+        }
+        catch {
+            throw new RecordRefusal();
+        }
+        if (keys.length > budget.left)
+            throw new RecordRefusal('node-limit');
+        for (const key of keys) {
+            if (key.length > 1024)
+                throw new RecordRefusal('node-limit');
+            const v = recordOwn(from, key);
+            check(v);
+            let copy = v;
+            if (!leaf(v)) {
+                if (seen.has(v))
+                    throw new RecordRefusal();
+                seen.add(v);
+                copy = make(v);
+                work.push({ from: v, to: copy });
+            }
+            Object.defineProperty(to, key, { value: copy, enumerable: true, writable: true, configurable: true });
+        }
+    }
+    return root;
+}
+export function bundleOf(value, idx, budget) {
+    const runtimeStageId = recordName(recordOwn(value, 'runtimeStageId')), stageId = recordName(recordOwn(value, 'stageId'));
+    const trace = recordList(recordOwn(value, 'trace'), 128).map((_, i) => {
+        const t = recordOwn(recordOwn(value, 'trace'), String(i)), path = recordName(recordOwn(t, 'path'), true), verb = recordOwn(t, 'verb');
+        if (!['set', 'merge', 'append', 'delete'].includes(verb))
+            throw new RecordRefusal();
+        const readKeys = recordOwn(t, 'readKeys');
+        return { path, verb: verb, ...(readKeys === undefined ? {} : { readKeys: names(readKeys, 128, true) }) };
+    });
+    spend(budget, trace.length + trace.reduce((n, t) => n + (t.readKeys?.length ?? 0), 0) + 1);
+    const overwrite = dataCopy(recordOwn(value, 'overwrite'), budget), updates = dataCopy(recordOwn(value, 'updates'), budget);
+    if (!overwrite ||
+        typeof overwrite !== 'object' ||
+        Array.isArray(overwrite) ||
+        !updates ||
+        typeof updates !== 'object' ||
+        Array.isArray(updates))
+        throw new RecordRefusal();
+    const redactedPaths = names(recordOwn(value, 'redactedPaths') ?? [], 128, true);
+    const untracked = recordOwn(value, 'untrackedSources'), phase = recordOwn(value, 'phase');
+    spend(budget, redactedPaths.length + (untracked === undefined ? 0 : recordList(untracked, 128).length));
+    return {
+        idx,
+        stage: stageId,
+        stageId,
+        runtimeStageId,
+        trace,
+        overwrite,
+        updates,
+        redactedPaths,
+        ...(untracked === undefined
+            ? {}
+            : {
+                untrackedSources: names(untracked).map((s) => {
+                    if (!['args', 'env', 'silent'].includes(s))
+                        throw new RecordRefusal();
+                    return s;
+                }),
+            }),
+        ...(phase === undefined
+            ? {}
+            : {
+                phase: (() => {
+                    if (phase !== 'exit' && phase !== 'repeat')
+                        throw new RecordRefusal();
+                    return phase;
+                })(),
+            }),
+    };
+}
+export function mapOf(value, limit, read, budget) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new RecordRefusal();
+    let keys;
+    try {
+        keys = Object.keys(value);
+    }
+    catch {
+        throw new RecordRefusal();
+    }
+    if (keys.length > limit)
+        throw new RecordRefusal('node-limit');
+    if (budget)
+        spend(budget, keys.length);
+    return new Map(keys.map((k) => [recordName(k), read(recordOwn(value, k))]));
+}
+/** Observe native promises by intrinsic without assimilating a data object's then accessor. */
+export function projectLoaded(work, project) {
+    return new Promise((resolve, reject) => {
+        const accept = (value) => {
+            try {
+                resolve(project(value));
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        let returned;
+        try {
+            returned = work();
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        try {
+            if (!observePromise(returned, (value) => accept(value), reject))
+                accept(returned);
+        }
+        catch (error) {
+            reject(error instanceof AdmissionError ? new RecordRefusal(error.code) : error);
+        }
+    });
+}

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

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

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

@@ -0,0 +1,164 @@
+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. */
+export class Session {
+    limits;
+    context;
+    nodes = new Set();
+    controller = new AbortController();
+    cache = new Map();
+    calls = 0;
+    edges = 0;
+    timedOut = false;
+    deadline;
+    timer;
+    external;
+    onAbort = () => this.controller.abort();
+    methods = {};
+    constructor(graph, options = {}) {
+        try {
+            plain(options);
+            const limits = { ...defaults };
+            for (const key of Object.keys(defaults)) {
+                const value = graphOwn(options, key);
+                if (value !== undefined) {
+                    if (typeof value !== 'number' ||
+                        !Number.isSafeInteger(value) ||
+                        value < (key === 'maxDepth' ? 0 : 1) ||
+                        value > ceilings[key])
+                        throw new TypeError();
+                    limits[key] = value;
+                }
+            }
+            this.limits = Object.freeze(limits);
+            const rank = graphOwn(options, 'rankRoots');
+            if (rank !== undefined && typeof rank !== 'function')
+                throw new TypeError();
+            const impactRank = graphOwn(options, 'rankImpact');
+            if (impactRank !== undefined && typeof impactRank !== 'function')
+                throw new TypeError();
+            const signal = graphOwn(options, 'signal');
+            if (signal !== undefined && !(signal instanceof AbortSignal))
+                throw new TypeError();
+            this.external = signal;
+            for (const key of ['parents', 'children', 'attention', 'gaps', 'roots']) {
+                let cursor = graph, method;
+                for (let depth = 0; cursor && cursor !== Object.prototype && depth < 8; depth++, cursor = Object.getPrototypeOf(cursor)) {
+                    const field = Object.getOwnPropertyDescriptor(cursor, key);
+                    if (field) {
+                        if (!('value' in field))
+                            throw new TypeError();
+                        method = field.value;
+                        break;
+                    }
+                }
+                if (typeof method !== 'function' && key !== 'roots')
+                    throw new TypeError();
+                if (typeof method === 'function')
+                    this.methods[key] = method.bind(graph);
+            }
+        }
+        catch {
+            throw new TypeError('CAUSE_CONFIGURATION_INVALID');
+        }
+        this.context = Object.freeze({ signal: this.controller.signal });
+        this.deadline = performance.now() + this.limits.timeoutMs;
+        this.external?.addEventListener('abort', this.onAbort, { once: true });
+        if (this.external?.aborted)
+            this.onAbort();
+        this.timer = setTimeout(() => {
+            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);
+    }
+    stopGap(id) {
+        // Resolved Promise chains can starve timers. Check the monotonic deadline too.
+        if (!this.controller.signal.aborted && performance.now() >= this.deadline) {
+            this.timedOut = true;
+            this.controller.abort();
+        }
+        return this.controller.signal.aborted ? gap(this.timedOut ? 'timeout' : 'cancelled', id) : undefined;
+    }
+    admit(id) {
+        graphName(id);
+        if (this.nodes.has(id))
+            return undefined;
+        if (this.nodes.size >= this.limits.maxNodes)
+            return gap('node-limit', id);
+        this.nodes.add(id);
+        return undefined;
+    }
+    hasRoots() {
+        return !!this.methods.roots;
+    }
+    read(method, id, project) {
+        const key = JSON.stringify([method, id]);
+        const cached = this.cache.get(key);
+        if (cached)
+            return cached;
+        const pending = this.invoke(id, () => {
+            const fn = this.methods[method];
+            if (!fn)
+                throw new AdmissionError('not-collected');
+            return id === undefined ? fn(this.context) : fn(id, this.context);
+        }, project);
+        this.cache.set(key, pending);
+        return pending;
+    }
+    invoke(id, work, project) {
+        const stopped = this.stopGap(id);
+        if (stopped)
+            return Promise.resolve({ gap: stopped });
+        if (++this.calls > this.limits.maxCalls)
+            return Promise.resolve({ gap: gap('call-limit', id) });
+        return new Promise((resolve) => {
+            let finished = false;
+            const finish = (result) => {
+                if (finished)
+                    return;
+                finished = true;
+                this.controller.signal.removeEventListener('abort', abort);
+                resolve(result);
+            };
+            const abort = () => finish({ gap: this.stopGap(id) ?? gap('cancelled', id) });
+            const accept = (raw) => {
+                if (finished)
+                    return;
+                const stopped = this.stopGap(id);
+                if (stopped) {
+                    finish({ gap: stopped });
+                    return;
+                }
+                try {
+                    const value = project(raw), expired = this.stopGap(id);
+                    finish(expired ? { gap: expired } : { value });
+                }
+                catch (error) {
+                    finish({ gap: gap(error instanceof AdmissionError ? error.code : 'invalid-data', id) });
+                }
+            };
+            this.controller.signal.addEventListener('abort', abort, { once: true });
+            if (this.controller.signal.aborted) {
+                abort();
+                return;
+            }
+            try {
+                const returned = work();
+                // Observe native Promises by intrinsic, never assimilate a payload's `then` getter.
+                if (!observePromise(returned, accept, () => finish({ gap: gap('unavailable', id) })))
+                    accept(returned);
+            }
+            catch (error) {
+                finish({ gap: gap(error instanceof AdmissionError ? error.code : 'unavailable', id) });
+            }
+        });
+    }
+}

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

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

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

@@ -0,0 +1,63 @@
+import { readStoredRecord } from '../time-travel/storedRecord.js';
+import { createLazyRecordGraph, recordOptions, } from './recordAdapter.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 = 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 = recordOwn(raw, String(i)), a = addressOf(recordOwn(entry, 'address'));
+            if (addressKey(a) !== addressKey(address))
+                throw new RecordRefusal();
+            const kind = recordOwn(entry, 'kind'), at = recordOwn(entry, 'at');
+            if (typeof at !== 'number' || !Number.isFinite(at))
+                throw new RecordRefusal();
+            if (kind === 'commit') {
+                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(recordOwn(entry, 'initialState'), budget) });
+            else if (kind === 'closed')
+                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 */
+            }
+            else
+                throw new RecordRefusal();
+        }
+        const record = readStoredRecord(entries, {
+            entries: max * 4 + 16,
+            missingCommits: max,
+            drillDepth: 16,
+            addressLength: 1536,
+        }), log = record.log(address);
+        if (!log)
+            throw new RecordRefusal();
+        if (log.gaps.length)
+            throw new RecordRefusal('not-collected');
+        return {
+            scope: {
+                address,
+                commitLog: log.commitLog,
+                reads: recordOwn(loaded, 'reads'),
+                controlDeps: recordOwn(loaded, 'controlDeps'),
+                attention: recordOwn(loaded, 'attention'),
+                complete: log.complete,
+            },
+            gaps: record.unread.length || log.gaps.length ? ['not-collected'] : [],
+        };
+    }), limits);
+}

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

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

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

@@ -0,0 +1,21 @@
+/** Host-computed quality drops or impact counts: scores rank recorded candidates, never create evidence. */
+function maximum(scores) {
+    return (candidates) => {
+        let best = -Infinity;
+        const tied = [];
+        for (const candidate of candidates) {
+            const score = scores.get(candidate.nodeId);
+            if (score === undefined || !Number.isFinite(score))
+                throw new TypeError('CAUSE_STRATEGY_EVIDENCE_MISSING');
+            if (score > best) {
+                best = score;
+                tied.length = 0;
+            }
+            if (score === best)
+                tied.push(candidate.nodeId);
+        }
+        return Object.freeze(tied);
+    };
+}
+export const largestDrop = (scores) => maximum(scores);
+export const mostAffected = (counts) => maximum(counts);

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

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

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

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

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

@@ -0,0 +1,24 @@
+import type { Adjacency, Attention, Gap, GapCode, NodeId } from './types.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;
+    constructor(code?: GapCode);
+}
+/**
+ * Only ordinary native promise wrappers belong to the async host contract.
+ * An own constructor could run an accessor/species during intrinsic then().
+ * Exotic wrappers remain the trusted host's responsibility, including rejection handling.
+ */
+export declare function observePromise(raw: unknown, accept: (raw: unknown) => void, reject: (reason: unknown) => void): boolean;
+export declare function graphOwn(value: unknown, key: string): unknown;
+export declare function plain(value: unknown): void;
+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[];
+export declare function adjacency(value: unknown, maximum: number): Adjacency;
+export declare const nodeIds: (value: unknown, max: number) => readonly NodeId[];
+export declare const gap: (code: GapCode, nodeId?: NodeId) => Gap;
+export declare function uniqueGaps(items: readonly Gap[]): readonly Gap[];