@kya-os/cli 1.8.1 → 1.8.3

package/dist/orchestrator/db/tickets.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Ticket store (ORC-W1 PR-1).
+ *
+ * The two load-bearing operations live here, and both encode their invariant
+ * in SQL rather than in a caller's discipline.
+ *
+ * @module orchestrator/db/tickets
+ */
+import { z } from "zod";
+import { type Ledger } from "./index.js";
+export declare const TicketStatusSchema: z.ZodEnum<["open", "claimed", "in-progress", "in-review", "blocked", "ready", "closed"]>;
+export type TicketStatus = z.infer<typeof TicketStatusSchema>;
+/**
+ * The statuses `setTicketStatus` is allowed to write.
+ *
+ * `closed` and `claimed` each carry something a bare status write cannot -- a
+ * recorded reason, and a claimant set in the same statement -- so each has a
+ * dedicated function here and neither is reachable through the generic setter.
+ *
+ * Defined in the STORE and not at the MCP boundary, because the boundary is
+ * only one of the entrances. The daemon, the CLI and any consumer of the built
+ * package call these functions directly, and a rule that holds at one door is
+ * not an invariant, it is a convention with good manners.
+ */
+export declare const SettableTicketStatusSchema: z.ZodEnum<["open", "in-progress", "in-review", "blocked", "ready"]>;
+export type SettableTicketStatus = z.infer<typeof SettableTicketStatusSchema>;
+export declare const SETTABLE_TICKET_STATUSES: ["open", "in-progress", "in-review", "blocked", "ready"];
+export declare const TicketSeveritySchema: z.ZodEnum<["blocking", "major", "minor", "nit"]>;
+export type TicketSeverity = z.infer<typeof TicketSeveritySchema>;
+export declare const TicketSourceSchema: z.ZodEnum<["linear", "log_scan", "review_finding", "manual"]>;
+export type TicketSource = z.infer<typeof TicketSourceSchema>;
+/**
+ * Shape of a `tickets` row.
+ *
+ * Rows are parsed rather than cast. better-sqlite3's `.get()` is typed `any`,
+ * so `as Ticket` would not merely be an unchecked assumption, it would switch
+ * off checking for everything downstream of it — the repo bans exactly that.
+ * Parsing also means a schema drift (a migration that renames a column, a
+ * hand-edited ledger) fails loudly at the read instead of surfacing as
+ * `undefined` three layers away.
+ */
+export declare const TicketRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    linear_id: z.ZodNullable<z.ZodString>;
+    title: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<["open", "claimed", "in-progress", "in-review", "blocked", "ready", "closed"]>;
+    severity: z.ZodNullable<z.ZodEnum<["blocking", "major", "minor", "nit"]>>;
+    source: z.ZodEnum<["linear", "log_scan", "review_finding", "manual"]>;
+    claimed_by: z.ZodNullable<z.ZodString>;
+    claimed_at: z.ZodNullable<z.ZodString>;
+    closed_reason: z.ZodNullable<z.ZodString>;
+    superseded_by: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    status: "open" | "closed" | "ready" | "claimed" | "in-progress" | "in-review" | "blocked";
+    body: string | null;
+    source: "linear" | "log_scan" | "review_finding" | "manual";
+    linear_id: string | null;
+    title: string;
+    severity: "blocking" | "major" | "minor" | "nit" | null;
+    claimed_by: string | null;
+    claimed_at: string | null;
+    closed_reason: string | null;
+    superseded_by: string | null;
+    created_at: string;
+    updated_at: string;
+}, {
+    id: string;
+    status: "open" | "closed" | "ready" | "claimed" | "in-progress" | "in-review" | "blocked";
+    body: string | null;
+    source: "linear" | "log_scan" | "review_finding" | "manual";
+    linear_id: string | null;
+    title: string;
+    severity: "blocking" | "major" | "minor" | "nit" | null;
+    claimed_by: string | null;
+    claimed_at: string | null;
+    closed_reason: string | null;
+    superseded_by: string | null;
+    created_at: string;
+    updated_at: string;
+}>;
+export type Ticket = z.infer<typeof TicketRowSchema>;
+export interface CreateTicketInput {
+    title: string;
+    source: TicketSource;
+    body?: string;
+    severity?: TicketSeverity;
+    linearId?: string;
+    id?: string;
+}
+/** Insert a ticket in the `open` state. */
+export declare function createTicket(db: Ledger, input: CreateTicketInput): Ticket;
+export declare function getTicket(db: Ledger, id: string): Ticket | undefined;
+/**
+ * Claim the oldest open ticket, atomically.
+ *
+ * The claim and the mark are ONE statement. A read-then-write pair here is a
+ * review-blocking defect, not a style preference: two orchestrator ticks, or
+ * two orchestrators pointed at one ledger, would both read the same open
+ * ticket and both staff it, producing two workers on one ticket in two
+ * checkouts. With a single UPDATE the losing caller changes zero rows and
+ * moves on.
+ *
+ * Returns null when nothing was claimable, which is an ordinary outcome and
+ * never an error.
+ */
+export declare function claimNextTicket(db: Ledger, workerDid: string): Ticket | null;
+/**
+ * Close a ticket by marking it, never by deleting it.
+ *
+ * There is deliberately no delete path anywhere in this package. Once a row is
+ * gone, a bad autonomous close and a clean backlog look identical, and the
+ * evidence needed to tell them apart went with it.
+ */
+export declare function closeTicket(db: Ledger, id: string, reason: string, supersededBy?: string): Ticket;
+/**
+ * Move a ticket to one of the statuses a plain status write can express.
+ *
+ * `closed` and `claimed` are refused: see `SettableTicketStatusSchema`. The
+ * check is made at RUNTIME and not left to the parameter type, because the
+ * callers it guards are the ones TypeScript never sees -- JavaScript consumers
+ * of the built package, and anything arriving through an `unknown`. A type
+ * cannot stop a caller that was never type-checked.
+ */
+export declare function setTicketStatus(db: Ledger, id: string, status: SettableTicketStatus): Ticket;
+/**
+ * Read tickets, optionally filtered, optionally capped.
+ *
+ * The cap is applied HERE, to the newest rows, not by the caller slicing an
+ * oldest-first list. Tickets soft-close and are never deleted, so closed
+ * history accumulates at the front of `created_at` order: capping afterwards
+ * meant that once the ledger outgrew the cap, an unfiltered read could be
+ * entirely closed rows with every open ticket invisible behind them. The
+ * journal and dispatch readers already ordered newest-first; this one was the
+ * outlier.
+ *
+ * The window is taken newest-first and then handed back oldest-first, so the
+ * result reads in the natural direction while still being the recent end of the
+ * ledger. `id` breaks ties because `created_at` alone is not unique -- two
+ * tickets made in the same millisecond would otherwise order arbitrarily, and
+ * an arbitrary order at the cap boundary decides which row is visible at all.
+ */
+export declare function listTickets(db: Ledger, status?: TicketStatus, limit?: number): Ticket[];
+//# sourceMappingURL=tickets.d.ts.map

package/dist/orchestrator/db/tickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/db/tickets.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,kBAAkB,0FAQ7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,qEAAoD,CAAC;AAC5F,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,eAAO,MAAM,wBAAwB,0DAAqC,CAAC;AAgB3E,eAAO,MAAM,oBAAoB,kDAAgD,CAAC;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,kBAAkB,+DAA6D,CAAC;AAC7F,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAc1B,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAQrD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,2CAA2C;AAC3C,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAiBzE;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB5E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CA4CR;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAqC5F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBvF"}

package/dist/orchestrator/db/tickets.js

@@ -0,0 +1,238 @@
+/**
+ * Ticket store (ORC-W1 PR-1).
+ *
+ * The two load-bearing operations live here, and both encode their invariant
+ * in SQL rather than in a caller's discipline.
+ *
+ * @module orchestrator/db/tickets
+ */
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { rowCap } from "./index.js";
+export const TicketStatusSchema = z.enum([
+    "open",
+    "claimed",
+    "in-progress",
+    "in-review",
+    "blocked",
+    "ready",
+    "closed",
+]);
+/**
+ * The statuses `setTicketStatus` is allowed to write.
+ *
+ * `closed` and `claimed` each carry something a bare status write cannot -- a
+ * recorded reason, and a claimant set in the same statement -- so each has a
+ * dedicated function here and neither is reachable through the generic setter.
+ *
+ * Defined in the STORE and not at the MCP boundary, because the boundary is
+ * only one of the entrances. The daemon, the CLI and any consumer of the built
+ * package call these functions directly, and a rule that holds at one door is
+ * not an invariant, it is a convention with good manners.
+ */
+export const SettableTicketStatusSchema = TicketStatusSchema.exclude(["closed", "claimed"]);
+export const SETTABLE_TICKET_STATUSES = SettableTicketStatusSchema.options;
+/**
+ * Why each excluded status is excluded, so a refusal names its replacement
+ * rather than just saying no.
+ *
+ * Null-prototyped, so a lookup answers for its OWN keys only. As a plain object
+ * literal every inherited name resolved -- `toString`, `constructor`,
+ * `__proto__` -- and `?? fallback` never fired, so a caller could steer the
+ * refusal into printing a native function body instead of the settable list.
+ */
+const UNSETTABLE_STATUS_REASON = Object.assign(Object.create(null), {
+    closed: "closing must record a reason, use closeTicket",
+    claimed: "claiming must set a claimant in the same statement, use claimNextTicket",
+});
+export const TicketSeveritySchema = z.enum(["blocking", "major", "minor", "nit"]);
+export const TicketSourceSchema = z.enum(["linear", "log_scan", "review_finding", "manual"]);
+/**
+ * Shape of a `tickets` row.
+ *
+ * Rows are parsed rather than cast. better-sqlite3's `.get()` is typed `any`,
+ * so `as Ticket` would not merely be an unchecked assumption, it would switch
+ * off checking for everything downstream of it — the repo bans exactly that.
+ * Parsing also means a schema drift (a migration that renames a column, a
+ * hand-edited ledger) fails loudly at the read instead of surfacing as
+ * `undefined` three layers away.
+ */
+export const TicketRowSchema = z.object({
+    id: z.string(),
+    linear_id: z.string().nullable(),
+    title: z.string(),
+    body: z.string().nullable(),
+    status: TicketStatusSchema,
+    severity: TicketSeveritySchema.nullable(),
+    source: TicketSourceSchema,
+    claimed_by: z.string().nullable(),
+    claimed_at: z.string().nullable(),
+    closed_reason: z.string().nullable(),
+    superseded_by: z.string().nullable(),
+    created_at: z.string(),
+    updated_at: z.string(),
+});
+/** Parse one row, or undefined when the query matched nothing. */
+function parseRow(row) {
+    if (row === undefined || row === null)
+        return undefined;
+    return TicketRowSchema.parse(row);
+}
+/** Insert a ticket in the `open` state. */
+export function createTicket(db, input) {
+    const now = new Date().toISOString();
+    const id = input.id ?? randomUUID();
+    db.prepare(`INSERT INTO tickets (id, linear_id, title, body, status, severity, source, created_at, updated_at)
+     VALUES (?, ?, ?, ?, 'open', ?, ?, ?, ?)`).run(id, input.linearId ?? null, input.title, input.body ?? null, input.severity ?? null, input.source, now, now);
+    return getTicket(db, id);
+}
+export function getTicket(db, id) {
+    return parseRow(db.prepare(`SELECT * FROM tickets WHERE id = ?`).get(id));
+}
+/**
+ * Claim the oldest open ticket, atomically.
+ *
+ * The claim and the mark are ONE statement. A read-then-write pair here is a
+ * review-blocking defect, not a style preference: two orchestrator ticks, or
+ * two orchestrators pointed at one ledger, would both read the same open
+ * ticket and both staff it, producing two workers on one ticket in two
+ * checkouts. With a single UPDATE the losing caller changes zero rows and
+ * moves on.
+ *
+ * Returns null when nothing was claimable, which is an ordinary outcome and
+ * never an error.
+ */
+export function claimNextTicket(db, workerDid) {
+    const now = new Date().toISOString();
+    const row = db
+        .prepare(`UPDATE tickets
+          SET status = 'claimed', claimed_by = ?, claimed_at = ?, updated_at = ?
+        WHERE id = (
+                SELECT id FROM tickets
+                 WHERE status = 'open'
+                 ORDER BY created_at, id
+                 LIMIT 1
+              )
+    RETURNING *`)
+        .get(workerDid, now, now);
+    return parseRow(row) ?? null;
+}
+/**
+ * Close a ticket by marking it, never by deleting it.
+ *
+ * There is deliberately no delete path anywhere in this package. Once a row is
+ * gone, a bad autonomous close and a clean backlog look identical, and the
+ * evidence needed to tell them apart went with it.
+ */
+export function closeTicket(db, id, reason, supersededBy) {
+    // Enforced here and not only at the tool, for the reason the whole module
+    // exists: "nothing is ever deleted" buys an audit trail only if the surviving
+    // row says WHY it closed, and a blank reason produces the unexplained closed
+    // row permanently, since a second close is refused.
+    if (reason.trim() === "") {
+        throw new Error(`orchestrator: closing ticket ${id} needs a non-empty reason`);
+    }
+    const info = db
+        .prepare(`UPDATE tickets
+          SET status        = 'closed',
+              closed_reason = ?,
+              superseded_by = ?,
+              updated_at    = ?,
+              -- Closing LEAVES claimed, so it releases the claim too. The rule
+              -- lived only in setTicketStatus, so a closed row kept naming a
+              -- live worker and answered "who holds this" in flat contradiction
+              -- of its own status. In the same statement, so the release cannot
+              -- be separated from the close by a failure between them.
+              -- If a third writer ever leaves claimed, move this to a trigger
+              -- rather than writing the rule a third time.
+              claimed_by    = NULL,
+              claimed_at    = NULL
+        WHERE id = ?
+          AND status <> 'closed'`)
+        .run(reason, supersededBy ?? null, new Date().toISOString(), id);
+    if (info.changes === 0) {
+        const existing = getTicket(db, id);
+        if (existing === undefined) {
+            throw new Error(`orchestrator: cannot close unknown ticket ${id}`);
+        }
+        // Closing twice used to overwrite the original reason and NULL out
+        // superseded_by, which reduces "soft, auditable close" to one mutable
+        // column: the record of WHY something closed is the point of not deleting
+        // it, and a second close silently replaces that record.
+        throw new Error(`orchestrator: ticket ${id} is already closed (${existing.closed_reason ?? "no reason recorded"})`);
+    }
+    return getTicket(db, id);
+}
+/**
+ * Move a ticket to one of the statuses a plain status write can express.
+ *
+ * `closed` and `claimed` are refused: see `SettableTicketStatusSchema`. The
+ * check is made at RUNTIME and not left to the parameter type, because the
+ * callers it guards are the ones TypeScript never sees -- JavaScript consumers
+ * of the built package, and anything arriving through an `unknown`. A type
+ * cannot stop a caller that was never type-checked.
+ */
+export function setTicketStatus(db, id, status) {
+    if (!SettableTicketStatusSchema.safeParse(status).success) {
+        const because = UNSETTABLE_STATUS_REASON[status] ??
+            `settable statuses are ${SETTABLE_TICKET_STATUSES.join(", ")}`;
+        throw new Error(`orchestrator: setTicketStatus cannot set '${status}'; ${because}`);
+    }
+    const info = db
+        .prepare(`UPDATE tickets
+          SET status     = ?,
+              updated_at = ?,
+              -- Any transition AWAY from claimed releases the claim, in the same
+              -- statement so the release cannot be separated from the status
+              -- change by a failure between them. Unconditional because the
+              -- guard above makes 'claimed' unreachable here: every status this
+              -- statement can write is a status that leaves it.
+              claimed_by = NULL,
+              claimed_at = NULL
+        WHERE id = ?
+          AND status <> 'closed'`)
+        .run(status, new Date().toISOString(), id);
+    if (info.changes === 0) {
+        // Distinguish the two ways to change nothing, because they mean opposite
+        // things to a caller: one is a bad id, the other is a refused transition.
+        const existing = getTicket(db, id);
+        if (existing === undefined) {
+            throw new Error(`orchestrator: cannot update unknown ticket ${id}`);
+        }
+        throw new Error(`orchestrator: ticket ${id} is closed; reopening is a human decision, not a status write`);
+    }
+    return getTicket(db, id);
+}
+/**
+ * Read tickets, optionally filtered, optionally capped.
+ *
+ * The cap is applied HERE, to the newest rows, not by the caller slicing an
+ * oldest-first list. Tickets soft-close and are never deleted, so closed
+ * history accumulates at the front of `created_at` order: capping afterwards
+ * meant that once the ledger outgrew the cap, an unfiltered read could be
+ * entirely closed rows with every open ticket invisible behind them. The
+ * journal and dispatch readers already ordered newest-first; this one was the
+ * outlier.
+ *
+ * The window is taken newest-first and then handed back oldest-first, so the
+ * result reads in the natural direction while still being the recent end of the
+ * ledger. `id` breaks ties because `created_at` alone is not unique -- two
+ * tickets made in the same millisecond would otherwise order arbitrarily, and
+ * an arbitrary order at the cap boundary decides which row is visible at all.
+ */
+export function listTickets(db, status, limit) {
+    const cap = rowCap(limit);
+    const rows = status
+        ? db
+            .prepare(`SELECT * FROM (
+             SELECT * FROM tickets WHERE status = ? ORDER BY created_at DESC, id DESC LIMIT ?
+           ) ORDER BY created_at, id`)
+            .all(status, cap)
+        : db
+            .prepare(`SELECT * FROM (
+             SELECT * FROM tickets ORDER BY created_at DESC, id DESC LIMIT ?
+           ) ORDER BY created_at, id`)
+            .all(cap);
+    return z.array(TicketRowSchema).parse(rows);
+}
+//# sourceMappingURL=tickets.js.map

package/dist/orchestrator/db/tickets.js.map

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

package/dist/orchestrator/db/verdicts.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Verdict and quorum store.
+ *
+ * The point of this module is that both writes are idempotent by NATURAL key,
+ * not by a hash of the event that produced them:
+ *
+ *   - a verdict is unique per (repo, pr, head_sha, reviewer_did)
+ *   - quorum is unique per (repo, pr, head_sha)
+ *
+ * Those keys are what the review protocol already means, so "have we processed
+ * this?" is answered by asking whether the row exists. The previous approach
+ * derived a content hash of the hub event and stored a synthetic marker beside
+ * the ticket, which needed its own scoping, its own lookup path, and its own
+ * durability guarantees -- three review findings' worth of them. A UNIQUE
+ * constraint the schema already declared does the same job and cannot expire,
+ * collide across tickets, or be looked for in the wrong window.
+ *
+ * `verdicts` was in the schema from the start with exactly this shape and no
+ * reader; this is that reader.
+ *
+ * @module cli/orchestrator/db/verdicts
+ */
+import { z } from "zod";
+import type { Ledger } from "./index.js";
+export declare const VerdictKindSchema: z.ZodEnum<["approve", "request-changes", "comment"]>;
+export type VerdictKind = z.infer<typeof VerdictKindSchema>;
+export declare const VerdictRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    ticket_id: z.ZodNullable<z.ZodString>;
+    repo: z.ZodString;
+    pr_number: z.ZodNumber;
+    head_sha: z.ZodString;
+    reviewer_did: z.ZodString;
+    verdict: z.ZodEnum<["approve", "request-changes", "comment"]>;
+    findings: z.ZodNullable<z.ZodString>;
+    counted: z.ZodNumber;
+    received_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    repo: string;
+    ticket_id: string | null;
+    pr_number: number;
+    head_sha: string;
+    reviewer_did: string;
+    verdict: "comment" | "approve" | "request-changes";
+    findings: string | null;
+    counted: number;
+    received_at: string;
+}, {
+    id: string;
+    repo: string;
+    ticket_id: string | null;
+    pr_number: number;
+    head_sha: string;
+    reviewer_did: string;
+    verdict: "comment" | "approve" | "request-changes";
+    findings: string | null;
+    counted: number;
+    received_at: string;
+}>;
+export type VerdictRow = z.infer<typeof VerdictRowSchema>;
+export interface RecordVerdictInput {
+    ticketId: string | null;
+    repo: string;
+    prNumber: number;
+    headSha: string;
+    reviewerDid: string;
+    verdict: VerdictKind;
+    /** The hub's own validity flag; false means it failed verdict validation. */
+    counted: boolean;
+    findings?: unknown;
+    /**
+     * PROTOCOL time -- the hub event's own timestamp -- not the wall clock at
+     * insert. Head ranking is derived from these, and consecutive better-sqlite3
+     * inserts land in the same millisecond, so a wall-clock stamp made ties the
+     * normal case on a cold-start replay and handed the decision to a lexicographic
+     * SHA comparison. Protocol time is the order things actually happened in, which
+     * is the order the ranking is trying to recover.
+     */
+    observedAt: number;
+}
+/**
+ * Record one reviewer's verdict on one head SHA.
+ *
+ * Returns true when something CHANGED: the verdict is new, or the same reviewer
+ * revised it on the same head. False means this exact verdict was already
+ * recorded, which is a replay, a re-delivered event, or a boot reconcile of a
+ * window already processed.
+ *
+ * `received_at` is NEVER rewritten on conflict: it is the FIRST sighting of this
+ * head, which head ranking depends on, and letting a late revision move it
+ * contradicted the very function that reads it. A revision updates the verdict,
+ * not when the head was first seen.
+ *
+ * The mind-change case is why this is an upsert rather than INSERT OR IGNORE.
+ * The hub explicitly permits a reviewer to follow an approval with
+ * request-changes on the SAME head and emits a second review_verdict for it. On
+ * a plain OR IGNORE that second verdict is dropped as "already handled" and the
+ * ticket never goes back to in-progress -- a reviewer withdrawing approval would
+ * be silently overruled by a uniqueness constraint.
+ *
+ * The guarded UPDATE is what keeps false meaning "nothing to do": re-delivering
+ * an identical verdict fails the WHERE, changes no rows, and reports false.
+ * `findings` is part of that comparison so a revision that only changes its
+ * reasons is still stored -- otherwise the recorded findings silently went stale
+ * while the verdict itself looked current.
+ *
+ * The id is a readable composite of the natural key rather than a hash, so a row
+ * can be found by hand in a debugging session.
+ */
+export declare function recordVerdict(db: Ledger, input: RecordVerdictInput): boolean;
+export interface RecordQuorumInput {
+    ticketId: string | null;
+    repo: string;
+    prNumber: number;
+    headSha: string;
+    quorumN?: number;
+    /** Protocol time, for the same reason as {@link RecordVerdictInput.observedAt}. */
+    observedAt: number;
+}
+/**
+ * Record that the hub declared quorum on one head SHA.
+ *
+ * Returns true when it was new. Quorum is stored rather than recomputed because
+ * the hub owns verdict validation, and a second implementation of the threshold
+ * here could disagree with the one that actually gated the decision.
+ */
+export declare function recordQuorum(db: Ledger, input: RecordQuorumInput): boolean;
+/** Every verdict on one PR head, newest first. */
+export declare function listVerdictsForPr(db: Ledger, repo: string, prNumber: number, headSha?: string): VerdictRow[];
+/** Has the hub already declared quorum on this head? */
+export declare function quorumReached(db: Ledger, repo: string, prNumber: number, headSha: string): boolean;
+/**
+ * The most recently seen head SHA for a pull request.
+ *
+ * Which revision the ledger currently believes is live. A push invalidates every
+ * prior verdict (the review protocol's settled rule), so status has to be derived
+ * from the newest head rather than from whichever head the event in hand names --
+ * otherwise a late or replayed quorum for superseded code moves current work.
+ * `counted: false` marks a stale VERDICT; quorum has no such flag.
+ *
+ * Ranked by when each head was FIRST seen, not when it was last touched. This is
+ * the whole correctness of the function. Ranking by last-touched let any newly
+ * recorded row for an older SHA promote it to "latest" -- including an uncounted
+ * stale verdict kept purely as evidence. Historical quorum on that superseded
+ * head would then clear a live objection on the real one, defeating the
+ * uncounted guard this derivation depends on. A head's first sighting cannot be
+ * moved by a late arrival, because the upsert never rewrites `received_at`.
+ *
+ * "When" is PROTOCOL time -- the hub event's own timestamp, carried in on
+ * `observedAt` -- not the wall clock at insert. Insert time made this a coin
+ * flip in the one case that matters most: on a cold start, `reconcileReviewState`
+ * replays the window fast enough that consecutive better-sqlite3 inserts land in
+ * the same millisecond, so every head tied and the winner fell to the SHA
+ * tiebreak. Half the time that elected the OLD head, derived a historical quorum
+ * against it, and moved a ticket to `ready` straight past a live counted
+ * request-changes on the new one.
+ *
+ * Ties still break on head_sha, for genuinely simultaneous protocol timestamps:
+ * an arbitrary-but-stable answer beats a fresh coin flip per query, and truly
+ * simultaneous revisions are ambiguous under any rule.
+ */
+export declare function latestHeadForPr(db: Ledger, repo: string, prNumber: number): string | undefined;
+/**
+ * The same ranking as {@link latestHeadForPr}, blind to uncounted verdicts.
+ *
+ * `latestHeadForPr` deliberately ranks EVERY verdict, counted or not -- a
+ * verdict naming a stale or malformed SHA still proves the hub saw that SHA,
+ * which is what that function's contract promises. But "a SHA was mentioned"
+ * and "a SHA was genuinely reviewed" are different questions, and DERIVING
+ * status needs the second one: a verdict the hub itself flagged invalid must
+ * not be able to outrank a real counted verdict or quorum recorded on a
+ * different head just because it happened to arrive with a later protocol
+ * timestamp. Left unfiltered, that lets review noise on a throwaway SHA
+ * occlude a real objection sitting under the head that actually matters --
+ * the ticket keeps whatever status the occluded head implied, forever,
+ * because nothing ever asks about that head again.
+ *
+ * Quorum rows carry no `counted` column and are never filtered here, the same
+ * way {@link latestHeadForPr} treats them: the hub is the sole authority for
+ * quorum, so a recorded quorum is trusted unconditionally.
+ *
+ * Returns undefined when no head has ANY trusted evidence yet -- distinct
+ * from "no evidence at all," which only {@link latestHeadForPr} can answer.
+ */
+export declare function latestTrustedHeadForPr(db: Ledger, repo: string, prNumber: number): string | undefined;
+//# sourceMappingURL=verdicts.d.ts.map

package/dist/orchestrator/db/verdicts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdicts.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/db/verdicts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,eAAO,MAAM,iBAAiB,sDAAoD,CAAC;AACnF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAW3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CA6B5E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAe1E;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,UAAU,EAAE,CAcd;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAMT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAe9F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAerG"}