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

package/dist/bundle/index.cjs

@@ -31,7 +31,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, UnknownShardError, ShardProvisioningError, CrossShardJoinError, VaultTemplateNotFoundError, ForgetStrategyNotConfiguredError, RecordCekNotFoundError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, UnknownShardError, ShardProvisioningError, DataResidencyError, CrossShardJoinError, VaultTemplateNotFoundError, ForgetStrategyNotConfiguredError, RecordCekNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -776,6 +776,21 @@ Resolutions:
         this.vaultId = vaultId;
       }
     };
+    DataResidencyError = class extends NoydbError {
+      vaultId;
+      requiredRegion;
+      backendRegion;
+      constructor(vaultId, requiredRegion, backendRegion) {
+        super(
+          "DATA_RESIDENCY",
+          `Shard "${vaultId}" requires region "${requiredRegion}" but its placement backend declares region ${backendRegion === void 0 ? "(none)" : `"${backendRegion}"`}. Refusing to provision \u2014 route this shard to a region-correct backend via routeStore({ vaultRoutes }) (e.g. a region-encoded partition key) before retrying.`
+        );
+        this.name = "DataResidencyError";
+        this.vaultId = vaultId;
+        this.requiredRegion = requiredRegion;
+        this.backendRegion = backendRegion;
+      }
+    };
     CrossShardJoinError = class extends NoydbError {
       constructor(message) {
         super("CROSS_SHARD_JOIN", message);
@@ -3893,7 +3908,146 @@ var init_policy = __esm({
   }
 });
 
+// src/i18n/script.ts
+function inferScripts(locale) {
+  const parts = locale.split("-");
+  const subtag = parts.find((t) => /^[A-Z][a-z]{3}$/.test(t));
+  if (subtag && SUBTAG_SCRIPTS[subtag]) return SUBTAG_SCRIPTS[subtag];
+  const base = (parts[0] ?? "").toLowerCase();
+  if (LATIN_BASE.has(base)) return ["Latin"];
+  const primary = SCRIPT_TABLE[base];
+  if (primary) return [...primary, "Latin"];
+  return ["Latin"];
+}
+var LATIN_BASE, SCRIPT_TABLE, SUBTAG_SCRIPTS, BASELINE;
+var init_script = __esm({
+  "src/i18n/script.ts"() {
+    "use strict";
+    LATIN_BASE = /* @__PURE__ */ new Set([
+      "en",
+      "fr",
+      "de",
+      "es",
+      "it",
+      "pt",
+      "nl",
+      "sv",
+      "no",
+      "da",
+      "fi",
+      "is",
+      "pl",
+      "cs",
+      "sk",
+      "hu",
+      "ro",
+      "hr",
+      "sl",
+      "et",
+      "lv",
+      "lt",
+      "tr",
+      "vi",
+      "id",
+      "ms",
+      "tl",
+      "sw",
+      "af",
+      "ca",
+      "gl",
+      "eu",
+      "cy",
+      "ga"
+    ]);
+    SCRIPT_TABLE = {
+      th: ["Thai"],
+      ko: ["Hangul", "Han"],
+      ja: ["Han", "Hiragana", "Katakana"],
+      zh: ["Han"],
+      ar: ["Arabic"],
+      fa: ["Arabic"],
+      ur: ["Arabic"],
+      ru: ["Cyrillic"],
+      uk: ["Cyrillic"],
+      bg: ["Cyrillic"],
+      sr: ["Cyrillic"],
+      he: ["Hebrew"],
+      el: ["Greek"],
+      hi: ["Devanagari"],
+      ta: ["Tamil"],
+      km: ["Khmer"],
+      lo: ["Lao"],
+      my: ["Myanmar"]
+    };
+    SUBTAG_SCRIPTS = {
+      Latn: ["Latin"],
+      Cyrl: ["Cyrillic", "Latin"],
+      Hans: ["Han", "Latin"],
+      Hant: ["Han", "Latin"],
+      Thai: ["Thai", "Latin"],
+      Arab: ["Arabic", "Latin"]
+    };
+    BASELINE = String.raw`\p{White_Space}\p{Script=Common}\p{Script=Inherited}\p{Mark}`;
+  }
+});
+
 // src/i18n/core.ts
+function toChain(fallback) {
+  return Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+}
+function pickFromChain(value, chain) {
+  for (const fb of chain) {
+    if (fb === "any") {
+      const any = Object.values(value).find((v) => v !== "");
+      if (any !== void 0) return any;
+    } else if (value[fb] !== void 0 && value[fb] !== "") {
+      return value[fb];
+    }
+  }
+  return void 0;
+}
+function resolveI18nText(value, locale, fallback, field, opts) {
+  if (locale === "raw") {
+    return value;
+  }
+  if (!locale) {
+    throw new LocaleNotSpecifiedError(field ?? "<unknown>");
+  }
+  if (value[locale] !== void 0 && value[locale] !== "") {
+    return value[locale];
+  }
+  const policy = opts?.policy ?? "throw";
+  const callerChain = toChain(fallback);
+  const callerHit = pickFromChain(value, callerChain);
+  if (callerHit !== void 0) return callerHit;
+  if (policy === "substitute") {
+    const subHit = pickFromChain(value, toChain(opts?.substitute));
+    if (subHit !== void 0) return subHit;
+    if (opts?.smartSubstitute) {
+      const smartHit = pickNearestScript(value, locale);
+      if (smartHit !== void 0) return smartHit;
+    }
+  }
+  if (policy === "throw") {
+    throw new LocaleNotSpecifiedError(
+      field ?? "<unknown>",
+      `No translation available for locale "${locale}"` + (callerChain.length > 0 ? ` or fallback chain [${callerChain.join(", ")}]` : "") + "."
+    );
+  }
+  return null;
+}
+function pickNearestScript(value, target) {
+  const targetScript = inferScripts(target)[0] ?? "Latin";
+  let best;
+  for (const [loc, v] of Object.entries(value)) {
+    if (typeof v !== "string" || v === "") continue;
+    const s = inferScripts(loc)[0] ?? "Latin";
+    const score = s === targetScript ? 0 : s === "Latin" ? 1 : 2;
+    if (best === void 0 || score < best.score) best = { score, v };
+    if (score === 0) break;
+  }
+  return best?.v;
+}
 function getAtPath(obj, path) {
   const arrayIdx = path.indexOf("[].");
   if (arrayIdx !== -1) {
@@ -3929,9 +4083,61 @@ function setAtPathInPlace(obj, path, value) {
   }
   obj[path] = value;
 }
+function applyAtPath(obj, path, locale, fallback, opts) {
+  const arrayIdx = path.indexOf("[].");
+  if (arrayIdx !== -1) {
+    const arrayKey = path.slice(0, arrayIdx);
+    const restPath = path.slice(arrayIdx + 3);
+    const arr = obj[arrayKey];
+    if (!Array.isArray(arr)) return obj;
+    return {
+      ...obj,
+      [arrayKey]: arr.map((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+        return applyAtPath(item, restPath, locale, fallback, opts);
+      })
+    };
+  }
+  const dotIdx = path.indexOf(".");
+  if (dotIdx !== -1) {
+    const head = path.slice(0, dotIdx);
+    const rest = path.slice(dotIdx + 1);
+    const nested = obj[head];
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return obj;
+    return {
+      ...obj,
+      [head]: applyAtPath(nested, rest, locale, fallback, opts)
+    };
+  }
+  const raw = obj[path];
+  if (raw === void 0 || raw === null) return obj;
+  if (typeof raw !== "object" || Array.isArray(raw)) return obj;
+  return {
+    ...obj,
+    [path]: resolveI18nText(raw, locale, fallback, path, opts)
+  };
+}
+function applyI18nLocale(record, i18nFields, locale, fallback, layer = "read") {
+  const fieldNames = Object.keys(i18nFields);
+  if (fieldNames.length === 0) return record;
+  let result = record;
+  for (const [field, descriptor] of Object.entries(i18nFields)) {
+    const { onMissing, substitute, smartSubstitute } = descriptor.options;
+    const opts = {
+      policy: resolvePolicy(onMissing, layer),
+      ...substitute !== void 0 ? { substitute } : {},
+      ...smartSubstitute ? { smartSubstitute } : {}
+    };
+    result = applyAtPath(result, field, locale, fallback, opts);
+  }
+  return result;
+}
 var init_core = __esm({
   "src/i18n/core.ts"() {
     "use strict";
+    init_errors();
+    init_policy();
+    init_script();
   }
 });
 
@@ -4343,6 +4549,21 @@ function formatCurrency(decimal, currency, scale, locale) {
   });
   return fmt.format(decimal);
 }
+function moneyScaledValue(stored, desc) {
+  let raw;
+  if (desc.mode === "fixed") {
+    raw = stored;
+  } else {
+    if (!isMoneyValueObject(stored)) return null;
+    raw = stored.amount;
+  }
+  if (typeof raw !== "string" && typeof raw !== "number") return null;
+  try {
+    return BigInt(String(raw));
+  } catch {
+    return null;
+  }
+}
 function decodeValue(stored, desc) {
   let currency;
   let scaledIntString;
@@ -4853,15 +5074,15 @@ function warnCeilingApproaching(target, side, rows, maxRows) {
     `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ceiling for target "${target}" (${rows} rows). Streaming joins over scan() are not yet supported for collections that need to exceed this.`
   );
 }
-function applyJoins(rows, joins, context) {
+function applyJoins(rows, joins, context, locale) {
   if (joins.length === 0) return [...rows];
   let result = [...rows];
   for (const leg of joins) {
-    result = applyOneJoin(result, leg, context);
+    result = applyOneJoin(result, leg, context, locale);
   }
   return result;
 }
-function applyOneJoin(leftRows, leg, context) {
+function applyOneJoin(leftRows, leg, context, locale) {
   if (leg.isDictJoin) {
     const dictSource = context.resolveDictSource?.(leg.field);
     if (!dictSource) {
@@ -4916,24 +5137,27 @@ function applyOneJoin(leftRows, leg, context) {
   if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
     warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
   }
+  const effLocale = locale ?? context.defaultLocale;
+  const i18nResolve = effLocale !== void 0 && source.i18nFields !== void 0 ? (right) => right !== null && typeof right === "object" ? applyI18nLocale(right, source.i18nFields, effLocale, void 0, "join") : right : void 0;
   const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
   if (strategy === "nested" && source.lookupById) {
     const lookup = (id) => source.lookupById?.(id);
-    return nestedLoopJoin(leftRows, leg, lookup);
+    return nestedLoopJoin(leftRows, leg, lookup, i18nResolve);
   }
-  return hashJoin(leftRows, leg, rightSnapshot);
+  return hashJoin(leftRows, leg, rightSnapshot, i18nResolve);
 }
-function nestedLoopJoin(leftRows, leg, lookupById) {
+function nestedLoopJoin(leftRows, leg, lookupById, i18nResolve) {
   const out = [];
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : lookupById(key);
+    let right = key === null ? void 0 : lookupById(key);
+    if (i18nResolve && right !== void 0) right = i18nResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
 }
-function hashJoin(leftRows, leg, rightSnapshot) {
+function hashJoin(leftRows, leg, rightSnapshot, i18nResolve) {
   const rightMap = /* @__PURE__ */ new Map();
   for (const record of rightSnapshot) {
     const rawId = readPath(record, "id");
@@ -4946,7 +5170,8 @@ function hashJoin(leftRows, leg, rightSnapshot) {
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : rightMap.get(key);
+    let right = key === null ? void 0 : rightMap.get(key);
+    if (i18nResolve && right !== void 0) right = i18nResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
@@ -4981,6 +5206,7 @@ var init_join = __esm({
     "use strict";
     init_predicate();
     init_errors();
+    init_core();
     DEFAULT_JOIN_MAX_ROWS = 5e4;
     JOIN_WARN_FRACTION = 0.8;
     warnedDanglingKeys = /* @__PURE__ */ new Set();
@@ -5285,7 +5511,7 @@ var init_money_reducer = __esm({
 });
 
 // src/query/builder.ts
-function executePlanWithSource(source, plan, joinContext) {
+function executePlanWithSource(source, plan, joinContext, locale) {
   const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
   let result;
   if (hasCrossJoins) {
@@ -5300,7 +5526,8 @@ function executePlanWithSource(source, plan, joinContext) {
     result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
   }
   if (plan.orderBy.length > 0) {
-    result = sortRecords(result, plan.orderBy);
+    const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale);
+    result = sortRecords(result, plan.orderBy, source.moneyFields, labelMaps);
   }
   if (plan.offset > 0) {
     result = result.slice(plan.offset);
@@ -5439,17 +5666,55 @@ function applyCrossJoin(leftRel, clause, rightSource) {
   }
   return expanded;
 }
-function sortRecords(records, orderBy) {
+function sortRecords(records, orderBy, moneyFields, labelMaps) {
   return [...records].sort((a, b) => {
-    for (const { field, direction } of orderBy) {
-      const av = readField(a, field);
-      const bv = readField(b, field);
-      const cmp = compareValues(av, bv);
+    for (const { field, direction, by } of orderBy) {
+      let av = readField(a, field);
+      let bv = readField(b, field);
+      const labelMap = by === "label" ? labelMaps?.get(field) : void 0;
+      if (labelMap) {
+        av = (typeof av === "string" ? labelMap.get(av) : void 0) ?? av;
+        bv = (typeof bv === "string" ? labelMap.get(bv) : void 0) ?? bv;
+        const cmp2 = compareValues(av, bv);
+        if (cmp2 !== 0) return direction === "asc" ? cmp2 : -cmp2;
+        continue;
+      }
+      const desc = moneyFields?.[field];
+      const cmp = desc ? compareMoney(av, bv, desc) : compareValues(av, bv);
       if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
     }
     return 0;
   });
 }
+function buildOrderLabelMaps(orderBy, joinContext, locale) {
+  if (!joinContext?.resolveDictSource) return void 0;
+  const resolveDict = joinContext.resolveDictSource.bind(joinContext);
+  let maps;
+  for (const { field, by } of orderBy) {
+    if (by !== "label") continue;
+    const dictSource = resolveDict(field);
+    if (!dictSource) continue;
+    const loc = locale ?? dictSource.displayLocale;
+    if (loc === void 0) continue;
+    const codeToLabel = /* @__PURE__ */ new Map();
+    for (const entry of dictSource.snapshot()) {
+      const k = entry["key"];
+      const labels = entry["labels"];
+      const label = labels?.[loc];
+      if (typeof k === "string" && typeof label === "string") codeToLabel.set(k, label);
+    }
+    ;
+    (maps ??= /* @__PURE__ */ new Map()).set(field, codeToLabel);
+  }
+  return maps;
+}
+function compareMoney(a, b, desc) {
+  const av = moneyScaledValue(a, desc);
+  const bv = moneyScaledValue(b, desc);
+  if (av === null) return bv === null ? 0 : 1;
+  if (bv === null) return -1;
+  return av < bv ? -1 : av > bv ? 1 : 0;
+}
 function readField(record, field) {
   if (record === null || record === void 0) return void 0;
   if (!field.includes(".")) {
@@ -5743,11 +6008,16 @@ var init_builder = __esm({
           this.predicates
         );
       }
-      /** Sort by a field. Subsequent calls are tie-breakers. */
-      orderBy(field, direction = "asc") {
+      /**
+       * Sort by a field. Subsequent calls are tie-breakers. Pass
+       * `{ by: 'label' }` to sort a `dictKey`/`staticDict` field by its resolved
+       * label at the query locale instead of the stored code (#285).
+       */
+      orderBy(field, direction = "asc", opts) {
+        const entry = opts?.by === "label" ? { field, direction, by: "label" } : { field, direction };
         return new _Query(
           this.source,
-          { ...this.plan, orderBy: [...this.plan.orderBy, { field, direction }] },
+          { ...this.plan, orderBy: [...this.plan.orderBy, entry] },
           this.joinContext,
           this.aggregateStrategy,
           this.predicates
@@ -5950,16 +6220,21 @@ var init_builder = __esm({
        * carries any join legs, they are applied after `where` / `orderBy`
        * / `limit` / `offset` narrow the left set. See the `.join()` doc
        * for the ordering rationale.
+       *
+       * `opts.locale` (#285 §3) resolves JOINED right-side i18n fields at the
+       * `join` layer to that locale; without it, the owning collection's default
+       * locale applies, and a locale-less query leaves joined i18n fields raw.
+       * (Left/base i18n fields are resolved by `get`/`list`, not here.)
        */
-      toArray() {
-        const base = this.decodeMoney(executePlanWithSource(this.source, this.plan, this.joinContext));
+      toArray(opts) {
+        const base = this.decodeMoney(executePlanWithSource(this.source, this.plan, this.joinContext, opts?.locale));
         if (this.plan.joins.length === 0) return base;
         if (!this.joinContext) {
           throw new Error(
             `Query.toArray(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
           );
         }
-        return applyJoins(base, this.plan.joins, this.joinContext);
+        return applyJoins(base, this.plan.joins, this.joinContext, opts?.locale);
       }
       /**
        * Decode this source's money fields on read (stored scaled-int → canonical
@@ -5978,9 +6253,9 @@ var init_builder = __esm({
         if (!moneyFields || Object.keys(moneyFields).length === 0) return records;
         return records.map((r) => decodeMoneyFields(r, moneyFields, "raw"));
       }
-      /** Return the first matching record, or null. Joins are applied. */
-      first() {
-        const arr = this.limit(1).toArray();
+      /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields (#285 §3). */
+      first(opts) {
+        const arr = this.limit(1).toArray(opts);
         return arr[0] ?? null;
       }
       /**
@@ -6994,6 +7269,95 @@ var init_strategy5 = __esm({
   }
 });
 
+// src/search/tokenize.ts
+var WORD, tokenize;
+var init_tokenize = __esm({
+  "src/search/tokenize.ts"() {
+    "use strict";
+    WORD = /[\p{L}\p{N}]+/gu;
+    tokenize = (text) => {
+      if (!text) return [];
+      return text.normalize("NFKC").toLowerCase().match(WORD) ?? [];
+    };
+  }
+});
+
+// src/search/scan.ts
+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;
+}
+var K1, B;
+var init_scan = __esm({
+  "src/search/scan.ts"() {
+    "use strict";
+    init_tokenize();
+    K1 = 1.2;
+    B = 0.75;
+  }
+});
+
+// src/search/index.ts
+var init_search = __esm({
+  "src/search/index.ts"() {
+    "use strict";
+    init_scan();
+  }
+});
+
 // src/indexing/unique-constraints.ts
 function buildUniqueConstraintSet(collectionName, indexes, mode) {
   const uniqueDefs = [];
@@ -8011,12 +8375,13 @@ var executor_exports2 = {};
 __export(executor_exports2, {
   MaterializedViewExecutor: () => MaterializedViewExecutor
 });
-async function materializeQueryResult(q, mvName) {
+async function materializeQueryResult(q, mvName, i18nLocale, i18nFields) {
   if (typeof q?.toArray === "function") {
     return await q.toArray();
   }
   if (typeof q?.run === "function") {
-    const result = await Promise.resolve(q.run());
+    const runOpts = i18nLocale !== void 0 ? { locale: i18nLocale, i18nFields } : void 0;
+    const result = await Promise.resolve(q.run(runOpts));
     if (Array.isArray(result)) {
       return result;
     }
@@ -8045,6 +8410,29 @@ async function materializeUnionResult(spec, db) {
   }
   if (!spec.groupBy) return unified;
   const groupFields = typeof spec.groupBy === "string" ? [spec.groupBy] : spec.groupBy;
+  if (spec.i18nLocale !== void 0 && spec.i18nFields !== void 0) {
+    const groupI18n = {};
+    for (const f of groupFields) {
+      const d = spec.i18nFields[f];
+      if (d !== void 0) groupI18n[f] = d;
+    }
+    if (Object.keys(groupI18n).length > 0) {
+      for (let i = 0; i < unified.length; i++) {
+        unified[i] = applyI18nLocale(unified[i], groupI18n, spec.i18nLocale, void 0, "mv");
+      }
+    }
+  }
+  for (const f of groupFields) {
+    for (const row of unified) {
+      const v = row[f];
+      if (v !== null && typeof v === "object") {
+        throw new LocaleNotSpecifiedError(
+          f,
+          `Materialized view "${spec.name}" groups by "${f}", whose value is a raw i18n locale map \u2014 an unstable object group key. Declare { i18nLocale, i18nFields } on the MV to resolve it at the 'mv' layer, or group by a dictKey/staticDict code (the stable key) and resolve the label at read time.`
+        );
+      }
+    }
+  }
   if (!spec.aggregate) {
     const seen = /* @__PURE__ */ new Map();
     for (const row of unified) {
@@ -8076,6 +8464,7 @@ var init_executor2 = __esm({
     init_registry();
     init_groupby();
     init_canonical_key();
+    init_core();
     DEFAULT_MAX_ROWS = 1e5;
     MaterializedViewExecutor = {
       async refresh(reg, accessor) {
@@ -8091,7 +8480,7 @@ var init_executor2 = __esm({
           rows = await materializeUnionResult(spec, ctxForQuery);
         } else {
           const q = spec.query(ctxForQuery);
-          rows = await materializeQueryResult(q, spec.name);
+          rows = await materializeQueryResult(q, spec.name, spec.i18nLocale, spec.i18nFields);
         }
         if (rows.length > maxRows) {
           throw new MaterializedViewTooLargeError(spec.name, rows.length, maxRows);
@@ -8272,6 +8661,15 @@ var init_fanout_sidecar = __esm({
 });
 
 // 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;
+  }
+}
 function warnOnceFallback(adapterName) {
   if (fallbackWarned.has(adapterName)) return;
   fallbackWarned.add(adapterName);
@@ -8341,6 +8739,7 @@ var init_collection = __esm({
     init_persisted_indexes();
     init_lazy_builder();
     init_strategy5();
+    init_search();
     init_errors();
     init_unique_constraints();
     init_cache();
@@ -9276,6 +9675,111 @@ var init_collection = __esm({
        * 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);
@@ -9286,29 +9790,60 @@ var init_collection = __esm({
         let DerivationExecutor2 = null;
         for (const { spec, strategyHash } of strategies) {
           const mode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
-          if (mode === "eager") {
-            if (DerivationExecutor2 === null) {
-              ({ DerivationExecutor: DerivationExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports)));
-            }
-            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 (DerivationExecutor2 === null) {
+            ({ DerivationExecutor: DerivationExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports)));
+          }
+          for (const run of runs) {
             const ctx = { vault: this.derivationSource.getReadOnlyFacade() };
-            const result = await DerivationExecutor2.run(spec, sourceWithId, sourceVersion, strategyHash, ctx);
+            const result = await DerivationExecutor2.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];
@@ -9321,7 +9856,7 @@ var init_collection = __esm({
                   this.adapter,
                   this.vault,
                   spec.source,
-                  id,
+                  run.runId,
                   key
                 );
                 const prevKeys = new Set(prior?.keys ?? []);
@@ -9348,7 +9883,7 @@ var init_collection = __esm({
                 }
                 await saveFanoutSidecar2(this.adapter, this.vault, {
                   source: spec.source,
-                  sourceId: id,
+                  sourceId: run.runId,
                   outputKey: key,
                   outputCollection: outSpec.collection,
                   keys: newKeysList
@@ -9356,25 +9891,44 @@ var init_collection = __esm({
                 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);
           }
         }
       }
@@ -9591,6 +10145,7 @@ var init_collection = __esm({
         if (!internal) {
           await this.dispatchMaterializedViewsOnDelete(id);
           await this.dispatchArrayDerivationsOnDelete(id);
+          if (existing) await this.dispatchRollupsOnDelete(existing.record);
         }
       }
       /**
@@ -9747,6 +10302,29 @@ var init_collection = __esm({
       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
@@ -9924,6 +10502,10 @@ var init_collection = __esm({
           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);
@@ -10012,7 +10594,10 @@ var init_collection = __esm({
             };
             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 } : {}
         };
       }
       /**
@@ -10245,6 +10830,10 @@ var init_collection = __esm({
           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(
@@ -10645,14 +11234,15 @@ var init_collection = __esm({
           (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) => {
@@ -10801,6 +11391,34 @@ var init_collection = __esm({
           }
         }
       }
+      /**
+       * @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
@@ -11672,6 +12290,35 @@ var init_archive = __esm({
 });
 
 // src/sequence/index.ts
+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;
@@ -11692,7 +12339,7 @@ async function sleepBackoff2(attempt) {
   const ms = Math.floor(Math.random() * ceil);
   await new Promise((r) => setTimeout(r, ms));
 }
-var SEQUENCE_COLLECTION, MAX_NEXT_ATTEMPTS, SequenceStore;
+var SEQUENCE_COLLECTION, MAX_NEXT_ATTEMPTS, SEQ_FORMAT_TOKEN, SEQ_PAD_TOKEN, SEQ_PARTITION_TOKEN, SequenceStore;
 var init_sequence = __esm({
   "src/sequence/index.ts"() {
     "use strict";
@@ -11701,6 +12348,9 @@ var init_sequence = __esm({
     init_errors();
     SEQUENCE_COLLECTION = "_sequences";
     MAX_NEXT_ATTEMPTS = 16;
+    SEQ_FORMAT_TOKEN = /\{([^{}]*)\}/g;
+    SEQ_PAD_TOKEN = /^seq:0(\d+)$/;
+    SEQ_PARTITION_TOKEN = /^partition\.(\d+)$/;
     SequenceStore = class {
       adapter;
       vault;
@@ -12145,6 +12795,9 @@ var init_strategy10 = __esm({
 });
 
 // src/refs.ts
+function isRefArray(desc) {
+  return desc.isArray === true;
+}
 var RefIntegrityError, RefRegistry;
 var init_refs = __esm({
   "src/refs.ts"() {
@@ -12190,7 +12843,7 @@ var init_refs = __esm({
           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}"`
               );
@@ -12201,7 +12854,7 @@ var init_refs = __esm({
         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);
         }
       }
@@ -12231,57 +12884,201 @@ var init_refs = __esm({
   }
 });
 
-// src/periods/periods.ts
-var PERIODS_COLLECTION;
-var init_periods = __esm({
-  "src/periods/periods.ts"() {
-    "use strict";
-    PERIODS_COLLECTION = "_periods";
-  }
-});
-
-// src/periods/index.ts
-var init_periods2 = __esm({
-  "src/periods/index.ts"() {
+// src/links/link-set.ts
+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 LINK_COLLECTION_PREFIX, LinkSet, LinkEndpointError, LinkIntegrityError;
+var init_link_set = __esm({
+  "src/links/link-set.ts"() {
     "use strict";
-    init_periods();
-  }
-});
-
-// src/blobs/export-blobs.ts
-function createExportBlobsHandle(actor, listAccessibleCollections, getCollection, writeAudit, options) {
-  let aborted = false;
-  const abort = () => {
-    aborted = true;
-  };
-  if (options.signal) {
-    if (options.signal.aborted) aborted = true;
-    options.signal.addEventListener("abort", () => {
-      aborted = true;
-    });
-  }
-  function assertLive() {
-    if (aborted) throw new ExportBlobsAbortedError("aborted by caller");
-  }
-  const allowlist = options.collections ? new Set(options.collections) : null;
-  let auditPromise = null;
-  function writeAuditOnce() {
-    if (!auditPromise) {
-      auditPromise = writeAudit({
-        id: generateBatchId(),
-        mechanism: "exportBlobs",
-        actor,
-        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        collections: options.collections ?? null,
-        predicate: Boolean(options.where),
-        afterBlobId: options.afterBlobId ?? null
-      });
-    }
-    return auditPromise;
-  }
-  async function* generate() {
-    await writeAuditOnce();
-    assertLive();
+    init_types();
+    init_crypto();
+    init_errors();
+    LINK_COLLECTION_PREFIX = "_links_";
+    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;
+      }
+    };
+    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;
+      }
+    };
+    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/periods/periods.ts
+var PERIODS_COLLECTION;
+var init_periods = __esm({
+  "src/periods/periods.ts"() {
+    "use strict";
+    PERIODS_COLLECTION = "_periods";
+  }
+});
+
+// src/periods/index.ts
+var init_periods2 = __esm({
+  "src/periods/index.ts"() {
+    "use strict";
+    init_periods();
+  }
+});
+
+// src/blobs/export-blobs.ts
+function createExportBlobsHandle(actor, listAccessibleCollections, getCollection, writeAudit, options) {
+  let aborted = false;
+  const abort = () => {
+    aborted = true;
+  };
+  if (options.signal) {
+    if (options.signal.aborted) aborted = true;
+    options.signal.addEventListener("abort", () => {
+      aborted = true;
+    });
+  }
+  function assertLive() {
+    if (aborted) throw new ExportBlobsAbortedError("aborted by caller");
+  }
+  const allowlist = options.collections ? new Set(options.collections) : null;
+  let auditPromise = null;
+  function writeAuditOnce() {
+    if (!auditPromise) {
+      auditPromise = writeAudit({
+        id: generateBatchId(),
+        mechanism: "exportBlobs",
+        actor,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        collections: options.collections ?? null,
+        predicate: Boolean(options.where),
+        afterBlobId: options.afterBlobId ?? null
+      });
+    }
+    return auditPromise;
+  }
+  async function* generate() {
+    await writeAuditOnce();
+    assertLive();
     const allCollections = await listAccessibleCollections();
     const targets = allCollections.filter((name) => {
       if (name.startsWith("_")) return false;
@@ -13906,14 +14703,17 @@ var init_read_only_facade = __esm({
     "use strict";
     ReadOnlyVaultFacade = class {
       _vault;
-      constructor(vault) {
+      _layer;
+      constructor(vault, layer = "read") {
         this._vault = vault;
+        this._layer = layer;
       }
       collection(name) {
         const c = this._vault.collection(name);
+        const layer = this._layer;
         return {
-          get: (id) => c.get(id),
-          list: () => c.list(),
+          get: (id) => c.get(id, { _layer: layer }),
+          list: () => c.list({ _layer: layer }),
           query: () => c.query()
         };
       }
@@ -13969,6 +14769,16 @@ var init_registry3 = __esm({
           if (fromExtra) fromExtra.push(reg);
           else this._bySource.set(extra, [reg]);
         }
+        for (const t of spec.triggerBy ?? []) {
+          const fromTrigger = this._bySource.get(t.collection);
+          if (fromTrigger) fromTrigger.push(reg);
+          else this._bySource.set(t.collection, [reg]);
+        }
+        if (spec.rollup) {
+          const fromRollup = this._bySource.get(spec.rollup.from);
+          if (fromRollup) fromRollup.push(reg);
+          else this._bySource.set(spec.rollup.from, [reg]);
+        }
         for (const key of outputKeys) {
           const output = spec.outputs[key];
           if (!output) continue;
@@ -14022,6 +14832,9 @@ var init_registry3 = __esm({
               for (const key of Object.keys(s.spec.outputs)) {
                 const output = s.spec.outputs[key];
                 if (!output) continue;
+                if (output.shape === "record" && output.collection === s.spec.source && output.denorm !== void 0) {
+                  continue;
+                }
                 visit(output.collection);
               }
             }
@@ -14237,6 +15050,7 @@ var init_vault = __esm({
     init_strategy10();
     init_refs();
     init_dictionary();
+    init_link_set();
     init_core();
     init_strategy2();
     init_sync_strategy();
@@ -14329,13 +15143,17 @@ var init_vault = __esm({
        */
       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.
@@ -14497,6 +15315,10 @@ var init_vault = __esm({
       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. */
@@ -14613,6 +15435,9 @@ var init_vault = __esm({
         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);
@@ -14684,6 +15509,7 @@ var init_vault = __esm({
             }));
             schemaUpdateGate = new SchemaUpdateGate(work);
           }
+          const effectiveHistoryConfig = options?.historyConfig ?? this.historyConfig;
           const collOpts = {
             adapter: this.adapter,
             vault: this.name,
@@ -14699,7 +15525,7 @@ var init_vault = __esm({
             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.
@@ -14710,7 +15536,11 @@ var init_vault = __esm({
             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,
@@ -15071,6 +15901,68 @@ var init_vault = __esm({
         }
         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 }`
@@ -15230,65 +16122,16 @@ var init_vault = __esm({
           });
         }
       }
-      /**
-       * 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) => {
@@ -15312,7 +16155,17 @@ var init_vault = __esm({
             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() {
@@ -15539,6 +16392,43 @@ var init_vault = __esm({
           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,
@@ -15588,6 +16478,11 @@ var init_vault = __esm({
             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;
             });
@@ -15626,10 +16521,45 @@ var init_vault = __esm({
               }
             }
           }
+          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
@@ -15690,6 +16620,23 @@ var init_vault = __esm({
             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,
@@ -15702,7 +16649,6 @@ var init_vault = __esm({
                 continue;
               }
               const refId = String(rawId);
-              const target = this.collection(descriptor.target);
               const exists = await target.get(refId);
               if (!exists) {
                 violations.push({
@@ -15717,6 +16663,19 @@ var init_vault = __esm({
             }
           }
         }
+        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 };
       }
       /**
@@ -15823,6 +16782,8 @@ var init_vault = __esm({
         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 ref of refs) {
@@ -15844,6 +16805,9 @@ var init_vault = __esm({
             ref.id,
             actor
           );
+          const idxPurge = await coll._purgePersistedIndexes(ref.id);
+          indexPostingsPurged += idxPurge.purged;
+          for (const field of idxPurge.residue) indexResidue.push(`${ref.collection}:${ref.id}:${field}`);
           if (blobsEnabled) {
             const r = await this.collection(ref.collection).blob(ref.id).shredAllForRecord();
             blobsShredded += r.shredded.length;
@@ -15879,7 +16843,9 @@ var init_vault = __esm({
             unmigratedCount: unmigratedRecords.length,
             blobsShredded,
             blobsRetainedShared,
-            blobResidueCollections: [...blobResidueCollections]
+            blobResidueCollections: [...blobResidueCollections],
+            indexPostingsPurged,
+            indexResidueCount: indexResidue.length
           })
         });
         return {
@@ -15891,6 +16857,8 @@ var init_vault = __esm({
           blobsShredded,
           blobsRetainedShared,
           blobResidueCollections: [...blobResidueCollections],
+          indexPostingsPurged,
+          indexResidue,
           ledgerEntry
         };
       }
@@ -15992,7 +16960,7 @@ var init_vault = __esm({
         const registry = new GuardRegistry2();
         for (const h of handles) registry.register(h.spec);
         this.guardRegistry = registry;
-        this.readOnlyFacade = new ReadOnlyVaultFacade2(this);
+        this.guardFacade = new ReadOnlyVaultFacade2(this, "guard");
       }
       /**
        * @internal — The gate handler in Noydb.#registerGuardGate calls into
@@ -16023,8 +16991,8 @@ var init_vault = __esm({
         }
         registry.validate();
         this.derivationRegistry = registry;
-        if (this.readOnlyFacade === null) {
-          this.readOnlyFacade = new ReadOnlyVaultFacade2(this);
+        if (this.derivationFacade === null) {
+          this.derivationFacade = new ReadOnlyVaultFacade2(this, "derivation");
         }
       }
       /**
@@ -16141,7 +17109,7 @@ var init_vault = __esm({
         const { DerivationExecutor: DerivationExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports));
         const sourceColl = this.collection(sourceCollection);
         const records = await sourceColl.list();
-        const ctx = { vault: this.readOnlyFacade ?? new (await Promise.resolve().then(() => (init_read_only_facade(), read_only_facade_exports))).ReadOnlyVaultFacade(this) };
+        const ctx = { vault: this.derivationFacade ?? new (await Promise.resolve().then(() => (init_read_only_facade(), read_only_facade_exports))).ReadOnlyVaultFacade(this, "derivation") };
         let derived = 0;
         let failed = 0;
         for (const record of records) {
@@ -16206,17 +17174,18 @@ var init_vault = __esm({
        * 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."
         );
       }
       /**
@@ -17152,6 +18121,8 @@ var init_vault = __esm({
        */
       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 () => {
@@ -17161,19 +18132,21 @@ var init_vault = __esm({
           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) {
@@ -17186,7 +18159,7 @@ var init_vault = __esm({
           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 = {
@@ -17200,7 +18173,7 @@ var init_vault = __esm({
             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,
@@ -17304,7 +18277,10 @@ var init_vault = __esm({
         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,
@@ -18615,43 +19591,214 @@ var init_executor3 = __esm({
   }
 });
 
-// src/federation/classify-skip.ts
-function classifyShardSkip(err) {
-  return err instanceof NoAccessError ? "no-grant" : "error";
-}
-var init_classify_skip = __esm({
-  "src/federation/classify-skip.ts"() {
-    "use strict";
-    init_errors();
-  }
-});
-
-// src/federation/cross-shard-join.ts
-function coerceKey(value) {
-  if (value === null || value === void 0) return null;
-  if (typeof value === "string") return value;
-  if (typeof value === "number" || typeof value === "bigint") return String(value);
-  return null;
-}
-function warnOnceBroadcastMiss(field, as, key) {
-  const dedup = `${field}\u2192${as}:${key}`;
-  if (warnedBroadcastKeys.has(dedup)) return;
-  warnedBroadcastKeys.add(dedup);
-  console.warn(
-    `[noy-db] broadcastJoin: no "${as}" dimension row for ${field}="${key}". Attaching null. Use mode: 'cascade' to silence.`
-  );
-}
-async function applyBroadcastLegs(rows, legs) {
-  if (legs.length === 0) return [...rows];
-  const indexes = [];
-  for (const leg of legs) {
-    const map = /* @__PURE__ */ new Map();
-    for (const rec of await leg.from.list()) {
-      const k = coerceKey(readPath(rec, leg.on));
-      if (k !== null && !map.has(k)) map.set(k, rec);
+// src/federation/schema-manifest.ts
+function captureBlueprint(configure) {
+  const recorded = [];
+  const collectionStub = new Proxy(
+    {},
+    {
+      get: () => () => collectionStub
     }
-    indexes.push({ leg, map });
-  }
+  );
+  const proxy = new Proxy(
+    {},
+    {
+      get: (_t, prop) => {
+        if (prop === "collection") {
+          return (name, opts) => {
+            recorded.push({
+              name,
+              indexes: opts?.indexes ?? [],
+              persistJsonSchema: !!opts?.persistJsonSchema
+            });
+            return collectionStub;
+          };
+        }
+        return () => proxy;
+      }
+    }
+  );
+  configure(proxy);
+  const sorted = [...recorded].sort((a, b) => a.name.localeCompare(b.name));
+  const indexes = {};
+  const persistJsonSchema = [];
+  for (const c of sorted) {
+    indexes[c.name] = c.indexes;
+    if (c.persistJsonSchema) persistJsonSchema.push(c.name);
+  }
+  return {
+    // `persistJsonSchema` is already name-sorted: it is populated while
+    // iterating `sorted` (collections in name order).
+    collections: sorted.map((c) => c.name),
+    indexes,
+    persistJsonSchema
+  };
+}
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
+}
+async function fingerprintBlueprint(bp) {
+  return sha256Hex2(new TextEncoder().encode(canonical(bp)));
+}
+var init_schema_manifest = __esm({
+  "src/federation/schema-manifest.ts"() {
+    "use strict";
+    init_crypto();
+  }
+});
+
+// src/federation/state-vault.ts
+var state_vault_exports = {};
+__export(state_vault_exports, {
+  STATE_VAULT_NAME: () => STATE_VAULT_NAME,
+  StateManagementVault: () => StateManagementVault
+});
+var REGISTRY, MANIFEST, EVENTS, MIGRATION_STATUS, StateManagementVault;
+var init_state_vault = __esm({
+  "src/federation/state-vault.ts"() {
+    "use strict";
+    init_schema_manifest();
+    init_constants2();
+    init_ulid();
+    init_constants2();
+    REGISTRY = "vaultRegistry";
+    MANIFEST = "schemaManifest";
+    EVENTS = "deploymentEvents";
+    MIGRATION_STATUS = "migrationStatus";
+    StateManagementVault = class _StateManagementVault {
+      constructor(registry, schemaManifest, events, migrationStatus) {
+        this.registry = registry;
+        this.schemaManifest = schemaManifest;
+        this.#events = events;
+        this.#migrationStatus = migrationStatus;
+      }
+      registry;
+      schemaManifest;
+      /**
+       * The append-only deployment-events log is kept truly private so the raw
+       * mutable Collection is never surfaced — events may only be written via
+       * `appendEvent` and read via `queryEvents`. (`registry` and
+       * `schemaManifest` are deliberately public: consumers read and write them.)
+       */
+      #events;
+      /** Per-shard fleet-migration progress (#271). Surfaced via typed methods only. */
+      #migrationStatus;
+      /** Idempotently open the reserved state vault and bind the control-plane collections. */
+      static async open(db) {
+        const vault = await db.openVault(STATE_VAULT_NAME);
+        return new _StateManagementVault(
+          vault.collection(REGISTRY),
+          vault.collection(MANIFEST),
+          vault.collection(EVENTS),
+          vault.collection(MIGRATION_STATUS)
+        );
+      }
+      /** Read one shard's migration status (or null). */
+      async getMigrationStatus(vaultId) {
+        return this.#migrationStatus.get(vaultId);
+      }
+      /** All migration-status rows (hydrates first). */
+      async listMigrationStatus() {
+        await this.#migrationStatus.list();
+        return this.#migrationStatus.query().toArray();
+      }
+      /** Upsert one shard's migration status (keyed by vaultId). */
+      async upsertMigrationStatus(row) {
+        await this.#migrationStatus.put(row.vaultId, row);
+      }
+      /** Read-only query over the append-only deployment-events log. */
+      queryEvents() {
+        return this.#events.query();
+      }
+      /**
+       * Append a deployment event with a fresh unique (ULID) id. This is the
+       * only write path to the events log; no update/delete is exposed.
+       * Callers should treat failures as non-fatal — this method does not
+       * swallow errors, so wrap the call site in try/catch where appropriate.
+       */
+      async appendEvent(event) {
+        const ts = event.ts ?? Date.now();
+        const id = generateULID();
+        await this.#events.put(id, { ...event, id, ts });
+      }
+      /**
+       * Ensure a manifest row exists for `(templateName, template.version)`.
+       * Safe to call repeatedly: the `fingerprint` is a deterministic hash of
+       * the template's declared shape (stable across calls), though each call
+       * refreshes `recordedAt`.
+       */
+      async recordManifest(templateName, template) {
+        const bp = captureBlueprint(template.configure);
+        const fingerprint = await fingerprintBlueprint(bp);
+        await this.schemaManifest.put(`${templateName}:${template.version}`, {
+          templateName,
+          version: template.version,
+          collections: bp.collections,
+          indexes: bp.indexes,
+          persistJsonSchema: bp.persistJsonSchema,
+          fingerprint,
+          recordedAt: Date.now()
+        });
+        return fingerprint;
+      }
+      /**
+       * True when `template`'s current declared shape does not match the recorded
+       * manifest for `(templateName, template.version)`. Because shards carry no
+       * schema state independent of their template, this catches "a template's
+       * shape changed without bumping `version`" — not independent per-shard drift.
+       * A missing manifest is treated as drift (nothing to verify against).
+       */
+      async detectDrift(templateName, template) {
+        const row = await this.schemaManifest.get(`${templateName}:${template.version}`);
+        if (!row) return true;
+        const current = await fingerprintBlueprint(captureBlueprint(template.configure));
+        return current !== row.fingerprint;
+      }
+    };
+  }
+});
+
+// src/federation/classify-skip.ts
+function classifyShardSkip(err) {
+  return err instanceof NoAccessError ? "no-grant" : "error";
+}
+var init_classify_skip = __esm({
+  "src/federation/classify-skip.ts"() {
+    "use strict";
+    init_errors();
+  }
+});
+
+// src/federation/cross-shard-join.ts
+function coerceKey(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+function warnOnceBroadcastMiss(field, as, key) {
+  const dedup = `${field}\u2192${as}:${key}`;
+  if (warnedBroadcastKeys.has(dedup)) return;
+  warnedBroadcastKeys.add(dedup);
+  console.warn(
+    `[noy-db] broadcastJoin: no "${as}" dimension row for ${field}="${key}". Attaching null. Use mode: 'cascade' to silence.`
+  );
+}
+async function applyBroadcastLegs(rows, legs) {
+  if (legs.length === 0) return [...rows];
+  const indexes = [];
+  for (const leg of legs) {
+    const map = /* @__PURE__ */ new Map();
+    for (const rec of await leg.from.list()) {
+      const k = coerceKey(readPath(rec, leg.on));
+      if (k !== null && !map.has(k)) map.set(k, rec);
+    }
+    indexes.push({ leg, map });
+  }
   return rows.map((row) => {
     const out = { ...row };
     for (const { leg, map } of indexes) {
@@ -18899,6 +20046,7 @@ var SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQ
 var init_vault_group = __esm({
   "src/federation/vault-group.ts"() {
     "use strict";
+    init_state_vault();
     init_errors();
     init_constants2();
     init_classify_skip();
@@ -18908,12 +20056,13 @@ var init_vault_group = __esm({
     SHARD_SEPARATOR = "--";
     SAFE_PARTITION_KEY = /^[A-Za-z0-9._-]+$/;
     VaultGroup = class {
-      constructor(db, name, registry, sharding, template) {
+      constructor(db, name, registry, sharding, template, migrateOnOpen = false) {
         this.db = db;
         this.name = name;
         this.registry = registry;
         this.sharding = sharding;
         this.template = template;
+        this.migrateOnOpen = migrateOnOpen;
         if (name.includes(SHARD_SEPARATOR)) {
           throw new ValidationError(
             `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
@@ -18925,6 +20074,7 @@ var init_vault_group = __esm({
       registry;
       sharding;
       template;
+      migrateOnOpen;
       /** @internal — set when the group is managed (no explicit registry). */
       stateVault;
       /** @internal */
@@ -18958,8 +20108,22 @@ var init_vault_group = __esm({
         const rows = this.registry.query().toArray();
         return rows.filter((r) => r.group === this.name);
       }
-      /** Open an existing shard and apply the template. */
+      /**
+       * Open an existing shard and apply the template. When `migrateOnOpen` is set
+       * (#271) and the shard's registry version is behind the template, its cutover
+       * runs inline first — so a behind shard never surfaces a stale handle.
+       */
       async openShard(partitionKey) {
+        if (this.migrateOnOpen) {
+          const row = await this.registry.get(this.registryId(partitionKey));
+          if (row && row.schemaVersion < this.template.version) {
+            await this.migrateShard(partitionKey);
+          }
+        }
+        return this._openShardRaw(partitionKey);
+      }
+      /** @internal — open + configure with no migrate-on-open hook (used by the migration path itself to avoid recursion). */
+      async _openShardRaw(partitionKey) {
         const vault = await this.db.openVault(this.shardVaultId(partitionKey), { create: false });
         this.template.configure(vault);
         return vault;
@@ -18971,13 +20135,21 @@ var init_vault_group = __esm({
        * - row + vault present → no-op, return handle
        * - row present, vault gone → ShardProvisioningError
        * - row absent (vault present or not) → open-or-create, configure, write row
+       *
+       * When `region` is given (the routing `put` passes `sharding.regionOf(record)`),
+       * the candidate backend's `capabilities.region` must match or this throws
+       * `DataResidencyError` BEFORE provisioning (#271 data-residency guard).
        */
-      async createShard(partitionKey) {
+      async createShard(partitionKey, region) {
         const vaultId = this.shardVaultId(partitionKey);
         const row = await this.registry.get(this.registryId(partitionKey));
         const provisioned = await this.db._shardVaultProvisioned(vaultId);
         if (row && !provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
         if (row && provisioned) return this.openShard(partitionKey);
+        if (region !== void 0) {
+          const backendRegion = this.db._resolveBackend(vaultId).capabilities?.region;
+          if (backendRegion !== region) throw new DataResidencyError(vaultId, region, backendRegion);
+        }
         const vault = await this.db.openVault(vaultId);
         this.template.configure(vault);
         await this.registry.put(this.registryId(partitionKey), {
@@ -19037,6 +20209,172 @@ var init_vault_group = __esm({
         });
         return { eligible, skipped };
       }
+      /** @internal — registered push-model cross-vault derivations (#271 Insight Vault). */
+      crossVaultDerivations = [];
+      /**
+       * Register a push-model cross-vault derivation — the Insight Vault pattern
+       * (#271, Layer 4). Drive it with {@link refreshInsights}.
+       *
+       * For each shard, `derive(records, ctx)` runs on that shard's `source`
+       * records and its return value is written into the analytics
+       * (`target.vault` / `target.collection`) vault, keyed by partition key —
+       * one summary row per shard. The derivation runs in-process under THIS
+       * group's `Noydb` (which already holds both the shard and Insight Vault
+       * keyrings); the shard's decrypted records are reduced to a summary that is
+       * re-encrypted under the Insight Vault's own DEK, so no shard ciphertext
+       * crosses a DEK boundary.
+       *
+       * **Zero-knowledge note:** the Insight Vault backend sees aggregated
+       * structure (totals, counts, timestamps) drawn from many shards — a weaker
+       * ZK profile than the per-shard vaults. Opt-in; keep summaries to aggregate
+       * scalars (no embeddings / no raw records).
+       *
+       * v1 is explicit-refresh (no write-path push); call `refreshInsights()`
+       * after a batch of writes, or on a schedule.
+       *
+       * The `target.vault` must NOT be the group itself or one of its shards —
+       * a summary writing back into client-shard data would breach the Insight
+       * Vault's separate-DEK-boundary contract. Such a target throws a
+       * `ValidationError` at registration (#271 Insight-write isolation).
+       */
+      withCrossVaultDerivation(spec) {
+        const target = spec.target.vault;
+        if (target === this.name || target.startsWith(`${this.name}${SHARD_SEPARATOR}`)) {
+          throw new ValidationError(
+            `withCrossVaultDerivation: target.vault "${target}" is the "${this.name}" group itself or one of its shards \u2014 an Insight summary must target a SEPARATE analytics vault, never write back into client-shard data (it would breach the per-shard DEK boundary). Use a distinct vault name.`
+          );
+        }
+        this.crossVaultDerivations.push(spec);
+      }
+      /**
+       * Run every registered {@link withCrossVaultDerivation}: read each eligible
+       * shard's source records, derive a per-shard summary, and write it into the
+       * Insight Vault keyed by partition key. Shards behind `minVersion`,
+       * unprovisioned, or whose read errors are reported in `skippedVaults` and
+       * are not written (a stale summary is never left behind for a failed shard).
+       */
+      async refreshInsights(options = {}) {
+        if (this.crossVaultDerivations.length === 0) return { written: 0, skippedVaults: [] };
+        const { eligible, skipped } = await this.resolveEligible(
+          options.minVersion !== void 0 ? { minVersion: options.minVersion } : {}
+        );
+        let written = 0;
+        for (const spec of this.crossVaultDerivations) {
+          const results = await this.db.queryAcross(
+            eligible.map((r) => r.vaultId),
+            async (vault) => {
+              this.template.configure(vault);
+              return vault.collection(spec.source).list();
+            },
+            { create: false, ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {} }
+          );
+          const insight = await this.db.openVault(spec.target.vault);
+          const out = insight.collection(spec.target.collection);
+          for (let i = 0; i < eligible.length; i++) {
+            const row = eligible[i];
+            const res = results[i];
+            if (!res || res.result === void 0) {
+              skipped.push({ vaultId: row.vaultId, reason: "error", ...res?.error ? { error: res.error } : {} });
+              continue;
+            }
+            const ctx = {
+              vaultId: row.vaultId,
+              partitionKey: row.partitionKey,
+              schemaVersion: row.schemaVersion
+            };
+            const summary = spec.derive(res.result, ctx);
+            await out.put(row.partitionKey, summary);
+            written++;
+          }
+        }
+        return { written, skippedVaults: skipped };
+      }
+      /** @internal — the control-plane vault for migration status; lazily opened. */
+      async ensureStateVault() {
+        if (!this.stateVault) this.stateVault = await StateManagementVault.open(this.db);
+        return this.stateVault;
+      }
+      /**
+       * Migrate ONE shard to the template's current version (#271 fleet runner,
+       * per-shard step). Opens the shard (applying the template, which arms the
+       * M12 cutover), drains schema-write detection, runs `vault.runSchemaCutover()`
+       * (the per-vault drain-barrier-transform protocol), then advances the
+       * registry row's `schemaVersion` and records `migration-status`. A shard
+       * already at the template version is a no-op (`status: 'done'`, migrated 0).
+       * Never throws on a cutover failure — it records `status: 'failed'` and
+       * returns the row, so a fleet run continues past a bad shard.
+       */
+      async migrateShard(partitionKey) {
+        const vaultId = this.shardVaultId(partitionKey);
+        const row = await this.registry.get(this.registryId(partitionKey));
+        if (!row) throw new UnknownShardError(partitionKey, this.name);
+        const target = this.template.version;
+        const sv = await this.ensureStateVault();
+        const base = { vaultId, group: this.name, currentVersion: row.schemaVersion, targetVersion: target };
+        if (row.schemaVersion >= target) {
+          const done = { ...base, status: "done", migrated: 0, finishedAt: Date.now() };
+          await sv.upsertMigrationStatus(done);
+          return done;
+        }
+        await sv.upsertMigrationStatus({ ...base, status: "running", startedAt: Date.now() });
+        try {
+          await sv.appendEvent({ type: "migration-started", group: this.name, vaultId, version: target });
+        } catch {
+        }
+        try {
+          const vault = await this._openShardRaw(partitionKey);
+          await vault._drainPendingSchemaWrites();
+          const { migrated } = await vault.runSchemaCutover();
+          await this.registry.put(this.registryId(partitionKey), { ...row, schemaVersion: target });
+          const done = { ...base, currentVersion: target, status: "done", migrated, finishedAt: Date.now() };
+          await sv.upsertMigrationStatus(done);
+          try {
+            await sv.appendEvent({ type: "migration-completed", group: this.name, vaultId, version: target });
+          } catch {
+          }
+          return done;
+        } catch (err) {
+          const error = err instanceof Error ? err.message : String(err);
+          const failed = { ...base, status: "failed", error, finishedAt: Date.now() };
+          await sv.upsertMigrationStatus(failed);
+          try {
+            await sv.appendEvent({ type: "migration-failed", group: this.name, vaultId, version: target, detail: error });
+          } catch {
+          }
+          return failed;
+        }
+      }
+      /**
+       * Active batch runner (#271): migrate every shard behind the template version
+       * to it, in controlled batches. **Resumable + crash-safe** — shards already at
+       * the target are skipped (the registry version is the source of truth), so a
+       * re-run after a crash only picks up the unfinished + previously-failed shards.
+       *
+       * - `cohort` — restrict to these partition keys (the staged / canary rollout:
+       *   migrate a small cohort, verify the Insight Vault, then run the rest).
+       * - `batchSize` — max shards migrated concurrently per batch (back-pressure).
+       *   Default 4. Batches run sequentially; shards within a batch run in parallel.
+       */
+      async migrateFleet(options = {}) {
+        const target = this.template.version;
+        const rows = await this.allRows();
+        const cohort = options.cohort;
+        const todo = rows.filter(
+          (r) => r.schemaVersion < target && (cohort === void 0 || cohort.includes(r.partitionKey))
+        );
+        const batchSize = Math.max(1, options.batchSize ?? 4);
+        const migrated = [];
+        const failed = [];
+        for (let i = 0; i < todo.length; i += batchSize) {
+          const batch = todo.slice(i, i + batchSize);
+          const settled = await Promise.all(batch.map((r) => this.migrateShard(r.partitionKey)));
+          for (const res of settled) {
+            if (res.status === "done") migrated.push(res.vaultId);
+            else failed.push({ vaultId: res.vaultId, error: res.error ?? "unknown" });
+          }
+        }
+        return { target, migrated, failed };
+      }
     };
     ShardedCollection = class {
       constructor(group, collectionName) {
@@ -19054,7 +20392,7 @@ var init_vault_group = __esm({
           if (this.group.sharding.autoCreate === false) {
             throw new UnknownShardError(key, this.group.name);
           }
-          vault = await this.group.createShard(key);
+          vault = await this.group.createShard(key, this.group.sharding.regionOf?.(record));
         } else {
           vault = await this.group.openShard(key);
         }
@@ -19244,159 +20582,6 @@ var init_vault_group = __esm({
   }
 });
 
-// src/federation/schema-manifest.ts
-function captureBlueprint(configure) {
-  const recorded = [];
-  const collectionStub = new Proxy(
-    {},
-    {
-      get: () => () => collectionStub
-    }
-  );
-  const proxy = new Proxy(
-    {},
-    {
-      get: (_t, prop) => {
-        if (prop === "collection") {
-          return (name, opts) => {
-            recorded.push({
-              name,
-              indexes: opts?.indexes ?? [],
-              persistJsonSchema: !!opts?.persistJsonSchema
-            });
-            return collectionStub;
-          };
-        }
-        return () => proxy;
-      }
-    }
-  );
-  configure(proxy);
-  const sorted = [...recorded].sort((a, b) => a.name.localeCompare(b.name));
-  const indexes = {};
-  const persistJsonSchema = [];
-  for (const c of sorted) {
-    indexes[c.name] = c.indexes;
-    if (c.persistJsonSchema) persistJsonSchema.push(c.name);
-  }
-  return {
-    // `persistJsonSchema` is already name-sorted: it is populated while
-    // iterating `sorted` (collections in name order).
-    collections: sorted.map((c) => c.name),
-    indexes,
-    persistJsonSchema
-  };
-}
-function canonical(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  const obj = value;
-  const keys = Object.keys(obj).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
-}
-async function fingerprintBlueprint(bp) {
-  return sha256Hex2(new TextEncoder().encode(canonical(bp)));
-}
-var init_schema_manifest = __esm({
-  "src/federation/schema-manifest.ts"() {
-    "use strict";
-    init_crypto();
-  }
-});
-
-// src/federation/state-vault.ts
-var state_vault_exports = {};
-__export(state_vault_exports, {
-  STATE_VAULT_NAME: () => STATE_VAULT_NAME,
-  StateManagementVault: () => StateManagementVault
-});
-var REGISTRY, MANIFEST, EVENTS, StateManagementVault;
-var init_state_vault = __esm({
-  "src/federation/state-vault.ts"() {
-    "use strict";
-    init_schema_manifest();
-    init_constants2();
-    init_ulid();
-    init_constants2();
-    REGISTRY = "vaultRegistry";
-    MANIFEST = "schemaManifest";
-    EVENTS = "deploymentEvents";
-    StateManagementVault = class _StateManagementVault {
-      constructor(registry, schemaManifest, events) {
-        this.registry = registry;
-        this.schemaManifest = schemaManifest;
-        this.#events = events;
-      }
-      registry;
-      schemaManifest;
-      /**
-       * The append-only deployment-events log is kept truly private so the raw
-       * mutable Collection is never surfaced — events may only be written via
-       * `appendEvent` and read via `queryEvents`. (`registry` and
-       * `schemaManifest` are deliberately public: consumers read and write them.)
-       */
-      #events;
-      /** Idempotently open the reserved state vault and bind the three control-plane collections. */
-      static async open(db) {
-        const vault = await db.openVault(STATE_VAULT_NAME);
-        return new _StateManagementVault(
-          vault.collection(REGISTRY),
-          vault.collection(MANIFEST),
-          vault.collection(EVENTS)
-        );
-      }
-      /** Read-only query over the append-only deployment-events log. */
-      queryEvents() {
-        return this.#events.query();
-      }
-      /**
-       * Append a deployment event with a fresh unique (ULID) id. This is the
-       * only write path to the events log; no update/delete is exposed.
-       * Callers should treat failures as non-fatal — this method does not
-       * swallow errors, so wrap the call site in try/catch where appropriate.
-       */
-      async appendEvent(event) {
-        const ts = event.ts ?? Date.now();
-        const id = generateULID();
-        await this.#events.put(id, { ...event, id, ts });
-      }
-      /**
-       * Ensure a manifest row exists for `(templateName, template.version)`.
-       * Safe to call repeatedly: the `fingerprint` is a deterministic hash of
-       * the template's declared shape (stable across calls), though each call
-       * refreshes `recordedAt`.
-       */
-      async recordManifest(templateName, template) {
-        const bp = captureBlueprint(template.configure);
-        const fingerprint = await fingerprintBlueprint(bp);
-        await this.schemaManifest.put(`${templateName}:${template.version}`, {
-          templateName,
-          version: template.version,
-          collections: bp.collections,
-          indexes: bp.indexes,
-          persistJsonSchema: bp.persistJsonSchema,
-          fingerprint,
-          recordedAt: Date.now()
-        });
-        return fingerprint;
-      }
-      /**
-       * True when `template`'s current declared shape does not match the recorded
-       * manifest for `(templateName, template.version)`. Because shards carry no
-       * schema state independent of their template, this catches "a template's
-       * shape changed without bumping `version`" — not independent per-shard drift.
-       * A missing manifest is treated as drift (nothing to verify against).
-       */
-      async detectDrift(templateName, template) {
-        const row = await this.schemaManifest.get(`${templateName}:${template.version}`);
-        if (!row) return true;
-        const current = await fingerprintBlueprint(captureBlueprint(template.configure));
-        return current !== row.fingerprint;
-      }
-    };
-  }
-});
-
 // src/noydb.ts
 var noydb_exports = {};
 __export(noydb_exports, {
@@ -20266,7 +21451,7 @@ var init_noydb = __esm({
         const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
         const stateVault = opts.registry ? void 0 : await StateManagementVault2.open(this);
         const registry = opts.registry ?? stateVault.registry;
-        const group = new VaultGroup2(this, name, registry, opts.sharding, template);
+        const group = new VaultGroup2(this, name, registry, opts.sharding, template, opts.migrateOnOpen ?? false);
         if (stateVault) {
           group._attachStateVault(stateVault);
           await stateVault.recordManifest(opts.sharding.vaultTemplate, template);
@@ -20300,6 +21485,16 @@ var init_noydb = __esm({
       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.
        *