@joe-broadhead/opencode-mem 0.9.12 → 0.9.14

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.
@@ -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,6 +18,8 @@ import {
13
18
  LINKS_MAX,
14
19
  LIST_MAX,
15
20
  MEMORY_TEXT_CHARS,
21
+ OWNER_ID_CHARS,
22
+ OWNER_NAME_CHARS,
16
23
  PAGES_MAX,
17
24
  RECENT_CONCURRENCY,
18
25
  RECENT_MAX_OFFSET,
@@ -20,12 +27,25 @@ import {
20
27
  RECENT_SPACES_MAX,
21
28
  RECORDS_OFF,
22
29
  RECORD_BODY_CHARS,
30
+ REVIEW_DUE_FIELD,
31
+ REVIEWED_FIELD,
23
32
  REVIEW_MAX,
33
+ ROUTINE_OWNER,
24
34
  SOURCE_CHARS,
25
35
  STATUS_CHARS,
26
36
  SUMMARY_CHARS,
37
+ TASK_CHARS,
38
+ TERM_GLOSSARIES_MAX,
39
+ TERM_TEXT_CHARS,
40
+ TERM_TYPES,
41
+ TERMS_ANSWER_BYTES,
42
+ TERMS_DEFAULT,
43
+ TERMS_MAX,
27
44
  } from "./contracts.js"
45
+ import { dayIn } from "../records.js"
46
+ import { oneLine } from "../util.js"
28
47
  import { ANSWER_BYTES, SPACE_KINDS, clip, clipText, fitList, idOf, jsonBytes, mapLimit, refuse, sourceLabel, spaceOf } from "./shape.js"
48
+ import { PAGE_TYPES } from "../tools/records-kit.js"
29
49
 
30
50
  /**
31
51
  * The views' reads of the records service (docs/design/memory-v1-contracts.md
@@ -130,6 +150,48 @@ export function plainLine(text) {
130
150
  .trim()
131
151
  }
132
152
 
153
+ /** The headings and list leads of a glossary page that are its sections, not terms. */
154
+ const GLOSSARY_SECTIONS = Object.freeze(["log", "notes", "note", "summary", "sources", "timeline", "related", "refs", "references"])
155
+
156
+ /**
157
+ * The terms a glossary page states: each list item's own lead (`- **Term**: …`,
158
+ * `- Term: …` or `- Term — …`), and each `## Term` heading that is not one of
159
+ * the page's sections. A line with no such lead names nothing, so it is no
160
+ * term; the page's own title is its subject, not an entry (Memory's ask 3).
161
+ *
162
+ * @param {unknown} body a page's Markdown
163
+ * @returns {string[]} the terms, deduplicated case-insensitively, each one line
164
+ */
165
+ export function glossaryEntries(body) {
166
+ const seen = new Set()
167
+ const terms = []
168
+ const add = (value) => {
169
+ const text = oneLine(value).replace(/[*_`\[\]]/g, "").trim()
170
+ if (!text || /\.$/.test(text)) return
171
+ const key = text.toLowerCase()
172
+ if (seen.has(key)) return
173
+ seen.add(key)
174
+ terms.push(clipText(text, TERM_TEXT_CHARS, TERM_TEXT_CHARS * 4).text)
175
+ }
176
+ // A section of the page (## Notes, ## Log) holds notes about the glossary, not
177
+ // its entries, so the list items under one are not terms.
178
+ let inSection = false
179
+ for (const line of String(body ?? "").split("\n")) {
180
+ const heading = /^\s*##\s+(.+?)\s*#*\s*$/.exec(line)
181
+ if (heading) {
182
+ const text = heading[1].replace(/[*_`]/g, "").trim()
183
+ inSection = GLOSSARY_SECTIONS.includes(text.toLowerCase())
184
+ if (text && !inSection) add(text)
185
+ continue
186
+ }
187
+ const item = /^\s*[-*]\s+(.*)$/.exec(line)
188
+ if (!item || inSection) continue
189
+ const lead = /^\*\*(.+?)\*\*\s*(?:[:—–-]|$)/.exec(item[1]) ?? /^([^:—–]{1,80}?)\s*[:—–]\s+\S/.exec(item[1])
190
+ if (lead) add(lead[1])
191
+ }
192
+ return terms
193
+ }
194
+
133
195
  /** A journal's summary: the first paragraph under `## Summary`, else the first line of text. */
134
196
  export function summaryOf(body) {
135
197
  const lines = String(body ?? "").split("\n")
@@ -248,6 +310,34 @@ export function memoriesIn(stats) {
248
310
  return 0
249
311
  }
250
312
 
313
+ /**
314
+ * The selection a recent list may be narrowed by (0.9.13): the agent that wrote
315
+ * a memory, and the task key it was written for. Each is checked here, before
316
+ * any space is read, and sent to the records service as its own filter
317
+ * (`author_agent`, `task`: docs/design/records-selection.md). `matches` holds a
318
+ * row that came from a read which takes no filters (a held memory) to the same
319
+ * rule, so a narrowed list never shows what the filter excluded.
320
+ *
321
+ * @param {{ agent?: unknown, task?: unknown }} [input]
322
+ */
323
+ export function recentFilters(input) {
324
+ const read = (name) => {
325
+ if (input?.[name] === undefined) return ""
326
+ const value = typeof input[name] === "string" ? input[name].trim() : ""
327
+ if (!value) refuse(`${name} must be text: the ${name === "agent" ? "agent that wrote a memory" : "task key it was written for"}.`)
328
+ if (value.length > 200) refuse(`${name} takes at most 200 characters.`)
329
+ return value
330
+ }
331
+ const agent = read("agent")
332
+ const task = read("task")
333
+ const agentMatches = (value, wanted) =>
334
+ wanted.endsWith("*") ? String(value ?? "").startsWith(wanted.slice(0, -1)) : String(value ?? "") === wanted
335
+ return {
336
+ body: { ...(agent ? { author_agent: agent } : {}), ...(task ? { task } : {}) },
337
+ matches: (row) => (!agent || agentMatches(row?.agent, agent)) && (!task || row?.task === task),
338
+ }
339
+ }
340
+
251
341
  /**
252
342
  * @param {{ runtime: any, personalScopes: () => Promise<Array<{ context: any }>>, available: () => Promise<void>, describe?: (error: unknown) => string }} input
253
343
  * `describe` says a failed read in words (a space that could not be read is
@@ -314,6 +404,98 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
314
404
  return label ? { source: clip(label, SOURCE_CHARS) } : {}
315
405
  }
316
406
 
407
+ /** The agent that wrote a record, where the record names one. */
408
+ function rowAgent(record) {
409
+ const agent = typeof record?.author?.agent === "string" ? record.author.agent.trim() : ""
410
+ return agent ? { agent: clip(agent, AGENT_CHARS) } : {}
411
+ }
412
+
413
+ /**
414
+ * The people in a space, by user id, as the space's own member roster names
415
+ * them (`control.listMembers`, which control scopes to a viewer of the space:
416
+ * the person's own, or one they chose, with the caller's own token). Read once
417
+ * per view call and never kept between calls, so no person's read answers with
418
+ * a roster read under someone else's access. A roster that cannot be read is
419
+ * no names, never a failed read: the owner is then named by its id.
420
+ */
421
+ async function memberNames(spaceId) {
422
+ const names = new Map()
423
+ const id = idOf(spaceId)
424
+ if (!id || id === "local" || !runtime.control || typeof runtime.control.listMembers !== "function") return names
425
+ try {
426
+ const members = (await runtime.control.listMembers({ userId: runtime.config?.user, spaceId: id })) ?? []
427
+ for (const member of members) {
428
+ const user = idOf(member?.user_id)
429
+ const name = typeof member?.name === "string" ? oneLine(member.name, OWNER_NAME_CHARS).trim() : ""
430
+ if (user && name) names.set(user, name)
431
+ }
432
+ } catch (error) {
433
+ runtime.log?.debug?.("view: the space's roster was not read", { space: id, error: error?.message })
434
+ }
435
+ return names
436
+ }
437
+
438
+ /**
439
+ * A page's owning person, where Memory can **name** them: the user id the
440
+ * record holds, and the name the space's roster gives it. `{}` otherwise, and
441
+ * the field is left out rather than filled with an id: an id is not a name.
442
+ * That is the usual answer for a reader with only a page grant, whom control
443
+ * refuses the space's member list (it needs viewer), and it is always the answer
444
+ * for the routines' own user, which owns what a routine writes and is no person.
445
+ */
446
+ async function ownerOf(record, spaceId) {
447
+ const id = idOf(record?.owner)
448
+ if (!id || id === ROUTINE_OWNER) return {}
449
+ const name = (await memberNames(spaceId)).get(id)
450
+ return name ? { owner: { id: clip(id, OWNER_ID_CHARS), name: clip(name, OWNER_NAME_CHARS) } } : {}
451
+ }
452
+
453
+ /** Today in the person's zone, as a bare date is compared with a page's review day. */
454
+ const todayIn = () => dayIn(runtime.clock?.now?.() ?? Date.now(), runtime.clock?.zone ?? "UTC")
455
+
456
+ /** A day or a date-time, as page metadata may carry one (the records service's own two forms). */
457
+ const DAY_OR_TIME = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2}))?$/
458
+
459
+ /**
460
+ * The review dates a page's own metadata carries (`fields.reviewed`,
461
+ * `fields.review_due`), each a date or date-time; anything else is no date.
462
+ * `reviewDue` is true when the day the page names is today or earlier.
463
+ */
464
+ function reviewDates(fields, today) {
465
+ const of = (name) => (typeof fields?.[name] === "string" && DAY_OR_TIME.test(fields[name].trim()) ? fields[name].trim() : "")
466
+ const reviewed = of(REVIEWED_FIELD)
467
+ const due = of(REVIEW_DUE_FIELD)
468
+ return {
469
+ ...(reviewed ? { reviewed: clip(reviewed, 40) } : {}),
470
+ ...(due ? { reviewDue: due.slice(0, 10) <= today } : {}),
471
+ }
472
+ }
473
+
474
+ /** The task key a record was written for, where the record has one. */
475
+ function rowTask(record) {
476
+ const task = typeof record?.task === "string" ? record.task.trim() : ""
477
+ return task ? { task: clip(task, TASK_CHARS) } : {}
478
+ }
479
+
480
+ /**
481
+ * The copies a record stands for: the ids it supersedes, and the id that
482
+ * superseded it, each only where the record has it. `{}` when it has neither,
483
+ * so a row always says whether it is part of a lineage.
484
+ */
485
+ function rowCopies(record) {
486
+ const supersedes = (Array.isArray(record?.supersedes) ? record.supersedes : []).map(idOf).filter(Boolean).slice(0, COPIES_MAX)
487
+ const supersededBy = idOf(record?.superseded_by)
488
+ return {
489
+ copies: {
490
+ ...(supersedes.length > 0 ? { supersedes } : {}),
491
+ ...(supersededBy ? { supersededBy } : {}),
492
+ },
493
+ }
494
+ }
495
+
496
+ /** A record's version: never negative, 0 when the store gave none. */
497
+ const rowVersion = (record) => ({ version: Math.max(0, Math.floor(Number(record?.version) || 0)) })
498
+
317
499
  /** A memory record as one row of the recent list. */
318
500
  function memoryRow(record, space) {
319
501
  return {
@@ -325,6 +507,10 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
325
507
  status: clip(record.status || "current", STATUS_CHARS),
326
508
  ...rowStatedBy(record.stated_by),
327
509
  ...rowSource(record.source),
510
+ ...rowAgent(record),
511
+ ...rowTask(record),
512
+ ...rowVersion(record),
513
+ ...rowCopies(record),
328
514
  }
329
515
  }
330
516
 
@@ -341,6 +527,10 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
341
527
  status: "proposed",
342
528
  ...rowStatedBy(proposal.stated_by),
343
529
  ...rowSource(proposal.source),
530
+ ...rowAgent(proposal),
531
+ ...rowTask(proposal),
532
+ ...rowVersion(proposal),
533
+ ...rowCopies(proposal),
344
534
  }
345
535
  }
346
536
 
@@ -396,13 +586,14 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
396
586
  if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0 || offset > RECENT_MAX_OFFSET || offset % RECENT_PAGE !== 0) {
397
587
  refuse(`offset is a multiple of ${RECENT_PAGE} from 0 to ${RECENT_MAX_OFFSET}`)
398
588
  }
589
+ const filters = recentFilters(input)
399
590
  const { targets, skipped } = await recentTargets(input)
400
591
  // The newest `offset + 51` of each space hold the newest of them all.
401
592
  const want = offset + RECENT_PAGE + 1
402
593
  const results = await mapLimit(targets, RECENT_CONCURRENCY, async (entry) => {
403
594
  const row = { id: entry.space.id, name: entry.space.name }
404
595
  const [memories, held] = await Promise.allSettled([
405
- records("records.list", { kind: "memory", limit: want }, entry.where),
596
+ records("records.list", { kind: "memory", limit: want, ...filters.body }, entry.where),
406
597
  records("review.list", { limit: HELD_MEMORIES_MAX }, entry.where),
407
598
  ])
408
599
  const rows = []
@@ -410,7 +601,13 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
410
601
  for (const record of memories.value?.records ?? []) if (idOf(record?.id)) rows.push(memoryRow(record, row))
411
602
  }
412
603
  if (held.status === "fulfilled") {
413
- for (const proposal of held.value?.proposals ?? []) if (isHeldMemory(proposal)) rows.push(heldMemoryRow(proposal, row))
604
+ // review.list takes no selection filters, so a held memory is held to
605
+ // them here by the same rule: an agent exactly or by prefix, a task key.
606
+ for (const proposal of held.value?.proposals ?? []) {
607
+ if (!isHeldMemory(proposal)) continue
608
+ const heldRow = heldMemoryRow(proposal, row)
609
+ if (filters.matches(heldRow)) rows.push(heldRow)
610
+ }
414
611
  }
415
612
  const error = [memories, held].find((read) => read.status === "rejected")?.reason
416
613
  if (error) runtime.log?.warn?.(`view memories.recent: a read in space ${entry.space.id} failed`, error)
@@ -433,6 +630,109 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
433
630
  }
434
631
  }
435
632
 
633
+ /** The kinds of term one answer may list, in the order it lists them. */
634
+ const TERM_RANK = Object.freeze(Object.fromEntries(TERM_TYPES.map((type, index) => [type, index])))
635
+
636
+ /**
637
+ * The people and names Memory knows (0.9.13): the titles of the pages that
638
+ * name a person, a project or a team, and the entries a glossary page states
639
+ * (`glossaryEntries`; its own title is the glossary's subject, not a term).
640
+ * Read over the same spaces a recent list is (`recentTargets`): the person's
641
+ * own first, then the shared spaces control lists for them, each read on its
642
+ * own and each failure or skipped space named in `incomplete`.
643
+ *
644
+ * Bounded three ways: the space cap, `max` terms, and the answer's own
645
+ * `TERMS_ANSWER_BYTES`. A glossary's entries need the page's whole body, which
646
+ * a list read clips, so it takes one more read per space for its first
647
+ * `TERM_GLOSSARIES_MAX` glossary pages; past that the answer says `more`.
648
+ */
649
+ async function termsList(input) {
650
+ await available()
651
+ const max = input?.max ?? TERMS_DEFAULT
652
+ if (!Number.isInteger(max) || max < 10 || max > TERMS_MAX) refuse(`max is a whole number from 10 to ${TERMS_MAX}.`)
653
+ const wanted = input?.types ?? [...TERM_TYPES]
654
+ if (!Array.isArray(wanted) || wanted.length === 0 || wanted.length > TERM_TYPES.length) refuse(`types is a list of ${TERM_TYPES.join(", ")}.`)
655
+ for (const type of wanted) if (!TERM_TYPES.includes(type)) refuse(`types is a list of ${TERM_TYPES.join(", ")}.`)
656
+ if (new Set(wanted).size !== wanted.length) refuse("types names each kind once.")
657
+ const { targets, skipped } = await recentTargets(input)
658
+ const results = await mapLimit(targets, RECENT_CONCURRENCY, async (entry) => {
659
+ const space = { id: entry.space.id, name: entry.space.name }
660
+ try {
661
+ const answer = await records("records.list", { kind: "page", limit: 200 }, entry.where)
662
+ const pages = (answer?.records ?? []).filter((record) => idOf(record?.path))
663
+ const terms = []
664
+ const glossaries = []
665
+ for (const record of pages) {
666
+ if (record.type === "glossary") {
667
+ if (wanted.includes("glossary") && glossaries.length < TERM_GLOSSARIES_MAX) glossaries.push(record)
668
+ continue
669
+ }
670
+ if (!wanted.includes(record.type)) continue
671
+ const text = clipText(plainLine(record.title || String(record.path).split("/").pop()), TERM_TEXT_CHARS, 320).text
672
+ if (text) terms.push({ text, kind: record.type, space, path: idOf(record.path) })
673
+ }
674
+ // A list read clips a page's body, so a glossary's entries take one more
675
+ // read of its first `TERM_GLOSSARIES_MAX` glossary pages.
676
+ if (glossaries.length > 0) {
677
+ const bodies = await records("records.get", { paths: glossaries.map((record) => record.path) }, entry.where)
678
+ for (const record of bodies?.records ?? []) {
679
+ const path = idOf(record?.path)
680
+ if (!path) continue
681
+ for (const text of glossaryEntries(record.body)) terms.push({ text, kind: "glossary", space, path })
682
+ }
683
+ }
684
+ return {
685
+ entry,
686
+ terms,
687
+ // Past the cap: a space with more pages than one read gives, or more
688
+ // glossary pages than are read for their entries.
689
+ past: Boolean(answer?.cursor) || pages.filter((record) => record.type === "glossary").length > TERM_GLOSSARIES_MAX,
690
+ }
691
+ } catch (error) {
692
+ runtime.log?.warn?.(`view terms.list: a read in space ${entry.space.id} failed`, error)
693
+ return { entry, error }
694
+ }
695
+ })
696
+ const failed = results.filter((result) => result.error !== undefined)
697
+ if (!results.some((result) => Array.isArray(result.terms))) throw failed[0].error
698
+ const order = new Map(targets.map((entry, index) => [entry.space.id, index]))
699
+ const terms = results
700
+ .flatMap((result) => result.terms ?? [])
701
+ .sort(
702
+ (a, b) =>
703
+ order.get(a.space.id) - order.get(b.space.id) ||
704
+ TERM_RANK[a.kind] - TERM_RANK[b.kind] ||
705
+ a.text.localeCompare(b.text, "en-GB") ||
706
+ a.path.localeCompare(b.path),
707
+ )
708
+ const out = {
709
+ terms: [],
710
+ // A space with more than one read gives is reported as more held.
711
+ more: terms.length > max || results.some((result) => result.past === true),
712
+ incomplete: [
713
+ ...failed.map((result) => ({ id: result.entry.space.id, name: result.entry.space.name, reason: clip(describe(result.error), 200) })),
714
+ ...skipped.map((entry) => ({
715
+ id: entry.space.id,
716
+ name: entry.space.name,
717
+ reason: clip(`Not read: a list covers at most ${RECENT_SPACES_MAX} spaces. Choose this space to see its names.`, 200),
718
+ })),
719
+ ].slice(0, LIST_MAX),
720
+ }
721
+ // The answer's own byte cap comes before `max`: a term's space and path ride with it.
722
+ let fitted = false
723
+ for (const term of terms) {
724
+ if (out.terms.length >= max) break
725
+ out.terms.push(term)
726
+ if (jsonBytes(out) > TERMS_ANSWER_BYTES) {
727
+ out.terms.pop()
728
+ fitted = true
729
+ break
730
+ }
731
+ }
732
+ if (fitted || terms.length > out.terms.length) out.more = true
733
+ return out
734
+ }
735
+
436
736
  /**
437
737
  * How many memories the personal space keeps (`entry` is the first of
438
738
  * `personalScopes()`), for the overview: `{ memories,
@@ -520,6 +820,15 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
520
820
  return out
521
821
  }
522
822
 
823
+ /** The payload's kind when it would make a record: a create or an opening (#55). */
824
+ function payloadOf(fields) {
825
+ const payload = fields?.payload && typeof fields.payload === "object" ? fields.payload : null
826
+ if (!payload) return undefined
827
+ const kind = ["memory", "page", "commitment"].find((name) => name === payload.kind)
828
+ if (!kind) return undefined
829
+ return { kind, ...(typeof payload.type === "string" && payload.type ? { type: clip(payload.type, 40) } : {}) }
830
+ }
831
+
523
832
  function proposalItem(proposal) {
524
833
  const fields = proposal?.fields && typeof proposal.fields === "object" ? proposal.fields : {}
525
834
  const stated = STATED_BY.has(proposal?.stated_by) ? proposal.stated_by : "unknown"
@@ -531,6 +840,9 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
531
840
  })
532
841
  .filter(Boolean)
533
842
  .slice(0, EVIDENCE_MAX)
843
+ const payload = payloadOf(fields)
844
+ const held = proposal?.type === "team_write"
845
+ const own = held ? heldSpace(fields) : undefined
534
846
  return {
535
847
  id: idOf(proposal.id),
536
848
  status: clip(proposal.status || "proposed", STATUS_CHARS),
@@ -540,31 +852,125 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
540
852
  reason: clip(fields.reason ?? "", 300),
541
853
  stated_by: stated,
542
854
  ...rowSource(proposal.source),
855
+ /** The session and turn that made it, where the record names them (#58 F4). */
856
+ ...rowRef(proposal, "session"),
857
+ ...rowRef(proposal, "turn"),
858
+ /** Whether Memory holds this write for the person to approve, rather than proposing a record. */
859
+ held,
860
+ ...(own ? { space: own } : {}),
543
861
  external: stated === "external",
544
862
  evidence,
545
863
  proposed: clipText(proposedText(proposal), 600, 1800).text,
546
864
  expires: clip(fields.expires ?? "", 40),
547
865
  created: clip(proposal.created ?? "", 40),
866
+ ...(payload ? { payload } : {}),
548
867
  }
549
868
  }
550
869
 
551
- async function reviewList(input) {
870
+ /**
871
+ * The space a held team write would be saved in, which the hold recorded from
872
+ * control (`fields.space_id`, `fields.space_name`: `src/tools/held-write.js`),
873
+ * so the person sees where their write would go without another read.
874
+ */
875
+ function heldSpace(fields) {
876
+ const id = idOf(fields?.space_id)
877
+ if (!id) return undefined
878
+ return { id, name: clip(fields.space_name || id, 200) }
879
+ }
880
+
881
+ /** A `source.session` or `source.turn` a row names, where it could be one (an id the schema takes). */
882
+ function rowRef(record, key) {
883
+ const value = typeof record?.source?.[key] === "string" ? record.source[key].trim() : ""
884
+ return idOf(value) ? { [key]: clip(value, 200) } : {}
885
+ }
886
+
887
+ /**
888
+ * A proposal's own type (`create`, `append`, `team_write`, `share`, …): what
889
+ * the record is, for a host that labels an item by it.
890
+ */
891
+ const proposalKind = (proposal) => (typeof proposal?.type === "string" && /^[a-zA-Z][a-zA-Z0-9._-]{0,127}$/.test(proposal.type) ? proposal.type : "")
892
+
893
+ /** The session a proposal was made in, where its source names one that could be a session id. */
894
+ const proposalSession = (proposal) => {
895
+ const session = typeof proposal?.source?.session === "string" ? proposal.source.session.trim() : ""
896
+ return idOf(session) ? session : ""
897
+ }
898
+
899
+ /**
900
+ * The proposals a review reads, each with the item its schema declares and
901
+ * the two facts only the Inbox shows (0.9.13): its `kind`, and the session it
902
+ * was made in (a held team write records that at hold time,
903
+ * `src/tools/held-write.js`), so a host can ask in that session's composer.
904
+ * `review.list` returns the declared items; the Inbox adds the rest.
905
+ */
906
+ async function reviewWith(input) {
552
907
  await available()
553
908
  const where = await target(input)
554
909
  const answer = await records("review.list", { limit: REVIEW_MAX + 1 }, where.where)
555
910
  const proposals = (answer?.proposals ?? []).filter((proposal) => idOf(proposal?.id))
556
911
  const out = { space: where.space, items: [], more: false }
557
- const fitted = fitList(out, "items", proposals.slice(0, REVIEW_MAX).map(proposalItem))
912
+ const fitted = fitList(
913
+ out,
914
+ "items",
915
+ proposals.slice(0, REVIEW_MAX).map((proposal) => ({
916
+ item: proposalItem(proposal),
917
+ kind: clip(proposalKind(proposal), 40),
918
+ session: clip(proposalSession(proposal), 200),
919
+ })),
920
+ )
558
921
  out.more = fitted || proposals.length > REVIEW_MAX
559
922
  return out
560
923
  }
561
924
 
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
- })
925
+ async function reviewList(input) {
926
+ const { space, items, more } = await reviewWith(input)
927
+ return { space, items: items.map((entry) => entry.item), more }
928
+ }
929
+
930
+ /**
931
+ * A listed page. Its owner is named from the space's roster, which the listing
932
+ * reads once (`memberNames`), so a page of a hundred rows asks control once; a
933
+ * page whose owner the roster cannot name has no `owner` at all, as in
934
+ * `pages.read` (an id, or the routines' user, is not a person's name).
935
+ */
936
+ const pageRow = (record, owners = new Map()) => {
937
+ const owner = idOf(record?.owner)
938
+ const name = owner && owner !== ROUTINE_OWNER ? owners.get(owner) : ""
939
+ return {
940
+ path: idOf(record.path),
941
+ title: clip(record.title || record.path, 200),
942
+ type: clip(record.type ?? "", 40),
943
+ updated: clip(record.updated ?? "", 40),
944
+ ...(name ? { owner: { id: clip(owner, OWNER_ID_CHARS), name: clip(name, OWNER_NAME_CHARS) } } : {}),
945
+ }
946
+ }
947
+
948
+ /** Two listed pages by title, as a page shows them (the service reads them newest first). */
949
+ const byTitle = (a, b) => String(a.title ?? "").localeCompare(String(b.title ?? ""), "en-GB")
950
+
951
+ /**
952
+ * How many records link to each listed page (0.9.13), counted by the read
953
+ * `pages.read` already uses (`records.backlinks`, one per page, asking for
954
+ * `BACKLINKS_MAX + 1` rows). A page whose count cannot be read keeps its row and says
955
+ * nothing about backlinks: not read is not zero. The reads are bounded by the
956
+ * listing's own cap (`PAGES_MAX`) and run a few at a time.
957
+ */
958
+ async function withBacklinkCounts(rows, where) {
959
+ const counts = await mapLimit(rows, BACKLINKS_CONCURRENCY, async (row) => {
960
+ try {
961
+ // One more row than shown: the 21st says `backlinksMore` without walking
962
+ // the whole list (0.9.13 review).
963
+ const answer = await records("records.backlinks", { path: row.path, limit: BACKLINKS_MAX + 1 }, where)
964
+ // A page never links to itself in the count (as pages.read leaves it out).
965
+ const found = (answer?.records ?? []).filter((record) => idOf(record?.id) && record.path !== row.path)
966
+ return { backlinks: Math.min(found.length, BACKLINKS_MAX), backlinksMore: found.length > BACKLINKS_MAX || answer?.truncated === true }
967
+ } catch (error) {
968
+ runtime.log?.debug?.("view pages.list: a backlink count was not read", { path: row.path, error: error?.message })
969
+ return {}
970
+ }
971
+ })
972
+ return rows.map((row, index) => ({ ...row, ...counts[index] }))
973
+ }
568
974
 
569
975
  async function pagesList(input) {
570
976
  await available()
@@ -573,24 +979,61 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
573
979
  folder = String(input.folder).trim().replace(/\/$/, "")
574
980
  if (!FOLDER.test(folder)) refuse("That is not a folder.")
575
981
  }
982
+ // A page type the vault keeps: the filter is the records service's own, and
983
+ // an unknown type is refused rather than answered as an empty shelf.
984
+ let type = ""
985
+ if (input?.type !== undefined && input.type !== "") {
986
+ type = typeof input.type === "string" ? input.type.trim() : ""
987
+ if (!PAGE_TYPES.includes(type)) refuse(`type is one of ${PAGE_TYPES.join(", ")}.`)
988
+ }
989
+ // A cursor the records service gave out, passed back unchanged (0.9.14): the
990
+ // listing pages on instead of starting again (see `cursor` in
991
+ // src/views/contracts.js for why a folder's read is exactly one page).
992
+ let cursor = ""
993
+ if (input?.cursor !== undefined && input.cursor !== "") {
994
+ cursor = typeof input.cursor === "string" ? input.cursor.trim() : ""
995
+ if (!cursor || cursor.length > CURSOR_CHARS || !/^[A-Za-z0-9_-]+$/.test(cursor)) refuse("That is not a listing cursor.")
996
+ if (!folder) refuse("A cursor continues a folder's list: name the folder with it.")
997
+ }
576
998
  const where = await target(input)
577
999
  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"))
1000
+ const read = { kind: "page", path_prefix: `${folder}/`, ...(type ? { type } : {}), ...(cursor ? { cursor } : {}) }
1001
+ const answer = await records("records.list", { ...read, limit: PAGES_MAX }, where.where)
1002
+ const rows = (answer?.records ?? []).filter((record) => idOf(record?.path))
1003
+ const owners = await memberNames(where.space.id)
1004
+ // Kept in the service's own order, newest first, so what a size cut keeps is
1005
+ // a run of rows from the top and its cursor can be asked for exactly.
1006
+ const counted = await withBacklinkCounts(rows.map((record) => pageRow(record, owners)), where.where)
581
1007
  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)
1008
+ const fitted = fitList(out, "pages", counted)
1009
+ out.more = fitted || Boolean(answer?.cursor)
1010
+ if (!fitted && answer?.cursor) {
1011
+ // Every row read is listed, so the service's own cursor continues after it.
1012
+ out.cursor = clip(answer.cursor, CURSOR_CHARS)
1013
+ } else if (fitted && out.pages.length > 0) {
1014
+ // Cut for size: the rows kept are a run from the top, so one more read for
1015
+ // exactly those asks the service for the cursor that continues after them
1016
+ // (the first read's cursor would skip every row it did not show).
1017
+ try {
1018
+ const again = await records("records.list", { ...read, limit: out.pages.length }, where.where)
1019
+ if (again?.cursor) out.cursor = clip(again.cursor, CURSOR_CHARS)
1020
+ } catch (error) {
1021
+ runtime.log?.debug?.("view pages.list: the cursor for a cut listing was not read", { folder, error: error?.message })
1022
+ }
1023
+ }
1024
+ // Read newest first, shown by title: the order within one page only, since
1025
+ // the cursor walks the service's order, not this one.
1026
+ out.pages.sort(byTitle)
584
1027
  return out
585
1028
  }
586
1029
  // The top: the folders the newest pages are in, and the pages in none (`index`).
587
1030
  const all = []
588
- let cursor
1031
+ let more
589
1032
  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)
1033
+ const answer = await records("records.list", { kind: "page", limit: 200, ...(type ? { type } : {}), ...(more ? { cursor: more } : {}) }, where.where)
591
1034
  all.push(...(answer?.records ?? []))
592
- cursor = answer?.cursor
593
- if (!cursor) break
1035
+ more = answer?.cursor
1036
+ if (!more) break
594
1037
  }
595
1038
  const counts = new Map()
596
1039
  const top = []
@@ -600,17 +1043,19 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
600
1043
  if (path.includes("/")) {
601
1044
  const name = path.split("/")[0]
602
1045
  counts.set(name, (counts.get(name) ?? 0) + 1)
603
- } else top.push(pageRow(record))
1046
+ } else top.push(record)
604
1047
  }
605
1048
  const rank = (name) => (KNOWN_FOLDERS.includes(name) ? KNOWN_FOLDERS.indexOf(name) : KNOWN_FOLDERS.length)
606
1049
  const folders = [...counts.entries()]
607
1050
  .sort(([a], [b]) => rank(a) - rank(b) || a.localeCompare(b))
608
1051
  .slice(0, FOLDERS_MAX)
609
1052
  .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")))
1053
+ 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
1054
  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
1055
+ const owners = await memberNames(where.space.id)
1056
+ const listed = await withBacklinkCounts(top.slice(0, PAGES_MAX).map((record) => pageRow(record, owners)), where.where)
1057
+ const fitted = fitList(out, "pages", listed)
1058
+ out.more = fitted || Boolean(more) || top.length > PAGES_MAX
614
1059
  return out
615
1060
  }
616
1061
 
@@ -647,6 +1092,8 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
647
1092
  stated_by: clip(record.stated_by ?? "", 20),
648
1093
  updated: clip(record.updated ?? "", 40),
649
1094
  version: Math.max(0, Math.floor(Number(record.version) || 0)),
1095
+ ...(await ownerOf(record, where.space.id)),
1096
+ ...reviewDates(record.fields, todayIn()),
650
1097
  fields: fieldLines(record.fields),
651
1098
  body: "",
652
1099
  clipped: false,
@@ -700,9 +1147,73 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
700
1147
  }
701
1148
  }
702
1149
 
1150
+ /**
1151
+ * A folder's graph, in one read (#58 F7): every page in the folder and the
1152
+ * links between them, from the listing the Pages view already reads
1153
+ * (`records.list`, whose rows carry their `links`). A link out of the folder is
1154
+ * not drawn: its target's own title is not in this read, and a node named by
1155
+ * half a fact is worse than none. `types` narrows which pages are kept.
1156
+ *
1157
+ * Communities are deliberately not named here: a community is a clustering of
1158
+ * the graph, not a property Memory keeps, and a cheap guess would label a
1159
+ * person's pages wrongly (see the issue's F7).
1160
+ */
1161
+ async function folderGraph(folder, where, max, types) {
1162
+ const answer = await records("records.list", { kind: "page", path_prefix: `${folder}/`, limit: GRAPH_NODES_MAX }, where.where)
1163
+ const rows = (answer?.records ?? []).filter((record) => idOf(record?.id) && idOf(record?.path))
1164
+ const keep = (record) => types.length === 0 || types.includes(clip(record?.type ?? "", 40))
1165
+ const kept = rows.filter((record) => keep(record) && record.path.startsWith(`${folder}/`))
1166
+ kept.sort((a, b) => a.path.localeCompare(b.path))
1167
+ const nodes = []
1168
+ const index = new Map()
1169
+ for (const record of kept) {
1170
+ if (nodes.length >= max) break
1171
+ index.set(record.id, nodes.length)
1172
+ index.set(record.path, nodes.length)
1173
+ nodes.push({
1174
+ id: idOf(record.id),
1175
+ path: clip(record.path, 200),
1176
+ title: clip(record.title || record.path, 80),
1177
+ kind: "page",
1178
+ type: clip(record.type ?? "", 40),
1179
+ dangling: false,
1180
+ })
1181
+ }
1182
+ const edges = []
1183
+ const seen = new Set()
1184
+ let cut = nodes.length < kept.length
1185
+ for (const record of kept) {
1186
+ const from = index.get(record.id)
1187
+ if (from === undefined) continue
1188
+ for (const link of Array.isArray(record.links) ? record.links : []) {
1189
+ const to = index.get(String(link ?? "").trim())
1190
+ if (to === undefined || to === from) continue
1191
+ const key = `${from}>${to}`
1192
+ if (seen.has(key)) continue
1193
+ seen.add(key)
1194
+ if (edges.length >= GRAPH_EDGES_MAX) {
1195
+ cut = true
1196
+ break
1197
+ }
1198
+ edges.push({ from, to, type: "link" })
1199
+ }
1200
+ }
1201
+ const out = { space: where.space, start: 0, nodes, edges: [], truncated: answer?.truncated === true || Boolean(answer?.cursor) || cut }
1202
+ if (fitList(out, "edges", edges)) out.truncated = true
1203
+ return out
1204
+ }
1205
+
703
1206
  async function graphLinks(input) {
704
1207
  await available()
705
- const ref = recordRef(input)
1208
+ // A folder is the whole graph in one read (#58 F7); a page is a neighbourhood.
1209
+ let folder = ""
1210
+ if (input?.folder !== undefined && input.folder !== "") {
1211
+ folder = String(input.folder).trim().replace(/\/$/, "")
1212
+ if (!FOLDER.test(folder)) refuse("That is not a folder.")
1213
+ if (input?.path !== undefined || input?.id !== undefined) refuse("A folder's graph is one read: leave out a page.")
1214
+ if ((input?.depth ?? 1) !== 1) refuse("A folder's graph is every page in it and the links between them: depth is 1.")
1215
+ }
1216
+ const ref = folder ? null : recordRef(input)
706
1217
  const depth = input?.depth ?? 1
707
1218
  if (depth !== 1 && depth !== 2) refuse("depth is 1 or 2.")
708
1219
  const max = input?.max ?? 80
@@ -710,6 +1221,7 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
710
1221
  const types = input?.types ?? []
711
1222
  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
1223
  const where = await target(input)
1224
+ if (folder) return folderGraph(folder, where, max, types)
713
1225
  const answer = await records(
714
1226
  "records.links",
715
1227
  { ...(ref.path ? { path: ref.path } : { id: ref.id }), depth, max_nodes: max, ...(types.length ? { types } : {}) },
@@ -760,6 +1272,8 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
760
1272
 
761
1273
  return {
762
1274
  memoryCount,
1275
+ /** The review read with each proposal's kind and session, for the Inbox. */
1276
+ reviewWith,
763
1277
  methods: {
764
1278
  "memories.recent": memoriesRecent,
765
1279
  "journal.list": journalList,
@@ -769,6 +1283,7 @@ export function createRecordsReads({ runtime, personalScopes, available, describ
769
1283
  "pages.read": pagesRead,
770
1284
  "pages.history": pagesHistory,
771
1285
  "graph.links": graphLinks,
1286
+ "terms.list": termsList,
772
1287
  },
773
1288
  }
774
1289
  }