@joe-broadhead/opencode-mem 0.9.14 → 0.11.3

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 (143) hide show
  1. package/CHANGELOG.md +1856 -0
  2. package/README.md +15 -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 +8921 -1070
  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 +88 -7
  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 +74 -23
  104. package/src/tools/held-write.js +46 -19
  105. package/src/tools/index.js +28 -0
  106. package/src/tools/ingest.js +38 -2
  107. package/src/tools/memory.js +56 -25
  108. package/src/tools/page.js +212 -95
  109. package/src/tools/recall.js +218 -4
  110. package/src/tools/share.js +42 -3
  111. package/src/tools/shared.js +84 -6
  112. package/src/tools/space-lifecycle.js +278 -0
  113. package/src/tools/spaces.js +381 -30
  114. package/src/tools/status.js +9 -2
  115. package/src/tools/wiki.js +231 -116
  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 +1082 -23
  134. package/src/views/inbox-bytes.js +103 -0
  135. package/src/views/profile.js +31 -0
  136. package/src/views/receipt.js +26 -1
  137. package/src/views/records-reads.js +520 -41
  138. package/src/views/rpc.js +153 -25
  139. package/src/views/shape.js +8 -5
  140. package/src/views/write-state.js +89 -0
  141. package/src/wiki-ingest.js +215 -0
  142. package/src/wiki-state.js +228 -0
  143. package/views/pages.html +2 -2
@@ -0,0 +1,103 @@
1
+ import { PAGE_PATH } from "./tools/records-kit.js"
2
+
3
+ /**
4
+ * A page's outlinks, read once: the ONE rule both of Memory's page reads use —
5
+ * the `mem_page` read (`src/tools/page.js`) and Jelly's page view
6
+ * (`src/views/records-reads.js`). A second copy of it is a second answer.
7
+ *
8
+ * A `[[path]]` link is not a page, and a mark saying so ("no page yet", or
9
+ * `exists: false`) is a claim about what the space holds. It may be made only
10
+ * where the absence is knowable to this reader:
11
+ *
12
+ * - the reader holds space-level read in the page's space (a role: viewer or
13
+ * above), not only a page grant: `records.get` puts a path in `missing` when
14
+ * it does not exist **or** when the caller cannot read it
15
+ * (`records/src/store.js` get, `canRead`), so for a grant-only reader a
16
+ * page it cannot see is indistinguishable from one that is not there; and
17
+ * - the lookup succeeded, and the page's own space could be read.
18
+ *
19
+ * Every other answer is `missing: null`, "unknown", which no caller may read as
20
+ * absence. A target left out of the lookup (past the cap, or a `rec_…` id) is
21
+ * never in the `missing` set either: the caller omits the mark for it rather
22
+ * than making one up.
23
+ */
24
+
25
+ /** The most links one lookup checks: `records.get` takes 50 ids and paths together. */
26
+ export const LINK_EXISTS_MAX = 50
27
+
28
+ /** A link that names a record id rather than a page path. */
29
+ const LINK_RECORD_ID = /^rec_/
30
+
31
+ /**
32
+ * The roles that carry space-level read: control's own list of a space's
33
+ * roles (`control/src/policy.js:17`, `SPACE_ROLES`). A role outside it is not
34
+ * space-level read, however plausible it looks.
35
+ */
36
+ const SPACE_READ_ROLES = Object.freeze(["viewer", "editor", "admin", "owner"])
37
+
38
+ /**
39
+ * Whether this reader holds space-level read rather than only a page grant.
40
+ * The one test of it: every claim about absence rests on this answer.
41
+ *
42
+ * Fail closed: only a role control itself names counts. Production lists a
43
+ * space reached only through a page or folder grant with NO role — control
44
+ * answers `role: permission.role`, null without a membership
45
+ * (`control/src/service/shared.js:476-487`), the gateway passes
46
+ * `space.role ?? null` (`deploy/auth/http/context.mjs:199-204`), and the
47
+ * plugin makes that `""` (`src/spaces.js:755`) — so an empty, null, "grant"
48
+ * or unknown role is not space-level read.
49
+ *
50
+ * @param {{ role?: string, space_kind?: string } | null | undefined} spaceContext
51
+ * the resolved space: control's role for the caller, its kind, or the
52
+ * `granted` context a space reached only through a page grant resolves to.
53
+ * Absent in local direct mode, where the store is the person's own and there
54
+ * is no control plane to name a role.
55
+ * @param {{ granted?: boolean }} [options] `granted: true` when the caller
56
+ * named a space that control refuses to resolve (a page grant got them in).
57
+ */
58
+ export function holdsSpaceRead(spaceContext, { granted = false } = {}) {
59
+ // A space reached through a grant is never space-level read, whatever role
60
+ // came with it.
61
+ if (granted || spaceContext?.space_kind === "granted") return false
62
+ if (!spaceContext) return true
63
+ return SPACE_READ_ROLES.includes(String(spaceContext.role ?? "").trim().toLowerCase())
64
+ }
65
+
66
+ /**
67
+ * One records lookup for a page's links.
68
+ *
69
+ * @param {{
70
+ * links: unknown,
71
+ * path?: string,
72
+ * spaceRead: boolean,
73
+ * call: (method: string, body: unknown) => Promise<any>,
74
+ * cap?: number,
75
+ * onError?: (error: unknown) => void,
76
+ * }} input
77
+ * `links`: the page's stored links; `path`: the page's own path, never
78
+ * looked up; `spaceRead`: `holdsSpaceRead`'s answer; `call`: the caller's
79
+ * records read; `onError`: told when the lookup fails.
80
+ * @returns {Promise<{ records: any[], missing: Set<string> | null }>}
81
+ * `records`: the targets this reader could read, for their titles;
82
+ * `missing`: the page paths known to name no page, or null when absence is
83
+ * not knowable.
84
+ */
85
+ export async function readOutlinks({ links, path, spaceRead, call, cap = LINK_EXISTS_MAX, onError } = {}) {
86
+ const targets = [...new Set((Array.isArray(links) ? links : []).map((link) => String(link ?? "").trim()))]
87
+ .filter(Boolean)
88
+ .slice(0, cap)
89
+ const ids = targets.filter((target) => LINK_RECORD_ID.test(target))
90
+ const paths = targets.filter((target) => !LINK_RECORD_ID.test(target) && PAGE_PATH.test(target) && target !== String(path ?? ""))
91
+ if (ids.length === 0 && paths.length === 0) return { records: [], missing: new Set() }
92
+ let answer
93
+ try {
94
+ answer = await call("records.get", { ...(ids.length > 0 ? { ids } : {}), ...(paths.length > 0 ? { paths } : {}) })
95
+ } catch (error) {
96
+ onError?.(error)
97
+ return { records: [], missing: null }
98
+ }
99
+ const records = Array.isArray(answer?.records) ? answer.records : []
100
+ if (!spaceRead) return { records, missing: null }
101
+ const absent = new Set((Array.isArray(answer?.missing) ? answer.missing : []).map((target) => String(target)))
102
+ return { records, missing: new Set(paths.filter((target) => absent.has(target))) }
103
+ }
@@ -0,0 +1,151 @@
1
+ /**
2
+ * The reservation proof a verified host action carries to the control plane
3
+ * (docs/design/p2-control.md, revision 1).
4
+ *
5
+ * A control-plane act is G2-P — a person only (DESIGN-CRUD §3.3): `share.transfer`,
6
+ * `share.decide` and `space.visibility`. Records verifies the
7
+ * host's `jelly-act+jwt` and spends it at the grant door, so records is the one
8
+ * service that can say "this person pressed this act, once". This module is how
9
+ * it says so to control:
10
+ *
11
+ * p2r1.<base64url claims>.<base64url HMAC-SHA256 over "p2r1.claims">
12
+ * claims {v, act, in, user, host, jti, iat, exp}
13
+ *
14
+ * It is **not** a second grant. A reservation authorises nothing on its own: it
15
+ * names what records has already spent, and the service that applies the act
16
+ * spends it again, in its own ledger and its own transaction, so one press is
17
+ * one change. Its life is at most a minute.
18
+ *
19
+ * Four copies carry this file, byte for byte identical (`npm run check:copies`):
20
+ * the plugin, records, the gateway and control. It is self-contained —
21
+ * `node:crypto` only, no I/O, no service imports. Records signs; the gateway and
22
+ * control verify; the plugin only carries what records answered, and never
23
+ * verifies or mints one.
24
+ *
25
+ * Nothing about a proof is logged: a verifier that explains which byte failed
26
+ * tells a caller which byte to change.
27
+ */
28
+ import { createHash, createHmac, timingSafeEqual } from "node:crypto"
29
+
30
+ /** The token's version marker, so a format change is a new prefix, never a guess. */
31
+ export const P2_PREFIX = "p2r1"
32
+ /** A proof is small: three parts, one of them a 32-byte MAC. */
33
+ export const MAX_P2_BYTES = 4096
34
+ /** The claims' own ceiling (docs/design/p2-control.md §2). */
35
+ export const MAX_ACT_BYTES = 128
36
+ export const MAX_USER_BYTES = 200
37
+ export const MAX_HOST_BYTES = 128
38
+ export const MAX_JTI_BYTES = 128
39
+ /** A reservation's life, and the skew allowed each way. */
40
+ export const MAX_LIFETIME_SECONDS = 60
41
+ export const CLOCK_SKEW_SECONDS = 5
42
+ /** The shortest shared key this accepts: a 256-bit secret. */
43
+ export const MIN_KEY_BYTES = 32
44
+
45
+ const BASE64URL = /^[A-Za-z0-9_-]+$/
46
+ const DIGEST = /^[A-Za-z0-9_-]{43}$/
47
+ const JTI = /^[A-Za-z0-9_-]{22,128}$/
48
+
49
+ /**
50
+ * The shared key, from the setting: a 32-byte-or-longer secret, or null. An
51
+ * absent or short key turns the whole path off (records issues nothing, the
52
+ * gateway and control refuse everything that carries a proof).
53
+ *
54
+ * @param {unknown} value
55
+ * @returns {Buffer | null}
56
+ */
57
+ export function readP2Key(value) {
58
+ if (typeof value !== "string") return null
59
+ const key = Buffer.from(value.trim(), "utf8")
60
+ if (key.length < MIN_KEY_BYTES) return null
61
+ return key
62
+ }
63
+
64
+ /**
65
+ * The digest a claim's `in` is: base64url SHA-256 over the **canonical JSON** of
66
+ * the act's input, exactly as the host signed it (`actionInputDigest`, ADR §4.2).
67
+ *
68
+ * A verifier that is not given the canonical bytes cannot compute this value: it
69
+ * is handed the bytes and hashes them, so a caller that sends a non-canonical
70
+ * form fails the digest rather than being re-canonicalised into a match.
71
+ *
72
+ * @param {string | Buffer} bytes
73
+ */
74
+ export function inputDigest(bytes) {
75
+ return createHash("sha256").update(typeof bytes === "string" ? Buffer.from(bytes, "utf8") : bytes).digest("base64url")
76
+ }
77
+
78
+ /** The token's signed half, so a verifier hashes the same bytes the signer did. */
79
+ function macOf(key, body) {
80
+ return createHmac("sha256", key).update(body, "ascii").digest("base64url")
81
+ }
82
+
83
+ /**
84
+ * Issue one reservation: what records spent, for whom, and for how long.
85
+ *
86
+ * @param {{ key: Buffer, act: string, in: string, user: string, host: string, jti: string, now?: number, lifetime?: number }} input
87
+ * @returns {string}
88
+ */
89
+ export function issueReservation({ key, act, in: digest, user, host, jti, now = Math.floor(Date.now() / 1000), lifetime = MAX_LIFETIME_SECONDS } = {}) {
90
+ if (!Buffer.isBuffer(key) || key.length < MIN_KEY_BYTES) throw new TypeError("issueReservation: a shared key of at least 32 bytes is required")
91
+ if (typeof act !== "string" || !act) throw new TypeError("issueReservation: an act is required")
92
+ if (typeof digest !== "string" || !DIGEST.test(digest)) throw new TypeError("issueReservation: the input digest is 43 base64url characters")
93
+ if (typeof user !== "string" || !user) throw new TypeError("issueReservation: the person is required")
94
+ if (typeof host !== "string" || !host) throw new TypeError("issueReservation: the host is required")
95
+ if (typeof jti !== "string" || !JTI.test(jti)) throw new TypeError("issueReservation: the grant's jti is required")
96
+ const seconds = Number.isSafeInteger(lifetime) ? Math.min(Math.max(lifetime, 1), MAX_LIFETIME_SECONDS) : MAX_LIFETIME_SECONDS
97
+ const claims = { v: 1, act, in: digest, user, host, jti, iat: now, exp: now + seconds }
98
+ const body = `${P2_PREFIX}.${Buffer.from(JSON.stringify(claims), "utf8").toString("base64url")}`
99
+ return `${body}.${macOf(key, body)}`
100
+ }
101
+
102
+ /**
103
+ * Verify one reservation proof, and nothing else: the caller still checks that
104
+ * the act, the input and the person are the ones it is acting for.
105
+ *
106
+ * @param {{ token: unknown, key: Buffer | null, now?: number }} input
107
+ * @returns {{ ok: true, claims: object } | { ok: false, code: string, detail: string }}
108
+ */
109
+ export function verifyReservation({ token, key, now = Math.floor(Date.now() / 1000) } = {}) {
110
+ if (!Buffer.isBuffer(key) || key.length < MIN_KEY_BYTES) return refuse("p2_unavailable", "no reservation key is configured")
111
+ if (typeof token !== "string" || !token) return refuse("p2_malformed", "the reservation is not a string")
112
+ if (Buffer.byteLength(token, "utf8") > MAX_P2_BYTES) return refuse("p2_malformed", `the reservation is over ${MAX_P2_BYTES} bytes`)
113
+ const parts = token.split(".")
114
+ if (parts.length !== 3) return refuse("p2_malformed", "the reservation is not three dot-separated parts")
115
+ const [prefix, claimsPart, macPart] = parts
116
+ if (prefix !== P2_PREFIX) return refuse("p2_malformed", "the reservation is not a p2r1 proof")
117
+ if (!BASE64URL.test(claimsPart) || !BASE64URL.test(macPart)) return refuse("p2_malformed", "a reservation part is not base64url")
118
+ if (Buffer.from(claimsPart, "base64url").toString("base64url") !== claimsPart) return refuse("p2_malformed", "a reservation part is not canonical base64url")
119
+ const given = Buffer.from(macPart, "base64url")
120
+ const expected = Buffer.from(macOf(key, `${prefix}.${claimsPart}`), "base64url")
121
+ if (given.length !== expected.length || !timingSafeEqual(given, expected)) return refuse("p2_signature", "the reservation's signature does not verify")
122
+ let claims
123
+ try {
124
+ claims = JSON.parse(Buffer.from(claimsPart, "base64url").toString("utf8"))
125
+ } catch {
126
+ return refuse("p2_malformed", "the claims are not JSON")
127
+ }
128
+ const problem = claimProblem(claims)
129
+ if (problem) return refuse("p2_malformed", problem)
130
+ if (!(claims.exp - claims.iat > 0) || claims.exp - claims.iat > MAX_LIFETIME_SECONDS) return refuse("p2_time", `the lifetime is not 1 to ${MAX_LIFETIME_SECONDS} seconds`)
131
+ if (claims.iat > now + CLOCK_SKEW_SECONDS) return refuse("p2_time", "the reservation is from the future")
132
+ if (now > claims.exp + CLOCK_SKEW_SECONDS) return refuse("p2_expired", "the reservation has expired")
133
+ return { ok: true, claims }
134
+ }
135
+
136
+ function refuse(code, detail) {
137
+ return { ok: false, code, detail }
138
+ }
139
+
140
+ /** Every claim this format requires, with its type and length; null when all are there. */
141
+ function claimProblem(claims) {
142
+ if (!claims || typeof claims !== "object" || Array.isArray(claims)) return "the claims are not an object"
143
+ if (claims.v !== 1) return "the reservation's version is not 1"
144
+ for (const [name, max] of [["act", MAX_ACT_BYTES], ["user", MAX_USER_BYTES], ["host", MAX_HOST_BYTES]]) {
145
+ if (typeof claims[name] !== "string" || !claims[name] || claims[name].length > max) return `${name} is not a string of 1 to ${max} characters`
146
+ }
147
+ if (typeof claims.in !== "string" || !DIGEST.test(claims.in)) return "in is not 43 base64url characters"
148
+ if (typeof claims.jti !== "string" || !JTI.test(claims.jti)) return "jti is not 22 to 128 base64url characters"
149
+ for (const name of ["iat", "exp"]) if (!Number.isSafeInteger(claims[name])) return `${name} is not a whole number of seconds`
150
+ return null
151
+ }
@@ -62,6 +62,25 @@ export const DEFAULT_RULES = Object.freeze([
62
62
  Object.freeze({ action: "session.bind", resource: "*", effect: "ask" }),
63
63
  // Unbinding a source in a shared space: it deletes the team's collected events.
64
64
  Object.freeze({ action: "sources.unbind", resource: "*", effect: "ask" }),
65
+ // A new shared space (G1): the person owns it; nothing is shared until they invite or copy.
66
+ Object.freeze({ action: "space.create", resource: "*", effect: "ask" }),
67
+ // Renaming a shared space (G1): every member sees the new name.
68
+ Object.freeze({ action: "space.rename", resource: "*", effect: "ask" }),
69
+ // Unarchiving a shared space (G1): it comes back online for every member.
70
+ Object.freeze({ action: "space.unarchive", resource: "*", effect: "ask" }),
71
+ // Archiving a shared space (G2, never skipped): it goes offline for every member.
72
+ Object.freeze({ action: "space.archive", resource: "*", effect: "ask" }),
73
+ // Leaving a shared space (G2, never skipped): only an admin can add the person back.
74
+ Object.freeze({ action: "space.leave", resource: "*", effect: "ask" }),
75
+ // Handing a shared space over (G2, never skipped): the person cannot take ownership back.
76
+ Object.freeze({ action: "space.handover", resource: "*", effect: "ask" }),
77
+ // A job run now reads a source and writes memory, so it asks (G1; skipAsks may lift it).
78
+ Object.freeze({ action: "job.run", resource: "*", effect: "ask" }),
79
+ // A resume starts the job reading and writing again, so it asks (G1; skipAsks may lift it).
80
+ Object.freeze({ action: "job.resume", resource: "*", effect: "ask" }),
81
+ // Archiving a job (G2): no setting lifts it; the tool asserts it directly.
82
+ Object.freeze({ action: "job.archive", resource: "*", effect: "ask" }),
83
+
65
84
  ])
66
85
 
67
86
  /**
@@ -70,6 +89,16 @@ export const DEFAULT_RULES = Object.freeze([
70
89
  */
71
90
  export const ASK_ACTIONS = Object.freeze(DEFAULT_RULES.map((rule) => rule.action))
72
91
 
92
+ /**
93
+ * G2 asks (DESIGN-CRUD §3, §8 D3): what cannot be undone or takes the
94
+ * person's access or ownership. Each is committed with the server's preview
95
+ * token, and `skipAsks` never lifts it: the setting does not take these names.
96
+ */
97
+ export const NEVER_SKIPPED = Object.freeze(["space.archive", "space.leave", "space.handover"])
98
+
99
+ /** The asks `skipAsks` may name: every ask but the G2 ones. */
100
+ export const SKIPPABLE_ASK_ACTIONS = Object.freeze(ASK_ACTIONS.filter((action) => !NEVER_SKIPPED.includes(action)))
101
+
73
102
  /**
74
103
  * Whether the person's `skipAsks` setting names `action`. It is the person's
75
104
  * own setting (user-level OpenCode config, or Memory's "Run without asking"
@@ -79,6 +108,7 @@ export const ASK_ACTIONS = Object.freeze(DEFAULT_RULES.map((rule) => rule.action
79
108
  * it still waits in the Inbox.
80
109
  */
81
110
  export function skipsAsk(config, action) {
111
+ if (NEVER_SKIPPED.includes(action)) return false
82
112
  return Array.isArray(config?.skipAsks) && config.skipAsks.includes(action)
83
113
  }
84
114
 
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Memory's descriptor reader: one thin layer over the contract's own
3
+ * `descriptor` module, so the trust rule is the same everywhere.
4
+ *
5
+ * - **The installed package on disk is the trust root.** `readDeclared(dir)`
6
+ * re-reads `<dir>/package.json`, validates its `sources` key and hashes it
7
+ * with `readInstalledDescriptor`; nothing here trusts `describe` or any RPC
8
+ * answer.
9
+ * - **The hash is the contract's**, so a grant stores the same hash every
10
+ * consumer computes; a changed hash re-asks the person.
11
+ * - **`sources` wins.** A package that declares `sources` never has its
12
+ * `memory` key read, and one that declares neither is not a declaration at
13
+ * all.
14
+ */
15
+ import { checkSources, descriptorHash, readInstalledDescriptor, SUPPORTED_CONTRACT_VERSIONS } from "./source-contract/index.js"
16
+
17
+ /** The labels a source row carries: which contract it was read under. */
18
+ export const CONTRACT_LABELS = Object.freeze({
19
+ sources: "sources (contract version 1)",
20
+ memory: "memory (previous)",
21
+ events_list: "events_list (previous)",
22
+ })
23
+
24
+ /** True when a package.json value is a `sources` declaration at all, before it is judged. */
25
+ export function isSourcesKey(value) {
26
+ return value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.contractVersion === "number" && Array.isArray(value.items)
27
+ }
28
+
29
+ /**
30
+ * A plugin's `sources` value, checked and hashed.
31
+ *
32
+ * @param {unknown} value `package.json#sources`
33
+ * @returns {{ ok: true, descriptor: object, hash: string } | { ok: false, problems: string[] }}
34
+ */
35
+ export function readSources(value) {
36
+ if (!isSourcesKey(value)) return { ok: false, problems: ["the package.json sources key is not a descriptor: an object with contractVersion and items is required"] }
37
+ if (!SUPPORTED_CONTRACT_VERSIONS.includes(value.contractVersion)) {
38
+ return { ok: false, problems: [`sources.contractVersion: ${value.contractVersion} is not a contract version Memory reads (${SUPPORTED_CONTRACT_VERSIONS.join(", ")})`] }
39
+ }
40
+ const checked = checkSources(value)
41
+ if (!checked.ok) return { ok: false, problems: checked.problems }
42
+ return { ok: true, descriptor: checked.value, hash: descriptorHash(value) }
43
+ }
44
+
45
+ /**
46
+ * The descriptor of the package installed at `directory`, read from disk,
47
+ * validated and hashed.
48
+ *
49
+ * @param {string} directory the package's own directory
50
+ * @param {{ version?: string }} [options]
51
+ * @returns {{ ok: true, package: string, version: string, descriptor: object, hash: string } | { ok: false, problems: string[] }}
52
+ */
53
+ export function readDeclared(directory, options = {}) {
54
+ let checked
55
+ try {
56
+ checked = readInstalledDescriptor(directory, options)
57
+ } catch (error) {
58
+ return { ok: false, problems: [`the installed package could not be read: ${String(error?.message ?? error).slice(0, 200)}`] }
59
+ }
60
+ if (!checked.ok) return { ok: false, problems: [...checked.problems] }
61
+ return { ok: true, package: checked.value.package, version: checked.value.version, descriptor: checked.value.sources, hash: checked.value.hash }
62
+ }