@rotorsoft/act 0.5.7 → 0.6.1

package/dist/index.cjs

@@ -48,6 +48,7 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   ZodEmpty: () => ZodEmpty,
   act: () => act,
+  build_tracer: () => build_tracer,
   config: () => config,
   dispose: () => dispose,
   disposeAndExit: () => disposeAndExit,
@@ -81,18 +82,24 @@ var ValidationError = class extends Error {
   }
 };
 var InvariantError = class extends Error {
-  details;
-  constructor(name, payload, target, description) {
-    super(`${name} failed invariant: ${description}`);
+  constructor(action2, payload, target, snapshot, description) {
+    super(`${action2} failed invariant: ${description}`);
+    this.action = action2;
+    this.payload = payload;
+    this.target = target;
+    this.snapshot = snapshot;
+    this.description = description;
     this.name = Errors.InvariantError;
-    this.details = { name, payload, target, description };
   }
 };
 var ConcurrencyError = class extends Error {
-  constructor(lastVersion, events, expectedVersion) {
+  constructor(stream, lastVersion, events, expectedVersion) {
     super(
-      `Concurrency error committing event "${events.at(0)?.name}". Expected version ${expectedVersion} but found version ${lastVersion}.`
+      `Concurrency error committing "${events.map((e) => `${stream}.${e.name}.${JSON.stringify(e.data)}`).join(
+        ", "
+      )}". Expected version ${expectedVersion} but found version ${lastVersion}.`
     );
+    this.stream = stream;
     this.lastVersion = lastVersion;
     this.events = events;
     this.expectedVersion = expectedVersion;
@@ -147,8 +154,9 @@ var QuerySchema = import_zod.z.object({
   created_before: import_zod.z.date().optional(),
   created_after: import_zod.z.date().optional(),
   backward: import_zod.z.boolean().optional(),
-  correlation: import_zod.z.string().optional()
-});
+  correlation: import_zod.z.string().optional(),
+  with_snaps: import_zod.z.boolean().optional()
+}).readonly();
 
 // src/types/index.ts
 var Environments = [
@@ -254,38 +262,71 @@ async function sleep(ms) {
 
 // src/adapters/InMemoryStore.ts
 var InMemoryStream = class {
-  constructor(stream) {
+  stream;
+  source;
+  at = -1;
+  retry = -1;
+  blocked = false;
+  error = "";
+  leased_at = void 0;
+  leased_by = void 0;
+  leased_until = void 0;
+  constructor(stream, source) {
     this.stream = stream;
+    this.source = source;
+  }
+  get is_avaliable() {
+    return !this.blocked && (!this.leased_until || this.leased_until <= /* @__PURE__ */ new Date());
   }
-  _at = -1;
-  _retry = -1;
-  _lease;
-  _blocked = false;
   /**
    * Attempt to lease this stream for processing.
-   * @param lease - Lease request.
+   * @param at - The end-of-lease watermark.
+   * @param by - The lease holder.
+   * @param millis - Lease duration in milliseconds.
    * @returns The granted lease or undefined if blocked.
    */
-  lease(lease) {
-    if (!this._blocked && lease.at > this._at) {
-      this._lease = { ...lease, retry: this._retry + 1 };
-      return this._lease;
+  lease(at, by, millis) {
+    if (this.is_avaliable && at > this.at) {
+      this.leased_at = at;
+      this.leased_by = by;
+      this.leased_until = new Date(Date.now() + millis);
+      millis > 0 && (this.retry = this.retry + 1);
+      return {
+        stream: this.stream,
+        source: this.source,
+        at,
+        by,
+        retry: this.retry
+      };
     }
   }
   /**
    * Acknowledge completion of processing for this stream.
-   * @param lease - Lease to acknowledge.
+   * @param at - Last processed watermark.
+   * @param by - Lease holder that processed the watermark.
    */
-  ack(lease) {
-    if (this._lease && lease.at >= this._at) {
-      this._retry = lease.retry;
-      this._blocked = lease.block;
-      if (!this._blocked && !lease.error) {
-        this._at = lease.at;
-        this._retry = 0;
-      }
-      this._lease = void 0;
+  ack(at, by) {
+    if (this.leased_by === by && at >= this.at) {
+      this.leased_at = void 0;
+      this.leased_by = void 0;
+      this.leased_until = void 0;
+      this.at = at;
+      this.retry = -1;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.
+   * @param error Blocked error message.
+   */
+  block(by, error) {
+    if (this.leased_by === by) {
+      this.blocked = true;
+      this.error = error;
+      return true;
     }
+    return false;
   }
 };
 var InMemoryStore = class {
@@ -315,6 +356,7 @@ var InMemoryStore = class {
   async drop() {
     await sleep();
     this._events.length = 0;
+    this._streams = /* @__PURE__ */ new Map();
   }
   /**
    * Query events in the store, optionally filtered by query options.
@@ -332,15 +374,17 @@ var InMemoryStore = class {
       limit,
       created_before,
       created_after,
-      correlation
+      correlation,
+      with_snaps = false
     } = query || {};
     let i = after + 1, count = 0;
     while (i < this._events.length) {
       const e = this._events[i++];
-      if (stream && e.stream !== stream) continue;
+      if (stream && !RegExp(`^${stream}$`).test(e.stream)) continue;
       if (names && !names.includes(e.name)) continue;
       if (correlation && e.meta?.correlation !== correlation) continue;
       if (created_after && e.created <= created_after) continue;
+      if (e.name === SNAP_EVENT && !with_snaps) continue;
       if (before && e.id >= before) break;
       if (created_before && e.created >= created_before) break;
       callback(e);
@@ -361,12 +405,14 @@ var InMemoryStore = class {
   async commit(stream, msgs, meta, expectedVersion) {
     await sleep();
     const instance = this._events.filter((e) => e.stream === stream);
-    if (typeof expectedVersion === "number" && instance.length - 1 !== expectedVersion)
+    if (typeof expectedVersion === "number" && instance.length - 1 !== expectedVersion) {
       throw new ConcurrencyError(
+        stream,
         instance.length - 1,
         msgs,
         expectedVersion
       );
+    }
     let version = instance.length;
     return msgs.map(({ name, data }) => {
       const committed = {
@@ -384,43 +430,49 @@ var InMemoryStore = class {
     });
   }
   /**
-   * Fetches new events from stream watermarks for processing.
-   * @param limit - Maximum number of streams to fetch.
-   * @returns Fetched streams and events.
+   * Polls the store for unblocked streams needing processing, ordered by lease watermark ascending.
+   * @param limit - Maximum number of streams to poll.
+   * @param descending - Whether to poll streams in descending order (aka poll the most advanced first).
+   * @returns The polled streams.
    */
-  async fetch(limit) {
-    const streams = [...this._streams.values()].filter((s) => !s._blocked).sort((a, b) => a._at - b._at).slice(0, limit);
-    const after = streams.length ? streams.reduce(
-      (min, s) => Math.min(min, s._at),
-      Number.MAX_SAFE_INTEGER
-    ) : -1;
-    const events = [];
-    await this.query((e) => e.name !== SNAP_EVENT && events.push(e), {
-      after,
-      limit
-    });
-    return { streams: streams.map(({ stream }) => stream), events };
+  async poll(limit, descending = false) {
+    await sleep();
+    return [...this._streams.values()].filter((s) => s.is_avaliable).sort((a, b) => descending ? b.at - a.at : a.at - b.at).slice(0, limit).map(({ stream, source, at }) => ({ stream, source, at }));
   }
   /**
    * Lease streams for processing (e.g., for distributed consumers).
-   * @param leases - Lease requests.
+   * @param leases - Lease requests for streams, including end-of-lease watermark, lease holder, and source stream.
+   * @param leaseMilis - Lease duration in milliseconds.
    * @returns Granted leases.
    */
-  async lease(leases) {
+  async lease(leases, millis) {
     await sleep();
-    return leases.map((lease) => {
-      const stream = this._streams.get(lease.stream) || // store new correlations
-      this._streams.set(lease.stream, new InMemoryStream(lease.stream)).get(lease.stream);
-      return stream.lease(lease);
+    return leases.map(({ stream, at, by, source }) => {
+      const found = this._streams.get(stream) || // store new correlations
+      this._streams.set(stream, new InMemoryStream(stream, source)).get(stream);
+      return found.lease(at, by, millis);
     }).filter((l) => !!l);
   }
   /**
    * Acknowledge completion of processing for leased streams.
-   * @param leases - Leases to acknowledge.
+   * @param leases - Leases to acknowledge, including last processed watermark and lease holder.
    */
   async ack(leases) {
     await sleep();
-    leases.forEach((lease) => this._streams.get(lease.stream)?.ack(lease));
+    return leases.filter(
+      (lease) => this._streams.get(lease.stream)?.ack(lease.at, lease.by)
+    );
+  }
+  /**
+   * Block a stream for processing after failing to process and reaching max retries with blocking enabled.
+   * @param leases - Leases to block, including lease holder and last error message.
+   * @returns Blocked leases.
+   */
+  async block(leases) {
+    await sleep();
+    return leases.filter(
+      (lease) => this._streams.get(lease.stream)?.block(lease.by, lease.error)
+    );
   }
 };
 
@@ -469,6 +521,62 @@ var SNAP_EVENT = "__snapshot__";
 var store = port(function store2(adapter) {
   return adapter || new InMemoryStore();
 });
+function build_tracer(logLevel2) {
+  if (logLevel2 === "trace") {
+    return {
+      fetched: (fetched) => {
+        const data = Object.fromEntries(
+          fetched.map(({ stream, source, events }) => {
+            const key = source ? `${stream}<-${source}` : stream;
+            const value = Object.fromEntries(
+              events.map(({ id, stream: stream2, name }) => [id, { [stream2]: name }])
+            );
+            return [key, value];
+          })
+        );
+        logger.trace(data, "\u26A1\uFE0F fetch");
+      },
+      correlated: (leases) => {
+        const data = leases.map(({ stream }) => stream).join(" ");
+        logger.trace(`\u26A1\uFE0F correlate ${data}`);
+      },
+      leased: (leases) => {
+        const data = Object.fromEntries(
+          leases.map(({ stream, at, retry }) => [stream, { at, retry }])
+        );
+        logger.trace(data, "\u26A1\uFE0F lease");
+      },
+      acked: (leases) => {
+        const data = Object.fromEntries(
+          leases.map(({ stream, at, retry }) => [stream, { at, retry }])
+        );
+        logger.trace(data, "\u26A1\uFE0F ack");
+      },
+      blocked: (leases) => {
+        const data = Object.fromEntries(
+          leases.map(({ stream, at, retry, error }) => [
+            stream,
+            { at, retry, error }
+          ])
+        );
+        logger.trace(data, "\u26A1\uFE0F block");
+      }
+    };
+  } else {
+    return {
+      fetched: () => {
+      },
+      correlated: () => {
+      },
+      leased: () => {
+      },
+      acked: () => {
+      },
+      blocked: () => {
+      }
+    };
+  }
+}
 
 // src/signals.ts
 process.once("SIGINT", async (arg) => {
@@ -530,21 +638,21 @@ async function load(me, stream, callback) {
       }
       callback && callback({ event, state: state2, patches, snaps });
     },
-    { stream },
-    true
+    { stream, with_snaps: true }
   );
-  logger.trace({ stream, patches, snaps, state: state2 }, "\u{1F7E2} load");
+  logger.trace(state2, `\u{1F7E2} load ${stream}`);
   return { event, state: state2, patches, snaps };
 }
 async function action(me, action2, target, payload, reactingTo, skipValidation = false) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
   payload = skipValidation ? payload : validate(action2, payload, me.actions[action2]);
+  const snapshot = await load(me, stream);
+  const expected = expectedVersion || snapshot.event?.version;
   logger.trace(
     payload,
-    `\u{1F535} ${action2} "${stream}${expectedVersion ? `@${expectedVersion}` : ""}"`
+    `\u{1F535} ${stream}.${action2}${typeof expected === "number" ? `.${expected}` : ""}`
   );
-  let snapshot = await load(me, stream);
   if (me.given) {
     const invariants = me.given[action2] || [];
     invariants.forEach(({ valid, description }) => {
@@ -553,15 +661,15 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
           action2,
           payload,
           target,
+          snapshot,
           description
         );
     });
   }
-  let { state: state2, patches } = snapshot;
-  const result = me.on[action2](payload, state2, target);
-  if (!result) return snapshot;
+  const result = me.on[action2](payload, snapshot, target);
+  if (!result) return [snapshot];
   if (Array.isArray(result) && result.length === 0) {
-    return snapshot;
+    return [snapshot];
   }
   const tuples = Array.isArray(result[0]) ? result : [result];
   const emitted = tuples.map(([name, data]) => ({
@@ -584,36 +692,47 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
       } : void 0
     }
   };
+  logger.trace(
+    emitted.map((e) => e.data),
+    `\u{1F534} commit ${stream}.${emitted.map((e) => e.name).join(", ")}`
+  );
   const committed = await store().commit(
     stream,
     emitted,
     meta,
     // TODO: review reactions not enforcing expected version
-    reactingTo ? void 0 : expectedVersion || snapshot.event?.version
+    reactingTo ? void 0 : expected
   );
-  snapshot = committed.map((event) => {
+  let { state: state2, patches } = snapshot;
+  const snapshots = committed.map((event) => {
     state2 = patch(state2, me.patch[event.name](event, state2));
     patches++;
-    logger.trace({ event, state: state2 }, "\u{1F534} commit");
     return { event, state: state2, patches, snaps: snapshot.snaps };
-  }).at(-1);
-  me.snap && me.snap(snapshot) && void snap(snapshot);
-  return snapshot;
+  });
+  const last = snapshots.at(-1);
+  me.snap && me.snap(last) && void snap(last);
+  return snapshots;
 }
 
 // src/act.ts
+var tracer = build_tracer(config().logLevel);
 var Act = class {
   /**
    * Create a new Act orchestrator.
    *
    * @param registry The registry of state, event, and action schemas
-   * @param drainLimit The maximum number of events to drain per cycle
    */
-  constructor(registry, drainLimit) {
+  constructor(registry) {
     this.registry = registry;
-    this.drainLimit = drainLimit;
+    dispose(() => {
+      this._emitter.removeAllListeners();
+      this.stop_correlations();
+      return Promise.resolve();
+    });
   }
   _emitter = new import_events.default();
+  _drain_locked = false;
+  _correlation_interval = void 0;
   emit(event, args) {
     return this._emitter.emit(event, args);
   }
@@ -640,16 +759,17 @@ var Act = class {
    * await app.do("increment", { stream: "counter1", actor }, { by: 1 });
    */
   async do(action2, target, payload, reactingTo, skipValidation = false) {
-    const snapshot = await action(
+    const snapshots = await action(
       this.registry.actions[action2],
       action2,
       target,
       payload,
+      // @ts-expect-error type lost
       reactingTo,
       skipValidation
     );
-    this.emit("committed", snapshot);
-    return snapshot;
+    this.emit("committed", snapshots);
+    return snapshots;
   }
   /**
    * Loads the current state snapshot for a given state machine and stream.
@@ -687,38 +807,58 @@ var Act = class {
     }, query);
     return { first, last, count };
   }
+  /**
+   * Query the event store for events matching a filter.
+   * Use this version with caution, as it return events in memory.
+   *
+   * @param query The query filter (e.g., by stream, event name, or time range)
+   * @returns The matching events
+   *
+   * @example
+   * const { count } = await app.query({ stream: "counter1" }, (event) => console.log(event));
+   */
+  async query_array(query) {
+    const events = [];
+    await store().query((e) => events.push(e), query);
+    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.
+   *
    * @internal
    * @param lease The lease to handle
-   * @param reactions The reactions to handle
-   * @returns The lease
+   * @param payloads The reactions to handle
+   * @returns The lease with results
    */
-  async handle(lease, reactions) {
+  async handle(lease, payloads) {
+    if (payloads.length === 0) return { lease, at: lease.at };
     const stream = lease.stream;
-    lease.retry > 0 && logger.warn(`Retrying ${stream}@${lease.at} (${lease.retry}).`);
-    for (const reaction of reactions) {
-      const { event, handler, options } = reaction;
+    let at = payloads.at(0).event.id, handled = 0;
+    lease.retry > 0 && logger.warn(`Retrying ${stream}@${at} (${lease.retry}).`);
+    for (const payload of payloads) {
+      const { event, handler, options } = payload;
       try {
         await handler(event, stream);
-        lease.at = event.id;
+        at = event.id;
+        handled++;
       } catch (error) {
-        lease.error = error;
-        if (error instanceof ValidationError)
-          logger.error({ stream, error }, error.message);
-        else logger.error(error);
-        if (lease.retry < options.maxRetries) lease.retry++;
-        else if (options.blockOnError) {
-          lease.block = true;
-          logger.error(`Blocked ${stream} after ${lease.retry} retries.`);
-        }
-        break;
+        logger.error(error);
+        const block = lease.retry >= options.maxRetries && options.blockOnError;
+        block && logger.error(`Blocking ${stream} after ${lease.retry} retries.`);
+        return {
+          lease,
+          at,
+          // only report error when nothing was handled
+          error: handled === 0 ? error.message : void 0,
+          block
+        };
       }
     }
-    return lease;
+    return { lease, at };
   }
-  drainLocked = false;
   /**
    * Drains and processes events from the store, triggering reactions and updating state.
    *
@@ -729,91 +869,173 @@ var Act = class {
    * @example
    * await app.drain();
    */
-  async drain() {
-    if (this.drainLocked) return 0;
-    this.drainLocked = true;
-    const drained = [];
-    const { streams, events } = await store().fetch(this.drainLimit);
-    if (events.length) {
-      logger.trace(
-        events.map(({ id, stream, name }) => ({ id, stream, name })).reduce(
-          (a, { id, stream, name }) => ({ ...a, [id]: { [stream]: name } }),
-          {}
-        ),
-        "\u26A1\uFE0F fetch"
-      );
-      const resolved = new Set(streams);
-      const correlated = /* @__PURE__ */ new Map();
-      for (const event of events) {
-        const register = this.registry.events[event.name];
-        if (!register) continue;
-        for (const reaction of register.reactions.values()) {
-          const stream = typeof reaction.resolver === "string" ? reaction.resolver : reaction.resolver(event);
-          if (stream) {
-            resolved.add(stream);
-            (correlated.get(stream) || correlated.set(stream, []).get(stream)).push({ ...reaction, event });
+  async drain({
+    streamLimit = 10,
+    eventLimit = 10,
+    leaseMillis = 1e4,
+    descending = false
+  } = {}) {
+    if (!this._drain_locked) {
+      try {
+        this._drain_locked = true;
+        const polled = await store().poll(streamLimit, descending);
+        const fetched = await Promise.all(
+          polled.map(async ({ stream, source, at }) => {
+            const events = await this.query_array({
+              stream: source,
+              after: at,
+              limit: eventLimit
+            });
+            return { stream, source, events };
+          })
+        );
+        fetched.length && tracer.fetched(fetched);
+        const [last_at, count] = fetched.reduce(
+          ([last_at2, count2], { events }) => [
+            Math.max(last_at2, events.at(-1)?.id || 0),
+            count2 + events.length
+          ],
+          [0, 0]
+        );
+        if (count > 0) {
+          const leases = /* @__PURE__ */ new Map();
+          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" ? (
+                  // @ts-expect-error index by key
+                  reaction.resolver(event)
+                ) : reaction.resolver;
+                return resolved && resolved.target === stream;
+              }).map((reaction) => ({ ...reaction, event }));
+            });
+            leases.set(stream, {
+              lease: {
+                stream,
+                by: (0, import_crypto2.randomUUID)(),
+                at: events.at(-1)?.id || last_at,
+                // move the lease watermark forward when no events found in window
+                retry: 0
+              },
+              // @ts-expect-error indexed by key
+              payloads
+            });
+          });
+          if (leases.size) {
+            const leased = await store().lease(
+              [...leases.values()].map((l) => l.lease),
+              leaseMillis
+            );
+            if (leased.length) {
+              tracer.leased(leased);
+              const handled = await Promise.all(
+                leased.map(
+                  (lease) => this.handle(lease, leases.get(lease.stream).payloads)
+                )
+              );
+              const acked = await store().ack(
+                handled.filter(({ error }) => !error).map(({ at, lease }) => ({ ...lease, at }))
+              );
+              if (acked.length) {
+                tracer.acked(acked);
+                this.emit("acked", acked);
+              }
+              const blocked = await store().block(
+                handled.filter(({ block }) => block).map(({ lease, error }) => ({ ...lease, error }))
+              );
+              if (blocked.length) {
+                tracer.blocked(blocked);
+                this.emit("blocked", blocked);
+              }
+              return { leased, acked, blocked };
+            }
           }
         }
+      } catch (error) {
+        logger.error(error);
+      } finally {
+        this._drain_locked = false;
       }
-      const last = events.at(-1).id;
-      const leases = [...resolved.values()].map((stream) => ({
-        by: (0, import_crypto2.randomUUID)(),
+    }
+    return { leased: [], acked: [], blocked: [] };
+  }
+  /**
+   * Correlates streams using reaction resolvers.
+   * @param query - The query filter (e.g., by stream, event name, or starting point).
+   * @returns The leases of newly correlated streams, and the last seen event ID.
+   */
+  async correlate(query = { after: -1, limit: 10 }) {
+    const correlated = /* @__PURE__ */ new Map();
+    let last_id = query.after || -1;
+    await store().query((event) => {
+      last_id = event.id;
+      const register = this.registry.events[event.name];
+      if (register) {
+        for (const reaction of register.reactions.values()) {
+          const resolved = typeof reaction.resolver === "function" ? reaction.resolver(event) : reaction.resolver;
+          resolved && (correlated.get(resolved.target) || correlated.set(resolved.target, []).get(resolved.target)).push({ ...reaction, source: resolved.source, event });
+        }
+      }
+    }, query);
+    if (correlated.size) {
+      const leases = [...correlated.entries()].map(([stream, payloads]) => ({
         stream,
-        at: last,
+        // TODO: by convention, the first defined source wins (this can be tricky)
+        source: payloads.find((p) => p.source)?.source || void 0,
+        by: (0, import_crypto2.randomUUID)(),
+        at: 0,
         retry: 0,
-        block: false
+        payloads
       }));
-      const leased = await store().lease(leases);
-      logger.trace(
-        leased.map(({ stream, at, retry }) => ({ stream, at, retry })).reduce(
-          (a, { stream, at, retry }) => ({ ...a, [stream]: { at, retry } }),
-          {}
-        ),
-        "\u26A1\uFE0F lease"
-      );
-      const handling = leased.map((lease) => ({
-        lease,
-        reactions: correlated.get(lease.stream) || []
-      })).filter(({ reactions }) => reactions.length);
-      if (handling.length) {
-        await Promise.allSettled(
-          handling.map(({ lease, reactions }) => this.handle(lease, reactions))
-        ).then(
-          (promise) => {
-            promise.forEach((result) => {
-              if (result.status === "rejected") logger.error(result.reason);
-              else if (!result.value.error) drained.push(result.value);
-            });
-          },
-          (error) => logger.error(error)
-        );
-        drained.length && this.emit("drained", drained);
-      }
-      await store().ack(leased);
-      logger.trace(
-        leased.map(({ stream, at, retry, block, error }) => ({
-          stream,
-          at,
-          retry,
-          block,
-          error
-        })).reduce(
-          (a, { stream, at, retry, block, error }) => ({
-            ...a,
-            [stream]: { at, retry, block, error }
-          }),
-          {}
-        ),
-        "\u26A1\uFE0F ack"
-      );
+      const leased = await store().lease(leases, 0);
+      leased.length && tracer.correlated(leased);
+      return { leased, last_id };
+    }
+    return { leased: [], last_id };
+  }
+  /**
+   * Starts correlation worker that identifies and registers new streams using reaction resolvers.
+   *
+   * Enables "dynamic reactions", allowing streams to be auto-discovered based on event content.
+   * - Uses a correlation sliding window over the event stream to identify new streams.
+   * - Once registered, these streams are picked up by the main `drain` loop.
+   * - Users should have full control over their correlation strategy.
+   * - The starting point keeps increasing with each new batch of events.
+   * - Users are responsible for storing the last seen event ID.
+   *
+   * @param query - The query filter (e.g., by stream, event name, or starting point).
+   * @param frequency - The frequency of correlation checks (in milliseconds).
+   * @param callback - Callback to report stats (new strems, last seen event ID, etc.).
+   * @returns true if the correlation worker started, false otherwise (already started).
+   */
+  start_correlations(query = {}, frequency = 1e4, callback) {
+    if (this._correlation_interval) return false;
+    const limit = query.limit || 100;
+    let after = query.after || -1;
+    this._correlation_interval = setInterval(
+      () => this.correlate({ ...query, after, limit }).then((result) => {
+        after = result.last_id;
+        if (callback && result.leased.length) callback(result.leased);
+      }).catch(console.error),
+      frequency
+    );
+    return true;
+  }
+  stop_correlations() {
+    if (this._correlation_interval) {
+      clearInterval(this._correlation_interval);
+      this._correlation_interval = void 0;
     }
-    this.drainLocked = false;
-    return drained.length;
   }
 };
 
 // src/act-builder.ts
-var _this_ = ({ stream }) => stream;
+var _this_ = ({ stream }) => ({
+  source: stream,
+  target: stream
+});
 var _void_ = () => void 0;
 function act(states = /* @__PURE__ */ new Set(), registry = {
   actions: {},
@@ -865,8 +1087,7 @@ function act(states = /* @__PURE__ */ new Set(), registry = {
           resolver: _this_,
           options: {
             blockOnError: options?.blockOnError ?? true,
-            maxRetries: options?.maxRetries ?? 3,
-            retryDelayMs: options?.retryDelayMs ?? 1e3
+            maxRetries: options?.maxRetries ?? 3
           }
         };
         registry.events[event].reactions.set(handler.name, reaction);
@@ -875,7 +1096,7 @@ function act(states = /* @__PURE__ */ new Set(), registry = {
           to(resolver) {
             registry.events[event].reactions.set(handler.name, {
               ...reaction,
-              resolver
+              resolver: typeof resolver === "string" ? { target: resolver } : resolver
             });
             return builder;
           },
@@ -889,7 +1110,7 @@ function act(states = /* @__PURE__ */ new Set(), registry = {
         };
       }
     }),
-    build: (drainLimit = 10) => new Act(registry, drainLimit),
+    build: () => new Act(registry),
     events: registry.events
   };
   return builder;
@@ -970,6 +1191,7 @@ function action_builder(state2) {
   ValidationError,
   ZodEmpty,
   act,
+  build_tracer,
   config,
   dispose,
   disposeAndExit,