@rotorsoft/act 0.35.1 → 0.35.2

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

@@ -0,0 +1,672 @@
+import type { Actor, AsOf, BatchHandler, BlockedLease, CloseResult, CloseTarget, Committed, Drain, DrainOptions, IAct, Lease, PrioritizeFilter, Query, Registry, Schema, SchemaRegister, Schemas, SettleOptions, Snapshot, State, StoreNotification, 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
+ *
+ * ```typescript
+ * const app = new Act(registry, 100);
+ * 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
+ * @template TStateMap Map of state names to state schemas
+ * @template TActor Actor type extending base Actor
+ */
+/**
+ * Default LRU cap for the subscribed-streams cache. Apps that mint many
+ * dynamic targets (one per aggregate) should override via
+ * {@link ActOptions.maxSubscribedStreams} based on expected concurrency.
+ */
+export declare const DEFAULT_MAX_SUBSCRIBED_STREAMS = 1000;
+/**
+ * Default debounce window (ms) for `settle()` when neither the per-call
+ * `SettleOptions.debounceMs` nor `ActOptions.settleDebounceMs` is set.
+ * Coalesces commits in the same tick and small bursts; sub-perceptible
+ * latency on the `"settled"` signal.
+ */
+export declare const DEFAULT_SETTLE_DEBOUNCE_MS = 10;
+/**
+ * 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.
+ */
+export type ActLifecycleEvents<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas> = {
+    committed: Snapshot<TSchemaReg, 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;
+};
+/**
+ * Options for {@link Act} construction (passed via {@link ActBuilder.build}).
+ *
+ * @property maxSubscribedStreams - Cap for the LRU set tracking already-
+ *   subscribed reaction streams. 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 = {
+    readonly maxSubscribedStreams?: number;
+    readonly settleDebounceMs?: number;
+};
+export declare class Act<TSchemaReg extends SchemaRegister<TActions>, TEvents extends Schemas, TActions extends Schemas, TStateMap extends Record<string, Schema> = Record<string, never>, TActor extends Actor = Actor> implements IAct<TEvents, TActions, TActor> {
+    readonly registry: Registry<TSchemaReg, TEvents, TActions>;
+    private readonly _states;
+    private _emitter;
+    /** Event names with at least one registered reaction (computed at build time) */
+    private readonly _reactive_events;
+    /** Drain pipeline driver: armed flag, concurrency lock, adaptive ratio. */
+    private readonly _drain;
+    /** Correlation state machine: lazy init, dynamic-resolver scan, periodic worker. */
+    private readonly _correlate;
+    /** Debounced correlate→drain catch-up loop. */
+    private readonly _settle;
+    /**
+     * Disposer for the cross-process notify subscription, set up eagerly
+     * during construction. Held as a promise because the subscription
+     * itself may be async (the PG adapter checks out a dedicated client
+     * and runs `LISTEN` before resolving). Resolves to `undefined` when
+     * the store doesn't implement `notify` or there are no registered
+     * reactions.
+     *
+     * **Contract:** the configured store must be injected via
+     * {@link store}`(adapter)` *before* calling `act()...build()`. The
+     * orchestrator wires notify against whatever store is current at
+     * construction time — late injection after build is unsupported.
+     */
+    private readonly _notify_disposer;
+    /**
+     * Emit a lifecycle event. The payload type is inferred from the event name
+     * via {@link ActLifecycleEvents}.
+     */
+    emit<E extends keyof ActLifecycleEvents<TSchemaReg, TEvents, TActions>>(event: E, args: ActLifecycleEvents<TSchemaReg, TEvents, TActions>[E]): boolean;
+    /**
+     * Register a listener for a lifecycle event. The listener receives the
+     * event-specific payload.
+     */
+    on<E extends keyof ActLifecycleEvents<TSchemaReg, TEvents, TActions>>(event: E, listener: (args: ActLifecycleEvents<TSchemaReg, TEvents, TActions>[E]) => void): this;
+    /**
+     * Remove a previously registered lifecycle listener.
+     */
+    off<E extends keyof ActLifecycleEvents<TSchemaReg, TEvents, TActions>>(event: E, listener: (args: ActLifecycleEvents<TSchemaReg, TEvents, TActions>[E]) => void): this;
+    /** Batch handlers for static-target projections (target → handler) */
+    private readonly _batch_handlers;
+    /** Event-sourcing handlers, optionally wrapped with trace decorators */
+    private readonly _es;
+    /** Correlate/drain pipeline ops, optionally wrapped with trace decorators */
+    private readonly _cd;
+    /**
+     * Event-name → owning state, computed at build time. The duplicate-event
+     * guard in merge.ts ensures one event name maps to at most one state, so
+     * this lookup is unambiguous. Used by `close()` to pick the right reducer
+     * set when seeding a `restart` snapshot in multi-state apps.
+     */
+    private readonly _event_to_state;
+    /** Logger resolved at construction time (after user port configuration) */
+    private readonly _logger;
+    /** Pre-bound IAct methods reused across drain cycles. Only `do` varies per
+     * payload (it captures the triggering event for reactingTo auto-inject). */
+    private readonly _bound_do;
+    private readonly _bound_load;
+    private readonly _bound_query;
+    private readonly _bound_query_array;
+    /** Reaction dispatchers built once and handed to runDrainCycle each cycle. */
+    private readonly _handle;
+    private readonly _handle_batch;
+    /**
+     * Create a new Act orchestrator. Prefer the {@link act} builder over
+     * direct construction — `act()...build()` wires the registry, merges
+     * partial states, and collects batch handlers from registered slices
+     * and projections in one pass.
+     *
+     * @param registry  Schemas for every event and action across registered states
+     * @param _states   Merged map of state name → state definition
+     * @param batchHandlers Static-target projection batch handlers (target → handler)
+     * @param options   Tuning knobs — see {@link ActOptions}
+     */
+    constructor(registry: Registry<TSchemaReg, TEvents, TActions>, _states?: Map<string, State<any, any, any>>, batchHandlers?: Map<string, BatchHandler<any>>, options?: ActOptions);
+    /**
+     * Subscribe to {@link Store.notify} when both the store and the
+     * registry support it. Returns the disposer (or `undefined` when no
+     * subscription was made). Errors during subscription are logged but
+     * never thrown — `notify` is a hint, not a contract.
+     */
+    private _wireNotify;
+    /**
+     * 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
+     *
+     * @template TKey - Action name from registered actions
+     * @param action - The name of the action to execute
+     * @param target - Target specification with stream ID and actor context
+     * @param payload - Action payload matching the action's schema
+     * @param reactingTo - Optional event that triggered this action (for correlation)
+     * @param skipValidation - Skip schema validation (use carefully, for performance)
+     * @returns Array of snapshots for all affected states (usually one)
+     *
+     * @throws {ValidationError} If payload doesn't match action schema
+     * @throws {InvariantError} If business rules are violated
+     * @throws {ConcurrencyError} If another process modified the stream
+     *
+     * @example Basic action execution
+     * ```typescript
+     * const snapshots = await app.do(
+     *   "increment",
+     *   {
+     *     stream: "counter-1",
+     *     actor: { id: "user1", name: "Alice" }
+     *   },
+     *   { by: 5 }
+     * );
+     *
+     * console.log(snapshots[0].state.count); // Current count after increment
+     * ```
+     *
+     * @example With error handling
+     * ```typescript
+     * try {
+     *   await app.do(
+     *     "withdraw",
+     *     { stream: "account-123", actor: { id: "user1", name: "Alice" } },
+     *     { amount: 1000 }
+     *   );
+     * } catch (error) {
+     *   if (error instanceof InvariantError) {
+     *     console.error("Business rule violated:", error.description);
+     *   } else if (error instanceof ConcurrencyError) {
+     *     console.error("Concurrent modification detected, retry...");
+     *   } else if (error instanceof ValidationError) {
+     *     console.error("Invalid payload:", error.details);
+     *   }
+     * }
+     * ```
+     *
+     * @example Reaction triggering another action (reactingTo auto-injected)
+     * ```typescript
+     * const app = act()
+     *   .withState(Order)
+     *   .withState(Inventory)
+     *   .on("OrderPlaced")
+     *     .do(async function reduceInventory(event, _stream, app) {
+     *       // Inside reaction handlers, reactingTo is auto-injected when omitted.
+     *       // The triggering event is used by default, maintaining the correlation chain.
+     *       await app.do(
+     *         "reduceStock",
+     *         { stream: "inventory-1", actor: { id: "sys", name: "system" } },
+     *         { amount: event.data.items.length }
+     *       );
+     *       // To use a different correlation, pass reactingTo explicitly:
+     *       // await app.do("reduceStock", target, payload, customEvent);
+     *     })
+     *     .to("inventory-1")
+     *   .build();
+     * ```
+     *
+     * @see {@link Target} for target structure
+     * @see {@link Snapshot} for return value structure
+     * @see {@link ValidationError}, {@link InvariantError}, {@link ConcurrencyError}
+     */
+    do<TKey extends keyof TActions>(action: TKey, target: Target<TActor>, payload: Readonly<TActions[TKey]>, reactingTo?: Committed<TEvents, string & keyof TEvents>, skipValidation?: boolean): Promise<Snapshot<TSchemaReg[TKey], TEvents>[]>;
+    /**
+     * Loads the current state snapshot for a specific stream.
+     *
+     * Reconstructs the current state by replaying events from the event store.
+     * Uses snapshots when available to optimize loading performance.
+     *
+     * Accepts either a State definition object or a state name string. When
+     * using a string, the merged state (from partial states registered via
+     * `.withState()`) is resolved by name.
+     *
+     * @template TNewState - State schema type
+     * @template TNewEvents - Event schemas type
+     * @template TNewActions - Action schemas type
+     * @param state - The state definition or state name to load
+     * @param stream - The stream ID (state instance identifier)
+     * @param callback - Optional callback invoked with the loaded snapshot
+     * @returns The current state snapshot for the stream
+     *
+     * @example Load by state definition
+     * ```typescript
+     * const snapshot = await app.load(Counter, "counter-1");
+     * console.log(snapshot.state.count);    // Current count
+     * console.log(snapshot.patches);        // Events since last snapshot
+     * ```
+     *
+     * @example Load by state name (useful with partial states)
+     * ```typescript
+     * const snapshot = await app.load("Ticket", "ticket-123");
+     * console.log(snapshot.state.title);    // Merged state from all partials
+     * ```
+     *
+     * @example Load multiple states
+     * ```typescript
+     * const [user, account] = await Promise.all([
+     *   app.load(User, "user-123"),
+     *   app.load(BankAccount, "account-456")
+     * ]);
+     * ```
+     *
+     * @see {@link Snapshot} for snapshot structure
+     */
+    load<TNewState extends Schema, TNewEvents extends Schemas, TNewActions extends Schemas>(state: State<TNewState, TNewEvents, TNewActions>, stream: string, callback?: (snapshot: Snapshot<TNewState, TNewEvents>) => void, asOf?: AsOf): Promise<Snapshot<TNewState, TNewEvents>>;
+    load<TKey extends keyof TStateMap & string>(name: TKey, stream: string, callback?: (snapshot: Snapshot<TStateMap[TKey], TEvents>) => void, asOf?: AsOf): Promise<Snapshot<TStateMap[TKey], TEvents>>;
+    /**
+     * Queries the event store for events matching a filter.
+     *
+     * Use this for analyzing event streams, generating reports, or debugging.
+     * The callback is invoked for each matching event, and the method returns
+     * summary information (first event, last event, total count).
+     *
+     * 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 callback - Optional callback invoked for each matching event
+     * @returns Object with first event, last event, and total count
+     *
+     * @example Query all events for a stream
+     * ```typescript
+     * const { first, last, count } = await app.query(
+     *   { stream: "counter-1" },
+     *   (event) => console.log(event.name, event.data)
+     * );
+     * console.log(`Found ${count} events from ${first?.id} to ${last?.id}`);
+     * ```
+     *
+     * @example Query specific event types
+     * ```typescript
+     * const { count } = await app.query(
+     *   { name: "UserCreated", limit: 100 },
+     *   (event) => {
+     *     console.log("User created:", event.data.email);
+     *   }
+     * );
+     * ```
+     *
+     * @example Query events in time range
+     * ```typescript
+     * const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
+     * const { count } = await app.query({
+     *   created_after: yesterday,
+     *   stream: "user-123"
+     * });
+     * console.log(`User had ${count} events in last 24 hours`);
+     * ```
+     *
+     * @see {@link query_array} for loading events into memory
+     */
+    query(query: Query, callback?: (event: Committed<TEvents, keyof TEvents>) => void): Promise<{
+        first?: Committed<TEvents, keyof TEvents>;
+        last?: Committed<TEvents, keyof TEvents>;
+        count: number;
+    }>;
+    /**
+     * Queries the event store and returns all matching events in memory.
+     *
+     * **Use with caution** - this loads all results into memory. For large result sets,
+     * use {@link query} with a callback instead to process events incrementally.
+     *
+     * @param query - The query filter (same as {@link query})
+     * @returns Array of all matching events
+     *
+     * @example Load all events for a stream
+     * ```typescript
+     * const events = await app.query_array({ stream: "counter-1" });
+     * console.log(`Loaded ${events.length} events`);
+     * events.forEach(event => console.log(event.name, event.data));
+     * ```
+     *
+     * @example Get recent events
+     * ```typescript
+     * const recent = await app.query_array({
+     *   stream: "user-123",
+     *   limit: 10
+     * });
+     * ```
+     *
+     * @see {@link query} for large result sets
+     */
+    query_array(query: Query): Promise<Committed<TEvents, keyof TEvents>[]>;
+    /**
+     * 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
+     *
+     * 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()` to discover target streams. For a higher-level
+     * API that handles debouncing, correlation, and signaling automatically, use {@link settle}.
+     *
+     * @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
+     * ```typescript
+     * await app.do("createUser", target, payload);
+     * await app.correlate();
+     * await app.drain();
+     * ```
+     *
+     * @example In production, prefer settle()
+     * ```typescript
+     * await app.do("CreateItem", target, input);
+     * app.settle(); // debounced correlate→drain, emits "settled"
+     * ```
+     *
+     * @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>>;
+    /**
+     * 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.
+     *
+     * @param query - Query filter to scan for new correlations
+     * @param query - Scan filter — see {@link Query} for fields (typically
+     *   `{ after: <event-id>, limit: <count> }`)
+     * @returns Object with newly leased streams and last scanned event ID
+     *
+     * @example Manual correlation
+     * ```typescript
+     * // Scan for new streams
+     * const { leased, last_id } = await app.correlate({ after: 0, limit: 100 });
+     * console.log(`Found ${leased.length} new streams`);
+     *
+     * // Save last_id for next scan
+     * await saveCheckpoint(last_id);
+     * ```
+     *
+     * @example Dynamic stream creation
+     * ```typescript
+     * const app = act()
+     *   .withState(User)
+     *   .withState(UserStats)
+     *   .on("UserLoggedIn")
+     *     .do(async (event) => ["incrementLoginCount", {}])
+     *     .to((event) => ({
+     *       target: `stats-${event.stream}` // Dynamic target per user
+     *     }))
+     *   .build();
+     *
+     * // Discover stats streams as users log in
+     * await app.correlate();
+     * ```
+     *
+     * @see {@link start_correlations} for automatic periodic correlation
+     * @see {@link stop_correlations} to stop automatic correlation
+     */
+    correlate(query?: Query): Promise<{
+        subscribed: number;
+        last_id: number;
+    }>;
+    /**
+     * Starts automatic periodic correlation worker for discovering new streams.
+     *
+     * The correlation worker runs in the background, scanning for new events and identifying
+     * new target streams based on reaction resolvers. It maintains a sliding window that
+     * advances with each scan, ensuring all events are eventually correlated.
+     *
+     * This is useful for dynamic stream creation patterns where you don't know all streams
+     * upfront - they're discovered as events arrive.
+     *
+     * **Note:** Only one correlation worker can run at a time per Act instance.
+     *
+     * @param query - Query filter for correlation scans — see {@link Query}
+     *   (typically `{ after: -1, limit: 100 }`)
+     * @param frequency - Correlation frequency in milliseconds (default: 10000)
+     * @param callback - Optional callback invoked with newly discovered streams
+     * @returns `true` if worker started, `false` if already running
+     *
+     * @example Start automatic correlation
+     * ```typescript
+     * // Start correlation worker scanning every 5 seconds
+     * app.start_correlations(
+     *   { after: 0, limit: 100 },
+     *   5000,
+     *   (leased) => {
+     *     console.log(`Discovered ${leased.length} new streams`);
+     *   }
+     * );
+     *
+     * // Later, stop it
+     * app.stop_correlations();
+     * ```
+     *
+     * @example With checkpoint persistence
+     * ```typescript
+     * // Load last checkpoint
+     * const lastId = await loadCheckpoint();
+     *
+     * app.start_correlations(
+     *   { after: lastId, limit: 100 },
+     *   10000,
+     *   async (leased) => {
+     *     // Save checkpoint for next restart
+     *     if (leased.length) {
+     *       const maxId = Math.max(...leased.map(l => l.at));
+     *       await saveCheckpoint(maxId);
+     *     }
+     *   }
+     * );
+     * ```
+     *
+     * @see {@link correlate} for manual one-time correlation
+     * @see {@link stop_correlations} to stop the worker
+     */
+    start_correlations(query?: Query, frequency?: number, callback?: (subscribed: number) => void): boolean;
+    /**
+     * Stops the automatic correlation worker.
+     *
+     * Call this to stop the background correlation worker started by {@link start_correlations}.
+     * This is automatically called when the Act instance is disposed.
+     *
+     * @example
+     * ```typescript
+     * // Start correlation
+     * app.start_correlations();
+     *
+     * // Later, stop it
+     * app.stop_correlations();
+     * ```
+     *
+     * @see {@link start_correlations}
+     */
+    stop_correlations(): void;
+    /**
+     * Cancels any pending or active settle cycle.
+     *
+     * @see {@link settle}
+     */
+    stop_settling(): void;
+    /**
+     * Reset reaction stream watermarks and request a drain on the next
+     * `drain()` / `settle()` cycle.
+     *
+     * 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.
+     *
+     * @param streams - Reaction target streams (e.g., projection names) to reset
+     * @returns Count of streams that were actually reset
+     *
+     * @example Rebuild a projection (production)
+     * ```typescript
+     * await app.reset(["my-projection"]);
+     * app.settle({ eventLimit: 1000 });   // emits "settled" when fully replayed
+     * ```
+     *
+     * @example Rebuild a projection (tests / scripts)
+     * ```typescript
+     * await app.reset(["my-projection"]);
+     * await app.drain({ eventLimit: 1000 });   // small streams: one pass is enough
+     * ```
+     *
+     * @see {@link Store.reset} for the underlying store primitive
+     * @see {@link settle} for the debounced full-catch-up loop
+     */
+    reset(streams: string[]): Promise<number>;
+    /**
+     * Bulk-update scheduling priority for streams matching `filter`.
+     *
+     * Operator-grade override of the `claim()` lagging-frontier
+     * ordering (ACT-102). 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).
+     * @param priority - New priority value. Set as-is — no clamp.
+     * @returns Count of streams whose priority changed.
+     *
+     * @example Boost a specific projection mid-replay
+     * ```typescript
+     * await app.prioritize({ stream: "^proj-orders$", stream_exact: false }, 10);
+     * ```
+     *
+     * @example Drop all audit projections to background
+     * ```typescript
+     * await app.prioritize({ source: "^audit-" }, -5);
+     * ```
+     *
+     * @example Reset everyone to default
+     * ```typescript
+     * await app.prioritize({}, 0);
+     * ```
+     *
+     * @see {@link Store.prioritize} for the underlying primitive
+     * @see {@link claim} for how priority biases scheduling
+     */
+    prioritize(filter: PrioritizeFilter, priority: number): Promise<number>;
+    /**
+     * 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
+     *
+     * @param targets - Per-stream close options (stream, restart?, archive?)
+     * @returns `{ truncated: TruncateResult, skipped: string[] }`
+     *
+     * @example Archive and close
+     * ```typescript
+     * await app.close([
+     *   { stream: "order-123", archive: async () => { await archiveToS3("order-123"); } },
+     *   { stream: "order-456" },
+     * ]);
+     * ```
+     *
+     * @example Close with restart (state loaded automatically after guard)
+     * ```typescript
+     * await app.close([
+     *   { stream: "counter-1", restart: true },
+     *   { stream: "counter-2" },  // tombstoned
+     * ]);
+     * ```
+     */
+    close(targets: CloseTarget[]): Promise<CloseResult>;
+    /**
+     * 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 acks, no blocks — 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.
+     *
+     * @param options - Settle configuration — see {@link SettleOptions} for fields:
+     *   `debounceMs` (default 10), `correlate` (default `{ after: -1, limit: 100 }`),
+     *   `maxPasses` (default `Infinity` — kill-switch for runaway loops),
+     *   `streamLimit` (default 10), `eventLimit` (default 10),
+     *   `leaseMillis` (default 10000).
+     *
+     * @example API mutations
+     * ```typescript
+     * await app.do("CreateItem", target, input);
+     * app.settle(); // non-blocking, returns immediately
+     *
+     * app.on("settled", (drain) => {
+     *   // notify SSE clients, invalidate caches, etc.
+     * });
+     * ```
+     *
+     * @see {@link drain} for single synchronous drain cycles
+     * @see {@link correlate} for manual correlation
+     */
+    settle(options?: SettleOptions): void;
+}
+//# sourceMappingURL=act.d.ts.map

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

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