@noy-db/core 0.1.1 → 0.3.0

package/dist/index.d.cts

@@ -21,7 +21,30 @@ interface EncryptedEnvelope {
 }
 /** All records across all collections for a compartment. */
 type CompartmentSnapshot = Record<string, Record<string, EncryptedEnvelope>>;
+/**
+ * Result of a single page fetch via the optional `listPage` adapter extension.
+ *
+ * `items` carries the actual encrypted envelopes (not just ids) so the
+ * caller can decrypt and emit a single record without an extra `get()`
+ * round-trip per id. `nextCursor` is `null` on the final page.
+ */
+interface ListPageResult {
+    /** Encrypted envelopes for this page, in adapter-defined order. */
+    items: Array<{
+        id: string;
+        envelope: EncryptedEnvelope;
+    }>;
+    /** Opaque cursor for the next page, or `null` if this was the last page. */
+    nextCursor: string | null;
+}
 interface NoydbAdapter {
+    /**
+     * Optional human-readable adapter name (e.g. 'memory', 'file', 'dynamo').
+     * Used in diagnostic messages and the listPage fallback warning. Adapters
+     * are encouraged to set this so logs are clearer about which backend is
+     * involved when something goes wrong.
+     */
+    name?: string;
     /** Get a single record. Returns null if not found. */
     get(compartment: string, collection: string, id: string): Promise<EncryptedEnvelope | null>;
     /** Put a record. Throws ConflictError if expectedVersion doesn't match. */
@@ -36,6 +59,26 @@ interface NoydbAdapter {
     saveAll(compartment: string, data: CompartmentSnapshot): Promise<void>;
     /** Optional connectivity check for sync engine. */
     ping?(): Promise<boolean>;
+    /**
+     * Optional pagination extension. Adapters that implement `listPage` get
+     * the streaming `Collection.scan()` fast path; adapters that don't are
+     * silently fallen back to a full `loadAll()` + slice (with a one-time
+     * console.warn).
+     *
+     * `cursor` is opaque to the core — each adapter encodes its own paging
+     * state (DynamoDB: base64 LastEvaluatedKey JSON; S3: ContinuationToken;
+     * memory/file/browser: numeric offset of a sorted id list). Pass
+     * `undefined` to start from the beginning.
+     *
+     * `limit` is a soft upper bound on `items.length`. Adapters MAY return
+     * fewer items even when more exist (e.g. if the underlying store has
+     * its own page size cap), and MUST signal "no more pages" by returning
+     * `nextCursor: null`.
+     *
+     * The 6-method core contract is unchanged — this is an additive
+     * extension discovered via `'listPage' in adapter`.
+     */
+    listPage?(compartment: string, collection: string, cursor?: string, limit?: number): Promise<ListPageResult>;
 }
 /** Type-safe helper for creating adapter factories. */
 declare function defineAdapter<TOptions>(factory: (options: TOptions) => NoydbAdapter): (options: TOptions) => NoydbAdapter;
@@ -282,8 +325,394 @@ declare function diff(oldObj: unknown, newObj: unknown, basePath?: string): Diff
 /** Format a diff as a human-readable string. */
 declare function formatDiff(changes: DiffEntry[]): string;
 
+/**
+ * Operator implementations for the query DSL.
+ *
+ * All predicates run client-side, AFTER decryption — they never see ciphertext.
+ * This file is dependency-free and tree-shakeable.
+ */
+/** Comparison operators supported by the where() builder. */
+type Operator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'contains' | 'startsWith' | 'between';
+/**
+ * A single field comparison clause inside a query plan.
+ * Plans are JSON-serializable, so this type uses primitives only.
+ */
+interface FieldClause {
+    readonly type: 'field';
+    readonly field: string;
+    readonly op: Operator;
+    readonly value: unknown;
+}
+/**
+ * A user-supplied predicate function escape hatch. Not serializable.
+ *
+ * The predicate accepts `unknown` at the type level so the surrounding
+ * Clause type can stay non-parametric — this keeps Collection<T> covariant
+ * in T at the public API surface. Builder methods cast user predicates
+ * (typed `(record: T) => boolean`) into this shape on the way in.
+ */
+interface FilterClause {
+    readonly type: 'filter';
+    readonly fn: (record: unknown) => boolean;
+}
+/** A logical group of clauses combined by AND or OR. */
+interface GroupClause {
+    readonly type: 'group';
+    readonly op: 'and' | 'or';
+    readonly clauses: readonly Clause[];
+}
+type Clause = FieldClause | FilterClause | GroupClause;
+/**
+ * Read a possibly nested field path like "address.city" from a record.
+ * Returns undefined if any segment is missing.
+ */
+declare function readPath(record: unknown, path: string): unknown;
+/**
+ * Evaluate a single field clause against a record.
+ * Returns false on type mismatches rather than throwing — query results
+ * exclude non-matching records by definition.
+ */
+declare function evaluateFieldClause(record: unknown, clause: FieldClause): boolean;
+/**
+ * Evaluate any clause (field / filter / group) against a record.
+ * The recursion depth is bounded by the user's query expression — no risk of
+ * blowing the stack on a 50K-record collection.
+ */
+declare function evaluateClause(record: unknown, clause: Clause): boolean;
+
+/**
+ * Secondary indexes for the query DSL.
+ *
+ * v0.3 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 v0.3 PR body — short version: at the v0.3 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.
+ *
+ * Today only single-field hash indexes are supported. Future shapes
+ * (composite, sorted, unique constraints) will land as additive variants
+ * of this discriminated union without breaking existing declarations.
+ */
+type IndexDef = 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.
+ */
+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).
+ */
+declare class CollectionIndexes {
+    private readonly indexes;
+    /**
+     * 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).
+     */
+    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;
+}
+
+/**
+ * Chainable, immutable query builder.
+ *
+ * Each builder operation returns a NEW Query — the underlying plan is never
+ * mutated. This makes plans safe to share, cache, and serialize.
+ */
+
+interface OrderBy {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+/**
+ * A complete query plan: zero-or-more clauses, optional ordering, pagination.
+ * Plans are JSON-serializable as long as no FilterClause is present.
+ *
+ * Plans are intentionally NOT parametric on T — see `predicate.ts` FilterClause
+ * for the variance reasoning. The public `Query<T>` API attaches the type tag.
+ */
+interface QueryPlan {
+    readonly clauses: readonly Clause[];
+    readonly orderBy: readonly OrderBy[];
+    readonly limit: number | undefined;
+    readonly offset: number;
+}
+/**
+ * Source of records that a query executes against.
+ *
+ * The interface is non-parametric to keep variance friendly: callers cast
+ * their typed source (e.g. `QuerySource<Invoice>`) into this opaque shape.
+ *
+ * `getIndexes` and `lookupById` are optional fast-path hooks. When both are
+ * present and a where clause matches an indexed field, the executor uses
+ * the index to skip a linear scan. Sources without these methods (or with
+ * `getIndexes` returning `null`) always fall back to a linear scan.
+ */
+interface QuerySource<T> {
+    /** Snapshot of all current records. The query never mutates this array. */
+    snapshot(): readonly T[];
+    /** Subscribe to mutations; returns an unsubscribe function. */
+    subscribe?(cb: () => void): () => void;
+    /** Index store for the indexed-fast-path. Optional. */
+    getIndexes?(): CollectionIndexes | null;
+    /** O(1) record lookup by id, used to materialize index hits. */
+    lookupById?(id: string): T | undefined;
+}
+/**
+ * The chainable builder. All methods return a new Query — the original
+ * remains unchanged. Terminal methods (`toArray`, `first`, `count`,
+ * `subscribe`) execute the plan against the source.
+ *
+ * Type parameter T flows through the public API for ergonomics, but the
+ * internal storage uses `unknown` so Collection<T> stays covariant.
+ */
+declare class Query<T> {
+    private readonly source;
+    private readonly plan;
+    constructor(source: QuerySource<T>, plan?: QueryPlan);
+    /** Add a field comparison. Multiple where() calls are AND-combined. */
+    where(field: string, op: Operator, value: unknown): Query<T>;
+    /**
+     * Logical OR group. Pass a callback that builds a sub-query.
+     * Each clause inside the callback is OR-combined; the group itself
+     * joins the parent plan with AND.
+     */
+    or(builder: (q: Query<T>) => Query<T>): Query<T>;
+    /**
+     * Logical AND group. Same shape as `or()` but every clause inside the group
+     * must match. Useful for explicit grouping inside a larger OR.
+     */
+    and(builder: (q: Query<T>) => Query<T>): Query<T>;
+    /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+    filter(fn: (record: T) => boolean): Query<T>;
+    /** Sort by a field. Subsequent calls are tie-breakers. */
+    orderBy(field: string, direction?: 'asc' | 'desc'): Query<T>;
+    /** Cap the result size. */
+    limit(n: number): Query<T>;
+    /** Skip the first N matching records (after ordering). */
+    offset(n: number): Query<T>;
+    /** Execute the plan and return the matching records. */
+    toArray(): T[];
+    /** Return the first matching record, or null. */
+    first(): T | null;
+    /** Return the number of matching records (after where/filter, before limit). */
+    count(): number;
+    /**
+     * Re-run the query whenever the source notifies of changes.
+     * Returns an unsubscribe function. The callback receives the latest result.
+     * Throws if the source does not support subscriptions.
+     */
+    subscribe(cb: (result: T[]) => void): () => void;
+    /**
+     * Return the plan as a JSON-friendly object. FilterClause entries are
+     * stripped (their `fn` cannot be serialized) and replaced with
+     * { type: 'filter', fn: '[function]' } so devtools can still see them.
+     */
+    toPlan(): unknown;
+}
+/**
+ * Execute a plan against a snapshot of records.
+ * Pure function — same input, same output, no side effects.
+ *
+ * Records are typed as `unknown` because plans are non-parametric; callers
+ * cast the return type at the API surface (see `Query.toArray()`).
+ */
+declare function executePlan(records: readonly unknown[], plan: QueryPlan): unknown[];
+
+interface LruOptions {
+    /** Maximum number of entries before eviction. Required if `maxBytes` is unset. */
+    maxRecords?: number;
+    /** Maximum total bytes before eviction. Computed from per-entry `size`. */
+    maxBytes?: number;
+}
+interface LruStats {
+    /** Total cache hits since construction (or `resetStats()`). */
+    hits: number;
+    /** Total cache misses since construction (or `resetStats()`). */
+    misses: number;
+    /** Total entries evicted since construction (or `resetStats()`). */
+    evictions: number;
+    /** Current number of cached entries. */
+    size: number;
+    /** Current sum of cached entry sizes (in bytes, approximate). */
+    bytes: number;
+}
+/**
+ * O(1) LRU cache. Both `get()` and `set()` promote the touched entry to
+ * the most-recently-used end. Eviction happens after every insert and
+ * walks the front of the Map iterator dropping entries until both
+ * budgets are satisfied.
+ */
+declare class Lru<K, V> {
+    private readonly entries;
+    private readonly maxRecords;
+    private readonly maxBytes;
+    private currentBytes;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(options: LruOptions);
+    /**
+     * Look up a key. Hits promote the entry to most-recently-used; misses
+     * return undefined. Both update the running stats counters.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Insert or update a key. If the key already exists, its size is
+     * accounted for and the entry is promoted to MRU. After insertion,
+     * eviction runs to maintain both budgets.
+     */
+    set(key: K, value: V, size: number): void;
+    /**
+     * Remove a key without affecting hit/miss stats. Used by `Collection.delete()`.
+     * Returns true if the key was present.
+     */
+    remove(key: K): boolean;
+    /** True if the cache currently holds an entry for the given key. */
+    has(key: K): boolean;
+    /**
+     * Drop every entry. Stats counters survive — call `resetStats()` if you
+     * want a clean slate. Used by `Collection.invalidate()` on key rotation.
+     */
+    clear(): void;
+    /** Reset hit/miss/eviction counters to zero. Does NOT touch entries. */
+    resetStats(): void;
+    /** Snapshot of current cache statistics. Cheap — no copying. */
+    stats(): LruStats;
+    /**
+     * Iterate over all currently-cached values. Order is least-recently-used
+     * first. Used by tests and devtools — production callers should use
+     * `Collection.scan()` instead.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Walk the cache from the LRU end and drop entries until both budgets
+     * are satisfied. Called after every `set()`. Single pass — entries are
+     * never re-promoted during eviction.
+     */
+    private evictUntilUnderBudget;
+    private overBudget;
+}
+
+/**
+ * Cache policy helpers — parse human-friendly byte budgets into raw numbers.
+ *
+ * Accepted shapes (case-insensitive on suffix):
+ *   number       — interpreted as raw bytes
+ *   '1024'       — string of digits, raw bytes
+ *   '50KB'       — kilobytes (×1024)
+ *   '50MB'       — megabytes (×1024²)
+ *   '1GB'        — gigabytes (×1024³)
+ *
+ * Decimals are accepted (`'1.5GB'` → 1610612736 bytes).
+ *
+ * Anything else throws — better to fail loud at construction time than
+ * to silently treat a typo as 0 bytes (which would evict everything).
+ */
+/** Parse a byte budget into a positive integer number of bytes. */
+declare function parseBytes(input: number | string): number;
+/**
+ * Estimate the in-memory byte size of a decrypted record.
+ *
+ * Uses `JSON.stringify().length` as a stand-in for actual heap usage.
+ * It's a deliberate approximation: real V8 heap size includes pointer
+ * overhead, hidden classes, and string interning that we can't measure
+ * from JavaScript. The JSON length is a stable, monotonic proxy that
+ * costs O(record size) per insert — fine when records are typically
+ * < 1 KB and the cache eviction is the slow path anyway.
+ *
+ * Returns `0` (and the caller must treat it as 1 for accounting) if
+ * stringification throws on circular references; this is documented
+ * but in practice records always come from JSON-decoded envelopes.
+ */
+declare function estimateRecordBytes(record: unknown): number;
+
 /** Callback for dirty tracking (sync engine integration). */
 type OnDirtyCallback = (collection: string, id: string, action: 'put' | 'delete', version: number) => Promise<void>;
+/**
+ * Per-collection cache configuration. Only meaningful when paired with
+ * `prefetch: false` (lazy mode); eager mode keeps the entire decrypted
+ * cache in memory and ignores these bounds.
+ */
+interface CacheOptions {
+    /** Maximum number of records to keep in memory before LRU eviction. */
+    maxRecords?: number;
+    /**
+     * Maximum total decrypted byte size before LRU eviction. Accepts a raw
+     * number or a human-friendly string: `'50KB'`, `'50MB'`, `'1GB'`.
+     * Eviction picks the least-recently-used entry until both budgets
+     * (maxRecords AND maxBytes, if both are set) are satisfied.
+     */
+    maxBytes?: number | string;
+}
+/** Statistics exposed via `Collection.cacheStats()`. */
+interface CacheStats extends LruStats {
+    /** True if this collection is in lazy mode. */
+    lazy: boolean;
+}
 /** A typed collection of records within a compartment. */
 declare class Collection<T> {
     private readonly adapter;
@@ -297,6 +726,36 @@ declare class Collection<T> {
     private readonly historyConfig;
     private readonly cache;
     private hydrated;
+    /**
+     * Lazy mode flag. `true` when constructed with `prefetch: false`.
+     * In lazy mode the cache is bounded by an LRU and `list()`/`query()`
+     * throw — callers must use `scan()` or per-id `get()` instead.
+     */
+    private readonly lazy;
+    /**
+     * LRU cache for lazy mode. Only allocated when `prefetch: false` is set.
+     * Stores `{ record, version }` entries the same shape as `this.cache`.
+     * Tree-shaking note: importing Collection without setting `prefetch:false`
+     * still pulls in the Lru class today; future bundle-size work could
+     * lazy-import the cache module.
+     */
+    private readonly lru;
+    /**
+     * In-memory secondary indexes for the query DSL.
+     *
+     * Built during `ensureHydrated()` and maintained on every put/delete.
+     * The query executor consults these for `==` and `in` operators on
+     * indexed fields, falling back to a linear scan for unindexed fields
+     * or unsupported operators.
+     *
+     * v0.3 ships in-memory only — persistence as encrypted blobs is a
+     * follow-up. See `query/indexes.ts` for the design rationale.
+     *
+     * Indexes are INCOMPATIBLE with lazy mode in v0.3 — the constructor
+     * rejects the combination because evicted records would silently
+     * disappear from the index without notification.
+     */
+    private readonly indexes;
     constructor(opts: {
         adapter: NoydbAdapter;
         compartment: string;
@@ -307,6 +766,19 @@ declare class Collection<T> {
         getDEK: (collectionName: string) => Promise<CryptoKey>;
         historyConfig?: HistoryConfig | undefined;
         onDirty?: OnDirtyCallback | undefined;
+        indexes?: IndexDef[] | undefined;
+        /**
+         * Hydration mode. `'eager'` (default) loads everything into memory on
+         * first access — matches v0.2 behavior exactly. `'lazy'` defers loads
+         * to per-id `get()` calls and bounds memory via the `cache` option.
+         */
+        prefetch?: boolean;
+        /**
+         * LRU cache options. Only meaningful when `prefetch: false`. At least
+         * one of `maxRecords` or `maxBytes` must be set in lazy mode — an
+         * unbounded lazy cache defeats the purpose.
+         */
+        cache?: CacheOptions | undefined;
     });
     /** Get a single record by ID. Returns null if not found. */
     get(id: string): Promise<T | null>;
@@ -314,10 +786,46 @@ declare class Collection<T> {
     put(id: string, record: T): Promise<void>;
     /** Delete a record by ID. */
     delete(id: string): Promise<void>;
-    /** List all records in the collection. */
+    /**
+     * List all records in the collection.
+     *
+     * Throws in lazy mode — bulk listing defeats the purpose of lazy
+     * hydration. Use `scan()` to iterate over the full collection
+     * page-by-page without holding more than `pageSize` records in memory.
+     */
     list(): Promise<T[]>;
-    /** Filter records by a predicate. */
+    /**
+     * Build a chainable query against the collection. Returns a `Query<T>`
+     * builder when called with no arguments.
+     *
+     * Backward-compatible overload: passing a predicate function returns
+     * the filtered records directly (the v0.2 API). Prefer the chainable
+     * form for new code.
+     *
+     * @example
+     * ```ts
+     * // New chainable API:
+     * const overdue = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .where('dueDate', '<', new Date())
+     *   .orderBy('dueDate')
+     *   .toArray();
+     *
+     * // Legacy predicate form (still supported):
+     * const drafts = invoices.query(i => i.status === 'draft');
+     * ```
+     */
+    query(): Query<T>;
     query(predicate: (record: T) => boolean): T[];
+    /**
+     * Cache statistics — useful for devtools, monitoring, and verifying
+     * that LRU eviction is happening as expected in lazy mode.
+     *
+     * In eager mode, returns size only (no hits/misses are tracked because
+     * every read is a cache hit by construction). In lazy mode, returns
+     * the full LRU stats: `{ hits, misses, evictions, size, bytes }`.
+     */
+    cacheStats(): CacheStats;
     /** Get version history for a record, newest first. */
     history(id: string, options?: HistoryOptions): Promise<HistoryEntry<T>[]>;
     /** Get a specific past version of a record. */
@@ -337,12 +845,77 @@ declare class Collection<T> {
     pruneRecordHistory(id: string | undefined, options: PruneOptions): Promise<number>;
     /** Clear all history for this collection (or a specific record). */
     clearHistory(id?: string): Promise<number>;
-    /** Count records in the collection. */
+    /**
+     * Count records in the collection.
+     *
+     * In eager mode this returns the in-memory cache size (instant). In
+     * lazy mode it asks the adapter via `list()` to enumerate ids — slower
+     * but still correct, and avoids loading any record bodies into memory.
+     */
     count(): Promise<number>;
+    /**
+     * Fetch a single page of records via the adapter's optional `listPage`
+     * extension. Returns the decrypted records for this page plus an opaque
+     * cursor for the next page.
+     *
+     * Pass `cursor: undefined` (or omit it) to start from the beginning.
+     * The final page returns `nextCursor: null`.
+     *
+     * If the adapter does NOT implement `listPage`, this falls back to a
+     * synthetic implementation: it loads all ids via `list()`, sorts them,
+     * and slices a window. The first call emits a one-time console.warn so
+     * developers can spot adapters that should opt into the fast path.
+     */
+    listPage(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Stream every record in the collection page-by-page, yielding decrypted
+     * records as an `AsyncIterable<T>`. The whole point: process collections
+     * larger than RAM without ever holding more than `pageSize` records
+     * decrypted at once.
+     *
+     * @example
+     * ```ts
+     * for await (const record of invoices.scan({ pageSize: 500 })) {
+     *   await processOne(record)
+     * }
+     * ```
+     *
+     * Uses `adapter.listPage` when available; otherwise falls back to the
+     * synthetic pagination path with the same one-time warning.
+     */
+    scan(opts?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+    /** Decrypt a page of envelopes returned by `adapter.listPage`. */
+    private decryptPage;
     /** Load all records from adapter into memory cache. */
     private ensureHydrated;
     /** Hydrate from a pre-loaded snapshot (used by Compartment). */
     hydrateFromSnapshot(records: Record<string, EncryptedEnvelope>): Promise<void>;
+    /**
+     * Rebuild secondary indexes from the current in-memory cache.
+     *
+     * Called after any bulk hydration. Incremental put/delete updates
+     * are handled by `indexes.upsert()` / `indexes.remove()` directly,
+     * so this only fires for full reloads.
+     *
+     * Synchronous and O(N × indexes.size); for the v0.3 target scale of
+     * 1K–50K records this completes in single-digit milliseconds.
+     */
+    private rebuildIndexes;
+    /**
+     * Get the in-memory index store. Used by `Query` to short-circuit
+     * `==` and `in` lookups when an index covers the where clause.
+     *
+     * Returns `null` if no indexes are declared on this collection.
+     */
+    getIndexes(): CollectionIndexes | null;
     /** Get all records as encrypted envelopes (for dump). */
     dumpEnvelopes(): Promise<Record<string, EncryptedEnvelope>>;
     private encryptRecord;
@@ -369,8 +942,26 @@ declare class Compartment {
         onDirty?: OnDirtyCallback | undefined;
         historyConfig?: HistoryConfig | undefined;
     });
-    /** Open a typed collection within this compartment. */
-    collection<T>(collectionName: string): Collection<T>;
+    /**
+     * Open a typed collection within this compartment.
+     *
+     * - `options.indexes` declares secondary indexes for the query DSL.
+     *   Indexes are computed in memory after decryption; adapters never
+     *   see plaintext index data.
+     * - `options.prefetch` (default `true`) controls hydration. Eager mode
+     *   loads everything on first access; lazy mode (`prefetch: false`)
+     *   loads records on demand and bounds memory via the LRU cache.
+     * - `options.cache` configures the LRU bounds. Required in lazy mode.
+     *   Accepts `{ maxRecords, maxBytes: '50MB' | 1024 }`.
+     *
+     * Lazy mode + indexes is rejected at construction time — see the
+     * Collection constructor for the rationale.
+     */
+    collection<T>(collectionName: string, options?: {
+        indexes?: IndexDef[];
+        prefetch?: boolean;
+        cache?: CacheOptions;
+    }): Collection<T>;
     /** List all collection names in this compartment. */
     collections(): Promise<string[]>;
     /** Dump compartment as encrypted JSON backup string. */
@@ -523,4 +1114,4 @@ declare function validatePassphrase(passphrase: string): void;
  */
 declare function estimateEntropy(passphrase: string): number;
 
-export { type BiometricCredential, type ChangeEvent, type ChangeType, Collection, Compartment, type CompartmentBackup, type CompartmentSnapshot, type Conflict, ConflictError, type ConflictStrategy, DecryptionError, type DiffEntry, type DirtyEntry, type EncryptedEnvelope, type GrantOptions, type HistoryConfig, type HistoryEntry, type HistoryOptions, InvalidKeyError, type KeyringFile, NOYDB_BACKUP_VERSION, NOYDB_FORMAT_VERSION, NOYDB_KEYRING_VERSION, NOYDB_SYNC_VERSION, NetworkError, NoAccessError, NotFoundError, Noydb, type NoydbAdapter, NoydbError, type NoydbEventMap, type NoydbOptions, type Permission, PermissionDeniedError, type Permissions, type PruneOptions, type PullResult, type PushResult, ReadOnlyError, type RevokeOptions, type Role, SyncEngine, type SyncMetadata, type SyncStatus, TamperedError, type UserInfo, ValidationError, createNoydb, defineAdapter, diff, enrollBiometric, estimateEntropy, formatDiff, isBiometricAvailable, loadBiometric, removeBiometric, saveBiometric, unlockBiometric, validatePassphrase };
+export { type BiometricCredential, type CacheOptions, type CacheStats, type ChangeEvent, type ChangeType, type Clause, Collection, CollectionIndexes, Compartment, type CompartmentBackup, type CompartmentSnapshot, type Conflict, ConflictError, type ConflictStrategy, DecryptionError, type DiffEntry, type DirtyEntry, type EncryptedEnvelope, type FieldClause, type FilterClause, type GrantOptions, type GroupClause, type HashIndex, type HistoryConfig, type HistoryEntry, type HistoryOptions, type IndexDef, InvalidKeyError, type KeyringFile, type ListPageResult, Lru, type LruOptions, type LruStats, NOYDB_BACKUP_VERSION, NOYDB_FORMAT_VERSION, NOYDB_KEYRING_VERSION, NOYDB_SYNC_VERSION, NetworkError, NoAccessError, NotFoundError, Noydb, type NoydbAdapter, NoydbError, type NoydbEventMap, type NoydbOptions, type Operator, type OrderBy, type Permission, PermissionDeniedError, type Permissions, type PruneOptions, type PullResult, type PushResult, Query, type QueryPlan, type QuerySource, ReadOnlyError, type RevokeOptions, type Role, SyncEngine, type SyncMetadata, type SyncStatus, TamperedError, type UserInfo, ValidationError, createNoydb, defineAdapter, diff, enrollBiometric, estimateEntropy, estimateRecordBytes, evaluateClause, evaluateFieldClause, executePlan, formatDiff, isBiometricAvailable, loadBiometric, parseBytes, readPath, removeBiometric, saveBiometric, unlockBiometric, validatePassphrase };