@rotorsoft/act 1.13.0 → 1.14.0

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-QCSXT5MB.js";
+} from "./chunk-QKVY5QAQ.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -34,6 +34,7 @@ import {
   QuerySchema,
   REDACTED,
   SHREDDED,
+  StoreError,
   StreamClosedError,
   TargetSchema,
   ValidationError,
@@ -43,7 +44,7 @@ import {
   pii_split,
   pii_strip,
   sensitive
-} from "./chunk-NGVWJXEF.js";
+} from "./chunk-4TJN4G7L.js";
 import "./chunk-5WRI5ZAA.js";
 
 // src/signals.ts
@@ -764,10 +765,7 @@ var AutocloseController = class {
   start() {
     if (this._timer) return false;
     this._timer = setInterval(() => {
-      this.run_once().catch((err) => {
-        this.deps.logger.error(
-          `Autoclose cycle errored: ${err instanceof Error ? err.message : String(err)}`
-        );
+      this.run_once().catch(() => {
       });
     }, this.deps.config.autocloseCycleMs);
     this._timer.unref();
@@ -800,6 +798,7 @@ var AutocloseController = class {
    */
   async run_once() {
     if (this._running) return null;
+    if (this.deps.breaker.state(Date.now()) === "open") return null;
     this._running = true;
     try {
       const correlation = close_correlation(
@@ -817,10 +816,14 @@ var AutocloseController = class {
         config: this.deps.config,
         correlation
       });
+      this.deps.breaker.passed();
       if (result.close_result.truncated.size > 0) {
         this.deps.on_closed(result.close_result);
       }
       return result;
+    } catch (error) {
+      this.deps.breaker.failed(Date.now(), error);
+      throw error;
     } finally {
       this._running = false;
     }
@@ -950,6 +953,93 @@ function classify_registry(registry, states) {
   };
 }
 
+// src/internal/circuit-breaker.ts
+import { z as z3 } from "zod";
+var DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 5;
+var DEFAULT_CIRCUIT_COOLDOWN_MS = 3e4;
+var CircuitBreakerOptionsSchema = z3.object({
+  failureThreshold: z3.number().int().min(1).default(DEFAULT_CIRCUIT_FAILURE_THRESHOLD),
+  cooldownMs: z3.number().int().min(100).max(36e5).default(DEFAULT_CIRCUIT_COOLDOWN_MS)
+});
+var resolveCircuitBreakerConfig = (options) => CircuitBreakerOptionsSchema.parse(options ?? {});
+var CircuitBreaker = class {
+  _failures = 0;
+  _opened_at;
+  _wake;
+  _threshold;
+  _cooldown_ms;
+  _hooks;
+  constructor(config2, hooks = {}) {
+    this._threshold = config2.failureThreshold;
+    this._cooldown_ms = config2.cooldownMs;
+    this._hooks = hooks;
+  }
+  /** Current state given the wall-clock `now`. */
+  state(now) {
+    if (this._opened_at === void 0) return "closed";
+    return now - this._opened_at >= this._cooldown_ms ? "half-open" : "open";
+  }
+  /** A store op passed — reset to closed and cancel any pending retry. */
+  passed() {
+    this._failures = 0;
+    this._opened_at = void 0;
+    this._clear_wake();
+  }
+  /**
+   * A store op failed. Opens the breaker when the consecutive-failure
+   * threshold is reached, or immediately re-opens (restarting the cooldown)
+   * if a half-open trial just failed. Returns the resulting state.
+   *
+   * Callers gate on the state directly — `state(now) === "open"` means skip.
+   * On opening, schedules the `on_retry` wake so recovery is automatic;
+   * always surfaces the failure via `on_error`.
+   */
+  failed(now, error) {
+    const circuit = this._advance(now);
+    if (circuit === "open") this._schedule_wake();
+    this._hooks.on_error?.(error, circuit);
+    return circuit;
+  }
+  /** Cancel the pending retry timer. Idempotent; call on shutdown. */
+  stop() {
+    this._clear_wake();
+  }
+  /**
+   * Schedule the `on_retry` wake `cooldownMs` out so the breaker re-trials
+   * the store on its own. No-op when no `on_retry` hook is wired (e.g. unit
+   * tests of the pure state machine). The timer is `unref`'d so it never
+   * keeps the process alive.
+   */
+  _schedule_wake() {
+    if (!this._hooks.on_retry) return;
+    this._clear_wake();
+    this._wake = setTimeout(() => {
+      this._wake = void 0;
+      this._hooks.on_retry?.();
+    }, this._cooldown_ms);
+    this._wake.unref();
+  }
+  _clear_wake() {
+    if (this._wake) {
+      clearTimeout(this._wake);
+      this._wake = void 0;
+    }
+  }
+  /** Pure state transition for a failure — no side effects. */
+  _advance(now) {
+    if (this._opened_at !== void 0) {
+      this._opened_at = now;
+      return "open";
+    }
+    this._failures += 1;
+    if (this._failures >= this._threshold) {
+      this._opened_at = now;
+      return "open";
+    }
+    return "closed";
+  }
+};
+
 // src/internal/correlate-cycle.ts
 var CorrelateCycle = class {
   _checkpoint = -1;
@@ -1802,6 +1892,8 @@ var DrainController = class {
   async drain(options = {}) {
     if (!this._armed) return EMPTY_DRAIN;
     if (this._locked) return EMPTY_DRAIN;
+    if (this._deps.breaker.state(Date.now()) === "open")
+      return EMPTY_DRAIN;
     const d = this._deps.defaults ?? {};
     const streamLimit = d.streamLimit ?? options.streamLimit ?? 10;
     const eventLimit = d.eventLimit ?? options.eventLimit ?? 10;
@@ -1823,6 +1915,7 @@ var DrainController = class {
         this._backoff.size > 0 ? this.is_deferred : void 0,
         this._deps.lane
       );
+      this._deps.breaker.passed();
       if (!cycle) {
         this._armed = false;
         return EMPTY_DRAIN;
@@ -1844,7 +1937,7 @@ var DrainController = class {
       if (!acked.length && !blocked.length && !has_errors) this._armed = false;
       return { fetched, leased, acked, blocked };
     } catch (error) {
-      this._deps.logger.error(error);
+      this._deps.breaker.failed(Date.now(), error);
       return EMPTY_DRAIN;
     } finally {
       this._locked = false;
@@ -2132,12 +2225,15 @@ var SettleLoop = class {
             ...correlate_query,
             after: this._deps.checkpoint()
           });
+          this._deps.breaker.passed();
           last_drain = await this._deps.drain(drain_options);
           const made_progress = subscribed > 0 || last_drain.acked.length > 0 || last_drain.blocked.length > 0;
           if (!made_progress) break;
         }
         if (last_drain) this._deps.on_settled(last_drain);
-      })().catch((err) => this._deps.logger.error(err)).finally(() => {
+      })().catch((err) => {
+        this._deps.breaker.failed(Date.now(), err);
+      }).finally(() => {
         this._running = false;
       });
     }, debounceMs);
@@ -2156,6 +2252,8 @@ var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
 var Act = class {
   _emitter = new EventEmitter();
+  /** ACT-984: orchestrator-owned circuit breaker shared by all drain lanes. */
+  _breaker;
   /** #803: gate the `Store.notify` subscription side. */
   _listen;
   /** #803: gate the local reaction pipeline (drain controllers, settle, correlate). */
@@ -2209,6 +2307,22 @@ var Act = class {
   emit(event, args) {
     return this._emitter.emit(event, args);
   }
+  /**
+   * The single store-failure handler: log it, then emit the `error`
+   * lifecycle event. Wired into the circuit breaker's `on_error`, so it
+   * runs on every `failed()` — drain / settle / autoclose just call
+   * `breaker.failed(now, error)` and never log or emit themselves.
+   *
+   * The emit is guarded against Node's `EventEmitter` contract that an
+   * unhandled `"error"` emission is rethrown (which would crash the process
+   * from inside the drain catch); logging is unconditional so failures are
+   * never silent.
+   */
+  _emit_error(error, circuit) {
+    this._logger.error(error);
+    if (this._emitter.listenerCount("error") > 0)
+      this.emit("error", { error, circuit });
+  }
   /**
    * Register a listener for a lifecycle event. The listener receives the
    * event-specific payload.
@@ -2337,6 +2451,25 @@ var Act = class {
     this._listen = options.listen !== false;
     this._drain = options.drain !== false;
     this._autoclose_config = resolveAutocloseConfig(options);
+    this._breaker = new CircuitBreaker(
+      resolveCircuitBreakerConfig(options.circuitBreaker),
+      {
+        on_error: (error, circuit) => this._emit_error(error, circuit),
+        // Re-probe the store when the cooldown elapses, so recovery is
+        // automatic even on the default lane (which has no periodic poller).
+        // The breaker is shared by every store-polling loop (drain, the
+        // settle correlate, autoclose), so any of them can trip it — but a
+        // bare `drain()` only touches the store when the controller is armed,
+        // so a trip from a correlate failure could go unprobed. `settle()`
+        // always runs a correlate (a store query) before draining, so it
+        // re-probes regardless of which loop opened the breaker: one success
+        // closes it and every loop resumes on its own cadence. A failed probe
+        // re-opens the breaker and reschedules the wake.
+        on_retry: () => {
+          this.settle({ debounceMs: 0 });
+        }
+      }
+    );
     this._event_to_state = event_to_state;
     this._event_to_lanes = event_to_lanes;
     const all_lanes = ["default", ...lanes.map((l) => l.name)];
@@ -2355,6 +2488,7 @@ var Act = class {
         handle_batch: this._handle_batch,
         on_acked: (acked) => this.emit("acked", acked),
         on_blocked: (blocked) => this.emit("blocked", blocked),
+        breaker: this._breaker,
         // Pass lane only when a true per-lane controller is active.
         // The all-lanes (single default) case keeps lane=undefined so
         // adapter SQL collapses to the pre-1103 shape.
@@ -2391,12 +2525,12 @@ var Act = class {
     );
     this._settle = new SettleLoop(
       {
-        logger: this._logger,
         init: () => this._correlate.init(),
         checkpoint: () => this._correlate.checkpoint,
         correlate: (q) => this.correlate(q),
         drain: (o) => this.drain(o),
-        on_settled: (drain) => this.emit("settled", drain)
+        on_settled: (drain) => this.emit("settled", drain),
+        breaker: this._breaker
       },
       options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
     );
@@ -2418,7 +2552,8 @@ var Act = class {
       config: this._autoclose_config,
       correlator: this._correlator,
       close_actor: { id: "$autoclose", name: "autoclose" },
-      on_closed: (result) => this.emit("closed", result)
+      on_closed: (result) => this.emit("closed", result),
+      breaker: this._breaker
     }) : void 0;
     this._notify_disposer = this._wire_notify(options.scoped?.store ?? store());
     dispose(() => this.shutdown());
@@ -2441,6 +2576,7 @@ var Act = class {
         this._emitter.removeAllListeners();
         this.stop_correlations();
         this.stop_settling();
+        this._breaker.stop();
         for (const c of this._drain_controllers.values()) c.stop();
         const disposer = await this._notify_disposer;
         if (disposer) await disposer();
@@ -3957,6 +4093,7 @@ export {
   REDACTED,
   SHREDDED,
   SNAP_EVENT,
+  StoreError,
   StreamClosedError,
   TOMBSTONE_EVENT,
   TargetSchema,