footprintjs 10.0.1 → 10.2.0

package/dist/types/index.d.ts

@@ -29,6 +29,15 @@ export { flowChart, FlowChartBuilder, flowChartSelector } from './lib/builder/in
 export type { BranchChart, ParallelForEachConfig, RetryPolicy } from './lib/builder/index.js';
 /** @category Quick Start — build-time observer (twin of FlowRecorder) */
 export type { StructureDeciderCompleteEvent, StructureEdgeAddedEvent, StructureEdgeKind, StructureLoopEdgeAddedEvent, StructureRecorder, StructureStageAddedEvent, StructureStageTaggedEvent, StructureSubflowMountedEvent, } from './lib/builder/index.js';
+/**
+ * @category Time Budget
+ *
+ * `timeBudget(chart)` — the slowest a chart can take, from its declared retry policies (`attempts × timeoutMs` plus
+ * the waits, summed along the slowest path), and every stage that makes a path unbounded, by name. `.budget(ms)`
+ * declares the caller's contract; `build()` refuses a chart that cannot keep it. Also `chart.timeBudget()`.
+ */
+export type { BudgetAssumptions, BudgetStep, TimeBudgetOptions, TimeBudgetReport, UnboundedReason, UnboundedStage, } from './lib/budget/index.js';
+export { timeBudget } from './lib/budget/index.js';
 /** @category Quick Start */
 export type { TypedStageFunction } from './lib/builder/typedFlowChart.js';
 /** @category Quick Start */
@@ -39,10 +48,59 @@ export { narrative } from './recorders.js';
 export type { DecideRule, DecisionEvidence, DecisionResult, DefaultBranch, FilterOps, RuleEvidence, SelectionEvidence, SelectionResult, WhenClause, WhereFilter, } from './lib/decide/index.js';
 /** @category Decision Branching */
 export { decide, select } from './lib/decide/index.js';
+/** @category Errors */
+export type { TerminalFailureContext } from './lib/errors/terminalFailure.js';
+/**
+ * @category Attempts
+ *
+ * One `AttemptRecord` per attempt of a stage with a declared `retry` policy, a `timeoutMs`, or a run deadline —
+ * timing, outcome, failure category, and the retry-or-stop decision as `DecisionEvidence` — on the stage's
+ * execution-tree node (`StageSnapshot.attempts` / `attemptSummary`) and on `FlowRecorder.onAttempt`.
+ * A call a stage makes through `scope.$call` is recorded the same way (kind `'call'`), and so is an SDK's own retry
+ * an adapter reports through `observed()` (`ObservedAttempt`, kind `'observed'`). `AttemptContext` is what
+ * `scope.$attempt()` returns, and what a call's function gets (the attempt's signal, the time left, `observed`);
+ * `LateWrite` is a write (or call) an ended attempt tried (`StageSnapshot.lateWrites`). A stage that changes an
+ * outside system declares it (`StageTouches`, `.touches()`), and a call does (`CallOptions`): every attempt then
+ * carries its `AttemptEffect`, and the key rule is handed an `IdempotencyKeyContext` once per execution.
+ */
+export type { AttemptCategory, AttemptContext, AttemptEffect, AttemptError, AttemptInputs, AttemptKind, AttemptNext, AttemptOptions, AttemptOutcome, AttemptReason, AttemptRecord, AttemptSummary, CallOptions, IdempotencyKeyContext, LateWrite, ObservedAttempt, StageTouches, UnknownEffectInit, } from './lib/attempt/index.js';
+/**
+ * @category Attempts
+ *
+ * An attempt by name (`series` + `attempt`) and per-outcome counts — what recorder rows hold of attempts.
+ */
+export type { AttemptOutcomeCounts, AttemptRef } from './lib/recorder/attemptSeries.js';
+/**
+ * @category Attempts
+ *
+ * `attempt()` — the attempt runner for code that is not a stage (records go to its `onAttempt`); `errorCategory`
+ * — the one failure classifier (seven fixed categories); `retryRules` — the one retry rule table, as `decide()`
+ * rules; the attempt contract's two errors.
+ */
+export { attempt, AttemptTimeoutError, errorCategory, retryRules, UnknownEffectError } from './lib/attempt/index.js';
+/**
+ * @category Correlation
+ *
+ * The run's correlation (10.1): `env.traceparent` (W3C, parsed strictly) or `env.traceId` + `env.operationId`
+ * become ONE frozen `RunCorrelation` per run — on `getSnapshot().correlation`, every flow event's
+ * `traversalContext.correlation` and every scope and emit event's `correlation`. `parseTraceparent` /
+ * `formatTraceparent` are the W3C codec; a refused header throws `TraceparentError` with a named `reason`.
+ */
+export type { ParsedTraceparent, RunCorrelation, TraceparentFields, TraceparentRefusal } from './lib/attempt/index.js';
+export { formatTraceparent, parseTraceparent, TraceparentError } from './lib/attempt/index.js';
 /** @category Run */
 export type { RunResult } from './lib/runner/index.js';
 /** @category Run */
 export type { FlowChartExecutorOptions } from './lib/runner/index.js';
+/**
+ * The crash-safe record (10.1): the executor's `sink` option, its accounting on `getSnapshot().sink`,
+ * `executor.flushRecord()`'s result, and the error a run with `onFailure: 'fail'` rejects with. The port
+ * (`RecordSink`, `memorySink`) is `foottrace/write`'s; the file adapter is `footprintjs/sinks`.
+ * @category Run
+ */
+export type { RecordFlushResult, RecordSinkFailureMode, RecordSinkFlushMode, RecordSinkOption, RecordSinkOptions, RecordSinkStats, } from './lib/runner/index.js';
+/** @category Run */
+export { RecordSinkError } from './lib/runner/index.js';
 /**
  * The four observability dials `FlowChartExecutorOptions` inherits.
  * @category Run
@@ -101,7 +159,7 @@ export { hasEmitRecorderMethods, hasFlowRecorderMethods, hasRecorderMethods, isF
  */
 export type { EmitEvent, EmitRecorder } from './lib/recorder/index.js';
 /** @category Observe — Flow */
-export type { FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowStageRetryEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, FlowThrottledEvent, ResumeLink, TraversalContext, } from './lib/engine/index.js';
+export type { FlowAttemptEvent, FlowBreakEvent, FlowDecisionEvent, FlowErrorEvent, FlowForkEvent, FlowLoopEvent, FlowNextEvent, FlowRecorder, FlowRunEvent, FlowRunFailedEvent, FlowSelectedEvent, FlowStageEvent, FlowStageRetryEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, FlowThrottledEvent, ResumeLink, TraversalContext, } from './lib/engine/index.js';
 /** @category Observe — Flow */
 export type { CombinedNarrativeEntry } from './lib/engine/index.js';
 /**
@@ -114,7 +172,7 @@ export type { NarrativeFormatter } from './lib/engine/index.js';
 /** @category Observe — Flow */
 export { NarrativeFlowRecorder } from './lib/engine/index.js';
 /** @category Observe — Flow */
-export type { ManifestEntry } from './lib/engine/index.js';
+export type { ManifestAttemptRow, ManifestEntry } from './lib/engine/index.js';
 /** @category Observe — Flow */
 export { ManifestFlowRecorder } from './lib/engine/index.js';
 /** @category Observe — Flow */
@@ -223,4 +281,6 @@ export { extractErrorInfo, formatErrorInfo } from './lib/engine/index.js';
  * `enableDevMode` for the full list and usage example.
  */
 export { disableDevMode, enableDevMode, isDevMode } from './lib/devMode.js';
+export type { RetryLoopCall, RetryLoopDecision, RetryLoopIdentity } from './lib/attempt/retryLoopTypes.js';
+export type { RetryLoopContext, RetryLoopOptions, RetryLoopState } from './lib/builder/retryLoop.js';
 export { stringifySnapshot } from './lib/runner/stringifySnapshot.js';

package/dist/types/lib/attempt/anySignal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * attempt/anySignal.ts — one signal that aborts when ANY of its inputs does.
+ *
+ * The attempt runner gives each attempt its own signal: the run's signal (cancellation, the deadline) composed
+ * with the attempt's own time cap. `AbortSignal.any` does this natively, but not in every browser this library
+ * runs in (design §3.1), so the composition is ours: small, and leak-free — every listener it adds to an input
+ * is removed the moment it aborts or is disposed, so a long run of attempts leaves nothing on the run's signal.
+ */
+/** A composed signal and the one call that releases its inputs. */
+export interface ComposedSignal {
+    readonly signal: AbortSignal;
+    /** Remove every listener this composition added to its inputs. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Compose `inputs` (undefined entries ignored): the result aborts with the reason of the first input to abort,
+ * or at once with the reason of an input that already has. Call `dispose()` when the attempt ends.
+ */
+export declare function anySignal(inputs: ReadonlyArray<AbortSignal | undefined>): ComposedSignal;

package/dist/types/lib/attempt/call.d.ts

@@ -0,0 +1,88 @@
+/**
+ * attempt/call.ts — a call made INSIDE a stage attempt: `scope.$call(target, fn, policy?)` (design §3.6, §3.8,
+ * packet P2).
+ *
+ * The same loop as a stage's retry (`runAttempts`, law 1), kind `'call'`, its `target` on every record — and a
+ * record even for a single call (`attempts: 1`): timing and outcome evidence with no retry. Its series is the
+ * call level of foottrace's attempt-id grammar ({@link callSeries}).
+ *
+ * THE LAW — a call lives within the attempt that made it. The host (the stage's scope) hands it that attempt's
+ * signal and its end as the call's deadline, so the call is capped by the time its stage attempt has left, and is
+ * cut when the stage attempt is cut (a time limit, so `'timeout'`; a cancellation, so `'aborted'`); and an `ended`
+ * signal that aborts when the attempt is over however it ended (it returned, threw, or its frame committed), so a
+ * call never outlives it. Following the P1b fence:
+ *   - the record of a call attempt cut BY its stage attempt's own abort lands — the cut is evidence;
+ *   - any other record that arrives once the stage attempt is over is REFUSED: noted by name (`host.refused`), never
+ *     kept, never fired; the call stops (its in-flight attempt is cut, a wait ends) and no further attempt of an
+ *     outside call starts — and the library-made rejection of such an orphan never surfaces as an unhandled one;
+ *   - a call never starts under a signal already aborted, nor past its deadline while that signal is still due (a
+ *     busy event loop fires timers late): no attempt, no record — the host's signal is its ONE deadline source.
+ * What the call's function does after its attempt ended cannot be trapped — it should RETURN its answer, not write
+ * the stage's scope (the scope's own fence still refuses a write from an ended stage attempt).
+ *
+ * A LEAF of the engine (L5): the host is a port, so nothing here names the scope.
+ */
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import type { EffectTarget } from './effect.js';
+import type { AttemptContext, AttemptRecord, ObservedAttempt, RetryPolicy } from './types.js';
+/**
+ * The series of the `ordinal`-th call (1-based) made during attempt `stageAttempt` of the stage execution
+ * `runtimeStageId`: `<runtimeStageId>@<n>.<k>` — so the id of the call's attempt `m` is `<series>@<m>`, foottrace's
+ * `buildAttemptId(runtimeStageId, n, { ordinal: k, attempt: m })` (design §3.4). Written here, in this one place,
+ * until the engine adopts foottrace 1.1.0's codec (P6); the bytes are the grammar's.
+ */
+export declare function callSeries(runtimeStageId: string, stageAttempt: number, ordinal: number): string;
+/** What the attempt that makes a call gives it — the scope implements it. */
+export interface CallHost {
+    /**
+     * The call's series ({@link callSeries}) — asked once, only when the call starts, so a call refused before it
+     * starts takes no ordinal and leaves no gap.
+     */
+    openSeries(): string;
+    /**
+     * The stage attempt's signal: the run's cancellation, the run's deadline and the attempt's own cap. When given, it
+     * is the call's ONE deadline source — it must abort at {@link deadline}, with a time-limit reason
+     * (`deadline.ts · markTimeLimit` / `deadlineReason`); the call arms no timer of its own.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * When the stage attempt must end, epoch ms — the call's deadline, capping each attempt by the time left. Absent
+     * for an uncapped attempt. Without a {@link signal}, the call arms the one timer that ends it here.
+     */
+    readonly deadline?: number;
+    /** The clock (default `Date.now`). */
+    readonly now?: () => number;
+    /**
+     * Aborts when the attempt that makes the call is over — however it ended — and when its frame commits: the call
+     * stops (its in-flight attempt is cut, a wait ends, no attempt follows) and its records are refused. No call
+     * outlives the attempt that made it.
+     */
+    readonly ended?: AbortSignal;
+    /**
+     * May a record of the call land on the stage now? `cut`: the call attempt was ended BY the stage attempt's own
+     * end, so its record is the evidence of that cut.
+     */
+    admits(cut: boolean): boolean;
+    /** The served form of an attempt's error — the run's redaction rule. */
+    serve(error: unknown): StructuredErrorInfo;
+    /** A record that may land: onto the stage, and the run's `onAttempt`. */
+    report(record: AttemptRecord, structuredError: StructuredErrorInfo | undefined): void;
+    /** A record that may not — the call outlived the attempt that made it. A name is noted; nothing is kept. */
+    refused(): void;
+    /**
+     * The outside system the call touches and its key (P3) — admitted at the call (`effect.ts · callTouches`), the
+     * recorded key served under the run's rule. Every record then carries its `effect`, and a series ended without an answer after an attempt of unknown
+     * effect rejects with `UnknownEffectError`.
+     */
+    readonly effect?: EffectTarget;
+    /** An observed report made through the call's own attempt context (`ended`: that call attempt was over). */
+    observe(report: ObservedAttempt, at: {
+        readonly attempt: number;
+        readonly ended: boolean;
+    }): void;
+}
+/**
+ * Run `fn` as the call `target` under `policy` (already admitted — `policy.ts · admitCallPolicy`) for `host`.
+ * Resolves with the answer, or rejects with the last attempt's own error.
+ */
+export declare function runCall<T>(target: string, fn: (attempt: AttemptContext) => Promise<T> | T, policy: RetryPolicy, host: CallHost): Promise<T>;

package/dist/types/lib/attempt/category.d.ts

@@ -0,0 +1,37 @@
+/**
+ * attempt/category.ts — `errorCategory`, the ONE failure classifier (design §3.9).
+ *
+ * Seven fixed values, so every recorder — the narrative, the metric layer, an agent's own — breaks failures down
+ * the same way; a recorder never invents a category of its own. Borrowed from agentfootprint's
+ * `classifyRetryReason` and widened, so its decorators adopt this one rather than keep theirs.
+ *
+ * Category is EVIDENCE, never policy: the default `retryOn` retries every category. A chart that wants "never
+ * retry a permanent failure" says so: `retryOn: (e) => errorCategory(e) !== 'permanent'`.
+ *
+ * Precedence — what the failure LOOKED like wins over what it declares:
+ *   1. the attempt's own timer (outcome `'timeout'`, or our `AttemptTimeoutError`)  → timeout
+ *   2. the run's signal ended it (outcome `'aborted'`)                              → unknown
+ *   3. status 429, or a declared `retryAfterMs` / `retryAfterSeconds`               → rate-limited
+ *   4. status 5xx                                                                   → server
+ *   5. status 401 / 403                                                             → auth
+ *   6. any other 4xx                                                                → permanent
+ *   7. `retryable: false`, or a validation error                                    → permanent
+ *   8. a transport failure (a socket code on the error or its cause, a fetch
+ *      `TypeError`, an `AbortError` / `TimeoutError` that was not the run's)        → network
+ *   9. anything else                                                                → unknown
+ *
+ * A status is a NUMBER (`status` or `statusCode`); a numeric string is not read as one. Total: a value whose
+ * reads throw (a hostile Proxy) is `'unknown'`, never a second throw from an error path.
+ */
+import type { AttemptCategory, AttemptOutcome } from './types.js';
+/**
+ * The category of an attempt's failure. `outcome` is how the attempt ended (default `'failed'`): it decides
+ * `'timeout'` (the attempt's own timer) and `'unknown'` (the run's signal) before the error is read.
+ */
+export declare function errorCategory(error: unknown, outcome?: AttemptOutcome): AttemptCategory;
+/**
+ * @internal Terminal ownership preserves a producer's known category. An
+ * unresolved effect is unknown, never the category of its physical cause.
+ * This does not rewrite historical attempt categories or re-read a known one.
+ */
+export declare function terminalCategory(error: unknown, known?: AttemptCategory): AttemptCategory;

package/dist/types/lib/attempt/correlation.d.ts

@@ -0,0 +1,95 @@
+/**
+ * attempt/correlation.ts — the run's correlation: the W3C `traceparent` codec and the ONE resolution of the env
+ * into a `RunCorrelation` (design docs/design/2026-10-time-and-failure-evidence.md §3.4, packet P4).
+ *
+ * THREAT MODEL. A `traceparent` comes from whoever sent the request. So:
+ *   - it is read STRICTLY to the W3C Trace Context grammar (`version-traceid-parentid-flags`, lowercase hex) and
+ *     anything else is refused by a NAMED reason (`TraceparentError.reason`) — the message never repeats the
+ *     header, and the error holds no copy of it;
+ *   - what the run keeps is the canonical form of what was parsed (`formatTraceparent`), never the received
+ *     bytes — a future version's tail is dropped;
+ *   - it is correlation only: a name the record carries so a run can be found from a trace. Nothing in the
+ *     library treats it as identity or authorisation.
+ *
+ * W3C forward compatibility: a version other than `00` (and never `ff`) is read by its first four fields; a
+ * longer header must continue with `-`. Version `00` is exactly 55 characters. A header longer than
+ * {@link MAX_HEADER_LENGTH} is refused before it is scanned.
+ */
+import type { RunCorrelation } from './types.js';
+/** Why a `traceparent` was refused — a NAME, so a caller can branch on it without reading a message. */
+export type TraceparentRefusal = 'not-a-string' | 'length' | 'version' | 'characters' | 'zero-trace-id' | 'zero-parent-id';
+/** A parsed `traceparent`: the W3C trace-id, the parent-id (the caller's unit of work), and its trace-flags. */
+export interface ParsedTraceparent {
+    /** 32 lowercase hex, not all zeros. */
+    readonly traceId: string;
+    /** The W3C parent-id — 16 lowercase hex, not all zeros. The library's word for it is "operation". */
+    readonly operationId: string;
+    /** Bit 0 of `flags`. */
+    readonly sampled: boolean;
+    /** The trace-flags byte as received — 2 lowercase hex — so a re-format keeps every bit (W3C level 2's random). */
+    readonly flags: string;
+}
+/**
+ * What `formatTraceparent` writes from. `flags` (2 lowercase hex) is the trace-flags byte, `'00'` when absent;
+ * `sampled`, when given, sets or clears its bit 0.
+ */
+export interface TraceparentFields {
+    readonly traceId: string;
+    readonly operationId: string;
+    readonly sampled?: boolean;
+    readonly flags?: string;
+}
+/** The longest header read at all (a future version may append fields; nothing legitimate is near this). */
+export declare const MAX_HEADER_LENGTH = 256;
+/** A `traceparent` the library will not read. The header itself is never in the message or on the error. */
+export declare class TraceparentError extends Error {
+    readonly reason: TraceparentRefusal;
+    constructor(reason: TraceparentRefusal);
+}
+/**
+ * Parse a W3C `traceparent` header strictly. Returns a frozen {@link ParsedTraceparent}; throws a
+ * {@link TraceparentError} naming the first rule the header breaks.
+ *
+ * @example
+ * parseTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+ * // { traceId: '4bf92f3577b34da6a3ce929d0e0e4736', operationId: '00f067aa0ba902b7', sampled: true, flags: '01' }
+ */
+export declare function parseTraceparent(header: unknown): ParsedTraceparent;
+/**
+ * Write a version-00 `traceparent` — for an outbound call that continues this run's trace. Both ids must be W3C
+ * ids and `flags` a byte of 2 lowercase hex (refused by name otherwise, like a parse); `sampled`, when given,
+ * sets or clears bit 0 of the flags. `formatTraceparent(parseTraceparent(h))` is `h` for any valid version-00 `h`.
+ *
+ * @example
+ * formatTraceparent({ traceId, operationId: mySpanId, sampled: true }); // '00-<traceId>-<mySpanId>-01'
+ */
+export declare function formatTraceparent(fields: TraceparentFields): string;
+/** The env fields correlation reads — structural, so this L5 file names nothing of the engine's `ExecutionEnv`. */
+export interface CorrelationEnv {
+    readonly traceparent?: unknown;
+    readonly traceId?: unknown;
+    readonly operationId?: unknown;
+}
+/**
+ * Admit a leg's env ONCE (called by `FlowChartExecutor · run` / `resume` before anything moves): a single
+ * own-property snapshot of it — every getter runs once, nothing is read off the prototype — and the correlation
+ * resolved from that snapshot. In the snapshot the stages see (`$getEnv()`), `traceparent` is exactly
+ * `correlation.traceparent` — the canonical header of the effective ids, or no key when the run's correlation has
+ * none — so stage code never holds the received bytes, nor a header naming another trace than the record.
+ * `env` is `undefined` exactly when none was given.
+ */
+export declare function admitRunEnv<E extends object>(env: E | undefined): {
+    readonly env: E | undefined;
+    readonly correlation: RunCorrelation | undefined;
+};
+/**
+ * The ONE resolution of a leg's correlation from its env. Only OWN fields count. `traceparent` is parsed once (a
+ * bad header refuses the leg — explicit ids do not rescue it); explicit `traceId` / `operationId` win over the
+ * header's and must be 1–256 printable ASCII characters (refused by field name, never echoed); an empty one is
+ * no id. Everything of the header — its parent-id as the operation, `sampled`, `traceparent` — rides only while
+ * the trace IS the header's, and `traceparent` is rebuilt from the EFFECTIVE ids with the header's flags
+ * (omitted when the operation is not a W3C parent-id), so the record never names one trace and files or
+ * propagates another's. Returns `undefined` when there is no trace id at all — and refuses
+ * an `operationId` with no trace to belong to.
+ */
+export declare function resolveCorrelation(env: CorrelationEnv | undefined): RunCorrelation | undefined;

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

@@ -0,0 +1,44 @@
+/**
+ * attempt/deadline.ts — what the run's deadline IS, to everything that reads time (design §3.1, law 3).
+ *
+ * The deadline is one number, epoch milliseconds (`env.deadline`); the executor arms the run's signal to abort when
+ * it passes (`runner/deadline.ts · armRun`). Reaching it is NOT a cancellation: an attempt the deadline cuts short
+ * timed out (it had no answer in the time it had — law 4), and the series stops `no-time-left`, not `aborted`. So
+ * the reason the run's signal aborts with at the deadline is BRANDED here, and the attempt runner tells the two
+ * apart by the brand — never by the message, never by the clock.
+ *
+ * The brand is a module-private WeakSet: an ordinary `Error` (same message, same name a run with `timeoutMs` always
+ * rejected with), recognisable only by identity.
+ */
+/** The reason the run's signal aborts with when its deadline passes — an `Error`, branded as the deadline's. */
+export declare function deadlineReason(message: string): Error;
+/**
+ * Brand `reason` as a time limit — what an attempt's own cap aborts with (P2). An attempt's cap is the deadline of
+ * every call made inside it (`attempt/call.ts`), so a call it cuts ran out of time: `'timeout'`, never `'aborted'`.
+ * The run's own signal never aborts with it, so a stage attempt reads nothing new.
+ */
+export declare function markTimeLimit<T extends object>(reason: T): T;
+/** Whether `reason` is the run's deadline or an attempt's cap — a time limit, not a cancellation. */
+export declare function isDeadlineReason(reason: unknown): boolean;
+/** Whether the signal aborted for a reason OTHER than a time limit — a cancellation. */
+export declare function isCancelled(signal: AbortSignal | undefined): boolean;
+/** A deadline as the engine reads one: a finite number (epoch ms), else none. */
+export declare function readDeadline(value: unknown): number | undefined;
+/**
+ * `setTimeout` for any delay: a delay past the host's limit is waited in chunks, so a 30-day deadline does not fire
+ * in a millisecond. Returns the one call that cancels it.
+ */
+export declare function setLongTimeout(fn: () => void, ms: number): () => void;
+/** Whether `value` is an AbortSignal (structurally — a signal from another realm counts). */
+export declare function isAbortSignal(value: unknown): value is AbortSignal;
+/** A signal that aborts at a deadline (or with its input), and the one call that releases both. */
+export interface ArmedDeadline {
+    readonly signal: AbortSignal | undefined;
+    dispose(): void;
+}
+/**
+ * Compose `signal` with a timer that aborts at `deadline` (epoch ms) with a branded {@link deadlineReason} — so the
+ * attempt runner's reading holds: the signal it is handed aborts at the deadline, as the run's does (`armRun`). A
+ * deadline already past aborts at once; without a deadline the signal is handed back as it is.
+ */
+export declare function armDeadline(signal: AbortSignal | undefined, deadline: number | undefined, message: string, now?: () => number): ArmedDeadline;

package/dist/types/lib/attempt/decision.d.ts

@@ -0,0 +1,52 @@
+/**
+ * attempt/decision.ts — the ONE retry rule table and the runner's evidence builder (design §3.1, §3.8, law 9).
+ *
+ * `retryRules(policy)` is the retry-or-stop decision as ordinary `decide()` rules over `AttemptInputs`, first
+ * match wins, default `retry` ("retryable"):
+ *
+ *   1  outcome = ok                    → done  succeeded
+ *   2  outcome = paused                → stop  paused
+ *   3  aborted = true                  → stop  aborted        (the run's signal — the attempt's outcome stays its own)
+ *   4  attempt ≥ of                    → stop  exhausted
+ *   5  retryOn = false                 → stop  declined       (a function rule: it shows the verdict it saw)
+ *   6  timeLeftAfterWaitMs ≤ 0         → stop  no-time-left
+ *      default                         → retry retryable
+ *
+ * Each rule's `label` IS the reason it names, so `reason` is a projection of the evidence, never a second
+ * vocabulary. The ceiling is `attempt/policy.ts · attemptCeiling`, the one reading the engine and the runner
+ * share.
+ *
+ * `decideAttempt` evaluates that table WITHOUT a scope (the runner has none — `decide()` needs a registered
+ * one) and builds the evidence `decide()` would build: the filter rows come from `decide()`'s own evaluator
+ * (`filter/evaluator.ts · evaluateFilter`), the function rows and the first-match loop mirror
+ * `decide/decide.ts` field for field and key for key. A property test pins that both paths give equal evidence
+ * for equal inputs (test/lib/attempt/property).
+ *
+ * Inputs are READ, one key at a time, only when a rule reaches them — so the user's `retryOn` and `backoffMs`
+ * run exactly when a retry needs them, as they did before the record existed.
+ */
+import type { DecideRule, DecisionEvidence } from '../decide/types.js';
+import type { AttemptInputs, AttemptNext, AttemptReason, RetryPolicy } from './types.js';
+/** The table's default: no rule stopped the series, so it retries. */
+export declare const RETRY_DEFAULT: Readonly<{
+    readonly branch: "retry";
+    readonly label: "retryable";
+}>;
+/**
+ * The retry rule table for `policy` — six `decide()` rules, then {@link RETRY_DEFAULT}. The ceiling is the
+ * whole number of attempts the policy allows, never fewer than one (`attemptCeiling`): a ceiling of `NaN` or
+ * `Infinity` cannot make rule 4 unreachable.
+ */
+export declare function retryRules(policy: Pick<RetryPolicy, 'attempts'>): DecideRule<AttemptInputs>[];
+/** A decision: the evidence, and its compact projection. */
+export interface AttemptDecision {
+    readonly evidence: DecisionEvidence;
+    readonly next: AttemptNext;
+    readonly reason: AttemptReason;
+}
+/**
+ * Evaluate `rules` (a `retryRules` table) over `read` — first match wins — and build the evidence `decide()`
+ * would record with the default {@link RETRY_DEFAULT}. `read(key)` returns one input; it is called only for the
+ * keys the evaluated rules touch, in rule order.
+ */
+export declare function decideAttempt(rules: readonly DecideRule<AttemptInputs>[], read: (key: string) => unknown): AttemptDecision;

package/dist/types/lib/attempt/effect.d.ts

@@ -0,0 +1,76 @@
+/**
+ * attempt/effect.ts — side-effect safety (design §3.3, packet P3): the ONE reading of what an attempt did to an
+ * outside system, and the ONE rule for a touching target.
+ *
+ *   - `touchesProblem` — the build law, asked at every door a touching declaration enters: the builder
+ *     (`FlowChartBuilder · applyTouches` / `applyRetryPolicy`), the traverser for a StageNode a stage returns at run
+ *     time (`FlowchartTraverser · admitDynamicNodes`), and the stage itself (`FlowchartTraverser · executeStage`, for
+ *     a chart edited after `build()`). A touching target that may retry without an idempotency key is refused: a
+ *     retry of a non-idempotent effect without one can apply it twice.
+ *   - `callTouches` — the same law for `scope.$call(target, fn, policy, { touches, idempotencyKey })`.
+ *   - `admitIdempotencyKey` — the key's format: 1–255 printable ASCII characters, no space. It travels in a request
+ *     header (`Idempotency-Key`), so a control character could forge one; the refusal names the field, never the
+ *     value.
+ *   - `effectOf` — `ok → 'applied'`; a failure whose error declares `effect: 'none'` → `'none'`; anything else →
+ *     `'unknown'`. A timeout is the absence of an answer (law 4), so it is never `'none'`.
+ *   - `unknownEffectError` — what a series that ends without an answer after ANY attempt of unknown effect fails
+ *     with, in place of the attempt's own error (its `cause`).
+ *   - `interruptProblem` — a keyless touching stage may not be re-run by an `interrupt()` resume.
+ */
+import { UnknownEffectError } from './errors.js';
+import type { AttemptEffect, AttemptOutcome, AttemptRecord, RetryPolicy, StageTouches } from './types.js';
+export { MAX_IDEMPOTENCY_KEY_LENGTH } from '../ids/idempotencyKey.js';
+/**
+ * What a touching runner series is told (`AttemptRunOptions.effect`): the system, the REAL key the attempts are made
+ * under, and the key as records carry it (the run's served form; the real one when no rule applies).
+ */
+export interface EffectTarget {
+    readonly system: string;
+    readonly idempotencyKey?: string;
+    readonly recordedKey?: string;
+}
+/**
+ * Why a touching declaration is refused, or `undefined` when it is admitted: `touches` must be `{ system,
+ * idempotencyKey? }` with `system` a name and the key rule a function; and a target that may retry (`retry`'s
+ * ceiling above 1) must declare the key rule.
+ */
+export declare function touchesProblem(touches: unknown, retry: Pick<RetryPolicy, 'attempts'> | undefined): string | undefined;
+/** `value` as an idempotency key (`ids/idempotencyKey.ts`, the one rule), or a `TypeError` that names `where`. */
+export declare function admitIdempotencyKey(where: string, value: unknown): string;
+/**
+ * A `$call`'s side-effect declaration, admitted: `undefined` when it touches nothing; otherwise the system and the
+ * key, refused with a `TypeError` naming `where` when malformed, when a key comes without a system, or when the
+ * call may retry with no key — before anything is sent.
+ */
+export declare function callTouches(where: string, options: unknown, policy: Pick<RetryPolicy, 'attempts'>): {
+    readonly system: string;
+    readonly idempotencyKey?: string;
+} | undefined;
+/** What an attempt that ended `outcome` (with `error`, when it failed) did to the outside system. */
+export declare function effectOf(outcome: AttemptOutcome, error: unknown): AttemptEffect;
+/**
+ * What a touching series fails with when any of its attempts left the effect unknown — never the attempt's own error,
+ * which a caller would read as a failure and retry. The key is the RECORDED one: under a redaction rule that names
+ * it, the error carries the placeholder, as every record does.
+ */
+export declare function unknownEffectError(target: EffectTarget, record: AttemptRecord, cause: unknown): UnknownEffectError;
+/** The key as records carry it: the served form when the caller gave one, else the key itself. */
+export declare function recordedKeyOf(target: EffectTarget): string | undefined;
+/** The runner's refusal of a touching series that may retry with no key — the law, at the last door. */
+export declare function refuseKeylessRetry(target: EffectTarget, attempts: number): void;
+/**
+ * Why a touching stage may not be RE-RUN by an `interrupt()` resume, or `undefined` when it may (P3). A resume
+ * re-runs the stage's function from its top — a second attempt of its effect — so the law that refuses a keyless
+ * retry refuses a keyless re-run too. Asked when the stage interrupts (`StageRunner`) and when a checkpoint is
+ * resumed (`runner/resume.ts · planResume`, for a checkpoint made by another version of the chart).
+ */
+export declare function interruptProblem(touches: StageTouches | undefined): string | undefined;
+/**
+ * The stand-in's declaration on a resume (P3): the paused stage's system, answering the key its checkpoint carried —
+ * the OPERATIONAL value, real (checkpoints are exempt from redaction by law). It is marked, so the run serves it
+ * like a key of unknown sources: under any state rule the records carry the placeholder (`isCarriedTouches`) — the
+ * resumed leg no longer holds the input the key was made of, so it cannot tell whether the key was masked.
+ */
+export declare function carriedTouches(system: string, key: string): StageTouches;
+/** The declaration answers a key a checkpoint carried ({@link carriedTouches}). */
+export declare function isCarriedTouches(touches: unknown): boolean;

package/dist/types/lib/attempt/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * attempt/errors.ts — the errors the attempt contract throws (design §3.3).
+ *
+ * - `AttemptTimeoutError` — the attempt's OWN timer ended it (`RetryPolicy.timeoutMs` / the run's deadline). A
+ *   timeout is the absence of an answer, not a failure of the outside system (law 4); `errorCategory` reads it
+ *   as `'timeout'`.
+ * - `UnknownEffectError` — a side-effecting target's last attempt ended with no answer, so nobody knows whether
+ *   the effect happened. "Reconcile, do not retry blindly" is on the error, not in prose.
+ *
+ * The idempotency key is a VALUE: it rides the error as a field (a redaction rule selects it by name) and is
+ * never spelled in a message.
+ */
+/** The attempt's own time cap ran out before it answered. */
+export declare class AttemptTimeoutError extends Error {
+    /** The attempt that ran out of time, 1-based. */
+    readonly attempt: number;
+    /** The cap it ran under, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(attempt: number, timeoutMs: number, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** What an `UnknownEffectError` names. */
+export interface UnknownEffectInit {
+    /** The outside system the stage touches — a name, never a value. */
+    readonly system: string;
+    /** The key the effect was attempted under — a value, kept as a field and never put in the message. */
+    readonly idempotencyKey?: string;
+    /** How many attempts ran. */
+    readonly attempts: number;
+    /** The last attempt's own error. */
+    readonly cause?: unknown;
+}
+/** A side-effecting target's last attempt ended with no answer: whether the effect happened is unknown. */
+export declare class UnknownEffectError extends Error {
+    readonly system: string;
+    /** Absent (not `undefined`) when no key was given — `declare`, so no class field is emitted for it. */
+    readonly idempotencyKey?: string;
+    readonly attempts: number;
+    constructor(init: UnknownEffectInit);
+}

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

@@ -0,0 +1,18 @@
+/**
+ * attempt/ — one runner, one record: every attempt the library runs is an `AttemptRecord` with the
+ * retry-or-stop decision that followed it (design docs/design/2026-10-time-and-failure-evidence.md).
+ *
+ * Public: the record's vocabulary, the one failure classifier, the one rule table, the two errors, and `attempt()`
+ * — the runner for code that is not a stage (P2). The loop itself (`runAttempts`), `runCall`, the evidence builder
+ * and `anySignal` are the engine's. `RetryPolicy` is declared in
+ * `./types.ts` and published through the builder's barrel, where it always was.
+ */
+export { errorCategory } from './category.js';
+export type { ParsedTraceparent, TraceparentFields, TraceparentRefusal } from './correlation.js';
+export { formatTraceparent, parseTraceparent, TraceparentError } from './correlation.js';
+export { retryRules } from './decision.js';
+export type { UnknownEffectInit } from './errors.js';
+export { AttemptTimeoutError, UnknownEffectError } from './errors.js';
+export type { AttemptOptions } from './standalone.js';
+export { attempt } from './standalone.js';
+export type { AttemptCategory, AttemptContext, AttemptEffect, AttemptError, AttemptInputs, AttemptKind, AttemptNext, AttemptOutcome, AttemptReason, AttemptRecord, AttemptSummary, CallOptions, IdempotencyKeyContext, LateWrite, ObservedAttempt, RunCorrelation, StageTouches, } from './types.js';

package/dist/types/lib/attempt/name.d.ts

@@ -0,0 +1,21 @@
+/**
+ * attempt/name.ts — the ONE rule for a name an attempt record carries (design §3.6, threat model, packet P2): the
+ * target of a `$call` / `attempt()`, a standalone series, and an observed report's target and source.
+ *
+ * A target is a NAME from code — `'stripe.quotes.create'` — never from a model and never a value. It rides every
+ * record, narrative line, recorder row and metric key exactly as given, so a name is refused unless it is a string
+ * of 1–{@link MAX_NAME_LENGTH} characters, not blank, with no control (C0, DEL, C1), format (zero-width, bidi
+ * overrides), surrogate, line/paragraph-separator, private-use or noncharacter code point:
+ *   - an empty or blank name names nothing;
+ *   - an overlong one is a value, or a flood of one;
+ *   - a control or separator character forges a narrative line or a log record, and a bidi override hides what a
+ *     line says.
+ * The refusal names the FIELD, never the value (P4's precedent): a rejected name may be exactly what must not be
+ * echoed. A `TypeError`, because a malformed name is the caller's code breaking its contract.
+ */
+/** The longest name an attempt record carries. */
+export declare const MAX_NAME_LENGTH = 128;
+/** Why `value` is not a name, or `undefined` when it is one. */
+export declare function attemptNameProblem(value: unknown): string | undefined;
+/** `value` as a name, or a `TypeError` that names `where` and `field` (never the value). */
+export declare function admitAttemptName(where: string, field: string, value: unknown): string;