@rotorsoft/act 1.13.0 → 1.14.0

package/dist/index.cjs

@@ -57,6 +57,7 @@ __export(index_exports, {
   REDACTED: () => REDACTED,
   SHREDDED: () => SHREDDED,
   SNAP_EVENT: () => SNAP_EVENT,
+  StoreError: () => StoreError,
   StreamClosedError: () => StreamClosedError,
   TOMBSTONE_EVENT: () => TOMBSTONE_EVENT,
   TargetSchema: () => TargetSchema,
@@ -307,7 +308,8 @@ var Errors = {
   InvariantError: "ERR_INVARIANT",
   ConcurrencyError: "ERR_CONCURRENCY",
   StreamClosedError: "ERR_STREAM_CLOSED",
-  NonRetryableError: "ERR_NON_RETRYABLE"
+  NonRetryableError: "ERR_NON_RETRYABLE",
+  StoreError: "ERR_STORE"
 };
 var ValidationError = class extends Error {
   /** The type of target being validated (e.g., "action", "event") */
@@ -376,6 +378,15 @@ var StreamClosedError = class extends Error {
     this.stream = stream;
   }
 };
+var StoreError = class extends Error {
+  /** The store operation that failed (e.g. `"claim"`, `"ack"`, `"commit"`). */
+  operation;
+  constructor(operation, options) {
+    super(`Store operation "${operation}" failed`, options);
+    this.name = Errors.StoreError;
+    this.operation = operation;
+  }
+};
 var NonRetryableError = class extends Error {
   /** The original failure, if any. Mirrors the standard `Error.cause` shape. */
   cause;
@@ -2136,10 +2147,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();
@@ -2172,6 +2180,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(
@@ -2189,10 +2198,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;
     }
@@ -2322,6 +2335,93 @@ function classify_registry(registry, states) {
   };
 }
 
+// src/internal/circuit-breaker.ts
+var import_zod7 = require("zod");
+var DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 5;
+var DEFAULT_CIRCUIT_COOLDOWN_MS = 3e4;
+var CircuitBreakerOptionsSchema = import_zod7.z.object({
+  failureThreshold: import_zod7.z.number().int().min(1).default(DEFAULT_CIRCUIT_FAILURE_THRESHOLD),
+  cooldownMs: import_zod7.z.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;
@@ -3174,6 +3274,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;
@@ -3195,6 +3297,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;
@@ -3216,7 +3319,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;
@@ -3225,7 +3328,7 @@ var DrainController = class {
 };
 
 // src/internal/merge.ts
-var import_zod7 = require("zod");
+var import_zod8 = require("zod");
 function base_type_name(zodType) {
   let t = zodType;
   while (typeof t.unwrap === "function") {
@@ -3234,7 +3337,7 @@ function base_type_name(zodType) {
   return t.constructor.name;
 }
 function merge_schemas(existing, incoming, state_name) {
-  if (existing instanceof import_zod7.ZodObject && incoming instanceof import_zod7.ZodObject) {
+  if (existing instanceof import_zod8.ZodObject && incoming instanceof import_zod8.ZodObject) {
     const existing_shape = existing.shape;
     const incoming_shape = incoming.shape;
     for (const key of Object.keys(incoming_shape)) {
@@ -3504,12 +3607,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);
@@ -3528,6 +3634,8 @@ var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
 var Act = class {
   _emitter = new import_node_events.default();
+  /** 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). */
@@ -3581,6 +3689,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.
@@ -3709,6 +3833,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)];
@@ -3727,6 +3870,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.
@@ -3763,12 +3907,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
     );
@@ -3790,7 +3934,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 ?? store2());
     dispose(() => this.shutdown());
@@ -3813,6 +3958,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();
@@ -5330,6 +5476,7 @@ function write_line(writer, line) {
   REDACTED,
   SHREDDED,
   SNAP_EVENT,
+  StoreError,
   StreamClosedError,
   TOMBSTONE_EVENT,
   TargetSchema,