@joe-broadhead/opencode-mem 0.9.14 → 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 (139) hide show
  1. package/CHANGELOG.md +1805 -0
  2. package/README.md +14 -7
  3. package/SECURITY.md +3 -1
  4. package/docs/agent-instructions.md +1 -1
  5. package/docs/agent-protocol.md +7 -7
  6. package/docs/permissions.md +16 -0
  7. package/package.json +7688 -339
  8. package/shared/page-paths.js +44 -0
  9. package/skills/mem.pages/SKILL.md +3 -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 +623 -30
  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 +11 -6
  88. package/src/recall.js +92 -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 +389 -92
  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 +37 -4
  104. package/src/tools/held-write.js +31 -12
  105. package/src/tools/index.js +27 -0
  106. package/src/tools/ingest.js +27 -2
  107. package/src/tools/memory.js +30 -7
  108. package/src/tools/page.js +95 -9
  109. package/src/tools/recall.js +208 -4
  110. package/src/tools/share.js +42 -3
  111. package/src/tools/shared.js +44 -4
  112. package/src/tools/space-lifecycle.js +278 -0
  113. package/src/tools/spaces.js +373 -29
  114. package/src/tools/status.js +9 -2
  115. package/src/tools/wiki.js +34 -4
  116. package/src/util.js +110 -6
  117. package/src/vendor/source-contract/README.md +24 -0
  118. package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
  119. package/src/vendor/source-contract/VENDOR.json +81 -0
  120. package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
  121. package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
  122. package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
  123. package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
  124. package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
  125. package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
  126. package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
  127. package/src/vendor/source-contract/cursor.js +26 -0
  128. package/src/vendor/source-contract/events.js +257 -0
  129. package/src/vendor/source-contract/registry.js +23 -0
  130. package/src/vendor/source-contract/tools-rpc.js +42 -0
  131. package/src/views/access-reads.js +256 -0
  132. package/src/views/communities.js +77 -0
  133. package/src/views/contracts.js +930 -21
  134. package/src/views/inbox-bytes.js +103 -0
  135. package/src/views/profile.js +31 -0
  136. package/src/views/records-reads.js +355 -38
  137. package/src/views/rpc.js +118 -8
  138. package/src/views/shape.js +8 -5
  139. package/views/pages.html +2 -2
@@ -0,0 +1,1162 @@
1
+ /**
2
+ * The fixed frame of plugin-declared Memory (DESIGN-PLUGIN-MEMORY §1.2, §5.6,
3
+ * and DESIGN-MEMORY-JOBS §9 for schema v2): the `memory-plugin.v2` schema of a
4
+ * plugin's `package.json#memory`, the read-verb allowlist with the write-verb
5
+ * check on every token, the connector's identity, reads and scope inputs, its
6
+ * templates, and the canonical digest (RFC 8785 JSON, SHA-256).
7
+ *
8
+ * One module, three copies kept identical by scripts/check-copies.mjs:
9
+ * records/src/plugins/manifest.js for the records service, which validates
10
+ * every report again, and src/plugins/manifest.js for the plugin's discovery.
11
+ * Its only import is the shape guard, which sits beside both copies.
12
+ *
13
+ * Nothing here names a plugin or a source. A manifest that fails anywhere is
14
+ * invalid as a whole: `validateManifest` answers the first reason, and
15
+ * nothing in it is used. Plugin text is data: it is length-limited and
16
+ * shape-checked here, and never enters a prompt, a tool description, a skill
17
+ * or the protocol.
18
+ */
19
+ import { createHash } from "node:crypto"
20
+ import { shapes } from "../shapes.js"
21
+
22
+ /** The schema's major version. Memory accepts this one and the one before it (v1's `sources` + `routines`). */
23
+ export const SCHEMA_VERSION = 2
24
+ export const SCHEMA_VERSIONS = Object.freeze([1, 2])
25
+ /** The `events_list` contract a declared source must speak (§9.3). */
26
+ export const SOURCE_CONTRACT = 2
27
+ /**
28
+ * The event fields a `perUnit` scope input may take its value from (§9.1 C).
29
+ * `thread` is written `<scheme>-thread:<channel id>:<thread ts>`, so its channel
30
+ * and its ts are the two parts of it, never anything parsed from an event's text.
31
+ */
32
+ export const PER_UNIT_FIELDS = Object.freeze(["external_id", "thread_channel", "thread_ts"])
33
+
34
+ /** The allowed verbs (§9.1 A). `fetch` is not one: it can send data out. */
35
+ export const READ_VERBS = Object.freeze(["read", "get", "list", "search", "lookup", "view", "describe", "history", "query", "count"])
36
+ /**
37
+ * The write verbs (§5.6): no token of a tail or op may be one of these.
38
+ *
39
+ * The name check cannot prove a tool is read-only: a tool named `get_x` may
40
+ * write. It refuses the obvious names; the real defences are that a binding's
41
+ * session allows exactly the grants the person confirmed (src/plugins/grants.js)
42
+ * and the plugin kit's recorded-assertion check, which fails a plugin's CI on
43
+ * any action its events_list asserts that its declaration does not list.
44
+ */
45
+ export const WRITE_VERBS = Object.freeze([
46
+ "send", "post", "reply", "set", "add", "edit", "create", "update", "upsert", "delete", "remove", "trash", "modify", "patch", "insert",
47
+ "import", "export", "write", "put", "save", "publish", "share", "invite", "upload", "schedule", "react", "mark", "label", "pin",
48
+ "follow", "archive", "move", "merge", "close", "comment", "assign", "draft", "approve", "submit", "cancel", "revoke", "grant", "run",
49
+ "execute", "invoke", "purge", "destroy", "drop", "wipe", "erase", "transfer", "trigger", "kick",
50
+ "join", "leave", "ban", "mute", "toggle", "forward", "dispatch", "clear", "flush", "reset", "truncate", "overwrite", "apply",
51
+ ])
52
+ /** Tokens that join two actions in one name (`read_and_delete`): refused whatever the verbs. */
53
+ export const CONJUNCTIONS = Object.freeze(["and", "then", "or"])
54
+ /** The deepest a declaration may nest (the schema needs 6), and the deepest canonical JSON goes. */
55
+ export const MAX_DEPTH = 12
56
+ const MAX_CANONICAL_DEPTH = 64
57
+ /** Namespaces no plugin may claim: Memory's own, the host's, and OpenCode's builtin tool ids. */
58
+ export const RESERVED_NAMESPACES = Object.freeze([
59
+ "mem", "opencode", "jobs", "execute", "codemode",
60
+ "bash", "read", "write", "edit", "glob", "grep", "list", "patch", "task", "todowrite", "todoread", "webfetch", "websearch", "skill", "question", "lsp", "shell", "plan", "build",
61
+ ])
62
+ /** The event kinds of the `events_list` contract, with v2's `snapshot` (§1.4). */
63
+ export const EVENT_KINDS = Object.freeze(["message", "meeting", "session", "bookmark", "issue", "pr", "commit", "doc", "event", "snapshot"])
64
+ /** The `render` engine's placeholders (§4.3), and only these. */
65
+ export const RENDER_PLACEHOLDERS = Object.freeze(["title", "count", "participants", "first_at", "last_at", "cite", "url", "text"])
66
+ /** The output kinds (§4.5). `section:<Heading>` is written with its heading. */
67
+ export const PROPOSAL_OUTPUTS = Object.freeze(["decision", "fact", "commitment_open", "commitment_close", "procedure", "person", "link"])
68
+
69
+ export const MAX_SOURCES = 8
70
+ export const MAX_ROUTINES = 16
71
+ export const MAX_READS = 16
72
+ export const MAX_TEMPLATES = 8
73
+ export const MAX_GRANTS = 8
74
+ export const MAX_SCOPE_KEYS = 8
75
+ export const MAX_INPUT_BYTES = 512
76
+ export const MAX_HINTS = 1500
77
+ export const MAX_RENDER_ITEMS = 50
78
+ export const MAX_TOKENS_PER_RUN = 25_000
79
+
80
+ const ID = /^[a-z][a-z0-9-]{0,39}$/
81
+ const NAMESPACE = /^[a-z][a-z0-9-]{0,31}$/
82
+ const LABEL = /^[a-z][a-z0-9_.:-]{0,63}$/
83
+ const LABEL_PREFIX = /^[a-z][a-z0-9_-]{0,31}$/
84
+ const METRIC = /^[a-z][a-z0-9_]{0,23}$/
85
+ const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/
86
+ const WINDOWS = ["1d", "7d", "31d"]
87
+ /** A host a templated `{url}` may point at: a domain, or `*.` and a domain. */
88
+ const HOST_PATTERN = /^(?:\*\.)?[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i
89
+ /**
90
+ * The multi-label public suffixes a person can register under but not *be*: a
91
+ * pattern of one of these names no site of theirs. A small embedded list, the
92
+ * common ones; a suffix it misses is caught by the registrable-domain rule.
93
+ */
94
+ const PUBLIC_SUFFIXES = new Set([
95
+ "co.uk", "org.uk", "ac.uk", "gov.uk", "me.uk", "net.uk", "sch.uk", "ltd.uk", "plc.uk",
96
+ "com.au", "net.au", "org.au", "edu.au", "gov.au", "co.nz", "net.nz", "org.nz", "govt.nz",
97
+ "co.jp", "ne.jp", "or.jp", "go.jp", "co.kr", "or.kr", "co.in", "net.in", "org.in", "co.za",
98
+ "com.br", "net.br", "org.br", "com.mx", "com.ar", "com.co", "com.pe", "com.ve", "com.uy",
99
+ "com.tr", "com.cn", "com.tw", "com.hk", "com.sg", "com.my", "com.ph", "com.vn", "com.pk",
100
+ "com.ng", "com.sa", "com.eg", "com.ua", "com.pl", "com.es", "com.gr", "com.pt", "com.ro",
101
+ "co.id", "co.il", "co.ke", "co.th", "co.ae", "co.ma", "co.bw", "co.zw", "co.tz", "co.ug",
102
+ ])
103
+ /** Hosts anyone can claim, or that hand a page to the next stranger: no evidence of the source. */
104
+ const SHARED_HOSTS = new Set([
105
+ "cloudfront.net", "amazonaws.com", "storage.googleapis.com", "blob.core.windows.net", "web.core.windows.net",
106
+ "herokuapp.com", "vercel.app", "netlify.app", "pages.dev", "workers.dev", "github.io", "githubusercontent.com",
107
+ "gitlab.io", "bitbucket.io", "appspot.com", "firebaseapp.com", "web.app", "azurewebsites.net", "elasticbeanstalk.com",
108
+ "onrender.com", "railway.app", "fly.dev", "deno.dev", "glitch.me", "repl.co", "surge.sh", "ngrok.io", "r2.dev",
109
+ "blogspot.com", "wordpress.com", "wixsite.com", "translate.goog", "ipfs.io", "dweb.link", "bit.ly", "tinyurl.com",
110
+ ])
111
+ /** Measurement and advertising: a collected link to one of these is a beacon, not a source. */
112
+ const TRACKER_HOSTS = new Set([
113
+ "doubleclick.net", "google-analytics.com", "googletagmanager.com", "googleadservices.com", "googlesyndication.com",
114
+ "2mdn.net", "facebook.net", "scorecardresearch.com", "criteo.com", "taboola.com", "outbrain.com", "adnxs.com",
115
+ "hotjar.com", "segment.io", "mixpanel.com", "amplitude.com", "quantserve.com", "moatads.com", "adsrvr.org",
116
+ "casalemedia.com", "rubiconproject.com", "pubmatic.com", "openx.net", "clarity.ms", "branch.io", "appsflyer.com",
117
+ "adjust.com", "kochava.com", "smartadserver.com", "teads.tv", "yieldmo.com", "bat.bing.com",
118
+ ])
119
+
120
+ /**
121
+ * The second-level labels a ccTLD hands out as registry rules (`com.de`,
122
+ * `gov.in`, `co.uk`): a pattern of one of these plus a two-letter country code
123
+ * names no site, and so does a wildcard on it. The embedded suffix list names
124
+ * the common ones; this rule is what catches one it misses.
125
+ */
126
+ const EFFECTIVE_SLD = new Set([
127
+ "com", "co", "gov", "org", "net", "ac", "edu", "ne", "or", "go", "nic", "mil", "sch", "ltd", "plc",
128
+ "gen", "web", "biz", "info", "nom", "res", "idv", "gob", "gouv", "gv", "k12", "muni",
129
+ ])
130
+
131
+ /** True when a two-label host is an effective-TLD rule: `<second level>.<ccTLD>`. */
132
+ function isEffectiveSldRule(labels) {
133
+ return labels.length === 2 && EFFECTIVE_SLD.has(labels[0]) && /^[a-z]{2}$/.test(labels[1])
134
+ }
135
+
136
+ /** The multi-label public suffix a host ends in, or null. */
137
+ function publicSuffixOf(labels) {
138
+ for (const size of [3, 2]) {
139
+ if (labels.length > size && PUBLIC_SUFFIXES.has(labels.slice(-size).join("."))) return labels.slice(-size).join(".")
140
+ }
141
+ return null
142
+ }
143
+
144
+ /**
145
+ * Why a `urlHosts` pattern is too broad to mean anything, or null: a public
146
+ * suffix alone, a wildcard sitting on one, no registrable domain under a
147
+ * wildcard, a shared host, or a tracker.
148
+ */
149
+ export function urlHostProblem(host) {
150
+ if (typeof host !== "string" || !HOST_PATTERN.test(host)) return "is not a host pattern (a domain such as slack.com, or *.slack.com)"
151
+ const bare = host.toLowerCase().replace(/^\*\./, "")
152
+ const labels = bare.split(".")
153
+ if (labels.length < 2) return "names no registrable domain (a host needs at least two labels)"
154
+ // §9.4: a label in punycode (`xn--…`) hides what the host actually is — another
155
+ // script, or a lookalike of the source's own name — so no pattern may carry one.
156
+ if (labels.some((label) => label.startsWith("xn--"))) return "is a punycode host (a label starting xn--), which hides what it is"
157
+ const suffix = publicSuffixOf(labels)
158
+ if (PUBLIC_SUFFIXES.has(bare)) return `is a public suffix (${bare}), which names no site`
159
+ if (isEffectiveSldRule(labels)) return `is an effective-TLD rule (${bare}), which names no site`
160
+ if (suffix && bare === suffix) return `is a public suffix (${suffix}), which names no site`
161
+ for (const listed of SHARED_HOSTS) if (bare === listed || bare.endsWith(`.${listed}`)) return `is a shared host (${listed}), which anyone can claim`
162
+ for (const listed of TRACKER_HOSTS) if (bare === listed || bare.endsWith(`.${listed}`)) return `is a tracker (${listed}), which is no source's destination`
163
+ return null
164
+ }
165
+ const CADENCES = ["daily", "weekly", "monthly"]
166
+ const ENGINES = ["render", "extract"]
167
+ const UNITS = ["event", "thread"]
168
+
169
+ class Invalid extends Error {}
170
+
171
+ /**
172
+ * A plugin-supplied name, as a reason may echo it: letters, digits, _, . and
173
+ * - only, at most 40 characters, else a fixed word. Reasons are shown in the
174
+ * console and reach the records service; they never carry plugin text.
175
+ */
176
+ function echo(name) {
177
+ const value = String(name ?? "")
178
+ return /^[A-Za-z0-9_.-]{1,40}$/.test(value) ? value : "(a name that is not shown)"
179
+ }
180
+
181
+ /** True when a JSON value nests deeper than `max` (arrays and objects), checked without recursion. */
182
+ function deeperThan(value, max) {
183
+ const stack = [[value, 0]]
184
+ while (stack.length) {
185
+ const [item, depth] = stack.pop()
186
+ if (item === null || typeof item !== "object") continue
187
+ if (depth >= max) return true
188
+ for (const child of Array.isArray(item) ? item : Object.values(item)) if (child !== null && typeof child === "object") stack.push([child, depth + 1])
189
+ }
190
+ return false
191
+ }
192
+
193
+ function fail(message) {
194
+ throw new Invalid(message)
195
+ }
196
+
197
+ function isObject(value) {
198
+ return value !== null && typeof value === "object" && !Array.isArray(value)
199
+ }
200
+
201
+ function object(value, where) {
202
+ if (!isObject(value)) fail(`${where} must be an object`)
203
+ return value
204
+ }
205
+
206
+ function only(value, keys, where) {
207
+ for (const key of Object.keys(value)) if (!keys.includes(key)) fail(`${where} has an unknown field ${echo(key)}`)
208
+ }
209
+
210
+ function list(value, where, { min = 0, max }) {
211
+ if (!Array.isArray(value)) fail(`${where} must be a list`)
212
+ if (value.length < min) fail(`${where} needs at least ${min} item${min === 1 ? "" : "s"}`)
213
+ if (value.length > max) fail(`${where} has more than ${max} items`)
214
+ return value
215
+ }
216
+
217
+ function pattern(value, regex, where) {
218
+ if (typeof value !== "string" || !regex.test(value)) fail(`${where} must match ${regex.source}`)
219
+ return value
220
+ }
221
+
222
+ function integer(value, where, { min, max }) {
223
+ if (!Number.isInteger(value) || value < min || value > max) fail(`${where} must be a whole number from ${min} to ${max}`)
224
+ return value
225
+ }
226
+
227
+ function bool(value, where) {
228
+ if (typeof value !== "boolean") fail(`${where} must be true or false`)
229
+ }
230
+
231
+ /** Display or template text: a string, at most `max` characters, no control characters, no unsafe shape. */
232
+ function text(value, where, { max, empty = false }) {
233
+ if (typeof value !== "string") fail(`${where} must be text`)
234
+ if (!empty && value.trim() === "") fail(`${where} must not be empty`)
235
+ if (value.length > max) fail(`${where} is longer than ${max} characters`)
236
+ if (CONTROL.test(value)) fail(`${where} has a control character`)
237
+ if (shapes(value).any) fail(`${where} has an unsafe shape (an instruction, a permission or a share)`)
238
+ return value
239
+ }
240
+
241
+ /** The tokens of a name: split on `_`, `.`, `-` and camelCase, lower case. */
242
+ function tokens(name) {
243
+ return String(name)
244
+ .split(/[_.\-]+/)
245
+ .flatMap((part) => part.split(/(?<=[a-z0-9])(?=[A-Z])/))
246
+ .map((part) => part.toLowerCase())
247
+ .filter(Boolean)
248
+ }
249
+
250
+ /**
251
+ * The forms a token may be a write verb in: itself, and without -ed, -ied,
252
+ * -d or -ing (a doubled last consonant undone). Plurals (-s, -es, -ies) and
253
+ * -er nouns are not: `labels`, `posts`, `sender` and `folder` are reads, and
254
+ * a compound such as `read_and_deletes` is refused by its conjunction.
255
+ */
256
+ function stems(token) {
257
+ const out = new Set([token])
258
+ for (const [suffix, back] of [["ied", "y"], ["ed", ""], ["d", ""], ["ing", ""]]) {
259
+ if (!token.endsWith(suffix) || token.length <= suffix.length + 1) continue
260
+ const base = token.slice(0, -suffix.length) + back
261
+ out.add(base)
262
+ out.add(`${base}e`)
263
+ if (/([b-df-hj-np-tv-z])\1$/.test(base)) out.add(base.slice(0, -1))
264
+ }
265
+ return [...out]
266
+ }
267
+
268
+ /** The first token that is a write verb in any form, or a conjunction; null when there is none. */
269
+ function writeToken(name) {
270
+ for (const token of tokens(name)) {
271
+ if (CONJUNCTIONS.includes(token)) return { token, conjunction: true }
272
+ const verb = stems(token).find((form) => WRITE_VERBS.includes(form))
273
+ if (verb) return { token, verb }
274
+ }
275
+ return null
276
+ }
277
+
278
+ function writeReason(found, where = "") {
279
+ return found.conjunction ? `"${found.token}"${where} joins two actions in one name` : `"${found.token}"${where} is a write verb (${found.verb})`
280
+ }
281
+
282
+ /**
283
+ * Why a grant is refused, or null when it is inside the frame (§5.6).
284
+ *
285
+ * - `action` is `<ns>_<tail>` or `<ns>.<tail>`; a tail starting `<ns>_` (an
286
+ * MCP server of the same name) loses that prefix once.
287
+ * - The tail is `events_list`; or `read` with a `[{account}:]<op>` resource
288
+ * whose op's last dotted segment starts with a read verb; or a tail whose
289
+ * first `_` token is a read verb.
290
+ * - Every token of the tail, and of a `read` op, passes the write-verb check.
291
+ * - No `*` or `?` in an action; a resource is `*` or a template whose only
292
+ * placeholder is `{account}`.
293
+ *
294
+ * @param {unknown} grant
295
+ * @param {string} namespace
296
+ * @returns {string | null}
297
+ */
298
+ export function checkGrant(grant, namespace) {
299
+ if (!isObject(grant)) return "a grant must be an object {action, resource}"
300
+ for (const key of Object.keys(grant)) if (key !== "action" && key !== "resource") return `a grant has an extra field ${echo(key)}`
301
+ const { action, resource } = grant
302
+ if (typeof action !== "string" || action.length === 0 || action.length > 120) return "a grant's action must be text of at most 120 characters"
303
+ const name = echo(action)
304
+ if (typeof resource !== "string" || resource.length === 0 || resource.length > 200) return `${name}: the resource must be text of at most 200 characters`
305
+ if (/[*?]/.test(action)) return `${name}: an action may not hold * or ?`
306
+ if (!/^[A-Za-z0-9_.-]+$/.test(action)) return `${name}: an action is letters, digits, _, . and - only`
307
+ const placeholders = resource.match(/\{[^}]*\}?/g) ?? []
308
+ if (placeholders.some((item) => item !== "{account}") || /[{}]/.test(resource.replaceAll("{account}", ""))) return `${name}: a resource's only placeholder is {account}`
309
+ if (resource !== "*" && resource.includes("*")) return `${name}: a resource is * or a template, not a pattern`
310
+ let tail = null
311
+ for (const separator of ["_", "."]) if (action.startsWith(`${namespace}${separator}`)) tail = action.slice(namespace.length + 1)
312
+ if (tail === null) return `${name}: not in the namespace ${namespace}`
313
+ if (tail.startsWith(`${namespace}_`)) tail = tail.slice(namespace.length + 1)
314
+ if (tail === "") return `${name}: no tool name after the namespace`
315
+ const write = writeToken(tail)
316
+ if (write) return `${name}: ${writeReason(write)}`
317
+ if (tail === "events_list") return null
318
+ if (tail === "read") {
319
+ const op = resource.startsWith("{account}:") ? resource.slice("{account}:".length) : resource
320
+ if (!/^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/.test(op)) return `${name}: a read resource is [{account}:]<op>, a dotted operation name`
321
+ const opWrite = writeToken(op)
322
+ if (opWrite) return `${name}: ${writeReason(opWrite, ` in ${echo(op)}`)}`
323
+ const first = tokens(op.split(".").at(-1))[0]
324
+ if (!READ_VERBS.includes(first)) return `${name}: ${echo(op)} does not start with a read verb (${READ_VERBS.join(", ")})`
325
+ return null
326
+ }
327
+ const first = tail.split("_")[0]
328
+ if (!READ_VERBS.includes(first)) return `${name}: "${echo(first)}" is not a read verb (${READ_VERBS.join(", ")})`
329
+ return null
330
+ }
331
+
332
+ function grants(value, namespace, where) {
333
+ list(value, where, { min: 0, max: MAX_GRANTS })
334
+ if (value.length > MAX_GRANTS) fail(`${where}: at most ${MAX_GRANTS} grants`)
335
+ const seen = new Set()
336
+ for (const grant of value) {
337
+ const reason = checkGrant(grant, namespace)
338
+ if (reason) fail(`${where}: ${reason}`)
339
+ const key = `${grant.action}\u0000${grant.resource}`
340
+ if (seen.has(key)) fail(`${where}: ${grant.action} is listed twice`)
341
+ seen.add(key)
342
+ }
343
+ }
344
+
345
+ /**
346
+ * A v2 grant (§9.1 A and D): `<ns>_<tool>` or `<ns>.<verb>`, a read verb
347
+ * somewhere in the name and no write verb anywhere, and a resource of `*` or
348
+ * `{account}:<operation>` whose last dotted segment starts with a read verb —
349
+ * an allowlist, so an operation added to an API later is refused by default.
350
+ */
351
+ function connectorGrants(value, namespace, where) {
352
+ list(value, where, { min: 1, max: MAX_GRANTS })
353
+ const seen = new Set()
354
+ for (const grant of value) {
355
+ object(grant, where)
356
+ only(grant, ["action", "resource"], where)
357
+ const { action, resource } = grant
358
+ if (typeof action !== "string" || action.length === 0 || action.length > 120) fail(`${where}: an action must be text of at most 120 characters`)
359
+ const name = echo(action)
360
+ if (typeof resource !== "string" || resource.length === 0 || resource.length > 200) fail(`${where}: ${name}: the resource must be text of at most 200 characters`)
361
+ if (/[*?]/.test(action) || !/^[A-Za-z0-9_.-]+$/.test(action)) fail(`${where}: ${name}: an action is letters, digits, _, . and - only, with no * or ?`)
362
+ const write = writeToken(action)
363
+ if (write) fail(`${where}: ${name}: ${writeReason(write)}`)
364
+ if (!tokens(action).some((token) => READ_VERBS.includes(token))) fail(`${where}: ${name} has no read verb (${READ_VERBS.join(", ")})`)
365
+ if (!action.startsWith(`${namespace}_`) && !action.startsWith(`${namespace}.`)) fail(`${where}: ${name} is not in the namespace ${namespace}`)
366
+ const placeholders = resource.match(/\{[^}]*\}?/g) ?? []
367
+ if (placeholders.some((item) => item !== "{account}") || /[{}]/.test(resource.replaceAll("{account}", ""))) fail(`${where}: ${name}: a resource's only placeholder is {account}`)
368
+ if (resource !== "*" && resource.includes("*")) fail(`${where}: ${name}: a resource is * or a template, not a pattern`)
369
+ if (resource !== "*") {
370
+ const operation = resource.startsWith("{account}:") ? resource.slice("{account}:".length) : resource
371
+ if (!/^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/.test(operation)) fail(`${where}: ${name}: a read resource is {account}:<operation>, a dotted operation name`)
372
+ const last = operation.split(".").at(-1)
373
+ if (!READ_VERBS.some((verb) => tokens(last)[0]?.startsWith(verb) ?? last.startsWith(verb))) fail(`${where}: ${name}: ${echo(last)} does not start with a read verb (${READ_VERBS.join(", ")})`)
374
+ }
375
+ const key = `${action}\u0000${resource}`
376
+ if (seen.has(key)) fail(`${where}: ${action} is listed twice`)
377
+ seen.add(key)
378
+ }
379
+ }
380
+
381
+ function checkSource(source, namespace, at) {
382
+ object(source, at)
383
+ only(source, ["id", "title", "summary", "contract", "input", "kinds", "grants", "probe", "scope", "cadence", "billing", "setup"], at)
384
+ const id = pattern(source.id, ID, `${at}.id`)
385
+ const where = `source ${id}`
386
+ text(source.title, `${where}: title`, { max: 60 })
387
+ text(source.summary, `${where}: summary`, { max: 200 })
388
+ if (source.contract !== SOURCE_CONTRACT) fail(`${where}: contract must be ${SOURCE_CONTRACT} (events_list v2)`)
389
+ if (source.input !== undefined) {
390
+ object(source.input, `${where}: input`)
391
+ if (Buffer.byteLength(canonicalJSON(source.input)) > MAX_INPUT_BYTES) fail(`${where}: input is larger than ${MAX_INPUT_BYTES} bytes`)
392
+ }
393
+ list(source.kinds, `${where}: kinds`, { min: 1, max: EVENT_KINDS.length })
394
+ if (!source.kinds.every((kind) => EVENT_KINDS.includes(kind)) || new Set(source.kinds).size !== source.kinds.length) fail(`${where}: kinds must be distinct names from ${EVENT_KINDS.join(", ")}`)
395
+ if (!Array.isArray(source.grants) || source.grants.length === 0) fail(`${where}: grants must list the actions events_list asserts`)
396
+ if (source.grants.length > MAX_GRANTS) fail(`${where}: at most ${MAX_GRANTS} grants`)
397
+ grants(source.grants, namespace, `${where}: grants`)
398
+ if (source.probe !== undefined) {
399
+ object(source.probe, `${where}: probe`)
400
+ only(source.probe, ["grants"], `${where}: probe`)
401
+ if (source.probe.grants !== undefined) {
402
+ if (Array.isArray(source.probe.grants) && source.probe.grants.length > MAX_GRANTS) fail(`${where}: probe: at most ${MAX_GRANTS} grants`)
403
+ grants(source.probe.grants, namespace, `${where}: probe.grants`)
404
+ }
405
+ }
406
+ if (source.scope !== undefined) {
407
+ list(source.scope, `${where}: scope`, { max: MAX_SCOPE_KEYS })
408
+ const keys = new Set()
409
+ for (const [index, item] of source.scope.entries()) {
410
+ const at2 = `${where}: scope[${index}]`
411
+ object(item, at2)
412
+ only(item, ["key", "title", "kind", "pattern", "max", "required", "suggest"], at2)
413
+ const key = pattern(item.key, /^[a-z][a-z0-9_]{0,31}$/, `${at2}.key`)
414
+ if (keys.has(key)) fail(`${where}: scope key ${key} is listed twice`)
415
+ keys.add(key)
416
+ text(item.title, `${at2}.title`, { max: 60 })
417
+ if (item.kind !== "ids") fail(`${at2}.kind must be "ids"`)
418
+ if (typeof item.pattern !== "string" || item.pattern.length === 0 || item.pattern.length > 120) fail(`${at2}.pattern must be a regular expression of at most 120 characters`)
419
+ try {
420
+ new RegExp(item.pattern, "u")
421
+ } catch {
422
+ fail(`${at2}.pattern is not a valid regular expression`)
423
+ }
424
+ integer(item.max, `${at2}.max`, { min: 1, max: 64 })
425
+ bool(item.required, `${at2}.required`)
426
+ bool(item.suggest, `${at2}.suggest`)
427
+ }
428
+ }
429
+ if (source.cadence !== undefined) {
430
+ object(source.cadence, `${where}: cadence`)
431
+ only(source.cadence, ["everyMinutes"], `${where}: cadence`)
432
+ // Memory clamps it to at least 15 (120 when billed) at use; here it is only a number.
433
+ integer(source.cadence.everyMinutes, `${where}: cadence.everyMinutes`, { min: 1, max: 10_080 })
434
+ }
435
+ if (source.billing !== undefined && source.billing !== null) {
436
+ object(source.billing, `${where}: billing`)
437
+ only(source.billing, ["unit", "note"], `${where}: billing`)
438
+ if (source.billing.unit !== "call") fail(`${where}: billing.unit must be "call"`)
439
+ if (source.billing.note !== undefined) text(source.billing.note, `${where}: billing.note`, { max: 200 })
440
+ }
441
+ if (source.setup !== undefined) text(source.setup, `${where}: setup`, { max: 300, empty: true })
442
+ return id
443
+ }
444
+
445
+ /**
446
+ * The markup a template's literal text may not carry: the block's own markers
447
+ * (a `<!-- /lens -->` in a line would end the block early), an image or a link
448
+ * (a line is text), an HTML tag, and a heading or quote (a line starts with the
449
+ * block's own bullet).
450
+ */
451
+ const LINE_MARKUP = Object.freeze([
452
+ [/<!--|-->/, "an HTML comment, or a lens marker"],
453
+ [/!\[/, "an image"],
454
+ [/\]\(/, "a link"],
455
+ [/<\/?[a-z]/i, "an HTML tag"],
456
+ [/^\s*#{1,6}\s/, "a heading"],
457
+ [/^\s*>\s/, "a quote"],
458
+ ])
459
+
460
+ /**
461
+ * Why a text carries markup a line may not have, or null. One judgement, used
462
+ * on a template's literal text and again on the line **after** substitution:
463
+ * a placeholder's value is collected text, so markup can arrive through it.
464
+ */
465
+ export function lineMarkupProblem(value) {
466
+ const text = String(value ?? "")
467
+ for (const [pattern, what] of LINE_MARKUP) if (pattern.test(text)) return what
468
+ return null
469
+ }
470
+
471
+ /** The characters that turn two placeholders into markup: `!{title}({url})`. */
472
+ const MARKUP_NEIGHBOURS = new Set(["!", "[", "]", "(", ")"])
473
+
474
+ /** A render line's literal text, with its placeholders checked and cut out, and no markup left in it. */
475
+ function renderLine(line, where) {
476
+ text(line, where, { max: 200 })
477
+ // A placeholder may not sit against the characters that make markup: the
478
+ // rendered line is checked too, but a template that can build markup at all
479
+ // is refused before it ever runs.
480
+ for (const match of line.matchAll(/\{([^{}]*)\}/g)) {
481
+ const name = match[1]
482
+ const before = match.index > 0 ? line[match.index - 1] : ""
483
+ const after = line[match.index + match[0].length] ?? ""
484
+ for (const [side, neighbour] of [["before", before], ["after", after]]) {
485
+ if (MARKUP_NEIGHBOURS.has(neighbour)) fail(`${where}: the placeholder {${echo(name)}} sits next to "${neighbour}" (${side} it), which makes markup. Put a space between them`)
486
+ }
487
+ }
488
+ const literal = line.replace(/\{([^{}]*)\}/g, (_, name) => {
489
+ if (RENDER_PLACEHOLDERS.includes(name)) return " "
490
+ if (/^metric:/.test(name) && METRIC.test(name.slice("metric:".length))) return " "
491
+ fail(`${where}: {${echo(name)}} is not a placeholder (${RENDER_PLACEHOLDERS.map((p) => `{${p}}`).join(", ")}, {metric:<key>})`)
492
+ })
493
+ if (/[{}]/.test(literal)) fail(`${where}: an unmatched { or }`)
494
+ const markup = lineMarkupProblem(literal)
495
+ if (markup) fail(`${where} carries markup: ${markup}. A line is text; the block's markers are Memory's`)
496
+ text(literal, where, { max: 200, empty: true })
497
+ }
498
+
499
+ function checkOutput(output, engine, where) {
500
+ if (typeof output !== "string") fail(`${where}: an output must be text`)
501
+ if (output === "journal" || output === "timeline") return
502
+ if (output.startsWith("section:")) {
503
+ if (engine !== "render") fail(`${where}: a section output is for the render engine only`)
504
+ text(output.slice("section:".length), `${where}: the section heading`, { max: 60 })
505
+ return
506
+ }
507
+ if (output.startsWith("proposal:") && PROPOSAL_OUTPUTS.includes(output.slice("proposal:".length))) {
508
+ if (engine !== "extract") fail(`${where}: proposals come from the extract engine only`)
509
+ return
510
+ }
511
+ fail(`${where}: ${echo(output)} is not an output kind (journal, timeline, section:<Heading>, proposal:${PROPOSAL_OUTPUTS.join("|")})`)
512
+ }
513
+
514
+ function checkRoutine(routine, sources, at) {
515
+ object(routine, at)
516
+ only(routine, ["id", "title", "summary", "on", "engine", "select", "hints", "render", "outputs", "budget"], at)
517
+ const id = pattern(routine.id, ID, `${at}.id`)
518
+ const where = `routine ${id}`
519
+ text(routine.title, `${where}: title`, { max: 60 })
520
+ text(routine.summary, `${where}: summary`, { max: 200 })
521
+ if (!CADENCES.includes(routine.on)) fail(`${where}: on must be ${CADENCES.join(", ")}`)
522
+ if (!ENGINES.includes(routine.engine)) fail(`${where}: engine must be render or extract`)
523
+ const select = object(routine.select, `${where}: select`)
524
+ only(select, ["sources", "kinds", "labels", "unit", "participant", "latest", "window", "minEvents", "maxUnits"], `${where}: select`)
525
+ list(select.sources, `${where}: select.sources`, { min: 1, max: MAX_SOURCES })
526
+ for (const name of select.sources) if (typeof name !== "string" || !sources.has(name)) fail(`${where}: select.sources may name only this plugin's own sources`)
527
+ if (select.kinds !== undefined) {
528
+ const allowed = new Set(select.sources.flatMap((name) => sources.get(name)))
529
+ list(select.kinds, `${where}: select.kinds`, { min: 1, max: EVENT_KINDS.length })
530
+ if (!select.kinds.every((kind) => allowed.has(kind))) fail(`${where}: select.kinds must be kinds its sources declare`)
531
+ }
532
+ if (select.labels !== undefined) {
533
+ list(select.labels, `${where}: select.labels`, { min: 1, max: 16 })
534
+ for (const label of select.labels) pattern(label, LABEL, `${where}: a label`)
535
+ }
536
+ if (!UNITS.includes(select.unit)) fail(`${where}: select.unit must be event or thread`)
537
+ if (select.participant !== undefined && select.participant !== "owner") fail(`${where}: select.participant may only be "owner"`)
538
+ if (select.latest !== undefined) {
539
+ object(select.latest, `${where}: select.latest`)
540
+ only(select.latest, ["per"], `${where}: select.latest`)
541
+ pattern(select.latest.per, LABEL_PREFIX, `${where}: select.latest.per`)
542
+ }
543
+ if (!WINDOWS.includes(select.window)) fail(`${where}: select.window must be ${WINDOWS.join(", ")}`)
544
+ if (select.minEvents !== undefined) integer(select.minEvents, `${where}: select.minEvents`, { min: 1, max: 1000 })
545
+ if (select.maxUnits !== undefined) integer(select.maxUnits, `${where}: select.maxUnits`, { min: 1, max: 200 })
546
+ if (routine.engine === "extract") {
547
+ if (routine.render !== undefined) fail(`${where}: render is for the render engine only`)
548
+ if (routine.hints !== undefined) text(routine.hints, `${where}: hints`, { max: MAX_HINTS })
549
+ if (routine.budget !== undefined) {
550
+ object(routine.budget, `${where}: budget`)
551
+ only(routine.budget, ["tokensPerRun"], `${where}: budget`)
552
+ // Clamped to MAX_TOKENS_PER_RUN at use (§4.6); here only a positive number.
553
+ integer(routine.budget.tokensPerRun, `${where}: budget.tokensPerRun`, { min: 1, max: 1_000_000 })
554
+ }
555
+ } else {
556
+ if (routine.hints !== undefined) fail(`${where}: hints are for the extract engine only`)
557
+ if (routine.budget !== undefined) fail(`${where}: a budget is for the extract engine only`)
558
+ const render = object(routine.render, `${where}: render`)
559
+ only(render, ["into", "heading", "line", "max"], `${where}: render`)
560
+ if (render.into !== "journal" && render.into !== "section") fail(`${where}: render.into must be journal or section`)
561
+ text(render.heading, `${where}: render.heading`, { max: 60 })
562
+ renderLine(render.line, `${where}: render.line`)
563
+ integer(render.max, `${where}: render.max`, { min: 1, max: MAX_RENDER_ITEMS })
564
+ }
565
+ list(routine.outputs, `${where}: outputs`, { min: 1, max: 12 })
566
+ if (new Set(routine.outputs).size !== routine.outputs.length) fail(`${where}: an output is listed twice`)
567
+ for (const output of routine.outputs) checkOutput(output, routine.engine, `${where}: outputs`)
568
+ return id
569
+ }
570
+
571
+ /**
572
+ * Validate a `package.json#memory` value against `memory-plugin.v2` (or v1, the
573
+ * schema before connectors) and the frame. Never throws.
574
+ *
575
+ * @param {unknown} value
576
+ * @returns {{ ok: true, errors: [], reason: null, namespace: string } | { ok: false, errors: string[], reason: string }}
577
+ */
578
+ export function validateManifest(value) {
579
+ try {
580
+ const manifest = object(value, "the memory section")
581
+ if (deeperThan(manifest, MAX_DEPTH)) fail(`the memory section is nested deeper than ${MAX_DEPTH} levels`)
582
+ if (!Number.isInteger(manifest.version) || !SCHEMA_VERSIONS.includes(manifest.version)) fail(`version must be ${SCHEMA_VERSIONS.join(" or ")} (memory-plugin.v${SCHEMA_VERSION})`)
583
+ const namespace = manifest.version === 1 ? checkManifestV1(manifest) : checkManifestV2(manifest)
584
+ canonicalJSON(manifest)
585
+ return { ok: true, errors: [], reason: null, namespace }
586
+ } catch (error) {
587
+ const reason = error instanceof Invalid ? error.message : "the memory section could not be read"
588
+ return { ok: false, errors: [reason.slice(0, 300)], reason: reason.slice(0, 300) }
589
+ }
590
+ }
591
+
592
+ /** v1: sources of events and routines over them. Kept while a v1 plugin is installed. */
593
+ function checkManifestV1(manifest) {
594
+ only(manifest, ["$schema", "version", "namespace", "sources", "routines"], "the memory section")
595
+ if (manifest.$schema !== undefined && (typeof manifest.$schema !== "string" || manifest.$schema.length > 300)) fail("$schema must be a URL of at most 300 characters")
596
+ const namespace = namespaceOf(manifest)
597
+ list(manifest.sources, "sources", { min: 1, max: MAX_SOURCES })
598
+ const sources = new Map()
599
+ for (const [index, source] of manifest.sources.entries()) {
600
+ const id = checkSource(source, namespace, `sources[${index}]`)
601
+ if (sources.has(id)) fail(`duplicate source id ${id}`)
602
+ sources.set(id, source.kinds)
603
+ }
604
+ if (manifest.routines !== undefined) {
605
+ list(manifest.routines, "routines", { max: MAX_ROUTINES })
606
+ const ids = new Set()
607
+ for (const [index, routine] of manifest.routines.entries()) {
608
+ const id = checkRoutine(routine, sources, `routines[${index}]`)
609
+ if (ids.has(id)) fail(`duplicate routine id ${id}`)
610
+ ids.add(id)
611
+ }
612
+ }
613
+ return namespace
614
+ }
615
+
616
+ /** The namespace both schemas share, reserved names refused. */
617
+ function namespaceOf(manifest) {
618
+ const namespace = pattern(manifest.namespace, NAMESPACE, "namespace")
619
+ if (RESERVED_NAMESPACES.includes(namespace)) fail(`namespace ${namespace} is reserved`)
620
+ return namespace
621
+ }
622
+
623
+ // ---------------------------------------------------------------------------
624
+ // v2 (§9): the connector, its sources' identities, its reads, and its templates
625
+
626
+ /** A v2 section key the schema does not define, with the rename the design made where there is one. */
627
+ function onlyV2(value, keys, where) {
628
+ for (const key of Object.keys(value)) {
629
+ if (keys.includes(key)) continue
630
+ fail(key === "setup" ? `${where} has the unknown field setup: the static line is setupHint (§9.2)` : `${where} has an unknown field ${echo(key)}`)
631
+ }
632
+ }
633
+
634
+ function checkManifestV2(manifest) {
635
+ only(manifest, ["$schema", "version", "namespace", "connector", "sources", "templates"], "the memory section")
636
+ if (typeof manifest.$schema !== "string" || manifest.$schema.length > 300) fail("$schema must be a URL of at most 300 characters")
637
+ const namespace = namespaceOf(manifest)
638
+ const connector = checkConnector(manifest.connector, namespace)
639
+ list(manifest.sources, "sources", { min: 1, max: MAX_SOURCES })
640
+ const sources = new Map()
641
+ for (const [index, source] of manifest.sources.entries()) {
642
+ const id = checkConnectorSource(source, namespace, connector, `sources[${index}]`)
643
+ if (sources.has(id)) fail(`duplicate source id ${id}`)
644
+ sources.set(id, source)
645
+ }
646
+ // §9.1 D: a source's grants are a job's grants, so a suggestBy grant that is one
647
+ // of them has entered a job by the back door.
648
+ for (const source of sources.values()) {
649
+ for (const grant of source.grants) {
650
+ if (connector.suggest.has(grant.action)) fail(`source ${source.id}: ${grant.action} is a suggestBy grant and also a source's grant: suggestBy runs only at bind, so it is never a job's (§9.1 D)`)
651
+ }
652
+ }
653
+ // §9.2: a connector-wide default identity is enough until one sign-in differs;
654
+ // a source with none of its own needs the connector's.
655
+ if (!connector.identity && ![...sources.values()].every((source) => source.identity)) {
656
+ fail(`a source declares no identity and the connector has none, so Memory cannot read which account it is (§9.2)`)
657
+ }
658
+ if (manifest.templates !== undefined) {
659
+ list(manifest.templates, "templates", { max: MAX_TEMPLATES })
660
+ const ids = new Set()
661
+ for (const [index, template] of manifest.templates.entries()) {
662
+ const id = checkTemplate(template, new Set(sources.keys()), `templates[${index}]`, connector.reads)
663
+ if (ids.has(id)) fail(`duplicate template id ${id}`)
664
+ ids.add(id)
665
+ }
666
+ }
667
+ return namespace
668
+ }
669
+
670
+ /**
671
+ * §9.1 B and D: the connector's accounts, its own scope keys with their
672
+ * `suggestBy`, its declared reads, and whether it claims `operationScoped`.
673
+ */
674
+ function checkConnector(connector, namespace) {
675
+ object(connector, "the connector")
676
+ onlyV2(connector, ["accounts", "identity", "identityRead", "operationScoped", "reads", "scope", "billing", "urlHosts"], "the connector")
677
+ if (connector.accounts !== "single" && connector.accounts !== "multi") fail(`connector.accounts must be "single" or "multi"`)
678
+ if (connector.operationScoped !== undefined) bool(connector.operationScoped, "connector.operationScoped")
679
+ if (connector.identity !== undefined) checkIdentity(connector.identity, namespace, "the connector's identity", { sourceLevel: true })
680
+ if (connector.identityRead !== undefined) checkIdentity(connector.identityRead, namespace, "the connector's identityRead", { sourceLevel: false })
681
+ const scopeKeys = checkScope(connector.scope, namespace, "the connector's scope")
682
+ const reads = checkReads(connector.reads, namespace, scopeKeys)
683
+ // §9.1 B: `operationScoped` is a claim Memory can check and acts on: every
684
+ // dotted action's grant names its operation, so a job may call a direct read.
685
+ if (connector.operationScoped === true) {
686
+ const dotted = [...reads.values()].flatMap((read) => read.grants).filter((grant) => grant.action.includes("."))
687
+ if (dotted.length === 0) fail("connector.operationScoped is true, but no read declares a dotted action with an operation resource")
688
+ for (const grant of dotted) if (grant.resource === "*") fail(`connector.operationScoped is true, so ${grant.action} must name {account}:<operation>, not "*"`)
689
+ }
690
+ if (connector.billing !== undefined && connector.billing !== null) billing(connector.billing, "connector.billing")
691
+ // §9.4: the hosts a templated `{url}` may point at. A destination is a
692
+ // security decision, so a connector declares its own and nothing else renders.
693
+ const urlHosts = []
694
+ if (connector.urlHosts !== undefined) {
695
+ list(connector.urlHosts, "connector.urlHosts", { max: 8 })
696
+ for (const host of connector.urlHosts) {
697
+ const problem = urlHostProblem(host)
698
+ if (problem) fail(`connector.urlHosts: ${echo(host)} ${problem}`)
699
+ urlHosts.push(host.toLowerCase())
700
+ }
701
+ }
702
+ // §9.1 D: a suggestBy read runs only at bind, so its grants must never be a
703
+ // job-bearing grant: no identity, no identityRead, and no declared read.
704
+ const suggest = (Array.isArray(connector.scope) ? connector.scope : []).flatMap((key) => (Array.isArray(key?.suggestBy?.grants) ? key.suggestBy.grants : [])).map((grant) => grant.action)
705
+ const bearing = new Set([connector.identity, connector.identityRead, ...(Array.isArray(connector.reads) ? connector.reads : [])]
706
+ .flatMap((block) => (Array.isArray(block?.grants) ? block.grants : []))
707
+ .map((grant) => grant.action))
708
+ for (const action of new Set(suggest)) if (bearing.has(action)) fail(`${action} is a suggestBy grant and also a job-bearing grant: suggestBy runs only at bind, so its grants must not appear in an identity, identityRead or read (§9.1 D)`)
709
+ return { identity: connector.identity, identityRead: connector.identityRead, scopeKeys, reads, suggest: new Set(suggest), urlHosts }
710
+ }
711
+
712
+ /** §9.2: an identity answers the account and the owner, and nothing else. */
713
+ function checkIdentity(identity, namespace, where, { sourceLevel }) {
714
+ object(identity, where)
715
+ onlyV2(identity, ["method", "input", "grants", "account", "owner"], where)
716
+ if (sourceLevel) {
717
+ if (identity.method !== "events_list") fail(`${where}: method must be events_list: a source's identity is its limit:0 call (§9.2)`)
718
+ if (identity.input !== undefined) {
719
+ object(identity.input, `${where}: input`)
720
+ for (const key of Object.keys(identity.input)) if (!["source", "account", "limit"].includes(key)) fail(`${where}: input may name only source, account and limit`)
721
+ if (identity.input.limit !== 0) fail(`${where}: input.limit must be 0: the identity is the owner-only call, and any other limit reads events`)
722
+ }
723
+ if (Object.keys(identity.input ?? {}).length === 0) fail(`${where}: input must name the source and limit 0`)
724
+ } else {
725
+ if (typeof identity.method !== "string" || identity.method === "events_list") fail(`${where}: method must name the tools RPC read that answers the account (§9.2)`)
726
+ readName(identity.method, `${where}: method`)
727
+ }
728
+ connectorGrants(identity.grants, namespace, `${where}: grants`)
729
+ if (typeof identity.account !== "string" || !identity.account.startsWith("$.")) fail(`${where}: account must be a JSONPath starting $.`)
730
+ object(identity.owner, `${where}: owner`)
731
+ only(identity.owner, ["id", "label"], `${where}: owner`)
732
+ for (const key of ["id", "label"]) if (typeof identity.owner[key] !== "string" || !identity.owner[key].startsWith("$.")) fail(`${where}: owner.${key} must be a JSONPath starting $.`)
733
+ }
734
+
735
+ /** A read's method name: the verb allowlist, and no write verb anywhere (§9.1 A). */
736
+ function readName(name, where) {
737
+ if (typeof name !== "string" || name.length === 0 || name.length > 120) fail(`${where} must be a name of at most 120 characters`)
738
+ const write = writeToken(name)
739
+ if (write) fail(`${where}: ${writeReason(write)}`)
740
+ if (!tokens(name).some((token) => READ_VERBS.includes(token))) fail(`${where}: "${echo(name)}" has no read verb (${READ_VERBS.join(", ")})`)
741
+ }
742
+
743
+ /**
744
+ * §9.1 C: a scope key is what the person confirms. `suggestBy` runs only at
745
+ * bind, so its grants are checked like any other read's and kept out of jobs.
746
+ */
747
+ function checkScope(scope, namespace, where) {
748
+ if (!Array.isArray(scope)) fail(`${where} must be a list, empty when none`)
749
+ list(scope, where, { max: MAX_SCOPE_KEYS })
750
+ const keys = new Set()
751
+ for (const [index, entry] of scope.entries()) {
752
+ const at = `${where}[${index}]`
753
+ object(entry, at)
754
+ onlyV2(entry, ["key", "title", "kind", "pattern", "max", "required", "suggest", "suggestBy"], at)
755
+ const key = pattern(entry.key, /^[a-z][a-z0-9_]{0,31}$/, `${at}.key`)
756
+ if (keys.has(key)) fail(`${where}: scope key ${key} is listed twice`)
757
+ keys.add(key)
758
+ if (entry.title !== undefined) text(entry.title, `${at}.title`, { max: 60 })
759
+ if (entry.kind !== "ids") fail(`${at}.kind must be "ids"`)
760
+ if (typeof entry.pattern !== "string" || entry.pattern.length === 0 || entry.pattern.length > 120) fail(`${at}.pattern must be a regular expression of at most 120 characters`)
761
+ try {
762
+ new RegExp(entry.pattern, "u")
763
+ } catch {
764
+ fail(`${at}.pattern is not a valid regular expression`)
765
+ }
766
+ integer(entry.max, `${at}.max`, { min: 1, max: 64 })
767
+ bool(entry.required, `${at}.required`)
768
+ if (entry.suggest !== undefined) bool(entry.suggest, `${at}.suggest`)
769
+ if (entry.suggest === true && entry.suggestBy === undefined) fail(`${at} claims suggest: true but declares no suggestBy, so Memory has nothing to call`)
770
+ if (entry.suggestBy !== undefined) {
771
+ object(entry.suggestBy, `${at}.suggestBy`)
772
+ onlyV2(entry.suggestBy, ["method", "input", "grants", "ids", "labels"], `${at}.suggestBy`)
773
+ readName(entry.suggestBy.method, `${at}.suggestBy.method`)
774
+ if (entry.suggestBy.input !== undefined) object(entry.suggestBy.input, `${at}.suggestBy.input`)
775
+ connectorGrants(entry.suggestBy.grants, namespace, `${at}.suggestBy: grants`)
776
+ for (const field of ["ids", "labels"]) {
777
+ if (entry.suggestBy[field] !== undefined && (typeof entry.suggestBy[field] !== "string" || !entry.suggestBy[field].startsWith("$."))) fail(`${at}.suggestBy.${field} must be a JSONPath starting $.`)
778
+ }
779
+ }
780
+ }
781
+ return keys
782
+ }
783
+
784
+ /** §9.1 B and C: each declared read, its grants, and the scope inputs that pin it. */
785
+ function checkReads(reads, namespace, scopeKeys) {
786
+ const byMethod = new Map()
787
+ if (reads === undefined) return byMethod
788
+ list(reads, "connector.reads", { max: MAX_READS })
789
+ for (const [index, read] of reads.entries()) {
790
+ const at = `connector.reads[${index}]`
791
+ object(read, at)
792
+ onlyV2(read, ["method", "input", "grants", "scopeInputs", "kinds", "cursor", "billing"], at)
793
+ readName(read.method, `${at}.method`)
794
+ if (byMethod.has(read.method)) fail(`${at}.method ${echo(read.method)} is declared twice`)
795
+ if (read.input !== undefined) {
796
+ object(read.input, `${at}.input`)
797
+ if (Buffer.byteLength(canonicalJSON(read.input)) > MAX_INPUT_BYTES) fail(`${at}: input is larger than ${MAX_INPUT_BYTES} bytes`)
798
+ }
799
+ connectorGrants(read.grants, namespace, `${at}: grants`)
800
+ checkScopeInputs(read.scopeInputs, `${at}.scopeInputs`, scopeKeys)
801
+ if (read.kinds !== undefined) {
802
+ list(read.kinds, `${at}.kinds`, { min: 1, max: EVENT_KINDS.length })
803
+ if (!read.kinds.every((kind) => EVENT_KINDS.includes(kind))) fail(`${at}.kinds must be names from ${EVENT_KINDS.join(", ")}`)
804
+ }
805
+ if (read.cursor !== undefined) text(read.cursor, `${at}.cursor`, { max: 60 })
806
+ if (read.billing !== undefined && read.billing !== null) billing(read.billing, `${at}.billing`)
807
+ byMethod.set(read.method, read)
808
+ }
809
+ return byMethod
810
+ }
811
+
812
+ /**
813
+ * §9.1 C, as the kit checks it: a read is pinned to the confirmed scope by at
814
+ * least one binding-key input; a `perUnit` input takes its value from the event
815
+ * itself, and every `perUnit` of one read shares one `bind`; a `thread_ts`
816
+ * needs its `thread_channel` on the same bind, so a thread's channel is what
817
+ * keeps it inside the confirmed scope.
818
+ */
819
+ function checkScopeInputs(inputs, where, scopeKeys) {
820
+ if (inputs === undefined) fail(`${where} is missing: a read with no scope input is unscoped and not grantable`)
821
+ object(inputs, where)
822
+ if (Object.keys(inputs).length === 0) fail(`${where} is empty: a read with no scope input is unscoped and not grantable`)
823
+ let bound = 0
824
+ const binds = new Set()
825
+ const perUnit = []
826
+ for (const [field, value] of Object.entries(inputs)) {
827
+ if (typeof value === "string") {
828
+ if (!scopeKeys.has(value)) fail(`${where}.${field} names the scope key "${echo(value)}", which the connector's scope does not declare`)
829
+ bound += 1
830
+ continue
831
+ }
832
+ object(value, `${where}.${field}`)
833
+ onlyV2(value, ["perUnit", "bind"], `${where}.${field}`)
834
+ if (!PER_UNIT_FIELDS.includes(value.perUnit)) fail(`${where}.${field}: perUnit must be one of ${PER_UNIT_FIELDS.join(", ")} (a field of the event shape)`)
835
+ if (typeof value.bind !== "string" || !scopeKeys.has(value.bind)) fail(`${where}.${field}: perUnit needs bind to name a declared scope key, so the id stays inside the confirmed scope`)
836
+ binds.add(value.bind)
837
+ perUnit.push([field, value])
838
+ }
839
+ // §9.1 C: external_id is a per-unit value like any other, but it names no
840
+ // conversation: a read pinned only by it is pinned by nothing.
841
+ if (perUnit.length > 0 && perUnit.every(([, value]) => value.perUnit === "external_id")) fail(`${where} is pinned only by external_id, which names no conversation: a read needs a confirmed scope key (§9.1 C)`)
842
+ const ts = perUnit.find(([, value]) => value.perUnit === "thread_ts")
843
+ if (ts && !perUnit.some(([, value]) => value.perUnit === "thread_channel" && value.bind === ts[1].bind)) {
844
+ fail(`${where}.${ts[0]}: a thread_ts needs a thread_channel input on the same bind, so the thread's channel is pinned to the confirmed scope`)
845
+ }
846
+ if (binds.size > 1) fail(`${where} binds per-unit inputs to ${[...binds].join(", ")}: they must all name one scope key`)
847
+ if (bound === 0 && binds.size === 0) fail(`${where} pins no binding-key input, so the read is not scoped to what the person confirmed`)
848
+ if (bound > 0 && binds.size > 0) {
849
+ for (const key of binds) {
850
+ if (!Object.values(inputs).includes(key)) fail(`${where} pins a per-unit input through the unrelated key ${key}: its bind must be one of this read's binding-key inputs`)
851
+ }
852
+ }
853
+ }
854
+
855
+ /** §9.2: a source's grants are exactly what `events_list` asserts; its identity's are among them. */
856
+ function checkConnectorSource(source, namespace, connector, at) {
857
+ object(source, at)
858
+ onlyV2(source, ["id", "title", "summary", "contract", "input", "kinds", "grants", "identity", "scope", "cadence", "billing", "setupHint"], at)
859
+ const id = pattern(source.id, ID, `${at}.id`)
860
+ const where = `source ${id}`
861
+ text(source.title, `${where}: title`, { max: 60 })
862
+ text(source.summary, `${where}: summary`, { max: 200 })
863
+ if (source.contract !== SOURCE_CONTRACT) fail(`${where}: contract must be ${SOURCE_CONTRACT} (events_list v2)`)
864
+ if (source.input !== undefined) {
865
+ object(source.input, `${where}: input`)
866
+ if (Buffer.byteLength(canonicalJSON(source.input)) > MAX_INPUT_BYTES) fail(`${where}: input is larger than ${MAX_INPUT_BYTES} bytes`)
867
+ }
868
+ list(source.kinds, `${where}: kinds`, { min: 1, max: EVENT_KINDS.length })
869
+ if (!source.kinds.every((kind) => EVENT_KINDS.includes(kind)) || new Set(source.kinds).size !== source.kinds.length) fail(`${where}: kinds must be distinct names from ${EVENT_KINDS.join(", ")}`)
870
+ if (!Array.isArray(source.grants) || source.grants.length === 0) fail(`${where}: grants must list the actions events_list asserts`)
871
+ connectorGrants(source.grants, namespace, `${where}: grants`)
872
+ if (source.identity !== undefined) {
873
+ checkIdentity(source.identity, namespace, `${where}: identity`, { sourceLevel: true })
874
+ }
875
+ // §9.1 D: an identity's grants are only what `limit: 0` asserts, and they must
876
+ // be among the source's — that list is what a job's session allows for it.
877
+ const identity = source.identity ?? connector.identity
878
+ if (identity) {
879
+ const listed = new Set(source.grants.map((grant) => `${grant.action}\u0000${grant.resource}`))
880
+ for (const grant of identity.grants) {
881
+ if (!listed.has(`${grant.action}\u0000${grant.resource}`)) fail(`${where}: identity grants ${grant.action} on ${grant.resource}, which ${where}: grants does not list — an identity's grants must be among the source's (§9.1 D)`)
882
+ }
883
+ }
884
+ if (source.scope !== undefined) {
885
+ list(source.scope, `${where}: scope`, { max: MAX_SCOPE_KEYS })
886
+ const keys = new Set()
887
+ for (const [index, item] of source.scope.entries()) {
888
+ const at2 = `${where}: scope[${index}]`
889
+ object(item, at2)
890
+ onlyV2(item, ["key", "title", "kind", "pattern", "max", "required", "suggest"], at2)
891
+ const key = pattern(item.key, /^[a-z][a-z0-9_]{0,31}$/, `${at2}.key`)
892
+ if (keys.has(key)) fail(`${where}: scope key ${key} is listed twice`)
893
+ keys.add(key)
894
+ if (!connector.scopeKeys.has(key)) fail(`${at2} names ${key}, which the connector's scope does not declare`)
895
+ }
896
+ }
897
+ if (source.cadence !== undefined) {
898
+ object(source.cadence, `${where}: cadence`)
899
+ only(source.cadence, ["everyMinutes"], `${where}: cadence`)
900
+ // Memory clamps it to at least 15 (120 when billed) at use; here it is only a number.
901
+ integer(source.cadence.everyMinutes, `${where}: cadence.everyMinutes`, { min: 1, max: 10_080 })
902
+ }
903
+ if (source.billing !== undefined && source.billing !== null) billing(source.billing, `${where}: billing`)
904
+ if (source.setupHint !== undefined) text(source.setupHint, `${where}: setupHint`, { max: 300, empty: true })
905
+ return id
906
+ }
907
+
908
+ function billing(value, where) {
909
+ object(value, where)
910
+ only(value, ["unit", "note"], where)
911
+ if (value.unit !== "call") fail(`${where}.unit must be "call"`)
912
+ if (value.note !== undefined) text(value.note, `${where}.note`, { max: 200 })
913
+ }
914
+
915
+ /**
916
+ * §9.4: a template is a draft job a person can instantiate. It carries no
917
+ * grants and no account, so it can never widen what the person confirmed.
918
+ */
919
+ function checkTemplate(template, sourceIds, at, reads = new Map()) {
920
+ object(template, at)
921
+ onlyV2(template, ["id", "title", "summary", "trigger", "extract", "transform", "curate", "outputs", "budget"], at)
922
+ const id = pattern(template.id, ID, `${at}.id`)
923
+ const where = `template ${id}`
924
+ text(template.title, `${where}: title`, { max: 60 })
925
+ text(template.summary, `${where}: summary`, { max: 200 })
926
+ if (template.trigger !== undefined) {
927
+ object(template.trigger, `${where}: trigger`)
928
+ only(template.trigger, ["schedule"], `${where}: trigger`)
929
+ object(template.trigger.schedule, `${where}: trigger.schedule`)
930
+ only(template.trigger.schedule, ["every", "cron", "tz"], `${where}: trigger.schedule`)
931
+ if (template.trigger.schedule.every !== undefined) pattern(template.trigger.schedule.every, /^[0-9]{1,4}(m|h|d)$/, `${where}: trigger.schedule.every`)
932
+ if (template.trigger.schedule.cron !== undefined) text(template.trigger.schedule.cron, `${where}: trigger.schedule.cron`, { max: 120 })
933
+ if (template.trigger.schedule.tz !== undefined) text(template.trigger.schedule.tz, `${where}: trigger.schedule.tz`, { max: 64 })
934
+ }
935
+ const extract = object(template.extract, `${where}: extract`)
936
+ only(extract, ["steps"], `${where}: extract`)
937
+ const steps = list(extract.steps, `${where}: extract.steps`, { min: 1, max: 8 })
938
+ for (const [index, step] of steps.entries()) {
939
+ const at2 = `${where}: extract.steps[${index}]`
940
+ object(step, at2)
941
+ onlyV2(step, ["use", "call", "connector", "source", "for", "with", "paginate", "cursor", "emit"], at2)
942
+ const byUse = step.use !== undefined
943
+ const byCall = typeof step.call === "string"
944
+ if (byUse === byCall) fail(`${at2} needs exactly one of use (events_list) and call`)
945
+ if (byUse && step.use !== "events_list") fail(`${at2}.use must be events_list`)
946
+ if (byCall) readName(step.call, `${at2}.call`)
947
+ pattern(step.connector, /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/, `${at2}.connector`)
948
+ if (typeof step.source !== "string" || !sourceIds.has(step.source)) fail(`${at2}.source must name one of this plugin's declared sources`)
949
+ if (step.for !== undefined && step.for !== "thread" && step.for !== "unit") fail(`${at2}.for must be "thread" or "unit"`)
950
+ if (step.with !== undefined) {
951
+ object(step.with, `${at2}.with`)
952
+ // §9.1 C: the read pins these itself, from the person's confirmed scope.
953
+ // A template that set one would replace the pin, so it may not.
954
+ const pinned = new Set(Object.keys(byCall ? reads.get(step.call)?.scopeInputs ?? {} : {}))
955
+ for (const key of Object.keys(step.with)) {
956
+ if (pinned.has(key)) fail(`${at2}.with may not set ${echo(key)}: the read pins it from the person's confirmed scope, and a template cannot replace that (§9.1 C)`)
957
+ }
958
+ // §2.2: a step's inputs are binding values only, never an event's text.
959
+ for (const match of JSON.stringify(step.with).matchAll(/\{\{([^}]+)\}\}/g)) {
960
+ const ref = match[1].trim()
961
+ if (!/^(account|since|cursor\.[a-z][a-z0-9_]*|scope\.[a-z][a-z0-9_]*)$/.test(ref)) fail(`${at2}.with uses {{${echo(ref)}}}: only binding values are allowed, never item text`)
962
+ }
963
+ }
964
+ }
965
+ if (template.transform !== undefined) {
966
+ object(template.transform, `${where}: transform`)
967
+ only(template.transform, ["into", "map"], `${where}: transform`)
968
+ if (template.transform.into !== "events" && template.transform.into !== "documents") fail(`${where}: transform.into must be events or documents`)
969
+ if (template.transform.map !== undefined) object(template.transform.map, `${where}: transform.map`)
970
+ }
971
+ const curate = object(template.curate, `${where}: curate`)
972
+ only(curate, ["stages"], `${where}: curate`)
973
+ const stages = list(curate.stages, `${where}: curate.stages`, { min: 1, max: 8 })
974
+ const written = []
975
+ for (const [index, stage] of stages.entries()) {
976
+ const at2 = `${where}: curate.stages[${index}]`
977
+ object(stage, at2)
978
+ onlyV2(stage, ["engine", "select", "into", "heading", "line", "max", "hints", "outputs"], at2)
979
+ if (stage.engine !== "render" && stage.engine !== "extract" && stage.engine !== "synthesize") fail(`${at2}.engine must be render, extract or synthesize`)
980
+ if (stage.engine === "render") {
981
+ const into = stage.into
982
+ const isSection = typeof into === "string" && /^section:[A-Z][A-Za-z0-9 ]{0,39}$/.test(into)
983
+ if (!isSection && into !== "journal" && into !== "timeline") fail(`${at2}.into must be journal, timeline or section:<Heading>`)
984
+ if (typeof stage.line !== "string" || stage.line.length === 0 || stage.line.length > 400) fail(`${at2}.line must be 1 to 400 characters`)
985
+ renderLine(stage.line, `${at2}.line`)
986
+ integer(stage.max, `${at2}.max`, { min: 1, max: MAX_RENDER_ITEMS })
987
+ if (stage.heading !== undefined) text(stage.heading, `${at2}.heading`, { max: 60 })
988
+ if (stage.outputs !== undefined) fail(`${at2}: a render stage's output is its into`)
989
+ written.push(into)
990
+ }
991
+ if (stage.engine === "extract") {
992
+ const outputs = list(stage.outputs, `${at2}.outputs`, { min: 1, max: 12 })
993
+ for (const output of outputs) {
994
+ if (!output.startsWith("proposal:") || !PROPOSAL_OUTPUTS.includes(output.slice("proposal:".length))) fail(`${at2}.outputs names ${echo(output)}, which is not a proposal kind`)
995
+ written.push(output)
996
+ }
997
+ if (stage.hints !== undefined) text(stage.hints, `${at2}.hints`, { max: MAX_HINTS })
998
+ if (stage.into !== undefined || stage.line !== undefined) fail(`${at2}: an extract stage takes outputs and hints, not into or line`)
999
+ }
1000
+ if (stage.engine === "synthesize") {
1001
+ if (typeof stage.into !== "string" || !/^section:[A-Z][A-Za-z0-9 ]{0,39}$/.test(stage.into)) fail(`${at2}.into must be section:<Heading>`)
1002
+ integer(stage.max, `${at2}.max`, { min: 1, max: MAX_RENDER_ITEMS })
1003
+ written.push(stage.into)
1004
+ }
1005
+ if (stage.select !== undefined) checkSelector(stage.select, sourceIds, `${at2}.select`)
1006
+ }
1007
+ const outputs = list(template.outputs, `${where}: outputs`, { min: 1, max: 12 })
1008
+ if (new Set(outputs).size !== outputs.length) fail(`${where}: an output is listed twice`)
1009
+ for (const output of outputs) {
1010
+ if (output === "journal" || output === "timeline") continue
1011
+ if (typeof output === "string" && /^section:[A-Z][A-Za-z0-9 ]{0,39}$/.test(output)) continue
1012
+ if (typeof output === "string" && output.startsWith("proposal:") && PROPOSAL_OUTPUTS.includes(output.slice("proposal:".length))) continue
1013
+ fail(`${where}: outputs names ${echo(output)}, which is not an output kind`)
1014
+ }
1015
+ // §9.1 D: a template's outputs cover every stage's, or a stage would write what
1016
+ // the person never saw in the draft.
1017
+ for (const output of new Set(written)) if (!outputs.includes(output)) fail(`${where}: outputs must include ${echo(output)}, which a stage writes`)
1018
+ if (template.budget !== undefined) {
1019
+ object(template.budget, `${where}: budget`)
1020
+ only(template.budget, ["tokensPerRun"], `${where}: budget`)
1021
+ integer(template.budget.tokensPerRun, `${where}: budget.tokensPerRun`, { min: 1000, max: MAX_TOKENS_PER_RUN })
1022
+ }
1023
+ return id
1024
+ }
1025
+
1026
+ /** The selector a stage reads units with (§9.4). */
1027
+ function checkSelector(select, sourceIds, where) {
1028
+ object(select, where)
1029
+ only(select, ["sources", "kinds", "labels", "unit", "participant", "latest", "window", "minEvents", "maxUnits"], where)
1030
+ if (select.sources !== undefined) {
1031
+ list(select.sources, `${where}.sources`, { min: 1, max: MAX_SOURCES })
1032
+ for (const name of select.sources) if (typeof name !== "string" || !sourceIds.has(name)) fail(`${where}.sources may name only this plugin's own sources`)
1033
+ }
1034
+ if (select.kinds !== undefined) {
1035
+ list(select.kinds, `${where}.kinds`, { min: 1, max: EVENT_KINDS.length })
1036
+ if (!select.kinds.every((kind) => EVENT_KINDS.includes(kind))) fail(`${where}.kinds must be event kinds`)
1037
+ }
1038
+ if (select.labels !== undefined) {
1039
+ list(select.labels, `${where}.labels`, { min: 1, max: 16 })
1040
+ for (const label of select.labels) pattern(label, LABEL, `${where}: a label`)
1041
+ }
1042
+ if (select.unit !== undefined && !UNITS.includes(select.unit)) fail(`${where}.unit must be event or thread`)
1043
+ if (select.participant !== undefined && select.participant !== "owner") fail(`${where}.participant may only be "owner"`)
1044
+ if (select.latest !== undefined) {
1045
+ object(select.latest, `${where}.latest`)
1046
+ only(select.latest, ["per"], `${where}.latest`)
1047
+ pattern(select.latest.per, LABEL_PREFIX, `${where}.latest.per`)
1048
+ }
1049
+ if (select.window !== undefined && !WINDOWS.includes(select.window)) fail(`${where}.window must be ${WINDOWS.join(", ")}`)
1050
+ if (select.minEvents !== undefined) integer(select.minEvents, `${where}.minEvents`, { min: 1, max: 1000 })
1051
+ if (select.maxUnits !== undefined) integer(select.maxUnits, `${where}.maxUnits`, { min: 1, max: 200 })
1052
+ }
1053
+
1054
+ // ---------------------------------------------------------------------------
1055
+ // What a job reads: the identity, the declared reads, the templates, and the
1056
+ // exact grant set of §9.1 D
1057
+
1058
+ /** The identity a source reads its account and owner with: its own, else the connector's (§9.2). */
1059
+ export function identityFor(manifest, sourceId) {
1060
+ const source = (manifest?.sources ?? []).find((entry) => entry?.id === sourceId) ?? null
1061
+ if (!source) return null
1062
+ return source.identity ?? manifest?.connector?.identity ?? null
1063
+ }
1064
+
1065
+ /** Every read the connector declares, by method. */
1066
+ export function declaredReads(manifest) {
1067
+ return Array.isArray(manifest?.connector?.reads) ? manifest.connector.reads : []
1068
+ }
1069
+
1070
+ /** One declared read, or null when the connector declares none with that method. */
1071
+ export function readByMethod(manifest, method) {
1072
+ return declaredReads(manifest).find((read) => read?.method === method) ?? null
1073
+ }
1074
+
1075
+ /** The templates a manifest ships (§9.4). */
1076
+ export function templatesOf(manifest) {
1077
+ return Array.isArray(manifest?.templates) ? manifest.templates : []
1078
+ }
1079
+
1080
+ /** The template with this id, or null. */
1081
+ export function templateById(manifest, id) {
1082
+ return templatesOf(manifest).find((template) => template?.id === id) ?? null
1083
+ }
1084
+
1085
+ /** An account name a grant's resource may bind to. A wildcard, separator or empty is never one. */
1086
+ export function accountName(value) {
1087
+ if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._@%+-]{0,127}$/.test(value)) throw new TypeError("an account must be a plain account name")
1088
+ return value
1089
+ }
1090
+
1091
+ /**
1092
+ * The exact grant set a running job holds (DESIGN §9.1 D): every grant of the
1093
+ * job's source, every grant of each read its steps name, and every grant of the
1094
+ * identity's owner-only call, with `{account}` bound.
1095
+ *
1096
+ * `suggestBy` is not in it, and can never be: it runs only at bind, in the probe
1097
+ * session. A read the job's steps do not name contributes no grant.
1098
+ *
1099
+ * @param {any} manifest
1100
+ * @param {{source: string, account: string, steps?: Array<{use?: string, call?: string}>}} input
1101
+ * @returns {Array<{action: string, resource: string}>}
1102
+ */
1103
+ export function jobGrants(manifest, { source: sourceId, account, steps = [] }) {
1104
+ const source = (manifest?.sources ?? []).find((entry) => entry?.id === sourceId)
1105
+ if (!source) throw new TypeError(`the declaration has no source ${String(sourceId)}`)
1106
+ const bound = accountName(account)
1107
+ const out = new Map()
1108
+ const add = (grant) => {
1109
+ if (!grant || typeof grant.action !== "string" || typeof grant.resource !== "string") return
1110
+ const resource = grant.resource.replaceAll("{account}", bound)
1111
+ out.set(`${grant.action}\u0000${resource}`, { action: grant.action, resource })
1112
+ }
1113
+ for (const grant of Array.isArray(source.grants) ? source.grants : []) add(grant)
1114
+ for (const step of Array.isArray(steps) ? steps : []) {
1115
+ if (typeof step?.call !== "string") continue
1116
+ const read = readByMethod(manifest, step.call)
1117
+ if (!read) throw new TypeError(`the job's step calls ${String(step.call)}, which the declaration does not declare`)
1118
+ for (const grant of Array.isArray(read.grants) ? read.grants : []) add(grant)
1119
+ }
1120
+ const identity = identityFor(manifest, sourceId)
1121
+ for (const grant of Array.isArray(identity?.grants) ? identity.grants : []) add(grant)
1122
+ return [...out.values()]
1123
+ }
1124
+
1125
+
1126
+ /**
1127
+ * RFC 8785 canonical JSON for the values JSON.parse gives: object keys sorted
1128
+ * by UTF-16 code units, numbers and strings as ECMAScript serialises them.
1129
+ *
1130
+ * @param {unknown} value
1131
+ * @returns {string}
1132
+ */
1133
+ export function canonicalJSON(value, depth = 0) {
1134
+ if (depth > MAX_CANONICAL_DEPTH) throw new TypeError(`canonical JSON is nested deeper than ${MAX_CANONICAL_DEPTH} levels`)
1135
+ if (value === null || typeof value === "boolean") return JSON.stringify(value)
1136
+ if (typeof value === "number") {
1137
+ if (!Number.isFinite(value)) throw new TypeError("canonical JSON needs finite numbers")
1138
+ return JSON.stringify(value)
1139
+ }
1140
+ if (typeof value === "string") return JSON.stringify(value)
1141
+ if (Array.isArray(value)) return `[${value.map((item) => canonicalJSON(item, depth + 1)).join(",")}]`
1142
+ if (typeof value === "object") {
1143
+ const keys = Object.keys(value).sort()
1144
+ return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJSON(value[key], depth + 1)}`).join(",")}}`
1145
+ }
1146
+ throw new TypeError(`canonical JSON cannot hold a ${typeof value}`)
1147
+ }
1148
+
1149
+ /** The digest Memory pins a declaration by: `sha256:` and the hex of its canonical JSON. */
1150
+ export function manifestDigest(value) {
1151
+ return `sha256:${createHash("sha256").update(canonicalJSON(value), "utf8").digest("hex")}`
1152
+ }
1153
+
1154
+ /**
1155
+ * A `sources` descriptor's hash: the contract's own (`descriptorHash` in the
1156
+ * source-contract package), which is `manifestDigest` over the same canonical
1157
+ * JSON. Every consumer computes it the same way, so a grant's hash means the
1158
+ * same thing in Memory, jelly and a plugin's CI.
1159
+ */
1160
+ export function descriptorHash(value) {
1161
+ return manifestDigest(value)
1162
+ }