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

package/dist/with-lookup/aggregate/reducers.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Aggregation reducers for the query DSL.
+ *
+ * the reducer protocol plus five built-in factories
+ * (`count`, `sum`, `avg`, `min`, `max`) consumed by `Query.aggregate()`
+ * and, in the future, `Scan.aggregate()`. Every factory accepts
+ * an optional `{ seed }` parameter that is plumbed through the
+ * protocol but unused by the executor — that's the load-bearing
+ * half of  constraint #2. When partition-aware aggregation
+ * lands, the seed carries the previous partition's running total into
+ * the next partition without requiring a protocol change.
+ *
+ * Reducers are intentionally generic over their internal state type
+ * `S` so compound reducers (avg keeps `{sum, count}`, min/max keep a
+ * value bag) can model internal bookkeeping without leaking the
+ * implementation through the accumulator's public shape. `finalize`
+ * collapses `S` back into the user-visible `R`.
+ *
+ * Reducers are pure data — `init` / `step` / `finalize` / optional
+ * `remove` are stateless functions that receive and return `S`. This
+ * is the shape that admits O(1) incremental maintenance in a future
+ * optimization (delta-aware `LiveAggregation` applies `step` or
+ * `remove` per delta), without blocking the simpler "full re-run on
+ * source change" that ships.
+ */
+import type { MoneyString } from '../../via/money/branded.js';
+import type { QueryField } from '../../kernel/types.js';
+/**
+ * A single reducer: factory-produced, ready to plug into an
+ * `.aggregate()` spec.
+ *
+ * Type parameters:
+ *   - `R` — user-visible result type (what the aggregation returns
+ *     for this slot, e.g. `number` for `sum()`)
+ *   - `S` — internal state type, defaults to `R` for simple reducers
+ *     that don't need compound bookkeeping
+ *
+ * A reducer is stateless: every method is pure over `S`. `init()` is
+ * called once per aggregation run to build the initial state; `step()`
+ * folds a record into the state; `remove()` (optional) un-folds a
+ * record, enabling incremental live maintenance; `finalize()` reads
+ * the final answer out of the state at the end of the run.
+ */
+export interface Reducer<R, S = R> {
+    /** Build the initial state for a fresh aggregation run. */
+    init(): S;
+    /** Fold a record into the state. Returns the new state. */
+    step(state: S, record: unknown): S;
+    /**
+     * Un-fold a record from the state. Returns the new state.
+     *
+     * Optional — reducers without `remove` cannot be maintained
+     * incrementally and must be re-run from scratch when the underlying
+     * record set changes. `sum`, `count`, `avg` implement `remove` in
+     * O(1); `min` and `max` implement it in O(N) worst case (when the
+     * extremum itself is removed and the next extremum must be
+     * recomputed from the remaining contributing values).
+     */
+    remove?(state: S, record: unknown): S;
+    /** Collapse the internal state into the user-visible result. */
+    finalize(state: S): R;
+    /**
+     * Combine two independent partial states into one (then `finalize` once).
+     * Optional. MUST be associative + commutative with `init()` as identity.
+     * Never merge finalized results — only states. Enables parallel /
+     * hierarchical aggregation (e.g. cross-shard or advisor→firm rollup).
+     */
+    merge?(a: S, b: S): S;
+    /**
+     * Identifying operation tag stamped by each built-in factory.
+     * Used by `summariseAggregateOp` in the introspection walker to
+     * render human-readable aggregate descriptors in `dumpSchema()`.
+     * Optional so third-party custom reducers are unaffected.
+     */
+    readonly op?: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    /**
+     * Field name for field-based reducers (`sum`, `avg`, `min`, `max`).
+     * Absent on `count` which aggregates over record count, not a field.
+     */
+    readonly field?: string;
+    /**
+     * Money-only: target currency for `sum` over a multi-currency money
+     * field. Consumed by `wrapMoneyReducers` to convert per-currency
+     * subtotals to one figure. Ignored for non-money fields.
+     */
+    readonly convertTo?: string;
+    /**
+     * Money-only: FX rate map (`'USD->EUR' → rate`) used with `convertTo`.
+     */
+    readonly fx?: Record<string, number | string>;
+}
+/**
+ * Common options accepted by every reducer factory.
+ *
+ * `seed` — optional initial value for the internal state. **Unused by
+ * the executor**, plumbed through the protocol for  constraint
+ * #2 (partition-aware aggregation seam). In, partitioned
+ * aggregations will pass the previous partition's carry as `seed` so
+ * a long time series can be rolled forward one partition at a time
+ * without re-aggregating closed partitions.
+ *
+ * always uses `init()` with the factory's zero value, regardless
+ * of whether `seed` was passed. Do not remove the parameter — that's
+ * the whole point of having it exist now.
+ */
+export interface ReducerOptions<TSeed = unknown> {
+    /**  constraint #2 — seed is plumbed through but unused in. */
+    readonly seed?: TSeed;
+    /**
+     * Money-only (honored by `sum` over a multi-currency money field):
+     * convert per-currency subtotals to this currency for a single figure.
+     */
+    readonly convertTo?: string;
+    /** Money-only: FX rate map (`'USD->EUR' → rate`) used with `convertTo`. */
+    readonly fx?: Record<string, number | string>;
+}
+/**
+ * Count the number of records that match the query. Ignores field
+ * values entirely — the count is over the number of records, not over
+ * the number of non-null field values in any column.
+ */
+export declare function count(opts?: ReducerOptions<number>): Reducer<number>;
+/**
+ * Sum a numeric field across all matching records. Non-number values
+ * at the field path are coerced to 0 — consumers who want a different
+ * behavior (throw, skip, treat as NaN) should filter upstream via
+ * `.where()` or write a custom reducer.
+ *
+ * KNOWN LIMITATION (type imprecision): the declared result type is `number`,
+ * but when `field` is a **money** field the runtime returns a decimal *string*
+ * (e.g. `'0.30'`, or `{ EUR: '0.30' }` in multi-currency mode) — money sums are
+ * BigInt-exact in scaled space and never collapse to a float. The `number` type
+ * is therefore a lie for money fields; narrow the result yourself at the call
+ * site. A precise fix requires threading money-field declarations into the type
+ * system (tracked separately).
+ */
+export declare function sum(field: string, opts?: ReducerOptions<number>): Reducer<number>;
+/**
+ * Arithmetic mean of a numeric field across all matching records.
+ *
+ * Returns `null` for an empty result set (zero records is not a
+ * well-defined denominator — returning NaN would poison downstream
+ * arithmetic, and throwing would force every consumer to wrap in
+ * try/catch just to handle "no matches"). Consumers who want an
+ * explicit zero should coalesce with `?? 0`.
+ *
+ * Internal state is `{sum, count}` so the running average can be
+ * maintained incrementally — on each delta, both fields update in
+ * O(1) and `finalize` divides. Directly storing `avg` as state would
+ * not admit incremental removal without also tracking count.
+ */
+export declare function avg(field: string, opts?: ReducerOptions<{
+    sum: number;
+    count: number;
+}>): Reducer<number | null, {
+    sum: number;
+    count: number;
+}>;
+interface MinMaxState {
+    /**
+     * Multiset of contributing field values. Stored as a plain array
+     * because we need to support `remove` and a plain array gives us
+     * O(1) push + O(N) worst-case removal — which matches the
+     * documented min/max removal complexity. A sorted structure would
+     * let us drop the O(N) rescan but adds complexity that doesn't
+     * need; consumers hitting the O(N) ceiling should file an issue.
+     */
+    readonly values: number[];
+}
+/**
+ * Smallest numeric value of a field across all matching records.
+ * Returns `null` for an empty result set. See `avg()` for the
+ * reasoning on `null` vs NaN vs throwing.
+ *
+ * Incremental complexity: O(1) for `step`, O(N) worst case for
+ * `remove` when the current minimum is removed (the state holds the
+ * full multiset of contributing values and `finalize` scans for the
+ * new minimum). Consumers with very large result sets and frequent
+ * removals of the current extremum should either accept the cost or
+ * wait for a future optimization.
+ */
+export declare function min(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
+/**
+ * Largest numeric value of a field across all matching records.
+ * Mirror of `min()` — see that doc for semantics, null-on-empty
+ * behavior, and the O(N) removal caveat.
+ */
+export declare function max(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
+/**
+ * `sum()` for a **declared money field**, typed to match the runtime.
+ *
+ * `sum()` returns `Reducer<number>`, but `wrapMoneyReducers` (applied at
+ * `query.aggregate()` time, once `moneyFields` is known) rewrites any
+ * `sum`/`min`/`max` over a money field to a money reducer that finalizes to a
+ * `MoneyString` decimal — so the `number` type is a lie for money fields and
+ * consumers need a cast at every read site. `moneySum` is the same reducer with
+ * the correct `Reducer<MoneyString>` return type, so no read-site cast is
+ * needed. It is the caller's assertion that `field` is a money field; use plain
+ * `sum()` for non-money fields. (For a multi-currency money field WITHOUT
+ * `convertTo`, the runtime returns a per-currency `Record<string, MoneyString>`
+ * rather than a single `MoneyString` — pass `convertTo` to collapse to one
+ * currency, or read the map at the boundary.)
+ */
+export declare function moneySum(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString>;
+/**
+ * `min()` for a declared money field, typed `Reducer<MoneyString | null>`
+ * (null on an empty result set in fixed-currency mode, mirroring `min()`). See
+ * {@link moneySum} for the late-binding rewrite. Note: `convertTo`/`fx` on
+ * `opts` have no effect on min/max (cross-currency min/max is unsupported — use
+ * {@link moneySum} for currency conversion). In multi-currency mode the runtime
+ * returns a per-currency map and an empty result is `{}` rather than `null`.
+ */
+export declare function moneyMin(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+/**
+ * `max()` for a declared money field, typed `Reducer<MoneyString | null>`
+ * (null on an empty result set in fixed-currency mode, mirroring `max()`). See
+ * {@link moneyMin} for the `convertTo`/`fx` and multi-currency caveats.
+ */
+export declare function moneyMax(field: string, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+/**
+ * Typed builder passed to the `aggregate(b => spec)` overload.
+ *
+ * Each field-taking method narrows `field` to `QueryField<T, S>`, which
+ * excludes any field listed in the collection's `sensitive` option at
+ * compile time. `count()` carries no field argument and is always allowed.
+ *
+ * The type parameters match the `Query<T, S>` they come from:
+ *   - `T` — the record type of the collection
+ *   - `S` — the union of sensitive field keys (defaults to `never`)
+ *
+ * ONE shared runtime instance (`reducerBuilder`) serves all `T`/`S`
+ * combinations — the field narrowing is type-only; the methods delegate
+ * directly to the standalone factories.
+ */
+export interface ReducerBuilder<T, S extends keyof T = never, M extends keyof T & string = never> {
+    count(opts?: ReducerOptions<number>): Reducer<number>;
+    sum<F extends QueryField<T, S>>(field: F, opts?: ReducerOptions<number>): [F] extends [M] ? Reducer<MoneyString> : Reducer<number>;
+    avg(field: QueryField<T, S>, opts?: ReducerOptions<{
+        sum: number;
+        count: number;
+    }>): ReturnType<typeof avg>;
+    min<F extends QueryField<T, S>>(field: F, opts?: ReducerOptions<number>): [F] extends [M] ? Reducer<MoneyString | null> : ReturnType<typeof min>;
+    max<F extends QueryField<T, S>>(field: F, opts?: ReducerOptions<number>): [F] extends [M] ? Reducer<MoneyString | null> : ReturnType<typeof max>;
+    moneySum(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<MoneyString>;
+    moneyMin(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+    moneyMax(field: QueryField<T, S>, opts?: ReducerOptions<number>): Reducer<MoneyString | null>;
+}
+/**
+ * Shared runtime instance for the `aggregate(b => spec)` builder form.
+ *
+ * The field-narrowing to `QueryField<T, S>` is type-only — each method
+ * delegates directly to its standalone factory. A `(field: string) => R`
+ * factory is assignable to a `(field: QueryField<T,S>) => R` method by
+ * parameter-contravariance, so this single instance works for all `T`/`S`.
+ */
+export declare const reducerBuilder: ReducerBuilder<Record<string, unknown>>;
+export {};

package/dist/with-lookup/aggregate/strategy.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Strategy seam between the core Query / ScanBuilder chain and the
+ * optional aggregate / groupBy service. Core imports
+ * `AggregateStrategy` as a TYPE-ONLY symbol and `NO_AGGREGATE` as a
+ * tiny runtime stub.
+ *
+ * The heavy machinery — `Aggregation`, `GroupedQuery`, the
+ * reducer-step logic — is only reachable from `withAggregate()` in
+ * `./active.ts`, which is only exported through the
+ * `@noy-db/hub/aggregate` subpath. Consumers that don't import the
+ * subpath ship none of the ~886 LOC.
+ *
+ * @internal
+ */
+import type { Aggregation, AggregateSpec, AggregateResult, AggregationUpstream } from './aggregation.js';
+import type { GroupedQuery, GroupedQueryN } from './groupby.js';
+import type { ViaPipeline } from '../../kernel/via/pipeline.js';
+/**
+ * Seam interface. `@internal` — will promote to public only when the
+ * aggregate service is extracted into its own package.
+ *
+ * @internal
+ */
+export interface AggregateStrategy {
+    /**
+     * Build an `Aggregation<R>` for `Query.aggregate(spec)`. `executeRecords`
+     * is a closure that produces the matching record set when the
+     * aggregation runs. NO_AGGREGATE throws; the active strategy
+     * constructs a real `Aggregation`.
+     */
+    aggregate<Spec extends AggregateSpec>(executeRecords: () => readonly unknown[], spec: Spec, upstreams: readonly AggregationUpstream[]): Aggregation<AggregateResult<Spec>>;
+    /**
+     * Build a `GroupedQuery<T, F, S>` for `Query.groupBy(field)`. Same
+     * closure / upstream inputs as `aggregate` plus the group key field.
+     */
+    groupBy<T, F extends string, S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], field: F, upstreams: readonly AggregationUpstream[], dictLabelResolver?: (key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>, via?: ViaPipeline): GroupedQuery<T, F, S, M>;
+    /**
+     * Variadic-keyed sibling — builds a `GroupedQueryN<T, F, S>` for
+     * `Query.groupBy(...fields)`. No dictLabelResolver — `<field>Label`
+     * projection only applies to single-field groupings, which dispatch
+     * through `groupBy` above.
+     */
+    groupByN<T, F extends readonly string[], S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], fields: F, upstreams: readonly AggregationUpstream[], via?: ViaPipeline): GroupedQueryN<T, F, S, M>;
+    /**
+     * Terminal streaming aggregator for `ScanBuilder.aggregate(spec)`.
+     * Takes an async iterable of decrypted records + the spec and
+     * returns the reduced result.
+     */
+    scanAggregate<Spec extends AggregateSpec>(iter: AsyncIterable<unknown>, spec: Spec): Promise<AggregateResult<Spec>>;
+}
+/**
+ * No-aggregate stub. Every `.aggregate()` / `.groupBy()` / streaming
+ * `scan().aggregate()` call throws with a pointer at the subpath. The
+ * real `Aggregation` / `GroupedQuery` classes are never referenced at
+ * runtime, so the bundler drops the ~886 LOC.
+ *
+ * @internal
+ */
+export declare const NO_AGGREGATE: AggregateStrategy;

package/dist/with-lookup/embeddings/cosine.d.ts

@@ -0,0 +1,2 @@
+/** Cosine similarity in [-1,1]; 0 on zero-norm or length mismatch (no NaN). (L2) */
+export declare function cosine(a: Float32Array | number[], b: Float32Array | number[]): number;

package/dist/with-lookup/embeddings/descriptor.d.ts

@@ -0,0 +1,8 @@
+export interface EmbeddingDescriptor {
+    readonly source: string | readonly string[];
+    readonly encode: (text: string) => Promise<Float32Array>;
+    readonly dim: number;
+    readonly model: string;
+}
+/** Concatenate the record's source-field text (skips empties; supports nested/[]-wildcard paths). */
+export declare function embeddingSourceText(record: Record<string, unknown>, source: string | readonly string[]): string;

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

@@ -0,0 +1,4 @@
+export { cosine } from './cosine.js';
+export { embeddingSourceText, type EmbeddingDescriptor } from './descriptor.js';
+export { VectorSet, type StoredVector, type VectorHit } from './vector-set.js';
+export { encodeVecId } from './vec-id.js';

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