@rotorsoft/act 1.32.30 → 1.33.1

package/dist/@types/act.d.ts

@@ -1,225 +1,18 @@
-import { type CircuitBreakerOptions, type CircuitState, type PatchFn } from "./internal/index.js";
-export type { CircuitBreakerOptions, CircuitState } from "./internal/index.js";
-import { type Scoped } from "./ports.js";
-import type { Actor, AsOf, AuditCategory, AuditFinding, AuditOptions, BatchHandler, BlockedLease, CloseResult, CloseTarget, Committed, Correlator, DoOptions, Drain, DrainOptions, EventSink, EventSource, IAct, LaneConfig, Lease, LoadTarget, Query, Registry, ScanOptions, ScanResult, Schema, SchemaRegister, Schemas, SettleOptions, ShutdownOptions, Snapshot, State, StoreNotification, StreamFilter, StreamPosition, Target } from "./types/index.js";
-export { type AutocloseConfig, type AutoclosePolicy, DEFAULT_AUTOCLOSE_CYCLE_MINUTES, DEFAULT_CLOSE_BATCH_SIZE, DEFAULT_CLOSE_YIELD_MS, DEFAULT_MAX_SUBSCRIBED_STREAMS, DEFAULT_SETTLE_DEBOUNCE_MS, resolveAutocloseConfig, } from "./internal/index.js";
-/**
- * Lifecycle events emitted by {@link Act}, mapped to their payload type.
- * Drives the typing of `emit` / `on` / `off` — the event-name argument
- * narrows its payload at the call site.
- *
- * The first parameter is kept (unused) for arity compatibility: `committed`
- * carries snapshots of whichever state each action targeted, so its honest
- * element type is `Snapshot<Schema, TEvents>` — the register map itself was
- * never the shape of any snapshot's state.
- */
-export type ActLifecycleEvents<_TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas> = {
-    committed: Snapshot<Schema, TEvents>[];
-    acked: Lease[];
-    blocked: BlockedLease[];
-    settled: Drain<TEvents>;
-    closed: CloseResult;
-    /**
-     * A **different process** committed an event to the same backing store.
-     *
-     * Fires only when the configured store implements
-     * {@link Store.notify} and there is at least one registered reaction.
-     * The orchestrator uses the same signal internally to wake `settle()`
-     * — listeners get the raw payload for SSE fan-out, dashboards, and
-     * audit logs.
-     *
-     * Local commits do *not* fire `notified` (use `committed` for those):
-     * stores self-filter their own writes so this channel has a clean
-     * cross-process semantic.
-     */
-    notified: StoreNotification;
-    /**
-     * A stream's sensitive-data payload was wiped via {@link Act.forget}.
-     * Fires exactly once per successful `forget(stream)` call — idempotent
-     * second calls (no PII left on the stream) return `eventCount: 0` and
-     * do NOT re-emit. Apps that never call `forget()` never see this event.
-     *
-     * Listeners use it for the compliance side of GDPR / CCPA: audit log,
-     * downstream cache busts, projection-side wipes that the framework
-     * doesn't reach (e.g., search indexes, ETL caches). The framework's own
-     * cache is invalidated by `forget()` itself before the event fires.
-     */
-    forgotten: {
-        stream: string;
-        at: Date;
-        eventCount: number;
-    };
-    /**
-     * A store operation failed during the drain loop. Fires on
-     * every failed drain cycle — typically a {@link StoreError} from a
-     * degraded backend — carrying the orchestrator circuit breaker's state
-     * after the failure (`open` means the drain loop has backed off and will
-     * retry after the cooldown). Listen to alert on a degraded store; the
-     * framework logs the same error regardless. Emitted only when a listener
-     * is registered (Node's `EventEmitter` throws on an unhandled `"error"`).
-     */
-    error: {
-        error: unknown;
-        circuit: CircuitState;
-    };
-};
-/**
- * Options for {@link Act} construction (passed via {@link ActBuilder.build}).
- *
- * @property maxSubscribedStreams - Cap for the LRU tracking what each
- *   dynamically resolved reaction target was last subscribed at. Statically
- *   declared targets are held outside it and never evicted, so their lane
- *   and priority stay owned by the build-time subscribe.
- *   Default: {@link DEFAULT_MAX_SUBSCRIBED_STREAMS}.
- * @property settleDebounceMs - Debounce window (ms) used by `settle()` when
- *   the caller doesn't pass `SettleOptions.debounceMs`. Tune this once per
- *   Act instance instead of threading the value through every call site.
- *   Default: {@link DEFAULT_SETTLE_DEBOUNCE_MS}.
- */
-export type ActOptions<TLanes extends string = string> = {
-    readonly maxSubscribedStreams?: number;
-    readonly settleDebounceMs?: number;
-    /**
-     * Per-Act ports. When set, this Act runs against the
-     * provided store + cache instead of the singletons — threaded via
-     * AsyncLocalStorage so internals are unchanged. Both are required
-     * together (a shared cache across distinct stores would collide on
-     * stream keys). Omit for the singleton path.
-     */
-    readonly scoped?: Scoped;
-    /**
-     * Correlation-id generator for originating actions. When
-     * omitted, Act uses {@link default_correlator}, which produces a
-     * readable, time-monotonic-within-window, lowercase id of the form
-     * `{state[:4]}-{action[:4]}-{ts}{rnd}` (18 chars).
-     *
-     * Reactions inherit `reactingTo.meta.correlation` so the chain stays
-     * intact — the delegate is only consulted on originating commits and
-     * for the close-the-books transaction.
-     */
-    readonly correlator?: Correlator;
-    /** Restrict this process to a subset of declared lanes. */
-    readonly onlyLanes?: ReadonlyArray<TLanes>;
-    /**
-     * Subscribe to {@link Store.notify} on this instance. Defaults
-     * to `true`. Set `false` on instances that only commit and never
-     * react — the subscriber-connection budget is the practical scaling
-     * ceiling for the notify/listen pattern, and writer-only fleets
-     * spend it for nothing when they subscribe to a channel they never
-     * read. Commits still emit notifications (that's part of the
-     * store's commit protocol); only the subscriber side is gated.
-     */
-    readonly listen?: boolean;
-    /**
-     * Run the local reaction pipeline on this instance. Defaults
-     * to `true`. Set `false` on writer-only or sidecar instances: drain
-     * controllers' auto-cycle workers don't start, `correlate()` /
-     * `drain()` / `settle()` become no-ops, and the notify handler
-     * skips its drain-wakeup arm (but still emits the `notified`
-     * lifecycle event so observability sidecars work).
-     */
-    readonly drain?: boolean;
-    /**
-     * Orchestrator circuit breaker for the drain loop. After
-     * `failureThreshold` consecutive store failures the breaker opens and
-     * the drain loop skips `claim()` for `cooldownMs` instead of hammering a
-     * down backend, then allows a half-open trial. Out-of-range values throw
-     * a `ZodError` at `act().build()`. Defaults: threshold 5, cooldown 30s.
-     */
-    readonly circuitBreaker?: CircuitBreakerOptions;
-    /**
-     * @deprecated Accepted, validated, and ignored. It paced the off-hours
-     * re-check of the old autoclose sweep; the synthesized autoclose reaction now derives its re-check
-     * directly from `autocloseWindow` — a tick landing outside the window
-     * parks until the exact instant the window opens, so there is no
-     * polling cadence to configure (and nothing minute-denominated on the
-     * close surface). Still validated as an integer `[1, 1440]` so typos
-     * keep failing loudly at `act().build()`. Will be removed in the next
-     * major.
-     */
-    readonly autocloseCycleMinutes?: number;
-    /**
-     * @deprecated Unused since the autoclose sweep was replaced by a
-     * synthesized per-aggregate reaction — nothing pages the store in
-     * batches anymore, so nothing reads this. Accepted and validated
-     * (`[1, 1024]`) for compatibility; will be removed in the next major.
-     */
-    readonly closeBatchSize?: number;
-    /**
-     * @deprecated Unused: the sweep that yielded between
-     * successive `Store.truncate` calls no longer exists; closes are
-     * staged per stream by the autoclose reaction. Accepted and validated
-     * (`[0, 1000]`) for compatibility; will be removed in the next major.
-     */
-    readonly closeYieldMs?: number;
-    /**
-     * @deprecated Unused: the sweep-side predicate try/catch
-     * this flag steered no longer exists; a throwing policy predicate now
-     * follows the reaction retry path (`blockOnError: false`, three
-     * retries). Accepted for compatibility; will be removed in the next
-     * major.
-     */
-    readonly closeOnError?: boolean;
-    /**
-     * Optional off-hours window restricting when autoclose evaluates. A
-     * synthesized autoclose reaction that triggers outside the window
-     * defers to the next instant the window opens — derived from the
-     * window itself, no polling cadence. Hours are `[0, 23]` integers in
-     * `timeZone` (IANA, default `"UTC"`, DST-correct); `start > end` is
-     * an overnight window (e.g. `{ start: 22, end: 6 }`). Omit to
-     * evaluate regardless of clock time.
-     */
-    readonly autocloseWindow?: {
-        readonly start: number;
-        readonly end: number;
-        readonly timeZone?: string;
-    };
-    /**
-     * Validate folded state against its declared Zod schema after every
-     * reduction. Off by default.
-     *
-     * When `true`, each time an event is folded into state — on the
-     * command path (`do`), on `load`/replay, and inside projection-fold
-     * projections — the merged full state is parsed against the owning
-     * state's `state({ Name: schema })` schema. A reducer that produces
-     * schema-violating state (the calculator divide-by-zero NaN
-     * class) throws a {@link ValidationError} at the triggering event,
-     * whose `target` names the state and the event (`<state>.<event>#<id>`)
-     * — instead of the bad value propagating and surfacing hops later as a
-     * confusing downstream error.
-     *
-     * This is a **debugging / CI aid, not a production guard**. Turn it on
-     * in development and CI to catch total-reducer bugs at the source; the
-     * framework already validates action inputs and emitted events, so the
-     * reduced state is the one shape it otherwise trusts. The per-event
-     * patch step is selected **once at `build()`** (the same way the
-     * orchestrator picks bare vs trace-decorated store ops from the log
-     * level): when `false` (the default) the fold loop is byte-identical to
-     * a bare reduction — the validating patch step is never selected, so
-     * there is no per-event cost, not even a branch.
-     */
-    readonly validateFoldedState?: boolean;
-};
+import { type ActLifecycleEvents, type ActOptions } from "./types/act.js";
+import type { Actor, AsOf, AuditCategory, AuditFinding, AuditOptions, BatchHandler, CloseResult, CloseTarget, Committed, DoOptions, Drain, DrainOptions, EventSink, EventSource, IAct, LaneConfig, LoadTarget, PatchFn, Query, Registry, ScanOptions, ScanResult, Schema, SchemaRegister, Schemas, SettleOptions, ShutdownOptions, Snapshot, State, StreamFilter, StreamPosition, Target } from "./types/index.js";
 /**
  * @category Orchestrator
  * @see Store
  *
- * Main orchestrator for event-sourced state machines and workflows.
- *
- * It manages the lifecycle of actions, reactions, and event streams, providing APIs for loading state, executing actions, querying events, and draining reactions.
- *
- * ## Usage
+ * The orchestrator: executes actions, loads state, queries events, and runs
+ * the reactions each commit frees (on its own, unless `autoSettle: false`).
  *
  * ```typescript
  * const app = act().withState(Counter).build();
  * await app.do("increment", { stream: "counter1", actor }, { by: 1 });
  * const snapshot = await app.load(Counter, "counter1");
- * await app.drain();
  * ```
  *
- * - Register event listeners with `.on("committed", ...)` and `.on("acked", ...)` to react to lifecycle events.
- * - Use `.query()` to analyze event streams for analytics or debugging.
- *
  * @template TSchemaReg SchemaRegister for state
  * @template TEvents Schemas for events
  * @template TActions Schemas for actions
@@ -231,14 +24,15 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     private readonly _breaker;
     private readonly _listen;
     private readonly _drain;
+    private readonly _auto_settle;
     /** Whether any event has a reaction; nothing arms without one. */
     private readonly _reactive;
     private readonly _drain_controllers;
     private readonly _correlate;
     private readonly _settle;
     private _poll;
-    /** The deprecated `start_correlations` callback, while the poll runs. */
-    private _on_discovered;
+    /** The poll's correlate `limit`, used by every settle pass while it runs. */
+    private _poll_limit;
     /**
      * Wired at construction against the store current then, so a store
      * injected after `build()` is never notified.
@@ -318,21 +112,14 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     private _build_settle;
     private _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.
-     *
-     * 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.
+     * 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.
+     *
+     * 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).
@@ -347,15 +134,10 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     /** Failures are logged, never thrown: `notify` is a hint. */
     private _wire_notify;
     /**
-     * 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
@@ -429,9 +211,7 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      *
      * 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
      *
@@ -486,31 +266,23 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
         eventCount: number;
     }>;
     /**
-     * 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();
@@ -518,41 +290,36 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      *
      * @see {@link settle} for debounced correlate→drain with lifecycle events
      * @see {@link correlate} for dynamic stream discovery
-     * @see {@link start_correlations} for automatic correlation
      */
     drain(options?: DrainOptions): Promise<Drain<TEvents>>;
     private _arm_all;
+    /**
+     * Settles what a change armed (a commit, a reset, an unblock, a restore,
+     * a notification from another process), unless the app walks the
+     * pipeline itself (`autoSettle: false`).
+     */
+    private _settle_armed;
+    /** Schedules a settle pass; writer-only instances (`drain: false`) skip it. */
+    private _schedule;
     /** Arms only the lanes these events react on; true when any was armed. */
     private _arm_for_event_names;
     /** In parallel, so a slow lane never holds up a fast one. */
     private _drain_all;
     /**
-     * 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
      */
     correlate(query?: Query): Promise<{
         subscribed: number;
@@ -576,9 +343,6 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      *   reads (default 100). The scan always starts at the correlation
      *   checkpoint, so `after` is ignored.
      * @param frequency - Milliseconds between ticks (default: 10000)
-     * @param callback - Called with the number of newly subscribed streams
-     *   after each correlate pass that found some.
-     *   @deprecated Listen to the `"settled"` lifecycle event instead.
      * @returns `true` if the poll started, `false` if one is already running
      *
      * @example
@@ -591,7 +355,7 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      * @see {@link settle} for what each tick runs
      * @see {@link stop_correlations} to stop the poll
      */
-    start_correlations(query?: Query, frequency?: number, callback?: (subscribed: number) => void): boolean;
+    start_correlations(query?: Query, frequency?: number): boolean;
     /**
      * Stops the poll started by {@link start_correlations}. Idempotent, and
      * called by `shutdown()`.
@@ -600,25 +364,24 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      */
     stop_correlations(): void;
     /**
-     * Cancels any pending or active settle cycle.
+     * Drops the settle pass scheduled but not yet started. A cycle already
+     * running finishes; later changes schedule new passes.
      *
      * @see {@link settle}
      */
     stop_settling(): void;
     /**
-     * Reset reaction stream watermarks and request a drain on the next
-     * `drain()` / `settle()` cycle.
+     * Reset reaction stream watermarks and settle them, replaying their
+     * 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.
-     *
-     * Pair with `app.settle()` (or a single `app.drain()` for small streams).
-     * `settle()` loops correlate→drain until no progress is made, so one call
-     * fully catches up paginated streams without forcing callers to roll
-     * their own loop.
+     * 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
@@ -626,7 +389,7 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      * @example Rebuild a projection (production)
      * ```typescript
      * await app.reset(["my-projection"]);
-     * app.settle({ eventLimit: 1000 });   // emits "settled" when fully replayed
+     * app.settle({ eventLimit: 1000 }); // optional: bigger batches; emits "settled"
      * ```
      *
      * @see {@link Store.reset} for the underlying store primitive
@@ -642,11 +405,9 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      * {@link reset}, which rebuilds from event 0 (suitable for projection
      * rebuilds, wrong for "I fixed the bug, please retry").
      *
-     * Wraps `store().unblock(streams)` and raises the orchestrator's
-     * internal "needs drain" flag so a settled app picks up the now-free
-     * streams on the next cycle. Equivalent to calling `store().unblock(...)`
-     * directly, but `store().unblock(...)` alone leaves the flag
-     * untouched.
+     * Wraps `store().unblock(streams)` and settles the now-free streams on
+     * its own. `store().unblock(...)` alone leaves them waiting for the next
+     * commit.
      *
      * @param input - Stream names to unblock, or a {@link StreamFilter} for bulk recovery
      * @returns Count of streams that were actually flipped (were blocked)
@@ -723,64 +484,30 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
         limit?: number;
     }): Promise<StreamPosition[]>;
     /**
-     * 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}.
      */
     audit(categories?: AuditCategory[], options?: AuditOptions): AsyncIterable<AuditFinding>;
     /**
-     * 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.**
-     *
-     * @param filter - Selection criteria (regex by default).
+     * 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, like {@link query}).
      * @param priority - New priority value. Set as-is — no clamp.
      * @returns Count of streams whose priority changed.
      *
@@ -790,36 +517,17 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
      * ```
      *
      * @see {@link Store.prioritize} for the underlying primitive
-     * @see {@link claim} for how priority biases scheduling
      */
     prioritize(filter: StreamFilter, priority: number): Promise<number>;
     /** Shared by `close()` and reaction-requested closes. */
     private _run_close;
     /**
-     * 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[] }`
@@ -836,25 +544,28 @@ export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents ex
     /**
      * Debounced, non-blocking correlate→drain cycle.
      *
-     * Call this after `app.do()` (or `app.reset()`) to schedule a background
-     * drain. Multiple rapid calls within the debounce window are coalesced
-     * into a single cycle. Runs correlate→drain in a loop until a pass makes
-     * no progress — no new subscriptions, no events read, no streams leased —
-     * then emits
-     * the `"settled"` lifecycle event. This means a single `settle()` call
-     * fully catches up paginated streams (e.g. after `reset()` on a long
-     * projection) without forcing callers to loop.
+     * A local change that frees reaction work (a commit, `reset()`,
+     * `unblock()`, `restore()`) schedules this on its own unless the app
+     * sets `autoSettle: false`. Call it at startup, to run what was pending
+     * before a restart, or with options for the next pass. A pass already
+     * scheduled is never put off: calls before it runs join it (a shorter
+     * `debounceMs` brings it forward), and a call during a running cycle
+     * queues one more pass after it. Runs correlate→drain in a loop until a pass makes no
+     * progress — no new subscriptions, no events read, no streams leased —
+     * then emits the `"settled"` lifecycle event, so one call fully catches
+     * up paginated streams without forcing callers to loop.
      *
      * @param options - Settle configuration — see {@link SettleOptions} for fields:
-     *   `debounceMs` (default 10), `correlate` (default `{ after: -1, limit: 100 }`),
+     *   `debounceMs` (default 10), `correlate.limit` (default 100, or the
+     *   poll's limit while `start_correlations` runs; `after` is always the
+     *   checkpoint),
      *   `maxPasses` (default `Infinity` — kill-switch for runaway loops),
      *   `streamLimit` (default 10), `eventLimit` (default 10),
      *   `leaseMillis` (default 10000).
      *
-     * @example API mutations
+     * @example Startup
      * ```typescript
-     * await app.do("CreateItem", target, input);
-     * app.settle(); // non-blocking, returns immediately
+     * app.settle(); // run what was pending before the restart
      *
      * app.on("settled", (drain) => {
      *   // notify SSE clients, invalidate caches, etc.