opensquid 0.5.395

package/dist/rag/backends/libsql_store.js

@@ -0,0 +1,246 @@
+/**
+ * Generalized libSQL RAG backend: libsql storage + an INJECTED `Embedder` (hybrid semantic +
+ * lexical via RRF). The body is the former `libsql_qwen3` backend with the embedder extracted
+ * (T-STORE-FOUNDATION-LIBSQL): `libsql-qwen3` now wires the Ollama-Qwen3 embedder into this,
+ * `libsql-fastembed` wires the in-process fastembed embedder. One backend body, any embedder.
+ *
+ * Schema (libsql vector ext, @libsql/client 0.14): `F32_BLOB(dim)` stores 32-bit float vectors
+ * (`dim` from `embedder.dim`); `vector32('[...]')` parses a JSON array; `vector_distance_cos`
+ * returns `1 - cosine_similarity`; `libsql_vector_idx(col)` builds the DiskANN ANN index.
+ *
+ * Imports from: @libsql/client, ../rrf.js, ../embedders/types.js, ../types.js.
+ * Imported by: src/rag/backend_factory.ts.
+ */
+import { createClient } from '@libsql/client';
+import { rrfFuse } from '../rrf.js';
+import { deleteRecord, readRecords, writeRecord } from './perfile_source.js';
+import { inScope, UserAuthoredImmunityError } from '../types.js';
+export function libsqlStoreBackend(opts) {
+    let client = null;
+    const { embedder } = opts;
+    return {
+        async init() {
+            client = createClient({ url: opts.dbUrl });
+            await client.execute(`
+        CREATE TABLE IF NOT EXISTS lessons (
+          id TEXT PRIMARY KEY,
+          content TEXT NOT NULL,
+          tags TEXT NOT NULL,
+          source TEXT NOT NULL,
+          author TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          derived_from TEXT NOT NULL DEFAULT '[]',
+          consumed_by_user_lessons INTEGER NOT NULL DEFAULT 0,
+          tier TEXT NOT NULL DEFAULT 'shared',
+          namespace TEXT,
+          embedding F32_BLOB(${embedder.dim})
+        );
+      `);
+            // Additive scope columns for pre-existing DBs (CREATE TABLE IF NOT EXISTS won't add them).
+            // Idempotent: a duplicate-column error means an already-migrated DB; any other error surfaces later.
+            for (const ddl of [
+                `ALTER TABLE lessons ADD COLUMN tier TEXT NOT NULL DEFAULT 'shared'`,
+                `ALTER TABLE lessons ADD COLUMN namespace TEXT`,
+            ]) {
+                try {
+                    await client.execute(ddl);
+                }
+                catch {
+                    /* already migrated */
+                }
+            }
+            await client.execute(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS lessons_fts
+        USING fts5(id UNINDEXED, content, tags, source);
+      `);
+            try {
+                await client.execute(`
+          CREATE INDEX IF NOT EXISTS idx_lessons_vec
+          ON lessons (libsql_vector_idx(embedding));
+        `);
+            }
+            catch {
+                // index is optional; ordering by vector_distance_cos still works.
+            }
+        },
+        embed: (text) => embedder.embed(text),
+        async recall(query, k, scope) {
+            if (!client)
+                throw new Error('libsql-store: not initialized');
+            const safeMatch = ftsEscape(query);
+            const vec = await embedder.embed(query);
+            const semantic = [];
+            const lexical = [];
+            // Scope filter at the STORE (the real boundary): a row is eligible iff it is `shared` OR its
+            // namespace matches the recall scope. A null scope namespace binds `namespace = NULL` (always
+            // false in SQL) → only `shared` rows match → fail-closed. `ns` is the bound param for both legs.
+            const ns = scope.namespace;
+            if (vec) {
+                try {
+                    const rs = await client.execute({
+                        sql: `SELECT id, content, tags, source, author, created_at, derived_from, consumed_by_user_lessons, tier, namespace
+                  FROM lessons
+                  WHERE embedding IS NOT NULL AND (tier = 'shared' OR namespace = ?)
+                  ORDER BY vector_distance_cos(embedding, vector32(?)) ASC
+                  LIMIT ?`,
+                        args: [ns, JSON.stringify(vec), k],
+                    });
+                    rs.rows.forEach((r, i) => semantic.push({ lesson: rowToLesson(r), score: 1 / (i + 1), source: 'semantic' }));
+                }
+                catch {
+                    // Vector path unavailable on this libsql build — proceed lexical-only.
+                }
+            }
+            // Empty / all-stripped query → skip lexical leg.
+            if (safeMatch) {
+                try {
+                    const lex = await client.execute({
+                        sql: `SELECT l.id, l.content, l.tags, l.source, l.author, l.created_at,
+                  l.derived_from, l.consumed_by_user_lessons, l.tier, l.namespace
+                  FROM lessons_fts f JOIN lessons l ON l.id = f.id
+                  WHERE lessons_fts MATCH ? AND (l.tier = 'shared' OR l.namespace = ?)
+                  LIMIT ?`,
+                        args: [safeMatch, ns, k],
+                    });
+                    lex.rows.forEach((r, i) => lexical.push({ lesson: rowToLesson(r), score: 1 / (i + 1), source: 'lexical' }));
+                }
+                catch {
+                    // Malformed FTS5 expression slipped through — return semantic only.
+                }
+            }
+            // Post-filter via the authoritative pure predicate — a backstop so the SQL WHERE and the rule
+            // can never silently diverge (defense in depth; the isolation test asserts both).
+            return rrfFuse([semantic, lexical], k).filter((h) => inScope(h.lesson.tier, h.lesson.namespace, scope));
+        },
+        async storeLesson(lesson) {
+            if (!client)
+                throw new Error('libsql-store: not initialized');
+            // File-first: write the per-file source-of-truth (atomic) before the derived DB index, so a
+            // crash leaves the durable git-versionable truth intact and the DB is reconstructable.
+            if (opts.sourceDir !== undefined)
+                await writeRecord(opts.sourceDir, lesson);
+            const vec = await embedder.embed(lesson.content);
+            const tagsJson = JSON.stringify(lesson.tags);
+            // Idempotent upsert by id: re-storing a lesson with the same id (e.g. a
+            // re-memorize of the same body — id is the content-hash) REPLACES the prior
+            // row instead of raising a PRIMARY KEY conflict. Delete-then-insert covers
+            // both the main table and the contentless FTS index (FTS5 has no PK for
+            // INSERT OR REPLACE to key on), keeping the two in lockstep.
+            await client.execute({ sql: `DELETE FROM lessons WHERE id = ?`, args: [lesson.id] });
+            await client.execute({ sql: `DELETE FROM lessons_fts WHERE id = ?`, args: [lesson.id] });
+            const derivedFromJson = JSON.stringify(lesson.derivedFrom ?? []);
+            const consumed = lesson.consumedByUserLessons ?? 0;
+            const tier = lesson.tier ?? 'shared';
+            const namespace = lesson.namespace ?? null;
+            await client.execute({
+                sql: `INSERT INTO lessons (id, content, tags, source, author, created_at, derived_from,
+              consumed_by_user_lessons, tier, namespace, embedding)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ${vec ? 'vector32(?)' : 'NULL'})`,
+                args: vec
+                    ? [
+                        lesson.id,
+                        lesson.content,
+                        tagsJson,
+                        lesson.source,
+                        lesson.author,
+                        lesson.createdAt,
+                        derivedFromJson,
+                        consumed,
+                        tier,
+                        namespace,
+                        JSON.stringify(vec),
+                    ]
+                    : [
+                        lesson.id,
+                        lesson.content,
+                        tagsJson,
+                        lesson.source,
+                        lesson.author,
+                        lesson.createdAt,
+                        derivedFromJson,
+                        consumed,
+                        tier,
+                        namespace,
+                    ],
+            });
+            await client.execute({
+                sql: `INSERT INTO lessons_fts (id, content, tags, source) VALUES (?, ?, ?, ?)`,
+                args: [lesson.id, lesson.content, tagsJson, lesson.source],
+            });
+        },
+        async deleteLesson(id, delOpts) {
+            if (!client)
+                throw new Error('libsql-store: not initialized');
+            const found = await client.execute({
+                sql: `SELECT author FROM lessons WHERE id = ?`,
+                args: [id],
+            });
+            if (found.rows.length === 0)
+                return { deleted: false, forced: false };
+            const isUser = found.rows[0]?.author === 'user';
+            const force = delOpts?.force ?? false;
+            if (isUser && !force)
+                throw new UserAuthoredImmunityError(id);
+            await client.execute({ sql: `DELETE FROM lessons WHERE id = ?`, args: [id] });
+            await client.execute({ sql: `DELETE FROM lessons_fts WHERE id = ?`, args: [id] });
+            // Remove the per-file source too, else a later rebuild would resurrect the row.
+            if (opts.sourceDir !== undefined)
+                await deleteRecord(opts.sourceDir, id);
+            return { deleted: true, forced: isUser && force };
+        },
+    };
+}
+/**
+ * Rebuild the libSQL index from the per-file source-of-truth (the files are authoritative; the
+ * DB is disposable). Drops + recreates the index tables first so records deleted from the source
+ * don't linger, then re-indexes every record. Idempotent — a crash mid-rebuild is recovered by
+ * re-running it (the source is never touched). Cold-path maintenance op (e.g. after a git
+ * pull/merge of the source); for file-backed `dbUrl`s, not `:memory:`.
+ */
+export async function rebuildLibsqlIndex(opts) {
+    const client = createClient({ url: opts.dbUrl });
+    await client.execute('DROP TABLE IF EXISTS lessons');
+    await client.execute('DROP TABLE IF EXISTS lessons_fts');
+    client.close();
+    // No sourceDir on the rebuild backend → storeLesson re-indexes the DB only (it must NOT
+    // rewrite the files it is reading from).
+    const backend = libsqlStoreBackend({ dbUrl: opts.dbUrl, embedder: opts.embedder });
+    await backend.init();
+    const records = await readRecords(opts.sourceDir);
+    for (const r of records)
+        await backend.storeLesson(r);
+    return records.length;
+}
+// FTS5 escape: tokenize on whitespace, strip non-`[\p{L}\p{N}_]`, OR the survivors. `''` means
+// the caller skips the lexical leg. Exported so the wedge lesson store (src/rag/wedge) reuses the
+// one FTS-escape rule instead of duplicating it.
+export function ftsEscape(query) {
+    const tokens = query
+        .split(/\s+/)
+        .map((t) => t.replace(/[^\p{L}\p{N}_]/gu, ''))
+        .filter((t) => t.length > 0);
+    return tokens.length === 0 ? '' : tokens.join(' OR ');
+}
+function s(r, key) {
+    const v = r[key];
+    return typeof v === 'string' ? v : '';
+}
+function n(r, key) {
+    const v = r[key];
+    return typeof v === 'number' ? v : typeof v === 'bigint' ? Number(v) : 0;
+}
+function rowToLesson(r) {
+    return {
+        id: s(r, 'id'),
+        content: s(r, 'content'),
+        tags: JSON.parse(s(r, 'tags') || '[]'),
+        source: s(r, 'source'),
+        author: s(r, 'author') === 'user' ? 'user' : 'agent',
+        createdAt: s(r, 'created_at'),
+        derivedFrom: JSON.parse(s(r, 'derived_from') || '[]'),
+        consumedByUserLessons: n(r, 'consumed_by_user_lessons'),
+        tier: s(r, 'tier') === 'project' ? 'project' : 'shared',
+        namespace: typeof r.namespace === 'string' ? r.namespace : null,
+    };
+}
+//# sourceMappingURL=libsql_store.js.map

package/dist/rag/backends/libsql_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"libsql_store.js","sourceRoot":"","sources":["../../../src/rag/backends/libsql_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAyB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE7E,OAAO,EAAE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAiBjE,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAE1B,OAAO;QACL,KAAK,CAAC,IAAI;YACR,MAAM,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAC3C,MAAM,MAAM,CAAC,OAAO,CAAC;;;;;;;;;;;;+BAYI,QAAQ,CAAC,GAAG;;OAEpC,CAAC,CAAC;YACH,2FAA2F;YAC3F,qGAAqG;YACrG,KAAK,MAAM,GAAG,IAAI;gBAChB,oEAAoE;gBACpE,+CAA+C;aAChD,EAAE,CAAC;gBACF,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC5B,CAAC;gBAAC,MAAM,CAAC;oBACP,sBAAsB;gBACxB,CAAC;YACH,CAAC;YACD,MAAM,MAAM,CAAC,OAAO,CAAC;;;OAGpB,CAAC,CAAC;YACH,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,OAAO,CAAC;;;SAGpB,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;YACpE,CAAC;QACH,CAAC;QAED,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAErC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK;YAC1B,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAC9D,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACxC,MAAM,QAAQ,GAAgB,EAAE,CAAC;YACjC,MAAM,OAAO,GAAgB,EAAE,CAAC;YAChC,6FAA6F;YAC7F,8FAA8F;YAC9F,iGAAiG;YACjG,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;YAE3B,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,CAAC;oBACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;wBAC9B,GAAG,EAAE;;;;0BAIS;wBACd,IAAI,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;qBACnC,CAAC,CAAC;oBACH,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAClF,CAAC;gBACJ,CAAC;gBAAC,MAAM,CAAC;oBACP,uEAAuE;gBACzE,CAAC;YACH,CAAC;YACD,iDAAiD;YACjD,IAAI,SAAS,EAAE,CAAC;gBACd,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;wBAC/B,GAAG,EAAE;;;;0BAIS;wBACd,IAAI,EAAE,CAAC,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;qBACzB,CAAC,CAAC;oBACH,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACxB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAChF,CAAC;gBACJ,CAAC;gBAAC,MAAM,CAAC;oBACP,oEAAoE;gBACtE,CAAC;YACH,CAAC;YAED,8FAA8F;YAC9F,kFAAkF;YAClF,OAAO,OAAO,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAClD,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAClD,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,MAAM;YACtB,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAC9D,4FAA4F;YAC5F,uFAAuF;YACvF,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;gBAAE,MAAM,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC5E,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC7C,wEAAwE;YACxE,4EAA4E;YAC5E,2EAA2E;YAC3E,wEAAwE;YACxE,6DAA6D;YAC7D,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,kCAAkC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACrF,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,sCAAsC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACzF,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,MAAM,CAAC,qBAAqB,IAAI,CAAC,CAAC;YACnD,MAAM,IAAI,GAAe,MAAM,CAAC,IAAI,IAAI,QAAQ,CAAC;YACjD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC;YAC3C,MAAM,MAAM,CAAC,OAAO,CAAC;gBACnB,GAAG,EAAE;;sDAEyC,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,GAAG;gBAC7E,IAAI,EAAE,GAAG;oBACP,CAAC,CAAC;wBACE,MAAM,CAAC,EAAE;wBACT,MAAM,CAAC,OAAO;wBACd,QAAQ;wBACR,MAAM,CAAC,MAAM;wBACb,MAAM,CAAC,MAAM;wBACb,MAAM,CAAC,SAAS;wBAChB,eAAe;wBACf,QAAQ;wBACR,IAAI;wBACJ,SAAS;wBACT,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;qBACpB;oBACH,CAAC,CAAC;wBACE,MAAM,CAAC,EAAE;wBACT,MAAM,CAAC,OAAO;wBACd,QAAQ;wBACR,MAAM,CAAC,MAAM;wBACb,MAAM,CAAC,MAAM;wBACb,MAAM,CAAC,SAAS;wBAChB,eAAe;wBACf,QAAQ;wBACR,IAAI;wBACJ,SAAS;qBACV;aACN,CAAC,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC;gBACnB,GAAG,EAAE,yEAAyE;gBAC9E,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;aAC3D,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,YAAY,CAAC,EAAU,EAAE,OAA6B;YAC1D,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAC9D,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;gBACjC,GAAG,EAAE,yCAAyC;gBAC9C,IAAI,EAAE,CAAC,EAAE,CAAC;aACX,CAAC,CAAC;YACH,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACtE,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;YAChD,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,KAAK,CAAC;YACtC,IAAI,MAAM,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,yBAAyB,CAAC,EAAE,CAAC,CAAC;YAC9D,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,kCAAkC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9E,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,sCAAsC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAClF,gFAAgF;YAChF,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;gBAAE,MAAM,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YACzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,IAAI,KAAK,EAAE,CAAC;QACpD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAIxC;IACC,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACjD,MAAM,MAAM,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;IACrD,MAAM,MAAM,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC;IACzD,MAAM,CAAC,KAAK,EAAE,CAAC;IACf,wFAAwF;IACxF,yCAAyC;IACzC,MAAM,OAAO,GAAG,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACnF,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IACrB,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC;AAED,+FAA+F;AAC/F,kGAAkG;AAClG,iDAAiD;AACjD,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,MAAM,GAAG,KAAK;SACjB,KAAK,CAAC,KAAK,CAAC;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;SAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,CAAC,CAAC,CAAM,EAAE,GAAW;IAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC;AACD,SAAS,CAAC,CAAC,CAAM,EAAE,GAAW;IAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC;AACD,SAAS,WAAW,CAAC,CAAM;IACzB,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;QACd,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;QACxB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,IAAI,CAAa;QAClD,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC;QACtB,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO;QACpD,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC;QAC7B,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,IAAI,IAAI,CAAa;QACjE,qBAAqB,EAAE,CAAC,CAAC,CAAC,EAAE,0BAA0B,CAAC;QACvD,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;QACvD,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;KAChE,CAAC;AACJ,CAAC"}

package/dist/rag/backends/loop_engine.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Loop-engine RAG backend — routes RagBackend through the engine daemon's
+ * JSON-RPC API (memory.search + memory.create) via the T.4 UDS singleton.
+ *
+ * Quality: `mode: 'hybrid'` invokes engine-side RRF fusion (K=60, Cormack
+ * et al. 2009) — drop-in equivalent to opensquid's `src/rag/rrf.ts:65`
+ * per T.1.JJ. No TS-side fusion needed; engine does it server-side over a
+ * larger native vector index than libsql's DiskANN.
+ *
+ * Critical design locks (T.1.B + T.1.#6):
+ *
+ *  1. **storeLesson → memory.create is INTENTIONAL, not a bug.** Routing
+ *     here through `lesson.create` would force every recall-pool write
+ *     through the wedge gate's 24h + applied_count=3 + external_signal
+ *     promotion requirements (per T.1.F — unsatisfiable in a single
+ *     write call, breaks unit tests). RagBackend.storeLesson semantically
+ *     stores a recallable memory, NOT a wedge-gated lesson; lesson
+ *     lifecycle is a separate surface added in T.6.
+ *
+ *  2. **Description synthesis is mandatory.** `memory.create` rejects
+ *     empty `description` (T.1.B INVALID_PARAMS -32602). Synthesized
+ *     from first sentence → first 80 chars → ultimate fallback. Lesson
+ *     shape doesn't carry a description field today, so we derive it.
+ *
+ *  3. **`include_body: true` on every recall.** memory.search's default
+ *     `body_preview` is truncated to 240 chars (engine serve.rs); without
+ *     this flag RecallHit.lesson.content gets cut mid-sentence.
+ *
+ *  4. **Source vocab mapping at the boundary.** Engine speaks
+ *     `'semantic' | 'text' | 'both'`; RagBackend's RecallHit speaks
+ *     `'semantic' | 'lexical' | 'fused'`. The adapter table is the
+ *     single point of translation — DO NOT leak engine vocab past it.
+ *
+ *  5. **Engine schema gap.** `memory.create` doesn't preserve tags /
+ *     source / author / createdAt today (T.8 follow-up filed). For v1
+ *     we send `description` + `content` only; lesson metadata round-trips
+ *     via the Lesson defaults applied by `src/functions/rag.ts:122-145`.
+ *
+ *  6. **No daemon lifecycle here.** `EngineClient` connects via the T.4
+ *     `acquireOrSpawnEngine()` singleton transparently — zero per-call
+ *     subprocess cost, cross-session shared engine.
+ *
+ * Imports from: ../../engine/client.js, ../ollama_client.js, ../types.js.
+ * Imported by: src/rag/backend_factory.ts.
+ */
+import { EngineClient } from '../../engine/client.js';
+import type { RagBackend } from '../types.js';
+export interface LoopEngineBackendOpts {
+    /** Injected client for tests; production uses the singleton-backed default. */
+    client?: EngineClient;
+    /** Recall mode. 'hybrid' = engine semantic+text+RRF (default, matches
+     *  libsql-qwen3 quality per T.1.JJ). 'semantic' = vector only. 'text' =
+     *  pure text-match. */
+    mode?: 'semantic' | 'text' | 'hybrid';
+    /** Ollama URL for embed() — only used when a rule asks for a raw vector
+     *  via the `embed` primitive. Engine handles embedding internally for
+     *  memory.create + memory.search. */
+    ollamaUrl?: string;
+}
+export declare function loopEngineBackend(opts?: LoopEngineBackendOpts): RagBackend;
+//# sourceMappingURL=loop_engine.d.ts.map

package/dist/rag/backends/loop_engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop_engine.d.ts","sourceRoot":"","sources":["../../../src/rag/backends/loop_engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAgB,YAAY,EAAY,MAAM,wBAAwB,CAAC;AAK9E,OAAO,KAAK,EAAwB,UAAU,EAAa,MAAM,aAAa,CAAC;AAE/E,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;2BAEuB;IACvB,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IACtC;;yCAEqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,qBAA0B,GAAG,UAAU,CAgF9E"}

package/dist/rag/backends/loop_engine.js

@@ -0,0 +1,160 @@
+/**
+ * Loop-engine RAG backend — routes RagBackend through the engine daemon's
+ * JSON-RPC API (memory.search + memory.create) via the T.4 UDS singleton.
+ *
+ * Quality: `mode: 'hybrid'` invokes engine-side RRF fusion (K=60, Cormack
+ * et al. 2009) — drop-in equivalent to opensquid's `src/rag/rrf.ts:65`
+ * per T.1.JJ. No TS-side fusion needed; engine does it server-side over a
+ * larger native vector index than libsql's DiskANN.
+ *
+ * Critical design locks (T.1.B + T.1.#6):
+ *
+ *  1. **storeLesson → memory.create is INTENTIONAL, not a bug.** Routing
+ *     here through `lesson.create` would force every recall-pool write
+ *     through the wedge gate's 24h + applied_count=3 + external_signal
+ *     promotion requirements (per T.1.F — unsatisfiable in a single
+ *     write call, breaks unit tests). RagBackend.storeLesson semantically
+ *     stores a recallable memory, NOT a wedge-gated lesson; lesson
+ *     lifecycle is a separate surface added in T.6.
+ *
+ *  2. **Description synthesis is mandatory.** `memory.create` rejects
+ *     empty `description` (T.1.B INVALID_PARAMS -32602). Synthesized
+ *     from first sentence → first 80 chars → ultimate fallback. Lesson
+ *     shape doesn't carry a description field today, so we derive it.
+ *
+ *  3. **`include_body: true` on every recall.** memory.search's default
+ *     `body_preview` is truncated to 240 chars (engine serve.rs); without
+ *     this flag RecallHit.lesson.content gets cut mid-sentence.
+ *
+ *  4. **Source vocab mapping at the boundary.** Engine speaks
+ *     `'semantic' | 'text' | 'both'`; RagBackend's RecallHit speaks
+ *     `'semantic' | 'lexical' | 'fused'`. The adapter table is the
+ *     single point of translation — DO NOT leak engine vocab past it.
+ *
+ *  5. **Engine schema gap.** `memory.create` doesn't preserve tags /
+ *     source / author / createdAt today (T.8 follow-up filed). For v1
+ *     we send `description` + `content` only; lesson metadata round-trips
+ *     via the Lesson defaults applied by `src/functions/rag.ts:122-145`.
+ *
+ *  6. **No daemon lifecycle here.** `EngineClient` connects via the T.4
+ *     `acquireOrSpawnEngine()` singleton transparently — zero per-call
+ *     subprocess cost, cross-session shared engine.
+ *
+ * Imports from: ../../engine/client.js, ../ollama_client.js, ../types.js.
+ * Imported by: src/rag/backend_factory.ts.
+ */
+import { ENGINE_ERROR, EngineClient, RpcError } from '../../engine/client.js';
+import { ollamaEmbed } from '../ollama_client.js';
+import { UserAuthoredImmunityError } from '../types.js';
+export function loopEngineBackend(opts = {}) {
+    const client = opts.client ?? new EngineClient();
+    const mode = opts.mode ?? 'hybrid';
+    const ollamaUrl = opts.ollamaUrl ?? 'http://localhost:11434';
+    return {
+        async init() {
+            // Ensures engine daemon is up + connected before any primitive call.
+            // Singleton handles spawn-or-acquire; ping confirms the handshake.
+            await client.ping();
+        },
+        async embed(text) {
+            // RagBackend contract says embedder-unavailable returns null, not
+            // throws (T.1.T). ollamaEmbed throws on HTTP / malformed response;
+            // we translate.
+            try {
+                return await ollamaEmbed(ollamaUrl, text);
+            }
+            catch {
+                return null;
+            }
+        },
+        async recall(query, k) {
+            const result = await client.memorySearch({
+                query,
+                limit: k,
+                mode,
+                include_body: true,
+            });
+            return result.results.map((h) => ({
+                lesson: {
+                    id: h.id,
+                    content: h.body_preview,
+                    tags: [],
+                    source: 'unknown',
+                    author: 'user',
+                    createdAt: '',
+                },
+                score: h.similarity,
+                source: mapEngineSource(h.source),
+            }));
+        },
+        async storeLesson(lesson) {
+            const description = synthesizeDescription(lesson.content);
+            await client.memoryCreate({
+                description,
+                content: lesson.content,
+                // Preserve eviction immunity across the write-path cutover: a `user`-authored memory must
+                // round-trip `authored_by` so the engine keeps it eviction-immune (else memorize→storeLesson
+                // would silently strip immunity). The string collapses to Lesson.author ('user'|'agent').
+                authored_by: lesson.author,
+            });
+        },
+        async deleteLesson(id, delOpts) {
+            try {
+                await client.memoryGet({ id }); // existence pre-check (NOT_FOUND → not-found result)
+            }
+            catch (e) {
+                if (e instanceof RpcError && e.code === ENGINE_ERROR.NOT_FOUND) {
+                    return { deleted: false, forced: false };
+                }
+                throw e;
+            }
+            try {
+                const result = await client.memoryDelete({
+                    id,
+                    ...(delOpts?.force === undefined ? {} : { force: delOpts.force }),
+                });
+                return { deleted: true, forced: result.forced };
+            }
+            catch (e) {
+                if (e instanceof RpcError && e.code === ENGINE_ERROR.USER_MEMORY_IMMUNE) {
+                    throw new UserAuthoredImmunityError(id);
+                }
+                throw e;
+            }
+        },
+    };
+}
+/**
+ * Derive a non-empty description from lesson content. Engine rejects
+ * empty descriptions with INVALID_PARAMS -32602 (T.1.B). Algorithm:
+ *   1. First sentence (split on `.!?\n`), trimmed, capped at 80 chars
+ *   2. Fallback: first 80 chars of raw content (for sentence-free text)
+ *   3. Ultimate fallback: `'untitled memory'` (empty-content edge case)
+ *
+ * 80 chars chosen to match engine's description display budget without
+ * truncation in `manifest.assemble` output (engine serve.rs body_preview).
+ */
+function synthesizeDescription(content) {
+    const firstSentence = content.split(/[.!?\n]/)[0]?.trim() ?? content;
+    return firstSentence.slice(0, 80) || content.slice(0, 80) || 'untitled memory';
+}
+/**
+ * Translate engine source vocabulary into RagBackend RecallHit vocabulary.
+ * Engine uses `'semantic' | 'text' | 'both'` (only present in hybrid
+ * results); opensquid uses `'semantic' | 'lexical' | 'fused'`. When
+ * engine omits source (non-hybrid modes), default to `'semantic'` —
+ * matches the dominant recall-from-vector path.
+ */
+function mapEngineSource(s) {
+    switch (s) {
+        case 'semantic':
+            return 'semantic';
+        case 'text':
+            return 'lexical';
+        case 'both':
+            return 'fused';
+        default:
+            return 'semantic';
+    }
+}
+//# sourceMappingURL=loop_engine.js.map

package/dist/rag/backends/loop_engine.js.map

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

package/dist/rag/backends/perfile_source.d.ts

@@ -0,0 +1,8 @@
+import type { Lesson } from '../types.js';
+/** Write `<dir>/<id>.md` atomically as `---`-fenced frontmatter + body. */
+export declare function writeRecord(dir: string, lesson: Lesson): Promise<void>;
+/** Remove `<dir>/<id>.md` (explicit deletion). Idempotent — a missing file is not an error. */
+export declare function deleteRecord(dir: string, id: string): Promise<void>;
+/** Read every `<dir>/*.md` record back into `Lesson[]`. Missing dir → `[]`. */
+export declare function readRecords(dir: string): Promise<Lesson[]>;
+//# sourceMappingURL=perfile_source.d.ts.map

package/dist/rag/backends/perfile_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perfile_source.d.ts","sourceRoot":"","sources":["../../../src/rag/backends/perfile_source.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5E;AAED,+FAA+F;AAC/F,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE;AAED,+EAA+E;AAC/E,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwChE"}

package/dist/rag/backends/perfile_source.js

@@ -0,0 +1,78 @@
+/**
+ * Per-file source-of-truth for the libSQL store (T-STORE-PERFILE-SOURCE, rewrite Phase 1 slice
+ * 1b). Each lesson is one `---`-fenced YAML-frontmatter + markdown-body file `<dir>/<id>.md` —
+ * the same SHAPE as the engine's `mem-*.md` (different field set: lessons carry tags/source/
+ * author). This per-file form is the git-versionable, mergeable truth (spike E3: per-file +
+ * atomic-claim = 0% git-merge conflict); the libSQL DB is a derived, rebuildable index.
+ *
+ * `writeRecord` writes ATOMICALLY (temp file + `rename`, atomic on POSIX) so a crash mid-write
+ * never leaves a partial/corrupt source file — which is what makes "file-first, DB derived"
+ * actually durable. `readRecords` parses the fenced form back to `Lesson` (the body is taken
+ * verbatim after the closing fence, so body content containing `---`/`:` never re-enters YAML).
+ *
+ * Imports from: node:fs/promises, node:path, yaml, ../types.js.
+ * Imported by: src/rag/backends/libsql_store.ts.
+ */
+import { readFile, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { atomicWriteFile, safeRecordId } from '../../storage/atomic_file.js';
+/** Write `<dir>/<id>.md` atomically as `---`-fenced frontmatter + body. */
+export async function writeRecord(dir, lesson) {
+    const frontmatter = stringifyYaml({
+        id: lesson.id,
+        tags: lesson.tags,
+        source: lesson.source,
+        author: lesson.author,
+        created_at: lesson.createdAt,
+        // Compression columns serialized ONLY when non-default, so regular-memory files stay
+        // byte-identical (no churn / no migration); only consolidated memories gain the keys.
+        ...(lesson.derivedFrom?.length ? { derived_from: lesson.derivedFrom } : {}),
+        ...(lesson.consumedByUserLessons
+            ? { consumed_by_user_lessons: lesson.consumedByUserLessons }
+            : {}),
+    });
+    await atomicWriteFile(join(dir, `${safeRecordId(lesson.id)}.md`), `---\n${frontmatter}---\n${lesson.content}`);
+}
+/** Remove `<dir>/<id>.md` (explicit deletion). Idempotent — a missing file is not an error. */
+export async function deleteRecord(dir, id) {
+    await rm(join(dir, `${safeRecordId(id)}.md`), { force: true });
+}
+/** Read every `<dir>/*.md` record back into `Lesson[]`. Missing dir → `[]`. */
+export async function readRecords(dir) {
+    let files;
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith('.md'));
+    }
+    catch {
+        return []; // no source dir yet
+    }
+    const out = [];
+    for (const f of files) {
+        const raw = await readFile(join(dir, f), 'utf8');
+        if (!raw.startsWith('---\n'))
+            continue;
+        const end = raw.indexOf('\n---\n', 4);
+        if (end === -1)
+            continue;
+        const fm = parseYaml(raw.slice(4, end + 1));
+        out.push({
+            id: fm.id ?? f.replace(/\.md$/, ''),
+            content: raw.slice(end + 5), // everything after the closing "\n---\n"
+            tags: Array.isArray(fm.tags) ? fm.tags : [],
+            source: fm.source ?? 'memory',
+            author: fm.author === 'user' ? 'user' : 'agent',
+            createdAt: fm.created_at ?? new Date(0).toISOString(),
+            // Compression keys included ONLY when present (mirrors writeRecord's non-default-only write),
+            // so a base-memory file round-trips to an object with no compression keys.
+            ...(Array.isArray(fm.derived_from) && fm.derived_from.length
+                ? { derivedFrom: fm.derived_from }
+                : {}),
+            ...(typeof fm.consumed_by_user_lessons === 'number' && fm.consumed_by_user_lessons
+                ? { consumedByUserLessons: fm.consumed_by_user_lessons }
+                : {}),
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=perfile_source.js.map

package/dist/rag/backends/perfile_source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perfile_source.js","sourceRoot":"","sources":["../../../src/rag/backends/perfile_source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAEtE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAI7E,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,MAAc;IAC3D,MAAM,WAAW,GAAG,aAAa,CAAC;QAChC,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,UAAU,EAAE,MAAM,CAAC,SAAS;QAC5B,qFAAqF;QACrF,sFAAsF;QACtF,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,MAAM,CAAC,qBAAqB;YAC9B,CAAC,CAAC,EAAE,wBAAwB,EAAE,MAAM,CAAC,qBAAqB,EAAE;YAC5D,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IACH,MAAM,eAAe,CACnB,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,EAC1C,QAAQ,WAAW,QAAQ,MAAM,CAAC,OAAO,EAAE,CAC5C,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAW,EAAE,EAAU;IACxD,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,oBAAoB;IACjC,CAAC;IACD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QACvC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QACtC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,SAAS;QACzB,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAQxC,CAAC;QACH,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;YACnC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,yCAAyC;YACtE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;YAC3C,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,QAAQ;YAC7B,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO;YAC/C,SAAS,EAAE,EAAE,CAAC,UAAU,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;YACrD,8FAA8F;YAC9F,2EAA2E;YAC3E,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,MAAM;gBAC1D,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,YAAY,EAAE;gBAClC,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,EAAE,CAAC,wBAAwB,KAAK,QAAQ,IAAI,EAAE,CAAC,wBAAwB;gBAChF,CAAC,CAAC,EAAE,qBAAqB,EAAE,EAAE,CAAC,wBAAwB,EAAE;gBACxD,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/rag/config.d.ts

@@ -0,0 +1,38 @@
+/**
+ * RAG backend configuration resolver.
+ *
+ * Decides which backend `buildRegistry()` instantiates for the host
+ * runtime. Resolution chain (first match wins):
+ *
+ *   1. `OPENSQUID_RAG_BACKEND` env var — explicit override (test seam +
+ *      user pinning). Accepts: `loop-engine` | `libsql-qwen3` |
+ *      `libsql-fastembed` | `libsql-lexical` | `claude-auto-memory`. Unknown
+ *      values surface as an error at boot rather than silently defaulting.
+ *   2. `~/.opensquid/rag-config.json` — persisted user choice. Same kind
+ *      vocabulary. Phase 1 ships read-only; setup wizard writes it.
+ *   3. Default: `loop-engine` when the engine binary is discoverable
+ *      via `resolveEngineBin()`; else `libsql-fastembed` (self-contained
+ *      in-process embedder — works out-of-box with NO Ollama; E2-validated
+ *      recall parity with Qwen3). `libsql-qwen3` stays available via override.
+ *
+ * The discoverability check is non-blocking — if the engine binary
+ * lookup throws, we fall back to libsql-fastembed with a stderr note. This
+ * keeps boot resilient to a half-migrated engine path while still
+ * preferring the engine when it's wired up correctly.
+ *
+ * Each variant's tunable opts (`dbUrl`, `ollamaUrl`, `mode`) accept
+ * config-file overrides. Sensible defaults baked in so a missing
+ * config file produces a working backend without any user setup.
+ *
+ * Imports from: ../engine/config.js, ./backend_factory.js.
+ * Imported by: src/runtime/bootstrap.ts.
+ */
+import type { BackendConfig } from './backend_factory.js';
+/**
+ * Resolve the backend config for `buildRegistry()`. Always returns a
+ * usable config — never null. Logs to stderr when falling back to the
+ * libsql default after an engine binary lookup miss so users see why
+ * their preferred backend isn't active.
+ */
+export declare function resolveBackendConfig(): Promise<BackendConfig>;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/rag/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAwB1D;;;;;GAKG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,aAAa,CAAC,CAgDnE"}