@kybernesis/brain-storage-sqlite 0.8.4 → 0.10.0

package/dist/migrations/timeline/002-file-provenance.js

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export const migration = {
+    id: '002-file-provenance',
+    db: 'timeline',
+    statements: [
+        `ALTER TABLE timeline_events ADD COLUMN file_path TEXT`,
+        `ALTER TABLE timeline_events ADD COLUMN content_hash TEXT`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS idx_timeline_file_path
+       ON timeline_events(file_path) WHERE file_path IS NOT NULL`,
+    ],
+    backfill(db) {
+        db.exec(`
+      UPDATE timeline_events
+      SET file_path = substr(title, instr(title, 'File: ') + 6)
+      WHERE id IN (
+        SELECT MAX(id) FROM timeline_events
+        WHERE type = 'file' AND file_path IS NULL AND title LIKE '%File: %'
+        GROUP BY title
+      )
+    `);
+    },
+};
+//# sourceMappingURL=002-file-provenance.js.map

package/dist/migrations/timeline/002-file-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"002-file-provenance.js","sourceRoot":"","sources":["../../../src/migrations/timeline/002-file-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,CAAC,MAAM,SAAS,GAAc;IAClC,EAAE,EAAE,qBAAqB;IACzB,EAAE,EAAE,UAAU;IACd,UAAU,EAAE;QACV,uDAAuD;QACvD,0DAA0D;QAC1D;iEAC6D;KAC9D;IACD,QAAQ,CAAC,EAAE;QACT,EAAE,CAAC,IAAI,CAAC;;;;;;;;KAQP,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/migrations/timeline/002-proof.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Proof migration (Spec A T8 / C9): a trivial additive column purely to
+ * exercise the runner end-to-end against a copy of a real brain.
+ *
+ * Deliberately NOT in the default registry — shipping a probe column to every
+ * consumer has no value. The real-brain regression test injects it via
+ * `opts.registry`; the first SHIPPED migration will be Spec B's provenance
+ * columns (which must also update the matching ensure*Schema CREATE body —
+ * see registry.ts).
+ */
+import type { Migration } from '../types.js';
+export declare const proofMigration: Migration;
+//# sourceMappingURL=002-proof.d.ts.map

package/dist/migrations/timeline/002-proof.d.ts.map

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

package/dist/migrations/timeline/002-proof.js

@@ -0,0 +1,16 @@
+/**
+ * Proof migration (Spec A T8 / C9): a trivial additive column purely to
+ * exercise the runner end-to-end against a copy of a real brain.
+ *
+ * Deliberately NOT in the default registry — shipping a probe column to every
+ * consumer has no value. The real-brain regression test injects it via
+ * `opts.registry`; the first SHIPPED migration will be Spec B's provenance
+ * columns (which must also update the matching ensure*Schema CREATE body —
+ * see registry.ts).
+ */
+export const proofMigration = {
+    id: '002-proof',
+    db: 'timeline',
+    statements: ['ALTER TABLE timeline_events ADD COLUMN _migration_probe TEXT'],
+};
+//# sourceMappingURL=002-proof.js.map

package/dist/migrations/timeline/002-proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"002-proof.js","sourceRoot":"","sources":["../../../src/migrations/timeline/002-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,EAAE,EAAE,WAAW;IACf,EAAE,EAAE,UAAU;IACd,UAAU,EAAE,CAAC,8DAA8D,CAAC;CAC7E,CAAC"}

package/dist/migrations/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Schema migration types (Spec A — docs/specs/migration-capability.md).
+ *
+ * A migration is a small, named, immutable-once-shipped module. Its DDL is
+ * DECLARATIVE (`statements`), not an imperative `up(db)` — the runner executes
+ * the statements in order. Declarative SQL keeps the checksum honest (we hash
+ * the normalized SQL, not JS source) and stays dialect-portable for a future
+ * libsql/Turso backend (Arcana).
+ *
+ * MVP constraint: statements must be ADDITIVE (`ALTER TABLE ... ADD COLUMN`,
+ * `CREATE TABLE/INDEX IF NOT EXISTS`) — no drop/rewrite. Table-rebuild
+ * migrations are out of MVP scope.
+ */
+import type Database from 'better-sqlite3';
+/**
+ * The four brain DBs that carry migrations. Subset of `DbKind` in index.ts
+ * (same spelling — `entityGraph`, not `entity-graph`); `idempotency` is a
+ * cache-shaped DB with no migration line.
+ */
+export type MigrationKind = 'timeline' | 'entityGraph' | 'sleep' | 'vectors';
+export interface Migration {
+    /** Ordered + named, e.g. '002-add-file-provenance'. NEVER edit after release (checksum guards it). */
+    readonly id: string;
+    /** Which DB file this migration belongs to (each carries its own _migrations table). */
+    readonly db: MigrationKind;
+    /** Plain-SQLite DDL, executed in order inside the migration transaction. Checksummed. */
+    readonly statements: readonly string[];
+    /**
+     * Marks the no-op baseline marker (one per kind, by convention `001-baseline`).
+     * On a LEGACY unversioned DB (sentinel table present, no `_migrations`), only
+     * baseline-flagged entries are stamped as applied without running.
+     */
+    readonly baseline?: boolean;
+    /** Optional data backfill — idempotent, resumable; runs after `statements` in the same txn. */
+    backfill?(db: Database.Database): void;
+}
+export interface MigrationOptions {
+    /**
+     * 'apply'  — advance schema (local consumers: KBDE / KyberBot via autoMigrate;
+     *            Arcana's migrator job per-tenant).
+     * 'check'  — never write; throw SchemaBehindError on pending (Arcana serving path).
+     * Refuse-when-ahead applies in BOTH modes.
+     */
+    mode: 'apply' | 'check';
+    /**
+     * Invoked once before the first pending migration applies (apply mode only).
+     * Local: copyFileBackup (WAL checkpoint + `<name>.pre-<firstPendingId>.bak`).
+     * Cloud: snapshot hook or no-op.
+     */
+    backup?: (db: Database.Database, firstPendingId: string) => void;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/migrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,SAAS;IACxB,sGAAsG;IACtG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE"}

package/dist/migrations/types.js

@@ -0,0 +1,15 @@
+/**
+ * Schema migration types (Spec A — docs/specs/migration-capability.md).
+ *
+ * A migration is a small, named, immutable-once-shipped module. Its DDL is
+ * DECLARATIVE (`statements`), not an imperative `up(db)` — the runner executes
+ * the statements in order. Declarative SQL keeps the checksum honest (we hash
+ * the normalized SQL, not JS source) and stays dialect-portable for a future
+ * libsql/Turso backend (Arcana).
+ *
+ * MVP constraint: statements must be ADDITIVE (`ALTER TABLE ... ADD COLUMN`,
+ * `CREATE TABLE/INDEX IF NOT EXISTS`) — no drop/rewrite. Table-rebuild
+ * migrations are out of MVP scope.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/migrations/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/migrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/provider.d.ts

@@ -10,7 +10,17 @@
  * corresponding brain-core module; behaviour is held constant.
  */
 import type { StorageProvider } from '@kybernesis/brain-contracts';
-/** Reset the lazy vec-store cache (test/utility). */
-export declare function resetLazyVectorStore(): void;
-export declare function createSqliteStorageProvider(): StorageProvider;
+import type { MigrationOptions } from './migrations/types.js';
+export { resetLazyVectorStore } from './vec-lazy.js';
+export interface SqliteStorageProviderOptions {
+    /**
+     * Migration trigger (Spec A) — consumer-chosen, off when omitted.
+     * `true` → local default `{ mode:'apply', backup: copyFileBackup }` (KBDE /
+     * KyberBot: self-heal on open). Cloud serving (Arcana) passes
+     * `{ mode:'check' }` — refuse ahead AND behind, never write; its migrator
+     * job calls `runMigrations` standalone per tenant.
+     */
+    autoMigrate?: boolean | MigrationOptions;
+}
+export declare function createSqliteStorageProvider(options?: SqliteStorageProviderOptions): StorageProvider;
 //# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,6BAA6B,CAAC;AAgCrC,qDAAqD;AACrD,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AA6BD,wBAAgB,2BAA2B,IAAI,eAAe,CAiB7D"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAa9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;CAC1C;AAED,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,4BAAiC,GACzC,eAAe,CAoBjB"}

package/dist/provider.js

@@ -9,6 +9,7 @@
  * The SQL that lands here is moved verbatim (port-faithful) from the
  * corresponding brain-core module; behaviour is held constant.
  */
+import { setAutoMigrate } from './migrations/config.js';
 import { sqliteFactStore } from './fact-store.js';
 import { sqliteTimelineStore } from './timeline.js';
 import { sqliteEntityGraphStore } from './entity-graph.js';
@@ -16,64 +17,15 @@ import { sqliteSleepStore } from './sleep-store.js';
 import { sqliteSleepMaintenance } from './sleep-maintenance.js';
 import { sqliteSearchQueries } from './search-queries.js';
 import { sqliteFactRetrievalQueries } from './fact-retrieval-queries.js';
-// ─── Lazy vector store ────────────────────────────────────────────────────────
-// VectorRepository is a first-class member of the bundle (decision #3 Option A), but
-// brain-storage-vec carries the sqlite-vec NATIVE binary. We load it lazily on
-// first vector use so it never costs apps anything at provider-creation time,
-// and brain-storage-sqlite keeps NO static dependency on sqlite-vec. If the
-// package can't be loaded (not installed / wrong platform), the store degrades
-// to safe no-ops — brain-core's vectors layer maps these to its graceful results.
-let _vecStore = null;
-let _vecAttempted = false;
-async function loadVecStore() {
-    if (_vecAttempted)
-        return _vecStore;
-    _vecAttempted = true;
-    try {
-        const mod = await import('@kybernesis/brain-storage-vec');
-        _vecStore = mod.sqliteVecStore;
+// Lazy vector store lives in vec-lazy.ts (Spec B: timeline.ts also needs it
+// for cluster cleanup, and importing provider.ts from timeline.ts would close
+// the documented eval-order cycle). Re-exported here for API compatibility.
+import { lazyVectorStore } from './vec-lazy.js';
+export { resetLazyVectorStore } from './vec-lazy.js';
+export function createSqliteStorageProvider(options = {}) {
+    if (options.autoMigrate !== undefined) {
+        setAutoMigrate(options.autoMigrate);
     }
-    catch {
-        _vecStore = null;
-    }
-    return _vecStore;
-}
-/** Reset the lazy vec-store cache (test/utility). */
-export function resetLazyVectorStore() {
-    _vecStore = null;
-    _vecAttempted = false;
-}
-const lazyVectorStore = {
-    async available(t) {
-        const s = await loadVecStore();
-        return s ? s.available(t) : false;
-    },
-    async hasOrigin(t, originId) {
-        const s = await loadVecStore();
-        if (!s)
-            return false;
-        return s.hasOrigin(t, originId);
-    },
-    async insertChunk(t, chunk) {
-        const s = await loadVecStore();
-        if (!s)
-            throw new Error('[brain-storage-sqlite] vector backend unavailable');
-        return s.insertChunk(t, chunk);
-    },
-    async search(t, embedding, limit) {
-        const s = await loadVecStore();
-        if (!s)
-            return [];
-        return s.search(t, embedding, limit);
-    },
-    async stats(t) {
-        const s = await loadVecStore();
-        if (!s)
-            return { count: 0, available: false };
-        return s.stats(t);
-    },
-};
-export function createSqliteStorageProvider() {
     return {
         repositories: {
             timeline: sqliteTimelineStore,

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAEzE,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAarD,MAAM,UAAU,2BAA2B,CACzC,UAAwC,EAAE;IAE1C,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACtC,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IACD,OAAO;QACL,YAAY,EAAE;YACZ,QAAQ,EAAE,mBAAmB;YAC7B,QAAQ,EAAE,sBAAsB;YAChC,KAAK,EAAE,eAAe;YACtB,KAAK,EAAE,gBAAgB;YACvB,OAAO,EAAE,eAAe;SACzB;QACD,gFAAgF;QAChF,MAAM,EAAE;YACN,MAAM,EAAE,mBAAmB,EAAE,KAAK;YAClC,aAAa,EAAE,0BAA0B,EAAE,KAAK;YAChD,KAAK,EAAE,sBAAsB,EAAE,OAAO;SAEvC;KACF,CAAC;AACJ,CAAC"}

package/dist/reconcile.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Reconcile (Spec B) — diff the brain against the filesystem and converge.
+ * This is the capability that catches the 42-files class: files marked
+ * "synced" but silently absent from the brain.
+ *
+ * REPORT-ONLY by default: a plain run returns structured findings and makes no
+ * destructive change. The one write a report run performs is the documented
+ * lazy baseline (resolved decision #2): a legacy row with NULL content_hash
+ * whose file exists on disk gets the CURRENT file's hash stamped and is
+ * classified up-to-date — trusting the present file as baseline avoids a full
+ * re-embed of every legacy row.
+ *
+ * Classification:
+ *   missing  — on disk, no brain row          (→ repair: re-ingest via callback)
+ *   stale    — both, hashes differ            (→ repair: re-ingest via callback)
+ *   orphaned — brain row, no file on disk     (→ removeOrphaned: delete cluster)
+ *   renamed  — a missing path whose hash equals an orphaned row's hash
+ *              (→ repair: ONE file_path UPDATE — cluster, enrichment, and
+ *               embeddings all survive; no re-ingest, no re-embed)
+ *
+ * Rename-and-edit is NOT detected (hashes differ) — it degrades to the
+ * missing + orphaned pair, i.e. add + remove. Documented limitation.
+ *
+ * Re-ingest is delegated to `opts.reingest` because ingestion is brain-core's
+ * pipeline (LLM extraction + embedding) and the dependency points the other
+ * way. The consumer (KBDE/KyberBot sweep, Arcana job) wires storeConversation
+ * into it — see the spec's consumer-integration section.
+ *
+ * Filesystem truth = the walked roots; the watched-folders manifest is never
+ * consulted. Dotfiles and dot-directories are skipped.
+ */
+import type { TenantContext } from '@kybernesis/brain-contracts';
+export interface ReconcileDiskFile {
+    file_path: string;
+    absolute_path: string;
+    content_hash: string;
+}
+export interface ReconcileReport {
+    missing: ReconcileDiskFile[];
+    stale: Array<ReconcileDiskFile & {
+        id: number;
+        brain_hash: string;
+    }>;
+    orphaned: Array<{
+        id: number;
+        file_path: string;
+        content_hash: string | null;
+    }>;
+    renamed: Array<{
+        id: number;
+        from: string;
+        to: string;
+    }>;
+    /** Legacy NULL-hash rows stamped with the current file's hash this run. */
+    baselined: number;
+    /** Files seen on disk across all roots. */
+    scanned: number;
+    /** Actions actually performed (empty unless repair/removeOrphaned). */
+    repaired: {
+        relabelled: number;
+        reingested: number;
+        removed: number;
+    };
+}
+export interface ReconcileOptions {
+    /** Filesystem roots to walk; brain file_paths are relative to one of these. */
+    roots: string[];
+    /** Apply renames (relabel) and re-ingest missing/stale via `reingest`. */
+    repair?: boolean;
+    /** Delete orphaned rows + their clusters. Destructive — explicitly opt-in. */
+    removeOrphaned?: boolean;
+    /** Consumer-provided ingest (brain-core storeConversation wired by the consumer). */
+    reingest?: (file: ReconcileDiskFile) => Promise<void>;
+}
+export declare function reconcile(t: TenantContext, opts: ReconcileOptions): Promise<ReconcileReport>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAKjE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC,iBAAiB,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAChF,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAkBD,wBAAsB,SAAS,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqElG"}

package/dist/reconcile.js

@@ -0,0 +1,120 @@
+/**
+ * Reconcile (Spec B) — diff the brain against the filesystem and converge.
+ * This is the capability that catches the 42-files class: files marked
+ * "synced" but silently absent from the brain.
+ *
+ * REPORT-ONLY by default: a plain run returns structured findings and makes no
+ * destructive change. The one write a report run performs is the documented
+ * lazy baseline (resolved decision #2): a legacy row with NULL content_hash
+ * whose file exists on disk gets the CURRENT file's hash stamped and is
+ * classified up-to-date — trusting the present file as baseline avoids a full
+ * re-embed of every legacy row.
+ *
+ * Classification:
+ *   missing  — on disk, no brain row          (→ repair: re-ingest via callback)
+ *   stale    — both, hashes differ            (→ repair: re-ingest via callback)
+ *   orphaned — brain row, no file on disk     (→ removeOrphaned: delete cluster)
+ *   renamed  — a missing path whose hash equals an orphaned row's hash
+ *              (→ repair: ONE file_path UPDATE — cluster, enrichment, and
+ *               embeddings all survive; no re-ingest, no re-embed)
+ *
+ * Rename-and-edit is NOT detected (hashes differ) — it degrades to the
+ * missing + orphaned pair, i.e. add + remove. Documented limitation.
+ *
+ * Re-ingest is delegated to `opts.reingest` because ingestion is brain-core's
+ * pipeline (LLM extraction + embedding) and the dependency points the other
+ * way. The consumer (KBDE/KyberBot sweep, Arcana job) wires storeConversation
+ * into it — see the spec's consumer-integration section.
+ *
+ * Filesystem truth = the walked roots; the watched-folders manifest is never
+ * consulted. Dotfiles and dot-directories are skipped.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDb } from './index.js';
+import { contentHash } from './hash.js';
+import { sqliteTimelineStore } from './timeline.js';
+function walk(dir, relBase, acc) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const abs = join(dir, entry.name);
+        const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            walk(abs, rel, acc);
+        }
+        else if (entry.isFile()) {
+            // first root wins on cross-root relpath collision
+            if (!acc.has(rel)) {
+                acc.set(rel, { file_path: rel, absolute_path: abs, content_hash: contentHash(readFileSync(abs)) });
+            }
+        }
+    }
+}
+export async function reconcile(t, opts) {
+    const onDisk = new Map();
+    for (const root of opts.roots)
+        walk(root, '', onDisk);
+    const brainRows = await sqliteTimelineStore.listAllFilePaths(t);
+    const db = getDb(t, 'timeline');
+    const stampHash = db.prepare(`UPDATE timeline_events SET content_hash = ? WHERE id = ?`);
+    let baselined = 0;
+    const stale = [];
+    const orphaned = [];
+    const brainPaths = new Set();
+    for (const row of brainRows) {
+        brainPaths.add(row.file_path);
+        const disk = onDisk.get(row.file_path);
+        if (!disk) {
+            orphaned.push(row);
+        }
+        else if (row.content_hash === null) {
+            stampHash.run(disk.content_hash, row.id); // lazy baseline: trust the current file
+            baselined++;
+        }
+        else if (row.content_hash !== disk.content_hash) {
+            stale.push({ ...disk, id: row.id, brain_hash: row.content_hash });
+        }
+    }
+    let missing = [...onDisk.values()].filter((f) => !brainPaths.has(f.file_path));
+    // Rename detection: a missing path whose content matches an orphaned row's
+    // hash is the same file under a new name — relocate the LOCATOR, keep the
+    // cluster. (Requires the orphaned row to carry a hash; legacy NULL-hash
+    // orphans can't match and stay orphaned.)
+    const renamed = [];
+    const orphanByHash = new Map();
+    for (const o of orphaned)
+        if (o.content_hash)
+            orphanByHash.set(o.content_hash, o);
+    missing = missing.filter((m) => {
+        const o = orphanByHash.get(m.content_hash);
+        if (!o)
+            return true;
+        renamed.push({ id: o.id, from: o.file_path, to: m.file_path });
+        orphanByHash.delete(m.content_hash);
+        orphaned.splice(orphaned.indexOf(o), 1);
+        return false;
+    });
+    const repaired = { relabelled: 0, reingested: 0, removed: 0 };
+    if (opts.repair) {
+        const relabel = db.prepare(`UPDATE timeline_events SET file_path = ? WHERE id = ?`);
+        for (const r of renamed) {
+            relabel.run(r.to, r.id);
+            repaired.relabelled++;
+        }
+        if (opts.reingest) {
+            for (const f of [...missing, ...stale]) {
+                await opts.reingest(f);
+                repaired.reingested++;
+            }
+        }
+    }
+    if (opts.removeOrphaned) {
+        for (const o of orphaned) {
+            await sqliteTimelineStore.removeFileCluster(t, o.file_path, { removeEvent: true });
+            repaired.removed++;
+        }
+    }
+    return { missing, stale, orphaned, renamed, baselined, scanned: onDisk.size, repaired };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconcile.js.map

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

package/dist/timeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAOV,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AAwDrC,iEAAiE;AACjE,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAG5D;AAuGD,eAAO,MAAM,mBAAmB,EAAE,kBAiNjC,CAAC"}
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAOV,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AA6DrC,iEAAiE;AACjE,wBAAgB,wBAAwB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAG5D;AA2GD,eAAO,MAAM,mBAAmB,EAAE,kBAoRjC,CAAC"}

package/dist/timeline.js

@@ -6,6 +6,7 @@
  */
 import { getDb } from './index.js';
 import { sanitizeFtsQuery } from './fts-sanitizer.js';
+import { lazyVectorStore } from './vec-lazy.js';
 function rowToEvent(row) {
     return {
         id: row.id,
@@ -29,6 +30,8 @@ function rowToEvent(row) {
         classification: row.classification ?? undefined,
         connection_id: row.connection_id ?? undefined,
         source_did: row.source_did ?? undefined,
+        file_path: row.file_path ?? undefined,
+        content_hash: row.content_hash ?? undefined,
     };
 }
 const initialized = new Set();
@@ -65,7 +68,9 @@ function ensureSchema(t) {
       project_id TEXT,
       classification TEXT,
       connection_id TEXT,
-      source_did TEXT
+      source_did TEXT,
+      file_path TEXT,
+      content_hash TEXT
     );
 
     CREATE INDEX IF NOT EXISTS idx_timeline_timestamp ON timeline_events(timestamp);
@@ -77,6 +82,8 @@ function ensureSchema(t) {
     CREATE INDEX IF NOT EXISTS idx_timeline_project ON timeline_events(project_id);
     CREATE INDEX IF NOT EXISTS idx_timeline_classification ON timeline_events(classification);
     CREATE INDEX IF NOT EXISTS idx_timeline_connection ON timeline_events(connection_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_timeline_file_path
+      ON timeline_events(file_path) WHERE file_path IS NOT NULL;
 
     CREATE VIRTUAL TABLE IF NOT EXISTS timeline_fts USING fts5(
       title, summary, entities, topics, content='',
@@ -145,13 +152,13 @@ export const sqliteTimelineStore = {
     async addEvent(t, event) {
         ensureSchema(t);
         const db = getDb(t, 'timeline');
-        const result = db.prepare(`
-      INSERT INTO timeline_events
-        (type, timestamp, end_timestamp, title, summary, source_path,
-         entities_json, topics_json,
-         project_id, tags_json, classification, connection_id, source_did)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(source_path) DO UPDATE SET
+        // Dual-key upsert (Spec B): file rows converge on file_path (the mutable
+        // locator), conversation rows on source_path — exactly as before. In the
+        // file branch the row ADOPTS the new ingest's source_path (the fresh
+        // facts/chunks cluster lives under it; exact-match cleanup removes the old
+        // one), while the row id and enrichment columns (priority, tier, decay,
+        // pin, access, last_enriched) persist by omission from the SET list.
+        const sharedSet = `
         type = excluded.type,
         timestamp = excluded.timestamp,
         end_timestamp = excluded.end_timestamp,
@@ -163,10 +170,60 @@ export const sqliteTimelineStore = {
         tags_json = COALESCE(excluded.tags_json, timeline_events.tags_json),
         classification = COALESCE(excluded.classification, timeline_events.classification),
         connection_id = COALESCE(excluded.connection_id, timeline_events.connection_id),
-        source_did = COALESCE(excluded.source_did, timeline_events.source_did)
-    `).run(event.type, event.timestamp, event.end_timestamp ?? null, event.title, event.summary ?? '', event.source_path, JSON.stringify(event.entities), JSON.stringify(event.topics), event.project_id ?? null, event.tags ? JSON.stringify(event.tags) : null, event.classification ?? null, event.connection_id ?? null, event.source_did ?? null);
+        source_did = COALESCE(excluded.source_did, timeline_events.source_did)`;
+        const conflictClause = event.file_path
+            ? `ON CONFLICT(file_path) WHERE file_path IS NOT NULL DO UPDATE SET
+           source_path = excluded.source_path,
+           content_hash = excluded.content_hash,${sharedSet}`
+            : `ON CONFLICT(source_path) DO UPDATE SET
+           file_path = COALESCE(excluded.file_path, timeline_events.file_path),
+           content_hash = COALESCE(excluded.content_hash, timeline_events.content_hash),${sharedSet}`;
+        const result = db.prepare(`
+      INSERT INTO timeline_events
+        (type, timestamp, end_timestamp, title, summary, source_path,
+         entities_json, topics_json,
+         project_id, tags_json, classification, connection_id, source_did,
+         file_path, content_hash)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ${conflictClause}
+    `).run(event.type, event.timestamp, event.end_timestamp ?? null, event.title, event.summary ?? '', event.source_path, JSON.stringify(event.entities), JSON.stringify(event.topics), event.project_id ?? null, event.tags ? JSON.stringify(event.tags) : null, event.classification ?? null, event.connection_id ?? null, event.source_did ?? null, event.file_path ?? null, event.content_hash ?? null);
         return result.lastInsertRowid;
     },
+    async removeFileCluster(t, filePath, opts = {}) {
+        ensureSchema(t);
+        const db = getDb(t, 'timeline');
+        // EXACT match only — the substring approach this replaces cross-deleted
+        // notes.md when re-ingesting meeting-notes.md (baseline bug #14).
+        const row = db
+            .prepare(`SELECT id, source_path FROM timeline_events WHERE file_path = ?`)
+            .get(filePath);
+        if (!row)
+            return { removed: false, facts: 0, chunks: 0 };
+        // source_path = channel://<channel>/<conversationId> — the cluster key.
+        const conversationId = row.source_path.split('/').pop() ?? '';
+        const facts = conversationId
+            ? db.prepare(`DELETE FROM facts WHERE source_conversation_id = ?`).run(conversationId).changes
+            : 0;
+        const chunks = conversationId
+            ? await lazyVectorStore.deleteByOriginPrefix(t, `${conversationId}_seg_`)
+            : 0;
+        if (opts.removeEvent) {
+            db.prepare(`DELETE FROM timeline_events WHERE id = ?`).run(row.id);
+        }
+        return { removed: true, facts, chunks };
+    },
+    async listAllFilePaths(t, opts = {}) {
+        ensureSchema(t);
+        const db = getDb(t, 'timeline');
+        return db
+            .prepare(`
+        SELECT id, file_path, content_hash FROM timeline_events
+        WHERE type = 'file' AND file_path IS NOT NULL AND id > ?
+        ORDER BY id ASC
+        LIMIT ?
+      `)
+            .all(opts.afterId ?? 0, opts.limit ?? -1);
+    },
     async removeEventByPath(t, sourcePath) {
         ensureSchema(t);
         const db = getDb(t, 'timeline');