@rotorsoft/act 1.33.0 → 1.33.1

package/dist/index.js

@@ -40,7 +40,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-JABYJGT7.js";
+} from "./chunk-NYH6FNTM.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -70,7 +70,7 @@ import {
   pii_fields,
   pii_schemas,
   sensitive
-} from "./chunk-2PMUONGF.js";
+} from "./chunk-TJ4JRRUR.js";
 
 // src/signals.ts
 process.once("SIGINT", async (arg) => {
@@ -3187,21 +3187,14 @@ var Act = class {
   }
   _shutdown_promise;
   /**
-   * Per-instance teardown: stop scheduling new work, give drain cycles
-   * already in flight a bounded chance to finish, then remove lifecycle
-   * listeners and tear down the cross-process notify subscription.
+   * Per-instance teardown: stops scheduling, gives the cycles in flight up
+   * to `graceMs` to reach their `ack` (an abandoned handler holds its lease
+   * until it expires), then removes listeners and the notify subscription.
+   * The budget is a ceiling, not a delay.
    *
-   * Scheduling stops first, then in-flight cycles get up to `graceMs` to
-   * reach their `ack` (an abandoned handler holds its lease until it
-   * expires). Listeners come off after the wait, so they still see work that
-   * finished during it. The budget is a ceiling, not a delay; when it runs
-   * out, teardown proceeds anyway.
-   *
-   * Idempotent — repeated calls return the same promise, and the first
-   * call's `graceMs` is the one that applies. Registered automatically with
-   * the global `dispose()` registry at construction, so process-wide
-   * `dispose()()` covers it; test helpers (or operators that mint
-   * short-lived Acts) call it explicitly for prompt cleanup.
+   * Idempotent: repeated calls return the same promise, with the first
+   * call's `graceMs`. Registered with the global `dispose()` registry, so
+   * `dispose()()` covers it; call it directly for prompt cleanup.
    *
    * @param options - See {@link ShutdownOptions}. Defaults the grace budget
    *   to the largest lane `leaseMillis` (capped at 30s).
@@ -3279,15 +3272,10 @@ var Act = class {
     }
   }
   /**
-   * Executes an action on a state instance, committing resulting events.
-   *
-   * This is the primary method for modifying state. It:
-   * 1. Validates the action payload against the schema
-   * 2. Loads the current state snapshot
-   * 3. Checks invariants (business rules)
-   * 4. Executes the action handler to generate events
-   * 5. Applies events to create new state
-   * 6. Commits events to the store with optimistic concurrency control
+   * Executes an action: validates the payload, loads the state, checks its
+   * invariants, and commits the events its handler emits, with optimistic
+   * concurrency on the stream. The reactions to those events settle on
+   * their own (unless `autoSettle: false`).
    *
    * @template TKey - Action name from registered actions
    * @param action - The name of the action to execute
@@ -3366,9 +3354,7 @@ var Act = class {
    *
    * For small result sets, consider using {@link query_array} instead.
    *
-   * @param query - Filter criteria — see {@link Query} for available fields
-   *   (`stream`, `name`, `after`, `before`, `created_after`, `created_before`,
-   *   `limit`, `with_snaps`, `stream_exact`)
+   * @param query - Filter criteria; see {@link Query} for the fields
    * @param callback - Optional callback invoked for each matching event
    * @returns Object with first event, last event, and total count
    *
@@ -3452,31 +3438,23 @@ var Act = class {
     });
   }
   /**
-   * Processes pending reactions by draining uncommitted events from the event store.
-   *
-   * Runs a single drain cycle:
-   * 1. Polls the store for streams with uncommitted events
-   * 2. Leases streams to prevent concurrent processing
-   * 3. Fetches events for each leased stream
-   * 4. Executes matching reaction handlers
-   * 5. Acknowledges successful reactions or blocks failing ones
+   * Runs one drain cycle: claims streams with marked work (leasing them),
+   * fetches their events, runs the matching reactions, and acks or blocks
+   * each stream.
    *
-   * Drain uses a dual-frontier strategy to balance processing of new streams (lagging)
-   * vs active streams (leading). The ratio adapts based on event pressure.
-   *
-   * Call `correlate()` before `drain()`. It is not only how dynamic targets
-   * are discovered: a stream is claimable while `at < correlated_at`, and
-   * `correlate` is the only component that raises that mark, so a
-   * commit no correlate has seen is not drainable, static targets included. For a
-   * higher-level API that handles debouncing, correlation, and signaling
-   * automatically, use {@link settle}.
+   * A stream is claimable only once `correlate()` has marked it, static
+   * targets included, so a commit no correlate has seen is not drainable.
+   * Apps rarely call this: each commit settles its reactions on its own.
+   * With `autoSettle: false`, tests walk the pipeline with `correlate()`
+   * then `drain()` (see the testing guide).
    *
    * @param options - Drain configuration — see {@link DrainOptions} for fields
    *   (`streamLimit`, `eventLimit`, `leaseMillis`).
    * @returns Drain statistics with fetched, leased, acked, and blocked counts
    *
-   * @example In tests and scripts
+   * @example Walking the pipeline in a test
    * ```typescript
+   * const app = act().withState(User).withProjection(Users).build({ autoSettle: false });
    * await app.do("createUser", target, payload);
    * await app.correlate();
    * await app.drain();
@@ -3484,7 +3462,6 @@ var Act = class {
    *
    * @see {@link settle} for debounced correlate→drain with lifecycle events
    * @see {@link correlate} for dynamic stream discovery
-   * @see {@link start_correlations} for automatic correlation
    */
   async drain(options = {}) {
     resolveDrainConfig(options);
@@ -3551,32 +3528,20 @@ var Act = class {
     return { fetched, leased, acked, blocked };
   }
   /**
-   * Discovers and registers new streams dynamically based on reaction resolvers.
-   *
-   * Correlation enables "dynamic reactions" where target streams are determined at runtime
-   * based on event content. For example, you might create a stats stream for each user
-   * when they perform certain actions.
-   *
-   * This method scans events matching the query and identifies new target streams based
-   * on reaction resolvers. It then registers these streams so they'll be picked up by
-   * the next drain cycle.
+   * Scans committed events from the correlation checkpoint, subscribes the
+   * target streams their reactions resolve to (static or computed from
+   * the event), and marks their work so the next drain can claim it.
    *
    * @param query - Scan filter — see {@link Query} for fields (typically
-   *   `{ after: <event-id>, limit: <count> }`)
+   *   `{ limit: <count> }`; the scan starts at the checkpoint)
    * @returns The number of newly subscribed streams and the last scanned event id
    *
    * @example Manual correlation
    * ```typescript
-   * // Scan for new streams
-   * const { subscribed, last_id } = await app.correlate({ after: 0, limit: 100 });
-   * console.log(`Subscribed ${subscribed} new streams`);
-   *
-   * // Save last_id for next scan
-   * await saveCheckpoint(last_id);
+   * const { subscribed } = await app.correlate({ limit: 100 });
    * ```
    *
    * @see {@link start_correlations} for automatic periodic correlation
-   * @see {@link stop_correlations} to stop automatic correlation
    */
   async correlate(query = { after: -1, limit: 10 }) {
     const { subscribed, last_id } = await this._correlate_scanned(query);
@@ -3656,15 +3621,13 @@ var Act = class {
    * events through their reactions.
    *
    * Use this to replay events through projections (or other reaction targets)
-   * after changing handler logic. Equivalent to calling `store().reset(streams)`
-   * directly, but also raises the orchestrator's internal "needs drain" flag —
-   * `store().reset(...)` alone leaves the flag untouched, so a settled app
-   * would short-circuit and skip the replay.
-   *
-   * The reset schedules a settle on its own, which loops correlate→drain
-   * until the replay catches up. Call `app.settle(options)` right after to
-   * give that pass batch options, or
-   * `correlate()` / `drain()` to drive the replay by hand.
+   * after changing handler logic. It rewinds the same watermarks as
+   * `store().reset(streams)`, and also wakes the drain and schedules a
+   * settle, which loops correlate→drain until the replay catches up;
+   * `store().reset(...)` alone leaves a settled app idle. Call
+   * `app.settle(options)` right after to give that pass batch options, or,
+   * with `autoSettle: false`, `correlate()` / `drain()` to drive the replay
+   * by hand.
    *
    * @param input - Reaction target streams (e.g., projection names) to reset, or a {@link StreamFilter} for bulk operations
    * @returns Count of streams that were actually reset
@@ -3823,45 +3786,20 @@ var Act = class {
     });
   }
   /**
-   * Operator-driven store audit.
-   *
-   * Walks the connected store and yields per-category findings —
-   * each tagged with the remediation it suggests. Same operator-
-   * driven category as `app.close()` / `app.reset()` /
-   * `app.unblock()` / `app.blocked_streams()`: never auto-invoked by
-   * the framework; the operator decides when to run it (CI gate,
-   * scheduled job, ad-hoc forensics) and what to do with the
-   * findings.
+   * Operator-driven store audit: walks the store and yields findings per
+   * category, each with the remediation it suggests. Never run by the
+   * framework. Pass a subset of categories to scope the work; the iterable
+   * can be broken early, and findings stream without buffering the report.
    *
-   * Categories are independent — pass a subset to scope the work,
-   * or omit to run everything:
+   * @param categories - Subset of categories to run (default: all).
+   * @param options - Query window + per-category thresholds.
+   * @returns Async iterable of {@link AuditFinding}.
    *
+   * @example Schema drift since the last scan
    * ```typescript
-   * // Targeted: schema drift + deprecated-event load only
-   * for await (const f of app.audit(["schema", "deprecated-load"], {
-   *   query: { created_after: lastScan },
-   *   thresholds: { deprecatedLoadShareMin: 0.10 },
-   * })) {
+   * for await (const f of app.audit(["schema"], { query: { created_after: lastScan } }))
    *   await escalate(f);
-   * }
-   *
-   * // Full audit, default thresholds
-   * for await (const f of app.audit()) console.log(f);
    * ```
-   *
-   * Returns an `AsyncIterable` so callers can `break` early — the
-   * underlying store paginations respect the iterator protocol and
-   * stop cleanly. Each finding is emitted independently, so
-   * pipelining into Slack / persistence / further analysis works
-   * without buffering the full report in memory.
-   *
-   * Findings shape — see {@link AuditFinding}. The discriminated
-   * union carries enough context for the operator to act on each
-   * finding directly: stream id, event id, recommendation hints.
-   *
-   * @param categories - Subset of categories to run (default: all).
-   * @param options - Query window + per-category thresholds.
-   * @returns Async iterable of {@link AuditFinding}.
    */
   async *audit(categories, options) {
     const it = audit(this._audit_deps, categories, options)[Symbol.asyncIterator]();
@@ -3872,22 +3810,13 @@ var Act = class {
     }
   }
   /**
-   * Bulk-update scheduling priority for streams matching `filter`.
-   *
-   * Operator-grade override of the `claim()` lagging-frontier
-   * ordering. Useful when a long-running replay needs to
-   * jump ahead of other lagging streams, or when a no-longer-urgent
-   * job should yield slots back to the rest. Build-time priorities
-   * (set via the resolver's `priority` field) are subject to a
-   * `max()` invariant across reactions; this API ignores that and
-   * sets the priority outright on every matching row.
-   *
-   * Filter shape mirrors {@link query} / {@link Store.query_streams}:
-   * `stream` / `source` are regex by default, exact with the
-   * `*_exact` flags; `blocked` restricts to blocked or unblocked
-   * rows. **An empty filter (`{}`) updates every registered stream.**
+   * Sets the scheduling priority of every stream matching `filter`, as-is:
+   * unlike build-time priorities (the highest across reactions wins), this
+   * overrides them. Useful to let a long replay jump ahead of other lagging
+   * streams, or to yield slots back. **An empty filter (`{}`) updates every
+   * registered stream.**
    *
-   * @param filter - Selection criteria (regex by default).
+   * @param filter - Selection criteria (regex by default, like {@link query}).
    * @param priority - New priority value. Set as-is — no clamp.
    * @returns Count of streams whose priority changed.
    *
@@ -3897,7 +3826,6 @@ var Act = class {
    * ```
    *
    * @see {@link Store.prioritize} for the underlying primitive
-   * @see {@link claim} for how priority biases scheduling
    */
   async prioritize(filter, priority) {
     return this._scoped(() => store().prioritize(filter, priority));
@@ -3924,30 +3852,12 @@ var Act = class {
     return result;
   }
   /**
-   * Close the books — guard, archive, truncate, and optionally restart streams.
-   *
-   * Safely removes historical events from the operational store:
-   *
-   * 1. **Correlate** — discover pending reaction targets
-   * 2. **Safety check** — skip streams with pending reactions (skipped when no reactive events)
-   * 3. **Guard** — commit `__tombstone__` with `expectedVersion` to block concurrent writes
-   * 4. **Load state** — for streams in `snapshots`, load final state while guarded (no races)
-   * 5. **Archive** — user callback per stream (abort-all on failure, streams are guarded)
-   * 6. **Truncate + seed** — atomic: delete all events, insert `__snapshot__` or `__tombstone__`
-   * 7. **Cache** — invalidate (tombstoned) or warm (restarted)
-   * 8. **Emit "closed"** — lifecycle event with results
-   *
-   * Targets carrying `before` take the **windowed** branch instead —
-   * close the books on a rolling window: probe the min consumer
-   * watermark (so the boundary never rises past a lagging reaction),
-   * run the archive callback against the cutoff, then prune the prefix
-   * below the closest safe `__snapshot__`. No tombstone guard (the
-   * pre-cutoff prefix is immutable), no seed, cache untouched — the
-   * stream stays live and keeps accepting actions. Requires the state
-   * to snapshot via `.snap(...)`; no qualifying snapshot ⇒ the stream
-   * lands in `skipped` (retry after the next snapshot). Windowed
-   * entries in the result echo `before` and carry the surviving
-   * boundary snapshot as `committed`.
+   * Close the books: guard, archive, truncate, and optionally restart
+   * streams. A stream with pending reactions is skipped; an archive
+   * failure aborts the whole close while the streams are still guarded.
+   * Targets carrying `before` prune a rolling window instead and leave the
+   * stream live (needs `.snap(...)`). The phases and their failure
+   * semantics are in the close-cycle architecture page.
    *
    * @param targets - Per-stream close options (stream, restart?, archive?, before?)
    * @returns `{ truncated: TruncateResult, skipped: string[] }`