advisers 0.2.2 → 0.2.3

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/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,17 @@ 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
- export const SCHEMA_VERSION = 19
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. This is NOT the wire
28
+ * format: LedgerSnapshot.version stays 1 (see core/src/ledger.ts).
29
+ */
30
+ export const SCHEMA_VERSION = 20
31
+ /** The last schema built by the single-block legacy migration (0.2.2). */
32
+ const LEGACY_SCHEMA_VERSION = 19
22
33
  const DEFAULT_BUSY_TIMEOUT_MS = 5000
23
34
  const OPEN_RETRIES = 6
24
35
  const BUSY_ERRCODES = new Set([5, 6]) // SQLITE_BUSY, SQLITE_LOCKED
@@ -104,6 +115,44 @@ export class DatabaseLockedError extends Error {
104
115
  }
105
116
  }
106
117
 
118
+ /**
119
+ * Version of this CLI, recorded in meta.schema_migrated_app for support. Read
120
+ * from the package manifest so it cannot drift from the released version.
121
+ */
122
+ const APP_VERSION = (() => {
123
+ try {
124
+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
125
+ return typeof pkg?.version === 'string' ? pkg.version : '0.0.0'
126
+ } catch {
127
+ return '0.0.0'
128
+ }
129
+ })()
130
+
131
+ /** E_SCHEMA_STALE: the on-disk schema is older than this CLI (read path). */
132
+ function schemaStaleError(path, version) {
133
+ const found = version === null || version === undefined ? 'unknown' : `v${version}`
134
+ const error = new Error(
135
+ `E_SCHEMA_STALE: database schema at ${path} is ${found} but this CLI expects v${SCHEMA_VERSION}; ` +
136
+ 'if another advisers process is upgrading it, retry in a moment; otherwise run a writable ' +
137
+ 'command (for example `advisers doctor`) to migrate it first.',
138
+ )
139
+ error.name = 'SchemaStaleError'
140
+ error.code = 'E_SCHEMA_STALE'
141
+ error.schemaVersion = version ?? null
142
+ error.expected = SCHEMA_VERSION
143
+ return error
144
+ }
145
+
146
+ /** E_SCHEMA_NEWER: the on-disk schema is newer than this CLI (fail closed). */
147
+ function schemaNewerError(path, version) {
148
+ const error = new Error(`database schema v${version} is newer than this CLI (v${SCHEMA_VERSION}); upgrade advisers before opening ${path}`)
149
+ error.name = 'SchemaNewerError'
150
+ error.code = 'E_SCHEMA_NEWER'
151
+ error.schemaVersion = Number(version)
152
+ error.expected = SCHEMA_VERSION
153
+ return error
154
+ }
155
+
107
156
  function readEnvMs(name, fallback, max) {
108
157
  const raw = process.env[name]
109
158
  if (raw === undefined || raw === null || String(raw).trim() === '') return fallback
@@ -371,6 +420,21 @@ function idsFor(snapshot) {
371
420
  return ids
372
421
  }
373
422
 
423
+ // ---------------------------------------------------------------------------
424
+ // Schema v20 (0.2.3 persistence v2): the migration ledger plus the per-version
425
+ // step table. The three indexes are new persisted objects too, but the reason
426
+ // this is a schema bump is the new table + the step framework (not the indexes
427
+ // alone: secondary indexes are normally layout-only, see INDEXES).
428
+ // ---------------------------------------------------------------------------
429
+ const SCHEMA_MIGRATIONS_DDL = `CREATE TABLE IF NOT EXISTS schema_migrations (
430
+ version INTEGER PRIMARY KEY,
431
+ name TEXT NOT NULL,
432
+ applied_at TEXT NOT NULL,
433
+ duration_ms INTEGER NOT NULL,
434
+ backup_path TEXT
435
+ );
436
+ `
437
+
374
438
  const SCHEMA = `
375
439
  CREATE TABLE IF NOT EXISTS matters (
376
440
  id TEXT PRIMARY KEY, title TEXT NOT NULL, status TEXT NOT NULL, domain TEXT NOT NULL,
@@ -478,7 +542,7 @@ CREATE TABLE IF NOT EXISTS calendar_events (
478
542
  source TEXT, imported_at TEXT NOT NULL
479
543
  );
480
544
  CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
481
- `
545
+ ${SCHEMA_MIGRATIONS_DDL}`
482
546
 
483
547
  // ---------------------------------------------------------------------------
484
548
  // Full-text search (schema v19; 2026-11-17 performance audit round 2, P2-6).
@@ -556,6 +620,13 @@ function ftsDdl(tokenizer) {
556
620
  * the 2026-11-17 performance audit (nudges/facts/deliveries/calendar_events/
557
621
  * task_runs/sessions/model_calls/preferences/commitments).
558
622
  */
623
+ /** v20 indexes: FTS seq early-stop, fact identity lookup, candidate status. */
624
+ const V20_INDEXES = `
625
+ CREATE INDEX IF NOT EXISTS idx_turns_seq ON turns(seq);
626
+ CREATE INDEX IF NOT EXISTS idx_facts_identity ON facts(subject, predicate, matter_id);
627
+ CREATE INDEX IF NOT EXISTS idx_memory_candidates_status ON memory_candidates(status);
628
+ `
629
+
559
630
  const INDEXES = `
560
631
  CREATE INDEX IF NOT EXISTS idx_nudges_commitment_at ON nudges(commitment_id, at);
561
632
  CREATE INDEX IF NOT EXISTS idx_nudges_local_day_level ON nudges(local_day, level);
@@ -569,8 +640,26 @@ CREATE INDEX IF NOT EXISTS idx_deliveries_created ON deliveries(created_at);
569
640
  CREATE INDEX IF NOT EXISTS idx_task_runs_created ON task_runs(created_at);
570
641
  CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at);
571
642
  CREATE INDEX IF NOT EXISTS idx_model_calls_created ON model_calls(created_at);
572
- `
643
+ ${V20_INDEXES}`
644
+
573
645
 
646
+ /**
647
+ * Per-version migration steps (schema v20+). Each step must be idempotent
648
+ * (IF NOT EXISTS / INSERT OR REPLACE) because it can be retried after a crash
649
+ * that rolled the transaction back. migrate() runs every step with
650
+ * version > current inside one BEGIN IMMEDIATE, records name/duration/backup
651
+ * in schema_migrations, and only then bumps meta.schema_version.
652
+ */
653
+ const MIGRATIONS = [
654
+ {
655
+ version: 20,
656
+ name: 'incremental-writes-readonly-reads',
657
+ up(store) {
658
+ store.db.exec(SCHEMA_MIGRATIONS_DDL)
659
+ store.db.exec(V20_INDEXES)
660
+ },
661
+ },
662
+ ]
574
663
  const json = (v) => JSON.stringify(v ?? [])
575
664
  const parse = (v, fallback = []) => {
576
665
  if (v == null) return fallback
@@ -667,11 +756,275 @@ const LEDGER_TABLE_LOADERS = {
667
756
  routes: { table: 'routes', routes: true },
668
757
  }
669
758
 
759
+
760
+ // ---------------------------------------------------------------------------
761
+ // Incremental-write row codecs (0.2.3 persistence v2 phase 2).
762
+ //
763
+ // _saveRows() below is the historical full-snapshot writer and stays the
764
+ // import/seed path. The targeted insert*/update* methods must produce exactly
765
+ // the same column bytes as _saveRows(), so one ENTITY_SPECS table per entity
766
+ // lists the column + codec of every persisted field. Both paths therefore
767
+ // cannot drift silently: test/incremental-write.test.js compares the old
768
+ // load+save result with the targeted-write result row by row.
769
+ //
770
+ // Only the four ledger entities touched by the 0.2.3 write commands are
771
+ // covered; 0.3 replaces this with core's ENTITY_SPECS single source of truth.
772
+ // ---------------------------------------------------------------------------
773
+ const encodeText = (v) => (v === undefined || v === null ? null : String(v))
774
+ const encodeInt = (v) => Math.trunc(Number(v))
775
+ const encodeReal = (v) => Number(v)
776
+ const encodeJson = (v) => json(v)
777
+ const encodeJsonNullable = (v) => (v === undefined || v === null ? null : json(v))
778
+ const encodeReminderOffsets = (v) => (v === undefined || v === null ? null : JSON.stringify(v))
779
+ const CODECS = {
780
+ text: encodeText,
781
+ int: encodeInt,
782
+ real: encodeReal,
783
+ json: encodeJson,
784
+ 'json-nullable': encodeJsonNullable,
785
+ reminder: encodeReminderOffsets,
786
+ }
787
+
788
+ const ENTITY_SPECS = {
789
+ matters: {
790
+ table: 'matters',
791
+ key: 'id',
792
+ map: mapMatterRow,
793
+ columns: {
794
+ id: ['id', 'text'], title: ['title', 'text'], status: ['status', 'text'], domain: ['domain', 'text'],
795
+ secrecy: ['secrecy', 'int'], summary: ['summary', 'text'], participants: ['participants', 'json'],
796
+ deadlines: ['deadlines', 'json'], openQuestions: ['open_questions', 'json'],
797
+ createdAt: ['created_at', 'text'], updatedAt: ['updated_at', 'text'],
798
+ },
799
+ },
800
+ facts: {
801
+ table: 'facts',
802
+ key: 'id',
803
+ map: mapFactRow,
804
+ columns: {
805
+ id: ['id', 'text'], matterId: ['matter_id', 'text'], subject: ['subject', 'text'],
806
+ predicate: ['predicate', 'text'], object: ['object', 'text'], recordedAt: ['recorded_at', 'text'],
807
+ expiredAt: ['expired_at', 'text'], authority: ['authority', 'text'], confidence: ['confidence', 'real'],
808
+ source: ['source', 'json-nullable'], evidence: ['evidence', 'json-nullable'], status: ['status', 'text'],
809
+ validFrom: ['valid_from', 'text'], validTo: ['valid_to', 'text'], supersedes: ['supersedes', 'text'],
810
+ supersededBy: ['superseded_by', 'text'], shadowedBy: ['shadowed_by', 'text'],
811
+ lastSeenAt: ['last_seen_at', 'text'], deletedAt: ['deleted_at', 'text'], deletedReason: ['deleted_reason', 'text'],
812
+ },
813
+ },
814
+ commitments: {
815
+ table: 'commitments',
816
+ key: 'id',
817
+ map: mapCommitmentRow,
818
+ columns: {
819
+ id: ['id', 'text'], matterId: ['matter_id', 'text'], debtor: ['debtor', 'text'], creditor: ['creditor', 'text'],
820
+ action: ['action', 'text'], dueAt: ['due_at', 'text'], timezone: ['timezone', 'text'], status: ['status', 'text'],
821
+ evidence: ['evidence', 'json'], capability: ['capability', 'text'], doneAt: ['done_at', 'text'],
822
+ reminderOffsets: ['reminder_offsets', 'reminder'],
823
+ },
824
+ },
825
+ preferences: {
826
+ table: 'preferences',
827
+ key: 'id',
828
+ map: mapPreferenceRow,
829
+ columns: {
830
+ id: ['id', 'text'], kind: ['kind', 'text'], statement: ['statement', 'text'], scope: ['scope', 'json'],
831
+ source: ['source', 'json'], evidence: ['evidence', 'json'], confidence: ['confidence', 'real'],
832
+ status: ['status', 'text'], validFrom: ['valid_from', 'text'], lastConfirmed: ['last_confirmed', 'text'],
833
+ expiresAt: ['expires_at', 'text'], priority: ['priority', 'text'],
834
+ },
835
+ },
836
+ }
837
+
838
+ function encodeEntityValue(codec, value) {
839
+ const encode = CODECS[codec]
840
+ if (!encode) throw new Error(`unknown entity column codec: ${codec}`)
841
+ return encode(value)
842
+ }
843
+
844
+ /** Tables whose row counts are sampled to verify a pre-migration backup. */
845
+ const BACKUP_SAMPLE_TABLES = ['matters', 'facts', 'commitments', 'preferences', 'audit']
846
+ // ---------------------------------------------------------------------------
847
+ // WAL status / recovery (robustness audit 2026-11-17 P1-6).
848
+ //
849
+ // SQLite's documented recovery semantics: a WAL whose header is invalid, whose
850
+ // last frame is torn, or whose checksums do not verify is treated as if it
851
+ // contained no transactions. The database still opens (that is safe for the
852
+ // main file) but every transaction committed since the last checkpoint that
853
+ // only lived in the WAL is silently lost, and `quick_check` still says ok.
854
+ //
855
+ // This pre-open check classifies the sidecar BEFORE SQLite can ignore it:
856
+ // - invalid (bad magic/version/page-size/header checksum, or a stale first
857
+ // frame): preserve the bytes as state.db-wal.corrupt-<ts>, move the unusable
858
+ // WAL aside (and the rebuildable -shm cache), then warn loudly and record a
859
+ // quick_check of the surviving database;
860
+ // - truncated (valid header, size not a whole number of frames): keep the WAL
861
+ // so SQLite recovers its valid prefix, copy it aside as evidence, and warn
862
+ // that frames after the tear may be lost;
863
+ // - ok / absent / empty: no warning (the common case has no extra I/O cost).
864
+ // No database bytes are ever deleted: the preserved copy is the recovery path.
865
+ // `inspectWalStatus()` is also exported so bin/doctor can report the sidecar
866
+ // without opening the store (Wave 1 `doctor --check-db` / `audit --check-db`).
867
+ // ---------------------------------------------------------------------------
868
+ const WAL_HEADER_SIZE = 32
869
+ const WAL_FRAME_HEADER_SIZE = 24
870
+ const WAL_VERSION = 3007000
871
+ const WAL_MAGIC_LE = 0x377f0682
872
+ const WAL_MAGIC_BE = 0x377f0683
873
+ /** Suffix of a preserved copy of a WAL file SQLite cannot use (0600). */
874
+ export const WAL_CORRUPT_SUFFIX = '-wal.corrupt-'
875
+
876
+ /** SQLite WAL checksum: cumulative s1/s2 over 32-bit words (big- or little-endian). */
877
+ function walChecksum(bytes, bigEndian, start1 = 0, start2 = 0) {
878
+ let s1 = start1 >>> 0
879
+ let s2 = start2 >>> 0
880
+ for (let offset = 0; offset + 8 <= bytes.length; offset += 8) {
881
+ const first = bigEndian ? bytes.readUInt32BE(offset) : bytes.readUInt32LE(offset)
882
+ const second = bigEndian ? bytes.readUInt32BE(offset + 4) : bytes.readUInt32LE(offset + 4)
883
+ s1 = (s1 + first + s2) >>> 0
884
+ s2 = (s2 + second + s1) >>> 0
885
+ }
886
+ return [s1 >>> 0, s2 >>> 0]
887
+ }
888
+
889
+ function readAtSync(file, position, length) {
890
+ const fd = openSync(file, 'r')
891
+ try {
892
+ const buffer = Buffer.alloc(length)
893
+ const bytesRead = readSync(fd, buffer, 0, length, position)
894
+ return buffer.subarray(0, bytesRead)
895
+ } finally {
896
+ try { closeSync(fd) } catch {}
897
+ }
898
+ }
899
+
900
+ function corruptStamp(now) {
901
+ return new Date(now).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z')
902
+ }
903
+
904
+ /** Report the state of <db>-wal without opening SQLite or modifying anything. */
905
+ export function inspectWalStatus(dbPath) {
906
+ const path = `${dbPath}-wal`
907
+ const report = { path, present: false, bytes: 0, status: 'absent', frames: 0, pageSize: null, header: null, reason: null, warning: null }
908
+ if (!dbPath || dbPath === ':memory:') { report.status = 'memory'; return report }
909
+ let stat
910
+ try { stat = statSync(path) } catch (error) {
911
+ 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` }
912
+ return report
913
+ }
914
+ report.present = true
915
+ report.bytes = stat.size
916
+ if (!stat.isFile()) { report.status = 'invalid'; report.reason = 'not-a-regular-file'; return report }
917
+ if (stat.size === 0) { report.status = 'empty'; return report }
918
+ if (stat.size < WAL_HEADER_SIZE) { report.status = 'invalid'; report.reason = `truncated header (${stat.size} of ${WAL_HEADER_SIZE} bytes)`; return report }
919
+ let header
920
+ try { header = readAtSync(path, 0, WAL_HEADER_SIZE) } catch (error) { report.status = 'unreadable'; report.reason = String(error?.message ?? error); return report }
921
+ if (header.length < WAL_HEADER_SIZE) { report.status = 'invalid'; report.reason = 'truncated header'; return report }
922
+ const magic = header.readUInt32BE(0)
923
+ const version = header.readUInt32BE(4)
924
+ const pageSize = header.readUInt32BE(8)
925
+ 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 }
926
+ if (version !== WAL_VERSION) { report.status = 'invalid'; report.reason = `unsupported WAL format version ${version}`; return report }
927
+ if (!Number.isInteger(pageSize) || pageSize < 512 || pageSize > 65536 || (pageSize & (pageSize - 1)) !== 0) { report.status = 'invalid'; report.reason = `invalid WAL page size ${pageSize}`; return report }
928
+ const bigEndian = magic === WAL_MAGIC_BE
929
+ const [checksum1, checksum2] = walChecksum(header.subarray(0, 24), bigEndian)
930
+ if (checksum1 !== header.readUInt32BE(24) || checksum2 !== header.readUInt32BE(28)) { report.status = 'invalid'; report.reason = 'WAL header checksum mismatch'; return report }
931
+ report.pageSize = pageSize
932
+ report.header = { magic: bigEndian ? 'be' : 'le', version, pageSize }
933
+ // A writer may be appending right now (direct library use has no instance
934
+ // lock). Only classify a size-based tear when the size is stable; otherwise
935
+ // report 'changing' and stay quiet instead of warning about a false tear.
936
+ let stable
937
+ try { stable = statSync(path) } catch (error) { report.status = 'unreadable'; report.reason = String(error?.message ?? error); return report }
938
+ if (stable.size !== stat.size) { report.status = 'changing'; return report }
939
+ const frameSize = WAL_FRAME_HEADER_SIZE + pageSize
940
+ const payloadBytes = stat.size - WAL_HEADER_SIZE
941
+ report.frames = Math.floor(payloadBytes / frameSize)
942
+ if (payloadBytes % frameSize !== 0) {
943
+ report.status = 'truncated'
944
+ report.reason = 'torn-frame'
945
+ 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`
946
+ return report
947
+ }
948
+ if (report.frames > 0) {
949
+ try {
950
+ const firstFrame = readAtSync(path, WAL_HEADER_SIZE, WAL_FRAME_HEADER_SIZE)
951
+ if (firstFrame.length === WAL_FRAME_HEADER_SIZE) {
952
+ const salt1 = firstFrame.readUInt32BE(8)
953
+ const salt2 = firstFrame.readUInt32BE(12)
954
+ if (salt1 !== header.readUInt32BE(16) || salt2 !== header.readUInt32BE(20)) {
955
+ report.status = 'invalid'
956
+ report.reason = 'stale first frame (WAL salt mismatch)'
957
+ return report
958
+ }
959
+ }
960
+ } catch {}
961
+ }
962
+ report.status = 'ok'
963
+ return report
964
+ }
965
+
966
+ /** Copy a WAL sidecar next to the database as evidence (0600, fsynced). */
967
+ function preserveWalCopy(dbPath, report, { now = Date.now() } = {}) {
968
+ const backup = `${dbPath}${WAL_CORRUPT_SUFFIX}${corruptStamp(now)}`
969
+ try {
970
+ copyFileWithRetrySync(report.path, backup, { mode: 0o600 })
971
+ fsyncFileSync(backup)
972
+ return { backup, error: null }
973
+ } catch (error) {
974
+ return { backup: null, error }
975
+ }
976
+ }
977
+
978
+ /**
979
+ * Inspect (and, for a writable open, quarantine) a WAL before SQLite sees it.
980
+ * Returns the inspection report plus `backup` / `quarantined` / `warning`.
981
+ * For readOnly opens nothing is written: the DB is only reported on.
982
+ */
983
+ export function prepareWalForOpen(dbPath, { readOnly = false, now = Date.now() } = {}) {
984
+ const report = inspectWalStatus(dbPath)
985
+ if (report.status !== 'invalid' && report.status !== 'truncated') return report
986
+ if (readOnly) {
987
+ 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'
988
+ if (report.status === 'invalid') {
989
+ 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.`
990
+ } else {
991
+ report.warning = `${report.warning}. Read-only open left it untouched; run 'advisers doctor --check-db' to preserve it.`
992
+ }
993
+ return report
994
+ }
995
+ const preserved = preserveWalCopy(dbPath, report, { now })
996
+ report.backup = preserved.backup
997
+ report.preserveError = preserved.error ? String(preserved.error?.message ?? preserved.error) : null
998
+ if (report.status === 'invalid' && preserved.backup) {
999
+ try {
1000
+ rmWithRetrySync(report.path)
1001
+ try { if (existsSync(`${dbPath}-shm`)) rmWithRetrySync(`${dbPath}-shm`) } catch {}
1002
+ report.quarantined = true
1003
+ } catch (error) {
1004
+ report.quarantined = false
1005
+ report.preserveError = String(error?.message ?? error)
1006
+ }
1007
+ }
1008
+ const preservedText = report.backup
1009
+ ? ` the file was preserved as ${report.backup}.`
1010
+ : ` the file could not be preserved (${report.preserveError ?? 'unknown error'}).`
1011
+ if (report.status === 'invalid') {
1012
+ 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.`
1013
+ } else {
1014
+ report.warning = `${report.warning}.${preservedText} Run 'advisers doctor' before relying on the most recent writes.`
1015
+ }
1016
+ return report
1017
+ }
1018
+
670
1019
  export class SqliteStore {
671
1020
  constructor(path, { readOnly = false, checkIntegrity = false, busyTimeoutMs = Number(process.env.ADVISERS_SQLITE_BUSY_TIMEOUT_MS) || DEFAULT_BUSY_TIMEOUT_MS } = {}) {
672
1021
  this.path = path
673
1022
  this.busyTimeoutMs = busyTimeoutMs
1023
+ // 0.2.3 read path: a read-only store never runs DDL/migrate/journal-mode
1024
+ // pragmas and refuses every write method with E_READ_ONLY (see read()).
1025
+ this.readOnly = Boolean(readOnly)
674
1026
  this._transactionDepth = 0
1027
+ this._readDepth = 0
675
1028
  this._baselineIds = null
676
1029
  this._fullLoad = false
677
1030
  // FTS5 state (schema v19): which indexes exist and which tokenizer built
@@ -680,22 +1033,63 @@ export class SqliteStore {
680
1033
  this.ftsTokenizer = null
681
1034
  this.ftsWarning = null
682
1035
  this._ftsTables = new Set()
1036
+ // P1-5: searchTurns()/searchSummaries() set these when FTS and LIKE
1037
+ // disagree; verifyFtsIntegrity() fills ftsIntegrityReport for doctor.
1038
+ this._ftsBroken = false
1039
+ this._ftsWarned = false
1040
+ this.ftsIntegrityWarning = null
1041
+ this.ftsIntegrityReport = null
683
1042
  // P2-2 (0.2.1): an existing 0-byte file is treated as corrupt instead of a
684
1043
  // brand-new database. Before this, SQLite turned it into an empty schema and
685
1044
  // every command reported "no data" while silently rebuilding the ledger.
686
1045
  assertDatabaseFileUsable(path)
1046
+ // P1-6: classify (and, for writable opens, quarantine) an unusable WAL
1047
+ // before SQLite opens the file and treats it as empty. `walStatus` is kept
1048
+ // on the store so doctor/audit can report it (see walReport()).
1049
+ this.walStatus = null
687
1050
  try {
1051
+ this.walStatus = prepareWalForOpen(path, { readOnly })
1052
+ if (this.walStatus.warning) {
1053
+ try { console.warn(`advisers: warning: ${this.walStatus.warning}`) } catch {}
1054
+ }
688
1055
  this.db = readOnly ? new DatabaseSync(path, { readOnly: true }) : new DatabaseSync(path)
689
1056
  // P0-1: sqlite only applies busy_timeout to statements that run after the
690
1057
  // pragma is set; concurrent first-opens used to fail on journal_mode=WAL
691
1058
  // because busy_timeout was set afterwards.
692
1059
  this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(Number(busyTimeoutMs) || 0))}`)
1060
+ if (this.walStatus.quarantined) {
1061
+ // The pre-check moved an unusable WAL aside; verify that the surviving
1062
+ // main database is structurally sound (this is the one open where the
1063
+ // O(db) quick_check cost is justified).
1064
+ try {
1065
+ const recovered = this.db.prepare('PRAGMA quick_check').get()
1066
+ this.walStatus.recovery = { quickCheck: String(recovered?.quick_check ?? 'unknown') }
1067
+ if (this.walStatus.recovery.quickCheck !== 'ok') {
1068
+ try { console.warn(`advisers: warning: quick_check after WAL recovery reported '${this.walStatus.recovery.quickCheck}'`) } catch {}
1069
+ }
1070
+ } catch (error) {
1071
+ this.walStatus.recovery = { error: String(error?.message ?? error) }
1072
+ }
1073
+ }
693
1074
  if (readOnly) {
694
1075
  this._initFtsState()
695
1076
  if (checkIntegrity) this.assertIntegrity()
696
1077
  return
697
1078
  }
698
1079
  this.enableWal()
1080
+ // A torn WAL was preserved by the pre-open check. Fold its valid prefix
1081
+ // into the main database and truncate the sidecar so subsequent opens are
1082
+ // clean; the preserved copy remains available for forensics.
1083
+ if (this.walStatus?.status === 'truncated' && this.walStatus.backup) {
1084
+ try {
1085
+ this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)')
1086
+ this.walStatus.recovered = true
1087
+ this.walStatus.current = inspectWalStatus(path)
1088
+ } catch (error) {
1089
+ this.walStatus.recovered = false
1090
+ this.walStatus.recoveryError = String(error?.message ?? error)
1091
+ }
1092
+ }
699
1093
  this.db.exec('PRAGMA secure_delete = ON')
700
1094
  this.db.exec('PRAGMA synchronous = NORMAL')
701
1095
  this.initializeSchema()
@@ -709,6 +1103,75 @@ export class SqliteStore {
709
1103
  }
710
1104
  }
711
1105
 
1106
+ // -------------------------------------------------------------------------
1107
+ // Read-only access (0.2.3 read path; 03-design-persistence-v2.md §4).
1108
+ //
1109
+ // A read-only store never enables WAL, never runs DDL/migrate and never
1110
+ // takes the HOME instance lock (that lock lives in bin/ and only protects
1111
+ // writers), so pure-read commands work while another process holds the write
1112
+ // lock. The connection reads a committed WAL snapshot: an uncommitted writer
1113
+ // transaction is invisible and does not block the reader.
1114
+ // -------------------------------------------------------------------------
1115
+
1116
+ /** meta.schema_version, or null when the meta table/row does not exist. */
1117
+ schemaVersion() {
1118
+ try {
1119
+ const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
1120
+ return row ? Number(row.value) : null
1121
+ } catch {
1122
+ return null
1123
+ }
1124
+ }
1125
+
1126
+ /** Throw E_SCHEMA_STALE / E_SCHEMA_NEWER unless this database is current. */
1127
+ assertSchemaCurrent() {
1128
+ const version = this.schemaVersion()
1129
+ if (version === SCHEMA_VERSION) return version
1130
+ if (version !== null && version > SCHEMA_VERSION) throw schemaNewerError(this.path, version)
1131
+ throw schemaStaleError(this.path, version)
1132
+ }
1133
+
1134
+ /** Throw E_READ_ONLY for any write attempted on a read-only store. */
1135
+ _assertWritable(operation = 'write') {
1136
+ if (!this.readOnly) return
1137
+ 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`)
1138
+ error.name = 'ReadOnlyStoreError'
1139
+ error.code = 'E_READ_ONLY'
1140
+ error.operation = operation
1141
+ throw error
1142
+ }
1143
+
1144
+ /** Directed row writes are only valid inside mutate()/transaction(). */
1145
+ _assertInWriteTransaction(operation) {
1146
+ this._assertWritable(operation)
1147
+ if (this._transactionDepth > 0) return
1148
+ const error = new Error(`E_TX_REQUIRED: ${operation} must run inside SqliteStore.mutate() or transaction() (${this.path})`)
1149
+ error.name = 'TransactionRequiredError'
1150
+ error.code = 'E_TX_REQUIRED'
1151
+ throw error
1152
+ }
1153
+
1154
+ /**
1155
+ * Run fn inside one read transaction so several SELECTs see the same WAL
1156
+ * snapshot (multi-query commands: status/receipt/deliveries/doctor/export).
1157
+ * A read() nested inside a write transaction joins that transaction.
1158
+ */
1159
+ read(fn) {
1160
+ if (typeof fn !== 'function') throw new TypeError('read requires a function')
1161
+ if (this._transactionDepth > 0 || this._readDepth > 0) return fn(this)
1162
+ this.db.exec('BEGIN DEFERRED')
1163
+ this._readDepth++
1164
+ try {
1165
+ const result = fn(this)
1166
+ this.db.exec('COMMIT')
1167
+ return result
1168
+ } catch (error) {
1169
+ try { this.db.exec('ROLLBACK') } catch {}
1170
+ throw error
1171
+ } finally {
1172
+ this._readDepth--
1173
+ }
1174
+ }
712
1175
  /** Full-database integrity check; explicit because it is O(database size). */
713
1176
  assertIntegrity() {
714
1177
  const row = this.db.prepare('PRAGMA quick_check').get()
@@ -717,8 +1180,37 @@ export class SqliteStore {
717
1180
  return verdict
718
1181
  }
719
1182
 
1183
+ /**
1184
+ * Aggregate integrity report for `doctor --check-db` / `audit --check-db`
1185
+ * (Wave 1 contract). quick_check is O(db) and the FTS check is O(index), so
1186
+ * both are opt-in; the WAL report is cheap and always included.
1187
+ */
1188
+ integrityReport({ quickCheck = true, fts = false } = {}) {
1189
+ const report = { ok: true, path: this.path, schemaVersion: null, quickCheck: null, wal: null, fts: null, errors: [] }
1190
+ try { report.schemaVersion = this.getMeta('schema_version') } catch (error) { report.errors.push(`cannot read schema_version: ${String(error?.message ?? error).slice(0, 160)}`) }
1191
+ if (quickCheck) {
1192
+ try {
1193
+ const verdict = String(this.db.prepare('PRAGMA quick_check').get()?.quick_check ?? 'unknown')
1194
+ report.quickCheck = { ok: verdict === 'ok', verdict }
1195
+ if (verdict !== 'ok') { report.ok = false; report.errors.push(`PRAGMA quick_check: ${verdict}`) }
1196
+ } catch (error) {
1197
+ report.quickCheck = { ok: false, error: String(error?.message ?? error).slice(0, 200) }
1198
+ report.ok = false
1199
+ report.errors.push(`PRAGMA quick_check failed: ${report.quickCheck.error}`)
1200
+ }
1201
+ }
1202
+ report.wal = this.walReport()
1203
+ if (!report.wal.ok) { report.ok = false; if (report.wal.initial?.warning) report.errors.push(report.wal.initial.warning) }
1204
+ if (fts) {
1205
+ report.fts = this.verifyFtsIntegrity()
1206
+ if (!report.fts.ok) { report.ok = false; if (report.fts.warning) report.errors.push(report.fts.warning) }
1207
+ }
1208
+ return report
1209
+ }
1210
+
720
1211
  /** WAL is persistent; skip the switch when already enabled and retry on busy. */
721
1212
  enableWal() {
1213
+ this._assertWritable('enableWal')
722
1214
  if (!this.path || this.path === ':memory:') return 'memory'
723
1215
  const current = String(this.db.prepare('PRAGMA journal_mode').get()?.journal_mode ?? '').toLowerCase()
724
1216
  if (current === 'wal' || current === 'memory') return current
@@ -739,6 +1231,12 @@ export class SqliteStore {
739
1231
  }
740
1232
 
741
1233
  initializeSchema() {
1234
+ this._assertWritable('initializeSchema')
1235
+ // P2-9: migration backups must be taken OUTSIDE the write transaction --
1236
+ // a 'wal_checkpoint(TRUNCATE)' inside BEGIN IMMEDIATE fails with 'database
1237
+ // table is locked', and copying the main file without folding the WAL can
1238
+ // silently omit committed rows. Read the old version and back up first.
1239
+ this._migrationBackup = this._prepareMigrationBackup()
742
1240
  this._transaction('IMMEDIATE', () => {
743
1241
  this.db.exec(SCHEMA)
744
1242
  this.migrate()
@@ -830,11 +1328,185 @@ export class SqliteStore {
830
1328
  return tokenizer
831
1329
  }
832
1330
 
1331
+ /**
1332
+ * Report the WAL/shm state and whether this connection can checkpoint.
1333
+ * `initial` is the pre-open inspection (see inspectWalStatus above); a fresh
1334
+ * `current` read lets a long-lived store (mcp/ui) be diagnosed too.
1335
+ */
1336
+ walReport() {
1337
+ const report = {
1338
+ path: this.path,
1339
+ initial: this.walStatus ?? { status: 'absent', present: false },
1340
+ current: inspectWalStatus(this.path),
1341
+ }
1342
+ try { report.journalMode = String(this.db.prepare('PRAGMA journal_mode').get()?.journal_mode ?? '') } catch (error) { report.journalModeError = String(error?.message ?? error) }
1343
+ try {
1344
+ const checkpoint = this.db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get()
1345
+ report.checkpoint = { busy: Number(checkpoint?.busy ?? 0) !== 0, log: Number(checkpoint?.log ?? 0), checkpointed: Number(checkpoint?.checkpointed ?? 0) }
1346
+ } catch (error) { report.checkpoint = { error: String(error?.message ?? error) } }
1347
+ const bad = (status) => ['invalid', 'truncated', 'unreadable'].includes(String(status))
1348
+ // A WAL that was preserved and then quarantined/checkpointed is reported as
1349
+ // recovered, but the maintenance check still fails once: data committed
1350
+ // after the last checkpoint may have been lost. The next open is clean.
1351
+ report.recovered = Boolean(
1352
+ report.initial.preserveError == null &&
1353
+ (report.initial.quarantined === true ||
1354
+ (report.initial.backup && (report.initial.recovered === true || !bad(report.current.status)))),
1355
+ )
1356
+ report.ok = !bad(report.current.status) && !bad(report.initial.status) && report.initial.preserveError == null
1357
+ return report
1358
+ }
1359
+
1360
+ /**
1361
+ * Verify the two FTS5 indexes against their source tables (robustness audit
1362
+ * 2026-11-17 P1-5). A desynchronised index makes search silently return
1363
+ * fewer rows than a LIKE scan; this is the explicit check that doctor and
1364
+ * audit --check-db should surface (O(index), so never run on every open).
1365
+ *
1366
+ * Checks per index: table present, the three sync triggers present, FTS5
1367
+ * 'integrity-check' (catches malformed/desynced segments), source vs index
1368
+ * (shadow docsize) row counts, and a deterministic rowid sample in both
1369
+ * directions. On a non-ok result the store also marks its FTS path unusable
1370
+ * (`searchTurns`/`searchSummaries` then use LIKE until a rebuild).
1371
+ */
1372
+ verifyFtsIntegrity({ sampleSize = 100 } = {}) {
1373
+ this._initFtsState()
1374
+ const report = {
1375
+ ok: true,
1376
+ state: 'ok',
1377
+ tokenizer: this.ftsTokenizer,
1378
+ tables: {},
1379
+ triggers: { expected: FTS_TRIGGER_NAMES.slice(), missing: [] },
1380
+ checkedAt: new Date().toISOString(),
1381
+ errors: [],
1382
+ warning: null,
1383
+ repair: 'advisers audit --rebuild-fts',
1384
+ }
1385
+ let existingTriggers = new Set()
1386
+ try {
1387
+ existingTriggers = new Set(this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'trigger'").all().map((row) => row.name))
1388
+ } catch (error) {
1389
+ report.errors.push(`cannot list triggers: ${String(error?.message ?? error).slice(0, 200)}`)
1390
+ }
1391
+ const triggerMap = {
1392
+ turns_fts: ['turns_ai', 'turns_ad', 'turns_au'],
1393
+ summaries_fts: ['summaries_ai', 'summaries_ad', 'summaries_au'],
1394
+ }
1395
+ const sourceMap = {
1396
+ turns_fts: { table: 'turns' },
1397
+ summaries_fts: { table: 'session_summaries' },
1398
+ }
1399
+ let anyTable = false
1400
+ let inconsistent = false
1401
+ let missingTable = false
1402
+ for (const table of FTS_TABLE_NAMES) {
1403
+ const source = sourceMap[table]
1404
+ const info = {
1405
+ table,
1406
+ sourceTable: source.table,
1407
+ exists: false,
1408
+ triggers: { expected: triggerMap[table].slice(), missing: [] },
1409
+ integrityCheck: 'skipped',
1410
+ sourceCount: null,
1411
+ indexCount: null,
1412
+ countMismatch: false,
1413
+ sample: { checked: 0, missingFromIndex: [], extraInIndex: [] },
1414
+ }
1415
+ 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)}`) }
1416
+ report.tables[table] = info
1417
+ if (!info.exists) {
1418
+ missingTable = true
1419
+ info.triggers.missing = triggerMap[table].slice()
1420
+ report.errors.push(`${table}: the FTS index table is missing although schema v19 expects it`)
1421
+ continue
1422
+ }
1423
+ anyTable = true
1424
+ info.triggers.missing = triggerMap[table].filter((name) => !existingTriggers.has(name))
1425
+ if (info.triggers.missing.length) {
1426
+ inconsistent = true
1427
+ report.errors.push(`${table}: missing FTS sync trigger(s) ${info.triggers.missing.join(', ')}; rows written without them are not indexed`)
1428
+ }
1429
+ try {
1430
+ this.db.prepare(`INSERT INTO ${table}(${table}, rank) VALUES('integrity-check', 1)`).run()
1431
+ info.integrityCheck = 'ok'
1432
+ } catch (error) {
1433
+ info.integrityCheck = 'malformed'
1434
+ inconsistent = true
1435
+ report.errors.push(`${table}: FTS5 integrity-check failed: ${String(error?.message ?? error).slice(0, 200)}`)
1436
+ }
1437
+ 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)}`) }
1438
+ try { info.indexCount = Number(this.db.prepare(`SELECT COUNT(*) AS n FROM ${table}_docsize`).get()?.n ?? 0) } catch (error) { info.indexCount = null }
1439
+ if (info.sourceCount != null && info.indexCount != null && info.sourceCount !== info.indexCount) {
1440
+ info.countMismatch = true
1441
+ inconsistent = true
1442
+ report.errors.push(`${table}: index has ${info.indexCount} row(s) for ${info.sourceCount} source row(s)`)
1443
+ }
1444
+ if (info.sourceCount && info.sourceCount > 0) {
1445
+ try {
1446
+ const limitN = Math.max(1, Math.min(Number(sampleSize) || 0, 1000))
1447
+ const sampleIds = this.db.prepare(`SELECT rowid AS id FROM ${source.table} ORDER BY rowid LIMIT ?`).all(limitN).map((row) => row.id)
1448
+ if (sampleIds.length) {
1449
+ const indexed = new Set(this.db.prepare(`SELECT id FROM ${table}_docsize WHERE id IN (${sampleIds.map(() => '?').join(',')})`).all(...sampleIds).map((row) => row.id))
1450
+ info.sample.checked = sampleIds.length
1451
+ info.sample.missingFromIndex = sampleIds.filter((id) => !indexed.has(id))
1452
+ if (info.sample.missingFromIndex.length) {
1453
+ inconsistent = true
1454
+ report.errors.push(`${table}: sample rowid(s) ${info.sample.missingFromIndex.slice(0, 10).join(', ')} are in the source table but not in the index`)
1455
+ }
1456
+ const indexIds = this.db.prepare(`SELECT id FROM ${table}_docsize ORDER BY id LIMIT ?`).all(limitN).map((row) => row.id)
1457
+ if (indexIds.length) {
1458
+ 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))
1459
+ info.sample.extraInIndex = indexIds.filter((id) => !sourceIds.has(id))
1460
+ if (info.sample.extraInIndex.length) {
1461
+ inconsistent = true
1462
+ report.errors.push(`${table}: sample rowid(s) ${info.sample.extraInIndex.slice(0, 10).join(', ')} are in the index but not in the source table`)
1463
+ }
1464
+ }
1465
+ }
1466
+ } catch (error) {
1467
+ report.errors.push(`${table}: sample comparison failed: ${String(error?.message ?? error).slice(0, 160)}`)
1468
+ }
1469
+ }
1470
+ }
1471
+ report.triggers.missing = FTS_TRIGGER_NAMES.filter((name) => !existingTriggers.has(name))
1472
+ if (!anyTable) {
1473
+ if (this.ftsWarning) {
1474
+ report.state = 'degraded'
1475
+ report.warning = `FTS5 is unavailable/degraded (${this.ftsWarning}); search uses LIKE only`
1476
+ } else {
1477
+ report.state = 'missing'
1478
+ report.ok = false
1479
+ report.errors.push('no FTS index tables exist although schema v19 expects them')
1480
+ }
1481
+ } else if (inconsistent || missingTable) {
1482
+ report.state = 'inconsistent'
1483
+ report.ok = false
1484
+ }
1485
+ if (!report.ok) {
1486
+ 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`
1487
+ this._ftsBroken = true
1488
+ this.ftsIntegrityWarning = report.warning
1489
+ }
1490
+ this.ftsIntegrityReport = report
1491
+ return report
1492
+ }
1493
+
1494
+ /** Record a detected FTS/LIKE result mismatch and warn once per store. */
1495
+ _markFtsInconsistent(table, ftsCount, likeCount) {
1496
+ this._ftsBroken = true
1497
+ 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`
1498
+ this.ftsIntegrityWarning = message
1499
+ if (this._ftsWarned) return
1500
+ this._ftsWarned = true
1501
+ try { console.warn(`advisers: warning: ${message}`) } catch {}
1502
+ }
1503
+
833
1504
  /**
834
1505
  * Run fn() in a write transaction with bounded SQLITE_BUSY retries.
835
1506
  * Nested calls join the outer transaction (no nested BEGIN).
836
1507
  */
837
1508
  _transaction(mode, fn, { retries = OPEN_RETRIES } = {}) {
1509
+ if (String(mode).toUpperCase() === 'IMMEDIATE') this._assertWritable('transaction')
838
1510
  if (this._transactionDepth > 0) return fn()
839
1511
  let lastError
840
1512
  for (let attempt = 0; attempt <= retries; attempt++) {
@@ -866,11 +1538,29 @@ export class SqliteStore {
866
1538
  return this._transaction(mode, fn)
867
1539
  }
868
1540
 
1541
+ /**
1542
+ * One BEGIN IMMEDIATE for a directed write: fn() runs inside, then (when
1543
+ * provided) the audit row is appended to the same transaction. Any throw —
1544
+ * business error or audit failure — rolls every row back, so a ledger write
1545
+ * never commits without its audit row and an audit row never claims a write
1546
+ * that rolled back (invariant I1). Returns { result, audit }.
1547
+ */
1548
+ mutate(fn, audit) {
1549
+ this._assertWritable('mutate')
1550
+ if (typeof fn !== 'function') throw new TypeError('mutate requires a function')
1551
+ return this._transaction('IMMEDIATE', () => {
1552
+ const result = fn(this)
1553
+ const auditRow = audit === undefined || audit === null ? null : this._appendAuditRow(audit)
1554
+ return { result, audit: auditRow }
1555
+ })
1556
+ }
1557
+
869
1558
  /**
870
1559
  * Checkpoint the WAL so a copied/sealed database file is self-contained.
871
1560
  * Returns busy=true when another connection prevented a full checkpoint.
872
1561
  */
873
1562
  checkpoint({ mode = 'TRUNCATE', retries = OPEN_RETRIES } = {}) {
1563
+ this._assertWritable('checkpoint')
874
1564
  let last = null
875
1565
  for (let attempt = 0; attempt <= retries; attempt++) {
876
1566
  last = this.db.prepare(`PRAGMA wal_checkpoint(${mode})`).get()
@@ -882,30 +1572,103 @@ export class SqliteStore {
882
1572
  return { busy: Number(last?.busy ?? 1) !== 0, log: Number(last?.log ?? 0), checkpointed: Number(last?.checkpointed ?? 0) }
883
1573
  }
884
1574
 
1575
+ /** Read the on-disk schema version before SCHEMA/migrate run (0 = new/empty). */
1576
+ _readSchemaVersionForBackup() {
1577
+ try {
1578
+ const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
1579
+ return row ? Number(row.value) : 0
1580
+ } catch (error) {
1581
+ if (/no such table/i.test(String(error?.message ?? error))) return 0
1582
+ throw error
1583
+ }
1584
+ }
1585
+
1586
+ /** Take the pre-migration backup while no write transaction is open. */
1587
+ _prepareMigrationBackup() {
1588
+ if (!this.path || this.path === ':memory:') return null
1589
+ const current = this._readSchemaVersionForBackup()
1590
+ if (!Number.isFinite(current) || current <= 0 || current >= SCHEMA_VERSION) return null
1591
+ return this.backupBeforeMigrate(current)
1592
+ }
1593
+
1594
+ /**
1595
+ * Same-directory backup of the database before a schema migration.
1596
+ *
1597
+ * P2-9 (2026-11-17 robustness audit): the old implementation copied only the
1598
+ * main database file. Committed transactions that still lived in the WAL
1599
+ * were missing from the backup (measured: backup 300 rows vs main DB 301),
1600
+ * so rolling back to it silently dropped data. Now the WAL is folded into
1601
+ * the main file with 'PRAGMA wal_checkpoint(TRUNCATE)' before the copy; if
1602
+ * another connection prevents the checkpoint the migration is refused
1603
+ * rather than proceeding with an incomplete backup.
1604
+ *
1605
+ * The copy is verified with a read-only DatabaseSync quick_check, the
1606
+ * schema_version it was taken at, and a row-count sample of the five tables
1607
+ * whose loss matters most (matters/facts/commitments/preferences/audit). A
1608
+ * failed verification removes the partial backup and throws (fail-closed).
1609
+ * The directory entry is fsynced after the copy so a crash cannot leave a
1610
+ * visible-but-empty backup. Returns the backup path.
1611
+ */
885
1612
  backupBeforeMigrate(current) {
886
- if (!this.path || this.path === ':memory:') return
1613
+ this._assertWritable('backupBeforeMigrate')
1614
+ if (!this.path || this.path === ':memory:') return null
1615
+ const checkpoint = this.checkpoint({ mode: 'TRUNCATE' })
1616
+ if (checkpoint.busy) {
1617
+ 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`)
1618
+ // Wave-2 Persistence v2 contract (03-design-persistence-v2.md §5.4): stable
1619
+ // code so bin/ can map it to an actionable message.
1620
+ error.code = 'E_MIGRATE_BUSY'
1621
+ throw error
1622
+ }
1623
+ // Sample the main database AFTER the checkpoint (so WAL-only commits are
1624
+ // included) and compare it with the copy: a backup that silently dropped
1625
+ // committed rows must never be used as the rollback path.
1626
+ const expectedCounts = this._sampleTableCounts(this.db)
887
1627
  const target = `${this.path}.before-migrate-v${current}-${Date.now()}`
1628
+ let backupDb = null
888
1629
  try {
889
- copyFileSync(this.path, target)
1630
+ copyFileWithRetrySync(this.path, target, { mode: 0o600 })
1631
+ fsyncFileSync(target)
1632
+ // Make the directory entry durable too: without this a crash can leave a
1633
+ // correctly-sized backup that is not recoverable after reboot.
1634
+ try { fsyncDirSync(dirname(this.path)) } catch {}
1635
+ backupDb = new DatabaseSync(target, { readOnly: true })
1636
+ const verdict = String(backupDb.prepare('PRAGMA quick_check').get()?.quick_check ?? 'unknown')
1637
+ if (verdict !== 'ok') throw new Error(`quick_check on the backup reported '${verdict}'`)
1638
+ const meta = backupDb.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
1639
+ if (meta && Number(meta.value) !== Number(current)) {
1640
+ throw new Error(`backup contains schema_version ${meta.value}, expected ${current}`)
1641
+ }
1642
+ this._verifyBackupCounts(backupDb, expectedCounts)
890
1643
  try { chmodSync(target, 0o600) } catch {}
1644
+ return target
891
1645
  } catch (error) {
892
- throw new Error(`refusing to migrate without a backup of ${this.path}: ${error.message}`)
1646
+ try { backupDb?.close() } catch {}
1647
+ backupDb = null
1648
+ try { rmWithRetrySync(target) } catch {}
1649
+ const wrapped = new Error(`refusing to migrate without a verified backup of ${this.path}: ${String(error?.message ?? error).slice(0, 300)}`)
1650
+ wrapped.code = 'E_MIGRATION_BACKUP'
1651
+ throw wrapped
1652
+ } finally {
1653
+ try { backupDb?.close() } catch {}
1654
+ // Opening a WAL-mode backup read-only makes SQLite create <backup>-wal/-shm;
1655
+ // they are verification artifacts, not part of the backup, so remove them.
1656
+ for (const suffix of ['-wal', '-shm']) {
1657
+ try { if (existsSync(target + suffix)) rmSync(target + suffix, { force: true }) } catch {}
1658
+ }
893
1659
  }
894
1660
  }
895
1661
 
896
1662
  /**
897
- * Bring an older database up to SCHEMA_VERSION. Runs inside the caller's
898
- * write transaction (initializeSchema). Refuses futures schemas and keeps
899
- * a same-directory backup before altering an existing database.
1663
+ * Pre-v20 single-block idempotent migration (0.2.2 and earlier).
1664
+ *
1665
+ * Kept apart from the version-step table below: it builds every base table,
1666
+ * adds the columns older releases lacked, installs the v19 trigram FTS and
1667
+ * stamps meta.schema_version=19. The v20 step then adds the migration ledger
1668
+ * and the new indexes in the same outer transaction.
900
1669
  */
901
- migrate() {
902
- const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
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 {
1670
+ _legacyMigrateThrough19() {
1671
+ {
909
1672
  this.db.exec(`CREATE TABLE IF NOT EXISTS seen_events (
910
1673
  link_id TEXT NOT NULL, account_id TEXT NOT NULL, dedupe_key TEXT NOT NULL,
911
1674
  seen_at TEXT NOT NULL, PRIMARY KEY(link_id, account_id, dedupe_key)
@@ -986,13 +1749,86 @@ CREATE TABLE IF NOT EXISTS task_runs (
986
1749
  // instead of falling back to a LIKE table scan. Runs last so the source
987
1750
  // tables (turns, session_summaries) exist for the 'rebuild' backfill.
988
1751
  this._setupFts()
989
- this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)').run('schema_version', String(SCHEMA_VERSION))
990
- } catch (error) {
991
- throw error
1752
+ this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)').run('schema_version', String(LEGACY_SCHEMA_VERSION))
1753
+ }
1754
+ }
1755
+
1756
+ /**
1757
+ * Bring an older database up to SCHEMA_VERSION.
1758
+ *
1759
+ * Runs inside the caller's write transaction (initializeSchema). Order:
1760
+ * 1. read the on-disk version (0 = fresh database whose meta table was just
1761
+ * created by SCHEMA);
1762
+ * 2. refuse a future schema (E_SCHEMA_NEWER, fail closed);
1763
+ * 3. legacy block for < v19 (idempotent base tables + FTS);
1764
+ * 4. every MIGRATIONS step with version > current, recording
1765
+ * schema_migrations(version, name, applied_at, duration_ms, backup_path);
1766
+ * 5. stamp meta.schema_version = SCHEMA_VERSION and the diagnostics keys.
1767
+ *
1768
+ * A failure anywhere rolls back every DDL write and the version stamp, so a
1769
+ * failed migration leaves the old database intact and retryable.
1770
+ */
1771
+ migrate() {
1772
+ this._assertWritable('migrate')
1773
+ const row = this.db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version')
1774
+ const current = row ? Number(row.value) : 0
1775
+ if (!Number.isFinite(current) || current < 0) throw new Error(`invalid schema_version in ${this.path}: ${row?.value}`)
1776
+ if (current > SCHEMA_VERSION) throw schemaNewerError(this.path, current)
1777
+ if (current >= SCHEMA_VERSION) return
1778
+ // initializeSchema() already took the verified backup before opening its
1779
+ // write transaction (a WAL checkpoint cannot run inside one); only direct
1780
+ // callers of migrate() fall back to taking it here.
1781
+ if (current > 0 && !this._migrationBackup) this._migrationBackup = this.backupBeforeMigrate(current)
1782
+ if (current < LEGACY_SCHEMA_VERSION) this._legacyMigrateThrough19()
1783
+ // A direct migrate() caller may not have run SCHEMA first; the steps assume
1784
+ // the migration ledger exists.
1785
+ this.db.exec(SCHEMA_MIGRATIONS_DDL)
1786
+ const from = current
1787
+ for (const step of MIGRATIONS) {
1788
+ if (step.version <= current) continue
1789
+ const startedAt = Date.now()
1790
+ this._runMigrationStep(step)
1791
+ this.db.prepare('INSERT OR REPLACE INTO schema_migrations(version,name,applied_at,duration_ms,backup_path) VALUES(?,?,?,?,?)')
1792
+ .run(step.version, step.name, new Date().toISOString(), Date.now() - startedAt, this._migrationBackup ?? null)
1793
+ }
1794
+ const migratedAt = new Date().toISOString()
1795
+ const setMeta = this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)')
1796
+ setMeta.run('schema_version', String(SCHEMA_VERSION))
1797
+ setMeta.run('schema_migrated_from', String(from))
1798
+ setMeta.run('schema_migrated_at', migratedAt)
1799
+ setMeta.run('schema_migrated_app', APP_VERSION)
1800
+ if (this._migrationBackup) setMeta.run('schema_migration_backup', this._migrationBackup)
1801
+ }
1802
+
1803
+ /** Run one migration step (separate method so tests can inject a failure). */
1804
+ _runMigrationStep(step) {
1805
+ step.up(this)
1806
+ }
1807
+
1808
+ /** Row counts for the verify-after-copy step of the migration backup. */
1809
+ _sampleTableCounts(db) {
1810
+ const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => row.name))
1811
+ const counts = {}
1812
+ for (const table of BACKUP_SAMPLE_TABLES) {
1813
+ if (!tables.has(table)) continue
1814
+ counts[table] = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n ?? 0)
1815
+ }
1816
+ return counts
1817
+ }
1818
+
1819
+ /** Fail-closed comparison of the backup row counts with the main database. */
1820
+ _verifyBackupCounts(backupDb, expected) {
1821
+ const actual = this._sampleTableCounts(backupDb)
1822
+ for (const [table, expectedCount] of Object.entries(expected)) {
1823
+ const actualCount = actual[table]
1824
+ if (actualCount !== expectedCount) {
1825
+ throw new Error(`backup row count mismatch for ${table}: backup has ${actualCount ?? 'no table'}, main database has ${expectedCount}`)
1826
+ }
992
1827
  }
993
1828
  }
994
1829
 
995
1830
  upsertSession({ conversationId, matterId, title }) {
1831
+ this._assertWritable('upsertSession')
996
1832
  const now = new Date().toISOString()
997
1833
  this.db.prepare(`INSERT INTO sessions(conversation_id,matter_id,title,created_at,updated_at)
998
1834
  VALUES(?,?,?,?,?)
@@ -1011,6 +1847,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1011
1847
  }
1012
1848
 
1013
1849
  addDelivery({ matterId, conversationId, files, tool, title, validation }) {
1850
+ this._assertWritable('addDelivery')
1014
1851
  const id = `del_${randomUUID().replace(/-/g, '').slice(0, 16)}`
1015
1852
  this.db.prepare('INSERT INTO deliveries(id,matter_id,conversation_id,files,tool,title,validation,created_at) VALUES(?,?,?,?,?,?,?,?)')
1016
1853
  .run(id, matterId, conversationId, JSON.stringify(files ?? []), tool ?? null, title ?? null, validation ?? null, new Date().toISOString())
@@ -1027,14 +1864,17 @@ CREATE TABLE IF NOT EXISTS task_runs (
1027
1864
  }
1028
1865
 
1029
1866
  setMeta(key, value) {
1867
+ this._assertWritable('setMeta')
1030
1868
  this.db.prepare('INSERT OR REPLACE INTO meta(key,value) VALUES(?,?)').run(key, String(value))
1031
1869
  }
1032
1870
 
1033
1871
  deleteMeta(key) {
1872
+ this._assertWritable('deleteMeta')
1034
1873
  this.db.prepare('DELETE FROM meta WHERE key = ?').run(key)
1035
1874
  }
1036
1875
 
1037
1876
  addTaskRun({ conversationId, matterId, task, tools, artifacts, outcome }) {
1877
+ this._assertWritable('addTaskRun')
1038
1878
  const id = `run_${randomUUID().replace(/-/g, '').slice(0, 16)}`
1039
1879
  this.db.prepare('INSERT INTO task_runs(id,conversation_id,matter_id,task,tools,artifacts,outcome,created_at) VALUES(?,?,?,?,?,?,?,?)')
1040
1880
  .run(id, conversationId, matterId ?? null, task, json(tools), json(artifacts), outcome, new Date().toISOString())
@@ -1047,6 +1887,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1047
1887
  }
1048
1888
 
1049
1889
  addNudge({ localDay, level, commitmentId, body }) {
1890
+ this._assertWritable('addNudge')
1050
1891
  const key = `${localDay}:${level}:${commitmentId}`
1051
1892
  const id = `nudge_${randomUUID().replace(/-/g, '').slice(0, 16)}`
1052
1893
  try {
@@ -1059,6 +1900,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1059
1900
  }
1060
1901
 
1061
1902
  setNudgeOutcome(id, outcome) {
1903
+ this._assertWritable('setNudgeOutcome')
1062
1904
  return Number(this.db.prepare('UPDATE nudges SET outcome = ?, outcome_at = ? WHERE id = ?').run(outcome, new Date().toISOString(), id).changes) > 0
1063
1905
  }
1064
1906
 
@@ -1078,6 +1920,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1078
1920
  * rows actually inserted (existing rows are left untouched).
1079
1921
  */
1080
1922
  addNudges(rows) {
1923
+ this._assertWritable('addNudges')
1081
1924
  if (!rows?.length) return 0
1082
1925
  return this._transaction('IMMEDIATE', () => {
1083
1926
  const statement = this.db.prepare('INSERT OR IGNORE INTO nudges(id,at,local_day,level,commitment_id,dedupe_key,body) VALUES(?,?,?,?,?,?,?)')
@@ -1149,6 +1992,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1149
1992
 
1150
1993
  /** P0-2: delete a batch of meta keys in one transaction. */
1151
1994
  deleteMetaKeys(keys) {
1995
+ this._assertWritable('deleteMetaKeys')
1152
1996
  if (!keys?.length) return 0
1153
1997
  return this._transaction('IMMEDIATE', () => {
1154
1998
  const statement = this.db.prepare('DELETE FROM meta WHERE key = ?')
@@ -1162,7 +2006,16 @@ CREATE TABLE IF NOT EXISTS task_runs (
1162
2006
  return this.db.prepare('SELECT * FROM nudges ORDER BY at DESC LIMIT ?').all(limit)
1163
2007
  }
1164
2008
 
1165
- purgeMatterData(matterId) {
2009
+ /**
2010
+ * Delete the non-ledger rows of one matter (sessions/turns/summaries/runs/
2011
+ * nudges/candidates/deliveries). The VACUUM is a maintenance operation: it
2012
+ * cannot run inside a transaction, so when this is called from inside
2013
+ * mutate()/transaction() it is skipped and the caller runs it after COMMIT
2014
+ * (pass { vacuum: false } explicitly to force that). Standalone calls keep
2015
+ * the historical checkpoint+VACUUM behaviour.
2016
+ */
2017
+ purgeMatterData(matterId, { vacuum = true } = {}) {
2018
+ this._assertWritable('purgeMatterData')
1166
2019
  const conversations = this.db.prepare('SELECT conversation_id FROM sessions WHERE matter_id = ?').all(matterId).map((r) => r.conversation_id)
1167
2020
  let turns = 0
1168
2021
  let summaries = 0
@@ -1182,11 +2035,14 @@ CREATE TABLE IF NOT EXISTS task_runs (
1182
2035
  this.db.prepare('DELETE FROM research_runs WHERE matter_id = ?').run(matterId)
1183
2036
  const sessions = this.db.prepare('DELETE FROM sessions WHERE matter_id = ?').run(matterId).changes
1184
2037
  const deliveries = this.db.prepare('DELETE FROM deliveries WHERE matter_id = ?').run(matterId).changes
1185
- try { this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); this.db.exec('VACUUM') } catch {}
2038
+ if (vacuum && this._transactionDepth === 0) {
2039
+ try { this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); this.db.exec('VACUUM') } catch {}
2040
+ }
1186
2041
  return { sessions: Number(sessions), deliveries: Number(deliveries), turns, summaries, runs, nudges, candidates }
1187
2042
  }
1188
2043
 
1189
2044
  addTurn({ conversationId, role, content }) {
2045
+ this._assertWritable('addTurn')
1190
2046
  const seq = (this.db.prepare('SELECT MAX(seq) AS n FROM turns WHERE conversation_id = ?').get(conversationId)?.n ?? 0) + 1
1191
2047
  const id = `turn_${randomUUID().replace(/-/g, '').slice(0, 16)}`
1192
2048
  this.db.prepare('INSERT INTO turns(id,conversation_id,seq,role,content,created_at) VALUES(?,?,?,?,?,?)')
@@ -1200,6 +2056,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1200
2056
  }
1201
2057
 
1202
2058
  upsertCalendarEvent({ uid, summary, startsAt, endsAt, allDay = false, tzid, location, rrule, source }) {
2059
+ this._assertWritable('upsertCalendarEvent')
1203
2060
  this.db.prepare(`INSERT INTO calendar_events(uid,summary,starts_at,ends_at,all_day,tzid,location,rrule,source,imported_at)
1204
2061
  VALUES(?,?,?,?,?,?,?,?,?,?)
1205
2062
  ON CONFLICT(uid) DO UPDATE SET summary=excluded.summary, starts_at=excluded.starts_at, ends_at=excluded.ends_at,
@@ -1221,6 +2078,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1221
2078
  }
1222
2079
 
1223
2080
  permitReplayStore() {
2081
+ this._assertWritable('permitReplayStore')
1224
2082
  return {
1225
2083
  has: (permitId) => Boolean(this.db.prepare('SELECT 1 FROM permit_consumed WHERE permit_id = ?').get(permitId)),
1226
2084
  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 +2087,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1229
2087
  }
1230
2088
 
1231
2089
  addResearchRun({ matterId, query, answer, sources, usage, stopReason }) {
2090
+ this._assertWritable('addResearchRun')
1232
2091
  const id = `rr_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
1233
2092
  this.db.prepare('INSERT INTO research_runs(id,matter_id,query,answer,sources,usage,stop_reason,created_at) VALUES(?,?,?,?,?,?,?,?)')
1234
2093
  .run(id, matterId ?? null, query, answer, JSON.stringify(sources ?? []), usage ? JSON.stringify(usage) : null, stopReason ?? null, new Date().toISOString())
@@ -1240,6 +2099,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1240
2099
  }
1241
2100
 
1242
2101
  addModelCall({ conversationId, matterId, turnId, task, model, effort, thinking, usage, durationMs, finishReason, status = 'ok', code, attempts = 1 }) {
2102
+ this._assertWritable('addModelCall')
1243
2103
  const id = `mc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
1244
2104
  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
2105
  VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(
@@ -1282,6 +2142,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1282
2142
  }
1283
2143
 
1284
2144
  proposeCandidate({ kind, payload, evidence }) {
2145
+ this._assertWritable('proposeCandidate')
1285
2146
  const id = `cand_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
1286
2147
  const now = new Date().toISOString()
1287
2148
  this.db.prepare('INSERT INTO memory_candidates(id,kind,payload,evidence,status,created_at) VALUES(?,?,?,?,?,?)')
@@ -1300,6 +2161,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1300
2161
  }
1301
2162
 
1302
2163
  reviewCandidate(id, status, reason) {
2164
+ this._assertWritable('reviewCandidate')
1303
2165
  this.db.prepare('UPDATE memory_candidates SET status = ?, reviewed_at = ?, reject_reason = ? WHERE id = ?')
1304
2166
  .run(status, new Date().toISOString(), reason ?? null, id)
1305
2167
  return this.getCandidate(id)
@@ -1352,16 +2214,39 @@ CREATE TABLE IF NOT EXISTS task_runs (
1352
2214
  const join = matterId ? ' JOIN sessions s ON s.conversation_id = t.conversation_id' : ''
1353
2215
  const where = clauses.length ? ` AND ${clauses.join(' AND ')}` : ''
1354
2216
  const map = (r) => ({ id: r.id, conversationId: r.conversation_id, seq: r.seq, role: r.role, content: r.content, createdAt: r.created_at })
1355
- if (this.ftsTokenizer && this._ftsTables.has('turns_fts') && q.length >= FTS_TRIGRAM_MIN_QUERY) {
2217
+ const likeRows = () => {
2218
+ 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)
2219
+ return rows.reverse().map(map)
2220
+ }
2221
+ let ftsRows = null
2222
+ if (this.ftsTokenizer && this._ftsTables.has('turns_fts') && !this._ftsBroken && q.length >= FTS_TRIGRAM_MIN_QUERY) {
1356
2223
  try {
1357
- const rows = 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)
1358
- if (rows.length) return rows.map(map)
2224
+ 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
2225
  } catch {
1360
2226
  // Malformed or special FTS query: use the LIKE scan below.
2227
+ ftsRows = null
2228
+ }
2229
+ }
2230
+ // P1-5: a full FTS page is returned ranked, as before. A short page is
2231
+ // cross-checked with a LIKE scan; if LIKE finds more rows the index is
2232
+ // incomplete (or the MATCH query was narrower) and the complete, seq-ordered
2233
+ // LIKE rows are returned with one warning instead of silently losing hits.
2234
+ if (ftsRows && ftsRows.length >= limit) return ftsRows.map(map)
2235
+ const rows = likeRows()
2236
+ if (ftsRows && ftsRows.length) {
2237
+ if (rows.length > ftsRows.length) {
2238
+ this._markFtsInconsistent('turns_fts', ftsRows.length, rows.length)
2239
+ return rows
1361
2240
  }
2241
+ return ftsRows.map(map)
1362
2242
  }
1363
- 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)
1364
- return rows.reverse().map(map)
2243
+ if (ftsRows && ftsRows.length === 0 && rows.length > 0 && this.ftsTokenizer === 'trigram') {
2244
+ // Trigram indexes every 3+ character substring, so a 0-hit MATCH that a
2245
+ // LIKE scan contradicts means the index is missing rows (not a tokenizer
2246
+ // limitation); warn instead of quietly returning the LIKE rows.
2247
+ this._markFtsInconsistent('turns_fts', 0, rows.length)
2248
+ }
2249
+ return rows
1365
2250
  }
1366
2251
 
1367
2252
  /**
@@ -1375,16 +2260,29 @@ CREATE TABLE IF NOT EXISTS task_runs (
1375
2260
  const where = conversationId ? ' AND s.conversation_id = ?' : ''
1376
2261
  const filterArgs = conversationId ? [conversationId] : []
1377
2262
  const map = (r) => ({ conversationId: r.conversation_id, summary: r.summary, throughSeq: r.through_seq, updatedAt: r.updated_at })
1378
- if (this.ftsTokenizer && this._ftsTables.has('summaries_fts') && q.length >= FTS_TRIGRAM_MIN_QUERY) {
2263
+ 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)
2264
+ let ftsRows = null
2265
+ if (this.ftsTokenizer && this._ftsTables.has('summaries_fts') && !this._ftsBroken && q.length >= FTS_TRIGRAM_MIN_QUERY) {
1379
2266
  try {
1380
- const rows = 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)
1381
- if (rows.length) return rows.map(map)
2267
+ 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
2268
  } catch {
1383
2269
  // Malformed or special FTS query: use the LIKE scan below.
2270
+ ftsRows = null
2271
+ }
2272
+ }
2273
+ if (ftsRows && ftsRows.length >= limit) return ftsRows.map(map)
2274
+ const rows = likeRows()
2275
+ if (ftsRows && ftsRows.length) {
2276
+ if (rows.length > ftsRows.length) {
2277
+ this._markFtsInconsistent('summaries_fts', ftsRows.length, rows.length)
2278
+ return rows
1384
2279
  }
2280
+ return ftsRows.map(map)
1385
2281
  }
1386
- const rows = 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)
1387
- return rows.map(map)
2282
+ if (ftsRows && ftsRows.length === 0 && rows.length > 0 && this.ftsTokenizer === 'trigram') {
2283
+ this._markFtsInconsistent('summaries_fts', 0, rows.length)
2284
+ }
2285
+ return rows
1388
2286
  }
1389
2287
 
1390
2288
  getSessionSummary(conversationId) {
@@ -1393,6 +2291,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1393
2291
  }
1394
2292
 
1395
2293
  upsertSessionSummary({ conversationId, summary, throughSeq, pins }) {
2294
+ this._assertWritable('upsertSessionSummary')
1396
2295
  const max = this.db.prepare('SELECT MAX(version) AS v FROM summary_versions WHERE conversation_id = ?').get(conversationId)?.v ?? 0
1397
2296
  const version = max + 1
1398
2297
  const at = new Date().toISOString()
@@ -1419,10 +2318,12 @@ CREATE TABLE IF NOT EXISTS task_runs (
1419
2318
  * can never both chain onto the same predecessor (audit fork, P0-3).
1420
2319
  */
1421
2320
  appendAudit({ actor, action, allowed, reason }) {
2321
+ this._assertWritable('appendAudit')
1422
2322
  return this._transaction('IMMEDIATE', () => this._appendAuditRow({ actor, action, allowed, reason }))
1423
2323
  }
1424
2324
 
1425
2325
  _appendAuditRow({ actor, action, allowed, reason }) {
2326
+ this._assertWritable('appendAudit')
1426
2327
  const last = this.db.prepare('SELECT hash FROM audit ORDER BY seq DESC LIMIT 1').get()
1427
2328
  const prev = last?.hash ?? ''
1428
2329
  const at = new Date().toISOString()
@@ -1461,11 +2362,13 @@ CREATE TABLE IF NOT EXISTS task_runs (
1461
2362
  }
1462
2363
 
1463
2364
  markSeen(linkId, accountId, dedupeKey) {
2365
+ this._assertWritable('markSeen')
1464
2366
  this.db.prepare('INSERT OR REPLACE INTO seen_events VALUES(?,?,?,?)')
1465
2367
  .run(linkId, accountId, dedupeKey, new Date().toISOString())
1466
2368
  }
1467
2369
 
1468
2370
  pruneSeen(ttlDays = 7) {
2371
+ this._assertWritable('pruneSeen')
1469
2372
  const cutoff = new Date(Date.now() - ttlDays * 86_400_000).toISOString()
1470
2373
  this.db.prepare('DELETE FROM seen_events WHERE seen_at < ?').run(cutoff)
1471
2374
  }
@@ -1483,6 +2386,132 @@ CREATE TABLE IF NOT EXISTS task_runs (
1483
2386
  }
1484
2387
  }
1485
2388
 
2389
+ // -------------------------------------------------------------------------
2390
+ // Directed entity reads/writes (0.2.3 incremental write path).
2391
+ //
2392
+ // Every insert*/update* must run inside mutate()/transaction() (otherwise
2393
+ // E_TX_REQUIRED: a ledger row must never commit outside the transaction that
2394
+ // carries its audit row), and produces exactly the bytes _saveRows() would
2395
+ // (shared ENTITY_SPECS codecs). update* writes only the columns a patch
2396
+ // explicitly names; an unknown field is an error so a typo cannot silently
2397
+ // write nothing. get*/find* are read methods usable on read-only stores.
2398
+ // -------------------------------------------------------------------------
2399
+
2400
+ _getEntity(kind, id) {
2401
+ const spec = ENTITY_SPECS[kind]
2402
+ if (!spec) throw new Error(`unknown entity: ${kind}`)
2403
+ const row = this.db.prepare(`SELECT * FROM ${spec.table} WHERE ${spec.key} = ?`).get(id)
2404
+ return row ? spec.map(row) : undefined
2405
+ }
2406
+
2407
+ getMatter(id) { return this._getEntity('matters', id) }
2408
+ getFact(id) { return this._getEntity('facts', id) }
2409
+ getCommitment(id) { return this._getEntity('commitments', id) }
2410
+ getPreference(id) { return this._getEntity('preferences', id) }
2411
+
2412
+ _insertEntity(operation, kind, entity) {
2413
+ this._assertInWriteTransaction(operation)
2414
+ const spec = ENTITY_SPECS[kind]
2415
+ if (!spec) throw new Error(`unknown entity: ${kind}`)
2416
+ const fields = Object.keys(spec.columns)
2417
+ const columns = fields.map((field) => spec.columns[field][0])
2418
+ const values = fields.map((field) => encodeEntityValue(spec.columns[field][1], entity?.[field]))
2419
+ this.db.prepare(`INSERT INTO ${spec.table}(${columns.join(',')}) VALUES(${fields.map(() => '?').join(',')})`).run(...values)
2420
+ return entity
2421
+ }
2422
+
2423
+ insertMatter(row) { return this._insertEntity('insertMatter', 'matters', row) }
2424
+ insertFact(row) { return this._insertEntity('insertFact', 'facts', row) }
2425
+ insertCommitment(row) { return this._insertEntity('insertCommitment', 'commitments', row) }
2426
+ insertPreference(row) { return this._insertEntity('insertPreference', 'preferences', row) }
2427
+
2428
+ _updateEntity(operation, kind, id, patch) {
2429
+ this._assertInWriteTransaction(operation)
2430
+ const spec = ENTITY_SPECS[kind]
2431
+ if (!spec) throw new Error(`unknown entity: ${kind}`)
2432
+ const assignments = []
2433
+ const values = []
2434
+ for (const field of Object.keys(patch ?? {})) {
2435
+ const column = spec.columns[field]
2436
+ if (!column) throw new Error(`unknown ${kind} field: ${field}`)
2437
+ const value = patch[field]
2438
+ if (value === undefined) continue
2439
+ assignments.push(`${column[0]} = ?`)
2440
+ values.push(encodeEntityValue(column[1], value))
2441
+ }
2442
+ if (assignments.length) {
2443
+ this.db.prepare(`UPDATE ${spec.table} SET ${assignments.join(', ')} WHERE ${spec.key} = ?`).run(...values, id)
2444
+ }
2445
+ return this._getEntity(kind, id)
2446
+ }
2447
+
2448
+ updateMatter(id, patch) { return this._updateEntity('updateMatter', 'matters', id, patch) }
2449
+ updateFact(id, patch) { return this._updateEntity('updateFact', 'facts', id, patch) }
2450
+ updateCommitment(id, patch) { return this._updateEntity('updateCommitment', 'commitments', id, patch) }
2451
+ updatePreference(id, patch) { return this._updateEntity('updatePreference', 'preferences', id, patch) }
2452
+
2453
+ /**
2454
+ * The confirmed, unexpired fact for one identity (remember/supersede path).
2455
+ * predicate 'said' never matches: conversation echoes do not supersede each
2456
+ * other (same rule as core Ledger.remember). Uses idx_facts_identity. The
2457
+ * `IS ?` comparison treats a missing matterId like SQLite's IS NULL.
2458
+ */
2459
+ findFactCurrent({ subject, predicate, matterId } = {}) {
2460
+ if (predicate === 'said') return undefined
2461
+ const row = this.db.prepare(`
2462
+ SELECT * FROM facts
2463
+ WHERE status = 'confirmed' AND expired_at IS NULL AND subject = ? AND predicate = ? AND (matter_id IS ?)
2464
+ ORDER BY rowid LIMIT 1
2465
+ `).get(subject, predicate, matterId ?? null)
2466
+ return row ? mapFactRow(row) : undefined
2467
+ }
2468
+
2469
+ /** First non-deprecated preference with this exact statement (correct/learn). */
2470
+ findPreferenceByStatement(statement) {
2471
+ const row = this.db.prepare("SELECT * FROM preferences WHERE statement = ? AND status <> 'deprecated' ORDER BY rowid LIMIT 1").get(statement)
2472
+ return row ? mapPreferenceRow(row) : undefined
2473
+ }
2474
+
2475
+ /** First active matter by insertion order (commit add / memory accept default). */
2476
+ firstActiveMatter() {
2477
+ const row = this.db.prepare("SELECT * FROM matters WHERE status = 'active' ORDER BY rowid LIMIT 1").get()
2478
+ return row ? mapMatterRow(row) : undefined
2479
+ }
2480
+
2481
+ /**
2482
+ * Persist one tick() batch atomically (no audit row, matching the historical
2483
+ * tick behaviour): nudge inserts, snooze wake-ups and the snooze meta
2484
+ * cleanup either all commit or all roll back, so a nudge can never be
2485
+ * recorded while its wake-up is lost. The conditional UPDATE keeps a
2486
+ * concurrent state change (e.g. the commitment was completed meanwhile)
2487
+ * authoritative. Returns { nudges, woke, metaDeleted }.
2488
+ */
2489
+ applyTick({ nudgeRows = [], wakeIds = [], snoozeKeys = [] } = {}) {
2490
+ this._assertWritable('applyTick')
2491
+ return this._transaction('IMMEDIATE', () => {
2492
+ const now = new Date().toISOString()
2493
+ let nudges = 0
2494
+ if (nudgeRows.length) {
2495
+ const insert = this.db.prepare('INSERT OR IGNORE INTO nudges(id,at,local_day,level,commitment_id,dedupe_key,body) VALUES(?,?,?,?,?,?,?)')
2496
+ for (const row of nudgeRows) {
2497
+ const dedupeKey = `${row.localDay}:${row.level}:${row.commitmentId}`
2498
+ const id = `nudge_${randomUUID().replace(/-/g, '').slice(0, 16)}`
2499
+ nudges += Number(insert.run(id, row.at ?? now, row.localDay, row.level, row.commitmentId, dedupeKey, row.body).changes)
2500
+ }
2501
+ }
2502
+ let woke = 0
2503
+ if (wakeIds.length) {
2504
+ const wake = this.db.prepare("UPDATE commitments SET status = 'open' WHERE id = ? AND status = 'snoozed'")
2505
+ for (const id of wakeIds) woke += Number(wake.run(id).changes)
2506
+ }
2507
+ let metaDeleted = 0
2508
+ if (snoozeKeys.length) {
2509
+ const del = this.db.prepare('DELETE FROM meta WHERE key = ?')
2510
+ for (const key of snoozeKeys) metaDeleted += Number(del.run(key).changes)
2511
+ }
2512
+ return { nudges, woke, metaDeleted }
2513
+ })
2514
+ }
1486
2515
  // -------------------------------------------------------------------------
1487
2516
  // Partial loading (P1-2, 0.2.2)
1488
2517
  //
@@ -1700,6 +2729,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1700
2729
  }
1701
2730
 
1702
2731
  save(snapshot) {
2732
+ this._assertWritable('save')
1703
2733
  return this._transaction('IMMEDIATE', () => this._saveRows(snapshot))
1704
2734
  }
1705
2735
 
@@ -1709,6 +2739,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1709
2739
  * committed). `inside` runs inside the same transaction before the audit row.
1710
2740
  */
1711
2741
  saveWithAudit(snapshot, audit, inside) {
2742
+ this._assertWritable('saveWithAudit')
1712
2743
  return this._transaction('IMMEDIATE', () => {
1713
2744
  this._saveRows(snapshot)
1714
2745
  if (typeof inside === 'function') inside(this)
@@ -1717,6 +2748,7 @@ CREATE TABLE IF NOT EXISTS task_runs (
1717
2748
  }
1718
2749
 
1719
2750
  _saveRows(snapshot) {
2751
+ this._assertWritable('save')
1720
2752
  const db = this.db
1721
2753
  const newIds = idsFor(snapshot)
1722
2754
  const baseline = this._baselineIds
@@ -1784,3 +2816,28 @@ CREATE TABLE IF NOT EXISTS task_runs (
1784
2816
  this.db.close()
1785
2817
  }
1786
2818
  }
2819
+
2820
+ /**
2821
+ * Open an existing database for lock-free reads (0.2.3 read path).
2822
+ *
2823
+ * The store is read-only (DatabaseSync readOnly): no DDL, no migration, no
2824
+ * journal-mode pragmas, no HOME instance lock — so it works while a long-lived
2825
+ * writer holds the lock, reading the last committed WAL snapshot. The schema is
2826
+ * asserted up front: a stale database throws E_SCHEMA_STALE (a writable command
2827
+ * has to migrate it first) and a future one throws E_SCHEMA_NEWER. The caller
2828
+ * decides whether to fall back to the writable path (bin's openReadStore).
2829
+ *
2830
+ * @param {string} path database file
2831
+ * @param {{ checkIntegrity?: boolean, busyTimeoutMs?: number }} [options]
2832
+ * @returns {SqliteStore}
2833
+ */
2834
+ export function openReadStore(path, { checkIntegrity = false, busyTimeoutMs } = {}) {
2835
+ const store = new SqliteStore(path, { readOnly: true, checkIntegrity, busyTimeoutMs })
2836
+ try {
2837
+ store.assertSchemaCurrent()
2838
+ return store
2839
+ } catch (error) {
2840
+ try { store.close() } catch {}
2841
+ throw error
2842
+ }
2843
+ }