visualproof 0.0.0-stage → 0.2.0

package/dist/server/askfollow.js

@@ -0,0 +1,286 @@
+// Asking others to follow (CollabSpec decision 10, AgentSpec decision 8; the owner's decisions of
+// 2026-10-12). A reader with a name who is visible, or an agent at level advise or full, asks
+// everyone on the server — private readers too, who are counted, never named — or one person to
+// follow them. The server relays the request to each page asked as one of its live events (`ask`),
+// and each page's answer to the asking page (`ask-answer`) or to the agent, which waits for them; it
+// holds each asker to one request per 30 s, and checks who may ask. A page shows one request at a
+// time: a newer one, from another asker, replaces it there, and the one replaced counts as not
+// answered. A request ends when every page asked has answered or its 30 s are over (and a little
+// more, for an answer on its way); its asker leaving, or going private, withdraws it. Nothing is
+// kept past a request's life but when each asker last asked, for the 30 s that it counts.
+//
+// The server does not know who follows whom — following is the page's own (web/src/people.ts) — so
+// a page asked whose reader follows the asker already answers so at once (`following`), shows
+// nothing, and is not counted as asked.
+//
+// The agents' endpoint (POST /api/agent/ask-follow) is server/agent.ts's, in its shape
+// (server/agentviews.ts, AgentEndpoint), as the notes' are (server/agentnotes.ts).
+import { randomBytes } from "node:crypto";
+import { sameName } from "../shared/collab.js";
+import { ASK_GRACE_MS, ASK_MS, ASK_WORDS, askLine, cleanAnswer, foldAnswers } from "../shared/askfollow.js";
+import { fail, whoOf } from "./agent.js";
+import { agentKey } from "./presence.js";
+/** The key a name counts under: whatever the case, however Unicode writes it (shared/collab.ts,
+ *  sameName). */
+const nameKey = (s) => s.trim().normalize("NFKC").toLowerCase();
+export class Asks {
+    port;
+    ms;
+    grace;
+    requests = new Map();
+    /** the request each page shows, by its stream's secret, while it has not answered it */
+    showing = new Map();
+    /** when each asker last asked, kept only while it counts */
+    last = new Map();
+    now = () => Date.now();
+    constructor(port, opts = {}) {
+        this.port = port;
+        this.ms = opts.ms ?? ASK_MS;
+        this.grace = opts.grace ?? ASK_GRACE_MS;
+    }
+    /** How many requests are going on: none is kept past its life. */
+    get pending() {
+        return this.requests.size;
+    }
+    /** Seconds before `asker` may ask again; 0 when they may. What no longer counts is forgotten. */
+    retryAfter(asker) {
+        const now = this.now();
+        for (const [k, at] of this.last)
+            if (now - at >= this.ms)
+                this.last.delete(k);
+        const since = Math.max(-Infinity, ...asker.rate.map((k) => this.last.get(k) ?? -Infinity));
+        return Number.isFinite(since) ? Math.max(1, Math.ceil((since + this.ms - now) / 1000)) : 0;
+    }
+    /** Ask `whom` to follow `asker`: the request is told to every page of theirs at once, the one each
+     *  showed replaced. Nobody there to ask is no request, and does not count for the rate. */
+    ask(asker, whom) {
+        const wait = this.retryAfter(asker);
+        if (wait)
+            return { status: 429, error: `You asked a moment ago: one request every ${Math.round(this.ms / 1000)} s. Ask again in ${wait} s.`, hint: `Wait ${wait} s.`, retryAfter: wait };
+        const found = this.whom(asker, whom);
+        if (!Array.isArray(found))
+            return found;
+        if (!found.length)
+            return { ok: { id: null, asked: [], private: 0, ms: this.ms, report: { id: null, pages: 0, people: [], private: { asked: 0 }, summary: "Nobody is on the page to ask." } } };
+        for (const k of asker.rate)
+            this.last.set(k, this.now());
+        const id = randomBytes(9).toString("base64url");
+        const r = { id, asker, targets: new Map(found.map((s) => [s.token, { was: s, answer: null }])), timer: setTimeout(() => this.expire(id), this.ms + this.grace), waiters: new Set() };
+        r.timer.unref?.();
+        this.requests.set(id, r);
+        const told = { id, from: asker.from, name: asker.name, ...(asker.agent ? { agent: true } : {}), ...(asker.verified ? { verified: true } : {}), ms: this.ms };
+        for (const s of found) {
+            // the request this page showed is replaced by this one, from the newest asker: not answered
+            const was = this.showing.get(s.token);
+            if (was && was !== id)
+                this.answered(was, s.token, "timeout");
+            this.showing.set(s.token, id);
+            this.port.send(s.token, "ask", told);
+        }
+        return { ok: { id, asked: found.filter((s) => !s.private).map((s) => s.id), private: found.filter((s) => s.private).length, ms: this.ms, report: this.report(r) } };
+    }
+    /** The pages `whom` names, but the asker's own; or why there are none to name. */
+    whom(asker, whom) {
+        const streams = this.port.streams();
+        // the asker's own pages: the one that asks, and the others of a person of their name
+        const own = (s) => s.token === asker.stream || (!asker.agent && !s.private && s.name !== null && sameName(s.name, asker.name) && s.verified === asker.verified);
+        const pagesOf = (s) => (s.name === null ? [s] : streams.filter((x) => !x.private && x.name !== null && sameName(x.name, s.name) && x.verified === s.verified));
+        const peers = this.port.peers();
+        if ("everyone" in whom)
+            return streams.filter((s) => !own(s));
+        if ("page" in whom) {
+            const p = peers.find((x) => x.id === whom.page);
+            if (p?.agent)
+                return { status: 409, error: `${p.name} is an agent: agents cannot be asked to follow.`, hint: "Ask a person." };
+            const s = streams.find((x) => x.id === whom.page && !x.private);
+            if (!p || !s)
+                return { status: 404, error: "That reader is not here any more.", hint: "Ask someone among the initials at the top right." };
+            if (own(s))
+                return { status: 400, error: "That is you.", hint: "Ask someone else." };
+            return pagesOf(s).filter((x) => !own(x));
+        }
+        const named = streams.filter((s) => !s.private && s.name !== null && sameName(s.name, whom.name));
+        if (!named.length) {
+            if (peers.some((p) => p.agent && p.name !== null && sameName(p.name, whom.name)))
+                return { status: 409, error: `${whom.name} is an agent: agents cannot be asked to follow.`, hint: "Ask a person." };
+            const names = [...new Set(streams.flatMap((s) => (!s.private && s.name !== null && !own(s) ? [s.name] : [])))].sort();
+            return { status: 404, error: `Nobody called ${whom.name} is on the page.`, hint: names.length ? `GET /api/agent/companion lists the people here: ${names.join(", ")}.` : "Nobody else is on the page now; GET /api/agent/companion?wait=60 tells you when someone comes.", didYouMean: names.slice(0, 5) };
+        }
+        const mine = named.filter((s) => !own(s));
+        return mine.length ? mine : { status: 400, error: "That is you.", hint: "Ask someone else." };
+    }
+    /** A page answers, by its stream's secret: once, a request it was asked and that goes on. */
+    answer(token, id, answer) {
+        const a = cleanAnswer(answer);
+        if (!a)
+            return { status: 400, body: { error: "answer is follow, decline, timeout or following." } };
+        const r = typeof id === "string" ? this.requests.get(id) : undefined;
+        if (!r)
+            return { status: 404, body: { error: "This request is over." } };
+        const t = r.targets.get(token);
+        if (!t)
+            return { status: 403, body: { error: "This page was not asked." } };
+        if (t.answer)
+            return { status: 409, body: { error: "This page answered already." } };
+        this.answered(r.id, token, a);
+        return { status: 200, body: { ok: true } };
+    }
+    /** Waits for request `id` to end, and resolves to what it came to; at once where it is over or
+     *  unknown (null), or when `signal` aborts (what it came to so far). */
+    settled(id, signal) {
+        const r = this.requests.get(id);
+        if (!r)
+            return Promise.resolve(null);
+        return new Promise((done) => {
+            const end = (rep) => {
+                r.waiters.delete(end);
+                signal?.removeEventListener("abort", stop);
+                done(rep);
+            };
+            const stop = () => end(this.report(r));
+            r.waiters.add(end);
+            signal?.addEventListener("abort", stop, { once: true });
+        });
+    }
+    /** A page's event stream closed: what it was asked is not answered, and what it asked is withdrawn. */
+    closed(token) {
+        this.withdraw(token, false);
+        for (const r of [...this.requests.values()])
+            if (r.targets.get(token)?.answer === null)
+                this.answered(r.id, token, "timeout");
+        this.showing.delete(token);
+    }
+    /** The page that asked can no longer be followed — it went private, or closed (`told` false: it is
+     *  not there to tell): its requests end, each page that has not answered is told so (`ask-end`),
+     *  and the asker that it did not. */
+    withdraw(token, told = true) {
+        for (const r of [...this.requests.values()]) {
+            if (r.asker.stream !== token)
+                continue;
+            for (const [tok, t] of r.targets) {
+                if (t.answer)
+                    continue;
+                if (this.showing.get(tok) === r.id)
+                    this.showing.delete(tok);
+                this.port.send(tok, "ask-end", { id: r.id });
+                if (told)
+                    this.answered(r.id, tok, "timeout");
+            }
+            this.finish(r);
+        }
+    }
+    /** Page `token`'s answer to request `id`: kept, and told to whoever asked. */
+    answered(id, token, answer) {
+        const r = this.requests.get(id);
+        const t = r?.targets.get(token);
+        if (!r || !t || t.answer)
+            return;
+        t.answer = answer;
+        if (this.showing.get(token) === id)
+            this.showing.delete(token);
+        if (r.asker.stream) {
+            // a page is named as the others know it now: a private one by nobody
+            const now = this.port.streams().find((s) => s.token === token) ?? t.was;
+            this.port.send(r.asker.stream, "ask-answer", { id, from: now.private ? null : now.id, answer });
+        }
+        if ([...r.targets.values()].every((x) => x.answer))
+            this.finish(r);
+    }
+    /** The request's time is over: the pages that have not answered did not, and are told it ended. */
+    expire(id) {
+        const r = this.requests.get(id);
+        if (!r)
+            return;
+        for (const [tok, t] of r.targets) {
+            if (t.answer)
+                continue;
+            this.port.send(tok, "ask-end", { id });
+            this.answered(id, tok, "timeout");
+        }
+        this.finish(r);
+    }
+    /** The request is over: whoever waits for it is told what it came to, and nothing of it is kept. */
+    finish(r) {
+        if (!this.requests.has(r.id))
+            return;
+        clearTimeout(r.timer);
+        this.requests.delete(r.id);
+        for (const [tok] of r.targets)
+            if (this.showing.get(tok) === r.id)
+                this.showing.delete(tok);
+        const rep = this.report(r);
+        for (const w of [...r.waiters])
+            w(rep);
+    }
+    /** What request `r` came to so far, person by person. */
+    report(r) {
+        const people = new Map();
+        const priv = [];
+        for (const [tok, t] of r.targets) {
+            if (t.was.private) {
+                priv.push(t.answer);
+                continue;
+            }
+            const key = t.was.name === null ? `s:${tok}` : `${t.was.verified ? "v" : "n"}:${nameKey(t.was.name)}`;
+            const p = people.get(key) ?? { name: t.was.name, verified: t.was.verified, answers: [] };
+            p.answers.push(t.answer);
+            people.set(key, p);
+        }
+        const states = [];
+        const out = [...people.values()].map((p) => {
+            const s = foldAnswers(p.answers);
+            states.push(s);
+            return { name: p.name, ...(p.verified ? { verified: true } : {}), answer: ASK_WORDS[s] };
+        });
+        const counts = {};
+        for (const a of priv) {
+            const s = foldAnswers([a]);
+            states.push(s);
+            counts[ASK_WORDS[s]] = (counts[ASK_WORDS[s]] ?? 0) + 1;
+        }
+        return { id: r.id, pages: r.targets.size, people: out, private: { asked: priv.length, ...counts }, summary: askLine(states) ?? (states.length ? "Everyone asked follows you already." : "Nobody was asked.") };
+    }
+}
+/** The agents' endpoint (AgentSpec decision 8): an agent at level advise or full asks everyone on
+ *  the page, or one person, to follow it, and waits for their answers. */
+export function askEndpoints(world, refuse) {
+    return [
+        {
+            method: "POST",
+            path: "/api/agent/ask-follow",
+            needs: "advise",
+            about: "Ask the people on the page to follow you (the owner's decision of 2026-10-12): everyone — private readers too, counted, never named — or one person (who). Each sees a banner for 30 s, \"<you> (agent) asks you to follow · Follow · Not now\", with your mark; following you opens your conversation. Those following you already are not asked. One request every 30 s. The answer waits for theirs, at most the 30 s the request lasts (wait: false answers at once): who follows you now, who declined, who did not answer. Agents cannot be asked to follow.",
+            params: { who: "optional: a person's name, as GET /api/agent/companion lists people; left out, everyone on the page", wait: "false: answer at once, with whom it asked, without their answers (default: wait for them, at most 30 s)" },
+            returns: "{ok, id, pages, people: [{name, verified?, answer: following|declined|no answer|already following|waiting}], private: {asked, following?, declined?, no answer?, already following?, waiting?}, summary, waited} — 429 with retryAfter within 30 s of your last request",
+            run: async (a) => {
+                const c = a.caller;
+                if (c.kind !== "agent")
+                    return fail(400, "This API records what agents do: say you are one.", "Send X-VisualProof-Kind: agent with every request, beside X-VisualProof-Name.");
+                if (!c.name)
+                    return fail(401, "Say who you are first: a request to follow says who asks.", "Send X-VisualProof-Name: <your name>, e.g. Claude.", { who: true });
+                const no = refuse(c, "advise");
+                if (no)
+                    return no;
+                if (!world.asks)
+                    return fail(404, "This server relays no requests to follow.", "Point people at what you look at with a note, or a link (POST /api/agent/view/link).");
+                // people follow the agent's entry in presence: one not listed could not be followed
+                const from = agentKey(whoOf(c));
+                if (!world.presence.list().some((p) => p.id === from))
+                    return fail(409, "You are not among the people on the page, so nobody could follow you.", "Agents without a token of their own are listed 32 at most; ask again once one has gone, or ask for a token (Share, then AI agent, in the page).");
+                const b = a.body && typeof a.body === "object" && !Array.isArray(a.body) ? a.body : {};
+                if (b.who !== undefined && b.who !== null && (typeof b.who !== "string" || !b.who.trim()))
+                    return fail(400, "who is a person's name.", "GET /api/agent/companion lists the people on the page by name; leave who out to ask everyone.");
+                if (b.wait !== undefined && typeof b.wait !== "boolean")
+                    return fail(400, "wait is true or false.", "Leave it out to wait for the answers.");
+                const whom = typeof b.who === "string" ? { name: b.who.trim() } : { everyone: true };
+                const r = world.asks.ask({ name: c.name, verified: false, agent: true, from, stream: null, rate: [c.token ? `t:${c.token.id}` : `a:${nameKey(c.name)}`] }, whom);
+                if (!("ok" in r))
+                    return fail(r.status, r.error, r.hint, { ...(r.retryAfter ? { retryAfter: r.retryAfter } : {}), ...(r.didYouMean ? { didYouMean: r.didYouMean } : {}) }, r.retryAfter ? { "retry-after": String(r.retryAfter) } : undefined);
+                const t0 = Date.now();
+                const sent = r.ok;
+                const rep = sent.id && b.wait !== false ? ((await world.asks.settled(sent.id, a.signal)) ?? sent.report) : sent.report;
+                return { status: 200, body: { ok: true, ...rep, waited: Math.round((Date.now() - t0) / 100) / 10 } };
+            },
+        },
+    ];
+}

package/dist/server/boardspots.js

@@ -0,0 +1,159 @@
+// Where a view's board draws what its exported document prints (the owner's decisions of 2026-10-12:
+// the board is the outline of the document; shared/doc/order.ts orders by it), read on the server as
+// a page draws the board at rest, so that an export from the page, from an agent or of a past build
+// follows the board everyone on it sees.
+//
+// The board is laid out as the page lays it out (shared/board.ts): the server's layout for a board of
+// the whole project, else the view's layout memory recalled — the server keeps it, as the pages hand
+// it over — and, where no page has laid the board out for what it holds now (a view never opened, a
+// new build, a review that changed what a scope holds), laid out from that memory by the same pure
+// functions the page runs, which gives the picture the next page will show; nothing is handed over,
+// since exporting only reads. A board of a past build is laid out as the Time Machine lays it out
+// (web/src/timemachine.ts): from the view's memory of that build, else from its memory or the latest
+// build's layout of the whole project, a declaration renamed since read under its name then. The
+// view's pins are then applied by the page's own scene (web/src/scene.ts, which is pure): what is
+// dropped stays where it was dropped and its neighbours make room, as the page draws them.
+//
+// What a page draws that the server does not read: folds, which gather a cluster's contents into a
+// disc and slide its neighbours inward — the document prints everything whatever is folded, so its
+// order is the board's with nothing folded; a reader's visitors and their temporary clusters, which
+// are theirs alone; the easing of things still moving; and a drag not let go yet. A note on the ring
+// is read where it points — the angle it was let go at, else that of what it is about — on the
+// innermost ring, as when the board is zoomed in so far that one ring holds every note; one that
+// points nowhere is at the top of the ring, in the order notes were written.
+import { boardSet, edgesOf, layoutKey, pastSetKey, recalled, wholeLayout, boardLayout } from "../shared/board.js";
+import { computeLayout, memoryOf, stabilize } from "../shared/layout.js";
+import { declSpot } from "../shared/notecard.js";
+import { aboutMembers, existsIn, itemSpot, itemWhy, linkedOn, linksByFile, noteBoard, viewSpot } from "../shared/noteplace.js";
+import { aboutAngle, ringAround, ringRadians } from "../shared/ring.js";
+import { fixedScope } from "../shared/views.js";
+import { renamedMemory } from "../web/src/past.js";
+import { Scene } from "../web/src/scene.js";
+/** a declaration on the ring's edge, as the page counts it there (web/src/sticky.ts, ringNow) */
+const LEAF_RING_R = 8;
+/** the most declarations the centre of what a note on the ring is about is taken over, every so
+ *  many of them beyond, as the page samples them (web/src/sticky.ts) */
+const ABOUT_MOST = 4000;
+/** The board of view `b.rec` as its page draws it at rest, nothing folded: where each declaration,
+ *  circle and note is (shared/doc/order.ts). */
+export function boardSpots(b) {
+    const { g, review, rec } = b;
+    const mode = rec.clustering;
+    const hidden = rec.hidden[mode] ?? [];
+    const bs = boardSet(g, review, rec.scope);
+    const G = bs.sub ? bs.sub.graph : g;
+    let L;
+    let fresh = false;
+    if (b.past) {
+        const key = pastSetKey(b.past.snapshot, layoutKey(bs.key, hidden));
+        const quick = recalled(G, mode, key, b.memory, hidden);
+        if (quick)
+            L = quick.layout;
+        else {
+            // laid out from the view's memory; with none, from the latest build's layout where the view's
+            // board of now is the whole project (the Time Machine's `wholeNow`), else afresh
+            const whole = !b.memory && !!b.whole && boardSet(b.past.now, b.past.nowReview, rec.scope).whole;
+            const base = b.memory ? b.memory.mem : whole ? memoryOf(wholeLayout(b.whole, b.past.now.nodes, mode, hidden), b.past.now.nodes) : null;
+            L = stabilize(computeLayout(mode, G.nodes, edgesOf(G), hidden), G.nodes, base && renamedMemory(base, b.past.nowName));
+            fresh = true;
+        }
+    }
+    else if (bs.whole && b.whole)
+        L = wholeLayout(b.whole, G.nodes, mode, hidden);
+    else {
+        const quick = recalled(G, mode, layoutKey(bs.key, hidden), b.memory, hidden);
+        L = quick ? quick.layout : boardLayout(G, mode, bs.key, b.memory, hidden).layout;
+        fresh = !quick;
+    }
+    // the pins applied as the page applies them, nothing folded
+    const S = new Scene(L);
+    S.restore(rec.pins[mode] ?? { nodes: {}, clusters: {} }, [], (i) => G.nodes[i].name);
+    const decls = new Map();
+    for (let i = 0; i < G.n; i++)
+        decls.set(G.nodes[i].name, [S.nwx[i], S.nwy[i]]);
+    const clusters = new Map();
+    L.clusters.forEach((c, k) => clusters.set(c.key, [S.cwx[k], S.cwy[k]]));
+    // the notes the view shows, each where the page draws its icon (web/src/sticky.ts, render)
+    const nb = noteBoard(L, mode, G.nodes);
+    const exists = existsIn(g.nodes);
+    const links = linksByFile(review.links);
+    const view = { all: fixedScope(rec), items: rec.items };
+    const index = new Map(L.clusters.map((c, k) => [c.key, k]));
+    const chain = (c) => {
+        const out = [];
+        for (let x = c; x >= 0; x = L.clusters[x].parent)
+            out.push(L.clusters[x].key);
+        return out;
+    };
+    let ring;
+    const ringOf = () => (ring ??= ringAround([...S.rootC.map((c) => ({ x: S.cwx[c], y: S.cwy[c], r: S.drawnR[c] })), ...S.rootN.map((i) => ({ x: S.nwx[i], y: S.nwy[i], r: LEAF_RING_R }))]));
+    /** Where a note on the ring is read: where it points on the innermost ring, else its top. */
+    const onRing = (spot) => {
+        const R = ringOf();
+        if (!R)
+            return [0, 0];
+        let a = spot && spot.angle !== null ? ringRadians(spot.angle) : null;
+        if (a === null && spot?.about) {
+            let about = aboutMembers(nb, spot.about);
+            if (about.length > ABOUT_MOST)
+                about = about.filter((_, k) => k % Math.ceil(about.length / ABOUT_MOST) === 0);
+            if (about.length) {
+                let x = 0, y = 0;
+                for (const j of about)
+                    [x, y] = [x + S.nwx[j], y + S.nwy[j]];
+                a = aboutAngle(R, [x / about.length, y / about.length]);
+            }
+        }
+        const t = a ?? -Math.PI / 2;
+        return [R.x + R.r * Math.cos(t), R.y + R.r * Math.sin(t)];
+    };
+    const notes = [];
+    const seen = new Set();
+    const place = (note, kind, spot) => {
+        if (!spot || seen.has(note.id))
+            return;
+        seen.add(note.id);
+        // attached to a declaration the board holds: printed after it, its icon at its offset from the
+        // point, a place on the board in its units, as the page draws it
+        const on = note.decl && nb.index.get(note.decl.name);
+        if (note.decl && on !== undefined) {
+            notes.push({ note, kind, at: declSpot([S.nwx[on], S.nwy[on]], note.decl.at), in: chain(L.cluster[on]), on: note.decl.name });
+            return;
+        }
+        switch (spot.at) {
+            case "cluster": {
+                // a fraction of the radius drawn
+                const R = S.drawnR[spot.c];
+                notes.push({ note, kind, at: [S.cwx[spot.c] + spot.f[0] * R, S.cwy[spot.c] + spot.f[1] * R], in: chain(spot.c) });
+                return;
+            }
+            case "offset": {
+                // kept inside its circle, however the circle changed since it was put there
+                const R = S.drawnR[spot.c];
+                const len = Math.hypot(spot.d[0], spot.d[1]);
+                const f = len > R ? R / len : 1;
+                notes.push({ note, kind, at: [S.cwx[spot.c] + spot.d[0] * f, S.cwy[spot.c] + spot.d[1] * f], in: chain(spot.c) });
+                return;
+            }
+            case "world":
+                notes.push({ note, kind, at: [spot.x, spot.y], in: [] });
+                return;
+            case "ring":
+                notes.push({ note, kind, at: onRing(spot), in: [] });
+                return;
+            default:
+                // a place this reading does not know: at the start, at the top of the ring
+                notes.push({ note, kind, at: onRing(null), in: [] });
+        }
+    };
+    for (const n of b.notes) {
+        const why = itemWhy(n, view, nb, exists, links);
+        place(n, "project", why ? itemSpot(n, nb, exists, linkedOn(n, nb, links)) : null);
+    }
+    for (const n of rec.notes ?? [])
+        place(n, "view", viewSpot(n, nb, (key) => index.get(key) ?? -1));
+    // in the order they were written, which is the order of those level on the board: the notes that
+    // point nowhere on the ring, at its top
+    notes.sort((x, y) => (x.note.at < y.note.at ? -1 : x.note.at > y.note.at ? 1 : 0));
+    return { decls, clusters, notes, ...(fresh ? { fresh: true } : {}) };
+}

package/dist/server/dirs.js

@@ -0,0 +1,175 @@
+// Where the server keeps what it writes, in two places (the owner's decision of 2026-10-13): the
+// site and the cache. Nothing is written into the project, and nothing into this repository.
+//
+//   site   what one running VisualProof site holds, which cannot be derived again: the review's
+//          logs (`log/`, server/review.ts), the history of the builds it saw, the library's files,
+//          the views and their layouts (and the notes they keep), the timeline, the TCB baselines,
+//          conversations with agents, agents' tokens, personal links. Local: it holds secrets, and
+//          is backed up, never committed
+//   cache  what a rebuild makes again: extractions, the usage pass's results, the prepared views,
+//          what was read of the library's files, typeset documents, Lean's language server's
+//          folder; and, shared by every project, the Lean programs compiled per toolchain and the
+//          page's bundle
+//
+// The site is one folder, `--site` (relative to the current directory, or absolute; by default
+// `<data home>/sites/<key>`), made with a README that says what it is; one server at a time holds
+// it (`.lock`). The caches are under one root, `--cache` (by default the cache home): the project's
+// in `projects/<key>`, the Lean programs in `lean/`, the page's bundle in `web/`. The homes follow
+// the platform, and `XDG_DATA_HOME` / `XDG_CACHE_HOME` when set, on any platform.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+const here = () => ({ platform: process.platform, env: process.env, home: homedir() });
+/** Where VisualProof keeps its sites. */
+export function dataHome(h = here()) {
+    if (h.env.XDG_DATA_HOME)
+        return join(h.env.XDG_DATA_HOME, "visualproof");
+    if (h.platform === "darwin")
+        return join(h.home, "Library", "Application Support", "visualproof");
+    if (h.platform === "win32")
+        return join(h.env.LOCALAPPDATA ?? join(h.home, "AppData", "Local"), "visualproof", "data");
+    return join(h.home, ".local", "share", "visualproof");
+}
+/** Where VisualProof keeps its caches. */
+export function cacheHome(h = here()) {
+    if (h.env.XDG_CACHE_HOME)
+        return join(h.env.XDG_CACHE_HOME, "visualproof");
+    if (h.platform === "darwin")
+        return join(h.home, "Library", "Caches", "visualproof");
+    if (h.platform === "win32")
+        return join(h.env.LOCALAPPDATA ?? join(h.home, "AppData", "Local"), "visualproof", "cache");
+    return join(h.home, ".cache", "visualproof");
+}
+/** A project's name among the others: its folder's name and a hash of its path. */
+export function projectKey(root) {
+    return `${basename(root)}-${createHash("sha1").update(root).digest("hex").slice(0, 8)}`;
+}
+/** The folders of the project at `root`: its site where `site` says (relative to the current
+ *  directory, as `--cache` is: the owner's decision of 2026-10-14) or
+ *  under the data home, its caches under `cacheRoot` or the cache home. */
+export function projectDirs(root, site, cacheRoot, h = here()) {
+    const cache = cacheRoot ? resolve(cacheRoot) : cacheHome(h);
+    return {
+        site: site === null ? join(dataHome(h), "sites", projectKey(root)) : resolve(site),
+        cache: join(cache, "projects", projectKey(root)),
+        lean: join(cache, "lean"),
+    };
+}
+/** What the site's folder is, for whoever finds it in the project: written when the folder is
+ *  made (by the server, or with the first log), one already there left as it is. */
+export const SITE_README = `# This VisualProof site's folder
+
+VisualProof keeps here what this site holds of the project: what reviewers said about its
+declarations (\`log/\`), the history of the builds it saw, the library's files, the views and their
+layouts, the timeline, conversations with agents, agents' tokens and personal links.
+
+It is local. It holds secrets (agents' tokens, personal links): it is not meant to be committed.
+Back it up: none of it can be derived again. What VisualProof can derive again is in its cache
+(\`--cache\`), not here.
+
+- \`log/\` holds one file per writer: \`<name>-<hash>.jsonl\` for a person,
+  \`<name>-<hash>.agent.jsonl\` for an AI agent: its opinions are advice, never counted; what else
+  it did (a target, a key declaration, a trusted prefix) counts as a person's would, and is shown
+  as an agent's. The hash is of the writer's exact name, which every line carries; the file's
+  name is only a container.
+- Someone invited by a personal link writes to \`<id>.person.jsonl\`, the id being their link's:
+  every line carries it (\`person\`) beside the name it was written under, and a \`name\` line says
+  they go by another name from then on. All they wrote shows under the latest.
+- \`log/visualproof.server.jsonl\` is VisualProof's own: the renames it found between two builds,
+  each a move that carries what was said of the declaration to its new name, and the links it
+  carried to a cluster a build renamed as a whole.
+- Each line is one event: an opinion on a declaration (bound to its version), a target marked
+  or taken off, a prefix trusted without review or no longer, a key declaration of a target marked
+  or unmarked, a move of what was said of one declaration to another (or its undoing), a file
+  added to the project's library (named by its SHA-256: its bytes are kept beside, in \`files/\`)
+  and its title, archiving and restoring, a link from a declaration or a cluster to a place in one,
+  edited or removed.
+- Files are only ever appended to, each writer to their own.
+- The review is what replaying every file gives: one writer's events in the order of their file,
+  different writers' by time.
+- Do not edit a line by hand. A line VisualProof cannot read (a line cut short) is reported;
+  nothing more is written to that file until it is fixed by hand.
+`;
+/** The site's folder, made if it is not there: then with its README. One already there, made by
+ *  hand or by an earlier version, is left as it is. True when it was made now. */
+export function openSite(dir) {
+    if (existsSync(dir))
+        return false;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "README.md"), SITE_README);
+    return true;
+}
+/** Another server holds the site. */
+export class SiteBusy extends Error {
+    dir;
+    pid;
+    constructor(dir, pid) {
+        super(`another VisualProof server (process ${pid}) is using the site ${dir}; stop it first, or give this one a --site of its own`);
+        this.dir = dir;
+        this.pid = pid;
+    }
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // a process of another user's is there all the same
+        return e.code === "EPERM";
+    }
+}
+/** The living process that holds the site, if one does: what `lockSite` would refuse, without
+ *  taking it (`visualproof doctor`). */
+export function siteHolder(dir) {
+    try {
+        const held = Number(readFileSync(join(dir, ".lock"), "utf8").trim());
+        return Number.isInteger(held) && held > 0 && alive(held) ? held : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Takes the site for this process (`.lock`, holding its id), so that two servers never write the
+ *  same site: SiteBusy while another living process holds it; the lock of one that died is taken
+ *  over. The answer lets it go, as the process exits. */
+export function lockSite(dir, pid = process.pid) {
+    const file = join(dir, ".lock");
+    for (let tries = 0;; tries++) {
+        try {
+            writeFileSync(file, `${pid}\n`, { flag: "wx" });
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST" || tries > 3)
+                throw e;
+            let held = NaN;
+            try {
+                held = Number(readFileSync(file, "utf8").trim());
+            }
+            catch {
+                // let go meanwhile
+            }
+            if (held === pid)
+                break;
+            if (Number.isInteger(held) && held > 0 && alive(held))
+                throw new SiteBusy(dir, held);
+            try {
+                unlinkSync(file);
+            }
+            catch {
+                // taken over by another meanwhile: tried again
+            }
+        }
+    }
+    return () => {
+        try {
+            if (readFileSync(file, "utf8").trim() === String(pid))
+                unlinkSync(file);
+        }
+        catch {
+            // gone already
+        }
+    };
+}