visualproof 0.5.0 → 0.7.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 (107) hide show
  1. package/README.md +2 -2
  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 +125 -115
  17. package/dist/assets/tips/tour.webp +0 -0
  18. package/dist/extractor/Extract.lean +13 -3
  19. package/dist/mcp/visualproof-mcp.mjs +20 -9
  20. package/dist/server/access.js +28 -0
  21. package/dist/server/agent.js +130 -2819
  22. package/dist/server/agentactivity.js +72 -0
  23. package/dist/server/agentadvice.js +115 -0
  24. package/dist/server/agentdocs.js +1 -1
  25. package/dist/server/agententry.js +180 -0
  26. package/dist/server/agentexport.js +469 -0
  27. package/dist/server/agentfollow.js +384 -0
  28. package/dist/server/agentgraph.js +128 -0
  29. package/dist/server/agentlean.js +144 -0
  30. package/dist/server/agentlibrary.js +1 -1
  31. package/dist/server/agentplaces.js +242 -0
  32. package/dist/server/agentread.js +569 -0
  33. package/dist/server/agenttalk.js +282 -0
  34. package/dist/server/agenttcb.js +378 -0
  35. package/dist/server/agentviews.js +2 -2
  36. package/dist/server/app.js +377 -0
  37. package/dist/server/appaccess.js +127 -0
  38. package/dist/server/appagent.js +110 -0
  39. package/dist/server/appgraph.js +176 -0
  40. package/dist/server/appshare.js +179 -0
  41. package/dist/server/appsite.js +120 -0
  42. package/dist/server/apptalk.js +178 -0
  43. package/dist/server/artcmd.js +1 -1
  44. package/dist/server/askfollow.js +1 -1
  45. package/dist/server/deploy.js +204 -53
  46. package/dist/server/events.js +1 -1
  47. package/dist/server/history.js +51 -3
  48. package/dist/server/historyapi.js +34 -2
  49. package/dist/server/hover.js +11 -7
  50. package/dist/server/identity.js +1 -1
  51. package/dist/server/invites.js +113 -20
  52. package/dist/server/libraryroute.js +3 -3
  53. package/dist/server/live.js +186 -30
  54. package/dist/server/main.js +31 -1613
  55. package/dist/server/mcptools.js +33 -20
  56. package/dist/server/options.js +350 -0
  57. package/dist/server/outside.js +311 -0
  58. package/dist/server/pastdoc.js +22 -3
  59. package/dist/server/presence.js +3 -3
  60. package/dist/server/project.js +28 -4
  61. package/dist/server/prompt.js +8 -3
  62. package/dist/server/readonlygate.js +4 -4
  63. package/dist/server/reviewapi.js +51 -17
  64. package/dist/server/send.js +259 -0
  65. package/dist/server/talk.js +238 -116
  66. package/dist/server/tokens.js +13 -5
  67. package/dist/server/view.js +3 -1
  68. package/dist/server/views.js +1 -1
  69. package/dist/shared/artrecipe.js +3 -3
  70. package/dist/shared/build.js +35 -1
  71. package/dist/shared/collab.js +9 -1
  72. package/dist/shared/comment.js +1 -1
  73. package/dist/shared/doc/build.js +30 -14
  74. package/dist/shared/doc/latex.js +7 -2
  75. package/dist/shared/doc/model.js +4 -2
  76. package/dist/shared/doc/sections.js +21 -4
  77. package/dist/shared/keys.js +66 -37
  78. package/dist/shared/lostfound.js +1 -0
  79. package/dist/shared/mentions.js +83 -0
  80. package/dist/shared/outside.js +16 -0
  81. package/dist/shared/pastgraph.js +11 -2
  82. package/dist/shared/query.js +13 -4
  83. package/dist/shared/review.js +91 -21
  84. package/dist/shared/reviewqueue.js +6 -1
  85. package/dist/shared/scope.js +1 -1
  86. package/dist/web/bundle/app.js +51289 -49853
  87. package/dist/web/index.html +45 -9
  88. package/dist/web/src/reviewqueue.js +52 -19
  89. package/dist/web/src/selection.js +1 -1
  90. package/dist/web/src/theme.js +1 -1
  91. package/dist/web/src/trust.js +271 -0
  92. package/dist/web/src/visitors.js +1 -1
  93. package/dist/web/style.css +181 -70
  94. package/docs/agent-api/README.md +13 -11
  95. package/docs/agent-api/advice.md +8 -2
  96. package/docs/agent-api/export.md +9 -6
  97. package/docs/agent-api/following.md +11 -12
  98. package/docs/agent-api/history.md +6 -3
  99. package/docs/agent-api/mcp.md +15 -15
  100. package/docs/agent-api/notes.md +1 -1
  101. package/docs/agent-api/reading.md +10 -4
  102. package/docs/agent-api/requests.md +12 -15
  103. package/docs/agent-api/talking.md +60 -55
  104. package/docs/agent-api/tcb.md +21 -21
  105. package/docs/agent-api/views.md +3 -4
  106. package/docs/agent-api/words.md +8 -8
  107. package/package.json +2 -1
@@ -935,7 +935,7 @@ export class Views {
935
935
  return null;
936
936
  }
937
937
  // ---------------------------------------------------------------- the page's endpoints
938
- /** A request under /api/views, read by main.ts: what the page asks, under the name it gives. An
938
+ /** A request under /api/views, read by appsite.ts: what the page asks, under the name it gives. An
939
939
  * agent may use them too, within what `--agents` allows (AgentSpec decision 9): opening a view
940
940
  * is reading; everything else, deleting a view and laying one out afresh included, is level
941
941
  * full, recorded as the agent's. A private reader's changes are recorded without a name, and
@@ -2,9 +2,9 @@
2
2
  // picture of the board is, in words that hold on any project — a size by its name, names by a rule
3
3
  // ("the clusters to depth 1, and the targets"), targets and the selection by full name — so that
4
4
  // one recipe makes the same kind of picture of every codebase. An agent sends one
5
- // (POST /api/agent/artwork, server/agent.ts); the link it gets back carries it after `#`, and the
6
- // page that opens it resolves it against the board it opens on (web/src/main.ts, openRecipe) and
7
- // opens the artwork mode with what it says, saving the files where the link asks.
5
+ // (POST /api/agent/artwork, server/agentexport.ts); the link it gets back carries it after `#`, and
6
+ // the page that opens it resolves it against the board it opens on (web/src/pageart.ts, openRecipe)
7
+ // and opens the artwork mode with what it says, saving the files where the link asks.
8
8
  import { ART_MAX_SIDE, ART_NAMES_BYTES, ART_RULED_BYTES, ART_STYLES, ART_TARGETS_BYTES, artNameId, cleanNames, FOOT_SIZE, SCHEMES, TITLE_CHARS, TITLE_SIZE } from "./collab.js";
9
9
  /** The sizes offered (web/src/artwork.ts, PRESETS), each in either orientation: given landscape;
10
10
  * `key`, a recipe's name for it. */
@@ -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
+ }
@@ -96,7 +96,7 @@ export function artNameId(kind, s) {
96
96
  return `${kind === "cluster" ? "c" : "d"}:${s}`;
97
97
  }
98
98
  /** The most an artwork's names hidden, its names shown, and its targets chosen each take in what
99
- * presence carries, in bytes of their JSON: a heartbeat is at most 16 KB (server/main.ts), and the
99
+ * presence carries, in bytes of their JSON: a heartbeat is at most 16 KB (server/apptalk.ts), and the
100
100
  * rest of where a reader is has room beside them. Names by selection are kept as what differs from
101
101
  * As shown, so that a few names hidden or added are a few names carried. */
102
102
  export const ART_NAMES_BYTES = 4000;
@@ -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) {
@@ -16,7 +16,7 @@
16
16
  // made of, what a quote of an opinion keeps, a quote of source lines, and where either goes in the
17
17
  // text being written; tested in test/comment.test.ts.
18
18
  /** the longest comment, in UTF-16 units, as the server takes it (server/reviewapi.ts,
19
- * server/agent.ts, `invalid` in shared/review.ts) */
19
+ * server/agentadvice.ts, `invalid` in shared/review.ts) */
20
20
  export const MAX_COMMENT = 10000;
21
21
  /** a quote of an opinion keeps at most this many lines of its comment, and this many characters */
22
22
  export const QUOTE_LINES = 4;
@@ -16,7 +16,10 @@
16
16
  // read but what the view's scope reads to say what it holds, and the trusted prefixes: no status,
17
17
  // no opinion is printed. Its title is the view's, as the view is named, and its author line the
18
18
  // people who left a trace on the view (ExportSpec decisions 14 and 15), whom the server finds
19
- // (shared/doc/authors.ts) and the view brings; no setting gives either.
19
+ // (shared/doc/authors.ts) and the view brings; no setting gives either. A declaration from outside
20
+ // the project is printed where it is key for a target (ExportSpec decision 8, the owner's decision of
21
+ // 2026-10-20), as the project's are, from its package's source (or Lean's core's), its proofs found
22
+ // by reading it; the rest of the outside world is counted on the head card.
20
23
  //
21
24
  // A view of a past build makes that build's document (ExportSpec decision 16): its graph is the past
22
25
  // graph its board is of (shared/pastgraph.ts), that build's declarations alone; each declaration's
@@ -35,7 +38,7 @@ import { addedNames, clusterSubject, declSubject, fileOf, linksOf } from "../lib
35
38
  import { DOC_VERSION } from "./model.js";
36
39
  import { freshSpots, orderDoc } from "./order.js";
37
40
  import { cutByText, cutProofs, statementOnly } from "./proof.js";
38
- import { planDoc, tooMuch } from "./sections.js";
41
+ import { outsideKeys, planDoc, tooMuch } from "./sections.js";
39
42
  /** A view the builder cannot make a document of: it holds nothing of the project, or more than a
40
43
  * document holds. The server answers it 400, with its message. */
41
44
  export class DocInputError extends Error {
@@ -55,7 +58,8 @@ export function buildDoc(input) {
55
58
  const { g, review: d, settings: s, view } = input;
56
59
  const past = input.past ?? null;
57
60
  const set = evaluate(view.scope, { g, review: d });
58
- const plan = planDoc(g, set, view.clustering, view.hidden);
61
+ // what it holds from outside the project that is key is printed too (decision 8)
62
+ const plan = planDoc(g, set, view.clustering, view.hidden, outsideKeys(g, d));
59
63
  const why = tooMuch(plan.count);
60
64
  if (why)
61
65
  throw new DocInputError(why);
@@ -137,7 +141,9 @@ export function buildDoc(input) {
137
141
  // the docstring shown as prose is not repeated in the code
138
142
  const code = codeFor(i, doc !== null);
139
143
  const papers = papersOf(declSubject(v.name));
140
- return { id: v.name, name: v.name, short: g.short(i), kind: v.kind, module: v.module, file: input.fileOf(v.module), line: v.range ? v.range[0] : null, doc, code, ...(papers ? { papers } : {}) };
144
+ const out = g.isExt(i) ? input.outside?.(v.module) ?? null : null;
145
+ const file = g.isExt(i) ? out?.file ?? null : input.fileOf(v.module);
146
+ return { id: v.name, name: v.name, short: g.short(i), kind: v.kind, module: v.module, file, ...(g.isExt(i) ? { external: true, ...(out ? { package: out.package } : {}) } : {}), line: v.range && (out || !g.isExt(i)) ? v.range[0] : null, doc, code, ...(papers ? { papers } : {}) };
141
147
  };
142
148
  /** A declaration's code: its source where it can be read (a theorem's up to its statement, a
143
149
  * definition's whole with the proofs in it cut), else the statement the graph holds. `dropDoc`:
@@ -160,10 +166,13 @@ export function buildDoc(input) {
160
166
  elide(c);
161
167
  return c;
162
168
  };
163
- const src = g.isExt(i) || !v.range ? null : sourceOf(v.module);
169
+ // outside the project, its package's source where it is found (decision 8)
170
+ const ext = g.isExt(i);
171
+ const src = !v.range || (ext && !input.outside?.(v.module)) ? null : sourceOf(v.module);
164
172
  const at = src ? excerptOf(src.lines, src.edited, v.name, v.range) : null;
165
- // a past build's text that is not kept (HistorySpec decision 21): its statement then, said so
166
- if (!src && past && !g.isExt(i) && v.range)
173
+ // a past build's text that is not kept (HistorySpec decisions 21 and 24): its statement then,
174
+ // said so
175
+ if (!src && past && v.range)
167
176
  return { ...fromGraph(), notKept: true };
168
177
  if (!src || !at)
169
178
  return fromGraph();
@@ -189,10 +198,10 @@ export function buildDoc(input) {
189
198
  const cut = v.proofs?.length ? cutProofs(src.lines, start, at.end, v.proofs) : null;
190
199
  return cut?.cuts ? { lines: cut.lines, proofElided: false, from: "source", proofsCut: cut.cuts } : codeOf(text, from);
191
200
  }
192
- // the pass's places are not this text's (a past build's never are): the proofs as reading the
193
- // text finds them
201
+ // the pass's places are not this text's (a past build's never are, nor the outside world's): the
202
+ // proofs as reading the text finds them
194
203
  const cut = cutByText(text);
195
- return placed({ lines: cut.lines, proofElided: false, from, ...(cut.cuts ? { proofsCut: cut.cuts } : {}), textCut: past ? "past" : src.edited ? "edited" : "unread" });
204
+ return placed({ lines: cut.lines, proofElided: false, from, ...(cut.cuts ? { proofsCut: cut.cuts } : {}), textCut: ext ? "outside" : past ? "past" : src.edited ? "edited" : "unread" });
196
205
  };
197
206
  // a declaration, then the notes attached to it, as its explanation
198
207
  const declItem = (i) => {
@@ -312,9 +321,9 @@ export function docNotes(doc) {
312
321
  };
313
322
  const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
314
323
  const out = [];
315
- const why = { edited: "their file changed since it was compiled", unread: "the usage pass has not read them (it is off, still running, or failed on their module)" };
324
+ const why = { edited: "their file changed since it was compiled", unread: "the usage pass has not read them (it is off, still running, or failed on their module)", outside: "they are outside the project, which the usage pass reads alone" };
316
325
  const reading = "Reading the text leaves out every `by` block, one that builds data too, and keeps a proof written as a term.";
317
- for (const k of ["edited", "unread"]) {
326
+ for (const k of ["edited", "unread", "outside"]) {
318
327
  const es = all.filter((e) => e.code.textCut === k);
319
328
  if (es.length)
320
329
  out.push(`The proofs inside ${count(es.length, "definition", "definitions")} were found by reading the text rather than where the usage pass found them, since ${why[k]}: ${names(es)}. ${reading}`);
@@ -330,8 +339,15 @@ export function docNotes(doc) {
330
339
  if (gone.length)
331
340
  out.push(`The text of ${count(gone.length, "declaration", "declarations")} at this build is not kept, and ${gone.length === 1 ? "its statement is" : "their statements are"} printed instead: ${names(gone)}.`);
332
341
  const bare = all.filter((e) => e.code.from === "statement" && !e.code.notKept);
333
- if (bare.length)
334
- out.push(`${count(bare.length, "declaration of the project is", "declarations of the project are")} printed from the graph's statement rather than from the source: ${names(bare)}.`);
342
+ const own = bare.filter((e) => !e.external);
343
+ const away = bare.filter((e) => e.external);
344
+ if (own.length)
345
+ out.push(`${count(own.length, "declaration of the project is", "declarations of the project are")} printed from the graph's statement rather than from the source: ${names(own)}.`);
346
+ if (away.length)
347
+ out.push(`${count(away.length, "key declaration from outside the project is", "key declarations from outside the project are")} printed by name alone, their source not found: ${names(away)}.`);
348
+ const changed = all.filter((e) => e.package && e.code.from === "edited");
349
+ if (changed.length)
350
+ out.push(`${count(changed.length, "key declaration from outside the project is", "key declarations from outside the project are")} printed from ${changed.length === 1 ? "its package" : "their packages"} as ${changed.length === 1 ? "it is" : "they are"} now, at another revision than the graph was read at, found by name: ${names(changed)}.`);
335
351
  return out;
336
352
  }
337
353
  /** A theorem's proof left out: `:= …` after the statement's last line. */
@@ -204,6 +204,9 @@ function blocks(bs) {
204
204
  /** What is said under the code of a declaration of a past build whose text of then is not kept
205
205
  * (ExportSpec decision 16): its statement as the build recorded it is printed instead. */
206
206
  export const NOT_KEPT_NOTE = "Its source text at this build is not kept: printed is its statement, as the build recorded it.";
207
+ /** The same of a declaration outside the project (HistorySpec decision 24): outside sources are not
208
+ * kept per build, and its package is at another revision now; the build kept no statement of it. */
209
+ export const OUTSIDE_NOT_KEPT_NOTE = "Its source at this build was not kept: outside sources are not kept per build, and its package is at another revision now.";
207
210
  /** A declaration: its head, its full name and place, what it is, its code. `level`: its PDF
208
211
  * bookmark's, one below its section's. */
209
212
  function decl(d, level, refs = new Map()) {
@@ -212,12 +215,14 @@ function decl(d, level, refs = new Map()) {
212
215
  out.push(`\\vpBookmark{${id}}{${int(level)}}{${escapeLatex(bookmarkText(d.short))}}`);
213
216
  out.push(`\\begin{vpDecl}{${id}}{${escapeLatex(d.short)}}{${escapeLatex(d.kind)}}`);
214
217
  out.push(`\\vpFullName{${escapeName(d.name)}}`);
215
- out.push(`\\vpPlace{${escapeName(d.module)}}{${d.file ? escapePath(d.file) : ""}}{${d.line ? int(d.line) : ""}}`);
218
+ // outside the project, its file in its package, the package named (ExportSpec decision 8)
219
+ const file = d.file ? `${d.file}${d.package ? ` (${d.package})` : ""}` : "";
220
+ out.push(`\\vpPlace{${escapeName(d.module)}}{${file ? escapePath(file) : ""}}{${d.line ? int(d.line) : ""}}`);
216
221
  if (d.doc)
217
222
  out.push(`\\begin{vpDocstring}`, blocks(d.doc), `\\end{vpDocstring}`);
218
223
  out.push(code(d.code));
219
224
  if (d.code.notKept)
220
- out.push(`\\vpDeclNote{${escapeLatex(NOT_KEPT_NOTE)}}`);
225
+ out.push(`\\vpDeclNote{${escapeLatex(d.external ? OUTSIDE_NOT_KEPT_NOTE : NOT_KEPT_NOTE)}}`);
221
226
  if (d.papers)
222
227
  out.push(papers(d.papers, refs));
223
228
  // the notes attached to it, as its explanation
@@ -33,5 +33,7 @@
33
33
  * (2026-10-12): the board's order, a section's declarations, notes and sections in one list
34
34
  * (`items`), the document's first ones too; the notes the view shows (`NoteEntry`), a declaration's
35
35
  * own under it (`DeclEntry.notes`), their images and clips as figures; a declaration a note names
36
- * linked where the document prints it (an inline `decl`). */
37
- export const DOC_VERSION = 10;
36
+ * linked where the document prints it (an inline `decl`). 11 (2026-10-20): a declaration from outside
37
+ * the project that is key for a target printed as the project's are, from its package's source
38
+ * (`DeclEntry.package`; `textCut: "outside"`), the rest of the outside world counted as before. */
39
+ export const DOC_VERSION = 11;
@@ -1,6 +1,8 @@
1
1
  // The exported document's plan (ExportSpec decisions 12 and 13): what a view holds, as the document
2
2
  // prints it. Every declaration of the project the board holds is printed, whatever is folded; what
3
- // the view holds from outside the project is not, and is counted instead. The sections are the
3
+ // the view holds from outside the project is not, and is counted instead — but where it is key for a
4
+ // target (ExportSpec decision 8, the owner's decision of 2026-10-20: key declarations may be outside
5
+ // since 0.6.0), which is printed as the project's are, from its package's source. The sections are the
4
6
  // view's cluster structure as the board shows it — its clustering, its hidden levels taken out
5
7
  // (ViewSpec decision 24; shared/layout.ts, clusterTree) — each cluster that holds something printed
6
8
  // a section, nested by its depth.
@@ -11,6 +13,7 @@
11
13
  // in that order, and the Export window (web/src/exportmodal.ts) says from it what the document will
12
14
  // hold, so that the two agree.
13
15
  import { clusterTree } from "../layout.js";
16
+ import { evaluate } from "../query.js";
14
17
  /** Heading levels: section, subsection, subsubsection, then a paragraph-level heading, which every
15
18
  * deeper level takes too. */
16
19
  export const HEADING_LEVELS = 4;
@@ -25,13 +28,23 @@ export function tooMuch(count) {
25
28
  return `This view holds ${count.toLocaleString("en")} declarations of the project; a document prints at most ${MAX_DOC_DECLS.toLocaleString("en")}. Export a narrower view: a namespace or a folder, a target's Key view (key(T)) or the TCB of a target`;
26
29
  return null;
27
30
  }
31
+ /** The declarations outside the project a document prints (ExportSpec decision 8, the owner's
32
+ * decision of 2026-10-20): those key for a target, each target's marks that its TCB or review set
33
+ * still holds (`key(targets)`, shared/query.ts), per node of `g`. */
34
+ export function outsideKeys(g, d) {
35
+ const key = evaluate({ op: "key", of: "targets" }, { g, review: d });
36
+ for (let i = 0; i < g.projectCount; i++)
37
+ key[i] = 0;
38
+ return key;
39
+ }
28
40
  /** The plan of the document of the board that holds `set` (per node of `g`) clustered by `mode`
29
41
  * with the levels `hidden` hidden. A cluster that holds no declaration of its own and one section
30
42
  * only is merged into it, its heading `A.B`, so that the document has no heading chains with
31
43
  * nothing under them; the board merges such a chain into one circle already where it holds nothing
32
44
  * else at all. On a board of a past build, `g` is its past graph (shared/pastgraph.ts), which holds
33
- * that build's declarations alone. */
34
- export function planDoc(g, set, mode, hidden) {
45
+ * that build's declarations alone. `keyed`: the declarations outside the project that are printed,
46
+ * those key for a target (`outsideKeys`); none where it is left out. */
47
+ export function planDoc(g, set, mode, hidden, keyed = null) {
35
48
  // the board's members in the whole graph's order, as a board's graph has them (shared/board.ts)
36
49
  const members = [];
37
50
  for (let i = 0; i < g.n; i++)
@@ -42,8 +55,11 @@ export function planDoc(g, set, mode, hidden) {
42
55
  const top = [];
43
56
  const by = new Map();
44
57
  let outside = 0;
58
+ let keyOutside = 0;
45
59
  members.forEach((i, k) => {
46
- if (g.isExt(i)) {
60
+ if (g.isExt(i) && keyed?.[i])
61
+ keyOutside++;
62
+ else if (g.isExt(i)) {
47
63
  outside++;
48
64
  const lib = g.nodes[i].module.split(".")[0] || g.nodes[i].module;
49
65
  by.set(lib, (by.get(lib) ?? 0) + 1);
@@ -88,6 +104,7 @@ export function planDoc(g, set, mode, hidden) {
88
104
  sections,
89
105
  count: top.length + own.reduce((a, d) => a + d.length, 0),
90
106
  sectionCount,
107
+ keyOutside,
91
108
  outside: { count: outside, by: [...by].map(([name, count]) => ({ name, count })).sort((a, b) => b.count - a.count || (a.name < b.name ? -1 : 1)) },
92
109
  };
93
110
  }
@@ -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
@@ -65,6 +65,7 @@ export function lostEntries(d, views, has, known = (n) => n.includes("."), pinWh
65
65
  name,
66
66
  ...who(o),
67
67
  ...(o.recordedBy ? { recordedBy: o.recordedBy } : {}),
68
+ ...(o.withdrawn ? { withdrawn: o.withdrawn } : {}),
68
69
  verdict: o.verdict,
69
70
  ...(o.comment ? { comment: o.comment } : {}),
70
71
  ...(was.length ? { aliases: was.map((n) => lostKey.opinion(name, n, o.at)) } : {}),
@@ -0,0 +1,83 @@
1
+ // Mentions (CollabSpec decision 13, the owner's decision of 2026-10-19): `@` and a name in a message,
2
+ // the name of a person or of an agent as it is listed. The server reads them as a message is written
3
+ // (server/talk.ts): a person's mention of an agent hands the message to that agent, an agent's is
4
+ // shown and never handed. The page completes one as it is typed, from the people online and the
5
+ // agents listed, and marks the reader's own.
6
+ //
7
+ // Names may hold spaces ("Alice's AI"), so a mention is not a word: it is read against the names it
8
+ // may be, the longest that fits first, compared as names are (shared/collab.ts, sameName), and only
9
+ // where nothing of a name goes on after it (`@Al` is not `@Alice`). An `@` inside a word (an address,
10
+ // alice@example.org) mentions nobody.
11
+ import { MAX_NAME, nameKey, sameName } from "./collab.js";
12
+ /** what a name goes on with: after a mention there is none of it, and before its `@` neither */
13
+ const WORDY = /[\p{L}\p{N}_]/u;
14
+ /** The mentions in `text` of the names `names`, in order: at each `@` that starts a word, the
15
+ * longest of the names written there. */
16
+ export function mentionsIn(text, names) {
17
+ const sorted = [...new Set(names)].filter((n) => n.trim() !== "").sort((a, b) => b.length - a.length);
18
+ const out = [];
19
+ if (!sorted.length)
20
+ return out;
21
+ for (let i = text.indexOf("@"); i >= 0; i = text.indexOf("@", i + 1)) {
22
+ if (i > 0 && WORDY.test(text[i - 1]))
23
+ continue;
24
+ const rest = text.slice(i + 1, i + 1 + MAX_NAME + 1);
25
+ if (!rest || /^\s/.test(rest))
26
+ continue;
27
+ for (const n of sorted) {
28
+ const piece = rest.slice(0, n.length);
29
+ if (piece.length === n.length && sameName(piece, n) && !WORDY.test(rest[n.length] ?? "")) {
30
+ out.push({ name: n, start: i, end: i + 1 + n.length });
31
+ i += n.length;
32
+ break;
33
+ }
34
+ }
35
+ }
36
+ return out;
37
+ }
38
+ /** The names `text` mentions, each once, in the order first mentioned. */
39
+ export function mentioned(text, names) {
40
+ const out = [];
41
+ for (const m of mentionsIn(text, names))
42
+ if (!out.some((x) => sameName(x, m.name)))
43
+ out.push(m.name);
44
+ return out;
45
+ }
46
+ /** The mention being typed just before `caret`: where its `@` is, and what follows it so far (one
47
+ * line, a name's length at most); null where none is being typed. */
48
+ export function typingMention(text, caret) {
49
+ const before = text.slice(Math.max(0, caret - MAX_NAME - 1), caret);
50
+ const at = before.lastIndexOf("@");
51
+ if (at < 0)
52
+ return null;
53
+ const start = caret - before.length + at;
54
+ if (start > 0 && WORDY.test(text[start - 1]))
55
+ return null;
56
+ const query = before.slice(at + 1);
57
+ if (/[\n@]/.test(query) || /^\s/.test(query))
58
+ return null;
59
+ return { start, query };
60
+ }
61
+ /** The names that complete `query`, at most `max`: those that start with it first, then those with a
62
+ * word that does; people before agents, each in the order given. */
63
+ export function completions(query, names, max = 8) {
64
+ const q = nameKey(query);
65
+ const seen = new Set();
66
+ const first = [], then = [];
67
+ for (const n of names) {
68
+ const k = nameKey(n.name);
69
+ if (!k || seen.has(k))
70
+ continue;
71
+ seen.add(k);
72
+ if (k.startsWith(q))
73
+ first.push(n);
74
+ else if (q && k.split(/[\s.'’-]+/).some((w) => w.startsWith(q)))
75
+ then.push(n);
76
+ }
77
+ const people = (xs) => [...xs.filter((x) => !x.agent), ...xs.filter((x) => x.agent)];
78
+ return [...people(first), ...people(then)].slice(0, max);
79
+ }
80
+ /** Whether `text` mentions `name` (the reader's, say): one of its mentions is of that name. */
81
+ export function mentions(text, name, names = [name]) {
82
+ return mentionsIn(text, [...names, name]).some((m) => sameName(m.name, name));
83
+ }
@@ -0,0 +1,16 @@
1
+ // A declaration outside the project, where it is written (ReviewSpec, "The source window", the
2
+ // owner's decision of 2026-10-20): a package of the project's lake-manifest, or Lean's core, as the
3
+ // server finds it (server/outside.ts) and tells the page and the agents with the file's text.
4
+ import { githubBlob } from "./deploy.js";
5
+ /** The package in words, as the window's title bar and the agents say it: `mathlib at 089be84`,
6
+ * `Lean v4.35.0`. */
7
+ export function packageWords(o) {
8
+ if (!o.rev)
9
+ return o.package;
10
+ return o.core ? `${o.package} ${o.rev}` : `${o.package} at ${o.rev.slice(0, 7)}`;
11
+ }
12
+ /** "Open on GitHub" for lines `from` to `to` (from 1) of an outside file: its package's repository at
13
+ * the revision; null where there is none. */
14
+ export function outsideLink(o, from, to) {
15
+ return o.github ? githubBlob(o.github.repo, o.github.rev, o.github.path, from, to) : null;
16
+ }
@@ -22,7 +22,7 @@ export const PAST_CHANGED = 4;
22
22
  /** renamed since: shown under its name then */
23
23
  export const PAST_RENAMED = 8;
24
24
  /** The git commit of a past build; none where it is not known, or only guessed. Its source is the
25
- * project's, which the page has now (web/src/main.ts, GET /api/git). */
25
+ * project's, which the page has now (web/src/pageart.ts, GET /api/git). */
26
26
  function gitThen(commit) {
27
27
  if (!commit || commit.guessed)
28
28
  return { git: undefined };
@@ -36,7 +36,16 @@ export function pastGraph(snap, edges, now, diff) {
36
36
  const thenName = new Map(diff.renamed.map(([a, b]) => [b, a]));
37
37
  const removed = new Set(diff.removed);
38
38
  const changed = new Set(diff.changed.map((n) => thenName.get(n) ?? n));
39
- const nodes = snap.nodes;
39
+ // a snapshot read before 0.7.0 recorded no place for its outside declarations: where its package
40
+ // is at the same revision now, the place now is the place then, and only there is its source shown
41
+ // (HistorySpec decision 24; the server says which), so it takes the place now
42
+ const nodes = snap.nodes.map((v, i) => {
43
+ if (i < P || v.range)
44
+ return v;
45
+ const j = now.byName.get(v.name);
46
+ const r = j !== undefined && now.isExt(j) ? now.nodes[j].range : undefined;
47
+ return r ? { ...v, range: r } : v;
48
+ });
40
49
  const meta = {
41
50
  schema: 1,
42
51
  layoutVersion: now.meta.layoutVersion,