@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/stores/fetch-request.mts

@@ -0,0 +1,346 @@
+import type {Database} from '../db/database.mts';
+import {DataError, ensure} from '../errors/index.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 FETCH_KINDS = [
+  'scan_project',
+  'fetch_ticket',
+  'refresh_ticket',
+] as const;
+export type FetchKind = (typeof FETCH_KINDS)[number];
+export type FetchResolution = 'materialized' | 'missing';
+
+export interface ScanPayload {
+  projects: string[];
+  cursor: string | null;
+}
+
+export interface TicketPayload {
+  ticket: string;
+}
+
+export interface FetchRequest {
+  id: number;
+  source: string;
+  kind: FetchKind;
+  payload: ScanPayload | TicketPayload;
+  createdAt: string;
+  deliveredAt: string | null;
+  resolution: FetchResolution | null;
+}
+
+const COLUMNS =
+  'id, source, kind, payload, created_at, delivered_at, resolution';
+
+/**
+ * The durable instruction queue. A ticket request is keyed by its serialized
+ * payload, so a row that was already resolved `missing` still suppresses a
+ * re-enqueue — that is what stops one dead reference restarting the loop.
+ */
+export class FetchRequestStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  async enqueueScan(input: {
+    source: string;
+    projects: readonly string[];
+    cursor: string | null;
+    at: string;
+  }): Promise<number> {
+    assertInstant(input.at, 'at');
+    const payload: ScanPayload = {
+      projects: [...input.projects],
+      cursor: input.cursor,
+    };
+    return this.#insert(
+      input.source,
+      'scan_project',
+      JSON.stringify(payload),
+      input.at
+    );
+  }
+
+  /**
+   * Enqueue a ticket request. The existence check and insert execute atomically in a
+   * transaction to prevent two processes racing past the check and both inserting for
+   * the same ticket. The check deliberately matches any existing row, including one
+   * already resolved `missing`, so a ticket the tracker does not have is not
+   * requested again for the rest of the refresh.
+   */
+  async enqueueTicket(input: {
+    source: string;
+    ticket: string;
+    at: string;
+  }): Promise<number | null> {
+    assertInstant(input.at, 'at');
+    const payload = JSON.stringify({
+      ticket: input.ticket,
+    } satisfies TicketPayload);
+    return this.#db.transaction(() => {
+      const existing = this.#db.get(
+        `SELECT id FROM fetch_request
+         WHERE source = ? AND kind = 'fetch_ticket' AND payload = ?`,
+        [input.source, payload]
+      );
+      if (existing !== undefined) return null;
+      return this.#insert(input.source, 'fetch_ticket', payload, input.at);
+    });
+  }
+
+  /**
+   * Enqueue a recurring re-read of a ticket the graph already holds.
+   *
+   * A distinct kind from `fetch_ticket`, because their lifecycles differ in
+   * both directions: reconcile resolves a `fetch_ticket` the moment the node
+   * exists (for a re-read it always does, which would resolve it before any
+   * fetch happened), and `enqueueTicket` dedupes against resolved rows for
+   * the life of a refresh (which would allow exactly one re-read ever).
+   * A `refresh_ticket` is resolved by the ticket write itself — the UPDATE
+   * inside `TicketStore.upsertTicket`'s transaction, so `ticket set` answers
+   * whoever asked — and dedupes only against its own open rows: one
+   * outstanding ask per ticket.
+   */
+  async enqueueTicketRefresh(input: {
+    source: string;
+    ticket: string;
+    at: string;
+  }): Promise<number | null> {
+    assertInstant(input.at, 'at');
+    const payload = JSON.stringify({
+      ticket: input.ticket,
+    } satisfies TicketPayload);
+    return this.#db.transaction(() => {
+      const open = this.#db.get(
+        `SELECT id FROM fetch_request
+         WHERE source = ? AND kind = 'refresh_ticket' AND payload = ?
+           AND resolution IS NULL`,
+        [input.source, payload]
+      );
+      if (open !== undefined) return null;
+      // The history's only job is carrying the newest ask time for the
+      // cadence; without this, every answered ask is a permanent row and a
+      // long-lived ticket accretes one per cadence forever.
+      this.#db.run(
+        `DELETE FROM fetch_request
+         WHERE kind = 'refresh_ticket' AND payload = ? AND resolution IS NOT NULL`,
+        [payload]
+      );
+      return this.#insert(input.source, 'refresh_ticket', payload, input.at);
+    });
+  }
+
+  /**
+   * Re-offer refresh asks that were pushed but never answered. Scan-resume
+   * redelivery deliberately does not own these, so without this a push the
+   * session never heard (channel down, session gone) would leave the ask
+   * open forever — and an open ask suppresses every future one.
+   */
+  async redeliverStaleTicketRefreshes(
+    now: string,
+    olderThanSeconds: number
+  ): Promise<number> {
+    assertInstant(now, 'now');
+    return this.#db.run(
+      `UPDATE fetch_request SET delivered_at = NULL
+       WHERE kind = 'refresh_ticket' AND resolution IS NULL
+         AND delivered_at IS NOT NULL
+         AND unixepoch(?) - unixepoch(delivered_at) >= ?`,
+      [now, olderThanSeconds]
+    );
+  }
+
+  /**
+   * When a ticket was last asked about via `refresh_ticket`, or null if
+   * never. Drives the cadence: due = no open ask and the last one is older
+   * than the interval.
+   */
+  async lastTicketRefreshAt(ticket: string): Promise<string | null> {
+    const row = this.#db.get(
+      `SELECT MAX(created_at) AS at FROM fetch_request
+       WHERE kind = 'refresh_ticket' AND payload = ?`,
+      [JSON.stringify({ticket} satisfies TicketPayload)]
+    );
+    return typeof row?.at === 'string' ? row.at : null;
+  }
+
+  async undelivered(): Promise<FetchRequest[]> {
+    return this.#db
+      .all(
+        `SELECT ${COLUMNS} FROM fetch_request
+         WHERE delivered_at IS NULL AND resolution IS NULL
+         ORDER BY id`
+      )
+      .map(toRequest);
+  }
+
+  /**
+   * Mark a source's scan instruction answered. Nothing else resolves it —
+   * `openCount` ignores it, and the refresh's own state holds the scan open —
+   * so without this it stays outstanding for the life of the refresh and
+   * `redeliver` would put a finished scan back on the wire, whose `refresh
+   * done` the CLI would then refuse for having no scan in progress.
+   */
+  async resolveScan(source: string): Promise<number> {
+    return this.#db.run(
+      `UPDATE fetch_request SET resolution = 'materialized'
+       WHERE source = ? AND kind = 'scan_project' AND resolution IS NULL`,
+      [source]
+    );
+  }
+
+  /**
+   * Offer every unresolved request for a source to the channel again by
+   * clearing its delivery mark. Nothing acknowledges a channel push, so a
+   * delivery mark records that the server wrote the event, not that a session
+   * received it. Re-delivering costs the agent a duplicate instruction it will
+   * satisfy idempotently; not re-delivering leaves it waiting on an event that
+   * is already marked sent, with nothing to time it out.
+   */
+  async redeliver(source: string): Promise<number> {
+    return this.#db.run(
+      `UPDATE fetch_request SET delivered_at = NULL
+       WHERE source = ? AND resolution IS NULL
+         AND kind IN ('scan_project','fetch_ticket')`,
+      [source]
+    );
+  }
+
+  async markDelivered(id: number, at: string): Promise<void> {
+    assertInstant(at, 'at');
+    this.#db.run('UPDATE fetch_request SET delivered_at = ? WHERE id = ?', [
+      at,
+      id,
+    ]);
+  }
+
+  async resolve(id: number, resolution: FetchResolution): Promise<void> {
+    this.#db.run('UPDATE fetch_request SET resolution = ? WHERE id = ?', [
+      resolution,
+      id,
+    ]);
+  }
+
+  async openTickets(): Promise<{id: number; source: string; ticket: string}[]> {
+    return this.#db
+      .all(
+        `SELECT id, source, payload FROM fetch_request
+         WHERE kind = 'fetch_ticket' AND resolution IS NULL
+         ORDER BY id`
+      )
+      .map((row) => ({
+        id: Number(row.id),
+        source: String(row.source),
+        ticket: (JSON.parse(String(row.payload)) as TicketPayload).ticket,
+      }));
+  }
+
+  async openTicketRequest(
+    ticket: string
+  ): Promise<{id: number; source: string} | null> {
+    const row = this.#db.get(
+      `SELECT id, source FROM fetch_request
+       WHERE kind IN ('fetch_ticket','refresh_ticket')
+         AND resolution IS NULL AND payload = ?`,
+      [JSON.stringify({ticket} satisfies TicketPayload)]
+    );
+    return row === undefined
+      ? null
+      : {id: Number(row.id), source: String(row.source)};
+  }
+
+  async bySource(source: string): Promise<FetchRequest[]> {
+    return this.#db
+      .all(
+        `SELECT ${COLUMNS} FROM fetch_request WHERE source = ? ORDER BY id`,
+        [source]
+      )
+      .map(toRequest);
+  }
+
+  /**
+   * Outstanding ticket requests. Deliberately not counting the `scan_project`
+   * row: it resolves only when the scan completes (`resolveScan`), and a
+   * refresh in `scanning` is already held open by its state, so counting it
+   * here would just delay the close.
+   */
+  async openCount(source: string): Promise<number> {
+    const row = this.#db.get(
+      `SELECT COUNT(*) AS n FROM fetch_request
+       WHERE source = ? AND kind = 'fetch_ticket' AND resolution IS NULL`,
+      [source]
+    );
+    return row === undefined ? 0 : Number(row.n);
+  }
+
+  async clear(source: string): Promise<number> {
+    return this.#db.run('DELETE FROM fetch_request WHERE source = ?', [source]);
+  }
+
+  /**
+   * Forget a closing refresh's own requests, except the `missing` tombstones.
+   * Those are what stop a ticket the tracker does not have from being
+   * requested again, so a refresh that closes must leave them behind; only an
+   * explicit new scan forgets them.
+   *
+   * Scoped to the kinds a refresh owns, the same pair `redeliver` scopes to.
+   * A `refresh_ticket` row belongs to the cadence, not to any one refresh: it
+   * carries the only record of when its ticket was last asked about, and
+   * deleting it reads as "never asked", which re-asks on the next tick and
+   * every tick after. That history prunes itself — `enqueueTicketRefresh`
+   * drops the resolved row it replaces — so nothing here needs to.
+   */
+  async clearExceptMissing(source: string): Promise<number> {
+    return this.#db.run(
+      `DELETE FROM fetch_request
+       WHERE source = ? AND (resolution IS NULL OR resolution <> 'missing')
+         AND kind IN ('scan_project','fetch_ticket')`,
+      [source]
+    );
+  }
+
+  #insert(
+    source: string,
+    kind: FetchKind,
+    payload: string,
+    at: string
+  ): number {
+    this.#db.run(
+      `INSERT INTO fetch_request (source, kind, payload, created_at)
+       VALUES (?, ?, ?, ?)`,
+      [source, kind, payload, at]
+    );
+    // The id must be read back per-connection: several dispatch processes write this
+    // table concurrently, and a table-wide "highest id" would return another process's row.
+    const row = this.#db.get('SELECT last_insert_rowid() AS id');
+    ensure(
+      row !== undefined,
+      () => new DataError('a fetch request just inserted must exist')
+    );
+    return Number(row.id);
+  }
+}
+
+/* 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 toRequest(row: Record<string, unknown>): FetchRequest {
+  return {
+    id: Number(row.id),
+    source: String(row.source),
+    kind: row.kind as FetchKind,
+    payload: JSON.parse(String(row.payload)) as ScanPayload | TicketPayload,
+    createdAt: String(row.created_at),
+    deliveredAt: row.delivered_at === null ? null : String(row.delivered_at),
+    resolution:
+      row.resolution === null ? null : (row.resolution as FetchResolution),
+  };
+}
+/* eslint-enable @typescript-eslint/no-base-to-string */
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/stores/index.mts

@@ -0,0 +1,19 @@
+export * from './materialize.mts';
+export * from './project.mts';
+export * from './milestone.mts';
+export * from './ticket.mts';
+export * from './pr.mts';
+export * from './edge.mts';
+export * from './session.mts';
+export * from './coordination.mts';
+export * from './cursor.mts';
+export * from './refresh.mts';
+export * from './fetch-request.mts';
+export * from './notice.mts';
+export * from './policy.mts';
+export * from './review.mts';
+export {PrEventStore} from './pr-event.mts';
+export type {PendingEvent} from './pr-event.mts';
+export {WatchStore} from './watch.mts';
+export type {DueWatch} from './watch.mts';
+export {WorkerStore} from './worker.mts';

package/src/lib/stores/materialize.mts

@@ -0,0 +1,69 @@
+import type {Database} from '../db/database.mts';
+import {DataError, ensure} from '../errors/index.mts';
+import type {ConcreteKind, Kind} from '../model/status.mts';
+
+export interface NodeRow {
+  id: number;
+  kind: Kind;
+}
+
+export function findNode(db: Database, externalId: string): NodeRow | null {
+  const row = db.get('SELECT id, kind FROM node WHERE external_id = ?', [
+    externalId,
+  ]);
+  if (row === undefined) return null;
+  return {id: Number(row.id), kind: row.kind as Kind};
+}
+
+/** The node for an id, creating an `unknown` placeholder when nobody wrote it. */
+export function nodeRef(db: Database, externalId: string): number {
+  const existing = findNode(db, externalId);
+  if (existing !== null) return existing.id;
+  db.run("INSERT INTO node (external_id, kind) VALUES (?, 'unknown')", [
+    externalId,
+  ]);
+  const created = findNode(db, externalId);
+  ensure(
+    created !== null,
+    () => new DataError('a node just inserted must exist')
+  );
+  return created.id;
+}
+
+/**
+ * The node for a satellite being written: created with its kind, or promoted
+ * from a placeholder. Any kind may block any other, so promotion has no edge
+ * legality to check — only that the id is not already the *other* concrete kind.
+ */
+export function materialize(
+  db: Database,
+  externalId: string,
+  kind: ConcreteKind
+): number {
+  const existing = findNode(db, externalId);
+  if (existing === null) {
+    db.run('INSERT INTO node (external_id, kind) VALUES (?, ?)', [
+      externalId,
+      kind,
+    ]);
+    const created = findNode(db, externalId);
+    ensure(
+      created !== null,
+      () => new DataError('a node just inserted must exist')
+    );
+    return created.id;
+  }
+  if (existing.kind === kind) return existing.id;
+  ensure(
+    existing.kind === 'unknown',
+    () =>
+      new DataError(
+        `id "${externalId}" is already a ${existing.kind}; it cannot also be a ${kind}`,
+        {
+          hint: `entities share one id space — give the ${kind} a different id, or remove the ${existing.kind} first.`,
+        }
+      )
+  );
+  db.run('UPDATE node SET kind = ? WHERE id = ?', [kind, existing.id]);
+  return existing.id;
+}

package/src/lib/stores/milestone.mts

@@ -0,0 +1,74 @@
+import type {Database} from '../db/database.mts';
+import {ensure, UsageError} from '../errors/index.mts';
+import type {Milestone} 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`. */
+
+/**
+ * Milestones. Membership is not stored here — a ticket belongs to a milestone by
+ * blocking it (a `ticket → milestone` edge), so removing a milestone node lets
+ * the edge FK cascade its membership away.
+ */
+export class MilestoneStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  async upsertMilestone(milestone: Milestone): Promise<void> {
+    await this.#db.transaction(() => {
+      // Same rule as tickets: the project must already be recorded. A name
+      // passed where the id belongs would otherwise materialize an
+      // unknown-kind placeholder and silently parent the milestone onto a
+      // node no project join can see.
+      const project = findNode(this.#db, milestone.project);
+      ensure(
+        project !== null && project.kind === 'project',
+        () =>
+          new UsageError(`"${milestone.project}" is not a recorded project`, {
+            hint: 'record it first with `dispatch project set`, and pass the project id — a project name is not its id.',
+          })
+      );
+      const projectId = project.id;
+      const nodeId = materialize(this.#db, milestone.id, 'milestone');
+      this.#db.run(
+        `INSERT INTO milestone (node_id, project_id, name) VALUES (?, ?, ?)
+         ON CONFLICT(node_id) DO UPDATE SET
+           project_id = excluded.project_id, name = excluded.name`,
+        [nodeId, projectId, milestone.name]
+      );
+    });
+  }
+
+  /** Remove a milestone; its edges, claim, and review cascade via node FKs. */
+  async removeMilestone(id: string): Promise<boolean> {
+    return this.#db.transaction(() => {
+      const node = findNode(this.#db, id);
+      if (node?.kind !== 'milestone') return false;
+      this.#db.run('DELETE FROM node WHERE id = ?', [node.id]);
+      return true;
+    });
+  }
+
+  async getMilestone(id: string): Promise<Milestone | null> {
+    const row = this.#db.get(
+      `SELECT n.external_id AS id, pn.external_id AS project, m.name AS name
+       FROM milestone m
+       JOIN node n ON n.id = m.node_id
+       JOIN node pn ON pn.id = m.project_id
+       WHERE n.external_id = ?`,
+      [id]
+    );
+    if (row === undefined) return null;
+    return {
+      id: String(row.id),
+      project: String(row.project),
+      name: String(row.name),
+    };
+  }
+}
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/stores/notice.mts

@@ -0,0 +1,57 @@
+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 NOTICE_KINDS = [
+  'park_human_blocked',
+  'alert_failure',
+  'project_complete',
+] as const;
+export type NoticeKind = (typeof NOTICE_KINDS)[number];
+
+/**
+ * Once-per-episode markers for the condition orders. A condition (a ticket
+ * needs parking, a failure needs surfacing, a project completed) fires one
+ * order while it holds; `prune` clears markers whose condition lapsed so a new
+ * episode fires again.
+ */
+export class NoticeStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  async has(kind: NoticeKind, node: string): Promise<boolean> {
+    return (
+      this.#db.get('SELECT 1 AS x FROM notice WHERE kind = ? AND node = ?', [
+        kind,
+        node,
+      ]) !== undefined
+    );
+  }
+
+  async record(kind: NoticeKind, node: string, at: string): Promise<void> {
+    assertInstant(at, 'at');
+    this.#db.run(
+      `INSERT INTO notice (kind, node, emitted_at) VALUES (?, ?, ?)
+       ON CONFLICT(kind, node) DO NOTHING`,
+      [kind, node, at]
+    );
+  }
+
+  /** Drop every marker of `kind` whose node is not in `holding`. */
+  async prune(kind: NoticeKind, holding: readonly string[]): Promise<number> {
+    const placeholders = holding.map(() => '?').join(', ');
+    return this.#db.run(
+      holding.length === 0
+        ? 'DELETE FROM notice WHERE kind = ?'
+        : `DELETE FROM notice WHERE kind = ? AND node NOT IN (${placeholders})`,
+      [kind, ...holding]
+    );
+  }
+}
+
+/* eslint-enable @typescript-eslint/require-await */

package/src/lib/stores/policy.mts

@@ -0,0 +1,48 @@
+import type {Database} from '../db/database.mts';
+import {DEFAULT_REPO_CAPS} from '../model/index.mts';
+import type {RepoCapPolicy} from '../model/index.mts';
+
+/* eslint-disable @typescript-eslint/require-await --
+ * Async facade over synchronous `node:sqlite`; see `../db/database.mts`. */
+
+const REPO_CAPS_KEY = 'repo_caps';
+
+/**
+ * The admission policy the running server was started with, kept in the
+ * database so a reader that is not that server — `dispatch status`, mainly —
+ * reports against the caps actually in force instead of guessing the
+ * defaults. The server writes it at startup; the last one to start wins,
+ * which matches the caps' meaning: they bound one host's shared resources,
+ * not one session's share of them.
+ */
+export class PolicyStore {
+  readonly #db: Database;
+
+  constructor(db: Database) {
+    this.#db = db;
+  }
+
+  /** The stored policy, or the defaults when none was ever written. */
+  async getRepoCaps(): Promise<RepoCapPolicy> {
+    const row = this.#db.get('SELECT value FROM meta WHERE key = ?', [
+      REPO_CAPS_KEY,
+    ]);
+    if (typeof row?.value !== 'string') return DEFAULT_REPO_CAPS;
+    const stored = JSON.parse(row.value) as Partial<RepoCapPolicy>;
+    return {
+      openPrs: stored.openPrs ?? DEFAULT_REPO_CAPS.openPrs,
+      inFlightBuilds: stored.inFlightBuilds ?? DEFAULT_REPO_CAPS.inFlightBuilds,
+      openPrsByRepo: stored.openPrsByRepo ?? {},
+      inFlightBuildsByRepo: stored.inFlightBuildsByRepo ?? {},
+    };
+  }
+
+  async setRepoCaps(policy: RepoCapPolicy): Promise<void> {
+    this.#db.run('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)', [
+      REPO_CAPS_KEY,
+      JSON.stringify(policy),
+    ]);
+  }
+}
+
+/* eslint-enable @typescript-eslint/require-await */