@noy-db/hub 0.3.0-pre.10 → 0.3.0-pre.11

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

@@ -0,0 +1,30 @@
+/**
+ * Active indexing strategy factory. Calling `withIndexing()` returns
+ * an `IndexStrategy` whose `createState` constructs a real
+ * `CollectionIndexes` (eager) or `PersistedCollectionIndex` (lazy)
+ * per Collection, depending on the collection's `prefetch` mode and
+ * its declared `IndexDef[]`.
+ *
+ * This module is only reachable through the `@noy-db/hub/indexing`
+ * subpath — a consumer that never imports the subpath ships none of
+ * this (ESM tree-shaking + hub's `"sideEffects": false`).
+ */
+import type { IndexStrategy } from './strategy.js';
+/**
+ * Build the default indexing strategy. Pass into
+ * `createNoydb({ indexStrategy: withIndexing() })` to light up the
+ * eager-mode `==/in` fast-path on `.query()` and the full lazy-mode
+ * `.lazyQuery()` + rebuild / reconcile / auto-reconcile surface.
+ *
+ * @example
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withIndexing } from '@noy-db/hub/indexing'
+ *
+ * const db = await createNoydb({
+ *   store, user, secret,
+ *   indexStrategy: withIndexing(),
+ * })
+ * ```
+ */
+export declare function withIndexing(): IndexStrategy;

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

@@ -0,0 +1,120 @@
+/**
+ * Collection-level index maintenance — the eager/unique rebuild-from-cache
+ * helpers, the full `rebuildIndexes` / `reconcileIndex` repair surface, and the
+ * persisted `_idx/<field>/<recordId>` side-car maintenance fired from the write
+ * path.
+ *
+ * Eager mode keeps an in-memory `CollectionIndexes` + `UniqueConstraintSet`;
+ * lazy mode keeps durable encrypted side-cars whose in-memory mirror is a
+ * `PersistedCollectionIndex`. These functions write/repair both. The unique-
+ * constraint correctness and the side-car drift reconciliation are the parts to
+ * watch: behaviour here is byte-identical to the inline code it replaced.
+ *
+ * Every function takes a small {@link IndexingContext} (the exact `this.*` the
+ * moving methods touched) instead of `this`, mirroring the `record-keys/`
+ * siblings. The eager `cache` Map and the three index/constraint mirror objects
+ * are passed by reference (the SAME instances `Collection` owns, never copied)
+ * so maintenance always mutates the live mirrors the query path reads. The
+ * `persistedIndexesLoaded` flag and `ensure*` hydration stay collection-resident
+ * and are reached via callbacks.
+ *
+ * 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 { NoydbEventEmitter } from '../../kernel/events.js';
+import type { CollectionIndexes } from './eager-indexes.js';
+import type { UniqueConstraintSet } from './unique-constraints.js';
+import { type PersistedCollectionIndex } from './persisted-indexes.js';
+/** Everything the moving index-maintenance methods touched on `this.*`. */
+export interface IndexingContext<T> {
+    /** Collection name — the canonical record namespace + error context. */
+    readonly name: string;
+    /** Vault namespace the records + side-cars live under. */
+    readonly vault: string;
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** The record codec — decrypts records + side-car bodies, encrypts side-cars. */
+    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 — eager rebuild short-circuits, reconcile requires it. */
+    readonly lazy: boolean;
+    /** Event emitter — surfaces `index:write-partial` on side-car write failure. */
+    readonly emitter: NoydbEventEmitter;
+    /** The in-memory eager index mirror, or null (SHARED reference). */
+    readonly indexes: CollectionIndexes | null;
+    /** The in-memory unique-constraint mirror, or null (SHARED reference). */
+    readonly uniqueConstraints: UniqueConstraintSet | null;
+    /** The lazy-mode persisted-index mirror, or null (SHARED reference). */
+    readonly persistedIndexes: PersistedCollectionIndex | null;
+    /** Hydrate the eager cache before rebuilding from it. */
+    ensureHydrated(): Promise<void>;
+    /** Bulk-load the persisted-index mirror from side-cars (lazy mode). */
+    ensurePersistedIndexesLoaded(): Promise<void>;
+    /** Set the collection-resident `persistedIndexesLoaded` flag. */
+    setPersistedIndexesLoaded(value: boolean): void;
+}
+/**
+ * Rebuild the eager in-memory `CollectionIndexes` from the current cache.
+ * Called after any bulk hydration; incremental put/delete updates go through
+ * `indexes.upsert()`/`.remove()` directly, so this only fires for full reloads.
+ */
+export declare function rebuildEagerIndexesFromCache<T>(ctx: IndexingContext<T>): void;
+/**
+ * Rebuild unique-constraint maps from the current in-memory cache.
+ * Called after any bulk hydration alongside `rebuildEagerIndexesFromCache`.
+ */
+export declare function rebuildUniqueConstraintsFromCache<T>(ctx: IndexingContext<T>): void;
+/**
+ * Rebuild every declared index from scratch — eager refresh from cache, or a
+ * full lazy-mode side-car teardown + rewrite. NOT incremental; for per-field
+ * drift repair use {@link reconcileIndex}.
+ */
+export declare function rebuildIndexes<T>(ctx: IndexingContext<T>): Promise<void>;
+/**
+ * Compare the persisted `_idx/<field>/*` side-cars against the canonical
+ * records for a single field, reporting the drift (and optionally repairing
+ * it). Lazy mode only — eager mode throws (the in-memory index cannot drift).
+ */
+export declare function reconcileIndex<T>(ctx: IndexingContext<T>, field: string, opts?: {
+    dryRun?: boolean;
+}): Promise<{
+    field: string;
+    missing: string[];
+    stale: string[];
+    applied: number;
+}>;
+/**
+ * Write / update / delete the `_idx/<field>/<recordId>` side-cars for every
+ * declared persistence-index field after a successful main-record `put()`.
+ * Called AFTER `adapter.put()` of the main record succeeds; side-car write
+ * failures surface as `index:write-partial` and do NOT fail the put.
+ */
+export declare function maintainPersistedIndexesOnPut<T>(ctx: IndexingContext<T>, id: string, newRecord: T, previousRecord: T | null, version: number): Promise<void>;
+/**
+ * Tear down `_idx/<field>/<recordId>` side-cars for a deleted record.
+ * Mirror state updates regardless of adapter outcome; adapter failures
+ * surface on `index:write-partial` the same way put does.
+ */
+export declare function maintainPersistedIndexesOnDelete<T>(ctx: IndexingContext<T>, id: string, previousRecord: T): Promise<void>;
+/**
+ * @internal — hard-delete this record's persisted `_idx/<field>/<recordId>`
+ * side-cars for the erasure path. `forget()` crypto-shreds the body but
+ * keeps the collection DEK, under which these side-cars are encrypted — so
+ * without this they leave the indexed field VALUES readable after a "forget".
+ *
+ * Content-free: the side-car id is `encodeIdxId(def.key, id)`, so it needs no
+ * body decode (the body is being shredded). Eager mode has no durable side-car
+ * → no-op. The in-memory mirror is left as-is: it is ephemeral (rebuilt from
+ * the now-deleted side-cars on reopen) and live reads skip the tombstone, so a
+ * stale mirror hit cannot surface the erased record. Returns the count deleted
+ * + the `def.key`s whose delete FAILED (residue that still leaks the value).
+ */
+export declare function purgePersistedIndexes<T>(ctx: IndexingContext<T>, id: string): Promise<{
+    purged: number;
+    residue: string[];
+}>;

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,69 @@
+/**
+ * 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';
+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;
+    /** Ensure `_idx/<field>/*` side-cars have been bulk-loaded into the mirror. */
+    ensurePersistedIndexesLoaded(): Promise<void>;
+    /** Decrypt one record by id, or return null if it's gone. */
+    getRecord(id: string): Promise<T | null>;
+}
+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,186 @@
+/**
+ * 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;
+    /**
+     * 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.
+     */
+    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.
+     */
+    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`).
+     */
+    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;