@qodeca/xezar 0.13.0 → 0.14.0

package/dist/contract/mcp-idempotency.d.ts

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+/**
+ * Durable operation identity for MCP mutations (issue #101, decision D-06 —
+ * `docs/features/mcp-server/mcp-d06-versioning-idempotency-audit-decision.md`).
+ *
+ * Every mutating MCP tool takes a client-generated `operationId`. The server keys a receipt on
+ * `<projectId>/<operationId>` — the project half comes from the trusted connection binding, never
+ * from a tool argument — and verifies the stored `action` and payload digest on every retry. The
+ * JSON-RPC request id is deliberately NOT this identity: it correlates one request with one
+ * response and does not survive a reconnect (D-06 § 5.1).
+ *
+ * These are wire shapes only. How a receipt is stored lives in the service
+ * (`packages/xezar/src/mcp/operation-receipts.ts`); nothing here is persisted as-is.
+ */
+/**
+ * The operation id a client supplies (D-06 § 5.2). Opaque: a UUIDv4 is the expected shape, but the
+ * server neither requires nor parses one. 8–128 characters from a closed alphabet — the bounds are
+ * shape bounds only (a technical proposal in D-06 § 1.1), and the alphabet keeps `/` out so the
+ * stored `<projectId>/<operationId>` key splits unambiguously.
+ */
+export declare const operationIdSchema: z.ZodString;
+export type OperationId = z.infer<typeof operationIdSchema>;
+/**
+ * A stored, settled outcome (D-06 § 9.2). `in-progress` is deliberately absent: it is derived from
+ * liveness at lookup time and is never written down.
+ *
+ * - `ok` — the effect happened and the result is recorded.
+ * - `rejected` — refused before any effect (validation, `stale_version`, permission).
+ * - `not-applied` — reconciliation ESTABLISHED that the effect did not happen.
+ * - `unverified` — the effect may have happened; nothing has established which. Never retried.
+ */
+export declare const operationOutcomeSchema: z.ZodEnum<{
+    "not-applied": "not-applied";
+    ok: "ok";
+    rejected: "rejected";
+    unverified: "unverified";
+}>;
+export type OperationOutcome = z.infer<typeof operationOutcomeSchema>;
+/** What a settled `ok` operation produced — a reference, never content (D-06 § 7.1, § 10.3). */
+export declare const operationResultRefSchema: z.ZodObject<{
+    kind: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type OperationResultRef = z.infer<typeof operationResultRefSchema>;
+/**
+ * A short machine-readable reason or error code. Never a raw error body: output from `gh` or `git`
+ * can carry a token or a path (D-06 § 9.3, § 10.3), so the alphabet admits no `/`, `=` or quote
+ * and the length is capped.
+ */
+export declare const operationReasonSchema: z.ZodString;
+export type OperationReason = z.infer<typeof operationReasonSchema>;
+/**
+ * The read a reconciler performs to answer "did this effect happen?" (D-06 § 9.3). Recorded in the
+ * `intent` line BEFORE the effect, because after a crash nothing else can rebuild it.
+ */
+export declare const reconcilePredicateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"run-by-key">;
+    predictedRunId: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"forge-search">;
+    repository: z.ZodString;
+    headBranch: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"git-state">;
+    ref: z.ZodString;
+    sha: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+}, z.core.$strip>], "kind">;
+export type ReconcilePredicate = z.infer<typeof reconcilePredicateSchema>;
+export type ReconcileKind = ReconcilePredicate['kind'];
+/** Guidance a client gets with every `unverified` answer (D-06 § 9.3 rule 5). */
+export declare const UNVERIFIED_GUIDANCE: 'read current state; a new operationId is a new action';
+/** A settled operation — a first attempt that finished, or a retry replaying the stored outcome. */
+export declare const operationSettledResultSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        "not-applied": "not-applied";
+        ok: "ok";
+        rejected: "rejected";
+    }>;
+    operationId: z.ZodString;
+    action: z.ZodString;
+    replayed: z.ZodBoolean;
+    resultRef: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    errorCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type OperationSettledResult = z.infer<typeof operationSettledResultSchema>;
+/**
+ * A duplicate that arrived while the first attempt is still live in this process (D-06 § 6). Not
+ * uncertain: the server knows the operation is running and will settle it.
+ */
+export declare const operationInProgressResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"in-progress">;
+    operationId: z.ZodString;
+    action: z.ZodString;
+    startedAt: z.ZodString;
+}, z.core.$strip>;
+export type OperationInProgressResult = z.infer<typeof operationInProgressResultSchema>;
+/**
+ * The effect may have happened and nothing has established which (D-06 § 9.3). No effect ran for
+ * this call, and none will run for any retry of the same `operationId`.
+ */
+export declare const operationUnverifiedResultSchema: z.ZodObject<{
+    status: z.ZodLiteral<"unverified">;
+    operationId: z.ZodString;
+    action: z.ZodString;
+    startedAt: z.ZodString;
+    reconcile: z.ZodObject<{
+        kind: z.ZodEnum<{
+            "forge-search": "forge-search";
+            "git-state": "git-state";
+            none: "none";
+            "run-by-key": "run-by-key";
+        }>;
+        attemptedAt: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    guidance: z.ZodLiteral<"read current state; a new operationId is a new action">;
+}, z.core.$strip>;
+export type OperationUnverifiedResult = z.infer<typeof operationUnverifiedResultSchema>;
+/**
+ * The same `operationId` arrived with a different action or payload (D-06 § 6). No effect ran, and
+ * the stored operation's result is deliberately NOT returned — handing back another intention's
+ * result would be wrong and a small information leak. `mismatch` says which half disagreed.
+ */
+export declare const operationKeyConflictSchema: z.ZodObject<{
+    error: z.ZodLiteral<"operation_key_conflict">;
+    operationId: z.ZodString;
+    storedAction: z.ZodString;
+    storedAt: z.ZodString;
+    mismatch: z.ZodEnum<{
+        action: "action";
+        payload: "payload";
+    }>;
+}, z.core.$strip>;
+export type OperationKeyConflict = z.infer<typeof operationKeyConflictSchema>;
+/**
+ * The receipt journal cannot be written (read-only repository, full disk), so the operation cannot
+ * be made idempotent and is refused BEFORE its effect (D-06 § 7.5).
+ */
+export declare const operationReceiptUnavailableSchema: z.ZodObject<{
+    error: z.ZodLiteral<"operation_receipt_unavailable">;
+    operationId: z.ZodString;
+    reason: z.ZodLiteral<"journal_unwritable">;
+}, z.core.$strip>;
+export type OperationReceiptUnavailable = z.infer<typeof operationReceiptUnavailableSchema>;
+/** Every answer the operation-receipt layer gives a mutating MCP tool. */
+export declare const operationAnswerSchema: z.ZodUnion<readonly [z.ZodObject<{
+    status: z.ZodEnum<{
+        "not-applied": "not-applied";
+        ok: "ok";
+        rejected: "rejected";
+    }>;
+    operationId: z.ZodString;
+    action: z.ZodString;
+    replayed: z.ZodBoolean;
+    resultRef: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    errorCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"in-progress">;
+    operationId: z.ZodString;
+    action: z.ZodString;
+    startedAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"unverified">;
+    operationId: z.ZodString;
+    action: z.ZodString;
+    startedAt: z.ZodString;
+    reconcile: z.ZodObject<{
+        kind: z.ZodEnum<{
+            "forge-search": "forge-search";
+            "git-state": "git-state";
+            none: "none";
+            "run-by-key": "run-by-key";
+        }>;
+        attemptedAt: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    guidance: z.ZodLiteral<"read current state; a new operationId is a new action">;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodLiteral<"operation_key_conflict">;
+    operationId: z.ZodString;
+    storedAction: z.ZodString;
+    storedAt: z.ZodString;
+    mismatch: z.ZodEnum<{
+        action: "action";
+        payload: "payload";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodLiteral<"operation_receipt_unavailable">;
+    operationId: z.ZodString;
+    reason: z.ZodLiteral<"journal_unwritable">;
+}, z.core.$strip>]>;
+export type OperationAnswer = z.infer<typeof operationAnswerSchema>;

package/dist/contract/mcp-journal.d.ts

@@ -0,0 +1,268 @@
+import { z } from 'zod';
+/**
+ * The per-project MCP event journal (#103) — the wire half. The writer, the retention and the
+ * cursor arithmetic live in `packages/xezar/src/mcp/event-journal.ts`.
+ *
+ * Every shape here was decided elsewhere, and each comment names where:
+ *  - D-05 (`docs/features/mcp-server/mcp-d05-async-event-contract-decision.md`) § 6.1–6.3 fixes
+ *    the row envelope, the per-project gapless `journalSeq`, and `eventId = "<projectId>:<seq>"`;
+ *    § 6.5 fixes the opaque cursor, replay strictly after it, the rejected malformed cursor and the
+ *    explicit `cursor_too_old` answer.
+ *  - D-09 (`mcp-d09-limits-retention-packaging-decision.md`) § 3 fixes every number: B-01 (page
+ *    bytes), B-02/B-20 (page rows), B-04 (cursor bytes), B-19 (retention).
+ *
+ * This is NOT the per-run transcript: `runEventSchema` (`events.ts`) is one run's NDJSON, ordered by
+ * a per-run `seq` that is allowed gaps. A journal row is ordered by the PROJECT's `journalSeq`,
+ * which never has one, and it carries a summary — never a payload (D-05 § 6.3).
+ */
+/** B-19: the newest rows a project keeps, whatever their age. */
+export declare const MCP_JOURNAL_RETAINED_ROWS = 10000;
+/** B-19: a row younger than this is never evicted, however many rows there are. */
+export declare const MCP_JOURNAL_MIN_RETENTION_DAYS = 14;
+/** B-02 / B-20: rows per replay page — the transcript page size, reused, not a second one. */
+export declare const MCP_JOURNAL_PAGE_ROWS = 100;
+/** B-01: serialized UTF-8 bytes of the rows on one page. Whichever of this and the row count is
+ *  reached first ends the page; a page always carries at least one row when one is outstanding. */
+export declare const MCP_JOURNAL_PAGE_BYTES = 40000;
+/** B-04: the size ceiling of every MCP cursor, the same as the transcript history cursor. */
+export declare const MCP_JOURNAL_CURSOR_MAX_BYTES = 2048;
+/**
+ * Shape bound on `summary`, not a behavioural limit: it keeps the largest possible row far inside
+ * one B-01 page, so a single row can never need B-03's chunking. D-05 measured the whole envelope
+ * at 399 bytes; a summary is one line of prose, never a transcript, diff or file content.
+ */
+export declare const MCP_JOURNAL_SUMMARY_MAX_CHARS = 500;
+/** The agreed significant-event catalog (requirements § 6). Closed: D-05 § 6.3. */
+export declare const mcpJournalCategorySchema: z.ZodEnum<{
+    "E-01": "E-01";
+    "E-02": "E-02";
+    "E-03": "E-03";
+    "E-04": "E-04";
+    "E-05": "E-05";
+    "E-06": "E-06";
+}>;
+export type McpJournalCategory = z.infer<typeof mcpJournalCategorySchema>;
+/**
+ * Who caused the row (D-05 § 6.3). Server-derived, never taken from a tool argument. Together with
+ * `causedBy` this is the F-13 echo-loop guard: an adapter drops a row whose `origin` is `leader` AND
+ * whose `causedBy` is its own outstanding operation — never merely because it recognises the run.
+ */
+export declare const mcpJournalOriginSchema: z.ZodEnum<{
+    human: "human";
+    leader: "leader";
+    system: "system";
+}>;
+export type McpJournalOrigin = z.infer<typeof mcpJournalOriginSchema>;
+/** A leader operation id, as D-06 § 5.2 shapes every `operationId`. Opaque; never parsed. */
+export declare const mcpJournalOperationIdSchema: z.ZodString;
+/** The registry slug (`PROJECT_ID_RE` in `packages/xezar/src/workspace/config.ts`). */
+export declare const mcpJournalProjectIdSchema: z.ZodString;
+/**
+ * The affected resource. `version` is the D-06 token of the resource as it was when the row was
+ * written, carried through replay unchanged (D-05 § 6.3). It is always PRESENT: `null` is the
+ * explicit "this subject has no version" (an executor, say), never a missing key.
+ */
+export declare const mcpJournalSubjectSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type McpJournalSubject = z.infer<typeof mcpJournalSubjectSchema>;
+/** Provenance back to one run transcript line. Never identity, never order (D-05 § 6.1). */
+export declare const mcpJournalSourceSchema: z.ZodObject<{
+    runId: z.ZodString;
+    runSeq: z.ZodNumber;
+}, z.core.$strip>;
+/** `kind` is the finer machine label under a category; open for additive growth (D-05 § 6.3). */
+export declare const mcpJournalKindSchema: z.ZodString;
+/**
+ * What an emitter hands the journal. The journal assigns `journalSeq`, `ts`, `projectId` and
+ * `eventId` itself — a caller cannot choose its own position or its own project.
+ */
+export declare const mcpJournalAppendInputSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        "E-01": "E-01";
+        "E-02": "E-02";
+        "E-03": "E-03";
+        "E-04": "E-04";
+        "E-05": "E-05";
+        "E-06": "E-06";
+    }>;
+    kind: z.ZodString;
+    subject: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    origin: z.ZodEnum<{
+        human: "human";
+        leader: "leader";
+        system: "system";
+    }>;
+    causedBy: z.ZodNullable<z.ZodString>;
+    summary: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodString;
+        runSeq: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type McpJournalAppendInput = z.input<typeof mcpJournalAppendInputSchema>;
+/** One journal row, exactly as it is stored and exactly as it is replayed (D-05 § 6.3). */
+export declare const mcpJournalRowSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        "E-01": "E-01";
+        "E-02": "E-02";
+        "E-03": "E-03";
+        "E-04": "E-04";
+        "E-05": "E-05";
+        "E-06": "E-06";
+    }>;
+    kind: z.ZodString;
+    subject: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    origin: z.ZodEnum<{
+        human: "human";
+        leader: "leader";
+        system: "system";
+    }>;
+    causedBy: z.ZodNullable<z.ZodString>;
+    summary: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodString;
+        runSeq: z.ZodNumber;
+    }, z.core.$strip>>;
+    eventId: z.ZodString;
+    journalSeq: z.ZodNumber;
+    ts: z.ZodString;
+    projectId: z.ZodString;
+}, z.core.$strip>;
+export type McpJournalRow = z.infer<typeof mcpJournalRowSchema>;
+/** Opaque to the client. It encodes project, epoch and position; a client never builds one. */
+export declare const mcpJournalCursorSchema: z.ZodString;
+export type McpJournalCursor = z.infer<typeof mcpJournalCursorSchema>;
+/** A replay read: everything strictly after `cursor`, or from the oldest retained row without one. */
+export declare const mcpJournalReadInputSchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type McpJournalReadInput = z.infer<typeof mcpJournalReadInputSchema>;
+export declare const mcpJournalPageSchema: z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    events: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            "E-01": "E-01";
+            "E-02": "E-02";
+            "E-03": "E-03";
+            "E-04": "E-04";
+            "E-05": "E-05";
+            "E-06": "E-06";
+        }>;
+        kind: z.ZodString;
+        subject: z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+            version: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        origin: z.ZodEnum<{
+            human: "human";
+            leader: "leader";
+            system: "system";
+        }>;
+        causedBy: z.ZodNullable<z.ZodString>;
+        summary: z.ZodString;
+        source: z.ZodOptional<z.ZodObject<{
+            runId: z.ZodString;
+            runSeq: z.ZodNumber;
+        }, z.core.$strip>>;
+        eventId: z.ZodString;
+        journalSeq: z.ZodNumber;
+        ts: z.ZodString;
+        projectId: z.ZodString;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodString;
+    hasMore: z.ZodBoolean;
+    oldestSeq: z.ZodNullable<z.ZodNumber>;
+    latestSeq: z.ZodNumber;
+}, z.core.$strip>;
+export type McpJournalPage = z.infer<typeof mcpJournalPageSchema>;
+/**
+ * The explicit gap (D-05 § 6.5, adopted by D-09 B-19). Rows the cursor still needed are gone —
+ * evicted by retention, or the journal was recreated — so NOTHING is replayed: a partial replay
+ * would read as "nothing happened" in between. The caller reads current state first, then continues
+ * from `resumeCursor`, which sits just before the oldest row still retained.
+ */
+export declare const mcpJournalCursorTooOldSchema: z.ZodObject<{
+    status: z.ZodLiteral<"cursor_too_old">;
+    oldestSeq: z.ZodNullable<z.ZodNumber>;
+    latestSeq: z.ZodNumber;
+    resumeCursor: z.ZodString;
+    recovery: z.ZodObject<{
+        required: z.ZodLiteral<"current-state">;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type McpJournalCursorTooOld = z.infer<typeof mcpJournalCursorTooOldSchema>;
+export declare const mcpJournalReadResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    events: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            "E-01": "E-01";
+            "E-02": "E-02";
+            "E-03": "E-03";
+            "E-04": "E-04";
+            "E-05": "E-05";
+            "E-06": "E-06";
+        }>;
+        kind: z.ZodString;
+        subject: z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+            version: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        origin: z.ZodEnum<{
+            human: "human";
+            leader: "leader";
+            system: "system";
+        }>;
+        causedBy: z.ZodNullable<z.ZodString>;
+        summary: z.ZodString;
+        source: z.ZodOptional<z.ZodObject<{
+            runId: z.ZodString;
+            runSeq: z.ZodNumber;
+        }, z.core.$strip>>;
+        eventId: z.ZodString;
+        journalSeq: z.ZodNumber;
+        ts: z.ZodString;
+        projectId: z.ZodString;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodString;
+    hasMore: z.ZodBoolean;
+    oldestSeq: z.ZodNullable<z.ZodNumber>;
+    latestSeq: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"cursor_too_old">;
+    oldestSeq: z.ZodNullable<z.ZodNumber>;
+    latestSeq: z.ZodNumber;
+    resumeCursor: z.ZodString;
+    recovery: z.ZodObject<{
+        required: z.ZodLiteral<"current-state">;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "status">;
+export type McpJournalReadResult = z.infer<typeof mcpJournalReadResultSchema>;
+/**
+ * A cursor the journal refuses outright. Never "start from zero" — that would replay the whole
+ * retention window into a model turn (D-05 § 6.5). `cursor_project_mismatch` names neither project:
+ * the bound session already knows its own, and the other one is not its business (N-01).
+ */
+export declare const mcpJournalCursorRejectionSchema: z.ZodObject<{
+    error: z.ZodEnum<{
+        cursor_project_mismatch: "cursor_project_mismatch";
+        invalid_cursor: "invalid_cursor";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type McpJournalCursorRejection = z.infer<typeof mcpJournalCursorRejectionSchema>;

package/dist/contract/mcp-leader.d.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+export declare const mcpLeaderActionInputSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"attach">;
+    client: z.ZodLiteral<"opencode">;
+    baseUrl: z.ZodURL;
+    sessionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"attach">;
+    client: z.ZodLiteral<"pi">;
+}, z.core.$strict>], "client">, z.ZodObject<{
+    action: z.ZodLiteral<"stop">;
+}, z.core.$strict>]>;
+export type McpLeaderActionInput = z.infer<typeof mcpLeaderActionInputSchema>;
+/** The leader session attached to the project, if any. */
+export declare const mcpLeaderSessionSchema: z.ZodObject<{
+    client: z.ZodEnum<{
+        opencode: "opencode";
+        pi: "pi";
+    }>;
+    state: z.ZodLiteral<"attached">;
+}, z.core.$strip>;
+export type McpLeaderSession = z.infer<typeof mcpLeaderSessionSchema>;
+/**
+ * The event controller of the MCP session that owns the project, when one is open. The three
+ * cursors are D-05 § 6.6's, stay apart, and each reports only what HAPPENED — never where pushing
+ * happened to start (QA on #311):
+ * - `deliveredSeq`: the newest row really handed to the attached leader, in this journal. A row
+ *   the leader caused itself (its own echo) is never handed to it and never counted, so this can stay
+ *   below `latestSeq` with nothing wrong — and it says nothing about those rows;
+ * - `ackedSeq`: the newest row the leader acknowledged with an explicit tool call — the same record
+ *   `leader_events` keeps, so the two never disagree; 0 until it acknowledges;
+ * - `reactedSeq`: the newest row a model turn was really seen to carry; 0 until one is.
+ */
+export declare const mcpLeaderDeliverySchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        disconnected: "disconnected";
+        dispatching: "dispatching";
+        ended: "ended";
+        idle: "idle";
+        inert: "inert";
+        recovering: "recovering";
+    }>;
+    deliveredSeq: z.ZodNumber;
+    ackedSeq: z.ZodNumber;
+    reactedSeq: z.ZodNumber;
+    latestSeq: z.ZodNumber;
+}, z.core.$strip>;
+export type McpLeaderDelivery = z.infer<typeof mcpLeaderDeliverySchema>;
+/** Why events are kept rather than delivered right now. Always recoverable: nothing is lost. */
+export declare const mcpLeaderBlockerSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    fix: z.ZodString;
+}, z.core.$strip>;
+export type McpLeaderBlocker = z.infer<typeof mcpLeaderBlockerSchema>;
+export declare const mcpLeaderStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    available: z.ZodLiteral<true>;
+    leader: z.ZodNullable<z.ZodObject<{
+        client: z.ZodEnum<{
+            opencode: "opencode";
+            pi: "pi";
+        }>;
+        state: z.ZodLiteral<"attached">;
+    }, z.core.$strip>>;
+    delivery: z.ZodNullable<z.ZodObject<{
+        state: z.ZodEnum<{
+            disconnected: "disconnected";
+            dispatching: "dispatching";
+            ended: "ended";
+            idle: "idle";
+            inert: "inert";
+            recovering: "recovering";
+        }>;
+        deliveredSeq: z.ZodNumber;
+        ackedSeq: z.ZodNumber;
+        reactedSeq: z.ZodNumber;
+        latestSeq: z.ZodNumber;
+    }, z.core.$strip>>;
+    blocker: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        fix: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "available">;
+export type McpLeaderStatus = z.infer<typeof mcpLeaderStatusSchema>;

package/dist/contract/mcp-ownership.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+/**
+ * Per-project MCP ownership (#99, decision D-02 in
+ * `docs/features/mcp-server/mcp-d02-session-binding-decision.md` § 4).
+ *
+ * Exactly one logical MCP session owns a project. A second one is refused with the
+ * *project-occupied* error, and an owner whose lease was lost or fenced is refused with the
+ * *session-expired* error on every later call.
+ *
+ * Neither error is standard MCP. The MCP specification publishes no error registry and no
+ * "project busy" code in the pages D-02 examined; both numbers are xezar's own, chosen inside the
+ * JSON-RPC 2.0 range reserved for implementation-defined server errors (`-32000` to `-32099`) and
+ * clear of every code the TypeScript SDK already claims. A future SDK release could still claim
+ * them, which is why **`data.reason` is the authoritative discriminator, not `code`**.
+ */
+/** JSON-RPC `code` of the project-occupied error. Implementation-defined, not standard. */
+export declare const MCP_PROJECT_OCCUPIED_CODE = -32080;
+/** JSON-RPC `code` of the session-expired error. Implementation-defined, not standard. */
+export declare const MCP_SESSION_EXPIRED_CODE = -32081;
+/** The namespaced discriminators. A consumer branches on these, never on the number. */
+export declare const MCP_PROJECT_OCCUPIED_REASON = "com.qodeca.xezar/project-occupied";
+export declare const MCP_SESSION_EXPIRED_REASON = "com.qodeca.xezar/session-expired";
+/**
+ * The JSON-RPC `error` object a second logical client receives from `initialize` while the
+ * project has a live owner. On Streamable HTTP it travels in a 200 response; on stdio it is the
+ * ordinary JSON-RPC error response.
+ *
+ * `.strict()` at both levels is the N-01 guarantee made structural: the refusal carries the
+ * project's own id, a human sentence and `retryable`, and NOTHING about the competing owner — no
+ * session id, fencing token, pid, client name or version, and no "occupied since" timestamp. A
+ * field added here is a field that can fingerprint another client, so adding one is a review
+ * question, not a convenience.
+ */
+export declare const mcpProjectOccupiedErrorSchema: z.ZodObject<{
+    code: z.ZodLiteral<-32080>;
+    message: z.ZodString;
+    data: z.ZodObject<{
+        reason: z.ZodLiteral<"com.qodeca.xezar/project-occupied">;
+        projectId: z.ZodString;
+        retryable: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type McpProjectOccupiedError = z.infer<typeof mcpProjectOccupiedErrorSchema>;
+/**
+ * The JSON-RPC `error` object a fenced or expired owner receives on any later call. On Streamable
+ * HTTP the transport answers 404 for that `MCP-Session-Id` instead, which every conforming client
+ * already treats as "start a new session"; on stdio this error is sent and the server then closes
+ * its output stream. Either way the exit is an automatic reconnect by the bridge — never the model
+ * and never a person.
+ */
+export declare const mcpSessionExpiredErrorSchema: z.ZodObject<{
+    code: z.ZodLiteral<-32081>;
+    message: z.ZodString;
+    data: z.ZodObject<{
+        reason: z.ZodLiteral<"com.qodeca.xezar/session-expired">;
+        projectId: z.ZodString;
+        retryable: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type McpSessionExpiredError = z.infer<typeof mcpSessionExpiredErrorSchema>;
+/**
+ * A project's occupancy as the cockpit renders it. Derived at READ time by the same classifier
+ * acquisition runs — never a stored flag, because a dead owner's claim can sit on disk until the
+ * next acquirer reaps it, and a stored flag would render "occupied" for a project nobody owns.
+ *
+ * - `unowned` — no claim, or none that is live. The resting state; nothing is blocked.
+ * - `owned` — one live owner. A second client would be refused.
+ * - `expired` — an owner's claim outlived its lease or its process. The next acquirer reclaims it.
+ *
+ * Deliberately no owner detail: the cockpit offers no control that changes this state (F-18 — no
+ * manual disconnect, no forced takeover), so it needs nothing to act on.
+ */
+export declare const projectOwnerStateSchema: z.ZodEnum<{
+    expired: "expired";
+    owned: "owned";
+    unowned: "unowned";
+}>;
+export type ProjectOwnerState = z.infer<typeof projectOwnerStateSchema>;