@noy-db/hub 0.3.0-pre.9 → 0.4.0-pre.0

package/dist/with-lookup/indexing/persisted-indexes.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Persistent, encrypted secondary indexes for lazy-mode collections.
+ *
+ * Parallel to the in-memory `CollectionIndexes` used by eager mode (see
+ * `packages/hub/src/query/indexes.ts`): same logical surface, but entries
+ * are materialised as encrypted side-car records (`_idx/<field>/<recordId>`)
+ * and bulk-loaded into an in-memory mirror on first query.
+ *
+ * This module only owns the id-namespace convention, the in-memory mirror,
+ * and the typed errors. Write-path integration (PR 2 / ), query-planner
+ * dispatch (PR 3 / , PR 4 / ), and the rebuild/reconcile utilities
+ * (PR 5 / ) live in other files.
+ *
+ * See the design spec for the full architecture + threat model.
+ */
+/**
+ * Reserved id prefix for encrypted index side-car records.
+ * Matches the existing `_keyring`, `_ledger_deltas/…`, `_meta/handle`
+ * conventions inside a collection's id namespace.
+ */
+export declare const IDX_PREFIX: "_idx/";
+/**
+ * Encode the side-car record id for a (field, recordId) pair.
+ *
+ * Format: `_idx/<field>/<recordId>` — no escaping. Field names may contain
+ * dots (for dotted-path access consistent with eager-mode `readPath`);
+ * record ids may contain slashes. The first two slash-separated segments
+ * are `_idx` and the field; everything after the *second* slash is the
+ * record id verbatim.
+ */
+export declare function encodeIdxId(field: string, recordId: string): string;
+/**
+ * Decode a side-car id back into `{ field, recordId }`, or `null` if the
+ * input is not a well-formed idx id. A well-formed id is:
+ *   - prefixed with `_idx/`
+ *   - contains a field segment (non-empty, no slashes)
+ *   - contains a record-id segment (non-empty, may contain slashes)
+ */
+export declare function decodeIdxId(id: string): {
+    field: string;
+    recordId: string;
+} | null;
+/**
+ * Fast-path predicate for discriminating side-car ids from regular record
+ * ids and other reserved namespaces. Used by the hub to filter `list()`
+ * results during bulk-load of the in-memory mirror.
+ */
+export declare function isIdxId(id: string): boolean;
+/**
+ * Sorted-value entry returned by `orderedBy()`. Mirrors the body shape
+ * used by the write path — but `orderedBy` emits them already sorted by
+ * `value` in the requested direction. Consumers (PR 4 / ) treat the
+ * array as immutable and paginate via a numeric offset.
+ *
+ * **Note on `value`:** as of, this is the ORIGINAL TYPED
+ * value (number, Date, boolean, etc.), not the stringified bucket key.
+ * That's what lets range predicates and `orderedBy` compare numerically
+ * instead of stumbling into `'10' < '2'` on `String(n)`.
+ */
+export interface OrderedEntry {
+    readonly recordId: string;
+    readonly value: unknown;
+}
+/**
+ * Bulk-load row shape accepted by `ingest()`. The `value` field is the
+ * decrypted index body's `value` field verbatim.
+ */
+export interface IngestRow {
+    readonly recordId: string;
+    readonly value: unknown;
+}
+/**
+ * Structured index definition. Single-field indexes carry just a field
+ * name; composite indexes carry the ordered list of fields and
+ * the synthetic `key` (= fields joined by `COMPOSITE_DELIMITER`) used
+ * as the bucket-map key and side-car envelope id segment.
+ */
+export type PersistedIndexDef = {
+    readonly kind: 'single';
+    readonly field: string;
+    readonly key: string;
+} | {
+    readonly kind: 'composite';
+    readonly fields: readonly string[];
+    readonly key: string;
+};
+/**
+ * Delimiter used to synthesize a composite-index key from an ordered
+ * field list. Intentionally a character that is extremely unusual in
+ * JavaScript object keys (`|`) so collision with a literal field name
+ * is vanishingly rare in practice. Composite declarations whose field
+ * names contain `|` are rejected at declare-time with an explicit
+ * error.
+ */
+export declare const COMPOSITE_DELIMITER = "|";
+export declare function compositeKey(fields: readonly string[]): string;
+export declare class PersistedCollectionIndex {
+    private readonly indexes;
+    private readonly defs;
+    /**
+     * Per-field bucket-key canonicalizer (#677 — lazy twin of #672's
+     * `CollectionIndexes.setCanonicalizer`), registered ONCE via
+     * {@link setCanonicalizer} when the collection wires indexing up
+     * (money-aware via `ViaPipeline.canonicalizeIndexKey`). Consulted by
+     * EVERY bucket-mutation site — `ingest`/`upsert`/`remove` — so bucket
+     * membership is symmetric: a legacy non-canonical stored value (e.g.
+     * `'0100'`) and a canonical one (`'100'`) land in the SAME bucket,
+     * mirroring `eager-indexes.ts`'s `addToIndex`/`removeFromIndex`.
+     */
+    private canonicalize?;
+    /**
+     * Register the bucket-key canonicalizer. Called once, where the
+     * collection constructs its indexing state — safe to call again (the
+     * closure is simply replaced) but there is normally only one caller.
+     */
+    setCanonicalizer(fn: (field: string, value: unknown) => string | undefined): void;
+    /**
+     * Declare a single-field index. Subsequent `upsert` / `ingest` calls
+     * populate the in-memory mirror; calls before `declare` are no-ops
+     * (tolerant bulk-load ordering). Idempotent.
+     */
+    declare(field: string): void;
+    /**
+     * Declare a composite (multi-field) index. The synthetic
+     * key is `fields.join('|')`; it doubles as the in-memory map key and
+     * the `_idx/<key>/<recordId>` side-car field segment. Callers upsert
+     * and lookup via the same `key` as single-field indexes, just with a
+     * tuple value (JSON-stringified for bucketing).
+     */
+    declareComposite(fields: readonly string[]): void;
+    /**
+     * Every declared index's structured definition. Collection walks this
+     * when materialising side-cars on put/delete so it can extract a
+     * single-field value or a composite tuple appropriately.
+     */
+    definitions(): PersistedIndexDef[];
+    /** True if `field` has been declared as indexable on this mirror. */
+    has(field: string): boolean;
+    /** All declared field names, in declaration order. */
+    fields(): string[];
+    /**
+     * Bulk-load the mirror from decrypted index bodies. Intended to be
+     * called once per field after reading the collection's `_idx/<field>/*`
+     * side-cars. Safe to call twice with the same rows — bucket Sets
+     * deduplicate recordIds. If `field` is not declared, this is a no-op
+     * (tolerates the case where bulk-load runs before `declare()` lands).
+     */
+    ingest(field: string, rows: readonly IngestRow[]): void;
+    /**
+     * Incrementally update a record's index entry for one field. Called by
+     * `Collection.put()` after the main write succeeds. If
+     * `previousValue` is non-null, the record is removed from the old
+     * bucket first — this is the update path. Pass `null` for fresh adds.
+     * No-op if the field is not declared.
+     */
+    upsert(recordId: string, field: string, newValue: unknown, previousValue: unknown): void;
+    /**
+     * Remove a record from the index for one field. Called by
+     * `Collection.delete()`. No-op if the field is not declared or
+     * the record isn't in the bucket. Empty buckets are dropped to keep
+     * the Map clean.
+     */
+    remove(recordId: string, field: string, value: unknown): void;
+    /**
+     * Drop all bucket data while preserving field declarations. Called on
+     * invalidation (incoming sync changes, keyring rotation) — the next
+     * query re-populates via `ingest`.
+     */
+    clear(): void;
+    /**
+     * Equality lookup — return the set of record ids whose `field` matches
+     * `value`. Returns `null` if the field is not declared (caller falls
+     * back to scan or throws `IndexRequiredError`). Returns a shared empty
+     * set if the field is declared but no record matches — that set MUST
+     * NOT be mutated by the caller.
+     *
+     * `value` is bucketed via the plain {@link stringifyKey} — it is NOT
+     * canonicalized here. Callers on a Via-covered field (money) canonicalize
+     * `value` themselves BEFORE calling (see `lazy-builder.ts`'s
+     * `resolveCandidateIds()`, #677) — the SAME caller-canonicalizes split
+     * `eager-indexes.ts`'s `lookupEqual`/`lookupIn` use (see `kernel/query/
+     * builder.ts`'s `candidateRecords()`), so probing here twice never
+     * double-canonicalizes.
+     */
+    lookupEqual(field: string, value: unknown): ReadonlySet<string> | null;
+    /**
+     * Set lookup — return the union of record ids whose `field` matches any
+     * of `values`. Returns `null` if the field is not declared. Returns a
+     * fresh (non-shared) Set — safe for the caller to mutate. Same
+     * caller-canonicalizes contract as {@link lookupEqual} (#677).
+     */
+    lookupIn(field: string, values: readonly unknown[]): ReadonlySet<string> | null;
+    /**
+     * Range lookup. Return record ids whose indexed value
+     * satisfies the predicate. Comparison happens on the ORIGINAL TYPED
+     * value carried in `state.values` — so numeric `<` sorts numerically,
+     * not lexicographically on `String(n)`. Returns `null` if the field
+     * is not declared.
+     *
+     * Supported ops: `'<'`, `'<='`, `'>'`, `'>='`, `'between'`. For
+     * `'between'`, `value` is `[lo, hi]` and both bounds are inclusive
+     * (matches the eager-mode operator contract in `predicate.ts`).
+     *
+     * NOT canonicalized (#677): this method compares `value` against the
+     * ORIGINAL TYPED `state.values`, not a stringified bucket key, so a
+     * `canonicalizeIndexKey`-shaped (`string | undefined`) result would not
+     * even type-check as a bound here. This does NOT mirror eager mode the
+     * way `lookupEqual`/`lookupIn` do: `moneyIndexProbe` (`via/money/
+     * where.ts`) never emits a range probe, so EAGER mode's `candidateRecords`
+     * never calls an index for a range clause and always scans.
+     *
+     * LAZY mode's `resolveCandidateIds()` (`lazy-builder.ts`) no longer
+     * dispatches a Via-covered (e.g. money) range clause through THIS method
+     * at all (#684) — it enumerates the field's indexed ids via `orderedBy()`
+     * instead and leaves the raw/typed comparison here for the (now
+     * Via-aware) post-filter to redo correctly in scaled-int space. A
+     * NON-via range clause still dispatches through this method exactly as
+     * before — the raw/typed comparison here is correct and sufficient for
+     * fields with no decode-transforming Via binding.
+     */
+    lookupRange(field: string, op: '<' | '<=' | '>' | '>=' | 'between', value: unknown): ReadonlySet<string> | null;
+    /**
+     * Sorted iteration — return every entry on `field` as an
+     * `OrderedEntry[]`, sorted by the ORIGINAL TYPED value (no more
+     * `'10' < '2'` surprises on numeric fields). Consumers paginate with
+     * a numeric offset. `OrderedEntry.value` is the typed value.
+     */
+    orderedBy(field: string, dir: 'asc' | 'desc'): readonly OrderedEntry[] | null;
+}

package/dist/with-lookup/indexing/strategy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Strategy seam between core Collection and the optional indexing
+ * service. Core imports `IndexStrategy` and `IndexState` as
+ * TYPE-ONLY symbols and `NO_INDEXING` as a tiny runtime stub.
+ *
+ * The heavy classes — `CollectionIndexes`, `PersistedCollectionIndex`,
+ * `LazyQuery` — are only instantiated inside the `withIndexing()`
+ * factory under `./active.ts`, which in turn is only reachable through
+ * the `@noy-db/hub/indexing` subpath export. A consumer that never
+ * imports the subpath ships none of those classes in their bundle
+ * (ESM tree-shaking + hub's `"sideEffects": false`).
+ *
+ * @internal
+ */
+import type { CollectionIndexes, IndexDef } from './eager-indexes.js';
+import type { PersistedCollectionIndex } from './persisted-indexes.js';
+/**
+ * Per-collection container for whatever mirrors the active strategy
+ * decided to materialize. Both accessors may return `null` — they do
+ * for `NO_INDEXING`, and `getEagerIndexes` returns null in a
+ * lazy-mode collection even when indexing is active (lazy uses the
+ * persisted mirror instead).
+ *
+ * `isEnabled` is a cheap guard so collection code can short-circuit
+ * the full indexing path without inspecting either mirror.
+ *
+ * @internal
+ */
+export interface IndexState {
+    readonly isEnabled: boolean;
+    getEagerIndexes(): CollectionIndexes | null;
+    getPersistedIndexes(): PersistedCollectionIndex | null;
+}
+/**
+ * Factory that builds one `IndexState` per Collection. Called exactly
+ * once inside each Collection constructor with the declared
+ * `IndexDef[]` and the lazy-mode flag (so lazy collections get the
+ * persisted mirror and eager collections get the in-memory one).
+ *
+ * @internal
+ */
+export interface IndexStrategy {
+    createState(args: {
+        readonly defs: readonly IndexDef[];
+        readonly lazy: boolean;
+    }): IndexState;
+}
+/**
+ * No-indexing stub. Every Collection defaults to this; it returns a
+ * cheap `IndexState` whose mirrors are both `null`. Collection code
+ * null-checks both accessors and short-circuits, so no indexing code
+ * path runs and the heavy classes never arrive in the bundle.
+ *
+ * @internal
+ */
+export declare const NO_INDEXING: IndexStrategy;

package/dist/with-lookup/indexing/unique-constraints.d.ts

@@ -0,0 +1,74 @@
+/**
+ * In-memory unique-constraint enforcement for eager-mode collections.
+ *
+ * Each `UniqueConstraintSet` holds one or more constraints, each covering
+ * an ordered tuple of field names. On every `put()` the caller invokes
+ * `check()` BEFORE the store write; on success it calls `upsert()` to
+ * update the maps. `remove()` is called on `delete()`.
+ *
+ * Null-distinct semantics: if ANY constrained field is `null` or
+ * `undefined` in the record, that record is exempt from the constraint —
+ * `keyFor` returns `null` and the record is silently skipped.
+ * This matches standard SQL NULL-distinct behavior.
+ *
+ * Only used in eager mode (`prefetch !== false`). Lazy-mode collections
+ * throw at registration instead (see Collection constructor).
+ */
+import type { IndexDef } from './eager-indexes.js';
+export declare class UniqueConstraintSet {
+    private readonly collectionName;
+    private readonly constraints;
+    constructor(collectionName: string, uniqueDefs: readonly (readonly string[])[]);
+    get size(): number;
+    /**
+     * Compute the canonical key for a record under a given constraint.
+     * Returns `null` if any constrained field is `null` or `undefined`
+     * (the record is exempt — no constraint is checked).
+     */
+    private keyFor;
+    /**
+     * Throw `UniqueConstraintError` if writing `id` with `record` would
+     * collide with a DIFFERENT existing record. Call BEFORE the store write.
+     */
+    check(id: string, record: unknown): void;
+    /**
+     * Update the constraint maps after a successful write.
+     * Pass `previous` when updating an existing record (so the old key
+     * is removed first). Pass `null` or `undefined` for a fresh insert.
+     */
+    upsert(id: string, record: unknown, previous?: unknown): void;
+    /**
+     * Remove a record from all constraint maps.
+     * Called by `Collection.delete()`.
+     */
+    remove(id: string, record: unknown): void;
+    /**
+     * Rebuild all constraint maps from a full snapshot.
+     * Called after hydration (ensureHydrated / hydrateFromSnapshot).
+     *
+     * **Last-writer-wins**: this method does NOT validate pre-existing data
+     * for duplicates. If the store already contains two records sharing a
+     * constrained value (written before the unique index was declared), the
+     * last one processed wins the map slot and the duplicate is silently
+     * displaced — no error is thrown, and the earlier holder is evicted from
+     * the map. Callers retrofitting a unique index onto populated data should
+     * run a one-time uniqueness scan before relying on enforcement.
+     */
+    build(entries: Iterable<readonly [string, unknown]>): void;
+}
+/**
+ * Build the `UniqueConstraintSet` for a collection from its `IndexDef[]`,
+ * or return `null` when no `unique: true` index is declared.
+ *
+ * Unique enforcement is **eager-mode only**. If any `unique` index is
+ * declared on a lazy (`prefetch:false`), CRDT, or tiered collection, this
+ * throws `UnsupportedIndexOptionError` at registration rather than letting
+ * those write paths (which bypass `check()`/`upsert()`) silently skip
+ * enforcement. Kept out of the Collection constructor to keep that
+ * always-on kernel file lean (kernel-surface invariant).
+ */
+export declare function buildUniqueConstraintSet(collectionName: string, indexes: readonly IndexDef[] | undefined, mode: {
+    readonly lazy: boolean;
+    readonly crdt: boolean;
+    readonly tiered: boolean;
+}): UniqueConstraintSet | null;

package/dist/with-lookup/search/active.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Enable the search / retrieval capability.
+ * Pass to `createNoydb({ searchStrategy: withSearch() })` to make a collection's
+ * `search` / `retrieve` / `similarTo` / `warmIndex` / `flushIndex` methods live,
+ * and to enable the put()-time embedding-vector compute for collections that
+ * declare an `embeddings` config. The search/retrieval engine is dynamically
+ * imported here, so it stays out of the floor bundle until opted in.
+ */
+import type { SearchStrategy } from './strategy.js';
+export declare function withSearch(): SearchStrategy;

package/dist/with-lookup/search/build-docs.d.ts

@@ -0,0 +1,15 @@
+import type { I18nTextDescriptor } from '../../via/i18n/core.js';
+import type { DictKeyDescriptor, StaticDictDescriptor } from '../../via/i18n/dictionary.js';
+import type { IndexDoc } from './inverted-index.js';
+type FieldEntry = IndexDoc['fields'][number];
+export declare function buildStringFieldEntries(record: Record<string, unknown>, textIndexes: readonly string[], only?: readonly string[]): FieldEntry[];
+export declare function buildI18nFieldEntries(record: Record<string, unknown>, i18nFields: Record<string, I18nTextDescriptor>, textIndexes: readonly string[], only?: readonly string[]): FieldEntry[];
+/** label map: field -> (key -> { locale -> label }). Precomputed in the collection (async for dynamic dicts). */
+export declare function buildDictKeyFieldEntries(record: Record<string, unknown>, dictKeyFields: Record<string, DictKeyDescriptor | StaticDictDescriptor>, labelMaps: Map<string, Map<string, Record<string, string>>>, textIndexes: readonly string[], only?: readonly string[]): FieldEntry[];
+/**
+ * Blob filenames precomputed in the collection (`field -> filenames[]`, from one
+ * async `listSlots()` per record — the heaviest source, see {@link buildBlobFieldEntries}'s
+ * caller). Bytes are never tokenized; only the slot `filename` is indexed.
+ */
+export declare function buildBlobFieldEntries(filenamesByField: Map<string, string[]>): FieldEntry[];
+export {};

package/dist/with-lookup/search/collection-facade.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Collection-level search / retrieval (`search` / `retrieve` / `similarTo` +
+ * the lexical-index build/flush/warm machinery).
+ *
+ * This is the retrieval surface: a pure client-side lexical scan
+ * (`search`), the persisted-or-in-memory inverted-index lifecycle
+ * (`flushIndex` / `warmIndex` / `buildRetrievalDocs` + the dict-label / blob-
+ * filename resolvers that feed it), and the lexical / semantic / hybrid
+ * `retrieve` fan-out plus raw-vector kNN (`similarTo`). None of it touches the
+ * write path — it reads the live eager cache and the encrypted `_vec` / `_ftindex`
+ * side-cars.
+ *
+ * Every function takes a small {@link SearchContext} instead of `this`,
+ * mirroring the `record-keys/` siblings.
+ *
+ * The `cache` is the SAME `Map` reference `Collection` owns (passed by
+ * reference, never copied) so the index always builds over the live working
+ * set. {@link buildPersistedIndexCallbacks} is special: it is invoked from the
+ * `Collection` constructor *before* `this.codec` exists, so it takes a context
+ * THUNK and resolves the context lazily at each callback invocation.
+ *
+ * Internal service — not exported as a `@noy-db/hub/*` subpath.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { RecordCodec } from '../../kernel/enclave/index.js';
+import { type I18nTextDescriptor } from '../../via/i18n/core.js';
+import { type DictKeyDescriptor, type StaticDictDescriptor, type DictionaryHandle } from '../../via/i18n/dictionary.js';
+import type { BlobSet } from '../../with-shape/blobs/blob-set.js';
+import type { BlobFieldsConfig } from '../../with-shape/blobs/blob-compaction.js';
+import { type VectorSet, type EmbeddingDescriptor } from '../embeddings/index.js';
+import { type SearchOptions, type SearchResult } from './index.js';
+import type { IndexStore } from './index-store.js';
+import type { PersistedIndexCallbacks } from './persisted-index-store.js';
+import type { IndexDoc } from './inverted-index.js';
+import type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+/** Everything the moving search/retrieval methods touched on `this.*`. */
+export interface SearchContext<T> {
+    /** Collection name — error context + `_ftindex` row key. */
+    readonly name: string;
+    /** Vault namespace the side-cars (`_vec`, `_ftindex`) live under. */
+    readonly vault: string;
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** The record codec — decrypts the `_vec` / `_ftindex` side-car bodies. */
+    readonly codec: RecordCodec<T>;
+    /** The eager working-set cache (SHARED `Map` reference, never copied). */
+    readonly cache: Map<string, {
+        record: T;
+        version: number;
+    }>;
+    /** True in lazy mode — search/retrieve/warm require eager mode. */
+    readonly lazy: boolean;
+    /** Declared text-index fields, or undefined. */
+    readonly textIndexes: readonly string[] | undefined;
+    /** Declared i18n fields, or undefined. */
+    readonly i18nFields: Record<string, I18nTextDescriptor> | undefined;
+    /** Declared dictionary-key fields, or undefined. */
+    readonly dictKeyFields: Record<string, DictKeyDescriptor | StaticDictDescriptor> | undefined;
+    /** Declared blob fields, or undefined. */
+    readonly blobFields: BlobFieldsConfig | undefined;
+    /** Dictionary handle resolver (dynamic dict-key labels), or undefined. */
+    readonly getDictionary: ((name: string) => Promise<DictionaryHandle>) | undefined;
+    /** The lexical inverted-index store (in-memory or persisted), or undefined. */
+    readonly searchIndexStore: IndexStore | undefined;
+    /** The vector set for semantic retrieval, or undefined. */
+    readonly vectorSet: VectorSet | undefined;
+    /** The embeddings descriptor, or undefined. */
+    readonly embeddings: EmbeddingDescriptor | undefined;
+    /** Hydrate the eager cache before reading it. */
+    ensureHydrated(): Promise<void>;
+    /** Open the blob facade for a record (used to list indexed blob filenames). */
+    blob(id: string): BlobSet;
+}
+/**
+ * Client-side lexical scan over the live eager cache. Eager mode only;
+ * nothing searchable is written to the store.
+ */
+export declare function search<T>(ctx: SearchContext<T>, field: string, query: string, opts?: SearchOptions): Promise<SearchResult<T>[]>;
+/** L1 — build IndexDoc[] for the configured text fields over the live cache. */
+export declare function buildRetrievalDocs<T>(ctx: SearchContext<T>, labelMaps: Map<string, Map<string, Record<string, string>>>, blobFilenames: Map<string, Map<string, string[]>>, only?: readonly string[]): IndexDoc[];
+/** L1 — true iff any configured text index is also a blob field (gates ALL slot I/O). */
+export declare function hasIndexedBlobFields<T>(ctx: SearchContext<T>, only?: readonly string[]): boolean;
+/** L1.5 — force-persist the lexical index now (e.g. on save/idle). Persists only when textIndexPersist is enabled; a no-op otherwise. */
+export declare function flushIndex<T>(ctx: SearchContext<T>): Promise<void>;
+/**
+ * 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: ctx.cache stores { record, version } — currentFingerprint()
+ * iterates over e.version.
+ *
+ * NOTE: this factory is invoked from the `Collection` constructor *before*
+ * `this.codec` is assigned, so it takes a context THUNK and resolves the
+ * context lazily inside each callback — by the time a callback actually runs,
+ * the codec and cache are fully wired.
+ */
+export declare function buildPersistedIndexCallbacks<T>(provideCtx: () => SearchContext<T>): PersistedIndexCallbacks;
+/** L1 — pre-build the lexical index (e.g. on open) so the first retrieve() pays no build scan. */
+export declare function warmIndex<T>(ctx: SearchContext<T>): Promise<void>;
+/** Retrieval. mode: 'lexical' (default) | 'semantic' (L2) | 'hybrid' (L3). */
+export declare function retrieve<T>(ctx: SearchContext<T>, query: string, opts?: RetrieveOptions<T>): Promise<RetrieveHit<T>[]>;
+/** 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). */
+export declare function similarTo<T>(ctx: SearchContext<T>, vector: Float32Array, opts?: {
+    k?: number;
+    minScore?: number;
+    includeRecord?: boolean;
+}): Promise<RetrieveHit<T>[]>;
+/**
+ * L2 — the embedding write-hook: derive a record's embedding vector at
+ * write and persist it as the encrypted `_vec` side-car. Routed through the
+ * search strategy so it runs only when `withSearch()` is opted in — computing
+ * vectors that no gated `similarTo` / semantic `retrieve` could query would be
+ * dead weight, so the compute is paired with the search capability. The caller
+ * (`Collection.put`) only invokes this when `embeddings` is declared.
+ */
+export declare function embedOnWrite<T>(ctx: SearchContext<T>, id: string, record: T, version: number): Promise<void>;
+/**
+ * Force-re-derive every eligible tier-0 record's `_vec` sidecar once (#788).
+ * Opt-in bulk repair for the #726 re-namespace: legacy bare-id rows are
+ * unreachable to `buildVectorLoad` (it only recognises `<collection>/<id>`
+ * keys) and otherwise self-heal only when a record is next `put()` — this
+ * lets an adopter recover recall immediately instead of waiting on writes.
+ *
+ * **Skips elevated records** (`liveRecordIsElevated`) rather than refusing
+ * the whole walk — the OPPOSITE of `_applyCutoverTransform`'s
+ * `assertCutoverTierSafe` refuse-whole-batch precedent. An elevated record is
+ * SUPPOSED to have no `_vec` (`syncTierSearch` purges it on elevate);
+ * re-embedding one here would write searchable plaintext-derived data above
+ * tier 0. Load-bearing: never write a `_vec` row for an elevated record.
+ *
+ * Tombstones, delete markers, and a raw `get` racing a delete between `list`
+ * and `get` all decrypt to `null` (`decryptRecord` already folds
+ * tombstone/delete-marker into that null) and are skipped the same way.
+ * Unconditional re-derive, no already-migrated check — safe to re-run after
+ * a partial failure (each id is independently idempotent).
+ */
+export declare function rebuildEmbeddings<T>(ctx: SearchContext<T>): Promise<{
+    rebuilt: number;
+    skipped: number;
+}>;
+/**
+ * Sync the collection's SEARCH artifacts after a tier move (#721). Both the
+ * lexical `_ftindex` blob and the `_vec/<id>` embedding are encrypted under
+ * the tier-0 DEK and hold the record's derived plaintext (full field text /
+ * a text-invertible vector), so leaving them means elevation never hid what
+ * the record was searchable by — the `forget()` precedent, unapplied to
+ * elevate. `null` → the record left tier 0: purge its `_vec` sidecar (mirrors
+ * `Collection._purgeVector`), and invalidate the `_ftindex` blob (mirrors
+ * `Collection._purgeSearchIndex`: deletes the persisted blob when persisted,
+ * else drops the in-memory index) so the next `retrieve()` rebuilds from the
+ * elevated-free `ctx.cache`. A record → it is tier-0 again: re-embed it via
+ * {@link embedOnWrite}, then invalidate `_ftindex` so the rebuild includes it
+ * again. No-op fast when the collection has neither a lexical index nor a
+ * vector set.
+ */
+export declare function syncTierSearch<T>(ctx: SearchContext<T>, id: string, record: T | null, version?: number): Promise<void>;

package/dist/with-lookup/search/fuse.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+import type { RetrieveHit } from './retrieve-types.js';
+export 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.
+ */
+export declare function fuseRetrieval<T>(lists: ReadonlyArray<ReadonlyArray<RetrieveHit<T>>>, opts?: FuseOptions): RetrieveHit<T>[];

package/dist/with-lookup/search/index-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The index persistence seam (L1.5). MemoryIndexStore is session-scoped and
+ * lazy; an opaque-blob backend implements the same interface so the
+ * collection call-site is unchanged.
+ */
+import { InvertedIndex, type IndexDoc } from './inverted-index.js';
+export interface IndexStore {
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    markDirty(): void;
+    flush(): Promise<void>;
+    readonly built: boolean;
+}
+export declare class MemoryIndexStore implements IndexStore {
+    private index;
+    get built(): boolean;
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    markDirty(): void;
+    flush(): Promise<void>;
+}

package/dist/with-lookup/search/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Search service — scan-mode full-text search.
+ *
+ * Tree-shakeable: only reaches the bundle when `collection.search()` is called.
+ * The store-usable blind index (SSE) is a separate, gated opt-in and not
+ * built here.
+ */
+export { tokenize, type Tokenizer } from './tokenize.js';
+export { searchScan, type SearchOptions, type SearchResult, type SearchEntry } from './scan.js';
+export { segmentTokens, segmentTokenizer, type Token } from './segment.js';
+export { InvertedIndex, type IndexDoc, type IndexHit, type QueryOptions } from './inverted-index.js';
+export { extractSnippet } from './snippet.js';
+export { MemoryIndexStore, type IndexStore } from './index-store.js';
+export { buildStringFieldEntries } from './build-docs.js';
+export type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+export { fuseRetrieval, type FuseOptions } from './fuse.js';
+export { withSearch } from './active.js';
+export { NO_SEARCH, type SearchStrategy } from './strategy.js';
+export { SearchNotEnabledError } from '../../kernel/errors.js';

package/dist/with-lookup/search/inverted-index.d.ts

@@ -0,0 +1,47 @@
+export interface IndexDoc {
+    readonly id: string;
+    readonly fields: ReadonlyArray<{
+        readonly field: string;
+        readonly locale?: string;
+        readonly text: string;
+    }>;
+}
+export interface IndexHit {
+    readonly id: string;
+    readonly score: number;
+    readonly field: string;
+    readonly locale?: string;
+    readonly text: string;
+    readonly offset: number;
+}
+export interface QueryOptions {
+    readonly limit?: number;
+    readonly match?: 'any' | 'all';
+    readonly prefix?: boolean;
+    readonly fields?: readonly string[];
+}
+export interface IndexSnapshot {
+    readonly v: 1;
+    readonly fieldStats: ReadonlyArray<[string, {
+        df: [string, number][];
+        n: number;
+        totalLen: number;
+    }]>;
+    readonly docs: ReadonlyArray<{
+        id: string;
+        field: string;
+        locale?: string;
+        text: string;
+        len: number;
+        tf: [string, number][];
+        firstOffset: [string, number][];
+    }>;
+}
+export declare class InvertedIndex {
+    private readonly fieldStats;
+    private readonly docs;
+    static build(docs: ReadonlyArray<IndexDoc>): InvertedIndex;
+    query(query: string, opts?: QueryOptions): IndexHit[];
+    toSnapshot(): IndexSnapshot;
+    static fromSnapshot(s: IndexSnapshot): InvertedIndex;
+}