visualproof 0.0.0-stage → 0.1.0

package/dist/shared/review.js

@@ -0,0 +1,642 @@
+// The review (ReviewSpec.md): reviewers' opinions on declarations, each bound to one version of
+// the declaration by its content hash, and the targets whose TCBs are being reviewed. What is
+// stored, how the review is read back from it, and what the page reads off it. No consensus is
+// decided here: a status is a summary of what reviewers said.
+//
+// What is stored (decided 2026-10-08): one append-only log per writer, each line one event — an
+// opinion, a target marked or taken off, a prefix trusted or no longer trusted, a key declaration
+// of a target marked or unmarked (ExportSpec decision 1) — carrying who wrote it and when. The
+// review is what replaying every log gives (`replay`): one writer's events in the order of their
+// file, different writers' by time. Each writer appends to a file of their own, so two never write
+// the same one. `ReviewData` is that replay, the state the server, the page and the agents' API
+// read; server/review.ts keeps the files.
+//
+// An agent's opinion is advice (AgentSpec decision 2): it is kept in the same list, marked
+// `agent`, and nothing that summarises the review reads it — `current`, and so every status, mark
+// and progress, is people's opinions only; `advice` is the agents'. Whatever else an agent does at
+// level full (AgentSpec decision 9) — a target, a prefix trusted, a key declaration — counts as a
+// person's would, and is marked `agent` too, so that the page always says it was an agent's. Every
+// line of an agent's log is marked, and no line of a person's.
+//
+// Someone invited by a personal link (CollabSpec decision 9, 2026-10-09) is the link, not a name:
+// their events go to one log named by the link's id, every line of it carrying the id (`person`)
+// beside the name it was written under, and a rename appends a `name` line. The replay keeps, per
+// id, the name its latest line gives (`people`), and shows everything that id wrote under it, so a
+// rename never makes a new writer, and the log needs nothing but itself to say who is who.
+//
+// An explanation of a declaration was an event too, until the owner removed explanations on
+// 2026-10-08 (ExportSpec decision 2): what a declaration is belongs in its docstring, and why a
+// reviewer thinks it right in their opinion's comment. So was a checkpoint of a target's review,
+// until the owner removed checkpoints on 2026-10-09 (ReviewSpec decision 4): an opinion goes stale
+// by itself when what it judged changes, what newly enters a TCB shows as not yet reviewed, the
+// timeline records each target's TCB changes, and the exported document records a target as it
+// stands at a build. A log may still hold such a line: the replay skips it (`readEvent`) without
+// calling it a problem, so that its writer writes on.
+//
+// Since 2026-10-09 a move (HistorySpec.md) carries what was said of one declaration to another, and
+// says where one is another renamed: shared/moves.ts replays it. Since 2026-10-11 the library's
+// files and the links into them are events too (AttachmentSpec.md): shared/library.ts replays them.
+//
+// Declarations are keyed by name, and a name can be anything Lean allows: `toString`,
+// `constructor`, even `__proto__`. Every object keyed by names here has no prototype (`byName`),
+// is read with Object.hasOwn, and is never spread or assigned into a plain object.
+import { applyLibrary, invalidLibrary, isLibraryOp, libraryEventOf, libraryFromJson, libraryNoChange, readLibraryEvent, renamePerson } from "./library.js";
+import { applyMove, moveIsIdle, readMove } from "./moves.js";
+export const DEFAULT_TRUSTED = ["Batteries", "Init", "Lean", "Mathlib", "Std"];
+/** The trusted entry that stands for everything outside the project, whatever its module (no Lean
+ *  name starts with "@", so it is no prefix of one). */
+export const OUTSIDE = "@external";
+/** A trusted entry as the page and the timeline show it. */
+export function prefixLabel(p) {
+    return p === OUTSIDE ? "the outside world" : p;
+}
+/** the longest text an opinion records, in UTF-16 units: far beyond any declaration a reviewer
+ *  reads, and small enough that a log stays a file people read */
+export const MAX_TEXT = 65536;
+export const STANDARD_AXIOMS = ["Classical.choice", "Quot.sound", "propext"];
+/** An object keyed by names: without a prototype, so that no name means something already. */
+export function byName() {
+    return Object.create(null);
+}
+export function emptyReview() {
+    return { version: 1, trusted: [...DEFAULT_TRUSTED], targets: byName(), opinions: byName(), keys: byName(), people: byName() };
+}
+/** A personal link's id (server/invites.ts): who someone invited by one is, in the review's logs. */
+export function validPersonId(s) {
+    return typeof s === "string" && /^[0-9a-f]{10}$/.test(s);
+}
+/** A prefix that can be trusted: a dotted Lean name, as a module or a namespace is written, and
+ *  short enough to read in a list. */
+export function validPrefix(s) {
+    if (s === OUTSIDE)
+        return true;
+    const part = "(?:[\\p{L}_][\\p{L}\\p{N}_'!?₀-₉ₐ-ₜ]*|«[^»\\n\\r]*»|[0-9]+)";
+    return typeof s === "string" && s.length <= 200 && new RegExp(`^${part}(?:\\.${part})*$`, "u").test(s);
+}
+/** A request is checked before anything is written: sizes are bounded, fields have the right
+ *  kinds. Returns the reason it is refused, or null. */
+export function invalid(r) {
+    if (!r || typeof r !== "object")
+        return "not an object";
+    const o = r;
+    const str = (v, max, optional = false) => v === undefined ? optional : typeof v === "string" && v.length > 0 && v.length <= max;
+    // trust names a prefix, a move two declarations; everything else one declaration
+    if (o.op === "trust") {
+        if (!validPrefix(o.prefix))
+            return "prefix";
+    }
+    else if (isLibraryOp(o.op)) {
+        // a file is named by its hash, a link by its id (shared/library.ts)
+    }
+    else if (o.op === "move") {
+        if (!str(o.from, 2000) || !str(o.to, 2000) || o.from === o.to)
+            return "a move is from one declaration to another";
+    }
+    else if (!str(o.name, 2000))
+        return "name";
+    if (!str(o.by, 120) || !o.by.trim())
+        return "reviewer";
+    // the server says whether the request came from an agent, from who asks, never the page; what
+    // an agent may record is its level's to say, checked where the request comes in
+    if (o.agent !== undefined && typeof o.agent !== "boolean")
+        return "agent";
+    if (o.person !== undefined && (!validPersonId(o.person) || o.agent))
+        return "person";
+    switch (o.op) {
+        case "opinion":
+            if (o.verdict !== "approve" && o.verdict !== "comment")
+                return "verdict";
+            if (!str(o.comment, 10000, true))
+                return "comment";
+            if (o.verdict === "comment" && !o.comment?.trim())
+                return "a comment needs text";
+            if (!str(o.hash, 64, true))
+                return "hash";
+            if (!str(o.text, MAX_TEXT, true))
+                return "text";
+            if (!str(o.statement, MAX_TEXT, true))
+                return "statement";
+            if (o.text !== undefined && o.statement !== undefined)
+                return "a text or a statement, not both";
+            return null;
+        case "target":
+            return typeof o.on === "boolean" ? null : "on";
+        case "trust":
+            return typeof o.on === "boolean" ? null : "on";
+        case "key":
+            if (!str(o.target, 2000))
+                return "target";
+            if (o.target === o.name)
+                return "a target is always key for itself";
+            return typeof o.on === "boolean" ? null : "on";
+        case "move":
+            if (o.rename !== undefined && typeof o.rename !== "boolean")
+                return "rename";
+            if (!str(o.auto, 200, true))
+                return "auto";
+            if (o.snap !== undefined && !(Number.isInteger(o.snap) && o.snap > 0))
+                return "snap";
+            return typeof o.on === "boolean" ? null : "on";
+        default:
+            return isLibraryOp(o.op) ? invalidLibrary(o) : "op";
+    }
+}
+/** The event that records a (checked) request, as it is appended to its writer's log;
+ *  `toolchain` and `now` come from the server. `d` is the review it is recorded on: a change of
+ *  mind on the same version and the same text does not repeat the text, so that a log grows by
+ *  the opinion alone. */
+export function eventOf(d, r, toolchain, now) {
+    const by = r.by.trim();
+    // an agent's event says so, whatever it is; so does one by someone invited by a personal link
+    const agent = r.agent ? { agent: true } : {};
+    const person = r.person ? { person: r.person } : {};
+    switch (r.op) {
+        case "opinion": {
+            const e = { op: "opinion", name: r.name, by, ...person, verdict: r.verdict, at: now, toolchain };
+            if (r.comment?.trim())
+                e.comment = r.comment.trim();
+            if (r.agent)
+                e.agent = true;
+            // the text matters only to an opinion that can go stale, one bound to a version
+            if (r.hash) {
+                e.hash = r.hash;
+                const was = (Object.hasOwn(d.opinions, r.name) ? d.opinions[r.name] : []).findLast((p) => author(p) === author(e));
+                const same = was?.hash === r.hash ? judgedOn(d, r.name, was) : null;
+                if (r.text !== undefined && !(same?.of === "source" && same.text === r.text))
+                    e.text = r.text;
+                else if (r.text === undefined && r.statement !== undefined && !(same?.of === "statement" && same.text === r.statement))
+                    e.statement = r.statement;
+            }
+            return e;
+        }
+        case "target":
+            return { op: "target", at: now, by, ...person, name: r.name, on: r.on, ...agent };
+        case "trust":
+            return { op: "trust", at: now, by, ...person, prefix: r.prefix, on: r.on, ...agent };
+        case "key":
+            return { op: "key", at: now, by, ...person, target: r.target, name: r.name, on: r.on, ...agent };
+        case "move":
+            return {
+                op: "move",
+                at: now,
+                by,
+                ...person,
+                from: r.from,
+                to: r.to,
+                on: r.on,
+                ...(r.rename ? { rename: true } : {}),
+                ...(r.auto ? { auto: r.auto } : {}),
+                ...(r.snap ? { snap: r.snap } : {}),
+                ...agent,
+            };
+        default:
+            return libraryEventOf(r, by, now, !!r.agent, r.person ?? null);
+    }
+}
+/** The line that says someone invited by a personal link goes by `name` from `now` on, appended to
+ *  their log when they rename themselves (server/review.ts, `named`). */
+export function nameEvent(person, name, now) {
+    return { op: "name", at: now, by: name.trim(), person };
+}
+/** One step of the replay: the review after `e`. Every page and the server take the same steps
+ *  in the same order, so they hold the same review. */
+export function applyEvent(d, e) {
+    // the name someone invited by a personal link goes by is the one their latest line gives: what
+    // they wrote before shows under it from now on
+    if (e.person)
+        named(d, e.person, e.by);
+    // who did it, where an agent did: the page marks it as an agent's
+    const agent = e.agent ? { agent: true } : {};
+    const person = e.person ? { person: e.person } : {};
+    switch (e.op) {
+        case "name":
+            return;
+        case "opinion": {
+            const { op: _op, name, ...o } = e;
+            (Object.hasOwn(d.opinions, name) ? d.opinions[name] : (d.opinions[name] = [])).push(o);
+            return;
+        }
+        case "target":
+            if (!e.on)
+                delete d.targets[e.name];
+            else if (!Object.hasOwn(d.targets, e.name))
+                d.targets[e.name] = { by: e.by, at: e.at, ...agent, ...person };
+            return;
+        case "trust": {
+            const rest = d.trusted.filter((p) => p !== e.prefix);
+            d.trusted = [...new Set(e.on ? [...rest, e.prefix] : rest)].sort();
+            return;
+        }
+        case "key": {
+            // the first mark stands (who marked it, and when) until it is taken off
+            const ks = Object.hasOwn(d.keys, e.target) ? d.keys[e.target] : null;
+            if (e.on) {
+                const m = ks ?? (d.keys[e.target] = byName());
+                if (!Object.hasOwn(m, e.name))
+                    m[e.name] = { by: e.by, at: e.at, ...agent, ...person };
+            }
+            else if (ks) {
+                delete ks[e.name];
+                if (!Object.keys(ks).length)
+                    delete d.keys[e.target];
+            }
+            return;
+        }
+        case "move":
+            applyMove(d, e);
+            return;
+        default:
+            applyLibrary(d, e);
+    }
+}
+/** Someone invited by a personal link goes by `name` now: what their id wrote shows under it, and
+ *  the name they went by before is kept among those they had. */
+function named(d, id, name) {
+    const p = Object.hasOwn(d.people, id) ? d.people[id] : null;
+    if (p?.name === name)
+        return;
+    if (!p) {
+        d.people[id] = { name, was: [] };
+        return;
+    }
+    p.was = [...p.was.filter((n) => n !== p.name && n !== name), p.name];
+    p.name = name;
+    for (const ops of Object.values(d.opinions))
+        for (const o of ops)
+            if (o.person === id)
+                o.by = name;
+    for (const t of Object.values(d.targets))
+        if (t.person === id)
+            t.by = name;
+    for (const marks of Object.values(d.keys))
+        for (const m of Object.values(marks))
+            if (m.person === id)
+                m.by = name;
+    renamePerson(d, id, name);
+}
+/** The opinion on `name` given at `at` by whoever is, or was, called `by`: what a quote of an
+ *  opinion (shared/comment.ts, `opinionRef`) names, which stays right once its writer, invited by a
+ *  personal link, renames themselves. */
+export function findOpinion(d, name, by, at) {
+    const was = (o) => !!o.person && Object.hasOwn(d.people, o.person) && d.people[o.person].was.includes(by);
+    return (Object.hasOwn(d.opinions, name) ? d.opinions[name] : []).find((o) => o.at === at && (o.by === by || was(o)));
+}
+/** Record a (checked) request on `d` at once: the event, applied. */
+export function record(d, r, toolchain, now) {
+    const e = eventOf(d, r, toolchain, now);
+    applyEvent(d, e);
+    return e;
+}
+/** Whether recording `r` would change nothing: a target marked that is one, a prefix trusted that
+ *  is, a key declaration marked that is. Such a request is answered, and nothing is appended. */
+export function noChange(d, r) {
+    if (r.op === "target")
+        return Object.hasOwn(d.targets, r.name) === r.on;
+    if (r.op === "trust")
+        return d.trusted.includes(r.prefix) === r.on;
+    if (r.op === "key")
+        return keyMarked(d, r.target, r.name) === r.on;
+    if (r.op === "move")
+        return moveIsIdle(d, { ...r, rename: r.rename || undefined });
+    if (isLibraryOp(r.op))
+        return libraryNoChange(d, r);
+    return false;
+}
+/** Events the review no longer records: an explanation (`explain`), removed by the owner on
+ *  2026-10-08, and a checkpoint of a target's review (`checkpoint`), removed on 2026-10-09. A line
+ *  of one in a log is skipped, whatever it holds. */
+const RETIRED_OPS = ["explain", "checkpoint"];
+/** A line of a log, read: the event it holds, or why it is not one; null for an event of a kind
+ *  the review no longer records (`RETIRED_OPS`), which is skipped — neither applied nor a problem,
+ *  so that an older log is read and its writer writes on. Only known fields are kept, in objects
+ *  of their own. Every line in an agent's log (`agentLog`) is marked as an agent's — its
+ *  opinions advice, its other events what it did at level full, which was checked when it was
+ *  written; a log read back from disk is replayed as written — and no line in a person's is.
+ *  Likewise every line in the log of someone invited by a personal link (`personLog`, the link's
+ *  id, from the file's name) carries that id, and no line elsewhere carries one; their `name` lines
+ *  are read there only. */
+export function readEvent(raw, agentLog, personLog = null) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return "not an event";
+    const o = raw;
+    if (RETIRED_OPS.includes(o.op))
+        return null;
+    const str = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
+    if (!str(o.at, 40) || !Number.isFinite(Date.parse(o.at)))
+        return "no time (at)";
+    if (!str(o.by, 120) || !o.by.trim())
+        return "no writer (by)";
+    const at = o.at, by = o.by;
+    if (agentLog ? o.agent !== true : o.agent !== undefined)
+        return agentLog ? "a line of an agent's log not marked as an agent's" : "an agent's line in a person's log";
+    if (personLog ? o.person !== personLog : o.person !== undefined)
+        return personLog ? "a line of an invited person's log without their id (person)" : "an invited person's line in another's log";
+    const agent = agentLog ? { agent: true } : {};
+    const person = personLog ? { person: personLog } : {};
+    switch (o.op) {
+        case "name":
+            return personLog ? { op: "name", at, by, person: personLog } : "a name line outside an invited person's log";
+        case "opinion": {
+            if (!str(o.name, 2000))
+                return "name";
+            if (o.verdict !== "approve" && o.verdict !== "comment")
+                return "verdict";
+            const e = { op: "opinion", name: o.name, by, ...person, verdict: o.verdict, at };
+            for (const [k, max] of [["comment", 10000], ["hash", 64], ["toolchain", 200], ["text", MAX_TEXT], ["statement", MAX_TEXT]]) {
+                if (o[k] === undefined)
+                    continue;
+                if (!str(o[k], max))
+                    return k;
+                e[k] = o[k];
+            }
+            if (e.text !== undefined && e.statement !== undefined)
+                return "a text and a statement";
+            if (agentLog)
+                e.agent = true;
+            return e;
+        }
+        case "target":
+            if (!str(o.name, 2000))
+                return "name";
+            return typeof o.on === "boolean" ? { op: "target", at, by, ...person, name: o.name, on: o.on, ...agent } : "on";
+        case "trust":
+            if (!validPrefix(o.prefix))
+                return "prefix";
+            return typeof o.on === "boolean" ? { op: "trust", at, by, ...person, prefix: o.prefix, on: o.on, ...agent } : "on";
+        case "key":
+            if (!str(o.name, 2000))
+                return "name";
+            if (!str(o.target, 2000))
+                return "target";
+            return typeof o.on === "boolean" ? { op: "key", at, by, ...person, target: o.target, name: o.name, on: o.on, ...agent } : "on";
+        case "move": {
+            const m = readMove(o, at, by, agentLog);
+            return typeof m === "string" ? m : { ...m, ...person };
+        }
+        default:
+            return isLibraryOp(o.op) ? readLibraryEvent(o, at, by, agentLog, personLog) : "op";
+    }
+}
+/** Every log merged into one sequence: one writer's events in the order of their file, different
+ *  writers' by time; at the same time, by file name (the same on every replica, so every server
+ *  replays the same). A writer's clock going backwards keeps their order and delays nobody else's
+ *  past their own. */
+export function merged(logs) {
+    const ls = [...logs].sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+    const time = ls.map((l) => l.events.map((e) => Date.parse(e.at)));
+    const next = ls.map(() => 0);
+    const out = [];
+    for (;;) {
+        let best = -1;
+        for (let k = 0; k < ls.length; k++)
+            if (next[k] < ls[k].events.length && (best < 0 || time[k][next[k]] < time[best][next[best]]))
+                best = k;
+        if (best < 0)
+            return out;
+        out.push({ file: ls[best].file, e: ls[best].events[next[best]++] });
+    }
+}
+/** The review every log gives. */
+export function replay(logs) {
+    const d = emptyReview();
+    for (const { e } of merged(logs))
+        applyEvent(d, e);
+    return d;
+}
+/** The review as JSON carried it (the server's answer, a snapshot): the same review, with its
+ *  objects keyed by names made again without a prototype. */
+export function reviewFromJson(raw) {
+    const d = emptyReview();
+    const r = (raw && typeof raw === "object" ? raw : {});
+    if (Array.isArray(r.trusted))
+        d.trusted = [...new Set(r.trusted.filter((t) => typeof t === "string"))].sort();
+    const own = (o) => (o && typeof o === "object" && !Array.isArray(o) ? Object.entries(o) : []);
+    const marks = (x) => ({ ...(x.agent === true ? { agent: true } : {}), ...(validPersonId(x.person) ? { person: x.person } : {}) });
+    const was = (x) => (Array.isArray(x.was) && x.was.every((w) => typeof w === "string") ? { was: x.was } : {});
+    for (const [name, t] of own(r.targets)) {
+        const x = t;
+        d.targets[name] = { by: String(x.by ?? ""), at: String(x.at ?? ""), ...marks(x), ...was(x) };
+    }
+    for (const [name, ops] of own(r.opinions))
+        if (Array.isArray(ops))
+            d.opinions[name] = ops.filter((o) => !!o && typeof o === "object");
+    for (const [target, ks] of own(r.keys)) {
+        const m = byName();
+        for (const [name, k] of own(ks)) {
+            const x = (k && typeof k === "object" ? k : {});
+            const wasOf = Array.isArray(x.wasOf) && x.wasOf.every((w) => typeof w === "string") ? { wasOf: x.wasOf } : {};
+            m[name] = { by: String(x.by ?? ""), at: String(x.at ?? ""), ...marks(x), ...was(x), ...wasOf };
+        }
+        if (Object.keys(m).length)
+            d.keys[target] = m;
+    }
+    for (const [id, p] of own(r.people)) {
+        const x = (p && typeof p === "object" ? p : {});
+        if (validPersonId(id) && typeof x.name === "string")
+            d.people[id] = { name: x.name, was: Array.isArray(x.was) ? x.was.filter((n) => typeof n === "string") : [] };
+    }
+    const renamed = own(r.renamed).filter(([, v]) => typeof v === "string");
+    if (renamed.length) {
+        d.renamed = byName();
+        for (const [k, v] of renamed)
+            d.renamed[k] = v;
+    }
+    // the library's files, links and history (shared/library.ts)
+    Object.assign(d, libraryFromJson(r));
+    return d;
+}
+// ---------------------------------------------------------------------------------------------
+// The logs' names
+/** FNV-1a over a text's UTF-8 bytes, as 8 hex digits: short, and the same in the page and the
+ *  server. */
+export function shortHash(s) {
+    let h = 0x811c9dc5;
+    for (const b of new TextEncoder().encode(s))
+        h = Math.imul(h ^ b, 0x01000193) >>> 0;
+    return h.toString(16).padStart(8, "0");
+}
+/** the longest readable part of a log's name, in UTF-16 units: the whole name stays under 60 */
+const SLUG = 32;
+/** The file a writer's events are appended to, in the site's `log/`: a readable part of
+ *  their name and a short hash of their exact name — `Alice-3f2a9c1b.jsonl`, an agent's
+ *  `Claude-7c01aa52.agent.jsonl`. The site's folder may be copied, backed up or synced anywhere,
+ *  Windows included, so the name is one every copy accepts: only letters and digits
+ *  that read the same in every Unicode normal form (accents dropped), joined by hyphens — no
+ *  `< > : " / \ | ? *`, no control character, no space or dot at the end, no `~` (an NTFS short
+ *  name's shape), never a device name (the hash follows the readable part) — under 60 characters;
+ *  and two names that differ only in case get two hashes, so their files differ by more than case
+ *  (macOS and Windows would take them for one). The hash is of the exact name the events carry.
+ *  Someone invited by a personal link writes to a log named by the link's id alone, whatever name
+ *  they go by — `3f2a9c1b07.person.jsonl` — so that a rename never starts a new file. */
+export function logFileName(name, agent, person = null) {
+    if (person)
+        return `${person}.person.jsonl`;
+    const plain = name.normalize("NFD").replace(/\p{M}+/gu, "").normalize("NFC");
+    let slug = "";
+    for (const c of plain) {
+        const keep = /^[\p{L}\p{N}]$/u.test(c) && c.normalize("NFD") === c && c.normalize("NFKC") === c;
+        const add = keep ? c : slug.endsWith("-") ? "" : "-";
+        if (slug.length + add.length > SLUG)
+            break;
+        slug += add;
+    }
+    slug = slug.replace(/^-+|-+$/g, "") || "writer";
+    return `${slug}-${shortHash(name)}${agent ? ".agent" : ""}.jsonl`;
+}
+/** The personal link's id a log is named by (`logFileName`), or null for any other log. */
+export function personOfLog(file) {
+    return /^([0-9a-f]{10})\.person\.jsonl$/.exec(file)?.[1] ?? null;
+}
+/** The problems in a few words, for the page and /api/status; null when there are none. */
+export function problemsText(ps) {
+    if (!ps.length)
+        return null;
+    const files = [...new Set(ps.map((p) => p.file))];
+    const each = ps.slice(0, 3).map((p) => `log/${p.file}, line ${p.line}: ${p.why}`).join("; ");
+    const who = [...new Set(ps.map((p) => p.writer ?? `the writer of log/${p.file}`))].join(", ");
+    return (`${ps.length === 1 ? "A line" : `${ps.length} lines`} of the review cannot be read — ${each}${ps.length > 3 ? `; and ${ps.length - 3} more` : ""}. ` +
+        `The rest is read; nothing is rewritten, and nothing more is written to ${files.length === 1 ? "that file" : "those files"} (${who}) until ${files.length === 1 ? "it is" : "they are"} fixed by hand.`);
+}
+/** Who gave an opinion: a person and an agent of the same name are two writers, and neither's
+ *  replaces the other's; someone invited by a personal link is their link, whatever name they went
+ *  by, and a guest who took a name they once had is someone else. */
+function author(o) {
+    return o.person ? `link ${o.person}` : (o.agent ? "agent " : "person ") + o.by;
+}
+/** Each author's latest opinion on a declaration, people's or agents': a new one replaces their
+ *  earlier one. */
+function latest(d, name, agents) {
+    const out = new Map();
+    // own keys only: a declaration may be called `constructor` or `toString`
+    for (const o of Object.hasOwn(d.opinions, name) ? d.opinions[name] : [])
+        if (!!o.agent === agents)
+            out.set(author(o), o);
+    return [...out.values()];
+}
+/** Each reviewer's latest opinion on a declaration: a new one replaces their earlier one. People
+ *  only: an agent's opinion is advice, and nothing read off this counts it. */
+export function current(d, name) {
+    return latest(d, name, false);
+}
+/** Each agent's latest advice on a declaration (AgentSpec decision 2), shown apart and never
+ *  counted. */
+export function advice(d, name) {
+    return latest(d, name, true);
+}
+/** Which verdict a summary shows when the opinions on a declaration's present version differ, the
+ *  first that any of them gives: a comment ahead of an approval, so that what a reviewer said is
+ *  not hidden by someone else's approval (the owner's default, 2026-10-09). Every summary reads
+ *  this order — the status (`statusOf`), what agents advise (`adviceOf`), and so every count,
+ *  colour and query built on them — and changing it here changes them all. */
+export const VERDICT_ORDER = ["comment", "approve"];
+/** The status a verdict gives a declaration when it is the one shown. */
+const STATUS_OF = { approve: "approved", comment: "commented" };
+/** The verdict shown of those given, in `VERDICT_ORDER`; null when none is given. */
+function summary(given) {
+    return VERDICT_ORDER.find((v) => given.some((o) => o.verdict === v)) ?? null;
+}
+/** What agents advise on the present version of a declaration, summed up as a status is
+ *  (`VERDICT_ORDER`); null when no agent has advised on it. */
+export function adviceOf(d, name, hash) {
+    return summary(advice(d, name).filter((o) => fresh(o, hash)));
+}
+/** What an opinion was given on, as recorded: with the opinion itself, or — where it replaced the
+ *  same reviewer's opinion on the same version and the same text, which `record` does not repeat —
+ *  with the one it replaced. Null for an opinion older than the record of it. */
+export function judgedOn(d, name, o) {
+    const own = (p) => p.text !== undefined ? { of: "source", text: p.text } : p.statement !== undefined ? { of: "statement", text: p.statement } : null;
+    // each author's previous opinion, and what it was given on, in the order given
+    const last = new Map();
+    for (const p of Object.hasOwn(d.opinions, name) ? d.opinions[name] : []) {
+        const prev = last.get(author(p));
+        const judged = own(p) ?? (p.hash && prev?.hash === p.hash ? prev.judged : null);
+        if (p === o)
+            return judged;
+        last.set(author(p), { hash: p.hash, judged });
+    }
+    return own(o);
+}
+/** Whether an opinion is about the version there is now. */
+export function fresh(o, hash) {
+    return !o.hash || !hash || o.hash === hash;
+}
+/** A summary of what reviewers said about the present version (ReviewSpec, "What the page shows"):
+ *  the verdict shown of those on it (`VERDICT_ORDER`), else stale where every opinion is on an
+ *  earlier version, else none. */
+export function statusOf(d, name, hash) {
+    const now = current(d, name);
+    if (!now.length)
+        return "none";
+    const v = summary(now.filter((o) => fresh(o, hash)));
+    return v ? STATUS_OF[v] : "stale";
+}
+/** Whether a dotted name is `prefix` or lies under it, a whole component at a time: "Foo" covers
+ *  "Foo" and "Foo.Bar", not "FooBar". */
+export function under(s, prefix) {
+    return s === prefix || s.startsWith(prefix + ".");
+}
+/** Whether a trusted prefix covers a declaration. The world outside the project is trusted by
+ *  module, as Mathlib is: its names (Nat.add, Finset.sum) say nothing of where they come from; or
+ *  as a whole (OUTSIDE). A project's own declaration is trusted by its module or its name, so that
+ *  a vendored library (a folder of files) and a layer reviewed on its own (a namespace) can both be
+ *  named. */
+export function covers(prefix, name, module, external) {
+    if (prefix === OUTSIDE)
+        return external;
+    return under(module, prefix) || (!external && under(name, prefix));
+}
+/** The trusted prefixes that cover a declaration, in the list's (sorted) order: a prefix comes
+ *  before the longer ones under it. */
+export function trustedBy(d, name, module, external) {
+    return d.trusted.filter((p) => covers(p, name, module, external));
+}
+/** Whether a declaration is trusted without review: a trusted prefix covers it, or it is a
+ *  standard axiom. */
+export function trusted(d, name, module, external) {
+    return STANDARD_AXIOMS.includes(name) || trustedBy(d, name, module, external).length > 0;
+}
+/** What the canvas and the lists mark a declaration with: what reviewers said about it, and when
+ *  nobody has, whether a trusted prefix covers it — for the project's own declarations only:
+ *  the outside world trusted by default is the rule there, not news. */
+export function markOf(d, name, module, external, hash) {
+    const s = statusOf(d, name, hash);
+    if (s !== "none" || external)
+        return s;
+    return trustedBy(d, name, module, false).length ? "trusted" : "none";
+}
+/** How far the review of a set (a target's TCB) has come. */
+export function progressOf(d, members) {
+    const p = { total: 0, approved: 0, commented: 0, stale: 0 };
+    for (const m of members) {
+        if (trusted(d, m.name, m.module, m.ext))
+            continue;
+        p.total++;
+        const s = statusOf(d, m.name, m.hash);
+        if (s === "approved")
+            p.approved++;
+        else if (s === "commented")
+            p.commented++;
+        else if (s === "stale")
+            p.stale++;
+    }
+    return p;
+}
+// ---------------------------------------------------------------------------------------------
+// Key declarations (ExportSpec decision 1)
+/** Whether `name` is marked as a key declaration of `target` (own keys only: a target may be
+ *  called `constructor`). The target itself is key without a mark: see keyMarks. */
+export function keyMarked(d, target, name) {
+    return Object.hasOwn(d.keys, target) && Object.hasOwn(d.keys[target], name);
+}
+/** The declarations marked as key for `target`, by name, sorted; the target itself, always
+ *  key, is not among them. Whether each is still in the target's review is the graph's to say
+ *  (shared/keys.ts, keySet). */
+export function keyMarks(d, target) {
+    return Object.hasOwn(d.keys, target) ? Object.keys(d.keys[target]).sort() : [];
+}
+/** The targets `name` is marked key for, sorted. */
+export function keyFor(d, name) {
+    return Object.keys(d.keys)
+        .filter((t) => Object.hasOwn(d.keys[t], name))
+        .sort();
+}