footprintjs 10.2.0 → 10.3.0

package/dist/types/lib/capture/nativeCoverage.d.ts

@@ -0,0 +1,56 @@
+import type { LogAddress } from 'foottrace';
+import type { TerminalFailureContext } from '../errors/terminalFailure.js';
+export type CaptureChannelStatus = 'captured' | 'disabled' | 'partial' | 'failed' | 'unknown';
+export type CaptureLimitation = 'tracked-state-only' | 'final-attempt-views' | 'read-sources-not-collected' | 'child-scopes-not-attested' | 'storage-not-attested' | 'resumed-segment' | 'redacted-export' | 'redaction-active' | 'custom-scope' | 'read-retention-failed' | 'commit-retention-failed' | 'attention-omitted' | 'recorder-snapshot-failed' | 'identity-omitted' | 'execution-broken' | 'modes-unavailable';
+/** A producer acknowledgement, not engine inspection of a recorder's implementation. */
+export interface RecorderCaptureAcknowledgement {
+    readonly version: 1;
+    readonly runId: string;
+    readonly control: 'captured' | 'partial' | 'unknown';
+}
+/** Engine observation of ONE root-log segment. Never a durable or whole-workflow completeness claim. */
+export interface NativeCaptureNote {
+    readonly version: 1;
+    readonly runId: string;
+    readonly scope: 'root-log';
+    readonly logAddress: LogAddress;
+    /** Half-open offsets in this log. A same-executor resume starts at the previous end. */
+    readonly commits: {
+        readonly from: number;
+        readonly to: number;
+    };
+    readonly boundary: {
+        readonly status: 'running' | 'completed' | 'paused' | 'failed' | 'cancelled';
+        readonly failure?: TerminalFailureContext;
+    };
+    readonly modes: {
+        readonly readTracking: 'full' | 'summary' | 'off' | 'unknown';
+        readonly writeTracking: 'full' | 'summary' | 'off' | 'unknown';
+        readonly commitValues: 'full' | 'delta' | 'unknown';
+        readonly writeProvenance: 'off' | 'reads-prefix' | 'unknown';
+    };
+    readonly channels: {
+        readonly reads: CaptureChannelStatus;
+        readonly writes: CaptureChannelStatus;
+        readonly attention: CaptureChannelStatus;
+        readonly control: CaptureChannelStatus;
+        readonly readSources: 'not-collected';
+    };
+    readonly persistence: 'memory-only';
+    readonly limitations: readonly CaptureLimitation[];
+}
+/** @internal Bounded facts collected at native funnels; no values, key names, recorder discovery or tree walk. */
+export declare class NativeCapture {
+    readonly runId: string;
+    readonly logAddress: LogAddress;
+    readonly from: number;
+    private readonly gaps;
+    private boundary;
+    private readonly modes;
+    constructor(runId: string, logAddress: LogAddress, from: number, modes: NativeCaptureNote['modes']);
+    limit(gap: CaptureLimitation): void;
+    end(status: NativeCaptureNote['boundary']['status'], failure?: TerminalFailureContext): void;
+    snapshot(to: number, control?: CaptureChannelStatus, redacted?: boolean): NativeCaptureNote;
+}
+/** Stored/recorder metadata is untrusted. Read data properties only, never getters or arbitrary strings. */
+export declare function copyCaptureAcknowledgement(value: unknown): RecorderCaptureAcknowledgement | undefined;

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

@@ -14,6 +14,7 @@
 import type { CommitPhase, EmitSourcePosition, UntrackedSource } from 'foottrace';
 import type { EventLog, SharedMemory } from 'foottrace/write';
 import type { AttemptContext, AttemptRecord, AttemptSummary, LateWrite } from '../attempt/types.js';
+import type { NativeCapture } from '../capture/nativeCoverage.js';
 import type { StructuredErrorInfo } from '../errors/errorInfo.js';
 import { type TerminalFailureContext, NativeFailureState } from '../errors/terminalFailure.js';
 import { type DiagnosticChannel, DiagnosticCollector } from './DiagnosticCollector.js';
@@ -57,6 +58,8 @@ export declare class StageContext {
     private policy;
     /** The emitting frame's logical leg, never the mutable executor's current leg. */
     private emitRunId?;
+    /** The native root-log collector; copied to same-log frames, never child runtimes. */
+    capture?: NativeCapture;
     stageName: string;
     /** Unique stage identifier from the builder (matches spec node id). */
     stageId: string;
@@ -342,6 +345,7 @@ export declare class StageContext {
      * `'summary'` records a cheap marker, `'off'` records nothing.
      */
     getValue(path: string[], key?: string, description?: string): unknown;
+    private readRetainedValue;
     /**
      * How many tracked reads of this frame read a value the run's rule selects
      * (a key it masks whole, or one with secret fields). A boundary that maps
@@ -455,6 +459,7 @@ export declare class StageContext {
      *   reads them post-run for the execution-tree snapshot.
      */
     commit(phase?: CommitPhase): void;
+    private commitRetained;
     /** Whether this frame has committed — a call's record arriving after it is late (P2, `ScopeFacade · call`). */
     get committed(): boolean;
     /**

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

@@ -3,11 +3,13 @@ import type { Attention } from 'foottrace';
 import type { AttemptRecord, AttemptSummary } from '../attempt/types.js';
 /** One execution's ownership, pending summary, marks and omission accounting stay in this helper. */
 export declare class StageAttention {
+    private readonly onOmitted?;
     private marks?;
     private omitted;
     private retryPossible;
     private summary?;
     private terminal?;
+    constructor(onOmitted?: (() => void) | undefined);
     /** A new execution starts fresh; an attempt discard never calls this. No collection is reconstructed. */
     begin(): void;
     /** Called only after the frame retained this attempt. Raw error, target and decision payloads are never read. */

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,8 @@ 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 { NativeCapture } from '../capture/nativeCoverage.js';
 import type { StageSnapshot } from '../memory/frameTypes.js';
 import type { RunPolicy } from '../memory/runPolicy.js';
 import { StageContext } from '../memory/StageContext.js';
@@ -43,6 +45,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 +61,8 @@ 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?: NativeCaptureNote;
     /**
      * 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
@@ -161,6 +167,9 @@ export interface RuntimeRecord {
     readonly meta?: Meta;
 }
 export declare class ExecutionRuntime {
+    /** Present only for the current opted-in root leg. Never inherited by a subflow runtime. */
+    capture?: NativeCapture;
+    beginCapture(runId: string): NativeCapture;
     globalStore: SharedMemory;
     /**
      * Parallel redacted mirror of `globalStore`. Populated by every commit that

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

@@ -65,6 +65,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * See docs/guides/execution-model.md.
      */
     private _isExecuting;
+    private captureSignal?;
     private failureState;
     /** Safe native context for the latest rejected leg; undefined before, during, after success or pause. */
     getFailureContext(): TerminalFailureContext | undefined;
@@ -188,6 +189,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * the `RecordSinkError`.
      */
     private settleRecorded;
+    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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",