@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
@@ -12,7 +12,9 @@
12
12
  * list under `mem_spaces`, recent memories under `mem_recall`, the wiki under
13
13
  * `mem_wiki`, commitments under `mem_commitments`, and (0.9) journals, pages,
14
14
  * history and the graph under `mem_page`, proposals awaiting review under
15
- * `mem_spaces` (its `review` action). None of them writes: a write starts as a
15
+ * `mem_spaces` (its `review` action). `memory.setup` reads nothing of anyone's:
16
+ * it answers the numbers setup recorded at this start, under `mem_status`,
17
+ * which is the tool that says what Memory is doing on this host. None of them writes: a write starts as a
16
18
  * message the person sends (`open-agent`), and the agent's tool runs under the
17
19
  * person's rules. That includes a review decision: Jelly lets a view call only
18
20
  * read-only methods (its `viewIssues`, and its host route), and a view call
@@ -65,18 +67,145 @@ export const JOURNAL_SOURCES_MAX = 200
65
67
  export const REVIEW_MAX = 20
66
68
  /** Evidence quotes shown per proposal. */
67
69
  export const EVIDENCE_MAX = 3
70
+ /**
71
+ * The provenance rows one proposal's read carries (#76): its evidence, then the
72
+ * record's own source. A proposal comes from a handful of turns and events, so
73
+ * ten holds the ones a review page lists and the rest are cut, not invented.
74
+ */
75
+ export const PROPOSAL_SOURCES_MAX = 10
68
76
  /** Pages one Pages answer lists, and the folders it names. */
69
77
  export const PAGES_MAX = 150
70
78
  export const FOLDERS_MAX = 50
79
+ /**
80
+ * A paged listing's cursor, as an opaque token: the records service's own
81
+ * (`records.list`'s `cursor`, a base64url pair of the last row's update time and
82
+ * id). A folder's listing reads exactly `PAGES_MAX` rows, so the token continues
83
+ * after the last row listed; a listing that had to be cut short for size says
84
+ * `more` without one (`src/views/records-reads.js`).
85
+ */
86
+ export const CURSOR_CHARS = 600
87
+ /**
88
+ * The most backlinks one listed page's count stands for. The count is read
89
+ * bounded, one `records.backlinks` read per page that asks for `BACKLINKS_MAX + 1`
90
+ * rows: a page with more says `backlinksMore`, so a listing never walks a
91
+ * page's whole backlink list (0.9.13 review).
92
+ */
93
+ export const BACKLINKS_MAX = 20
94
+ /** Backlink reads in flight at once, when a listing counts them. */
95
+ export const BACKLINKS_CONCURRENCY = 4
96
+ /**
97
+ * The bytes of a meeting's transcript one `page.save` carries (Jelly's #61),
98
+ * counted as UTF-8 bytes, never characters. The page keeps it in its field
99
+ * `fields.transcript`, where the meeting engine reads it
100
+ * (`records/src/jobs/meetings.js`), and the records service holds a page's
101
+ * whole `fields` to 32 KiB (`LIMITS.fieldsBytes`): the meeting's own fields and
102
+ * its file links ride there too, so the transcript takes half of it. The
103
+ * declared `maxLength` is this figure in **characters** — a JSON Schema cannot
104
+ * say bytes, and a string is never shorter than its byte count — and the
105
+ * operation refuses a transcript over this many bytes with the limit in words,
106
+ * before the store sees it. Nothing is ever stored in part: a transcript that
107
+ * does not fit waits for the Files address and a read in parts (later work).
108
+ */
109
+ export const PAGE_TRANSCRIPT_BYTES = 16 * 1024
110
+ /**
111
+ * Characters of any page's notes one `page.save` carries, the cap every page had
112
+ * before meetings were saved: 58 KiB, the body a host signs for a grant (ADR
113
+ * §4.4). The figure is a ceiling a JSON Schema can state, and what a press may
114
+ * really carry is measured on the whole input before it is saved — a page's
115
+ * notes are not made smaller for the sake of a meeting's transcript.
116
+ */
117
+ export const PAGE_BODY_CHARS = 58 * 1024
71
118
  /** A page's fields, outlinks and backlinks one answer carries. */
72
119
  export const FIELDS_MAX = 24
73
120
  export const LINKS_MAX = 50
74
121
  /** Versions and lineage one history answer lists. */
75
122
  export const HISTORY_MAX = 50
76
123
  export const LINEAGE_MAX = 20
124
+ /**
125
+ * The terms one answer may list (Jelly's ask 3), the most it may ask for, and
126
+ * the characters of one term; the answer itself is held under
127
+ * `TERMS_ANSWER_BYTES`, well inside Jelly's 64 KB cap.
128
+ */
129
+ export const TERMS_MAX = 500
130
+ export const TERMS_DEFAULT = 100
131
+ export const TERM_TEXT_CHARS = 80
132
+ export const TERMS_ANSWER_BYTES = 32_000
133
+ /**
134
+ * The page types a term may come from. `glossary` is a page's entries, not its
135
+ * title; the others are the page's own title (`people/ama` says "Ama Mensah").
136
+ */
137
+ export const TERM_TYPES = Object.freeze(["person", "project", "team", "glossary"])
138
+ /** Glossary pages one space's terms are read from, and their bodies read in one call. */
139
+ export const TERM_GLOSSARIES_MAX = 10
140
+
141
+ /**
142
+ * The names a host's dictation knows (0.10.2; Jelly's asks 3 and 6), the most
143
+ * one answer lists, and the aliases one name carries: `names.known` is a
144
+ * dictation vocabulary, so it is capped at 50 and carries no space, no path and
145
+ * no count, only what a caller would say.
146
+ */
147
+ export const NAMES_MAX = 50
148
+ export const NAME_ALIASES_MAX = 4
149
+ /** The rows one `names.known` list read asks for (the service's own cap), and how many reads one space may take. */
150
+ export const NAMES_PAGE = 200
151
+ export const NAMES_SCAN_PAGES = 5
152
+ /**
153
+ * The page types a name comes from. The read asks the service for exactly these,
154
+ * so a space with thousands of newer journals or topics still offers its people.
155
+ */
156
+ export const NAMES_PAGE_TYPES = Object.freeze(["person", "project", "team", "glossary"])
157
+ /** The kinds of name one answer may carry; a glossary entry is `term`. */
158
+ export const NAME_KINDS = Object.freeze(["person", "project", "team", "term"])
159
+
160
+ /**
161
+ * Whether a write to a space waits for a grant (Jelly's ask 4, its #49 answer 8),
162
+ * so a host can say "this waits for you in the Inbox". **False for now:** Memory
163
+ * holds no write for a grant yet, so every space answers `grantOnly: false`, from
164
+ * this one constant. The day a space's held-write policy exists, the read takes
165
+ * the value from that policy and this becomes the fallback for a server that
166
+ * names none.
167
+ */
168
+ export const SPACE_GRANT_ONLY = false
169
+
77
170
  /** The graph's caps: nodes (the records service's own cap) and edges. */
78
171
  export const GRAPH_NODES_MAX = 200
79
172
  export const GRAPH_EDGES_MAX = 600
173
+ /**
174
+ * A page's owner, as a view names one: control's user id for the person the
175
+ * record's own `owner` names — matched through the space's member roster, which
176
+ * carries each member's upstream (memory) user id beside its own, because a
177
+ * record's owner is the upstream id the records service keeps — and the person's
178
+ * name from that roster (control's `listMembers`, read once per call). `name` is
179
+ * the key Jelly's `readPage` reads (`owner.name`, at most 120 characters) and is
180
+ * the issue's `label`; `id` is control's, the person's id everywhere else, never
181
+ * the upstream one (docs/jelly.md).
182
+ *
183
+ * **A person Memory can name, or no owner at all.** An id is not a name: control's
184
+ * member list needs the viewer role (`control/src/service/spaces.js`), so a reader
185
+ * holding only a page grant is refused it, and Jelly would print `usr_…` where a
186
+ * person's name goes. So `owner` is left out (Jelly reads absent as none) unless
187
+ * the roster names that person, and never for the routines' own user.
188
+ */
189
+ export const OWNER_ID_CHARS = 200
190
+ export const OWNER_NAME_CHARS = 120
191
+ /**
192
+ * The user the routines write as (`records/src/access.js`, `ROUTINE_USER`), which
193
+ * owns every page a routine writes. It is not a person, so a view never shows it
194
+ * as a page's owner.
195
+ */
196
+ export const ROUTINE_OWNER = "routines"
197
+ /**
198
+ * The page fields a page's own metadata may carry a review with, each a date
199
+ * (`YYYY-MM-DD`) or a date-time: `fields.reviewed` (when it was last reviewed)
200
+ * and `fields.review_due` (when it is next due). Memory keeps no review schedule
201
+ * of its own, so a page that names neither says nothing about a review. Anything
202
+ * that is not a date is not one, and the field is left out rather than guessed.
203
+ */
204
+ export const REVIEWED_FIELD = "reviewed"
205
+ export const REVIEW_DUE_FIELD = "review_due"
206
+
207
+ /** Characters of the oldest capture queue entry's time (an ISO instant). */
208
+ export const SPOOL_TIME_CHARS = 40
80
209
 
81
210
  /** Spaces one recent-memories list reads (the person's own first), and how many it reads at once. */
82
211
  export const RECENT_SPACES_MAX = 20
@@ -84,22 +213,94 @@ export const RECENT_CONCURRENCY = 4
84
213
  /** Characters of a status or a where-it-came-from line on a memory row. */
85
214
  export const STATUS_CHARS = 20
86
215
  export const SOURCE_CHARS = 200
216
+ /** Characters of the agent that wrote a memory, and of the task key it was written for. */
217
+ export const AGENT_CHARS = 80
218
+ export const TASK_CHARS = 200
219
+ /** Copies (the ids a memory supersedes) one row carries; the record's own cap is 20. */
220
+ export const COPIES_MAX = 20
87
221
  /** Memories held for review one space adds to the recent list (the newest). */
88
222
  export const HELD_MEMORIES_MAX = 50
89
223
 
90
224
  /** The most items one Inbox read carries: Jelly's own cap (`INBOX_CAP`). */
91
225
  export const INBOX_MAX = 64
226
+ /**
227
+ * The most bytes one Inbox read's answer may carry, held below Jelly's own cap
228
+ * on a plugin RPC answer: `VIEW_DATA_MAX_BYTES`, 65,536 bytes
229
+ * (`protocol/contracts/src/plugin-views.ts` on its master), which its host
230
+ * refuses, leaving the person's last Inbox in place, silently
231
+ * (`backend/host/src/plugin-views/rpc.ts:247`). The margin is 4 KiB, the one the
232
+ * meeting press keeps (`PRESS_BYTES`, `src/ops/space-ops.js`).
233
+ *
234
+ * **A guard for the meeting carry, not a fix for today's read.** Without
235
+ * `inboxItemMeeting`, an answer peaks at 28–33 KB and never reaches this. With
236
+ * it, a full Inbox of proposals whose moments are quoted in CJK comes to about
237
+ * 75–80 KB, and `src/views/inbox-bytes.js` trims that to this.
238
+ */
239
+ export const INBOX_READ_BYTES_MAX = 61_440
240
+ /**
241
+ * Whether an Inbox item carries the session a proposal was made in.
242
+ *
243
+ * **False, and Jelly's to change.** Jelly reads an Inbox item with a strict
244
+ * schema that knows only `key, category, kind?, label, name?, line?,
245
+ * explanation?, action?, at, count?` (`PluginInboxReadItemSchema`,
246
+ * `protocol/contracts/src/plugin-inbox.ts` on its master): a field it does not
247
+ * know makes it refuse the whole Inbox, not just that item. The session is
248
+ * stored on a held write already (`source.session`, `src/tools/held-write.js`)
249
+ * and read here (`reviewWith`), so the day Jelly adds `session?` this becomes
250
+ * true and the field in `inboxOutput` beside it turns on with it.
251
+ *
252
+ * `scripts/check-jelly-master.sh` is the check: it runs the declaration against
253
+ * Jelly's own master and fails while a declared field is one it refuses.
254
+ */
255
+ export const INBOX_ITEM_SESSION = false
256
+ /**
257
+ * Whether an Inbox item carries the `revision` and the `decisions` a decide
258
+ * button needs (Jelly's answer 2 and 6, app#2430). **False, and Jelly's to
259
+ * change:** its Inbox item is a strict schema that knows neither, so a field it
260
+ * does not know makes it refuse the whole Inbox. `npm run check:jelly:master`
261
+ * is the proof they are held back: with this false, no sample item carries them,
262
+ * and Jelly's own reader refuses one that did. The day Jelly widens the item,
263
+ * this becomes true and `inbox.list` sends them.
264
+ */
265
+ export const INBOX_ITEM_ACTIONS = false
266
+ /**
267
+ * Whether an Inbox item carries the meeting a proposal was drawn from — `meeting
268
+ * {id, path}`, and each `evidence` entry's `at` and `file`, exactly as
269
+ * `review.list` carries them (#62) — so the Inbox can say which meeting a Keep
270
+ * row came from and when it was said.
271
+ *
272
+ * **False, and Jelly's to change.** Jelly reads an Inbox item with a strict
273
+ * schema (`PluginInboxReadItemSchema`, `protocol/contracts/src/plugin-inbox.ts`
274
+ * on its master) that knows `key, category, kind?, label, name?, line?,
275
+ * explanation?, action?, revision?, decisions?, at, count?` and nothing else,
276
+ * and its host **leaves out** an item it cannot read rather than showing it
277
+ * (`backend/host/src/plugin-inbox/gather.ts`): carrying these today would make
278
+ * the proposal disappear from the Inbox, not gain a meeting. The fields are
279
+ * derived from the proposal's own `fields.meeting_id`, `fields.meeting` and
280
+ * `fields.evidence` — nothing is stored for this, and the read comes from the
281
+ * same space as `review.list` — and they go on the wire the day Jelly's item
282
+ * takes them, when this becomes true and `inboxOutput` beside it turns on with
283
+ * it.
284
+ *
285
+ * `scripts/check-jelly-master.sh` is the check: it runs the declaration against
286
+ * Jelly's own master and fails while sample items carry a field it refuses.
287
+ */
288
+ export const INBOX_ITEM_MEETING = false
92
289
  /**
93
290
  * Overdue commitments one Inbox read lists, the most overdue first. With the
94
291
  * proposals (`REVIEW_MAX`) the read stays within `INBOX_MAX`.
95
292
  */
96
293
  export const OVERDUE_MAX = INBOX_MAX - REVIEW_MAX
97
294
  /**
98
- * The Jelly notice category an overdue commitment is published under. Jelly's
99
- * own words name `alert` "Security alerts" (reserved for account and device
100
- * security, which breaks through Pause) and `commitment` "Commitments", so an
101
- * overdue reminder is a `commitment`. The one line to change if Jelly asks for
102
- * another.
295
+ * The Jelly notice category an overdue commitment is published under: decided
296
+ * in issue #48, and `commitment`, not the `alert` that issue first proposed.
297
+ * Jelly's own words name `alert` "Security alerts" - reserved for account and
298
+ * device security, which breaks through the person's Pause - and `commitment`
299
+ * "Commitments". An overdue reminder is neither security nor urgent, and the
300
+ * item's own key already says `commitment:<id>`, so the category agrees with
301
+ * what the host routes. Jelly's expectations for the notice (one item per
302
+ * commitment, updated in place, cleared by a new due date) do not depend on
303
+ * the category. The one line to change if Jelly asks for another.
103
304
  */
104
305
  export const OVERDUE_CATEGORY = "commitment"
105
306
  /** The Inbox item's label (the banner's title) and its stable key prefix. */
@@ -145,14 +346,58 @@ const viewInput = (properties = {}, required = []) => ({
145
346
  const empty = viewInput()
146
347
  const id = { type: "string", maxLength: 200 }
147
348
  const line = (max) => ({ type: "string", maxLength: max })
349
+ /** A count: a non-negative whole number, never the rows behind it. */
350
+ const count = (minimum) => ({ type: "integer", minimum })
148
351
  const space = {
149
352
  type: "object",
150
353
  additionalProperties: false,
151
- required: ["id", "name", "kind"],
354
+ required: ["id", "name", "kind", "grantOnly"],
152
355
  properties: {
153
356
  id,
154
357
  name: line(200),
155
358
  kind: { type: "string", enum: ["personal", "shared", "unknown"] },
359
+ /**
360
+ * Whether a write here waits for a grant: `SPACE_GRANT_ONLY` for now (false,
361
+ * since Memory holds no write for a grant), so Jelly's "this waits for you
362
+ * in the Inbox" has a field to read the day a policy lands.
363
+ */
364
+ grantOnly: { type: "boolean" },
365
+ /** How many people the space is shared with, when control answers it: a count, never the rows (jelly #55). */
366
+ members: count(0),
367
+ /** How many wikis the space holds, when control answers it (jelly #55). */
368
+ wikis: count(0),
369
+ },
370
+ }
371
+
372
+ /**
373
+ * `memory.setup`'s answer (jelly #80, D226): the phases of this engine start's
374
+ * setup and their total, on a monotonic clock, and when the start began. Only
375
+ * the numbers recorded once, as setup ended (`src/setup-time.js`): a host reads
376
+ * it for its engine-start telemetry, before anything else is asked.
377
+ *
378
+ * `ms` is the phases' sum, and each `ms` is a duration in milliseconds. `at` is
379
+ * ISO 8601 with milliseconds, the same length as a record's own instants.
380
+ */
381
+ const setupOutput = {
382
+ type: "object",
383
+ additionalProperties: false,
384
+ required: ["ms", "phases", "at"],
385
+ properties: {
386
+ ms: { type: "number", minimum: 0 },
387
+ phases: {
388
+ type: "array",
389
+ maxItems: 32,
390
+ items: {
391
+ type: "object",
392
+ additionalProperties: false,
393
+ required: ["name", "ms"],
394
+ properties: {
395
+ name: line(40),
396
+ ms: { type: "number", minimum: 0 },
397
+ },
398
+ },
399
+ },
400
+ at: line(40),
156
401
  },
157
402
  }
158
403
 
@@ -169,6 +414,8 @@ const overviewOutput = {
169
414
  * "refused" (the credential was turned down), or "unreachable" (anything else: try again).
170
415
  */
171
416
  state: { type: "string", enum: ["unconfigured", "refused", "unreachable"] },
417
+ /** Not connected only: that state's one fixed sentence, at most 60 characters, ending in the next step (jelly #73). */
418
+ tile: line(60),
172
419
  /** Where the bearer comes from: Jelly, a pasted key, the token option, or nothing. */
173
420
  credential: { type: "string", enum: ["jelly", "key", "option", "opencode", "none"] },
174
421
  /** Jelly's refusal code while the plugin falls back to a pasted key. */
@@ -182,6 +429,20 @@ const overviewOutput = {
182
429
  failing_since: line(40),
183
430
  /** Whether the records service answers (memories are records from 0.9); "unavailable" says the page shows `RECORDS_OFF`. */
184
431
  records: { type: "string", enum: ["ok", "unavailable"] },
432
+ /**
433
+ * The engine's own capture queue on this machine, as `mem_status` tells the
434
+ * agent: `depth` is what still waits to be sent (a capture the server has not
435
+ * taken yet), and `oldest` when the oldest of those was queued. Absent when
436
+ * the engine keeps no queue, and on a memory that cannot be used. It is the
437
+ * host engine's queue, not the speaker's, so a host several people share
438
+ * shows their queue together.
439
+ */
440
+ spool: {
441
+ type: "object",
442
+ additionalProperties: false,
443
+ required: ["depth"],
444
+ properties: { depth: { type: "integer", minimum: 0 }, oldest: line(SPOOL_TIME_CHARS) },
445
+ },
185
446
  space,
186
447
  counts: {
187
448
  type: "object",
@@ -208,7 +469,7 @@ const spacesOutput = {
208
469
  items: {
209
470
  type: "object",
210
471
  additionalProperties: false,
211
- required: ["id", "name", "kind", "role"],
472
+ required: ["id", "name", "kind", "grantOnly", "role"],
212
473
  properties: { ...space.properties, role: line(40) },
213
474
  },
214
475
  },
@@ -219,6 +480,10 @@ const recentInput = viewInput({
219
480
  offset: { type: "integer", minimum: 0, maximum: RECENT_MAX_OFFSET, multipleOf: RECENT_PAGE },
220
481
  /** A space the person chose from `spaces.list`; omitted, every space they can read. */
221
482
  space: id,
483
+ /** Only what this agent wrote, as the records service names it; a trailing `*` matches every agent that starts with it. */
484
+ agent: line(200),
485
+ /** Only what was written for this task key ("checkout-v3"). */
486
+ task: line(200),
222
487
  })
223
488
 
224
489
  /** The space a row came from. */
@@ -229,6 +494,9 @@ const rowSpace = {
229
494
  properties: { id, name: line(200) },
230
495
  }
231
496
 
497
+ /** A count, the views' own: never negative. */
498
+ const integer = { type: "integer", minimum: 0 }
499
+
232
500
  const recentOutput = {
233
501
  type: "object",
234
502
  additionalProperties: false,
@@ -255,7 +523,7 @@ const recentOutput = {
255
523
  items: {
256
524
  type: "object",
257
525
  additionalProperties: false,
258
- required: ["id", "text", "type", "at", "space", "status"],
526
+ required: ["id", "text", "type", "at", "space", "status", "version", "copies"],
259
527
  properties: {
260
528
  id,
261
529
  text: line(MEMORY_TEXT_CHARS),
@@ -269,6 +537,21 @@ const recentOutput = {
269
537
  stated_by: { type: "string", enum: ["person", "agent", "inferred", "external"] },
270
538
  /** Where it came from, as "event evt_…", "turn msg-…", "routine daily@v1" and so on, where the record says. */
271
539
  source: line(SOURCE_CHARS),
540
+ /** The agent that wrote it, where the record names one. */
541
+ agent: line(AGENT_CHARS),
542
+ /** The task key it was written for, where the record names one. */
543
+ task: line(TASK_CHARS),
544
+ /** The record's version; 0 when the store gave none. */
545
+ version: integer,
546
+ /** The copies it stands for: the ids it supersedes, and the id that superseded it. Both only where they exist. */
547
+ copies: {
548
+ type: "object",
549
+ additionalProperties: false,
550
+ properties: {
551
+ supersedes: { type: "array", maxItems: COPIES_MAX, items: id },
552
+ supersededBy: id,
553
+ },
554
+ },
272
555
  },
273
556
  },
274
557
  },
@@ -362,7 +645,6 @@ const commitmentsOutput = {
362
645
 
363
646
  /* ---------------------------------------------------------------- records (0.9) */
364
647
 
365
- const integer = { type: "integer", minimum: 0 }
366
648
  const flag = { type: "boolean" }
367
649
  const list = (items, max) => ({ type: "array", maxItems: max, items })
368
650
  const object = (properties, required = Object.keys(properties)) => ({
@@ -373,8 +655,51 @@ const object = (properties, required = Object.keys(properties)) => ({
373
655
  })
374
656
  /** A space the person chose from `spaces.list`; omitted, their personal space. */
375
657
  const spaceInput = { space: id }
658
+ /** A page's owning person in its space: the record's own owner, named by the space's roster; absent when no one can be named. */
659
+ const pageOwner = object({ id: line(OWNER_ID_CHARS), name: line(OWNER_NAME_CHARS) }, ["id", "name"])
376
660
  const period = { type: "string", enum: ["day", "week", "month"] }
377
661
 
662
+ /**
663
+ * The size limits a `page.save` really keeps, said where a host reads them. A
664
+ * JSON Schema counts characters, never bytes, and cannot add a body's bytes to
665
+ * a transcript's, so these numbers are ceilings the host may rely on: the act
666
+ * measures what it is given — a transcript in UTF-8 bytes, a meeting and a
667
+ * page's fields in the JSON the store writes, and the whole press against the
668
+ * grant's cap — and refuses what is too large in words before anything is
669
+ * signed or written, never cutting it.
670
+ */
671
+ export const pageBody = {
672
+ type: "string",
673
+ maxLength: PAGE_BODY_CHARS,
674
+ description:
675
+ "The page's notes: 59392 characters, and a whole press (body, transcript and files) is held to 61440 bytes of JSON.",
676
+ }
677
+ /**
678
+ * A meeting's transcript, as `page.save` takes it: the declared ceiling is the
679
+ * byte cap counted in characters (a JSON Schema counts characters, never
680
+ * bytes), and the operation holds it to `PAGE_TRANSCRIPT_BYTES` UTF-8 bytes. A
681
+ * transcript longer than that is not saved: a Files address on the page
682
+ * (`fields.transcript_file`), read in parts with the person's own rights, is
683
+ * later work.
684
+ */
685
+ export const pageTranscript = {
686
+ type: "string",
687
+ maxLength: PAGE_TRANSCRIPT_BYTES,
688
+ description:
689
+ "The meeting's transcript, held to 16384 UTF-8 bytes. A longer one is refused, never cut: a Files address on the page and a read in parts is later work.",
690
+ }
691
+ /**
692
+ * The same property without its `description`: a view method's schema is read
693
+ * by the pinned engine's RPC, which knows the keywords the views use and none
694
+ * beyond them, so the host-facing note stays on the action's own declaration.
695
+ */
696
+ const withoutNote = ({ description: _note, ...schema }) => schema
697
+ /** The meeting a save names: its id and its times, kept small. */
698
+ export const pageMeeting = {
699
+ type: "object",
700
+ description: "The meeting's id and its times, at most 1024 bytes of JSON.",
701
+ }
702
+
378
703
  const journalListInput = viewInput({ ...spaceInput, period })
379
704
 
380
705
  const journalListOutput = object({
@@ -446,28 +771,106 @@ const reviewListOutput = object({
446
771
  title: line(200),
447
772
  /** The record or page it changes, when it changes one. */
448
773
  target: line(200),
774
+ /**
775
+ * The wiki a new page would land in, where the proposal names one
776
+ * (#63, #76): a space holds several wikis, and a folder path does not
777
+ * say which. Absent when the proposal names none.
778
+ */
779
+ wiki: line(128),
780
+ /** The folder a new page would land in, from the path the proposal names (#63). */
781
+ parent: line(300),
449
782
  reason: line(300),
450
783
  stated_by: { type: "string", enum: ["person", "agent", "inferred", "external", "unknown"] },
451
784
  /** Where it came from, as "event evt_…" or "routine daily@v1", where the record says. */
452
785
  source: line(SOURCE_CHARS),
786
+ /** The session that made it, where the record names one: a held write records its own. */
787
+ session: line(200),
788
+ /** The turn (the assistant message) that made it, where the record names one. */
789
+ turn: line(200),
790
+ /** Whether Memory is holding a write for this person to approve (a `team_write`), not proposing a record. */
791
+ held: flag,
792
+ /**
793
+ * A held write's own target space: where its records would be saved, which
794
+ * is not the space this review was read from. Absent for a proposed record.
795
+ */
796
+ space: rowSpace,
453
797
  /** Whether the words came from someone other than the person: the page labels it. */
454
798
  external: flag,
799
+ /**
800
+ * The meeting page a proposal was drawn from (#62), so a host ties the
801
+ * item to the meeting it came from: the record's id and its path. Absent
802
+ * for a proposal that came from something other than a meeting.
803
+ */
804
+ meeting: object({ id, path: line(300) }, ["id"]),
455
805
  evidence: list(
456
- object({ kind: { type: "string", enum: ["event", "turn", "record"] }, ref: id, quote: line(300) }),
806
+ object(
807
+ {
808
+ kind: { type: "string", enum: ["event", "turn", "record"] },
809
+ ref: id,
810
+ quote: line(300),
811
+ /** The transcript moment the line was said, when it is a meeting proposal (#62). */
812
+ at: line(20),
813
+ /** The transcript file the moment came from, when the page named one. */
814
+ file: line(200),
815
+ },
816
+ ["kind", "ref", "quote"],
817
+ ),
457
818
  EVIDENCE_MAX,
458
819
  ),
820
+ /**
821
+ * Where the proposal's words came from, for the review page's Sources
822
+ * section (#76): the evidence it cites, then the record's own
823
+ * provenance, each row once. A proposal with neither has none.
824
+ */
825
+ sources: list(
826
+ object({ kind: { type: "string", enum: ["event", "turn", "record", "session", "routine", "url"] }, ref: line(300), quote: line(300) }, ["kind", "ref"]),
827
+ PROPOSAL_SOURCES_MAX,
828
+ ),
459
829
  /** The text accepting it would apply; the Edit box starts from it. */
460
830
  proposed: line(600),
461
831
  expires: line(40),
462
832
  created: line(40),
833
+ /** #55: what accepting it would make, when the payload is a record (a share names none). */
834
+ payload: object(
835
+ {
836
+ kind: { type: "string", enum: ["memory", "page", "commitment"] },
837
+ type: line(40),
838
+ },
839
+ ["kind"],
840
+ ),
463
841
  },
464
- ["id", "status", "action", "title", "target", "reason", "stated_by", "external", "evidence", "proposed", "expires", "created"],
842
+ ["id", "status", "action", "title", "target", "reason", "stated_by", "external", "evidence", "sources", "proposed", "expires", "created", "held"],
465
843
  ),
466
844
  REVIEW_MAX,
467
845
  ),
468
846
  more: flag,
469
847
  })
470
848
 
849
+ /**
850
+ * The `meeting` and `evidence` an Inbox item carries when `INBOX_ITEM_MEETING`
851
+ * is true: one source for the shape `inboxOutput` declares the day that flag
852
+ * turns on, so a test can hold a read that carries them to the shape Jelly will
853
+ * read then.
854
+ */
855
+ export const INBOX_MEETING_FIELDS = Object.freeze({
856
+ /** The meeting page a proposal was drawn from (#62), as `review.list` carries it. */
857
+ meeting: object({ id, path: line(300) }, ["id"]),
858
+ /** The moments the proposal cites, as `review.list` carries them. */
859
+ evidence: list(
860
+ object(
861
+ {
862
+ kind: { type: "string", enum: ["event", "turn", "record"] },
863
+ ref: id,
864
+ quote: line(300),
865
+ at: line(20),
866
+ file: line(200),
867
+ },
868
+ ["kind", "ref", "quote"],
869
+ ),
870
+ EVIDENCE_MAX,
871
+ ),
872
+ })
873
+
471
874
  const inboxOutput = object({
472
875
  /**
473
876
  * What waits for the person, as the host replaces its whole copy with each
@@ -476,14 +879,31 @@ const inboxOutput = object({
476
879
  * each and updated in place from day to day. An item that is no longer true
477
880
  * is left out, and the host drops it.
478
881
  */
479
- items: list(object({
480
- key: line(200),
481
- category: { type: "string", enum: ["request", OVERDUE_CATEGORY] },
482
- label: line(40),
483
- name: line(120),
484
- line: line(120),
485
- at: line(40),
486
- }), INBOX_MAX),
882
+ items: list(object(
883
+ {
884
+ key: line(200),
885
+ category: { type: "string", enum: ["request", OVERDUE_CATEGORY] },
886
+ label: line(40),
887
+ name: line(120),
888
+ line: line(120),
889
+ at: line(40),
890
+ /** A proposal's own type (`create`, `team_write`, `share`, …), where it has one: Jelly's `kind?` takes it. */
891
+ kind: line(40),
892
+ ...(INBOX_ITEM_SESSION
893
+ ? { session: line(200) }
894
+ : {}),
895
+ ...(INBOX_ITEM_MEETING ? INBOX_MEETING_FIELDS : {}),
896
+ ...(INBOX_ITEM_ACTIONS
897
+ ? {
898
+ /** The proposal's version, as `inbox.decide`'s `revision` takes it. */
899
+ revision: { type: "integer", minimum: 1 },
900
+ /** The decisions the item offers: accept, private, decline. */
901
+ decisions: { type: "array", maxItems: 3, items: { type: "string" } },
902
+ }
903
+ : {}),
904
+ },
905
+ ["key", "category", "label", "name", "line", "at"],
906
+ ), INBOX_MAX),
487
907
  })
488
908
 
489
909
  const pagesListOutput = object({
@@ -491,9 +911,33 @@ const pagesListOutput = object({
491
911
  /** The folder listed, "" for the top. */
492
912
  folder: line(64),
493
913
  folders: list(object({ name: line(64), count: integer }), FOLDERS_MAX),
494
- pages: list(object({ path: id, title: line(200), type: line(40), updated: line(40) }), PAGES_MAX),
914
+ pages: list(
915
+ object(
916
+ {
917
+ path: id,
918
+ title: line(200),
919
+ type: line(40),
920
+ updated: line(40),
921
+ /** The page's owning person, where the page names one. */
922
+ owner: pageOwner,
923
+ /** How many pages link to this one, at most `BACKLINKS_MAX`; absent when the count could not be read. */
924
+ backlinks: integer,
925
+ /** Whether there are more backlinks than `backlinks` counts. */
926
+ backlinksMore: flag,
927
+ },
928
+ ["path", "title", "type", "updated"],
929
+ ),
930
+ PAGES_MAX,
931
+ ),
495
932
  more: flag,
496
- })
933
+ /**
934
+ * Where the next page starts, when a folder has more pages than one answer
935
+ * lists: pass it back as `cursor`. Absent when this is the last page, and when
936
+ * the answer was cut for size (then `more` is true and the rest is not read
937
+ * further: a listing that big is read folder by folder).
938
+ */
939
+ cursor: line(CURSOR_CHARS),
940
+ }, ["space", "folder", "folders", "pages", "more"])
497
941
 
498
942
  const pageRef = { ...spaceInput, path: id, id }
499
943
 
@@ -508,14 +952,42 @@ const pagesReadOutput = object({
508
952
  stated_by: line(20),
509
953
  updated: line(40),
510
954
  version: integer,
955
+ /**
956
+ * The page's owning person, where Memory can name them: the record's owner, and
957
+ * the name the space's member roster gives that id. Left out when the roster
958
+ * cannot name the person (a reader with only a page grant cannot list members),
959
+ * and for the routines' own user: an id is not a name, and Jelly's `readPage`
960
+ * draws whatever `name` says.
961
+ */
962
+ owner: pageOwner,
963
+ /** When the page was last reviewed, from its own `fields.reviewed` (a date or date-time); absent when it says none. */
964
+ reviewed: line(40),
965
+ /**
966
+ * Whether a review is due: true when the page's own `fields.review_due` (a
967
+ * date) is today or earlier. A boolean because that is what Jelly's `readPage`
968
+ * draws ("Review due"); a page that names no due date says nothing.
969
+ */
970
+ reviewDue: flag,
511
971
  fields: list(object({ name: line(40), value: line(300) }), FIELDS_MAX),
512
972
  body: line(RECORD_BODY_CHARS),
513
973
  clipped: flag,
514
- /** Each `[[link]]` of the body: its target, and the record it names when there is one. */
515
- outlinks: list(object({ target: line(200), title: line(200), exists: flag }), LINKS_MAX),
974
+ /**
975
+ * Each `[[link]]` of the body: its target, the record it names when there is
976
+ * one, and `exists` only where existence is known — false for a page this
977
+ * reader can prove is not there, true for the record it read. It is absent
978
+ * when the answer would be a guess (a reader with only a page grant, a failed
979
+ * lookup), and the page then marks nothing; the rule is `src/outlinks.js`.
980
+ */
981
+ outlinks: list(object({ target: line(200), title: line(200), exists: flag }, ["target", "title"]), LINKS_MAX),
516
982
  backlinks: list(object({ id, path: line(200), title: line(200), type: line(40) }), LINKS_MAX),
517
983
  backlinksMore: flag,
518
- })
984
+ /**
985
+ * Present when these are only the backlinks this reader can see (it holds no
986
+ * space-level read, so the store filter hides the rest): the page says
987
+ * "Nothing you can see links here." rather than "Nothing links here yet."
988
+ */
989
+ backlinksPartial: flag,
990
+ }, ["space", "id", "path", "kind", "type", "title", "status", "stated_by", "updated", "version", "fields", "body", "clipped", "outlinks", "backlinks", "backlinksMore"])
519
991
 
520
992
  const lineageItem = object({ id, title: line(200), status: line(20) })
521
993
 
@@ -529,8 +1001,194 @@ const pagesHistoryOutput = object({
529
1001
  supersededBy: list(lineageItem, LINEAGE_MAX),
530
1002
  })
531
1003
 
1004
+ const termsInput = viewInput({
1005
+ /** A space the person chose from `spaces.list`; omitted, every space they can read. */
1006
+ space: id,
1007
+ /** The kinds of term to list; omitted, all of `TERM_TYPES`. */
1008
+ types: { type: "array", maxItems: TERM_TYPES.length, items: { type: "string", enum: [...TERM_TYPES] } },
1009
+ /** The most terms to list, 10 to `TERMS_MAX`; omitted, `TERMS_DEFAULT`. */
1010
+ max: { type: "integer", minimum: 10, maximum: TERMS_MAX },
1011
+ })
1012
+
1013
+ const termsOutput = object({
1014
+ /** The people and names Memory knows, in space order and then by text. */
1015
+ terms: list(
1016
+ object(
1017
+ {
1018
+ text: line(TERM_TEXT_CHARS),
1019
+ /** The page type the name came from: person, project, team, or a glossary entry. */
1020
+ kind: line(40),
1021
+ space: rowSpace,
1022
+ /** The page it is written on, for a reader that wants to open it. */
1023
+ path: id,
1024
+ },
1025
+ ["text", "kind", "space"],
1026
+ ),
1027
+ TERMS_MAX,
1028
+ ),
1029
+ /** Whether more names are held than this answer lists. */
1030
+ more: flag,
1031
+ /** A space that could not be read, or was not read, and why: named, never dropped. */
1032
+ incomplete: list(
1033
+ object({ id, name: line(200), reason: line(200) }, ["id", "name", "reason"]),
1034
+ LIST_MAX,
1035
+ ),
1036
+ })
1037
+
1038
+ const namesOutput = object({
1039
+ /**
1040
+ * The people, projects, teams and glossary terms Memory can name, the most
1041
+ * referenced first and then by name: at most `NAMES_MAX`, each one only
1042
+ * `{name, kind, aliases?}`, with no space id and no path (a dictation
1043
+ * vocabulary, not a page list). A name that appears in two spaces is one
1044
+ * entry, its aliases together.
1045
+ */
1046
+ names: list(
1047
+ object(
1048
+ {
1049
+ name: line(TERM_TEXT_CHARS),
1050
+ /** person, project, team, or a glossary entry (`term`). */
1051
+ kind: { type: "string", enum: [...NAME_KINDS] },
1052
+ /** Other ways the page says this name (`fields.aliases`), at most `NAME_ALIASES_MAX`, sorted; absent when it names none. */
1053
+ aliases: list(line(TERM_TEXT_CHARS), NAME_ALIASES_MAX),
1054
+ },
1055
+ ["name", "kind"],
1056
+ ),
1057
+ NAMES_MAX,
1058
+ ),
1059
+ /**
1060
+ * Whether the answer was cut: a space with more pages than one scan reads
1061
+ * (`NAMES_SCAN_PAGES`), more names than `NAMES_MAX`, or more glossary pages
1062
+ * than have their bodies read. A host that needs every name of such a space
1063
+ * asks for that space alone, or reads its pages.
1064
+ */
1065
+ more: flag,
1066
+ /** A space that could not be read, or was not read, and why: named, never dropped. */
1067
+ incomplete: list(
1068
+ object({ id, name: line(200), reason: line(200) }, ["id", "name", "reason"]),
1069
+ LIST_MAX,
1070
+ ),
1071
+ }, ["names", "more", "incomplete"])
1072
+
1073
+ /**
1074
+ * The people, and the grants, one access answer asks control for (Jelly's ask
1075
+ * 10): 50 a page, then `fitAccessPage` keeps what fits `ANSWER_BYTES`, and the
1076
+ * cursor continues after the last row shown. Control answers a space's whole
1077
+ * roster or a target's whole grant list, so the page and the cursor are what
1078
+ * keep an answer bounded without losing a row.
1079
+ */
1080
+ export const ACCESS_PAGE = 50
1081
+
1082
+ /**
1083
+ * A cursor of one of these reads: this read's own opaque token, bound to the
1084
+ * space and target it was given for (`encodeCursor`/`decodeCursor` in
1085
+ * `src/views/access-reads.js`), never the records service's.
1086
+ */
1087
+ const accessCursor = { type: "string", maxLength: CURSOR_CHARS }
1088
+
1089
+ const membersInput = viewInput({
1090
+ /** A space from `spaces.list`; omitted, the person's personal space. */
1091
+ space: id,
1092
+ /** The `cursor` a previous page answered, to read on from the row after its last; omitted, the top. */
1093
+ cursor: accessCursor,
1094
+ })
1095
+
1096
+ const membersOutput = object({
1097
+ /** The space whose roster this is. */
1098
+ space: rowSpace,
1099
+ /**
1100
+ * The space's people, as control's own roster gives them and its own rules
1101
+ * let the caller see: a member (viewer or above) or a space-wide grant, never
1102
+ * a page grant alone. At most `ACCESS_PAGE` a page, and always inside
1103
+ * `ANSWER_BYTES`.
1104
+ */
1105
+ members: list(
1106
+ object(
1107
+ {
1108
+ /** The person's control user id. */
1109
+ person: id,
1110
+ /** Their name, their email, or their id: one line, the person as control names them. */
1111
+ label: line(200),
1112
+ /** Their space role, in control's own words: owner, admin, editor or viewer. */
1113
+ role: line(40),
1114
+ /** When they joined, where control says. */
1115
+ added: line(40),
1116
+ },
1117
+ ["person", "label", "role"],
1118
+ ),
1119
+ ACCESS_PAGE,
1120
+ ),
1121
+ /** Whether anything is left after this page: a row cut for room, or a row past it. */
1122
+ more: flag,
1123
+ /** Where to read on from, whenever `more`: the row after the last one shown. */
1124
+ cursor: accessCursor,
1125
+ }, ["space", "members", "more"])
1126
+
1127
+ const grantsInput = viewInput({
1128
+ /** A space from `spaces.list`; omitted, the person's personal space. */
1129
+ space: id,
1130
+ /**
1131
+ * A page, folder or wiki of the space: the id of its registered share (the
1132
+ * `resource` a `mem_share` grant names), not a path. Its grants are its
1133
+ * owner's and a space admin's to list. Omitted, the answer is the grants that
1134
+ * name the caller, because a key cannot list every grant in a space.
1135
+ */
1136
+ target: id,
1137
+ /** The `cursor` a previous page answered, to read on from the row after its last; omitted, the top. */
1138
+ cursor: accessCursor,
1139
+ })
1140
+
1141
+ const grantsOutput = object({
1142
+ /** The space the grants are in. */
1143
+ space: rowSpace,
1144
+ /** Whose grants these are: the named target's (`target`), or the caller's own (`mine`). */
1145
+ scope: { type: "string", enum: ["target", "mine"] },
1146
+ /** The target the call named, or null for the caller's own grants. */
1147
+ target: { type: ["string", "null"], maxLength: 200 },
1148
+ /**
1149
+ * Who has access, and how much: one row a principal, the strongest access
1150
+ * first as control lists them. At most `ACCESS_PAGE` a page, and always
1151
+ * inside `ANSWER_BYTES`.
1152
+ */
1153
+ grants: list(
1154
+ object(
1155
+ {
1156
+ /**
1157
+ * Who it names: exactly one of `person`, `group`, `role` (an
1158
+ * organisation role) or `agent`, as control's principal types.
1159
+ */
1160
+ subject: {
1161
+ type: "object",
1162
+ additionalProperties: false,
1163
+ properties: { person: id, group: id, role: id, agent: id },
1164
+ },
1165
+ /** Their access in control's words: viewer, editor or admin. */
1166
+ access: line(40),
1167
+ /** What it is on: the space itself, a collection, or one registered resource. */
1168
+ target: object({ type: line(20), id }),
1169
+ /** A person's name (or email) where control gives one, else their id. */
1170
+ label: line(200),
1171
+ /** When the access started. */
1172
+ since: line(40),
1173
+ /** When it ends, where it does: control hides an expired grant. */
1174
+ expires: line(40),
1175
+ },
1176
+ ["subject", "access", "target", "label"],
1177
+ ),
1178
+ ACCESS_PAGE,
1179
+ ),
1180
+ /** Whether anything is left after this page: a row cut for room, or a row past it. */
1181
+ more: flag,
1182
+ /** Where to read on from, whenever `more`: the row after the last one shown. */
1183
+ cursor: accessCursor,
1184
+ /** Said when the list is the caller's own grants: a key reads no space's whole grant list. */
1185
+ note: line(300),
1186
+ }, ["space", "scope", "target", "grants", "more"])
1187
+
532
1188
  const graphInput = viewInput({
533
1189
  ...pageRef,
1190
+ /** A folder (a wiki): every page in it and the links between them, in one read. One of `path`, `id` or `folder`. */
1191
+ folder: line(64),
534
1192
  depth: { type: "integer", minimum: 1, maximum: 2 },
535
1193
  max: { type: "integer", minimum: 10, maximum: GRAPH_NODES_MAX },
536
1194
  /** Record types to keep (person, project, decision, …); empty keeps every type. */
@@ -551,7 +1209,16 @@ const graphOutput = object({
551
1209
  kind: line(20),
552
1210
  type: line(40),
553
1211
  dangling: flag,
554
- }),
1212
+ /**
1213
+ * The group this node's links put it in, among the nodes of this answer
1214
+ * (Jelly's ask 2, for colouring the graph): a computed grouping of the
1215
+ * visible pages, never stored, the same for the same graph
1216
+ * (`src/views/communities.js`; docs/jelly.md, "Communities in a graph").
1217
+ * A node the caller cannot see is not in the answer, so no community
1218
+ * reveals one. Every node of every answer carries it.
1219
+ */
1220
+ community: integer,
1221
+ }, ["id", "path", "title", "kind", "type", "dangling", "community"]),
555
1222
  GRAPH_NODES_MAX,
556
1223
  ),
557
1224
  /** Edges by node index. */
@@ -591,11 +1258,270 @@ const profileReadOutput = object({
591
1258
  notes: list(line(200), PROFILE_NOTES_MAX),
592
1259
  })
593
1260
 
1261
+ /**
1262
+ * The previews of Memory's actions (#58 section A): what a Jelly `always`
1263
+ * confirmation shows before the person presses, and A12's About-you preview.
1264
+ * Each is a read: it changes nothing, and it is called with the action's own
1265
+ * input, as the person whose device asked.
1266
+ *
1267
+ * `profile.erase.preview` is also one of the reads Jelly's About-you page asks
1268
+ * for by name (`LIVE_OPTIONAL_READS`, opencode-mem#49), so its shape is the one
1269
+ * that page reads.
1270
+ */
1271
+ const pagePath = { type: "string", maxLength: 300 }
1272
+ /** A memory a confirm or correct would change. */
1273
+ const memoryPreviewOutput = {
1274
+ type: "object",
1275
+ additionalProperties: false,
1276
+ required: ["found", "id", "version", "body", "status"],
1277
+ properties: {
1278
+ found: { type: "boolean" },
1279
+ id,
1280
+ version: { type: "integer", minimum: 0 },
1281
+ body: line(4000),
1282
+ status: { type: "string", maxLength: 40 },
1283
+ },
1284
+ }
1285
+
1286
+ /** A commitment a delete or a move would change: its own words, never only its id. */
1287
+ const commitmentPreviewOutput = {
1288
+ type: "object",
1289
+ additionalProperties: false,
1290
+ required: ["found", "id", "what", "state", "version"],
1291
+ properties: {
1292
+ found: { type: "boolean" },
1293
+ id,
1294
+ what: { type: "string", maxLength: 300 },
1295
+ state: { type: "string", maxLength: 40 },
1296
+ version: { type: "integer", minimum: 0 },
1297
+ to: { type: "string", maxLength: 200 },
1298
+ },
1299
+ }
1300
+
1301
+ /** A page a save or a delete touches, and a copy's source and target. */
1302
+ const pageFactsOutput = {
1303
+ type: "object",
1304
+ additionalProperties: false,
1305
+ required: ["space", "path", "exists", "version", "approvalRequired"],
1306
+ properties: { space: { type: "string", maxLength: 200 }, path: pagePath, exists: { type: "boolean" }, version: { type: "integer", minimum: 0 }, type: { type: "string", maxLength: 40 }, title: { type: "string", maxLength: 300 }, approvalRequired: { type: "boolean" } },
1307
+ }
1308
+ const accessPreviewOutput = {
1309
+ type: "object",
1310
+ properties: { ok: { type: "boolean" }, gainAccess: { type: "array", maxItems: 100, items: { type: "object" } }, loseAccess: { type: "array", maxItems: 100, items: { type: "object" } }, affected: { type: "integer", minimum: 0 }, target: { type: "object" }, from: { type: "object" }, to: { type: "object" }, path: pagePath, pages: { type: "integer", minimum: 0 }, wiki: id, space: { type: "string", maxLength: 200 }, ownerNow: { type: "object" }, state: { type: "string", maxLength: 40 } },
1311
+ }
1312
+ /** A move's answer: one page's access delta, or the pages a folder or a list moves. */
1313
+ const movePreviewOutput = {
1314
+ type: "object",
1315
+ properties: {
1316
+ ok: { type: "boolean" },
1317
+ action: { type: "string", maxLength: 40 },
1318
+ gainAccess: { type: "array", maxItems: 100, items: { type: "object" } },
1319
+ loseAccess: { type: "array", maxItems: 100, items: { type: "object" } },
1320
+ affected: { type: "integer", minimum: 0 },
1321
+ count: { type: "integer", minimum: 0 },
1322
+ // At most 50: a page's old and new path can each be 300 characters, and
1323
+ // Jelly caps a preview at 64 KiB (see MAX_FOLDER_PAGES in src/ops).
1324
+ pages: { type: "array", maxItems: 50, items: { type: "object" } },
1325
+ from: { type: "object" },
1326
+ to: { type: "object" },
1327
+ approvalRequired: { type: "boolean" },
1328
+ },
1329
+ }
1330
+
1331
+ /** A delete's answer: every page the press removes. */
1332
+ const deletePreviewOutput = {
1333
+ type: "object",
1334
+ additionalProperties: false,
1335
+ required: ["space", "count", "pages", "approvalRequired"],
1336
+ properties: {
1337
+ space: { type: "string", maxLength: 200 },
1338
+ count: { type: "integer", minimum: 0 },
1339
+ pages: {
1340
+ type: "array",
1341
+ maxItems: 50,
1342
+ items: { type: "object", additionalProperties: false, required: ["path", "exists", "version"], properties: { path: pagePath, exists: { type: "boolean" }, version: { type: "integer", minimum: 0 }, type: { type: "string", maxLength: 40 }, title: { type: "string", maxLength: 300 } } },
1343
+ },
1344
+ path: pagePath,
1345
+ exists: { type: "boolean" },
1346
+ version: { type: "integer", minimum: 0 },
1347
+ approvalRequired: { type: "boolean" },
1348
+ },
1349
+ }
1350
+
1351
+ /** A copy's answer: a page's source and target, or the memories it would take. */
1352
+ const copyPreviewOutput = {
1353
+ type: "object",
1354
+ additionalProperties: false,
1355
+ required: ["op", "from", "to"],
1356
+ properties: {
1357
+ ok: { type: "boolean" },
1358
+ op: { type: "string", enum: ["page", "memories"] },
1359
+ from: { type: "object" },
1360
+ to: { type: "object" },
1361
+ count: { type: "integer", minimum: 0 },
1362
+ ids: { type: "array", maxItems: 100, items: id },
1363
+ memories: { type: "array", maxItems: 50, items: { type: "object" } },
1364
+ missing: { type: "array", maxItems: 100, items: id },
1365
+ note: { type: "string", maxLength: 300 },
1366
+ },
1367
+ }
1368
+
1369
+ /** What one organiser op would change: the op's own name, and the memories. */
1370
+ const organisePreviewOutput = {
1371
+ type: "object",
1372
+ additionalProperties: false,
1373
+ required: ["op", "label", "from"],
1374
+ properties: {
1375
+ ok: { type: "boolean" },
1376
+ op: { type: "string", enum: ["retire", "restore", "confirm"] },
1377
+ label: { type: "string", maxLength: 60 },
1378
+ count: { type: "integer", minimum: 0 },
1379
+ memories: {
1380
+ type: "array",
1381
+ maxItems: 50,
1382
+ items: { type: "object", additionalProperties: false, required: ["id", "title"], properties: { id, title: { type: "string", maxLength: 160 }, status: { type: "string", maxLength: 40 } } },
1383
+ },
1384
+ missing: { type: "array", maxItems: 100, items: id },
1385
+ from: { type: "object" },
1386
+ to: { type: "object" },
1387
+ },
1388
+ }
1389
+
1390
+ /** What one space op would change: the op's own name, and the space. */
1391
+ const spaceManagePreviewOutput = {
1392
+ type: "object",
1393
+ additionalProperties: false,
1394
+ required: ["op", "label", "space"],
1395
+ properties: {
1396
+ ok: { type: "boolean" },
1397
+ op: { type: "string", enum: ["rename", "archive", "unarchive", "leave"] },
1398
+ label: { type: "string", maxLength: 60 },
1399
+ space: { type: "object", additionalProperties: false, required: ["id"], properties: { id, name: { type: "string", maxLength: 200 } } },
1400
+ to: { type: "string", maxLength: 120 },
1401
+ summary: { type: "string", maxLength: 300 },
1402
+ reversible: { type: "boolean" },
1403
+ expectedDigest: { type: "string", maxLength: 200 },
1404
+ },
1405
+ }
1406
+
1407
+ const pageWritePreviewOutput = {
1408
+ type: "object",
1409
+ additionalProperties: false,
1410
+ required: ["space", "path", "exists", "version", "approvalRequired", "added", "removed"],
1411
+ properties: {
1412
+ space: { type: "string", maxLength: 200 },
1413
+ path: pagePath,
1414
+ /** Whether the page exists now: false is a create, at `expectVersion` 0. */
1415
+ exists: { type: "boolean" },
1416
+ /** Its version now, 0 when it does not exist. */
1417
+ version: { type: "integer", minimum: 0 },
1418
+ /** The version the action carries, where the page gave one; absent when it carries none. */
1419
+ expectVersion: { type: "integer", minimum: 0 },
1420
+ /** True for a team space: the person approves the change in Memory's own page, never here. */
1421
+ approvalRequired: { type: "boolean" },
1422
+ /** Lines the write would add, and remove, against the version it names. */
1423
+ added: { type: "integer", minimum: 0 },
1424
+ removed: { type: "integer", minimum: 0 },
1425
+ },
1426
+ }
1427
+
1428
+ const joinRequestPreviewOutput = {
1429
+ type: "object",
1430
+ properties: {
1431
+ ok: { type: "boolean" },
1432
+ /** The request the person is deciding. */
1433
+ requestId: id,
1434
+ /** The space it is for. */
1435
+ space: { type: "object", properties: { id: { type: "string", maxLength: 200 }, name: { type: "string", maxLength: 400 } } },
1436
+ /** The person who asked; null when the request no longer names one. */
1437
+ user: { type: ["object", "null"], properties: { user_id: { type: "string", maxLength: 200 }, name: { type: "string", maxLength: 400 } } },
1438
+ /** The words they wrote with the request, if any. */
1439
+ note: { type: ["string", "null"], maxLength: 2000 },
1440
+ /** The read access the asker gains when it is approved. */
1441
+ gainAccess: { type: "array", maxItems: 100, items: { type: "object" } },
1442
+ loseAccess: { type: "array", maxItems: 100, items: { type: "object" } },
1443
+ affected: { type: "integer", minimum: 0 },
1444
+ },
1445
+ }
1446
+
1447
+ const visibilityPreviewOutput = {
1448
+ type: "object",
1449
+ properties: {
1450
+ ok: { type: "boolean" },
1451
+ space: { type: "object", properties: { id: { type: "string", maxLength: 200 }, name: { type: "string", maxLength: 400 } } },
1452
+ /** Who may join now, and who could after the change. */
1453
+ from: { type: "string", enum: ["invite", "open"] },
1454
+ to: { type: "string", enum: ["invite", "open"] },
1455
+ /** How many people are in it now. */
1456
+ members: { type: "integer", minimum: 0 },
1457
+ /** The join requests that would become direct joins. */
1458
+ pendingRequests: { type: "integer", minimum: 0 },
1459
+ /** Who could then find or join it, in the person's words. */
1460
+ discoverable: line(400),
1461
+ unaffected: { type: "array", maxItems: 100, items: { type: "object" } },
1462
+ },
1463
+ }
1464
+
1465
+ const proposalPreviewOutput = {
1466
+ type: "object",
1467
+ additionalProperties: false,
1468
+ required: ["found", "id", "version", "state", "kind", "space", "text"],
1469
+ properties: {
1470
+ /** False when the proposal is gone, or is not this person's to decide. */
1471
+ found: { type: "boolean" },
1472
+ id,
1473
+ version: { type: "integer", minimum: 0 },
1474
+ /** proposed, accepting, accepted, rejected, applied, applied_private or declined. */
1475
+ state: { type: "string", maxLength: 40 },
1476
+ /** The proposal's type: create, share, team_write and so on. */
1477
+ kind: { type: "string", maxLength: 40 },
1478
+ /** The shared space a held write would reach, where it names one. */
1479
+ space: { type: "string", maxLength: 200 },
1480
+ /** The record's title, on one line: what a confirm panel says ("Keep "<title>"?"), never its id (jelly #75). */
1481
+ title: line(120),
1482
+ /** The words a keep, an edit or a private keep would save. */
1483
+ text: line(4000),
1484
+ },
1485
+ }
1486
+
1487
+ const erasePreviewOutput = {
1488
+ type: "object",
1489
+ additionalProperties: false,
1490
+ required: ["lines", "count", "snapshot"],
1491
+ properties: {
1492
+ lines: {
1493
+ type: "array",
1494
+ maxItems: 20,
1495
+ items: {
1496
+ type: "object",
1497
+ additionalProperties: false,
1498
+ required: ["id", "text", "space"],
1499
+ properties: { id, text: line(300), space: { type: "string", maxLength: 200 } },
1500
+ },
1501
+ },
1502
+ /** Every line the erase would remove, including the ones not shown. */
1503
+ count: { type: "integer", minimum: 0 },
1504
+ /** The digest the erase action carries; a profile that changed no longer has it. */
1505
+ snapshot: { type: "string", maxLength: 43 },
1506
+ /** True when the phrase is too short to erase by (under four characters). */
1507
+ tooShort: { type: "boolean" },
1508
+ /** What the erase does not do: the turns it came from stay, so it can come back. */
1509
+ note: { type: "string", maxLength: 300 },
1510
+ },
1511
+ }
1512
+
594
1513
  /**
595
1514
  * The methods, in the order `package.json` declares them.
596
1515
  * @type {ReadonlyArray<{ name: string, label: string, permission: string, input: object, output: object }>}
597
1516
  */
598
1517
  export const VIEW_METHODS = Object.freeze([
1518
+ {
1519
+ name: "memory.setup",
1520
+ label: "read how long Memory's own setup took at this engine start",
1521
+ permission: "mem_status",
1522
+ input: empty,
1523
+ output: setupOutput,
1524
+ },
599
1525
  {
600
1526
  name: "memory.overview",
601
1527
  label: "say whether memory is connected and how much it holds",
@@ -665,7 +1591,7 @@ export const VIEW_METHODS = Object.freeze([
665
1591
  name: "pages.list",
666
1592
  label: "list your pages by folder",
667
1593
  permission: "mem_page",
668
- input: viewInput({ ...spaceInput, folder: line(64) }),
1594
+ input: viewInput({ ...spaceInput, folder: line(64), cursor: line(CURSOR_CHARS) }),
669
1595
  output: pagesListOutput,
670
1596
  },
671
1597
  {
@@ -696,21 +1622,242 @@ export const VIEW_METHODS = Object.freeze([
696
1622
  input: empty,
697
1623
  output: profileReadOutput,
698
1624
  },
1625
+ {
1626
+ name: "profile.erase.preview",
1627
+ label: "show the lines an erase from your profile would remove",
1628
+ permission: "mem_recall",
1629
+ input: viewInput({ phrase: line(200), snapshot: line(43) }, ["phrase"]),
1630
+ output: erasePreviewOutput,
1631
+ },
1632
+ {
1633
+ name: "page.write.preview",
1634
+ label: "show what a page write would change",
1635
+ permission: "mem_page",
1636
+ // The body stays under the 64 KiB a grant can carry (ADR §4.4), as the
1637
+ // action's own does.
1638
+ input: viewInput({ space: line(128), path: pagePath, body: line(58 * 1024), expectVersion: { type: "integer", minimum: 0 } }, ["space", "path"]),
1639
+ output: pageWritePreviewOutput,
1640
+ },
1641
+ {
1642
+ name: "page.save.preview",
1643
+ label: "show what saving a page would write",
1644
+ permission: "mem_page",
1645
+ input: viewInput({ space: line(128), path: line(300), folder: line(200), title: line(300), body: withoutNote(pageBody), meeting: withoutNote(pageMeeting), transcript: withoutNote(pageTranscript), files: { type: "array", maxItems: 50, items: line(300) } }, ["body"]),
1646
+ output: pageFactsOutput,
1647
+ },
1648
+ {
1649
+ name: "page.move.preview",
1650
+ label: "show who gains and loses a moved page",
1651
+ permission: "mem_page",
1652
+ // One page, a folder or up to fifty pages: the preview takes the action's
1653
+ // own input, and answers every page a folder or a list would move.
1654
+ input: viewInput({
1655
+ space: line(128),
1656
+ path: line(300),
1657
+ prefix: line(300),
1658
+ paths: { type: "array", maxItems: 50, items: line(300) },
1659
+ to: { type: "object", additionalProperties: false, properties: { space: line(128), path: line(300), folder: line(200) } },
1660
+ }, ["space"]),
1661
+ output: movePreviewOutput,
1662
+ },
1663
+ {
1664
+ name: "page.delete.preview",
1665
+ label: "show the page a delete would remove",
1666
+ permission: "mem_page",
1667
+ // Every page the press removes, never only the first.
1668
+ input: viewInput({ space: line(128), path: line(300), paths: { type: "array", maxItems: 50, items: line(300) } }, ["space"]),
1669
+ output: deletePreviewOutput,
1670
+ },
1671
+ {
1672
+ name: "wiki.delete.preview",
1673
+ label: "show what deleting a wiki would remove",
1674
+ permission: "mem_wiki",
1675
+ input: viewInput({ space: line(128), wiki: id }, ["space", "wiki"]),
1676
+ output: accessPreviewOutput,
1677
+ },
1678
+ {
1679
+ name: "share.copy.preview",
1680
+ label: "show what a copy would take, and where it would land",
1681
+ permission: "mem_page",
1682
+ // `op` picks the console's two copies: a page, or the person's own memories.
1683
+ // `to.wiki` sends a page's copy into a hub wiki, as one flat source file.
1684
+ input: viewInput({ op: { type: "string", enum: ["page", "memories"] }, from: { type: "object", additionalProperties: false, properties: { space: line(128), path: line(300) } }, to: { type: "object", additionalProperties: false, properties: { space: line(128), folder: line(200), path: line(300), wiki: line(128) } }, ids: { type: "array", maxItems: 100, items: id }, version: { type: "integer", minimum: 1 }, note: line(300) }, ["op"]),
1685
+ output: copyPreviewOutput,
1686
+ },
1687
+ {
1688
+ name: "commitment.delete.preview",
1689
+ label: "show the commitment a delete would remove",
1690
+ permission: "mem_commitments",
1691
+ input: viewInput({ id, space: line(128), what: line(300), revision: { type: "integer", minimum: 1 } }, ["id"]),
1692
+ output: commitmentPreviewOutput,
1693
+ },
1694
+ {
1695
+ name: "commitment.move.preview",
1696
+ label: "show the commitment a move would take, and where it goes",
1697
+ permission: "mem_commitments",
1698
+ input: viewInput({ id, space: line(128), what: line(300), revision: { type: "integer", minimum: 1 }, to: { type: "object", additionalProperties: false, required: ["space"], properties: { space: line(128) } } }, ["space", "id", "to"]),
1699
+ output: commitmentPreviewOutput,
1700
+ },
1701
+ {
1702
+ name: "memory.organise.preview",
1703
+ label: "show which memories would move, retire, restore or be confirmed",
1704
+ permission: "mem_recall",
1705
+ // The preview names the op: moving memories and confirming them are not the
1706
+ // same press.
1707
+ input: viewInput({ space: line(128), op: { type: "string", enum: ["retire", "restore", "confirm"] }, ids: { type: "array", maxItems: 100, items: id } }, ["space", "op"]),
1708
+ output: organisePreviewOutput,
1709
+ },
1710
+ {
1711
+ name: "share.grant.preview",
1712
+ label: "show what sharing would give someone",
1713
+ permission: "mem_share",
1714
+ input: viewInput({ space: line(128), target: { type: "object" }, person: line(200), access: { type: "string", enum: ["read", "write"] } }, ["target", "person", "access"]),
1715
+ output: accessPreviewOutput,
1716
+ },
1717
+ {
1718
+ name: "share.revoke.preview",
1719
+ label: "show what taking access back would change",
1720
+ permission: "mem_share",
1721
+ input: viewInput({ space: line(128), target: { type: "object" }, person: line(200) }, ["target", "person"]),
1722
+ output: accessPreviewOutput,
1723
+ },
1724
+ {
1725
+ name: "share.transfer.preview",
1726
+ needsControlP2: true,
1727
+ label: "show who would own a space after a handover",
1728
+ permission: "mem_share",
1729
+ input: viewInput({ space: line(128), target: { type: "object" }, to: line(200) }, ["space", "to"]),
1730
+ output: accessPreviewOutput,
1731
+ },
1732
+ {
1733
+ name: "space.manage.preview",
1734
+ needsControlP2: true,
1735
+ label: "show what renaming, archiving or leaving a space would change",
1736
+ permission: "mem_spaces",
1737
+ input: viewInput({ space: line(128), op: { type: "string", enum: ["rename", "archive", "unarchive", "leave"] }, name: line(120), expectedDigest: line(200) }, ["space", "op"]),
1738
+ output: spaceManagePreviewOutput,
1739
+ },
1740
+ {
1741
+ name: "space.joinRequest.preview",
1742
+ label: "show who a join request would let in",
1743
+ permission: "mem_spaces",
1744
+ input: viewInput({ requestId: id, decision: { type: "string", enum: ["approve", "decline"] }, note: line(300) }, ["requestId"]),
1745
+ output: joinRequestPreviewOutput,
1746
+ },
1747
+ {
1748
+ name: "space.visibility.preview",
1749
+ needsControlP2: true,
1750
+ label: "show who could find or join a space after a change",
1751
+ permission: "mem_spaces",
1752
+ input: viewInput({ space: line(128), visibility: { type: "string", enum: ["invite", "open"] } }, ["space", "visibility"]),
1753
+ output: visibilityPreviewOutput,
1754
+ },
1755
+ {
1756
+ name: "proposal.decide.preview",
1757
+ label: "show the edit a proposal decision would apply",
1758
+ permission: "mem_spaces",
1759
+ input: viewInput({ space: line(128), id, op: { type: "string", enum: ["accept", "askChanges", "reject"] }, edits: line(56 * 1024), note: line(2000) }, ["id", "op"]),
1760
+ output: proposalPreviewOutput,
1761
+ },
1762
+ {
1763
+ name: "memory.revise.preview",
1764
+ label: "show the memory a confirm or correct would change",
1765
+ permission: "mem_recall",
1766
+ // An `add` has no record yet: the read answers `found: false`, which is what
1767
+ // the person's own confirmation needs to know.
1768
+ input: viewInput({ space: line(128), id, revision: { type: "integer", minimum: 1 }, action: { type: "string", enum: ["confirm", "correct", "add"] }, content: line(56 * 1024) }, ["space"]),
1769
+ output: memoryPreviewOutput,
1770
+ },
1771
+ {
1772
+ name: "inbox.decide.preview",
1773
+ label: "show the Inbox item a decision would settle",
1774
+ permission: "mem_spaces",
1775
+ input: viewInput({ itemId: line(200), decision: { type: "string", enum: ["accept", "private", "decline"] }, revision: { type: "integer", minimum: 1 } }, ["itemId", "decision", "revision"]),
1776
+ output: proposalPreviewOutput,
1777
+ },
1778
+ {
1779
+ name: "review.decide.preview",
1780
+ label: "show the record a review decision would save",
1781
+ permission: "mem_spaces",
1782
+ input: viewInput({ id, op: { type: "string", enum: ["accept", "edit", "reject", "private", "decline"] }, revision: { type: "integer", minimum: 1 }, text: line(4000) }, ["id", "op"]),
1783
+ output: proposalPreviewOutput,
1784
+ },
1785
+ {
1786
+ name: "write.decide.preview",
1787
+ label: "show the held write an edit or a private keep acts on",
1788
+ permission: "mem_spaces",
1789
+ input: viewInput({ id, op: { type: "string", enum: ["edit", "private"] }, revision: { type: "integer", minimum: 1 }, text: line(4000) }, ["id", "op"]),
1790
+ output: proposalPreviewOutput,
1791
+ },
1792
+ {
1793
+ name: "held.decide.preview",
1794
+ needsRoom: true,
1795
+ label: "show the held write an accept, edit or drop acts on",
1796
+ permission: "mem_spaces",
1797
+ input: viewInput({ id, op: { type: "string", enum: ["accept", "edit", "drop"] }, edits: line(4000), revision: { type: "integer", minimum: 1 } }, ["id", "op"]),
1798
+ output: proposalPreviewOutput,
1799
+ },
1800
+ {
1801
+ name: "suggestion.dismiss.preview",
1802
+ needsRoom: true,
1803
+ label: "show the suggestion a dismissal would hide",
1804
+ permission: "mem_spaces",
1805
+ input: viewInput({ id, forever: { type: "boolean" }, revision: { type: "integer", minimum: 1 } }, ["id"]),
1806
+ output: proposalPreviewOutput,
1807
+ },
1808
+ {
1809
+ name: "terms.list",
1810
+ label: "list the people and names Memory knows",
1811
+ permission: "mem_page",
1812
+ input: termsInput,
1813
+ output: termsOutput,
1814
+ },
1815
+ {
1816
+ name: "names.known",
1817
+ label: "list the names Memory knows, for dictation",
1818
+ permission: "mem_page",
1819
+ input: empty,
1820
+ output: namesOutput,
1821
+ },
1822
+ // Who is in a space, and who one of its pages is shared with: the space page
1823
+ // and the share sheet read them here instead of asking the agent (ask 10).
1824
+ // Both answer as `mem_spaces` does (`members`, `access`), and control decides
1825
+ // every visibility rule: a member's roster, a page owner's or an admin's grants.
1826
+ {
1827
+ name: "members.list",
1828
+ label: "list a space's members",
1829
+ permission: "mem_spaces",
1830
+ input: membersInput,
1831
+ output: membersOutput,
1832
+ },
1833
+ {
1834
+ name: "grants.list",
1835
+ label: "list who a page, folder or wiki is shared with",
1836
+ permission: "mem_spaces",
1837
+ input: grantsInput,
1838
+ output: grantsOutput,
1839
+ },
699
1840
  ])
700
1841
 
701
- // TODO(#49): no snooze action, and no other act, is declared here yet. Snoozing
702
- // an overdue commitment is `commitments.update {id, due}` with a new due date,
703
- // confirm never (Jelly's answer on #48): the item clears by itself once the due
704
- // day is in the future. Acting from a host's UI waits for the verified-caller
705
- // grant and its verifier (#49, 0.10), so until then the person moves a due date
706
- // by asking the agent (`mem_commitments update`). Declare the act, and add it
707
- // to `jelly.actions`, in the change that lands the verifier; never as an
708
- // unverified RPC.
1842
+ // The acts are declared in `jelly.actions` (#58 section A), not here: they are
1843
+ // what a person's own page changes as the person, under a host-signed grant
1844
+ // (docs/design/adr-verified-caller-grants.md). Snoozing an overdue commitment is
1845
+ // `commitment.snooze {id, due}` with a new due date, confirm never (Jelly's
1846
+ // answer on #48): the item clears by itself once the due day is in the future.
1847
+ // `src/actions.js` is their one source, and `test/actions.test.js` holds
1848
+ // `package.json` to it. No action is an RPC method: `act.<name>` is registered
1849
+ // with the engine alone, and Jelly's own fence refuses it to everything but the
1850
+ // host's call for a person.
709
1851
 
710
1852
  /** The refusal a page can show in the plugin's own words (`call.error`). */
711
1853
  export const VIEW_ERROR = "memory.refused"
712
1854
 
713
- /** `jelly.rpc` as package.json declares it. */
1855
+ /**
1856
+ * `jelly.rpc` as package.json declares it: every read the views call, and the
1857
+ * previews of every action declared. With Jelly's protocol major 7 (48
1858
+ * actions) all actions are declared, so every preview is named here too; the
1859
+ * `needsControlP2`/`needsRoom` markers stay on the methods as history.
1860
+ */
714
1861
  export function declaredMethods() {
715
1862
  return VIEW_METHODS.map(({ name, label, permission, input, output }) => ({
716
1863
  name,