@aigne/afs-index 1.12.0-beta.5

package/dist/backend/sqlite-backend.mjs

@@ -0,0 +1,890 @@
+import { KeyGeneratorRegistry } from "../keys/registry.mjs";
+import { segmentCJK } from "../text/cjk.mjs";
+import { entryPathPrefixRange } from "./prefix-range.mjs";
+import { createSchema } from "./schema.mjs";
+import { SQLiteAFS } from "@aigne/afs-sqlite";
+import { sql } from "drizzle-orm";
+import { AFS } from "@aigne/afs";
+import { joinURL } from "ufo";
+
+//#region src/backend/sqlite-backend.ts
+/**
+* SQLiteIndexBackend — pluggable SQLite storage backend for the Index Provider.
+*
+* Implements the IndexBackend interface using AFSSQLite through AFS.
+* - CRUD operations use built-in AFS actions (insert, query, update_where, delete_where)
+* - Schema creation uses getDatabase() as a local variable (one-time DDL bootstrap)
+* - FTS / count / anchor-intersection use registered custom actions via afs.exec()
+* - Zero stored db handle — all runtime operations go through AFS
+*/
+const MOUNT_NAME = "db";
+var SQLiteIndexBackend = class {
+	afs;
+	sqliteProvider;
+	dbUrl;
+	keyRegistry;
+	ftsTokenizer;
+	scope;
+	embeddingDimension = 0;
+	initialized = false;
+	constructor(dbUrl = ":memory:", keyRegistry, opts = {}) {
+		this.dbUrl = dbUrl;
+		this.keyRegistry = keyRegistry ?? new KeyGeneratorRegistry();
+		this.ftsTokenizer = opts.ftsTokenizer;
+		this.scope = opts.scope ?? "";
+	}
+	/** See `IndexBackend.setKeyRegistry` — wires an injected backend to the provider's shared registry. */
+	setKeyRegistry(registry) {
+		this.keyRegistry = registry;
+	}
+	get mountPath() {
+		return joinURL("/modules", MOUNT_NAME);
+	}
+	tableAction(table, action) {
+		return joinURL(this.mountPath, table, ".actions", action);
+	}
+	/**
+	* Idempotent (design.md §4.4 addendum, owner decision 2026-07-05): a
+	* caller that needs the backend usable BEFORE any `AFSIndex` action runs
+	* (e.g. `initCursor` at follower-registration time — see daemon.ts /
+	* cf-session-view.ts) must call this explicitly; `AFSIndex.ensureInitialized()`
+	* ALSO calls it unconditionally on the first real action. Without the
+	* guard, that second call re-mounted a BRAND NEW `SQLiteAFS`/connection —
+	* for a `:memory:` db this silently discarded everything the first
+	* connection had written (caught by the Node/CF parity test's in-memory
+	* backend); for a file-backed db it "only" leaked an extra connection.
+	*/
+	async initialize() {
+		if (this.initialized) return;
+		this.sqliteProvider = new SQLiteAFS({
+			url: this.dbUrl,
+			name: MOUNT_NAME,
+			accessMode: "readwrite"
+		});
+		this.afs = new AFS();
+		await this.afs.mount(this.sqliteProvider);
+		await createSchema(await this.sqliteProvider.getDatabase(), { ftsTokenizer: this.ftsTokenizer });
+		this.registerCustomActions();
+		this.initialized = true;
+	}
+	registerCustomActions() {
+		this.sqliteProvider.registerAction("anchor_intersection", async (ctx, params) => {
+			const keyGroups = params.key_groups;
+			const tenantScope = params.tenant_scope ?? "";
+			const scope = params.scope;
+			const pathPrefix = params.path_prefix;
+			const minConfidence = params.min_confidence;
+			const limit = params.limit;
+			const metaFilter = params.meta_filter;
+			const domains = params.domains;
+			if (!keyGroups || keyGroups.length === 0) return { rows: [] };
+			const cteNames = [];
+			const cteParts = [];
+			for (let i = 0; i < keyGroups.length; i++) {
+				const cteName = `g${i}`;
+				cteNames.push(cteName);
+				const extraConds = [];
+				for (const prefix of [scope, pathPrefix]) if (prefix) {
+					const [lo, hi] = entryPathPrefixRange(prefix);
+					extraConds.push(sql`entry_path >= ${lo} AND entry_path < ${hi}`);
+				}
+				if (minConfidence != null) extraConds.push(sql`confidence >= ${minConfidence}`);
+				const arms = keyGroups[i].values.map((v) => sql`SELECT entry_path, confidence FROM idx_anchor_key WHERE ${sql.join([
+					sql`scope = ${tenantScope}`,
+					sql`index_key = ${v}`,
+					...extraConds
+				], sql` AND `)}`);
+				cteParts.push(sql`${sql.raw(cteName)} AS (SELECT entry_path, MIN(confidence) as min_conf FROM (${sql.join(arms, sql` UNION ALL `)}) GROUP BY entry_path)`);
+			}
+			const cteSql = sql`WITH ${sql.join(cteParts, sql`, `)}`;
+			let selectSql;
+			const cteJoinParts = [];
+			let scoreExpr;
+			if (cteNames.length === 1) scoreExpr = `${cteNames[0]}.min_conf`;
+			else {
+				for (let i = 1; i < cteNames.length; i++) cteJoinParts.push(`INNER JOIN ${cteNames[i]} ON ${cteNames[0]}.entry_path = ${cteNames[i]}.entry_path`);
+				scoreExpr = `MIN(${cteNames.map((n) => `${n}.min_conf`).join(", ")})`;
+			}
+			const entryJoinPart = [];
+			let entryWhereSql = null;
+			if (domains && domains.length > 0 || metaFilter && Object.keys(metaFilter).length > 0) {
+				entryJoinPart.push(`INNER JOIN ds_indexed_entry ie ON ${cteNames[0]}.entry_path = ie.entry_path AND ie.scope = '${sqlEscape(tenantScope)}'`);
+				const entryConditions = [];
+				if (domains && domains.length > 0) {
+					const domainPlaceholders = domains.map((d) => sql`${d}`);
+					entryConditions.push(sql`ie.domain IN (${sql.join(domainPlaceholders, sql`, `)})`);
+				}
+				for (const [key, expected] of Object.entries(metaFilter ?? {})) if (Array.isArray(expected)) {
+					if (expected.length === 0) return { rows: [] };
+					const placeholders = expected.map((v) => sql`${v}`);
+					entryConditions.push(sql`json_extract(ie.meta, ${`$.${key}`}) IN (${sql.join(placeholders, sql`, `)})`);
+				} else entryConditions.push(sql`json_extract(ie.meta, ${`$.${key}`}) = ${expected}`);
+				entryWhereSql = sql.join(entryConditions, sql` AND `);
+			}
+			const allJoins = [...cteJoinParts, ...entryJoinPart].join(" ");
+			if (entryWhereSql) selectSql = sql`${cteSql} SELECT ${sql.raw(cteNames[0])}.entry_path, ${sql.raw(scoreExpr)} as score FROM ${sql.raw(cteNames[0])} ${sql.raw(allJoins)} WHERE ${entryWhereSql}`;
+			else selectSql = sql`${cteSql} SELECT ${sql.raw(cteNames[0])}.entry_path, ${sql.raw(scoreExpr)} as score FROM ${sql.raw(cteNames[0])} ${sql.raw(allJoins)}`;
+			const orderSql = limit != null ? sql`${selectSql} ORDER BY score DESC, ${sql.raw(cteNames[0])}.entry_path LIMIT ${limit}` : sql`${selectSql} ORDER BY score DESC, ${sql.raw(cteNames[0])}.entry_path`;
+			return { rows: await ctx.db.all(orderSql) };
+		}, {
+			description: "Anchor key intersection with CTE-based AND logic",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("fts_write", async (ctx, params) => {
+			const { scope, path, summary } = params;
+			await writeFtsRow(ctx.db, scope, path, segmentCJK(summary));
+			return { success: true };
+		}, {
+			description: "Write summary to FTS5 index (insert-or-replace by rowid, not full scan)",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("fts_query", async (ctx, params) => {
+			const { text, limit, meta_filter, domain, domains, path_prefix, tenant_scope } = params;
+			const tScope = tenant_scope ?? "";
+			const needsJoin = meta_filter && Object.keys(meta_filter).length > 0 || typeof domain === "string" && domain.length > 0 || Array.isArray(domains) && domains.length > 0 || typeof path_prefix === "string" && path_prefix.length > 0;
+			let query;
+			if (needsJoin) {
+				const conditions = [sql`idx_fts MATCH ${text}`, sql`idx_fts.scope = ${tScope}`];
+				if (domain) conditions.push(sql`ie.domain = ${domain}`);
+				if (domains && domains.length > 0) {
+					const domainPlaceholders = domains.map((d) => sql`${d}`);
+					conditions.push(sql`ie.domain IN (${sql.join(domainPlaceholders, sql`, `)})`);
+				}
+				if (path_prefix) conditions.push(sql`ie.entry_path LIKE ${`${path_prefix}%`}`);
+				for (const [key, expected] of Object.entries(meta_filter ?? {})) if (Array.isArray(expected)) {
+					if (expected.length === 0) return { rows: [] };
+					const placeholders = expected.map((v) => sql`${v}`);
+					conditions.push(sql`json_extract(ie.meta, ${`$.${key}`}) IN (${sql.join(placeholders, sql`, `)})`);
+				} else conditions.push(sql`json_extract(ie.meta, ${`$.${key}`}) = ${expected}`);
+				const where = sql.join(conditions, sql` AND `);
+				query = limit != null ? sql`SELECT idx_fts.entry_path, idx_fts.rank FROM idx_fts INNER JOIN ds_indexed_entry ie ON idx_fts.entry_path = ie.entry_path WHERE ${where} ORDER BY idx_fts.rank LIMIT ${limit}` : sql`SELECT idx_fts.entry_path, idx_fts.rank FROM idx_fts INNER JOIN ds_indexed_entry ie ON idx_fts.entry_path = ie.entry_path WHERE ${where} ORDER BY idx_fts.rank`;
+			} else query = limit != null ? sql`SELECT entry_path, rank FROM idx_fts WHERE idx_fts MATCH ${text} AND scope = ${tScope} ORDER BY rank LIMIT ${limit}` : sql`SELECT entry_path, rank FROM idx_fts WHERE idx_fts MATCH ${text} AND scope = ${tScope} ORDER BY rank`;
+			return { rows: await ctx.db.all(query) };
+		}, {
+			description: "FTS5 search with optional domain/scope/metaFilter isolation",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("fts_delete", async (ctx, params) => {
+			const { scope, path } = params;
+			await deleteFtsRow(ctx.db, scope, path);
+			return { success: true };
+		}, {
+			description: "Remove entry from FTS5 index (delete by rowid, not full scan)",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("fts_get", async (ctx, params) => {
+			const { scope, path } = params;
+			return { summary: (await ctx.db.all(sql`SELECT summary FROM idx_fts WHERE scope = ${scope} AND entry_path = ${path} LIMIT 1`))[0]?.summary ?? null };
+		}, {
+			description: "Read the stored FTS summary for a single entry",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("count_entries", async (ctx, params) => {
+			const filter = params;
+			const conditions = [sql`scope = ${filter.tenant_scope ?? ""}`];
+			if (filter.domain) conditions.push(sql`domain = ${filter.domain}`);
+			if (filter.state) conditions.push(sql`state = ${filter.state}`);
+			if (filter.extractorId) conditions.push(sql`extractor_id = ${filter.extractorId}`);
+			if (filter.scope) conditions.push(sql`entry_path LIKE ${`${filter.scope}%`}`);
+			if (filter.boundDomains && filter.boundDomains.length > 0) {
+				const ps = filter.boundDomains.map((d) => sql`${d}`);
+				conditions.push(sql`domain IN (${sql.join(ps, sql`, `)})`);
+			}
+			const query = sql`SELECT COUNT(*) as count FROM ds_indexed_entry WHERE ${sql.join(conditions, sql` AND `)}`;
+			return { count: (await ctx.db.all(query))[0]?.count ?? 0 };
+		}, {
+			description: "Count indexed entries with optional filters",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("embedding_write", async (ctx, params) => {
+			const { scope, path, embedding } = params;
+			const blob = embeddingToBlob(embedding);
+			await ctx.db.run(sql`INSERT INTO idx_embedding_vector (scope, entry_path, embedding, embedding_blob, dimension) VALUES (${scope}, ${path}, '', ${blob}, ${embedding.length})
+              ON CONFLICT(scope, entry_path) DO UPDATE SET
+                embedding = excluded.embedding,
+                embedding_blob = excluded.embedding_blob,
+                dimension = excluded.dimension`);
+			return { success: true };
+		}, {
+			description: "Write embedding vector",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("embedding_query", async (ctx, params) => {
+			const filter = params ?? {};
+			const conditions = [sql`idx_embedding_vector.scope = ${filter.tenant_scope ?? ""}`];
+			if (filter.domain) conditions.push(sql`ds_indexed_entry.domain = ${filter.domain}`);
+			if (filter.domains && filter.domains.length > 0) {
+				const domainPlaceholders = filter.domains.map((d) => sql`${d}`);
+				conditions.push(sql`ds_indexed_entry.domain IN (${sql.join(domainPlaceholders, sql`, `)})`);
+			}
+			if (filter.path_prefix) conditions.push(sql`ds_indexed_entry.entry_path LIKE ${`${filter.path_prefix}%`}`);
+			const where = sql`WHERE ${sql.join(conditions, sql` AND `)}`;
+			return { rows: await ctx.db.all(sql`SELECT idx_embedding_vector.entry_path     AS entry_path,
+                     idx_embedding_vector.embedding      AS embedding,
+                     idx_embedding_vector.embedding_blob AS embedding_blob
+              FROM idx_embedding_vector
+              JOIN ds_indexed_entry
+                ON ds_indexed_entry.scope = idx_embedding_vector.scope
+               AND ds_indexed_entry.entry_path = idx_embedding_vector.entry_path
+              ${where}`) };
+		}, {
+			description: "Fetch embeddings (filtered by domain/scope) for vector search",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("embedding_delete", async (ctx, params) => {
+			const { scope, path } = params;
+			await ctx.db.run(sql`DELETE FROM idx_embedding_vector WHERE scope = ${scope} AND entry_path = ${path}`);
+			return { success: true };
+		}, {
+			description: "Remove embedding vector",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("upsert_entry", async (ctx, params) => {
+			const e = params;
+			await ctx.db.run(sql`INSERT OR REPLACE INTO ds_indexed_entry (scope, entry_path, domain, state, indexed_at, updated_at, anchor_count, source_path, source_hash, extractor_id, meta) VALUES (${e.scope}, ${e.entry_path}, ${e.domain}, ${e.state}, ${e.indexed_at}, ${e.updated_at}, ${e.anchor_count}, ${e.source_path ?? null}, ${e.source_hash ?? null}, ${e.extractor_id ?? null}, ${e.meta ?? null})`);
+			return { success: true };
+		}, {
+			description: "Single entry upsert via INSERT OR REPLACE",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("replace_anchors", async (ctx, params) => {
+			const { scope, path, dataRows, keyRows } = params;
+			await ctx.db.run(sql`DELETE FROM idx_anchor_data WHERE scope = ${scope} AND entry_path = ${path}`);
+			await ctx.db.run(sql`DELETE FROM idx_anchor_key WHERE scope = ${scope} AND entry_path = ${path}`);
+			for (const row of dataRows) await ctx.db.run(sql`INSERT INTO idx_anchor_data (scope, entry_path, anchor_type, confidence, raw_anchor) VALUES (${scope}, ${row.entry_path}, ${row.anchor_type}, ${row.confidence}, ${row.raw_anchor})`);
+			for (const row of keyRows) await ctx.db.run(sql`INSERT OR REPLACE INTO idx_anchor_key (scope, index_key, entry_path, anchor_type, confidence) VALUES (${scope}, ${row.index_key}, ${row.entry_path}, ${row.anchor_type}, ${row.confidence})`);
+			return { success: true };
+		}, {
+			description: "Replace all anchors for a single entry",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("write_indexed_document", async (ctx, params) => {
+			const { entry, path, dataRows, keyRows, summary } = params;
+			await ctx.db.run(sql.raw("BEGIN TRANSACTION"));
+			try {
+				await ctx.db.run(sql`INSERT OR REPLACE INTO ds_indexed_entry (scope, entry_path, domain, state, indexed_at, updated_at, anchor_count, source_path, source_hash, extractor_id, meta) VALUES (${entry.scope}, ${entry.entry_path}, ${entry.domain}, ${entry.state}, ${entry.indexed_at}, ${entry.updated_at}, ${entry.anchor_count}, ${entry.source_path ?? null}, ${entry.source_hash ?? null}, ${entry.extractor_id ?? null}, ${entry.meta ?? null})`);
+				await ctx.db.run(sql`DELETE FROM idx_anchor_data WHERE scope = ${entry.scope} AND entry_path = ${path}`);
+				await ctx.db.run(sql`DELETE FROM idx_anchor_key WHERE scope = ${entry.scope} AND entry_path = ${path}`);
+				for (const row of dataRows) await ctx.db.run(sql`INSERT INTO idx_anchor_data (scope, entry_path, anchor_type, confidence, raw_anchor) VALUES (${entry.scope}, ${row.entry_path}, ${row.anchor_type}, ${row.confidence}, ${row.raw_anchor})`);
+				for (const row of keyRows) await ctx.db.run(sql`INSERT OR REPLACE INTO idx_anchor_key (scope, index_key, entry_path, anchor_type, confidence) VALUES (${entry.scope}, ${row.index_key}, ${row.entry_path}, ${row.anchor_type}, ${row.confidence})`);
+				if (summary) await writeFtsRow(ctx.db, entry.scope, path, segmentCJK(summary));
+				await ctx.db.run(sql.raw("COMMIT"));
+				return { success: true };
+			} catch (error) {
+				await ctx.db.run(sql.raw("ROLLBACK"));
+				throw error;
+			}
+		}, {
+			description: "Write entry metadata, anchors, and FTS summary in one transaction",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("batch_purge", async (ctx, params) => {
+			const { scope, paths, skipVector } = params;
+			await ctx.db.run(sql.raw("BEGIN TRANSACTION"));
+			try {
+				for (const path of paths) {
+					await ctx.db.run(sql`DELETE FROM idx_anchor_data WHERE scope = ${scope} AND entry_path = ${path}`);
+					await ctx.db.run(sql`DELETE FROM idx_anchor_key WHERE scope = ${scope} AND entry_path = ${path}`);
+					await deleteFtsRow(ctx.db, scope, path);
+					if (skipVector !== true) await ctx.db.run(sql`DELETE FROM idx_embedding_vector WHERE scope = ${scope} AND entry_path = ${path}`);
+					await ctx.db.run(sql`DELETE FROM ds_indexed_entry WHERE scope = ${scope} AND entry_path = ${path}`);
+				}
+				await ctx.db.run(sql.raw("COMMIT"));
+				return { count: paths.length };
+			} catch (error) {
+				await ctx.db.run(sql.raw("ROLLBACK"));
+				throw error;
+			}
+		}, {
+			description: "Purge entries and all associated data in a single transaction",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("batch_upsert_entries", async (ctx, params) => {
+			const entries = params.entries;
+			await ctx.db.run(sql.raw("BEGIN TRANSACTION"));
+			try {
+				for (const e of entries) await ctx.db.run(sql`INSERT OR REPLACE INTO ds_indexed_entry (scope, entry_path, domain, state, indexed_at, updated_at, anchor_count, source_path, source_hash, extractor_id, meta) VALUES (${e.scope}, ${e.entry_path}, ${e.domain}, ${e.state}, ${e.indexed_at}, ${e.updated_at}, ${e.anchor_count}, ${e.source_path ?? null}, ${e.source_hash ?? null}, ${e.extractor_id ?? null}, ${e.meta ?? null})`);
+				await ctx.db.run(sql.raw("COMMIT"));
+				return { count: entries.length };
+			} catch (error) {
+				await ctx.db.run(sql.raw("ROLLBACK"));
+				throw error;
+			}
+		}, {
+			description: "Batch upsert entries in a single transaction",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("batch_replace_anchors", async (ctx, params) => {
+			const { scope, items } = params;
+			await ctx.db.run(sql.raw("BEGIN TRANSACTION"));
+			try {
+				for (const item of items) {
+					await ctx.db.run(sql`DELETE FROM idx_anchor_data WHERE scope = ${scope} AND entry_path = ${item.path}`);
+					await ctx.db.run(sql`DELETE FROM idx_anchor_key WHERE scope = ${scope} AND entry_path = ${item.path}`);
+					for (const row of item.dataRows) await ctx.db.run(sql`INSERT INTO idx_anchor_data (scope, entry_path, anchor_type, confidence, raw_anchor) VALUES (${scope}, ${row.entry_path}, ${row.anchor_type}, ${row.confidence}, ${row.raw_anchor})`);
+					for (const row of item.keyRows) await ctx.db.run(sql`INSERT OR REPLACE INTO idx_anchor_key (scope, index_key, entry_path, anchor_type, confidence) VALUES (${scope}, ${row.index_key}, ${row.entry_path}, ${row.anchor_type}, ${row.confidence})`);
+				}
+				await ctx.db.run(sql.raw("COMMIT"));
+				return { count: items.length };
+			} catch (error) {
+				await ctx.db.run(sql.raw("ROLLBACK"));
+				throw error;
+			}
+		}, {
+			description: "Batch replace anchors in a single transaction",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("batch_write_fts", async (ctx, params) => {
+			const { scope, items } = params;
+			await ctx.db.run(sql.raw("BEGIN TRANSACTION"));
+			try {
+				for (const item of items) await writeFtsRow(ctx.db, scope, item.path, item.summary);
+				await ctx.db.run(sql.raw("COMMIT"));
+				return { count: items.length };
+			} catch (error) {
+				await ctx.db.run(sql.raw("ROLLBACK"));
+				throw error;
+			}
+		}, {
+			description: "Batch write FTS summaries in a single transaction",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("cursor_read", async (ctx, params) => {
+			const { consumer_id } = params;
+			const rows = await ctx.db.all(sql`SELECT consumer_id, last_seq, watermarks, updated_at FROM idx_index_cursor WHERE consumer_id = ${consumer_id} LIMIT 1`);
+			if (rows.length === 0) return { cursor: null };
+			const row = rows[0];
+			return { cursor: {
+				consumerId: row.consumer_id,
+				lastSeq: row.last_seq,
+				watermarks: row.watermarks ? JSON.parse(row.watermarks) : void 0,
+				updatedAt: row.updated_at
+			} };
+		}, {
+			description: "Read changelog follower cursor",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("cursor_write", async (ctx, params) => {
+			const { consumer_id, last_seq, watermarks } = params;
+			const now = Date.now();
+			await ctx.db.run(sql`INSERT INTO idx_index_cursor (consumer_id, last_seq, watermarks, updated_at, served_at)
+	      VALUES (${consumer_id}, ${last_seq}, ${watermarks ? JSON.stringify(watermarks) : null}, ${now}, ${now})
+              ON CONFLICT(consumer_id) DO UPDATE SET
+                last_seq = MAX(last_seq, excluded.last_seq),
+                watermarks = excluded.watermarks,
+		updated_at = excluded.updated_at,
+		served_at = excluded.served_at`);
+			return { success: true };
+		}, {
+			description: "Write index follower cursor (monotonic last_seq; dead column post-cutover)",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("cursor_mark_served", async (ctx, params) => {
+			const { consumer_id } = params;
+			await ctx.db.run(sql`UPDATE idx_index_cursor SET served_at = ${Date.now()} WHERE consumer_id = ${consumer_id}`);
+			return { success: true };
+		}, {
+			description: "Mark changelog follower cursor as served",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("cursor_init", async (ctx, params) => {
+			const { consumer_id, instance_did, domains } = params;
+			const now = Date.now();
+			await ctx.db.run(sql`INSERT OR IGNORE INTO idx_index_cursor (consumer_id, last_seq, watermarks, updated_at, served_at, instance_did, domains)
+	      VALUES (${consumer_id}, 0, NULL, ${now}, ${now}, ${instance_did ?? null}, ${domains ?? null})`);
+			return { success: true };
+		}, {
+			description: "Initialize changelog follower cursor (idempotent)",
+			tableLevel: true
+		});
+		this.sqliteProvider.registerAction("cursor_scope_list", async (ctx, params) => {
+			const { family_consumer_id } = params;
+			return { registrations: (await ctx.db.all(sql`SELECT consumer_id, instance_did, domains, updated_at, served_at
+	      FROM idx_index_cursor
+	      WHERE consumer_id LIKE ${`${family_consumer_id}:%`}`)).map((r) => ({
+				scope: cursorScopeFromConsumerId(r.consumer_id, family_consumer_id, r.instance_did),
+				consumerId: r.consumer_id,
+				instanceDid: r.instance_did,
+				domainsJson: r.domains,
+				updatedAt: r.updated_at,
+				servedAt: r.served_at ?? r.updated_at
+			})) };
+		}, {
+			description: "List changelog follower cursor registrations",
+			tableLevel: true
+		});
+	}
+	async readCursor(consumerId) {
+		return (await this.afs.exec(this.tableAction("idx_index_cursor", "cursor_read"), { consumer_id: consumerId })).data.cursor;
+	}
+	async writeCursor(consumerId, lastSeq, watermarks) {
+		await this.afs.exec(this.tableAction("idx_index_cursor", "cursor_write"), {
+			consumer_id: consumerId,
+			last_seq: lastSeq,
+			watermarks: watermarks ?? null
+		});
+	}
+	async markCursorServed(consumerId) {
+		await this.afs.exec(this.tableAction("idx_index_cursor", "cursor_mark_served"), { consumer_id: consumerId });
+	}
+	async initCursor(consumerId, registration) {
+		await this.afs.exec(this.tableAction("idx_index_cursor", "cursor_init"), {
+			consumer_id: consumerId,
+			instance_did: registration?.instanceDid ?? null,
+			domains: registration?.domainsJson ?? null
+		});
+	}
+	async listCursorScopes(consumerId) {
+		return (await this.afs.exec(this.tableAction("idx_index_cursor", "cursor_scope_list"), { family_consumer_id: consumerId })).data.registrations;
+	}
+	async close() {
+		this.afs = void 0;
+		this.sqliteProvider = void 0;
+	}
+	async writeEntry(entry) {
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "upsert_entry"), this.entryToRow(entry));
+	}
+	async writeIndexedDocument(document) {
+		const path = document.entry.entryPath;
+		const anchors = document.anchors ?? [];
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "write_indexed_document"), {
+			entry: this.entryToRow(document.entry),
+			path,
+			dataRows: anchors.map((anchor) => ({
+				entry_path: path,
+				anchor_type: anchor.type,
+				confidence: anchor.confidence,
+				raw_anchor: JSON.stringify(anchor)
+			})),
+			keyRows: anchors.flatMap((anchor) => this.keyRegistry.generateKeys(anchor).map((key) => ({
+				index_key: key,
+				entry_path: path,
+				anchor_type: anchor.type,
+				confidence: anchor.confidence
+			}))),
+			summary: document.summary ?? null
+		});
+	}
+	entryToRow(entry) {
+		const data = {
+			scope: this.scope,
+			entry_path: entry.entryPath,
+			domain: entry.domain,
+			state: entry.state,
+			indexed_at: entry.indexedAt,
+			updated_at: entry.updatedAt,
+			anchor_count: entry.anchorCount
+		};
+		if (entry.sourcePath != null) data.source_path = entry.sourcePath;
+		if (entry.sourceHash != null) data.source_hash = entry.sourceHash;
+		if (entry.extractorId != null) data.extractor_id = entry.extractorId;
+		if (entry.meta != null) data.meta = JSON.stringify(entry.meta);
+		return data;
+	}
+	async getEntry(path) {
+		const data = (await this.afs.exec(this.tableAction("ds_indexed_entry", "query"), {
+			where: {
+				scope: this.scope,
+				entry_path: path
+			},
+			limit: 1
+		})).data;
+		if (!data.rows || data.rows.length === 0) return null;
+		return rowToEntry(data.rows[0]);
+	}
+	async removeEntry(path) {
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "delete_where"), { where: {
+			scope: this.scope,
+			entry_path: path
+		} });
+	}
+	async removeIndexedDocument(path, opts) {
+		await this.purgeEntries([path], opts);
+	}
+	async listEntries(filter) {
+		const where = { scope: this.scope };
+		if (filter.domain) where.domain = filter.domain;
+		if (filter.state) where.state = filter.state;
+		if (filter.extractorId) where.extractor_id = filter.extractorId;
+		if (filter.scope) where.entry_path = { $like: `${filter.scope}%` };
+		if (filter.boundDomains && filter.boundDomains.length > 0) where.domain = { $in: filter.boundDomains };
+		return ((await this.afs.exec(this.tableAction("ds_indexed_entry", "query"), { where })).data.rows ?? []).map(rowToEntry);
+	}
+	async markStale(filter) {
+		const entryWhere = {
+			scope: this.scope,
+			state: "active"
+		};
+		if (filter.extractorId) entryWhere.extractor_id = filter.extractorId;
+		if (filter.domain) entryWhere.domain = filter.domain;
+		if (filter.scope) entryWhere.entry_path = { $like: `${filter.scope}%` };
+		if (filter.boundDomains && filter.boundDomains.length > 0) entryWhere.domain = { $in: filter.boundDomains };
+		if (filter.anchorType) {
+			const anchorData = (await this.afs.exec(this.tableAction("idx_anchor_data", "query"), { where: {
+				scope: this.scope,
+				anchor_type: filter.anchorType
+			} })).data;
+			const paths = [...new Set(anchorData.rows.map((r) => r.entry_path))];
+			if (paths.length === 0) return 0;
+			if (typeof entryWhere.entry_path === "object") entryWhere.entry_path = {
+				...entryWhere.entry_path,
+				$in: paths
+			};
+			else entryWhere.entry_path = { $in: paths };
+		}
+		return (await this.afs.exec(this.tableAction("ds_indexed_entry", "update_where"), {
+			where: entryWhere,
+			data: { state: "stale" }
+		})).data.affectedRows;
+	}
+	async countEntries(filter) {
+		return (await this.afs.exec(this.tableAction("ds_indexed_entry", "count_entries"), {
+			tenant_scope: this.scope,
+			domain: filter.domain,
+			state: filter.state,
+			extractorId: filter.extractorId,
+			scope: filter.scope,
+			boundDomains: filter.boundDomains
+		})).data.count;
+	}
+	async writeAnchors(path, anchors) {
+		const dataRows = anchors.map((anchor) => ({
+			entry_path: path,
+			anchor_type: anchor.type,
+			confidence: anchor.confidence,
+			raw_anchor: JSON.stringify(anchor)
+		}));
+		const keyRows = anchors.flatMap((anchor) => this.keyRegistry.generateKeys(anchor).map((key) => ({
+			index_key: key,
+			entry_path: path,
+			anchor_type: anchor.type,
+			confidence: anchor.confidence
+		})));
+		await this.afs.exec(this.tableAction("idx_anchor_data", "replace_anchors"), {
+			scope: this.scope,
+			path,
+			dataRows,
+			keyRows
+		});
+	}
+	async queryAnchors(query) {
+		if (query.keys.length === 0) return [];
+		const params = {
+			key_groups: query.keys.map((kg) => {
+				const values = /* @__PURE__ */ new Set();
+				for (const raw of kg.values) {
+					const synthetic = {
+						type: kg.type ?? "exact",
+						values: [raw],
+						confidence: 1
+					};
+					const generated = this.keyRegistry.generateKeys(synthetic);
+					for (const k of generated) values.add(k);
+					values.add(raw);
+				}
+				return { values: [...values] };
+			}),
+			tenant_scope: this.scope,
+			scope: query.scope,
+			min_confidence: query.minConfidence,
+			limit: query.limit
+		};
+		if (query.pathPrefix) params.path_prefix = query.pathPrefix;
+		if (query.metaFilter && Object.keys(query.metaFilter).length > 0) params.meta_filter = query.metaFilter;
+		if (query.domains && query.domains.length > 0) params.domains = query.domains;
+		return ((await this.afs.exec(this.tableAction("idx_anchor_key", "anchor_intersection"), params)).data.rows ?? []).map((r) => ({
+			entryPath: r.entry_path,
+			score: r.score
+		}));
+	}
+	async removeAnchors(path) {
+		await this.afs.exec(this.tableAction("idx_anchor_data", "delete_where"), { where: {
+			scope: this.scope,
+			entry_path: path
+		} });
+		await this.afs.exec(this.tableAction("idx_anchor_key", "delete_where"), { where: {
+			scope: this.scope,
+			entry_path: path
+		} });
+	}
+	async getAnchorData(path) {
+		return ((await this.afs.exec(this.tableAction("idx_anchor_data", "query"), { where: {
+			scope: this.scope,
+			entry_path: path
+		} })).data.rows ?? []).map((r) => ({
+			entryPath: r.entry_path,
+			anchorType: r.anchor_type,
+			confidence: r.confidence,
+			rawAnchor: r.raw_anchor
+		}));
+	}
+	async writeSummary(path, summary) {
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "fts_write"), {
+			scope: this.scope,
+			path,
+			summary
+		});
+	}
+	async getSummary(path) {
+		return (await this.afs.exec(this.tableAction("ds_indexed_entry", "fts_get"), {
+			scope: this.scope,
+			path
+		})).data.summary ?? null;
+	}
+	async queryFTS(text, limit, metaFilter, opts) {
+		try {
+			const sanitized = sanitizeFTS5(text);
+			if (!sanitized) return [];
+			const params = {
+				text: sanitized,
+				limit,
+				tenant_scope: this.scope
+			};
+			if (metaFilter && Object.keys(metaFilter).length > 0) params.meta_filter = metaFilter;
+			if (opts?.domain) params.domain = opts.domain;
+			if (opts?.domains && opts.domains.length > 0) params.domains = opts.domains;
+			if (opts?.scope) params.scope = opts.scope;
+			if (opts?.pathPrefix) params.path_prefix = opts.pathPrefix;
+			return ((await this.afs.exec(this.tableAction("ds_indexed_entry", "fts_query"), params)).data.rows ?? []).map((r) => ({
+				entryPath: r.entry_path,
+				rank: -r.rank
+			}));
+		} catch {
+			return [];
+		}
+	}
+	async removeSummary(path) {
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "fts_delete"), {
+			scope: this.scope,
+			path
+		});
+	}
+	async writeEmbedding(path, embedding) {
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "embedding_write"), {
+			scope: this.scope,
+			path,
+			embedding
+		});
+		if (this.embeddingDimension === 0 && embedding.length > 0) this.embeddingDimension = embedding.length;
+	}
+	async queryVector(embedding, limit, opts) {
+		const rows = (await this.afs.exec(this.tableAction("ds_indexed_entry", "embedding_query"), {
+			tenant_scope: this.scope,
+			...opts?.domain ? { domain: opts.domain } : {},
+			...opts?.domains && opts.domains.length > 0 ? { domains: opts.domains } : {},
+			...opts?.scope ? { scope: opts.scope } : {},
+			...opts?.pathPrefix ? { path_prefix: opts.pathPrefix } : {}
+		})).data.rows ?? [];
+		const queryVec = Float32Array.from(embedding);
+		const results = rows.map((r) => ({
+			entryPath: r.entry_path,
+			similarity: cosineSimilarityF32(queryVec, decodeStoredEmbedding(r))
+		}));
+		results.sort((a, b) => b.similarity - a.similarity);
+		if (limit != null) return results.slice(0, limit);
+		return results;
+	}
+	async removeEmbedding(path) {
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "embedding_delete"), {
+			scope: this.scope,
+			path
+		});
+	}
+	embeddingCapability() {
+		return {
+			supported: true,
+			dimension: this.embeddingDimension
+		};
+	}
+	async writeEntriesBatch(entries) {
+		if (entries.length === 0) return;
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "batch_upsert_entries"), { entries: entries.map((e) => this.entryToRow(e)) });
+	}
+	async writeAnchorsBatch(items) {
+		if (items.length === 0) return;
+		const batchItems = items.map((item) => ({
+			path: item.path,
+			dataRows: item.anchors.map((anchor) => ({
+				entry_path: item.path,
+				anchor_type: anchor.type,
+				confidence: anchor.confidence,
+				raw_anchor: JSON.stringify(anchor)
+			})),
+			keyRows: item.anchors.flatMap((anchor) => this.keyRegistry.generateKeys(anchor).map((key) => ({
+				index_key: key,
+				entry_path: item.path,
+				anchor_type: anchor.type,
+				confidence: anchor.confidence
+			})))
+		}));
+		await this.afs.exec(this.tableAction("idx_anchor_data", "batch_replace_anchors"), {
+			scope: this.scope,
+			items: batchItems
+		});
+	}
+	async writeSummariesBatch(items) {
+		if (items.length === 0) return;
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "batch_write_fts"), {
+			scope: this.scope,
+			items
+		});
+	}
+	async purgeEntries(paths, opts) {
+		if (paths.length === 0) return 0;
+		await this.afs.exec(this.tableAction("ds_indexed_entry", "batch_purge"), {
+			scope: this.scope,
+			paths,
+			skipVector: opts?.skipVector === true
+		});
+		return paths.length;
+	}
+	async queryCombined(keys, text, opts) {
+		const anchorResults = keys.length > 0 ? await this.queryAnchors({
+			keys,
+			scope: opts?.scope,
+			minConfidence: opts?.minConfidence,
+			limit: opts?.limit
+		}) : [];
+		const anchorPaths = new Set(anchorResults.map((r) => r.entryPath));
+		const ftsResults = text ? await this.queryFTS(text, opts?.limit) : [];
+		const results = anchorResults.map((r) => {
+			const fts = ftsResults.find((f) => f.entryPath === r.entryPath);
+			return {
+				entryPath: r.entryPath,
+				anchorScore: r.score,
+				ftsRank: fts?.rank,
+				score: r.score + (fts?.rank ?? 0)
+			};
+		});
+		for (const f of ftsResults) if (!anchorPaths.has(f.entryPath)) results.push({
+			entryPath: f.entryPath,
+			ftsRank: f.rank,
+			score: f.rank
+		});
+		results.sort((a, b) => b.score - a.score);
+		if (opts?.limit != null) return results.slice(0, opts.limit);
+		return results;
+	}
+};
+/** Get-or-create the stable idx_fts rowid for (scope, path) via the mapping table. */
+async function ensureFtsRowid(db, scope, path) {
+	await db.run(sql`INSERT INTO idx_fts_rowid (scope, entry_path) VALUES (${scope}, ${path})
+        ON CONFLICT(scope, entry_path) DO NOTHING`);
+	return (await db.all(sql`SELECT fts_rowid FROM idx_fts_rowid WHERE scope = ${scope} AND entry_path = ${path} LIMIT 1`))[0].fts_rowid;
+}
+/** Atomically insert-or-replace an entry's FTS row at its stable mapped rowid. */
+async function writeFtsRow(db, scope, path, summary) {
+	const rowid = await ensureFtsRowid(db, scope, path);
+	await db.run(sql`INSERT OR REPLACE INTO idx_fts (rowid, scope, entry_path, summary) VALUES (${rowid}, ${scope}, ${path}, ${summary})`);
+}
+/** Delete an entry's idx_fts row (by mapped rowid, O(1)) and its mapping row. */
+async function deleteFtsRow(db, scope, path) {
+	await db.run(sql`DELETE FROM idx_fts WHERE rowid = (SELECT fts_rowid FROM idx_fts_rowid WHERE scope = ${scope} AND entry_path = ${path})`);
+	await db.run(sql`DELETE FROM idx_fts_rowid WHERE scope = ${scope} AND entry_path = ${path}`);
+}
+function sqlEscape(value) {
+	return value.replace(/'/g, "''");
+}
+function rowToEntry(row) {
+	return {
+		entryPath: row.entry_path,
+		sourcePath: row.source_path ?? void 0,
+		sourceHash: row.source_hash ?? void 0,
+		domain: row.domain,
+		state: row.state,
+		extractorId: row.extractor_id ?? void 0,
+		indexedAt: row.indexed_at,
+		updatedAt: row.updated_at,
+		anchorCount: row.anchor_count,
+		meta: row.meta ? JSON.parse(row.meta) : void 0
+	};
+}
+function cursorScopeFromConsumerId(consumerId, familyConsumerId, instanceDid) {
+	const prefix = `${familyConsumerId}:`;
+	if (!consumerId.startsWith(prefix)) return "";
+	const tail = consumerId.slice(prefix.length);
+	if (instanceDid) {
+		const suffix = `:${instanceDid}`;
+		if (tail.endsWith(suffix)) return tail.slice(0, -suffix.length);
+	}
+	const firstSeparator = tail.indexOf(":");
+	return firstSeparator === -1 ? tail : tail.slice(0, firstSeparator);
+}
+/**
+* Sanitize text for FTS5 MATCH queries.
+* Removes special FTS5 characters to prevent query syntax errors.
+*
+* NOTE: does NOT strip AND/OR/NOT. The query text reaching this backend is
+* always pre-built by `transformFtsQuery` (the single owner of FTS query
+* construction, #933), which strips *bare* boolean keywords from the raw
+* input and then re-emits `OR` only as an intentional infix operator for
+* memory's or-recall mode (#1002). Stripping it again here silently collapsed
+* or-mode back to AND — the #1002 follow-up bug that dropped memory recall for
+* plural/partial-word queries (e.g. "architecture OR use" → "architecture use",
+* which no longer matched "…uses architecture…").
+*/
+function sanitizeFTS5(text) {
+	return text.replace(/["*^()\-+{}:]/g, " ").replace(/\s+/g, " ").trim();
+}
+/**
+* Float32-typed cosine similarity. Used by `queryVector` once we've
+* decoded the stored blob into a Float32Array view — typed-array indexed
+* access is ~2× the speed of `number[]` access in V8 because the JIT
+* doesn't need to deopt-check for hole/undefined slots.
+*/
+function cosineSimilarityF32(a, b) {
+	const len = Math.min(a.length, b.length);
+	let dot = 0;
+	let magA = 0;
+	let magB = 0;
+	for (let i = 0; i < len; i++) {
+		const ai = a[i];
+		const bi = b[i];
+		dot += ai * bi;
+		magA += ai * ai;
+		magB += bi * bi;
+	}
+	const denom = Math.sqrt(magA) * Math.sqrt(magB);
+	return denom === 0 ? 0 : dot / denom;
+}
+/**
+* Encode an embedding (number[]) to little-endian Float32 bytes for
+* BLOB storage. Returns a Node `Buffer` — that's the only typed-array
+* shape that drizzle's libsql adapter binds through correctly when
+* the underlying client is file-backed. Both `Uint8Array` and raw
+* `ArrayBuffer` get serialized via `toString()` somewhere in the
+* binding pipeline (yielding "0,32,71,..." or "[object ArrayBuffer]"
+* respectively), which corrupts the BLOB. The in-memory libsql client
+* doesn't exhibit this, which is why unit tests passed — file-backed
+* is the production path. `Buffer` is a `Uint8Array` subclass with the
+* correct `toString()` and is honored as a BLOB by both clients.
+*
+* `Buffer` is Node-only. CF Workers / browser builds of this provider
+* would need a different code path; we don't ship the index there
+* today.
+*/
+function embeddingToBlob(embedding) {
+	const f32 = Float32Array.from(embedding);
+	return Buffer.from(f32.buffer, f32.byteOffset, f32.byteLength);
+}
+/**
+* Decode a stored embedding row into Float32Array. Prefers the BLOB
+* column; falls back to JSON-parsing the legacy TEXT column for rows
+* indexed before the schema migration. Different SQLite drivers hand
+* back different containers — libsql returns a raw `ArrayBuffer`,
+* better-sqlite3 returns a `Buffer`, others a `Uint8Array`. Normalize.
+*/
+function decodeStoredEmbedding(row) {
+	const blob = row.embedding_blob;
+	if (blob != null) {
+		if (blob instanceof ArrayBuffer) return new Float32Array(blob.slice(0));
+		const view = new Float32Array(blob.buffer, blob.byteOffset, blob.byteLength / Float32Array.BYTES_PER_ELEMENT);
+		return new Float32Array(view);
+	}
+	if (row.embedding != null && row.embedding !== "") return Float32Array.from(JSON.parse(row.embedding));
+	return new Float32Array(0);
+}
+
+//#endregion
+export { SQLiteIndexBackend };
+//# sourceMappingURL=sqlite-backend.mjs.map