footprintjs 10.0.1 → 10.2.0

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

@@ -9,9 +9,10 @@
  * The engine (FlowchartTraverser) receives this as its runtime parameter.
  * After execution, consumers query it for the full execution state.
  */
-import type { CommitBundle, CommitValuesMode, LogAddress } from 'foottrace';
-import type { WriteProvenanceMode } from 'foottrace/write';
+import type { CommitBundle, CommitValuesMode, LogAddress, LogOutcome, Meta } from 'foottrace';
+import type { RecordSink, WriteProvenanceMode } from 'foottrace/write';
 import { EventLog, SharedMemory } from 'foottrace/write';
+import type { RunCorrelation } from '../attempt/types.js';
 import type { StageSnapshot } from '../memory/frameTypes.js';
 import type { RunPolicy } from '../memory/runPolicy.js';
 import { StageContext } from '../memory/StageContext.js';
@@ -56,6 +57,13 @@ export type RuntimeSnapshot = {
      * snapshot carries a DIFFERENT runId than the paused run's snapshot.
      */
     readonly runId: string;
+    /**
+     * The run's correlation (10.1) — `env.traceparent`, or `env.traceId` + `env.operationId`, resolved once per
+     * leg; the same frozen object every event of the leg carries (`TraversalContext.correlation`, a scope event's
+     * `correlation`). Like `runId`, per leg: a resume carries ITS env's, never the paused leg's. Absent — no
+     * key — when none was given.
+     */
+    readonly correlation?: RunCorrelation;
     sharedState: Record<string, unknown>;
     executionTree: StageSnapshot;
     /**
@@ -124,7 +132,34 @@ export type RuntimeSnapshot = {
      * with `{ delivery: 'deferred' }` on this executor (zero-cost discipline).
      */
     observerStats?: ObserverStats;
+    /**
+     * The crash-safe record's accounting (10.1, P6) — how many entries the run handed its sink and how many the sink
+     * did not take. ABSENT unless the executor was built with a `sink` and a run started.
+     */
+    sink?: RecordSinkStats;
 };
+/** `getSnapshot().sink` — what the run handed its sink, and what the sink did not take (10.1, P6). */
+export interface RecordSinkStats {
+    /** Entries handed to the adapter (each `opened`, `commit`, `note`, `closed` call). */
+    readonly entries: number;
+    /**
+     * Losses — a method that threw or rejected, an entry the log refused to send, a `meta` the log could not copy
+     * (that entry was still stored, without it), and failed or timed-out flushes. A rejection that settles after the
+     * run finished is counted when it settles.
+     */
+    readonly failed: number;
+    /** The last loss's error, as text. Absent while nothing was lost. */
+    readonly lastError?: string;
+}
+/**
+ * Where a runtime's log writes as it lands (10.1, P6): the run's sink, the log's address and what the writer puts on
+ * its `opened` entry. Absent → the log is the plain one-argument `EventLog`, byte-identical to 10.0.
+ */
+export interface RuntimeRecord {
+    readonly sink: RecordSink;
+    readonly address: LogAddress;
+    readonly meta?: Meta;
+}
 export declare class ExecutionRuntime {
     globalStore: SharedMemory;
     /**
@@ -139,6 +174,8 @@ export declare class ExecutionRuntime {
     redactedStore?: SharedMemory;
     rootStageContext: StageContext;
     executionHistory: EventLog;
+    /** The run's sink, when this runtime's log writes to one — handed on to every mount (`recordFor`). */
+    private recordSink?;
     /** Original root for getSnapshot() — set before resume changes rootStageContext. */
     private _snapshotRoot?;
     private _initialState;
@@ -155,7 +192,7 @@ export declare class ExecutionRuntime {
      *   every frame after inherits the same reference. Default: every dial at
      *   its default, no rule, no mirror.
      */
-    constructor(rootName: string, rootId: string, defaultValues?: unknown, initialState?: unknown, policy?: RunPolicy);
+    constructor(rootName: string, rootId: string, defaultValues?: unknown, initialState?: unknown, policy?: RunPolicy, record?: RuntimeRecord);
     /**
      * A fresh root frame for this runtime — `globalStore`, `executionHistory`,
      * the run's policy and (when kept) the mirror. Also how `SubflowExecutor`
@@ -193,6 +230,16 @@ export declare class ExecutionRuntime {
      * 9.44.2).
      */
     private getFoldBase;
+    /**
+     * Where a mount's log writes (10.1, P6): the same sink, at this log's address plus the mount's `runtimeStageId`
+     * (`drillPath: [...parent, mount]`, the address law `RuntimeSnapshot.logAddress` states). Absent when this log
+     * writes to no sink — a mount of a plain log is plain too.
+     */
+    recordFor(mountRuntimeStageId: string, meta?: Meta): RuntimeRecord | undefined;
+    /** Tell the sink this runtime's log ended. Nothing happens without a sink; never throws. */
+    closeRecord(outcome: LogOutcome, meta?: Meta): void;
+    /** Note something beside this runtime's log, in its sink (a resumed leg). Nothing without a sink; never throws. */
+    noteRecord(kind: string, data: Meta): void;
     getPipelines(): string[];
     setRootObject(path: string[], key: string, value: unknown): void;
     /**
@@ -222,14 +269,15 @@ export declare class ExecutionRuntime {
      * `stateAt`, which is the honest signal that the base did not travel with
      * this log — a partial answer that says it is partial, never a silent one.
      *
-     * Returns `Omit<RuntimeSnapshot, 'runId'>`: the runtime is the memory
+     * Returns `Omit<RuntimeSnapshot, 'runId' | 'correlation'>`: the runtime is the memory
      * container and doesn't know which run it serves — `runId` is per-run
      * executor state, stamped by `FlowchartTraverser.getSnapshot()` (which
      * owns the run's id and already stamps it on every event). Subflows'
      * nested runtimes deliberately have NO runId of their own (a subflow is
-     * part of the parent's logical run).
+     * part of the parent's logical run). `correlation` is the traverser's for
+     * the same reason.
      */
     getSnapshot(options?: {
         redact?: boolean;
-    }): Omit<RuntimeSnapshot, 'runId'>;
+    }): Omit<RuntimeSnapshot, 'runId' | 'correlation'>;
 }

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';
@@ -36,6 +37,7 @@ import type { RedactionPolicy, RedactionReport, ScopeRecorder } from '../scope/t
 import type { AttachRecorderOptions, ObserverDrainResult } from './DeferredObserverTier.js';
 import { type RuntimeSnapshot } from './ExecutionRuntime.js';
 import { type FlowChartExecutorOptions } from './options.js';
+import { type RecordFlushResult } from './recordSink.js';
 export declare class FlowChartExecutor<TOut = any, TScope = any> {
     private traverser;
     /** Shared execution counter and per-stage visit counts (loopIteration) — shared BY
@@ -63,7 +65,16 @@ 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
+     * accounting and its failure mode. Fresh per `run()` and per fresh-executor resume; a same-executor resume keeps
+     * it, as it keeps the root log. Absent without a `sink` option.
+     */
+    private record;
     /**
      * Create a FlowChartExecutor.
      *
@@ -159,7 +170,7 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * const result = await executor.resume(restored, { approved: true });
      * ```
      */
-    resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth' | 'maxIterations'>): Promise<ExecutorResult>;
+    resume(checkpoint: FlowchartCheckpoint, resumeInput?: unknown, options?: Pick<RunOptions, 'signal' | 'env' | 'maxDepth' | 'maxIterations' | 'deadline' | 'timeoutMs'>): Promise<ExecutorResult>;
     /**
      * The settle of a leg that threw: flush the deferred tier (the OUTERMOST
      * handler — a pause re-throws through subflow traversers without exit
@@ -168,6 +179,22 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      * is rethrown.
      */
     private pausedOrThrow;
+    /**
+     * The settle of a leg that writes its record (10.1, P6) — the 10.0 settle (`run()` / `resume()`), then the root
+     * log's closing entry with how the leg ended, then (`flush: 'auto'`) the adapter's flush, all before the leg
+     * counts as finished. A leg without a sink never comes here: its settle has no extra await.
+     *
+     * The leg's own error always wins. A run that finished but lost an entry under `onFailure: 'fail'` rejects with
+     * the `RecordSinkError`.
+     */
+    private settleRecorded;
+    /**
+     * What a new root log opens with: names and numbers the run already serves — the run, the chart, the correlation,
+     * the deadline, the declared budget, and the run a fresh-executor resume continues. Served by the record.
+     */
+    private openingMeta;
+    /** The closing entry's error: the run's SERVED form of it, its name, message and code only (never `raw`). */
+    private closingError;
     /** The re-entrancy guard: one executor = one in-flight execution. */
     private assertIdle;
     /**
@@ -273,7 +300,8 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
      *
      * @param options `{ input, env }` — `input` is the frozen business input
      *   (read in a stage via `scope.$getArgs()`); `env` is infrastructure context
-     *   like `{ signal, timeoutMs, traceId }` (read via `scope.$getEnv()`).
+     *   like `{ signal, timeoutMs, traceId }` (read via `scope.$getEnv()`); `deadline` / `timeoutMs` give the run
+     *   its deadline (`env.deadline`, `scope.$attempt().timeLeftMs()`).
      *
      * After it resolves, read results off the executor:
      * - `getSnapshot()` — full state, commit log, execution tree.
@@ -294,6 +322,22 @@ export declare class FlowChartExecutor<TOut = any, TScope = any> {
     drainObservers(opts?: {
         timeoutMs?: number;
     }): Promise<ObserverDrainResult>;
+    /**
+     * Flush the record sink (10.1, P6): await the adapter's `flush()` — for an executor built with
+     * `sink: { adapter, flush: 'manual' }`, or before a serverless process freezes. `timeoutMs` bounds the wait; a
+     * flush still running then is `pending` (and keeps running). A failed flush is counted on `getSnapshot().sink`.
+     * Done at once without a sink, or with an adapter that has no `flush`.
+     *
+     * @example
+     * ```typescript
+     * const executor = new FlowChartExecutor(chart, { sink: { adapter: fileSink(path), flush: 'manual' } });
+     * await executor.run();
+     * await executor.flushRecord({ timeoutMs: 2_000 });
+     * ```
+     */
+    flushRecord(opts?: {
+        timeoutMs?: number;
+    }): Promise<RecordFlushResult>;
     /**
      * Returns the runtime snapshot.
      *

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

@@ -5,6 +5,7 @@
  * Called by FlowChartBuilder.build() to enrich the compiled chart with
  * d3-style chainable run methods and self-describing outputs.
  */
+import { type TimeBudgetOptions, type TimeBudgetReport } from '../budget/index.js';
 import type { FlowChart } from '../builder/types.js';
 import type { JsonSchema } from '../contract/types.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
@@ -49,6 +50,11 @@ export interface RunnableFlowChart<TOut = any, TScope = any> extends FlowChart<T
     toMCPTool(): MCPToolDescription;
     /** Generate a Mermaid flowchart diagram string from the chart's node graph. */
     toMermaid(): string;
+    /**
+     * The slowest this chart can take, from its declared retry policies — `timeBudget(chart, options)`. Checks
+     * against the chart's declared `.budget(ms)` unless `options.budgetMs` is given.
+     */
+    timeBudget(options?: TimeBudgetOptions): TimeBudgetReport;
 }
 /**
  * Enrich a FlowChart with run + describe methods.

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

@@ -15,6 +15,7 @@
  *     from the same per-stage list as `onRead`/`onWrite`);
  *   - a flow attach turns the narrative on (the flow channel needs it).
  */
+import type { RunCorrelation } from '../attempt/types.js';
 import type { CombinedNarrativeRecorderOptions } from '../engine/narrative/CombinedNarrativeRecorder.js';
 import { CombinedNarrativeRecorder } from '../engine/narrative/CombinedNarrativeRecorder.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
@@ -77,7 +78,7 @@ export declare class RunObservers {
      * The marked-keys set is ALWAYS wired (a stage can call
      * `setValue(key, val, true)` for per-call redaction without any policy).
      */
-    composeScopeFactory<TScope>(baseFactory: ScopeFactory<TScope>, redactionPolicy: RedactionPolicy | undefined, sharedRedactedKeys: Set<string>): ScopeFactory<TScope>;
+    composeScopeFactory<TScope>(baseFactory: ScopeFactory<TScope>, redactionPolicy: RedactionPolicy | undefined, sharedRedactedKeys: Set<string>, correlation?: RunCorrelation): ScopeFactory<TScope>;
     /**
      * The leg's flow recorders: the narrative recorder (when on), the user's
      * flow recorders, then the deferred tier's flow tap (RFC-001 Block 7) —

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

@@ -0,0 +1,42 @@
+/**
+ * runner/deadline.ts — `armRun`: the run's ONE effective signal and its deadline (design §3.1, P1b).
+ *
+ * A run has three ways to be told to stop — `RunOptions.signal`, `env.signal`, and a deadline (`RunOptions.deadline`,
+ * `now + RunOptions.timeoutMs`, or `env.deadline`; the earliest wins). Before 10.1 they did not compose: `timeoutMs`
+ * was ignored beside a `signal`, and `env.signal` was readable but never raced. `armRun` composes all of them into
+ * one signal the traverser races (and hands every subflow), and stamps the env a stage reads:
+ *
+ *   env.deadline = the deadline (epoch ms)      env.signal = the one composed signal
+ *
+ * — but only when there is something to stamp AND somewhere it was already going: a deadline always gives the run
+ * an env; a signal is stamped onto an env the caller gave. A run with no deadline and no env keeps no env, so a
+ * stage's `$getEnv()` stays `{}` and its commit carries no `'env'` mark — byte-identical to 10.0.
+ *
+ * At the deadline the signal aborts with a BRANDED reason (`attempt/deadline.ts`) carrying the message a run with
+ * `timeoutMs` always rejected with, so the attempt runner reads it as "out of time" (`timeout` / `no-time-left`),
+ * never as a cancellation.
+ */
+import type { ExecutionEnv } from '../engine/types.js';
+/** What `armRun` reads — the run's own options. */
+export interface RunTiming {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly deadline?: number;
+    readonly env?: ExecutionEnv;
+    /**
+     * The executor's own stop (10.1, P6): a record sink with `onFailure: 'fail'` aborts it at the first lost entry,
+     * with the `RecordSinkError` as its reason. Composed like the others; absent for every other run.
+     */
+    readonly stop?: AbortSignal;
+}
+/** The armed run: the signal the traverser races, the env stages read, and the one call that releases both. */
+export interface ArmedRun {
+    readonly signal: AbortSignal | undefined;
+    readonly env: ExecutionEnv | undefined;
+    /** The run's deadline, epoch ms — absent without one. */
+    readonly deadline: number | undefined;
+    /** Clear the deadline timer and remove every listener composition added. Idempotent. */
+    dispose(): void;
+}
+/** Compose the run's signal and deadline from its options; `now` is the clock (epoch ms). */
+export declare function armRun(timing: RunTiming, now?: () => number): ArmedRun;

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

@@ -1,11 +1,13 @@
 export type { ComposableRunner } from './ComposableRunner.js';
 export type { AttachRecorderOptions, ObserverDelivery, ObserverDrainResult, ObserverStats, } from './DeferredObserverTier.js';
-export type { RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
+export type { RecorderSnapshot, RecordSinkStats, RuntimeSnapshot } from './ExecutionRuntime.js';
 export { ExecutionRuntime } from './ExecutionRuntime.js';
 export { FlowChartExecutor } from './FlowChartExecutor.js';
 export type { SubtreeSnapshot } from './getSubtreeSnapshot.js';
 export { getSubtreeSnapshot, listSubflowPaths } from './getSubtreeSnapshot.js';
 export type { FlowChartExecutorOptions } from './options.js';
+export type { RecordFlushResult, RecordSinkFailureMode, RecordSinkFlushMode, RecordSinkOption, RecordSinkOptions, } from './recordSink.js';
+export { RecordSinkError } from './recordSink.js';
 export type { RunResult } from './RunContext.js';
 export { RunContext } from './RunContext.js';
 export type { RunnableFlowChart } from './RunnableChart.js';

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

@@ -9,6 +9,7 @@ import type { FlowChart } from '../builder/types.js';
 import type { ScopeFactory, StreamHandlers } from '../engine/types.js';
 import type { RunDials } from '../memory/runPolicy.js';
 import type { ScopeProtectionMode } from '../scope/protection/types.js';
+import { type RecordSinkOption, type ResolvedRecordSink } from './recordSink.js';
 /**
  * Options object for `FlowChartExecutor` — preferred over positional params.
  *
@@ -44,6 +45,20 @@ export interface FlowChartExecutorOptions<TScope = any> extends RunDials {
     initialContext?: unknown;
     /** Read-only input accessible via `scope.getArgs()` — never tracked or written. */
     readOnlyContext?: unknown;
+    /**
+     * Where the run's record goes AS IT LANDS, so a run that never finishes still leaves it: every log of the run
+     * (the root and each subflow mount) hands the sink its `opened` base, each commit, a note per attempt that ended,
+     * and its `closed` outcome. `fileSink(path)` (`footprintjs/sinks`, Node) or `memorySink()` (`foottrace/write`);
+     * read it back with `readStoredRecord` (`foottrace`). The redaction policy applies before any entry is written.
+     * A failing sink never stops the run (`onFailure: 'report'`, the default) — `getSnapshot().sink` counts what was
+     * lost. See the guide's "A crash-safe record".
+     *
+     * @example
+     * ```typescript
+     * const executor = new FlowChartExecutor(chart, { sink: fileSink('/var/footprint/run.jsonl') });
+     * ```
+     */
+    sink?: RecordSinkOption;
     /**
      * Custom error classifier for throttling detection. Return `true` if a fork
      * child's error represents a rate-limit or backpressure condition; the
@@ -70,6 +85,8 @@ export interface ExecutorArgs<TOut, TScope> {
     scopeProtectionMode?: ScopeProtectionMode;
     /** The dials as given (absent = default) — the run's policy is built from them per leg. */
     dials: RunDials;
+    /** The record sink, resolved and checked at construction (10.1, P6). */
+    sink?: ResolvedRecordSink;
 }
 /**
  * Resolve either constructor form. The 2-param form is the options form with

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

@@ -0,0 +1,128 @@
+/**
+ * runner/recordSink.ts — the run's side of the crash-safe record (design §3.5, packet P6).
+ *
+ * foottrace owns the port (`RecordSink`, `foottrace/write`): a log built with a sink hands it every entry AS IT
+ * LANDS — `opened`, `commit`, `note`, `closed` — and counts what the sink did not take. This file is what the
+ * EXECUTOR adds around an app's adapter, one {@link RunRecord} per run:
+ *
+ *   - THE ONE LAW, before any byte leaves: the `opened` base is the run's served form of it (the redaction rule's
+ *     `retainState`, the mirror's seed — so a policy key seeded by `initialContext` or a checkpoint never reaches
+ *     the sink), and the `opened` / `closed` meta are boundary records (`retainBoundary`). A commit is the log's own
+ *     bundle, already scrubbed at commit; an attempt note carries the served `AttemptRecord` (no `raw`).
+ *   - ACCOUNTING: every entry handed to the adapter is counted, every loss too (`getSnapshot().sink`), with a
+ *     dev-mode warning on the first loss of a run. The adapter's own `onFailure` hears a dispatched entry's loss
+ *     with that same served entry and a served error, isolated. A refusal before dispatch is counted without
+ *     forwarding Foottrace's unserved entry.
+ *   - THE FAILURE MODE (owner ruling Q3): `'report'` (default) — the run goes on; `'fail'` — the first lost entry
+ *     aborts the run's signal with a {@link RecordSinkError}, and a run that finished with a loss rejects with it.
+ *   - FLUSH: `'auto'` (default) — `run()` / `resume()` await the adapter's `flush()` after the closing entry;
+ *     `'manual'` — the app calls `executor.flushRecord()`.
+ *
+ * Every adapter method is called synchronously from the log; whatever the adapter throws or rejects with is the
+ * log's to count (`EventLog · sinkFailures`), never the run's — so nothing here throws to the engine.
+ */
+import type { Meta } from 'foottrace';
+import type { RecordSink } from 'foottrace/write';
+import type { RedactionRule } from '../memory/redaction.js';
+import type { RecordSinkStats } from './ExecutionRuntime.js';
+/** What a lost entry does to the run: `'report'` counts it and goes on; `'fail'` fails the run. */
+export type RecordSinkFailureMode = 'report' | 'fail';
+/** When the adapter's `flush()` runs: after each run's closing entry (`'auto'`), or when the app asks. */
+export type RecordSinkFlushMode = 'auto' | 'manual';
+/**
+ * The executor's `sink` option in its long form. The short form is the adapter itself.
+ *
+ * @example
+ * ```typescript
+ * new FlowChartExecutor(chart, { sink: { adapter: fileSink('/var/footprint/run.jsonl'), onFailure: 'fail' } });
+ * ```
+ */
+export interface RecordSinkOptions {
+    /** Where the entries go — `fileSink(path)` (`footprintjs/sinks`), `memorySink()` (`foottrace/write`), or yours. */
+    readonly adapter: RecordSink;
+    /** `'report'` (default): a lost entry is counted and the run goes on. `'fail'`: the first one fails the run. */
+    readonly onFailure?: RecordSinkFailureMode;
+    /** `'auto'` (default): `run()` awaits the adapter's `flush()` after the closing entry. `'manual'`: `flushRecord()`. */
+    readonly flush?: RecordSinkFlushMode;
+}
+/** The executor's `sink` option: an adapter, or {@link RecordSinkOptions}. */
+export type RecordSinkOption = RecordSink | RecordSinkOptions;
+/** What `executor.flushRecord()` resolves with — the `drainObservers` shape. */
+export interface RecordFlushResult {
+    /** The adapter's flush finished (or there was nothing to flush). */
+    readonly done: boolean;
+    /** The adapter's flush threw or rejected — counted on `getSnapshot().sink`. */
+    readonly failed: boolean;
+    /** The flush had not settled when `timeoutMs` ran out. */
+    readonly pending: boolean;
+}
+/**
+ * A run with `sink: { onFailure: 'fail' }` lost an entry: the record the app asked to be kept is not whole.
+ * `cause` is the adapter's own error.
+ */
+export declare class RecordSinkError extends Error {
+    readonly cause: unknown;
+    readonly name = "RecordSinkError";
+    constructor(message: string, cause: unknown);
+}
+/** The option resolved once, at construction. */
+export interface ResolvedRecordSink {
+    readonly adapter: RecordSink;
+    readonly onFailure: RecordSinkFailureMode;
+    readonly flush: RecordSinkFlushMode;
+}
+/**
+ * Resolve the executor's `sink` option, or refuse it with a `TypeError` naming what is wrong — a wiring mistake
+ * the app makes once, so it fails at construction, never mid-run.
+ */
+export declare function resolveRecordSink(option: unknown): ResolvedRecordSink | undefined;
+/**
+ * One run's record sink: the sink every log of the run writes to (root and mounts), its accounting and its
+ * failure mode. A same-executor resume keeps it (the root log goes on); a fresh run makes a new one.
+ */
+export declare class RunRecord {
+    private readonly resolved;
+    /** Hand this to every `EventLog` of the run. */
+    readonly sink: RecordSink;
+    private entries;
+    private failed;
+    private lastError?;
+    private warned;
+    private rule?;
+    /** Aborted at the first loss under `'fail'` — composed into the leg's signal; fresh per leg ({@link beginLeg}). */
+    private stopper?;
+    private failure?;
+    /** Opaque error identities only: no raw entry or adapter error is enumerable on the transport error. */
+    private readonly invocationFailures;
+    constructor(resolved: ResolvedRecordSink);
+    /** Capture the served entry now; an asynchronous failure keeps this leg's rule, not a later resume's rule. */
+    private invoke;
+    /** A sink error is the diagnostic errors.recordSinkError; raw causes belong only to the caller's exception. */
+    private errorView;
+    /**
+     * A same-executor resume starts a new leg on the same record: the counts go on (one log, one record), but the
+     * failure mode is the LEG's — a loss in an earlier leg (which already failed that leg) does not stop this one —
+     * and the dev-mode warning may fire again.
+     */
+    beginLeg(): void;
+    /** The leg's redaction rule — a resume builds a new one; the next `opened` / `closed` is served under it. */
+    useRule(rule: RedactionRule | undefined): void;
+    /** Aborts at the first loss under `onFailure: 'fail'`; absent otherwise. */
+    get stopSignal(): AbortSignal | undefined;
+    get flushMode(): RecordSinkFlushMode;
+    /** The loss that fails the run under `'fail'`; absent while nothing was lost (and always under `'report'`). */
+    get fatal(): RecordSinkError | undefined;
+    stats(): RecordSinkStats;
+    /**
+     * Await the adapter's `flush()`, at most `timeoutMs` when given. A flush that throws or rejects is a loss
+     * (counted, and fatal under `'fail'`); one still running at the deadline is `pending` and keeps running — and,
+     * with `pendingIsLoss` (the run's own flush), counted as a loss too, so a flush that never settles cannot hold a
+     * run open, and cannot pass for one that landed. Nothing here throws: a hostile adapter (a throwing `flush`
+     * getter, a promise with its own `then`) is a loss, never the run's error.
+     */
+    flush(timeoutMs?: number, pendingIsLoss?: boolean): Promise<RecordFlushResult>;
+    /** The meta as served: a boundary record, scrubbed by key name at every depth (an inert rule copies nothing). */
+    serve(meta: Meta): Meta;
+    /** One loss: counted, warned once per run, told with a safe dispatched entry when available, fatal under 'fail'. */
+    private lost;
+}

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

@@ -17,6 +17,7 @@
  * The executor owns the per-run state between the steps (the runId, the
  * runtime, the traverser); this module never holds any.
  */
+import type { RunCorrelation } from '../attempt/types.js';
 import type { FlowChart } from '../builder/types.js';
 import { ResumeEntry } from '../engine/handlers/ResumeEntry.js';
 import type { StageNode } from '../engine/types.js';
@@ -70,4 +71,6 @@ export declare function announceResume<TOut, TScope>(plan: ResumePlan<TOut, TSco
     readonly runId: string;
     readonly executionCount: number;
     readonly observers: RunObservers;
+    /** The RESUMED leg's correlation (from `resume()`'s env) — on both events, like every event of the leg. */
+    readonly correlation?: RunCorrelation;
 }): void;

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

@@ -7,7 +7,7 @@
  */
 import type { FlowchartTraverser } from '../engine/traversal/FlowchartTraverser.js';
 import type { RunObservers } from './attach.js';
-import type { RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
+import type { RecorderSnapshot, RecordSinkStats, RuntimeSnapshot } from './ExecutionRuntime.js';
 /**
  * The served snapshot. `sharedState` is the LIVE view in production (zero
  * copy); in dev mode it is a deep-frozen CLONE, so a consumer mutation throws
@@ -15,7 +15,7 @@ import type { RecorderSnapshot, RuntimeSnapshot } from './ExecutionRuntime.js';
  */
 export declare function servedSnapshot(traverser: FlowchartTraverser<any, any>, observers: RunObservers, options?: {
     redact?: boolean;
-}): RuntimeSnapshot;
+}, sink?: RecordSinkStats): RuntimeSnapshot;
 /**
  * Collect `toSnapshot()` bundles from every attached recorder — ONE entry
  * per recorder id, across all channels and both delivery tiers.