visualproof 0.2.0 → 0.3.0

package/dist/shared/artrecipe.js

@@ -0,0 +1,316 @@
+// An artwork recipe (ExportSpec decision 20, drafted 2026-10-15 for the owner's review): what a
+// picture of the board is, in words that hold on any project — a size by its name, names by a rule
+// ("the clusters to depth 1, and the targets"), targets and the selection by full name — so that
+// one recipe makes the same kind of picture of every codebase. An agent sends one
+// (POST /api/agent/artwork, server/agent.ts); the link it gets back carries it after `#`, and the
+// page that opens it resolves it against the board it opens on (web/src/main.ts, openRecipe) and
+// opens the artwork mode with what it says, saving the files where the link asks.
+import { ART_MAX_SIDE, ART_NAMES_BYTES, ART_RULED_BYTES, ART_STYLES, ART_TARGETS_BYTES, artNameId, cleanNames, FOOT_SIZE, SCHEMES, TITLE_CHARS, TITLE_SIZE } from "./collab.js";
+/** The sizes offered (web/src/artwork.ts, PRESETS), each in either orientation: given landscape;
+ *  `key`, a recipe's name for it. */
+export const ART_PRESETS = [
+    { key: "hd", name: "HD", w: 1920, h: 1080 },
+    { key: "4k", name: "4K", w: 3840, h: 2160 },
+    { key: "square", name: "Square", w: 4096, h: 4096 },
+    { key: "a3", name: "A3, 300 dpi", w: 4961, h: 3508 },
+    { key: "a2", name: "A2, 300 dpi", w: 7016, h: 4961 },
+];
+/** How a click selects, as the address names it (web/src/selection.ts, TOOLS): Selection; Rests on's
+ *  Uses, TCB, Keys and Direct; Used by. */
+export const RECIPE_MODES = ["plain", "deps", "tcb", "keys", "refs", "apps"];
+/** The most a recipe takes, in bytes of its JSON: the link carries it. */
+export const RECIPE_BYTES = 6000;
+const FIELDS = ["size", "orientation", "style", "theme", "transparent", "colouring", "border", "title", "subtitle", "titleSize", "footSize", "source", "names", "targets", "keys", "notes", "edges", "selection", "lit", "view"];
+const NAME_FIELDS = ["from", "clusters", "minShare", "targets", "decls", "omit"];
+/** A recipe as given, checked: each field as it says, nothing unknown (a field misspelt would
+ *  otherwise be a picture silently unlike the one meant). */
+export function readRecipe(v) {
+    const bad = (error, hint) => ({ error, hint });
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return bad("recipe is an object.", 'E.g. {"size": "a2", "orientation": "portrait", "names": {"clusters": 1}}.');
+    if (new TextEncoder().encode(JSON.stringify(v)).length > RECIPE_BYTES)
+        return bad(`A recipe is at most ${RECIPE_BYTES} bytes.`, "Name clusters by a depth rather than one by one.");
+    const o = v;
+    const unknown = Object.keys(o).filter((k) => !FIELDS.includes(k));
+    if (unknown.length)
+        return bad(`recipe has no field ${unknown.join(", ")}.`, `Its fields: ${FIELDS.join(", ")}.`);
+    const r = {};
+    const bool = (k) => {
+        if (o[k] === undefined)
+            return null;
+        if (typeof o[k] !== "boolean")
+            return `${k} is true or false.`;
+        r[k] = o[k];
+        return null;
+    };
+    const oneOf = (k, of) => {
+        if (o[k] === undefined)
+            return null;
+        if (!of.includes(o[k]))
+            return `${k} is ${of.join(", ")}.`;
+        r[k] = o[k];
+        return null;
+    };
+    const num = (k, least, most) => {
+        if (o[k] === undefined)
+            return null;
+        if (typeof o[k] !== "number" || !Number.isFinite(o[k]) || o[k] < least || o[k] > most)
+            return `${k} is a number from ${least} to ${most} (hundredths of the picture's height).`;
+        r[k] = o[k];
+        return null;
+    };
+    const text = (k) => {
+        if (o[k] === undefined)
+            return null;
+        if (o[k] !== null && (typeof o[k] !== "string" || o[k].length > TITLE_CHARS))
+            return `${k} is text of at most ${TITLE_CHARS} characters, "" for none, or null for the project's own.`;
+        r[k] = o[k];
+        return null;
+    };
+    const names = (x) => Array.isArray(x) && x.length <= 2000 && x.every((n) => typeof n === "string" && n.length > 0 && n.length <= 1000);
+    const fault = bool("transparent") ?? bool("border") ?? bool("source") ?? bool("keys") ?? bool("notes") ?? bool("lit") ??
+        oneOf("orientation", ["landscape", "portrait"]) ?? oneOf("style", ART_STYLES) ?? oneOf("theme", ["light", "dark"]) ??
+        oneOf("colouring", SCHEMES) ?? oneOf("edges", ["all", "selection", "none"]) ??
+        num("titleSize", TITLE_SIZE.least, TITLE_SIZE.most) ?? num("footSize", FOOT_SIZE.least, FOOT_SIZE.most) ?? text("title") ?? text("subtitle");
+    if (fault)
+        return bad(fault, "See GET /api/agent/docs/export, \"Artwork\".");
+    if (o.size !== undefined) {
+        const s = o.size;
+        if (typeof s === "string") {
+            if (!ART_PRESETS.some((p) => p.key === s))
+                return bad(`size ${s} is no size.`, `A size by name (${ART_PRESETS.map((p) => p.key).join(", ")}) or {w, h} in pixels.`);
+            r.size = s;
+        }
+        else {
+            const sw = s?.w, sh = s?.h;
+            const side = (x) => Number.isInteger(x) && x >= 16 && x <= ART_MAX_SIDE;
+            if (!side(sw) || !side(sh))
+                return bad(`size is a name or {w, h}: whole pixels from 16 to ${ART_MAX_SIDE}.`, `Names: ${ART_PRESETS.map((p) => p.key).join(", ")}.`);
+            r.size = { w: sw, h: sh };
+        }
+    }
+    if (o.names !== undefined) {
+        const n = o.names;
+        if (n === "board" || n === "clusters" || n === "none")
+            r.names = n;
+        else if (n && typeof n === "object" && !Array.isArray(n)) {
+            const m = n;
+            const extra = Object.keys(m).filter((k) => !NAME_FIELDS.includes(k));
+            if (extra.length)
+                return bad(`names has no field ${extra.join(", ")}.`, `Its fields: ${NAME_FIELDS.join(", ")}.`);
+            const rule = {};
+            if (m.from !== undefined) {
+                if (m.from !== "none" && m.from !== "board")
+                    return bad("names.from is none or board.", "From none: only what the rule names; from board: what the board writes, the rule's besides.");
+                rule.from = m.from;
+            }
+            if (m.clusters !== undefined) {
+                if (Number.isInteger(m.clusters) && m.clusters >= 0 && m.clusters <= 20)
+                    rule.clusters = m.clusters;
+                else if (names(m.clusters))
+                    rule.clusters = m.clusters;
+                else
+                    return bad("names.clusters is a depth (0: the top level) or a list of clusters' keys.", "E.g. 1: the top level and the clusters right under it.");
+            }
+            if (m.minShare !== undefined) {
+                if (typeof m.minShare !== "number" || !(m.minShare >= 0 && m.minShare <= 1))
+                    return bad("names.minShare is a share from 0 to 1.", "0.01: a cluster below the top named where it holds at least 1% of the project's declarations.");
+                rule.minShare = m.minShare;
+            }
+            if (m.targets !== undefined) {
+                if (typeof m.targets !== "boolean")
+                    return bad("names.targets is true or false.", "The shown targets' names.");
+                rule.targets = m.targets;
+            }
+            for (const k of ["decls", "omit"]) {
+                if (m[k] === undefined)
+                    continue;
+                if (!names(m[k]))
+                    return bad(`names.${k} is a list of names.`, k === "decls" ? "Declarations by full name." : "Clusters by key, declarations by full name.");
+                rule[k] = m[k];
+            }
+            r.names = rule;
+        }
+        else
+            return bad('names is "board", "clusters", "none" or a rule {from, clusters, minShare, targets, decls, omit}.', 'E.g. {"clusters": 1}: the top level and the clusters right under it, and the targets.');
+    }
+    if (o.targets !== undefined) {
+        const t = o.targets;
+        if (t === "all" || t === "none" || t === "faded")
+            r.targets = t;
+        else if (names(t))
+            r.targets = t;
+        else
+            return bad('targets is "all", "none", "faded" or a list of targets\' full names.', "Those named are marked, the others drawn as any declaration.");
+    }
+    if (o.selection !== undefined && o.selection !== null) {
+        const s = o.selection;
+        if (!s || typeof s !== "object" || typeof s.name !== "string" || !s.name || (s.mode !== undefined && !RECIPE_MODES.includes(s.mode)) || Object.keys(s).some((k) => k !== "name" && k !== "mode"))
+            return bad("selection is {name, mode?}: a declaration's full name, and how it is selected.", `mode: ${RECIPE_MODES.join(", ")} (default tcb).`);
+        r.selection = { name: s.name, ...(s.mode !== undefined ? { mode: s.mode } : {}) };
+    }
+    else if (o.selection === null)
+        r.selection = null;
+    if (o.view !== undefined && o.view !== null) {
+        if (typeof o.view !== "string" || !o.view || o.view.length > 200)
+            return bad("view is a view's id.", "GET /api/agent/views lists them; left out, the Project.");
+        r.view = o.view;
+    }
+    return { recipe: r };
+}
+/** the outside world's cluster, as a reader may call it */
+const EXTERNAL = "⟨external⟩";
+const keyOf = (k) => (k === "External" ? EXTERNAL : k.startsWith("External.") ? EXTERNAL + k.slice(8) : k);
+/** A recipe resolved against a board: everything it leaves out as a new artwork has it (4K
+ *  landscape, the board's look, light, names as the board writes them, every target marked). Names
+ *  are written from none: the clusters named by key, the declarations and the targets' names
+ *  wherever they fall (ArtworkLook `shownNames`), as names ticked by hand are; the clusters a depth
+ *  rule names — the outside world's own, and the project's down to the depth that hold `minShare`
+ *  of the project — only where they cover no name already written (`ruledNames`; the owner's
+ *  decision of 2026-10-15: names chosen by a rule never overlap). */
+export function resolveRecipe(r, b) {
+    const problems = [];
+    const preset = typeof r.size === "string" ? ART_PRESETS.find((p) => p.key === r.size) : ART_PRESETS[1];
+    const given = typeof r.size === "object" ? r.size : { w: preset.w, h: preset.h };
+    const portrait = r.orientation ? r.orientation === "portrait" : given.h > given.w;
+    const [long, short] = given.w >= given.h ? [given.w, given.h] : [given.h, given.w];
+    const { w, h } = portrait ? { w: short, h: long } : { w: long, h: short };
+    // what the recipe names that the board has not is said (`problems`); what is left out for room,
+    // counted (`left`); a target of the review the board has not — a target outlives its declaration's
+    // rename or removal — is left out unsaid, as the board leaves it
+    let left = 0;
+    const targetSet = new Set(b.targets);
+    const held = (n) => b.clusterOf(n) !== undefined;
+    let targets = "marked";
+    let shownTargets = [];
+    let marked = b.targets.filter(held);
+    if (r.targets === "none")
+        [targets, marked] = ["plain", []];
+    else if (r.targets === "faded")
+        targets = "highlight";
+    else if (Array.isArray(r.targets)) {
+        const unknown = r.targets.filter((t) => !targetSet.has(t));
+        if (unknown.length)
+            problems.push(`not targets of the review: ${unknown.join(", ")}`);
+        const off = r.targets.filter((t) => targetSet.has(t) && !held(t));
+        if (off.length)
+            problems.push(`targets not on the board: ${off.join(", ")}`);
+        const on = r.targets.filter((t) => targetSet.has(t) && held(t));
+        shownTargets = cleanNames(on, ART_TARGETS_BYTES);
+        left += new Set(on).size - shownTargets.length;
+        targets = "chosen";
+        marked = shownTargets;
+    }
+    // the names
+    let labels = "board";
+    let namesFrom = "board";
+    let shown = [];
+    let hidden = [];
+    let ruledIds = [];
+    const named = { clusters: [], ruled: [], decls: [] };
+    const n = r.names;
+    if (n === "board" || n === "clusters" || n === "none")
+        labels = n;
+    else if (n) {
+        labels = "chosen";
+        namesFrom = n.from ?? "none";
+        const omit = new Set((n.omit ?? []).map(keyOf));
+        const byKey = new Map(b.clusters.map((c, i) => [c.key, i]));
+        if (typeof n.clusters === "number") {
+            const least = Math.ceil((n.minShare ?? 0.01) * b.projectCount);
+            b.clusters.forEach((c) => {
+                if ((c.ext ? c.depth === 0 : c.depth <= n.clusters && c.count >= least) && !omit.has(c.key))
+                    named.ruled.push(c.key);
+            });
+        }
+        else if (Array.isArray(n.clusters)) {
+            for (const k of n.clusters) {
+                const key = keyOf(k);
+                if (!byKey.has(key))
+                    problems.push(`no cluster ${k} on the board`);
+                else if (!omit.has(key) && !named.clusters.includes(key))
+                    named.clusters.push(key);
+            }
+        }
+        // the targets' names (all on the board), and the declarations named
+        const decls = n.targets === false ? [] : [...marked];
+        for (const d of n.decls ?? []) {
+            if (!held(d))
+                problems.push(`no declaration ${d} on the board`);
+            else
+                decls.push(d);
+        }
+        for (const d of decls)
+            if (!omit.has(d) && !named.decls.includes(d))
+                named.decls.push(d);
+        const ids = [...named.clusters.map((k) => artNameId("cluster", k)), ...named.decls.map((d) => artNameId("decl", d))];
+        shown = cleanNames(ids, ART_NAMES_BYTES);
+        const ruled = named.ruled.map((k) => artNameId("cluster", k));
+        ruledIds = cleanNames(ruled, ART_RULED_BYTES);
+        left += ids.length + ruled.length - shown.length - ruledIds.length;
+        // what is named is what the artwork carries
+        const kept = new Set([...shown, ...ruledIds]);
+        named.clusters = named.clusters.filter((k) => kept.has(artNameId("cluster", k)));
+        named.ruled = named.ruled.filter((k) => kept.has(artNameId("cluster", k)));
+        named.decls = named.decls.filter((d) => kept.has(artNameId("decl", d)));
+        // from the board, what to leave out is said as hidden
+        if (namesFrom === "board")
+            hidden = cleanNames([...omit].map((k) => (byKey.has(k) ? artNameId("cluster", k) : artNameId("decl", k))), ART_NAMES_BYTES);
+    }
+    const look = {
+        w,
+        h,
+        scheme: r.colouring ?? "kind",
+        theme: r.theme ?? "light",
+        background: r.transparent ? "transparent" : "theme",
+        labels,
+        namesFrom,
+        hiddenNames: hidden,
+        shownNames: shown,
+        ruledNames: ruledIds,
+        edges: r.edges ?? "all",
+        notes: r.notes ?? true,
+        targets,
+        shownTargets,
+        keys: r.keys ?? true,
+        selection: r.lit ?? true,
+        source: r.source ?? false,
+        style: r.style ?? "board",
+        title: r.title ?? null,
+        subtitle: r.subtitle ?? null,
+        titleSize: r.titleSize ?? TITLE_SIZE.first,
+        footSize: r.footSize ?? FOOT_SIZE.first,
+        border: r.border ?? false,
+    };
+    return { look, named, left, problems };
+}
+/** A recipe as the link carries it after `#`: its JSON, base64url. */
+export function encodeRecipe(r) {
+    const bytes = new TextEncoder().encode(JSON.stringify(r));
+    let s = "";
+    for (const x of bytes)
+        s += String.fromCharCode(x);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** A link's recipe, read back; null where it is none. */
+export function decodeRecipe(text) {
+    try {
+        const s = atob(text.replace(/-/g, "+").replace(/_/g, "/"));
+        return JSON.parse(new TextDecoder().decode(Uint8Array.from(s, (c) => c.charCodeAt(0))));
+    }
+    catch {
+        return null;
+    }
+}
+/** the address's word for the recipe, and for the files to save */
+export const RECIPE_PARAM = "art";
+export const SAVE_PARAM = "save";
+/** A fragment's recipe and the files it asks to save; null where it carries none. */
+export function recipeIn(hash) {
+    const p = new URLSearchParams(hash.startsWith("#") ? hash.slice(1) : hash);
+    const text = p.get(RECIPE_PARAM);
+    if (!text)
+        return null;
+    const save = (p.get(SAVE_PARAM) ?? "").split(",").filter((k) => k === "png" || k === "svg");
+    return { text, save: [...new Set(save)] };
+}

package/dist/shared/collab.js

@@ -93,8 +93,11 @@ export function artNameId(kind, s) {
  *  presence carries, in bytes of their JSON: a heartbeat is at most 16 KB (server/main.ts), and the
  *  rest of where a reader is has room beside them. Names by selection are kept as what differs from
  *  As shown, so that a few names hidden or added are a few names carried. */
-export const ART_NAMES_BYTES = 4500;
+export const ART_NAMES_BYTES = 4000;
 export const ART_TARGETS_BYTES = 2500;
+/** the names a recipe's rule chose (ArtworkLook `ruledNames`): a rule names a few clusters. The four
+ *  lists full, with the longest title and line, leave a heartbeat room (test/sharesnap.test.ts) */
+export const ART_RULED_BYTES = 1000;
 /** What `x` adds to a list's JSON: itself, quoted, and a comma. */
 const jsonBytes = (x) => new TextEncoder().encode(JSON.stringify(x)).length + 1;
 /** A list of names as given, checked: strings, each once, none empty or longer than a name is (1,000
@@ -148,12 +151,14 @@ export function cleanArtwork(v) {
     // say them, and the key marks as the targets drew them before (with their stars, unless As any)
     const namesFrom = o.namesFrom === "none" ? "none" : "board";
     const hiddenNames = cleanNames(o.hiddenNames, ART_NAMES_BYTES, isArtNameId), shownNames = cleanNames(o.shownNames, ART_NAMES_BYTES, isArtNameId);
+    // the names a recipe's rule chose, said since later that night: none where a page does not say them
+    const ruledNames = cleanNames(o.ruledNames, ART_RULED_BYTES, isArtNameId);
     const shownTargets = cleanNames(o.shownTargets, ART_TARGETS_BYTES);
     const keys = typeof o.keys === "boolean" ? o.keys : targets !== "plain";
     // the style and the title, said since that night: as the board, the project's own; the foot's
     // size, said since later that night: the first
     const style = one(ART_STYLES, o.style) ?? "board";
-    return { w, h, scheme, theme, background, labels, namesFrom, hiddenNames, shownNames, edges, notes: o.notes, targets, shownTargets, keys, selection: o.selection, source: o.source === true, style, title: cleanTitle(o.title), subtitle: cleanTitle(o.subtitle), titleSize: cleanTitleSize(o.titleSize), footSize: cleanFootSize(o.footSize), border: o.border === true, region: [...r] };
+    return { w, h, scheme, theme, background, labels, namesFrom, hiddenNames, shownNames, ruledNames, edges, notes: o.notes, targets, shownTargets, keys, selection: o.selection, source: o.source === true, style, title: cleanTitle(o.title), subtitle: cleanTitle(o.subtitle), titleSize: cleanTitleSize(o.titleSize), footSize: cleanFootSize(o.footSize), border: o.border === true, region: [...r] };
 }
 /** The legend's schemes (CanvasSpec, "Colour schemes"). */
 export const SCHEMES = ["kind", "status"];

package/dist/shared/declfind.js

@@ -0,0 +1,95 @@
+// A declaration by the name someone gives (the agents' API, server/agent.ts; the artwork command,
+// server/artcmd.ts): the graph's own name; else the declaration a name it folds is folded into — a
+// declaration Lean generated from a command, or a constructor, recursor, field, equation lemma of
+// one — else, where none is, the names likely meant.
+import { search } from "./search.js";
+/** the last components of names Lean generates beside a declaration (extractor/Extract.lean,
+ *  `generatedSuffixes`, and the like) */
+export const GENERATED_LAST = /^(?:rec|recOn|casesOn|noConfusion|noConfusionType|ctorElim|ctorElimType|below|brecOn|binductionOn|ibelow|ctorIdx|toCtorIdx|ofNat|ofNat_ctorIdx|sizeOf_spec|injEq|inj|eq_def|induct|mutual_induct|fun_cases|induct_unfolding|ext_iff|congr_simp|mk|elim|(?:eq|match|proof)_\d+|_.*)$/;
+/** The edit distance between two short strings, or `most + 1` once it is more than `most`. */
+export function editDistance(a, b, most) {
+    if (Math.abs(a.length - b.length) > most)
+        return most + 1;
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        let best = i;
+        for (let j = 1; j <= b.length; j++) {
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            best = Math.min(best, row[j]);
+        }
+        if (best > most)
+            return most + 1;
+        prev = row;
+    }
+    return Math.min(prev[b.length], most + 1);
+}
+/** The declaration a name the graph has no node for is folded into: a declaration Lean generated
+ *  from a command (ViewNode.also), or a constructor, recursor, field, equation lemma… of a
+ *  declaration or of one so generated, which is a name one component below it. A name one
+ *  component below a declaration that is a typo or two away from a declaration beside it is
+ *  taken for that typo, not for something folded, unless its last component is one Lean
+ *  generates. */
+export function foldedAt(g, name) {
+    const direct = g.foldedInto.get(name);
+    if (direct !== undefined)
+        return direct;
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0)
+        return undefined;
+    const head = name.slice(0, dot), last = name.slice(dot + 1);
+    const at = g.byName.get(head) ?? g.foldedInto.get(head);
+    if (at === undefined || !last)
+        return undefined;
+    if (!GENERATED_LAST.test(last)) {
+        const most = last.length < 5 ? 1 : 2;
+        const near = (n) => n.length > head.length + 1 && n.startsWith(head + ".") && !n.includes(".", head.length + 1) && editDistance(n.slice(head.length + 1).toLowerCase(), last.toLowerCase(), most) <= most;
+        for (const n of g.nodes)
+            if (near(n.name))
+                return undefined;
+        for (const n of g.foldedInto.keys())
+            if (near(n))
+                return undefined;
+    }
+    return at;
+}
+/** Up to five names like `name`: the same name in another case; then the same last component,
+ *  or one a typo or two away, in the same namespace first; then what the search finds. */
+export function guessNames(g, index, name) {
+    const dot = name.lastIndexOf(".");
+    const last = name.slice(dot + 1).toLowerCase();
+    const ns = dot < 0 ? "" : name.slice(0, dot);
+    const scored = new Map();
+    const offer = (n, score) => {
+        if ((scored.get(n) ?? Infinity) > score)
+            scored.set(n, score);
+    };
+    const lower = name.toLowerCase();
+    const most = last.length < 5 ? 1 : 2;
+    // the graph's declarations, and the names Lean generated from a command that they fold
+    for (const name of [...g.nodes.map((n) => n.name), ...g.foldedInto.keys()]) {
+        if (name.toLowerCase() === lower)
+            offer(name, -1);
+        const k = name.lastIndexOf(".");
+        const d = editDistance(name.slice(k + 1).toLowerCase(), last, most);
+        if (d <= most)
+            offer(name, 2 * d + (name.slice(0, Math.max(0, k)) === ns ? 0 : 1));
+    }
+    let rank = 0;
+    for (const q of [name.slice(dot + 1), name.replace(/\./g, " ")]) {
+        if (q.trim().length < 2)
+            continue;
+        const f = search(index, q);
+        for (const h of [...f.hits.name, ...f.hits.statement].slice(0, 10))
+            offer(g.nodes[h.i].name, 10 + rank++);
+    }
+    return [...scored]
+        .sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || (a[0] < b[0] ? -1 : 1))
+        .slice(0, 5)
+        .map(([n]) => n);
+}
+/** The declaration `name` names, its own or the one it is folded into; undefined where none is. */
+export function declAt(g, name) {
+    const n = name.trim();
+    return g.byName.get(n) ?? foldedAt(g, n);
+}

package/dist/shared/lostfound.js

@@ -64,6 +64,7 @@ export function lostEntries(d, views, has, known = (n) => n.includes("."), pinWh
                 kind: "opinion",
                 name,
                 ...who(o),
+                ...(o.recordedBy ? { recordedBy: o.recordedBy } : {}),
                 verdict: o.verdict,
                 ...(o.comment ? { comment: o.comment } : {}),
                 ...(was.length ? { aliases: was.map((n) => lostKey.opinion(name, n, o.at)) } : {}),

package/dist/shared/pastgraph.js

@@ -21,12 +21,12 @@ export const PAST_GHOST = 1;
 export const PAST_CHANGED = 4;
 /** renamed since: shown under its name then */
 export const PAST_RENAMED = 8;
-/** The git source of a past build: the project's source, the build's own commit; none where the
- *  build's commit is not known, or only guessed. */
-function gitThen(now, commit) {
+/** The git commit of a past build; none where it is not known, or only guessed. Its source is the
+ *  project's, which the page has now (web/src/main.ts, GET /api/git). */
+function gitThen(commit) {
     if (!commit || commit.guessed)
         return { git: undefined };
-    return { git: { source: now?.source ?? null, commit: commit.hash, branch: commit.branch, ...(commit.dirty ? { dirty: true } : {}) } };
+    return { git: { source: null, commit: commit.hash, branch: commit.branch, ...(commit.dirty ? { dirty: true } : {}) } };
 }
 /** The past graph of snapshot `snap` (its declarations and its edges, as /graph's parts give them),
  *  marked by `diff` (from it to the latest), with the project's description of `now`. */
@@ -40,8 +40,8 @@ export function pastGraph(snap, edges, now, diff) {
     const meta = {
         schema: 1,
         layoutVersion: now.meta.layoutVersion,
-        // the commit of that build, where it is known; the source is the project's now
-        project: { ...now.meta.project, extractedAt: snap.snapshot.at, ...gitThen(now.meta.project.git, snap.snapshot.commit) },
+        // the commit of that build, where it is known
+        project: { ...now.meta.project, extractedAt: snap.snapshot.at, ...gitThen(snap.snapshot.commit) },
         modules: snap.modules.map((m) => ({ name: m.name, file: null, imports: m.imports })),
         nodes,
         projectCount: P,

package/dist/shared/review.js

@@ -40,6 +40,7 @@
 // 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 { validName } from "./collab.js";
 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"];
@@ -102,6 +103,19 @@ export function invalid(r) {
         return "agent";
     if (o.person !== undefined && (!validPersonId(o.person) || o.agent))
         return "person";
+    // an opinion recorded for someone else (ReviewSpec decision 8): a person's, for another person
+    if (o.for !== undefined || o.forPerson !== undefined) {
+        if (o.op !== "opinion")
+            return "only an opinion is recorded for someone else";
+        if (o.agent)
+            return "an agent records for no one";
+        if (typeof o.for !== "string" || !validName(o.for.trim()))
+            return "for";
+        if (o.forPerson !== undefined && !validPersonId(o.forPerson))
+            return "forPerson";
+        if (o.for.trim() === o.by.trim() || (o.forPerson !== undefined && o.forPerson === o.person))
+            return "an opinion of one's own is recorded as one's own";
+    }
     switch (o.op) {
         case "opinion":
             if (o.verdict !== "approve" && o.verdict !== "comment")
@@ -153,6 +167,12 @@ export function eventOf(d, r, toolchain, now) {
     switch (r.op) {
         case "opinion": {
             const e = { op: "opinion", name: r.name, by, ...person, verdict: r.verdict, at: now, toolchain };
+            // recorded for someone else (ReviewSpec decision 8)
+            if (r.for?.trim()) {
+                e.for = r.for.trim();
+                if (r.forPerson)
+                    e.forPerson = r.forPerson;
+            }
             if (r.comment?.trim())
                 e.comment = r.comment.trim();
             if (r.agent)
@@ -160,7 +180,7 @@ export function eventOf(d, r, toolchain, now) {
             // 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 was = (Object.hasOwn(d.opinions, r.name) ? d.opinions[r.name] : []).findLast((p) => author(p) === voice(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;
@@ -212,8 +232,8 @@ export function applyEvent(d, e) {
         case "name":
             return;
         case "opinion": {
-            const { op: _op, name, ...o } = e;
-            (Object.hasOwn(d.opinions, name) ? d.opinions[name] : (d.opinions[name] = [])).push(o);
+            const { op: _op, name, for: forName, forPerson, ...o } = e;
+            (Object.hasOwn(d.opinions, name) ? d.opinions[name] : (d.opinions[name] = [])).push(forName === undefined ? o : recordedFor(d, o, forName, forPerson));
             return;
         }
         case "target":
@@ -256,15 +276,27 @@ function named(d, id, name) {
     if (p?.name === name)
         return;
     if (!p) {
-        d.people[id] = { name, was: [] };
+        // first seen after opinions were recorded for them (decision 8): those show under this name,
+        // the names they were written under kept, so that a quote of one still finds it
+        const was = new Set();
+        for (const ops of Object.values(d.opinions))
+            for (const o of ops)
+                if (o.person === id && o.by !== name) {
+                    was.add(o.by);
+                    o.by = name;
+                }
+        d.people[id] = { name, was: [...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)
+        for (const o of ops) {
             if (o.person === id)
                 o.by = name;
+            if (o.recordedBy?.person === id)
+                o.recordedBy.by = name;
+        }
     for (const t of Object.values(d.targets))
         if (t.person === id)
             t.by = name;
@@ -351,6 +383,20 @@ export function readEvent(raw, agentLog, personLog = null) {
             }
             if (e.text !== undefined && e.statement !== undefined)
                 return "a text and a statement";
+            // recorded for someone else (ReviewSpec decision 8): a person's line, for another person
+            if (o.for !== undefined || o.forPerson !== undefined) {
+                if (agentLog)
+                    return "an agent's opinion recorded for someone else";
+                if (typeof o.for !== "string" || !validName(o.for))
+                    return "for";
+                if (o.forPerson !== undefined && !validPersonId(o.forPerson))
+                    return "forPerson";
+                if (o.for === by || (o.forPerson !== undefined && o.forPerson === personLog))
+                    return "an opinion recorded for its own writer";
+                e.for = o.for;
+                if (o.forPerson !== undefined)
+                    e.forPerson = o.forPerson;
+            }
             if (agentLog)
                 e.agent = true;
             return e;
@@ -503,6 +549,17 @@ export function problemsText(ps) {
 function author(o) {
     return o.person ? `link ${o.person}` : (o.agent ? "agent " : "person ") + o.by;
 }
+/** Whose an opinion line is: theirs it was recorded for (ReviewSpec decision 8), else its writer's. */
+function voice(e) {
+    return e.for === undefined ? author(e) : author({ by: e.for, verdict: e.verdict, at: e.at, ...(e.forPerson ? { person: e.forPerson } : {}) });
+}
+/** An opinion recorded for someone else (ReviewSpec decision 8), as the review holds it: theirs —
+ *  under their latest name where they are invited — saying who recorded it. */
+function recordedFor(d, o, forName, forPerson) {
+    const { by, person, ...rest } = o;
+    const name = forPerson && Object.hasOwn(d.people, forPerson) ? d.people[forPerson].name : forName;
+    return { ...rest, by: name, ...(forPerson ? { person: forPerson } : {}), recordedBy: { by, ...(person ? { person } : {}) } };
+}
 /** Each author's latest opinion on a declaration, people's or agents': a new one replaces their
  *  earlier one. */
 function latest(d, name, agents) {