@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/schedule/scheduler.mts

@@ -0,0 +1,355 @@
+import type {Database} from '../db/database.mts';
+import {
+  DEFAULT_STALE_AFTER_SECONDS,
+  dispatchQueue,
+  milestoneStates,
+} from '../graph/index.mts';
+import {classifiedItems} from '../graph/index.mts';
+import {derive, repoPrLoad} from '../graph/index.mts';
+import {
+  CoordinationStore,
+  FetchRequestStore,
+  NoticeStore,
+  PolicyStore,
+  RefreshStore,
+  SessionStore,
+} from '../stores/index.mts';
+import type {NoticeKind} from '../stores/notice.mts';
+import {RepoAdmission} from './caps.mts';
+
+/** How many agents may be in flight at once when nothing configures it. */
+export const DEFAULT_MAX_PARALLEL = 3;
+
+export interface WorkOrder {
+  kind:
+    | 'dispatch_ticket'
+    | 'dispatch_pr'
+    | 'perform_milestone_review'
+    | 'park_human_blocked'
+    | 'alert_failure'
+    | 'project_complete';
+  meta: Record<string, string>;
+  body: string;
+}
+
+export interface TickResult {
+  orders: WorkOrder[];
+  /** The session's own row is gone; the server must exit, not re-register. */
+  retired: boolean;
+  /** Sources mid-ingest that held this tick's scheduling; empty when none did. */
+  ingesting: string[];
+}
+
+/**
+ * The deterministic half of orchestration: everything the server decides on a
+ * tick. Reads the derived read-model, claims before it emits, and returns the
+ * work orders to push — it never touches the channel itself, so it tests
+ * without one.
+ */
+export class Scheduler {
+  readonly #db: Database;
+  readonly #session: string;
+  readonly #maxParallel: number;
+
+  constructor(
+    db: Database,
+    opts: {session: string; maxParallel?: number | undefined}
+  ) {
+    this.#db = db;
+    this.#session = opts.session;
+    this.#maxParallel = opts.maxParallel ?? DEFAULT_MAX_PARALLEL;
+  }
+
+  async tick(now: string): Promise<TickResult> {
+    const sessions = new SessionStore(this.#db);
+    if (!(await sessions.heartbeat(this.#session, now))) {
+      return {orders: [], retired: true, ingesting: []};
+    }
+    await sessions.sweepStale(now, DEFAULT_STALE_AFTER_SECONDS);
+
+    await this.#refreshTickets(now);
+
+    const own = await sessions.getSession(this.#session);
+    const orders: WorkOrder[] = [];
+
+    // Nothing at all while a tracker scan is writing the graph. A scan fills
+    // the graph ticket by ticket and learns each ticket's dependencies in a
+    // second round trip, so under one a real blocker can simply be absent —
+    // and an item with no blocker edges is indistinguishable from an item
+    // with none, which admits work whose blocker is still open. Reviews and
+    // the completion notice read the same half-built graph, so the whole
+    // emission waits rather than just the queue. The scan itself is delivered
+    // off `fetch_request` rows, not from here, so holding this cannot stall
+    // the thing it is waiting for.
+    const ingesting = await new RefreshStore(this.#db).ingesting();
+
+    // No work order before the acknowledgement: a work order claims a node,
+    // which a session that never hears the channel would never release.
+    if (own?.ackedAt != null && ingesting.length === 0) {
+      // One admission budget per tick: the cap minus everything in flight. A
+      // claim is both the obligation to run an agent and that agent's compute
+      // grant, so it consumes capacity from the moment it exists. Reviews
+      // spend first: a review is the continuation of already-landed work and
+      // opens a gate other work waits behind.
+      const coordination = new CoordinationStore(this.#db);
+      const inFlight = await coordination.inFlightCount({
+        now,
+        staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+      });
+      const budget = Math.max(0, this.#maxParallel - inFlight);
+      const reviews = await this.#reviews(now, budget);
+      orders.push(...reviews);
+      // The per-repo caps bound resources the claim ledger cannot see: a PR
+      // holds preview stacks and cloud quota for as long as it stays open,
+      // and a yielded worker holds no claim at all. Like the budget, they are
+      // read before any claim is taken, so two servers scheduling at the same
+      // instant can each spend the same free slot; the claims each one writes
+      // are what the other's next tick counts.
+      const admission = new RepoAdmission(
+        await new PolicyStore(this.#db).getRepoCaps(),
+        await repoPrLoad(this.#db, {
+          now,
+          staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+        })
+      );
+      orders.push(
+        ...(await this.#fill(now, budget - reviews.length, admission))
+      );
+      orders.push(...(await this.#conditions(now)));
+    }
+    return {orders, retired: false, ingesting};
+  }
+
+  /**
+   * Ask the session to re-read tickets whose tracker state can change under
+   * us, on a cadence derived from where each ticket is. The server cannot
+   * read the tracker itself, so it owns the *when*: the ask is a durable
+   * `refresh_ticket` instruction the drain delivers once the channel is
+   * acked, `ticket set` is the answer, and a status change the write reveals
+   * is pushed as an event. Backlog and terminal tickets are not asked about —
+   * the scan covers them — and one ask per ticket stays open at a time.
+   *
+   * In-flight tickets move on a person's timescale (a reply, a review), so
+   * five minutes; parked ones on an operator's (fifteen).
+   */
+  async #refreshTickets(now: string): Promise<void> {
+    const requests = new FetchRequestStore(this.#db);
+    // An ask pushed ten minutes ago and never answered was lost in flight;
+    // clearing its mark lets the drain offer it again.
+    await requests.redeliverStaleTicketRefreshes(now, 600);
+    const rows = this.#db.all(
+      `SELECT n.external_id AS id, t.status, p.source
+       FROM ticket t
+       JOIN node n ON n.id = t.node_id
+       JOIN project p ON p.node_id = t.project_id
+       WHERE p.source IS NOT NULL
+         AND t.status IN ('in-progress','in-review','finished','delivered',
+                          'paused','awaiting-external')`
+    );
+    const nowMs = Date.parse(now);
+    for (const row of rows) {
+      const status = String(row.status);
+      const cadenceMs =
+        status === 'paused' || status === 'awaiting-external'
+          ? 900_000
+          : 300_000;
+      const ticket = String(row.id);
+      const last = await requests.lastTicketRefreshAt(ticket);
+      if (last !== null && nowMs - Date.parse(last) < cadenceMs) continue;
+      await requests.enqueueTicketRefresh({
+        source: String(row.source),
+        ticket,
+        at: now,
+      });
+    }
+  }
+
+  /**
+   * Claim-then-emit for the dispatch queue, up to the remaining budget. The
+   * budget bounds this tick's work; the cap passed to `claim` is what actually
+   * binds, because a second server scheduling concurrently computed its budget
+   * from the same pre-claim reading. A `full` outcome ends the pass — the
+   * later entries cannot fit either.
+   *
+   * A per-repo cap ends nothing: it refuses one entry, and a later entry for
+   * another repo may still fit. Only PR items are gated; a ticket-worker keeps
+   * planning and registering PR items, which then wait in the queue for a slot
+   * — that is the queue doing its job.
+   */
+  async #fill(
+    now: string,
+    budget: number,
+    admission: RepoAdmission
+  ): Promise<WorkOrder[]> {
+    const coordination = new CoordinationStore(this.#db);
+    const orders: WorkOrder[] = [];
+
+    for (const {entry, pass} of await dispatchQueue(this.#db, {now})) {
+      if (orders.length >= budget) break;
+      if (entry.item.kind === 'pr' && admission.admit(entry.item) !== null)
+        continue;
+      const claim = await coordination.claim({
+        node: entry.item.id,
+        session: this.#session,
+        claimedAt: now,
+        capacity: {
+          max: this.#maxParallel,
+          staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+        },
+      });
+      if (claim.outcome === 'full') break;
+      if (claim.outcome !== 'claimed' && claim.outcome !== 'refreshed')
+        continue;
+      const passNote = pass === null ? '' : ` (pass: ${pass})`;
+      if (entry.item.kind === 'pr') {
+        admission.reserve(entry.item);
+        orders.push({
+          kind: 'dispatch_pr',
+          meta: {
+            pr: entry.item.id,
+            pass: pass ?? 'available',
+            ...(entry.item.ticket === null ? {} : {ticket: entry.item.ticket}),
+          },
+          body: `Launch a pr-worker agent for PR item ${entry.item.id}${entry.item.ticket === null ? '' : ` (implements ticket ${entry.item.ticket})`}${passNote}. It is claimed for this session; the agent records the outcome when done.`,
+        });
+      } else {
+        orders.push({
+          kind: 'dispatch_ticket',
+          meta: {
+            project: entry.item.project ?? '',
+            ticket: entry.item.id,
+            pass: pass ?? 'available',
+          },
+          body: `Launch a ticket-worker agent for ticket ${entry.item.id}${passNote}. It is claimed for this session; the agent records the outcome when done.`,
+        });
+      }
+    }
+    return orders;
+  }
+
+  /**
+   * One review order per open gate, tracked by a milestone-keyed claim and
+   * bounded by the shared budget — a review order launches an agent too.
+   */
+  async #reviews(now: string, budget: number): Promise<WorkOrder[]> {
+    const coordination = new CoordinationStore(this.#db);
+    const orders: WorkOrder[] = [];
+    for (const milestone of await milestoneStates(this.#db, {now})) {
+      if (orders.length >= budget) break;
+      if (!milestone.readyForReview || milestone.reviewRecorded) continue;
+      if (milestone.claim?.live === true) continue;
+      const claim = await coordination.claim({
+        node: milestone.id,
+        session: this.#session,
+        claimedAt: now,
+        capacity: {
+          max: this.#maxParallel,
+          staleAfterSeconds: DEFAULT_STALE_AFTER_SECONDS,
+        },
+      });
+      if (claim.outcome === 'full') break;
+      if (claim.outcome !== 'claimed' && claim.outcome !== 'refreshed')
+        continue;
+      orders.push({
+        kind: 'perform_milestone_review',
+        meta: {project: milestone.project, milestone: milestone.id},
+        body: `Launch a milestone-reviewer agent for milestone ${milestone.id} in project ${milestone.project}. Recording the review opens the gate.`,
+      });
+    }
+    return orders;
+  }
+
+  /**
+   * The tick's non-scheduling duties, fired once per episode: park
+   * human-blocked work, surface unrecoverable failures, announce completion.
+   */
+  async #conditions(now: string): Promise<WorkOrder[]> {
+    const notices = new NoticeStore(this.#db);
+    const orders: WorkOrder[] = [];
+    const items = await classifiedItems(this.#db, {now});
+
+    const emit = async (
+      kind: NoticeKind,
+      holding: {node: string; meta: Record<string, string>; body: string}[]
+    ): Promise<void> => {
+      for (const {node, meta, body} of holding) {
+        if (await notices.has(kind, node)) continue;
+        await notices.record(kind, node, now);
+        orders.push({kind, meta, body});
+      }
+      await notices.prune(
+        kind,
+        holding.map((entry) => entry.node)
+      );
+    };
+
+    await emit(
+      'park_human_blocked',
+      items
+        .filter(
+          (entry) =>
+            entry.item.kind === 'ticket' &&
+            entry.classification === 'human-blocked' &&
+            entry.item.status !== 'paused' &&
+            entry.item.status !== 'awaiting-external'
+        )
+        .map((entry) => ({
+          node: entry.item.id,
+          meta: {
+            project: entry.item.project ?? '',
+            ticket: entry.item.id,
+          },
+          body: `Ticket ${entry.item.id} needs a human. Park it (awaiting-external, or paused if the tracker lacks it) and post the handoff through the tracker adapter.`,
+        }))
+    );
+
+    // A human-blocked PR item shares the alert channel with failures: the
+    // item has no status to park, so the alert is the only way the operator
+    // hears the question its worker left behind. The episode marker keys on
+    // the outcome kind too, so replacing a failed outcome with a fresh
+    // human-blocked question (or vice versa) starts a new episode.
+    await emit(
+      'alert_failure',
+      items
+        .filter(
+          (entry) =>
+            (entry.outcome?.outcome === 'failed' &&
+              entry.outcome.retryable !== true) ||
+            (entry.item.kind === 'pr' &&
+              entry.outcome?.outcome === 'human-blocked')
+        )
+        .map((entry) => ({
+          node: `${entry.item.id}#${entry.outcome?.outcome ?? ''}`,
+          meta:
+            entry.item.kind === 'pr'
+              ? {
+                  pr: entry.item.id,
+                  ...(entry.item.ticket === null
+                    ? {}
+                    : {ticket: entry.item.ticket}),
+                }
+              : {project: entry.item.project ?? '', ticket: entry.item.id},
+          body:
+            entry.outcome?.outcome === 'human-blocked'
+              ? `PR item ${entry.item.id} is waiting on an operator response${entry.outcome.detail == null ? '' : ` (${entry.outcome.detail})`}. Alert the operator on the PR if one exists, else on its ticket. An answer on the PR — a comment, a review, a push — requeues it on its own; if the answer arrives anywhere else, requeue it with \`dispatch outcome rm --id ${entry.item.id}\`.`
+              : entry.item.kind === 'pr'
+                ? `PR item ${entry.item.id} failed unrecoverably${entry.outcome?.detail == null ? '' : ` (${entry.outcome.detail})`}. Alert the operator; requeue by removing the outcome once addressed.`
+                : `Ticket ${entry.item.id} failed unrecoverably${entry.outcome?.detail == null ? '' : ` (${entry.outcome.detail})`}. Alert the operator on the ticket; requeue by removing the outcome once addressed.`,
+        }))
+    );
+
+    const graph = await derive(this.#db, {now});
+    await emit(
+      'project_complete',
+      graph.projects
+        .filter((project) => project.terminal)
+        .map((project) => ({
+          node: project.id,
+          meta: {project: project.id},
+          body: `Project ${project.id} is complete: every ticket is verified or canceled. Announce it and stop when no other project remains.`,
+        }))
+    );
+
+    return orders;
+  }
+}

package/src/lib/schedule/tick.mts

@@ -0,0 +1,266 @@
+import {nowIso} from '../db/time.mts';
+import {withDatabase} from '../db/index.mts';
+import type {Logger} from '../logger/index.mts';
+import type {ChannelWriter} from '../mcp/channel.mts';
+import {
+  CoordinationStore,
+  PrEventStore,
+  PrStore,
+  SessionStore,
+  WatchStore,
+  WorkerStore,
+} from '../stores/index.mts';
+import {
+  adoptOrphans,
+  githubSnapshot,
+  pollWatches,
+  renderSnapshot,
+} from '../watch/index.mts';
+import type {Snapshotter} from '../watch/index.mts';
+import {Scheduler} from './scheduler.mts';
+import type {WorkOrder} from './scheduler.mts';
+
+/** First probe retry delay; doubles per unanswered probe up to the cap. */
+const PROBE_DELAY_MS = 5_000;
+const PROBE_DELAY_CAP_MS = 60_000;
+
+export interface TickState {
+  readonly registryId: string;
+  readonly maxParallel?: number | undefined;
+  /** Last adoption sweep; a slow cadence, since orphans are rare. */
+  adoptDueAtMs: number;
+  probeDelayMs: number;
+  probeDueAtMs: number;
+  /** The session's row was retired; scheduling stops for good. */
+  retired: boolean;
+}
+
+export function createTickState(
+  registryId: string,
+  maxParallel?: number
+): TickState {
+  return {
+    registryId,
+    maxParallel,
+    adoptDueAtMs: 0,
+    probeDelayMs: PROBE_DELAY_MS,
+    probeDueAtMs: 0,
+    retired: false,
+  };
+}
+
+/**
+ * One server tick: heartbeat and schedule, poll the PR watches, push what
+ * they observed, push the resulting work orders, and keep the acknowledgement
+ * handshake alive — an unanswered probe re-pushes on a capped backoff rather
+ * than latching a verdict. Runs on the timer and after every tool call.
+ *
+ * Observations are pushed only once the channel is acked, for the same reason
+ * work orders are: an event pushed into a channel the runner silently refused
+ * would be marked delivered while nobody heard it. Unlike a work order there
+ * is no later re-derivation — the next snapshot compares against a state that
+ * already contains the change — so until the ack lands the rows wait.
+ */
+export async function runServerTick(
+  channel: ChannelWriter,
+  env: NodeJS.ProcessEnv,
+  state: TickState,
+  opts: {nowMs?: number; log?: Logger; snapshot?: Snapshotter} = {}
+): Promise<void> {
+  if (state.retired) return;
+  const now = nowIso();
+  const nowMs = opts.nowMs ?? Date.now();
+
+  let orders: WorkOrder[] = [];
+  let acked = false;
+
+  const schedule = async (): Promise<void> => {
+    await withDatabase(undefined, env, async (db) => {
+      const scheduler = new Scheduler(db, {
+        session: state.registryId,
+        maxParallel: state.maxParallel,
+      });
+      const result = await scheduler.tick(now);
+      if (result.retired) {
+        state.retired = true;
+        return;
+      }
+      if (result.ingesting.length > 0) {
+        opts.log?.debug('scheduling held while the graph is being built', {
+          sources: result.ingesting.join(','),
+        });
+      }
+      orders = [...orders, ...result.orders];
+
+      const own = await new SessionStore(db).getSession(state.registryId);
+      if (own !== null && own.ackedAt === null && nowMs >= state.probeDueAtMs) {
+        channel.push(
+          'probe',
+          {server: state.registryId},
+          `Run \`dispatch mcp ack --server ${state.registryId}\` (the \`mcp_ack\` tool) to acknowledge this channel; work orders wait on it.`
+        );
+        state.probeDueAtMs = nowMs + state.probeDelayMs;
+        state.probeDelayMs = Math.min(
+          state.probeDelayMs * 2,
+          PROBE_DELAY_CAP_MS
+        );
+      }
+      acked = own !== null && own.ackedAt !== null;
+    });
+  };
+
+  // Heartbeat before the watch poll: snapshotting shells out to gh, and a
+  // slow pass must not let this session read as stale mid-tick.
+  await schedule();
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the schedule() closure sets `state.retired`; the analyzer cannot see the write
+  if (state.retired) return;
+
+  try {
+    const {fired} = await pollWatches(env, {
+      snapshot: opts.snapshot ?? githubSnapshot,
+      log: opts.log,
+    });
+    // A fired watch re-queued its item unless a live worker still holds it,
+    // in which case the push below relays instead; a second pass dispatches
+    // the queued ones in this tick rather than the next. Claims make the
+    // extra pass idempotent.
+    if (fired.length > 0) await schedule();
+  } catch (error) {
+    opts.log?.error('watch pass failed', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the schedule() closure sets `state.retired`; the analyzer cannot see the write
+  if (state.retired) return;
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the schedule() closure assigns `acked`; the analyzer cannot see the write
+  if (acked) {
+    if (nowMs >= state.adoptDueAtMs) {
+      state.adoptDueAtMs = nowMs + 900_000;
+      try {
+        const adopted = await adoptOrphans(env, {log: opts.log});
+        if (adopted > 0) opts.log?.info('adopted orphaned PRs', {adopted});
+      } catch (error) {
+        opts.log?.error('adoption sweep failed', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    try {
+      await pushObservations(channel, env, state.registryId, now, opts.log);
+    } catch (error) {
+      // A push failure must not cost this tick's already-claimed orders; the
+      // rows stay undelivered and the next tick retries.
+      opts.log?.error('observation push failed', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  for (const order of orders) {
+    channel.push(order.kind, order.meta, order.body);
+  }
+}
+
+/**
+ * Hand the session every observation the poll owes it. Each names the PR item
+ * it belongs to, which is what lets the session route it to the worker
+ * holding that PR rather than acting on it itself.
+ */
+export async function pushObservations(
+  channel: ChannelWriter,
+  env: NodeJS.ProcessEnv,
+  session: string,
+  at: string,
+  log?: Logger
+): Promise<void> {
+  await withDatabase(undefined, env, async (db) => {
+    const events = new PrEventStore(db);
+    const prs = new PrStore(db);
+    const watches = new WatchStore(db);
+    const workers = new WorkerStore(db);
+    const coordination = new CoordinationStore(db);
+    // An address only relays while its claim actually goes to this session;
+    // otherwise the event falls through to cold re-dispatch, which claims.
+    const relayTarget = async (
+      ref: string | null,
+      node: string
+    ): Promise<string | null> => {
+      if (ref === null) return null;
+      const claimed = await coordination.claim({
+        node,
+        session,
+        claimedAt: at,
+      });
+      return claimed.outcome === 'claimed' || claimed.outcome === 'refreshed'
+        ? ref
+        : null;
+    };
+
+    for (const event of await events.undelivered(session)) {
+      try {
+        // Every fallible step — the snapshot's JSON parse, the render, the
+        // lookups — runs before the event is claimed. A malformed snapshot
+        // then leaves the row undelivered to retry next tick instead of being
+        // marked delivered and lost, and the per-event catch keeps one bad
+        // event from aborting the whole drain.
+        const pr = await prs.getPr(event.node);
+        // When a live worker holds this node, its address rides the event and
+        // the session relays instead of letting the item cold-start.
+        //
+        // Re-take the claim as part of relaying. The worker gave its own back
+        // at `pr yield` so the watch could arm, and its terminal act — the
+        // outcome — requires one; a relayed event is the instruction to
+        // perform that act, so the address and the authority to use it have to
+        // travel together. Without this a terminal event always lands one
+        // dispatch short of being recorded, and the item wedges: the worker
+        // row suppresses re-dispatch, and the relay is already spent.
+        //
+        // Unbounded deliberately. The agent is running already, so this is
+        // work that was admitted once, not a second admission — and capacity
+        // is exactly what the yield handed back.
+        const agent = await relayTarget(
+          await workers.refFor(event.node, session),
+          event.node
+        );
+        // A ticket event has no PR payload; the session re-reads the ticket
+        // through the tracker adapter. A PR event renders from the snapshot
+        // the poll already stored — no subprocess, so no per-tick push cap.
+        const snapshot =
+          event.kind === 'ticket_changed' ||
+          pr?.repo == null ||
+          pr.prNumber == null
+            ? null
+            : await watches.latestSnapshot(event.node);
+        const body =
+          snapshot !== null && pr?.repo != null && pr.prNumber != null
+            ? renderSnapshot(pr.repo, pr.prNumber, snapshot)
+            : event.kind === 'ticket_changed'
+              ? `${event.summary} Re-read the ticket through the tracker adapter before acting.`
+              : `${event.summary} No snapshot was stored; run \`pr-status --repo ${pr?.repo ?? '<repo>'} ${String(pr?.prNumber ?? 0)}\` yourself before acting.`;
+        const meta = {
+          // `agent` is the router's reserved key: stamped after the spread so
+          // no event producer can smuggle an address in.
+          ...event.meta,
+          ...(agent === null ? {} : {agent}),
+          item: event.node,
+          ...(pr?.repo == null ? {} : {repo: pr.repo}),
+          ...(pr?.prNumber == null ? {} : {pr: String(pr.prNumber)}),
+        };
+
+        // The claim is the last DB write before the push, and conditional:
+        // with session-NULL events drainable by any server, only the one that
+        // wins the claim pushes. It has to precede the push, so the single
+        // residual is a push that throws after the claim — a failed stdout
+        // write, i.e. a dying server, which a retry could not have helped.
+        if (!(await events.markDelivered(event.id, at))) continue;
+        channel.push(event.kind, meta, body);
+      } catch (error) {
+        log?.error('event delivery failed', {
+          node: event.node,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  });
+}

package/src/lib/stores/CLAUDE.md

@@ -0,0 +1,24 @@
+# stores
+
+One store per concept over the shared `Database`. A store is organized around a
+concept, not a single table: an operation may write several tables atomically.
+
+- `materialize.mts` — shared node create/promote (placeholder → concrete kind),
+  with the id-kind conflict check. Used by every write store.
+- `project` / `milestone` / `ticket` / `pr` — per-kind upsert/remove/read.
+- `edge` — the blocking DAG: add/remove/setEdges with cycle rejection.
+- `session` — session lifecycle; claims cascade off it.
+- `coordination` — claims and outcomes (transactionally linked). A claim is
+  also the compute grant, so it is the only ledger admissions budget against.
+- `cursor` — delta-sync cursors.
+- `refresh` — the per-tracker ingest state machine, its pending cursor, and the
+  completion-emitted marker.
+- `fetch-request` — the durable instruction queue: enqueue, deliver, redeliver,
+  resolve, and the open count that decides when a refresh closes.
+- `notice` — once-per-episode markers for the scheduler's condition orders.
+- `policy` — the per-repo admission caps the running server was started with,
+  so a reader in another process reports against the caps in force.
+- `review` — milestone reviews with the member snapshot that expires them.
+
+The derived read-model (frontier, classification, milestone state, anomalies)
+lives in `../graph`; the scheduler that acts on it lives in `../schedule`.