footprintjs 10.2.1 → 10.4.0

package/dist/types/lib/memory/runPolicy.d.ts

@@ -30,7 +30,7 @@
  * its own store when `mirror` is set.
  */
 import type { CommitValuesMode } from 'foottrace';
-import type { WriteProvenanceMode } from 'foottrace/write';
+import type { ReadSourceLimits, WriteProvenanceMode } from 'foottrace/write';
 import type { ReadTrackingMode, WriteTrackingMode } from './frameTypes.js';
 import type { RedactionRule } from './redaction.js';
 /**
@@ -38,6 +38,10 @@ import type { RedactionRule } from './redaction.js';
  * one is its default. `FlowChartExecutorOptions` extends this interface.
  */
 export interface RunDials {
+    /** Native, bounded scalar read-source occurrences (#113). Default false; memory-only in packet 3. */
+    readSources?: boolean | {
+        readonly limits: Partial<ReadSourceLimits>;
+    };
     /**
      * Policy for `StageSnapshot.stageReads` (#14). Default `'full'` — every
      * tracked read `structuredClone`s the value into the stage's read view

package/dist/types/lib/pause/types.d.ts

@@ -267,6 +267,8 @@ export interface PauseResult {
  * ```
  */
 export interface FlowchartCheckpoint {
+    /** Paused root-leg observation only. No history/recorder data or storage acknowledgement is included. */
+    readonly capture?: import('../capture/readSources.js').NativeCaptureObservation;
     /**
      * The checkpoint FORMAT: `2`, the lean checkpoint (`1` from 9.39.0; absent
      * before). `resume()` reads every older one through the one upcaster

package/dist/types/lib/recorder/ControlDepRecorder.d.ts

@@ -89,6 +89,8 @@ export interface ControlDecisionRecord {
     ruleLabel?: string;
 }
 export interface ControlDepRecorderOptions {
+    /** Opt in to a same-run collection acknowledgement in the snapshot bundle. */
+    captureCoverage?: boolean;
     /** Recorder id. Defaults to `control-deps-N` (auto-incremented). */
     id?: string;
 }
@@ -115,7 +117,11 @@ export declare class ControlDepRecorder implements FlowRecorder {
     private readonly consumedSlots;
     /** Convention 4 — runId of the run currently being recorded. */
     private lastRunId?;
+    private readonly captureCoverage;
+    private captureRunId?;
+    private captureIntact;
     constructor(options?: ControlDepRecorderOptions);
+    onRunStart(event: import('../engine/narrative/types.js').FlowRunEvent): void;
     onDecision(event: FlowDecisionEvent): void;
     onAttempt(event: FlowAttemptEvent): void;
     onSelected(event: FlowSelectedEvent): void;
@@ -146,13 +152,18 @@ export declare class ControlDepRecorder implements FlowRecorder {
      * Parentless roots cannot have a governing control edge.
      */
     toSnapshot(): {
-        name: string;
         data: {
             decisions: ControlDecisionRecord[];
             controlDeps: {
                 [k: string]: ControlDependency;
             };
         };
+        capture?: {
+            version: 1;
+            runId: string;
+            control: "captured" | "partial";
+        } | undefined;
+        name: string;
     };
     /** Reset all state (also happens automatically on runId change). */
     clear(): void;

package/dist/types/lib/recorder/snapshot.d.ts

@@ -16,4 +16,4 @@ import type { RecorderSnapshot } from '../runner/ExecutionRuntime.js';
 /** What `toSnapshot()` returns: a snapshot row without the `id` the attach site owns. */
 export type RecorderBundle = Omit<RecorderSnapshot, 'id'>;
 /** Rebuild `bundle` as the snapshot row for the recorder attached under `id`. */
-export declare function copyBundle(id: string, bundle: RecorderBundle): RecorderSnapshot;
+export declare function copyBundle(id: string, bundle: RecorderBundle, includeCapture?: boolean): RecorderSnapshot;

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

@@ -13,6 +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 { 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';
@@ -43,6 +48,8 @@ export interface RecorderSnapshot {
      * keep the values JSON-safe, since this rides the snapshot out to disk.
      */
     meta?: Readonly<Record<string, unknown>>;
+    /** Optional current-run capture acknowledgement from the recorder contract. */
+    capture?: RecorderCaptureAcknowledgement;
 }
 export type RuntimeSnapshot = {
     /**
@@ -57,6 +64,10 @@ export type RuntimeSnapshot = {
      * snapshot carries a DIFFERENT runId than the paused run's snapshot.
      */
     readonly runId: string;
+    /** Opt-in native observation; root log and current leg only, never durable storage. */
+    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
@@ -140,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;
     /**
@@ -161,6 +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
@@ -192,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

@@ -65,6 +65,8 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * See docs/guides/execution-model.md.
      */
     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;
@@ -188,6 +190,9 @@ 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,
      * the deadline, the declared budget, and the run a fresh-executor resume continues. Served by the record.

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/options.d.ts

@@ -59,6 +59,8 @@ export interface FlowChartExecutorOptions<TScope = any> extends RunDials {
      * ```
      */
     sink?: RecordSinkOption;
+    /** Opt in to a versioned, memory-only root-log capture note on snapshots (#111 stage 1). */
+    captureCoverage?: boolean;
     /**
      * Custom error classifier for throttling detection. Return `true` if a fork
      * child's error represents a rate-limit or backpressure condition; the
@@ -87,6 +89,7 @@ export interface ExecutorArgs<TOut, TScope> {
     dials: RunDials;
     /** The record sink, resolved and checked at construction (10.1, P6). */
     sink?: ResolvedRecordSink;
+    captureCoverage?: boolean;
 }
 /**
  * Resolve either constructor form. The 2-param form is the options form with

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/snapshot.d.ts

@@ -5,7 +5,9 @@
  * served subflow results (each subflow's own mirror under `redact: true`), one
  * recorder row per recorder id, and the deferred tier's accounting.
  */
+import type { FlowRecorder } from '../engine/narrative/types.js';
 import type { FlowchartTraverser } from '../engine/traversal/FlowchartTraverser.js';
+import type { ScopeRecorder } from '../scope/types.js';
 import type { RunObservers } from './attach.js';
 import type { RecorderSnapshot, RecordSinkStats, RuntimeSnapshot } from './ExecutionRuntime.js';
 /**
@@ -38,4 +40,4 @@ export declare function servedSnapshot(traverser: FlowchartTraverser<any, any>,
  * recorder cannot smuggle an `id` of its own choosing into the snapshot (the
  * id is the executor's, and consumers index by it).
  */
-export declare function collectRecorderSnapshots(observers: RunObservers): RecorderSnapshot[];
+export declare function collectRecorderSnapshots(observers: RunObservers, collected?: (recorder: ScopeRecorder | FlowRecorder, row: RecorderSnapshot) => void, includeCapture?: boolean): RecorderSnapshot[];

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/scope/runtime.d.ts

@@ -49,3 +49,5 @@ export declare function scopeRuntimeFor(scope: unknown): Readonly<ScopeRuntime>
 export declare function requireScopeRuntime(scope: unknown, message?: string): Readonly<ScopeRuntime>;
 /** @internal decide()/select() asked outside a stage: name THEM, not the custom-factory migration. */
 export declare function requireDecisionScopeRuntime(scope: unknown): Readonly<ScopeRuntime>;
+export declare function registerNativeCaptureTarget(target: object, context: object): void;
+export declare function hasNativeCaptureTarget(target: object, context: object): boolean;

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.2.1",
+  "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"