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

package/dist/issue-IHARXWW5.js

@@ -0,0 +1,18 @@
+import {
+  issueAttestationCore
+} from "./chunk-MTL7MXGR.js";
+import "./chunk-QWFHIOD2.js";
+import "./chunk-4AOERLTV.js";
+import "./chunk-KJFW62P4.js";
+import "./chunk-SEE332EV.js";
+import "./chunk-6QSQQLSE.js";
+import "./chunk-DE4DH2RZ.js";
+import "./chunk-LQ4ZHOKP.js";
+import "./chunk-LP7BEXCT.js";
+import "./chunk-UYB234ZR.js";
+import "./chunk-ODVPTDPK.js";
+import "./chunk-244VXYPG.js";
+export {
+  issueAttestationCore
+};
+//# sourceMappingURL=issue-IHARXWW5.js.map

package/dist/ivf-flat-UZ6DQDLS.js

@@ -0,0 +1,314 @@
+// src/with-lookup/embeddings/ivf-flat.ts
+function defaultNlist(n) {
+  return Math.max(4, Math.min(256, Math.round(Math.sqrt(n) / 4)));
+}
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 >>> 0;
+    let t = a;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function dot(a, b) {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+  return s;
+}
+function invNorm(v) {
+  let n = 0;
+  for (let i = 0; i < v.length; i++) n += v[i] * v[i];
+  return n === 0 ? 0 : 1 / Math.sqrt(n);
+}
+var IVF_DEFAULTS = {
+  nlist: void 0,
+  nprobe: 8,
+  sampleSize: 4096,
+  iterations: 6,
+  seed: 2654435769
+};
+var IvfFlatIndex = class {
+  params;
+  /** Unit-length partition representatives, `nlist` of them. */
+  centroids = [];
+  /** `lists[c]` = point slots assigned to centroid `c`. */
+  lists = [];
+  // Points, as parallel arrays. A "point" is one vector: a whole-record vector
+  // or one chunk of a chunked record. Parallel arrays rather than an object
+  // per point because at the gating scale there are hundreds of thousands of
+  // them and per-object overhead would dwarf the payload we deliberately
+  // refused to copy.
+  pVec = [];
+  pInv = [];
+  pRecord = [];
+  pChunk = [];
+  /** Owning list, or -1 for a free slot. */
+  pList = [];
+  recordIds = [];
+  slotOfRecord = /* @__PURE__ */ new Map();
+  pointsOfRecord = /* @__PURE__ */ new Map();
+  freeSlots = [];
+  live = 0;
+  builtAt = 0;
+  /**
+   * 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 = 0;
+  constructor(params = {}) {
+    this.params = { ...IVF_DEFAULTS, ...params };
+  }
+  get size() {
+    return this.live;
+  }
+  get nlist() {
+    return this.centroids.length;
+  }
+  /**
+   * 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() {
+    if (this.centroids.length === 0) return true;
+    return this.live > this.builtAt * 2 || this.live * 2 < this.builtAt;
+  }
+  build(vectors) {
+    this.centroids = [];
+    this.lists = [];
+    this.pVec = [];
+    this.pInv = [];
+    this.pRecord = [];
+    this.pChunk = [];
+    this.pList = [];
+    this.recordIds = [];
+    this.slotOfRecord = /* @__PURE__ */ new Map();
+    this.pointsOfRecord = /* @__PURE__ */ new Map();
+    this.freeSlots = [];
+    this.live = 0;
+    for (const v of vectors) this.addPoints(v, -1);
+    this.builtAt = this.live;
+    const dim = this.firstDim();
+    if (dim === 0) return;
+    const k = Math.max(1, Math.min(this.params.nlist ?? defaultNlist(this.live), this.live));
+    this.centroids = fitCentroids(this.sampleUnitVectors(dim), k, this.params);
+    if (this.centroids.length === 0) return;
+    this.lists = Array.from({ length: this.centroids.length }, () => []);
+    for (let p = 0; p < this.pVec.length; p++) {
+      if (this.pVec[p] === void 0) continue;
+      this.assign(p);
+    }
+  }
+  upsert(vector) {
+    this.remove(vector.id);
+    this.addPoints(vector, -1);
+    if (this.centroids.length === 0) return;
+    for (const p of this.pointsOfRecord.get(vector.id) ?? []) if (this.pList[p] === -1) this.assign(p);
+  }
+  remove(recordId) {
+    const pts = this.pointsOfRecord.get(recordId);
+    if (!pts) return;
+    for (const p of pts) {
+      const l = this.pList[p];
+      if (l >= 0) {
+        const list = this.lists[l];
+        const at = list.indexOf(p);
+        if (at >= 0) {
+          list[at] = list[list.length - 1];
+          list.pop();
+        }
+      }
+      this.pVec[p] = void 0;
+      this.pChunk[p] = void 0;
+      this.pList[p] = -1;
+      this.freeSlots.push(p);
+      this.live--;
+    }
+    this.pointsOfRecord.delete(recordId);
+  }
+  search(query, k, opts = {}) {
+    if (k <= 0 || this.centroids.length === 0) return [];
+    const qi = invNorm(query);
+    const minScore = opts.minScore ?? -Infinity;
+    if (qi === 0) return [];
+    const qn = new Float32Array(query.length);
+    for (let i = 0; i < query.length; i++) qn[i] = query[i] * qi;
+    const nprobe = Math.max(1, Math.min(opts.nprobe ?? this.params.nprobe, this.centroids.length));
+    const probes = this.topCentroids(qn, nprobe);
+    this.lastProbedPoints = 0;
+    const best = /* @__PURE__ */ new Map();
+    for (const c of probes) {
+      this.lastProbedPoints += this.lists[c].length;
+      for (const p of this.lists[c]) {
+        const v = this.pVec[p];
+        if (v === void 0 || v.length !== qn.length) continue;
+        const score = dot(qn, v) * this.pInv[p];
+        const r = this.pRecord[p];
+        const cur = best.get(r);
+        if (cur === void 0 || score > cur.score) best.set(r, { score, chunk: this.pChunk[p] });
+      }
+    }
+    const hits = [];
+    for (const [r, b] of best) {
+      if (b.score < minScore) continue;
+      hits.push(b.chunk ? { id: this.recordIds[r], score: b.score, chunk: b.chunk } : { id: this.recordIds[r], score: b.score });
+    }
+    hits.sort((a, b) => b.score - a.score);
+    return hits.slice(0, k);
+  }
+  /**
+   * 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.
+   */
+  sampleUnitVectors(dim) {
+    const slots = this.pVec.length;
+    const want = Math.min(slots, this.params.sampleSize);
+    const stride = Math.max(1, Math.floor(slots / Math.max(1, want)));
+    const sample = [];
+    for (let p = 0; p < slots && sample.length < want; p += stride) {
+      const v = this.pVec[p];
+      const inv = this.pInv[p];
+      if (v === void 0 || inv === 0 || v.length !== dim) continue;
+      const u = new Float32Array(dim);
+      for (let i = 0; i < dim; i++) u[i] = v[i] * inv;
+      sample.push(u);
+    }
+    return sample;
+  }
+  firstDim() {
+    for (const v of this.pVec) if (v !== void 0 && v.length > 0) return v.length;
+    return 0;
+  }
+  topCentroids(qn, nprobe) {
+    const scores = new Float64Array(this.centroids.length);
+    for (let c = 0; c < this.centroids.length; c++) {
+      const cv = this.centroids[c];
+      scores[c] = cv.length === qn.length ? dot(qn, cv) : -Infinity;
+    }
+    const order = [];
+    for (let c = 0; c < scores.length; c++) order.push(c);
+    order.sort((a, b) => scores[b] - scores[a]);
+    return order.slice(0, nprobe);
+  }
+  assign(p) {
+    const v = this.pVec[p];
+    if (v === void 0 || this.centroids.length === 0) return;
+    let bestC = 0;
+    let bestS = -Infinity;
+    const inv = this.pInv[p];
+    for (let c = 0; c < this.centroids.length; c++) {
+      const cv = this.centroids[c];
+      if (cv.length !== v.length) continue;
+      const s = dot(cv, v) * inv;
+      if (s > bestS) {
+        bestS = s;
+        bestC = c;
+      }
+    }
+    this.pList[p] = bestC;
+    this.lists[bestC].push(p);
+  }
+  recordSlot(id) {
+    const existing = this.slotOfRecord.get(id);
+    if (existing !== void 0) return existing;
+    const slot = this.recordIds.length;
+    this.recordIds.push(id);
+    this.slotOfRecord.set(id, slot);
+    return slot;
+  }
+  /** Materialise one record's points into free slots. `list` -1 = unassigned. */
+  addPoints(v, list) {
+    const r = this.recordSlot(v.id);
+    const pts = [];
+    const push = (vec, chunk) => {
+      const p = this.freeSlots.pop() ?? this.pVec.length;
+      this.pVec[p] = vec;
+      this.pInv[p] = invNorm(vec);
+      this.pRecord[p] = r;
+      this.pChunk[p] = chunk;
+      this.pList[p] = list;
+      pts.push(p);
+      this.live++;
+    };
+    if (v.chunks && v.chunks.length > 0) {
+      for (const c of v.chunks) push(c.vec, { id: c.id, start: c.start, end: c.end });
+    } else if (v.vec) {
+      push(v.vec, void 0);
+    }
+    if (pts.length > 0) this.pointsOfRecord.set(v.id, pts);
+  }
+};
+function fitCentroids(sample, k, params) {
+  if (sample.length === 0) return [];
+  const dim = sample[0].length;
+  const kk = Math.min(k, sample.length);
+  const rand = mulberry32(params.seed);
+  const centroids = [sample[Math.floor(rand() * sample.length)].slice()];
+  const best = new Float64Array(sample.length).fill(Infinity);
+  while (centroids.length < kk) {
+    const last = centroids[centroids.length - 1];
+    let total = 0;
+    for (let i = 0; i < sample.length; i++) {
+      const d = 1 - dot(sample[i], last);
+      const w = d * d;
+      if (w < best[i]) best[i] = w;
+      total += best[i];
+    }
+    if (total === 0) break;
+    let target = rand() * total;
+    let pick = sample.length - 1;
+    for (let i = 0; i < sample.length; i++) {
+      target -= best[i];
+      if (target <= 0) {
+        pick = i;
+        break;
+      }
+    }
+    centroids.push(sample[pick].slice());
+  }
+  for (let it = 0; it < params.iterations; it++) {
+    const sums = Array.from({ length: centroids.length }, () => new Float64Array(dim));
+    const counts = new Int32Array(centroids.length);
+    for (const u of sample) {
+      let bc = 0, bs = -Infinity;
+      for (let c = 0; c < centroids.length; c++) {
+        const s = dot(u, centroids[c]);
+        if (s > bs) {
+          bs = s;
+          bc = c;
+        }
+      }
+      const acc = sums[bc];
+      for (let i = 0; i < dim; i++) acc[i] += u[i];
+      counts[bc]++;
+    }
+    for (let c = 0; c < centroids.length; c++) {
+      if (counts[c] === 0) continue;
+      const acc = sums[c];
+      let n = 0;
+      for (let i = 0; i < dim; i++) n += acc[i] * acc[i];
+      if (n === 0) continue;
+      const inv = 1 / Math.sqrt(n);
+      const cv = centroids[c];
+      for (let i = 0; i < dim; i++) cv[i] = acc[i] * inv;
+    }
+  }
+  return centroids;
+}
+export {
+  IvfFlatIndex,
+  defaultNlist
+};
+//# sourceMappingURL=ivf-flat-UZ6DQDLS.js.map

package/dist/ivf-flat-UZ6DQDLS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-lookup/embeddings/ivf-flat.ts"],"sourcesContent":["/**\n * IVF-flat — the approximate vector index (#1360 part 2).\n *\n * ## Why IVF-flat and not HNSW\n *\n * The choice is a build-cost argument, not a taste one, and the numbers are in\n * `test-harnesses/benchmarks/src/vector-ann-index.bench.ts`.\n *\n * Every index here is paid for **once per session**: the vector set is loaded\n * from the encrypted `_vec` sidecars into memory, so an index built over it\n * dies with the process. There is no persisted index to amortise against —\n * `_vec` holds vectors, never a graph — so the only question that matters is\n * *how many queries does the build cost, and how many does it save?*\n *\n * - **IVF-flat** builds in `n · nlist` dot products = exactly `nlist`\n *   brute-force queries, and `nlist` is a knob we choose. At the defaults it is\n *   tens of query-equivalents, and one query then costs ~`(nlist + nprobe ·\n *   n/nlist)/n` of a brute-force scan.\n * - **HNSW** builds in `n · log n · efConstruction` distance computations —\n *   hundreds to thousands of query-equivalents at the same corpus — and its\n *   deletes need tombstones plus periodic graph repair. It wins on\n *   queries-per-second at *very* large n with a *persisted* graph. Neither\n *   condition holds here.\n *\n * The deciding property is that a noy-db collection is mutable: `put()` and\n * `forget()` run constantly, and IVF handles both in `O(nlist)` (assign to the\n * nearest centroid / splice out of one list) with no graph to repair.\n *\n * ## The scoring identity — why this is exact arithmetic on an approximate set\n *\n * Cosine is scale-invariant, so with a unit-normalised query `q̂`:\n *\n *     cosine(q, v) = dot(q̂, v) · (1/‖v‖)\n *\n * The index therefore stores the **caller's own `Float32Array` by reference**\n * plus one scalar `1/‖v‖` per point, and never a normalised copy. That is the\n * difference between `O(n)` and `O(n·d)` of index memory: at 100k × 768 a\n * normalised copy would be another ~300 MB. Scores this class returns are the\n * same numbers `cosine()` returns, bit for bit up to float association order —\n * so a hit's score is comparable with an exact hit's score, and `minScore`\n * means the same thing on both paths.\n *\n * ## What is approximate, and where recall goes\n *\n * Only the CANDIDATE SET is approximate: a true neighbour whose point sits in\n * an unprobed list is missed. `nprobe` is the dial; recall is measured, not\n * assumed (`__tests__/embeddings-ivf-recall.test.ts` and the benchmark).\n *\n * ⭐ Chunking interacts here: a record is scored by its best chunk *among the\n * probed lists*. A record whose best chunk is unprobed can still be returned\n * via a weaker chunk, with a lower score than exact search would give it. That\n * is a score difference, not only a membership difference, and it is why the\n * recall test compares folded RECORD results rather than raw points.\n *\n * ⚠️ **Ties do not order identically to the exact path**, even at `nprobe =\n * nlist`. Both sort by score with a stable sort, but over different scan\n * orders, so two records holding the SAME score can swap places. Neither path\n * ever promised a tie-break order. A real embedding corpus has no exact ties;\n * a test with a toy encoder is full of them, so compare by score there.\n */\nimport type { EmbeddingChunk } from './chunks.js'\nimport type { StoredVector, VectorHit } from './vector-set.js'\nimport type { VectorIndex, VectorIndexSearchOptions } from './vector-index.js'\n\n/**\n * Default partition count for a corpus of `n` points.\n *\n * Build cost is `nlist` brute-force-query-equivalents and query cost is\n * roughly `(nlist + nprobe·n/nlist)/n` of one, so `nlist` trades build against\n * query *linearly in opposite directions*.\n *\n * MEASURED (768d, 100,000 vectors, `nprobe: 8`; full table in\n * `test-harnesses/benchmarks/src/vector-ann-index.bench.ts`):\n *\n * | nlist       | scan  | speedup | recall@10 | build         |\n * |-------------|-------|---------|-----------|---------------|\n * | 79 = √n/4   | 10.3% |  9.7x   | 0.895     |  56 queries   |\n * | 316 = √n    |  3.0% | 33.8x   | 0.813     | 288 queries   |\n *\n * √n is the better index and the worse DEFAULT. This index is per-session —\n * it is rebuilt from the decrypted sidecars every time the process starts and\n * is never persisted — so a build has only this session's queries to amortise\n * against, and 288 query-equivalents is a bad opening bid for a consumer who\n * runs a dozen searches. `√n/4` costs ~56 and still cuts the scan by 10x.\n * A long-lived query-heavy session should override it; that is what the knob\n * is for. The CAP (256) matters as much as the formula: it bounds the build at\n * the top end, where an uncapped √n grows without limit.\n */\nexport function defaultNlist(n: number): number {\n  return Math.max(4, Math.min(256, Math.round(Math.sqrt(n) / 4)))\n}\n\n/** Deterministic PRNG — the index must be identical across runs for a given corpus. */\nfunction mulberry32(seed: number): () => number {\n  let a = seed >>> 0\n  return () => {\n    a = (a + 0x6d2b79f5) >>> 0\n    let t = a\n    t = Math.imul(t ^ (t >>> 15), t | 1)\n    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296\n  }\n}\n\nfunction dot(a: Float32Array, b: Float32Array): number {\n  let s = 0\n  for (let i = 0; i < a.length; i++) s += a[i]! * b[i]!\n  return s\n}\n\n/** `1/‖v‖`, or 0 for a zero vector — which makes its score 0, exactly as `cosine()` does. */\nfunction invNorm(v: Float32Array): number {\n  let n = 0\n  for (let i = 0; i < v.length; i++) n += v[i]! * v[i]!\n  return n === 0 ? 0 : 1 / Math.sqrt(n)\n}\n\ninterface IvfParams {\n  readonly nlist: number | undefined\n  readonly nprobe: number\n  readonly sampleSize: number\n  readonly iterations: number\n  readonly seed: number\n}\n\nconst IVF_DEFAULTS: IvfParams = {\n  nlist: undefined,\n  nprobe: 8,\n  sampleSize: 4096,\n  iterations: 6,\n  seed: 0x9e3779b9,\n}\n\nexport class IvfFlatIndex implements VectorIndex {\n  private readonly params: IvfParams\n\n  /** Unit-length partition representatives, `nlist` of them. */\n  private centroids: Float32Array[] = []\n  /** `lists[c]` = point slots assigned to centroid `c`. */\n  private lists: number[][] = []\n\n  // Points, as parallel arrays. A \"point\" is one vector: a whole-record vector\n  // or one chunk of a chunked record. Parallel arrays rather than an object\n  // per point because at the gating scale there are hundreds of thousands of\n  // them and per-object overhead would dwarf the payload we deliberately\n  // refused to copy.\n  private pVec: (Float32Array | undefined)[] = []\n  private pInv: number[] = []\n  private pRecord: number[] = []\n  private pChunk: (EmbeddingChunk | undefined)[] = []\n  /** Owning list, or -1 for a free slot. */\n  private pList: number[] = []\n\n  private recordIds: string[] = []\n  private slotOfRecord = new Map<string, number>()\n  private pointsOfRecord = new Map<string, number[]>()\n  private freeSlots: number[] = []\n  private live = 0\n  private builtAt = 0\n  /**\n   * Points actually scored by the last {@link search} — the deterministic\n   * measure of what the index bought.\n   *\n   * Wall-clock speedup is not reproducible on a loaded machine (measured: the\n   * same cell varied 100x across reps while other work ran), but the fraction\n   * of the corpus a query touches is exact arithmetic and identical on every\n   * machine. The benchmark reports both and treats this as the primary number;\n   * latency follows from it and the brute-force table's µs-per-vector.\n   */\n  lastProbedPoints = 0\n\n  constructor(params: Partial<IvfParams> = {}) {\n    this.params = { ...IVF_DEFAULTS, ...params }\n  }\n\n  get size(): number { return this.live }\n  get nlist(): number { return this.centroids.length }\n\n  /**\n   * Rebuild when the corpus has doubled or halved since the fit. Incremental\n   * upserts assign to EXISTING centroids, so a set that grew 10x around new\n   * topics is partitioned by a map of the old ones — recall decays silently,\n   * which is the failure mode this flag exists to stop.\n   */\n  get stale(): boolean {\n    if (this.centroids.length === 0) return true\n    return this.live > this.builtAt * 2 || this.live * 2 < this.builtAt\n  }\n\n  build(vectors: readonly StoredVector[]): void {\n    this.centroids = []\n    this.lists = []\n    this.pVec = []; this.pInv = []; this.pRecord = []; this.pChunk = []; this.pList = []\n    this.recordIds = []\n    this.slotOfRecord = new Map()\n    this.pointsOfRecord = new Map()\n    this.freeSlots = []\n    this.live = 0\n\n    // Materialise the points first (unassigned), then fit, then assign.\n    for (const v of vectors) this.addPoints(v, -1)\n    this.builtAt = this.live\n\n    const dim = this.firstDim()\n    if (dim === 0) return\n    const k = Math.max(1, Math.min(this.params.nlist ?? defaultNlist(this.live), this.live))\n    this.centroids = fitCentroids(this.sampleUnitVectors(dim), k, this.params)\n    // No centroids means no usable vector to fit on — every point was\n    // zero-norm or off-dimension. Leave the points unassigned; `nlist === 0`\n    // is the signal `VectorSet` reads to fall back to the exact scan, which\n    // scores those vectors 0 rather than dropping them.\n    if (this.centroids.length === 0) return\n    this.lists = Array.from({ length: this.centroids.length }, () => [] as number[])\n    for (let p = 0; p < this.pVec.length; p++) {\n      if (this.pVec[p] === undefined) continue\n      this.assign(p)\n    }\n  }\n\n  upsert(vector: StoredVector): void {\n    this.remove(vector.id)\n    this.addPoints(vector, -1)\n    if (this.centroids.length === 0) return\n    for (const p of this.pointsOfRecord.get(vector.id) ?? []) if (this.pList[p] === -1) this.assign(p)\n  }\n\n  remove(recordId: string): void {\n    const pts = this.pointsOfRecord.get(recordId)\n    if (!pts) return\n    for (const p of pts) {\n      const l = this.pList[p]!\n      if (l >= 0) {\n        const list = this.lists[l]!\n        const at = list.indexOf(p)\n        if (at >= 0) { list[at] = list[list.length - 1]!; list.pop() }\n      }\n      this.pVec[p] = undefined\n      this.pChunk[p] = undefined\n      this.pList[p] = -1\n      this.freeSlots.push(p)\n      this.live--\n    }\n    this.pointsOfRecord.delete(recordId)\n    // The record's SLOT is deliberately kept. `put()` on an existing id is\n    // remove-then-add, and freeing the slot there would mint a new one on\n    // every write — unbounded growth on the hottest path. A slot is 8 bytes\n    // and one string; a re-put reuses it.\n  }\n\n  search(query: Float32Array, k: number, opts: VectorIndexSearchOptions = {}): VectorHit[] {\n    if (k <= 0 || this.centroids.length === 0) return []\n    const qi = invNorm(query)\n    const minScore = opts.minScore ?? -Infinity\n    // A zero-norm query scores 0 against everything (cosine's contract). There\n    // is no meaningful ranking to approximate, so answer exactly rather than\n    // returning whichever list the arbitrary probe order happened to pick.\n    if (qi === 0) return []\n    const qn = new Float32Array(query.length)\n    for (let i = 0; i < query.length; i++) qn[i] = query[i]! * qi\n\n    const nprobe = Math.max(1, Math.min(opts.nprobe ?? this.params.nprobe, this.centroids.length))\n    const probes = this.topCentroids(qn, nprobe)\n    this.lastProbedPoints = 0\n\n    // Fold to one hit per RECORD by best chunk, exactly as the exact path does\n    // — `k` counts records, never fragments.\n    const best = new Map<number, { score: number; chunk: EmbeddingChunk | undefined }>()\n    for (const c of probes) {\n      this.lastProbedPoints += this.lists[c]!.length\n      for (const p of this.lists[c]!) {\n        const v = this.pVec[p]\n        if (v === undefined || v.length !== qn.length) continue\n        const score = dot(qn, v) * this.pInv[p]!\n        const r = this.pRecord[p]!\n        const cur = best.get(r)\n        if (cur === undefined || score > cur.score) best.set(r, { score, chunk: this.pChunk[p] })\n      }\n    }\n    const hits: VectorHit[] = []\n    for (const [r, b] of best) {\n      if (b.score < minScore) continue\n      hits.push(b.chunk ? { id: this.recordIds[r]!, score: b.score, chunk: b.chunk } : { id: this.recordIds[r]!, score: b.score })\n    }\n    hits.sort((a, b) => b.score - a.score)\n    return hits.slice(0, k)\n  }\n\n  /**\n   * A deterministic fixed-stride sample of the corpus, unit-normalised — the\n   * only place the index materialises normalised copies, and it is bounded by\n   * `sampleSize` rather than by `n`. A stride (not a random draw) so the fit\n   * is reproducible without spending the PRNG, which is saved for k-means++\n   * seeding where it actually buys recall.\n   */\n  private sampleUnitVectors(dim: number): Float32Array[] {\n    const slots = this.pVec.length\n    const want = Math.min(slots, this.params.sampleSize)\n    const stride = Math.max(1, Math.floor(slots / Math.max(1, want)))\n    const sample: Float32Array[] = []\n    for (let p = 0; p < slots && sample.length < want; p += stride) {\n      const v = this.pVec[p]\n      const inv = this.pInv[p]!\n      if (v === undefined || inv === 0 || v.length !== dim) continue\n      const u = new Float32Array(dim)\n      for (let i = 0; i < dim; i++) u[i] = v[i]! * inv\n      sample.push(u)\n    }\n    return sample\n  }\n\n  private firstDim(): number {\n    for (const v of this.pVec) if (v !== undefined && v.length > 0) return v.length\n    return 0\n  }\n\n  private topCentroids(qn: Float32Array, nprobe: number): number[] {\n    // nlist is capped at 256, so a full scan + partial selection is cheaper\n    // than any heap — and it is a rounding error next to the list scan.\n    const scores = new Float64Array(this.centroids.length)\n    for (let c = 0; c < this.centroids.length; c++) {\n      const cv = this.centroids[c]!\n      scores[c] = cv.length === qn.length ? dot(qn, cv) : -Infinity\n    }\n    const order: number[] = []\n    for (let c = 0; c < scores.length; c++) order.push(c)\n    order.sort((a, b) => scores[b]! - scores[a]!)\n    return order.slice(0, nprobe)\n  }\n\n  private assign(p: number): void {\n    const v = this.pVec[p]\n    if (v === undefined || this.centroids.length === 0) return\n    let bestC = 0\n    let bestS = -Infinity\n    const inv = this.pInv[p]!\n    for (let c = 0; c < this.centroids.length; c++) {\n      const cv = this.centroids[c]!\n      if (cv.length !== v.length) continue\n      const s = dot(cv, v) * inv\n      if (s > bestS) { bestS = s; bestC = c }\n    }\n    this.pList[p] = bestC\n    this.lists[bestC]!.push(p)\n  }\n\n  private recordSlot(id: string): number {\n    const existing = this.slotOfRecord.get(id)\n    if (existing !== undefined) return existing\n    const slot = this.recordIds.length\n    this.recordIds.push(id)\n    this.slotOfRecord.set(id, slot)\n    return slot\n  }\n\n  /** Materialise one record's points into free slots. `list` -1 = unassigned. */\n  private addPoints(v: StoredVector, list: number): void {\n    const r = this.recordSlot(v.id)\n    const pts: number[] = []\n    const push = (vec: Float32Array, chunk: EmbeddingChunk | undefined): void => {\n      const p = this.freeSlots.pop() ?? this.pVec.length\n      this.pVec[p] = vec\n      this.pInv[p] = invNorm(vec)\n      this.pRecord[p] = r\n      this.pChunk[p] = chunk\n      this.pList[p] = list\n      pts.push(p)\n      this.live++\n    }\n    if (v.chunks && v.chunks.length > 0) {\n      for (const c of v.chunks) push(c.vec, { id: c.id, start: c.start, end: c.end })\n    } else if (v.vec) {\n      push(v.vec, undefined)\n    }\n    if (pts.length > 0) this.pointsOfRecord.set(v.id, pts)\n  }\n}\n\n/**\n * Spherical k-means over a deterministic SAMPLE, not the corpus.\n *\n * Clustering all `n` points would cost `iterations · n · k · d`; assigning\n * them once costs `n · k · d`. Fitting on a sample makes the iterations free\n * relative to the single unavoidable assignment pass, which is the whole\n * reason IVF's build stays affordable at the #1360 gating scale.\n */\nfunction fitCentroids(sample: readonly Float32Array[], k: number, params: IvfParams): Float32Array[] {\n  if (sample.length === 0) return []\n  const dim = sample[0]!.length\n  const kk = Math.min(k, sample.length)\n\n  // k-means++ seeding on unit vectors, weighting by squared cosine distance.\n  const rand = mulberry32(params.seed)\n  const centroids: Float32Array[] = [sample[Math.floor(rand() * sample.length)]!.slice()]\n  const best = new Float64Array(sample.length).fill(Infinity)\n  while (centroids.length < kk) {\n    const last = centroids[centroids.length - 1]!\n    let total = 0\n    for (let i = 0; i < sample.length; i++) {\n      const d = 1 - dot(sample[i]!, last)\n      const w = d * d\n      if (w < best[i]!) best[i] = w\n      total += best[i]!\n    }\n    if (total === 0) break\n    let target = rand() * total\n    let pick = sample.length - 1\n    for (let i = 0; i < sample.length; i++) { target -= best[i]!; if (target <= 0) { pick = i; break } }\n    centroids.push(sample[pick]!.slice())\n  }\n\n  // Lloyd, spherical: mean, then re-normalise. An empty cluster KEEPS its\n  // previous centroid rather than being re-seeded — a dead list costs one\n  // wasted centroid comparison per query, whereas re-seeding mid-fit makes the\n  // result depend on the iteration count in a way nothing else here does.\n  for (let it = 0; it < params.iterations; it++) {\n    const sums = Array.from({ length: centroids.length }, () => new Float64Array(dim))\n    const counts = new Int32Array(centroids.length)\n    for (const u of sample) {\n      let bc = 0, bs = -Infinity\n      for (let c = 0; c < centroids.length; c++) {\n        const s = dot(u, centroids[c]!)\n        if (s > bs) { bs = s; bc = c }\n      }\n      const acc = sums[bc]!\n      for (let i = 0; i < dim; i++) acc[i]! += u[i]!\n      counts[bc]!++\n    }\n    for (let c = 0; c < centroids.length; c++) {\n      if (counts[c] === 0) continue\n      const acc = sums[c]!\n      let n = 0\n      for (let i = 0; i < dim; i++) n += acc[i]! * acc[i]!\n      if (n === 0) continue\n      const inv = 1 / Math.sqrt(n)\n      const cv = centroids[c]!\n      for (let i = 0; i < dim; i++) cv[i] = acc[i]! * inv\n    }\n  }\n  return centroids\n}\n"],"mappings":"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","names":[]}

package/dist/{json-schema-V3M5MUCM.js → json-schema-3SHX72CC.js}

@@ -22,6 +22,7 @@ function buildJsonSchema(desc, base) {
     if (f.unit !== void 0) prop["x-unit"] = f.unit;
     if (f.semanticType !== void 0) prop["x-semanticType"] = f.semanticType;
     if (f.sensitivity !== void 0) prop["x-sensitivity"] = f.sensitivity;
+    if (f.bulk !== void 0) prop["x-bulk"] = f.bulk;
     if (f.widget !== void 0) prop["x-widget"] = f.widget;
     if (f.editable === false) prop["x-readonly"] = true;
     if (f.money !== void 0) prop["x-money"] = f.money;
@@ -39,4 +40,4 @@ function buildJsonSchema(desc, base) {
 export {
   buildJsonSchema
 };
-//# sourceMappingURL=json-schema-V3M5MUCM.js.map
+//# sourceMappingURL=json-schema-3SHX72CC.js.map

package/dist/json-schema-3SHX72CC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-shape/introspection/json-schema.ts"],"sourcesContent":["/**\n * `buildJsonSchema` — pure overlay that merges describe() metadata onto a\n * base JSON Schema (from derivePersistedSchema) as `x-` extension keys.\n *\n * When no base JSON Schema is available (non-zod / unknown validator),\n * builds a minimal `{ type:'object', properties }` from describe()'s field\n * type tags. No static `import 'zod'` — validator derivation stays lazy.\n *\n * @module\n */\n\nimport type { CollectionDescription } from './describe.js'\n\n/** Map a DescribedField's type tag to a JSON-Schema `type`. */\nfunction jsonType(t: string): string {\n  switch (t) {\n    case 'number': return 'number'\n    case 'boolean': return 'boolean'\n    case 'array': return 'array'\n    case 'object': return 'object'\n    default: return 'string'\n  }\n}\n\n/** Overlay describe() metadata onto a base JSON Schema (or build a minimal one). */\nexport function buildJsonSchema(desc: CollectionDescription, base?: Record<string, unknown> | null): object {\n  const baseProps = (base?.['properties'] as Record<string, Record<string, unknown>> | undefined) ?? {}\n  const properties: Record<string, Record<string, unknown>> = {}\n  for (const f of desc.fields) {\n    const prop: Record<string, unknown> = { ...(baseProps[f.key] ?? { type: jsonType(f.type) }) }\n    prop['x-label'] = f.label\n    if (f.unit !== undefined) prop['x-unit'] = f.unit\n    if (f.semanticType !== undefined) prop['x-semanticType'] = f.semanticType\n    if (f.sensitivity !== undefined) prop['x-sensitivity'] = f.sensitivity\n    // Read-shape sensitivity (#1363). Orthogonal to x-sensitivity: a field can\n    // be 'public' and still belong to a corpus whose coverage is protected.\n    if (f.bulk !== undefined) prop['x-bulk'] = f.bulk\n    if (f.widget !== undefined) prop['x-widget'] = f.widget\n    if (f.editable === false) prop['x-readonly'] = true\n    if (f.money !== undefined) prop['x-money'] = f.money\n    if (f.ref !== undefined) prop['x-ref'] = f.ref.target\n    if (f.dict?.values) {\n      const labels: Record<string, string> = {}\n      for (const v of f.dict.values) if (v.label !== undefined) labels[v.value] = v.label\n      if (Object.keys(labels).length) prop['x-enumLabels'] = labels\n    }\n    // `x-classified` carries the whole classified block, incl. `equatable` when\n    // set — emitted ungated (boundary note on DescribedField.classified): a\n    // deployment wanting it gated can gate this behind its value-bearing door.\n    if (f.classified !== undefined) prop['x-classified'] = f.classified\n    properties[f.key] = prop\n  }\n  return base != null && typeof base === 'object'\n    ? { ...base, properties }\n    : { type: 'object', properties }\n}\n"],"mappings":";AAcA,SAAS,SAAS,GAAmB;AACnC,UAAQ,GAAG;AAAA,IACT,KAAK;AAAU,aAAO;AAAA,IACtB,KAAK;AAAW,aAAO;AAAA,IACvB,KAAK;AAAS,aAAO;AAAA,IACrB,KAAK;AAAU,aAAO;AAAA,IACtB;AAAS,aAAO;AAAA,EAClB;AACF;AAGO,SAAS,gBAAgB,MAA6B,MAA+C;AAC1G,QAAM,YAAa,OAAO,YAAY,KAA6D,CAAC;AACpG,QAAM,aAAsD,CAAC;AAC7D,aAAW,KAAK,KAAK,QAAQ;AAC3B,UAAM,OAAgC,EAAE,GAAI,UAAU,EAAE,GAAG,KAAK,EAAE,MAAM,SAAS,EAAE,IAAI,EAAE,EAAG;AAC5F,SAAK,SAAS,IAAI,EAAE;AACpB,QAAI,EAAE,SAAS,OAAW,MAAK,QAAQ,IAAI,EAAE;AAC7C,QAAI,EAAE,iBAAiB,OAAW,MAAK,gBAAgB,IAAI,EAAE;AAC7D,QAAI,EAAE,gBAAgB,OAAW,MAAK,eAAe,IAAI,EAAE;AAG3D,QAAI,EAAE,SAAS,OAAW,MAAK,QAAQ,IAAI,EAAE;AAC7C,QAAI,EAAE,WAAW,OAAW,MAAK,UAAU,IAAI,EAAE;AACjD,QAAI,EAAE,aAAa,MAAO,MAAK,YAAY,IAAI;AAC/C,QAAI,EAAE,UAAU,OAAW,MAAK,SAAS,IAAI,EAAE;AAC/C,QAAI,EAAE,QAAQ,OAAW,MAAK,OAAO,IAAI,EAAE,IAAI;AAC/C,QAAI,EAAE,MAAM,QAAQ;AAClB,YAAM,SAAiC,CAAC;AACxC,iBAAW,KAAK,EAAE,KAAK,OAAQ,KAAI,EAAE,UAAU,OAAW,QAAO,EAAE,KAAK,IAAI,EAAE;AAC9E,UAAI,OAAO,KAAK,MAAM,EAAE,OAAQ,MAAK,cAAc,IAAI;AAAA,IACzD;AAIA,QAAI,EAAE,eAAe,OAAW,MAAK,cAAc,IAAI,EAAE;AACzD,eAAW,EAAE,GAAG,IAAI;AAAA,EACtB;AACA,SAAO,QAAQ,QAAQ,OAAO,SAAS,WACnC,EAAE,GAAG,MAAM,WAAW,IACtB,EAAE,MAAM,UAAU,WAAW;AACnC;","names":[]}

package/dist/kernel/collection-config.d.ts

@@ -1,22 +1,3 @@
-/**
- * Collection construction config — the PURE half of the `Collection`
- * constructor.
- *
- * `resolveCollectionConfig` takes the raw `CollectionOpts` the Vault threads in
- * and resolves every `?? default`, every normalized/derived field, and runs the
- * pure construction-time validations (embeddings-on-CRDT, money-field paths,
- * deterministic-risk acknowledgement). It holds **no `this`** and performs no
- * external side effect — the only objects it allocates (`Set`s, `VectorSet`,
- * the CEK `Lru`) are the same instances the collection then owns by reference.
- *
- * The `this`-dependent construction (the search-index store whose persisted
- * callback closes over `this.searchContext()`, the `RecordCodec`, and the
- * SyncEngine conflict-resolver registration) stays in the constructor — those
- * genuinely capture the live instance (and the conflict-resolver closures close
- * over `conflictPolicy: ConflictPolicy<T>`, whose invariant-in-T custom-merge
- * signature can't be exposed via a method without breaking `Collection<T>`
- * assignability to `Collection<unknown>`).
- */
 import type { StrategyBag } from '../port/with/strategies.js';
 import type { NoydbStore, ConflictPolicy, CollectionConflictResolver, HistoryConfig, TierMode, CrossTierAccessEvent, VdigFieldPolicy } from './types.js';
 import type { EnclaveKey } from './enclave/index.js';
@@ -43,7 +24,7 @@ import type { FieldRef, Grain } from './via/graph.js';
 import type { FieldMeta } from '../with-shape/introspection/field-meta.js';
 import type { CollectionMeta } from '../with-shape/introspection/meta.js';
 import type { RefDescriptor } from './refs.js';
-import type { JoinableSource } from './query/index.js';
+import type { JoinableSource } from './query/relate/join.js';
 import { VectorSet, type EmbeddingDescriptor } from '../with-lookup/embeddings/index.js';
 import { Lru } from './cache/index.js';
 import type { ReadOnlyVaultFacade } from '../with-audit/guards/types.js';
@@ -210,6 +191,8 @@ export interface CollectionOpts<T> {
     embeddings?: EmbeddingDescriptor | undefined;
     /** — string fields exposed to client-side `retrieve()`. */
     textIndexes?: readonly string[] | undefined;
+    /** — subset of `textIndexes` recording token positions (phrase / proximity, #1354). */
+    textIndexPositions?: readonly string[] | undefined;
     /** — pre-build the lexical index on open (eager-only). */
     warmIndexOnOpen?: boolean | undefined;
     /** — persist the lexical index as an opaque encrypted blob at `_ftindex/<name>`. */
@@ -712,6 +695,7 @@ export declare function resolveCollectionConfig<T>(opts: CollectionOpts<T>): {
     } | undefined;
     i18nFields: Record<string, I18nTextDescriptor> | undefined;
     textIndexes: readonly string[] | undefined;
+    textIndexPositions: readonly string[] | undefined;
     embeddings: EmbeddingDescriptor | undefined;
     vectorSet: VectorSet | undefined;
     dictKeyFields: Record<string, StaticDictDescriptor<string> | DictKeyDescriptor<string>> | undefined;

package/dist/kernel/collection.d.ts

@@ -17,11 +17,11 @@ import type { GhostRecord } from './types.js';
 import type { StandardSchemaV1 } from './schema.js';
 import type { DiffEntry } from '../with-commit/history/diff.js';
 import { Query, ScanBuilder } from './query/index.js';
-import type { JoinableSource } from './query/index.js';
+import type { JoinableSource } from './query/relate/join.js';
 import { type CollectionIndexes } from '../with-lookup/indexing/eager-indexes.js';
 import { LazyQuery } from '../with-lookup/indexing/lazy-builder.js';
 import type { SearchOptions, SearchResult } from '../with-lookup/search/index.js';
-import type { RetrieveOptions, RetrieveHit } from '../with-lookup/search/retrieve-types.js';
+import type { RetrieveOptions, RetrieveHit, SimilarToOptions } from '../with-lookup/search/retrieve-types.js';
 import type { RefDescriptor } from './refs.js';
 import { type CollectionDescription, type DescribeOptions } from '../with-shape/introspection/describe.js';
 import type { CollectionConfig } from '../with-shape/introspection/types.js';
@@ -112,6 +112,10 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
     private readonly blobFields;
     private readonly blobTierPolicy;
     private readonly cache;
+    /** #1418 — mutation stamp for a derived-output memo, or `null` when one must NOT be used because a redundant re-write would still be observable (gate handler, history, sync, search) or there is no eager cache to stamp. The rules and their measured rationale live with the consumer, `with-formula/materialized-views/emit-memo.ts`. `_`-prefixed deliberately: `kernel-api-surface-golden` freezes the PUBLIC surface and this is an executor seam. @internal */
+    get _cacheStamp(): number | null;
+    /** #1439 — could a `beforePut` gate fire for THIS row? Asks each handler's declared scope, not merely whether any is registered — the bus is vault-wide, the gates are not. @internal */
+    _derivedWriteGated(record: Record<string, unknown>): boolean;
     private hydrated;
     /**
      * #606: ids known to carry a delete marker in the store — lets the #589
@@ -221,8 +225,12 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
     private i18nFields;
     /** The configured string fields exposed to `retrieve()`; `undefined` for ordinary collections (zero-cost). */
     private readonly textIndexes;
+    /** #1354 — the subset of `textIndexes` carrying positional postings (phrase / proximity). */
+    private readonly textIndexPositions;
     /** Session-scoped lexical index store; `undefined` (zero-cost) unless `textIndexes` is non-empty. */
     private readonly searchIndexStore;
+    /** Encrypted field-index sidecars (#1359); `null` (zero-cost) unless an index declared `persist: true`. */
+    private readonly fieldIndexStore;
     /** Embedding config for write-time vector derivation; `undefined` (zero-cost) for ordinary
      *  collections. When set, `put()` encodes the source field(s) and stores an encrypted `_vec` sidecar. */
     private readonly embeddings;
@@ -427,6 +435,8 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
         readonly fields: readonly string[];
         readonly unique?: boolean;
     }>;
+    /** #1447 — `field -> via brands covering it`, for `dumpSchema()`. Brand and field only, never a binding's config; see `via/pipeline.ts#fieldCoverage`. Consumed by walk.ts. */
+    getViaCoverage(): Record<string, readonly string[]> | undefined;
     /**
      * Aggregate all collection-level configuration options that are actively set
      * into a {@link CollectionConfig} snapshot. Returns `undefined` when no options
@@ -971,11 +981,7 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
     /** Retrieval (lexical | semantic | hybrid) — gated behind `searchStrategy: withSearch()`. */
     retrieve(query: string, opts?: RetrieveOptions<T>): Promise<RetrieveHit<T>[]>;
     /** Raw-vector kNN — gated behind `searchStrategy: withSearch()`. */
-    similarTo(vector: Float32Array, opts?: {
-        k?: number;
-        minScore?: number;
-        includeRecord?: boolean;
-    }): Promise<RetrieveHit<T>[]>;
+    similarTo(vector: Float32Array, opts?: SimilarToOptions): Promise<RetrieveHit<T>[]>;
     /** Opt-in bulk `_vec` re-derive (#788) — a plain collection has nothing to rebuild; gated behind `searchStrategy: withSearch()` otherwise. */
     rebuildEmbeddings(): Promise<{
         rebuilt: number;
@@ -1055,7 +1061,7 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
      * the filtered records directly (the API). Prefer the chainable
      * form for new code.
      *
-     * **Lazy-MV gap:** `query()` is synchronous and does NOT
+     * **Cold-collection gate (#1414):** until something has bulk-loaded this collection (`list()`, `get()`), every terminal returns a value that hydrates when AWAITED and throws `CollectionNotHydratedError` on synchronous use — an unloaded collection is not an empty one; see `query/hydration.ts`. **Lazy-MV gap:** `query()` is synchronous and does NOT
      * trigger lazy materialized-view resolve-on-read. If this
      * collection is a lazy MV's output and the MV is currently stale,
      * `query().toArray()` returns the pre-stale snapshot. To force a
@@ -1275,6 +1281,10 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
      * Never writes to the store and never fires write hooks, so it cannot loop.
      */
     _applyRemoteChange(id: string, action: 'put' | 'delete'): Promise<void>;
+    /** @internal #1362 — same as {@link _applyRemoteChange}, for a frame that carries NO verb.
+     *  A peer's claim about the verb is not evidence; the re-read decides it, exactly as
+     *  `_compensateRevertedWrite` does. Untrusted ingress is why the frame omits it. */
+    _applyRemoteSignal(id: string): Promise<void>;
     /**
      * Origin-tagged mutation choke point (#623 task 10) — the single dispatch
      * point every put/delete path funnels through, AFTER its own store write,
@@ -1401,6 +1411,15 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
      * vault-shared `_blob` DEK (enabling cross-collection deduplication).
      */
     blob(id: string): BlobSet;
+    /**
+     * #1452 — would an update of record `id` pass the `beforePut` gate bus right
+     * now? Runs the bus with `incoming = existing`, so closed periods and record
+     * guards refuse an attachment change exactly as they would refuse the
+     * record's own update. A record with no stored body (never written, marker,
+     * elevated tier) is not gated — attaching before the first `put()` was
+     * always allowed. @internal
+     */
+    _assertRecordMutable(id: string): Promise<void>;
     /** Get all records as encrypted envelopes (for dump). */
     dumpEnvelopes(): Promise<Record<string, EncryptedEnvelope>>;
     /**
@@ -1469,6 +1488,8 @@ export declare class Collection<T, S extends keyof T = never, Q extends keyof T
     /** Drop a record's encrypted _vec sidecar on erasure (a vector is text-invertible).
      *  Called by vault.ts forget() inside a resilient try/catch; residue is reported in ForgetResult. */
     _purgeVector(id: string): Promise<void>;
+    /** @internal #1359 — force an immediate sidecar write, cancelling the debounce. No-op when none opted in. */
+    _flushFieldIndexes(): Promise<void>;
     /** Drop the persisted lexical-index blob (forget/erasure): an opaque
      *  all-records index must not survive crypto-shred. Idempotent; no-op without persist. */
     _purgeSearchIndex(): Promise<void>;

package/dist/kernel/enclave/crypto.d.ts

@@ -93,6 +93,13 @@ export declare function deriveSecretKey(secret: string, salt: Uint8Array, params
 }): Promise<CryptoKey>;
 /** Generate a random AES-256-GCM data encryption key. */
 export declare function generateDEK(): Promise<CryptoKey>;
+/** Serialize a DEK set to `{ collection: base64(rawKey) }`. */
+export declare function exportDekSet(deks: Map<string, CryptoKey>): Promise<Record<string, string>>;
+/**
+ * Reverse of {@link exportDekSet}. Keys come back extractable AES-GCM
+ * (`encrypt`/`decrypt`), matching what `generateDEK` mints.
+ */
+export declare function importDekSet(exported: Record<string, string>): Promise<Map<string, CryptoKey>>;
 /** Wrap (encrypt) a DEK with a KEK using AES-KW. Returns base64 string. */
 export declare function wrapKey(dek: CryptoKey, kek: CryptoKey): Promise<string>;
 /** Unwrap (decrypt) a DEK from base64 string using a KEK. */
@@ -331,5 +338,14 @@ export declare function decryptDeterministic(ivBase64: string, dataBase64: strin
 export declare function generateIV(): Uint8Array;
 /** Generate a random 32-byte salt for PBKDF2. */
 export declare function generateSalt(): Uint8Array;
+/**
+ * Mint a fresh recovery secret — the high-entropy value a recovery profile
+ * wraps the DEK set under and then hands out (Shamir splits it into shares;
+ * paper prints it). Not a salt: a salt is public, this is not, and a fork
+ * may size them differently. The reference enclave returns 32 bytes.
+ *
+ * Callers must zero the buffer once it has been wrapped and split.
+ */
+export declare function generateRecoverySecret(): Uint8Array;
 export declare function bufferToBase64(buffer: ArrayBuffer | Uint8Array): string;
 export declare function base64ToBuffer(base64: string): Uint8Array<ArrayBuffer>;

package/dist/kernel/enclave/index.d.ts

@@ -57,7 +57,7 @@
  */
 export type { EnclaveKey, EncryptResult } from './crypto.js';
 export { encrypt, decrypt, encryptBytes, decryptBytes, encryptBytesWithAAD, decryptBytesWithAAD, encryptDeterministic, decryptDeterministic, sha256Hex, hmacSha256Hex, deriveBlobAddressKey, } from './crypto.js';
-export { deriveKey, deriveSecretKey, generateDEK, generateSalt, generateIV, wrapKey, unwrapKey, bufferToBase64, base64ToBuffer, derivePresenceKey, deriveDeterministicKey, deriveSealedFieldKey, deriveSealedFieldKeyFromCek, wrapCek, unwrapCek, importCek, encodeEchoParts, deriveEchoKey, } from './crypto.js';
+export { deriveKey, deriveSecretKey, generateDEK, exportDekSet, importDekSet, generateSalt, generateRecoverySecret, generateIV, wrapKey, unwrapKey, bufferToBase64, base64ToBuffer, derivePresenceKey, deriveDeterministicKey, deriveSealedFieldKey, deriveSealedFieldKeyFromCek, wrapCek, unwrapCek, importCek, encodeEchoParts, deriveEchoKey, } from './crypto.js';
 export type { SecretKeyUsage } from './crypto.js';
 export type { EchoSecretParts } from './crypto.js';
 export { resolveStableCek, rewrapBodyToDek, rewrapEnvelope, applyRewrappedBody, isRewrappedUnder } from './record-keys/lifecycle.js';

package/dist/kernel/enclave/record-keys/record-codec.d.ts

@@ -97,6 +97,18 @@ export interface RecordCodecContext<T> {
      * snapshot.
      */
     via: ViaPipeline | undefined;
+    /**
+     * Read-coverage observer (#1363), resolved once per Collection from
+     * `strategies.coverage.observer(...)`. `undefined` for every un-opted-in
+     * deployment AND for every collection the sensor does not account for, so
+     * the decrypt path costs one `!== undefined` test.
+     *
+     * ⛔⛔ TELEMETRY, NOT A CONTROL: an insider holding the device and local keys
+     * holds the DEK, so this observes an extraction it cannot prevent. It exists
+     * to make one visible early, attributable and loud. It may never grow a
+     * return value — a decrypt is not gated on it, and nothing here may refuse.
+     */
+    readonly onDecrypt?: ((id: string) => void) | undefined;
 }
 export declare class RecordCodec<T> {
     private readonly ctx;
@@ -230,6 +242,19 @@ export declare class RecordCodec<T> {
      * perfectly good record (#1041).
      */
     decryptJsonString(ref: RecordRef, envelope: EncryptedEnvelope): Promise<string | null>;
+    /**
+     * Fire the read-coverage observer for a successful record decrypt (#1363).
+     *
+     * ⚠️ ONLY for this codec's OWN collection. `ref.collection` can be a storage
+     * identity that is not the live collection — a history/version address, the
+     * `_vec` vector sidecar, the `_ft` lexical index (#1041) — and their ids are
+     * not this corpus's ids, so counting them would corrupt the very estimate
+     * the sensor exists to produce. The cost is a deliberate UNDER-count: a
+     * principal reading the corpus through its history sidecar is not accounted.
+     * A sensor that under-counts is honest; one that inflates cries wolf and
+     * gets turned off. Recorded rather than papered over.
+     */
+    private observeDecrypt;
     /**
      * Unseal a single `_sealed[field]` slot to its plaintext value: derive the
      * per-field key off the collection DEK, AES-GCM-decrypt the `iv:data` blob,