@rotorsoft/act 1.32.22 → 1.32.24

package/dist/index.js

@@ -26,7 +26,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-T3CWXVGT.js";
+} from "./chunk-OG5O36AJ.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -1584,71 +1584,27 @@ function report_lane_conflict(seen, handler, target, kept, dropped) {
 var CorrelateCycle = class {
   _checkpoint = -1;
   _initialized = false;
-  /**
-   * This worker's identity for the correlation lease. A per-instance
-   * UUID, matching the drain's convention, so a renewal is recognised as the
-   * same holder and a restarted process never inherits a stale claim.
-   */
+  /** Lease holder id; per instance, so a restart never inherits a stale claim. */
   _by = randomUUID();
-  /**
-   * Which correlator this is. Computed once from the registry so identical
-   * workers share a lease and unrelated applications never do.
-   */
   _key;
-  /**
-   * When this worker's correlation lease runs out, as a local clock reading,
-   * or 0 when it holds none.
-   *
-   * Cached so the holder doesn't ask the store on every pass. A stale belief
-   * can only cause a duplicate scan, and marks are idempotent, so it costs
-   * work, never correctness.
-   */
+  /** Local expiry of the held lease (0 = none); stale only costs a duplicate scan. */
   _lease_until = 0;
-  /**
-   * Whether a scan might find anything, like the drain's flag: a commit or
-   * notification raises it, a short page lowers it, and a disarmed scan
-   * returns without touching the store.
-   *
-   * Starts armed: the log may already hold events this process has never
-   * correlated, and only a scan can find out.
-   */
+  /** Raised by a commit or notification, lowered by a short page. Starts armed. */
   _armed = true;
-  /** In-flight init, memoized for single-flight and cleared on failure. */
   _init_promise;
-  // Dynamically discovered targets → what each was last subscribed at,
-  // bounded by `maxSubscribedStreams`. It decides *what* a scan sends with a
-  // target: priority/lane only when the resolution beats the recorded floor,
-  // otherwise the row's own values. See {@link Subscription}.
+  // Bounded by `maxSubscribedStreams`; static records live apart so eviction
+  // never drops their +Infinity floor.
   _dynamic_subscriptions;
-  /**
-   * What each static target was subscribed at by `init`. A plain map, never
-   * evicted: the collection is the build-time `_static_targets` list, so it
-   * is already bounded by the registry and costs nothing the registry does
-   * not already hold.
-   *
-   * Kept out of the LRU so eviction can never drop a static target's
-   * `+Infinity` floor and let a dynamic resolution re-lane it.
-   */
   _static_subscriptions = /* @__PURE__ */ new Map();
-  /** Compiled pattern sources, bounded by {@link PATTERN_CACHE_SIZE}. */
   _patterns = new LruMap(PATTERN_CACHE_SIZE);
   _registry;
   _static_targets;
   _cd;
   _on_init;
-  /**
-   * Async cold-start hook, run once after `on_init` inside `init()`. The
-   * orchestrator re-seeds its defer timers from the persisted `deferred_at`
-   * here, so an idle deferred stream re-arms across a restart.
-   */
+  /** Runs once after `on_init`; re-seeds defer timers across a restart. */
   _on_init_async;
-  /** Lanes a controller exists for. See {@link CorrelateCycleDeps}. */
   _declared_lanes;
-  /**
-   * Offending declarations already reported, so a resolver firing for every
-   * matching event reports once. Owned by the instance rather than the
-   * module: `internal/` holds no module-level state.
-   */
+  /** Report-once keys; per instance because `internal/` holds no module state. */
   _reported = /* @__PURE__ */ new Set();
   constructor({
     registry,
@@ -1669,28 +1625,13 @@ var CorrelateCycle = class {
     this._on_init = on_init;
     this._on_init_async = on_init_async;
   }
-  /** Last correlated event id. */
   get checkpoint() {
     return this._checkpoint;
   }
-  /**
-   * Signal that a commit (local or remote) may have produced events this
-   * process has not correlated. Cheap and idempotent — the orchestrator calls
-   * it on every commit and every notification.
-   */
+  /** A commit (local or remote) may have produced uncorrelated events. */
   arm() {
     this._armed = true;
   }
-  /**
-   * Initialize correlation state on first call.
-   * - Reads the durable correlate checkpoint (and max(at)) from the store,
-   *   flooring a first boot at `watermark - back_scan` so an event
-   *   committed-but-not-correlated before a crash is re-scanned on
-   *   restart instead of skipped
-   * - Subscribes static resolver targets (idempotent upsert)
-   * - Populates the subscribed-streams LRU
-   * - Fires `on_init` once (Act uses this to flag a cold-start drain)
-   */
   async init() {
     if (this._initialized) return;
     if (!this._init_promise) {
@@ -1717,16 +1658,7 @@ var CorrelateCycle = class {
     }
     await this._on_init_async?.();
   }
-  /**
-   * Start correlation over after the event log was replaced wholesale
-   * (`restore`). The restored log is renumbered from the start and its
-   * subscription rows are gone, so the in-memory scan position and both
-   * subscription records describe a log that no longer exists. Dropping them
-   * and the init latch makes the next pass run cold-start again: static
-   * targets are re-subscribed, the checkpoint is re-read from the store
-   * (which `restore` reset), and dynamic targets are rediscovered by the
-   * scan.
-   */
+  /** After `restore` replaced the log: forget everything and cold-start again. */
   restart() {
     this._initialized = false;
     this._init_promise = void 0;
@@ -1735,21 +1667,11 @@ var CorrelateCycle = class {
     this._static_subscriptions.clear();
     this._armed = true;
   }
-  /**
-   * Forget dynamic targets whose subscription rows no longer exist (a full
-   * close deletes the row), so a later scan re-subscribes them. Static
-   * targets keep their records.
-   */
+  /** Forget dynamic targets whose rows a full close deleted, so they re-subscribe. */
   forget_subscribed(streams) {
     for (const stream of streams) this._dynamic_subscriptions.delete(stream);
   }
-  /**
-   * Would an event from `stream` be fetched for a target subscribed with
-   * `source`? The subscription's source is the filter `fetch` queries with
-   * — literal names by equality, patterns compiled as a `RegExp` — so an
-   * event outside it is not work for that target and must not mark it.
-   * No source means the target consumes every stream.
-   */
+  /** 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;
@@ -1760,16 +1682,7 @@ var CorrelateCycle = class {
     }
     return pattern.test(stream);
   }
-  /**
-   * Scan the events past the checkpoint, resolve each to its target
-   * streams, and record what it found through `cd.subscribe` — new dynamic
-   * targets get registered, and every target an event resolved to gets its
-   * **work mark** raised to that event's id.
-   *
-   * Both resolver kinds are walked. A static target is already subscribed
-   * at init, but marking it is what makes it claimable without probing the
-   * event log, so the scan runs for every app.
-   */
+  /** Scan past the checkpoint, subscribe new targets and raise their work marks. */
   async correlate(query = { after: -1, limit: 10 }, lease = false) {
     await this.init();
     if (!this._armed)
@@ -1854,10 +1767,8 @@ var CorrelateCycle = class {
           }
         }
       },
-      // Decline the sensitive payload: the scan only needs name/stream/id,
-      // and one undecryptable row would otherwise stop every stream's
-      // reactions. Resolvers therefore see `pii: null`; correlate runs
-      // actor-less, so plaintext here would be un-gated disclosure.
+      // Resolvers see `pii: null`: correlate runs actor-less, and one
+      // undecryptable row would otherwise stop every stream's reactions.
       { ...query, after, with_pii: false }
     );
     if (this._declared_lanes.size > 1) await this._recall(correlated);
@@ -1900,14 +1811,9 @@ var CorrelateCycle = class {
     return { subscribed: 0, last_id, marked: 0, scanned: true };
   }
   /**
-   * Give each target this scan had no record of the record its row holds.
-   *
-   * A target with no record is either new or forgotten. Its row, when it
-   * has one, says what lane and priority it was subscribed at; a resolution
-   * that doesn't beat that priority carries the row's values, exactly as if
-   * the record had never been evicted. One read per target with no record,
-   * and only when more than one lane is declared: with one lane there is no
-   * lane to lose, and the store already keeps the higher priority.
+   * 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);
@@ -1943,13 +1849,7 @@ var CorrelateCycle = class {
       })
     );
   }
-  /**
-   * Hand the correlation lease back early.
-   *
-   * The port has no release verb; re-acquiring as the same holder with a
-   * zero duration releases it. Best-effort: a failure costs the lease's
-   * remaining lifetime, as a crash would.
-   */
+  /** Release the lease early by re-acquiring it for zero ms. Best-effort. */
   async release_correlation() {
     try {
       this._lease_until = 0;
@@ -2426,11 +2326,9 @@ async function load(me, target, callback, patch_fn = bare_patch) {
     {
       stream,
       stream_exact: true,
-      // `with_snaps` on every non-time-travel load. Cold, it resumes from the
-      // latest snapshot (this is the only place that decides it; stores just
-      // apply it). Warm, it keeps a snapshot above a stale checkpoint in the
-      // result, so a windowed close that pruned the events in between can't
-      // make the fold apply the tail onto stale state.
+      // `with_snaps` on every non-time-travel load: cold, it resumes from the
+      // latest snapshot; warm, it keeps a snapshot above a stale checkpoint,
+      // so a windowed close's prune can't fold the tail onto stale state.
       ...cached ? { after: cached.event_id, with_snaps: true } : { ...time_travel ? {} : { with_snaps: true }, ...asOf }
     }
   );
@@ -2454,10 +2352,7 @@ async function load(me, target, callback, patch_fn = bare_patch) {
     event,
     state: state2,
     version: event?.version ?? cached?.version ?? -1,
-    // Head event id, captured atomically with `state`: the last replayed
-    // event's id on a cache miss, or the cached checkpoint's event_id on a
-    // warm hit with no new events. Consumers read this instead of a
-    // separate cache lookup that could race a concurrent commit.
+    // Captured with `state`, so consumers never race a separate cache lookup.
     id: event?.id ?? cached?.event_id ?? -1,
     patches,
     snaps,
@@ -2519,8 +2414,7 @@ async function action(me, action2, target, payload, options, patch_fn = bare_pat
           action: {
             name: action2,
             ...target
-            // payload intentionally omitted from causation metadata —
-            // callers correlate via the correlation id when they need it.
+            // payload intentionally omitted
           },
           event: reactingTo ? {
             id: reactingTo.id,
@@ -2923,61 +2817,35 @@ var DrainController = class {
   _locked = false;
   _ratio = 0.5;
   /**
-   * Local wake for streams this worker parked (backoff or defer). The
-   * schedule itself is persisted in the store; this runs the drain at the
-   * earliest pending visit. A parked stream already carries its mark, so
-   * the drain alone finds it, and on an idle app nothing else would.
-   * Every drain re-aims it when it ends, and a due entry stays until a pass
-   * handles it or a pass that started after it came due claims nothing, so
-   * the wake keeps draining until every due stream is reached.
-   * `stop()` cancels the timer and a stopped drain never re-schedules it,
-   * so a wake never runs after a stop.
+   * 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.
    */
   _defer = new DeferTimer(() => {
     this._armed = true;
     void this._deps.run_scoped(() => this.drain());
   });
-  /** Worker timer. Set when `start()` is active, undefined otherwise. */
   _worker;
-  /**
-   * Misroutings this controller has reported. A resolver returning a
-   * projection's target does so for every matching event; one line per event
-   * would bury the signal it exists to raise.
-   */
   _misrouted = /* @__PURE__ */ new Set();
   _stopped = false;
-  /**
-   * Resolves when the cycle in flight finishes, so a graceful shutdown can
-   * wait for it. Never rejects.
-   */
+  /** Never rejects; graceful shutdown waits on it. */
   _inflight;
   _inflight_done;
   _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
-   * settles to no-progress, the controller disarms itself.
-   */
   arm() {
     this._armed = true;
   }
-  /**
-   * Re-seed a persisted `deferred_at` into the local wake at cold start, so
-   * an idle deferred stream re-arms at its due-time with no new commit.
-   * Seeds collapse into one timer; the earliest wins.
-   */
+  /** Cold start: re-seed a persisted `deferred_at` into the local wake. */
   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;
   }
-  /** The cycle in flight, or `undefined` when idle. */
   get inflight() {
     return this._inflight;
   }
@@ -2985,19 +2853,10 @@ var DrainController = class {
   get lease_millis() {
     return this._deps.defaults?.leaseMillis;
   }
-  /** Lane this controller drains (undefined spans all lanes). */
   get lane() {
     return this._deps.lane;
   }
-  /**
-   * Start a per-lane worker that drains at the lane's `cycleMs`
-   * cadence. When armed, the worker calls `drain()` on every
-   * tick and re-schedules; when not armed, it still re-schedules at
-   * `cycleMs` so a future `arm()` is picked up on the next tick.
-   *
-   * The setTimeout chain uses `unref()` so it doesn't keep the process
-   * alive on its own.
-   */
+  /** Drains every `cycleMs` while armed; the unref'd timer never holds the process. */
   start(cycleMs) {
     if (this._worker || this._stopped) return;
     const run = this._deps.run_scoped;
@@ -3010,7 +2869,6 @@ var DrainController = class {
     this._worker = setTimeout(tick, cycleMs);
     this._worker.unref();
   }
-  /** Stop the per-lane worker. Idempotent. */
   stop() {
     this._stopped = true;
     if (this._worker) {
@@ -3019,7 +2877,6 @@ var DrainController = class {
     }
     this._defer.stop();
   }
-  /** Run one drain pass. Short-circuits when not armed or already running. */
   async drain(options = {}) {
     if (!this._armed) return EMPTY_DRAIN;
     if (this._locked) return EMPTY_DRAIN;