advisers 0.2.3 → 0.3.1

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 (70) hide show
  1. package/LICENSE +0 -0
  2. package/NOTICE +0 -0
  3. package/README-zh.md +15 -6
  4. package/README.md +22 -6
  5. package/THIRD-PARTY-NOTICES.md +1 -1
  6. package/bin/advisers.js +3323 -222
  7. package/index.js +1 -1
  8. package/lib/agent.js +0 -0
  9. package/lib/attachments.js +0 -0
  10. package/lib/audit-anchor.js +683 -0
  11. package/lib/backup.js +1345 -0
  12. package/lib/capture.js +0 -0
  13. package/lib/context-window.js +0 -0
  14. package/lib/digest.js +0 -0
  15. package/lib/doc-review.js +0 -0
  16. package/lib/egress.js +0 -0
  17. package/lib/error-codes.js +1373 -0
  18. package/lib/evidence.js +202 -26
  19. package/lib/fs-safe.js +70 -7
  20. package/lib/ical.js +0 -0
  21. package/lib/imap.js +6 -2
  22. package/lib/importers.js +0 -0
  23. package/lib/learning.js +0 -0
  24. package/lib/ledger-read.js +608 -0
  25. package/lib/mcp-server.js +294 -38
  26. package/lib/model.js +0 -0
  27. package/lib/node-warning-filter.js +15 -0
  28. package/lib/notify.js +13 -3
  29. package/lib/nudge.js +0 -0
  30. package/lib/ocr.js +0 -0
  31. package/lib/pdf.js +0 -0
  32. package/lib/pet-brief-store.js +0 -0
  33. package/lib/pet-brief.js +102 -39
  34. package/lib/receipt-verify.js +213 -15
  35. package/lib/relative-date.js +0 -0
  36. package/lib/remind.js +91 -36
  37. package/lib/research.js +0 -0
  38. package/lib/review.js +0 -0
  39. package/lib/routine.js +0 -0
  40. package/lib/safety/classifier.js +0 -0
  41. package/lib/safety/explain.js +0 -0
  42. package/lib/safety/index.js +0 -0
  43. package/lib/safety/redact.js +0 -0
  44. package/lib/safety/rules.js +0 -0
  45. package/lib/scheduler.js +0 -0
  46. package/lib/source.js +0 -0
  47. package/lib/sqlite.js +1214 -24
  48. package/lib/sync.js +0 -0
  49. package/lib/text-safe.js +229 -0
  50. package/lib/timestamp.js +0 -0
  51. package/lib/tos/index.js +1 -1
  52. package/lib/tos/manifest.json +6 -6
  53. package/lib/tos/privacy.zh-CN.md +12 -9
  54. package/lib/tos/safety.zh-CN.md +4 -3
  55. package/lib/tos/summary.zh-CN.md +3 -3
  56. package/lib/tos/terms.zh-CN.md +8 -6
  57. package/lib/tui/color.js +164 -0
  58. package/lib/tui/index.js +33 -0
  59. package/lib/tui/json.js +124 -0
  60. package/lib/tui/labels.js +50 -0
  61. package/lib/tui/policy.js +108 -0
  62. package/lib/tui/render.js +371 -0
  63. package/lib/tui/sanitize.js +142 -0
  64. package/lib/tui/text-file.js +116 -0
  65. package/lib/tui/width.js +577 -0
  66. package/lib/ui.js +0 -0
  67. package/lib/undo.js +0 -0
  68. package/lib/untrusted.js +0 -0
  69. package/lib/vault.js +0 -0
  70. package/package.json +6 -5
@@ -0,0 +1,608 @@
1
+ // ---------------------------------------------------------------------------
2
+ // Read-only ledger facade (0.3.0 exported subpath `advisers/lib/ledger-read.js`).
3
+ //
4
+ // This is the single read-policy entry point for consumers that are NOT the
5
+ // CLI writer path (the DSH adapter today; MCP/pet-brief/other readers later).
6
+ // It opens the local ledger READ-ONLY and never becomes a writer:
7
+ //
8
+ // - no top-level `node:sqlite` import; sqlite is loaded lazily so a host
9
+ // without `node:sqlite` (e.g. an Electron renderer) can still import this
10
+ // module and receive a stable E_LEDGER_UNAVAILABLE instead of a load crash;
11
+ // - readOnly connection + assertSchemaCurrent only: no migrations, no DDL,
12
+ // no journal-mode pragmas, no checkpoint/vacuum;
13
+ // - no HOME instance lock, no HOME directory creation, no DB writes;
14
+ // - TOS gate: an existing acceptance record for the packaged TOS version and
15
+ // text hash is REQUIRED. This module never writes an acceptance record and
16
+ // deliberately ignores the ADVISERS_TOS_VERSION env override when deciding
17
+ // (an env var must not be able to fake consent);
18
+ // - deterministic, consumer-facing error codes (E_LEDGER_ABSENT /
19
+ // E_TOS_REQUIRED / E_VAULT_SEALED / E_SCHEMA_STALE / E_SCHEMA_NEWER /
20
+ // E_LEDGER_UNAVAILABLE / E_LEDGER_CORRUPT / E_LEDGER_BUSY / E_USAGE) with
21
+ // an actionable `hint` that never contains an absolute filesystem path;
22
+ // - every call opens and closes its own short read transaction, so a vault
23
+ // unseal / sync pull inode replacement and a concurrent writer are safe;
24
+ // - per-item clearance (default 0, fail closed): rows whose matter.secrecy
25
+ // is above the clearance are excluded and only counted, never partially
26
+ // returned.
27
+ //
28
+ // The API is a versioned contract (docs/LEDGER-READ-API.md): 0.x versions only
29
+ // add fields/signatures; existing names, shapes and error codes stay stable.
30
+ // ---------------------------------------------------------------------------
31
+ import { existsSync, readFileSync } from 'node:fs'
32
+ import { homedir } from 'node:os'
33
+ import { isAbsolute, join } from 'node:path'
34
+
35
+ import { secrecyLevel } from './egress.js'
36
+ import { evidenceRecordSecrecy } from './evidence.js'
37
+
38
+ /** File name of the SQLite ledger inside an Advisers home. */
39
+ export const LEDGER_DB_FILE = 'state.db'
40
+ /** File name of the legacy JSON ledger inside an Advisers home. */
41
+ export const LEDGER_JSON_FILE = 'state.json'
42
+ /** Suffix of a sealed (encrypted) vault that replaced the plaintext database. */
43
+ export const LEDGER_VAULT_SUFFIX = '.vault'
44
+
45
+ /** Ledger table names understood by the wire snapshot (`Ledger.fromJSON`). */
46
+ const WIRE_TABLES = Object.freeze([
47
+ 'matters', 'facts', 'commitments', 'preferences', 'links', 'updates',
48
+ 'routines', 'routinePatches', 'routes',
49
+ ])
50
+ const WIRE_TABLE_SET = new Set(WIRE_TABLES)
51
+
52
+ /** Entity kinds accepted by readEntityById(). */
53
+ const ENTITY_KINDS = Object.freeze({
54
+ commitments: { singular: 'commitment', method: 'getCommitment' },
55
+ facts: { singular: 'fact', method: 'getFact' },
56
+ preferences: { singular: 'preference', method: 'getPreference' },
57
+ matters: { singular: 'matter', method: 'getMatter' },
58
+ })
59
+
60
+ /**
61
+ * Stable read-facade error. `code` is the contract; `hint` is an actionable
62
+ * next step for the user with no absolute path in it.
63
+ */
64
+ export class LedgerReadError extends Error {
65
+ constructor(code, message, hint, extra = {}) {
66
+ super(String(message))
67
+ this.name = 'LedgerReadError'
68
+ this.code = String(code)
69
+ if (hint) this.hint = String(hint)
70
+ if (extra && typeof extra === 'object') Object.assign(this, extra)
71
+ }
72
+ }
73
+
74
+ /* -------------------------------------------------------------------------- */
75
+ /* home resolution */
76
+ /* -------------------------------------------------------------------------- */
77
+
78
+ /**
79
+ * Resolve the Advisers home directory.
80
+ *
81
+ * Order: `options.home` -> `ADVISERS_HOME` -> `~/.advisers` (the same rule as
82
+ * the CLI / lib/tos defaultHome). An explicitly supplied `home` must be an
83
+ * absolute path; a relative one is a configuration error (E_USAGE), not a data
84
+ * error, so a caller cannot silently read a cwd-relative directory.
85
+ *
86
+ * @param {{ home?: string }} [options]
87
+ * @returns {string}
88
+ */
89
+ export function resolveAdvisersHome({ home } = {}) {
90
+ if (home !== undefined && home !== null) {
91
+ if (typeof home !== 'string' || home.trim() === '') {
92
+ throw new LedgerReadError('E_USAGE', 'options.home must be a non-empty absolute path', 'Pass an absolute directory (or omit home to use ADVISERS_HOME / ~/.advisers).')
93
+ }
94
+ if (!isAbsolute(home)) {
95
+ throw new LedgerReadError('E_USAGE', 'options.home must be an absolute path', 'Pass an absolute directory (or omit home to use ADVISERS_HOME / ~/.advisers).')
96
+ }
97
+ return home
98
+ }
99
+ const fromEnv = typeof process.env.ADVISERS_HOME === 'string' ? process.env.ADVISERS_HOME.trim() : ''
100
+ if (fromEnv) return fromEnv
101
+ return join(homedir(), '.advisers')
102
+ }
103
+
104
+ /* -------------------------------------------------------------------------- */
105
+ /* path-safe messages */
106
+ /* -------------------------------------------------------------------------- */
107
+
108
+ /** Replace known absolute paths in a message/warning with portable labels. */
109
+ function sanitizePathText(value, home) {
110
+ let text = String(value ?? '')
111
+ if (!home) return text
112
+ const replacements = [
113
+ [join(home, LEDGER_DB_FILE) + '-wal', LEDGER_DB_FILE + '-wal'],
114
+ [join(home, LEDGER_DB_FILE) + '-shm', LEDGER_DB_FILE + '-shm'],
115
+ [join(home, LEDGER_DB_FILE), LEDGER_DB_FILE],
116
+ [join(home, LEDGER_JSON_FILE), LEDGER_JSON_FILE],
117
+ [join(home, 'tos.json'), 'tos.json'],
118
+ [join(home, 'instance.lock'), 'instance.lock'],
119
+ [home, '~/.advisers'],
120
+ ]
121
+ for (const [from, to] of replacements) {
122
+ if (from && from !== '/') text = text.split(from).join(to)
123
+ }
124
+ return text
125
+ }
126
+
127
+ function sanitizeMessage(value, home) {
128
+ return sanitizePathText(value, home).replace(/\s+/g, ' ').trim().slice(0, 400)
129
+ }
130
+
131
+ /* -------------------------------------------------------------------------- */
132
+ /* error translation */
133
+ /* -------------------------------------------------------------------------- */
134
+
135
+ function isReadOnlyVolumeError(error) {
136
+ const code = String(error?.code ?? '')
137
+ if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS' || code === 'EISDIR' || code === 'ENOTDIR') return true
138
+ return /readonly database|read-only database|unable to open database file|cannot open database|attempt to write a readonly database/i.test(String(error?.message ?? ''))
139
+ }
140
+
141
+ function isCorruptDatabaseError(error) {
142
+ const code = String(error?.code ?? '')
143
+ if (code === 'E_DB_CORRUPT') return true
144
+ return /file is (?:not a database|encrypted)|database disk image is malformed|malformed database/i.test(String(error?.message ?? ''))
145
+ }
146
+
147
+ function isBusyDatabaseError(error) {
148
+ const code = String(error?.code ?? '')
149
+ if (code === 'E_DB_LOCKED') return true
150
+ if (typeof error?.errcode === 'number' && (error.errcode === 5 || error.errcode === 6)) return true
151
+ return /SQLITE_BUSY|SQLITE_LOCKED|database (?:table )?is locked/i.test(String(error?.message ?? ''))
152
+ }
153
+
154
+ /**
155
+ * Translate an open/read failure into a stable LedgerReadError.
156
+ * Messages are our own (short, path-free); the raw error stays as `cause`.
157
+ */
158
+ function translateOpenError(error, home) {
159
+ if (error instanceof LedgerReadError) return error
160
+ if (isCorruptDatabaseError(error)) {
161
+ return new LedgerReadError('E_LEDGER_CORRUPT', 'the ledger database is corrupt or not a SQLite database', 'Back up state.db (do not delete it), then run `advisers doctor`; do not rebuild or replace the file.', { cause: error })
162
+ }
163
+ if (isBusyDatabaseError(error)) {
164
+ return new LedgerReadError('E_LEDGER_BUSY', 'the ledger is temporarily busy', 'Retry in a moment; a long-running writer may be checkpointing the ledger.', { cause: error })
165
+ }
166
+ if (isReadOnlyVolumeError(error)) {
167
+ return new LedgerReadError('E_LEDGER_UNAVAILABLE', 'the ledger cannot be opened read-only in this environment', 'Use a local writable directory for ADVISERS_HOME and make sure this process may read state.db; network/synced volumes and read-only mounts are not supported.', { cause: error })
168
+ }
169
+ const code = String(error?.code ?? '')
170
+ if (code === 'E_SCHEMA_STALE') {
171
+ return new LedgerReadError('E_SCHEMA_STALE', 'the on-disk ledger schema is older than this Advisers version; a read-only open never migrates it', 'Run any writable CLI command (for example `advisers doctor`) to migrate the ledger, then retry.', { schemaVersion: error?.schemaVersion ?? null, expected: error?.expected ?? null, cause: error })
172
+ }
173
+ if (code === 'E_SCHEMA_NEWER') {
174
+ return new LedgerReadError('E_SCHEMA_NEWER', 'the on-disk ledger schema is newer than this Advisers version; refusing to read it', 'Upgrade the `advisers` / `dsh-advisers` package so both sides use the same ledger schema.', { schemaVersion: error?.schemaVersion ?? null, expected: error?.expected ?? null, cause: error })
175
+ }
176
+ return new LedgerReadError('E_LEDGER_UNAVAILABLE', 'the ledger could not be opened read-only', 'Check that state.db exists on a local filesystem and the current process can read it; if the error persists run `advisers doctor`.', { cause: error })
177
+ }
178
+
179
+ function absentError() {
180
+ return new LedgerReadError('E_LEDGER_ABSENT', 'no ledger was found in the Advisers home directory', 'Run `advisers init` to create the local ledger; the read-only facade never creates it.', { reason: 'missing' })
181
+ }
182
+
183
+ function vaultSealedError() {
184
+ return new LedgerReadError('E_VAULT_SEALED', 'the ledger is sealed; no plaintext database exists', 'Run `advisers vault unseal` (or `advisers vault status`) first; this facade never creates an empty database.', { reason: 'sealed' })
185
+ }
186
+
187
+ /* -------------------------------------------------------------------------- */
188
+ /* TOS gate */
189
+ /* -------------------------------------------------------------------------- */
190
+
191
+ /**
192
+ * Current packaged-TOS acceptance status for a home. Never writes.
193
+ * The packaged manifest (not ADVISERS_TOS_VERSION) decides the version/hash, so
194
+ * an environment variable cannot fake consent (0.3.0 S3).
195
+ */
196
+ async function tosStatus(home) {
197
+ let tos
198
+ try { tos = await import('./tos/index.js') } catch { return { accepted: false, reason: 'unavailable' } }
199
+ try {
200
+ const manifest = tos.readManifest()
201
+ const info = tos.currentTos({ version: manifest.version })
202
+ const status = tos.acceptanceStatus({ home, version: info.version, sha256: info.sha256 })
203
+ return { accepted: status.accepted === true, reason: String(status.reason ?? (status.accepted ? 'accepted' : 'missing')) }
204
+ } catch {
205
+ return { accepted: false, reason: 'unavailable' }
206
+ }
207
+ }
208
+
209
+ async function requireTos(home) {
210
+ const status = await tosStatus(home)
211
+ if (status.accepted) return
212
+ throw new LedgerReadError('E_TOS_REQUIRED', `the current Advisers Terms of Service are not accepted for this ledger (${status.reason})`, 'Run `advisers tos show` and accept the current terms with an interactive CLI command; the DSH/read-only surface must never record acceptance for the user.', { reason: status.reason })
213
+ }
214
+
215
+ /* -------------------------------------------------------------------------- */
216
+ /* backend selection + ledger handles */
217
+ /* -------------------------------------------------------------------------- */
218
+
219
+ function storePreference() {
220
+ return String(process.env.ADVISERS_STORE ?? '').trim().toLowerCase()
221
+ }
222
+
223
+ /**
224
+ * Decide which backend this home uses. Mirrors the CLI's ADVISERS_STORE rule,
225
+ * with one read-only affordance: when the env var is unset and only the
226
+ * legacy state.json exists, the facade reads JSON instead of pretending the
227
+ * ledger is absent (it never falls back from SQLite to JSON).
228
+ */
229
+ function detectBackend(home) {
230
+ const dbPath = join(home, LEDGER_DB_FILE)
231
+ const jsonPath = join(home, LEDGER_JSON_FILE)
232
+ const pref = storePreference()
233
+ if (pref === 'json') return { backend: 'json', dbPath, jsonPath }
234
+ if (existsSync(dbPath)) return { backend: 'sqlite', dbPath, jsonPath }
235
+ if (pref === 'sqlite') return { backend: 'sqlite', dbPath, jsonPath }
236
+ if (existsSync(jsonPath)) return { backend: 'json', dbPath, jsonPath }
237
+ return { backend: 'sqlite', dbPath, jsonPath }
238
+ }
239
+
240
+ function readJsonLedger(jsonPath) {
241
+ let text
242
+ try {
243
+ text = readFileSync(jsonPath, 'utf8')
244
+ } catch (error) {
245
+ throw translateOpenError(error, '')
246
+ }
247
+ try {
248
+ const parsed = JSON.parse(text)
249
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not a JSON object')
250
+ return parsed
251
+ } catch (error) {
252
+ throw new LedgerReadError('E_LEDGER_CORRUPT', 'the JSON ledger store cannot be parsed', 'Back up state.json (do not delete it), then run `advisers doctor`; the read-only facade never repairs the file.', { cause: error })
253
+ }
254
+ }
255
+
256
+ function notFoundInHome(backend) {
257
+ const dbPath = backend.dbPath
258
+ if (existsSync(dbPath + LEDGER_VAULT_SUFFIX)) return vaultSealedError()
259
+ return absentError()
260
+ }
261
+
262
+ function jsonArray(ledger, table) {
263
+ const value = ledger?.[table]
264
+ return Array.isArray(value) ? value : []
265
+ }
266
+
267
+ function jsonMatterSecrecy(ledger, matterId) {
268
+ if (typeof matterId !== 'string' || !matterId) return 0
269
+ const matter = jsonArray(ledger, 'matters').find((row) => row?.id === matterId)
270
+ if (!matter) return Number.POSITIVE_INFINITY
271
+ return secrecyLevel(matter)
272
+ }
273
+
274
+ function normalizeClearance(value) {
275
+ const level = Number(value)
276
+ return Number.isFinite(level) && level >= 0 ? Math.floor(level) : 0
277
+ }
278
+
279
+ function normalizeLimit(value) {
280
+ if (value === undefined || value === null) return null
281
+ const limit = Number(value)
282
+ if (!Number.isInteger(limit) || limit < 1) {
283
+ throw new LedgerReadError('E_USAGE', 'limit must be a positive integer when supplied', 'Omit limit to return every row that passes the clearance gate.')
284
+ }
285
+ return limit
286
+ }
287
+
288
+ function normalizeParts(parts) {
289
+ if (parts === undefined || parts === null) return null
290
+ if (!Array.isArray(parts)) throw new LedgerReadError('E_USAGE', 'parts must be an array of wire table names', `Accepted names: ${WIRE_TABLES.join(', ')}.`)
291
+ const selected = []
292
+ for (const part of parts) {
293
+ if (!WIRE_TABLE_SET.has(part)) throw new LedgerReadError('E_USAGE', `unknown snapshot part: ${String(part)}`, `Accepted names: ${WIRE_TABLES.join(', ')}.`)
294
+ if (!selected.includes(part)) selected.push(part)
295
+ }
296
+ return selected
297
+ }
298
+
299
+ function commitmentIndexRow(row) {
300
+ const view = { id: String(row.id), debtor: String(row.debtor ?? ''), creditor: String(row.creditor ?? ''), action: String(row.action ?? ''), status: String(row.status ?? '') }
301
+ if (typeof row.due_at === 'string' && row.due_at) view.dueAt = row.due_at
302
+ else if (typeof row.dueAt === 'string' && row.dueAt) view.dueAt = row.dueAt
303
+ const matterId = row.matter_id ?? row.matterId
304
+ if (typeof matterId === 'string' && matterId) view.matterId = matterId
305
+ return view
306
+ }
307
+
308
+ async function loadSqliteBinding() {
309
+ try {
310
+ return await import('./sqlite.js')
311
+ } catch (error) {
312
+ throw new LedgerReadError('E_LEDGER_UNAVAILABLE', 'the SQLite runtime (node:sqlite) is not available in this Node.js process', 'Use a Node.js >= 22.16 host (the ledger needs node:sqlite). The DSH adapter falls back to a marked preview when this code is returned.', { cause: error })
313
+ }
314
+ }
315
+
316
+ /** Open the ledger read-only, gate TOS, and return a short-lived handle. */
317
+ async function openLedgerHandle(home) {
318
+ const backend = detectBackend(home)
319
+ if (backend.backend === 'json') {
320
+ if (!existsSync(backend.jsonPath)) throw notFoundInHome({ dbPath: backend.dbPath })
321
+ await requireTos(home)
322
+ const ledger = readJsonLedger(backend.jsonPath)
323
+ return {
324
+ backend: 'json',
325
+ schemaVersion: null,
326
+ warnings: [],
327
+ close() {},
328
+ getEntity: (kind, id, clearance) => jsonEntity(ledger, kind, id, clearance),
329
+ index: (options) => jsonCommitmentIndex(ledger, options),
330
+ snapshot: (parts) => jsonSnapshot(ledger, parts),
331
+ }
332
+ }
333
+ if (!existsSync(backend.dbPath)) throw notFoundInHome(backend)
334
+ await requireTos(home)
335
+ const sqlite = await loadSqliteBinding()
336
+ let store
337
+ try {
338
+ store = sqlite.openReadStore(backend.dbPath)
339
+ } catch (error) {
340
+ throw translateOpenError(error, home)
341
+ }
342
+ const warnings = []
343
+ if (store.walStatus?.warning) warnings.push(sanitizeMessage(store.walStatus.warning, home))
344
+ return {
345
+ backend: 'sqlite',
346
+ schemaVersion: store.schemaVersion(),
347
+ warnings,
348
+ close() { try { store.close() } catch {} },
349
+ getEntity(kind, id, clearance) {
350
+ const spec = ENTITY_KINDS[kind]
351
+ return sqliteEntity(store, spec, kind, id, clearance)
352
+ },
353
+ index(options) {
354
+ return sqliteCommitmentIndex(store, options)
355
+ },
356
+ snapshot(parts) {
357
+ return store.read(() => store.loadSnapshot(parts))
358
+ },
359
+ }
360
+ }
361
+
362
+ async function withLedger(home, fn) {
363
+ const handle = await openLedgerHandle(home)
364
+ try { return await fn(handle) } finally { handle.close() }
365
+ }
366
+
367
+ /* -------------------------------------------------------------------------- */
368
+ /* sqlite projections */
369
+ /* -------------------------------------------------------------------------- */
370
+
371
+ // Narrow, index-friendly projection: only the columns a read model shows. This
372
+ // deliberately does NOT call store.loadCommitments(), which maps every column
373
+ // (including the evidence JSON) for every open row. 20k open commitments cost
374
+ // ~17ms with this projection (docs/PERFORMANCE.md; 0.3.0 research report 10
375
+ // section 1.4 E8).
376
+ const COMMITMENT_INDEX_SQL = 'SELECT id, debtor, creditor, action, due_at, matter_id, status FROM commitments'
377
+ const OPEN_COMMITMENT_INDEX_SQL = COMMITMENT_INDEX_SQL + ' WHERE status = ?'
378
+ const MATTER_SECRECY_SQL = 'SELECT id, secrecy FROM matters'
379
+
380
+ function sqliteCommitmentIndex(store, { all, clearance }) {
381
+ const { rawRows, matterRows } = store.read(() => ({
382
+ rawRows: all
383
+ ? store.db.prepare(COMMITMENT_INDEX_SQL).all()
384
+ : store.db.prepare(OPEN_COMMITMENT_INDEX_SQL).all('open'),
385
+ matterRows: store.db.prepare(MATTER_SECRECY_SQL).all(),
386
+ }))
387
+ const secrecyById = new Map()
388
+ for (const matter of matterRows) secrecyById.set(matter.id, matter.secrecy)
389
+ const rows = []
390
+ let protectedExcluded = 0
391
+ for (const raw of rawRows) {
392
+ const matterId = raw.matter_id
393
+ let secrecy = 0
394
+ if (typeof matterId === 'string' && matterId) {
395
+ secrecy = secrecyById.has(matterId) ? secrecyLevel({ secrecy: secrecyById.get(matterId) }) : Number.POSITIVE_INFINITY
396
+ }
397
+ if (secrecy > clearance) { protectedExcluded += 1; continue }
398
+ rows.push(commitmentIndexRow(raw))
399
+ }
400
+ return { rows, total: rows.length, protectedExcluded }
401
+ }
402
+
403
+ function sqliteEntity(store, spec, kind, id, clearance) {
404
+ return store.read(() => {
405
+ const record = store[spec.method](id)
406
+ if (!record) return { record: null, hidden: false }
407
+ let secrecy
408
+ if (kind === 'matters') secrecy = secrecyLevel(record)
409
+ else secrecy = evidenceRecordSecrecy({ getMatter: (matterId) => store.getMatter(matterId) }, spec.singular, record)
410
+ const hidden = secrecy > clearance
411
+ return { record: hidden ? null : record, hidden }
412
+ })
413
+ }
414
+
415
+ /* -------------------------------------------------------------------------- */
416
+ /* JSON store projections (legacy ADVISERS_STORE=json) */
417
+ /* -------------------------------------------------------------------------- */
418
+
419
+ function jsonEntity(ledger, kind, id, clearance) {
420
+ const table = kind
421
+ const record = jsonArray(ledger, table).find((row) => row?.id === id)
422
+ if (!record) return { record: null, hidden: false }
423
+ const spec = ENTITY_KINDS[kind]
424
+ let secrecy
425
+ if (kind === 'matters') secrecy = secrecyLevel(record)
426
+ else secrecy = evidenceRecordSecrecy({ getMatter: (matterId) => jsonArray(ledger, 'matters').find((row) => row?.id === matterId) }, spec.singular, record)
427
+ const hidden = secrecy > clearance
428
+ return { record: hidden ? null : record, hidden }
429
+ }
430
+
431
+ function jsonCommitmentIndex(ledger, { all, clearance }) {
432
+ const rows = []
433
+ let protectedExcluded = 0
434
+ for (const raw of jsonArray(ledger, 'commitments')) {
435
+ if (!all && raw?.status !== 'open') continue
436
+ const secrecy = jsonMatterSecrecy(ledger, raw?.matterId)
437
+ if (secrecy > clearance) { protectedExcluded += 1; continue }
438
+ rows.push(commitmentIndexRow(raw))
439
+ }
440
+ return { rows, total: rows.length, protectedExcluded }
441
+ }
442
+
443
+ function jsonSnapshot(ledger, parts) {
444
+ const snapshot = { version: Number.isInteger(ledger?.version) ? ledger.version : 1 }
445
+ for (const table of parts ?? WIRE_TABLES) {
446
+ const value = ledger?.[table]
447
+ if (table === 'routes') snapshot.routes = value && typeof value === 'object' && !Array.isArray(value) ? value : {}
448
+ else snapshot[table] = Array.isArray(value) ? value : []
449
+ }
450
+ return snapshot
451
+ }
452
+
453
+ /* -------------------------------------------------------------------------- */
454
+ /* public API */
455
+ /* -------------------------------------------------------------------------- */
456
+
457
+ /**
458
+ * Read-only diagnostic. Never returns ledger rows and never throws for a data
459
+ * problem (it reports `readable`, `reason` and an optional `error` instead).
460
+ *
461
+ * @param {{ home?: string }} [options]
462
+ * @returns {Promise<{backend:'sqlite'|'json', dbPresent:boolean, sealed:boolean,
463
+ * statePresent:boolean, schemaVersion:number|null,
464
+ * tos:{accepted:boolean, reason:string}, warnings:string[], readable:boolean,
465
+ * reason?:string, error?:{code:string, message:string, hint?:string}}>}
466
+ */
467
+ export async function readLedgerStatus({ home } = {}) {
468
+ const root = resolveAdvisersHome({ home })
469
+ const tos = await tosStatus(root)
470
+ const backend = detectBackend(root)
471
+ if (backend.backend === 'json') {
472
+ const statePresent = existsSync(backend.jsonPath)
473
+ const status = { backend: 'json', dbPresent: false, sealed: false, statePresent, schemaVersion: null, tos, warnings: [], readable: false }
474
+ if (!statePresent) { status.reason = 'absent'; return status }
475
+ try {
476
+ const ledger = readJsonLedger(backend.jsonPath)
477
+ status.readable = true
478
+ status.snapshotVersion = Number.isInteger(ledger.version) ? ledger.version : 1
479
+ } catch (error) {
480
+ const mapped = error instanceof LedgerReadError ? error : translateOpenError(error, root)
481
+ status.error = { code: mapped.code, message: mapped.message }
482
+ if (mapped.hint) status.error.hint = mapped.hint
483
+ }
484
+ return status
485
+ }
486
+ const dbPresent = existsSync(backend.dbPath)
487
+ const sealed = !dbPresent && existsSync(backend.dbPath + LEDGER_VAULT_SUFFIX)
488
+ const status = { backend: 'sqlite', dbPresent, sealed, statePresent: false, schemaVersion: null, tos, warnings: [], readable: false }
489
+ if (!dbPresent) { status.reason = sealed ? 'sealed' : 'absent'; return status }
490
+ try {
491
+ const sqlite = await loadSqliteBinding()
492
+ const store = sqlite.openReadStore(backend.dbPath)
493
+ try {
494
+ status.schemaVersion = store.schemaVersion()
495
+ status.readable = true
496
+ if (store.walStatus?.warning) status.warnings.push(sanitizeMessage(store.walStatus.warning, root))
497
+ } finally { try { store.close() } catch {} }
498
+ } catch (error) {
499
+ const mapped = translateOpenError(error, root)
500
+ status.error = { code: mapped.code, message: mapped.message }
501
+ if (mapped.hint) status.error.hint = mapped.hint
502
+ if (mapped.schemaVersion !== undefined) status.schemaVersion = mapped.schemaVersion
503
+ }
504
+ return status
505
+ }
506
+
507
+ /**
508
+ * Targeted open-commitment index. This one projection powers the DSH today /
509
+ * who views and the commit-ls list without loading a whole ledger snapshot:
510
+ * one narrow SELECT over `commitments` (status index) plus the small matters
511
+ * table for the per-item clearance gate.
512
+ *
513
+ * Protected rows (matter.secrecy > clearance) are excluded from `rows` and
514
+ * only counted in `protectedExcluded`; they are never partially returned.
515
+ *
516
+ * @param {{ home?: string, clearance?: number, all?: boolean, limit?: number }} [options]
517
+ * @returns {Promise<{rows:Array<{id:string,debtor:string,creditor:string,
518
+ * action:string,status:string,dueAt?:string,matterId?:string}>,
519
+ * total:number, protectedExcluded:number, clearance:number,
520
+ * schemaVersion:number|null, backend:'sqlite'|'json', readAt:string,
521
+ * warnings:string[]}>}
522
+ */
523
+ export async function readOpenCommitmentIndex({ home, clearance = 0, all = false, limit = null } = {}) {
524
+ const root = resolveAdvisersHome({ home })
525
+ const level = normalizeClearance(clearance)
526
+ const max = normalizeLimit(limit)
527
+ return withLedger(root, (handle) => {
528
+ const result = handle.index({ all: all === true, clearance: level })
529
+ return {
530
+ rows: max === null ? result.rows : result.rows.slice(0, max),
531
+ total: result.total,
532
+ protectedExcluded: result.protectedExcluded,
533
+ clearance: level,
534
+ schemaVersion: handle.schemaVersion,
535
+ backend: handle.backend,
536
+ readAt: new Date().toISOString(),
537
+ warnings: handle.warnings.slice(),
538
+ }
539
+ })
540
+ }
541
+
542
+ /**
543
+ * One entity by primary key: an O(1) point query, never a table scan (the DSH
544
+ * evidence tool uses this). A record whose matter secrecy is above `clearance`
545
+ * is NOT returned: `record` is null, `hidden` is true and `protectedExcluded`
546
+ * is 1, so the caller can distinguish 'withheld' from 'missing'.
547
+ *
548
+ * @param {{ home?: string, kind:'commitments'|'facts'|'preferences'|'matters',
549
+ * id:string, clearance?:number }} [options]
550
+ * @returns {Promise<{record:object|null, hidden:boolean, clearance:number,
551
+ * protectedExcluded:number, schemaVersion:number|null, backend:'sqlite'|'json',
552
+ * readAt:string, warnings:string[]}>}
553
+ */
554
+ export async function readEntityById({ home, kind, id, clearance = 0 } = {}) {
555
+ const root = resolveAdvisersHome({ home })
556
+ if (!Object.prototype.hasOwnProperty.call(ENTITY_KINDS, kind)) {
557
+ throw new LedgerReadError('E_USAGE', `unknown entity kind: ${String(kind)}`, 'kind must be commitments, facts, preferences, or matters.')
558
+ }
559
+ if (typeof id !== 'string' || id.trim() === '') {
560
+ throw new LedgerReadError('E_USAGE', 'id must be a non-empty string', 'Pass the ledger row id, for example cm_… / fact_… / pref_… / matter id.')
561
+ }
562
+ const key = id.trim()
563
+ const level = normalizeClearance(clearance)
564
+ return withLedger(root, (handle) => {
565
+ const result = handle.getEntity(kind, key, level)
566
+ return {
567
+ record: result.record,
568
+ hidden: result.hidden === true,
569
+ clearance: level,
570
+ protectedExcluded: result.hidden ? 1 : 0,
571
+ schemaVersion: handle.schemaVersion,
572
+ backend: handle.backend,
573
+ readAt: new Date().toISOString(),
574
+ warnings: handle.warnings.slice(),
575
+ }
576
+ })
577
+ }
578
+
579
+ /**
580
+ * Wire-v1 ledger snapshot (subset). This is the raw `Ledger.toJSON` shape for
581
+ * trusted in-process consumers (e.g. building a core Ledger); it does NOT apply
582
+ * the per-item clearance gate. Do not hand this snapshot to a model/egress
583
+ * surface without a clearance projection.
584
+ *
585
+ * @param {{ home?: string, parts?: string[] }} [options]
586
+ * @returns {Promise<{snapshot:object, schemaVersion:number|null,
587
+ * backend:'sqlite'|'json', readAt:string, warnings:string[]}>}
588
+ */
589
+ export async function readLedgerSnapshot({ home, parts = null } = {}) {
590
+ const root = resolveAdvisersHome({ home })
591
+ const selected = normalizeParts(parts)
592
+ return withLedger(root, (handle) => ({
593
+ snapshot: handle.snapshot(selected),
594
+ schemaVersion: handle.schemaVersion,
595
+ backend: handle.backend,
596
+ readAt: new Date().toISOString(),
597
+ warnings: handle.warnings.slice(),
598
+ }))
599
+ }
600
+
601
+ export default Object.freeze({
602
+ LedgerReadError,
603
+ resolveAdvisersHome,
604
+ readLedgerStatus,
605
+ readOpenCommitmentIndex,
606
+ readEntityById,
607
+ readLedgerSnapshot,
608
+ })