@aigne/afs-index 1.12.0-beta.5

package/dist/backend/d1-index-backend.cjs

@@ -0,0 +1,656 @@
+const require_registry = require('../keys/registry.cjs');
+const require_cjk = require('../text/cjk.cjs');
+const require_d1_vector_backend = require('./d1-vector-backend.cjs');
+const require_prefix_range = require('./prefix-range.cjs');
+let _aigne_afs_sqlite = require("@aigne/afs-sqlite");
+let drizzle_orm = require("drizzle-orm");
+
+//#region src/backend/d1-index-backend.ts
+/**
+* D1IndexBackend — IndexBackend implementation for Cloudflare D1.
+*
+* Runs in the DID Space D1 (the same edge SQLite as the tree index), so it is
+* reachable from every path that builds a session view — afs-rpc, MCP, and the
+* WebSocket/DO — because all three funnel through `buildCfSessionView`.
+*
+* Isolation is by SCOPE (a `scope` column on every table, mirroring how the DID
+* Space tree index partitions its D1 rows). One backend instance is bound to one
+* scope: per-user index → `deriveScope(callerDid)`, per-instance index →
+* `deriveScope(installerDid)`. Different scopes never see each other's rows.
+*
+* Notes vs the (removed) DO-SQLite backend:
+*   - db is built via `initDatabase({ d1 })` (drizzle-orm/d1), not ctx.storage.sql.
+*   - D1 returns BLOB columns as `number[]`; `decodeStoredEmbedding` handles that
+*     alongside ArrayBuffer/Uint8Array.
+*   - No explicit `BEGIN TRANSACTION`: D1 auto-commits each statement and the
+*     index is a derived, rebuildable read model (a partial batch self-heals on
+*     the next reconcile).
+*/
+const DEFAULT_FTS_TOKENIZER = "unicode61 remove_diacritics 2";
+/** D1 handles whose scope-partitioned schema has been ensured this isolate. */
+const schemaEnsured = /* @__PURE__ */ new WeakSet();
+const cursorServedAtSupported = /* @__PURE__ */ new WeakMap();
+var D1IndexBackend = class {
+	db;
+	d1;
+	scope;
+	keyRegistry;
+	ftsTokenizer;
+	_injectedVectorBackend;
+	_vectorBackend;
+	constructor(d1, scope, keyRegistry, opts = {}) {
+		this.d1 = d1;
+		this.scope = scope;
+		this.keyRegistry = keyRegistry ?? new require_registry.KeyGeneratorRegistry();
+		this.ftsTokenizer = opts.ftsTokenizer ?? DEFAULT_FTS_TOKENIZER;
+		this._injectedVectorBackend = opts.vectorBackend;
+	}
+	/** See `IndexBackend.setKeyRegistry` — wires an injected backend to the provider's shared registry. */
+	setKeyRegistry(registry) {
+		this.keyRegistry = registry;
+	}
+	async initialize() {
+		this.db = await (0, _aigne_afs_sqlite.initDatabase)({ d1: this.d1 });
+		if (!this.d1 || typeof this.d1 !== "object" || !schemaEnsured.has(this.d1)) {
+			await this.ensureSchema();
+			if (this.d1 && typeof this.d1 === "object") schemaEnsured.add(this.d1);
+		}
+		this._vectorBackend = this._injectedVectorBackend ?? new require_d1_vector_backend.D1VectorBackend(this.db, this.scope);
+	}
+	async close() {
+		this.db = void 0;
+	}
+	d1BatchBinding() {
+		if (!this.d1 || typeof this.d1 !== "object") return null;
+		const candidate = this.d1;
+		return typeof candidate.prepare === "function" && typeof candidate.batch === "function" ? candidate : null;
+	}
+	/**
+	* Rename the anchor tables `arc_anchor_*` → `idx_anchor_*` in place, preserving
+	* rows. Probe-guarded (renames only when the legacy table exists and the target
+	* does not) so it is idempotent and safe on fresh / already-migrated / racing
+	* isolates. Concurrent isolates may both attempt the ALTER on the same D1 —
+	* the loser's `no such table` / `already exists` is swallowed.
+	*
+	* ensureSchema runs on the cold-start (first-request-per-isolate) path, so the
+	* existence check is a SINGLE `sqlite_master` read for all four names rather
+	* than one per pair — one O(1) probe, no per-request cost (steady state is
+	* gated out by the `schemaEnsured` WeakSet).
+	*/
+	async renameAnchorTables() {
+		const pairs = [["arc_anchor_data", "idx_anchor_data"], ["arc_anchor_key", "idx_anchor_key"]];
+		const names = pairs.flat().map((n) => `'${n}'`);
+		const rows = await this.db.all(drizzle_orm.sql.raw(`SELECT name FROM sqlite_master WHERE type='table' AND name IN (${names.join(", ")})`));
+		const present = new Set(rows.map((r) => r.name));
+		for (const [legacy, next] of pairs) {
+			if (!present.has(legacy)) continue;
+			try {
+				if (present.has(next)) await this.db.run(drizzle_orm.sql.raw(`DROP TABLE IF EXISTS ${legacy}`));
+				else await this.db.run(drizzle_orm.sql.raw(`ALTER TABLE ${legacy} RENAME TO ${next}`));
+			} catch {}
+		}
+	}
+	async ensureSchema() {
+		const tokenizer = this.ftsTokenizer.replace(/'/g, "''");
+		await this.renameAnchorTables();
+		await this.db.run(drizzle_orm.sql.raw(`CREATE TABLE IF NOT EXISTS ds_indexed_entry (
+        scope         TEXT NOT NULL,
+        entry_path    TEXT NOT NULL,
+        domain        TEXT,
+        state         TEXT,
+        indexed_at    TEXT,
+        updated_at    TEXT,
+        anchor_count  INTEGER DEFAULT 0,
+        source_path   TEXT,
+        source_hash   TEXT,
+        extractor_id  TEXT,
+        meta          TEXT,
+        PRIMARY KEY (scope, entry_path)
+      )`));
+		await this.db.run(drizzle_orm.sql.raw(`CREATE TABLE IF NOT EXISTS idx_anchor_data (
+        scope        TEXT NOT NULL,
+        entry_path   TEXT NOT NULL,
+        anchor_type  TEXT NOT NULL,
+        confidence   REAL,
+        raw_anchor   TEXT
+      )`));
+		await this.db.run(drizzle_orm.sql.raw(`CREATE TABLE IF NOT EXISTS idx_anchor_key (
+        scope        TEXT NOT NULL,
+        index_key    TEXT NOT NULL,
+        entry_path   TEXT NOT NULL,
+        anchor_type  TEXT NOT NULL,
+        confidence   REAL,
+        PRIMARY KEY (scope, index_key, entry_path, anchor_type)
+      )`));
+		await this.db.run(drizzle_orm.sql.raw(`CREATE INDEX IF NOT EXISTS idx_ad_scope_path ON idx_anchor_data(scope, entry_path)`));
+		await this.db.run(drizzle_orm.sql.raw(`CREATE INDEX IF NOT EXISTS idx_ad_scope_anchor_type ON idx_anchor_data(scope, anchor_type)`));
+		await this.db.run(drizzle_orm.sql.raw(`CREATE INDEX IF NOT EXISTS idx_ak_scope_path ON idx_anchor_key(scope, entry_path)`));
+		await this.db.run(drizzle_orm.sql.raw(`CREATE TABLE IF NOT EXISTS idx_embedding_vector (
+        scope          TEXT NOT NULL,
+        entry_path     TEXT NOT NULL,
+        embedding      TEXT,
+        embedding_blob BLOB,
+        dimension      INTEGER,
+        PRIMARY KEY (scope, entry_path)
+      )`));
+		await this.db.run(drizzle_orm.sql.raw(`CREATE VIRTUAL TABLE IF NOT EXISTS idx_fts USING fts5(
+        scope UNINDEXED,
+        entry_path UNINDEXED,
+        summary,
+        tokenize='${tokenizer}'
+      )`));
+		await this.ensureFtsRowidMapping();
+		await this.db.run(drizzle_orm.sql.raw(`CREATE TABLE IF NOT EXISTS idx_index_cursor (
+        scope        TEXT NOT NULL,
+        consumer_id  TEXT NOT NULL,
+        last_seq     INTEGER NOT NULL DEFAULT 0,
+        watermarks   TEXT,
+        updated_at   INTEGER NOT NULL,
+	served_at    INTEGER,
+        instance_did TEXT,
+        domains      TEXT,
+        PRIMARY KEY (scope, consumer_id)
+      )`));
+	}
+	/**
+	* Create `idx_fts_rowid` the first time this D1 sees it, backfilling from
+	* any pre-existing `idx_fts` rows (issue #1103). The backfill maps every
+	* existing FTS row to its own rowid so a later rewrite REPLACEs in place
+	* instead of leaving a duplicate for the same (scope, entry_path).
+	*
+	* Race-safe across concurrent cold isolates — D1 auto-commits each statement
+	* (no transaction), so two isolates can run this at once on a fresh D1:
+	*   - `CREATE TABLE IF NOT EXISTS` never throws on a concurrent create.
+	*   - The one-time backfill runs only while the mapping is still empty (a
+	*     cheap LIMIT-1 probe, NOT a scan), so steady state costs nothing extra.
+	*   - `INSERT OR IGNORE` makes the backfill itself idempotent, so two
+	*     isolates racing it (or a re-run) can't collide on the PK/UNIQUE.
+	*/
+	async ensureFtsRowidMapping() {
+		await this.db.run(drizzle_orm.sql.raw(`CREATE TABLE IF NOT EXISTS idx_fts_rowid (
+        fts_rowid   INTEGER PRIMARY KEY AUTOINCREMENT,
+        scope       TEXT NOT NULL,
+        entry_path  TEXT NOT NULL,
+        UNIQUE (scope, entry_path)
+      )`));
+		if ((await this.db.all(drizzle_orm.sql.raw("SELECT 1 AS one FROM idx_fts_rowid LIMIT 1"))).length > 0) return;
+		await this.db.run(drizzle_orm.sql.raw(`INSERT OR IGNORE INTO idx_fts_rowid (fts_rowid, scope, entry_path) SELECT rowid, scope, entry_path FROM idx_fts`));
+	}
+	async supportsCursorServedAt() {
+		if (this.d1 && typeof this.d1 === "object") {
+			const cached = cursorServedAtSupported.get(this.d1);
+			if (cached !== void 0) return cached;
+		}
+		const supported = (await this.db.all(drizzle_orm.sql.raw("PRAGMA table_info(idx_index_cursor)"))).some((c) => c.name === "served_at");
+		if (supported && this.d1 && typeof this.d1 === "object") cursorServedAtSupported.set(this.d1, supported);
+		return supported;
+	}
+	async writeEntry(entry) {
+		const e = entryToRow(entry);
+		await this.db.run(drizzle_orm.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 (${this.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})`);
+	}
+	async writeIndexedDocument(document) {
+		const d1 = this.d1BatchBinding();
+		if (!d1) {
+			await this.writeEntry(document.entry);
+			await this.writeAnchors(document.entry.entryPath, document.anchors ?? []);
+			if (document.summary) await this.writeSummary(document.entry.entryPath, document.summary);
+			return;
+		}
+		const entry = entryToRow(document.entry);
+		const entryPath = document.entry.entryPath;
+		const statements = [
+			d1.prepare(`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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).bind(this.scope, entry.entry_path, entry.domain, entry.state, entry.indexed_at, entry.updated_at, entry.anchor_count, entry.source_path, entry.source_hash, entry.extractor_id, entry.meta),
+			d1.prepare("DELETE FROM idx_anchor_data WHERE scope = ? AND entry_path = ?").bind(this.scope, entryPath),
+			d1.prepare("DELETE FROM idx_anchor_key WHERE scope = ? AND entry_path = ?").bind(this.scope, entryPath)
+		];
+		const anchors = document.anchors ?? [];
+		for (const chunk of chunkArray(anchors, 18)) statements.push(d1.prepare(`INSERT INTO idx_anchor_data (scope, entry_path, anchor_type, confidence, raw_anchor) VALUES ${chunk.map(() => "(?, ?, ?, ?, ?)").join(", ")}`).bind(...chunk.flatMap((a) => [
+			this.scope,
+			entryPath,
+			a.type,
+			a.confidence,
+			JSON.stringify(a)
+		])));
+		const keyRows = anchors.flatMap((a) => this.keyRegistry.generateKeys(a).map((key) => ({
+			anchor: a,
+			key
+		})));
+		for (const chunk of chunkArray(keyRows, 18)) statements.push(d1.prepare(`INSERT OR REPLACE INTO idx_anchor_key (scope, index_key, entry_path, anchor_type, confidence) VALUES ${chunk.map(() => "(?, ?, ?, ?, ?)").join(", ")}`).bind(...chunk.flatMap(({ anchor, key }) => [
+			this.scope,
+			key,
+			entryPath,
+			anchor.type,
+			anchor.confidence
+		])));
+		if (document.summary) statements.push(d1.prepare("INSERT INTO idx_fts_rowid (scope, entry_path) VALUES (?, ?) ON CONFLICT(scope, entry_path) DO NOTHING").bind(this.scope, entryPath), d1.prepare(`INSERT OR REPLACE INTO idx_fts (rowid, scope, entry_path, summary)
+	     VALUES ((SELECT fts_rowid FROM idx_fts_rowid WHERE scope = ? AND entry_path = ?), ?, ?, ?)`).bind(this.scope, entryPath, this.scope, entryPath, require_cjk.segmentCJK(document.summary)));
+		await d1.batch(statements);
+	}
+	async getEntry(path) {
+		const rows = await this.db.all(drizzle_orm.sql`SELECT * FROM ds_indexed_entry WHERE scope = ${this.scope} AND entry_path = ${path} LIMIT 1`);
+		if (rows.length === 0) return null;
+		return rowToEntry(rows[0]);
+	}
+	async removeEntry(path) {
+		await this.db.run(drizzle_orm.sql`DELETE FROM ds_indexed_entry WHERE scope = ${this.scope} AND entry_path = ${path}`);
+	}
+	async removeIndexedDocument(path, opts) {
+		const skipVector = opts?.skipVector === true;
+		const d1 = this.d1BatchBinding();
+		if (!d1) {
+			await this.removeAnchors(path);
+			await this.removeSummary(path);
+			if (!skipVector) await this.removeEmbedding(path);
+			await this.removeEntry(path);
+			return;
+		}
+		if (this._injectedVectorBackend && !skipVector) await this.removeEmbedding(path);
+		const statements = [
+			d1.prepare("DELETE FROM idx_anchor_data WHERE scope = ? AND entry_path = ?").bind(this.scope, path),
+			d1.prepare("DELETE FROM idx_anchor_key WHERE scope = ? AND entry_path = ?").bind(this.scope, path),
+			d1.prepare("DELETE FROM idx_fts WHERE rowid = (SELECT fts_rowid FROM idx_fts_rowid WHERE scope = ? AND entry_path = ?)").bind(this.scope, path),
+			d1.prepare("DELETE FROM idx_fts_rowid WHERE scope = ? AND entry_path = ?").bind(this.scope, path),
+			d1.prepare("DELETE FROM ds_indexed_entry WHERE scope = ? AND entry_path = ?").bind(this.scope, path)
+		];
+		if (!this._injectedVectorBackend && !skipVector) statements.splice(4, 0, d1.prepare("DELETE FROM idx_embedding_vector WHERE scope = ? AND entry_path = ?").bind(this.scope, path));
+		await d1.batch(statements);
+	}
+	async listEntries(filter) {
+		const conditions = this.entryConditions(filter);
+		return (await this.db.all(drizzle_orm.sql`SELECT * FROM ds_indexed_entry WHERE ${drizzle_orm.sql.join(conditions, drizzle_orm.sql` AND `)}`)).map(rowToEntry);
+	}
+	entryConditions(filter) {
+		const conditions = [drizzle_orm.sql`scope = ${this.scope}`];
+		if (filter.domain) conditions.push(drizzle_orm.sql`domain = ${filter.domain}`);
+		if (filter.state) conditions.push(drizzle_orm.sql`state = ${filter.state}`);
+		if (filter.extractorId) conditions.push(drizzle_orm.sql`extractor_id = ${filter.extractorId}`);
+		if (filter.scope) conditions.push(drizzle_orm.sql`entry_path LIKE ${`${filter.scope}%`}`);
+		if (filter.boundDomains && filter.boundDomains.length > 0) {
+			const ps = filter.boundDomains.map((d) => drizzle_orm.sql`${d}`);
+			conditions.push(drizzle_orm.sql`domain IN (${drizzle_orm.sql.join(ps, drizzle_orm.sql`, `)})`);
+		}
+		return conditions;
+	}
+	async markStale(filter) {
+		const conditions = [drizzle_orm.sql`scope = ${this.scope}`, drizzle_orm.sql`state = 'active'`];
+		if (filter.domain) conditions.push(drizzle_orm.sql`domain = ${filter.domain}`);
+		if (filter.extractorId) conditions.push(drizzle_orm.sql`extractor_id = ${filter.extractorId}`);
+		if (filter.scope) conditions.push(drizzle_orm.sql`entry_path LIKE ${`${filter.scope}%`}`);
+		if (filter.boundDomains && filter.boundDomains.length > 0) {
+			const ps = filter.boundDomains.map((d) => drizzle_orm.sql`${d}`);
+			conditions.push(drizzle_orm.sql`domain IN (${drizzle_orm.sql.join(ps, drizzle_orm.sql`, `)})`);
+		}
+		if (filter.anchorType) {
+			const anchorRows = await this.db.all(drizzle_orm.sql`SELECT DISTINCT entry_path FROM idx_anchor_data INDEXED BY idx_ad_scope_anchor_type WHERE scope = ${this.scope} AND anchor_type = ${filter.anchorType}`);
+			if (anchorRows.length === 0) return 0;
+			const placeholders = anchorRows.map((r) => drizzle_orm.sql`${r.entry_path}`);
+			conditions.push(drizzle_orm.sql`entry_path IN (${drizzle_orm.sql.join(placeholders, drizzle_orm.sql`, `)})`);
+		}
+		const where = drizzle_orm.sql.join(conditions, drizzle_orm.sql` AND `);
+		const count = (await this.db.all(drizzle_orm.sql`SELECT COUNT(*) as count FROM ds_indexed_entry WHERE ${where}`))[0]?.count ?? 0;
+		if (count === 0) return 0;
+		await this.db.run(drizzle_orm.sql`UPDATE ds_indexed_entry SET state = 'stale' WHERE ${where}`);
+		return count;
+	}
+	async countEntries(filter) {
+		const conditions = this.entryConditions(filter);
+		return (await this.db.all(drizzle_orm.sql`SELECT COUNT(*) as count FROM ds_indexed_entry WHERE ${drizzle_orm.sql.join(conditions, drizzle_orm.sql` AND `)}`))[0]?.count ?? 0;
+	}
+	async writeAnchors(path, anchors) {
+		await this.db.run(drizzle_orm.sql`DELETE FROM idx_anchor_data WHERE scope = ${this.scope} AND entry_path = ${path}`);
+		await this.db.run(drizzle_orm.sql`DELETE FROM idx_anchor_key WHERE scope = ${this.scope} AND entry_path = ${path}`);
+		if (anchors.length === 0) return;
+		const dataRows = anchors.map((a) => drizzle_orm.sql`(${this.scope}, ${path}, ${a.type}, ${a.confidence}, ${JSON.stringify(a)})`);
+		await this.multiRowInsert(drizzle_orm.sql`INSERT INTO idx_anchor_data (scope, entry_path, anchor_type, confidence, raw_anchor) VALUES `, dataRows);
+		const keyRows = anchors.flatMap((a) => this.keyRegistry.generateKeys(a).map((key) => drizzle_orm.sql`(${this.scope}, ${key}, ${path}, ${a.type}, ${a.confidence})`));
+		await this.multiRowInsert(drizzle_orm.sql`INSERT OR REPLACE INTO idx_anchor_key (scope, index_key, entry_path, anchor_type, confidence) VALUES `, keyRows);
+	}
+	/**
+	* Run `<prefix>(row),(row),…` as multi-row INSERT statement(s), chunked so
+	* each stays under D1's 100-bound-parameter-per-statement limit (5 columns per
+	* row → 18 rows ≈ 90 params). No-op on an empty row list. Portable across all
+	* db backends (plain `db.run`, unlike the driver-specific db.batch).
+	*/
+	async multiRowInsert(prefix, rows) {
+		const CHUNK = 18;
+		for (let i = 0; i < rows.length; i += CHUNK) await this.db.run(drizzle_orm.sql`${prefix}${drizzle_orm.sql.join(rows.slice(i, i + CHUNK), drizzle_orm.sql`, `)}`);
+	}
+	async queryAnchors(query) {
+		if (query.keys.length === 0) return [];
+		const keyGroups = 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
+				};
+				for (const k of this.keyRegistry.generateKeys(synthetic)) values.add(k);
+				values.add(raw);
+			}
+			return { values: [...values] };
+		});
+		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 [query.scope, query.pathPrefix]) if (prefix) {
+				const [lo, hi] = require_prefix_range.entryPathPrefixRange(prefix);
+				extraConds.push(drizzle_orm.sql`entry_path >= ${lo} AND entry_path < ${hi}`);
+			}
+			if (query.minConfidence != null) extraConds.push(drizzle_orm.sql`confidence >= ${query.minConfidence}`);
+			const arms = keyGroups[i].values.map((v) => drizzle_orm.sql`SELECT entry_path, confidence FROM idx_anchor_key WHERE ${drizzle_orm.sql.join([
+				drizzle_orm.sql`scope = ${this.scope}`,
+				drizzle_orm.sql`index_key = ${v}`,
+				...extraConds
+			], drizzle_orm.sql` AND `)}`);
+			cteParts.push(drizzle_orm.sql`${drizzle_orm.sql.raw(cteName)} AS (SELECT entry_path, MIN(confidence) as min_conf FROM (${drizzle_orm.sql.join(arms, drizzle_orm.sql` UNION ALL `)}) GROUP BY entry_path)`);
+		}
+		const cteSql = drizzle_orm.sql`WITH ${drizzle_orm.sql.join(cteParts, drizzle_orm.sql`, `)}`;
+		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 metaFilter = query.metaFilter;
+		const domains = query.domains;
+		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(this.scope)}'`);
+			const entryConditions = [];
+			if (domains && domains.length > 0) {
+				const ps = domains.map((d) => drizzle_orm.sql`${d}`);
+				entryConditions.push(drizzle_orm.sql`ie.domain IN (${drizzle_orm.sql.join(ps, drizzle_orm.sql`, `)})`);
+			}
+			for (const [key, expected] of Object.entries(metaFilter ?? {})) if (Array.isArray(expected)) {
+				if (expected.length === 0) return [];
+				const ps = expected.map((v) => drizzle_orm.sql`${v}`);
+				entryConditions.push(drizzle_orm.sql`json_extract(ie.meta, ${`$.${key}`}) IN (${drizzle_orm.sql.join(ps, drizzle_orm.sql`, `)})`);
+			} else entryConditions.push(drizzle_orm.sql`json_extract(ie.meta, ${`$.${key}`}) = ${expected}`);
+			entryWhereSql = drizzle_orm.sql.join(entryConditions, drizzle_orm.sql` AND `);
+		}
+		const allJoins = [...cteJoinParts, ...entryJoinPart].join(" ");
+		let selectSql;
+		if (entryWhereSql) selectSql = drizzle_orm.sql`${cteSql} SELECT ${drizzle_orm.sql.raw(cteNames[0])}.entry_path, ${drizzle_orm.sql.raw(scoreExpr)} as score FROM ${drizzle_orm.sql.raw(cteNames[0])} ${drizzle_orm.sql.raw(allJoins)} WHERE ${entryWhereSql}`;
+		else selectSql = drizzle_orm.sql`${cteSql} SELECT ${drizzle_orm.sql.raw(cteNames[0])}.entry_path, ${drizzle_orm.sql.raw(scoreExpr)} as score FROM ${drizzle_orm.sql.raw(cteNames[0])} ${drizzle_orm.sql.raw(allJoins)}`;
+		const orderSql = query.limit != null ? drizzle_orm.sql`${selectSql} ORDER BY score DESC, ${drizzle_orm.sql.raw(cteNames[0])}.entry_path LIMIT ${query.limit}` : drizzle_orm.sql`${selectSql} ORDER BY score DESC, ${drizzle_orm.sql.raw(cteNames[0])}.entry_path`;
+		return (await this.db.all(orderSql)).map((r) => ({
+			entryPath: r.entry_path,
+			score: r.score
+		}));
+	}
+	async removeAnchors(path) {
+		await this.db.run(drizzle_orm.sql`DELETE FROM idx_anchor_data WHERE scope = ${this.scope} AND entry_path = ${path}`);
+		await this.db.run(drizzle_orm.sql`DELETE FROM idx_anchor_key WHERE scope = ${this.scope} AND entry_path = ${path}`);
+	}
+	async getAnchorData(path) {
+		return (await this.db.all(drizzle_orm.sql`SELECT * FROM idx_anchor_data WHERE scope = ${this.scope} AND entry_path = ${path}`)).map((r) => ({
+			entryPath: r.entry_path,
+			anchorType: r.anchor_type,
+			confidence: r.confidence,
+			rawAnchor: r.raw_anchor
+		}));
+	}
+	async writeSummary(path, summary) {
+		await writeFtsRow(this.db, this.scope, path, require_cjk.segmentCJK(summary));
+	}
+	async getSummary(path) {
+		return (await this.db.all(drizzle_orm.sql`SELECT summary FROM idx_fts WHERE scope = ${this.scope} AND entry_path = ${path} LIMIT 1`))[0]?.summary ?? null;
+	}
+	async queryFTS(text, limit, metaFilter, opts) {
+		try {
+			const sanitized = sanitizeFTS5(text);
+			if (!sanitized) return [];
+			const needsJoin = metaFilter && Object.keys(metaFilter).length > 0 || typeof opts?.domain === "string" && opts.domain.length > 0 || Array.isArray(opts?.domains) && opts.domains.length > 0 || typeof opts?.pathPrefix === "string" && opts.pathPrefix.length > 0;
+			let query;
+			if (needsJoin) {
+				const conditions = [
+					drizzle_orm.sql`idx_fts MATCH ${sanitized}`,
+					drizzle_orm.sql`idx_fts.scope = ${this.scope}`,
+					drizzle_orm.sql`ie.scope = ${this.scope}`
+				];
+				if (opts?.domain) conditions.push(drizzle_orm.sql`ie.domain = ${opts.domain}`);
+				if (opts?.domains && opts.domains.length > 0) {
+					const ps = opts.domains.map((d) => drizzle_orm.sql`${d}`);
+					conditions.push(drizzle_orm.sql`ie.domain IN (${drizzle_orm.sql.join(ps, drizzle_orm.sql`, `)})`);
+				}
+				if (opts?.pathPrefix) conditions.push(drizzle_orm.sql`ie.entry_path LIKE ${`${opts.pathPrefix}%`}`);
+				for (const [key, expected] of Object.entries(metaFilter ?? {})) if (Array.isArray(expected)) {
+					if (expected.length === 0) return [];
+					const ps = expected.map((v) => drizzle_orm.sql`${v}`);
+					conditions.push(drizzle_orm.sql`json_extract(ie.meta, ${`$.${key}`}) IN (${drizzle_orm.sql.join(ps, drizzle_orm.sql`, `)})`);
+				} else conditions.push(drizzle_orm.sql`json_extract(ie.meta, ${`$.${key}`}) = ${expected}`);
+				const where = drizzle_orm.sql.join(conditions, drizzle_orm.sql` AND `);
+				query = limit != null ? drizzle_orm.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}` : drizzle_orm.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 ? drizzle_orm.sql`SELECT entry_path, rank FROM idx_fts WHERE idx_fts MATCH ${sanitized} AND scope = ${this.scope} ORDER BY rank LIMIT ${limit}` : drizzle_orm.sql`SELECT entry_path, rank FROM idx_fts WHERE idx_fts MATCH ${sanitized} AND scope = ${this.scope} ORDER BY rank`;
+			return (await this.db.all(query)).map((r) => ({
+				entryPath: r.entry_path,
+				rank: -r.rank
+			}));
+		} catch {
+			return [];
+		}
+	}
+	async removeSummary(path) {
+		await deleteFtsRow(this.db, this.scope, path);
+	}
+	async writeEmbedding(path, embedding, domain) {
+		await this._vectorBackend.upsert(path, embedding, domain);
+	}
+	async queryVector(embedding, limit, opts) {
+		return this._vectorBackend.query(embedding, {
+			domain: opts?.domain,
+			domains: opts?.domains,
+			pathPrefix: opts?.pathPrefix
+		}, limit);
+	}
+	async removeEmbedding(path) {
+		await this._vectorBackend.delete(path);
+	}
+	embeddingCapability() {
+		return this._vectorBackend.capability();
+	}
+	async readCursor(consumerId) {
+		const rows = await this.db.all(drizzle_orm.sql`SELECT consumer_id, last_seq, watermarks, updated_at FROM idx_index_cursor WHERE scope = ${this.scope} AND consumer_id = ${consumerId} LIMIT 1`);
+		if (rows.length === 0) return null;
+		const row = rows[0];
+		return {
+			consumerId: row.consumer_id,
+			lastSeq: row.last_seq,
+			watermarks: row.watermarks ? JSON.parse(row.watermarks) : void 0,
+			updatedAt: row.updated_at
+		};
+	}
+	/**
+	* Set a cursor row's `last_seq` (+ watermarks/updated_at/served_at).
+	*
+	* NOTE (index-follower-dirty-path §4.2 cutover): the index FOLLOWER no longer
+	* calls this — after the changelog replay was deleted, `last_seq` is a DEAD
+	* COLUMN (nothing advances it during drain; scheduling rides `served_at` via
+	* `markCursorServed`). `writeCursor` now has NO production caller (the ops
+	* scripts write cursor rows via raw SQL, not this method); it is retained for
+	* the monotonic-guard test suite + as a stable backend primitive, so the
+	* `MAX(last_seq, excluded.last_seq)` guard (issue #935 BLOCK fix #2) stays
+	* correct there; watermarks/updated_at/served_at update unconditionally.
+	*/
+	async writeCursor(consumerId, lastSeq, watermarks) {
+		const now = Date.now();
+		const watermarksJson = watermarks ? JSON.stringify(watermarks) : null;
+		if (await this.supportsCursorServedAt()) {
+			await this.db.run(drizzle_orm.sql`INSERT INTO idx_index_cursor (scope, consumer_id, last_seq, watermarks, updated_at, served_at)
+	  VALUES (${this.scope}, ${consumerId}, ${lastSeq}, ${watermarksJson}, ${now}, ${now})
+	  ON CONFLICT(scope, 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;
+		}
+		await this.db.run(drizzle_orm.sql`INSERT INTO idx_index_cursor (scope, consumer_id, last_seq, watermarks, updated_at)
+	  VALUES (${this.scope}, ${consumerId}, ${lastSeq}, ${watermarksJson}, ${now})
+          ON CONFLICT(scope, consumer_id) DO UPDATE SET
+            last_seq = MAX(last_seq, excluded.last_seq),
+            watermarks = excluded.watermarks,
+            updated_at = excluded.updated_at`);
+	}
+	async markCursorServed(consumerId) {
+		if (!await this.supportsCursorServedAt()) return;
+		await this.db.run(drizzle_orm.sql`UPDATE idx_index_cursor SET served_at = ${Date.now()} WHERE scope = ${this.scope} AND consumer_id = ${consumerId}`);
+	}
+	async initCursor(consumerId, registration) {
+		const now = Date.now();
+		if (await this.supportsCursorServedAt()) {
+			await this.db.run(drizzle_orm.sql`INSERT OR IGNORE INTO idx_index_cursor (scope, consumer_id, last_seq, watermarks, updated_at, served_at, instance_did, domains)
+	  VALUES (${this.scope}, ${consumerId}, 0, NULL, ${now}, ${now}, ${registration?.instanceDid ?? null}, ${registration?.domainsJson ?? null})`);
+			return;
+		}
+		await this.db.run(drizzle_orm.sql`INSERT OR IGNORE INTO idx_index_cursor (scope, consumer_id, last_seq, watermarks, updated_at, instance_did, domains)
+          VALUES (${this.scope}, ${consumerId}, 0, NULL, ${now}, ${registration?.instanceDid ?? null}, ${registration?.domainsJson ?? null})`);
+	}
+	/**
+	* See {@link IndexBackend.listCursorScopes}. Deliberately NOT filtered by
+	* `this.scope` — this is the one cursor operation that must see EVERY
+	* scope in the D1, so the CF cron can discover work registered by ANY
+	* caller in ANY prior isolate, not just the scope this backend instance
+	* happens to be constructed for.
+	*
+	* `consumerId` is a FAMILY prefix, not an exact match (design.md §4.4
+	* addendum, owner decision 2026-07-05): every real cursor row's
+	* `consumer_id` is scope-qualified via `deriveFollowerConsumerId(scope)`
+	* ("index:{scope}") so a single shared backend/database can host multiple
+	* scopes without their cursor rows colliding — see follower.ts. Discovery
+	* doesn't know the scope in advance (that's its whole job), so it matches
+	* every row whose `consumer_id` starts with `"{consumerId}:"` instead of
+	* one exact value. Callers keep passing the bare `FOLLOWER_CONSUMER_ID`
+	* ("index") — this method appends the `:` separator internally.
+	*/
+	async listCursorScopes(consumerId) {
+		return (await this.db.all(await this.supportsCursorServedAt() ? drizzle_orm.sql`SELECT scope, consumer_id, instance_did, domains, updated_at, served_at FROM idx_index_cursor WHERE consumer_id LIKE ${`${consumerId}:%`}` : drizzle_orm.sql`SELECT scope, consumer_id, instance_did, domains, updated_at FROM idx_index_cursor WHERE consumer_id LIKE ${`${consumerId}:%`}`)).map((r) => ({
+			scope: r.scope,
+			consumerId: r.consumer_id,
+			instanceDid: r.instance_did,
+			domainsJson: r.domains,
+			updatedAt: r.updated_at,
+			servedAt: r.served_at ?? r.updated_at
+		}));
+	}
+	async writeEntriesBatch(entries) {
+		for (const entry of entries) await this.writeEntry(entry);
+	}
+	async writeAnchorsBatch(items) {
+		for (const item of items) await this.writeAnchors(item.path, item.anchors);
+	}
+	async writeSummariesBatch(items) {
+		for (const item of items) await this.writeSummary(item.path, item.summary);
+	}
+	async purgeEntries(paths, opts) {
+		const skipVector = opts?.skipVector === true;
+		const d1 = this.d1BatchBinding();
+		if (d1 && skipVector && paths.length > 0) {
+			const stmts = [];
+			for (const path of paths) stmts.push(d1.prepare("DELETE FROM idx_anchor_data WHERE scope = ? AND entry_path = ?").bind(this.scope, path), d1.prepare("DELETE FROM idx_anchor_key WHERE scope = ? AND entry_path = ?").bind(this.scope, path), d1.prepare("DELETE FROM idx_fts WHERE rowid = (SELECT fts_rowid FROM idx_fts_rowid WHERE scope = ? AND entry_path = ?)").bind(this.scope, path), d1.prepare("DELETE FROM idx_fts_rowid WHERE scope = ? AND entry_path = ?").bind(this.scope, path), d1.prepare("DELETE FROM ds_indexed_entry WHERE scope = ? AND entry_path = ?").bind(this.scope, path));
+			for (const chunk of chunkArray(stmts, 50)) await d1.batch(chunk);
+			return paths.length;
+		}
+		for (const path of paths) {
+			await this.removeAnchors(path);
+			await this.removeSummary(path);
+			if (!skipVector) await this.removeEmbedding(path);
+			await this.removeEntry(path);
+		}
+		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(drizzle_orm.sql`INSERT INTO idx_fts_rowid (scope, entry_path) VALUES (${scope}, ${path})
+        ON CONFLICT(scope, entry_path) DO NOTHING`);
+	return (await db.all(drizzle_orm.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(drizzle_orm.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(drizzle_orm.sql`DELETE FROM idx_fts WHERE rowid = (SELECT fts_rowid FROM idx_fts_rowid WHERE scope = ${scope} AND entry_path = ${path})`);
+	await db.run(drizzle_orm.sql`DELETE FROM idx_fts_rowid WHERE scope = ${scope} AND entry_path = ${path}`);
+}
+function entryToRow(entry) {
+	return {
+		entry_path: entry.entryPath,
+		domain: entry.domain,
+		state: entry.state,
+		indexed_at: entry.indexedAt,
+		updated_at: entry.updatedAt,
+		anchor_count: entry.anchorCount,
+		source_path: entry.sourcePath ?? null,
+		source_hash: entry.sourceHash ?? null,
+		extractor_id: entry.extractorId ?? null,
+		meta: entry.meta != null ? JSON.stringify(entry.meta) : null
+	};
+}
+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 sqlEscape(value) {
+	return value.replace(/'/g, "''");
+}
+function chunkArray(items, size) {
+	const chunks = [];
+	for (let i = 0; i < items.length; i += size) chunks.push(items.slice(i, i + size));
+	return chunks;
+}
+function sanitizeFTS5(text) {
+	return text.replace(/["*^()\-+{}:]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+//#endregion
+exports.D1IndexBackend = D1IndexBackend;