@rotorsoft/act 1.32.23 → 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))
@@ -1584,71 +1565,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 = 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,
@@ -1669,28 +1606,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) {
@@ -1717,16 +1639,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;
@@ -1735,21 +1648,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;
@@ -1760,16 +1663,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)
@@ -1854,10 +1748,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);
@@ -1900,14 +1792,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);
@@ -1943,13 +1830,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;
@@ -2232,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 {
@@ -2426,38 +2319,28 @@ 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 }
     }
   );
   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,
     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,
@@ -2519,8 +2402,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,
@@ -2540,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;
@@ -2574,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) {
@@ -2923,61 +2787,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;
   }
@@ -2985,19 +2823,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;
@@ -3010,7 +2839,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) {
@@ -3019,7 +2847,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;
@@ -3393,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
@@ -3453,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);
@@ -3483,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;
@@ -3542,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;
@@ -3612,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),
@@ -3630,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;
@@ -3670,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());
@@ -3696,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,
@@ -3718,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) => {
@@ -3732,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(
       {
@@ -3746,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
@@ -3786,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;
@@ -3822,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;
@@ -4139,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) {
@@ -4169,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))
@@ -4249,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 () => {
@@ -4597,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, {
@@ -4682,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.