@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/db/schema.mts

@@ -0,0 +1,195 @@
+/**
+ * Bumped on any change an existing database file cannot absorb. `Database.open`
+ * refuses a file whose recorded version differs. The database is a rebuildable
+ * cache (the graph re-derives from a full sync; sessions and claims are pure
+ * runtime state), so a bump's recovery is "delete the file and re-sync" — there
+ * is no migration machinery.
+ */
+export const SCHEMA_VERSION = 6;
+
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS node (
+  id          INTEGER PRIMARY KEY,
+  external_id TEXT NOT NULL UNIQUE,
+  kind        TEXT NOT NULL CHECK (kind IN ('project','milestone','ticket','pr','unknown'))
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS project (
+  node_id INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  name    TEXT NOT NULL,
+  source  TEXT
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS milestone (
+  node_id    INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  project_id INTEGER NOT NULL REFERENCES node(id),
+  name       TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS ticket (
+  node_id        INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  project_id     INTEGER NOT NULL REFERENCES node(id),
+  url            TEXT NOT NULL,
+  title          TEXT NOT NULL,
+  status         TEXT NOT NULL CHECK (status IN (
+                   'backlog','paused','awaiting-external','available','in-progress',
+                   'in-review','finished','delivered','verified','canceled')),
+  target_kind    TEXT NOT NULL CHECK (target_kind IN ('pr','verification','human-only')),
+  requires_human INTEGER NOT NULL CHECK (requires_human IN (0,1)),
+  injected       INTEGER NOT NULL CHECK (injected IN (0,1)),
+  priority       REAL,
+  branch_hint    TEXT,
+  labels         TEXT NOT NULL,
+  updated_at     TEXT
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS pr (
+  node_id    INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  ticket_id  INTEGER REFERENCES node(id),
+  origin     TEXT NOT NULL CHECK (origin IN ('prompt','ticket','adopted','resumed')),
+  repo       TEXT,
+  pr_number  INTEGER,
+  url        TEXT,
+  branch     TEXT,
+  title      TEXT NOT NULL,
+  injected   INTEGER NOT NULL CHECK (injected IN (0,1)),
+  priority   REAL,
+  updated_at TEXT
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS edge (
+  blocker INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+  blocked INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+  PRIMARY KEY (blocker, blocked),
+  CHECK (blocker <> blocked)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS session (
+  id                TEXT PRIMARY KEY,
+  host              TEXT,
+  pid               INTEGER,
+  claude_session_id TEXT,
+  acked_at          TEXT,
+  started_at        TEXT NOT NULL,
+  heartbeat_at      TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS claim (
+  node_id    INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  session_id TEXT NOT NULL REFERENCES session(id) ON DELETE CASCADE,
+  actor      TEXT,
+  worktree   TEXT,
+  branch     TEXT,
+  claimed_at TEXT NOT NULL
+) STRICT;
+
+/* A worker's PR wait, handed to the server. The snapshot column holds the last
+   observation the poll took; diffing the next one against it is what turns
+   "something changed" into named events. */
+CREATE TABLE IF NOT EXISTS watch (
+  node_id    INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  state      TEXT NOT NULL CHECK (state IN ('watching','fired')),
+  snapshot   TEXT,
+  interval_s INTEGER NOT NULL,
+  session_id TEXT,
+  created_at TEXT NOT NULL,
+  checked_at TEXT,
+  expires_at TEXT NOT NULL
+) STRICT;
+
+/* Observations owed to a session, oldest first. Delivery is recorded so a
+   server restart re-pushes what nobody heard rather than assuming it landed.
+   session_id is the session whose worker armed the wait: with a shared graph
+   DB several servers drain this table, and only that one can route the event
+   to the worker holding the PR. A null session_id is drainable by any. */
+CREATE TABLE IF NOT EXISTS pr_event (
+  id           INTEGER PRIMARY KEY,
+  node_id      INTEGER NOT NULL REFERENCES node(id) ON DELETE CASCADE,
+  kind         TEXT NOT NULL,
+  summary      TEXT NOT NULL,
+  meta         TEXT NOT NULL,
+  session_id   TEXT,
+  observed_at  TEXT NOT NULL,
+  delivered_at TEXT
+) STRICT;
+
+/* A live worker's address: the agent ref its launcher got back, recorded so
+   an event for the node can be relayed to the worker that already holds its
+   context. Cleared with the outcome — not the yield — so a yielded worker
+   stays resumable until it reports. */
+CREATE TABLE IF NOT EXISTS worker (
+  node_id    INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  session_id TEXT NOT NULL REFERENCES session(id) ON DELETE CASCADE,
+  agent_ref  TEXT NOT NULL,
+  launched_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS outcome (
+  node_id     INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  outcome     TEXT NOT NULL CHECK (outcome IN
+                ('verified','canceled','delivered','human-blocked','decomposed','failed')),
+  retryable   INTEGER CHECK (retryable IN (0,1)),
+  detail      TEXT,
+  recorded_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS review (
+  milestone_id INTEGER PRIMARY KEY REFERENCES node(id) ON DELETE CASCADE,
+  recorded_at  TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS review_member (
+  milestone_id       INTEGER NOT NULL REFERENCES review(milestone_id) ON DELETE CASCADE,
+  member_external_id TEXT NOT NULL,
+  PRIMARY KEY (milestone_id, member_external_id)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS cursor (
+  source TEXT PRIMARY KEY,
+  value  TEXT NOT NULL
+) STRICT;
+
+/* A refresh must outlive the staleness sweep that reaps its session, which is the case takeover exists for. */
+CREATE TABLE IF NOT EXISTS refresh (
+  source                TEXT PRIMARY KEY,
+  state                 TEXT NOT NULL CHECK (state IN ('scanning','resolving','idle')),
+  session_id            TEXT,
+  projects              TEXT NOT NULL,
+  pending_cursor        TEXT,
+  started_at            TEXT NOT NULL,
+  completed_at          TEXT,
+  completion_emitted_at TEXT
+) STRICT;
+
+/* One row per condition order in flight: fires once while its condition holds,
+   cleared when the condition lapses so a new episode can fire again. */
+CREATE TABLE IF NOT EXISTS notice (
+  kind       TEXT NOT NULL CHECK (kind IN ('park_human_blocked','alert_failure','project_complete')),
+  node       TEXT NOT NULL,
+  emitted_at TEXT NOT NULL,
+  PRIMARY KEY (kind, node)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS fetch_request (
+  id           INTEGER PRIMARY KEY,
+  source       TEXT NOT NULL,
+  kind         TEXT NOT NULL CHECK (kind IN ('scan_project','fetch_ticket','refresh_ticket')),
+  payload      TEXT NOT NULL,
+  created_at   TEXT NOT NULL,
+  delivered_at TEXT,
+  resolution   TEXT CHECK (resolution IN ('materialized','missing'))
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS ticket_project      ON ticket (project_id);
+CREATE INDEX IF NOT EXISTS milestone_project   ON milestone (project_id);
+CREATE INDEX IF NOT EXISTS pr_ticket           ON pr (ticket_id);
+CREATE INDEX IF NOT EXISTS edge_blocked        ON edge (blocked);
+CREATE INDEX IF NOT EXISTS claim_session       ON claim (session_id);
+CREATE INDEX IF NOT EXISTS fetch_request_open  ON fetch_request (source, resolution);
+CREATE INDEX IF NOT EXISTS pr_event_undelivered ON pr_event (delivered_at, session_id, id);
+`;

package/src/lib/db/time.mts

@@ -0,0 +1,24 @@
+import {DataError, ensure} from '../errors/index.mts';
+
+/**
+ * RFC 3339 shape, checked before Date.parse: V8 also accepts local formats like
+ * "07/31/2026", which would record an instant the caller never meant.
+ */
+const RFC3339_RE =
+  /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:[Zz]|[+-]\d{2}:\d{2})$/u;
+
+/** The current instant as a Zulu ISO-8601 string — what callers stamp rows with. */
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/** Reject a timestamp that is not RFC 3339, where the fix is naming the field. */
+export function assertInstant(value: string, field: string): void {
+  ensure(
+    RFC3339_RE.test(value) && !Number.isNaN(Date.parse(value)),
+    () =>
+      new DataError(`${field} is not an RFC 3339 timestamp: "${value}"`, {
+        hint: `pass an instant like 2026-07-31T12:00:00Z, or omit ${field}.`,
+      })
+  );
+}

package/src/lib/db/with-database.mts

@@ -0,0 +1,56 @@
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+
+import type {Option} from '../command/index.mts';
+import {Database} from './database.mts';
+
+/**
+ * The `--db` flag every graph-writing command carries. Declared `as const
+ * satisfies Option` rather than typed `Option`: `ParsedOptions` reads the
+ * literal `type` to decide what `run` receives, and a widened type resolves to
+ * `never`.
+ */
+export const DB_OPTION = {
+  type: 'string',
+  description:
+    'Graph database path. Defaults to $DISPATCH_DB, else $XDG_STATE_HOME/dispatch/graph-v2.db.',
+  positional: false,
+  required: false,
+} as const satisfies Option;
+
+export function resolveDbPath(
+  flag: string | undefined,
+  env: NodeJS.ProcessEnv
+): string {
+  if (flag !== undefined && flag !== '') return flag;
+  if (env.DISPATCH_DB !== undefined && env.DISPATCH_DB !== '')
+    return env.DISPATCH_DB;
+  const state =
+    env.XDG_STATE_HOME !== undefined && env.XDG_STATE_HOME !== ''
+      ? env.XDG_STATE_HOME
+      : join(homedir(), '.local', 'state');
+  // `graph-v2.db`, not `graph.db`: installations that ran the retired
+  // `dispatch graph …` CLI still have a `graph.db` in this directory at an
+  // incompatible schema, and `Database.open` refuses a file recorded at a
+  // foreign version. The suffix names the CLI generation, not the schema
+  // version.
+  return join(state, 'dispatch', 'graph-v2.db');
+}
+
+/**
+ * Open the graph, run `body`, and close it even if `body` throws. Several
+ * agents share one file, so a command that leaks its handle holds a lock the
+ * next one has to wait out.
+ */
+export async function withDatabase<T>(
+  flag: string | undefined,
+  env: NodeJS.ProcessEnv,
+  body: (db: Database) => Promise<T> | T
+): Promise<T> {
+  const db = await Database.open(resolveDbPath(flag, env));
+  try {
+    return await body(db);
+  } finally {
+    await db.close();
+  }
+}

package/src/lib/errors/CLAUDE.md

@@ -0,0 +1,18 @@
+# Errors
+
+The failure taxonomy the CLI and MCP server throw. Every deliberate error extends
+`DispatchError`, so one `instanceof` separates an intended failure from a crash.
+The caller is usually an agent, so errors carry an optional `hint` for whoever has
+to fix it. One class per file; `index.mts` re-exports all of them.
+
+`dispatch-error.mts` is the root: `message`, `hint`, `toString()` rendering
+message + hint, and no transport-specific field. `command-error.mts` —
+`CommandError` extends it for validate/discover/run failures, adding the CLI
+`exitCode`; `usage-error.mts` (2), `environment-error.mts` (3), and
+`definition-error.mts` (1) specialize it. `json-rpc-error.mts` — `JsonRpcError`
+also extends `DispatchError`, but as the MCP server's protocol fault it carries a
+JSON-RPC `code`, not an `exitCode` — a sibling of `CommandError`, not a command
+failure. `ensure.mts` holds `assertUsage` and the lazy `ensure`.
+
+Add a class only when a caller must branch on a failure the existing ones don't
+cover; give it its own file under the right parent.

package/src/lib/errors/command-error.mts

@@ -0,0 +1,13 @@
+import {DispatchError} from './dispatch-error.mts';
+
+/**
+ * A failure from validating, discovering, or running a command. The CLI returns
+ * its `exitCode`; the MCP transport renders it as an `isError` tool result. This
+ * is the base for the command-facing taxonomy — a transport-protocol failure
+ * (the MCP server's `JsonRpcError`) extends `DispatchError` directly instead, as
+ * a sibling of this, because it carries a protocol code rather than an exit code.
+ */
+export class CommandError extends DispatchError {
+  override readonly name: string = 'CommandError';
+  readonly exitCode: number = 1;
+}

package/src/lib/errors/data-error.mts

@@ -0,0 +1,12 @@
+import {CommandError} from './command-error.mts';
+
+/**
+ * The caller's input was well-formed but describes invalid data: a dependency
+ * cycle, an id used as two kinds, an unknown status. Distinct from `UsageError`
+ * (a malformed invocation) so a caller can branch on "fix the data" vs "fix the
+ * command line".
+ */
+export class DataError extends CommandError {
+  override readonly name: string = 'DataError';
+  override readonly exitCode = 4;
+}

package/src/lib/errors/definition-error.mts

@@ -0,0 +1,6 @@
+import {CommandError} from './command-error.mts';
+
+/** A command is defined or registered wrong — a bug in the plugin, fixed by editing the command file. */
+export class DefinitionError extends CommandError {
+  override readonly name: string = 'DefinitionError';
+}

package/src/lib/errors/dispatch-error.mts

@@ -0,0 +1,27 @@
+export interface DispatchErrorOptions extends ErrorOptions {
+  /** What to do about it, written for the agent that ran the command. */
+  readonly hint?: string;
+}
+
+/**
+ * An intended, caller-actionable failure, as opposed to a crash — the root of
+ * every deliberate error the plugin throws, so one `instanceof` tells the two
+ * apart. Command failures (`CommandError`) and transport-protocol failures
+ * (`JsonRpcError`) both extend it; the root itself holds no transport-specific
+ * field, only the `hint` and rendering common to all of them.
+ */
+export class DispatchError extends Error {
+  override readonly name: string = 'DispatchError';
+  readonly hint: string | undefined;
+
+  constructor(message: string, options: DispatchErrorOptions = {}) {
+    super(message, options);
+    this.hint = options.hint;
+  }
+
+  override toString(): string {
+    return this.hint === undefined
+      ? `${this.name}: ${this.message}`
+      : `${this.name}: ${this.message}\nhint: ${this.hint}`;
+  }
+}

package/src/lib/errors/ensure.mts

@@ -0,0 +1,22 @@
+import type {DispatchError} from './dispatch-error.mts';
+import {UsageError} from './usage-error.mts';
+
+/** `assert` for caller input: a failed check is a usage error, not a crash. */
+export function assertUsage(
+  condition: unknown,
+  message: string
+): asserts condition {
+  if (!condition) {
+    throw new UsageError(message);
+  }
+}
+
+/** `assert` against a taxonomy error, built lazily so the passing path never constructs it. */
+export function ensure(
+  condition: unknown,
+  error: () => DispatchError
+): asserts condition {
+  if (!condition) {
+    throw error();
+  }
+}

package/src/lib/errors/environment-error.mts

@@ -0,0 +1,7 @@
+import {CommandError} from './command-error.mts';
+
+/** A variable the command declared in `env` is missing. The command was right; the environment was not. */
+export class EnvironmentError extends CommandError {
+  override readonly name: string = 'EnvironmentError';
+  override readonly exitCode = 3;
+}

package/src/lib/errors/index.mts

@@ -0,0 +1,8 @@
+export * from './dispatch-error.mts';
+export * from './command-error.mts';
+export * from './data-error.mts';
+export * from './usage-error.mts';
+export * from './environment-error.mts';
+export * from './definition-error.mts';
+export * from './json-rpc-error.mts';
+export * from './ensure.mts';

package/src/lib/errors/json-rpc-error.mts

@@ -0,0 +1,18 @@
+import {DispatchError} from './dispatch-error.mts';
+
+/**
+ * A JSON-RPC protocol failure (bad method, malformed request, unknown tool).
+ * The server loop renders it into an `error` response. A sibling of
+ * `CommandError` under `DispatchError`: it carries a protocol `code` rather than
+ * an exit code, and unlike a command failure — which becomes a successful result
+ * with `isError: true` — it is a wire-level fault, not a tool result.
+ */
+export class JsonRpcError extends DispatchError {
+  override readonly name = 'JsonRpcError';
+  readonly code: number;
+
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+  }
+}

package/src/lib/errors/usage-error.mts

@@ -0,0 +1,7 @@
+import {CommandError} from './command-error.mts';
+
+/** The caller invoked the command wrong: an unknown flag, a missing argument, a bad choice. */
+export class UsageError extends CommandError {
+  override readonly name: string = 'UsageError';
+  override readonly exitCode = 2;
+}

package/src/lib/graph/CLAUDE.md

@@ -0,0 +1,17 @@
+# graph
+
+The derived read-model: every scheduling decision, as SQL over the stores'
+tables. Consumers read results; nothing re-derives.
+
+- `pipeline.mts` — the shared CTE prefix (edge semantics, blocking closure,
+  claim liveness, milestone gating, classification, the dispatch queue) plus
+  the rank/queue orderings and parameter plumbing. Read its doc comment first.
+- `queries.mts` — `classifiedItems`, `frontier`, `dispatchQueue`,
+  `milestoneStates` over the prefix, plus `repoPrLoad`: per-repo open and
+  building PR counts for the admission caps, read from the stored watch
+  snapshots rather than a fetch of its own.
+- `anomalies.mts` — global structure writes could not refuse: dangling
+  placeholder endpoints, mutually blocking projects, cycles as a safety net.
+- `derive.mts` — assembles counts and the terminal verdict from the above.
+- `rows.mts` — row → model narrowing shared by the queries.
+- `types.mts` — the result types and `DeriveOptions`.

package/src/lib/graph/anomalies.mts

@@ -0,0 +1,110 @@
+/* eslint-disable @typescript-eslint/require-await --
+ * `node:sqlite` is synchronous; the async facade keeps call sites stable. */
+import type {Database} from '../db/database.mts';
+import {integer, splitList, text} from './rows.mts';
+import type {Anomaly} from './types.mts';
+
+/**
+ * What the writes could not prevent. Kind conflicts, self-edges, cycles, and
+ * malformed timestamps are rejected at write time; what remains is global
+ * structure no single write can judge:
+ *
+ * - a placeholder edge endpoint — the node was never written (a fetch that
+ *   resolved `missing`, or an ingest that never completed);
+ * - two projects that block each other, so neither can finish first;
+ * - a cycle, as a safety net for a hand-edited or imported database.
+ */
+export async function anomalies(db: Database): Promise<Anomaly[]> {
+  const out: Anomaly[] = [];
+
+  const cycleNodes = db
+    .all(
+      `WITH RECURSIVE reach(target, id) AS (
+         SELECT blocker, blocked FROM edge
+         UNION
+         SELECT r.target, e.blocked FROM reach r JOIN edge e ON e.blocker = r.id
+       )
+       SELECT DISTINCT n.external_id AS id
+       FROM reach r JOIN node n ON n.id = r.target
+       WHERE r.target = r.id
+       ORDER BY id`
+    )
+    .map((row) => text(row.id) ?? '');
+  if (cycleNodes.length > 0) {
+    out.push({
+      kind: 'cycle',
+      nodes: cycleNodes,
+      detail: `dependency cycle through ${cycleNodes.join(', ')}; the CLI refuses cycle-closing edges, so this database was edited by something else — remove an edge to break the loop`,
+    });
+  }
+
+  for (const row of db.all(
+    `SELECT nb.external_id AS blocker, nb.kind AS blocker_kind,
+            nd.external_id AS blocked
+     FROM edge e
+     JOIN node nb ON nb.id = e.blocker
+     JOIN node nd ON nd.id = e.blocked
+     WHERE nb.kind = 'unknown' OR nd.kind = 'unknown'
+     ORDER BY blocker, blocked`
+  )) {
+    const blocker = text(row.blocker) ?? '';
+    const blocked = text(row.blocked) ?? '';
+    out.push({
+      kind: 'dangling-edge',
+      nodes: [blocker, blocked],
+      detail:
+        text(row.blocker_kind) === 'unknown'
+          ? `blocker ${blocker} of ${blocked} is not in the graph; ${blocked} is held blocked until ${blocker} is written or the edge is removed`
+          : `${blocker} blocks ${blocked}, which is not in the graph; the edge schedules nothing — write ${blocked} if it is in scope`,
+    });
+  }
+
+  const pairs = db.all(
+    `WITH pe(a, b) AS (
+       SELECT DISTINCT tb.project_id, td.project_id
+       FROM edge e
+       JOIN ticket tb ON tb.node_id = e.blocker
+       JOIN ticket td ON td.node_id = e.blocked
+       WHERE tb.project_id <> td.project_id
+     )
+     SELECT x.a AS a_id, x.b AS b_id,
+            pa.external_id AS a, pb.external_id AS b
+     FROM pe x
+     JOIN pe y ON y.a = x.b AND y.b = x.a
+     JOIN node pa ON pa.id = x.a
+     JOIN node pb ON pb.id = x.b
+     WHERE x.a < x.b
+     ORDER BY a, b`
+  );
+  for (const pair of pairs) {
+    const involved = db
+      .all(
+        `SELECT group_concat(id, ',') AS ids FROM (
+           SELECT DISTINCT n.external_id AS id
+           FROM edge e
+           JOIN ticket tb ON tb.node_id = e.blocker
+           JOIN ticket td ON td.node_id = e.blocked
+           JOIN node n ON n.id = e.blocker OR n.id = e.blocked
+           WHERE (tb.project_id = ? AND td.project_id = ?)
+              OR (tb.project_id = ? AND td.project_id = ?)
+           ORDER BY id
+         )`,
+        [
+          integer(pair.a_id),
+          integer(pair.b_id),
+          integer(pair.b_id),
+          integer(pair.a_id),
+        ]
+      )
+      .flatMap((row) => splitList(row.ids));
+    out.push({
+      kind: 'cross-project-reverse',
+      nodes: involved,
+      detail: `projects ${text(pair.a) ?? ''} and ${text(pair.b) ?? ''} block each other; neither can be completed first`,
+    });
+  }
+
+  return out;
+}
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/graph/derive.mts

@@ -0,0 +1,96 @@
+import type {Database} from '../db/database.mts';
+import {anomalies} from './anomalies.mts';
+import {classifiedItems, milestoneStates} from './queries.mts';
+import {text} from './rows.mts';
+import type {
+  Classification,
+  ClassificationCounts,
+  ClassifiedItem,
+  DeriveOptions,
+  DerivedGraph,
+  ProjectCounts,
+} from './types.mts';
+
+const OPEN: readonly Classification[] = [
+  'available',
+  'blocked',
+  'human-blocked',
+  'in-flight',
+  'dormant',
+];
+
+/**
+ * Assemble the derived graph. The reasoning — blocking, ranking, gating,
+ * classification, anomalies — is the SQL in `pipeline.mts`; this only reads
+ * those results and tallies counts, so no consumer re-derives anything.
+ */
+export async function derive(
+  db: Database,
+  options: DeriveOptions = {}
+): Promise<DerivedGraph> {
+  const items = await classifiedItems(db, options);
+  const tickets = items.filter((entry) => entry.item.kind === 'ticket');
+  const prs = items.filter((entry) => entry.item.kind === 'pr');
+  const milestones = await milestoneStates(db, options);
+
+  const allProjects = db
+    .all(
+      `SELECT n.external_id AS id, p.name FROM project p
+       JOIN node n ON n.id = p.node_id
+       WHERE (? IS NULL OR n.external_id = ?)
+       ORDER BY id`,
+      [options.project ?? null, options.project ?? null]
+    )
+    .map((row) => ({id: text(row.id) ?? '', name: text(row.name) ?? ''}));
+
+  // A project with an owed milestone review is not done: the review is work.
+  const isTerminal = (project: string): boolean =>
+    !tickets.some(
+      (entry) =>
+        entry.item.project === project && OPEN.includes(entry.classification)
+    ) &&
+    !milestones.some(
+      (milestone) =>
+        milestone.project === project &&
+        milestone.readyForReview &&
+        !milestone.reviewRecorded
+    );
+
+  const projects = allProjects.map((project) => ({
+    ...project,
+    terminal: isTerminal(project.id),
+  }));
+
+  return {
+    projects,
+    items: tickets,
+    milestones,
+    counts: allProjects.map((project): ProjectCounts => ({
+      project: project.id,
+      total: tickets.filter((entry) => entry.item.project === project.id)
+        .length,
+      ...tally(tickets.filter((entry) => entry.item.project === project.id)),
+      terminal: isTerminal(project.id),
+    })),
+    prs,
+    anomalies: await anomalies(db),
+    terminal:
+      projects.every((project) => project.terminal) &&
+      !prs.some((entry) => OPEN.includes(entry.classification)),
+  };
+}
+
+function tally(entries: readonly ClassifiedItem[]): ClassificationCounts {
+  const count = (kind: Classification): number =>
+    entries.filter((entry) => entry.classification === kind).length;
+
+  return {
+    available: count('available'),
+    blocked: count('blocked'),
+    humanBlocked: count('human-blocked'),
+    inFlight: count('in-flight'),
+    dormant: count('dormant'),
+    verified: count('verified'),
+    canceled: count('canceled'),
+  };
+}

package/src/lib/graph/index.mts

@@ -0,0 +1,26 @@
+export {anomalies} from './anomalies.mts';
+export {derive} from './derive.mts';
+export {DEFAULT_STALE_AFTER_SECONDS} from './pipeline.mts';
+export {
+  classifiedItems,
+  dispatchQueue,
+  frontier,
+  milestoneStates,
+  repoPrLoad,
+} from './queries.mts';
+export type {RepoPrLoad} from './queries.mts';
+export type {
+  Anomaly,
+  Classification,
+  ClassificationCounts,
+  ClassifiedItem,
+  ClaimView,
+  DerivedGraph,
+  DeriveOptions,
+  MilestoneState,
+  OutcomeView,
+  Pass,
+  ProjectCounts,
+  QueueEntry,
+  WorkItem,
+} from './types.mts';