@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/stores/pr-event.mts

@@ -0,0 +1,94 @@
+import type {Database} from '../db/database.mts';
+import {assertInstant} from '../db/time.mts';
+import type {ObservationKind} from '../watch/diff.mts';
+import {findNode} from './materialize.mts';
+
+/* eslint-disable @typescript-eslint/require-await --
+ * Async facade over synchronous `node:sqlite`; see `../db/database.mts`. */
+
+export interface PendingEvent {
+  readonly id: number;
+  readonly node: string;
+  readonly kind: ObservationKind;
+  readonly summary: string;
+  readonly meta: Readonly<Record<string, string>>;
+  readonly observedAt: string;
+}
+
+/**
+ * Observations the poll took and the session has not yet been told about.
+ *
+ * They outlive the tick that produced them: a push into a channel nobody is
+ * listening to would otherwise lose the one notice a waiting worker gets, and
+ * unlike a fetch instruction there is no later poll that re-derives it — the
+ * next snapshot compares against the state that already includes the change.
+ * So delivery is recorded, and a restart re-pushes what was never marked.
+ */
+export class PrEventStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  /**
+   * Undelivered observations this session may push, oldest first.
+   *
+   * Scoped to the session that armed the wait: several servers share one
+   * graph DB, and only the session whose worker holds the PR can route the
+   * event to it. A row with no session is drainable by any — it belongs to a
+   * wait armed outside a server. So is a row whose session is gone: the worker
+   * it named died with it, and a watch outlives its session often enough that
+   * holding the row would strand the last notice of every wait a restart
+   * interrupted.
+   */
+  async undelivered(session: string, limit = 50): Promise<PendingEvent[]> {
+    return this.#db
+      .all(
+        `SELECT e.id, n.external_id AS node, e.kind, e.summary, e.meta, e.observed_at
+         FROM pr_event e JOIN node n ON n.id = e.node_id
+         WHERE e.delivered_at IS NULL
+           AND (e.session_id IS NULL OR e.session_id = ?
+                OR NOT EXISTS (SELECT 1 FROM session s WHERE s.id = e.session_id))
+         ORDER BY e.id
+         LIMIT ?`,
+        [session, limit]
+      )
+      .map((row) => ({
+        id: Number(row.id),
+        node: String(row.node),
+        kind: row.kind as ObservationKind,
+        summary: String(row.summary),
+        meta: JSON.parse(String(row.meta)) as Record<string, string>,
+        observedAt: String(row.observed_at),
+      }));
+  }
+
+  /**
+   * Claim an event for delivery. True from exactly one caller: a session-NULL
+   * event is drainable by any server, and select-then-mark would let two of
+   * them push the same tracker transition — which a session then acts on
+   * twice. The claim is the conditional write, so push only after it.
+   */
+  async markDelivered(id: number, at: string): Promise<boolean> {
+    assertInstant(at, 'at');
+    return (
+      this.#db.run(
+        'UPDATE pr_event SET delivered_at = ? WHERE id = ? AND delivered_at IS NULL',
+        [at, id]
+      ) > 0
+    );
+  }
+
+  /**
+   * Drop a node's events. Called when its outcome lands: the item concluded,
+   * so anything still owed describes a wait that no longer exists.
+   */
+  async clear(node: string): Promise<number> {
+    const found = findNode(this.#db, node);
+    if (found === null) return 0;
+    return this.#db.run('DELETE FROM pr_event WHERE node_id = ?', [found.id]);
+  }
+}
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/stores/pr.mts

@@ -0,0 +1,167 @@
+import {assertInstant} from '../db/time.mts';
+import type {Database} from '../db/database.mts';
+import {DataError, ensure} from '../errors/index.mts';
+import {isPrOrigin, PR_ORIGIN_LIST} from '../model/status.mts';
+import type {Pr} from '../model/types.mts';
+import {findNode, materialize, nodeRef} from './materialize.mts';
+
+/* eslint-disable @typescript-eslint/require-await --
+ * Async facade over synchronous `node:sqlite`; see `../db/database.mts`. */
+
+/** A partial write: `id` names the item, every other key is optional. */
+export type PrPatch = Partial<Omit<Pr, 'id'>> & {id: string};
+
+function pick<K extends keyof Pr>(
+  patch: PrPatch,
+  key: K,
+  fallback: Pr[K]
+): Pr[K] {
+  const given = patch[key];
+  return given === undefined ? fallback : (given as Pr[K]);
+}
+
+export class PrStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  async upsertPr(pr: Pr): Promise<void> {
+    ensure(
+      isPrOrigin(pr.origin),
+      () =>
+        new DataError(`"${pr.origin}" is not a pr origin`, {
+          hint: `use one of: ${PR_ORIGIN_LIST}.`,
+        })
+    );
+    if (pr.updatedAt !== null) assertInstant(pr.updatedAt, '--updated-at');
+
+    await this.#db.transaction(() => {
+      this.#write(pr);
+    });
+  }
+
+  #write(pr: Pr): void {
+    const nodeId = materialize(this.#db, pr.id, 'pr');
+    const ticketId = pr.ticket === null ? null : nodeRef(this.#db, pr.ticket);
+    this.#db.run(
+      `INSERT INTO pr (
+         node_id, ticket_id, origin, repo, pr_number, url, branch, title,
+         injected, priority, updated_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         ticket_id = excluded.ticket_id, origin = excluded.origin,
+         repo = excluded.repo, pr_number = excluded.pr_number,
+         url = excluded.url, branch = excluded.branch, title = excluded.title,
+         injected = excluded.injected, priority = excluded.priority,
+         updated_at = excluded.updated_at`,
+      [
+        nodeId,
+        ticketId,
+        pr.origin,
+        pr.repo,
+        pr.prNumber,
+        pr.url,
+        pr.branch,
+        pr.title,
+        pr.injected ? 1 : 0,
+        pr.priority,
+        pr.updatedAt,
+      ]
+    );
+  }
+
+  /**
+   * Write only the fields the caller named, leaving the rest as they are.
+   *
+   * The full-record `upsertPr` is for a writer that holds the whole record —
+   * an adoption sweep reading the forge. A worker does not: its documented job
+   * is to keep the URL and PR number current as they come to exist, and it
+   * knows nothing about the ticket link or title the item was registered with.
+   * Assigning every column from a write like that silently unlinks the item
+   * from its ticket and resets its origin, which drops it out of every
+   * project-scoped view.
+   *
+   * Omitting a field preserves it; passing an explicit value — `null`
+   * included — sets it. An id with no row yet is created, taking the same
+   * defaults a bare registration would.
+   */
+  async patchPr(patch: PrPatch): Promise<void> {
+    const {origin} = patch;
+    if (origin !== undefined) {
+      ensure(
+        isPrOrigin(origin),
+        () =>
+          new DataError(`"${origin}" is not a pr origin`, {
+            hint: `use one of: ${PR_ORIGIN_LIST}.`,
+          })
+      );
+    }
+    if (patch.updatedAt != null) assertInstant(patch.updatedAt, '--updated-at');
+
+    await this.#db.transaction(() => {
+      const existing = this.#read(patch.id);
+      const merged: Pr = {
+        id: patch.id,
+        ticket: pick(patch, 'ticket', existing?.ticket ?? null),
+        origin: pick(patch, 'origin', existing?.origin ?? 'prompt'),
+        repo: pick(patch, 'repo', existing?.repo ?? null),
+        prNumber: pick(patch, 'prNumber', existing?.prNumber ?? null),
+        url: pick(patch, 'url', existing?.url ?? null),
+        branch: pick(patch, 'branch', existing?.branch ?? null),
+        title: pick(patch, 'title', existing?.title ?? ''),
+        injected: pick(patch, 'injected', existing?.injected ?? false),
+        priority: pick(patch, 'priority', existing?.priority ?? null),
+        updatedAt: pick(patch, 'updatedAt', existing?.updatedAt ?? null),
+      };
+      this.#write(merged);
+    });
+  }
+
+  async removePr(id: string): Promise<boolean> {
+    return this.#db.transaction(() => {
+      const node = findNode(this.#db, id);
+      if (node?.kind !== 'pr') return false;
+      this.#db.run('DELETE FROM node WHERE id = ?', [node.id]);
+      return true;
+    });
+  }
+
+  /* eslint-disable @typescript-eslint/no-base-to-string --
+   * SQLite hands back `unknown`; `String()` converts a primitive rather than
+   * asserting a type the row has not been checked for. */
+  async getPr(id: string): Promise<Pr | null> {
+    return this.#read(id);
+  }
+
+  #read(id: string): Pr | null {
+    const row = this.#db.get(
+      `SELECT n.external_id AS id, tn.external_id AS ticket, p.origin, p.repo,
+              p.pr_number, p.url, p.branch, p.title, p.injected, p.priority,
+              p.updated_at
+       FROM pr p
+       JOIN node n ON n.id = p.node_id
+       LEFT JOIN node tn ON tn.id = p.ticket_id
+       WHERE n.external_id = ?`,
+      [id]
+    );
+    if (row === undefined) return null;
+    return {
+      id: String(row.id),
+      ticket: row.ticket === null ? null : String(row.ticket),
+      origin: row.origin as Pr['origin'],
+      repo: row.repo === null ? null : String(row.repo),
+      prNumber: row.pr_number === null ? null : Number(row.pr_number),
+      url: row.url === null ? null : String(row.url),
+      branch: row.branch === null ? null : String(row.branch),
+      title: String(row.title),
+      injected: row.injected === 1,
+      priority: row.priority === null ? null : Number(row.priority),
+      updatedAt: row.updated_at === null ? null : String(row.updated_at),
+    };
+  }
+  /* eslint-enable @typescript-eslint/no-base-to-string */
+}
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/stores/project.mts

@@ -0,0 +1,79 @@
+import type {Database} from '../db/database.mts';
+import type {Project} from '../model/types.mts';
+import {findNode, materialize} from './materialize.mts';
+
+/* eslint-disable @typescript-eslint/require-await --
+ * Async facade over synchronous `node:sqlite`; see `../db/database.mts`. */
+
+/** Projects: the 1:1 scoping partition tickets and milestones belong to. */
+export class ProjectStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  async upsertProject(project: {
+    id: string;
+    name: string;
+    source?: string | null;
+  }): Promise<void> {
+    await this.#db.transaction(() => {
+      const nodeId = materialize(this.#db, project.id, 'project');
+      this.#db.run(
+        `INSERT INTO project (node_id, name, source) VALUES (?, ?, ?)
+         ON CONFLICT(node_id) DO UPDATE SET
+           name = excluded.name, source = excluded.source`,
+        [nodeId, project.name, project.source ?? null]
+      );
+    });
+  }
+
+  /**
+   * Remove a project. If a ticket or milestone still names it, demote its node
+   * to an `unknown` placeholder (the reference stays valid); otherwise delete
+   * the node outright. Returns whether a declared project was found.
+   */
+  async removeProject(id: string): Promise<boolean> {
+    return this.#db.transaction(() => {
+      const node = findNode(this.#db, id);
+      if (node?.kind !== 'project') return false;
+      const referenced =
+        this.#db.get(
+          `SELECT 1 FROM ticket WHERE project_id = ?
+           UNION SELECT 1 FROM milestone WHERE project_id = ? LIMIT 1`,
+          [node.id, node.id]
+        ) !== undefined;
+      this.#db.run('DELETE FROM project WHERE node_id = ?', [node.id]);
+      if (referenced) {
+        this.#db.run("UPDATE node SET kind = 'unknown' WHERE id = ?", [
+          node.id,
+        ]);
+      } else {
+        this.#db.run('DELETE FROM node WHERE id = ?', [node.id]);
+      }
+      return true;
+    });
+  }
+
+  /* eslint-disable @typescript-eslint/no-base-to-string --
+   * SQLite hands back `unknown`; `String()` converts a primitive rather than
+   * asserting a type the row has not been checked for. */
+  async getProject(id: string): Promise<Project | null> {
+    const row = this.#db.get(
+      `SELECT n.external_id AS id, p.name AS name, p.source AS source
+       FROM project p JOIN node n ON n.id = p.node_id
+       WHERE n.external_id = ?`,
+      [id]
+    );
+    if (row === undefined) return null;
+    return {
+      id: String(row.id),
+      name: String(row.name),
+      source: row.source === null ? null : String(row.source),
+    };
+  }
+  /* eslint-enable @typescript-eslint/no-base-to-string */
+}
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/stores/refresh.mts

@@ -0,0 +1,197 @@
+import type {Database} from '../db/database.mts';
+import {assertInstant} from '../db/time.mts';
+
+/* eslint-disable @typescript-eslint/require-await --
+ * Async facade over synchronous `node:sqlite`; see `../db/database.mts`. */
+
+export const REFRESH_STATES = ['scanning', 'resolving', 'idle'] as const;
+export type RefreshState = (typeof REFRESH_STATES)[number];
+
+export interface RefreshRow {
+  source: string;
+  state: RefreshState;
+  sessionId: string | null;
+  projects: string[];
+  pendingCursor: string | null;
+  startedAt: string;
+  completedAt: string | null;
+  completionEmittedAt: string | null;
+}
+
+const COLUMNS = `source, state, session_id, projects, pending_cursor,
+                 started_at, completed_at, completion_emitted_at`;
+
+/**
+ * One row per tracker source: which phase its ingest is in, who owns it, and
+ * whether its completion event still owes a push.
+ */
+export class RefreshStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  async open(input: {
+    source: string;
+    projects: readonly string[];
+    sessionId: string | null;
+    at: string;
+  }): Promise<void> {
+    assertInstant(input.at, 'at');
+    this.#upsert(
+      input.source,
+      'scanning',
+      input.sessionId,
+      JSON.stringify([...input.projects]),
+      input.at
+    );
+  }
+
+  async openResolving(input: {
+    source: string;
+    sessionId: string | null;
+    at: string;
+  }): Promise<void> {
+    assertInstant(input.at, 'at');
+    this.#upsert(input.source, 'resolving', input.sessionId, '[]', input.at);
+  }
+
+  async setState(source: string, state: RefreshState): Promise<void> {
+    this.#db.run('UPDATE refresh SET state = ? WHERE source = ?', [
+      state,
+      source,
+    ]);
+  }
+
+  async setPendingCursor(source: string, cursor: string): Promise<void> {
+    this.#db.run('UPDATE refresh SET pending_cursor = ? WHERE source = ?', [
+      cursor,
+      source,
+    ]);
+  }
+
+  async close(source: string, at: string): Promise<void> {
+    assertInstant(at, 'at');
+    this.#db.run(
+      `UPDATE refresh
+       SET state = 'idle', completed_at = ?, completion_emitted_at = NULL,
+           pending_cursor = NULL
+       WHERE source = ?`,
+      [at, source]
+    );
+  }
+
+  async markCompletionEmitted(source: string, at: string): Promise<void> {
+    assertInstant(at, 'at');
+    this.#db.run(
+      'UPDATE refresh SET completion_emitted_at = ? WHERE source = ?',
+      [at, source]
+    );
+  }
+
+  async pendingCompletions(): Promise<string[]> {
+    return this.#db
+      .all(
+        `SELECT source FROM refresh
+         WHERE completed_at IS NOT NULL AND completion_emitted_at IS NULL
+         ORDER BY source`
+      )
+      .map((row) => String(row.source));
+  }
+
+  async hasLiveSession(source: string): Promise<boolean> {
+    // A refresh records the Claude session id its command ran under, while a
+    // server registers under a minted registry id and carries the Claude id
+    // in its own column — so the owning session matches on either.
+    return (
+      this.#db.get(
+        `SELECT 1 FROM refresh r
+         JOIN session s
+           ON s.id = r.session_id OR s.claude_session_id = r.session_id
+         WHERE r.source = ?`,
+        [source]
+      ) !== undefined
+    );
+  }
+
+  /**
+   * Sources whose ingest is mid-flight and still owned by a live session. A
+   * scan writes a ticket before it writes that ticket's edges, so the graph
+   * under one is missing dependencies it will have moments later — and a
+   * missing edge reads as "no blockers", the permissive answer. Callers that
+   * would act on the graph wait for this to come back empty.
+   *
+   * A refresh whose session has been swept is excluded: nobody is going to
+   * finish it, so leaving it in would wedge those callers for good.
+   */
+  async ingesting(): Promise<string[]> {
+    return this.#db
+      .all(
+        `SELECT r.source FROM refresh r
+         JOIN session s
+           ON s.id = r.session_id OR s.claude_session_id = r.session_id
+         WHERE r.state <> 'idle'
+         ORDER BY r.source`
+      )
+      .map((row) => String(row.source));
+  }
+
+  async get(source: string): Promise<RefreshRow | null> {
+    const row = this.#db.get(
+      `SELECT ${COLUMNS} FROM refresh WHERE source = ?`,
+      [source]
+    );
+    return row === undefined ? null : toRow(row);
+  }
+
+  async active(): Promise<RefreshRow[]> {
+    return this.#db
+      .all(
+        `SELECT ${COLUMNS} FROM refresh WHERE state <> 'idle' ORDER BY source`
+      )
+      .map(toRow);
+  }
+
+  #upsert(
+    source: string,
+    state: RefreshState,
+    sessionId: string | null,
+    projects: string,
+    at: string
+  ): void {
+    this.#db.run(
+      `INSERT INTO refresh (${COLUMNS})
+       VALUES (?, ?, ?, ?, NULL, ?, NULL, NULL)
+       ON CONFLICT(source) DO UPDATE SET
+         state = excluded.state, session_id = excluded.session_id,
+         projects = excluded.projects, pending_cursor = NULL,
+         started_at = excluded.started_at, completed_at = NULL,
+         completion_emitted_at = NULL`,
+      [source, state, sessionId, projects, at]
+    );
+  }
+}
+
+/* eslint-disable @typescript-eslint/no-base-to-string --
+ * SQLite hands back `unknown`; `String()` converts a primitive rather than
+ * asserting a type the row has not been checked for. */
+function toRow(row: Record<string, unknown>): RefreshRow {
+  return {
+    source: String(row.source),
+    state: row.state as RefreshState,
+    sessionId: row.session_id === null ? null : String(row.session_id),
+    projects: JSON.parse(String(row.projects)) as string[],
+    pendingCursor:
+      row.pending_cursor === null ? null : String(row.pending_cursor),
+    startedAt: String(row.started_at),
+    completedAt: row.completed_at === null ? null : String(row.completed_at),
+    completionEmittedAt:
+      row.completion_emitted_at === null
+        ? null
+        : String(row.completion_emitted_at),
+  };
+}
+/* eslint-enable @typescript-eslint/no-base-to-string */
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/stores/review.mts

@@ -0,0 +1,113 @@
+/* eslint-disable @typescript-eslint/require-await --
+ * Async facade over synchronous `node:sqlite`; see `../db/database.mts`. */
+import type {Database} from '../db/database.mts';
+import {assertInstant} from '../db/time.mts';
+import {DataError, ensure} from '../errors/index.mts';
+import {RESOLVED_STATUSES} from '../model/status.mts';
+import {findNode} from './materialize.mts';
+
+/**
+ * Milestone reviews. Recording snapshots the member set, which is what makes
+ * a review expire: the read-model counts a review only while it covers
+ * exactly the current members and none moved after it was recorded.
+ */
+export class ReviewStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  async record(milestone: string, at: string, session: string): Promise<void> {
+    assertInstant(at, 'at');
+    await this.#db.transaction(() => {
+      const node = findNode(this.#db, milestone);
+      ensure(
+        node !== null && node.kind === 'milestone',
+        () =>
+          new DataError(`"${milestone}" is not a milestone in the graph`, {
+            hint: 'record a review on a milestone the graph already holds.',
+          })
+      );
+      const members = this.#db.all(
+        `SELECT n.external_id AS id, t.status
+         FROM edge e
+         JOIN ticket t ON t.node_id = e.blocker
+         JOIN node n ON n.id = e.blocker
+         WHERE e.blocked = ?
+         ORDER BY id`,
+        [node.id]
+      );
+      ensure(
+        members.length > 0,
+        () =>
+          new DataError(`milestone "${milestone}" has no members to review`, {
+            hint: 'a review covers member tickets; join them with edge add first.',
+          })
+      );
+      const open = members.filter(
+        (member) =>
+          !(RESOLVED_STATUSES as ReadonlySet<string>).has(String(member.status))
+      );
+      ensure(
+        open.length === 0,
+        () =>
+          new DataError(
+            `milestone "${milestone}" still has unresolved members: ${open
+              .map((member) => String(member.id))
+              .join(', ')}`,
+            {
+              hint: 'a milestone is reviewed once every member is verified or canceled.',
+            }
+          )
+      );
+      this.#db.run(
+        `INSERT INTO review (milestone_id, recorded_at) VALUES (?, ?)
+         ON CONFLICT(milestone_id) DO UPDATE SET recorded_at = excluded.recorded_at`,
+        [node.id, at]
+      );
+      this.#db.run('DELETE FROM review_member WHERE milestone_id = ?', [
+        node.id,
+      ]);
+      for (const member of members) {
+        this.#db.run(
+          'INSERT INTO review_member (milestone_id, member_external_id) VALUES (?, ?)',
+          [node.id, String(member.id)]
+        );
+      }
+      // The review opens the gate; the reviewing claim has served its
+      // purpose. Only the reporter's own claim goes: a reviewer whose session
+      // was swept can record late, by which time the milestone may have been
+      // re-dispatched, and revoking that reviewer's grant would strand it.
+      this.#db.run('DELETE FROM claim WHERE node_id = ? AND session_id = ?', [
+        node.id,
+        session,
+      ]);
+    });
+  }
+
+  /**
+   * End a review without recording it — the gate stays closed. Releases only
+   * the caller's own claim, for the same reason `record` does.
+   */
+  async release(milestone: string, session: string): Promise<boolean> {
+    return this.#db.guard(() => {
+      const node = findNode(this.#db, milestone);
+      ensure(
+        node !== null && node.kind === 'milestone',
+        () =>
+          new DataError(`"${milestone}" is not a milestone in the graph`, {
+            hint: 'name the milestone the review order carried.',
+          })
+      );
+      return (
+        this.#db.run('DELETE FROM claim WHERE node_id = ? AND session_id = ?', [
+          node.id,
+          session,
+        ]) > 0
+      );
+    });
+  }
+}
+
+/* eslint-enable @typescript-eslint/require-await */