agentfootprint 11.0.0 → 11.1.0

package/dist/esm/trace-toolpack/storedCauseProjection.js

@@ -0,0 +1,117 @@
+import { copyJson } from '../lib/boundedJson.js';
+import { captureOwn as own } from './causeCapture.js';
+import { projectCauseBasis } from './causeProjection.js';
+import { bindStoredCause } from './storedCauseBinding.js';
+import { storedCauseSources } from './storedCauseSources.js';
+function savedNodes(history) {
+    const nodes = new Map();
+    const paths = new Map();
+    const pending = [
+        { node: history.executionTree, path: ['executionTree'] },
+    ];
+    let visited = 0;
+    while (pending.length) {
+        const current = pending.pop();
+        if (!current)
+            break;
+        const { node, path } = current;
+        if (++visited > 4096 || node === null || typeof node !== 'object' || Array.isArray(node))
+            throw Error('Invalid saved tree.');
+        for (const field of ['stageReads', 'stageWrites']) {
+            const view = own(node, field);
+            if (view !== undefined &&
+                (view === null ||
+                    typeof view !== 'object' ||
+                    Array.isArray(view) ||
+                    ![Object.prototype, null].includes(Object.getPrototypeOf(view))))
+                throw Error('Invalid saved captured view.');
+        }
+        const id = own(node, 'runtimeStageId');
+        if (id !== undefined) {
+            if (typeof id !== 'string' || !id.length || id.length > 128 || nodes.has(id))
+                throw Error('Ambiguous saved tree.');
+            nodes.set(id, node);
+            // JSON arrays of literal segments are injective; dotted/slashed business keys stay whole.
+            paths.set(JSON.stringify(path), id);
+        }
+        const next = own(node, 'next');
+        if (next !== undefined)
+            pending.push({ node: next, path: [...path, 'next'] });
+        const children = own(node, 'children');
+        if (children !== undefined) {
+            if (!Array.isArray(children) || children.length > 4096)
+                throw Error('Invalid saved tree.');
+            for (let index = children.length - 1; index >= 0; index--)
+                pending.push({ node: children[index], path: [...path, 'children', String(index)] });
+        }
+    }
+    const readKeys = new Map();
+    // FootPrint already validated the paths and their digest. Only project their recorded meaning.
+    for (const path of history.absent ?? []) {
+        const id = paths.get(JSON.stringify(path.slice(0, -2)));
+        if (id === undefined)
+            throw Error('Missing saved observation owner.');
+        if (path[path.length - 2] !== 'stageReads')
+            continue;
+        const keys = readKeys.get(id) ?? [];
+        const key = path[path.length - 1];
+        if (key === undefined)
+            throw Error('Missing saved observation key.');
+        keys.push(key);
+        readKeys.set(id, keys);
+    }
+    return { nodes, readKeys };
+}
+/** A narrow graph projection over admitted producer history, never a synthetic RuntimeSnapshot. */
+export function projectStoredCause(value, runId, maxBytes) {
+    try {
+        // Reuse the shared data-only copier. Its detached tree/sidecar/log are retained privately together.
+        const history = copyJson(value, maxBytes * 4, true, 256);
+        if (history.runId !== runId || !Array.isArray(history.commitLog))
+            return { status: 'unknown', reason: 'native-capture' };
+        if (history.commitLog.length > 4096)
+            return { status: 'unknown', reason: 'projection-incomplete' };
+        const version = own(history.capture, 'version');
+        if ((version !== 1 && version !== 2) ||
+            (version === 1 && own(history, 'readSources') !== undefined))
+            return { status: 'unknown', reason: 'native-capture' };
+        const sources = version === 2 ? storedCauseSources(history) : undefined;
+        if (typeof sources === 'string')
+            return { status: 'unknown', reason: sources };
+        const { nodes, readKeys } = savedNodes(history);
+        // These are facts from this one history; no runtime-only fields or alternate history are synthesized.
+        const basis = {
+            runId: history.runId,
+            capture: history.capture,
+            logAddress: own(history.capture, 'logAddress'),
+            commitValues: own(own(history.capture, 'modes'), 'commitValues'),
+            writeProvenance: own(own(history.capture, 'modes'), 'writeProvenance'),
+            commitLog: history.commitLog,
+            recorders: history.recorders,
+        };
+        const projected = projectCauseBasis(basis, nodes, undefined, {
+            readKeys,
+            ...(history.initialState === undefined ? {} : { initialState: history.initialState }),
+            ...(sources === undefined ? {} : { sources }),
+        });
+        if (projected === undefined || projected === 'truncated')
+            return { status: 'unknown', reason: 'projection-incomplete' };
+        if ([
+            'missing-attestation',
+            'invalid-attestation',
+            'run-mismatch',
+            'scope-not-covered',
+            'incomplete-extent',
+            'capture-limited',
+        ].includes(projected.capture.reason))
+            return { status: 'unknown', reason: 'native-capture' };
+        return {
+            status: 'ready',
+            cause: bindStoredCause(projected.graph, projected.capture, history, version),
+        };
+    }
+    catch {
+        return { status: 'unknown', reason: 'projection-incomplete' };
+    }
+}
+//# sourceMappingURL=storedCauseProjection.js.map

package/dist/esm/trace-toolpack/storedCauseProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storedCauseProjection.js","sourceRoot":"","sources":["../../../src/trace-toolpack/storedCauseProjection.ts"],"names":[],"mappings":"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"}

package/dist/esm/trace-toolpack/storedCauseReader.d.ts

@@ -0,0 +1,3 @@
+import type { readStoredCapture as DeclaredReader } from 'footprintjs/trace';
+/** The public reader when present; absent exports stay unsupported without a linking failure. */
+export declare const readStoredCapture: typeof DeclaredReader | undefined;

package/dist/esm/trace-toolpack/storedCauseReader.js

@@ -0,0 +1,9 @@
+// Older supported producers lack this optional reader. A named value import would
+// break browser linking even when unused; the named type still checks ownership.
+// The architecture test pins this exception to this one reader and public door.
+// eslint-disable-next-line no-restricted-syntax -- Optional reader; test/architecture/storedCauseReader.test.ts guards this single boundary.
+import * as producer from 'footprintjs/trace';
+const candidate = Reflect.get(producer, 'readStoredCapture');
+/** The public reader when present; absent exports stay unsupported without a linking failure. */
+export const readStoredCapture = typeof candidate === 'function' ? candidate : undefined;
+//# sourceMappingURL=storedCauseReader.js.map

package/dist/esm/trace-toolpack/storedCauseReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storedCauseReader.js","sourceRoot":"","sources":["../../../src/trace-toolpack/storedCauseReader.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,iFAAiF;AACjF,gFAAgF;AAChF,6IAA6I;AAC7I,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAC;AAE9C,MAAM,SAAS,GAAY,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;AAEtE,iGAAiG;AACjG,MAAM,CAAC,MAAM,iBAAiB,GAC5B,OAAO,SAAS,KAAK,UAAU,CAAC,CAAC,CAAE,SAAmC,CAAC,CAAC,CAAC,SAAS,CAAC"}

package/dist/esm/trace-toolpack/storedCauseSources.d.ts

@@ -0,0 +1,8 @@
+import type { StoredCaptureHistory } from 'footprintjs/trace';
+import type { RecordScope } from 'foottrace/cause';
+import type { SourceCaptureStatus } from './causeCapture.js';
+/** Policy over one public-reader-admitted history, not a second stored protocol validator. */
+export declare function storedCauseSources(history: StoredCaptureHistory): {
+    readonly status: SourceCaptureStatus;
+    readonly scope: NonNullable<RecordScope['readSources']>;
+} | 'source-ownership-unproven' | 'source-incomplete';

package/dist/esm/trace-toolpack/storedCauseSources.js

@@ -0,0 +1,28 @@
+/** Policy over one public-reader-admitted history, not a second stored protocol validator. */
+export function storedCauseSources(history) {
+    const sources = history.readSources;
+    if (sources?.version !== 2 ||
+        sources.ownership.version !== 1 ||
+        sources.ownership.status !== 'captured' ||
+        sources.ownership.limitations.length !== 0)
+        return 'source-ownership-unproven';
+    if (!sources.record ||
+        sources.record.version !== 1 ||
+        sources.record.segment !== 1 ||
+        !['captured', 'partial', 'failed', 'unknown'].includes(sources.status))
+        return 'source-incomplete';
+    return {
+        status: sources.status,
+        scope: {
+            record: sources.record,
+            // Only independently collected native ownership authorizes bindings. No source row,
+            // filename, receipt, guessed root namespace or fabricated attempt may supply them.
+            executions: sources.ownership.executions.map(({ runtimeStageId, stateAddress, attemptIds }) => ({
+                runtimeStageId,
+                stateAddress,
+                attemptIds,
+            })),
+        },
+    };
+}
+//# sourceMappingURL=storedCauseSources.js.map

package/dist/esm/trace-toolpack/storedCauseSources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storedCauseSources.js","sourceRoot":"","sources":["../../../src/trace-toolpack/storedCauseSources.ts"],"names":[],"mappings":"AAIA,8FAA8F;AAC9F,MAAM,UAAU,kBAAkB,CAAC,OAA6B;IAO9D,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IACpC,IACE,OAAO,EAAE,OAAO,KAAK,CAAC;QACtB,OAAO,CAAC,SAAS,CAAC,OAAO,KAAK,CAAC;QAC/B,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,UAAU;QACvC,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;QAE1C,OAAO,2BAA2B,CAAC;IACrC,IACE,CAAC,OAAO,CAAC,MAAM;QACf,OAAO,CAAC,MAAM,CAAC,OAAO,KAAK,CAAC;QAC5B,OAAO,CAAC,MAAM,CAAC,OAAO,KAAK,CAAC;QAC5B,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;QAEtE,OAAO,mBAAmB,CAAC;IAC7B,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,MAA6B;QAC7C,KAAK,EAAE;YACL,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,oFAAoF;YACpF,mFAAmF;YACnF,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAC1C,CAAC,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;gBACjD,cAAc;gBACd,YAAY;gBACZ,UAAU;aACX,CAAC,CACH;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/trace-toolpack/storedCauseTypes.d.ts

@@ -0,0 +1,48 @@
+import type { StoredRecordLimits } from 'foottrace';
+import type { CaptureReason, SnapshotCapture } from './causeCapture.js';
+import type { TraceCauseArtifacts } from './causeTypes.js';
+/** Host-only options for one already authorized saved root; no model storage selector. */
+export interface ReadStoredCauseOptions {
+    readonly runId: string;
+    /**
+     * Structural producer-reader allowances: finite non-negative integers only.
+     * Defaults: entries 16,384; missingCommits 4,096; drillDepth 64; addressLength 2,048.
+     * Entry ceiling: 65,536. The other defaults are their ceilings; lower values, including zero, are allowed.
+     * Requests above a ceiling are refused, never silently clamped.
+     */
+    readonly readerLimits?: StoredRecordLimits;
+    /** Producer-reader evidence limit. Default 1 MiB; integer 1..8 MiB. */
+    readonly maxBytes?: number;
+    /** Checked before and after admission; cannot preempt a synchronous host iterator. */
+    readonly signal?: AbortSignal;
+}
+/** Fixed failure vocabulary; private receipt data and exceptions are never returned. */
+export type StoredCauseUnknown = 'invalid-data' | 'reader-limit' | 'stored-admission' | 'native-capture' | 'projection-incomplete' | 'source-ownership-unproven' | 'source-incomplete' | 'cancelled' | 'unsupported' | 'unavailable';
+/** Separate native observation and adapter acknowledgement; neither authenticates a producer. */
+export interface StoredCauseAdmission {
+    readonly native: {
+        readonly status: 'admitted' | 'incomplete';
+        readonly reason: CaptureReason;
+        readonly version: 1 | 2;
+        readonly scope: 'root-log';
+        readonly persistence: 'memory-only';
+    };
+    readonly storage: {
+        readonly status: 'adapter-acknowledged-history';
+        readonly scope: 'root-log';
+    };
+    readonly readSources: SnapshotCapture['readSources'];
+}
+/** Factory-owned cause. This display assessment is not transferable serving authority. */
+export interface StoredCauseArtifacts extends TraceCauseArtifacts {
+    readonly admission: StoredCauseAdmission;
+}
+/** Unknown has no graph to query; ready does not promise a unique root. */
+export type StoredCauseResult = {
+    readonly status: 'ready';
+    readonly cause: StoredCauseArtifacts;
+} | {
+    readonly status: 'unknown';
+    readonly reason: StoredCauseUnknown;
+    readonly cause?: never;
+};

package/dist/esm/trace-toolpack/storedCauseTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storedCauseTypes.js.map

package/dist/esm/trace-toolpack/storedCauseTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storedCauseTypes.js","sourceRoot":"","sources":["../../../src/trace-toolpack/storedCauseTypes.ts"],"names":[],"mappings":""}

package/dist/esm/trace-toolpack/traceToolpack.js

@@ -43,6 +43,8 @@ import { boundedPreview, clampParam, displayKey, displayText, normalizeKey, rend
 import { askInner, framed, innerPackSlot } from './innerDescent.js';
 import { openRecording } from './openRecording.js';
 import { buildCauseTools } from './causeTools.js';
+import { storedCauseAssessment } from './storedCauseBinding.js';
+import { captureOwn } from './causeCapture.js';
 import { homeMountOf, innerCommitCount, mountChain, openSubflow, opensWithSeed, subflowResultsOf, subflowWrote, } from './subflowRecords.js';
 import { resolveToolpackOptions, TOOLPACK_HARD_CAPS, } from './types.js';
 // ── Display caps that are structural (not consumer-tunable) ───────────────
@@ -356,6 +358,22 @@ function matchWindow(text, needleLower, radius) {
  * agent mid-run — and treat tool outputs as data, not instructions.
  */
 export function traceToolpack(artifacts, options) {
+    // Saved-only evidence has its own graph-only door. Inspect the claim as data
+    // before a snapshot getter, indexing or any graph code can run.
+    let savedClaim = true;
+    try {
+        const cause = Object.getOwnPropertyDescriptor(artifacts, 'cause');
+        savedClaim =
+            storedCauseAssessment(artifacts).kind !== 'none' ||
+                (cause === undefined
+                    ? 'cause' in artifacts
+                    : storedCauseAssessment(captureOwn(artifacts, 'cause')).kind !== 'none');
+    }
+    catch {
+        // An accessor or hostile object cannot supply evidence for a mixed bag.
+    }
+    if (savedClaim)
+        throw new TypeError('Stored capture evidence requires traceCauseTools.');
     const opts = resolveToolpackOptions(options);
     const index = buildIndex(artifacts);
     // ONE reader over the scattered tool-call evidence, shared by the two