reviewzy 0.1.0

package/src/db/style-guide.ts

@@ -0,0 +1,236 @@
+import { ulid } from "ulid";
+import { projectIdBySlug } from "./queries.ts";
+import type { Store } from "./store.ts";
+
+/** One `style_guides` row as stored: the json columns are opaque strings to every reader. */
+export type StyleGuideRow = {
+  readonly id: string;
+  readonly project_id: string | null;
+  readonly markdown: string;
+  readonly banned_words: string;
+  readonly glossary: string;
+};
+
+/** The typed shape every writer hands the store; the json encoding happens here, never at a call site. */
+export type StyleGuideInput = {
+  readonly markdown: string;
+  readonly bannedWords: readonly string[];
+  readonly glossary: Readonly<Record<string, string>>;
+};
+
+/** The save form at the boundary: the raw strings straight off the POST body, before any typing. */
+export type StyleGuideForm = {
+  readonly markdown: string;
+  readonly bannedWordsCsv: string;
+  readonly glossaryText: string;
+};
+
+/**
+ * The one refusal the parse knows: a glossary line that cannot become an entry. The line is named
+ * by number and content, and the reason tells the message which fix to offer. A line with a colon
+ * but an empty key refuses too: the merge renders an empty key as no item, so accepting it would
+ * silently drop what the author typed.
+ */
+export type StyleGuideFormRefusal = {
+  readonly kind: "glossary_line";
+  readonly lineNumber: number;
+  readonly line: string;
+  readonly reason: "no_colon" | "empty_key";
+};
+
+export type StyleGuideFormParse =
+  | { readonly ok: true; readonly input: StyleGuideInput }
+  | { readonly ok: false; readonly refusal: StyleGuideFormRefusal };
+
+/**
+ * Types the three form fields at the boundary. Banned words split on commas, trimmed, empties
+ * dropped, duplicates dropped at first occurrence (the merge's union keeps first occurrence too,
+ * so what the form shows after a save is what the merge would list). Glossary lines split on the
+ * first colon, both sides trimmed; blank lines are no entries (a textarea naturally ends in a
+ * newline); an empty value is a deliberate override, matching the merge's project-wins semantics.
+ * Markdown stays raw, never trimmed: the merge trims at render, and trimming here would store
+ * bytes the author never saw.
+ */
+export function parseStyleGuideForm(form: StyleGuideForm): StyleGuideFormParse {
+  const bannedWords: string[] = [];
+  for (const raw of form.bannedWordsCsv.split(",")) {
+    const word = raw.trim();
+    if (word !== "" && !bannedWords.includes(word)) bannedWords.push(word);
+  }
+
+  // The glossary accumulates on a null-prototype object: `glossary["__proto__"] = value` on a plain
+  // object would vanish through the Object.prototype setter, silently dropping a key the merge
+  // would render. An own property stores and round-trips like any other key.
+  const glossary: Record<string, string> = Object.create(null);
+  const lines = form.glossaryText.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.trim() === "") continue;
+    const colon = line.indexOf(":");
+    if (colon === -1) {
+      return { ok: false, refusal: { kind: "glossary_line", lineNumber: i + 1, line, reason: "no_colon" } };
+    }
+    const key = line.slice(0, colon).trim();
+    if (key === "") {
+      return { ok: false, refusal: { kind: "glossary_line", lineNumber: i + 1, line, reason: "empty_key" } };
+    }
+    glossary[key] = line.slice(colon + 1).trim();
+  }
+  return { ok: true, input: { markdown: form.markdown, bannedWords, glossary } };
+}
+
+/**
+ * Upserts one guide row: `projectSlug` null addresses the single global row, a slug its project
+ * row. The project must already exist — the dashboard editor (queue task 15) only ever edits
+ * projects that have entries, and reads never create one, so a slug that resolves to nothing is a
+ * caller bug, refused by name rather than minted.
+ */
+function resolveProjectId(store: Store, slug: string): string {
+  const id = projectIdBySlug(store, slug);
+  if (id === null) {
+    throw new Error(
+      `reviewzy: upsertStyleGuide: project "${slug}" does not exist; file an entry into it first, or pass null for the global row`,
+    );
+  }
+  return id;
+}
+
+export function upsertStyleGuide(store: Store, projectSlug: string | null, input: StyleGuideInput): void {
+  const projectId = projectSlug === null ? null : resolveProjectId(store, projectSlug);
+  const now = Date.now();
+  const write = store.db.transaction(() => {
+    // `IS ?` over `= ?`: a bound NULL must still match the global row, and `= NULL` never matches.
+    const existing = store.db.query("SELECT id FROM style_guides WHERE project_id IS ?").get(projectId) as
+      | { id: string }
+      | null;
+    if (existing === null) {
+      store.db.run(
+        `INSERT INTO style_guides (id, project_id, markdown, banned_words, glossary, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        [ulid(), projectId, input.markdown, JSON.stringify(input.bannedWords), JSON.stringify(input.glossary), now, now],
+      );
+    } else {
+      store.db.run(
+        "UPDATE style_guides SET markdown = ?, banned_words = ?, glossary = ?, updated_at = ? WHERE id = ?",
+        [input.markdown, JSON.stringify(input.bannedWords), JSON.stringify(input.glossary), now, existing.id],
+      );
+    }
+  });
+  write();
+}
+
+/** The stored json array, or the empty list when it is not an array of strings: only the editor (task 15) writes these columns, so a malformed value is a foreign or hand-edited row, not something to crash a read over. */
+function parseBannedWords(json: string): readonly string[] {
+  try {
+    const parsed: unknown = JSON.parse(json);
+    if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) return parsed;
+  } catch {
+    // fall through to the empty list
+  }
+  return [];
+}
+
+/** The stored json map, or the empty map when it is not an object of strings; same tolerance as `parseBannedWords`. */
+function parseGlossary(json: string): Readonly<Record<string, string>> {
+  try {
+    const parsed: unknown = JSON.parse(json);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed) &&
+      Object.values(parsed).every((value) => typeof value === "string")
+    ) {
+      return parsed as Record<string, string>;
+    }
+  } catch {
+    // fall through to the empty map
+  }
+  return {};
+}
+
+/** A stored item cannot carry a line break into the merged markdown: the break would render as a new bullet or a broken `key: value` line, saying things no stored item said. Foreign rows are tolerated, never their line breaks. */
+function renderItem(item: string): string {
+  return item.replace(/[\r\n]+/g, " ");
+}
+
+/** The one row a section addresses: `projectSlug` null is the single global row, a slug its project row. Null when the section has no row yet. */
+function guideRow(store: Store, projectSlug: string | null): StyleGuideRow | null {
+  if (projectSlug === null) {
+    return store.db.query(
+      "SELECT id, project_id, markdown, banned_words, glossary FROM style_guides WHERE project_id IS NULL",
+    ).get() as StyleGuideRow | null;
+  }
+  return store.db.query(
+    `SELECT s.id, s.project_id, s.markdown, s.banned_words, s.glossary
+     FROM style_guides s JOIN projects p ON p.id = s.project_id WHERE p.slug = ?`,
+  ).get(projectSlug) as StyleGuideRow | null;
+}
+
+/** The stored section read back typed, the read side of `parseStyleGuideForm`: the editor renders it, and a store row the editor never wrote (a foreign or hand-edited row) reads as empty values, never crashes. Null when the section has no row. */
+export function readStyleGuideSection(store: Store, projectSlug: string | null): StyleGuideInput | null {
+  const row = guideRow(store, projectSlug);
+  if (row === null) return null;
+  return { markdown: row.markdown, bannedWords: parseBannedWords(row.banned_words), glossary: parseGlossary(row.glossary) };
+}
+
+/**
+ * The merged style guide `docs/mcp-contract.md`'s resource section pins: the global row's markdown,
+ * a blank line, the project row's markdown, then the union of banned words (global items first,
+ * each once, at its first occurrence) and the glossary (global entries first, a key both rows
+ * define rendering the project value, project-only keys appended). Blocks join with exactly one
+ * blank line and the stored markdown is trimmed of trailing whitespace so an editor's trailing
+ * newline cannot stack blank lines. Both rows are optional: no rows at all renders the empty
+ * string. Deterministic for any fixed store.
+ *
+ * Queue task 8 (`fetch_approved`) embeds this same text, so this is the one place the merge is
+ * spelled out.
+ */
+export function mergedStyleGuide(store: Store, projectSlug: string): string {
+  const globalRow = guideRow(store, null);
+  const projectRow = guideRow(store, projectSlug);
+
+  const blocks: string[] = [];
+  for (const markdown of [globalRow?.markdown, projectRow?.markdown]) {
+    const trimmed = markdown?.trimEnd() ?? "";
+    if (trimmed !== "") blocks.push(trimmed);
+  }
+
+  const banned: string[] = [];
+  const seen = new Set<string>();
+  for (const word of [...parseBannedWords(globalRow?.banned_words ?? "[]"), ...parseBannedWords(projectRow?.banned_words ?? "[]")]) {
+    if (!seen.has(word)) {
+      seen.add(word);
+      banned.push(word);
+    }
+  }
+  // An empty word bans nothing and an empty key names no term: each would render a dangling bullet
+  // ("- " or "- : value"), so both are no items at all. Empty values are different — the
+  // project-wins `??` below makes an intentionally empty project value a deliberate override.
+  const bannedLines = banned.filter((word) => word !== "").map((word) => `- ${renderItem(word)}`);
+  if (bannedLines.length > 0) blocks.push(`## banned\n${bannedLines.join("\n")}`);
+
+  const glossary: [string, string][] = [];
+  const globalGlossary = parseGlossary(globalRow?.glossary ?? "{}");
+  const projectGlossary = parseGlossary(projectRow?.glossary ?? "{}");
+  const keys = new Set<string>();
+  for (const [key, value] of Object.entries(globalGlossary)) {
+    // The project wins a key it owns; the own-property read keeps a `__proto__` key the project
+    // lacks on the global value, where a bare index would return the inherited accessor. `??`
+    // falls through only on null/undefined, so an intentionally empty project value renders empty.
+    const projectValue = Object.hasOwn(projectGlossary, key) ? projectGlossary[key] : undefined;
+    glossary.push([key, projectValue ?? value]);
+    keys.add(key);
+  }
+  for (const [key, value] of Object.entries(projectGlossary)) {
+    if (!keys.has(key)) {
+      glossary.push([key, value]);
+      keys.add(key);
+    }
+  }
+  const glossaryLines = glossary
+    .filter(([key]) => key !== "")
+    .map(([key, value]) => `- ${renderItem(key)}: ${renderItem(value)}`);
+  if (glossaryLines.length > 0) blocks.push(`## glossary\n${glossaryLines.join("\n")}`);
+
+  return blocks.join("\n\n");
+}

package/src/db/sweep.ts

@@ -0,0 +1,88 @@
+import type { Store } from "./store.ts";
+
+/** The hourly cadence `src/daemon/main.ts` arms the sweep timer with. */
+export const SWEEP_INTERVAL_MS = 3_600_000;
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * The retention cutoff for a sweep taken "now": entries applied before this instant are past the
+ * `ARCHIVE_AFTER_DAYS` window (`docs/design.md` "retention").
+ */
+export function archiveCutoff(now: number, archiveAfterDays: number): number {
+  return now - archiveAfterDays * MS_PER_DAY;
+}
+
+/**
+ * The one classification every sweep statement re-asserts, bound with the cutoff: an applied
+ * entry whose apply is strictly older than the cutoff and not already archived. `applied_at < ?`
+ * never matches a NULL `applied_at` (sqlite folds the comparison to NULL, which a WHERE drops),
+ * and `archived_at IS NULL` keeps a live row already stamped out of the selection.
+ */
+const EXPIRED_APPLIED = "status = 'applied' AND applied_at < ? AND archived_at IS NULL";
+
+/**
+ * The candidate snapshot: what one sweep would move if it ran right now. Advisory only — the act
+ * (`sweepArchive`) re-asserts the same classification in every statement, so a row that changed
+ * after this read is skipped there, never moved.
+ */
+export function selectArchiveCandidates(store: Store, now: number, archiveAfterDays: number): string[] {
+  const rows = store.db
+    .query(`SELECT id FROM entries WHERE ${EXPIRED_APPLIED} ORDER BY id`)
+    .all(archiveCutoff(now, archiveAfterDays)) as { id: string }[];
+  return rows.map((row) => row.id);
+}
+
+/**
+ * The retention sweep: moves every expired applied entry, plus its revisions, into the archive
+ * tables, in one transaction, and returns the number of entries moved. A second run over the same
+ * data has nothing left to insert and returns 0.
+ *
+ * The statement order is load-bearing: the archive inserts run before the live deletes because
+ * `entry_revisions_archive.entry_id` references `entries_archive(id)` and `entry_revisions.entry_id`
+ * references `entries(id)`, both `NO ACTION` (migrations.ts) — a sweep that moved an entry without
+ * first moving its revisions, or deleted an entry before its revisions, fails loudly on the
+ * foreign key instead of orphaning or destroying history. Every statement re-asserts the
+ * classification, so a row that changed since a candidate snapshot was taken (the selection
+ * above) is skipped at act time rather than trusted from the snapshot.
+ */
+export function sweepArchive(store: Store, now: number, archiveAfterDays: number): number {
+  const cutoff = archiveCutoff(now, archiveAfterDays);
+  const move = store.db.transaction(() => {
+    // The entry copy is column-for-column, `archived_at` stamped with this sweep's now. The
+    // write count comes from this insert: it is exactly the entries moved.
+    const moved = store.db.run(
+      `INSERT INTO entries_archive (
+        id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
+        anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
+        filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, archived_at
+      )
+      SELECT
+        id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
+        anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
+        filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, ?
+      FROM entries
+      WHERE ${EXPIRED_APPLIED}`,
+      [now, cutoff],
+    ).changes;
+
+    store.db.run(
+      `INSERT INTO entry_revisions_archive (id, entry_id, human_text, status, created_at, archived_at)
+       SELECT r.id, r.entry_id, r.human_text, r.status, r.created_at, ?
+       FROM entry_revisions r
+       JOIN entries e ON e.id = r.entry_id
+       WHERE e.${EXPIRED_APPLIED}`,
+      [now, cutoff],
+    );
+
+    // Live revisions die before their entries: the NO ACTION foreign key makes the reverse order
+    // an immediate failure.
+    store.db.run(`DELETE FROM entry_revisions WHERE entry_id IN (SELECT id FROM entries WHERE ${EXPIRED_APPLIED})`, [
+      cutoff,
+    ]);
+    store.db.run(`DELETE FROM entries WHERE ${EXPIRED_APPLIED}`, [cutoff]);
+
+    return moved;
+  });
+  return move();
+}

package/src/mcp/await-approved.ts

@@ -0,0 +1,156 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { entriesByIds, type ApprovedEntryRow, type EntryStatus } from "../db/queries.ts";
+import { STATUS_CHANGE_EVENT, type Store } from "../db/store.ts";
+import { ApprovedEntry, approvedRowsToWire } from "./fetch-approved.ts";
+
+/** The contract's wait ceiling: `timeout_ms` caps at 600000. */
+export const AWAIT_TIMEOUT_MAX_MS = 600_000;
+
+/** The contract's wait default: 60000ms. */
+export const AWAIT_TIMEOUT_DEFAULT_MS = 60_000;
+
+/** The sqlite poll cadence that backs the event bus: resolution comes from an event when one is available, a status read at this interval otherwise. */
+const AWAIT_POLL_MS = 500;
+
+/** The hint `docs/mcp-contract.md` pins for a timeout or a drain: retry after this long, never sooner. */
+const AWAIT_POLL_AGAIN_MS = 5_000;
+
+/**
+ * The contract's clamp, pure so a unit test can pin it — a wire test cannot wait out 600 seconds.
+ * The zod boundary already refuses anything below 1, so the floor here only guards direct calls.
+ */
+export function clampTimeoutMs(ms: number): number {
+  return Math.min(Math.max(ms, 1), AWAIT_TIMEOUT_MAX_MS);
+}
+
+const AwaitApprovedArgs = z.object({
+  ids: z.array(z.string().min(1)).min(1),
+  timeout_ms: z.number().int().min(1).default(AWAIT_TIMEOUT_DEFAULT_MS),
+});
+
+const AwaitApprovedOutput = z.object({
+  resolved: z.boolean(),
+  statuses: z.record(z.string(), z.enum(["draft", "approved", "applied", "rejected"])),
+  entries: z.array(ApprovedEntry).optional(),
+  poll_again_after_ms: z.number().int().min(1).optional(),
+});
+
+type AwaitOutcome = {
+  readonly resolved: boolean;
+  readonly statuses: Record<string, EntryStatus>;
+  readonly entries: z.infer<typeof ApprovedEntry>[];
+};
+
+/** A refusal is an ordinary thrown Error: the SDK answers it as a tool result with `isError: true`, never as a json-rpc protocol error. */
+function refuse(where: string, problem: string, fix: string): never {
+  throw new Error(`await_approved refused: ${where}: ${problem}. fix: ${fix}`);
+}
+
+/**
+ * The one wait: every named id must be approved or rejected. The fast path is the store-scoped
+ * event bus — any status change wakes a re-check, and the re-check is the decision — with a 500ms
+ * sqlite poll as the backstop for a change that never dispatched, and the timeout as the ceiling.
+ * Settles once: the first resolution wins, and every timer and listener is torn down so the
+ * process exits cleanly. The drain path resolves the waiter through the store's waiter registry
+ * with the same poll-again outcome as a timeout, whatever the statuses say at that moment.
+ */
+function waitForEntries(store: Store, ids: readonly string[], timeoutMs: number): Promise<AwaitOutcome> {
+  return new Promise((resolve) => {
+    let settled = false;
+
+    function settle(outcome: AwaitOutcome): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      clearInterval(poll);
+      store.events.removeEventListener(STATUS_CHANGE_EVENT, recheck);
+      unregister();
+      resolve(outcome);
+    }
+
+    function evaluate(): AwaitOutcome {
+      const rows = entriesByIds(store, ids);
+      const statuses: Record<string, EntryStatus> = {};
+      const approved: ApprovedEntryRow[] = [];
+      for (const row of rows) {
+        statuses[row.id] = row.status;
+        if (row.status === "approved") approved.push(row);
+      }
+      // The status map's contract is one key per named id, so a row that vanished since the
+      // up-front check (the planned retention sweep moves rows to the archive) must not resolve
+      // the wait with the id silently missing: keep waiting, and the caller's next call surfaces
+      // the missing id in the up-front refusal.
+      const done =
+        rows.length === ids.length &&
+        rows.every((row) => row.status === "approved" || row.status === "rejected");
+      return done
+        ? { resolved: true, statuses, entries: approvedRowsToWire(approved) }
+        : { resolved: false, statuses, entries: [] };
+    }
+
+    function recheck(): void {
+      const outcome = evaluate();
+      // The event and the poll settle only a resolved wait; the timeout settles with the current
+      // state, and a drain with the current statuses forced into the poll-again shape.
+      if (outcome.resolved) settle(outcome);
+    }
+
+    function settleDrain(): void {
+      const outcome = evaluate();
+      // The drain's pin: always the poll-again shape, because the daemon is leaving — a
+      // resolved:true would hand the client a completed answer with no daemon behind it.
+      settle({ ...outcome, resolved: false });
+    }
+
+    const timeout = setTimeout(() => settle(evaluate()), timeoutMs);
+    const poll = setInterval(recheck, AWAIT_POLL_MS);
+    store.events.addEventListener(STATUS_CHANGE_EVENT, recheck);
+    const unregister = store.registerWaiter(settleDrain);
+
+    // The rows may already be resolved when the wait starts: the answer then is immediate.
+    recheck();
+  });
+}
+
+/**
+ * Registers the contract's blocking tool: a live session waits until every named id reaches
+ * approved or rejected. The up-front existence check and the refusal sit here, not in the query:
+ * reads never auto-create anything, so an unknown id must surface as a business refusal naming it
+ * before any waiting begins.
+ */
+export function registerAwaitApprovedTool(server: McpServer, store: Store): void {
+  server.registerTool(
+    "await_approved",
+    {
+      title: "Wait for entries to be approved or rejected",
+      description:
+        "Block until every named entry reaches approved or rejected, holding the call open — the one long-poll on this server, for a live session that filed entries and wants to sleep until the human signs off instead of polling fetch_approved. ids: the exact entry ids to wait for; duplicates are deduped silently, and the status map carries one key per id. timeout_ms: how long to block, default 60000, capped at 600000 — a larger value is clamped, never refused. Resolves when every named id is approved or rejected: resolved true, statuses one per named id, and entries the approved rows only, each in fetch_approved's row shape (id, repo, file, anchor_text, anchor_before, anchor_after, anchor_hash, file_hash, text, constraints parsed) — a rejected id appears in statuses only, never in entries. On timeout: resolved false, the current per-id statuses, and poll_again_after_ms 5000 — never an error; call again with the same ids to keep waiting. Refused, naming the id and the fix: an id that does not exist at call time (a read tool never creates one). An entry in applied does not resolve the wait: only approved or rejected does.",
+      inputSchema: AwaitApprovedArgs,
+      outputSchema: AwaitApprovedOutput,
+    },
+    async (args) => {
+      const ids = [...new Set(args.ids)];
+      const timeoutMs = clampTimeoutMs(args.timeout_ms);
+
+      const existing = new Set(entriesByIds(store, ids).map((row) => row.id));
+      const missing = ids.filter((id) => !existing.has(id));
+      if (missing.length > 0) {
+        refuse(
+          `entry "${missing[0]!}"${missing.length > 1 ? ` and ${missing.length - 1} more` : ""}`,
+          "no such entry, and a read tool never creates one",
+          "file it with file_entries first, or list entries to see the ids that exist",
+        );
+      }
+
+      const outcome = await waitForEntries(store, ids, timeoutMs);
+      const output = outcome.resolved
+        ? { resolved: true, statuses: outcome.statuses, entries: outcome.entries }
+        : { resolved: false, statuses: outcome.statuses, poll_again_after_ms: AWAIT_POLL_AGAIN_MS };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  );
+}

package/src/mcp/fetch-approved.ts

@@ -0,0 +1,132 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { approvedEntries, projectIdBySlug, type ApprovedEntryRow } from "../db/queries.ts";
+import { mergedStyleGuide } from "../db/style-guide.ts";
+import type { Store } from "../db/store.ts";
+
+/**
+ * The contract's three params, `project` required: there is no cross-project fetch — the merged
+ * style guide is per-project, and the applying agent needs the voice of the project it writes into.
+ */
+const FetchApprovedArgs = z.object({
+  project: z.string().min(1),
+  ids: z.array(z.string().min(1)).min(1).optional(),
+  since: z.string().min(1).optional(),
+});
+
+/**
+ * The read-side constraints shape: the same four fields the write boundary refuses to misspell,
+ * but tolerated loosely — a row storing anything else (a hand-edited or foreign row, since no
+ * writer of this server produced it) renders `{}` instead of failing an apply-back.
+ */
+const ParsedConstraints = z.strictObject({
+  max_len: z.number().int().positive().optional(),
+  placeholders: z.array(z.string()).optional(),
+  tone: z.string().optional(),
+  notes: z.string().optional(),
+});
+
+/** The wire entry the contract's parenthetical names: text + anchor + constraints, no status (everything here is approved) and no context. */
+export const ApprovedEntry = z.object({
+  id: z.string(),
+  repo: z.string(),
+  file: z.string(),
+  anchor_text: z.string(),
+  anchor_before: z.string(),
+  anchor_after: z.string(),
+  anchor_hash: z.string(),
+  file_hash: z.string(),
+  text: z.string().nullable(),
+  constraints: ParsedConstraints,
+});
+
+const FetchApprovedOutput = z.object({
+  entries: z.array(ApprovedEntry),
+  style_guide: z.string(),
+  next_since: z.string().optional(),
+});
+
+/** A refusal is an ordinary thrown Error: the SDK answers it as a tool result with `isError: true`, never as a json-rpc protocol error. */
+function refuse(where: string, problem: string, fix: string): never {
+  throw new Error(`fetch_approved refused: ${where}: ${problem}. fix: ${fix}`);
+}
+
+/**
+ * The stored constraints json, or the empty object when it does not parse into the typed shape —
+ * the same tolerance class as the style-guide reads: an unparseable value is a foreign or
+ * hand-edited row, never a reason to fail the fetch.
+ */
+function parseConstraints(json: string): z.infer<typeof ParsedConstraints> {
+  try {
+    const parsed: unknown = JSON.parse(json);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      const result = ParsedConstraints.safeParse(parsed);
+      if (result.success) return result.data;
+    }
+  } catch {
+    // fall through to the empty object
+  }
+  return {};
+}
+
+/**
+ * The one mapping from approved store rows to the wire shape; fetch_approved and await_approved
+ * share it, so the two tools' entries arrays cannot drift.
+ */
+export function approvedRowsToWire(rows: readonly ApprovedEntryRow[]): z.infer<typeof ApprovedEntry>[] {
+  return rows.map((row) => ({
+    id: row.id,
+    repo: row.repo,
+    file: row.file,
+    anchor_text: row.anchor_text,
+    anchor_before: row.anchor_before,
+    anchor_after: row.anchor_after,
+    anchor_hash: row.anchor_hash,
+    file_hash: row.file_hash,
+    text: row.human_text,
+    constraints: parseConstraints(row.constraints),
+  }));
+}
+
+/**
+ * Registers the contract's apply-back tool: approved prose, anchors, and constraints, with the
+ * merged style guide embedded so a bulk rewrite shares one voice. The project lookup and the
+ * refusal sit here, not in the query: reads never auto-create a project, so an unknown slug must
+ * surface as a business refusal naming the slug and the fix before any query runs.
+ */
+export function registerFetchApprovedTool(server: McpServer, store: Store): void {
+  server.registerTool(
+    "fetch_approved",
+    {
+      title: "Fetch approved entries to apply",
+      description:
+        "Fetch the approved entries of a project, ready to apply: the human-signed prose (text), the anchor to locate and replace it by, and the constraints the replacement must keep. Only approved entries are ever returned — a draft, applied, or rejected entry never appears, and an id naming one simply contributes nothing. Entries come back ordered by ascending entry id, at most 50 per call (fixed server-side page); when exactly 50 come back, next_since holds the last entry's id, and the walk continues by passing that id back as since (rows with id > since) — when next_since is absent the walk is exhausted, stop fetching. ids (exact entry ids) combines with since by AND. The project slug is required and must already exist: an unknown slug is refused (read tools never create one). Each entry carries id, repo, file, anchor_text, anchor_before, anchor_after, anchor_hash, file_hash, text (the approved prose; null only on an approved row nobody ever wrote into), and constraints — parsed into {max_len?, placeholders?, tone?, notes?} so the apply-back can check the text against them, an unparseable stored value rendering as {}. style_guide is the same merged text the reviewzy://projects/{slug}/style-guide resource serves, embedded so bulk rewrites share one voice.",
+      inputSchema: FetchApprovedArgs,
+      outputSchema: FetchApprovedOutput,
+    },
+    async (args) => {
+      const projectId = projectIdBySlug(store, args.project);
+      if (projectId === null) {
+        refuse(
+          `project "${args.project}"`,
+          "no such project, and a read tool never creates one",
+          "file an entry into it with file_entries first, then fetch again",
+        );
+      }
+
+      const { rows, nextSince } = approvedEntries(store, projectId, { ids: args.ids, since: args.since });
+
+      const output = {
+        entries: approvedRowsToWire(rows),
+        style_guide: mergedStyleGuide(store, args.project),
+        // An exhausted walk carries no `next_since` key at all: absent is the signal to stop, so an
+        // empty page must never smuggle one in.
+        ...(nextSince === null ? {} : { next_since: nextSince }),
+      };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  );
+}