advisers 0.3.1 → 0.4.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 (48) hide show
  1. package/README-zh.md +13 -15
  2. package/README.md +32 -22
  3. package/THIRD-PARTY-NOTICES.md +1 -1
  4. package/bin/advisers.js +2769 -183
  5. package/index.js +1 -1
  6. package/lib/brief-archive.js +267 -0
  7. package/lib/client-pack.js +1016 -0
  8. package/lib/consent.js +390 -0
  9. package/lib/credentials.js +195 -0
  10. package/lib/customer-read.js +524 -0
  11. package/lib/error-codes.js +516 -7
  12. package/lib/evidence.js +928 -120
  13. package/lib/kb-extract.js +626 -0
  14. package/lib/kb-facts.js +429 -0
  15. package/lib/kb-pages.js +1084 -0
  16. package/lib/kb.js +1036 -0
  17. package/lib/ledger-read.js +109 -1
  18. package/lib/mail-errors.js +46 -0
  19. package/lib/mail-extract.js +351 -0
  20. package/lib/mail-imap.js +446 -0
  21. package/lib/mail-import.js +176 -0
  22. package/lib/mail-parse.js +223 -0
  23. package/lib/mail-store.js +731 -0
  24. package/lib/mail.js +506 -0
  25. package/lib/mcp-server.js +397 -11
  26. package/lib/notify.js +265 -7
  27. package/lib/policy/decision.js +315 -0
  28. package/lib/policy/egress.js +268 -0
  29. package/lib/policy/errors.js +71 -0
  30. package/lib/policy/index.js +99 -0
  31. package/lib/policy/rules.js +468 -0
  32. package/lib/policy/surfaces.js +141 -0
  33. package/lib/receipt-verify.js +283 -26
  34. package/lib/receivables.js +1653 -0
  35. package/lib/scheduler.js +453 -9
  36. package/lib/shell.js +1406 -0
  37. package/lib/source.js +98 -3
  38. package/lib/sqlite.js +501 -49
  39. package/lib/tos/index.js +2 -2
  40. package/lib/tos/manifest.json +6 -6
  41. package/lib/tos/privacy.zh-CN.md +33 -20
  42. package/lib/tos/safety.zh-CN.md +7 -6
  43. package/lib/tos/summary.zh-CN.md +3 -2
  44. package/lib/tos/terms.zh-CN.md +31 -16
  45. package/lib/tui/labels.js +1 -1
  46. package/lib/tui/render.js +1 -1
  47. package/lib/urgency.js +467 -0
  48. package/package.json +4 -4
@@ -0,0 +1,1084 @@
1
+ /**
2
+ * KB compiled pages (0.4.0, schema v22): deterministic, rebuildable projections
3
+ * of the local ledger and KB. A page is derived data, never a fourth ledger:
4
+ * every byte comes from rows in the same database, and `kb page rebuild` is the
5
+ * only writer (the CLI wires the command; this module owns the derivation).
6
+ *
7
+ * Four page kinds (45 section 3.6):
8
+ * - client: identity, projects, counts, open commitments, recent timeline, facts;
9
+ * - project: project fields, its matters, deliveries and open commitments;
10
+ * - timeline: the derived client timeline (deliveries + commitments only, never
11
+ * note bodies), reuseing lib/customer-read.js;
12
+ * - facts: one fact chain per (subject, matter) with validFrom/validTo and
13
+ * evidence quotes.
14
+ *
15
+ * Determinism contract:
16
+ * - data contains no wall clock; generated_at lives only on the row;
17
+ * - inputsSha256 = sha256(canonical JSON of the page data), so identical
18
+ * database rows produce byte-identical markdown/json/hash across processes;
19
+ * - json column is canonical JSON (sorted keys), markdown is a pure function of
20
+ * the same data; rebuild writes only rows whose hash changed;
21
+ * - page ids are stable: page_client_<id>, page_project_<id>,
22
+ * page_timeline_<id>, page_facts_<sha256(subject|matter)[0:12]>.
23
+ *
24
+ * Privacy: notes are counted, never rendered; a page whose owner is above the
25
+ * caller's clearance is filtered BEFORE counting/paging and only counted in
26
+ * protectedExcluded; unresolvable owners fail closed. No model, no network.
27
+ */
28
+ import { createHash } from 'node:crypto'
29
+ import { entityError } from './sqlite.js'
30
+ import { readClientStatus } from './customer-read.js'
31
+ import { stripBidiControls, stripControlChars, stripTerminalSequences } from './text-safe.js'
32
+
33
+ export const KB_PAGE_KINDS = Object.freeze(['client', 'project', 'timeline', 'facts'])
34
+ export const KB_PAGE_GENERATOR = 'deterministic@1'
35
+ export const KB_PAGE_LIST_LIMIT = 50
36
+ export const KB_PAGE_LIST_LIMIT_MAX = 500
37
+ export const KB_PAGE_FACTS_MAX = 500
38
+ export const KB_PAGE_FACTS_PER_GROUP_MAX = 200
39
+ export const KB_PAGE_FACT_EVIDENCE_MAX = 200
40
+
41
+ const KIND_RANK = Object.freeze({ client: 0, project: 1, timeline: 2, facts: 3 })
42
+ const FACT_QUOTE_MAX = 200
43
+ const DELIVERY_PREVIEW_MAX = 20
44
+
45
+ /* -------------------------------------------------------------------------- */
46
+ /* deterministic helpers */
47
+ /* -------------------------------------------------------------------------- */
48
+
49
+ function normalizeJson(value) {
50
+ if (value === undefined) return null
51
+ if (value instanceof Date) return value.toISOString()
52
+ if (Array.isArray(value)) return value.map((item) => normalizeJson(item))
53
+ if (value && typeof value === 'object') {
54
+ const out = {}
55
+ for (const key of Object.keys(value).sort()) {
56
+ if (value[key] === undefined) continue
57
+ out[key] = normalizeJson(value[key])
58
+ }
59
+ return out
60
+ }
61
+ if (typeof value === 'number' && !Number.isFinite(value)) return null
62
+ return value
63
+ }
64
+
65
+ /** Canonical JSON (sorted keys at every depth) used for the page hash + json column. */
66
+ export function canonicalJson(value) {
67
+ return JSON.stringify(normalizeJson(value))
68
+ }
69
+
70
+ export function sha256Hex(text) {
71
+ return createHash('sha256').update(String(text), 'utf8').digest('hex')
72
+ }
73
+
74
+ function sanitizeInline(value, max = 200) {
75
+ const text = stripControlChars(stripBidiControls(stripTerminalSequences(String(value ?? ''))), { keepNewlines: false, keepTabs: false, replacement: ' ' })
76
+ .replace(/\s+/gu, ' ').trim()
77
+ const chars = Array.from(text)
78
+ return chars.length <= max ? text : chars.slice(0, max).join('')
79
+ }
80
+
81
+ function sanitizeBlock(value) {
82
+ return stripControlChars(stripBidiControls(stripTerminalSequences(String(value ?? ''))), { keepNewlines: true, keepTabs: true, replacement: ' ' })
83
+ .replace(/\n{3,}/g, '\n\n').trim()
84
+ }
85
+
86
+ function cell(value) {
87
+ return sanitizeInline(value, 160).replace(/\|/g, '\\|')
88
+ }
89
+
90
+ function numberOrNull(value) {
91
+ if (value === undefined || value === null) return null
92
+ const number = Number(value)
93
+ return Number.isFinite(number) ? number : null
94
+ }
95
+
96
+ function stringOrNull(value) {
97
+ if (value === undefined || value === null || value === '') return null
98
+ return String(value)
99
+ }
100
+
101
+ function assertStore(store) {
102
+ if (!store || !store.db || typeof store.db.prepare !== 'function' || typeof store.read !== 'function' || typeof store.mutate !== 'function') {
103
+ throw new TypeError('kb-pages requires an opened SqliteStore')
104
+ }
105
+ }
106
+
107
+ function hasSqliteObject(store, name, types = ['table']) {
108
+ const placeholders = types.map(() => '?').join(',')
109
+ return Boolean(store.db.prepare('SELECT name FROM sqlite_master WHERE name = ? AND type IN (' + placeholders + ')').get(name, ...types))
110
+ }
111
+
112
+ export function assertKbPagesSchema(store) {
113
+ assertStore(store)
114
+ if (!hasSqliteObject(store, 'kb_pages')) {
115
+ throw entityError('E_SCHEMA_STALE', 'kb_pages is missing; open an upgraded database (schema v22)', 'advisers doctor')
116
+ }
117
+ }
118
+
119
+ /* -------------------------------------------------------------------------- */
120
+ /* page ids */
121
+ /* -------------------------------------------------------------------------- */
122
+
123
+ export function clientPageId(clientId) {
124
+ return 'page_client_' + String(clientId)
125
+ }
126
+
127
+ export function projectPageId(projectId) {
128
+ return 'page_project_' + String(projectId)
129
+ }
130
+
131
+ export function timelinePageId(clientId) {
132
+ return 'page_timeline_' + String(clientId)
133
+ }
134
+
135
+ /** Stable facts-page key for one (subject, matter) pair. */
136
+ export function factsPageKey(subject, matterId) {
137
+ return sha256Hex(String(subject) + '|' + String(matterId ?? '')).slice(0, 12)
138
+ }
139
+
140
+ export function factsPageId(subject, matterId) {
141
+ return 'page_facts_' + factsPageKey(subject, matterId)
142
+ }
143
+
144
+ /** Parse a stable page id back into an identity ({kind, clientId|projectId|hash}). */
145
+ export function parseKbPageId(id) {
146
+ const text = String(id ?? '')
147
+ let match = /^page_client_(.+)$/.exec(text)
148
+ if (match) return { kind: 'client', clientId: match[1] }
149
+ match = /^page_timeline_(.+)$/.exec(text)
150
+ if (match) return { kind: 'timeline', clientId: match[1] }
151
+ match = /^page_project_(.+)$/.exec(text)
152
+ if (match) return { kind: 'project', projectId: match[1] }
153
+ match = /^page_facts_([0-9a-f]{12})$/.exec(text)
154
+ if (match) return { kind: 'facts', key: match[1] }
155
+ return null
156
+ }
157
+
158
+ /* -------------------------------------------------------------------------- */
159
+ /* owner / clearance helpers */
160
+ /* -------------------------------------------------------------------------- */
161
+
162
+ function loadOwnerMaps(store) {
163
+ const clients = new Map(store.db.prepare('SELECT id, secrecy_default FROM clients').all().map((row) => [String(row.id), Number(row.secrecy_default ?? 0)]))
164
+ const matters = new Map(store.db.prepare('SELECT id, secrecy, client_id FROM matters').all().map((row) => [String(row.id), { secrecy: Number(row.secrecy ?? 0), clientId: stringOrNull(row.client_id) }]))
165
+ const projects = new Map(store.db.prepare('SELECT id, client_id FROM projects').all().map((row) => [String(row.id), stringOrNull(row.client_id)]))
166
+ return { clients, matters, projects }
167
+ }
168
+
169
+ function ownerSecrecy(maps, owner) {
170
+ if (!owner) return Number.POSITIVE_INFINITY
171
+ let level = 0
172
+ if (owner.clientId) {
173
+ const value = maps.clients.get(String(owner.clientId))
174
+ if (value === undefined) return Number.POSITIVE_INFINITY
175
+ level = Math.max(level, value)
176
+ }
177
+ if (owner.matterId) {
178
+ const matter = maps.matters.get(String(owner.matterId))
179
+ if (!matter) return Number.POSITIVE_INFINITY
180
+ level = Math.max(level, matter.secrecy)
181
+ if (matter.clientId) {
182
+ const value = maps.clients.get(matter.clientId)
183
+ if (value === undefined) return Number.POSITIVE_INFINITY
184
+ level = Math.max(level, value)
185
+ }
186
+ }
187
+ return level
188
+ }
189
+
190
+ function pageOwnerFromRow(row, maps) {
191
+ let data = null
192
+ try { data = JSON.parse(String(row.json ?? '')) } catch { data = null }
193
+ if (data && data.owner && typeof data.owner === 'object') {
194
+ return { clientId: stringOrNull(data.owner.clientId), matterId: stringOrNull(data.owner.matterId) }
195
+ }
196
+ const kind = String(row.kind)
197
+ if (kind === 'client' || kind === 'timeline') return { clientId: String(row.subject_id), matterId: null }
198
+ if (kind === 'project') {
199
+ const clientId = maps.projects.get(String(row.subject_id))
200
+ return clientId === undefined ? null : { clientId, matterId: null }
201
+ }
202
+ return null
203
+ }
204
+
205
+ /* -------------------------------------------------------------------------- */
206
+ /* source refs */
207
+ /* -------------------------------------------------------------------------- */
208
+
209
+ function collectSourceRefs(data) {
210
+ const refs = []
211
+ const seen = new Set()
212
+ const push = (kind, id) => {
213
+ if (id === undefined || id === null || id === '') return
214
+ const key = kind + ':' + String(id)
215
+ if (seen.has(key)) return
216
+ seen.add(key)
217
+ refs.push({ kind, id: String(id) })
218
+ }
219
+ const pushOpen = (open) => {
220
+ for (const item of [...(open?.mine ?? []), ...(open?.waiting ?? [])]) push('commitment', item.id)
221
+ }
222
+ if (data.kind === 'client' || data.kind === 'timeline') {
223
+ push('client', data.client.id)
224
+ for (const project of data.projects ?? []) push('project', project.id)
225
+ for (const item of data.timeline ?? []) push(item.ref.kind, item.ref.id)
226
+ pushOpen(data.open)
227
+ for (const fact of data.facts ?? []) push('fact', fact.id)
228
+ } else if (data.kind === 'project') {
229
+ push('client', data.client.id)
230
+ push('project', data.project.id)
231
+ for (const matter of data.matters ?? []) push('matter', matter.id)
232
+ for (const delivery of data.deliveries ?? []) push('delivery', delivery.id)
233
+ pushOpen(data.open)
234
+ } else if (data.kind === 'facts') {
235
+ if (data.matterId) push('matter', data.matterId)
236
+ if (data.owner && data.owner.clientId) push('client', data.owner.clientId)
237
+ for (const fact of data.facts ?? []) push('fact', fact.id)
238
+ }
239
+ refs.sort((a, b) => (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
240
+ return refs
241
+ }
242
+
243
+ /* -------------------------------------------------------------------------- */
244
+ /* fact views */
245
+ /* -------------------------------------------------------------------------- */
246
+
247
+ function parseJsonArray(value) {
248
+ if (value === undefined || value === null) return []
249
+ try {
250
+ const parsed = typeof value === 'string' ? JSON.parse(value) : value
251
+ return Array.isArray(parsed) ? parsed : []
252
+ } catch { return [] }
253
+ }
254
+
255
+ function factEvidence(evidence) {
256
+ const out = []
257
+ for (const item of parseJsonArray(evidence)) {
258
+ if (!item || typeof item !== 'object') continue
259
+ const quote = stringOrNull(item.quote) ?? stringOrNull(item.source && item.source.quote)
260
+ const ref = stringOrNull(item.ref) ?? (item.sessionId ? String(item.sessionId) + '#' + String(item.turnId ?? '') : null)
261
+ if (!quote && !ref) continue
262
+ out.push({
263
+ ...(quote ? { quote: sanitizeInline(quote, FACT_QUOTE_MAX) } : {}),
264
+ ...(ref ? { ref } : {}),
265
+ })
266
+ if (out.length >= 3) break
267
+ }
268
+ return out
269
+ }
270
+
271
+ function factView(row) {
272
+ return {
273
+ id: String(row.id),
274
+ subject: String(row.subject ?? ''),
275
+ predicate: String(row.predicate ?? ''),
276
+ object: sanitizeInline(row.object, 500),
277
+ ...(row.matter_id === null || row.matter_id === undefined ? {} : { matterId: String(row.matter_id) }),
278
+ authority: String(row.authority ?? ''),
279
+ confidence: Number(row.confidence ?? 0),
280
+ status: String(row.status ?? ''),
281
+ recordedAt: String(row.recorded_at ?? ''),
282
+ ...(row.valid_from === null || row.valid_from === undefined ? {} : { validFrom: String(row.valid_from) }),
283
+ ...(row.valid_to === null || row.valid_to === undefined ? {} : { validTo: String(row.valid_to) }),
284
+ ...(row.supersedes === null || row.supersedes === undefined ? {} : { supersedes: String(row.supersedes) }),
285
+ ...(row.superseded_by === null || row.superseded_by === undefined ? {} : { supersededBy: String(row.superseded_by) }),
286
+ evidence: factEvidence(row.evidence),
287
+ }
288
+ }
289
+
290
+ function currentFactsForClient(store, clientId, clearance, clientSecrecyDefault) {
291
+ const matters = store.listMattersByClient(clientId).filter((matter) => Math.max(Number(clientSecrecyDefault ?? 0), Number(matter.secrecy ?? 0)) <= clearance)
292
+ if (!matters.length) return []
293
+ const placeholders = matters.map(() => '?').join(',')
294
+ const rows = store.db.prepare("SELECT id, matter_id, subject, predicate, object, authority, confidence, valid_from, valid_to, supersedes, superseded_by, evidence, recorded_at, status FROM facts WHERE deleted_at IS NULL AND status = 'confirmed' AND matter_id IN (" + placeholders + ') ORDER BY subject ASC, predicate ASC, matter_id ASC, recorded_at ASC, id ASC LIMIT 50')
295
+ .all(...matters.map((matter) => String(matter.id)))
296
+ return rows.map(factView)
297
+ }
298
+
299
+ /* -------------------------------------------------------------------------- */
300
+ /* page data builders (pure projections; no wall clock) */
301
+ /* -------------------------------------------------------------------------- */
302
+
303
+ function pickCounts(counts) {
304
+ const source = counts ?? {}
305
+ return {
306
+ matters: Number(source.matters ?? 0),
307
+ mattersArchived: Number(source.mattersArchived ?? 0),
308
+ deliveries: Number(source.deliveries ?? 0),
309
+ notes: Number(source.notes ?? 0),
310
+ commitments: Number(source.commitments ?? 0),
311
+ openMine: Number(source.openMine ?? 0),
312
+ openWaiting: Number(source.openWaiting ?? 0),
313
+ }
314
+ }
315
+
316
+ function pickOpenItem(item) {
317
+ return {
318
+ id: String(item.id),
319
+ action: sanitizeInline(item.action, 200),
320
+ debtor: String(item.debtor ?? ''),
321
+ creditor: String(item.creditor ?? ''),
322
+ ...(item.matterId === undefined ? {} : { matterId: String(item.matterId) }),
323
+ ...(item.dueAt === undefined ? {} : { dueAt: String(item.dueAt) }),
324
+ ...(item.projectId === undefined ? {} : { projectId: String(item.projectId) }),
325
+ }
326
+ }
327
+
328
+ function pickTimelineItem(item) {
329
+ return {
330
+ at: String(item.at),
331
+ kind: String(item.kind),
332
+ title: sanitizeInline(item.title, 200),
333
+ ref: { kind: String(item.ref.kind), id: String(item.ref.id) },
334
+ ...(item.matterId === undefined ? {} : { matterId: String(item.matterId) }),
335
+ }
336
+ }
337
+
338
+ function clientPageData(status, facts, timelineLimit = 20) {
339
+ const client = status.client
340
+ const timeline = (status.timeline ?? []).slice(0, timelineLimit).map(pickTimelineItem)
341
+ const timelineTotal = Number(status.timelineTotal ?? (status.timeline ?? []).length)
342
+ return {
343
+ version: 1,
344
+ kind: 'client',
345
+ generator: KB_PAGE_GENERATOR,
346
+ owner: { clientId: String(client.id), matterId: null },
347
+ client: {
348
+ id: String(client.id),
349
+ name: sanitizeInline(client.name, 200),
350
+ status: String(client.status ?? ''),
351
+ aliases: (client.aliases ?? []).map((alias) => sanitizeInline(alias, 80)),
352
+ tags: (client.tags ?? []).map((tag) => sanitizeInline(tag, 80)),
353
+ secrecyDefault: Number(client.secrecyDefault ?? 0),
354
+ },
355
+ counts: pickCounts(status.counts),
356
+ nextDueAt: status.nextDueAt ?? null,
357
+ projects: (status.projects ?? []).map((project) => ({
358
+ id: String(project.id),
359
+ name: sanitizeInline(project.name, 200),
360
+ status: String(project.status ?? ''),
361
+ counts: pickCounts(project.counts),
362
+ nextDueAt: project.nextDueAt ?? null,
363
+ })),
364
+ open: {
365
+ mine: (status.open?.mine ?? []).map(pickOpenItem),
366
+ waiting: (status.open?.waiting ?? []).map(pickOpenItem),
367
+ mineTotal: Number(status.open?.mineTotal ?? 0),
368
+ waitingTotal: Number(status.open?.waitingTotal ?? 0),
369
+ },
370
+ timeline,
371
+ timelineTotal,
372
+ timelineTruncated: timelineTotal > timeline.length,
373
+ facts,
374
+ protectedExcluded: Number(status.protectedExcluded ?? 0),
375
+ }
376
+ }
377
+
378
+ function timelinePageData(status, timelineLimit = 100) {
379
+ const client = status.client
380
+ const timeline = (status.timeline ?? []).slice(0, timelineLimit).map(pickTimelineItem)
381
+ const timelineTotal = Number(status.timelineTotal ?? (status.timeline ?? []).length)
382
+ return {
383
+ version: 1,
384
+ kind: 'timeline',
385
+ generator: KB_PAGE_GENERATOR,
386
+ owner: { clientId: String(client.id), matterId: null },
387
+ client: { id: String(client.id), name: sanitizeInline(client.name, 200), status: String(client.status ?? '') },
388
+ timeline,
389
+ timelineTotal,
390
+ timelineTruncated: timelineTotal > timeline.length,
391
+ protectedExcluded: Number(status.protectedExcluded ?? 0),
392
+ }
393
+ }
394
+
395
+ function projectPageData(store, client, projectRow, projectStatus, status, clearance) {
396
+ const clientLevel = Number(client.secrecyDefault ?? 0)
397
+ if (clientLevel > clearance) return null
398
+ const matterRows = store.listMattersByProject(projectRow.id)
399
+ const visibleMatters = []
400
+ let protectedMatters = 0
401
+ for (const matter of matterRows) {
402
+ if (Math.max(clientLevel, Number(matter.secrecy ?? 0)) <= clearance) visibleMatters.push(matter)
403
+ else protectedMatters += 1
404
+ }
405
+ const matterIds = visibleMatters.map((matter) => String(matter.id))
406
+ const allowed = new Set(matterIds)
407
+ let deliveries = []
408
+ if (matterIds.length) {
409
+ const placeholders = matterIds.map(() => '?').join(',')
410
+ deliveries = store.db.prepare('SELECT id, matter_id, title, tool, created_at FROM deliveries WHERE matter_id IN (' + placeholders + ') ORDER BY created_at DESC, rowid DESC LIMIT ?')
411
+ .all(...matterIds, DELIVERY_PREVIEW_MAX)
412
+ }
413
+ const pickProjectOpen = (items) => (items ?? [])
414
+ .filter((item) => item.matterId !== undefined && allowed.has(String(item.matterId)))
415
+ .map(pickOpenItem)
416
+ return {
417
+ version: 1,
418
+ kind: 'project',
419
+ generator: KB_PAGE_GENERATOR,
420
+ owner: { clientId: String(client.id), matterId: null },
421
+ project: {
422
+ id: String(projectRow.id),
423
+ name: sanitizeInline(projectRow.name, 200),
424
+ status: String(projectRow.status ?? ''),
425
+ startedAt: projectRow.startedAt ?? null,
426
+ dueAt: projectRow.dueAt ?? null,
427
+ defaultMatterId: projectRow.defaultMatterId ?? null,
428
+ createdAt: projectRow.createdAt ?? null,
429
+ updatedAt: projectRow.updatedAt ?? null,
430
+ },
431
+ client: { id: String(client.id), name: sanitizeInline(client.name, 200), status: String(client.status ?? ''), secrecyDefault: clientLevel },
432
+ counts: pickCounts(projectStatus?.counts),
433
+ nextDueAt: projectStatus?.nextDueAt ?? null,
434
+ matters: visibleMatters.map((matter) => ({ id: String(matter.id), title: sanitizeInline(matter.title, 200), status: String(matter.status ?? '') })),
435
+ deliveries: deliveries.map((delivery) => ({
436
+ id: String(delivery.id),
437
+ matterId: String(delivery.matter_id),
438
+ title: sanitizeInline(delivery.title ?? delivery.tool ?? delivery.id, 200),
439
+ tool: delivery.tool === null || delivery.tool === undefined ? null : sanitizeInline(delivery.tool, 80),
440
+ createdAt: String(delivery.created_at ?? ''),
441
+ })),
442
+ open: {
443
+ mine: pickProjectOpen(status.open?.mine),
444
+ waiting: pickProjectOpen(status.open?.waiting),
445
+ mineTotal: Number(projectStatus?.counts?.openMine ?? 0),
446
+ waitingTotal: Number(projectStatus?.counts?.openWaiting ?? 0),
447
+ },
448
+ protectedExcluded: protectedMatters + Number(status.protectedExcluded ?? 0),
449
+ }
450
+ }
451
+
452
+ function factsPageData(store, subject, matterId, clearance) {
453
+ const matter = matterId === null || matterId === undefined ? undefined : store.getMatter(String(matterId))
454
+ if (matterId !== null && matterId !== undefined && !matter) return null
455
+ const client = matter && matter.clientId ? store.getClient(String(matter.clientId)) : undefined
456
+ if (matter && matter.clientId && !client) return null
457
+ const level = Math.max(Number(client?.secrecyDefault ?? 0), Number(matter?.secrecy ?? 0))
458
+ if (level > clearance) return null
459
+ const rows = store.db.prepare("SELECT id, matter_id, subject, predicate, object, authority, confidence, status, recorded_at, valid_from, valid_to, supersedes, superseded_by, evidence FROM facts WHERE subject = ? AND (matter_id IS ?) AND deleted_at IS NULL ORDER BY recorded_at ASC, id ASC LIMIT ?")
460
+ .all(String(subject), matterId === null || matterId === undefined ? null : String(matterId), KB_PAGE_FACTS_PER_GROUP_MAX)
461
+ if (!rows.length) return null
462
+ return {
463
+ version: 1,
464
+ kind: 'facts',
465
+ generator: KB_PAGE_GENERATOR,
466
+ owner: { clientId: client ? String(client.id) : null, matterId: matter ? String(matter.id) : null },
467
+ subject: sanitizeInline(subject, 200),
468
+ matterId: matter ? String(matter.id) : null,
469
+ facts: rows.map(factView),
470
+ }
471
+ }
472
+
473
+ /* -------------------------------------------------------------------------- */
474
+ /* markdown renderers (pure functions of the data) */
475
+ /* -------------------------------------------------------------------------- */
476
+
477
+ function table(header, rows) {
478
+ const lines = ['| ' + header.join(' | ') + ' |', '| ' + header.map(() => '---').join(' | ') + ' |']
479
+ for (const row of rows) lines.push('| ' + row.join(' | ') + ' |')
480
+ return lines
481
+ }
482
+
483
+ function countsLine(counts) {
484
+ return 'matters ' + counts.matters + ' (archived ' + counts.mattersArchived + '), deliveries ' + counts.deliveries
485
+ + ', notes ' + counts.notes + ', commitments ' + counts.commitments
486
+ + ', open mine ' + counts.openMine + ', open waiting ' + counts.openWaiting
487
+ }
488
+
489
+ function openLines(items) {
490
+ return items.map((item) => '- [ ] ' + cell(item.action) + ' (' + cell(item.matterId ?? '-') + ')' + (item.dueAt ? ' due ' + cell(item.dueAt) : ''))
491
+ }
492
+
493
+ function timelineLines(items) {
494
+ return items.map((item) => '- ' + cell(item.at) + ' ' + cell(item.kind) + ': ' + cell(item.title) + ' (' + cell(item.ref.kind) + ':' + cell(item.ref.id) + ')')
495
+ }
496
+
497
+ function factLines(items) {
498
+ return items.map((fact) => '- ' + cell(fact.predicate) + ' = ' + cell(fact.object)
499
+ + (fact.validFrom ? ' (from ' + cell(fact.validFrom) + ')' : '')
500
+ + (fact.validTo ? ' (until ' + cell(fact.validTo) + ')' : '')
501
+ + ' [' + cell(fact.status) + ']')
502
+ }
503
+
504
+ function renderClientMarkdown(data) {
505
+ const lines = []
506
+ lines.push('# Client: ' + sanitizeInline(data.client.name))
507
+ lines.push('')
508
+ lines.push('- id: ' + data.client.id)
509
+ lines.push('- status: ' + data.client.status)
510
+ lines.push('- aliases: ' + (data.client.aliases.length ? data.client.aliases.join(', ') : '(none)'))
511
+ lines.push('- tags: ' + (data.client.tags.length ? data.client.tags.join(', ') : '(none)'))
512
+ lines.push('- secrecy default: ' + data.client.secrecyDefault)
513
+ lines.push('- next due: ' + (data.nextDueAt ?? '(none)'))
514
+ lines.push('- counts: ' + countsLine(data.counts))
515
+ if (data.protectedExcluded > 0) lines.push('- protected excluded: ' + data.protectedExcluded)
516
+ lines.push('')
517
+ lines.push('## Projects')
518
+ if (!data.projects.length) lines.push('(none)')
519
+ else lines.push(...table(['Project', 'Status', 'Matters', 'Deliveries', 'Commitments', 'Next due'], data.projects.map((project) => [
520
+ cell(project.name),
521
+ cell(project.status),
522
+ String(project.counts.matters),
523
+ String(project.counts.deliveries),
524
+ String(project.counts.commitments),
525
+ cell(project.nextDueAt ?? '(none)'),
526
+ ])))
527
+ lines.push('')
528
+ lines.push('## Open commitments (mine)')
529
+ lines.push(...(data.open.mine.length ? openLines(data.open.mine) : ['(none)']))
530
+ lines.push('')
531
+ lines.push('## Open commitments (waiting on client)')
532
+ lines.push(...(data.open.waiting.length ? openLines(data.open.waiting) : ['(none)']))
533
+ lines.push('')
534
+ lines.push('## Timeline (' + data.timeline.length + ' of ' + data.timelineTotal + ')')
535
+ lines.push(...(data.timeline.length ? timelineLines(data.timeline) : ['(none)']))
536
+ lines.push('')
537
+ lines.push('## Facts')
538
+ lines.push(...(data.facts.length ? factLines(data.facts) : ['(none)']))
539
+ lines.push('')
540
+ lines.push('_generator: ' + data.generator + '_')
541
+ return lines.join('\n')
542
+ }
543
+
544
+ function renderProjectMarkdown(data) {
545
+ const lines = []
546
+ lines.push('# Project: ' + sanitizeInline(data.project.name))
547
+ lines.push('')
548
+ lines.push('- id: ' + data.project.id)
549
+ lines.push('- client: ' + data.client.id + ' (' + data.client.name + ')')
550
+ lines.push('- status: ' + data.project.status)
551
+ lines.push('- started at: ' + (data.project.startedAt ?? '(none)'))
552
+ lines.push('- due at: ' + (data.project.dueAt ?? '(none)'))
553
+ lines.push('- default matter: ' + (data.project.defaultMatterId ?? '(none)'))
554
+ lines.push('- next due: ' + (data.nextDueAt ?? '(none)'))
555
+ lines.push('- counts: ' + countsLine(data.counts))
556
+ if (data.protectedExcluded > 0) lines.push('- protected excluded: ' + data.protectedExcluded)
557
+ lines.push('')
558
+ lines.push('## Matters')
559
+ if (!data.matters.length) lines.push('(none)')
560
+ else lines.push(...table(['Matter', 'Status', 'Title'], data.matters.map((matter) => [cell(matter.id), cell(matter.status), cell(matter.title)])))
561
+ lines.push('')
562
+ lines.push('## Deliveries (' + data.deliveries.length + ' shown)')
563
+ if (!data.deliveries.length) lines.push('(none)')
564
+ else for (const delivery of data.deliveries) lines.push('- ' + cell(delivery.createdAt) + ' ' + cell(delivery.title) + ' (' + cell(delivery.id) + ')')
565
+ lines.push('')
566
+ lines.push('## Open commitments (mine)')
567
+ lines.push(...(data.open.mine.length ? openLines(data.open.mine) : ['(none)']))
568
+ lines.push('')
569
+ lines.push('## Open commitments (waiting on client)')
570
+ lines.push(...(data.open.waiting.length ? openLines(data.open.waiting) : ['(none)']))
571
+ lines.push('')
572
+ lines.push('_generator: ' + data.generator + '_')
573
+ return lines.join('\n')
574
+ }
575
+
576
+ function renderTimelineMarkdown(data) {
577
+ const lines = []
578
+ lines.push('# Timeline: ' + sanitizeInline(data.client.name))
579
+ lines.push('')
580
+ lines.push('- client: ' + data.client.id)
581
+ lines.push('- events: ' + data.timeline.length + ' of ' + data.timelineTotal)
582
+ if (data.protectedExcluded > 0) lines.push('- protected excluded: ' + data.protectedExcluded)
583
+ lines.push('')
584
+ lines.push('## Events')
585
+ lines.push(...(data.timeline.length ? timelineLines(data.timeline) : ['(none)']))
586
+ lines.push('')
587
+ lines.push('_generator: ' + data.generator + '_')
588
+ return lines.join('\n')
589
+ }
590
+
591
+ function renderFactsMarkdown(data) {
592
+ const lines = []
593
+ lines.push('# Facts: ' + sanitizeInline(data.subject))
594
+ lines.push('')
595
+ if (data.matterId) lines.push('- matter: ' + data.matterId)
596
+ if (data.owner.clientId) lines.push('- client: ' + data.owner.clientId)
597
+ lines.push('')
598
+ lines.push('## Facts')
599
+ if (!data.facts.length) lines.push('(none)')
600
+ for (const fact of data.facts) {
601
+ lines.push('### ' + cell(fact.predicate) + ' = ' + cell(fact.object))
602
+ lines.push('')
603
+ lines.push('- status: ' + fact.status)
604
+ lines.push('- authority: ' + fact.authority + ', confidence: ' + fact.confidence)
605
+ lines.push('- recorded at: ' + fact.recordedAt)
606
+ lines.push('- valid from: ' + (fact.validFrom ?? '(none)'))
607
+ lines.push('- valid to: ' + (fact.validTo ?? '(none)'))
608
+ if (fact.supersedes) lines.push('- supersedes: ' + fact.supersedes)
609
+ if (fact.supersededBy) lines.push('- superseded by: ' + fact.supersededBy)
610
+ for (const evidence of fact.evidence) {
611
+ lines.push('- evidence: ' + (evidence.quote ?? '') + (evidence.ref ? ' [' + evidence.ref + ']' : ''))
612
+ }
613
+ lines.push('')
614
+ }
615
+ lines.push('_generator: ' + data.generator + '_')
616
+ return lines.join('\n')
617
+ }
618
+
619
+ function pageTitle(data) {
620
+ if (data.kind === 'client') return 'Client: ' + data.client.name
621
+ if (data.kind === 'project') return 'Project: ' + data.project.name
622
+ if (data.kind === 'timeline') return 'Timeline: ' + data.client.name
623
+ return 'Facts: ' + data.subject
624
+ }
625
+
626
+ function renderMarkdown(data) {
627
+ if (data.kind === 'client') return renderClientMarkdown(data)
628
+ if (data.kind === 'project') return renderProjectMarkdown(data)
629
+ if (data.kind === 'timeline') return renderTimelineMarkdown(data)
630
+ return renderFactsMarkdown(data)
631
+ }
632
+
633
+ /* -------------------------------------------------------------------------- */
634
+ /* page assembly + builders */
635
+ /* -------------------------------------------------------------------------- */
636
+
637
+ function makePage(pageId, subjectId, data) {
638
+ const json = canonicalJson(data)
639
+ return {
640
+ id: String(pageId),
641
+ kind: String(data.kind),
642
+ subjectId: String(subjectId),
643
+ title: sanitizeInline(pageTitle(data), 200),
644
+ markdown: renderMarkdown(data),
645
+ json,
646
+ sourceRefs: collectSourceRefs(data),
647
+ inputsSha256: sha256Hex(json),
648
+ data,
649
+ }
650
+ }
651
+
652
+ function buildClientPage(status, facts) {
653
+ return makePage(clientPageId(status.client.id), status.client.id, clientPageData(status, facts))
654
+ }
655
+
656
+ function buildTimelinePage(status) {
657
+ return makePage(timelinePageId(status.client.id), status.client.id, timelinePageData(status))
658
+ }
659
+
660
+ function buildProjectPage(store, client, projectRow, projectStatus, status, clearance) {
661
+ const data = projectPageData(store, client, projectRow, projectStatus, status, clearance)
662
+ if (!data) return null
663
+ return makePage(projectPageId(projectRow.id), projectRow.id, data)
664
+ }
665
+
666
+ function buildFactsPage(store, subject, matterId, clearance) {
667
+ const data = factsPageData(store, subject, matterId, clearance)
668
+ if (!data) return null
669
+ const key = matterId === null || matterId === undefined ? null : String(matterId)
670
+ return makePage(factsPageId(subject, key), factsPageKey(subject, key), data)
671
+ }
672
+
673
+ function buildAllPages(store, { clearance, kind = null }) {
674
+ const pages = []
675
+ const degraded = []
676
+ let skipped = 0
677
+ const want = (value) => kind === null || kind === value
678
+ const clients = store.listClients({ status: 'all', includeDeleted: false, limit: 1000 })
679
+ for (const client of clients) {
680
+ const clientLevel = Number(client.secrecyDefault ?? 0)
681
+ if (clientLevel > clearance) { skipped += 1; continue }
682
+ let status = null
683
+ try {
684
+ status = readClientStatus(store, client.id, { clearance, timelineLimit: 100, openLimit: 20 })
685
+ } catch (error) {
686
+ degraded.push('client_read_failed')
687
+ skipped += 1
688
+ continue
689
+ }
690
+ if (!status) { skipped += 1; continue }
691
+ if (want('client')) pages.push(buildClientPage(status, currentFactsForClient(store, client.id, clearance, clientLevel)))
692
+ if (want('timeline')) pages.push(buildTimelinePage(status))
693
+ if (want('project')) {
694
+ for (const projectStatus of status.projects ?? []) {
695
+ const projectRow = typeof store.getProject === 'function' ? store.getProject(projectStatus.id) : undefined
696
+ if (!projectRow) { skipped += 1; continue }
697
+ const page = buildProjectPage(store, client, projectRow, projectStatus, status, clearance)
698
+ if (page) pages.push(page)
699
+ else skipped += 1
700
+ }
701
+ }
702
+ }
703
+ if (want('facts')) {
704
+ const groups = store.db.prepare('SELECT subject, matter_id FROM facts WHERE deleted_at IS NULL GROUP BY subject, matter_id ORDER BY subject ASC, matter_id ASC LIMIT ?').all(KB_PAGE_FACTS_MAX + 1)
705
+ if (groups.length > KB_PAGE_FACTS_MAX) {
706
+ degraded.push('facts_pages_capped')
707
+ groups.length = KB_PAGE_FACTS_MAX
708
+ }
709
+ for (const group of groups) {
710
+ if (group.subject === null || group.subject === undefined) { skipped += 1; continue }
711
+ const matterId = group.matter_id === null || group.matter_id === undefined ? null : String(group.matter_id)
712
+ const page = buildFactsPage(store, group.subject, matterId, clearance)
713
+ if (page) pages.push(page)
714
+ else skipped += 1
715
+ }
716
+ }
717
+ return { pages, degraded: [...new Set(degraded)].sort(), skipped }
718
+ }
719
+
720
+ function buildPageByIdentity(store, identity, { clearance, storedRow = null } = {}) {
721
+ if (!identity) return null
722
+ if (identity.kind === 'client' || identity.kind === 'timeline') {
723
+ const client = typeof store.getClient === 'function' ? store.getClient(identity.clientId) : undefined
724
+ if (!client || client.deletedAt) return null
725
+ const clientLevel = Number(client.secrecyDefault ?? 0)
726
+ if (clientLevel > clearance) return null
727
+ const status = readClientStatus(store, client.id, { clearance, timelineLimit: 100, openLimit: 20 })
728
+ if (!status) return null
729
+ if (identity.kind === 'client') return buildClientPage(status, currentFactsForClient(store, client.id, clearance, clientLevel))
730
+ return buildTimelinePage(status)
731
+ }
732
+ if (identity.kind === 'project') {
733
+ const project = typeof store.getProject === 'function' ? store.getProject(identity.projectId) : undefined
734
+ if (!project || project.deletedAt) return null
735
+ const client = typeof store.getClient === 'function' ? store.getClient(project.clientId) : undefined
736
+ if (!client || client.deletedAt) return null
737
+ const clientLevel = Number(client.secrecyDefault ?? 0)
738
+ if (clientLevel > clearance) return null
739
+ const status = readClientStatus(store, client.id, { clearance, timelineLimit: 100, openLimit: 20 })
740
+ if (!status) return null
741
+ const projectStatus = (status.projects ?? []).find((projectRow) => projectRow.id === project.id)
742
+ return buildProjectPage(store, client, project, projectStatus, status, clearance)
743
+ }
744
+ if (identity.kind === 'facts') {
745
+ let subject = null
746
+ let matterId = null
747
+ if (storedRow) {
748
+ try {
749
+ const data = JSON.parse(String(storedRow.json ?? ''))
750
+ subject = stringOrNull(data.subject)
751
+ matterId = stringOrNull(data.matterId)
752
+ } catch { subject = null }
753
+ }
754
+ if (subject === null) return null
755
+ return buildFactsPage(store, subject, matterId, clearance)
756
+ }
757
+ return null
758
+ }
759
+
760
+ /* -------------------------------------------------------------------------- */
761
+ /* stored views + public API */
762
+ /* -------------------------------------------------------------------------- */
763
+
764
+ function normalizeClearance(value) {
765
+ const number = Number(value)
766
+ if (!Number.isFinite(number) || number < 0) return 0
767
+ return Math.floor(number)
768
+ }
769
+
770
+ function clampLimit(value, fallback, max) {
771
+ if (value === undefined || value === null) return fallback
772
+ const number = Number(value)
773
+ if (!Number.isInteger(number) || number < 1) return fallback
774
+ return Math.min(number, max)
775
+ }
776
+
777
+ function storedPageView(row) {
778
+ let data = null
779
+ try { data = JSON.parse(String(row.json ?? '')) } catch { data = null }
780
+ let sourceRefs = []
781
+ try {
782
+ const parsed = JSON.parse(String(row.source_refs ?? '[]'))
783
+ if (Array.isArray(parsed)) sourceRefs = parsed
784
+ } catch { sourceRefs = [] }
785
+ return {
786
+ id: String(row.id),
787
+ kind: String(row.kind),
788
+ subjectId: String(row.subject_id),
789
+ title: sanitizeInline(row.title, 200),
790
+ markdown: String(row.markdown ?? ''),
791
+ data,
792
+ sourceRefs,
793
+ inputsSha256: String(row.inputs_sha256),
794
+ generatedAt: String(row.generated_at),
795
+ status: String(row.status),
796
+ }
797
+ }
798
+
799
+ function livePageView(page) {
800
+ return {
801
+ id: page.id,
802
+ kind: page.kind,
803
+ subjectId: page.subjectId,
804
+ title: page.title,
805
+ markdown: page.markdown,
806
+ data: page.data,
807
+ sourceRefs: page.sourceRefs,
808
+ inputsSha256: page.inputsSha256,
809
+ generatedAt: null,
810
+ status: 'live',
811
+ }
812
+ }
813
+
814
+ /**
815
+ * List stored pages. check:true recomputes every page against the live ledger
816
+ * and reports stale/staleReason (pure read; nothing is written).
817
+ */
818
+ export function kbPageList(store, options = {}) {
819
+ assertKbPagesSchema(store)
820
+ const kind = options.kind === undefined || options.kind === null ? null : String(options.kind)
821
+ if (kind !== null && !KB_PAGE_KINDS.includes(kind)) throw entityError('E_KB_INVALID', 'unknown page kind: ' + kind, 'use one of ' + KB_PAGE_KINDS.join(', '))
822
+ const check = options.check === true
823
+ const clearance = normalizeClearance(options.clearance === undefined ? 3 : options.clearance)
824
+ const limit = clampLimit(options.limit, KB_PAGE_LIST_LIMIT, KB_PAGE_LIST_LIMIT_MAX)
825
+ const filterId = options.id === undefined || options.id === null ? null : String(options.id)
826
+ return store.read(() => {
827
+ const maps = loadOwnerMaps(store)
828
+ const rows = store.db.prepare('SELECT * FROM kb_pages WHERE deleted_at IS NULL ORDER BY kind ASC, id ASC').all()
829
+ const summaries = []
830
+ let protectedExcluded = 0
831
+ let staleCount = 0
832
+ for (const row of rows) {
833
+ if (kind !== null && String(row.kind) !== kind) continue
834
+ if (filterId !== null && String(row.id) !== filterId) continue
835
+ const owner = pageOwnerFromRow(row, maps)
836
+ const level = ownerSecrecy(maps, owner)
837
+ if (!Number.isFinite(level) || level > clearance) { protectedExcluded += 1; continue }
838
+ const summary = {
839
+ id: String(row.id),
840
+ kind: String(row.kind),
841
+ subjectId: String(row.subject_id),
842
+ title: sanitizeInline(row.title, 200),
843
+ generatedAt: String(row.generated_at),
844
+ status: String(row.status),
845
+ inputsSha256: String(row.inputs_sha256),
846
+ stale: null,
847
+ }
848
+ if (check) {
849
+ const identity = parseKbPageId(row.id)
850
+ let live = null
851
+ try { live = identity ? buildPageByIdentity(store, identity, { clearance, storedRow: row }) : null } catch { live = null }
852
+ if (!live) {
853
+ summary.stale = true
854
+ summary.staleReason = 'source_missing'
855
+ } else {
856
+ summary.stale = live.inputsSha256 !== String(row.inputs_sha256)
857
+ if (summary.stale) summary.staleReason = 'inputs_changed'
858
+ }
859
+ if (summary.stale) staleCount += 1
860
+ }
861
+ summaries.push(summary)
862
+ }
863
+ summaries.sort((a, b) => ((KIND_RANK[a.kind] ?? 9) - (KIND_RANK[b.kind] ?? 9)) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
864
+ const total = summaries.length
865
+ const pages = summaries.slice(0, limit)
866
+ return {
867
+ ok: true,
868
+ command: 'kb page ls',
869
+ pages,
870
+ total,
871
+ truncated: total > pages.length,
872
+ limit,
873
+ clearance,
874
+ protectedExcluded,
875
+ ...(check ? { staleCount } : {}),
876
+ }
877
+ })
878
+ }
879
+
880
+ /**
881
+ * Show one page. Default recomputes it live from the ledger (pure read) and
882
+ * reports stale vs the stored row; stored:true returns the stored content.
883
+ */
884
+ export function kbPageShow(store, id, options = {}) {
885
+ assertKbPagesSchema(store)
886
+ const key = typeof id === 'string' ? id.trim() : ''
887
+ if (!key) throw entityError('E_KB_INVALID', 'page id is required')
888
+ const stored = options.stored === true
889
+ const wantDiff = options.diff === true
890
+ const clearance = normalizeClearance(options.clearance === undefined ? 3 : options.clearance)
891
+ return store.read(() => {
892
+ const row = store.db.prepare('SELECT * FROM kb_pages WHERE id = ? AND deleted_at IS NULL').get(key) ?? null
893
+ const maps = loadOwnerMaps(store)
894
+ if (row) {
895
+ const owner = pageOwnerFromRow(row, maps)
896
+ const level = ownerSecrecy(maps, owner)
897
+ if (!Number.isFinite(level) || level > clearance) throw entityError('E_KB_PAGE_NOT_FOUND', 'unknown page: ' + key)
898
+ }
899
+ const identity = parseKbPageId(key)
900
+ if (!identity) throw entityError('E_KB_PAGE_NOT_FOUND', 'unknown page: ' + key)
901
+ if (stored && !row) throw entityError('E_KB_PAGE_NOT_FOUND', 'unknown page: ' + key)
902
+ const live = buildPageByIdentity(store, identity, { clearance, storedRow: row })
903
+ if (!live) {
904
+ if (!row) throw entityError('E_KB_PAGE_NOT_FOUND', 'unknown page: ' + key)
905
+ return {
906
+ ok: true,
907
+ command: 'kb page show',
908
+ page: storedPageView(row),
909
+ live: null,
910
+ stale: true,
911
+ staleReason: 'source_missing',
912
+ stored: { exists: true, inputsSha256: String(row.inputs_sha256), generatedAt: String(row.generated_at), status: String(row.status) },
913
+ clearance,
914
+ }
915
+ }
916
+ const stale = !row || String(row.inputs_sha256) !== live.inputsSha256
917
+ const page = stored && row ? storedPageView(row) : livePageView(live)
918
+ const result = {
919
+ ok: true,
920
+ command: 'kb page show',
921
+ page,
922
+ live: { inputsSha256: live.inputsSha256, markdown: live.markdown, data: live.data, sourceRefs: live.sourceRefs },
923
+ stale,
924
+ stored: {
925
+ exists: Boolean(row),
926
+ inputsSha256: row ? String(row.inputs_sha256) : null,
927
+ generatedAt: row ? String(row.generated_at) : null,
928
+ status: row ? String(row.status) : null,
929
+ },
930
+ clearance,
931
+ }
932
+ if (wantDiff && row && stale) result.diff = unifiedDiff(String(row.markdown ?? ''), live.markdown)
933
+ return result
934
+ })
935
+ }
936
+
937
+ /** Line-based unified diff (bounded LCS); no dependency and no DOM/HTML. */
938
+ export function unifiedDiff(before, after) {
939
+ const a = String(before ?? '').replace(/\r\n/g, '\n').split('\n')
940
+ const b = String(after ?? '').replace(/\r\n/g, '\n').split('\n')
941
+ if (a.length > 400 || b.length > 400) {
942
+ return '@@ page too large for an inline line diff @@' + '\n' + '- before: ' + a.length + ' lines' + '\n' + '+ after: ' + b.length + ' lines'
943
+ }
944
+ const n = a.length
945
+ const m = b.length
946
+ const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0))
947
+ for (let i = n - 1; i >= 0; i -= 1) {
948
+ for (let j = m - 1; j >= 0; j -= 1) {
949
+ dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
950
+ }
951
+ }
952
+ const lines = []
953
+ let i = 0
954
+ let j = 0
955
+ while (i < n && j < m) {
956
+ if (a[i] === b[j]) {
957
+ lines.push(' ' + a[i])
958
+ i += 1
959
+ j += 1
960
+ } else if (dp[i + 1][j] >= dp[i][j + 1]) {
961
+ lines.push('- ' + a[i])
962
+ i += 1
963
+ } else {
964
+ lines.push('+ ' + b[j])
965
+ j += 1
966
+ }
967
+ }
968
+ while (i < n) { lines.push('- ' + a[i]); i += 1 }
969
+ while (j < m) { lines.push('+ ' + b[j]); j += 1 }
970
+ return lines.join('\n')
971
+ }
972
+
973
+ function existingPageHashes(store) {
974
+ const map = new Map()
975
+ for (const row of store.db.prepare('SELECT id, inputs_sha256 FROM kb_pages').all()) map.set(String(row.id), String(row.inputs_sha256))
976
+ return map
977
+ }
978
+
979
+ function rebuildBuild(store, { clearance, kind, id }) {
980
+ if (id === null) return buildAllPages(store, { clearance, kind })
981
+ const stored = store.db.prepare('SELECT * FROM kb_pages WHERE id = ?').get(id) ?? null
982
+ const identity = parseKbPageId(id)
983
+ const page = buildPageByIdentity(store, identity, { clearance, storedRow: stored })
984
+ if (!page) throw entityError('E_KB_PAGE_NOT_FOUND', 'page cannot be derived: ' + id)
985
+ return { pages: [page], degraded: [], skipped: 0 }
986
+ }
987
+
988
+ /**
989
+ * Rebuild computed pages. This is the only write path: one transaction, one
990
+ * audit row, and only rows whose inputsSha256 changed are rewritten (so a
991
+ * no-op rebuild is byte-identical). dryRun computes the same plan without
992
+ * writing. onlyStale is accepted for CLI symmetry; the incremental rule above
993
+ * already writes only stale rows.
994
+ */
995
+ export function kbPageRebuild(store, options = {}) {
996
+ assertKbPagesSchema(store)
997
+ const kind = options.kind === undefined || options.kind === null ? null : String(options.kind)
998
+ if (kind !== null && !KB_PAGE_KINDS.includes(kind)) throw entityError('E_KB_INVALID', 'unknown page kind: ' + kind, 'use one of ' + KB_PAGE_KINDS.join(', '))
999
+ const id = options.id === undefined || options.id === null ? null : String(options.id)
1000
+ const clearance = normalizeClearance(options.clearance === undefined ? 3 : options.clearance)
1001
+ const dryRun = options.dryRun === true
1002
+ if (id !== null) {
1003
+ const identity = parseKbPageId(id)
1004
+ if (!identity) throw entityError('E_KB_PAGE_NOT_FOUND', 'unknown page id: ' + id)
1005
+ if (kind !== null && identity.kind !== kind) throw entityError('E_KB_INVALID', 'page id does not match kind ' + kind)
1006
+ }
1007
+ const plan = (built, existing) => {
1008
+ const written = []
1009
+ let unchanged = 0
1010
+ for (const page of built.pages) {
1011
+ if (existing.get(page.id) === page.inputsSha256) { unchanged += 1; continue }
1012
+ written.push(page)
1013
+ }
1014
+ return { written, unchanged }
1015
+ }
1016
+ if (dryRun) {
1017
+ return store.read(() => {
1018
+ const built = rebuildBuild(store, { clearance, kind, id })
1019
+ const planned = plan(built, existingPageHashes(store))
1020
+ return {
1021
+ ok: true,
1022
+ command: 'kb page rebuild',
1023
+ dryRun: true,
1024
+ counts: { built: built.pages.length, written: planned.written.length, unchanged: planned.unchanged, skipped: built.skipped },
1025
+ pages: planned.written.map((page) => ({ id: page.id, kind: page.kind })),
1026
+ degraded: built.degraded,
1027
+ clearance,
1028
+ }
1029
+ })
1030
+ }
1031
+ const audit = { actor: 'local', action: 'kb.page.rebuild', allowed: true, reason: '' }
1032
+ const outcome = store.mutate(() => {
1033
+ const built = rebuildBuild(store, { clearance, kind, id })
1034
+ const planned = plan(built, existingPageHashes(store))
1035
+ const generatedAt = new Date().toISOString()
1036
+ const insert = store.db.prepare('INSERT OR REPLACE INTO kb_pages(id,kind,subject_id,title,markdown,json,source_refs,inputs_sha256,generated_at,status,deleted_at) VALUES(?,?,?,?,?,?,?,?,?,?,?)')
1037
+ for (const page of planned.written) {
1038
+ insert.run(page.id, page.kind, page.subjectId, page.title, page.markdown, page.json, JSON.stringify(page.sourceRefs), page.inputsSha256, generatedAt, 'generated', null)
1039
+ }
1040
+ audit.reason = 'built ' + built.pages.length + ', written ' + planned.written.length + ', unchanged ' + planned.unchanged
1041
+ return { built: built.pages.length, written: planned.written, unchanged: planned.unchanged, skipped: built.skipped, degraded: built.degraded }
1042
+ }, audit)
1043
+ return {
1044
+ ok: true,
1045
+ command: 'kb page rebuild',
1046
+ dryRun: false,
1047
+ counts: { built: outcome.result.built, written: outcome.result.written.length, unchanged: outcome.result.unchanged, skipped: outcome.result.skipped },
1048
+ pages: outcome.result.written.map((page) => ({ id: page.id, kind: page.kind })),
1049
+ degraded: outcome.result.degraded,
1050
+ clearance,
1051
+ }
1052
+ }
1053
+
1054
+ /** Convenience wrapper for `kb page diff`: stale flag plus a bounded line diff. */
1055
+ export function kbPageDiff(store, id, options = {}) {
1056
+ const shown = kbPageShow(store, id, { ...options, diff: true })
1057
+ return { ok: true, command: 'kb page diff', pageId: shown.page.id, stale: shown.stale, diff: shown.diff ?? '' }
1058
+ }
1059
+
1060
+ export default Object.freeze({
1061
+ KB_PAGE_KINDS,
1062
+ KB_PAGE_GENERATOR,
1063
+ KB_PAGE_LIST_LIMIT,
1064
+ KB_PAGE_LIST_LIMIT_MAX,
1065
+ KB_PAGE_FACTS_MAX,
1066
+ KB_PAGE_FACTS_PER_GROUP_MAX,
1067
+ KB_PAGE_FACT_EVIDENCE_MAX,
1068
+ clientPageId,
1069
+ projectPageId,
1070
+ timelinePageId,
1071
+ factsPageKey,
1072
+ factsPageId,
1073
+ parseKbPageId,
1074
+ canonicalJson,
1075
+ sha256Hex,
1076
+ unifiedDiff,
1077
+ kbPageList,
1078
+ kbPageShow,
1079
+ kbPageRebuild,
1080
+ kbPageDiff,
1081
+ assertKbPagesSchema,
1082
+ })
1083
+
1084
+