@rotorsoft/act 1.22.6 → 1.22.7

package/dist/index.cjs

@@ -703,6 +703,10 @@ var InMemoryStream = class {
   get leased_until() {
     return this._leased_until;
   }
+  /** Persisted next-visit time (#1090/#1221), or undefined when no active defer. */
+  get deferred_at() {
+    return this._deferred_at;
+  }
   /**
    * Attempt to lease this stream for processing.
    * @param lease - The lease request.
@@ -1297,7 +1301,8 @@ var InMemoryStore = class {
         priority: s.priority,
         leased_by: s.leased_by,
         leased_until: s.leased_until,
-        lane: s.lane
+        lane: s.lane,
+        deferred_at: s.deferred_at
       });
       count++;
       if (count >= limit) break;
@@ -2924,6 +2929,16 @@ var CorrelateCycle = class {
   _has_dynamic_resolvers;
   _cd;
   _on_init;
+  /**
+   * Async cold-start hook (#1221). Runs once, after the sync `on_init`,
+   * inside the same `init()` await. The orchestrator uses it to re-seed the
+   * process-local defer timers from the store's persisted `deferred_at` so
+   * an idle deferred stream re-arms its drain across a restart. Kept
+   * separate from `on_init` because seeding is an async store read; `init`
+   * already awaits, so folding it in here preserves the "runs exactly once"
+   * 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
@@ -2932,7 +2947,7 @@ var CorrelateCycle = class {
    * `_scoped` (identity for a non-scoped Act), so it's required.
    */
   _run_scoped;
-  constructor(registry, static_targets, has_dynamic_resolvers, cd, maxSubscribedStreams, on_init, run_scoped) {
+  constructor(registry, static_targets, has_dynamic_resolvers, cd, maxSubscribedStreams, on_init, run_scoped, on_init_async) {
     this._subscribed = new LruSet(maxSubscribedStreams);
     this._registry = registry;
     this._static_targets = static_targets;
@@ -2940,6 +2955,7 @@ var CorrelateCycle = class {
     this._cd = cd;
     this._on_init = on_init;
     this._run_scoped = run_scoped;
+    this._on_init_async = on_init_async;
   }
   /** Last correlated event id. */
   get checkpoint() {
@@ -2961,6 +2977,7 @@ var CorrelateCycle = class {
     for (const { stream } of this._static_targets) {
       this._subscribed.add(stream);
     }
+    await this._on_init_async?.();
   }
   /**
    * Discover dynamic-resolver targets in the events past the checkpoint
@@ -3834,6 +3851,22 @@ var DrainController = class {
   arm() {
     this._armed = true;
   }
+  /**
+   * Re-seed a persisted defer schedule into the process-local timer at cold
+   * start (#1221). The `_defer` map lives in worker memory and is empty
+   * after a restart; a stream deferred to a future due-time (e.g. an idle
+   * autoclose aggregate) is durable in the store's `deferred_at` but has
+   * nothing in memory to re-arm the drain at the due-time. The orchestrator
+   * reads the persisted `deferred_at` for this controller's lane and calls
+   * this to park the stream + (re)schedule the shared wake — so the drain
+   * re-arms at the due-time with no intervening commit. `schedule()`
+   * collapses many seeds into one timer, so callers may seed in a loop and
+   * let the earliest due-time win.
+   */
+  seed_defer(stream, at) {
+    this._defer.set(stream, at);
+    this._defer.schedule();
+  }
   /** Read-only flag — true while a commit / reset is unprocessed. */
   get armed() {
     return this._armed;
@@ -4382,6 +4415,7 @@ var Act = class {
     this._drain = options.drain !== false;
     this._breaker = this._build_breaker(options);
     this._drain_controllers = this._build_drain_controllers(options, lanes);
+    this._advise_orphaned_lanes(options, lanes);
     this._audit_deps = this._build_audit_deps();
     this._correlate = this._build_correlate(options, classification);
     this._settle = this._build_settle(options);
@@ -4474,6 +4508,31 @@ var Act = class {
     }
     return controllers;
   }
+  /**
+   * Orphaned-lane startup advisory (#1220). When `onlyLanes` is set, this
+   * instance builds a controller only for its slice of the declared lane
+   * universe — every OTHER declared lane's stream is persisted (correlate
+   * subscribes all static targets regardless of `onlyLanes`) but never
+   * claimed here. If no peer worker deploys with those lanes in ITS
+   * `onlyLanes`, their reactions accumulate forever, silently. A single
+   * process can't verify the cluster invariant `∪ onlyLanes ⊇ declared
+   * lanes`, so we surface the per-instance signal — "these declared lanes
+   * have no controller here" — the same way the deprecated-event advisory
+   * surfaces legacy events. No advisory when `onlyLanes` is unset (every
+   * lane gets a controller) or covers every declared lane.
+   */
+  _advise_orphaned_lanes(options, lanes) {
+    if (!options.onlyLanes || options.onlyLanes.length === 0) return;
+    const active = new Set(this._drain_controllers.keys());
+    const orphaned = ["default", ...lanes.map((l) => l.name)].filter(
+      (name) => !active.has(name)
+    );
+    if (orphaned.length === 0) return;
+    const list = orphaned.map((name) => `"${name}"`).join(", ");
+    this._logger.info(
+      `Act declared ${orphaned.length} orphaned lane(s) on this instance: ${list}. onlyLanes excludes them, so no DrainController claims their streams here \u2014 their reactions accumulate un-drained unless a peer worker deploys with these lanes in its onlyLanes. Ensure the cluster invariant holds: the union of every worker's onlyLanes must cover every declared lane. See docs/docs/guides/production-checklist.md \xA7 Sizing lanes.`
+    );
+  }
   /**
    * Audit deps bag. Snapshotted after registry classification and
    * drain-controller build so the audit module sees the finalized lane
@@ -4487,7 +4546,14 @@ var Act = class {
       event_to_state: this._event_to_state,
       states: this._states,
       known_events: new Set(this._event_to_state.keys()),
-      declared_lanes: new Set(this._drain_controllers.keys()),
+      // The DECLARED lane universe — the implicit "default" plus every
+      // `.withLane(...)` name — NOT `_drain_controllers.keys()` (#1224).
+      // An `onlyLanes`-filtered instance builds a controller only for its
+      // slice of lanes, so keying off the active controller set would flag
+      // a stream correctly assigned to an excluded-but-declared lane (one
+      // another worker drains) as `unknown-lane`. The audit reports what's
+      // structurally routable across the cluster, not what this process runs.
+      declared_lanes: /* @__PURE__ */ new Set(["default", ...this._lanes.map((l) => l.name)]),
       routed_events: new Set(this._event_to_lanes.keys())
     };
   }
@@ -4508,9 +4574,36 @@ var Act = class {
       },
       // Re-scope the background `start_correlations` timer so its
       // correlate resolves the scoped ports, not the singleton (#1191).
-      this._scoped
+      this._scoped,
+      // Cold-start defer re-seed (#1221). Skipped on writer-only instances
+      // (`drain: false`) — they run no local controllers to re-arm.
+      this._drain ? () => this._seed_persisted_defers() : void 0
     );
   }
+  /**
+   * Re-seed every active lane controller's process-local defer timer from
+   * the store's persisted `deferred_at` (#1221). Runs once at cold start,
+   * inside `CorrelateCycle.init`, after static targets are subscribed.
+   *
+   * The defer timer is worker memory: empty after a restart. A stream
+   * deferred to a future due-time (the classic case: an idle autoclose
+   * aggregate that deferred its terminal close) is durable in the store but
+   * has nothing in memory to re-arm the drain — the controller disarms on
+   * the first empty claim and, since the aggregate is idle, no commit ever
+   * re-arms it. Reading the persisted schedule and seeding the owning lane's
+   * timer restores the wake, so the close fires at the due-time.
+   *
+   * Streams whose lane has no controller on this instance (excluded by
+   * `onlyLanes`) are skipped — a peer worker owns that lane's timer.
+   */
+  async _seed_persisted_defers() {
+    const now = Date.now();
+    await store2().query_streams((pos) => {
+      if (pos.deferred_at === void 0 || pos.deferred_at <= now) return;
+      const controller = this._drain_controllers.get(pos.lane ?? "default");
+      controller?.seed_defer(pos.stream, pos.deferred_at);
+    });
+  }
   /** Settle loop driving correlate + drain to quiescence. */
   _build_settle(options) {
     return new SettleLoop(