@rotorsoft/act 1.18.5 → 1.18.7

package/dist/index.js

@@ -616,6 +616,108 @@ function compile_autoclose_policy(options) {
   };
 }
 
+// src/internal/close-signal.ts
+var CloseSignal = class extends Error {
+  /**
+   * Stream to close. Omitted → the reaction's own lease stream (a self-close).
+   * The synthesized autoclose reaction sets it to the aggregate stream, since
+   * its lease runs on a synthetic `__autoclose__` target.
+   */
+  stream;
+  /** Optional archive callback to run while the stream is guarded. */
+  archive;
+  /**
+   * Watermark to ack the requesting reaction to before the close runs. The
+   * close-cycle safety guard skips a stream whose subscriptions (matched by
+   * source) lag the head; the autoclose reaction's `source` is the aggregate,
+   * so it must advance its own watermark to the live head id it evaluated
+   * against — otherwise it blocks its own close. Defaults to the triggering
+   * event id when omitted.
+   */
+  at;
+  constructor(opts) {
+    super("reaction requested close");
+    this.name = "CloseSignal";
+    this.stream = opts?.stream;
+    this.archive = opts?.archive;
+    this.at = opts?.at;
+  }
+};
+
+// src/internal/defer-signal.ts
+var DeferSignal = class extends Error {
+  /**
+   * The unresolved schedule. The dispatcher turns this into an absolute
+   * due-time by resolving it against the triggering event.
+   */
+  when;
+  constructor(when) {
+    super("reaction deferred");
+    this.name = "DeferSignal";
+    this.when = when;
+  }
+};
+
+// src/internal/autoclose-reaction.ts
+var AUTOCLOSE_TARGET_PREFIX = "__autoclose__:";
+function synthesize_autoclose_reactions(registry, states, config2) {
+  for (const st of states.values()) {
+    const predicate = st.autoclose;
+    if (!predicate) continue;
+    const after_ms = st.autoclose_after_ms;
+    const archiver = st.archive;
+    const reaction = {
+      // Run on a SYNTHETIC stream — `source` is the aggregate, `target` is a
+      // per-aggregate `__autoclose__` key — so the autoclose reaction never
+      // shares a watermark with the aggregate's own reactions. A shared
+      // watermark would let autoclose's defer short-circuit the aggregate's
+      // other reactions (the "a defer affects all reactions on a stream"
+      // hazard). The close still targets the aggregate (`source`).
+      resolver: (e) => ({
+        target: `${AUTOCLOSE_TARGET_PREFIX}${e.stream}`,
+        source: e.stream
+      }),
+      // Never block on autoclose: a transient query/store error should retry,
+      // not quarantine the synthetic stream.
+      options: { blockOnError: false, maxRetries: 3 },
+      handler: async (event) => {
+        const aggregate = event.stream;
+        if (!in_autoclose_window(config2.autocloseWindow, /* @__PURE__ */ new Date()))
+          throw new DeferSignal({
+            at: new Date(Date.now() + config2.autocloseCycleMinutes * 6e4)
+          });
+        const stats = await store().query_stats([aggregate], {
+          count: true,
+          exclude: [TOMBSTONE_EVENT]
+        });
+        const entry = stats.get(aggregate);
+        if (!entry) return;
+        const head = entry.head;
+        if (predicate(aggregate, head, entry.count))
+          throw new CloseSignal({
+            stream: aggregate,
+            archive: archiver ? () => archiver(aggregate, head) : void 0,
+            // Ack this reaction's own watermark to the live head so the
+            // close-cycle guard (which matches subscriptions by source =
+            // aggregate) sees it caught up instead of blocking its own close.
+            at: head.id
+          });
+        if (after_ms !== void 0)
+          throw new DeferSignal({
+            at: new Date(head.created.getTime() + after_ms)
+          });
+      }
+    };
+    const key = `__autoclose_${st.name}`;
+    for (const event_name of Object.keys(st.events)) {
+      registry.events[event_name]?.reactions.set(
+        key,
+        reaction
+      );
+    }
+  }
+}
+
 // src/internal/build-classify.ts
 var ALL_LANES = /* @__PURE__ */ Symbol("act-1103/all-lanes");
 function classify_registry(registry, states) {
@@ -671,22 +773,6 @@ function classify_registry(registry, states) {
 
 // src/internal/defer-config.ts
 import { z as z3 } from "zod";
-
-// src/internal/defer-signal.ts
-var DeferSignal = class extends Error {
-  /**
-   * The unresolved schedule. The dispatcher turns this into an absolute
-   * due-time by resolving it against the triggering event.
-   */
-  when;
-  constructor(when) {
-    super("reaction deferred");
-    this.name = "DeferSignal";
-    this.when = when;
-  }
-};
-
-// src/internal/defer-config.ts
 var DeferDurationSchema = z3.object({
   days: z3.number().positive().optional(),
   hours: z3.number().positive().optional(),
@@ -1170,34 +1256,6 @@ async function truncate_and_warm_cache(guarded, seed_states, guard_events, corre
   return truncated;
 }
 
-// src/internal/close-signal.ts
-var CloseSignal = class extends Error {
-  /**
-   * Stream to close. Omitted → the reaction's own lease stream (a self-close).
-   * The synthesized autoclose reaction sets it to the aggregate stream, since
-   * its lease runs on a synthetic `__autoclose__` target.
-   */
-  stream;
-  /** Optional archive callback to run while the stream is guarded. */
-  archive;
-  /**
-   * Watermark to ack the requesting reaction to before the close runs. The
-   * close-cycle safety guard skips a stream whose subscriptions (matched by
-   * source) lag the head; the autoclose reaction's `source` is the aggregate,
-   * so it must advance its own watermark to the live head id it evaluated
-   * against — otherwise it blocks its own close. Defaults to the triggering
-   * event id when omitted.
-   */
-  at;
-  constructor(opts) {
-    super("reaction requested close");
-    this.name = "CloseSignal";
-    this.stream = opts?.stream;
-    this.archive = opts?.archive;
-    this.at = opts?.at;
-  }
-};
-
 // src/internal/correlate-cycle.ts
 var CorrelateCycle = class {
   _checkpoint = -1;
@@ -2365,7 +2423,15 @@ var SettleLoop = class {
 // src/act.ts
 var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
-var AUTOCLOSE_TARGET_PREFIX = "__autoclose__:";
+function validate_only_lanes(options, lanes) {
+  if (!options.onlyLanes || options.onlyLanes.length === 0) return;
+  const declared = /* @__PURE__ */ new Set(["default", ...lanes.map((l) => l.name)]);
+  const unknown = options.onlyLanes.filter((l) => !declared.has(l));
+  if (unknown.length > 0)
+    throw new Error(
+      `ActOptions.onlyLanes references undeclared lane(s): ${unknown.map((l) => `"${l}"`).join(", ")}`
+    );
+}
 var Act = class {
   _emitter = new EventEmitter();
   /** ACT-984: orchestrator-owned circuit breaker shared by all drain lanes. */
@@ -2400,13 +2466,6 @@ var Act = class {
   registry;
   /** Map of state name → state definition; populated by the builder. */
   _states;
-  /**
-   * Resolved autoclose configuration (#837 / epic #802). Frozen at
-   * `act().build()` via {@link resolveAutocloseConfig}.
-   *
-   * @internal
-   */
-  _autoclose_config;
   /**
    * Emit a lifecycle event. The payload type is inferred from the event name
    * via {@link ActLifecycleEvents}.
@@ -2523,17 +2582,7 @@ var Act = class {
     this._states = states;
     this._batch_handlers = batch_handlers;
     this._lanes = lanes;
-    if (options.onlyLanes && options.onlyLanes.length > 0) {
-      const declared = /* @__PURE__ */ new Set([
-        "default",
-        ...lanes.map((l) => l.name)
-      ]);
-      const unknown = options.onlyLanes.filter((l) => !declared.has(l));
-      if (unknown.length > 0)
-        throw new Error(
-          `ActOptions.onlyLanes references undeclared lane(s): ${unknown.map((l) => `"${l}"`).join(", ")}`
-        );
-    }
+    validate_only_lanes(options, lanes);
     this._scoped = options.scoped ? (fn) => scoped.run(options.scoped, fn) : (fn) => fn();
     this._correlator = options.correlator ?? default_correlator;
     this._es = build_es(this._logger, this._correlator);
@@ -2547,99 +2596,59 @@ var Act = class {
       bound_forget: this._bound_forget
     });
     this._handle_batch = build_handle_batch(this._logger);
-    for (const st of this._states.values()) {
-      const predicate = st.autoclose;
-      if (!predicate) continue;
-      const after_ms = st.autoclose_after_ms;
-      const archiver = st.archive;
-      const reaction = {
-        // Run on a SYNTHETIC stream — `source` is the aggregate, `target` is a
-        // per-aggregate `__autoclose__` key — so the autoclose reaction never
-        // shares a watermark with the aggregate's own reactions. A shared
-        // watermark would let autoclose's defer short-circuit the aggregate's
-        // other reactions (the "a defer affects all reactions on a stream"
-        // hazard). The close still targets the aggregate (`source`).
-        resolver: (e) => ({
-          target: `${AUTOCLOSE_TARGET_PREFIX}${e.stream}`,
-          source: e.stream
-        }),
-        // Never block on autoclose: a transient query/store error should retry,
-        // not quarantine the synthetic stream.
-        options: { blockOnError: false, maxRetries: 3 },
-        handler: async (event) => {
-          const aggregate = event.stream;
-          const config2 = this._autoclose_config;
-          if (!in_autoclose_window(config2.autocloseWindow, /* @__PURE__ */ new Date()))
-            throw new DeferSignal({
-              at: new Date(Date.now() + config2.autocloseCycleMinutes * 6e4)
-            });
-          const stats = await store().query_stats([aggregate], {
-            count: true,
-            exclude: [TOMBSTONE_EVENT]
-          });
-          const entry = stats.get(aggregate);
-          if (!entry) return;
-          const head = entry.head;
-          if (predicate(aggregate, head, entry.count))
-            throw new CloseSignal({
-              stream: aggregate,
-              archive: archiver ? () => archiver(aggregate, head) : void 0,
-              // Ack this reaction's own watermark to the live head so the
-              // close-cycle guard (which matches subscriptions by source =
-              // aggregate) sees it caught up instead of blocking its own close.
-              at: head.id
-            });
-          if (after_ms !== void 0)
-            throw new DeferSignal({
-              at: new Date(head.created.getTime() + after_ms)
-            });
-        }
-      };
-      const key = `__autoclose_${st.name}`;
-      for (const event_name of Object.keys(st.events)) {
-        this.registry.events[event_name]?.reactions.set(
-          key,
-          reaction
-        );
-      }
-    }
-    const {
-      static_targets,
-      has_dynamic_resolvers,
-      reactive_events,
-      event_to_state,
-      event_to_lanes
-    } = classify_registry(this.registry, this._states);
-    this._reactive_events = reactive_events;
+    const classification = classify_registry(this.registry, this._states);
+    this._reactive_events = classification.reactive_events;
+    this._event_to_state = classification.event_to_state;
+    this._event_to_lanes = classification.event_to_lanes;
     this._listen = options.listen !== false;
     this._drain = options.drain !== false;
-    this._autoclose_config = resolveAutocloseConfig(options);
-    this._breaker = new CircuitBreaker(
+    this._breaker = this._build_breaker(options);
+    this._drain_controllers = this._build_drain_controllers(options, lanes);
+    this._audit_deps = this._build_audit_deps();
+    this._correlate = this._build_correlate(options, classification);
+    this._settle = this._build_settle(options);
+    this._notify_disposer = this._wire_notify(options.scoped?.store ?? store());
+    dispose(() => this.shutdown());
+  }
+  /**
+   * Circuit breaker shared by every store-polling loop (drain, the settle
+   * correlate, autoclose). Validates the knobs eagerly so out-of-range
+   * values throw at build time, not on the first cycle tick.
+   */
+  _build_breaker(options) {
+    return 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.
+        // Any polling loop can trip the shared breaker — 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;
+  }
+  /**
+   * One DrainController per active lane. The implicit "default" lane is
+   * always present unless onlyLanes excludes it. Each controller filters
+   * its claim() by its lane name; the legacy single-controller path is the
+   * active set === { "default" } case with `lane: undefined` deps so
+   * claim() doesn't filter (preserves the single-lane SQL planner shape
+   * for apps that never call withLane).
+   */
+  _build_drain_controllers(options, lanes) {
     const all_lanes = ["default", ...lanes.map((l) => l.name)];
     const only_set = options.onlyLanes && options.onlyLanes.length > 0 ? new Set(options.onlyLanes) : void 0;
     const active_lanes = only_set ? all_lanes.filter((n) => only_set.has(n)) : all_lanes;
     const single_default_lane = active_lanes.length === 1 && active_lanes[0] === "default";
-    this._drain_controllers = /* @__PURE__ */ new Map();
+    const controllers = /* @__PURE__ */ new Map();
     for (const name of active_lanes) {
       const cfg = lanes.find((l) => l.name === name);
       const controller = new DrainController({
@@ -2651,10 +2660,11 @@ var Act = class {
         handle_batch: this._handle_batch,
         on_acked: (acked) => this.emit("acked", acked),
         on_blocked: (blocked) => this.emit("blocked", blocked),
-        // Reaction-requested close (#1090). Runs the same close machinery as
+        // Reaction-requested close. Runs the same close machinery as
         // `app.close` (tombstone guard + archive + atomic truncate) for the
-        // targets a handler signalled via `CloseSignal`. No `correlate()` here
-        // — the drain that produced these targets has already correlated.
+        // targets a handler signalled via `CloseSignal`. No `correlate()`
+        // here — the drain that produced these targets has already
+        // correlated.
         on_close: async (targets) => {
           const close_actor = { id: "$close", name: "close" };
           const result = await run_close_cycle(targets, {
@@ -2670,7 +2680,7 @@ var Act = class {
         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.
+        // adapter SQL collapses to the single-lane shape.
         lane: single_default_lane ? void 0 : name,
         defaults: cfg && {
           streamLimit: cfg.streamLimit,
@@ -2679,30 +2689,47 @@ var Act = class {
       });
       if (cfg?.cycleMs !== void 0 && options.drain !== false)
         controller.start(cfg.cycleMs);
-      this._drain_controllers.set(name, controller);
+      controllers.set(name, controller);
     }
-    this._audit_deps = {
+    return controllers;
+  }
+  /**
+   * Audit deps bag. Snapshotted after registry classification and
+   * drain-controller build so the audit module sees the finalized lane
+   * set. Held as an immutable bag — the orchestrator never carries audit
+   * logic itself, only this typed contract.
+   */
+  _build_audit_deps() {
+    return {
       store,
       logger: this._logger,
-      event_to_state,
+      event_to_state: this._event_to_state,
       states: this._states,
-      known_events: new Set(event_to_state.keys()),
+      known_events: new Set(this._event_to_state.keys()),
       declared_lanes: new Set(this._drain_controllers.keys()),
-      routed_events: new Set(event_to_lanes.keys())
+      routed_events: new Set(this._event_to_lanes.keys())
     };
-    this._correlate = new CorrelateCycle(
+  }
+  /**
+   * Correlate cycle over the classified registry. The cold-start callback
+   * arms every controller — historical events may need processing —
+   * except on writer-only instances (`drain: false`).
+   */
+  _build_correlate(options, classification) {
+    return new CorrelateCycle(
       this.registry,
-      static_targets,
-      has_dynamic_resolvers,
+      classification.static_targets,
+      classification.has_dynamic_resolvers,
       this._cd,
       options.maxSubscribedStreams ?? DEFAULT_MAX_SUBSCRIBED_STREAMS,
-      // Cold start: assume drain is needed (historical events may need processing).
-      // #803: writer-only instances skip the cold-start arm.
       () => {
         if (this._drain && this._reactive_events.size > 0) this._arm_all();
       }
     );
-    this._settle = new SettleLoop(
+  }
+  /** Settle loop driving correlate + drain to quiescence. */
+  _build_settle(options) {
+    return new SettleLoop(
       {
         init: () => this._correlate.init(),
         checkpoint: () => this._correlate.checkpoint,
@@ -2713,8 +2740,6 @@ var Act = class {
       },
       options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
     );
-    this._notify_disposer = this._wire_notify(options.scoped?.store ?? store());
-    dispose(() => this.shutdown());
   }
   /** True after the first `shutdown()` call. Guards idempotency. */
   _shutdown_promise;
@@ -3763,6 +3788,14 @@ function act() {
           };
           batch_handlers.set(target, wrapped);
         }
+        synthesize_autoclose_reactions(
+          registry,
+          states,
+          resolveAutocloseConfig(options ?? {})
+        );
+        Object.freeze(registry.actions);
+        Object.freeze(registry.events);
+        Object.freeze(registry);
         _built = true;
       }
       return new Act(