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
@@ -0,0 +1,178 @@
1
+ // People on the page with one another (the routes of server/app.ts): where each one is, which the
2
+ // others see (presence: CollabSpec decisions 4 and 8), asking others to follow (decision 10), and
3
+ // the conversations (decision 13, AgentSpec decision 8) — the public channel, each agent's private
4
+ // one with its maker, a new conversation there. Agents do all of it through their API.
5
+ import { cleanView, madeBy, nameKey, withoutArtwork } from "../shared/collab.js";
6
+ import { forPages, MAX_PERSON, PUBLIC, THREAD } from "./talk.js";
7
+ import { mentioned } from "../shared/mentions.js";
8
+ import { sendJson } from "./send.js";
9
+ import { placeOf } from "./agentfollow.js";
10
+ /** where a reader is: the others see it (CollabSpec decision 4); of a private reader, only that
11
+ * they are here (decision 8) */
12
+ export async function presence(app, req, res, agent) {
13
+ const live = app.live;
14
+ const r = await app.json(req, 16384);
15
+ if (r.error !== undefined)
16
+ return sendJson(res, { error: r.error }, 400);
17
+ const b = (r.body ?? {});
18
+ // an agent is one entry by its name (server/presence.ts), never private; a page speaks for
19
+ // its own event stream only, by the secret the stream was given (`hello`)
20
+ const name = app.ids.who(req);
21
+ const priv = !agent && b.private === true;
22
+ // agents have no artwork (ExportSpec decision 19): the page draws it
23
+ if (agent && name)
24
+ live.presence.agentBeat(name, withoutArtwork(cleanView(b.view)));
25
+ else if (!live.beat(b.token, priv ? null : name, priv ? null : cleanView(b.view), !priv && b.idle === true, priv, !!app.ids.person(req), name))
26
+ return sendJson(res, { error: "This heartbeat is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
27
+ return sendJson(res, { ok: true });
28
+ }
29
+ /** The conversations (CollabSpec decision 13, AgentSpec decision 8), for pages: a channel read
30
+ * (GET ?channel=public|<agent id>&before=<id>, the newest 200 first) and a message written in it
31
+ * (POST {channel, text, place}). Everyone with a name reads and writes the public channel; an
32
+ * agent's private channel is its maker's alone (shared/collab.ts, madeBy: 403 to anyone else).
33
+ * A read-only reader neither sees nor writes any (403), whatever the page sends; agents talk
34
+ * through their API. A private channel cannot be written to while its agent is offline (409); a
35
+ * mention of it in the public channel can, and is handed to it when it comes back. At most so
36
+ * many messages a minute, a person's in every channel together. */
37
+ export async function chat(app, req, res, url) {
38
+ const live = app.live;
39
+ if (req.method !== "GET" && req.method !== "POST")
40
+ return sendJson(res, { error: "/api/chat answers GET and POST." }, 405);
41
+ if (app.readOnlyOf.has(req))
42
+ return sendJson(res, { error: "This page is read-only.", readOnly: true }, 403);
43
+ if (app.ids.kind(req) === "agent")
44
+ return sendJson(res, { error: "Agents talk through their API.", hint: "GET /api/agent/channel, POST /api/agent/reply." }, 403);
45
+ const me = app.ids.who(req);
46
+ if (!me)
47
+ return sendJson(res, { error: "Say who you are first: the conversations are for people with a name, and a message is sent under yours.", who: true }, 401);
48
+ const who = { name: me, person: app.ids.person(req)?.id ?? null };
49
+ /** the channel a request names: the public one, or an agent's private one that is this
50
+ * reader's — 404 where there is no such agent, 403 where it is someone else's */
51
+ const channelOf = (raw) => {
52
+ if (raw === "public" || raw === undefined || raw === null || raw === "")
53
+ return { key: PUBLIC, agent: null };
54
+ const tok = typeof raw === "string" ? live.presence.tokenOf(raw) : null;
55
+ const record = tok ? live.tokens.get(tok) : undefined;
56
+ if (!tok || !record)
57
+ return { status: 404, body: { error: "There is no such channel: public, or the id of an agent with a token of its own." } };
58
+ if (!madeBy(record, who))
59
+ return { status: 403, body: { error: `${record.name}'s private channel is ${record.by}'s, who made its token: nobody else reads or writes it.`, private: true } };
60
+ return { key: tok, agent: { id: raw, record } };
61
+ };
62
+ if (req.method === "GET") {
63
+ const c = channelOf(url.searchParams.get("channel") ?? url.searchParams.get("agent"));
64
+ if ("status" in c)
65
+ return sendJson(res, c.body, c.status);
66
+ const raw = url.searchParams.get("before");
67
+ const before = raw && /^\d{1,9}$/.test(raw) ? Number(raw) : null;
68
+ const messages = live.talk.thread(c.key, THREAD, before).map(forPages);
69
+ if (!c.agent)
70
+ return sendJson(res, { channel: PUBLIC, messages });
71
+ return sendJson(res, { channel: c.agent.id, agent: { id: c.agent.id, name: c.agent.record.name, talk: live.talk.talk(c.key) }, messages });
72
+ }
73
+ const r = await app.json(req, 1 << 16);
74
+ if (r.error !== undefined)
75
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
76
+ const b = (r.body ?? {});
77
+ const c = channelOf(b.channel ?? b.agent);
78
+ if ("status" in c)
79
+ return sendJson(res, c.body, c.status);
80
+ if (c.agent && live.talk.state(c.key) === "offline")
81
+ return sendJson(res, { error: "offline", message: `${c.agent.record.name} is offline: it can be written to once it listens again.` }, 409);
82
+ const text = typeof b.text === "string" ? b.text.trim() : "";
83
+ if (!text)
84
+ return sendJson(res, { error: "The message is empty." }, 400);
85
+ if (text.length > MAX_PERSON)
86
+ return sendJson(res, { error: `A message is at most ${MAX_PERSON.toLocaleString("en")} characters.` }, 400);
87
+ const wait = live.talk.allow("person", who.person ? `p:${who.person}` : `n:${nameKey(me)}`);
88
+ if (wait)
89
+ return sendJson(res, { error: `Too many messages at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
90
+ // where the writer was, as the page says it, bounded: a selection can be a long query; a private
91
+ // reader's message says nothing of where they are (CollabSpec decision 8), only who wrote it
92
+ const view = app.ids.privateOf(req) === null ? cleanView(b.place) : null;
93
+ const at = view ? placeOf(app.agents, view) : null;
94
+ const clip = (x, n) => (x !== null && x.length > n ? x.slice(0, n - 1) + "…" : x);
95
+ const where = at ? { inWords: clip(at.inWords, 600), view: at.view, declaration: clip(at.declaration, 300), selection: clip(at.selection, 300) } : null;
96
+ // the names it mentions; in the public channel, the agents among them are handed it
97
+ const can = live.mentionable();
98
+ const mentions = mentioned(text, can.names);
99
+ const to = c.agent ? [] : [...new Set(mentions.flatMap((n) => can.agents.get(nameKey(n)) ?? []))];
100
+ const message = live.talk.post(c.key, { from: me, kind: "person", text, ...(mentions.length ? { mentions } : {}), where, to });
101
+ return sendJson(res, { ok: true, channel: c.agent?.id ?? PUBLIC, message: forPages(message) });
102
+ }
103
+ /** A new conversation in an agent's private channel (AgentSpec decision 8, the owner's decisions
104
+ * of 2026-10-11 and 2026-10-19): a divider, from its maker alone, held to the rate of their
105
+ * messages; an offline agent's too, so that its next session starts clean. One right after
106
+ * another divides nothing: it is answered `unchanged`, and neither written nor counted. */
107
+ export async function chatNew(app, req, res) {
108
+ const live = app.live;
109
+ if (req.method !== "POST")
110
+ return sendJson(res, { error: "/api/chat/new answers POST." }, 405);
111
+ if (app.readOnlyOf.has(req))
112
+ return sendJson(res, { error: "This page is read-only.", readOnly: true }, 403);
113
+ if (app.ids.kind(req) === "agent")
114
+ return sendJson(res, { error: "A new conversation is for people to start." }, 403);
115
+ const me = app.ids.who(req);
116
+ if (!me)
117
+ return sendJson(res, { error: "Say who you are first: a new conversation is started under your name.", who: true }, 401);
118
+ const r = await app.json(req, 1 << 12);
119
+ if (r.error !== undefined)
120
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
121
+ const b = (r.body ?? {});
122
+ const tok = typeof b.agent === "string" ? live.presence.tokenOf(b.agent) : null;
123
+ const record = tok ? live.tokens.get(tok) : undefined;
124
+ if (!tok || !record)
125
+ return sendJson(res, { error: "There is no such agent: only an agent with a token of its own has a private channel." }, 404);
126
+ const person = app.ids.person(req)?.id ?? null;
127
+ if (!madeBy(record, { name: me, person }))
128
+ return sendJson(res, { error: `Only ${record.by}, who made ${record.name}'s token, starts a new conversation with it.`, private: true }, 403);
129
+ if (live.talk.fresh(tok))
130
+ return sendJson(res, { ok: true, unchanged: true, divider: null, message: "Nothing was said since the conversation began: it is new already." });
131
+ const wait = live.talk.allow("person", person ? `p:${person}` : `n:${nameKey(me)}`);
132
+ if (wait)
133
+ return sendJson(res, { error: `Too many at once: wait ${wait} s.`, retryAfter: wait }, 429, { "retry-after": String(wait) });
134
+ const divider = live.talk.restart(tok, me);
135
+ return sendJson(res, { ok: true, divider: divider && forPages(divider) });
136
+ }
137
+ /** Asking others to follow (CollabSpec decision 10, the owner's decision of 2026-10-12), for pages:
138
+ * POST /api/ask {token, to?} — the page whose event stream holds `token` asks everyone on the
139
+ * server, or the person whose page is listed as `to`, to follow its reader, who has a name and is
140
+ * visible: a private reader cannot be followed; POST /api/ask/answer {token, id, answer} — a page
141
+ * asked answers, whoever its reader is. The server relays both (server/askfollow.ts); agents ask
142
+ * through their API (POST /api/agent/ask-follow). */
143
+ export async function ask(app, req, res, url) {
144
+ const live = app.live;
145
+ if (req.method !== "POST")
146
+ return sendJson(res, { error: `${url.pathname} answers POST.` }, 405);
147
+ if (app.ids.kind(req) === "agent")
148
+ return sendJson(res, { error: "Agents ask through their API.", hint: "POST /api/agent/ask-follow." }, 403);
149
+ const r = await app.json(req, 4096);
150
+ if (r.error !== undefined)
151
+ return sendJson(res, { error: `The body is ${r.error}.` }, 400);
152
+ const b = (r.body ?? {});
153
+ const page = live.pageStream(b.token);
154
+ if (!page)
155
+ return sendJson(res, { error: "This request is not from an open event stream of this page's: it is sent with the token the stream says hello with.", stream: false }, 403);
156
+ if (url.pathname === "/api/ask/answer") {
157
+ const a = live.asks.answer(b.token, b.id, b.answer);
158
+ return sendJson(res, a.body, a.status);
159
+ }
160
+ if (url.pathname !== "/api/ask")
161
+ return sendJson(res, { error: "not found" }, 404);
162
+ const me = app.ids.who(req);
163
+ if (!me)
164
+ return sendJson(res, app.nameless(req, "a request to follow you says who asks"), 401);
165
+ if (page.private || app.ids.privateOf(req) !== null)
166
+ return sendJson(res, { error: "You are private: nobody can follow you. Go visible (the menu under your name) to ask." }, 409);
167
+ if (b.to !== undefined && b.to !== null && typeof b.to !== "string")
168
+ return sendJson(res, { error: "to is a reader's id, as presence lists them; left out, everyone." }, 400);
169
+ const person = app.ids.person(req);
170
+ // one request every 30 s per person — their personal link, else their name — and per page
171
+ const key = person ? `p:${person.id}` : `n:${nameKey(me)}`;
172
+ const a = live.asks.ask({ name: me, verified: !!person, agent: false, from: page.id, stream: b.token, rate: [key, `s:${b.token}`] }, typeof b.to === "string" ? { page: b.to } : { everyone: true });
173
+ if ("ok" in a) {
174
+ const { report: _, ...sent } = a.ok;
175
+ return sendJson(res, { ok: true, ...sent });
176
+ }
177
+ return sendJson(res, { error: a.error, ...(a.retryAfter ? { retryAfter: a.retryAfter } : {}) }, a.status, a.retryAfter ? { "retry-after": String(a.retryAfter) } : undefined);
178
+ }
@@ -118,7 +118,7 @@ export function makeArtwork(prep, review, project, ask) {
118
118
  if (problems.length)
119
119
  return { problems };
120
120
  const s = cleanSettings(res.look, { scheme: "kind", theme: "light" });
121
- // the theme as the mode sets it (web/src/main.ts, drawLook): the board's style in the artwork's,
121
+ // the theme as the mode sets it (web/src/pageart.ts, drawLook): the board's style in the artwork's,
122
122
  // the cells and the starfield in the dark one
123
123
  const css = readFileSync(join(WEB, "style.css"), "utf8");
124
124
  const v = cssTheme(css, s.style === "board" ? s.theme === "dark" : true);
@@ -4,7 +4,7 @@
4
4
  // target's TCB that changed (with the opinions that went stale by it) — and is told of re-layouts,
5
5
  // of targets taken off and of prefixes trusted or no longer trusted (the review's state keeps the
6
6
  // trusted list, not who changed it), and of what agents do beside their advice: notes, layout
7
- // batches and their undoing (server/agent.ts), and of views saved, renamed, deleted and laid out
7
+ // batches and their undoing (server/agentplaces.ts), and of views saved, renamed, deleted and laid out
8
8
  // afresh (server/views.ts). Opinions, targets and key marks are in the review's logs
9
9
  // (server/review.ts); the page reads them from there.
10
10
  //
@@ -19,6 +19,11 @@
19
19
  // history/sources/<sha256>.gz one text of a project file (server/sourcestore.ts)
20
20
  // history/snapshots/<id>.json.gz a snapshot's manifest: module → content hash, and module →
21
21
  // the text its build compiled (`sources`)
22
+ //
23
+ // The sources outside the project — the packages', Lean's core's — are not kept (HistorySpec
24
+ // decision 24, the owner's of 2026-10-20): a snapshot records each package's revision as the
25
+ // lake-manifest pinned it (`packages`; the core's is its toolchain), and a past build shows an
26
+ // outside declaration's source only where its package is at that revision now.
22
27
  // history/index.jsonl one line per snapshot (SnapshotInfo), appended; the last line
23
28
  // of an id is what it is (a build read again supersedes)
24
29
  //
@@ -72,6 +77,42 @@ export function commitNow(root) {
72
77
  const status = git(root, "status", "--porcelain", "--untracked-files=no", "--", "*.lean");
73
78
  return { hash, branch: branch && branch !== "HEAD" ? branch : null, ...(status ? { dirty: true } : {}) };
74
79
  }
80
+ /** Each package's revision as a lake-manifest's text pins it (a past build's, from its commit):
81
+ * name → rev; null where the text is not a manifest. */
82
+ export function manifestRevisions(text) {
83
+ try {
84
+ const m = JSON.parse(text);
85
+ if (!Array.isArray(m.packages))
86
+ return null;
87
+ const out = {};
88
+ for (const p of m.packages)
89
+ if (typeof p?.name === "string" && p.name && typeof p.rev === "string" && p.rev)
90
+ out[p.name] = p.rev;
91
+ return out;
92
+ }
93
+ catch {
94
+ return null;
95
+ }
96
+ }
97
+ /** Give the snapshots read before 0.7.0 recorded them their packages' revisions (HistorySpec
98
+ * decision 24): each one's commit's lake-manifest.json, where its commit is known (not guessed) and
99
+ * its `.lean` files were that commit's (not dirty); read-only git, once (a snapshot given them is
100
+ * not looked at again). How many were given theirs. */
101
+ export function backfillPackages(h, root) {
102
+ let n = 0;
103
+ for (const s of h.list()) {
104
+ const c = s.commit;
105
+ if (s.packages || !c || c.guessed || c.dirty || !/^[0-9a-f]{7,64}$/.test(c.hash))
106
+ continue;
107
+ const text = git(root, "show", `${c.hash}:./lake-manifest.json`);
108
+ const revs = text === null ? null : manifestRevisions(text);
109
+ if (!revs)
110
+ continue;
111
+ h.annotate(s.id, { packages: { revs, from: "commit" } });
112
+ n++;
113
+ }
114
+ return n;
115
+ }
75
116
  /** The project's git source and the commit checked out, as a page may show them (an artwork's foot,
76
117
  * ExportSpec decision 19): the remote's address (`origin`, else the first) with no user name or
77
118
  * password (sourceAddress); null where the project is not a git repository. Read-only, as `git`. */
@@ -213,7 +254,7 @@ function records(g) {
213
254
  r.out.push([src, at.get(dst), m]);
214
255
  }
215
256
  }
216
- const externals = g.externals.map((e) => ({ name: e.name, kind: e.kind, module: e.module, ax: axNames(e.ax) })).sort((a, b) => (a.name < b.name ? -1 : 1));
257
+ const externals = g.externals.map((e) => ({ name: e.name, kind: e.kind, module: e.module, ax: axNames(e.ax), ...(e.range ? { range: e.range } : {}) })).sort((a, b) => (a.name < b.name ? -1 : 1));
217
258
  return { modules: [...byModule.values()].sort((a, b) => (a.module < b.module ? -1 : 1)), externals, edges };
218
259
  }
219
260
  function snapNode(v, g, ax) {
@@ -419,6 +460,8 @@ export class History {
419
460
  ...(same?.renames ? { renames: same.renames } : {}),
420
461
  ...(texts ? { sources: texts } : {}),
421
462
  ...(o.tool ? { tool: o.tool } : {}),
463
+ // the packages' revisions as read now; a build read again before 0.7.0 keeps what was found
464
+ ...(o.packages ? { packages: { revs: o.packages, from: "read" } } : same?.packages ? { packages: same.packages } : {}),
422
465
  };
423
466
  this.save(info);
424
467
  this.readOf(id).add(o.fingerprint);
@@ -474,6 +517,11 @@ export class History {
474
517
  const text = ref.blob ? this.sources.text(ref.blob) : null;
475
518
  return { ref: ref.blob && text === null ? { ...ref, blob: undefined, why: "its kept text cannot be read" } : ref, text };
476
519
  }
520
+ /** The modules snapshot `id`'s outside declarations are in. */
521
+ outsideModulesOf(id) {
522
+ const g = this.graph(id);
523
+ return new Set(g ? g.nodes.slice(g.projectCount).map((v) => v.module) : []);
524
+ }
477
525
  /** The modules snapshot `id` holds. */
478
526
  modulesOf(id) {
479
527
  return Object.keys(this.manifest(id)?.modules ?? {}).sort();
@@ -523,7 +571,7 @@ export class History {
523
571
  }
524
572
  const projectCount = nodes.length;
525
573
  for (const e of externals)
526
- nodes.push({ name: e.name, kind: e.kind, module: e.module, type: "", ax: e.ax, hash: "", ext: true });
574
+ nodes.push({ name: e.name, kind: e.kind, module: e.module, type: "", ax: e.ax, hash: "", ext: true, ...(e.range ? { range: e.range } : {}) });
527
575
  const index = new Map(nodes.map((v, i) => [v.name, i]));
528
576
  const edges = [];
529
577
  recs.forEach((r, k) => {
@@ -770,7 +818,7 @@ export function pageGraph(g, identity) {
770
818
  };
771
819
  const nodes = g.nodes.map((v) => {
772
820
  if (v.ext)
773
- return { name: v.name, kind: v.kind, module: v.module, ax: axOf(v.ax), ext: true };
821
+ return { name: v.name, kind: v.kind, module: v.module, ax: axOf(v.ax), ext: true, ...(v.range ? { range: v.range } : {}) };
774
822
  const { ax, hash, shape: _s, refs: _r, ...rest } = v;
775
823
  return { ...rest, ax: axOf(ax), hash: snapVersion(v, identity), ...(v.shape ? { kernel: hash } : {}) };
776
824
  });
@@ -18,6 +18,7 @@
18
18
  import { dirname } from "node:path";
19
19
  import { MAX_ARCHIVE_KEYS, validKey } from "./lostfound.js";
20
20
  import { offThread, runJob } from "./historythread.js";
21
+ import { outsideSource } from "./outside.js";
21
22
  const no = (status, error) => ({ status, body: { error } });
22
23
  const ok = (body) => ({ status: 200, body });
23
24
  /** the parts of the last snapshots asked, per history, by snapshot, build read and renames */
@@ -87,10 +88,13 @@ export async function snapshotParts(w, id) {
87
88
  /** Module `module`'s text at snapshot `id`'s build (GET /source; HistorySpec decision 23): the
88
89
  * text its build was compiled from, with its Lake hash and how it was matched to the build, or
89
90
  * why it is not kept. Never another text. */
90
- export function pastSource(h, id, module) {
91
+ export function pastSource(h, id, module, outsideNow) {
91
92
  const s = h.get(id);
92
93
  const t = h.textOf(id, module);
93
94
  const build = { snapshot: id, at: s.at, commit: s.commit };
95
+ // a module of the outside world that build referred to (HistorySpec decision 24)
96
+ if (!t && outsideNow && !h.modulesOf(id).includes(module) && h.outsideModulesOf(id).has(module))
97
+ return pastOutside(s, module, outsideNow);
94
98
  if (!t) {
95
99
  const why = h.sourcesOf(id) === null ? "the texts of this build are still being looked for" : h.modulesOf(id).includes(module) ? "its module has no file of the project" : `the build has no module ${module.slice(0, 300)}`;
96
100
  return { status: 404, body: { error: `The text of ${module.slice(0, 300)} at this build is not kept: ${why}.`, kept: false, why, ...build } };
@@ -99,6 +103,32 @@ export function pastSource(h, id, module) {
99
103
  return { status: 404, body: { error: `The text of ${module} at this build is not kept: ${t.ref.why ?? "it was not found"}.`, kept: false, why: t.ref.why ?? null, file: t.ref.file, ...build } };
100
104
  return { status: 200, body: { module, file: t.ref.file, text: t.text, lake: t.ref.lake ?? null, check: t.ref.check, from: t.ref.from ?? null, ...build } };
101
105
  }
106
+ /** A short revision, as the answers say it: a commit's first seven characters, a release whole. */
107
+ const shortRev = (r) => (!r ? "an unrecorded revision" : /^[0-9a-f]{40,64}$/.test(r) ? r.slice(0, 7) : r);
108
+ /** Outside module `module`'s text at snapshot `s`'s build (HistorySpec decision 24, the owner's of
109
+ * 2026-10-20): outside sources are not kept per build, so it is the file as it is now where its
110
+ * package is at the revision that build had — the lake-manifest's `rev` then, recorded with the
111
+ * snapshot; for Lean's core, its toolchain — and otherwise not kept, said so with both revisions.
112
+ * `check: "rev"`: matched to the build by its package's revision. */
113
+ export function pastOutside(s, module, outsideNow) {
114
+ const build = { snapshot: s.id, at: s.at, commit: s.commit };
115
+ const no = (why, file) => ({ status: 404, body: { error: `The text of ${module.slice(0, 300)} at this build was not kept: ${why}.`, kept: false, why, outside: true, ...(file ? { file } : {}), ...build } });
116
+ const now = outsideNow(module);
117
+ if (!now)
118
+ return no("outside sources are not kept per build, and its file is not found outside the project now");
119
+ const p = now.file.package;
120
+ const revs = s.packages?.revs;
121
+ const then = p.core ? s.toolchain : revs && Object.hasOwn(revs, p.name) ? revs[p.name] : null;
122
+ const rev = p.core ? now.toolchain : p.rev;
123
+ if (!p.core && !s.packages)
124
+ return no(`outside sources are not kept per build, and the revisions of this build's packages were not recorded`, now.file.file);
125
+ if (!then || !rev || then !== rev)
126
+ return no(`outside sources are not kept per build, and ${p.core ? `the toolchain, whose core it is in, was ${then} then and is ${rev} now` : `${p.name} was at ${shortRev(then)} then and is at ${shortRev(rev)} now`}`, now.file.file);
127
+ const src = outsideSource(now.file);
128
+ if (!src)
129
+ return no("outside sources are not kept per build, and its file cannot be read now", now.file.file);
130
+ return { status: 200, body: { module, file: src.file, text: src.text, lake: null, check: "rev", from: "outside", outside: src.outside, ...build } };
131
+ }
102
132
  /** A snapshot named in the query, `id` (or another key): the snapshot, or why not. The latest
103
133
  * build's where it is left out and `dflt` says so. */
104
134
  function snapshotOf(w, a, key, dflt) {
@@ -198,7 +228,8 @@ export async function historyAnswer(w, a, refuse = () => null) {
198
228
  const module = a.query.get("module") ?? "";
199
229
  if (!module || module.length > 2000)
200
230
  return no(400, "Say which module: module=<its name>.");
201
- return pastSource(h, id, module);
231
+ // asked of the world as a method: the live server's reads its own state
232
+ return pastSource(h, id, module, w.outsideNow && ((m) => w.outsideNow(m)));
202
233
  }
203
234
  if (path === "/diff") {
204
235
  const from = snapshotOf(w, a, "from", false);
@@ -273,6 +304,7 @@ export function historyWorld(world) {
273
304
  lastHad: (name) => world.lastHad?.(name) ?? null,
274
305
  archiveEntries: (keys, on, who) => world.archiveEntries?.(keys, on, who) ?? { status: 404, body: { error: "not found" } },
275
306
  following: () => world.following?.() ?? null,
307
+ outsideNow: (module) => world.outsideNow?.(module) ?? null,
276
308
  };
277
309
  }
278
310
  /** The same, as endpoints of the agents' API (server/agent.ts): reading only, at every level. */
@@ -6,7 +6,10 @@
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.
9
+ // At most two files are kept open; the server stops after ten idle minutes. A file outside the
10
+ // project — a package's, Lean's core's, whose source the window shows too (the owner's decision of
11
+ // 2026-10-20; server/outside.ts) — is opened by the same Lean in the same way: elaborated against
12
+ // the `.olean` files of what it imports, nothing built.
10
13
  //
11
14
  // A name in a hover card opens a card of its own: what Lean says about a declaration by name is
12
15
  // asked in a scratch file of VisualProof's (in the project's cache, never in the project) that
@@ -358,10 +361,11 @@ export class LeanHover {
358
361
  this.idle.unref();
359
362
  }
360
363
  /** Have Lean elaborate a file (its present text), keeping at most KEEP_OPEN open. */
361
- async open(rel, text, hash) {
364
+ async open(file, text, hash) {
362
365
  await this.start();
363
366
  this.touch();
364
- const uri = pathToFileURL(join(this.project.root, rel)).href;
367
+ const rel = typeof file === "string" ? file : file.name;
368
+ const uri = pathToFileURL(typeof file === "string" ? join(this.project.root, file) : file.path).href;
365
369
  let doc = this.docs.get(rel);
366
370
  if (doc)
367
371
  this.unstall(doc, doc.processing >= 0);
@@ -397,10 +401,10 @@ export class LeanHover {
397
401
  }
398
402
  /** What is at (line, character) of the file — UTF-16 columns, as the page counts them. Waits
399
403
  * up to `waitMs` for Lean to elaborate that far, then says how far it is. */
400
- async hover(rel, text, hash, line, character, waitMs) {
404
+ async hover(file, text, hash, line, character, waitMs) {
401
405
  let doc;
402
406
  try {
403
- doc = await this.open(rel, text, hash);
407
+ doc = await this.open(file, text, hash);
404
408
  }
405
409
  catch (e) {
406
410
  return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
@@ -417,10 +421,10 @@ export class LeanHover {
417
421
  * hover's code — a declaration's full name where the position refers to one, a variable's name
418
422
  * where it is one — or null where Lean has nothing to say. This is how the source window links
419
423
  * every name to what it means, dot notation and `open`s included, as go-to-definition would. */
420
- async names(rel, text, hash, positions, waitMs) {
424
+ async names(file, text, hash, positions, waitMs) {
421
425
  let doc;
422
426
  try {
423
- doc = await this.open(rel, text, hash);
427
+ doc = await this.open(file, text, hash);
424
428
  }
425
429
  catch (e) {
426
430
  return { error: this.failure ?? (e instanceof Error ? e.message : String(e)) };
@@ -131,7 +131,7 @@ export function headerText(s) {
131
131
  * in the agents' answers. This is where a private reader's anonymity lives: whatever arranges a
132
132
  * board — pins, folds, re-layouts, scopes and clusterings, views made, renamed and deleted, notes
133
133
  * left on a board — takes its author from here, through server/views.ts (`handle`, whose `me` is
134
- * this) and main.ts (an undo). The review is not layout: opinions, targets, key marks and trust
134
+ * this) and appsite.ts (an undo). The review is not layout: opinions, targets, key marks and trust
135
135
  * take the caller's own name, and need one. */
136
136
  export function layoutAuthor(caller) {
137
137
  return caller.private ? null : caller.name;
@@ -1,5 +1,5 @@
1
1
  // The library's routes for pages (AttachmentSpec decisions 1–11): `/api/library/…`, behind the same
2
- // access check as the page (main.ts lets a request get here only once it is in). What they do is
2
+ // access check as the page (app.ts lets a request get here only once it is in). What they do is
3
3
  // server/library.ts's, which the agents' endpoints call too (server/agentlibrary.ts); here are only
4
4
  // what HTTP needs: who asks, the body — a file's bytes as they are, sent with the file's name in the
5
5
  // query, or JSON — and answers that are bytes (a file, a page, a clip), sent so that a browser never
@@ -55,7 +55,7 @@ function readBytes(req, limit) {
55
55
  });
56
56
  }
57
57
  /** An uploaded file's bytes, the body as it is; or null, the request answered already (413) where it
58
- * is larger than a file of the library may be. The agents' upload reads its body so too (main.ts). */
58
+ * is larger than a file of the library may be. The agents' upload reads its body so too (appagent.ts). */
59
59
  export async function readUpload(req, res) {
60
60
  try {
61
61
  return await readBytes(req, MAX_FILE);
@@ -63,7 +63,7 @@ export async function readUpload(req, res) {
63
63
  catch (e) {
64
64
  if (!(e instanceof TooLarge))
65
65
  throw e;
66
- // the rest is read and thrown away, and the answer goes once it has all come, as main.ts's
66
+ // the rest is read and thrown away, and the answer goes once it has all come, as send.ts's
67
67
  // tooLarge does: a connection closed while the client still sends is reset on some systems
68
68
  let done = false;
69
69
  const answer = () => {
@@ -33,7 +33,7 @@ import { buildChanges } from "../shared/build.js";
33
33
  import { Views } from "./views.js";
34
34
  import { graphOf, memoryProblem, titleContext } from "./agentviews.js";
35
35
  import { ownName, rebinder, versionBase, versions, withVersions } from "./versions.js";
36
- import { buildTime, commitNow, History } from "./history.js";
36
+ import { backfillPackages, buildTime, commitNow, History } from "./history.js";
37
37
  import { backfillSources, keepSources } from "./sourcestore.js";
38
38
  import { findRenames, Renames } from "./renames.js";
39
39
  import { carryClusterLinks, Library } from "./library.js";
@@ -46,6 +46,7 @@ import { boardSet } from "../shared/board.js";
46
46
  import { derivesOn, existsIn } from "../shared/noteplace.js";
47
47
  import { packageVersion } from "./version.js";
48
48
  import { withoutReasons } from "../shared/timeline.js";
49
+ import { OutsideSources } from "./outside.js";
49
50
  const TICK = 1000;
50
51
  /** outputs quiet this long, and no compile running: the build is over */
51
52
  const SETTLE = 2500;
@@ -75,6 +76,9 @@ export const BUILD_DELTA_MAX = 64 << 10;
75
76
  export const BUILD_DELTA_PART = 1 / 8;
76
77
  /** The graph's modules and their files (meta.modules), per graph read (agentviews.ts, graphOf). */
77
78
  const moduleFiles = new WeakMap();
79
+ /** The modules the graph's outside declarations are in, per graph read: the only outside modules
80
+ * whose source is served or handed to Lean (server/outside.ts). */
81
+ const outsideModules = new WeakMap();
78
82
  export class Live {
79
83
  project;
80
84
  /** the site directory and the project's caches (server/dirs.ts) */
@@ -175,6 +179,10 @@ export class Live {
175
179
  nodeIndex = new Map();
176
180
  /** the declarations outside the project the graph on show refers to: in it too */
177
181
  outside = new Set();
182
+ /** where the outside declarations' sources are (server/outside.ts), and the packages' revisions
183
+ * as the graph on show was read: a package at another one now is not the text it was read from */
184
+ outsideSources;
185
+ outsideRead = null;
178
186
  constructor(project, dirs, saved, review, editor = null, jobs = DEFAULT_JOBS) {
179
187
  this.project = project;
180
188
  this.dirs = dirs;
@@ -182,6 +190,8 @@ export class Live {
182
190
  this.review = review;
183
191
  this.editor = editor;
184
192
  this.usage = new UsagePass(project, dirs, saved ? 0 : jobs, (l) => this.say(l));
193
+ // the toolchain is the project's as it is now: a branch followed may change it (server/deploy.ts)
194
+ this.outsideSources = new OutsideSources(project.root, () => this.project.toolchain);
185
195
  this.tracker = new BuildTracker(project);
186
196
  this.timeline = new Timeline(dirs.site, (e) => this.sendActivity(e));
187
197
  this.tokens = new AgentTokens(dirs.site);
@@ -372,6 +382,39 @@ export class Live {
372
382
  moduleFiles.set(G.meta, (files = new Map(G.meta.modules.map((m) => [m.name, m.file]))));
373
383
  return files.get(module);
374
384
  }
385
+ /** The file of a module outside the project, where an outside declaration of the graph on show
386
+ * is in it (ReviewSpec, "The source window", the owner's decision of 2026-10-20): its package's or
387
+ * Lean's core's (server/outside.ts), and whether that package is at another revision now than
388
+ * when the graph was read (`changed`). Undefined where the graph has no outside declaration in
389
+ * that module (or there is no graph yet, or it is a saved graph's, whose project is not here),
390
+ * null where its file is not found. */
391
+ outsideFile(module) {
392
+ const G = graphOf(this);
393
+ if (!G || this.saved)
394
+ return undefined;
395
+ let mods = outsideModules.get(G.meta);
396
+ if (!mods)
397
+ outsideModules.set(G.meta, (mods = new Set(G.meta.nodes.slice(G.meta.projectCount).map((v) => v.module))));
398
+ if (!mods.has(module))
399
+ return undefined;
400
+ const file = this.outsideSources.find(module);
401
+ if (!file)
402
+ return null;
403
+ const read = this.outsideRead;
404
+ const p = file.package;
405
+ const changed = !!read && (p.core ? read.toolchain !== this.project.toolchain : (read.packages[p.name] ?? null) !== p.rev);
406
+ return { file, changed };
407
+ }
408
+ /** A module outside the project as it is now, whatever the graph on show holds (server/outside.ts),
409
+ * and the toolchain now: what a past build's outside source is compared with (HistorySpec
410
+ * decision 24; server/historyapi.ts, `pastOutside`). Null for a saved graph, whose project is not
411
+ * here. */
412
+ outsideNow(module) {
413
+ if (this.saved)
414
+ return null;
415
+ const file = this.outsideSources.find(module);
416
+ return file && { file, toolchain: this.project.toolchain };
417
+ }
375
418
  /** The Project view's pins changed (the agents' API): every page gets the operations, and who
376
419
  * made them. */
377
420
  placesChanged(ops, from, by) {
@@ -470,6 +513,18 @@ export class Live {
470
513
  // background (HistorySpec decision 22): a snapshot backfilled is not looked at again
471
514
  if (this.history)
472
515
  void backfillSources(this.history, this.project, this.dirs.cache, (l) => this.say(l)).catch((e) => this.say(`history: the source texts could not be backfilled: ${e instanceof Error ? e.message : String(e)}`));
516
+ // the packages' revisions of the snapshots read before they were recorded, from their commits
517
+ // (HistorySpec decision 24)
518
+ if (this.history && !this.saved) {
519
+ try {
520
+ const n = backfillPackages(this.history, this.project.root);
521
+ if (n)
522
+ this.say(`history: ${n} snapshot(s) given their packages' revisions, from their commits' lake-manifest.json`);
523
+ }
524
+ catch (e) {
525
+ this.say(`history: the packages' revisions could not be backfilled: ${e instanceof Error ? e.message : String(e)}`);
526
+ }
527
+ }
473
528
  // the review's logs are watched whatever the graph comes from: they may change on disk any time
474
529
  this.timers.push(setInterval(() => this.checkReview(), TICK));
475
530
  this.timers.push(setInterval(() => {
@@ -665,6 +720,10 @@ export class Live {
665
720
  this.base = versionBase(ex.graph);
666
721
  this.nodeIndex = new Map(this.base.names.map((n, i) => [n, i]));
667
722
  this.outside = new Set(ex.graph.externals.map((e) => e.name));
723
+ // the revisions its outside declarations were read at: those of the manifest it was extracted
724
+ // with (server/extract.ts, fingerprint), as it is now; the packages and the toolchain as they are
725
+ this.outsideSources.forget();
726
+ this.outsideRead = this.saved ? null : { packages: this.outsideSources.revisions(), toolchain: this.project.toolchain };
668
727
  // the history first: the renames found against the build before are migrated, so that the
669
728
  // versions served are made under them (HistorySpec.md)
670
729
  const renamed = this.snapshot(ex, missing);
@@ -822,7 +881,7 @@ export class Live {
822
881
  written = found.written;
823
882
  return found;
824
883
  };
825
- const r = this.history.record(ex.graph, { at: buildTime(this.project), fingerprint: ex.fingerprint, commit, toolchain: this.project.toolchain, missing, sources, tool: this.toolVersion });
884
+ const r = this.history.record(ex.graph, { at: buildTime(this.project), fingerprint: ex.fingerprint, commit, toolchain: this.project.toolchain, missing, sources, tool: this.toolVersion, packages: this.outsideSources.revisions() });
826
885
  if (!r.written)
827
886
  return renamed;
828
887
  const s = r.info;