visualproof 0.4.4 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/README.md +16 -7
  2. package/dist/assets/tips/phone-fingers.light.mp4 +0 -0
  3. package/dist/assets/tips/phone-fingers.light.webp +0 -0
  4. package/dist/assets/tips/tour-agent.webp +0 -0
  5. package/dist/assets/tips/tour-arrange.webp +0 -0
  6. package/dist/assets/tips/tour-artwork.webp +0 -0
  7. package/dist/assets/tips/tour-checks.webp +0 -0
  8. package/dist/assets/tips/tour-keys.webp +0 -0
  9. package/dist/assets/tips/tour-library.webp +0 -0
  10. package/dist/assets/tips/tour-project.webp +0 -0
  11. package/dist/assets/tips/tour-review.webp +0 -0
  12. package/dist/assets/tips/tour-share.webp +0 -0
  13. package/dist/assets/tips/tour-source.webp +0 -0
  14. package/dist/assets/tips/tour-target.webp +0 -0
  15. package/dist/assets/tips/tour-view.webp +0 -0
  16. package/dist/assets/tips/tour.json +132 -117
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/mcp/visualproof-mcp.mjs +20 -9
  19. package/dist/server/access.js +31 -1
  20. package/dist/server/accesspage.js +130 -0
  21. package/dist/server/agent.js +143 -50
  22. package/dist/server/askfollow.js +1 -1
  23. package/dist/server/buildwatch.js +133 -0
  24. package/dist/server/deploy.js +995 -0
  25. package/dist/server/doctor.js +15 -3
  26. package/dist/server/film.js +1 -1
  27. package/dist/server/historyapi.js +100 -50
  28. package/dist/server/historythread.js +206 -0
  29. package/dist/server/hover.js +8 -0
  30. package/dist/server/invites.js +113 -20
  31. package/dist/server/live.js +308 -60
  32. package/dist/server/main.js +450 -77
  33. package/dist/server/mcptools.js +33 -20
  34. package/dist/server/presence.js +3 -3
  35. package/dist/server/prompt.js +8 -3
  36. package/dist/server/readonlygate.js +4 -4
  37. package/dist/server/review.js +27 -7
  38. package/dist/server/reviewapi.js +51 -17
  39. package/dist/server/status.js +119 -46
  40. package/dist/server/talk.js +231 -115
  41. package/dist/server/tokens.js +10 -2
  42. package/dist/server/usage.js +51 -0
  43. package/dist/shared/board.js +2 -1
  44. package/dist/shared/build.js +35 -1
  45. package/dist/shared/collab.js +8 -0
  46. package/dist/shared/deploy.js +35 -0
  47. package/dist/shared/keys.js +66 -37
  48. package/dist/shared/layout.js +297 -70
  49. package/dist/shared/libm.js +366 -0
  50. package/dist/shared/lostfound.js +1 -0
  51. package/dist/shared/mentions.js +83 -0
  52. package/dist/shared/palette.js +1 -1
  53. package/dist/shared/query.js +13 -4
  54. package/dist/shared/review.js +91 -21
  55. package/dist/shared/reviewqueue.js +6 -1
  56. package/dist/shared/separate.js +556 -32
  57. package/dist/web/bundle/app.js +5022 -2736
  58. package/dist/web/bundle/edges.js +2 -1
  59. package/dist/web/bundle/layout.js +1026 -80
  60. package/dist/web/index.html +45 -9
  61. package/dist/web/src/canvas.js +47 -34
  62. package/dist/web/src/overview.js +4 -1
  63. package/dist/web/src/reviewqueue.js +52 -19
  64. package/dist/web/src/scene.js +13 -12
  65. package/dist/web/src/status.js +28 -0
  66. package/dist/web/src/theme.js +108 -0
  67. package/dist/web/src/trust.js +271 -0
  68. package/dist/web/style.css +283 -105
  69. package/docs/agent-api/README.md +13 -11
  70. package/docs/agent-api/advice.md +8 -2
  71. package/docs/agent-api/export.md +1 -1
  72. package/docs/agent-api/following.md +11 -12
  73. package/docs/agent-api/history.md +6 -2
  74. package/docs/agent-api/mcp.md +15 -15
  75. package/docs/agent-api/notes.md +1 -1
  76. package/docs/agent-api/reading.md +2 -2
  77. package/docs/agent-api/requests.md +16 -18
  78. package/docs/agent-api/talking.md +60 -55
  79. package/docs/agent-api/tcb.md +21 -21
  80. package/docs/agent-api/views.md +3 -4
  81. package/docs/agent-api/words.md +8 -8
  82. package/package.json +2 -1
@@ -21,6 +21,7 @@ import { spawn } from "node:child_process";
21
21
  import { childEnv, DETACH, grouped } from "./children.js";
22
22
  import { createHash } from "node:crypto";
23
23
  import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
24
+ import { freemem, totalmem } from "node:os";
24
25
  import { join } from "node:path";
25
26
  import { SITE_BODY, SITE_GRAMMAR, SITE_PROOF, SITE_TCB } from "../shared/graph.js";
26
27
  import { USAGE, USAGE_PROGRAM, leanProgram, prune } from "./extract.js";
@@ -31,6 +32,43 @@ import { compiledTextHash, lakeTextHash } from "./status.js";
31
32
  export const DEFAULT_JOBS = 8;
32
33
  /** A worker still running after this long is stopped, and its module reported as failed. */
33
34
  const WORKER_TIMEOUT_MS = 10 * 60_000;
35
+ const GB = 2 ** 30;
36
+ /** What a worker may hold at most, the `.olean` files it maps counted, on a large project on
37
+ * Mathlib: the showcase's (NavierStokesAndEuler, 2,657 modules) at 6 jobs peaked at 39 GB resident,
38
+ * 15 GB of it shared. Off Mathlib, a worker holds far less. */
39
+ export const WORKER_PEAK = 6 * GB;
40
+ /** What the machine keeps for itself and the rest while the pass runs: with less available, no new
41
+ * worker starts while another runs (`roomForWorker`). */
42
+ export function memoryFloor(total = totalmem()) {
43
+ return Math.max(2 * GB, total / 20);
44
+ }
45
+ /** Whether one more worker may start, `running` running: the first always; another while the
46
+ * machine has more than the floor available (os.freemem: MemAvailable on Linux). Workers come and
47
+ * go a module at a time, so that the pass holds back to what the memory allows. */
48
+ export function roomForWorker(running, available = freemem(), floor = memoryFloor()) {
49
+ return running === 0 || available >= floor;
50
+ }
51
+ /** Whether a project is on Mathlib, as its lakefile or manifest says: whose workers each map
52
+ * gigabytes. */
53
+ export function onMathlib(root) {
54
+ return ["lakefile.toml", "lakefile.lean", "lake-manifest.json"].some((f) => {
55
+ try {
56
+ return /mathlib/i.test(readFileSync(join(root, f), "utf8"));
57
+ }
58
+ catch {
59
+ return false;
60
+ }
61
+ });
62
+ }
63
+ /** What `jobs` workers may hold on a project on Mathlib, against `available` bytes: null where it
64
+ * fits (or off Mathlib), else what they may need and how many fit. */
65
+ export function jobsAdvice(jobs, mathlib, available = freemem()) {
66
+ if (!mathlib || jobs <= 1 || jobs * WORKER_PEAK <= available)
67
+ return null;
68
+ return { need: jobs * WORKER_PEAK, fits: Math.max(1, Math.floor(available / WORKER_PEAK)) };
69
+ }
70
+ /** Bytes in GB, in words. */
71
+ export const inGB = (bytes) => `${(bytes / GB).toFixed(bytes < 10 * GB ? 1 : 0)} GB`;
34
72
  /** Mixed into the fingerprint of a merged graph: bumped when the merge changes, so that graphs
35
73
  * merged before are not served as if made by this one. 3: the units' proof spans. (A change to
36
74
  * extractor/Usage.lean changes every module's key by itself: its text is in the salt.) */
@@ -93,6 +131,8 @@ export class UsagePass {
93
131
  status;
94
132
  /** the run going on, to stop when a newer build supersedes it */
95
133
  current = null;
134
+ /** the machine's memory available, as the pass asks it before each worker (a test's own) */
135
+ available = freemem;
96
136
  constructor(project, dirs, jobs, log) {
97
137
  this.project = project;
98
138
  this.dir = join(dirs.cache, "usage");
@@ -236,8 +276,19 @@ export class UsagePass {
236
276
  const modsFile = join(this.dir, "project-modules.txt");
237
277
  writeFileSync(modsFile, plan.modules.join("\n") + "\n");
238
278
  const queue = plan.todo.slice();
279
+ const floor = memoryFloor();
280
+ let held = false;
239
281
  const worker = async () => {
240
282
  while (queue.length && !run.cancelled) {
283
+ // memory short, another worker running: this one waits for it (said once a pass)
284
+ while (!roomForWorker(run.children.size, this.available(), floor) && !run.cancelled) {
285
+ if (!held)
286
+ this.log(`usage pass: ${inGB(this.available())} of memory available, less than ${inGB(floor)}: fewer workers at a time until there is more`);
287
+ held = true;
288
+ await new Promise((ok) => setTimeout(ok, 250));
289
+ }
290
+ if (!queue.length || run.cancelled)
291
+ return;
241
292
  const t = queue.shift();
242
293
  const e = await this.one(run, bin, env, modsFile, t);
243
294
  if (run.cancelled)
@@ -28,6 +28,7 @@
28
28
  // definition on a board of a target's review set — is still a path. So what is lit is exactly what a view of it holds
29
29
  // (`lightUp`, `zoomScope`), and Zoom in shows what was lit.
30
30
  import { clusterTree, computeLayout, memoryOf, regroup, stabilize, withLocal } from "./layout.js";
31
+ import { hypot } from "./libm.js";
31
32
  import { evaluate, within } from "./query.js";
32
33
  import { Graph } from "./viewgraph.js";
33
34
  /** The declarations `set` holds, as a graph of their own (edges among them only). */
@@ -272,7 +273,7 @@ export function reframePins(g, before, after, pins, mode) {
272
273
  return w;
273
274
  };
274
275
  const r = (v) => Math.round(v * 10) / 10;
275
- const away = (x1, y1, x2, y2) => Math.hypot(x1 - x2, y1 - y2) > 0.5;
276
+ const away = (x1, y1, x2, y2) => hypot(x1 - x2, y1 - y2) > 0.5;
276
277
  let extra = 0;
277
278
  // the same after, parents first, with the pins as they are made
278
279
  const wa = [];
@@ -1,2 +1,36 @@
1
1
  // Build status, as the server reports it to the page.
2
- export {};
2
+ /** What changed from the files as last sent (`sent`: each file's status as JSON, by module) to
3
+ * `next`'s: the files changed or new, the modules gone, and `next`'s files as JSON, by module, for
4
+ * the next change. */
5
+ export function buildChanges(sent, next) {
6
+ const texts = new Map();
7
+ const files = [];
8
+ for (const f of next.files) {
9
+ const t = JSON.stringify(f);
10
+ texts.set(f.module, t);
11
+ if (sent.get(f.module) !== t)
12
+ files.push(f);
13
+ }
14
+ const gone = [...sent.keys()].filter((m) => !texts.has(m));
15
+ return { files, gone, texts };
16
+ }
17
+ /** `held` with change `d` applied: the files changed replaced where they are, those new added at the
18
+ * end, those gone taken out. Null where it is no change of what is held: of another run of the
19
+ * server's, or from another revision (a change missed between). */
20
+ export function applyBuildDelta(held, d) {
21
+ if (d.epoch !== held.epoch || d.base !== held.rev)
22
+ return null;
23
+ const changed = new Map(d.files.map((f) => [f.module, f]));
24
+ const gone = new Set(d.gone);
25
+ const files = [];
26
+ for (const f of held.status?.files ?? []) {
27
+ if (gone.has(f.module))
28
+ continue;
29
+ const c = changed.get(f.module);
30
+ files.push(c ?? f);
31
+ if (c)
32
+ changed.delete(f.module);
33
+ }
34
+ files.push(...changed.values());
35
+ return { epoch: d.epoch, rev: d.rev, status: { active: d.active, progress: d.progress, files, counts: d.counts } };
36
+ }
@@ -171,6 +171,14 @@ export const SCHEMES = ["kind", "status"];
171
171
  /** Activity's filters: the kind of event, and whose (web/src/activity.ts). */
172
172
  export const ACTIVITY_KINDS = ["all", "review", "build", "change"];
173
173
  export const ACTIVITY_WHO = ["all", "agents", "people"];
174
+ /** Whether `who` made the token `t` (AgentSpec decision 7): the personal link that made it, where an
175
+ * invited person did; else the name it was made under, as names are compared. Its private channel
176
+ * and its prompt are theirs alone. */
177
+ export function madeBy(t, who) {
178
+ if (t.makerPerson)
179
+ return who.person === t.makerPerson;
180
+ return who.name !== null && sameName(who.name, t.by);
181
+ }
174
182
  /** A session id: what a page calls itself for as long as it is open, in its event stream's address
175
183
  * only (the server keeps a page's streams few by it); it is never told to the others. */
176
184
  export function validSession(s) {
@@ -0,0 +1,35 @@
1
+ // A branch of a git repository the server follows and builds itself (SPEC/DeploySpec.md), as the
2
+ // pages and agents are told it: where it comes from, the build going on, the newest commit waiting
3
+ // for it, the last build that ended; and the links into GitHub a page makes of it.
4
+ /** The same without what is for those let in fully: the builds' logs. */
5
+ export function slimDeploy(d) {
6
+ const drop = (x) => {
7
+ if (!x || x.tail === undefined)
8
+ return x;
9
+ const { tail: _, ...rest } = x;
10
+ return rest;
11
+ };
12
+ return { ...d, building: drop(d.building), last: drop(d.last) };
13
+ }
14
+ /** A commit as a page writes it. */
15
+ export const shortCommit = (c) => c.slice(0, 7);
16
+ /** What a step is doing, in words. */
17
+ export const STEP_WORDS = {
18
+ fetch: "fetching it",
19
+ checkout: "checking it out",
20
+ cache: "getting Mathlib's cache",
21
+ build: "lake build",
22
+ };
23
+ const enc = (p) => p.split("/").map(encodeURIComponent).join("/");
24
+ /** A file of the repository at a commit on GitHub, lines `from` to `to` (from 1) marked. */
25
+ export function githubBlob(repo, commit, file, from, to) {
26
+ return `https://github.com/${repo}/blob/${commit}/${enc(file)}#L${from}${to > from ? `-L${to}` : ""}`;
27
+ }
28
+ /** A commit on GitHub. */
29
+ export function githubCommit(repo, commit) {
30
+ return `https://github.com/${repo}/commit/${commit}`;
31
+ }
32
+ /** A branch on GitHub. */
33
+ export function githubTree(repo, branch) {
34
+ return `https://github.com/${repo}/tree/${enc(branch)}`;
35
+ }
@@ -1,21 +1,26 @@
1
- // Key declarations (ExportSpec decisions 1, 3 and 4): the members of a target's review that matter
2
- // for understanding it — the central definitions, the structures they are built on, the main theorem —
3
- // marked by people, or by agents at level full, per target; the target itself is always key. What each key declaration rests
4
- // on beyond itself (its support), and how the key declarations rest on one another (the key graph),
5
- // are pure functions of the graph, the review and the target's review set, over the same set and
6
- // edges the review queue walks (shared/reviewqueue.ts): the page, the agents' API and the exported
7
- // document (shared/doc/) all read them here.
1
+ // Key declarations (ExportSpec decisions 1, 3 and 4): the members of a target's TCB that matter for
2
+ // understanding it — the central definitions, the structures they are built on, the main theorem —
3
+ // marked by people, or by agents at level full, per target; the target itself is always key. A key
4
+ // declaration may be trusted (the owner's decision of 2026-10-19): trust says it needs no review, key
5
+ // that it is needed to read the target. It is read and printed as any key one is, and counted apart:
6
+ // key progress counts the key declarations that need review, "+N trusted" beside them (keyCounts).
7
+ // What each key declaration rests on beyond itself (its support), and how the key declarations rest
8
+ // on one another (the key graph), are pure functions of the graph, the review and the target's review
9
+ // set, over the same edges the review queue walks (shared/reviewqueue.ts): the page, the agents' API
10
+ // and the exported document (shared/doc/) all read them here.
8
11
  //
9
12
  // A member x that is not key is *supported by* a key declaration k when x is reachable from k
10
- // through members that are not key, along statement and body references. The key graph has an edge
11
- // from k₁ to k₂ when k₂ is reachable from k₁ that way. Two refinements keep "every member is
12
- // supported by some key declaration" true where the review set is more than what the target
13
- // reaches through its members:
13
+ // through members of the TCB that are not key, along statement and body references; k's support is
14
+ // the members of the review set it supports — a trusted member is passed through, never counted
15
+ // (TCBSpec decision 7). The key graph has an edge from k₁ to k₂ when k₂ is reachable from k₁ that
16
+ // way. Two refinements keep "every member is supported by some key declaration" true where the
17
+ // review set is more than what the target reaches through its members:
14
18
  //
15
- // - a declaration of the project in the target's TCB that is trusted, by module or by name (a layer
16
- // reviewed elsewhere), is not a member, but what it uses may be: the walk passes through it as
17
- // through a member that is not key (the outside world never uses the project, so nothing else
18
- // outside the set can lead back into it);
19
+ // - a declaration of the target's TCB that is trusted, by module or by name (a layer reviewed
20
+ // elsewhere, or the outside world), is not a member, but what it uses may be, and it may be key:
21
+ // the walk passes through it as through a member that is not key. Through the outside world only
22
+ // where something there is key or needs review: the outside world never uses the project, so
23
+ // nothing else there can lead back to a key declaration or a member;
19
24
  // - a non-standard axiom the target rests on only through a proof is a member that no statement or
20
25
  // body reaches: it is the target's support, as `viaProof` says.
21
26
  //
@@ -23,31 +28,47 @@
23
28
  // target's TCB, each walk reads the edges of the members and of what it passes through, never the
24
29
  // whole graph's (Sphere-Packing-Lean's `Dim24.MainTheorem`: its TCB of 226 in 72 ms, its keys in 1 ms).
25
30
  import { keyMarks, statusOf } from "./review.js";
26
- import { TCB_SITES } from "./reviewqueue.js";
27
- /** The key declarations of `root` among the members of its review (`order`, the queue's order —
28
- * shared/reviewqueue.ts), in that order: the target, and each member marked key. A mark on
29
- * a declaration that has left the review (now trusted, or no longer in the TCB) is kept in the
30
- * review but counts for nothing until it is back. */
31
- export function keySet(g, d, root, order) {
31
+ import { dependencyOrder, TCB_SITES } from "./reviewqueue.js";
32
+ /** The key declarations of `root`: the target, and each declaration marked key for it that its TCB
33
+ * (`tcb`, statement and body reach) or its review set (`order`, the members in the queue's order —
34
+ * shared/reviewqueue.ts) holds, trusted or not (ExportSpec decision 1). In order: the trusted ones
35
+ * first, in dependency order among themselves; then those of the review set in review order; the
36
+ * target last, whether it needs review or not. A mark on a declaration that has left the TCB is
37
+ * kept in the review but counts for nothing until it is back; one on a declaration trusted since
38
+ * stays, trusted. */
39
+ export function keySet(g, d, root, order, tcb = g.reach([root], TCB_SITES, "out")) {
32
40
  const marked = new Set(keyMarks(d, g.nodes[root].name));
33
- return order.filter((i) => i === root || marked.has(g.nodes[i].name));
41
+ const member = new Set(order);
42
+ const trusted = [];
43
+ for (const name of marked) {
44
+ const i = g.byName.get(name);
45
+ if (i !== undefined && i !== root && tcb[i] && !member.has(i))
46
+ trusted.push(i);
47
+ }
48
+ return [...dependencyOrder(g, trusted), ...order.filter((i) => i !== root && marked.has(g.nodes[i].name)), root];
49
+ }
50
+ /** `root`'s key declarations (keySet) and those of them that need no review, without walking the key
51
+ * graph: what counting them needs (keyCounts). */
52
+ export function keyParts(g, d, root, order, tcb) {
53
+ const keys = keySet(g, d, root, order, tcb);
54
+ const member = new Set(order);
55
+ return { keys, trusted: keys.filter((k) => !member.has(k)) };
34
56
  }
35
- /** `root`'s key graph over its review: `order` is the review's members in review order (the
36
- * queue's `order`). */
57
+ /** `root`'s key graph over its TCB: `order` is the review's members in review order (the queue's
58
+ * `order`). */
37
59
  export function keyGraph(g, d, root, order) {
38
- const keys = keySet(g, d, root, order);
39
- // the target is always key, also where the review does not hold it (a test, a graph read again)
40
- if (!keys.includes(root))
41
- keys.push(root);
60
+ const tcb = g.reach([root], TCB_SITES, "out");
61
+ const { keys, trusted } = keyParts(g, d, root, order, tcb);
42
62
  const keyAt = new Map();
43
63
  keys.forEach((k, j) => keyAt.set(k, j));
44
64
  const position = new Map();
45
65
  order.forEach((i, k) => position.set(i, k));
46
66
  const member = (v) => position.has(v);
47
- // what a walk may pass through besides members: the project's own declarations in the target's
48
- // TCB that are not members, which only a trusted prefix keeps out of the review
49
- const tcb = g.reach([root], TCB_SITES, "out");
50
- const passable = (v) => member(v) || (tcb[v] === 1 && !g.isExt(v));
67
+ // what a walk may pass through besides members: the declarations of the target's TCB that are not
68
+ // members, which only trust keeps out of the review — the outside world's only where something
69
+ // there is key or a member, since nothing outside leads back into the project
70
+ const outside = keys.some((k) => g.isExt(k)) || order.some((i) => g.isExt(i));
71
+ const passable = (v) => member(v) || (tcb[v] === 1 && (outside || !g.isExt(v)));
51
72
  const supporters = new Map();
52
73
  const support = keys.map(() => []);
53
74
  const edges = new Set();
@@ -101,12 +122,19 @@ export function keyGraph(g, d, root, order) {
101
122
  return {
102
123
  root,
103
124
  keys,
125
+ trusted,
104
126
  supporters,
105
127
  support,
106
128
  edges: [...edges].sort((a, b) => a - b).map((x) => [Math.floor(x / K), x % K]),
107
129
  viaProof,
108
130
  };
109
131
  }
132
+ /** How `kg`'s key declarations stand (ExportSpec decision 4): those that need review by people's
133
+ * status; the trusted ones counted apart. */
134
+ export function keyCounts(g, d, kg) {
135
+ const trusted = new Set(kg.trusted);
136
+ return { ...statusCounts(g, d, kg.keys.filter((k) => !trusted.has(k))), trusted: trusted.size };
137
+ }
110
138
  /** The key graph's edges to draw while the tool is the Keys step of Rests on and something is lit
111
139
  * (ViewSpec decision 20): of each key graph given — the focus's target's, or elsewhere every
112
140
  * target's, which makes the union over the targets whose key declarations are lit — the edges
@@ -140,11 +168,12 @@ export function statusCounts(g, d, xs) {
140
168
  }
141
169
  return c;
142
170
  }
143
- /** The review's order with its key declarations first (ExportSpec decision 4): the key ones in
144
- * review order, then the rest in review order — how the agents' API lists a review set with
145
- * `key=first`. */
146
- export function keyFirst(order, isKey) {
147
- return [...order.filter(isKey), ...order.filter((i) => !isKey(i))];
171
+ /** The review's order with its key declarations first (ExportSpec decision 4): the key ones, `keys`
172
+ * in their order (keySet: the trusted ones first, then the review's in review order), then the rest
173
+ * of the review in review order — how the agents' API lists a review set with `key=first`. */
174
+ export function keyFirst(order, keys) {
175
+ const isKey = new Set(keys);
176
+ return [...keys, ...order.filter((i) => !isKey.has(i))];
148
177
  }
149
178
  /** The key graph's layers, top-down (an index per key declaration, into `kg.keys`): the target at
150
179
  * 0, each other one a layer below every key declaration that rests on it — the longest path from