@joe-broadhead/opencode-mem 0.8.4 → 0.9.0

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 (52) hide show
  1. package/CHANGELOG.md +455 -0
  2. package/README.md +114 -61
  3. package/docs/agent-protocol.md +67 -177
  4. package/package.json +1351 -98
  5. package/skills/mem.pages/SKILL.md +143 -0
  6. package/skills/mem.sharing/SKILL.md +82 -0
  7. package/skills/mem.sources/SKILL.md +93 -0
  8. package/skills/mem.usage/SKILL.md +118 -492
  9. package/src/backend/records.js +285 -0
  10. package/src/bootstrap.js +49 -45
  11. package/src/call-shapes.js +41 -10
  12. package/src/collector-lock.js +162 -0
  13. package/src/collector-service.js +441 -0
  14. package/src/collector.js +381 -0
  15. package/src/commands.js +3 -3
  16. package/src/config.js +12 -1
  17. package/src/curation.js +1 -1
  18. package/src/permissions.js +18 -2
  19. package/src/protocol.js +55 -24
  20. package/src/recall.js +104 -27
  21. package/src/records-store.js +280 -120
  22. package/src/records.js +63 -11
  23. package/src/runtime.js +23 -14
  24. package/src/skills.js +44 -18
  25. package/src/sources.js +58 -0
  26. package/src/spaces.js +93 -10
  27. package/src/tools/aliases.js +163 -0
  28. package/src/tools/commitments.js +12 -9
  29. package/src/tools/index.js +88 -19
  30. package/src/tools/ingest.js +277 -0
  31. package/src/tools/knowledge.js +6 -1
  32. package/src/tools/memory.js +640 -210
  33. package/src/tools/page.js +411 -0
  34. package/src/tools/recall.js +363 -112
  35. package/src/tools/records-kit.js +142 -0
  36. package/src/tools/share.js +1012 -0
  37. package/src/tools/shared.js +8 -1
  38. package/src/tools/spaces.js +431 -143
  39. package/src/tools/status.js +87 -58
  40. package/src/tools/wiki.js +2 -2
  41. package/src/views/contracts.js +273 -3
  42. package/src/views/records-reads.js +675 -0
  43. package/src/views/rpc.js +17 -100
  44. package/src/views/shape.js +61 -0
  45. package/views/commitments.html +4 -0
  46. package/views/graph.html +753 -0
  47. package/views/home.html +11 -5
  48. package/views/journal.html +621 -0
  49. package/views/memory.html +7 -1
  50. package/views/pages.html +636 -0
  51. package/views/review.html +406 -0
  52. package/views/today.html +309 -0
@@ -1,48 +1,287 @@
1
1
  /**
2
- * Reading and writing a space's records wiki ("Memory records",
3
- * `commitments.json`). The pure rules live in `records.js`.
2
+ * A space's commitments as records (kind `commitment`) in the records service
3
+ * (docs/design/memory-v1-contracts.md §4.1), and the one-time migration of the
4
+ * hub's reserved "Memory records" wiki (`commitments.json`) into them.
4
5
  *
5
- * Two of one person's agents can write the file at once, and the wiki raw
6
- * route has no conditional write yet (GAPS S2). So a write is a
7
- * read-modify-write that detects a change since its read:
6
+ * The interface is the one the hub-file store had, so `mem_commitments`, the
7
+ * Due list and the views keep their shape: `read(scope)` answers
8
+ * `{ records: { items } }` in the item shape of `records.js`, and
9
+ * `change(scope, spaceContext, change, context)` applies one add, update or
10
+ * delete. The pure rules (validation, the duplicate check, the Due list) stay
11
+ * in `records.js`.
8
12
  *
9
- * 1. Read the file and apply the change.
10
- * 2. Re-read just before writing. If the file changed, apply the same change
11
- * (it names its target by id) to the newer copy and start again.
12
- * 3. Write, then read back. If another writer replaced the file in between,
13
- * and the change is not in what is stored now, apply it to that copy and
14
- * write again.
13
+ * Concurrency: an update sends the record's `base_version`; a
14
+ * `version_conflict` (another writer got there first) re-reads and applies the
15
+ * same change to the newer copy, at most three rounds, then reports a conflict
16
+ * instead of overwriting.
15
17
  *
16
- * Every write is built from the newest copy read, so a record another writer
17
- * added is kept: a change touches only its own id. After three rounds without
18
- * a stable read, the write reports a conflict instead of overwriting.
18
+ * Migration, on the first read or write in a space (per process): the hub
19
+ * file's items are put as commitment records carrying their old id as
20
+ * `fields.legacy_id`, skipping any already migrated, and the file is then
21
+ * rewritten with a `migrated` stamp and kept. A stamped file is never
22
+ * migrated again; the legacy-id check makes a repeat after a partial run
23
+ * harmless. Its old `cmt_` ids still address the migrated records.
19
24
  */
20
25
  import {
26
+ CLOSED_RETENTION_DAYS,
21
27
  RECORDS_FILE,
22
28
  RECORDS_WIKI,
23
29
  applyChange,
30
+ commitmentFields,
24
31
  dayIn,
25
- emptyRecords,
32
+ itemOfRecord,
26
33
  parseRecords,
34
+ prune,
27
35
  serializeRecords,
28
36
  } from "./records.js"
37
+ import { isRecordsCode } from "./backend/records.js"
29
38
  import { errorMessage } from "./util.js"
30
39
 
31
40
  export const MAX_ROUNDS = 3
41
+ /** Commitment records read per list page, and pages read at most. */
42
+ const PAGE = 200
43
+ const MAX_PAGES = 10
32
44
 
33
- /** True when a stored copy already reflects a change (nothing left to write). */
34
- function reflects(records, change, item) {
35
- const stored = records.items.find((entry) => entry.id === change.id)
36
- if (change.action === "delete") return !stored
37
- if (!stored || !item) return false
38
- return JSON.stringify(stored) === JSON.stringify(item)
45
+ /**
46
+ * @param {{ backend: any, control?: any, log?: any, client?: { call: Function } | null }} deps
47
+ */
48
+ export function createRecordsStore({ backend, control, log, client }) {
49
+ const hub = createHubFile({ backend, control, log })
50
+ /** Spaces whose hub file is migrated (or absent), and migrations running now. */
51
+ const migrated = new Set()
52
+ const migrating = new Map()
53
+
54
+ function need() {
55
+ if (!client) throw new Error("the records service is not configured")
56
+ return client
57
+ }
58
+
59
+ /** One records call in the space a scope names. Reads never send the session, so they never bind it. */
60
+ function call(method, body, scope, { session } = {}) {
61
+ return need().call(method, body, { scope, space: scope?.space_id, ...(session ? { sessionID: session } : {}) })
62
+ }
63
+
64
+ const spaceKey = (scope) => String(scope?.space_id || scope?.team_id || "local")
65
+
66
+ /** Every commitment record in the space, any status, newest first. */
67
+ async function listRecords(scope) {
68
+ const records = []
69
+ let cursor
70
+ for (let page = 0; page < MAX_PAGES; page += 1) {
71
+ const data = await call("records.list", { kind: "commitment", status: "all", limit: PAGE, full: true, ...(cursor ? { cursor } : {}) }, scope)
72
+ records.push(...(data?.records ?? []))
73
+ cursor = data?.cursor
74
+ if (!cursor) break
75
+ }
76
+ return records
77
+ }
78
+
79
+ /**
80
+ * Migrate the hub file once per space. A failure is logged and retried on the
81
+ * next use; it never fails the read or write that triggered it.
82
+ *
83
+ * @returns {Promise<{ migrated: number, skipped: number, marked: boolean, reason?: string }>}
84
+ */
85
+ async function migrate(scope) {
86
+ const key = spaceKey(scope)
87
+ if (migrated.has(key)) return { migrated: 0, skipped: 0, marked: false, reason: "done" }
88
+ if (migrating.has(key)) return migrating.get(key)
89
+ const run = (async () => {
90
+ try {
91
+ const result = await migrateOnce(scope)
92
+ migrated.add(key)
93
+ if (result.migrated > 0) log?.info?.("commitments migrated into records", { migrated: result.migrated, skipped: result.skipped })
94
+ return result
95
+ } catch (error) {
96
+ log?.warn?.("commitments migration failed; it is retried on the next use", { error: errorMessage(error) })
97
+ return { migrated: 0, skipped: 0, marked: false, reason: `failed: ${errorMessage(error)}` }
98
+ } finally {
99
+ migrating.delete(key)
100
+ }
101
+ })()
102
+ migrating.set(key, run)
103
+ return run
104
+ }
105
+
106
+ async function migrateOnce(scope) {
107
+ for (let round = 1; round <= MAX_ROUNDS; round += 1) {
108
+ const file = await hub.read(scope)
109
+ if (!file) return { migrated: 0, skipped: 0, marked: false, reason: "no hub file" }
110
+ if (file.parsed.migrated) return { migrated: 0, skipped: 0, marked: false, reason: "already migrated" }
111
+ const present = new Set((await listRecords(scope)).map((record) => record.fields?.legacy_id).filter(Boolean))
112
+ let count = 0
113
+ let skipped = 0
114
+ for (const item of file.parsed.items) {
115
+ if (present.has(item.id)) {
116
+ skipped += 1
117
+ continue
118
+ }
119
+ await call("records.put", { record: migratedRecord(item) }, scope)
120
+ present.add(item.id)
121
+ count += 1
122
+ }
123
+ // Stamp the file only if nobody wrote it meanwhile; otherwise migrate
124
+ // what they added too.
125
+ const latest = await hub.readText(scope, file.wikiID)
126
+ if (latest !== file.text) continue
127
+ const stamped = serializeRecords({ ...file.parsed, version: file.parsed.version + 1, migrated: { at: new Date().toISOString(), to: "records", items: file.parsed.items.length } })
128
+ await backend.writeWikiRaw({ scope, wikiID: file.wikiID, files: [{ filename: RECORDS_FILE, content: stamped }] })
129
+ return { migrated: count, skipped, marked: true }
130
+ }
131
+ throw new Error("the hub's commitments file kept changing during the migration")
132
+ }
133
+
134
+ /**
135
+ * The space's commitments, in the item shape of `records.js`.
136
+ *
137
+ * @returns {Promise<{ records: { items: any[] }, raw: any[] }>}
138
+ */
139
+ async function read(scope) {
140
+ await migrate(scope)
141
+ const raw = await listRecords(scope)
142
+ return { records: { items: raw.map(itemOfRecord) }, raw }
143
+ }
144
+
145
+ /** The record a commitment id names: its `rec_` id, or the `cmt_` id it had before the migration. */
146
+ function find(raw, id) {
147
+ return raw.find((record) => record.id === id) ?? raw.find((record) => record.fields?.legacy_id === id) ?? null
148
+ }
149
+
150
+ /**
151
+ * Apply one change, with the version check described above.
152
+ *
153
+ * @param {any} scope
154
+ * @param {any} _spaceContext
155
+ * @param {{ action: "add" | "update" | "delete", id?: string, fields?: Record<string, any> }} change
156
+ * @param {{ now: number, zone: string, session?: string }} context
157
+ * @returns {Promise<{ item?: any, records?: { items: any[] }, rounds?: number, unchanged?: boolean, error?: string, conflict?: boolean }>}
158
+ */
159
+ async function change(scope, _spaceContext, change, context) {
160
+ const today = dayIn(context.now, context.zone)
161
+ for (let round = 1; round <= MAX_ROUNDS; round += 1) {
162
+ const { records, raw } = await read(scope)
163
+ if (change.action === "add") {
164
+ const applied = applyChange(records, { ...change, id: "new" }, { today, session: context.session })
165
+ if (applied.error) return { error: applied.error }
166
+ if (applied.unchanged) return { item: applied.item, records, rounds: round, unchanged: true }
167
+ const data = await call("records.put", { record: commitmentRecord(applied.item, { session: context.session }) }, scope, { session: context.session })
168
+ const item = itemOfRecord(data.record)
169
+ const items = [...records.items, item]
170
+ await pruneClosed(scope, raw, today)
171
+ return { item, records: { items }, rounds: round }
172
+ }
173
+ const target = find(raw, String(change.id ?? ""))
174
+ if (!target) return { error: `no commitment ${String(change.id ?? "").slice(0, 40)} in this space` }
175
+ const current = itemOfRecord(target)
176
+ if (change.action === "delete") {
177
+ const data = await call("records.delete", { ids: [target.id] }, scope, { session: context.session })
178
+ if (!(data?.deleted ?? []).includes(target.id)) return { error: `the records service did not delete ${target.id}` }
179
+ return { item: current, records: { items: records.items.filter((item) => item.id !== current.id) }, rounds: round }
180
+ }
181
+ const applied = applyChange({ items: [current] }, { ...change, id: current.id }, { today, session: context.session })
182
+ if (applied.error) return { error: applied.error }
183
+ try {
184
+ const data = await call(
185
+ "records.put",
186
+ { record: { id: target.id, ...commitmentRecord(applied.item, { session: context.session, keep: target }), base_version: target.version } },
187
+ scope,
188
+ { session: context.session },
189
+ )
190
+ const item = itemOfRecord(data.record)
191
+ await pruneClosed(scope, raw, today)
192
+ return { item, records: { items: records.items.map((entry) => (entry.id === item.id ? item : entry)) }, rounds: round }
193
+ } catch (error) {
194
+ if (!isRecordsCode(error, "version_conflict")) throw error
195
+ log?.debug?.("commitment changed since read; applying again", { round })
196
+ }
197
+ }
198
+ return { conflict: true, error: "another agent kept changing this commitment; nothing was overwritten. Try again in a moment." }
199
+ }
200
+
201
+ /** Closed commitments past the retention window are deleted on a write, best effort. */
202
+ async function pruneClosed(scope, raw, today) {
203
+ const items = raw.map(itemOfRecord)
204
+ const keep = new Set(prune(items, today).map((item) => item.id))
205
+ const old = raw.filter((record) => !keep.has(record.id)).map((record) => record.id)
206
+ if (old.length === 0) return
207
+ try {
208
+ await call("records.delete", { ids: old }, scope)
209
+ } catch (error) {
210
+ log?.debug?.(`closed commitments older than ${CLOSED_RETENTION_DAYS} days were not pruned`, { error: errorMessage(error) })
211
+ }
212
+ }
213
+
214
+ /**
215
+ * The session-start dashboard: the space's `index` page, or null when it has
216
+ * none. A failed read throws, so the pinned block counts it as a miss.
217
+ */
218
+ async function readIndex(scope) {
219
+ const data = await call("records.get", { paths: ["index"] }, scope)
220
+ return (data?.records ?? []).find((record) => record.path === "index") ?? null
221
+ }
222
+
223
+ return {
224
+ read,
225
+ change,
226
+ migrate,
227
+ readIndex,
228
+ locate: hub.locate,
229
+ isRecordsWiki: hub.isRecordsWiki,
230
+ noteRecordsWiki: hub.noteRecordsWiki,
231
+ remember: hub.remember,
232
+ }
233
+ }
234
+
235
+ /** A hub item as the commitment record it becomes, carrying its old id. */
236
+ function migratedRecord(item) {
237
+ const record = commitmentRecord(item, { session: item.session })
238
+ record.fields.legacy_id = item.id
239
+ if (item.created) record.fields.created_day = item.created
240
+ // Provenance is a field: a record's source names only a session, turn, event, url, routine or record (§2.3).
241
+ record.fields.migrated_from = "hub"
242
+ return record
243
+ }
244
+
245
+ /** The commitment fields this module writes whole; the item is their only source. */
246
+ const OWNED_FIELDS = Object.freeze(["what", "owner", "due", "trigger", "state", "project", "link", "closed_at", "links"])
247
+
248
+ /** A commitment item as the record the service stores (kind and type `commitment`). */
249
+ export function commitmentRecord(item, { session, keep } = {}) {
250
+ // The service merges fields on update and removes a key sent as null
251
+ // (§2.3), so a field this module owns that the item no longer has (a cleared
252
+ // due, the closed_at of a reopened commitment) is sent as null; any other
253
+ // field is kept.
254
+ const fields = { ...commitmentFields(item) }
255
+ if (keep) {
256
+ for (const key of OWNED_FIELDS) if (keep.fields?.[key] !== undefined && fields[key] === undefined) fields[key] = null
257
+ }
258
+ const record = {
259
+ kind: "commitment",
260
+ type: "commitment",
261
+ title: item.what,
262
+ body: commitmentBody(item),
263
+ fields,
264
+ ...(keep ? {} : { stated_by: "agent" }),
265
+ }
266
+ if (!keep && session) record.source = { session: String(session) }
267
+ return record
268
+ }
269
+
270
+ /** The searchable text: what, and when. The project is a link. */
271
+ function commitmentBody(item) {
272
+ const lines = [String(item.what ?? "")]
273
+ if (item.due) lines.push(`Due: ${item.due}`)
274
+ if (item.trigger) lines.push(`When: ${item.trigger}`)
275
+ if (item.project) lines.push(`Project: [[projects/${item.project}]]`)
276
+ return lines.join("\n")
39
277
  }
40
278
 
41
279
  /**
42
- * @param {{ backend: any, control?: any, log?: any }} deps
280
+ * The hub's reserved records wiki: found to migrate it, and kept out of
281
+ * mem_wiki (`isRecordsWiki`). Nothing new is written to it except the
282
+ * migration stamp.
43
283
  */
44
- export function createRecordsStore({ backend, control, log }) {
45
- /** Records wiki id per container: one lookup per space and process. */
284
+ function createHubFile({ backend, control, log }) {
46
285
  const wikiIds = new Map()
47
286
  const known = new Set()
48
287
 
@@ -51,24 +290,23 @@ export function createRecordsStore({ backend, control, log }) {
51
290
  known.add(wikiID)
52
291
  }
53
292
 
54
- /** True for a wiki id this process knows is a records wiki. */
55
293
  function isRecordsWiki(wikiID) {
56
294
  return known.has(String(wikiID ?? ""))
57
295
  }
58
296
 
297
+ function noteRecordsWiki(wikiID) {
298
+ if (wikiID) known.add(String(wikiID))
299
+ }
300
+
59
301
  /**
60
- * Find the space's records wiki. A wiki listing that fails is an error, not
61
- * an empty space: a write must never create a second records wiki because a
62
- * read timed out.
302
+ * Find the space's records wiki in the wiki list or the asset catalogue (each
303
+ * can miss one the other has). Only both failing is an error.
63
304
  */
64
305
  async function locate(scope) {
65
306
  const key = String(scope.team_id ?? "")
66
307
  if (wikiIds.has(key)) return wikiIds.get(key)
67
- // The wiki list and the asset catalogue can each miss a wiki the other
68
- // has (knowledge.js discoverKnowledge merges them for the same reason), so
69
- // both are read; only both failing is an error.
70
308
  const [wikis, assets] = await Promise.allSettled([
71
- backend.listWiki({ scope }),
309
+ typeof backend.listWiki === "function" ? backend.listWiki({ scope }) : Promise.reject(new Error("no wiki listing")),
72
310
  typeof backend.listAccessibleAssets === "function"
73
311
  ? backend.listAccessibleAssets({ scope, assetType: "llm_wiki" })
74
312
  : Promise.reject(new Error("no asset listing")),
@@ -84,35 +322,15 @@ export function createRecordsStore({ backend, control, log }) {
84
322
  return String(found)
85
323
  }
86
324
 
87
- /** Create the records wiki and, where a control plane owns the catalogue, register it. */
88
- async function create(scope, spaceContext) {
89
- const wiki = await backend.createWiki({ scope, name: RECORDS_WIKI })
90
- const wikiID = String(wiki?.wiki_id ?? "")
91
- if (!wikiID) throw new Error("wiki/create returned no wiki_id")
92
- const registered = typeof wiki?.resource_id === "string" && wiki.resource_id.trim()
93
- if (!registered && control && spaceContext?.space_id) {
94
- const userId = spaceContext.user_id
95
- if (userId) {
96
- await control.createResource({
97
- userId,
98
- spaceId: spaceContext.space_id,
99
- resource: { kind: "wiki", upstream_id: wikiID, name: RECORDS_WIKI },
100
- })
101
- }
102
- }
103
- remember(String(scope.team_id ?? ""), wikiID)
104
- return wikiID
105
- }
106
-
107
325
  async function readText(scope, wikiID) {
108
326
  let data
109
327
  try {
110
328
  data = await backend.readWikiRaw({ scope, wikiID, filenames: [RECORDS_FILE] })
111
329
  } catch (error) {
112
- // The cached id may belong to a wiki that was deleted since.
113
330
  if (Number(error?.status) === 404) {
114
331
  for (const [key, value] of wikiIds) if (value === wikiID) wikiIds.delete(key)
115
332
  known.delete(wikiID)
333
+ return ""
116
334
  }
117
335
  throw error
118
336
  }
@@ -120,80 +338,22 @@ export function createRecordsStore({ backend, control, log }) {
120
338
  return typeof item?.content === "string" ? item.content : ""
121
339
  }
122
340
 
123
- /**
124
- * The space's commitments. No records wiki yet is an empty set.
125
- *
126
- * @returns {Promise<{ wikiID: string, records: ReturnType<typeof emptyRecords>, text: string }>}
127
- */
341
+ /** The file, parsed, or null when the space has none (or it holds nothing). */
128
342
  async function read(scope) {
129
343
  const wikiID = await locate(scope)
130
- if (!wikiID) return { wikiID: "", records: emptyRecords(), text: "" }
344
+ if (!wikiID) return null
131
345
  const text = await readText(scope, wikiID)
346
+ if (!text.trim()) return null
132
347
  const parsed = parseRecords(text)
133
- if (parsed.error) throw new Error(parsed.error)
134
- return { wikiID, records: parsed.records, text }
135
- }
136
-
137
- /**
138
- * Apply one change with the concurrency check described above.
139
- *
140
- * @param {any} scope
141
- * @param {any} spaceContext
142
- * @param {{ action: "add" | "update" | "delete", id: string, fields?: Record<string, any> }} change
143
- * @param {{ now: number, zone: string, session?: string }} context
144
- * @returns {Promise<{ item?: any, records?: any, rounds?: number, unchanged?: boolean, error?: string, conflict?: boolean }>}
145
- */
146
- async function change(scope, spaceContext, change, context) {
147
- const today = dayIn(context.now, context.zone)
148
- let wikiID = await locate(scope)
149
- if (!wikiID && change.action !== "add") return { error: `no commitment ${change.id} in this space: it has no commitments yet` }
150
- if (!wikiID) wikiID = await create(scope, spaceContext)
151
-
152
- let text = await readText(scope, wikiID)
153
- for (let round = 1; round <= MAX_ROUNDS; round += 1) {
154
- const parsed = parseRecords(text)
155
- if (parsed.error) return { error: `${parsed.error}; nothing was written` }
156
- const applied = applyChange(parsed.records, change, { today, session: context.session })
157
- if (applied.error) return { error: applied.error }
158
- if (applied.unchanged) return { item: applied.item, records: parsed.records, rounds: round, unchanged: true }
159
- const next = { ...parsed.records, version: parsed.records.version + 1, items: applied.items }
160
- const body = serializeRecords(next)
161
-
162
- // Re-read just before writing: a write since our read means our copy is
163
- // old, so the change is applied again to the newer one.
164
- const latest = await readText(scope, wikiID)
165
- if (latest !== text) {
166
- log?.debug?.("records changed since read; merging", { round })
167
- text = latest
168
- continue
169
- }
170
-
171
- await backend.writeWikiRaw({ scope, wikiID, files: [{ filename: RECORDS_FILE, content: body }] })
172
-
173
- // Read back: a writer that raced us between the re-read and the write
174
- // shows here. If our change is in what is stored, we are done;
175
- // otherwise apply it to the stored copy and write again.
176
- const stored = await readText(scope, wikiID)
177
- if (stored === body) return { item: applied.item, records: next, rounds: round }
178
- const storedParsed = parseRecords(stored)
179
- if (!storedParsed.error && reflects(storedParsed.records, change, applied.item)) {
180
- return { item: applied.item, records: storedParsed.records, rounds: round }
181
- }
182
- log?.debug?.("records replaced after write; merging", { round })
183
- text = stored
348
+ if (parsed.error) {
349
+ log?.warn?.("the hub's commitments file is unreadable; it is not migrated", { error: parsed.error })
350
+ return null
184
351
  }
185
- return {
186
- conflict: true,
187
- error: `another agent kept changing this space's commitments; nothing was overwritten. Try again in a moment.`,
188
- }
189
- }
190
-
191
- /** Note a records wiki seen in a listing, so mem_wiki refuses it by id too. */
192
- function noteRecordsWiki(wikiID) {
193
- if (wikiID) known.add(String(wikiID))
352
+ return { wikiID, text, parsed: parsed.records }
194
353
  }
195
354
 
196
- return { read, change, locate, isRecordsWiki, noteRecordsWiki, remember }
355
+ void control
356
+ return { locate, readText, read, isRecordsWiki, noteRecordsWiki, remember }
197
357
  }
198
358
 
199
359
  /** A records read for the pinned block: never throws; a failure is `null`. */
package/src/records.js CHANGED
@@ -2,16 +2,19 @@
2
2
  * Commitments: things someone will do, with a time or a trigger, kept as a
3
3
  * structured record with a state (docs/design/memory-value-design.md §7).
4
4
  *
5
- * Atoms cannot hold this: they cannot be updated, upstream assigns their type,
6
- * and `work_task` atoms are withheld from recall by design. So each space
7
- * keeps one reserved, never-ingested wiki, "Memory records", holding one file,
8
- * `commitments.json`:
5
+ * From 0.9.0 each commitment is a record of kind `commitment` in the records
6
+ * service (docs/design/memory-v1-contracts.md §2.3), with its state in
7
+ * `fields`. Before that, each space kept one reserved, never-ingested wiki,
8
+ * "Memory records", holding one file, `commitments.json`:
9
9
  *
10
10
  * { "marker": "opencode-mem:records v1", "version": 7, "items": [ … ] }
11
11
  *
12
- * This module is pure: parse, validate, apply a change, merge a change into a
13
- * newer copy, and render the Due list and the list answer. The I/O and the
14
- * concurrency check live in `records-store.js`.
12
+ * `records-store.js` migrates that file into records once and stamps it
13
+ * `migrated`; the parser here still reads it for that.
14
+ *
15
+ * This module is pure: parse, validate, apply a change, map an item to and
16
+ * from its record, and render the Due list and the list answer. The I/O and
17
+ * the concurrency check live in `records-store.js`.
15
18
  */
16
19
  import { isInstructionShaped } from "./curation.js"
17
20
  import { neutralizeFenceClosers, oneLine } from "./util.js"
@@ -69,12 +72,61 @@ export function parseRecords(text) {
69
72
  const items = (Array.isArray(parsed.items) ? parsed.items : []).filter(
70
73
  (item) => item && typeof item === "object" && typeof item.id === "string" && typeof item.what === "string",
71
74
  )
72
- return { records: { marker: RECORDS_MARKER, version, items } }
75
+ const migrated = parsed.migrated && typeof parsed.migrated === "object" ? { migrated: parsed.migrated } : {}
76
+ return { records: { marker: RECORDS_MARKER, version, ...migrated, items } }
73
77
  }
74
78
 
75
79
  /** The file's text; the marker is the first key, as a share's marker is its first line. */
76
80
  export function serializeRecords(records) {
77
- return `${JSON.stringify({ marker: RECORDS_MARKER, version: records.version, items: records.items }, null, 2)}\n`
81
+ const migrated = records.migrated ? { migrated: records.migrated } : {}
82
+ return `${JSON.stringify({ marker: RECORDS_MARKER, version: records.version, ...migrated, items: records.items }, null, 2)}\n`
83
+ }
84
+
85
+ /** The calendar day of an ISO time, or the value itself when it is already a day. */
86
+ function dayOf(value) {
87
+ const text = String(value ?? "")
88
+ return DATE.test(text) ? text : text.slice(0, 10)
89
+ }
90
+
91
+ /**
92
+ * A commitment record (kind `commitment`) as the item every answer and the Due
93
+ * list read: `{ id, what, owner, due?, trigger?, state, project?, link?,
94
+ * created, updated, closed?, session?, legacy_id? }`. The id is the record's
95
+ * `rec_` id; a commitment migrated from the hub file keeps its old `cmt_` id
96
+ * as `legacy_id`.
97
+ */
98
+ export function itemOfRecord(record) {
99
+ const fields = record?.fields ?? {}
100
+ return compact({
101
+ id: String(record?.id ?? ""),
102
+ what: String(fields.what ?? record?.title ?? ""),
103
+ owner: fields.owner ?? "user",
104
+ due: fields.due,
105
+ trigger: fields.trigger,
106
+ state: STATES.includes(fields.state) ? fields.state : "open",
107
+ project: fields.project,
108
+ link: fields.link,
109
+ created: fields.created_day ?? dayOf(record?.created),
110
+ updated: dayOf(record?.updated),
111
+ closed: fields.closed_at ? dayOf(fields.closed_at) : undefined,
112
+ session: record?.source?.session,
113
+ legacy_id: fields.legacy_id,
114
+ })
115
+ }
116
+
117
+ /** An item's state as a commitment record's `fields` (contract §2.3): `what` is also the title. */
118
+ export function commitmentFields(item) {
119
+ return compact({
120
+ what: item.what,
121
+ owner: item.owner ?? "user",
122
+ due: item.due,
123
+ trigger: item.trigger,
124
+ state: item.state ?? "open",
125
+ project: item.project,
126
+ link: item.link,
127
+ closed_at: item.state && item.state !== "open" ? item.closed : undefined,
128
+ links: item.project ? [`projects/${item.project}`] : undefined,
129
+ })
78
130
  }
79
131
 
80
132
  /** True when a file's text is a records file (used to keep it out of mem_wiki). */
@@ -396,7 +448,7 @@ export function dueSection(items, { today, zone, workingDays = DUE_WORKING_DAYS
396
448
  if (due.length === 0) return { text: "", withheld }
397
449
  const lines = due
398
450
  .slice(0, DUE_MAX_LINES)
399
- .map((item) => `- ${dueLabel(item, today, zone)}: ${shown(item.what, 160)} (${shown(ownerLabel(item.owner), 60)}) [${shown(item.id, 20)}]`)
451
+ .map((item) => `- ${dueLabel(item, today, zone)}: ${shown(item.what, 160)} (${shown(ownerLabel(item.owner), 60)}) [${shown(item.id, 40)}]`)
400
452
  const more = open.length - withheld - lines.length
401
453
  if (more > 0) lines.push(`(${more} more open: mem_commitments list)`)
402
454
  return { text: `## Due (${formatDay(today)})\n${lines.join("\n")}`, withheld }
@@ -428,7 +480,7 @@ export function filterItems(items, filter, zone) {
428
480
 
429
481
  /** One line of a list answer. */
430
482
  export function itemLine(item, today, zone) {
431
- const parts = [`${shown(item.id, 20)}`, shown(item.what, MAX_WHAT_CHARS)]
483
+ const parts = [`${shown(item.id, 40)}`, shown(item.what, MAX_WHAT_CHARS)]
432
484
  const when = item.state === "open" ? dueLabel(item, today, zone) : item.due ? formatDue(item.due, zone) : ""
433
485
  if (when) parts.push(item.state === "open" ? when : `due ${when}`)
434
486
  if (item.trigger) parts.push(`when: ${shown(item.trigger, MAX_TRIGGER_CHARS)}`)