@noy-db/hub 0.1.0-pre.3

package/dist/lazy-builder-BwEoBQZ9.d.ts

@@ -0,0 +1,304 @@
+import { I as IndexDef, C as CollectionIndexes, F as FieldClause, O as Operator } from './predicate-SBHmi6D0.js';
+
+/**
+ * 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.
+ */
+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.
+ */
+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)
+ */
+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.
+ */
+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)`.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare const COMPOSITE_DELIMITER = "|";
+declare function compositeKey(fields: readonly string[]): string;
+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 (#275: 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;
+}
+
+/**
+ * Strategy seam between core Collection and the optional indexing
+ * subsystem. 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
+ */
+
+/**
+ * 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
+ */
+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
+ */
+interface IndexStrategy {
+    createState(args: {
+        readonly defs: readonly IndexDef[];
+        readonly lazy: boolean;
+    }): IndexState;
+}
+
+/**
+ * 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).
+ */
+
+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.
+ */
+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;
+}
+declare class LazyQuery<T> {
+    private readonly source;
+    private readonly plan;
+    constructor(source: LazyQuerySource<T>, plan?: LazyPlan);
+    where<V>(field: string, op: Operator, value: V): LazyQuery<T>;
+    orderBy(field: string, direction?: 'asc' | 'desc'): LazyQuery<T>;
+    limit(n: number): LazyQuery<T>;
+    offset(n: number): LazyQuery<T>;
+    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 { COMPOSITE_DELIMITER as C, type IndexStrategy as I, type LazyOrderBy as L, type OrderedEntry as O, PersistedCollectionIndex as P, IDX_PREFIX as a, type IndexState as b, type IngestRow as c, LazyQuery as d, type LazyQuerySource as e, type PersistedIndexDef as f, compositeKey as g, decodeIdxId as h, encodeIdxId as i, isIdxId as j };

package/dist/lazy-builder-CZVLKh0Z.d.cts

@@ -0,0 +1,304 @@
+import { I as IndexDef, C as CollectionIndexes, F as FieldClause, O as Operator } from './predicate-SBHmi6D0.cjs';
+
+/**
+ * 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.
+ */
+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.
+ */
+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)
+ */
+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.
+ */
+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)`.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare const COMPOSITE_DELIMITER = "|";
+declare function compositeKey(fields: readonly string[]): string;
+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 (#275: 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;
+}
+
+/**
+ * Strategy seam between core Collection and the optional indexing
+ * subsystem. 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
+ */
+
+/**
+ * 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
+ */
+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
+ */
+interface IndexStrategy {
+    createState(args: {
+        readonly defs: readonly IndexDef[];
+        readonly lazy: boolean;
+    }): IndexState;
+}
+
+/**
+ * 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).
+ */
+
+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.
+ */
+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;
+}
+declare class LazyQuery<T> {
+    private readonly source;
+    private readonly plan;
+    constructor(source: LazyQuerySource<T>, plan?: LazyPlan);
+    where<V>(field: string, op: Operator, value: V): LazyQuery<T>;
+    orderBy(field: string, direction?: 'asc' | 'desc'): LazyQuery<T>;
+    limit(n: number): LazyQuery<T>;
+    offset(n: number): LazyQuery<T>;
+    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 { COMPOSITE_DELIMITER as C, type IndexStrategy as I, type LazyOrderBy as L, type OrderedEntry as O, PersistedCollectionIndex as P, IDX_PREFIX as a, type IndexState as b, type IngestRow as c, LazyQuery as d, type LazyQuerySource as e, type PersistedIndexDef as f, compositeKey as g, decodeIdxId as h, encodeIdxId as i, isIdxId as j };

package/dist/ledger-2NX4L7PN.js

@@ -0,0 +1,33 @@
+import "./chunk-UF3BUNQZ.js";
+import {
+  LEDGER_COLLECTION,
+  LEDGER_DELTAS_COLLECTION,
+  LedgerStore,
+  applyPatch,
+  computePatch
+} from "./chunk-XHFOENR2.js";
+import {
+  canonicalJson,
+  envelopePayloadHash,
+  hashEntry,
+  paddedIndex,
+  parseIndex,
+  sha256Hex
+} from "./chunk-CIMZBAZB.js";
+import "./chunk-ZRG4V3F5.js";
+import "./chunk-MR4424N3.js";
+import "./chunk-ACLDOTNQ.js";
+export {
+  LEDGER_COLLECTION,
+  LEDGER_DELTAS_COLLECTION,
+  LedgerStore,
+  applyPatch,
+  canonicalJson,
+  computePatch,
+  envelopePayloadHash,
+  hashEntry,
+  paddedIndex,
+  parseIndex,
+  sha256Hex
+};
+//# sourceMappingURL=ledger-2NX4L7PN.js.map

package/dist/ledger-2NX4L7PN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}