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

package/dist/bundle/index.cjs

@@ -203,7 +203,7 @@ var init_format = __esm({
 });
 
 // src/errors.ts
-var NoydbError, DebugPlaintextError, DebugReservedFieldError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, ForgetStrategyNotConfiguredError, RecordCekNotFoundError;
+var NoydbError, DebugPlaintextError, DebugReservedFieldError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, ForgetStrategyNotConfiguredError, RecordCekNotFoundError, EmbeddingDimMismatchError, EmbeddingModelMismatchError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -948,6 +948,34 @@ Resolutions:
         this.id = id;
       }
     };
+    EmbeddingDimMismatchError = class extends NoydbError {
+      field;
+      expected;
+      actual;
+      constructor(field, expected, actual) {
+        super(
+          "EMBEDDING_DIM_MISMATCH",
+          `Embedding for "${field}" has dim ${actual}, expected ${expected}.`
+        );
+        this.name = "EmbeddingDimMismatchError";
+        this.field = field;
+        this.expected = expected;
+        this.actual = actual;
+      }
+    };
+    EmbeddingModelMismatchError = class extends NoydbError {
+      expected;
+      found;
+      constructor(expected, found) {
+        super(
+          "EMBEDDING_MODEL_MISMATCH",
+          `Embedding model mismatch: collection uses "${expected}" but a stored vector is "${found}". Run vault.embeddings.reindex() after changing the encoder.`
+        );
+        this.name = "EmbeddingModelMismatchError";
+        this.expected = expected;
+        this.found = found;
+      }
+    };
   }
 });
 
@@ -6862,6 +6890,36 @@ var init_builder = __esm({
           predicates
         );
       }
+      /**
+       * @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() {
+        const entries = this.source.snapshotEntries?.();
+        if (entries === void 0) {
+          throw new Error(
+            "Query._idArray(): the query source has no snapshotEntries(); retrieve({ within }) requires a collection-backed query (collection.query())."
+          );
+        }
+        if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+          throw new Error(
+            "Query._idArray(): retrieve({ within }) does not support crossJoin queries (cross-join produces new row objects, breaking id recovery). Use where/filter/and/or, or a projection .join()."
+          );
+        }
+        const refToId = /* @__PURE__ */ new Map();
+        for (const { id, record } of entries) refToId.set(record, id);
+        const matched = executePlanWithSource(this.source, this.plan, this.joinContext);
+        const ids = [];
+        for (const r of matched) {
+          const id = refToId.get(r);
+          if (id !== void 0) ids.push(id);
+        }
+        return ids;
+      }
       /**
        * Filter by a registered deterministic predicate. Requires
        * the Query to have been augmented with a predicates map (typically
@@ -8297,11 +8355,469 @@ var init_scan = __esm({
   }
 });
 
+// src/search/segment.ts
+var SEGMENTER, segmentTokens, segmentTokenizer;
+var init_segment = __esm({
+  "src/search/segment.ts"() {
+    "use strict";
+    SEGMENTER = new Intl.Segmenter(void 0, { granularity: "word" });
+    segmentTokens = (text) => {
+      const out = [];
+      if (!text) return out;
+      for (const s of SEGMENTER.segment(text)) {
+        if (s.isWordLike) out.push({ term: s.segment.normalize("NFKC").toLowerCase(), offset: s.index });
+      }
+      return out;
+    };
+    segmentTokenizer = (text) => segmentTokens(text).map((t) => t.term);
+  }
+});
+
+// src/search/inverted-index.ts
+var K12, B2, InvertedIndex;
+var init_inverted_index = __esm({
+  "src/search/inverted-index.ts"() {
+    "use strict";
+    init_segment();
+    K12 = 1.2;
+    B2 = 0.75;
+    InvertedIndex = class _InvertedIndex {
+      // per field: df (term -> #docs), N (#docs), totalLen
+      fieldStats = /* @__PURE__ */ new Map();
+      docs = [];
+      static build(docs) {
+        const idx = new _InvertedIndex();
+        for (const d of docs) {
+          for (const f of d.fields) {
+            const tokens = segmentTokens(f.text);
+            const tf = /* @__PURE__ */ new Map();
+            const firstOffset = /* @__PURE__ */ new Map();
+            for (const t of tokens) {
+              tf.set(t.term, (tf.get(t.term) ?? 0) + 1);
+              if (!firstOffset.has(t.term)) firstOffset.set(t.term, t.offset);
+            }
+            const doc = { id: d.id, field: f.field, ...f.locale !== void 0 ? { locale: f.locale } : {}, text: f.text, len: tokens.length, tf, firstOffset };
+            idx.docs.push(doc);
+            let s = idx.fieldStats.get(f.field);
+            if (!s) {
+              s = { df: /* @__PURE__ */ new Map(), n: 0, totalLen: 0 };
+              idx.fieldStats.set(f.field, s);
+            }
+            s.n += 1;
+            s.totalLen += doc.len;
+            for (const term of tf.keys()) s.df.set(term, (s.df.get(term) ?? 0) + 1);
+          }
+        }
+        return idx;
+      }
+      query(query, opts = {}) {
+        const terms = segmentTokenizer(query);
+        if (terms.length === 0) return [];
+        const usePrefix = opts.prefix ?? false;
+        const exact = usePrefix ? terms.slice(0, -1) : terms;
+        const prefix = usePrefix ? terms[terms.length - 1] : void 0;
+        const match = opts.match ?? "any";
+        const required = exact.length + (prefix !== void 0 ? 1 : 0);
+        const best = /* @__PURE__ */ new Map();
+        for (const doc of this.docs) {
+          if (opts.fields !== void 0 && !opts.fields.includes(doc.field)) continue;
+          const stats = this.fieldStats.get(doc.field);
+          const avgdl = stats.totalLen / stats.n || 1;
+          let score = 0;
+          let matchedCount = 0;
+          let snippetOffset = -1;
+          const scoreTerm = (tf, df, offset) => {
+            if (tf <= 0) return;
+            matchedCount += 1;
+            if (snippetOffset < 0 && offset >= 0) snippetOffset = offset;
+            const idf = Math.log(1 + (stats.n - df + 0.5) / (df + 0.5));
+            const denom = tf + K12 * (1 - B2 + B2 * (doc.len / avgdl));
+            score += idf * (tf * (K12 + 1) / (denom || 1));
+          };
+          for (const qt of exact) scoreTerm(doc.tf.get(qt) ?? 0, stats.df.get(qt) ?? 0, doc.firstOffset.get(qt) ?? -1);
+          if (prefix !== void 0) {
+            const exactSet = new Set(exact);
+            let ptf = 0;
+            let poff = -1;
+            for (const [term, c] of doc.tf) {
+              if (term.startsWith(prefix) && !exactSet.has(term)) {
+                ptf += c;
+                if (poff < 0) poff = doc.firstOffset.get(term) ?? -1;
+              }
+            }
+            if (ptf > 0) {
+              let pdf = 0;
+              for (const d of this.docs) {
+                if (d.field === doc.field && [...d.tf.keys()].some((t) => t.startsWith(prefix))) pdf++;
+              }
+              scoreTerm(ptf, pdf || 1, poff);
+            }
+          }
+          if (matchedCount === 0) continue;
+          if (match === "all" && matchedCount < required) continue;
+          const hit = {
+            id: doc.id,
+            score,
+            field: doc.field,
+            text: doc.text,
+            offset: snippetOffset < 0 ? 0 : snippetOffset,
+            ...doc.locale !== void 0 ? { locale: doc.locale } : {}
+          };
+          const prev = best.get(doc.id);
+          if (!prev || hit.score > prev.score) best.set(doc.id, hit);
+        }
+        const results = [...best.values()].sort((a, b) => b.score - a.score);
+        return opts.limit !== void 0 ? results.slice(0, opts.limit) : results;
+      }
+      toSnapshot() {
+        return {
+          v: 1,
+          fieldStats: [...this.fieldStats].map(([f, s]) => [f, { df: [...s.df], n: s.n, totalLen: s.totalLen }]),
+          docs: this.docs.map((d) => ({
+            id: d.id,
+            field: d.field,
+            text: d.text,
+            len: d.len,
+            tf: [...d.tf],
+            firstOffset: [...d.firstOffset],
+            ...d.locale !== void 0 ? { locale: d.locale } : {}
+          }))
+        };
+      }
+      static fromSnapshot(s) {
+        const idx = new _InvertedIndex();
+        for (const [f, st] of s.fieldStats) idx.fieldStats.set(f, { df: new Map(st.df), n: st.n, totalLen: st.totalLen });
+        for (const d of s.docs) {
+          idx.docs.push({
+            id: d.id,
+            field: d.field,
+            text: d.text,
+            len: d.len,
+            tf: new Map(d.tf),
+            firstOffset: new Map(d.firstOffset),
+            ...d.locale !== void 0 ? { locale: d.locale } : {}
+          });
+        }
+        return idx;
+      }
+    };
+  }
+});
+
+// src/search/snippet.ts
+function extractSnippet(text, offset, window = 80) {
+  const chars = Array.from(text);
+  if (chars.length <= window) return text;
+  const cpOffset = Array.from(text.slice(0, Math.max(0, offset))).length;
+  const half = Math.floor(window / 2);
+  let start = Math.max(0, cpOffset - half);
+  const end = Math.min(chars.length, start + window);
+  start = Math.max(0, end - window);
+  const body = chars.slice(start, end).join("");
+  return `${start > 0 ? "\u2026" : ""}${body}${end < chars.length ? "\u2026" : ""}`;
+}
+var init_snippet = __esm({
+  "src/search/snippet.ts"() {
+    "use strict";
+  }
+});
+
+// src/search/index-store.ts
+var MemoryIndexStore;
+var init_index_store = __esm({
+  "src/search/index-store.ts"() {
+    "use strict";
+    init_inverted_index();
+    MemoryIndexStore = class {
+      index;
+      get built() {
+        return this.index !== void 0;
+      }
+      async ensureBuilt(build) {
+        if (this.index === void 0) this.index = InvertedIndex.build(build());
+        return this.index;
+      }
+      markDirty() {
+        this.index = void 0;
+      }
+      async flush() {
+      }
+    };
+  }
+});
+
+// src/search/build-docs.ts
+function buildStringFieldEntries(record, textIndexes, only) {
+  const fields = only ? textIndexes.filter((f) => only.includes(f)) : textIndexes;
+  const out = [];
+  for (const field of fields) {
+    for (const leaf of getAtPath(record, field)) {
+      if (typeof leaf === "string" && leaf !== "") out.push({ field, text: leaf });
+    }
+  }
+  return out;
+}
+function buildI18nFieldEntries(record, i18nFields, textIndexes, only) {
+  const fields = (only ? textIndexes.filter((f) => only.includes(f)) : textIndexes).filter((f) => f in i18nFields);
+  const out = [];
+  for (const field of fields) {
+    for (const leaf of getAtPath(record, field)) {
+      if (!leaf || typeof leaf !== "object" || Array.isArray(leaf)) continue;
+      for (const [locale, val] of Object.entries(leaf)) {
+        if (typeof val === "string" && val !== "") out.push({ field, locale, text: val });
+      }
+    }
+  }
+  return out;
+}
+function buildDictKeyFieldEntries(record, dictKeyFields, labelMaps, textIndexes, only) {
+  const fields = (only ? textIndexes.filter((f) => only.includes(f)) : textIndexes).filter((f) => f in dictKeyFields);
+  const out = [];
+  for (const field of fields) {
+    const map = labelMaps.get(field);
+    if (!map) continue;
+    for (const leaf of getAtPath(record, field)) {
+      const keys = typeof leaf === "string" ? [leaf] : Array.isArray(leaf) ? leaf.filter((k) => typeof k === "string") : [];
+      for (const key of keys) {
+        const labels = map.get(key);
+        if (!labels) continue;
+        for (const [locale, label] of Object.entries(labels)) {
+          if (label !== "") out.push({ field, locale, text: label });
+        }
+      }
+    }
+  }
+  return out;
+}
+function buildBlobFieldEntries(filenamesByField) {
+  const out = [];
+  for (const [field, names] of filenamesByField) {
+    for (const name of names) if (name !== "") out.push({ field, text: name });
+  }
+  return out;
+}
+var init_build_docs = __esm({
+  "src/search/build-docs.ts"() {
+    "use strict";
+    init_core();
+  }
+});
+
+// src/search/fuse.ts
+function fuseRetrieval(lists, opts = {}) {
+  const k = opts.k ?? 60;
+  const acc = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (const hit of list) {
+      const contribution = 1 / (k + hit.rank);
+      const prev = acc.get(hit.id);
+      if (prev === void 0) {
+        acc.set(hit.id, { score: contribution, hit });
+      } else {
+        prev.score += contribution;
+        prev.hit = mergePresentation(prev.hit, hit);
+      }
+    }
+  }
+  const merged = [...acc.values()].sort(
+    (a, b) => b.score - a.score || (a.hit.id < b.hit.id ? -1 : a.hit.id > b.hit.id ? 1 : 0)
+  );
+  const limited = opts.limit !== void 0 ? merged.slice(0, opts.limit) : merged;
+  return limited.map((m, i) => ({ ...m.hit, score: m.score, rank: i + 1 }));
+}
+function mergePresentation(a, b) {
+  const lexical = a.field !== "(vector)" ? a : b;
+  const other = lexical === a ? b : a;
+  return {
+    ...lexical,
+    ...lexical.record === void 0 && other.record !== void 0 ? { record: other.record } : {}
+  };
+}
+var init_fuse = __esm({
+  "src/search/fuse.ts"() {
+    "use strict";
+  }
+});
+
 // src/search/index.ts
 var init_search = __esm({
   "src/search/index.ts"() {
     "use strict";
     init_scan();
+    init_fuse();
+  }
+});
+
+// src/search/serialize.ts
+function serializeIndex(idx) {
+  return JSON.stringify(idx.toSnapshot());
+}
+function deserializeIndex(json) {
+  return InvertedIndex.fromSnapshot(JSON.parse(json));
+}
+var init_serialize = __esm({
+  "src/search/serialize.ts"() {
+    "use strict";
+    init_inverted_index();
+  }
+});
+
+// src/search/persisted-index-store.ts
+function fpEqual(a, b) {
+  return a.count === b.count && a.maxVersion === b.maxVersion;
+}
+var PersistedIndexStore;
+var init_persisted_index_store = __esm({
+  "src/search/persisted-index-store.ts"() {
+    "use strict";
+    init_inverted_index();
+    init_serialize();
+    PersistedIndexStore = class {
+      constructor(cb) {
+        this.cb = cb;
+        this.debounceMs = cb.debounceMs ?? 1e3;
+      }
+      cb;
+      index;
+      timer = null;
+      lastBuild;
+      debounceMs;
+      get built() {
+        return this.index !== void 0;
+      }
+      async ensureBuilt(build) {
+        this.lastBuild = build;
+        if (this.index !== void 0) return this.index;
+        const loaded = await this.cb.load();
+        if (loaded !== null && fpEqual(loaded.fingerprint, this.cb.currentFingerprint())) {
+          this.index = deserializeIndex(loaded.json);
+          return this.index;
+        }
+        this.index = InvertedIndex.build(build());
+        await this.persist();
+        return this.index;
+      }
+      markDirty() {
+        this.index = void 0;
+        if (this.timer) clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+          this.timer = null;
+          void this.rebuildAndPersist().catch(() => {
+          });
+        }, this.debounceMs);
+      }
+      /** Force an immediate persist (cancels any pending debounce). */
+      async flush() {
+        if (this.timer) {
+          clearTimeout(this.timer);
+          this.timer = null;
+        }
+        await this.rebuildAndPersist();
+      }
+      /** Delete the persisted blob and drop the in-memory index (forget/erasure). */
+      async removePersisted() {
+        if (this.timer) {
+          clearTimeout(this.timer);
+          this.timer = null;
+        }
+        this.index = void 0;
+        await this.cb.remove();
+      }
+      /** Rebuild using the last known build thunk, then persist. */
+      async rebuildAndPersist() {
+        if (this.lastBuild === void 0) return;
+        if (this.index === void 0) {
+          this.index = InvertedIndex.build(this.lastBuild());
+        }
+        await this.persist();
+      }
+      async persist() {
+        if (this.index === void 0) return;
+        await this.cb.save(serializeIndex(this.index), this.cb.currentFingerprint());
+      }
+    };
+  }
+});
+
+// src/embeddings/cosine.ts
+function cosine(a, b) {
+  if (a.length !== b.length) return 0;
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i], y = b[i];
+    dot += x * y;
+    na += x * x;
+    nb += y * y;
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+var init_cosine = __esm({
+  "src/embeddings/cosine.ts"() {
+    "use strict";
+  }
+});
+
+// src/embeddings/descriptor.ts
+function embeddingSourceText(record, source) {
+  const fields = typeof source === "string" ? [source] : source;
+  const parts = [];
+  for (const f of fields) {
+    for (const leaf of getAtPath(record, f)) {
+      if (typeof leaf === "string" && leaf !== "") parts.push(leaf);
+    }
+  }
+  return parts.join(" ");
+}
+var init_descriptor2 = __esm({
+  "src/embeddings/descriptor.ts"() {
+    "use strict";
+    init_core();
+  }
+});
+
+// src/embeddings/vector-set.ts
+var VectorSet;
+var init_vector_set = __esm({
+  "src/embeddings/vector-set.ts"() {
+    "use strict";
+    init_cosine();
+    init_errors();
+    VectorSet = class {
+      vectors;
+      get loaded() {
+        return this.vectors !== void 0;
+      }
+      async ensureLoaded(load) {
+        if (this.vectors === void 0) this.vectors = await load();
+      }
+      markDirty() {
+        this.vectors = void 0;
+      }
+      cosineTopK(query, k, opts = {}) {
+        const all = this.vectors ?? [];
+        const minScore = opts.minScore ?? -Infinity;
+        const hits = [];
+        for (const v of all) {
+          if (opts.expectModel !== void 0 && v.model !== opts.expectModel) {
+            throw new EmbeddingModelMismatchError(opts.expectModel, v.model);
+          }
+          const score = cosine(query, v.vec);
+          if (score >= minScore) hits.push({ id: v.id, score });
+        }
+        hits.sort((a, b) => b.score - a.score);
+        return hits.slice(0, k);
+      }
+    };
+  }
+});
+
+// src/embeddings/index.ts
+var init_embeddings = __esm({
+  "src/embeddings/index.ts"() {
+    "use strict";
+    init_descriptor2();
+    init_vector_set();
   }
 });
 
@@ -9687,7 +10203,12 @@ var init_collection = __esm({
     init_lazy_builder();
     init_strategy5();
     init_search();
+    init_index_store();
+    init_persisted_index_store();
+    init_snippet();
+    init_build_docs();
     init_errors();
+    init_embeddings();
     init_unique_constraints();
     init_cache();
     init_ulid();
@@ -9839,12 +10360,33 @@ var init_collection = __esm({
        * Declared via the `i18nFields` collection option.
        */
       i18nFields;
+      /**
+       * #308 L1 — the configured string fields exposed to `retrieve()`. `undefined`
+       * for ordinary collections, so the search path costs nothing when unused.
+       */
+      textIndexes;
+      /**
+       * #308 L1 — the session-scoped lexical index store. `undefined` (so the dirty
+       * poke + retrieve are zero-cost) unless `textIndexes` is non-empty.
+       */
+      searchIndexStore;
       /**
        * #435 — the densify-enabled subset of {@link i18nFields} (fields whose
        * descriptor opts in via `densifyOnWrite: true`). `undefined` when none opt
        * in, so the write path skips all densify work for ordinary collections.
        */
       i18nDensifyFields;
+      /**
+       * #308 L2 — embedding config for write-time vector derivation. `undefined`
+       * for ordinary collections (zero cost). When set, `put()` encodes the
+       * source field(s) and stores an encrypted `_vec` sidecar.
+       */
+      embeddings;
+      /**
+       * #308 L2 — in-memory vector set, populated lazily from `_vec` sidecars.
+       * `undefined` when no embedding config is declared.
+       */
+      vectorSet;
       /**
        * Map of field name → `DictKeyDescriptor` for fields declared with
        * `dictKey()`. Used by `get()`/`list()` to add `<field>Label` virtual
@@ -9871,6 +10413,12 @@ var init_collection = __esm({
        * Signature: `(dictName, key, locale, fallback?) => Promise<string | undefined>`
        */
       dictLabelResolver;
+      /**
+       * #308 L1 — async callback provided by the Vault to open a dynamic
+       * dictionary handle (for label-map pre-computation in the search index).
+       * Only used in `resolveDictLabelMaps()`; static dicts bypass this entirely.
+       */
+      getDictionary;
       /**
        * Synchronous callback provided by the Vault that validates
        * i18nText fields on `put()`. Throws `MissingTranslationError` when
@@ -10031,15 +10579,25 @@ var init_collection = __esm({
         this.refEnforcer = opts.refEnforcer;
         this.joinResolver = opts.joinResolver;
         this.i18nFields = opts.i18nFields;
+        this.textIndexes = opts.textIndexes;
+        this.searchIndexStore = opts.textIndexes && opts.textIndexes.length > 0 ? opts.textIndexPersist ? new PersistedIndexStore(this.buildPersistedIndexCallbacks()) : new MemoryIndexStore() : void 0;
         const densifyFields = opts.i18nFields ? Object.fromEntries(
           Object.entries(opts.i18nFields).filter(([, d]) => d.options.densifyOnWrite === true)
         ) : {};
         this.i18nDensifyFields = Object.keys(densifyFields).length > 0 ? densifyFields : void 0;
+        if (opts.embeddings && opts.crdt) {
+          throw new Error(
+            `Collection "${opts.name}": embeddings are not supported on CRDT collections (L2). Use a non-CRDT collection for semantic search.`
+          );
+        }
+        this.embeddings = opts.embeddings;
+        this.vectorSet = opts.embeddings ? new VectorSet() : void 0;
         this.dictKeyFields = opts.dictKeyFields;
         if (opts.moneyFields) validateMoneyFieldPaths(opts.moneyFields);
         this.moneyFields = opts.moneyFields;
         this.computed = opts.computed;
         this.dictLabelResolver = opts.dictLabelResolver;
+        this.getDictionary = opts.getDictionary;
         this.i18nPutValidator = opts.i18nPutValidator;
         this.autoTranslateHook = opts.autoTranslateHook;
         this.defaultLocale = opts.defaultLocale;
@@ -10621,6 +11179,7 @@ var init_collection = __esm({
           }
           await this.onDirty?.(this.name, id, "put", version2);
           this.emitter.emit("change", { vault: this.vault, collection: this.name, id, action: "put" });
+          this.searchIndexStore?.markDirty();
           await this.onAccess?.("put", id);
           await this.dispatchDerivations(id, record, version2);
           await this.dispatchMaterializedViews(id, record);
@@ -10662,6 +11221,15 @@ var init_collection = __esm({
         }
         const envelope = await this.encryptRecord(record, version, cek, options?.source, options?.sourceTs);
         await this.adapter.put(this.vault, this.name, id, envelope);
+        if (this.embeddings) {
+          const text = embeddingSourceText(record, this.embeddings.source);
+          const vec = await this.embeddings.encode(text);
+          if (vec.length !== this.embeddings.dim) throw new EmbeddingDimMismatchError("embeddings", this.embeddings.dim, vec.length);
+          const body = JSON.stringify({ vec: Array.from(vec), model: this.embeddings.model, dim: this.embeddings.dim });
+          const vecEnv = await this.encryptJsonString(body, version);
+          await this.adapter.put(this.vault, "_vec", id, vecEnv);
+          this.vectorSet?.markDirty();
+        }
         if (this.ledger) {
           const appendInput = {
             op: "put",
@@ -10692,6 +11260,7 @@ var init_collection = __esm({
           id,
           action: "put"
         });
+        this.searchIndexStore?.markDirty();
         await this.onAccess?.("put", id);
         await this.dispatchDerivations(id, record, version);
         await this.dispatchMaterializedViews(id, record);
@@ -11215,6 +11784,7 @@ var init_collection = __esm({
           id,
           action: "delete"
         });
+        this.searchIndexStore?.markDirty();
         await this.onAccess?.("delete", id);
         if (!internal) {
           await this.dispatchMaterializedViewsOnDelete(id);
@@ -11399,6 +11969,252 @@ var init_collection = __esm({
         for (const [id, e] of this.cache) entries.push({ id, record: stripI18nFilled(e.record) });
         return searchScan(entries, field, query, opts);
       }
+      /** #308 L1 — build IndexDoc[] for the configured text fields over the live cache. */
+      buildRetrievalDocs(labelMaps, blobFilenames, only) {
+        const docs = [];
+        for (const [id, e] of this.cache) {
+          const rec = stripI18nFilled(e.record);
+          const fields = buildStringFieldEntries(rec, this.textIndexes ?? [], only);
+          if (this.i18nFields) fields.push(...buildI18nFieldEntries(rec, this.i18nFields, this.textIndexes ?? [], only));
+          if (this.dictKeyFields) fields.push(...buildDictKeyFieldEntries(rec, this.dictKeyFields, labelMaps, this.textIndexes ?? [], only));
+          const blobNames = blobFilenames.get(id);
+          if (blobNames) fields.push(...buildBlobFieldEntries(blobNames));
+          if (fields.length > 0) docs.push({ id, fields });
+        }
+        return docs;
+      }
+      /** #308 L1 — true iff any configured text index is also a blob field (gates ALL slot I/O). */
+      hasIndexedBlobFields(only) {
+        if (!this.blobFields || !this.textIndexes) return false;
+        const fields = only ? this.textIndexes.filter((f) => only.includes(f)) : this.textIndexes;
+        return fields.some((f) => f in this.blobFields);
+      }
+      /**
+       * #308 L1 — resolve `recordId -> (blobField -> filenames[])` by listing slots
+       * for the configured blob fields of each cached record. Blob slot metadata is
+       * NOT inline on the record: it lives in a separate `_blob_slots_*` collection,
+       * so this costs ONE `blob(id).list()` (a `listSlots`) per record at build time
+       * — the heaviest indexing source. Fully gated by {@link hasIndexedBlobFields};
+       * non-blob (and blob-but-not-indexed) collections do ZERO slot I/O.
+       */
+      async resolveBlobFilenames(only) {
+        const out = /* @__PURE__ */ new Map();
+        if (!this.hasIndexedBlobFields(only)) return out;
+        const indexed = (only ? this.textIndexes.filter((f) => only.includes(f)) : this.textIndexes).filter((f) => f in this.blobFields);
+        const indexedSet = new Set(indexed);
+        for (const id of this.cache.keys()) {
+          let slots;
+          try {
+            slots = await this.blob(id).list();
+          } catch {
+            continue;
+          }
+          let byField;
+          for (const slot of slots) {
+            if (!indexedSet.has(slot.name) || !slot.filename) continue;
+            if (!byField) {
+              byField = /* @__PURE__ */ new Map();
+              out.set(id, byField);
+            }
+            const names = byField.get(slot.name);
+            if (names) names.push(slot.filename);
+            else byField.set(slot.name, [slot.filename]);
+          }
+        }
+        return out;
+      }
+      /** #308 L1 — field -> (key -> {locale->label}) for dictKey fields; static from table, dynamic via getDictionary().list(). */
+      async resolveDictLabelMaps() {
+        const maps = /* @__PURE__ */ new Map();
+        if (!this.dictKeyFields || !this.textIndexes) return maps;
+        for (const field of this.textIndexes) {
+          const desc = this.dictKeyFields[field];
+          if (!desc) continue;
+          const m = /* @__PURE__ */ new Map();
+          if (isStaticDictDescriptor(desc)) {
+            for (const [key, labels] of Object.entries(desc.table)) m.set(key, labels);
+          } else {
+            if (this.getDictionary) {
+              const handle = await this.getDictionary(desc.name);
+              for (const e of await handle.list()) m.set(e.key, e.labels);
+            }
+          }
+          maps.set(field, m);
+        }
+        return maps;
+      }
+      /** #308 L1.5 — force-persist the lexical index now (e.g. on save/idle). Persists only when textIndexPersist is enabled; a no-op otherwise. */
+      async flushIndex() {
+        if (!this.searchIndexStore) return;
+        await this.ensureHydrated();
+        const labelMaps = await this.resolveDictLabelMaps();
+        const blobFilenames = await this.resolveBlobFilenames();
+        await this.searchIndexStore.ensureBuilt(() => this.buildRetrievalDocs(labelMaps, blobFilenames));
+        await this.searchIndexStore.flush?.();
+      }
+      /** #308 L2 — load + decrypt all _vec sidecars into StoredVector[] for the VectorSet. */
+      buildVectorLoad() {
+        return async () => {
+          const ids = await this.adapter.list(this.vault, "_vec");
+          const out = [];
+          for (const id of ids) {
+            const env = await this.adapter.get(this.vault, "_vec", id);
+            if (!env) continue;
+            const body = await this.decryptJsonString(env);
+            if (body === null) continue;
+            const parsed = JSON.parse(body);
+            out.push({ id, vec: new Float32Array(parsed.vec), model: parsed.model });
+          }
+          return out;
+        };
+      }
+      /**
+       * #308 L1.5 — build the PersistedIndexCallbacks bridge: crypto lives here
+       * (collection has getDEK / encryptJsonString / decryptJsonString / adapter),
+       * the index store itself is crypto-free.
+       *
+       * Fingerprint encoding: body-wrap approach — save(json, fp) stores
+       * JSON.stringify({ fp, idx: json }) as the encrypted body so the standard
+       * EncryptedEnvelope shape is never extended. load() decrypts and JSON.parses
+       * the wrapper back out.
+       *
+       * Cache shape: this.cache stores { record, version } — currentFingerprint()
+       * iterates over e.version.
+       */
+      buildPersistedIndexCallbacks() {
+        const FT = "_ftindex";
+        return {
+          load: async () => {
+            const env = await this.adapter.get(this.vault, FT, this.name);
+            if (!env) return null;
+            const body = await this.decryptJsonString(env);
+            if (body === null) return null;
+            try {
+              const wrapped = JSON.parse(body);
+              return { json: wrapped.idx, fingerprint: wrapped.fp };
+            } catch {
+              return null;
+            }
+          },
+          save: async (json, fp) => {
+            const body = JSON.stringify({ fp, idx: json });
+            const env = await this.encryptJsonString(body, fp.count);
+            await this.adapter.put(this.vault, FT, this.name, env);
+          },
+          remove: async () => {
+            await this.adapter.delete(this.vault, FT, this.name);
+          },
+          currentFingerprint: () => {
+            let maxVersion = 0;
+            for (const e of this.cache.values()) if (e.version > maxVersion) maxVersion = e.version;
+            return { count: this.cache.size, maxVersion };
+          }
+        };
+      }
+      /** #308 L1 — pre-build the lexical index (e.g. on open) so the first retrieve() pays no build scan. */
+      async warmIndex() {
+        if (!this.searchIndexStore) return;
+        if (this.lazy) {
+          throw new Error(
+            `Collection "${this.name}": warmIndex() requires eager mode (prefetch: true).`
+          );
+        }
+        await this.ensureHydrated();
+        const built = this.searchIndexStore.built;
+        const labelMaps = built ? /* @__PURE__ */ new Map() : await this.resolveDictLabelMaps();
+        const blobFilenames = built ? /* @__PURE__ */ new Map() : await this.resolveBlobFilenames();
+        await this.searchIndexStore.ensureBuilt(() => this.buildRetrievalDocs(labelMaps, blobFilenames));
+      }
+      /** #308 — retrieval. mode: 'lexical' (default) | 'semantic' (L2) | 'hybrid' (L3). */
+      async retrieve(query, opts = {}) {
+        const hits = opts.mode === "semantic" ? await this.retrieveSemantic(query, opts) : opts.mode === "hybrid" ? await this.retrieveHybrid(query, opts) : await this.retrieveLexical(query, opts);
+        return opts.within ? this.applyWithin(hits, opts.within) : hits;
+      }
+      /** #308 L3 — keep only hits whose id matches the structured query, re-rank 1-based. */
+      applyWithin(hits, within) {
+        const ids = new Set(within._idArray());
+        return hits.filter((h) => ids.has(h.id)).map((h, i) => ({ ...h, rank: i + 1 }));
+      }
+      /** #308 L1 — client-side lexical retrieval; ranked { id, score, field, snippet, locale? }. */
+      async retrieveLexical(query, opts) {
+        if (!this.searchIndexStore) {
+          throw new Error(`Collection "${this.name}": retrieve() requires a textIndexes config.`);
+        }
+        if (this.lazy) {
+          throw new Error(
+            `Collection "${this.name}": retrieve() requires eager mode (prefetch: true).`
+          );
+        }
+        await this.ensureHydrated();
+        const built = this.searchIndexStore.built;
+        const labelMaps = built ? /* @__PURE__ */ new Map() : await this.resolveDictLabelMaps();
+        const blobFilenames = built ? /* @__PURE__ */ new Map() : await this.resolveBlobFilenames();
+        const index = await this.searchIndexStore.ensureBuilt(() => this.buildRetrievalDocs(labelMaps, blobFilenames));
+        const hits = index.query(query, {
+          ...opts.limit !== void 0 ? { limit: opts.limit } : {},
+          ...opts.match ? { match: opts.match } : {},
+          ...opts.prefix ? { prefix: opts.prefix } : {},
+          ...opts.fields ? { fields: opts.fields } : {}
+        });
+        const window = opts.snippetWindow ?? 80;
+        return hits.map((h, i) => {
+          const base = {
+            id: h.id,
+            score: h.score,
+            rank: i + 1,
+            field: h.field,
+            snippet: extractSnippet(h.text, h.offset, window),
+            ...h.locale !== void 0 ? { locale: h.locale } : {},
+            ...opts.includeRecord ? (() => {
+              const e = this.cache.get(h.id);
+              return e ? { record: stripI18nFilled(e.record) } : {};
+            })() : {}
+          };
+          return base;
+        });
+      }
+      /** #308 L3 — hybrid: fuse lexical (L1) + semantic (L2) by RRF. Requires embeddings. */
+      async retrieveHybrid(query, opts) {
+        if (!this.embeddings) {
+          throw new Error(`Collection "${this.name}": retrieve({mode:'hybrid'}) requires an embeddings config.`);
+        }
+        const [lex, sem] = await Promise.all([
+          this.retrieveLexical(query, opts),
+          this.retrieveSemantic(query, opts)
+        ]);
+        return fuseRetrieval([lex, sem], opts.limit !== void 0 ? { limit: opts.limit } : {});
+      }
+      /** #308 L2 — semantic branch of retrieve(): encode query → similarTo(). */
+      async retrieveSemantic(query, opts) {
+        if (!this.embeddings) throw new Error(`Collection "${this.name}": retrieve({mode:'semantic'}) requires an embeddings config.`);
+        if (this.lazy) throw new Error(`Collection "${this.name}": retrieve() requires eager mode (prefetch: true).`);
+        const qVec = await this.embeddings.encode(query);
+        return this.similarTo(qVec, {
+          ...opts.limit !== void 0 ? { k: opts.limit } : {},
+          ...opts.minScore !== void 0 ? { minScore: opts.minScore } : {},
+          ...opts.includeRecord ? { includeRecord: true } : {}
+        });
+      }
+      /** #308 L2 — raw-vector kNN over the encrypted vector set (decrypted in the trusted tier).
+       *  Snippet is '' for vector hits in v1 (semantic match isn't span-located). */
+      async similarTo(vector, opts = {}) {
+        if (!this.embeddings || !this.vectorSet) throw new Error(`Collection "${this.name}": similarTo() requires an embeddings config.`);
+        if (this.lazy) throw new Error(`Collection "${this.name}": similarTo() requires eager mode (prefetch: true).`);
+        await this.ensureHydrated();
+        await this.vectorSet.ensureLoaded(this.buildVectorLoad());
+        const hits = this.vectorSet.cosineTopK(vector, opts.k ?? 10, {
+          ...opts.minScore !== void 0 ? { minScore: opts.minScore } : {},
+          expectModel: this.embeddings.model
+        });
+        return hits.map((h, i) => {
+          const base = { id: h.id, score: h.score, rank: i + 1, field: "(vector)", snippet: "" };
+          if (opts.includeRecord) {
+            const e = this.cache.get(h.id);
+            if (e) base.record = stripI18nFilled(e.record);
+          }
+          return base;
+        });
+      }
       // ─── Bulk operations ─────────────────────────────────────
       /**
        * Put many records in one call. Each item is processed sequentially
@@ -11568,6 +12384,7 @@ var init_collection = __esm({
           // back to a linear scan otherwise.
           getIndexes: () => this.getIndexes(),
           lookupById: (id) => this.cache.get(id)?.record,
+          snapshotEntries: () => [...this.cache.entries()].map(([id, e]) => ({ id, record: e.record })),
           ...this.moneyFields ? { moneyFields: this.moneyFields } : {}
         };
         const resolver = this.joinResolver;
@@ -11998,6 +12815,7 @@ var init_collection = __esm({
       async _applyRemoteChange(id, action) {
         await this._invalidateCacheEntry(id);
         this.emitter.emit("change", { vault: this.vault, collection: this.name, id, action });
+        this.searchIndexStore?.markDirty();
       }
       /** @internal — the current in-memory record without a store read (for conflict capture). */
       _peekCached(id) {
@@ -12496,6 +13314,19 @@ var init_collection = __esm({
         }
         return { purged, residue };
       }
+      /** #308 L2 — drop a record's encrypted _vec sidecar on erasure (a vector is text-invertible).
+       *  Called by vault.ts forget() inside a resilient try/catch; residue is reported in ForgetResult. */
+      async _purgeVector(id) {
+        await this.adapter.delete(this.vault, "_vec", id);
+        this.vectorSet?.markDirty();
+      }
+      /** #308 L1.5 — drop the persisted lexical-index blob (forget/erasure): an opaque
+       *  all-records index must not survive crypto-shred. Idempotent; no-op without persist. */
+      async _purgeSearchIndex() {
+        const store = this.searchIndexStore;
+        if (store && "removePersisted" in store) await store.removePersisted();
+        else store?.markDirty();
+      }
       /**
        * Bulk-load the persisted-index mirror from `_idx/<field>/*` side-cars
        * on first lazy-mode query. Idempotent — subsequent calls short-circuit
@@ -17192,6 +18023,10 @@ var init_vault = __esm({
           collOpts.onCrossTierAccess = (event) => this.emitCrossTier(event);
           if (this.syncAdapter !== void 0) collOpts.syncAdapter = this.syncAdapter;
           if (options?.i18nFields !== void 0) collOpts.i18nFields = options.i18nFields;
+          if (options?.embeddings !== void 0) collOpts.embeddings = options.embeddings;
+          if (options?.textIndexes !== void 0) collOpts.textIndexes = options.textIndexes;
+          if (options?.warmIndexOnOpen !== void 0) collOpts.warmIndexOnOpen = options.warmIndexOnOpen;
+          if (options?.textIndexPersist !== void 0) collOpts.textIndexPersist = options.textIndexPersist;
           if (options?.moneyFields !== void 0) collOpts.moneyFields = options.moneyFields;
           if (options?.computed !== void 0) collOpts.computed = options.computed;
           if (options?.dictKeyFields !== void 0) {
@@ -17204,6 +18039,7 @@ var init_vault = __esm({
               const handle = this.dictionary(dictName);
               return handle.resolveLabel(key, locale, fallback);
             };
+            collOpts.getDictionary = async (name) => this.dictionary(name);
             collOpts.dictKeyFields = options.dictKeyFields;
           }
           if (options?.i18nFields !== void 0 || options?.dictKeyFields !== void 0) {
@@ -17217,6 +18053,10 @@ var init_vault = __esm({
           }
           coll = new Collection(collOpts);
           this.collectionCache.set(collectionName, coll);
+          if (options?.warmIndexOnOpen === true && options.prefetch !== false) {
+            void coll.warmIndex().catch(() => {
+            });
+          }
           if (options?.persistJsonSchema === true && options.schema !== void 0 && (options.schemaUpdate?.length ?? 0) === 0) {
             const validator = options.schema;
             const work = (async () => {
@@ -17326,6 +18166,16 @@ var init_vault = __esm({
         this.#fenceWatcher = void 0;
         this.#fenceCoordinationStarted = false;
       }
+      /** @internal #308 L1.5 — best-effort flush of all open collections' persisted
+       *  lexical indexes on close(). Called fire-and-forget from noydb.close().
+       *  Correctness is backstopped by the fingerprint: a missed flush → rebuild on
+       *  next load. Only collections with textIndexPersist have a flush(); others no-op. */
+      async _flushSearchIndexes() {
+        for (const coll of this.collectionCache.values()) {
+          await coll.flushIndex().catch(() => {
+          });
+        }
+      }
       /** @internal Drive one heartbeat + watch cycle deterministically (tests). */
       async _fenceTick() {
         this._ensureFenceCoordination();
@@ -18400,6 +19250,11 @@ var init_vault = __esm({
           const idxPurge = await coll._purgePersistedIndexes(ref.id);
           indexPostingsPurged += idxPurge.purged;
           for (const field of idxPurge.residue) indexResidue.push(`${ref.collection}:${ref.id}:${field}`);
+          try {
+            await coll._purgeVector(ref.id);
+          } catch {
+            indexResidue.push(`${ref.collection}:${ref.id}:_vec`);
+          }
           if (blobsEnabled) {
             const r = await this.collection(ref.collection).blob(ref.id).shredAllForRecord();
             blobsShredded += r.shredded.length;
@@ -18414,6 +19269,13 @@ var init_vault = __esm({
           }
           await this._removeSubjectRef(subjectId, ref);
         }
+        for (const collName of collections) {
+          try {
+            await this.collection(collName)._purgeSearchIndex();
+          } catch {
+            indexResidue.push(`${collName}:_ftindex`);
+          }
+        }
         const subjectHash = await sha256Hex3(subjectId);
         const ledger = this.getLedgerOrNull();
         if (!ledger) {
@@ -22512,6 +23374,7 @@ var init_noydb = __esm({
         }
         this.syncEngines.clear();
         for (const v of this.vaultCache.values()) v._stopFenceCoordination();
+        for (const v of this.vaultCache.values()) void v._flushSearchIndexes();
         this.disableTabCoordination();
         this.keyringCache.clear();
         this.vaultCache.clear();