footprintjs 10.0.1 → 10.2.0

package/dist/types/lib/{decide → filter}/evaluator.d.ts

@@ -1,13 +1,18 @@
 /**
- * decide/evaluator -- Prisma-style filter evaluator for decision rules.
+ * filter/evaluator -- Prisma-style filter evaluator for decision rules.
  *
  * Pure function. Takes a WhereFilter, a value getter, and a redaction checker.
  * Evaluates each condition, records the result, returns matched/conditions.
  *
  * All keys in the filter are ANDed (all must match for the rule to match).
  * Decoupled from ScopeFacade — receives callbacks, not scope.
+ *
+ * A LEAF module of its own (P2, 10.1): `decide()` (decide/) and the attempt rule table (attempt/decision.ts) share
+ * this one law, and neither may reach the other's dependencies through it. In decide/ it made `attempt/` reach
+ * `scope/` (decide.ts imports the scope runtime), so a `scope → attempt` edge — `scope.$call` — closed a module
+ * cycle.
  */
-import type { FilterCondition, WhereFilter } from './types.js';
+import type { FilterCondition, WhereFilter } from '../decide/types.js';
 /**
  * Evaluates a Prisma-style filter against scope values.
  *

package/dist/types/lib/ids/idempotencyKey.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ids/idempotencyKey.ts — the ONE format rule for an idempotency key (design §3.3, packet P3). A leaf: the attempt
+ * law (`attempt/effect.ts · admitIdempotencyKey`, a key a stage's rule or a `$call` gives) and the checkpoint decoder
+ * (`pause/record.ts`, a key a paused execution carries to its resume) both ask it, so a key a stored checkpoint
+ * smuggles in is held to the same rule as one the code made.
+ *
+ * 1–255 printable ASCII characters (`\x21`–`\x7e`), no space: a key travels in a request header
+ * (`Idempotency-Key`), so a CR/LF could forge one, and 255 is Stripe's limit, inside every header limit. The
+ * problem names the rule, never the value.
+ */
+/** The longest idempotency key. */
+export declare const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/** Why `value` is not an idempotency key, or `undefined` when it is one. */
+export declare function idempotencyKeyProblem(value: unknown): string | undefined;

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

@@ -13,12 +13,28 @@
  */
 import type { CommitPhase, EmitSourcePosition, UntrackedSource } from 'foottrace';
 import type { EventLog, SharedMemory } from 'foottrace/write';
+import type { AttemptContext, AttemptRecord, AttemptSummary, LateWrite } from '../attempt/types.js';
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import { type TerminalFailureContext, NativeFailureState } from '../errors/terminalFailure.js';
 import { type DiagnosticChannel, DiagnosticCollector } from './DiagnosticCollector.js';
 import type { FlowControlType, StageSnapshot } from './frameTypes.js';
 import type { RedactionVerdict } from './redaction.js';
 import { RedactionRule } from './redaction.js';
 import type { RunPolicy } from './runPolicy.js';
+/**
+ * How many call and observed attempt records one stage execution keeps (P2) — a stage that calls in a loop must
+ * not grow the execution tree without bound. The rest are counted (`StageSnapshot.attemptsDropped`) and still
+ * fired on `onAttempt`. A stage's OWN attempt records are never displaced: its policy's ceiling bounds them.
+ */
+export declare const MAX_CALL_RECORDS = 1000;
 export declare class StageContext {
+    #private;
+    /** @internal Ownership of an escaping failure. Shared only by sequential frames, never serialized. */
+    failureState: NativeFailureState;
+    /** @internal The native frame stamp, independent of mutable recorder event context. */
+    get failureIdentity(): NonNullable<TerminalFailureContext['stage']> | undefined;
+    /** @internal Stamped before observers; never inherited by another frame or persisted. */
+    bindFailureIdentity(runId: string, runtimeStageId: string): void;
     /**
      * The record half of this frame (`RecordFrame.ts`, L3, C3): the heap and,
      * when the run keeps them, the redacted mirror and the log; the address;
@@ -138,6 +154,41 @@ export declare class StageContext {
      * stages that never touch an untracked path pay nothing.
      */
     private _untrackedSources?;
+    /**
+     * The attempts of this frame's execution (10.1) — its own under the attempt runner, appended as each attempt ends
+     * (`FlowchartTraverser · executeStage`), and those of the calls it made (P2, {@link reportCallAttempt}) — read
+     * by {@link snapshotSelf}. Append-only
+     * evidence like `debug`: NOT cleared by {@link discardStaged} (the earlier attempts are the point) and never
+     * part of a commit bundle. Lazily allocated: a stage without a policy pays nothing.
+     */
+    private _attempts?;
+    /** The attempt series at a glance, stamped once when it ends. */
+    private _attemptSummary?;
+    /** Facts collected for this execution only; retry discards deliberately keep them. */
+    private _attention?;
+    /**
+     * The attempt now running (P1b) — set by `StageRunner` before the scope is built, so the facade can hand it out
+     * (`scope.$attempt()`) and fence its own attempt. Absent for a stage the attempt runner does not run.
+     */
+    private _attempt?;
+    /** The run's signal, for the attempt a stage outside the runner reports (attempt 1 of 1). */
+    private _runSignal?;
+    /** Every attempt up to this number has ENDED without an answer — its scope is fenced (0 = none). */
+    private _endedThrough;
+    /** Writes an attempt tried after it ended — dropped at the scope, kept here as names. Lazily allocated. */
+    private _lateWrites?;
+    /**
+     * Where a call's attempt records are reported (P2) — the engine's `onAttempt` for this stage execution, set by
+     * `FlowchartTraverser · executeStage` with the stage's own traversal context (and its correlation).
+     */
+    private _attemptReporter?;
+    /** Calls made so far, per stage attempt — the `k` of a call's series. Lazily allocated. */
+    private _callOrdinals?;
+    /** Per stage attempt, the signal its calls stop by (`callsEndedSignal`). Lazily allocated. */
+    private _callsEnded?;
+    /** Call and observed records kept on the frame, and those past {@link MAX_CALL_RECORDS}. */
+    private _callRecords;
+    private _attemptsDropped;
     /** Observer called after commit() — used by ScopeFacade to fire ScopeRecorder.onCommit. */
     private _commitObserver?;
     constructor(runId: string, name: string, stageId: string, sharedMemory: SharedMemory, branchId?: string, eventLog?: EventLog, isDecider?: boolean);
@@ -404,6 +455,8 @@ export declare class StageContext {
      *   reads them post-run for the execution-tree snapshot.
      */
     commit(phase?: CommitPhase): void;
+    /** Whether this frame has committed — a call's record arriving after it is late (P2, `ScopeFacade · call`). */
+    get committed(): boolean;
     /**
      * Throw away everything this stage has STAGED, without committing any of it.
      *
@@ -429,14 +482,81 @@ export declare class StageContext {
      *                    holds bare references — dropping it un-clones nothing);
      *  - `_untrackedSources` — the D2 honesty markers, released with the rest.
      *
-     * What is deliberately KEPT: `debug` (logs, metrics, errors, flow messages).
-     * Diagnostics are the append-only record of what every attempt did, and the
-     * retry feature's whole point is that the earlier attempts stay visible.
+     * What is deliberately KEPT: `debug` (logs, metrics, errors, flow messages)
+     * and the attempt records (10.1). Both are the append-only record of what
+     * every attempt did, and the retry feature's whole point is that the earlier
+     * attempts stay visible.
      *
      * No commit is recorded and no observer fires — a discarded attempt is not a
      * cursor stop, because from shared state's point of view it never happened.
      */
     discardStaged(): void;
+    /** Append one attempt's record — the attempt runner calls this as each attempt ends. */
+    recordAttempt(record: AttemptRecord): void;
+    /** Stamp the series' summary — once, when the runner ends the series. */
+    endAttempts(summary: AttemptSummary): void;
+    /** Reset only at the node's execution stamp, never between attempts. */
+    beginAttention(): void;
+    /** Delegate the explicit retained-error fact; attention owns validation of its proof. */
+    markStageFailure(): void;
+    /**
+     * The crash-safe record (10.1, P6): an attempt that ended is noted in the run's sink AT ONCE, beside this frame's
+     * log — so a process killed before the stage commits (mid-retry) still leaves every attempt that ended. The
+     * record is the one the tree keeps: frozen, `structuredClone`-safe, its error the SERVED form (no `raw`), so the
+     * note needs no second redaction pass. Without a sink the log does nothing (`EventLog · note`).
+     */
+    private noteAttempt;
+    /** The attempts of this execution so far, in order — its own and its calls'; `undefined` when there are none. */
+    get attempts(): readonly AttemptRecord[] | undefined;
+    /** The ended series' summary; `undefined` while it runs and without a policy. */
+    get attemptSummary(): AttemptSummary | undefined;
+    /** The attempt about to run (and the run's signal) — `StageRunner` sets both before it builds the scope. */
+    useAttempt(attempt: AttemptContext | undefined, runSignal: AbortSignal | undefined): void;
+    /** The attempt now running; `undefined` for a stage the attempt runner does not run. */
+    get attempt(): AttemptContext | undefined;
+    /** The run's signal, as `StageRunner` last saw it. */
+    get runSignal(): AbortSignal | undefined;
+    /**
+     * Attempt `attempt` ended without an answer: from now on its scope is fenced — a write, an emit or a read
+     * through it is refused (`ScopeFacade`). The runner calls this the moment the attempt's signal aborts.
+     */
+    endAttempt(attempt: number): void;
+    /** Whether attempt `attempt` has ended — its scope may no longer touch the stage. */
+    hasAttemptEnded(attempt: number): boolean;
+    /** Record a write an ended attempt tried — a name, never the value. Append-only evidence like the attempts. */
+    recordLateWrite(write: LateWrite): void;
+    /** This execution's own idempotency key may be made of a selected value (or was carried by a checkpoint). */
+    private _effectKeyTainted;
+    /** A touching `$call` with NO key started in this execution — the stage may not be re-run by a resume. */
+    private _keylessEffect;
+    /**
+     * Start an execution's side-effect bookkeeping (`FlowchartTraverser · executeStage`, before attempt 1) — reset,
+     * because a frame can be re-used by a later execution. `keyTainted`: the stage's own key may be made of a selected
+     * value, so a key a `$call` passes on (`$attempt().idempotencyKey`) is served the same way.
+     */
+    beginEffects(keyTainted: boolean): void;
+    get effectKeyTainted(): boolean;
+    /** A keyless touching `$call` started: an `interrupt()` after it would re-send it on resume (`StageRunner`). */
+    markKeylessEffect(): void;
+    get hasKeylessEffect(): boolean;
+    /** Where this execution's call records are reported — the engine sets it before the stage runs. */
+    useAttemptReporter(report: ((record: AttemptRecord, structuredError: StructuredErrorInfo | undefined) => void) | undefined): void;
+    /**
+     * The signal the calls of stage attempt `stageAttempt` run under besides its own (P2): aborted when that attempt is
+     * over — however it ended — and when the frame commits, so no call outlives the attempt that made it (no
+     * background retry, no wait, no listener left on the run's signal). Already aborted after the commit.
+     */
+    callsEndedSignal(stageAttempt: number): AbortSignal;
+    /** End the calls of `stageAttempt` (every attempt's when `undefined`) — `reason` when the attempt's signal gave one. */
+    private endCalls;
+    /** The next call's ordinal within stage attempt `stageAttempt`, 1-based (`attempt/call.ts · callSeries`). */
+    nextCallOrdinal(stageAttempt: number): number;
+    /**
+     * A call's (or an observed) attempt record: kept beside the stage's own attempts — the first
+     * {@link MAX_CALL_RECORDS}, the rest counted — and reported to the run's `onAttempt` either way. Like the stage's
+     * records, NOT cleared by {@link discardStaged}: a failed attempt's calls are evidence too.
+     */
+    reportCallAttempt(record: AttemptRecord, structuredError: StructuredErrorInfo | undefined): void;
     /**
      * Create (or return) this context's linked successor.
      *

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

@@ -0,0 +1,26 @@
+/** Engine-owned attention is collected with retained facts; snapshots only copy this bounded projection. */
+import type { Attention } from 'foottrace';
+import type { AttemptRecord, AttemptSummary } from '../attempt/types.js';
+/** One execution's ownership, pending summary, marks and omission accounting stay in this helper. */
+export declare class StageAttention {
+    private marks?;
+    private omitted;
+    private retryPossible;
+    private summary?;
+    private terminal?;
+    /** A new execution starts fresh; an attempt discard never calls this. No collection is reconstructed. */
+    begin(): void;
+    /** Called only after the frame retained this attempt. Raw error, target and decision payloads are never read. */
+    recordAttempt(record: AttemptRecord, owner: string): void;
+    recordSummary(summary: AttemptSummary): void;
+    /** A summary-only cut wait has no phantom final attempt; use its actual retained summary. */
+    private projectSummary;
+    /** Only the explicit retained stage-error path calls this; a diagnostic value never classifies itself. */
+    stageFailed(errors: unknown): void;
+    attemptDropped(): void;
+    /** Keep only bounded exact references; one slot is reserved to disclose omissions. */
+    append(attention: Attention): void;
+    missing(): void;
+    /** Copy already collected bounded marks, never an attempt array, diagnostic bag or execution tree. */
+    snapshot(): readonly Attention[];
+}

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

@@ -47,6 +47,14 @@ export declare function firstDifferingPath(before: unknown, after: unknown, pref
  * path names it); this text names the stage the handle came from.
  */
 export declare function deadFrameMessage(stageName: string, runtimeStageId: string | undefined, key: string): string;
+/**
+ * The refusal raised in an attempt that has ENDED (P1b) — timed out, aborted or
+ * failed — when the function behind it touches its scope anyway. The engine
+ * stopped waiting for it; whatever it does now would land beside a later
+ * attempt (or after the stage's commit), so it is refused. A write or emit is
+ * recorded on the stage (`StageSnapshot.lateWrites`) before this is thrown.
+ */
+export declare function lateAttemptMessage(stageName: string, series: string, attempt: number, key: string): string;
 /**
  * The warning text for a key the stage WROTE after changing, in place, the
  * committed value it had read before its first write (copy-on-write, 9.29.0).

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

@@ -7,9 +7,13 @@
  * in the record's `types.ts` until C6; the record names nothing outside itself now
  * (`RECORD_FILES`, scripts/layering.config.cjs), so they sit beside the frame that writes them.
  *
+ * A retried stage's node also carries its attempts (`attempts`, `attemptSummary` — the attempt leaf's types, L0).
+ *
  * A `StageSnapshot` is an `ExecutionTree` (`types.ts`), the shape the record's readers walk:
  * `commitStops`, `tagStops` and `keysReadFromExecutionTree` take one.
  */
+import type { Attention } from 'foottrace';
+import type { AttemptRecord, AttemptSummary, LateWrite } from '../attempt/types.js';
 import type { RetentionPolicy } from '../capture/policies.js';
 /** Types of control flow decisions captured by the execution engine. */
 export type FlowControlType = 'next' | 'branch' | 'children' | 'selected' | 'subflow' | 'loop';
@@ -93,6 +97,40 @@ export type StageSnapshot = {
     metrics: Record<string, unknown>;
     evals: Record<string, unknown>;
     flowMessages?: FlowMessage[];
+    /**
+     * Every attempt of this execution, in order — when it started, how long it took, how it ended, and the
+     * retry-or-stop decision that followed (`AttemptRecord`): the stage's own under its retry policy, a `timeoutMs`
+     * or a run deadline (10.1, `kind: 'stage'`), and those of the calls it made through `scope.$call` and the
+     * outside attempts it reported through `observed()` (P2, `kind: 'call'` / `'observed'`, the first 1000 —
+     * `StageContext · MAX_CALL_RECORDS`). Absent when there are none. The commit log never carries attempts: a
+     * retried stage is still ONE bundle.
+     */
+    attempts?: readonly AttemptRecord[];
+    /**
+     * Call and observed attempt records this execution made past the first 1000 — counted, not kept (each still
+     * fired `onAttempt`). Absent when none were dropped.
+     */
+    attemptsDropped?: number;
+    /**
+     * The series at a glance — counts per outcome, and how it ended. Stamped when the series ends: absent while it
+     * is still running (a snapshot taken mid-stage) and without a policy.
+     */
+    attemptSummary?: AttemptSummary;
+    /**
+     * Writes (and emits) an attempt tried AFTER it had ended — timed out, aborted or failed — in the order they came
+     * (P1b). Each was dropped at the scope, so none reached the stage's buffer, its commit or a recorder; this is
+     * the record that they were tried — the first 100 (`MAX_LATE_WRITES`). An abandoned function can keep running
+     * after the run ended, so the list can grow after a snapshot was taken. Names only, never values. Absent when
+     * there were none.
+     */
+    lateWrites?: readonly LateWrite[];
+    /**
+     * Fixed-reason marks collected as this execution runs. Absent when no fact needs attention.
+     * Attempt evidence uses canonical Foottrace attempt IDs. Summary-only and stage-error proof resolves within THIS node
+     * through attemptSummary, errors:stageExecutionError or attemptsDropped. Quality marks are read-time recorder work.
+     * Marks retain no error text, values, targets or idempotency keys; omitted proof is disclosed as not-collected.
+     */
+    attention?: readonly Attention[];
     next?: StageSnapshot;
     children?: StageSnapshot[];
 };

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

@@ -224,6 +224,18 @@ export declare class RedactionRule {
      * channel) applies on top. Clear values keep their identity.
      */
     retainDiagnostic(address: readonly string[], value: unknown): unknown;
+    /**
+     * An idempotency key as records serve it (P3, design §6). The key is a VALUE, and the documented way to make one
+     * is from the input or the state (`order-${args.orderId}`) — so it is selected by its NAME (the diagnostic entry
+     * `{ idempotencyKey }`: a state rule of that name, or `policy.diagnostics` at `logs.idempotencyKey`) AND by its
+     * SOURCES, conservatively, the subflow-mapper taint law's way: when the input it may be derived from holds a
+     * selected key at any depth, or the stage read a selected value before making it (`selectedReads`), it is served
+     * whole as the placeholder. Never value equality. An inert rule never reads it.
+     */
+    retainIdempotencyKey(key: string, sources: {
+        readonly input?: unknown;
+        readonly selectedReads?: number;
+    }): string;
     /**
      * Retain flow-message text (`flowMessages.description` / `.rationale`): text
      * the engine composes has no name of its own, so no state selector reaches

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

@@ -114,6 +114,8 @@ export declare class PauseSignal extends Error {
      * (`completeExecution`), or both carried over for a queued sibling.
      */
     private _pausedExecution?;
+    /** The paused execution's idempotency key (P3) — a touching stage's, stamped once at the stage boundary. */
+    private _idempotencyKey?;
     constructor(data: unknown, stageId: string, pausedBy?: 'interrupt');
     get subflowPath(): readonly string[];
     /** The paused execution (its run and `[path/]stageId#N`), once both are known. */
@@ -125,6 +127,13 @@ export declare class PauseSignal extends Error {
      * carries both (it paused in an EARLIER run).
      */
     stampExecution(runtimeStageId: string, runId?: string): void;
+    /**
+     * The idempotency key the paused execution ran under (P3) — a touching stage's. It rides the checkpoint so the
+     * resume re-runs the stage (or its `resumeFn`) under the SAME key: the input its rule read does not cross a
+     * resume. First stamp wins.
+     */
+    get idempotencyKey(): string | undefined;
+    stampIdempotencyKey(key: string | undefined): void;
     /**
      * Name the run for every pause on this signal that paused in it — this one
      * and its queued siblings that do not already carry a run (a sibling raised
@@ -213,6 +222,8 @@ export interface PendingPause {
     readonly pausedBy?: 'interrupt';
     /** Which execution the sibling paused in (as `pausedExecution`, 9.37.0) — kept so its own resume links to it. */
     readonly pausedExecution?: PausedExecution;
+    /** The idempotency key the sibling's execution ran under (as `idempotencyKey`, 10.1). */
+    readonly idempotencyKey?: string;
 }
 /**
  * Returned by a pausable stage's execute/resume function to signal pause.
@@ -277,6 +288,14 @@ export interface FlowchartCheckpoint {
      * which then resumes without a link.
      */
     readonly pausedExecution?: PausedExecution;
+    /**
+     * The idempotency key the paused execution ran under (10.1) — present only when the paused stage `touches` an
+     * outside system with a key rule. `resume()` re-runs the stage (or runs its `resumeFn`) under THIS key, never a
+     * recomputed one: the input the rule read does not cross a resume, and a different key on the re-run would make
+     * the outside system apply the effect twice. A real value, like `sharedState` — no redaction policy touches the
+     * checkpoint. A malformed one is refused at `resume()`.
+     */
+    readonly idempotencyKey?: string;
     /** Path through subflows to the paused stage (e.g., ['sf-payment', 'sf-validation']).
      *  Empty array when paused at the top level. */
     readonly subflowPath: readonly string[];

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

@@ -7,6 +7,9 @@
  *
  * Dependency: type-only imports from engine/ and scope/ (zero runtime cost).
  */
+import type { AttemptContext, CallOptions, RetryPolicy } from '../attempt/types.js';
+import type { FlowChart } from '../builder/types.js';
+import type { DetachDriver, DetachHandle } from '../detach/types.js';
 import type { ExecutionEnv } from '../engine/types.js';
 import type { ScopeRecorder } from '../scope/types.js';
 export interface ReactiveTarget {
@@ -27,6 +30,10 @@ export interface ReactiveTarget {
     getValueSilent?(key?: string): unknown;
     getArgs<T = Record<string, unknown>>(): T;
     getEnv(): Readonly<ExecutionEnv>;
+    /** The attempt the stage function runs in — its signal, its cap and the time left (P1b). */
+    getAttempt(): AttemptContext;
+    /** A call to an outside system on the attempt runner, recorded under this stage (P2). */
+    call<R>(target: string, fn: (attempt: AttemptContext) => Promise<R> | R, policy?: RetryPolicy, options?: CallOptions): Promise<R>;
     attachScopeRecorder(recorder: ScopeRecorder): void;
     detachScopeRecorder(recorderId: string): void;
     getScopeRecorders(): ScopeRecorder[];
@@ -36,8 +43,8 @@ export interface ReactiveTarget {
     addMetric(name: string, value: unknown): void;
     addEval(name: string, value: unknown): void;
     emitEvent(name: string, payload?: unknown): void;
-    detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
-    detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
+    detachAndJoinLater(driver: DetachDriver, child: FlowChart, input?: unknown): DetachHandle;
+    detachAndForget(driver: DetachDriver, child: FlowChart, input?: unknown): void;
 }
 export interface ScopeMethods {
     $getValue(key: string): unknown;
@@ -48,6 +55,31 @@ export interface ScopeMethods {
     $read(dotPath: string): unknown;
     $getArgs<T = Record<string, unknown>>(): T;
     $getEnv(): Readonly<ExecutionEnv>;
+    /**
+     * The attempt this stage function runs in (P1b): `attempt` / `of`, the `signal` to pass to `fetch` and SDK
+     * calls (it aborts at the attempt's cap, the run's deadline, or a cancellation), and `timeLeftMs()` — the
+     * milliseconds before the run's deadline (`Infinity` without one; reading it with a deadline marks the stage's
+     * commit `untrackedSources: ['env']`). A stage with no retry policy and no deadline is attempt 1 of 1.
+     */
+    $attempt(): AttemptContext;
+    /**
+     * A call to an outside system, made inside this stage (P2): `fn` runs on the attempt runner under `policy`
+     * (none = ONE attempt — still recorded), and every attempt is an `AttemptRecord` of kind `'call'` on this
+     * stage's node and on `onAttempt`, with its timing, outcome, category and decision. It runs under this stage
+     * attempt's time and signal — pass `t.signal` on. `target` is a NAME from code (1–128 characters, no control
+     * character), never a value. A malformed call (target, `fn`, policy) or one from an attempt that already ended
+     * THROWS at the call, synchronously, like every scope refusal — it is the stage's code breaking its contract; a
+     * call that runs and fails REJECTS with its last attempt's own error. A call that changes an outside system
+     * declares it in `options` (`{ touches, idempotencyKey }`, P3): a touching call that may retry needs a key, every
+     * record carries its `effect`, and a call that ends without an answer after any attempt of unknown effect rejects
+     * with `UnknownEffectError`.
+     *
+     * ```typescript
+     * const quote = await scope.$call('stripe.quotes.create', (t) => stripe.quotes.create(body, { signal: t.signal }),
+     *   { attempts: 3, timeoutMs: 10_000 });
+     * ```
+     */
+    $call<R>(target: string, fn: (attempt: AttemptContext) => Promise<R> | R, policy?: RetryPolicy, options?: CallOptions): Promise<R>;
     $debug(key: string, value: unknown): void;
     $log(value: unknown): void;
     $error(key: string, value: unknown): void;
@@ -129,8 +161,8 @@ export interface ScopeMethods {
      * ```
      */
     $emit(name: string, payload?: unknown): void;
-    $detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
-    $detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
+    $detachAndJoinLater(driver: DetachDriver, child: FlowChart, input?: unknown): DetachHandle;
+    $detachAndForget(driver: DetachDriver, child: FlowChart, input?: unknown): void;
     /**
      * Stop the current execution context.
      *

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

@@ -0,0 +1,141 @@
+import type { FlowAttemptEvent, FlowDecisionEvent, FlowPauseEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent } from '../engine/narrative/types.js';
+import type { AttemptAggregate, AttemptDecisionRow, AttemptQuery, AttemptRecorderOptions, AttemptStorageStats, AttemptStore, PhysicalAttemptRow } from './attemptMetricsTypes.js';
+export declare class AttemptRecorder implements FlowRecorder {
+    readonly id: string;
+    private readonly rows;
+    private readonly logical;
+    private readonly starts;
+    private reads;
+    private readonly pending;
+    private readonly exemplars;
+    private readonly maxRows;
+    private readonly maxPending;
+    private readonly timeoutMs;
+    private readonly store?;
+    private failed;
+    private dropped;
+    private omittedRows;
+    constructor(options?: AttemptRecorderOptions);
+    onRunStart(event: FlowRunEvent): void;
+    onRunEnd(event: FlowRunEvent): void;
+    onPause(event: FlowPauseEvent): void;
+    onRunFailed(event: FlowRunFailedEvent): void;
+    private end;
+    onAttempt(event: FlowAttemptEvent): void;
+    onDecision(event: FlowDecisionEvent): void;
+    private collect;
+    storage(): AttemptStorageStats;
+    flush(): Promise<AttemptStorageStats>;
+    byTarget(): AttemptAggregate['byTarget'];
+    byRun(): AttemptAggregate['byRun'];
+    slowest(target: string, limit?: number): import("./attemptMetricsTypes.js").AttemptMetricRef[];
+    series(series: string, runId?: string): {
+        attempts: PhysicalAttemptRow[];
+        decisions: AttemptDecisionRow[];
+    };
+    aggregate(supplied?: AttemptQuery): Promise<AttemptAggregate>;
+    private readStored;
+    toSnapshot(): {
+        name: string;
+        data: {
+            byTarget: Map<string, import("./attemptMetricsTypes.js").AttemptStats>;
+            byRun: Map<string, import("./attemptMetricsTypes.js").AttemptRunStats>;
+        };
+        meta: {
+            projection: string;
+            exemplars: number;
+            rows: number;
+            maxRows: number;
+            storage: AttemptStorageStats;
+            workTime: string;
+        };
+    };
+    toOTel(): {
+        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;
+                })[];
+            }[];
+        }[];
+    };
+    /** Clear completed local projections; active/paused evidence and bounded ownership survive executor auto-clear. */
+    clear(): void;
+}
+/** Bounded reference adapter for tests/local use; apps supply their own database adapter. */
+export declare function memoryStore(options?: {
+    readonly maxRows?: number;
+}): AttemptStore & {
+    stats(): {
+        rows: number;
+        omittedRows: number;
+    };
+};

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

@@ -27,6 +27,17 @@
  *      completing consumes its slot via `onError`, so the post-fan-out
  *      convergence stage is never misattributed as a branch entry.
  *
+ *   3. attempt stops (10.1) — `onAttempt`: a stage whose retry series STOPPED
+ *      (it gave up, or a later attempt paused or was aborted; the shared
+ *      predicate `recorder/attemptSeries.ts · isRetryEvidence`) made a decision of its
+ *      own — the retry-or-stop decision, in the shape `decide()` produces. It
+ *      is recorded beside the deciders as `kind: 'attempt-stop'`
+ *      (`getDecisions()`, `getAttemptStop(id)`), `chosen: 'stop'`, the stop
+ *      reason as its `ruleLabel`. It is NOT a branch entry: a control edge in
+ *      `causalChain` links a stage to ANOTHER execution that governed it, and
+ *      the stop governs the stage itself — so `lookup` is unchanged, and a
+ *      reader walking a failed stage reads the stop off its decision record.
+ *
  *   `lookup(runtimeStageId)` then walks the ancestor chain from the stage
  *   upward; the first ancestor (or the stage itself) registered as a
  *   branch entry yields its governing decider — the NEAREST decision.
@@ -55,9 +66,15 @@ import { causalChain } from 'foottrace';
  */
 import type { ControlDependency, ControlDepLookup } from 'foottrace';
 import type { DecisionEvidence, SelectionEvidence } from '../decide/types.js';
-import type { FlowDecisionEvent, FlowErrorEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent } from '../engine/narrative/types.js';
+import type { FlowAttemptEvent, FlowDecisionEvent, FlowErrorEvent, FlowRecorder, FlowSelectedEvent, FlowStageEvent } from '../engine/narrative/types.js';
 /** One recorded decision/selection event (RFC-003 D5). */
 export interface ControlDecisionRecord {
+    /**
+     * `'attempt-stop'` for a stage's own retry-or-stop decision that STOPPED its series (10.1) — then
+     * `deciderRuntimeStageId` is the stage's execution, `chosen` is `'stop'`, `evidence` the attempt's decision and
+     * `ruleLabel` the stop reason. Absent for a decider / selector.
+     */
+    kind?: 'attempt-stop';
     /** runtimeStageId of the decider/selector execution step. */
     deciderRuntimeStageId: string;
     /** Chosen branch display name (decider) or selected names (selector). */
@@ -100,6 +117,7 @@ export declare class ControlDepRecorder implements FlowRecorder {
     private lastRunId?;
     constructor(options?: ControlDepRecorderOptions);
     onDecision(event: FlowDecisionEvent): void;
+    onAttempt(event: FlowAttemptEvent): void;
     onSelected(event: FlowSelectedEvent): void;
     onStageExecuted(event: FlowStageEvent): void;
     /**
@@ -118,8 +136,24 @@ export declare class ControlDepRecorder implements FlowRecorder {
     lookup(runtimeStageId: string): ControlDependency | undefined;
     /** The lookup as a bare function — plug into `causalChain(..., { controlDeps })`. */
     asLookup(): ControlDepLookup;
-    /** All decisions recorded for the current run, in event order. */
+    /** The attempt-stop decision of a stage execution whose retry series stopped, if it did. */
+    getAttemptStop(runtimeStageId: string): ControlDecisionRecord | undefined;
+    /** All decisions recorded for the current run, in event order — deciders, selectors and attempt stops. */
     getDecisions(): ControlDecisionRecord[];
+    /**
+     * Current-run control evidence for the native snapshot. Project only the
+     * stage identities collected during traversal; never walk the execution tree.
+     * Parentless roots cannot have a governing control edge.
+     */
+    toSnapshot(): {
+        name: string;
+        data: {
+            decisions: ControlDecisionRecord[];
+            controlDeps: {
+                [k: string]: ControlDependency;
+            };
+        };
+    };
     /** Reset all state (also happens automatically on runId change). */
     clear(): void;
     /** Convention 4: a new runId means a new run — reset transient state. */