@rotorsoft/act 1.32.26 → 1.32.28

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-QXW3JV2H.js";
+} from "./chunk-5FXT63KF.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -53,7 +53,7 @@ import {
   pii_split,
   pii_strip,
   sensitive
-} from "./chunk-XSG2NW4J.js";
+} from "./chunk-F7K7SIG6.js";
 
 // src/signals.ts
 process.once("SIGINT", async (arg) => {
@@ -81,10 +81,8 @@ var ALL_LANES = /* @__PURE__ */ Symbol("act-1103/all-lanes");
 function classify_registry(registry, states) {
   const statics = /* @__PURE__ */ new Map();
   const target_lanes = /* @__PURE__ */ new Map();
-  const reactive_events = /* @__PURE__ */ new Set();
   const event_to_lanes = /* @__PURE__ */ new Map();
   for (const [name, register] of Object.entries(registry.events)) {
-    if (register.reactions.size > 0) reactive_events.add(name);
     for (const reaction of register.reactions.values()) {
       if (typeof reaction.resolver === "function") {
         event_to_lanes.set(name, ALL_LANES);
@@ -122,7 +120,6 @@ function classify_registry(registry, states) {
   }
   return {
     static_targets: [...statics.values()],
-    reactive_events,
     event_to_state,
     event_to_lanes
   };
@@ -1135,6 +1132,10 @@ var CircuitBreaker = class {
   get failing() {
     return this._failures > 0;
   }
+  /** How long the store is left alone after a failure before a retry. */
+  get cooldown_ms() {
+    return this._cooldown_ms;
+  }
   /** Current state given the wall-clock `now`. */
   state(now) {
     if (this._opened_at === void 0) return "closed";
@@ -1279,7 +1280,7 @@ async function run_full_closes(full, target_map, deps, skipped) {
   }
   const safe = await partition_by_safety(
     stream_info,
-    deps.reactive_events_size,
+    deps.reactive,
     skipped,
     deps.probe_page_size ?? SAFETY_PROBE_PAGE_SIZE,
     deps.catch_up_correlation
@@ -1316,8 +1317,8 @@ async function run_full_closes(full, target_map, deps, skipped) {
   );
 }
 async function run_windowed_closes(windowed, deps, skipped) {
-  const checkpoint = deps.reactive_events_size > 0 ? await deps.catch_up_correlation(Number.MAX_SAFE_INTEGER) : -1;
-  const min_at = deps.reactive_events_size > 0 ? await probe_min_watermarks(
+  const checkpoint = deps.reactive ? await deps.catch_up_correlation(Number.MAX_SAFE_INTEGER) : -1;
+  const min_at = deps.reactive ? await probe_min_watermarks(
     windowed.map((t) => t.stream),
     deps.probe_page_size ?? SAFETY_PROBE_PAGE_SIZE,
     checkpoint
@@ -1405,8 +1406,8 @@ async function scan_stream_heads(streams) {
   }
   return out;
 }
-async function partition_by_safety(stream_info, reactive_events_size, skipped, page_size, catch_up_correlation2) {
-  if (reactive_events_size === 0) return [...stream_info.keys()];
+async function partition_by_safety(stream_info, reactive, skipped, page_size, catch_up_correlation2) {
+  if (!reactive) return [...stream_info.keys()];
   let needed = -1;
   for (const info of stream_info.values())
     needed = Math.max(needed, info.max_id);
@@ -2685,20 +2686,24 @@ function fetch_failure_policy(registry) {
     }
   return { blockOnError, maxRetries };
 }
-function resolver_failed(lease, { error, options }) {
-  log().error(error);
-  const block2 = options.blockOnError && lease.retry >= options.maxRetries;
+function finalize(lease, handled, at, error, options, logger, failed_at) {
+  if (!error) return { lease, handled, acked_at: at };
+  logger.error(error);
+  const non_retryable = error instanceof NonRetryableError;
+  const block2 = options.blockOnError && (non_retryable || lease.retry >= options.maxRetries);
+  if (block2)
+    logger.error(
+      non_retryable ? `Blocking ${lease.stream} on non-retryable error.` : `Blocking ${lease.stream} after ${lease.retry} retries.`
+    );
+  const next_attempt_at = block2 ? void 0 : Date.now() + compute_backoff_delay(lease.retry, options.backoff ?? DEFAULT_BACKOFF);
   return {
     lease,
-    handled: 0,
-    acked_at: lease.at,
-    error,
-    ...block2 ? { block: true } : {
-      next_attempt_at: Date.now() + compute_backoff_delay(
-        lease.retry,
-        options.backoff ?? DEFAULT_BACKOFF
-      )
-    }
+    handled,
+    acked_at: at,
+    error: error.message,
+    block: block2,
+    next_attempt_at,
+    failed_at
   };
 }
 function warn_misrouted(seen, stream, handler, event) {
@@ -2746,7 +2751,9 @@ async function run_drain_cycle(deps, cycle) {
           resolved = dynamic ? resolver(event) : resolver;
         } catch (error) {
           failed ??= {
-            error: `Resolver of reaction "${reaction.handler.name}" threw on ${String(event.name)} #${event.id} (stream "${event.stream}"): ${String(error)}`,
+            error: new Error(
+              `Resolver of reaction "${reaction.handler.name}" threw on ${String(event.name)} #${event.id} (stream "${event.stream}"): ${String(error)}`
+            ),
             options: reaction.options
           };
           return false;
@@ -2768,23 +2775,29 @@ async function run_drain_cycle(deps, cycle) {
     leased.map((lease) => {
       const entry = fetch_map.get(lease.stream);
       if (entry.fetch.error !== void 0) {
-        const error = `Fetch failed for ${lease.stream}: ${entry.fetch.error}`;
-        log().error(error);
         const policy = fetch_failure_policy(registry);
-        const block2 = !store_failing && policy.blockOnError && lease.retry >= policy.maxRetries;
-        const failed = {
-          lease,
-          handled: 0,
-          acked_at: lease.at,
-          error,
-          ...block2 ? { block: true } : {
-            next_attempt_at: Date.now() + compute_backoff_delay(lease.retry, DEFAULT_BACKOFF)
-          }
-        };
-        return Promise.resolve(failed);
+        return Promise.resolve(
+          finalize(
+            lease,
+            0,
+            lease.at,
+            new Error(`Fetch failed for ${lease.stream}: ${entry.fetch.error}`),
+            store_failing ? { ...policy, blockOnError: false } : policy,
+            deps.logger
+          )
+        );
       }
       if (entry.failed)
-        return Promise.resolve(resolver_failed(lease, entry.failed));
+        return Promise.resolve(
+          finalize(
+            lease,
+            0,
+            lease.at,
+            entry.failed.error,
+            entry.failed.options,
+            deps.logger
+          )
+        );
       const at = entry.fetch.events.at(-1)?.id || fetch_window_at;
       const { payloads } = entry;
       const exhausted = budget_exhausted(
@@ -2823,18 +2836,23 @@ var EMPTY_DRAIN = {
   acked: [],
   blocked: []
 };
+var RETRY = "";
 var DrainController = class {
   _armed = false;
   _locked = false;
   _ratio = 0.5;
   /**
-   * Local wake at the earliest parked (backoff or defer) visit; the schedule
-   * itself is persisted. On an idle app nothing else would drain it. A due
-   * entry stays until handled or until a later pass claims nothing.
+   * Local wake at the earliest parked (backoff or defer) visit, or at the
+   * lease expiry after a failed pass (the {@link RETRY} key); the schedule
+   * itself is persisted. On an idle app nothing else would drain it. It
+   * drains until a pass leases nothing, and an entry stays until handled or
+   * until a later pass claims nothing.
    */
   _defer = new DeferTimer(() => {
     this._armed = true;
-    void this._deps.run_scoped(() => this.drain());
+    void this._deps.run_scoped(async () => {
+      while ((await this.drain()).leased.length > 0) ;
+    });
   });
   _worker;
   _misrouted = /* @__PURE__ */ new Set();
@@ -2931,10 +2949,12 @@ var DrainController = class {
       if (acked.length) this._deps.on_acked(acked);
       if (closeable.length) await this._deps.on_close(closeable);
       this._deps.breaker.passed();
-      const has_errors = handled.some(({ error }) => error);
-      if (!acked.length && !blocked.length && !has_errors) this._armed = false;
       return { fetched, leased, acked, blocked };
     } catch (error) {
+      this._defer.set(
+        RETRY,
+        Date.now() + Math.max(leaseMillis, this._deps.breaker.cooldown_ms)
+      );
       this._deps.breaker.failed(Date.now(), error);
       return EMPTY_DRAIN;
     } finally {
@@ -3058,7 +3078,8 @@ var SettleLoop = class {
   /**
    * Schedule a settle pass. Multiple calls inside the debounce window
    * coalesce into one cycle. The cycle runs correlate→drain in a loop
-   * until no progress is made (no new subscriptions, no acks, no blocks)
+   * until no progress is made (no new subscriptions, no events read, no
+   * streams leased)
    * or `maxPasses` is reached, then emits the `"settled"` lifecycle event
    * via {@link SettleDeps.on_settled}.
    */
@@ -3098,7 +3119,7 @@ var SettleLoop = class {
             acked: [...settled_drain.acked, ...drain.acked],
             blocked: [...settled_drain.blocked, ...drain.blocked]
           } : drain;
-          const made_progress = subscribed > 0 || drain.acked.length > 0 || drain.blocked.length > 0 || last_id > after_before;
+          const made_progress = subscribed > 0 || drain.leased.length > 0 || last_id > after_before;
           if (!made_progress) break;
         }
         if (settled_drain) this._deps.on_settled(settled_drain);
@@ -3135,26 +3156,6 @@ var SettleLoop = class {
 };
 
 // src/builders/reaction-builder.ts
-function finalize(lease, handled, at, error, options, logger, failed_at) {
-  if (!error) return { lease, handled, acked_at: at };
-  logger.error(error);
-  const non_retryable = error instanceof NonRetryableError;
-  const block2 = options.blockOnError && (non_retryable || lease.retry >= options.maxRetries);
-  if (block2)
-    logger.error(
-      non_retryable ? `Blocking ${lease.stream} on non-retryable error.` : `Blocking ${lease.stream} after ${lease.retry} retries.`
-    );
-  const next_attempt_at = block2 ? void 0 : Date.now() + compute_backoff_delay(lease.retry, options.backoff ?? DEFAULT_BACKOFF);
-  return {
-    lease,
-    handled,
-    acked_at: at,
-    error: error.message,
-    block: block2,
-    next_attempt_at,
-    failed_at
-  };
-}
 function build_handle(deps) {
   const { logger, reaction_scope } = deps;
   return async (lease, payloads) => {
@@ -3264,7 +3265,8 @@ var Act = class {
   _breaker;
   _listen;
   _drain;
-  _reactive_events;
+  /** Whether any event has a reaction; nothing arms without one. */
+  _reactive;
   _drain_controllers;
   _correlate;
   _settle;
@@ -3394,7 +3396,7 @@ var Act = class {
     });
     this._handle_batch = build_handle_batch(this._logger);
     const classification = classify_registry(this.registry, this._states);
-    this._reactive_events = classification.reactive_events;
+    this._reactive = classification.event_to_lanes.size > 0;
     this._event_to_state = classification.event_to_state;
     this._event_to_lanes = classification.event_to_lanes;
     this._listen = options.listen !== false;
@@ -3501,9 +3503,8 @@ var Act = class {
       declared_lanes: new Set(this._declared_lanes),
       // Built after the controllers, so their keys are the active lanes.
       shard: this._drain_controllers.size < this._declared_lanes.length ? [...this._drain_controllers.keys()] : void 0,
-      on_init: () => {
-        if (this._drain && this._reactive_events.size > 0) this._arm_all();
-      },
+      // Only reached on a draining app: writer-only ones never correlate.
+      on_init: () => this._arm_all(),
       on_init_async: this._drain ? () => this._seed_persisted_defers() : void 0
     });
   }
@@ -3600,7 +3601,7 @@ var Act = class {
   }
   /** Failures are logged, never thrown: `notify` is a hint. */
   async _wire_notify(s) {
-    if (this._reactive_events.size === 0) return void 0;
+    if (!this._reactive) return void 0;
     if (!s.notify) return void 0;
     if (!this._listen) return void 0;
     try {
@@ -3660,46 +3661,6 @@ var Act = class {
    * console.log(snapshots[0].state.count); // Current count after increment
    * ```
    *
-   * @example With error handling
-   * ```typescript
-   * try {
-   *   await app.do(
-   *     "withdraw",
-   *     { stream: "account-123", actor: { id: "user1", name: "Alice" } },
-   *     { amount: 1000 }
-   *   );
-   * } catch (error) {
-   *   if (error instanceof InvariantError) {
-   *     console.error("Business rule violated:", error.description);
-   *   } else if (error instanceof ConcurrencyError) {
-   *     console.error("Concurrent modification detected, retry...");
-   *   } else if (error instanceof ValidationError) {
-   *     console.error("Invalid payload:", error.details);
-   *   }
-   * }
-   * ```
-   *
-   * @example Reaction triggering another action (reactingTo auto-injected)
-   * ```typescript
-   * const app = act()
-   *   .withState(Order)
-   *   .withState(Inventory)
-   *   .on("OrderPlaced")
-   *     .do(async function reduceInventory(event, _stream, app) {
-   *       // Inside reaction handlers, reactingTo is auto-injected when omitted.
-   *       // The triggering event is used by default, maintaining the correlation chain.
-   *       await app.do(
-   *         "reduceStock",
-   *         { stream: "inventory-1", actor: { id: "sys", name: "system" } },
-   *         { amount: event.data.items.length }
-   *       );
-   *       // To use a different correlation, pass reactingTo explicitly:
-   *       // await app.do("reduceStock", target, payload, { reactingTo: customEvent });
-   *     })
-   *     .to("inventory-1")
-   *   .build();
-   * ```
-   *
    * @see {@link Target} for target structure
    * @see {@link Snapshot} for return value structure
    * @see {@link ValidationError}, {@link InvariantError}, {@link ConcurrencyError}
@@ -3715,10 +3676,9 @@ var Act = class {
         payload,
         do_options
       );
-      if (this._reactive_events.size > 0)
-        this._arm_for_event_names(
-          snapshots.map((s) => s.event.name)
-        );
+      this._arm_for_event_names(
+        snapshots.map((s) => s.event.name)
+      );
       this.emit("committed", snapshots);
       return snapshots;
     });
@@ -3765,26 +3725,6 @@ var Act = class {
    * console.log(`Found ${count} events from ${first?.id} to ${last?.id}`);
    * ```
    *
-   * @example Query specific event types
-   * ```typescript
-   * const { count } = await app.query(
-   *   { name: "UserCreated", limit: 100 },
-   *   (event) => {
-   *     console.log("User created:", event.data.email);
-   *   }
-   * );
-   * ```
-   *
-   * @example Query events in time range
-   * ```typescript
-   * const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
-   * const { count } = await app.query({
-   *   created_after: yesterday,
-   *   stream: "user-123"
-   * });
-   * console.log(`User had ${count} events in last 24 hours`);
-   * ```
-   *
    * @see {@link query_array} for loading events into memory
    */
   async query(query, callback) {
@@ -3816,14 +3756,6 @@ var Act = class {
    * events.forEach(event => console.log(event.name, event.data));
    * ```
    *
-   * @example Get recent events
-   * ```typescript
-   * const recent = await app.query_array({
-   *   stream: "user-123",
-   *   limit: 10
-   * });
-   * ```
-   *
    * @see {@link query} for large result sets
    */
   async query_array(query) {
@@ -3894,12 +3826,6 @@ var Act = class {
    * await app.drain();
    * ```
    *
-   * @example In production, prefer settle()
-   * ```typescript
-   * await app.do("CreateItem", target, input);
-   * app.settle(); // debounced correlate→drain, emits "settled"
-   * ```
-   *
    * @see {@link settle} for debounced correlate→drain with lifecycle events
    * @see {@link correlate} for dynamic stream discovery
    * @see {@link start_correlations} for automatic correlation
@@ -3911,6 +3837,7 @@ var Act = class {
     return this._scoped(() => this._drain_all(options));
   }
   _arm_all() {
+    if (!this._reactive) return;
     this._correlate.arm();
     for (const c of this._drain_controllers.values()) c.arm();
   }
@@ -3966,37 +3893,20 @@ var Act = class {
    * on reaction resolvers. It then registers these streams so they'll be picked up by
    * the next drain cycle.
    *
-   * @param query - Query filter to scan for new correlations
    * @param query - Scan filter — see {@link Query} for fields (typically
    *   `{ after: <event-id>, limit: <count> }`)
-   * @returns Object with newly leased streams and last scanned event ID
+   * @returns The number of newly subscribed streams and the last scanned event id
    *
    * @example Manual correlation
    * ```typescript
    * // Scan for new streams
-   * const { leased, last_id } = await app.correlate({ after: 0, limit: 100 });
-   * console.log(`Found ${leased.length} new streams`);
+   * const { subscribed, last_id } = await app.correlate({ after: 0, limit: 100 });
+   * console.log(`Subscribed ${subscribed} new streams`);
    *
    * // Save last_id for next scan
    * await saveCheckpoint(last_id);
    * ```
    *
-   * @example Dynamic stream creation
-   * ```typescript
-   * const app = act()
-   *   .withState(User)
-   *   .withState(UserStats)
-   *   .on("UserLoggedIn")
-   *     .do(async (event) => ["incrementLoginCount", {}])
-   *     .to((event) => ({
-   *       target: `stats-${event.stream}` // Dynamic target per user
-   *     }))
-   *   .build();
-   *
-   * // Discover stats streams as users log in
-   * await app.correlate();
-   * ```
-   *
    * @see {@link start_correlations} for automatic periodic correlation
    * @see {@link stop_correlations} to stop automatic correlation
    */
@@ -4009,8 +3919,7 @@ var Act = class {
     if (!this._drain) return { subscribed: 0, last_id: -1, scanned: false };
     return this._scoped(async () => {
       const { subscribed, last_id, marked, scanned } = await this._correlate.correlate(query, lease);
-      if ((subscribed > 0 || marked > 0) && this._reactive_events.size > 0)
-        this._arm_all();
+      if (subscribed > 0 || marked > 0) this._arm_all();
       if (subscribed > 0) this._on_discovered?.(subscribed);
       return { subscribed, last_id, scanned };
     });
@@ -4102,12 +4011,6 @@ var Act = class {
    * app.settle({ eventLimit: 1000 });   // emits "settled" when fully replayed
    * ```
    *
-   * @example Rebuild a projection (tests / scripts)
-   * ```typescript
-   * await app.reset(["my-projection"]);
-   * await app.drain({ eventLimit: 1000 });   // small streams: one pass is enough
-   * ```
-   *
    * @see {@link Store.reset} for the underlying store primitive
    * @see {@link settle} for the debounced full-catch-up loop
    */
@@ -4116,7 +4019,7 @@ var Act = class {
       const count = await store().reset(input);
       for (const handler of this._batch_handlers.values())
         handler[FOLD_RESET]?.();
-      if (count > 0 && this._reactive_events.size > 0) this._arm_all();
+      if (count > 0) this._arm_all();
       return count;
     });
   }
@@ -4150,7 +4053,7 @@ var Act = class {
   async unblock(input) {
     return this._scoped(async () => {
       const count = await store().unblock(input);
-      if (count > 0 && this._reactive_events.size > 0) this._arm_all();
+      if (count > 0) this._arm_all();
       return count;
     });
   }
@@ -4186,11 +4089,6 @@ var Act = class {
    * await cache().clear();   // operator's responsibility
    * ```
    *
-   * @example Copy one store into another
-   * ```typescript
-   * await app.restore(pg, {}, sqlite);
-   * ```
-   *
    * @see {@link Store.restore} for the underlying driver-pattern primitive.
    */
   async restore(source, opts = {}, sink) {
@@ -4329,16 +4227,6 @@ var Act = class {
    * await app.prioritize({ stream: "^proj-orders$", stream_exact: false }, 10);
    * ```
    *
-   * @example Drop all audit projections to background
-   * ```typescript
-   * await app.prioritize({ source: "^audit-" }, -5);
-   * ```
-   *
-   * @example Reset everyone to default
-   * ```typescript
-   * await app.prioritize({}, 0);
-   * ```
-   *
    * @see {@link Store.prioritize} for the underlying primitive
    * @see {@link claim} for how priority biases scheduling
    */
@@ -4349,7 +4237,7 @@ var Act = class {
   async _run_close(targets) {
     const close_actor = { id: "$close", name: "close" };
     const result = await run_close_cycle(targets, {
-      reactive_events_size: this._reactive_events.size,
+      reactive: this._reactive,
       catch_up_correlation: (until) => catch_up_correlation(
         this._correlate,
         (limit) => this.correlate({ limit }),
@@ -4402,27 +4290,6 @@ var Act = class {
    *   { stream: "order-456" },
    * ]);
    * ```
-   *
-   * @example Close with restart (state loaded automatically after guard)
-   * ```typescript
-   * await app.close([
-   *   { stream: "counter-1", restart: true },
-   *   { stream: "counter-2" },  // tombstoned
-   * ]);
-   * ```
-   *
-   * @example Windowed close — keep the last 180 days of real events
-   * ```typescript
-   * const cutoff = new Date();
-   * cutoff.setDate(cutoff.getDate() - 180);
-   * await app.close([
-   *   {
-   *     stream: "ledger-acme",
-   *     before: cutoff,
-   *     archive: async () => { await archiveToS3("ledger-acme", cutoff); },
-   *   },
-   * ]);
-   * ```
    */
   async close(targets) {
     if (!targets.length) return { truncated: /* @__PURE__ */ new Map(), skipped: [] };
@@ -4434,7 +4301,8 @@ var Act = class {
    * Call this after `app.do()` (or `app.reset()`) to schedule a background
    * drain. Multiple rapid calls within the debounce window are coalesced
    * into a single cycle. Runs correlate→drain in a loop until a pass makes
-   * no progress — no new subscriptions, no acks, no blocks — then emits
+   * no progress — no new subscriptions, no events read, no streams leased —
+   * then emits
    * the `"settled"` lifecycle event. This means a single `settle()` call
    * fully catches up paginated streams (e.g. after `reset()` on a long
    * projection) without forcing callers to loop.