visualproof 0.0.0-stage → 0.1.0

package/dist/server/project.js

@@ -0,0 +1,222 @@
+// What the server knows about the codebase it shows, found by reading files only.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join, relative, resolve, sep } from "node:path";
+export class ProjectError extends Error {
+}
+/** `defaultTargets`, the package's name and its `[[lean_lib]]` tables from a lakefile.toml, without
+ *  a TOML parser: the keys read are single-line strings or arrays of strings in every lakefile Lake
+ *  writes, an array over several lines included. */
+export function readLakefileToml(text) {
+    const out = { libs: [] };
+    const strings = (v) => [...v.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+    // only the part before the first table header is the package itself
+    const head = text.split(/^\s*\[/m)[0];
+    const name = head.match(/^\s*name\s*=\s*"([^"]+)"/m);
+    if (name)
+        out.name = name[1];
+    const dt = head.match(/^\s*defaultTargets\s*=\s*\[([^\]]*)\]/m);
+    if (dt)
+        out.defaultTargets = strings(dt[1]);
+    for (const table of text.split(/^(?=\s*\[)/m)) {
+        if (!/^\s*\[\[\s*lean_lib\s*\]\]/.test(table))
+            continue;
+        const lib = table.match(/^\s*name\s*=\s*"([^"]+)"/m);
+        if (!lib)
+            continue;
+        const roots = table.match(/^\s*roots\s*=\s*\[([^\]]*)\]/m);
+        const globs = table.match(/^\s*globs\s*=\s*\[([^\]]*)\]/m);
+        out.libs.push({ name: lib[1], ...(roots ? { roots: strings(roots[1]) } : {}), ...(globs ? { globs: strings(globs[1]) } : {}) });
+    }
+    return out;
+}
+/** The modules a library builds, as Lake decides them: its globs, by default one of each of its
+ *  roots, by default its name; a glob of submodules matched against `known`, the modules there are.
+ *  A module named alone is kept even unknown, so that what is missing is said. */
+export function libModules(lib, known) {
+    const all = [...known].sort();
+    const out = new Set();
+    for (const g of lib.globs ?? lib.roots ?? [lib.name]) {
+        const glob = /^(.*)\.([+*])$/.exec(g);
+        if (!glob) {
+            out.add(g);
+            continue;
+        }
+        const [, base, which] = glob;
+        if (which === "*" && all.includes(base))
+            out.add(base);
+        for (const m of all)
+            if (m.startsWith(`${base}.`))
+                out.add(m);
+    }
+    return [...out];
+}
+/** The same from a lakefile.lean, read as text, never elaborated (Lake would write into the project
+ *  and run its code): the package's name, its libraries with the `roots := #[…]` and
+ *  `globs := #[…]` they give, and those marked `@[default_target]`. What a lakefile computes is not
+ *  seen; `--root` says it then. */
+export function readLakefileLean(text) {
+    const out = { libs: [] };
+    const code = stripLeanComments(text);
+    // a name: its parts, each plain or in «», joined by dots
+    const part = String.raw `(?:«[^»]+»|[A-Za-z_][\w'!?]*)`;
+    const ident = String.raw `(${part}(?:\.${part})*)`;
+    const unquote = (n) => n.replace(/[«»]/g, "");
+    const name = code.match(new RegExp(String.raw `^package\s+${ident}`, "m"));
+    if (name)
+        out.name = unquote(name[1]);
+    const targets = [];
+    for (const m of code.matchAll(new RegExp(String.raw `(@\[[^\]]*\]\s*)?lean_lib\s+${ident}`, "g"))) {
+        // the library's declaration runs to the next line that starts at the margin
+        const rest = code.slice(m.index + m[0].length);
+        const block = rest.slice(0, rest.search(/\n(?=\S)/) + 1 || rest.length);
+        const lib = { name: unquote(m[2]) };
+        const roots = block.match(/\broots\s*:=\s*#\[([^\]]*)\]/);
+        if (roots)
+            lib.roots = [...roots[1].matchAll(new RegExp("`" + ident, "g"))].map((r) => unquote(r[1]));
+        const globs = block.match(/\bglobs\s*:=\s*#\[([^\]]*)\]/);
+        if (globs) {
+            const kinds = { one: "", submodules: ".+", andSubmodules: ".*" };
+            lib.globs = [...globs[1].matchAll(new RegExp(String.raw `(?:Glob)?\.(one|submodules|andSubmodules)\s+\x60` + ident, "g"))].map((g) => unquote(g[2]) + kinds[g[1]]);
+        }
+        out.libs.push(lib);
+        if (m[1] && /\bdefault_target\b/.test(m[1]))
+            targets.push(lib.name);
+    }
+    if (targets.length)
+        out.defaultTargets = targets;
+    return out;
+}
+/** Lean source without its comments: `--` to the end of the line, `/- … -/` nested. Strings are
+ *  not looked into: a lakefile's strings hold no comment marks that matter here. */
+function stripLeanComments(text) {
+    let out = "";
+    let depth = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text.startsWith("/-", i)) {
+            depth++;
+            i++;
+        }
+        else if (depth > 0 && text.startsWith("-/", i)) {
+            depth--;
+            i++;
+        }
+        else if (depth > 0) {
+            if (text[i] === "\n")
+                out += "\n";
+        }
+        else if (text.startsWith("--", i)) {
+            const nl = text.indexOf("\n", i);
+            if (nl < 0)
+                break;
+            i = nl - 1;
+        }
+        else
+            out += text[i];
+    }
+    return out;
+}
+/** Every .lean file outside .lake, indexed by each module name it could be: a file
+ *  `ThirdParty/Vendored/X.lean` can be `ThirdParty.Vendored.X` or `Vendored.X` depending on the
+ *  library's srcDir. The shortest path wins a tie, which is the usual layout. */
+export function indexSources(root) {
+    const files = new Map();
+    const walk = (dir) => {
+        for (const ent of readdirSync(dir, { withFileTypes: true })) {
+            if (ent.name.startsWith(".") || ent.name === "node_modules")
+                continue;
+            const p = join(dir, ent.name);
+            if (ent.isDirectory())
+                walk(p);
+            else if (ent.isFile() && ent.name.endsWith(".lean") && !ent.name.startsWith("lakefile")) {
+                const rel = relative(root, p);
+                const parts = rel.slice(0, -".lean".length).split(sep);
+                for (let i = 0; i < parts.length; i++) {
+                    const mod = parts.slice(i).join(".");
+                    const prev = files.get(mod);
+                    if (prev === undefined || prev.length > rel.length)
+                        files.set(mod, rel);
+                }
+            }
+        }
+    };
+    walk(root);
+    return files;
+}
+/** The project's modules a library's globs are matched against: those Lake built (an `.olean` in
+ *  `libDir`) that have a source, and, for a project not built yet, those whose source sits where
+ *  the module's name says, under the project's folder. */
+function knownModules(libDir, files) {
+    const known = new Set();
+    for (const [mod, rel] of files)
+        if (rel === mod.split(".").join(sep) + ".lean")
+            known.add(mod);
+    const walk = (dir, prefix) => {
+        if (!existsSync(dir))
+            return;
+        for (const ent of readdirSync(dir, { withFileTypes: true })) {
+            if (ent.isDirectory())
+                walk(join(dir, ent.name), [...prefix, ent.name]);
+            else if (ent.name.endsWith(".olean")) {
+                const mod = [...prefix, ent.name.slice(0, -".olean".length)].join(".");
+                if (files.has(mod))
+                    known.add(mod);
+            }
+        }
+    };
+    walk(libDir, []);
+    return known;
+}
+/** What a project's modules to read are, in words: its targets, and how many modules they stand
+ *  for where that is more. */
+export function targetsInWords(p) {
+    const t = p.targets ?? p.roots;
+    return t.join(", ") + (p.roots.length > t.length ? `: ${p.roots.length} modules` : "");
+}
+export function openProject(path, rootsOverride, requireBuild = true) {
+    const root = resolve(path);
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        throw new ProjectError(`${root} is not a directory`);
+    }
+    const tcFile = join(root, "lean-toolchain");
+    if (!existsSync(tcFile))
+        throw new ProjectError(`no lean-toolchain in ${root}: not a Lean project`);
+    const toolchain = readFileSync(tcFile, "utf8").trim();
+    let name = basename(root);
+    let roots = rootsOverride;
+    let targets = rootsOverride;
+    const toml = join(root, "lakefile.toml");
+    const lean = join(root, "lakefile.lean");
+    const lf = existsSync(toml) ? readLakefileToml(readFileSync(toml, "utf8")) : existsSync(lean) ? readLakefileLean(readFileSync(lean, "utf8")) : { libs: [] };
+    if (lf.name)
+        name = lf.name;
+    const libDir = join(root, ".lake", "build", "lib", "lean");
+    const files = indexSources(root);
+    // a target that is a library stands for the modules it builds; any other, for a module: the
+    // default targets, or those `--root` names (a library or a module)
+    if (roots.length === 0 && lf.defaultTargets)
+        roots = targets = lf.defaultTargets;
+    if (targets.some((t) => lf.libs.some((l) => l.name === t))) {
+        const known = knownModules(libDir, files);
+        const out = new Set();
+        for (const t of targets) {
+            const lib = lf.libs.find((l) => l.name === t);
+            const mods = lib ? libModules(lib, known) : [t];
+            // a library with nothing built nor written is named, so that it is said to be unbuilt
+            for (const m of mods.length ? mods : [t])
+                out.add(m);
+        }
+        roots = [...out];
+    }
+    if (roots.length === 0) {
+        throw new ProjectError("cannot tell which modules to read: pass --root <Module> (the lakefile names no default " +
+            "library: no defaultTargets in lakefile.toml, no @[default_target] lean_lib in lakefile.lean)");
+    }
+    for (const r of requireBuild ? roots : []) {
+        const olean = join(libDir, ...r.split(".")) + ".olean";
+        if (!existsSync(olean)) {
+            throw new ProjectError(`${r} has not been built (${relative(root, olean)} is missing). ` +
+                "VisualProof reads what `lake build` produced and never builds itself.");
+        }
+    }
+    return { root, name, toolchain, roots, targets, libDir, files };
+}

package/dist/server/prompt.js

@@ -0,0 +1,53 @@
+// The prompt Share makes for an AI agent (AgentSpec decision 7): plain English that any agent able
+// to make HTTP requests can act on alone, pasted into it by the person who shared. It says where the
+// server is (as that person's browser reached it), gives the agent's token, who the agent is here,
+// its level and when the token expires, and the few rules that matter before anything is read. What
+// the person wants done they tell the agent themselves, and where they are the companion says (GET
+// /api/agent/companion). Everything else is in GET /api/agent, a short entry the prompt sends the
+// agent to first, and the documentation's topics it names (the MCP server's docs tool): the prompt
+// stays short, and what the API says cannot drift from the prompt.
+//
+// The prompt is made from the token and its record alone, so Share can show it again, the same,
+// while the token is in force.
+//
+// Since decision 8 it also makes the agent one people can talk to, at once: a Claude Code agent
+// installs VisualProof's MCP server, has its user restart the session (MCP servers load when one
+// starts), and then listens by itself — wait_for_message, which returns the moment someone writes;
+// any other agent listens on its inbox over HTTP. Either way its first wait may bring the
+// conversation so far (the owner's decision of 2026-10-11), which it reads and does not answer.
+import { claudeCodeSteps, utc } from "./mcptools.js";
+const MAY = {
+    read: "you may read everything and show what you look at, but not give advice or change anything",
+    advise: "you may read, give advice on declarations and leave notes that point people at something",
+    full: "you may read, give advice, leave notes, and also do whatever a person can do in the page — mark targets and key declarations, trust prefixes, make and change views and pins — each recorded as yours, an agent's",
+};
+/** The prompt, as text. */
+export function agentPrompt(p) {
+    const r = p.record;
+    const lines = [
+        `${r.by} invites you to work with them in VisualProof, a web tool for reviewing a Lean project: it shows the project's declarations, the trusted computing base (TCB) of its theorems, and the review people make of it.`,
+        "",
+        `Server: ${p.url}`,
+        `Your token: ${p.token}`,
+        `  It is a secret. Send it with every request as the header "Authorization: Bearer <token>". Never print it or show it to anyone, and store it nowhere except where a tool's configuration needs it.`,
+        "",
+        `You are "${r.name}", an AI agent. Your level is ${r.level}: ${MAY[r.level]}. The token expires ${utc(r.expires)}.`,
+        "",
+        `Start with GET ${p.url}/api/agent — a short entry: who you are, how to begin, the rules, and the documentation's topics (GET /api/agent/docs/<topic>; with the MCP server below, its docs tool).`,
+        "",
+        `People on the page can talk to you, and you listen for them whenever you have nothing else to do. If you are Claude Code, set that up now (GET /api/agent/mcp/install says the same, and how other MCP clients do it):`,
+        claudeCodeSteps(p.url, p.token),
+        `Not Claude Code, nor MCP: listen with GET ${p.url}/api/agent/inbox?wait=<seconds>, which answers the moment someone writes; answer with POST /api/agent/reply, then ask again.`,
+        "Either way, the first wait after you join may bring earlier messages; read them as context and do not answer them again.",
+        "",
+        "Ground rules:",
+        r.level === "read"
+            ? `- You only read here: tell ${r.by} what you find.`
+            : "- What you say is advice: shown apart, never counted. Give your reasons; a comment needs text saying what is wrong, unclear or worth checking, and where.",
+        r.level === "read"
+            ? "- Show what you look at with POST /api/agent/view. You never move anyone else's view."
+            : "- Show what you look at with POST /api/agent/view, and point people at things with notes (POST /api/agent/note). You never move anyone else's view.",
+        `- When you are done, say so: POST /api/agent/view {"leave": true}.`,
+    ];
+    return lines.join("\n") + "\n";
+}

package/dist/server/readonly.js

@@ -0,0 +1,152 @@
+// Read-only links (CollabSpec decision 11, the owner's decision of 2026-10-13): whoever is let in
+// may make one from Share, for anyone they want to show the project to. It lets its holder see
+// what a guest sees and change nothing that is shared; nobody sees them (not listed, not counted).
+// A read-only reader's own Share gives the link they came by, so that revoking one link cuts off
+// everyone it reached.
+//
+// A link is `/r/vpr_<id>_<secret>`, made as a personal link is (server/invites.ts): the id names it
+// in Share's list, the secret is 32 random bytes. Opened, it leaves a cookie and goes on to the
+// page; the cookie's value is the id and a digest of the token, never the token (cookies are not
+// kept per port, and other services answer on this host's name). Unlike a personal link's, the
+// token is kept: a read-only link is made to be passed on, so whoever holds it, and whoever is let
+// in, may see it again, which gives none of them more than they have. It is kept in
+// `<site>/readonly-links.json`, readable by the server's user alone. A link lasts until it is
+// revoked, which cuts its pages off at once; revoked links stay, saying who revoked them.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cookieOf } from "./invites.js";
+export const READONLY_PREFIX = "vpr_";
+/** where a read-only link points: `/r/<token>` */
+export const READONLY_PATH = "/r/";
+const FILE = "readonly-links.json";
+const COOKIE = "visualproof_readonly";
+const MAX_AGE = 400 * 24 * 3600;
+const FLUSH_MS = 60_000;
+const ID = /^[0-9a-f]{10}$/;
+const SECRET = /^[A-Za-z0-9_-]{43}$/;
+const sha = (s) => createHash("sha256").update(s).digest();
+const cookieValue = (r) => `${r.id}.${sha(`visualproof read-only cookie\0${r.token}`).toString("base64url")}`;
+const same = (a, b) => timingSafeEqual(sha(a), sha(b));
+const info = (r) => ({ id: r.id, path: `${READONLY_PATH}${r.token}`, by: r.by, created: r.created, revoked: r.revoked, revokedBy: r.revokedBy, lastUsed: r.lastUsed });
+export class ReadOnlyLinks {
+    file;
+    records = [];
+    cookieName;
+    dirty = false;
+    timer = null;
+    /** told when a link is revoked: its pages' event streams end (server/live.ts) */
+    onEnded = () => { };
+    /** `siteDir` null keeps the links in memory only (tests). */
+    constructor(siteDir) {
+        this.file = siteDir ? join(siteDir, FILE) : null;
+        let own = null;
+        if (this.file && existsSync(this.file)) {
+            try {
+                const data = JSON.parse(readFileSync(this.file, "utf8"));
+                if (typeof data.cookie === "string" && /^[0-9a-f]{12}$/.test(data.cookie))
+                    own = data.cookie;
+                if (Array.isArray(data.links))
+                    this.records = data.links.filter(isRecord);
+            }
+            catch {
+                // a file that cannot be read lets nobody in by a read-only link; it is kept aside
+                renameSync(this.file, `${this.file}.broken-${Date.now()}`);
+            }
+        }
+        this.cookieName = `${COOKIE}_${own ?? randomBytes(6).toString("hex")}`;
+        if (this.file) {
+            this.timer = setInterval(() => this.flush(), FLUSH_MS);
+            this.timer.unref?.();
+        }
+    }
+    /** Make a link, by `by` (null: someone who gave no name). */
+    create(by, now = Date.now()) {
+        let id;
+        do
+            id = randomBytes(5).toString("hex");
+        while (this.records.some((r) => r.id === id));
+        const r = { id, token: `${READONLY_PREFIX}${id}_${randomBytes(32).toString("base64url")}`, by, created: new Date(now).toISOString(), revoked: null, revokedBy: null, lastUsed: null };
+        this.records.push(r);
+        this.save();
+        return info(r);
+    }
+    /** What a link's token is, compared in constant time whether or not its id is known. */
+    check(token, now = Date.now()) {
+        if (!token.startsWith(READONLY_PREFIX))
+            return null;
+        const id = token.slice(READONLY_PREFIX.length, READONLY_PREFIX.length + 10);
+        const r = ID.test(id) && token[READONLY_PREFIX.length + 10] === "_" && SECRET.test(token.slice(READONLY_PREFIX.length + 11)) ? this.records.find((x) => x.id === id) : undefined;
+        const ok = same(token, r?.token ?? "no such link");
+        return r && ok ? this.seen(r, now) : null;
+    }
+    /** What a request's cookie says: a link in force, one revoked (to be forgotten), or none. */
+    ofCookie(header, now = Date.now()) {
+        const given = cookieOf(header, this.cookieName);
+        if (given === null)
+            return null;
+        const r = given.indexOf(".") === 10 ? this.records.find((x) => x.id === given.slice(0, 10)) : undefined;
+        const ok = same(given, r ? cookieValue(r) : "no such link");
+        return r && ok ? this.seen(r, now) : null;
+    }
+    seen(r, now) {
+        if (r.revoked)
+            return { ended: "revoked", link: info(r) };
+        r.lastUsed = new Date(now).toISOString();
+        this.dirty = true;
+        return { ok: info(r) };
+    }
+    /** The cookie that lets a browser in by link `id`, read-only (a `Set-Cookie` value). */
+    cookie(id) {
+        const r = this.records.find((x) => x.id === id);
+        if (!r)
+            throw new Error(`no read-only link ${id}`);
+        return `${this.cookieName}=${cookieValue(r)}; Path=/; Max-Age=${MAX_AGE}; HttpOnly; SameSite=Lax`;
+    }
+    /** What makes a browser forget a revoked link's cookie. */
+    forget() {
+        return `${this.cookieName}=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax`;
+    }
+    /** Every link, those in force first, newest first within each. */
+    list() {
+        const order = (r) => (r.revoked ? 1 : 0);
+        return [...this.records].sort((a, b) => order(a) - order(b) || b.created.localeCompare(a.created)).map(info);
+    }
+    get(id) {
+        const r = this.records.find((x) => x.id === id);
+        return r ? info(r) : undefined;
+    }
+    /** Revoke a link in force: it lets nobody in from now on, and its pages' streams end. */
+    revoke(id, by, now = Date.now()) {
+        const r = this.records.find((x) => x.id === id);
+        if (!r || r.revoked)
+            return false;
+        r.revoked = new Date(now).toISOString();
+        r.revokedBy = by;
+        this.save();
+        this.onEnded(info(r));
+        return true;
+    }
+    flush() {
+        if (this.dirty)
+            this.save();
+    }
+    close() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.flush();
+    }
+    save() {
+        this.dirty = false;
+        if (!this.file)
+            return;
+        const tmp = `${this.file}.tmp`;
+        writeFileSync(tmp, JSON.stringify({ cookie: this.cookieName.slice(COOKIE.length + 1), links: this.records }, null, 1) + "\n", { mode: 0o600 });
+        renameSync(tmp, this.file);
+    }
+}
+function isRecord(x) {
+    const r = x;
+    return !!r && typeof r === "object" && ID.test(r.id) && typeof r.token === "string" && r.token.startsWith(`${READONLY_PREFIX}${r.id}_`) && typeof r.created === "string";
+}

package/dist/server/readonlygate.js

@@ -0,0 +1,123 @@
+// What a read-only reader may ask (CollabSpec decision 11): what a guest reads, and nothing that
+// changes what is shared. The server refuses the rest (403) whatever the page sends; the page does
+// not offer it. What costs the server is bounded for read-only readers: Lean's answers, by address
+// and in all, each kept per build; the printed document, one typesetting at a time for them all.
+/** Whether a read-only reader may make this request. */
+export function readOnlyAllows(method, path) {
+    const read = method === "GET" || method === "HEAD";
+    if (read) {
+        // the page and its files
+        if (path === "/" || path === "/index.html" || path === "/style.css" || /^\/(app|layout|edges|pdfworker)\.js(\.map)?$/.test(path) || path.startsWith("/pdfjs/"))
+            return true;
+        // the graph, its sources and Lean's answers, the review, what happened, the views, the history,
+        // the library, the printed document's state and files, who the reader is and the link they
+        // came by, and the event stream every change comes by
+        if (["/api/status", "/api/meta", "/api/edges", "/api/source", "/api/review", "/api/activity", "/api/identity", "/api/share"].includes(path))
+            return true;
+        // a stream is opened by GET alone: a HEAD would take one of their places for nothing
+        if (path === "/api/events")
+            return method === "GET";
+        if (path === "/api/hover" || path === "/api/hover/describe" || path === "/api/hover/print")
+            return true;
+        for (const p of ["/api/views", "/api/history", "/api/library", "/api/export"])
+            if (path === p || path.startsWith(`${p}/`))
+                return true;
+        return false;
+    }
+    // a file opened in Lean, the names in a declaration's source: reads, posted for their size
+    if (method === "POST" && (path === "/api/hover/open" || path === "/api/hover/names"))
+        return true;
+    // the printed document of a view as it is shared (bounded below)
+    if (method === "POST" && path === "/api/export")
+        return true;
+    return false;
+}
+/** Whether Lean's answer is what it says in the end, to be kept for the build: not a failure, nor
+ *  "still elaborating" (server/hover.ts), which a later request must ask again. */
+export function finalAnswer(body) {
+    const b = body;
+    return !!b && typeof b === "object" && !b.error && !b.pending;
+}
+/** At most `per` in `ms` for each key, and `all` in all: a sliding count per key. */
+class Rate {
+    hits = new Map();
+    every = [];
+    per;
+    all;
+    ms;
+    constructor(per, all, ms) {
+        this.per = per;
+        this.all = all;
+        this.ms = ms;
+    }
+    /** 0 when `key` may go now (and it is counted), else the seconds to wait. */
+    take(key, now = Date.now()) {
+        const since = now - this.ms;
+        const mine = (this.hits.get(key) ?? []).filter((t) => t > since);
+        this.every = this.every.filter((t) => t > since);
+        const wait = (ts, max) => (ts.length < max ? 0 : Math.max(1, Math.ceil((ts[ts.length - max] + this.ms - now) / 1000)));
+        const w = Math.max(wait(mine, this.per), wait(this.every, this.all));
+        if (w === 0) {
+            mine.push(now);
+            this.every.push(now);
+        }
+        if (mine.length)
+            this.hits.set(key, mine);
+        else
+            this.hits.delete(key);
+        // the keys of addresses gone quiet go with them
+        if (this.hits.size > 10_000)
+            for (const [k, ts] of this.hits)
+                if (!ts.some((t) => t > since))
+                    this.hits.delete(k);
+        return w;
+    }
+}
+/** Lean's answers to read-only readers, and their printed documents. */
+export class ReadOnlyBounds {
+    /** Lean's answers: per address, and for every read-only reader together, a minute's worth */
+    lean = new Rate(60, 300, 60_000);
+    /** Lean's answers to the same question about the same build, as read-only readers asked them */
+    answers = new Map();
+    static ANSWERS = 2000;
+    /** the read-only readers' document being typeset, by its job's id; `RESERVED` while it starts */
+    exporting = null;
+    static RESERVED = "\0starting";
+    /** whether a job is still running (server/export.ts) */
+    running;
+    constructor(running = () => false) {
+        this.running = running;
+    }
+    /** 0 when an address may ask Lean now, else the seconds to wait (429). */
+    leanWait(address, now = Date.now()) {
+        return this.lean.take(address, now);
+    }
+    /** An answer kept for this build and question, if there is one. */
+    answer(key) {
+        return this.answers.get(key);
+    }
+    /** Keep an answer, the oldest going past ANSWERS. */
+    keep(key, answer) {
+        this.answers.delete(key);
+        this.answers.set(key, answer);
+        while (this.answers.size > ReadOnlyBounds.ANSWERS)
+            this.answers.delete(this.answers.keys().next().value);
+    }
+    /** Whether a read-only reader may start a document now: no other read-only document is being
+     *  typeset, nor starting. */
+    mayExport() {
+        if (this.exporting && this.exporting !== ReadOnlyBounds.RESERVED && !this.running(this.exporting))
+            this.exporting = null;
+        return this.exporting === null;
+    }
+    /** Take the place before a document starts (`mayExport` said yes). */
+    reserveExport() {
+        this.exporting = ReadOnlyBounds.RESERVED;
+    }
+    /** The document started (the export's answer), or failed to: the place is its job's while it
+     *  runs, and free otherwise. */
+    exportStarted(answer) {
+        const job = answer?.job;
+        this.exporting = job?.state === "running" && typeof job.id === "string" ? job.id : null;
+    }
+}