@coreplane/switchboard 1.205.0 → 1.206.0

package/dist/assets/src/core/delivery.ts

@@ -81,6 +81,9 @@ export interface PullRequestFacts {
   createdAt: string;
   /** ISO 8601 — every fact here is a MERGED pull request. */
   mergedAt: string;
+  /** ISO 8601 — GitHub's `updated_at` of the pull request when these facts were read; an incremental
+   *  read re-reads a listed row only when this moved. Absent on facts read before it was kept. */
+  updatedAt?: string;
   /** The head CI first ran on; absent when nothing recorded a head. */
   firstHeadSha?: string;
   ci: CiRunFact[];
@@ -201,6 +204,22 @@ export interface DeliveryReport {
   /** ISO 8601 — when the pull requests' facts were read from GitHub: the snapshot's time, or
    *  the live read's. The service stamps it; a report built straight from facts has none. */
   snapshotAt?: string;
+  /** ISO 8601 — every pull request merged at or after this instant is in the report; when the
+   *  report is `truncated`, the weeks that began before it hold the newest pull requests only
+   *  (`weekIncomplete`). The service stamps it from the source; a report built straight from
+   *  facts has none. */
+  completeFrom?: string;
+}
+
+/** A week row holds the newest pull requests only — not the week's — when the report is truncated and
+ *  the week began before the instant the report is complete from (the week holding that instant is
+ *  partial, so it counts). A report that names no instant marks no week. */
+export function weekIncomplete(report: Pick<DeliveryReport, "truncated" | "completeFrom">, week: string): boolean {
+  return (
+    report.truncated &&
+    report.completeFrom !== undefined &&
+    Date.parse(`${week}T00:00:00Z`) < Date.parse(report.completeFrom)
+  );
 }
 
 // ---- the arithmetic ---------------------------------------------------------------------
@@ -546,9 +565,18 @@ export function snapshotAgeText(snapshotAt: string, nowMs: number): string {
   return unit(Math.round(hours / 24), "day");
 }
 
+/** `<YYYY-MM-DD> <hh:mm> UTC` — an instant as the text spells one. */
+const clock = (iso: string): string => `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+
 /** `as of <YYYY-MM-DD> <hh:mm> UTC, 12 minutes ago` — the snapshot's time and age. */
 function asOf(snapshotAt: string, nowMs: number): string {
-  return `as of ${snapshotAt.slice(0, 10)} ${snapshotAt.slice(11, 16)} UTC, ${snapshotAgeText(snapshotAt, nowMs)}`;
+  return `as of ${clock(snapshotAt)}, ${snapshotAgeText(snapshotAt, nowMs)}`;
+}
+
+/** `the newest 291 pull requests only, complete from <YYYY-MM-DD> <hh:mm> UTC` — what a truncated report covers. */
+function coverage(report: DeliveryReport): string {
+  const from = report.completeFrom === undefined ? "" : `, complete from ${clock(report.completeFrom)}`;
+  return `the newest ${report.totals.prsMerged} pull requests only${from}`;
 }
 
 /** One block per week, then the units — single-spaced lines, so chat carries them as they are. */
@@ -557,19 +585,16 @@ export function renderDeliveryReport(report: DeliveryReport, nowMs: number = sys
     [
       `${report.repo} · ${report.range.since} → ${report.range.until} · ${report.range.weeks} week${report.range.weeks === 1 ? "" : "s"}`,
       ...(report.snapshotAt !== undefined ? [asOf(report.snapshotAt, nowMs)] : []),
+      ...(report.truncated ? [coverage(report)] : []),
     ].join(" · "),
   ];
-  if (report.truncated) lines.push("(the newest pull requests only — the fetch stopped before the range's start)");
   for (const w of report.weeks) {
+    const week = `Week of ${w.week}${weekIncomplete(report, w.week) ? " (incomplete)" : ""}`;
     if (w.prsMerged === 0) {
-      lines.push("", `Week of ${w.week}: nothing merged`);
+      lines.push("", `${week}: nothing merged`);
       continue;
     }
-    lines.push(
-      "",
-      `Week of ${w.week}: ${w.prsMerged} merged (${w.agentAuthoredPrs} agent-authored)`,
-      ...indicatorLines(w),
-    );
+    lines.push("", `${week}: ${w.prsMerged} merged (${w.agentAuthoredPrs} agent-authored)`, ...indicatorLines(w));
   }
   if (report.weeks.length > 1 && report.totals.prsMerged > 0) {
     lines.push(
@@ -675,6 +700,11 @@ export interface DeliveryFetch {
 export interface DeliveryFetchOptions {
   /** Read GitHub now, whatever a snapshot holds, and refresh the snapshot. */
   fresh?: boolean;
+  /** An incremental read (the snapshot's refresh): only the pull requests touched at or after `since`
+   *  — the listing is newest-touched first, so the first older row ends it — and, of those, only the
+   *  rows whose update time `known` does not already hold for their number; a held row's stored facts
+   *  stand. The fetch is then complete from `since`, not from the range's start. */
+  touched?: { since: string; known: ReadonlyMap<number, string> };
 }
 
 /** Where the pull requests' facts come from: GitHub in production (behind the snapshot), memory in tests. */
@@ -682,13 +712,36 @@ export interface DeliverySource {
   fetchPullRequests(repo: string, range: DeliveryRange, opts?: DeliveryFetchOptions): Promise<DeliveryFetch>;
 }
 
-/** The second implementation (AGENTS.md invariant 2) and the test double: a map of repo → facts. */
+/** The second implementation (AGENTS.md invariant 2) and the test double: a map of repo → facts.
+ *  An incremental read answers the rows touched since the instant (by `updatedAt`, else `mergedAt`)
+ *  whose update time the caller does not hold, complete from that instant. */
 export class InMemoryDeliverySource implements DeliverySource {
-  readonly calls: Array<{ repo: string; range: DeliveryRange; fresh?: boolean }> = [];
-  constructor(private readonly byRepo: Readonly<Record<string, PullRequestFacts[]>> = {}) {}
+  readonly calls: Array<{
+    repo: string;
+    range: DeliveryRange;
+    fresh?: boolean;
+    touched?: DeliveryFetchOptions["touched"];
+  }> = [];
+  constructor(private byRepo: Readonly<Record<string, PullRequestFacts[]>> = {}) {}
+  /** Replace what a repository answers (a test moving GitHub on). */
+  set(repo: string, prs: PullRequestFacts[]): void {
+    this.byRepo = { ...this.byRepo, [repo]: prs };
+  }
   fetchPullRequests(repo: string, range: DeliveryRange, opts?: DeliveryFetchOptions): Promise<DeliveryFetch> {
-    this.calls.push({ repo, range, ...(opts?.fresh ? { fresh: true } : {}) });
-    return Promise.resolve({ prs: this.byRepo[repo] ?? [], truncated: false });
+    this.calls.push({
+      repo,
+      range,
+      ...(opts?.fresh ? { fresh: true } : {}),
+      ...(opts?.touched ? { touched: opts.touched } : {}),
+    });
+    const all = this.byRepo[repo] ?? [];
+    const touched = opts?.touched;
+    if (!touched) return Promise.resolve({ prs: all, truncated: false });
+    const since = Date.parse(touched.since);
+    const prs = all.filter(
+      (p) => Date.parse(p.updatedAt ?? p.mergedAt) >= since && touched.known.get(p.number) !== p.updatedAt,
+    );
+    return Promise.resolve({ prs, truncated: false, completeFrom: touched.since });
   }
 }
 
@@ -707,8 +760,8 @@ export interface DeliveryService {
   /** The configured repositories; the first is the page's default. */
   repos(): string[];
   /** The report for one repository over the resolved range — from the snapshot when one fits the
-   *  range, a live read otherwise or on `fresh`; stamped with when its facts were read. Throws on
-   *  upstream failure. */
+   *  range, a live read otherwise or on `fresh`; stamped with when its facts were read and from
+   *  when they are complete. Throws on upstream failure. */
   report(repo: string, opts: DeliveryReportOptions): Promise<DeliveryReport>;
 }
 
@@ -769,6 +822,7 @@ export function createDeliveryService(
         }),
         // A source behind a snapshot says when it read; a bare one read just now.
         snapshotAt: fetched.fetchedAt ?? at.toISOString(),
+        ...(fetched.completeFrom !== undefined ? { completeFrom: fetched.completeFrom } : {}),
       };
     },
   };

package/dist/assets/src/core/deliverySnapshotStore.ts

@@ -17,27 +17,44 @@ import { errorSuffix } from "./workerError.js";
 // Node-free on purpose: the state Worker imports `isDeliverySnapshot` by
 // relative path so the bot and the Worker validate ONE shape.
 //
+// A snapshot is written whole once — the first read of a repository — and
+// patched by every refresh after: the rows the refresh re-read, the rows that
+// aged out of the window, the new meta. A busy repository's window is many MB
+// and its hourly change a few rows, so the write follows the change.
+//
 // Route contract (JSON in/out, bearer = the Worker's MEMORY_TOKEN):
-//   POST /delivery/get {repo}      → {snapshot: DeliverySnapshot | null}
-//   POST /delivery/put {snapshot}  → {ok: true, prs}
+//   POST /delivery/get {repo}       → {snapshot: DeliverySnapshot | null}
+//   POST /delivery/put {snapshot}   → {ok: true, prs}          replace the repository's snapshot whole
+//   POST /delivery/merge {patch}    → {ok: true, prs} | 404    apply a refresh; 404 with no snapshot to merge into
 
-/** One repository's facts as a source assembled them, and when. */
-export interface DeliverySnapshot {
+/** What a snapshot says about itself: everything but the rows. */
+export interface DeliverySnapshotMeta {
   /** `owner/name`. */
   repo: string;
   /** ISO 8601 — when the read from GitHub began. */
   snapshotAt: string;
   /** The window the facts were read for: Monday-start weeks ending on the snapshot day. */
   range: DeliveryRange;
-  /** Every pull request merged inside the window that the read reached. */
-  prs: PullRequestFacts[];
-  /** The listing stopped at its page cap before the window's start — the newest pull requests only. */
+  /** The read stopped at its page cap before the window's start — the newest pull requests only. */
   truncated: boolean;
   /** ISO 8601 — every pull request merged at or after this instant is in `prs`: the window's
-   *  start on a complete read, the oldest update the capped listing reached otherwise. */
+   *  start on a complete read, the oldest update a capped listing reached otherwise. */
   completeFrom: string;
 }
 
+/** One repository's facts as a source assembled them, and when. */
+export interface DeliverySnapshot extends DeliverySnapshotMeta {
+  /** Every pull request merged inside the window that the reads reached, in number order. */
+  prs: PullRequestFacts[];
+}
+
+/** What one refresh changes in a stored snapshot: the new meta, the rows the read re-read — they
+ *  replace the stored ones by number — and the numbers of the rows that aged out of the window. */
+export interface DeliverySnapshotPatch extends DeliverySnapshotMeta {
+  upsert: PullRequestFacts[];
+  drop: number[];
+}
+
 const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
 const isInstant = (v: unknown): v is string => typeof v === "string" && Number.isFinite(Date.parse(v));
 
@@ -52,6 +69,7 @@ export function isPullRequestFacts(v: unknown): v is PullRequestFacts {
     typeof p.author === "string" &&
     isInstant(p.createdAt) &&
     isInstant(p.mergedAt) &&
+    (p.updatedAt === undefined || isInstant(p.updatedAt)) &&
     (p.firstHeadSha === undefined || typeof p.firstHeadSha === "string") &&
     Array.isArray(p.ci) &&
     Array.isArray(p.reviews) &&
@@ -60,32 +78,59 @@ export function isPullRequestFacts(v: unknown): v is PullRequestFacts {
   );
 }
 
-export function isDeliverySnapshot(v: unknown): v is DeliverySnapshot {
-  if (typeof v !== "object" || v === null) return false;
-  const s = v as Record<string, unknown>;
+/** The fields every snapshot document carries, present and of the right kind. */
+function hasSnapshotMeta(s: Record<string, unknown>): boolean {
   if (typeof s.repo !== "string" || !REPO_SLUG.test(s.repo)) return false;
   if (!isInstant(s.snapshotAt) || !isInstant(s.completeFrom)) return false;
   if (typeof s.truncated !== "boolean") return false;
   const range = s.range as Record<string, unknown> | null | undefined;
-  if (
-    typeof range !== "object" ||
-    range === null ||
-    typeof range.since !== "string" ||
-    !ISO_DAY.test(range.since) ||
-    typeof range.until !== "string" ||
-    !ISO_DAY.test(range.until) ||
-    typeof range.weeks !== "number" ||
-    !Number.isFinite(range.weeks)
-  )
-    return false;
-  return Array.isArray(s.prs) && s.prs.every(isPullRequestFacts);
+  return (
+    typeof range === "object" &&
+    range !== null &&
+    typeof range.since === "string" &&
+    ISO_DAY.test(range.since) &&
+    typeof range.until === "string" &&
+    ISO_DAY.test(range.until) &&
+    typeof range.weeks === "number" &&
+    Number.isFinite(range.weeks)
+  );
+}
+
+export function isDeliverySnapshot(v: unknown): v is DeliverySnapshot {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v as Record<string, unknown>;
+  return hasSnapshotMeta(s) && Array.isArray(s.prs) && s.prs.every(isPullRequestFacts);
+}
+
+export function isDeliverySnapshotPatch(v: unknown): v is DeliverySnapshotPatch {
+  if (typeof v !== "object" || v === null) return false;
+  const { upsert, drop, ...meta } = v as Record<string, unknown>;
+  return (
+    hasSnapshotMeta(meta) &&
+    Array.isArray(upsert) &&
+    upsert.every(isPullRequestFacts) &&
+    Array.isArray(drop) &&
+    drop.every((n) => typeof n === "number" && Number.isFinite(n))
+  );
+}
+
+/** The snapshot a patch leaves behind when applied to `stored`: rows by number, in number order. */
+export function applyPatch(stored: DeliverySnapshot, patch: DeliverySnapshotPatch): DeliverySnapshot {
+  const { upsert, drop, ...meta } = patch;
+  const rows = new Map(stored.prs.map((p) => [p.number, p]));
+  for (const p of upsert) rows.set(p.number, p);
+  for (const n of drop) rows.delete(n);
+  return { ...meta, prs: [...rows.values()].sort((a, b) => a.number - b.number) };
 }
 
 export interface DeliverySnapshotStore {
   /** The repository's stored snapshot, or undefined when none was ever stored. Throws on failure. */
   get(repo: string): Promise<DeliverySnapshot | undefined>;
-  /** Replace the repository's snapshot. Throws on failure; callers warn, never crash. */
+  /** Replace the repository's snapshot whole. Throws on failure; callers warn, never crash. */
   put(snapshot: DeliverySnapshot): Promise<void>;
+  /** Apply a refresh to the repository's stored snapshot. False when nothing is stored to merge
+   *  into — the caller then writes the snapshot whole. Throws on failure. */
+  merge(patch: DeliverySnapshotPatch): Promise<boolean>;
 }
 
 export class InMemoryDeliverySnapshotStore implements DeliverySnapshotStore {
@@ -99,6 +144,13 @@ export class InMemoryDeliverySnapshotStore implements DeliverySnapshotStore {
   async put(snapshot: DeliverySnapshot): Promise<void> {
     this.byRepo.set(snapshot.repo, structuredClone(snapshot));
   }
+
+  async merge(patch: DeliverySnapshotPatch): Promise<boolean> {
+    const stored = this.byRepo.get(patch.repo);
+    if (!stored) return false;
+    this.byRepo.set(patch.repo, applyPatch(stored, structuredClone(patch)));
+    return true;
+  }
 }
 
 /** Per-request ceiling: a snapshot of a busy repository is a few MB each way. */
@@ -137,6 +189,14 @@ export class WorkerDeliverySnapshotStore implements DeliverySnapshotStore {
     if (!res.ok) throw new Error(`state Worker /delivery/put HTTP ${res.status}${await errorSuffix(res)}`);
   }
 
+  async merge(patch: DeliverySnapshotPatch): Promise<boolean> {
+    const res = await this.post("/delivery/merge", { patch });
+    // Nothing stored to merge into — or a Worker from before the route: either way the caller writes whole.
+    if (res.status === 404) return false;
+    if (!res.ok) throw new Error(`state Worker /delivery/merge HTTP ${res.status}${await errorSuffix(res)}`);
+    return true;
+  }
+
   private post(path: string, body: unknown): Promise<Response> {
     return this.fetchImpl(`${this.baseUrl}${path}`, {
       method: "POST",

package/dist/assets/src/core/reviewVerdict.ts

@@ -0,0 +1,296 @@
+// Deterministic review verdict → GitHub comment body.
+//
+// Downstream automation (a repository's opt-in `auto-approve-review-lgtm.yml`
+// workflow) approves a PR when the review App's review body STARTS WITH the
+// exact token `LGTM:`. That token must therefore never depend on how the model happens to
+// phrase its opening line. The model states its judgement through the
+// structured `submit_verdict` tool (src/tools/workspace.ts); this module turns
+// that structured value into the first line of the posted body:
+//
+//   approve          → "LGTM: <summary>"
+//   request_changes  → "Changes requested: <summary>"
+//   (no verdict)     → "No verdict submitted — not approving." (fail-closed)
+//
+// The model's prose follows after a blank line. Whatever the prose says, only
+// an explicit `approve` verdict can produce a body that begins with "LGTM".
+//
+// The verdict also carries typed findings (docs/reference/specs/agent-ship.md item 6):
+// one compact entry per issue, rendered as a list under the verdict line, so
+// a fix round can reference each finding by its stable id and answer it with
+// a typed disposition (`parseDispositionsInput` below). Findings validate
+// fail-closed PER finding — a malformed finding drops with a note, a
+// malformed array drops the whole field — and an `approve` carrying a
+// self-declared `blocking` finding is downgraded to `request_changes`, so the
+// posted body can never begin with `LGTM:` over a defect the reviewer itself
+// called blocking.
+
+import { normalizeHead } from "./reviewedHead.js";
+import { redactSecrets } from "./redact.js";
+
+export type ReviewVerdictKind = "approve" | "request_changes";
+
+export const FINDING_SEVERITIES = ["blocking", "major", "minor", "nit"] as const;
+export type FindingSeverity = (typeof FINDING_SEVERITIES)[number];
+
+export interface Finding {
+  /** Stable id the reviewer assigned in order ("F1", "F2", …) — dispositions
+   *  reference findings by this id. */
+  id: string;
+  severity: FindingSeverity;
+  /** Repo-relative file the finding points at. */
+  file: string;
+  /** Optional 1-based line. An unusable value is dropped like a malformed
+   *  `head` — the finding stands without it. */
+  line?: number;
+  /** One line naming the issue; the full explanation lives in the prose. */
+  title: string;
+}
+
+export interface ReviewVerdict {
+  verdict: ReviewVerdictKind;
+  /** One line: why. Newlines are collapsed so the token line stays one line. */
+  summary: string;
+  /** The commit the agent says it reviewed (`git rev-parse HEAD` in its
+   *  checkout), 7–40 lowercase hex. The dispatcher's reviewed-head guard
+   *  (reviewedHead.ts) compares it to the PR head when the workspace HEAD
+   *  could not be observed directly. Absent when not supplied or malformed. */
+  head?: string;
+  /** Typed findings enumerated through `submit_verdict`. Present only when
+   *  the input carried a findings array (possibly empty after drops); absent
+   *  when no array was supplied or the array itself was malformed. */
+  findings?: Finding[];
+  /** Parse notes naming what was dropped from `findings` (ids/indices with
+   *  reasons) — surfaced in the tool ack so the model can resubmit, never
+   *  rendered into the posted body. */
+  droppedFindings?: string[];
+}
+
+export const LGTM_TOKEN = "LGTM:";
+export const CHANGES_TOKEN = "Changes requested:";
+export const NO_VERDICT_LINE = "No verdict submitted — not approving.";
+
+/** Parse an arbitrary tool input into a verdict, or null when it is not one. */
+export function parseVerdictInput(input: Record<string, unknown>): ReviewVerdict | null {
+  const verdict = input.verdict;
+  if (verdict !== "approve" && verdict !== "request_changes") return null;
+  const summary = typeof input.summary === "string" ? oneLine(input.summary) : "";
+  const head = normalizeHead(input.head);
+  const out: ReviewVerdict = { verdict, summary };
+  if (head) out.head = head;
+  if (input.findings !== undefined) {
+    const parsed = parseFindings(input.findings);
+    if (parsed.findings) out.findings = parsed.findings;
+    if (parsed.dropped.length) out.droppedFindings = parsed.dropped;
+    // Verdict/severity consistency, fail-closed: an approve carrying a
+    // blocking finding downgrades so the posted body can never start with
+    // `LGTM:` over a self-declared blocking defect. Keyed on the RAW entries'
+    // declared severity, not the validated survivors — a blocking entry that
+    // itself failed validation and dropped still poisons the approve.
+    if (out.verdict === "approve" && parsed.blocking.length > 0) {
+      out.verdict = "request_changes";
+      out.summary = oneLine(
+        `${out.summary} [downgraded from approve: blocking finding${parsed.blocking.length === 1 ? "" : "s"} ${parsed.blocking.join(", ")}]`,
+      );
+    }
+  }
+  return out;
+}
+
+/** Fail-closed per finding: each malformed entry drops with a note naming its
+ *  index (and id when readable); a non-array drops the whole field.
+ *  `blocking` labels every raw entry that declared severity "blocking" —
+ *  valid or not — for the approve downgrade above. */
+function parseFindings(value: unknown): { findings?: Finding[]; dropped: string[]; blocking: string[] } {
+  if (!Array.isArray(value)) {
+    return { dropped: ["findings: dropped — not an array"], blocking: [] };
+  }
+  const findings: Finding[] = [];
+  const dropped: string[] = [];
+  const blocking: string[] = [];
+  value.forEach((raw, i) => {
+    const parsed = parseFinding(raw);
+    if (parsed.finding) {
+      findings.push(parsed.finding);
+    } else {
+      dropped.push(`findings[${i}]${parsed.id ? ` (${parsed.id})` : ""}: dropped — ${parsed.reason}`);
+    }
+    const label = parsed.finding?.id ?? parsed.id ?? `findings[${i}]`;
+    const r = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : undefined;
+    if (r?.severity === "blocking") blocking.push(label);
+  });
+  return { findings, dropped, blocking };
+}
+
+function parseFinding(
+  raw: unknown,
+): { finding: Finding; id?: never; reason?: never } | { finding?: never; id?: string; reason: string } {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { reason: "not an object" };
+  const r = raw as Record<string, unknown>;
+  const id = typeof r.id === "string" ? oneLine(r.id) : "";
+  if (!id) return { reason: "missing or empty id" };
+  const severity = r.severity;
+  if (!(FINDING_SEVERITIES as readonly unknown[]).includes(severity)) {
+    return { id, reason: `invalid severity ${JSON.stringify(r.severity)} (expected ${FINDING_SEVERITIES.join("|")})` };
+  }
+  const file = typeof r.file === "string" ? oneLine(r.file) : "";
+  if (!file) return { id, reason: "missing or empty file" };
+  const title = typeof r.title === "string" ? oneLine(r.title) : "";
+  if (!title) return { id, reason: "missing or empty title" };
+  const finding: Finding = { id, severity: severity as FindingSeverity, file, title };
+  // Like `head`: an unusable optional locator is dropped, the finding stands —
+  // dropping the whole finding over a bad line would also drop the severity
+  // that the approve→request_changes downgrade keys on.
+  if (typeof r.line === "number" && Number.isInteger(r.line) && r.line >= 1) finding.line = r.line;
+  return { finding };
+}
+
+function oneLine(s: string): string {
+  return s.replace(/\s*\n+\s*/g, " ").trim();
+}
+
+/** The exact first line of the posted body for a verdict (or its absence). */
+export function verdictLine(verdict: ReviewVerdict | undefined): string {
+  if (!verdict) return NO_VERDICT_LINE;
+  const token = verdict.verdict === "approve" ? LGTM_TOKEN : CHANGES_TOKEN;
+  const summary = oneLine(verdict.summary);
+  return summary ? `${token} ${summary}` : token;
+}
+
+/** One compact finding line — `[severity] id file[:line] — title` — shared by
+ *  the posted body's list (bulleted below) and ship's synthesized child turns. */
+export function formatFinding(f: Finding): string {
+  const location = f.line !== undefined ? `${f.file}:${f.line}` : f.file;
+  return `[${f.severity}] ${f.id} ${location} — ${f.title}`;
+}
+
+/**
+ * Build the body posted to GitHub: the deterministic verdict line, the
+ * compact findings list (when present), a blank line, then the model's
+ * review text. Never starts with "LGTM" unless the verdict is `approve`.
+ */
+export function buildReviewPostBody(answer: string, verdict: ReviewVerdict | undefined): string {
+  const head = [verdictLine(verdict), ...(verdict?.findings ?? []).map((f) => `- ${formatFinding(f)}`)];
+  return `${head.join("\n")}\n\n${answer.trim()}`;
+}
+
+// --- Dispositions (the coding side's answer to findings) -------------------
+//
+// A fix round records one disposition per finding through the
+// `submit_dispositions` tool; the ship orchestrator keeps the last valid set
+// and splits a cap report into declined (disposition recorded) vs unaddressed
+// (none). Validation mirrors the findings above: a malformed entry drops with
+// a note; a non-array input rejects the whole call.
+
+export type DispositionKind = "fixed" | "declined";
+
+export interface FindingDisposition {
+  /** The stable finding id from the review verdict this disposition answers. */
+  findingId: string;
+  disposition: DispositionKind;
+  /** One line: what was done, or why the finding was declined. */
+  note: string;
+}
+
+/**
+ * Parse a `submit_dispositions` input. Null when `dispositions` is not an
+ * array (the call is rejected, nothing recorded); otherwise each malformed
+ * entry drops with a note naming its index (and findingId when readable),
+ * mirroring the per-finding validation above. A missing note is tolerated as
+ * "" (the summary convention), never a dropped entry.
+ */
+export function parseDispositionsInput(
+  input: Record<string, unknown>,
+): { dispositions: FindingDisposition[]; dropped: string[] } | null {
+  const value = input.dispositions;
+  if (!Array.isArray(value)) return null;
+  const dispositions: FindingDisposition[] = [];
+  const dropped: string[] = [];
+  value.forEach((raw, i) => {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      dropped.push(`dispositions[${i}]: dropped — not an object`);
+      return;
+    }
+    const r = raw as Record<string, unknown>;
+    const findingId = typeof r.findingId === "string" ? oneLine(r.findingId) : "";
+    if (!findingId) {
+      dropped.push(`dispositions[${i}]: dropped — missing or empty findingId`);
+      return;
+    }
+    const disposition = r.disposition;
+    if (disposition !== "fixed" && disposition !== "declined") {
+      dropped.push(
+        `dispositions[${i}] (${findingId}): dropped — invalid disposition ${JSON.stringify(r.disposition)} (expected fixed|declined)`,
+      );
+      return;
+    }
+    const note = typeof r.note === "string" ? oneLine(r.note) : "";
+    dispositions.push({ findingId, disposition, note });
+  });
+  return { dispositions, dropped };
+}
+
+// ---- the stored shapes (docs/reference/specs/run-history.md items 2 and 3) ---------------------------
+
+const VERDICT_KINDS: readonly string[] = ["approve", "request_changes"];
+const DISPOSITION_KINDS: readonly string[] = ["fixed", "declined"];
+
+const isRecordLike = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
+
+function isFindingShape(v: unknown): v is Finding {
+  if (!isRecordLike(v)) return false;
+  return (
+    typeof v.id === "string" &&
+    (FINDING_SEVERITIES as readonly string[]).includes(v.severity as string) &&
+    typeof v.file === "string" &&
+    typeof v.title === "string" &&
+    (v.line === undefined || typeof v.line === "number")
+  );
+}
+
+/** Structural check on a verdict read back from a stored record: the kind, a
+ *  string summary, an optional string head, findings each with an id, a known
+ *  severity, a file and a title. Shape only, no bounds — what a record carries
+ *  was validated by `parseVerdictInput` on the way in and redacted since. */
+export function isReviewVerdictShape(v: unknown): v is ReviewVerdict {
+  if (!isRecordLike(v)) return false;
+  if (!VERDICT_KINDS.includes(v.verdict as string) || typeof v.summary !== "string") return false;
+  if (v.head !== undefined && typeof v.head !== "string") return false;
+  if (v.findings !== undefined && !(Array.isArray(v.findings) && v.findings.every(isFindingShape))) return false;
+  return true;
+}
+
+/** Structural check on a disposition set read back from a stored record. */
+export function isFindingDispositionsShape(v: unknown): v is FindingDisposition[] {
+  return (
+    Array.isArray(v) &&
+    v.every(
+      (d) =>
+        isRecordLike(d) &&
+        typeof d.findingId === "string" &&
+        DISPOSITION_KINDS.includes(d.disposition as string) &&
+        typeof d.note === "string",
+    )
+  );
+}
+
+/** Every string leaf of the verdict through the redaction seam — the summary,
+ *  each finding's file and title — the input untouched: what the one record
+ *  assembly writes. `droppedFindings` are parse notes for the model and never
+ *  ride a record. */
+export function redactVerdict(v: ReviewVerdict, redact: (s: string) => string = redactSecrets): ReviewVerdict {
+  return {
+    verdict: v.verdict,
+    summary: redact(v.summary),
+    ...(v.head !== undefined ? { head: v.head } : {}),
+    ...(v.findings !== undefined
+      ? { findings: v.findings.map((f) => ({ ...f, file: redact(f.file), title: redact(f.title) })) }
+      : {}),
+  };
+}
+
+export function redactDispositions(
+  dispositions: readonly FindingDisposition[],
+  redact: (s: string) => string = redactSecrets,
+): FindingDisposition[] {
+  return dispositions.map((d) => ({ findingId: d.findingId, disposition: d.disposition, note: redact(d.note) }));
+}