visualproof 0.8.2 → 0.9.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 (41) hide show
  1. package/README.md +10 -8
  2. package/dist/assets/tips/tour-library.webp +0 -0
  3. package/dist/assets/tips/tour-source.webp +0 -0
  4. package/dist/assets/tips/tour.json +90 -90
  5. package/dist/extractor/Extract.lean +34 -11
  6. package/dist/server/agent.js +19 -7
  7. package/dist/server/agentexport.js +2 -1
  8. package/dist/server/agentfollow.js +13 -3
  9. package/dist/server/agentlean.js +91 -1
  10. package/dist/server/agentnotes.js +6 -4
  11. package/dist/server/agentread.js +33 -1
  12. package/dist/server/app.js +1 -1
  13. package/dist/server/appgraph.js +24 -0
  14. package/dist/server/boardspots.js +1 -1
  15. package/dist/server/goals.js +224 -0
  16. package/dist/server/hover.js +281 -8
  17. package/dist/server/live.js +14 -0
  18. package/dist/server/main.js +3 -2
  19. package/dist/server/mcptools.js +11 -5
  20. package/dist/server/options.js +17 -2
  21. package/dist/server/readonlygate.js +2 -1
  22. package/dist/server/reviewapi.js +5 -2
  23. package/dist/server/status.js +43 -5
  24. package/dist/shared/build.js +9 -0
  25. package/dist/shared/collab.js +14 -2
  26. package/dist/shared/declfind.js +23 -3
  27. package/dist/shared/goals.js +309 -0
  28. package/dist/shared/hygiene.js +18 -0
  29. package/dist/shared/noteplace.js +45 -19
  30. package/dist/shared/scope.js +74 -45
  31. package/dist/shared/sharesnap.js +4 -2
  32. package/dist/web/bundle/app.js +2266 -579
  33. package/dist/web/index.html +1 -1
  34. package/dist/web/src/highlight.js +53 -3
  35. package/dist/web/style.css +148 -0
  36. package/docs/agent-api/README.md +1 -1
  37. package/docs/agent-api/mcp.md +1 -1
  38. package/docs/agent-api/notes.md +3 -2
  39. package/docs/agent-api/reading.md +38 -2
  40. package/docs/agent-api/words.md +3 -2
  41. package/package.json +1 -1
@@ -6,7 +6,8 @@
6
6
  // lakefile in the directory it was started from. Started elsewhere with the project's LEAN_PATH,
7
7
  // it reads the `.olean` files the owner's builds left and writes nothing (SPEC.md: "No .lake
8
8
  // conflict"). It elaborates the file it is asked about once, then answers hovers in milliseconds.
9
- // At most two files are kept open; the server stops after ten idle minutes. A file outside the
9
+ // At most `--lean-files` files are kept open (four by default); the server stops after ten idle
10
+ // minutes. A file outside the
10
11
  // project — a package's, Lean's core's, whose source the window shows too (the owner's decision of
11
12
  // 2026-10-20; server/outside.ts) — is opened by the same Lean in the same way: elaborated against
12
13
  // the `.olean` files of what it imports, nothing built.
@@ -18,25 +19,41 @@
18
19
  // (a diagnostic), not as a hover.
19
20
  //
20
21
  // Lean runs each open file in a worker process of its own, which can die (a worker on a large
21
- // project holds gigabytes: 4.1 GB for Sphere-Packing-Lean's main theorem's module; and the kernel's OOM killer picks the
22
+ // project holds gigabytes: 1.9 GB resident for Sphere-Packing-Lean's main theorem's module, 5.2 GB
23
+ // for its Leech lattice's norm, measured on 2026-11-01; and the kernel's OOM killer picks the
22
24
  // largest). Lean then says the file's progress
23
25
  // is a fatal error, and starts the worker again only when the document changes: until then every
24
26
  // question about it would wait forever. So a crashed document is closed and opened again here, as a
25
27
  // new version, and its questions asked anew; one that keeps crashing is given up on for a while,
26
28
  // with why; a question Lean does not answer in REQUEST_MS is answered that it did not; and what
27
29
  // Lean is doing is part of /api/status (`state`).
30
+ //
31
+ // The InfoView (ReviewSpec, "The InfoView"; the owner's decisions of 2026-11-01) asks the same Lean,
32
+ // of the same open file, the goals at a place: before the tactic there and after it, and the
33
+ // expected type of the term there (`goals`). Lean is asked at positions alone, which the server
34
+ // reads from the file's text (shared/goals.ts, tacticSpan). It asks through Lean's RPC first — one
35
+ // session per open file, kept alive while the file is open — for goals whose subterms Lean can say
36
+ // more of (`subterm`: their type and doc, asked by the number the answer gives each); where the RPC
37
+ // cannot be had, Lean's plain answers. Lean's answers keep what they refer to alive in the session:
38
+ // the server holds the last ANSWERS of each file's, and releases what it lets go. The widgets Lean has
39
+ // at a place are counted, never fetched nor drawn (SECURITY.md).
28
40
  import { spawn, spawnSync } from "node:child_process";
29
41
  import { childEnv, DETACH, end, grouped } from "./children.js";
30
42
  import { existsSync, mkdirSync } from "node:fs";
31
43
  import { join } from "node:path";
32
44
  import { pathToFileURL } from "node:url";
45
+ import { afterLine, holdsBy, tacticSpan } from "../shared/goals.js";
46
+ import { afterTheLine, readInfo, readInteractiveGoals, readInteractiveTermGoal, readPlainGoals, readPlainTermGoal, readWidgets, Reading, refsIn } from "./goals.js";
33
47
  /** A Lean name, dotted, and nothing else: no spaces, no line breaks, no commands. */
34
48
  export function isDeclName(s) {
35
49
  const part = "(?:[\\p{L}_][\\p{L}\\p{N}_'!?\u2080-\u2089\u2090-\u209c]*|«[^»\\n\\r]*»|[0-9]+)";
36
50
  return s.length <= 2000 && new RegExp(`^${part}(?:\\.${part})*$`, "u").test(s);
37
51
  }
38
52
  const SEVERITY = ["error", "error", "warning", "information", "hint"];
39
- const KEEP_OPEN = 2;
53
+ /** the files kept open at most, where the server is not told otherwise (`--lean-files`), and the
54
+ * most it may be told */
55
+ export const KEEP_OPEN = 4;
56
+ export const MAX_LEAN_FILES = 16;
40
57
  const IDLE_MS = 10 * 60 * 1000;
41
58
  /** the longest a question waits for Lean's answer before it is answered that there was none */
42
59
  const REQUEST_MS = 5 * 60 * 1000;
@@ -53,6 +70,13 @@ const GIVE_UP_MS = 5 * 60 * 1000;
53
70
  const FATAL = 2;
54
71
  /** questions waiting for their turn in the scratch file, at most */
55
72
  const MAX_QUEUED = 16;
73
+ /** how often an RPC session is told it is still in use: Lean ends one it hears nothing of for 30 s */
74
+ const KEEP_ALIVE_MS = 10_000;
75
+ /** the goals answers kept per open file, with what Lean holds for their subterms */
76
+ const ANSWERS = 32;
77
+ /** Lean's codes: the RPC session is gone (its worker restarted, or it expired); no such method */
78
+ const RPC_RECONNECT = -32900;
79
+ const NO_METHOD = -32601;
56
80
  export class LeanHover {
57
81
  project;
58
82
  dir;
@@ -89,9 +113,14 @@ export class LeanHover {
89
113
  /** what Lean last published about each document it has open: the version it is about, and the
90
114
  * messages (a `#print` says what it prints so) */
91
115
  diagnostics = new Map();
92
- constructor(project, cacheDir) {
116
+ /** the files kept open at most (`--lean-files`) */
117
+ keepOpen;
118
+ /** what tells the RPC sessions they are still in use, while there is one */
119
+ alive = null;
120
+ constructor(project, cacheDir, keepOpen = KEEP_OPEN) {
93
121
  this.project = project;
94
122
  this.dir = join(cacheDir, "lean-server");
123
+ this.keepOpen = Math.max(1, Math.floor(keepOpen));
95
124
  }
96
125
  /** The project's `lean` and LEAN_PATH, found once. */
97
126
  resolveEnv() {
@@ -204,6 +233,11 @@ export class LeanHover {
204
233
  take(msg) {
205
234
  if (!msg || typeof msg !== "object")
206
235
  return;
236
+ // a request of Lean's own (`workspace/semanticTokens/refresh`, `workspace/inlayHint/refresh`, as
237
+ // a file is elaborated) carries an id of Lean's counting, which may be one of ours: it is no
238
+ // answer. It is answered, as an editor does, with nothing
239
+ if (msg.id !== undefined && msg.method !== undefined)
240
+ return this.send({ id: msg.id, result: null });
207
241
  if (msg.id !== undefined && this.waiting.has(msg.id)) {
208
242
  this.waiting.get(msg.id)(msg);
209
243
  this.waiting.delete(msg.id);
@@ -288,8 +322,14 @@ export class LeanHover {
288
322
  }
289
323
  open.version = sc ? ++this.scratchVersion : open.version + 1;
290
324
  open.progressAt = Date.now();
291
- if (doc)
325
+ if (doc) {
292
326
  doc.processing = 0;
327
+ // a new worker: the RPC session and what it held went with the old one
328
+ doc.rpc = null;
329
+ doc.connecting = null;
330
+ doc.answers.clear();
331
+ doc.computing.clear();
332
+ }
293
333
  if (sc)
294
334
  sc.done = false;
295
335
  this.notify("textDocument/didOpen", { textDocument: { uri, languageId: "lean4", version: open.version, text: open.text } });
@@ -360,7 +400,7 @@ export class LeanHover {
360
400
  this.idle = setTimeout(() => this.stop(), IDLE_MS);
361
401
  this.idle.unref();
362
402
  }
363
- /** Have Lean elaborate a file (its present text), keeping at most KEEP_OPEN open. */
403
+ /** Have Lean elaborate a file (its present text), keeping at most `keepOpen` open. */
364
404
  async open(file, text, hash) {
365
405
  await this.start();
366
406
  this.touch();
@@ -385,11 +425,11 @@ export class LeanHover {
385
425
  this.notify("textDocument/didChange", { textDocument: { uri, version: doc.version }, contentChanges: [{ text }] });
386
426
  }
387
427
  else if (!doc) {
388
- doc = { uri, version: 1, text, progressAt: Date.now(), hash, lines: text.split("\n").length, used: 0, processing: 0 };
428
+ doc = { uri, version: 1, text, progressAt: Date.now(), hash, lines: text.split("\n").length, used: 0, processing: 0, rpc: null, connecting: null, answers: new Map(), computing: new Map() };
389
429
  this.docs.set(rel, doc);
390
430
  this.notify("textDocument/didOpen", { textDocument: { uri, languageId: "lean4", version: 1, text } });
391
431
  // too many open: the one least recently asked about is closed
392
- if (this.docs.size > KEEP_OPEN) {
432
+ if (this.docs.size > this.keepOpen) {
393
433
  const [old] = [...this.docs.entries()].filter(([k]) => k !== rel).sort((a, b) => a[1].used - b[1].used)[0];
394
434
  this.notify("textDocument/didClose", { textDocument: { uri: this.docs.get(old).uri } });
395
435
  this.diagnostics.delete(this.docs.get(old).uri);
@@ -442,6 +482,226 @@ export class LeanHover {
442
482
  }),
443
483
  };
444
484
  }
485
+ /** The goals at (line, character) of the file, for the InfoView (ReviewSpec, "The InfoView"):
486
+ * before the tactic there and after it, the expected type of the term there, how many widgets
487
+ * Lean has there. Waits up to `waitMs` for Lean to elaborate that far, then says how far it is;
488
+ * a place Lean has passed is answered at once. */
489
+ async goals(file, text, hash, line, character, waitMs) {
490
+ let doc;
491
+ try {
492
+ doc = await this.open(file, text, hash);
493
+ }
494
+ catch (e) {
495
+ return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
496
+ }
497
+ const e = await Promise.race([this.goalsAt(doc, line, character), after(waitMs)]);
498
+ if (!e)
499
+ return { pending: { line: doc.processing < 0 ? doc.lines : doc.processing, of: doc.lines } };
500
+ return e.answer;
501
+ }
502
+ /** What Lean says of subterm `k` of the goals answer at (line, character): its type, the term
503
+ * with its implicit arguments, its doc. The answer is asked again where it was let go, or its
504
+ * session ended; only Lean's own reference for the subterm reaches Lean. */
505
+ async subterm(file, text, hash, line, character, k, waitMs) {
506
+ let doc;
507
+ try {
508
+ doc = await this.open(file, text, hash);
509
+ }
510
+ catch (e) {
511
+ return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
512
+ }
513
+ const deadline = Date.now() + waitMs;
514
+ for (let tries = 0; tries < 2; tries++) {
515
+ const e = await Promise.race([this.goalsAt(doc, line, character), after(Math.max(0, deadline - Date.now()))]);
516
+ if (!e)
517
+ return { pending: { line: doc.processing < 0 ? doc.lines : doc.processing, of: doc.lines } };
518
+ const ref = e.refs[k];
519
+ if (!e.answer.interactive || !ref || e.session === null)
520
+ return { error: "Lean has no such subterm there" };
521
+ // the session the answer was had in has ended: asked again in a new one
522
+ if (e.session !== doc.rpc) {
523
+ this.forget(doc, line, character);
524
+ continue;
525
+ }
526
+ const position = { line, character };
527
+ const r = await Promise.race([this.request("$/lean/rpc/call", { textDocument: { uri: doc.uri }, position, sessionId: e.session, method: "Lean.Widget.InteractiveDiagnostics.infoToInteractive", params: ref }), after(Math.max(1000, deadline - Date.now()))]);
528
+ if (!r)
529
+ return { pending: { line: doc.processing < 0 ? doc.lines : doc.processing, of: doc.lines } };
530
+ if (r.error?.code === RPC_RECONNECT) {
531
+ if (doc.rpc === e.session)
532
+ doc.rpc = null;
533
+ this.forget(doc, line, character);
534
+ continue;
535
+ }
536
+ if (r.error)
537
+ return { error: r.error.message };
538
+ // what the popup refers to is of no use once read
539
+ this.release(doc, e.session, refsIn(r.result));
540
+ return readInfo(r.result);
541
+ }
542
+ return { error: "Lean's RPC session ended" };
543
+ }
544
+ /** The goals answer at a place of a document, kept or asked; one being asked is joined. Kept, an
545
+ * answer comes at once; one that came after the page stopped waiting is kept too, so that what it
546
+ * holds in Lean is released in its turn. */
547
+ goalsAt(doc, line, character) {
548
+ const key = `${doc.version}:${line}:${character}`;
549
+ const kept = doc.answers.get(key);
550
+ if (kept) {
551
+ doc.answers.delete(key);
552
+ doc.answers.set(key, kept);
553
+ return Promise.resolve(kept);
554
+ }
555
+ let p = doc.computing.get(key);
556
+ if (!p) {
557
+ const asked = this.askGoals(doc, line, character).then((e) => {
558
+ if (doc.computing.get(key) === asked)
559
+ doc.computing.delete(key);
560
+ // a failure is asked again next time; an answer of a worker since replaced is let go
561
+ if (!e.answer.error && (e.session === null || e.session === doc.rpc))
562
+ this.keep(doc, key, e);
563
+ else if (e.session !== null)
564
+ this.release(doc, e.session, e.held);
565
+ return e;
566
+ });
567
+ p = asked;
568
+ doc.computing.set(key, p);
569
+ }
570
+ return p;
571
+ }
572
+ /** Keep an answer of a document's, the oldest let go past ANSWERS (what Lean holds for it
573
+ * released). */
574
+ keep(doc, key, e) {
575
+ doc.answers.set(key, e);
576
+ while (doc.answers.size > ANSWERS) {
577
+ const [old, gone] = doc.answers.entries().next().value;
578
+ doc.answers.delete(old);
579
+ if (gone.session !== null)
580
+ this.release(doc, gone.session, gone.held);
581
+ }
582
+ }
583
+ /** Let go of the answers kept for a place, of any version. */
584
+ forget(doc, line, character) {
585
+ for (const [key, e] of doc.answers)
586
+ if (key.endsWith(`:${line}:${character}`)) {
587
+ doc.answers.delete(key);
588
+ if (e.session !== null && e.session === doc.rpc)
589
+ this.release(doc, e.session, e.held);
590
+ }
591
+ }
592
+ /** Tell Lean what of a session's it may let go of. */
593
+ release(doc, session, refs) {
594
+ if (!refs.length || doc.rpc !== session || !this.docOf(doc.uri))
595
+ return;
596
+ for (let i = 0; i < refs.length; i += 1000)
597
+ this.notify("$/lean/rpc/release", { uri: doc.uri, sessionId: session, refs: refs.slice(i, i + 1000) });
598
+ }
599
+ /** The RPC session of a document, made once: null where Lean gives none. While there is one, every
600
+ * session is told every KEEP_ALIVE_MS that it is still in use. */
601
+ session(doc) {
602
+ if (doc.rpc)
603
+ return Promise.resolve(doc.rpc);
604
+ if (!doc.connecting) {
605
+ const version = doc.version;
606
+ const c = this.request("$/lean/rpc/connect", { uri: doc.uri }, 60_000).then((m) => {
607
+ if (doc.connecting === c)
608
+ doc.connecting = null;
609
+ const id = m.result?.sessionId;
610
+ const sid = typeof id === "string" || typeof id === "number" ? String(id) : null;
611
+ // a document opened again meanwhile has a new worker: this session was the old one's
612
+ if (!sid || !this.docOf(doc.uri) || doc.version < version)
613
+ return null;
614
+ doc.rpc = sid;
615
+ this.alive ??= setInterval(() => {
616
+ for (const d of this.docs.values())
617
+ if (d.rpc)
618
+ this.notify("$/lean/rpc/keepAlive", { uri: d.uri, sessionId: d.rpc });
619
+ }, KEEP_ALIVE_MS);
620
+ this.alive.unref?.();
621
+ return sid;
622
+ });
623
+ doc.connecting = c;
624
+ }
625
+ return doc.connecting;
626
+ }
627
+ /** Ask Lean the goals at a place: through its RPC, tagged, where it can (a session gone is made
628
+ * again once); else its plain answers. Before the tactic at its first character, after it at its
629
+ * end — or, for a tactic that holds a block of its own, where the proof goes on —, the term's
630
+ * expected type and the widgets where the place is. */
631
+ async askGoals(doc, line, character) {
632
+ const text = doc.text.split("\n")[line] ?? "";
633
+ const span = tacticSpan(text, character);
634
+ // a tactic that holds a block of its own ends inside it: the state after the whole line is
635
+ // where the proof goes on, its next line's start (the owner's decision of 2026-11-01); Lean's
636
+ // answer at the end where it does not go on there
637
+ const next = span && holdsBy(text, span.from, span.to) ? afterLine(doc.text, line, span.from) : null;
638
+ const end = { line, character: span ? span.to : character };
639
+ const at = {
640
+ before: { line, character: span ? span.from : character },
641
+ after: next ? { line: next.line, character: next.ch } : end,
642
+ here: { line, character },
643
+ ...(next ? { end } : {}),
644
+ };
645
+ const tactic = span ? { line, ...span } : null;
646
+ for (let tries = 0; tries < 2; tries++) {
647
+ const sid = await this.session(doc);
648
+ if (!sid)
649
+ break;
650
+ const r = await this.interactive(doc, sid, at);
651
+ if (r === "plain")
652
+ break;
653
+ if (r !== "reconnect")
654
+ return { ...r, answer: { tactic, ...r.answer } };
655
+ if (doc.rpc === sid)
656
+ doc.rpc = null;
657
+ }
658
+ const q = (method, position) => this.request(method, { textDocument: { uri: doc.uri }, position });
659
+ const [b, a, t, e] = await Promise.all([q("$/lean/plainGoal", at.before), q("$/lean/plainGoal", at.after), q("$/lean/plainTermGoal", at.here), at.end ? q("$/lean/plainGoal", at.end) : null]);
660
+ if (b.error && a.error && t.error)
661
+ return { answer: { error: b.error.message }, refs: [], held: [], session: null };
662
+ const before = b.error ? null : readPlainGoals(b.result);
663
+ const after = afterOf(at, before, a.error ? null : readPlainGoals(a.result), () => (e && !e.error ? readPlainGoals(e.result) : null));
664
+ return { answer: { tactic, before, ...after, term: t.error ? null : readPlainTermGoal(t.result), interactive: false }, refs: [], held: [], session: null };
665
+ }
666
+ /** The goals at the three places through Lean's RPC, in session `sid`; "reconnect" where the
667
+ * session is gone, "plain" where Lean has no such methods. */
668
+ async interactive(doc, sid, at) {
669
+ const call = (method, params, position) => this.request("$/lean/rpc/call", { textDocument: { uri: doc.uri }, position, sessionId: sid, method, params });
670
+ const where = (position) => ({ textDocument: { uri: doc.uri }, position });
671
+ const asked = await Promise.all([
672
+ call("Lean.Widget.getInteractiveGoals", where(at.before), at.before),
673
+ call("Lean.Widget.getInteractiveGoals", where(at.after), at.after),
674
+ call("Lean.Widget.getInteractiveTermGoal", where(at.here), at.here),
675
+ // counted, never fetched nor drawn: a widget's JavaScript is the project's code
676
+ call("Lean.Widget.getWidgets", at.here, at.here),
677
+ ...(at.end ? [call("Lean.Widget.getInteractiveGoals", where(at.end), at.end)] : []),
678
+ ]);
679
+ const held = asked.flatMap((m) => refsIn(m.result));
680
+ const [b, a, t, w, e] = asked;
681
+ if (asked.some((m) => m.error?.code === RPC_RECONNECT)) {
682
+ this.release(doc, sid, held);
683
+ return "reconnect";
684
+ }
685
+ if (b.error?.code === NO_METHOD || t.error?.code === NO_METHOD) {
686
+ this.release(doc, sid, held);
687
+ return "plain";
688
+ }
689
+ if (b.error && a.error && t.error) {
690
+ this.release(doc, sid, held);
691
+ return { answer: { error: b.error.message }, refs: [], held: [], session: null };
692
+ }
693
+ const reading = new Reading();
694
+ const widgets = w.error ? 0 : readWidgets(w.result);
695
+ const before = b.error ? null : readInteractiveGoals(b.result, reading);
696
+ const answer = {
697
+ before,
698
+ ...afterOf(at, before, a.error ? null : readInteractiveGoals(a.result, reading), () => (e && !e.error ? readInteractiveGoals(e.result, reading) : null)),
699
+ term: t.error ? null : readInteractiveTermGoal(t.result, reading),
700
+ ...(widgets ? { widgets } : {}),
701
+ interactive: true,
702
+ };
703
+ return { answer, refs: reading.refs, held, session: sid };
704
+ }
445
705
  /** What Lean says about the declaration `name` — its signature and doc, as its hover shows
446
706
  * them — where `module` is imported. `name` must be a name and nothing else
447
707
  * (`isDeclName`): it is written into Lean source. */
@@ -574,6 +834,9 @@ export class LeanHover {
574
834
  }
575
835
  /** Forget the running Lean: what it had open, and the questions it will not answer now. */
576
836
  reset() {
837
+ if (this.alive)
838
+ clearInterval(this.alive);
839
+ this.alive = null;
577
840
  this.ready = false;
578
841
  this.proc = null;
579
842
  this.buf = Buffer.alloc(0);
@@ -604,6 +867,16 @@ export class LeanHover {
604
867
  this.failure = null;
605
868
  }
606
869
  }
870
+ /** The goals after the tactic: where the proof goes on, as the state after the whole line (Lean's
871
+ * diff there being the next tactic's, it is made this one's: afterTheLine), where Lean has a tactic
872
+ * state there; else those at the tactic's end (`atEnd`, read only then). */
873
+ function afterOf(at, before, after, atEnd) {
874
+ if (!at.end)
875
+ return { after };
876
+ if (after)
877
+ return { after: afterTheLine(before, after), afterFrom: at.after.line };
878
+ return { after: atEnd() };
879
+ }
607
880
  /** Null after `ms`: what a question for Lean is raced against. */
608
881
  function after(ms) {
609
882
  return new Promise((ok) => setTimeout(() => ok(null), ms).unref());
@@ -77,6 +77,8 @@ export const BUILD_DELTA_MAX = 64 << 10;
77
77
  export const BUILD_DELTA_PART = 1 / 8;
78
78
  /** The graph's modules and their files (meta.modules), per graph read (agentviews.ts, graphOf). */
79
79
  const moduleFiles = new WeakMap();
80
+ /** The Lake hashes of the texts the graph's modules were compiled from, per graph read. */
81
+ const compiledHashes = new WeakMap();
80
82
  /** The modules the graph's outside declarations are in, per graph read: the only outside modules
81
83
  * whose source is served or handed to Lean (server/outside.ts). */
82
84
  const outsideModules = new WeakMap();
@@ -470,6 +472,18 @@ export class Live {
470
472
  moduleFiles.set(G.meta, (files = new Map(G.meta.modules.map((m) => [m.name, m.file]))));
471
473
  return files.get(module);
472
474
  }
475
+ /** The Lake hash of the text a module of the graph on show was compiled from (meta.modules[].compiled):
476
+ * the InfoView's goals are of that text alone (ReviewSpec, "The InfoView"). Undefined where the
477
+ * graph has no such module, or does not say. */
478
+ compiledOf(module) {
479
+ const G = graphOf(this);
480
+ if (!G)
481
+ return undefined;
482
+ let hashes = compiledHashes.get(G.meta);
483
+ if (!hashes)
484
+ compiledHashes.set(G.meta, (hashes = new Map(G.meta.modules.map((m) => [m.name, m.compiled]))));
485
+ return hashes.get(module);
486
+ }
473
487
  /** The file of a module outside the project, where an outside declaration of the graph on show
474
488
  * is in it (ReviewSpec, "The source window", the owner's decision of 2026-10-20): its package's or
475
489
  * Lean's core's (server/outside.ts), and whether that package is at another revision now than
@@ -11,7 +11,7 @@ import { SiteBusy, cacheHome, lockSite, openSite, projectDirs } from "./dirs.js"
11
11
  import { ProjectError, openProject, targetsInWords } from "./project.js";
12
12
  import { Live } from "./live.js";
13
13
  import { ReviewStore } from "./review.js";
14
- import { LeanHover } from "./hover.js";
14
+ import { KEEP_OPEN, LeanHover } from "./hover.js";
15
15
  import { Identities } from "./identity.js";
16
16
  import { LAYOUT_VERSION } from "../shared/graph.js";
17
17
  import { readProjectView, Views } from "./views.js";
@@ -133,7 +133,8 @@ async function main() {
133
133
  const review = new ReviewStore(project.root, dirs.site);
134
134
  const live = new Live(project, dirs, o.graph, review, o.editor, o.jobs);
135
135
  live.library.limit = o.libraryLimit;
136
- const hover = new LeanHover(project, dirs.cache);
136
+ // hovers and the InfoView: at most --lean-files files open at once (ReviewSpec, "The InfoView")
137
+ const hover = new LeanHover(project, dirs.cache, o.leanFiles ?? KEEP_OPEN);
137
138
  const ids = new Identities(o.identityHeader);
138
139
  let key = null;
139
140
  try {
@@ -82,19 +82,25 @@ export const TOOLS = [
82
82
  actions: {
83
83
  source: { method: "GET", path: "/api/agent/source", says: "its text and context; snapshot: at a past build", args: ["name", "snapshot"] },
84
84
  context: { method: "GET", path: "/api/agent/context", says: "namespaces, opens, variables, options in force there", args: ["name"] },
85
- module: { method: "GET", path: "/api/agent/module", says: "a module's doc comments and declarations in file order", args: ["name", "of"] },
85
+ module: { method: "GET", path: "/api/agent/module", says: "a module's doc comments and declarations in file order; lines: the file's text", args: ["name", "of", "lines"] },
86
86
  },
87
- args: { name: str("a declaration's full name; module: a module's name"), snapshot: SNAPSHOT, of: str("module: a declaration, for its module") },
87
+ args: { name: str("a declaration's full name; module: a module's name"), snapshot: SNAPSHOT, of: str("module: a declaration, for its module"), lines: str("module: <from>-<to> from 1, at most 400: the file's lines") },
88
88
  },
89
89
  {
90
90
  name: "lean",
91
- about: "Ask Lean about any name — a declaration, a constructor, a field, a generated name — where the project's module is imported.",
91
+ about: "Ask Lean about any name — a declaration, a constructor, a field, a generated name — where the project's module is imported; or the goals at a line of a proof, as its InfoView shows them.",
92
92
  actions: {
93
93
  describe: { method: "GET", path: "/api/agent/describe", says: "its signature and doc, as a hover", args: ["name", "module"] },
94
94
  print: { method: "GET", path: "/api/agent/print", says: "#print: the elaborated declaration, every name in full", args: ["name", "module", "proofs"] },
95
+ goals: { method: "GET", path: "/api/agent/goals", says: "the goals before and after the tactic at a line, and the expected type there", args: ["name", "module", "line", "column"] },
96
+ },
97
+ args: {
98
+ name: str("a full Lean name; goals: a declaration"),
99
+ module: str("optional: the module to import; goals: a module, with a line of its file"),
100
+ proofs: bool("print: proofs too"),
101
+ line: int("goals: the line, from 1, of the declaration's text (or the module's file)"),
102
+ column: int("goals: optional, from 1"),
95
103
  },
96
- args: { name: str("a full Lean name"), module: str("optional: the module to import"), proofs: bool("print: proofs too") },
97
- required: ["name"],
98
104
  },
99
105
  {
100
106
  name: "refs",
@@ -9,6 +9,7 @@ import { packageVersion } from "./doctor.js";
9
9
  import { UPDATE_MODES } from "./updates.js";
10
10
  import { DEFAULT_JOBS } from "./usage.js";
11
11
  import { invalidTemplate } from "../shared/editor.js";
12
+ import { KEEP_OPEN, MAX_LEAN_FILES } from "./hover.js";
12
13
  import { DEFAULT_LIBRARY_LIMIT, validSha } from "../shared/library.js";
13
14
  /** The usage, to stderr with status 2 for a command line it cannot read; asked for (`--help`),
14
15
  * to stdout with status 0. */
@@ -17,7 +18,7 @@ function usage(code = 2) {
17
18
  [--mathlib-cache shared|own] [--root Name]... [--port 4173] [--host 127.0.0.1]
18
19
  [--site dir] [--cache dir] [--graph saved.json]
19
20
  [--identity-header X-Forwarded-User] [--editor URL-template]
20
- [--agents read|advise|full] [--access-key-file file] [--public] [--jobs ${DEFAULT_JOBS}]
21
+ [--agents read|advise|full] [--access-key-file file] [--public] [--jobs ${DEFAULT_JOBS}] [--lean-files ${KEEP_OPEN}]
21
22
  [--public-url https://host] [--allowed-host name]... [--library-limit GB]
22
23
  [--updates auto|notify|off]
23
24
  visualproof purge-file <lean-project> <sha256> [--site dir] [--cache dir]
@@ -106,6 +107,12 @@ function usage(code = 2) {
106
107
  short, fewer run at a time. The import of a module is bound by memory bandwidth: past
107
108
  about a quarter of the cores it gains little.
108
109
 
110
+ --lean-files how many files Lean's language server keeps open at once for hovers and the
111
+ InfoView (default ${KEEP_OPEN}; 1 to ${MAX_LEAN_FILES}): each is elaborated once, then answered at once,
112
+ and the one least recently asked about is closed past this many. A file's worker holds
113
+ what its imports take — a few hundred MB, several GB on Mathlib (1.9 to 2.6 GB resident
114
+ for Sphere-Packing-Lean's files, 5.2 GB for its heaviest) — for ten idle minutes at most.
115
+
109
116
  --access-key-file let in only those given the link http://<host>:<port>/k/<key>, the key being
110
117
  what the file holds (one is made there, readable by its owner alone, if there is none).
111
118
  The link leaves a cookie in the browser; agents send Authorization: Bearer <key>.
@@ -170,7 +177,7 @@ export function parseArgs(argv) {
170
177
  console.error(`visualproof: VISUALPROOF_UPDATES=${fromEnv}: say auto, notify or off`);
171
178
  process.exit(2);
172
179
  }
173
- const o = { cmd, path: "", roots: [], port: 4173, host: "127.0.0.1", site: null, cache: null, graph: null, out: null, label: "VisualProof", identityHeader: null, editor: null, agents: "full", accessKeyFile: null, jobs: DEFAULT_JOBS, publicUrl: null, allowedHosts: [], libraryLimit: DEFAULT_LIBRARY_LIMIT, sha: null, publicRead: false, recipe: null, png: false, svg: false, screen: { w: 1920, h: 1200 }, updates: UPDATE_MODES.includes(fromEnv) ? fromEnv : "auto", remote: null, branch: null, poll: null, buildHours: null, mathlibCache: null };
180
+ const o = { cmd, path: "", roots: [], port: 4173, host: "127.0.0.1", site: null, cache: null, graph: null, out: null, label: "VisualProof", identityHeader: null, editor: null, agents: "full", accessKeyFile: null, jobs: DEFAULT_JOBS, leanFiles: null, publicUrl: null, allowedHosts: [], libraryLimit: DEFAULT_LIBRARY_LIMIT, sha: null, publicRead: false, recipe: null, png: false, svg: false, screen: { w: 1920, h: 1200 }, updates: UPDATE_MODES.includes(fromEnv) ? fromEnv : "auto", remote: null, branch: null, poll: null, buildHours: null, mathlibCache: null };
174
181
  for (let i = 0; i < rest.length; i++) {
175
182
  const a = rest[i];
176
183
  const val = () => rest[++i] ?? usage();
@@ -237,6 +244,14 @@ export function parseArgs(argv) {
237
244
  usage();
238
245
  o.jobs = n;
239
246
  }
247
+ else if (a === "--lean-files" && cmd === "serve") {
248
+ const n = Number(val());
249
+ if (!Number.isInteger(n) || n < 1 || n > MAX_LEAN_FILES) {
250
+ console.error(`visualproof: --lean-files ${String(n).slice(0, 40)}: say how many files Lean keeps open at once, from 1 to ${MAX_LEAN_FILES}`);
251
+ process.exit(2);
252
+ }
253
+ o.leanFiles = n;
254
+ }
240
255
  else if (a === "--branch" && cmd === "serve")
241
256
  o.branch = val();
242
257
  else if (a === "--poll" && cmd === "serve") {
@@ -17,7 +17,8 @@ export function readOnlyAllows(method, path) {
17
17
  // a stream is opened by GET alone: a HEAD would take one of their places for nothing
18
18
  if (path === "/api/events")
19
19
  return method === "GET";
20
- if (path === "/api/hover" || path === "/api/hover/describe" || path === "/api/hover/print")
20
+ // and the InfoView's goals at a place, and what a subterm of them is (ReviewSpec, "The InfoView")
21
+ if (path === "/api/hover" || path === "/api/hover/describe" || path === "/api/hover/print" || path === "/api/hover/goals" || path === "/api/hover/goals/info")
21
22
  return true;
22
23
  for (const p of ["/api/views", "/api/history", "/api/library", "/api/export"])
23
24
  if (path === p || path.startsWith(`${p}/`))
@@ -34,6 +34,7 @@ import { exactContext, judgedText } from "../shared/context.js";
34
34
  import { MAX_TEXT, STANDARD_AXIOMS, standing, validPrefix } from "../shared/review.js";
35
35
  import { keyableSet } from "../shared/reviewqueue.js";
36
36
  import { lakeTextHash } from "./status.js";
37
+ import { isCompiledText } from "../shared/build.js";
37
38
  const refuse = (status, error, hint) => ({ status, error, hint });
38
39
  const answer = (r) => ({ status: r.status, body: { error: r.error, hint: r.hint } });
39
40
  export class ReviewApi {
@@ -73,8 +74,10 @@ export class ReviewApi {
73
74
  const text = readFileSync(join(this.world.project.root, rel), "utf8");
74
75
  const compiled = v.modules.get(n.module)?.compiled ?? null;
75
76
  hash = lakeTextHash(text);
76
- if (compiled && hash !== compiled)
77
- return refuse(409, `${n.module} changed since it was compiled: an opinion is about the compiled version, which is not what is there now.`, "Review it once the file is compiled again.");
77
+ if (!isCompiledText(compiled, hash))
78
+ return refuse(409, compiled
79
+ ? `${n.module} changed since it was compiled: an opinion is about the compiled version, which is not what is there now.`
80
+ : `Nothing records which text ${n.module} was compiled from (a build restored from Lake's artifact cache, its file modified since): an opinion is about the compiled version.`, "Review it once the file is compiled again.");
78
81
  lines = text.split("\n");
79
82
  }
80
83
  catch {
@@ -8,7 +8,11 @@
8
8
  // - modules downstream of a failure are not rebuilt and keep their old .olean;
9
9
  // - there is no build lock. A compile in progress is a `lean … -o <libDir>/Foo.olean` process;
10
10
  // - the trace records the hash of the source it was built from. Lake rebuilds when that hash
11
- // changes, not when the mtime does, so "stale" here compares the same hash (`lakeTextHash`).
11
+ // changes, not when the mtime does, so "stale" here compares the same hash (`lakeTextHash`);
12
+ // - a build restored from Lake's artifact cache (`lake cache get`, `enableArtifactCache`) has a
13
+ // trace with its outputs and the input hash they were found under, and no inputs (the source's
14
+ // hash among them); restored from the local cache, no log either: the source counts as compiled
15
+ // as long as it has not been modified since Lake wrote that trace (`compiledFrom`).
12
16
  import { execFile } from "node:child_process";
13
17
  import { tracked } from "./children.js";
14
18
  import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
@@ -234,7 +238,7 @@ function readTrace(file, at, source) {
234
238
  const hit = traceCache.get(file);
235
239
  if (hit && hit.mtime === at)
236
240
  return hit;
237
- const v = { mtime: at, warnings: 0, sorry: false, builtFrom: null };
241
+ const v = { mtime: at, warnings: 0, sorry: false, builtFrom: null, restored: false, depHash: null };
238
242
  try {
239
243
  const t = JSON.parse(readFileSync(file, "utf8"));
240
244
  for (const e of (t.log ?? [])) {
@@ -247,6 +251,11 @@ function readTrace(file, at, source) {
247
251
  if (Array.isArray(inp) && typeof inp[0] === "string" && inp[0].endsWith(source))
248
252
  v.builtFrom = inp[1];
249
253
  }
254
+ // a restored build's trace (Lake's `BuildMetadata.ofFetch`, `synthetic`; or the one a cache's
255
+ // `.ltar` holds, which keeps the outputs and the log alone): the outputs, and no inputs at all
256
+ v.restored = v.builtFrom === null && t.outputs != null && !(Array.isArray(t.inputs) && t.inputs.length);
257
+ if (typeof t.depHash === "string")
258
+ v.depHash = t.depHash;
250
259
  }
251
260
  catch {
252
261
  // a trace being written: read it next time
@@ -254,12 +263,38 @@ function readTrace(file, at, source) {
254
263
  traceCache.set(file, v);
255
264
  return v;
256
265
  }
266
+ /** Each restored build's text found compiled, by its trace's file: the input hash Lake found the
267
+ * outputs under and the text's hash (`compiledFrom`). */
268
+ const restoredTexts = new Map();
269
+ /** The Lake hash of the text a build was compiled from: the one its trace records; for a build
270
+ * restored from Lake's artifact cache, which records none, the source's as it is now, where the
271
+ * source has not been modified since Lake wrote the trace. Lake writes it once it has hashed the
272
+ * source, with everything else the module is built from, into the input hash it found the outputs
273
+ * under: the text there then is the text they were compiled from. Modified since, nothing is
274
+ * known of it — Lake would hash it again — and nothing is claimed, but where the same trace was
275
+ * seen with the same text before: a file saved or checked out again unchanged (Lake, finding the
276
+ * same input hash, leaves the trace as it is). Seen by this process alone: after a restart such a
277
+ * file counts as changed until Lake writes its trace again. */
278
+ export function compiledFrom(t, traceAt, src, traceFile = "") {
279
+ if (t.builtFrom !== null)
280
+ return t.builtFrom;
281
+ if (!t.restored || src === null)
282
+ return null;
283
+ if (src.at <= traceAt) {
284
+ if (traceFile)
285
+ restoredTexts.set(traceFile, { depHash: t.depHash, hash: src.hash });
286
+ return src.hash;
287
+ }
288
+ const seen = traceFile ? restoredTexts.get(traceFile) : undefined;
289
+ return seen && seen.depHash === t.depHash && seen.hash === src.hash ? src.hash : null;
290
+ }
257
291
  function probe(p, m) {
258
292
  const base = join(p.libDir, ...m.name.split("."));
259
293
  const trace = mtime(base + ".trace");
260
- const t = trace !== null ? readTrace(base + ".trace", trace, "/" + m.file) : { warnings: 0, sorry: false, builtFrom: null };
294
+ const t = trace !== null ? readTrace(base + ".trace", trace, "/" + m.file) : { warnings: 0, sorry: false, builtFrom: null, restored: false, depHash: null };
261
295
  const src = sourceHash(join(p.root, m.file));
262
- return { olean: mtime(base + ".olean"), trace, source: src?.hash ?? null, sourceAt: src?.at ?? null, ...t };
296
+ const builtFrom = trace !== null ? compiledFrom(t, trace, src, base + ".trace") : null;
297
+ return { olean: mtime(base + ".olean"), trace, source: src?.hash ?? null, sourceAt: src?.at ?? null, ...t, builtFrom };
263
298
  }
264
299
  /** A look at every module's files: three times each (its outputs', its source's), read once. */
265
300
  export function probeAll(p, mods) {
@@ -292,7 +327,7 @@ export function compiledTextHash(p, module, file) {
292
327
  const trace = mtime(base + ".trace");
293
328
  if (trace === null || mtime(base + ".olean") === null)
294
329
  return null;
295
- return readTrace(base + ".trace", trace, "/" + file).builtFrom;
330
+ return compiledFrom(readTrace(base + ".trace", trace, "/" + file), trace, sourceHash(join(p.root, file)), base + ".trace");
296
331
  }
297
332
  export class BuildTracker {
298
333
  p;
@@ -329,6 +364,9 @@ export class BuildTracker {
329
364
  own.set(m.name, pr.trace !== null ? "failed" : "unbuilt");
330
365
  else if (pr.builtFrom !== null && pr.source !== null && pr.builtFrom !== pr.source)
331
366
  own.set(m.name, "stale");
367
+ // restored from Lake's artifact cache and modified since: not known to be what was compiled
368
+ else if (pr.restored && pr.builtFrom === null && pr.source !== null)
369
+ own.set(m.name, "stale");
332
370
  else
333
371
  own.set(m.name, pr.sorry ? "sorry" : "ok");
334
372
  }