@codedology/code-forge 0.7.1 → 0.7.3

package/src/review/schema-fallback.mjs

@@ -0,0 +1,351 @@
+/**
+ * The second-level retry after repeated `schema` misses on ONE packet (block B55, issue #2).
+ *
+ * Field data: one L2 reviewer model answered `unavailable: schema` four times in a row on the same
+ * packet (round 1, its retry, a patch_check recheck, a fresh review), while the model configured in
+ * `review.second_levels.L2` reviewed that packet cleanly on its first try.
+ *
+ * What counts as "2 schema failures on the same packet": a stub-guard verdict `schema` from a
+ * session of the level's OWN ladder (never one from a second-level try) on the same packet — the
+ * same run, file, content hash and exact packet text (`packet_hash`, sha256 of the text) — at the
+ * same level and role (one level's misses or mark never count for, or block, another's). Every
+ * such miss leaves one signed `review.schema_invalid` row; the count is those rows (read through
+ * `history`, which only counts rows whose MAC verifies) plus the miss in hand. In practice: the
+ * round's first session is miss 1; the worker's existing retry of that round (`next: retry`, the
+ * next ticket re-runs the SAME packet) is miss 2, and that ticket then tries the second level once.
+ * A session that times out is retried first by `session-retry.mjs` and counts once, with its last
+ * result; a `needs_file` round or a Markdown section is another packet text, so another count, and
+ * so is a recheck whose pending set changed between tries (S1 `resolved` closed another finding,
+ * so the open-findings list differs): a different packet starts its own count, by design.
+ *
+ * The rows written here carry no `run`, `file` or `content_hash`: the worker's `writeRow` stamps
+ * them (`worker/loop.mjs`: `{...row, block, file, content_hash: ticket.content_hash}`, signed with
+ * the run key), and the worker's history reads them back by the same ticket values — so outside
+ * the worker (no history) nothing is ever tried.
+ *
+ * At most ONCE per packet: a signed `review.schema_fallback` row is written BEFORE the second level
+ * is spawned, and any such row for the packet (whatever its outcome) stops every later try; when
+ * that row cannot be written nothing is spawned. The second level is `review.second_levels.<level>`
+ * only — nothing is tried without one; when every model of it is the one that just failed, the
+ * mark says `refused: same-model` and nothing is spawned. The try goes through the same `spawn` as
+ * any session, so the budget gate (`budget.usd`, B33) refuses it like any other (its own
+ * `budget.refused` row; the review is `unavailable: budget`). For a closed-book role every Codex
+ * model of the second level (its own and its ladder) is dropped unless
+ * `review.allow_open_book_codex`; when none is left the mark says `refused: closed-book` and
+ * nothing is spawned — the spawner's own refusal stays as it was. Its answer goes
+ * through the same stub guard; a valid one is a normal answer, a failed one leaves the file
+ * unavailable as before.
+ *
+ * Every schema miss (second-level ones included) is logged as `review.schema_invalid {lens, role,
+ * level, provider, model, fallback_step, packet_hash, second_level, ...diagnosis}` — a STRUCTURAL
+ * diagnosis of the answer, never its text ({@link diagnoseAnswer}): its size and kind, for JSON the
+ * top-level keys with their JSON types and the finding-schema errors (path, keyword, a few
+ * schema-side params, Ajv's message), for non-JSON the kind of parse error and its byte offset.
+ * Text a model copies from the packet into a JSON string can never reach the ledger this way.
+ *
+ * Concurrency: the worker never runs two tickets for one (block, file) at once (its file lock,
+ * `worker/loop.mjs`), and round 1, its retry, every recheck and the patch_check of a file are all
+ * tickets for that file, so one packet's history is read and written by one ticket at a time. The
+ * read-history → write-mark section here also runs under an in-process lock per (packet hash,
+ * level, role), so even the same file in two blocks cannot take a packet's one try twice.
+ *
+ * No ledger writer (`writeRow` absent) ⇒ nothing is logged and nothing is tried. The helpers never
+ * throw: a history that cannot be read disables the try (with one warning line), and a
+ * second-level spawn that throws is a session with no result (`exit`) after its mark row.
+ */
+
+import { createHash } from 'node:crypto';
+import { closedBookRefused, openBookCodexAllowed } from '../config/closed-book.mjs';
+import { resolveLevel } from '../config/known-ids.mjs';
+import { logWarning } from '../util/error-log.mjs';
+import { keyedLock } from '../util/locks.mjs';
+import { schemaErrorsOf } from './validate-review.mjs';
+
+/** Schema misses of the level's own ladder on one packet before the second level is tried. */
+export const SCHEMA_FAILURES_BEFORE_FALLBACK = 2;
+
+/** At most this many schema errors are kept in a diagnosis (`errors_total` has the full count). */
+export const DIAGNOSIS_MAX_ERRORS = 20;
+/** At most this many top-level keys are kept in a diagnosis (the rest counted in `other_keys`). */
+export const DIAGNOSIS_MAX_KEYS = 30;
+/** Ajv's message, and a parse error, are kept up to this length. */
+const MESSAGE_MAX = 120;
+/** A key or path segment is shown only when it is this plain; any other is `*` (it could be content). */
+const PLAIN_KEY = /^[A-Za-z0-9_.-]{1,40}$/;
+/** The Ajv params kept: they come from the schema, never from the answer's data. */
+const KEPT_PARAMS = Object.freeze(['missingProperty', 'additionalProperty', 'type', 'limit', 'comparison', 'format']);
+
+/**
+ * @typedef {(packetHash: string, who: {level: string, role: string}) => Promise<{failures: number, fellBack: boolean}>} SchemaHistory -
+ *   the signed history of ONE packet (`packetHash`) at one level and role in this run for this
+ *   file at this content hash: `failures` = `review.schema_invalid` rows of the level's own ladder
+ *   (`second_level` not true), `fellBack` = a `review.schema_fallback` row exists. Built by the
+ *   worker; absent ⇒ no second-level try.
+ */
+
+/** @param {string} text @returns {string} the packet's identity: sha256 hex of its exact text. */
+export function packetHash(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+/** @param {unknown} v @returns {string} the JSON type of `v`. */
+function jsonType(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (typeof v === 'number') return Number.isInteger(v) ? 'integer' : 'number';
+  return typeof v;
+}
+
+/** @param {unknown} key @returns {string} the key when plain (or an array index), else `*`. */
+function plainKey(key) {
+  if (typeof key === 'number') return String(key);
+  return typeof key === 'string' && PLAIN_KEY.test(key) ? key : '*';
+}
+
+/** @param {string} pointer @returns {string} the JSON pointer with every non-plain segment as `*`. */
+function plainPath(pointer) {
+  if (pointer === '') return '';
+  const segments = pointer.slice(1).split('/').map((seg) => (/^\d+$/.test(seg) ? seg : plainKey(seg.replace(/~1/g, '/').replace(/~0/g, '~'))));
+  return `/${segments.join('/')}`;
+}
+
+/**
+ * A parse error without any of the text: V8 quotes the input after a `"` and names the bad
+ * character, so the message is cut at its first quote, the token and the line/column dropped.
+ * @param {string} message @returns {string}
+ */
+function plainParseError(message) {
+  const cut = message
+    .split('"')[0]
+    .replace(/Unexpected token '.*?'/, 'Unexpected token')
+    .replace(/\s*\(line \d+ column \d+\)/, '')
+    .replace(/[,\s]+$/, '');
+  return cut.slice(0, MESSAGE_MAX);
+}
+
+/**
+ * The structural diagnosis of a schema miss (B55) — never the answer's text: `answer_bytes`,
+ * `answer_kind` (`json`, `not-json`, `empty`); for JSON `top_type`, `top_keys` (plain keys ⇒ their
+ * JSON type, at most {@link DIAGNOSIS_MAX_KEYS}; any other key only counted in `other_keys`),
+ * `schema_errors` (at most {@link DIAGNOSIS_MAX_ERRORS}, from the stub guard's own validator:
+ * `path` with non-plain segments as `*`, `keyword`, the schema-side `params`, Ajv's `message` ≤ 120
+ * chars) and `errors_total`; for non-JSON `parse_error` (V8's message cut before any quoted input)
+ * and `parse_offset` (bytes; null when V8 gives no position).
+ * @param {Record<string, any> | null} res - the session result (`text`, else `answer`).
+ * @returns {Record<string, any>}
+ */
+export function diagnoseAnswer(res) {
+  const text = typeof res?.text === 'string' && res.text.length > 0 ? res.text : typeof res?.answer === 'string' ? res.answer : '';
+  const answer_bytes = Buffer.byteLength(text);
+  /** @type {unknown} */
+  let value = res?.answer !== undefined && res?.answer !== null && typeof res.answer !== 'string' ? res.answer : undefined;
+  if (value === undefined) {
+    if (text.trim().length === 0) return { answer_bytes, answer_kind: 'empty' };
+    try {
+      value = JSON.parse(text);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const at = /at position (\d+)/.exec(message);
+      const parse_offset = at ? Buffer.byteLength(text.slice(0, Number(at[1]))) : /end of JSON input/.test(message) ? answer_bytes : null;
+      return { answer_bytes, answer_kind: 'not-json', parse_error: plainParseError(message), parse_offset };
+    }
+  }
+  /** @type {Record<string, string>} */
+  const top_keys = {};
+  let other_keys = 0;
+  if (jsonType(value) === 'object') {
+    for (const [k, v] of Object.entries(/** @type {Record<string, unknown>} */ (value))) {
+      if (PLAIN_KEY.test(k) && k !== '__proto__' && Object.keys(top_keys).length < DIAGNOSIS_MAX_KEYS) top_keys[k] = jsonType(v);
+      else other_keys += 1;
+    }
+  }
+  const errors = schemaErrorsOf(value);
+  const schema_errors = errors.slice(0, DIAGNOSIS_MAX_ERRORS).map((e) => {
+    /** @type {Record<string, unknown>} */
+    const given = e.params ?? {};
+    /** @type {Record<string, unknown>} */
+    const params = {};
+    for (const name of KEPT_PARAMS) {
+      const v = given[name];
+      if (v === undefined) continue;
+      if (name === 'missingProperty' || name === 'additionalProperty') params[name] = plainKey(v);
+      else if (typeof v === 'number' || typeof v === 'string') params[name] = v;
+      else if (Array.isArray(v)) params[name] = v.filter((x) => typeof x === 'string');
+    }
+    return { path: plainPath(e.instancePath ?? ''), keyword: e.keyword, params, message: String(e.message ?? '').slice(0, MESSAGE_MAX) };
+  });
+  return { answer_bytes, answer_kind: 'json', top_type: jsonType(value), top_keys, other_keys, schema_errors, errors_total: errors.length };
+}
+
+/**
+ * The config a second-level try runs with: `levels.<level>` replaced by
+ * `review.second_levels.<level>`. Every model of that level — its own, then its fallback ladder —
+ * gets its effective provider (the entry's own, else the level's: its `provider`, else
+ * `review.second_provider`, else the top-level one), and every one equal to the model that just
+ * failed is dropped; for a closed-book `role` every model Codex cannot run closed-book is dropped
+ * too (unless `review.allow_open_book_codex`). The first one left runs, the rest are its ladder.
+ * `ok: false` with `no-second-level` when none is configured for the level, `same-model` when
+ * nothing but the failed model is configured, `closed-book` when only refused models are left.
+ * @param {Record<string, any>} cfg @param {string} level
+ * @param {{provider: string | null, model: string | null}} from - the model that missed.
+ * @param {string} [role] - the session's role (closed-book check); absent ⇒ no such check.
+ * @returns {{ok: true, cfg: Record<string, any>, provider: string, model: string} | {ok: false, reason: 'no-second-level' | 'same-model' | 'closed-book'}}
+ */
+export function secondLevelFor(cfg, level, from, role) {
+  const override = cfg?.review?.second_levels?.[level] ?? null;
+  if (!override || typeof override !== 'object' || typeof override.model !== 'string' || override.model.length === 0) return { ok: false, reason: 'no-second-level' };
+  const levelProvider = override.provider ?? cfg?.review?.second_provider ?? cfg?.provider;
+  if (typeof levelProvider !== 'string' || levelProvider.length === 0) return { ok: false, reason: 'no-second-level' };
+  const { fallback: ladder, effort: _effort, ...own } = override;
+  /** @type {Array<{provider: string, model: string, effort?: string}>} */
+  const models = [override, ...(Array.isArray(ladder) ? ladder : [])]
+    .filter((e) => e && typeof e === 'object' && typeof e.model === 'string' && e.model.length > 0)
+    .map((e) => ({ provider: typeof e.provider === 'string' && e.provider.length > 0 ? e.provider : levelProvider, model: e.model, ...(typeof e.effort === 'string' ? { effort: e.effort } : {}) }))
+    .filter((e) => !(e.provider === from.provider && e.model === from.model));
+  if (models.length === 0) return { ok: false, reason: 'same-model' };
+  const openBook = openBookCodexAllowed(cfg);
+  const runnable = role === undefined ? models : models.filter((e) => !closedBookRefused(e.provider, role, openBook));
+  if (runnable.length === 0) return { ok: false, reason: 'closed-book' };
+  const [first, ...rest] = runnable;
+  const entry = { ...own, provider: first.provider, model: first.model, ...(first.effort ? { effort: first.effort } : {}), fallback: rest };
+  const next = { ...cfg, levels: { ...cfg.levels, [level]: entry } };
+  try {
+    resolveLevel(next, /** @type {any} */ (level));
+  } catch {
+    return { ok: false, reason: 'no-second-level' };
+  }
+  return { ok: true, cfg: next, provider: first.provider, model: first.model };
+}
+
+/**
+ * Log a schema miss and, when it is the packet's second (see the module doc), try the second level
+ * once. Never throws (see the module doc).
+ * @param {object} p
+ * @param {Record<string, any> | null} p.res - the missed session's result.
+ * @param {{lens: string, role: string, level: string}} p.session
+ * @param {string} p.packetText - the exact packet the session read (still on disk for `spawnAt`).
+ * @param {Record<string, any>} p.cfg - the config the missed session ran with.
+ * @param {boolean} p.allowed - false where a second-level try is never made (consensus mode).
+ * @param {SchemaHistory | undefined} p.history
+ * @param {((row: Record<string, any>) => Promise<unknown>) | undefined} p.writeRow - throws on a
+ *   failed write; absent ⇒ nothing is logged or tried.
+ * @param {(cfg: Record<string, any>) => Promise<{res: Record<string, any> | null, attempts: number}>} p.spawnAt
+ *   - the same session on the same packet with another config (timeout retry included).
+ * @returns {Promise<{res: Record<string, any> | null, attempts: number, to: {level: string, provider: string, model: string}} | null>}
+ *   the second level's result, or null when none was spawned.
+ */
+export async function afterSchemaMiss({ res, session, packetText, cfg, allowed, history, writeRow, spawnAt }) {
+  if (!writeRow) return null;
+  const write = writeRow;
+  const hash = packetHash(packetText);
+  const from = { provider: typeof res?.provider === 'string' ? res.provider : null, model: typeof res?.model === 'string' ? res.model : null };
+  /** @type {{cfg: Record<string, any>, to: {level: string, provider: string, model: string}} | null} */
+  let go = null;
+  try {
+    go = await keyedLock(`schema-fallback\0${hash}\0${session.level}\0${session.role}`, async () => {
+      // the history is read BEFORE this miss is logged: failures = signed earlier misses + this one
+      let seen = null;
+      if (allowed && history) {
+        try {
+          seen = await history(hash, { level: session.level, role: session.role });
+        } catch {
+          seen = null; // unreadable history ⇒ no try (fail closed), one warning line
+          await logWarning({ warning: 'review_schema_history', message: 'the schema-miss history could not be read; no second-level try' }).catch(() => null);
+        }
+      }
+      try {
+        await write({ event: 'review.schema_invalid', lens: session.lens, role: session.role, level: session.level, ...from, fallback_step: res?.fallback_step ?? 0, packet_hash: hash, second_level: false, ...diagnoseAnswer(res) });
+      } catch {
+        // the log is best-effort; the count then misses this one (fewer tries, never more)
+      }
+      if (!seen || seen.fellBack || seen.failures + 1 < SCHEMA_FAILURES_BEFORE_FALLBACK) return null;
+      const second = secondLevelFor(cfg, session.level, from, session.role);
+      const to = `review.second_levels.${session.level}`;
+      /** @type {string | null} */
+      let refused = null;
+      if (second.ok === false) {
+        if (second.reason === 'no-second-level') return null;
+        refused = second.reason; // `same-model` or `closed-book`: nothing of the level may run
+      }
+      await write({
+        event: 'review.schema_fallback',
+        lens: session.lens,
+        role: session.role,
+        level: session.level,
+        packet_hash: hash,
+        from_provider: from.provider,
+        from_model: from.model,
+        to,
+        to_provider: second.ok ? second.provider : null,
+        to_model: second.ok ? second.model : null,
+        attempts: seen.failures + 1,
+        ...(refused ? { refused } : {}),
+      }); // the once-per-packet mark: a failed write throws ⇒ no try
+      return !second.ok ? null : { cfg: second.cfg, to: { level: to, provider: second.provider, model: second.model } };
+    });
+  } catch {
+    return null;
+  }
+  if (!go) return null;
+  await logWarning({ warning: 'review_schema_fallback', message: 'a review answer failed the schema twice on one packet; the second level was tried once' }).catch(() => null);
+  try {
+    const out = await spawnAt(go.cfg);
+    return { res: out.res, attempts: out.attempts, to: go.to };
+  } catch {
+    // a throwing spawn is a session with no result: `exit` through the stub guard, never approval
+    return { res: null, attempts: 1, to: go.to };
+  }
+}
+
+/**
+ * Log a schema miss of the second-level try itself (never counted, never tried again).
+ * @param {{res: Record<string, any> | null, session: {lens: string, role: string, level: string}, packetText: string, writeRow: ((row: Record<string, any>) => Promise<unknown>) | undefined}} p
+ */
+export async function logSecondLevelMiss({ res, session, packetText, writeRow }) {
+  if (!writeRow) return;
+  try {
+    await writeRow({
+      event: 'review.schema_invalid',
+      lens: session.lens,
+      role: session.role,
+      level: session.level,
+      provider: typeof res?.provider === 'string' ? res.provider : null,
+      model: typeof res?.model === 'string' ? res.model : null,
+      fallback_step: res?.fallback_step ?? 0,
+      packet_hash: packetHash(packetText),
+      second_level: true,
+      ...diagnoseAnswer(res),
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * The worker's {@link SchemaHistory} over the run's ledger: for the packet, level and role asked
+ * about, rows of `runId` for `file` at `contentHash` with that `packet_hash`, `level` and `role`
+ * whose MAC verifies (`verify`; a row that does not verify, or whose check throws, counts for
+ * nothing). A miss on another packet of the same content, or at another level, never counts.
+ * @param {{readRows: () => Promise<Array<Record<string, any>>>, verify: (row: Record<string, any>) => boolean, runId: string, file: string, contentHash: string}} opts
+ * @returns {SchemaHistory}
+ */
+export function ledgerSchemaHistory({ readRows, verify, runId, file, contentHash }) {
+  return async (hash, who) => {
+    const rows = (await readRows()).filter((r) => r?.run === runId && r.file === file && r.content_hash === contentHash && r.packet_hash === hash && r.level === who.level && r.role === who.role);
+    let failures = 0;
+    let fellBack = false;
+    for (const r of rows) {
+      if (r.event !== 'review.schema_invalid' && r.event !== 'review.schema_fallback') continue;
+      let ok = false;
+      try {
+        ok = verify(r);
+      } catch {
+        ok = false;
+      }
+      if (!ok) continue;
+      if (r.event === 'review.schema_fallback') fellBack = true;
+      else if (r.second_level !== true) failures += 1;
+    }
+    return { failures, fellBack };
+  };
+}

package/src/review/sections.mjs

@@ -0,0 +1,282 @@
+/**
+ * Markdown section packets (block B54, issue #2 field note).
+ *
+ * A Markdown file (`.md`, `.markdown`) whose diff ALONE is over the packet budget
+ * (`split_required`) is reviewed section by section instead of refused:
+ *  1. the headings of the CURRENT file are found (`#`..`######`, ATX; a heading inside a fenced
+ *     code block — ``` or ~~~ — is not one);
+ *  2. every hunk is cut at each heading line it carries on its new side (a context or `+` line), so
+ *     a new or rewritten document — ONE hunk — splits too. Each piece is a valid unified-diff hunk
+ *     with its own header (`@@ -a,b +c,d @@`, real line numbers on both sides); a hunk that holds no
+ *     heading keeps its own header. A piece with no `+`/`-` line joins its neighbour;
+ *  3. the pieces are grouped by the nearest preceding heading (lines before the first heading are
+ *     one group), and consecutive groups are packed, in file order, into section packets whose
+ *     diff-only packet stays within the budget — splits happen only at headings.
+ * One group that alone is still over the budget ⇒ the file stays `split_required` (with that
+ * group's `tokensIn` and its heading): nothing is ever truncated. A diff with no hunk, or whose
+ * hunks do not parse one to one, never yields a section: it is `split_required` too — and so,
+ * fail-safe, is a deleted file or one with no heading whose diff is over the budget (one group). Any other file keeps
+ * `split_required`. Pure functions: no I/O.
+ */
+
+import { parseDiff, splitLines } from './context.mjs';
+
+/** @typedef {import('./packet.mjs').FileDiff} FileDiff */
+
+/** @param {string} file @returns {boolean} whether `file` is reviewed by section when over budget. */
+export const isMarkdownFile = (file) => /\.(md|markdown)$/i.test(file);
+
+/** A fence opener/closer: up to 3 spaces, then 3+ backticks or tildes. */
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+/** An ATX heading: up to 3 spaces, 1–6 `#`, then a space/tab or the end of the line. */
+const HEADING_RE = /^ {0,3}#{1,6}(?:[ \t]|$)/;
+/** A heading is named in results by its text, cut at this many characters. */
+const HEADING_MAX = 120;
+
+/**
+ * The ATX headings of `content`, outside fenced code blocks and outside a YAML front matter block.
+ * @param {string | null} content @returns {Map<number, string>} 1-based line ⇒ the heading line, trimmed.
+ */
+export function markdownHeadings(content) {
+  /** @type {Map<number, string>} */
+  const out = new Map();
+  /** @type {{char: string, len: number} | null} */
+  let fence = null;
+  const lines = splitLines(content).map((raw) => (raw.endsWith('\r') ? raw.slice(0, -1) : raw)); // a CRLF file matches like an LF one
+  // YAML front matter (`---` on line 1 … a closing `---` or `...`) holds no heading
+  const close = lines[0] === '---' ? lines.findIndex((l, i) => i > 0 && (l === '---' || l === '...')) : -1;
+  lines.forEach((line, i) => {
+    if (i <= close) return;
+    const f = FENCE_RE.exec(line);
+    if (fence) {
+      // a closing fence: the same character, at least as long, nothing after it
+      if (f && f[1][0] === fence.char && f[1].length >= fence.len && f[2].trim() === '') fence = null;
+      return;
+    }
+    // a backtick fence whose info string carries a backtick is inline code, not a fence
+    if (f && !(f[1][0] === '`' && f[2].includes('`'))) {
+      fence = { char: f[1][0], len: f[1].length };
+      return;
+    }
+    if (HEADING_RE.test(line)) out.set(i + 1, line.trim().slice(0, HEADING_MAX));
+  });
+  return out;
+}
+
+/**
+ * @typedef {object} Piece - one hunk, or one heading-bounded part of a hunk.
+ * @property {number} key - the line of the nearest preceding heading (0 = before the first).
+ * @property {string | null} header - the original header line when the piece is the whole hunk.
+ * @property {number} oldCursor - the first old-side line the piece covers.
+ * @property {number} newCursor - the first new-side line the piece covers.
+ * @property {string[]} lines - the body lines (` `, `+`, `-`, `\`).
+ */
+
+/** @param {Piece} p @returns {boolean} whether the piece changes anything. */
+const changes = (p) => p.lines.some((l) => l.startsWith('+') || l.startsWith('-'));
+
+/** @param {Map<number, string>} headings @param {number} line @returns {number} the last heading at or before `line`, else 0. */
+function headingAtOrBefore(headings, line) {
+  let best = 0;
+  for (const h of headings.keys()) if (h <= line && h > best) best = h;
+  return best;
+}
+
+/**
+ * Cut one hunk at the heading lines on its new side.
+ * @param {{header: string, oldStart: number, oldLines: number, newStart: number, newLines: number}} hunk
+ * @param {string} headerLine - the hunk's header line as git printed it.
+ * @param {string[]} body @param {Map<number, string>} headings
+ * @returns {Piece[]}
+ */
+function cutHunk(hunk, headerLine, body, headings) {
+  let oldCursor = hunk.oldLines === 0 ? hunk.oldStart + 1 : hunk.oldStart;
+  let newCursor = hunk.newLines === 0 ? hunk.newStart + 1 : hunk.newStart;
+  const firstNew = body.length > 0 && (body[0].startsWith(' ') || body[0].startsWith('+'));
+  /** @type {Piece[]} */
+  const pieces = [{ key: headingAtOrBefore(headings, firstNew ? newCursor : newCursor - 1), header: headerLine, oldCursor, newCursor, lines: [] }];
+  for (const line of body) {
+    const onNew = line.startsWith(' ') || line.startsWith('+');
+    const current = /** @type {Piece} */ (pieces.at(-1));
+    if (onNew && headings.has(newCursor) && current.lines.some((l) => !l.startsWith('\\'))) {
+      pieces.push({ key: newCursor, header: null, oldCursor, newCursor, lines: [] });
+    }
+    /** @type {Piece} */ (pieces.at(-1)).lines.push(line);
+    if (line.startsWith(' ')) {
+      oldCursor += 1;
+      newCursor += 1;
+    } else if (line.startsWith('+')) {
+      newCursor += 1;
+    } else if (line.startsWith('-')) {
+      oldCursor += 1;
+    }
+  }
+  if (pieces.length === 1) return pieces;
+  // a piece that only carries context joins the next piece (or, when last, the previous one)
+  for (let i = 0; i < pieces.length && pieces.length > 1; ) {
+    const p = pieces[i];
+    if (changes(p)) {
+      i += 1;
+      continue;
+    }
+    const next = pieces[i + 1];
+    if (next) pieces[i + 1] = { ...next, oldCursor: p.oldCursor, newCursor: p.newCursor, lines: [...p.lines, ...next.lines] };
+    else pieces[i - 1].lines.push(...p.lines);
+    pieces.splice(i, 1);
+  }
+  for (const p of pieces) p.header = null;
+  if (pieces.length === 1) pieces[0].header = headerLine;
+  return pieces;
+}
+
+/** @param {Piece} p @returns {string} the piece's header line. */
+function headerOf(p) {
+  if (p.header !== null) return p.header;
+  const oldCount = p.lines.filter((l) => l.startsWith(' ') || l.startsWith('-')).length;
+  const newCount = p.lines.filter((l) => l.startsWith(' ') || l.startsWith('+')).length;
+  // an empty side names the line BEFORE the change, as git does (`-0,0` for a new file)
+  return `@@ -${oldCount === 0 ? p.oldCursor - 1 : p.oldCursor},${oldCount} +${newCount === 0 ? p.newCursor - 1 : p.newCursor},${newCount} @@`;
+}
+
+/**
+ * @typedef {object} SectionGroup
+ * @property {number} key - the heading line (0 = before the first heading).
+ * @property {string} heading - the heading line, or `(before first heading)`.
+ * @property {FileDiff} diff - the group's own diff (the file header, then its pieces).
+ */
+
+/**
+ * Split a Markdown file's diff into heading groups (steps 1–3 of the module doc, before packing).
+ * @param {FileDiff} diff
+ * @returns {SectionGroup[] | null} in file order (one group when the file has no heading; none when
+ *   the diff has no hunk); null when the `@@` lines of the text do not match `diff.hunks` one to
+ *   one — a hunk is never dropped silently.
+ */
+export function sectionGroups(diff) {
+  const headings = markdownHeadings(diff.content);
+  const all = diff.diffText.split('\n');
+  if (all.at(-1) === '') all.pop();
+  const first = all.findIndex((l) => l.startsWith('@@'));
+  if (first < 0) return diff.hunks.length === 0 ? [] : null;
+  const fileHeader = all.slice(0, first);
+  /** @type {Piece[]} */
+  const pieces = [];
+  let h = 0;
+  for (let i = first; i < all.length; ) {
+    let end = i + 1;
+    while (end < all.length && !all[end].startsWith('@@')) end += 1;
+    const hunk = diff.hunks[h];
+    if (!hunk || !all[i].startsWith(hunk.header)) return null;
+    h += 1;
+    pieces.push(...cutHunk(hunk, all[i], all.slice(i + 1, end), headings));
+    i = end;
+  }
+  if (h !== diff.hunks.length) return null;
+  /** @type {Array<{key: number, pieces: Piece[]}>} */
+  const groups = [];
+  for (const p of pieces) {
+    const last = groups.at(-1);
+    if (last && last.key === p.key) last.pieces.push(p);
+    else groups.push({ key: p.key, pieces: [p] });
+  }
+  return groups.map((g) => ({ key: g.key, heading: headings.get(g.key) ?? '(before first heading)', diff: diffOf(diff, fileHeader, g.pieces) }));
+}
+
+/**
+ * @param {FileDiff} diff @param {string[]} fileHeader @param {Piece[]} pieces
+ * @returns {FileDiff} the pieces as one file diff (the hunk list re-parsed from its own text).
+ */
+function diffOf(diff, fileHeader, pieces) {
+  const diffText = `${[...fileHeader, ...pieces.flatMap((p) => [headerOf(p), ...p.lines])].join('\n')}\n`;
+  return { file: diff.file, kind: diff.kind, diffText, content: diff.content, ...parseDiff(diffText) };
+}
+
+/**
+ * @typedef {object} Section
+ * @property {number} index - 1-based, in file order.
+ * @property {string[]} headings - the headings the section covers.
+ * @property {number[]} keys - the heading lines of its groups (0 = before the first heading).
+ * @property {FileDiff} diff
+ */
+
+/**
+ * Pack the heading groups into section packets within `budget` (step 3 of the module doc). A
+ * candidate's size is `measure(its diff, its groups)` (a recheck adds the open findings it lists
+ * for those groups). Never `ok` with no section: a diff with no hunk, or one whose hunks do not
+ * parse one to one, is `split_required` at `measure(diff, [])` with `section: null`.
+ * @param {{diff: FileDiff, budget: number, measure: (diff: FileDiff, groups: SectionGroup[]) => number}} opts -
+ *   `measure`: the packet tokens of a candidate (the largest over the session lenses).
+ * @returns {{status: 'ok', sections: Section[]} | {status: 'split_required', tokensIn: number, budget: number, section: string | null}}
+ */
+export function packSections({ diff, budget, measure }) {
+  const groups = sectionGroups(diff);
+  if (groups === null || groups.length === 0) return { status: 'split_required', tokensIn: measure(diff, []), budget, section: null };
+  /** @param {SectionGroup[]} set */
+  const size = (set) => measure(merge(diff, set), set);
+  /** @type {Section[]} */
+  const sections = [];
+  /** @type {SectionGroup[]} */
+  let open = [];
+  const flush = () => {
+    if (open.length === 0) return;
+    sections.push({ index: sections.length + 1, headings: open.map((g) => g.heading), keys: open.map((g) => g.key), diff: merge(diff, open) });
+    open = [];
+  };
+  for (const g of groups) {
+    const alone = size([g]);
+    if (alone > budget) return { status: 'split_required', tokensIn: alone, budget, section: g.heading };
+    if (open.length > 0 && size([...open, g]) > budget) flush();
+    open.push(g);
+  }
+  flush();
+  return { status: 'ok', sections };
+}
+
+/**
+ * @param {FileDiff} diff @param {SectionGroup[]} groups @returns {FileDiff} the groups as one diff.
+ */
+function merge(diff, groups) {
+  if (groups.length === 1) return groups[0].diff;
+  const bodies = groups.map((g) => {
+    const text = g.diff.diffText;
+    return text.slice(text.startsWith('@@') ? 0 : text.indexOf('\n@@') + 1);
+  });
+  const head = groups[0].diff.diffText;
+  const fileHeader = head.startsWith('@@') ? '' : head.slice(0, head.indexOf('\n@@') + 1);
+  const diffText = `${fileHeader}${bodies.join('')}`;
+  return { file: diff.file, kind: diff.kind, diffText, content: diff.content, ...parseDiff(diffText) };
+}
+
+/**
+ * Where an open finding is listed in a sectioned recheck (each open finding in exactly ONE packet).
+ * Contract: with at least one section, always a valid position — the section whose hunks span the
+ * finding's first line, else the nearest section by line distance (ties go to the earlier one), so
+ * a finding outside every section (a late finding kept open by `review.late_findings: block`, a
+ * line that moved in the fix) still lands in one; -1 only when `sections` is empty.
+ * @param {ReadonlyArray<{diff: FileDiff}>} sections @param {{line_start: number}} finding
+ * @returns {number} the position in `sections`, or -1.
+ */
+export function sectionOf(sections, finding) {
+  let best = -1;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  sections.forEach((s, i) => {
+    const start = Math.min(...s.diff.hunks.map((h) => h.newStart));
+    const end = Math.max(...s.diff.hunks.map((h) => h.newStart + Math.max(h.newLines, 1) - 1));
+    const line = finding.line_start;
+    const distance = line < start ? start - line : line > end ? line - end : 0;
+    if (distance < bestDistance) {
+      best = i;
+      bestDistance = distance;
+    }
+  });
+  return best;
+}
+
+/**
+ * A section's findings with ids unique per file: `S<index>.<id>`.
+ * @template {{id: string}} F
+ * @param {ReadonlyArray<F>} findings @param {number} index @returns {F[]}
+ */
+export function sectionFindings(findings, index) {
+  return findings.map((f) => ({ ...f, id: `S${index}.${f.id}` }));
+}

package/src/review/validate-review.mjs

@@ -37,6 +37,17 @@ const validateSchema = (() => {
   return new Ajv2020({ allErrors: true, strict: false }).compile(body);
 })();
 
+/**
+ * The finding-schema errors of `value` from the SAME validator the stub guard uses (B55): Ajv's
+ * raw error objects, every one (`allErrors`). Callers must strip anything that can carry the
+ * answer's content (`review/schema-fallback.mjs`); this returns them as Ajv gives them.
+ * @param {unknown} value @returns {Array<import('ajv').ErrorObject>} empty when it validates.
+ */
+export function schemaErrorsOf(value) {
+  if (validateSchema(value) === true) return [];
+  return [...(validateSchema.errors ?? [])];
+}
+
 /** @param {Record<string, any> | undefined} cfg @returns {number} */
 export function minTokensOut(cfg) {
   const v = cfg?.review?.min_tokens_out;