@kybernesis/brain-storage-sqlite 0.2.0 → 0.6.0

package/dist/provider.js

@@ -0,0 +1,93 @@
+/**
+ * SQLite StorageProvider — the default backend wired by brain-core's seam.
+ *
+ * The persistence stores (timeline, entities, facts) + the minimal sleep read +
+ * the lazy vector store are all real as of 0.3.0. The sleep maintenance engine,
+ * hybrid-search, and fact-retrieval remain on guarded direct getDb (deferred to
+ * 0.4.0 — see docs/specs/storage-architecture-0.3-and-0.4.md).
+ *
+ * The SQL that lands here is moved verbatim (port-faithful) from the
+ * corresponding brain-core module; behaviour is held constant.
+ */
+import { sqliteFactStore } from './fact-store.js';
+import { sqliteTimelineStore } from './timeline.js';
+import { sqliteEntityGraphStore } from './entity-graph.js';
+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;
+    }
+    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,
+            entities: sqliteEntityGraphStore,
+            facts: sqliteFactStore,
+            sleep: sqliteSleepStore,
+            vectors: lazyVectorStore,
+        },
+        // Business plane — populated per gate (U1 search, U2 fact-retrieval, U3 sleep).
+        domain: {
+            search: sqliteSearchQueries, // U1
+            factRetrieval: sqliteFactRetrievalQueries, // U2
+            sleep: sqliteSleepMaintenance, // U3b+
+        },
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/search-queries.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SearchQueries (SQLite impl) — the hybrid-search candidate/factor SQL.
+ *
+ * Business plane (gate U1 of the 0.6.0 untangle). The SQL here moved VERBATIM
+ * from brain-core/hybrid-search.ts; behaviour is held constant. Only candidate
+ * generation + score-factor fetches live here — the scoring itself (RRF fusion,
+ * metadata weights, tier boosts, segment dedup) stays in brain-core.
+ *
+ * Each method is tolerant of a bad FTS token / missing column exactly as the
+ * original inline code was (try/catch → []), so parity holds.
+ */
+import type { SearchQueries } from '@kybernesis/brain-contracts';
+export declare const sqliteSearchQueries: SearchQueries;
+//# sourceMappingURL=search-queries.d.ts.map

package/dist/search-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-queries.d.ts","sourceRoot":"","sources":["../src/search-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,aAAa,EAId,MAAM,6BAA6B,CAAC;AAIrC,eAAO,MAAM,mBAAmB,EAAE,aA0EjC,CAAC"}

package/dist/search-queries.js

@@ -0,0 +1,84 @@
+/**
+ * SearchQueries (SQLite impl) — the hybrid-search candidate/factor SQL.
+ *
+ * Business plane (gate U1 of the 0.6.0 untangle). The SQL here moved VERBATIM
+ * from brain-core/hybrid-search.ts; behaviour is held constant. Only candidate
+ * generation + score-factor fetches live here — the scoring itself (RRF fusion,
+ * metadata weights, tier boosts, segment dedup) stays in brain-core.
+ *
+ * Each method is tolerant of a bad FTS token / missing column exactly as the
+ * original inline code was (try/catch → []), so parity holds.
+ */
+import { getDb } from './index.js';
+import { sanitizeFtsQuery } from './fts-sanitizer.js';
+export const sqliteSearchQueries = {
+    async temporalCandidates(t, term, limit) {
+        const db = getDb(t, 'timeline');
+        try {
+            const like = `%${term.toLowerCase()}%`;
+            return db.prepare(`
+        SELECT id, title, summary, source_path, timestamp, type
+        FROM timeline_events
+        WHERE LOWER(title) LIKE ? OR LOWER(summary) LIKE ?
+        ORDER BY timestamp DESC LIMIT ?
+      `).all(like, like, limit);
+        }
+        catch {
+            return []; // best-effort, matching the original inline behaviour
+        }
+    },
+    async metadataCandidates(t, query, limit) {
+        // Bug Fix #2: sanitize so hyphens / unicode / FTS5 reserved tokens don't throw.
+        const ftsQuery = sanitizeFtsQuery(query);
+        if (!ftsQuery)
+            return [];
+        const db = getDb(t, 'timeline');
+        try {
+            return db.prepare(`
+        SELECT t.id, t.source_path, t.title, t.summary, t.type, t.timestamp,
+               t.tier, t.priority, t.tags_json
+        FROM timeline_events t
+        JOIN timeline_fts fts ON t.id = fts.rowid
+        WHERE timeline_fts MATCH ? ORDER BY rank LIMIT ?
+      `).all(ftsQuery, limit);
+        }
+        catch {
+            return []; // FTS query failed (e.g. bad token) — candidates stays []
+        }
+    },
+    async entityAugmentedCandidates(t, query) {
+        const out = [];
+        try {
+            const db = getDb(t, 'timeline');
+            const entityDb = getDb(t, 'entityGraph');
+            const queryLower = query.toLowerCase();
+            const allEntities = entityDb.prepare('SELECT id, name FROM entities ORDER BY mention_count DESC LIMIT 100').all();
+            const matched = allEntities.filter(e => queryLower.includes(e.name.toLowerCase()) && e.name.length >= 3);
+            for (const ent of matched.slice(0, 3)) {
+                const mentions = entityDb.prepare('SELECT DISTINCT source_path FROM entity_mentions WHERE entity_id = ? ORDER BY timestamp DESC LIMIT 10').all(ent.id);
+                for (const m of mentions) {
+                    const event = db.prepare('SELECT id, title, summary, source_path, timestamp, type FROM timeline_events WHERE source_path = ?').get(m.source_path);
+                    if (event)
+                        out.push(event);
+                }
+            }
+        }
+        catch (err) {
+            console.warn('[brain-storage-sqlite/search] entity augmentation failed', { err: String(err) });
+        }
+        return out;
+    },
+    async enrichByPath(t, sourcePath) {
+        const db = getDb(t, 'timeline');
+        try {
+            const row = db.prepare(`
+        SELECT tier, priority, tags_json, entities_json FROM timeline_events WHERE source_path = ?
+      `).get(sourcePath);
+            return row ?? null;
+        }
+        catch {
+            return null; // non-critical
+        }
+    },
+};
+//# sourceMappingURL=search-queries.js.map

package/dist/search-queries.js.map

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

package/dist/sleep-maintenance.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SleepMaintenance (SQLite impl) — the maintenance-engine policy encoded IN SQL.
+ *
+ * Business plane (gate U3 of the 0.6.0 untangle). Only statements whose business
+ * heuristic lives inside the SQL itself land here (policy UPDATEs, normalization
+ * GROUP BYs, multi-clause prune WHEREs, unprocessed-detection NOT EXISTS) —
+ * relocated VERBATIM from the brain-core sleep steps; behaviour held constant.
+ * The scoring/decision JS stays in the steps.
+ *
+ * Grows green per sub-gate (U3b decay; U3d consolidate; U3e entity-hygiene;
+ * U3f summarize/observe). See docs/specs/storage-untangle-0.6.0-progress.md.
+ */
+import type { SleepMaintenance } from '@kybernesis/brain-contracts';
+export declare const sqliteSleepMaintenance: SleepMaintenance;
+//# sourceMappingURL=sleep-maintenance.d.ts.map

package/dist/sleep-maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-maintenance.d.ts","sourceRoot":"","sources":["../src/sleep-maintenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACK,gBAAgB,EAGhC,MAAM,6BAA6B,CAAC;AAGrC,eAAO,MAAM,sBAAsB,EAAE,gBAmOpC,CAAC"}

package/dist/sleep-maintenance.js

@@ -0,0 +1,227 @@
+/**
+ * SleepMaintenance (SQLite impl) — the maintenance-engine policy encoded IN SQL.
+ *
+ * Business plane (gate U3 of the 0.6.0 untangle). Only statements whose business
+ * heuristic lives inside the SQL itself land here (policy UPDATEs, normalization
+ * GROUP BYs, multi-clause prune WHEREs, unprocessed-detection NOT EXISTS) —
+ * relocated VERBATIM from the brain-core sleep steps; behaviour held constant.
+ * The scoring/decision JS stays in the steps.
+ *
+ * Grows green per sub-gate (U3b decay; U3d consolidate; U3e entity-hygiene;
+ * U3f summarize/observe). See docs/specs/storage-untangle-0.6.0-progress.md.
+ */
+import { getDb } from './index.js';
+export const sqliteSleepMaintenance = {
+    // ── decay: policy-bearing fact UPDATEs (U3b) ──
+    async expireTemporalFacts(t) {
+        const db = getDb(t, 'timeline');
+        const r = db.prepare(`
+      UPDATE facts SET is_latest = 0, updated_at = datetime('now')
+      WHERE expires_at IS NOT NULL
+        AND expires_at < datetime('now')
+        AND is_latest = 1
+    `).run();
+        return r.changes;
+    },
+    async lastFactConfidenceDecayAt(t) {
+        const db = getDb(t, 'timeline');
+        const row = db.prepare(`
+      SELECT MAX(updated_at) as last_decay FROM facts
+      WHERE updated_at IS NOT NULL AND confidence < 0.85
+    `).get();
+        return row?.last_decay ?? null;
+    },
+    async decayFactConfidence(t) {
+        const db = getDb(t, 'timeline');
+        const r = db.prepare(`
+      UPDATE facts
+      SET confidence = MAX(confidence * 0.95, 0.15),
+          updated_at = datetime('now')
+      WHERE source_type IN ('ai-extraction', 'chat')
+        AND created_at < datetime('now', '-90 days')
+        AND last_reinforced_at IS NULL
+        AND COALESCE(is_retracted, 0) = 0
+        AND confidence > 0.15
+        AND is_latest = 1
+    `).run();
+        return r.changes;
+    },
+    // ── consolidate: title-normalization grouping + merge (U3d; stays SQL) ──
+    async fetchConsolidationGroups(t, threshold, limit) {
+        const db = getDb(t, 'timeline');
+        // Normalization (strip `[channel] ` prefix + trailing `...`) is done IN SQL —
+        // decision 3: keep it SQL, relocated verbatim, parity-asserted. NOT JS.
+        return db.prepare(`
+      SELECT
+        TRIM(REPLACE(
+          CASE WHEN INSTR(title, '] ') > 0
+            THEN SUBSTR(title, INSTR(title, '] ') + 2)
+            ELSE title
+          END,
+          '...', ''
+        )) as normalized_title,
+        COUNT(*) as cnt,
+        GROUP_CONCAT(id) as ids,
+        MIN(timestamp) as first_ts,
+        MAX(timestamp) as last_ts
+      FROM timeline_events
+      WHERE (is_pinned IS NULL OR is_pinned = 0)
+      GROUP BY normalized_title
+      HAVING COUNT(*) >= ?
+      ORDER BY cnt DESC
+      LIMIT ?
+    `).all(threshold, limit);
+    },
+    async sumAccessCounts(t, ids) {
+        const db = getDb(t, 'timeline');
+        const placeholders = ids.map(() => '?').join(',');
+        const row = db.prepare(`
+      SELECT COALESCE(SUM(COALESCE(access_count, 0)), 0) as total
+      FROM timeline_events WHERE id IN (${placeholders})
+    `).get(...ids);
+        return row.total;
+    },
+    async consolidateInto(t, keepId, removeIds, addedAccess) {
+        const db = getDb(t, 'timeline');
+        const placeholders = removeIds.map(() => '?').join(',');
+        db.prepare(`
+      UPDATE timeline_events
+      SET access_count = COALESCE(access_count, 0) + ?,
+          last_accessed = datetime('now')
+      WHERE id = ?
+    `).run(addedAccess, keepId);
+        db.prepare(`
+      DELETE FROM timeline_events WHERE id IN (${placeholders})
+    `).run(...removeIds);
+    },
+    // ── entity-hygiene: policy filters (U3e) ──
+    async cleanOrphans(t) {
+        const db = getDb(t, 'entityGraph');
+        db.prepare(`
+      DELETE FROM entity_relations WHERE
+        source_id NOT IN (SELECT id FROM entities) OR
+        target_id NOT IN (SELECT id FROM entities)
+    `).run();
+        db.prepare(`
+      DELETE FROM entity_mentions WHERE
+        entity_id NOT IN (SELECT id FROM entities)
+    `).run();
+    },
+    async fetchAllEntities(t) {
+        const db = getDb(t, 'entityGraph');
+        return db.prepare('SELECT id, name, type, mention_count FROM entities').all();
+    },
+    async fetchSameNameGroups(t) {
+        const db = getDb(t, 'entityGraph');
+        return db.prepare(`
+      SELECT normalized_name,
+             GROUP_CONCAT(id        ORDER BY type) as ids,
+             GROUP_CONCAT(type      ORDER BY type) as types,
+             GROUP_CONCAT(name      ORDER BY type) as names,
+             GROUP_CONCAT(mention_count ORDER BY type) as mention_counts
+      FROM entities
+      GROUP BY normalized_name
+      HAVING COUNT(DISTINCT type) > 1
+    `).all();
+    },
+    async fetchVariantEntities(t, limit) {
+        const db = getDb(t, 'entityGraph');
+        return db.prepare(`
+      SELECT id, name, normalized_name, type, mention_count
+      FROM entities ORDER BY mention_count DESC, normalized_name ASC, type ASC LIMIT ?
+    `).all(limit);
+    },
+    async fetchEntityProfile(t, entityId) {
+        const db = getDb(t, 'entityGraph');
+        const mentions = db.prepare(`
+      SELECT context FROM entity_mentions
+      WHERE entity_id = ? AND context IS NOT NULL AND context != ''
+      ORDER BY timestamp DESC, context ASC LIMIT 5
+    `).all(entityId);
+        const related = db.prepare(`
+      SELECT DISTINCT e.name FROM entity_relations r
+      JOIN entities e ON (
+        (r.source_id = ? AND e.id = r.target_id) OR
+        (r.target_id = ? AND e.id = r.source_id)
+      )
+      ORDER BY r.strength DESC, e.name ASC LIMIT 10
+    `).all(entityId, entityId);
+        return {
+            contexts: mentions.map(m => m.context),
+            related: related.map(r => r.name),
+        };
+    },
+    async fetchPruneCandidates(t, pruneDate) {
+        const db = getDb(t, 'entityGraph');
+        // Bug B11B: ALL 5 filters must apply (omitting any over-prunes the graph).
+        return db.prepare(`
+      SELECT e.id, e.name, e.type, e.mention_count, e.last_seen, e.is_pinned
+      FROM entities e
+      WHERE e.mention_count <= 1
+        AND e.type = 'topic'
+        AND e.last_seen < ?
+        AND (e.is_pinned IS NULL OR e.is_pinned = 0)
+        AND NOT EXISTS (SELECT 1 FROM entity_relations WHERE source_id = e.id OR target_id = e.id)
+    `).all(pruneDate);
+    },
+    async fetchProfileCandidates(t, limit) {
+        const db = getDb(t, 'entityGraph');
+        // SQL verbatim from KAD entity-hygiene phase 5 — 3 columns, no mention_count.
+        return db.prepare(`
+      SELECT id, name, type FROM entities
+      WHERE mention_count >= 3
+      ORDER BY mention_count DESC, name ASC, type ASC LIMIT ?
+    `).all(limit);
+    },
+    // ── summarize + observe + reasoning: detection/heuristic SQL (U3f) ──
+    async fetchStaleSummaryIds(t, limit) {
+        const db = getDb(t, 'timeline');
+        const rows = db.prepare(`
+      SELECT id FROM timeline_events
+      WHERE (summary IS NULL
+             OR length(summary) < 50
+             OR summary LIKE '{%'
+             OR summary LIKE '# %'
+             OR length(summary) > 500)
+        AND (last_enriched IS NULL OR last_enriched < datetime('now', '-3 days'))
+      ORDER BY priority DESC
+      LIMIT ?
+    `).all(limit);
+        return rows.map(r => r.id);
+    },
+    async fetchUnprocessedConversations(t, limit) {
+        const db = getDb(t, 'timeline');
+        return db.prepare(`
+      SELECT te.id, te.source_path, te.title, te.summary, te.timestamp,
+             te.entities_json, te.topics_json
+      FROM timeline_events te
+      WHERE te.type = 'conversation'
+        AND te.summary IS NOT NULL
+        AND LENGTH(te.summary) > 50
+        AND NOT EXISTS (
+          SELECT 1 FROM timeline_events obs
+          WHERE obs.source_path LIKE 'observation://' || REPLACE(te.source_path, 'channel://', '') || '/%'
+        )
+        AND NOT EXISTS (
+          SELECT 1 FROM facts f
+          WHERE f.source_path LIKE 'fact://' || REPLACE(te.source_path, 'channel://', '') || '/%'
+        )
+        AND NOT EXISTS (
+          SELECT 1 FROM facts f
+          WHERE f.source_path LIKE 'realtime://' || REPLACE(te.source_path, 'channel://', '') || '/%'
+        )
+      ORDER BY te.timestamp DESC
+      LIMIT ?
+    `).all(limit);
+    },
+    async fetchEntityCooccurrence(t, entityId, limit) {
+        const db = getDb(t, 'entityGraph');
+        return db.prepare(`
+      SELECT e2.name, er.strength FROM entity_relations er
+      JOIN entities e2 ON e2.id = CASE WHEN er.source_id = ? THEN er.target_id ELSE er.source_id END
+      WHERE (er.source_id = ? OR er.target_id = ?) AND er.strength > 1
+      ORDER BY er.strength DESC LIMIT ?
+    `).all(entityId, entityId, entityId, limit);
+    },
+};
+//# sourceMappingURL=sleep-maintenance.js.map

package/dist/sleep-maintenance.js.map

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

package/dist/sleep-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SleepRepository (SQLite impl) — CRUD/persistence for the maintenance engine.
+ *
+ * The cohesive sleep store (decision 1): each method opens whichever DB kind it
+ * needs. As of U3a it carries the run lifecycle (sleep_runs), checkpoints,
+ * telemetry, schema bootstrap, and the existing memory_edges read. The
+ * per-step CRUD (tier/decay/link/queue/event reads+writes) lands at U3b–U3f.
+ *
+ * SQL moved VERBATIM from brain-core/sleep/{db,index,utils/checkpoint}.ts;
+ * behaviour held constant.
+ */
+import type Database from 'better-sqlite3';
+import type { TenantContext, SleepRepository } from '@kybernesis/brain-contracts';
+/**
+ * Ensure the sleep schema exists; returns the pooled sleep handle.
+ *
+ * This is the PUBLIC re-export surface (brain-core/sleep/db.ts re-exports it),
+ * kept handle-returning for 0.5.0 API parity (U4 decision A: frozen public API).
+ * The sleep ENGINE no longer consumes the handle — 0.6.0 routes every step
+ * through the seam — so a future release can deprecate the handle return. Lives
+ * HERE (storage package) so brain-core/src stays free of raw getDb.
+ */
+export declare function ensureSleepSchema(t: TenantContext): Database.Database;
+/** Reap >2h-old 'running' rows to 'failed'; returns rows changed. (public re-export) */
+export declare function recoverStaleSleepRuns(t: TenantContext): number;
+/** Reset the per-tenant schema-init cache. (public re-export; test/utility) */
+export declare function resetSleepSchemaCache(slug?: string): void;
+export declare const sqliteSleepStore: SleepRepository;
+//# sourceMappingURL=sleep-store.d.ts.map

package/dist/sleep-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-store.d.ts","sourceRoot":"","sources":["../src/sleep-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EACV,aAAa,EAAE,eAAe,EAI/B,MAAM,6BAA6B,CAAC;AAmFrC;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,aAAa,GAAG,QAAQ,CAAC,QAAQ,CAOrE;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAW9D;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAGzD;AAED,eAAO,MAAM,gBAAgB,EAAE,eAkR9B,CAAC"}