@noy-db/hub 0.3.0-pre.10 → 0.3.0-pre.12

package/dist/via/i18n/core.d.ts

@@ -0,0 +1,267 @@
+/**
+ * i18nText schema type —
+ *
+ * `i18nText({ languages, required })` creates a descriptor for a
+ * multi-language content field whose value is stored as a
+ * `{ [locale]: string }` map (e.g. `{ en: 'Consulting', th: 'ที่ปรึกษา' }`).
+ *
+ * On put, the descriptor validates that required languages are present.
+ * On read (when a `locale` option is passed), the map is collapsed to the
+ * caller's locale string via the fallback chain.
+ *
+ * Design decisions
+ * ────────────────
+ *
+ * **Descriptor pattern (not a Zod type).**
+ * `i18nText()` returns a plain descriptor object used in the collection's
+ * `i18nFields` option — same pattern as `ref()` / `dictKey()`. This keeps
+ * `@noy-db/core` at zero runtime dependencies and avoids Zod v3 field-type
+ * constraints. TypeScript inference is handled via the descriptor's type.
+ *
+ * **Enforcement at the collection boundary.**
+ * The `required` option is checked by `Collection.put()` via the compartment's
+ * registered `i18nFields`. Failed validation throws `MissingTranslationError`
+ * — a distinct class from `SchemaValidationError` so callers can tell
+ * "wrong shape" from "missing translations".
+ *
+ * **Resolution is post-decryption.**
+ * Locale resolution happens AFTER `decryptRecord()`, as a pure in-memory
+ * transform. No additional crypto work is needed. The resolved record is
+ * returned in place of the stored one, with i18nText fields replaced by
+ * their locale-resolved strings.
+ *
+ * **`locale: 'raw'`.**
+ * Passing `{ locale: 'raw' }` skips resolution and returns the full
+ * `{ [locale]: string }` map — useful for bilingual exports, admin UIs,
+ * and any context where all translations must be visible at once.
+ *
+ * **Out of scope.**
+ * Pluralization, RTL rendering, date/number formatting, per-locale CRDT
+ * merging.
+ */
+import type { OnMissing, OnMissingPolicy, Layer } from './policy.js';
+/** Flatten an intersection into a single object literal for nicer hovers. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The stored shape of a multilingual field, inferred from its `required`
+ * mode — so the compiler forces you to handle an absent optional locale
+ * (`string | undefined`) instead of silently yielding `undefined`.
+ *
+ * Mirrors `i18nText({ languages, required })`:
+ * - `'all'` (default) — every locale required: `{ th: string; en: string }`
+ * - `'any'`           — every locale optional: `{ th?: string; en?: string }`
+ *   (the "at least one present" guarantee is runtime-only — not expressible
+ *   in TypeScript — so each key is optional)
+ * - `readonly L[]`    — listed locales required, the rest optional:
+ *   `I18nMap<'th'|'en', ['th']>` → `{ th: string; en?: string }`
+ *
+ * @example
+ * ```ts
+ * type Lang = 'th' | 'en'
+ * interface Contact {
+ *   name: I18nMap<Lang, 'any'>      // { th?: string; en?: string }
+ *   legalName: I18nMap<Lang, ['th']> // { th: string; en?: string }
+ *   slug: I18nMap<Lang>             // { th: string; en: string }
+ * }
+ * ```
+ *
+ * @public
+ */
+export type I18nMap<Langs extends string, Required extends 'all' | 'any' | readonly Langs[] = 'all'> = Required extends 'all' ? Record<Langs, string> : Required extends 'any' ? Partial<Record<Langs, string>> : Required extends readonly (infer R extends Langs)[] ? Prettify<Record<R, string> & Partial<Record<Exclude<Langs, R>, string>>> : never;
+/**
+ * Options for `i18nText()`.
+ *
+ * `languages` declares the full set of supported locales. `required`
+ * controls which must be present on every `put()`.
+ *
+ * `autoTranslate` is the per-field opt-in for the `plaintextTranslator`
+ * hook. When `true` and a `plaintextTranslator` is configured
+ * on `createNoydb()`, missing translations are generated before `put()`.
+ * Default: `false`.
+ */
+export interface I18nTextOptions {
+    /** All supported locale codes (BCP 47). */
+    readonly languages: readonly string[];
+    /**
+     * Which locales must be present on every `put()`.
+     *
+     * - `'all'`       — every declared language must be present.
+     * - `'any'`       — at least one declared language must be present.
+     * - `string[]`    — listed locales are required; others are optional.
+     */
+    readonly required: 'all' | 'any' | readonly string[];
+    /**
+     * Per-field opt-in for the `plaintextTranslator` hook.
+     * When `true`, missing required translations are auto-generated
+     * before `put()` if a translator is configured. Default: `false`.
+     */
+    readonly autoTranslate?: boolean;
+    /**
+     * What to do when this field is resolved to a locale that is absent.
+     * A single policy, or a per-layer map (read/guard/join/mv/derivation/
+     * export). Default `'throw'` — today's behavior, zero breaking change.
+     * See {@link OnMissingPolicy}.
+     *
+     * NOTE (current wiring): ALL layers are enforced — `read` (`get`/`list`),
+     * `guard`, `derivation`, `mv`, `join`, `export`. Guard / derivation
+     * `ctx.vault` reads resolve under their own layer policy (`guard` defaults to
+     * the lenient `'substitute'`). The `mv` layer fires for materialized views
+     * that declare `{ i18nLocale, i18nFields }` — UNION (group-key i18n fields
+     * resolve before the unified-row bucketing) and query-form (resolved in
+     * `GroupedAggregation.run` before `groupAndReduce`); grouping a raw i18n field
+     * without a locale throws. The `join` layer resolves a joined right-side i18n
+     * field to the query locale (`toArray({ locale })` or the vault default; raw
+     * when locale-less). The `export` layer fires for
+     * `exportStream`/`exportJSON({ resolveLabels })` — records collapse to the
+     * export locale.
+     */
+    readonly onMissing?: OnMissingPolicy;
+    /**
+     * Ordered preferred-substitute locales used when `onMissing` resolves
+     * to `'substitute'` and the target locale is absent. `'any'` as an
+     * element means "first non-empty value". A caller-supplied `fallback`
+     * at read time takes precedence over this declared list.
+     */
+    readonly substitute?: readonly string[];
+    /**
+     * Smart-substitute. When `true`, a missing-locale `substitute` walk that
+     * misses the explicit chain prefers the available locale whose script is
+     * nearest the target (same script, then Latin) rather than an arbitrary value
+     * — e.g. a missing Thai label prefers another Thai (or Latin) translation over
+     * an unreadable script. Default `false` (legacy first-non-empty behavior).
+     */
+    readonly smartSubstitute?: boolean;
+    /**
+     * Per-locale script enforcement (write-time). `'auto'` infers the
+     * allowed Unicode scripts per locale (asymmetric Latin tolerance); an
+     * object overrides per slot. Absent ⇒ no check. See `./script.ts`.
+     */
+    readonly script?: 'auto' | Partial<Record<string, readonly string[]>>;
+    /**
+     * What to do when a slot's value contains characters outside its
+     * allowed script set. Default `'reject'`.
+     */
+    readonly onScriptViolation?: 'reject' | 'filter' | 'warn';
+    /**
+     * Eager-fill empty locale slots from the substitute chain at
+     * write time, recording provenance in the internal `_i18nFilled` marker.
+     * Mutually exclusive with an EXPLICIT `'throw'` onMissing policy (densify
+     * fills every hole, so a throw would be unreachable). Without an explicit
+     * `substitute`, fills from `'any'` (first non-empty). Default absent.
+     */
+    readonly densifyOnWrite?: boolean;
+}
+/**
+ * Descriptor returned by `i18nText()`. Attach to the collection's
+ * `i18nFields` option:
+ *
+ * ```ts
+ * const lineItems = company.collection<LineItem>('line-items', {
+ *   i18nFields: {
+ *     description: i18nText({ languages: ['en', 'th'], required: 'all' }),
+ *   },
+ * })
+ * ```
+ */
+export interface I18nTextDescriptor {
+    readonly _noydbI18nText: true;
+    /** Via port brand marker — lets an `I18nTextDescriptor` satisfy the kernel's opaque `ViaDescriptor` (#623 Task 9). */
+    readonly _viaBrand: 'i18n';
+    readonly options: I18nTextOptions;
+}
+/**
+ * Create an `I18nTextDescriptor` for a multi-language content field.
+ *
+ * @param options  Language list + enforcement mode.
+ *
+ * @example
+ * ```ts
+ * i18nText({ languages: ['en', 'th'], required: 'all' })
+ * i18nText({ languages: ['en', 'th'], required: ['th'], autoTranslate: true })
+ * ```
+ */
+export declare function i18nText(options: I18nTextOptions): I18nTextDescriptor;
+export { isI18nTextDescriptor } from '../../port/with/i18n-strategy.js';
+/**
+ * Validate that a value is a valid `{ [locale]: string }` map and that
+ * all required locales are present. Throws `MissingTranslationError`
+ * when the required constraint is violated.
+ *
+ * Called by `Collection.put()` for each registered `i18nField`.
+ *
+ * @param value       The raw field value from the record being put.
+ * @param field       The field name (used in the thrown error message).
+ * @param descriptor  The `i18nText()` descriptor for this field.
+ */
+export declare function validateI18nTextValue(value: unknown, field: string, descriptor: I18nTextDescriptor): void;
+/**
+ * Resolve an i18nText value (`{ [locale]: string }` map) to a string
+ * for the given locale.
+ *
+ * @param value    The stored locale map.
+ * @param locale   The requested locale code, or `'raw'` to return the map.
+ * @param fallback Single locale or ordered list; use `'any'` as the last
+ *                 element to fall back to any available translation.
+ * @param field    Field name used in `LocaleNotSpecifiedError` messages.
+ * @returns The resolved string, OR the original map when `locale === 'raw'`.
+ */
+/** Options for the policy-aware form of {@link resolveI18nText}. */
+export interface ResolveI18nOptions {
+    /** Effective policy for the resolution layer. Default `'throw'`. */
+    readonly policy?: OnMissing;
+    /** Declared substitute chain; applied only under policy `'substitute'`. */
+    readonly substitute?: readonly string[];
+    /**
+     * Smart-substitute. When `true` and policy is `'substitute'`, after the
+     * explicit chain misses, pick the available locale whose script is nearest the
+     * target (same script first, then Latin's broad readability) instead of an
+     * arbitrary value. Default `false`.
+     */
+    readonly smartSubstitute?: boolean;
+}
+export declare function resolveI18nText(value: Record<string, string>, locale: string, fallback?: string | readonly string[], field?: string): string | Record<string, string>;
+export declare function resolveI18nText(value: Record<string, string>, locale: string, fallback: string | readonly string[] | undefined, field: string | undefined, opts: ResolveI18nOptions): string | Record<string, string> | null;
+export { getAtPath } from '../../kernel/paths.js';
+/**
+ * Apply locale resolution to a single record, returning a new copy.
+ *
+ * For each field registered as an `i18nText` descriptor:
+ * - If `locale === 'raw'`, the field value is left as the stored map.
+ * - Otherwise, the field value is replaced with the resolved string.
+ *
+ * Field paths support dot notation (`'address.lineOne'`) and array
+ * wildcards (`'contacts[].title'`). Top-level fields work as before.
+ *
+ * @param record      The decrypted record.
+ * @param i18nFields  Map of field path → `I18nTextDescriptor`.
+ * @param locale      The requested locale (or `'raw'`).
+ * @param fallback    Fallback chain (optional).
+ * @param layer       Resolution layer (default `'read'`). Each field's
+ *                    `onMissing` policy is resolved for this layer, so the
+ *                    same record resolves leniently on a get but strictly
+ *                    inside an mv/derivation.
+ */
+export declare function applyI18nLocale(record: Record<string, unknown>, i18nFields: Record<string, I18nTextDescriptor>, locale: string, fallback?: string | readonly string[], layer?: Layer): Record<string, unknown>;
+/**
+ * Sync i18n-text-only present-for-join dressing — the exact `join`-layer
+ * partial application `kernel/query/join.ts` used to import and call
+ * directly before #626's retirement (#650 Task 6): fixes `fallback`
+ * `undefined` and `layer` `'join'`. `via/lookup/snapshot.ts`'s
+ * `buildPresentForJoin` composes this with the lookup-label half to build
+ * the `JoinableSource.presentForJoin` hook the join executor now calls
+ * instead of reaching into this module.
+ */
+export declare function presentI18nForJoin(record: Record<string, unknown>, i18nFields: Record<string, I18nTextDescriptor>, locale: string): Record<string, unknown>;
+/**
+ * Remove the internal densify provenance marker (`_i18nFilled`) from a
+ * read-facing record. NON-mutating: returns the same object when the
+ * marker is absent, otherwise a shallow copy without the marker.
+ *
+ * MUST be applied on every user-facing read return — even locale-less ones,
+ * which bypass {@link applyI18nLocale}. MUST NOT be applied on the internal
+ * prior-read path (decryptRecord / resolveDensifyPrior), where densify needs
+ * the marker.
+ */
+export declare function stripI18nFilled<T extends Record<string, unknown>>(record: T): T;

package/dist/via/i18n/densify.d.ts

@@ -0,0 +1,24 @@
+import type { I18nTextDescriptor } from './core.js';
+/**
+ * Per field, the locales that are UNCHANGED round-tripped densify fills — i.e.
+ * marked filled on the prior record AND identical in the incoming record.
+ * These are exempt from write-time script enforcement (they are derived copies,
+ * not authored text). Slots the user changed are NOT exempt (validated as authored).
+ */
+export declare function computeExemptFills(prior: Record<string, unknown> | undefined, incoming: Record<string, unknown>, fields: Record<string, I18nTextDescriptor>): Map<string, Set<string>>;
+/**
+ * Mutate `record` in place: fill empty declared-language slots for each
+ * densify-enabled field from the field's substitute chain, recompute unchanged
+ * prior fills, clear marks for slots that became authored, and write the
+ * resulting `_i18nFilled` marker (removed when empty).
+ *
+ * `prior` is read-only — it is never mutated.
+ *
+ * Provenance uses value-equality (decision A): a slot counts as an unchanged
+ * fill when it was prior-marked AND its value still equals the prior value. A
+ * consequence is that re-authoring a value byte-identical to the existing fill
+ * keeps it classified as a fill (the visible value is unchanged either way; the
+ * slot stays script-exempt and will auto-refresh if its source later changes).
+ * This is inherent to value-equality provenance, not a bug.
+ */
+export declare function densify(record: Record<string, unknown>, prior: Record<string, unknown> | undefined, fields: Record<string, I18nTextDescriptor>): void;

package/dist/via/i18n/dictionary.d.ts

@@ -0,0 +1,200 @@
+/**
+ * _dict_* reserved collections + dictKey schema descriptor —
+ *
+ * Stores bounded enum-like field dictionaries as reserved encrypted
+ * collections (`_dict_<name>/`) within a vault. Each dictionary
+ * entry maps a stable key (e.g. `'paid'`) to a locale → label record
+ * (e.g. `{ en: 'Paid', th: 'ชำระแล้ว' }`).
+ *
+ * Design decisions
+ * ────────────────
+ *
+ * **Why reserved collections, not a separate store?**
+ * Same answer as `_sync_credentials`: the compartment's existing
+ * encryption stack is exactly right. Dictionaries are encrypted under the
+ * same vault DEK, inherit ACL, ledger, and backup/restore for free.
+ *
+ * **One collection per dictionary, not one collection with namespaces.**
+ * Each `_dict_<name>/` collection holds entries `{ id: key, labels: {...} }`.
+ * This composes with `ref()` naturally (a dictKey IS a ref to the dict
+ * collection), and means the query DSL works over dictionary entries
+ * without any special-casing.
+ *
+ * **dictKey() is a descriptor, not a Zod type.**
+ * The descriptor pattern matches `ref()`: declare NOYDB-specific metadata
+ * in the collection options alongside `refs`. TypeScript inference comes
+ * from the descriptor's generic parameter, not from Zod internals.
+ *
+ * API:
+ *   `dictKey(name, keys?)` — returns a DictKeyDescriptor
+ *   `vault.dictionary(name)` — returns a DictionaryHandle
+ *   `DictionaryHandle.put/putAll/get/delete/rename/list` — CRUD
+ *
+ * The storage engine (`DictionaryHandle`, `DictEntry`, `DictionaryOptions`,
+ * `DICT_COLLECTION_PREFIX`, `dictCollectionName`) moved to
+ * `via/lookup/handle.ts` (#650 Task 1 — via-lookup extraction, phase
+ * D of the Via port) and is renamed `LookupHandle` there; re-exported here
+ * under the original names for one release so existing importers of this
+ * module compile unchanged. This file keeps only the descriptor factories
+ * (`dictKey`/`staticDict`), which are locale/i18n-coupled and stay put.
+ */
+import type { OnMissingPolicy } from './policy.js';
+export { isDictCollectionName } from '../../port/with/i18n-strategy.js';
+export { DictionaryHandle, DICT_COLLECTION_PREFIX, dictCollectionName, type DictEntry, type DictionaryOptions, } from '../lookup/handle.js';
+/**
+ * Descriptor returned by `dictKey()`. Attach to the collection's
+ * `dictKeyFields` option to declare which fields are dictionary-backed:
+ *
+ * ```ts
+ * const invoices = company.collection<Invoice>('invoices', {
+ *   dictKeyFields: {
+ *     status: dictKey('status', ['draft', 'open', 'paid'] as const),
+ *   },
+ * })
+ * ```
+ *
+ * The generic parameter `Keys` narrows the TypeScript type of the field
+ * to a literal union; the runtime value of `keys` is used by `put()`
+ * validation to reject unknown keys when a key set is declared.
+ */
+export interface DictKeyDescriptor<Keys extends string = string> {
+    readonly _noydbDictKey: true;
+    /** Via port brand marker (#623 Task 9) — dictKey shares the i18n binding brand. */
+    readonly _viaBrand: 'i18n';
+    /** Which dictionary this field references. */
+    readonly name: string;
+    /** Declared valid keys. When set, `put()` rejects keys not in this set. */
+    readonly keys: readonly Keys[] | undefined;
+    /**
+     * What to do when a label is missing for the resolved locale. Mirrors
+     * `i18nText`'s `onMissing`. Default behavior (when unset) preserves the
+     * legacy contract: a missing label is omitted (scalar) or `null`
+     * (array element) — i.e. `'null'`. Set `'substitute'` to walk the
+     * declared `substitute` chain, or `'throw'` to raise.
+     */
+    readonly onMissing?: OnMissingPolicy;
+    /** Ordered preferred-substitute locales for label resolution. */
+    readonly substitute?: readonly string[];
+    /**
+     * Optional inline display labels (value → label map). A SYNC display
+     * fallback for `describe()` when async `dictLabels` (from `_dict_`) are
+     * not resolved. The async path still wins when available.
+     */
+    readonly labels?: Record<string, string>;
+}
+/**
+ * Create a `DictKeyDescriptor` for a dictionary-backed enum field.
+ *
+ * @param name        The dictionary name (corresponds to `_dict_<name>` collection).
+ * @param keysOrMap   Either:
+ *   - An `as const` array of valid key literals — narrows the TypeScript type
+ *     to a literal union and enables put-time validation.
+ *   - A **value→label map** (`{ draft: 'Draft', paid: 'Paid' }`) — keys are
+ *     inferred from the map, and the labels are stored as inline display
+ *     defaults surfaced by `describe()` without a store read.
+ * @param opts        `{ labels?, onMissing?, substitute? }` when the array form
+ *                    is used; `opts.labels` provides inline display defaults for
+ *                    specific keys (same semantics as the map form, but
+ *                    explicit key order from the array is preserved).
+ *
+ * @example
+ * ```ts
+ * // array form (original):
+ * dictKey('status', ['draft', 'open', 'paid'] as const)
+ *
+ * // value→label map form (keys inferred, inline labels for describe()):
+ * dictKey('status', { draft: 'Draft', open: 'Open', paid: 'Paid' })
+ *
+ * // array + opts.labels (preserves explicit order, partial labels OK):
+ * dictKey('status', ['draft', 'open', 'paid'] as const, { labels: { paid: 'Paid' } })
+ * ```
+ */
+export declare function dictKey<Keys extends string>(name: string, keysOrMap?: readonly Keys[] | Record<Keys, string>, opts?: {
+    onMissing?: OnMissingPolicy;
+    substitute?: readonly string[];
+    labels?: Record<string, string>;
+}): DictKeyDescriptor<Keys>;
+export { isDictKeyDescriptor } from '../../port/with/i18n-strategy.js';
+/**
+ * Descriptor returned by `staticDict()`. A sibling to {@link DictKeyDescriptor}
+ * for **closed, defined-in-code, identical-across-vaults** enums (honorific,
+ * civil-status, gender, religion, ContactTitle, status…).
+ *
+ * Unlike `dictKey`, the labels are supplied **at registration in code** and
+ * resolved through the *same* label machinery, but with **no `_dict_*`
+ * per-vault encrypted copy** and **no `rename()`**. The record stores only
+ * the **code**; a static dict has no mutation surface.
+ *
+ * **Hybrid resolution.** Because a static dict is pure code with no
+ * vault-locale dependency, it can — via a configured `displayLocale` — emit a
+ * `<field>Label` even under a **locale-less read** (the property a locale-less
+ * consumer needs and `dictKey` cannot provide). When a locale *is* active it
+ * behaves exactly like `dictKey` (honoring `onMissing`/`substitute`).
+ *
+ * ```ts
+ * const workers = vault.collection<Worker>('workers', {
+ *   dictKeyFields: {
+ *     civilStatus: staticDict('civilStatus', {
+ *       adultMale:   { th: 'นาย',    en: 'Mr'  },
+ *       adultFemale: { th: 'นาง',    en: 'Mrs' },
+ *     }, { displayLocale: 'th' }),
+ *   },
+ * })
+ * ```
+ */
+export interface StaticDictDescriptor<Keys extends string = string> {
+    readonly _noydbStaticDict: true;
+    /** Via port brand marker (#623 Task 9) — staticDict shares the i18n binding brand. */
+    readonly _viaBrand: 'i18n';
+    /** Which dictionary this field references (the registry name). */
+    readonly name: string;
+    /** The in-code label table: key → { locale → label }. */
+    readonly table: Readonly<Record<Keys, Readonly<Record<string, string>>>>;
+    /** Declared valid keys — derived from `Object.keys(table)`. */
+    readonly keys: readonly Keys[];
+    /**
+     * Locale used to emit `<field>Label` under a **locale-less** read — the
+     * hybrid hinge. When unset, a static dict behaves like `dictKey` under a
+     * locale-less read (no label); a locale-less consumer almost always wants
+     * it set.
+     */
+    readonly displayLocale?: string;
+    /** Same `onMissing` policy engine as `dictKey`. Default `'null'`. */
+    readonly onMissing?: OnMissingPolicy;
+    /** Ordered preferred-substitute locales for label resolution. */
+    readonly substitute?: readonly string[];
+    /**
+     * Validate the stored code against `keys` on every `put()`. Default `true`
+     * — codes are closed by construction, so an unknown code is a bug. Set
+     * `false` to allow open codes (skips the `UnknownDictCodeError` guard).
+     */
+    readonly validateCodes?: boolean;
+}
+/**
+ * Create a `StaticDictDescriptor` for a code-provided enum field — a sibling
+ * to {@link dictKey} for closed, code-defined, identical-across-vaults enums.
+ *
+ * The labels live in `table` (no `_dict_*` collection, no `rename()`); the
+ * record stores only the stable code. Pass `displayLocale` so `<field>Label`
+ * resolves even under a locale-less read.
+ *
+ * @param name   The dictionary name (used for the readonly-guard registry and
+ *               the query label seam — never creates a `_dict_<name>` key).
+ * @param table  `{ key: { locale: label } }` map.
+ * @param opts   `displayLocale` (locale-less label), `onMissing`, `substitute`.
+ *
+ * @example
+ * ```ts
+ * staticDict('civilStatus', {
+ *   adultMale:   { th: 'นาย',    en: 'Mr'  },
+ *   adultFemale: { th: 'นาง',    en: 'Mrs' },
+ * }, { displayLocale: 'th' })
+ * ```
+ */
+export declare function staticDict<const T extends Record<string, Record<string, string>>>(name: string, table: T, opts?: {
+    displayLocale?: string;
+    onMissing?: OnMissingPolicy;
+    substitute?: readonly string[];
+    validateCodes?: boolean;
+}): StaticDictDescriptor<Extract<keyof T, string>>;
+export { isStaticDictDescriptor } from '../../port/with/i18n-strategy.js';

package/dist/via/i18n/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@noy-db/hub/i18n` — subpath export for the multi-locale primitives.
+ *
+ * Apps that only speak English never have to import from this subpath
+ * — the main `@noy-db/hub` entry still re-exports these symbols for
+ * backward compatibility through.x. Consumers that opt into the
+ * subpath import get a smaller bundle (~2 KB estimated savings).
+ *
+ * Re-exports:
+ *   - `dictKey`, `DictionaryHandle`, dictionary collection helpers
+ *   - `i18nText`, `resolveI18nText`, `applyI18nLocale`, validators
+ */
+export * from './core.js';
+export * from './dictionary.js';
+export { resolvePolicy } from './policy.js';
+export type { OnMissing, Layer, OnMissingPolicy } from './policy.js';
+export { inferScripts, enforceScript } from './script.js';
+export type { ScriptWarning } from './script.js';
+export { withI18n } from './active.js';
+export type { I18nStrategy } from './strategy.js';
+export { ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, ScriptViolationError, StaticDictReadonlyError, UnknownDictCodeError, } from '../../kernel/errors.js';

package/dist/via/i18n/policy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-layer i18n resolution policy.
+ *
+ * `onMissing` governs what happens when a multilingual field is resolved
+ * to a target locale that is absent. It may be a single scalar policy or
+ * a per-layer map, so a field can be lenient at the app read boundary but
+ * strict inside a materialized view.
+ *
+ * Effective policy for layer `λ`:
+ *
+ * ```
+ * explicit(λ) = typeof onMissing === 'object' ? onMissing[λ] : undefined
+ * scalar      = typeof onMissing === 'string' ? onMissing : undefined
+ * policy(λ)   = explicit(λ) ?? layerDefault(λ) ?? scalar ?? 'throw'
+ * ```
+ *
+ * - `layerDefault('guard') = 'substitute'` — guards are lenient unless
+ *   EXPLICITLY overridden; they never inherit a scalar policy (a guard
+ *   reading a display value must not hard-fail on a missing locale).
+ * - every other layer has no default, so it inherits the scalar, else
+ *   falls back to `'throw'` (today's behavior — zero breaking change).
+ *
+ * @public
+ */
+export type OnMissing = 'substitute' | 'null' | 'throw';
+/**
+ * The contexts in which a multilingual field is resolved. Each can carry
+ * its own `onMissing` policy.
+ *
+ * - `read`       — ordinary app reads (`get`/`list`/query projection).
+ * - `guard`      — a guard callback reading a value.
+ * - `join`       — a joined record expanded onto a row.
+ * - `mv`         — materialized-view input.
+ * - `derivation` — derivation input.
+ * - `export`     — bundle/public-envelope export.
+ */
+export type Layer = 'read' | 'guard' | 'join' | 'mv' | 'derivation' | 'export';
+/** Field-level policy: a single scalar, or a per-layer map. */
+export type OnMissingPolicy = OnMissing | Partial<Record<Layer, OnMissing>>;
+/**
+ * Resolve the effective `OnMissing` for a layer from a field's declared
+ * policy. See module docs for the resolution rule.
+ */
+export declare function resolvePolicy(onMissing: OnMissingPolicy | undefined, layer: Layer): OnMissing;

package/dist/via/i18n/script.d.ts

@@ -0,0 +1,26 @@
+import type { I18nTextDescriptor } from './core.js';
+/**
+ * Infer the allowed Unicode scripts for a BCP-47 locale, with asymmetric
+ * Latin tolerance. A script subtag (`th-Latn`) wins over the base
+ * language. Unknown locales default to `['Latin']`.
+ */
+export declare function inferScripts(locale: string): readonly string[];
+/** A non-fatal script violation recorded under `'filter'`/`'warn'` modes. */
+export interface ScriptWarning {
+    readonly field: string;
+    readonly locale: string;
+    readonly expected: readonly string[];
+    readonly sample: string;
+}
+/**
+ * Enforce a field's script constraint over an i18nText value map.
+ *
+ * - No `script` option ⇒ returns the value unchanged.
+ * - `onScriptViolation: 'reject'` (default) ⇒ throws {@link ScriptViolationError}.
+ * - `'filter'` ⇒ returns a copy with disallowed characters stripped + warnings.
+ * - `'warn'` ⇒ returns the value unchanged + warnings.
+ */
+export declare function enforceScript(value: Record<string, unknown>, field: string, descriptor: I18nTextDescriptor, exempt?: ReadonlySet<string>): {
+    value: Record<string, unknown>;
+    warnings: ScriptWarning[];
+};

package/dist/via/i18n/strategy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Strategy seam for the optional i18n (multi-locale + dictionary)
+ * service. `I18nStrategy` + `BuildDictionaryHandleOptions` + `NO_I18N`
+ * now live on the kernel port (`port/with/i18n-strategy.ts`, #623
+ * Task 7) — re-exported here for compat with existing importers of
+ * this module. Real `applyI18nLocale` / `validateI18nTextValue` /
+ * `DictionaryHandle` are only reachable via `withI18n()` in
+ * `./active.ts`.
+ *
+ * @internal
+ */
+export type { I18nStrategy, BuildDictionaryHandleOptions } from '../../port/with/i18n-strategy.js';
+export { NO_I18N } from '../../port/with/i18n-strategy.js';

package/dist/via/lookup/active.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Active lookup strategy — `withLookup()` returns the real implementation
+ * that constructs `LookupHandle` instances (the `_dict_*` / future
+ * `_lookup_*` reserved-collection engine).
+ *
+ * #650 Task 1 (via-lookup extraction, phase D): this is the new home for
+ * the handle-construction logic that used to live inline in
+ * `via/i18n/active.ts`'s `withI18n().buildDictionaryHandle`, which
+ * now delegates here (same handle, new home — see that file). Splitting
+ * the import chain through this file is the same `#553` tree-shake seam
+ * `via/i18n/active.ts` already used: the `LookupHandle` engine only
+ * ships in a consumer's bundle once something reaches `withLookup()` (today
+ * that's transitively via `withI18n()`; later phase-D tasks may call it
+ * directly).
+ *
+ * @public
+ */
+import type { LookupStrategy } from '../../port/with/lookup-strategy.js';
+export declare function withLookup(): LookupStrategy;