actor-ts 0.9.0

package/dist/pattern/BackoffSupervisor.d.ts

@@ -0,0 +1,234 @@
+import { Actor } from '../Actor.js';
+import { Props } from '../Props.js';
+import { type SupervisorStrategy } from '../Supervision.js';
+import { type BackoffPolicy } from './BackoffPolicy.js';
+/**
+ * BackoffSupervisor — wraps a single child actor and reschedules its
+ * restart with an exponential backoff (plus jitter).  Use this when
+ * the child's failure is **transient** — flaky DB, broker reconnect
+ * window, third-party API hiccup — and immediate restart would just
+ * hammer the broken dependency.
+ *
+ *   const supervisor = system.spawn(
+ *     BackoffSupervisor.props({
+ *       childProps: Props.create(() => new MyFlaky()),
+ *       minBackoff: 200,
+ *       maxBackoff: 10_000,
+ *       randomFactor: 0.2,
+ *     }),
+ *     'flaky-supervisor',
+ *   );
+ *   // Send messages to the supervisor — they're forwarded to the
+ *   // current child, or stashed during a backoff window.
+ *   supervisor.tell({ kind: 'do-work' }, replyTo);
+ *
+ * **Mechanism.**  The supervisor:
+ *
+ *   1. Runs the child under `stoppingStrategy` so a child crash leads
+ *      to a clean Stop (rather than an immediate Restart).
+ *   2. Death-watches the child (`context.watch`) and listens for
+ *      `Terminated`.  Either a crash-induced stop or an external
+ *      `child.stop()` triggers the same backoff path — pragmatic for
+ *      a v1; finer-grained "respawn only on crash" behaviour is
+ *      available via the `respawnOn: 'failure'` option below.
+ *   3. On `Terminated` it schedules a single-shot timer to spawn a
+ *      fresh child after `policy.delayFor(restartCount)` ms.
+ *   4. While the child is dead, user messages are buffered (`stash`
+ *      mode, default) or dropped (`drop` mode).  Stashed messages are
+ *      flushed to the new child once it spawns, preserving sender refs
+ *      so ask-replies still go to the original asker.  An optional
+ *      `drainGraceMs` window delays the drain so a child that crashes
+ *      in `preStart` doesn't take the stash with it to dead-letter
+ *      — the stash is held back until the new child has clearly
+ *      survived its grace window.  New messages arriving during the
+ *      grace forward immediately so the happy-path latency is
+ *      unaffected.
+ *   5. The restart counter resets when the child has been alive for
+ *      `resetCounter` ms — default `'after-min-stable'` which uses
+ *      `minBackoff` as the threshold.  After a long-running successful
+ *      child, the next failure starts the backoff at `minBackoff` again
+ *      rather than where the last failure left off.
+ *
+ * **Out of scope (v1).**
+ *   - Cluster-aware supervision.  This pattern is local to the parent
+ *     by design — distributed restart coordination belongs in a sharded
+ *     entity or a cluster-singleton, not the supervisor.
+ *   - `onFailure`-only mode (respawn only on crash, not on external
+ *     stop).  Workaround: configure the child to terminate itself only
+ *     on errors and use an explicit `PoisonPill` for shutdown — the
+ *     supervisor will respawn either way until **it** is stopped.
+ */
+/** Reset rule for the consecutive-restart counter. */
+export type ResetCounter = 
+/** Never reset — the counter grows monotonically. */
+'never'
+/** Reset after the child has been alive for `>= minBackoff` ms. */
+ | 'after-min-stable'
+/** Reset after the child has been alive for `>= ms` ms. */
+ | {
+    readonly kind: 'after-time';
+    readonly ms: number;
+};
+/** What to do with messages that arrive while the child is dead. */
+export type ForwardStrategy = 
+/** Buffer them and re-deliver to the next child instance. */
+'stash'
+/** Drop them silently (the supervisor logs at debug level). */
+ | 'drop';
+/**
+ * Which terminations should trigger a respawn (#68).  Two modes,
+ * because the right answer depends on whether you treat a clean
+ * self-stop as recoverable or as a deliberate end of life:
+ *
+ *   - `'any'` *(default)* — respawn on every termination, whether the
+ *     child crashed (uncaught throw) or stopped itself cleanly
+ *     (`context.stop(self)`, `PoisonPill`, parent-driven stop).  This
+ *     is the original v1 (#48) behaviour.
+ *   - `'failure'` — respawn only when the child crashed.  A clean
+ *     self-stop is taken as "this child is done"; the supervisor
+ *     itself stops afterwards instead of spawning a replacement.
+ *   - `'stop'` — the inverse: respawn only on clean stops (e.g. a
+ *     transient connection actor that periodically tears itself
+ *     down).  Crashes propagate "up" by stopping the supervisor.
+ *
+ * Matching is on the **last termination only** — the supervisor
+ * re-arms its tracking on every respawn, so a string of crashes
+ * followed by a clean stop in `'failure'` mode would respawn through
+ * each crash and then stop on the clean stop.
+ */
+export type TerminationTrigger = 'any' | 'failure' | 'stop';
+export interface BackoffOptions<T> {
+    /** How to construct the child. */
+    readonly childProps: Props<T>;
+    /** Name suffix for the child.  The actual child name is
+     *  `${childName}-${incarnation}` so successive incarnations don't
+     *  collide on names while the previous instance is still tearing down. */
+    readonly childName?: string;
+    /** Floor for the backoff delay, in ms.  Must be > 0. */
+    readonly minBackoff: number;
+    /** Ceiling for the backoff delay, in ms.  Must be >= `minBackoff`. */
+    readonly maxBackoff: number;
+    /** Jitter fraction in `[0, 1]`.  Default `0.2`. */
+    readonly randomFactor?: number;
+    /** Custom policy — overrides the default exponential backoff. */
+    readonly policy?: BackoffPolicy;
+    /** Counter-reset rule.  Default `'after-min-stable'`. */
+    readonly resetCounter?: ResetCounter;
+    /** What to do with messages while the child is dead.  Default `'stash'`. */
+    readonly forward?: ForwardStrategy;
+    /**
+     * Which terminations should trigger a respawn.  Default `'any'`
+     * (current v1 behaviour: respawn on crash AND on clean stop).
+     * See {@link TerminationTrigger} for the three modes.
+     */
+    readonly triggerOn?: TerminationTrigger;
+    /** Stash buffer size (only when `forward === 'stash'`).  Default 1000. */
+    readonly maxStashSize?: number;
+    /**
+     * Grace period after a respawn before stashed messages are forwarded
+     * to the new child.  This protects buffered messages against children
+     * that crash in `preStart` — if the child dies during the grace
+     * window, the stash is preserved for the **next** incarnation.
+     *
+     * Default: `min(50ms, minBackoff)`.  Set `0` to disable (drain
+     * immediately on spawn — the v0 behaviour).
+     */
+    readonly drainGraceMs?: number;
+    /**
+     * What to do with messages that arrive during the grace window
+     * (after a respawn, before the child has proven it survives
+     * `drainGraceMs`).  Two modes (#67):
+     *
+     *   - `true` *(default)* — v1 behaviour.  New messages forward
+     *     immediately to the about-to-be-confirmed child; if that
+     *     child dies in `preStart`, those forwarded messages
+     *     dead-letter.  Lowest latency on the happy path, accepts
+     *     dead-letters during a preStart-crash cascade.
+     *   - `false` — strict mode.  New messages stash until the grace
+     *     expires, then drain alongside the carry-over stash from the
+     *     previous incarnation.  Costs up to `drainGraceMs` of latency
+     *     on the first messages after a respawn but guarantees nothing
+     *     dead-letters when the child keeps crashing in `preStart`.
+     *     Opt-in to fix the dead-letter cascade described in #67.
+     *
+     * Has no effect when `drainGraceMs === 0` — without a grace there
+     * is no "uncertain" window for the gate to apply to.
+     */
+    readonly forwardDuringGrace?: boolean;
+    /** Override `Date.now`/`Math.random` for deterministic tests. */
+    readonly clock?: () => number;
+}
+export declare class BackoffSupervisor<T> extends Actor<unknown> {
+    /**
+     * Build a `Props` that spawns a `BackoffSupervisor` configured with
+     * the given options.  Apply `withSupervisorStrategy` if you want to
+     * change how the supervisor itself is supervised (the **child** is
+     * always run under `stoppingStrategy` regardless of this).
+     */
+    static props<T>(opts: BackoffOptions<T>): Props<unknown>;
+    private readonly opts;
+    private readonly policy;
+    private readonly childName;
+    private readonly forward;
+    private readonly stashLimit;
+    private readonly resetThresholdMs;
+    private readonly drainGraceMs;
+    private readonly clock;
+    private readonly triggerOn;
+    private readonly forwardDuringGrace;
+    /**
+     * Set by the supervisor's decider (#68) on the way to `Stop` so
+     * `handleTerminated` can distinguish a crash-driven termination from
+     * a clean self-stop.  Reset after every Terminated handling so a
+     * stale "true" can't be carried over into the next incarnation's
+     * lifecycle.
+     */
+    private lastTerminationWasFailure;
+    /**
+     * `true` once the current child has survived the `drainGraceMs`
+     * window (#67).  Cleared on every spawn + Terminated.  Gates
+     * direct-forwarding of new messages while the child is still in
+     * its uncertain grace period — without the gate, messages arriving
+     * between two failed respawn attempts forward straight into a
+     * crashing child and dead-letter.
+     */
+    private childConfirmedAlive;
+    /** The currently-live child, or `null` while we're in a backoff window. */
+    private currentChild;
+    /** Counter for the **next** restart's delay (0 = first respawn). */
+    private restartCount;
+    /** Wall-clock ts of the last successful spawn, for the reset-window check. */
+    private spawnTs;
+    /** Monotonic incarnation counter — used to disambiguate child names. */
+    private incarnation;
+    /** Buffered messages waiting for the next child. */
+    private readonly stash;
+    constructor(opts: BackoffOptions<T>);
+    /**
+     * The supervisor's own strategy applied to **its child**.  The
+     * decider always returns `Directive.Stop` (so the cell's restart
+     * loop doesn't fight ours), but BEFORE returning it sets
+     * {@link lastTerminationWasFailure} — that's the only place we can
+     * tell "the child crashed" apart from "the child stopped itself
+     * cleanly".  `handleTerminated` reads the flag, applies the
+     * `triggerOn` policy (#68), then resets it.
+     *
+     * Users should not override this; configure the supervisor's parent
+     * instead if you want a different policy for the supervisor itself.
+     */
+    supervisorStrategy(): SupervisorStrategy;
+    preStart(): void;
+    onReceive(message: unknown): Promise<void>;
+    postStop(): void;
+    private spawnChild;
+    private handleTerminated;
+    /**
+     * Translate the `(triggerOn, wasFailure)` pair into a respawn / stop
+     * decision (#68).  Pure function — easy to unit-test in isolation
+     * if we ever want to.
+     */
+    private shouldRespawn;
+    private respawn;
+    private drainStash;
+}
+//# sourceMappingURL=BackoffSupervisor.d.ts.map

package/dist/pattern/BackoffSupervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackoffSupervisor.d.ts","sourceRoot":"","sources":["../../src/pattern/BackoffSupervisor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,sDAAsD;AACtD,MAAM,MAAM,YAAY;AACtB,qDAAqD;AACnD,OAAO;AACT,mEAAmE;GACjE,kBAAkB;AACpB,2DAA2D;GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,oEAAoE;AACpE,MAAM,MAAM,eAAe;AACzB,6DAA6D;AAC3D,OAAO;AACT,+DAA+D;GAC7D,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAC9B;;8EAE0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAYD,qBAAa,iBAAiB,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,OAAO,CAAC;IACtD;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC;IAIxD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAC7C;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB,CAAS;IAC1C;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB,CAAS;IAEpC,2EAA2E;IAC3E,OAAO,CAAC,YAAY,CAA4B;IAChD,oEAAoE;IACpE,OAAO,CAAC,YAAY,CAAK;IACzB,8EAA8E;IAC9E,OAAO,CAAC,OAAO,CAAK;IACpB,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAAK;IACxB,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;gBAElC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IAoCnC;;;;;;;;;;;OAWG;IACM,kBAAkB,IAAI,kBAAkB;IAOxC,QAAQ,IAAI,IAAI;IAIV,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA4ChD,QAAQ,IAAI,IAAI;IAWzB,OAAO,CAAC,UAAU;IA8BlB,OAAO,CAAC,gBAAgB;IAwDxB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;CAOnB"}

package/dist/pattern/BackoffSupervisor.js

@@ -0,0 +1,292 @@
+import { match } from 'ts-pattern';
+import { Actor } from '../Actor.js';
+import { Props } from '../Props.js';
+import { Directive, OneForOneStrategy, } from '../Supervision.js';
+import { Terminated } from '../SystemMessages.js';
+import { exponentialBackoff, } from './BackoffPolicy.js';
+/** Default child name when the user doesn't supply one. */
+const DEFAULT_CHILD_NAME = 'child';
+/** Default cap so a stuck supervisor doesn't OOM the process. */
+const DEFAULT_STASH_LIMIT = 1000;
+export class BackoffSupervisor extends Actor {
+    /**
+     * Build a `Props` that spawns a `BackoffSupervisor` configured with
+     * the given options.  Apply `withSupervisorStrategy` if you want to
+     * change how the supervisor itself is supervised (the **child** is
+     * always run under `stoppingStrategy` regardless of this).
+     */
+    static props(opts) {
+        return Props.create(() => new BackoffSupervisor(opts));
+    }
+    opts;
+    policy;
+    childName;
+    forward;
+    stashLimit;
+    resetThresholdMs;
+    drainGraceMs;
+    clock;
+    triggerOn;
+    forwardDuringGrace;
+    /**
+     * Set by the supervisor's decider (#68) on the way to `Stop` so
+     * `handleTerminated` can distinguish a crash-driven termination from
+     * a clean self-stop.  Reset after every Terminated handling so a
+     * stale "true" can't be carried over into the next incarnation's
+     * lifecycle.
+     */
+    lastTerminationWasFailure = false;
+    /**
+     * `true` once the current child has survived the `drainGraceMs`
+     * window (#67).  Cleared on every spawn + Terminated.  Gates
+     * direct-forwarding of new messages while the child is still in
+     * its uncertain grace period — without the gate, messages arriving
+     * between two failed respawn attempts forward straight into a
+     * crashing child and dead-letter.
+     */
+    childConfirmedAlive = false;
+    /** The currently-live child, or `null` while we're in a backoff window. */
+    currentChild = null;
+    /** Counter for the **next** restart's delay (0 = first respawn). */
+    restartCount = 0;
+    /** Wall-clock ts of the last successful spawn, for the reset-window check. */
+    spawnTs = 0;
+    /** Monotonic incarnation counter — used to disambiguate child names. */
+    incarnation = 0;
+    /** Buffered messages waiting for the next child. */
+    stash = [];
+    constructor(opts) {
+        super();
+        if (!Number.isFinite(opts.minBackoff) || opts.minBackoff <= 0) {
+            throw new Error(`BackoffSupervisor: minBackoff must be > 0, got ${opts.minBackoff}`);
+        }
+        if (!Number.isFinite(opts.maxBackoff) || opts.maxBackoff < opts.minBackoff) {
+            throw new Error(`BackoffSupervisor: maxBackoff (${opts.maxBackoff}) must be >= minBackoff (${opts.minBackoff})`);
+        }
+        this.opts = opts;
+        this.policy = opts.policy ?? exponentialBackoff({
+            minMs: opts.minBackoff,
+            maxMs: opts.maxBackoff,
+            randomFactor: opts.randomFactor ?? 0.2,
+        });
+        this.childName = opts.childName ?? DEFAULT_CHILD_NAME;
+        this.forward = opts.forward ?? 'stash';
+        this.stashLimit = opts.maxStashSize ?? DEFAULT_STASH_LIMIT;
+        this.resetThresholdMs = resolveResetThreshold(opts.resetCounter, opts.minBackoff);
+        if (opts.drainGraceMs !== undefined) {
+            if (!Number.isFinite(opts.drainGraceMs) || opts.drainGraceMs < 0) {
+                throw new Error(`BackoffSupervisor: drainGraceMs must be >= 0, got ${opts.drainGraceMs}`);
+            }
+            this.drainGraceMs = opts.drainGraceMs;
+        }
+        else {
+            this.drainGraceMs = Math.min(50, opts.minBackoff);
+        }
+        this.clock = opts.clock ?? Date.now;
+        this.triggerOn = opts.triggerOn ?? 'any';
+        // Default `true` keeps the v1 fast-forward path; the dead-letter
+        // protection is opt-in (#67) because every respawn would
+        // otherwise pay `drainGraceMs` of latency on the happy path.
+        this.forwardDuringGrace = opts.forwardDuringGrace ?? true;
+    }
+    /**
+     * The supervisor's own strategy applied to **its child**.  The
+     * decider always returns `Directive.Stop` (so the cell's restart
+     * loop doesn't fight ours), but BEFORE returning it sets
+     * {@link lastTerminationWasFailure} — that's the only place we can
+     * tell "the child crashed" apart from "the child stopped itself
+     * cleanly".  `handleTerminated` reads the flag, applies the
+     * `triggerOn` policy (#68), then resets it.
+     *
+     * Users should not override this; configure the supervisor's parent
+     * instead if you want a different policy for the supervisor itself.
+     */
+    supervisorStrategy() {
+        return new OneForOneStrategy((_err) => {
+            this.lastTerminationWasFailure = true;
+            return Directive.Stop;
+        });
+    }
+    preStart() {
+        this.spawnChild();
+    }
+    async onReceive(message) {
+        if (message instanceof Terminated) {
+            this.handleTerminated(message);
+            return;
+        }
+        // Internal respawn tick — we only ever schedule it via timers, so
+        // any other appearance is a bug somewhere upstream.
+        if (message === RESPAWN_TICK) {
+            this.respawn();
+            return;
+        }
+        // Internal drain tick — fired drainGraceMs after a respawn.  If
+        // the child is still alive, mark it confirmed and drain the
+        // stash.  If it died in the meantime, currentChild is null and
+        // we leave the stash for the next incarnation.
+        if (message === DRAIN_TICK) {
+            if (this.currentChild) {
+                this.childConfirmedAlive = true;
+                this.drainStash(this.currentChild);
+            }
+            return;
+        }
+        // User message — forward (when confirmed alive) or stash.  The
+        // `forwardDuringGrace` opt-out preserves the v1 behaviour for
+        // users who prefer zero-latency forwarding over the
+        // dead-letter-during-preStart-crash protection (#67).
+        if (this.currentChild && (this.childConfirmedAlive || this.forwardDuringGrace)) {
+            this.currentChild.tell(message, this.sender.toNullable());
+            return;
+        }
+        if (this.forward === 'drop') {
+            this.log.debug('BackoffSupervisor: dropping message during backoff window', { message });
+            return;
+        }
+        // 'stash' mode.
+        if (this.stash.length >= this.stashLimit) {
+            this.log.warn('BackoffSupervisor: stash full — dropping oldest message', {
+                stashLimit: this.stashLimit,
+            });
+            this.stash.shift();
+        }
+        this.stash.push({ msg: message, sender: this.sender.toNullable() });
+    }
+    postStop() {
+        // Cancel any pending respawn / drain — the cell already cancels
+        // its timers for us, but doing it explicitly keeps the intent
+        // obvious if someone refactors `timers.cancelAll`.
+        this.context.timers.cancel(RESPAWN_TIMER_KEY);
+        this.context.timers.cancel(DRAIN_TIMER_KEY);
+        this.stash.length = 0;
+    }
+    /* ------------------------- internals ---------------------------------- */
+    spawnChild() {
+        this.incarnation += 1;
+        const name = `${this.childName}-${this.incarnation}`;
+        const child = this.context.spawn(this.opts.childProps, name);
+        this.context.watch(child);
+        this.currentChild = child;
+        this.spawnTs = this.clock();
+        // Reset the alive-confirmation flag.  In the default
+        // `forwardDuringGrace: true` mode this only matters for the
+        // explicit-stash carry-over (the gate doesn't apply); in the
+        // opt-in strict mode it gates new forwards until DRAIN_TICK
+        // flips it back to true.  `drainGraceMs === 0` skips the grace
+        // entirely.
+        this.childConfirmedAlive = this.drainGraceMs === 0;
+        if (this.drainGraceMs === 0) {
+            this.drainStash(child);
+            return;
+        }
+        // Wait one grace period before flipping confirmedAlive AND
+        // draining the stash — a child that crashes in `preStart`
+        // doesn't take the stash with it to dead-letter, and (with
+        // `forwardDuringGrace: false`, the default) new messages
+        // arriving in the post-respawn window are stashed too.
+        this.context.timers.startSingleTimer(DRAIN_TIMER_KEY, DRAIN_TICK, this.drainGraceMs);
+    }
+    handleTerminated(t) {
+        // Ignore stale Terminated messages from a previous incarnation —
+        // can happen if we already started a respawn before the old ref's
+        // Terminated finished its trip through the mailbox.
+        if (!this.currentChild || !t.actor.equals(this.currentChild)) {
+            return;
+        }
+        // Snapshot + clear the failure flag set by the decider.  Doing it
+        // here (not later) keeps the supervisor's state clean even if the
+        // triggerOn check causes us to stop ourselves and skip the rest.
+        const wasFailure = this.lastTerminationWasFailure;
+        this.lastTerminationWasFailure = false;
+        if (!this.shouldRespawn(wasFailure)) {
+            this.log.info('BackoffSupervisor: child terminated, triggerOn rejected — supervisor stops', {
+                child: t.actor.toString(),
+                cause: wasFailure ? 'failure' : 'stop',
+                triggerOn: this.triggerOn,
+            });
+            // Stop ourselves — the parent (or whoever spawned us) gets a
+            // Terminated for the supervisor and decides what to do next.
+            this.currentChild = null;
+            this.childConfirmedAlive = false;
+            this.context.timers.cancel(DRAIN_TIMER_KEY);
+            this.context.stop(this.self);
+            return;
+        }
+        const aliveFor = this.clock() - this.spawnTs;
+        if (this.resetThresholdMs !== null && aliveFor >= this.resetThresholdMs) {
+            this.restartCount = 0;
+        }
+        const delay = this.policy.delayFor(this.restartCount);
+        this.restartCount += 1;
+        this.currentChild = null;
+        // Reset the alive-confirmation flag (#67) — the next spawn starts
+        // its grace window from scratch, and any messages arriving
+        // between now and that spawn must stash, not forward.
+        this.childConfirmedAlive = false;
+        // Cancel any pending drain — the child it was waiting on is gone.
+        // The stash itself is preserved for the next incarnation.
+        this.context.timers.cancel(DRAIN_TIMER_KEY);
+        this.context.timers.startSingleTimer(RESPAWN_TIMER_KEY, RESPAWN_TICK, Math.max(0, Math.round(delay)));
+        this.log.info('BackoffSupervisor: child terminated, respawn scheduled', {
+            child: t.actor.toString(),
+            cause: wasFailure ? 'failure' : 'stop',
+            delayMs: delay,
+            restartCount: this.restartCount,
+            aliveMs: aliveFor,
+        });
+    }
+    /**
+     * Translate the `(triggerOn, wasFailure)` pair into a respawn / stop
+     * decision (#68).  Pure function — easy to unit-test in isolation
+     * if we ever want to.
+     */
+    shouldRespawn(wasFailure) {
+        // Exhaustive match — adding a new TerminationTrigger variant
+        // forces this site to be updated (TS error otherwise).
+        return match(this.triggerOn)
+            .with('any', () => true)
+            .with('failure', () => wasFailure)
+            .with('stop', () => !wasFailure)
+            .exhaustive();
+    }
+    respawn() {
+        if (this.currentChild !== null) {
+            // Defensive — should never happen, but a lingering tick is a
+            // correctness hazard worth a log line.
+            this.log.warn('BackoffSupervisor: respawn tick fired with a live child — ignoring');
+            return;
+        }
+        this.spawnChild();
+    }
+    drainStash(child) {
+        if (this.stash.length === 0)
+            return;
+        const drained = this.stash.splice(0, this.stash.length);
+        for (const { msg, sender } of drained) {
+            child.tell(msg, sender);
+        }
+    }
+}
+/** Sentinel for the respawn timer message. */
+const RESPAWN_TICK = Symbol.for('actor-ts.pattern.BackoffSupervisor.respawn');
+const RESPAWN_TIMER_KEY = 'actor-ts.pattern.BackoffSupervisor.respawn';
+/** Sentinel for the stash-drain timer message. */
+const DRAIN_TICK = Symbol.for('actor-ts.pattern.BackoffSupervisor.drain');
+const DRAIN_TIMER_KEY = 'actor-ts.pattern.BackoffSupervisor.drain';
+function resolveResetThreshold(rule, minBackoff) {
+    // Exhaustive over `ResetCounter | undefined`.  `undefined` maps to
+    // the same default behaviour as 'after-min-stable'.  Adding a new
+    // ResetCounter variant forces this site to be updated.
+    return match(rule)
+        .with(undefined, 'after-min-stable', () => minBackoff)
+        .with('never', () => null)
+        .with({ kind: 'after-time' }, (r) => {
+        if (!Number.isFinite(r.ms) || r.ms < 0) {
+            throw new Error(`BackoffSupervisor: resetCounter.ms must be a non-negative number, got ${r.ms}`);
+        }
+        return r.ms;
+    })
+        .exhaustive();
+}
+//# sourceMappingURL=BackoffSupervisor.js.map

package/dist/pattern/BackoffSupervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackoffSupervisor.js","sourceRoot":"","sources":["../../src/pattern/BackoffSupervisor.ts"],"names":[],"mappings":"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"}

package/dist/pattern/CircuitBreaker.d.ts

@@ -0,0 +1,49 @@
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerSettings {
+    /** Consecutive failures before the breaker opens.  Must be >= 1. */
+    readonly maxFailures: number;
+    /** How long the breaker stays open before letting a probe through.  ms. */
+    readonly resetTimeoutMs: number;
+    /** Per-call timeout; exceeding this counts as a failure. */
+    readonly callTimeoutMs?: number;
+    /** Optional: classify errors as non-failures to bypass breaker counting. */
+    readonly isFailure?: (err: Error) => boolean;
+}
+export declare class CircuitBreakerOpenError extends Error {
+    constructor(message?: string);
+}
+export declare class CircuitBreakerTimeoutError extends Error {
+    constructor(ms: number);
+}
+type StateListener = (state: CircuitState) => void;
+/**
+ * Three-state circuit breaker.  Wraps calls that might fail — when enough
+ * fail in a row the breaker "opens" and refuses further calls for a
+ * timeout window.  The first call after the timeout probes the upstream
+ * ("half-open"); if it succeeds, the breaker closes and normal operation
+ * resumes.
+ *
+ * Not tied to actors — works with any `() => Promise<T>` factory.  For
+ * actor-based usage, wrap `ask(target, msg, timeout)` in the factory.
+ */
+export declare class CircuitBreaker {
+    readonly settings: CircuitBreakerSettings;
+    private _state;
+    private failureCount;
+    private nextProbeAt;
+    private readonly listeners;
+    constructor(settings: CircuitBreakerSettings);
+    get state(): CircuitState;
+    /** Call `factory` under breaker supervision.  Throws `CircuitBreakerOpenError` when open. */
+    call<T>(factory: () => Promise<T>): Promise<T>;
+    /** Observe state transitions — useful for logging/metrics. */
+    onStateChange(listener: StateListener): () => void;
+    /** Force the breaker into a specific state (mostly for tests / admin). */
+    setState(next: CircuitState): void;
+    private onSuccess;
+    private onFailure;
+    private maybeTransitionToHalfOpen;
+    private applyTimeout;
+}
+export {};
+//# sourceMappingURL=CircuitBreaker.d.ts.map

package/dist/pattern/CircuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitBreaker.d.ts","sourceRoot":"","sources":["../../src/pattern/CircuitBreaker.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC;CAC9C;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,SAA4B;CAIhD;AAED,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,EAAE,EAAE,MAAM;CAIvB;AAED,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAEnD;;;;;;;;;GASG;AACH,qBAAa,cAAc;aAMG,QAAQ,EAAE,sBAAsB;IAL5D,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;gBAE1B,QAAQ,EAAE,sBAAsB;IAS5D,IAAI,KAAK,IAAI,YAAY,CAAwB;IAEjD,6FAA6F;IACvF,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBpD,8DAA8D;IAC9D,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI;IAKlD,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAQlC,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,yBAAyB;IAKjC,OAAO,CAAC,YAAY;CASrB"}