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

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

@@ -0,0 +1,122 @@
+/**
+ * Secondary indexes for the query DSL.
+ *
+ * ships **in-memory hash indexes**:
+ *   - Built during `Collection.ensureHydrated()` from the decrypted cache
+ *   - Maintained incrementally on `put` and `delete`
+ *   - Consulted by the query executor for `==` and `in` operators on
+ *     indexed fields, falling back to a linear scan otherwise
+ *   - Live entirely in memory — no adapter writes for the index itself
+ *
+ * Persistent encrypted index blobs (the spec's "store as a separate
+ * AES-256-GCM blob" note) are deferred to a follow-up issue. The reasons
+ * are documented in the PR body — short version: at the target
+ * scale of 1K–50K records, building the index during hydrate is free,
+ * so persistence buys nothing measurable.
+ */
+/**
+ * Index declaration accepted by `Collection`'s constructor.
+ *
+ * Accepts:
+ *   - `string` — a single-field hash index (`'clientId'`)
+ *   - `{ fields: [...] }` or `readonly string[]` — a composite index
+ *     over an ordered field tuple. Only lazy-mode
+ *     collections consume composite declarations today; eager mode
+ *     silently treats a composite as equivalent to declaring each
+ *     component field as its own single-field index.
+ *
+ * Additive variants (unique constraints, partial indexes) will land as
+ * further union members without breaking existing declarations.
+ */
+export type IndexDef = string | {
+    readonly fields: readonly string[];
+    readonly unique?: boolean;
+} | readonly string[];
+/**
+ * Internal representation of a built hash index.
+ *
+ * Maps stringified field values to the set of record ids whose value
+ * for that field matches. Stringification keeps the index simple and
+ * works uniformly for primitives (`'open'`, `'42'`, `'true'`).
+ *
+ * Records whose indexed field is `undefined` or `null` are NOT inserted
+ * — `query().where('field', '==', undefined)` falls back to a linear
+ * scan, which is the conservative behavior.
+ */
+export interface HashIndex {
+    readonly field: string;
+    readonly buckets: Map<string, Set<string>>;
+}
+/**
+ * Container for all indexes on a single collection.
+ *
+ * Methods are pure with respect to the in-memory `buckets` Map — they
+ * never touch the adapter or the keyring. The Collection class owns
+ * lifecycle (build on hydrate, maintain on put/delete).
+ */
+export declare class CollectionIndexes {
+    private readonly indexes;
+    /**
+     * Per-field bucket-key canonicalizer (#672 review C1), registered ONCE
+     * via {@link setCanonicalizer} when the collection wires indexing up
+     * (money-aware via `ViaPipeline.canonicalizeIndexKey`). Consulted by
+     * EVERY bucket-mutation site — `build`/`upsert`/`remove` — so bucket
+     * membership is symmetric by construction: a value can never be added
+     * under a canonical key and later removed under the raw one (or vice
+     * versa), which is what stranded ids on `put`/`delete` before this fix.
+     */
+    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 an index. Subsequent record additions are tracked under it.
+     * Calling this twice for the same field is a no-op (idempotent).
+     */
+    declare(field: string): void;
+    /** True if the given field has a declared index. */
+    has(field: string): boolean;
+    /** All declared field names, in declaration order. */
+    fields(): string[];
+    /**
+     * Build all declared indexes from a snapshot of records.
+     * Called once per hydration. O(N × indexes.size). Buckets through the
+     * registered {@link setCanonicalizer} closure, same as `upsert`/`remove`.
+     */
+    build<T>(records: ReadonlyArray<{
+        id: string;
+        record: T;
+    }>): void;
+    /**
+     * Insert or update a single record across all indexes.
+     * Called by `Collection.put()` after the encrypted write succeeds.
+     *
+     * If `previousRecord` is provided, the record is removed from any old
+     * buckets first — this is the update path. Pass `null` for fresh adds.
+     */
+    upsert<T>(id: string, newRecord: T, previousRecord: T | null): void;
+    /**
+     * Remove a record from all indexes. Called by `Collection.delete()`
+     * (and as the first half of `upsert` for the update path).
+     */
+    remove<T>(id: string, record: T): void;
+    /** Drop all index data. Called when the collection is invalidated. */
+    clear(): void;
+    /**
+     * Equality lookup: return the set of record ids whose `field` matches
+     * the given value. Returns `null` if no index covers the field — the
+     * caller should fall back to a linear scan.
+     *
+     * The returned Set is a reference to the index's internal storage —
+     * callers must NOT mutate it.
+     */
+    lookupEqual(field: string, value: unknown): ReadonlySet<string> | null;
+    /**
+     * Set lookup: return the union of record ids whose `field` matches any
+     * of the given values. Returns `null` if no index covers the field.
+     */
+    lookupIn(field: string, values: readonly unknown[]): ReadonlySet<string> | null;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * @noy-db/hub/indexing — opt-in secondary-index service.
+ *
+ * @category capability
+ *
+ * Groups every file whose reason-for-existing is secondary indexes:
+ *   - `eager-indexes` (in-memory `CollectionIndexes` for eager-mode
+ *     collections' `.where(f, '==', v)` fast-path)
+ *   - `persisted-indexes` (lazy-mode `_idx/<field>/<recordId>`
+ *     side-car mirror with composite / typed-value support)
+ *   - `lazy-builder` (`LazyQuery<T>` chainable builder that
+ *     dispatches through the persisted mirror)
+ *
+ * Hub's root barrel (`@noy-db/hub`) and the `@noy-db/hub/query`
+ * subpath continue to re-export `CollectionIndexes` and `IndexDef`
+ * for backward compatibility with consumers written before the
+ * relocation. New code should prefer this subpath so the
+ * capability boundary is explicit in import statements.
+ */
+export { withIndexing } from './active.js';
+export type { IndexStrategy, IndexState } from './strategy.js';
+export { CollectionIndexes } from './eager-indexes.js';
+export type { IndexDef, HashIndex } from './eager-indexes.js';
+export { PersistedCollectionIndex, IDX_PREFIX, COMPOSITE_DELIMITER, encodeIdxId, decodeIdxId, isIdxId, compositeKey, } from './persisted-indexes.js';
+export type { OrderedEntry, IngestRow, PersistedIndexDef, } from './persisted-indexes.js';
+export { LazyQuery } from './lazy-builder.js';
+export type { LazyQuerySource, LazyOrderBy } from './lazy-builder.js';

package/dist/with-lookup/indexing/lazy-builder.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Lazy-mode query builder.
+ *
+ * Companion to `Query<T>` in `builder.ts`, but built for collections in lazy
+ * mode where `snapshot()` is unavailable — records live in the adapter and
+ * are pulled on demand. Dispatches through `PersistedCollectionIndex` to
+ * resolve a candidate record-id set, then decrypts only those records.
+ *
+ * Scope:
+ *   - `.where(field, '==' | 'in', value)` — dispatched through the index
+ *   - `.where(field, other-op, value)` — evaluated against the decrypted
+ *     candidate set (non-indexed ops still require the field to be indexed
+ *     — we need SOMETHING to scope the candidate set)
+ *   - `.orderBy(field, dir?)` — dispatched through `orderedBy` when no
+ *     `==`/`in` clause is present; otherwise applied as an in-memory sort
+ *     over the candidate set
+ *   - `.limit(n)` / `.offset(n)` — page slice after filtering
+ *   - `.toArray()` / `.first()` / `.count()` — terminals
+ *
+ * Every field referenced by a where or orderBy clause MUST be indexed;
+ * otherwise `toArray()` throws `IndexRequiredError`. This is deliberate:
+ * silent scan-fallback would hide the very performance cliff that lazy-mode
+ * indexes exist to prevent (see `docs/architecture.md` §indexes).
+ */
+import type { FieldClause, Operator } from '../../kernel/query/predicate.js';
+import type { PersistedCollectionIndex } from './persisted-indexes.js';
+import type { QueryField } from '../../kernel/types.js';
+import type { ViaPipeline } from '../../kernel/via/pipeline.js';
+export interface LazyOrderBy {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+/**
+ * Source abstraction the LazyQuery runs against. Collection implements it.
+ * Kept minimal so the builder stays test-friendly.
+ */
+export interface LazyQuerySource<T> {
+    readonly collectionName: string;
+    readonly persistedIndexes: PersistedCollectionIndex;
+    /**
+     * Per-field bucket-key canonicalizer (#677 — lazy twin of the eager
+     * `candidateRecords()` probe-resolution in `kernel/query/builder.ts`).
+     * Consulted in `resolveCandidateIds()` for `==`/`in` clause values
+     * BEFORE calling `lookupEqual`/`lookupIn`, so a mixed-era stored value
+     * (money) probes the SAME canonical bucket the write path now
+     * populates. A narrow closure — not the whole `ViaPipeline` — keeps
+     * the with-lookup/kernel seam thin. `undefined` (no via, or no binding
+     * covers the field) is the common case: falls back to the raw value,
+     * unchanged from today.
+     */
+    canonicalizeIndexKey?(field: string, value: unknown): string | undefined;
+    /** Ensure `_idx/<field>/*` side-cars have been bulk-loaded into the mirror. */
+    ensurePersistedIndexesLoaded(): Promise<void>;
+    /**
+     * Decrypt one record by id in RAW (pre-`present()`, stored-form) shape,
+     * or return null if it's gone (#684 — the raw-fetch seam). Used by the
+     * post-filter (`toArray()`) so a `clause.via.evaluate` (e.g. money) sees
+     * the same operand/actual-value space as eager's `filterRecords` — the
+     * DECODED form (e.g. money's canonical decimal) is only materialized
+     * for survivors, via {@link decodeRecord}.
+     */
+    getRawRecord(id: string): Promise<unknown>;
+    /**
+     * Apply this collection's locale/virtual-field decode (`present()`) to a
+     * RAW record already known to match — the output-side twin of
+     * {@link getRawRecord}. Mirrors eager's `Query.decodeVia`.
+     */
+    decodeRecord(record: unknown): Promise<T>;
+    /**
+     * This collection's compiled Via pipeline (money, i18n, …), read lazily
+     * (a method, not a captured value) so a late `_setVia` (#666) is honored
+     * — same closure discipline as {@link canonicalizeIndexKey}. `undefined`
+     * when the collection has no Via-covered fields.
+     */
+    via(): ViaPipeline | undefined;
+}
+interface LazyPlan {
+    readonly clauses: readonly FieldClause[];
+    readonly orderBy: readonly LazyOrderBy[];
+    readonly limit: number | undefined;
+    readonly offset: number;
+}
+export declare class LazyQuery<T, S extends keyof T = never, Q extends keyof T & string = never> {
+    private readonly source;
+    private readonly plan;
+    constructor(source: LazyQuerySource<T>, plan?: LazyPlan);
+    where<V>(field: QueryField<T, S, Q>, op: Operator, value: V): LazyQuery<T, S, Q>;
+    orderBy(field: QueryField<T, S>, direction?: 'asc' | 'desc'): LazyQuery<T, S, Q>;
+    limit(n: number): LazyQuery<T, S, Q>;
+    offset(n: number): LazyQuery<T, S, Q>;
+    toArray(): Promise<T[]>;
+    first(): Promise<T | null>;
+    count(): Promise<number>;
+    /**
+     * Resolve the candidate record-id set to decrypt. Returns null when the
+     * query has no usable driver — no `==`/`in` clause and no `orderBy`
+     * clause that can scope the scan. Callers interpret null as
+     * IndexRequiredError (see `toArray`).
+     */
+    private resolveCandidateIds;
+}
+export {};

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 {};