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

package/dist/index.cjs

@@ -46,7 +46,7 @@ var init_types = __esm({
 });
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, PeriodClosedError, RecordLockedError, FieldFrozenError, IllegalTransitionError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, ScriptViolationError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, SnapshotNotFoundError, UnknownShardError, ShardProvisioningError, CrossShardJoinError, VaultTemplateNotFoundError, ForgetStrategyNotConfiguredError, SealedRecordExpiredError, SealedRecordMismatchError, RecordCekNotFoundError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, PeriodClosedError, RecordLockedError, FieldFrozenError, IllegalTransitionError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, ScriptViolationError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, SnapshotNotFoundError, UnknownShardError, ShardProvisioningError, DataResidencyError, CrossShardJoinError, VaultTemplateNotFoundError, ForgetStrategyNotConfiguredError, SealedRecordExpiredError, SealedRecordMismatchError, RecordCekNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -1035,6 +1035,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);
@@ -2433,9 +2448,371 @@ __export(public_envelope_exports, {
 var init_public_envelope = __esm({
   "src/meta/public-envelope/index.ts"() {
     "use strict";
-    init_types2();
-    init_schema();
-    init_storage();
+    init_types2();
+    init_schema();
+    init_storage();
+  }
+});
+
+// src/i18n/policy.ts
+function resolvePolicy(onMissing, layer) {
+  const explicit = onMissing && typeof onMissing === "object" ? onMissing[layer] : void 0;
+  const scalar = typeof onMissing === "string" ? onMissing : void 0;
+  const layerDefault = layer === "guard" ? "substitute" : void 0;
+  return explicit ?? layerDefault ?? scalar ?? "throw";
+}
+var init_policy = __esm({
+  "src/i18n/policy.ts"() {
+    "use strict";
+  }
+});
+
+// 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"];
+}
+function allowedFor(descriptor, locale) {
+  const script = descriptor.options.script;
+  if (script && script !== "auto") {
+    const explicit = script[locale];
+    if (explicit) return explicit;
+  }
+  return inferScripts(locale);
+}
+function fullMatcher(scripts) {
+  const cls = scripts.map((s) => `\\p{Script=${s}}`).join("");
+  return new RegExp(`^[${BASELINE}${cls}]*$`, "u");
+}
+function charMatcher(scripts) {
+  const cls = scripts.map((s) => `\\p{Script=${s}}`).join("");
+  return new RegExp(`[${BASELINE}${cls}]`, "u");
+}
+function offendingSample(str, scripts) {
+  const ok = charMatcher(scripts);
+  const bad = [];
+  for (const ch of str) {
+    if (!ok.test(ch)) bad.push(ch);
+    if (bad.length >= 8) break;
+  }
+  return bad.join("");
+}
+function stripDisallowed(str, scripts) {
+  const ok = charMatcher(scripts);
+  let out = "";
+  for (const ch of str) if (ok.test(ch)) out += ch;
+  return out;
+}
+function enforceScript(value, field, descriptor) {
+  const opt = descriptor.options;
+  if (!opt.script) return { value, warnings: [] };
+  const mode = opt.onScriptViolation ?? "reject";
+  const warnings = [];
+  let out = value;
+  for (const [locale, raw] of Object.entries(value)) {
+    if (typeof raw !== "string") continue;
+    const allowed = allowedFor(descriptor, locale);
+    if (fullMatcher(allowed).test(raw)) continue;
+    const sample = offendingSample(raw, allowed);
+    if (mode === "reject") {
+      throw new ScriptViolationError(field, locale, allowed, sample);
+    }
+    warnings.push({ field, locale, expected: allowed, sample });
+    if (mode === "filter") {
+      if (out === value) out = { ...value };
+      out[locale] = stripDisallowed(raw, allowed);
+    }
+  }
+  return { value: out, warnings };
+}
+var LATIN_BASE, SCRIPT_TABLE, SUBTAG_SCRIPTS, BASELINE;
+var init_script = __esm({
+  "src/i18n/script.ts"() {
+    "use strict";
+    init_errors();
+    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 i18nText(options) {
+  return { _noydbI18nText: true, options };
+}
+function isI18nTextDescriptor(x) {
+  return typeof x === "object" && x !== null && x._noydbI18nText === true;
+}
+function validateI18nTextValue(value, field, descriptor) {
+  const { options } = descriptor;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new MissingTranslationError(
+      field,
+      options.languages,
+      `Field "${field}" must be a { [locale]: string } map, got ${typeof value}.`
+    );
+  }
+  const map = value;
+  for (const [locale, v] of Object.entries(map)) {
+    if (typeof v !== "string") {
+      throw new MissingTranslationError(
+        field,
+        [locale],
+        `Field "${field}": locale "${locale}" must be a string, got ${typeof v}.`
+      );
+    }
+  }
+  const { required } = options;
+  if (required === "all") {
+    const missing = options.languages.filter(
+      (lang) => !(lang in map) || map[lang] === ""
+    );
+    if (missing.length > 0) {
+      throw new MissingTranslationError(
+        field,
+        missing,
+        `Field "${field}" requires all declared languages. Missing: ${missing.join(", ")}.`
+      );
+    }
+  } else if (required === "any") {
+    const present = options.languages.some(
+      (lang) => lang in map && map[lang] !== ""
+    );
+    if (!present) {
+      throw new MissingTranslationError(
+        field,
+        options.languages,
+        `Field "${field}" requires at least one declared language. None present.`
+      );
+    }
+  } else {
+    const requiredList = required;
+    const missing = requiredList.filter(
+      (lang) => !(lang in map) || map[lang] === ""
+    );
+    if (missing.length > 0) {
+      throw new MissingTranslationError(
+        field,
+        missing,
+        `Field "${field}" requires: ${requiredList.join(", ")}. Missing: ${missing.join(", ")}.`
+      );
+    }
+  }
+}
+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) {
+    const arrayKey = path.slice(0, arrayIdx);
+    const restPath = path.slice(arrayIdx + 3);
+    const arr = obj[arrayKey];
+    if (!Array.isArray(arr)) return [];
+    return arr.flatMap((item) => {
+      if (!item || typeof item !== "object" || Array.isArray(item)) return [];
+      return getAtPath(item, restPath);
+    });
+  }
+  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 [];
+    return getAtPath(nested, rest);
+  }
+  const val = obj[path];
+  return val !== void 0 ? [val] : [];
+}
+function setAtPathInPlace(obj, path, value) {
+  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;
+    setAtPathInPlace(nested, rest, value);
+    return;
+  }
+  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();
   }
 });
 
@@ -3418,6 +3795,7 @@ var init_groupby = __esm({
     init_canonical_key();
     init_errors();
     init_money_reducer();
+    init_core();
     GROUPBY_WARN_CARDINALITY = 1e4;
     GROUPBY_MAX_CARDINALITY = 1e5;
     warnedCardinalityFields = /* @__PURE__ */ new Set();
@@ -3486,9 +3864,29 @@ var init_groupby = __esm({
       upstreams;
       dictLabelResolver;
       fields;
-      /** Execute the query, group, reduce, and return an array of rows. */
-      run() {
-        return groupAndReduce(this.executeRecords(), this.fields, this.spec);
+      /**
+       * Execute the query, group, reduce, and return an array of rows.
+       *
+       * `opts` (#285 query-form MV grouping): when a `locale` + `i18nFields` are
+       * given, the declared group-key `i18nText` fields are resolved to that locale
+       * at the `mv` layer BEFORE bucketing — so an i18n group key is a stable string
+       * instead of a raw `{locale}` map. The MV executor passes the MV's
+       * `i18nLocale`/`i18nFields`; ordinary `.run()` callers pass nothing and are
+       * unaffected.
+       */
+      run(opts) {
+        let records = this.executeRecords();
+        if (opts?.locale !== void 0 && opts.i18nFields !== void 0) {
+          const groupI18n = {};
+          for (const f of this.fields) {
+            const d = opts.i18nFields[f];
+            if (d !== void 0) groupI18n[f] = d;
+          }
+          if (Object.keys(groupI18n).length > 0) {
+            records = records.map((r) => applyI18nLocale(r, groupI18n, opts.locale, void 0, "mv"));
+          }
+        }
+        return groupAndReduce(records, this.fields, this.spec);
       }
       /**
        * Execute the query, group, reduce, and resolve `<field>Label` for
@@ -4073,12 +4471,13 @@ var executor_exports3 = {};
 __export(executor_exports3, {
   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;
     }
@@ -4107,6 +4506,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) {
@@ -4138,6 +4560,7 @@ var init_executor3 = __esm({
     init_registry();
     init_groupby();
     init_canonical_key();
+    init_core();
     DEFAULT_MAX_ROWS = 1e5;
     MaterializedViewExecutor = {
       async refresh(reg, accessor) {
@@ -4153,7 +4576,7 @@ var init_executor3 = __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);
@@ -5506,13 +5929,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), {
@@ -5594,8 +6025,19 @@ var init_vault_group = __esm({
        *
        * 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);
       }
       /**
@@ -5744,7 +6186,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);
         }
@@ -5971,6 +6413,7 @@ __export(src_exports, {
   DICT_COLLECTION_PREFIX: () => DICT_COLLECTION_PREFIX,
   DIRECTORY_RECORD_ID: () => DIRECTORY_RECORD_ID,
   DanglingReferenceError: () => DanglingReferenceError,
+  DataResidencyError: () => DataResidencyError,
   DecryptionError: () => DecryptionError,
   DelegationTargetMissingError: () => DelegationTargetMissingError,
   DerivationCapExceededError: () => DerivationCapExceededError,
@@ -6293,6 +6736,7 @@ __export(src_exports, {
   sha256Hex: () => sha256Hex3,
   staticDict: () => staticDict,
   sum: () => sum,
+  tokenize: () => tokenize,
   transitionGuard: () => transitionGuard,
   unwrapDeksFromBlob: () => unwrapDeksFromBlob,
   unwrapDeksFromPaperEntry: () => unwrapDeksFromPaperEntry,
@@ -6691,11 +7135,8 @@ async function compressBytes(data) {
   if (typeof CompressionStream === "undefined") {
     return { bytes: data, algorithm: "none" };
   }
-  const cs = new CompressionStream("gzip");
-  const writer = cs.writable.getWriter();
-  await writer.write(data);
-  await writer.close();
-  const buf = await new Response(cs.readable).arrayBuffer();
+  const piped = new Response(data).body.pipeThrough(new CompressionStream("gzip"));
+  const buf = await new Response(piped).arrayBuffer();
   return { bytes: new Uint8Array(buf), algorithm: "gzip" };
 }
 async function decompressBytes(data) {
@@ -6704,11 +7145,8 @@ async function decompressBytes(data) {
       "[noy-db] DecompressionStream not available \u2014 cannot decompress blob chunk"
     );
   }
-  const ds = new DecompressionStream("gzip");
-  const writer = ds.writable.getWriter();
-  await writer.write(data);
-  await writer.close();
-  const buf = await new Response(ds.readable).arrayBuffer();
+  const piped = new Response(data).body.pipeThrough(new DecompressionStream("gzip"));
+  const buf = await new Response(piped).arrayBuffer();
   return new Uint8Array(buf);
 }
 function concatChunks(chunks) {
@@ -8240,6 +8678,14 @@ function routeStore(opts) {
       const q = {};
       for (const [k, v] of writeQueues) q[k] = v.writes.length;
       return { overrides: ov, suspended: [...suspended], queued: q };
+    },
+    resolveBackend(vaultId) {
+      if (opts.vaultRoutes) {
+        for (const [prefix, s] of Object.entries(opts.vaultRoutes)) {
+          if (vaultId.startsWith(prefix)) return s;
+        }
+      }
+      return primary;
     }
   };
   if (anyHas("listVaults")) {
@@ -12406,286 +12852,91 @@ async function recoverUser(store, vault, callerKeyring, options) {
   const target = JSON.parse(env._data);
   const targetRole = options.role ?? target.role;
   if (!canRecover(callerKeyring.role, targetRole)) {
-    throw new PermissionDeniedError(
-      `Role "${callerKeyring.role}" cannot recover role "${targetRole}"`
-    );
-  }
-  if (!canRecover(callerKeyring.role, target.role)) {
-    throw new PermissionDeniedError(
-      `Role "${callerKeyring.role}" cannot recover role "${target.role}"`
-    );
-  }
-  for (const coll of Object.keys(target.deks)) {
-    if (!callerKeyring.deks.has(coll)) {
-      throw new PrivilegeEscalationError(coll);
-    }
-  }
-  if (options.validatePassphrase && !options.allowWeakPassphrase) {
-    assertStrongPassphrase(options.passphrase, options.passphrasePolicy);
-  }
-  const newSalt = generateSalt();
-  const newKek = await deriveKey(options.passphrase, newSalt);
-  const wrappedDeks = {};
-  for (const coll of Object.keys(target.deks)) {
-    const callerDek = callerKeyring.deks.get(coll);
-    if (!callerDek) {
-      throw new PrivilegeEscalationError(coll);
-    }
-    wrappedDeks[coll] = await wrapKey(callerDek, newKek);
-  }
-  const canary = await mintKeyringCanary(newKek);
-  const next = {
-    ...target,
-    _noydb_keyring: NOYDB_KEYRING_VERSION,
-    role: targetRole,
-    display_name: options.displayName ?? target.display_name,
-    deks: wrappedDeks,
-    salt: bufferToBase64(newSalt),
-    granted_by: callerKeyring.userId,
-    authenticators: [],
-    canary
-  };
-  const envelope = {
-    _noydb: 1,
-    _v: 1,
-    _ts: (/* @__PURE__ */ new Date()).toISOString(),
-    _iv: "",
-    _data: JSON.stringify(next)
-  };
-  await store.put(vault, "_keyring", options.userId, envelope);
-}
-
-// src/index.ts
-init_errors();
-
-// src/noydb.ts
-init_errors();
-init_constants();
-init_ulid();
-init_public_envelope();
-
-// src/vault.ts
-init_types();
-
-// src/collection.ts
-init_types();
-
-// src/crdt/strategy.ts
-var NOT_ENABLED = new Error(
-  'CRDT mode requires the CRDT strategy. Import `{ withCrdt }` from "@noy-db/hub/crdt" and pass it to `createNoydb({ crdtStrategy: withCrdt() })`.'
-);
-var NO_CRDT = {
-  buildLwwMapState() {
-    throw NOT_ENABLED;
-  },
-  buildRgaState() {
-    throw NOT_ENABLED;
-  },
-  mergeCrdtStates() {
-    throw NOT_ENABLED;
-  },
-  resolveCrdtSnapshot() {
-    throw NOT_ENABLED;
-  }
-};
-
-// src/i18n/core.ts
-init_errors();
-
-// src/i18n/policy.ts
-function resolvePolicy(onMissing, layer) {
-  const explicit = onMissing && typeof onMissing === "object" ? onMissing[layer] : void 0;
-  const scalar = typeof onMissing === "string" ? onMissing : void 0;
-  const layerDefault = layer === "guard" ? "substitute" : void 0;
-  return explicit ?? layerDefault ?? scalar ?? "throw";
-}
-
-// src/i18n/core.ts
-function i18nText(options) {
-  return { _noydbI18nText: true, options };
-}
-function isI18nTextDescriptor(x) {
-  return typeof x === "object" && x !== null && x._noydbI18nText === true;
-}
-function validateI18nTextValue(value, field, descriptor) {
-  const { options } = descriptor;
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new MissingTranslationError(
-      field,
-      options.languages,
-      `Field "${field}" must be a { [locale]: string } map, got ${typeof value}.`
-    );
-  }
-  const map = value;
-  for (const [locale, v] of Object.entries(map)) {
-    if (typeof v !== "string") {
-      throw new MissingTranslationError(
-        field,
-        [locale],
-        `Field "${field}": locale "${locale}" must be a string, got ${typeof v}.`
-      );
-    }
-  }
-  const { required } = options;
-  if (required === "all") {
-    const missing = options.languages.filter(
-      (lang) => !(lang in map) || map[lang] === ""
-    );
-    if (missing.length > 0) {
-      throw new MissingTranslationError(
-        field,
-        missing,
-        `Field "${field}" requires all declared languages. Missing: ${missing.join(", ")}.`
-      );
-    }
-  } else if (required === "any") {
-    const present = options.languages.some(
-      (lang) => lang in map && map[lang] !== ""
-    );
-    if (!present) {
-      throw new MissingTranslationError(
-        field,
-        options.languages,
-        `Field "${field}" requires at least one declared language. None present.`
-      );
-    }
-  } else {
-    const requiredList = required;
-    const missing = requiredList.filter(
-      (lang) => !(lang in map) || map[lang] === ""
-    );
-    if (missing.length > 0) {
-      throw new MissingTranslationError(
-        field,
-        missing,
-        `Field "${field}" requires: ${requiredList.join(", ")}. Missing: ${missing.join(", ")}.`
-      );
-    }
-  }
-}
-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 (policy === "throw") {
-    throw new LocaleNotSpecifiedError(
-      field ?? "<unknown>",
-      `No translation available for locale "${locale}"` + (callerChain.length > 0 ? ` or fallback chain [${callerChain.join(", ")}]` : "") + "."
-    );
-  }
-  return null;
-}
-function getAtPath(obj, path) {
-  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 [];
-    return arr.flatMap((item) => {
-      if (!item || typeof item !== "object" || Array.isArray(item)) return [];
-      return getAtPath(item, restPath);
-    });
+    throw new PermissionDeniedError(
+      `Role "${callerKeyring.role}" cannot recover role "${targetRole}"`
+    );
   }
-  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 [];
-    return getAtPath(nested, rest);
+  if (!canRecover(callerKeyring.role, target.role)) {
+    throw new PermissionDeniedError(
+      `Role "${callerKeyring.role}" cannot recover role "${target.role}"`
+    );
   }
-  const val = obj[path];
-  return val !== void 0 ? [val] : [];
-}
-function setAtPathInPlace(obj, path, value) {
-  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;
-    setAtPathInPlace(nested, rest, value);
-    return;
+  for (const coll of Object.keys(target.deks)) {
+    if (!callerKeyring.deks.has(coll)) {
+      throw new PrivilegeEscalationError(coll);
+    }
   }
-  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);
-      })
-    };
+  if (options.validatePassphrase && !options.allowWeakPassphrase) {
+    assertStrongPassphrase(options.passphrase, options.passphrasePolicy);
   }
-  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 newSalt = generateSalt();
+  const newKek = await deriveKey(options.passphrase, newSalt);
+  const wrappedDeks = {};
+  for (const coll of Object.keys(target.deks)) {
+    const callerDek = callerKeyring.deks.get(coll);
+    if (!callerDek) {
+      throw new PrivilegeEscalationError(coll);
+    }
+    wrappedDeks[coll] = await wrapKey(callerDek, newKek);
   }
-  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)
+  const canary = await mintKeyringCanary(newKek);
+  const next = {
+    ...target,
+    _noydb_keyring: NOYDB_KEYRING_VERSION,
+    role: targetRole,
+    display_name: options.displayName ?? target.display_name,
+    deks: wrappedDeks,
+    salt: bufferToBase64(newSalt),
+    granted_by: callerKeyring.userId,
+    authenticators: [],
+    canary
+  };
+  const envelope = {
+    _noydb: 1,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(next)
   };
+  await store.put(vault, "_keyring", options.userId, envelope);
 }
-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 } = descriptor.options;
-    const opts = {
-      policy: resolvePolicy(onMissing, layer),
-      ...substitute !== void 0 ? { substitute } : {}
-    };
-    result = applyAtPath(result, field, locale, fallback, opts);
+
+// src/index.ts
+init_errors();
+
+// src/noydb.ts
+init_errors();
+init_constants();
+init_ulid();
+init_public_envelope();
+
+// src/vault.ts
+init_types();
+
+// src/collection.ts
+init_types();
+
+// src/crdt/strategy.ts
+var NOT_ENABLED = new Error(
+  'CRDT mode requires the CRDT strategy. Import `{ withCrdt }` from "@noy-db/hub/crdt" and pass it to `createNoydb({ crdtStrategy: withCrdt() })`.'
+);
+var NO_CRDT = {
+  buildLwwMapState() {
+    throw NOT_ENABLED;
+  },
+  buildRgaState() {
+    throw NOT_ENABLED;
+  },
+  mergeCrdtStates() {
+    throw NOT_ENABLED;
+  },
+  resolveCrdtSnapshot() {
+    throw NOT_ENABLED;
   }
-  return result;
-}
+};
+
+// src/collection.ts
+init_core();
 
 // src/i18n/dictionary.ts
 init_types();
@@ -13390,6 +13641,7 @@ var NO_I18N = {
 };
 
 // src/collection.ts
+init_policy();
 init_crypto();
 init_errors();
 init_tiers();
@@ -13441,6 +13693,7 @@ init_predicate();
 // src/query/join.ts
 init_predicate();
 init_errors();
+init_core();
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
 var JOIN_WARN_FRACTION = 0.8;
 function coerceRefKey(value) {
@@ -13468,15 +13721,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) {
@@ -13531,24 +13784,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");
@@ -13561,7 +13817,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;
@@ -13859,11 +14116,16 @@ var Query = class _Query {
       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
@@ -14066,16 +14328,21 @@ var Query = class _Query {
    * 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
@@ -14094,9 +14361,9 @@ var Query = class _Query {
     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;
   }
   /**
@@ -14339,7 +14606,7 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan, joinContext) {
+function executePlanWithSource(source, plan, joinContext, locale) {
   const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
   let result;
   if (hasCrossJoins) {
@@ -14354,7 +14621,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, source.moneyFields);
+    const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale);
+    result = sortRecords(result, plan.orderBy, source.moneyFields, labelMaps);
   }
   if (plan.offset > 0) {
     result = result.slice(plan.offset);
@@ -14511,11 +14779,19 @@ function applyCrossJoin(leftRel, clause, rightSource) {
   }
   return expanded;
 }
-function sortRecords(records, orderBy, moneyFields) {
+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);
+    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;
@@ -14523,6 +14799,28 @@ function sortRecords(records, orderBy, moneyFields) {
     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);
@@ -15502,6 +15800,74 @@ var DISABLED_STATE = {
   getPersistedIndexes: () => null
 };
 
+// src/search/tokenize.ts
+var WORD = /[\p{L}\p{N}]+/gu;
+var tokenize = (text) => {
+  if (!text) return [];
+  return text.normalize("NFKC").toLowerCase().match(WORD) ?? [];
+};
+
+// src/search/scan.ts
+var K1 = 1.2;
+var B = 0.75;
+function fieldText(record, field) {
+  const v = record[field];
+  if (typeof v === "string") return v;
+  if (v === null || v === void 0) return "";
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return "";
+}
+function searchScan(entries, field, query, opts = {}, tokenizer = tokenize) {
+  const queryTerms = tokenizer(query);
+  if (queryTerms.length === 0) return [];
+  const match = opts.match ?? "any";
+  const usePrefix = opts.prefix ?? false;
+  const exactTerms = usePrefix ? queryTerms.slice(0, -1) : queryTerms;
+  const prefixTerm = usePrefix ? queryTerms[queryTerms.length - 1] : void 0;
+  const docs = entries.map((e) => ({ id: e.id, record: e.record, terms: tokenizer(fieldText(e.record, field)) }));
+  const N = docs.length || 1;
+  const df = /* @__PURE__ */ new Map();
+  let totalLen = 0;
+  for (const d of docs) {
+    totalLen += d.terms.length;
+    for (const t of new Set(d.terms)) df.set(t, (df.get(t) ?? 0) + 1);
+  }
+  const avgdl = totalLen / N || 1;
+  let prefixDf = 0;
+  if (prefixTerm !== void 0) {
+    for (const d of docs) {
+      if (d.terms.some((t) => t.startsWith(prefixTerm))) prefixDf++;
+    }
+  }
+  const requiredCount = exactTerms.length + (prefixTerm !== void 0 ? 1 : 0);
+  const results = [];
+  for (const d of docs) {
+    const tf = /* @__PURE__ */ new Map();
+    for (const t of d.terms) tf.set(t, (tf.get(t) ?? 0) + 1);
+    const matched = [];
+    for (const qt of exactTerms) {
+      const c = tf.get(qt) ?? 0;
+      if (c > 0) matched.push({ tf: c, df: df.get(qt) ?? 0 });
+    }
+    if (prefixTerm !== void 0) {
+      let ptf = 0;
+      for (const [t, c] of tf) if (t.startsWith(prefixTerm)) ptf += c;
+      if (ptf > 0) matched.push({ tf: ptf, df: prefixDf });
+    }
+    if (matched.length === 0) continue;
+    if (match === "all" && matched.length < requiredCount) continue;
+    let score = 0;
+    for (const m of matched) {
+      const idf = Math.log(1 + (N - m.df + 0.5) / (m.df + 0.5));
+      const denom = m.tf + K1 * (1 - B + B * (d.terms.length / avgdl));
+      score += idf * (m.tf * (K1 + 1) / (denom || 1));
+    }
+    results.push({ id: d.id, score, record: d.record });
+  }
+  results.sort((a, b) => b.score - a.score);
+  return opts.limit !== void 0 ? results.slice(0, opts.limit) : results;
+}
+
 // src/collection.ts
 init_errors();
 
@@ -17789,6 +18155,29 @@ var Collection = class {
   hasReadTransforms() {
     return this.moneyFields !== void 0 && Object.keys(this.moneyFields).length > 0 || this.i18nFields !== void 0 && Object.keys(this.i18nFields).length > 0 || this.dictKeyFields !== void 0 && Object.keys(this.dictKeyFields).length > 0;
   }
+  /**
+   * Scan-mode full-text search over a plain-text `field` (#308). Decrypts the
+   * collection in memory and ranks records by BM25 against the tokenized query.
+   * **Zero added store leakage** — pure client-side scan; nothing searchable is
+   * written to the store. (A store-usable blind index for at-scale search is a
+   * separate, gated opt-in — see the #308 design note.) Eager mode only.
+   *
+   * `opts.match` (`'any'` default | `'all'`), `opts.prefix` (last query term as
+   * a prefix → typeahead), `opts.limit` (top-N). Returns `{ id, score, record }`
+   * ranked by descending score. The default tokenizer is word-boundary based —
+   * see `src/search/tokenize.ts` for the Thai/CJK caveat.
+   */
+  async search(field, query, opts = {}) {
+    if (this.lazy) {
+      throw new Error(
+        `Collection "${this.name}": search() (scan mode) requires eager mode (prefetch: true). A store-usable blind index for lazy / at-scale search is a separate gated opt-in (#308).`
+      );
+    }
+    await this.ensureHydrated();
+    const entries = [];
+    for (const [id, e] of this.cache) entries.push({ id, record: e.record });
+    return searchScan(entries, field, query, opts);
+  }
   // ─── Bulk operations ─────────────────────────────────────
   /**
    * Put many records in one call. Each item is processed sequentially
@@ -17966,6 +18355,10 @@ var Collection = class {
       leftCollection,
       resolveRef: (field) => resolver.resolveRef(leftCollection, field),
       resolveSource: (collectionName) => resolver.resolveSource(collectionName),
+      // #285 §3 — flow the vault/collection default locale to joins so a
+      // joined i18n field resolves like get()/list() when no per-call
+      // locale is given; toArray({ locale }) overrides it.
+      ...this.defaultLocale !== void 0 ? { defaultLocale: this.defaultLocale } : {},
       ...resolver.resolveDictSource ? { resolveDictSource: (field) => resolver.resolveDictSource(leftCollection, field) } : {}
     } : void 0;
     return new Query(source, void 0, joinContext, this.aggregateStrategy);
@@ -18054,7 +18447,10 @@ var Collection = class {
         };
         this.emitter.on("change", handler);
         return () => this.emitter.off("change", handler);
-      }
+      },
+      // #285 §3 — expose this (right-side) collection's i18nText descriptors so
+      // the join executor can resolve joined i18n fields at the `join` layer.
+      ...this.i18nFields !== void 0 ? { i18nFields: this.i18nFields } : {}
     };
   }
   /**
@@ -18287,6 +18683,10 @@ var Collection = class {
       leftCollection,
       resolveRef: (field) => resolver.resolveRef(leftCollection, field),
       resolveSource: (collectionName) => resolver.resolveSource(collectionName),
+      // #285 §3 — flow the vault/collection default locale to joins so a
+      // joined i18n field resolves like get()/list() when no per-call
+      // locale is given; toArray({ locale }) overrides it.
+      ...this.defaultLocale !== void 0 ? { defaultLocale: this.defaultLocale } : {},
       ...resolver.resolveDictSource ? { resolveDictSource: (field) => resolver.resolveDictSource(leftCollection, field) } : {}
     } : void 0;
     return new ScanBuilder(
@@ -18844,6 +19244,34 @@ var Collection = class {
       }
     }
   }
+  /**
+   * @internal — hard-delete this record's persisted `_idx/<field>/<recordId>`
+   * side-cars for the erasure path (#401). `forget()` crypto-shreds the body but
+   * keeps the collection DEK, under which these side-cars are encrypted — so
+   * without this they leave the indexed field VALUES readable after a "forget".
+   *
+   * Content-free: the side-car id is `encodeIdxId(def.key, id)`, so it needs no
+   * body decode (the body is being shredded). Eager mode has no durable side-car
+   * → no-op. The in-memory mirror is left as-is: it is ephemeral (rebuilt from
+   * the now-deleted side-cars on reopen) and live reads skip the tombstone, so a
+   * stale mirror hit cannot surface the erased record. Returns the count deleted
+   * + the `def.key`s whose delete FAILED (residue that still leaks the value).
+   */
+  async _purgePersistedIndexes(id) {
+    const persisted = this.persistedIndexes;
+    if (!persisted) return { purged: 0, residue: [] };
+    let purged = 0;
+    const residue = [];
+    for (const def of persisted.definitions()) {
+      try {
+        await this.adapter.delete(this.vault, this.name, encodeIdxId(def.key, id));
+        purged++;
+      } catch {
+        residue.push(def.key);
+      }
+    }
+    return { purged, residue };
+  }
   /**
    * Bulk-load the persisted-index mirror from `_idx/<field>/*` side-cars
    * on first lazy-mode query. Idempotent — subsequent calls short-circuit
@@ -19976,6 +20404,7 @@ var NO_PERIODS = {
 };
 
 // src/vault.ts
+init_core();
 init_errors();
 
 // src/periods/periods.ts
@@ -22586,6 +23015,8 @@ var Vault = class {
     const blobResidueCollections = /* @__PURE__ */ new Set();
     let blobsShredded = 0;
     let blobsRetainedShared = 0;
+    let indexPostingsPurged = 0;
+    const indexResidue = [];
     const blobsEnabled = this.blobStrategy !== void 0;
     const actor = this.keyring.userId;
     for (const ref2 of refs) {
@@ -22607,6 +23038,9 @@ var Vault = class {
         ref2.id,
         actor
       );
+      const idxPurge = await coll._purgePersistedIndexes(ref2.id);
+      indexPostingsPurged += idxPurge.purged;
+      for (const field of idxPurge.residue) indexResidue.push(`${ref2.collection}:${ref2.id}:${field}`);
       if (blobsEnabled) {
         const r = await this.collection(ref2.collection).blob(ref2.id).shredAllForRecord();
         blobsShredded += r.shredded.length;
@@ -22642,7 +23076,9 @@ var Vault = class {
         unmigratedCount: unmigratedRecords.length,
         blobsShredded,
         blobsRetainedShared,
-        blobResidueCollections: [...blobResidueCollections]
+        blobResidueCollections: [...blobResidueCollections],
+        indexPostingsPurged,
+        indexResidueCount: indexResidue.length
       })
     });
     return {
@@ -22654,6 +23090,8 @@ var Vault = class {
       blobsShredded,
       blobsRetainedShared,
       blobResidueCollections: [...blobResidueCollections],
+      indexPostingsPurged,
+      indexResidue,
       ledgerEntry
     };
   }
@@ -23916,6 +24354,8 @@ var Vault = class {
    */
   async *exportStream(opts = {}) {
     const granularity = opts.granularity ?? "collection";
+    const exportLocale = opts.resolveLabels;
+    const localeOpts = exportLocale !== void 0 ? { locale: exportLocale, _layer: "export" } : void 0;
     const snapshot = await this.adapter.loadAll(this.name);
     const collectionNames = Object.keys(snapshot).sort();
     const ledgerHead = opts.withLedgerHead ? await (async () => {
@@ -23925,19 +24365,21 @@ var Vault = class {
       return head ? { hash: head.hash, index: head.entry.index, ts: head.entry.ts } : void 0;
     })() : void 0;
     const dictSnapshotCache = /* @__PURE__ */ new Map();
-    for (const collectionName of collectionNames) {
-      const dictFields = this.dictKeyFieldRegistry.get(collectionName);
-      if (dictFields && Object.keys(dictFields).length > 0) {
-        const snap = {};
-        for (const [fieldName, dictName] of Object.entries(dictFields)) {
-          const entries = await this.dictionary(dictName).list();
-          const keyMap = {};
-          for (const entry of entries) {
-            keyMap[entry.key] = entry.labels;
+    if (exportLocale === void 0) {
+      for (const collectionName of collectionNames) {
+        const dictFields = this.dictKeyFieldRegistry.get(collectionName);
+        if (dictFields && Object.keys(dictFields).length > 0) {
+          const snap = {};
+          for (const [fieldName, dictName] of Object.entries(dictFields)) {
+            const entries = await this.dictionary(dictName).list();
+            const keyMap = {};
+            for (const entry of entries) {
+              keyMap[entry.key] = entry.labels;
+            }
+            snap[fieldName] = keyMap;
           }
-          snap[fieldName] = keyMap;
+          dictSnapshotCache.set(collectionName, snap);
         }
-        dictSnapshotCache.set(collectionName, snap);
       }
     }
     for (const collectionName of collectionNames) {
@@ -23950,7 +24392,7 @@ var Vault = class {
       if (granularity === "collection") {
         const records = [];
         for (const id of ids) {
-          const record = await coll.get(id);
+          const record = await coll.get(id, localeOpts);
           if (record !== null) records.push(record);
         }
         const chunk = {
@@ -23964,7 +24406,7 @@ var Vault = class {
         yield chunk;
       } else {
         for (const id of ids) {
-          const record = await coll.get(id);
+          const record = await coll.get(id, localeOpts);
           if (record === null) continue;
           const chunk = {
             collection: collectionName,
@@ -24068,7 +24510,10 @@ var Vault = class {
     const allDictionaries = {};
     for await (const chunk of this.exportStream({
       granularity: "collection",
-      withLedgerHead: opts.withLedgerHead === true
+      withLedgerHead: opts.withLedgerHead === true,
+      // #285 export layer: thread the export locale so records are read at the
+      // `export` layer (i18nText collapsed + dictKey/staticDict labels resolved).
+      ...opts.resolveLabels !== void 0 ? { resolveLabels: opts.resolveLabels } : {}
     })) {
       collections[chunk.collection] = {
         schema: null,
@@ -25902,6 +26347,16 @@ var Noydb = class {
   async _shardVaultProvisioned(vaultId) {
     return (await this.options.store.list(vaultId, "_keyring")).length > 0;
   }
+  /**
+   * @internal — the physical backend store a vault id maps to. A
+   * `routeStore` resolves the vault-prefix route via its `resolveBackend`;
+   * a plain store is its own backend. Used by the federation data-residency
+   * guard to read the placement backend's `capabilities.region` (#271).
+   */
+  _resolveBackend(vaultId) {
+    const store = this.options.store;
+    return store.resolveBackend ? store.resolveBackend(vaultId) : this.options.store;
+  }
   /**
    * Change the current user's passphrase for a vault.
    *
@@ -28461,6 +28916,11 @@ function withMaterializedView(spec) {
       );
     }
   }
+  if (spec.i18nLocale !== void 0 && spec.i18nFields === void 0) {
+    throw new MaterializedViewConfigError(
+      `withMaterializedView "${spec.name}": i18nLocale requires i18nFields \u2014 declare the i18nText descriptors of the group-key fields so they can be resolved at the mv layer before bucketing.`
+    );
+  }
   if (typeof spec.rowKey !== "function") {
     throw new ValidationError("withMaterializedView: rowKey is required (no default; see spec \xA7 Type surface)");
   }
@@ -28510,6 +28970,7 @@ function withOverlayedView(spec) {
 // src/index.ts
 init_errors();
 init_errors();
+init_core();
 
 // src/money/index.ts
 init_descriptor();
@@ -28626,138 +29087,9 @@ function isMoneyLike(value) {
   return decimalScaleOf(value) !== null;
 }
 
-// src/i18n/script.ts
-init_errors();
-var 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"
-]);
-var 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"]
-};
-var SUBTAG_SCRIPTS = {
-  Latn: ["Latin"],
-  Cyrl: ["Cyrillic", "Latin"],
-  Hans: ["Han", "Latin"],
-  Hant: ["Han", "Latin"],
-  Thai: ["Thai", "Latin"],
-  Arab: ["Arabic", "Latin"]
-};
-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"];
-}
-function allowedFor(descriptor, locale) {
-  const script = descriptor.options.script;
-  if (script && script !== "auto") {
-    const explicit = script[locale];
-    if (explicit) return explicit;
-  }
-  return inferScripts(locale);
-}
-var BASELINE = String.raw`\p{White_Space}\p{Script=Common}\p{Script=Inherited}\p{Mark}`;
-function fullMatcher(scripts) {
-  const cls = scripts.map((s) => `\\p{Script=${s}}`).join("");
-  return new RegExp(`^[${BASELINE}${cls}]*$`, "u");
-}
-function charMatcher(scripts) {
-  const cls = scripts.map((s) => `\\p{Script=${s}}`).join("");
-  return new RegExp(`[${BASELINE}${cls}]`, "u");
-}
-function offendingSample(str, scripts) {
-  const ok = charMatcher(scripts);
-  const bad = [];
-  for (const ch of str) {
-    if (!ok.test(ch)) bad.push(ch);
-    if (bad.length >= 8) break;
-  }
-  return bad.join("");
-}
-function stripDisallowed(str, scripts) {
-  const ok = charMatcher(scripts);
-  let out = "";
-  for (const ch of str) if (ok.test(ch)) out += ch;
-  return out;
-}
-function enforceScript(value, field, descriptor) {
-  const opt = descriptor.options;
-  if (!opt.script) return { value, warnings: [] };
-  const mode = opt.onScriptViolation ?? "reject";
-  const warnings = [];
-  let out = value;
-  for (const [locale, raw] of Object.entries(value)) {
-    if (typeof raw !== "string") continue;
-    const allowed = allowedFor(descriptor, locale);
-    if (fullMatcher(allowed).test(raw)) continue;
-    const sample = offendingSample(raw, allowed);
-    if (mode === "reject") {
-      throw new ScriptViolationError(field, locale, allowed, sample);
-    }
-    warnings.push({ field, locale, expected: allowed, sample });
-    if (mode === "filter") {
-      if (out === value) out = { ...value };
-      out[locale] = stripDisallowed(raw, allowed);
-    }
-  }
-  return { value: out, warnings };
-}
-
 // src/index.ts
+init_policy();
+init_script();
 init_errors();
 
 // src/team/sync-credentials.ts
@@ -29424,6 +29756,7 @@ function shortJSON(value) {
   DICT_COLLECTION_PREFIX,
   DIRECTORY_RECORD_ID,
   DanglingReferenceError,
+  DataResidencyError,
   DecryptionError,
   DelegationTargetMissingError,
   DerivationCapExceededError,
@@ -29746,6 +30079,7 @@ function shortJSON(value) {
   sha256Hex,
   staticDict,
   sum,
+  tokenize,
   transitionGuard,
   unwrapDeksFromBlob,
   unwrapDeksFromPaperEntry,