footprintjs 10.0.1 → 10.2.0

package/dist/esm/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>;

package/dist/esm/lib/attempt/standalone.js

@@ -0,0 +1,126 @@
+/**
+ * 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 { isDevMode } from '../devMode.js';
+import { extractErrorInfo } from '../errors/errorInfo.js';
+import { armDeadline, isAbortSignal } from './deadline.js';
+import { admitAttemptName } from './name.js';
+import { observedRecord, ObservedSeriesBook, readObservedReport } from './observed.js';
+import { admitCallPolicy } from './policy.js';
+import { runAttempts } from './runner.js';
+const WHERE = 'attempt()';
+/**
+ * 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 function attempt(fn, policy, options = {}) {
+    if (typeof fn !== 'function')
+        throw new TypeError(`${WHERE}: fn must be a function`);
+    const admitted = admitCallPolicy(WHERE, policy);
+    const read = readOptions(options);
+    const armed = armDeadline(read.signal, read.deadline, `${WHERE} passed its deadline (${String(read.deadline)} epoch ms)`);
+    if (armed.signal?.aborted) {
+        armed.dispose();
+        return Promise.reject(armed.signal.reason);
+    }
+    const deliver = (record) => {
+        if (read.onAttempt === undefined)
+            return;
+        try {
+            read.onAttempt(record);
+        }
+        catch (error) {
+            if (isDevMode()) {
+                // eslint-disable-next-line no-console
+                console.warn(`[footprint] ${WHERE}: onAttempt threw; the record was still made`, error);
+            }
+        }
+    };
+    const observing = new ObservedOwner(read.series, deliver);
+    return runAttempts((_attempt, context) => fn(context), admitted, {
+        series: read.series,
+        kind: 'call',
+        ...(read.target !== undefined && { target: read.target }),
+        ...(armed.signal !== undefined && { signal: armed.signal }),
+        ...(read.deadline !== undefined && { deadline: read.deadline }),
+        onAttempt: (record) => deliver(record),
+        observe: (report, at) => observing.observe(report, at),
+    }).finally(() => armed.dispose());
+}
+/** The options as read: each once, validated (a `TypeError` naming the field). */
+function readOptions(options) {
+    if (options === null || typeof options !== 'object')
+        throw new TypeError(`${WHERE}: options must be an object`);
+    const { target, series, deadline, signal, onAttempt } = options;
+    const name = target === undefined ? undefined : admitAttemptName(WHERE, 'target', target);
+    const named = series === undefined ? name ?? 'attempt' : admitAttemptName(WHERE, 'series', series);
+    if (deadline !== undefined && (typeof deadline !== 'number' || Number.isNaN(deadline))) {
+        throw new TypeError(`${WHERE}: deadline must be a number (epoch ms)`);
+    }
+    if (signal !== undefined && !isAbortSignal(signal))
+        throw new TypeError(`${WHERE}: signal must be an AbortSignal`);
+    if (onAttempt !== undefined && typeof onAttempt !== 'function') {
+        throw new TypeError(`${WHERE}: onAttempt must be a function`);
+    }
+    // `-Infinity` is a deadline long past (no attempt starts); `Infinity` is none.
+    const at = deadline === -Infinity ? 0 : deadline;
+    return {
+        ...(name !== undefined && { target: name }),
+        series: named,
+        ...(at !== undefined && Number.isFinite(at) && { deadline: at }),
+        ...(signal !== undefined && { signal }),
+        ...(onAttempt !== undefined && { onAttempt }),
+    };
+}
+/**
+ * The observed reports of a standalone series: each attempt `m` opens its own call level, `<series>@<m>.<k>` — the
+ * shape a stage attempt's calls have, rooted at the caller's series. A report after its attempt ended is dropped.
+ */
+class ObservedOwner {
+    series;
+    deliver;
+    current;
+    constructor(series, deliver) {
+        this.series = series;
+        this.deliver = deliver;
+    }
+    observe(report, at) {
+        const read = readObservedReport(report);
+        // After its attempt ended: dropped, never thrown — an SDK's own callback may fire late, and an observed attempt
+        // never changes control flow.
+        if (at.ended)
+            return;
+        if (this.current?.attempt !== at.attempt) {
+            let ordinal = 0;
+            const prefix = `${this.series}@${at.attempt}`;
+            this.current = { attempt: at.attempt, book: new ObservedSeriesBook(() => `${prefix}.${++ordinal}`) };
+        }
+        const { record } = observedRecord(read, {
+            series: this.current.book.seriesFor(read),
+            now: Date.now,
+            // No run, no rule: the error's structured info (the record keeps its named fields only).
+            serve: extractErrorInfo,
+        });
+        this.deliver(record);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RhbmRhbG9uZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9saWIvYXR0ZW1wdC9zdGFuZGFsb25lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQW9CRztBQUVILE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFDMUMsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFDMUQsT0FBTyxFQUFFLFdBQVcsRUFBRSxhQUFhLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFDM0QsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sV0FBVyxDQUFDO0FBQzdDLE9BQU8sRUFBRSxjQUFjLEVBQUUsa0JBQWtCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFDdkYsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBRzFDLE1BQU0sS0FBSyxHQUFHLFdBQVcsQ0FBQztBQXNCMUI7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxPQUFPLENBQ3JCLEVBQStDLEVBQy9DLE1BQW9CLEVBQ3BCLFVBQTBCLEVBQUU7SUFFNUIsSUFBSSxPQUFPLEVBQUUsS0FBSyxVQUFVO1FBQUUsTUFBTSxJQUFJLFNBQVMsQ0FBQyxHQUFHLEtBQUsseUJBQXlCLENBQUMsQ0FBQztJQUNyRixNQUFNLFFBQVEsR0FBRyxlQUFlLENBQUMsS0FBSyxFQUFFLE1BQU0sQ0FBQyxDQUFDO0lBQ2hELE1BQU0sSUFBSSxHQUFHLFdBQVcsQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUNsQyxNQUFNLEtBQUssR0FBRyxXQUFXLENBQ3ZCLElBQUksQ0FBQyxNQUFNLEVBQ1gsSUFBSSxDQUFDLFFBQVEsRUFDYixHQUFHLEtBQUsseUJBQXlCLE1BQU0sQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLFlB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LENBQUMsTUFBTSxDQUFDLENBQUM7UUFDeEMsZ0hBQWdIO1FBQ2hILDhCQUE4QjtRQUM5QixJQUFJLEVBQUUsQ0FBQyxLQUFLO1lBQUUsT0FBTztRQUNyQixJQUFJLElBQUksQ0FBQyxPQUFPLEVBQUUsT0FBTyxLQUFLLEVBQUUsQ0FBQyxPQUFPLEVBQUUsQ0FBQztZQUN6QyxJQUFJLE9BQU8sR0FBRyxDQUFDLENBQUM7WUFDaEIsTUFBTSxNQUFNLEdBQUcsR0FBRyxJQUFJLENBQUMsTUFBTSxJQUFJLEVBQUUsQ0FBQyxPQUFPLEVBQUUsQ0FBQztZQUM5QyxJQUFJLENBQUMsT0FBTyxHQUFHLEVBQUUsT0FBTyxFQUFFLEVBQUUsQ0FBQyxPQUFPLEVBQUUsSUFBSSxFQUFFLElBQUksa0JBQWtCLENBQUMsR0FBRyxFQUFFLENBQUMsR0FBRyxNQUFNLElBQUksRUFBRSxPQUFPLEVBQUUsQ0FBQyxFQUFFLENBQUM7UUFDdkcsQ0FBQztRQUNELE1BQU0sRUFBRSxNQUFNLEVBQUUsR0FBRyxjQUFjLENBQUMsSUFBSSxFQUFFO1lBQ3RDLE1BQU0sRUFBRSxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDO1lBQ3pDLEdBQUcsRUFBRSxJQUFJLENBQUMsR0FBRztZQUNiLHlGQUF5RjtZQUN6RixLQUFLLEVBQUUsZ0JBQWdCO1NBQ3hCLENBQUMsQ0FBQztRQUNILElBQUksQ0FBQyxPQUFPLENBQUMsTUFBTSxDQUFDLENBQUM7SUFDdkIsQ0FBQztDQUNGIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBhdHRlbXB0L3N0YW5kYWxvbmUudHMg4oCUIGBhdHRlbXB0KGZuLCBwb2xpY3k/LCBvcHRpb25zPylgOiB0aGUgYXR0ZW1wdCBydW5uZXIgd2l0aCBubyBzY29wZSBhbmQgbm8gcnVuIChkZXNpZ24gwqczLjYsXG4gKiBwYWNrZXQgUDIpLlxuICpcbiAqIFRoZSBzYW1lIGxvb3AsIHRoZSBzYW1lIHJlY29yZCAobGF3IDEpIGZvciBjb2RlIHRoYXQgaXMgbm90IGEgc3RhZ2Ug4oCUIGEgcHJvdmlkZXIgZGVjb3JhdG9yLCBhIGNsaWVudCB3cmFwcGVyLCBhXG4gKiBzY3JpcHQuIFRoZXJlIGlzIG5vIHJ1biwgc28gdGhlcmUgaXMgbm8gZXhlY3V0aW9uIHRyZWUgYW5kIG5vIGhvb2s6IGV2ZXJ5IHJlY29yZCBnb2VzIHRvIGBvcHRpb25zLm9uQXR0ZW1wdGAsIHRoZVxuICogY2FsbGVyJ3Mgb3duLCBhcyBlYWNoIGF0dGVtcHQgZW5kcy4gVGhlcmUgaXMgbm8gcmVkYWN0aW9uIHJ1bGUgZWl0aGVyOiB0aGUgcmVjb3JkIGhvbGRzIHRoZSBlcnJvcidzIG5hbWVkIGZpZWxkc1xuICogKG5ldmVyIHRoZSB0aHJvd24gdmFsdWUpLCBhbmQgdGhlIGNhbGxlcidzIGNhbGxiYWNrIGRlY2lkZXMgd2hhdCB0byBrZWVwLlxuICpcbiAqIFRpbWUgYW5kIGNhbmNlbGxhdGlvbiBhcmUgdGhlIGNhbGxlcidzOiBgZGVhZGxpbmVgIGNhcHMgZXZlcnkgYXR0ZW1wdCBieSB0aGUgdGltZSBsZWZ0IChhbmQgYSB3YWl0IHRoYXQgd291bGRcbiAqIG91dGxhc3QgaXQgaXMgbmV2ZXIgc3RhcnRlZCDigJQgYG5vLXRpbWUtbGVmdGApOyBgc2lnbmFsYCBjYW5jZWxzLiBBIGRlYWRsaW5lIGFscmVhZHkgcGFzdCwgb3IgYSBzaWduYWwgYWxyZWFkeVxuICogYWJvcnRlZCwgc3RhcnRzIG5vIGF0dGVtcHQgYW5kIHJlY29yZHMgbm90aGluZy5cbiAqXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBjb25zdCByZXMgPSBhd2FpdCBhdHRlbXB0KCh0KSA9PiBmZXRjaCh1cmwsIHsgc2lnbmFsOiB0LnNpZ25hbCB9KSwgeyBhdHRlbXB0czogMywgdGltZW91dE1zOiA1XzAwMCB9LCB7XG4gKiAgIHRhcmdldDogJ2ludmVudG9yeS5sb29rdXAnLFxuICogICBkZWFkbGluZTogRGF0ZS5ub3coKSArIDIwXzAwMCxcbiAqICAgb25BdHRlbXB0OiAocmVjb3JkKSA9PiBsb2cuaW5mbyhyZWNvcmQpLFxuICogfSk7XG4gKiBgYGBcbiAqL1xuXG5pbXBvcnQgeyBpc0Rldk1vZGUgfSBmcm9tICcuLi9kZXZNb2RlLmpzJztcbmltcG9ydCB7IGV4dHJhY3RFcnJvckluZm8gfSBmcm9tICcuLi9lcnJvcnMvZXJyb3JJbmZvLmpzJztcbmltcG9ydCB7IGFybURlYWRsaW5lLCBpc0Fib3J0U2lnbmFsIH0gZnJvbSAnLi9kZWFkbGluZS5qcyc7XG5pbXBvcnQgeyBhZG1pdEF0dGVtcHROYW1lIH0gZnJvbSAnLi9uYW1lLmpzJztcbmltcG9ydCB7IG9ic2VydmVkUmVjb3JkLCBPYnNlcnZlZFNlcmllc0Jvb2ssIHJlYWRPYnNlcnZlZFJlcG9ydCB9IGZyb20gJy4vb2JzZXJ2ZWQuanMnO1xuaW1wb3J0IHsgYWRtaXRDYWxsUG9saWN5IH0gZnJvbSAnLi9wb2xpY3kuanMnO1xuaW1wb3J0IHsgcnVuQXR0ZW1wdHMgfSBmcm9tICcuL3J1bm5lci5qcyc7XG5pbXBvcnQgdHlwZSB7IEF0dGVtcHRDb250ZXh0LCBBdHRlbXB0UmVjb3JkLCBPYnNlcnZlZEF0dGVtcHQsIFJldHJ5UG9saWN5IH0gZnJvbSAnLi90eXBlcy5qcyc7XG5cbmNvbnN0IFdIRVJFID0gJ2F0dGVtcHQoKSc7XG5cbi8qKiBIb3cgYSBzdGFuZGFsb25lIGF0dGVtcHQgc2VyaWVzIGlzIG5hbWVkLCB0aW1lZCBhbmQgcmVwb3J0ZWQuICovXG5leHBvcnQgaW50ZXJmYWNlIEF0dGVtcHRPcHRpb25zIHtcbiAgLyoqIFRoZSBvdXRzaWRlIHRhcmdldCDigJQgYSBuYW1lIGZyb20gY29kZSAoMeKAkzEyOCBjaGFyYWN0ZXJzLCBubyBjb250cm9sIGNoYXJhY3RlciksIHN0YW1wZWQgb24gZXZlcnkgcmVjb3JkLiAqL1xuICByZWFkb25seSB0YXJnZXQ/OiBzdHJpbmc7XG4gIC8qKlxuICAgKiBUaGUgc2VyaWVzIGV2ZXJ5IHJlY29yZCBuYW1lcyDigJQgdGhlIGNhbGxlcidzIG5hbWUgZm9yIHRoaXMgb25lIG9wZXJhdGlvbiAoYW4gb3JkZXIgaWQsIGEgcmVxdWVzdCBpZCksIHNvIHR3b1xuICAgKiBvcGVyYXRpb25zIGNhbiBiZSB0b2xkIGFwYXJ0LiBEZWZhdWx0OiB0aGUgdGFyZ2V0LCBlbHNlIGAnYXR0ZW1wdCdgLlxuICAgKi9cbiAgcmVhZG9ubHkgc2VyaWVzPzogc3RyaW5nO1xuICAvKiogVGhlIGRlYWRsaW5lLCBlcG9jaCBtaWxsaXNlY29uZHM6IGV2ZXJ5IGF0dGVtcHQgaXMgY2FwcGVkIGJ5IHRoZSB0aW1lIGxlZnQgYmVmb3JlIGl0LiAqL1xuICByZWFkb25seSBkZWFkbGluZT86IG51bWJlcjtcbiAgLyoqIENhbmNlbHMgdGhlIHNlcmllczogdGhlIGF0dGVtcHQgaW4gZmxpZ2h0IGlzIGN1dCAoYGFib3J0ZWRgKSwgYSB3YWl0IGVuZHMsIGFuZCBubyBhdHRlbXB0IGZvbGxvd3MuICovXG4gIHJlYWRvbmx5IHNpZ25hbD86IEFib3J0U2lnbmFsO1xuICAvKipcbiAgICogRXZlcnkgYXR0ZW1wdCwgYXQgaXRzIGVuZCDigJQgdGhlIG9ubHkgcGxhY2UgYSBzdGFuZGFsb25lIHJlY29yZCBnb2VzLiBBIHRocm93IGZyb20gaXQgaXMgaXNvbGF0ZWQ6IGl0IG5ldmVyXG4gICAqIGNoYW5nZXMgdGhlIGNhbGwncyBvdXRjb21lIChkZXYgbW9kZSB3YXJucykuXG4gICAqL1xuICByZWFkb25seSBvbkF0dGVtcHQ/OiAocmVjb3JkOiBBdHRlbXB0UmVjb3JkKSA9PiB2b2lkO1xufVxuXG4vKipcbiAqIFJ1biBgZm5gIHVuZGVyIGBwb2xpY3lgIChub25lID0gb25lIGF0dGVtcHQsIHN0aWxsIHJlY29yZGVkKSBhbmQgcmVzb2x2ZSB3aXRoIGl0cyBhbnN3ZXIsIG9yIHJlamVjdCB3aXRoIHRoZSBMQVNUXG4gKiBhdHRlbXB0J3Mgb3duIGVycm9yLiBgZm5gIGdldHMgdGhlIGF0dGVtcHQncyBgQXR0ZW1wdENvbnRleHRgOiBwYXNzIGBzaWduYWxgIHRvIHRoZSB3b3JrLCByZWFkIGB0aW1lTGVmdE1zKClgLFxuICogYW5kIHJlcG9ydCBhbiBTREsncyBvd24gcmV0cmllcyB3aXRoIGBvYnNlcnZlZCgpYC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGF0dGVtcHQ8VD4oXG4gIGZuOiAoYXR0ZW1wdDogQXR0ZW1wdENvbnRleHQpID0+IFByb21pc2U8VD4gfCBULFxuICBwb2xpY3k/OiBSZXRyeVBvbGljeSxcbiAgb3B0aW9uczogQXR0ZW1wdE9wdGlvbnMgPSB7fSxcbik6IFByb21pc2U8VD4ge1xuICBpZiAodHlwZW9mIGZuICE9PSAnZnVuY3Rpb24nKSB0aHJvdyBuZXcgVHlwZUVycm9yKGAke1dIRVJFfTogZm4gbXVzdCBiZSBhIGZ1bmN0aW9uYCk7XG4gIGNvbnN0IGFkbWl0dGVkID0gYWRtaXRDYWxsUG9saWN5KFdIRVJFLCBwb2xpY3kpO1xuICBjb25zdCByZWFkID0gcmVhZE9wdGlvbnMob3B0aW9ucyk7XG4gIGNvbnN0IGFybWVkID0gYXJtRGVhZGxpbmUoXG4gICAgcmVhZC5zaWduYWwsXG4gICAgcmVhZC5kZWFkbGluZSxcbiAgICBgJHtXSEVSRX0gcGFzc2VkIGl0cyBkZWFkbGluZSAoJHtTdHJpbmcocmVhZC5kZWFkbGluZSl9IGVwb2NoIG1zKWAsXG4gICk7XG4gIGlmIChhcm1lZC5zaWduYWw/LmFib3J0ZWQpIHtcbiAgICBhcm1lZC5kaXNwb3NlKCk7XG4gICAgcmV0dXJuIFByb21pc2UucmVqZWN0KGFybWVkLnNpZ25hbC5yZWFzb24pO1xuICB9XG4gIGNvbnN0IGRlbGl2ZXIgPSAocmVjb3JkOiBBdHRlbXB0UmVjb3JkKSA9PiB7XG4gICAgaWYgKHJlYWQub25BdHRlbXB0ID09PSB1bmRlZmluZWQpIHJldHVybjtcbiAgICB0cnkge1xuICAgICAgcmVhZC5vbkF0dGVtcHQocmVjb3JkKTtcbiAgICB9IGNhdGNoIChlcnJvcikge1xuICAgICAgaWYgKGlzRGV2TW9kZSgpKSB7XG4gICAgICAgIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBuby1jb25zb2xlXG4gICAgICAgIGNvbnNvbGUud2FybihgW2Zvb3RwcmludF0gJHtXSEVSRX06IG9uQXR0ZW1wdCB0aHJldzsgdGhlIHJlY29yZCB3YXMgc3RpbGwgbWFkZWAsIGVycm9yKTtcbiAgICAgIH1cbiAgICB9XG4gIH07XG4gIGNvbnN0IG9ic2VydmluZyA9IG5ldyBPYnNlcnZlZE93bmVyKHJlYWQuc2VyaWVzLCBkZWxpdmVyKTtcbiAgcmV0dXJuIHJ1bkF0dGVtcHRzPFQ+KChfYXR0ZW1wdCwgY29udGV4dCkgPT4gZm4oY29udGV4dCksIGFkbWl0dGVkLCB7XG4gICAgc2VyaWVzOiByZWFkLnNlcmllcyxcbiAgICBraW5kOiAnY2FsbCcsXG4gICAgLi4uKHJlYWQudGFyZ2V0ICE9PSB1bmRlZmluZWQgJiYgeyB0YXJnZXQ6IHJlYWQudGFyZ2V0IH0pLFxuICAgIC4uLihhcm1lZC5zaWduYWwgIT09IHVuZGVmaW5lZCAmJiB7IHNpZ25hbDogYXJtZWQuc2lnbmFsIH0pLFxuICAgIC4uLihyZWFkLmRlYWRsaW5lICE9PSB1bmRlZmluZWQgJiYgeyBkZWFkbGluZTogcmVhZC5kZWFkbGluZSB9KSxcbiAgICBvbkF0dGVtcHQ6IChyZWNvcmQpID0+IGRlbGl2ZXIocmVjb3JkKSxcbiAgICBvYnNlcnZlOiAocmVwb3J0LCBhdCkgPT4gb2JzZXJ2aW5nLm9ic2VydmUocmVwb3J0LCBhdCksXG4gIH0pLmZpbmFsbHkoKCkgPT4gYXJtZWQuZGlzcG9zZSgpKTtcbn1cblxuLyoqIFRoZSBvcHRpb25zIGFzIHJlYWQ6IGVhY2ggb25jZSwgdmFsaWRhdGVkIChhIGBUeXBlRXJyb3JgIG5hbWluZyB0aGUgZmllbGQpLiAqL1xuZnVuY3Rpb24gcmVhZE9wdGlvbnMob3B0aW9uczogQXR0ZW1wdE9wdGlvbnMpOiB7XG4gIHRhcmdldD86IHN0cmluZztcbiAgc2VyaWVzOiBzdHJpbmc7XG4gIGRlYWRsaW5lPzogbnVtYmVyO1xuICBzaWduYWw/OiBBYm9ydFNpZ25hbDtcbiAgb25BdHRlbXB0PzogKHJlY29yZDogQXR0ZW1wdFJlY29yZCkgPT4gdm9pZDtcbn0ge1xuICBpZiAob3B0aW9ucyA9PT0gbnVsbCB8fCB0eXBlb2Ygb3B0aW9ucyAhPT0gJ29iamVjdCcpIHRocm93IG5ldyBUeXBlRXJyb3IoYCR7V0hFUkV9OiBvcHRpb25zIG11c3QgYmUgYW4gb2JqZWN0YCk7XG4gIGNvbnN0IHsgdGFyZ2V0LCBzZXJpZXMsIGRlYWRsaW5lLCBzaWduYWwsIG9uQXR0ZW1wdCB9ID0gb3B0aW9ucztcbiAgY29uc3QgbmFtZSA9IHRhcmdldCA9PT0gdW5kZWZpbmVkID8gdW5kZWZpbmVkIDogYWRtaXRBdHRlbXB0TmFtZShXSEVSRSwgJ3RhcmdldCcsIHRhcmdldCk7XG4gIGNvbnN0IG5hbWVkID0gc2VyaWVzID09PSB1bmRlZmluZWQgPyBuYW1lID8/ICdhdHRlbXB0JyA6IGFkbWl0QXR0ZW1wdE5hbWUoV0hFUkUsICdzZXJpZXMnLCBzZXJpZXMpO1xuICBpZiAoZGVhZGxpbmUgIT09IHVuZGVmaW5lZCAmJiAodHlwZW9mIGRlYWRsaW5lICE9PSAnbnVtYmVyJyB8fCBOdW1iZXIuaXNOYU4oZGVhZGxpbmUpKSkge1xuICAgIHRocm93IG5ldyBUeXBlRXJyb3IoYCR7V0hFUkV9OiBkZWFkbGluZSBtdXN0IGJlIGEgbnVtYmVyIChlcG9jaCBtcylgKTtcbiAgfVxuICBpZiAoc2lnbmFsICE9PSB1bmRlZmluZWQgJiYgIWlzQWJvcnRTaWduYWwoc2lnbmFsKSkgdGhyb3cgbmV3IFR5cGVFcnJvcihgJHtXSEVSRX06IHNpZ25hbCBtdXN0IGJlIGFuIEFib3J0U2lnbmFsYCk7XG4gIGlmIChvbkF0dGVtcHQgIT09IHVuZGVmaW5lZCAmJiB0eXBlb2Ygb25BdHRlbXB0ICE9PSAnZnVuY3Rpb24nKSB7XG4gICAgdGhyb3cgbmV3IFR5cGVFcnJvcihgJHtXSEVSRX06IG9uQXR0ZW1wdCBtdXN0IGJlIGEgZnVuY3Rpb25gKTtcbiAgfVxuICAvLyBgLUluZmluaXR5YCBpcyBhIGRlYWRsaW5lIGxvbmcgcGFzdCAobm8gYXR0ZW1wdCBzdGFydHMpOyBgSW5maW5pdHlgIGlzIG5vbmUuXG4gIGNvbnN0IGF0ID0gZGVhZGxpbmUgPT09IC1JbmZpbml0eSA/IDAgOiBkZWFkbGluZTtcbiAgcmV0dXJuIHtcbiAgICAuLi4obmFtZSAhPT0gdW5kZWZpbmVkICYmIHsgdGFyZ2V0OiBuYW1lIH0pLFxuICAgIHNlcmllczogbmFtZWQsXG4gICAgLi4uKGF0ICE9PSB1bmRlZmluZWQgJiYgTnVtYmVyLmlzRmluaXRlKGF0KSAmJiB7IGRlYWRsaW5lOiBhdCB9KSxcbiAgICAuLi4oc2lnbmFsICE9PSB1bmRlZmluZWQgJiYgeyBzaWduYWwgfSksXG4gICAgLi4uKG9uQXR0ZW1wdCAhPT0gdW5kZWZpbmVkICYmIHsgb25BdHRlbXB0IH0pLFxuICB9O1xufVxuXG4vKipcbiAqIFRoZSBvYnNlcnZlZCByZXBvcnRzIG9mIGEgc3RhbmRhbG9uZSBzZXJpZXM6IGVhY2ggYXR0ZW1wdCBgbWAgb3BlbnMgaXRzIG93biBjYWxsIGxldmVsLCBgPHNlcmllcz5APG0+LjxrPmAg4oCUIHRoZVxuICogc2hhcGUgYSBzdGFnZSBhdHRlbXB0J3MgY2FsbHMgaGF2ZSwgcm9vdGVkIGF0IHRoZSBjYWxsZXIncyBzZXJpZXMuIEEgcmVwb3J0IGFmdGVyIGl0cyBhdHRlbXB0IGVuZGVkIGlzIGRyb3BwZWQuXG4gKi9cbmNsYXNzIE9ic2VydmVkT3duZXIge1xuICBwcml2YXRlIGN1cnJlbnQ/OiB7IHJlYWRvbmx5IGF0dGVtcHQ6IG51bWJlcjsgcmVhZG9ubHkgYm9vazogT2JzZXJ2ZWRTZXJpZXNCb29rIH07XG5cbiAgY29uc3RydWN0b3IocHJpdmF0ZSByZWFkb25seSBzZXJpZXM6IHN0cmluZywgcHJpdmF0ZSByZWFkb25seSBkZWxpdmVyOiAocmVjb3JkOiBBdHRlbXB0UmVjb3JkKSA9PiB2b2lkKSB7fVxuXG4gIG9ic2VydmUocmVwb3J0OiBPYnNlcnZlZEF0dGVtcHQsIGF0OiB7IHJlYWRvbmx5IGF0dGVtcHQ6IG51bWJlcjsgcmVhZG9ubHkgZW5kZWQ6IGJvb2xlYW4gfSk6IHZvaWQge1xuICAgIGNvbnN0IHJlYWQgPSByZWFkT2JzZXJ2ZWRSZXBvcnQocmVwb3J0KTtcbiAgICAvLyBBZnRlciBpdHMgYXR0ZW1wdCBlbmRlZDogZHJvcHBlZCwgbmV2ZXIgdGhyb3duIOKAlCBhbiBTREsncyBvd24gY2FsbGJhY2sgbWF5IGZpcmUgbGF0ZSwgYW5kIGFuIG9ic2VydmVkIGF0dGVtcHRcbiAgICAvLyBuZXZlciBjaGFuZ2VzIGNvbnRyb2wgZmxvdy5cbiAgICBpZiAoYXQuZW5kZWQpIHJldHVybjtcbiAgICBpZiAodGhpcy5jdXJyZW50Py5hdHRlbXB0ICE9PSBhdC5hdHRlbXB0KSB7XG4gICAgICBsZXQgb3JkaW5hbCA9IDA7XG4gICAgICBjb25zdCBwcmVmaXggPSBgJHt0aGlzLnNlcmllc31AJHthdC5hdHRlbXB0fWA7XG4gICAgICB0aGlzLmN1cnJlbnQgPSB7IGF0dGVtcHQ6IGF0LmF0dGVtcHQsIGJvb2s6IG5ldyBPYnNlcnZlZFNlcmllc0Jvb2soKCkgPT4gYCR7cHJlZml4fS4keysrb3JkaW5hbH1gKSB9O1xuICAgIH1cbiAgICBjb25zdCB7IHJlY29yZCB9ID0gb2JzZXJ2ZWRSZWNvcmQocmVhZCwge1xuICAgICAgc2VyaWVzOiB0aGlzLmN1cnJlbnQuYm9vay5zZXJpZXNGb3IocmVhZCksXG4gICAgICBub3c6IERhdGUubm93LFxuICAgICAgLy8gTm8gcnVuLCBubyBydWxlOiB0aGUgZXJyb3IncyBzdHJ1Y3R1cmVkIGluZm8gKHRoZSByZWNvcmQga2VlcHMgaXRzIG5hbWVkIGZpZWxkcyBvbmx5KS5cbiAgICAgIHNlcnZlOiBleHRyYWN0RXJyb3JJbmZvLFxuICAgIH0pO1xuICAgIHRoaXMuZGVsaXZlcihyZWNvcmQpO1xuICB9XG59XG4iXX0=

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

@@ -0,0 +1,453 @@
+/**
+ * attempt/types.ts — the attempt vocabulary: ONE record shape for every try the library runs.
+ *
+ * A retry is a loop, and every pass of it is an `AttemptRecord`: when it started, how long it took, how it
+ * ended, its failure category, and the retry-or-stop decision that followed it — a `DecisionEvidence`, the
+ * shape `decide()` produces, so a reader walks a retry exactly as it walks a decider (design
+ * docs/design/2026-10-time-and-failure-evidence.md, §3.1, §3.8, §4).
+ *
+ * WHERE it lives: on the execution tree (`StageSnapshot.attempts` / `attemptSummary`), on the `onAttempt`
+ * hook, and in recorders' stores — never on the commit bundle, so every log stays byte-identical (Q1).
+ *
+ * A LEAF (L0, scripts/layering.config.cjs): the frame's snapshot type (`memory/frameTypes.ts`, L4) names
+ * `AttemptRecord`, so this file imports only other leaves' types.
+ */
+import type { DecisionEvidence } from '../decide/types.js';
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import type { RetryLoopCall } from './retryLoopTypes.js';
+/**
+ * Declarative per-stage retry policy — the policy the attempt runner runs (`AttemptPolicy` in the design is
+ * this one type, under this one name).
+ *
+ * WHY this exists: a retry hand-rolled inside a stage function is invisible to
+ * the trace. The stage shows one execution, the commit log shows one bundle,
+ * and the two failed calls that preceded the successful one left no mark
+ * anywhere — an unexplained behaviour in a library whose whole thesis is that
+ * nothing invisible happens. Declared here instead, every attempt is part of
+ * the record: each attempt fires `FlowRecorder.onAttempt` with its
+ * {@link AttemptRecord}, each failed attempt that is retried also fires
+ * `FlowRecorder.onStageRetry`, and the stage's execution-tree node carries
+ * `attempts` and `attemptSummary`.
+ *
+ * A POLICY, not a stage kind — `retry` sits on a normal stage the way
+ * `isPausable` / `isStreaming` do. The serialized node `type` is unchanged and
+ * every existing consumer keeps rendering the stage exactly as before.
+ *
+ * @example
+ * ```ts
+ * flowChart<State>('Fetch user', fetchFn, 'fetch-user')
+ *   .retry({ attempts: 3, backoffMs: (n) => 100 * 2 ** (n - 1) })
+ * ```
+ */
+export interface RetryPolicy {
+    /**
+     * How many times the stage function may run in total, INCLUDING the first
+     * run. Must be an integer >= 1; `1` means "no retry" (a declared no-op,
+     * accepted so a policy can be switched off without deleting it — such a
+     * stage runs once and records no attempts).
+     */
+    attempts: number;
+    /**
+     * How long to wait before the NEXT attempt. Either a fixed number of
+     * milliseconds, or a function of the attempt that just FAILED (1-based) and
+     * its error, returning milliseconds — `(n) => 100 * 2 ** (n - 1)` is
+     * exponential backoff; `(n, error) => statedWaitMs(error) ?? 100 * n` honours
+     * a wait the outside system stated (a `Retry-After`) without the engine
+     * parsing anything. A one-argument function is unchanged. Omitted (or a
+     * non-finite / negative result, or a throw) means no wait.
+     *
+     * The wait is a plain awaited timer that is CANCELLED by the run's
+     * `AbortSignal`. It is not a pause: a chart cannot be checkpointed in the
+     * middle of a backoff. Under a run deadline, a wait that would outlast it is
+     * never started: the series stops `no-time-left`.
+     */
+    backoffMs?: number | ((attempt: number, error: unknown) => number);
+    /**
+     * The most one wait may last, in milliseconds — a finite number >= 0. The
+     * runner ENFORCES it: every wait is `min(backoffMs's answer, maxBackoffMs)`,
+     * whatever the error stated, so the declaration cannot lie.
+     *
+     * It is what makes a FUNCTION backoff countable before the run. A function
+     * may read the error (a stated `Retry-After`), and no error exists at build,
+     * so the static budget check never asks it: with `maxBackoffMs` it counts
+     * each wait at the ceiling; without, the stage is unbounded (`'backoff'`).
+     *
+     * @example
+     * ```ts
+     * .retry({ attempts: 4, timeoutMs: 10_000, backoffMs: (n, error) => statedWaitMs(error) ?? 500 * n, maxBackoffMs: 5_000 })
+     * ```
+     */
+    maxBackoffMs?: number;
+    /**
+     * The cap on ONE attempt, in milliseconds — a finite number > 0. The attempt
+     * runs under `min(timeoutMs, time left before the run's deadline)`; when the
+     * cap runs out, the attempt's signal (`scope.$attempt().signal`) aborts with
+     * an `AttemptTimeoutError`, the engine stops waiting for it, and the attempt
+     * is recorded `timeout` (then retried like any failure, if the policy allows).
+     *
+     * What the engine stops is the WAITING. The function's own work stops only if
+     * it passes the signal on (`fetch(url, { signal: scope.$attempt().signal })`);
+     * whatever it writes after its attempt ended is dropped and recorded on the
+     * stage (`StageSnapshot.lateWrites`).
+     *
+     * Declared with `attempts: 1`, it is a timeout with no retry — the stage
+     * still records its one attempt.
+     */
+    timeoutMs?: number;
+    /**
+     * Is THIS error worth another attempt? Defaults to retrying every error.
+     * Returning `false` ends the stage immediately on the normal error path, with
+     * no retry event; the attempt's record says why it stopped (`reason:
+     * 'declined'`).
+     *
+     * A throw from this predicate is treated as `false` — a broken predicate
+     * must not turn a failing stage into an infinite retry loop. The record
+     * tells the two apart: a throw stops the series `declined` with
+     * `retryOnThrew: true`.
+     */
+    retryOn?: (error: unknown) => boolean;
+}
+/**
+ * Who ran the attempt: the engine, for a stage's own policy (`'stage'`); the attempt runner, for a call a stage made
+ * through `scope.$call` or for the standalone `attempt()` (`'call'`); an outside system on its own — an SDK's
+ * internal retry — reported through `AttemptContext.observed` (`'observed'`, P2).
+ */
+export type AttemptKind = 'stage' | 'call' | 'observed';
+/**
+ * How one attempt ended. `'timeout'` is the attempt's OWN timer (never the outside system failing — law 4);
+ * `'paused'` is a pause (control flow, never retried). `'aborted'` is the run's signal ending the attempt: the
+ * attempt threw the abort's own reason. An attempt that threw its own error is `'failed'`, with its category,
+ * even when the run aborted around it — the abort is then the series' stop reason (`reason: 'aborted'`), never a
+ * rewrite of what the attempt did.
+ */
+export type AttemptOutcome = 'ok' | 'failed' | 'timeout' | 'aborted' | 'paused';
+/**
+ * The failure category of an attempt that did not succeed — ONE fixed set of seven, classified by
+ * `errorCategory` (`attempt/category.ts`), so every recorder breaks failures down the same way (§3.9).
+ * Evidence, never policy: the default `retryOn` retries every category.
+ */
+export type AttemptCategory = 'timeout' | 'rate-limited' | 'server' | 'network' | 'auth' | 'permanent' | 'unknown';
+/** What follows an attempt: another one, the value (`'done'`), or the attempt's own error (`'stop'`). */
+export type AttemptNext = 'retry' | 'done' | 'stop';
+/**
+ * Why the series went on or ended — the matched rule's label in `retryRules` (`attempt/decision.ts`), or the
+ * default's (`'retryable'`).
+ */
+export type AttemptReason = 'succeeded' | 'paused' | 'aborted' | 'exhausted' | 'declined' | 'no-time-left' | 'retryable';
+/**
+ * What an attempt did to the outside system a touching target names (design §3.3, P3) — present only on the records
+ * of a target that declared `touches`:
+ *   - `'applied'` — the attempt answered (`ok`);
+ *   - `'none'` — it failed, and its error itself declares `effect: 'none'` (the adapter's word: nothing was sent);
+ *   - `'unknown'` — anything else: a timeout, a cancellation, a pause, or a failure the adapter did not declare
+ *     harmless. Nobody knows whether the effect happened, so the series never reports it as failed or ok: a last
+ *     attempt of unknown effect fails with `UnknownEffectError` — reconcile, do not retry blindly.
+ */
+export type AttemptEffect = 'applied' | 'none' | 'unknown';
+/** What a stage's idempotency-key rule is handed — once per EXECUTION, before attempt 1 (`StageTouches`). */
+export interface IdempotencyKeyContext {
+    /**
+     * The run's (or the subflow's) input, frozen. On the root of a resumed leg the run's input is gone (it does not
+     * cross a resume), so reading it there THROWS rather than hand the rule nothing — the stage fails before anything
+     * is sent. A paused stage itself resumes under the key its checkpoint carries; the rule is not asked again.
+     */
+    readonly args: unknown;
+    /** This run's id. Regenerated per run and per resume — never a key on its own (see `StageTouches`). */
+    readonly runId: string;
+    /** The execution the key is for (`charge#4`). */
+    readonly runtimeStageId: string;
+    /**
+     * A committed state value, read without tracking — the key is not a write. Use it for a key the chart keeps in
+     * state; it survives a resume, where `args` does not (reading `args` on a resumed leg's root throws). A selected
+     * value read here makes the recorded key the redaction placeholder. Read-only: a frozen copy, never the committed
+     * value itself.
+     */
+    getState(key: string): unknown;
+}
+/**
+ * A stage that changes something outside the run — a charge, an email, a write to another service (design §3.3,
+ * P3). Declared with `.touches(system, { idempotencyKey })` or a `touches` option; a POLICY-like field on the node,
+ * like `retry` and `tags`. The built spec carries `system` only.
+ *
+ * `system` is a NAME from code (`'stripe'`) — never a value. `idempotencyKey` is the RULE that makes the key, run
+ * ONCE per execution (not per attempt) and handed to every attempt as `scope.$attempt().idempotencyKey`. It must
+ * name the OPERATION, so that every retry — and a resume's re-run, and a caller's whole-run retry — sends the same
+ * key: derive it from the input (`order-${args.orderId}`) or from state (`getState('orderId')`), never from `runId`
+ * alone (it changes on a resume) and never from what a model wrote. The builder refuses a touching stage that may retry with no rule, and the engine refuses an
+ * `interrupt()` in a keyless touching stage (a resume re-runs it). Under a redaction rule, a key derived from an
+ * input that holds a selected value is served as the placeholder (records, hook, `UnknownEffectError`) — the
+ * caller recomputes it from the input it gave to reconcile.
+ */
+export interface StageTouches {
+    /** The outside system — a name, 1–128 characters, no control, format or line-separator character. */
+    readonly system: string;
+    /**
+     * The key rule — a function, so the key belongs to the execution (a constant would make every run one operation).
+     * Its answer must be 1–255 printable ASCII characters with no space (it travels in a request header); anything
+     * else fails the stage with a `TypeError` that never echoes it.
+     */
+    readonly idempotencyKey?: (context: IdempotencyKeyContext) => string;
+}
+/**
+ * What `scope.$call(target, fn, policy, options)` declares beyond its policy (P3): the outside system the call
+ * touches, and the key it is made under. A call that touches a system and may retry must carry a key; the key is a
+ * VALUE the stage computed from its input or its state — never from model output — and is checked like a stage's.
+ */
+export interface CallOptions {
+    /** The outside system the call changes — a name like `target`. */
+    readonly touches?: string;
+    /**
+     * The key every attempt of the call is made under — only with `touches`. When the stage can `interrupt()`, derive it
+     * from state or from `scope.$attempt().idempotencyKey`, never from `$getArgs()`: the input does not cross a resume,
+     * so an args-derived key would differ on the re-run.
+     */
+    readonly idempotencyKey?: string;
+}
+/**
+ * An attempt's error as the run SERVES it — `StructuredErrorInfo` under the run's redaction rule
+ * (`RedactionRule.retainStageError`), without `raw`: a record must survive `structuredClone` and must never
+ * hand out the thrown value itself.
+ */
+export type AttemptError = Omit<StructuredErrorInfo, 'raw'>;
+/**
+ * What a retry-or-stop decision reads — the inputs `retryRules` evaluates, first match wins (§3.1). The runner
+ * computes each one only when a rule reaches it, so `retryOn` and `backoffMs` run exactly when a retry needs
+ * them.
+ *
+ * `category` and `keyPresent` are inputs no default rule reads; a chart's own rules over the same inputs may.
+ * `timeLeftMs` is `Infinity` without a deadline, and so is `timeLeftAfterWaitMs` (= `timeLeftMs − delayMs`):
+ * the no-time-left rule compares one input with a constant, as every `decide()` filter does.
+ */
+export interface AttemptInputs {
+    readonly outcome: AttemptOutcome;
+    readonly category?: AttemptCategory;
+    /**
+     * The run's signal has aborted — read when rule 3 is reached, so an abort raised inside `retryOn` is seen by
+     * the decision taken again after it. Always `true` for an `'aborted'` outcome.
+     */
+    readonly aborted: boolean;
+    /** This attempt, 1-based. */
+    readonly attempt: number;
+    /** The attempts the policy allows in total. */
+    readonly of: number;
+    readonly timeLeftMs: number;
+    /** The wait before the next attempt, from `backoffMs` (`0` when it is absent, invalid or throws). */
+    readonly delayMs: number;
+    readonly timeLeftAfterWaitMs: number;
+    /**
+     * The policy's `retryOn` verdict on this attempt's error (`true` when absent; a throw is `false`, and the
+     * record says it threw: `AttemptRecord.retryOnThrew`).
+     */
+    readonly retryOn: boolean;
+    /** Whether the target declared an idempotency key — never its value. */
+    readonly keyPresent: boolean;
+}
+/**
+ * One attempt — the unit of time and failure evidence. Frozen; survives `structuredClone`.
+ *
+ * Identity: `series` (the stage execution's `runtimeStageId` for a stage attempt) plus `attempt`.
+ */
+export interface AttemptRecord {
+    /** Logical workflow/pass link, stamped by an explicit retry helper; physical series/attempt stay unchanged. */
+    readonly retryLoop?: RetryLoopCall;
+    /**
+     * The series the attempt belongs to. A stage attempt: its execution's `runtimeStageId`. A call — `$call`, or an
+     * observed SDK call — made during stage attempt `n`: `<runtimeStageId>@<n>.<k>`, the `k`-th call of that attempt,
+     * so `<series>@<attempt>` is the attempt id of foottrace's grammar (design §3.4). A standalone `attempt()`: the
+     * caller's name for the operation.
+     */
+    readonly series: string;
+    readonly kind: AttemptKind;
+    /**
+     * The outside target of a `'call'` or `'observed'` attempt — a NAME from code (`'stripe.quotes.create'`), never
+     * a value. Absent on a stage attempt: its stage names it.
+     */
+    readonly target?: string;
+    /** Who ran an `'observed'` attempt — the report's `source` (`'sdk'` unless it said otherwise). Absent otherwise. */
+    readonly source?: string;
+    /** 1-based within the series. */
+    readonly attempt: number;
+    /** The attempts the policy allows in total. */
+    readonly of?: number;
+    /** Epoch milliseconds when the attempt started. */
+    readonly startedAt: number;
+    readonly durationMs: number;
+    /** How the attempt itself ended — never rewritten by what the series did next (see {@link AttemptOutcome}). */
+    readonly outcome: AttemptOutcome;
+    /**
+     * Present when the attempt failed, timed out or was aborted; absent for `'ok'` and `'paused'`. Read off the
+     * error as it stood when the decision was made (after `retryOn` ran), like `error`.
+     */
+    readonly category?: AttemptCategory;
+    /** The retry-or-stop decision — the evidence `decide()` would record for `retryRules(policy)`. */
+    readonly decision: DecisionEvidence;
+    /** `decision.chosen` — the compact projection a badge reads. */
+    readonly next: AttemptNext;
+    readonly reason: AttemptReason;
+    /**
+     * `true` when the policy's `retryOn` THREW on this attempt's error (absent otherwise). A throw is "do not
+     * retry", so the reason is `'declined'`; this flag keeps a broken predicate apart from a real `false`.
+     */
+    readonly retryOnThrew?: true;
+    /**
+     * The wait before the next attempt — present when the decision computed it: a retry, or (under a deadline) a
+     * `no-time-left` stop, whose wait would have outlasted the time left.
+     */
+    readonly delayMs?: number;
+    /**
+     * The cap this attempt ran under, in milliseconds — `min(RetryPolicy.timeoutMs, time left before the deadline)`
+     * at its start. Absent when neither was set (the attempt ran uncapped).
+     */
+    readonly timeoutMs?: number;
+    /** The time left before the run's deadline when the decision was made (negative once past). Absent without one. */
+    readonly timeLeftMs?: number;
+    /** The served error of an attempt that failed, timed out or was aborted. */
+    readonly error?: AttemptError;
+    /** The outside system a touching target names (P3). Absent for a target that touches nothing. */
+    readonly system?: string;
+    /**
+     * The key the attempt was made under, as the run SERVES it — retained under the diagnostic rule as
+     * `{ idempotencyKey }`, so a redaction rule of that name (or `policy.diagnostics`) scrubs it. Absent without a key.
+     */
+    readonly idempotencyKey?: string;
+    /** What the attempt did to the outside system (see {@link AttemptEffect}). Present only on a touching target. */
+    readonly effect?: AttemptEffect;
+}
+/**
+ * The attempt a function is running in — a stage's (`scope.$attempt()`, design §3.1), or a call's (the argument
+ * `scope.$call` and `attempt()` hand their function, P2). Never serialised: it holds a live signal.
+ *
+ * A stage with no retry policy and no deadline is attempt 1 of 1, with the run's signal (or one that never
+ * aborts) and `Infinity` left.
+ */
+export interface AttemptContext {
+    /** The series its record names (see {@link AttemptRecord.series}). */
+    readonly series: string;
+    /** This attempt, 1-based. */
+    readonly attempt: number;
+    /** The attempts the policy allows in total. */
+    readonly of: number;
+    /**
+     * Aborts when this attempt must stop: at its cap (`AttemptTimeoutError`), at the run's deadline, or when the run
+     * is cancelled. Pass it to `fetch` and SDK calls — the engine stops waiting at the cap either way, but only the
+     * function can stop its own work.
+     */
+    readonly signal: AbortSignal;
+    /** The run's deadline, epoch milliseconds — absent without one. */
+    readonly deadline?: number;
+    /** The cap this attempt runs under (see {@link AttemptRecord.timeoutMs}) — absent when uncapped. */
+    readonly timeoutMs?: number;
+    /** The outside system this attempt touches (P3) — absent when it touches none. */
+    readonly system?: string;
+    /**
+     * The key this attempt must be made under — the REAL key, computed once per execution from the declared rule (or
+     * the `$call`'s option). Pass it to the system (`{ idempotencyKey }`), so a retry, a resume and a caller's retry
+     * all name one operation. Absent without a key. Records carry its served form.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * Milliseconds before the run's deadline — `Infinity` without one. Read through the scope, it marks the stage's
+     * commit `untrackedSources: ['env']` when a deadline exists: time is an input the record cannot replay.
+     */
+    timeLeftMs(): number;
+    /**
+     * Report an attempt an outside system ran ON ITS OWN — an SDK's internal retry (design §3.6, P2). It becomes an
+     * `AttemptRecord` of kind `'observed'` beside this attempt's evidence, and fires `onAttempt`; it never changes
+     * control flow — in either direction: a report that comes after this attempt ended (an SDK's callback firing
+     * late) is dropped and recorded by name (`lateWrites`), never thrown. Only the report's named fields are read; its
+     * error is served under the run's redaction rule, and no hook is handed the error object itself. A malformed
+     * report is the adapter's bug: a `TypeError` naming the field. Prefer one loop: turn the SDK's own retries off and
+     * run the call under `scope.$call`.
+     */
+    observed(report: ObservedAttempt): void;
+}
+/**
+ * An attempt an outside system ran on its own, as an adapter reports it (`AttemptContext.observed`). Only these
+ * fields are read — each once; anything else on the object is dropped.
+ *
+ * A report with `of` stands for one attempt of the SDK's series; a report without one stands for the SDK's WHOLE
+ * call, its count unknown — "the SDK ran this" rather than a pretended count.
+ */
+export interface ObservedAttempt {
+    /** The outside target — a name from code: 1–128 characters, no control, format or line-separator character. */
+    readonly target: string;
+    /** Which attempt of the SDK's own series, 1-based. Default `1`. */
+    readonly attempt?: number;
+    /** The attempts the SDK allows in total, when it says (≥ `attempt`). */
+    readonly of?: number;
+    /** How the SDK's attempt ended. An SDK cannot pause a flowchart, so `'paused'` is refused. */
+    readonly outcome: Exclude<AttemptOutcome, 'paused'>;
+    /** How long it took, milliseconds — finite and ≥ 0. */
+    readonly durationMs: number;
+    /** When it started, epoch milliseconds. Default: the report's arrival minus `durationMs`. */
+    readonly startedAt?: number;
+    /** Who ran it — a name like `target`. Default `'sdk'`. */
+    readonly source?: string;
+    /** The error of an attempt that did not succeed — served under the run's redaction rule, never kept as thrown. */
+    readonly error?: unknown;
+}
+/**
+ * A write, emit, diagnostic, detach or call an attempt tried AFTER it had ended — timed out, aborted or failed —
+ * dropped at the scope and recorded on its stage (`StageSnapshot.lateWrites`, the first 100 —
+ * `StageContext · MAX_LATE_WRITES`). A name, never the value.
+ */
+export interface LateWrite {
+    /** The attempt that wrote late, 1-based. */
+    readonly attempt: number;
+    /**
+     * The state key (a dotted path for a nested write), the emitted event's name (a diagnostic's emit name —
+     * `log.debug.<key>`, `metric.<name>` — for `$debug` / `$metric` / …), `detach:<child root id>`, or — on the
+     * `'attempt'` channel (P2) — `call:<target>` (a `$call` started, or a call's record arriving, after its attempt
+     * ended) or `observed:<target>` (an observed report after it).
+     */
+    readonly key: string;
+    readonly channel: 'state' | 'emit' | 'detach' | 'attempt';
+}
+/**
+ * A series at a glance — stamped once, when the series ends (the Lens badge, §3.10). `last` is how it ended:
+ * the last record's `next` / `reason` (and `category`, `retryOnThrew`), or `stop` / `aborted` when the run's
+ * signal cut a wait (no attempt followed, so none is recorded).
+ *
+ * The SERIES' outcome, not the STAGE's. `last.next: 'done'` says the stage function returned; the stage can
+ * still fail after that — its commit can fail (a value nothing can clone), and a StageNode it returned can be
+ * refused at the run-time door (R5) — and then its `onError` fires with this summary unchanged. Whether the
+ * stage failed is the execution's own fact (its error), never read off this summary.
+ */
+export interface AttemptSummary {
+    readonly count: number;
+    readonly ok: number;
+    readonly failed: number;
+    readonly timeout: number;
+    readonly aborted: number;
+    readonly paused: number;
+    readonly last: {
+        readonly next: Exclude<AttemptNext, 'retry'>;
+        readonly reason: AttemptReason;
+        readonly category?: AttemptCategory;
+        readonly retryOnThrew?: true;
+        /** The series' effect — `unknown` once any attempt left it unknown, unless the series ended with an answer. Touching targets only. */
+        readonly effect?: AttemptEffect;
+    };
+}
+/**
+ * The run's correlation — which outside trace and unit of work this run belongs to (design §3.4). Resolved ONCE
+ * per leg (`run()`, and each `resume()`) from the env by `attempt/correlation.ts · resolveCorrelation`, frozen, and
+ * handed by reference to `RuntimeSnapshot.correlation`, every flow event's `TraversalContext.correlation`, and
+ * every scope and emit event's `correlation`. Absent — no key anywhere — when the env gives none.
+ *
+ * Correlation only: a NAME the record carries so a run can be found from a trace. Never identity, never
+ * authorisation — a `traceparent` comes from whoever sent the request.
+ */
+export interface RunCorrelation {
+    /** `env.traceId`, else the trace id of `env.traceparent` (32 lowercase hex). */
+    readonly traceId: string;
+    /** `env.operationId`, else the header's parent-id (only while the trace is the header's): the caller's unit of work. */
+    readonly operationId?: string;
+    /** The header's sampled flag (bit 0 of trace-flags) — present only while the trace is the header's. A hint. */
+    readonly sampled?: boolean;
+    /**
+     * The canonical header of the EFFECTIVE ids (`formatTraceparent`) — for propagating the trace onward. Present
+     * only while the trace is the header's and the operation is a W3C parent-id; never the received bytes.
+     */
+    readonly traceparent?: string;
+}