@aigne/afs-index 1.12.0-beta.5

package/dist/index-provider.mjs

@@ -0,0 +1,1167 @@
+import { generateTimeKeys } from "./keys/time.mjs";
+import { KeyGeneratorRegistry } from "./keys/registry.mjs";
+import { SQLiteIndexBackend } from "./backend/sqlite-backend.mjs";
+import { createEmbedder } from "./embed.mjs";
+import { extractFromMeta } from "./extraction/defaults.mjs";
+import { ExtractorManager } from "./extraction/manager.mjs";
+import { createNormalizedValueGenerator } from "./keys/normalized.mjs";
+import { QueryEngine } from "./query/engine.mjs";
+import { DEFAULT_SEARCH_MODE, SEARCH_MODES } from "./types.mjs";
+import { __decorate } from "./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.mjs";
+import { explainZodError, makeNsLog } from "@aigne/afs";
+import { joinURL } from "ufo";
+import { AFSBaseProvider, Actions, Explain, List, Meta, Read, Search } from "@aigne/afs/provider";
+import { z } from "zod/v4";
+
+//#region src/index-provider.ts
+const log = makeNsLog("provider:index");
+const IndexArgsSchema = z.object({
+	entryPath: z.string(),
+	domain: z.string().optional(),
+	anchors: z.array(z.object({
+		type: z.string(),
+		confidence: z.number()
+	}).passthrough()).optional(),
+	summary: z.string().optional(),
+	embeddingSummary: z.string().optional(),
+	embedding: z.array(z.number()).optional(),
+	sourcePath: z.string().optional(),
+	sourceHash: z.string().optional(),
+	extractorId: z.string().optional(),
+	meta: z.record(z.string(), z.unknown()).optional()
+});
+const QueryArgsSchema = z.object({
+	mode: z.enum(SEARCH_MODES).optional(),
+	ftsMode: z.enum(["and", "or"]).optional(),
+	anchors: z.array(z.object({
+		type: z.string(),
+		values: z.array(z.string())
+	})).optional(),
+	text: z.string().optional(),
+	embeddingText: z.string().optional(),
+	embedding: z.array(z.number()).optional(),
+	rewriter: z.enum(["none", "multi-query"]).optional(),
+	opts: z.object({
+		scope: z.string().optional(),
+		pathPrefix: z.string().optional(),
+		limit: z.number().optional(),
+		cursor: z.string().optional(),
+		minResults: z.number().optional(),
+		minConfidence: z.number().optional(),
+		metaFilter: z.record(z.string(), z.unknown()).optional(),
+		embeddingFloor: z.number().optional(),
+		anchorFilter: z.boolean().optional(),
+		explain: z.boolean().optional()
+	}).optional()
+});
+const ReindexArgsSchema = z.object({
+	scope: z.string().optional(),
+	extractorId: z.string().optional(),
+	domain: z.string().optional()
+});
+const RegisterDomainArgsSchema = z.object({
+	name: z.string(),
+	types: z.array(z.object({ name: z.string() }).passthrough()).optional()
+});
+const GetArgsSchema = z.object({
+	entryPath: z.string().optional(),
+	entryPaths: z.array(z.string()).optional()
+});
+const CleanupArgsSchema = z.object({
+	state: z.enum(["stale", "removed"]).optional().default("stale"),
+	domain: z.string().optional(),
+	scope: z.string().optional()
+});
+const VerifyArgsSchema = z.object({
+	domain: z.string().optional(),
+	scope: z.string().optional()
+});
+const DiscoverArgsSchema = z.object({
+	providerPath: z.string(),
+	domain: z.string().optional()
+});
+const afsIndexOptionsSchema = z.object({
+	dbPath: z.string().optional(),
+	defaultDomain: z.string().optional()
+});
+var AFSIndex = class extends AFSBaseProvider {
+	name;
+	description;
+	accessMode = "readwrite";
+	options;
+	keyRegistry = new KeyGeneratorRegistry();
+	backend;
+	queryEngine;
+	domains = /* @__PURE__ */ new Map();
+	extractors = new ExtractorManager();
+	unsubscribes = [];
+	afsRoot;
+	initialized = false;
+	follower;
+	catchUpInflight;
+	static schema() {
+		return afsIndexOptionsSchema;
+	}
+	static manifest() {
+		return {
+			name: "index",
+			description: "Full-text search and anchor-based indexing for AFS entries.\n- FTS5 full-text search on summaries\n- Structured anchor indexing (time, person, topic, location)\n- Combined query modes: anchor, fts, semantic\n- Actions: index, query, reindex, cleanup",
+			uriTemplate: "index://{dbPath+}",
+			category: "composite",
+			schema: z.object({
+				dbPath: z.string(),
+				defaultDomain: z.string().optional()
+			}),
+			tags: [
+				"index",
+				"search",
+				"fts5",
+				"sqlite",
+				"anchor"
+			],
+			capabilityTags: [
+				"read-write",
+				"search",
+				"auth:none",
+				"local"
+			],
+			security: {
+				riskLevel: "local",
+				resourceAccess: ["local-filesystem"],
+				dataSensitivity: [],
+				notes: ["Stores SQLite index database on local filesystem"]
+			}
+		};
+	}
+	constructor(options = {}) {
+		super();
+		this.options = options;
+		this.name = options.name ?? "index";
+		this.description = options.description ?? "AFS Index Provider — unified structured indexing";
+		if (options.timeKeyGranularity?.length) {
+			const include = new Set(options.timeKeyGranularity);
+			this.keyRegistry.register("time", (anchor) => generateTimeKeys(anchor, include));
+		}
+	}
+	async ensureInitialized() {
+		if (this.initialized) return;
+		this.backend = this.options.backend ?? new SQLiteIndexBackend(this.options.dbPath ?? ":memory:", this.keyRegistry, { ftsTokenizer: this.options.ftsTokenizer });
+		this.backend.setKeyRegistry?.(this.keyRegistry);
+		await this.backend.initialize();
+		this.queryEngine = new QueryEngine(this.backend);
+		this.initialized = true;
+	}
+	onMount(root, _mountPath) {
+		this.afsRoot = root;
+		const unsubWrite = root.subscribe?.({ type: "afs:write" }, (event) => {
+			this.handleWriteEvent(event.path);
+		});
+		if (unsubWrite) this.unsubscribes.push(unsubWrite);
+		const unsubDelete = root.subscribe?.({ type: "afs:delete" }, (event) => {
+			this.handleDeleteEvent(event.path);
+		});
+		if (unsubDelete) this.unsubscribes.push(unsubDelete);
+		const unsubMount = root.subscribe?.({ type: "afs:mount" }, (event) => {
+			if (event.source === this.name) return;
+			this.handleMountEvent(event.path);
+		});
+		if (unsubMount) this.unsubscribes.push(unsubMount);
+	}
+	async handleMountEvent(providerPath) {
+		try {
+			if (!this.afsRoot) return;
+			const domainName = providerPath.split("/").filter(Boolean).pop() ?? "unknown";
+			const result = await this.discoverProvider(providerPath, domainName);
+			if (result.anchorTypes.length === 0 && !result.config && !result.extractor) this.domains.delete(domainName);
+		} catch {}
+	}
+	async handleDeleteEvent(path) {
+		try {
+			await this.ensureInitialized();
+			if (!await this.backend.getEntry(path)) return;
+			await this.backend.removeAnchors(path);
+			await this.backend.removeSummary(path);
+			if (this.backend.removeEmbedding) await this.backend.removeEmbedding(path);
+			await this.backend.removeEntry(path);
+		} catch {}
+	}
+	async handleWriteEvent(path) {
+		try {
+			if (!this.afsRoot) return;
+			await this.ensureInitialized();
+			let domain;
+			let result;
+			const extracted = this.extractors.hasRegistrations ? await this.extractors.extract(path, this.afsRoot) : null;
+			if (extracted) {
+				domain = extracted.domain;
+				result = extracted.result;
+			} else {
+				const readResult = await this.afsRoot.read?.(path);
+				if (!readResult?.data?.meta) return;
+				const entry = readResult.data;
+				const defaultResult = extractFromMeta(path, entry.meta);
+				if (!defaultResult) return;
+				domain = this.options.defaultDomain ?? "default";
+				result = defaultResult;
+			}
+			if (!this.shouldIndex(path, domain)) return;
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			await this.backend.writeEntry({
+				entryPath: path,
+				sourcePath: path,
+				domain,
+				state: "active",
+				indexedAt: now,
+				updatedAt: now,
+				anchorCount: result.anchors.length
+			});
+			if (result.anchors.length > 0) await this.backend.writeAnchors(path, result.anchors);
+			if (result.summary) await this.backend.writeSummary(path, result.summary);
+			if (this.backend.writeEmbedding) {
+				const embedding = result.embedding ?? await this.autoEmbed(result.summary);
+				if (embedding) await this.backend.writeEmbedding(path, embedding);
+			}
+		} catch {}
+	}
+	async close() {
+		for (const unsub of this.unsubscribes) unsub();
+		this.unsubscribes.length = 0;
+		this.extractors.clear();
+		if (this.initialized) {
+			await this.backend.close();
+			this.initialized = false;
+		}
+	}
+	async readRoot(ctx) {
+		return this.buildEntry(ctx.path, {
+			content: this.description,
+			meta: {
+				kind: "afs:directory",
+				childrenCount: 3
+			}
+		});
+	}
+	async listRoot(ctx) {
+		return { data: [
+			this.buildEntry(joinURL(ctx.path, "domains"), { meta: {
+				kind: "afs:directory",
+				childrenCount: this.domains.size
+			} }),
+			this.buildEntry(joinURL(ctx.path, "stats"), { meta: {
+				kind: "afs:directory",
+				childrenCount: 3
+			} }),
+			this.buildEntry(joinURL(ctx.path, "config"), { meta: {
+				kind: "afs:directory",
+				childrenCount: 3
+			} })
+		] };
+	}
+	async listActions(ctx) {
+		const actions = [
+			"index",
+			"query",
+			"get",
+			"reindex",
+			"cleanup",
+			"verify",
+			"register-domain",
+			"discover"
+		];
+		const READ_ACTIONS = new Set([
+			"query",
+			"get",
+			"discover",
+			"verify"
+		]);
+		return { data: actions.map((name) => this.buildEntry(joinURL(ctx.path, name), {
+			id: name,
+			meta: {
+				kind: "afs:executable",
+				effect: READ_ACTIONS.has(name) ? "read" : "write"
+			}
+		})) };
+	}
+	readDomains(ctx) {
+		return this.buildEntry(ctx.path, { meta: {
+			kind: "afs:directory",
+			childrenCount: this.domains.size
+		} });
+	}
+	readStatsDir(ctx) {
+		return this.buildEntry(ctx.path, { meta: {
+			kind: "afs:directory",
+			childrenCount: 3
+		} });
+	}
+	readConfigDir(ctx) {
+		return this.buildEntry(ctx.path, { meta: {
+			kind: "afs:directory",
+			childrenCount: 3
+		} });
+	}
+	async listDomains(ctx) {
+		return { data: Array.from(this.domains.values()).map((d) => this.buildEntry(joinURL(ctx.path, d.name), {
+			id: d.name,
+			content: {
+				types: d.types.map((t) => t.name),
+				indexable: d.config?.indexable
+			}
+		})) };
+	}
+	async listStatsDir(ctx) {
+		return { data: [
+			"total-entries",
+			"active-entries",
+			"stale-entries"
+		].map((key) => this.buildEntry(joinURL(ctx.path, key), {
+			id: key,
+			meta: {
+				kind: "afs:value",
+				childrenCount: 0
+			}
+		})) };
+	}
+	listConfig(ctx) {
+		return { data: [
+			"llm-provider",
+			"embedding-enabled",
+			"default-domain"
+		].map((key) => this.buildEntry(joinURL(ctx.path, key), {
+			id: key,
+			meta: {
+				kind: "afs:value",
+				childrenCount: 0
+			}
+		})) };
+	}
+	listStatsKey() {
+		return { data: [] };
+	}
+	listConfigKey() {
+		return { data: [] };
+	}
+	async listDomainName(ctx) {
+		await this.ensureInitialized();
+		return { data: (await this.backend.listEntries({ domain: ctx.params.name })).map((e) => this.buildEntry(joinURL(ctx.path, encodeURIComponent(e.entryPath)), {
+			id: e.entryPath,
+			content: {
+				entryPath: e.entryPath,
+				sourcePath: e.sourcePath,
+				state: e.state,
+				anchorCount: e.anchorCount,
+				indexedAt: e.indexedAt,
+				updatedAt: e.updatedAt
+			},
+			meta: {
+				kind: "index:entry",
+				domain: e.domain,
+				state: e.state,
+				anchorCount: e.anchorCount,
+				childrenCount: 0,
+				...e.meta ?? {}
+			},
+			createdAt: new Date(e.indexedAt),
+			updatedAt: new Date(e.updatedAt)
+		})) };
+	}
+	readRootMeta(ctx) {
+		const meta = {
+			kind: "afs:directory",
+			childrenCount: 3
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readDomainsMeta(ctx) {
+		const meta = {
+			kind: "afs:directory",
+			childrenCount: this.domains.size
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readStatsMeta(ctx) {
+		const meta = {
+			kind: "afs:directory",
+			childrenCount: 3
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readConfigMeta(ctx) {
+		const meta = {
+			kind: "afs:directory",
+			childrenCount: 3
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readStatsKeyMeta(ctx) {
+		const meta = {
+			kind: "afs:value",
+			childrenCount: 0
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readConfigKeyMeta(ctx) {
+		const meta = {
+			kind: "afs:value",
+			childrenCount: 0
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	async readDomainNameMeta(ctx) {
+		await this.ensureInitialized();
+		const meta = {
+			kind: "afs:directory",
+			childrenCount: await this.backend.countEntries({ domain: ctx.params.name })
+		};
+		return this.buildEntry(ctx.path, {
+			content: meta,
+			meta
+		});
+	}
+	readCapabilities(ctx) {
+		return this.buildEntry(ctx.path, { content: { operations: this.getOperationsDeclaration() } });
+	}
+	explainRoot(_ctx) {
+		return {
+			content: `AFS Index Provider — unified structured indexing.\n\nCombines anchor indexing, full-text search, and optional embedding search. Domains: ${this.domains.size} registered.`,
+			format: "text"
+		};
+	}
+	explainPath(ctx) {
+		return {
+			content: `Index provider path: /${ctx.params.path}`,
+			format: "text"
+		};
+	}
+	async searchHandler(_ctx, query, options) {
+		await this.ensureInitialized();
+		try {
+			return { data: (await this.queryEngine.query({
+				mode: "fts",
+				text: query,
+				opts: { limit: options?.limit }
+			})).map((r) => this.buildEntry(r.entryPath, { content: {
+				matchType: r.matchType,
+				score: r.score
+			} })) };
+		} catch {
+			return { data: [] };
+		}
+	}
+	async readConfig(ctx) {
+		switch (ctx.params.key) {
+			case "llm-provider": return this.buildEntry(ctx.path, { content: { value: this.options.llmProvider ?? null } });
+			case "embedding-enabled": return this.buildEntry(ctx.path, { content: { value: this.options.embeddingEnabled ?? false } });
+			case "default-domain": return this.buildEntry(ctx.path, { content: { value: this.options.defaultDomain ?? "default" } });
+			default: return;
+		}
+	}
+	async readStats(ctx) {
+		await this.ensureInitialized();
+		switch (ctx.params.key) {
+			case "total-entries": {
+				const count = await this.backend.countEntries({});
+				return this.buildEntry(ctx.path, { content: { value: count } });
+			}
+			case "active-entries": {
+				const count = await this.backend.countEntries({ state: "active" });
+				return this.buildEntry(ctx.path, { content: { value: count } });
+			}
+			case "stale-entries": {
+				const count = await this.backend.countEntries({ state: "stale" });
+				return this.buildEntry(ctx.path, { content: { value: count } });
+			}
+			default: return;
+		}
+	}
+	async execIndex(_ctx, args) {
+		const parsed = IndexArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, IndexArgsSchema)
+			}
+		};
+		await this.ensureInitialized();
+		const { entryPath, anchors: rawAnchors, summary, embeddingSummary, embedding: explicitEmbedding, sourcePath, sourceHash, extractorId, meta } = parsed.data;
+		const domain = parsed.data.domain ?? this.options.defaultDomain ?? "default";
+		const anchors = rawAnchors ?? [];
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const entry = {
+			entryPath,
+			sourcePath,
+			sourceHash,
+			domain,
+			state: "active",
+			extractorId,
+			indexedAt: now,
+			updatedAt: now,
+			anchorCount: anchors.length,
+			meta
+		};
+		await this.backend.writeEntry(entry);
+		if (anchors.length > 0) await this.backend.writeAnchors(entryPath, anchors);
+		if (summary) await this.backend.writeSummary(entryPath, summary);
+		if (this.backend.writeEmbedding) {
+			const embedding = explicitEmbedding ?? await this.autoEmbed(embeddingSummary ?? summary);
+			if (embedding) await this.backend.writeEmbedding(entryPath, embedding);
+		}
+		return {
+			success: true,
+			data: {
+				entryPath,
+				anchorCount: anchors.length
+			}
+		};
+	}
+	async execQuery(_ctx, args) {
+		const misplaced = [
+			"limit",
+			"cursor",
+			"anchorFilter",
+			"explain",
+			"scope",
+			"pathPrefix",
+			"minConfidence",
+			"metaFilter",
+			"embeddingFloor",
+			"minResults"
+		].filter((k) => k in args);
+		if (misplaced.length > 0) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: `Parameter(s) ${misplaced.map((k) => `"${k}"`).join(", ")} must be nested inside "opts" (e.g. { opts: { ${misplaced[0]}: ... } })`
+			}
+		};
+		const parsed = QueryArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, QueryArgsSchema)
+			}
+		};
+		await this.ensureInitialized();
+		if (this.follower && !parsed.data.opts?.cursor) {
+			const { task, started } = this.startCatchUpOnce();
+			const schedule = this.options.scheduleBackground;
+			if (schedule) {
+				if (started) schedule(task);
+			} else await task;
+		}
+		const { anchors, text, embeddingText, opts } = parsed.data;
+		const mode = parsed.data.mode ?? this.options.defaultSearchMode ?? DEFAULT_SEARCH_MODE;
+		const ftsMode = parsed.data.ftsMode;
+		const rewriter = parsed.data.rewriter ?? "none";
+		if (rewriter !== "none" && opts?.cursor) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: "Query cursor is not supported with rewriter mode"
+			}
+		};
+		if (rewriter === "multi-query" && !parsed.data.embedding && (text || embeddingText) && this.resolveChatProvider()) {
+			const original = embeddingText ?? text;
+			return {
+				success: true,
+				data: { results: await this.queryWithMultiQuery({
+					original,
+					ftsText: text,
+					mode,
+					anchors,
+					opts
+				}) }
+			};
+		}
+		const embedding = parsed.data.embedding ?? (mode === "semantic" ? await this.autoEmbed(embeddingText ?? text, "query") : null);
+		let page;
+		try {
+			page = await this.queryEngine.queryPage({
+				mode,
+				ftsMode,
+				anchors,
+				text,
+				embedding: embedding ?? void 0,
+				opts: this.options.embeddingFloor != null && opts?.embeddingFloor == null ? {
+					...opts,
+					embeddingFloor: this.options.embeddingFloor
+				} : opts,
+				boundDomains: this.options.boundDomains
+			});
+		} catch (err) {
+			if (err instanceof Error && err.message === "Invalid or stale query cursor") return {
+				success: false,
+				error: {
+					code: "VALIDATION_ERROR",
+					message: err.message
+				}
+			};
+			throw err;
+		}
+		const { results } = page;
+		if (opts?.explain) {
+			const explanation = await this.buildExplanation({
+				mode,
+				text,
+				embeddingText,
+				anchors,
+				opts,
+				embeddingUsed: embedding !== null && embedding !== void 0,
+				results
+			});
+			log.debug("query explain", {
+				...explanation,
+				results: results.map((r) => ({
+					path: r.entryPath,
+					matchType: r.matchType,
+					score: r.score,
+					explanation: r.explanation
+				}))
+			});
+			return {
+				success: true,
+				data: {
+					results,
+					explanation,
+					...page.meta ? { meta: page.meta } : {}
+				}
+			};
+		}
+		return {
+			success: true,
+			data: {
+				results,
+				...page.meta ? { meta: page.meta } : {}
+			}
+		};
+	}
+	/**
+	* Build a "why did the query return what it returned" diagnostic.
+	*
+	* Cheap probes only: scope cardinality (countEntries), result-type
+	* breakdown (already in the result list), echo of the parsed inputs.
+	* Does not re-run the query — purely additive per planning doc §P4.
+	*/
+	async buildExplanation(args) {
+		const { mode, text, embeddingText, anchors, opts, embeddingUsed, results } = args;
+		const scopeFilter = opts?.scope;
+		const domain = scopeFilter ? scopeFilter.replace(/^\/+/, "") : void 0;
+		let totalIndexedInScope;
+		try {
+			totalIndexedInScope = await this.backend.countEntries({
+				...domain ? { domain } : {},
+				...scopeFilter ? { scope: scopeFilter } : {},
+				state: "active"
+			});
+		} catch {
+			totalIndexedInScope = void 0;
+		}
+		const matchTypeBreakdown = {};
+		for (const r of results) matchTypeBreakdown[r.matchType] = (matchTypeBreakdown[r.matchType] ?? 0) + 1;
+		let whyEmpty;
+		if (results.length === 0) if (totalIndexedInScope === 0) whyEmpty = `No entries indexed in scope "${scopeFilter ?? "(no scope)"}" — likely a domain mismatch or missing ingestion.`;
+		else if (mode === "fts" && !text) whyEmpty = "FTS mode requested but `text` was empty.";
+		else if (mode === "anchor" && (!anchors || anchors.length === 0)) whyEmpty = "Anchor mode requested but `anchors` was empty.";
+		else if (mode === "semantic" && !embeddingUsed) whyEmpty = "Semantic mode requested but no embedding was generated (no `text`/`embeddingText` and no auto-embed available).";
+		else whyEmpty = `Index has ${totalIndexedInScope ?? "?"} entries in scope but none matched query.`;
+		return {
+			mode,
+			ftsQuery: text,
+			embeddingText: embeddingText ?? text,
+			embeddingUsed,
+			anchors,
+			scope: scopeFilter,
+			metaFilter: opts?.metaFilter,
+			totalIndexedInScope,
+			resultCount: results.length,
+			matchTypeBreakdown,
+			whyEmpty
+		};
+	}
+	async execGet(_ctx, args) {
+		const parsed = GetArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, GetArgsSchema)
+			}
+		};
+		await this.ensureInitialized();
+		const paths = parsed.data.entryPaths ?? (parsed.data.entryPath ? [parsed.data.entryPath] : []);
+		if (paths.length === 0) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: "entryPath or entryPaths required"
+			}
+		};
+		const bound = this.options.boundDomains;
+		const inBounds = (entry) => !entry || !bound || bound.length === 0 || bound.includes(entry.domain);
+		const entries = [];
+		for (const p of paths) {
+			const entry = await this.backend.getEntry(p);
+			if (!inBounds(entry)) {
+				entries.push({
+					entryPath: p,
+					entry: null,
+					summary: null
+				});
+				continue;
+			}
+			const summary = this.backend.getSummary ? await this.backend.getSummary(p) : null;
+			entries.push({
+				entryPath: p,
+				entry,
+				summary
+			});
+		}
+		return {
+			success: true,
+			data: { entries }
+		};
+	}
+	async execReindex(_ctx, args) {
+		const parsed = ReindexArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, ReindexArgsSchema)
+			}
+		};
+		await this.ensureInitialized();
+		const { scope, extractorId, domain } = parsed.data;
+		return {
+			success: true,
+			data: { staleCount: await this.backend.markStale({
+				scope,
+				extractorId,
+				domain,
+				boundDomains: this.options.boundDomains
+			}) }
+		};
+	}
+	async execCleanup(_ctx, args) {
+		const parsed = CleanupArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, CleanupArgsSchema)
+			}
+		};
+		await this.ensureInitialized();
+		const { state, domain, scope } = parsed.data;
+		const paths = (await this.backend.listEntries({
+			state,
+			domain,
+			scope,
+			boundDomains: this.options.boundDomains
+		})).map((e) => e.entryPath);
+		let purgedCount;
+		if (this.backend.purgeEntries) purgedCount = await this.backend.purgeEntries(paths);
+		else {
+			purgedCount = 0;
+			for (const path of paths) {
+				await this.backend.removeAnchors(path);
+				await this.backend.removeSummary(path);
+				if (this.backend.removeEmbedding) await this.backend.removeEmbedding(path);
+				await this.backend.removeEntry(path);
+				purgedCount++;
+			}
+		}
+		return {
+			success: true,
+			data: { purgedCount }
+		};
+	}
+	/**
+	* `verify` — index self-stats for drift detection.
+	*
+	* Returns the index's own view of what it holds: total entries, breakdown
+	* by domain and state, and how many entries have zero anchors (a common
+	* symptom of a half-finished or corrupted index). A caller compares these
+	* against the source-of-truth provider (e.g. memory's `health.totalEntries`)
+	* to decide whether to trigger a rebuild — without guessing from empty
+	* query results.
+	*/
+	async execVerify(_ctx, args) {
+		const parsed = VerifyArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, VerifyArgsSchema)
+			}
+		};
+		await this.ensureInitialized();
+		const { domain, scope } = parsed.data;
+		const entries = await this.backend.listEntries({
+			...domain ? { domain } : {},
+			...scope ? { scope } : {},
+			boundDomains: this.options.boundDomains
+		});
+		const byDomain = {};
+		const byState = {};
+		let anchorlessCount = 0;
+		for (const e of entries) {
+			byDomain[e.domain] = (byDomain[e.domain] ?? 0) + 1;
+			byState[e.state] = (byState[e.state] ?? 0) + 1;
+			if (!e.anchorCount) anchorlessCount++;
+		}
+		return {
+			success: true,
+			data: {
+				totalEntries: entries.length,
+				byDomain,
+				byState,
+				anchorlessCount,
+				...domain ? { domain } : {},
+				...scope ? { scope } : {}
+			}
+		};
+	}
+	/**
+	* Register one or more domains from a manifest projection, wiring each
+	* declared anchor type into the key registry (normalizedValue by default).
+	*
+	* This is the non-exec entry point for session-view wiring: called at index
+	* handle creation time so domains survive Worker restarts (the in-memory
+	* handles are rebuilt from the manifest on every cold start).
+	*/
+	registerDomains(domains) {
+		for (const domain of domains) {
+			this.domains.set(domain.name, {
+				name: domain.name,
+				...domain.scope ? { scope: domain.scope } : {},
+				types: domain.anchorTypes,
+				...domain.config ? { config: domain.config } : {}
+			});
+			this.registerAnchorTypeKeyGenerators(domain.anchorTypes);
+		}
+	}
+	/**
+	* Attach a changelog follower so execQuery triggers a lightweight catch-up
+	* before returning results. Called once at index handle creation time by the
+	* CF session-view (cf-session-view.ts) after building the follower.
+	*/
+	setFollower(follower) {
+		this.follower = follower;
+		follower.setEmbedder((text) => this.autoEmbed(text, "passage"));
+	}
+	startCatchUpOnce() {
+		if (this.catchUpInflight) return {
+			task: this.catchUpInflight,
+			started: false
+		};
+		const follower = this.follower;
+		if (!follower) return {
+			task: Promise.resolve(),
+			started: false
+		};
+		let task;
+		task = follower.runCatchUp().catch(() => {}).finally(() => {
+			if (this.catchUpInflight === task) this.catchUpInflight = void 0;
+		});
+		this.catchUpInflight = task;
+		return {
+			task,
+			started: true
+		};
+	}
+	/**
+	* Wire declared anchor types into the shared key registry. Types with an
+	* explicit function keyGenerator use it directly; types without one get a
+	* normalizedValue generator (lowercase+trim) instead of the exact fallback
+	* (JSON.stringify, field-order/case-sensitive).
+	*
+	* Built-in types (time/location/person/topic — registered in
+	* `KeyGeneratorRegistry`'s constructor) are never overwritten here, even if
+	* a manifest or `.index/anchor-types/` declaration reuses one of those
+	* names: the built-in's multi-dimensional key generator always wins (issue
+	* #934 P0 — see `KeyGeneratorRegistry.isBuiltin`). Shared by
+	* `registerDomains` (manifest wiring) and `discoverProvider` (`.index/`
+	* convention wiring) — previously duplicated inline in both.
+	*/
+	registerAnchorTypeKeyGenerators(anchorTypes) {
+		for (const anchorType of anchorTypes) {
+			if (this.keyRegistry.isBuiltin(anchorType.name)) continue;
+			if (typeof anchorType.keyGenerator === "function") this.keyRegistry.register(anchorType.name, anchorType.keyGenerator);
+			else this.keyRegistry.register(anchorType.name, createNormalizedValueGenerator());
+		}
+	}
+	async execRegisterDomain(_ctx, args) {
+		const parsed = RegisterDomainArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, RegisterDomainArgsSchema)
+			}
+		};
+		const name = parsed.data.name;
+		const types = parsed.data.types ?? [];
+		this.domains.set(name, {
+			name,
+			types
+		});
+		return {
+			success: true,
+			data: {
+				domain: name,
+				typeCount: types.length
+			}
+		};
+	}
+	async execDiscover(_ctx, args) {
+		const parsed = DiscoverArgsSchema.safeParse(args);
+		if (!parsed.success) return {
+			success: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: explainZodError(parsed.error, DiscoverArgsSchema)
+			}
+		};
+		if (!this.afsRoot) return {
+			success: false,
+			error: {
+				code: "NOT_MOUNTED",
+				message: "Provider not mounted (no AFS root)"
+			}
+		};
+		const { providerPath } = parsed.data;
+		const domainName = parsed.data.domain ?? providerPath.split("/").filter(Boolean).pop() ?? "unknown";
+		const result = await this.discoverProvider(providerPath, domainName);
+		return {
+			success: true,
+			data: {
+				domain: result.domainName,
+				anchorTypes: result.anchorTypes.map((t) => t.name),
+				config: result.config,
+				extractor: result.extractor
+			}
+		};
+	}
+	async discoverProvider(providerPath, domainName) {
+		const root = this.afsRoot;
+		let config;
+		try {
+			const content = (await root.read(joinURL(providerPath, ".index", "config"))).data?.content;
+			if (content && typeof content === "object") config = content;
+		} catch {}
+		const anchorTypes = [];
+		try {
+			const typesPath = joinURL(providerPath, ".index", "anchor-types");
+			const typesList = await root.list(typesPath);
+			for (const entry of typesList.data) if (entry.id) try {
+				const content = (await root.read(joinURL(typesPath, entry.id))).data?.content;
+				if (content && typeof content === "object" && "name" in content) anchorTypes.push(content);
+			} catch {}
+		} catch {}
+		let extractor;
+		try {
+			const content = (await root.read(joinURL(providerPath, ".index", "extractor"))).data?.content;
+			if (content && typeof content === "object" && "path" in content) extractor = content;
+		} catch {}
+		this.domains.set(domainName, {
+			name: domainName,
+			scope: providerPath,
+			types: anchorTypes,
+			config,
+			extractor
+		});
+		this.registerAnchorTypeKeyGenerators(anchorTypes);
+		if (extractor) this.extractors.register(domainName, {
+			id: `${domainName}-extractor`,
+			scope: providerPath,
+			mode: extractor.mode,
+			extractor: extractor.path
+		});
+		return {
+			domainName,
+			anchorTypes,
+			config,
+			extractor
+		};
+	}
+	/**
+	* Check if a path should be indexed based on .index/config rules.
+	* Finds the domain whose scope covers the path and applies its config.
+	* If no matching domain config exists, allows indexing by default.
+	*/
+	shouldIndex(path, _domain) {
+		let config;
+		for (const domainDef of this.domains.values()) if (domainDef.scope && path.startsWith(domainDef.scope) && domainDef.config) {
+			config = domainDef.config;
+			break;
+		}
+		if (!config) return true;
+		const { indexable, skip } = config;
+		if (skip?.some((pattern) => matchGlob(path, pattern))) return false;
+		if (indexable && indexable.length > 0) return indexable.some((pattern) => matchGlob(path, pattern));
+		return true;
+	}
+	/**
+	* Auto-generate embedding via LLM provider if configured and enabled.
+	* Returns null if LLM is not available or embedding is disabled.
+	*
+	* @param type - "passage" for write-time (document), "query" for query-time.
+	*   Models like E5 require different prefixes for query vs passage.
+	*/
+	async autoEmbed(text, type = "passage") {
+		return createEmbedder({
+			embeddingEnabled: this.options.embeddingEnabled,
+			llmProvider: this.options.llmProvider,
+			embedRoot: this.options.embeddingAfsRoot ?? this.afsRoot
+		})(text, type);
+	}
+	/**
+	* Resolve the chat-action path used by query rewriters. Prefers an
+	* explicit `chatProvider` config; falls back to `<llmProvider>/.actions/chat`
+	* because the same AigneHub default endpoint hosts both embedding
+	* and chat actions in practice.
+	*/
+	resolveChatProvider() {
+		if (this.options.chatProvider) return this.options.chatProvider;
+		if (this.options.llmProvider) return joinURL(this.options.llmProvider, ".actions", "chat");
+		return null;
+	}
+	/**
+	* Generate paraphrases of `question` via the chat provider. Returns
+	* the paraphrases plus the original question (the original is kept
+	* as a safety net in case the rewrites drift). Returns just `[question]`
+	* if the chat call fails — degrades gracefully to baseline.
+	*/
+	async generateParaphrases(question) {
+		const chatPath = this.resolveChatProvider();
+		const chatRoot = this.options.embeddingAfsRoot ?? this.afsRoot;
+		if (!chatPath || !chatRoot) return [question];
+		try {
+			const result = await chatRoot.exec(chatPath, { messages: [{
+				role: "system",
+				content: "Rewrite a search query as 3 different paraphrases that mean the same thing but use different vocabulary. Each paraphrase should be a single line. Output exactly 3 lines, no numbering, no preamble. Keep them concrete and search-ready."
+			}, {
+				role: "user",
+				content: question
+			}] }, {});
+			if (!result.success || !result.data) return [question];
+			const data = result.data;
+			if (!data.text) return [question];
+			return [question, ...data.text.split("\n").map((l) => l.replace(/^\s*[-*0-9.)\]]+\s*/, "").trim()).filter((l) => l.length > 0).slice(0, 3)];
+		} catch {
+			return [question];
+		}
+	}
+	/**
+	* Multi-query retrieval: generate N paraphrases, embed each, run a
+	* separate semantic query per variant, and RRF-fuse the result lists.
+	* The `index-diverse-bench` shows 2.6× MRR lift on paraphrase queries
+	* with this strategy. Each variant pulls top-(2×limit) so the fusion
+	* has enough candidates to differentiate; the final list is trimmed
+	* to the caller's requested limit.
+	*/
+	async queryWithMultiQuery(input) {
+		const { original, ftsText, mode, anchors, opts } = input;
+		const variants = await this.generateParaphrases(original);
+		const requestedLimit = opts?.limit ?? 10;
+		const fanoutLimit = Math.max(requestedLimit * 2, 10);
+		const lists = [];
+		for (const variant of variants) {
+			const embedding = await this.autoEmbed(variant, "query");
+			const variantResults = await this.queryEngine.query({
+				mode,
+				anchors,
+				text: variant === original ? ftsText : variant,
+				embedding: embedding ?? void 0,
+				opts: {
+					...opts,
+					limit: fanoutLimit
+				},
+				boundDomains: this.options.boundDomains
+			});
+			lists.push({ entries: variantResults });
+		}
+		const k = 60;
+		const scores = /* @__PURE__ */ new Map();
+		for (const list of lists) for (let i = 0; i < list.entries.length; i++) {
+			const entry = list.entries[i];
+			const contribution = 1 / (k + i + 1);
+			const existing = scores.get(entry.entryPath);
+			if (existing) existing.score += contribution;
+			else scores.set(entry.entryPath, {
+				entry,
+				score: contribution
+			});
+		}
+		return [...scores.values()].sort((a, b) => b.score - a.score).slice(0, requestedLimit).map(({ entry, score }) => ({
+			...entry,
+			score
+		}));
+	}
+};
+__decorate([Read("/")], AFSIndex.prototype, "readRoot", null);
+__decorate([List("/")], AFSIndex.prototype, "listRoot", null);
+__decorate([Actions("/")], AFSIndex.prototype, "listActions", null);
+__decorate([Read("/domains")], AFSIndex.prototype, "readDomains", null);
+__decorate([Read("/stats")], AFSIndex.prototype, "readStatsDir", null);
+__decorate([Read("/config")], AFSIndex.prototype, "readConfigDir", null);
+__decorate([List("/domains")], AFSIndex.prototype, "listDomains", null);
+__decorate([List("/stats")], AFSIndex.prototype, "listStatsDir", null);
+__decorate([List("/config")], AFSIndex.prototype, "listConfig", null);
+__decorate([List("/stats/:key")], AFSIndex.prototype, "listStatsKey", null);
+__decorate([List("/config/:key")], AFSIndex.prototype, "listConfigKey", null);
+__decorate([List("/domains/:name")], AFSIndex.prototype, "listDomainName", null);
+__decorate([Meta("/")], AFSIndex.prototype, "readRootMeta", null);
+__decorate([Meta("/domains")], AFSIndex.prototype, "readDomainsMeta", null);
+__decorate([Meta("/stats")], AFSIndex.prototype, "readStatsMeta", null);
+__decorate([Meta("/config")], AFSIndex.prototype, "readConfigMeta", null);
+__decorate([Meta("/stats/:key")], AFSIndex.prototype, "readStatsKeyMeta", null);
+__decorate([Meta("/config/:key")], AFSIndex.prototype, "readConfigKeyMeta", null);
+__decorate([Meta("/domains/:name")], AFSIndex.prototype, "readDomainNameMeta", null);
+__decorate([Read("/.meta/.capabilities")], AFSIndex.prototype, "readCapabilities", null);
+__decorate([Explain("/")], AFSIndex.prototype, "explainRoot", null);
+__decorate([Explain("/:path*")], AFSIndex.prototype, "explainPath", null);
+__decorate([Search("/:path*")], AFSIndex.prototype, "searchHandler", null);
+__decorate([Read("/config/:key")], AFSIndex.prototype, "readConfig", null);
+__decorate([Read("/stats/:key")], AFSIndex.prototype, "readStats", null);
+__decorate([Actions.Exec("/", "index")], AFSIndex.prototype, "execIndex", null);
+__decorate([Actions.Exec("/", "query")], AFSIndex.prototype, "execQuery", null);
+__decorate([Actions.Exec("/", "get")], AFSIndex.prototype, "execGet", null);
+__decorate([Actions.Exec("/", "reindex")], AFSIndex.prototype, "execReindex", null);
+__decorate([Actions.Exec("/", "cleanup")], AFSIndex.prototype, "execCleanup", null);
+__decorate([Actions.Exec("/", "verify")], AFSIndex.prototype, "execVerify", null);
+__decorate([Actions.Exec("/", "register-domain")], AFSIndex.prototype, "execRegisterDomain", null);
+__decorate([Actions.Exec("/", "discover")], AFSIndex.prototype, "execDiscover", null);
+/**
+* Simple glob matching — supports `*` (single segment) and `**` (multi-segment).
+* Also matches bare extensions like `*.md` against any path ending with `.md`.
+*/
+function matchGlob(path, pattern) {
+	const regexStr = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "⧫").replace(/\*/g, "[^/]*").replace(/⧫/g, ".*").replace(/\?/g, "[^/]");
+	return (/* @__PURE__ */ new RegExp(`(^|/)${regexStr}$`)).test(path);
+}
+
+//#endregion
+export { AFSIndex };
+//# sourceMappingURL=index-provider.mjs.map