footprintjs 10.0.1 → 10.2.0

package/dist/types/lib/builder/FlowChartBuilder.d.ts

@@ -11,10 +11,11 @@
  * The execute() convenience method is intentionally omitted —
  * it belongs in the runner layer (Phase 5).
  */
-import type { ParallelForEachConfig, RetryPolicy, ScopeFactory } from '../engine/types.js';
+import type { ParallelForEachConfig, RetryPolicy, ScopeFactory, StageTouches } from '../engine/types.js';
 import type { PausableHandler } from '../pause/types.js';
 import type { TypedScope } from '../reactive/types.js';
 import { type RunnableFlowChart } from '../runner/RunnableChart.js';
+import type { RetryLoopOptions } from './retryLoop.js';
 import type { StructureEdgeKind, StructureRecorder } from './structure/StructureRecorder.js';
 import { StructureRecorderDispatcher } from './structure/StructureRecorderDispatcher.js';
 import { type TypedStageFunction } from './typedFlowChart.js';
@@ -35,6 +36,7 @@ export declare class DeciderList<TOut = any, TScope = any> {
     options?: {
         readonly loopTo?: string;
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     /**
@@ -54,6 +56,7 @@ export declare class DeciderList<TOut = any, TScope = any> {
     options?: {
         readonly loopTo?: string;
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): DeciderList<TOut, TScope>;
@@ -107,6 +110,7 @@ export declare class SelectorFnList<TOut = any, TScope = any> {
      *  `{ tags }` puts declared tags on it (see `FlowChartBuilder.tag`). */
     options?: {
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     /**
@@ -122,6 +126,7 @@ export declare class SelectorFnList<TOut = any, TScope = any> {
      *  contract); `{ tags }` puts declared tags on it. */
     options?: {
         readonly retry?: RetryPolicy;
+        readonly touches?: StageTouches;
         readonly tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): SelectorFnList<TOut, TScope>;
@@ -286,6 +291,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     }): this;
     start(name: string, fn: StageFunction<TOut, TScope> | PausableHandler<TScope>, id: string, description?: string, options?: {
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): this;
     /**
@@ -303,9 +309,12 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     startSelector(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, options?: {
         failFast?: boolean;
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, description?: string): this;
+    /** Compose a keyed outside operation, reconciliation, shared retry decision and wait as ordinary chart nodes. */
+    addRetryLoop<TValue = unknown>(id: string, options: RetryLoopOptions<TScope, TValue>): this;
     addStreamingFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, streamId?: string, description?: string): this;
     /**
      * Add a pausable stage — can pause execution and resume later with input.
@@ -417,6 +426,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      *  `{ tags }` likewise. */
     options?: {
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): DeciderList<TOut, TScope>;
     addSelectorFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, 
@@ -426,6 +436,7 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
     options?: {
         failFast?: boolean;
         retry?: RetryPolicy;
+        touches?: StageTouches;
         tags?: readonly string[];
     }): SelectorFnList<TOut, TScope>;
     addListOfFunction(children: SimplifiedParallelSpec<TOut, TScope>[], options?: {
@@ -489,8 +500,13 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * failed calls that came before the successful one left no mark anywhere —
      * an unexplained behaviour in a library whose whole point is that nothing
      * invisible happens. Declared here, every attempt is part of the record: each
-     * failed attempt fires `FlowRecorder.onStageRetry` and appears in the
-     * narrative, in order, between the attempts' own reads and writes.
+     * attempt fires `FlowRecorder.onAttempt` with its `AttemptRecord` (outcome,
+     * duration, failure category, the retry-or-stop decision), which is what
+     * feeds the narrative — one line per attempt, in order, between the
+     * attempts' own reads and writes. The stage's execution-tree node keeps the
+     * records (`attempts`, `attemptSummary`). A failed attempt that is retried
+     * also fires `FlowRecorder.onStageRetry`, which the narrative does not tell
+     * twice.
      *
      * ## What an attempt is
      *
@@ -518,6 +534,46 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * `retry` option instead.
      */
     retry(policy: RetryPolicy): this;
+    /**
+     * Declare that the stage you JUST added changes an outside system — a charge, an email, a write to another
+     * service (10.1, design §3.3) — and give the rule for its idempotency key.
+     *
+     * ## Why declare it
+     *
+     * A retry is safe for a read. For a charge it is safe only when the outside system can tell a retry from a new
+     * request — by an idempotency key. So the builder refuses a touching stage that may retry (`.retry({ attempts >
+     * 1 })`, in either order) without a key rule: a double charge must be impossible to write by accident. A default
+     * key made by the library was rejected — the run id changes across a resume and a caller's whole-run retry, the
+     * two places a double charge actually happens. The key must name the OPERATION: derive it from the input the rule
+     * is handed, never from model output (`({ getState }) => …` reads it from state). A
+     * keyless touching stage may not `interrupt()`: a resume re-runs it from its top. In a chart that pauses, derive
+     * keys from state (`({ getState }) => …`): the run's input does not cross a resume.
+     *
+     * ## What it changes at run time
+     *
+     * The stage always runs on the attempt runner. The key rule runs ONCE per execution, before attempt 1, and every
+     * attempt gets the key as `scope.$attempt().idempotencyKey` — pass it to the system. Every attempt record says
+     * what it did there (`effect`: `'applied'`, `'none'` when the error itself declares `effect: 'none'`, else
+     * `'unknown'`). When ANY attempt left the effect unknown — it timed out, was cut, or failed without the adapter
+     * saying nothing was sent — the stage fails with `UnknownEffectError`: reconcile with the system by the key, do
+     * not retry blindly. The spec carries the system's name (`touches`).
+     *
+     * @example
+     * ```ts
+     * flowChart<Order>('Load order', loadFn, 'load')
+     *   .addFunction('Charge card', chargeFn, 'charge')
+     *   .touches('stripe', { idempotencyKey: ({ args }) => `order-${(args as { orderId: string }).orderId}` })
+     *   .retry({ attempts: 3, timeoutMs: 20_000 })
+     * ```
+     *
+     * Applies to the CURRENT cursor, like `.retry()`; where the cursor would be ambiguous (a decider, selector,
+     * branch, or fork child), declare it in that method's own `touches` option. Refused: on a subflow mount, a
+     * parallel-for-each stage or a loop reference (no function of their own), after a mount or a fork (the cursor did
+     * not move), twice, with a system that is not a name, and with a key that is not a function.
+     */
+    touches(system: string, options?: {
+        readonly idempotencyKey?: StageTouches['idempotencyKey'];
+    }): this;
     /**
      * Put NAMES on the stage you JUST added. The first commit bundle of each
      * execution of that stage carries them (`CommitBundle.tags` — the bundle
@@ -574,11 +630,40 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * second declaration on the same stage.
      */
     tag(...names: readonly string[]): this;
+    /**
+     * Declare the chart's time budget: the most milliseconds a caller gives one run (design §3.2).
+     *
+     * WHY: the incident behind it — a stage retried an SDK call four times, 40 s each, past a caller's 120 s, and the
+     * record said "one stage, one error". Both numbers were declared: the policy on the stage, the budget of the
+     * caller. So `build()` checks one against the other: it REFUSES the chart when its declared policies already allow
+     * longer (`attempts × timeoutMs` plus the waits, summed along the slowest path — see `timeBudget`), and in dev mode
+     * names every stage it cannot bound (no `timeoutMs`, a function backoff with no `maxBackoffMs`, a loop, a lazy
+     * subflow, a `parallelForEach`). The spec root carries it (`budgetMs`); at run start, a deadline shorter than it is
+     * a dev-mode warning.
+     *
+     * Chart-level, so it may be declared anywhere before `build()`, once.
+     *
+     * @example
+     * ```ts
+     * flowChart<State>('Read', readFn, 'read', { retry: { attempts: 1, timeoutMs: 5_000 } })
+     *   .addFunction('Charge', chargeFn, 'charge')
+     *   .retry({ attempts: 4, timeoutMs: 40_000, backoffMs: 1_000 })
+     *   .budget(120_000)
+     *   .build(); // throws: its declared policies allow 168000 ms, over its budget by 48000 ms
+     * ```
+     */
+    budget(ms: number): this;
     loopTo(stageId: string): this;
     onStream(handler: StreamTokenHandler): this;
     onStreamStart(handler: StreamLifecycleHandler): this;
     onStreamEnd(handler: StreamLifecycleHandler): this;
     build(): RunnableFlowChart<TOut, TScope>;
+    /**
+     * The declared budget, checked (owner ruling Q2): refused when the chart's bounded part alone allows longer — a
+     * time its declared policies allow a run to take, so the budget cannot be promised; every stage it cannot bound is
+     * a dev-mode warning.
+     */
+    private _checkBudget;
     /** Override the scope factory. Rarely needed — auto-embeds TypedScope by default. */
     setScopeFactory(factory: ScopeFactory<TScope>): this;
     toSpec<TResult = SerializedPipelineStructure>(): TResult;

package/dist/types/lib/builder/retryLoop.d.ts

@@ -0,0 +1,56 @@
+import type { RetryLoopBudget } from '../attempt/retryLoopContext.js';
+import type { RetryLoopCall } from '../attempt/retryLoopTypes.js';
+import type { AttemptContext, AttemptEffect, AttemptError, AttemptRecord, IdempotencyKeyContext, RetryPolicy } from '../attempt/types.js';
+import type { DecisionEvidence } from '../decide/types.js';
+export interface RetryLoopContext extends AttemptContext {
+    readonly retryLoop: RetryLoopCall;
+}
+export interface RetryLoopOptions<TScope = any, TValue = unknown> {
+    readonly touches: string;
+    readonly idempotencyKey: (context: IdempotencyKeyContext) => string;
+    readonly retry: RetryPolicy;
+    readonly attempt: (scope: TScope, context: RetryLoopContext) => TValue | Promise<TValue>;
+    /** 'none' must authoritatively establish that the operation was not applied; an empty search is not enough. */
+    readonly reconcile: (scope: TScope, context: RetryLoopContext) => AttemptEffect | Promise<AttemptEffect>;
+    readonly into?: string;
+    readonly onStop?: 'throw' | 'continue';
+    readonly wait?: 'sleep' | 'pause';
+}
+/** Operational state stays real; normal state retention scrubs selected keys and every error is already served. */
+export interface RetryLoopState<TValue = unknown> {
+    readonly id: string;
+    readonly series: string;
+    readonly attempt: number;
+    readonly of: number;
+    readonly idempotencyKey: string;
+    readonly effect: AttemptEffect;
+    readonly reconciled: boolean;
+    readonly outcome?: AttemptRecord['outcome'];
+    readonly category?: AttemptRecord['category'];
+    readonly error?: AttemptError;
+    readonly value?: TValue;
+    readonly delayMs: number;
+    readonly retryOn: boolean;
+    readonly retryOnThrew?: true;
+    readonly decision?: DecisionEvidence;
+    readonly terminal: boolean;
+    readonly resumeAt?: number;
+}
+/** Builder-only composition interface; no runtime engine kind or new scope method. */
+interface Builder {
+    addFunction(name: string, fn: (scope: any) => any, id: string): this;
+    addPausableFunction(name: string, handler: {
+        execute(scope: any): any;
+        resume(scope: any, input: unknown): any;
+    }, id: string): this;
+    addDeciderFunction(name: string, fn: (scope: any) => any, id: string): {
+        addFunctionBranch(branch: string, name: string, fn: (scope: any) => any, id?: string, options?: any): any;
+        end(): Builder;
+    };
+    touches(system: string, options: {
+        idempotencyKey: (context: IdempotencyKeyContext) => string;
+    }): this;
+    tag(...names: string[]): this;
+}
+export declare function appendRetryLoop<TScope>(builder: Builder, id: string, supplied: RetryLoopOptions<TScope>, stamp: (budget: RetryLoopBudget, branch?: string) => void): void;
+export {};

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

@@ -9,7 +9,7 @@
  * The builder remains standalone at runtime.
  */
 import type { StageNode } from '../engine/graph/StageNode.js';
-import type { ILogger, RetryPolicy, ScopeFactory, StageFunction } from '../engine/types.js';
+import type { ILogger, RetryPolicy, ScopeFactory, StageFunction, StageTouches } from '../engine/types.js';
 import type { ScopeProtectionMode } from '../scope/protection/types.js';
 import type { StructureRecorder } from './structure/StructureRecorder.js';
 export type { ResumeFn, StageNode } from '../engine/graph/StageNode.js';
@@ -71,6 +71,26 @@ export interface SerializedPipelineStructure {
      * be `undefined` at fire time for exactly the stages that have a policy.
      */
     retryAttempts?: number;
+    /**
+     * The cap on ONE attempt of this stage, from its declared {@link RetryPolicy}
+     * (`timeoutMs`). Present only when declared. With `retryAttempts` it is what
+     * bounds the stage in time: at most `retryAttempts × timeoutMs` plus the
+     * waits between attempts (`timeBudget`). Same read-it-from-the-built-spec
+     * caveat as `retryAttempts`.
+     */
+    timeoutMs?: number;
+    /**
+     * The chart's declared time budget (`.budget(ms)`), on the ROOT spec only —
+     * the most milliseconds a caller gives one run. `build()` refused the chart
+     * if its declared policies could already take longer. Absent when undeclared.
+     */
+    budgetMs?: number;
+    /**
+     * The outside system this stage changes (`.touches(system, …)`, 10.1) — the
+     * NAME only; the key rule is a function and stays on the node. Present only
+     * when declared. Same read-it-from-the-built-spec caveat as `retryAttempts`.
+     */
+    touches?: string;
     /**
      * Declared tags (9.21.0) — the NAMES the author put on this stage at build
      * time, copied as-is (JSON-safe, free strings; footprintjs owns no
@@ -118,6 +138,12 @@ export interface FlowChartSpec {
     /** Total attempts allowed by this stage's declared retry policy — the count
      *  only (see `SerializedPipelineStructure.retryAttempts`). */
     retryAttempts?: number;
+    /** The cap on one attempt (see `SerializedPipelineStructure.timeoutMs`). */
+    timeoutMs?: number;
+    /** The chart's declared time budget, on the root only (see `SerializedPipelineStructure.budgetMs`). */
+    budgetMs?: number;
+    /** The outside system this stage changes, by name (see `SerializedPipelineStructure.touches`). */
+    touches?: string;
     /** Declared tags on this stage, as-is (see `SerializedPipelineStructure.tags`). */
     tags?: readonly string[];
 }
@@ -154,6 +180,12 @@ export interface FlowChartOptions {
      * at their own declaration site. See {@link RetryPolicy}.
      */
     retry?: RetryPolicy;
+    /**
+     * The outside system the chart's FIRST stage changes, and its idempotency-key
+     * rule (10.1). Later stages use the `.touches()` modifier, or the `touches`
+     * option at their own declaration site. See {@link StageTouches}.
+     */
+    touches?: StageTouches;
     /**
      * Declared tags for the chart's FIRST stage. Later stages use the `.tag()`
      * modifier, or the `tags` option at their own declaration site. A tag is a
@@ -190,6 +222,8 @@ export type SimplifiedParallelSpec<TOut = any, TScope = any> = {
     /** Declarative retry policy for this fork child. Fork branches are where
      *  flaky I/O usually lives, so each child declares its own. */
     retry?: RetryPolicy;
+    /** The outside system this fork child changes, and its key rule (10.1). */
+    touches?: StageTouches;
     /** Declared tags for this fork child — each child's bundle carries its own. */
     tags?: readonly string[];
 };

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

@@ -8,5 +8,5 @@
 export type { DecideRule, DecisionEvidence, DecisionResult, DefaultBranch, FilterCondition, FilterOps, FilterRuleEvidence, FunctionRuleEvidence, ReadInput, RuleEvidence, SelectionEvidence, SelectionResult, WhenClause, WhereFilter, } from './types.js';
 export { DECISION_RESULT } from './types.js';
 export { decide, select } from './decide.js';
-export { evaluateFilter } from './evaluator.js';
+export { evaluateFilter } from '../filter/evaluator.js';
 export { EvidenceCollector } from './evidence.js';

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

@@ -1,3 +1,4 @@
+import type { RetryLoopDecision } from '../attempt/retryLoopTypes.js';
 /**
  * decide/types -- Type definitions for the decide()/select() decision reasoning system.
  *
@@ -126,6 +127,8 @@ export interface FilterCondition {
     redacted: boolean;
 }
 export interface DecisionEvidence {
+    /** Explicit logical-loop link recorded by addRetryLoop; no key, raw error or provider payload. */
+    retryLoop?: RetryLoopDecision;
     rules: RuleEvidence[];
     /** The branch selected. Equals `default` when no rule matched. */
     chosen: string;

package/dist/types/lib/engine/graph/StageNode.d.ts

@@ -8,7 +8,7 @@
  * - Back-edges via dynamic next (loop)
  * - Isolated sub-traversals via `isSubflowRoot` (subflow)
  */
-import type { ParallelForEachConfig, RetryPolicy, StageFunction, SubflowMountOptions } from '../types.js';
+import type { ParallelForEachConfig, RetryPolicy, StageFunction, StageTouches, SubflowMountOptions } from '../types.js';
 /**
  * Resume function for pausable stages.
  * Unlike StageFunction, the 2nd argument is the resume input (not breakFn).
@@ -84,6 +84,16 @@ export type StageNode<TOut = any, TScope = any> = {
      * See {@link RetryPolicy}.
      */
     retry?: RetryPolicy;
+    /**
+     * The outside system this stage changes, and the rule for its idempotency key (10.1, design §3.3). A POLICY-like
+     * field, the `retry` / `tags` precedent: no node kind, no `computeNodeType` edit, and the prefixer's
+     * `{ ...node }` spread carries it through subflow prefixing. Lands only through
+     * `FlowChartBuilder · applyTouches`; a touching stage that may retry without a key rule is refused there, at the
+     * run-time door for a returned node, and at the stage. Honoured by `FlowchartTraverser · executeStage`: the key
+     * is computed once per execution, every attempt records its `effect`, and a series that ends without an answer after any attempt of unknown effect fails
+     * the stage with `UnknownEffectError`. See {@link StageTouches}.
+     */
+    touches?: StageTouches;
     /**
      * Declared tags (9.21.0) — the NAMES the author put on this stage at build
      * time. A POLICY-like field, not a kind: no `computeNodeType` edit, no

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

@@ -7,11 +7,18 @@
  * - Handle streaming stages (onStart, onToken, onEnd lifecycle)
  * - Sync+async safety: only await real Promises (instanceof check)
  */
+import type { AttemptContext } from '../../attempt/types.js';
 import type { StageContext } from '../../memory/StageContext.js';
 import type { StageNode } from '../graph/StageNode.js';
 import type { HandlerDeps, StageFunction } from '../types.js';
 export declare class StageRunner<TOut = any, TScope = any> {
     private readonly deps;
     constructor(deps: HandlerDeps<TOut, TScope>);
-    run(node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFn: () => void): Promise<TOut>;
+    /**
+     * Run one stage function. `attempt` is the attempt runner's (P1b) — present when the stage runs under a retry
+     * policy, a `timeoutMs` or a run deadline: the scope hands it out (`$attempt()`) and is fenced to it, and the
+     * race below is against ITS signal (the run's, composed with the attempt's cap). Without one, the race is
+     * against the run's signal, as it always was.
+     */
+    run(node: StageNode<TOut, TScope>, stageFunc: StageFunction<TOut, TScope>, context: StageContext, breakFn: () => void, attempt?: AttemptContext): Promise<TOut>;
 }

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,7 +14,16 @@ 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. */
 export declare function loggableStageError(context: StageContext, error: unknown): unknown;
+/**
+ * A touching stage's idempotency key as records carry it (P3, design §6) — `RedactionRule · retainIdempotencyKey`:
+ * selected by its name, and served whole when the input its rule was handed holds a selected key or the rule read
+ * a selected state value. The stage itself
+ * keeps the real key.
+ */
+export declare function servedIdempotencyKey(context: StageContext, key: string, input: unknown, readSelected?: boolean): string;

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

@@ -14,11 +14,11 @@ export { NullControlFlowNarrativeGenerator } from './narrative/NullControlFlowNa
 export type { IControlFlowNarrative } from './narrative/types.js';
 export { FlowRecorderDispatcher } from './narrative/FlowRecorderDispatcher.js';
 export { NarrativeFlowRecorder } from './narrative/NarrativeFlowRecorder.js';
-export type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowStageRetryEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, FlowThrottledEvent, ResumeLink, TraversalContext, } from './narrative/types.js';
+export type { FlowAttemptEvent, FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowStageRetryEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, FlowThrottledEvent, ResumeLink, TraversalContext, } from './narrative/types.js';
 export type { StructuredErrorInfo } from '../errors/errorInfo.js';
 export { extractErrorInfo, formatErrorInfo } from '../errors/errorInfo.js';
 export { AdaptiveNarrativeFlowRecorder } from './narrative/recorders/AdaptiveNarrativeFlowRecorder.js';
-export type { ManifestEntry } from './narrative/recorders/ManifestFlowRecorder.js';
+export type { ManifestAttemptRow, ManifestEntry } from './narrative/recorders/ManifestFlowRecorder.js';
 export { ManifestFlowRecorder } from './narrative/recorders/ManifestFlowRecorder.js';
 export { MilestoneNarrativeFlowRecorder } from './narrative/recorders/MilestoneNarrativeFlowRecorder.js';
 export { ProgressiveNarrativeFlowRecorder } from './narrative/recorders/ProgressiveNarrativeFlowRecorder.js';

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

@@ -18,7 +18,7 @@ import type { CombinedRecorder } from '../../recorder/CombinedRecorder.js';
 import type { EmitEvent } from '../../recorder/EmitRecorder.js';
 import type { ErrorEvent, PauseEvent, ReadEvent, ResumeEvent, WriteEvent } from '../../scope/types.js';
 import type { CombinedNarrativeEntry, NarrativeFormatter } from './narrativeTypes.js';
-import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowPauseEvent, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowStageRetryEvent, FlowSubflowEvent } from './types.js';
+import type { FlowAttemptEvent, FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowPauseEvent, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
 export interface CombinedNarrativeRecorderOptions {
     includeStepNumbers?: boolean;
     includeValues?: boolean;
@@ -82,21 +82,36 @@ export declare class CombinedNarrativeRecorder implements CombinedRecorder {
     onLoop(event: FlowLoopEvent): void;
     onBreak(event: FlowBreakEvent): void;
     /**
-     * A failed attempt that was retried. BUFFERED, not pushed: this is the only
-     * flow event that fires DURING a stage, so pushing it straight to the store
-     * would place the line before its own stage header. Buffered alongside the
-     * reads and writes, it flushes in true execution order:
+     * One attempt of a retried stage (10.1). BUFFERED, not pushed: attempt
+     * events fire DURING a stage, so pushing one straight to the store would
+     * place the line before its own stage header. Buffered alongside the reads
+     * and writes, it flushes in true execution order:
      *
-     *     Step 3: Fetch user
-     *       ↳ read userId = "u1"
-     *       ↳ [Retry]: attempt 1 of 3 failed … retrying
-     *       ↳ read userId = "u1"
-     *       ↳ wrote user = { … }
+     *     Stage 3: Fetch user
+     *       Step 1: Read userId = "u1"
+     *       Attempt 1 of 3 at Fetch user failed in 12ms (…), retrying in 100ms.
+     *       Step 3: Read userId = "u1"
+     *       Step 4: Write user = { … }
+     *       Attempt 2 of 3 at Fetch user succeeded in 9ms.
+     *
+     * This line replaces the 9.15 `[Retry]` line: it already says "retrying",
+     * so `onStageRetry` is not narrated (two lines for one fact).
      */
-    onStageRetry(event: FlowStageRetryEvent): void;
+    onAttempt(event: FlowAttemptEvent): void;
     onPause(event: PauseEvent | FlowPauseEvent): void;
     onResume(event: ResumeEvent | FlowResumeEvent): void;
     onError(event: ErrorEvent | FlowErrorEvent): void;
+    /**
+     * A failed stage has no header (its `[Error]` line stands for it) and its
+     * buffered reads and writes are not narrated — the narrative's law since
+     * before retry existed, kept. Its ATTEMPT lines are the exception (10.1):
+     * the stop reason is the point, so they follow the error line, in order,
+     * as its depth-1 sub-items. A stage with no retry policy buffers no attempt
+     * lines, so its failure narrates exactly as before.
+     */
+    private flushAttempts;
+    /** One attempt line — the consumer's `renderAttempt` first; `null` drops it, `undefined` falls back. */
+    private pushAttempt;
     /**
      * Receive a consumer-emitted event from `scope.$emit(name, payload)`.
      *
@@ -158,7 +173,7 @@ export declare class CombinedNarrativeRecorder implements CombinedRecorder {
         description: string;
         preferredOperation: "translate";
         data: {
-            type: "subflow" | "loop" | "error" | "pause" | "emit" | "fork" | "selector" | "stage" | "step" | "condition" | "break" | "resume" | "retry";
+            type: "attempt" | "retry" | "error" | "stage" | "emit" | "subflow" | "loop" | "pause" | "fork" | "selector" | "step" | "condition" | "break" | "resume";
             text: string;
             depth: number;
             stageName?: string | undefined;
@@ -186,6 +201,5 @@ export declare class CombinedNarrativeRecorder implements CombinedRecorder {
     private defaultRenderSubflow;
     private defaultRenderLoop;
     private defaultRenderBreak;
-    private defaultRenderRetry;
     private defaultRenderError;
 }

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

@@ -10,8 +10,10 @@
  *
  * When no recorders are attached, every method is a fast no-op (empty array check).
  */
+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;
@@ -34,13 +36,14 @@ export declare class FlowRecorderDispatcher implements IControlFlowNarrative {
     onLoop(targetStage: string, iteration: number, description?: string, traversalContext?: TraversalContext): void;
     onBreak(stageName: string, traversalContext?: TraversalContext, reason?: string, propagatedFromSubflow?: string): void;
     onError(stageName: string, errorMessage: string, structuredError: StructuredErrorInfo, traversalContext?: TraversalContext): void;
+    onAttempt(stageName: string, stageId: string, record: AttemptRecord, structuredError: StructuredErrorInfo | undefined, traversalContext?: TraversalContext): void;
     onStageRetry(stageName: string, stageId: string, attempt: number, maxAttempts: number, delayMs: number, structuredError: StructuredErrorInfo, traversalContext?: TraversalContext): void;
     onThrottled(stageName: string, stageId: string, structuredError: StructuredErrorInfo, traversalContext?: TraversalContext): void;
     onPause(stageName: string, stageId: string, pauseData: unknown, subflowPath: readonly string[], traversalContext?: TraversalContext): void;
     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/NarrativeFlowRecorder.d.ts

@@ -8,7 +8,7 @@
  * Consumers who want different narrative behavior (windowed loops, adaptive
  * summarization, etc.) can replace this with a different FlowRecorder.
  */
-import type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowPauseEvent, FlowRecorder, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowStageRetryEvent, FlowSubflowEvent } from './types.js';
+import type { FlowAttemptEvent, FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowPauseEvent, FlowRecorder, FlowResumeEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent } from './types.js';
 export declare class NarrativeFlowRecorder implements FlowRecorder {
     readonly id: string;
     private sentences;
@@ -20,6 +20,14 @@ export declare class NarrativeFlowRecorder implements FlowRecorder {
      * `onStageExecuted` for that stage stays silent — an arrival is told ONCE.
      */
     private announcedArrival;
+    /**
+     * A retried stage's attempt sentences, by `runtimeStageId`, held until the stage's own outcome is known. A
+     * stage that FAILED tells its attempts beneath its error sentence — where the combined narrative puts them
+     * (`CombinedNarrativeRecorder · flushAttempts`), so the two built-in narratives tell a failure in one order,
+     * the stop reason last. A stage that completed (or paused) tells them where they always stood: before the
+     * sentence its completion adds.
+     */
+    private readonly heldAttempts;
     constructor(id?: string);
     onStageExecuted(event: FlowStageEvent): void;
     onNext(_event: FlowNextEvent): void;
@@ -31,11 +39,22 @@ export declare class NarrativeFlowRecorder implements FlowRecorder {
     onLoop(event: FlowLoopEvent): void;
     onBreak(event: FlowBreakEvent): void;
     onError(event: FlowErrorEvent): void;
-    onStageRetry(event: FlowStageRetryEvent): void;
+    /**
+     * One sentence per attempt of a retried stage (10.1) — its outcome, duration, cause and decision. It replaces
+     * the 9.15 retry sentence (`onStageRetry` is no longer narrated here): the attempt line already says
+     * "retrying", and says it for the attempt that stopped the series too. Held until the stage's outcome is
+     * known ({@link heldAttempts}); an event with no `runtimeStageId` has nothing to hold it by, so it is told now.
+     */
+    onAttempt(event: FlowAttemptEvent): void;
     onPause(event: FlowPauseEvent): void;
     onResume(event: FlowResumeEvent): void;
-    /** Returns a defensive copy of accumulated sentences. */
+    /**
+     * Returns a defensive copy of accumulated sentences. Attempt sentences still held — read mid-stage, before the
+     * stage's outcome — come last, so nothing the run did is ever missing from the copy.
+     */
     getSentences(): string[];
     /** Clears accumulated sentences. Useful for reuse across runs. */
     clear(): void;
+    /** Tell the held attempt sentences of `runtimeStageId`, in order, and stop holding them. */
+    private releaseAttempts;
 }

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

@@ -18,6 +18,7 @@ export declare class NullControlFlowNarrativeGenerator implements IControlFlowNa
     onLoop(): void;
     onBreak(): void;
     onError(): void;
+    onAttempt(): void;
     onStageRetry(): void;
     onPause(): void;
     onResume(): void;

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

@@ -1,4 +1,5 @@
 /** Shared English sentence bodies, with no event capture or recorder state. */
+import type { AttemptRecord } from '../../../attempt/types.js';
 import type { ValidationIssue } from '../../../schema/errors.js';
 import type { BreakRenderContext, DecisionRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, StageRenderContext } from '../narrativeTypes.js';
 import type { FlowResumeEvent } from '../types.js';
@@ -14,3 +15,25 @@ export declare function validationDetails(issues: readonly ValidationIssue[]): s
 export declare function errorSentence(ctx: Pick<ErrorRenderContext, 'stageName' | 'message'>): string;
 /** Callers retain their distinct rules for whether to display empty details. */
 export declare function validationSentence(details: string): string;
+/**
+ * Whether the narrative tells an attempt (P1b). A STAGE series of ONE attempt — a stage run on the attempt runner
+ * only because of a `timeoutMs` or the run's deadline — that succeeded or paused says nothing the stage's own line
+ * does not, so it is not told (its record is still on the tree and the hook). Every other attempt is — every call
+ * and every observed attempt too (P2): the stage's own line never mentions them.
+ */
+export declare function isAttemptTold(record: AttemptRecord): boolean;
+/**
+ * One attempt of a retried stage, as one sentence (10.1): its outcome and duration, the cause of a failure
+ * (`category: message`, the category left out when it is `unknown`), and the decision — the wait before a retry,
+ * or why the series stopped. The error is the record's SERVED message, so a redacted error reads redacted here.
+ * Under a run deadline the decision also says the time left (P1b).
+ *
+ *   Attempt 1 of 3 at Fetch rate failed in 812ms (rate-limited: 429), retrying in 4s.
+ *   Attempt 3 of 3 at Fetch rate succeeded in 31ms.
+ *   Attempt 1 of 4 at Charge card failed in 120ms (permanent: card declined); stopped: retryOn declined.
+ *   Attempt 2 of 3 at Fetch rate timed out after 40s, retrying in 2s (70s left).
+ *   Attempt 2 of 4 at Charge card timed out after 20s; stopped: no time left (300ms left, next wait 2s).
+ */
+export declare function attemptSentence(stageName: string, record: AttemptRecord): string;
+/** A duration as the narrative says it: whole milliseconds under a second, seconds (one decimal at most) above. */
+export declare function formatDuration(ms: number): string;

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

@@ -1,11 +1,11 @@
 export type { CombinedNarrativeRecorderOptions } from './CombinedNarrativeRecorder.js';
 export { CombinedNarrativeRecorder } from './CombinedNarrativeRecorder.js';
-export type { BreakRenderContext, CombinedNarrativeEntry, CombinedNarrativeOptions, DecisionRenderContext, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, } from './narrativeTypes.js';
+export type { AttemptRenderContext, BreakRenderContext, CombinedNarrativeEntry, CombinedNarrativeOptions, DecisionRenderContext, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, } from './narrativeTypes.js';
 export { NullControlFlowNarrativeGenerator } from './NullControlFlowNarrativeGenerator.js';
 export type { IControlFlowNarrative } from './types.js';
 export { FlowRecorderDispatcher } from './FlowRecorderDispatcher.js';
 export { NarrativeFlowRecorder } from './NarrativeFlowRecorder.js';
-export type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, } from './types.js';
+export type { FlowAttemptEvent, FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowSubflowEvent, } from './types.js';
 export { AdaptiveNarrativeFlowRecorder } from './recorders/AdaptiveNarrativeFlowRecorder.js';
 export { MilestoneNarrativeFlowRecorder } from './recorders/MilestoneNarrativeFlowRecorder.js';
 export { ProgressiveNarrativeFlowRecorder } from './recorders/ProgressiveNarrativeFlowRecorder.js';