@rotorsoft/act 1.32.10 → 1.32.12

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-F4F5AKM3.js";
+} from "./chunk-UVFP2BQ3.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -1589,7 +1589,6 @@ var CorrelateCycle = class {
   _armed = true;
   /** In-flight init, memoized for single-flight and cleared on failure. */
   _init_promise;
-  _timer = void 0;
   // Dynamically discovered targets → what each was last subscribed at,
   // bounded by `maxSubscribedStreams`. The static half lives in
   // `_static_subscriptions` below, which is deliberately not evictable.
@@ -1633,14 +1632,6 @@ var CorrelateCycle = class {
    * guarantee without a second gate on the Act side.
    */
   _on_init_async;
-  /**
-   * Scope runner (#1191). The periodic `start_polling` timer fires
-   * outside any caller frame, so its `correlate()` must be re-wrapped in
-   * the Act's `_scoped` bag or `store()`/`cache()` resolve to the
-   * singleton for a scoped Act. The orchestrator always threads its
-   * `_scoped` (identity for a non-scoped Act), so it's required.
-   */
-  _run_scoped;
   /**
    * Tail re-scan window applied to the cold-start checkpoint (ACT-1207).
    * See {@link DEFAULT_COLD_START_BACK_SCAN}. Constructor arg (not a
@@ -1661,7 +1652,6 @@ var CorrelateCycle = class {
     cd,
     max_subscribed_streams,
     declared_lanes,
-    run_scoped,
     on_init,
     on_init_async,
     cold_start_back_scan = DEFAULT_COLD_START_BACK_SCAN,
@@ -1675,7 +1665,6 @@ var CorrelateCycle = class {
     this._static_targets = static_targets;
     this._cd = cd;
     this._on_init = on_init;
-    this._run_scoped = run_scoped;
     this._on_init_async = on_init_async;
     this._cold_start_back_scan = cold_start_back_scan;
   }
@@ -1923,33 +1912,6 @@ var CorrelateCycle = class {
     this._armed = found === query.limit;
     return { subscribed: 0, last_id, marked: 0, scanned: true };
   }
-  /**
-   * Start a periodic correlation worker. Returns false if one is already
-   * running. Errors from `correlate()` are routed through `log()` so they
-   * land in the configured logger (the timer keeps running on failure).
-   */
-  start_polling(query = {}, frequency = 1e4, callback) {
-    if (this._timer) return false;
-    const limit = query.limit || 100;
-    this._timer = setInterval(
-      () => this._run_scoped(() => {
-        this.arm();
-        return this.correlate(
-          {
-            ...query,
-            after: this._checkpoint,
-            limit
-          },
-          true
-        );
-      }).then((result) => {
-        if (callback && result.subscribed) callback(result.subscribed);
-      }).catch((err) => log().error(err)),
-      frequency
-    );
-    return true;
-  }
-  /** Stop the periodic correlation worker. Idempotent. */
   /**
    * Hand the correlation lease back early.
    *
@@ -1980,12 +1942,6 @@ var CorrelateCycle = class {
       );
     }
   }
-  stop_polling() {
-    if (this._timer) {
-      clearInterval(this._timer);
-      this._timer = void 0;
-    }
-  }
 };
 
 // src/internal/correlator.ts
@@ -3488,6 +3444,10 @@ var Act = class {
   _correlate;
   /** Debounced correlate→drain catch-up loop. */
   _settle;
+  /** Timer behind {@link start_correlations}. */
+  _poll;
+  /** The deprecated `start_correlations` callback, while the poll runs. */
+  _on_discovered;
   /**
    * Disposer for the cross-process notify subscription, set up eagerly
    * during construction. Held as a promise because the subscription
@@ -3897,9 +3857,6 @@ var Act = class {
       on_init: () => {
         if (this._drain && this._reactive_events.size > 0) this._arm_all();
       },
-      // Re-scope the background `start_correlations` timer so its
-      // correlate resolves the scoped ports, not the singleton (#1191).
-      run_scoped: this._scoped,
       // Cold-start defer re-seed (#1221). Skipped on writer-only instances
       // (`drain: false`) — they run no local controllers to re-arm.
       on_init_async: this._drain ? () => this._seed_persisted_defers() : void 0
@@ -4489,86 +4446,63 @@ var Act = class {
       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) this._on_discovered?.(subscribed);
       return { subscribed, last_id, scanned };
     });
   }
   /**
-   * Starts automatic periodic correlation worker for discovering new streams.
+   * Starts a background poll that settles on a timer: each tick looks for
+   * new events, subscribes the streams their reactions target, and drains
+   * them.
+   *
+   * Use it when this process can miss commits — another process writes to a
+   * store without `notify`, or a notification is lost. It is the safety net
+   * under `notify`: a missed wakeup costs at most one `frequency` of latency.
+   *
+   * Only one poll runs per Act instance. On a writer-only instance
+   * (`drain: false`) each tick is a no-op, like `settle()`.
+   *
+   * @param query - Only `limit` is used: the most events each correlate pass
+   *   reads (default 100). The scan always starts at the correlation
+   *   checkpoint, so `after` is ignored.
+   * @param frequency - Milliseconds between ticks (default: 10000)
+   * @param callback - Called with the number of newly subscribed streams
+   *   after each correlate pass that found some.
+   *   @deprecated Listen to the `"settled"` lifecycle event instead.
+   * @returns `true` if the poll started, `false` if one is already running
    *
-   * The correlation worker runs in the background, scanning for new events and identifying
-   * new target streams based on reaction resolvers. It maintains a sliding window that
-   * advances with each scan, ensuring all events are eventually correlated.
-   *
-   * This is useful for dynamic stream creation patterns where you don't know all streams
-   * upfront - they're discovered as events arrive.
-   *
-   * **Note:** Only one correlation worker can run at a time per Act instance.
-   *
-   * @param query - Query filter for correlation scans — see {@link Query}
-   *   (typically `{ after: -1, limit: 100 }`)
-   * @param frequency - Correlation frequency in milliseconds (default: 10000)
-   * @param callback - Optional callback invoked with newly discovered streams
-   * @returns `true` if worker started, `false` if already running
-   *
-   * @example Start automatic correlation
+   * @example
    * ```typescript
-   * // Start correlation worker scanning every 5 seconds
-   * app.start_correlations(
-   *   { after: 0, limit: 100 },
-   *   5000,
-   *   (leased) => {
-   *     console.log(`Discovered ${leased.length} new streams`);
-   *   }
-   * );
-   *
-   * // Later, stop it
+   * app.start_correlations({ limit: 100 }, 5000);
+   * // later
    * app.stop_correlations();
    * ```
    *
-   * @example With checkpoint persistence
-   * ```typescript
-   * // Load last checkpoint
-   * const lastId = await loadCheckpoint();
-   *
-   * app.start_correlations(
-   *   { after: lastId, limit: 100 },
-   *   10000,
-   *   async (leased) => {
-   *     // Save checkpoint for next restart
-   *     if (leased.length) {
-   *       const maxId = Math.max(...leased.map(l => l.at));
-   *       await saveCheckpoint(maxId);
-   *     }
-   *   }
-   * );
-   * ```
-   *
-   * @see {@link correlate} for manual one-time correlation
-   * @see {@link stop_correlations} to stop the worker
+   * @see {@link settle} for what each tick runs
+   * @see {@link stop_correlations} to stop the poll
    */
   start_correlations(query = {}, frequency = 1e4, callback) {
-    const started = this._correlate.start_polling(query, frequency, callback);
-    return started;
+    if (this._poll) return false;
+    this._on_discovered = callback;
+    const correlate = { limit: query.limit || 100 };
+    this._poll = setInterval(() => {
+      this._correlate.arm();
+      this.settle({ debounceMs: 0, correlate });
+    }, frequency);
+    return true;
   }
   /**
-   * Stops the automatic correlation worker.
-   *
-   * Call this to stop the background correlation worker started by {@link start_correlations}.
-   * This is automatically called when the Act instance is disposed.
-   *
-   * @example
-   * ```typescript
-   * // Start correlation
-   * app.start_correlations();
-   *
-   * // Later, stop it
-   * app.stop_correlations();
-   * ```
+   * Stops the poll started by {@link start_correlations}. Idempotent, and
+   * called by `shutdown()`.
    *
    * @see {@link start_correlations}
    */
   stop_correlations() {
-    this._correlate.stop_polling();
+    if (this._poll) {
+      clearInterval(this._poll);
+      this._poll = void 0;
+    }
+    this._on_discovered = void 0;
     void this._scoped(() => this._correlate.release_correlation());
   }
   /**