visualproof 0.6.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 (60) hide show
  1. package/README.md +2 -2
  2. package/dist/extractor/Extract.lean +13 -3
  3. package/dist/server/agent.js +102 -2879
  4. package/dist/server/agentactivity.js +72 -0
  5. package/dist/server/agentadvice.js +115 -0
  6. package/dist/server/agentdocs.js +1 -1
  7. package/dist/server/agententry.js +180 -0
  8. package/dist/server/agentexport.js +469 -0
  9. package/dist/server/agentfollow.js +384 -0
  10. package/dist/server/agentgraph.js +128 -0
  11. package/dist/server/agentlean.js +144 -0
  12. package/dist/server/agentlibrary.js +1 -1
  13. package/dist/server/agentplaces.js +242 -0
  14. package/dist/server/agentread.js +569 -0
  15. package/dist/server/agenttalk.js +282 -0
  16. package/dist/server/agenttcb.js +378 -0
  17. package/dist/server/agentviews.js +2 -2
  18. package/dist/server/app.js +377 -0
  19. package/dist/server/appaccess.js +127 -0
  20. package/dist/server/appagent.js +110 -0
  21. package/dist/server/appgraph.js +176 -0
  22. package/dist/server/appshare.js +179 -0
  23. package/dist/server/appsite.js +120 -0
  24. package/dist/server/apptalk.js +178 -0
  25. package/dist/server/artcmd.js +1 -1
  26. package/dist/server/events.js +1 -1
  27. package/dist/server/history.js +51 -3
  28. package/dist/server/historyapi.js +34 -2
  29. package/dist/server/hover.js +11 -7
  30. package/dist/server/identity.js +1 -1
  31. package/dist/server/libraryroute.js +3 -3
  32. package/dist/server/live.js +61 -2
  33. package/dist/server/main.js +17 -1746
  34. package/dist/server/options.js +350 -0
  35. package/dist/server/outside.js +311 -0
  36. package/dist/server/pastdoc.js +22 -3
  37. package/dist/server/project.js +28 -4
  38. package/dist/server/send.js +259 -0
  39. package/dist/server/talk.js +13 -7
  40. package/dist/server/tokens.js +3 -3
  41. package/dist/server/view.js +3 -1
  42. package/dist/server/views.js +1 -1
  43. package/dist/shared/artrecipe.js +3 -3
  44. package/dist/shared/collab.js +1 -1
  45. package/dist/shared/comment.js +1 -1
  46. package/dist/shared/doc/build.js +30 -14
  47. package/dist/shared/doc/latex.js +7 -2
  48. package/dist/shared/doc/model.js +4 -2
  49. package/dist/shared/doc/sections.js +21 -4
  50. package/dist/shared/outside.js +16 -0
  51. package/dist/shared/pastgraph.js +11 -2
  52. package/dist/shared/scope.js +1 -1
  53. package/dist/web/bundle/app.js +49580 -49284
  54. package/dist/web/src/selection.js +1 -1
  55. package/dist/web/src/theme.js +1 -1
  56. package/dist/web/src/visitors.js +1 -1
  57. package/docs/agent-api/export.md +8 -5
  58. package/docs/agent-api/history.md +3 -1
  59. package/docs/agent-api/reading.md +8 -2
  60. package/package.json +1 -1
@@ -4,7 +4,9 @@
4
4
  // makes the same graph here from the same answers (server/historyapi.ts), so that the document holds
5
5
  // exactly what the board shows, and reads each module's text of that build from the history's blobs
6
6
  // (server/sourcestore.ts, HistorySpec decisions 20–23). A text that is not kept is said so, never
7
- // stood in for by the latest build's.
7
+ // stood in for by the latest build's. A module outside the project is not kept per build: its text
8
+ // is its package's file now where that package is at the revision the build had, else not kept
9
+ // (decision 24; server/historyapi.ts, `pastOutside`).
8
10
  //
9
11
  // A snapshot's graph takes about a second to read back, and the past graph made from it a fraction
10
12
  // more: the last few builds printed are kept, each with the texts read for it, so that a second
@@ -12,7 +14,7 @@
12
14
  // again.
13
15
  import { pastGraph } from "../shared/pastgraph.js";
14
16
  import { pageGraph } from "./history.js";
15
- import { MOST_DIFF, snapshotDiff } from "./historyapi.js";
17
+ import { MOST_DIFF, pastOutside, snapshotDiff } from "./historyapi.js";
16
18
  /** how many past builds are kept: a past graph and the texts read for a large view are large on a
17
19
  * large project (Sphere-Packing-Lean's past graph: 13.7 MB of JSON) */
18
20
  const KEEP = 2;
@@ -53,6 +55,18 @@ export class PastBuilds {
53
55
  kept[m] = r.check;
54
56
  const past = pastGraph({ snapshot: info, modules: pg.modules, nodes: pg.nodes, projectCount: pg.projectCount, axioms: pg.axioms, axiomSets: pg.axiomSets, edgeCount: snap.edges.length, sources: kept }, Int32Array.from(pg.edges), now, diff);
55
57
  const texts = new Map();
58
+ // the outside world's texts of that build: its packages' files now, where at its revisions
59
+ const outsideTexts = new Map();
60
+ const w = this.w;
61
+ const outsideNow = w.outsideNow && ((m) => w.outsideNow(m));
62
+ const outside = (m) => {
63
+ if (!outsideTexts.has(m)) {
64
+ const r = outsideNow && h.outsideModulesOf(id).has(m) ? pastOutside(info, m, outsideNow) : null;
65
+ const body = r?.status === 200 ? r.body : null;
66
+ outsideTexts.set(m, body && { file: body.file, package: body.outside.package, lines: body.text.split("\n") });
67
+ }
68
+ return outsideTexts.get(m);
69
+ };
56
70
  const b = {
57
71
  info,
58
72
  past,
@@ -60,10 +74,15 @@ export class PastBuilds {
60
74
  source: (m) => {
61
75
  if (!texts.has(m)) {
62
76
  const t = h.textOf(id, m);
63
- texts.set(m, t && t.text !== null ? { lines: t.text.split("\n"), edited: false, contexts: null, hash: null, check: t.ref.check ?? "lake" } : null);
77
+ const o = t ? null : outside(m);
78
+ texts.set(m, t && t.text !== null ? { lines: t.text.split("\n"), edited: false, contexts: null, hash: null, check: t.ref.check ?? "lake" } : o ? { lines: o.lines, edited: false, contexts: null, hash: null } : null);
64
79
  }
65
80
  return texts.get(m);
66
81
  },
82
+ outside: (m) => {
83
+ const o = outside(m);
84
+ return o && { file: o.file, package: o.package };
85
+ },
67
86
  };
68
87
  this.kept.set(key, b);
69
88
  while (this.kept.size > KEEP)
@@ -17,6 +17,13 @@ export function readLakefileToml(text) {
17
17
  const dt = head.match(/^\s*defaultTargets\s*=\s*\[([^\]]*)\]/m);
18
18
  if (dt)
19
19
  out.defaultTargets = strings(dt[1]);
20
+ const dir = (t, key) => t.match(new RegExp(String.raw `^\s*${key}\s*=\s*"([^"]*)"`, "m"))?.[1];
21
+ const src = dir(head, "srcDir");
22
+ if (src !== undefined)
23
+ out.srcDir = src;
24
+ const build = dir(head, "buildDir");
25
+ if (build !== undefined)
26
+ out.buildDir = build;
20
27
  for (const table of text.split(/^(?=\s*\[)/m)) {
21
28
  if (!/^\s*\[\[\s*lean_lib\s*\]\]/.test(table))
22
29
  continue;
@@ -25,7 +32,8 @@ export function readLakefileToml(text) {
25
32
  continue;
26
33
  const roots = table.match(/^\s*roots\s*=\s*\[([^\]]*)\]/m);
27
34
  const globs = table.match(/^\s*globs\s*=\s*\[([^\]]*)\]/m);
28
- out.libs.push({ name: lib[1], ...(roots ? { roots: strings(roots[1]) } : {}), ...(globs ? { globs: strings(globs[1]) } : {}) });
35
+ const libSrc = dir(table, "srcDir");
36
+ out.libs.push({ name: lib[1], ...(roots ? { roots: strings(roots[1]) } : {}), ...(globs ? { globs: strings(globs[1]) } : {}), ...(libSrc !== undefined ? { srcDir: libSrc } : {}) });
29
37
  }
30
38
  return out;
31
39
  }
@@ -64,11 +72,24 @@ export function readLakefileLean(text) {
64
72
  const name = code.match(new RegExp(String.raw `^package\s+${ident}`, "m"));
65
73
  if (name)
66
74
  out.name = unquote(name[1]);
75
+ // a declaration runs to the next line that starts at the margin
76
+ const blockAfter = (at) => {
77
+ const rest = code.slice(at);
78
+ return rest.slice(0, rest.search(/\n(?=\S)/) + 1 || rest.length);
79
+ };
80
+ const dir = (block, key) => block.match(new RegExp(String.raw `\b${key}\s*:=\s*"([^"]*)"`))?.[1];
81
+ if (name) {
82
+ const block = blockAfter(name.index + name[0].length);
83
+ const src = dir(block, "srcDir");
84
+ if (src !== undefined)
85
+ out.srcDir = src;
86
+ const build = dir(block, "buildDir");
87
+ if (build !== undefined)
88
+ out.buildDir = build;
89
+ }
67
90
  const targets = [];
68
91
  for (const m of code.matchAll(new RegExp(String.raw `(@\[[^\]]*\]\s*)?lean_lib\s+${ident}`, "g"))) {
69
- // the library's declaration runs to the next line that starts at the margin
70
- const rest = code.slice(m.index + m[0].length);
71
- const block = rest.slice(0, rest.search(/\n(?=\S)/) + 1 || rest.length);
92
+ const block = blockAfter(m.index + m[0].length);
72
93
  const lib = { name: unquote(m[2]) };
73
94
  const roots = block.match(/\broots\s*:=\s*#\[([^\]]*)\]/);
74
95
  if (roots)
@@ -78,6 +99,9 @@ export function readLakefileLean(text) {
78
99
  const kinds = { one: "", submodules: ".+", andSubmodules: ".*" };
79
100
  lib.globs = [...globs[1].matchAll(new RegExp(String.raw `(?:Glob)?\.(one|submodules|andSubmodules)\s+\x60` + ident, "g"))].map((g) => unquote(g[2]) + kinds[g[1]]);
80
101
  }
102
+ const libSrc = dir(block, "srcDir");
103
+ if (libSrc !== undefined)
104
+ lib.srcDir = libSrc;
81
105
  out.libs.push(lib);
82
106
  if (m[1] && /\bdefault_target\b/.test(m[1]))
83
107
  targets.push(lib.name);
@@ -0,0 +1,259 @@
1
+ // How the server sends what it answers (server/app.ts): JSON, the page's files, the graph's parts,
2
+ // the whole of a revision, texts and downloads; and a body refused as too large while it comes.
3
+ //
4
+ // Pages are often far from the server (CollabSpec, "Far pages"): every byte counts, and what a
5
+ // browser has it should not fetch again. The page's files and the graph are sent compressed, with
6
+ // a tag naming their content; a browser that has that content already is told so (304) and sends
7
+ // nothing more. Everything else in JSON is compressed when it is large.
8
+ import { createHash } from "node:crypto";
9
+ import { existsSync, readFileSync, statSync } from "node:fs";
10
+ import { extname } from "node:path";
11
+ import { gunzip, gunzipSync, gzip, gzipSync } from "node:zlib";
12
+ import { packEdges } from "../shared/edgecodec.js";
13
+ const TYPES = {
14
+ ".woff2": "font/woff2",
15
+ ".html": "text/html; charset=utf-8",
16
+ ".css": "text/css; charset=utf-8",
17
+ ".js": "text/javascript; charset=utf-8",
18
+ ".map": "application/json",
19
+ };
20
+ /** The tag naming a content. */
21
+ function tagOf(body) {
22
+ return `"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
23
+ }
24
+ /** Whether the request already has the content `etag` names. */
25
+ function fresh(req, etag) {
26
+ const have = req.headers["if-none-match"];
27
+ return !!have && have.split(",").some((t) => t.trim().replace(/^W\//, "") === etag);
28
+ }
29
+ function acceptsGzip(req) {
30
+ return /\bgzip\b/.test(String(req?.headers["accept-encoding"] ?? ""));
31
+ }
32
+ /** the page's files as last read: compressed and tagged once per change on disk */
33
+ const files = new Map();
34
+ export function sendFile(req, res, file) {
35
+ if (refused.has(res))
36
+ return;
37
+ if (!existsSync(file))
38
+ return sendJson(res, { error: "not found" }, 404);
39
+ const st = statSync(file);
40
+ let f = files.get(file);
41
+ if (!f || f.mtime !== st.mtimeMs || f.size !== st.size) {
42
+ const body = readFileSync(file);
43
+ f = { mtime: st.mtimeMs, size: st.size, body, gz: null, etag: tagOf(body) };
44
+ files.set(file, f);
45
+ }
46
+ const head = { "content-type": TYPES[extname(file)] ?? "application/octet-stream", "cache-control": "no-cache", etag: f.etag, vary: "accept-encoding" };
47
+ if (fresh(req, f.etag)) {
48
+ res.writeHead(304, head);
49
+ return void res.end();
50
+ }
51
+ if (!acceptsGzip(req)) {
52
+ res.writeHead(200, head);
53
+ return void res.end(f.body);
54
+ }
55
+ f.gz ??= gzipSync(f.body, { level: 9 });
56
+ res.writeHead(200, { ...head, "content-encoding": "gzip" });
57
+ res.end(f.gz);
58
+ }
59
+ /** how long the rest of a body refused as too large is read before it is answered all the same,
60
+ * and the connection cut: long enough for a client to finish sending what it began, not for an
61
+ * endless body */
62
+ const TOO_LARGE_GRACE_MS = 2000;
63
+ export class TooLarge extends Error {
64
+ }
65
+ /** A request's body, refused (TooLarge) once it passes `limit` bytes: what comes after is not kept. */
66
+ export function readBody(req, limit) {
67
+ return new Promise((ok, fail) => {
68
+ const parts = [];
69
+ let size = 0;
70
+ if (Number(req.headers["content-length"]) > limit)
71
+ return fail(new TooLarge());
72
+ req.on("data", (b) => {
73
+ if (size > limit)
74
+ return;
75
+ size += b.length;
76
+ if (size > limit) {
77
+ parts.length = 0;
78
+ fail(new TooLarge());
79
+ }
80
+ else
81
+ parts.push(b);
82
+ });
83
+ req.on("end", () => ok(Buffer.concat(parts).toString("utf8")));
84
+ req.on("error", fail);
85
+ });
86
+ }
87
+ /** Responses refused as too large and not answered yet (tooLarge): what the handler that asked for
88
+ * the body answers meanwhile is not sent. */
89
+ export const refused = new WeakSet();
90
+ /** Answer 413 to a body too large and close the connection. The rest of the body is read and thrown
91
+ * away first, and the answer goes once it has all come: a connection closed while the client is
92
+ * still sending is reset on some systems (macOS), and the client never reads the answer. A client
93
+ * still sending after a short grace is answered all the same, and cut off. */
94
+ export function tooLarge(req, res, body) {
95
+ refused.add(res);
96
+ let done = false;
97
+ const answer = () => {
98
+ if (done)
99
+ return;
100
+ done = true;
101
+ refused.delete(res);
102
+ sendJson(res, body, 413, { connection: "close" });
103
+ };
104
+ req.on("data", () => { });
105
+ req.on("end", answer);
106
+ req.resume();
107
+ if (req.readableEnded)
108
+ answer();
109
+ setTimeout(() => {
110
+ answer();
111
+ setTimeout(() => req.socket.destroy(), 500).unref();
112
+ }, TOO_LARGE_GRACE_MS).unref();
113
+ }
114
+ /** Send a JSON answer, once: a handler that answers after something else already did (a body too
115
+ * large, answered as it was read) is not heard. */
116
+ export function sendJson(res, body, code = 200, headers = {}) {
117
+ if (res.headersSent || res.writableEnded || refused.has(res))
118
+ return;
119
+ sendJsonText(res, JSON.stringify(body), code, headers);
120
+ }
121
+ /** The same, of an answer written as JSON already. */
122
+ function sendJsonText(res, text, code = 200, headers = {}) {
123
+ if (res.headersSent || res.writableEnded || refused.has(res))
124
+ return;
125
+ // a small answer is not worth compressing; a status with its build log, a source file, are; a
126
+ // large one is compressed off the server's thread, which meanwhile answers others
127
+ if (text.length > JSON_GZIP_FROM && acceptsGzip(res.req)) {
128
+ res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", "content-encoding": "gzip", vary: "accept-encoding", ...headers });
129
+ if (text.length < JSON_GZIP_AWAY_FROM)
130
+ return void res.end(gzipSync(text));
131
+ return void gzip(text, (e, gz) => (e ? res.destroy(e) : res.end(gz)));
132
+ }
133
+ res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store", ...headers });
134
+ res.end(text);
135
+ }
136
+ /** what is sent whole under the tag of its revision, compressed, per what it is of (the review, the
137
+ * build status) */
138
+ const revisionGz = new WeakMap();
139
+ /** A whole sent under the tag of its revision: the review (GET /api/review), tagged with its run and
140
+ * its revision (server/review.ts), and the build status (GET /api/build, server/live.ts). A page that
141
+ * has it is answered 304, which a reload is, and one that fell behind is sent it compressed — once a
142
+ * revision, off the server's thread when it is large, the same bytes for every page (a review of
143
+ * 5,000 opinions on Sphere-Packing-Lean: 8.5 MB of JSON, 1.1 MB sent; the build status of
144
+ * NavierStokesAndEuler's 2,657 files: 362 KB, 42 KB sent). `of` is what it is of; `whole` writes it,
145
+ * asked only where it is sent. */
146
+ export function sendRevision(req, res, of, tag, whole) {
147
+ if (res.headersSent || res.writableEnded || refused.has(res))
148
+ return;
149
+ const head = { "content-type": "application/json", "cache-control": "private, no-cache", etag: tag, vary: "accept-encoding" };
150
+ if (fresh(req, tag)) {
151
+ res.writeHead(304, head);
152
+ return void res.end();
153
+ }
154
+ const text = whole();
155
+ if (text.length <= JSON_GZIP_FROM || !acceptsGzip(req)) {
156
+ res.writeHead(200, head);
157
+ return void res.end(text);
158
+ }
159
+ let c = revisionGz.get(of);
160
+ if (c?.tag !== tag) {
161
+ const gz = text.length < JSON_GZIP_AWAY_FROM ? Promise.resolve(gzipSync(text)) : new Promise((ok, fail) => gzip(text, (e, b) => (e ? fail(e) : ok(b))));
162
+ revisionGz.set(of, (c = { tag, gz }));
163
+ // a compression that failed is tried again by the next page that asks
164
+ gz.catch(() => revisionGz.get(of)?.gz === gz && revisionGz.delete(of));
165
+ }
166
+ c.gz.then((gz) => {
167
+ if (res.headersSent || res.destroyed)
168
+ return;
169
+ res.writeHead(200, { ...head, "content-encoding": "gzip" });
170
+ res.end(gz);
171
+ }, (e) => res.destroy(e));
172
+ }
173
+ /** Send a text that is not JSON (the agents' documentation, the MCP server's file), compressed
174
+ * where the client takes it. */
175
+ export function sendText(req, res, text, type, code = 200) {
176
+ if (res.headersSent || res.writableEnded || refused.has(res))
177
+ return;
178
+ const head = { "content-type": type, "cache-control": "no-store", vary: "accept-encoding" };
179
+ if (text.length > JSON_GZIP_FROM && acceptsGzip(req)) {
180
+ res.writeHead(code, { ...head, "content-encoding": "gzip" });
181
+ return void res.end(gzipSync(text));
182
+ }
183
+ res.writeHead(code, head);
184
+ res.end(text);
185
+ }
186
+ /** Send a file to download (a typeset document): as it is, never cached, named for the disk. */
187
+ export function sendDownload(res, f) {
188
+ if (res.headersSent || res.writableEnded || refused.has(res))
189
+ return;
190
+ res.writeHead(200, { "content-type": f.type, "content-length": String(f.body.length), "content-disposition": `attachment; filename="${f.name.replace(/[^A-Za-z0-9._-]/g, "_")}"`, "cache-control": "no-store" });
191
+ res.end(f.body);
192
+ }
193
+ /** The Host a request was sent to, when it looks like one. */
194
+ export function hostOf(req) {
195
+ return /^[A-Za-z0-9.:[\]-]{1,300}$/.test(req.headers.host ?? "") ? req.headers.host : "127.0.0.1";
196
+ }
197
+ /** The server's address as the request's browser reached it: its Origin where it names the host
198
+ * the request was sent to (a page's POST carries it, with the scheme), else http:// and the Host. */
199
+ export function reachedAt(req) {
200
+ const host = hostOf(req);
201
+ try {
202
+ const o = new URL(String(req.headers.origin ?? ""));
203
+ if (o.host === host && (o.protocol === "http:" || o.protocol === "https:"))
204
+ return o.origin;
205
+ }
206
+ catch {
207
+ // no Origin, or not an address: the Host
208
+ }
209
+ return `http://${host}`;
210
+ }
211
+ /** characters from which a JSON answer is sent compressed */
212
+ const JSON_GZIP_FROM = 2048;
213
+ /** characters from which a JSON answer is compressed off the server's thread: a snapshot's whole
214
+ * graph on NavierStokesAndEuler (GET /api/agent/history/graph, 105 MB of JSON) was 2 to 3 s of
215
+ * compressing, every page and agent waiting meanwhile */
216
+ export const JSON_GZIP_AWAY_FROM = 1 << 20;
217
+ /** the graph's parts as sent, each tagged once (a graph's buffers live as long as it does) */
218
+ const gzTags = new WeakMap();
219
+ /** A part of the graph, gzipped already: tagged, so that a page that has it gets 304; a client that
220
+ * does not take gzip (an agent's) is sent it as it is, made so off the server's thread. */
221
+ export function sendGz(req, res, gz, type) {
222
+ if (refused.has(res))
223
+ return;
224
+ let etag = gzTags.get(gz);
225
+ if (!etag)
226
+ gzTags.set(gz, (etag = tagOf(gz)));
227
+ const head = { "content-type": type, "cache-control": "private, no-cache", etag, vary: "accept-encoding" };
228
+ if (fresh(req, etag)) {
229
+ res.writeHead(304, head);
230
+ return void res.end();
231
+ }
232
+ if (!acceptsGzip(req))
233
+ return void gunzip(gz, (e, plain) => {
234
+ if (e)
235
+ return res.destroy(e);
236
+ res.writeHead(200, head);
237
+ res.end(plain);
238
+ });
239
+ res.writeHead(200, { ...head, "content-encoding": "gzip" });
240
+ res.end(gz);
241
+ }
242
+ /** the edges packed for pages (shared/edgecodec.ts), once per graph and format */
243
+ const packedEdges = new WeakMap();
244
+ export function packedGz(edgesGz, format) {
245
+ let byFormat = packedEdges.get(edgesGz);
246
+ if (!byFormat)
247
+ packedEdges.set(edgesGz, (byFormat = new Map()));
248
+ let p = byFormat.get(format);
249
+ if (!p) {
250
+ const raw = gunzipSync(edgesGz);
251
+ const edges = new Int32Array(raw.buffer, raw.byteOffset, raw.byteLength / 4);
252
+ let n = 0;
253
+ for (let k = 0; k < edges.length; k += 3)
254
+ n = Math.max(n, edges[k] + 1, edges[k + 1] + 1);
255
+ p = gzipSync(packEdges(edges, n, format), { level: 9 });
256
+ byFormat.set(format, p);
257
+ }
258
+ return p;
259
+ }
@@ -15,7 +15,7 @@
15
15
  //
16
16
  // The state each agent is shown in comes from what it does, not from what it says: *listening*
17
17
  // while a wait is open; *thinking* from the moment messages were handed to it until it replies, with
18
- // what its requests show it doing (server/agent.ts, doingOf) and the line it may set itself;
18
+ // what its requests show it doing (server/agenttalk.ts, doingOf) and the line it may set itself;
19
19
  // *working* when it makes requests with nothing to answer; *offline* once it has had no wait open
20
20
  // and made no request for its longest wait plus a minute — the time an agent that listens takes at
21
21
  // most to come back. An offline agent's private channel cannot be written to (409); a mention of it
@@ -27,7 +27,7 @@
27
27
  // many a minute. A person's message in the public channel keeps the tokens of the agents it is handed
28
28
  // to (`to`, the agents it mentions that were listed as it was written), which is told to nobody.
29
29
  // Revoking a token, or its expiry, ends its wait at once. Who may read and write which channel is
30
- // server/main.ts's to check (shared/collab.ts, madeBy), and which page is sent which message
30
+ // server/apptalk.ts's to check (shared/collab.ts, madeBy), and which page is sent which message
31
31
  // server/live.ts's.
32
32
  //
33
33
  // A session that replaces another knows nothing of what the page still shows (the owner's decisions
@@ -71,6 +71,10 @@ export class Talk {
71
71
  /** each channel's last id in this server's life: a channel whose messages all expired goes on
72
72
  * counting from there, so that no agent's place in it (`read`) passes what comes next */
73
73
  lastIds = new Map();
74
+ /** the order messages were written in here, which their times (to the millisecond) may not tell:
75
+ * what is handed to an agent from both channels at once is in that order (`inOrder`) */
76
+ written = new WeakMap();
77
+ writes = 0;
74
78
  agents = new Map();
75
79
  buckets = new Map();
76
80
  ticks = 0;
@@ -290,7 +294,7 @@ export class Talk {
290
294
  const a = this.agent(token);
291
295
  const mine = this.load(token).filter((m) => m.kind !== "agent" && m.id > a.read);
292
296
  const named = this.load(PUBLIC).filter((m) => m.id > a.readPublic && m.kind === "person" && !!m.to?.includes(token));
293
- return inOrder(mine, named);
297
+ return inOrder(mine, named, (m) => this.written.get(m) ?? 0);
294
298
  }
295
299
  /** What `queued` holds is the agent's from now on: what comes after it is handed next. */
296
300
  mark(a, queued) {
@@ -312,7 +316,7 @@ export class Talk {
312
316
  const news = since.filter((m) => fresh.has(m.id));
313
317
  const told = since.filter((m) => !fresh.has(m.id));
314
318
  const missed = queued.filter((m) => m.channel === "public");
315
- const earlier = earlierOf(inOrder(told, missed), news.length > 0, now);
319
+ const earlier = earlierOf(inOrder(told, missed, (m) => this.written.get(m) ?? 0), news.length > 0, now);
316
320
  return earlier ? [earlier, ...news.map(outward)] : news.map(outward);
317
321
  }
318
322
  /** Hand over what a wait answers with: what is queued is the agent's from now on; people's
@@ -428,6 +432,7 @@ export class Talk {
428
432
  this.lastIds.set(channel, id);
429
433
  const msg = { id, at: new Date(now).toISOString(), ...rest, channel: channel === PUBLIC ? "public" : "private", ...(to?.length ? { to } : {}) };
430
434
  thread.push(msg);
435
+ this.written.set(msg, ++this.writes);
431
436
  if (thread.length > 2 * HELD)
432
437
  thread.splice(0, thread.length - HELD);
433
438
  mkdirSync(this.dir, { recursive: true });
@@ -534,13 +539,14 @@ export function forPages(m) {
534
539
  const { where: _where, ...rest } = m;
535
540
  return rest;
536
541
  }
537
- /** Two channels' messages as one list, in the order they were written. */
538
- function inOrder(a, b) {
542
+ /** Two channels' messages as one list, in the order they were written: by their times, and those of
543
+ * one millisecond by `written` (what was read from disk, 0, keeps the order it is given in). */
544
+ function inOrder(a, b, written) {
539
545
  if (!b.length)
540
546
  return a;
541
547
  if (!a.length)
542
548
  return b;
543
- return [...a, ...b].sort((x, y) => (x.at < y.at ? -1 : x.at > y.at ? 1 : 0));
549
+ return [...a, ...b].sort((x, y) => (x.at < y.at ? -1 : x.at > y.at ? 1 : written(x) - written(y)));
544
550
  }
545
551
  /** What came before as the entry a returning agent is handed first, or null where there is none: the
546
552
  * newest of `told`, at most EARLIER_MESSAGES and EARLIER_CHARS characters of text, each with who
@@ -1,6 +1,6 @@
1
1
  // Agent tokens (AgentSpec decision 7): sharing with an AI agent hands it a credential of its own,
2
2
  // never the server's key. A person makes one from Share for one agent; the token fixes the agent's
3
- // name and what it may do, lasts a few days, reaches the agents' API only (server/main.ts), and can
3
+ // name and what it may do, lasts a few days, reaches the agents' API only (server/app.ts), and can
4
4
  // be revoked from Share by anyone with a name.
5
5
  //
6
6
  // A token is `vpa_<id>_<secret>`: the prefix makes one recognisable wherever it is pasted or leaks
@@ -91,7 +91,7 @@ export class AgentTokens {
91
91
  }
92
92
  }
93
93
  /** Make a token for an agent: the token (for its prompt) and its record. The name and level are
94
- * checked by the caller (server/main.ts); the name is used as given, numbered when an agent in
94
+ * checked by the caller (server/appshare.ts); the name is used as given, numbered when an agent in
95
95
  * force has it already; `by` is a person's name, and `person` their personal link's id where an
96
96
  * invited person makes it (`makerPerson`: who its maker is, AgentSpec decision 7). */
97
97
  create(o) {
@@ -119,7 +119,7 @@ export class AgentTokens {
119
119
  this.onChanged();
120
120
  return { token: tokenOf(record), record };
121
121
  }
122
- /** A token in force, whole, for its prompt to be shown again (server/main.ts); null when there is
122
+ /** A token in force, whole, for its prompt to be shown again (server/appshare.ts); null when there is
123
123
  * no such token in force — an ended one is never shown. */
124
124
  token(id, now = Date.now()) {
125
125
  const r = this.inForce(now).find((x) => x.id === id);
@@ -63,8 +63,10 @@ function viewParts(p, ex) {
63
63
  v.proofs = n.proofs;
64
64
  return v;
65
65
  });
66
+ // an outside declaration's doc and place in its package's source, which the source window shows
67
+ // (ReviewSpec, "The source window", the owner's decision of 2026-10-20)
66
68
  for (const e of g.externals)
67
- nodes.push({ name: e.name, kind: e.kind, module: e.module, ax: e.ax, ext: true });
69
+ nodes.push({ name: e.name, kind: e.kind, module: e.module, ax: e.ax, ext: true, ...(e.doc ? { doc: e.doc } : {}), ...(e.range ? { range: e.range } : {}) });
68
70
  notationStatements(p, nodes);
69
71
  const edges = new Int32Array(g.edges.length * 3);
70
72
  g.edges.forEach(([s, d, m], i) => {
@@ -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. */
@@ -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;
@@ -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. */