@rotorsoft/act 1.32.23 → 1.32.24

package/dist/@types/internal/event-sourcing.d.ts

@@ -1,190 +1,53 @@
 /**
- * @module event-sourcing
- * @category Internal
- *
- * Pure event-sourcing primitives: `snap` persists state checkpoints, `load`
- * reconstructs state by folding events through reducers, and `action`
- * validates an action, runs invariants, emits events, and commits them
- * atomically. `tombstone` commits the close-the-books guard with optimistic
- * concurrency.
- *
- * These are the bare implementations — observability is layered on top in
- * {@link "tracing"} and wired by the orchestrator at construction time.
- * No tracing imports here, no module-level mutable state.
- *
- * @internal
+ * Event-sourcing primitives: `snap`, `load`, `action`, `tombstone`, `scan`.
+ * Bare implementations; tracing wraps them in `tracing.ts`.
  */
 import { type Patch } from "@rotorsoft/act-patch";
 import type { Committed, DoOptions, EventSource, LoadTarget, ScanOptions, ScanResult, Schema, Schemas, Snapshot, State, Target } from "../types/index.js";
 /**
- * The reduction pipeline names three distinct things, and each word means
- * exactly one of them:
- *
- * - a **reducer** is a state's `.patch()` handler — it takes one event and
- *   returns a {@link Patch} *partial*;
- * - a **patch step** ({@link bare_patch} / {@link validating_patch}) merges
- *   that partial into the current state, yielding the next full state;
- * - the **fold** is the loop that applies the patch step across a stream's
- *   events (the reader loop in {@link load} / {@link action}, and the
- *   projection engine in {@link "projection-fold"}).
- *
- * `PatchFn` is the per-event patch step. The fold loop calls one of two
- * implementations, selected **once** at construction (in
- * {@link "tracing".build_es}) — never branched per event:
- *
- * - {@link bare_patch} — the default. Literally `patch(state, partial)`,
- *   no wrapper. No validation cost on the hot path.
- * - {@link validating_patch} — the opt-in `ActOptions.validateFoldedState`
- *   path. Merges, then parses the merged full state against the state's
- *   declared Zod schema.
- *
- * The `me`/`event` arguments are unused by the bare implementation but
- * carried on the shared signature so the fold loop is call-shape-identical
- * regardless of which patch step was selected — the validating
- * implementation needs them to name the failing reduction.
- *
- * @internal
+ * The patch step: merges a reducer's partial into state. Chosen once at
+ * construction (`build_es`), never per event. `me`/`event` only serve
+ * {@link validating_patch}, to name the failing reduction.
  */
 export type PatchFn = <TState extends Schema, TEvents extends Schemas, TActions extends Schemas>(me: State<TState, TEvents, TActions>, state: TState, partial: Readonly<Patch<TState>>, event: Committed<TEvents, keyof TEvents>) => TState;
-/**
- * The default patch step: a bare `patch()` merge with no wrapper and no
- * branch. The off-path is a plain reduction, so an
- * app that leaves `validateFoldedState` off pays nothing — not even a
- * comparison.
- *
- * @internal
- */
+/** The default patch step: a bare merge, so the hot path pays nothing. */
 export declare const bare_patch: PatchFn;
 /**
- * The opt-in patch step: merge the partial into state, then
- * parse the merged full state against the owning state's declared Zod
- * schema. A reducer that produces schema-violating state (the calculator
- * divide-by-zero NaN class) fails here, at the triggering event,
- * instead of propagating and surfacing hops later as a confusing
- * downstream error.
- *
- * The `target` string names the state and the triggering event
- * (`"<state>.<event>#<id>"`) so the resulting {@link ValidationError}
- * points straight at the reduction that produced bad state. A debugging /
- * CI aid, not a production guard — selected only when the operator opts
- * in.
- *
- * @internal
+ * `validateFoldedState`: merge, then parse against the state schema, so a
+ * bad reducer fails at its own event. A debugging aid, not a production guard.
  */
 export declare const validating_patch: PatchFn;
-/**
- * Internal action signature seen by the orchestrator — the {@link Correlator}
- * is bound at `build_es` time, so callers don't pass it through.
- *
- * @internal
- */
+/** `action` with the correlator and patch step bound by `build_es`. */
 type BoundAction = <TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TKey extends keyof TActions>(me: State<TState, TEvents, TActions>, action: TKey, target: Target, payload: Readonly<TActions[TKey]>, options?: DoOptions<TEvents>) => Promise<Snapshot<TState, TEvents>[]>;
-/** @internal */
 export interface EsOps {
     snap: typeof snap;
     load: typeof load;
     action: BoundAction;
     tombstone: typeof tombstone;
 }
-/**
- * Event sourcing utilities for snapshotting, loading, and committing actions/events.
- * Used internally by Act and state machines.
- */
-/**
- * Saves a snapshot of the state to the store.
- *
- * Snapshots are used to optimize state reconstruction for aggregates with long event streams.
- *
- * @template TState The type of state
- * @template TEvents The type of events
- * @param snapshot The snapshot to save
- * @returns Promise that resolves when the snapshot is saved
- *
- * @example
- * await snap(snapshot);
- */
+/** Commits a snapshot event. Never throws: a failed snapshot must not fail the action. */
 export declare function snap<TState extends Schema, TEvents extends Schemas>(snapshot: Snapshot<TState, TEvents>): Promise<Committed<TEvents, keyof TEvents> | undefined>;
 /**
- * Commits a tombstone event with optimistic concurrency, returning the
- * committed record on success or `undefined` if the stream moved past
- * `expectedVersion` (concurrent write detected). Other store errors
- * propagate.
- *
- * Used by `close()` to guard a stream while archive/truncate runs:
- * subsequent `action()` calls see the tombstone at head and reject with
- * {@link StreamClosedError} until the close completes.
- *
- * @internal
+ * Commits the close guard at `expectedVersion`; `undefined` when the stream
+ * moved. Actions then see the tombstone at head and throw {@link StreamClosedError}.
  */
 export declare function tombstone(stream: string, expectedVersion: number, correlation: string): Promise<Committed<Schemas, keyof Schemas> | undefined>;
 /**
- * Scan a restore source event by event. Owns pagination, validation,
- * the `drop_snapshots` filter, the `on_progress` callback, and the
- * causation remap; adapters supply only the per-event insert
- * `callback` via the driver pattern (see {@link Store.restore}).
- *
- * Pages the source with `limit`/`after`; a source that ignores the
- * filter (`CsvFile`) returns everything at once and the loop ends. Throws
- * on the first invalid event. Returns the result without `duration_ms`,
- * which {@link Act.restore} adds.
- *
- * @internal
+ * Pages a restore source: validation, drop filters, migrations, progress and
+ * causation remap. Adapters supply only the per-event insert `callback`
+ * (see {@link Store.restore}). A source that ignores `limit` (`CsvFile`)
+ * returns everything in one page.
  */
 export declare function scan(source: EventSource, opts?: ScanOptions, callback?: (event: Committed<Schemas, keyof Schemas>) => Promise<number>): Promise<Omit<ScanResult, "duration_ms">>;
 /**
- * Loads a snapshot of the state from the store by folding events through the
- * state's patch reducers.
- *
- * First checks the cache for a checkpoint, then queries the store for events
- * committed after the cached position. On cache miss, replays from the store
- * (using snapshots if available to avoid full replay).
- *
- * @template TState The type of state
- * @template TEvents The type of events
- * @template TActions The type of actions
- * @param me The state machine definition.
- * @param stream The stream (instance) to load
- * @param callback (Optional) Callback to receive the loaded snapshot as it is built
- * @param asOf (Optional) Time-travel cursor; bypasses the cache.
- * @param actor (Optional) Passed through to the state's `view` delegate
- *   when constructing the snapshot.event — semantics are the state's to
- *   define (see {@link state}).
- * @returns The snapshot of the loaded state
- *
- * @example
- * const snapshot = await load(Counter, "counter1");
+ * Folds a stream into state, from the cached checkpoint or the latest
+ * snapshot. `asOf` time-travels and bypasses the cache.
  */
 export declare function load<TState extends Schema, TEvents extends Schemas, TActions extends Schemas>(me: State<TState, TEvents, TActions>, target: LoadTarget, callback?: (snapshot: Snapshot<TState, TEvents>) => void, patch_fn?: PatchFn): Promise<Snapshot<TState, TEvents>>;
 /**
- * Executes an action and emits an event to be committed by the store.
- *
- * Validates the action, applies business invariants, emits events, and
- * commits them to the event store. When the action's
- * {@link ActionOptions} declare a retry budget, the orchestrator owns
- * the loop on {@link ConcurrencyError}: cache is invalidated, optional
- * `backoff` delay is applied, and the action re-runs from `load`. Any
- * other error rethrows immediately and does not consume the budget.
- *
- * Reactions skip optimistic concurrency (commit below passes
- * `undefined` as `expectedVersion` when `reactingTo` is set), so
- * `ConcurrencyError` cannot fire on the reaction-driven path — the
- * loop is naturally a no-op there.
- *
- * @template TState The type of state
- * @template TEvents The type of events
- * @template TActions The type of action_schemas
- * @template TKey The type of action to execute
- * @param me The state machine definition
- * @param action The action to execute
- * @param target The target (stream, actor, etc.)
- * @param payload The payload of the action
- * @param options Per-call dispatch options ({@link DoOptions}) —
- *   `reactingTo` to thread correlation, `correlator` to override the
- *   framework or orchestrator-level correlator for this call only.
- * @returns The snapshot of the committed event
- *
- * @example
- * const snapshot = await action(Counter, "increment", { stream: "counter1", actor }, { by: 1 });
+ * Validates, checks invariants, emits and commits. On {@link ConcurrencyError}
+ * it re-runs from `load` within the action's `maxRetries`; any other error
+ * rethrows. Reactions commit without the inferred version guard.
  */
 export declare function action<TState extends Schema, TEvents extends Schemas, TActions extends Schemas, TKey extends keyof TActions>(me: State<TState, TEvents, TActions>, action: TKey, target: Target, payload: Readonly<TActions[TKey]>, options?: DoOptions<TEvents>, patch_fn?: PatchFn): Promise<Snapshot<TState, TEvents>[]>;
 export {};

package/dist/@types/internal/event-sourcing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-sourcing.d.ts","sourceRoot":"","sources":["../../../src/internal/event-sourcing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"event-sourcing.d.ts","sourceRoot":"","sources":["../../../src/internal/event-sourcing.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -3128,71 +3128,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 = (0, import_node_crypto.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,
@@ -3213,28 +3169,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) {
@@ -3261,16 +3202,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;
@@ -3279,21 +3211,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;
@@ -3304,16 +3226,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)
@@ -3398,10 +3311,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);
@@ -3444,14 +3355,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);
@@ -3487,13 +3393,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;
@@ -3970,11 +3870,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 }
     }
   );
@@ -3998,10 +3896,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,
@@ -4063,8 +3958,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,
@@ -4467,61 +4361,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;
   }
@@ -4529,19 +4397,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;
@@ -4554,7 +4413,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) {
@@ -4563,7 +4421,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;