@noy-db/hub 0.2.0-pre.27 → 0.2.0-pre.29

package/dist/i18n/index.d.cts

@@ -1,12 +1,12 @@
-export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, v as validateI18nTextValue } from '../strategy-D1zjEV3n.cjs';
-import { I as I18nStrategy } from '../types-CwrTuYFI.cjs';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-CwrTuYFI.cjs';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-Dwk2k1xY.cjs';
+export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, h as stripI18nFilled, v as validateI18nTextValue } from '../strategy-mJExw4LQ.cjs';
+import { I as I18nStrategy } from '../types-Ba1vQ3AY.cjs';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-Ba1vQ3AY.cjs';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-BAWO5Z5a.cjs';
 import '../lazy-builder-eYZzLEL1.cjs';
 import '../predicate-BmhBSPCH.cjs';
 import '../strategy-BSxFXGzb.cjs';
 import '../index-BMmajblo.cjs';
-import '../index-DoxKSsMj.cjs';
+import '../index-C1SC1EPe.cjs';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.d.ts

@@ -1,12 +1,12 @@
-export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, v as validateI18nTextValue } from '../strategy-YQ1qJWyq.js';
-import { I as I18nStrategy } from '../types-CkSWJt0H.js';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-CkSWJt0H.js';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-Dwk2k1xY.js';
+export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, h as stripI18nFilled, v as validateI18nTextValue } from '../strategy-8QGs5KQE.js';
+import { I as I18nStrategy } from '../types-CUmZYJwN.js';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-CUmZYJwN.js';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-BAWO5Z5a.js';
 import '../lazy-builder-ChSqcF5t.js';
 import '../predicate-BmhBSPCH.js';
 import '../strategy-BSxFXGzb.js';
 import '../index-BMmajblo.js';
-import '../index-LaexBi3v.js';
+import '../index-Ddm8D3Oo.js';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.js

@@ -7,7 +7,7 @@ import {
   isDictKeyDescriptor,
   isStaticDictDescriptor,
   staticDict
-} from "../chunk-PFKAT4NT.js";
+} from "../chunk-REHF3HSJ.js";
 import {
   applyI18nLocale,
   enforceScript,
@@ -18,12 +18,13 @@ import {
   resolveI18nText,
   resolvePolicy,
   setAtPathInPlace,
+  stripI18nFilled,
   validateI18nTextValue
-} from "../chunk-KD253AI5.js";
-import "../chunk-LXA2E3VI.js";
+} from "../chunk-QXWJQ7UU.js";
+import "../chunk-ZCMOS4H2.js";
 import "../chunk-PDVP3C2I.js";
-import "../chunk-AD6RNBAW.js";
-import "../chunk-7JSP3E67.js";
+import "../chunk-A7DNZVAV.js";
+import "../chunk-E2MDPPOC.js";
 import {
   DictKeyInUseError,
   DictKeyMissingError,
@@ -34,7 +35,82 @@ import {
   StaticDictReadonlyError,
   TranslatorNotConfiguredError,
   UnknownDictCodeError
-} from "../chunk-DDOYOMAD.js";
+} from "../chunk-JZ5DS4DP.js";
+
+// src/i18n/densify.ts
+var MARKER = "_i18nFilled";
+function priorFilled(prior, field) {
+  if (!prior) return /* @__PURE__ */ new Set();
+  const marker = prior[MARKER];
+  return new Set(marker?.[field] ?? []);
+}
+function singleLeaf(record, field) {
+  const leaves = getAtPath(record, field);
+  if (leaves.length !== 1) return void 0;
+  const leaf = leaves[0];
+  if (!leaf || typeof leaf !== "object" || Array.isArray(leaf)) return void 0;
+  return leaf;
+}
+function computeExemptFills(prior, incoming, fields) {
+  const out = /* @__PURE__ */ new Map();
+  if (!prior) return out;
+  for (const field of Object.keys(fields)) {
+    const filled = priorFilled(prior, field);
+    if (filled.size === 0) continue;
+    const priorLeaf = singleLeaf(prior, field);
+    const incLeaf = singleLeaf(incoming, field);
+    if (!priorLeaf || !incLeaf) continue;
+    const exempt = /* @__PURE__ */ new Set();
+    for (const loc of filled) {
+      if (incLeaf[loc] !== void 0 && incLeaf[loc] !== "" && incLeaf[loc] === priorLeaf[loc]) {
+        exempt.add(loc);
+      }
+    }
+    if (exempt.size > 0) out.set(field, exempt);
+  }
+  return out;
+}
+function densify(record, prior, fields) {
+  let marker = record[MARKER];
+  for (const [field, descriptor] of Object.entries(fields)) {
+    const leaf = singleLeaf(record, field);
+    if (!leaf) continue;
+    const { languages, substitute, smartSubstitute } = descriptor.options;
+    const filledSet = priorFilled(prior, field);
+    const priorLeaf = singleLeaf(prior ?? {}, field);
+    const isUnchangedFill = (loc) => filledSet.has(loc) && priorLeaf?.[loc] !== void 0 && leaf[loc] === priorLeaf[loc];
+    const authored = {};
+    for (const [loc, val] of Object.entries(leaf)) {
+      if (typeof val === "string" && val !== "" && !isUnchangedFill(loc)) authored[loc] = val;
+    }
+    const filled = [];
+    for (const loc of languages) {
+      if (authored[loc] !== void 0) continue;
+      const sub = resolveI18nText(authored, loc, void 0, field, {
+        policy: "substitute",
+        substitute: substitute ?? ["any"],
+        ...smartSubstitute ? { smartSubstitute } : {}
+      });
+      if (typeof sub === "string" && sub !== "") {
+        leaf[loc] = sub;
+        filled.push(loc);
+      } else if (isUnchangedFill(loc)) {
+        delete leaf[loc];
+      }
+    }
+    if (filled.length > 0) {
+      marker ??= {};
+      marker[field] = filled;
+    } else if (marker) {
+      delete marker[field];
+    }
+  }
+  if (marker && Object.keys(marker).length > 0) {
+    record[MARKER] = marker;
+  } else {
+    delete record[MARKER];
+  }
+}
 
 // src/i18n/active.ts
 function withI18n() {
@@ -42,6 +118,8 @@ function withI18n() {
     applyI18nLocale,
     validateI18nTextValue,
     enforceScript,
+    computeExemptFills,
+    densify,
     buildDictionaryHandle(opts) {
       return new DictionaryHandle(
         opts.adapter,
@@ -85,6 +163,7 @@ export {
   resolvePolicy,
   setAtPathInPlace,
   staticDict,
+  stripI18nFilled,
   validateI18nTextValue,
   withI18n
 };

package/dist/i18n/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/i18n/active.ts"],"sourcesContent":["/**\n * Active i18n strategy — `withI18n()` returns the real implementation\n * that wires multi-locale resolution, i18nText validation, and the\n * `DictionaryHandle` for `dictKey` fields into the core read/write\n * paths.\n *\n * Consumers opt in by:\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withI18n } from '@noy-db/hub/i18n'\n *\n * const db = await createNoydb({\n *   store: ...,\n *   user: ...,\n *   i18nStrategy: withI18n(),\n * })\n * ```\n *\n * The factory delegates to the existing `core.ts` and `dictionary.ts`\n * modules. Splitting the import chain through this file is what lets\n * tsup tree-shake the `~854 LOC` of dictionary + locale resolution\n * out of the default bundle when no `withI18n()` import is present.\n *\n * @public\n */\n\nimport type { I18nStrategy, BuildDictionaryHandleOptions } from './strategy.js'\nimport { applyI18nLocale, validateI18nTextValue } from './core.js'\nimport { enforceScript } from './script.js'\nimport { DictionaryHandle } from './dictionary.js'\n\nexport function withI18n(): I18nStrategy {\n  return {\n    applyI18nLocale,\n    validateI18nTextValue,\n    enforceScript,\n    buildDictionaryHandle<Keys extends string = string>(\n      opts: BuildDictionaryHandleOptions<Keys>,\n    ): DictionaryHandle<Keys> {\n      return new DictionaryHandle<Keys>(\n        opts.adapter,\n        opts.compartmentName,\n        opts.dictionaryName,\n        opts.keyring,\n        opts.getDEK,\n        opts.encrypted,\n        opts.ledger,\n        opts.options,\n        opts.findAndUpdateReferences,\n        opts.emitter,\n      )\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,sBACE,MACwB;AACxB,aAAO,IAAI;AAAA,QACT,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MACP;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/i18n/densify.ts","../../src/i18n/active.ts"],"sourcesContent":["/**\n * #435 v1.x densifyOnWrite — eager-fill empty i18n slots from each field's\n * substitute chain at write time, recording provenance in the internal\n * `_i18nFilled` marker (decision A: dense map + prior-read).\n *\n * Pure functions over plain records; all DB wiring lives in collection.ts.\n * Only single-leaf i18n fields are supported (array-wildcard paths are\n * skipped, mirroring auto-translate).\n */\nimport { getAtPath, resolveI18nText } from './core.js'\nimport type { I18nTextDescriptor } from './core.js'\n\nconst MARKER = '_i18nFilled'\n\ntype Leaf = Record<string, string>\n\n/** Locales recorded as densify-filled on the prior record for `field`. */\nfunction priorFilled(prior: Record<string, unknown> | undefined, field: string): Set<string> {\n  if (!prior) return new Set()\n  const marker = prior[MARKER] as Record<string, string[]> | undefined\n  return new Set(marker?.[field] ?? [])\n}\n\n/** The single leaf map for `field`, or undefined for absent / array-wildcard / non-object. */\nfunction singleLeaf(record: Record<string, unknown>, field: string): Leaf | undefined {\n  const leaves = getAtPath(record, field)\n  if (leaves.length !== 1) return undefined\n  const leaf = leaves[0]\n  if (!leaf || typeof leaf !== 'object' || Array.isArray(leaf)) return undefined\n  return leaf as Leaf\n}\n\n/**\n * Per field, the locales that are UNCHANGED round-tripped densify fills — i.e.\n * marked filled on the prior record AND identical in the incoming record.\n * These are exempt from write-time script enforcement (they are derived copies,\n * not authored text). Slots the user changed are NOT exempt (validated as authored).\n */\nexport function computeExemptFills(\n  prior: Record<string, unknown> | undefined,\n  incoming: Record<string, unknown>,\n  fields: Record<string, I18nTextDescriptor>,\n): Map<string, Set<string>> {\n  const out = new Map<string, Set<string>>()\n  if (!prior) return out\n  for (const field of Object.keys(fields)) {\n    const filled = priorFilled(prior, field)\n    if (filled.size === 0) continue\n    const priorLeaf = singleLeaf(prior, field)\n    const incLeaf = singleLeaf(incoming, field)\n    if (!priorLeaf || !incLeaf) continue\n    const exempt = new Set<string>()\n    for (const loc of filled) {\n      if (incLeaf[loc] !== undefined && incLeaf[loc] !== '' && incLeaf[loc] === priorLeaf[loc]) {\n        exempt.add(loc)\n      }\n    }\n    if (exempt.size > 0) out.set(field, exempt)\n  }\n  return out\n}\n\n/**\n * Mutate `record` in place: fill empty declared-language slots for each\n * densify-enabled field from the field's substitute chain, recompute unchanged\n * prior fills, clear marks for slots that became authored, and write the\n * resulting `_i18nFilled` marker (removed when empty).\n *\n * `prior` is read-only — it is never mutated.\n *\n * Provenance uses value-equality (decision A): a slot counts as an unchanged\n * fill when it was prior-marked AND its value still equals the prior value. A\n * consequence is that re-authoring a value byte-identical to the existing fill\n * keeps it classified as a fill (the visible value is unchanged either way; the\n * slot stays script-exempt and will auto-refresh if its source later changes).\n * This is inherent to value-equality provenance, not a bug.\n */\nexport function densify(\n  record: Record<string, unknown>,\n  prior: Record<string, unknown> | undefined,\n  fields: Record<string, I18nTextDescriptor>,\n): void {\n  let marker = record[MARKER] as Record<string, string[]> | undefined\n\n  for (const [field, descriptor] of Object.entries(fields)) {\n    const leaf = singleLeaf(record, field)\n    if (!leaf) continue\n    const { languages, substitute, smartSubstitute } = descriptor.options\n    const filledSet = priorFilled(prior, field)\n    const priorLeaf = singleLeaf(prior ?? {}, field)\n    const isUnchangedFill = (loc: string): boolean =>\n      filledSet.has(loc) && priorLeaf?.[loc] !== undefined && leaf[loc] === priorLeaf[loc]\n\n    // Authored source = present, non-empty, NOT an unchanged prior fill.\n    const authored: Leaf = {}\n    for (const [loc, val] of Object.entries(leaf)) {\n      if (typeof val === 'string' && val !== '' && !isUnchangedFill(loc)) authored[loc] = val\n    }\n\n    const filled: string[] = []\n    for (const loc of languages) {\n      if (authored[loc] !== undefined) continue // real value present → not a fill\n      const sub = resolveI18nText(authored, loc, undefined, field, {\n        policy: 'substitute',\n        substitute: substitute ?? ['any'],\n        ...(smartSubstitute ? { smartSubstitute } : {}),\n      })\n      if (typeof sub === 'string' && sub !== '') {\n        leaf[loc] = sub\n        filled.push(loc)\n      } else if (isUnchangedFill(loc)) {\n        delete leaf[loc] // stale fill with no source left → drop it\n      }\n    }\n\n    if (filled.length > 0) {\n      marker ??= {}\n      marker[field] = filled\n    } else if (marker) {\n      delete marker[field]\n    }\n  }\n\n  if (marker && Object.keys(marker).length > 0) {\n    record[MARKER] = marker\n  } else {\n    delete record[MARKER]\n  }\n}\n","/**\n * Active i18n strategy — `withI18n()` returns the real implementation\n * that wires multi-locale resolution, i18nText validation, and the\n * `DictionaryHandle` for `dictKey` fields into the core read/write\n * paths.\n *\n * Consumers opt in by:\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withI18n } from '@noy-db/hub/i18n'\n *\n * const db = await createNoydb({\n *   store: ...,\n *   user: ...,\n *   i18nStrategy: withI18n(),\n * })\n * ```\n *\n * The factory delegates to the existing `core.ts` and `dictionary.ts`\n * modules. Splitting the import chain through this file is what lets\n * tsup tree-shake the `~854 LOC` of dictionary + locale resolution\n * out of the default bundle when no `withI18n()` import is present.\n *\n * @public\n */\n\nimport type { I18nStrategy, BuildDictionaryHandleOptions } from './strategy.js'\nimport { applyI18nLocale, validateI18nTextValue } from './core.js'\nimport { enforceScript } from './script.js'\nimport { computeExemptFills, densify } from './densify.js'\nimport { DictionaryHandle } from './dictionary.js'\n\nexport function withI18n(): I18nStrategy {\n  return {\n    applyI18nLocale,\n    validateI18nTextValue,\n    enforceScript,\n    computeExemptFills,\n    densify,\n    buildDictionaryHandle<Keys extends string = string>(\n      opts: BuildDictionaryHandleOptions<Keys>,\n    ): DictionaryHandle<Keys> {\n      return new DictionaryHandle<Keys>(\n        opts.adapter,\n        opts.compartmentName,\n        opts.dictionaryName,\n        opts.keyring,\n        opts.getDEK,\n        opts.encrypted,\n        opts.ledger,\n        opts.options,\n        opts.findAndUpdateReferences,\n        opts.emitter,\n      )\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{index-DoxKSsMj.d.cts → index-C1SC1EPe.d.cts}

@@ -1,6 +1,6 @@
 import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-BmhBSPCH.cjs';
-import { N as NoydbError } from './errors-Dwk2k1xY.cjs';
-import { a as I18nTextDescriptor, N as MoneyDescriptor, A as AggregateStrategy, j as AggregateSpec, k as Aggregation, h as AggregateResult, o as GroupedQuery, p as GroupedQueryN } from './strategy-D1zjEV3n.cjs';
+import { N as NoydbError } from './errors-BAWO5Z5a.cjs';
+import { a as I18nTextDescriptor, P as MoneyDescriptor, A as AggregateStrategy, k as AggregateSpec, l as Aggregation, j as AggregateResult, p as GroupedQuery, q as GroupedQueryN } from './strategy-mJExw4LQ.cjs';
 
 /**
  * Foreign-key references — the soft-FK mechanism.
@@ -591,6 +591,14 @@ interface QuerySource<T> {
      * `sum`/`min`/`max` over money fields into exact BigInt reducers.
      */
     moneyFields?: Record<string, MoneyDescriptor>;
+    /**
+     * #308 L3 — id-paired snapshot for `Query._idArray()` (the `retrieve({within})`
+     * id projection). Optional: only collection-backed queries supply it.
+     */
+    snapshotEntries?(): readonly {
+        id: string;
+        record: T;
+    }[];
 }
 /**
  * The chainable builder. All methods return a new Query — the original
@@ -643,6 +651,15 @@ declare class Query<T> {
      * Consumers don't call this directly.
      */
     _withPredicates(predicates: ReadonlyMap<string, DeclaredPredicate>): Query<T>;
+    /**
+     * @internal — #308 L3. The ids of records matching this query's plan,
+     * recovered by reference identity: `executePlanWithSource` returns the
+     * ORIGINAL snapshot record references (money-decode and joins are applied
+     * later, in `toArray`), so each matched record is found in the id-paired
+     * `snapshotEntries()` map. Used by `collection.retrieve({ within })`.
+     * Throws if the source is not collection-backed (no `snapshotEntries`).
+     */
+    _idArray(): string[];
     /**
      * Filter by a registered deterministic predicate. Requires
      * the Query to have been augmented with a predicates map (typically

package/dist/{index-CqzZml-D.d.cts → index-DPG2nFmT.d.cts}

@@ -1,9 +1,32 @@
 import './predicate-BmhBSPCH.cjs';
-import './strategy-D1zjEV3n.cjs';
+import './strategy-mJExw4LQ.cjs';
 import './ulid-DRH25k3y.cjs';
-import './types-CwrTuYFI.cjs';
-import './errors-Dwk2k1xY.cjs';
-import './index-DoxKSsMj.cjs';
+import { dX as RetrieveHit } from './types-Ba1vQ3AY.cjs';
+import './errors-BAWO5Z5a.cjs';
+import './index-C1SC1EPe.cjs';
+
+/**
+ * #308 L3 — Reciprocal Rank Fusion. Merges N ranked `RetrieveHit` lists into
+ * one, scoring each id by Σ 1/(k + rank) across the lists it appears in. Pure,
+ * deterministic, no I/O — which is why it serves BOTH hybrid lexical⊕semantic
+ * fusion AND klum-db's cross-vault federation (the lists are per-vault). The
+ * fused `score` is the RRF score, NOT BM25 or cosine.
+ */
+
+interface FuseOptions {
+    /** Only 'rrf' in v1 (default). */
+    readonly strategy?: 'rrf';
+    /** RRF constant; larger flattens the rank weighting. Default 60. */
+    readonly k?: number;
+    /** Truncate the fused output to this many hits. */
+    readonly limit?: number;
+}
+/**
+ * Callers must supply hits with `rank >= 1` (the retrieve contract guarantees
+ * it; a federation caller passing `rank: 0` with `k: 0` would divide by zero).
+ * Doc-only note — no runtime guard; rank ≥ 1 is the retrieve contract.
+ */
+declare function fuseRetrieval<T>(lists: ReadonlyArray<ReadonlyArray<RetrieveHit<T>>>, opts?: FuseOptions): RetrieveHit<T>[];
 
 interface EncryptResult {
     iv: string;
@@ -67,4 +90,4 @@ declare function decryptDeterministic(ivBase64: string, dataBase64: string, dek:
 declare function bufferToBase64(buffer: ArrayBuffer | Uint8Array): string;
 declare function base64ToBuffer(base64: string): Uint8Array<ArrayBuffer>;
 
-export { bufferToBase64 as a, base64ToBuffer as b, decryptDeterministic as c, decryptBytes as d, derivePresenceKey as e, encryptBytes as f, encryptDeterministic as g, sha256Hex as s };
+export { type FuseOptions as F, bufferToBase64 as a, base64ToBuffer as b, decryptDeterministic as c, decryptBytes as d, derivePresenceKey as e, encryptBytes as f, encryptDeterministic as g, fuseRetrieval as h, sha256Hex as s };

package/dist/{index-wRwJVVJQ.d.ts → index-DcxTv3zx.d.ts}

@@ -1,9 +1,32 @@
 import './predicate-BmhBSPCH.js';
-import './strategy-YQ1qJWyq.js';
+import './strategy-8QGs5KQE.js';
 import './ulid-DRH25k3y.js';
-import './types-CkSWJt0H.js';
-import './errors-Dwk2k1xY.js';
-import './index-LaexBi3v.js';
+import { dX as RetrieveHit } from './types-CUmZYJwN.js';
+import './errors-BAWO5Z5a.js';
+import './index-Ddm8D3Oo.js';
+
+/**
+ * #308 L3 — Reciprocal Rank Fusion. Merges N ranked `RetrieveHit` lists into
+ * one, scoring each id by Σ 1/(k + rank) across the lists it appears in. Pure,
+ * deterministic, no I/O — which is why it serves BOTH hybrid lexical⊕semantic
+ * fusion AND klum-db's cross-vault federation (the lists are per-vault). The
+ * fused `score` is the RRF score, NOT BM25 or cosine.
+ */
+
+interface FuseOptions {
+    /** Only 'rrf' in v1 (default). */
+    readonly strategy?: 'rrf';
+    /** RRF constant; larger flattens the rank weighting. Default 60. */
+    readonly k?: number;
+    /** Truncate the fused output to this many hits. */
+    readonly limit?: number;
+}
+/**
+ * Callers must supply hits with `rank >= 1` (the retrieve contract guarantees
+ * it; a federation caller passing `rank: 0` with `k: 0` would divide by zero).
+ * Doc-only note — no runtime guard; rank ≥ 1 is the retrieve contract.
+ */
+declare function fuseRetrieval<T>(lists: ReadonlyArray<ReadonlyArray<RetrieveHit<T>>>, opts?: FuseOptions): RetrieveHit<T>[];
 
 interface EncryptResult {
     iv: string;
@@ -67,4 +90,4 @@ declare function decryptDeterministic(ivBase64: string, dataBase64: string, dek:
 declare function bufferToBase64(buffer: ArrayBuffer | Uint8Array): string;
 declare function base64ToBuffer(base64: string): Uint8Array<ArrayBuffer>;
 
-export { bufferToBase64 as a, base64ToBuffer as b, decryptDeterministic as c, decryptBytes as d, derivePresenceKey as e, encryptBytes as f, encryptDeterministic as g, sha256Hex as s };
+export { type FuseOptions as F, bufferToBase64 as a, base64ToBuffer as b, decryptDeterministic as c, decryptBytes as d, derivePresenceKey as e, encryptBytes as f, encryptDeterministic as g, fuseRetrieval as h, sha256Hex as s };

package/dist/{index-LaexBi3v.d.ts → index-Ddm8D3Oo.d.ts}

@@ -1,6 +1,6 @@
 import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-BmhBSPCH.js';
-import { N as NoydbError } from './errors-Dwk2k1xY.js';
-import { a as I18nTextDescriptor, N as MoneyDescriptor, A as AggregateStrategy, j as AggregateSpec, k as Aggregation, h as AggregateResult, o as GroupedQuery, p as GroupedQueryN } from './strategy-YQ1qJWyq.js';
+import { N as NoydbError } from './errors-BAWO5Z5a.js';
+import { a as I18nTextDescriptor, P as MoneyDescriptor, A as AggregateStrategy, k as AggregateSpec, l as Aggregation, j as AggregateResult, p as GroupedQuery, q as GroupedQueryN } from './strategy-8QGs5KQE.js';
 
 /**
  * Foreign-key references — the soft-FK mechanism.
@@ -591,6 +591,14 @@ interface QuerySource<T> {
      * `sum`/`min`/`max` over money fields into exact BigInt reducers.
      */
     moneyFields?: Record<string, MoneyDescriptor>;
+    /**
+     * #308 L3 — id-paired snapshot for `Query._idArray()` (the `retrieve({within})`
+     * id projection). Optional: only collection-backed queries supply it.
+     */
+    snapshotEntries?(): readonly {
+        id: string;
+        record: T;
+    }[];
 }
 /**
  * The chainable builder. All methods return a new Query — the original
@@ -643,6 +651,15 @@ declare class Query<T> {
      * Consumers don't call this directly.
      */
     _withPredicates(predicates: ReadonlyMap<string, DeclaredPredicate>): Query<T>;
+    /**
+     * @internal — #308 L3. The ids of records matching this query's plan,
+     * recovered by reference identity: `executePlanWithSource` returns the
+     * ORIGINAL snapshot record references (money-decode and joins are applied
+     * later, in `toArray`), so each matched record is found in the id-paired
+     * `snapshotEntries()` map. Used by `collection.retrieve({ within })`.
+     * Throws if the source is not collection-backed (no `snapshotEntries`).
+     */
+    _idArray(): string[];
     /**
      * Filter by a registered deterministic predicate. Requires
      * the Query to have been augmented with a predicates map (typically