@rotorsoft/act 1.35.3 → 1.37.0

package/dist/index.js

@@ -40,7 +40,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-SVVVS6GA.js";
+} from "./chunk-BRJZQ4IY.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -71,7 +71,7 @@ import {
   pii_fields,
   pii_schemas,
   sensitive
-} from "./chunk-H2QN755D.js";
+} from "./chunk-A3XDAB7T.js";
 
 // src/signals.ts
 process.once("SIGINT", async (arg) => {
@@ -709,12 +709,10 @@ var CircuitBreaker = class {
   stop() {
     this._clear_wake();
   }
-  /**
-   * Schedule the `on_retry` wake `cooldownMs` out so the breaker re-trials
-   * the store on its own. No-op when no `on_retry` hook is wired (e.g. unit
-   * tests of the pure state machine). The timer is `unref`'d so it never
-   * keeps the process alive.
-   */
+  // Schedule the `on_retry` wake `cooldownMs` out so the breaker re-trials
+  // the store on its own. No-op when no `on_retry` hook is wired (e.g. unit
+  // tests of the pure state machine). The timer is `unref`'d so it never
+  // keeps the process alive.
   _schedule_wake() {
     if (!this._hooks.on_retry) return;
     this._clear_wake();
@@ -730,7 +728,7 @@ var CircuitBreaker = class {
       this._wake = void 0;
     }
   }
-  /** Pure state transition for a failure — no side effects. */
+  // Pure state transition for a failure — no side effects.
   _advance(now) {
     if (this._opened_at !== void 0) {
       this._opened_at = now;
@@ -1157,23 +1155,19 @@ function report_lane_conflict(seen, handler, target, kept, dropped) {
 }
 var CorrelateCycle = class {
   _checkpoint = -1;
-  /** Lease holder id; per instance, so a restart never inherits a stale claim. */
+  // Lease holder id; per instance, so a restart never inherits a stale claim.
   _by = randomUUID();
   _key;
-  /** Local expiry of the held lease (0 = none); stale only costs a duplicate scan. */
+  // Local expiry of the held lease (0 = none); stale only costs a duplicate scan.
   _lease_until = 0;
-  /**
-   * Armed while `_raised` (bumped by a commit or notification) is ahead of
-   * `_lowered` (the raise count the last short page saw). Starts armed.
-   */
+  // Armed while `_raised` (bumped by a commit or notification) is ahead of
+  // `_lowered` (the raise count the last short page saw). Starts armed.
   _raised = 1;
   _lowered = 0;
-  /**
-   * Bumped by a release (shutdown), so a scan or lease reply that was out
-   * across one writes nothing.
-   */
+  // Bumped by a release (shutdown), so a scan or lease reply that was out
+  // across one writes nothing.
   _epoch = 0;
-  /** Passes in flight: a restore waits for them, and refuses new ones. */
+  // Passes in flight: a restore waits for them, and refuses new ones.
   _passes = /* @__PURE__ */ new Set();
   _restoring = false;
   _init_promise;
@@ -1187,7 +1181,7 @@ var CorrelateCycle = class {
   _cd;
   _on_init;
   _declared_lanes;
-  /** Report-once keys; per instance because `internal/` holds no module state. */
+  // Report-once keys; per instance because `internal/` holds no module state.
   _reported = /* @__PURE__ */ new Set();
   constructor({
     registry,
@@ -1254,7 +1248,7 @@ var CorrelateCycle = class {
   forget_subscribed(streams) {
     for (const stream of streams) this._dynamic_subscriptions.delete(stream);
   }
-  /** Would the target's own `fetch` (filtered by `source`) return this event? */
+  // Would the target's own `fetch` (filtered by `source`) return this event?
   _in_fetch_window(source, stream) {
     if (source === void 0 || source === stream) return true;
     if (is_literal_source(source)) return false;
@@ -1413,11 +1407,9 @@ var CorrelateCycle = class {
     if (!stopped && found !== limit) this._lowered = raised;
     return { kind: "scanned", last_id, subscribed: 0, marked: 0, read };
   }
-  /**
-   * Read the row of each target this scan had no record of (new or evicted),
-   * so a resolution that doesn't beat its priority keeps the row's lane.
-   * Only called with more than one lane declared.
-   */
+  // Read the row of each target this scan had no record of (new or evicted),
+  // so a resolution that doesn't beat its priority keeps the row's lane.
+  // Only called with more than one lane declared.
   async _recall(correlated) {
     const missed = [...correlated].filter(([, entry]) => entry.missed);
     await Promise.all(
@@ -2396,21 +2388,17 @@ function merge_drains(drains) {
 }
 var RETRY = "";
 var DrainController = class {
-  /**
-   * Armed while `_raised` is ahead of `_lowered` (the raise count the last
-   * empty claim saw), so a claim never lowers over a raise that landed
-   * during it.
-   */
+  // Armed while `_raised` is ahead of `_lowered` (the raise count the last
+  // empty claim saw), so a claim never lowers over a raise that landed
+  // during it.
   _raised = 0;
   _lowered = 0;
   _ratio = 0.5;
-  /**
-   * 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 or the controller stops, and an 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 or the controller stops, and an entry
+  // stays until handled or until a later pass claims nothing.
   _defer = new DeferTimer(() => {
     this.arm();
     void this._deps.run_scoped(async () => {
@@ -2420,7 +2408,7 @@ var DrainController = class {
   _worker;
   _misrouted = /* @__PURE__ */ new Set();
   _stopped = false;
-  /** The pass in flight. Never rejects; graceful shutdown waits on it. */
+  // The pass in flight. Never rejects; graceful shutdown waits on it.
   _inflight;
   _deps;
   constructor(deps) {
@@ -2487,7 +2475,7 @@ var DrainController = class {
     this._inflight = pass;
     return pass;
   }
-  /** One claim → fetch → handle → ack pass. Never throws. */
+  // One claim → fetch → handle → ack pass. Never throws.
   async _pass(streamLimit, eventLimit, leaseMillis) {
     try {
       const lagging = Math.ceil(streamLimit * this._ratio);
@@ -2848,21 +2836,19 @@ function build_handle_batch(logger) {
 // src/internal/settle.ts
 var SettleLoop = class {
   _timer = void 0;
-  /**
-   * The cycle in flight, set while one runs. Shutdown waits for it
-   * (`stop()` cancels scheduling only). Never rejects.
-   */
+  // The cycle in flight, set while one runs. Shutdown waits for it
+  // (`stop()` cancels scheduling only). Never rejects.
   _inflight;
-  /** A wake-up arrived while a cycle ran: run one more pass after it. */
+  // A wake-up arrived while a cycle ran: run one more pass after it.
   _pending = false;
-  /** The last caller's options, used by the next pass. */
+  // The last caller's options, used by the next pass.
   _next = void 0;
-  /** When the scheduled pass fires (epoch ms). */
+  // When the scheduled pass fires (epoch ms).
   _due = 0;
-  /** Set at shutdown: nothing schedules again. */
+  // Set at shutdown: nothing schedules again.
   _stopped = false;
   _deps;
-  /** Debounce window applied when the caller doesn't override via `SettleOptions.debounceMs`. */
+  // Debounce window applied when the caller doesn't override via `SettleOptions.debounceMs`.
   _default_debounce_ms;
   constructor(deps, default_debounce_ms) {
     this._deps = deps;
@@ -2960,18 +2946,16 @@ var Act = class {
   _breaker;
   _drain;
   _auto_settle;
-  /** Whether any event has a reaction; nothing arms without one. */
+  // Whether any event has a reaction; nothing arms without one.
   _reactive;
   _drain_controllers;
   _correlate;
   _settle;
   _poll;
-  /** The poll's correlate `limit`, used by every settle pass while it runs. */
+  // The poll's correlate `limit`, used by every settle pass while it runs.
   _poll_limit;
-  /**
-   * Wired at construction against the store current then, so a store
-   * injected after `build()` is never notified.
-   */
+  // Wired at construction against the store current then, so a store
+  // injected after `build()` is never notified.
   _notify_disposer;
   /** Public registry — kept as-is per the no-prefix-on-public convention. */
   registry;
@@ -2989,58 +2973,70 @@ var Act = class {
    * returns "had listeners" to preserve the `EventEmitter.emit` contract.
    */
   emit(event, args) {
-    const listeners = this._emitter.rawListeners(event);
+    return this._notify(event, args);
+  }
+  // Run each listener of `key` on its own, logging any that throws.
+  _notify(key, args) {
+    const listeners = this._emitter.rawListeners(key);
     for (const listener of listeners) {
       try {
         listener(args);
       } catch (error) {
-        this._logger.error(error, `${String(event)} listener threw`);
+        this._logger.error(error, `${key} listener threw`);
       }
     }
     return listeners.length > 0;
   }
-  /**
-   * The one place a store failure is logged and emitted (the breaker's
-   * `on_error`). The emit is guarded: an unhandled `"error"` emission
-   * would crash the process.
-   */
+  // The emitter key of one state's `committed` listeners.
+  _committed_key(state2) {
+    const name = typeof state2 === "string" ? state2 : state2.name;
+    if (!this._states.has(name))
+      throw new Error(`committed: "${name}" is not a state of this app`);
+    return `committed:${name}`;
+  }
+  // The one place a store failure is logged and emitted (the breaker's
+  // `on_error`). The emit is guarded: an unhandled `"error"` emission
+  // would crash the process.
   _emit_error(error, circuit) {
     this._logger.error(error);
     if (this._emitter.listenerCount("error") > 0)
       this.emit("error", { error, circuit });
   }
-  /**
-   * Register a listener for a lifecycle event. The listener receives the
-   * event-specific payload.
-   */
-  on(event, listener) {
-    this._emitter.on(event, listener);
+  on(event, state_or_listener, listener) {
+    if (listener)
+      this._emitter.on(
+        this._committed_key(state_or_listener),
+        listener
+      );
+    else this._emitter.on(event, state_or_listener);
     return this;
   }
-  /**
-   * Remove a previously registered lifecycle listener.
-   */
-  off(event, listener) {
-    this._emitter.off(event, listener);
+  off(event, state_or_listener, listener) {
+    if (listener)
+      this._emitter.off(
+        this._committed_key(state_or_listener),
+        listener
+      );
+    else this._emitter.off(event, state_or_listener);
     return this;
   }
   _batch_handlers;
   _es;
   _cd;
-  /** Unambiguous: merge rejects an event name declared by two states. */
+  // Unambiguous: merge rejects an event name declared by two states.
   _event_to_state;
-  /** Lanes to arm per event; `"all"` when a dynamic resolver hides the lane. */
+  // Lanes to arm per event; `"all"` when a dynamic resolver hides the lane.
   _event_to_lanes;
   _audit_deps;
   _logger = log();
-  /** This Act's ports: its own bag, or the singleton adapters. */
+  // This Act's ports: its own bag, or the singleton adapters.
   _ports;
-  /** Runs a body so internal `store()`/`cache()` calls resolve to `_ports`. */
+  // Runs a body so internal `store()`/`cache()` calls resolve to `_ports`.
   _scoped;
   _correlator;
   _lanes;
   _close_lock = new CloseLock();
-  /** Every lane a controller can exist for: `"default"` plus each declared one. */
+  // Every lane a controller can exist for: `"default"` plus each declared one.
   _declared_lanes;
   /** Drain lanes declared via `.withLane(...)`. Implicit default not included. */
   get lanes() {
@@ -3105,7 +3101,7 @@ var Act = class {
     );
     register_weak_disposer(new WeakRef(this), (self) => self.shutdown());
   }
-  /** Shared by drain, settle and autoclose; bad knobs throw at build. */
+  // Shared by drain, settle and autoclose; bad knobs throw at build.
   _build_breaker(options) {
     return new CircuitBreaker(
       resolveCircuitBreakerConfig(options.circuitBreaker),
@@ -3117,7 +3113,7 @@ var Act = class {
       }
     );
   }
-  /** Apps that declare no lanes pass no lane filter to `claim`. */
+  // Apps that declare no lanes pass no lane filter to `claim`.
   _build_drain_controllers(options, lanes, handle, handle_batch) {
     const all_lanes = this._declared_lanes;
     const only_set = options.onlyLanes?.length ? new Set(options.onlyLanes) : void 0;
@@ -3163,7 +3159,7 @@ var Act = class {
     }
     return controllers;
   }
-  /** One process can't see the cluster, so it reports its own lane gaps. */
+  // One process can't see the cluster, so it reports its own lane gaps.
   _advise_orphaned_lanes() {
     const active = new Set(this._drain_controllers.keys());
     const orphaned = this._declared_lanes.filter((name) => !active.has(name));
@@ -3173,7 +3169,7 @@ var Act = class {
       `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, built after the controllers so the lane set is final. */
+  // Audit deps, built after the controllers so the lane set is final.
   _build_audit_deps() {
     return {
       store,
@@ -3202,7 +3198,7 @@ var Act = class {
       }
     });
   }
-  /** Cold start: an idle deferred stream still fires on time after a restart. */
+  // Cold start: an idle deferred stream still fires on time after a restart.
   async _seed_persisted_defers() {
     const now = Date.now();
     await walk_streams(store(), (pos) => {
@@ -3256,10 +3252,8 @@ var Act = class {
     }
     return this._shutdown_promise;
   }
-  /**
-   * The largest `leaseMillis` among lanes with a cycle in flight (the
-   * default for none or 0, and for a running settle), capped.
-   */
+  // The largest `leaseMillis` among lanes with a cycle in flight (the
+  // default for none or 0, and for a running settle), capped.
   _derive_grace_ms(running, settling) {
     let max = settling ? DEFAULT_LEASE_MILLIS : 0;
     for (const c of running)
@@ -3288,7 +3282,7 @@ var Act = class {
       clearTimeout(timer);
     }
   }
-  /** Failures are logged, never thrown: `notify` is a hint. */
+  // Failures are logged, never thrown: `notify` is a hint.
   async _wire_notify(s, listen) {
     if (!this._reactive) return void 0;
     if (!s.notify) return void 0;
@@ -3360,6 +3354,10 @@ var Act = class {
       if (!snapshots[0].patch) return snapshots;
       this._wake(snapshots.map((s) => s.event.name));
       this.emit("committed", snapshots);
+      this._notify(
+        `committed:${this.registry.actions[action2].name}`,
+        snapshots
+      );
       return snapshots;
     });
   }
@@ -3505,28 +3503,26 @@ var Act = class {
       return { fetched: [], leased: [], acked: [], blocked: [] };
     return this._scoped(() => this._drain_all(options));
   }
-  /** Arms correlate and every lane; false on an app with no reactions. */
+  // Arms correlate and every lane; false on an app with no reactions.
   _arm_all() {
     if (!this._reactive) return false;
     this._correlate.arm();
     for (const c of this._drain_controllers.values()) c.arm();
     return true;
   }
-  /**
-   * Wakes what a change freed (a commit, a reset, an unblock, a restore,
-   * a notification from another process): arms the lanes these events
-   * react on, or every lane without names, and settles them unless the app
-   * walks the pipeline itself (`autoSettle: false`).
-   */
+  // Wakes what a change freed (a commit, a reset, an unblock, a restore,
+  // a notification from another process): arms the lanes these events
+  // react on, or every lane without names, and settles them unless the app
+  // walks the pipeline itself (`autoSettle: false`).
   _wake(names) {
     const armed = names ? this._arm_for_event_names(names) : this._arm_all();
     if (armed && this._auto_settle) this._schedule();
   }
-  /** Schedules a settle pass; writer-only instances (`drain: false`) skip it. */
+  // Schedules a settle pass; writer-only instances (`drain: false`) skip it.
   _schedule(options) {
     if (this._drain) this._settle.schedule(options);
   }
-  /** Arms only the lanes these events react on; true when any was armed. */
+  // Arms only the lanes these events react on; true when any was armed.
   _arm_for_event_names(names) {
     const to_arm = /* @__PURE__ */ new Set();
     for (const name of names) {
@@ -3543,7 +3539,7 @@ var Act = class {
     for (const lane of to_arm) this._drain_controllers.get(lane)?.arm();
     return true;
   }
-  /** In parallel, so a slow lane never holds up a fast one. */
+  // In parallel, so a slow lane never holds up a fast one.
   async _drain_all(options) {
     const merged = merge_drains(
       await Promise.all(
@@ -3585,7 +3581,7 @@ var Act = class {
       last_id: pass.last_id
     };
   }
-  /** One correlate pass; arms every lane when it found work. */
+  // One correlate pass; arms every lane when it found work.
   async _correlate_pass(limit, lease = false) {
     if (!this._drain) return { kind: "idle", last_id: -1 };
     return this._scoped(async () => {
@@ -3873,7 +3869,7 @@ var Act = class {
   async prioritize(filter, priority) {
     return this._scoped(() => store().prioritize(filter, priority));
   }
-  /** Shared by `close()` and reaction-requested closes. */
+  // Shared by `close()` and reaction-requested closes.
   async _run_close(targets) {
     const close_actor = { id: "$close", name: "close" };
     const result = await run_close_cycle(targets, {
@@ -4643,6 +4639,24 @@ function act() {
   const fold_specs = [];
   const lanes = [];
   let _built = false;
+  const advise_pii_types = () => {
+    const fields = /* @__PURE__ */ new Set();
+    for (const state2 of states.values()) {
+      const shape = state2.state.shape ?? {};
+      for (const [event, schema] of Object.entries(state2.events))
+        for (const [field, field_schema] of Object.entries(
+          pii_schemas(schema)
+        )) {
+          if (!reads_as_string(field_schema)) fields.add(`${event}.${field}`);
+          if (shape[field] && !reads_as_string(shape[field]))
+            fields.add(`${state2.name}.${field}`);
+        }
+    }
+    if (fields.size > 0)
+      log().warn(
+        `Act has ${fields.size} sensitive field(s) whose type isn't a string: ${[...fields].join(", ")}. A caller who may not see one reads "[REDACTED]" or "[SHREDDED]" there instead, which its type doesn't allow. Declare sensitive fields as strings. See docs/docs/guides/sensitive-data.md.`
+      );
+  };
   const read_wrap = (original) => {
     const wrapped = async (events, stream) => {
       const read = events.map((e) => _hr.get(e.name)?.(e) ?? e);
@@ -4781,6 +4795,7 @@ function act() {
         for (const [name, gate] of built.query_readers) _qg.set(name, gate);
         for (const [name, gate] of built.handler_readers) _hr.set(name, gate);
         finalize_deprecations();
+        advise_pii_types();
         for (const state2 of states.values()) {
           if (state2.disclose) _dp.set(state2.name, state2.disclose);
           if (state2.autoclose) _ac.set(state2.name, state2.autoclose);
@@ -4811,6 +4826,12 @@ function act() {
   };
   return builder;
 }
+function reads_as_string(schema) {
+  const def = schema._zod.def;
+  if (def.type === "string" || def.type === "transform") return true;
+  if (def.out) return reads_as_string(def.out);
+  return def.innerType ? reads_as_string(def.innerType) : false;
+}
 
 // src/builders/projection-builder.ts
 function _projection(target) {