advisers 0.2.2 → 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 +11 -7
- package/README.md +16 -8
- package/THIRD-PARTY-NOTICES.md +1 -1
- package/bin/advisers.js +6347 -542
- package/index.js +1 -1
- package/lib/agent.js +529 -80
- 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 +352 -43
- package/lib/fs-safe.js +347 -0
- 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 +331 -50
- package/lib/model.js +73 -1
- package/lib/node-warning-filter.js +15 -0
- package/lib/notify.js +13 -3
- package/lib/nudge.js +0 -0
- package/lib/ocr.js +29 -9
- package/lib/pdf.js +0 -0
- package/lib/pet-brief-store.js +0 -0
- package/lib/pet-brief.js +126 -64
- 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 +55 -2
- 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 +28 -0
- package/lib/scheduler.js +0 -0
- package/lib/source.js +0 -0
- package/lib/sqlite.js +2302 -55
- package/lib/sync.js +398 -71
- package/lib/text-safe.js +229 -0
- package/lib/timestamp.js +29 -9
- 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 +186 -0
- package/lib/vault.js +0 -0
- package/package.json +6 -5
package/lib/sqlite.js
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { DatabaseSync } from 'node:sqlite'
|
|
2
|
-
import { chmodSync, closeSync, copyFileSync, fsyncSync, mkdirSync, openSync, readFileSync, rmSync, statSync, unlinkSync, utimesSync, writeSync } from 'node:fs'
|
|
2
|
+
import { chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, unlinkSync, utimesSync, writeSync } from 'node:fs'
|
|
3
3
|
import { createHash, createHmac, randomUUID } from 'node:crypto'
|
|
4
4
|
import { dirname, join } from 'node:path'
|
|
5
|
+
import { copyFileWithRetrySync, fsyncDirSync, fsyncFileSync, rmWithRetrySync } from './fs-safe.js'
|
|
5
6
|
|
|
6
7
|
/**
|
|
7
8
|
* Open + write hardening (2026-11-17 robustness audit P0-1/P0-3/P1-2):
|
|
@@ -18,7 +19,26 @@ import { dirname, join } from 'node:path'
|
|
|
18
19
|
* - Migrations are refused for a schema newer than this CLI and are preceded
|
|
19
20
|
* by a same-directory backup of the old database.
|
|
20
21
|
*/
|
|
21
|
-
|
|
22
|
+
/**
|
|
23
|
+
* Physical database schema version (meta.schema_version).
|
|
24
|
+
*
|
|
25
|
+
* v20 (0.2.3 persistence v2): adds the schema_migrations ledger, the
|
|
26
|
+
* idx_turns_seq / idx_facts_identity / idx_memory_candidates_status indexes,
|
|
27
|
+
* and turns migrate() into a per-version step table.
|
|
28
|
+
*
|
|
29
|
+
* v21 (0.3.0 customer entities): adds clients / projects / client_notes,
|
|
30
|
+
* matters.client_id/project_id (nullable ownership; the single source of
|
|
31
|
+
* truth for who a matter belongs to), commitments.created_at (the derived
|
|
32
|
+
* customer timeline needs the moment a commitment was recorded, not its due
|
|
33
|
+
* date), and the deliveries lineage columns (client_id/project_id snapshot +
|
|
34
|
+
* template_name/template_version/quote_no/data_sha256). There is no event
|
|
35
|
+
* table and no stored counter: the timeline and the client views are derived
|
|
36
|
+
* from these rows by packages/core/src/customer.ts. This is NOT the wire
|
|
37
|
+
* format: LedgerSnapshot.version stays 1 (see core/src/ledger.ts).
|
|
38
|
+
*/
|
|
39
|
+
export const SCHEMA_VERSION = 21
|
|
40
|
+
/** The last schema built by the single-block legacy migration (0.2.2). */
|
|
41
|
+
const LEGACY_SCHEMA_VERSION = 19
|
|
22
42
|
const DEFAULT_BUSY_TIMEOUT_MS = 5000
|
|
23
43
|
const OPEN_RETRIES = 6
|
|
24
44
|
const BUSY_ERRCODES = new Set([5, 6]) // SQLITE_BUSY, SQLITE_LOCKED
|
|
@@ -104,6 +124,44 @@ export class DatabaseLockedError extends Error {
|
|
|
104
124
|
}
|
|
105
125
|
}
|
|
106
126
|
|
|
127
|
+
/**
|
|
128
|
+
* Version of this CLI, recorded in meta.schema_migrated_app for support. Read
|
|
129
|
+
* from the package manifest so it cannot drift from the released version.
|
|
130
|
+
*/
|
|
131
|
+
const APP_VERSION = (() => {
|
|
132
|
+
try {
|
|
133
|
+
const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
|
|
134
|
+
return typeof pkg?.version === 'string' ? pkg.version : '0.0.0'
|
|
135
|
+
} catch {
|
|
136
|
+
return '0.0.0'
|
|
137
|
+
}
|
|
138
|
+
})()
|
|
139
|
+
|
|
140
|
+
/** E_SCHEMA_STALE: the on-disk schema is older than this CLI (read path). */
|
|
141
|
+
function schemaStaleError(path, version) {
|
|
142
|
+
const found = version === null || version === undefined ? 'unknown' : `v${version}`
|
|
143
|
+
const error = new Error(
|
|
144
|
+
`E_SCHEMA_STALE: database schema at ${path} is ${found} but this CLI expects v${SCHEMA_VERSION}; ` +
|
|
145
|
+
'if another advisers process is upgrading it, retry in a moment; otherwise run a writable ' +
|
|
146
|
+
'command (for example `advisers doctor`) to migrate it first.',
|
|
147
|
+
)
|
|
148
|
+
error.name = 'SchemaStaleError'
|
|
149
|
+
error.code = 'E_SCHEMA_STALE'
|
|
150
|
+
error.schemaVersion = version ?? null
|
|
151
|
+
error.expected = SCHEMA_VERSION
|
|
152
|
+
return error
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** E_SCHEMA_NEWER: the on-disk schema is newer than this CLI (fail closed). */
|
|
156
|
+
function schemaNewerError(path, version) {
|
|
157
|
+
const error = new Error(`database schema v${version} is newer than this CLI (v${SCHEMA_VERSION}); upgrade advisers before opening ${path}`)
|
|
158
|
+
error.name = 'SchemaNewerError'
|
|
159
|
+
error.code = 'E_SCHEMA_NEWER'
|
|
160
|
+
error.schemaVersion = Number(version)
|
|
161
|
+
error.expected = SCHEMA_VERSION
|
|
162
|
+
return error
|
|
163
|
+
}
|
|
164
|
+
|
|
107
165
|
function readEnvMs(name, fallback, max) {
|
|
108
166
|
const raw = process.env[name]
|
|
109
167
|
if (raw === undefined || raw === null || String(raw).trim() === '') return fallback
|
|
@@ -371,11 +429,27 @@ function idsFor(snapshot) {
|
|
|
371
429
|
return ids
|
|
372
430
|
}
|
|
373
431
|
|
|
432
|
+
// ---------------------------------------------------------------------------
|
|
433
|
+
// Schema v20 (0.2.3 persistence v2): the migration ledger plus the per-version
|
|
434
|
+
// step table. The three indexes are new persisted objects too, but the reason
|
|
435
|
+
// this is a schema bump is the new table + the step framework (not the indexes
|
|
436
|
+
// alone: secondary indexes are normally layout-only, see INDEXES).
|
|
437
|
+
// ---------------------------------------------------------------------------
|
|
438
|
+
const SCHEMA_MIGRATIONS_DDL = `CREATE TABLE IF NOT EXISTS schema_migrations (
|
|
439
|
+
version INTEGER PRIMARY KEY,
|
|
440
|
+
name TEXT NOT NULL,
|
|
441
|
+
applied_at TEXT NOT NULL,
|
|
442
|
+
duration_ms INTEGER NOT NULL,
|
|
443
|
+
backup_path TEXT
|
|
444
|
+
);
|
|
445
|
+
`
|
|
446
|
+
|
|
374
447
|
const SCHEMA = `
|
|
375
448
|
CREATE TABLE IF NOT EXISTS matters (
|
|
376
449
|
id TEXT PRIMARY KEY, title TEXT NOT NULL, status TEXT NOT NULL, domain TEXT NOT NULL,
|
|
377
450
|
secrecy INTEGER NOT NULL, summary TEXT, participants TEXT NOT NULL, deadlines TEXT NOT NULL,
|
|
378
|
-
open_questions TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
|
|
451
|
+
open_questions TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
|
|
452
|
+
client_id TEXT, project_id TEXT
|
|
379
453
|
);
|
|
380
454
|
CREATE TABLE IF NOT EXISTS facts (
|
|
381
455
|
id TEXT PRIMARY KEY, matter_id TEXT, subject TEXT NOT NULL, predicate TEXT NOT NULL,
|
|
@@ -387,7 +461,8 @@ CREATE TABLE IF NOT EXISTS facts (
|
|
|
387
461
|
CREATE TABLE IF NOT EXISTS commitments (
|
|
388
462
|
id TEXT PRIMARY KEY, matter_id TEXT NOT NULL, debtor TEXT NOT NULL, creditor TEXT NOT NULL,
|
|
389
463
|
action TEXT NOT NULL, due_at TEXT, timezone TEXT NOT NULL, status TEXT NOT NULL,
|
|
390
|
-
evidence TEXT NOT NULL, capability TEXT NOT NULL, done_at TEXT, reminder_offsets TEXT
|
|
464
|
+
evidence TEXT NOT NULL, capability TEXT NOT NULL, done_at TEXT, reminder_offsets TEXT,
|
|
465
|
+
created_at TEXT
|
|
391
466
|
);
|
|
392
467
|
CREATE TABLE IF NOT EXISTS preferences (
|
|
393
468
|
id TEXT PRIMARY KEY, kind TEXT NOT NULL, statement TEXT NOT NULL, scope TEXT NOT NULL,
|
|
@@ -443,7 +518,9 @@ CREATE TABLE IF NOT EXISTS sessions (
|
|
|
443
518
|
);
|
|
444
519
|
CREATE TABLE IF NOT EXISTS deliveries (
|
|
445
520
|
id TEXT PRIMARY KEY, matter_id TEXT NOT NULL, conversation_id TEXT NOT NULL,
|
|
446
|
-
files TEXT NOT NULL, tool TEXT, title TEXT, validation TEXT, created_at TEXT NOT NULL
|
|
521
|
+
files TEXT NOT NULL, tool TEXT, title TEXT, validation TEXT, created_at TEXT NOT NULL,
|
|
522
|
+
client_id TEXT, project_id TEXT, template_name TEXT, template_version TEXT,
|
|
523
|
+
quote_no TEXT, data_sha256 TEXT
|
|
447
524
|
);
|
|
448
525
|
CREATE TABLE IF NOT EXISTS audit (
|
|
449
526
|
seq INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, actor TEXT NOT NULL,
|
|
@@ -477,8 +554,29 @@ CREATE TABLE IF NOT EXISTS calendar_events (
|
|
|
477
554
|
all_day INTEGER NOT NULL DEFAULT 0, tzid TEXT, location TEXT, rrule TEXT,
|
|
478
555
|
source TEXT, imported_at TEXT NOT NULL
|
|
479
556
|
);
|
|
557
|
+
-- 0.3.0 (schema v21) customer entities. display name + name_norm (application
|
|
558
|
+
-- normalisation: NFKC, zero-width stripped, whitespace folded, lowercase) is
|
|
559
|
+
-- what the partial unique index enforces among active rows, so an archived or
|
|
560
|
+
-- merged client's name can be reused. notes is short operator prose, never a
|
|
561
|
+
-- file path; nothing here is a fourth ledger (see docs/ARCHITECTURE.md).
|
|
562
|
+
CREATE TABLE IF NOT EXISTS clients (
|
|
563
|
+
id TEXT PRIMARY KEY, name TEXT NOT NULL, name_norm TEXT NOT NULL,
|
|
564
|
+
aliases TEXT NOT NULL DEFAULT '[]', status TEXT NOT NULL DEFAULT 'active',
|
|
565
|
+
tags TEXT NOT NULL DEFAULT '[]', secrecy_default INTEGER NOT NULL DEFAULT 0,
|
|
566
|
+
notes TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, deleted_at TEXT
|
|
567
|
+
);
|
|
568
|
+
CREATE TABLE IF NOT EXISTS projects (
|
|
569
|
+
id TEXT PRIMARY KEY, client_id TEXT NOT NULL, name TEXT NOT NULL, name_norm TEXT NOT NULL,
|
|
570
|
+
status TEXT NOT NULL DEFAULT 'active', started_at TEXT, due_at TEXT, default_matter_id TEXT,
|
|
571
|
+
notes TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, deleted_at TEXT
|
|
572
|
+
);
|
|
573
|
+
CREATE TABLE IF NOT EXISTS client_notes (
|
|
574
|
+
id TEXT PRIMARY KEY, client_id TEXT NOT NULL, project_id TEXT, matter_id TEXT,
|
|
575
|
+
kind TEXT NOT NULL, at TEXT NOT NULL, summary TEXT NOT NULL, source TEXT,
|
|
576
|
+
created_at TEXT NOT NULL, deleted_at TEXT
|
|
577
|
+
);
|
|
480
578
|
CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
|
|
481
|
-
`
|
|
579
|
+
${SCHEMA_MIGRATIONS_DDL}`
|
|
482
580
|
|
|
483
581
|
// ---------------------------------------------------------------------------
|
|
484
582
|
// Full-text search (schema v19; 2026-11-17 performance audit round 2, P2-6).
|
|
@@ -556,8 +654,46 @@ function ftsDdl(tokenizer) {
|
|
|
556
654
|
* the 2026-11-17 performance audit (nudges/facts/deliveries/calendar_events/
|
|
557
655
|
* task_runs/sessions/model_calls/preferences/commitments).
|
|
558
656
|
*/
|
|
657
|
+
/** v20 indexes: FTS seq early-stop, fact identity lookup, candidate status. */
|
|
658
|
+
const V20_INDEXES = `
|
|
659
|
+
CREATE INDEX IF NOT EXISTS idx_turns_seq ON turns(seq);
|
|
660
|
+
CREATE INDEX IF NOT EXISTS idx_facts_identity ON facts(subject, predicate, matter_id);
|
|
661
|
+
CREATE INDEX IF NOT EXISTS idx_memory_candidates_status ON memory_candidates(status);
|
|
662
|
+
`
|
|
663
|
+
|
|
664
|
+
/**
|
|
665
|
+
* v21 (customer entities) layout: the partial unique indexes are what makes
|
|
666
|
+
* duplicate active client/project names impossible even under a racing writer,
|
|
667
|
+
* while an archived/merged row may keep its old name so it can be reused. The
|
|
668
|
+
* ownership/lineage indexes serve the derived timeline and the client views;
|
|
669
|
+
* like every secondary index they are layout only (IF NOT EXISTS on open) and
|
|
670
|
+
* do not themselves bump the schema version.
|
|
671
|
+
*/
|
|
672
|
+
const V21_INDEXES = `
|
|
673
|
+
CREATE UNIQUE INDEX IF NOT EXISTS idx_clients_name_norm_active ON clients(name_norm) WHERE status = 'active' AND deleted_at IS NULL;
|
|
674
|
+
CREATE INDEX IF NOT EXISTS idx_clients_status ON clients(status);
|
|
675
|
+
CREATE INDEX IF NOT EXISTS idx_projects_client_status ON projects(client_id, status);
|
|
676
|
+
CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_client_name_active ON projects(client_id, name_norm) WHERE status = 'active' AND deleted_at IS NULL;
|
|
677
|
+
CREATE INDEX IF NOT EXISTS idx_client_notes_client_at ON client_notes(client_id, at DESC);
|
|
678
|
+
CREATE INDEX IF NOT EXISTS idx_matters_client ON matters(client_id, status);
|
|
679
|
+
CREATE INDEX IF NOT EXISTS idx_matters_project ON matters(project_id, status);
|
|
680
|
+
CREATE INDEX IF NOT EXISTS idx_commitments_matter ON commitments(matter_id);
|
|
681
|
+
CREATE INDEX IF NOT EXISTS idx_deliveries_matter ON deliveries(matter_id, created_at);
|
|
682
|
+
`
|
|
683
|
+
/**
|
|
684
|
+
* 0.3.0 P0-T2 (2026-11-20): two more layout-only indexes for the pet-brief read
|
|
685
|
+
* projection. Both replace a full facts scan + TEMP B-TREE on every pet-brief:
|
|
686
|
+
* - (status, confidence) serves the top-N facts by confidence query
|
|
687
|
+
* (measured 40ms -> 5ms at 200k facts);
|
|
688
|
+
* - (status, deleted_at, expired_at, subject) is covering for the redactor
|
|
689
|
+
* name-candidate scan (measured 69ms -> 34ms).
|
|
690
|
+
* Neither changes the schema version: secondary indexes are layout only and
|
|
691
|
+
* are created IF NOT EXISTS on open, like the 0.2.2 P2-1 indexes below.
|
|
692
|
+
*/
|
|
559
693
|
const INDEXES = `
|
|
560
694
|
CREATE INDEX IF NOT EXISTS idx_nudges_commitment_at ON nudges(commitment_id, at);
|
|
695
|
+
CREATE INDEX IF NOT EXISTS idx_facts_status_confidence ON facts(status, confidence);
|
|
696
|
+
CREATE INDEX IF NOT EXISTS idx_facts_valid_subject ON facts(status, deleted_at, expired_at, subject);
|
|
561
697
|
CREATE INDEX IF NOT EXISTS idx_nudges_local_day_level ON nudges(local_day, level);
|
|
562
698
|
CREATE INDEX IF NOT EXISTS idx_nudges_at ON nudges(at);
|
|
563
699
|
CREATE INDEX IF NOT EXISTS idx_commitments_status_due ON commitments(status, due_at);
|
|
@@ -569,14 +705,346 @@ CREATE INDEX IF NOT EXISTS idx_deliveries_created ON deliveries(created_at);
|
|
|
569
705
|
CREATE INDEX IF NOT EXISTS idx_task_runs_created ON task_runs(created_at);
|
|
570
706
|
CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at);
|
|
571
707
|
CREATE INDEX IF NOT EXISTS idx_model_calls_created ON model_calls(created_at);
|
|
572
|
-
|
|
708
|
+
${V20_INDEXES}
|
|
709
|
+
${V21_INDEXES}`
|
|
710
|
+
|
|
711
|
+
|
|
712
|
+
/**
|
|
713
|
+
* Per-version migration steps (schema v20+). Each step must be idempotent
|
|
714
|
+
* (IF NOT EXISTS / INSERT OR REPLACE) because it can be retried after a crash
|
|
715
|
+
* that rolled the transaction back. migrate() runs every step with
|
|
716
|
+
* version > current inside one BEGIN IMMEDIATE, records name/duration/backup
|
|
717
|
+
* in schema_migrations, and only then bumps meta.schema_version.
|
|
718
|
+
*/
|
|
719
|
+
/**
|
|
720
|
+
* Idempotent ALTER TABLE ... ADD COLUMN guard shared by the version steps.
|
|
721
|
+
* SQLite has no ADD COLUMN IF NOT EXISTS, and a step must be retryable after a
|
|
722
|
+
* crash rolled its transaction back (the column is then absent again).
|
|
723
|
+
*/
|
|
724
|
+
function addColumnIfMissing(db, table, column, type) {
|
|
725
|
+
const columns = db.prepare('PRAGMA table_info(' + table + ')').all().map((row) => row.name)
|
|
726
|
+
if (!columns.includes(column)) db.exec('ALTER TABLE ' + table + ' ADD COLUMN ' + column + ' ' + type)
|
|
727
|
+
}
|
|
573
728
|
|
|
729
|
+
/**
|
|
730
|
+
* Per-version migration steps (schema v20+). Each step must be idempotent
|
|
731
|
+
* (IF NOT EXISTS / INSERT OR REPLACE) because it can be retried after a crash
|
|
732
|
+
* that rolled the transaction back. migrate() runs every step with
|
|
733
|
+
* version > current inside one BEGIN IMMEDIATE, records name/duration/backup
|
|
734
|
+
* in schema_migrations, and only then bumps meta.schema_version.
|
|
735
|
+
*/
|
|
736
|
+
const MIGRATIONS = [
|
|
737
|
+
{
|
|
738
|
+
version: 20,
|
|
739
|
+
name: 'incremental-writes-readonly-reads',
|
|
740
|
+
up(store) {
|
|
741
|
+
store.db.exec(SCHEMA_MIGRATIONS_DDL)
|
|
742
|
+
store.db.exec(V20_INDEXES)
|
|
743
|
+
},
|
|
744
|
+
},
|
|
745
|
+
{
|
|
746
|
+
version: 21,
|
|
747
|
+
name: 'client-project-entities-delivery-lineage',
|
|
748
|
+
up(store) {
|
|
749
|
+
// The three new tables are part of SCHEMA and created with IF NOT EXISTS
|
|
750
|
+
// before this step runs (in initializeSchema's transaction), so a fresh
|
|
751
|
+
// database and an upgraded one converge on one layout; CREATE TABLE IF
|
|
752
|
+
// NOT EXISTS cannot add columns to an existing table, so the ownership /
|
|
753
|
+
// lineage columns are added here. All checks are idempotent.
|
|
754
|
+
addColumnIfMissing(store.db, 'matters', 'client_id', 'TEXT')
|
|
755
|
+
addColumnIfMissing(store.db, 'matters', 'project_id', 'TEXT')
|
|
756
|
+
// The derived timeline places a commitment at its creation instant; old
|
|
757
|
+
// rows keep NULL and the derivation reports them as degraded instead of
|
|
758
|
+
// pretending a due date is a historical event.
|
|
759
|
+
addColumnIfMissing(store.db, 'commitments', 'created_at', 'TEXT')
|
|
760
|
+
for (const [column, type] of [
|
|
761
|
+
['client_id', 'TEXT'], ['project_id', 'TEXT'],
|
|
762
|
+
['template_name', 'TEXT'], ['template_version', 'TEXT'],
|
|
763
|
+
['quote_no', 'TEXT'], ['data_sha256', 'TEXT'],
|
|
764
|
+
]) addColumnIfMissing(store.db, 'deliveries', column, type)
|
|
765
|
+
},
|
|
766
|
+
},
|
|
767
|
+
]
|
|
574
768
|
const json = (v) => JSON.stringify(v ?? [])
|
|
575
769
|
const parse = (v, fallback = []) => {
|
|
576
770
|
if (v == null) return fallback
|
|
577
771
|
try { return JSON.parse(v) } catch { return fallback }
|
|
578
772
|
}
|
|
579
773
|
|
|
774
|
+
// ---------------------------------------------------------------------------
|
|
775
|
+
// Customer entity helpers (schema v21, 0.3.0).
|
|
776
|
+
//
|
|
777
|
+
// clients/projects/client_notes are SQLite-only rows: they never enter the wire
|
|
778
|
+
// LedgerSnapshot, so the store is the single gate that validates them (bin and
|
|
779
|
+
// every future caller share this path):
|
|
780
|
+
// - a name is stored twice: name (display, verbatim) and name_norm (the
|
|
781
|
+
// duplicate key produced by normalizeClientName());
|
|
782
|
+
// - nothing is hard-deleted: deleted_at is the tombstone and the partial unique
|
|
783
|
+
// indexes only cover active, non-deleted rows, so a name can be reused after
|
|
784
|
+
// an archive/merge;
|
|
785
|
+
// - notes/summaries are short operator prose; a note source id that looks like
|
|
786
|
+
// an absolute path is refused so an exported customer view cannot carry the
|
|
787
|
+
// home directory with it.
|
|
788
|
+
// ---------------------------------------------------------------------------
|
|
789
|
+
|
|
790
|
+
/** Allowed client/project statuses (archived rows are tombstones). */
|
|
791
|
+
export const CLIENT_STATUSES = ['active', 'archived']
|
|
792
|
+
export const PROJECT_STATUSES = ['active', 'archived']
|
|
793
|
+
/** Allowed client_notes kinds. */
|
|
794
|
+
export const CLIENT_NOTE_KINDS = ['note', 'call', 'meeting', 'decision', 'email-summary']
|
|
795
|
+
/** Allowed client note source kinds (lineage only, never a file copy). */
|
|
796
|
+
export const CLIENT_NOTE_SOURCE_KINDS = ['delivery', 'matter', 'manual']
|
|
797
|
+
|
|
798
|
+
/**
|
|
799
|
+
* Tables that a full export --all carries next to the nine-table ledger
|
|
800
|
+
* snapshot. The three v21 customer tables are appended so an export/import
|
|
801
|
+
* round-trip cannot silently drop them; this constant is the single list the
|
|
802
|
+
* CLI should read instead of hard-coding its own (bin wiring is a separate
|
|
803
|
+
* 0.3.0 task).
|
|
804
|
+
*/
|
|
805
|
+
export const DATA_TABLES = Object.freeze([
|
|
806
|
+
'sessions', 'turns', 'session_summaries', 'summary_versions', 'deliveries', 'nudges',
|
|
807
|
+
'task_runs', 'audit', 'memory_candidates', 'permit_consumed',
|
|
808
|
+
'clients', 'projects', 'client_notes',
|
|
809
|
+
])
|
|
810
|
+
|
|
811
|
+
/** A business error with a stable code (message keeps the code for stderr). */
|
|
812
|
+
export function entityError(code, message, hint) {
|
|
813
|
+
const error = new Error(code + ': ' + message + (hint ? ' (hint: ' + hint + ')' : ''))
|
|
814
|
+
error.code = code
|
|
815
|
+
if (hint) error.hint = hint
|
|
816
|
+
return error
|
|
817
|
+
}
|
|
818
|
+
|
|
819
|
+
/**
|
|
820
|
+
* Duplicate-detection key for a client/project display name.
|
|
821
|
+
*
|
|
822
|
+
* NFKC folds compatibility forms (full-width A -> A), zero-width characters are
|
|
823
|
+
* removed, whitespace is folded/trimmed and lowercasing makes Latin matching
|
|
824
|
+
* case-insensitive (CJK is unchanged). Pure and deterministic so the unique
|
|
825
|
+
* index and the CLI agree byte for byte. Deliberately no fuzzy matching: two
|
|
826
|
+
* different spellings are never guessed to be one customer.
|
|
827
|
+
*/
|
|
828
|
+
export function normalizeClientName(value) {
|
|
829
|
+
if (typeof value !== 'string') throw new TypeError('name must be a string')
|
|
830
|
+
return value
|
|
831
|
+
.normalize('NFKC')
|
|
832
|
+
.replace(/[\u200B-\u200D\u2060\uFEFF]/g, '')
|
|
833
|
+
.trim()
|
|
834
|
+
.replace(/\s+/gu, ' ')
|
|
835
|
+
.toLowerCase()
|
|
836
|
+
}
|
|
837
|
+
|
|
838
|
+
const ABSOLUTE_PATH_RE = /^(?:[A-Za-z]:[\\/]|\/|\\\\)/
|
|
839
|
+
|
|
840
|
+
function invalidKind(kind) {
|
|
841
|
+
return kind === 'client' ? 'E_CLIENT_INVALID' : kind === 'project' ? 'E_PROJECT_INVALID' : 'E_CLIENT_NOTE_INVALID'
|
|
842
|
+
}
|
|
843
|
+
|
|
844
|
+
function validateDisplayName(kind, value, { max = 200 } = {}) {
|
|
845
|
+
if (typeof value !== 'string') throw entityError(invalidKind(kind), kind + ' name is required')
|
|
846
|
+
const name = value.normalize('NFKC').replace(/[\u200B-\u200D\u2060\uFEFF]/g, '').trim()
|
|
847
|
+
if (!name) throw entityError(invalidKind(kind), kind + ' name is required')
|
|
848
|
+
if (name.length > max) throw entityError(invalidKind(kind), kind + ' name is longer than ' + max + ' characters')
|
|
849
|
+
return name
|
|
850
|
+
}
|
|
851
|
+
|
|
852
|
+
function validateEntityStatus(kind, value) {
|
|
853
|
+
const allowed = kind === 'client' ? CLIENT_STATUSES : PROJECT_STATUSES
|
|
854
|
+
if (value === undefined || value === null) return 'active'
|
|
855
|
+
if (!allowed.includes(value)) {
|
|
856
|
+
throw entityError(invalidKind(kind), 'unknown ' + kind + ' status: ' + String(value), 'use one of ' + allowed.join(', '))
|
|
857
|
+
}
|
|
858
|
+
return value
|
|
859
|
+
}
|
|
860
|
+
|
|
861
|
+
function validateStringList(kind, field, value, { max = 100, itemMax = 200 } = {}) {
|
|
862
|
+
if (value === undefined || value === null) return []
|
|
863
|
+
if (!Array.isArray(value)) throw entityError(invalidKind(kind), field + ' must be an array of strings')
|
|
864
|
+
if (value.length > max) throw entityError(invalidKind(kind), field + ' has more than ' + max + ' entries')
|
|
865
|
+
const seen = new Set()
|
|
866
|
+
const list = []
|
|
867
|
+
for (const entry of value) {
|
|
868
|
+
if (typeof entry !== 'string') throw entityError(invalidKind(kind), field + ' must be an array of strings')
|
|
869
|
+
const text = entry.trim()
|
|
870
|
+
if (!text) throw entityError(invalidKind(kind), field + ' entries must not be empty')
|
|
871
|
+
if (text.length > itemMax) throw entityError(invalidKind(kind), field + ' entries must be at most ' + itemMax + ' characters')
|
|
872
|
+
if (seen.has(text)) continue
|
|
873
|
+
seen.add(text)
|
|
874
|
+
list.push(text)
|
|
875
|
+
}
|
|
876
|
+
return list
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
function validateSecrecy(value) {
|
|
880
|
+
if (value === undefined || value === null) return 0
|
|
881
|
+
const number = Number(value)
|
|
882
|
+
if (!Number.isInteger(number) || number < 0 || number > 3) {
|
|
883
|
+
throw entityError('E_CLIENT_INVALID', 'secrecyDefault must be an integer 0..3')
|
|
884
|
+
}
|
|
885
|
+
return number
|
|
886
|
+
}
|
|
887
|
+
|
|
888
|
+
/** Validate an optional date/date-time field and keep the caller text. */
|
|
889
|
+
function normalizeOptionalDate(kind, field, value) {
|
|
890
|
+
if (value === undefined || value === null) return null
|
|
891
|
+
if (typeof value !== 'string') throw entityError(invalidKind(kind), field + ' must be a YYYY-MM-DD date or an ISO timestamp')
|
|
892
|
+
const text = value.trim()
|
|
893
|
+
if (!text) return null
|
|
894
|
+
if (!/^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})?)?$/.test(text) || !Number.isFinite(Date.parse(text))) {
|
|
895
|
+
throw entityError(invalidKind(kind), field + ' must be a YYYY-MM-DD date or an ISO timestamp')
|
|
896
|
+
}
|
|
897
|
+
return text
|
|
898
|
+
}
|
|
899
|
+
|
|
900
|
+
/** Validate an optional free-text field (notes) and keep the caller text. */
|
|
901
|
+
function normalizeOptionalText(kind, field, value, max) {
|
|
902
|
+
if (value === undefined || value === null) return null
|
|
903
|
+
if (typeof value !== 'string') throw entityError(invalidKind(kind), field + ' must be a string')
|
|
904
|
+
const text = value.trim()
|
|
905
|
+
if (!text) return null
|
|
906
|
+
if (text.length > max) throw entityError(invalidKind(kind), field + ' must be at most ' + max + ' characters')
|
|
907
|
+
return text
|
|
908
|
+
}
|
|
909
|
+
|
|
910
|
+
/** Clamp a requested row limit into [1, max]. */
|
|
911
|
+
function normalizeRowLimit(value, { def = 100, max = 1000 } = {}) {
|
|
912
|
+
const number = Number(value)
|
|
913
|
+
if (!Number.isFinite(number) || number <= 0) return def
|
|
914
|
+
return Math.min(Math.floor(number), max)
|
|
915
|
+
}
|
|
916
|
+
|
|
917
|
+
/** Client-note event time: normalized to ISO UTC so ordering is unambiguous. */
|
|
918
|
+
function normalizeNoteInstant(value) {
|
|
919
|
+
if (value === undefined || value === null) return new Date().toISOString()
|
|
920
|
+
const text = String(value).trim()
|
|
921
|
+
const ms = text ? Date.parse(text) : Number.NaN
|
|
922
|
+
if (!Number.isFinite(ms)) throw entityError('E_CLIENT_NOTE_INVALID', 'at must be an ISO timestamp')
|
|
923
|
+
return new Date(ms).toISOString()
|
|
924
|
+
}
|
|
925
|
+
|
|
926
|
+
/** Validate the optional lineage JSON of a client note. */
|
|
927
|
+
function validateNoteSource(value) {
|
|
928
|
+
if (value === undefined || value === null) return null
|
|
929
|
+
if (typeof value !== 'object' || Array.isArray(value)) throw entityError('E_CLIENT_NOTE_INVALID', 'source must be an object')
|
|
930
|
+
const source = {}
|
|
931
|
+
if (value.kind !== undefined) {
|
|
932
|
+
if (!CLIENT_NOTE_SOURCE_KINDS.includes(value.kind)) {
|
|
933
|
+
throw entityError('E_CLIENT_NOTE_INVALID', 'unknown note source kind: ' + String(value.kind), 'use one of ' + CLIENT_NOTE_SOURCE_KINDS.join(', '))
|
|
934
|
+
}
|
|
935
|
+
source.kind = value.kind
|
|
936
|
+
}
|
|
937
|
+
if (value.id !== undefined) {
|
|
938
|
+
if (typeof value.id !== 'string' || !value.id.trim() || value.id.length > 200) {
|
|
939
|
+
throw entityError('E_CLIENT_NOTE_INVALID', 'source.id must be a short id string')
|
|
940
|
+
}
|
|
941
|
+
if (ABSOLUTE_PATH_RE.test(value.id.trim())) throw entityError('E_CLIENT_NOTE_INVALID', 'source.id must be an id, not a file path')
|
|
942
|
+
source.id = value.id.trim()
|
|
943
|
+
}
|
|
944
|
+
if (value.quote !== undefined) {
|
|
945
|
+
if (typeof value.quote !== 'string' || value.quote.length > 500) throw entityError('E_CLIENT_NOTE_INVALID', 'source.quote must be a string of at most 500 characters')
|
|
946
|
+
source.quote = value.quote
|
|
947
|
+
}
|
|
948
|
+
if (source.kind !== undefined && source.kind !== 'manual' && !source.id) {
|
|
949
|
+
throw entityError('E_CLIENT_NOTE_INVALID', 'source.id is required for a ' + source.kind + ' source')
|
|
950
|
+
}
|
|
951
|
+
return JSON.stringify(source)
|
|
952
|
+
}
|
|
953
|
+
|
|
954
|
+
/** Validate the optional delivery template lineage columns (v21). */
|
|
955
|
+
function normalizeDeliveryLineage({ clientId, projectId, templateName, templateVersion, quoteNo, dataSha256 } = {}) {
|
|
956
|
+
const shortText = (field, value, max) => {
|
|
957
|
+
if (value === undefined || value === null) return null
|
|
958
|
+
if (typeof value !== 'string') throw entityError('E_DELIVERY_INVALID', field + ' must be a string')
|
|
959
|
+
const text = value.trim()
|
|
960
|
+
if (!text) return null
|
|
961
|
+
if (text.length > max) throw entityError('E_DELIVERY_INVALID', field + ' must be at most ' + max + ' characters')
|
|
962
|
+
if (ABSOLUTE_PATH_RE.test(text)) throw entityError('E_DELIVERY_INVALID', field + ' must not be a file path')
|
|
963
|
+
return text
|
|
964
|
+
}
|
|
965
|
+
const idOf = (field, value) => {
|
|
966
|
+
if (value === undefined || value === null) return null
|
|
967
|
+
if (typeof value !== 'string' || !value.trim() || value.length > 200) throw entityError('E_DELIVERY_INVALID', field + ' must be an id string')
|
|
968
|
+
return value.trim()
|
|
969
|
+
}
|
|
970
|
+
const sha = dataSha256 === undefined || dataSha256 === null ? null : String(dataSha256).trim().toLowerCase()
|
|
971
|
+
if (sha !== null && !/^[0-9a-f]{64}$/.test(sha)) {
|
|
972
|
+
throw entityError('E_DELIVERY_INVALID', 'dataSha256 must be 64 lowercase hex characters', 'pass the SHA-256 of the canonical template data')
|
|
973
|
+
}
|
|
974
|
+
return {
|
|
975
|
+
clientId: idOf('clientId', clientId),
|
|
976
|
+
projectId: idOf('projectId', projectId),
|
|
977
|
+
templateName: shortText('templateName', templateName, 40),
|
|
978
|
+
templateVersion: shortText('templateVersion', templateVersion, 40),
|
|
979
|
+
quoteNo: shortText('quoteNo', quoteNo, 40),
|
|
980
|
+
dataSha256: sha,
|
|
981
|
+
}
|
|
982
|
+
}
|
|
983
|
+
|
|
984
|
+
const mapClientRow = (row) => ({
|
|
985
|
+
id: row.id,
|
|
986
|
+
name: row.name,
|
|
987
|
+
nameNorm: row.name_norm,
|
|
988
|
+
aliases: parse(row.aliases),
|
|
989
|
+
status: row.status,
|
|
990
|
+
tags: parse(row.tags),
|
|
991
|
+
secrecyDefault: Number(row.secrecy_default),
|
|
992
|
+
notes: row.notes ?? undefined,
|
|
993
|
+
createdAt: row.created_at,
|
|
994
|
+
updatedAt: row.updated_at,
|
|
995
|
+
...(row.deleted_at == null ? {} : { deletedAt: row.deleted_at }),
|
|
996
|
+
})
|
|
997
|
+
|
|
998
|
+
const mapProjectRow = (row) => ({
|
|
999
|
+
id: row.id,
|
|
1000
|
+
clientId: row.client_id,
|
|
1001
|
+
name: row.name,
|
|
1002
|
+
nameNorm: row.name_norm,
|
|
1003
|
+
status: row.status,
|
|
1004
|
+
startedAt: row.started_at ?? undefined,
|
|
1005
|
+
dueAt: row.due_at ?? undefined,
|
|
1006
|
+
defaultMatterId: row.default_matter_id ?? undefined,
|
|
1007
|
+
notes: row.notes ?? undefined,
|
|
1008
|
+
createdAt: row.created_at,
|
|
1009
|
+
updatedAt: row.updated_at,
|
|
1010
|
+
...(row.deleted_at == null ? {} : { deletedAt: row.deleted_at }),
|
|
1011
|
+
})
|
|
1012
|
+
|
|
1013
|
+
const mapClientNoteRow = (row) => ({
|
|
1014
|
+
id: row.id,
|
|
1015
|
+
clientId: row.client_id,
|
|
1016
|
+
projectId: row.project_id ?? undefined,
|
|
1017
|
+
matterId: row.matter_id ?? undefined,
|
|
1018
|
+
kind: row.kind,
|
|
1019
|
+
at: row.at,
|
|
1020
|
+
summary: row.summary,
|
|
1021
|
+
source: row.source ? parse(row.source, undefined) : undefined,
|
|
1022
|
+
createdAt: row.created_at,
|
|
1023
|
+
...(row.deleted_at == null ? {} : { deletedAt: row.deleted_at }),
|
|
1024
|
+
})
|
|
1025
|
+
|
|
1026
|
+
/**
|
|
1027
|
+
* Delivery row + template lineage. Rows written before v21 have no lineage
|
|
1028
|
+
* columns, so the new keys are omitted entirely (the pre-v21 JSON shape is
|
|
1029
|
+
* byte-identical for old rows).
|
|
1030
|
+
*/
|
|
1031
|
+
const mapDeliveryRow = (row) => ({
|
|
1032
|
+
id: row.id,
|
|
1033
|
+
matterId: row.matter_id,
|
|
1034
|
+
conversationId: row.conversation_id,
|
|
1035
|
+
files: parse(row.files),
|
|
1036
|
+
tool: row.tool ?? undefined,
|
|
1037
|
+
title: row.title ?? undefined,
|
|
1038
|
+
validation: row.validation ?? undefined,
|
|
1039
|
+
createdAt: row.created_at,
|
|
1040
|
+
...(row.client_id == null ? {} : { clientId: row.client_id }),
|
|
1041
|
+
...(row.project_id == null ? {} : { projectId: row.project_id }),
|
|
1042
|
+
...(row.template_name == null ? {} : { templateName: row.template_name }),
|
|
1043
|
+
...(row.template_version == null ? {} : { templateVersion: row.template_version }),
|
|
1044
|
+
...(row.quote_no == null ? {} : { quoteNo: row.quote_no }),
|
|
1045
|
+
...(row.data_sha256 == null ? {} : { dataSha256: row.data_sha256 }),
|
|
1046
|
+
})
|
|
1047
|
+
|
|
580
1048
|
// ---------------------------------------------------------------------------
|
|
581
1049
|
// Ledger row mappers + table registry (P1-2, 0.2.2).
|
|
582
1050
|
//
|
|
@@ -592,6 +1060,9 @@ const mapMatterRow = (r) => ({
|
|
|
592
1060
|
id: r.id, title: r.title, status: r.status, domain: r.domain, secrecy: r.secrecy,
|
|
593
1061
|
summary: r.summary ?? undefined, participants: parse(r.participants), deadlines: parse(r.deadlines),
|
|
594
1062
|
openQuestions: parse(r.open_questions), createdAt: r.created_at, updatedAt: r.updated_at,
|
|
1063
|
+
// v21 ownership is additive: pre-v21 rows (NULL) keep their exact old shape.
|
|
1064
|
+
...(r.client_id == null ? {} : { clientId: r.client_id }),
|
|
1065
|
+
...(r.project_id == null ? {} : { projectId: r.project_id }),
|
|
595
1066
|
})
|
|
596
1067
|
|
|
597
1068
|
const mapFactRow = (r) => ({
|
|
@@ -616,6 +1087,8 @@ const mapCommitmentRow = (r) => {
|
|
|
616
1087
|
id: r.id, matterId: r.matter_id, debtor: r.debtor, creditor: r.creditor, action: r.action,
|
|
617
1088
|
dueAt: r.due_at ?? undefined, timezone: r.timezone, status: r.status,
|
|
618
1089
|
evidence: parse(r.evidence), capability: r.capability, doneAt: r.done_at ?? undefined,
|
|
1090
|
+
// v21: additive (rows written before v21 have NULL here).
|
|
1091
|
+
...(r.created_at == null ? {} : { createdAt: r.created_at }),
|
|
619
1092
|
...(reminderOffsets === undefined ? {} : { reminderOffsets }),
|
|
620
1093
|
}
|
|
621
1094
|
}
|
|
@@ -667,11 +1140,281 @@ const LEDGER_TABLE_LOADERS = {
|
|
|
667
1140
|
routes: { table: 'routes', routes: true },
|
|
668
1141
|
}
|
|
669
1142
|
|
|
1143
|
+
|
|
1144
|
+
// ---------------------------------------------------------------------------
|
|
1145
|
+
// Incremental-write row codecs (0.2.3 persistence v2 phase 2).
|
|
1146
|
+
//
|
|
1147
|
+
// _saveRows() below is the historical full-snapshot writer and stays the
|
|
1148
|
+
// import/seed path. The targeted insert*/update* methods must produce exactly
|
|
1149
|
+
// the same column bytes as _saveRows(), so one ENTITY_SPECS table per entity
|
|
1150
|
+
// lists the column + codec of every persisted field. Both paths therefore
|
|
1151
|
+
// cannot drift silently: test/incremental-write.test.js compares the old
|
|
1152
|
+
// load+save result with the targeted-write result row by row.
|
|
1153
|
+
//
|
|
1154
|
+
// Only the four ledger entities touched by the 0.2.3 write commands are
|
|
1155
|
+
// covered; 0.3 replaces this with core's ENTITY_SPECS single source of truth.
|
|
1156
|
+
// ---------------------------------------------------------------------------
|
|
1157
|
+
const encodeText = (v) => (v === undefined || v === null ? null : String(v))
|
|
1158
|
+
const encodeInt = (v) => Math.trunc(Number(v))
|
|
1159
|
+
const encodeReal = (v) => Number(v)
|
|
1160
|
+
const encodeJson = (v) => json(v)
|
|
1161
|
+
const encodeJsonNullable = (v) => (v === undefined || v === null ? null : json(v))
|
|
1162
|
+
const encodeReminderOffsets = (v) => (v === undefined || v === null ? null : JSON.stringify(v))
|
|
1163
|
+
const CODECS = {
|
|
1164
|
+
text: encodeText,
|
|
1165
|
+
int: encodeInt,
|
|
1166
|
+
real: encodeReal,
|
|
1167
|
+
json: encodeJson,
|
|
1168
|
+
'json-nullable': encodeJsonNullable,
|
|
1169
|
+
reminder: encodeReminderOffsets,
|
|
1170
|
+
}
|
|
1171
|
+
|
|
1172
|
+
const ENTITY_SPECS = {
|
|
1173
|
+
matters: {
|
|
1174
|
+
table: 'matters',
|
|
1175
|
+
key: 'id',
|
|
1176
|
+
map: mapMatterRow,
|
|
1177
|
+
columns: {
|
|
1178
|
+
id: ['id', 'text'], title: ['title', 'text'], status: ['status', 'text'], domain: ['domain', 'text'],
|
|
1179
|
+
secrecy: ['secrecy', 'int'], summary: ['summary', 'text'], participants: ['participants', 'json'],
|
|
1180
|
+
deadlines: ['deadlines', 'json'], openQuestions: ['open_questions', 'json'],
|
|
1181
|
+
createdAt: ['created_at', 'text'], updatedAt: ['updated_at', 'text'],
|
|
1182
|
+
clientId: ['client_id', 'text'], projectId: ['project_id', 'text'],
|
|
1183
|
+
},
|
|
1184
|
+
},
|
|
1185
|
+
facts: {
|
|
1186
|
+
table: 'facts',
|
|
1187
|
+
key: 'id',
|
|
1188
|
+
map: mapFactRow,
|
|
1189
|
+
columns: {
|
|
1190
|
+
id: ['id', 'text'], matterId: ['matter_id', 'text'], subject: ['subject', 'text'],
|
|
1191
|
+
predicate: ['predicate', 'text'], object: ['object', 'text'], recordedAt: ['recorded_at', 'text'],
|
|
1192
|
+
expiredAt: ['expired_at', 'text'], authority: ['authority', 'text'], confidence: ['confidence', 'real'],
|
|
1193
|
+
source: ['source', 'json-nullable'], evidence: ['evidence', 'json-nullable'], status: ['status', 'text'],
|
|
1194
|
+
validFrom: ['valid_from', 'text'], validTo: ['valid_to', 'text'], supersedes: ['supersedes', 'text'],
|
|
1195
|
+
supersededBy: ['superseded_by', 'text'], shadowedBy: ['shadowed_by', 'text'],
|
|
1196
|
+
lastSeenAt: ['last_seen_at', 'text'], deletedAt: ['deleted_at', 'text'], deletedReason: ['deleted_reason', 'text'],
|
|
1197
|
+
},
|
|
1198
|
+
},
|
|
1199
|
+
commitments: {
|
|
1200
|
+
table: 'commitments',
|
|
1201
|
+
key: 'id',
|
|
1202
|
+
map: mapCommitmentRow,
|
|
1203
|
+
columns: {
|
|
1204
|
+
id: ['id', 'text'], matterId: ['matter_id', 'text'], debtor: ['debtor', 'text'], creditor: ['creditor', 'text'],
|
|
1205
|
+
action: ['action', 'text'], dueAt: ['due_at', 'text'], timezone: ['timezone', 'text'], status: ['status', 'text'],
|
|
1206
|
+
evidence: ['evidence', 'json'], capability: ['capability', 'text'], doneAt: ['done_at', 'text'],
|
|
1207
|
+
reminderOffsets: ['reminder_offsets', 'reminder'], createdAt: ['created_at', 'text'],
|
|
1208
|
+
},
|
|
1209
|
+
},
|
|
1210
|
+
preferences: {
|
|
1211
|
+
table: 'preferences',
|
|
1212
|
+
key: 'id',
|
|
1213
|
+
map: mapPreferenceRow,
|
|
1214
|
+
columns: {
|
|
1215
|
+
id: ['id', 'text'], kind: ['kind', 'text'], statement: ['statement', 'text'], scope: ['scope', 'json'],
|
|
1216
|
+
source: ['source', 'json'], evidence: ['evidence', 'json'], confidence: ['confidence', 'real'],
|
|
1217
|
+
status: ['status', 'text'], validFrom: ['valid_from', 'text'], lastConfirmed: ['last_confirmed', 'text'],
|
|
1218
|
+
expiresAt: ['expires_at', 'text'], priority: ['priority', 'text'],
|
|
1219
|
+
},
|
|
1220
|
+
},
|
|
1221
|
+
}
|
|
1222
|
+
|
|
1223
|
+
function encodeEntityValue(codec, value) {
|
|
1224
|
+
const encode = CODECS[codec]
|
|
1225
|
+
if (!encode) throw new Error(`unknown entity column codec: ${codec}`)
|
|
1226
|
+
return encode(value)
|
|
1227
|
+
}
|
|
1228
|
+
|
|
1229
|
+
/**
|
|
1230
|
+
* Tables whose row counts are sampled to verify a pre-migration backup. The
|
|
1231
|
+
* v21 customer tables are included so a future migration's backup verification
|
|
1232
|
+
* also proves the customer entities were copied (they are absent in older
|
|
1233
|
+
* databases and are then skipped by _sampleTableCounts).
|
|
1234
|
+
*/
|
|
1235
|
+
const BACKUP_SAMPLE_TABLES = ['matters', 'facts', 'commitments', 'preferences', 'audit', 'clients', 'projects', 'client_notes']
|
|
1236
|
+
// ---------------------------------------------------------------------------
|
|
1237
|
+
// WAL status / recovery (robustness audit 2026-11-17 P1-6).
|
|
1238
|
+
//
|
|
1239
|
+
// SQLite's documented recovery semantics: a WAL whose header is invalid, whose
|
|
1240
|
+
// last frame is torn, or whose checksums do not verify is treated as if it
|
|
1241
|
+
// contained no transactions. The database still opens (that is safe for the
|
|
1242
|
+
// main file) but every transaction committed since the last checkpoint that
|
|
1243
|
+
// only lived in the WAL is silently lost, and `quick_check` still says ok.
|
|
1244
|
+
//
|
|
1245
|
+
// This pre-open check classifies the sidecar BEFORE SQLite can ignore it:
|
|
1246
|
+
// - invalid (bad magic/version/page-size/header checksum, or a stale first
|
|
1247
|
+
// frame): preserve the bytes as state.db-wal.corrupt-<ts>, move the unusable
|
|
1248
|
+
// WAL aside (and the rebuildable -shm cache), then warn loudly and record a
|
|
1249
|
+
// quick_check of the surviving database;
|
|
1250
|
+
// - truncated (valid header, size not a whole number of frames): keep the WAL
|
|
1251
|
+
// so SQLite recovers its valid prefix, copy it aside as evidence, and warn
|
|
1252
|
+
// that frames after the tear may be lost;
|
|
1253
|
+
// - ok / absent / empty: no warning (the common case has no extra I/O cost).
|
|
1254
|
+
// No database bytes are ever deleted: the preserved copy is the recovery path.
|
|
1255
|
+
// `inspectWalStatus()` is also exported so bin/doctor can report the sidecar
|
|
1256
|
+
// without opening the store (Wave 1 `doctor --check-db` / `audit --check-db`).
|
|
1257
|
+
// ---------------------------------------------------------------------------
|
|
1258
|
+
const WAL_HEADER_SIZE = 32
|
|
1259
|
+
const WAL_FRAME_HEADER_SIZE = 24
|
|
1260
|
+
const WAL_VERSION = 3007000
|
|
1261
|
+
const WAL_MAGIC_LE = 0x377f0682
|
|
1262
|
+
const WAL_MAGIC_BE = 0x377f0683
|
|
1263
|
+
/** Suffix of a preserved copy of a WAL file SQLite cannot use (0600). */
|
|
1264
|
+
export const WAL_CORRUPT_SUFFIX = '-wal.corrupt-'
|
|
1265
|
+
|
|
1266
|
+
/** SQLite WAL checksum: cumulative s1/s2 over 32-bit words (big- or little-endian). */
|
|
1267
|
+
function walChecksum(bytes, bigEndian, start1 = 0, start2 = 0) {
|
|
1268
|
+
let s1 = start1 >>> 0
|
|
1269
|
+
let s2 = start2 >>> 0
|
|
1270
|
+
for (let offset = 0; offset + 8 <= bytes.length; offset += 8) {
|
|
1271
|
+
const first = bigEndian ? bytes.readUInt32BE(offset) : bytes.readUInt32LE(offset)
|
|
1272
|
+
const second = bigEndian ? bytes.readUInt32BE(offset + 4) : bytes.readUInt32LE(offset + 4)
|
|
1273
|
+
s1 = (s1 + first + s2) >>> 0
|
|
1274
|
+
s2 = (s2 + second + s1) >>> 0
|
|
1275
|
+
}
|
|
1276
|
+
return [s1 >>> 0, s2 >>> 0]
|
|
1277
|
+
}
|
|
1278
|
+
|
|
1279
|
+
function readAtSync(file, position, length) {
|
|
1280
|
+
const fd = openSync(file, 'r')
|
|
1281
|
+
try {
|
|
1282
|
+
const buffer = Buffer.alloc(length)
|
|
1283
|
+
const bytesRead = readSync(fd, buffer, 0, length, position)
|
|
1284
|
+
return buffer.subarray(0, bytesRead)
|
|
1285
|
+
} finally {
|
|
1286
|
+
try { closeSync(fd) } catch {}
|
|
1287
|
+
}
|
|
1288
|
+
}
|
|
1289
|
+
|
|
1290
|
+
function corruptStamp(now) {
|
|
1291
|
+
return new Date(now).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z')
|
|
1292
|
+
}
|
|
1293
|
+
|
|
1294
|
+
/** Report the state of <db>-wal without opening SQLite or modifying anything. */
|
|
1295
|
+
export function inspectWalStatus(dbPath) {
|
|
1296
|
+
const path = `${dbPath}-wal`
|
|
1297
|
+
const report = { path, present: false, bytes: 0, status: 'absent', frames: 0, pageSize: null, header: null, reason: null, warning: null }
|
|
1298
|
+
if (!dbPath || dbPath === ':memory:') { report.status = 'memory'; return report }
|
|
1299
|
+
let stat
|
|
1300
|
+
try { stat = statSync(path) } catch (error) {
|
|
1301
|
+
if (error?.code !== 'ENOENT') { report.status = 'unreadable'; report.reason = String(error?.message ?? error); report.warning = `E_WAL_UNREADABLE: cannot inspect ${path} (${report.reason}); if the database is open elsewhere, close it and retry` }
|
|
1302
|
+
return report
|
|
1303
|
+
}
|
|
1304
|
+
report.present = true
|
|
1305
|
+
report.bytes = stat.size
|
|
1306
|
+
if (!stat.isFile()) { report.status = 'invalid'; report.reason = 'not-a-regular-file'; return report }
|
|
1307
|
+
if (stat.size === 0) { report.status = 'empty'; return report }
|
|
1308
|
+
if (stat.size < WAL_HEADER_SIZE) { report.status = 'invalid'; report.reason = `truncated header (${stat.size} of ${WAL_HEADER_SIZE} bytes)`; return report }
|
|
1309
|
+
let header
|
|
1310
|
+
try { header = readAtSync(path, 0, WAL_HEADER_SIZE) } catch (error) { report.status = 'unreadable'; report.reason = String(error?.message ?? error); return report }
|
|
1311
|
+
if (header.length < WAL_HEADER_SIZE) { report.status = 'invalid'; report.reason = 'truncated header'; return report }
|
|
1312
|
+
const magic = header.readUInt32BE(0)
|
|
1313
|
+
const version = header.readUInt32BE(4)
|
|
1314
|
+
const pageSize = header.readUInt32BE(8)
|
|
1315
|
+
if (magic !== WAL_MAGIC_LE && magic !== WAL_MAGIC_BE) { report.status = 'invalid'; report.reason = `bad WAL magic 0x${magic.toString(16)} (header was overwritten or truncated)`; return report }
|
|
1316
|
+
if (version !== WAL_VERSION) { report.status = 'invalid'; report.reason = `unsupported WAL format version ${version}`; return report }
|
|
1317
|
+
if (!Number.isInteger(pageSize) || pageSize < 512 || pageSize > 65536 || (pageSize & (pageSize - 1)) !== 0) { report.status = 'invalid'; report.reason = `invalid WAL page size ${pageSize}`; return report }
|
|
1318
|
+
const bigEndian = magic === WAL_MAGIC_BE
|
|
1319
|
+
const [checksum1, checksum2] = walChecksum(header.subarray(0, 24), bigEndian)
|
|
1320
|
+
if (checksum1 !== header.readUInt32BE(24) || checksum2 !== header.readUInt32BE(28)) { report.status = 'invalid'; report.reason = 'WAL header checksum mismatch'; return report }
|
|
1321
|
+
report.pageSize = pageSize
|
|
1322
|
+
report.header = { magic: bigEndian ? 'be' : 'le', version, pageSize }
|
|
1323
|
+
// A writer may be appending right now (direct library use has no instance
|
|
1324
|
+
// lock). Only classify a size-based tear when the size is stable; otherwise
|
|
1325
|
+
// report 'changing' and stay quiet instead of warning about a false tear.
|
|
1326
|
+
let stable
|
|
1327
|
+
try { stable = statSync(path) } catch (error) { report.status = 'unreadable'; report.reason = String(error?.message ?? error); return report }
|
|
1328
|
+
if (stable.size !== stat.size) { report.status = 'changing'; return report }
|
|
1329
|
+
const frameSize = WAL_FRAME_HEADER_SIZE + pageSize
|
|
1330
|
+
const payloadBytes = stat.size - WAL_HEADER_SIZE
|
|
1331
|
+
report.frames = Math.floor(payloadBytes / frameSize)
|
|
1332
|
+
if (payloadBytes % frameSize !== 0) {
|
|
1333
|
+
report.status = 'truncated'
|
|
1334
|
+
report.reason = 'torn-frame'
|
|
1335
|
+
report.warning = `E_WAL_TRUNCATED: ${path} ends with a torn/partial frame (${payloadBytes % frameSize} of ${frameSize} bytes); SQLite recovers only the complete frames before the tear, so the most recently committed transactions may be lost`
|
|
1336
|
+
return report
|
|
1337
|
+
}
|
|
1338
|
+
if (report.frames > 0) {
|
|
1339
|
+
try {
|
|
1340
|
+
const firstFrame = readAtSync(path, WAL_HEADER_SIZE, WAL_FRAME_HEADER_SIZE)
|
|
1341
|
+
if (firstFrame.length === WAL_FRAME_HEADER_SIZE) {
|
|
1342
|
+
const salt1 = firstFrame.readUInt32BE(8)
|
|
1343
|
+
const salt2 = firstFrame.readUInt32BE(12)
|
|
1344
|
+
if (salt1 !== header.readUInt32BE(16) || salt2 !== header.readUInt32BE(20)) {
|
|
1345
|
+
report.status = 'invalid'
|
|
1346
|
+
report.reason = 'stale first frame (WAL salt mismatch)'
|
|
1347
|
+
return report
|
|
1348
|
+
}
|
|
1349
|
+
}
|
|
1350
|
+
} catch {}
|
|
1351
|
+
}
|
|
1352
|
+
report.status = 'ok'
|
|
1353
|
+
return report
|
|
1354
|
+
}
|
|
1355
|
+
|
|
1356
|
+
/** Copy a WAL sidecar next to the database as evidence (0600, fsynced). */
|
|
1357
|
+
function preserveWalCopy(dbPath, report, { now = Date.now() } = {}) {
|
|
1358
|
+
const backup = `${dbPath}${WAL_CORRUPT_SUFFIX}${corruptStamp(now)}`
|
|
1359
|
+
try {
|
|
1360
|
+
copyFileWithRetrySync(report.path, backup, { mode: 0o600 })
|
|
1361
|
+
fsyncFileSync(backup)
|
|
1362
|
+
return { backup, error: null }
|
|
1363
|
+
} catch (error) {
|
|
1364
|
+
return { backup: null, error }
|
|
1365
|
+
}
|
|
1366
|
+
}
|
|
1367
|
+
|
|
1368
|
+
/**
|
|
1369
|
+
* Inspect (and, for a writable open, quarantine) a WAL before SQLite sees it.
|
|
1370
|
+
* Returns the inspection report plus `backup` / `quarantined` / `warning`.
|
|
1371
|
+
* For readOnly opens nothing is written: the DB is only reported on.
|
|
1372
|
+
*/
|
|
1373
|
+
export function prepareWalForOpen(dbPath, { readOnly = false, now = Date.now() } = {}) {
|
|
1374
|
+
const report = inspectWalStatus(dbPath)
|
|
1375
|
+
if (report.status !== 'invalid' && report.status !== 'truncated') return report
|
|
1376
|
+
if (readOnly) {
|
|
1377
|
+
report.note = 'read-only open: the WAL was inspected but not modified; run a writable maintenance command (for example `advisers doctor --check-db`) to preserve and quarantine it'
|
|
1378
|
+
if (report.status === 'invalid') {
|
|
1379
|
+
report.warning = `E_WAL_CORRUPT: the WAL file ${report.path} cannot be used by SQLite (${report.reason}); read-only open left it untouched. Run 'advisers doctor --check-db' to preserve and quarantine it; transactions committed after the last checkpoint may be lost.`
|
|
1380
|
+
} else {
|
|
1381
|
+
report.warning = `${report.warning}. Read-only open left it untouched; run 'advisers doctor --check-db' to preserve it.`
|
|
1382
|
+
}
|
|
1383
|
+
return report
|
|
1384
|
+
}
|
|
1385
|
+
const preserved = preserveWalCopy(dbPath, report, { now })
|
|
1386
|
+
report.backup = preserved.backup
|
|
1387
|
+
report.preserveError = preserved.error ? String(preserved.error?.message ?? preserved.error) : null
|
|
1388
|
+
if (report.status === 'invalid' && preserved.backup) {
|
|
1389
|
+
try {
|
|
1390
|
+
rmWithRetrySync(report.path)
|
|
1391
|
+
try { if (existsSync(`${dbPath}-shm`)) rmWithRetrySync(`${dbPath}-shm`) } catch {}
|
|
1392
|
+
report.quarantined = true
|
|
1393
|
+
} catch (error) {
|
|
1394
|
+
report.quarantined = false
|
|
1395
|
+
report.preserveError = String(error?.message ?? error)
|
|
1396
|
+
}
|
|
1397
|
+
}
|
|
1398
|
+
const preservedText = report.backup
|
|
1399
|
+
? ` the file was preserved as ${report.backup}.`
|
|
1400
|
+
: ` the file could not be preserved (${report.preserveError ?? 'unknown error'}).`
|
|
1401
|
+
if (report.status === 'invalid') {
|
|
1402
|
+
report.warning = `E_WAL_CORRUPT: the WAL file ${report.path} cannot be used by SQLite (${report.reason}); SQLite ignores an invalid WAL, so transactions committed after the last checkpoint may be lost.${preservedText} Run 'advisers doctor' and take a fresh 'advisers backup'; for forensic recovery open the preserved copy with the sqlite3 CLI.`
|
|
1403
|
+
} else {
|
|
1404
|
+
report.warning = `${report.warning}.${preservedText} Run 'advisers doctor' before relying on the most recent writes.`
|
|
1405
|
+
}
|
|
1406
|
+
return report
|
|
1407
|
+
}
|
|
1408
|
+
|
|
670
1409
|
export class SqliteStore {
|
|
671
1410
|
constructor(path, { readOnly = false, checkIntegrity = false, busyTimeoutMs = Number(process.env.ADVISERS_SQLITE_BUSY_TIMEOUT_MS) || DEFAULT_BUSY_TIMEOUT_MS } = {}) {
|
|
672
1411
|
this.path = path
|
|
673
1412
|
this.busyTimeoutMs = busyTimeoutMs
|
|
1413
|
+
// 0.2.3 read path: a read-only store never runs DDL/migrate/journal-mode
|
|
1414
|
+
// pragmas and refuses every write method with E_READ_ONLY (see read()).
|
|
1415
|
+
this.readOnly = Boolean(readOnly)
|
|
674
1416
|
this._transactionDepth = 0
|
|
1417
|
+
this._readDepth = 0
|
|
675
1418
|
this._baselineIds = null
|
|
676
1419
|
this._fullLoad = false
|
|
677
1420
|
// FTS5 state (schema v19): which indexes exist and which tokenizer built
|
|
@@ -680,22 +1423,63 @@ export class SqliteStore {
|
|
|
680
1423
|
this.ftsTokenizer = null
|
|
681
1424
|
this.ftsWarning = null
|
|
682
1425
|
this._ftsTables = new Set()
|
|
1426
|
+
// P1-5: searchTurns()/searchSummaries() set these when FTS and LIKE
|
|
1427
|
+
// disagree; verifyFtsIntegrity() fills ftsIntegrityReport for doctor.
|
|
1428
|
+
this._ftsBroken = false
|
|
1429
|
+
this._ftsWarned = false
|
|
1430
|
+
this.ftsIntegrityWarning = null
|
|
1431
|
+
this.ftsIntegrityReport = null
|
|
683
1432
|
// P2-2 (0.2.1): an existing 0-byte file is treated as corrupt instead of a
|
|
684
1433
|
// brand-new database. Before this, SQLite turned it into an empty schema and
|
|
685
1434
|
// every command reported "no data" while silently rebuilding the ledger.
|
|
686
1435
|
assertDatabaseFileUsable(path)
|
|
1436
|
+
// P1-6: classify (and, for writable opens, quarantine) an unusable WAL
|
|
1437
|
+
// before SQLite opens the file and treats it as empty. `walStatus` is kept
|
|
1438
|
+
// on the store so doctor/audit can report it (see walReport()).
|
|
1439
|
+
this.walStatus = null
|
|
687
1440
|
try {
|
|
1441
|
+
this.walStatus = prepareWalForOpen(path, { readOnly })
|
|
1442
|
+
if (this.walStatus.warning) {
|
|
1443
|
+
try { console.warn(`advisers: warning: ${this.walStatus.warning}`) } catch {}
|
|
1444
|
+
}
|
|
688
1445
|
this.db = readOnly ? new DatabaseSync(path, { readOnly: true }) : new DatabaseSync(path)
|
|
689
1446
|
// P0-1: sqlite only applies busy_timeout to statements that run after the
|
|
690
1447
|
// pragma is set; concurrent first-opens used to fail on journal_mode=WAL
|
|
691
1448
|
// because busy_timeout was set afterwards.
|
|
692
1449
|
this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(Number(busyTimeoutMs) || 0))}`)
|
|
1450
|
+
if (this.walStatus.quarantined) {
|
|
1451
|
+
// The pre-check moved an unusable WAL aside; verify that the surviving
|
|
1452
|
+
// main database is structurally sound (this is the one open where the
|
|
1453
|
+
// O(db) quick_check cost is justified).
|
|
1454
|
+
try {
|
|
1455
|
+
const recovered = this.db.prepare('PRAGMA quick_check').get()
|
|
1456
|
+
this.walStatus.recovery = { quickCheck: String(recovered?.quick_check ?? 'unknown') }
|
|
1457
|
+
if (this.walStatus.recovery.quickCheck !== 'ok') {
|
|
1458
|
+
try { console.warn(`advisers: warning: quick_check after WAL recovery reported '${this.walStatus.recovery.quickCheck}'`) } catch {}
|
|
1459
|
+
}
|
|
1460
|
+
} catch (error) {
|
|
1461
|
+
this.walStatus.recovery = { error: String(error?.message ?? error) }
|
|
1462
|
+
}
|
|
1463
|
+
}
|
|
693
1464
|
if (readOnly) {
|
|
694
1465
|
this._initFtsState()
|
|
695
1466
|
if (checkIntegrity) this.assertIntegrity()
|
|
696
1467
|
return
|
|
697
1468
|
}
|
|
698
1469
|
this.enableWal()
|
|
1470
|
+
// A torn WAL was preserved by the pre-open check. Fold its valid prefix
|
|
1471
|
+
// into the main database and truncate the sidecar so subsequent opens are
|
|
1472
|
+
// clean; the preserved copy remains available for forensics.
|
|
1473
|
+
if (this.walStatus?.status === 'truncated' && this.walStatus.backup) {
|
|
1474
|
+
try {
|
|
1475
|
+
this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)')
|
|
1476
|
+
this.walStatus.recovered = true
|
|
1477
|
+
this.walStatus.current = inspectWalStatus(path)
|
|
1478
|
+
} catch (error) {
|
|
1479
|
+
this.walStatus.recovered = false
|
|
1480
|
+
this.walStatus.recoveryError = String(error?.message ?? error)
|
|
1481
|
+
}
|
|
1482
|
+
}
|
|
699
1483
|
this.db.exec('PRAGMA secure_delete = ON')
|
|
700
1484
|
this.db.exec('PRAGMA synchronous = NORMAL')
|
|
701
1485
|
this.initializeSchema()
|
|
@@ -709,6 +1493,75 @@ export class SqliteStore {
|
|
|
709
1493
|
}
|
|
710
1494
|
}
|
|
711
1495
|
|
|
1496
|
+
// -------------------------------------------------------------------------
|
|
1497
|
+
// Read-only access (0.2.3 read path; 03-design-persistence-v2.md §4).
|
|
1498
|
+
//
|
|
1499
|
+
// A read-only store never enables WAL, never runs DDL/migrate and never
|
|
1500
|
+
// takes the HOME instance lock (that lock lives in bin/ and only protects
|
|
1501
|
+
// writers), so pure-read commands work while another process holds the write
|
|
1502
|
+
// lock. The connection reads a committed WAL snapshot: an uncommitted writer
|
|
1503
|
+
// transaction is invisible and does not block the reader.
|
|
1504
|
+
// -------------------------------------------------------------------------
|
|
1505
|
+
|
|
1506
|
+
/** meta.schema_version, or null when the meta table/row does not exist. */
|
|
1507
|
+
schemaVersion() {
|
|
1508
|
+
try {
|
|
1509
|
+
const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
|
|
1510
|
+
return row ? Number(row.value) : null
|
|
1511
|
+
} catch {
|
|
1512
|
+
return null
|
|
1513
|
+
}
|
|
1514
|
+
}
|
|
1515
|
+
|
|
1516
|
+
/** Throw E_SCHEMA_STALE / E_SCHEMA_NEWER unless this database is current. */
|
|
1517
|
+
assertSchemaCurrent() {
|
|
1518
|
+
const version = this.schemaVersion()
|
|
1519
|
+
if (version === SCHEMA_VERSION) return version
|
|
1520
|
+
if (version !== null && version > SCHEMA_VERSION) throw schemaNewerError(this.path, version)
|
|
1521
|
+
throw schemaStaleError(this.path, version)
|
|
1522
|
+
}
|
|
1523
|
+
|
|
1524
|
+
/** Throw E_READ_ONLY for any write attempted on a read-only store. */
|
|
1525
|
+
_assertWritable(operation = 'write') {
|
|
1526
|
+
if (!this.readOnly) return
|
|
1527
|
+
const error = new Error(`E_READ_ONLY: ${operation} is not available on a read-only SqliteStore (${this.path}); open a writable store to change the ledger`)
|
|
1528
|
+
error.name = 'ReadOnlyStoreError'
|
|
1529
|
+
error.code = 'E_READ_ONLY'
|
|
1530
|
+
error.operation = operation
|
|
1531
|
+
throw error
|
|
1532
|
+
}
|
|
1533
|
+
|
|
1534
|
+
/** Directed row writes are only valid inside mutate()/transaction(). */
|
|
1535
|
+
_assertInWriteTransaction(operation) {
|
|
1536
|
+
this._assertWritable(operation)
|
|
1537
|
+
if (this._transactionDepth > 0) return
|
|
1538
|
+
const error = new Error(`E_TX_REQUIRED: ${operation} must run inside SqliteStore.mutate() or transaction() (${this.path})`)
|
|
1539
|
+
error.name = 'TransactionRequiredError'
|
|
1540
|
+
error.code = 'E_TX_REQUIRED'
|
|
1541
|
+
throw error
|
|
1542
|
+
}
|
|
1543
|
+
|
|
1544
|
+
/**
|
|
1545
|
+
* Run fn inside one read transaction so several SELECTs see the same WAL
|
|
1546
|
+
* snapshot (multi-query commands: status/receipt/deliveries/doctor/export).
|
|
1547
|
+
* A read() nested inside a write transaction joins that transaction.
|
|
1548
|
+
*/
|
|
1549
|
+
read(fn) {
|
|
1550
|
+
if (typeof fn !== 'function') throw new TypeError('read requires a function')
|
|
1551
|
+
if (this._transactionDepth > 0 || this._readDepth > 0) return fn(this)
|
|
1552
|
+
this.db.exec('BEGIN DEFERRED')
|
|
1553
|
+
this._readDepth++
|
|
1554
|
+
try {
|
|
1555
|
+
const result = fn(this)
|
|
1556
|
+
this.db.exec('COMMIT')
|
|
1557
|
+
return result
|
|
1558
|
+
} catch (error) {
|
|
1559
|
+
try { this.db.exec('ROLLBACK') } catch {}
|
|
1560
|
+
throw error
|
|
1561
|
+
} finally {
|
|
1562
|
+
this._readDepth--
|
|
1563
|
+
}
|
|
1564
|
+
}
|
|
712
1565
|
/** Full-database integrity check; explicit because it is O(database size). */
|
|
713
1566
|
assertIntegrity() {
|
|
714
1567
|
const row = this.db.prepare('PRAGMA quick_check').get()
|
|
@@ -717,8 +1570,37 @@ export class SqliteStore {
|
|
|
717
1570
|
return verdict
|
|
718
1571
|
}
|
|
719
1572
|
|
|
1573
|
+
/**
|
|
1574
|
+
* Aggregate integrity report for `doctor --check-db` / `audit --check-db`
|
|
1575
|
+
* (Wave 1 contract). quick_check is O(db) and the FTS check is O(index), so
|
|
1576
|
+
* both are opt-in; the WAL report is cheap and always included.
|
|
1577
|
+
*/
|
|
1578
|
+
integrityReport({ quickCheck = true, fts = false } = {}) {
|
|
1579
|
+
const report = { ok: true, path: this.path, schemaVersion: null, quickCheck: null, wal: null, fts: null, errors: [] }
|
|
1580
|
+
try { report.schemaVersion = this.getMeta('schema_version') } catch (error) { report.errors.push(`cannot read schema_version: ${String(error?.message ?? error).slice(0, 160)}`) }
|
|
1581
|
+
if (quickCheck) {
|
|
1582
|
+
try {
|
|
1583
|
+
const verdict = String(this.db.prepare('PRAGMA quick_check').get()?.quick_check ?? 'unknown')
|
|
1584
|
+
report.quickCheck = { ok: verdict === 'ok', verdict }
|
|
1585
|
+
if (verdict !== 'ok') { report.ok = false; report.errors.push(`PRAGMA quick_check: ${verdict}`) }
|
|
1586
|
+
} catch (error) {
|
|
1587
|
+
report.quickCheck = { ok: false, error: String(error?.message ?? error).slice(0, 200) }
|
|
1588
|
+
report.ok = false
|
|
1589
|
+
report.errors.push(`PRAGMA quick_check failed: ${report.quickCheck.error}`)
|
|
1590
|
+
}
|
|
1591
|
+
}
|
|
1592
|
+
report.wal = this.walReport()
|
|
1593
|
+
if (!report.wal.ok) { report.ok = false; if (report.wal.initial?.warning) report.errors.push(report.wal.initial.warning) }
|
|
1594
|
+
if (fts) {
|
|
1595
|
+
report.fts = this.verifyFtsIntegrity()
|
|
1596
|
+
if (!report.fts.ok) { report.ok = false; if (report.fts.warning) report.errors.push(report.fts.warning) }
|
|
1597
|
+
}
|
|
1598
|
+
return report
|
|
1599
|
+
}
|
|
1600
|
+
|
|
720
1601
|
/** WAL is persistent; skip the switch when already enabled and retry on busy. */
|
|
721
1602
|
enableWal() {
|
|
1603
|
+
this._assertWritable('enableWal')
|
|
722
1604
|
if (!this.path || this.path === ':memory:') return 'memory'
|
|
723
1605
|
const current = String(this.db.prepare('PRAGMA journal_mode').get()?.journal_mode ?? '').toLowerCase()
|
|
724
1606
|
if (current === 'wal' || current === 'memory') return current
|
|
@@ -739,6 +1621,12 @@ export class SqliteStore {
|
|
|
739
1621
|
}
|
|
740
1622
|
|
|
741
1623
|
initializeSchema() {
|
|
1624
|
+
this._assertWritable('initializeSchema')
|
|
1625
|
+
// P2-9: migration backups must be taken OUTSIDE the write transaction --
|
|
1626
|
+
// a 'wal_checkpoint(TRUNCATE)' inside BEGIN IMMEDIATE fails with 'database
|
|
1627
|
+
// table is locked', and copying the main file without folding the WAL can
|
|
1628
|
+
// silently omit committed rows. Read the old version and back up first.
|
|
1629
|
+
this._migrationBackup = this._prepareMigrationBackup()
|
|
742
1630
|
this._transaction('IMMEDIATE', () => {
|
|
743
1631
|
this.db.exec(SCHEMA)
|
|
744
1632
|
this.migrate()
|
|
@@ -830,11 +1718,185 @@ export class SqliteStore {
|
|
|
830
1718
|
return tokenizer
|
|
831
1719
|
}
|
|
832
1720
|
|
|
1721
|
+
/**
|
|
1722
|
+
* Report the WAL/shm state and whether this connection can checkpoint.
|
|
1723
|
+
* `initial` is the pre-open inspection (see inspectWalStatus above); a fresh
|
|
1724
|
+
* `current` read lets a long-lived store (mcp/ui) be diagnosed too.
|
|
1725
|
+
*/
|
|
1726
|
+
walReport() {
|
|
1727
|
+
const report = {
|
|
1728
|
+
path: this.path,
|
|
1729
|
+
initial: this.walStatus ?? { status: 'absent', present: false },
|
|
1730
|
+
current: inspectWalStatus(this.path),
|
|
1731
|
+
}
|
|
1732
|
+
try { report.journalMode = String(this.db.prepare('PRAGMA journal_mode').get()?.journal_mode ?? '') } catch (error) { report.journalModeError = String(error?.message ?? error) }
|
|
1733
|
+
try {
|
|
1734
|
+
const checkpoint = this.db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get()
|
|
1735
|
+
report.checkpoint = { busy: Number(checkpoint?.busy ?? 0) !== 0, log: Number(checkpoint?.log ?? 0), checkpointed: Number(checkpoint?.checkpointed ?? 0) }
|
|
1736
|
+
} catch (error) { report.checkpoint = { error: String(error?.message ?? error) } }
|
|
1737
|
+
const bad = (status) => ['invalid', 'truncated', 'unreadable'].includes(String(status))
|
|
1738
|
+
// A WAL that was preserved and then quarantined/checkpointed is reported as
|
|
1739
|
+
// recovered, but the maintenance check still fails once: data committed
|
|
1740
|
+
// after the last checkpoint may have been lost. The next open is clean.
|
|
1741
|
+
report.recovered = Boolean(
|
|
1742
|
+
report.initial.preserveError == null &&
|
|
1743
|
+
(report.initial.quarantined === true ||
|
|
1744
|
+
(report.initial.backup && (report.initial.recovered === true || !bad(report.current.status)))),
|
|
1745
|
+
)
|
|
1746
|
+
report.ok = !bad(report.current.status) && !bad(report.initial.status) && report.initial.preserveError == null
|
|
1747
|
+
return report
|
|
1748
|
+
}
|
|
1749
|
+
|
|
1750
|
+
/**
|
|
1751
|
+
* Verify the two FTS5 indexes against their source tables (robustness audit
|
|
1752
|
+
* 2026-11-17 P1-5). A desynchronised index makes search silently return
|
|
1753
|
+
* fewer rows than a LIKE scan; this is the explicit check that doctor and
|
|
1754
|
+
* audit --check-db should surface (O(index), so never run on every open).
|
|
1755
|
+
*
|
|
1756
|
+
* Checks per index: table present, the three sync triggers present, FTS5
|
|
1757
|
+
* 'integrity-check' (catches malformed/desynced segments), source vs index
|
|
1758
|
+
* (shadow docsize) row counts, and a deterministic rowid sample in both
|
|
1759
|
+
* directions. On a non-ok result the store also marks its FTS path unusable
|
|
1760
|
+
* (`searchTurns`/`searchSummaries` then use LIKE until a rebuild).
|
|
1761
|
+
*/
|
|
1762
|
+
verifyFtsIntegrity({ sampleSize = 100 } = {}) {
|
|
1763
|
+
this._initFtsState()
|
|
1764
|
+
const report = {
|
|
1765
|
+
ok: true,
|
|
1766
|
+
state: 'ok',
|
|
1767
|
+
tokenizer: this.ftsTokenizer,
|
|
1768
|
+
tables: {},
|
|
1769
|
+
triggers: { expected: FTS_TRIGGER_NAMES.slice(), missing: [] },
|
|
1770
|
+
checkedAt: new Date().toISOString(),
|
|
1771
|
+
errors: [],
|
|
1772
|
+
warning: null,
|
|
1773
|
+
repair: 'advisers audit --rebuild-fts',
|
|
1774
|
+
}
|
|
1775
|
+
let existingTriggers = new Set()
|
|
1776
|
+
try {
|
|
1777
|
+
existingTriggers = new Set(this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'trigger'").all().map((row) => row.name))
|
|
1778
|
+
} catch (error) {
|
|
1779
|
+
report.errors.push(`cannot list triggers: ${String(error?.message ?? error).slice(0, 200)}`)
|
|
1780
|
+
}
|
|
1781
|
+
const triggerMap = {
|
|
1782
|
+
turns_fts: ['turns_ai', 'turns_ad', 'turns_au'],
|
|
1783
|
+
summaries_fts: ['summaries_ai', 'summaries_ad', 'summaries_au'],
|
|
1784
|
+
}
|
|
1785
|
+
const sourceMap = {
|
|
1786
|
+
turns_fts: { table: 'turns' },
|
|
1787
|
+
summaries_fts: { table: 'session_summaries' },
|
|
1788
|
+
}
|
|
1789
|
+
let anyTable = false
|
|
1790
|
+
let inconsistent = false
|
|
1791
|
+
let missingTable = false
|
|
1792
|
+
for (const table of FTS_TABLE_NAMES) {
|
|
1793
|
+
const source = sourceMap[table]
|
|
1794
|
+
const info = {
|
|
1795
|
+
table,
|
|
1796
|
+
sourceTable: source.table,
|
|
1797
|
+
exists: false,
|
|
1798
|
+
triggers: { expected: triggerMap[table].slice(), missing: [] },
|
|
1799
|
+
integrityCheck: 'skipped',
|
|
1800
|
+
sourceCount: null,
|
|
1801
|
+
indexCount: null,
|
|
1802
|
+
countMismatch: false,
|
|
1803
|
+
sample: { checked: 0, missingFromIndex: [], extraInIndex: [] },
|
|
1804
|
+
}
|
|
1805
|
+
try { info.exists = Boolean(this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)) } catch (error) { report.errors.push(`${table}: cannot inspect sqlite_master: ${String(error?.message ?? error).slice(0, 200)}`) }
|
|
1806
|
+
report.tables[table] = info
|
|
1807
|
+
if (!info.exists) {
|
|
1808
|
+
missingTable = true
|
|
1809
|
+
info.triggers.missing = triggerMap[table].slice()
|
|
1810
|
+
report.errors.push(`${table}: the FTS index table is missing although schema v19 expects it`)
|
|
1811
|
+
continue
|
|
1812
|
+
}
|
|
1813
|
+
anyTable = true
|
|
1814
|
+
info.triggers.missing = triggerMap[table].filter((name) => !existingTriggers.has(name))
|
|
1815
|
+
if (info.triggers.missing.length) {
|
|
1816
|
+
inconsistent = true
|
|
1817
|
+
report.errors.push(`${table}: missing FTS sync trigger(s) ${info.triggers.missing.join(', ')}; rows written without them are not indexed`)
|
|
1818
|
+
}
|
|
1819
|
+
try {
|
|
1820
|
+
this.db.prepare(`INSERT INTO ${table}(${table}, rank) VALUES('integrity-check', 1)`).run()
|
|
1821
|
+
info.integrityCheck = 'ok'
|
|
1822
|
+
} catch (error) {
|
|
1823
|
+
info.integrityCheck = 'malformed'
|
|
1824
|
+
inconsistent = true
|
|
1825
|
+
report.errors.push(`${table}: FTS5 integrity-check failed: ${String(error?.message ?? error).slice(0, 200)}`)
|
|
1826
|
+
}
|
|
1827
|
+
try { info.sourceCount = Number(this.db.prepare(`SELECT COUNT(*) AS n FROM ${source.table}`).get()?.n ?? 0) } catch (error) { report.errors.push(`${table}: cannot count ${source.table}: ${String(error?.message ?? error).slice(0, 120)}`) }
|
|
1828
|
+
try { info.indexCount = Number(this.db.prepare(`SELECT COUNT(*) AS n FROM ${table}_docsize`).get()?.n ?? 0) } catch (error) { info.indexCount = null }
|
|
1829
|
+
if (info.sourceCount != null && info.indexCount != null && info.sourceCount !== info.indexCount) {
|
|
1830
|
+
info.countMismatch = true
|
|
1831
|
+
inconsistent = true
|
|
1832
|
+
report.errors.push(`${table}: index has ${info.indexCount} row(s) for ${info.sourceCount} source row(s)`)
|
|
1833
|
+
}
|
|
1834
|
+
if (info.sourceCount && info.sourceCount > 0) {
|
|
1835
|
+
try {
|
|
1836
|
+
const limitN = Math.max(1, Math.min(Number(sampleSize) || 0, 1000))
|
|
1837
|
+
const sampleIds = this.db.prepare(`SELECT rowid AS id FROM ${source.table} ORDER BY rowid LIMIT ?`).all(limitN).map((row) => row.id)
|
|
1838
|
+
if (sampleIds.length) {
|
|
1839
|
+
const indexed = new Set(this.db.prepare(`SELECT id FROM ${table}_docsize WHERE id IN (${sampleIds.map(() => '?').join(',')})`).all(...sampleIds).map((row) => row.id))
|
|
1840
|
+
info.sample.checked = sampleIds.length
|
|
1841
|
+
info.sample.missingFromIndex = sampleIds.filter((id) => !indexed.has(id))
|
|
1842
|
+
if (info.sample.missingFromIndex.length) {
|
|
1843
|
+
inconsistent = true
|
|
1844
|
+
report.errors.push(`${table}: sample rowid(s) ${info.sample.missingFromIndex.slice(0, 10).join(', ')} are in the source table but not in the index`)
|
|
1845
|
+
}
|
|
1846
|
+
const indexIds = this.db.prepare(`SELECT id FROM ${table}_docsize ORDER BY id LIMIT ?`).all(limitN).map((row) => row.id)
|
|
1847
|
+
if (indexIds.length) {
|
|
1848
|
+
const sourceIds = new Set(this.db.prepare(`SELECT rowid AS id FROM ${source.table} WHERE rowid IN (${indexIds.map(() => '?').join(',')})`).all(...indexIds).map((row) => row.id))
|
|
1849
|
+
info.sample.extraInIndex = indexIds.filter((id) => !sourceIds.has(id))
|
|
1850
|
+
if (info.sample.extraInIndex.length) {
|
|
1851
|
+
inconsistent = true
|
|
1852
|
+
report.errors.push(`${table}: sample rowid(s) ${info.sample.extraInIndex.slice(0, 10).join(', ')} are in the index but not in the source table`)
|
|
1853
|
+
}
|
|
1854
|
+
}
|
|
1855
|
+
}
|
|
1856
|
+
} catch (error) {
|
|
1857
|
+
report.errors.push(`${table}: sample comparison failed: ${String(error?.message ?? error).slice(0, 160)}`)
|
|
1858
|
+
}
|
|
1859
|
+
}
|
|
1860
|
+
}
|
|
1861
|
+
report.triggers.missing = FTS_TRIGGER_NAMES.filter((name) => !existingTriggers.has(name))
|
|
1862
|
+
if (!anyTable) {
|
|
1863
|
+
if (this.ftsWarning) {
|
|
1864
|
+
report.state = 'degraded'
|
|
1865
|
+
report.warning = `FTS5 is unavailable/degraded (${this.ftsWarning}); search uses LIKE only`
|
|
1866
|
+
} else {
|
|
1867
|
+
report.state = 'missing'
|
|
1868
|
+
report.ok = false
|
|
1869
|
+
report.errors.push('no FTS index tables exist although schema v19 expects them')
|
|
1870
|
+
}
|
|
1871
|
+
} else if (inconsistent || missingTable) {
|
|
1872
|
+
report.state = 'inconsistent'
|
|
1873
|
+
report.ok = false
|
|
1874
|
+
}
|
|
1875
|
+
if (!report.ok) {
|
|
1876
|
+
if (!report.warning) report.warning = `FTS index is inconsistent (${report.errors[0] ?? 'unknown reason'}); search falls back to LIKE so results stay complete; run '${report.repair}' to rebuild the index`
|
|
1877
|
+
this._ftsBroken = true
|
|
1878
|
+
this.ftsIntegrityWarning = report.warning
|
|
1879
|
+
}
|
|
1880
|
+
this.ftsIntegrityReport = report
|
|
1881
|
+
return report
|
|
1882
|
+
}
|
|
1883
|
+
|
|
1884
|
+
/** Record a detected FTS/LIKE result mismatch and warn once per store. */
|
|
1885
|
+
_markFtsInconsistent(table, ftsCount, likeCount) {
|
|
1886
|
+
this._ftsBroken = true
|
|
1887
|
+
const message = `FTS index ${table} is inconsistent (MATCH returned ${ftsCount} row(s) but LIKE returned ${likeCount}); search fell back to LIKE so results stay complete. Run 'advisers doctor --check-db' and 'advisers audit --rebuild-fts' to rebuild the index`
|
|
1888
|
+
this.ftsIntegrityWarning = message
|
|
1889
|
+
if (this._ftsWarned) return
|
|
1890
|
+
this._ftsWarned = true
|
|
1891
|
+
try { console.warn(`advisers: warning: ${message}`) } catch {}
|
|
1892
|
+
}
|
|
1893
|
+
|
|
833
1894
|
/**
|
|
834
1895
|
* Run fn() in a write transaction with bounded SQLITE_BUSY retries.
|
|
835
1896
|
* Nested calls join the outer transaction (no nested BEGIN).
|
|
836
1897
|
*/
|
|
837
1898
|
_transaction(mode, fn, { retries = OPEN_RETRIES } = {}) {
|
|
1899
|
+
if (String(mode).toUpperCase() === 'IMMEDIATE') this._assertWritable('transaction')
|
|
838
1900
|
if (this._transactionDepth > 0) return fn()
|
|
839
1901
|
let lastError
|
|
840
1902
|
for (let attempt = 0; attempt <= retries; attempt++) {
|
|
@@ -866,11 +1928,29 @@ export class SqliteStore {
|
|
|
866
1928
|
return this._transaction(mode, fn)
|
|
867
1929
|
}
|
|
868
1930
|
|
|
1931
|
+
/**
|
|
1932
|
+
* One BEGIN IMMEDIATE for a directed write: fn() runs inside, then (when
|
|
1933
|
+
* provided) the audit row is appended to the same transaction. Any throw —
|
|
1934
|
+
* business error or audit failure — rolls every row back, so a ledger write
|
|
1935
|
+
* never commits without its audit row and an audit row never claims a write
|
|
1936
|
+
* that rolled back (invariant I1). Returns { result, audit }.
|
|
1937
|
+
*/
|
|
1938
|
+
mutate(fn, audit) {
|
|
1939
|
+
this._assertWritable('mutate')
|
|
1940
|
+
if (typeof fn !== 'function') throw new TypeError('mutate requires a function')
|
|
1941
|
+
return this._transaction('IMMEDIATE', () => {
|
|
1942
|
+
const result = fn(this)
|
|
1943
|
+
const auditRow = audit === undefined || audit === null ? null : this._appendAuditRow(audit)
|
|
1944
|
+
return { result, audit: auditRow }
|
|
1945
|
+
})
|
|
1946
|
+
}
|
|
1947
|
+
|
|
869
1948
|
/**
|
|
870
1949
|
* Checkpoint the WAL so a copied/sealed database file is self-contained.
|
|
871
1950
|
* Returns busy=true when another connection prevented a full checkpoint.
|
|
872
1951
|
*/
|
|
873
1952
|
checkpoint({ mode = 'TRUNCATE', retries = OPEN_RETRIES } = {}) {
|
|
1953
|
+
this._assertWritable('checkpoint')
|
|
874
1954
|
let last = null
|
|
875
1955
|
for (let attempt = 0; attempt <= retries; attempt++) {
|
|
876
1956
|
last = this.db.prepare(`PRAGMA wal_checkpoint(${mode})`).get()
|
|
@@ -882,30 +1962,103 @@ export class SqliteStore {
|
|
|
882
1962
|
return { busy: Number(last?.busy ?? 1) !== 0, log: Number(last?.log ?? 0), checkpointed: Number(last?.checkpointed ?? 0) }
|
|
883
1963
|
}
|
|
884
1964
|
|
|
1965
|
+
/** Read the on-disk schema version before SCHEMA/migrate run (0 = new/empty). */
|
|
1966
|
+
_readSchemaVersionForBackup() {
|
|
1967
|
+
try {
|
|
1968
|
+
const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
|
|
1969
|
+
return row ? Number(row.value) : 0
|
|
1970
|
+
} catch (error) {
|
|
1971
|
+
if (/no such table/i.test(String(error?.message ?? error))) return 0
|
|
1972
|
+
throw error
|
|
1973
|
+
}
|
|
1974
|
+
}
|
|
1975
|
+
|
|
1976
|
+
/** Take the pre-migration backup while no write transaction is open. */
|
|
1977
|
+
_prepareMigrationBackup() {
|
|
1978
|
+
if (!this.path || this.path === ':memory:') return null
|
|
1979
|
+
const current = this._readSchemaVersionForBackup()
|
|
1980
|
+
if (!Number.isFinite(current) || current <= 0 || current >= SCHEMA_VERSION) return null
|
|
1981
|
+
return this.backupBeforeMigrate(current)
|
|
1982
|
+
}
|
|
1983
|
+
|
|
1984
|
+
/**
|
|
1985
|
+
* Same-directory backup of the database before a schema migration.
|
|
1986
|
+
*
|
|
1987
|
+
* P2-9 (2026-11-17 robustness audit): the old implementation copied only the
|
|
1988
|
+
* main database file. Committed transactions that still lived in the WAL
|
|
1989
|
+
* were missing from the backup (measured: backup 300 rows vs main DB 301),
|
|
1990
|
+
* so rolling back to it silently dropped data. Now the WAL is folded into
|
|
1991
|
+
* the main file with 'PRAGMA wal_checkpoint(TRUNCATE)' before the copy; if
|
|
1992
|
+
* another connection prevents the checkpoint the migration is refused
|
|
1993
|
+
* rather than proceeding with an incomplete backup.
|
|
1994
|
+
*
|
|
1995
|
+
* The copy is verified with a read-only DatabaseSync quick_check, the
|
|
1996
|
+
* schema_version it was taken at, and a row-count sample of the five tables
|
|
1997
|
+
* whose loss matters most (matters/facts/commitments/preferences/audit). A
|
|
1998
|
+
* failed verification removes the partial backup and throws (fail-closed).
|
|
1999
|
+
* The directory entry is fsynced after the copy so a crash cannot leave a
|
|
2000
|
+
* visible-but-empty backup. Returns the backup path.
|
|
2001
|
+
*/
|
|
885
2002
|
backupBeforeMigrate(current) {
|
|
886
|
-
|
|
2003
|
+
this._assertWritable('backupBeforeMigrate')
|
|
2004
|
+
if (!this.path || this.path === ':memory:') return null
|
|
2005
|
+
const checkpoint = this.checkpoint({ mode: 'TRUNCATE' })
|
|
2006
|
+
if (checkpoint.busy) {
|
|
2007
|
+
const error = new Error(`refusing to migrate without a consistent backup of ${this.path}: could not checkpoint the WAL (another connection is busy); close other advisers processes and retry`)
|
|
2008
|
+
// Wave-2 Persistence v2 contract (03-design-persistence-v2.md §5.4): stable
|
|
2009
|
+
// code so bin/ can map it to an actionable message.
|
|
2010
|
+
error.code = 'E_MIGRATE_BUSY'
|
|
2011
|
+
throw error
|
|
2012
|
+
}
|
|
2013
|
+
// Sample the main database AFTER the checkpoint (so WAL-only commits are
|
|
2014
|
+
// included) and compare it with the copy: a backup that silently dropped
|
|
2015
|
+
// committed rows must never be used as the rollback path.
|
|
2016
|
+
const expectedCounts = this._sampleTableCounts(this.db)
|
|
887
2017
|
const target = `${this.path}.before-migrate-v${current}-${Date.now()}`
|
|
2018
|
+
let backupDb = null
|
|
888
2019
|
try {
|
|
889
|
-
|
|
2020
|
+
copyFileWithRetrySync(this.path, target, { mode: 0o600 })
|
|
2021
|
+
fsyncFileSync(target)
|
|
2022
|
+
// Make the directory entry durable too: without this a crash can leave a
|
|
2023
|
+
// correctly-sized backup that is not recoverable after reboot.
|
|
2024
|
+
try { fsyncDirSync(dirname(this.path)) } catch {}
|
|
2025
|
+
backupDb = new DatabaseSync(target, { readOnly: true })
|
|
2026
|
+
const verdict = String(backupDb.prepare('PRAGMA quick_check').get()?.quick_check ?? 'unknown')
|
|
2027
|
+
if (verdict !== 'ok') throw new Error(`quick_check on the backup reported '${verdict}'`)
|
|
2028
|
+
const meta = backupDb.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
|
|
2029
|
+
if (meta && Number(meta.value) !== Number(current)) {
|
|
2030
|
+
throw new Error(`backup contains schema_version ${meta.value}, expected ${current}`)
|
|
2031
|
+
}
|
|
2032
|
+
this._verifyBackupCounts(backupDb, expectedCounts)
|
|
890
2033
|
try { chmodSync(target, 0o600) } catch {}
|
|
2034
|
+
return target
|
|
891
2035
|
} catch (error) {
|
|
892
|
-
|
|
2036
|
+
try { backupDb?.close() } catch {}
|
|
2037
|
+
backupDb = null
|
|
2038
|
+
try { rmWithRetrySync(target) } catch {}
|
|
2039
|
+
const wrapped = new Error(`refusing to migrate without a verified backup of ${this.path}: ${String(error?.message ?? error).slice(0, 300)}`)
|
|
2040
|
+
wrapped.code = 'E_MIGRATION_BACKUP'
|
|
2041
|
+
throw wrapped
|
|
2042
|
+
} finally {
|
|
2043
|
+
try { backupDb?.close() } catch {}
|
|
2044
|
+
// Opening a WAL-mode backup read-only makes SQLite create <backup>-wal/-shm;
|
|
2045
|
+
// they are verification artifacts, not part of the backup, so remove them.
|
|
2046
|
+
for (const suffix of ['-wal', '-shm']) {
|
|
2047
|
+
try { if (existsSync(target + suffix)) rmSync(target + suffix, { force: true }) } catch {}
|
|
2048
|
+
}
|
|
893
2049
|
}
|
|
894
2050
|
}
|
|
895
2051
|
|
|
896
2052
|
/**
|
|
897
|
-
*
|
|
898
|
-
*
|
|
899
|
-
*
|
|
2053
|
+
* Pre-v20 single-block idempotent migration (0.2.2 and earlier).
|
|
2054
|
+
*
|
|
2055
|
+
* Kept apart from the version-step table below: it builds every base table,
|
|
2056
|
+
* adds the columns older releases lacked, installs the v19 trigram FTS and
|
|
2057
|
+
* stamps meta.schema_version=19. The v20 step then adds the migration ledger
|
|
2058
|
+
* and the new indexes in the same outer transaction.
|
|
900
2059
|
*/
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
const current = row ? Number(row.value) : 0
|
|
904
|
-
if (!Number.isFinite(current) || current < 0) throw new Error(`invalid schema_version in ${this.path}: ${row?.value}`)
|
|
905
|
-
if (current > SCHEMA_VERSION) throw new Error(`database schema v${current} is newer than this CLI (v${SCHEMA_VERSION}); upgrade advisers before opening ${this.path}`)
|
|
906
|
-
if (current >= SCHEMA_VERSION) return
|
|
907
|
-
if (current > 0) this.backupBeforeMigrate(current)
|
|
908
|
-
try {
|
|
2060
|
+
_legacyMigrateThrough19() {
|
|
2061
|
+
{
|
|
909
2062
|
this.db.exec(`CREATE TABLE IF NOT EXISTS seen_events (
|
|
910
2063
|
link_id TEXT NOT NULL, account_id TEXT NOT NULL, dedupe_key TEXT NOT NULL,
|
|
911
2064
|
seen_at TEXT NOT NULL, PRIMARY KEY(link_id, account_id, dedupe_key)
|
|
@@ -986,16 +2139,89 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
986
2139
|
// instead of falling back to a LIKE table scan. Runs last so the source
|
|
987
2140
|
// tables (turns, session_summaries) exist for the 'rebuild' backfill.
|
|
988
2141
|
this._setupFts()
|
|
989
|
-
this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)').run('schema_version', String(
|
|
990
|
-
} catch (error) {
|
|
991
|
-
throw error
|
|
2142
|
+
this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)').run('schema_version', String(LEGACY_SCHEMA_VERSION))
|
|
992
2143
|
}
|
|
993
2144
|
}
|
|
994
2145
|
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
2146
|
+
/**
|
|
2147
|
+
* Bring an older database up to SCHEMA_VERSION.
|
|
2148
|
+
*
|
|
2149
|
+
* Runs inside the caller's write transaction (initializeSchema). Order:
|
|
2150
|
+
* 1. read the on-disk version (0 = fresh database whose meta table was just
|
|
2151
|
+
* created by SCHEMA);
|
|
2152
|
+
* 2. refuse a future schema (E_SCHEMA_NEWER, fail closed);
|
|
2153
|
+
* 3. legacy block for < v19 (idempotent base tables + FTS);
|
|
2154
|
+
* 4. every MIGRATIONS step with version > current, recording
|
|
2155
|
+
* schema_migrations(version, name, applied_at, duration_ms, backup_path);
|
|
2156
|
+
* 5. stamp meta.schema_version = SCHEMA_VERSION and the diagnostics keys.
|
|
2157
|
+
*
|
|
2158
|
+
* A failure anywhere rolls back every DDL write and the version stamp, so a
|
|
2159
|
+
* failed migration leaves the old database intact and retryable.
|
|
2160
|
+
*/
|
|
2161
|
+
migrate() {
|
|
2162
|
+
this._assertWritable('migrate')
|
|
2163
|
+
const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
|
|
2164
|
+
const current = row ? Number(row.value) : 0
|
|
2165
|
+
if (!Number.isFinite(current) || current < 0) throw new Error(`invalid schema_version in ${this.path}: ${row?.value}`)
|
|
2166
|
+
if (current > SCHEMA_VERSION) throw schemaNewerError(this.path, current)
|
|
2167
|
+
if (current >= SCHEMA_VERSION) return
|
|
2168
|
+
// initializeSchema() already took the verified backup before opening its
|
|
2169
|
+
// write transaction (a WAL checkpoint cannot run inside one); only direct
|
|
2170
|
+
// callers of migrate() fall back to taking it here.
|
|
2171
|
+
if (current > 0 && !this._migrationBackup) this._migrationBackup = this.backupBeforeMigrate(current)
|
|
2172
|
+
if (current < LEGACY_SCHEMA_VERSION) this._legacyMigrateThrough19()
|
|
2173
|
+
// A direct migrate() caller may not have run SCHEMA first; the steps assume
|
|
2174
|
+
// the migration ledger exists.
|
|
2175
|
+
this.db.exec(SCHEMA_MIGRATIONS_DDL)
|
|
2176
|
+
const from = current
|
|
2177
|
+
for (const step of MIGRATIONS) {
|
|
2178
|
+
if (step.version <= current) continue
|
|
2179
|
+
const startedAt = Date.now()
|
|
2180
|
+
this._runMigrationStep(step)
|
|
2181
|
+
this.db.prepare('INSERT OR REPLACE INTO schema_migrations(version,name,applied_at,duration_ms,backup_path) VALUES(?,?,?,?,?)')
|
|
2182
|
+
.run(step.version, step.name, new Date().toISOString(), Date.now() - startedAt, this._migrationBackup ?? null)
|
|
2183
|
+
}
|
|
2184
|
+
const migratedAt = new Date().toISOString()
|
|
2185
|
+
const setMeta = this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)')
|
|
2186
|
+
setMeta.run('schema_version', String(SCHEMA_VERSION))
|
|
2187
|
+
setMeta.run('schema_migrated_from', String(from))
|
|
2188
|
+
setMeta.run('schema_migrated_at', migratedAt)
|
|
2189
|
+
setMeta.run('schema_migrated_app', APP_VERSION)
|
|
2190
|
+
if (this._migrationBackup) setMeta.run('schema_migration_backup', this._migrationBackup)
|
|
2191
|
+
}
|
|
2192
|
+
|
|
2193
|
+
/** Run one migration step (separate method so tests can inject a failure). */
|
|
2194
|
+
_runMigrationStep(step) {
|
|
2195
|
+
step.up(this)
|
|
2196
|
+
}
|
|
2197
|
+
|
|
2198
|
+
/** Row counts for the verify-after-copy step of the migration backup. */
|
|
2199
|
+
_sampleTableCounts(db) {
|
|
2200
|
+
const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => row.name))
|
|
2201
|
+
const counts = {}
|
|
2202
|
+
for (const table of BACKUP_SAMPLE_TABLES) {
|
|
2203
|
+
if (!tables.has(table)) continue
|
|
2204
|
+
counts[table] = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n ?? 0)
|
|
2205
|
+
}
|
|
2206
|
+
return counts
|
|
2207
|
+
}
|
|
2208
|
+
|
|
2209
|
+
/** Fail-closed comparison of the backup row counts with the main database. */
|
|
2210
|
+
_verifyBackupCounts(backupDb, expected) {
|
|
2211
|
+
const actual = this._sampleTableCounts(backupDb)
|
|
2212
|
+
for (const [table, expectedCount] of Object.entries(expected)) {
|
|
2213
|
+
const actualCount = actual[table]
|
|
2214
|
+
if (actualCount !== expectedCount) {
|
|
2215
|
+
throw new Error(`backup row count mismatch for ${table}: backup has ${actualCount ?? 'no table'}, main database has ${expectedCount}`)
|
|
2216
|
+
}
|
|
2217
|
+
}
|
|
2218
|
+
}
|
|
2219
|
+
|
|
2220
|
+
upsertSession({ conversationId, matterId, title }) {
|
|
2221
|
+
this._assertWritable('upsertSession')
|
|
2222
|
+
const now = new Date().toISOString()
|
|
2223
|
+
this.db.prepare(`INSERT INTO sessions(conversation_id,matter_id,title,created_at,updated_at)
|
|
2224
|
+
VALUES(?,?,?,?,?)
|
|
999
2225
|
ON CONFLICT(conversation_id) DO UPDATE SET matter_id=excluded.matter_id, title=excluded.title, updated_at=excluded.updated_at`)
|
|
1000
2226
|
.run(conversationId, matterId, title.slice(0, 120), now, now)
|
|
1001
2227
|
}
|
|
@@ -1010,16 +2236,61 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1010
2236
|
return r ? { conversationId: r.conversation_id, matterId: r.matter_id, title: r.title, createdAt: r.created_at, updatedAt: r.updated_at } : undefined
|
|
1011
2237
|
}
|
|
1012
2238
|
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
2239
|
+
/**
|
|
2240
|
+
* Record one delivery row.
|
|
2241
|
+
*
|
|
2242
|
+
* v21 lineage (0.3.0): the optional client/project/template fields snapshot
|
|
2243
|
+
* WHO and WHICH template a delivery belonged to at generation time, so a
|
|
2244
|
+
* later matter re-link does not rewrite an already-generated receipt. When
|
|
2245
|
+
* the caller omits clientId/projectId they are filled from the matter the
|
|
2246
|
+
* delivery is filed under (the historical CLI path), and explicitly passed
|
|
2247
|
+
* ids are validated against the client/project rows. Every new argument is
|
|
2248
|
+
* optional: the pre-v21 call shape keeps working and old rows stay NULL.
|
|
2249
|
+
*/
|
|
2250
|
+
addDelivery({ matterId, conversationId, files, tool, title, validation, clientId, projectId, templateName, templateVersion, quoteNo, dataSha256 } = {}) {
|
|
2251
|
+
this._assertWritable('addDelivery')
|
|
2252
|
+
const lineage = normalizeDeliveryLineage({ clientId, projectId, templateName, templateVersion, quoteNo, dataSha256 })
|
|
2253
|
+
let resolvedClientId = lineage.clientId
|
|
2254
|
+
let resolvedProjectId = lineage.projectId
|
|
2255
|
+
if (resolvedProjectId !== null) {
|
|
2256
|
+
const project = this.getProject(resolvedProjectId)
|
|
2257
|
+
if (!project) throw entityError('E_PROJECT_NOT_FOUND', 'unknown project: ' + resolvedProjectId)
|
|
2258
|
+
if (resolvedClientId === null) resolvedClientId = project.clientId
|
|
2259
|
+
else if (project.clientId !== resolvedClientId) throw entityError('E_PROJECT_CLIENT_MISMATCH', 'project ' + resolvedProjectId + ' belongs to client ' + project.clientId)
|
|
2260
|
+
}
|
|
2261
|
+
if (resolvedClientId !== null && !this.getClient(resolvedClientId)) {
|
|
2262
|
+
throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + resolvedClientId)
|
|
2263
|
+
}
|
|
2264
|
+
if ((resolvedClientId === null || resolvedProjectId === null) && matterId) {
|
|
2265
|
+
const matter = this.getMatter(String(matterId))
|
|
2266
|
+
if (matter) {
|
|
2267
|
+
if (resolvedClientId === null) resolvedClientId = matter.clientId ?? null
|
|
2268
|
+
if (resolvedProjectId === null && (matter.clientId ?? null) === resolvedClientId) resolvedProjectId = matter.projectId ?? null
|
|
2269
|
+
}
|
|
2270
|
+
}
|
|
2271
|
+
const id = 'del_' + randomUUID().replace(/-/g, '').slice(0, 16)
|
|
2272
|
+
this.db.prepare('INSERT INTO deliveries(id,matter_id,conversation_id,files,tool,title,validation,created_at,client_id,project_id,template_name,template_version,quote_no,data_sha256) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)')
|
|
2273
|
+
.run(id, matterId, conversationId, JSON.stringify(files ?? []), tool ?? null, title ?? null, validation ?? null, new Date().toISOString(),
|
|
2274
|
+
resolvedClientId, resolvedProjectId, lineage.templateName, lineage.templateVersion, lineage.quoteNo, lineage.dataSha256)
|
|
1017
2275
|
return id
|
|
1018
2276
|
}
|
|
1019
2277
|
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
2278
|
+
/**
|
|
2279
|
+
* Newest delivery rows, optionally scoped.
|
|
2280
|
+
*
|
|
2281
|
+
* The second argument is additive: listDeliveries(limit) keeps its historical
|
|
2282
|
+
* result. clientId/projectId filter the generation-time snapshot columns
|
|
2283
|
+
* (receipt scope); matterId filters row ownership. The rowid tie-break keeps
|
|
2284
|
+
* same-millisecond rows in insertion order, as before.
|
|
2285
|
+
*/
|
|
2286
|
+
listDeliveries(limit = 20, { clientId, projectId, matterId } = {}) {
|
|
2287
|
+
const where = []
|
|
2288
|
+
const params = []
|
|
2289
|
+
if (clientId !== undefined && clientId !== null) { where.push('client_id = ?'); params.push(clientId) }
|
|
2290
|
+
if (projectId !== undefined && projectId !== null) { where.push('project_id = ?'); params.push(projectId) }
|
|
2291
|
+
if (matterId !== undefined && matterId !== null) { where.push('matter_id = ?'); params.push(matterId) }
|
|
2292
|
+
const sql = 'SELECT * FROM deliveries' + (where.length ? ' WHERE ' + where.join(' AND ') : '') + ' ORDER BY created_at DESC, rowid DESC LIMIT ?'
|
|
2293
|
+
return this.db.prepare(sql).all(...params, limit).map(mapDeliveryRow)
|
|
1023
2294
|
}
|
|
1024
2295
|
|
|
1025
2296
|
getMeta(key) {
|
|
@@ -1027,14 +2298,17 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1027
2298
|
}
|
|
1028
2299
|
|
|
1029
2300
|
setMeta(key, value) {
|
|
2301
|
+
this._assertWritable('setMeta')
|
|
1030
2302
|
this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)').run(key, String(value))
|
|
1031
2303
|
}
|
|
1032
2304
|
|
|
1033
2305
|
deleteMeta(key) {
|
|
2306
|
+
this._assertWritable('deleteMeta')
|
|
1034
2307
|
this.db.prepare('DELETE FROM meta WHERE key = ?').run(key)
|
|
1035
2308
|
}
|
|
1036
2309
|
|
|
1037
2310
|
addTaskRun({ conversationId, matterId, task, tools, artifacts, outcome }) {
|
|
2311
|
+
this._assertWritable('addTaskRun')
|
|
1038
2312
|
const id = `run_${randomUUID().replace(/-/g, '').slice(0, 16)}`
|
|
1039
2313
|
this.db.prepare('INSERT INTO task_runs(id,conversation_id,matter_id,task,tools,artifacts,outcome,created_at) VALUES(?,?,?,?,?,?,?,?)')
|
|
1040
2314
|
.run(id, conversationId, matterId ?? null, task, json(tools), json(artifacts), outcome, new Date().toISOString())
|
|
@@ -1047,6 +2321,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1047
2321
|
}
|
|
1048
2322
|
|
|
1049
2323
|
addNudge({ localDay, level, commitmentId, body }) {
|
|
2324
|
+
this._assertWritable('addNudge')
|
|
1050
2325
|
const key = `${localDay}:${level}:${commitmentId}`
|
|
1051
2326
|
const id = `nudge_${randomUUID().replace(/-/g, '').slice(0, 16)}`
|
|
1052
2327
|
try {
|
|
@@ -1059,6 +2334,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1059
2334
|
}
|
|
1060
2335
|
|
|
1061
2336
|
setNudgeOutcome(id, outcome) {
|
|
2337
|
+
this._assertWritable('setNudgeOutcome')
|
|
1062
2338
|
return Number(this.db.prepare('UPDATE nudges SET outcome = ?, outcome_at = ? WHERE id = ?').run(outcome, new Date().toISOString(), id).changes) > 0
|
|
1063
2339
|
}
|
|
1064
2340
|
|
|
@@ -1078,6 +2354,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1078
2354
|
* rows actually inserted (existing rows are left untouched).
|
|
1079
2355
|
*/
|
|
1080
2356
|
addNudges(rows) {
|
|
2357
|
+
this._assertWritable('addNudges')
|
|
1081
2358
|
if (!rows?.length) return 0
|
|
1082
2359
|
return this._transaction('IMMEDIATE', () => {
|
|
1083
2360
|
const statement = this.db.prepare('INSERT OR IGNORE INTO nudges(id,at,local_day,level,commitment_id,dedupe_key,body) VALUES(?,?,?,?,?,?,?)')
|
|
@@ -1149,6 +2426,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1149
2426
|
|
|
1150
2427
|
/** P0-2: delete a batch of meta keys in one transaction. */
|
|
1151
2428
|
deleteMetaKeys(keys) {
|
|
2429
|
+
this._assertWritable('deleteMetaKeys')
|
|
1152
2430
|
if (!keys?.length) return 0
|
|
1153
2431
|
return this._transaction('IMMEDIATE', () => {
|
|
1154
2432
|
const statement = this.db.prepare('DELETE FROM meta WHERE key = ?')
|
|
@@ -1162,7 +2440,16 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1162
2440
|
return this.db.prepare('SELECT * FROM nudges ORDER BY at DESC LIMIT ?').all(limit)
|
|
1163
2441
|
}
|
|
1164
2442
|
|
|
1165
|
-
|
|
2443
|
+
/**
|
|
2444
|
+
* Delete the non-ledger rows of one matter (sessions/turns/summaries/runs/
|
|
2445
|
+
* nudges/candidates/deliveries). The VACUUM is a maintenance operation: it
|
|
2446
|
+
* cannot run inside a transaction, so when this is called from inside
|
|
2447
|
+
* mutate()/transaction() it is skipped and the caller runs it after COMMIT
|
|
2448
|
+
* (pass { vacuum: false } explicitly to force that). Standalone calls keep
|
|
2449
|
+
* the historical checkpoint+VACUUM behaviour.
|
|
2450
|
+
*/
|
|
2451
|
+
purgeMatterData(matterId, { vacuum = true } = {}) {
|
|
2452
|
+
this._assertWritable('purgeMatterData')
|
|
1166
2453
|
const conversations = this.db.prepare('SELECT conversation_id FROM sessions WHERE matter_id = ?').all(matterId).map((r) => r.conversation_id)
|
|
1167
2454
|
let turns = 0
|
|
1168
2455
|
let summaries = 0
|
|
@@ -1182,11 +2469,14 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1182
2469
|
this.db.prepare('DELETE FROM research_runs WHERE matter_id = ?').run(matterId)
|
|
1183
2470
|
const sessions = this.db.prepare('DELETE FROM sessions WHERE matter_id = ?').run(matterId).changes
|
|
1184
2471
|
const deliveries = this.db.prepare('DELETE FROM deliveries WHERE matter_id = ?').run(matterId).changes
|
|
1185
|
-
|
|
2472
|
+
if (vacuum && this._transactionDepth === 0) {
|
|
2473
|
+
try { this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); this.db.exec('VACUUM') } catch {}
|
|
2474
|
+
}
|
|
1186
2475
|
return { sessions: Number(sessions), deliveries: Number(deliveries), turns, summaries, runs, nudges, candidates }
|
|
1187
2476
|
}
|
|
1188
2477
|
|
|
1189
2478
|
addTurn({ conversationId, role, content }) {
|
|
2479
|
+
this._assertWritable('addTurn')
|
|
1190
2480
|
const seq = (this.db.prepare('SELECT MAX(seq) AS n FROM turns WHERE conversation_id = ?').get(conversationId)?.n ?? 0) + 1
|
|
1191
2481
|
const id = `turn_${randomUUID().replace(/-/g, '').slice(0, 16)}`
|
|
1192
2482
|
this.db.prepare('INSERT INTO turns(id,conversation_id,seq,role,content,created_at) VALUES(?,?,?,?,?,?)')
|
|
@@ -1200,6 +2490,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1200
2490
|
}
|
|
1201
2491
|
|
|
1202
2492
|
upsertCalendarEvent({ uid, summary, startsAt, endsAt, allDay = false, tzid, location, rrule, source }) {
|
|
2493
|
+
this._assertWritable('upsertCalendarEvent')
|
|
1203
2494
|
this.db.prepare(`INSERT INTO calendar_events(uid,summary,starts_at,ends_at,all_day,tzid,location,rrule,source,imported_at)
|
|
1204
2495
|
VALUES(?,?,?,?,?,?,?,?,?,?)
|
|
1205
2496
|
ON CONFLICT(uid) DO UPDATE SET summary=excluded.summary, starts_at=excluded.starts_at, ends_at=excluded.ends_at,
|
|
@@ -1221,6 +2512,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1221
2512
|
}
|
|
1222
2513
|
|
|
1223
2514
|
permitReplayStore() {
|
|
2515
|
+
this._assertWritable('permitReplayStore')
|
|
1224
2516
|
return {
|
|
1225
2517
|
has: (permitId) => Boolean(this.db.prepare('SELECT 1 FROM permit_consumed WHERE permit_id = ?').get(permitId)),
|
|
1226
2518
|
claim: (permitId, expiresAt) => Number(this.db.prepare('INSERT OR IGNORE INTO permit_consumed(permit_id,expires_at,consumed_at) VALUES(?,?,?)').run(permitId, expiresAt, new Date().toISOString()).changes) === 1,
|
|
@@ -1229,6 +2521,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1229
2521
|
}
|
|
1230
2522
|
|
|
1231
2523
|
addResearchRun({ matterId, query, answer, sources, usage, stopReason }) {
|
|
2524
|
+
this._assertWritable('addResearchRun')
|
|
1232
2525
|
const id = `rr_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
|
|
1233
2526
|
this.db.prepare('INSERT INTO research_runs(id,matter_id,query,answer,sources,usage,stop_reason,created_at) VALUES(?,?,?,?,?,?,?,?)')
|
|
1234
2527
|
.run(id, matterId ?? null, query, answer, JSON.stringify(sources ?? []), usage ? JSON.stringify(usage) : null, stopReason ?? null, new Date().toISOString())
|
|
@@ -1240,6 +2533,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1240
2533
|
}
|
|
1241
2534
|
|
|
1242
2535
|
addModelCall({ conversationId, matterId, turnId, task, model, effort, thinking, usage, durationMs, finishReason, status = 'ok', code, attempts = 1 }) {
|
|
2536
|
+
this._assertWritable('addModelCall')
|
|
1243
2537
|
const id = `mc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
|
|
1244
2538
|
this.db.prepare(`INSERT INTO model_calls(id,conversation_id,matter_id,turn_id,task,model,effort,thinking,status,code,attempts,prompt_tokens,completion_tokens,reasoning_tokens,cached_tokens,total_tokens,duration_ms,finish_reason,created_at)
|
|
1245
2539
|
VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(
|
|
@@ -1282,6 +2576,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1282
2576
|
}
|
|
1283
2577
|
|
|
1284
2578
|
proposeCandidate({ kind, payload, evidence }) {
|
|
2579
|
+
this._assertWritable('proposeCandidate')
|
|
1285
2580
|
const id = `cand_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
|
|
1286
2581
|
const now = new Date().toISOString()
|
|
1287
2582
|
this.db.prepare('INSERT INTO memory_candidates(id,kind,payload,evidence,status,created_at) VALUES(?,?,?,?,?,?)')
|
|
@@ -1300,6 +2595,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1300
2595
|
}
|
|
1301
2596
|
|
|
1302
2597
|
reviewCandidate(id, status, reason) {
|
|
2598
|
+
this._assertWritable('reviewCandidate')
|
|
1303
2599
|
this.db.prepare('UPDATE memory_candidates SET status = ?, reviewed_at = ?, reject_reason = ? WHERE id = ?')
|
|
1304
2600
|
.run(status, new Date().toISOString(), reason ?? null, id)
|
|
1305
2601
|
return this.getCandidate(id)
|
|
@@ -1352,16 +2648,39 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1352
2648
|
const join = matterId ? ' JOIN sessions s ON s.conversation_id = t.conversation_id' : ''
|
|
1353
2649
|
const where = clauses.length ? ` AND ${clauses.join(' AND ')}` : ''
|
|
1354
2650
|
const map = (r) => ({ id: r.id, conversationId: r.conversation_id, seq: r.seq, role: r.role, content: r.content, createdAt: r.created_at })
|
|
1355
|
-
|
|
2651
|
+
const likeRows = () => {
|
|
2652
|
+
const rows = this.db.prepare(`SELECT t.* FROM turns t${join} WHERE t.content LIKE ?${where} ORDER BY t.seq DESC LIMIT ?`).all(`%${q}%`, ...filterArgs, limit)
|
|
2653
|
+
return rows.reverse().map(map)
|
|
2654
|
+
}
|
|
2655
|
+
let ftsRows = null
|
|
2656
|
+
if (this.ftsTokenizer && this._ftsTables.has('turns_fts') && !this._ftsBroken && q.length >= FTS_TRIGRAM_MIN_QUERY) {
|
|
1356
2657
|
try {
|
|
1357
|
-
|
|
1358
|
-
if (rows.length) return rows.map(map)
|
|
2658
|
+
ftsRows = this.db.prepare(`SELECT t.* FROM turns_fts f JOIN turns t ON t.rowid = f.rowid${join} WHERE turns_fts MATCH ?${where} ORDER BY rank LIMIT ?`).all(q, ...filterArgs, limit)
|
|
1359
2659
|
} catch {
|
|
1360
2660
|
// Malformed or special FTS query: use the LIKE scan below.
|
|
2661
|
+
ftsRows = null
|
|
1361
2662
|
}
|
|
1362
2663
|
}
|
|
1363
|
-
|
|
1364
|
-
|
|
2664
|
+
// P1-5: a full FTS page is returned ranked, as before. A short page is
|
|
2665
|
+
// cross-checked with a LIKE scan; if LIKE finds more rows the index is
|
|
2666
|
+
// incomplete (or the MATCH query was narrower) and the complete, seq-ordered
|
|
2667
|
+
// LIKE rows are returned with one warning instead of silently losing hits.
|
|
2668
|
+
if (ftsRows && ftsRows.length >= limit) return ftsRows.map(map)
|
|
2669
|
+
const rows = likeRows()
|
|
2670
|
+
if (ftsRows && ftsRows.length) {
|
|
2671
|
+
if (rows.length > ftsRows.length) {
|
|
2672
|
+
this._markFtsInconsistent('turns_fts', ftsRows.length, rows.length)
|
|
2673
|
+
return rows
|
|
2674
|
+
}
|
|
2675
|
+
return ftsRows.map(map)
|
|
2676
|
+
}
|
|
2677
|
+
if (ftsRows && ftsRows.length === 0 && rows.length > 0 && this.ftsTokenizer === 'trigram') {
|
|
2678
|
+
// Trigram indexes every 3+ character substring, so a 0-hit MATCH that a
|
|
2679
|
+
// LIKE scan contradicts means the index is missing rows (not a tokenizer
|
|
2680
|
+
// limitation); warn instead of quietly returning the LIKE rows.
|
|
2681
|
+
this._markFtsInconsistent('turns_fts', 0, rows.length)
|
|
2682
|
+
}
|
|
2683
|
+
return rows
|
|
1365
2684
|
}
|
|
1366
2685
|
|
|
1367
2686
|
/**
|
|
@@ -1375,16 +2694,29 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1375
2694
|
const where = conversationId ? ' AND s.conversation_id = ?' : ''
|
|
1376
2695
|
const filterArgs = conversationId ? [conversationId] : []
|
|
1377
2696
|
const map = (r) => ({ conversationId: r.conversation_id, summary: r.summary, throughSeq: r.through_seq, updatedAt: r.updated_at })
|
|
1378
|
-
|
|
2697
|
+
const likeRows = () => this.db.prepare(`SELECT s.* FROM session_summaries s WHERE s.summary LIKE ?${where} ORDER BY s.updated_at DESC LIMIT ?`).all(`%${q}%`, ...filterArgs, limit).map(map)
|
|
2698
|
+
let ftsRows = null
|
|
2699
|
+
if (this.ftsTokenizer && this._ftsTables.has('summaries_fts') && !this._ftsBroken && q.length >= FTS_TRIGRAM_MIN_QUERY) {
|
|
1379
2700
|
try {
|
|
1380
|
-
|
|
1381
|
-
if (rows.length) return rows.map(map)
|
|
2701
|
+
ftsRows = this.db.prepare(`SELECT s.* FROM summaries_fts f JOIN session_summaries s ON s.rowid = f.rowid WHERE summaries_fts MATCH ?${where} ORDER BY rank LIMIT ?`).all(q, ...filterArgs, limit)
|
|
1382
2702
|
} catch {
|
|
1383
2703
|
// Malformed or special FTS query: use the LIKE scan below.
|
|
2704
|
+
ftsRows = null
|
|
2705
|
+
}
|
|
2706
|
+
}
|
|
2707
|
+
if (ftsRows && ftsRows.length >= limit) return ftsRows.map(map)
|
|
2708
|
+
const rows = likeRows()
|
|
2709
|
+
if (ftsRows && ftsRows.length) {
|
|
2710
|
+
if (rows.length > ftsRows.length) {
|
|
2711
|
+
this._markFtsInconsistent('summaries_fts', ftsRows.length, rows.length)
|
|
2712
|
+
return rows
|
|
1384
2713
|
}
|
|
2714
|
+
return ftsRows.map(map)
|
|
2715
|
+
}
|
|
2716
|
+
if (ftsRows && ftsRows.length === 0 && rows.length > 0 && this.ftsTokenizer === 'trigram') {
|
|
2717
|
+
this._markFtsInconsistent('summaries_fts', 0, rows.length)
|
|
1385
2718
|
}
|
|
1386
|
-
|
|
1387
|
-
return rows.map(map)
|
|
2719
|
+
return rows
|
|
1388
2720
|
}
|
|
1389
2721
|
|
|
1390
2722
|
getSessionSummary(conversationId) {
|
|
@@ -1393,6 +2725,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1393
2725
|
}
|
|
1394
2726
|
|
|
1395
2727
|
upsertSessionSummary({ conversationId, summary, throughSeq, pins }) {
|
|
2728
|
+
this._assertWritable('upsertSessionSummary')
|
|
1396
2729
|
const max = this.db.prepare('SELECT MAX(version) AS v FROM summary_versions WHERE conversation_id = ?').get(conversationId)?.v ?? 0
|
|
1397
2730
|
const version = max + 1
|
|
1398
2731
|
const at = new Date().toISOString()
|
|
@@ -1419,10 +2752,12 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1419
2752
|
* can never both chain onto the same predecessor (audit fork, P0-3).
|
|
1420
2753
|
*/
|
|
1421
2754
|
appendAudit({ actor, action, allowed, reason }) {
|
|
2755
|
+
this._assertWritable('appendAudit')
|
|
1422
2756
|
return this._transaction('IMMEDIATE', () => this._appendAuditRow({ actor, action, allowed, reason }))
|
|
1423
2757
|
}
|
|
1424
2758
|
|
|
1425
2759
|
_appendAuditRow({ actor, action, allowed, reason }) {
|
|
2760
|
+
this._assertWritable('appendAudit')
|
|
1426
2761
|
const last = this.db.prepare('SELECT hash FROM audit ORDER BY seq DESC LIMIT 1').get()
|
|
1427
2762
|
const prev = last?.hash ?? ''
|
|
1428
2763
|
const at = new Date().toISOString()
|
|
@@ -1461,11 +2796,13 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1461
2796
|
}
|
|
1462
2797
|
|
|
1463
2798
|
markSeen(linkId, accountId, dedupeKey) {
|
|
2799
|
+
this._assertWritable('markSeen')
|
|
1464
2800
|
this.db.prepare('INSERT OR REPLACE INTO seen_events VALUES(?,?,?,?)')
|
|
1465
2801
|
.run(linkId, accountId, dedupeKey, new Date().toISOString())
|
|
1466
2802
|
}
|
|
1467
2803
|
|
|
1468
2804
|
pruneSeen(ttlDays = 7) {
|
|
2805
|
+
this._assertWritable('pruneSeen')
|
|
1469
2806
|
const cutoff = new Date(Date.now() - ttlDays * 86_400_000).toISOString()
|
|
1470
2807
|
this.db.prepare('DELETE FROM seen_events WHERE seen_at < ?').run(cutoff)
|
|
1471
2808
|
}
|
|
@@ -1483,6 +2820,735 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1483
2820
|
}
|
|
1484
2821
|
}
|
|
1485
2822
|
|
|
2823
|
+
// -------------------------------------------------------------------------
|
|
2824
|
+
// Directed entity reads/writes (0.2.3 incremental write path).
|
|
2825
|
+
//
|
|
2826
|
+
// Every insert*/update* must run inside mutate()/transaction() (otherwise
|
|
2827
|
+
// E_TX_REQUIRED: a ledger row must never commit outside the transaction that
|
|
2828
|
+
// carries its audit row), and produces exactly the bytes _saveRows() would
|
|
2829
|
+
// (shared ENTITY_SPECS codecs). update* writes only the columns a patch
|
|
2830
|
+
// explicitly names; an unknown field is an error so a typo cannot silently
|
|
2831
|
+
// write nothing. get*/find* are read methods usable on read-only stores.
|
|
2832
|
+
// -------------------------------------------------------------------------
|
|
2833
|
+
|
|
2834
|
+
_getEntity(kind, id) {
|
|
2835
|
+
const spec = ENTITY_SPECS[kind]
|
|
2836
|
+
if (!spec) throw new Error(`unknown entity: ${kind}`)
|
|
2837
|
+
const row = this.db.prepare(`SELECT * FROM ${spec.table} WHERE ${spec.key} = ?`).get(id)
|
|
2838
|
+
return row ? spec.map(row) : undefined
|
|
2839
|
+
}
|
|
2840
|
+
|
|
2841
|
+
getMatter(id) { return this._getEntity('matters', id) }
|
|
2842
|
+
getFact(id) { return this._getEntity('facts', id) }
|
|
2843
|
+
getCommitment(id) { return this._getEntity('commitments', id) }
|
|
2844
|
+
getPreference(id) { return this._getEntity('preferences', id) }
|
|
2845
|
+
|
|
2846
|
+
_insertEntity(operation, kind, entity) {
|
|
2847
|
+
this._assertInWriteTransaction(operation)
|
|
2848
|
+
const spec = ENTITY_SPECS[kind]
|
|
2849
|
+
if (!spec) throw new Error(`unknown entity: ${kind}`)
|
|
2850
|
+
const fields = Object.keys(spec.columns)
|
|
2851
|
+
const columns = fields.map((field) => spec.columns[field][0])
|
|
2852
|
+
const values = fields.map((field) => encodeEntityValue(spec.columns[field][1], entity?.[field]))
|
|
2853
|
+
this.db.prepare(`INSERT INTO ${spec.table}(${columns.join(',')}) VALUES(${fields.map(() => '?').join(',')})`).run(...values)
|
|
2854
|
+
return entity
|
|
2855
|
+
}
|
|
2856
|
+
|
|
2857
|
+
insertMatter(row) { return this._insertEntity('insertMatter', 'matters', row) }
|
|
2858
|
+
insertFact(row) { return this._insertEntity('insertFact', 'facts', row) }
|
|
2859
|
+
insertCommitment(row) { return this._insertEntity('insertCommitment', 'commitments', row) }
|
|
2860
|
+
insertPreference(row) { return this._insertEntity('insertPreference', 'preferences', row) }
|
|
2861
|
+
|
|
2862
|
+
_updateEntity(operation, kind, id, patch) {
|
|
2863
|
+
this._assertInWriteTransaction(operation)
|
|
2864
|
+
const spec = ENTITY_SPECS[kind]
|
|
2865
|
+
if (!spec) throw new Error(`unknown entity: ${kind}`)
|
|
2866
|
+
const assignments = []
|
|
2867
|
+
const values = []
|
|
2868
|
+
for (const field of Object.keys(patch ?? {})) {
|
|
2869
|
+
const column = spec.columns[field]
|
|
2870
|
+
if (!column) throw new Error(`unknown ${kind} field: ${field}`)
|
|
2871
|
+
const value = patch[field]
|
|
2872
|
+
if (value === undefined) continue
|
|
2873
|
+
assignments.push(`${column[0]} = ?`)
|
|
2874
|
+
values.push(encodeEntityValue(column[1], value))
|
|
2875
|
+
}
|
|
2876
|
+
if (assignments.length) {
|
|
2877
|
+
this.db.prepare(`UPDATE ${spec.table} SET ${assignments.join(', ')} WHERE ${spec.key} = ?`).run(...values, id)
|
|
2878
|
+
}
|
|
2879
|
+
return this._getEntity(kind, id)
|
|
2880
|
+
}
|
|
2881
|
+
|
|
2882
|
+
updateMatter(id, patch) { return this._updateEntity('updateMatter', 'matters', id, patch) }
|
|
2883
|
+
updateFact(id, patch) { return this._updateEntity('updateFact', 'facts', id, patch) }
|
|
2884
|
+
updateCommitment(id, patch) { return this._updateEntity('updateCommitment', 'commitments', id, patch) }
|
|
2885
|
+
updatePreference(id, patch) { return this._updateEntity('updatePreference', 'preferences', id, patch) }
|
|
2886
|
+
|
|
2887
|
+
/**
|
|
2888
|
+
* The confirmed, unexpired fact for one identity (remember/supersede path).
|
|
2889
|
+
* predicate 'said' never matches: conversation echoes do not supersede each
|
|
2890
|
+
* other (same rule as core Ledger.remember). Uses idx_facts_identity. The
|
|
2891
|
+
* `IS ?` comparison treats a missing matterId like SQLite's IS NULL.
|
|
2892
|
+
*/
|
|
2893
|
+
findFactCurrent({ subject, predicate, matterId } = {}) {
|
|
2894
|
+
if (predicate === 'said') return undefined
|
|
2895
|
+
const row = this.db.prepare(`
|
|
2896
|
+
SELECT * FROM facts
|
|
2897
|
+
WHERE status = 'confirmed' AND expired_at IS NULL AND subject = ? AND predicate = ? AND (matter_id IS ?)
|
|
2898
|
+
ORDER BY rowid LIMIT 1
|
|
2899
|
+
`).get(subject, predicate, matterId ?? null)
|
|
2900
|
+
return row ? mapFactRow(row) : undefined
|
|
2901
|
+
}
|
|
2902
|
+
|
|
2903
|
+
/** First non-deprecated preference with this exact statement (correct/learn). */
|
|
2904
|
+
findPreferenceByStatement(statement) {
|
|
2905
|
+
const row = this.db.prepare("SELECT * FROM preferences WHERE statement = ? AND status <> 'deprecated' ORDER BY rowid LIMIT 1").get(statement)
|
|
2906
|
+
return row ? mapPreferenceRow(row) : undefined
|
|
2907
|
+
}
|
|
2908
|
+
|
|
2909
|
+
/** First active matter by insertion order (commit add / memory accept default). */
|
|
2910
|
+
firstActiveMatter() {
|
|
2911
|
+
const row = this.db.prepare("SELECT * FROM matters WHERE status = 'active' ORDER BY rowid LIMIT 1").get()
|
|
2912
|
+
return row ? mapMatterRow(row) : undefined
|
|
2913
|
+
}
|
|
2914
|
+
|
|
2915
|
+
/**
|
|
2916
|
+
* Persist one tick() batch atomically (no audit row, matching the historical
|
|
2917
|
+
* tick behaviour): nudge inserts, snooze wake-ups and the snooze meta
|
|
2918
|
+
* cleanup either all commit or all roll back, so a nudge can never be
|
|
2919
|
+
* recorded while its wake-up is lost. The conditional UPDATE keeps a
|
|
2920
|
+
* concurrent state change (e.g. the commitment was completed meanwhile)
|
|
2921
|
+
* authoritative. Returns { nudges, woke, metaDeleted }.
|
|
2922
|
+
*/
|
|
2923
|
+
applyTick({ nudgeRows = [], wakeIds = [], snoozeKeys = [] } = {}) {
|
|
2924
|
+
this._assertWritable('applyTick')
|
|
2925
|
+
return this._transaction('IMMEDIATE', () => {
|
|
2926
|
+
const now = new Date().toISOString()
|
|
2927
|
+
let nudges = 0
|
|
2928
|
+
if (nudgeRows.length) {
|
|
2929
|
+
const insert = this.db.prepare('INSERT OR IGNORE INTO nudges(id,at,local_day,level,commitment_id,dedupe_key,body) VALUES(?,?,?,?,?,?,?)')
|
|
2930
|
+
for (const row of nudgeRows) {
|
|
2931
|
+
const dedupeKey = `${row.localDay}:${row.level}:${row.commitmentId}`
|
|
2932
|
+
const id = `nudge_${randomUUID().replace(/-/g, '').slice(0, 16)}`
|
|
2933
|
+
nudges += Number(insert.run(id, row.at ?? now, row.localDay, row.level, row.commitmentId, dedupeKey, row.body).changes)
|
|
2934
|
+
}
|
|
2935
|
+
}
|
|
2936
|
+
let woke = 0
|
|
2937
|
+
if (wakeIds.length) {
|
|
2938
|
+
const wake = this.db.prepare("UPDATE commitments SET status = 'open' WHERE id = ? AND status = 'snoozed'")
|
|
2939
|
+
for (const id of wakeIds) woke += Number(wake.run(id).changes)
|
|
2940
|
+
}
|
|
2941
|
+
let metaDeleted = 0
|
|
2942
|
+
if (snoozeKeys.length) {
|
|
2943
|
+
const del = this.db.prepare('DELETE FROM meta WHERE key = ?')
|
|
2944
|
+
for (const key of snoozeKeys) metaDeleted += Number(del.run(key).changes)
|
|
2945
|
+
}
|
|
2946
|
+
return { nudges, woke, metaDeleted }
|
|
2947
|
+
})
|
|
2948
|
+
}
|
|
2949
|
+
// -------------------------------------------------------------------------
|
|
2950
|
+
// Customer / project entities (schema v21, 0.3.0).
|
|
2951
|
+
//
|
|
2952
|
+
// clients/projects/client_notes are SQLite-only rows: they never enter the
|
|
2953
|
+
// wire LedgerSnapshot, so they are written with directed INSERT/UPDATE
|
|
2954
|
+
// statements (a caller that needs an audit row wraps them in mutate(fn,
|
|
2955
|
+
// audit), exactly like the other directed writes) and read back through the
|
|
2956
|
+
// CRUD methods below. A matter keeps the ownership (client_id/project_id) as
|
|
2957
|
+
// the single source of truth; the client timeline is derived from the rows
|
|
2958
|
+
// clientTimelineSources() returns, and there is no event table and no stored
|
|
2959
|
+
// counter that could disagree with them. Nothing is hard-deleted: archiving
|
|
2960
|
+
// sets status='archived' + deleted_at, so past work stays answerable.
|
|
2961
|
+
// -------------------------------------------------------------------------
|
|
2962
|
+
|
|
2963
|
+
/** A live (active, non-deleted) client row for a write, or a stable E_*. */
|
|
2964
|
+
_clientForWrite(clientId, operation = 'client') {
|
|
2965
|
+
const id = typeof clientId === 'string' ? clientId.trim() : ''
|
|
2966
|
+
const row = id ? this.db.prepare('SELECT * FROM clients WHERE id = ?').get(id) : undefined
|
|
2967
|
+
if (!row) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(clientId), 'advisers client add "<name>"')
|
|
2968
|
+
if (row.deleted_at != null || row.status !== 'active') {
|
|
2969
|
+
throw entityError('E_CLIENT_ARCHIVED', 'client is archived: ' + row.id + ' (' + operation + ')', 'advisers client ls')
|
|
2970
|
+
}
|
|
2971
|
+
return row
|
|
2972
|
+
}
|
|
2973
|
+
|
|
2974
|
+
/** Active client identity keys (name + aliases) other than exceptId. */
|
|
2975
|
+
_activeClientIdentities(exceptId = null) {
|
|
2976
|
+
const rows = this.db.prepare("SELECT id, name, aliases FROM clients WHERE status = 'active' AND deleted_at IS NULL").all()
|
|
2977
|
+
const result = []
|
|
2978
|
+
for (const row of rows) {
|
|
2979
|
+
if (exceptId != null && row.id === exceptId) continue
|
|
2980
|
+
const norms = new Map()
|
|
2981
|
+
norms.set(normalizeClientName(row.name), 'name')
|
|
2982
|
+
for (const alias of parse(row.aliases)) {
|
|
2983
|
+
if (typeof alias !== 'string') continue
|
|
2984
|
+
const norm = normalizeClientName(alias)
|
|
2985
|
+
if (norm && !norms.has(norm)) norms.set(norm, 'alias')
|
|
2986
|
+
}
|
|
2987
|
+
result.push({ id: row.id, name: row.name, norms: norms })
|
|
2988
|
+
}
|
|
2989
|
+
return result
|
|
2990
|
+
}
|
|
2991
|
+
|
|
2992
|
+
/**
|
|
2993
|
+
* Refuse a client name/alias that another live client already owns. The
|
|
2994
|
+
* partial unique index enforces the name half even under a racing writer;
|
|
2995
|
+
* aliases are checked here because they live inside a JSON column.
|
|
2996
|
+
*/
|
|
2997
|
+
_assertClientIdentityFree({ nameNorm, aliases = [] }, exceptId = null) {
|
|
2998
|
+
const identities = this._activeClientIdentities(exceptId)
|
|
2999
|
+
for (const identity of identities) {
|
|
3000
|
+
if (identity.norms.has(nameNorm)) {
|
|
3001
|
+
throw entityError('E_CLIENT_DUPLICATE', 'an active client named ' + identity.name + ' already exists (' + identity.id + ')', 'advisers client alias add ' + identity.id + ' <alias>')
|
|
3002
|
+
}
|
|
3003
|
+
}
|
|
3004
|
+
for (const alias of aliases) {
|
|
3005
|
+
const norm = normalizeClientName(alias)
|
|
3006
|
+
for (const identity of identities) {
|
|
3007
|
+
if (identity.norms.has(norm)) {
|
|
3008
|
+
throw entityError('E_CLIENT_ALIAS_CONFLICT', 'alias ' + alias + ' is already used by ' + identity.name + ' (' + identity.id + ')', 'advisers client alias add ' + identity.id + ' <alias>')
|
|
3009
|
+
}
|
|
3010
|
+
}
|
|
3011
|
+
}
|
|
3012
|
+
}
|
|
3013
|
+
|
|
3014
|
+
/** Create a client. Same-name active client -> E_CLIENT_DUPLICATE. */
|
|
3015
|
+
addClient({ name, aliases, tags, secrecyDefault, notes, status, id } = {}) {
|
|
3016
|
+
this._assertWritable('addClient')
|
|
3017
|
+
const displayName = validateDisplayName('client', name)
|
|
3018
|
+
const nameNorm = normalizeClientName(displayName)
|
|
3019
|
+
const aliasList = validateStringList('client', 'aliases', aliases)
|
|
3020
|
+
const tagList = validateStringList('client', 'tags', tags, { max: 20, itemMax: 40 })
|
|
3021
|
+
const secrecy = validateSecrecy(secrecyDefault)
|
|
3022
|
+
const clientStatus = validateEntityStatus('client', status)
|
|
3023
|
+
const clientId = id === undefined || id === null ? 'cl_' + randomUUID().replace(/-/g, '').slice(0, 16) : String(id).trim()
|
|
3024
|
+
if (!clientId) throw entityError('E_CLIENT_INVALID', 'client id must not be empty')
|
|
3025
|
+
if (this.getClient(clientId)) throw entityError('E_CLIENT_DUPLICATE', 'client id already exists: ' + clientId)
|
|
3026
|
+
if (clientStatus === 'active') this._assertClientIdentityFree({ nameNorm, aliases: aliasList })
|
|
3027
|
+
const now = new Date().toISOString()
|
|
3028
|
+
try {
|
|
3029
|
+
this.db.prepare('INSERT INTO clients(id,name,name_norm,aliases,status,tags,secrecy_default,notes,created_at,updated_at,deleted_at) VALUES(?,?,?,?,?,?,?,?,?,?,?)')
|
|
3030
|
+
.run(clientId, displayName, nameNorm, json(aliasList), clientStatus, json(tagList), secrecy, normalizeOptionalText('client', 'notes', notes, 4000), now, now, clientStatus === 'archived' ? now : null)
|
|
3031
|
+
} catch (error) {
|
|
3032
|
+
if (/UNIQUE constraint failed/i.test(String(error?.message ?? error))) {
|
|
3033
|
+
throw entityError('E_CLIENT_DUPLICATE', 'an active client with this name already exists', 'advisers client ls')
|
|
3034
|
+
}
|
|
3035
|
+
throw error
|
|
3036
|
+
}
|
|
3037
|
+
return this.getClient(clientId)
|
|
3038
|
+
}
|
|
3039
|
+
|
|
3040
|
+
/** One client by id (archived included; undefined when absent). */
|
|
3041
|
+
getClient(id) {
|
|
3042
|
+
const row = this.db.prepare('SELECT * FROM clients WHERE id = ?').get(String(id))
|
|
3043
|
+
return row ? mapClientRow(row) : undefined
|
|
3044
|
+
}
|
|
3045
|
+
|
|
3046
|
+
/** First live client whose name or alias normalises to the given name. */
|
|
3047
|
+
findClientByName(name) {
|
|
3048
|
+
const nameNorm = normalizeClientName(validateDisplayName('client', name))
|
|
3049
|
+
const rows = this.db.prepare("SELECT * FROM clients WHERE status = 'active' AND deleted_at IS NULL ORDER BY created_at, id").all()
|
|
3050
|
+
for (const row of rows) {
|
|
3051
|
+
if (row.name_norm === nameNorm) return mapClientRow(row)
|
|
3052
|
+
for (const alias of parse(row.aliases)) {
|
|
3053
|
+
if (typeof alias === 'string' && normalizeClientName(alias) === nameNorm) return mapClientRow(row)
|
|
3054
|
+
}
|
|
3055
|
+
}
|
|
3056
|
+
return undefined
|
|
3057
|
+
}
|
|
3058
|
+
|
|
3059
|
+
/**
|
|
3060
|
+
* List clients. Default is the live (active, non-deleted) list; pass
|
|
3061
|
+
* status:'archived' with includeDeleted:true for tombstones, status:'all'
|
|
3062
|
+
* for every status. Ordered by name_norm then id (deterministic).
|
|
3063
|
+
*/
|
|
3064
|
+
listClients({ status = 'active', includeDeleted = false, limit = 100 } = {}) {
|
|
3065
|
+
const where = []
|
|
3066
|
+
const params = []
|
|
3067
|
+
if (includeDeleted !== true) where.push('deleted_at IS NULL')
|
|
3068
|
+
if (status !== 'all') {
|
|
3069
|
+
const wanted = validateEntityStatus('client', status)
|
|
3070
|
+
where.push('status = ?')
|
|
3071
|
+
params.push(wanted)
|
|
3072
|
+
}
|
|
3073
|
+
const sql = 'SELECT * FROM clients' + (where.length ? ' WHERE ' + where.join(' AND ') : '') + ' ORDER BY name_norm ASC, id ASC LIMIT ?'
|
|
3074
|
+
return this.db.prepare(sql).all(...params, normalizeRowLimit(limit, { def: 100, max: 1000 })).map(mapClientRow)
|
|
3075
|
+
}
|
|
3076
|
+
|
|
3077
|
+
/**
|
|
3078
|
+
* Update the mutable client fields. Renames re-check the active identity
|
|
3079
|
+
* uniqueness; status:'archived' stamps deleted_at, status:'active' restores
|
|
3080
|
+
* (and fails closed if the name was reused meanwhile).
|
|
3081
|
+
*/
|
|
3082
|
+
updateClient(id, patch = {}) {
|
|
3083
|
+
this._assertWritable('updateClient')
|
|
3084
|
+
const current = this.getClient(id)
|
|
3085
|
+
if (!current) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(id))
|
|
3086
|
+
const allowed = ['name', 'aliases', 'tags', 'secrecyDefault', 'notes', 'status']
|
|
3087
|
+
for (const field of Object.keys(patch)) {
|
|
3088
|
+
if (!allowed.includes(field)) throw new Error('unknown client field: ' + field)
|
|
3089
|
+
}
|
|
3090
|
+
const name = patch.name === undefined ? current.name : validateDisplayName('client', patch.name)
|
|
3091
|
+
const nameNorm = normalizeClientName(name)
|
|
3092
|
+
const aliases = patch.aliases === undefined ? current.aliases : validateStringList('client', 'aliases', patch.aliases)
|
|
3093
|
+
const tags = patch.tags === undefined ? current.tags : validateStringList('client', 'tags', patch.tags, { max: 20, itemMax: 40 })
|
|
3094
|
+
const secrecy = patch.secrecyDefault === undefined ? current.secrecyDefault : validateSecrecy(patch.secrecyDefault)
|
|
3095
|
+
const notes = patch.notes === undefined ? (current.notes ?? null) : normalizeOptionalText('client', 'notes', patch.notes, 4000)
|
|
3096
|
+
const status = patch.status === undefined ? current.status : validateEntityStatus('client', patch.status)
|
|
3097
|
+
const now = new Date().toISOString()
|
|
3098
|
+
let deletedAt = current.deletedAt ?? null
|
|
3099
|
+
if (status === 'archived' && deletedAt === null) deletedAt = now
|
|
3100
|
+
if (status === 'active' && deletedAt !== null) deletedAt = null
|
|
3101
|
+
if (status === 'active') this._assertClientIdentityFree({ nameNorm, aliases }, current.id)
|
|
3102
|
+
try {
|
|
3103
|
+
this.db.prepare('UPDATE clients SET name = ?, name_norm = ?, aliases = ?, status = ?, tags = ?, secrecy_default = ?, notes = ?, updated_at = ?, deleted_at = ? WHERE id = ?')
|
|
3104
|
+
.run(name, nameNorm, json(aliases), status, json(tags), secrecy, notes, now, deletedAt, current.id)
|
|
3105
|
+
} catch (error) {
|
|
3106
|
+
if (/UNIQUE constraint failed/i.test(String(error?.message ?? error))) {
|
|
3107
|
+
throw entityError('E_CLIENT_DUPLICATE', 'an active client with this name already exists', 'advisers client ls')
|
|
3108
|
+
}
|
|
3109
|
+
throw error
|
|
3110
|
+
}
|
|
3111
|
+
return this.getClient(current.id)
|
|
3112
|
+
}
|
|
3113
|
+
|
|
3114
|
+
/** Soft-delete one client (status archived + tombstone); idempotent. */
|
|
3115
|
+
archiveClient(id, { now } = {}) {
|
|
3116
|
+
this._assertWritable('archiveClient')
|
|
3117
|
+
const current = this.getClient(id)
|
|
3118
|
+
if (!current) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(id))
|
|
3119
|
+
const at = now === undefined || now === null ? new Date().toISOString() : String(now)
|
|
3120
|
+
this.db.prepare("UPDATE clients SET status = 'archived', deleted_at = COALESCE(deleted_at, ?), updated_at = ? WHERE id = ?").run(at, at, current.id)
|
|
3121
|
+
return this.getClient(current.id)
|
|
3122
|
+
}
|
|
3123
|
+
|
|
3124
|
+
/** Restore an archived client; fails closed when its name was reused. */
|
|
3125
|
+
restoreClient(id) {
|
|
3126
|
+
this._assertWritable('restoreClient')
|
|
3127
|
+
const current = this.getClient(id)
|
|
3128
|
+
if (!current) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(id))
|
|
3129
|
+
this._assertClientIdentityFree({ nameNorm: current.nameNorm, aliases: current.aliases }, current.id)
|
|
3130
|
+
const now = new Date().toISOString()
|
|
3131
|
+
this.db.prepare("UPDATE clients SET status = 'active', deleted_at = NULL, updated_at = ? WHERE id = ?").run(now, current.id)
|
|
3132
|
+
return this.getClient(current.id)
|
|
3133
|
+
}
|
|
3134
|
+
|
|
3135
|
+
/** Append one alias; alias conflicts with another live client are refused. */
|
|
3136
|
+
addClientAlias(id, alias) {
|
|
3137
|
+
this._assertWritable('addClientAlias')
|
|
3138
|
+
const current = this.getClient(id)
|
|
3139
|
+
if (!current) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(id))
|
|
3140
|
+
const text = validateDisplayName('client', alias)
|
|
3141
|
+
const norm = normalizeClientName(text)
|
|
3142
|
+
if (norm === current.nameNorm || current.aliases.some((entry) => typeof entry === 'string' && normalizeClientName(entry) === norm)) return current
|
|
3143
|
+
this._assertClientIdentityFree({ nameNorm: current.nameNorm, aliases: [text] }, current.id)
|
|
3144
|
+
const aliases = [...current.aliases, text]
|
|
3145
|
+
this.db.prepare('UPDATE clients SET aliases = ?, updated_at = ? WHERE id = ?').run(json(aliases), new Date().toISOString(), current.id)
|
|
3146
|
+
return this.getClient(current.id)
|
|
3147
|
+
}
|
|
3148
|
+
|
|
3149
|
+
/** Remove one alias (normalised match); unknown alias -> E_CLIENT_ALIAS_NOT_FOUND. */
|
|
3150
|
+
removeClientAlias(id, alias) {
|
|
3151
|
+
this._assertWritable('removeClientAlias')
|
|
3152
|
+
const current = this.getClient(id)
|
|
3153
|
+
if (!current) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(id))
|
|
3154
|
+
const norm = normalizeClientName(validateDisplayName('client', alias))
|
|
3155
|
+
const aliases = current.aliases.filter((entry) => !(typeof entry === 'string' && normalizeClientName(entry) === norm))
|
|
3156
|
+
if (aliases.length === current.aliases.length) throw entityError('E_CLIENT_ALIAS_NOT_FOUND', 'unknown alias: ' + String(alias))
|
|
3157
|
+
this.db.prepare('UPDATE clients SET aliases = ?, updated_at = ? WHERE id = ?').run(json(aliases), new Date().toISOString(), current.id)
|
|
3158
|
+
return this.getClient(current.id)
|
|
3159
|
+
}
|
|
3160
|
+
|
|
3161
|
+
/**
|
|
3162
|
+
* Merge one client into another (explicit user intent; no fuzzy matching).
|
|
3163
|
+
*
|
|
3164
|
+
* Everything source-owned moves to the target: projects with a name clash are
|
|
3165
|
+
* merged onto the target project, the remaining projects/matters/notes and
|
|
3166
|
+
* delivery snapshots are re-pointed, the source is archived (never deleted),
|
|
3167
|
+
* and its name/aliases become target aliases when no third live client owns
|
|
3168
|
+
* them. One transaction: a merge can never half-happen.
|
|
3169
|
+
*/
|
|
3170
|
+
mergeClients(fromId, intoId, { now } = {}) {
|
|
3171
|
+
this._assertWritable('mergeClients')
|
|
3172
|
+
if (String(fromId) === String(intoId)) throw entityError('E_CLIENT_MERGE_SELF', 'cannot merge a client into itself')
|
|
3173
|
+
const source = this.getClient(fromId)
|
|
3174
|
+
if (!source) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(fromId))
|
|
3175
|
+
const target = this._clientForWrite(intoId, 'mergeClients')
|
|
3176
|
+
const targetRow = this.getClient(target.id)
|
|
3177
|
+
const at = now === undefined || now === null ? new Date().toISOString() : String(now)
|
|
3178
|
+
return this._transaction('IMMEDIATE', () => {
|
|
3179
|
+
const sourceProjects = this.db.prepare('SELECT * FROM projects WHERE client_id = ? ORDER BY name_norm, id').all(source.id).map(mapProjectRow)
|
|
3180
|
+
const targetProjects = this.db.prepare("SELECT * FROM projects WHERE client_id = ? AND status = 'active' AND deleted_at IS NULL").all(target.id).map(mapProjectRow)
|
|
3181
|
+
const byName = new Map(targetProjects.map((project) => [project.nameNorm, project]))
|
|
3182
|
+
let movedProjects = 0
|
|
3183
|
+
let mergedProjects = 0
|
|
3184
|
+
for (const project of sourceProjects) {
|
|
3185
|
+
const existing = byName.get(project.nameNorm)
|
|
3186
|
+
if (!existing) {
|
|
3187
|
+
this.db.prepare('UPDATE projects SET client_id = ?, updated_at = ? WHERE id = ?').run(target.id, at, project.id)
|
|
3188
|
+
movedProjects++
|
|
3189
|
+
} else {
|
|
3190
|
+
this.db.prepare('UPDATE matters SET project_id = ? WHERE project_id = ?').run(existing.id, project.id)
|
|
3191
|
+
this.db.prepare('UPDATE client_notes SET project_id = ? WHERE project_id = ?').run(existing.id, project.id)
|
|
3192
|
+
this.db.prepare("UPDATE projects SET status = 'archived', deleted_at = ?, updated_at = ? WHERE id = ?").run(at, at, project.id)
|
|
3193
|
+
mergedProjects++
|
|
3194
|
+
}
|
|
3195
|
+
}
|
|
3196
|
+
const movedMatters = Number(this.db.prepare('UPDATE matters SET client_id = ?, updated_at = ? WHERE client_id = ?').run(target.id, at, source.id).changes)
|
|
3197
|
+
const movedNotes = Number(this.db.prepare('UPDATE client_notes SET client_id = ? WHERE client_id = ?').run(target.id, source.id).changes)
|
|
3198
|
+
const movedDeliveries = Number(this.db.prepare('UPDATE deliveries SET client_id = ? WHERE client_id = ?').run(target.id, source.id).changes)
|
|
3199
|
+
this.db.prepare("UPDATE clients SET status = 'archived', deleted_at = COALESCE(deleted_at, ?), updated_at = ? WHERE id = ?").run(at, at, source.id)
|
|
3200
|
+
const taken = new Set()
|
|
3201
|
+
for (const identity of this._activeClientIdentities(target.id)) for (const norm of identity.norms.keys()) taken.add(norm)
|
|
3202
|
+
const aliases = targetRow.aliases.slice()
|
|
3203
|
+
const seen = new Set(aliases.map((entry) => normalizeClientName(String(entry))))
|
|
3204
|
+
let carriedAliases = 0
|
|
3205
|
+
for (const name of [source.name, ...source.aliases]) {
|
|
3206
|
+
if (typeof name !== 'string') continue
|
|
3207
|
+
const norm = normalizeClientName(name)
|
|
3208
|
+
if (!norm || norm === targetRow.nameNorm || seen.has(norm) || taken.has(norm)) continue
|
|
3209
|
+
aliases.push(name)
|
|
3210
|
+
seen.add(norm)
|
|
3211
|
+
carriedAliases++
|
|
3212
|
+
}
|
|
3213
|
+
if (carriedAliases) this.db.prepare('UPDATE clients SET aliases = ?, updated_at = ? WHERE id = ?').run(json(aliases), at, target.id)
|
|
3214
|
+
return {
|
|
3215
|
+
client: this.getClient(target.id),
|
|
3216
|
+
mergedFrom: source.id,
|
|
3217
|
+
movedMatters,
|
|
3218
|
+
movedProjects,
|
|
3219
|
+
mergedProjects,
|
|
3220
|
+
movedNotes,
|
|
3221
|
+
movedDeliveries,
|
|
3222
|
+
carriedAliases,
|
|
3223
|
+
}
|
|
3224
|
+
})
|
|
3225
|
+
}
|
|
3226
|
+
|
|
3227
|
+
// -------------------------------------------------------------------------
|
|
3228
|
+
// Projects (one client per project; a cross-client job is two projects).
|
|
3229
|
+
// -------------------------------------------------------------------------
|
|
3230
|
+
|
|
3231
|
+
/** Create a project under one live client. */
|
|
3232
|
+
addProject({ clientId, name, startedAt, dueAt, defaultMatterId, notes, status, id } = {}) {
|
|
3233
|
+
this._assertWritable('addProject')
|
|
3234
|
+
const client = this._clientForWrite(clientId, 'addProject')
|
|
3235
|
+
const displayName = validateDisplayName('project', name)
|
|
3236
|
+
const nameNorm = normalizeClientName(displayName)
|
|
3237
|
+
const projectStatus = validateEntityStatus('project', status)
|
|
3238
|
+
const projectId = id === undefined || id === null ? 'prj_' + randomUUID().replace(/-/g, '').slice(0, 16) : String(id).trim()
|
|
3239
|
+
if (!projectId) throw entityError('E_PROJECT_INVALID', 'project id must not be empty')
|
|
3240
|
+
if (this.getProject(projectId)) throw entityError('E_PROJECT_DUPLICATE', 'project id already exists: ' + projectId)
|
|
3241
|
+
let matterId = null
|
|
3242
|
+
if (defaultMatterId !== undefined && defaultMatterId !== null) {
|
|
3243
|
+
const matter = this.getMatter(String(defaultMatterId))
|
|
3244
|
+
if (!matter) throw entityError('E_MATTER_NOT_FOUND', 'unknown matter: ' + String(defaultMatterId), 'advisers matter ls')
|
|
3245
|
+
matterId = matter.id
|
|
3246
|
+
}
|
|
3247
|
+
const starts = normalizeOptionalDate('project', 'startedAt', startedAt)
|
|
3248
|
+
const ends = normalizeOptionalDate('project', 'dueAt', dueAt)
|
|
3249
|
+
const now = new Date().toISOString()
|
|
3250
|
+
try {
|
|
3251
|
+
this.db.prepare('INSERT INTO projects(id,client_id,name,name_norm,status,started_at,due_at,default_matter_id,notes,created_at,updated_at,deleted_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)')
|
|
3252
|
+
.run(projectId, client.id, displayName, nameNorm, projectStatus, starts, ends, matterId, normalizeOptionalText('project', 'notes', notes, 4000), now, now, projectStatus === 'archived' ? now : null)
|
|
3253
|
+
} catch (error) {
|
|
3254
|
+
if (/UNIQUE constraint failed/i.test(String(error?.message ?? error))) {
|
|
3255
|
+
throw entityError('E_PROJECT_DUPLICATE', 'this client already has an active project with this name', 'advisers project ls --client ' + client.id)
|
|
3256
|
+
}
|
|
3257
|
+
throw error
|
|
3258
|
+
}
|
|
3259
|
+
return this.getProject(projectId)
|
|
3260
|
+
}
|
|
3261
|
+
|
|
3262
|
+
/** One project by id (archived included; undefined when absent). */
|
|
3263
|
+
getProject(id) {
|
|
3264
|
+
const row = this.db.prepare('SELECT * FROM projects WHERE id = ?').get(String(id))
|
|
3265
|
+
return row ? mapProjectRow(row) : undefined
|
|
3266
|
+
}
|
|
3267
|
+
|
|
3268
|
+
/** Deterministic name lookup inside one client (active projects only). */
|
|
3269
|
+
findProjectByName(clientId, name) {
|
|
3270
|
+
const nameNorm = normalizeClientName(validateDisplayName('project', name))
|
|
3271
|
+
const row = this.db.prepare("SELECT * FROM projects WHERE client_id = ? AND name_norm = ? AND status = 'active' AND deleted_at IS NULL ORDER BY id LIMIT 1").get(String(clientId), nameNorm)
|
|
3272
|
+
return row ? mapProjectRow(row) : undefined
|
|
3273
|
+
}
|
|
3274
|
+
|
|
3275
|
+
/** List projects, optionally scoped to one client. */
|
|
3276
|
+
listProjects({ clientId, status = 'active', includeDeleted = false, limit = 100 } = {}) {
|
|
3277
|
+
const where = []
|
|
3278
|
+
const params = []
|
|
3279
|
+
if (includeDeleted !== true) where.push('deleted_at IS NULL')
|
|
3280
|
+
if (clientId !== undefined && clientId !== null) { where.push('client_id = ?'); params.push(String(clientId)) }
|
|
3281
|
+
if (status !== 'all') {
|
|
3282
|
+
const wanted = validateEntityStatus('project', status)
|
|
3283
|
+
where.push('status = ?')
|
|
3284
|
+
params.push(wanted)
|
|
3285
|
+
}
|
|
3286
|
+
const sql = 'SELECT * FROM projects' + (where.length ? ' WHERE ' + where.join(' AND ') : '') + ' ORDER BY client_id ASC, name_norm ASC, id ASC LIMIT ?'
|
|
3287
|
+
return this.db.prepare(sql).all(...params, normalizeRowLimit(limit, { def: 100, max: 1000 })).map(mapProjectRow)
|
|
3288
|
+
}
|
|
3289
|
+
|
|
3290
|
+
/** Update mutable project fields (rename re-checks the per-client uniqueness). */
|
|
3291
|
+
updateProject(id, patch = {}) {
|
|
3292
|
+
this._assertWritable('updateProject')
|
|
3293
|
+
const current = this.getProject(id)
|
|
3294
|
+
if (!current) throw entityError('E_PROJECT_NOT_FOUND', 'unknown project: ' + String(id))
|
|
3295
|
+
const allowed = ['name', 'status', 'startedAt', 'dueAt', 'defaultMatterId', 'notes']
|
|
3296
|
+
for (const field of Object.keys(patch)) {
|
|
3297
|
+
if (!allowed.includes(field)) throw new Error('unknown project field: ' + field)
|
|
3298
|
+
}
|
|
3299
|
+
const name = patch.name === undefined ? current.name : validateDisplayName('project', patch.name)
|
|
3300
|
+
const nameNorm = normalizeClientName(name)
|
|
3301
|
+
const status = patch.status === undefined ? current.status : validateEntityStatus('project', patch.status)
|
|
3302
|
+
const starts = patch.startedAt === undefined ? (current.startedAt ?? null) : normalizeOptionalDate('project', 'startedAt', patch.startedAt)
|
|
3303
|
+
const ends = patch.dueAt === undefined ? (current.dueAt ?? null) : normalizeOptionalDate('project', 'dueAt', patch.dueAt)
|
|
3304
|
+
const notes = patch.notes === undefined ? (current.notes ?? null) : normalizeOptionalText('project', 'notes', patch.notes, 4000)
|
|
3305
|
+
let matterId = current.defaultMatterId ?? null
|
|
3306
|
+
if (patch.defaultMatterId !== undefined) {
|
|
3307
|
+
matterId = patch.defaultMatterId === null ? null : String(patch.defaultMatterId)
|
|
3308
|
+
if (matterId !== null && !this.getMatter(matterId)) throw entityError('E_MATTER_NOT_FOUND', 'unknown matter: ' + matterId, 'advisers matter ls')
|
|
3309
|
+
}
|
|
3310
|
+
const now = new Date().toISOString()
|
|
3311
|
+
let deletedAt = current.deletedAt ?? null
|
|
3312
|
+
if (status === 'archived' && deletedAt === null) deletedAt = now
|
|
3313
|
+
if (status === 'active' && deletedAt !== null) deletedAt = null
|
|
3314
|
+
try {
|
|
3315
|
+
this.db.prepare('UPDATE projects SET name = ?, name_norm = ?, status = ?, started_at = ?, due_at = ?, default_matter_id = ?, notes = ?, updated_at = ?, deleted_at = ? WHERE id = ?')
|
|
3316
|
+
.run(name, nameNorm, status, starts, ends, matterId, notes, now, deletedAt, current.id)
|
|
3317
|
+
} catch (error) {
|
|
3318
|
+
if (/UNIQUE constraint failed/i.test(String(error?.message ?? error))) {
|
|
3319
|
+
throw entityError('E_PROJECT_DUPLICATE', 'this client already has an active project with this name', 'advisers project ls --client ' + current.clientId)
|
|
3320
|
+
}
|
|
3321
|
+
throw error
|
|
3322
|
+
}
|
|
3323
|
+
return this.getProject(current.id)
|
|
3324
|
+
}
|
|
3325
|
+
|
|
3326
|
+
/** Soft-delete one project (idempotent). */
|
|
3327
|
+
archiveProject(id, { now } = {}) {
|
|
3328
|
+
this._assertWritable('archiveProject')
|
|
3329
|
+
const current = this.getProject(id)
|
|
3330
|
+
if (!current) throw entityError('E_PROJECT_NOT_FOUND', 'unknown project: ' + String(id))
|
|
3331
|
+
const at = now === undefined || now === null ? new Date().toISOString() : String(now)
|
|
3332
|
+
this.db.prepare("UPDATE projects SET status = 'archived', deleted_at = COALESCE(deleted_at, ?), updated_at = ? WHERE id = ?").run(at, at, current.id)
|
|
3333
|
+
return this.getProject(current.id)
|
|
3334
|
+
}
|
|
3335
|
+
|
|
3336
|
+
// -------------------------------------------------------------------------
|
|
3337
|
+
// Client notes (the manual source of the derived timeline).
|
|
3338
|
+
// -------------------------------------------------------------------------
|
|
3339
|
+
|
|
3340
|
+
/** Resolve a project that must belong to the given client. */
|
|
3341
|
+
_projectForClient(projectId, clientId) {
|
|
3342
|
+
const project = this.getProject(String(projectId))
|
|
3343
|
+
if (!project) throw entityError('E_PROJECT_NOT_FOUND', 'unknown project: ' + String(projectId), 'advisers project ls')
|
|
3344
|
+
if (project.clientId !== clientId) throw entityError('E_PROJECT_CLIENT_MISMATCH', 'project ' + project.id + ' belongs to client ' + project.clientId)
|
|
3345
|
+
return project
|
|
3346
|
+
}
|
|
3347
|
+
|
|
3348
|
+
/**
|
|
3349
|
+
* Record one client note (phone call, meeting, decision, ...). The summary is
|
|
3350
|
+
* operator prose (<= 2000 chars); source is lineage only (kind/id/quote), so a
|
|
3351
|
+
* note can point at a delivery or matter without copying a file or a path.
|
|
3352
|
+
*/
|
|
3353
|
+
addClientNote({ clientId, projectId, matterId, kind, at, summary, source, id } = {}) {
|
|
3354
|
+
this._assertWritable('addClientNote')
|
|
3355
|
+
const client = this._clientForWrite(clientId, 'addClientNote')
|
|
3356
|
+
const noteKind = kind === undefined || kind === null ? 'note' : String(kind)
|
|
3357
|
+
if (!CLIENT_NOTE_KINDS.includes(noteKind)) {
|
|
3358
|
+
throw entityError('E_CLIENT_NOTE_INVALID', 'unknown note kind: ' + noteKind, 'use one of ' + CLIENT_NOTE_KINDS.join(', '))
|
|
3359
|
+
}
|
|
3360
|
+
let resolvedProjectId = null
|
|
3361
|
+
if (projectId !== undefined && projectId !== null) resolvedProjectId = this._projectForClient(projectId, client.id).id
|
|
3362
|
+
let resolvedMatterId = null
|
|
3363
|
+
if (matterId !== undefined && matterId !== null) {
|
|
3364
|
+
const matter = this.getMatter(String(matterId))
|
|
3365
|
+
if (!matter) throw entityError('E_MATTER_NOT_FOUND', 'unknown matter: ' + String(matterId), 'advisers matter ls')
|
|
3366
|
+
if (matter.clientId != null && matter.clientId !== client.id) {
|
|
3367
|
+
throw entityError('E_MATTER_CLIENT_MISMATCH', 'matter ' + matter.id + ' belongs to client ' + matter.clientId)
|
|
3368
|
+
}
|
|
3369
|
+
resolvedMatterId = matter.id
|
|
3370
|
+
if (resolvedProjectId === null && matter.projectId != null) resolvedProjectId = matter.projectId
|
|
3371
|
+
}
|
|
3372
|
+
if (typeof summary !== 'string' || !summary.trim()) throw entityError('E_CLIENT_NOTE_INVALID', 'summary is required')
|
|
3373
|
+
const text = summary.trim()
|
|
3374
|
+
if (text.length > 2000) throw entityError('E_CLIENT_NOTE_INVALID', 'summary must be at most 2000 characters')
|
|
3375
|
+
const noteAt = normalizeNoteInstant(at)
|
|
3376
|
+
const noteSource = validateNoteSource(source)
|
|
3377
|
+
const noteId = id === undefined || id === null ? 'note_' + randomUUID().replace(/-/g, '').slice(0, 16) : String(id).trim()
|
|
3378
|
+
if (!noteId) throw entityError('E_CLIENT_NOTE_INVALID', 'note id must not be empty')
|
|
3379
|
+
if (this.getClientNote(noteId)) throw entityError('E_CLIENT_NOTE_INVALID', 'note id already exists: ' + noteId)
|
|
3380
|
+
this.db.prepare('INSERT INTO client_notes(id,client_id,project_id,matter_id,kind,at,summary,source,created_at,deleted_at) VALUES(?,?,?,?,?,?,?,?,?,?)')
|
|
3381
|
+
.run(noteId, client.id, resolvedProjectId, resolvedMatterId, noteKind, noteAt, text, noteSource, new Date().toISOString(), null)
|
|
3382
|
+
return this.getClientNote(noteId)
|
|
3383
|
+
}
|
|
3384
|
+
|
|
3385
|
+
/** One note by id (deleted notes included; undefined when absent). */
|
|
3386
|
+
getClientNote(id) {
|
|
3387
|
+
const row = this.db.prepare('SELECT * FROM client_notes WHERE id = ?').get(String(id))
|
|
3388
|
+
return row ? mapClientNoteRow(row) : undefined
|
|
3389
|
+
}
|
|
3390
|
+
|
|
3391
|
+
/**
|
|
3392
|
+
* Notes of one client, newest event first (at DESC, then rowid DESC so notes
|
|
3393
|
+
* written in one batch keep their order). Soft-deleted notes are hidden by
|
|
3394
|
+
* default.
|
|
3395
|
+
*/
|
|
3396
|
+
listClientNotes({ clientId, projectId, matterId, includeDeleted = false, limit = 50 } = {}) {
|
|
3397
|
+
const where = []
|
|
3398
|
+
const params = []
|
|
3399
|
+
if (clientId !== undefined && clientId !== null) { where.push('client_id = ?'); params.push(String(clientId)) }
|
|
3400
|
+
if (projectId !== undefined && projectId !== null) { where.push('project_id = ?'); params.push(String(projectId)) }
|
|
3401
|
+
if (matterId !== undefined && matterId !== null) { where.push('matter_id = ?'); params.push(String(matterId)) }
|
|
3402
|
+
if (includeDeleted !== true) where.push('deleted_at IS NULL')
|
|
3403
|
+
const sql = 'SELECT * FROM client_notes' + (where.length ? ' WHERE ' + where.join(' AND ') : '') + ' ORDER BY at DESC, rowid DESC LIMIT ?'
|
|
3404
|
+
return this.db.prepare(sql).all(...params, normalizeRowLimit(limit, { def: 50, max: 500 })).map(mapClientNoteRow)
|
|
3405
|
+
}
|
|
3406
|
+
|
|
3407
|
+
/** Update one note; the client ownership cannot be changed, the project can. */
|
|
3408
|
+
updateClientNote(id, patch = {}) {
|
|
3409
|
+
this._assertWritable('updateClientNote')
|
|
3410
|
+
const current = this.getClientNote(id)
|
|
3411
|
+
if (!current) throw entityError('E_CLIENT_NOTE_NOT_FOUND', 'unknown note: ' + String(id))
|
|
3412
|
+
const allowed = ['kind', 'at', 'summary', 'projectId', 'matterId']
|
|
3413
|
+
for (const field of Object.keys(patch)) {
|
|
3414
|
+
if (!allowed.includes(field)) throw new Error('unknown client note field: ' + field)
|
|
3415
|
+
}
|
|
3416
|
+
const kind = patch.kind === undefined ? current.kind : String(patch.kind)
|
|
3417
|
+
if (!CLIENT_NOTE_KINDS.includes(kind)) throw entityError('E_CLIENT_NOTE_INVALID', 'unknown note kind: ' + kind, 'use one of ' + CLIENT_NOTE_KINDS.join(', '))
|
|
3418
|
+
const at = patch.at === undefined ? current.at : normalizeNoteInstant(patch.at)
|
|
3419
|
+
let summary = current.summary
|
|
3420
|
+
if (patch.summary !== undefined) {
|
|
3421
|
+
if (typeof patch.summary !== 'string' || !patch.summary.trim()) throw entityError('E_CLIENT_NOTE_INVALID', 'summary is required')
|
|
3422
|
+
summary = patch.summary.trim()
|
|
3423
|
+
if (summary.length > 2000) throw entityError('E_CLIENT_NOTE_INVALID', 'summary must be at most 2000 characters')
|
|
3424
|
+
}
|
|
3425
|
+
let projectId = current.projectId ?? null
|
|
3426
|
+
if (patch.projectId !== undefined) projectId = patch.projectId === null ? null : this._projectForClient(patch.projectId, current.clientId).id
|
|
3427
|
+
let matterId = current.matterId ?? null
|
|
3428
|
+
if (patch.matterId !== undefined) {
|
|
3429
|
+
if (patch.matterId === null) matterId = null
|
|
3430
|
+
else {
|
|
3431
|
+
const matter = this.getMatter(String(patch.matterId))
|
|
3432
|
+
if (!matter) throw entityError('E_MATTER_NOT_FOUND', 'unknown matter: ' + String(patch.matterId), 'advisers matter ls')
|
|
3433
|
+
if (matter.clientId != null && matter.clientId !== current.clientId) throw entityError('E_MATTER_CLIENT_MISMATCH', 'matter ' + matter.id + ' belongs to client ' + matter.clientId)
|
|
3434
|
+
matterId = matter.id
|
|
3435
|
+
}
|
|
3436
|
+
}
|
|
3437
|
+
this.db.prepare('UPDATE client_notes SET kind = ?, at = ?, summary = ?, project_id = ?, matter_id = ? WHERE id = ?').run(kind, at, summary, projectId, matterId, current.id)
|
|
3438
|
+
return this.getClientNote(current.id)
|
|
3439
|
+
}
|
|
3440
|
+
|
|
3441
|
+
/** Soft-delete one note (idempotent; never a hard delete of user data). */
|
|
3442
|
+
deleteClientNote(id, { now } = {}) {
|
|
3443
|
+
this._assertWritable('deleteClientNote')
|
|
3444
|
+
const current = this.getClientNote(id)
|
|
3445
|
+
if (!current) throw entityError('E_CLIENT_NOTE_NOT_FOUND', 'unknown note: ' + String(id))
|
|
3446
|
+
if (current.deletedAt) return current
|
|
3447
|
+
const at = now === undefined || now === null ? new Date().toISOString() : String(now)
|
|
3448
|
+
this.db.prepare('UPDATE client_notes SET deleted_at = ? WHERE id = ?').run(at, current.id)
|
|
3449
|
+
return this.getClientNote(current.id)
|
|
3450
|
+
}
|
|
3451
|
+
|
|
3452
|
+
// -------------------------------------------------------------------------
|
|
3453
|
+
// Matter ownership (client/project) + the derived timeline sources.
|
|
3454
|
+
// -------------------------------------------------------------------------
|
|
3455
|
+
|
|
3456
|
+
/**
|
|
3457
|
+
* Point one matter at a client (and optionally one of that client's
|
|
3458
|
+
* projects), or unlink it with both null. Only this column pair is written:
|
|
3459
|
+
* commitments/facts stay matter-scoped, so re-linking can never leave two
|
|
3460
|
+
* copies of the truth behind.
|
|
3461
|
+
*/
|
|
3462
|
+
setMatterClient(matterId, { clientId, projectId } = {}) {
|
|
3463
|
+
this._assertWritable('setMatterClient')
|
|
3464
|
+
const matter = this.getMatter(String(matterId))
|
|
3465
|
+
if (!matter) throw entityError('E_MATTER_NOT_FOUND', 'unknown matter: ' + String(matterId), 'advisers matter ls')
|
|
3466
|
+
let resolvedClientId = clientId === undefined || clientId === null ? null : clientId
|
|
3467
|
+
let resolvedProjectId = projectId === undefined || projectId === null ? null : projectId
|
|
3468
|
+
if (resolvedClientId === null && resolvedProjectId !== null) {
|
|
3469
|
+
throw entityError('E_PROJECT_CLIENT_MISMATCH', 'projectId requires clientId; a project belongs to exactly one client')
|
|
3470
|
+
}
|
|
3471
|
+
if (resolvedClientId !== null) {
|
|
3472
|
+
const client = this._clientForWrite(resolvedClientId, 'setMatterClient')
|
|
3473
|
+
resolvedClientId = client.id
|
|
3474
|
+
if (resolvedProjectId !== null) {
|
|
3475
|
+
const project = this._projectForClient(resolvedProjectId, resolvedClientId)
|
|
3476
|
+
if (project.status !== 'active' || project.deletedAt) throw entityError('E_PROJECT_ARCHIVED', 'project is archived: ' + project.id, 'advisers project ls')
|
|
3477
|
+
resolvedProjectId = project.id
|
|
3478
|
+
}
|
|
3479
|
+
}
|
|
3480
|
+
this.db.prepare('UPDATE matters SET client_id = ?, project_id = ?, updated_at = ? WHERE id = ?')
|
|
3481
|
+
.run(resolvedClientId, resolvedProjectId, new Date().toISOString(), matter.id)
|
|
3482
|
+
return this.getMatter(matter.id)
|
|
3483
|
+
}
|
|
3484
|
+
|
|
3485
|
+
/** Every matter owned by one client, in insertion order (archived included). */
|
|
3486
|
+
listMattersByClient(clientId, { status } = {}) {
|
|
3487
|
+
const where = ['client_id = ?']
|
|
3488
|
+
const params = [String(clientId)]
|
|
3489
|
+
if (status !== undefined && status !== null) { where.push('status = ?'); params.push(String(status)) }
|
|
3490
|
+
return this.db.prepare('SELECT * FROM matters WHERE ' + where.join(' AND ') + ' ORDER BY rowid').all(...params).map(mapMatterRow)
|
|
3491
|
+
}
|
|
3492
|
+
|
|
3493
|
+
/** Every matter owned by one project, in insertion order. */
|
|
3494
|
+
listMattersByProject(projectId, { status } = {}) {
|
|
3495
|
+
const where = ['project_id = ?']
|
|
3496
|
+
const params = [String(projectId)]
|
|
3497
|
+
if (status !== undefined && status !== null) { where.push('status = ?'); params.push(String(status)) }
|
|
3498
|
+
return this.db.prepare('SELECT * FROM matters WHERE ' + where.join(' AND ') + ' ORDER BY rowid').all(...params).map(mapMatterRow)
|
|
3499
|
+
}
|
|
3500
|
+
|
|
3501
|
+
/** Matters that are not linked to any client (the honest "unclassified" view). */
|
|
3502
|
+
listUnclassifiedMatters({ limit = 100 } = {}) {
|
|
3503
|
+
return this.db.prepare('SELECT * FROM matters WHERE client_id IS NULL ORDER BY rowid LIMIT ?').all(normalizeRowLimit(limit, { def: 100, max: 1000 })).map(mapMatterRow)
|
|
3504
|
+
}
|
|
3505
|
+
|
|
3506
|
+
/**
|
|
3507
|
+
* One read snapshot of everything a customer timeline is derived from.
|
|
3508
|
+
*
|
|
3509
|
+
* The caller merges these rows with packages/core/src/customer.ts
|
|
3510
|
+
* (deriveClientTimeline). Every query is scoped by the client's own matters,
|
|
3511
|
+
* so two clients can never see each other's rows: no full-table read followed
|
|
3512
|
+
* by an in-memory filter happens in this path. Limits bound each source (the
|
|
3513
|
+
* derivation applies the display limit afterwards).
|
|
3514
|
+
*/
|
|
3515
|
+
clientTimelineSources(clientId, { limit = 200 } = {}) {
|
|
3516
|
+
const client = this.getClient(String(clientId))
|
|
3517
|
+
if (!client) throw entityError('E_CLIENT_NOT_FOUND', 'unknown client: ' + String(clientId), 'advisers client ls')
|
|
3518
|
+
const rowLimit = normalizeRowLimit(limit, { def: 200, max: 500 })
|
|
3519
|
+
const matters = this.db.prepare('SELECT * FROM matters WHERE client_id = ? ORDER BY rowid').all(client.id).map(mapMatterRow)
|
|
3520
|
+
const projects = this.db.prepare('SELECT * FROM projects WHERE client_id = ? ORDER BY name_norm ASC, id ASC').all(client.id).map(mapProjectRow)
|
|
3521
|
+
const matterIds = matters.map((matter) => matter.id)
|
|
3522
|
+
let commitments = []
|
|
3523
|
+
let deliveries = []
|
|
3524
|
+
if (matterIds.length) {
|
|
3525
|
+
const placeholders = matterIds.map(() => '?').join(',')
|
|
3526
|
+
commitments = this.db.prepare('SELECT * FROM commitments WHERE matter_id IN (' + placeholders + ') ORDER BY rowid DESC LIMIT ?')
|
|
3527
|
+
.all(...matterIds, rowLimit).map(mapCommitmentRow)
|
|
3528
|
+
deliveries = this.db.prepare('SELECT * FROM deliveries WHERE matter_id IN (' + placeholders + ') ORDER BY created_at DESC, rowid DESC LIMIT ?')
|
|
3529
|
+
.all(...matterIds, rowLimit).map(mapDeliveryRow)
|
|
3530
|
+
}
|
|
3531
|
+
const notes = this.db.prepare('SELECT * FROM client_notes WHERE client_id = ? AND deleted_at IS NULL ORDER BY at DESC, rowid DESC LIMIT ?')
|
|
3532
|
+
.all(client.id, rowLimit).map(mapClientNoteRow)
|
|
3533
|
+
return { client: client, projects: projects, matters: matters, commitments: commitments, deliveries: deliveries, notes: notes, limit: rowLimit }
|
|
3534
|
+
}
|
|
3535
|
+
|
|
3536
|
+
/**
|
|
3537
|
+
* Raw rows of the SQLite-only tables carried next to a ledger export.
|
|
3538
|
+
*
|
|
3539
|
+
* The snake_case raw row shape matches what export --all has always written,
|
|
3540
|
+
* and DATA_TABLES is the single list of tables so an export/import helper
|
|
3541
|
+
* cannot silently drop the v21 customer entities.
|
|
3542
|
+
*/
|
|
3543
|
+
exportDataTables(tables = DATA_TABLES) {
|
|
3544
|
+
const data = {}
|
|
3545
|
+
for (const table of tables) {
|
|
3546
|
+
if (!DATA_TABLES.includes(table)) throw new Error('unknown export table: ' + table)
|
|
3547
|
+
data[table] = this.db.prepare('SELECT * FROM ' + table).all()
|
|
3548
|
+
}
|
|
3549
|
+
return data
|
|
3550
|
+
}
|
|
3551
|
+
|
|
1486
3552
|
// -------------------------------------------------------------------------
|
|
1487
3553
|
// Partial loading (P1-2, 0.2.2)
|
|
1488
3554
|
//
|
|
@@ -1549,27 +3615,180 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1549
3615
|
return matters
|
|
1550
3616
|
}
|
|
1551
3617
|
|
|
1552
|
-
|
|
3618
|
+
/**
|
|
3619
|
+
* Load one ledger table's rows.
|
|
3620
|
+
*
|
|
3621
|
+
* 0.3.0 P0-T1: two optional knobs keep the hot read paths off the TEMP
|
|
3622
|
+
* B-TREE. The v20 status-leading indexes (`idx_facts_status_deleted`,
|
|
3623
|
+
* `idx_commitments_status_due`) cannot satisfy `ORDER BY rowid` for a
|
|
3624
|
+
* status predicate, so SQLite sorted every matching row into a TEMP B-TREE
|
|
3625
|
+
* and spilled it to disk (pet-brief wrote 29 MB per run, today 5.6 MB).
|
|
3626
|
+
*
|
|
3627
|
+
* @param {object} [options]
|
|
3628
|
+
* @param {boolean} [options.validOnly] facts only: `expired_at IS NULL AND
|
|
3629
|
+
* deleted_at IS NULL`. With `status` also set this is an index key prefix,
|
|
3630
|
+
* so rowid order comes from the index and no sort/spill happens.
|
|
3631
|
+
* @param {'rowid'|'natural'|'table'} [options.order='rowid'] commitments only:
|
|
3632
|
+
* 'rowid' keeps the historical ORDER BY rowid (may sort); 'natural' leaves
|
|
3633
|
+
* the order to the plan (index order, no sort); 'table' reads the table
|
|
3634
|
+
* without an index (rowid order, no sort) -- the cheapest way to keep
|
|
3635
|
+
* insertion order when a predicate matches a large fraction of the table.
|
|
3636
|
+
*/
|
|
3637
|
+
loadFacts({ status, matterId, includeDeleted, validOnly } = {}) {
|
|
1553
3638
|
const where = []
|
|
1554
3639
|
const params = []
|
|
1555
3640
|
if (status !== undefined) { where.push('status = ?'); params.push(status) }
|
|
1556
3641
|
if (matterId !== undefined) { where.push('matter_id = ?'); params.push(matterId) }
|
|
1557
3642
|
if (includeDeleted === false) where.push('deleted_at IS NULL')
|
|
3643
|
+
if (validOnly === true) {
|
|
3644
|
+
where.push('expired_at IS NULL')
|
|
3645
|
+
if (includeDeleted !== true) where.push('deleted_at IS NULL')
|
|
3646
|
+
}
|
|
1558
3647
|
const facts = this._selectRows('facts', where, params, ' ORDER BY rowid').map(mapFactRow)
|
|
1559
3648
|
this._markLoadedRows('facts', facts)
|
|
1560
3649
|
return facts
|
|
1561
3650
|
}
|
|
1562
3651
|
|
|
1563
|
-
loadCommitments({ status, matterId } = {}) {
|
|
3652
|
+
loadCommitments({ status, matterId, order = 'rowid' } = {}) {
|
|
1564
3653
|
const where = []
|
|
1565
3654
|
const params = []
|
|
1566
3655
|
if (status !== undefined) { where.push('status = ?'); params.push(status) }
|
|
1567
3656
|
if (matterId !== undefined) { where.push('matter_id = ?'); params.push(matterId) }
|
|
1568
|
-
const
|
|
3657
|
+
const table = order === 'table' ? 'commitments NOT INDEXED' : 'commitments'
|
|
3658
|
+
const suffix = order === 'natural' || order === 'table' ? '' : ' ORDER BY rowid'
|
|
3659
|
+
const commitments = this._selectRows(table, where, params, suffix).map(mapCommitmentRow)
|
|
1569
3660
|
this._markLoadedRows('commitments', commitments)
|
|
1570
3661
|
return commitments
|
|
1571
3662
|
}
|
|
1572
3663
|
|
|
3664
|
+
// -------------------------------------------------------------------------
|
|
3665
|
+
// 0.3.0 P0-T2: narrow read projections (2026-11-20).
|
|
3666
|
+
//
|
|
3667
|
+
// The 0.2.x views paid two costs these projections remove: mapping whole
|
|
3668
|
+
// entities (JSON.parse of evidence / reminder_offsets) for rows a view only
|
|
3669
|
+
// counts, and ORDER BY rowid after a status predicate (TEMP B-TREE spill,
|
|
3670
|
+
// see P0-T1 above). Each projection returns exactly the columns its view
|
|
3671
|
+
// reads, in table-scan order (= rowid order): a NOT INDEXED scan is
|
|
3672
|
+
// sequential, so it keeps the historical array order without a sort and is
|
|
3673
|
+
// faster than 66k index -> table lookups at 200k rows (40 ms vs 100-120 ms).
|
|
3674
|
+
//
|
|
3675
|
+
// Only status predicates are pushed to SQL. Every due-date comparison stays
|
|
3676
|
+
// in JS: due_at is TEXT with mixed formats (date-only / no zone / Z /
|
|
3677
|
+
// offsets) and JS Date.parse semantics differ from SQLite julianday() for
|
|
3678
|
+
// the no-zone forms, so SQL-side date filtering would change behaviour.
|
|
3679
|
+
// These helpers are read-only and never feed save().
|
|
3680
|
+
// -------------------------------------------------------------------------
|
|
3681
|
+
|
|
3682
|
+
/**
|
|
3683
|
+
* Run a read-only projection and map rows positionally.
|
|
3684
|
+
* setReturnArrays skips building one object per row inside node:sqlite
|
|
3685
|
+
* (~25% faster at 66k rows) and the view maps only the columns it needs.
|
|
3686
|
+
*/
|
|
3687
|
+
_project(sql, params, map) {
|
|
3688
|
+
const statement = this.db.prepare(sql)
|
|
3689
|
+
if (typeof statement.setReturnArrays === 'function') statement.setReturnArrays(true)
|
|
3690
|
+
return statement.all(...params).map(map)
|
|
3691
|
+
}
|
|
3692
|
+
|
|
3693
|
+
/** today (human view): same minimal open-commitment rows as before. */
|
|
3694
|
+
projectOpenCommitmentsForToday() {
|
|
3695
|
+
return this._project(
|
|
3696
|
+
"SELECT id, debtor, creditor, action, due_at FROM commitments NOT INDEXED WHERE status = 'open'",
|
|
3697
|
+
[],
|
|
3698
|
+
(row) => ({ id: row[0], debtor: row[1], creditor: row[2], action: row[3], dueAt: row[4] ?? undefined }),
|
|
3699
|
+
)
|
|
3700
|
+
}
|
|
3701
|
+
|
|
3702
|
+
/**
|
|
3703
|
+
* remind / tui: every row buildReminders can turn into a reminder (not
|
|
3704
|
+
* done/dropped, has a due_at). The due-date test itself stays in JS.
|
|
3705
|
+
*/
|
|
3706
|
+
projectCommitmentsForReminders({ includeUndated = false } = {}) {
|
|
3707
|
+
return this._project(
|
|
3708
|
+
includeUndated
|
|
3709
|
+
? "SELECT id, status, creditor, action, due_at, reminder_offsets FROM commitments NOT INDEXED WHERE status NOT IN ('done','dropped')"
|
|
3710
|
+
: "SELECT id, status, creditor, action, due_at, reminder_offsets FROM commitments NOT INDEXED WHERE status NOT IN ('done','dropped') AND due_at IS NOT NULL",
|
|
3711
|
+
[],
|
|
3712
|
+
(row) => {
|
|
3713
|
+
const offsets = row[5] == null ? null : parse(row[5], null)
|
|
3714
|
+
return {
|
|
3715
|
+
id: row[0], status: row[1], creditor: row[2], action: row[3], dueAt: row[4],
|
|
3716
|
+
...(Array.isArray(offsets) ? { reminderOffsets: offsets } : {}),
|
|
3717
|
+
}
|
|
3718
|
+
},
|
|
3719
|
+
)
|
|
3720
|
+
}
|
|
3721
|
+
|
|
3722
|
+
/** digest: the two statuses buildDigest reads, in rowid order. */
|
|
3723
|
+
projectCommitmentsForDigest() {
|
|
3724
|
+
return this._project(
|
|
3725
|
+
"SELECT status, action, due_at, done_at FROM commitments NOT INDEXED WHERE status IN ('open','done')",
|
|
3726
|
+
[],
|
|
3727
|
+
(row) => ({ status: row[0], action: row[1], dueAt: row[2] ?? undefined, doneAt: row[3] ?? undefined }),
|
|
3728
|
+
)
|
|
3729
|
+
}
|
|
3730
|
+
|
|
3731
|
+
/**
|
|
3732
|
+
* pet-brief: open commitments, with hasEvidence computed in SQL.
|
|
3733
|
+
*
|
|
3734
|
+
* confidenceOfCommitment() only asks whether the parsed evidence array is
|
|
3735
|
+
* non-empty, so the projection answers it without shipping 66k evidence
|
|
3736
|
+
* JSON strings to JS. The CASE mirrors mapCommitmentRow's JSON.parse +
|
|
3737
|
+
* Array.isArray semantics exactly, including corrupt JSON (json_valid=0 ->
|
|
3738
|
+
* parse falls back to [] -> no evidence).
|
|
3739
|
+
*/
|
|
3740
|
+
projectCommitmentsForPetBrief() {
|
|
3741
|
+
return this._project(
|
|
3742
|
+
"SELECT id, matter_id, creditor, action, due_at, CASE WHEN json_valid(evidence) THEN (CASE WHEN json_type(evidence) = 'array' AND json_array_length(evidence) > 0 THEN 1 ELSE 0 END) ELSE 0 END FROM commitments NOT INDEXED WHERE status = 'open'",
|
|
3743
|
+
[],
|
|
3744
|
+
(row) => ({
|
|
3745
|
+
id: row[0], matterId: row[1], creditor: row[2], action: row[3],
|
|
3746
|
+
dueAt: row[4] ?? undefined, status: 'open', hasEvidence: row[5] === 1,
|
|
3747
|
+
}),
|
|
3748
|
+
)
|
|
3749
|
+
}
|
|
3750
|
+
|
|
3751
|
+
/**
|
|
3752
|
+
* pet-brief facts: the top-N confirmed facts by confidence that buildPetBrief
|
|
3753
|
+
* would sort and slice to. matterIds restricts to the public matters (a
|
|
3754
|
+
* matter-less fact is always public, matching buildPetBrief).
|
|
3755
|
+
*/
|
|
3756
|
+
projectFactsForPetBrief({ limit = 10, minConfidence = 0.7, matterIds = null } = {}) {
|
|
3757
|
+
// listFacts() semantics: confirmed + not expired + not deleted. buildPetBrief
|
|
3758
|
+
// only ever sees those rows, so the projection must filter them in SQL or an
|
|
3759
|
+
// expired fact could displace a live one in the top-N.
|
|
3760
|
+
const where = ["status = 'confirmed'", 'expired_at IS NULL', 'deleted_at IS NULL', 'confidence >= ?']
|
|
3761
|
+
const params = [minConfidence]
|
|
3762
|
+
if (Array.isArray(matterIds)) {
|
|
3763
|
+
if (matterIds.length) {
|
|
3764
|
+
where.push('(matter_id IS NULL OR matter_id IN (' + matterIds.map(() => '?').join(',') + '))')
|
|
3765
|
+
params.push(...matterIds)
|
|
3766
|
+
} else {
|
|
3767
|
+
where.push('matter_id IS NULL')
|
|
3768
|
+
}
|
|
3769
|
+
}
|
|
3770
|
+
params.push(Math.max(1, Math.trunc(limit)))
|
|
3771
|
+
return this._project(
|
|
3772
|
+
'SELECT id, matter_id, subject, predicate, object, confidence FROM facts WHERE ' + where.join(' AND ') + ' ORDER BY confidence DESC, id LIMIT ?',
|
|
3773
|
+
params,
|
|
3774
|
+
(row) => ({ id: row[0], matterId: row[1] ?? undefined, subject: row[2], predicate: row[3], object: row[4], confidence: row[5] }),
|
|
3775
|
+
)
|
|
3776
|
+
}
|
|
3777
|
+
|
|
3778
|
+
/** pet-brief redactor candidates: subjects of every fact listFacts() returns. */
|
|
3779
|
+
projectFactSubjectCandidates() {
|
|
3780
|
+
return this._project(
|
|
3781
|
+
"SELECT subject FROM facts NOT INDEXED WHERE status = 'confirmed' AND expired_at IS NULL AND deleted_at IS NULL",
|
|
3782
|
+
[],
|
|
3783
|
+
(row) => row[0],
|
|
3784
|
+
)
|
|
3785
|
+
}
|
|
3786
|
+
|
|
3787
|
+
/** pet-brief redactor candidates: every commitment's creditor, all statuses. */
|
|
3788
|
+
projectCommitmentCreditorCandidates() {
|
|
3789
|
+
return this._project('SELECT DISTINCT creditor FROM commitments', [], (row) => row[0])
|
|
3790
|
+
}
|
|
3791
|
+
|
|
1573
3792
|
loadPreferences({ status, kind } = {}) {
|
|
1574
3793
|
const where = []
|
|
1575
3794
|
const params = []
|
|
@@ -1700,6 +3919,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1700
3919
|
}
|
|
1701
3920
|
|
|
1702
3921
|
save(snapshot) {
|
|
3922
|
+
this._assertWritable('save')
|
|
1703
3923
|
return this._transaction('IMMEDIATE', () => this._saveRows(snapshot))
|
|
1704
3924
|
}
|
|
1705
3925
|
|
|
@@ -1709,6 +3929,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1709
3929
|
* committed). `inside` runs inside the same transaction before the audit row.
|
|
1710
3930
|
*/
|
|
1711
3931
|
saveWithAudit(snapshot, audit, inside) {
|
|
3932
|
+
this._assertWritable('saveWithAudit')
|
|
1712
3933
|
return this._transaction('IMMEDIATE', () => {
|
|
1713
3934
|
this._saveRows(snapshot)
|
|
1714
3935
|
if (typeof inside === 'function') inside(this)
|
|
@@ -1717,6 +3938,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1717
3938
|
}
|
|
1718
3939
|
|
|
1719
3940
|
_saveRows(snapshot) {
|
|
3941
|
+
this._assertWritable('save')
|
|
1720
3942
|
const db = this.db
|
|
1721
3943
|
const newIds = idsFor(snapshot)
|
|
1722
3944
|
const baseline = this._baselineIds
|
|
@@ -1735,22 +3957,22 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1735
3957
|
// direct library use (e.g. importing or seeding a ledger).
|
|
1736
3958
|
for (const [table] of LEDGER_TABLES) db.exec(`DELETE FROM ${table}`)
|
|
1737
3959
|
}
|
|
1738
|
-
const m = db.prepare('INSERT OR REPLACE INTO matters VALUES (
|
|
3960
|
+
const m = db.prepare('INSERT OR REPLACE INTO matters(id,title,status,domain,secrecy,summary,participants,deadlines,open_questions,created_at,updated_at,client_id,project_id) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)')
|
|
1739
3961
|
for (const x of snapshot.matters ?? []) {
|
|
1740
|
-
m.run(x.id, x.title, x.status, x.domain, x.secrecy, x.summary ?? null, json(x.participants), json(x.deadlines), json(x.openQuestions), x.createdAt, x.updatedAt)
|
|
3962
|
+
m.run(x.id, x.title, x.status, x.domain, x.secrecy, x.summary ?? null, json(x.participants), json(x.deadlines), json(x.openQuestions), x.createdAt, x.updatedAt, x.clientId ?? null, x.projectId ?? null)
|
|
1741
3963
|
}
|
|
1742
3964
|
const f = db.prepare(`INSERT OR REPLACE INTO facts(id,matter_id,subject,predicate,object,recorded_at,expired_at,authority,confidence,source,evidence,status,valid_from,valid_to,supersedes,superseded_by,shadowed_by,last_seen_at,deleted_at,deleted_reason)
|
|
1743
3965
|
VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
|
|
1744
3966
|
for (const x of snapshot.facts ?? []) {
|
|
1745
3967
|
f.run(x.id, x.matterId ?? null, x.subject, x.predicate, x.object, x.recordedAt, x.expiredAt ?? null, x.authority, x.confidence, x.source ? json(x.source) : null, x.evidence ? json(x.evidence) : null, x.status, x.validFrom ?? null, x.validTo ?? null, x.supersedes ?? null, x.supersededBy ?? null, x.shadowedBy ?? null, x.lastSeenAt ?? null, x.deletedAt ?? null, x.deletedReason ?? null)
|
|
1746
3968
|
}
|
|
1747
|
-
const c = db.prepare(`INSERT OR REPLACE INTO commitments(id,matter_id,debtor,creditor,action,due_at,timezone,status,evidence,capability,done_at,reminder_offsets)
|
|
1748
|
-
VALUES (
|
|
3969
|
+
const c = db.prepare(`INSERT OR REPLACE INTO commitments(id,matter_id,debtor,creditor,action,due_at,timezone,status,evidence,capability,done_at,reminder_offsets,created_at)
|
|
3970
|
+
VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)`)
|
|
1749
3971
|
for (const x of snapshot.commitments ?? []) {
|
|
1750
3972
|
// A missing/undefined list stays NULL so a round-trip keeps the pre-0.2.0
|
|
1751
3973
|
// "no field" shape; an explicit [] is preserved as its own value.
|
|
1752
3974
|
const reminderOffsets = Array.isArray(x.reminderOffsets) ? JSON.stringify(x.reminderOffsets) : null
|
|
1753
|
-
c.run(x.id, x.matterId, x.debtor, x.creditor, x.action, x.dueAt ?? null, x.timezone, x.status, json(x.evidence), x.capability, x.doneAt ?? null, reminderOffsets)
|
|
3975
|
+
c.run(x.id, x.matterId, x.debtor, x.creditor, x.action, x.dueAt ?? null, x.timezone, x.status, json(x.evidence), x.capability, x.doneAt ?? null, reminderOffsets, x.createdAt ?? null)
|
|
1754
3976
|
}
|
|
1755
3977
|
const p = db.prepare('INSERT OR REPLACE INTO preferences VALUES (?,?,?,?,?,?,?,?,?,?,?,?)')
|
|
1756
3978
|
for (const x of snapshot.preferences ?? []) {
|
|
@@ -1784,3 +4006,28 @@ CREATE TABLE IF NOT EXISTS task_runs (
|
|
|
1784
4006
|
this.db.close()
|
|
1785
4007
|
}
|
|
1786
4008
|
}
|
|
4009
|
+
|
|
4010
|
+
/**
|
|
4011
|
+
* Open an existing database for lock-free reads (0.2.3 read path).
|
|
4012
|
+
*
|
|
4013
|
+
* The store is read-only (DatabaseSync readOnly): no DDL, no migration, no
|
|
4014
|
+
* journal-mode pragmas, no HOME instance lock — so it works while a long-lived
|
|
4015
|
+
* writer holds the lock, reading the last committed WAL snapshot. The schema is
|
|
4016
|
+
* asserted up front: a stale database throws E_SCHEMA_STALE (a writable command
|
|
4017
|
+
* has to migrate it first) and a future one throws E_SCHEMA_NEWER. The caller
|
|
4018
|
+
* decides whether to fall back to the writable path (bin's openReadStore).
|
|
4019
|
+
*
|
|
4020
|
+
* @param {string} path database file
|
|
4021
|
+
* @param {{ checkIntegrity?: boolean, busyTimeoutMs?: number }} [options]
|
|
4022
|
+
* @returns {SqliteStore}
|
|
4023
|
+
*/
|
|
4024
|
+
export function openReadStore(path, { checkIntegrity = false, busyTimeoutMs } = {}) {
|
|
4025
|
+
const store = new SqliteStore(path, { readOnly: true, checkIntegrity, busyTimeoutMs })
|
|
4026
|
+
try {
|
|
4027
|
+
store.assertSchemaCurrent()
|
|
4028
|
+
return store
|
|
4029
|
+
} catch (error) {
|
|
4030
|
+
try { store.close() } catch {}
|
|
4031
|
+
throw error
|
|
4032
|
+
}
|
|
4033
|
+
}
|