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

package/dist/i18n/index.d.cts

@@ -1,12 +1,12 @@
-import { I as I18nStrategy } from '../types-CrSpRDuG.cjs';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nMap, f as I18nTextDescriptor, g as I18nTextOptions, L as Layer, O as OnMissing, h as OnMissingPolicy, R as ResolveI18nOptions, S as ScriptWarning, i as StaticDictDescriptor, j as applyI18nLocale, k as dictCollectionName, l as dictKey, m as enforceScript, n as getAtPath, o as i18nText, p as inferScripts, q as isDictCollectionName, r as isDictKeyDescriptor, s as isI18nTextDescriptor, t as isStaticDictDescriptor, u as resolveI18nText, v as resolvePolicy, w as setAtPathInPlace, x as staticDict, y as validateI18nTextValue } from '../types-CrSpRDuG.cjs';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-Dz64FA65.cjs';
+export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, v as validateI18nTextValue } from '../strategy-C5ol6NdV.cjs';
+import { I as I18nStrategy } from '../types-D-gr5t0G.cjs';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-D-gr5t0G.cjs';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-DL-zTrrF.cjs';
 import '../lazy-builder-eYZzLEL1.cjs';
 import '../predicate-BmhBSPCH.cjs';
-import '../strategy-CLC1j79g.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-C-SSRIxP.cjs';
-import '../index-u-kWzSrL.cjs';
+import '../index-BMmajblo.cjs';
+import '../index-BM7O48Ur.cjs';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.d.ts

@@ -1,12 +1,12 @@
-import { I as I18nStrategy } from '../types-CljIHm_J.js';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nMap, f as I18nTextDescriptor, g as I18nTextOptions, L as Layer, O as OnMissing, h as OnMissingPolicy, R as ResolveI18nOptions, S as ScriptWarning, i as StaticDictDescriptor, j as applyI18nLocale, k as dictCollectionName, l as dictKey, m as enforceScript, n as getAtPath, o as i18nText, p as inferScripts, q as isDictCollectionName, r as isDictKeyDescriptor, s as isI18nTextDescriptor, t as isStaticDictDescriptor, u as resolveI18nText, v as resolvePolicy, w as setAtPathInPlace, x as staticDict, y as validateI18nTextValue } from '../types-CljIHm_J.js';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-Dz64FA65.js';
+export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, v as validateI18nTextValue } from '../strategy-BDxQnnTX.js';
+import { I as I18nStrategy } from '../types-CraiZOyO.js';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-CraiZOyO.js';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-DL-zTrrF.js';
 import '../lazy-builder-ChSqcF5t.js';
 import '../predicate-BmhBSPCH.js';
-import '../strategy-4M9jo172.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-C-SSRIxP.js';
-import '../index-DpU6KWof.js';
+import '../index-BMmajblo.js';
+import '../index-BelbyUwz.js';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.js

@@ -1,29 +1,29 @@
-import {
-  enforceScript,
-  inferScripts
-} from "../chunk-JDWE6JMX.js";
 import {
   DICT_COLLECTION_PREFIX,
   DictionaryHandle,
-  applyI18nLocale,
   dictCollectionName,
   dictKey,
-  getAtPath,
-  i18nText,
   isDictCollectionName,
   isDictKeyDescriptor,
-  isI18nTextDescriptor,
   isStaticDictDescriptor,
+  staticDict
+} from "../chunk-H42KZXNV.js";
+import {
+  applyI18nLocale,
+  enforceScript,
+  getAtPath,
+  i18nText,
+  inferScripts,
+  isI18nTextDescriptor,
   resolveI18nText,
   resolvePolicy,
   setAtPathInPlace,
-  staticDict,
   validateI18nTextValue
-} from "../chunk-ROPJVUG3.js";
-import "../chunk-BSZOCSDZ.js";
+} from "../chunk-VEIVAYJ7.js";
+import "../chunk-M3FPNTO2.js";
 import "../chunk-PDVP3C2I.js";
-import "../chunk-SISBMAPO.js";
-import "../chunk-UNTGHX5A.js";
+import "../chunk-SHIUFIPW.js";
+import "../chunk-OKOKPYWH.js";
 import {
   DictKeyInUseError,
   DictKeyMissingError,
@@ -34,7 +34,7 @@ import {
   StaticDictReadonlyError,
   TranslatorNotConfiguredError,
   UnknownDictCodeError
-} from "../chunk-ZEGSDPB7.js";
+} from "../chunk-DJF3FXW5.js";
 
 // src/i18n/active.ts
 function withI18n() {

package/dist/{index-u-kWzSrL.d.cts → index-BM7O48Ur.d.cts}

@@ -1,6 +1,6 @@
 import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-BmhBSPCH.cjs';
-import { N as NoydbError } from './errors-Dz64FA65.cjs';
-import { v as MoneyDescriptor, A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery, h as GroupedQueryN } from './strategy-CLC1j79g.cjs';
+import { N as NoydbError } from './errors-DL-zTrrF.cjs';
+import { a as I18nTextDescriptor, N as MoneyDescriptor, A as AggregateStrategy, j as AggregateSpec, k as Aggregation, h as AggregateResult, o as GroupedQuery, p as GroupedQueryN } from './strategy-C5ol6NdV.cjs';
 
 /**
  * Foreign-key references — the soft-FK mechanism.
@@ -59,7 +59,19 @@ type RefMode = 'strict' | 'warn' | 'cascade';
 interface RefDescriptor {
     readonly target: string;
     readonly mode: RefMode;
+    /**
+     * Present and `true` only for an array ref (#377-A, `refArray()`): the
+     * field holds an ARRAY of ids, each validated against `target`
+     * independently (M:N). Absent for a scalar `ref()`. The same `mode`
+     * semantics apply per element — strict rejects on a missing element at
+     * put + blocks delete of a referenced target; cascade deletes every
+     * record whose array contains the deleted id; warn surfaces orphans
+     * only via `checkIntegrity()`.
+     */
+    readonly isArray?: true;
 }
+/** Runtime predicate: is this an array ref (`refArray()`) vs a scalar `ref()`? */
+declare function isRefArray(desc: RefDescriptor): boolean;
 /**
  * Thrown when a strict reference is violated — either `put()` with a
  * missing target id, or `delete()` of a target that still has
@@ -102,6 +114,30 @@ declare class RefScopeError extends NoydbError {
  * fails at collection construction time, not at the first put.
  */
 declare function ref(target: string, mode?: RefMode): RefDescriptor;
+/**
+ * Array reference (#377-A) — the many-to-many soft-FK. The field holds an
+ * array of ids; each element is validated against `target` independently.
+ *
+ * ```ts
+ * const orders = company.collection<Order>('orders', {
+ *   refs: { productIds: refArray('products', 'warn') },
+ * })
+ * ```
+ *
+ * Same three `mode` semantics as `ref()`, applied per element:
+ *   - **strict** — `put()` rejects if ANY element's target is missing;
+ *     `delete()` of a target is blocked while any record's array still
+ *     contains its id.
+ *   - **warn** — both succeed; orphaned elements surface via
+ *     `vault.checkIntegrity()` (one violation per dangling element).
+ *   - **cascade** — `delete()` of a target deletes every record whose
+ *     array contains its id (cycle-safe, like scalar cascade).
+ *
+ * A `null`/`undefined` field is allowed (no links). Non-array values, or
+ * non-string/number elements, are an integrity error. Cross-vault targets
+ * are rejected exactly as in `ref()`.
+ */
+declare function refArray(target: string, mode?: RefMode): RefDescriptor;
 /**
  * Per-vault registry of reference declarations.
  *
@@ -144,6 +180,7 @@ declare class RefRegistry {
         collection: string;
         field: string;
         mode: RefMode;
+        isArray?: true;
     }>;
     /**
      * Iterate every (collection → refs) pair that has at least one
@@ -285,6 +322,16 @@ interface JoinableSource {
      * (#291). Plain `_dict_*`-backed sources omit it.
      */
     readonly displayLocale?: string;
+    /**
+     * i18nText descriptors of the right-side collection (#285 §3, `join`
+     * layer). When present and the query carries a locale, each joined
+     * right-side record's i18n fields resolve to that locale at the `join`
+     * layer (`resolvePolicy(onMissing, 'join')`) BEFORE it is attached under
+     * the leg's alias — so a joined `i18nText` field is a resolved string, not
+     * a raw `{ locale }` map. Locale-less queries leave joined fields raw
+     * (consistent with a locale-less read).
+     */
+    readonly i18nFields?: Record<string, I18nTextDescriptor>;
     /**
      * Subscribe to mutations on this source. The callback fires
      * AFTER the underlying record set has been updated. Returns an
@@ -307,6 +354,13 @@ interface JoinableSource {
 interface JoinContext {
     /** Name of the left-side (owning) collection. */
     readonly leftCollection: string;
+    /**
+     * The owning collection's default locale (#285 §3). Used to resolve joined
+     * i18n fields at the `join` layer when a terminal call doesn't pass an
+     * explicit locale — so `openVault({ locale })` flows to joins like it does
+     * to `get`/`list`. A per-call `toArray({ locale })` overrides it.
+     */
+    readonly defaultLocale?: string;
     /** Look up a `RefDescriptor` by field name on the left collection. */
     resolveRef(field: string): RefDescriptor | null;
     /** Resolve a right-side source by target collection name. */
@@ -348,7 +402,7 @@ interface JoinContext {
  * query like `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`,
  * which should throw on the second leg if the left set exceeds 50.
  */
-declare function applyJoins(rows: readonly unknown[], joins: readonly JoinLeg[], context: JoinContext): unknown[];
+declare function applyJoins(rows: readonly unknown[], joins: readonly JoinLeg[], context: JoinContext, locale?: string): unknown[];
 /**
  * Test-only: reset the join warning deduplication state between
  * tests. Production code never calls this — the dedup state is
@@ -479,6 +533,13 @@ declare function buildLiveQuery<T>(recompute: () => T[], upstreams: readonly Liv
 interface OrderBy {
     readonly field: string;
     readonly direction: 'asc' | 'desc';
+    /**
+     * Sort key for a `dictKey`/`staticDict` field (#285): `'value'` (default)
+     * sorts by the stored code; `'label'` sorts by the code's resolved label at
+     * the query locale (`toArray({ locale })`, or a `staticDict` `displayLocale`).
+     * Falls back to the code when no label resolves.
+     */
+    readonly by?: 'value' | 'label';
 }
 /**
  * A complete query plan: zero-or-more clauses, optional ordering, pagination,
@@ -617,8 +678,14 @@ declare class Query<T> {
     and(builder: (q: Query<T>) => Query<T>): Query<T>;
     /** Escape hatch: add an arbitrary predicate function. Not serializable. */
     filter(fn: (record: T) => boolean): Query<T>;
-    /** Sort by a field. Subsequent calls are tie-breakers. */
-    orderBy(field: string, direction?: 'asc' | 'desc'): Query<T>;
+    /**
+     * 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: string, direction?: 'asc' | 'desc', opts?: {
+        by?: 'value' | 'label';
+    }): Query<T>;
     /** Cap the result size. */
     limit(n: number): Query<T>;
     /** Skip the first N matching records (after ordering). */
@@ -721,8 +788,15 @@ declare class Query<T> {
      * 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(): T[];
+    toArray(opts?: {
+        locale?: string;
+    }): T[];
     /**
      * Decode this source's money fields on read (stored scaled-int → canonical
      * decimal), so `query().toArray()` agrees with `get()`/`sum()` on the value.
@@ -736,8 +810,10 @@ declare class Query<T> {
      * money read through `get()`/`list()` with a locale.
      */
     private decodeMoney;
-    /** Return the first matching record, or null. Joins are applied. */
-    first(): T | null;
+    /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields (#285 §3). */
+    first(opts?: {
+        locale?: string;
+    }): T | null;
     /**
      * Return the number of matching records (after where/filter,
      * before limit). **Joins are NOT applied** — count() reports the
@@ -1229,4 +1305,4 @@ declare class ScanBuilder<T> implements AsyncIterable<T> {
     private recordMatches;
 }
 
-export { DEFAULT_CROSS_JOIN_MAX_ROWS as D, type JoinContext as J, type LiveQuery as L, type OrderBy as O, Query as Q, type RefDescriptor as R, ScanBuilder as S, DEFAULT_JOIN_MAX_ROWS as a, type JoinLeg as b, type JoinStrategy as c, type JoinableSource as d, type LiveUpstream as e, type QueryPlan as f, type QuerySource as g, RefIntegrityError as h, type RefMode as i, RefRegistry as j, RefScopeError as k, type RefViolation as l, type ScanPageProvider as m, applyJoins as n, buildLiveQuery as o, executePlan as p, resetJoinWarnings as q, ref as r };
+export { DEFAULT_CROSS_JOIN_MAX_ROWS as D, type JoinContext as J, type LiveQuery as L, type OrderBy as O, Query as Q, type RefDescriptor as R, ScanBuilder as S, DEFAULT_JOIN_MAX_ROWS as a, type JoinLeg as b, type JoinStrategy as c, type JoinableSource as d, type LiveUpstream as e, type QueryPlan as f, type QuerySource as g, RefIntegrityError as h, type RefMode as i, RefRegistry as j, RefScopeError as k, type RefViolation as l, type ScanPageProvider as m, applyJoins as n, buildLiveQuery as o, executePlan as p, isRefArray as q, ref as r, refArray as s, resetJoinWarnings as t };

package/dist/{index-C-SSRIxP.d.cts → index-BMmajblo.d.cts}

@@ -333,6 +333,20 @@ interface ForgetResult {
     readonly blobsRetainedShared: number;
     /** Collections with blobs that could NOT be crypto-shredded — legacy (no `_cek`) or blobs disabled (see type docs). */
     readonly blobResidueCollections: readonly string[];
+    /**
+     * Count of persisted `_idx/<field>/<recordId>` index side-cars hard-deleted
+     * across the shredded records (#401). These live under the retained
+     * collection DEK, so crypto-shred alone would leave the indexed field VALUES
+     * readable — `forget()` must delete them.
+     */
+    readonly indexPostingsPurged: number;
+    /**
+     * `collection:id:field` entries whose persisted `_idx` side-car could NOT be
+     * deleted (#401) — index residue that still leaks the indexed value under the
+     * retained collection DEK. Non-empty means erasure is INCOMPLETE: retry, or
+     * purge the side-car out of band.
+     */
+    readonly indexResidue: readonly string[];
     /** The single `op:'forget'` ledger entry appended for this erasure. */
     readonly ledgerEntry: LedgerEntry;
 }

package/dist/{index-C-SSRIxP.d.ts → index-BMmajblo.d.ts}

@@ -333,6 +333,20 @@ interface ForgetResult {
     readonly blobsRetainedShared: number;
     /** Collections with blobs that could NOT be crypto-shredded — legacy (no `_cek`) or blobs disabled (see type docs). */
     readonly blobResidueCollections: readonly string[];
+    /**
+     * Count of persisted `_idx/<field>/<recordId>` index side-cars hard-deleted
+     * across the shredded records (#401). These live under the retained
+     * collection DEK, so crypto-shred alone would leave the indexed field VALUES
+     * readable — `forget()` must delete them.
+     */
+    readonly indexPostingsPurged: number;
+    /**
+     * `collection:id:field` entries whose persisted `_idx` side-car could NOT be
+     * deleted (#401) — index residue that still leaks the indexed value under the
+     * retained collection DEK. Non-empty means erasure is INCOMPLETE: retry, or
+     * purge the side-car out of band.
+     */
+    readonly indexResidue: readonly string[];
     /** The single `op:'forget'` ledger entry appended for this erasure. */
     readonly ledgerEntry: LedgerEntry;
 }

package/dist/{index-DpU6KWof.d.ts → index-BelbyUwz.d.ts}

@@ -1,6 +1,6 @@
 import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-BmhBSPCH.js';
-import { N as NoydbError } from './errors-Dz64FA65.js';
-import { v as MoneyDescriptor, A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery, h as GroupedQueryN } from './strategy-4M9jo172.js';
+import { N as NoydbError } from './errors-DL-zTrrF.js';
+import { a as I18nTextDescriptor, N as MoneyDescriptor, A as AggregateStrategy, j as AggregateSpec, k as Aggregation, h as AggregateResult, o as GroupedQuery, p as GroupedQueryN } from './strategy-BDxQnnTX.js';
 
 /**
  * Foreign-key references — the soft-FK mechanism.
@@ -59,7 +59,19 @@ type RefMode = 'strict' | 'warn' | 'cascade';
 interface RefDescriptor {
     readonly target: string;
     readonly mode: RefMode;
+    /**
+     * Present and `true` only for an array ref (#377-A, `refArray()`): the
+     * field holds an ARRAY of ids, each validated against `target`
+     * independently (M:N). Absent for a scalar `ref()`. The same `mode`
+     * semantics apply per element — strict rejects on a missing element at
+     * put + blocks delete of a referenced target; cascade deletes every
+     * record whose array contains the deleted id; warn surfaces orphans
+     * only via `checkIntegrity()`.
+     */
+    readonly isArray?: true;
 }
+/** Runtime predicate: is this an array ref (`refArray()`) vs a scalar `ref()`? */
+declare function isRefArray(desc: RefDescriptor): boolean;
 /**
  * Thrown when a strict reference is violated — either `put()` with a
  * missing target id, or `delete()` of a target that still has
@@ -102,6 +114,30 @@ declare class RefScopeError extends NoydbError {
  * fails at collection construction time, not at the first put.
  */
 declare function ref(target: string, mode?: RefMode): RefDescriptor;
+/**
+ * Array reference (#377-A) — the many-to-many soft-FK. The field holds an
+ * array of ids; each element is validated against `target` independently.
+ *
+ * ```ts
+ * const orders = company.collection<Order>('orders', {
+ *   refs: { productIds: refArray('products', 'warn') },
+ * })
+ * ```
+ *
+ * Same three `mode` semantics as `ref()`, applied per element:
+ *   - **strict** — `put()` rejects if ANY element's target is missing;
+ *     `delete()` of a target is blocked while any record's array still
+ *     contains its id.
+ *   - **warn** — both succeed; orphaned elements surface via
+ *     `vault.checkIntegrity()` (one violation per dangling element).
+ *   - **cascade** — `delete()` of a target deletes every record whose
+ *     array contains its id (cycle-safe, like scalar cascade).
+ *
+ * A `null`/`undefined` field is allowed (no links). Non-array values, or
+ * non-string/number elements, are an integrity error. Cross-vault targets
+ * are rejected exactly as in `ref()`.
+ */
+declare function refArray(target: string, mode?: RefMode): RefDescriptor;
 /**
  * Per-vault registry of reference declarations.
  *
@@ -144,6 +180,7 @@ declare class RefRegistry {
         collection: string;
         field: string;
         mode: RefMode;
+        isArray?: true;
     }>;
     /**
      * Iterate every (collection → refs) pair that has at least one
@@ -285,6 +322,16 @@ interface JoinableSource {
      * (#291). Plain `_dict_*`-backed sources omit it.
      */
     readonly displayLocale?: string;
+    /**
+     * i18nText descriptors of the right-side collection (#285 §3, `join`
+     * layer). When present and the query carries a locale, each joined
+     * right-side record's i18n fields resolve to that locale at the `join`
+     * layer (`resolvePolicy(onMissing, 'join')`) BEFORE it is attached under
+     * the leg's alias — so a joined `i18nText` field is a resolved string, not
+     * a raw `{ locale }` map. Locale-less queries leave joined fields raw
+     * (consistent with a locale-less read).
+     */
+    readonly i18nFields?: Record<string, I18nTextDescriptor>;
     /**
      * Subscribe to mutations on this source. The callback fires
      * AFTER the underlying record set has been updated. Returns an
@@ -307,6 +354,13 @@ interface JoinableSource {
 interface JoinContext {
     /** Name of the left-side (owning) collection. */
     readonly leftCollection: string;
+    /**
+     * The owning collection's default locale (#285 §3). Used to resolve joined
+     * i18n fields at the `join` layer when a terminal call doesn't pass an
+     * explicit locale — so `openVault({ locale })` flows to joins like it does
+     * to `get`/`list`. A per-call `toArray({ locale })` overrides it.
+     */
+    readonly defaultLocale?: string;
     /** Look up a `RefDescriptor` by field name on the left collection. */
     resolveRef(field: string): RefDescriptor | null;
     /** Resolve a right-side source by target collection name. */
@@ -348,7 +402,7 @@ interface JoinContext {
  * query like `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`,
  * which should throw on the second leg if the left set exceeds 50.
  */
-declare function applyJoins(rows: readonly unknown[], joins: readonly JoinLeg[], context: JoinContext): unknown[];
+declare function applyJoins(rows: readonly unknown[], joins: readonly JoinLeg[], context: JoinContext, locale?: string): unknown[];
 /**
  * Test-only: reset the join warning deduplication state between
  * tests. Production code never calls this — the dedup state is
@@ -479,6 +533,13 @@ declare function buildLiveQuery<T>(recompute: () => T[], upstreams: readonly Liv
 interface OrderBy {
     readonly field: string;
     readonly direction: 'asc' | 'desc';
+    /**
+     * Sort key for a `dictKey`/`staticDict` field (#285): `'value'` (default)
+     * sorts by the stored code; `'label'` sorts by the code's resolved label at
+     * the query locale (`toArray({ locale })`, or a `staticDict` `displayLocale`).
+     * Falls back to the code when no label resolves.
+     */
+    readonly by?: 'value' | 'label';
 }
 /**
  * A complete query plan: zero-or-more clauses, optional ordering, pagination,
@@ -617,8 +678,14 @@ declare class Query<T> {
     and(builder: (q: Query<T>) => Query<T>): Query<T>;
     /** Escape hatch: add an arbitrary predicate function. Not serializable. */
     filter(fn: (record: T) => boolean): Query<T>;
-    /** Sort by a field. Subsequent calls are tie-breakers. */
-    orderBy(field: string, direction?: 'asc' | 'desc'): Query<T>;
+    /**
+     * 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: string, direction?: 'asc' | 'desc', opts?: {
+        by?: 'value' | 'label';
+    }): Query<T>;
     /** Cap the result size. */
     limit(n: number): Query<T>;
     /** Skip the first N matching records (after ordering). */
@@ -721,8 +788,15 @@ declare class Query<T> {
      * 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(): T[];
+    toArray(opts?: {
+        locale?: string;
+    }): T[];
     /**
      * Decode this source's money fields on read (stored scaled-int → canonical
      * decimal), so `query().toArray()` agrees with `get()`/`sum()` on the value.
@@ -736,8 +810,10 @@ declare class Query<T> {
      * money read through `get()`/`list()` with a locale.
      */
     private decodeMoney;
-    /** Return the first matching record, or null. Joins are applied. */
-    first(): T | null;
+    /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields (#285 §3). */
+    first(opts?: {
+        locale?: string;
+    }): T | null;
     /**
      * Return the number of matching records (after where/filter,
      * before limit). **Joins are NOT applied** — count() reports the
@@ -1229,4 +1305,4 @@ declare class ScanBuilder<T> implements AsyncIterable<T> {
     private recordMatches;
 }
 
-export { DEFAULT_CROSS_JOIN_MAX_ROWS as D, type JoinContext as J, type LiveQuery as L, type OrderBy as O, Query as Q, type RefDescriptor as R, ScanBuilder as S, DEFAULT_JOIN_MAX_ROWS as a, type JoinLeg as b, type JoinStrategy as c, type JoinableSource as d, type LiveUpstream as e, type QueryPlan as f, type QuerySource as g, RefIntegrityError as h, type RefMode as i, RefRegistry as j, RefScopeError as k, type RefViolation as l, type ScanPageProvider as m, applyJoins as n, buildLiveQuery as o, executePlan as p, resetJoinWarnings as q, ref as r };
+export { DEFAULT_CROSS_JOIN_MAX_ROWS as D, type JoinContext as J, type LiveQuery as L, type OrderBy as O, Query as Q, type RefDescriptor as R, ScanBuilder as S, DEFAULT_JOIN_MAX_ROWS as a, type JoinLeg as b, type JoinStrategy as c, type JoinableSource as d, type LiveUpstream as e, type QueryPlan as f, type QuerySource as g, RefIntegrityError as h, type RefMode as i, RefRegistry as j, RefScopeError as k, type RefViolation as l, type ScanPageProvider as m, applyJoins as n, buildLiveQuery as o, executePlan as p, isRefArray as q, ref as r, refArray as s, resetJoinWarnings as t };