footprintjs 10.3.0 → 10.4.0

package/dist/types/lib/runner/ExecutionRuntime.d.ts

@@ -13,8 +13,11 @@ import type { CommitBundle, CommitValuesMode, LogAddress, LogOutcome, Meta } fro
 import type { RecordSink, WriteProvenanceMode } from 'foottrace/write';
 import { EventLog, SharedMemory } from 'foottrace/write';
 import type { RunCorrelation } from '../attempt/types.js';
-import type { NativeCaptureNote, RecorderCaptureAcknowledgement } from '../capture/nativeCoverage.js';
+import type { CaptureHistoryStatus } from '../capture/historyTypes.js';
+import type { CaptureChannelStatus, RecorderCaptureAcknowledgement } from '../capture/nativeCoverage.js';
 import { NativeCapture } from '../capture/nativeCoverage.js';
+import type { EngineReadSources, NativeCaptureObservation, SourceLimitation } from '../capture/readSources.js';
+import { EngineReadSourceCapture } from '../capture/readSources.js';
 import type { StageSnapshot } from '../memory/frameTypes.js';
 import type { RunPolicy } from '../memory/runPolicy.js';
 import { StageContext } from '../memory/StageContext.js';
@@ -62,7 +65,9 @@ export type RuntimeSnapshot = {
      */
     readonly runId: string;
     /** Opt-in native observation; root log and current leg only, never durable storage. */
-    readonly capture?: NativeCaptureNote;
+    readonly capture?: NativeCaptureObservation;
+    /** Opt-in ordered native occurrences. Unknown ownership has no record; never infer observed-empty. */
+    readonly readSources?: EngineReadSources;
     /**
      * The run's correlation (10.1) — `env.traceparent`, or `env.traceId` + `env.operationId`, resolved once per
      * leg; the same frozen object every event of the leg carries (`TraversalContext.correlation`, a scope event's
@@ -146,6 +151,8 @@ export type RuntimeSnapshot = {
 };
 /** `getSnapshot().sink` — what the run handed its sink, and what the sink did not take (10.1, P6). */
 export interface RecordSinkStats {
+    /** Present only when explicit capture persistence was requested. Never inferred from an ordinary flush. */
+    readonly capture?: CaptureHistoryStatus;
     /** Entries handed to the adapter (each `opened`, `commit`, `note`, `closed` call). */
     readonly entries: number;
     /**
@@ -167,9 +174,13 @@ export interface RuntimeRecord {
     readonly meta?: Meta;
 }
 export declare class ExecutionRuntime {
+    readSources?: EngineReadSourceCapture;
     /** Present only for the current opted-in root leg. Never inherited by a subflow runtime. */
     capture?: NativeCapture;
     beginCapture(runId: string): NativeCapture;
+    /** A reused log cannot be retrofitted or relabelled as the new leg's base. */
+    resumeReadSources(runId: string): void;
+    captureSnapshot(to: number, control?: CaptureChannelStatus, redact?: boolean): NativeCaptureObservation | undefined;
     globalStore: SharedMemory;
     /**
      * Parallel redacted mirror of `globalStore`. Populated by every commit that
@@ -201,7 +212,10 @@ export declare class ExecutionRuntime {
      *   every frame after inherits the same reference. Default: every dial at
      *   its default, no rule, no mirror.
      */
-    constructor(rootName: string, rootId: string, defaultValues?: unknown, initialState?: unknown, policy?: RunPolicy, record?: RuntimeRecord);
+    constructor(rootName: string, rootId: string, defaultValues?: unknown, initialState?: unknown, policy?: RunPolicy, record?: RuntimeRecord, source?: {
+        readonly runId: string;
+        readonly unavailable?: SourceLimitation;
+    });
     /**
      * A fresh root frame for this runtime — `globalStore`, `executionHistory`,
      * the run's policy and (when kept) the mirror. Also how `SubflowExecutor`

package/dist/types/lib/runner/FlowChartExecutor.d.ts

@@ -66,6 +66,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      */
     private _isExecuting;
     private captureSignal?;
+    private captureHistoryLease?;
     private failureState;
     /** Safe native context for the latest rejected leg; undefined before, during, after success or pause. */
     getFailureContext(): TerminalFailureContext | undefined;
@@ -189,6 +190,8 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * the `RecordSinkError`.
      */
     private settleRecorded;
+    private settleRecordedLeg;
+    private saveCaptureHistory;
     private finishCapture;
     /**
      * What a new root log opens with: names and numbers the run already serves — the run, the chart, the correlation,

package/dist/types/lib/runner/captureHistory.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutionRuntime, RuntimeSnapshot } from './ExecutionRuntime.js';
+import type { RunRecord } from './recordSink.js';
+/** @internal Keeps a timed-out operation leased until its actual settlement. */
+export interface CaptureHistoryLease {
+    pending: boolean;
+}
+/** Persist one terminal native root segment, without changing its memory-only engine observation. */
+export declare function persistCaptureHistory(runtime: ExecutionRuntime, record: RunRecord, snapshot: () => RuntimeSnapshot, lease: CaptureHistoryLease): Promise<void>;

package/dist/types/lib/runner/checkpoint.d.ts

@@ -36,10 +36,12 @@
  * DESCRIPTIVE contract error naming the field (`describeCheckpointCloneFailure`)
  * instead of a naked `DataCloneError`.
  */
+import type { NativeCaptureObservation } from '../capture/readSources.js';
 import type { FlowchartTraverser } from '../engine/traversal/FlowchartTraverser.js';
 import type { FlowchartCheckpoint, PauseSignal, RedactionMarks } from '../pause/types.js';
 /** The paused run's counters, as the executor holds them at the pause. */
 export interface PausedRun {
+    readonly capture?: NativeCaptureObservation;
     readonly runId: string;
     readonly executionCount: number;
     readonly visitCounts: ReadonlyMap<string, number>;

package/dist/types/lib/runner/index.d.ts

@@ -1,3 +1,4 @@
+export type { CaptureHistoryOptions, CaptureHistoryReceipt, CaptureHistoryStatus, CaptureHistoryTarget, } from '../capture/historyTypes.js';
 export type { ComposableRunner } from './ComposableRunner.js';
 export type { AttachRecorderOptions, ObserverDelivery, ObserverDrainResult, ObserverStats, } from './DeferredObserverTier.js';
 export type { RecorderSnapshot, RecordSinkStats, RuntimeSnapshot } from './ExecutionRuntime.js';

package/dist/types/lib/runner/readStoredCapture.d.ts

@@ -0,0 +1,39 @@
+import type { CommitBundle, StoredRecordLimits } from 'foottrace';
+import type { CaptureHistoryReceipt } from '../capture/historyTypes.js';
+import type { NativeCaptureNote } from '../capture/nativeCoverage.js';
+import type { StageSnapshot } from '../memory/frameTypes.js';
+import type { RecorderSnapshot } from './ExecutionRuntime.js';
+/** Engine history whose storage evidence matched. Channels and native limitations retain their original meanings. */
+export interface StoredCaptureHistory {
+    readonly runId: string;
+    readonly capture: NativeCaptureNote;
+    readonly executionTree: StageSnapshot;
+    /**
+     * Sorted literal paths of own undefined stageReads/stageWrites entries omitted by JSON.
+     * Read alongside executionTree; this is not proof that the underlying state key never existed.
+     * At most 4096 paths of 256 segments, within the evidence byte limit. No entries are truncated.
+     */
+    readonly absent?: readonly (readonly string[])[];
+    readonly recorders?: readonly RecorderSnapshot[];
+    readonly commitLog: readonly CommitBundle[];
+    readonly initialState?: Record<string, unknown>;
+    readonly receipt: CaptureHistoryReceipt;
+}
+export type StoredCaptureResult = {
+    readonly status: 'acknowledged';
+    readonly history: StoredCaptureHistory;
+} | {
+    readonly status: 'unknown';
+    readonly reason: string;
+    readonly history?: never;
+};
+/**
+ * Read authorized stored entries using Foottrace's sequence/gap checks, then validate FootPrint's opaque metadata.
+ * A receipt is a host-adapter assertion, not a signature. Callers still own storage authorization and trust.
+ * Never performs causal analysis or upgrades partial native capture to complete.
+ */
+export declare function readStoredCapture(entries: Iterable<unknown>, options: {
+    runId: string;
+    limits?: StoredRecordLimits;
+    maxBytes?: number;
+}): Promise<StoredCaptureResult>;

package/dist/types/lib/runner/recordSink.d.ts

@@ -23,6 +23,7 @@
  */
 import type { Meta } from 'foottrace';
 import type { RecordSink } from 'foottrace/write';
+import type { CaptureHistoryOptions, CaptureHistoryStatus } from '../capture/historyTypes.js';
 import type { RedactionRule } from '../memory/redaction.js';
 import type { RecordSinkStats } from './ExecutionRuntime.js';
 /** What a lost entry does to the run: `'report'` counts it and goes on; `'fail'` fails the run. */
@@ -44,6 +45,8 @@ export interface RecordSinkOptions {
     readonly onFailure?: RecordSinkFailureMode;
     /** `'auto'` (default): `run()` awaits the adapter's `flush()` after the closing entry. `'manual'`: `flushRecord()`. */
     readonly flush?: RecordSinkFlushMode;
+    /** Opt-in capture evidence and explicit host acknowledgement; ordinary flush never implies durability. */
+    readonly capture?: CaptureHistoryOptions;
 }
 /** The executor's `sink` option: an adapter, or {@link RecordSinkOptions}. */
 export type RecordSinkOption = RecordSink | RecordSinkOptions;
@@ -70,6 +73,7 @@ export interface ResolvedRecordSink {
     readonly adapter: RecordSink;
     readonly onFailure: RecordSinkFailureMode;
     readonly flush: RecordSinkFlushMode;
+    readonly capture?: CaptureHistoryOptions;
 }
 /**
  * Resolve the executor's `sink` option, or refuse it with a `TypeError` naming what is wrong — a wiring mistake
@@ -92,6 +96,8 @@ export declare class RunRecord {
     /** Aborted at the first loss under `'fail'` — composed into the leg's signal; fresh per leg ({@link beginLeg}). */
     private stopper?;
     private failure?;
+    private capturePending;
+    private captureStatus?;
     /** Opaque error identities only: no raw entry or adapter error is enumerable on the transport error. */
     private readonly invocationFailures;
     constructor(resolved: ResolvedRecordSink);
@@ -113,6 +119,11 @@ export declare class RunRecord {
     /** The loss that fails the run under `'fail'`; absent while nothing was lost (and always under `'report'`). */
     get fatal(): RecordSinkError | undefined;
     stats(): RecordSinkStats;
+    get captureOptions(): CaptureHistoryOptions | undefined;
+    get pendingCaptureDeliveries(): number;
+    captureResult(result: CaptureHistoryStatus): void;
+    /** Same served seed as opened; a history digest never sees a seeded policy secret. */
+    captureInitialState(state: Record<string, unknown>): Record<string, unknown>;
     /**
      * Await the adapter's `flush()`, at most `timeoutMs` when given. A flush that throws or rejects is a loss
      * (counted, and fatal under `'fail'`); one still running at the deadline is `pending` and keeps running — and,

package/dist/types/lib/runner/storedCaptureAdmission.d.ts

@@ -0,0 +1,4 @@
+import type { StoredLog } from 'foottrace';
+import type { StoredCaptureResult } from './readStoredCapture.js';
+/** @internal Engine-metadata admission after Foottrace's generic record validation. */
+export declare function admitStoredCapture(log: StoredLog, runId: string, maxBytes: number): Promise<StoredCaptureResult>;

package/dist/types/lib/sinks/fileSink.d.ts

@@ -42,6 +42,7 @@
  * `readStoredRecord`); for richer values, bring an adapter with a richer encoding.
  */
 import type { RecordSink } from 'foottrace/write';
+import type { CaptureHistoryOptions } from '../capture/historyTypes.js';
 /** The default cap on a record file: 64 MiB. */
 export declare const DEFAULT_FILE_SINK_MAX_BYTES: number;
 /** The default cap on ONE entry's line: 8 MiB. */
@@ -69,7 +70,7 @@ export interface FileSinkOptions {
     readonly flushTimeoutMs?: number;
 }
 /** A record sink that appends to one file — `RecordSink` plus what the app needs to manage the file. */
-export interface FileSink extends RecordSink {
+export interface FileSink extends RecordSink, Pick<CaptureHistoryOptions, 'acknowledge'> {
     /** The absolute path the sink writes to — resolved once, when it was made. */
     readonly path: string;
     /**

package/dist/types/trace.d.ts

@@ -21,3 +21,5 @@ export { formatQualityTrace, qualityTrace } from './lib/recorder/qualityTrace.js
 export { SequenceStore } from './lib/recorder/SequenceStore.js';
 export type { Topology, TopologyEdge, TopologyIncomingKind, TopologyNode, TopologyNodeKind, TopologyRecorderOptions, } from './lib/recorder/TopologyRecorder.js';
 export { TopologyRecorder, topologyRecorder } from './lib/recorder/TopologyRecorder.js';
+export type { StoredCaptureHistory, StoredCaptureResult } from './lib/runner/readStoredCapture.js';
+export { readStoredCapture } from './lib/runner/readStoredCapture.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "10.3.0",
+  "version": "10.4.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -189,7 +189,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "foottrace": "^1.3.0"
+    "foottrace": "^1.7.0"
   },
   "peerDependencies": {
     "zod": "^3.0.0 || ^4.0.0"