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

package/dist/with-lookup/embeddings/ivf-flat.d.ts

@@ -0,0 +1,93 @@
+import type { StoredVector, VectorHit } from './vector-set.js';
+import type { VectorIndex, VectorIndexSearchOptions } from './vector-index.js';
+/**
+ * Default partition count for a corpus of `n` points.
+ *
+ * Build cost is `nlist` brute-force-query-equivalents and query cost is
+ * roughly `(nlist + nprobe·n/nlist)/n` of one, so `nlist` trades build against
+ * query *linearly in opposite directions*.
+ *
+ * MEASURED (768d, 100,000 vectors, `nprobe: 8`; full table in
+ * `test-harnesses/benchmarks/src/vector-ann-index.bench.ts`):
+ *
+ * | nlist       | scan  | speedup | recall@10 | build         |
+ * |-------------|-------|---------|-----------|---------------|
+ * | 79 = √n/4   | 10.3% |  9.7x   | 0.895     |  56 queries   |
+ * | 316 = √n    |  3.0% | 33.8x   | 0.813     | 288 queries   |
+ *
+ * √n is the better index and the worse DEFAULT. This index is per-session —
+ * it is rebuilt from the decrypted sidecars every time the process starts and
+ * is never persisted — so a build has only this session's queries to amortise
+ * against, and 288 query-equivalents is a bad opening bid for a consumer who
+ * runs a dozen searches. `√n/4` costs ~56 and still cuts the scan by 10x.
+ * A long-lived query-heavy session should override it; that is what the knob
+ * is for. The CAP (256) matters as much as the formula: it bounds the build at
+ * the top end, where an uncapped √n grows without limit.
+ */
+export declare function defaultNlist(n: number): number;
+interface IvfParams {
+    readonly nlist: number | undefined;
+    readonly nprobe: number;
+    readonly sampleSize: number;
+    readonly iterations: number;
+    readonly seed: number;
+}
+export declare class IvfFlatIndex implements VectorIndex {
+    private readonly params;
+    /** Unit-length partition representatives, `nlist` of them. */
+    private centroids;
+    /** `lists[c]` = point slots assigned to centroid `c`. */
+    private lists;
+    private pVec;
+    private pInv;
+    private pRecord;
+    private pChunk;
+    /** Owning list, or -1 for a free slot. */
+    private pList;
+    private recordIds;
+    private slotOfRecord;
+    private pointsOfRecord;
+    private freeSlots;
+    private live;
+    private builtAt;
+    /**
+     * Points actually scored by the last {@link search} — the deterministic
+     * measure of what the index bought.
+     *
+     * Wall-clock speedup is not reproducible on a loaded machine (measured: the
+     * same cell varied 100x across reps while other work ran), but the fraction
+     * of the corpus a query touches is exact arithmetic and identical on every
+     * machine. The benchmark reports both and treats this as the primary number;
+     * latency follows from it and the brute-force table's µs-per-vector.
+     */
+    lastProbedPoints: number;
+    constructor(params?: Partial<IvfParams>);
+    get size(): number;
+    get nlist(): number;
+    /**
+     * Rebuild when the corpus has doubled or halved since the fit. Incremental
+     * upserts assign to EXISTING centroids, so a set that grew 10x around new
+     * topics is partitioned by a map of the old ones — recall decays silently,
+     * which is the failure mode this flag exists to stop.
+     */
+    get stale(): boolean;
+    build(vectors: readonly StoredVector[]): void;
+    upsert(vector: StoredVector): void;
+    remove(recordId: string): void;
+    search(query: Float32Array, k: number, opts?: VectorIndexSearchOptions): VectorHit[];
+    /**
+     * A deterministic fixed-stride sample of the corpus, unit-normalised — the
+     * only place the index materialises normalised copies, and it is bounded by
+     * `sampleSize` rather than by `n`. A stride (not a random draw) so the fit
+     * is reproducible without spending the PRNG, which is saved for k-means++
+     * seeding where it actually buys recall.
+     */
+    private sampleUnitVectors;
+    private firstDim;
+    private topCentroids;
+    private assign;
+    private recordSlot;
+    /** Materialise one record's points into free slots. `list` -1 = unassigned. */
+    private addPoints;
+}
+export {};

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

@@ -0,0 +1,73 @@
+/**
+ * The approximate-index seam (#1360 part 2).
+ *
+ * This module holds **types only** — no algorithm. That is load-bearing for
+ * tree-shaking: `VectorSet` and the search facade reference an ANN index
+ * exclusively through {@link VectorIndex} (erased at build time) and through
+ * {@link VectorIndexConfig.create}, which the opt-in factory
+ * (`withVectorIndex()`) fills with a `await import('./ivf-flat.js')`. A
+ * consumer who never calls `withVectorIndex()` never links `ivf-flat.js` —
+ * not statically, not into a chunk it loads. `bundle-check`'s `search`
+ * scenario asserts exactly that, across every emitted chunk and not just the
+ * entry.
+ *
+ * ⛔ Do not add a value export here, and do not import `ivf-flat.js` from
+ * anywhere on the always-reachable path. Both would silently turn an opt-in
+ * into a tax on every consumer of `@noy-db/hub/search`.
+ */
+import type { StoredVector, VectorHit } from './vector-set.js';
+/** Per-query knobs. `nprobe` is the recall dial — see {@link VectorIndexConfig}. */
+export interface VectorIndexSearchOptions {
+    readonly minScore?: number;
+    /** Override the configured `nprobe` for this query only. Higher = better recall, slower. */
+    readonly nprobe?: number;
+}
+/**
+ * An in-hub approximate nearest-neighbour index over a collection's decrypted
+ * vectors. Lives entirely above the trust boundary: it is built from plaintext
+ * vectors already in memory and is never serialised to the store, so no
+ * backend ever holds a vector.
+ */
+export interface VectorIndex {
+    /** (Re)build from scratch over the whole vector set. */
+    build(vectors: readonly StoredVector[]): void;
+    /** Insert or replace one record's vectors (whole-record or chunked). */
+    upsert(vector: StoredVector): void;
+    /** Drop every point belonging to `recordId`. No-op if absent. */
+    remove(recordId: string): void;
+    /** Approximate top-k, one hit per RECORD (best chunk), highest score first. */
+    search(query: Float32Array, k: number, opts?: VectorIndexSearchOptions): VectorHit[];
+    /** Live point count (vectors, not records — a chunked record contributes one point per chunk). */
+    readonly size: number;
+    /**
+     * True when incremental churn has drifted the partitioning far enough from
+     * the corpus it was fitted to that a rebuild is cheaper than the recall loss.
+     */
+    readonly stale: boolean;
+    /** Introspection for the benchmark and for tests — never a behavioural input. */
+    readonly nlist: number;
+}
+/**
+ * What `withVectorIndex()` returns and what a collection's
+ * `embeddings.index` holds. Everything is a number except `create`, which is
+ * the dynamic-import seam.
+ */
+export interface VectorIndexConfig {
+    /**
+     * Below this many VECTORS the index is not built and search stays exact.
+     * Chunking multiplies vectors per record, so this counts points, not records.
+     */
+    readonly minVectors: number;
+    /** Default lists probed per query — the recall dial. */
+    readonly nprobe: number;
+    /** Number of partitions; `undefined` = derive from the corpus size. */
+    readonly nlist: number | undefined;
+    /** Points sampled to fit the centroids (the full corpus is only assigned, never clustered). */
+    readonly sampleSize: number;
+    /** Lloyd iterations over the sample. */
+    readonly iterations: number;
+    /** Seed for the deterministic k-means++ init — same corpus, same index, every run. */
+    readonly seed: number;
+    /** Lazily link and construct the implementation. */
+    create(): Promise<VectorIndex>;
+}

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

@@ -1,19 +1,112 @@
+import type { EmbeddingChunk, StoredChunk } from './chunks.js';
+import type { VectorIndexConfig } from './vector-index.js';
+/**
+ * One record's vectors. Exactly one of `vec` (whole-record, the pre-#1360
+ * shape) and `chunks` (sub-document, #1360) is populated by the loader; a row
+ * with neither is inert and scores nothing.
+ */
 export interface StoredVector {
     readonly id: string;
-    readonly vec: Float32Array;
     readonly model: string;
+    readonly vec?: Float32Array;
+    /** #1360 — sub-document chunks. When present, the record is scored by its BEST chunk. */
+    readonly chunks?: readonly StoredChunk[];
 }
 export interface VectorHit {
     readonly id: string;
     readonly score: number;
+    /** #1360 — the winning chunk's span, when the record was scored via chunks. */
+    readonly chunk?: EmbeddingChunk;
+}
+/** Options accepted by {@link VectorSet.topK}. */
+export interface VectorTopKOptions {
+    readonly minScore?: number;
+    readonly expectModel?: string;
+    /**
+     * Force the exact brute-force scan for this query, whatever the corpus size
+     * and whatever `index` the descriptor declares. Exactness stays REACHABLE:
+     * an approximate default that cannot be turned off is a correctness change
+     * dressed as a performance one.
+     */
+    readonly exact?: boolean;
+    /** Per-query recall dial; overrides the configured `nprobe`. Ignored on the exact path. */
+    readonly nprobe?: number;
 }
 export declare class VectorSet {
+    private readonly indexConfig?;
     private vectors;
+    /** id → position in `vectors`, so an incremental write is O(1), not O(n). */
+    private posById;
+    /** model → live record count, so the model guard is O(1) per query on the indexed path. */
+    private modelCounts;
+    private points;
+    private index;
+    private indexing;
+    /**
+     * Set when a build produced NO partitions — a corpus of nothing but
+     * zero-norm or mismatched-dimension vectors. An empty index answers every
+     * query with `[]`, which is a WRONG answer rather than a slow one (the exact
+     * path scores those vectors 0 and returns them), so the set falls back to
+     * brute force and does not retry the build on every query.
+     */
+    private indexUnusable;
+    /**
+     * `indexConfig` is `withVectorIndex()`'s return value, taken from the
+     * collection's `embeddings.index`. Absent — the overwhelmingly common case —
+     * and this class behaves exactly as it did before #1360 part 2.
+     */
+    constructor(indexConfig?: VectorIndexConfig | undefined);
     get loaded(): boolean;
+    /** Live VECTOR count (chunks included) — what `minVectors` is compared against. */
+    get pointCount(): number;
+    /** Test/benchmark introspection: whether an approximate index is currently serving queries. */
+    get indexed(): boolean;
     ensureLoaded(load: () => Promise<StoredVector[]>): Promise<void>;
     markDirty(): void;
+    /**
+     * Incrementally insert or replace one record's vectors.
+     *
+     * This is what makes an approximate index viable at all here. `markDirty()`
+     * drops the whole set, so before #1360 part 2 every `put()` cost a full
+     * re-load on the next query — survivable for a brute-force scan that has no
+     * build step, fatal for an index whose build is tens of query-equivalents.
+     * `embedOnWrite` already holds the vectors it just encoded, so it can hand
+     * them over instead of throwing the set away.
+     *
+     * No-op when the set is not loaded: an unloaded set is already "dirty", and
+     * the next query loads everything from the sidecars anyway.
+     */
+    upsert(vector: StoredVector): void;
+    /**
+     * Incrementally drop one record's vectors. Removal is a SWAP with the last
+     * element, not a splice: `vectors` order is whatever `adapter.list()`
+     * returned and has never been part of any contract, so preserving it would
+     * buy nothing and cost an O(n) index rebuild on every `forget()`.
+     */
+    removeRecord(id: string): void;
+    private decModel;
+    /**
+     * Brute-force cosine kNN, one hit per RECORD. **Always exact.**
+     *
+     * #1360 best-chunk folding: a chunked record contributes its single BEST
+     * chunk score, never one hit per chunk and never a sum. Summing would make a
+     * long document outrank a short exact match purely for having more chunks —
+     * the folding is what keeps the score comparable across record lengths, and
+     * what keeps `k` a count of records rather than of fragments.
+     */
     cosineTopK(query: Float32Array, k: number, opts?: {
         minScore?: number;
         expectModel?: string;
     }): VectorHit[];
+    /**
+     * kNN under the collection's policy: approximate when an index is opted in
+     * AND the corpus is at or above `minVectors`, exact otherwise.
+     *
+     * ⭐ The default below the threshold is EXACT, deliberately: an index that
+     * builds on a 300-vector collection pays a build the queries can never
+     * amortise, and buys a recall cliff for a scan that was already sub-millisecond.
+     */
+    topK(query: Float32Array, k: number, opts?: VectorTopKOptions): Promise<VectorHit[]>;
+    /** Build (or rebuild, once churn has made it stale) the index. Concurrency-safe. */
+    private ensureIndex;
 }

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

@@ -0,0 +1,67 @@
+/**
+ * `withVectorIndex()` — the opt-in for the approximate vector index (#1360).
+ *
+ * ```ts
+ * import { withVectorIndex } from '@noy-db/hub/search'
+ *
+ * const col = vault.collection('docs', {
+ *   embeddings: { source: 'body', encode, dim: 768, model: 'e5-base',
+ *                 index: withVectorIndex({ nprobe: 12 }) },
+ * })
+ * ```
+ *
+ * Three properties, each load-bearing:
+ *
+ * 1. **Opt-in.** No `index` on the descriptor and every search is exact brute
+ *    force, byte for byte the pre-#1360 path. Nothing about this file runs.
+ * 2. **Tree-shaken.** The algorithm arrives through `await import()` inside
+ *    {@link create}, so a consumer of `@noy-db/hub/search` who never calls
+ *    this function never links `ivf-flat.js` into any chunk.
+ * 3. **Still gated by scale even once opted in.** {@link
+ *    VectorIndexConfig.minVectors} defaults to the measured crossover, so a
+ *    small corpus pays no build cost and gets exact answers — opting in
+ *    declares a willingness to index, not an instruction to index now.
+ */
+import type { VectorIndexConfig } from './vector-index.js';
+export interface VectorIndexOptions {
+    /**
+     * Stay exact below this many VECTORS. Default 20,000.
+     *
+     * Chosen from `vector-brute-force.bench.ts`: below ~20k points the
+     * brute-force scan is inside a 100 ms interactive budget at every dimension
+     * measured (the tightest row, 1536d, crosses at ~18-48k depending on the
+     * machine), and IVF's build — tens of brute-force-query-equivalents — has no
+     * query volume to amortise against down there. Counts POINTS, not records — #1360
+     * chunking puts one point per chunk, so 2,500 documents at 8 chunks each
+     * already crosses this.
+     */
+    readonly minVectors?: number;
+    /**
+     * Lists probed per query — **the recall dial**. Default 8.
+     *
+     * Recall rises monotonically with `nprobe`, and `nprobe = nlist` is
+     * exhaustive — the same answer as brute force, by construction.
+     *
+     * MEASURED recall@10 at this default, against exact brute force on a
+     * clustered corpus: **0.895** (768d, 100k vectors), **0.942** (384d, 100k),
+     * **0.918** (1536d, 50k), **0.928** (64d, 20k — the CI assertion in
+     * `__tests__/embeddings-ivf-recall.test.ts`). Raising it to 16 buys ~0.95
+     * for roughly double the scan.
+     *
+     * Raise it when a miss costs more than a millisecond — and prefer
+     * `{ exact: true }` on the query over `nprobe: nlist` when the answer must
+     * be exact, because that says what you mean and survives an `nlist` change.
+     */
+    readonly nprobe?: number;
+    /** Partitions. Default: derived from the corpus size — see `defaultNlist`. */
+    readonly nlist?: number;
+    /** Points sampled to fit the centroids. Default 4096. */
+    readonly sampleSize?: number;
+    /** Lloyd iterations over the sample. Default 6. */
+    readonly iterations?: number;
+    /** k-means++ seed. Default fixed, so the same corpus yields the same index. */
+    readonly seed?: number;
+}
+/** Vectors below which an opted-in collection still answers exactly. */
+export declare const DEFAULT_INDEX_MIN_VECTORS = 20000;
+export declare function withVectorIndex(opts?: VectorIndexOptions): VectorIndexConfig;

package/dist/with-lookup/indexing/collection-facade.d.ts

@@ -21,11 +21,13 @@
  * 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 { RecordCodec } from '../../capsule/index.js';
 import type { NoydbEventEmitter } from '../../kernel/events.js';
-import type { CollectionIndexes } from './eager-indexes.js';
+import { type CollectionIndexes, type IndexDef } from './eager-indexes.js';
 import type { UniqueConstraintSet } from './unique-constraints.js';
 import { type PersistedCollectionIndex } from './persisted-indexes.js';
+import { PersistedFieldIndexes, type FieldIndexCallbacks } from './persisted-field-indexes.js';
+export type { PersistedFieldIndexes } from './persisted-field-indexes.js';
 /** Everything the moving index-maintenance methods touched on `this.*`. */
 export interface IndexingContext<T> {
     /** Collection name — the canonical record namespace + error context. */
@@ -51,6 +53,8 @@ export interface IndexingContext<T> {
     readonly uniqueConstraints: UniqueConstraintSet | null;
     /** The lazy-mode persisted-index mirror, or null (SHARED reference). */
     readonly persistedIndexes: PersistedCollectionIndex | null;
+    /** The eager-mode persisted field-index sidecars (#1359), or null (SHARED reference). */
+    readonly fieldIndexes: PersistedFieldIndexes | null;
     /** Hydrate the eager cache before rebuilding from it. */
     ensureHydrated(): Promise<void>;
     /** Bulk-load the persisted-index mirror from side-cars (lazy mode). */
@@ -63,7 +67,64 @@ export interface IndexingContext<T> {
  * 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;
+export declare function rebuildEagerIndexesFromCache<T>(ctx: IndexingContext<T>, skip?: ReadonlySet<string>): void;
+/**
+ * Bridge the crypto-free {@link PersistedFieldIndexes} to this collection's
+ * codec + adapter — the exact division `buildPersistedIndexCallbacks` uses for
+ * the search index: crypto lives here, the store does not know it exists.
+ *
+ * One record per `(collection, index)`, at `_fieldidx / <collection>/<key>`.
+ * The freshness stamp rides INSIDE the encrypted body (`{fp, idx}`) rather
+ * than on the envelope, so the `EncryptedEnvelope` shape is never extended and
+ * the stamp is not readable at rest.
+ *
+ * Takes a context THUNK for the same reason the search bridge does: it is
+ * built from the `Collection` constructor, before `this.codec` is assigned.
+ */
+export declare function buildFieldIndexCallbacks<T>(provideCtx: () => IndexingContext<T>, debounceMs?: number): FieldIndexCallbacks;
+/**
+ * Build this collection's sidecar coordinator, or `null` when no index asked
+ * to be persisted — so every other collection pays nothing. Kept here rather
+ * than in `Collection` so the kernel spine never names a `with-*` class
+ * (port-layering); the collection holds it only as a type.
+ */
+export declare function createPersistedFieldIndexes<T>(provideCtx: () => IndexingContext<T>, indexes: CollectionIndexes | null): PersistedFieldIndexes | null;
+/**
+ * The bulk-hydration index build, with the #1359 persisted-sidecar fast path
+ * in front of it: adopt every sidecar whose freshness stamp still matches the
+ * cache, then rebuild only what was not adopted, then owe a write-back for
+ * whatever had to be rebuilt (a fully restored open rewrites nothing).
+ *
+ * A sidecar that is absent, stale, unreadable or internally inconsistent
+ * simply does not appear in `restored`, so the outcome is the pre-#1359
+ * rebuild — the failure mode is always cost, never a wrong answer. The
+ * liveness predicate is the record cache itself.
+ *
+ * Collapses to exactly the old synchronous call when no index opted in.
+ */
+export declare function hydrateEagerIndexes<T>(ctx: IndexingContext<T>): Promise<void>;
+/**
+ * The unique-constraint pre-flight every ordinary `put()` runs before its
+ * store write (#1358). One entry point, three outcomes, and NONE of them is a
+ * silent pass:
+ *
+ *  - **CRDT** (`enforcement === 'detect'`) — returns without checking, on
+ *    purpose. A replica cannot refuse a value another offline replica may
+ *    already hold, so it does not pretend to; the collision is reported from
+ *    `UniqueConstraintSet.upsert`/`build` on `unique:violation` instead. See
+ *    that class's module doc.
+ *  - **Lazy** (`prefetch: false`) — a point lookup through the persisted
+ *    `_idx/` mirror, which lazy mode already maintains on every write. The
+ *    mirror is bulk-loaded first (the same hydration a lazy query forces), so
+ *    a record written in a PRIOR session is seen.
+ *  - **Eager** — the in-memory map, unchanged.
+ *
+ * The TIER dimension is orthogonal and is checked separately, by
+ * `checkUniqueAcrossTiers` in `with-audit/tiers/index.ts` — it needs the
+ * keyring to decrypt above-tier records, which this context deliberately
+ * does not carry.
+ */
+export declare function checkUniqueOnPut<T>(ctx: IndexingContext<T>, id: string, record: unknown): Promise<void>;
 /**
  * Rebuild unique-constraint maps from the current in-memory cache.
  * Called after any bulk hydration alongside `rebuildEagerIndexesFromCache`.
@@ -155,3 +216,25 @@ export declare function purgePersistedIndexes<T>(ctx: IndexingContext<T>, id: st
  * 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>;
+/**
+ * #1421 — `indexes:` declared while the indexing service is not opted in.
+ *
+ * `indexes:` is accepted and recorded whatever the strategy is; with
+ * `NO_INDEXING` nothing builds them, so every lookup scans. Results stay
+ * correct and performance is quietly wrong, which is how the reporting
+ * consumer's production lookups had been scans without anything saying so.
+ *
+ * ⚠️ **Warn, never throw.** Declaring `indexes:` without opting in is
+ * legitimate — one collection definition can be shared between a full app and
+ * a lightweight script that deliberately skips the index engine. Refusing
+ * would break that. But silence is the wrong default when a declaration the
+ * caller wrote has no effect.
+ *
+ * Normalizes the declared defs and, on the way past, warns. Called once from the
+ * `Collection` constructor, so the warning is once per collection
+ * (`vault.collection()` caches the handle) and never per query.
+ */
+export declare function resolveDeclaredIndexes(defs: readonly IndexDef[], collectionName: string, indexingEnabled: boolean): ReadonlyArray<{
+    readonly fields: readonly string[];
+    readonly unique?: boolean;
+}>;

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

@@ -0,0 +1,129 @@
+/**
+ * Compound (multi-field) sorted indexes — the tuple-keyed sibling of
+ * `sorted-indexes.ts` (#1345).
+ *
+ * A compound index is an array of `{ keys, seq, id }` entries kept in
+ * ascending `(keys[0], keys[1], …, seq)` order, where each `keys[i]` is
+ * the SAME `SortKey` the single-field sorted index builds — so the tuple
+ * encoding is order-preserving per component BY CONSTRUCTION rather than
+ * by a second, hand-rolled serialization. Nothing is flattened into a
+ * delimited string: a string component can therefore contain any byte
+ * without colliding with a separator, and a money field canonicalized to
+ * a scaled-integer string (`ViaPipeline.canonicalizeIndexKey`) or a date
+ * stored as ISO text sorts inside its own component exactly as it does in
+ * the single-field index.
+ *
+ * The two load-bearing properties of #1344 hold PER COMPONENT:
+ *
+ *  - **Kind-partitioned.** `compareKeys` ranks by runtime kind first, so
+ *    within any equality-prefix run a `string` probe on the next
+ *    component cannot reach `number` entries — mirroring `predicate.ts`'s
+ *    `isComparable`, exactly as the linear scan behaves.
+ *  - **Ties keep insertion order** in both directions. `orderedIds()`
+ *    walks equal-key runs forward even when emitting descending, because
+ *    `sortRecords()` negates its comparator over a STABLE sort.
+ *
+ * **A record is indexed only when EVERY component has an order-defined
+ * value.** One nullish or non-orderable component and the record is
+ * absent — which is why the query builder compares {@link
+ * CompoundIndex.size} against the snapshot size before dispatching, and
+ * falls back to the scan when the index does not cover the collection.
+ *
+ * PERSISTENCE (#1359) is OPT-IN, same as its single-field sibling. The wire
+ * form keeps the tuple as an ARRAY of per-component keys — see
+ * `index-snapshot.ts`: flattening it to a delimited string would destroy
+ * exactly the per-component ordering and kind partition this class is built
+ * to preserve.
+ */
+import { type RangeOperator, type SortKey } from './sorted-indexes.js';
+import { type CompoundIndexSnapshot, type FieldIndexSnapshot } from './index-snapshot.js';
+/** A range constraint on the component just past the equality prefix. */
+export interface CompoundRangeProbe {
+    readonly op: RangeOperator;
+    readonly value: unknown;
+}
+/** One collection's index over an ordered field tuple. */
+export declare class CompoundIndex {
+    readonly fields: readonly string[];
+    private readonly entries;
+    private nextSeq;
+    constructor(fields: readonly string[]);
+    get size(): number;
+    clear(): void;
+    /**
+     * Insert one record. No-op unless every component has an ordered key.
+     *
+     * `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, keys: readonly SortKey[] | undefined, seq?: number): void;
+    /**
+     * Remove one record, addressed by the tuple it was indexed under.
+     * Returns the rank it held, so an UPDATE can reinstate it: `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.
+     */
+    remove(id: string, keys: readonly SortKey[] | undefined): number | undefined;
+    /**
+     * Ids matching an equality prefix, optionally narrowed by a range on
+     * the next component. An empty set is authoritative: the index covers
+     * these fields and nothing matches.
+     */
+    lookup(prefix: readonly SortKey[], range?: CompoundRangeProbe): Set<string>;
+    /**
+     * Ids matching an equality prefix, in the order of the remaining
+     * components. Ties keep INSERTION order in both directions — a plain
+     * `.reverse()` would disagree with `sortRecords()` on equal keys.
+     */
+    orderedIds(prefix: readonly SortKey[], direction: 'asc' | 'desc'): string[];
+    private slice;
+    /** [start, end) of the entries whose first `upto` components equal `probe`. */
+    private run;
+    /** [start, end) of the entries in [from,to) whose component `k` has this kind. */
+    private kindRun;
+    private kindBoundary;
+    /** First index in [from,to) whose first `upto` components are >= `probe`. */
+    private lowerBound;
+    /** First index in [from,to) whose first `upto` components are > `probe`. */
+    private upperBound;
+    /**
+     * The persistable form of this index (#1359). Each entry's tuple stays an
+     * ARRAY of `[kind, key]` pairs: nothing is joined into a string, so a
+     * string component may hold any byte and the per-component kind partition
+     * survives the round trip intact.
+     */
+    toSnapshot(): CompoundIndexSnapshot;
+    /**
+     * Adopt a validated snapshot, or refuse it. Same contract as
+     * `SortedIndex.loadSnapshot`: all-or-nothing, and an entry naming a record
+     * the cache does not hold rejects the whole blob so crash residue becomes a
+     * rebuild rather than a wrong answer. A snapshot whose field tuple is not
+     * exactly this index's is refused — the declaration changed under it.
+     */
+    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;
+    private compare;
+}
+/**
+ * The tuple key for one record, or `undefined` when any component is
+ * nullish or has no order-defined runtime type. Canonicalizes through the
+ * same per-field closure the hash and sorted indexes use, so a Via-covered
+ * component lives in one key space across all three.
+ */
+export declare function tupleKeyOf<T>(fields: readonly string[], record: T, canonicalize?: (field: string, value: unknown) => string | undefined): SortKey[] | undefined;
+/** Probe keys for an equality prefix, or `undefined` if any operand is unorderable. */
+export declare function probeKeysOf(values: readonly unknown[]): SortKey[] | undefined;
+/** Build the whole index from a snapshot. Entry seqs follow snapshot order. */
+export declare function buildCompoundIndex<T>(idx: CompoundIndex, records: ReadonlyArray<{
+    id: string;
+    record: T;
+}>, canonicalize?: (field: string, value: unknown) => string | undefined): void;
+/** Stable map key for a field tuple. `\0` cannot appear in a field path. */
+export declare function compoundKey(fields: readonly string[]): string;