@codedology/code-forge 0.8.0 → 0.10.0

package/src/review/reopen.mjs

@@ -0,0 +1,256 @@
+/**
+ * B72 (issues #12, #15): `block reopen <id> --file <path> --run <r> --reason <text>` — the human
+ * restarts the review of a file the fix loop STOPPED (any reason: `review_cap`,
+ * `l3_patch_exhausted`, `split_required`, …) or whose state is LOST (B68). Only a stopped file
+ * needs content that differs from what its stop reviewed; a lost file restarts on its current
+ * content.
+ *
+ * Human-only like `block waive`: the verb is on `CODER_ONLY_FORBIDDEN` (`src/util/forbidden.mjs`)
+ * and its row is signed with the run key, `by: human` (`block waive` has no other in-verb guard,
+ * so neither has this). The verb (`reopenFile`) refuses, writing no row, with a stable code:
+ *  - `usage` (exit 2) — no `--file`, no `--reason`, or a path with a control character or that is
+ *    not a normalised repo-root-relative path (`checkFileForm`, shared with `block waive`);
+ *  - `unknown_block` — the run does not know the block (the code `block waive` uses);
+ *  - `reopen-block-not-open` — the block is not open (stopped or closed);
+ *  - `reopen-not-owned` — the block does not own the file;
+ *  - `reopen-tampered` — the file's state does not verify (an integrity failure stays a security
+ *    event; the owner's exit is `block close --no-require-reviews`);
+ *  - `reopen-not-stopped` — no state, or a state that is open or complete;
+ *  - `reopen-same-content` — a stopped file whose current content is the content its stop
+ *    reviewed (no free re-roll: the human waives the findings instead), or a stop whose content
+ *    is unknown;
+ *  - `reopen-already-recorded` — a verified human row already names the file's latest anchor seq
+ *    for other content (run `review-file`, or the content changed since that reopen);
+ *  - `reopen-write-failed` — the signed row was not written.
+ * Accepted, it first drops the done marker of the current content's ticket (C11, `io.clearDone`),
+ * then writes ONE signed `review.reopened {block, file, from: stopped|lost, stop_reason, at_seq,
+ * from_hash, to_hash, reason, by: human}` row (`at_seq` = the file's latest anchor seq). There is
+ * at most one verified human row per `at_seq`: a retry on the same content finds it and writes
+ * none.
+ *
+ * The content a stop reviewed (`stopContentHash`) is the stopped state's `stop_content_hash`,
+ * which the worker sets on every stop (`src/worker/engine.mjs`) and which is signed through the
+ * anchor. A state from before B72 has none: then the latest verified `review.cap` row of THIS
+ * stop counts — written after the file's latest verified `review.reopened` row, with the state's
+ * round and stop reason — else the content is unknown and the reopen is refused.
+ *
+ * The worker (`fixLoopRound`) asks `reopenRowFor`: a verified human row of this run for the block
+ * and file whose `at_seq` is the file's latest anchor seq starts a new state (round 1, a FULL
+ * review, `reviewed_content` null, the level from the run record, `l3_rung_used` kept). The new
+ * state saves at `at_seq + 1`, so a row works once. For `stopped` the content must still differ
+ * from the stop's content; else the stop repeats.
+ *
+ * This file imports nothing from `src/worker/`: the fix-loop state is read through `io`.
+ */
+import { StateError } from '../state/paths.mjs';
+import { verifyRow } from '../state/signer.mjs';
+import { checkFileForm } from './verb-forms.mjs';
+
+export const REOPENED_EVENT = 'review.reopened';
+
+/** A code a refusal may name: an errno (`EACCES`), a StateError code (`ledger-locked`), a name. */
+const CAUSE_CODE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+
+/**
+ * B79: the code a failed write names — the error's `code`, else its `name`, when it has the form
+ * {@link CAUSE_CODE}, else `unknown` (a thrown `undefined` or `null` too). Called only for a
+ * write that threw; one that wrote nothing is named `no-write` by its caller. Never the message:
+ * it may hold a path or a value.
+ * @param {unknown} err @returns {string}
+ */
+function causeCode(err) {
+  if (err === null || err === undefined) return 'unknown';
+  const e = /** @type {{code?: unknown, name?: unknown}} */ (err);
+  if (typeof e.code === 'string' && CAUSE_CODE.test(e.code)) return e.code;
+  if (typeof e.name === 'string' && CAUSE_CODE.test(e.name)) return e.name;
+  return 'unknown';
+}
+
+/**
+ * Whether a row's MAC verifies with the run key (a throw is a no).
+ * @param {Record<string, any>} row @param {Buffer} key
+ */
+function verified(row, key) {
+  try {
+    return verifyRow(row, key).ok === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The content hash the stop of a stopped state reviewed, or null when it is unknown: the state's
+ * `stop_content_hash`; for a state from before B72, the latest verified `review.cap` row of this
+ * run for the block and file that belongs to this stop (after the file's latest verified
+ * `review.reopened` row, with the state's round and stop reason).
+ * @param {Record<string, any> | null} state
+ * @param {ReadonlyArray<Record<string, any>>} rows
+ * @param {{runId: string, block: string, file: string, key: Buffer}} at
+ * @returns {string | null}
+ */
+export function stopContentHash(state, rows, { runId, block, file, key }) {
+  if (state?.status !== 'stopped') return null;
+  if (typeof state.stop_content_hash === 'string' && state.stop_content_hash.length > 0) return state.stop_content_hash;
+  const mine = (/** @type {Record<string, any>} */ r) => r?.run === runId && r.block === block && r.file === file && verified(r, key);
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const r = rows[i];
+    if (r?.event === REOPENED_EVENT && mine(r)) return null;
+    if (r?.event !== 'review.cap' || !mine(r)) continue;
+    if (typeof r.content_hash !== 'string' || r.round !== state.round || r.reason !== state.next?.reason) return null;
+    return r.content_hash;
+  }
+  return null;
+}
+
+/**
+ * The block checks every reopen runs first, before any config, key or ledger read: the run must
+ * know the block (`unknown_block`, the code `block waive` uses) and the block must be open.
+ * @param {Record<string, any>} record @param {string} runId @param {string} id
+ * @returns {Record<string, any>} the block's entry.
+ * @throws {StateError} `unknown_block` or `reopen-block-not-open`.
+ */
+export function openBlockEntry(record, runId, id) {
+  const entry = record.blocks?.[id];
+  if (!entry) throw new StateError('unknown_block', `block ${id} is not in run ${runId}`);
+  if (entry.status !== 'open') throw new StateError('reopen-block-not-open', `reopen-block-not-open: block ${id} is not open in run ${runId}; nothing was recorded`);
+  return entry;
+}
+
+/**
+ * The latest verified human `review.reopened` row of this run for the block and file whose
+ * `at_seq` is `seq`, or null.
+ * @param {ReadonlyArray<Record<string, any>>} rows
+ * @param {{runId: string, block: string, file: string, key: Buffer, seq: number}} at
+ * @returns {Record<string, any> | null}
+ */
+function latestRowAt(rows, { runId, block, file, key, seq }) {
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const r = rows[i];
+    if (r?.event !== REOPENED_EVENT || r.run !== runId || r.block !== block || r.file !== file) continue;
+    if (r.by !== 'human' || r.at_seq !== seq || !verified(r, key)) continue;
+    return r;
+  }
+  return null;
+}
+
+/**
+ * Worker side: the `review.reopened` row that restarts this file now, or null. Only a row whose MAC
+ * verifies with the run key, of this run, block and file, `by: human`, and whose `at_seq` is the
+ * file's latest anchor seq counts (the latest such row). A `lost` state needs `from: lost`; a
+ * stopped state needs `from: stopped` AND current content that is neither the row's `from_hash`
+ * nor the content the stop reviewed (`stopContentHash`; unknown ⇒ no restart).
+ * @param {ReadonlyArray<Record<string, any>>} rows
+ * @param {{runId: string, block: string, file: string, key: Buffer, status: string, state: Record<string, any> | null, seq: number, contentHash: string}} at
+ * @returns {Record<string, any> | null}
+ */
+export function reopenRowFor(rows, { runId, block, file, key, status, state, seq, contentHash }) {
+  const row = latestRowAt(rows, { runId, block, file, key, seq });
+  if (row === null) return null;
+  if (status === 'lost') return row.from === 'lost' ? row : null;
+  if ((status === 'ok' || status === 'restored') && state?.status === 'stopped' && row.from === 'stopped') {
+    const stopHash = stopContentHash(state, rows, { runId, block, file, key });
+    if (stopHash === null || contentHash === stopHash || contentHash === row.from_hash) return null;
+    return row;
+  }
+  return null;
+}
+
+/**
+ * The verb (`block reopen`): check, drop the done marker (`io.clearDone`), then write the signed
+ * row — or return the verified human row an earlier try wrote for the same `at_seq` and `to_hash`
+ * (at most one row per `at_seq`: one for other content is refused `reopen-already-recorded`).
+ * @param {{
+ *   runId: string, id: string, file: unknown, reason: unknown,
+ *   record: Record<string, any>, rows: ReadonlyArray<Record<string, any>>, key: Buffer,
+ *   writeRow: (row: Record<string, any>) => Promise<unknown>,
+ *   writeSigned: (runId: string, writeRow: (row: Record<string, any>) => Promise<unknown>, row: Record<string, any>) => Promise<unknown>,
+ *   io: {
+ *     owns: (owned: ReadonlyArray<string>, file: string, kinds?: Readonly<Record<string, string>>) => boolean,
+ *     loadState: (where: Record<string, any>) => {status: string, state: Record<string, any> | null, seq: number},
+ *     contentHash: (file: string) => string,
+ *     clearDone: (file: string) => boolean,
+ *   },
+ * }} opts
+ * @returns {Promise<{row: Record<string, any>, cleared: boolean, existing: boolean}>}
+ * @throws {StateError} `usage` or a refusal code (see the module doc).
+ */
+export async function reopenFile({ runId, id, file, reason, record, rows, key, writeRow, writeSigned, io }) {
+  if (typeof file !== 'string' || file.length === 0) throw new StateError('usage', 'block reopen needs --file <path>');
+  if (typeof reason !== 'string' || reason.trim().length === 0) throw new StateError('usage', 'block reopen needs --reason');
+  checkFileForm(file, { normalized: true });
+  const entry = openBlockEntry(record, runId, id);
+  const owned = Array.isArray(entry.owned_files) ? entry.owned_files : [];
+  if (!io.owns(owned, file, entry.owned_kinds)) throw new StateError('reopen-not-owned', `reopen-not-owned: block ${id} does not own ${file}; nothing was recorded`);
+
+  const runRows = rows.filter((r) => r?.run === runId);
+  const loaded = io.loadState({ runId, block: id, file, key, rows: runRows });
+  if (loaded.status === 'tampered') {
+    throw new StateError('reopen-tampered', `reopen-tampered: the review state of ${file} does not verify (a security event, not a stop); the owner's way out is block close --no-require-reviews; nothing was recorded`);
+  }
+  const current = io.contentHash(file);
+  /** @type {'stopped' | 'lost'} */
+  let from;
+  /** @type {string | null} */
+  let stopReason = null;
+  /** @type {string | null} */
+  let fromHash = null;
+  if (loaded.status === 'lost') {
+    from = 'lost';
+  } else if ((loaded.status === 'ok' || loaded.status === 'restored') && loaded.state?.status === 'stopped') {
+    from = 'stopped';
+    stopReason = typeof loaded.state.next?.reason === 'string' ? loaded.state.next.reason : 'stopped';
+    fromHash = stopContentHash(loaded.state, runRows, { runId, block: id, file, key });
+    if (fromHash === null) {
+      throw new StateError('reopen-same-content', `reopen-same-content: the content the stop of ${file} reviewed is unknown, so a change cannot be shown; waive its findings instead (block waive); nothing was recorded`);
+    }
+    if (fromHash === current) {
+      throw new StateError('reopen-same-content', `reopen-same-content: ${file} still has the content its stop (${stopReason}) reviewed; change the file first, or waive its findings (block waive); nothing was recorded`);
+    }
+  } else {
+    const what = loaded.status === 'none' || loaded.state === null ? 'has no review state' : `is ${loaded.state.status}`;
+    throw new StateError('reopen-not-stopped', `reopen-not-stopped: ${file} ${what}; only a stopped or lost file is reopened; nothing was recorded`);
+  }
+  if (!Number.isInteger(loaded.seq) || loaded.seq < 0) {
+    throw new StateError('reopen-tampered', `reopen-tampered: the review state of ${file} has no valid anchor seq; nothing was recorded`);
+  }
+  // one verified human row per at_seq: the same content reuses it, other content is refused
+  const earlier = latestRowAt(runRows, { runId, block: id, file, key, seq: loaded.seq });
+  if (earlier !== null && earlier.to_hash !== current) {
+    throw new StateError('reopen-already-recorded', `reopen-already-recorded: ${file} was already reopened at state seq ${loaded.seq} for other content; run review-file, or the content changed since the reopen; nothing was recorded`);
+  }
+  // C11: the cached result of the current content's ticket would repeat the stop — dropped FIRST,
+  // so a failed row write leaves at worst a re-run that returns the same stop, never a row with a
+  // stale marker
+  const cleared = io.clearDone(file);
+  if (earlier !== null) return { row: earlier, cleared, existing: true };
+  const row = { event: REOPENED_EVENT, block: id, file, from, stop_reason: stopReason, at_seq: loaded.seq, from_hash: fromHash, to_hash: current, reason: reason.trim(), by: 'human' };
+  /** @type {Record<string, any> | null} */
+  let written = null;
+  let signedOut = null;
+  /** @type {unknown} */
+  let failure = null;
+  // a thrown `undefined` (or null) is still a throw: `threw`, not the value, says the write threw
+  let threw = false;
+  try {
+    signedOut = await writeSigned(runId, async (signed) => {
+      const result = await writeRow(signed);
+      // the ledger's appendRow resolves with the row it wrote; nothing (or false) is no write
+      if (result === null || result === undefined || result === false) return result;
+      written = signed;
+      return result;
+    }, row);
+  } catch (err) {
+    written = null;
+    failure = err;
+    threw = true;
+  }
+  if (written === null || signedOut === null || signedOut === undefined || signedOut === false) {
+    // B79: the cause is kept (`cause`) and named by its code only — never a path, key or config value
+    const refused = new StateError('reopen-write-failed', `reopen-write-failed: the signed review.reopened row for ${file} was not written (${threw ? causeCode(failure) : 'no-write'}); run block reopen again`);
+    // StateError takes (code, message) only (src/state/paths.mjs is not this block's): `cause` is
+    // set here, non-enumerable like a native one, so a serializer never emits the cause's path
+    if (threw) Object.defineProperty(refused, 'cause', { value: failure, enumerable: false, configurable: true, writable: true });
+    throw refused;
+  }
+  return { row: written, cleared, existing: false };
+}

package/src/review/route.mjs

@@ -0,0 +1,232 @@
+/**
+ * Size-based review routing (block B90): `review.routes` sends a big file to a named model with
+ * its own session timeout and its own second level, with no `.code-forge.yml` edit and no reload.
+ *
+ * A rule is `{min_lines, level?, model, provider?, effort?, fallback?, session_timeout_s?, second?}`.
+ * `level` is the level it replaces (`L2` default, or `L3`, the judge). The worker picks the route
+ * once per ticket, before any session, from the line count of the file's content in the reviewed
+ * tree (the bytes it hashed). A deleted file has no content and is never routed. Among the rules
+ * of one level, the one with the largest `min_lines` that is at most the count wins.
+ *
+ * The routed ticket runs with a derived config: `levels.<level>` = the rule's model entry
+ * (`model`, `provider`, `effort`, `fallback`; with no `provider` the top-level one, like any level
+ * entry), `review.second_levels.<level>` = `second` when given — except an L2 rule while
+ * `review.multimodel` is on: the consensus second reviewer is `review.second_levels.L2`, so it is
+ * kept. The timeout is ONE value for every session of the ticket: the largest `session_timeout_s`
+ * among the matched rules that set one, else the unrouted timeout (`review.session_timeout_s`).
+ *
+ * No `review.routes` (or no rule that matches) leaves the config object itself untouched. Pure:
+ * no I/O; the worker (`src/worker/loop.mjs`) reads the bytes, writes the signed `review.route` row
+ * and pins the timeout. This module never imports `src/worker`.
+ */
+
+import { resolveLevel } from '../config/known-ids.mjs';
+
+/** The levels a rule may replace: the reviewers (L2) and the judge (L3). */
+export const ROUTE_LEVELS = Object.freeze(['L2', 'L3']);
+
+/** The level a rule replaces when it names none. */
+export const DEFAULT_ROUTE_LEVEL = 'L2';
+
+/** The keys of a rule that form the routed level entry (`$defs/level`). */
+const ENTRY_KEYS = Object.freeze(['model', 'provider', 'effort', 'fallback']);
+
+/** A route list that cannot be used: the ticket is `unavailable` with this code, never reviewed on another model. */
+export class RouteError extends Error {
+  constructor() {
+    super('review.routes is not a list of valid rules');
+    this.code = 'route-invalid';
+  }
+}
+
+/**
+ * The number of lines of a file's content: its newline bytes, plus one for a last line with no
+ * newline. Counted on the bytes, never on decoded text. `null` (a deleted file) and an empty file
+ * have 0 lines.
+ * @param {Buffer | null} bytes @returns {number}
+ */
+export function countLines(bytes) {
+  if (bytes === null || bytes.length === 0) return 0;
+  let n = 0;
+  for (let at = bytes.indexOf(0x0a); at !== -1; at = bytes.indexOf(0x0a, at + 1)) n += 1;
+  return bytes[bytes.length - 1] === 0x0a ? n : n + 1;
+}
+
+/** @param {unknown} v @returns {v is Record<string, any>} */
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** @param {unknown} v @returns {boolean} */
+const isPositiveInt = (v) => Number.isInteger(v) && /** @type {number} */ (v) >= 1;
+
+/** @param {unknown} v @returns {boolean} a non-empty string. */
+const isText = (v) => typeof v === 'string' && v.length > 0;
+
+/** @param {unknown} v @returns {boolean} absent, or a string (the schema's `effort`/`provider` types). */
+const optString = (v) => v === undefined || typeof v === 'string';
+
+/**
+ * A fallback item (`$defs/level` fallback): an object with a model and a provider, and an
+ * `effort` string when present.
+ * @param {unknown} v @returns {boolean}
+ */
+const isFallbackItem = (v) => isObject(v) && isText(v.model) && isText(v.provider) && optString(v.effort);
+
+/**
+ * A `$defs/level`-shaped entry: a model string, `provider` and `effort` strings when present, and
+ * `fallback` (when present) a list of fallback items. Used for a rule and for its `second`.
+ * @param {unknown} v @returns {boolean}
+ */
+function isEntry(v) {
+  if (!isObject(v) || !isText(v.model) || !optString(v.provider) || !optString(v.effort)) return false;
+  return v.fallback === undefined || (Array.isArray(v.fallback) && v.fallback.every(isFallbackItem));
+}
+
+/**
+ * Is `rule` usable? The schema and config rule 18 refuse everything else at `run start` and
+ * `run reload`; this guards a snapshot that never went through them.
+ * @param {unknown} rule @returns {boolean}
+ */
+function usable(rule) {
+  if (!isEntry(rule)) return false;
+  const r = /** @type {Record<string, any>} */ (rule);
+  if (!Number.isInteger(r.min_lines) || r.min_lines < 0) return false;
+  if (r.level !== undefined && !ROUTE_LEVELS.includes(r.level)) return false;
+  if (r.session_timeout_s !== undefined && !isPositiveInt(r.session_timeout_s)) return false;
+  if (r.second !== undefined && !isEntry(r.second)) return false;
+  return true;
+}
+
+/** @param {Record<string, any>} rule @returns {Record<string, any>} the level entry a rule routes to. */
+function entryOf(rule) {
+  /** @type {Record<string, any>} */
+  const entry = {};
+  for (const key of ENTRY_KEYS) if (rule[key] !== undefined) entry[key] = rule[key];
+  return entry;
+}
+
+/**
+ * The provider a rule's routed level runs on — the one place it is decided, shared with config
+ * validation (rules 16 and 18) so the two cannot drift: the rule's entry REPLACES
+ * `levels.<level>`, so a rule with no `provider` inherits the top-level `provider` (never the
+ * replaced level's own `provider`), resolved exactly as the spawner resolves any level.
+ * @param {Record<string, any> | null | undefined} cfg @param {Record<string, any>} rule
+ * @returns {string | undefined} undefined when the routed level cannot be resolved.
+ */
+export function ruleProvider(cfg, rule) {
+  const level = rule?.level ?? DEFAULT_ROUTE_LEVEL;
+  const levels = { ...(isObject(cfg?.levels) ? cfg?.levels : {}), [level]: isObject(rule) ? entryOf(rule) : {} };
+  try {
+    return resolveLevel({ ...(cfg ?? {}), levels }, /** @type {any} */ (level)).provider;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The rules of `cfg.review.routes`: `[]` when the key is absent or null.
+ * @param {Record<string, any> | null | undefined} cfg
+ * @returns {Array<Record<string, any>>}
+ * @throws {RouteError} the key is set but is not a list of usable rules.
+ */
+export function routeRules(cfg) {
+  const routes = cfg?.review?.routes;
+  if (routes === undefined || routes === null) return [];
+  if (!Array.isArray(routes) || !routes.every(usable)) throw new RouteError();
+  // config rule 18 refuses the same level and min_lines twice; a snapshot that skipped it fails
+  // closed here rather than letting list order pick the rule
+  const seen = new Set(routes.map((r) => `${r.level ?? DEFAULT_ROUTE_LEVEL}\0${r.min_lines}`));
+  if (seen.size !== routes.length) throw new RouteError();
+  return routes;
+}
+
+/**
+ * The winning rule per level for a file of `lines` lines: among the rules of a level, the largest
+ * `min_lines` that is at most `lines`. A deleted file (`deleted: true`) is never routed.
+ * @param {Record<string, any> | null | undefined} cfg @param {number} lines - a non-negative integer.
+ * @param {{deleted?: boolean}} [opts]
+ * @returns {Array<{level: string, rule: Record<string, any>}>} in `ROUTE_LEVELS` order; `[]` ⇒ no route.
+ * @throws {RouteError}
+ */
+export function pickRoutes(cfg, lines, { deleted = false } = {}) {
+  const rules = routeRules(cfg);
+  // a count that is not a line count never picks (or skips) a route: fail closed
+  if (!Number.isInteger(lines) || lines < 0) throw new RouteError();
+  if (deleted || rules.length === 0) return [];
+  /** @type {Array<{level: string, rule: Record<string, any>}>} */
+  const out = [];
+  for (const level of ROUTE_LEVELS) {
+    let best = null;
+    for (const rule of rules) {
+      if ((rule.level ?? DEFAULT_ROUTE_LEVEL) !== level || rule.min_lines > lines) continue;
+      if (best === null || rule.min_lines > best.min_lines) best = rule;
+    }
+    if (best !== null) out.push({ level, rule: best });
+  }
+  return out;
+}
+
+/**
+ * @typedef {object} RoutedTicket
+ * @property {Record<string, any>} cfg - the config every session of the ticket runs with; the SAME
+ *   object as the input when nothing is routed.
+ * @property {number} timeoutS - the session timeout of every session of the ticket.
+ * @property {Array<Record<string, any>>} rows - one `review.route` row body per routed level
+ *   (`{event, level, min_lines, lines, provider, model, session_timeout_s, second_model}`), unsigned.
+ */
+
+/**
+ * The ticket's routed config, timeout and `review.route` rows.
+ * @param {Record<string, any>} cfg - the ticket's config snapshot.
+ * @param {{lines: number, deleted?: boolean, timeoutS: number}} file - `timeoutS`: the unrouted timeout.
+ * @returns {RoutedTicket}
+ * @throws {RouteError}
+ */
+export function routeTicket(cfg, { lines, deleted = false, timeoutS }) {
+  const picked = pickRoutes(cfg, lines, { deleted });
+  if (picked.length === 0) return { cfg, timeoutS, rows: [] };
+  const given = picked.map(({ rule }) => rule.session_timeout_s).filter((t) => t !== undefined);
+  const routedTimeout = given.length > 0 ? Math.max(...given) : timeoutS;
+  const levels = { ...(isObject(cfg.levels) ? cfg.levels : {}) };
+  const review = { ...(isObject(cfg.review) ? cfg.review : {}) };
+  /** @type {Record<string, any>} */
+  const seconds = { ...(isObject(review.second_levels) ? review.second_levels : {}) };
+  let secondsChanged = false;
+  /** @type {Array<{level: string, rule: Record<string, any>, second: boolean}>} */
+  const applied = [];
+  for (const { level, rule } of picked) {
+    levels[level] = entryOf(rule);
+    // the consensus second reviewer is `second_levels.L2`: an L2 rule never replaces it then
+    const second = rule.second !== undefined && !(level === 'L2' && review.multimodel === true);
+    if (second) {
+      seconds[level] = rule.second;
+      secondsChanged = true;
+    }
+    applied.push({ level, rule, second });
+  }
+  if (secondsChanged) review.second_levels = seconds;
+  const routed = { ...cfg, levels, review };
+  const rows = applied.map(({ level, rule, second }) => ({
+    event: 'review.route',
+    level,
+    min_lines: rule.min_lines,
+    lines,
+    provider: providerOf(cfg, rule),
+    model: rule.model,
+    session_timeout_s: routedTimeout,
+    second_model: second ? rule.second.model : null,
+  }));
+  return { cfg: routed, timeoutS: routedTimeout, rows };
+}
+
+/**
+ * The provider the routed level resolves to — the one its sessions spawn on (`ruleProvider`).
+ * @param {Record<string, any>} cfg - the unrouted snapshot. @param {Record<string, any>} rule
+ * @returns {string}
+ * @throws {RouteError} the routed level cannot be resolved (e.g. no provider anywhere): the ticket
+ *   is `route-invalid`, never a row with no provider.
+ */
+function providerOf(cfg, rule) {
+  const provider = ruleProvider(cfg, rule);
+  if (provider === undefined) throw new RouteError();
+  return provider;
+}