footprintjs 10.0.1 → 10.2.0

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

@@ -5,12 +5,19 @@
  * The CombinedNarrativeBuilder class was removed in v1.0.
  * Use CombinedNarrativeRecorder (auto-attached by setEnableNarrative()) instead.
  */
+import type { AttemptRecord } from '../../attempt/types.js';
 export interface CombinedNarrativeEntry {
     type: 'stage' | 'step' | 'condition' | 'fork' | 'selector' | 'subflow' | 'loop' | 'break' | 'error' | 'pause' | 'resume' | 'emit'
-    /** A failed attempt at a stage with a declared retry policy, which was
-     *  retried. Rendered as a depth-1 sub-item of its stage, IN ORDER between
-     *  the attempts' reads and writes. */
-     | 'retry';
+    /** A failed attempt that was retried — rendered by 9.15–10.0 only. Since
+     *  10.1 the built-in narrative renders one `'attempt'` line per attempt
+     *  instead; the member stays so a narrative stored by an earlier release
+     *  still type-checks. */
+     | 'retry'
+    /** One attempt of a stage with a declared retry policy (10.1): its outcome,
+     *  duration, cause and decision. A depth-1 sub-item of its stage, IN ORDER
+     *  between the attempts' reads and writes; for a stage that failed, the
+     *  lines follow its `'error'` entry. */
+     | 'attempt';
     text: string;
     depth: number;
     stageName?: string;
@@ -108,21 +115,14 @@ export interface ErrorRenderContext {
     validationIssues?: string;
 }
 /**
- * Context passed to `NarrativeFormatter.renderRetry` — one failed attempt at a
- * stage with a declared retry policy, which the engine then retried. Fires only
- * for attempts followed by another attempt; the final failure goes to
- * `renderError`.
+ * Context passed to `NarrativeFormatter.renderAttempt` — one attempt of a stage
+ * with a declared retry policy (10.1), whatever its outcome.
  */
-export interface RetryRenderContext {
+export interface AttemptRenderContext {
+    /** The stage the attempt ran. */
     stageName: string;
-    /** Which attempt just failed, 1-based. */
-    attempt: number;
-    /** Total attempts the policy allows, including the first. */
-    maxAttempts: number;
-    /** Milliseconds waited before the next attempt. `0` = immediate. */
-    delayMs: number;
-    /** The failed attempt's error message. */
-    message: string;
+    /** The attempt: outcome, duration, category, the served error, and the retry-or-stop decision. */
+    record: AttemptRecord;
 }
 /**
  * Context passed to `NarrativeFormatter.renderEmit` — fires for every
@@ -193,11 +193,17 @@ export interface NarrativeFormatter {
     renderBreak?(ctx: BreakRenderContext): string;
     renderError?(ctx: ErrorRenderContext): string;
     /**
-     * Format a retried attempt into a narrative line. Rendered as a depth-1
-     * sub-item of its stage, positioned between the attempts' reads and writes
-     * so the narrative reads in the order things actually happened.
+     * Format one attempt of a retried stage (10.1) into a narrative line — a
+     * depth-1 sub-item of its stage, between the attempts' reads and writes (for
+     * a stage that failed for good, beneath its error line). It replaces the
+     * 9.15–10.0 `renderRetry`, which is removed: this line says "retrying" too.
+     *
+     *   - `string`    → use as the narrative line
+     *   - `null`      → deliberately exclude this entry
+     *   - `undefined` → fall back to the library's default sentence
+     *                   (`Attempt 2 of 3 at Fetch failed in 12ms (…), retrying in 1s.`)
      */
-    renderRetry?(ctx: RetryRenderContext): string;
+    renderAttempt?(ctx: AttemptRenderContext): string | null | undefined;
     /**
      * Format a consumer-emitted event (from `scope.$emit(name, payload)`)
      * into a narrative line.

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

@@ -9,6 +9,14 @@
  * The manifest reflects only subflows that were actually entered during
  * execution — unvisited branches are not included.
  *
+ * Attempts (10.1): a stage whose retry series retried, gave up or timed out gets a row —
+ * `{ stageId, stageName, runtimeStageId, attempts: AttemptSummary }` — on the
+ * entry of the subflow it ran in (`ManifestEntry.attempts`). The manifest has
+ * no entry for the top-level chart, so a top-level stage's row (or one whose
+ * subflow entry this recorder never saw) is served by `getRootAttempts()` and
+ * rides the snapshot bundle's `meta.rootAttempts` (absent when empty — the
+ * bundle's `data` keeps its shape).
+ *
  * @example
  * ```typescript
  * const manifest = new ManifestFlowRecorder();
@@ -22,7 +30,18 @@
  * const spec = manifest.getSpec('sf-credit-check');
  * ```
  */
-import type { FlowRecorder, FlowSubflowEvent, FlowSubflowRegisteredEvent } from '../types.js';
+import type { AttemptSummary } from '../../../attempt/types.js';
+import type { FlowAttemptEvent, FlowRecorder, FlowSubflowEvent, FlowSubflowRegisteredEvent } from '../types.js';
+/** One stage execution whose retry series retried, gave up or timed out, at a glance. */
+export interface ManifestAttemptRow {
+    /** Stable stage id (path-prefixed inside a subflow). */
+    stageId: string;
+    stageName: string;
+    /** The execution — the series' `runtimeStageId`. */
+    runtimeStageId: string;
+    /** The series at a glance — equal to the stage's `StageSnapshot.attemptSummary`. */
+    attempts: AttemptSummary;
+}
 /** A single entry in the subflow manifest tree. */
 export interface ManifestEntry {
     /** Subflow identifier — use for on-demand spec lookup. */
@@ -33,6 +52,8 @@ export interface ManifestEntry {
     description?: string;
     /** Nested subflows entered within this subflow. */
     children: ManifestEntry[];
+    /** Stages run directly in this subflow whose series retried, gave up or timed out — absent when none did. */
+    attempts?: ManifestAttemptRow[];
 }
 export declare class ManifestFlowRecorder implements FlowRecorder {
     readonly id: string;
@@ -42,12 +63,31 @@ export declare class ManifestFlowRecorder implements FlowRecorder {
     private roots;
     /** Full specs stored from dynamic registration events. */
     private specs;
+    /**
+     * Open entries by subflowId — where a stage's row lands. Not the stack: parallel subflow siblings exit out of
+     * stack order, so the entry a row belongs to may no longer be on it.
+     */
+    private openEntries;
+    /** Rows of top-level stages — the manifest has no entry for the top-level chart. */
+    private rootAttempts;
+    /** Per-series tallies of the series that retried, gave up or timed out. */
+    private readonly attemptBook;
     constructor(id?: string);
     onSubflowEntry(event: FlowSubflowEvent): void;
-    onSubflowExit(_event: FlowSubflowEvent): void;
+    onSubflowExit(event: FlowSubflowEvent): void;
+    /**
+     * A series' row lands once, when it ends, on the open entry of the subflow the stage ran in; a top-level
+     * stage's (or one whose entry this recorder never saw) on the root rows.
+     */
+    onAttempt(event: FlowAttemptEvent): void;
     onSubflowRegistered(event: FlowSubflowRegisteredEvent): void;
     /** Returns the manifest tree — lightweight, suitable for snapshot inclusion. */
     getManifest(): ManifestEntry[];
+    /**
+     * Rows of top-level stages whose series retried, gave up or timed out, in the order the series ended — plus any row of a
+     * subflow stage whose entry this recorder never saw (its path-prefixed `stageId` says where it ran).
+     */
+    getRootAttempts(): ManifestAttemptRow[];
     /**
      * Returns the full spec for a dynamically-registered subflow.
      * Only populated for subflows auto-registered at runtime (via StageNode
@@ -59,6 +99,9 @@ export declare class ManifestFlowRecorder implements FlowRecorder {
     /** Returns all stored spec IDs. */
     getSpecIds(): string[];
     toSnapshot(): {
+        meta?: {
+            rootAttempts: ManifestAttemptRow[];
+        } | undefined;
         name: string;
         description: string;
         preferredOperation: "translate";

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

@@ -1,5 +1,5 @@
 export { AdaptiveNarrativeFlowRecorder } from './AdaptiveNarrativeFlowRecorder.js';
-export type { ManifestEntry } from './ManifestFlowRecorder.js';
+export type { ManifestAttemptRow, ManifestEntry } from './ManifestFlowRecorder.js';
 export { ManifestFlowRecorder } from './ManifestFlowRecorder.js';
 export { MilestoneNarrativeFlowRecorder } from './MilestoneNarrativeFlowRecorder.js';
 export { ProgressiveNarrativeFlowRecorder } from './ProgressiveNarrativeFlowRecorder.js';

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

@@ -6,8 +6,10 @@
  *
  * @module
  */
+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
@@ -63,11 +65,28 @@ export interface IControlFlowNarrative {
      * `RedactionRule.retainStageError` (the diagnostic policy applied once), elsewhere `extractErrorInfo`.
      */
     onError(stageName: string, errorMessage: string, structuredError: StructuredErrorInfo, traversalContext?: TraversalContext): void;
+    /**
+     * Called at the END of every attempt (10.1) — every outcome, with the
+     * attempt's {@link AttemptRecord} (timing, outcome, category, the
+     * retry-or-stop decision): a stage's own (`record.kind === 'stage'`, under a
+     * retry policy, a `timeoutMs` or a run deadline), and the calls it makes
+     * (`'call'`, `scope.$call`) and outside attempts it reports (`'observed'`)
+     * during the stage (P2). A stage attempt fires before `onStageRetry` when it
+     * is retried, and before `onError` / `onStageExecuted` for the last.
+     * `structuredError` is the attempt's served error (`raw` included unless the
+     * policy masked it; never for an observed attempt); absent for a success or
+     * a pause.
+     *
+     * Event arithmetic: one per attempt — for a stage, the number of attempts it
+     * made plus one per call or observed attempt (filter on `record.kind`).
+     */
+    onAttempt(stageName: string, stageId: string, record: AttemptRecord, structuredError: StructuredErrorInfo | undefined, traversalContext?: TraversalContext): void;
     /**
      * Called when an attempt at a stage with a declared `retry` policy failed
-     * AND another attempt will run. Fires after the failed attempt's staged
-     * writes are discarded and BEFORE the backoff wait, so a live monitor learns
-     * "retrying in 500 ms" when the decision is made, not after the wait.
+     * AND another attempt will run. Fires after that attempt's `onAttempt`,
+     * after its staged writes are discarded and BEFORE the backoff wait, so a
+     * live monitor learns "retrying in 500 ms" when the decision is made, not
+     * after the wait.
      *
      * Event arithmetic: an exhausted policy fires `attempts - 1` of these and
      * then one `onError`; a `retryOn` that declines fires ZERO of these and one
@@ -113,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[];
 }
@@ -193,6 +212,12 @@ export interface TraversalContext {
      * checkpoint predates 9.37.0 (it did not record the paused execution).
      */
     readonly resumedFrom?: ResumeLink;
+    /**
+     * The run's correlation (10.1) — `env.traceparent`, or `env.traceId` + `env.operationId`, resolved once per
+     * leg. The SAME frozen object, by reference, on every stamp of the leg (subflows included) and on
+     * `getSnapshot().correlation`. Absent — no key — when the env gives none.
+     */
+    readonly correlation?: RunCorrelation;
 }
 /**
  * The paused execution a resume continues — `TraversalContext.resumedFrom`.
@@ -339,6 +364,39 @@ export interface FlowThrottledEvent {
     /** Explicit channel discriminant — see {@link FlowErrorEvent.channel}. */
     channel?: 'flow';
 }
+/**
+ * Event passed to FlowRecorder.onAttempt — one attempt, at its end (10.1): a
+ * stage's own under its retry policy, a `timeoutMs` or a run deadline
+ * (`record.kind === 'stage'`), or — during the stage — a call it made
+ * (`'call'`, `scope.$call`) or an outside attempt it reported (`'observed'`,
+ * P2). `stageName` / `stageId` / `traversalContext` are the stage's in every
+ * case; filter on `record.kind` to count one kind.
+ *
+ * WHY this event exists: `onStageRetry` says "attempt N failed, retrying" and
+ * nothing else — not how long a try took, not why the series stopped, and
+ * nothing at all when `retryOn` declined. Every attempt is an
+ * {@link AttemptRecord} instead, whatever its outcome, with the decision that
+ * followed it in the shape `decide()` records — the same records the stage's
+ * execution-tree node keeps (`StageSnapshot.attempts`).
+ *
+ * Fires once per attempt, before `onStageRetry` (when the attempt is retried)
+ * and before `onError` / `onStageExecuted` (for the last). The record is
+ * frozen and survives `structuredClone`; `structuredError` is the served error
+ * with `raw`, as on {@link FlowStageRetryEvent} — except for an observed
+ * attempt, whose error the library never threw (`raw` is undefined).
+ */
+export interface FlowAttemptEvent {
+    stageName: string;
+    /** Stable stage identifier from the builder (matches spec node id). */
+    stageId: string;
+    /** The attempt: timing, outcome, category, decision, and the served error without `raw`. */
+    record: AttemptRecord;
+    /** The attempt's served error with `raw` — absent for a success or a pause. */
+    structuredError?: StructuredErrorInfo;
+    traversalContext?: TraversalContext;
+    /** Explicit channel discriminant — see {@link FlowErrorEvent.channel}. */
+    channel?: 'flow';
+}
 /**
  * Event passed to FlowRecorder.onStageRetry — one failed attempt at a stage
  * that carries a declared {@link import('../types.js').RetryPolicy}, and which
@@ -352,7 +410,9 @@ export interface FlowThrottledEvent {
  * Fires only for attempts followed by another attempt. The final failure takes
  * the ordinary error path (`onError`), so the two never double-report the same
  * failure: an exhausted `attempts: 3` policy emits 2 retry events + 1 error
- * event; a `retryOn` that declines emits 0 retry events + 1 error event.
+ * event; a `retryOn` that declines emits 0 retry events + 1 error event. Each
+ * attempt — retried or not — also fires {@link FlowAttemptEvent} first (10.1),
+ * which is where a declined stop is recorded (`reason: 'declined'`).
  */
 export interface FlowStageRetryEvent {
     stageName: string;
@@ -428,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.
@@ -461,6 +523,13 @@ export interface FlowRecorder {
     onLoop?(event: FlowLoopEvent): void;
     onBreak?(event: FlowBreakEvent): void;
     onError?(event: FlowErrorEvent): void;
+    /**
+     * Called at the end of EVERY attempt — a stage's own, and the calls and
+     * observed attempts it makes during the stage (filter on `record.kind`) —
+     * with its record and the decision that followed (10.1). See
+     * {@link FlowAttemptEvent}.
+     */
+    onAttempt?(event: FlowAttemptEvent): void;
     /**
      * Called once per failed attempt that WILL be retried, for stages carrying a
      * declared `retry` policy. The final failure arrives via `onError` instead,

package/dist/types/lib/engine/traversal/FlowchartTraverser.d.ts

@@ -22,6 +22,7 @@
  * Break semantics: If a stage calls breakFn(), commit and STOP.
  * Patch model: Stage writes into local patch; commitPatch() after return or throw.
  */
+import type { RunCorrelation } from '../../attempt/types.js';
 import type { ScopeProtectionMode } from '../../scope/protection/types.js';
 import type { QueuedPause, ResumeEntry } from '../handlers/ResumeEntry.js';
 import { FlowRecorderDispatcher } from '../narrative/FlowRecorderDispatcher.js';
@@ -128,6 +129,11 @@ export interface TraverserOptions<TOut = any, TScope = any> {
      * needs it. See `runner/runId.ts`.
      */
     runId: string;
+    /**
+     * The leg's correlation (10.1, `attempt/correlation.ts · resolveCorrelation`) — stamped onto every
+     * TraversalContext and the snapshot, inherited by subflow traversers BY REFERENCE. Absent when the env gave none.
+     */
+    correlation?: RunCorrelation;
 }
 /**
  * Traverser-local overlay entry for a node whose stage function returned a
@@ -173,6 +179,11 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     private subflows;
     private readonly logger;
     private readonly signal?;
+    /**
+     * The run's deadline, epoch ms (`env.deadline`, stamped by the executor's `armRun`; a subflow inherits the env).
+     * Under one, EVERY stage runs on the attempt runner, so a lone stage the deadline cuts still leaves its attempt.
+     */
+    private readonly deadline?;
     private readonly parentSubflowId?;
     /** RFC-003 D1: runtimeStageId of the subflow mount stage in the parent
      *  traverser. Fallback `parentRuntimeStageId` for stages whose context has
@@ -187,6 +198,8 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     /** Per-`executor.run()` identifier. Stamped onto every TraversalContext.
      *  Inherited by subflow traversers so all events of one run share one runId. */
     private readonly runId;
+    /** The leg's correlation — one frozen object, stamped on every TraversalContext; inherited by subflows. */
+    private readonly correlation?;
     private readonly nodeResolver;
     private readonly childrenExecutor;
     private readonly subflowExecutor;
@@ -327,6 +340,7 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
     getSnapshot(options?: {
         redact?: boolean;
     }): {
+        correlation?: RunCorrelation | undefined;
         runId: string;
         sharedState: Record<string, unknown>;
         executionTree: unknown;
@@ -383,29 +397,55 @@ export declare class FlowchartTraverser<TOut = any, TScope = any> {
      * this method as `runStage`), and by extension fork children and
      * subflow-internal stages, which re-enter Phase 3 in their own traverser.
      *
-     * Which is exactly why the declarative retry loop lives HERE and nowhere
-     * else: one implementation gives `retry` to every stage kind that has a
-     * function to retry. (Putting it in `StageRunner` would have been wrong —
-     * the runner owns the scope and the interrupt boundary, but not the
-     * `StageContext` whose staged writes a failed attempt must discard.)
+     * Which is exactly why a declared `retry` policy is honoured HERE and
+     * nowhere else: one call gives `retry` to every stage kind that has a
+     * function to retry. The loop itself is the attempt runner's
+     * (`attempt/runner.ts · runAttempts`, 10.1 — one runner, one record); this
+     * method hands it the engine's half: one attempt (`StageRunner · run`, a
+     * fresh scope each time), the discard between attempts
+     * (`StageContext · discardStaged` — the runner cannot reach a frame), the
+     * served form of an attempt's error (`servedStageError`, the run's
+     * redaction rule), and where each record goes (the frame, for the
+     * execution tree; `onAttempt` and `onStageRetry`, for recorders).
      *
-     * With no `retry` policy this is a single call, byte-identical to the
-     * pre-9.15 path.
+     * NOT `async`, on purpose — the microtask shape of a stage is part of what
+     * the engine keeps byte-identical (parallel siblings settle in the order
+     * they always did):
+     *   - no policy (or `attempts: 1`, a declared-but-off policy): one call
+     *     through an async frame ({@link runStageOnce}), exactly the pre-10.1
+     *     shape — and no attempt is recorded;
+     *   - a policy: the runner's own promise, whose one await per attempt is the
+     *     same one await the 9.15 loop had.
      */
     private executeStage;
     /**
-     * R5 for ids a stage ADOPTS at run time (a returned StageNode's `next` chain,
-     * `children` and subflow ids): the same refusal the builder's doors apply —
-     * `ids/reservedIds.ts · refuseReservedId` — so "no user id carries a
-     * grammar delimiter" stays true by construction. Loop-ref stubs (they name an
-     * existing node) and the chart's own nodes (admitted at build; a prefixed id
-     * carries `/` on purpose) are not new ids and are skipped. A subflow
-     * definition's own tree is a built chart and is not walked.
-     */
-    private admitDynamicIds;
-    /** `retryOn` gate. A throwing predicate counts as "do not retry" — a broken
-     *  predicate must never turn a failing stage into an endless retry loop. */
-    private shouldRetry;
+     * A touching stage's side-effect target for THIS execution (P3, design §3.3). The law first — a chart edited
+     * after `build()` reaches the stage without the builder's refusal, so the stage asks `touchesProblem` itself (the
+     * last door). Then the key: the declared rule runs ONCE per execution, before attempt 1, handed the frozen input,
+     * the run id and this execution's id; its answer is admitted (`admitIdempotencyKey` — the format, never echoed) and
+     * served under the run's diagnostic rule as `{ idempotencyKey }` for the records. Throws on any refusal.
+     */
+    private effectTarget;
+    /** One call of a stage with no retry policy, through an async frame — the pre-10.1 microtask shape. */
+    private runStageOnce;
+    /**
+     * The run-time door for nodes a stage RETURNS (its `next` chain, `children`
+     * and subflow ids) — the builder never saw them, so this applies the
+     * builder's refusals:
+     *   - R5, ids: `ids/reservedIds.ts · refuseReservedId`, so "no user id
+     *     carries a grammar delimiter" stays true by construction. Loop-ref stubs
+     *     (they name an existing node) and the chart's own nodes (admitted at
+     *     build; a prefixed id carries `/` on purpose) are not new ids and are
+     *     skipped.
+     *   - a declared `retry`: `attempt/policy.ts · retryPolicyProblem`, the rule
+     *     `FlowChartBuilder · applyRetryPolicy` applies at build — `attempts`
+     *     must be a whole number >= 1, never `NaN`, `Infinity` or `0`.
+     *   - a declared `touches`: `attempt/effect.ts · touchesProblem`, the rule
+     *     `FlowChartBuilder · applyTouches` applies at build — a node that
+     *     touches an outside system and may retry must declare a key rule.
+     * A subflow definition's own tree is a built chart and is not walked.
+     */
+    private admitDynamicNodes;
     /**
      * Trampoline driver — pre-order DFS traversal entry point.
      *

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

@@ -19,6 +19,7 @@
  * has always done.
  */
 import { type RuntimeStageId } from 'foottrace';
+import type { RunCorrelation } from '../attempt/types.js';
 import type { ResumeLink, TraversalContext } from './narrative/types.js';
 /** Everything a stamp can carry; optional keys are written only when PRESENT on this object. */
 export interface TraversalStamp {
@@ -32,11 +33,13 @@ export interface TraversalStamp {
     readonly subflowId?: string;
     readonly subflowPath?: string;
     readonly resumedFrom?: ResumeLink;
+    /** The leg's correlation — the same frozen object on every stamp; written last, only when present. */
+    readonly correlation?: RunCorrelation;
 }
 /**
  * Build the stamp. `parentStageId` / `subflowId` / `subflowPath` are copied
  * when the key is present (even as `undefined`); `parentRuntimeStageId`,
- * `loopIteration` and `resumedFrom` only when they hold a value.
+ * `loopIteration`, `resumedFrom` and `correlation` only when they hold a value.
  */
 export declare function traversalContextFor(stamp: TraversalStamp): TraversalContext;
 /**
@@ -44,7 +47,7 @@ export declare function traversalContextFor(stamp: TraversalStamp): TraversalCon
  * depth 0) so the `runId` is reliably available on run events without forcing
  * recorders to handle `traversalContext === undefined`.
  */
-export declare function rootTraversalContext(runId: string): TraversalContext;
+export declare function rootTraversalContext(runId: string, correlation?: RunCorrelation): TraversalContext;
 /**
  * The `onResume` stamp. Names the stand-in's own execution (`runtimeStageId`,
  * the id its commit carries), the REAL subflow it runs in — `subflowId` is the
@@ -62,4 +65,6 @@ export declare function resumeTraversalContext(resume: {
     /** `checkpoint.subflowPath`: the prefixed id of every subflow on the way down, outermost first. */
     readonly subflowPath: readonly string[];
     readonly resumedFrom?: ResumeLink;
+    /** The RESUMED leg's correlation (from `resume()`'s env) — never the paused leg's. */
+    readonly correlation?: RunCorrelation;
 }): TraversalContext;

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

@@ -4,7 +4,7 @@
  * Centralizes type definitions to avoid circular dependencies.
  * Every handler receives HandlerDeps (the DI bag) instead of importing the traverser.
  */
-import type { LogAddress } from 'foottrace';
+import type { LogAddress, LogOutcome, Meta } from 'foottrace';
 import type { SharedMemory } from 'foottrace/write';
 import type { FlowControlType, FlowMessage } from '../memory/frameTypes.js';
 import type { StageContext } from '../memory/StageContext.js';
@@ -104,57 +104,7 @@ export interface ParallelForEachConfig<TItem = any, TScope = any> {
      */
     failFast?: boolean;
 }
-/**
- * Declarative per-stage retry policy.
- *
- * WHY this exists: a retry hand-rolled inside a stage function is invisible to
- * the trace. The stage shows one execution, the commit log shows one bundle,
- * and the two failed calls that preceded the successful one left no mark
- * anywhere — an unexplained behaviour in a library whose whole thesis is that
- * nothing invisible happens. Declared here instead, every attempt is part of
- * the record: each failed attempt fires `FlowRecorder.onStageRetry` with the
- * attempt number, the wait, and the structured error.
- *
- * A POLICY, not a stage kind — `retry` sits on a normal stage the way
- * `isPausable` / `isStreaming` do. The serialized node `type` is unchanged and
- * every existing consumer keeps rendering the stage exactly as before.
- *
- * @example
- * ```ts
- * flowChart<State>('Fetch user', fetchFn, 'fetch-user')
- *   .retry({ attempts: 3, backoffMs: (n) => 100 * 2 ** (n - 1) })
- * ```
- */
-export interface RetryPolicy {
-    /**
-     * How many times the stage function may run in total, INCLUDING the first
-     * run. Must be an integer >= 1; `1` means "no retry" (a declared no-op,
-     * accepted so a policy can be switched off without deleting it).
-     */
-    attempts: number;
-    /**
-     * How long to wait before the NEXT attempt. Either a fixed number of
-     * milliseconds, or a function of the attempt that just FAILED (1-based)
-     * returning milliseconds — `(n) => 100 * 2 ** (n - 1)` is exponential
-     * backoff. Omitted (or a non-finite / negative result) means no wait.
-     *
-     * The wait is a plain awaited timer that is CANCELLED by the run's
-     * `AbortSignal`. It is not a pause: a chart cannot be checkpointed in the
-     * middle of a backoff.
-     */
-    backoffMs?: number | ((attempt: number) => number);
-    /**
-     * Is THIS error worth another attempt? Defaults to retrying every error.
-     * Returning `false` ends the stage immediately on the normal error path —
-     * exactly as if no policy had been declared, and with no retry event (the
-     * policy chose not to act; there is nothing to report that the error event
-     * does not already say).
-     *
-     * A throw from this predicate is treated as `false` — a broken predicate
-     * must not turn a failing stage into an infinite retry loop.
-     */
-    retryOn?: (error: unknown) => boolean;
-}
+export type { RetryPolicy, StageTouches } from '../attempt/types.js';
 /**
  * Controls how array values from outputMapper are merged into parent scope.
  */
@@ -438,6 +388,14 @@ export interface IExecutionRuntime {
     };
     setRootObject(path: string[], key: string, value: unknown): void;
     getPipelines(): string[];
+    /**
+     * Where a mount's own log writes as it lands (10.1, P6) — the run's sink at this log's address plus the mount's
+     * `runtimeStageId`. `undefined` when this runtime's log writes to no sink. `SubflowExecutor` hands it to the
+     * nested runtime it constructs.
+     */
+    recordFor?(mountRuntimeStageId: string, meta?: Meta): unknown;
+    /** Tell the sink this runtime's log ended (10.1, P6) — a mount's at its exit. No-op without a sink. */
+    closeRecord?(outcome: LogOutcome, meta?: Meta): void;
 }
 /**
  * ExecutionEnv — infrastructure values that propagate through nested executors.
@@ -452,12 +410,39 @@ export interface IExecutionRuntime {
  * parent and child flowcharts.
  */
 export interface ExecutionEnv {
-    /** AbortSignal for cooperative cancellation across nested executors. */
+    /**
+     * AbortSignal for cooperative cancellation across nested executors. Honoured by the engine (10.1): it ends the
+     * run like `RunOptions.signal`. Under a run that has a signal or a deadline AND an env, a stage reads the run's
+     * ONE effective signal here — `RunOptions.signal`, this one and the deadline's timer, composed.
+     */
     readonly signal?: AbortSignal;
-    /** Timeout budget in milliseconds. */
+    /** Timeout budget in milliseconds. Readable only — the run's deadline is {@link deadline}. */
     readonly timeoutMs?: number;
-    /** Trace identifier for distributed tracing / observability. */
+    /**
+     * Trace identifier for distributed tracing / observability. With `operationId` (or alone) it becomes the run's
+     * `RunCorrelation`; it wins over the trace id of `traceparent`. 1–256 printable ASCII characters with no space
+     * (since 10.1 anything else rejects the run with a `TypeError` naming the field — the id rides every event);
+     * an empty string is no id.
+     */
     readonly traceId?: string;
+    /**
+     * The caller's unit of work (W3C's parent-id) — part of the run's `RunCorrelation`; wins over the header's
+     * parent-id. Needs a trace: `traceId` or `traceparent` (refused alone). Same character rule as `traceId`.
+     */
+    readonly operationId?: string;
+    /**
+     * A W3C `traceparent` header, usually straight from an inbound request. Parsed STRICTLY once per run — a
+     * malformed one refuses the run with a `TraceparentError` naming the reason (never the header). Stages read
+     * back (`$getEnv()`) exactly `RunCorrelation.traceparent` — the canonical header of the effective ids — or no
+     * key when the run's correlation carries none. Correlation only: never identity or authorisation.
+     */
+    readonly traceparent?: string;
+    /**
+     * The run's deadline, epoch milliseconds (10.1) — the earliest of `RunOptions.deadline`, `now + RunOptions.timeoutMs`
+     * and a deadline given here. The run's signal aborts when it passes; every attempt is capped by the time left.
+     * Inherited by subflows. Read it through `scope.$attempt().timeLeftMs()`.
+     */
+    readonly deadline?: number;
 }
 /**
  * HandlerDeps — Dependency injection bag passed to all handler modules.
@@ -496,10 +481,20 @@ export interface HandlerDeps<TOut = any, TScope = any> {
 }
 /** Options for FlowChartExecutor.run(). */
 export interface RunOptions {
-    /** AbortSignal for cooperative cancellation. */
+    /** AbortSignal for cooperative cancellation. Composed with `env.signal` and the deadline (10.1). */
     signal?: AbortSignal;
-    /** Timeout in milliseconds. Creates an internal AbortController. */
+    /**
+     * Timeout in milliseconds: the run's deadline is `now + timeoutMs`. The run aborts when it passes (rejecting with
+     * `Execution timed out after <timeoutMs>ms`), stages read it as `env.deadline`, and every stage records its
+     * attempt (`StageSnapshot.attempts`). Honoured beside a `signal` since 10.1 (it used to be ignored there).
+     */
     timeoutMs?: number;
+    /**
+     * The run's deadline, epoch milliseconds (10.1) — `Date.now() + 120_000`. Same effect as `timeoutMs`; when both
+     * are given, the earlier wins. A deadline already past stops the run before its first stage. A resumed leg has
+     * its own: pass it again to `resume()`.
+     */
+    deadline?: number;
     /**
      * Runtime input data for the pipeline.
      * Becomes the readOnlyContext accessible via `scope.getArgs()`.

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;
+}