@aigne/afs-index 1.12.0-beta.5

package/dist/offline-rebuild.d.cts

@@ -0,0 +1,57 @@
+import { IndexBackend } from "./backend/types.cjs";
+import { TimeKeyGranularity } from "./types.cjs";
+import { AFSRoot, BlockletIndexDomain } from "@aigne/afs";
+
+//#region src/offline-rebuild.d.ts
+interface OfflineRebuildResult {
+  /** Relational/FTS/anchor rows cleared before the rebuild (vectors preserved). */
+  cleared: number;
+  /** Live paths (re)indexed. */
+  indexed: number;
+  /** Live paths that failed to index (kept for the caller to log). */
+  failed: number;
+  /** Live paths no declared domain claims (skipped). */
+  skipped: number;
+}
+interface OfflineRebuildOptions {
+  /** Scope-stamped index backend (writes relational/FTS/anchor for one scope). */
+  backend: IndexBackend;
+  /** Content-reading AFS for the scope's fragment (`read`/`stat` of live files). */
+  spaceAfs: AFSRoot;
+  /** The blocklet's declared index domains. */
+  domains: BlockletIndexDomain[];
+  /**
+   * Space-relative live entry paths to rebuild (e.g. `items/x.json`) — enumerated
+   * by the caller from live `ds_entries` under `blocklets/{instanceDid}/user/`.
+   */
+  livePaths: string[];
+  /**
+   * The blocklet's `index.timeKeyGranularity` (blocklet.yaml top-level, NOT part
+   * of `domains[]`) — caps which time buckets a `time` anchor expands into
+   * (issue #1215; e.g. `[year, month, day]` instead of the 8-bucket default).
+   *
+   * CRITICAL for a config-change rebuild: the `time` key expansion happens in the
+   * BACKEND's `keyRegistry` (`generateKeys`), which a plain `new D1IndexBackend`
+   * default-constructs to the FULL 8-bucket generator. The live/cron path applies
+   * the policy by having `AFSIndex` register a granularity-limited `time`
+   * generator and `setKeyRegistry` it onto the backend (index-provider.ts) — the
+   * offline seam must do the SAME, or a rebuild silently re-writes the old
+   * high-cardinality time keys. When set, this wires that generator before the
+   * clear+rebuild. Omit to keep the backend's existing registry unchanged.
+   */
+  timeKeyGranularity?: TimeKeyGranularity[];
+  /**
+   * Optional progress reporter for long (esp. REMOTE) rebuilds. `phase:"clear"`
+   * fires once with the count about to be purged; `phase:"rebuild"` fires
+   * periodically with `done`/`total` reindexed paths.
+   */
+  onProgress?: (info: {
+    phase: "clear" | "rebuild";
+    done: number;
+    total: number;
+  }) => void;
+}
+declare function offlineRebuildScope(opts: OfflineRebuildOptions): Promise<OfflineRebuildResult>;
+//#endregion
+export { OfflineRebuildOptions, OfflineRebuildResult, offlineRebuildScope };
+//# sourceMappingURL=offline-rebuild.d.cts.map

package/dist/offline-rebuild.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-rebuild.d.cts","names":[],"sources":["../src/offline-rebuild.ts"],"mappings":";;;;;UAgCiB,oBAAA;EAiBf;EAfA,OAAA;EAoBA;EAlBA,OAAA;EAiCqB;EA/BrB,MAAA;EAqCsB;EAnCtB,OAAA;AAAA;AAAA,UAGe,qBAAA;EAgCgE;EA9B/E,OAAA,EAAS,YAAA;EAiCW;EA/BpB,QAAA,EAAU,OAAA;;EAEV,OAAA,EAAS,mBAAA;EA+BA;;;;EA1BT,SAAA;EAyBA;;;;;;;;;;;;;;EAVA,kBAAA,GAAqB,kBAAA;;;;;;EAMrB,UAAA,IAAc,IAAA;IAAQ,KAAA;IAA4B,IAAA;IAAc,KAAA;EAAA;AAAA;AAAA,iBAG5C,mBAAA,CACpB,IAAA,EAAM,qBAAA,GACL,OAAA,CAAQ,oBAAA"}

package/dist/offline-rebuild.d.mts

@@ -0,0 +1,57 @@
+import { IndexBackend } from "./backend/types.mjs";
+import { TimeKeyGranularity } from "./types.mjs";
+import { AFSRoot, BlockletIndexDomain } from "@aigne/afs";
+
+//#region src/offline-rebuild.d.ts
+interface OfflineRebuildResult {
+  /** Relational/FTS/anchor rows cleared before the rebuild (vectors preserved). */
+  cleared: number;
+  /** Live paths (re)indexed. */
+  indexed: number;
+  /** Live paths that failed to index (kept for the caller to log). */
+  failed: number;
+  /** Live paths no declared domain claims (skipped). */
+  skipped: number;
+}
+interface OfflineRebuildOptions {
+  /** Scope-stamped index backend (writes relational/FTS/anchor for one scope). */
+  backend: IndexBackend;
+  /** Content-reading AFS for the scope's fragment (`read`/`stat` of live files). */
+  spaceAfs: AFSRoot;
+  /** The blocklet's declared index domains. */
+  domains: BlockletIndexDomain[];
+  /**
+   * Space-relative live entry paths to rebuild (e.g. `items/x.json`) — enumerated
+   * by the caller from live `ds_entries` under `blocklets/{instanceDid}/user/`.
+   */
+  livePaths: string[];
+  /**
+   * The blocklet's `index.timeKeyGranularity` (blocklet.yaml top-level, NOT part
+   * of `domains[]`) — caps which time buckets a `time` anchor expands into
+   * (issue #1215; e.g. `[year, month, day]` instead of the 8-bucket default).
+   *
+   * CRITICAL for a config-change rebuild: the `time` key expansion happens in the
+   * BACKEND's `keyRegistry` (`generateKeys`), which a plain `new D1IndexBackend`
+   * default-constructs to the FULL 8-bucket generator. The live/cron path applies
+   * the policy by having `AFSIndex` register a granularity-limited `time`
+   * generator and `setKeyRegistry` it onto the backend (index-provider.ts) — the
+   * offline seam must do the SAME, or a rebuild silently re-writes the old
+   * high-cardinality time keys. When set, this wires that generator before the
+   * clear+rebuild. Omit to keep the backend's existing registry unchanged.
+   */
+  timeKeyGranularity?: TimeKeyGranularity[];
+  /**
+   * Optional progress reporter for long (esp. REMOTE) rebuilds. `phase:"clear"`
+   * fires once with the count about to be purged; `phase:"rebuild"` fires
+   * periodically with `done`/`total` reindexed paths.
+   */
+  onProgress?: (info: {
+    phase: "clear" | "rebuild";
+    done: number;
+    total: number;
+  }) => void;
+}
+declare function offlineRebuildScope(opts: OfflineRebuildOptions): Promise<OfflineRebuildResult>;
+//#endregion
+export { OfflineRebuildOptions, OfflineRebuildResult, offlineRebuildScope };
+//# sourceMappingURL=offline-rebuild.d.mts.map

package/dist/offline-rebuild.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-rebuild.d.mts","names":[],"sources":["../src/offline-rebuild.ts"],"mappings":";;;;;UAgCiB,oBAAA;EAiBf;EAfA,OAAA;EAoBA;EAlBA,OAAA;EAiCqB;EA/BrB,MAAA;EAqCsB;EAnCtB,OAAA;AAAA;AAAA,UAGe,qBAAA;EAgCgE;EA9B/E,OAAA,EAAS,YAAA;EAiCW;EA/BpB,QAAA,EAAU,OAAA;;EAEV,OAAA,EAAS,mBAAA;EA+BA;;;;EA1BT,SAAA;EAyBA;;;;;;;;;;;;;;EAVA,kBAAA,GAAqB,kBAAA;;;;;;EAMrB,UAAA,IAAc,IAAA;IAAQ,KAAA;IAA4B,IAAA;IAAc,KAAA;EAAA;AAAA;AAAA,iBAG5C,mBAAA,CACpB,IAAA,EAAM,qBAAA,GACL,OAAA,CAAQ,oBAAA"}

package/dist/offline-rebuild.mjs

@@ -0,0 +1,49 @@
+import { generateTimeKeys } from "./keys/time.mjs";
+import { KeyGeneratorRegistry } from "./keys/registry.mjs";
+import { IndexFollower } from "./follower.mjs";
+
+//#region src/offline-rebuild.ts
+async function offlineRebuildScope(opts) {
+	const { backend, spaceAfs, domains, livePaths, timeKeyGranularity } = opts;
+	if (timeKeyGranularity?.length && backend.setKeyRegistry) {
+		const registry = new KeyGeneratorRegistry();
+		const include = new Set(timeKeyGranularity);
+		registry.register("time", (anchor) => generateTimeKeys(anchor, include));
+		backend.setKeyRegistry(registry);
+	}
+	let cleared = 0;
+	const boundDomains = domains.map((d) => d.name);
+	const existing = backend.listEntries ? await backend.listEntries({ boundDomains }) : [];
+	if (existing.length > 0 && backend.purgeEntries) {
+		opts.onProgress?.({
+			phase: "clear",
+			done: 0,
+			total: existing.length
+		});
+		cleared = await backend.purgeEntries(existing.map((e) => e.entryPath), { skipVector: true });
+		opts.onProgress?.({
+			phase: "clear",
+			done: cleared,
+			total: existing.length
+		});
+	}
+	const { indexed, failed, skipped } = await new IndexFollower({
+		spaceAfs,
+		backend,
+		domains
+	}).reindexPaths(livePaths, (done, total) => opts.onProgress?.({
+		phase: "rebuild",
+		done,
+		total
+	}));
+	return {
+		cleared,
+		indexed,
+		failed,
+		skipped
+	};
+}
+
+//#endregion
+export { offlineRebuildScope };
+//# sourceMappingURL=offline-rebuild.mjs.map

package/dist/offline-rebuild.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-rebuild.mjs","names":[],"sources":["../src/offline-rebuild.ts"],"sourcesContent":["/**\n * Offline reset-and-rebuild for ONE scope (index-follower-dirty-path §10.1).\n *\n * The relational / FTS / anchor layers are pure derived views of `ds_entries`\n * and need no embedding, so they can be cleared and rebuilt from CURRENT live\n * state cheaply. This is BOTH the first-deploy backfill and the ONLY recovery\n * path (the big-bang cutover keeps no changelog-replay fallback — design §10):\n *\n *   1. CLEAR the relational/FTS/anchor rows for the scope with `skipVector:true`\n *      — the D1-native `idx_embedding_vector` AND any injected Upstash vectors\n *      are left UNTOUCHED (constraint B: never re-embed).\n *   2. REBUILD from the live entries via the follower's `reindexPaths` with NO\n *      embedder wired — byte-identical relational/FTS/anchor output, zero vector\n *      writes.\n *\n * Gap-proof: the rebuild reads LIVE state, never the changelog, so it does NOT\n * depend on any cursor water line `L`/`M` (design §10 cutover gap) — a live\n * entry that was never indexed is rebuilt regardless. Idempotent + re-runnable:\n * clearing then rebuilding from the same live set converges to the same rows.\n *\n * This helper is the single tested seam both the CF and Node offline ops scripts\n * call; the scripts only supply a scope-stamped `backend`, a content-reading\n * `spaceAfs`, the `domains`, and the live entry paths to rebuild.\n */\n\nimport type { AFSRoot, BlockletIndexDomain } from \"@aigne/afs\";\nimport type { IndexBackend } from \"./backend/types.js\";\nimport { IndexFollower } from \"./follower.js\";\nimport { KeyGeneratorRegistry } from \"./keys/registry.js\";\nimport { generateTimeKeys } from \"./keys/time.js\";\nimport type { TimeKeyGranularity } from \"./types.js\";\n\nexport interface OfflineRebuildResult {\n  /** Relational/FTS/anchor rows cleared before the rebuild (vectors preserved). */\n  cleared: number;\n  /** Live paths (re)indexed. */\n  indexed: number;\n  /** Live paths that failed to index (kept for the caller to log). */\n  failed: number;\n  /** Live paths no declared domain claims (skipped). */\n  skipped: number;\n}\n\nexport interface OfflineRebuildOptions {\n  /** Scope-stamped index backend (writes relational/FTS/anchor for one scope). */\n  backend: IndexBackend;\n  /** Content-reading AFS for the scope's fragment (`read`/`stat` of live files). */\n  spaceAfs: AFSRoot;\n  /** The blocklet's declared index domains. */\n  domains: BlockletIndexDomain[];\n  /**\n   * Space-relative live entry paths to rebuild (e.g. `items/x.json`) — enumerated\n   * by the caller from live `ds_entries` under `blocklets/{instanceDid}/user/`.\n   */\n  livePaths: string[];\n  /**\n   * The blocklet's `index.timeKeyGranularity` (blocklet.yaml top-level, NOT part\n   * of `domains[]`) — caps which time buckets a `time` anchor expands into\n   * (issue #1215; e.g. `[year, month, day]` instead of the 8-bucket default).\n   *\n   * CRITICAL for a config-change rebuild: the `time` key expansion happens in the\n   * BACKEND's `keyRegistry` (`generateKeys`), which a plain `new D1IndexBackend`\n   * default-constructs to the FULL 8-bucket generator. The live/cron path applies\n   * the policy by having `AFSIndex` register a granularity-limited `time`\n   * generator and `setKeyRegistry` it onto the backend (index-provider.ts) — the\n   * offline seam must do the SAME, or a rebuild silently re-writes the old\n   * high-cardinality time keys. When set, this wires that generator before the\n   * clear+rebuild. Omit to keep the backend's existing registry unchanged.\n   */\n  timeKeyGranularity?: TimeKeyGranularity[];\n  /**\n   * Optional progress reporter for long (esp. REMOTE) rebuilds. `phase:\"clear\"`\n   * fires once with the count about to be purged; `phase:\"rebuild\"` fires\n   * periodically with `done`/`total` reindexed paths.\n   */\n  onProgress?: (info: { phase: \"clear\" | \"rebuild\"; done: number; total: number }) => void;\n}\n\nexport async function offlineRebuildScope(\n  opts: OfflineRebuildOptions,\n): Promise<OfflineRebuildResult> {\n  const { backend, spaceAfs, domains, livePaths, timeKeyGranularity } = opts;\n\n  // 0. Apply the domain's time-key granularity policy (issue #1215) BEFORE the\n  //    rebuild writes any anchors. The `time` anchor → `idx_anchor_key` expansion\n  //    lives in the backend's keyRegistry; a plain backend defaults to the full\n  //    8-bucket generator, so without this a rebuild re-writes the OLD\n  //    high-cardinality keys. A fresh registry keeps the built-in\n  //    exact/location/person/topic defaults and overrides ONLY `time` with the\n  //    granularity-limited generator.\n  //\n  //    NOTE: this offline path does NOT register the declared facet types\n  //    (tag/site/status/…) with `createNormalizedValueGenerator` the way the\n  //    live follower does (index-provider.ts `registerDomains`). That is SAFE\n  //    only because `generateExactKeys` — the registry's fallback for those\n  //    unregistered types — now emits the SAME canonical bare, lowercased\n  //    `<type>:<value>` key the normalized generator would (see keys/exact.ts).\n  //    Before that fix the fallback emitted `tag:{\"value\":\"…\"}` JSON, so an\n  //    offline rebuild silently rewrote every facet key into a form the query\n  //    side never matched — the whole reason facet search broke on a rebuilt\n  //    index. Do NOT \"restore\" a JSON exact fallback without re-registering the\n  //    facet types here.\n  if (timeKeyGranularity?.length && backend.setKeyRegistry) {\n    const registry = new KeyGeneratorRegistry();\n    const include = new Set(timeKeyGranularity);\n    registry.register(\"time\", (anchor) => generateTimeKeys(anchor, include));\n    backend.setKeyRegistry(registry);\n  }\n\n  // 1. Clear relational/FTS/anchor for THIS blocklet's domains only, PRESERVING\n  //    all vectors. CRITICAL: a scope is SHARED across a user's blocklets (CF:\n  //    scope = HMAC(userDid); Node: the shared user-index.db), all stamped with\n  //    the same `scope` but different `domain` values. Clearing by scope alone\n  //    (`listEntries({})`) would WIPE sibling blocklets' index rows — a\n  //    cross-blocklet data loss (tasks.md §Security/§Data-leak). Bound the clear\n  //    to this blocklet's own domains, exactly as the query/reindex paths do\n  //    (AFSIndexOptions.boundDomains). The rebuild below is already domain-bound\n  //    (reindexPaths only indexes paths matching `domains`), so the two stay\n  //    symmetric and confined to this blocklet.\n  let cleared = 0;\n  const boundDomains = domains.map((d) => d.name);\n  const existing = backend.listEntries ? await backend.listEntries({ boundDomains }) : [];\n  if (existing.length > 0 && backend.purgeEntries) {\n    opts.onProgress?.({ phase: \"clear\", done: 0, total: existing.length });\n    cleared = await backend.purgeEntries(\n      existing.map((e) => e.entryPath),\n      { skipVector: true },\n    );\n    opts.onProgress?.({ phase: \"clear\", done: cleared, total: existing.length });\n  }\n\n  // 2. Rebuild from live entries with NO embedder (vectors untouched) and NO\n  //    dirty queue (reindexPaths is changelog-independent — it re-reads live\n  //    content per path and writes the three derived layers).\n  const follower = new IndexFollower({ spaceAfs, backend, domains });\n  const { indexed, failed, skipped } = await follower.reindexPaths(livePaths, (done, total) =>\n    opts.onProgress?.({ phase: \"rebuild\", done, total }),\n  );\n  return { cleared, indexed, failed, skipped };\n}\n"],"mappings":";;;;;AA8EA,eAAsB,oBACpB,MAC+B;CAC/B,MAAM,EAAE,SAAS,UAAU,SAAS,WAAW,uBAAuB;AAqBtE,KAAI,oBAAoB,UAAU,QAAQ,gBAAgB;EACxD,MAAM,WAAW,IAAI,sBAAsB;EAC3C,MAAM,UAAU,IAAI,IAAI,mBAAmB;AAC3C,WAAS,SAAS,SAAS,WAAW,iBAAiB,QAAQ,QAAQ,CAAC;AACxE,UAAQ,eAAe,SAAS;;CAalC,IAAI,UAAU;CACd,MAAM,eAAe,QAAQ,KAAK,MAAM,EAAE,KAAK;CAC/C,MAAM,WAAW,QAAQ,cAAc,MAAM,QAAQ,YAAY,EAAE,cAAc,CAAC,GAAG,EAAE;AACvF,KAAI,SAAS,SAAS,KAAK,QAAQ,cAAc;AAC/C,OAAK,aAAa;GAAE,OAAO;GAAS,MAAM;GAAG,OAAO,SAAS;GAAQ,CAAC;AACtE,YAAU,MAAM,QAAQ,aACtB,SAAS,KAAK,MAAM,EAAE,UAAU,EAChC,EAAE,YAAY,MAAM,CACrB;AACD,OAAK,aAAa;GAAE,OAAO;GAAS,MAAM;GAAS,OAAO,SAAS;GAAQ,CAAC;;CAO9E,MAAM,EAAE,SAAS,QAAQ,YAAY,MADpB,IAAI,cAAc;EAAE;EAAU;EAAS;EAAS,CAAC,CACd,aAAa,YAAY,MAAM,UACjF,KAAK,aAAa;EAAE,OAAO;EAAW;EAAM;EAAO,CAAC,CACrD;AACD,QAAO;EAAE;EAAS;EAAS;EAAQ;EAAS"}

package/dist/query/engine.cjs

@@ -0,0 +1,433 @@
+const require_fts = require('../text/fts.cjs');
+const require_limits = require('./limits.cjs');
+
+//#region src/query/engine.ts
+const QUERY_CURSOR_VERSION = 1;
+const MAX_QUERY_WINDOW = 2e3;
+function stableJson(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	const obj = value;
+	return `{${Object.keys(obj).sort().filter((k) => obj[k] !== void 0).map((k) => `${JSON.stringify(k)}:${stableJson(obj[k])}`).join(",")}}`;
+}
+function hashString(input) {
+	let h = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		h ^= input.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return (h >>> 0).toString(36);
+}
+function encodeCursor(payload) {
+	return `q1.${encodeURIComponent(JSON.stringify(payload))}`;
+}
+function decodeCursor(cursor) {
+	if (!cursor.startsWith("q1.")) return null;
+	try {
+		const parsed = JSON.parse(decodeURIComponent(cursor.slice(3)));
+		if (parsed.v !== QUERY_CURSOR_VERSION || typeof parsed.offset !== "number" || !Number.isFinite(parsed.offset) || parsed.offset < 0 || Math.floor(parsed.offset) !== parsed.offset || typeof parsed.qh !== "string" || !parsed.qh) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/**
+* Human-readable label for an anchor filter (issue #1069 debug info) — e.g.
+* `person:[name:alice] & topic:[cooking]`. Static per query (queryAnchors ANDs
+* across groups, ORs within a group's values — see `anchor_intersection`), so
+* every entry the filter returns satisfies the same label; safe to reuse
+* across all of a list's entries rather than recomputing per-entry.
+*/
+function describeAnchorFilter(keys) {
+	return keys.map((k) => `${k.type}:[${k.values.join(",")}]`).join(" & ");
+}
+/** Human-readable label for an FTS query (issue #1069 debug info). */
+function describeFtsQuery(text) {
+	return `"${text}"`;
+}
+function formatContribution(c) {
+	return `${c.source}${c.label ? ` ${c.label}` : ""} rank=${c.rank} score=${c.rawScore.toFixed(3)}`;
+}
+/**
+* Reciprocal Rank Fusion — merge multiple ranked lists into one.
+*
+* Each entry's score = Σ(1 / (k + rank + 1)) across all lists it appears in.
+* Rank-based fusion naturally handles different score scales.
+*
+* @param lists - Ranked lists from different retrieval sources (anchor, FTS, embedding)
+* @param k - Smoothing constant (default 60, standard in literature)
+* @param explain - When true (issue #1069), decorate each result with a
+*   composite `explanation` listing every contributing source's rank/score
+*   and the final RRF math. Default false: identical output to before this
+*   flag existed (byte-for-byte — no `explanation` key at all).
+*/
+function reciprocalRankFusion(lists, k = 60, explain = false) {
+	const scores = /* @__PURE__ */ new Map();
+	for (const list of lists) for (let rank = 0; rank < list.entries.length; rank++) {
+		const entry = list.entries[rank];
+		const contribution = 1 / (k + rank + 1);
+		const existing = scores.get(entry.entryPath);
+		const rrfContribution = {
+			source: list.source,
+			rank,
+			rawScore: entry.score,
+			label: list.label
+		};
+		if (existing) {
+			existing.rrfScore += contribution;
+			existing.contributions.push(rrfContribution);
+			if (rank < existing.bestRank) {
+				existing.bestRank = rank;
+				existing.bestSource = list.source;
+			}
+		} else scores.set(entry.entryPath, {
+			entryPath: entry.entryPath,
+			rrfScore: contribution,
+			bestSource: list.source,
+			bestRank: rank,
+			contributions: [rrfContribution]
+		});
+	}
+	return Array.from(scores.values()).sort((a, b) => b.rrfScore - a.rrfScore || a.entryPath.localeCompare(b.entryPath)).map(({ entryPath, rrfScore, bestSource, contributions }) => {
+		const result = {
+			entryPath,
+			matchType: bestSource,
+			score: rrfScore
+		};
+		if (explain) result.explanation = `${contributions.map(formatContribution).join("; ")}; RRF=${rrfScore.toFixed(4)}`;
+		return result;
+	});
+}
+/**
+* Candidate pool size when `anchorFilter` is on (Epic #932 S2/S3 facet search).
+* The anchor∩text intersection needs more than the final `limit` of text
+* candidates so a facet-matching but lower-text-ranked entry isn't dropped
+* before the filter. Sized for personal (aside-scale) data.
+*/
+const ANCHOR_FILTER_CANDIDATES = 500;
+var QueryEngine = class {
+	constructor(backend) {
+		this.backend = backend;
+	}
+	/**
+	* Resolve the `boundDomains` fallback filter for a query: `undefined` when
+	* the caller passed an explicit `opts.scope` (their scope wins outright,
+	* never overridden — see `QueryInput.boundDomains`), otherwise the bound
+	* set (or `undefined` if none/empty, a strict no-op preserving today's
+	* "no domain → query everything" behavior for the global `/modules/index`
+	* mount and any other caller that never sets `boundDomains`).
+	*/
+	domainsFilter(input) {
+		if (input.opts?.scope) return void 0;
+		return input.boundDomains && input.boundDomains.length > 0 ? input.boundDomains : void 0;
+	}
+	/**
+	* Applies time-decay to a score based on entry's updatedAt timestamp.
+	* Formula: score * e^(-lambda * ageDays)
+	*/
+	async applyDecay(results, lambda) {
+		const now = Date.now();
+		const decayed = [];
+		for (const r of results) {
+			const entry = await this.backend.getEntry(r.entryPath);
+			if (!entry) {
+				decayed.push(r);
+				continue;
+			}
+			const ageDays = (now - new Date(entry.updatedAt).getTime()) / 864e5;
+			decayed.push({
+				...r,
+				score: r.score * Math.exp(-lambda * ageDays)
+			});
+		}
+		decayed.sort((a, b) => b.score - a.score);
+		return decayed;
+	}
+	queryHash(input, limit) {
+		const opts = input.opts ?? {};
+		return hashString(stableJson({
+			mode: input.mode,
+			ftsMode: input.ftsMode,
+			anchors: input.anchors,
+			text: input.text,
+			embedding: input.embedding,
+			boundDomains: input.boundDomains,
+			opts: {
+				anchorFilter: opts.anchorFilter,
+				decay: opts.decay,
+				embeddingFloor: opts.embeddingFloor,
+				limit,
+				metaFilter: opts.metaFilter,
+				minConfidence: opts.minConfidence,
+				minResults: opts.minResults,
+				pathPrefix: opts.pathPrefix,
+				scope: opts.scope
+			}
+		}));
+	}
+	async queryPage(input) {
+		const { mode } = input;
+		const limit = require_limits.normalizeQueryLimit(input.opts?.limit);
+		if (limit <= 0) return { results: [] };
+		const qh = this.queryHash(input, limit);
+		const cursor = input.opts?.cursor;
+		const decoded = cursor ? decodeCursor(cursor) : null;
+		if (cursor && (!decoded || decoded.qh !== qh)) throw new Error("Invalid or stale query cursor");
+		const offset = decoded?.offset ?? 0;
+		const requestedWindow = offset + limit + 1;
+		const windowLimit = Math.min(requestedWindow, MAX_QUERY_WINDOW);
+		const truncated = requestedWindow > MAX_QUERY_WINDOW;
+		let results;
+		switch (mode) {
+			case "anchor":
+				results = await this.queryAnchor(input, windowLimit);
+				break;
+			case "fts":
+				results = await this.queryFTS(input, windowLimit);
+				break;
+			case "combined":
+				results = await this.queryCombined(input, windowLimit);
+				break;
+			case "semantic":
+				results = await this.querySemantic(input, windowLimit);
+				break;
+		}
+		if (input.opts?.decay && results.length > 0) results = await this.applyDecay(results, input.opts.decay.lambda);
+		if (input.opts?.explain && input.anchors?.length && results.length > 0) results = await this.attachAnchorDetails(results, input.anchors);
+		const page = results.slice(offset, offset + limit);
+		const hasMore = !truncated && results.length > offset + limit;
+		const meta = hasMore || truncated ? {
+			...hasMore ? { cursor: encodeCursor({
+				v: QUERY_CURSOR_VERSION,
+				offset: offset + limit,
+				qh
+			}) } : {},
+			hasMore,
+			...truncated ? { truncated: true } : {}
+		} : void 0;
+		return {
+			results: page,
+			...meta ? { meta } : {}
+		};
+	}
+	async query(input) {
+		return (await this.queryPage(input)).results;
+	}
+	/**
+	* For each result whose `matchType === "anchor"`, fetch the entry's stored
+	* anchors and filter to the types the query actually asked for — the
+	* concrete "why was this record matched" evidence issue #1069 wants.
+	* `queryAnchors`'s `anchor_intersection` ANDs across groups (see
+	* `sqlite-backend.ts`), so any entry in the anchor list satisfied every
+	* requested type; we don't re-verify individual values here (that would
+	* require re-deriving generated keys, which live in `AFSIndex`'s
+	* `KeyGeneratorRegistry`, not the engine) — we report the entry's own
+	* anchors of the requested type(s) as the matched evidence.
+	*/
+	async attachAnchorDetails(results, anchors) {
+		const types = new Set(anchors.map((k) => k.type));
+		const out = [];
+		for (const r of results) {
+			if (r.matchType !== "anchor") {
+				out.push(r);
+				continue;
+			}
+			const matched = (await this.backend.getAnchorData(r.entryPath)).filter((a) => types.has(a.anchorType));
+			out.push({
+				...r,
+				anchors: matched
+			});
+		}
+		return out;
+	}
+	async queryAnchor(input, limit) {
+		if (!input.anchors || input.anchors.length === 0) return [];
+		const results = await this.backend.queryAnchors({
+			keys: input.anchors,
+			scope: input.opts?.scope,
+			pathPrefix: input.opts?.pathPrefix,
+			domains: this.domainsFilter(input),
+			minConfidence: input.opts?.minConfidence,
+			limit,
+			metaFilter: input.opts?.metaFilter
+		});
+		const explain = input.opts?.explain === true;
+		const label = explain ? describeAnchorFilter(input.anchors) : void 0;
+		return results.map((r) => ({
+			entryPath: r.entryPath,
+			matchType: "anchor",
+			score: r.score,
+			...explain ? { explanation: `anchor ${label} score=${r.score.toFixed(3)}` } : {}
+		}));
+	}
+	async queryFTS(input, limit) {
+		if (!input.text) return [];
+		const transformed = require_fts.transformFtsQuery(input.text, input.ftsMode);
+		if (!transformed) return [];
+		const scope = input.opts?.scope;
+		const domain = scope ? scope.replace(/^\/+/, "") : void 0;
+		const domains = this.domainsFilter(input);
+		const pathPrefix = input.opts?.pathPrefix;
+		const results = await this.backend.queryFTS(transformed, limit, input.opts?.metaFilter, {
+			...domain ? { domain } : {},
+			...scope ? { scope } : {},
+			...domains ? { domains } : {},
+			...pathPrefix ? { pathPrefix } : {}
+		});
+		const explain = input.opts?.explain === true;
+		const label = explain ? describeFtsQuery(transformed) : void 0;
+		return results.map((r) => ({
+			entryPath: r.entryPath,
+			matchType: "fts",
+			score: r.rank,
+			...explain ? { explanation: `fts ${label} rank=${r.rank.toFixed(3)}` } : {}
+		}));
+	}
+	/** Collect anchor + FTS ranked lists from backend. */
+	async collectLists(input, limit) {
+		const lists = [];
+		if (input.anchors?.length) {
+			const results = await this.backend.queryAnchors({
+				keys: input.anchors,
+				scope: input.opts?.scope,
+				pathPrefix: input.opts?.pathPrefix,
+				domains: this.domainsFilter(input),
+				minConfidence: input.opts?.minConfidence,
+				limit,
+				metaFilter: input.opts?.metaFilter
+			});
+			if (results.length > 0) {
+				const explain = input.opts?.explain === true;
+				lists.push({
+					source: "anchor",
+					entries: results.map((r) => ({
+						entryPath: r.entryPath,
+						score: r.score
+					})),
+					...explain ? { label: describeAnchorFilter(input.anchors) } : {}
+				});
+			}
+		}
+		if (input.text) {
+			const transformedText = require_fts.transformFtsQuery(input.text, input.ftsMode);
+			if (transformedText) {
+				const scope = input.opts?.scope;
+				const domain = scope ? scope.replace(/^\/+/, "") : void 0;
+				const domains = this.domainsFilter(input);
+				const pathPrefix = input.opts?.pathPrefix;
+				const results = await this.backend.queryFTS(transformedText, limit, input.opts?.metaFilter, {
+					...domain ? { domain } : {},
+					...scope ? { scope } : {},
+					...domains ? { domains } : {},
+					...pathPrefix ? { pathPrefix } : {}
+				});
+				if (results.length > 0) {
+					const explain = input.opts?.explain === true;
+					lists.push({
+						source: "fts",
+						entries: results.map((r) => ({
+							entryPath: r.entryPath,
+							score: r.rank
+						})),
+						...explain ? { label: describeFtsQuery(transformedText) } : {}
+					});
+				}
+			}
+		}
+		return lists;
+	}
+	async queryCombined(input, limit) {
+		const anchorFilter = input.opts?.anchorFilter ?? false;
+		const lists = await this.collectLists(input, this.candidateLimit(limit, anchorFilter));
+		return this.fuseOrFilter(lists, limit, anchorFilter, input.opts?.explain === true);
+	}
+	async querySemantic(input, limit) {
+		const anchorFilter = input.opts?.anchorFilter ?? false;
+		const explain = input.opts?.explain === true;
+		const candidates = this.candidateLimit(limit, anchorFilter);
+		const lists = await this.collectLists(input, candidates);
+		if (input.embedding && this.backend.queryVector) {
+			const scope = input.opts?.scope;
+			const domain = scope ? scope.replace(/^\/+/, "") : void 0;
+			const domains = this.domainsFilter(input);
+			const pathPrefix = input.opts?.pathPrefix;
+			const vectorResults = await this.backend.queryVector(input.embedding, candidates, {
+				...domain ? { domain } : {},
+				...scope ? { scope } : {},
+				...domains ? { domains } : {},
+				...pathPrefix ? { pathPrefix } : {}
+			});
+			if (vectorResults.length > 0) {
+				let entries = vectorResults.map((r) => ({
+					entryPath: r.entryPath,
+					score: r.similarity
+				}));
+				const floor = input.opts?.embeddingFloor;
+				if (floor != null) {
+					const explicit = /* @__PURE__ */ new Set();
+					for (const l of lists) for (const e of l.entries) explicit.add(e.entryPath);
+					entries = entries.filter((e) => explicit.has(e.entryPath) || e.score >= floor);
+				}
+				if (entries.length > 0) lists.push({
+					source: "embedding",
+					entries,
+					...explain ? { label: "cosine" } : {}
+				});
+			}
+		}
+		return this.fuseOrFilter(lists, limit, anchorFilter, explain);
+	}
+	/**
+	* Over-fetch candidates when anchor-filtering so the anchor∩text intersection
+	* has enough to work with — an anchor-matching, text-relevant entry ranked
+	* beyond `limit` would otherwise be dropped before the filter runs. (For
+	* aside-scale personal data this window comfortably covers a tag/collection's
+	* items; a truly-huge facet set could still clip the long tail — a
+	* backend-level `WHERE entry IN (facet-set)` is the follow-up for that.)
+	*/
+	candidateLimit(limit, anchorFilter) {
+		return anchorFilter ? Math.max(limit, ANCHOR_FILTER_CANDIDATES) : limit;
+	}
+	/**
+	* Combine ranked lists into the final result. Default = RRF fusion (union of
+	* every source). When `anchorFilter` is on AND an anchor list is present, the
+	* anchors are a HARD FILTER instead (Epic #932 S2/S3 facet search): with text
+	* → the text ranking intersected with the anchor-matching set; facet-only (no
+	* text) → the anchor set itself. No anchor list (no anchors / none matched) →
+	* plain text-only, so `anchorFilter` never turns a valid text search empty.
+	*/
+	fuseOrFilter(lists, limit, anchorFilter, explain = false) {
+		if (lists.length === 0) return [];
+		const flatten = (l) => l.entries.map((e, rank) => ({
+			entryPath: e.entryPath,
+			matchType: l.source,
+			score: e.score,
+			...explain ? { explanation: formatContribution({
+				source: l.source,
+				rank,
+				rawScore: e.score,
+				label: l.label
+			}) } : {}
+		}));
+		if (anchorFilter) {
+			const anchorList = lists.find((l) => l.source === "anchor");
+			const textLists = lists.filter((l) => l.source !== "anchor");
+			if (anchorList) {
+				const allowed = new Set(anchorList.entries.map((e) => e.entryPath));
+				if (textLists.length === 0) return flatten(anchorList).slice(0, limit);
+				const filtered = (textLists.length === 1 ? flatten(textLists[0]) : reciprocalRankFusion(textLists, 60, explain)).filter((r) => allowed.has(r.entryPath)).slice(0, limit);
+				if (explain && anchorList.label) return filtered.map((r) => ({
+					...r,
+					explanation: `${r.explanation ?? ""}; hard-filtered by anchor ${anchorList.label}`.replace(/^; /, "")
+				}));
+				return filtered;
+			}
+		}
+		if (lists.length === 1) return flatten(lists[0]).slice(0, limit);
+		return reciprocalRankFusion(lists, 60, explain).slice(0, limit);
+	}
+};
+
+//#endregion
+exports.QueryEngine = QueryEngine;
+exports.reciprocalRankFusion = reciprocalRankFusion;

package/dist/query/engine.d.cts

@@ -0,0 +1,34 @@
+import { MatchType, QueryResult } from "../types.cjs";
+
+//#region src/query/engine.d.ts
+/** A ranked list from a single retrieval source, pre-sorted by relevance. */
+interface RankedList {
+  source: MatchType;
+  entries: {
+    entryPath: string;
+    score: number;
+  }[];
+  /**
+   * Human-readable descriptor of what this list represents (e.g. the anchor
+   * filter or the FTS query text) — only built when `explain` is requested
+   * (issue #1069). Used to compose `QueryResult.explanation`.
+   */
+  label?: string;
+}
+/**
+ * Reciprocal Rank Fusion — merge multiple ranked lists into one.
+ *
+ * Each entry's score = Σ(1 / (k + rank + 1)) across all lists it appears in.
+ * Rank-based fusion naturally handles different score scales.
+ *
+ * @param lists - Ranked lists from different retrieval sources (anchor, FTS, embedding)
+ * @param k - Smoothing constant (default 60, standard in literature)
+ * @param explain - When true (issue #1069), decorate each result with a
+ *   composite `explanation` listing every contributing source's rank/score
+ *   and the final RRF math. Default false: identical output to before this
+ *   flag existed (byte-for-byte — no `explanation` key at all).
+ */
+declare function reciprocalRankFusion(lists: RankedList[], k?: number, explain?: boolean): QueryResult[];
+//#endregion
+export { reciprocalRankFusion };
+//# sourceMappingURL=engine.d.cts.map

package/dist/query/engine.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.cts","names":[],"sources":["../../src/query/engine.ts"],"mappings":";;;;UAoHU,UAAA;EACR,MAAA,EAAQ,SAAA;EACR,OAAA;IAAW,SAAA;IAAmB,KAAA;EAAA;;;;;;EAM9B,KAAA;AAAA;;;;;;;;;;;;;;iBA4Bc,oBAAA,CAAqB,KAAA,EAAO,UAAA,IAAc,CAAA,WAAQ,OAAA,aAAkB,WAAA"}