@noy-db/hub 0.2.0-pre.18 → 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();
   }
 });
 
@@ -4868,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) {
@@ -4931,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");
@@ -4961,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;
@@ -4996,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();
@@ -5300,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) {
@@ -5315,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, 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);
@@ -5454,11 +5666,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;
@@ -5466,6 +5686,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);
@@ -5766,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
@@ -5973,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
@@ -6001,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;
       }
       /**
@@ -7017,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 = [];
@@ -8034,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;
     }
@@ -8068,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) {
@@ -8099,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) {
@@ -8114,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);
@@ -8373,6 +8739,7 @@ var init_collection = __esm({
     init_persisted_indexes();
     init_lazy_builder();
     init_strategy5();
+    init_search();
     init_errors();
     init_unique_constraints();
     init_cache();
@@ -9935,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
@@ -10112,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);
@@ -10200,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 } : {}
         };
       }
       /**
@@ -10433,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(
@@ -10990,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
@@ -16353,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) {
@@ -16374,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;
@@ -16409,7 +16843,9 @@ var init_vault = __esm({
             unmigratedCount: unmigratedRecords.length,
             blobsShredded,
             blobsRetainedShared,
-            blobResidueCollections: [...blobResidueCollections]
+            blobResidueCollections: [...blobResidueCollections],
+            indexPostingsPurged,
+            indexResidueCount: indexResidue.length
           })
         });
         return {
@@ -16421,6 +16857,8 @@ var init_vault = __esm({
           blobsShredded,
           blobsRetainedShared,
           blobResidueCollections: [...blobResidueCollections],
+          indexPostingsPurged,
+          indexResidue,
           ledgerEntry
         };
       }
@@ -17683,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 () => {
@@ -17692,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) {
@@ -17717,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 = {
@@ -17731,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,
@@ -17835,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,
@@ -19690,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), {
@@ -19778,8 +20231,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);
       }
       /**
@@ -19928,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);
         }
@@ -21021,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.
        *