@rotorsoft/act 1.32.22 → 1.32.24

package/dist/index.cjs

@@ -1142,25 +1142,19 @@ var InMemoryStore = class {
    */
   async defer(input, deferred_at) {
     await sleep();
-    let count = 0;
-    if (Array.isArray(input)) {
-      for (const name of new Set(input)) {
-        const s = this._streams.get(name);
-        if (s) {
-          s.defer(deferred_at);
-          count++;
-        }
-      }
-    } else {
-      const matches = this._filter_predicate(input);
-      for (const s of this._streams.values()) {
-        if (matches(s)) {
-          s.defer(deferred_at);
-          count++;
-        }
-      }
-    }
-    return count;
+    const selected = this._select(input);
+    for (const s of selected) s.defer(deferred_at);
+    return selected.length;
+  }
+  /**
+   * The streams named by `input`: an explicit list (de-duplicated, so a
+   * repeated name counts once, matching the SQL adapters' set-based
+   * `stream = ANY(...)`; unknown names are skipped) or a {@link StreamFilter}.
+   */
+  _select(input) {
+    if (Array.isArray(input))
+      return [...new Set(input)].map((name) => this._streams.get(name)).filter((s) => s !== void 0);
+    return [...this._streams.values()].filter(this._filter_predicate(input));
   }
   /**
    * Build a predicate from a {@link StreamFilter}. Compiled regexes are
@@ -1196,37 +1190,10 @@ var InMemoryStore = class {
    */
   async reset(input) {
     await sleep();
-    let count = 0;
-    if (Array.isArray(input)) {
-      for (const name of new Set(input)) {
-        const s = this._streams.get(name);
-        if (s) {
-          s.reset();
-          count++;
-        }
-      }
-    } else {
-      const matches = this._filter_predicate(input);
-      for (const s of this._streams.values()) {
-        if (matches(s)) {
-          s.reset();
-          count++;
-        }
-      }
-    }
-    return count;
+    const selected = this._select(input);
+    for (const s of selected) s.reset();
+    return selected.length;
   }
-  /**
-   * Clear the blocked flag (and retry / error / lease) on the matched
-   * streams without touching the watermark. Streams that aren't blocked
-   * at call time are silently skipped. Accepts either an explicit list
-   * of names or a {@link StreamFilter}. The filter form always restricts
-   * to blocked streams — passing `blocked: false` matches nothing.
-   * See {@link Store.unblock}.
-   *
-   * @param input - Stream names or a filter selecting the streams to unblock.
-   * @returns Count of streams that were actually flipped (were blocked).
-   */
   /**
    * Wipe the sensitive-data payload for every event on the stream — see
    * {@link Store.forget_pii}. O(1) drop of the stream's inner Map; the size of
@@ -1242,21 +1209,23 @@ var InMemoryStore = class {
     this._pii.delete(stream);
     return count;
   }
+  /**
+   * Clear the blocked flag (and retry / error / lease) on the matched
+   * streams without touching the watermark. Streams that aren't blocked
+   * at call time are silently skipped. Accepts either an explicit list
+   * of names or a {@link StreamFilter}. The filter form always restricts
+   * to blocked streams — passing `blocked: false` matches nothing.
+   * See {@link Store.unblock}.
+   *
+   * @param input - Stream names or a filter selecting the streams to unblock.
+   * @returns Count of streams that were actually flipped (were blocked).
+   */
   async unblock(input) {
     await sleep();
-    let count = 0;
-    if (Array.isArray(input)) {
-      for (const name of input) {
-        const s = this._streams.get(name);
-        if (s?.unblock()) count++;
-      }
-    } else {
-      const matches = this._filter_predicate({ ...input, blocked: true });
-      for (const s of this._streams.values()) {
-        if (matches(s) && s.unblock()) count++;
-      }
-    }
-    return count;
+    const selected = this._select(
+      Array.isArray(input) ? input : { ...input, blocked: true }
+    );
+    return selected.filter((s) => s.unblock()).length;
   }
   /**
    * Bulk-update priority of streams matching `filter`. Mirrors
@@ -1269,16 +1238,9 @@ var InMemoryStore = class {
    */
   async prioritize(filter, priority) {
     await sleep();
-    const matches = this._filter_predicate(filter);
-    let count = 0;
-    for (const s of this._streams.values()) {
-      if (!matches(s)) continue;
-      if (s.priority !== priority) {
-        s.set_priority(priority);
-        count++;
-      }
-    }
-    return count;
+    const changed = this._select(filter).filter((s) => s.priority !== priority);
+    for (const s of changed) s.set_priority(priority);
+    return changed.length;
   }
   /**
    * Streams registered subscription positions to the callback, ordered by
@@ -1289,10 +1251,8 @@ var InMemoryStore = class {
     await sleep();
     const limit = query?.limit ?? 100;
     const after = query?.after;
-    const blocked = query?.blocked;
     const source_matches = query?.source_matches;
-    const stream_re = query?.stream !== void 0 && !query.stream_exact ? new RegExp(query.stream) : void 0;
-    const source_re = query?.source !== void 0 && !query.source_exact ? new RegExp(query.source) : void 0;
+    const matches = this._filter_predicate(query ?? {});
     const reverse_cache = /* @__PURE__ */ new Map();
     const reverse_match = (source) => {
       let re = reverse_cache.get(source);
@@ -1306,20 +1266,10 @@ var InMemoryStore = class {
     let count = 0;
     for (const s of sorted) {
       if (after !== void 0 && s.stream <= after) continue;
-      if (query?.stream !== void 0) {
-        if (query.stream_exact ? s.stream !== query.stream : !stream_re.test(s.stream))
-          continue;
-      }
-      if (query?.source !== void 0) {
-        if (s.source === void 0) continue;
-        if (query.source_exact ? s.source !== query.source : !source_re.test(s.source))
-          continue;
-      }
+      if (!matches(s)) continue;
       if (source_matches !== void 0) {
         if (s.source && !reverse_match(s.source)) continue;
       }
-      if (blocked !== void 0 && s.blocked !== blocked) continue;
-      if (query?.lane !== void 0 && s.lane !== query.lane) continue;
       if (count >= limit) break;
       callback({
         stream: s.stream,
@@ -3178,71 +3128,27 @@ function report_lane_conflict(seen, handler, target, kept, dropped) {
 var CorrelateCycle = class {
   _checkpoint = -1;
   _initialized = false;
-  /**
-   * This worker's identity for the correlation lease. A per-instance
-   * UUID, matching the drain's convention, so a renewal is recognised as the
-   * same holder and a restarted process never inherits a stale claim.
-   */
+  /** Lease holder id; per instance, so a restart never inherits a stale claim. */
   _by = (0, import_node_crypto.randomUUID)();
-  /**
-   * Which correlator this is. Computed once from the registry so identical
-   * workers share a lease and unrelated applications never do.
-   */
   _key;
-  /**
-   * When this worker's correlation lease runs out, as a local clock reading,
-   * or 0 when it holds none.
-   *
-   * Cached so the holder doesn't ask the store on every pass. A stale belief
-   * can only cause a duplicate scan, and marks are idempotent, so it costs
-   * work, never correctness.
-   */
+  /** Local expiry of the held lease (0 = none); stale only costs a duplicate scan. */
   _lease_until = 0;
-  /**
-   * Whether a scan might find anything, like the drain's flag: a commit or
-   * notification raises it, a short page lowers it, and a disarmed scan
-   * returns without touching the store.
-   *
-   * Starts armed: the log may already hold events this process has never
-   * correlated, and only a scan can find out.
-   */
+  /** Raised by a commit or notification, lowered by a short page. Starts armed. */
   _armed = true;
-  /** In-flight init, memoized for single-flight and cleared on failure. */
   _init_promise;
-  // Dynamically discovered targets → what each was last subscribed at,
-  // bounded by `maxSubscribedStreams`. It decides *what* a scan sends with a
-  // target: priority/lane only when the resolution beats the recorded floor,
-  // otherwise the row's own values. See {@link Subscription}.
+  // Bounded by `maxSubscribedStreams`; static records live apart so eviction
+  // never drops their +Infinity floor.
   _dynamic_subscriptions;
-  /**
-   * What each static target was subscribed at by `init`. A plain map, never
-   * evicted: the collection is the build-time `_static_targets` list, so it
-   * is already bounded by the registry and costs nothing the registry does
-   * not already hold.
-   *
-   * Kept out of the LRU so eviction can never drop a static target's
-   * `+Infinity` floor and let a dynamic resolution re-lane it.
-   */
   _static_subscriptions = /* @__PURE__ */ new Map();
-  /** Compiled pattern sources, bounded by {@link PATTERN_CACHE_SIZE}. */
   _patterns = new LruMap(PATTERN_CACHE_SIZE);
   _registry;
   _static_targets;
   _cd;
   _on_init;
-  /**
-   * Async cold-start hook, run once after `on_init` inside `init()`. The
-   * orchestrator re-seeds its defer timers from the persisted `deferred_at`
-   * here, so an idle deferred stream re-arms across a restart.
-   */
+  /** Runs once after `on_init`; re-seeds defer timers across a restart. */
   _on_init_async;
-  /** Lanes a controller exists for. See {@link CorrelateCycleDeps}. */
   _declared_lanes;
-  /**
-   * Offending declarations already reported, so a resolver firing for every
-   * matching event reports once. Owned by the instance rather than the
-   * module: `internal/` holds no module-level state.
-   */
+  /** Report-once keys; per instance because `internal/` holds no module state. */
   _reported = /* @__PURE__ */ new Set();
   constructor({
     registry,
@@ -3263,28 +3169,13 @@ var CorrelateCycle = class {
     this._on_init = on_init;
     this._on_init_async = on_init_async;
   }
-  /** Last correlated event id. */
   get checkpoint() {
     return this._checkpoint;
   }
-  /**
-   * Signal that a commit (local or remote) may have produced events this
-   * process has not correlated. Cheap and idempotent — the orchestrator calls
-   * it on every commit and every notification.
-   */
+  /** A commit (local or remote) may have produced uncorrelated events. */
   arm() {
     this._armed = true;
   }
-  /**
-   * Initialize correlation state on first call.
-   * - Reads the durable correlate checkpoint (and max(at)) from the store,
-   *   flooring a first boot at `watermark - back_scan` so an event
-   *   committed-but-not-correlated before a crash is re-scanned on
-   *   restart instead of skipped
-   * - Subscribes static resolver targets (idempotent upsert)
-   * - Populates the subscribed-streams LRU
-   * - Fires `on_init` once (Act uses this to flag a cold-start drain)
-   */
   async init() {
     if (this._initialized) return;
     if (!this._init_promise) {
@@ -3311,16 +3202,7 @@ var CorrelateCycle = class {
     }
     await this._on_init_async?.();
   }
-  /**
-   * Start correlation over after the event log was replaced wholesale
-   * (`restore`). The restored log is renumbered from the start and its
-   * subscription rows are gone, so the in-memory scan position and both
-   * subscription records describe a log that no longer exists. Dropping them
-   * and the init latch makes the next pass run cold-start again: static
-   * targets are re-subscribed, the checkpoint is re-read from the store
-   * (which `restore` reset), and dynamic targets are rediscovered by the
-   * scan.
-   */
+  /** After `restore` replaced the log: forget everything and cold-start again. */
   restart() {
     this._initialized = false;
     this._init_promise = void 0;
@@ -3329,21 +3211,11 @@ var CorrelateCycle = class {
     this._static_subscriptions.clear();
     this._armed = true;
   }
-  /**
-   * Forget dynamic targets whose subscription rows no longer exist (a full
-   * close deletes the row), so a later scan re-subscribes them. Static
-   * targets keep their records.
-   */
+  /** Forget dynamic targets whose rows a full close deleted, so they re-subscribe. */
   forget_subscribed(streams) {
     for (const stream of streams) this._dynamic_subscriptions.delete(stream);
   }
-  /**
-   * Would an event from `stream` be fetched for a target subscribed with
-   * `source`? The subscription's source is the filter `fetch` queries with
-   * — literal names by equality, patterns compiled as a `RegExp` — so an
-   * event outside it is not work for that target and must not mark it.
-   * No source means the target consumes every stream.
-   */
+  /** Would the target's own `fetch` (filtered by `source`) return this event? */
   _in_fetch_window(source, stream) {
     if (source === void 0 || source === stream) return true;
     if (is_literal_source(source)) return false;
@@ -3354,16 +3226,7 @@ var CorrelateCycle = class {
     }
     return pattern.test(stream);
   }
-  /**
-   * Scan the events past the checkpoint, resolve each to its target
-   * streams, and record what it found through `cd.subscribe` — new dynamic
-   * targets get registered, and every target an event resolved to gets its
-   * **work mark** raised to that event's id.
-   *
-   * Both resolver kinds are walked. A static target is already subscribed
-   * at init, but marking it is what makes it claimable without probing the
-   * event log, so the scan runs for every app.
-   */
+  /** Scan past the checkpoint, subscribe new targets and raise their work marks. */
   async correlate(query = { after: -1, limit: 10 }, lease = false) {
     await this.init();
     if (!this._armed)
@@ -3448,10 +3311,8 @@ var CorrelateCycle = class {
           }
         }
       },
-      // Decline the sensitive payload: the scan only needs name/stream/id,
-      // and one undecryptable row would otherwise stop every stream's
-      // reactions. Resolvers therefore see `pii: null`; correlate runs
-      // actor-less, so plaintext here would be un-gated disclosure.
+      // Resolvers see `pii: null`: correlate runs actor-less, and one
+      // undecryptable row would otherwise stop every stream's reactions.
       { ...query, after, with_pii: false }
     );
     if (this._declared_lanes.size > 1) await this._recall(correlated);
@@ -3494,14 +3355,9 @@ var CorrelateCycle = class {
     return { subscribed: 0, last_id, marked: 0, scanned: true };
   }
   /**
-   * Give each target this scan had no record of the record its row holds.
-   *
-   * A target with no record is either new or forgotten. Its row, when it
-   * has one, says what lane and priority it was subscribed at; a resolution
-   * that doesn't beat that priority carries the row's values, exactly as if
-   * the record had never been evicted. One read per target with no record,
-   * and only when more than one lane is declared: with one lane there is no
-   * lane to lose, and the store already keeps the higher priority.
+   * Read the row of each target this scan had no record of (new or evicted),
+   * so a resolution that doesn't beat its priority keeps the row's lane.
+   * Only called with more than one lane declared.
    */
   async _recall(correlated) {
     const missed = [...correlated].filter(([, entry]) => entry.missed);
@@ -3537,13 +3393,7 @@ var CorrelateCycle = class {
       })
     );
   }
-  /**
-   * Hand the correlation lease back early.
-   *
-   * The port has no release verb; re-acquiring as the same holder with a
-   * zero duration releases it. Best-effort: a failure costs the lease's
-   * remaining lifetime, as a crash would.
-   */
+  /** Release the lease early by re-acquiring it for zero ms. Best-effort. */
   async release_correlation() {
     try {
       this._lease_until = 0;
@@ -4020,11 +3870,9 @@ async function load(me, target, callback, patch_fn = bare_patch) {
     {
       stream,
       stream_exact: true,
-      // `with_snaps` on every non-time-travel load. Cold, it resumes from the
-      // latest snapshot (this is the only place that decides it; stores just
-      // apply it). Warm, it keeps a snapshot above a stale checkpoint in the
-      // result, so a windowed close that pruned the events in between can't
-      // make the fold apply the tail onto stale state.
+      // `with_snaps` on every non-time-travel load: cold, it resumes from the
+      // latest snapshot; warm, it keeps a snapshot above a stale checkpoint,
+      // so a windowed close's prune can't fold the tail onto stale state.
       ...cached ? { after: cached.event_id, with_snaps: true } : { ...time_travel ? {} : { with_snaps: true }, ...asOf }
     }
   );
@@ -4048,10 +3896,7 @@ async function load(me, target, callback, patch_fn = bare_patch) {
     event,
     state: state2,
     version: event?.version ?? cached?.version ?? -1,
-    // Head event id, captured atomically with `state`: the last replayed
-    // event's id on a cache miss, or the cached checkpoint's event_id on a
-    // warm hit with no new events. Consumers read this instead of a
-    // separate cache lookup that could race a concurrent commit.
+    // Captured with `state`, so consumers never race a separate cache lookup.
     id: event?.id ?? cached?.event_id ?? -1,
     patches,
     snaps,
@@ -4113,8 +3958,7 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
           action: {
             name: action2,
             ...target
-            // payload intentionally omitted from causation metadata —
-            // callers correlate via the correlation id when they need it.
+            // payload intentionally omitted
           },
           event: reactingTo ? {
             id: reactingTo.id,
@@ -4517,61 +4361,35 @@ var DrainController = class {
   _locked = false;
   _ratio = 0.5;
   /**
-   * Local wake for streams this worker parked (backoff or defer). The
-   * schedule itself is persisted in the store; this runs the drain at the
-   * earliest pending visit. A parked stream already carries its mark, so
-   * the drain alone finds it, and on an idle app nothing else would.
-   * Every drain re-aims it when it ends, and a due entry stays until a pass
-   * handles it or a pass that started after it came due claims nothing, so
-   * the wake keeps draining until every due stream is reached.
-   * `stop()` cancels the timer and a stopped drain never re-schedules it,
-   * so a wake never runs after a stop.
+   * Local wake at the earliest parked (backoff or defer) visit; the schedule
+   * itself is persisted. On an idle app nothing else would drain it. A due
+   * entry stays until handled or until a later pass claims nothing.
    */
   _defer = new DeferTimer(() => {
     this._armed = true;
     void this._deps.run_scoped(() => this.drain());
   });
-  /** Worker timer. Set when `start()` is active, undefined otherwise. */
   _worker;
-  /**
-   * Misroutings this controller has reported. A resolver returning a
-   * projection's target does so for every matching event; one line per event
-   * would bury the signal it exists to raise.
-   */
   _misrouted = /* @__PURE__ */ new Set();
   _stopped = false;
-  /**
-   * Resolves when the cycle in flight finishes, so a graceful shutdown can
-   * wait for it. Never rejects.
-   */
+  /** Never rejects; graceful shutdown waits on it. */
   _inflight;
   _inflight_done;
   _deps;
   constructor(deps) {
     this._deps = deps;
   }
-  /**
-   * Signal that a commit (or reset / cold-start) may have produced work.
-   * Subsequent `drain()` calls will run the pipeline; once the pipeline
-   * settles to no-progress, the controller disarms itself.
-   */
   arm() {
     this._armed = true;
   }
-  /**
-   * Re-seed a persisted `deferred_at` into the local wake at cold start, so
-   * an idle deferred stream re-arms at its due-time with no new commit.
-   * Seeds collapse into one timer; the earliest wins.
-   */
+  /** Cold start: re-seed a persisted `deferred_at` into the local wake. */
   seed_defer(stream, at) {
     this._defer.set(stream, at);
     this._defer.schedule();
   }
-  /** Read-only flag — true while a commit / reset is unprocessed. */
   get armed() {
     return this._armed;
   }
-  /** The cycle in flight, or `undefined` when idle. */
   get inflight() {
     return this._inflight;
   }
@@ -4579,19 +4397,10 @@ var DrainController = class {
   get lease_millis() {
     return this._deps.defaults?.leaseMillis;
   }
-  /** Lane this controller drains (undefined spans all lanes). */
   get lane() {
     return this._deps.lane;
   }
-  /**
-   * Start a per-lane worker that drains at the lane's `cycleMs`
-   * cadence. When armed, the worker calls `drain()` on every
-   * tick and re-schedules; when not armed, it still re-schedules at
-   * `cycleMs` so a future `arm()` is picked up on the next tick.
-   *
-   * The setTimeout chain uses `unref()` so it doesn't keep the process
-   * alive on its own.
-   */
+  /** Drains every `cycleMs` while armed; the unref'd timer never holds the process. */
   start(cycleMs) {
     if (this._worker || this._stopped) return;
     const run = this._deps.run_scoped;
@@ -4604,7 +4413,6 @@ var DrainController = class {
     this._worker = setTimeout(tick, cycleMs);
     this._worker.unref();
   }
-  /** Stop the per-lane worker. Idempotent. */
   stop() {
     this._stopped = true;
     if (this._worker) {
@@ -4613,7 +4421,6 @@ var DrainController = class {
     }
     this._defer.stop();
   }
-  /** Run one drain pass. Short-circuits when not armed or already running. */
   async drain(options = {}) {
     if (!this._armed) return EMPTY_DRAIN;
     if (this._locked) return EMPTY_DRAIN;