@rotorsoft/act 1.4.0 → 1.5.0

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-XKCTGUW2.js";
+} from "./chunk-I4L224TZ.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -36,7 +36,7 @@ import {
   TargetSchema,
   ValidationError,
   ZodEmpty
-} from "./chunk-TZWDSNSN.js";
+} from "./chunk-PMAZTOSO.js";
 import "./chunk-5WRI5ZAA.js";
 
 // src/signals.ts
@@ -681,18 +681,23 @@ async function truncateAndWarmCache(guarded, seedStates, guardEvents, correlatio
 
 // src/internal/correlate-cycle.ts
 var CorrelateCycle = class {
-  constructor(registry, staticTargets, hasDynamicResolvers, cd, maxSubscribedStreams, onInit) {
-    this.registry = registry;
-    this.staticTargets = staticTargets;
-    this.hasDynamicResolvers = hasDynamicResolvers;
-    this.cd = cd;
-    this.onInit = onInit;
-    this._subscribed = new LruSet(maxSubscribedStreams);
-  }
   _checkpoint = -1;
   _initialized = false;
   _timer = void 0;
   _subscribed;
+  _registry;
+  _static_targets;
+  _has_dynamic_resolvers;
+  _cd;
+  _on_init;
+  constructor(registry, staticTargets, hasDynamicResolvers, cd, maxSubscribedStreams, onInit) {
+    this._subscribed = new LruSet(maxSubscribedStreams);
+    this._registry = registry;
+    this._static_targets = staticTargets;
+    this._has_dynamic_resolvers = hasDynamicResolvers;
+    this._cd = cd;
+    this._on_init = onInit;
+  }
   /** Last correlated event id. */
   get checkpoint() {
     return this._checkpoint;
@@ -707,10 +712,10 @@ var CorrelateCycle = class {
   async init() {
     if (this._initialized) return;
     this._initialized = true;
-    const { watermark } = await store().subscribe([...this.staticTargets]);
+    const { watermark } = await store().subscribe([...this._static_targets]);
     this._checkpoint = watermark;
-    this.onInit?.();
-    for (const { stream } of this.staticTargets) {
+    this._on_init?.();
+    for (const { stream } of this._static_targets) {
       this._subscribed.add(stream);
     }
   }
@@ -721,7 +726,7 @@ var CorrelateCycle = class {
    */
   async correlate(query = { after: -1, limit: 10 }) {
     await this.init();
-    if (!this.hasDynamicResolvers)
+    if (!this._has_dynamic_resolvers)
       return { subscribed: 0, last_id: this._checkpoint };
     const after = Math.max(this._checkpoint, query.after || -1);
     const correlated = /* @__PURE__ */ new Map();
@@ -729,7 +734,7 @@ var CorrelateCycle = class {
     await store().query(
       (event) => {
         last_id = event.id;
-        const register = this.registry.events[event.name];
+        const register = this._registry.events[event.name];
         if (register) {
           for (const reaction of register.reactions.values()) {
             if (typeof reaction.resolver !== "function") continue;
@@ -765,7 +770,7 @@ var CorrelateCycle = class {
           lane
         })
       );
-      const { subscribed } = await this.cd.subscribe(streams);
+      const { subscribed } = await this._cd.subscribe(streams);
       this._checkpoint = last_id;
       if (subscribed) {
         for (const { stream } of streams) {
@@ -1389,9 +1394,6 @@ var EMPTY_DRAIN = {
   blocked: []
 };
 var DrainController = class {
-  constructor(deps) {
-    this.deps = deps;
-  }
   _armed = false;
   _locked = false;
   _ratio = 0.5;
@@ -1407,6 +1409,10 @@ var DrainController = class {
   /** Worker timer (ACT-1103). Set when `start()` is active, undefined otherwise. */
   _worker;
   _stopped = false;
+  _deps;
+  constructor(deps) {
+    this._deps = deps;
+  }
   /**
    * Signal that a commit (or reset / cold-start) may have produced work.
    * Subsequent `drain()` calls will run the pipeline; once the pipeline
@@ -1447,7 +1453,7 @@ var DrainController = class {
   }
   /** Lane this controller drains (undefined = legacy single-lane span). */
   get lane() {
-    return this.deps.lane;
+    return this._deps.lane;
   }
   /**
    * Start a per-lane worker that drains at the lane's `cycleMs`
@@ -1481,7 +1487,7 @@ var DrainController = class {
   async drain(options = {}) {
     if (!this._armed) return EMPTY_DRAIN;
     if (this._locked) return EMPTY_DRAIN;
-    const d = this.deps.defaults ?? {};
+    const d = this._deps.defaults ?? {};
     const streamLimit = d.streamLimit ?? options.streamLimit ?? 10;
     const eventLimit = d.eventLimit ?? options.eventLimit ?? 10;
     const leaseMillis = d.leaseMillis ?? options.leaseMillis ?? 1e4;
@@ -1490,24 +1496,24 @@ var DrainController = class {
       const lagging = Math.ceil(streamLimit * this._ratio);
       const leading = streamLimit - lagging;
       const cycle = await runDrainCycle(
-        this.deps.ops,
-        this.deps.registry,
-        this.deps.batchHandlers,
-        this.deps.handle,
-        this.deps.handleBatch,
+        this._deps.ops,
+        this._deps.registry,
+        this._deps.batchHandlers,
+        this._deps.handle,
+        this._deps.handleBatch,
         lagging,
         leading,
         eventLimit,
         leaseMillis,
         this._backoff.size > 0 ? this.isDeferred : void 0,
-        this.deps.lane
+        this._deps.lane
       );
       if (!cycle) {
         this._armed = false;
         return EMPTY_DRAIN;
       }
       const { leased, fetched, handled, acked, blocked } = cycle;
-      traceCycle(this.deps.logger, leased, fetched, handled, acked, blocked);
+      traceCycle(this._deps.logger, leased, fetched, handled, acked, blocked);
       this._ratio = computeLagLeadRatio(handled, lagging, leading);
       for (const lease of acked) this._backoff.delete(lease.stream);
       for (const lease of blocked) this._backoff.delete(lease.stream);
@@ -1517,13 +1523,13 @@ var DrainController = class {
         }
       }
       if (this._backoff.size > 0) this.scheduleBackoffWake();
-      if (acked.length) this.deps.onAcked(acked);
-      if (blocked.length) this.deps.onBlocked(blocked);
+      if (acked.length) this._deps.onAcked(acked);
+      if (blocked.length) this._deps.onBlocked(blocked);
       const hasErrors = handled.some(({ error }) => error);
       if (!acked.length && !blocked.length && !hasErrors) this._armed = false;
       return { fetched, leased, acked, blocked };
     } catch (error) {
-      this.deps.logger.error(error);
+      this._deps.logger.error(error);
       return EMPTY_DRAIN;
     } finally {
       this._locked = false;
@@ -1784,12 +1790,15 @@ function buildHandleBatch(logger) {
 
 // src/internal/settle.ts
 var SettleLoop = class {
-  constructor(deps, defaultDebounceMs) {
-    this.deps = deps;
-    this.defaultDebounceMs = defaultDebounceMs;
-  }
   _timer = void 0;
   _running = false;
+  _deps;
+  /** Debounce window applied when the caller doesn't override via `SettleOptions.debounceMs`. */
+  _default_debounce_ms;
+  constructor(deps, defaultDebounceMs) {
+    this._deps = deps;
+    this._default_debounce_ms = defaultDebounceMs;
+  }
   /**
    * Schedule a settle pass. Multiple calls inside the debounce window
    * coalesce into one cycle. The cycle runs correlate→drain in a loop
@@ -1799,7 +1808,7 @@ var SettleLoop = class {
    */
   schedule(options = {}) {
     const {
-      debounceMs = this.defaultDebounceMs,
+      debounceMs = this._default_debounce_ms,
       correlate: correlateQuery = { after: -1, limit: 100 },
       maxPasses = Infinity,
       ...drainOptions
@@ -1810,19 +1819,19 @@ var SettleLoop = class {
       if (this._running) return;
       this._running = true;
       (async () => {
-        await this.deps.init();
+        await this._deps.init();
         let lastDrain;
         for (let i = 0; i < maxPasses; i++) {
-          const { subscribed } = await this.deps.correlate({
+          const { subscribed } = await this._deps.correlate({
             ...correlateQuery,
-            after: this.deps.checkpoint()
+            after: this._deps.checkpoint()
           });
-          lastDrain = await this.deps.drain(drainOptions);
+          lastDrain = await this._deps.drain(drainOptions);
           const made_progress = subscribed > 0 || lastDrain.acked.length > 0 || lastDrain.blocked.length > 0;
           if (!made_progress) break;
         }
-        if (lastDrain) this.deps.onSettled(lastDrain);
-      })().catch((err) => this.deps.logger.error(err)).finally(() => {
+        if (lastDrain) this._deps.onSettled(lastDrain);
+      })().catch((err) => this._deps.logger.error(err)).finally(() => {
         this._running = false;
       });
     }, debounceMs);
@@ -1840,6 +1849,117 @@ var SettleLoop = class {
 var DEFAULT_MAX_SUBSCRIBED_STREAMS = 1e3;
 var DEFAULT_SETTLE_DEBOUNCE_MS = 10;
 var Act = class {
+  _emitter = new EventEmitter();
+  /** #803: gate the `Store.notify` subscription side. */
+  _listen;
+  /** #803: gate the local reaction pipeline (drain controllers, settle, correlate). */
+  _drain;
+  /** Event names with at least one registered reaction (computed at build time) */
+  _reactive_events;
+  /** One DrainController per active lane, keyed by lane name. */
+  _drain_controllers;
+  /** Correlation state machine: lazy init, dynamic-resolver scan, periodic worker. */
+  _correlate;
+  /** Debounced correlate→drain catch-up loop. */
+  _settle;
+  /**
+   * Disposer for the cross-process notify subscription, set up eagerly
+   * during construction. Held as a promise because the subscription
+   * itself may be async (the PG adapter checks out a dedicated client
+   * and runs `LISTEN` before resolving). Resolves to `undefined` when
+   * the store doesn't implement `notify` or there are no registered
+   * reactions.
+   *
+   * **Contract:** the configured store must be injected via
+   * {@link store}`(adapter)` *before* calling `act()...build()`. The
+   * orchestrator wires notify against whatever store is current at
+   * construction time — late injection after build is unsupported.
+   */
+  _notify_disposer;
+  /** Public registry — kept as-is per the no-prefix-on-public convention. */
+  registry;
+  /** Map of state name → state definition; populated by the builder. */
+  _states;
+  /**
+   * Emit a lifecycle event. The payload type is inferred from the event name
+   * via {@link ActLifecycleEvents}.
+   */
+  emit(event, args) {
+    return this._emitter.emit(event, args);
+  }
+  /**
+   * Register a listener for a lifecycle event. The listener receives the
+   * event-specific payload.
+   */
+  on(event, listener) {
+    this._emitter.on(event, listener);
+    return this;
+  }
+  /**
+   * Remove a previously registered lifecycle listener.
+   */
+  off(event, listener) {
+    this._emitter.off(event, listener);
+    return this;
+  }
+  /** Batch handlers for static-target projections (target → handler) */
+  _batch_handlers;
+  /** Event-sourcing handlers, optionally wrapped with trace decorators */
+  _es;
+  /** Correlate/drain pipeline ops, optionally wrapped with trace decorators */
+  _cd;
+  /**
+   * Event-name → owning state, computed at build time. The duplicate-event
+   * guard in merge.ts ensures one event name maps to at most one state, so
+   * this lookup is unambiguous. Used by `close()` to pick the right reducer
+   * set when seeding a `restart` snapshot in multi-state apps.
+   */
+  _event_to_state;
+  /**
+   * Event-name → lane fan-in for selective arming (ACT-1103). Built by
+   * `classifyRegistry` once per build. `"all"` means at least one of
+   * the event's reactions is a dynamic resolver (lane opaque until
+   * runtime); a `Set<string>` lists the static lanes only that event's
+   * reactions target.
+   */
+  _event_to_lanes;
+  /**
+   * Audit dependency bag (#723). Built once at construction; held as
+   * an immutable snapshot of the registry state the audit module
+   * needs. Lives in `internal/audit.ts` — this orchestrator never
+   * carries audit logic, only the deps + a one-liner that hands them
+   * over.
+   */
+  _audit_deps;
+  /** Logger resolved at construction time (after user port configuration) */
+  _logger = log();
+  /** Wraps a public-method body so internal `store()`/`cache()` resolve to the
+   * per-Act ports (ACT-501). No-op when the Act is unscoped — so the singleton
+   * 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);
+  _bound_load = this.load.bind(this);
+  _bound_query = this.query.bind(this);
+  _bound_query_array = this.query_array.bind(this);
+  /** Reaction dispatchers built once and handed to runDrainCycle each cycle. */
+  _handle;
+  _handle_batch;
+  /** Declared drain lanes (ACT-1103). */
+  _lanes;
+  /** Drain lanes declared via `.withLane(...)`. Implicit default not included. */
+  get lanes() {
+    return this._lanes;
+  }
   /**
    * Create a new Act orchestrator. Prefer the {@link act} builder over
    * direct construction — `act()...build()` wires the registry, merges
@@ -1854,9 +1974,9 @@ var Act = class {
    *   these from `.withLane(...)` calls. Slice 1 records them on the
    *   instance; later slices fan out one `DrainController` per lane.
    */
-  constructor(registry, _states = /* @__PURE__ */ new Map(), batchHandlers = /* @__PURE__ */ new Map(), options = {}, lanes = []) {
+  constructor(registry, states = /* @__PURE__ */ new Map(), batchHandlers = /* @__PURE__ */ new Map(), options = {}, lanes = []) {
     this.registry = registry;
-    this._states = _states;
+    this._states = states;
     this._batch_handlers = batchHandlers;
     this._lanes = lanes;
     if (options.onlyLanes && options.onlyLanes.length > 0) {
@@ -1890,6 +2010,8 @@ var Act = class {
       eventToLanes
     } = classifyRegistry(this.registry, this._states);
     this._reactive_events = reactiveEvents;
+    this._listen = options.listen !== false;
+    this._drain = options.drain !== false;
     this._event_to_state = eventToState;
     this._event_to_lanes = eventToLanes;
     const allLanes = ["default", ...lanes.map((l) => l.name)];
@@ -1917,7 +2039,8 @@ var Act = class {
           leaseMillis: cfg.leaseMillis
         }
       });
-      if (cfg?.cycleMs !== void 0) controller.start(cfg.cycleMs);
+      if (cfg?.cycleMs !== void 0 && options.drain !== false)
+        controller.start(cfg.cycleMs);
       this._drain_controllers.set(name, controller);
     }
     this._audit_deps = {
@@ -1935,9 +2058,10 @@ var Act = class {
       hasDynamicResolvers,
       this._cd,
       options.maxSubscribedStreams ?? DEFAULT_MAX_SUBSCRIBED_STREAMS,
-      // Cold start: assume drain is needed (historical events may need processing)
+      // Cold start: assume drain is needed (historical events may need processing).
+      // #803: writer-only instances skip the cold-start arm.
       () => {
-        if (this._reactive_events.size > 0) this._armAll();
+        if (this._drain && this._reactive_events.size > 0) this._armAll();
       }
     );
     this._settle = new SettleLoop(
@@ -1954,109 +2078,6 @@ var Act = class {
     this._notify_disposer = this._wireNotify(options.scoped?.store ?? store());
     dispose(() => this.shutdown());
   }
-  _emitter = new EventEmitter();
-  /** Event names with at least one registered reaction (computed at build time) */
-  _reactive_events;
-  /** One DrainController per active lane, keyed by lane name. */
-  _drain_controllers;
-  /** Correlation state machine: lazy init, dynamic-resolver scan, periodic worker. */
-  _correlate;
-  /** Debounced correlate→drain catch-up loop. */
-  _settle;
-  /**
-   * Disposer for the cross-process notify subscription, set up eagerly
-   * during construction. Held as a promise because the subscription
-   * itself may be async (the PG adapter checks out a dedicated client
-   * and runs `LISTEN` before resolving). Resolves to `undefined` when
-   * the store doesn't implement `notify` or there are no registered
-   * reactions.
-   *
-   * **Contract:** the configured store must be injected via
-   * {@link store}`(adapter)` *before* calling `act()...build()`. The
-   * orchestrator wires notify against whatever store is current at
-   * construction time — late injection after build is unsupported.
-   */
-  _notify_disposer;
-  /**
-   * Emit a lifecycle event. The payload type is inferred from the event name
-   * via {@link ActLifecycleEvents}.
-   */
-  emit(event, args) {
-    return this._emitter.emit(event, args);
-  }
-  /**
-   * Register a listener for a lifecycle event. The listener receives the
-   * event-specific payload.
-   */
-  on(event, listener) {
-    this._emitter.on(event, listener);
-    return this;
-  }
-  /**
-   * Remove a previously registered lifecycle listener.
-   */
-  off(event, listener) {
-    this._emitter.off(event, listener);
-    return this;
-  }
-  /** Batch handlers for static-target projections (target → handler) */
-  _batch_handlers;
-  /** Event-sourcing handlers, optionally wrapped with trace decorators */
-  _es;
-  /** Correlate/drain pipeline ops, optionally wrapped with trace decorators */
-  _cd;
-  /**
-   * Event-name → owning state, computed at build time. The duplicate-event
-   * guard in merge.ts ensures one event name maps to at most one state, so
-   * this lookup is unambiguous. Used by `close()` to pick the right reducer
-   * set when seeding a `restart` snapshot in multi-state apps.
-   */
-  _event_to_state;
-  /**
-   * Event-name → lane fan-in for selective arming (ACT-1103). Built by
-   * `classifyRegistry` once per build. `"all"` means at least one of
-   * the event's reactions is a dynamic resolver (lane opaque until
-   * runtime); a `Set<string>` lists the static lanes only that event's
-   * reactions target.
-   */
-  _event_to_lanes;
-  /**
-   * Audit dependency bag (#723). Built once at construction; held as
-   * an immutable snapshot of the registry state the audit module
-   * needs. Lives in `internal/audit.ts` — this orchestrator never
-   * carries audit logic, only the deps + a one-liner that hands them
-   * over.
-   */
-  _audit_deps;
-  /** Logger resolved at construction time (after user port configuration) */
-  _logger = log();
-  /** Wraps a public-method body so internal `store()`/`cache()` resolve to the
-   * per-Act ports (ACT-501). No-op when the Act is unscoped — so the singleton
-   * 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);
-  _bound_load = this.load.bind(this);
-  _bound_query = this.query.bind(this);
-  _bound_query_array = this.query_array.bind(this);
-  /** Reaction dispatchers built once and handed to runDrainCycle each cycle. */
-  _handle;
-  _handle_batch;
-  /** Declared drain lanes (ACT-1103). */
-  _lanes;
-  /** Drain lanes declared via `.withLane(...)`. Implicit default not included. */
-  get lanes() {
-    return this._lanes;
-  }
   /** True after the first `shutdown()` call. Guards idempotency. */
   _shutdown_promise;
   /**
@@ -2091,14 +2112,17 @@ var Act = class {
   async _wireNotify(s) {
     if (this._reactive_events.size === 0) return void 0;
     if (!s.notify) return void 0;
+    if (!this._listen) return void 0;
     try {
       return await s.notify((notification) => {
         try {
           this.emit("notified", notification);
-          const armed = this._armForEventNames(
-            notification.events.map((e) => e.name)
-          );
-          if (armed) this._settle.schedule({ debounceMs: 0 });
+          if (this._drain) {
+            const armed = this._armForEventNames(
+              notification.events.map((e) => e.name)
+            );
+            if (armed) this._settle.schedule({ debounceMs: 0 });
+          }
         } catch (err) {
           this._logger.error(err, "notified handler threw");
         }
@@ -2349,6 +2373,8 @@ var Act = class {
    * @see {@link start_correlations} for automatic correlation
    */
   async drain(options = {}) {
+    if (!this._drain)
+      return { fetched: [], leased: [], acked: [], blocked: [] };
     return this._scoped(() => this._drainAll(options));
   }
   /** Arm every active lane controller (ACT-1103). */
@@ -2449,6 +2475,7 @@ var Act = class {
    * @see {@link stop_correlations} to stop automatic correlation
    */
   async correlate(query = { after: -1, limit: 10 }) {
+    if (!this._drain) return { subscribed: 0, last_id: -1 };
     return this._scoped(() => this._correlate.correlate(query));
   }
   /**
@@ -2874,6 +2901,7 @@ var Act = class {
    * @see {@link correlate} for manual correlation
    */
   settle(options = {}) {
+    if (!this._drain) return;
     this._settle.schedule(options);
   }
 };