@rotorsoft/act 0.32.7 → 0.33.1

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   ConcurrencyError: () => ConcurrencyError,
   ConsoleLogger: () => ConsoleLogger,
   DEFAULT_MAX_SUBSCRIBED_STREAMS: () => DEFAULT_MAX_SUBSCRIBED_STREAMS,
+  DEFAULT_SETTLE_DEBOUNCE_MS: () => DEFAULT_SETTLE_DEBOUNCE_MS,
   Environments: () => Environments,
   Errors: () => Errors,
   EventMetaSchema: () => EventMetaSchema,
@@ -183,7 +184,7 @@ var ConsoleLogger = class _ConsoleLogger {
   }
 };
 
-// src/internal/lru-map.ts
+// src/lru-map.ts
 var LruMap = class {
   constructor(_maxSize) {
     this._maxSize = _maxSize;
@@ -973,6 +974,37 @@ process.once("unhandledRejection", async (arg) => {
 // src/act.ts
 var import_events = __toESM(require("events"), 1);
 
+// src/internal/build-classify.ts
+function classifyRegistry(registry, states) {
+  const statics = /* @__PURE__ */ new Map();
+  const reactiveEvents = /* @__PURE__ */ new Set();
+  let hasDynamicResolvers = false;
+  for (const [name, register] of Object.entries(registry.events)) {
+    if (register.reactions.size > 0) reactiveEvents.add(name);
+    for (const reaction of register.reactions.values()) {
+      if (typeof reaction.resolver === "function") {
+        hasDynamicResolvers = true;
+      } else {
+        const { target, source } = reaction.resolver;
+        const key = `${target}|${source ?? ""}`;
+        if (!statics.has(key)) statics.set(key, { stream: target, source });
+      }
+    }
+  }
+  const eventToState = /* @__PURE__ */ new Map();
+  for (const merged of states.values()) {
+    for (const eventName of Object.keys(merged.events)) {
+      eventToState.set(eventName, merged);
+    }
+  }
+  return {
+    staticTargets: [...statics.values()],
+    hasDynamicResolvers,
+    reactiveEvents,
+    eventToState
+  };
+}
+
 // src/internal/close-cycle.ts
 var import_crypto = require("crypto");
 async function runCloseCycle(targets, deps) {
@@ -1128,8 +1160,142 @@ async function truncateAndWarmCache(guarded, seedStates, guardEvents, correlatio
   return truncated;
 }
 
+// src/internal/correlate-cycle.ts
+var CorrelateCycle = class {
+  constructor(registry, staticTargets, hasDynamicResolvers, cd, maxSubscribedStreams, onInit) {
+    this.registry = registry;
+    this.staticTargets = staticTargets;
+    this.hasDynamicResolvers = hasDynamicResolvers;
+    this.cd = cd;
+    this.onInit = onInit;
+    this._subscribed = new LruSet(maxSubscribedStreams);
+  }
+  _checkpoint = -1;
+  _initialized = false;
+  _timer = void 0;
+  _subscribed;
+  /** Last correlated event id. */
+  get checkpoint() {
+    return this._checkpoint;
+  }
+  /**
+   * Initialize correlation state on first call.
+   * - Reads max(at) from store as cold-start checkpoint
+   * - Subscribes static resolver targets (idempotent upsert)
+   * - Populates the subscribed-streams LRU
+   * - Fires `onInit` once (Act uses this to flag a cold-start drain)
+   */
+  async init() {
+    if (this._initialized) return;
+    this._initialized = true;
+    const { watermark } = await store().subscribe([...this.staticTargets]);
+    this._checkpoint = watermark;
+    this.onInit?.();
+    for (const { stream } of this.staticTargets) {
+      this._subscribed.add(stream);
+    }
+  }
+  /**
+   * Discover dynamic-resolver targets in the events past the checkpoint
+   * and register any new streams via `cd.subscribe`. Static targets are
+   * subscribed at init time, so this only walks dynamic resolvers.
+   */
+  async correlate(query = { after: -1, limit: 10 }) {
+    await this.init();
+    if (!this.hasDynamicResolvers)
+      return { subscribed: 0, last_id: this._checkpoint };
+    const after = Math.max(this._checkpoint, query.after || -1);
+    const correlated = /* @__PURE__ */ new Map();
+    let last_id = after;
+    await store().query(
+      (event) => {
+        last_id = event.id;
+        const register = this.registry.events[event.name];
+        if (register) {
+          for (const reaction of register.reactions.values()) {
+            if (typeof reaction.resolver !== "function") continue;
+            const resolved = reaction.resolver(event);
+            if (resolved && !this._subscribed.has(resolved.target)) {
+              const entry = correlated.get(resolved.target) || {
+                source: resolved.source,
+                payloads: []
+              };
+              entry.payloads.push({
+                ...reaction,
+                source: resolved.source,
+                event
+              });
+              correlated.set(resolved.target, entry);
+            }
+          }
+        }
+      },
+      { ...query, after }
+    );
+    if (correlated.size) {
+      const streams = [...correlated.entries()].map(([stream, { source }]) => ({
+        stream,
+        source
+      }));
+      const { subscribed } = await this.cd.subscribe(streams);
+      this._checkpoint = last_id;
+      if (subscribed) {
+        for (const { stream } of streams) {
+          this._subscribed.add(stream);
+        }
+      }
+      return { subscribed, last_id };
+    }
+    this._checkpoint = last_id;
+    return { subscribed: 0, last_id };
+  }
+  /**
+   * Start a periodic correlation worker. Returns false if one is already
+   * running. Errors from `correlate()` are sent to `console.error` (matches
+   * pre-extraction behavior; the timer keeps running on failure).
+   */
+  startPolling(query = {}, frequency = 1e4, callback) {
+    if (this._timer) return false;
+    const limit = query.limit || 100;
+    this._timer = setInterval(
+      () => this.correlate({ ...query, after: this._checkpoint, limit }).then((result) => {
+        if (callback && result.subscribed) callback(result.subscribed);
+      }).catch(console.error),
+      frequency
+    );
+    return true;
+  }
+  /** Stop the periodic correlation worker. Idempotent. */
+  stopPolling() {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = void 0;
+    }
+  }
+};
+
 // src/internal/drain-cycle.ts
 var import_crypto2 = require("crypto");
+
+// src/internal/drain-ratio.ts
+var RATIO_MIN = 0.2;
+var RATIO_MAX = 0.8;
+var RATIO_DEFAULT = 0.5;
+function computeLagLeadRatio(handled, lagging, leading) {
+  let lagging_handled = 0;
+  let leading_handled = 0;
+  for (const { lease, handled: count } of handled) {
+    if (lease.lagging) lagging_handled += count;
+    else leading_handled += count;
+  }
+  const lagging_avg = lagging > 0 ? lagging_handled / lagging : 0;
+  const leading_avg = leading > 0 ? leading_handled / leading : 0;
+  const total = lagging_avg + leading_avg;
+  if (total === 0) return RATIO_DEFAULT;
+  return Math.max(RATIO_MIN, Math.min(RATIO_MAX, lagging_avg / total));
+}
+
+// src/internal/drain-cycle.ts
 async function runDrainCycle(ops, registry, batchHandlers, handle, handleBatch, lagging, leading, eventLimit, leaseMillis) {
   const leased = await ops.claim(lagging, leading, (0, import_crypto2.randomUUID)(), leaseMillis);
   if (!leased.length) return void 0;
@@ -1171,24 +1337,73 @@ async function runDrainCycle(ops, registry, batchHandlers, handle, handleBatch,
   );
   return { leased, fetched, handled, acked, blocked };
 }
-
-// src/internal/drain-ratio.ts
-var RATIO_MIN = 0.2;
-var RATIO_MAX = 0.8;
-var RATIO_DEFAULT = 0.5;
-function computeLagLeadRatio(handled, lagging, leading) {
-  let lagging_handled = 0;
-  let leading_handled = 0;
-  for (const { lease, handled: count } of handled) {
-    if (lease.lagging) lagging_handled += count;
-    else leading_handled += count;
+var EMPTY_DRAIN = {
+  fetched: [],
+  leased: [],
+  acked: [],
+  blocked: []
+};
+var DrainController = class {
+  constructor(deps) {
+    this.deps = deps;
   }
-  const lagging_avg = lagging > 0 ? lagging_handled / lagging : 0;
-  const leading_avg = leading > 0 ? leading_handled / leading : 0;
-  const total = lagging_avg + leading_avg;
-  if (total === 0) return RATIO_DEFAULT;
-  return Math.max(RATIO_MIN, Math.min(RATIO_MAX, lagging_avg / total));
-}
+  _armed = false;
+  _locked = false;
+  _ratio = 0.5;
+  /**
+   * 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;
+  }
+  /** Read-only flag — true while a commit / reset is unprocessed. */
+  get armed() {
+    return this._armed;
+  }
+  /** Run one drain pass. Short-circuits when not armed or already running. */
+  async drain({
+    streamLimit = 10,
+    eventLimit = 10,
+    leaseMillis = 1e4
+  } = {}) {
+    if (!this._armed) return EMPTY_DRAIN;
+    if (this._locked) return EMPTY_DRAIN;
+    try {
+      this._locked = true;
+      const lagging = Math.ceil(streamLimit * this._ratio);
+      const leading = streamLimit - lagging;
+      const cycle = await runDrainCycle(
+        this.deps.ops,
+        this.deps.registry,
+        this.deps.batchHandlers,
+        this.deps.handle,
+        this.deps.handleBatch,
+        lagging,
+        leading,
+        eventLimit,
+        leaseMillis
+      );
+      if (!cycle) {
+        this._armed = false;
+        return EMPTY_DRAIN;
+      }
+      const { leased, fetched, handled, acked, blocked } = cycle;
+      this._ratio = computeLagLeadRatio(handled, lagging, leading);
+      if (acked.length) this.deps.onAcked(acked);
+      if (blocked.length) this.deps.onBlocked(blocked);
+      const hasErrors = handled.some(({ error }) => error);
+      if (!acked.length && !blocked.length && !hasErrors) this._armed = false;
+      return { fetched, leased, acked, blocked };
+    } catch (error) {
+      this.deps.logger.error(error);
+      return EMPTY_DRAIN;
+    } finally {
+      this._locked = false;
+    }
+  }
+};
 
 // src/internal/merge.ts
 var import_zod4 = require("zod");
@@ -1329,6 +1544,140 @@ var _this_ = ({ stream }) => ({
   target: stream
 });
 
+// src/internal/reactions.ts
+function finalize(lease, handled, at, error, options, logger) {
+  if (!error) return { lease, handled, at };
+  logger.error(error);
+  const block2 = lease.retry >= options.maxRetries && options.blockOnError;
+  if (block2)
+    logger.error(`Blocking ${lease.stream} after ${lease.retry} retries.`);
+  return {
+    lease,
+    handled,
+    at,
+    error: handled === 0 ? error.message : void 0,
+    block: block2
+  };
+}
+function buildHandle(deps) {
+  const { logger, boundDo, boundLoad, boundQuery, boundQueryArray } = deps;
+  return async (lease, payloads) => {
+    if (payloads.length === 0) return { lease, handled: 0, at: lease.at };
+    const stream = lease.stream;
+    let at = payloads.at(0).event.id;
+    let handled = 0;
+    if (lease.retry > 0)
+      logger.warn(`Retrying ${stream}@${at} (${lease.retry}).`);
+    const scopedApp = {
+      do: boundDo,
+      load: boundLoad,
+      query: boundQuery,
+      query_array: boundQueryArray
+    };
+    for (const payload of payloads) {
+      const { event, handler } = payload;
+      scopedApp.do = (action2, target, actionPayload, reactingTo, skipValidation) => boundDo(
+        action2,
+        target,
+        actionPayload,
+        reactingTo ?? event,
+        skipValidation
+      );
+      try {
+        await handler(event, stream, scopedApp);
+        at = event.id;
+        handled++;
+      } catch (error) {
+        return finalize(
+          lease,
+          handled,
+          at,
+          error,
+          payload.options,
+          logger
+        );
+      }
+    }
+    return finalize(lease, handled, at, void 0, payloads[0].options, logger);
+  };
+}
+function buildHandleBatch(logger) {
+  return async (lease, payloads, batchHandler) => {
+    const stream = lease.stream;
+    const events = payloads.map((p) => p.event);
+    const options = payloads[0].options;
+    if (lease.retry > 0)
+      logger.warn(`Retrying batch ${stream}@${events[0].id} (${lease.retry}).`);
+    try {
+      await batchHandler(events, stream);
+      return finalize(
+        lease,
+        events.length,
+        events.at(-1).id,
+        void 0,
+        options,
+        logger
+      );
+    } catch (error) {
+      return finalize(lease, 0, lease.at, error, options, logger);
+    }
+  };
+}
+
+// src/internal/settle.ts
+var SettleLoop = class {
+  constructor(deps, defaultDebounceMs) {
+    this.deps = deps;
+    this.defaultDebounceMs = defaultDebounceMs;
+  }
+  _timer = void 0;
+  _running = false;
+  /**
+   * Schedule a settle pass. Multiple calls inside the debounce window
+   * coalesce into one cycle. The cycle runs correlate→drain in a loop
+   * until no progress is made (no new subscriptions, no acks, no blocks)
+   * or `maxPasses` is reached, then emits the `"settled"` lifecycle event
+   * via {@link SettleDeps.onSettled}.
+   */
+  schedule(options = {}) {
+    const {
+      debounceMs = this.defaultDebounceMs,
+      correlate: correlateQuery = { after: -1, limit: 100 },
+      maxPasses = Infinity,
+      ...drainOptions
+    } = options;
+    if (this._timer) clearTimeout(this._timer);
+    this._timer = setTimeout(() => {
+      this._timer = void 0;
+      if (this._running) return;
+      this._running = true;
+      (async () => {
+        await this.deps.init();
+        let lastDrain;
+        for (let i = 0; i < maxPasses; i++) {
+          const { subscribed } = await this.deps.correlate({
+            ...correlateQuery,
+            after: this.deps.checkpoint()
+          });
+          lastDrain = await this.deps.drain(drainOptions);
+          const made_progress = subscribed > 0 || lastDrain.acked.length > 0 || lastDrain.blocked.length > 0;
+          if (!made_progress) break;
+        }
+        if (lastDrain) this.deps.onSettled(lastDrain);
+      })().catch((err) => this.deps.logger.error(err)).finally(() => {
+        this._running = false;
+      });
+    }, debounceMs);
+  }
+  /** Cancel any pending or active settle cycle. Idempotent. */
+  stop() {
+    if (this._timer) {
+      clearTimeout(this._timer);
+      this._timer = void 0;
+    }
+  }
+};
+
 // src/internal/drain.ts
 var claim = (lagging, leading, by, millis) => store().claim(lagging, leading, by, millis);
 async function fetch(leased, eventLimit) {
@@ -1385,26 +1734,40 @@ async function tombstone(stream, expectedVersion, correlation) {
 async function load(me, stream, callback, asOf) {
   const timeTravel = !!asOf && Object.values(asOf).some((v) => v !== void 0);
   const cached = timeTravel ? void 0 : await cache().get(stream);
+  const cache_hit = !!cached;
   let state2 = cached?.state ?? (me.init ? me.init() : {});
   let patches = cached?.patches ?? 0;
   let snaps = cached?.snaps ?? 0;
+  let version = cached?.version ?? -1;
+  let replayed = 0;
   let event;
   await store().query(
     (e) => {
       event = e;
+      version = e.version;
       if (e.name === SNAP_EVENT) {
         state2 = e.data;
         snaps++;
         patches = 0;
+        replayed++;
       } else if (me.patch[e.name]) {
         state2 = (0, import_act_patch.patch)(state2, me.patch[e.name](event, state2));
         patches++;
+        replayed++;
       } else if (e.name !== TOMBSTONE_EVENT) {
         log().warn(
           `Skipping unknown event "${String(e.name)}" on stream "${stream}" (id=${e.id}) \u2014 no reducer in state "${me.name}"`
         );
       }
-      callback && callback({ event, state: state2, patches, snaps });
+      callback && callback({
+        event,
+        state: state2,
+        version,
+        patches,
+        snaps,
+        cache_hit,
+        replayed
+      });
     },
     {
       stream,
@@ -1412,7 +1775,16 @@ async function load(me, stream, callback, asOf) {
       ...cached ? { after: cached.event_id } : { with_snaps: true, ...asOf }
     }
   );
-  return { event, state: state2, patches, snaps };
+  if (replayed > 0 && !timeTravel && event) {
+    await cache().set(stream, {
+      state: state2,
+      version,
+      event_id: event.id,
+      patches,
+      snaps
+    });
+  }
+  return { event, state: state2, version, patches, snaps, cache_hit, replayed };
 }
 async function action(me, action2, target, payload, reactingTo, skipValidation = false) {
   const { stream, expectedVersion, actor } = target;
@@ -1484,7 +1856,16 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     const p = me.patch[event.name](event, state2);
     state2 = (0, import_act_patch.patch)(state2, p);
     patches++;
-    return { event, state: state2, patches, snaps: snapshot.snaps, patch: p };
+    return {
+      event,
+      state: state2,
+      version: event.version,
+      patches,
+      snaps: snapshot.snaps,
+      patch: p,
+      cache_hit: snapshot.cache_hit,
+      replayed: snapshot.replayed
+    };
   });
   const last = snapshots.at(-1);
   const snapped = me.snap && me.snap(last);
@@ -1506,12 +1887,35 @@ var C_ORANGE = "\x1B[38;5;208m";
 var C_GREEN = "\x1B[38;5;42m";
 var C_MAGENTA = "\x1B[38;5;165m";
 var C_DRAIN = "\x1B[38;5;244m";
+var C_HIT = "\x1B[38;5;82m";
+var C_MISS = "\x1B[38;5;220m";
 var C_RESET = "\x1B[0m";
 var es_caption = (caption, color, body) => PRETTY ? `${color}${body}${C_RESET}` : `${caption}: ${body}`;
 var drain_caption = (caption) => {
   const tag = `>> ${caption}`;
   return PRETTY ? `${C_DRAIN}${tag}${C_RESET}` : tag;
 };
+var cache_marker = (hit) => {
+  const word = hit ? "hit" : "miss";
+  if (!PRETTY) return word;
+  return `${hit ? C_HIT : C_MISS}${word}${C_RESET}${C_GREEN}`;
+};
+var stats_marker = (version, replayed, snaps, patches) => {
+  const text = `v=${version} replayed=${replayed} snaps=${snaps} patches=${patches}`;
+  if (!PRETTY) return text;
+  return `${C_DRAIN}${text}${C_RESET}${C_GREEN}`;
+};
+var as_of_marker = (asOf) => {
+  if (!asOf) return "";
+  const parts = [];
+  if (asOf.before !== void 0) parts.push(`before=${asOf.before}`);
+  if (asOf.created_before !== void 0)
+    parts.push(`created_before=${asOf.created_before.toISOString()}`);
+  if (asOf.created_after !== void 0)
+    parts.push(`created_after=${asOf.created_after.toISOString()}`);
+  if (asOf.limit !== void 0) parts.push(`limit=${asOf.limit}`);
+  return parts.length ? ` (as-of ${parts.join(" ")})` : " (as-of)";
+};
 var traced = (inner, exit, entry) => (async (...args) => {
   entry?.(...args);
   const result = await inner(...args);
@@ -1537,9 +1941,19 @@ function buildEs(logger) {
         )
       );
     }),
-    load: traced(load, void 0, (_me, stream, _cb, asOf) => {
+    load: traced(load, (result, _me, stream, _cb, asOf) => {
+      const stats = stats_marker(
+        result.version,
+        result.replayed,
+        result.snaps,
+        result.patches
+      );
       logger.trace(
-        es_caption("load", C_GREEN, `${stream}${asOf ? " (as-of)" : ""}`)
+        es_caption(
+          "load",
+          C_GREEN,
+          `${stream}${as_of_marker(asOf)} ${cache_marker(result.cache_hit)} ${stats}`
+        )
       );
     }),
     action: traced(
@@ -1633,37 +2047,57 @@ function buildDrain(logger) {
 
 // src/act.ts
 var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
+var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
 var Act = class {
   constructor(registry, _states = /* @__PURE__ */ new Map(), batchHandlers = /* @__PURE__ */ new Map(), options = {}) {
     this.registry = registry;
     this._states = _states;
     this._batch_handlers = batchHandlers;
-    this._subscribed_streams = new LruSet(
-      options.maxSubscribedStreams ?? DEFAULT_MAX_SUBSCRIBED_STREAMS
-    );
     this._es = buildEs(this._logger);
     this._cd = buildDrain(this._logger);
-    const statics = /* @__PURE__ */ new Map();
-    for (const [name, register] of Object.entries(this.registry.events)) {
-      if (register.reactions.size > 0) {
-        this._reactive_events.add(name);
-      }
-      for (const reaction of register.reactions.values()) {
-        if (typeof reaction.resolver === "function") {
-          this._has_dynamic_resolvers = true;
-        } else {
-          const { target, source } = reaction.resolver;
-          const key = `${target}|${source ?? ""}`;
-          if (!statics.has(key)) statics.set(key, { stream: target, source });
-        }
-      }
-    }
-    this._static_targets = [...statics.values()];
-    for (const merged of this._states.values()) {
-      for (const eventName of Object.keys(merged.events)) {
-        this._event_to_state.set(eventName, merged);
+    this._handle = buildHandle({
+      logger: this._logger,
+      boundDo: this._bound_do,
+      boundLoad: this._bound_load,
+      boundQuery: this._bound_query,
+      boundQueryArray: this._bound_query_array
+    });
+    this._handle_batch = buildHandleBatch(this._logger);
+    const { staticTargets, hasDynamicResolvers, reactiveEvents, eventToState } = classifyRegistry(this.registry, this._states);
+    this._reactive_events = reactiveEvents;
+    this._event_to_state = eventToState;
+    this._drain = new DrainController({
+      logger: this._logger,
+      ops: this._cd,
+      registry: this.registry,
+      batchHandlers: this._batch_handlers,
+      handle: this._handle,
+      handleBatch: this._handle_batch,
+      onAcked: (acked) => this.emit("acked", acked),
+      onBlocked: (blocked) => this.emit("blocked", blocked)
+    });
+    this._correlate = new CorrelateCycle(
+      this.registry,
+      staticTargets,
+      hasDynamicResolvers,
+      this._cd,
+      options.maxSubscribedStreams ?? DEFAULT_MAX_SUBSCRIBED_STREAMS,
+      // Cold start: assume drain is needed (historical events may need processing)
+      () => {
+        if (this._reactive_events.size > 0) this._drain.arm();
       }
-    }
+    );
+    this._settle = new SettleLoop(
+      {
+        logger: this._logger,
+        init: () => this._correlate.init(),
+        checkpoint: () => this._correlate.checkpoint,
+        correlate: (q) => this.correlate(q),
+        drain: (o) => this.drain(o),
+        onSettled: (drain) => this.emit("settled", drain)
+      },
+      options.settleDebounceMs ?? DEFAULT_SETTLE_DEBOUNCE_MS
+    );
     dispose(() => {
       this._emitter.removeAllListeners();
       this.stop_correlations();
@@ -1672,30 +2106,14 @@ var Act = class {
     });
   }
   _emitter = new import_events.default();
-  _drain_locked = false;
-  _drain_lag2lead_ratio = 0.5;
-  _correlation_timer = void 0;
-  _settle_timer = void 0;
-  _settling = false;
-  _correlation_checkpoint = -1;
-  /**
-   * Streams already subscribed via store.subscribe() — both the static
-   * targets registered at init and dynamic targets discovered by
-   * correlate(). correlate() consults this set to avoid re-subscribing
-   * known streams.
-   *
-   * Bounded LRU so apps that mint millions of dynamic targets (one per
-   * aggregate) don't grow this unbounded. Eviction costs at most one
-   * redundant store.subscribe() call per evicted-but-still-active stream
-   * (subscribe is idempotent). Cap configurable via {@link ActOptions}.
-   */
-  _subscribed_streams;
-  _has_dynamic_resolvers = false;
-  _correlation_initialized = false;
   /** Event names with at least one registered reaction (computed at build time) */
-  _reactive_events = /* @__PURE__ */ new Set();
-  /** Set in do() when a committed event has reactions — cleared by drain() */
-  _needs_drain = false;
+  _reactive_events;
+  /** Drain pipeline driver: armed flag, concurrency lock, adaptive ratio. */
+  _drain;
+  /** Correlation state machine: lazy init, dynamic-resolver scan, periodic worker. */
+  _correlate;
+  /** Debounced correlate→drain catch-up loop. */
+  _settle;
   /**
    * Emit a lifecycle event. The payload type is inferred from the event name
    * via {@link ActLifecycleEvents}.
@@ -1724,8 +2142,6 @@ var Act = class {
    * @param registry The registry of state, event, and action schemas
    * @param states Map of state names to their (potentially merged) state definitions
    */
-  /** Static resolver targets collected at build time */
-  _static_targets;
   /** Batch handlers for static-target projections (target → handler) */
   _batch_handlers;
   /** Event-sourcing handlers, optionally wrapped with trace decorators */
@@ -1738,7 +2154,7 @@ var Act = class {
    * this lookup is unambiguous. Used by `close()` to pick the right reducer
    * set when seeding a `restart` snapshot in multi-state apps.
    */
-  _event_to_state = /* @__PURE__ */ new Map();
+  _event_to_state;
   /** Logger resolved at construction time (after user port configuration) */
   _logger = log();
   /** Pre-bound IAct methods reused across drain cycles. Only `do` varies per
@@ -1747,9 +2163,9 @@ var Act = class {
   _bound_load = this.load.bind(this);
   _bound_query = this.query.bind(this);
   _bound_query_array = this.query_array.bind(this);
-  /** Pre-bound dispatchers handed to runDrainCycle each cycle. */
-  _bound_handle = this.handle.bind(this);
-  _bound_handle_batch = this.handleBatch.bind(this);
+  /** Reaction dispatchers built once and handed to runDrainCycle each cycle. */
+  _handle;
+  _handle_batch;
   /**
    * Executes an action on a state instance, committing resulting events.
    *
@@ -1840,10 +2256,12 @@ var Act = class {
       reactingTo,
       skipValidation
     );
-    for (const snap2 of snapshots) {
-      if (snap2.event?.name && this._reactive_events.has(snap2.event.name)) {
-        this._needs_drain = true;
-        break;
+    if (this._reactive_events.size > 0) {
+      for (const snap2 of snapshots) {
+        if (snap2.event?.name && this._reactive_events.has(snap2.event.name)) {
+          this._drain.arm();
+          break;
+        }
       }
     }
     this.emit("committed", snapshots);
@@ -1951,109 +2369,6 @@ var Act = class {
     await store().query((e) => events.push(e), query);
     return events;
   }
-  /**
-   * Shared finalization for the two reaction-runner shapes (per-event
-   * `handle` and bulk `handleBatch`). Centralizes the error log, retry-vs-
-   * block decision, and the "error reported only when nothing was handled"
-   * rule that's true in both shapes (in batch mode, `handled` is always 0
-   * on failure, so the rule degenerates to "always reported").
-   */
-  _finalize(lease, handled, at, error, options) {
-    if (!error) return { lease, handled, at };
-    this._logger.error(error);
-    const block2 = lease.retry >= options.maxRetries && options.blockOnError;
-    if (block2)
-      this._logger.error(
-        `Blocking ${lease.stream} after ${lease.retry} retries.`
-      );
-    return {
-      lease,
-      handled,
-      at,
-      error: handled === 0 ? error.message : void 0,
-      block: block2
-    };
-  }
-  /**
-   * Handles leased reactions one event at a time.
-   *
-   * Called by the main `drain` loop after fetching new events. Each handler
-   * receives a scoped `IAct` proxy that auto-injects the triggering event
-   * as `reactingTo` when `do()` is called without it, maintaining
-   * correlation chains by default (#587). Handlers can still pass an
-   * explicit `reactingTo` to override.
-   *
-   * @internal
-   */
-  async handle(lease, payloads) {
-    if (payloads.length === 0) return { lease, handled: 0, at: lease.at };
-    const stream = lease.stream;
-    let at = payloads.at(0).event.id;
-    let handled = 0;
-    if (lease.retry > 0)
-      this._logger.warn(`Retrying ${stream}@${at} (${lease.retry}).`);
-    const doAction = this._bound_do;
-    const scopedApp = {
-      do: doAction,
-      load: this._bound_load,
-      query: this._bound_query,
-      query_array: this._bound_query_array
-    };
-    for (const payload of payloads) {
-      const { event, handler } = payload;
-      scopedApp.do = (action2, target, payload2, reactingTo, skipValidation) => doAction(
-        action2,
-        target,
-        payload2,
-        reactingTo ?? event,
-        skipValidation
-      );
-      try {
-        await handler(event, stream, scopedApp);
-        at = event.id;
-        handled++;
-      } catch (error) {
-        return this._finalize(
-          lease,
-          handled,
-          at,
-          error,
-          payload.options
-        );
-      }
-    }
-    return this._finalize(lease, handled, at, void 0, payloads[0].options);
-  }
-  /**
-   * Handles a batch of events for a projection with a batch handler.
-   *
-   * Called by `drain()` when a leased stream is a static-target projection
-   * with a registered batch handler. All events are passed to the handler
-   * in a single call, enabling bulk DB operations.
-   *
-   * @internal
-   */
-  async handleBatch(lease, payloads, batchHandler) {
-    const stream = lease.stream;
-    const events = payloads.map((p) => p.event);
-    const options = payloads[0].options;
-    if (lease.retry > 0)
-      this._logger.warn(
-        `Retrying batch ${stream}@${events[0].id} (${lease.retry}).`
-      );
-    try {
-      await batchHandler(events, stream);
-      return this._finalize(
-        lease,
-        events.length,
-        events.at(-1).id,
-        void 0,
-        options
-      );
-    } catch (error) {
-      return this._finalize(lease, 0, lease.at, error, options);
-    }
-  }
   /**
    * Processes pending reactions by draining uncommitted events from the event store.
    *
@@ -2093,54 +2408,8 @@ var Act = class {
    * @see {@link correlate} for dynamic stream discovery
    * @see {@link start_correlations} for automatic correlation
    */
-  async drain({
-    streamLimit = 10,
-    eventLimit = 10,
-    leaseMillis = 1e4
-  } = {}) {
-    if (!this._needs_drain) {
-      return { fetched: [], leased: [], acked: [], blocked: [] };
-    }
-    if (this._drain_locked) {
-      return { fetched: [], leased: [], acked: [], blocked: [] };
-    }
-    try {
-      this._drain_locked = true;
-      const lagging = Math.ceil(streamLimit * this._drain_lag2lead_ratio);
-      const leading = streamLimit - lagging;
-      const cycle = await runDrainCycle(
-        this._cd,
-        this.registry,
-        this._batch_handlers,
-        this._bound_handle,
-        this._bound_handle_batch,
-        lagging,
-        leading,
-        eventLimit,
-        leaseMillis
-      );
-      if (!cycle) {
-        this._needs_drain = false;
-        return { fetched: [], leased: [], acked: [], blocked: [] };
-      }
-      const { leased, fetched, handled, acked, blocked } = cycle;
-      this._drain_lag2lead_ratio = computeLagLeadRatio(
-        handled,
-        lagging,
-        leading
-      );
-      if (acked.length) this.emit("acked", acked);
-      if (blocked.length) this.emit("blocked", blocked);
-      const hasErrors = handled.some(({ error }) => error);
-      if (!acked.length && !blocked.length && !hasErrors)
-        this._needs_drain = false;
-      return { fetched, leased, acked, blocked };
-    } catch (error) {
-      this._logger.error(error);
-      return { fetched: [], leased: [], acked: [], blocked: [] };
-    } finally {
-      this._drain_locked = false;
-    }
+  async drain(options = {}) {
+    return this._drain.drain(options);
   }
   /**
    * Discovers and registers new streams dynamically based on reaction resolvers.
@@ -2187,71 +2456,8 @@ var Act = class {
    * @see {@link start_correlations} for automatic periodic correlation
    * @see {@link stop_correlations} to stop automatic correlation
    */
-  /**
-   * Initialize correlation state on first call.
-   * - Reads max(at) from store as cold-start checkpoint
-   * - Subscribes static resolver targets (idempotent upsert)
-   * - Populates the subscribed statics set
-   * @internal
-   */
-  async _init_correlation() {
-    if (this._correlation_initialized) return;
-    this._correlation_initialized = true;
-    const { watermark } = await store().subscribe(this._static_targets);
-    this._correlation_checkpoint = watermark;
-    if (this._reactive_events.size > 0) this._needs_drain = true;
-    for (const { stream } of this._static_targets) {
-      this._subscribed_streams.add(stream);
-    }
-  }
   async correlate(query = { after: -1, limit: 10 }) {
-    await this._init_correlation();
-    if (!this._has_dynamic_resolvers)
-      return { subscribed: 0, last_id: this._correlation_checkpoint };
-    const after = Math.max(this._correlation_checkpoint, query.after || -1);
-    const correlated = /* @__PURE__ */ new Map();
-    let last_id = after;
-    await store().query(
-      (event) => {
-        last_id = event.id;
-        const register = this.registry.events[event.name];
-        if (register) {
-          for (const reaction of register.reactions.values()) {
-            if (typeof reaction.resolver !== "function") continue;
-            const resolved = reaction.resolver(event);
-            if (resolved && !this._subscribed_streams.has(resolved.target)) {
-              const entry = correlated.get(resolved.target) || {
-                source: resolved.source,
-                payloads: []
-              };
-              entry.payloads.push({
-                ...reaction,
-                source: resolved.source,
-                event
-              });
-              correlated.set(resolved.target, entry);
-            }
-          }
-        }
-      },
-      { ...query, after }
-    );
-    if (correlated.size) {
-      const streams = [...correlated.entries()].map(([stream, { source }]) => ({
-        stream,
-        source
-      }));
-      const { subscribed } = await this._cd.subscribe(streams);
-      this._correlation_checkpoint = last_id;
-      if (subscribed) {
-        for (const { stream } of streams) {
-          this._subscribed_streams.add(stream);
-        }
-      }
-      return { subscribed, last_id };
-    }
-    this._correlation_checkpoint = last_id;
-    return { subscribed: 0, last_id };
+    return this._correlate.correlate(query);
   }
   /**
    * Starts automatic periodic correlation worker for discovering new streams.
@@ -2309,15 +2515,7 @@ var Act = class {
    * @see {@link stop_correlations} to stop the worker
    */
   start_correlations(query = {}, frequency = 1e4, callback) {
-    if (this._correlation_timer) return false;
-    const limit = query.limit || 100;
-    this._correlation_timer = setInterval(
-      () => this.correlate({ ...query, after: this._correlation_checkpoint, limit }).then((result) => {
-        if (callback && result.subscribed) callback(result.subscribed);
-      }).catch(console.error),
-      frequency
-    );
-    return true;
+    return this._correlate.startPolling(query, frequency, callback);
   }
   /**
    * Stops the automatic correlation worker.
@@ -2337,10 +2535,7 @@ var Act = class {
    * @see {@link start_correlations}
    */
   stop_correlations() {
-    if (this._correlation_timer) {
-      clearInterval(this._correlation_timer);
-      this._correlation_timer = void 0;
-    }
+    this._correlate.stopPolling();
   }
   /**
    * Cancels any pending or active settle cycle.
@@ -2348,10 +2543,7 @@ var Act = class {
    * @see {@link settle}
    */
   stop_settling() {
-    if (this._settle_timer) {
-      clearTimeout(this._settle_timer);
-      this._settle_timer = void 0;
-    }
+    this._settle.stop();
   }
   /**
    * Reset reaction stream watermarks and request a drain on the next
@@ -2388,9 +2580,7 @@ var Act = class {
    */
   async reset(streams) {
     const count = await store().reset(streams);
-    if (count > 0 && this._reactive_events.size > 0) {
-      this._needs_drain = true;
-    }
+    if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
     return count;
   }
   /**
@@ -2473,34 +2663,7 @@ var Act = class {
    * @see {@link correlate} for manual correlation
    */
   settle(options = {}) {
-    const {
-      debounceMs = 10,
-      correlate: correlateQuery = { after: -1, limit: 100 },
-      maxPasses = Infinity,
-      ...drainOptions
-    } = options;
-    if (this._settle_timer) clearTimeout(this._settle_timer);
-    this._settle_timer = setTimeout(() => {
-      this._settle_timer = void 0;
-      if (this._settling) return;
-      this._settling = true;
-      (async () => {
-        await this._init_correlation();
-        let lastDrain;
-        for (let i = 0; i < maxPasses; i++) {
-          const { subscribed } = await this.correlate({
-            ...correlateQuery,
-            after: this._correlation_checkpoint
-          });
-          lastDrain = await this.drain(drainOptions);
-          const made_progress = subscribed > 0 || lastDrain.acked.length > 0 || lastDrain.blocked.length > 0;
-          if (!made_progress) break;
-        }
-        if (lastDrain) this.emit("settled", lastDrain);
-      })().catch((err) => this._logger.error(err)).finally(() => {
-        this._settling = false;
-      });
-    }, debounceMs);
+    this._settle.schedule(options);
   }
 };
 
@@ -2783,6 +2946,7 @@ function action_builder(state2) {
   ConcurrencyError,
   ConsoleLogger,
   DEFAULT_MAX_SUBSCRIBED_STREAMS,
+  DEFAULT_SETTLE_DEBOUNCE_MS,
   Environments,
   Errors,
   EventMetaSchema,