footprintjs 10.1.0 → 10.2.0

package/dist/types/index.d.ts

@@ -48,6 +48,8 @@ export { narrative } from './recorders.js';
 export type { DecideRule, DecisionEvidence, DecisionResult, DefaultBranch, FilterOps, RuleEvidence, SelectionEvidence, SelectionResult, WhenClause, WhereFilter, } from './lib/decide/index.js';
 /** @category Decision Branching */
 export { decide, select } from './lib/decide/index.js';
+/** @category Errors */
+export type { TerminalFailureContext } from './lib/errors/terminalFailure.js';
 /**
  * @category Attempts
  *

package/dist/types/lib/attempt/category.d.ts

@@ -29,3 +29,9 @@ import type { AttemptCategory, AttemptOutcome } from './types.js';
  * `'timeout'` (the attempt's own timer) and `'unknown'` (the run's signal) before the error is read.
  */
 export declare function errorCategory(error: unknown, outcome?: AttemptOutcome): AttemptCategory;
+/**
+ * @internal Terminal ownership preserves a producer's known category. An
+ * unresolved effect is unknown, never the category of its physical cause.
+ * This does not rewrite historical attempt categories or re-read a known one.
+ */
+export declare function terminalCategory(error: unknown, known?: AttemptCategory): AttemptCategory;

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

@@ -63,7 +63,7 @@
  */
 import type { StructuredErrorInfo } from '../errors/errorInfo.js';
 import type { EffectTarget } from './effect.js';
-import type { AttemptContext, AttemptKind, AttemptRecord, AttemptSummary, ObservedAttempt, RetryPolicy } from './types.js';
+import type { AttemptCategory, AttemptContext, AttemptKind, AttemptRecord, AttemptSummary, ObservedAttempt, RetryPolicy } from './types.js';
 /** What a series reports, and the engine's between-attempt step. Every member is optional. */
 export interface AttemptRunOptions {
     /** The series every record names — for a stage attempt, its execution's `runtimeStageId`. */
@@ -95,6 +95,8 @@ export interface AttemptRunOptions {
     readonly onRetry?: (attempt: number, of: number, delayMs: number, structuredError: StructuredErrorInfo) => void;
     /** The series ended: called once, before the last `onAttempt` (or after a wait the run's signal cut). */
     readonly onEnd?: (summary: AttemptSummary) => void;
+    /** @internal Native owner only: the exact escaping value and category, before its stage serves the error. */
+    readonly onFailure?: (error: unknown, category: AttemptCategory) => void;
     /** `retryOn` threw — the attempt is treated as declined; the engine logs the throw here. */
     readonly onRetryOnThrew?: (thrown: unknown) => void;
     /**

package/dist/types/lib/engine/handlers/commitStage.d.ts

@@ -8,6 +8,13 @@
  * outright); it is a stage failure like any other, so `onError` fires for the
  * stage before the error propagates.
  */
+import type { CommitPhase } from 'foottrace';
 import type { StageContext } from '../../memory/StageContext.js';
 import type { IControlFlowNarrative, TraversalContext } from '../narrative/types.js';
+/**
+ * All native stage commits own their exact escaping commit error, including
+ * commits while another error or pause was bubbling. Capture safe ownership
+ * only; existing diagnostic/event behavior stays with the caller.
+ */
+export declare function commitStageWrites(context: StageContext, phase?: CommitPhase): void;
 export declare function commitStage(context: StageContext, narrative: IControlFlowNarrative, stageName: string, traversalContext?: TraversalContext): void;

package/dist/types/lib/engine/handlers/stageError.d.ts

@@ -14,6 +14,8 @@ export declare function recordStageError(context: StageContext, error: unknown):
     message: string;
     structuredError: StructuredErrorInfo;
 };
+/** Capture before commit observers or diagnostic serving can change the raw value. */
+export declare function captureStageFailure(context: StageContext, error: unknown): void;
 /** The served form of a thrown value at any other report of a stage failure (retry, throttle). */
 export declare function servedStageError(context: StageContext, error: unknown): StructuredErrorInfo;
 /** What the logger is handed: the thrown value, or its masked form when the policy masked its text. */

package/dist/types/lib/engine/narrative/FlowRecorderDispatcher.d.ts

@@ -13,6 +13,7 @@
 import type { AttemptRecord } from '../../attempt/types.js';
 import type { DecisionEvidence, SelectionEvidence } from '../../decide/types.js';
 import type { StructuredErrorInfo } from '../../errors/errorInfo.js';
+import type { TerminalFailureContext } from '../../errors/terminalFailure.js';
 import type { FlowRecorder, IControlFlowNarrative, StageType, TraversalContext } from './types.js';
 export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     private recorders;
@@ -42,7 +43,7 @@ export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     onResume(stageName: string, stageId: string, hasInput: boolean, traversalContext?: TraversalContext): void;
     onRunStart(input: unknown, traversalContext?: TraversalContext): void;
     onRunEnd(output: unknown, traversalContext?: TraversalContext): void;
-    onRunFailed(error: StructuredErrorInfo, traversalContext?: TraversalContext): void;
+    onRunFailed(error: StructuredErrorInfo, traversalContext?: TraversalContext, failure?: TerminalFailureContext): void;
     /**
      * Returns sentences from an attached NarrativeFlowRecorder (looked up by ID).
      * Callers that need sentences should attach a NarrativeFlowRecorder with id 'narrative'

package/dist/types/lib/engine/narrative/types.d.ts

@@ -9,6 +9,7 @@
 import type { AttemptRecord, RunCorrelation } from '../../attempt/types.js';
 import type { DecisionEvidence, SelectionEvidence } from '../../decide/types.js';
 import type { StructuredErrorInfo } from '../../errors/errorInfo.js';
+import type { TerminalFailureContext } from '../../errors/terminalFailure.js';
 /**
  *
  * Uses Null Object pattern: NullControlFlowNarrativeGenerator satisfies this
@@ -131,7 +132,7 @@ export interface IControlFlowNarrative {
      * error, so it does not fire this. Subflow-traversers do NOT fire it;
      * their errors propagate to the parent and surface at the top level.
      */
-    onRunFailed(error: StructuredErrorInfo, traversalContext?: TraversalContext): void;
+    onRunFailed(error: StructuredErrorInfo, traversalContext?: TraversalContext, failure?: TerminalFailureContext): void;
     /** Returns accumulated narrative sentences in execution order. */
     getSentences(): string[];
 }
@@ -487,6 +488,8 @@ export interface FlowRunFailedEvent {
     /** Structured details of the error that terminated the run. */
     structuredError: StructuredErrorInfo;
     traversalContext?: TraversalContext;
+    /** Native terminal ownership, independent of served error details. Absent on legacy manually emitted events. */
+    readonly failure?: TerminalFailureContext;
 }
 /**
  * FlowRecorder — Pluggable observer for control flow events.

package/dist/types/lib/errors/terminalFailure.d.ts

@@ -0,0 +1,29 @@
+import type { AttemptCategory } from '../attempt/types.js';
+/** Safe context for the failure that escaped a native run; never the exception itself. */
+export interface TerminalFailureContext {
+    readonly category: AttemptCategory;
+    /** Absent when no native stage owns this failure (for example input admission or run retention). */
+    readonly stage?: {
+        readonly runId: string;
+        readonly runtimeStageId: string;
+    };
+}
+/**
+ * @internal One execution chain's failure ownership, not an error history.
+ * Sequential frames share it; forks and subflows do not. Only an explicitly
+ * selected escaping rejection may transfer ownership to its parent chain.
+ * Raw identity lives in a private slot and is released when the leg settles.
+ */
+export declare class NativeFailureState {
+    #private;
+    get result(): TerminalFailureContext | undefined;
+    capture(error: unknown, category: AttemptCategory, stage: NonNullable<TerminalFailureContext['stage']>): void;
+    /** A runner already classified this exact native failure before it was served. */
+    owns(error: unknown): boolean;
+    adopt(child: NativeFailureState, error: unknown): void;
+    /** Publish at the run event boundary; keep ownership until executor settlement. */
+    announce(error: unknown): TerminalFailureContext;
+    finish(error: unknown): void;
+    /** Success or pause has no terminal failure. Also closes contained branch ownership. */
+    complete(): void;
+}

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

@@ -15,6 +15,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 { StructuredErrorInfo } from '../errors/errorInfo.js';
+import { type TerminalFailureContext, NativeFailureState } from '../errors/terminalFailure.js';
 import { type DiagnosticChannel, DiagnosticCollector } from './DiagnosticCollector.js';
 import type { FlowControlType, StageSnapshot } from './frameTypes.js';
 import type { RedactionVerdict } from './redaction.js';
@@ -27,6 +28,13 @@ import type { RunPolicy } from './runPolicy.js';
  */
 export declare const MAX_CALL_RECORDS = 1000;
 export declare class StageContext {
+    #private;
+    /** @internal Ownership of an escaping failure. Shared only by sequential frames, never serialized. */
+    failureState: NativeFailureState;
+    /** @internal The native frame stamp, independent of mutable recorder event context. */
+    get failureIdentity(): NonNullable<TerminalFailureContext['stage']> | undefined;
+    /** @internal Stamped before observers; never inherited by another frame or persisted. */
+    bindFailureIdentity(runId: string, runtimeStageId: string): void;
     /**
      * The record half of this frame (`RecordFrame.ts`, L3, C3): the heap and,
      * when the run keeps them, the redacted mirror and the log; the address;
@@ -156,6 +164,8 @@ export declare class StageContext {
     private _attempts?;
     /** The attempt series at a glance, stamped once when it ends. */
     private _attemptSummary?;
+    /** Facts collected for this execution only; retry discards deliberately keep them. */
+    private _attention?;
     /**
      * The attempt now running (P1b) — set by `StageRunner` before the scope is built, so the facade can hand it out
      * (`scope.$attempt()`) and fence its own attempt. Absent for a stage the attempt runner does not run.
@@ -485,6 +495,10 @@ export declare class StageContext {
     recordAttempt(record: AttemptRecord): void;
     /** Stamp the series' summary — once, when the runner ends the series. */
     endAttempts(summary: AttemptSummary): void;
+    /** Reset only at the node's execution stamp, never between attempts. */
+    beginAttention(): void;
+    /** Delegate the explicit retained-error fact; attention owns validation of its proof. */
+    markStageFailure(): void;
     /**
      * The crash-safe record (10.1, P6): an attempt that ended is noted in the run's sink AT ONCE, beside this frame's
      * log — so a process killed before the stage commits (mid-retry) still leaves every attempt that ended. The

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

@@ -0,0 +1,26 @@
+/** Engine-owned attention is collected with retained facts; snapshots only copy this bounded projection. */
+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 marks?;
+    private omitted;
+    private retryPossible;
+    private summary?;
+    private terminal?;
+    /** 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. */
+    recordAttempt(record: AttemptRecord, owner: string): void;
+    recordSummary(summary: AttemptSummary): void;
+    /** A summary-only cut wait has no phantom final attempt; use its actual retained summary. */
+    private projectSummary;
+    /** Only the explicit retained stage-error path calls this; a diagnostic value never classifies itself. */
+    stageFailed(errors: unknown): void;
+    attemptDropped(): void;
+    /** Keep only bounded exact references; one slot is reserved to disclose omissions. */
+    append(attention: Attention): void;
+    missing(): void;
+    /** Copy already collected bounded marks, never an attempt array, diagnostic bag or execution tree. */
+    snapshot(): readonly Attention[];
+}

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

@@ -12,6 +12,7 @@
  * A `StageSnapshot` is an `ExecutionTree` (`types.ts`), the shape the record's readers walk:
  * `commitStops`, `tagStops` and `keysReadFromExecutionTree` take one.
  */
+import type { Attention } from 'foottrace';
 import type { AttemptRecord, AttemptSummary, LateWrite } from '../attempt/types.js';
 import type { RetentionPolicy } from '../capture/policies.js';
 /** Types of control flow decisions captured by the execution engine. */
@@ -123,6 +124,13 @@ export type StageSnapshot = {
      * there were none.
      */
     lateWrites?: readonly LateWrite[];
+    /**
+     * Fixed-reason marks collected as this execution runs. Absent when no fact needs attention.
+     * Attempt evidence uses canonical Foottrace attempt IDs. Summary-only and stage-error proof resolves within THIS node
+     * through attemptSummary, errors:stageExecutionError or attemptsDropped. Quality marks are read-time recorder work.
+     * Marks retain no error text, values, targets or idempotency keys; omitted proof is disclosed as not-collected.
+     */
+    attention?: readonly Attention[];
     next?: StageSnapshot;
     children?: StageSnapshot[];
 };

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

@@ -140,6 +140,20 @@ export declare class ControlDepRecorder implements FlowRecorder {
     getAttemptStop(runtimeStageId: string): ControlDecisionRecord | undefined;
     /** All decisions recorded for the current run, in event order — deciders, selectors and attempt stops. */
     getDecisions(): ControlDecisionRecord[];
+    /**
+     * Current-run control evidence for the native snapshot. Project only the
+     * stage identities collected during traversal; never walk the execution tree.
+     * Parentless roots cannot have a governing control edge.
+     */
+    toSnapshot(): {
+        name: string;
+        data: {
+            decisions: ControlDecisionRecord[];
+            controlDeps: {
+                [k: string]: ControlDependency;
+            };
+        };
+    };
     /** Reset all state (also happens automatically on runId change). */
     clear(): void;
     /** Convention 4: a new runId means a new run — reset transient state. */

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

@@ -28,6 +28,7 @@ import type { CombinedNarrativeEntry } from '../engine/narrative/narrativeTypes.
 import type { ManifestEntry } from '../engine/narrative/recorders/ManifestFlowRecorder.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
 import { type ExecutorResult, type RunOptions, type ScopeFactory, type SerializedPipelineStructure, type StageNode, type SubflowResult } from '../engine/types.js';
+import { type TerminalFailureContext } from '../errors/terminalFailure.js';
 import type { ReadTrackingMode, WriteTrackingMode } from '../memory/frameTypes.js';
 import type { FlowchartCheckpoint } from '../pause/types.js';
 import type { CombinedRecorder } from '../recorder/CombinedRecorder.js';
@@ -64,6 +65,9 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * See docs/guides/execution-model.md.
      */
     private _isExecuting;
+    private failureState;
+    /** Safe native context for the latest rejected leg; undefined before, during, after success or pause. */
+    getFailureContext(): TerminalFailureContext | undefined;
     private readonly flowChartArgs;
     /**
      * The crash-safe record of the current run (10.1, P6) — the sink every log of the run writes to, its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -38,7 +38,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "clean": "rm -rf build/* coverage dist node_modules package-lock.json",
+    "clean": "rm -rf build/* coverage dist node_modules",
     "build": "rm -rf dist && tsc && tsc -p tsconfig.esm.json && node scripts/postbuild-esm.mjs",
     "prepare": "husky",
     "watch": "tsc -w",
@@ -189,7 +189,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "foottrace": "^1.1.0"
+    "foottrace": "^1.3.0"
   },
   "peerDependencies": {
     "zod": "^3.0.0 || ^4.0.0"
@@ -201,12 +201,12 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.1",
-    "@typescript-eslint/eslint-plugin": "^5.61.0",
-    "@typescript-eslint/parser": "^5.61.0",
+    "@typescript-eslint/eslint-plugin": "^8.71.2",
+    "@typescript-eslint/parser": "^8.71.2",
     "@vitest/coverage-v8": "^4.1.8",
     "concurrently": "^8.0.1",
     "esbuild": "^0.28.0",
-    "eslint": "^8.44.0",
+    "eslint": "^8.57.1",
     "eslint-config-prettier": "^6.15.0",
     "eslint-config-standard": "^17.0.0",
     "eslint-import-resolver-typescript": "^3.5.2",