@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/with-lookup/indexing/eager-indexes.d.ts

@@ -14,6 +14,9 @@
  * scale of 1K–50K records, building the index during hydrate is free,
  * so persistence buys nothing measurable.
  */
+import { type RangeOperator } from './sorted-indexes.js';
+import { type CompoundRangeProbe } from './compound-indexes.js';
+import { type FieldIndexSnapshot } from './index-snapshot.js';
 /**
  * Index declaration accepted by `Collection`'s constructor.
  *
@@ -30,8 +33,55 @@
  */
 export type IndexDef = string | {
     readonly fields: readonly string[];
+    /**
+     * Enforce that no two records share this field tuple. A MULTI-field
+     * tuple is a COMPOUND unique — uniqueness over the tuple, never over
+     * each component on its own (`['workerId','employerId']` allows one
+     * worker at many employers). Null-distinct: a record with `null` or
+     * `undefined` in any constrained field is exempt.
+     *
+     * ⚠️ **What "unique" means depends on the collection's mode (#1358),
+     * and one of the four cannot promise prevention at all:**
+     *
+     * - eager (default) — prevented, from the in-memory map.
+     * - lazy (`prefetch: false`) — prevented, by a point lookup through the
+     *   persisted `_idx/` mirror. Requires `withIndexing()`.
+     * - tiered (`tiers: [...]`) — prevented across every tier whose DEK the
+     *   writer holds. **A tier the writer cannot read is outside the
+     *   guarantee** — those records are unreadable, so no local check can
+     *   see them, and a duplicate against one is accepted.
+     * - CRDT (`crdt: '...'`) — **NOT prevented.** Uniqueness cannot be
+     *   enforced across concurrent replicas: two replicas that are offline
+     *   from each other can both accept the same value, and no local check
+     *   can prevent that. The write always succeeds and both records are
+     *   kept; the collision is reported on the `unique:violation` event as
+     *   a `UniqueConstraintError`, both when it happens and when a later
+     *   session first sees the two records together. What you get is
+     *   uniqueness within what this writer could see at write time, plus
+     *   detection when the replicas meet.
+     */
     readonly unique?: boolean;
+    readonly kind?: IndexKind;
+    /**
+     * Persist this index as an encrypted sidecar so a restart reuses it
+     * instead of rebuilding (#1359). Only meaningful with `kind: 'sorted'`
+     * — the hash index is not persisted. OPT-IN until measured: at the
+     * 1K–50K target scale rebuild-on-open is free, and a sidecar is a
+     * write on every debounce window plus a blob at rest.
+     */
+    readonly persist?: boolean;
 } | readonly string[];
+/**
+ * The access structure an index declaration asks for (#1344).
+ *
+ * `'hash'` (the default, and what every pre-#1344 declaration means) is
+ * the equality/`in` bucket map. `'sorted'` additionally maintains an
+ * ordered array over the same canonicalized keys, which lights up
+ * index-driven `<`, `<=`, `>`, `>=`, `between`, `startsWith` and
+ * `orderBy(field).limit(n)`. A `'sorted'` declaration keeps the hash
+ * index too — `==`/`in` stay O(1).
+ */
+export type IndexKind = 'hash' | 'sorted';
 /**
  * Normalize a declared `IndexDef[]` into a uniform `{ fields, unique? }`
  * shape: `string` → `{fields:[s]}`, `string[]` → `{fields}`, object →
@@ -66,6 +116,27 @@ export interface HashIndex {
  */
 export declare class CollectionIndexes {
     private readonly indexes;
+    /**
+     * Sorted (range) indexes, keyed by field — the #1344 half. Parallel to
+     * `indexes` above and maintained at the SAME mutation sites, through the
+     * SAME `canonicalize` closure, so the two can never disagree about which
+     * key space a field lives in.
+     */
+    private readonly sorted;
+    /**
+     * Compound (tuple-keyed) sorted indexes, keyed by the joined field
+     * tuple — the #1345 half. Third parallel map, maintained at the SAME
+     * mutation sites through the SAME `canonicalize` closure as the other
+     * two, so no field can end up in disagreeing key spaces.
+     */
+    private readonly compound;
+    /**
+     * The indexes declared `persist: true` (#1359), keyed by their SIDECAR key
+     * (`s:<field>` / `c:<f1>,<f2>`). A separate map rather than a flag on the
+     * index classes: persistence is a property of the DECLARATION, and the
+     * index classes stay unaware of storage.
+     */
+    private readonly persistable;
     /**
      * Per-field bucket-key canonicalizer (#672 review C1), registered ONCE
      * via {@link setCanonicalizer} when the collection wires indexing up
@@ -87,6 +158,65 @@ export declare class CollectionIndexes {
      * Calling this twice for the same field is a no-op (idempotent).
      */
     declare(field: string): void;
+    /**
+     * Declare a sorted (range) index on a field. Independent of
+     * {@link declare} — callers that want both `==` speed and range speed
+     * declare both (which is what `withIndexing()` does for a
+     * `kind: 'sorted'` declaration). Idempotent.
+     */
+    declareSorted(field: string, opts?: {
+        readonly persist?: boolean;
+    }): void;
+    /** True if the given field has a declared SORTED index. */
+    hasSorted(field: string): boolean;
+    /** All sorted-index field names, in declaration order. */
+    sortedFields(): string[];
+    /** Number of entries in a field's sorted index (0 when undeclared). */
+    sortedSize(field: string): number;
+    /**
+     * Range lookup: ids whose `field` satisfies the operator. Returns
+     * `null` when no SORTED index covers the field — the caller falls back
+     * to a linear scan. An empty set means "the index covers this field and
+     * nothing matches", which is authoritative.
+     */
+    lookupRange(field: string, op: RangeOperator, value: unknown): ReadonlySet<string> | null;
+    /**
+     * Ids of every indexed record in `field` order. `null` when no sorted
+     * index covers the field. Records whose value is nullish or has no
+     * order-defined type are absent — compare against {@link sortedSize}
+     * before treating the result as the full collection.
+     */
+    orderedIds(field: string, direction: 'asc' | 'desc'): readonly string[] | null;
+    /**
+     * Declare a compound (multi-field) sorted index over an ordered field
+     * tuple. A tuple shorter than two fields is a single-field sorted index
+     * and is ignored here. Idempotent.
+     */
+    declareCompound(fields: readonly string[], opts?: {
+        readonly persist?: boolean;
+    }): void;
+    /** Every declared field tuple, in declaration order. */
+    compoundTuples(): ReadonlyArray<readonly string[]>;
+    /**
+     * Number of records the tuple's index holds (0 when undeclared). A
+     * record with a nullish or non-orderable component is absent, so a
+     * caller that removes clauses from the plan MUST compare this against
+     * the snapshot size before trusting the result.
+     */
+    compoundSize(fields: readonly string[]): number;
+    /**
+     * Compound lookup: ids whose leading components equal `prefixValues`,
+     * optionally narrowed by a range on the component just past them.
+     * `null` when no compound index covers the tuple, or when an operand
+     * has no order-defined type — the caller falls back to a linear scan.
+     */
+    lookupCompound(fields: readonly string[], prefixValues: readonly unknown[], range?: CompoundRangeProbe): ReadonlySet<string> | null;
+    /**
+     * Ids matching an equality prefix, ordered by the remaining components.
+     * `null` when no compound index covers the tuple or an operand has no
+     * order-defined type. See {@link compoundSize} for the coverage caveat.
+     */
+    compoundOrderedIds(fields: readonly string[], prefixValues: readonly unknown[], direction: 'asc' | 'desc'): readonly string[] | null;
     /** True if the given field has a declared index. */
     has(field: string): boolean;
     /** All declared field names, in declaration order. */
@@ -99,7 +229,17 @@ export declare class CollectionIndexes {
     build<T>(records: ReadonlyArray<{
         id: string;
         record: T;
-    }>): void;
+    }>, skip?: ReadonlySet<string>): void;
+    /** Sidecar keys of every index declared `persist: true`, in declaration order. */
+    persistableKeys(): readonly string[];
+    /** The persistable snapshot behind one sidecar key, or `undefined` if it is not declared. */
+    snapshotIndex(key: string): FieldIndexSnapshot | undefined;
+    /**
+     * Adopt a validated snapshot into the index behind `key`. `false` means the
+     * caller must rebuild that index from the cache — the index is left
+     * untouched, never half-loaded.
+     */
+    restoreIndex(key: string, snap: FieldIndexSnapshot, isLive: (id: string) => boolean): boolean;
     /**
      * Insert or update a single record across all indexes.
      * Called by `Collection.put()` after the encrypted write succeeds.
@@ -120,6 +260,12 @@ export declare class CollectionIndexes {
      * the given value. Returns `null` if no index covers the field — the
      * caller should fall back to a linear scan.
      *
+     * ⛔ ALSO `null` when the OPERAND has no bucket ADDRESS (#1402) — a
+     * nullish operand, or an object one, which every object-valued record in
+     * the collection shares. Answering those from the buckets returns rows
+     * the scan does not, silently, and only on the collections that happen to
+     * have an index. See `isProbeableBucketKey` for the two measurements.
+     *
      * The returned Set is a reference to the index's internal storage —
      * callers must NOT mutate it.
      */
@@ -127,6 +273,29 @@ export declare class CollectionIndexes {
     /**
      * Set lookup: return the union of record ids whose `field` matches any
      * of the given values. Returns `null` if no index covers the field.
+     *
+     * ⛔ ALSO `null` when ANY member of `values` has no bucket address
+     * (#1402) — one unaddressable member poisons the whole union, since the
+     * result is a union and there is no partial answer to hand back. Same
+     * measurement as {@link lookupEqual}.
      */
     lookupIn(field: string, values: readonly unknown[]): ReadonlySet<string> | null;
+    /**
+     * One record id per NON-EMPTY bucket of `field`'s hash index, in bucket
+     * order — the index-backed spine of `Query.distinct()` (#1347). `null` when
+     * no hash index covers the field, so the caller scans instead.
+     *
+     * The bucket set IS the distinct key set, so this costs O(buckets) rather
+     * than O(records). It returns REPRESENTATIVE IDS rather than the keys
+     * themselves on purpose: a bucket key is a canonical string (money's
+     * BigInt-normalized scaled int, say), and `distinct()` owes its caller the
+     * field's real value, which only the record carries.
+     *
+     * Bucket insertion order is first-seen record order — `build()` walks the
+     * snapshot in order and `upsert()` appends — which is why an index-backed
+     * `distinct()` and a scanned one agree on ORDER too, not merely on the set.
+     * Empty buckets are skipped defensively; `removeFromIndex` already deletes
+     * them, so this is belt-and-braces against a future partial removal path.
+     */
+    bucketRepresentatives(field: string): readonly string[] | null;
 }

package/dist/with-lookup/indexing/index-snapshot.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The on-disk shape of a persisted field index (#1359) — the format both
+ * `SortedIndex` (#1344) and `CompoundIndex` (#1345) round-trip through, plus
+ * the structural validator every load must pass.
+ *
+ * ⭐ **Nothing is flattened into a delimited string.** A compound entry keeps
+ * its tuple as an ARRAY of per-component keys, each carrying its runtime KIND
+ * alongside its value — which is the whole point of #1345's in-memory shape
+ * and would be destroyed by a `join()`. Two properties depend on it:
+ *
+ *  - **Kind survives.** Entries rank by runtime kind FIRST (mirroring
+ *    `predicate.ts`'s `isComparable`), so a `string` probe must not reach
+ *    `number` entries. An encoding that wrote only the value would collapse
+ *    `1` and `'1'` into one key space on the way back in.
+ *  - **Per-component ordering survives.** A string component may contain any
+ *    byte, including whatever a separator would have been.
+ *
+ * The validator is deliberately paranoid and its failure mode is a REBUILD,
+ * never a partial load: a blob that is truncated, from a future format, or
+ * internally out of order is rejected whole. See
+ * {@link parseFieldIndexSnapshot}.
+ */
+/** Bump on ANY incompatible change to the shapes below. An older stamp is rejected, not migrated. */
+export declare const FIELD_INDEX_SNAPSHOT_VERSION = 1;
+/** One `SortKey`, wire form: `[kind, key]`. `kind` IS the sort rank. */
+export type WireKey = readonly [kind: number, key: number | string];
+/** One `SortedIndex` entry: `[kind, key, seq, id]`. */
+export type WireSortedEntry = readonly [kind: number, key: number | string, seq: number, id: string];
+/** One `CompoundIndex` entry: `[tupleKeys, seq, id]` — the tuple stays an ARRAY. */
+export type WireCompoundEntry = readonly [keys: readonly WireKey[], seq: number, id: string];
+export interface SortedIndexSnapshot {
+    readonly v: number;
+    readonly t: 'sorted';
+    readonly field: string;
+    readonly nextSeq: number;
+    readonly entries: readonly WireSortedEntry[];
+}
+export interface CompoundIndexSnapshot {
+    readonly v: number;
+    readonly t: 'compound';
+    readonly fields: readonly string[];
+    readonly nextSeq: number;
+    readonly entries: readonly WireCompoundEntry[];
+}
+export type FieldIndexSnapshot = SortedIndexSnapshot | CompoundIndexSnapshot;
+/**
+ * Sidecar key for a single-field sorted index. Field paths are
+ * percent-encoded so no field name can collide with the `,` the compound
+ * form joins on, nor with the `s:` / `c:` discriminator.
+ */
+export declare function sortedIndexKey(field: string): string;
+/** Sidecar key for a compound index over an ordered field tuple. */
+export declare function compoundIndexKey(fields: readonly string[]): string;
+/**
+ * Decode + validate a persisted snapshot. Returns `null` — meaning "rebuild"
+ * — for anything that is not exactly the current format: bad JSON (a torn
+ * write), a version stamp from another release, a shape mismatch, a
+ * malformed key, or entries out of the order the index's binary searches
+ * require. A caller must never repair a snapshot; the source of truth is the
+ * cache, and rebuilding from it is always available.
+ */
+export declare function parseFieldIndexSnapshot(json: string): FieldIndexSnapshot | null;

package/dist/with-lookup/indexing/lazy-builder.d.ts

@@ -88,6 +88,12 @@ export declare class LazyQuery<T, S extends keyof T = never, Q extends keyof T &
     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>;
+    /**
+     * **ASYNC here, unlike `Query.toArray()` (#1413).** Same method name, a
+     * different contract, because the surface underneath differs: this one
+     * genuinely fetches through the persisted `_idx/` side-car, so it genuinely awaits. `Query`'s terminal reads an
+     * already-decrypted in-memory cache and returns `T[]` synchronously.
+     */
     toArray(): Promise<T[]>;
     first(): Promise<T | null>;
     count(): Promise<number>;
@@ -97,6 +103,33 @@ export declare class LazyQuery<T, S extends keyof T = never, Q extends keyof T &
      * clause that can scope the scan. Callers interpret null as
      * IndexRequiredError (see `toArray`).
      */
+    /**
+     * #1407 — refuse a NULLISH `==`/`in` operand in lazy mode instead of
+     * answering it with the empty bucket.
+     *
+     * `addToState` skips nullish values outright, so a record whose value IS
+     * nullish is absent from the persisted index. `lookupEqual` then returns the
+     * empty `\0NULL\0` bucket, and `[]` reads as "no rows match" when the truth
+     * is "the matching rows are not visible from here". Measured on an indexed
+     * field: `where('tag','==',null)` returned `[]` from lazy while the eager
+     * scan returned the row.
+     *
+     * ⛔ There is no superset to fall back to, which is what makes this
+     * different from every other unaddressable-operand case in this function.
+     * Enumerating the field's indexed ids returns a set that EXCLUDES every
+     * match — the opposite of a superset — so "enumerate and post-filter", the
+     * move the via-declined, via-`in`, via-RANGE and #1355 prefix branches all
+     * make, is unavailable here.
+     *
+     * ⭐ AN OBJECT OPERAND NEEDS NOTHING, and the first draft of this fix gave it
+     * something. `\0OBJECT\0` holds every object-valued record, only an object
+     * can `===` an object operand, and `toArray()`'s post-filter applies the
+     * exact predicate — so the bucket is already a sound superset, and a TIGHTER
+     * one than `orderedBy` would produce. Routing it through `orderedBy` was a
+     * silent perf regression dressed as a correctness fix. Verified by deleting
+     * the guard entirely: only the nullish cases fail.
+     */
+    private refuseNullishProbe;
     private resolveCandidateIds;
 }
 export {};

package/dist/with-lookup/indexing/persisted-field-indexes.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Persisted encrypted field indexes (#1359) — the debounce + freshness half.
+ *
+ * Shape deliberately mirrors the search index's `PersistedIndexStore`: this
+ * class is CRYPTO-FREE and storage-free. The collection injects
+ * load/save/remove callbacks that encrypt under the collection's DEK before
+ * they touch the adapter, so an index sidecar is ciphertext at rest like every
+ * other byte hub writes — the trust boundary does not move.
+ *
+ * One sidecar per `(collection, index)`, addressed by the index's sidecar key
+ * (`s:<field>` / `c:<f1>,<f2>`).
+ *
+ * ## Why crash residue can only ever be a rebuild
+ *
+ * A sidecar is a CACHE of something the record cache can always recompute, and
+ * it is used only when four independent checks pass:
+ *
+ *  1. it decrypts under the collection's DEK (a foreign or corrupt blob does not),
+ *  2. it parses as the CURRENT snapshot format, entries well-formed and in the
+ *     order the binary searches assume (`parseFieldIndexSnapshot`),
+ *  3. its freshness stamp equals the live one — record count, max record
+ *     version, and an order-independent digest over every `(id, version)` pair
+ *     in the cache, so any write, delete or re-put since the sidecar was
+ *     written changes it,
+ *  4. every id it names is still live in the cache.
+ *
+ * Any failure discards the whole blob and rebuilds from the cache. There is no
+ * repair path and no partial load, by construction: a half-adopted index would
+ * answer confidently and wrongly, which is the one outcome persistence may not
+ * introduce. A save that never lands, lands torn, or lands and is then
+ * overtaken by a crashed write leaves at most a blob that fails check 2, 3 or 4.
+ *
+ * The residual is a blob at rest holding indexed field VALUES after a
+ * `forget()` — closed by `purgePersistedIndexes`, which deletes these sidecars
+ * on erasure the same way it deletes the lazy-mode ones.
+ */
+import type { FieldIndexSnapshot } from './index-snapshot.js';
+/**
+ * The freshness stamp. `count` + `maxVersion` is the search store's signal;
+ * `digest` is the strengthening this index needs — an ordered index is wrong
+ * in a way a search index is merely imprecise, so a stamp that two different
+ * cache states can share is not good enough. See {@link fieldIndexFingerprint}.
+ */
+export interface FieldIndexFingerprint {
+    readonly count: number;
+    readonly maxVersion: number;
+    readonly digest: string;
+}
+export interface FieldIndexCallbacks {
+    /** Sidecar keys to persist, and the snapshot/restore hooks over them. */
+    keys(): readonly string[];
+    snapshot(key: string): FieldIndexSnapshot | undefined;
+    restore(key: string, snap: FieldIndexSnapshot, isLive: (id: string) => boolean): boolean;
+    load(key: string): Promise<{
+        json: string;
+        fingerprint: FieldIndexFingerprint;
+    } | null>;
+    save(key: string, json: string, fp: FieldIndexFingerprint): Promise<void>;
+    remove(key: string): Promise<void>;
+    currentFingerprint(): FieldIndexFingerprint;
+    debounceMs?: number;
+}
+/**
+ * An order-independent stamp over the cache's `(id, version)` pairs.
+ *
+ * Order-independent because cache iteration order is the adapter's `list()`
+ * order and is not promised to be stable across opens; a stamp that changed
+ * with it would reject every fresh sidecar and quietly turn persistence off.
+ * Two 32-bit accumulators (sum and xor over FNV-1a) rather than one, so a
+ * collision needs both to agree. `_v` increments on every write, so a changed
+ * record body always changes this — a record's indexed values cannot move
+ * underneath a matching stamp.
+ */
+export declare function fieldIndexFingerprint(cache: ReadonlyMap<string, {
+    readonly version: number;
+}>): FieldIndexFingerprint;
+/** Coordinates the sidecars of one collection's opted-in field indexes. */
+export declare class PersistedFieldIndexes {
+    private readonly cb;
+    private timer;
+    private readonly debounceMs;
+    constructor(cb: FieldIndexCallbacks);
+    /** True when at least one index on this collection asked to be persisted. */
+    get enabled(): boolean;
+    /**
+     * Restore whatever is fresh. Returns the sidecar keys that were adopted —
+     * the caller rebuilds every other declared index from the cache. Never
+     * throws for a bad blob: an unreadable sidecar is indistinguishable from an
+     * absent one, and both mean "rebuild".
+     */
+    restore(isLive: (id: string) => boolean): Promise<ReadonlySet<string>>;
+    /** Schedule a debounced write of every opted-in sidecar. */
+    markDirty(): void;
+    /** Force an immediate write (cancels any pending debounce). */
+    flush(): Promise<void>;
+    /** Delete every sidecar — erasure, and any point the blobs must not survive. */
+    removeAll(): Promise<{
+        purged: number;
+        residue: string[];
+    }>;
+    /** Drop a pending debounce without writing (collection teardown). */
+    dispose(): void;
+    private persist;
+}

package/dist/with-lookup/indexing/persisted-indexes.d.ts

@@ -183,6 +183,18 @@ export declare class PersistedCollectionIndex {
      * double-canonicalizes.
      */
     lookupEqual(field: string, value: unknown): ReadonlySet<string> | null;
+    /**
+     * Equality lookup that applies the registered canonicalizer to `value`
+     * FIRST — the write side (`ingest`/`upsert` → `addToState`) canonicalizes,
+     * so a probe that does not would miss a Via-covered (e.g. money) match.
+     *
+     * {@link lookupEqual} deliberately keeps the caller-canonicalizes contract
+     * because the query planner has already canonicalized by the time it gets
+     * here (#677). The unique-constraint pre-flight (#1358) has not, and has no
+     * access to the Via pipeline, so it probes through this instead. Returns
+     * `null` when the field is not declared.
+     */
+    probeEqual(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

package/dist/with-lookup/indexing/sorted-indexes.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Sorted (range) secondary indexes — the ordered sibling of the hash
+ * index in `eager-indexes.ts` (#1344).
+ *
+ * A sorted index is an array of `{ kind, key, seq, id }` entries kept in
+ * ascending `(kindRank, key, seq)` order. Binary search then answers
+ * `<`, `<=`, `>`, `>=`, `between` and `startsWith` as a contiguous slice,
+ * and `orderedIds()` walks the array for `orderBy(field).limit(n)`.
+ *
+ * Three properties are load-bearing, each mirroring the linear scan this
+ * replaces (`kernel/query/predicate.ts`):
+ *
+ *  - **Kind-partitioned.** `evaluateFieldClause`'s `isComparable` refuses
+ *    to order two values of different runtime types, so entries are ranked
+ *    by kind FIRST. A `string` probe therefore cannot reach `number`
+ *    entries, exactly as the scan cannot. Values with no order-defined
+ *    type (booleans, objects, arrays) are not indexed at all.
+ *  - **Nullish is not indexed**, same as the hash index.
+ *  - **Ties keep insertion order** (`seq`), which after a `build()` is
+ *    snapshot order — so an index-served `orderBy(...).limit(n)` returns
+ *    the same rows the stable scan-and-sort would. An in-place UPDATE
+ *    reinstates the rank it held rather than appending (#1369): the record
+ *    cache does not move a re-`put` record, so neither may the index.
+ *
+ * Keys canonicalise through the SAME per-field closure the hash index
+ * uses (`ViaPipeline.canonicalizeIndexKey`), so a Via-covered field's
+ * entries live in one key space here too. Range DISPATCH for a
+ * Via-covered clause is nevertheless declined by the query builder (a
+ * money operand has no ordered stored-form probe) — see
+ * `kernel/query/builder.ts`'s `candidateRecords`.
+ *
+ * PERSISTENCE (#1359) is OPT-IN, via `{ persist: true }` on the declaration.
+ * {@link SortedIndex.toSnapshot} / {@link SortedIndex.loadSnapshot} are the
+ * whole of this class's part in it — the encrypted sidecar, the freshness
+ * stamp and the debounce live in `persisted-field-indexes.ts`. Without the
+ * opt-in the index is in memory only and rebuilt on hydrate, as before.
+ */
+import { type FieldIndexSnapshot, type SortedIndexSnapshot } from './index-snapshot.js';
+/** Range operators a sorted index can answer. */
+export type RangeOperator = '<' | '<=' | '>' | '>=' | 'between' | 'startsWith';
+export { KIND_STRING, compareKeys, toSortKey, type KeyKind, type SortKey } from '../../kernel/query/sort-key.js';
+/** A single field's sorted index. */
+export declare class SortedIndex {
+    readonly field: string;
+    private readonly entries;
+    private nextSeq;
+    constructor(field: string);
+    get size(): number;
+    clear(): void;
+    /**
+     * Insert one record. No-op when the value has no order-defined kind.
+     *
+     * `seq` REINSTATES a rank a previous entry for this id held — see
+     * {@link remove}'s return value and `CollectionIndexes.upsert`. Omit it
+     * for a fresh insert, which appends after every existing tie.
+     */
+    add(id: string, value: unknown, canonicalKey: string | undefined, seq?: number): void;
+    /**
+     * Remove one record, addressed by the value it was indexed under.
+     * Returns the rank it held, so an UPDATE can reinstate it (#1369):
+     * `sortRecords()` sorts a snapshot whose order does not change when a
+     * record is written in place, so a tie-breaking rank that drifted to the
+     * back on every `put` would make an index-served page disagree with the
+     * scan it must match. Same contract as `CompoundIndex.remove`.
+     */
+    remove(id: string, value: unknown, canonicalKey: string | undefined): number | undefined;
+    /**
+     * Ids in ascending (or descending) key order. Ties keep INSERTION order
+     * in both directions — `sortRecords()` negates its comparator over a
+     * stable sort, which reverses the key order but not the order of equal
+     * keys. A plain `.reverse()` here would disagree on ties.
+     */
+    orderedIds(direction: 'asc' | 'desc'): string[];
+    /**
+     * Ids matching a range clause. Returns an empty set when the probe has
+     * no comparable kind — which is what the linear scan would produce too.
+     */
+    lookup(op: RangeOperator, value: unknown): Set<string>;
+    private prefix;
+    private slice;
+    /** [start, end) of the run of entries with the given kind — binary, not linear. */
+    private kindBounds;
+    private kindBoundary;
+    /** First index whose key is >= `probe`. */
+    private lowerBound;
+    /** First index whose key is > `probe`. */
+    private upperBound;
+    /**
+     * The persistable form of this index (#1359). `kind` travels with every
+     * key: entries rank by runtime kind first, so an encoding that dropped it
+     * would let a `string` probe reach `number` entries on the way back in.
+     */
+    toSnapshot(): SortedIndexSnapshot;
+    /**
+     * Adopt a validated snapshot, or refuse it. Refusal (`false`) means the
+     * caller rebuilds — it NEVER means a partial index: the entries are staged
+     * and only swapped in once every one of them is accepted.
+     *
+     * `isLive` is the caller's liveness predicate over the record cache. An
+     * entry naming a record the cache does not hold means the blob and the
+     * collection have diverged (a crash between the two writes, say), so the
+     * whole blob is discarded. Crash residue must be a rebuild, never a wrong
+     * answer.
+     */
+    loadSnapshot(snap: FieldIndexSnapshot, isLive: (id: string) => boolean): boolean;
+    /**
+     * Insertion point that keeps ties in `seq` order. A fresh entry lands at
+     * the end of its tie run; a REINSTATED one (see {@link add}) lands back at
+     * its own rank inside it.
+     */
+    private insertionPoint;
+}
+/** Build the whole index from a snapshot. Entry seqs follow snapshot order. */
+export declare function buildSortedIndex<T>(idx: SortedIndex, records: ReadonlyArray<{
+    id: string;
+    record: T;
+}>, canonicalize?: (field: string, value: unknown) => string | undefined): void;