footprintjs 10.0.1 → 10.2.0

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

@@ -0,0 +1,66 @@
+/**
+ * attempt/observed.ts — an attempt the library did NOT run: an outside system's own retry (an SDK's), reported by an
+ * adapter through `AttemptContext.observed` (design §3.6, packet P2). Same record shape, kind `'observed'`.
+ *
+ * WHY: the incident behind this design was four 40 s attempts inside an SDK that the record called "one stage, one
+ * error". The best fix is one loop — the SDK's retries off, the call under `scope.$call`. Where an SDK must keep its
+ * retries, its adapter reports each one here, so the record says what happened rather than nothing.
+ *
+ * THREE LAWS.
+ *   - A report is read, never trusted. Only the named fields are read, each ONCE (a getter cannot answer twice);
+ *     a name is held to the one name rule (`name.ts`); numbers must be what they say. Anything else on the
+ *     object — a request body, headers — is never read, so it can never reach a record ({@link readObservedReport}).
+ *   - The error is served under the run's redaction rule (the owner's `serve`), like every attempt's error; the
+ *     record keeps its named fields, and no hook is handed the adapter's error object (`raw` is dropped: the
+ *     library never threw it, and an SDK error can carry its request).
+ *   - An observed attempt never changes control flow. Its `decision` is the ONE rule table read over what the
+ *     report states, under the default policy (every error retryable, no deadline) — the library's reading of the
+ *     SDK's attempt, never the SDK's own decision, which the record cannot know. A report without `of` stands for
+ *     the SDK's whole call: it is its last attempt, so a failure reads `exhausted`.
+ *
+ * SERIES. Reports are grouped by {@link ObservedSeriesBook}, owned by whoever owns the attempt they were reported
+ * on: a growing attempt number continues its target's series; a number that does not grow opens a new one (the
+ * SDK started another call).
+ */
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import type { AttemptOutcome, AttemptRecord } from './types.js';
+/** A report as read: every field once, validated, defaults applied. */
+export interface ObservedReport {
+    readonly target: string;
+    readonly source: string;
+    readonly attempt: number;
+    readonly of?: number;
+    readonly outcome: Exclude<AttemptOutcome, 'paused'>;
+    readonly durationMs: number;
+    readonly startedAt?: number;
+    readonly error?: unknown;
+}
+/**
+ * Read an adapter's report: the named fields only, each once. A malformed report is refused with a `TypeError`
+ * naming the field (never its value).
+ */
+export declare function readObservedReport(report: unknown): ObservedReport;
+/** What turns a report into a record — the owner's series, clock and served-error rule. */
+export interface ObservedRecordInit {
+    readonly series: string;
+    readonly now: () => number;
+    readonly serve: (error: unknown) => StructuredErrorInfo;
+}
+/** The frozen record of a report, and the served error (with `raw`) the `onAttempt` hook carries. */
+export declare function observedRecord(report: ObservedReport, init: ObservedRecordInit): {
+    record: AttemptRecord;
+    structuredError?: StructuredErrorInfo;
+};
+/** How many distinct target/source pairs one attempt's book remembers — past it, each report opens its own series. */
+export declare const MAX_OPEN_OBSERVED_SERIES = 256;
+/**
+ * Groups one attempt's observed reports into series. A report continues the open series of its target and source
+ * while its attempt number grows; otherwise it opens a new one through `open` (the owner's next call-level series).
+ * Bounded: it remembers at most {@link MAX_OPEN_OBSERVED_SERIES} names.
+ */
+export declare class ObservedSeriesBook {
+    private readonly openSeries;
+    private readonly open;
+    constructor(openSeries: () => string);
+    seriesFor(report: Pick<ObservedReport, 'target' | 'source' | 'attempt'>): string;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * attempt/policy.ts — the ONE reading of a `RetryPolicy`'s ceiling, and the ONE rule for a valid policy.
+ *
+ * `attemptCeiling` is how many attempts a policy allows. Three readers ask it, so they can never disagree about a
+ * stage: the engine's gate (`FlowchartTraverser · executeStage` — does this stage retry at all?), the runner
+ * (`runAttempts` — every record's `of`) and the rule table (`retryRules` — rule 4's threshold).
+ *
+ * `retryPolicyProblem` says why a declared policy is refused. Two doors ask it, with the same words: the builder
+ * at build (`FlowChartBuilder · applyRetryPolicy`), and the traverser for a StageNode a stage returns at run time
+ * (`FlowchartTraverser · admitDynamicNodes`), which the builder never saw.
+ */
+import type { RetryPolicy } from './types.js';
+/**
+ * The attempts a policy allows: its whole number (a fraction is floored, as the 9.15 loop read it), and never
+ * fewer than one. Anything that is not a finite number of at least one — `NaN`, `Infinity`, `0`, a negative, a
+ * non-number — is `1`: a broken ceiling never loops.
+ */
+export declare function attemptCeiling(attempts: unknown): number;
+/**
+ * Why `retry` is refused, or `undefined` when it is a valid policy: `attempts` must be a whole number ≥ 1, a
+ * declared `timeoutMs` a finite number > 0, and a declared `maxBackoffMs` a finite number ≥ 0. `attempts: 1` is
+ * valid on purpose — a policy declared but switched off (or, with a `timeoutMs`, a timeout with no retry).
+ */
+export declare function retryPolicyProblem(retry: Pick<RetryPolicy, 'attempts' | 'timeoutMs' | 'maxBackoffMs'>): string | undefined;
+/**
+ * The ceiling a policy puts on ONE wait (`maxBackoffMs`): a finite number ≥ 0, else none. The runner caps every
+ * wait at it (`waitAfter`), and the static budget check counts each wait at it — one reading, so the check's bound
+ * is the runner's law.
+ */
+export declare function backoffCeilingMs(maxBackoffMs: unknown): number | undefined;
+/** A wait the policy's `backoffMs` answered (already defended, `resolveBackoffMs`), capped at its declared ceiling. */
+export declare function cappedWaitMs(waitMs: number, maxBackoffMs: unknown): number;
+/**
+ * The cap a policy puts on one attempt: a finite number > 0, else none. The one reading the engine's gate and the
+ * runner share (the builder refuses any other declared value, `retryPolicyProblem`).
+ */
+export declare function attemptTimeoutMs(timeoutMs: unknown): number | undefined;
+/** The policy of a call made with none: one attempt — still recorded (a single call is evidence too). */
+export declare const SINGLE_CALL: RetryPolicy;
+/**
+ * A `$call` / `attempt()` policy as the caller handed it: absent means {@link SINGLE_CALL}; anything else must be a
+ * valid `RetryPolicy` (`retryPolicyProblem`) or it is refused with a `TypeError` naming `where` — at the call,
+ * before anything runs.
+ */
+export declare function admitCallPolicy(where: string, policy: unknown): RetryPolicy;

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

@@ -0,0 +1,11 @@
+/**
+ * attempt/record.ts — how an `AttemptRecord` holds what it holds: frozen to its leaves, and an error only as the run
+ * SERVES it, named fields only. One owner, so a record the runner makes (`runner.ts`) and a record an adapter
+ * reports (`observed.ts`) can never differ in what they keep.
+ */
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import type { AttemptError } from './types.js';
+/** The record's copy of a served error: its named fields only — never `raw`, never an extra own key. */
+export declare function recordedError(served: StructuredErrorInfo): AttemptError;
+/** Freeze a record built of plain objects and arrays, to its leaves. */
+export declare function freezeDeep<T>(value: T): T;

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

@@ -0,0 +1,18 @@
+/** Internal one-call port: the builder declares logical identity; the call owner stamps it before dispatch. */
+import type { RetryLoopCall } from './retryLoopTypes.js';
+import type { AttemptRecord } from './types.js';
+export interface RetryLoopCallPort {
+    readonly identity: RetryLoopCall;
+    readonly record: (record: AttemptRecord) => void;
+}
+export declare function registerRetryLoopCall(target: object, port: RetryLoopCallPort): () => void;
+/** Claimed once, so nested calls made by the user's callback do not inherit the outer call's logical identity. */
+export declare function takeRetryLoopCall(target: object): RetryLoopCallPort | undefined;
+export interface RetryLoopBudget {
+    readonly passes?: number;
+    readonly role: 'callback' | 'control' | 'wait';
+    readonly timeoutMs?: number;
+    readonly waitMs?: number;
+}
+export declare function declareRetryLoopBudget(node: object, budget: RetryLoopBudget): void;
+export declare function retryLoopBudget(node: object): RetryLoopBudget | undefined;

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

@@ -0,0 +1,18 @@
+/** Logical identity of an explicit retry workflow. Physical attempt identities remain unchanged. */
+export interface RetryLoopIdentity {
+    readonly id: string;
+    readonly series: string;
+    readonly attempt: number;
+    readonly of: number;
+}
+/** The role of one physical call inside a logical pass. */
+export interface RetryLoopCall extends RetryLoopIdentity {
+    readonly phase: 'attempt' | 'reconcile';
+}
+/** The explicit chart decision, after reconciliation; never rewrites a physical call's outcome. */
+export interface RetryLoopDecision extends RetryLoopIdentity {
+    readonly effect: 'applied' | 'none' | 'unknown';
+    readonly reconciled: boolean;
+    readonly next: 'retry' | 'done' | 'stop';
+    readonly reason: string;
+}

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

@@ -0,0 +1,157 @@
+/**
+ * attempt/runner.ts — `runAttempts`, THE retry loop (design §3.1, law 1: one runner, one record).
+ *
+ * Runs a function under a policy and records every try: one frozen `AttemptRecord` per attempt, carrying its
+ * timing, outcome, failure category and the retry-or-stop decision (`attempt/decision.ts`), and one
+ * `AttemptSummary` when the series ends. The engine's stage retry (`FlowchartTraverser · executeStage`) runs on
+ * it; later packets run in-stage calls and standalone `attempt()` on it too.
+ *
+ * The loop, per attempt n — for a failed attempt, the 9.15 loop's order, step for step:
+ *
+ *   start → run(n) → outcome (ok | failed | aborted [it threw the run's abort reason] | paused [a PauseSignal])
+ *         → decide over the inputs, first match wins (`retryRules`) — retryOn is asked here (rule 5)
+ *         → the run's signal aborted inside retryOn? decide again: rule 3 stops the series here, before the
+ *           discard and before backoffMs, as the 9.15 abort check did
+ *         → retry: between(n) — the discard — and THEN backoffMs(n), the wait's length
+ *         → the error's served form and category, read after retryOn and backoffMs ran → the record
+ *         → onEnd(summary)                                               only when the series ends here
+ *         → onAttempt(record, served error)
+ *         → done: return the value · stop: rethrow the attempt's OWN error
+ *         → retry: onRetry(n, of, delay, served error) → wait (cut short by the signal) → aborted? stop
+ *
+ * WHAT IT PRESERVES (the 9.15 loop's behaviour, moved here unchanged): the function runs the same number of
+ * times; `retryOn` is asked only for a failed, non-final attempt; `backoffMs` only when a retry follows, after
+ * the discard; a throwing predicate is "do not retry", a throwing or non-finite backoff is "no wait"; a pause is
+ * never retried; the attempt's own error is rethrown, never a wrapper; and a failed attempt's order —
+ * `retryOn` → the abort check → the discard (`between`) → `backoffMs` → the served error → the retry event →
+ * the wait → the abort check. So an abort inside `retryOn` stops before the discard and never asks `backoffMs`;
+ * an abort inside `backoffMs` comes after the discard, still fires the retry event, then ends at the wait; and
+ * the served error shows what `retryOn` did to the thrown value. The one difference: when the run's signal has
+ * ALREADY aborted as the attempt fails, the series stops without asking `retryOn` (the abort decides first —
+ * rule 3 before rule 5).
+ *
+ * WHAT IT ADDS: the record and the summary. A record is frozen to its leaves and holds only clone-safe data —
+ * the error as the run SERVES it (`serve`, the redaction rule's form) without `raw`. The hook gets the served
+ * `StructuredErrorInfo` whole, `raw` included, as `onStageRetry` always has. A record never rewrites what the
+ * attempt did: an attempt that threw its own error is `failed`, with its category, even when the run aborted
+ * around it — the abort is the series' stop reason (`reason: 'aborted'`); a throwing `retryOn` is `declined`
+ * with `retryOnThrew: true`, apart from a real `false`.
+ *
+ * TIME (P1b). Each attempt runs under `min(policy.timeoutMs, time left before options.deadline)` and gets an
+ * `AttemptContext` — its signal, composed from the run's and its own cap's timer (`LiveAttempt`). The cap's timer
+ * aborts with an `AttemptTimeoutError`; the run's deadline aborts the run's signal with a branded reason
+ * (`attempt/deadline.ts`). Either way the attempt is `'timeout'`, never `'aborted'`: the deadline is not a
+ * cancellation, so rule 3 does not match and rule 6 (`timeLeftAfterWaitMs ≤ 0`) stops a series whose next wait
+ * would outlast it. Under a deadline rule 6 needs the wait's length, so `backoffMs(n, error)` is asked DURING the
+ * decision — before the discard; without one the 9.15 order above holds unchanged. No attempt starts at or past
+ * the deadline: a wait the deadline cut ends the series `no-time-left`, recording no further attempt.
+ *
+ * THE FENCE. The moment an attempt ends without an answer — its signal aborts (synchronously, before any listener
+ * the function added) or it throws — `onAbandon(n)` fires once, and the engine closes that attempt's scope: the
+ * function may still be running, and nothing it does afterwards may land beside a later attempt.
+ *
+ * ONE async frame with ONE await per attempt: the engine relies on that to keep a retried stage's microtask
+ * shape, so parallel siblings settle in the order they always did. The engine races the attempt's signal itself,
+ * at the stage boundary (`raced: true`); any other caller gets the race here, so the series never waits on an
+ * attempt past its cap.
+ *
+ * CALLS (P2). The same loop runs a call a stage makes (`attempt/call.ts · runCall`, kind `'call'`, its `target` on
+ * every record) and the standalone `attempt()`. An attempt's cap is the DEADLINE of every call made inside it, so
+ * the cap's reason is branded a time limit (`attempt/deadline.ts · markTimeLimit`): a call cut by its stage
+ * attempt's cap timed out, it was not cancelled. `attemptEndsAt` says when an attempt must end; an `interrupt()`
+ * thrown inside a call is a pause, like a `PauseSignal` — never retried.
+ */
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import type { EffectTarget } from './effect.js';
+import type { AttemptCategory, AttemptContext, AttemptKind, AttemptRecord, AttemptSummary, ObservedAttempt, RetryPolicy } from './types.js';
+/** What a series reports, and the engine's between-attempt step. Every member is optional. */
+export interface AttemptRunOptions {
+    /** The series every record names — for a stage attempt, its execution's `runtimeStageId`. */
+    readonly series: string;
+    /** Default `'stage'`. */
+    readonly kind?: AttemptKind;
+    /** The outside target every record names — a call's (`$call`, `attempt()`); absent for a stage attempt. */
+    readonly target?: string;
+    /**
+     * The run's signal. Once it has aborted (other than at the deadline), rule 3 stops the series
+     * (`reason: 'aborted'`); it cuts a wait short. An attempt that threw its reason is recorded `'aborted'` — or
+     * `'timeout'` when the reason is the deadline's (`attempt/deadline.ts`).
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * The run's deadline, epoch milliseconds. Every attempt is capped by the time left; rule 6 stops a series whose
+     * next wait would outlast it (`no-time-left`). Absent (or not finite) = no deadline: the time left is `Infinity`.
+     */
+    readonly deadline?: number;
+    /** The clock, epoch milliseconds. Default `Date.now`. */
+    readonly now?: () => number;
+    /** The served form of a failed attempt's error. Default `extractErrorInfo` (no redaction rule). */
+    readonly serve?: (error: unknown) => StructuredErrorInfo;
+    /** Between a failed attempt and the next, before `backoffMs`: the engine discards the attempt's staged writes. */
+    readonly between?: (attempt: number) => void;
+    /** Every attempt, at its end, with its served error (`undefined` for `'ok'` and `'paused'`). */
+    readonly onAttempt?: (record: AttemptRecord, structuredError: StructuredErrorInfo | undefined) => void;
+    /** A failed attempt that WILL be retried — after `between` and `onAttempt`, before the wait. */
+    readonly onRetry?: (attempt: number, of: number, delayMs: number, structuredError: StructuredErrorInfo) => void;
+    /** The series ended: called once, before the last `onAttempt` (or after a wait the run's signal cut). */
+    readonly onEnd?: (summary: AttemptSummary) => void;
+    /** @internal Native owner only: the exact escaping value and category, before its stage serves the error. */
+    readonly onFailure?: (error: unknown, category: AttemptCategory) => void;
+    /** `retryOn` threw — the attempt is treated as declined; the engine logs the throw here. */
+    readonly onRetryOnThrew?: (thrown: unknown) => void;
+    /**
+     * The attempt ended without an answer — called SYNCHRONOUSLY the moment its signal aborts (its cap, the deadline,
+     * a cancellation), else as soon as it failed. Whatever the abandoned function does afterwards is not this
+     * series': the engine fences its scope here. Once per attempt; never for `'ok'` or `'paused'` — except an attempt
+     * that STARTED under an already-aborted signal, fenced once its synchronous part has run (nobody waits for it).
+     */
+    readonly onAbandon?: (attempt: number) => void;
+    /**
+     * The caller races `run`'s promise against the attempt's signal itself — the engine does, at the stage boundary
+     * (`StageRunner`), so a stage keeps its one await per attempt. Otherwise the runner races it: the series never
+     * waits on an attempt past its cap.
+     */
+    readonly raced?: boolean;
+    /**
+     * What an attempt's `observed(report)` does (P2) — the owner of the attempt records the report: `runCall` hands
+     * a call's reports to the scope, `attempt()` keeps its own. `ended` says the attempt had already ended when the
+     * report came (the owner drops it). Absent — a stage attempt's context, whose `observed` the scope's
+     * `$attempt()` replaces — `observed` is refused with a `TypeError`.
+     */
+    readonly observe?: (report: ObservedAttempt, at: {
+        readonly attempt: number;
+        readonly ended: boolean;
+    }) => void;
+    /**
+     * The outside system the target touches (P3, design §3.3). Every record then says what its attempt did to it
+     * (`effect`) and names the system and the RECORDED key; every attempt's context carries the REAL key. A series
+     * that ends without an answer after any attempt of unknown effect fails with `UnknownEffectError` (its `cause` the attempt's own error) —
+     * except a pause, which stays a pause. A touching series that may retry without a key is refused before anything
+     * runs: the law's last door.
+     */
+    readonly effect?: EffectTarget;
+}
+/**
+ * When the attempt behind `context` must end, epoch milliseconds — its start plus its cap (`min(timeoutMs, time
+ * left)`, so never past the run's deadline) — or `undefined` for an uncapped attempt. A call made inside the
+ * attempt runs under it as its deadline (`attempt/call.ts`). Only the runner's own contexts are known.
+ */
+export declare function attemptEndsAt(context: AttemptContext | undefined): number | undefined;
+/**
+ * Run `run` until it succeeds or the policy stops it; resolve with its value or reject with the LAST attempt's
+ * own error. `run(n)` is called with the attempt number, 1-based.
+ */
+export declare function runAttempts<T>(run: (attempt: number, context: AttemptContext) => Promise<T> | T, policy: RetryPolicy, options: AttemptRunOptions): Promise<T>;
+/**
+ * Resolve a policy's `backoffMs` for the attempt that just failed (1-based) and its error. Anything that is not a finite,
+ * positive number — a missing dial, a negative value, a `NaN` from a consumer's arithmetic, or a throwing
+ * function — becomes `0`, i.e. retry immediately. A backoff dial must never be able to crash a run or park it
+ * forever.
+ */
+export declare function resolveBackoffMs(backoffMs: RetryPolicy['backoffMs'], attempt: number, error?: unknown): number;
+/**
+ * Await `ms`, cut short by an abort. Resolves either way — the caller re-checks `signal.aborted` and rethrows
+ * the attempt's own error, so a cancelled run never sits out a long backoff and never loses the failure that
+ * caused it. The timer and the listener are always cleaned up.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

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

@@ -0,0 +1,47 @@
+/**
+ * attempt/standalone.ts — `attempt(fn, policy?, options?)`: the attempt runner with no scope and no run (design §3.6,
+ * packet P2).
+ *
+ * The same loop, the same record (law 1) for code that is not a stage — a provider decorator, a client wrapper, a
+ * script. There is no run, so there is no execution tree and no hook: every record goes to `options.onAttempt`, the
+ * caller's own, as each attempt ends. There is no redaction rule either: the record holds the error's named fields
+ * (never the thrown value), and the caller's callback decides what to keep.
+ *
+ * Time and cancellation are the caller's: `deadline` caps every attempt by the time left (and a wait that would
+ * outlast it is never started — `no-time-left`); `signal` cancels. A deadline already past, or a signal already
+ * aborted, starts no attempt and records nothing.
+ *
+ * ```typescript
+ * const res = await attempt((t) => fetch(url, { signal: t.signal }), { attempts: 3, timeoutMs: 5_000 }, {
+ *   target: 'inventory.lookup',
+ *   deadline: Date.now() + 20_000,
+ *   onAttempt: (record) => log.info(record),
+ * });
+ * ```
+ */
+import type { AttemptContext, AttemptRecord, RetryPolicy } from './types.js';
+/** How a standalone attempt series is named, timed and reported. */
+export interface AttemptOptions {
+    /** The outside target — a name from code (1–128 characters, no control character), stamped on every record. */
+    readonly target?: string;
+    /**
+     * The series every record names — the caller's name for this one operation (an order id, a request id), so two
+     * operations can be told apart. Default: the target, else `'attempt'`.
+     */
+    readonly series?: string;
+    /** The deadline, epoch milliseconds: every attempt is capped by the time left before it. */
+    readonly deadline?: number;
+    /** Cancels the series: the attempt in flight is cut (`aborted`), a wait ends, and no attempt follows. */
+    readonly signal?: AbortSignal;
+    /**
+     * Every attempt, at its end — the only place a standalone record goes. A throw from it is isolated: it never
+     * changes the call's outcome (dev mode warns).
+     */
+    readonly onAttempt?: (record: AttemptRecord) => void;
+}
+/**
+ * Run `fn` under `policy` (none = one attempt, still recorded) and resolve with its answer, or reject with the LAST
+ * attempt's own error. `fn` gets the attempt's `AttemptContext`: pass `signal` to the work, read `timeLeftMs()`,
+ * and report an SDK's own retries with `observed()`.
+ */
+export declare function attempt<T>(fn: (attempt: AttemptContext) => Promise<T> | T, policy?: RetryPolicy, options?: AttemptOptions): Promise<T>;