@noy-db/hub 0.2.0-pre.17 → 0.2.0-pre.19

package/dist/{chunk-D77ZQSQQ.js → chunk-KYGGXXT6.js}

@@ -7,10 +7,10 @@ import {
 import {
   TxContext,
   revertExecuted
-} from "./chunk-ZNGPEV5J.js";
+} from "./chunk-V3VIRTTE.js";
 import {
   OverlayedCollection
-} from "./chunk-XMHUK5PN.js";
+} from "./chunk-X7FJMKT3.js";
 import {
   NO_AGGREGATE,
   Query,
@@ -20,36 +20,36 @@ import {
   decodeMoneyFields,
   quantizeMoneyFields,
   validateMoneyFieldPaths
-} from "./chunk-HGVSHKZW.js";
+} from "./chunk-3Q2AOPLT.js";
 import {
   EXPORT_AUDIT_COLLECTION,
   createExportBlobsHandle,
   runCompaction
-} from "./chunk-KCEHMDZF.js";
+} from "./chunk-U7JNBSS3.js";
 import {
   LazyQuery,
   decodeIdxId,
   encodeIdxId
-} from "./chunk-NYSYPFXJ.js";
+} from "./chunk-B6E5IRPJ.js";
 import {
   canonicalGroupKey
-} from "./chunk-7H2GEJ3O.js";
+} from "./chunk-OBMYMKGO.js";
 import {
   readPath
-} from "./chunk-J7RWBXFY.js";
+} from "./chunk-LSIIPKYT.js";
 import {
   SCHEMAS_COLLECTION,
   loadPersistedSchema,
   resolveManagedSecret,
   savePersistedSchema,
   saveSealedPassphrase
-} from "./chunk-AEIKD3PP.js";
+} from "./chunk-VNUE6FHP.js";
 import {
   loadPublicEnvelope,
   readPublicEnvelope,
   savePublicEnvelope,
   validatePublicEnvelopeInput
-} from "./chunk-YYVZYTWW.js";
+} from "./chunk-E66DSTJP.js";
 import {
   buildTombstone,
   isTombstone,
@@ -58,17 +58,19 @@ import {
   rewrapBodyToDek,
   rotateRecordCek,
   sealRecordToHost
-} from "./chunk-U5QCMH3W.js";
+} from "./chunk-GKQAU52M.js";
 import {
   PERIODS_COLLECTION
-} from "./chunk-BH3X5L6A.js";
+} from "./chunk-YZE6C3TQ.js";
 import {
-  getAtPath,
   isDictCollectionName,
-  isStaticDictDescriptor,
+  isStaticDictDescriptor
+} from "./chunk-H42KZXNV.js";
+import {
+  getAtPath,
   resolvePolicy,
   setAtPathInPlace
-} from "./chunk-ROPJVUG3.js";
+} from "./chunk-VEIVAYJ7.js";
 import {
   ManagedRecoveryNotEnrolledError,
   PolicyDeniedError,
@@ -90,11 +92,11 @@ import {
   saveShamirRecoveryEntries,
   updateAuthenticator,
   writeMagicLinkGrant
-} from "./chunk-QHM6XEAH.js";
+} from "./chunk-S22UOMHM.js";
 import {
   assertTierAccess,
   dekKey
-} from "./chunk-5LIROIDM.js";
+} from "./chunk-FBLAWK6A.js";
 import {
   USER_ENVELOPE_COLLECTION,
   assertKeyringOpenAllowed,
@@ -119,7 +121,7 @@ import {
   rotateKeys,
   saveUserEnvelope,
   updateKeyringIdentity
-} from "./chunk-BSZOCSDZ.js";
+} from "./chunk-M3FPNTO2.js";
 import {
   INDEXED_STORE_POLICY
 } from "./chunk-2QR2PQTT.js";
@@ -129,7 +131,7 @@ import {
 import {
   LEDGER_COLLECTION,
   LEDGER_DELTAS_COLLECTION
-} from "./chunk-DWEBTE2W.js";
+} from "./chunk-YX333DPS.js";
 import {
   sha256Hex as sha256Hex2
 } from "./chunk-PDVP3C2I.js";
@@ -141,11 +143,11 @@ import {
   readDottedPath,
   rebuildSubjectIndex,
   removeSubjectRef
-} from "./chunk-I5IUYN7B.js";
+} from "./chunk-KNKNOJFS.js";
 import {
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION
-} from "./chunk-SISBMAPO.js";
+} from "./chunk-SHIUFIPW.js";
 import {
   decrypt,
   encrypt,
@@ -153,13 +155,14 @@ import {
   sha256Hex,
   unwrapCek,
   wrapCek
-} from "./chunk-UNTGHX5A.js";
+} from "./chunk-OKOKPYWH.js";
 import {
   AlreadyElevatedError,
   AttestationError,
   BackupCorruptedError,
   BackupLedgerError,
   ConflictError,
+  DerivationCapExceededError,
   ElevationExpiredError,
   ExportCapabilityError,
   ForgetStrategyNotConfiguredError,
@@ -191,7 +194,7 @@ import {
   UnsupportedIndexOptionError,
   ValidationError,
   VaultTemplateNotFoundError
-} from "./chunk-ZEGSDPB7.js";
+} from "./chunk-DJF3FXW5.js";
 
 // src/policy/storage.ts
 var META_COLLECTION = "_meta";
@@ -506,6 +509,74 @@ var DISABLED_STATE = {
   getPersistedIndexes: () => null
 };
 
+// src/search/tokenize.ts
+var WORD = /[\p{L}\p{N}]+/gu;
+var tokenize = (text) => {
+  if (!text) return [];
+  return text.normalize("NFKC").toLowerCase().match(WORD) ?? [];
+};
+
+// src/search/scan.ts
+var K1 = 1.2;
+var B = 0.75;
+function fieldText(record, field) {
+  const v = record[field];
+  if (typeof v === "string") return v;
+  if (v === null || v === void 0) return "";
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return "";
+}
+function searchScan(entries, field, query, opts = {}, tokenizer = tokenize) {
+  const queryTerms = tokenizer(query);
+  if (queryTerms.length === 0) return [];
+  const match = opts.match ?? "any";
+  const usePrefix = opts.prefix ?? false;
+  const exactTerms = usePrefix ? queryTerms.slice(0, -1) : queryTerms;
+  const prefixTerm = usePrefix ? queryTerms[queryTerms.length - 1] : void 0;
+  const docs = entries.map((e) => ({ id: e.id, record: e.record, terms: tokenizer(fieldText(e.record, field)) }));
+  const N = docs.length || 1;
+  const df = /* @__PURE__ */ new Map();
+  let totalLen = 0;
+  for (const d of docs) {
+    totalLen += d.terms.length;
+    for (const t of new Set(d.terms)) df.set(t, (df.get(t) ?? 0) + 1);
+  }
+  const avgdl = totalLen / N || 1;
+  let prefixDf = 0;
+  if (prefixTerm !== void 0) {
+    for (const d of docs) {
+      if (d.terms.some((t) => t.startsWith(prefixTerm))) prefixDf++;
+    }
+  }
+  const requiredCount = exactTerms.length + (prefixTerm !== void 0 ? 1 : 0);
+  const results = [];
+  for (const d of docs) {
+    const tf = /* @__PURE__ */ new Map();
+    for (const t of d.terms) tf.set(t, (tf.get(t) ?? 0) + 1);
+    const matched = [];
+    for (const qt of exactTerms) {
+      const c = tf.get(qt) ?? 0;
+      if (c > 0) matched.push({ tf: c, df: df.get(qt) ?? 0 });
+    }
+    if (prefixTerm !== void 0) {
+      let ptf = 0;
+      for (const [t, c] of tf) if (t.startsWith(prefixTerm)) ptf += c;
+      if (ptf > 0) matched.push({ tf: ptf, df: prefixDf });
+    }
+    if (matched.length === 0) continue;
+    if (match === "all" && matched.length < requiredCount) continue;
+    let score = 0;
+    for (const m of matched) {
+      const idf = Math.log(1 + (N - m.df + 0.5) / (m.df + 0.5));
+      const denom = m.tf + K1 * (1 - B + B * (d.terms.length / avgdl));
+      score += idf * (m.tf * (K1 + 1) / (denom || 1));
+    }
+    results.push({ id: d.id, score, record: d.record });
+  }
+  results.sort((a, b) => b.score - a.score);
+  return opts.limit !== void 0 ? results.slice(0, opts.limit) : results;
+}
+
 // src/indexing/unique-constraints.ts
 var UniqueConstraintSet = class {
   constructor(collectionName, uniqueDefs) {
@@ -837,7 +908,7 @@ async function resolveStaleOnRead(accessor, outputCollection, id) {
     }
     const sourceWithId = { ...source, id };
     if (DerivationExecutor === null) {
-      ({ DerivationExecutor } = await import("./executor-CFFWPWBJ.js"));
+      ({ DerivationExecutor } = await import("./executor-OKFLQCDW.js"));
     }
     const ctx = { vault: accessor.getReadOnlyFacade() };
     const result = await DerivationExecutor.run(spec, sourceWithId, 0, strategyHash, ctx);
@@ -875,6 +946,15 @@ async function resolveStaleOnRead(accessor, outputCollection, id) {
 }
 
 // src/collection.ts
+function selfWriteFieldEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
 var fallbackWarned = /* @__PURE__ */ new Set();
 function warnOnceFallback(adapterName) {
   if (fallbackWarned.has(adapterName)) return;
@@ -1373,7 +1453,7 @@ var Collection = class {
       }
     }
     if (this.materializedViewSource !== void 0) {
-      const { resolveStaleMVOnRead } = await import("./stale-TOA36SRK.js");
+      const { resolveStaleMVOnRead } = await import("./stale-NTEV5SLX.js");
       await resolveStaleMVOnRead(this.materializedViewSource, this.name);
     }
     let record;
@@ -1783,7 +1863,7 @@ var Collection = class {
       if (mode === "eager") {
         if (executor === null) {
           ;
-          ({ MaterializedViewExecutor: executor } = await import("./executor-3W63Y44O.js"));
+          ({ MaterializedViewExecutor: executor } = await import("./executor-44R5CUS2.js"));
         }
         await executor.refresh(reg, {
           getCollection: (name) => this.materializedViewSource.getCollection(name),
@@ -1792,7 +1872,7 @@ var Collection = class {
         });
       } else if (mode === "lazy") {
         if (staleHelpers === null) {
-          staleHelpers = await import("./stale-TOA36SRK.js");
+          staleHelpers = await import("./stale-NTEV5SLX.js");
         }
         staleHelpers.markMVStale(registry, reg.spec.name);
       }
@@ -1809,6 +1889,111 @@ var Collection = class {
    * output (carries `_derivedFrom`) — defensive guard against missed
    * cycle detection.
    */
+  /**
+   * @internal #376 — the RAW stored record (canonical-money form, i18n maps
+   * intact), WITHOUT the locale resolution `get()` applies. Used as the
+   * patch base for self-write reverse-denorm so writing back never clobbers
+   * an i18n map or re-quantizes money incorrectly. Returns null for
+   * missing / tombstoned records.
+   */
+  async _getStoredRecord(id) {
+    let raw;
+    if (this.lazy && this.lru) {
+      const cached = this.lru.get(id);
+      if (cached) raw = cached.record;
+      else {
+        const env = await this.adapter.get(this.vault, this.name, id);
+        if (!env || isTombstone(env, this.encrypted)) return null;
+        raw = await this.decryptRecord(env, { id });
+        if (raw === null) return null;
+        this.lru.set(id, { record: raw, version: env._v }, estimateRecordBytes(raw));
+      }
+    } else {
+      await this.ensureHydrated();
+      raw = this.cache.get(id)?.record ?? null;
+    }
+    if (raw === null) return null;
+    return canonicalizeStoredMoney(raw, this.moneyFields);
+  }
+  /**
+   * @internal #376 — ids of records whose top-level `field` equals `value`.
+   * Uses the FK index when the field is indexed (O(matches)); otherwise a
+   * linear scan (O(N) — fine for small child sets; index the FK to scale).
+   */
+  async _findMatchingIds(field, value) {
+    const hit = this.getIndexes()?.lookupEqual(field, value);
+    if (hit) return [...hit];
+    const target = String(value);
+    const matches = (rec) => {
+      const fv = rec[field];
+      return (typeof fv === "string" || typeof fv === "number") && String(fv) === target;
+    };
+    if (!this.lazy) {
+      await this.ensureHydrated();
+      const out2 = [];
+      for (const [rid, e] of this.cache) {
+        if (matches(e.record)) out2.push(rid);
+      }
+      return out2;
+    }
+    const ids = await this.adapter.list(this.vault, this.name);
+    const out = [];
+    for (const rid of ids) {
+      const raw = await this._getStoredRecord(rid);
+      if (raw !== null && matches(raw)) out.push(rid);
+    }
+    return out;
+  }
+  /**
+   * @internal #376 slice 2 — recompute a rollup aggregate onto the parent.
+   * Gathers every child of `parentId`, runs `compute`, and patches only the
+   * rollup `field` onto the parent's raw stored record (value-equality
+   * guarded). No-op when the parent record does not exist.
+   */
+  async recomputeRollup(spec, parentId) {
+    if (this.derivationSource === void 0 || spec.rollup === void 0) return;
+    const { from, key, field, compute } = spec.rollup;
+    const into = spec.source;
+    const intoColl = this.derivationSource.getCollection(into);
+    const base = await intoColl._getStoredRecord(parentId);
+    if (base === null) return;
+    const fromColl = this.derivationSource.getCollection(from);
+    const childIds = await fromColl._findMatchingIds(key, parentId);
+    const children = [];
+    for (const cid of childIds) {
+      const c = await fromColl.get(cid);
+      if (c !== null && c !== void 0) children.push(c);
+    }
+    const newValue = compute(children);
+    if (selfWriteFieldEqual(base[field], newValue)) return;
+    const patched = { ...base, [field]: newValue };
+    const txCtx = this.derivationSource.getActiveTxContext();
+    if (txCtx !== null) {
+      const prior = await this.adapter.get(this.vault, into, parentId);
+      txCtx._executed.push({
+        op: { type: "put", vaultName: this.vault, collectionName: into, id: parentId },
+        priorEnvelope: prior
+      });
+    }
+    await intoColl.put(parentId, patched);
+  }
+  /**
+   * @internal #376 slice 2 — fire any rollups for which THIS collection is the
+   * child `from`, recomputing the affected parent after a child delete. Called
+   * from the delete path with the just-removed record's key value. Other
+   * derivation kinds do not react to deletes (unchanged).
+   */
+  async dispatchRollupsOnDelete(deleted) {
+    if (this.derivationSource === void 0) return;
+    const registry = this.derivationSource.registry();
+    const rec = deleted;
+    for (const { spec } of registry.strategiesForSource(this.name)) {
+      if (!spec.rollup || spec.rollup.from !== this.name) continue;
+      const kv = rec[spec.rollup.key];
+      if (typeof kv !== "string" && typeof kv !== "number") continue;
+      await this.recomputeRollup(spec, String(kv));
+    }
+  }
   async dispatchDerivations(id, record, version) {
     if (this.derivationSource === void 0) return;
     const incoming = canonicalizeStoredMoney(record, this.moneyFields);
@@ -1819,29 +2004,60 @@ var Collection = class {
     let DerivationExecutor = null;
     for (const { spec, strategyHash } of strategies) {
       const mode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
-      if (mode === "eager") {
-        if (DerivationExecutor === null) {
-          ({ DerivationExecutor } = await import("./executor-CFFWPWBJ.js"));
-        }
-        let sourceWithId;
-        let sourceVersion = version;
-        if (spec.source === this.name) {
-          sourceWithId = { ...incoming, id };
+      if (spec.rollup) {
+        if (mode !== "eager") continue;
+        let parentId;
+        if (this.name === spec.rollup.from) {
+          const kv = incoming[spec.rollup.key];
+          parentId = typeof kv === "string" || typeof kv === "number" ? String(kv) : null;
         } else {
-          const primary = await this.derivationSource.getCollection(spec.source).get(id);
-          if (primary === null || primary === void 0) continue;
-          sourceWithId = { ...primary, id };
-          sourceVersion = 0;
+          parentId = id;
+        }
+        if (parentId !== null) await this.recomputeRollup(spec, parentId);
+        continue;
+      }
+      const isSource = spec.source === this.name;
+      const isSibling = !isSource && (spec.sources?.includes(this.name) ?? false);
+      const trigger = !isSource && !isSibling ? spec.triggerBy?.find((t) => t.collection === this.name) : void 0;
+      const runs = [];
+      if (isSource) {
+        runs.push({ input: { ...incoming, id }, base: incoming, runId: id, version });
+      } else if (isSibling) {
+        const p = await this.derivationSource.getCollection(spec.source).get(id);
+        if (p !== null && p !== void 0) {
+          const raw = await this.derivationSource.getCollection(spec.source)._getStoredRecord(id);
+          runs.push({ input: { ...p, id }, base: raw ?? p, runId: id, version: 0 });
+        }
+      } else if (trigger) {
+        const srcColl = this.derivationSource.getCollection(spec.source);
+        const ids = await srcColl._findMatchingIds(trigger.on, id);
+        if (trigger.maxFanout !== void 0 && ids.length > trigger.maxFanout) {
+          throw new DerivationCapExceededError(`triggerBy ${this.name}\u2192${spec.source}`, ids.length, trigger.maxFanout);
         }
+        for (const sid of ids) {
+          const raw = await srcColl._getStoredRecord(sid);
+          if (raw === null) continue;
+          runs.push({ input: { ...raw, id: sid }, base: raw, runId: sid, version: 0 });
+        }
+      }
+      if (runs.length === 0) continue;
+      if (mode !== "eager") {
+        for (const run of runs) await markStale(registry, spec, run.runId);
+        continue;
+      }
+      if (DerivationExecutor === null) {
+        ({ DerivationExecutor } = await import("./executor-OKFLQCDW.js"));
+      }
+      for (const run of runs) {
         const ctx = { vault: this.derivationSource.getReadOnlyFacade() };
-        const result = await DerivationExecutor.run(spec, sourceWithId, sourceVersion, strategyHash, ctx);
+        const result = await DerivationExecutor.run(spec, run.input, run.version, strategyHash, ctx);
         for (const key of Object.keys(spec.outputs)) {
           const out = result.outputs[key];
           if (!out) continue;
           if (out.kind === "failed") {
             const err = out.error;
             if (spec.strict) throw err;
-            console.warn(`[derivation] output "${key}" for source "${spec.source}" id="${id}" failed:`, err);
+            console.warn(`[derivation] output "${key}" for source "${spec.source}" id="${run.runId}" failed:`, err);
             continue;
           }
           const outSpec = spec.outputs[key];
@@ -1849,12 +2065,12 @@ var Collection = class {
           const outputCollection = this.derivationSource.getCollection(outSpec.collection);
           const txCtx = this.derivationSource.getActiveTxContext();
           if (out.kind === "array") {
-            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-FIJJ46YG.js");
+            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-DCQWJQ6S.js");
             const prior = await loadFanoutSidecar(
               this.adapter,
               this.vault,
               spec.source,
-              id,
+              run.runId,
               key
             );
             const prevKeys = new Set(prior?.keys ?? []);
@@ -1881,7 +2097,7 @@ var Collection = class {
             }
             await saveFanoutSidecar(this.adapter, this.vault, {
               source: spec.source,
-              sourceId: id,
+              sourceId: run.runId,
               outputKey: key,
               outputCollection: outSpec.collection,
               keys: newKeysList
@@ -1889,25 +2105,44 @@ var Collection = class {
             continue;
           }
           if (out.skipped === true) {
-            await outputCollection._internalDelete(id, txCtx);
+            await outputCollection._internalDelete(run.runId, txCtx);
+            continue;
+          }
+          if (outSpec.shape === "record" && outSpec.denorm !== void 0 && outSpec.collection === spec.source) {
+            const value = out.value;
+            const patched = { ...run.base };
+            let changed = false;
+            for (const f of outSpec.denorm) {
+              if (!selfWriteFieldEqual(run.base[f], value[f])) {
+                patched[f] = value[f];
+                changed = true;
+              }
+            }
+            if (!changed) continue;
+            if (txCtx !== null) {
+              const prior = await this.adapter.get(this.vault, outSpec.collection, run.runId);
+              txCtx._executed.push({
+                op: { type: "put", vaultName: this.vault, collectionName: outSpec.collection, id: run.runId },
+                priorEnvelope: prior
+              });
+            }
+            await outputCollection.put(run.runId, patched);
             continue;
           }
           if (txCtx !== null) {
-            const prior = await this.adapter.get(this.vault, outSpec.collection, id);
+            const prior = await this.adapter.get(this.vault, outSpec.collection, run.runId);
             txCtx._executed.push({
               op: {
                 type: "put",
                 vaultName: this.vault,
                 collectionName: outSpec.collection,
-                id
+                id: run.runId
               },
               priorEnvelope: prior
             });
           }
-          await outputCollection.put(id, out.value);
+          await outputCollection.put(run.runId, out.value);
         }
-      } else {
-        await markStale(registry, spec, id);
       }
     }
   }
@@ -2124,6 +2359,7 @@ var Collection = class {
     if (!internal) {
       await this.dispatchMaterializedViewsOnDelete(id);
       await this.dispatchArrayDerivationsOnDelete(id);
+      if (existing) await this.dispatchRollupsOnDelete(existing.record);
     }
   }
   /**
@@ -2192,7 +2428,7 @@ var Collection = class {
       for (const [outputKey, outSpec] of Object.entries(spec.outputs)) {
         if (outSpec.shape !== "array") continue;
         if (helpers === null) {
-          helpers = await import("./fanout-sidecar-FIJJ46YG.js");
+          helpers = await import("./fanout-sidecar-DCQWJQ6S.js");
         }
         const sidecar = await helpers.loadFanoutSidecar(
           this.adapter,
@@ -2232,7 +2468,7 @@ var Collection = class {
       if (mode === "eager") {
         if (executor === null) {
           ;
-          ({ MaterializedViewExecutor: executor } = await import("./executor-3W63Y44O.js"));
+          ({ MaterializedViewExecutor: executor } = await import("./executor-44R5CUS2.js"));
         }
         await executor.refresh(reg, {
           getCollection: (name) => this.materializedViewSource.getCollection(name),
@@ -2241,7 +2477,7 @@ var Collection = class {
         });
       } else if (mode === "lazy") {
         if (staleHelpers === null) {
-          staleHelpers = await import("./stale-TOA36SRK.js");
+          staleHelpers = await import("./stale-NTEV5SLX.js");
         }
         staleHelpers.markMVStale(registry, reg.spec.name);
       }
@@ -2264,7 +2500,7 @@ var Collection = class {
       );
     }
     if (this.materializedViewSource !== void 0) {
-      const { resolveStaleMVOnRead } = await import("./stale-TOA36SRK.js");
+      const { resolveStaleMVOnRead } = await import("./stale-NTEV5SLX.js");
       await resolveStaleMVOnRead(this.materializedViewSource, this.name);
     }
     await this.ensureHydrated();
@@ -2280,6 +2516,29 @@ var Collection = class {
   hasReadTransforms() {
     return this.moneyFields !== void 0 && Object.keys(this.moneyFields).length > 0 || this.i18nFields !== void 0 && Object.keys(this.i18nFields).length > 0 || this.dictKeyFields !== void 0 && Object.keys(this.dictKeyFields).length > 0;
   }
+  /**
+   * Scan-mode full-text search over a plain-text `field` (#308). Decrypts the
+   * collection in memory and ranks records by BM25 against the tokenized query.
+   * **Zero added store leakage** — pure client-side scan; nothing searchable is
+   * written to the store. (A store-usable blind index for at-scale search is a
+   * separate, gated opt-in — see the #308 design note.) Eager mode only.
+   *
+   * `opts.match` (`'any'` default | `'all'`), `opts.prefix` (last query term as
+   * a prefix → typeahead), `opts.limit` (top-N). Returns `{ id, score, record }`
+   * ranked by descending score. The default tokenizer is word-boundary based —
+   * see `src/search/tokenize.ts` for the Thai/CJK caveat.
+   */
+  async search(field, query, opts = {}) {
+    if (this.lazy) {
+      throw new Error(
+        `Collection "${this.name}": search() (scan mode) requires eager mode (prefetch: true). A store-usable blind index for lazy / at-scale search is a separate gated opt-in (#308).`
+      );
+    }
+    await this.ensureHydrated();
+    const entries = [];
+    for (const [id, e] of this.cache) entries.push({ id, record: e.record });
+    return searchScan(entries, field, query, opts);
+  }
   // ─── Bulk operations ─────────────────────────────────────
   /**
    * Put many records in one call. Each item is processed sequentially
@@ -2457,6 +2716,10 @@ var Collection = class {
       leftCollection,
       resolveRef: (field) => resolver.resolveRef(leftCollection, field),
       resolveSource: (collectionName) => resolver.resolveSource(collectionName),
+      // #285 §3 — flow the vault/collection default locale to joins so a
+      // joined i18n field resolves like get()/list() when no per-call
+      // locale is given; toArray({ locale }) overrides it.
+      ...this.defaultLocale !== void 0 ? { defaultLocale: this.defaultLocale } : {},
       ...resolver.resolveDictSource ? { resolveDictSource: (field) => resolver.resolveDictSource(leftCollection, field) } : {}
     } : void 0;
     return new Query(source, void 0, joinContext, this.aggregateStrategy);
@@ -2545,7 +2808,10 @@ var Collection = class {
         };
         this.emitter.on("change", handler);
         return () => this.emitter.off("change", handler);
-      }
+      },
+      // #285 §3 — expose this (right-side) collection's i18nText descriptors so
+      // the join executor can resolve joined i18n fields at the `join` layer.
+      ...this.i18nFields !== void 0 ? { i18nFields: this.i18nFields } : {}
     };
   }
   /**
@@ -2778,6 +3044,10 @@ var Collection = class {
       leftCollection,
       resolveRef: (field) => resolver.resolveRef(leftCollection, field),
       resolveSource: (collectionName) => resolver.resolveSource(collectionName),
+      // #285 §3 — flow the vault/collection default locale to joins so a
+      // joined i18n field resolves like get()/list() when no per-call
+      // locale is given; toArray({ locale }) overrides it.
+      ...this.defaultLocale !== void 0 ? { defaultLocale: this.defaultLocale } : {},
       ...resolver.resolveDictSource ? { resolveDictSource: (field) => resolver.resolveDictSource(leftCollection, field) } : {}
     } : void 0;
     return new ScanBuilder(
@@ -3178,14 +3448,15 @@ var Collection = class {
       (d) => isStaticDictDescriptor(d) && d.displayLocale !== void 0
     );
     if (!locale && !hasStaticDisplay) return result;
+    const layer = localeOpts?._layer ?? "read";
     if (locale && hasI18n && this.i18nFields) {
-      result = this.i18nStrategy.applyI18nLocale(result, this.i18nFields, locale, localeOpts?.fallback);
+      result = this.i18nStrategy.applyI18nLocale(result, this.i18nFields, locale, localeOpts?.fallback, layer);
     }
     if (hasDict && this.dictKeyFields && this.dictLabelResolver && locale !== "raw") {
       const withLabels = { ...result };
       const resolver = this.dictLabelResolver;
       for (const [field, desc] of Object.entries(this.dictKeyFields)) {
-        const policy = desc.onMissing ? resolvePolicy(desc.onMissing, "read") : "null";
+        const policy = desc.onMissing ? resolvePolicy(desc.onMissing, layer) : "null";
         const fallback = policy === "substitute" ? localeOpts?.fallback ?? desc.substitute : localeOpts?.fallback;
         const effLocale = locale ?? (isStaticDictDescriptor(desc) ? desc.displayLocale : void 0);
         const resolveKey = async (key) => {
@@ -3334,6 +3605,34 @@ var Collection = class {
       }
     }
   }
+  /**
+   * @internal — hard-delete this record's persisted `_idx/<field>/<recordId>`
+   * side-cars for the erasure path (#401). `forget()` crypto-shreds the body but
+   * keeps the collection DEK, under which these side-cars are encrypted — so
+   * without this they leave the indexed field VALUES readable after a "forget".
+   *
+   * Content-free: the side-car id is `encodeIdxId(def.key, id)`, so it needs no
+   * body decode (the body is being shredded). Eager mode has no durable side-car
+   * → no-op. The in-memory mirror is left as-is: it is ephemeral (rebuilt from
+   * the now-deleted side-cars on reopen) and live reads skip the tombstone, so a
+   * stale mirror hit cannot surface the erased record. Returns the count deleted
+   * + the `def.key`s whose delete FAILED (residue that still leaks the value).
+   */
+  async _purgePersistedIndexes(id) {
+    const persisted = this.persistedIndexes;
+    if (!persisted) return { purged: 0, residue: [] };
+    let purged = 0;
+    const residue = [];
+    for (const def of persisted.definitions()) {
+      try {
+        await this.adapter.delete(this.vault, this.name, encodeIdxId(def.key, id));
+        purged++;
+      } catch {
+        residue.push(def.key);
+      }
+    }
+    return { purged, residue };
+  }
   /**
    * Bulk-load the persisted-index mirror from `_idx/<field>/*` side-cars
    * on first lazy-mode query. Idempotent — subsequent calls short-circuit
@@ -4026,6 +4325,38 @@ function withArchive(opts) {
 // src/sequence/index.ts
 var SEQUENCE_COLLECTION = "_sequences";
 var MAX_NEXT_ATTEMPTS = 16;
+var SEQ_FORMAT_TOKEN = /\{([^{}]*)\}/g;
+var SEQ_PAD_TOKEN = /^seq:0(\d+)$/;
+var SEQ_PARTITION_TOKEN = /^partition\.(\d+)$/;
+function compileSequenceFormat(format, series, partition) {
+  const parts = partition ?? [];
+  for (const m of format.matchAll(SEQ_FORMAT_TOKEN)) {
+    const token = m[1] ?? "";
+    if (token === "seq") continue;
+    if (SEQ_PAD_TOKEN.test(token)) continue;
+    const partMatch = SEQ_PARTITION_TOKEN.exec(token);
+    if (partMatch) {
+      const idx = Number(partMatch[1]);
+      if (idx >= parts.length) {
+        throw new ValidationError(
+          `sequence("${series}"): format token "{${token}}" references partition index ${idx}, but only ${parts.length} partition component(s) were supplied.`
+        );
+      }
+      continue;
+    }
+    throw new ValidationError(
+      `sequence("${series}"): format contains unknown token "{${token}}". Accepted tokens: {seq}, {seq:0N}, {partition.i}.`
+    );
+  }
+  return (serial) => format.replace(SEQ_FORMAT_TOKEN, (full, token) => {
+    if (token === "seq") return String(serial);
+    const padMatch = SEQ_PAD_TOKEN.exec(token);
+    if (padMatch) return String(serial).padStart(Number(padMatch[1]), "0");
+    const partMatch = SEQ_PARTITION_TOKEN.exec(token);
+    if (partMatch) return String(parts[Number(partMatch[1])]);
+    return full;
+  });
+}
 function resolveSequenceKey(series, opts) {
   const partition = opts?.partition;
   if (!partition || partition.length === 0) return series;
@@ -4345,6 +4676,9 @@ var NO_PERIODS = {
 };
 
 // src/refs.ts
+function isRefArray(desc) {
+  return desc.isArray === true;
+}
 var RefIntegrityError = class extends NoydbError {
   collection;
   id;
@@ -4381,6 +4715,17 @@ function ref(target, mode = "strict") {
   }
   return { target, mode };
 }
+function refArray(target, mode = "strict") {
+  if (target.includes("/")) {
+    throw new RefScopeError(target);
+  }
+  if (!target || target.startsWith("_")) {
+    throw new Error(
+      `refArray(): target collection name must be non-empty and cannot start with '_' (reserved for internal collections). Got "${target}".`
+    );
+  }
+  return { target, mode, isArray: true };
+}
 var RefRegistry = class {
   outbound = /* @__PURE__ */ new Map();
   inbound = /* @__PURE__ */ new Map();
@@ -4405,7 +4750,7 @@ var RefRegistry = class {
       for (const k of existingKeys) {
         const a = existing[k];
         const b = refs[k];
-        if (!a || !b || a.target !== b.target || a.mode !== b.mode) {
+        if (!a || !b || a.target !== b.target || a.mode !== b.mode || a.isArray !== b.isArray) {
           throw new Error(
             `RefRegistry: conflicting ref declarations for collection "${collection}" field "${k}"`
           );
@@ -4416,7 +4761,7 @@ var RefRegistry = class {
     this.outbound.set(collection, { ...refs });
     for (const [field, desc] of Object.entries(refs)) {
       const list = this.inbound.get(desc.target) ?? [];
-      list.push({ collection, field, mode: desc.mode });
+      list.push({ collection, field, mode: desc.mode, ...desc.isArray ? { isArray: true } : {} });
       this.inbound.set(desc.target, list);
     }
   }
@@ -4444,6 +4789,141 @@ var RefRegistry = class {
   }
 };
 
+// src/links/link-set.ts
+var LINK_COLLECTION_PREFIX = "_links_";
+function linkCollectionName(name) {
+  return `${LINK_COLLECTION_PREFIX}${name}`;
+}
+function isLinkCollectionName(name) {
+  return name.startsWith(LINK_COLLECTION_PREFIX);
+}
+function linkRowKey(aId, bId) {
+  return `${encodeURIComponent(aId)}|${encodeURIComponent(bId)}`;
+}
+var LinkSet = class {
+  constructor(adapter, vault, name, spec, encrypted, getDEK, actor, emitter, endpointExists) {
+    this.adapter = adapter;
+    this.vault = vault;
+    this.name = name;
+    this.spec = spec;
+    this.encrypted = encrypted;
+    this.getDEK = getDEK;
+    this.actor = actor;
+    this.emitter = emitter;
+    this.endpointExists = endpointExists;
+    this.collName = linkCollectionName(name);
+  }
+  adapter;
+  vault;
+  name;
+  spec;
+  encrypted;
+  getDEK;
+  actor;
+  emitter;
+  endpointExists;
+  collName;
+  dekPromise = null;
+  dek() {
+    if (!this.dekPromise) this.dekPromise = this.getDEK(this.collName);
+    return this.dekPromise;
+  }
+  async encryptEntry(entry, version) {
+    const json = JSON.stringify(entry);
+    const base = { _noydb: NOYDB_FORMAT_VERSION, _v: version, _ts: (/* @__PURE__ */ new Date()).toISOString(), _by: this.actor };
+    if (!this.encrypted) return { ...base, _iv: "", _data: json };
+    const { iv, data } = await encrypt(json, await this.dek());
+    return { ...base, _iv: iv, _data: data };
+  }
+  async decryptEntry(env) {
+    const json = this.encrypted ? await decrypt(env._iv, env._data, await this.dek()) : env._data;
+    return JSON.parse(json);
+  }
+  async connect(aId, bId, meta) {
+    if (!await this.endpointExists(this.spec.a, aId)) {
+      throw new LinkEndpointError(this.name, this.spec.a, aId);
+    }
+    if (!await this.endpointExists(this.spec.b, bId)) {
+      throw new LinkEndpointError(this.name, this.spec.b, bId);
+    }
+    const key = linkRowKey(aId, bId);
+    const entry = meta !== void 0 ? { a: aId, b: bId, meta } : { a: aId, b: bId };
+    const existing = await this.adapter.get(this.vault, this.collName, key);
+    const env = await this.encryptEntry(entry, (existing?._v ?? 0) + 1);
+    await this.adapter.put(this.vault, this.collName, key, env, existing?._v);
+    this.emitter.emit("change", { vault: this.vault, collection: this.collName, id: key, action: "put" });
+  }
+  async disconnect(aId, bId) {
+    const key = linkRowKey(aId, bId);
+    const existing = await this.adapter.get(this.vault, this.collName, key);
+    if (!existing) return;
+    await this.adapter.delete(this.vault, this.collName, key);
+    this.emitter.emit("change", { vault: this.vault, collection: this.collName, id: key, action: "delete" });
+  }
+  async has(aId, bId) {
+    return await this.adapter.get(this.vault, this.collName, linkRowKey(aId, bId)) !== null;
+  }
+  async of(id) {
+    const rows = await this.list();
+    return rows.filter((r) => r.a === id || r.b === id);
+  }
+  async list() {
+    const keys = await this.adapter.list(this.vault, this.collName);
+    const out = [];
+    for (const key of keys) {
+      const env = await this.adapter.get(this.vault, this.collName, key);
+      if (!env) continue;
+      const e = await this.decryptEntry(env);
+      out.push(e.meta !== void 0 ? { a: e.a, b: e.b, meta: e.meta } : { a: e.a, b: e.b });
+    }
+    return out;
+  }
+  // ── Vault-internal cascade helpers ──────────────────────────────────
+  /** @internal — rows where the deleted endpoint id matches the relevant slot. */
+  async _rowsTouchingEndpoint(collection, id) {
+    const rows = await this.list();
+    return rows.filter(
+      (r) => this.spec.a === collection && r.a === id || this.spec.b === collection && r.b === id
+    );
+  }
+  /** @internal — the storage collection name (for tx pre-image capture). */
+  get _collectionName() {
+    return this.collName;
+  }
+};
+var LinkEndpointError = class extends NoydbError {
+  link;
+  endpoint;
+  missingId;
+  constructor(link, endpoint, missingId) {
+    super(
+      "LINK_ENDPOINT",
+      `link("${link}").connect: endpoint "${endpoint}" has no record "${missingId}".`
+    );
+    this.name = "LinkEndpointError";
+    this.link = link;
+    this.endpoint = endpoint;
+    this.missingId = missingId;
+  }
+};
+var LinkIntegrityError = class extends NoydbError {
+  link;
+  endpoint;
+  id;
+  count;
+  constructor(link, endpoint, id, count) {
+    super(
+      "LINK_INTEGRITY",
+      `Cannot delete "${endpoint}"/"${id}": ${count} link(s) in "${link}" still reference it (onDelete: 'strict').`
+    );
+    this.name = "LinkIntegrityError";
+    this.link = link;
+    this.endpoint = endpoint;
+    this.id = id;
+    this.count = count;
+  }
+};
+
 // src/meta/user-envelope/api.ts
 var UserApi = class {
   constructor(adapter, vaultName, writerKeyringId, getDek, checkGate2) {
@@ -5468,13 +5948,17 @@ var Vault = class {
    */
   overlayedViewRegistry = null;
   /**
-   * Cached read-only facade handed to guard callbacks via `ctx.vault`,
-   * and to derivation callbacks via `derive(source, ctx)`. Allocated
-   * eagerly inside `_initGuards()` and/or `_initDerivations()` so read
+   * Cached read-only facades handed to guard callbacks via `ctx.vault`
+   * and to derivation callbacks via `derive(source, ctx)`. Split by
+   * resolution layer (#285): the guard facade reads at `layer:'guard'`,
+   * the derivation facade at `layer:'derivation'`, so i18nText / dictKey
+   * fields resolve under that layer's `onMissing` policy. Allocated
+   * eagerly inside `_initGuards()` / `_initDerivations()` so read
    * accessors stay synchronous (callers in `tx/transaction.ts` rely on
-   * that). Stays `null` for vaults with neither subsystem configured.
+   * that). Each stays `null` for vaults without that subsystem.
    */
-  readOnlyFacade = null;
+  guardFacade = null;
+  derivationFacade = null;
   getDEK;
   /**
    * Per-principal user envelope API.
@@ -5636,6 +6120,10 @@ var Vault = class {
   i18nFieldRegistry = /* @__PURE__ */ new Map();
   /** Cache of DictionaryHandle instances, one per dictionary name. */
   dictionaryCache = /* @__PURE__ */ new Map();
+  /** Registered link specs (#377-B), keyed by link name; set by `vault.link()`. */
+  linkRegistry = /* @__PURE__ */ new Map();
+  /** Cache of LinkSet handles, one per link name. */
+  linkSetCache = /* @__PURE__ */ new Map();
   /** — subscribers for cross-tier access events. */
   crossTierSubs = /* @__PURE__ */ new Set();
   /** — currently-active elevation, or null. One per vault. */
@@ -5752,6 +6240,9 @@ var Vault = class {
     if (collectionName === SEQUENCE_COLLECTION) {
       throw new ReservedCollectionNameError(collectionName);
     }
+    if (isLinkCollectionName(collectionName)) {
+      throw new ReservedCollectionNameError(collectionName);
+    }
     let coll = this.collectionCache.get(collectionName);
     if (coll && options?.moneyFields) {
       coll._applyMoneyFields(options.moneyFields);
@@ -5823,6 +6314,7 @@ var Vault = class {
         }));
         schemaUpdateGate = new SchemaUpdateGate(work);
       }
+      const effectiveHistoryConfig = options?.historyConfig ?? this.historyConfig;
       const collOpts = {
         adapter: this.adapter,
         vault: this.name,
@@ -5838,7 +6330,7 @@ var Vault = class {
         schemaFence: this.schemaFence,
         getDEK: this.getDEK,
         onDirty: this.onDirty,
-        historyConfig: this.historyConfig,
+        historyConfig: effectiveHistoryConfig,
         // thread the vault-wide blob strategy into every
         // collection. `undefined` is intentionally preserved so the
         // Collection constructor uses its NO_BLOBS default.
@@ -5849,7 +6341,11 @@ var Vault = class {
         historyStrategy: this.historyStrategy,
         i18nStrategy: this.i18nStrategy,
         syncStrategy: this.syncStrategy,
-        ledger: this.getLedgerOrNull() ?? void 0,
+        // Per-collection ledger opt-out (#361): when this collection sets
+        // `historyConfig.ledger: false`, withhold the ledger reference so all
+        // four `if (this.ledger)` append sites in Collection no-op. The chain
+        // stays valid — it simply never receives this collection's entries.
+        ledger: effectiveHistoryConfig.ledger === false ? void 0 : this.getLedgerOrNull() ?? void 0,
         refEnforcer: this,
         joinResolver: this,
         defaultLocale: this.locale,
@@ -6210,6 +6706,68 @@ var Vault = class {
     }
     return handle;
   }
+  /**
+   * Declare a managed many-to-many link set (#377-B). Registers a
+   * `_links_<name>` junction between two endpoint collections; access its
+   * rows via `vault.links(name)`. Idempotent for an identical re-declaration;
+   * a conflicting one throws. See {@link links}.
+   *
+   * ```ts
+   * vault.link('saleLineLinks', { a: ref('saleLines'), b: ref('purchaseLines'), onDelete: 'cascade' })
+   * ```
+   *
+   * `a` / `b` accept either a collection name or a `ref(target)` descriptor
+   * (only its `target` is used — links manage their own integrity). `onDelete`
+   * governs what happens to link rows when an endpoint record is deleted
+   * (`'cascade'` default, `'strict'`, `'warn'`).
+   */
+  link(name, spec) {
+    const a = typeof spec.a === "string" ? spec.a : spec.a.target;
+    const b = typeof spec.b === "string" ? spec.b : spec.b.target;
+    for (const [slot, target] of [["a", a], ["b", b]]) {
+      if (!target || target.startsWith("_") || target.includes("/")) {
+        throw new ValidationError(
+          `vault.link("${name}"): endpoint "${slot}" must be a simple collection name, got "${target}".`
+        );
+      }
+    }
+    const resolved = { a, b, ...spec.onDelete ? { onDelete: spec.onDelete } : {} };
+    const existing = this.linkRegistry.get(name);
+    if (existing) {
+      if (existing.a !== resolved.a || existing.b !== resolved.b || (existing.onDelete ?? "cascade") !== (resolved.onDelete ?? "cascade")) {
+        throw new ValidationError(`vault.link("${name}"): conflicting re-declaration.`);
+      }
+      return;
+    }
+    this.linkRegistry.set(name, resolved);
+  }
+  /**
+   * Access a declared link set (#377-B). Throws if `name` was not first
+   * declared via {@link link}. Returns a cached {@link LinkSetHandle}:
+   * `connect(a, b, meta?)`, `disconnect(a, b)`, `has(a, b)`, `of(id)`, `list()`.
+   */
+  links(name) {
+    let handle = this.linkSetCache.get(name);
+    if (!handle) {
+      const spec = this.linkRegistry.get(name);
+      if (!spec) {
+        throw new ValidationError(`vault.links("${name}"): not declared. Call vault.link("${name}", { a, b }) first.`);
+      }
+      handle = new LinkSet(
+        this.adapter,
+        this.name,
+        name,
+        spec,
+        this.encrypted,
+        this.getDEK,
+        this.keyring.userId,
+        this.emitter,
+        async (collection, id) => await this.collection(collection).get(id) !== null
+      );
+      this.linkSetCache.set(name, handle);
+    }
+    return handle;
+  }
   /**
    * Build a `JoinableSource` for a dictKey field, for use in dict joins
    *. Returns a source whose snapshot contains `{ key, ...labels }`
@@ -6369,65 +6927,16 @@ var Vault = class {
       });
     }
   }
-  /**
-   * Bulk blob extraction primitive.
-   *
-   * Returns an async-iterable handle over every blob attached to
-   * records in the vault. Single capability check (`plaintext/blob`)
-   * at handle creation; single audit entry to `_export_audit` before
-   * the first yield. Per-blob decryption happens lazily as the
-   * consumer pulls tuples.
-   *
-   * ```ts
-   * const handle = vault.exportBlobs({
-   *   collections: ['invoiceScans'],
-   *   where: (rec) => (rec as { clientId?: string }).clientId === 'c-123',
-   * })
-   * for await (const { bytes, meta, recordRef } of handle) {
-   *   await uploadToColdStorage(bytes, recordRef)
-   * }
-   * ```
-   *
-   * @see `@noy-db/hub/store/export-blobs` for the full option surface.
-   */
-  /**
-   * Evict blob slots per the per-collection `blobFields` retention
-   * policy.
-   *
-   * Iterates every collection declared with `{ blobFields: {...} }`.
-   * For each record, checks every configured slot against its
-   * policy — `retainDays` (age-based TTL) and/or `evictWhen(record)`
-   * (predicate) — and evicts matching slots. Every eviction writes
-   * one entry to `_blob_eviction_audit` (actor + eTag + reason +
-   * timestamp, no plaintext). Consumer-scheduled; noy-db never runs
-   * this on its own.
-   *
-   * ```ts
-   * await vault.compact()                                   // run full pass
-   * await vault.compact({ dryRun: true })                   // preview counts
-   * await vault.compact({ maxEvictions: 1000 })             // cap batch
-   * ```
-   */
-  /**
-   * Atomic, gap-free numbering. `vault.sequence('invoice-2026').next()`
-   * returns 1, 2, 3, … with no gaps or duplicates under concurrency, via
-   * an optimistic-CAS counter at `_sequences/<name>`. Each name is an
-   * independent sequence.
-   *
-   * **Online-only:** `next()` throws `SequenceOfflineError` unless the
-   * store advertises `capabilities.casAtomic` — gap-free numbering cannot
-   * be serialized by an offline / non-CAS writer.
-   *
-   * ```ts
-   * const n = await vault.sequence('invoice-2026').next()   // 1, then 2, …
-   * const cur = await vault.sequence('invoice-2026').peek()  // current value, no allocation
-   * ```
-   */
   sequence(series, opts) {
     if (series.includes("\0")) {
       throw new ValidationError(`sequence("${series}"): series name must not contain a null byte (\\x00).`);
     }
     if (this.numberingConfigs.has(series)) {
+      if (opts?.format !== void 0) {
+        throw new ValidationError(
+          `sequence("${series}") is a deferred-numbering series; the format option applies to CAS sequences only.`
+        );
+      }
       const eng = this.deferred();
       return {
         next: async (nextOpts) => {
@@ -6451,7 +6960,17 @@ var Vault = class {
         actor: this.keyring.userId
       });
     }
-    return this.sequenceStore.handle(resolveSequenceKey(series, opts));
+    const handle = this.sequenceStore.handle(resolveSequenceKey(series, opts));
+    if (opts?.format === void 0) return handle;
+    const render = compileSequenceFormat(opts.format, series, opts.partition);
+    return {
+      next: async (nextOpts) => {
+        const serial = await handle.next(nextOpts);
+        return { serial, formatted: render(serial) };
+      },
+      peek: () => handle.peek(),
+      seedTo: (n) => handle.seedTo(n)
+    };
   }
   /** @internal — lazily build the deferred-numbering engine with a cache-coherent stamp. */
   deferred() {
@@ -6566,12 +7085,12 @@ var Vault = class {
     if (!fieldSchema) {
       throw new AttestationError(`issueAttestation: collection '${collectionName}' has no attestation field-schema. Declare it via vault.collection('${collectionName}', { attestation: { fields: [...] } }).`);
     }
-    const { issueAttestationCore } = await import("./issue-TTMGHQ2J.js");
+    const { issueAttestationCore } = await import("./issue-EPA2PSWP.js");
     const out = await issueAttestationCore(this.makeIssueContext(), { collection: collectionName, id, fieldSchema });
     return { docId: out.docId, qr: out.qr, keyId: out.keyId, publicKeyB64: out.publicKeyB64 };
   }
   async getDocumentSigningPublicKey() {
-    const { loadSigner, loadOrCreateSigner } = await import("./signer-YSXZT574.js");
+    const { loadSigner, loadOrCreateSigner } = await import("./signer-UNWOUJAK.js");
     const existing = await loadSigner(this.adapter, this.name, this.getDEK);
     if (existing) return { keyId: existing.keyId, publicKeyB64: existing.publicKeyB64 };
     if (this.keyring.role !== "owner") {
@@ -6597,19 +7116,19 @@ var Vault = class {
     };
   }
   async revokeAttestation(docId) {
-    const { revokeDocCore } = await import("./revoke-B54H2S2W.js");
+    const { revokeDocCore } = await import("./revoke-IFLXEZA5.js");
     await revokeDocCore(this.makeRevokeContext(), docId);
   }
   async unrevokeAttestation(docId) {
-    const { unrevokeDocCore } = await import("./revoke-B54H2S2W.js");
+    const { unrevokeDocCore } = await import("./revoke-IFLXEZA5.js");
     await unrevokeDocCore(this.makeRevokeContext(), docId);
   }
   async getRevokedDocIds() {
-    const { getRevokedDocIdsCore } = await import("./revoke-B54H2S2W.js");
+    const { getRevokedDocIdsCore } = await import("./revoke-IFLXEZA5.js");
     return getRevokedDocIdsCore(this.makeRevokeContext());
   }
   async publishRevocationList() {
-    const { publishRevocationListCore } = await import("./revoke-B54H2S2W.js");
+    const { publishRevocationListCore } = await import("./revoke-IFLXEZA5.js");
     return publishRevocationListCore(this.makeRevokeContext());
   }
   makeRevokeContext() {
@@ -6678,6 +7197,43 @@ var Vault = class {
       if (descriptor.mode !== "strict") continue;
       const rawId = obj[field];
       if (rawId === null || rawId === void 0) continue;
+      if (isRefArray(descriptor)) {
+        if (!Array.isArray(rawId)) {
+          throw new RefIntegrityError({
+            collection: collectionName,
+            id: obj["id"] ?? "<unknown>",
+            field,
+            refTo: descriptor.target,
+            refId: null,
+            message: `Array ref field "${collectionName}.${field}" must be an array, got ${typeof rawId}.`
+          });
+        }
+        const arrTarget = this.collection(descriptor.target);
+        for (const el of rawId) {
+          if (typeof el !== "string" && typeof el !== "number") {
+            throw new RefIntegrityError({
+              collection: collectionName,
+              id: obj["id"] ?? "<unknown>",
+              field,
+              refTo: descriptor.target,
+              refId: null,
+              message: `Array ref "${collectionName}.${field}" elements must be strings or numbers, got ${typeof el}.`
+            });
+          }
+          const elId = String(el);
+          if (!await arrTarget.get(elId)) {
+            throw new RefIntegrityError({
+              collection: collectionName,
+              id: obj["id"] ?? "<unknown>",
+              field,
+              refTo: descriptor.target,
+              refId: elId,
+              message: `Strict array ref "${collectionName}.${field}" \u2192 "${descriptor.target}" cannot be satisfied: element id "${elId}" not found in "${descriptor.target}".`
+            });
+          }
+        }
+        continue;
+      }
       if (typeof rawId !== "string" && typeof rawId !== "number") {
         throw new RefIntegrityError({
           collection: collectionName,
@@ -6727,6 +7283,11 @@ var Vault = class {
         const allRecords = await fromCollection.list();
         const matches = allRecords.filter((rec) => {
           const raw = rec[rule.field];
+          if (rule.isArray) {
+            return Array.isArray(raw) && raw.some(
+              (el) => (typeof el === "string" || typeof el === "number") && String(el) === id
+            );
+          }
           if (typeof raw !== "string" && typeof raw !== "number") return false;
           return String(raw) === id;
         });
@@ -6765,10 +7326,45 @@ var Vault = class {
           }
         }
       }
+      await this.enforceLinksOnDelete(collectionName, id);
     } finally {
       this.cascadeInProgress.delete(key);
     }
   }
+  /**
+   * @internal — apply link `onDelete` policy when an endpoint record is
+   * deleted (#377-B). `'strict'` throws (blocks the delete), `'cascade'`
+   * removes the touching link rows (tx-atomic when a transaction is active),
+   * `'warn'` leaves orphans for `checkIntegrity()`.
+   */
+  async enforceLinksOnDelete(collectionName, id) {
+    for (const [name, spec] of this.linkRegistry) {
+      if (spec.a !== collectionName && spec.b !== collectionName) continue;
+      const handle = this.links(name);
+      const touching = await handle._rowsTouchingEndpoint(collectionName, id);
+      if (touching.length === 0) continue;
+      const mode = spec.onDelete ?? "cascade";
+      if (mode === "warn") continue;
+      if (mode === "strict") {
+        throw new LinkIntegrityError(name, collectionName, id, touching.length);
+      }
+      const linkColl = handle._collectionName;
+      const txCtx = this.noydb._activeTxContextOrNull;
+      for (const row of touching) {
+        const rowKey = linkRowKey(row.a, row.b);
+        if (txCtx !== null) {
+          const prior = await this.adapter.get(this.name, linkColl, rowKey);
+          if (prior !== null) {
+            txCtx._executed.push({
+              op: { type: "delete", vaultName: this.name, collectionName: linkColl, id: rowKey },
+              priorEnvelope: prior
+            });
+          }
+        }
+        await handle.disconnect(row.a, row.b);
+      }
+    }
+  }
   // ─── Join resolver) ────────────────────
   /**
    * Look up the `RefDescriptor` the left collection declared for a
@@ -6829,6 +7425,23 @@ var Vault = class {
         for (const [field, descriptor] of Object.entries(refs)) {
           const rawId = record[field];
           if (rawId === null || rawId === void 0) continue;
+          const target = this.collection(descriptor.target);
+          if (isRefArray(descriptor)) {
+            if (!Array.isArray(rawId)) {
+              violations.push({ collection: collectionName, id: recId, field, refTo: descriptor.target, refId: rawId, mode: descriptor.mode });
+              continue;
+            }
+            for (const el of rawId) {
+              if (typeof el !== "string" && typeof el !== "number") {
+                violations.push({ collection: collectionName, id: recId, field, refTo: descriptor.target, refId: el, mode: descriptor.mode });
+                continue;
+              }
+              if (!await target.get(String(el))) {
+                violations.push({ collection: collectionName, id: recId, field, refTo: descriptor.target, refId: el, mode: descriptor.mode });
+              }
+            }
+            continue;
+          }
           if (typeof rawId !== "string" && typeof rawId !== "number") {
             violations.push({
               collection: collectionName,
@@ -6841,7 +7454,6 @@ var Vault = class {
             continue;
           }
           const refId = String(rawId);
-          const target = this.collection(descriptor.target);
           const exists = await target.get(refId);
           if (!exists) {
             violations.push({
@@ -6856,6 +7468,19 @@ var Vault = class {
         }
       }
     }
+    for (const [name, spec] of this.linkRegistry) {
+      const linkColl = linkCollectionName(name);
+      const rows = await this.links(name).list();
+      for (const row of rows) {
+        const rowKey = linkRowKey(row.a, row.b);
+        if (await this.collection(spec.a).get(row.a) === null) {
+          violations.push({ collection: linkColl, id: rowKey, field: "a", refTo: spec.a, refId: row.a, mode: spec.onDelete ?? "cascade" });
+        }
+        if (await this.collection(spec.b).get(row.b) === null) {
+          violations.push({ collection: linkColl, id: rowKey, field: "b", refTo: spec.b, refId: row.b, mode: spec.onDelete ?? "cascade" });
+        }
+      }
+    }
     return { violations };
   }
   /**
@@ -6962,6 +7587,8 @@ var Vault = class {
     const blobResidueCollections = /* @__PURE__ */ new Set();
     let blobsShredded = 0;
     let blobsRetainedShared = 0;
+    let indexPostingsPurged = 0;
+    const indexResidue = [];
     const blobsEnabled = this.blobStrategy !== void 0;
     const actor = this.keyring.userId;
     for (const ref2 of refs) {
@@ -6983,6 +7610,9 @@ var Vault = class {
         ref2.id,
         actor
       );
+      const idxPurge = await coll._purgePersistedIndexes(ref2.id);
+      indexPostingsPurged += idxPurge.purged;
+      for (const field of idxPurge.residue) indexResidue.push(`${ref2.collection}:${ref2.id}:${field}`);
       if (blobsEnabled) {
         const r = await this.collection(ref2.collection).blob(ref2.id).shredAllForRecord();
         blobsShredded += r.shredded.length;
@@ -7018,7 +7648,9 @@ var Vault = class {
         unmigratedCount: unmigratedRecords.length,
         blobsShredded,
         blobsRetainedShared,
-        blobResidueCollections: [...blobResidueCollections]
+        blobResidueCollections: [...blobResidueCollections],
+        indexPostingsPurged,
+        indexResidueCount: indexResidue.length
       })
     });
     return {
@@ -7030,6 +7662,8 @@ var Vault = class {
       blobsShredded,
       blobsRetainedShared,
       blobResidueCollections: [...blobResidueCollections],
+      indexPostingsPurged,
+      indexResidue,
       ledgerEntry
     };
   }
@@ -7126,12 +7760,12 @@ var Vault = class {
     if (handles.length === 0) return;
     const [{ GuardRegistry }, { ReadOnlyVaultFacade }] = await Promise.all([
       import("./registry-DKEXOJVO.js"),
-      import("./read-only-facade-ITU6L7BL.js")
+      import("./read-only-facade-EX6WZZBP.js")
     ]);
     const registry = new GuardRegistry();
     for (const h of handles) registry.register(h.spec);
     this.guardRegistry = registry;
-    this.readOnlyFacade = new ReadOnlyVaultFacade(this);
+    this.guardFacade = new ReadOnlyVaultFacade(this, "guard");
   }
   /**
    * @internal — The gate handler in Noydb.#registerGuardGate calls into
@@ -7153,8 +7787,8 @@ var Vault = class {
   async _initDerivations(handles) {
     if (handles.length === 0) return;
     const [{ DerivationRegistry }, { ReadOnlyVaultFacade }] = await Promise.all([
-      import("./registry-TGZISEWC.js"),
-      import("./read-only-facade-ITU6L7BL.js")
+      import("./registry-ERNAMRDE.js"),
+      import("./read-only-facade-EX6WZZBP.js")
     ]);
     const registry = new DerivationRegistry();
     for (const h of handles) {
@@ -7162,8 +7796,8 @@ var Vault = class {
     }
     registry.validate();
     this.derivationRegistry = registry;
-    if (this.readOnlyFacade === null) {
-      this.readOnlyFacade = new ReadOnlyVaultFacade(this);
+    if (this.derivationFacade === null) {
+      this.derivationFacade = new ReadOnlyVaultFacade(this, "derivation");
     }
   }
   /**
@@ -7184,7 +7818,7 @@ var Vault = class {
    */
   async _initMaterializedViews(handles) {
     if (handles.length === 0) return;
-    const { MaterializedViewRegistry } = await import("./registry-SECUWSGY.js");
+    const { MaterializedViewRegistry } = await import("./registry-RDPTFXQ7.js");
     const registry = new MaterializedViewRegistry();
     this.materializedViewRegistry = registry;
     const db = this;
@@ -7208,7 +7842,7 @@ var Vault = class {
    */
   async _initOverlayedViews(handles) {
     if (handles.length === 0) return;
-    const { OverlayedViewRegistry } = await import("./registry-3YFLZ7WD.js");
+    const { OverlayedViewRegistry } = await import("./registry-EXTHSXQW.js");
     const registry = new OverlayedViewRegistry();
     const mvRegistry = this.materializedViewRegistry;
     const overlayNames = /* @__PURE__ */ new Set();
@@ -7255,13 +7889,13 @@ var Vault = class {
     if (!reg) {
       throw new Error(`refreshView: no MV registered with name "${name}"`);
     }
-    const { MaterializedViewExecutor } = await import("./executor-3W63Y44O.js");
+    const { MaterializedViewExecutor } = await import("./executor-44R5CUS2.js");
     const result = await MaterializedViewExecutor.refresh(reg, {
       getCollection: (n) => this.collection(n),
       getActiveTxContext: () => this.noydb._activeTxContextOrNull,
       getQueryContext: () => this
     });
-    const { clearMVStale } = await import("./stale-TOA36SRK.js");
+    const { clearMVStale } = await import("./stale-NTEV5SLX.js");
     clearMVStale(registry, name);
     return result;
   }
@@ -7277,10 +7911,10 @@ var Vault = class {
     if (registry === null) return { derived: 0, failed: 0 };
     const strategies = registry.strategiesForSource(sourceCollection);
     if (strategies.length === 0) return { derived: 0, failed: 0 };
-    const { DerivationExecutor } = await import("./executor-CFFWPWBJ.js");
+    const { DerivationExecutor } = await import("./executor-OKFLQCDW.js");
     const sourceColl = this.collection(sourceCollection);
     const records = await sourceColl.list();
-    const ctx = { vault: this.readOnlyFacade ?? new (await import("./read-only-facade-ITU6L7BL.js")).ReadOnlyVaultFacade(this) };
+    const ctx = { vault: this.derivationFacade ?? new (await import("./read-only-facade-EX6WZZBP.js")).ReadOnlyVaultFacade(this, "derivation") };
     let derived = 0;
     let failed = 0;
     for (const record of records) {
@@ -7302,7 +7936,7 @@ var Vault = class {
           if (!outSpec) continue;
           const outputColl = this.collection(outSpec.collection);
           if (out.kind === "array") {
-            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-FIJJ46YG.js");
+            const { loadFanoutSidecar, saveFanoutSidecar } = await import("./fanout-sidecar-DCQWJQ6S.js");
             const prior = await loadFanoutSidecar(this.adapter, this.name, spec.source, id, key);
             const prevKeys = new Set(prior?.keys ?? []);
             const newKeysList = out.entries.map((e) => e.key);
@@ -7345,17 +7979,18 @@ var Vault = class {
    * never see null).
    */
   _getReadOnlyFacade() {
-    return this.readOnlyFacade;
+    return this.guardFacade;
   }
   /**
-   * Internal lazy-allocator for the read-only facade. Used as a
-   * defensive fallback; in practice `_initGuards()` eagerly
-   * instantiates this, so the lazy path is a no-op.
+   * Internal lazy-allocator for the derivation read-only facade
+   * (`layer:'derivation'`). Used as a defensive fallback; in practice
+   * `_initDerivations()` eagerly instantiates this, so the lazy path is
+   * a no-op.
    */
   _ensureReadOnlyFacade() {
-    if (this.readOnlyFacade !== null) return this.readOnlyFacade;
+    if (this.derivationFacade !== null) return this.derivationFacade;
     throw new Error(
-      "Vault: guard hook fired before _initGuards() completed. This typically means the vault was opened via the sync fallback path (Noydb.vault(name)) without first calling await db.openVault(name). See issue #132."
+      "Vault: derivation hook fired before _initDerivations() completed. This typically means the vault was opened via the sync fallback path (Noydb.vault(name)) without first calling await db.openVault(name). See issue #132."
     );
   }
   /**
@@ -7523,7 +8158,7 @@ var Vault = class {
    * collection.
    */
   async delegate(opts) {
-    const { issueDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-MGH5SODX.js");
+    const { issueDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-5HON72PV.js");
     if (!this.keyring.kek) {
       throw new ValidationError(
         "issueDelegation: keyring.kek is null \u2014 issuing a delegation requires a tier-1 unlock. Re-authenticate at tier 1 (passphrase) first."
@@ -7545,7 +8180,7 @@ var Vault = class {
    * if the id does not exist.
    */
   async revokeDelegation(id) {
-    const { revokeDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-MGH5SODX.js");
+    const { revokeDelegation, DELEGATIONS_COLLECTION } = await import("./delegation-5HON72PV.js");
     await revokeDelegation(this.adapter, this.name, id);
     void DELEGATIONS_COLLECTION;
   }
@@ -8014,7 +8649,7 @@ var Vault = class {
    * @see docs/subsystems/public-envelope.md
    */
   async getPublicEnvelope(opts = {}) {
-    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-RXZNP3V6.js");
+    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-AGU6SS4Z.js");
     return readPublicEnvelope2(this.adapter, this.name, opts);
   }
   /**
@@ -8291,6 +8926,8 @@ var Vault = class {
    */
   async *exportStream(opts = {}) {
     const granularity = opts.granularity ?? "collection";
+    const exportLocale = opts.resolveLabels;
+    const localeOpts = exportLocale !== void 0 ? { locale: exportLocale, _layer: "export" } : void 0;
     const snapshot = await this.adapter.loadAll(this.name);
     const collectionNames = Object.keys(snapshot).sort();
     const ledgerHead = opts.withLedgerHead ? await (async () => {
@@ -8300,19 +8937,21 @@ var Vault = class {
       return head ? { hash: head.hash, index: head.entry.index, ts: head.entry.ts } : void 0;
     })() : void 0;
     const dictSnapshotCache = /* @__PURE__ */ new Map();
-    for (const collectionName of collectionNames) {
-      const dictFields = this.dictKeyFieldRegistry.get(collectionName);
-      if (dictFields && Object.keys(dictFields).length > 0) {
-        const snap = {};
-        for (const [fieldName, dictName] of Object.entries(dictFields)) {
-          const entries = await this.dictionary(dictName).list();
-          const keyMap = {};
-          for (const entry of entries) {
-            keyMap[entry.key] = entry.labels;
+    if (exportLocale === void 0) {
+      for (const collectionName of collectionNames) {
+        const dictFields = this.dictKeyFieldRegistry.get(collectionName);
+        if (dictFields && Object.keys(dictFields).length > 0) {
+          const snap = {};
+          for (const [fieldName, dictName] of Object.entries(dictFields)) {
+            const entries = await this.dictionary(dictName).list();
+            const keyMap = {};
+            for (const entry of entries) {
+              keyMap[entry.key] = entry.labels;
+            }
+            snap[fieldName] = keyMap;
           }
-          snap[fieldName] = keyMap;
+          dictSnapshotCache.set(collectionName, snap);
         }
-        dictSnapshotCache.set(collectionName, snap);
       }
     }
     for (const collectionName of collectionNames) {
@@ -8325,7 +8964,7 @@ var Vault = class {
       if (granularity === "collection") {
         const records = [];
         for (const id of ids) {
-          const record = await coll.get(id);
+          const record = await coll.get(id, localeOpts);
           if (record !== null) records.push(record);
         }
         const chunk = {
@@ -8339,7 +8978,7 @@ var Vault = class {
         yield chunk;
       } else {
         for (const id of ids) {
-          const record = await coll.get(id);
+          const record = await coll.get(id, localeOpts);
           if (record === null) continue;
           const chunk = {
             collection: collectionName,
@@ -8443,7 +9082,10 @@ var Vault = class {
     const allDictionaries = {};
     for await (const chunk of this.exportStream({
       granularity: "collection",
-      withLedgerHead: opts.withLedgerHead === true
+      withLedgerHead: opts.withLedgerHead === true,
+      // #285 export layer: thread the export locale so records are read at the
+      // `export` layer (i18nText collapsed + dictKey/staticDict labels resolved).
+      ...opts.resolveLabels !== void 0 ? { resolveLabels: opts.resolveLabels } : {}
     })) {
       collections[chunk.collection] = {
         schema: null,
@@ -9679,7 +10321,7 @@ var Noydb = class {
       if (!facade) return;
       const ctx = { existing, vault: facade, userId: e.userId, role: e.role };
       await registry.runChecks(e.collection, incoming, ctx);
-      const { GuardExecutor } = await import("./executor-VDQQOR4F.js");
+      const { GuardExecutor } = await import("./executor-AOACUK7Z.js");
       for (const g of guards) {
         await GuardExecutor.checkFrozenFields(g, e.docId, existing, incoming, e.computedFieldNames);
       }
@@ -10280,11 +10922,11 @@ var Noydb = class {
     if (name === STATE_VAULT_NAME) throw new ReservedVaultNameError(name);
     const template = this.vaultTemplates.get(opts.sharding.vaultTemplate);
     if (!template) throw new VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
-    const { VaultGroup } = await import("./vault-group-DHAHFX2A.js");
-    const { StateManagementVault } = await import("./state-vault-W2OEABNO.js");
+    const { VaultGroup } = await import("./vault-group-27EV7KB4.js");
+    const { StateManagementVault } = await import("./state-vault-TUTFRTOA.js");
     const stateVault = opts.registry ? void 0 : await StateManagementVault.open(this);
     const registry = opts.registry ?? stateVault.registry;
-    const group = new VaultGroup(this, name, registry, opts.sharding, template);
+    const group = new VaultGroup(this, name, registry, opts.sharding, template, opts.migrateOnOpen ?? false);
     if (stateVault) {
       group._attachStateVault(stateVault);
       await stateVault.recordManifest(opts.sharding.vaultTemplate, template);
@@ -10308,7 +10950,7 @@ var Noydb = class {
    */
   async openStateManagementVault() {
     if (this.closed) throw new ValidationError("Instance is closed");
-    const { StateManagementVault } = await import("./state-vault-W2OEABNO.js");
+    const { StateManagementVault } = await import("./state-vault-TUTFRTOA.js");
     return StateManagementVault.open(this);
   }
   /**
@@ -10318,6 +10960,16 @@ var Noydb = class {
   async _shardVaultProvisioned(vaultId) {
     return (await this.options.store.list(vaultId, "_keyring")).length > 0;
   }
+  /**
+   * @internal — the physical backend store a vault id maps to. A
+   * `routeStore` resolves the vault-prefix route via its `resolveBackend`;
+   * a plain store is its own backend. Used by the federation data-residency
+   * guard to read the placement backend's `capabilities.region` (#271).
+   */
+  _resolveBackend(vaultId) {
+    const store = this.options.store;
+    return store.resolveBackend ? store.resolveBackend(vaultId) : this.options.store;
+  }
   /**
    * Change the current user's passphrase for a vault.
    *
@@ -11810,6 +12462,7 @@ function normalizeSyncTargets(sync) {
 
 export {
   withArchive,
+  compileSequenceFormat,
   resolveSequenceKey,
   SequenceStore,
   validateSchemaInput,
@@ -11817,10 +12470,15 @@ export {
   isZodSchema,
   derivePersistedSchema,
   persistSchemaIfNeeded,
+  isRefArray,
   RefIntegrityError,
   RefScopeError,
   ref,
+  refArray,
   RefRegistry,
+  isLinkCollectionName,
+  LinkEndpointError,
+  LinkIntegrityError,
   QuickUnlockStore,
   UserApi,
   META_COLLECTION,
@@ -11833,6 +12491,7 @@ export {
   describeAllUsersAuth,
   ComputedFieldError,
   evalComputedFields,
+  tokenize,
   Lru,
   parseBytes,
   estimateRecordBytes,
@@ -11849,4 +12508,4 @@ export {
   Noydb,
   createNoydb
 };
-//# sourceMappingURL=chunk-D77ZQSQQ.js.map
+//# sourceMappingURL=chunk-KYGGXXT6.js.map