@rotorsoft/act 0.41.0 → 0.43.0

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   InMemoryStore: () => InMemoryStore,
   InvariantError: () => InvariantError,
   LogLevels: () => LogLevels,
+  NonRetryableError: () => NonRetryableError,
   PackageSchema: () => PackageSchema,
   QuerySchema: () => QuerySchema,
   SNAP_EVENT: () => SNAP_EVENT,
@@ -286,7 +287,8 @@ var Errors = {
   ValidationError: "ERR_VALIDATION",
   InvariantError: "ERR_INVARIANT",
   ConcurrencyError: "ERR_CONCURRENCY",
-  StreamClosedError: "ERR_STREAM_CLOSED"
+  StreamClosedError: "ERR_STREAM_CLOSED",
+  NonRetryableError: "ERR_NON_RETRYABLE"
 };
 var ValidationError = class extends Error {
   constructor(target, payload, details) {
@@ -329,6 +331,15 @@ var StreamClosedError = class extends Error {
     this.name = Errors.StreamClosedError;
   }
 };
+var NonRetryableError = class extends Error {
+  /** The original failure, if any. Mirrors the standard `Error.cause` shape. */
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = Errors.NonRetryableError;
+    this.cause = options?.cause;
+  }
+};
 
 // src/utils.ts
 var import_zod3 = require("zod");
@@ -597,6 +608,20 @@ var InMemoryStream = class {
     this._leased_by = void 0;
     this._leased_until = void 0;
   }
+  /**
+   * Clear the blocked flag and lease bookkeeping without touching the
+   * watermark. Returns true if the stream was actually blocked (and is
+   * now flipped); false otherwise.
+   */
+  unblock() {
+    if (!this._blocked) return false;
+    this._blocked = false;
+    this._retry = -1;
+    this._error = "";
+    this._leased_by = void 0;
+    this._leased_until = void 0;
+    return true;
+  }
 };
 var InMemoryStore = class {
   // stored events
@@ -832,19 +857,81 @@ var InMemoryStore = class {
     return leases.map((l) => this._streams.get(l.stream)?.block(l, l.error)).filter((l) => !!l);
   }
   /**
-   * Reset watermarks for the given streams to -1, clearing retry, blocked,
-   * error, and lease state so they can be replayed from the beginning.
-   * @param streams - Stream names to reset.
+   * Build a predicate from a {@link StreamFilter}. Compiled regexes are
+   * cached in the closure so callers can apply it across the streams
+   * map without re-compiling per iteration.
+   */
+  _filterPredicate(filter) {
+    const streamRe = filter.stream && !filter.stream_exact ? new RegExp(filter.stream) : void 0;
+    const sourceRe = filter.source && !filter.source_exact ? new RegExp(filter.source) : void 0;
+    return (s) => {
+      if (filter.stream !== void 0) {
+        if (filter.stream_exact ? s.stream !== filter.stream : !streamRe.test(s.stream))
+          return false;
+      }
+      if (filter.source !== void 0) {
+        if (s.source === void 0) return false;
+        if (filter.source_exact ? s.source !== filter.source : !sourceRe.test(s.source))
+          return false;
+      }
+      if (filter.blocked !== void 0 && s.blocked !== filter.blocked)
+        return false;
+      return true;
+    };
+  }
+  /**
+   * Reset watermarks to -1, clearing retry, blocked, error, and lease
+   * state so the matched streams can be replayed from the beginning.
+   * Accepts either an explicit list of names or a {@link StreamFilter}.
+   *
+   * @param input - Stream names or a filter selecting the streams to reset.
    * @returns Count of streams that were actually reset.
    */
-  async reset(streams) {
+  async reset(input) {
     await sleep();
     let count = 0;
-    for (const name of streams) {
-      const s = this._streams.get(name);
-      if (s) {
-        s.reset();
-        count++;
+    if (Array.isArray(input)) {
+      for (const name of input) {
+        const s = this._streams.get(name);
+        if (s) {
+          s.reset();
+          count++;
+        }
+      }
+    } else {
+      const matches = this._filterPredicate(input);
+      for (const s of this._streams.values()) {
+        if (matches(s)) {
+          s.reset();
+          count++;
+        }
+      }
+    }
+    return count;
+  }
+  /**
+   * Clear the blocked flag (and retry / error / lease) on the matched
+   * streams without touching the watermark. Streams that aren't blocked
+   * at call time are silently skipped. Accepts either an explicit list
+   * of names or a {@link StreamFilter}. The filter form always restricts
+   * to blocked streams — passing `blocked: false` matches nothing.
+   * See {@link Store.unblock}.
+   *
+   * @param input - Stream names or a filter selecting the streams to unblock.
+   * @returns Count of streams that were actually flipped (were blocked).
+   */
+  async unblock(input) {
+    await sleep();
+    let count = 0;
+    if (Array.isArray(input)) {
+      for (const name of input) {
+        const s = this._streams.get(name);
+        if (s?.unblock()) count++;
+      }
+    } else {
+      const matches = this._filterPredicate({ ...input, blocked: true });
+      for (const s of this._streams.values()) {
+        if (matches(s) && s.unblock()) count++;
       }
     }
     return count;
@@ -860,21 +947,10 @@ var InMemoryStore = class {
    */
   async prioritize(filter, priority) {
     await sleep();
-    const streamRe = filter.stream && !filter.stream_exact ? new RegExp(filter.stream) : void 0;
-    const sourceRe = filter.source && !filter.source_exact ? new RegExp(filter.source) : void 0;
+    const matches = this._filterPredicate(filter);
     let count = 0;
     for (const s of this._streams.values()) {
-      if (filter.stream !== void 0) {
-        if (filter.stream_exact ? s.stream !== filter.stream : !streamRe.test(s.stream))
-          continue;
-      }
-      if (filter.source !== void 0) {
-        if (s.source === void 0) continue;
-        if (filter.source_exact ? s.source !== filter.source : !sourceRe.test(s.source))
-          continue;
-      }
-      if (filter.blocked !== void 0 && s.blocked !== filter.blocked)
-        continue;
+      if (!matches(s)) continue;
       if (s.priority !== priority) {
         s.setPriority(priority);
         count++;
@@ -1090,7 +1166,6 @@ function classifyRegistry(registry, states) {
 }
 
 // src/internal/close-cycle.ts
-var import_node_crypto = require("crypto");
 async function runCloseCycle(targets, deps) {
   const targetMap = new Map(targets.map((t) => [t.stream, t]));
   const streams = [...targetMap.keys()];
@@ -1102,11 +1177,10 @@ async function runCloseCycle(targets, deps) {
     skipped
   );
   if (!safe.length) return { truncated: /* @__PURE__ */ new Map(), skipped };
-  const correlation = (0, import_node_crypto.randomUUID)();
   const { guarded, guardEvents } = await guardWithTombstones(
     safe,
     streamInfo,
-    correlation,
+    deps.correlation,
     deps.tombstone,
     skipped
   );
@@ -1124,7 +1198,7 @@ async function runCloseCycle(targets, deps) {
     guarded,
     seedStates,
     guardEvents,
-    correlation
+    deps.correlation
   );
   return { truncated, skipped };
 }
@@ -1365,6 +1439,30 @@ var CorrelateCycle = class {
   }
 };
 
+// src/internal/correlator.ts
+var import_node_crypto = require("crypto");
+var BASE = 36;
+var SEG_WIDTH = 4;
+var SEG_SPACE = BASE ** SEG_WIDTH;
+function seg(n) {
+  return n.toString(BASE).padStart(SEG_WIDTH, "0");
+}
+var defaultCorrelator = ({ state: state2, action: action2 }) => {
+  const s = state2.slice(0, SEG_WIDTH).toLowerCase();
+  const a = action2.slice(0, SEG_WIDTH).toLowerCase();
+  const ts = seg(Date.now() % SEG_SPACE);
+  const rnd = seg((0, import_node_crypto.randomInt)(SEG_SPACE));
+  return `${s}-${a}-${ts}${rnd}`;
+};
+function closeCorrelation(correlator, actor) {
+  return correlator({
+    state: "$close",
+    action: "close",
+    stream: "$close",
+    actor
+  });
+}
+
 // src/internal/drain-cycle.ts
 var import_node_crypto2 = require("crypto");
 
@@ -1755,9 +1853,12 @@ function computeBackoffDelay(retry, opts) {
 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;
+  const nonRetryable = error instanceof NonRetryableError;
+  const block2 = options.blockOnError && (nonRetryable || lease.retry >= options.maxRetries);
   if (block2)
-    logger.error(`Blocking ${lease.stream} after ${lease.retry} retries.`);
+    logger.error(
+      nonRetryable ? `Blocking ${lease.stream} on non-retryable error.` : `Blocking ${lease.stream} after ${lease.retry} retries.`
+    );
   const nextAttemptAt = !block2 && options.backoff ? Date.now() + computeBackoffDelay(lease.retry, options.backoff) : void 0;
   return {
     lease,
@@ -1907,7 +2008,6 @@ var block = (leases) => store2().block(leases);
 var subscribe = (streams) => store2().subscribe(streams);
 
 // src/internal/event-sourcing.ts
-var import_node_crypto3 = require("crypto");
 var import_act_patch = require("@rotorsoft/act-patch");
 async function snap(snapshot) {
   try {
@@ -1995,7 +2095,7 @@ async function load(me, stream, callback, asOf) {
   }
   return { event, state: state2, version, patches, snaps, cache_hit, replayed };
 }
-async function action(me, action2, target, payload, reactingTo, skipValidation = false) {
+async function action(me, action2, target, payload, reactingTo, skipValidation = false, correlator = defaultCorrelator) {
   const { stream, expectedVersion, actor } = target;
   if (!stream) throw new Error("Missing target stream");
   const validated = skipValidation ? payload : validate(action2, payload, me.actions[action2]);
@@ -2041,7 +2141,12 @@ async function action(me, action2, target, payload, reactingTo, skipValidation =
     data: skipValidation ? data : validate(name, data, me.events[name])
   }));
   const meta = {
-    correlation: reactingTo?.meta.correlation || (0, import_node_crypto3.randomUUID)(),
+    correlation: reactingTo?.meta.correlation || correlator({
+      action: action2,
+      state: me.name,
+      stream,
+      actor: target.actor
+    }),
     causation: {
       action: {
         name: action2,
@@ -2145,12 +2250,21 @@ var traced = (inner, exit, entry) => (async (...args) => {
   exit?.(result, ...args);
   return result;
 });
-function buildEs(logger) {
+function buildEs(logger, correlator = defaultCorrelator) {
+  const boundAction = (me, actionName, target, payload, reactingTo, skipValidation = false) => action(
+    me,
+    actionName,
+    target,
+    payload,
+    reactingTo,
+    skipValidation,
+    correlator
+  );
   if (logger.level !== "trace") {
     return {
       snap,
       load,
-      action,
+      action: boundAction,
       tombstone
     };
   }
@@ -2180,7 +2294,7 @@ function buildEs(logger) {
       );
     }),
     action: traced(
-      action,
+      boundAction,
       (snapshots, _me, _action, target) => {
         const committed = snapshots.filter((s) => s.event);
         if (committed.length) {
@@ -2288,7 +2402,8 @@ var Act = class {
     this._states = _states;
     this._batch_handlers = batchHandlers;
     this._scoped = options.scoped ? (fn) => scoped.run(options.scoped, fn) : (fn) => fn();
-    this._es = buildEs(this._logger);
+    this._correlator = options.correlator ?? defaultCorrelator;
+    this._es = buildEs(this._logger, this._correlator);
     this._cd = buildDrain(this._logger);
     this._handle = buildHandle({
       logger: this._logger,
@@ -2401,6 +2516,13 @@ var Act = class {
    * path keeps reading fresh `store()`/`cache()` per call, which matters for
    * tests that dispose and re-seed mid-suite. */
   _scoped;
+  /**
+   * Correlation-id generator for originating actions. Bound at
+   * construction from `options.correlator ?? defaultCorrelator`. The
+   * `do()` path passes this into the `_es.action` closure; close-cycle
+   * uses it via {@link closeCorrelation}.
+   */
+  _correlator;
   /** 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);
@@ -2876,13 +2998,81 @@ var Act = class {
    * @see {@link Store.reset} for the underlying store primitive
    * @see {@link settle} for the debounced full-catch-up loop
    */
-  async reset(streams) {
+  async reset(input) {
     return this._scoped(async () => {
-      const count = await store2().reset(streams);
+      const count = await store2().reset(input);
       if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
       return count;
     });
   }
+  /**
+   * Clear the blocked flag on streams without replaying their history.
+   *
+   * Use this to recover from a poison message after fixing the
+   * underlying issue — the stream resumes from the next event after the
+   * last successful ack, not from the beginning. Compare with
+   * {@link reset}, which rebuilds from event 0 (suitable for projection
+   * rebuilds, wrong for "I fixed the bug, please retry").
+   *
+   * Wraps `store().unblock(streams)` and raises the orchestrator's
+   * internal "needs drain" flag so a settled app picks up the now-free
+   * streams on the next cycle. Equivalent to calling `store().unblock(...)`
+   * directly, but `store().unblock(...)` alone leaves the flag
+   * untouched.
+   *
+   * @param streams - Stream names to unblock
+   * @returns Count of streams that were actually flipped (were blocked)
+   *
+   * @example Recover from a 4xx webhook after fixing the bug
+   * ```typescript
+   * await app.unblock(["webhooks-out-customer-42"]);
+   * // The stream resumes from the next event, not from zero.
+   * ```
+   *
+   * @see {@link Store.unblock} for the underlying store primitive
+   * @see {@link reset} for the rebuild-from-zero alternative
+   */
+  async unblock(input) {
+    return this._scoped(async () => {
+      const count = await store2().unblock(input);
+      if (count > 0 && this._reactive_events.size > 0) this._drain.arm();
+      return count;
+    });
+  }
+  /**
+   * Return every currently-blocked stream position. Convenience wrapper
+   * around `store().query_streams(cb, { blocked: true })` for the common
+   * "show me what's broken" operational query.
+   *
+   * Results are ordered by stream name, paginated by `limit` (default
+   * 100). Pass `after` to fetch the next page (keyset cursor on the
+   * stream name). For richer queries — including blocked + source
+   * filters, or full unblocked introspection — drop to
+   * `store().query_streams(...)` directly.
+   *
+   * @returns Array of {@link StreamPosition} for currently-blocked streams.
+   *
+   * @example Discover and recover
+   * ```typescript
+   * const blocked = await app.blocked_streams();
+   * console.table(blocked.map(({ stream, retry, error }) => ({ stream, retry, error })));
+   *
+   * // Operator investigates, then bulk-unblocks the family:
+   * await app.unblock({ stream: "^webhooks-out-" });
+   * ```
+   */
+  async blocked_streams(options) {
+    return this._scoped(async () => {
+      const positions = [];
+      await store2().query_streams(
+        (p) => {
+          positions.push(p);
+        },
+        { blocked: true, after: options?.after, limit: options?.limit }
+      );
+      return positions;
+    });
+  }
   /**
    * Bulk-update scheduling priority for streams matching `filter`.
    *
@@ -2961,12 +3151,14 @@ var Act = class {
     if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
     return this._scoped(async () => {
       await this.correlate({ limit: 1e3 });
+      const closeActor = { id: "$close", name: "close" };
       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
+        logger: this._logger,
+        correlation: closeCorrelation(this._correlator, closeActor)
       });
       this.emit("closed", result);
       return result;
@@ -3337,6 +3529,7 @@ function action_builder(state2) {
   InMemoryStore,
   InvariantError,
   LogLevels,
+  NonRetryableError,
   PackageSchema,
   QuerySchema,
   SNAP_EVENT,