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

package/dist/chunk-YSK2CU2Q.js

@@ -0,0 +1,936 @@
+import {
+  isProbeableBucketKey,
+  stringifyBucketKey
+} from "./chunk-SUZKW6UR.js";
+import {
+  KIND_STRING,
+  compareKeys,
+  toSortKey
+} from "./chunk-LGNDFRYC.js";
+import {
+  readPath
+} from "./chunk-HLEK5VAN.js";
+
+// src/with-lookup/indexing/index-snapshot.ts
+var FIELD_INDEX_SNAPSHOT_VERSION = 1;
+function sortedIndexKey(field) {
+  return `s:${encodeURIComponent(field)}`;
+}
+function compoundIndexKey(fields) {
+  return `c:${fields.map(encodeURIComponent).join(",")}`;
+}
+function isWireKey(x) {
+  if (!Array.isArray(x) || x.length !== 2) return false;
+  const [kind, key] = x;
+  if (kind === 0 || kind === 2) return typeof key === "number" && Number.isFinite(key);
+  if (kind === 1) return typeof key === "string";
+  return false;
+}
+function isSeq(x) {
+  return typeof x === "number" && Number.isInteger(x) && x >= 0;
+}
+function parseFieldIndexSnapshot(json) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null) return null;
+  const o = raw;
+  if (o["v"] !== FIELD_INDEX_SNAPSHOT_VERSION) return null;
+  if (!isSeq(o["nextSeq"]) || !Array.isArray(o["entries"])) return null;
+  const nextSeq = o["nextSeq"];
+  const entries = o["entries"];
+  if (o["t"] === "sorted") {
+    if (typeof o["field"] !== "string") return null;
+    const out = [];
+    for (const e of entries) {
+      if (!Array.isArray(e) || e.length !== 4) return null;
+      const [kind, key, seq, id] = e;
+      if (!isWireKey([kind, key])) return null;
+      if (!isSeq(seq) || seq >= nextSeq || typeof id !== "string") return null;
+      out.push([kind, key, seq, id]);
+    }
+    if (!isAscending(out.map((e) => [[e[0], e[1]]]), out.map((e) => e[2]))) return null;
+    return { v: FIELD_INDEX_SNAPSHOT_VERSION, t: "sorted", field: o["field"], nextSeq, entries: out };
+  }
+  if (o["t"] === "compound") {
+    const fields = o["fields"];
+    if (!Array.isArray(fields) || fields.length === 0 || !fields.every((f) => typeof f === "string")) return null;
+    const out = [];
+    for (const e of entries) {
+      if (!Array.isArray(e) || e.length !== 3) return null;
+      const [keys, seq, id] = e;
+      if (!Array.isArray(keys) || keys.length !== fields.length || !keys.every(isWireKey)) return null;
+      if (!isSeq(seq) || seq >= nextSeq || typeof id !== "string") return null;
+      out.push([keys, seq, id]);
+    }
+    if (!isAscending(out.map((e) => e[0]), out.map((e) => e[1]))) return null;
+    return { v: FIELD_INDEX_SNAPSHOT_VERSION, t: "compound", fields, nextSeq, entries: out };
+  }
+  return null;
+}
+function isAscending(keys, seqs) {
+  for (let i = 1; i < keys.length; i++) {
+    const c = compareWireTuples(keys[i - 1], keys[i]);
+    if (c > 0) return false;
+    if (c === 0 && seqs[i - 1] >= seqs[i]) return false;
+  }
+  return true;
+}
+function compareWireTuples(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (x[0] !== y[0]) return x[0] - y[0];
+    if (typeof x[1] === "number" && typeof y[1] === "number") {
+      if (x[1] !== y[1]) return x[1] - y[1];
+    } else if (x[1] !== y[1]) {
+      return x[1] < y[1] ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+// src/with-lookup/indexing/sorted-indexes.ts
+var SortedIndex = class {
+  constructor(field) {
+    this.field = field;
+  }
+  field;
+  entries = [];
+  nextSeq = 0;
+  get size() {
+    return this.entries.length;
+  }
+  clear() {
+    this.entries.length = 0;
+    this.nextSeq = 0;
+  }
+  /**
+   * 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, value, canonicalKey, seq) {
+    const sk = toSortKey(value, canonicalKey);
+    if (!sk) return;
+    const entry = { ...sk, seq: seq ?? this.nextSeq++, id };
+    this.entries.splice(this.insertionPoint(entry), 0, entry);
+  }
+  /**
+   * 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, value, canonicalKey) {
+    const sk = toSortKey(value, canonicalKey);
+    if (!sk) return void 0;
+    for (let i = this.lowerBound(sk); i < this.entries.length; i++) {
+      const e = this.entries[i];
+      if (compareKeys(e, sk) !== 0) break;
+      if (e.id === id) {
+        this.entries.splice(i, 1);
+        return e.seq;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * 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) {
+    if (direction === "asc") return this.entries.map((e) => e.id);
+    const out = [];
+    let end = this.entries.length;
+    while (end > 0) {
+      let start = end - 1;
+      while (start > 0 && compareKeys(this.entries[start - 1], this.entries[end - 1]) === 0) start--;
+      for (let i = start; i < end; i++) out.push(this.entries[i].id);
+      end = start;
+    }
+    return out;
+  }
+  /**
+   * 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, value) {
+    if (op === "startsWith") return this.prefix(value);
+    if (op === "between") {
+      if (!Array.isArray(value) || value.length !== 2) return /* @__PURE__ */ new Set();
+      const lo2 = toSortKey(value[0], void 0);
+      const hi2 = toSortKey(value[1], void 0);
+      if (!lo2 || !hi2 || lo2.kind !== hi2.kind) return /* @__PURE__ */ new Set();
+      return this.slice(this.lowerBound(lo2), this.upperBound(hi2));
+    }
+    const probe = toSortKey(value, void 0);
+    if (!probe) return /* @__PURE__ */ new Set();
+    const lo = this.lowerBound(probe);
+    const hi = this.upperBound(probe);
+    const [kindStart, kindEnd] = this.kindBounds(probe.kind);
+    switch (op) {
+      case "<":
+        return this.slice(kindStart, lo);
+      case "<=":
+        return this.slice(kindStart, hi);
+      case ">":
+        return this.slice(hi, kindEnd);
+      case ">=":
+        return this.slice(lo, kindEnd);
+      default: {
+        const _exhaustive = op;
+        void _exhaustive;
+        return /* @__PURE__ */ new Set();
+      }
+    }
+  }
+  prefix(value) {
+    if (typeof value !== "string") return /* @__PURE__ */ new Set();
+    const out = /* @__PURE__ */ new Set();
+    const from = this.lowerBound({ kind: KIND_STRING, key: value });
+    for (let i = from; i < this.entries.length; i++) {
+      const e = this.entries[i];
+      if (e.kind !== KIND_STRING) break;
+      if (!e.key.startsWith(value)) break;
+      out.add(e.id);
+    }
+    return out;
+  }
+  slice(from, to) {
+    const out = /* @__PURE__ */ new Set();
+    for (let i = from; i < to; i++) out.add(this.entries[i].id);
+    return out;
+  }
+  /** [start, end) of the run of entries with the given kind — binary, not linear. */
+  kindBounds(kind) {
+    return [this.kindBoundary((k) => k < kind), this.kindBoundary((k) => k <= kind)];
+  }
+  kindBoundary(before) {
+    let lo = 0;
+    let hi = this.entries.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (before(this.entries[mid].kind)) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  /** First index whose key is >= `probe`. */
+  lowerBound(probe) {
+    let lo = 0;
+    let hi = this.entries.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (compareKeys(this.entries[mid], probe) < 0) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  /** First index whose key is > `probe`. */
+  upperBound(probe) {
+    let lo = 0;
+    let hi = this.entries.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (compareKeys(this.entries[mid], probe) <= 0) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  /**
+   * 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() {
+    return {
+      v: FIELD_INDEX_SNAPSHOT_VERSION,
+      t: "sorted",
+      field: this.field,
+      nextSeq: this.nextSeq,
+      entries: this.entries.map((e) => [e.kind, e.key, e.seq, e.id])
+    };
+  }
+  /**
+   * 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, isLive) {
+    if (snap.t !== "sorted" || snap.field !== this.field) return false;
+    const staged = [];
+    for (const [kind, key, seq, id] of snap.entries) {
+      if (!isLive(id)) return false;
+      staged.push({ kind, key, seq, id });
+    }
+    this.entries.length = 0;
+    for (const e of staged) this.entries.push(e);
+    this.nextSeq = snap.nextSeq;
+    return true;
+  }
+  /**
+   * 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.
+   */
+  insertionPoint(entry) {
+    let i = this.upperBound(entry);
+    while (i > 0 && compareKeys(this.entries[i - 1], entry) === 0 && this.entries[i - 1].seq > entry.seq) {
+      i--;
+    }
+    return i;
+  }
+};
+function buildSortedIndex(idx, records, canonicalize) {
+  idx.clear();
+  for (const { id, record } of records) {
+    const value = readPath(record, idx.field);
+    if (value === null || value === void 0) continue;
+    idx.add(id, value, canonicalize?.(idx.field, value));
+  }
+}
+
+// src/with-lookup/indexing/compound-indexes.ts
+var CompoundIndex = class {
+  constructor(fields) {
+    this.fields = fields;
+  }
+  fields;
+  entries = [];
+  nextSeq = 0;
+  get size() {
+    return this.entries.length;
+  }
+  clear() {
+    this.entries.length = 0;
+    this.nextSeq = 0;
+  }
+  /**
+   * 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, keys, seq) {
+    if (!keys) return;
+    const entry = { keys, seq: seq ?? this.nextSeq++, id };
+    this.entries.splice(this.insertionPoint(entry), 0, entry);
+  }
+  /**
+   * 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, keys) {
+    if (!keys) return void 0;
+    const [from, to] = this.run(keys, keys.length);
+    for (let i = from; i < to; i++) {
+      if (this.entries[i].id === id) {
+        const [gone] = this.entries.splice(i, 1);
+        return gone.seq;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * 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, range) {
+    const [from, to] = this.run(prefix, prefix.length);
+    if (!range) return this.slice(from, to);
+    const k = prefix.length;
+    if (k >= this.fields.length) return /* @__PURE__ */ new Set();
+    if (range.op === "startsWith") {
+      if (typeof range.value !== "string") return /* @__PURE__ */ new Set();
+      const out = /* @__PURE__ */ new Set();
+      const start = this.lowerBound([...prefix, { kind: KIND_STRING, key: range.value }], k + 1, from, to);
+      for (let i = start; i < to; i++) {
+        const key = this.entries[i].keys[k];
+        if (key.kind !== KIND_STRING) break;
+        if (!key.key.startsWith(range.value)) break;
+        out.add(this.entries[i].id);
+      }
+      return out;
+    }
+    if (range.op === "between") {
+      if (!Array.isArray(range.value) || range.value.length !== 2) return /* @__PURE__ */ new Set();
+      const lo2 = toSortKey(range.value[0], void 0);
+      const hi2 = toSortKey(range.value[1], void 0);
+      if (!lo2 || !hi2 || lo2.kind !== hi2.kind) return /* @__PURE__ */ new Set();
+      return this.slice(
+        this.lowerBound([...prefix, lo2], k + 1, from, to),
+        this.upperBound([...prefix, hi2], k + 1, from, to)
+      );
+    }
+    const probe = toSortKey(range.value, void 0);
+    if (!probe) return /* @__PURE__ */ new Set();
+    const [kindStart, kindEnd] = this.kindRun(from, to, k, probe.kind);
+    const lo = this.lowerBound([...prefix, probe], k + 1, from, to);
+    const hi = this.upperBound([...prefix, probe], k + 1, from, to);
+    switch (range.op) {
+      case "<":
+        return this.slice(kindStart, lo);
+      case "<=":
+        return this.slice(kindStart, hi);
+      case ">":
+        return this.slice(hi, kindEnd);
+      case ">=":
+        return this.slice(lo, kindEnd);
+      default: {
+        const _exhaustive = range.op;
+        void _exhaustive;
+        return /* @__PURE__ */ new Set();
+      }
+    }
+  }
+  /**
+   * 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, direction) {
+    const [from, to] = this.run(prefix, prefix.length);
+    const out = [];
+    if (direction === "asc") {
+      for (let i = from; i < to; i++) out.push(this.entries[i].id);
+      return out;
+    }
+    let end = to;
+    while (end > from) {
+      let start = end - 1;
+      while (start > from && this.compare(this.entries[start - 1], this.entries[end - 1].keys, this.fields.length) === 0) {
+        start--;
+      }
+      for (let i = start; i < end; i++) out.push(this.entries[i].id);
+      end = start;
+    }
+    return out;
+  }
+  slice(from, to) {
+    const out = /* @__PURE__ */ new Set();
+    for (let i = from; i < to; i++) out.add(this.entries[i].id);
+    return out;
+  }
+  /** [start, end) of the entries whose first `upto` components equal `probe`. */
+  run(probe, upto) {
+    return [
+      this.lowerBound(probe, upto, 0, this.entries.length),
+      this.upperBound(probe, upto, 0, this.entries.length)
+    ];
+  }
+  /** [start, end) of the entries in [from,to) whose component `k` has this kind. */
+  kindRun(from, to, k, kind) {
+    return [
+      this.kindBoundary(from, to, k, (x) => x < kind),
+      this.kindBoundary(from, to, k, (x) => x <= kind)
+    ];
+  }
+  kindBoundary(from, to, k, before) {
+    let lo = from;
+    let hi = to;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (before(this.entries[mid].keys[k].kind)) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  /** First index in [from,to) whose first `upto` components are >= `probe`. */
+  lowerBound(probe, upto, from, to) {
+    let lo = from;
+    let hi = to;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (this.compare(this.entries[mid], probe, upto) < 0) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  /** First index in [from,to) whose first `upto` components are > `probe`. */
+  upperBound(probe, upto, from, to) {
+    let lo = from;
+    let hi = to;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      if (this.compare(this.entries[mid], probe, upto) <= 0) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  }
+  /**
+   * 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() {
+    return {
+      v: FIELD_INDEX_SNAPSHOT_VERSION,
+      t: "compound",
+      fields: [...this.fields],
+      nextSeq: this.nextSeq,
+      entries: this.entries.map(
+        (e) => [e.keys.map((k) => [k.kind, k.key]), e.seq, e.id]
+      )
+    };
+  }
+  /**
+   * 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, isLive) {
+    if (snap.t !== "compound") return false;
+    if (snap.fields.length !== this.fields.length) return false;
+    for (let i = 0; i < snap.fields.length; i++) if (snap.fields[i] !== this.fields[i]) return false;
+    const staged = [];
+    for (const [keys, seq, id] of snap.entries) {
+      if (!isLive(id)) return false;
+      staged.push({ keys: keys.map((k) => ({ kind: k[0], key: k[1] })), seq, id });
+    }
+    this.entries.length = 0;
+    for (const e of staged) this.entries.push(e);
+    this.nextSeq = snap.nextSeq;
+    return true;
+  }
+  /**
+   * 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.
+   */
+  insertionPoint(entry) {
+    const to = this.upperBound(entry.keys, this.fields.length, 0, this.entries.length);
+    let i = to;
+    while (i > 0 && this.compare(this.entries[i - 1], entry.keys, this.fields.length) === 0 && this.entries[i - 1].seq > entry.seq) {
+      i--;
+    }
+    return i;
+  }
+  compare(entry, probe, upto) {
+    for (let i = 0; i < upto; i++) {
+      const c = compareKeys(entry.keys[i], probe[i]);
+      if (c !== 0) return c;
+    }
+    return 0;
+  }
+};
+function tupleKeyOf(fields, record, canonicalize) {
+  const keys = [];
+  for (const field of fields) {
+    const value = readPath(record, field);
+    if (value === null || value === void 0) return void 0;
+    const key = toSortKey(value, canonicalize?.(field, value));
+    if (!key) return void 0;
+    keys.push(key);
+  }
+  return keys;
+}
+function probeKeysOf(values) {
+  const keys = [];
+  for (const value of values) {
+    const key = toSortKey(value, void 0);
+    if (!key) return void 0;
+    keys.push(key);
+  }
+  return keys;
+}
+function buildCompoundIndex(idx, records, canonicalize) {
+  idx.clear();
+  for (const { id, record } of records) {
+    idx.add(id, tupleKeyOf(idx.fields, record, canonicalize));
+  }
+}
+function compoundKey(fields) {
+  return fields.join("\0");
+}
+
+// src/with-lookup/indexing/eager-indexes.ts
+function normalizeIndexDefs(defs) {
+  return defs.map((def) => {
+    if (typeof def === "string") return { fields: [def] };
+    if (Array.isArray(def)) return { fields: def };
+    return def;
+  });
+}
+var CollectionIndexes = class {
+  indexes = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  sorted = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  compound = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  persistable = /* @__PURE__ */ new Map();
+  /**
+   * Per-field bucket-key canonicalizer (#672 review C1), registered ONCE
+   * via {@link setCanonicalizer} when the collection wires indexing up
+   * (money-aware via `ViaPipeline.canonicalizeIndexKey`). Consulted by
+   * EVERY bucket-mutation site — `build`/`upsert`/`remove` — so bucket
+   * membership is symmetric by construction: a value can never be added
+   * under a canonical key and later removed under the raw one (or vice
+   * versa), which is what stranded ids on `put`/`delete` before this fix.
+   */
+  canonicalize;
+  /**
+   * Register the bucket-key canonicalizer. Called once, where the
+   * collection constructs its indexing state — safe to call again (the
+   * closure is simply replaced) but there is normally only one caller.
+   */
+  setCanonicalizer(fn) {
+    this.canonicalize = fn;
+  }
+  /**
+   * Declare an index. Subsequent record additions are tracked under it.
+   * Calling this twice for the same field is a no-op (idempotent).
+   */
+  declare(field) {
+    if (this.indexes.has(field)) return;
+    this.indexes.set(field, { field, buckets: /* @__PURE__ */ new Map() });
+  }
+  /**
+   * 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, opts) {
+    let idx = this.sorted.get(field);
+    if (!idx) {
+      idx = new SortedIndex(field);
+      this.sorted.set(field, idx);
+    }
+    if (opts?.persist) this.persistable.set(sortedIndexKey(field), idx);
+  }
+  /** True if the given field has a declared SORTED index. */
+  hasSorted(field) {
+    return this.sorted.has(field);
+  }
+  /** All sorted-index field names, in declaration order. */
+  sortedFields() {
+    return [...this.sorted.keys()];
+  }
+  /** Number of entries in a field's sorted index (0 when undeclared). */
+  sortedSize(field) {
+    return this.sorted.get(field)?.size ?? 0;
+  }
+  /**
+   * 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, op, value) {
+    return this.sorted.get(field)?.lookup(op, value) ?? 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, direction) {
+    return this.sorted.get(field)?.orderedIds(direction) ?? 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, opts) {
+    if (fields.length < 2) return;
+    const key = compoundKey(fields);
+    let idx = this.compound.get(key);
+    if (!idx) {
+      idx = new CompoundIndex([...fields]);
+      this.compound.set(key, idx);
+    }
+    if (opts?.persist) this.persistable.set(compoundIndexKey(fields), idx);
+  }
+  /** Every declared field tuple, in declaration order. */
+  compoundTuples() {
+    return [...this.compound.values()].map((idx) => idx.fields);
+  }
+  /**
+   * 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) {
+    return this.compound.get(compoundKey(fields))?.size ?? 0;
+  }
+  /**
+   * 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, prefixValues, range) {
+    const idx = this.compound.get(compoundKey(fields));
+    if (!idx) return null;
+    const prefix = probeKeysOf(prefixValues);
+    if (!prefix) return null;
+    return idx.lookup(prefix, range);
+  }
+  /**
+   * 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, prefixValues, direction) {
+    const idx = this.compound.get(compoundKey(fields));
+    if (!idx) return null;
+    const prefix = probeKeysOf(prefixValues);
+    if (!prefix) return null;
+    return idx.orderedIds(prefix, direction);
+  }
+  /** True if the given field has a declared index. */
+  has(field) {
+    return this.indexes.has(field);
+  }
+  /** All declared field names, in declaration order. */
+  fields() {
+    return [...this.indexes.keys()];
+  }
+  /**
+   * Build all declared indexes from a snapshot of records.
+   * Called once per hydration. O(N × indexes.size). Buckets through the
+   * registered {@link setCanonicalizer} closure, same as `upsert`/`remove`.
+   */
+  build(records, skip = EMPTY_KEYS) {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+      for (const { id, record } of records) {
+        addToIndex(idx, id, record, this.canonicalize);
+      }
+    }
+    for (const [field, idx] of this.sorted) {
+      if (skip.has(sortedIndexKey(field))) continue;
+      buildSortedIndex(idx, records, this.canonicalize);
+    }
+    for (const idx of this.compound.values()) {
+      if (skip.has(compoundIndexKey(idx.fields))) continue;
+      buildCompoundIndex(idx, records, this.canonicalize);
+    }
+  }
+  /** Sidecar keys of every index declared `persist: true`, in declaration order. */
+  persistableKeys() {
+    return [...this.persistable.keys()];
+  }
+  /** The persistable snapshot behind one sidecar key, or `undefined` if it is not declared. */
+  snapshotIndex(key) {
+    return this.persistable.get(key)?.toSnapshot();
+  }
+  /**
+   * 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, snap, isLive) {
+    return this.persistable.get(key)?.loadSnapshot(snap, isLive) ?? false;
+  }
+  /**
+   * Insert or update a single record across all indexes.
+   * Called by `Collection.put()` after the encrypted write succeeds.
+   *
+   * If `previousRecord` is provided, the record is removed from any old
+   * buckets first — this is the update path. Pass `null` for fresh adds.
+   */
+  upsert(id, newRecord, previousRecord) {
+    if (this.indexes.size === 0 && this.sorted.size === 0 && this.compound.size === 0) return;
+    const ranks = /* @__PURE__ */ new Map();
+    const sortedRanks = /* @__PURE__ */ new Map();
+    if (previousRecord !== null) {
+      for (const [key, idx] of this.compound) {
+        ranks.set(key, idx.remove(id, tupleKeyOf(idx.fields, previousRecord, this.canonicalize)));
+      }
+      for (const [key, idx] of this.sorted) {
+        const value = readPath(previousRecord, idx.field);
+        if (value === null || value === void 0) continue;
+        sortedRanks.set(key, idx.remove(id, value, this.canonicalize?.(idx.field, value)));
+      }
+      this.remove(id, previousRecord);
+    }
+    for (const idx of this.indexes.values()) {
+      addToIndex(idx, id, newRecord, this.canonicalize);
+    }
+    for (const [key, idx] of this.sorted) {
+      const value = readPath(newRecord, idx.field);
+      if (value === null || value === void 0) continue;
+      idx.add(id, value, this.canonicalize?.(idx.field, value), sortedRanks.get(key));
+    }
+    for (const [key, idx] of this.compound) {
+      idx.add(id, tupleKeyOf(idx.fields, newRecord, this.canonicalize), ranks.get(key));
+    }
+  }
+  /**
+   * Remove a record from all indexes. Called by `Collection.delete()`
+   * (and as the first half of `upsert` for the update path).
+   */
+  remove(id, record) {
+    if (this.indexes.size === 0 && this.sorted.size === 0 && this.compound.size === 0) return;
+    for (const idx of this.indexes.values()) {
+      removeFromIndex(idx, id, record, this.canonicalize);
+    }
+    for (const idx of this.sorted.values()) {
+      const value = readPath(record, idx.field);
+      if (value === null || value === void 0) continue;
+      idx.remove(id, value, this.canonicalize?.(idx.field, value));
+    }
+    for (const idx of this.compound.values()) {
+      idx.remove(id, tupleKeyOf(idx.fields, record, this.canonicalize));
+    }
+  }
+  /** Drop all index data. Called when the collection is invalidated. */
+  clear() {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+    }
+    for (const idx of this.sorted.values()) {
+      idx.clear();
+    }
+    for (const idx of this.compound.values()) {
+      idx.clear();
+    }
+  }
+  /**
+   * Equality lookup: return the set of record ids whose `field` matches
+   * the given value. Returns `null` if no index covers the field — the
+   * caller should fall back to a linear scan.
+   *
+   * ⛔ 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.
+   */
+  lookupEqual(field, value) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    if (!isProbeableBucketKey(value)) return null;
+    const key = stringifyKey(value);
+    return idx.buckets.get(key) ?? EMPTY_SET;
+  }
+  /**
+   * 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, values) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    if (!values.every(isProbeableBucketKey)) return null;
+    const out = /* @__PURE__ */ new Set();
+    for (const value of values) {
+      const key = stringifyKey(value);
+      const bucket = idx.buckets.get(key);
+      if (bucket) {
+        for (const id of bucket) out.add(id);
+      }
+    }
+    return out;
+  }
+  /**
+   * 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) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const out = [];
+    for (const bucket of idx.buckets.values()) {
+      for (const id of bucket) {
+        out.push(id);
+        break;
+      }
+    }
+    return out;
+  }
+};
+var EMPTY_SET = /* @__PURE__ */ new Set();
+var EMPTY_KEYS = /* @__PURE__ */ new Set();
+var stringifyKey = stringifyBucketKey;
+function addToIndex(idx, id, record, canonicalize) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = canonicalize?.(idx.field, value) ?? stringifyKey(value);
+  let bucket = idx.buckets.get(key);
+  if (!bucket) {
+    bucket = /* @__PURE__ */ new Set();
+    idx.buckets.set(key, bucket);
+  }
+  bucket.add(id);
+}
+function removeFromIndex(idx, id, record, canonicalize) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = canonicalize?.(idx.field, value) ?? stringifyKey(value);
+  const bucket = idx.buckets.get(key);
+  if (!bucket) return;
+  bucket.delete(id);
+  if (bucket.size === 0) idx.buckets.delete(key);
+}
+
+export {
+  parseFieldIndexSnapshot,
+  normalizeIndexDefs,
+  CollectionIndexes
+};
+//# sourceMappingURL=chunk-YSK2CU2Q.js.map