advisers 0.2.3 → 0.3.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.
- package/LICENSE +0 -0
- package/NOTICE +0 -0
- package/README-zh.md +10 -6
- package/README.md +15 -6
- package/THIRD-PARTY-NOTICES.md +1 -1
- package/bin/advisers.js +3323 -222
- package/index.js +1 -1
- package/lib/agent.js +0 -0
- package/lib/attachments.js +0 -0
- package/lib/audit-anchor.js +683 -0
- package/lib/backup.js +1345 -0
- package/lib/capture.js +0 -0
- package/lib/context-window.js +0 -0
- package/lib/digest.js +0 -0
- package/lib/doc-review.js +0 -0
- package/lib/egress.js +0 -0
- package/lib/error-codes.js +1373 -0
- package/lib/evidence.js +202 -26
- package/lib/fs-safe.js +70 -7
- package/lib/ical.js +0 -0
- package/lib/imap.js +6 -2
- package/lib/importers.js +0 -0
- package/lib/learning.js +0 -0
- package/lib/ledger-read.js +608 -0
- package/lib/mcp-server.js +294 -38
- package/lib/model.js +0 -0
- package/lib/node-warning-filter.js +15 -0
- package/lib/notify.js +13 -3
- package/lib/nudge.js +0 -0
- package/lib/ocr.js +0 -0
- package/lib/pdf.js +0 -0
- package/lib/pet-brief-store.js +0 -0
- package/lib/pet-brief.js +102 -39
- package/lib/receipt-verify.js +213 -15
- package/lib/relative-date.js +0 -0
- package/lib/remind.js +91 -36
- package/lib/research.js +0 -0
- package/lib/review.js +0 -0
- package/lib/routine.js +0 -0
- package/lib/safety/classifier.js +0 -0
- package/lib/safety/explain.js +0 -0
- package/lib/safety/index.js +0 -0
- package/lib/safety/redact.js +0 -0
- package/lib/safety/rules.js +0 -0
- package/lib/scheduler.js +0 -0
- package/lib/source.js +0 -0
- package/lib/sqlite.js +1214 -24
- package/lib/sync.js +0 -0
- package/lib/text-safe.js +229 -0
- package/lib/timestamp.js +0 -0
- package/lib/tos/index.js +1 -1
- package/lib/tos/manifest.json +6 -6
- package/lib/tos/privacy.zh-CN.md +12 -9
- package/lib/tos/safety.zh-CN.md +4 -3
- package/lib/tos/summary.zh-CN.md +3 -3
- package/lib/tos/terms.zh-CN.md +8 -6
- package/lib/tui/color.js +164 -0
- package/lib/tui/index.js +33 -0
- package/lib/tui/json.js +124 -0
- package/lib/tui/labels.js +50 -0
- package/lib/tui/policy.js +108 -0
- package/lib/tui/render.js +371 -0
- package/lib/tui/sanitize.js +142 -0
- package/lib/tui/text-file.js +116 -0
- package/lib/tui/width.js +577 -0
- package/lib/ui.js +0 -0
- package/lib/undo.js +0 -0
- package/lib/untrusted.js +0 -0
- package/lib/vault.js +0 -0
- 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
|
+
})
|