@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/setup/history.ts

@@ -0,0 +1,443 @@
+// Review history, the companion's half (setup & scan spec "Review
+// history"). The VM prints a digest of what past reviews said
+// (`src/reviewhistory.ts`), the PC writes it into the state home
+// (`src/tui/historypull.ts`), and here the companion reads it and hands back
+// THEMES — the recurring things this team asks for in review, in the
+// companion's own words.
+//
+// The boundary this module exists for: the raw comments are colleagues' names
+// and words, and they never leave the state home. The companion may read them
+// (that is how it condenses), but what goes onward — to reviewer memory as
+// `#history` entries, and to the repo portrait through `readHistoryThemes` —
+// is only the validated theme list. A theme that quotes a raw comment (eight
+// words running) or names a comment's author is REFUSED, with the reason, so
+// the companion rewrites it; nothing is silently trimmed into something the
+// companion did not say. The quote check is a belt, not a proof: a paraphrase
+// close enough to be a quote in all but word order gets through, and the
+// companion's prompt carries the rule too.
+//
+// Persistence: `<state home>/setup/history-themes.json` — the saved themes and
+// the ones they replaced. Memory: a save RETIRES the earlier unpinned
+// `#history` entries and writes the new ones, so a re-run supersedes rather
+// than piles up (the survey's rule); a pinned, `#manual` or `source=manual` one is the
+// operator's and is left alone.
+import { dehash, parseEventTags, parseHashTags } from "../memory/eventtags.js";
+import { normalizeTag, refOf, type MemoryStore } from "../memory/store.js";
+import { parseDigest, type ReviewHistoryDigest } from "../reviewhistory.js";
+import type { StateFs } from "./engine.js";
+
+/** The digest's place in the state home — `historypull.ts` writes it here. */
+export const HISTORY_DIGEST_FILE = "setup/review-history.json";
+export const HISTORY_THEMES_FILE = "setup/history-themes.json";
+export const HISTORY_THEMES_VERSION = 1;
+export const HISTORY_TAG = "history";
+
+/** One save carries at most this many themes — the scan's pattern cap. */
+export const MAX_THEMES = 20;
+export const THEME_TITLE_MAX = 80;
+export const THEME_SUMMARY_MAX = 400;
+/** A theme sharing this many consecutive words with a raw comment quotes it. */
+export const QUOTE_WORDS = 8;
+/** A page of raw items the companion reads at a time. */
+export const HISTORY_PAGE_MAX = 200;
+
+export const THEME_SOURCES = ["human", "bot", "feedback", "mixed"] as const;
+export type ThemeSource = (typeof THEME_SOURCES)[number];
+
+export interface HistoryTheme {
+  title: string;
+  summary: string;
+  /** Which half of the history shows it: human reviewers, the daemon's own
+   * rounds, `[feedback]`, or more than one. */
+  source: ThemeSource;
+  /** How many items the companion counted behind it. */
+  weight: number;
+}
+
+export interface HistoryThemesFile {
+  version: number;
+  saved_at: string;
+  repo: string;
+  /** Which digest the themes were condensed from. */
+  digest_generated_at: string;
+  themes: HistoryTheme[];
+  previous: { saved_at: string; themes: HistoryTheme[] } | null;
+}
+
+export type DigestRead =
+  | { state: "absent" }
+  | { state: "unreadable"; error: string }
+  | { state: "ok"; digest: ReviewHistoryDigest };
+
+/** The digest in the state home, if there is one this version reads. */
+export function readDigest(fs: StateFs): DigestRead {
+  let text: string | null;
+  try {
+    text = fs.read(HISTORY_DIGEST_FILE);
+  } catch (err) {
+    return { state: "unreadable", error: `${HISTORY_DIGEST_FILE} cannot be read: ${String(err)}` };
+  }
+  if (text === null) return { state: "absent" };
+  const p = parseDigest(text);
+  return p.ok
+    ? { state: "ok", digest: p.digest }
+    : { state: "unreadable", error: `${HISTORY_DIGEST_FILE}: ${p.error}` };
+}
+
+// ---- the companion's view ----
+
+export const HISTORY_SECTIONS = ["human", "rounds", "feedback"] as const;
+export type HistorySection = (typeof HISTORY_SECTIONS)[number];
+
+export interface HistorySummary {
+  repo: string;
+  generated_at: string;
+  since: string;
+  months: number;
+  human_comments: number;
+  prs_scanned: number;
+  prs_enumerated: number;
+  truncated: boolean;
+  rounds: number;
+  feedback: number;
+  problems: string[];
+  /** Nothing in any half — a repo with no merged-PR reviews, rounds or feedback. */
+  empty: boolean;
+}
+
+export function summarize(d: ReviewHistoryDigest): HistorySummary {
+  return {
+    repo: d.repo,
+    generated_at: d.generated_at,
+    since: d.window.since,
+    months: d.window.months,
+    human_comments: d.human.comments.length,
+    prs_scanned: d.human.prs_scanned,
+    prs_enumerated: d.human.prs_enumerated,
+    truncated: d.human.truncated,
+    rounds: d.rounds.length,
+    feedback: d.feedback.length,
+    problems: d.problems,
+    empty: d.human.comments.length === 0 && d.rounds.length === 0 && d.feedback.length === 0,
+  };
+}
+
+/** One page of one half, rendered as lines the companion reads in context.
+ * Raw text, by design: this is the condensing step, inside the state home's
+ * boundary. */
+export function historyPage(
+  d: ReviewHistoryDigest,
+  section: HistorySection,
+  offset: number,
+  limit: number,
+): { total: number; offset: number; lines: string[] } {
+  const lim = Math.max(1, Math.min(HISTORY_PAGE_MAX, Math.floor(limit)));
+  const off = Math.max(0, Math.floor(offset));
+  const one = (s: string | null): string => (s ?? "").replace(/\s+/g, " ").trim();
+  let all: string[];
+  if (section === "human") {
+    all = d.human.comments.map(
+      (c) =>
+        `#${c.pr} ${c.kind}${c.path ? ` ${c.path}` : ""} [${c.state}] @${c.author}: ${one(c.body)}`,
+    );
+  } else if (section === "rounds") {
+    all = d.rounds.map(
+      (r) =>
+        `#${r.pr} round ${r.round_no}${r.backfilled ? " (imported)" : ""} ${r.verdict ?? "—"} ${r.finished_at ?? ""}: ${one(r.summary) || "(no summary)"}`,
+    );
+  } else {
+    all = d.feedback.map(
+      (f) =>
+        `#${f.pr} ${f.kind} ${f.created_at}${f.author ? ` @${f.author}` : ""}: ${one(f.body) || "(no text)"}`,
+    );
+  }
+  return { total: all.length, offset: off, lines: all.slice(off, off + lim) };
+}
+
+// ---- themes: validation and the leak belt ----
+
+export type ThemeRefusal = { ok: false; errors: string[] };
+
+const words = (t: string): string[] =>
+  t
+    .normalize("NFKC")
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}_]+/u)
+    .filter((w) => w !== "");
+
+/** The raw human text of a digest — what must not travel. Round summaries are
+ * the daemon's own prose, not a colleague's, and are not in here. */
+function rawTexts(d: ReviewHistoryDigest): string[] {
+  return [...d.human.comments.map((c) => c.body), ...d.feedback.map((f) => f.body ?? "")];
+}
+
+function authorsOf(d: ReviewHistoryDigest): Set<string> {
+  const out = new Set<string>();
+  for (const c of d.human.comments) out.add(c.author.toLowerCase());
+  for (const f of d.feedback) if (f.author) out.add(f.author.toLowerCase());
+  out.delete("");
+  return out;
+}
+
+/** Every window of QUOTE_WORDS consecutive words, joined by a space. */
+function* shinglesOf(w: readonly string[]): Generator<string> {
+  for (let i = 0; i + QUOTE_WORDS <= w.length; i++) yield w.slice(i, i + QUOTE_WORDS).join(" ");
+}
+
+/**
+ * What a theme's text gives away, or [] when it gives nothing: a run of
+ * QUOTE_WORDS words out of any raw comment, or a comment author's login —
+ * `@login` always, and the bare login when it cannot pass for an ordinary word
+ * (four characters or more, or carrying a digit or a hyphen).
+ */
+export function leakChecker(d: ReviewHistoryDigest): (text: string) => string[] {
+  const shingles = new Set<string>();
+  for (const raw of rawTexts(d)) for (const s of shinglesOf(words(raw))) shingles.add(s);
+  const authors = authorsOf(d);
+  return (text) => {
+    const out: string[] = [];
+    const tw = words(text);
+    for (const s of shinglesOf(tw)) {
+      if (shingles.has(s)) {
+        out.push(`quotes a raw review comment ("${s}…") — say it in your own words`);
+        break;
+      }
+    }
+    const lower = text.toLowerCase();
+    const tokens = new Set(lower.split(/[^a-z0-9_-]+/).filter(Boolean));
+    for (const login of authors) {
+      const distinctive = login.length >= 4 || /[\d-]/.test(login);
+      if (lower.includes(`@${login}`) || (distinctive && tokens.has(login))) {
+        out.push(`names a comment author (${login}) — themes are about the code, not who said it`);
+      }
+    }
+    return out;
+  };
+}
+
+/** One-shot form of `leakChecker`. */
+export function leaksIn(text: string, d: ReviewHistoryDigest): string[] {
+  return leakChecker(d)(text);
+}
+
+/** Strict: the companion's list, or every reason it is not one. */
+export function normalizeThemes(raw: unknown): { ok: true; themes: HistoryTheme[] } | ThemeRefusal {
+  if (!Array.isArray(raw))
+    return {
+      ok: false,
+      errors: ["`themes` must be an array (empty is allowed: an empty history has none)"],
+    };
+  const errors: string[] = [];
+  if (raw.length > MAX_THEMES)
+    errors.push(
+      `at most ${MAX_THEMES} themes per save (got ${raw.length}) — merge the smaller ones`,
+    );
+  const themes: HistoryTheme[] = [];
+  for (const [i, t] of raw.entries()) {
+    const o = (t ?? {}) as Record<string, unknown>;
+    const title = typeof o.title === "string" ? o.title.trim() : "";
+    const summary = typeof o.summary === "string" ? o.summary.trim() : "";
+    const source = o.source;
+    const weight =
+      typeof o.weight === "string" && /^\d+$/.test(o.weight) ? Number(o.weight) : o.weight;
+    const at = `themes[${i}]`;
+    if (title === "" || title.length > THEME_TITLE_MAX)
+      errors.push(`${at}.title must be 1..${THEME_TITLE_MAX} characters`);
+    if (summary === "" || summary.length > THEME_SUMMARY_MAX)
+      errors.push(`${at}.summary must be 1..${THEME_SUMMARY_MAX} characters`);
+    if (/[\r\n]/.test(title) || /[\r\n]/.test(summary))
+      errors.push(`${at}: one line each — no newlines`);
+    if (title.startsWith("#") || summary.startsWith("#"))
+      errors.push(`${at}: must not start with '#' (tags are the tool's to write)`);
+    if (typeof source !== "string" || !(THEME_SOURCES as readonly string[]).includes(source)) {
+      errors.push(`${at}.source must be one of ${THEME_SOURCES.join(" | ")}`);
+    }
+    if (typeof weight !== "number" || !Number.isInteger(weight) || weight < 1)
+      errors.push(`${at}.weight must be a positive integer (items behind it)`);
+    themes.push({ title, summary, source: source as ThemeSource, weight: weight as number });
+  }
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, themes };
+}
+
+/** The one memory entry text a theme becomes. The header is ours (`#history`
+ * then `k=v`), and the fixed word `Theme:` ends it, so nothing the companion
+ * wrote can extend the header into a tag (`src/memory/eventtags.ts`); its own
+ * `#word`s are de-hashed, so a theme about "our #manual notes" never reads as
+ * a manual entry to a whole-text tag reader. */
+export function themeEntryText(t: HistoryTheme): string {
+  return `#${HISTORY_TAG} source=${t.source} weight=${t.weight} Theme: ${dehash(`${t.title} — ${t.summary}`)}`;
+}
+
+// ---- save & read ----
+
+export interface MemoryOutcome {
+  written: number;
+  retired: number;
+  /** Why memory was not (fully) written — the themes are saved regardless. */
+  problems: string[];
+}
+
+export interface SaveThemesDeps {
+  state: StateFs;
+  memory: MemoryStore | null;
+  clock: () => Date;
+}
+
+export type SaveThemesResult =
+  { ok: true; themes: HistoryTheme[]; memory: MemoryOutcome } | ThemeRefusal;
+
+function readThemesFile(fs: StateFs): { file: HistoryThemesFile | null; error: string | null } {
+  let text: string | null;
+  try {
+    text = fs.read(HISTORY_THEMES_FILE);
+  } catch (err) {
+    return { file: null, error: `${HISTORY_THEMES_FILE} cannot be read: ${String(err)}` };
+  }
+  if (text === null) return { file: null, error: null };
+  try {
+    const f = JSON.parse(text) as HistoryThemesFile;
+    if (f.version !== HISTORY_THEMES_VERSION || !Array.isArray(f.themes))
+      throw new Error("not a themes file this version reads");
+    const n = normalizeThemes(f.themes);
+    if (!n.ok) throw new Error(n.errors.join("; "));
+    return { file: { ...f, themes: n.themes }, error: null };
+  } catch (err) {
+    return {
+      file: null,
+      error: `${HISTORY_THEMES_FILE}: ${String(err)} — nothing will overwrite it; move it aside to start over`,
+    };
+  }
+}
+
+/**
+ * Save the companion's themes: validated, checked against the digest they came
+ * from for anything raw, then written to the state home and — when this
+ * assembly has memory — to reviewer memory as `#history` entries, replacing
+ * the earlier unpinned ones. Refused outright when there is no digest to have
+ * condensed from, or a themes file this version cannot read is in the way.
+ */
+export async function saveHistoryThemes(
+  deps: SaveThemesDeps,
+  raw: unknown,
+): Promise<SaveThemesResult> {
+  const read = readDigest(deps.state);
+  if (read.state === "absent") {
+    return {
+      ok: false,
+      errors: [
+        "no review history digest in the state home yet — the owner runs `qcr history pull` to fetch one",
+      ],
+    };
+  }
+  if (read.state === "unreadable") return { ok: false, errors: [read.error] };
+  const n = normalizeThemes(raw);
+  if (!n.ok) return n;
+  const leaksOf = leakChecker(read.digest);
+  const leaks = n.themes.flatMap((t, i) =>
+    leaksOf(`${t.title} ${t.summary}`).map((l) => `themes[${i}] ${l}`),
+  );
+  if (leaks.length > 0) return { ok: false, errors: leaks };
+  const prior = readThemesFile(deps.state);
+  if (prior.error !== null) return { ok: false, errors: [prior.error] };
+
+  const file: HistoryThemesFile = {
+    version: HISTORY_THEMES_VERSION,
+    saved_at: deps.clock().toISOString(),
+    repo: read.digest.repo,
+    digest_generated_at: read.digest.generated_at,
+    themes: n.themes,
+    previous: prior.file ? { saved_at: prior.file.saved_at, themes: prior.file.themes } : null,
+  };
+  deps.state.write(HISTORY_THEMES_FILE, `${JSON.stringify(file, null, 2)}\n`);
+
+  const memory: MemoryOutcome = { written: 0, retired: 0, problems: [] };
+  if (deps.memory === null) {
+    memory.problems.push(
+      "no reviewer memory in this assembly — themes saved to the state home only",
+    );
+    return { ok: true, themes: n.themes, memory };
+  }
+  try {
+    // The store's `tags` scan the whole text (search wants a quoted `#tag`),
+    // but only the HEADER says what an entry is: a feedback comment reading
+    // "keep #history out of billing" is not an earlier theme to retire, and
+    // a theme that mentions "#manual" is not the owner's own entry.
+    const sweeper = deps.memory as MemoryStore & {
+      sweep?: () => Promise<{
+        entries: Awaited<ReturnType<MemoryStore["read"]>>;
+        unread: string[];
+      }>;
+    };
+    const snapshot = typeof sweeper.sweep === "function" ? await sweeper.sweep() : null;
+    const incomplete = snapshot !== null && snapshot.unread.length > 0;
+    if (incomplete)
+      memory.problems.push(
+        "earlier history themes UNKNOWN — memory enumeration is incomplete; supersession cannot be confirmed",
+      );
+    const old = (snapshot?.entries ?? (await deps.memory.search("", { tag: HISTORY_TAG }))).filter(
+      (e) => {
+        const header = parseHashTags(e.text).map(normalizeTag);
+        return (
+          header.includes(HISTORY_TAG) &&
+          !e.pinned &&
+          !header.includes("manual") &&
+          parseEventTags(e.text).source !== "manual"
+        );
+      },
+    );
+    // The new themes land BEFORE the old ones go: a write memory refuses (or
+    // a stop between the two) leaves the earlier themes live, never neither.
+    const retained = new Set<(typeof old)[number]>();
+    for (const t of n.themes) {
+      const text = themeEntryText(t);
+      const existing = old.find((e) => e.text === text);
+      if (existing) {
+        retained.add(existing);
+        memory.written++;
+        continue;
+      }
+      const r = await deps.memory.apply({ op: "note", text });
+      if (r.ok) memory.written++;
+      else memory.problems.push(`could not write "${t.title}": ${r.message}`);
+    }
+    if (incomplete || memory.written < n.themes.length) {
+      memory.problems.push(
+        `the earlier #${HISTORY_TAG} entries are kept — ${incomplete ? "earlier themes could not all be read" : "not every new theme was written"}; the next save replaces them`,
+      );
+    } else {
+      for (const e of old) {
+        if (retained.has(e)) continue;
+        const r = await deps.memory.apply({ op: "retire", ...refOf(e) });
+        if (r.ok) memory.retired++;
+        else
+          memory.problems.push(`could not retire an earlier #${HISTORY_TAG} entry: ${r.message}`);
+      }
+    }
+  } catch (err) {
+    memory.problems.push(`memory unreachable: ${String(err)}`);
+  }
+  return { ok: true, themes: n.themes, memory };
+}
+
+/**
+ * The saved themes — the ONLY thing about review history the repo portrait
+ * carries, never the digest (the portrait reads the digest only to
+ * check its narrative quotes none of it). Null when none are saved or the file
+ * cannot be read.
+ */
+export function readHistoryThemes(fs: StateFs): HistoryThemesFile | null {
+  return readThemesFile(fs).file;
+}
+
+/** `readHistoryThemes` with the two nulls told apart — the portrait records
+ * an unreadable themes file as UNKNOWN, never as "no themes yet". */
+export function historyThemesState(
+  fs: StateFs,
+):
+  | { state: "absent" }
+  | { state: "unreadable"; error: string }
+  | { state: "ok"; file: HistoryThemesFile } {
+  const r = readThemesFile(fs);
+  if (r.error !== null) return { state: "unreadable", error: r.error };
+  return r.file === null ? { state: "absent" } : { state: "ok", file: r.file };
+}

package/src/setup/interview.ts

@@ -0,0 +1,243 @@
+// The setup interview's deterministic half (setup & scan spec "Interview
+// mapping"). The companion runs the interview — adaptive, driven by
+// the repo portrait — and this file is what its answers MEAN: a fixed list of
+// concerns, a priority per concern, and one table in code that turns a
+// priority into lens settings. The same answers always produce the same
+// profile, and every setting can say which concern put it there.
+//
+// Four points every interview covers, whatever else it asks (FIXED_POINTS):
+// the project's goals (words, which become lens emphasis), what must block a
+// merge, the risk areas (security, data, money, compliance), and style &
+// tests. Every concern below belongs to one of the last three; the goals are
+// recorded as text. A profile write is refused until every concern has a
+// priority — that is how "covers the four points" is a property of the tool
+// rather than a hope about the conversation.
+//
+// The table owns four keys of `[lenses.<pass>]` (packages/pi-plugin/src/lenstuning.ts) — `enabled`,
+// `min_tier`, `effort`, `max_severity` — on every lens a concern names, and
+// nothing else: `emphasis` is the companion's words, `guide` is a drafted
+// style guide, and a lens no concern names is never touched. `normal` is the
+// shipped behaviour, so it CLEARS those four keys rather than writing them.
+// A lens two concerns share takes the HIGHER priority of the two: switching
+// one concern off never switches off a lens another concern still wants.
+//
+// Pure — no port, no clock, no disk.
+import type { LensTuning } from "@quickchatai/pi-quickreview/src/lenstuning.js";
+
+/** The four points every setup interview covers. */
+export const FIXED_POINTS = [
+  {
+    name: "goals",
+    question: "What is this project for, and what does a good change to it look like?",
+  },
+  { name: "merge-blocking", question: "What must stop a pull request from merging?" },
+  { name: "risk", question: "Which risk areas matter here — security, data, money, compliance?" },
+  { name: "style-tests", question: "How much do code style and tests matter in review?" },
+] as const;
+
+export type FixedPoint = (typeof FIXED_POINTS)[number]["name"];
+
+/** How much one concern matters to this repo, highest first. */
+export const PRIORITIES = ["critical", "important", "normal", "ignore"] as const;
+export type Priority = (typeof PRIORITIES)[number];
+
+/** The keys of `[lenses.<pass>]` the table owns. */
+export const TABLE_KEYS = ["enabled", "min_tier", "effort", "max_severity"] as const;
+export type TableSettings = Pick<LensTuning, (typeof TABLE_KEYS)[number]>;
+
+/**
+ * THE table: a priority → the lens settings it means.
+ *
+ *   critical  — on, at the strongest tier, at the model's ceiling, and able
+ *               to block (`P0` lifts every cap the lens would otherwise carry);
+ *   important — on (a lens a `[review]` lever gates runs anyway), never below
+ *               the mid tier, at medium effort; its own severity cap stands;
+ *   normal    — nothing: the shipped behaviour (and a re-tune back to normal
+ *               clears whatever an earlier answer wrote);
+ *   ignore    — off: not planned, not addable, not paid for.
+ */
+export const PRIORITY_SETTINGS: Readonly<Record<Priority, Readonly<TableSettings>>> = {
+  critical: {
+    enabled: true,
+    min_tier: "sol-high",
+    effort: "high",
+    max_severity: "P0",
+  },
+  important: { enabled: true, min_tier: "sol-med", effort: "medium" },
+  normal: {},
+  ignore: { enabled: false },
+};
+
+export interface Concern {
+  name: string;
+  point: Exclude<FixedPoint, "goals">;
+  title: string;
+  /** The lenses whose settings this concern's priority decides. */
+  lenses: readonly string[];
+}
+
+/**
+ * The concerns, and the lenses each one decides. Neither the validator
+ * (`pass-validate` — a profile may switch it off by hand, the interview never
+ * does), `pass-intent` (its question/nit cap is fixed by design) nor
+ * `pass-ask-human` is here.
+ */
+export const CONCERNS: readonly Concern[] = [
+  {
+    name: "correctness",
+    point: "merge-blocking",
+    title: "Correctness — logic bugs, broken invariants, local slips",
+    lenses: ["pass-baseline", "pass-widened", "pass-sweep"],
+  },
+  {
+    name: "reliability",
+    point: "merge-blocking",
+    title: "Production reliability — behaviour changes, many pods, queued work",
+    lenses: ["pass-prod-risk", "pass-statelessness", "pass-deferred"],
+  },
+  {
+    name: "compatibility",
+    point: "merge-blocking",
+    title: "Deploy-window compatibility — old and new code running together",
+    lenses: ["pass-backcompat", "pass-rollout"],
+  },
+  {
+    name: "integrations",
+    point: "merge-blocking",
+    title: "External contracts — provider payloads and their semantics",
+    lenses: ["pass-contracts"],
+  },
+  {
+    name: "frontend",
+    point: "merge-blocking",
+    title: "Frontend state — effects, mutations, async UI",
+    lenses: ["pass-ui"],
+  },
+  {
+    name: "design",
+    point: "merge-blocking",
+    title: "Design — placement, simplicity, abstraction, duplication, consistency",
+    lenses: [
+      "pass-placement",
+      "pass-simplicity",
+      "pass-abstraction",
+      "pass-maintainability",
+      "pass-duplication",
+      "pass-consistency",
+    ],
+  },
+  {
+    name: "security",
+    point: "risk",
+    title: "Security — authz, injection, tenant isolation, trust bounds",
+    lenses: ["pass-security", "pass-bounds"],
+  },
+  {
+    name: "data",
+    point: "risk",
+    title: "Data safety — migrations, backfills, persisted bytes",
+    lenses: ["pass-data-safety", "pass-roundtrip"],
+  },
+  {
+    name: "money",
+    point: "risk",
+    title: "Money — payments and billing: double charges, lost events, races",
+    lenses: ["pass-contracts", "pass-delivery", "pass-concurrency"],
+  },
+  {
+    name: "compliance",
+    point: "risk",
+    title: "Compliance — personal data, audit trails, retention",
+    lenses: ["pass-security", "pass-data-safety"],
+  },
+  {
+    name: "style",
+    point: "style-tests",
+    title: "Code style — against a written guide",
+    lenses: ["pass-style"],
+  },
+  {
+    name: "tests",
+    point: "style-tests",
+    title: "Tests — what the change breaks, what its tests really test",
+    lenses: ["pass-tests"],
+  },
+];
+
+export const CONCERN_NAMES: readonly string[] = CONCERNS.map((c) => c.name);
+
+export type Priorities = Readonly<Record<string, Priority>>;
+
+/** Higher wins: `PRIORITIES` is highest first. */
+const rankOf = (p: Priority): number => PRIORITIES.length - PRIORITIES.indexOf(p);
+
+/** Read a `{concern: priority}` object the companion sent. Unknown concerns
+ * and unknown priorities are refused by name; a missing concern is not an
+ * error here (the write decides whether the set is complete). */
+export function parsePriorities(
+  raw: unknown,
+): { ok: true; priorities: Record<string, Priority> } | { ok: false; errors: string[] } {
+  if (raw === undefined || raw === null) return { ok: true, priorities: {} };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, errors: ["`priorities` must be an object of {concern: priority}"] };
+  }
+  const errors: string[] = [];
+  const out: Record<string, Priority> = {};
+  for (const [concern, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!CONCERN_NAMES.includes(concern)) {
+      errors.push(`unknown concern "${concern}" — one of: ${CONCERN_NAMES.join(", ")}`);
+      continue;
+    }
+    const p = typeof value === "string" ? value.trim().toLowerCase() : value;
+    if (!(PRIORITIES as readonly unknown[]).includes(p)) {
+      errors.push(
+        `${concern}: priority must be one of ${PRIORITIES.join(", ")}, got ${JSON.stringify(value)}`,
+      );
+      continue;
+    }
+    out[concern] = p as Priority;
+  }
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, priorities: out };
+}
+
+/** The concerns `priorities` does not answer yet, in table order. */
+export function unansweredConcerns(priorities: Priorities): string[] {
+  return CONCERN_NAMES.filter((c) => priorities[c] === undefined);
+}
+
+/** One lens's settings as the table decides them, and why. */
+export interface LensDecision {
+  lens: string;
+  priority: Priority;
+  /** The concern(s) at that priority that decided it. */
+  because: string[];
+  settings: TableSettings;
+}
+
+/**
+ * The table applied: every lens any concern names, at the highest priority
+ * among the concerns naming it, with that priority's settings. Only concerns
+ * present in `priorities` count; a lens none of them names is absent.
+ * Deterministic (lens name order).
+ */
+export function lensDecisions(priorities: Priorities): LensDecision[] {
+  const best = new Map<string, { priority: Priority; because: string[] }>();
+  for (const concern of CONCERNS) {
+    const p = priorities[concern.name];
+    if (p === undefined) continue;
+    for (const lens of concern.lenses) {
+      const cur = best.get(lens);
+      if (!cur || rankOf(p) > rankOf(cur.priority))
+        best.set(lens, { priority: p, because: [concern.name] });
+      else if (rankOf(p) === rankOf(cur.priority)) cur.because.push(concern.name);
+    }
+  }
+  return [...best.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([lens, { priority, because }]) => ({
+      lens,
+      priority,
+      because,
+      settings: { ...PRIORITY_SETTINGS[priority] },
+    }));
+}