visualproof 0.0.0-stage → 0.1.0

package/dist/server/renames.js

@@ -0,0 +1,268 @@
+// Renames (HistorySpec.md, decided by the owner on 2026-10-09). On each new graph, the declarations
+// that vanished since the build before are paired with those that appeared:
+//
+// - **High confidence**: the same version once names are mapped — the same content, with what it
+//   refers to the same, the declaration itself and what was renamed with it set aside (TCBSpec
+//   decision 3) — and the same kind, one declaration on each side. A pairing can make another
+//   (what refers to a renamed declaration is known once that one is), so it is found again until
+//   nothing more pairs. Against a build read before versions, the same kernel's hash stands for it.
+//   Such a rename is migrated by itself (server/live.ts): a move in the server's log where something
+//   was said of the declaration or of what refers to it, and its pins, its notes' mentions and its
+//   views' scopes moved on the server (server/views.ts) — each recorded here, with what undoes it.
+// - **Medium confidence**: what is alike without being the same — the same last name, the same
+//   module, nearby, a statement that reads alike, or content the same as several others'. Offered as
+//   suggestions, never applied.
+//
+// What a module of either build that could not be read held is set aside: it did not vanish.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { refIdentity, versionOf } from "./versions.js";
+/** What stands for the declaration itself in its own references, so that a declaration can be
+ *  paired before its own rename is known. */
+const SELF = "\u0000self";
+/** the least likeness a suggestion has */
+export const SUGGEST_FROM = 0.6;
+/** the most candidates a vanished declaration is compared with for a suggestion */
+const MAX_CANDIDATES = 200;
+const last = (name) => name.slice(name.lastIndexOf(".") + 1);
+const tail = (module) => module.slice(module.lastIndexOf(".") + 1);
+/** The words a statement is written with, dotted names by their last part: what two statements
+ *  are compared by. */
+function words(type) {
+    return new Set(type.replace(/[\p{L}_][\p{L}\p{N}_'!?.₀-₉]*/gu, (m) => last(m)).split(/[\s()[\]{}:,]+/).filter(Boolean));
+}
+function jaccard(a, b) {
+    if (!a.size && !b.size)
+        return 1;
+    let both = 0;
+    for (const x of a)
+        if (b.has(x))
+            both++;
+    return both / (a.size + b.size - both);
+}
+/** The pairs of `before`'s vanished declarations with `after`'s new ones, high confidence first.
+ *  `identity`: the renames in force before these (server/versions.ts). */
+export function findRenames(before, after, identity) {
+    const proj = (g) => g.nodes.slice(0, g.projectCount);
+    const inBefore = new Set(proj(before).map((n) => n.name));
+    const inAfter = new Set(proj(after).map((n) => n.name));
+    const unreadAfter = new Set(after.info.missing);
+    const unreadBefore = new Set(before.info.missing);
+    const gone = proj(before).filter((n) => !inAfter.has(n.name) && !unreadAfter.has(n.module));
+    const came = proj(after).filter((n) => !inBefore.has(n.name) && !unreadBefore.has(n.module));
+    if (!gone.length || !came.length)
+        return [];
+    // after's new names → the names they had, as found so far
+    const was = new Map();
+    const used = new Set();
+    const out = [];
+    const shapeKey = (n, map) => n.shape && n.refs ? `${n.kind}|${versionOf(n.shape, n.refs.map((r) => refIdentity(r, (u) => (u === n.name ? SELF : map(u)))))}` : null;
+    const pairUnique = (key, why) => {
+        const byKey = new Map();
+        const add = (n, side) => {
+            const k = key(n, side === "b" ? "before" : "after");
+            if (k === null)
+                return;
+            let e = byKey.get(k);
+            if (!e)
+                byKey.set(k, (e = { b: [], a: [] }));
+            e[side].push(n);
+        };
+        for (const n of gone)
+            if (!used.has(n.name))
+                add(n, "b");
+        for (const n of came)
+            if (!was.has(n.name))
+                add(n, "a");
+        let made = 0;
+        for (const { b, a } of byKey.values()) {
+            if (b.length !== 1 || a.length !== 1)
+                continue;
+            was.set(a[0].name, b[0].name);
+            used.add(b[0].name);
+            out.push({ from: b[0].name, to: a[0].name, confidence: "high", why });
+            made++;
+        }
+        return made;
+    };
+    // the same version, names aside, again as long as a pairing makes another
+    const afterIdentity = (u) => identity(was.get(u) ?? u);
+    while (pairUnique((n, side) => shapeKey(n, side === "before" ? identity : afterIdentity), "same version") > 0)
+        ;
+    // against a build read before versions: the same kernel's hash, which a rename of what it refers
+    // to changes, but a rename of the declaration alone does not where it does not mention itself
+    if (!(proj(before).some((n) => n.shape) && proj(after).some((n) => n.shape)))
+        pairUnique((n) => `${n.kind}|k:${n.hash}`, "same kernel hash");
+    // suggestions: alike, not the same
+    const rest = gone.filter((n) => !used.has(n.name));
+    const open = came.filter((n) => !was.has(n.name));
+    if (!rest.length || !open.length)
+        return out;
+    const byLast = new Map();
+    const byModule = new Map();
+    const byShape = new Map();
+    for (const n of open) {
+        for (const [m, k] of [[byLast, `${n.kind}|${last(n.name)}`], [byModule, `${n.kind}|${n.module}`]]) {
+            const xs = m.get(k);
+            if (xs)
+                xs.push(n);
+            else
+                m.set(k, [n]);
+        }
+        const sk = shapeKey(n, afterIdentity);
+        if (sk)
+            byShape.set(sk, [...(byShape.get(sk) ?? []), n]);
+    }
+    const text = new Map();
+    const wordsOf = (n) => text.get(n) ?? (text.set(n, words(n.type)), text.get(n));
+    const offers = [];
+    for (const v of rest) {
+        const sk = shapeKey(v, identity);
+        const sameContent = new Set(sk ? byShape.get(sk) ?? [] : []);
+        const cands = new Set([...(byLast.get(`${v.kind}|${last(v.name)}`) ?? []), ...(byModule.get(`${v.kind}|${v.module}`) ?? []), ...sameContent]);
+        let best = null;
+        let k = 0;
+        for (const w of cands) {
+            if (k++ >= MAX_CANDIDATES)
+                break;
+            const clues = [];
+            let score = 0;
+            if (last(w.name) === last(v.name))
+                (score += 0.4), clues.push("the same last name");
+            if (w.module === v.module) {
+                score += 0.15;
+                clues.push("the same module");
+                if (w.range && v.range && Math.abs(w.range[0] - v.range[0]) <= 30)
+                    (score += 0.05), clues.push("nearby");
+            }
+            else if (tail(w.module) === tail(v.module))
+                (score += 0.1), clues.push("a file of the same name");
+            const sim = jaccard(wordsOf(v), wordsOf(w));
+            score += 0.4 * sim;
+            if (sim >= 0.8)
+                clues.push("a statement that reads alike");
+            if (sameContent.has(w))
+                (score = Math.max(score, 0.8)), clues.push("the same content as others");
+            score = Math.min(1, Math.round(score * 100) / 100);
+            if (score >= SUGGEST_FROM && (!best || score > best.score))
+                best = { from: v.name, to: w.name, confidence: "medium", why: clues.join(", "), score };
+        }
+        if (best)
+            offers.push(best);
+    }
+    // each new declaration offered once, to the one it is likest
+    offers.sort((p, q) => q.score - p.score || (p.from < q.from ? -1 : 1));
+    const taken = new Set();
+    for (const p of offers) {
+        if (taken.has(p.to))
+            continue;
+        taken.add(p.to);
+        out.push(p);
+    }
+    return out;
+}
+/** The migrations and suggestions, kept in `<site>/history/`: `migrations.jsonl`, one line per
+ *  migration and one per undoing (`{undo, by, agent?, person?, at}`); `renames.jsonl`, one line per
+ *  graph read with the pairs found against the build before (`{snap, at, pairs}`). Appended, never
+ *  rewritten. */
+export class Renames {
+    migFile;
+    pairFile;
+    migrations = [];
+    byId = new Map();
+    /** per snapshot, the pairs found at it (each read of its build adds its own) */
+    found = new Map();
+    constructor(historyDir) {
+        this.migFile = join(historyDir, "migrations.jsonl");
+        this.pairFile = join(historyDir, "renames.jsonl");
+        for (const l of lines(this.migFile)) {
+            const o = l;
+            if (typeof o.undo === "string") {
+                const m = this.byId.get(o.undo);
+                if (m && typeof o.by === "string" && typeof o.at === "string")
+                    m.undone = { by: o.by, ...(o.agent ? { agent: true } : {}), ...(typeof o.person === "string" ? { person: o.person } : {}), at: o.at };
+            }
+            else if (typeof o.id === "string" && typeof o.from === "string" && typeof o.to === "string") {
+                this.migrations.push(o);
+                this.byId.set(o.id, o);
+            }
+        }
+        for (const l of lines(this.pairFile)) {
+            const o = l;
+            if (Number.isInteger(o.snap) && Array.isArray(o.pairs))
+                this.add(o.snap, o.pairs);
+        }
+    }
+    add(snap, pairs) {
+        const was = this.found.get(snap) ?? [];
+        const seen = new Set(was.map((p) => `${p.from}\u0000${p.to}`));
+        this.found.set(snap, [...was, ...pairs.filter((p) => !seen.has(`${p.from}\u0000${p.to}`))]);
+    }
+    /** The pairs found at a graph read of snapshot `snap`'s build. */
+    record(snap, pairs) {
+        if (!pairs.length)
+            return;
+        mkdirSync(join(this.pairFile, ".."), { recursive: true });
+        appendFileSync(this.pairFile, JSON.stringify({ snap, at: new Date().toISOString(), pairs }) + "\n");
+        this.add(snap, pairs);
+    }
+    get(id) {
+        return this.byId.get(id) ?? null;
+    }
+    /** A migration made: kept, under the next id. */
+    migrated(m) {
+        const full = { id: `m${this.migrations.length + 1}`, ...m };
+        mkdirSync(join(this.migFile, ".."), { recursive: true });
+        appendFileSync(this.migFile, JSON.stringify(full) + "\n");
+        this.migrations.push(full);
+        this.byId.set(full.id, full);
+        return full;
+    }
+    /** A migration undone (`person`: by someone invited by a personal link, the link's id). */
+    undone(id, by, agent, person) {
+        const m = this.byId.get(id);
+        if (!m)
+            return;
+        const at = new Date().toISOString();
+        const who = { by, ...(agent ? { agent: true } : {}), ...(person ? { person } : {}) };
+        appendFileSync(this.migFile, JSON.stringify({ undo: id, ...who, at }) + "\n");
+        m.undone = { ...who, at };
+    }
+    /** The renames of high confidence found from snapshot `from` to snapshot `to`, composed along the
+     *  builds between: a name at `from` → its name at `to`. `order`: the snapshots' ids, oldest
+     *  build first. */
+    between(from, to, order) {
+        const i = order.indexOf(from), j = order.indexOf(to);
+        const out = new Map();
+        if (i < 0 || j < 0 || j <= i)
+            return out;
+        for (const id of order.slice(i + 1, j + 1)) {
+            const step = new Map((this.found.get(id) ?? []).filter((p) => p.confidence === "high").map((p) => [p.from, p.to]));
+            // a name renamed before goes on from its name now; any other starts from its name at `from`
+            const now = new Set(out.values());
+            for (const [a, b] of out)
+                if (step.has(b))
+                    out.set(a, step.get(b));
+            for (const [a, b] of step)
+                if (!now.has(a) && !out.has(a))
+                    out.set(a, b);
+        }
+        return out;
+    }
+}
+function lines(file) {
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    for (const l of readFileSync(file, "utf8").split("\n")) {
+        if (!l.trim())
+            continue;
+        try {
+            out.push(JSON.parse(l));
+        }
+        catch {
+            // a line cut short (the server stopped while writing): left out
+        }
+    }
+    return out;
+}

package/dist/server/review.js

@@ -0,0 +1,334 @@
+// The review's storage (ReviewSpec.md, decision 5; the log design decided 2026-10-08): the site's
+// `log/` (server/dirs.ts). The site is local,
+// never committed (the owner's decision of 2026-10-13): the review is the site's, as its history is.
+//
+// One append-only log per writer, `log/<name>-<hash>.jsonl` (an agent's `….agent.jsonl`; someone
+// invited by a personal link, `<id>.person.jsonl`, whatever name they go by), one event per line
+// (shared/review.ts). A person's events go to their file, an agent's to its own —
+// its advice, and at level full whatever else it does (AgentSpec decision 9), every line marked
+// as an agent's. Nothing is ever rewritten: an event is appended, after checking that the file is the
+// size last read, so that what was written meanwhile (by hand, a restored backup) is read first and
+// never written over.
+//
+// The review is the replay of every log. The folder is looked at every second; only files whose
+// size, time or inode changed are read again. A file that only grew is parsed from where the last
+// read stopped; one that shrank or changed before that point (a rewrite, a checkout) is read whole.
+// A line that cannot be read (a line cut short, a bad edit by hand) is reported, the
+// file's other lines and the other files are read, and nothing more is appended to that file until
+// someone fixes it by hand. A line of an event the review no longer records (an explanation, since
+// 2026-10-08; a checkpoint, since 2026-10-09) is skipped, neither reported nor holding up its file.
+//
+// What changed is told as a change (`ReviewChange`): the events that came after everything replayed
+// so far, which a page applies to its own review — or, when an event came in between (older events
+// restored from a backup, a rewrite), the whole review again.
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { SITE_README } from "./dirs.js";
+import { applyEvent, emptyReview, eventOf, invalid, logFileName, merged, nameEvent, noChange, personOfLog, problemsText, readEvent } from "../shared/review.js";
+const LOG_DIR = "log";
+/** The server's own log: the moves it made of the renames it found, and the links it carried with a
+ *  cluster a build renamed (AttachmentSpec decision 6), and nothing else; a move made twice
+ *  carries nothing the second time. */
+export const SERVER_LOG = "visualproof.server.jsonl";
+/** the name the server's moves are recorded under */
+export const SERVER_WRITER = { name: "VisualProof", agent: false, server: true };
+export class ReviewStore {
+    dir;
+    logDir;
+    data = emptyReview();
+    /** this run's id, and the revision of `data`: one more at every change */
+    epoch = randomBytes(6).toString("hex");
+    rev = 0;
+    /** told of every change, after it is made (server/live.ts sends it to the pages) */
+    onChange = null;
+    files = new Map();
+    /** the replay's order: what `data` was made from */
+    order = [];
+    /** what the replay reads an event as (`setReading`): the event, unless an opinion recorded under
+     *  the kernel's content hash is bound to its version (server/versions.ts, `rebinder`). The same
+     *  object each time for the same line, so that what was replayed is still told from what is new */
+    reading = null;
+    read_ = new WeakMap();
+    /** the next commit replays every event, as `reading` changed */
+    again = false;
+    /** `dir` relative to the project, or absolute. Nothing is created until something is written. */
+    constructor(projectRoot, dir) {
+        this.dir = isAbsolute(dir) ? dir : resolve(projectRoot, dir);
+        this.logDir = join(this.dir, LOG_DIR);
+        this.refresh();
+    }
+    /** Every line that cannot be read, file by file. */
+    get problems() {
+        return [...this.files.values()].flatMap((f) => f.problems);
+    }
+    /** The problems in words (the page, /api/status); null when every line reads. */
+    get error() {
+        return problemsText(this.problems);
+    }
+    /** The whole review, as a page takes it on (re)connecting. */
+    whole() {
+        return { epoch: this.epoch, rev: this.rev, data: this.data, problems: this.problems, error: this.error };
+    }
+    /** The file a writer's events go to (shared/review.ts, logFileName). */
+    fileOf(w) {
+        return w.server ? SERVER_LOG : logFileName(w.name, w.agent, w.person ?? null);
+    }
+    /** Read the logs that changed on disk since last read; the change, or null when nothing did. */
+    refresh() {
+        let names = [];
+        try {
+            names = readdirSync(this.logDir).filter((n) => n.endsWith(".jsonl")).sort();
+        }
+        catch {
+            // no folder yet: no review yet
+        }
+        let changed = false;
+        for (const gone of [...this.files.keys()].filter((f) => !names.includes(f))) {
+            this.files.delete(gone);
+            changed = true;
+        }
+        for (const name of names)
+            if (this.read(name))
+                changed = true;
+        return changed ? this.commit() : null;
+    }
+    /** Read one log again if its stamp changed: from where the last read stopped when it only grew,
+     *  else whole. Whether anything was read. */
+    read(name) {
+        const path = join(this.logDir, name);
+        const was = this.files.get(name);
+        let buf;
+        let stamp;
+        try {
+            const st = statSync(path);
+            if (!st.isFile())
+                return this.files.delete(name);
+            stamp = `${st.size}:${st.mtimeMs}:${st.ino}`;
+            if (was?.stamp === stamp)
+                return false;
+            buf = readFileSync(path);
+        }
+        catch (e) {
+            // unreadable (permissions, gone between listing and reading): said, what was read of it is
+            // kept, nothing is written to it, and it is read again at the next look
+            const f = was ?? this.fresh(name, "");
+            f.problems = [...f.problems.filter((p) => p.line > 0), { file: name, line: 0, why: `the file cannot be read (${e instanceof Error ? e.message : String(e)})`, writer: null }];
+            f.stamp = "";
+            this.files.set(name, f);
+            return true;
+        }
+        // only grown: the bytes read before are still there, the same
+        if (was && buf.length >= was.offset && createHash("sha256").update(buf.subarray(0, was.offset)).digest("hex") === was.hash.copy().digest("hex")) {
+            was.stamp = stamp;
+            this.parse(was, buf);
+            return true;
+        }
+        const f = this.fresh(name, stamp);
+        this.files.set(name, f);
+        this.parse(f, buf);
+        return true;
+    }
+    fresh(name, stamp) {
+        return { file: name, agent: name.endsWith(".agent.jsonl"), person: personOfLog(name), server: name === SERVER_LOG, stamp, offset: 0, hash: createHash("sha256"), lines: 0, events: [], tail: null, problems: [] };
+    }
+    /** Parse what follows `f.offset` in `buf`: whole lines become events (or problems), the rest is
+     *  the tail. */
+    parse(f, buf) {
+        // a tail read before is read again with what came after it, and a file that could not be read
+        // before is no longer said to be unreadable
+        f.tail = null;
+        f.problems = f.problems.filter((p) => p.line > 0 && p.line <= f.lines);
+        const take = (text, line, last) => {
+            let raw;
+            try {
+                raw = JSON.parse(text);
+            }
+            catch {
+                f.problems.push({ file: f.file, line, why: last ? `the last line is cut short (${clip(text)})` : `not an event (${clip(text)})`, writer: null });
+                return null;
+            }
+            let e = readEvent(raw, f.agent, f.person);
+            // the server writes the moves it found there, and the links it carried with a cluster a build
+            // renamed (AttachmentSpec decision 6); they are written nowhere else
+            if (e && typeof e !== "string" && f.server !== serversOwn(e))
+                e = f.server ? "the server's log holds the moves it found and the links it carried, nothing else" : "a move the server found, or a link it carried, outside its own log";
+            // an event of a kind no longer recorded is skipped: read, not a problem
+            if (e === null || typeof e !== "string")
+                return e;
+            f.problems.push({ file: f.file, line, why: `${e} (${clip(text)})`, writer: null });
+            return null;
+        };
+        let at = f.offset;
+        for (;;) {
+            const nl = buf.indexOf(10, at);
+            if (nl < 0)
+                break;
+            f.hash.update(buf.subarray(at, nl + 1));
+            const text = buf.subarray(at, nl).toString("utf8").replace(/\r$/, "");
+            f.lines++;
+            if (text.trim()) {
+                const e = take(text, f.lines, false);
+                if (e)
+                    f.events.push(e);
+            }
+            at = nl + 1;
+        }
+        f.offset = at;
+        if (at < buf.length) {
+            const text = buf.subarray(at).toString("utf8");
+            f.tail = { bytes: buf.length - at, event: text.trim() ? take(text, f.lines + 1, true) : null };
+        }
+        // whose log it is, as its good lines say
+        const who = f.events[0]?.by ?? f.tail?.event?.by ?? null;
+        for (const p of f.problems)
+            p.writer = who;
+    }
+    /** Replay what was read, and say what changed: the new events alone where they all come after
+     *  what was replayed before, else the whole review. A log read whole again has events of its own
+     *  (new objects), and one gone has none: either way what was replayed is no longer where it was,
+     *  and the review is replayed whole. */
+    commit() {
+        const logs = [...this.files.values()].map((f) => ({ file: f.file, events: f.tail?.event ? [...f.events, f.tail.event] : f.events }));
+        const next = merged(logs).map((x) => this.readAs(x.e));
+        const before = this.order;
+        const appended = !this.again && next.length >= before.length && before.every((e, k) => next[k] === e);
+        this.again = false;
+        const base = this.rev;
+        this.rev++;
+        this.order = next;
+        let events = null;
+        if (appended) {
+            events = next.slice(before.length);
+            for (const e of events)
+                applyEvent(this.data, e);
+        }
+        else {
+            this.data = emptyReview();
+            for (const e of next)
+                applyEvent(this.data, e);
+        }
+        const c = { epoch: this.epoch, base, rev: this.rev, events, problems: this.problems };
+        this.onChange?.(c);
+        return c;
+    }
+    readAs(e) {
+        if (!this.reading)
+            return e;
+        let r = this.read_.get(e);
+        if (!r)
+            this.read_.set(e, (r = this.reading(e)));
+        return r;
+    }
+    /** Read every event through `reading` from now on (a new graph, or new renames, change what an
+     *  opinion recorded under the kernel's hash is bound to): the whole review is replayed, and the
+     *  pages are told. */
+    setReading(reading) {
+        this.reading = reading;
+        this.read_ = new WeakMap();
+        this.again = true;
+        return this.commit();
+    }
+    /** When a new event is recorded: now — or, where the last event replayed is as late (another
+     *  writer in the same millisecond), just after it, so that what is appended comes after what was
+     *  replayed and pages are sent the new event alone. A clock far ahead is not followed. */
+    nextTime() {
+        const now = Date.now();
+        const last = this.order.length ? Date.parse(this.order[this.order.length - 1].at) : 0;
+        return new Date(last >= now && last - now < 1000 ? last + 1 : now).toISOString();
+    }
+    /** Record a (checked) request under its writer's name: one line appended to their log, never
+     *  anything rewritten. Refused when their log has a line that cannot be read, until it is fixed
+     *  by hand; a request that changes nothing (a target marked that is one) appends nothing. */
+    append(who, r, toolchain) {
+        const why = invalid(r);
+        if (why)
+            return { status: 400, error: why };
+        const w = { name: who.name.trim(), agent: who.agent, person: who.person ?? null, server: who.server };
+        if (r.by.trim() !== w.name || !!r.agent !== w.agent || (r.person ?? null) !== w.person)
+            return { status: 400, error: "an event is recorded under the name and kind of who asks" };
+        if (!!w.server !== serversOwn(r))
+            return { status: 400, error: "the server records the moves it found and the links it carried, and only it does" };
+        // what someone else wrote meanwhile comes first
+        this.refresh();
+        if (noChange(this.data, r))
+            return { change: null, unchanged: true };
+        return this.write(this.fileOf(w), () => eventOf(this.data, r, toolchain, this.nextTime()));
+    }
+    /** Someone invited by a personal link renamed themselves (CollabSpec decision 9): their log says
+     *  so, a `name` line, so that everything they wrote shows under the new name on every replica.
+     *  Nothing is written for someone who has no log yet — their first line will carry the name — nor
+     *  when the log says that name already. */
+    named(person, name) {
+        this.refresh();
+        const file = logFileName(name, false, person);
+        const now = Object.hasOwn(this.data.people, person) ? this.data.people[person].name : null;
+        if (!this.files.has(file) || now === name.trim())
+            return { change: null, unchanged: true };
+        return this.write(file, () => nameEvent(person, name, this.nextTime()));
+    }
+    /** Append the event `make` gives to log `file`: one line, once the file is as it was last read —
+     *  else what someone else wrote is read first, and the event made again. Refused while the file
+     *  has a line that cannot be read. */
+    write(file, make) {
+        for (let tries = 0; tries < 3; tries++) {
+            const f = this.files.get(file);
+            if (f?.problems.length) {
+                const p = f.problems[0];
+                return {
+                    status: 409,
+                    error: `Your review log (log/${file} in ${this.dir}) has a line that cannot be read — line ${p.line}: ${p.why}. ` +
+                        "Nothing more is written to it until it is fixed by hand; nothing in it was changed.",
+                };
+            }
+            const e = make();
+            const expected = f ? f.offset + (f.tail?.bytes ?? 0) : 0;
+            // a last line without its newline (written by hand) ends before this one starts
+            const line = Buffer.from((f?.tail?.bytes ? "\n" : "") + JSON.stringify(e) + "\n", "utf8");
+            if (!existsSync(this.logDir)) {
+                mkdirSync(this.logDir, { recursive: true });
+                // what the folder is, for whoever finds it (with the first log, where the
+                // server did not make the folder; one already there is left as it is)
+                try {
+                    writeFileSync(join(this.dir, "README.md"), SITE_README, { flag: "wx" });
+                }
+                catch {
+                    // there is one
+                }
+            }
+            const fd = openSync(join(this.logDir, file), "a");
+            let wrote = false;
+            try {
+                // the file is as last read, or someone else wrote to it: that is read first, then this
+                // is tried again
+                if (fstatSync(fd).size === expected) {
+                    writeSync(fd, line);
+                    wrote = true;
+                }
+            }
+            finally {
+                closeSync(fd);
+            }
+            if (!wrote) {
+                this.refresh();
+                continue;
+            }
+            const c = this.refresh();
+            if (!c)
+                return { status: 500, error: "the review log was written but could not be read back" };
+            return { change: c, event: e };
+        }
+        return { status: 409, error: `Your review log (log/${file}) kept changing while this was written; try again.` };
+    }
+}
+/** Whether an event is one only the server writes, in its own log: a move of a rename it found, or
+ *  a link it carried with a cluster a build renamed as a whole (server/library.ts); each says why
+ *  (`auto`). */
+function serversOwn(e) {
+    return (e.op === "move" || e.op === "link-edit") && e.auto !== undefined;
+}
+/** A line's start, as a problem quotes it. */
+function clip(text) {
+    const t = text.trim();
+    return t.length > 60 ? `${t.slice(0, 57)}…` : t;
+}