@rotorsoft/act 0.32.3 → 0.32.5

package/dist/index.js

@@ -117,26 +117,75 @@ var ConsoleLogger = class _ConsoleLogger {
   }
 };
 
+// src/internal/lru-map.ts
+var LruMap = class {
+  constructor(_maxSize) {
+    this._maxSize = _maxSize;
+  }
+  _entries = /* @__PURE__ */ new Map();
+  get(key) {
+    const v = this._entries.get(key);
+    if (v === void 0) return void 0;
+    this._entries.delete(key);
+    this._entries.set(key, v);
+    return v;
+  }
+  has(key) {
+    return this._entries.has(key);
+  }
+  set(key, value) {
+    this._entries.delete(key);
+    if (this._entries.size >= this._maxSize) {
+      const oldest = this._entries.keys().next().value;
+      if (oldest !== void 0) this._entries.delete(oldest);
+    }
+    this._entries.set(key, value);
+  }
+  delete(key) {
+    return this._entries.delete(key);
+  }
+  clear() {
+    this._entries.clear();
+  }
+  get size() {
+    return this._entries.size;
+  }
+};
+var LruSet = class {
+  _map;
+  constructor(maxSize) {
+    this._map = new LruMap(maxSize);
+  }
+  has(value) {
+    return this._map.has(value);
+  }
+  add(value) {
+    this._map.set(value, true);
+  }
+  delete(value) {
+    return this._map.delete(value);
+  }
+  clear() {
+    this._map.clear();
+  }
+  get size() {
+    return this._map.size;
+  }
+};
+
 // src/adapters/InMemoryCache.ts
 var InMemoryCache = class {
-  _entries = /* @__PURE__ */ new Map();
-  _maxSize;
+  // CacheEntry<any> lets `get<TState>` and `set<TState>` flow without casts:
+  // any is bidirectionally compatible with the per-call TState binding, while
+  // the public Cache interface still presents a typed surface to callers.
+  _entries;
   constructor(options) {
-    this._maxSize = options?.maxSize ?? 1e3;
+    this._entries = new LruMap(options?.maxSize ?? 1e3);
   }
   async get(stream) {
-    const entry = this._entries.get(stream);
-    if (!entry) return void 0;
-    this._entries.delete(stream);
-    this._entries.set(stream, entry);
-    return entry;
+    return this._entries.get(stream);
   }
   async set(stream, entry) {
-    this._entries.delete(stream);
-    if (this._entries.size >= this._maxSize) {
-      const first = this._entries.keys().next().value;
-      this._entries.delete(first);
-    }
     this._entries.set(stream, entry);
   }
   async invalidate(stream) {
@@ -179,12 +228,19 @@ var BaseSchema = PackageSchema.extend({
 });
 var { NODE_ENV, LOG_LEVEL, LOG_SINGLE_LINE, SLEEP_MS } = process.env;
 var env = NODE_ENV || "development";
-var logLevel = LOG_LEVEL || (NODE_ENV === "test" ? "error" : NODE_ENV === "production" ? "info" : "trace");
+var logLevel = LOG_LEVEL || (NODE_ENV === "test" ? "fatal" : NODE_ENV === "production" ? "info" : "trace");
 var logSingleLine = (LOG_SINGLE_LINE || "true") === "true";
 var sleepMs = parseInt(NODE_ENV === "test" ? "0" : SLEEP_MS ?? "100", 10);
 var pkg = getPackage();
+var _validated;
 var config = () => {
-  return extend({ ...pkg, env, logLevel, logSingleLine, sleepMs }, BaseSchema);
+  if (!_validated) {
+    _validated = extend(
+      { ...pkg, env, logLevel, logSingleLine, sleepMs },
+      BaseSchema
+    );
+  }
+  return _validated;
 };
 
 // src/utils.ts
@@ -607,7 +663,7 @@ function port(injector) {
     if (!adapters.has(injector.name)) {
       const injected = injector(adapter);
       adapters.set(injector.name, injected);
-      console.log(`[act] + ${injector.name}:${injected.constructor.name}`);
+      log().info(`[act] + ${injector.name}:${injected.constructor.name}`);
     }
     return adapters.get(injector.name);
   };
@@ -633,7 +689,7 @@ async function disposeAndExit(code = "EXIT") {
   }
   for (const adapter of [...adapters.values()].reverse()) {
     await adapter.dispose();
-    console.log(`[act] - ${adapter.constructor.name}`);
+    log().info(`[act] - ${adapter.constructor.name}`);
   }
   adapters.clear();
   config().env !== "test" && process.exit(code === "ERROR" ? 1 : 0);
@@ -664,9 +720,233 @@ process.once("unhandledRejection", async (arg) => {
 });
 
 // src/act.ts
-import { randomUUID as randomUUID2 } from "crypto";
 import EventEmitter from "events";
 
+// src/internal/close-cycle.ts
+import { randomUUID } from "crypto";
+async function runCloseCycle(targets, deps) {
+  if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
+  const targetMap = new Map(targets.map((t) => [t.stream, t]));
+  const streams = [...targetMap.keys()];
+  const skipped = [];
+  const streamInfo = await scanStreamHeads(streams);
+  const safe = await partitionBySafety(
+    streamInfo,
+    deps.reactiveEventsSize,
+    skipped
+  );
+  if (!safe.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
+  const correlation = randomUUID();
+  const { guarded, guardEvents } = await guardWithTombstones(
+    safe,
+    streamInfo,
+    correlation,
+    deps.tombstone,
+    skipped
+  );
+  if (!guarded.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
+  const seedStates = await loadRestartSeeds(
+    guarded,
+    targetMap,
+    streamInfo,
+    deps.eventToState,
+    deps.load,
+    deps.logger
+  );
+  await runArchiveCallbacks(guarded, targetMap);
+  const truncated = await truncateAndWarmCache(
+    guarded,
+    seedStates,
+    guardEvents,
+    correlation
+  );
+  return { truncated, skipped };
+}
+async function scanStreamHeads(streams) {
+  const out = /* @__PURE__ */ new Map();
+  await Promise.all(
+    streams.map(async (s) => {
+      let maxId = -1;
+      let version = -1;
+      let lastEventName;
+      await store().query(
+        (e) => {
+          if (e.name === TOMBSTONE_EVENT) return;
+          if (maxId === -1) {
+            maxId = e.id;
+            version = e.version;
+          }
+          if (e.name !== SNAP_EVENT && lastEventName === void 0) {
+            lastEventName = e.name;
+          }
+        },
+        // limit: 2 covers the typical snapshot-at-head case (snapshot is
+        // always preceded by the domain event it captured). Streams with
+        // unusual layouts fall back to no-seed via the lookup miss path.
+        { stream: s, stream_exact: true, backward: true, limit: 2 }
+      );
+      if (maxId >= 0) out.set(s, { maxId, version, lastEventName });
+    })
+  );
+  return out;
+}
+async function partitionBySafety(streamInfo, reactiveEventsSize, skipped) {
+  if (reactiveEventsSize === 0) return [...streamInfo.keys()];
+  const pendingSet = /* @__PURE__ */ new Set();
+  await store().query_streams((position) => {
+    const sourceRe = position.source ? RegExp(position.source) : void 0;
+    for (const [stream, info] of streamInfo) {
+      if ((!sourceRe || sourceRe.test(stream)) && position.at < info.maxId) {
+        pendingSet.add(stream);
+      }
+    }
+  });
+  const safe = [];
+  for (const [stream] of streamInfo) {
+    if (pendingSet.has(stream)) skipped.push(stream);
+    else safe.push(stream);
+  }
+  return safe;
+}
+async function guardWithTombstones(safe, streamInfo, correlation, tombstone2, skipped) {
+  const guarded = [];
+  const guardEvents = /* @__PURE__ */ new Map();
+  await Promise.all(
+    safe.map(async (stream) => {
+      const info = streamInfo.get(stream);
+      const committed = await tombstone2(stream, info.version, correlation);
+      if (committed) {
+        guarded.push(stream);
+        guardEvents.set(stream, { id: committed.id, stream });
+      } else {
+        skipped.push(stream);
+      }
+    })
+  );
+  return { guarded, guardEvents };
+}
+async function loadRestartSeeds(guarded, targetMap, streamInfo, eventToState, load2, logger) {
+  const seedStates = /* @__PURE__ */ new Map();
+  await Promise.all(
+    guarded.filter((s) => targetMap.get(s)?.restart).map(async (stream) => {
+      const lastEventName = streamInfo.get(stream)?.lastEventName;
+      const ownerState = lastEventName ? eventToState.get(lastEventName) : void 0;
+      if (!ownerState) {
+        logger.error(
+          `Cannot seed restart for "${stream}": no registered state owns event "${lastEventName ?? "<none>"}". Stream will be tombstoned instead.`
+        );
+        return;
+      }
+      const snap2 = await load2(ownerState, stream);
+      seedStates.set(stream, snap2.state);
+    })
+  );
+  return seedStates;
+}
+async function runArchiveCallbacks(guarded, targetMap) {
+  for (const stream of guarded) {
+    const archiveFn = targetMap.get(stream)?.archive;
+    if (archiveFn) await archiveFn();
+  }
+}
+async function truncateAndWarmCache(guarded, seedStates, guardEvents, correlation) {
+  const truncTargets = guarded.map((stream) => {
+    const snapshot = seedStates.get(stream);
+    const guard = guardEvents.get(stream);
+    return {
+      stream,
+      snapshot,
+      meta: {
+        correlation,
+        causation: {
+          event: { id: guard.id, name: TOMBSTONE_EVENT, stream: guard.stream }
+        }
+      }
+    };
+  });
+  const truncated = await store().truncate(truncTargets);
+  await Promise.all(
+    guarded.map(async (stream) => {
+      const entry = truncated.get(stream);
+      const state2 = seedStates.get(stream);
+      if (state2 && entry) {
+        await cache().set(stream, {
+          state: state2,
+          version: entry.committed.version,
+          event_id: entry.committed.id,
+          patches: 0,
+          snaps: 1
+        });
+      } else {
+        await cache().invalidate(stream);
+      }
+    })
+  );
+  return truncated;
+}
+
+// src/internal/drain-cycle.ts
+import { randomUUID as randomUUID2 } from "crypto";
+async function runDrainCycle(ops, registry, batchHandlers, handle, handleBatch, lagging, leading, eventLimit, leaseMillis) {
+  const leased = await ops.claim(lagging, leading, randomUUID2(), leaseMillis);
+  if (!leased.length) return void 0;
+  const fetched = await ops.fetch(leased, eventLimit);
+  const fetchMap = /* @__PURE__ */ new Map();
+  const fetch_window_at = fetched.reduce(
+    (max, { at, events }) => Math.max(max, events.at(-1)?.id || at),
+    0
+  );
+  for (const f of fetched) {
+    const { stream, events } = f;
+    const payloads = events.flatMap((event) => {
+      const register = registry.events[event.name];
+      if (!register) return [];
+      return [...register.reactions.values()].filter((reaction) => {
+        const resolved = typeof reaction.resolver === "function" ? reaction.resolver(event) : reaction.resolver;
+        return resolved && resolved.target === stream;
+      }).map((reaction) => ({ ...reaction, event }));
+    });
+    fetchMap.set(stream, { fetch: f, payloads });
+  }
+  const handled = await Promise.all(
+    leased.map((lease) => {
+      const entry = fetchMap.get(lease.stream);
+      const at = entry?.fetch.events.at(-1)?.id || fetch_window_at;
+      const payloads = entry?.payloads ?? [];
+      const batchHandler = batchHandlers.get(lease.stream);
+      if (batchHandler && payloads.length > 0) {
+        return handleBatch({ ...lease, at }, payloads, batchHandler);
+      }
+      return handle({ ...lease, at }, payloads);
+    })
+  );
+  const acked = await ops.ack(
+    handled.filter(({ error }) => !error).map(({ at, lease }) => ({ ...lease, at }))
+  );
+  const blocked = await ops.block(
+    handled.filter(({ block: block2 }) => block2).map(({ lease, error }) => ({ ...lease, error }))
+  );
+  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;
+  }
+  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/merge.ts
 import { ZodObject } from "zod";
 function baseTypeName(zodType) {
@@ -774,6 +1054,15 @@ function mergePatches(existing, incoming, stateName) {
   }
   return merged;
 }
+function mergeEventRegister(target, source) {
+  for (const [eventName, sourceReg] of Object.entries(source)) {
+    const targetReg = target[eventName];
+    if (!targetReg) continue;
+    for (const [name, reaction] of sourceReg.reactions) {
+      targetReg.reactions.set(name, reaction);
+    }
+  }
+}
 function mergeProjection(proj, events) {
   for (const eventName of Object.keys(proj.events)) {
     const projRegister = proj.events[eventName];
@@ -818,7 +1107,7 @@ var subscribe = (streams) => store().subscribe(streams);
 
 // src/internal/event-sourcing.ts
 import { patch } from "@rotorsoft/act-patch";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 async function snap(snapshot) {
   try {
     const { id, stream, name, meta, version } = snapshot.event;
@@ -836,6 +1125,20 @@ async function snap(snapshot) {
     log().error(error);
   }
 }
+async function tombstone(stream, expectedVersion, correlation) {
+  try {
+    const [committed] = await store().commit(
+      stream,
+      [{ name: TOMBSTONE_EVENT, data: {} }],
+      { correlation, causation: {} },
+      expectedVersion
+    );
+    return committed;
+  } catch (error) {
+    if (error instanceof ConcurrencyError) return void 0;
+    throw error;
+  }
+}
 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);
@@ -900,7 +1203,7 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     data: skipValidation ? data : validate(name, data, me.events[name])
   }));
   const meta = {
-    correlation: reactingTo?.meta.correlation || randomUUID(),
+    correlation: reactingTo?.meta.correlation || randomUUID3(),
     causation: {
       action: {
         name: action2,
@@ -951,6 +1254,18 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
 }
 
 // src/internal/tracing.ts
+var PRETTY = config().env !== "production";
+var C_BLUE = "\x1B[38;5;39m";
+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_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 traced = (inner, exit, entry) => (async (...args) => {
   entry?.(...args);
   const result = await inner(...args);
@@ -959,16 +1274,27 @@ var traced = (inner, exit, entry) => (async (...args) => {
 });
 function buildEs(logger) {
   if (logger.level !== "trace") {
-    return { snap, load, action };
+    return {
+      snap,
+      load,
+      action,
+      tombstone
+    };
   }
   return {
     snap: traced(snap, void 0, (snapshot) => {
       logger.trace(
-        `\u{1F7E0} snap ${snapshot.event.stream}@${snapshot.event.version}`
+        es_caption(
+          "snap",
+          C_MAGENTA,
+          `${snapshot.event.stream}@${snapshot.event.version}`
+        )
       );
     }),
     load: traced(load, void 0, (_me, stream, _cb, asOf) => {
-      logger.trace(`\u{1F7E2} load ${stream}${asOf ? " (as-of)" : ""}`);
+      logger.trace(
+        es_caption("load", C_GREEN, `${stream}${asOf ? " (as-of)" : ""}`)
+      );
     }),
     action: traced(
       action,
@@ -977,14 +1303,27 @@ function buildEs(logger) {
         if (committed.length) {
           logger.trace(
             committed.map((s) => s.event.data),
-            `\u{1F534} commit ${target.stream}.${committed.map((s) => s.event.name).join(", ")}`
+            es_caption(
+              "committed",
+              C_ORANGE,
+              `${target.stream}.${committed.map((s) => s.event.name).join(", ")}`
+            )
           );
         }
       },
       (_me, action2, target, payload) => {
-        logger.trace(payload, `\u{1F535} ${target.stream}.${action2}`);
+        logger.trace(
+          payload,
+          es_caption("action", C_BLUE, `${target.stream}.${action2}`)
+        );
       }
-    )
+    ),
+    tombstone: traced(tombstone, (committed, stream) => {
+      if (committed)
+        logger.trace(
+          es_caption("tombstoned", C_ORANGE, `${stream}@${committed.version}`)
+        );
+    })
   };
 }
 function buildDrain(logger) {
@@ -1003,7 +1342,7 @@ function buildDrain(logger) {
         const data = Object.fromEntries(
           leased.map(({ stream, at, retry }) => [stream, { at, retry }])
         );
-        logger.trace(data, ">> lease");
+        logger.trace(data, drain_caption("claimed"));
       }
     }),
     fetch: traced(fetch, (fetched) => {
@@ -1016,14 +1355,14 @@ function buildDrain(logger) {
           return [key, value];
         })
       );
-      logger.trace(data, ">> fetch");
+      logger.trace(data, drain_caption("fetched"));
     }),
     ack: traced(ack, (acked) => {
       if (acked.length) {
         const data = Object.fromEntries(
           acked.map(({ stream, at, retry }) => [stream, { at, retry }])
         );
-        logger.trace(data, ">> ack");
+        logger.trace(data, drain_caption("acked"));
       }
     }),
     block: traced(block, (blocked) => {
@@ -1034,27 +1373,31 @@ function buildDrain(logger) {
             { at, retry, error }
           ])
         );
-        logger.trace(data, ">> block");
+        logger.trace(data, drain_caption("blocked"));
       }
     }),
     subscribe: traced(subscribe, (result, streams) => {
       if (result.subscribed) {
         const data = streams.map(({ stream }) => stream).join(" ");
-        logger.trace(`>> correlate ${data}`);
+        logger.trace(`${drain_caption("correlated")} ${data}`);
       }
     })
   };
 }
 
 // src/act.ts
+var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var Act = class {
-  constructor(registry, _states = /* @__PURE__ */ new Map(), batchHandlers = /* @__PURE__ */ new Map()) {
+  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 = [];
+    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);
@@ -1063,14 +1406,13 @@ var Act = class {
         if (typeof reaction.resolver === "function") {
           this._has_dynamic_resolvers = true;
         } else {
-          statics.push({
-            stream: reaction.resolver.target,
-            source: reaction.resolver.source
-          });
+          const { target, source } = reaction.resolver;
+          const key = `${target}|${source ?? ""}`;
+          if (!statics.has(key)) statics.set(key, { stream: target, source });
         }
       }
     }
-    this._static_targets = statics;
+    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);
@@ -1090,20 +1432,42 @@ var Act = class {
   _settle_timer = void 0;
   _settling = false;
   _correlation_checkpoint = -1;
-  _subscribed_statics = /* @__PURE__ */ new Set();
+  /**
+   * 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;
+  /**
+   * Emit a lifecycle event. The payload type is inferred from the event name
+   * via {@link ActLifecycleEvents}.
+   */
   emit(event, args) {
     return this._emitter.emit(event, args);
   }
+  /**
+   * Register a listener for a lifecycle event. The listener receives the
+   * event-specific payload.
+   */
   on(event, listener) {
     this._emitter.on(event, listener);
     return this;
   }
+  /**
+   * Remove a previously registered lifecycle listener.
+   */
   off(event, listener) {
     this._emitter.off(event, listener);
     return this;
@@ -1131,6 +1495,15 @@ var Act = class {
   _event_to_state = /* @__PURE__ */ new Map();
   /** Logger resolved at construction time (after user port configuration) */
   _logger = log();
+  /** Pre-bound IAct methods reused across drain cycles. Only `do` varies per
+   * payload (it captures the triggering event for reactingTo auto-inject). */
+  _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);
+  /** Pre-bound dispatchers handed to runDrainCycle each cycle. */
+  _bound_handle = this.handle.bind(this);
+  _bound_handle_batch = this.handleBatch.bind(this);
   /**
    * Executes an action on a state instance, committing resulting events.
    *
@@ -1333,35 +1706,55 @@ var Act = class {
     return events;
   }
   /**
-   * Handles leased reactions.
-   *
-   * This is called by the main `drain` loop after fetching new events.
-   * It handles reactions, supporting retries, blocking, and error handling.
+   * 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.
    *
-   * 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 this behavior.
+   * 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
-   * @param lease The lease to handle
-   * @param payloads The reactions to handle
-   * @returns The lease with results
    */
   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, handled = 0;
-    lease.retry > 0 && this._logger.warn(`Retrying ${stream}@${at} (${lease.retry}).`);
-    const doAction = this.do.bind(this);
+    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.load.bind(this),
-      query: this.query.bind(this),
-      query_array: this.query_array.bind(this)
+      load: this._bound_load,
+      query: this._bound_query,
+      query_array: this._bound_query_array
     };
     for (const payload of payloads) {
-      const { event, handler, options } = payload;
+      const { event, handler } = payload;
       scopedApp.do = (action2, target, payload2, reactingTo, skipValidation) => doAction(
         action2,
         target,
@@ -1374,22 +1767,16 @@ var Act = class {
         at = event.id;
         handled++;
       } catch (error) {
-        this._logger.error(error);
-        const block2 = lease.retry >= options.maxRetries && options.blockOnError;
-        block2 && this._logger.error(
-          `Blocking ${stream} after ${lease.retry} retries.`
-        );
-        return {
+        return this._finalize(
           lease,
           handled,
           at,
-          // only report error when nothing was handled
-          error: handled === 0 ? error.message : void 0,
-          block: block2
-        };
+          error,
+          payload.options
+        );
       }
     }
-    return { lease, handled, at };
+    return this._finalize(lease, handled, at, void 0, payloads[0].options);
   }
   /**
    * Handles a batch of events for a projection with a batch handler.
@@ -1399,33 +1786,26 @@ var Act = class {
    * in a single call, enabling bulk DB operations.
    *
    * @internal
-   * @param lease The lease to handle
-   * @param payloads The reactions to handle
-   * @param batchHandler The batch handler for this projection
-   * @returns The lease with results
    */
   async handleBatch(lease, payloads, batchHandler) {
     const stream = lease.stream;
     const events = payloads.map((p) => p.event);
-    const at = events.at(-1).id;
-    lease.retry > 0 && this._logger.warn(
-      `Retrying batch ${stream}@${events[0].id} (${lease.retry}).`
-    );
+    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 { lease, handled: events.length, at };
-    } catch (error) {
-      this._logger.error(error);
-      const { options } = payloads[0];
-      const block2 = lease.retry >= options.maxRetries && options.blockOnError;
-      block2 && this._logger.error(`Blocking ${stream} after ${lease.retry} retries.`);
-      return {
+      return this._finalize(
         lease,
-        handled: 0,
-        at: lease.at,
-        error: error.message,
-        block: block2
-      };
+        events.length,
+        events.at(-1).id,
+        void 0,
+        options
+      );
+    } catch (error) {
+      return this._finalize(lease, 0, lease.at, error, options);
     }
   }
   /**
@@ -1475,81 +1855,46 @@ var Act = class {
     if (!this._needs_drain) {
       return { fetched: [], leased: [], acked: [], blocked: [] };
     }
-    if (!this._drain_locked) {
-      try {
-        this._drain_locked = true;
-        const lagging = Math.ceil(streamLimit * this._drain_lag2lead_ratio);
-        const leading = streamLimit - lagging;
-        const leased = await this._cd.claim(
-          lagging,
-          leading,
-          randomUUID2(),
-          leaseMillis
-        );
-        if (!leased.length) {
-          this._needs_drain = false;
-          return { fetched: [], leased: [], acked: [], blocked: [] };
-        }
-        const fetched = await this._cd.fetch(leased, eventLimit);
-        const payloadsMap = /* @__PURE__ */ new Map();
-        const fetch_window_at = fetched.reduce(
-          (max, { at, events }) => Math.max(max, events.at(-1)?.id || at),
-          0
-        );
-        fetched.forEach(({ stream, events }) => {
-          const payloads = events.flatMap((event) => {
-            const register = this.registry.events[event.name];
-            if (!register) return [];
-            return [...register.reactions.values()].filter((reaction) => {
-              const resolved = typeof reaction.resolver === "function" ? reaction.resolver(event) : reaction.resolver;
-              return resolved && resolved.target === stream;
-            }).map((reaction) => ({ ...reaction, event }));
-          });
-          payloadsMap.set(stream, payloads);
-        });
-        const handled = await Promise.all(
-          leased.map((lease) => {
-            const streamFetch = fetched.find((f) => f.stream === lease.stream);
-            const at = streamFetch?.events.at(-1)?.id || fetch_window_at;
-            const payloads = payloadsMap.get(lease.stream);
-            const batchHandler = this._batch_handlers.get(lease.stream);
-            if (batchHandler && payloads.length > 0) {
-              return this.handleBatch({ ...lease, at }, payloads, batchHandler);
-            }
-            return this.handle({ ...lease, at }, payloads);
-          })
-        );
-        const [lagging_handled, leading_handled] = handled.reduce(
-          ([lagging_handled2, leading_handled2], { lease, handled: handled2 }) => [
-            lagging_handled2 + (lease.lagging ? handled2 : 0),
-            leading_handled2 + (lease.lagging ? 0 : handled2)
-          ],
-          [0, 0]
-        );
-        const lagging_avg = lagging > 0 ? lagging_handled / lagging : 0;
-        const leading_avg = leading > 0 ? leading_handled / leading : 0;
-        const total = lagging_avg + leading_avg;
-        this._drain_lag2lead_ratio = total > 0 ? Math.max(0.2, Math.min(0.8, lagging_avg / total)) : 0.5;
-        const acked = await this._cd.ack(
-          handled.filter(({ error }) => !error).map(({ at, lease }) => ({ ...lease, at }))
-        );
-        if (acked.length) this.emit("acked", acked);
-        const blocked = await this._cd.block(
-          handled.filter(({ block: block2 }) => block2).map(({ lease, error }) => ({ ...lease, error }))
-        );
-        if (blocked.length) this.emit("blocked", blocked);
-        const result = { fetched, leased, acked, blocked };
-        const hasErrors = handled.some(({ error }) => error);
-        if (!acked.length && !blocked.length && !hasErrors)
-          this._needs_drain = false;
-        return result;
-      } catch (error) {
-        this._logger.error(error);
-      } finally {
-        this._drain_locked = false;
+    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;
     }
-    return { fetched: [], leased: [], acked: [], blocked: [] };
   }
   /**
    * Discovers and registers new streams dynamically based on reaction resolvers.
@@ -1610,7 +1955,7 @@ var Act = class {
     this._correlation_checkpoint = watermark;
     if (this._reactive_events.size > 0) this._needs_drain = true;
     for (const { stream } of this._static_targets) {
-      this._subscribed_statics.add(stream);
+      this._subscribed_streams.add(stream);
     }
   }
   async correlate(query = { after: -1, limit: 10 }) {
@@ -1628,7 +1973,7 @@ var Act = class {
           for (const reaction of register.reactions.values()) {
             if (typeof reaction.resolver !== "function") continue;
             const resolved = reaction.resolver(event);
-            if (resolved && !this._subscribed_statics.has(resolved.target)) {
+            if (resolved && !this._subscribed_streams.has(resolved.target)) {
               const entry = correlated.get(resolved.target) || {
                 source: resolved.source,
                 payloads: []
@@ -1654,7 +1999,7 @@ var Act = class {
       this._correlation_checkpoint = last_id;
       if (subscribed) {
         for (const { stream } of streams) {
-          this._subscribed_statics.add(stream);
+          this._subscribed_streams.add(stream);
         }
       }
       return { subscribed, last_id };
@@ -1837,143 +2182,14 @@ var Act = class {
    */
   async close(targets) {
     if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
-    const targetMap = new Map(targets.map((t) => [t.stream, t]));
-    const streams = [...targetMap.keys()];
     await this.correlate({ limit: 1e3 });
-    const streamInfo = /* @__PURE__ */ new Map();
-    await Promise.all(
-      streams.map(async (s) => {
-        let maxId = -1;
-        let version = -1;
-        let lastEventName;
-        await store().query(
-          (e) => {
-            if (e.name === TOMBSTONE_EVENT) return;
-            if (maxId === -1) {
-              maxId = e.id;
-              version = e.version;
-            }
-            if (e.name !== SNAP_EVENT && lastEventName === void 0) {
-              lastEventName = e.name;
-            }
-          },
-          // limit: 2 covers the typical snapshot-at-head case (snapshot is
-          // always preceded by the domain event it captured). Streams with
-          // unusual layouts fall back to no-seed via the lookup miss path.
-          { stream: s, stream_exact: true, backward: true, limit: 2 }
-        );
-        if (maxId >= 0) streamInfo.set(s, { maxId, version, lastEventName });
-      })
-    );
-    const skipped = [];
-    let safe;
-    if (this._reactive_events.size === 0) {
-      safe = [...streamInfo.keys()];
-    } else {
-      const pendingSet = /* @__PURE__ */ new Set();
-      await store().query_streams((position) => {
-        const sourceRe = position.source ? RegExp(position.source) : void 0;
-        for (const [stream, info] of streamInfo) {
-          if ((!sourceRe || sourceRe.test(stream)) && position.at < info.maxId) {
-            pendingSet.add(stream);
-          }
-        }
-      });
-      safe = [];
-      for (const [stream] of streamInfo) {
-        if (pendingSet.has(stream)) {
-          skipped.push(stream);
-        } else {
-          safe.push(stream);
-        }
-      }
-    }
-    if (!safe.length) {
-      const result2 = { truncated: /* @__PURE__ */ new Map(), skipped };
-      this.emit("closed", result2);
-      return result2;
-    }
-    const correlation = randomUUID2();
-    const guarded = [];
-    const guardEvents = /* @__PURE__ */ new Map();
-    await Promise.all(
-      safe.map(async (stream) => {
-        try {
-          const info = streamInfo.get(stream);
-          const [committed] = await store().commit(
-            stream,
-            [{ name: TOMBSTONE_EVENT, data: {} }],
-            { correlation, causation: {} },
-            info.version
-          );
-          guarded.push(stream);
-          guardEvents.set(stream, { id: committed.id, stream });
-        } catch {
-          skipped.push(stream);
-        }
-      })
-    );
-    if (!guarded.length) {
-      const result2 = { truncated: /* @__PURE__ */ new Map(), skipped };
-      this.emit("closed", result2);
-      return result2;
-    }
-    const seedStates = /* @__PURE__ */ new Map();
-    await Promise.all(
-      guarded.filter((s) => targetMap.get(s)?.restart).map(async (stream) => {
-        const lastEventName = streamInfo.get(stream)?.lastEventName;
-        const ownerState = lastEventName ? this._event_to_state.get(lastEventName) : void 0;
-        if (!ownerState) {
-          this._logger.error(
-            `Cannot seed restart for "${stream}": no registered state owns event "${lastEventName ?? "<none>"}". Stream will be tombstoned instead.`
-          );
-          return;
-        }
-        const snap2 = await this._es.load(ownerState, stream);
-        seedStates.set(stream, snap2.state);
-      })
-    );
-    for (const stream of guarded) {
-      const archiveFn = targetMap.get(stream)?.archive;
-      if (archiveFn) await archiveFn();
-    }
-    const truncTargets = guarded.map((stream) => {
-      const snapshot = seedStates.get(stream);
-      const guard = guardEvents.get(stream);
-      return {
-        stream,
-        snapshot,
-        meta: {
-          correlation,
-          causation: {
-            event: {
-              id: guard.id,
-              name: TOMBSTONE_EVENT,
-              stream: guard.stream
-            }
-          }
-        }
-      };
+    const result = await runCloseCycle(targets, {
+      reactiveEventsSize: this._reactive_events.size,
+      eventToState: this._event_to_state,
+      load: this._es.load,
+      tombstone: this._es.tombstone,
+      logger: this._logger
     });
-    const truncated = await store().truncate(truncTargets);
-    await Promise.all(
-      guarded.map(async (stream) => {
-        const entry = truncated.get(stream);
-        const state2 = seedStates.get(stream);
-        if (state2 && entry) {
-          await cache().set(stream, {
-            state: state2,
-            version: entry.committed.version,
-            event_id: entry.committed.id,
-            patches: 0,
-            snaps: 1
-          });
-        } else {
-          await cache().invalidate(stream);
-        }
-      })
-    );
-    const result = { truncated, skipped };
     this.emit("closed", result);
     return result;
   }
@@ -2042,7 +2258,7 @@ var Act = class {
   }
 };
 
-// src/act-builder.ts
+// src/builders/act-builder.ts
 function registerBatchHandler(proj, batchHandlers) {
   if (!proj.batchHandler || !proj.target) return;
   const existing = batchHandlers.get(proj.target);
@@ -2051,56 +2267,33 @@ function registerBatchHandler(proj, batchHandlers) {
   }
   batchHandlers.set(proj.target, proj.batchHandler);
 }
-function act(states = /* @__PURE__ */ new Map(), registry = {
-  actions: {},
-  events: {}
-}, pendingProjections = [], batchHandlers = /* @__PURE__ */ new Map()) {
+function act() {
+  const states = /* @__PURE__ */ new Map();
+  const registry = {
+    actions: {},
+    events: {}
+  };
+  const pendingProjections = [];
+  const batchHandlers = /* @__PURE__ */ new Map();
   const builder = {
     withState: (state2) => {
       registerState(state2, states, registry.actions, registry.events);
-      return act(
-        states,
-        registry,
-        pendingProjections,
-        batchHandlers
-      );
+      return builder;
     },
     withSlice: (input) => {
       for (const s of input.states.values()) {
         registerState(s, states, registry.actions, registry.events);
       }
-      for (const eventName of Object.keys(input.events)) {
-        const sliceRegister = input.events[eventName];
-        for (const [name, reaction] of sliceRegister.reactions) {
-          registry.events[eventName].reactions.set(name, reaction);
-        }
-      }
+      mergeEventRegister(registry.events, input.events);
       pendingProjections.push(...input.projections);
-      return act(
-        states,
-        registry,
-        pendingProjections,
-        batchHandlers
-      );
+      return builder;
     },
     withProjection: (proj) => {
       mergeProjection(proj, registry.events);
       registerBatchHandler(proj, batchHandlers);
-      return act(
-        states,
-        registry,
-        pendingProjections,
-        batchHandlers
-      );
-    },
-    withActor: () => {
-      return act(
-        states,
-        registry,
-        pendingProjections,
-        batchHandlers
-      );
+      return builder;
     },
+    withActor: () => builder,
     on: (event) => ({
       do: (handler, options) => {
         const reaction = {
@@ -2116,19 +2309,15 @@ function act(states = /* @__PURE__ */ new Map(), registry = {
             `Reaction handler for "${String(event)}" must be a named function`
           );
         registry.events[event].reactions.set(handler.name, reaction);
-        return {
-          ...builder,
+        return Object.assign(builder, {
           to(resolver) {
-            registry.events[event].reactions.set(handler.name, {
-              ...reaction,
-              resolver: typeof resolver === "string" ? { target: resolver } : resolver
-            });
+            reaction.resolver = typeof resolver === "string" ? { target: resolver } : resolver;
             return builder;
           }
-        };
+        });
       }
     }),
-    build: () => {
+    build: (options) => {
       for (const proj of pendingProjections) {
         mergeProjection(proj, registry.events);
         registerBatchHandler(proj, batchHandlers);
@@ -2136,7 +2325,8 @@ function act(states = /* @__PURE__ */ new Map(), registry = {
       return new Act(
         registry,
         states,
-        batchHandlers
+        batchHandlers,
+        options
       );
     },
     events: registry.events
@@ -2144,8 +2334,9 @@ function act(states = /* @__PURE__ */ new Map(), registry = {
   return builder;
 }
 
-// src/projection-builder.ts
-function _projection(target, events) {
+// src/builders/projection-builder.ts
+function _projection(target) {
+  const events = {};
   const defaultResolver = typeof target === "string" ? { target } : void 0;
   const base = {
     on: (entry) => {
@@ -2175,17 +2366,13 @@ function _projection(target, events) {
               `Projection handler for "${event}" must be a named function`
             );
           register.reactions.set(handler.name, reaction);
-          const nextBuilder = _projection(target, events);
-          return {
-            ...nextBuilder,
+          const widened = base;
+          return Object.assign(widened, {
             to(resolver) {
-              register.reactions.set(handler.name, {
-                ...reaction,
-                resolver: typeof resolver === "string" ? { target: resolver } : resolver
-              });
-              return nextBuilder;
+              reaction.resolver = typeof resolver === "string" ? { target: resolver } : resolver;
+              return widened;
             }
-          };
+          });
         }
       };
     },
@@ -2197,8 +2384,7 @@ function _projection(target, events) {
     events
   };
   if (typeof target === "string") {
-    return {
-      ...base,
+    return Object.assign(base, {
       batch: (handler) => ({
         build: () => ({
           _tag: "Projection",
@@ -2207,34 +2393,28 @@ function _projection(target, events) {
           batchHandler: handler
         })
       })
-    };
+    });
   }
   return base;
 }
-function projection(target, events = {}) {
-  return _projection(target, events);
+function projection(target) {
+  return _projection(target);
 }
 
-// src/slice-builder.ts
-function slice(states = /* @__PURE__ */ new Map(), actions = {}, events = {}, projections = []) {
+// src/builders/slice-builder.ts
+function slice() {
+  const states = /* @__PURE__ */ new Map();
+  const actions = {};
+  const events = {};
+  const projections = [];
   const builder = {
     withState: (state2) => {
       registerState(state2, states, actions, events);
-      return slice(
-        states,
-        actions,
-        events,
-        projections
-      );
+      return builder;
     },
     withProjection: (proj) => {
       projections.push(proj);
-      return slice(
-        states,
-        actions,
-        events,
-        projections
-      );
+      return builder;
     },
     on: (event) => ({
       do: (handler, options) => {
@@ -2251,16 +2431,12 @@ function slice(states = /* @__PURE__ */ new Map(), actions = {}, events = {}, pr
             `Reaction handler for "${String(event)}" must be a named function`
           );
         events[event].reactions.set(handler.name, reaction);
-        return {
-          ...builder,
+        return Object.assign(builder, {
           to(resolver) {
-            events[event].reactions.set(handler.name, {
-              ...reaction,
-              resolver: typeof resolver === "string" ? { target: resolver } : resolver
-            });
+            reaction.resolver = typeof resolver === "string" ? { target: resolver } : resolver;
             return builder;
           }
-        };
+        });
       }
     }),
     build: () => ({
@@ -2274,7 +2450,7 @@ function slice(states = /* @__PURE__ */ new Map(), actions = {}, events = {}, pr
   return builder;
 }
 
-// src/state-builder.ts
+// src/builders/state-builder.ts
 function state(entry) {
   const keys = Object.keys(entry);
   if (keys.length !== 1) throw new Error("state() requires exactly one key");
@@ -2292,7 +2468,7 @@ function state(entry) {
               return [k, fn];
             })
           );
-          const builder = action_builder({
+          const internal = {
             events,
             actions: {},
             state: stateSchema,
@@ -2300,18 +2476,12 @@ function state(entry) {
             init,
             patch: defaultPatch,
             on: {}
-          });
+          };
+          const builder = action_builder(internal);
           return Object.assign(builder, {
             patch(customPatch) {
-              return action_builder({
-                events,
-                actions: {},
-                state: stateSchema,
-                name,
-                init,
-                patch: { ...defaultPatch, ...customPatch },
-                on: {}
-              });
+              Object.assign(internal.patch, customPatch);
+              return builder;
             }
           });
         }
@@ -2320,50 +2490,43 @@ function state(entry) {
   };
 }
 function action_builder(state2) {
-  return {
+  const internal = state2;
+  const builder = {
     on(entry) {
       const keys = Object.keys(entry);
       if (keys.length !== 1) throw new Error(".on() requires exactly one key");
       const action2 = keys[0];
       const schema = entry[action2];
-      if (action2 in state2.actions)
+      if (action2 in internal.actions)
         throw new Error(`Duplicate action "${action2}"`);
-      const actions = {
-        ...state2.actions,
-        [action2]: schema
-      };
-      const on = { ...state2.on };
-      const _given = { ...state2.given };
+      internal.actions[action2] = schema;
       function given(rules) {
-        _given[action2] = rules;
+        (internal.given ??= {})[action2] = rules;
         return { emit };
       }
       function emit(handler) {
         if (typeof handler === "string") {
           const eventName = handler;
-          on[action2] = ((payload) => [eventName, payload]);
+          internal.on[action2] = (payload) => [
+            eventName,
+            payload
+          ];
         } else {
-          on[action2] = handler;
+          internal.on[action2] = handler;
         }
-        return action_builder({
-          ...state2,
-          actions,
-          on,
-          given: _given
-        });
+        return builder;
       }
       return { given, emit };
     },
     snap(snap2) {
-      return action_builder({
-        ...state2,
-        snap: snap2
-      });
+      internal.snap = snap2;
+      return builder;
     },
     build() {
-      return state2;
+      return internal;
     }
   };
+  return builder;
 }
 export {
   Act,
@@ -2372,6 +2535,7 @@ export {
   CommittedMetaSchema,
   ConcurrencyError,
   ConsoleLogger,
+  DEFAULT_MAX_SUBSCRIBED_STREAMS,
   Environments,
   Errors,
   EventMetaSchema,