@rotorsoft/act 1.32.24 → 1.32.25

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-OG5O36AJ.js";
+} from "./chunk-QXW3JV2H.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -1355,37 +1355,34 @@ async function windowed_prune_pending(stream, before, max_id) {
 }
 async function probe_min_watermarks(streams, page_size, checkpoint) {
   const min_at = /* @__PURE__ */ new Map();
-  const source_regex = /* @__PURE__ */ new Map();
-  const get_regex = (source) => {
-    let re = source_regex.get(source);
+  const matches = source_matcher();
+  await walk_streams(
+    store(),
+    (position) => {
+      const pending = position.correlated_at === void 0 || position.at < position.correlated_at;
+      const cap = pending ? position.at : Math.max(position.at, checkpoint);
+      for (const stream of streams) {
+        if (matches(position.source, stream)) {
+          const prev = min_at.get(stream);
+          if (prev === void 0 || cap < prev) min_at.set(stream, cap);
+        }
+      }
+    },
+    { limit: page_size, source_matches: streams }
+  );
+  return min_at;
+}
+function source_matcher() {
+  const compiled = /* @__PURE__ */ new Map();
+  return (source, stream) => {
+    if (!source) return true;
+    let re = compiled.get(source);
     if (!re) {
       re = new RegExp(source);
-      source_regex.set(source, re);
+      compiled.set(source, re);
     }
-    return re;
+    return re.test(stream);
   };
-  let after;
-  for (; ; ) {
-    let last;
-    const { count } = await store().query_streams(
-      (position) => {
-        last = position.stream;
-        const source_re = position.source ? get_regex(position.source) : void 0;
-        const pending = position.correlated_at === void 0 || position.at < position.correlated_at;
-        const cap = pending ? position.at : Math.max(position.at, checkpoint);
-        for (const stream of streams) {
-          if (!source_re || source_re.test(stream)) {
-            const prev = min_at.get(stream);
-            if (prev === void 0 || cap < prev) min_at.set(stream, cap);
-          }
-        }
-      },
-      { after, limit: page_size, source_matches: streams }
-    );
-    if (count < page_size) break;
-    after = last;
-  }
-  return min_at;
 }
 async function scan_stream_heads(streams) {
   const stats = await store().query_stats(streams, {
@@ -1419,36 +1416,20 @@ async function partition_by_safety(stream_info, reactive_events_size, skipped, p
     if (checkpoint < info.max_id) uncorrelated.add(stream);
   }
   const pending_set = /* @__PURE__ */ new Set();
-  const source_regex = /* @__PURE__ */ new Map();
-  const get_regex = (source) => {
-    let re = source_regex.get(source);
-    if (!re) {
-      re = new RegExp(source);
-      source_regex.set(source, re);
-    }
-    return re;
-  };
+  const matches = source_matcher();
   const targets = [...stream_info.keys()];
-  let after;
-  for (; ; ) {
-    let last;
-    const { count } = await store().query_streams(
-      (position) => {
-        last = position.stream;
-        const source_re = position.source ? get_regex(position.source) : void 0;
-        const has_work = position.correlated_at !== void 0 && position.at < position.correlated_at;
-        if (!has_work) return;
-        for (const [stream, info] of stream_info) {
-          if ((!source_re || source_re.test(stream)) && position.at < info.max_id) {
-            pending_set.add(stream);
-          }
-        }
-      },
-      { after, limit: page_size, source_matches: targets }
-    );
-    if (count < page_size) break;
-    after = last;
-  }
+  await walk_streams(
+    store(),
+    (position) => {
+      const has_work = position.correlated_at !== void 0 && position.at < position.correlated_at;
+      if (!has_work) return;
+      for (const [stream, info] of stream_info) {
+        if (matches(position.source, stream) && position.at < info.max_id)
+          pending_set.add(stream);
+      }
+    },
+    { limit: page_size, source_matches: targets }
+  );
   const safe = [];
   for (const [stream] of stream_info) {
     if (pending_set.has(stream) || uncorrelated.has(stream))
@@ -2132,6 +2113,18 @@ var validating_patch = (me, state2, partial, event) => {
   );
 };
 var DEFAULT_BATCH = 500;
+var cache_put = (stream, entry) => cache().set(stream, entry).catch(
+  (err) => log().warn(
+    err,
+    "cache set skipped; the next load re-folds from the store"
+  )
+);
+var cache_drop = (stream) => cache().invalidate(stream).catch(
+  (err) => log().warn(
+    err,
+    "cache invalidate skipped; a stale checkpoint re-folds from its event_id"
+  )
+);
 async function snap(snapshot) {
   const { id, stream, name, meta, version } = snapshot.event;
   try {
@@ -2334,19 +2327,14 @@ async function load(me, target, callback, patch_fn = bare_patch) {
   );
   const head_is_tombstone = event?.name === TOMBSTONE_EVENT;
   if (replayed > 0 && !time_travel && event && !me.pii_aware && !head_is_tombstone) {
-    await cache().set(stream, {
+    await cache_put(stream, {
       stream,
       state: state2,
       version: event.version,
       event_id: event.id,
       patches,
       snaps
-    }).catch(
-      (err) => log().warn(
-        err,
-        "cache set skipped; the next load re-folds from the store"
-      )
-    );
+    });
   }
   return {
     event,
@@ -2434,14 +2422,7 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
           reactingTo ? expectedVersion : expected
         );
       } catch (error) {
-        if (error instanceof ConcurrencyError) {
-          cache().invalidate(stream).catch(
-            (err) => log().warn(
-              err,
-              "cache invalidate skipped; a stale checkpoint re-folds from its event_id"
-            )
-          );
-        }
+        if (error instanceof ConcurrencyError) void cache_drop(stream);
         throw error;
       }
       let { state: state2, patches } = snapshot;
@@ -2468,26 +2449,15 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
       const snap_event = snapped ? await snap(last) : void 0;
       if (!me.pii_aware) {
         if (contiguous)
-          cache().set(stream, {
+          void cache_put(stream, {
             stream,
             state: last.state,
             version: snap_event?.version ?? last.event.version,
             event_id: snap_event?.id ?? last.event.id,
             patches: snap_event ? 0 : last.patches,
             snaps: snap_event ? last.snaps + 1 : last.snaps
-          }).catch(
-            (err) => log().warn(
-              err,
-              "cache set skipped; the next load re-folds from the store"
-            )
-          );
-        else
-          cache().invalidate(stream).catch(
-            (err) => log().warn(
-              err,
-              "cache invalidate skipped; a stale checkpoint re-folds from its event_id"
-            )
-          );
+          });
+        else void cache_drop(stream);
       }
       return snapshots;
     } catch (error) {
@@ -3250,41 +3220,23 @@ function validate_only_lanes(options, lanes) {
 }
 var Act = class {
   _emitter = new EventEmitter();
-  /** Circuit breaker shared by all drain lanes. */
   _breaker;
-  /** Whether this instance subscribes to `Store.notify`. */
   _listen;
-  /** Whether this instance runs reactions (drain, settle, correlate). */
   _drain;
-  /** Event names with at least one registered reaction (computed at build time) */
   _reactive_events;
-  /** One DrainController per active lane, keyed by lane name. */
   _drain_controllers;
-  /** Correlation: lazy init and the scan that marks work. */
   _correlate;
-  /** Debounced correlate→drain catch-up loop. */
   _settle;
-  /** Timer behind {@link start_correlations}. */
   _poll;
   /** The deprecated `start_correlations` callback, while the poll runs. */
   _on_discovered;
   /**
-   * Disposer for the cross-process notify subscription, set up eagerly
-   * during construction. Held as a promise because the subscription
-   * itself may be async (the PG adapter checks out a dedicated client
-   * and runs `LISTEN` before resolving). Resolves to `undefined` when
-   * the store doesn't implement `notify` or there are no registered
-   * reactions.
-   *
-   * **Contract:** the configured store must be injected via
-   * {@link store}`(adapter)` *before* calling `act()...build()`. The
-   * orchestrator wires notify against whatever store is current at
-   * construction time — late injection after build is unsupported.
+   * Wired at construction against the store current then, so a store
+   * injected after `build()` is never notified.
    */
   _notify_disposer;
   /** Public registry — kept as-is per the no-prefix-on-public convention. */
   registry;
-  /** Map of state name → state definition; populated by the builder. */
   _states;
   /**
    * Emit a lifecycle event. The payload type is inferred from the event name
@@ -3310,15 +3262,9 @@ var Act = class {
     return listeners.length > 0;
   }
   /**
-   * 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.
+   * The one place a store failure is logged and emitted (the breaker's
+   * `on_error`). The emit is guarded: an unhandled `"error"` emission
+   * would crash the process.
    */
   _emit_error(error, circuit) {
     this._logger.error(error);
@@ -3340,58 +3286,29 @@ var Act = class {
     this._emitter.off(event, listener);
     return this;
   }
-  /** Batch handlers for static-target projections (target → handler) */
   _batch_handlers;
-  /** Event-sourcing handlers, optionally wrapped with trace decorators */
   _es;
-  /** Correlate/drain pipeline ops, optionally wrapped with trace decorators */
   _cd;
-  /**
-   * Event-name → owning state, computed at build time. The duplicate-event
-   * guard in merge.ts ensures one event name maps to at most one state, so
-   * this lookup is unambiguous. Used by `close()` to pick the right reducer
-   * set when seeding a `restart` snapshot in multi-state apps.
-   */
+  /** Unambiguous: merge rejects an event name declared by two states. */
   _event_to_state;
-  /**
-   * Event-name → lane fan-in for selective arming. Built by
-   * `classify_registry` once per build. `"all"` means at least one of
-   * the event's reactions is a dynamic resolver (lane opaque until
-   * runtime); a `Set<string>` lists the static lanes only that event's
-   * reactions target.
-   */
+  /** Lanes to arm per event; `"all"` when a dynamic resolver hides the lane. */
   _event_to_lanes;
-  /** What `internal/audit.ts` needs, built once at construction. */
   _audit_deps;
-  /** Logger resolved at construction time (after user port configuration) */
   _logger = log();
   /** This Act's ports: its own bag, or the singleton adapters. */
   _ports;
-  /**
-   * Runs a body inside this Act's ports frame, so internal
-   * `store()`/`cache()` calls resolve to `_ports`.
-   */
+  /** Runs a body so internal `store()`/`cache()` calls resolve to `_ports`. */
   _scoped;
-  /**
-   * Correlation-id generator for originating actions. Bound at
-   * construction from `options.correlator ?? default_correlator`. The
-   * `do()` path passes this into the `_es.action` closure; close-cycle
-   * uses it via {@link close_correlation}.
-   */
   _correlator;
-  /** Pre-bound IAct methods reused across drain cycles. Only `do` varies per
-   * payload (it captures the triggering event for reactingTo auto-inject). */
+  // Bound once, reused by every reaction payload.
   _bound_do = this.do.bind(this);
   _bound_load = this.load.bind(this);
   _bound_query = this.query.bind(this);
   _bound_query_array = this.query_array.bind(this);
   _bound_forget = this.forget.bind(this);
-  /** Reaction dispatchers built once and handed to run_drain_cycle each cycle. */
   _handle;
   _handle_batch;
-  /** Declared drain lanes. */
   _lanes;
-  /** Serializes close critical sections per stream. */
   _close_lock = new CloseLock();
   /** Every lane a controller can exist for: `"default"` plus each declared one. */
   _declared_lanes;
@@ -3399,26 +3316,7 @@ var Act = class {
   get lanes() {
     return this._lanes;
   }
-  /**
-   * Create a new Act orchestrator. Prefer the {@link act} builder over
-   * direct construction — `act()...build()` wires the registry, merges
-   * partial states, and collects batch handlers from registered slices
-   * and projections in one pass.
-   *
-   * @param registry  Schemas for every event and action across registered states
-   * @param states    Merged map of state name → state definition
-   * @param batch_handlers Static-target projection batch handlers (target → handler)
-   * @param options   Tuning knobs — see {@link ActOptions}
-   * @param lanes     Declared drain lanes. The builder collects
-   *   these from `.withLane(...)` calls; one `DrainController` runs
-   *   per lane, plus the implicit `"default"`.
-   * @param patch_fn  The per-event patch step selected once by the builder
-   *   from `ActOptions.validateFoldedState` — `bare_patch` by
-   *   default, `validating_patch` when the flag is on. The builder uses
-   *   the same value for its projection-fold handlers, so there is a
-   *   single selection site. Defaults to `bare_patch` for direct
-   *   construction.
-   */
+  /** Use the {@link act} builder rather than constructing directly. */
   constructor(registry, states = /* @__PURE__ */ new Map(), batch_handlers = /* @__PURE__ */ new Map(), options = {}, lanes = [], patch_fn = bare_patch) {
     this.registry = registry;
     this._states = states;
@@ -3469,11 +3367,7 @@ var Act = class {
     this._notify_disposer = this._wire_notify(this._ports.store);
     register_weak_disposer(new WeakRef(this), (self) => self.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.
-   */
+  /** Shared by drain, settle and autoclose; bad knobs throw at build. */
   _build_breaker(options) {
     return new CircuitBreaker(
       resolveCircuitBreakerConfig(options.circuitBreaker),
@@ -3487,11 +3381,7 @@ var Act = class {
       }
     );
   }
-  /**
-   * One DrainController per active lane, plus the implicit "default" unless
-   * `onlyLanes` excludes it. Apps that declare no lanes pass no lane filter
-   * to `claim`.
-   */
+  /** Apps that declare no lanes pass no lane filter to `claim`. */
   _build_drain_controllers(options, lanes) {
     const all_lanes = this._declared_lanes;
     const only_set = options.onlyLanes && options.onlyLanes.length > 0 ? new Set(options.onlyLanes) : void 0;
@@ -3527,11 +3417,7 @@ var Act = class {
     }
     return controllers;
   }
-  /**
-   * Startup advisory naming declared lanes that `onlyLanes` leaves without a
-   * controller here. One process can't check that the cluster covers every
-   * lane, so it reports its own gaps.
-   */
+  /** One process can't see the cluster, so it reports its own lane gaps. */
   _advise_orphaned_lanes(options) {
     if (!options.onlyLanes || options.onlyLanes.length === 0) return;
     const active = new Set(this._drain_controllers.keys());
@@ -3553,11 +3439,6 @@ var Act = class {
       routed_events: new Set(this._event_to_lanes.keys())
     };
   }
-  /**
-   * 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({
       registry: this.registry,
@@ -3575,12 +3456,7 @@ var Act = class {
       on_init_async: this._drain ? () => this._seed_persisted_defers() : void 0
     });
   }
-  /**
-   * At cold start, re-seed each lane controller's local wake from the
-   * persisted future `deferred_at`, so an idle deferred stream (an
-   * autoclose waiting out its window) still fires on time. Streams on lanes
-   * this instance doesn't run are skipped.
-   */
+  /** Cold start: an idle deferred stream still fires on time after a restart. */
   async _seed_persisted_defers() {
     const now = Date.now();
     await walk_streams(store(), (pos) => {
@@ -3589,7 +3465,6 @@ var Act = class {
       controller?.seed_defer(pos.stream, pos.deferred_at);
     });
   }
-  /** Settle loop driving correlate + drain to quiescence. */
   _build_settle(options) {
     return new SettleLoop(
       {
@@ -3603,7 +3478,6 @@ var Act = class {
       options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
     );
   }
-  /** True after the first `shutdown()` call. Guards idempotency. */
   _shutdown_promise;
   /**
    * Per-instance teardown: stop scheduling new work, give drain cycles
@@ -3643,14 +3517,8 @@ var Act = class {
     return this._shutdown_promise;
   }
   /**
-   * Wait for every in-flight drain cycle, or for the grace budget to elapse,
-   * whichever comes first. Cycle promises never reject (`drain()` contains
-   * its own errors), so this never throws.
-   *
-   * An omitted budget is the largest `leaseMillis` among lanes with a cycle
-   * in flight (the drain's fallback for lanes that pinned none, or pinned
-   * 0, which is the same as none), with an in-flight settle counting on the
-   * fallback, capped at the maximum. Idle lanes don't count.
+   * The largest `leaseMillis` among lanes with a cycle in flight (the
+   * default for none or 0, and for a running settle), capped.
    */
   _derive_grace_ms(running, settling) {
     let max = settling ? DEFAULT_LEASE_MILLIS : 0;
@@ -3679,12 +3547,7 @@ var Act = class {
       clearTimeout(timer);
     }
   }
-  /**
-   * Subscribe to {@link Store.notify} when both the store and the
-   * registry support it. Returns the disposer (or `undefined` when no
-   * subscription was made). Errors during subscription are logged but
-   * never thrown — `notify` is a hint, not a contract.
-   */
+  /** Failures are logged, never thrown: `notify` is a hint. */
   async _wire_notify(s) {
     if (this._reactive_events.size === 0) return void 0;
     if (!s.notify) return void 0;
@@ -3996,20 +3859,11 @@ var Act = class {
       return { fetched: [], leased: [], acked: [], blocked: [] };
     return this._scoped(() => this._drain_all(options));
   }
-  /** Arm every active lane controller. */
   _arm_all() {
     this._correlate.arm();
     for (const c of this._drain_controllers.values()) c.arm();
   }
-  /**
-   * Arm only the lane controllers whose reactions match the supplied
-   * event names (selective arming). Events with any dynamic
-   * resolver fall back to `_arm_all()` via the `"all"` sentinel — the
-   * resolver's lane isn't known until correlate runs the function.
-   * Events with no reactions are skipped; `_event_to_lanes` doesn't
-   * carry them. Returns true when any controller was armed (used by
-   * the notify handler to decide whether to schedule a settle).
-   */
+  /** Arms only the lanes these events react on; true when any was armed. */
   _arm_for_event_names(names) {
     const to_arm = /* @__PURE__ */ new Set();
     for (const name of names) {
@@ -4026,14 +3880,7 @@ var Act = class {
     for (const lane of to_arm) this._drain_controllers.get(lane)?.arm();
     return true;
   }
-  /** Drain every active lane controller in parallel and aggregate.
-   *
-   * Parallel — not sequential — so a slow lane's in-flight handler does
-   * not block a fast lane's claim/dispatch/ack cycle. Each controller's
-   * `claim()` is independent (filtered by lane); the store's
-   * `SKIP LOCKED` keeps cross-controller races safe. Lifecycle events
-   * (`acked`, `blocked`) may interleave by lane — listeners filter via
-   * `lease.lane`. */
+  /** In parallel, so a slow lane never holds up a fast one. */
   async _drain_all(options) {
     const results = await Promise.all(
       [...this._drain_controllers.values()].map((c) => c.drain(options))
@@ -4106,14 +3953,7 @@ var Act = class {
     const { subscribed, last_id } = await this._correlate_scanned(query);
     return { subscribed, last_id };
   }
-  /**
-   * `correlate` plus whether the pass actually read the store.
-   *
-   * The settle loop needs that extra bit to decide whether the pass carries a
-   * circuit-breaker health signal, and a disarmed pass carries none. It stays
-   * internal rather than widening the public `correlate` return, which is
-   * charter-covered and has no use for it.
-   */
+  /** `correlate` plus `scanned`, which settle needs for the breaker. */
   async _correlate_scanned(query, lease = false) {
     if (!this._drain) return { subscribed: 0, last_id: -1, scanned: false };
     return this._scoped(async () => {
@@ -4454,11 +4294,7 @@ var Act = class {
   async prioritize(filter, priority) {
     return this._scoped(() => store().prioritize(filter, priority));
   }
-  /**
-   * Run one close: the cycle with this Act's ports, then emit `closed`. Shared by `close()` and the drain's
-   * reaction-requested closes. The close actor lets a custom correlator
-   * still tag tenant context or trace ids.
-   */
+  /** Shared by `close()` and reaction-requested closes. */
   async _run_close(targets) {
     const close_actor = { id: "$close", name: "close" };
     const result = await run_close_cycle(targets, {
@@ -4539,10 +4375,7 @@ var Act = class {
    */
   async close(targets) {
     if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
-    return this._scoped(async () => {
-      await this.correlate({ limit: CLOSE_CATCH_UP_LIMIT });
-      return this._run_close(targets);
-    });
+    return this._scoped(() => this._run_close(targets));
   }
   /**
    * Debounced, non-blocking correlate→drain cycle.