@qodeca/xezar 0.13.0 → 0.14.0

package/dist/mcp/event-controller.d.ts

@@ -0,0 +1,230 @@
+import type { McpJournalRow, McpProjectOccupiedError, McpSessionExpiredError } from '../contract/index.js';
+import { type ProjectOwnership } from '../workspace/project-owner.ts';
+import { type EventJournal } from './event-journal.ts';
+/**
+ * The non-model event controller (#107): it follows ONE project's event journal (#103) on behalf
+ * of the logical MCP session that owns the project (#99), and hands significant events to a
+ * client-specific reaction adapter (#108–#110). It never starts a model turn of its own.
+ *
+ * WHAT IT CONSUMES, AND DOES NOT DECIDE. The event identity, order, replay and acknowledgement
+ * model are D-05 (`docs/features/mcp-server/mcp-d05-async-event-contract-decision.md` § 6); the
+ * numbers are D-09 (`mcp-d09-limits-retention-packaging-decision.md` § 3). Every constant below
+ * names the one it reuses.
+ *
+ * - **Source.** The project journal only (`EventJournal`), never the workspace stream — requirements
+ *   § 8 forbids an unfiltered workspace stream reaching MCP, and the journal already holds exactly
+ *   E-01–E-06 for exactly one project. The journal is also the QUEUE: undelivered rows are the
+ *   journal between this controller's position and its head, so the queue is durable, gapless and
+ *   bounded by B-19 retention, and no event lives only in this object's memory.
+ * - **Coalescing.** D-05 N3 decided *no coalescing window*: rows are never merged, delayed or
+ *   dropped. What coalesces is DISPATCHES: at most one is in flight, and every row that arrived
+ *   before it starts rides in it, up to one journal page (B-20, 100 rows; B-01, 40 000 bytes).
+ *   So a burst of N rows appended in one tick reaches the adapter as `ceil(N / 100)` dispatches,
+ *   each row intact and in `journalSeq` order, and rows that arrive while a dispatch is in flight
+ *   go out together in the next one.
+ * WHOSE FACTS ARE WHOSE. This controller serves one SESSION, and its cursors belong to the project's
+ * journal. Whether the leader is reachable is a fact about the LEADER, so it is not kept here: the
+ * adapter records it (`LeaderDelivery`), and it therefore survives a session change and is never
+ * inherited by a leader that has just been attached (QA on #311, round five, both directions).
+ *
+ * - **Delivery is not reaction (F-20).** `deliver` hands rows to the client application and is
+ *   non-model. Whether a model turn then starts is the adapter's own, client-specific decision, and
+ *   it reports that separately through `recordReaction`. The three D-05 § 6.6 cursors are kept
+ *   apart: `deliveredSeq` (this controller, on a resolved `deliver`), `ackedSeq` (the leader,
+ *   through an explicit tool call — `ack`) and `reactedSeq` (the adapter, when a turn carrying the
+ *   rows really started). `reactedSeq` lagging `deliveredSeq` is a normal state, not a fault.
+ * - **Non-model traffic only (N-06).** The heartbeat, a transport retry and an acknowledgement
+ *   never call anything that can start a turn: the heartbeat calls the adapter's optional
+ *   `heartbeat`, a retry re-sends the SAME undelivered rows, and `ack` touches only a number.
+ *   Rows already delivered in this session are never dispatched again.
+ * - **At-least-once (D-05 § 6.6).** A new session resumes after the leader's last ACK, not after
+ *   the last delivery: a row handed to a previous client that the leader never acknowledged is
+ *   outstanding, and F-21 says reconnect delivers it. In production the leader acknowledges through
+ *   the pull tool (`leader_events ack`), so that record is the ACK read here (`acknowledged`, #332):
+ *   one source of truth, not two cursors that can disagree. The leader deduplicates on `eventId`. The
+ *   echo guard (drop a `leader` row whose `causedBy` is the adapter's own operation) is the
+ *   adapter's, per D-05 § 6.3: rows reach it whole.
+ *
+ * ONE LOGICAL OWNER. This controller and the MCP bridge are one client, not two (compatibility
+ * report, "Recommended architecture"; F-18). So the controller never acquires: it is handed the
+ * project's `ProjectOwnership` and the session key the transport acquired with, starts only while
+ * that session is the live owner, and re-checks it before every dispatch and at every heartbeat.
+ * It never calls `acquire` or `release` — the lease is the transport's, released on connection
+ * close (D-02.4) — so it can neither create a second claim nor end the session it serves. A
+ * second controller for the same project is refused: a competing session with project-occupied,
+ * and a second controller for the SAME session too, because two dispatchers over one journal are
+ * the "two independent streams delivering duplicates" risk of requirements § 12.
+ *
+ * INERT WITHOUT A CLIENT (N-07). With no adapter the controller subscribes to nothing, starts no
+ * timer, reads no ownership and writes no file. The journal keeps accumulating rows exactly as it
+ * does with no controller at all.
+ *
+ * ## Every state, and who fires each exit
+ *
+ * No exit below is a human action, and no state holds a queued row without an on-by-default path
+ * to the adapter.
+ *
+ * | State | Exit | Who fires it | If nobody fires it |
+ * | --- | --- | --- | --- |
+ * | inert | — (terminal for this object) | — | correct: no client, nothing is owed; rows stay in the journal |
+ * | idle | → dispatching | a journal append (subscription) or the heartbeat tick | the heartbeat tick (B-17, 30 s) re-reads the journal, so a missed wakeup costs at most one interval |
+ * | idle | → disconnected | a failed heartbeat probe | stays idle — the correct resting state |
+ * | dispatching | → idle | `deliver` resolving | the attempt is aborted after one heartbeat interval and counts as a transport drop |
+ * | dispatching | → recovering | `deliver` rejecting, or the attempt timing out | — (the timeout above always fires) |
+ * | recovering | → idle / → disconnected | the round itself: at most 5 attempts, full-jitter backoff ≤ 200 ms | — (bounded) |
+ * | disconnected | → dispatching | the heartbeat tick (one new bounded round per interval) or the adapter's `wake` on reconnect | the heartbeat timer is on by default, so rows are retried every 30 s for as long as the session owns the project |
+ * | any active state | → ended | `close` (the transport, on connection close), or losing ownership, found at the next dispatch or heartbeat | lease expiry (30 s, B-14) makes the owner check fail at the next heartbeat |
+ * | ended | — (terminal) | — | rows stay in the journal and the persisted cursors; the next session's controller resumes after the last ack |
+ *
+ * What reaches a terminal state BECAUSE of this controller: nothing but this object. It holds no
+ * run, queue slot, lease or worktree, and ending it touches none.
+ *
+ * ## Where its state lives
+ *
+ * `<dataDir>/mcp/event-controller.json`, beside the journal: `{ v, projectId, epoch, deliveredSeq,
+ * ackedSeq, reactedSeq, floorSeq }`, written by atomic tmp+rename after every change (D-05 N4:
+ * persisted per delivery, not batched). Written, never required. With a leader record (production)
+ * the file keeps only real history — what was pushed and what reacted — and WHERE pushing starts
+ * comes from the leader's record. Standalone, no file means a first session that starts at the
+ * journal head (nothing was ever owed to a leader that did not exist; it reads current state, F-21),
+ * and an unreadable file starts at the head WITH a stated gap. Either way no reported cursor is ever
+ * set to a position nothing reached (QA on #311): a start is a floor, not a delivery. An unwritable
+ * directory keeps the cursors in memory with one warning.
+ */
+/** Heartbeat and liveness period. B-17 / D-05 N6, reusing the hub's `HEARTBEAT_MS` (`server/ws.ts`). */
+export declare const EVENT_CONTROLLER_HEARTBEAT_MS = 30000;
+/**
+ * Delivery attempts per recovery round, and the cap on the doubling full-jitter backoff between them.
+ * D-01, D-05 and D-09 fix no delivery-retry numbers (B-16 is the bridge's own "no retry" on a dead
+ * socket, which this is not), so the bounded-recovery shape is the one D-02 measured and D-09 adopted
+ * as B-15 for the same kind of local contention, rather than a new one.
+ */
+export declare const EVENT_DELIVERY_ATTEMPTS = 5;
+export declare const EVENT_DELIVERY_BACKOFF_CAP_MS = 200;
+/** Stated to the adapter when rows this session was owed are gone (D-05 § 6.5, A-21). */
+export interface EventRecovery {
+    readonly required: 'current-state';
+    readonly oldestSeq: number | null;
+    readonly latestSeq: number;
+    readonly message: string;
+}
+/** One dispatch: consecutive journal rows, oldest first, never merged, never rewritten. */
+export interface EventDispatch {
+    readonly projectId: string;
+    readonly events: readonly McpJournalRow[];
+    /** Present when a gap was detected: read current state before acting on `events`. */
+    readonly recovery?: EventRecovery;
+}
+/**
+ * The client-specific half (#108 Claude Code, #109 Codex, #110 OpenCode). Nothing here can start a
+ * model turn on the controller's behalf: that is the adapter's decision, reported back through
+ * `EventController.recordReaction`.
+ */
+export interface ReactionAdapter {
+    /**
+     * Hand `dispatch` to the client application — NON-MODEL. Resolve once the client's transport
+     * accepted it; reject, or honour `signal`, when it did not. Resolving is delivery, not reaction.
+     * Resolve with a `DeliveryReceipt` when not every row was really handed over (the leader's own
+     * echoes are not); resolving with nothing means all of them were.
+     */
+    deliver(dispatch: EventDispatch, signal: AbortSignal): Promise<void | DeliveryReceipt>;
+    /** Optional non-model liveness probe (N-06). A rejection marks the transport disconnected. */
+    heartbeat?(signal: AbortSignal): Promise<void>;
+}
+/**
+ * What an adapter says about a dispatch it settled: the newest row it REALLY handed to the client,
+ * or `null` for none (every row was one the leader caused itself). `deliveredSeq` counts only
+ * these, so it never claims a row reached the leader when it did not (QA on #311).
+ */
+export interface DeliveryReceipt {
+    readonly handedThrough: number | null;
+}
+export type EventControllerState = 'inert' | 'idle' | 'dispatching' | 'recovering' | 'disconnected' | 'ended';
+export interface EventControllerStatus {
+    state: EventControllerState;
+    deliveredSeq: number;
+    ackedSeq: number;
+    reactedSeq: number;
+    latestSeq: number;
+}
+/** What `ack` and `recordReaction` answer. `ahead` changes nothing; neither ever rewinds. */
+export interface CursorAdvance {
+    status: 'advanced' | 'unchanged' | 'ahead' | 'inactive';
+    seq: number;
+}
+/** The leader's acknowledgement record as the controller reads it. `LeaderCursors` implements it. */
+export interface LeaderRecord {
+    /**
+     * Rows after `seq` are owed to the leader: its last acknowledgement, or — for a leader with no
+     * acknowledgement yet — where its record began (#251: the journal head the first time xezar kept
+     * one). `sameEpoch` false: the record counts in a journal that has since been recreated.
+     */
+    owedAfter(): {
+        seq: number;
+        sameEpoch: boolean;
+    };
+    /** The last row the leader acknowledged with an explicit tool call; 0 when it never has. */
+    acknowledged(): number;
+}
+export type EventControllerStart = {
+    outcome: 'started' | 'inert';
+    controller: EventController;
+} | {
+    outcome: 'refused';
+    error: McpProjectOccupiedError | McpSessionExpiredError;
+};
+export interface EventControllerOptions {
+    /** The bound project's journal — the one `EventJournal.open` returned for it. */
+    journal: Pick<EventJournal, 'projectId' | 'rowsPath' | 'epoch' | 'latestSeq' | 'oldestSeq' | 'headCursor' | 'read' | 'subscribe'>;
+    /** The bound project's owner slot. Read, never acquired or released, by this controller. */
+    ownership: Pick<ProjectOwnership, 'projectId' | 'sessionToken' | 'state'>;
+    /** The key the transport acquired the lease with — the logical session this controller serves. */
+    sessionKey: string;
+    /** The client's reaction adapter. Absent: no client is configured, and the controller is inert. */
+    adapter?: ReactionAdapter;
+    /**
+     * The leader's own record of what it has taken into account — in production the pull tool's
+     * `LeaderCursors` (#251), the ONE acknowledgement (#332). When given, the controller keeps no rival
+     * cursor: it pushes only rows after `owedAfter()`, read when a session starts AND before every
+     * dispatch, and reports `acknowledged()` as `ackedSeq`. Absent: the controller's own cursor file
+     * and `ack()` stand in (#107's standalone shape, and its tests).
+     */
+    leaderRecord?: LeaderRecord;
+    /** Test seams. Production uses the defaults. */
+    heartbeatMs?: number;
+    random?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    warn?: (message: string) => void;
+}
+export declare class EventController {
+    #private;
+    readonly projectId: string;
+    private constructor();
+    /**
+     * Start the controller for the session `sessionKey`, which must already own the project through
+     * the transport's own acquisition. Throws only on a caller bug (journal and owner slot of two
+     * different projects); every runtime condition is an answer.
+     */
+    static start(opts: EventControllerOptions): EventControllerStart;
+    get state(): EventControllerState;
+    status(): EventControllerStatus;
+    /**
+     * The leader's acknowledgement (D-05 § 6.6): monotonic and idempotent. At or below the current
+     * ack it is a successful no-op, never a rewind; past the journal head it changes nothing. It
+     * calls no adapter, so it can never cost a model turn.
+     */
+    ack(journalSeq: number): CursorAdvance;
+    /**
+     * The adapter's report that a model turn carrying rows up to `journalSeq` really started — the
+     * reaction half of F-20, recorded apart from delivery. Monotonic; never past a row the adapter was
+     * handed. A turn may start before `deliver` has resolved, so a row still in flight counts as handed.
+     */
+    recordReaction(journalSeq: number): CursorAdvance;
+    /** The adapter's transport came back: start a recovery round now instead of at the next tick. */
+    wake(): void;
+    /**
+     * Confirmed end of the session's connection — fired by the transport where it releases the lease.
+     * Ends this controller only: the lease, the journal and every run are untouched.
+     */
+    close(): void;
+}