@kybernesis/brain-storage-sqlite 0.8.4 → 0.10.0

package/dist/hash.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Content fingerprint (Spec B): sha256 over RAW FILE BYTES — deliberately not
+ * normalized/extracted text, so the hash is simple, stable, decoupled from
+ * extraction, and fails safe. The same function serves both sides of the
+ * contract: consumers compute it at file-read for ingest; reconcile recomputes
+ * it from disk for comparison.
+ */
+export declare function contentHash(rawBytes: Uint8Array | string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAEjE"}

package/dist/hash.js

@@ -0,0 +1,12 @@
+/**
+ * Content fingerprint (Spec B): sha256 over RAW FILE BYTES — deliberately not
+ * normalized/extracted text, so the hash is simple, stable, decoupled from
+ * extraction, and fails safe. The same function serves both sides of the
+ * contract: consumers compute it at file-read for ingest; reconcile recomputes
+ * it from disk for comparison.
+ */
+import { createHash } from 'node:crypto';
+export function contentHash(rawBytes) {
+    return createHash('sha256').update(rawBytes).digest('hex');
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,UAAU,WAAW,CAAC,QAA6B;IACvD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC"}

package/dist/index.d.ts

@@ -4,6 +4,15 @@ export { sanitizeFtsQuery } from './fts-sanitizer.js';
 export { resetTimelineSchemaCache } from './timeline.js';
 export { resetEntityGraphSchemaCache } from './entity-graph.js';
 export { ensureSleepSchema, recoverStaleSleepRuns, resetSleepSchemaCache } from './sleep-store.js';
+export { runMigrations } from './migrations/runner.js';
+export { copyFileBackup } from './migrations/backup.js';
+export { setAutoMigrate } from './migrations/config.js';
+export { registry as migrationRegistry, sentinelTables } from './migrations/registry.js';
+export { SchemaAheadError, SchemaBehindError, ChecksumDriftError } from './migrations/errors.js';
+export type { Migration, MigrationKind, MigrationOptions } from './migrations/types.js';
+export { reconcile } from './reconcile.js';
+export type { ReconcileOptions, ReconcileReport, ReconcileDiskFile } from './reconcile.js';
+export { contentHash } from './hash.js';
 import type { TenantContext } from '@kybernesis/brain-contracts';
 export type DbKind = 'timeline' | 'entityGraph' | 'vectors' | 'sleep' | 'idempotency';
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAWhE,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACnG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;AAgBtF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAevE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOjD;AAED,wBAAgB,QAAQ,IAAI,IAAI,CAK/B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAWhE,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAKnG,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,QAAQ,IAAI,iBAAiB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjG,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAIxF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;AAkBtF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CA2BvE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOjD;AAED,wBAAgB,QAAQ,IAAI,IAAI,CAK/B"}

package/dist/index.js

@@ -16,7 +16,24 @@ export { resetEntityGraphSchemaCache } from './entity-graph.js';
 // any module on this cycle — either would TDZ-throw on import
 // ('Cannot access getDb before initialization').
 export { ensureSleepSchema, recoverStaleSleepRuns, resetSleepSchemaCache } from './sleep-store.js';
+// Migration surface (Spec A). runMigrations is a STANDALONE primitive — the
+// trigger is consumer-chosen: local apps opt in via setAutoMigrate / the
+// provider's autoMigrate option; Arcana serving runs mode:'check' and its
+// migrator job drives mode:'apply' per tenant.
+export { runMigrations } from './migrations/runner.js';
+export { copyFileBackup } from './migrations/backup.js';
+export { setAutoMigrate } from './migrations/config.js';
+export { registry as migrationRegistry, sentinelTables } from './migrations/registry.js';
+export { SchemaAheadError, SchemaBehindError, ChecksumDriftError } from './migrations/errors.js';
+// File provenance + reconcile (Spec B). reconcile() is report-only by default;
+// repair/removeOrphaned are explicit opt-ins. Consumers wire storeConversation
+// into opts.reingest (the library never ingests on its own).
+export { reconcile } from './reconcile.js';
+export { contentHash } from './hash.js';
+import { runMigrations } from './migrations/runner.js';
+import { getAutoMigrate } from './migrations/config.js';
 const pool = new Map();
+const MIGRATABLE_KINDS = ['timeline', 'entityGraph', 'sleep', 'vectors'];
 function resolveDbPath(t, kind) {
     switch (kind) {
         case 'timeline': return t.paths.timelineDbPath;
@@ -45,6 +62,21 @@ export function getDb(t, kind) {
     db.pragma('journal_mode = WAL');
     db.pragma('synchronous = NORMAL');
     db.pragma('foreign_keys = ON');
+    // After PRAGMAs, before first use — and before pooling, so a refused DB
+    // (SchemaAheadError / SchemaBehindError) is closed, not cached half-open.
+    const autoMigrate = getAutoMigrate();
+    if (autoMigrate && MIGRATABLE_KINDS.includes(kind)) {
+        try {
+            runMigrations(db, kind, autoMigrate);
+        }
+        catch (err) {
+            try {
+                db.close();
+            }
+            catch { /* ignore */ }
+            throw err;
+        }
+    }
     pool.set(key, db);
     return db;
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/migrations/backup.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Local backup strategy: WAL-checkpoint then copy the DB file to
+ * `<name>.pre-<firstPendingId>.bak` beside it, BEFORE any migration applies.
+ *
+ * This is the default for local consumers (KBDE / KyberBot). Cloud (Arcana)
+ * injects its own hook — snapshot or no-op — via `MigrationOptions.backup`;
+ * per-file `.bak` copies don't fit N-tenant scale.
+ *
+ * Must run OUTSIDE the migration transaction: `wal_checkpoint` cannot execute
+ * while a transaction is open. The runner guarantees this ordering.
+ */
+import type Database from 'better-sqlite3';
+export declare function copyFileBackup(db: Database.Database, firstPendingId: string): void;
+//# sourceMappingURL=backup.d.ts.map

package/dist/migrations/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/migrations/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAKlF"}

package/dist/migrations/backup.js

@@ -0,0 +1,20 @@
+/**
+ * Local backup strategy: WAL-checkpoint then copy the DB file to
+ * `<name>.pre-<firstPendingId>.bak` beside it, BEFORE any migration applies.
+ *
+ * This is the default for local consumers (KBDE / KyberBot). Cloud (Arcana)
+ * injects its own hook — snapshot or no-op — via `MigrationOptions.backup`;
+ * per-file `.bak` copies don't fit N-tenant scale.
+ *
+ * Must run OUTSIDE the migration transaction: `wal_checkpoint` cannot execute
+ * while a transaction is open. The runner guarantees this ordering.
+ */
+import { copyFileSync } from 'node:fs';
+export function copyFileBackup(db, firstPendingId) {
+    if (db.memory)
+        return; // nothing on disk to back up (tests / ephemeral DBs)
+    // Fold the WAL into the main file so the copy is complete and self-contained.
+    db.pragma('wal_checkpoint(TRUNCATE)');
+    copyFileSync(db.name, `${db.name}.pre-${firstPendingId}.bak`);
+}
+//# sourceMappingURL=backup.js.map

package/dist/migrations/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../../src/migrations/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,MAAM,UAAU,cAAc,CAAC,EAAqB,EAAE,cAAsB;IAC1E,IAAI,EAAE,CAAC,MAAM;QAAE,OAAO,CAAC,qDAAqD;IAC5E,8EAA8E;IAC9E,EAAE,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,QAAQ,cAAc,MAAM,CAAC,CAAC;AAChE,CAAC"}

package/dist/migrations/config.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Auto-migrate trigger config (Spec A) — consumer-chosen, OFF by default.
+ *
+ * Lives in its own module (not index.ts) so provider.ts can import it without
+ * joining the index ↔ sleep-store eval-order cycle documented in index.ts.
+ *
+ * `true` → the local default: { mode:'apply', backup: copyFileBackup }
+ * (KBDE / KyberBot self-heal on open). Cloud serving (Arcana) passes
+ * { mode:'check' } — refuse ahead AND behind, never write schema.
+ */
+import type { MigrationOptions } from './types.js';
+export declare function setAutoMigrate(config: MigrationOptions | boolean | null): void;
+export declare function getAutoMigrate(): MigrationOptions | null;
+//# sourceMappingURL=config.d.ts.map

package/dist/migrations/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/migrations/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAI9E;AAED,wBAAgB,cAAc,IAAI,gBAAgB,GAAG,IAAI,CAExD"}

package/dist/migrations/config.js

@@ -0,0 +1,24 @@
+/**
+ * Auto-migrate trigger config (Spec A) — consumer-chosen, OFF by default.
+ *
+ * Lives in its own module (not index.ts) so provider.ts can import it without
+ * joining the index ↔ sleep-store eval-order cycle documented in index.ts.
+ *
+ * `true` → the local default: { mode:'apply', backup: copyFileBackup }
+ * (KBDE / KyberBot self-heal on open). Cloud serving (Arcana) passes
+ * { mode:'check' } — refuse ahead AND behind, never write schema.
+ */
+import { copyFileBackup } from './backup.js';
+let autoMigrateConfig = null;
+export function setAutoMigrate(config) {
+    if (config === true)
+        autoMigrateConfig = { mode: 'apply', backup: copyFileBackup };
+    else if (config === false || config === null)
+        autoMigrateConfig = null;
+    else
+        autoMigrateConfig = config;
+}
+export function getAutoMigrate() {
+    return autoMigrateConfig;
+}
+//# sourceMappingURL=config.js.map

package/dist/migrations/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/migrations/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,IAAI,iBAAiB,GAA4B,IAAI,CAAC;AAEtD,MAAM,UAAU,cAAc,CAAC,MAAyC;IACtE,IAAI,MAAM,KAAK,IAAI;QAAE,iBAAiB,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;SAC9E,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,IAAI;QAAE,iBAAiB,GAAG,IAAI,CAAC;;QAClE,iBAAiB,GAAG,MAAM,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,iBAAiB,CAAC;AAC3B,CAAC"}

package/dist/migrations/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Migration refusal errors (Spec A). All three are LOUD refusals — callers must
+ * never swallow them; a brain DB in an unexpected schema state is unusable
+ * until a human (or the migrator) intervenes.
+ */
+/** The DB has applied migration ids this build doesn't know — code is older than the schema. Refuse in BOTH modes. */
+export declare class SchemaAheadError extends Error {
+    readonly kind: string;
+    readonly unknownIds: readonly string[];
+    constructor(kind: string, unknownIds: readonly string[]);
+}
+/** Pending migrations exist but mode is 'check' (serving path must never mutate schema). */
+export declare class SchemaBehindError extends Error {
+    readonly kind: string;
+    readonly pendingIds: readonly string[];
+    constructor(kind: string, pendingIds: readonly string[]);
+}
+/** An applied migration's recorded checksum no longer matches this build's body — a shipped migration was edited. */
+export declare class ChecksumDriftError extends Error {
+    readonly kind: string;
+    readonly id: string;
+    constructor(kind: string, id: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/migrations/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/migrations/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sHAAsH;AACtH,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,IAAI,EAAE,MAAM;aACZ,UAAU,EAAE,SAAS,MAAM,EAAE;gBAD7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,MAAM,EAAE;CAShD;AAED,4FAA4F;AAC5F,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,IAAI,EAAE,MAAM;aACZ,UAAU,EAAE,SAAS,MAAM,EAAE;gBAD7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,MAAM,EAAE;CAShD;AAED,qHAAqH;AACrH,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAAE,MAAM;aACZ,EAAE,EAAE,MAAM;gBADV,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM;CAS7B"}

package/dist/migrations/errors.js

@@ -0,0 +1,45 @@
+/**
+ * Migration refusal errors (Spec A). All three are LOUD refusals — callers must
+ * never swallow them; a brain DB in an unexpected schema state is unusable
+ * until a human (or the migrator) intervenes.
+ */
+/** The DB has applied migration ids this build doesn't know — code is older than the schema. Refuse in BOTH modes. */
+export class SchemaAheadError extends Error {
+    kind;
+    unknownIds;
+    constructor(kind, unknownIds) {
+        super(`[brain-storage-sqlite] ${kind} DB schema is AHEAD of this build — ` +
+            `unknown applied migration(s): ${unknownIds.join(', ')}. ` +
+            `Upgrade the consumer; refusing to touch the DB.`);
+        this.kind = kind;
+        this.unknownIds = unknownIds;
+        this.name = 'SchemaAheadError';
+    }
+}
+/** Pending migrations exist but mode is 'check' (serving path must never mutate schema). */
+export class SchemaBehindError extends Error {
+    kind;
+    pendingIds;
+    constructor(kind, pendingIds) {
+        super(`[brain-storage-sqlite] ${kind} DB schema is BEHIND this build — ` +
+            `pending migration(s): ${pendingIds.join(', ')}. ` +
+            `Run the migrator (mode:'apply'); serving refuses to migrate.`);
+        this.kind = kind;
+        this.pendingIds = pendingIds;
+        this.name = 'SchemaBehindError';
+    }
+}
+/** An applied migration's recorded checksum no longer matches this build's body — a shipped migration was edited. */
+export class ChecksumDriftError extends Error {
+    kind;
+    id;
+    constructor(kind, id) {
+        super(`[brain-storage-sqlite] ${kind} migration '${id}' checksum mismatch — ` +
+            `a shipped migration was edited in place. Shipped migrations are immutable; ` +
+            `add a new migration instead.`);
+        this.kind = kind;
+        this.id = id;
+        this.name = 'ChecksumDriftError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/migrations/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/migrations/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sHAAsH;AACtH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAEvB;IACA;IAFlB,YACkB,IAAY,EACZ,UAA6B;QAE7C,KAAK,CACH,0BAA0B,IAAI,sCAAsC;YAClE,iCAAiC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC1D,iDAAiD,CACpD,CAAC;QAPc,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAmB;QAO7C,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAExB;IACA;IAFlB,YACkB,IAAY,EACZ,UAA6B;QAE7C,KAAK,CACH,0BAA0B,IAAI,oCAAoC;YAChE,yBAAyB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAClD,8DAA8D,CACjE,CAAC;QAPc,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAmB;QAO7C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,qHAAqH;AACrH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IACA;IAFlB,YACkB,IAAY,EACZ,EAAU;QAE1B,KAAK,CACH,0BAA0B,IAAI,eAAe,EAAE,wBAAwB;YACrE,6EAA6E;YAC7E,8BAA8B,CACjC,CAAC;QAPc,SAAI,GAAJ,IAAI,CAAQ;QACZ,OAAE,GAAF,EAAE,CAAQ;QAO1B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/migrations/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ordered migration registry, one line per DB kind (each DB file has its own
+ * `_migrations` table and version line). Append-only: new migrations go at the
+ * END of a kind's list; shipped entries are immutable (checksum-guarded).
+ */
+import type { Migration, MigrationKind } from './types.js';
+/**
+ * Legacy-detection signal per DB (baseline decision, Spec A T6): if this table
+ * exists but `_migrations` doesn't, the DB predates the migration system —
+ * stamp the baseline without running it. Each name is the oldest table that
+ * has existed in that DB since v1.
+ */
+export declare const sentinelTables: Readonly<Record<MigrationKind, string>>;
+export declare const registry: Readonly<Record<MigrationKind, readonly Migration[]>>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/migrations/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/migrations/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAKlE,CAAC;AAYF,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAC,CAK1E,CAAC"}

package/dist/migrations/registry.js

@@ -0,0 +1,34 @@
+/**
+ * Ordered migration registry, one line per DB kind (each DB file has its own
+ * `_migrations` table and version line). Append-only: new migrations go at the
+ * END of a kind's list; shipped entries are immutable (checksum-guarded).
+ */
+import { migration as fileProvenance } from './timeline/002-file-provenance.js';
+/**
+ * Legacy-detection signal per DB (baseline decision, Spec A T6): if this table
+ * exists but `_migrations` doesn't, the DB predates the migration system —
+ * stamp the baseline without running it. Each name is the oldest table that
+ * has existed in that DB since v1.
+ */
+export const sentinelTables = {
+    timeline: 'timeline_events',
+    entityGraph: 'entities',
+    sleep: 'sleep_runs',
+    vectors: 'chunk_meta',
+};
+/**
+ * `001-baseline` is a MARKER, not DDL: table creation stays owned by the lazy
+ * `ensure*Schema` paths (CREATE TABLE IF NOT EXISTS with current bodies).
+ * Discipline that follows: every real migration must ALSO update the matching
+ * CREATE body, so fresh DBs are born current (and get stamped as such).
+ */
+function baseline(db) {
+    return { id: '001-baseline', db, statements: [], baseline: true };
+}
+export const registry = {
+    timeline: [baseline('timeline'), fileProvenance],
+    entityGraph: [baseline('entityGraph')],
+    sleep: [baseline('sleep')],
+    vectors: [baseline('vectors')],
+};
+//# sourceMappingURL=registry.js.map

package/dist/migrations/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/migrations/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,SAAS,IAAI,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAA4C;IACrE,QAAQ,EAAE,iBAAiB;IAC3B,WAAW,EAAE,UAAU;IACvB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,YAAY;CACtB,CAAC;AAEF;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,EAAiB;IACjC,OAAO,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAA0D;IAC7E,QAAQ,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IAChD,WAAW,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IACtC,KAAK,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1B,OAAO,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;CAC/B,CAAC"}

package/dist/migrations/runner.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Migration runner core (Spec A — docs/specs/migration-capability.md).
+ *
+ * Each of the four brain DB files carries its own `_migrations` table tracking
+ * only that DB's migrations. The runner is a STANDALONE primitive — consumers
+ * choose the trigger (local getDb autoMigrate vs Arcana's per-tenant migrator);
+ * it must never be buried inside getDb.
+ */
+import type Database from 'better-sqlite3';
+import type { Migration, MigrationKind, MigrationOptions } from './types.js';
+type Registry = Partial<Record<MigrationKind, readonly Migration[]>>;
+/**
+ * Run (or check) the migration line for one DB. STANDALONE primitive — the
+ * trigger is consumer-chosen: local getDb passes `mode:'apply'` when
+ * `autoMigrate` is set; Arcana serving passes `mode:'check'`; Arcana's
+ * migrator job drives `mode:'apply'` per tenant.
+ *
+ * Ordering (deliberate deviation from the spec pseudocode, which drew backup
+ * inside the txn): the backup hook runs BEFORE the write transaction opens —
+ * `PRAGMA wal_checkpoint` cannot execute inside an open transaction. The
+ * applies themselves are atomic: one IMMEDIATE transaction, with the applied
+ * set re-read under the write lock so a concurrent opener no-ops instead of
+ * double-applying.
+ */
+export declare function runMigrations(db: Database.Database, kind: MigrationKind, opts: MigrationOptions & {
+    registry?: Registry;
+}): void;
+/** Create the `_migrations` ledger if absent. Idempotent. */
+export declare function ensureMigrationsTable(db: Database.Database): void;
+/** Applied migrations as id → checksum. */
+export declare function readApplied(db: Database.Database): Map<string, string>;
+/** Record a migration as applied. */
+export declare function record(db: Database.Database, m: Migration): void;
+/**
+ * Checksum of the migration's NORMALIZED SQL (whitespace-collapsed), not its
+ * JS source — formatting edits don't churn it; semantic edits do.
+ */
+export declare function checksumOf(m: Migration): string;
+/**
+ * Version a DB that has no `_migrations` table yet (baseline decision, T6):
+ *
+ * - LEGACY (sentinel table exists, no ledger): the DB was built by the old
+ *   CREATE-IF-NOT-EXISTS path → stamp `001-baseline` as applied WITHOUT
+ *   running it; later migrations stay pending and will apply normally.
+ * - FRESH (no sentinel, no ledger): the lazy `ensure*Schema` paths will create
+ *   the CURRENT schema after open, so stamp ALL registry ids as applied —
+ *   running an ALTER against tables that don't exist yet would crash, and the
+ *   fresh CREATE bodies already include every shipped migration's columns.
+ * - VERSIONED (ledger exists): untouched.
+ */
+export declare function baselineIfUnversioned(db: Database.Database, kind: MigrationKind, migrations: readonly Migration[]): void;
+/** The DB must not hold applied ids this build doesn't know (code older than schema). */
+export declare function assertNotAhead(kind: MigrationKind, applied: ReadonlyMap<string, string>, migrations: readonly Migration[]): void;
+/** Every applied id this build knows must still checksum-match — shipped migrations are immutable. */
+export declare function assertNoChecksumDrift(kind: MigrationKind, applied: ReadonlyMap<string, string>, migrations: readonly Migration[]): void;
+export {};
+//# sourceMappingURL=runner.d.ts.map

package/dist/migrations/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/migrations/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAI7E,KAAK,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,SAAS,EAAE,CAAC,CAAC,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,gBAAgB,GAAG;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC/C,IAAI,CAkCN;AAED,6DAA6D;AAC7D,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAQjE;AAED,2CAA2C;AAC3C,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAKtE;AAED,qCAAqC;AACrC,wBAAgB,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,SAAS,GAAG,IAAI,CAMhE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAG/C;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,IAAI,CAUN;AAQD,yFAAyF;AACzF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,IAAI,CAIN;AAED,sGAAsG;AACtG,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,IAAI,CAON"}

package/dist/migrations/runner.js

@@ -0,0 +1,141 @@
+/**
+ * Migration runner core (Spec A — docs/specs/migration-capability.md).
+ *
+ * Each of the four brain DB files carries its own `_migrations` table tracking
+ * only that DB's migrations. The runner is a STANDALONE primitive — consumers
+ * choose the trigger (local getDb autoMigrate vs Arcana's per-tenant migrator);
+ * it must never be buried inside getDb.
+ */
+import { createHash } from 'node:crypto';
+import { registry as defaultRegistry, sentinelTables } from './registry.js';
+import { SchemaAheadError, SchemaBehindError, ChecksumDriftError } from './errors.js';
+/**
+ * Run (or check) the migration line for one DB. STANDALONE primitive — the
+ * trigger is consumer-chosen: local getDb passes `mode:'apply'` when
+ * `autoMigrate` is set; Arcana serving passes `mode:'check'`; Arcana's
+ * migrator job drives `mode:'apply'` per tenant.
+ *
+ * Ordering (deliberate deviation from the spec pseudocode, which drew backup
+ * inside the txn): the backup hook runs BEFORE the write transaction opens —
+ * `PRAGMA wal_checkpoint` cannot execute inside an open transaction. The
+ * applies themselves are atomic: one IMMEDIATE transaction, with the applied
+ * set re-read under the write lock so a concurrent opener no-ops instead of
+ * double-applying.
+ */
+export function runMigrations(db, kind, opts) {
+    const migrations = (opts.registry ?? defaultRegistry)[kind] ?? [];
+    if (opts.mode === 'check') {
+        // Serving path: NEVER write — not even the ledger table. A DB with no
+        // ledger and a non-empty registry is behind (everything pending), which
+        // includes a fresh tenant DB: serving refuses until the migrator runs.
+        const applied = migrationsTableExists(db) ? readApplied(db) : new Map();
+        assertNotAhead(kind, applied, migrations);
+        assertNoChecksumDrift(kind, applied, migrations);
+        const pending = migrations.filter((m) => !applied.has(m.id));
+        if (pending.length)
+            throw new SchemaBehindError(kind, pending.map((m) => m.id));
+        return;
+    }
+    baselineIfUnversioned(db, kind, migrations);
+    ensureMigrationsTable(db);
+    const applied = readApplied(db);
+    assertNotAhead(kind, applied, migrations);
+    assertNoChecksumDrift(kind, applied, migrations);
+    const pending = migrations.filter((m) => !applied.has(m.id));
+    if (pending.length === 0)
+        return;
+    opts.backup?.(db, pending[0].id);
+    db.transaction(() => {
+        const appliedNow = readApplied(db); // re-check under the write lock (race loser no-ops)
+        for (const m of pending) {
+            if (appliedNow.has(m.id))
+                continue;
+            for (const sql of m.statements)
+                db.exec(sql);
+            m.backfill?.(db);
+            record(db, m);
+        }
+    }).immediate();
+}
+/** Create the `_migrations` ledger if absent. Idempotent. */
+export function ensureMigrationsTable(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS _migrations (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL,
+      checksum TEXT NOT NULL
+    )`);
+}
+/** Applied migrations as id → checksum. */
+export function readApplied(db) {
+    const rows = db
+        .prepare(`SELECT id, checksum FROM _migrations`)
+        .all();
+    return new Map(rows.map((r) => [r.id, r.checksum]));
+}
+/** Record a migration as applied. */
+export function record(db, m) {
+    db.prepare(`INSERT INTO _migrations (id, applied_at, checksum) VALUES (?, ?, ?)`).run(m.id, new Date().toISOString(), checksumOf(m));
+}
+/**
+ * Checksum of the migration's NORMALIZED SQL (whitespace-collapsed), not its
+ * JS source — formatting edits don't churn it; semantic edits do.
+ */
+export function checksumOf(m) {
+    const normalized = m.statements.map(normalizeSql).join('\n');
+    return createHash('sha256').update(normalized).digest('hex');
+}
+function normalizeSql(sql) {
+    return sql.trim().replace(/\s+/g, ' ');
+}
+function migrationsTableExists(db) {
+    return !!db
+        .prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='_migrations'`)
+        .get();
+}
+/**
+ * Version a DB that has no `_migrations` table yet (baseline decision, T6):
+ *
+ * - LEGACY (sentinel table exists, no ledger): the DB was built by the old
+ *   CREATE-IF-NOT-EXISTS path → stamp `001-baseline` as applied WITHOUT
+ *   running it; later migrations stay pending and will apply normally.
+ * - FRESH (no sentinel, no ledger): the lazy `ensure*Schema` paths will create
+ *   the CURRENT schema after open, so stamp ALL registry ids as applied —
+ *   running an ALTER against tables that don't exist yet would crash, and the
+ *   fresh CREATE bodies already include every shipped migration's columns.
+ * - VERSIONED (ledger exists): untouched.
+ */
+export function baselineIfUnversioned(db, kind, migrations) {
+    if (migrations.length === 0)
+        return;
+    if (migrationsTableExists(db))
+        return;
+    const legacy = tableExists(db, sentinelTables[kind]);
+    db.transaction(() => {
+        ensureMigrationsTable(db);
+        const toStamp = legacy ? migrations.filter((m) => m.baseline) : migrations;
+        for (const m of toStamp)
+            record(db, m);
+    }).immediate();
+}
+function tableExists(db, name) {
+    return !!db
+        .prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?`)
+        .get(name);
+}
+/** The DB must not hold applied ids this build doesn't know (code older than schema). */
+export function assertNotAhead(kind, applied, migrations) {
+    const known = new Set(migrations.map((m) => m.id));
+    const unknown = [...applied.keys()].filter((id) => !known.has(id));
+    if (unknown.length)
+        throw new SchemaAheadError(kind, unknown);
+}
+/** Every applied id this build knows must still checksum-match — shipped migrations are immutable. */
+export function assertNoChecksumDrift(kind, applied, migrations) {
+    for (const m of migrations) {
+        const recorded = applied.get(m.id);
+        if (recorded !== undefined && recorded !== checksumOf(m)) {
+            throw new ChecksumDriftError(kind, m.id);
+        }
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/migrations/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/migrations/runner.ts"],"names":[],"mappings":"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"}

package/dist/migrations/timeline/002-file-provenance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Spec B (docs/specs/file-provenance-and-reconcile.md): file provenance.
+ *
+ * Adds the mutable LOCATOR (`file_path`, relative path, type='file' rows only)
+ * and the VERSION fingerprint (`content_hash` = sha256 of raw file bytes) to
+ * timeline_events. Stable identity (random source_path / chunk origin_id) is
+ * deliberately untouched — separating identity from locator is what makes a
+ * rename a one-row UPDATE.
+ *
+ * The unique index is PARTIAL: conversation rows keep file_path NULL in any
+ * number; non-NULL paths are unique (the dual-key upsert rides on it — proven
+ * in partial-upsert.spike.test.ts on better-sqlite3 + libsql).
+ *
+ * Backfill stamps file_path from the legacy `title` ("… File: <relpath>") —
+ * in-DB only, no file reads; content_hash stays NULL on legacy rows (the first
+ * reconcile run stamps it lazily). DEDUPE-AWARE: legacy brains can hold
+ * duplicate rows for the same file (the pile-up bug Spec B fixes) — stamping
+ * all of them would violate the new unique index and roll back the whole
+ * migration, so only the NEWEST row (MAX(id)) per title gets the locator;
+ * older duplicates stay NULL and remain reachable by source_path.
+ */
+import type { Migration } from '../types.js';
+export declare const migration: Migration;
+//# sourceMappingURL=002-file-provenance.d.ts.map

package/dist/migrations/timeline/002-file-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"002-file-provenance.d.ts","sourceRoot":"","sources":["../../../src/migrations/timeline/002-file-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,eAAO,MAAM,SAAS,EAAE,SAoBvB,CAAC"}