@kya-os/cli 1.8.1 → 1.8.3

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

@@ -0,0 +1,108 @@
+/**
+ * Dispatch store (ORC-W1 PR-2).
+ *
+ * One row per task handed to a worker. Its job in PR-2 is correlation: it is
+ * how an incoming hub event, which knows a taskId, becomes a journal entry
+ * attached to the right ticket.
+ *
+ * @module orchestrator/db/dispatches
+ */
+import { z } from "zod";
+import { type Ledger } from "./index.js";
+export declare const DispatchStatusSchema: z.ZodEnum<["dispatched", "in-progress", "completed", "failed"]>;
+export type DispatchStatus = z.infer<typeof DispatchStatusSchema>;
+export declare const DispatchRowSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    ticket_id: z.ZodString;
+    worker_did: z.ZodString;
+    repo: z.ZodNullable<z.ZodString>;
+    branch: z.ZodNullable<z.ZodString>;
+    pr_number: z.ZodNullable<z.ZodNumber>;
+    status: z.ZodEnum<["dispatched", "in-progress", "completed", "failed"]>;
+    dispatched_at: z.ZodString;
+    completed_at: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "failed" | "completed" | "in-progress" | "dispatched";
+    repo: string | null;
+    ticket_id: string;
+    task_id: string;
+    worker_did: string;
+    branch: string | null;
+    pr_number: number | null;
+    dispatched_at: string;
+    completed_at: string | null;
+}, {
+    status: "failed" | "completed" | "in-progress" | "dispatched";
+    repo: string | null;
+    ticket_id: string;
+    task_id: string;
+    worker_did: string;
+    branch: string | null;
+    pr_number: number | null;
+    dispatched_at: string;
+    completed_at: string | null;
+}>;
+export type DispatchRow = z.infer<typeof DispatchRowSchema>;
+export interface RecordDispatchInput {
+    taskId: string;
+    ticketId: string;
+    workerDid: string;
+    repo?: string;
+    branch?: string;
+    prNumber?: number;
+}
+export declare function recordDispatch(db: Ledger, input: RecordDispatchInput): DispatchRow;
+export declare function getDispatch(db: Ledger, taskId: string): DispatchRow | undefined;
+/**
+ * The ticket a task belongs to, or null when this task was never dispatched
+ * through the ledger.
+ *
+ * Null is an ordinary answer, not an error: the hub is multi-tenant and emits
+ * events for work this orchestrator did not start. The caller records the
+ * observation with no ticket rather than guessing at one.
+ */
+export declare function findTicketIdByTaskId(db: Ledger, taskId: string): string | null;
+/**
+ * Find the ticket behind a pull request.
+ *
+ * The only correlation available for review events. `pr_quorum_reached` carries
+ * `repo`/`prNumber`/`headSha` and no task id at all, and `review_verdict`'s task
+ * id is optional AND belongs to the reviewer's task rather than the dispatch
+ * that produced the branch. Without this, every quorum event lands in the
+ * journal with a null ticket, which is why the Review lens could show that
+ * something was approved but not what.
+ *
+ * `idx_dispatches_pr` already indexed (repo, pr_number) with no reader; this is
+ * the reader it was waiting for.
+ *
+ * Newest dispatch wins. A PR reopened after a failed first attempt has two
+ * dispatch rows, and the live one is the recent one.
+ *
+ * Ties break on `rowid` DESC, meaning last-inserted, because `dispatched_at`
+ * has millisecond resolution and a retry loop can record two dispatches inside
+ * one millisecond. Tiebreaking on `task_id` instead would order them
+ * alphabetically, which silently returns whichever id happens to sort lower --
+ * the older attempt as often as not.
+ *
+ * Null is an ordinary answer for the same reason as {@link findTicketIdByTaskId}:
+ * the hub is multi-tenant and reviews PRs this orchestrator never dispatched.
+ */
+export declare function findTicketIdByPr(db: Ledger, repo: string, prNumber: number): string | null;
+export declare function setDispatchStatus(db: Ledger, taskId: string, status: DispatchStatus): DispatchRow;
+/**
+ * Read dispatches, newest first, optionally capped.
+ *
+ * The cap is applied in SQL rather than by the caller slicing the result.
+ * Dispatches are never deleted, so this table only grows: a cap enforced after
+ * the read bounds the RESPONSE while still asking SQLite to materialise every
+ * dispatch ever recorded, which is the opposite of what a row cap is for. The
+ * ticket and journal readers already capped in SQL for this reason; this one was
+ * the outlier.
+ *
+ * `task_id` breaks ties because `dispatched_at` is an ISO timestamp and not
+ * unique -- two dispatches recorded 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 listDispatches(db: Ledger, limit?: number): DispatchRow[];
+//# sourceMappingURL=dispatches.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatches.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/db/dispatches.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,oBAAoB,iEAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,WAAW,CAelF;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAI/E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW1F;AAED,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,GACrB,WAAW,CAUb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAKxE"}

package/dist/orchestrator/db/dispatches.js

@@ -0,0 +1,122 @@
+/**
+ * Dispatch store (ORC-W1 PR-2).
+ *
+ * One row per task handed to a worker. Its job in PR-2 is correlation: it is
+ * how an incoming hub event, which knows a taskId, becomes a journal entry
+ * attached to the right ticket.
+ *
+ * @module orchestrator/db/dispatches
+ */
+import { z } from "zod";
+import { rowCap } from "./index.js";
+export const DispatchStatusSchema = z.enum([
+    "dispatched",
+    "in-progress",
+    "completed",
+    "failed",
+]);
+export const DispatchRowSchema = z.object({
+    task_id: z.string(),
+    ticket_id: z.string(),
+    worker_did: z.string(),
+    repo: z.string().nullable(),
+    branch: z.string().nullable(),
+    pr_number: z.number().nullable(),
+    status: DispatchStatusSchema,
+    dispatched_at: z.string(),
+    completed_at: z.string().nullable(),
+});
+export function recordDispatch(db, input) {
+    db.prepare(`INSERT INTO dispatches
+       (task_id, ticket_id, worker_did, repo, branch, pr_number, status, dispatched_at)
+     VALUES (?, ?, ?, ?, ?, ?, 'dispatched', ?)`).run(input.taskId, input.ticketId, input.workerDid, input.repo ?? null, input.branch ?? null, input.prNumber ?? null, new Date().toISOString());
+    return getDispatch(db, input.taskId);
+}
+export function getDispatch(db, taskId) {
+    const row = db.prepare(`SELECT * FROM dispatches WHERE task_id = ?`).get(taskId);
+    if (row === undefined || row === null)
+        return undefined;
+    return DispatchRowSchema.parse(row);
+}
+/**
+ * The ticket a task belongs to, or null when this task was never dispatched
+ * through the ledger.
+ *
+ * Null is an ordinary answer, not an error: the hub is multi-tenant and emits
+ * events for work this orchestrator did not start. The caller records the
+ * observation with no ticket rather than guessing at one.
+ */
+export function findTicketIdByTaskId(db, taskId) {
+    const row = db.prepare(`SELECT ticket_id FROM dispatches WHERE task_id = ?`).get(taskId);
+    if (row === undefined || row === null)
+        return null;
+    return z.object({ ticket_id: z.string() }).parse(row).ticket_id;
+}
+/**
+ * Find the ticket behind a pull request.
+ *
+ * The only correlation available for review events. `pr_quorum_reached` carries
+ * `repo`/`prNumber`/`headSha` and no task id at all, and `review_verdict`'s task
+ * id is optional AND belongs to the reviewer's task rather than the dispatch
+ * that produced the branch. Without this, every quorum event lands in the
+ * journal with a null ticket, which is why the Review lens could show that
+ * something was approved but not what.
+ *
+ * `idx_dispatches_pr` already indexed (repo, pr_number) with no reader; this is
+ * the reader it was waiting for.
+ *
+ * Newest dispatch wins. A PR reopened after a failed first attempt has two
+ * dispatch rows, and the live one is the recent one.
+ *
+ * Ties break on `rowid` DESC, meaning last-inserted, because `dispatched_at`
+ * has millisecond resolution and a retry loop can record two dispatches inside
+ * one millisecond. Tiebreaking on `task_id` instead would order them
+ * alphabetically, which silently returns whichever id happens to sort lower --
+ * the older attempt as often as not.
+ *
+ * Null is an ordinary answer for the same reason as {@link findTicketIdByTaskId}:
+ * the hub is multi-tenant and reviews PRs this orchestrator never dispatched.
+ */
+export function findTicketIdByPr(db, repo, prNumber) {
+    const row = db
+        .prepare(`SELECT ticket_id FROM dispatches
+        WHERE repo = ? AND pr_number = ?
+        ORDER BY dispatched_at DESC, rowid DESC
+        LIMIT 1`)
+        .get(repo, prNumber);
+    if (row === undefined || row === null)
+        return null;
+    return z.object({ ticket_id: z.string() }).parse(row).ticket_id;
+}
+export function setDispatchStatus(db, taskId, status) {
+    const completedAt = status === "completed" || status === "failed" ? new Date().toISOString() : null;
+    const info = db
+        .prepare(`UPDATE dispatches SET status = ?, completed_at = ? WHERE task_id = ?`)
+        .run(status, completedAt, taskId);
+    if (info.changes === 0) {
+        throw new Error(`orchestrator: cannot update unknown dispatch ${taskId}`);
+    }
+    return getDispatch(db, taskId);
+}
+/**
+ * Read dispatches, newest first, optionally capped.
+ *
+ * The cap is applied in SQL rather than by the caller slicing the result.
+ * Dispatches are never deleted, so this table only grows: a cap enforced after
+ * the read bounds the RESPONSE while still asking SQLite to materialise every
+ * dispatch ever recorded, which is the opposite of what a row cap is for. The
+ * ticket and journal readers already capped in SQL for this reason; this one was
+ * the outlier.
+ *
+ * `task_id` breaks ties because `dispatched_at` is an ISO timestamp and not
+ * unique -- two dispatches recorded 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 listDispatches(db, limit) {
+    const rows = db
+        .prepare(`SELECT * FROM dispatches ORDER BY dispatched_at DESC, task_id DESC LIMIT ?`)
+        .all(rowCap(limit));
+    return z.array(DispatchRowSchema).parse(rows);
+}
+//# sourceMappingURL=dispatches.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatches.js","sourceRoot":"","sources":["../../../src/orchestrator/db/dispatches.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAe,MAAM,YAAY,CAAC;AAEjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC;IACzC,YAAY;IACZ,aAAa;IACb,WAAW;IACX,QAAQ;CACT,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,MAAM,EAAE,oBAAoB;IAC5B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAYH,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,KAA0B;IACnE,EAAE,CAAC,OAAO,CACR;;gDAE4C,CAC7C,CAAC,GAAG,CACH,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,IAAI,IAAI,IAAI,EAClB,KAAK,CAAC,MAAM,IAAI,IAAI,EACpB,KAAK,CAAC,QAAQ,IAAI,IAAI,EACtB,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CACzB,CAAC;IACF,OAAO,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,MAAM,CAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,MAAc;IACpD,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,4CAA4C,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjF,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACxD,OAAO,iBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAU,EAAE,MAAc;IAC7D,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,oDAAoD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACzF,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAU,EAAE,IAAY,EAAE,QAAgB;IACzE,MAAM,GAAG,GAAG,EAAE;SACX,OAAO,CACN;;;gBAGU,CACX;SACA,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,EAAU,EACV,MAAc,EACd,MAAsB;IAEtB,MAAM,WAAW,GACf,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CAAC,sEAAsE,CAAC;SAC/E,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,gDAAgD,MAAM,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,WAAW,CAAC,EAAE,EAAE,MAAM,CAAE,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU,EAAE,KAAc;IACvD,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CAAC,4EAA4E,CAAC;SACrF,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtB,OAAO,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAChD,CAAC"}

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

@@ -0,0 +1,50 @@
+/**
+ * Ledger open + schema application.
+ *
+ * Lives inside `@kya-os/cli` rather than in a package of its own. The last
+ * internal package extracted from this CLI (`@kya-os/cli-kit`) had exactly one
+ * consumer and a `workspace:*` dependency that blocked publishing, and was
+ * folded back in. One consumer does not justify a package.
+ *
+ * @module cli/orchestrator/db
+ */
+import type BetterSqlite3 from "better-sqlite3";
+export type Ledger = BetterSqlite3.Database;
+/**
+ * How long a writer waits on SQLite's own lock before giving up, in ms.
+ *
+ * Without this, a second connection's write against an already-locked
+ * database gets `SQLITE_BUSY` back IMMEDIATELY -- not after a wait, on the
+ * very first attempt -- and every caller here (the journal writer, the
+ * liveness beat, a reconnect's replay) treats that as a genuine failure
+ * rather than momentary contention. `busy_timeout` makes SQLite retry
+ * acquiring the lock internally for this long before it reports busy, which
+ * is what turns a same-instant collision between two writers into a queued
+ * write instead of a dropped one.
+ */
+export declare const LEDGER_BUSY_TIMEOUT_MS = 5000;
+/**
+ * Turn an optional caller cap into a SQL `LIMIT` value.
+ *
+ * SQLite reads ANY negative LIMIT as "no limit", which is what makes the omitted
+ * case a one-statement affair -- but it also means a caller who passes a bad cap
+ * gets the whole table back. `-1` meaning unlimited is a deliberate sentinel;
+ * `-5` arriving from a caller's arithmetic is a bug, and answering it with every
+ * row is the exact failure a row cap exists to prevent, reached by asking for
+ * fewer rows.
+ *
+ * Shared by every capped reader so the sentinel is written once and the
+ * validation cannot be present in one store and missing in the next.
+ */
+export declare function rowCap(limit: number | undefined): number;
+/** Per-user state directory for the orchestrator ledger. */
+export declare function stateDir(): string;
+/** Default on-disk location of the ledger. */
+export declare function defaultLedgerPath(): string;
+/**
+ * Open (creating if absent) the ledger and apply the schema.
+ *
+ * Pass `":memory:"` for tests.
+ */
+export declare function openLedger(path?: string): Ledger;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/db/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAC;AAGhD,MAAM,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC;AAI5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AA0B5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMxD;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,IAAI,MAAM,CAOjC;AAED,8CAA8C;AAC9C,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,MAA4B,GAAG,MAAM,CA0BrE"}

package/dist/orchestrator/db/index.js

@@ -0,0 +1,116 @@
+/**
+ * Ledger open + schema application.
+ *
+ * Lives inside `@kya-os/cli` rather than in a package of its own. The last
+ * internal package extracted from this CLI (`@kya-os/cli-kit`) had exactly one
+ * consumer and a `workspace:*` dependency that blocked publishing, and was
+ * folded back in. One consumer does not justify a package.
+ *
+ * @module cli/orchestrator/db
+ */
+import { createRequire } from "node:module";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { LEDGER_SCHEMA } from "./schema.js";
+const require_ = createRequire(import.meta.url);
+/**
+ * How long a writer waits on SQLite's own lock before giving up, in ms.
+ *
+ * Without this, a second connection's write against an already-locked
+ * database gets `SQLITE_BUSY` back IMMEDIATELY -- not after a wait, on the
+ * very first attempt -- and every caller here (the journal writer, the
+ * liveness beat, a reconnect's replay) treats that as a genuine failure
+ * rather than momentary contention. `busy_timeout` makes SQLite retry
+ * acquiring the lock internally for this long before it reports busy, which
+ * is what turns a same-instant collision between two writers into a queued
+ * write instead of a dropped one.
+ */
+export const LEDGER_BUSY_TIMEOUT_MS = 5000;
+/**
+ * Load the SQLite driver on first use.
+ *
+ * `better-sqlite3` is an OPTIONAL dependency, and loaded lazily so it stays
+ * that way in practice. It is the only native addon `@kya-os/cli` pulls in,
+ * and the overwhelming majority of this CLI's users run `init`, `register` or
+ * `dco` and never touch the orchestrator at all. A top-level import would make
+ * every one of them download or compile it, and would break the entire CLI on
+ * any platform lacking a prebuild, rather than just the commands that need a
+ * database.
+ */
+function loadDriver() {
+    try {
+        return require_("better-sqlite3");
+    }
+    catch (err) {
+        throw new Error("Orchestrator commands need the optional 'better-sqlite3' dependency, " +
+            "which is not installed or failed to build. Install it with " +
+            "`npm install better-sqlite3`. " +
+            `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Turn an optional caller cap into a SQL `LIMIT` value.
+ *
+ * SQLite reads ANY negative LIMIT as "no limit", which is what makes the omitted
+ * case a one-statement affair -- but it also means a caller who passes a bad cap
+ * gets the whole table back. `-1` meaning unlimited is a deliberate sentinel;
+ * `-5` arriving from a caller's arithmetic is a bug, and answering it with every
+ * row is the exact failure a row cap exists to prevent, reached by asking for
+ * fewer rows.
+ *
+ * Shared by every capped reader so the sentinel is written once and the
+ * validation cannot be present in one store and missing in the next.
+ */
+export function rowCap(limit) {
+    if (limit === undefined)
+        return -1;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error(`orchestrator: limit must be a positive integer, got ${String(limit)}`);
+    }
+    return limit;
+}
+/** Per-user state directory for the orchestrator ledger. */
+export function stateDir() {
+    const override = process.env.KYA_OS_ORCHESTRATOR_STATE_DIR;
+    if (override)
+        return override;
+    const xdg = process.env.XDG_STATE_HOME;
+    return xdg
+        ? join(xdg, "kya-os", "orchestrator")
+        : join(homedir(), ".local", "state", "kya-os", "orchestrator");
+}
+/** Default on-disk location of the ledger. */
+export function defaultLedgerPath() {
+    return join(stateDir(), "ledger.db");
+}
+/**
+ * Open (creating if absent) the ledger and apply the schema.
+ *
+ * Pass `":memory:"` for tests.
+ */
+export function openLedger(path = defaultLedgerPath()) {
+    if (path !== ":memory:") {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    const Database = loadDriver();
+    const db = new Database(path);
+    // See LEDGER_BUSY_TIMEOUT_MS. Meaningless for a private `:memory:` database
+    // (no other connection can ever reach it), but harmless to set regardless --
+    // one pragma applied unconditionally beats a conditional whose only purpose
+    // is to skip a no-op.
+    db.pragma(`busy_timeout = ${LEDGER_BUSY_TIMEOUT_MS}`);
+    // WAL so a reader (a TUI, another CLI invocation) never blocks the writer.
+    // An in-memory database cannot journal to a file, and asking it to silently
+    // leaves journal_mode at "memory", so only set it where it means something.
+    if (path !== ":memory:") {
+        db.pragma("journal_mode = WAL");
+    }
+    // The schema leans on foreign keys (superseded_by, dispatches.ticket_id).
+    // SQLite defaults this OFF per-connection, so forgetting it turns every
+    // referential guarantee into a comment.
+    db.pragma("foreign_keys = ON");
+    db.exec(LEDGER_SCHEMA);
+    return db;
+}
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,93 @@
+/**
+ * Journal store (ORC-W1 PR-2).
+ *
+ * The journal records what the daemon OBSERVED, written from protocol events
+ * rather than from a model narrating its own behaviour. That distinction is
+ * the whole reason the daemon is the single writer.
+ *
+ * @module orchestrator/db/journal
+ */
+import { z } from "zod";
+import { type Ledger } from "./index.js";
+import type { HubEventLike } from "../events.js";
+export declare const JournalRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    ticket_id: z.ZodNullable<z.ZodString>;
+    event_type: z.ZodString;
+    agent_did: z.ZodNullable<z.ZodString>;
+    agent_name: z.ZodNullable<z.ZodString>;
+    data: z.ZodString;
+    observed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    data: string;
+    id: string;
+    ticket_id: string | null;
+    event_type: string;
+    agent_did: string | null;
+    agent_name: string | null;
+    observed_at: string;
+}, {
+    data: string;
+    id: string;
+    ticket_id: string | null;
+    event_type: string;
+    agent_did: string | null;
+    agent_name: string | null;
+    observed_at: string;
+}>;
+export type JournalRow = z.infer<typeof JournalRowSchema>;
+/**
+ * Deterministic id for an event, so replaying it is a no-op.
+ *
+ * Hub events carry no id of their own, and the daemon replays a window of
+ * recent events on every boot to recover what it slept through. Without a
+ * content-derived key each restart would duplicate that window, and the
+ * journal's value is that you can count things in it.
+ *
+ * Derived from the fields that identify an occurrence rather than from
+ * arrival order, so the same event seen live and again on replay collapses to
+ * one row.
+ */
+export declare function journalEventId(event: HubEventLike): string;
+export interface AppendJournalInput {
+    event: HubEventLike;
+    ticketId?: string | null;
+    /**
+     * Override the content-derived id, for a row that records an ACT rather than
+     * an observation.
+     *
+     * The default id is a hash of the event's content, which makes a replayed hub
+     * observation collapse to one row -- correct, and the reason the journal can
+     * be counted. It is wrong for something the system DID. Two identical status
+     * transitions in the same millisecond are two distinct acts, and content
+     * addressing silently dropped the second while its ticket write committed,
+     * leaving state that the evidence beside it disagreed with.
+     *
+     * So: observations are keyed by what they are, acts are keyed by being a
+     * separate occurrence. Callers recording an act pass a fresh id.
+     */
+    id?: string;
+}
+/**
+ * Append an observation. Idempotent: a replayed event updates nothing and
+ * inserts nothing, because its id is derived from its content.
+ *
+ * Returns true when the row was new, which lets a caller distinguish "first
+ * time seen" from "replayed" without a second query.
+ */
+export declare function appendJournal(db: Ledger, input: AppendJournalInput): boolean;
+/**
+ * Recent entries, newest first.
+ *
+ * Ties on `observed_at` break on `rowid`, i.e. insertion order, matching the
+ * dispatch reader. `id` used to serve as the tiebreak, which read as ordered
+ * only because content-addressed ids made same-millisecond duplicates collapse
+ * in the first place. Once acts are keyed per occurrence they genuinely coexist
+ * within a millisecond, and ordering them by id is uuid order -- no order at
+ * all. An audit trail that lists three transitions in the wrong sequence is
+ * worse than one that lists two, because it reads as authoritative.
+ */
+export declare function listJournal(db: Ledger, limit?: number): JournalRow[];
+export declare function listJournalForTicket(db: Ledger, ticketId: string, limit?: number): JournalRow[];
+export declare function countJournal(db: Ledger): number;
+//# sourceMappingURL=journal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/db/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;EAQ3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAS1D;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;;;;;;;;;;OAaG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAkB5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,UAAU,EAAE,CAKjE;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,KAAK,SAAM,GACV,UAAU,EAAE,CASd;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/orchestrator/db/journal.js

@@ -0,0 +1,91 @@
+/**
+ * Journal store (ORC-W1 PR-2).
+ *
+ * The journal records what the daemon OBSERVED, written from protocol events
+ * rather than from a model narrating its own behaviour. That distinction is
+ * the whole reason the daemon is the single writer.
+ *
+ * @module orchestrator/db/journal
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { rowCap } from "./index.js";
+export const JournalRowSchema = z.object({
+    id: z.string(),
+    ticket_id: z.string().nullable(),
+    event_type: z.string(),
+    agent_did: z.string().nullable(),
+    agent_name: z.string().nullable(),
+    data: z.string(),
+    observed_at: z.string(),
+});
+/**
+ * Deterministic id for an event, so replaying it is a no-op.
+ *
+ * Hub events carry no id of their own, and the daemon replays a window of
+ * recent events on every boot to recover what it slept through. Without a
+ * content-derived key each restart would duplicate that window, and the
+ * journal's value is that you can count things in it.
+ *
+ * Derived from the fields that identify an occurrence rather than from
+ * arrival order, so the same event seen live and again on replay collapses to
+ * one row.
+ */
+export function journalEventId(event) {
+    const canonical = JSON.stringify([
+        event.type,
+        event.timestamp,
+        event.agentDid,
+        event.agentName,
+        event.data,
+    ]);
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
+}
+/**
+ * Append an observation. Idempotent: a replayed event updates nothing and
+ * inserts nothing, because its id is derived from its content.
+ *
+ * Returns true when the row was new, which lets a caller distinguish "first
+ * time seen" from "replayed" without a second query.
+ */
+export function appendJournal(db, input) {
+    const { event } = input;
+    const info = db
+        .prepare(`INSERT OR IGNORE INTO journal
+         (id, ticket_id, event_type, agent_did, agent_name, data, observed_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(input.id ?? journalEventId(event), input.ticketId ?? null, event.type, event.agentDid || null, event.agentName || null, JSON.stringify(event.data ?? {}), new Date(event.timestamp).toISOString());
+    return info.changes === 1;
+}
+/**
+ * Recent entries, newest first.
+ *
+ * Ties on `observed_at` break on `rowid`, i.e. insertion order, matching the
+ * dispatch reader. `id` used to serve as the tiebreak, which read as ordered
+ * only because content-addressed ids made same-millisecond duplicates collapse
+ * in the first place. Once acts are keyed per occurrence they genuinely coexist
+ * within a millisecond, and ordering them by id is uuid order -- no order at
+ * all. An audit trail that lists three transitions in the wrong sequence is
+ * worse than one that lists two, because it reads as authoritative.
+ */
+export function listJournal(db, limit = 100) {
+    const rows = db
+        .prepare(`SELECT * FROM journal ORDER BY observed_at DESC, rowid DESC LIMIT ?`)
+        .all(rowCap(limit));
+    return z.array(JournalRowSchema).parse(rows);
+}
+export function listJournalForTicket(db, ticketId, limit = 100) {
+    // Bounded like listJournal, and validated like it too. An unbounded branch
+    // here means a caller's validated cap is silently ignored the moment it also
+    // passes a ticket id, which is the shape a cap-bypass usually takes: not a
+    // missing check, a second path that forgot it.
+    const rows = db
+        .prepare(`SELECT * FROM journal WHERE ticket_id = ? ORDER BY observed_at DESC, rowid DESC LIMIT ?`)
+        .all(ticketId, rowCap(limit));
+    return z.array(JournalRowSchema).parse(rows);
+}
+export function countJournal(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM journal`).get();
+    return z.object({ n: z.number() }).parse(row).n;
+}
+//# sourceMappingURL=journal.js.map

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

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