footprintjs 10.0.1 → 10.2.0

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

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function attemptCeiling(attempts) {
+    const whole = typeof attempts === 'number' ? Math.floor(attempts) : NaN;
+    return Number.isFinite(whole) && whole >= 1 ? whole : 1;
+}
+/**
+ * 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 function retryPolicyProblem(retry) {
+    const { attempts, timeoutMs, maxBackoffMs } = retry;
+    if (!(typeof attempts === 'number' && Number.isInteger(attempts) && attempts >= 1)) {
+        return (`retry.attempts must be a whole number >= 1 (got ${String(attempts)}). ` +
+            'It counts TOTAL runs including the first, so `attempts: 3` means one run plus up to two retries; ' +
+            '`attempts: 1` means the policy is declared but currently off.');
+    }
+    if (timeoutMs !== undefined && attemptTimeoutMs(timeoutMs) === undefined) {
+        return (`retry.timeoutMs must be a finite number of milliseconds > 0 (got ${String(timeoutMs)}). ` +
+            'It caps ONE attempt; leave it out for an uncapped attempt.');
+    }
+    if (maxBackoffMs !== undefined && backoffCeilingMs(maxBackoffMs) === undefined) {
+        return (`retry.maxBackoffMs must be a finite number of milliseconds >= 0 (got ${String(maxBackoffMs)}). ` +
+            'It caps every wait between attempts; leave it out for an uncapped wait.');
+    }
+    return 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 function backoffCeilingMs(maxBackoffMs) {
+    return typeof maxBackoffMs === 'number' && Number.isFinite(maxBackoffMs) && maxBackoffMs >= 0
+        ? maxBackoffMs
+        : undefined;
+}
+/** A wait the policy's `backoffMs` answered (already defended, `resolveBackoffMs`), capped at its declared ceiling. */
+export function cappedWaitMs(waitMs, maxBackoffMs) {
+    const ceiling = backoffCeilingMs(maxBackoffMs);
+    return ceiling === undefined ? waitMs : Math.min(waitMs, ceiling);
+}
+/**
+ * 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 function attemptTimeoutMs(timeoutMs) {
+    return typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
+}
+/** The policy of a call made with none: one attempt — still recorded (a single call is evidence too). */
+export const SINGLE_CALL = Object.freeze({ attempts: 1 });
+/**
+ * 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 function admitCallPolicy(where, policy) {
+    if (policy === undefined)
+        return SINGLE_CALL;
+    if (policy === null || typeof policy !== 'object') {
+        throw new TypeError(`${where}: the policy must be a RetryPolicy object ({ attempts, timeoutMs?, backoffMs?, retryOn? })`);
+    }
+    const problem = retryPolicyProblem(policy);
+    if (problem !== undefined)
+        throw new TypeError(`${where}: ${problem}`);
+    return policy;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9saWN5LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2xpYi9hdHRlbXB0L3BvbGljeS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7OztHQVVHO0FBSUg7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxjQUFjLENBQUMsUUFBaUI7SUFDOUMsTUFBTSxLQUFLLEdBQUcsT0FBTyxRQUFRLEtBQUssUUFBUSxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsQ0FBQyxHQUFHLENBQUM7SUFDeEUsT0FBTyxNQUFNLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxJQUFJLEtBQUssSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQzFELENBQUM7QUFFRDs7OztHQUlHO0FBQ0gsTUFBTSxVQUFVLGtCQUFrQixDQUNoQyxLQUFtRTtJQUVuRSxNQUFNLEVBQUUsUUFBUSxFQUFFLFNBQVMsRUFBRSxZQUFZLEVBQUUsR0FBRyxLQUFLLENBQUM7SUFDcEQsSUFBSSxDQUFDLENBQUMsT0FBTyxRQUFRLEtBQUssUUFBUSxJQUFJLE1BQU0sQ0FBQyxTQUFTLENBQUMsUUFBUSxDQUFDLElBQUksUUFBUSxJQUFJLENBQUMsQ0FBQyxFQUFFLENBQUM7UUFDbkYsT0FBTyxDQUNMLG1EQUFtRCxNQUFNLENBQUMsUUFBUSxDQUFDLEtBQUs7WUFDeEUsbUdBQW1HO1lBQ25HLCtEQUErRCxDQUNoRSxDQUFDO0lBQ0osQ0FBQztJQUNELElBQUksU0FBUyxLQUFLLFNBQVMsSUFBSSxnQkFBZ0IsQ0FBQyxTQUFTLENBQUMsS0FBSyxTQUFTLEVBQUUsQ0FBQztRQUN6RSxPQUFPLENBQ0wsb0VBQW9FLE1BQU0sQ0FBQyxTQUFTLENBQUMsS0FBSztZQUMxRiw0REFBNEQsQ0FDN0QsQ0FBQztJQUNKLENBQUM7SUFDRCxJQUFJLFlBQVksS0FBSyxTQUFTLElBQUksZ0JBQWdCLENBQUMsWUFBWSxDQUFDLEtBQUssU0FBUyxFQUFFLENBQUM7UUFDL0UsT0FBTyxDQUNMLHdFQUF3RSxNQUFNLENBQUMsWUFBWSxDQUFDLEtBQUs7WUFDakcseUVBQXlFLENBQzFFLENBQUM7SUFDSixDQUFDO0lBQ0QsT0FBTyxTQUFTLENBQUM7QUFDbkIsQ0FBQztBQUVEOzs7O0dBSUc7QUFDSCxNQUFNLFVBQVUsZ0JBQWdCLENBQUMsWUFBcUI7SUFDcEQsT0FBTyxPQUFPLFlBQVksS0FBSyxRQUFRLElBQUksTUFBTSxDQUFDLFFBQVEsQ0FBQyxZQUFZLENBQUMsSUFBSSxZQUFZLElBQUksQ0FBQztRQUMzRixDQUFDLENBQUMsWUFBWTtRQUNkLENBQUMsQ0FBQyxTQUFTLENBQUM7QUFDaEIsQ0FBQztBQUVELHVIQUF1SDtBQUN2SCxNQUFNLFVBQVUsWUFBWSxDQUFDLE1BQWMsRUFBRSxZQUFxQjtJQUNoRSxNQUFNLE9BQU8sR0FBRyxnQkFBZ0IsQ0FBQyxZQUFZLENBQUMsQ0FBQztJQUMvQyxPQUFPLE9BQU8sS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxNQUFNLEVBQUUsT0FBTyxDQUFDLENBQUM7QUFDcEUsQ0FBQztBQUVEOzs7R0FHRztBQUNILE1BQU0sVUFBVSxnQkFBZ0IsQ0FBQyxTQUFrQjtJQUNqRCxPQUFPLE9BQU8sU0FBUyxLQUFLLFFBQVEsSUFBSSxNQUFNLENBQUMsUUFBUSxDQUFDLFNBQVMsQ0FBQyxJQUFJLFNBQVMsR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDO0FBQzlHLENBQUM7QUFFRCx5R0FBeUc7QUFDekcsTUFBTSxDQUFDLE1BQU0sV0FBVyxHQUFnQixNQUFNLENBQUMsTUFBTSxDQUFDLEVBQUUsUUFBUSxFQUFFLENBQUMsRUFBRSxDQUFDLENBQUM7QUFFdkU7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxlQUFlLENBQUMsS0FBYSxFQUFFLE1BQWU7SUFDNUQsSUFBSSxNQUFNLEtBQUssU0FBUztRQUFFLE9BQU8sV0FBVyxDQUFDO0lBQzdDLElBQUksTUFBTSxLQUFLLElBQUksSUFBSSxPQUFPLE1BQU0sS0FBSyxRQUFRLEVBQUUsQ0FBQztRQUNsRCxNQUFNLElBQUksU0FBUyxDQUNqQixHQUFHLEtBQUssNEZBQTRGLENBQ3JHLENBQUM7SUFDSixDQUFDO0lBQ0QsTUFBTSxPQUFPLEdBQUcsa0JBQWtCLENBQUMsTUFBcUIsQ0FBQyxDQUFDO0lBQzFELElBQUksT0FBTyxLQUFLLFNBQVM7UUFBRSxNQUFNLElBQUksU0FBUyxDQUFDLEdBQUcsS0FBSyxLQUFLLE9BQU8sRUFBRSxDQUFDLENBQUM7SUFDdkUsT0FBTyxNQUFxQixDQUFDO0FBQy9CLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIGF0dGVtcHQvcG9saWN5LnRzIOKAlCB0aGUgT05FIHJlYWRpbmcgb2YgYSBgUmV0cnlQb2xpY3lgJ3MgY2VpbGluZywgYW5kIHRoZSBPTkUgcnVsZSBmb3IgYSB2YWxpZCBwb2xpY3kuXG4gKlxuICogYGF0dGVtcHRDZWlsaW5nYCBpcyBob3cgbWFueSBhdHRlbXB0cyBhIHBvbGljeSBhbGxvd3MuIFRocmVlIHJlYWRlcnMgYXNrIGl0LCBzbyB0aGV5IGNhbiBuZXZlciBkaXNhZ3JlZSBhYm91dCBhXG4gKiBzdGFnZTogdGhlIGVuZ2luZSdzIGdhdGUgKGBGbG93Y2hhcnRUcmF2ZXJzZXIgwrcgZXhlY3V0ZVN0YWdlYCDigJQgZG9lcyB0aGlzIHN0YWdlIHJldHJ5IGF0IGFsbD8pLCB0aGUgcnVubmVyXG4gKiAoYHJ1bkF0dGVtcHRzYCDigJQgZXZlcnkgcmVjb3JkJ3MgYG9mYCkgYW5kIHRoZSBydWxlIHRhYmxlIChgcmV0cnlSdWxlc2Ag4oCUIHJ1bGUgNCdzIHRocmVzaG9sZCkuXG4gKlxuICogYHJldHJ5UG9saWN5UHJvYmxlbWAgc2F5cyB3aHkgYSBkZWNsYXJlZCBwb2xpY3kgaXMgcmVmdXNlZC4gVHdvIGRvb3JzIGFzayBpdCwgd2l0aCB0aGUgc2FtZSB3b3JkczogdGhlIGJ1aWxkZXJcbiAqIGF0IGJ1aWxkIChgRmxvd0NoYXJ0QnVpbGRlciDCtyBhcHBseVJldHJ5UG9saWN5YCksIGFuZCB0aGUgdHJhdmVyc2VyIGZvciBhIFN0YWdlTm9kZSBhIHN0YWdlIHJldHVybnMgYXQgcnVuIHRpbWVcbiAqIChgRmxvd2NoYXJ0VHJhdmVyc2VyIMK3IGFkbWl0RHluYW1pY05vZGVzYCksIHdoaWNoIHRoZSBidWlsZGVyIG5ldmVyIHNhdy5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7IFJldHJ5UG9saWN5IH0gZnJvbSAnLi90eXBlcy5qcyc7XG5cbi8qKlxuICogVGhlIGF0dGVtcHRzIGEgcG9saWN5IGFsbG93czogaXRzIHdob2xlIG51bWJlciAoYSBmcmFjdGlvbiBpcyBmbG9vcmVkLCBhcyB0aGUgOS4xNSBsb29wIHJlYWQgaXQpLCBhbmQgbmV2ZXJcbiAqIGZld2VyIHRoYW4gb25lLiBBbnl0aGluZyB0aGF0IGlzIG5vdCBhIGZpbml0ZSBudW1iZXIgb2YgYXQgbGVhc3Qgb25lIOKAlCBgTmFOYCwgYEluZmluaXR5YCwgYDBgLCBhIG5lZ2F0aXZlLCBhXG4gKiBub24tbnVtYmVyIOKAlCBpcyBgMWA6IGEgYnJva2VuIGNlaWxpbmcgbmV2ZXIgbG9vcHMuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBhdHRlbXB0Q2VpbGluZyhhdHRlbXB0czogdW5rbm93bik6IG51bWJlciB7XG4gIGNvbnN0IHdob2xlID0gdHlwZW9mIGF0dGVtcHRzID09PSAnbnVtYmVyJyA/IE1hdGguZmxvb3IoYXR0ZW1wdHMpIDogTmFOO1xuICByZXR1cm4gTnVtYmVyLmlzRmluaXRlKHdob2xlKSAmJiB3aG9sZSA+PSAxID8gd2hvbGUgOiAxO1xufVxuXG4vKipcbiAqIFdoeSBgcmV0cnlgIGlzIHJlZnVzZWQsIG9yIGB1bmRlZmluZWRgIHdoZW4gaXQgaXMgYSB2YWxpZCBwb2xpY3k6IGBhdHRlbXB0c2AgbXVzdCBiZSBhIHdob2xlIG51bWJlciDiiaUgMSwgYVxuICogZGVjbGFyZWQgYHRpbWVvdXRNc2AgYSBmaW5pdGUgbnVtYmVyID4gMCwgYW5kIGEgZGVjbGFyZWQgYG1heEJhY2tvZmZNc2AgYSBmaW5pdGUgbnVtYmVyIOKJpSAwLiBgYXR0ZW1wdHM6IDFgIGlzXG4gKiB2YWxpZCBvbiBwdXJwb3NlIOKAlCBhIHBvbGljeSBkZWNsYXJlZCBidXQgc3dpdGNoZWQgb2ZmIChvciwgd2l0aCBhIGB0aW1lb3V0TXNgLCBhIHRpbWVvdXQgd2l0aCBubyByZXRyeSkuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXRyeVBvbGljeVByb2JsZW0oXG4gIHJldHJ5OiBQaWNrPFJldHJ5UG9saWN5LCAnYXR0ZW1wdHMnIHwgJ3RpbWVvdXRNcycgfCAnbWF4QmFja29mZk1zJz4sXG4pOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICBjb25zdCB7IGF0dGVtcHRzLCB0aW1lb3V0TXMsIG1heEJhY2tvZmZNcyB9ID0gcmV0cnk7XG4gIGlmICghKHR5cGVvZiBhdHRlbXB0cyA9PT0gJ251bWJlcicgJiYgTnVtYmVyLmlzSW50ZWdlcihhdHRlbXB0cykgJiYgYXR0ZW1wdHMgPj0gMSkpIHtcbiAgICByZXR1cm4gKFxuICAgICAgYHJldHJ5LmF0dGVtcHRzIG11c3QgYmUgYSB3aG9sZSBudW1iZXIgPj0gMSAoZ290ICR7U3RyaW5nKGF0dGVtcHRzKX0pLiBgICtcbiAgICAgICdJdCBjb3VudHMgVE9UQUwgcnVucyBpbmNsdWRpbmcgdGhlIGZpcnN0LCBzbyBgYXR0ZW1wdHM6IDNgIG1lYW5zIG9uZSBydW4gcGx1cyB1cCB0byB0d28gcmV0cmllczsgJyArXG4gICAgICAnYGF0dGVtcHRzOiAxYCBtZWFucyB0aGUgcG9saWN5IGlzIGRlY2xhcmVkIGJ1dCBjdXJyZW50bHkgb2ZmLidcbiAgICApO1xuICB9XG4gIGlmICh0aW1lb3V0TXMgIT09IHVuZGVmaW5lZCAmJiBhdHRlbXB0VGltZW91dE1zKHRpbWVvdXRNcykgPT09IHVuZGVmaW5lZCkge1xuICAgIHJldHVybiAoXG4gICAgICBgcmV0cnkudGltZW91dE1zIG11c3QgYmUgYSBmaW5pdGUgbnVtYmVyIG9mIG1pbGxpc2Vjb25kcyA+IDAgKGdvdCAke1N0cmluZyh0aW1lb3V0TXMpfSkuIGAgK1xuICAgICAgJ0l0IGNhcHMgT05FIGF0dGVtcHQ7IGxlYXZlIGl0IG91dCBmb3IgYW4gdW5jYXBwZWQgYXR0ZW1wdC4nXG4gICAgKTtcbiAgfVxuICBpZiAobWF4QmFja29mZk1zICE9PSB1bmRlZmluZWQgJiYgYmFja29mZkNlaWxpbmdNcyhtYXhCYWNrb2ZmTXMpID09PSB1bmRlZmluZWQpIHtcbiAgICByZXR1cm4gKFxuICAgICAgYHJldHJ5Lm1heEJhY2tvZmZNcyBtdXN0IGJlIGEgZmluaXRlIG51bWJlciBvZiBtaWxsaXNlY29uZHMgPj0gMCAoZ290ICR7U3RyaW5nKG1heEJhY2tvZmZNcyl9KS4gYCArXG4gICAgICAnSXQgY2FwcyBldmVyeSB3YWl0IGJldHdlZW4gYXR0ZW1wdHM7IGxlYXZlIGl0IG91dCBmb3IgYW4gdW5jYXBwZWQgd2FpdC4nXG4gICAgKTtcbiAgfVxuICByZXR1cm4gdW5kZWZpbmVkO1xufVxuXG4vKipcbiAqIFRoZSBjZWlsaW5nIGEgcG9saWN5IHB1dHMgb24gT05FIHdhaXQgKGBtYXhCYWNrb2ZmTXNgKTogYSBmaW5pdGUgbnVtYmVyIOKJpSAwLCBlbHNlIG5vbmUuIFRoZSBydW5uZXIgY2FwcyBldmVyeVxuICogd2FpdCBhdCBpdCAoYHdhaXRBZnRlcmApLCBhbmQgdGhlIHN0YXRpYyBidWRnZXQgY2hlY2sgY291bnRzIGVhY2ggd2FpdCBhdCBpdCDigJQgb25lIHJlYWRpbmcsIHNvIHRoZSBjaGVjaydzIGJvdW5kXG4gKiBpcyB0aGUgcnVubmVyJ3MgbGF3LlxuICovXG5leHBvcnQgZnVuY3Rpb24gYmFja29mZkNlaWxpbmdNcyhtYXhCYWNrb2ZmTXM6IHVua25vd24pOiBudW1iZXIgfCB1bmRlZmluZWQge1xuICByZXR1cm4gdHlwZW9mIG1heEJhY2tvZmZNcyA9PT0gJ251bWJlcicgJiYgTnVtYmVyLmlzRmluaXRlKG1heEJhY2tvZmZNcykgJiYgbWF4QmFja29mZk1zID49IDBcbiAgICA/IG1heEJhY2tvZmZNc1xuICAgIDogdW5kZWZpbmVkO1xufVxuXG4vKiogQSB3YWl0IHRoZSBwb2xpY3kncyBgYmFja29mZk1zYCBhbnN3ZXJlZCAoYWxyZWFkeSBkZWZlbmRlZCwgYHJlc29sdmVCYWNrb2ZmTXNgKSwgY2FwcGVkIGF0IGl0cyBkZWNsYXJlZCBjZWlsaW5nLiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGNhcHBlZFdhaXRNcyh3YWl0TXM6IG51bWJlciwgbWF4QmFja29mZk1zOiB1bmtub3duKTogbnVtYmVyIHtcbiAgY29uc3QgY2VpbGluZyA9IGJhY2tvZmZDZWlsaW5nTXMobWF4QmFja29mZk1zKTtcbiAgcmV0dXJuIGNlaWxpbmcgPT09IHVuZGVmaW5lZCA/IHdhaXRNcyA6IE1hdGgubWluKHdhaXRNcywgY2VpbGluZyk7XG59XG5cbi8qKlxuICogVGhlIGNhcCBhIHBvbGljeSBwdXRzIG9uIG9uZSBhdHRlbXB0OiBhIGZpbml0ZSBudW1iZXIgPiAwLCBlbHNlIG5vbmUuIFRoZSBvbmUgcmVhZGluZyB0aGUgZW5naW5lJ3MgZ2F0ZSBhbmQgdGhlXG4gKiBydW5uZXIgc2hhcmUgKHRoZSBidWlsZGVyIHJlZnVzZXMgYW55IG90aGVyIGRlY2xhcmVkIHZhbHVlLCBgcmV0cnlQb2xpY3lQcm9ibGVtYCkuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBhdHRlbXB0VGltZW91dE1zKHRpbWVvdXRNczogdW5rbm93bik6IG51bWJlciB8IHVuZGVmaW5lZCB7XG4gIHJldHVybiB0eXBlb2YgdGltZW91dE1zID09PSAnbnVtYmVyJyAmJiBOdW1iZXIuaXNGaW5pdGUodGltZW91dE1zKSAmJiB0aW1lb3V0TXMgPiAwID8gdGltZW91dE1zIDogdW5kZWZpbmVkO1xufVxuXG4vKiogVGhlIHBvbGljeSBvZiBhIGNhbGwgbWFkZSB3aXRoIG5vbmU6IG9uZSBhdHRlbXB0IOKAlCBzdGlsbCByZWNvcmRlZCAoYSBzaW5nbGUgY2FsbCBpcyBldmlkZW5jZSB0b28pLiAqL1xuZXhwb3J0IGNvbnN0IFNJTkdMRV9DQUxMOiBSZXRyeVBvbGljeSA9IE9iamVjdC5mcmVlemUoeyBhdHRlbXB0czogMSB9KTtcblxuLyoqXG4gKiBBIGAkY2FsbGAgLyBgYXR0ZW1wdCgpYCBwb2xpY3kgYXMgdGhlIGNhbGxlciBoYW5kZWQgaXQ6IGFic2VudCBtZWFucyB7QGxpbmsgU0lOR0xFX0NBTEx9OyBhbnl0aGluZyBlbHNlIG11c3QgYmUgYVxuICogdmFsaWQgYFJldHJ5UG9saWN5YCAoYHJldHJ5UG9saWN5UHJvYmxlbWApIG9yIGl0IGlzIHJlZnVzZWQgd2l0aCBhIGBUeXBlRXJyb3JgIG5hbWluZyBgd2hlcmVgIOKAlCBhdCB0aGUgY2FsbCxcbiAqIGJlZm9yZSBhbnl0aGluZyBydW5zLlxuICovXG5leHBvcnQgZnVuY3Rpb24gYWRtaXRDYWxsUG9saWN5KHdoZXJlOiBzdHJpbmcsIHBvbGljeTogdW5rbm93bik6IFJldHJ5UG9saWN5IHtcbiAgaWYgKHBvbGljeSA9PT0gdW5kZWZpbmVkKSByZXR1cm4gU0lOR0xFX0NBTEw7XG4gIGlmIChwb2xpY3kgPT09IG51bGwgfHwgdHlwZW9mIHBvbGljeSAhPT0gJ29iamVjdCcpIHtcbiAgICB0aHJvdyBuZXcgVHlwZUVycm9yKFxuICAgICAgYCR7d2hlcmV9OiB0aGUgcG9saWN5IG11c3QgYmUgYSBSZXRyeVBvbGljeSBvYmplY3QgKHsgYXR0ZW1wdHMsIHRpbWVvdXRNcz8sIGJhY2tvZmZNcz8sIHJldHJ5T24/IH0pYCxcbiAgICApO1xuICB9XG4gIGNvbnN0IHByb2JsZW0gPSByZXRyeVBvbGljeVByb2JsZW0ocG9saWN5IGFzIFJldHJ5UG9saWN5KTtcbiAgaWYgKHByb2JsZW0gIT09IHVuZGVmaW5lZCkgdGhyb3cgbmV3IFR5cGVFcnJvcihgJHt3aGVyZX06ICR7cHJvYmxlbX1gKTtcbiAgcmV0dXJuIHBvbGljeSBhcyBSZXRyeVBvbGljeTtcbn1cbiJdfQ==

package/dist/esm/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/esm/lib/attempt/record.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/** The record's copy of a served error: its named fields only — never `raw`, never an extra own key. */
+export function recordedError(served) {
+    return {
+        message: served.message,
+        ...(served.name !== undefined && { name: served.name }),
+        ...(served.code !== undefined && { code: served.code }),
+        ...(served.issues !== undefined && { issues: served.issues.map((issue) => ({ ...issue, path: [...issue.path] })) }),
+    };
+}
+/** Freeze a record built of plain objects and arrays, to its leaves. */
+export function freezeDeep(value) {
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const key of Object.keys(value))
+            freezeDeep(value[key]);
+    }
+    return value;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVjb3JkLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2xpYi9hdHRlbXB0L3JlY29yZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7OztHQUlHO0FBS0gsd0dBQXdHO0FBQ3hHLE1BQU0sVUFBVSxhQUFhLENBQUMsTUFBMkI7SUFDdkQsT0FBTztRQUNMLE9BQU8sRUFBRSxNQUFNLENBQUMsT0FBTztRQUN2QixHQUFHLENBQUMsTUFBTSxDQUFDLElBQUksS0FBSyxTQUFTLElBQUksRUFBRSxJQUFJLEVBQUUsTUFBTSxDQUFDLElBQUksRUFBRSxDQUFDO1FBQ3ZELEdBQUcsQ0FBQyxNQUFNLENBQUMsSUFBSSxLQUFLLFNBQVMsSUFBSSxFQUFFLElBQUksRUFBRSxNQUFNLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDdkQsR0FBRyxDQUFDLE1BQU0sQ0FBQyxNQUFNLEtBQUssU0FBUyxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUMsS0FBSyxFQUFFLEVBQUUsQ0FBQyxDQUFDLEVBQUUsR0FBRyxLQUFLLEVBQUUsSUFBSSxFQUFFLENBQUMsR0FBRyxLQUFLLENBQUMsSUFBSSxDQUFDLEVBQUUsQ0FBQyxDQUFDLEVBQUUsQ0FBQztLQUNwSCxDQUFDO0FBQ0osQ0FBQztBQUVELHdFQUF3RTtBQUN4RSxNQUFNLFVBQVUsVUFBVSxDQUFJLEtBQVE7SUFDcEMsSUFBSSxLQUFLLEtBQUssSUFBSSxJQUFJLE9BQU8sS0FBSyxLQUFLLFFBQVEsSUFBSSxDQUFDLE1BQU0sQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUMzRSxNQUFNLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQ3JCLEtBQUssTUFBTSxHQUFHLElBQUksTUFBTSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUM7WUFBRSxVQUFVLENBQUUsS0FBaUMsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDO0lBQzVGLENBQUM7SUFDRCxPQUFPLEtBQUssQ0FBQztBQUNmLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIGF0dGVtcHQvcmVjb3JkLnRzIOKAlCBob3cgYW4gYEF0dGVtcHRSZWNvcmRgIGhvbGRzIHdoYXQgaXQgaG9sZHM6IGZyb3plbiB0byBpdHMgbGVhdmVzLCBhbmQgYW4gZXJyb3Igb25seSBhcyB0aGUgcnVuXG4gKiBTRVJWRVMgaXQsIG5hbWVkIGZpZWxkcyBvbmx5LiBPbmUgb3duZXIsIHNvIGEgcmVjb3JkIHRoZSBydW5uZXIgbWFrZXMgKGBydW5uZXIudHNgKSBhbmQgYSByZWNvcmQgYW4gYWRhcHRlclxuICogcmVwb3J0cyAoYG9ic2VydmVkLnRzYCkgY2FuIG5ldmVyIGRpZmZlciBpbiB3aGF0IHRoZXkga2VlcC5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7IFN0cnVjdHVyZWRFcnJvckluZm8gfSBmcm9tICcuLi9lcnJvcnMvZXJyb3JJbmZvLmpzJztcbmltcG9ydCB0eXBlIHsgQXR0ZW1wdEVycm9yIH0gZnJvbSAnLi90eXBlcy5qcyc7XG5cbi8qKiBUaGUgcmVjb3JkJ3MgY29weSBvZiBhIHNlcnZlZCBlcnJvcjogaXRzIG5hbWVkIGZpZWxkcyBvbmx5IOKAlCBuZXZlciBgcmF3YCwgbmV2ZXIgYW4gZXh0cmEgb3duIGtleS4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZWNvcmRlZEVycm9yKHNlcnZlZDogU3RydWN0dXJlZEVycm9ySW5mbyk6IEF0dGVtcHRFcnJvciB7XG4gIHJldHVybiB7XG4gICAgbWVzc2FnZTogc2VydmVkLm1lc3NhZ2UsXG4gICAgLi4uKHNlcnZlZC5uYW1lICE9PSB1bmRlZmluZWQgJiYgeyBuYW1lOiBzZXJ2ZWQubmFtZSB9KSxcbiAgICAuLi4oc2VydmVkLmNvZGUgIT09IHVuZGVmaW5lZCAmJiB7IGNvZGU6IHNlcnZlZC5jb2RlIH0pLFxuICAgIC4uLihzZXJ2ZWQuaXNzdWVzICE9PSB1bmRlZmluZWQgJiYgeyBpc3N1ZXM6IHNlcnZlZC5pc3N1ZXMubWFwKChpc3N1ZSkgPT4gKHsgLi4uaXNzdWUsIHBhdGg6IFsuLi5pc3N1ZS5wYXRoXSB9KSkgfSksXG4gIH07XG59XG5cbi8qKiBGcmVlemUgYSByZWNvcmQgYnVpbHQgb2YgcGxhaW4gb2JqZWN0cyBhbmQgYXJyYXlzLCB0byBpdHMgbGVhdmVzLiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGZyZWV6ZURlZXA8VD4odmFsdWU6IFQpOiBUIHtcbiAgaWYgKHZhbHVlICE9PSBudWxsICYmIHR5cGVvZiB2YWx1ZSA9PT0gJ29iamVjdCcgJiYgIU9iamVjdC5pc0Zyb3plbih2YWx1ZSkpIHtcbiAgICBPYmplY3QuZnJlZXplKHZhbHVlKTtcbiAgICBmb3IgKGNvbnN0IGtleSBvZiBPYmplY3Qua2V5cyh2YWx1ZSkpIGZyZWV6ZURlZXAoKHZhbHVlIGFzIFJlY29yZDxzdHJpbmcsIHVua25vd24+KVtrZXldKTtcbiAgfVxuICByZXR1cm4gdmFsdWU7XG59XG4iXX0=

package/dist/esm/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/esm/lib/attempt/retryLoopContext.js

@@ -0,0 +1,24 @@
+const calls = new WeakMap();
+export function registerRetryLoopCall(target, port) {
+    if (calls.has(target))
+        throw new Error('retry loop: another call is already being prepared on this scope');
+    calls.set(target, port);
+    return () => {
+        if (calls.get(target) === port)
+            calls.delete(target);
+    };
+}
+/** Claimed once, so nested calls made by the user's callback do not inherit the outer call's logical identity. */
+export function takeRetryLoopCall(target) {
+    const port = calls.get(target);
+    calls.delete(target);
+    return port;
+}
+const budgets = new WeakMap();
+export function declareRetryLoopBudget(node, budget) {
+    budgets.set(node, Object.freeze({ ...budget }));
+}
+export function retryLoopBudget(node) {
+    return budgets.get(node);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmV0cnlMb29wQ29udGV4dC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uL3NyYy9saWIvYXR0ZW1wdC9yZXRyeUxvb3BDb250ZXh0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQVNBLE1BQU0sS0FBSyxHQUFHLElBQUksT0FBTyxFQUE2QixDQUFDO0FBRXZELE1BQU0sVUFBVSxxQkFBcUIsQ0FBQyxNQUFjLEVBQUUsSUFBdUI7SUFDM0UsSUFBSSxLQUFLLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQztRQUFFLE1BQU0sSUFBSSxLQUFLLENBQUMsa0VBQWtFLENBQUMsQ0FBQztJQUMzRyxLQUFLLENBQUMsR0FBRyxDQUFDLE1BQU0sRUFBRSxJQUFJLENBQUMsQ0FBQztJQUN4QixPQUFPLEdBQUcsRUFBRTtRQUNWLElBQUksS0FBSyxDQUFDLEdBQUcsQ0FBQyxNQUFNLENBQUMsS0FBSyxJQUFJO1lBQUUsS0FBSyxDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUN2RCxDQUFDLENBQUM7QUFDSixDQUFDO0FBRUQsa0hBQWtIO0FBQ2xILE1BQU0sVUFBVSxpQkFBaUIsQ0FBQyxNQUFjO0lBQzlDLE1BQU0sSUFBSSxHQUFHLEtBQUssQ0FBQyxHQUFHLENBQUMsTUFBTSxDQUFDLENBQUM7SUFDL0IsS0FBSyxDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUNyQixPQUFPLElBQUksQ0FBQztBQUNkLENBQUM7QUFTRCxNQUFNLE9BQU8sR0FBRyxJQUFJLE9BQU8sRUFBMkIsQ0FBQztBQUN2RCxNQUFNLFVBQVUsc0JBQXNCLENBQUMsSUFBWSxFQUFFLE1BQXVCO0lBQzFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsSUFBSSxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsRUFBRSxHQUFHLE1BQU0sRUFBRSxDQUFDLENBQUMsQ0FBQztBQUNsRCxDQUFDO0FBQ0QsTUFBTSxVQUFVLGVBQWUsQ0FBQyxJQUFZO0lBQzFDLE9BQU8sT0FBTyxDQUFDLEdBQUcsQ0FBQyxJQUFJLENBQUMsQ0FBQztBQUMzQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqIEludGVybmFsIG9uZS1jYWxsIHBvcnQ6IHRoZSBidWlsZGVyIGRlY2xhcmVzIGxvZ2ljYWwgaWRlbnRpdHk7IHRoZSBjYWxsIG93bmVyIHN0YW1wcyBpdCBiZWZvcmUgZGlzcGF0Y2guICovXG5pbXBvcnQgdHlwZSB7IFJldHJ5TG9vcENhbGwgfSBmcm9tICcuL3JldHJ5TG9vcFR5cGVzLmpzJztcbmltcG9ydCB0eXBlIHsgQXR0ZW1wdFJlY29yZCB9IGZyb20gJy4vdHlwZXMuanMnO1xuXG5leHBvcnQgaW50ZXJmYWNlIFJldHJ5TG9vcENhbGxQb3J0IHtcbiAgcmVhZG9ubHkgaWRlbnRpdHk6IFJldHJ5TG9vcENhbGw7XG4gIHJlYWRvbmx5IHJlY29yZDogKHJlY29yZDogQXR0ZW1wdFJlY29yZCkgPT4gdm9pZDtcbn1cblxuY29uc3QgY2FsbHMgPSBuZXcgV2Vha01hcDxvYmplY3QsIFJldHJ5TG9vcENhbGxQb3J0PigpO1xuXG5leHBvcnQgZnVuY3Rpb24gcmVnaXN0ZXJSZXRyeUxvb3BDYWxsKHRhcmdldDogb2JqZWN0LCBwb3J0OiBSZXRyeUxvb3BDYWxsUG9ydCk6ICgpID0+IHZvaWQge1xuICBpZiAoY2FsbHMuaGFzKHRhcmdldCkpIHRocm93IG5ldyBFcnJvcigncmV0cnkgbG9vcDogYW5vdGhlciBjYWxsIGlzIGFscmVhZHkgYmVpbmcgcHJlcGFyZWQgb24gdGhpcyBzY29wZScpO1xuICBjYWxscy5zZXQodGFyZ2V0LCBwb3J0KTtcbiAgcmV0dXJuICgpID0+IHtcbiAgICBpZiAoY2FsbHMuZ2V0KHRhcmdldCkgPT09IHBvcnQpIGNhbGxzLmRlbGV0ZSh0YXJnZXQpO1xuICB9O1xufVxuXG4vKiogQ2xhaW1lZCBvbmNlLCBzbyBuZXN0ZWQgY2FsbHMgbWFkZSBieSB0aGUgdXNlcidzIGNhbGxiYWNrIGRvIG5vdCBpbmhlcml0IHRoZSBvdXRlciBjYWxsJ3MgbG9naWNhbCBpZGVudGl0eS4gKi9cbmV4cG9ydCBmdW5jdGlvbiB0YWtlUmV0cnlMb29wQ2FsbCh0YXJnZXQ6IG9iamVjdCk6IFJldHJ5TG9vcENhbGxQb3J0IHwgdW5kZWZpbmVkIHtcbiAgY29uc3QgcG9ydCA9IGNhbGxzLmdldCh0YXJnZXQpO1xuICBjYWxscy5kZWxldGUodGFyZ2V0KTtcbiAgcmV0dXJuIHBvcnQ7XG59XG5cbmV4cG9ydCBpbnRlcmZhY2UgUmV0cnlMb29wQnVkZ2V0IHtcbiAgcmVhZG9ubHkgcGFzc2VzPzogbnVtYmVyO1xuICByZWFkb25seSByb2xlOiAnY2FsbGJhY2snIHwgJ2NvbnRyb2wnIHwgJ3dhaXQnO1xuICByZWFkb25seSB0aW1lb3V0TXM/OiBudW1iZXI7XG4gIHJlYWRvbmx5IHdhaXRNcz86IG51bWJlcjtcbn1cblxuY29uc3QgYnVkZ2V0cyA9IG5ldyBXZWFrTWFwPG9iamVjdCwgUmV0cnlMb29wQnVkZ2V0PigpO1xuZXhwb3J0IGZ1bmN0aW9uIGRlY2xhcmVSZXRyeUxvb3BCdWRnZXQobm9kZTogb2JqZWN0LCBidWRnZXQ6IFJldHJ5TG9vcEJ1ZGdldCk6IHZvaWQge1xuICBidWRnZXRzLnNldChub2RlLCBPYmplY3QuZnJlZXplKHsgLi4uYnVkZ2V0IH0pKTtcbn1cbmV4cG9ydCBmdW5jdGlvbiByZXRyeUxvb3BCdWRnZXQobm9kZTogb2JqZWN0KTogUmV0cnlMb29wQnVkZ2V0IHwgdW5kZWZpbmVkIHtcbiAgcmV0dXJuIGJ1ZGdldHMuZ2V0KG5vZGUpO1xufVxuIl19

package/dist/esm/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/esm/lib/attempt/retryLoopTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmV0cnlMb29wVHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvbGliL2F0dGVtcHQvcmV0cnlMb29wVHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiIsInNvdXJjZXNDb250ZW50IjpbIi8qKiBMb2dpY2FsIGlkZW50aXR5IG9mIGFuIGV4cGxpY2l0IHJldHJ5IHdvcmtmbG93LiBQaHlzaWNhbCBhdHRlbXB0IGlkZW50aXRpZXMgcmVtYWluIHVuY2hhbmdlZC4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmV0cnlMb29wSWRlbnRpdHkge1xuICByZWFkb25seSBpZDogc3RyaW5nO1xuICByZWFkb25seSBzZXJpZXM6IHN0cmluZztcbiAgcmVhZG9ubHkgYXR0ZW1wdDogbnVtYmVyO1xuICByZWFkb25seSBvZjogbnVtYmVyO1xufVxuXG4vKiogVGhlIHJvbGUgb2Ygb25lIHBoeXNpY2FsIGNhbGwgaW5zaWRlIGEgbG9naWNhbCBwYXNzLiAqL1xuZXhwb3J0IGludGVyZmFjZSBSZXRyeUxvb3BDYWxsIGV4dGVuZHMgUmV0cnlMb29wSWRlbnRpdHkge1xuICByZWFkb25seSBwaGFzZTogJ2F0dGVtcHQnIHwgJ3JlY29uY2lsZSc7XG59XG5cbi8qKiBUaGUgZXhwbGljaXQgY2hhcnQgZGVjaXNpb24sIGFmdGVyIHJlY29uY2lsaWF0aW9uOyBuZXZlciByZXdyaXRlcyBhIHBoeXNpY2FsIGNhbGwncyBvdXRjb21lLiAqL1xuZXhwb3J0IGludGVyZmFjZSBSZXRyeUxvb3BEZWNpc2lvbiBleHRlbmRzIFJldHJ5TG9vcElkZW50aXR5IHtcbiAgcmVhZG9ubHkgZWZmZWN0OiAnYXBwbGllZCcgfCAnbm9uZScgfCAndW5rbm93bic7XG4gIHJlYWRvbmx5IHJlY29uY2lsZWQ6IGJvb2xlYW47XG4gIHJlYWRvbmx5IG5leHQ6ICdyZXRyeScgfCAnZG9uZScgfCAnc3RvcCc7XG4gIHJlYWRvbmx5IHJlYXNvbjogc3RyaW5nO1xufVxuIl19

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