footprintjs 10.0.1 → 10.2.0

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

@@ -59,6 +59,7 @@
  * ```
  */
 import type { EmitSourcePosition } from 'foottrace';
+import type { RunCorrelation } from '../attempt/types.js';
 import type { RecorderBundle } from './snapshot.js';
 /**
  * Event delivered to `EmitRecorder.onEmit`.
@@ -109,6 +110,8 @@ export interface EmitEvent {
      * Absent on old/manual events and scopes without a bound engine log.
      */
     readonly sourcePosition?: EmitSourcePosition;
+    /** The run's correlation (10.1) — as on every scope event (`RecorderContext.correlation`). Absent when none. */
+    readonly correlation?: RunCorrelation;
 }
 /**
  * Pluggable observer for consumer-emitted structured events.

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

@@ -33,6 +33,18 @@
  *   (it means "in progress" or "paused"). The `getBoundary()` helper
  *   returns `{ entry, exit: undefined }` in that case.
  *
+ * Attempts (10.1):
+ *   An `exit` entry carries `attempts` — the count of attempts made inside
+ *   the boundary, at any depth, by outcome, and how many series gave up —
+ *   and `failedAttempts`, the failed / timed-out / aborted ones by name. Only
+ *   series that retried, gave up or timed out count (`recorder/attemptSeries.ts ·
+ *   isRetryEvidence`), so both fields are absent when nothing retried, and a
+ *   boundary pair says what it cost to get through. An `entry` never carries
+ *   them: the cost is known only at the exit — so a boundary that never
+ *   exits (a run or subflow that failed, e.g. because a stage gave up, or a
+ *   pause) carries no count; the attempts are then on the execution tree and
+ *   the attempt-aware recorders (Topology, Debug, Quality).
+ *
  * Redaction:
  *   Payload redaction is the engine's responsibility (`RedactionPolicy`).
  *   By the time payloads reach this recorder via `FlowSubflowEvent` or
@@ -63,7 +75,8 @@
  *   .filter((b) => b.subflowPath[1] === 'sf-agent');  // path[0] is the root
  * ```
  */
-import type { FlowRecorder, FlowRunEvent, FlowSubflowEvent } from '../engine/narrative/types.js';
+import type { FlowAttemptEvent, FlowRecorder, FlowRunEvent, FlowSubflowEvent } from '../engine/narrative/types.js';
+import type { AttemptOutcomeCounts, AttemptRef } from './attemptSeries.js';
 export type InOutPhase = 'entry' | 'exit';
 /** Synthetic id for the top-level run's boundary pair. */
 export declare const ROOT_SUBFLOW_ID = "__root__";
@@ -111,6 +124,20 @@ export interface InOutEntry {
      *  Lens uses this to render the root pair as `user → run → user` instead of
      *  the regular subflow shape. */
     readonly isRoot: boolean;
+    /** `phase: 'exit'` only, and only when something inside retried, gave up or timed out — see {@link InOutAttempts}. */
+    readonly attempts?: InOutAttempts;
+    /** With `attempts`: the attempts inside that failed, timed out or were aborted, in the order they ended. */
+    readonly failedAttempts?: readonly AttemptRef[];
+}
+/**
+ * What it cost to get through a boundary: the attempts made inside it (at any depth) by series that retried, gave
+ * up or timed out — `count`, per outcome (`timeout` included), and how many of those series gave up (`exhausted`,
+ * `declined`, `no-time-left`).
+ */
+export interface InOutAttempts {
+    readonly count: number;
+    readonly byOutcome: AttemptOutcomeCounts;
+    readonly gaveUp: number;
 }
 export interface InOutRecorderOptions {
     /** ScopeRecorder id. Defaults to `inout-N` (auto-incremented). */
@@ -132,11 +159,20 @@ export declare class InOutRecorder implements FlowRecorder {
     readonly id: string;
     /** 1:N ordered storage with per-step index (Convention 1 — composed). */
     private readonly store;
+    /** The root run's attempts — every attempt is inside it. */
+    private rootAttempts;
+    /** Open subflow boundaries' attempts, by path-prefixed subflowId. */
+    private readonly openAttempts;
     constructor(options?: InOutRecorderOptions);
     onRunStart(event: FlowRunEvent): void;
     onRunEnd(event: FlowRunEvent): void;
     onSubflowEntry(event: FlowSubflowEvent): void;
     onSubflowExit(event: FlowSubflowEvent): void;
+    /**
+     * Counts an attempt in the root boundary and in every open subflow boundary that contains the stage — the
+     * subflow the stage ran in is that subflow's id or below it.
+     */
+    onAttempt(event: FlowAttemptEvent): void;
     /** All entries in execution order (entry+exit interleaved). */
     getBoundaries(): InOutEntry[];
     /** Entry/exit pair for one chart execution.

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

@@ -10,6 +10,17 @@
  *   - **Accumulate**: progressive quality up to slider position
  *   - **Aggregate**: overall pipeline quality score
  *
+ * Attempts (10.1): a stage whose retry series GAVE UP (exhausted, declined,
+ * no time left) or TIMED OUT is a quality drop at that stage — `drop:
+ * 'attempts'`, with the series' `attempts` summary and a factor naming why.
+ * A series that gave up never reached `onStageEnd` (the stage failed), so the
+ * recorder scores it itself: `0`, the floor, with the keys its last attempt
+ * read — which is what `qualityTrace()` walks to pair the drop with its
+ * causal parents. A series that timed out and recovered keeps the scoring
+ * function's score and gains the flag. Attempts reach a recorder on the FLOW
+ * channel (`onAttempt`): attach with `attachCombinedRecorder` to see them —
+ * `attachScopeRecorder` scores exactly as before.
+ *
  * @example
  * ```typescript
  * const quality = new QualityRecorder((runtimeStageId, context) => {
@@ -30,6 +41,8 @@
  * quality.getLowest();  // { runtimeStageId: 'call-llm#5', entry: { score: 0.7, ... } }
  * ```
  */
+import type { AttemptSummary } from '../attempt/types.js';
+import type { FlowAttemptEvent } from '../engine/narrative/types.js';
 import type { ReadEvent, ScopeRecorder, StageEvent, WriteEvent } from '../scope/types.js';
 import type { RecorderOperation } from './RecorderOperation.js';
 /** Per-step quality data stored by QualityRecorder. */
@@ -46,6 +59,10 @@ export interface QualityEntry {
     keysRead: string[];
     /** Keys written during this step (for backtracking). */
     keysWritten: string[];
+    /** Present when the step's retry series gave up or timed out — a quality drop by attempts (10.1). */
+    drop?: 'attempts';
+    /** With `drop`: the series at a glance. */
+    attempts?: AttemptSummary;
 }
 /**
  * Scoring function called at the end of each stage.
@@ -76,16 +93,26 @@ export declare class QualityRecorder implements ScopeRecorder {
     /** 1:1 per-step storage (Convention 1 — composed, not inherited). */
     private readonly store;
     private readonly scoringFn;
-    private currentRuntimeStageId;
-    private currentStageId;
-    private currentStageName;
-    private currentKeysRead;
-    private currentKeysWritten;
+    /**
+     * Each execution in flight, by its OWN runtimeStageId (10.1) — every event owns its attribution, so parallel
+     * siblings never score under each other's id or with each other's keys (until 10.0 one shared "current stage"
+     * buffer did). A retried execution's entry restarts with each attempt: a series that gave up is scored with the
+     * keys its last attempt touched. Released at the stage's end, or when a drop consumes it.
+     */
+    private readonly inFlight;
+    /** Per-series tallies of the series that retried, gave up or timed out. */
+    private readonly attemptBook;
     constructor(scoringFn: QualityScoringFn, options?: QualityRecorderOptions);
     onStageStart(event: StageEvent): void;
     onRead(event: ReadEvent): void;
     onWrite(event: WriteEvent): void;
     onStageEnd(event: StageEvent): void;
+    /**
+     * A series that ended after giving up or timing out is a drop at its stage. `onAttempt` for the last attempt
+     * fires after that attempt's `onStageEnd` (when it returned), so a recovered series amends the scored entry; a
+     * series that gave up has none, and is scored here.
+     */
+    onAttempt(event: FlowAttemptEvent): void;
     /** Translate: quality entry for a specific runtimeStageId. */
     getByKey(runtimeStageId: string): QualityEntry | undefined;
     /** All per-step quality entries as a read-only Map (insertion-ordered). */

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

@@ -15,10 +15,16 @@
  *   three primitive channels, one live graph, queryable at any moment during
  *   or after a run.
  *
- * What it records — THREE node kinds for complete composition coverage:
+ * What it records — FOUR node kinds for complete composition coverage:
  *   1. 'subflow'          — via onSubflowEntry (a mounted subflow boundary)
  *   2. 'fork-branch'      — via onFork (one node per child, synthesized)
  *   3. 'decision-branch'  — via onDecision (the chosen branch, synthesized)
+ *   4. 'attempt-series'   — via onAttempt (10.1): a stage execution that
+ *      RETRIED, GAVE UP or TIMED OUT (`recorder/attemptSeries.ts · isRetryEvidence`), with its
+ *      `attemptSummary` and its ordered `attempts`. A retry is a loop, so each
+ *      retry decision is a self-edge of kind 'retry' on the node — the way
+ *      onLoop draws 'loop-iteration'. A stage that ran once (with or without a
+ *      policy) is no node, as before.
  *
  *   When a fork-branch or decision-branch target IS ALSO a subflow, the
  *   subsequent onSubflowEntry creates a subflow CHILD of the synthetic node.
@@ -48,11 +54,13 @@
  * topo.getSubflowNodes();                     // only mounted subflows
  * ```
  */
-import type { FlowDecisionEvent, FlowForkEvent, FlowLoopEvent, FlowRecorder, FlowSubflowEvent } from '../engine/narrative/types.js';
+import type { AttemptSummary } from '../attempt/types.js';
+import type { FlowAttemptEvent, FlowDecisionEvent, FlowForkEvent, FlowLoopEvent, FlowRecorder, FlowSubflowEvent } from '../engine/narrative/types.js';
+import type { AttemptRef } from './attemptSeries.js';
 /** The kind of composition unit a node represents. */
-export type TopologyNodeKind = 'subflow' | 'fork-branch' | 'decision-branch';
+export type TopologyNodeKind = 'subflow' | 'fork-branch' | 'decision-branch' | 'attempt-series';
 /** How the traversal reached this node — drives consumer layout decisions. */
-export type TopologyIncomingKind = 'root' | 'next' | 'fork-branch' | 'decision-branch' | 'loop-iteration';
+export type TopologyIncomingKind = 'root' | 'next' | 'fork-branch' | 'decision-branch' | 'loop-iteration' | 'retry';
 /** A composition-significant point in the graph. */
 export interface TopologyNode {
     /** Unique id. Subflows use their subflowId (with `#n` suffix on re-entry).
@@ -76,8 +84,16 @@ export interface TopologyNode {
     /** runtimeStageId when the corresponding subflow exited. Only meaningful
      *  for kind='subflow'; fork/decision-branch nodes are instantaneous. */
     exitedAt?: string;
-    /** Kind-specific extras: forkParent, decider, rationale, description. */
+    /** Kind-specific extras: forkParent, decider, rationale, description; stageId for an attempt series. */
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * kind='attempt-series' only: the series at a glance — equal to the stage's
+     * `StageSnapshot.attemptSummary`. Absent while the series is in flight (or
+     * when the run's signal cut its wait: no record says how it ended).
+     */
+    readonly attemptSummary?: AttemptSummary;
+    /** kind='attempt-series' only: the series' attempts, in order. */
+    readonly attempts?: readonly AttemptRef[];
 }
 /** A traversal transition between two nodes. */
 export interface TopologyEdge {
@@ -135,12 +151,26 @@ export declare class TopologyRecorder implements FlowRecorder {
      * TopologyRecorder is supposed to expose.
      */
     private readonly previousSubflowInScope;
+    /** Open subflow node id by its path-prefixed subflowId — where a stage's attempt series hangs. */
+    private readonly openSubflowByPath;
+    /** Per-series tallies of the series that are evidence (retried, gave up or timed out). */
+    private readonly attemptBook;
     constructor(options?: TopologyRecorderOptions);
     onSubflowEntry(event: FlowSubflowEvent): void;
     onSubflowExit(event: FlowSubflowEvent): void;
     onFork(event: FlowForkEvent): void;
     onDecision(event: FlowDecisionEvent): void;
     onLoop(event: FlowLoopEvent): void;
+    onAttempt(event: FlowAttemptEvent): void;
+    /**
+     * A new series node, under its parent: the pending fork-branch / decision-
+     * branch of the same name (a fork child or a chosen branch that is a plain
+     * stage), else the open subflow the stage runs in (read off its
+     * runtimeStageId — the stack top can be a parallel sibling), else the top
+     * level. One edge from
+     * the parent, as for every composition child.
+     */
+    private placeSeries;
     /** Called by the executor before each `run()` — resets all state. */
     clear(): void;
     /** Live snapshot of the composition graph. Safe during or after a run. */

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

@@ -0,0 +1,11 @@
+import type { AttemptQuery, AttemptRow } from './attemptMetricsTypes.js';
+/** Decode plain own data only; external data never gets to run getters or coercion hooks. */
+export declare function ownDataRecord(value: unknown): Record<string, unknown> | undefined;
+/** Read an external array window by descriptors, never by executing an index accessor or iterator. */
+export declare function metricWindow(value: unknown, maxRows: number): {
+    values: unknown[];
+    omitted: number;
+};
+/** Invalid stored data is omitted and accounted, never copied as an arbitrary envelope. */
+export declare function metricRow(value: unknown): AttemptRow | undefined;
+export declare function matchesQuery(row: AttemptRow, query: AttemptQuery): boolean;

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

@@ -0,0 +1,7 @@
+import type { AttemptAggregate, AttemptMetricRef, AttemptRow, AttemptStorageStats, PhysicalAttemptRow } from './attemptMetricsTypes.js';
+export declare const attemptRowKey: (row: AttemptRow) => string;
+export declare const logicalKey: (runId: string, series: string, attempt: number) => string;
+export declare const seriesKey: (runId: string, series: string) => string;
+export declare function reference(row: PhysicalAttemptRow): AttemptMetricRef;
+export declare function worst(rows: readonly PhysicalAttemptRow[], limit: number): AttemptMetricRef[];
+export declare function aggregateAttempts(rows: readonly AttemptRow[], exemplars: number, storage: AttemptStorageStats): AttemptAggregate;

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

@@ -0,0 +1,114 @@
+/** Payload-free P7 rows and public metric projections. Store adapters receive named facts, never errors or keys. */
+import type { AttemptId } from 'foottrace';
+import type { RetryLoopCall, RetryLoopDecision } from '../attempt/retryLoopTypes.js';
+import type { AttemptCategory, AttemptEffect, AttemptKind, AttemptNext, AttemptOutcome, AttemptReason } from '../attempt/types.js';
+export interface AttemptMetricRef {
+    readonly id: AttemptId;
+    readonly series: string;
+    readonly runId: string;
+    readonly runtimeStageId: string;
+    readonly attemptKind: AttemptKind;
+    readonly retryLoop?: RetryLoopCall;
+    readonly target: string;
+    readonly traceId?: string;
+    readonly startedAt: number;
+    readonly durationMs: number;
+    readonly outcome: AttemptOutcome;
+    readonly category?: AttemptCategory;
+    readonly next: AttemptNext;
+    readonly reason: AttemptReason;
+}
+export interface PhysicalAttemptRow extends AttemptMetricRef {
+    readonly kind: 'attempt';
+    readonly attemptKind: AttemptKind;
+    readonly attempt: number;
+    readonly of?: number;
+    readonly effect?: AttemptEffect;
+    readonly retryLoop?: RetryLoopCall;
+}
+export interface AttemptDecisionRow extends RetryLoopDecision {
+    readonly kind: 'decision';
+    readonly runId: string;
+    readonly target: string;
+    readonly runtimeStageId: string;
+    readonly attemptId: AttemptId;
+    readonly startedAt: number;
+}
+export interface AttemptRunRow {
+    readonly kind: 'run';
+    readonly runId: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly outcome: 'running' | 'ok' | 'failed' | 'paused';
+}
+export type AttemptRow = PhysicalAttemptRow | AttemptDecisionRow | AttemptRunRow;
+export interface AttemptQuery {
+    readonly since?: number;
+    readonly until?: number;
+    readonly target?: string;
+    readonly runId?: string;
+}
+export interface AttemptStore {
+    append(rows: readonly AttemptRow[]): void | Promise<void>;
+    read(query: AttemptQuery): Promise<readonly AttemptRow[]>;
+    /** Optional known retention accounting; omitted evidence must not appear complete. */
+    stats?(): {
+        readonly omittedRows: number;
+    };
+}
+export interface AttemptStorageStats {
+    readonly pending: number;
+    readonly failed: number;
+    readonly dropped: number;
+    readonly omittedRows: number;
+    readonly incomplete: boolean;
+}
+export interface AttemptStats {
+    readonly target: string;
+    readonly count: number;
+    readonly byKind: Record<AttemptKind, number>;
+    readonly byOutcome: Record<AttemptOutcome, number>;
+    readonly byCategory: Record<AttemptCategory, number>;
+    readonly retries: number;
+    readonly seriesRetried: number;
+    readonly gaveUp: number;
+    readonly effectUnknown: number;
+    readonly latencyMs: {
+        readonly p50: number;
+        readonly p90: number;
+        readonly p95: number;
+        readonly max: number;
+        readonly mean: number;
+    };
+    /** Sum of attempt durations (work time), which can overlap or nest; not elapsed run time. */
+    readonly budgetUsedMs: number;
+    readonly exemplars: {
+        readonly slowest: AttemptMetricRef[];
+        readonly timeout: AttemptMetricRef[];
+        readonly failed: AttemptMetricRef[];
+        readonly unknown: AttemptMetricRef[];
+        readonly gaveUp: AttemptMetricRef[];
+    };
+}
+export interface AttemptRunStats {
+    readonly runId: string;
+    readonly attempts: number;
+    readonly retries: number;
+    readonly gaveUp: number;
+    readonly budgetUsedMs: number;
+    readonly budgetMs?: number;
+    readonly exemplars: AttemptMetricRef[];
+    readonly outcome: AttemptRunRow['outcome'] | 'incomplete';
+}
+export interface AttemptAggregate {
+    readonly byTarget: Map<string, AttemptStats>;
+    readonly byRun: Map<string, AttemptRunStats>;
+    readonly storage: AttemptStorageStats;
+}
+export interface AttemptRecorderOptions {
+    readonly exemplars?: number;
+    readonly maxRows?: number;
+    readonly maxPending?: number;
+    readonly storeTimeoutMs?: number;
+    readonly store?: AttemptStore;
+}

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

@@ -0,0 +1,78 @@
+import type { AttemptStats, PhysicalAttemptRow } from './attemptMetricsTypes.js';
+export declare function attemptOTel(rows: readonly PhysicalAttemptRow[], byTarget: ReadonlyMap<string, AttemptStats>, limit: number): {
+    resourceMetrics: {
+        resource: {
+            attributes: never[];
+        };
+        scopeMetrics: {
+            scope: {
+                name: string;
+            };
+            metrics: ({
+                name: string;
+                unit: string;
+                description: string;
+                histogram: {
+                    aggregationTemporality: number;
+                    dataPoints: {
+                        attributes: {
+                            key: string;
+                            value: {
+                                stringValue: string;
+                            };
+                        }[];
+                        startTimeUnixNano: string;
+                        timeUnixNano: string;
+                        count: string;
+                        sum: number;
+                        explicitBounds: number[];
+                        bucketCounts: string[];
+                        exemplars: {
+                            traceId?: string | undefined;
+                            asDouble: number;
+                            timeUnixNano: string;
+                            filteredAttributes: {
+                                key: string;
+                                value: {
+                                    stringValue: string;
+                                };
+                            }[];
+                        }[];
+                    }[];
+                };
+                sum?: undefined;
+            } | {
+                name: string;
+                unit: string;
+                sum: {
+                    aggregationTemporality: number;
+                    isMonotonic: boolean;
+                    dataPoints: {
+                        attributes: {
+                            key: string;
+                            value: {
+                                stringValue: string;
+                            };
+                        }[];
+                        startTimeUnixNano: string;
+                        timeUnixNano: string;
+                        asDouble: number;
+                        exemplars: {
+                            asDouble: number;
+                            traceId?: string | undefined;
+                            timeUnixNano: string;
+                            filteredAttributes: {
+                                key: string;
+                                value: {
+                                    stringValue: string;
+                                };
+                            }[];
+                        }[];
+                    }[];
+                };
+                description?: undefined;
+                histogram?: undefined;
+            })[];
+        }[];
+    }[];
+};

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

@@ -0,0 +1,81 @@
+/**
+ * recorder/attemptSeries.ts — what a RECORDER keeps of a series: the one evidence predicate, the stop that gave up, and a
+ * per-series tally rebuilt from `onAttempt` records (design §5.1, P1c).
+ *
+ * WHY one module: seven built-in recorders account for attempts, and each must agree on two questions — "is this
+ * series worth a row?" and "did it give up?" — or a Topology node and a boundary count would disagree about the
+ * same run. Asked here, once.
+ *
+ * THE predicate (`isRetryEvidence`): a series is evidence when it RETRIED (some attempt was followed by another),
+ * GAVE UP while a retry was possible (it stopped `exhausted`, `declined` or `no-time-left` with `of > 1`, §3.9), or
+ * TIMED OUT (an attempt ran out of its cap or the deadline — P1b's lone timeout is the incident's own shape). A
+ * policy stage that succeeded first time — or that paused or was aborted on its first attempt — is
+ * indistinguishable from a stage with no policy in every recorder row, so a chart in which nothing retried keeps
+ * those rows byte-identical (law 2). So is a LONE attempt (`of: 1`, recorded for every stage of a run with a
+ * deadline, P1b) that merely failed: a stage error like any other, so a deadline alone never multiplies rows.
+ *
+ * Records arrive in order within a series, so the predicate is decided at the series' FIRST record: attempt 1 is
+ * evidence iff it did not end the series quietly, and every later attempt is evidence by being one.
+ *
+ * L5 (`recorder/**`), beside the stores: it imports the attempt vocabulary's types only (the L0 leaf), so
+ * `recorder/` never takes a runtime edge into `attempt/` — whose runner reaches `decide/` and `scope/`, which
+ * import `recorder/` (a module cycle).
+ */
+import type { AttemptOutcome, AttemptRecord, AttemptSummary } from '../attempt/types.js';
+/**
+ * One attempt, named — `series` (the stage execution's `runtimeStageId`) plus the 1-based `attempt`. The
+ * identity `AttemptRecord` carries until the engine stamps foottrace's attempt id (design §3.4).
+ */
+export interface AttemptRef {
+    readonly series: string;
+    readonly attempt: number;
+}
+/** Attempt counts per outcome — the shape `AttemptSummary` uses, without the series' end. */
+export type AttemptOutcomeCounts = Readonly<Record<AttemptOutcome, number>>;
+/** The series stopped on this record because retrying was given up (exhausted, declined or no time left). */
+export declare function gaveUp(record: Pick<AttemptRecord, 'next' | 'reason'>): boolean;
+/**
+ * The record belongs to a STAGE's series that retried, gave up or timed out — the one row predicate every recorder
+ * shares. A call's or an observed attempt (`scope.$call`, `observed()`, P2) is never a row here: these recorders keep
+ * one row per stage execution, and a call is counted per TARGET (the `attempts()` recorder, P7) — drawn as a stage's
+ * retry it would say the stage retried when only its call did.
+ */
+export declare function isRetryEvidence(record: AttemptRecord): boolean;
+/** Did the attempt itself fail — a failure, a timeout or the run's abort (not a success, not a pause)? */
+export declare function attemptFailed(record: AttemptRecord): boolean;
+/** The record's name. */
+export declare function attemptRef(record: AttemptRecord): AttemptRef;
+/**
+ * The path-prefixed id of the subflow an attempt's stage ran in (`'sf-outer/sf-inner'`), or `undefined` at the top
+ * level — read off the stage execution's `runtimeStageId` (the event's, else the series'), the one id that always
+ * carries it.
+ */
+export declare function subflowOfAttempt(event: {
+    readonly record: AttemptRecord;
+    readonly traversalContext?: {
+        readonly runtimeStageId: string;
+    };
+}): string | undefined;
+/** A zeroed per-outcome count. */
+export declare function emptyOutcomeCounts(): Record<AttemptOutcome, number>;
+/** What a recorder knows of one series so far. `summary` is present once the series ended. */
+export interface AttemptSeriesState {
+    readonly series: string;
+    /** The series' attempts, in order. */
+    readonly attempts: readonly AttemptRef[];
+    /**
+     * The series at a glance — the same value the runner stamps on `StageSnapshot.attemptSummary`, rebuilt from the
+     * records. Absent while the last record says `retry`: the series is in flight, or the run's signal cut its wait
+     * (no record follows; only the execution tree knows how it ended).
+     */
+    readonly summary?: AttemptSummary;
+}
+/**
+ * Per-series tallies, keyed by `series`, for the series that are evidence. `add` returns the series' state after
+ * the record, or `undefined` for a record that is not evidence (nothing to keep).
+ */
+export declare class AttemptSeriesBook {
+    private readonly bySeries;
+    add(record: AttemptRecord): AttemptSeriesState | undefined;
+    clear(): void;
+}

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

@@ -30,6 +30,7 @@
  *
  * Pinned by test/lib/recorder/hooks.test.ts (the `@ts-expect-error` probes).
  */
+import type { RunCorrelation } from '../attempt/types.js';
 import type { FlowRecorder } from '../engine/narrative/types.js';
 import type { ErrorEvent, ScopeRecorder } from '../scope/types.js';
 import type { EmitRecorder } from './EmitRecorder.js';
@@ -174,6 +175,12 @@ export declare const HOOKS: {
         };
         readonly executorMade: false;
     };
+    readonly onAttempt: {
+        readonly on: {
+            readonly flow: "FlowAttemptEvent";
+        };
+        readonly executorMade: false;
+    };
     readonly onStageRetry: {
         readonly on: {
             readonly flow: "FlowStageRetryEvent";
@@ -240,6 +247,8 @@ export interface FailureSite {
     readonly stageId: string;
     readonly runtimeStageId: string;
     readonly pipelineId: string;
+    /** The run's correlation, when the site's events carry one — the failure event carries it too. */
+    readonly correlation?: RunCorrelation;
 }
 /**
  * THE scope-channel `onError` event for a recorder that threw in `hook` — built in ONE place