@joe-broadhead/opencode-mem 0.9.12 → 0.11.2

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 (144) hide show
  1. package/CHANGELOG.md +1934 -2
  2. package/README.md +29 -17
  3. package/SECURITY.md +3 -1
  4. package/docs/agent-instructions.md +17 -0
  5. package/docs/agent-protocol.md +8 -8
  6. package/docs/permissions.md +22 -4
  7. package/package.json +7923 -217
  8. package/shared/page-paths.js +44 -0
  9. package/skills/mem.pages/SKILL.md +8 -1
  10. package/skills/mem.usage/SKILL.md +15 -15
  11. package/src/action-grant-keys.js +159 -0
  12. package/src/action-grant.js +439 -0
  13. package/src/actions.js +1690 -0
  14. package/src/backend/records.js +25 -2
  15. package/src/backend/v3.js +76 -22
  16. package/src/call-shapes.js +17 -16
  17. package/src/collector-lock.js +533 -62
  18. package/src/collector-service.js +153 -26
  19. package/src/collector.js +627 -33
  20. package/src/config.js +79 -6
  21. package/src/connect.js +106 -8
  22. package/src/credentials.js +123 -25
  23. package/src/events.js +174 -3
  24. package/src/forget-turn.js +141 -0
  25. package/src/host-refusal.js +78 -0
  26. package/src/index.js +209 -22
  27. package/src/jobs/host.js +557 -0
  28. package/src/ops/codes.js +110 -0
  29. package/src/ops/copy-lineage.js +42 -0
  30. package/src/ops/index.js +28 -0
  31. package/src/ops/space-ops.js +1936 -0
  32. package/src/outlinks.js +103 -0
  33. package/src/p2-reservation.js +151 -0
  34. package/src/permissions.js +30 -0
  35. package/src/plugins/descriptor.js +62 -0
  36. package/src/plugins/discovery.js +318 -0
  37. package/src/plugins/grants.js +178 -0
  38. package/src/plugins/locate.js +319 -0
  39. package/src/plugins/manifest.js +1162 -0
  40. package/src/plugins/source-contract/index.js +34 -0
  41. package/src/plugins/source-contract/policy.js +102 -0
  42. package/src/plugins/source-contract/vendor/PROVENANCE.json +17 -0
  43. package/src/plugins/source-contract/vendor/RELEASE-SHA256SUMS +3 -0
  44. package/src/plugins/source-contract/vendor/RELEASE.json +17 -0
  45. package/src/plugins/source-contract/vendor/SHA256SUMS +41 -0
  46. package/src/plugins/source-contract/vendor/THIRD-PARTY-NOTICES.md +35 -0
  47. package/src/plugins/source-contract/vendor/broker-client.js +93 -0
  48. package/src/plugins/source-contract/vendor/chunks/chunk-3M5PAKSS.js +84 -0
  49. package/src/plugins/source-contract/vendor/chunks/chunk-4ERCA4TK.js +185 -0
  50. package/src/plugins/source-contract/vendor/chunks/chunk-6HDIB2SA.js +183 -0
  51. package/src/plugins/source-contract/vendor/chunks/chunk-ELPJD3ND.js +10 -0
  52. package/src/plugins/source-contract/vendor/chunks/chunk-HLVAKAYG.js +10 -0
  53. package/src/plugins/source-contract/vendor/chunks/chunk-I2RXJJJM.js +81 -0
  54. package/src/plugins/source-contract/vendor/chunks/chunk-KWEWSZ4V.js +505 -0
  55. package/src/plugins/source-contract/vendor/chunks/chunk-KYWBTAF4.js +182 -0
  56. package/src/plugins/source-contract/vendor/chunks/chunk-Q3RQA5J2.js +249 -0
  57. package/src/plugins/source-contract/vendor/chunks/chunk-RRUAIQ4I.js +156 -0
  58. package/src/plugins/source-contract/vendor/chunks/chunk-RYNKNCPP.js +165 -0
  59. package/src/plugins/source-contract/vendor/chunks/chunk-W5SHR7DQ.js +9477 -0
  60. package/src/plugins/source-contract/vendor/chunks/chunk-ZUKF7P6U.js +653 -0
  61. package/src/plugins/source-contract/vendor/cursor.js +26 -0
  62. package/src/plugins/source-contract/vendor/descriptor.js +34 -0
  63. package/src/plugins/source-contract/vendor/events.js +257 -0
  64. package/src/plugins/source-contract/vendor/index.js +10 -0
  65. package/src/plugins/source-contract/vendor/params.js +22 -0
  66. package/src/plugins/source-contract/vendor/permission.js +28 -0
  67. package/src/plugins/source-contract/vendor/pick.js +22 -0
  68. package/src/plugins/source-contract/vendor/read.js +29 -0
  69. package/src/plugins/source-contract/vendor/registry.js +23 -0
  70. package/src/plugins/source-contract/vendor/schema.js +17 -0
  71. package/src/plugins/source-contract/vendor/schemas/output.agenda.json +96 -0
  72. package/src/plugins/source-contract/vendor/schemas/output.countdown.json +28 -0
  73. package/src/plugins/source-contract/vendor/schemas/output.image.json +28 -0
  74. package/src/plugins/source-contract/vendor/schemas/output.inbox.json +84 -0
  75. package/src/plugins/source-contract/vendor/schemas/output.links.json +46 -0
  76. package/src/plugins/source-contract/vendor/schemas/output.list.json +57 -0
  77. package/src/plugins/source-contract/vendor/schemas/output.metric.json +61 -0
  78. package/src/plugins/source-contract/vendor/schemas/output.note.json +14 -0
  79. package/src/plugins/source-contract/vendor/schemas/output.progress.json +50 -0
  80. package/src/plugins/source-contract/vendor/schemas/output.record.json +38 -0
  81. package/src/plugins/source-contract/vendor/schemas/output.table.json +61 -0
  82. package/src/plugins/source-contract/vendor/schemas/output.thread.json +62 -0
  83. package/src/plugins/source-contract/vendor/schemas/sources.json +819 -0
  84. package/src/plugins/source-contract/vendor/schemas.js +19 -0
  85. package/src/plugins/source-contract/vendor/tools-rpc.js +42 -0
  86. package/src/plugins/verify.js +56 -0
  87. package/src/protocol.js +21 -5
  88. package/src/recall.js +104 -5
  89. package/src/records.js +61 -2
  90. package/src/requests.js +216 -0
  91. package/src/runtime.js +89 -7
  92. package/src/setup-time.js +68 -0
  93. package/src/skills.js +230 -8
  94. package/src/source-ids.js +25 -0
  95. package/src/sources/declaration.js +365 -0
  96. package/src/sources/reads.js +772 -0
  97. package/src/sources/rpc.js +151 -0
  98. package/src/sources.js +409 -90
  99. package/src/spaces.js +283 -11
  100. package/src/spool.js +61 -4
  101. package/src/stated.js +10 -5
  102. package/src/storable.js +139 -0
  103. package/src/tools/commitments.js +47 -5
  104. package/src/tools/held-write.js +36 -13
  105. package/src/tools/index.js +27 -0
  106. package/src/tools/ingest.js +27 -2
  107. package/src/tools/memory.js +52 -14
  108. package/src/tools/page.js +95 -9
  109. package/src/tools/recall.js +208 -4
  110. package/src/tools/records-kit.js +2 -1
  111. package/src/tools/share.js +42 -3
  112. package/src/tools/shared.js +44 -4
  113. package/src/tools/space-lifecycle.js +278 -0
  114. package/src/tools/spaces.js +373 -29
  115. package/src/tools/status.js +9 -2
  116. package/src/tools/wiki.js +34 -4
  117. package/src/util.js +110 -6
  118. package/src/vendor/source-contract/README.md +24 -0
  119. package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
  120. package/src/vendor/source-contract/VENDOR.json +81 -0
  121. package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
  122. package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
  123. package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
  124. package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
  125. package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
  126. package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
  127. package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
  128. package/src/vendor/source-contract/cursor.js +26 -0
  129. package/src/vendor/source-contract/events.js +257 -0
  130. package/src/vendor/source-contract/registry.js +23 -0
  131. package/src/vendor/source-contract/tools-rpc.js +42 -0
  132. package/src/views/access-reads.js +256 -0
  133. package/src/views/communities.js +77 -0
  134. package/src/views/contracts.js +1183 -36
  135. package/src/views/inbox-bytes.js +103 -0
  136. package/src/views/overdue.js +1 -1
  137. package/src/views/profile.js +31 -0
  138. package/src/views/receipt.js +81 -0
  139. package/src/views/records-reads.js +869 -37
  140. package/src/views/rpc.js +159 -11
  141. package/src/views/shape.js +8 -5
  142. package/views/memory.html +16 -3
  143. package/views/pages.html +2 -2
  144. package/views/remembered.html +130 -0
@@ -1,5 +1,10 @@
1
1
  import { isRecordsUnavailable } from "../backend/records.js"
2
2
  import {
3
+ AGENT_CHARS,
4
+ BACKLINKS_CONCURRENCY,
5
+ BACKLINKS_MAX,
6
+ COPIES_MAX,
7
+ CURSOR_CHARS,
3
8
  EVIDENCE_MAX,
4
9
  FIELDS_MAX,
5
10
  FOLDERS_MAX,
@@ -13,19 +18,44 @@ import {
13
18
  LINKS_MAX,
14
19
  LIST_MAX,
15
20
  MEMORY_TEXT_CHARS,
21
+ NAME_ALIASES_MAX,
22
+ NAME_KINDS,
23
+ NAMES_MAX,
24
+ NAMES_PAGE,
25
+ NAMES_PAGE_TYPES,
26
+ NAMES_SCAN_PAGES,
27
+ OWNER_ID_CHARS,
28
+ OWNER_NAME_CHARS,
16
29
  PAGES_MAX,
30
+ PROPOSAL_SOURCES_MAX,
17
31
  RECENT_CONCURRENCY,
18
32
  RECENT_MAX_OFFSET,
19
33
  RECENT_PAGE,
20
34
  RECENT_SPACES_MAX,
21
35
  RECORDS_OFF,
22
36
  RECORD_BODY_CHARS,
37
+ REVIEW_DUE_FIELD,
38
+ REVIEWED_FIELD,
23
39
  REVIEW_MAX,
40
+ ROUTINE_OWNER,
24
41
  SOURCE_CHARS,
42
+ SPACE_GRANT_ONLY,
25
43
  STATUS_CHARS,
26
44
  SUMMARY_CHARS,
45
+ TASK_CHARS,
46
+ TERM_GLOSSARIES_MAX,
47
+ TERM_TEXT_CHARS,
48
+ TERM_TYPES,
49
+ TERMS_ANSWER_BYTES,
50
+ TERMS_DEFAULT,
51
+ TERMS_MAX,
27
52
  } from "./contracts.js"
53
+ import { dayIn } from "../records.js"
54
+ import { oneLine } from "../util.js"
28
55
  import { ANSWER_BYTES, SPACE_KINDS, clip, clipText, fitList, idOf, jsonBytes, mapLimit, refuse, sourceLabel, spaceOf } from "./shape.js"
56
+ import { PAGE_TYPES } from "../tools/records-kit.js"
57
+ import { communitiesOf } from "./communities.js"
58
+ import { holdsSpaceRead, readOutlinks } from "../outlinks.js"
29
59
 
30
60
  /**
31
61
  * The views' reads of the records service (docs/design/memory-v1-contracts.md
@@ -130,6 +160,48 @@ export function plainLine(text) {
130
160
  .trim()
131
161
  }
132
162
 
163
+ /** The headings and list leads of a glossary page that are its sections, not terms. */
164
+ const GLOSSARY_SECTIONS = Object.freeze(["log", "notes", "note", "summary", "sources", "timeline", "related", "refs", "references"])
165
+
166
+ /**
167
+ * The terms a glossary page states: each list item's own lead (`- **Term**: …`,
168
+ * `- Term: …` or `- Term — …`), and each `## Term` heading that is not one of
169
+ * the page's sections. A line with no such lead names nothing, so it is no
170
+ * term; the page's own title is its subject, not an entry (Memory's ask 3).
171
+ *
172
+ * @param {unknown} body a page's Markdown
173
+ * @returns {string[]} the terms, deduplicated case-insensitively, each one line
174
+ */
175
+ export function glossaryEntries(body) {
176
+ const seen = new Set()
177
+ const terms = []
178
+ const add = (value) => {
179
+ const text = oneLine(value).replace(/[*_`\[\]]/g, "").trim()
180
+ if (!text || /\.$/.test(text)) return
181
+ const key = text.toLowerCase()
182
+ if (seen.has(key)) return
183
+ seen.add(key)
184
+ terms.push(clipText(text, TERM_TEXT_CHARS, TERM_TEXT_CHARS * 4).text)
185
+ }
186
+ // A section of the page (## Notes, ## Log) holds notes about the glossary, not
187
+ // its entries, so the list items under one are not terms.
188
+ let inSection = false
189
+ for (const line of String(body ?? "").split("\n")) {
190
+ const heading = /^\s*##\s+(.+?)\s*#*\s*$/.exec(line)
191
+ if (heading) {
192
+ const text = heading[1].replace(/[*_`]/g, "").trim()
193
+ inSection = GLOSSARY_SECTIONS.includes(text.toLowerCase())
194
+ if (text && !inSection) add(text)
195
+ continue
196
+ }
197
+ const item = /^\s*[-*]\s+(.*)$/.exec(line)
198
+ if (!item || inSection) continue
199
+ const lead = /^\*\*(.+?)\*\*\s*(?:[:—–-]|$)/.exec(item[1]) ?? /^([^:—–]{1,80}?)\s*[:—–]\s+\S/.exec(item[1])
200
+ if (lead) add(lead[1])
201
+ }
202
+ return terms
203
+ }
204
+
133
205
  /** A journal's summary: the first paragraph under `## Summary`, else the first line of text. */
134
206
  export function summaryOf(body) {
135
207
  const lines = String(body ?? "").split("\n")
@@ -248,6 +320,67 @@ export function memoriesIn(stats) {
248
320
  return 0
249
321
  }
250
322
 
323
+ /**
324
+ * The selection a recent list may be narrowed by (0.9.13): the agent that wrote
325
+ * a memory, and the task key it was written for. Each is checked here, before
326
+ * any space is read, and sent to the records service as its own filter
327
+ * (`author_agent`, `task`: docs/design/records-selection.md). `matches` holds a
328
+ * row that came from a read which takes no filters (a held memory) to the same
329
+ * rule, so a narrowed list never shows what the filter excluded.
330
+ *
331
+ * @param {{ agent?: unknown, task?: unknown }} [input]
332
+ */
333
+ export function recentFilters(input) {
334
+ const read = (name) => {
335
+ if (input?.[name] === undefined) return ""
336
+ const value = typeof input[name] === "string" ? input[name].trim() : ""
337
+ if (!value) refuse(`${name} must be text: the ${name === "agent" ? "agent that wrote a memory" : "task key it was written for"}.`)
338
+ if (value.length > 200) refuse(`${name} takes at most 200 characters.`)
339
+ return value
340
+ }
341
+ const agent = read("agent")
342
+ const task = read("task")
343
+ const agentMatches = (value, wanted) =>
344
+ wanted.endsWith("*") ? String(value ?? "").startsWith(wanted.slice(0, -1)) : String(value ?? "") === wanted
345
+ return {
346
+ body: { ...(agent ? { author_agent: agent } : {}), ...(task ? { task } : {}) },
347
+ matches: (row) => (!agent || agentMatches(row?.agent, agent)) && (!task || row?.task === task),
348
+ }
349
+ }
350
+
351
+ /**
352
+ * Name each node's community, from the answer's own nodes and edges
353
+ * (`communitiesOf`): every node of a graph answer carries one, so a host can
354
+ * colour the graph, and a node cut from the answer is in no community.
355
+ *
356
+ * The grouping is the graph's, not the order the service returned it in: the
357
+ * nodes are put in one canonical order first (by path, then id, then their place
358
+ * in the answer) and the edges follow them, so two reads of the same pages give
359
+ * the same communities whatever order they arrive in.
360
+ *
361
+ * @param {{ nodes: Array<Record<string, unknown>>, edges: Array<{ from: number, to: number }> }} answer
362
+ */
363
+ function addCommunities(answer) {
364
+ const canonical = answer.nodes.map((_, index) => index)
365
+ const key = (index) => String(answer.nodes[index]?.path ?? "")
366
+ const second = (index) => String(answer.nodes[index]?.id ?? "")
367
+ canonical.sort((a, b) => {
368
+ const left = key(a)
369
+ const right = key(b)
370
+ if (left !== right) return left < right ? -1 : 1
371
+ const leftId = second(a)
372
+ const rightId = second(b)
373
+ if (leftId !== rightId) return leftId < rightId ? -1 : 1
374
+ return a - b
375
+ })
376
+ const place = new Map(canonical.map((index, at) => [index, at]))
377
+ const edges = answer.edges
378
+ .map((edge) => ({ from: place.get(edge.from), to: place.get(edge.to) }))
379
+ .sort((a, b) => a.from - b.from || a.to - b.to)
380
+ const groups = communitiesOf(canonical.length, edges)
381
+ for (const [at, index] of canonical.entries()) answer.nodes[index].community = groups[at]
382
+ }
383
+
251
384
  /**
252
385
  * @param {{ runtime: any, personalScopes: () => Promise<Array<{ context: any }>>, available: () => Promise<void>, describe?: (error: unknown) => string }} input
253
386
  * `describe` says a failed read in words (a space that could not be read is
@@ -285,10 +418,16 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
285
418
  if (!found) refuse("That space isn't one of yours.")
286
419
  return {
287
420
  where: { ...(scope ? { scope } : {}), space: spaceId },
288
- space: { id: spaceId, name: clip(found.name || spaceId, 200), kind: SPACE_KINDS.has(found.kind) ? found.kind : "unknown" },
421
+ space: {
422
+ id: spaceId,
423
+ name: clip(found.name || spaceId, 200),
424
+ kind: SPACE_KINDS.has(found.kind) ? found.kind : "unknown",
425
+ grantOnly: SPACE_GRANT_ONLY,
426
+ },
427
+ spaceRead: holdsSpaceRead({ role: found.role, space_kind: found.kind }),
289
428
  }
290
429
  }
291
- return { where: whereOf(first), space: spaceOf(first?.context ?? null) }
430
+ return { where: whereOf(first), space: spaceOf(first?.context ?? null), spaceRead: holdsSpaceRead(first?.context ?? null) }
292
431
  }
293
432
 
294
433
  /** `{ path }` or `{ id }` from a view's input; one of them, checked. */
@@ -314,6 +453,133 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
314
453
  return label ? { source: clip(label, SOURCE_CHARS) } : {}
315
454
  }
316
455
 
456
+ /** The agent that wrote a record, where the record names one. */
457
+ function rowAgent(record) {
458
+ const agent = typeof record?.author?.agent === "string" ? record.author.agent.trim() : ""
459
+ return agent ? { agent: clip(agent, AGENT_CHARS) } : {}
460
+ }
461
+
462
+ /**
463
+ * The people in a space, as the space's own member roster names them
464
+ * (`control.listMembers`, which control scopes to a viewer of the space: the
465
+ * person's own, or one they chose, with the caller's own token). Read once
466
+ * per view call and never kept between calls, so no person's read answers with
467
+ * a roster read under someone else's access. A roster that cannot be read is
468
+ * no members, never a failed read: the page is then named no owner.
469
+ *
470
+ * Keyed by the id a record's `owner` carries, which is not the roster's own. The
471
+ * records service keeps the **upstream** user id the gateway sends it
472
+ * (`x-records-user`, from `context.user.upstream_id`;
473
+ * deploy/auth/records-scope.mjs), while control's roster knows the person by its
474
+ * own `user_id` (`usr_…`). Matching one against the other by equality names
475
+ * nobody, which is why every page carried no owner until the roster learned to
476
+ * carry each member's upstream id too. The member itself is kept so `owner.id`
477
+ * can be control's own `user_id` — the person's id everywhere else (a space's
478
+ * members read, `src/tools/spaces.js`) — and never the core's: an id Jelly
479
+ * cannot relate to a member it can see, and one it should not see at all.
480
+ */
481
+ async function memberNames(spaceId) {
482
+ const members = new Map()
483
+ const id = idOf(spaceId)
484
+ if (!id || id === "local" || !runtime.control || typeof runtime.control.listMembers !== "function") return members
485
+ try {
486
+ const roster = (await runtime.control.listMembers({ userId: runtime.config?.user, spaceId: id })) ?? []
487
+ /** Two people answering to one key would name the wrong one; that key names nobody. */
488
+ const shared = new Set()
489
+ const claim = (key, person) => {
490
+ const seen = members.get(key)
491
+ if (seen && seen.id !== person.id) shared.add(key)
492
+ else members.set(key, person)
493
+ }
494
+ for (const member of roster) {
495
+ const user = idOf(member?.user_id)
496
+ const name = typeof member?.name === "string" ? oneLine(member.name, OWNER_NAME_CHARS).trim() : ""
497
+ if (!user || !name) continue
498
+ // One key, the one that person's records are written under: their
499
+ // upstream id, or their own user id when control has no upstream id for
500
+ // them (the gateway sends that as `x-records-user` instead). Never both,
501
+ // so a record owned by someone else, whose upstream id happens to equal
502
+ // this member's user id, does not name this member.
503
+ claim(idOf(member?.upstream_user_id) || user, { id: user, name })
504
+ }
505
+ for (const key of shared) members.delete(key)
506
+ } catch (error) {
507
+ runtime.log?.debug?.("view: the space's roster was not read", { space: id, error: error?.message })
508
+ }
509
+ return members
510
+ }
511
+
512
+ /**
513
+ * The roster member a record's `owner` names, by the id that record was written
514
+ * under (the roster's key). Null for no owner, for one the roster cannot name,
515
+ * and for the routines' own user (which owns what a routine writes and is no
516
+ * person).
517
+ */
518
+ const memberFor = (members, owner) => {
519
+ const id = idOf(owner)
520
+ return id && id !== ROUTINE_OWNER ? (members.get(id) ?? null) : null
521
+ }
522
+
523
+ /**
524
+ * A page's owning person, where Memory can **name** them: the roster member the
525
+ * record's `owner` names (by the upstream id the record holds), shown as
526
+ * control's own `user_id` and the name the roster gives them. `{}` otherwise,
527
+ * and the field is left out rather than filled with an id: an id is not a name.
528
+ * That is the usual answer for a reader with only a page grant, whom control
529
+ * refuses the space's member list (it needs viewer), and it is always the answer
530
+ * for the routines' own user, which owns what a routine writes and is no person.
531
+ */
532
+ async function ownerOf(record, spaceId) {
533
+ const member = memberFor(await memberNames(spaceId), record?.owner)
534
+ return member ? { owner: { id: clip(member.id, OWNER_ID_CHARS), name: clip(member.name, OWNER_NAME_CHARS) } } : {}
535
+ }
536
+
537
+ /** Today in the person's zone, as a bare date is compared with a page's review day. */
538
+ const todayIn = () => dayIn(runtime.clock?.now?.() ?? Date.now(), runtime.clock?.zone ?? "UTC")
539
+
540
+ /** A day or a date-time, as page metadata may carry one (the records service's own two forms). */
541
+ const DAY_OR_TIME = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2}))?$/
542
+
543
+ /**
544
+ * The review dates a page's own metadata carries (`fields.reviewed`,
545
+ * `fields.review_due`), each a date or date-time; anything else is no date.
546
+ * `reviewDue` is true when the day the page names is today or earlier.
547
+ */
548
+ function reviewDates(fields, today) {
549
+ const of = (name) => (typeof fields?.[name] === "string" && DAY_OR_TIME.test(fields[name].trim()) ? fields[name].trim() : "")
550
+ const reviewed = of(REVIEWED_FIELD)
551
+ const due = of(REVIEW_DUE_FIELD)
552
+ return {
553
+ ...(reviewed ? { reviewed: clip(reviewed, 40) } : {}),
554
+ ...(due ? { reviewDue: due.slice(0, 10) <= today } : {}),
555
+ }
556
+ }
557
+
558
+ /** The task key a record was written for, where the record has one. */
559
+ function rowTask(record) {
560
+ const task = typeof record?.task === "string" ? record.task.trim() : ""
561
+ return task ? { task: clip(task, TASK_CHARS) } : {}
562
+ }
563
+
564
+ /**
565
+ * The copies a record stands for: the ids it supersedes, and the id that
566
+ * superseded it, each only where the record has it. `{}` when it has neither,
567
+ * so a row always says whether it is part of a lineage.
568
+ */
569
+ function rowCopies(record) {
570
+ const supersedes = (Array.isArray(record?.supersedes) ? record.supersedes : []).map(idOf).filter(Boolean).slice(0, COPIES_MAX)
571
+ const supersededBy = idOf(record?.superseded_by)
572
+ return {
573
+ copies: {
574
+ ...(supersedes.length > 0 ? { supersedes } : {}),
575
+ ...(supersededBy ? { supersededBy } : {}),
576
+ },
577
+ }
578
+ }
579
+
580
+ /** A record's version: never negative, 0 when the store gave none. */
581
+ const rowVersion = (record) => ({ version: Math.max(0, Math.floor(Number(record?.version) || 0)) })
582
+
317
583
  /** A memory record as one row of the recent list. */
318
584
  function memoryRow(record, space) {
319
585
  return {
@@ -325,6 +591,10 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
325
591
  status: clip(record.status || "current", STATUS_CHARS),
326
592
  ...rowStatedBy(record.stated_by),
327
593
  ...rowSource(record.source),
594
+ ...rowAgent(record),
595
+ ...rowTask(record),
596
+ ...rowVersion(record),
597
+ ...rowCopies(record),
328
598
  }
329
599
  }
330
600
 
@@ -341,6 +611,10 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
341
611
  status: "proposed",
342
612
  ...rowStatedBy(proposal.stated_by),
343
613
  ...rowSource(proposal.source),
614
+ ...rowAgent(proposal),
615
+ ...rowTask(proposal),
616
+ ...rowVersion(proposal),
617
+ ...rowCopies(proposal),
344
618
  }
345
619
  }
346
620
 
@@ -371,7 +645,12 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
371
645
  seen.add(spaceId)
372
646
  others.push({
373
647
  where: { ...(scope ? { scope } : {}), space: spaceId },
374
- space: { id: spaceId, name: clip(space.name || spaceId, 200), kind: SPACE_KINDS.has(space.kind) ? space.kind : "unknown" },
648
+ space: {
649
+ id: spaceId,
650
+ name: clip(space.name || spaceId, 200),
651
+ kind: SPACE_KINDS.has(space.kind) ? space.kind : "unknown",
652
+ grantOnly: SPACE_GRANT_ONLY,
653
+ },
375
654
  })
376
655
  }
377
656
  const room = Math.max(0, RECENT_SPACES_MAX - 1)
@@ -396,13 +675,14 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
396
675
  if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0 || offset > RECENT_MAX_OFFSET || offset % RECENT_PAGE !== 0) {
397
676
  refuse(`offset is a multiple of ${RECENT_PAGE} from 0 to ${RECENT_MAX_OFFSET}`)
398
677
  }
678
+ const filters = recentFilters(input)
399
679
  const { targets, skipped } = await recentTargets(input)
400
680
  // The newest `offset + 51` of each space hold the newest of them all.
401
681
  const want = offset + RECENT_PAGE + 1
402
682
  const results = await mapLimit(targets, RECENT_CONCURRENCY, async (entry) => {
403
683
  const row = { id: entry.space.id, name: entry.space.name }
404
684
  const [memories, held] = await Promise.allSettled([
405
- records("records.list", { kind: "memory", limit: want }, entry.where),
685
+ records("records.list", { kind: "memory", limit: want, ...filters.body }, entry.where),
406
686
  records("review.list", { limit: HELD_MEMORIES_MAX }, entry.where),
407
687
  ])
408
688
  const rows = []
@@ -410,7 +690,13 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
410
690
  for (const record of memories.value?.records ?? []) if (idOf(record?.id)) rows.push(memoryRow(record, row))
411
691
  }
412
692
  if (held.status === "fulfilled") {
413
- for (const proposal of held.value?.proposals ?? []) if (isHeldMemory(proposal)) rows.push(heldMemoryRow(proposal, row))
693
+ // review.list takes no selection filters, so a held memory is held to
694
+ // them here by the same rule: an agent exactly or by prefix, a task key.
695
+ for (const proposal of held.value?.proposals ?? []) {
696
+ if (!isHeldMemory(proposal)) continue
697
+ const heldRow = heldMemoryRow(proposal, row)
698
+ if (filters.matches(heldRow)) rows.push(heldRow)
699
+ }
414
700
  }
415
701
  const error = [memories, held].find((read) => read.status === "rejected")?.reason
416
702
  if (error) runtime.log?.warn?.(`view memories.recent: a read in space ${entry.space.id} failed`, error)
@@ -433,6 +719,258 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
433
719
  }
434
720
  }
435
721
 
722
+ /** The kinds of term one answer may list, in the order it lists them. */
723
+ const TERM_RANK = Object.freeze(Object.fromEntries(TERM_TYPES.map((type, index) => [type, index])))
724
+
725
+ /**
726
+ * The people and names Memory knows (0.9.13): the titles of the pages that
727
+ * name a person, a project or a team, and the entries a glossary page states
728
+ * (`glossaryEntries`; its own title is the glossary's subject, not a term).
729
+ * Read over the same spaces a recent list is (`recentTargets`): the person's
730
+ * own first, then the shared spaces control lists for them, each read on its
731
+ * own and each failure or skipped space named in `incomplete`.
732
+ *
733
+ * Bounded three ways: the space cap, `max` terms, and the answer's own
734
+ * `TERMS_ANSWER_BYTES`. A glossary's entries need the page's whole body, which
735
+ * a list read clips, so it takes one more read per space for its first
736
+ * `TERM_GLOSSARIES_MAX` glossary pages; past that the answer says `more`.
737
+ */
738
+ async function termsList(input) {
739
+ await available()
740
+ const max = input?.max ?? TERMS_DEFAULT
741
+ if (!Number.isInteger(max) || max < 10 || max > TERMS_MAX) refuse(`max is a whole number from 10 to ${TERMS_MAX}.`)
742
+ const wanted = input?.types ?? [...TERM_TYPES]
743
+ if (!Array.isArray(wanted) || wanted.length === 0 || wanted.length > TERM_TYPES.length) refuse(`types is a list of ${TERM_TYPES.join(", ")}.`)
744
+ for (const type of wanted) if (!TERM_TYPES.includes(type)) refuse(`types is a list of ${TERM_TYPES.join(", ")}.`)
745
+ if (new Set(wanted).size !== wanted.length) refuse("types names each kind once.")
746
+ const { targets, skipped } = await recentTargets(input)
747
+ const results = await mapLimit(targets, RECENT_CONCURRENCY, async (entry) => {
748
+ const space = { id: entry.space.id, name: entry.space.name }
749
+ try {
750
+ const answer = await records("records.list", { kind: "page", limit: 200 }, entry.where)
751
+ const pages = (answer?.records ?? []).filter((record) => idOf(record?.path))
752
+ const terms = []
753
+ const glossaries = []
754
+ for (const record of pages) {
755
+ if (record.type === "glossary") {
756
+ if (wanted.includes("glossary") && glossaries.length < TERM_GLOSSARIES_MAX) glossaries.push(record)
757
+ continue
758
+ }
759
+ if (!wanted.includes(record.type)) continue
760
+ const text = clipText(plainLine(record.title || String(record.path).split("/").pop()), TERM_TEXT_CHARS, 320).text
761
+ if (text) terms.push({ text, kind: record.type, space, path: idOf(record.path) })
762
+ }
763
+ // A list read clips a page's body, so a glossary's entries take one more
764
+ // read of its first `TERM_GLOSSARIES_MAX` glossary pages.
765
+ if (glossaries.length > 0) {
766
+ const bodies = await records("records.get", { paths: glossaries.map((record) => record.path) }, entry.where)
767
+ for (const record of bodies?.records ?? []) {
768
+ const path = idOf(record?.path)
769
+ if (!path) continue
770
+ for (const text of glossaryEntries(record.body)) terms.push({ text, kind: "glossary", space, path })
771
+ }
772
+ }
773
+ return {
774
+ entry,
775
+ terms,
776
+ // Past the cap: a space with more pages than one read gives, or more
777
+ // glossary pages than are read for their entries.
778
+ past: Boolean(answer?.cursor) || pages.filter((record) => record.type === "glossary").length > TERM_GLOSSARIES_MAX,
779
+ }
780
+ } catch (error) {
781
+ runtime.log?.warn?.(`view terms.list: a read in space ${entry.space.id} failed`, error)
782
+ return { entry, error }
783
+ }
784
+ })
785
+ const failed = results.filter((result) => result.error !== undefined)
786
+ if (!results.some((result) => Array.isArray(result.terms))) throw failed[0].error
787
+ const order = new Map(targets.map((entry, index) => [entry.space.id, index]))
788
+ const terms = results
789
+ .flatMap((result) => result.terms ?? [])
790
+ .sort(
791
+ (a, b) =>
792
+ order.get(a.space.id) - order.get(b.space.id) ||
793
+ TERM_RANK[a.kind] - TERM_RANK[b.kind] ||
794
+ a.text.localeCompare(b.text, "en-GB") ||
795
+ a.path.localeCompare(b.path),
796
+ )
797
+ const out = {
798
+ terms: [],
799
+ // A space with more than one read gives is reported as more held.
800
+ more: terms.length > max || results.some((result) => result.past === true),
801
+ incomplete: [
802
+ ...failed.map((result) => ({ id: result.entry.space.id, name: result.entry.space.name, reason: clip(describe(result.error), 200) })),
803
+ ...skipped.map((entry) => ({
804
+ id: entry.space.id,
805
+ name: entry.space.name,
806
+ reason: clip(`Not read: a list covers at most ${RECENT_SPACES_MAX} spaces. Choose this space to see its names.`, 200),
807
+ })),
808
+ ].slice(0, LIST_MAX),
809
+ }
810
+ // The answer's own byte cap comes before `max`: a term's space and path ride with it.
811
+ let fitted = false
812
+ for (const term of terms) {
813
+ if (out.terms.length >= max) break
814
+ out.terms.push(term)
815
+ if (jsonBytes(out) > TERMS_ANSWER_BYTES) {
816
+ out.terms.pop()
817
+ fitted = true
818
+ break
819
+ }
820
+ }
821
+ if (fitted || terms.length > out.terms.length) out.more = true
822
+ return out
823
+ }
824
+
825
+ /**
826
+ * The names of the people, projects and teams Memory knows, and the entries
827
+ * its glossary pages state, for a host's dictation vocabulary (0.10.2; Jelly's
828
+ * asks 3 and 6). Read over the same spaces a recent list is
829
+ * (`recentTargets`): the person's own first, then the shared spaces control
830
+ * lists for them, each read on its own and each failure or skipped space named
831
+ * in `incomplete`. No space id, no path and no count is returned: a caller
832
+ * gets what it would say, and nothing about where the page lives.
833
+ *
834
+ * **Every page of a kind, not the newest few.** Each list read asks the service
835
+ * for `NAMES_PAGE_TYPES` only (`person`, `project`, `team`, `glossary`), so a
836
+ * space with thousands of newer journals and topics still offers its people,
837
+ * and follows the cursor for up to `NAMES_SCAN_PAGES` pages. A space with more
838
+ * than that says `more` rather than looking complete.
839
+ *
840
+ * **Order is deterministic: the most referenced name first, then by name.** A
841
+ * name is referenced by the pages of the same read that link to it (`links`,
842
+ * which a list row already carries); a glossary entry takes its glossary
843
+ * page's count. Only pages the caller may read are in the read, so a link from
844
+ * a page outside a grant is never counted. A name two spaces both know is one
845
+ * entry, its aliases together, so the same memory answers the same way every
846
+ * call.
847
+ *
848
+ * Bounded: at most `NAMES_SCAN_PAGES` reads of `NAMES_PAGE` rows per space, at
849
+ * most `NAMES_MAX` names, and no more than `TERM_GLOSSARIES_MAX` glossary
850
+ * bodies read per space (as `terms.list` does).
851
+ */
852
+ async function namesKnown(input) {
853
+ await available()
854
+ if (input && Object.keys(input).length > 0) refuse("names.known takes no options.")
855
+ const { targets, skipped } = await recentTargets({})
856
+ const results = await mapLimit(targets, RECENT_CONCURRENCY, async (entry) => {
857
+ try {
858
+ const pages = []
859
+ let cursor = null
860
+ let cut = false
861
+ for (let scan = 0; scan < NAMES_SCAN_PAGES; scan += 1) {
862
+ const answer = await records(
863
+ "records.list",
864
+ { kind: "page", type: [...NAMES_PAGE_TYPES], limit: NAMES_PAGE, ...(cursor ? { cursor } : {}) },
865
+ entry.where,
866
+ )
867
+ pages.push(...(answer?.records ?? []).filter((record) => idOf(record?.path)))
868
+ cursor = typeof answer?.cursor === "string" && answer.cursor ? answer.cursor : null
869
+ if (!cursor) break
870
+ }
871
+ // A cursor still to follow is a space with more pages than one scan reads.
872
+ cut = Boolean(cursor)
873
+ const glossaries = pages.filter((record) => record.type === "glossary")
874
+ const read = glossaries.slice(0, TERM_GLOSSARIES_MAX)
875
+ let bodies = []
876
+ if (read.length > 0) {
877
+ const answer = await records("records.get", { paths: read.map((record) => record.path) }, entry.where)
878
+ bodies = answer?.records ?? []
879
+ }
880
+ return { entry, pages, glossaries: read, bodies, cut, past: glossaries.length > read.length }
881
+ } catch (error) {
882
+ runtime.log?.warn?.(`view names.known: a read in space ${entry.space.id} failed`, error)
883
+ return { entry, error }
884
+ }
885
+ })
886
+ const failed = results.filter((result) => result.error !== undefined)
887
+ if (!results.some((result) => Array.isArray(result.pages))) throw failed[0].error
888
+ // A glossary page's own title is its subject, not a name: only its entries are.
889
+ const kindOf = Object.freeze({ person: "person", project: "project", team: "team" })
890
+ const names = []
891
+ for (const result of results) {
892
+ if (!result.pages) continue
893
+ // How many pages of this space link to each page: a name's references.
894
+ const references = new Map()
895
+ for (const record of result.pages) {
896
+ for (const link of Array.isArray(record?.links) ? record.links : []) {
897
+ const target = String(link ?? "").trim()
898
+ if (!target) continue
899
+ references.set(target, (references.get(target) ?? 0) + 1)
900
+ }
901
+ }
902
+ const refsOf = (record) => Math.max(0, references.get(record.path) ?? 0) + Math.max(0, references.get(idOf(record.id)) ?? 0)
903
+ for (const record of result.pages) {
904
+ const kind = kindOf[record.type]
905
+ if (!kind) continue
906
+ const name = clipText(plainLine(record.title || String(record.path).split("/").pop()), TERM_TEXT_CHARS, 320).text
907
+ if (name) names.push({ name, kind, refs: refsOf(record), space: result.entry.space.id, path: idOf(record.path), aliases: aliasesOf(record, name) })
908
+ }
909
+ // A glossary page's own title is not a name; its entries are, under the page's own count.
910
+ for (const record of result.bodies) {
911
+ const page = result.glossaries.find((glossary) => glossary.path === record?.path)
912
+ const refs = page ? refsOf(page) : 0
913
+ for (const name of glossaryEntries(record?.body)) {
914
+ names.push({ name, kind: "term", refs, space: result.entry.space.id, path: idOf(record?.path), aliases: [] })
915
+ }
916
+ }
917
+ }
918
+ const rank = new Map(NAME_KINDS.map((kind, index) => [kind, index]))
919
+ names.sort(
920
+ (a, b) =>
921
+ b.refs - a.refs ||
922
+ a.name.localeCompare(b.name, "en-GB") ||
923
+ rank.get(a.kind) - rank.get(b.kind) ||
924
+ a.path.localeCompare(b.path) ||
925
+ a.space.localeCompare(b.space),
926
+ )
927
+ // One entry per name: the most referenced one says it, and the aliases of
928
+ // the others join it.
929
+ const merged = new Map()
930
+ for (const name of names) {
931
+ const key = name.name.toLocaleLowerCase("en-GB")
932
+ const kept = merged.get(key)
933
+ if (!kept) {
934
+ merged.set(key, { name: name.name, kind: name.kind, aliases: name.aliases })
935
+ continue
936
+ }
937
+ kept.aliases = [...new Set([...kept.aliases, ...name.aliases])]
938
+ .sort((a, b) => a.localeCompare(b, "en-GB"))
939
+ .slice(0, NAME_ALIASES_MAX)
940
+ }
941
+ const kept = [...merged.values()]
942
+ const out = {
943
+ names: kept.slice(0, NAMES_MAX).map(({ name, kind, aliases }) => ({ name, kind, ...(aliases.length > 0 ? { aliases } : {}) })),
944
+ // A space past the scan, a glossary past its bodies, or more names than one answer holds.
945
+ more: kept.length > NAMES_MAX || results.some((result) => result.cut === true || result.past === true),
946
+ incomplete: [
947
+ ...failed.map((result) => ({ id: result.entry.space.id, name: result.entry.space.name, reason: clip(describe(result.error), 200) })),
948
+ ...skipped.map((entry) => ({
949
+ id: entry.space.id,
950
+ name: entry.space.name,
951
+ reason: clip(`Not read: a list covers at most ${RECENT_SPACES_MAX} spaces. Choose this space to see its names.`, 200),
952
+ })),
953
+ ].slice(0, LIST_MAX),
954
+ }
955
+ return out
956
+ }
957
+
958
+ /** A page's own other names (`fields.aliases`), one line each, sorted, never the name itself. */
959
+ function aliasesOf(record, name) {
960
+ const raw = Array.isArray(record?.fields?.aliases) ? record.fields.aliases : []
961
+ const seen = new Set([name.toLocaleLowerCase("en-GB")])
962
+ const aliases = []
963
+ for (const value of raw) {
964
+ if (typeof value !== "string") continue
965
+ const alias = clipText(plainLine(value), TERM_TEXT_CHARS, 320).text
966
+ const key = alias.toLocaleLowerCase("en-GB")
967
+ if (!alias || seen.has(key)) continue
968
+ seen.add(key)
969
+ aliases.push(alias)
970
+ }
971
+ return aliases.sort((a, b) => a.localeCompare(b, "en-GB")).slice(0, NAME_ALIASES_MAX)
972
+ }
973
+
436
974
  /**
437
975
  * How many memories the personal space keeps (`entry` is the first of
438
976
  * `personalScopes()`), for the overview: `{ memories,
@@ -520,51 +1058,223 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
520
1058
  return out
521
1059
  }
522
1060
 
1061
+ /** The payload's kind when it would make a record: a create or an opening (#55). */
1062
+ function payloadOf(fields) {
1063
+ const payload = fields?.payload && typeof fields.payload === "object" ? fields.payload : null
1064
+ if (!payload) return undefined
1065
+ const kind = ["memory", "page", "commitment"].find((name) => name === payload.kind)
1066
+ if (!kind) return undefined
1067
+ return { kind, ...(typeof payload.type === "string" && payload.type ? { type: clip(payload.type, 40) } : {}) }
1068
+ }
1069
+
523
1070
  function proposalItem(proposal) {
524
1071
  const fields = proposal?.fields && typeof proposal.fields === "object" ? proposal.fields : {}
525
1072
  const stated = STATED_BY.has(proposal?.stated_by) ? proposal.stated_by : "unknown"
1073
+ // A meeting proposal's citation keeps the moment and the transcript file
1074
+ // (#62), so a host can say when it was said and which recording it came from.
526
1075
  const evidence = (Array.isArray(fields.evidence) ? fields.evidence : [])
527
1076
  .map((item) => {
528
1077
  const kind = ["event", "turn", "record"].find((name) => typeof item?.[name] === "string")
529
1078
  const ref = kind ? idOf(item[kind]) : ""
530
- return kind && ref ? { kind, ref, quote: clip(item.quote ?? "", 300) } : null
1079
+ if (!kind || !ref) return null
1080
+ return {
1081
+ kind,
1082
+ ref,
1083
+ quote: clip(item.quote ?? "", 300),
1084
+ ...(typeof item.at === "string" && item.at ? { at: clip(item.at, 20) } : {}),
1085
+ ...(typeof item.file === "string" && item.file ? { file: clip(item.file, 200) } : {}),
1086
+ }
531
1087
  })
532
1088
  .filter(Boolean)
533
1089
  .slice(0, EVIDENCE_MAX)
1090
+ const payload = payloadOf(fields)
1091
+ const held = proposal?.type === "team_write"
1092
+ const own = held ? heldSpace(fields) : undefined
534
1093
  return {
535
1094
  id: idOf(proposal.id),
536
1095
  status: clip(proposal.status || "proposed", STATUS_CHARS),
537
1096
  action: clip(fields.action || proposal.type || "", 40),
538
1097
  title: clip(proposal.title ?? "", 200),
539
1098
  target: clip(fields.target_path || fields.target_id || "", 200),
1099
+ /** The wiki and the folder a page proposal would write to (#63, #76). */
1100
+ ...(wikiOf(fields) ? { wiki: wikiOf(fields) } : {}),
1101
+ ...(parentOf(fields.target_path) ? { parent: parentOf(fields.target_path) } : {}),
540
1102
  reason: clip(fields.reason ?? "", 300),
541
1103
  stated_by: stated,
542
1104
  ...rowSource(proposal.source),
1105
+ /** The session and turn that made it, where the record names them (#58 F4). */
1106
+ ...rowRef(proposal, "session"),
1107
+ ...rowRef(proposal, "turn"),
1108
+ /** Whether Memory holds this write for the person to approve, rather than proposing a record. */
1109
+ held,
1110
+ ...(own ? { space: own } : {}),
1111
+ ...meetingOf(fields),
543
1112
  external: stated === "external",
544
1113
  evidence,
1114
+ sources: proposalSources(proposal, evidence),
545
1115
  proposed: clipText(proposedText(proposal), 600, 1800).text,
546
1116
  expires: clip(fields.expires ?? "", 40),
547
1117
  created: clip(proposal.created ?? "", 40),
1118
+ ...(payload ? { payload } : {}),
548
1119
  }
549
1120
  }
550
1121
 
551
- async function reviewList(input) {
1122
+ /** The wiki a proposal names, where the record carries one the schema takes. */
1123
+ function wikiOf(fields) {
1124
+ const wiki = idOf(fields?.wiki)
1125
+ return wiki ? clip(wiki, 128) : ""
1126
+ }
1127
+
1128
+ /** The folder a proposal's path sits in (`projects/harbour` → `projects/`), or "". */
1129
+ function parentOf(path) {
1130
+ const text = typeof path === "string" ? path.trim() : ""
1131
+ const at = text.lastIndexOf("/")
1132
+ return at > 0 ? clip(text.slice(0, at + 1), 300) : ""
1133
+ }
1134
+
1135
+ /**
1136
+ * Where a proposal's words came from, as rows the review page lists (#76):
1137
+ * the evidence it cites with its quotes, then the record's own source refs
1138
+ * (an event, a turn, a session, a routine) once each. A quote is the record's
1139
+ * own text, so erasing the record takes it with the rest of the row; a ref is
1140
+ * an id, never a person's name. Bounded by `PROPOSAL_SOURCES_MAX`.
1141
+ */
1142
+ function proposalSources(proposal, evidence) {
1143
+ const rows = evidence.map((item) => ({ kind: item.kind, ref: item.ref, ...(item.quote ? { quote: item.quote } : {}) }))
1144
+ const seen = new Set(rows.map((row) => `${row.kind} ${row.ref}`))
1145
+ const source = proposal?.source && typeof proposal.source === "object" ? proposal.source : {}
1146
+ for (const kind of ["event", "turn", "session", "routine"]) {
1147
+ const value = typeof source[kind] === "string" ? source[kind].trim() : ""
1148
+ const ref = idOf(value) ? clip(value, 200) : ""
1149
+ if (!ref || seen.has(`${kind} ${ref}`)) continue
1150
+ seen.add(`${kind} ${ref}`)
1151
+ rows.push({ kind, ref })
1152
+ }
1153
+ // A `url` row is safe only while a source removal **withdraws** a waiting
1154
+ // proposal that cites a removed event (`feat/source-removals`): its scrub
1155
+ // drops `fields.evidence` quotes, never `record.source`. If a later change
1156
+ // keeps such proposals listed, drop this row (review R3).
1157
+ const url = typeof source.url === "string" ? source.url.trim() : ""
1158
+ if (url && /^https?:\/\/[^\s<>"']{1,290}$/.test(url) && !seen.has(`url ${url}`)) rows.push({ kind: "url", ref: url })
1159
+ return rows.slice(0, PROPOSAL_SOURCES_MAX)
1160
+ }
1161
+
1162
+ /**
1163
+ * The meeting page a proposal was drawn from (#62): the record's id
1164
+ * (`fields.meeting_id`) and its path (`fields.meeting`), which the meeting
1165
+ * engine writes on every proposal it makes. Absent when the proposal came
1166
+ * from something else, so a page never shows a meeting it does not have.
1167
+ */
1168
+ function meetingOf(fields) {
1169
+ const id = idOf(fields?.meeting_id)
1170
+ if (!id) return {}
1171
+ const path = typeof fields?.meeting === "string" ? clip(fields.meeting, 300) : ""
1172
+ return { meeting: { id, ...(path ? { path } : {}) } }
1173
+ }
1174
+
1175
+ /**
1176
+ * The space a held team write would be saved in, which the hold recorded from
1177
+ * control (`fields.space_id`, `fields.space_name`: `src/tools/held-write.js`),
1178
+ * so the person sees where their write would go without another read.
1179
+ */
1180
+ function heldSpace(fields) {
1181
+ const id = idOf(fields?.space_id)
1182
+ if (!id) return undefined
1183
+ return { id, name: clip(fields.space_name || id, 200) }
1184
+ }
1185
+
1186
+ /** A `source.session` or `source.turn` a row names, where it could be one (an id the schema takes). */
1187
+ function rowRef(record, key) {
1188
+ const value = typeof record?.source?.[key] === "string" ? record.source[key].trim() : ""
1189
+ return idOf(value) ? { [key]: clip(value, 200) } : {}
1190
+ }
1191
+
1192
+ /**
1193
+ * A proposal's own type (`create`, `append`, `team_write`, `share`, …): what
1194
+ * the record is, for a host that labels an item by it.
1195
+ */
1196
+ const proposalKind = (proposal) => (typeof proposal?.type === "string" && /^[a-zA-Z][a-zA-Z0-9._-]{0,39}$/.test(proposal.type) ? proposal.type : "")
1197
+
1198
+ /** The session a proposal was made in, where its source names one that could be a session id. */
1199
+ const proposalSession = (proposal) => {
1200
+ const session = typeof proposal?.source?.session === "string" ? proposal.source.session.trim() : ""
1201
+ return idOf(session) ? session : ""
1202
+ }
1203
+
1204
+ /**
1205
+ * The proposals a review reads, each with the item its schema declares and
1206
+ * the two facts only the Inbox shows (0.9.13): its `kind`, and the session it
1207
+ * was made in (a held team write records that at hold time,
1208
+ * `src/tools/held-write.js`), so a host can ask in that session's composer.
1209
+ * `review.list` returns the declared items; the Inbox adds the rest.
1210
+ */
1211
+ async function reviewWith(input) {
552
1212
  await available()
553
1213
  const where = await target(input)
554
1214
  const answer = await records("review.list", { limit: REVIEW_MAX + 1 }, where.where)
555
1215
  const proposals = (answer?.proposals ?? []).filter((proposal) => idOf(proposal?.id))
556
1216
  const out = { space: where.space, items: [], more: false }
557
- const fitted = fitList(out, "items", proposals.slice(0, REVIEW_MAX).map(proposalItem))
1217
+ const fitted = fitList(
1218
+ out,
1219
+ "items",
1220
+ proposals.slice(0, REVIEW_MAX).map((proposal) => ({
1221
+ item: proposalItem(proposal),
1222
+ kind: clip(proposalKind(proposal), 40),
1223
+ session: clip(proposalSession(proposal), 200),
1224
+ })),
1225
+ )
558
1226
  out.more = fitted || proposals.length > REVIEW_MAX
559
1227
  return out
560
1228
  }
561
1229
 
562
- const pageRow = (record) => ({
563
- path: idOf(record.path),
564
- title: clip(record.title || record.path, 200),
565
- type: clip(record.type ?? "", 40),
566
- updated: clip(record.updated ?? "", 40),
567
- })
1230
+ async function reviewList(input) {
1231
+ const { space, items, more } = await reviewWith(input)
1232
+ return { space, items: items.map((entry) => entry.item), more }
1233
+ }
1234
+
1235
+ /**
1236
+ * A listed page. Its owner is named from the space's roster, which the listing
1237
+ * reads once (`memberNames`), so a page of a hundred rows asks control once; a
1238
+ * page whose owner the roster cannot name has no `owner` at all, as in
1239
+ * `pages.read` (an id, or the routines' user, is not a person's name).
1240
+ */
1241
+ const pageRow = (record, members = new Map()) => {
1242
+ const member = memberFor(members, record?.owner)
1243
+ return {
1244
+ path: idOf(record.path),
1245
+ title: clip(record.title || record.path, 200),
1246
+ type: clip(record.type ?? "", 40),
1247
+ updated: clip(record.updated ?? "", 40),
1248
+ ...(member ? { owner: { id: clip(member.id, OWNER_ID_CHARS), name: clip(member.name, OWNER_NAME_CHARS) } } : {}),
1249
+ }
1250
+ }
1251
+
1252
+ /** Two listed pages by title, as a page shows them (the service reads them newest first). */
1253
+ const byTitle = (a, b) => String(a.title ?? "").localeCompare(String(b.title ?? ""), "en-GB")
1254
+
1255
+ /**
1256
+ * How many records link to each listed page (0.9.13), counted by the read
1257
+ * `pages.read` already uses (`records.backlinks`, one per page, asking for
1258
+ * `BACKLINKS_MAX + 1` rows). A page whose count cannot be read keeps its row and says
1259
+ * nothing about backlinks: not read is not zero. The reads are bounded by the
1260
+ * listing's own cap (`PAGES_MAX`) and run a few at a time.
1261
+ */
1262
+ async function withBacklinkCounts(rows, where) {
1263
+ const counts = await mapLimit(rows, BACKLINKS_CONCURRENCY, async (row) => {
1264
+ try {
1265
+ // One more row than shown: the 21st says `backlinksMore` without walking
1266
+ // the whole list (0.9.13 review).
1267
+ const answer = await records("records.backlinks", { path: row.path, limit: BACKLINKS_MAX + 1 }, where)
1268
+ // A page never links to itself in the count (as pages.read leaves it out).
1269
+ const found = (answer?.records ?? []).filter((record) => idOf(record?.id) && record.path !== row.path)
1270
+ return { backlinks: Math.min(found.length, BACKLINKS_MAX), backlinksMore: found.length > BACKLINKS_MAX || answer?.truncated === true }
1271
+ } catch (error) {
1272
+ runtime.log?.debug?.("view pages.list: a backlink count was not read", { path: row.path, error: error?.message })
1273
+ return {}
1274
+ }
1275
+ })
1276
+ return rows.map((row, index) => ({ ...row, ...counts[index] }))
1277
+ }
568
1278
 
569
1279
  async function pagesList(input) {
570
1280
  await available()
@@ -573,24 +1283,61 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
573
1283
  folder = String(input.folder).trim().replace(/\/$/, "")
574
1284
  if (!FOLDER.test(folder)) refuse("That is not a folder.")
575
1285
  }
1286
+ // A page type the vault keeps: the filter is the records service's own, and
1287
+ // an unknown type is refused rather than answered as an empty shelf.
1288
+ let type = ""
1289
+ if (input?.type !== undefined && input.type !== "") {
1290
+ type = typeof input.type === "string" ? input.type.trim() : ""
1291
+ if (!PAGE_TYPES.includes(type)) refuse(`type is one of ${PAGE_TYPES.join(", ")}.`)
1292
+ }
1293
+ // A cursor the records service gave out, passed back unchanged (0.9.14): the
1294
+ // listing pages on instead of starting again (see `cursor` in
1295
+ // src/views/contracts.js for why a folder's read is exactly one page).
1296
+ let cursor = ""
1297
+ if (input?.cursor !== undefined && input.cursor !== "") {
1298
+ cursor = typeof input.cursor === "string" ? input.cursor.trim() : ""
1299
+ if (!cursor || cursor.length > CURSOR_CHARS || !/^[A-Za-z0-9_-]+$/.test(cursor)) refuse("That is not a listing cursor.")
1300
+ if (!folder) refuse("A cursor continues a folder's list: name the folder with it.")
1301
+ }
576
1302
  const where = await target(input)
577
1303
  if (folder) {
578
- const answer = await records("records.list", { kind: "page", path_prefix: `${folder}/`, limit: 200 }, where.where)
579
- const rows = (answer?.records ?? []).filter((record) => idOf(record?.path)).map(pageRow)
580
- rows.sort((a, b) => a.title.localeCompare(b.title, "en-GB"))
1304
+ const read = { kind: "page", path_prefix: `${folder}/`, ...(type ? { type } : {}), ...(cursor ? { cursor } : {}) }
1305
+ const answer = await records("records.list", { ...read, limit: PAGES_MAX }, where.where)
1306
+ const rows = (answer?.records ?? []).filter((record) => idOf(record?.path))
1307
+ const owners = await memberNames(where.space.id)
1308
+ // Kept in the service's own order, newest first, so what a size cut keeps is
1309
+ // a run of rows from the top and its cursor can be asked for exactly.
1310
+ const counted = await withBacklinkCounts(rows.map((record) => pageRow(record, owners)), where.where)
581
1311
  const out = { space: where.space, folder, folders: [], pages: [], more: false }
582
- const fitted = fitList(out, "pages", rows.slice(0, PAGES_MAX))
583
- out.more = fitted || rows.length > PAGES_MAX || Boolean(answer?.cursor)
1312
+ const fitted = fitList(out, "pages", counted)
1313
+ out.more = fitted || Boolean(answer?.cursor)
1314
+ if (!fitted && answer?.cursor) {
1315
+ // Every row read is listed, so the service's own cursor continues after it.
1316
+ out.cursor = clip(answer.cursor, CURSOR_CHARS)
1317
+ } else if (fitted && out.pages.length > 0) {
1318
+ // Cut for size: the rows kept are a run from the top, so one more read for
1319
+ // exactly those asks the service for the cursor that continues after them
1320
+ // (the first read's cursor would skip every row it did not show).
1321
+ try {
1322
+ const again = await records("records.list", { ...read, limit: out.pages.length }, where.where)
1323
+ if (again?.cursor) out.cursor = clip(again.cursor, CURSOR_CHARS)
1324
+ } catch (error) {
1325
+ runtime.log?.debug?.("view pages.list: the cursor for a cut listing was not read", { folder, error: error?.message })
1326
+ }
1327
+ }
1328
+ // Read newest first, shown by title: the order within one page only, since
1329
+ // the cursor walks the service's order, not this one.
1330
+ out.pages.sort(byTitle)
584
1331
  return out
585
1332
  }
586
1333
  // The top: the folders the newest pages are in, and the pages in none (`index`).
587
1334
  const all = []
588
- let cursor
1335
+ let more
589
1336
  for (let read = 0; read < FOLDER_SCAN_PAGES; read += 1) {
590
- const answer = await records("records.list", { kind: "page", limit: 200, ...(cursor ? { cursor } : {}) }, where.where)
1337
+ const answer = await records("records.list", { kind: "page", limit: 200, ...(type ? { type } : {}), ...(more ? { cursor: more } : {}) }, where.where)
591
1338
  all.push(...(answer?.records ?? []))
592
- cursor = answer?.cursor
593
- if (!cursor) break
1339
+ more = answer?.cursor
1340
+ if (!more) break
594
1341
  }
595
1342
  const counts = new Map()
596
1343
  const top = []
@@ -600,17 +1347,19 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
600
1347
  if (path.includes("/")) {
601
1348
  const name = path.split("/")[0]
602
1349
  counts.set(name, (counts.get(name) ?? 0) + 1)
603
- } else top.push(pageRow(record))
1350
+ } else top.push(record)
604
1351
  }
605
1352
  const rank = (name) => (KNOWN_FOLDERS.includes(name) ? KNOWN_FOLDERS.indexOf(name) : KNOWN_FOLDERS.length)
606
1353
  const folders = [...counts.entries()]
607
1354
  .sort(([a], [b]) => rank(a) - rank(b) || a.localeCompare(b))
608
1355
  .slice(0, FOLDERS_MAX)
609
1356
  .map(([name, count]) => ({ name: clip(name, 64), count }))
610
- top.sort((a, b) => (a.path === "index" ? -1 : b.path === "index" ? 1 : a.title.localeCompare(b.title, "en-GB")))
1357
+ top.sort((a, b) => (a.path === "index" ? -1 : b.path === "index" ? 1 : String(a.title ?? a.path).localeCompare(String(b.title ?? b.path), "en-GB")))
611
1358
  const out = { space: where.space, folder: "", folders, pages: [], more: false }
612
- const fitted = fitList(out, "pages", top.slice(0, PAGES_MAX))
613
- out.more = fitted || Boolean(cursor) || top.length > PAGES_MAX
1359
+ const owners = await memberNames(where.space.id)
1360
+ const listed = await withBacklinkCounts(top.slice(0, PAGES_MAX).map((record) => pageRow(record, owners)), where.where)
1361
+ const fitted = fitList(out, "pages", listed)
1362
+ out.more = fitted || Boolean(more) || top.length > PAGES_MAX
614
1363
  return out
615
1364
  }
616
1365
 
@@ -622,16 +1371,17 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
622
1371
  const record = (answer?.records ?? [])[0]
623
1372
  if (!record || !idOf(record.id)) refuse(ref.path ? "That page isn't in this memory." : "That record isn't in this memory.")
624
1373
  const targets = [...new Set((Array.isArray(record.links) ? record.links : []).map((link) => String(link ?? "").trim()).filter(Boolean))].slice(0, LINKS_MAX)
625
- const linkIds = targets.filter((target) => RECORD_ID.test(target))
626
- const linkPaths = targets.filter((target) => !RECORD_ID.test(target) && PAGE_PATH.test(target))
627
- const [linked, back] = await Promise.all([
628
- targets.length > 0
629
- ? records("records.get", { ...(linkIds.length ? { ids: linkIds } : {}), ...(linkPaths.length ? { paths: linkPaths } : {}) }, where.where).catch(() => ({ records: [] }))
630
- : { records: [] },
631
- record.path ? records("records.backlinks", { path: record.path }, where.where).catch(() => ({ records: [] })) : { records: [] },
1374
+ // The links' titles and whether any is knowably missing, from the one rule
1375
+ // the tool's page read uses (`src/outlinks.js`): `missing` is null when the
1376
+ // absence is not knowable to this reader, and then the answer says nothing
1377
+ // about existence. A failed backlinks read fails this read: it is never
1378
+ // shown as a page nothing links to.
1379
+ const [{ records: linked, missing }, back] = await Promise.all([
1380
+ readOutlinks({ links: targets, path: record.path, spaceRead: where.spaceRead, call: (method, body) => records(method, body, where.where) }),
1381
+ record.path ? records("records.backlinks", { path: record.path }, where.where) : { records: [] },
632
1382
  ])
633
1383
  const known = new Map()
634
- for (const found of linked?.records ?? []) {
1384
+ for (const found of linked) {
635
1385
  if (found?.id) known.set(found.id, found)
636
1386
  if (found?.path) known.set(found.path, found)
637
1387
  }
@@ -647,12 +1397,20 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
647
1397
  stated_by: clip(record.stated_by ?? "", 20),
648
1398
  updated: clip(record.updated ?? "", 40),
649
1399
  version: Math.max(0, Math.floor(Number(record.version) || 0)),
1400
+ ...(await ownerOf(record, where.space.id)),
1401
+ ...reviewDates(record.fields, todayIn()),
650
1402
  fields: fieldLines(record.fields),
651
1403
  body: "",
652
1404
  clipped: false,
653
1405
  outlinks: targets.map((target) => {
654
1406
  const found = known.get(target)
655
- return { target: clip(target, 200), title: clip(found?.title || "", 200), exists: Boolean(found) }
1407
+ const row = { target: clip(target, 200), title: clip(found?.title || "", 200) }
1408
+ // `exists` only where it is known: false for a page path this reader can
1409
+ // prove is not there, true for a record it read. Omitted otherwise (a
1410
+ // grant-only reader, a failed lookup, a target past the cap), so the
1411
+ // page never marks a link it cannot answer for.
1412
+ const exists = found ? true : missing?.has(target) ? false : undefined
1413
+ return exists === undefined ? row : { ...row, exists }
656
1414
  }),
657
1415
  backlinks: backlinks.slice(0, LINKS_MAX).map((found) => ({
658
1416
  id: idOf(found.id),
@@ -661,6 +1419,9 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
661
1419
  type: clip(found.type ?? "", 40),
662
1420
  })),
663
1421
  backlinksMore: backlinks.length > LINKS_MAX || back?.truncated === true,
1422
+ // Only the backlinks this reader can see (the store's own filter): the
1423
+ // page says so rather than "nothing links here".
1424
+ ...(where.spaceRead ? {} : { backlinksPartial: true }),
664
1425
  }
665
1426
  const room = Math.max(4_000, ANSWER_BYTES - jsonBytes(out))
666
1427
  const { text, clipped } = clipText(record.body ?? "", RECORD_BODY_CHARS, room)
@@ -700,9 +1461,74 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
700
1461
  }
701
1462
  }
702
1463
 
1464
+ /**
1465
+ * A folder's graph, in one read (#58 F7): every page in the folder and the
1466
+ * links between them, from the listing the Pages view already reads
1467
+ * (`records.list`, whose rows carry their `links`). A link out of the folder is
1468
+ * not drawn: its target's own title is not in this read, and a node named by
1469
+ * half a fact is worse than none. `types` narrows which pages are kept.
1470
+ *
1471
+ * Every node then carries its `community` (`addCommunities`): a clustering of
1472
+ * this answer's own pages by their links, computed on the read and never
1473
+ * stored (Jelly's ask 2).
1474
+ */
1475
+ async function folderGraph(folder, where, max, types) {
1476
+ const answer = await records("records.list", { kind: "page", path_prefix: `${folder}/`, limit: GRAPH_NODES_MAX }, where.where)
1477
+ const rows = (answer?.records ?? []).filter((record) => idOf(record?.id) && idOf(record?.path))
1478
+ const keep = (record) => types.length === 0 || types.includes(clip(record?.type ?? "", 40))
1479
+ const kept = rows.filter((record) => keep(record) && record.path.startsWith(`${folder}/`))
1480
+ kept.sort((a, b) => a.path.localeCompare(b.path))
1481
+ const nodes = []
1482
+ const index = new Map()
1483
+ for (const record of kept) {
1484
+ if (nodes.length >= max) break
1485
+ index.set(record.id, nodes.length)
1486
+ index.set(record.path, nodes.length)
1487
+ nodes.push({
1488
+ id: idOf(record.id),
1489
+ path: clip(record.path, 200),
1490
+ title: clip(record.title || record.path, 80),
1491
+ kind: "page",
1492
+ type: clip(record.type ?? "", 40),
1493
+ dangling: false,
1494
+ })
1495
+ }
1496
+ const edges = []
1497
+ const seen = new Set()
1498
+ let cut = nodes.length < kept.length
1499
+ for (const record of kept) {
1500
+ const from = index.get(record.id)
1501
+ if (from === undefined) continue
1502
+ for (const link of Array.isArray(record.links) ? record.links : []) {
1503
+ const to = index.get(String(link ?? "").trim())
1504
+ if (to === undefined || to === from) continue
1505
+ const key = `${from}>${to}`
1506
+ if (seen.has(key)) continue
1507
+ seen.add(key)
1508
+ if (edges.length >= GRAPH_EDGES_MAX) {
1509
+ cut = true
1510
+ break
1511
+ }
1512
+ edges.push({ from, to, type: "link" })
1513
+ }
1514
+ }
1515
+ const out = { space: where.space, start: 0, nodes, edges: [], truncated: answer?.truncated === true || Boolean(answer?.cursor) || cut }
1516
+ if (fitList(out, "edges", edges)) out.truncated = true
1517
+ addCommunities(out)
1518
+ return out
1519
+ }
1520
+
703
1521
  async function graphLinks(input) {
704
1522
  await available()
705
- const ref = recordRef(input)
1523
+ // A folder is the whole graph in one read (#58 F7); a page is a neighbourhood.
1524
+ let folder = ""
1525
+ if (input?.folder !== undefined && input.folder !== "") {
1526
+ folder = String(input.folder).trim().replace(/\/$/, "")
1527
+ if (!FOLDER.test(folder)) refuse("That is not a folder.")
1528
+ if (input?.path !== undefined || input?.id !== undefined) refuse("A folder's graph is one read: leave out a page.")
1529
+ if ((input?.depth ?? 1) !== 1) refuse("A folder's graph is every page in it and the links between them: depth is 1.")
1530
+ }
1531
+ const ref = folder ? null : recordRef(input)
706
1532
  const depth = input?.depth ?? 1
707
1533
  if (depth !== 1 && depth !== 2) refuse("depth is 1 or 2.")
708
1534
  const max = input?.max ?? 80
@@ -710,6 +1536,7 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
710
1536
  const types = input?.types ?? []
711
1537
  if (!Array.isArray(types) || types.length > 20 || types.some((type) => typeof type !== "string" || !RECORD_TYPE.test(type))) refuse("types are record types such as person or decision.")
712
1538
  const where = await target(input)
1539
+ if (folder) return folderGraph(folder, where, max, types)
713
1540
  const answer = await records(
714
1541
  "records.links",
715
1542
  { ...(ref.path ? { path: ref.path } : { id: ref.id }), depth, max_nodes: max, ...(types.length ? { types } : {}) },
@@ -755,11 +1582,14 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
755
1582
  }
756
1583
  const out = { space: where.space, start, nodes, edges: [], truncated: answer?.truncated === true || cut }
757
1584
  if (fitList(out, "edges", edges)) out.truncated = true
1585
+ addCommunities(out)
758
1586
  return out
759
1587
  }
760
1588
 
761
1589
  return {
762
1590
  memoryCount,
1591
+ /** The review read with each proposal's kind and session, for the Inbox. */
1592
+ reviewWith,
763
1593
  methods: {
764
1594
  "memories.recent": memoriesRecent,
765
1595
  "journal.list": journalList,
@@ -769,6 +1599,8 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
769
1599
  "pages.read": pagesRead,
770
1600
  "pages.history": pagesHistory,
771
1601
  "graph.links": graphLinks,
1602
+ "terms.list": termsList,
1603
+ "names.known": namesKnown,
772
1604
  },
773
1605
  }
774
1606
  }