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

package/dist/with-lookup/embeddings/vec-id.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Collection-namespaced `_vec` side-car ids (#726).
+ *
+ * `_vec` embedding side-cars used to be keyed by the bare record id,
+ * vault-wide — two collections sharing a record id shared one `_vec` row.
+ * This was verified to be a clobber/crash bug, NOT a confidentiality leak:
+ * every collection has its own DEK, and AES-GCM auth-tag verification means
+ * decrypting a foreign collection's `_vec` row under the wrong DEK throws
+ * `TamperedError` rather than returning wrong plaintext — no disclosure
+ * mechanism exists. The real bug was id collision: a same-id write/forget in
+ * one collection could clobber or delete the other collection's row, and a
+ * collection whose `similarTo()` / cold semantic `retrieve()` encountered a
+ * foreign same-id row crashed with an uncaught `TamperedError` (a DoS). The
+ * store-collection bucket stays the literal `'_vec'`; the id becomes
+ * composite: `${collection}/${recordId}`. Mirrors `encodeIdxId`
+ * (`../indexing/persisted-indexes.js`).
+ *
+ * Decode is deliberately NOT split-on-`/`: the collection is always known
+ * at the decode site (`ctx.name`), so `decodeVecId` strips that known
+ * prefix — correct even when `recordId` itself contains `/`.
+ *
+ * Precondition: `collection` itself must not contain `/` — otherwise
+ * `${collection}/${recordId}` is ambiguous (e.g. collection `'a'` would
+ * misattribute collection `'a/b'`'s rows via prefix match in `isVecIdFor`).
+ * Collection names are NOT currently restricted to a `/`-free charset by
+ * `vault.collection()`, so `encodeVecId` enforces the precondition itself,
+ * failing loud at the write boundary rather than silently misencoding.
+ */
+/**
+ * Encode the `_vec` side-car id for a (collection, recordId) pair.
+ * Format: `<collection>/<recordId>` — no escaping; `recordId` may contain `/`.
+ *
+ * Throws if `collection` contains `/`: that would make the composite id
+ * ambiguous against `isVecIdFor`'s prefix match (collection `'a'` would
+ * appear to own collection `'a/b'`'s rows), reintroducing the clobber/crash
+ * risk the namespacing fix exists to close.
+ */
+export declare function encodeVecId(collection: string, recordId: string): string;
+/**
+ * Decode a `_vec` id back to the bare record id, given the KNOWN owning
+ * collection — strips the `<collection>/` prefix rather than splitting on
+ * `/`, so a `recordId` containing `/` round-trips correctly. Returns `null`
+ * if `vecId` does not belong to `collection`.
+ */
+export declare function decodeVecId(collection: string, vecId: string): string | null;
+/** Predicate form of {@link decodeVecId} — used to filter `list()` results. */
+export declare function isVecIdFor(collection: string, vecId: string): boolean;

package/dist/with-lookup/embeddings/vector-set.d.ts

@@ -0,0 +1,19 @@
+export interface StoredVector {
+    readonly id: string;
+    readonly vec: Float32Array;
+    readonly model: string;
+}
+export interface VectorHit {
+    readonly id: string;
+    readonly score: number;
+}
+export declare class VectorSet {
+    private vectors;
+    get loaded(): boolean;
+    ensureLoaded(load: () => Promise<StoredVector[]>): Promise<void>;
+    markDirty(): void;
+    cosineTopK(query: Float32Array, k: number, opts?: {
+        minScore?: number;
+        expectModel?: string;
+    }): VectorHit[];
+}

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,157 @@
+/**
+ * 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, EncryptedEnvelope } 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[];
+}>;
+/**
+ * Sync this collection's indexes after a tier move (#709). Persisted
+ * `_idx/<field>/<recordId>` side-cars are always encrypted under the
+ * tier-0 DEK regardless of the record's own tier, and the eager in-memory
+ * `CollectionIndexes` mirror holds plaintext bucket values too — so both
+ * leak an elevated record's indexed field values unless swept the same way
+ * `purgePersistedIndexes` already sweeps them for `forget()` ("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", `purgePersistedIndexes` above).
+ *
+ * `record === null` — the record just left tier 0: purge its persisted
+ * side-cars (content-free, no decrypt needed) and drop its eager-mirror
+ * entry, read from `ctx.cache` (the caller's pre-write value — the caller
+ * MUST invoke this before evicting/overwriting that cache entry, so it
+ * still reflects the value being replaced).
+ *
+ * `record` given — the record is tier-0 again: (re)build its entries from
+ * that record, using the SAME pre-write `ctx.cache` read as the previous
+ * value so a stale bucket (e.g. a same-tier `putAtTier` value change) is
+ * cleaned up rather than left as a false-positive hit. `version` stamps
+ * the rebuilt side-car's own envelope version.
+ *
+ * `priorEnvelope` (#720) — the RAW envelope the caller read BEFORE its own
+ * overwrite landed (`putAtTier`'s `existing` / `demote`'s pre-move
+ * `envelope`), for the `ctx.cache`-miss lazy case: by this call's time the
+ * adapter already holds the NEW envelope, so a `ctx.adapter.get()` here
+ * would only ever re-observe the write just made — useless for recovering
+ * what a same-tier `putAtTier` may have dropped. Optional: the null-record
+ * branches (elevate / demote-to-intermediate / putAtTier(tier>0)) never
+ * need it — their only prior-dependent step, the eager `indexes.remove`
+ * below, already has what it needs from `ctx.cache` (eager mode is
+ * unaffected by the raw-envelope overwrite; lazy mode has no eager mirror).
+ *
+ * No-ops fast when the collection has neither index kind declared.
+ */
+export declare function syncTierIndexes<T>(ctx: IndexingContext<T>, id: string, record: T | null, version: number, priorEnvelope?: EncryptedEnvelope): Promise<void>;

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