@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/via/classified/guards.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Refusal matrix R1-R5 (spec) — ONE guard, run at BOTH doors:
+ * `collection()` config resolution AND `_applyClassifiedFields` (the reconcile
+ * seam), because crdt/conflictPolicy/perRecordKeys are construction-only
+ * while classifiedFields can attach later (C5's lesson). @module
+ */
+import type { ClassifiedFieldSpec } from './descriptor.js';
+export interface ClassifiedGuardCtx {
+    readonly perRecordKeys: boolean;
+    readonly crdt: boolean;
+    readonly hasConflictPolicy: boolean;
+    /** False on plaintext (`encrypt: false`) collections — no vdig/seal path exists. */
+    readonly storeCiphertext: boolean;
+    readonly deterministicFields: ReadonlySet<string> | null;
+    readonly indexedFields: ReadonlySet<string>;
+    readonly textIndexFields: ReadonlySet<string>;
+    readonly vectorSourceFields: ReadonlySet<string>;
+    readonly subjectKeyField: string | undefined;
+    readonly bareSensitiveFields: ReadonlySet<string>;
+    /** Collection-level gate for the `equatable` knob (R8 double door). */
+    readonly acknowledgeEquatableRisk: boolean;
+}
+export declare function guardClassifiedCompat(collection: string, byField: Record<string, ClassifiedFieldSpec>, ctx: ClassifiedGuardCtx): void;

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

@@ -0,0 +1,11 @@
+/** Classified fields barrel — descriptors, presets, resolver, errors (stage 1). @module */
+export type { ClassifiedStorage, ClassifiedList, ClassifiedRider, ClassifiedFieldSpec, ClassifiedGroup, ClassifiedEntry, } from './descriptor.js';
+export { isClassifiedFieldSpec, isClassifiedGroup } from './descriptor.js';
+export { resolveClassifiedFields, type ResolvedClassified } from './resolve.js';
+export { classified } from './presets.js';
+export { luhnCheck } from './validators.js';
+export { enforceClassifiedWrite } from './write.js';
+export { ClassifiedConfigError, ClassifiedNeverStoredError, ClassifiedValidationError, ClassifiedRevealError, ClassifiedVerifyError, ClassifiedRotationError } from './errors.js';
+export { withClassified } from './active.js';
+export { NO_CLASSIFIED, type ClassifiedStrategy, type ClassifiedRevealCtx } from './strategy.js';
+export type { ClassifiedVerdict, ClassifiedVerifyCtx } from './strategy.js';

package/dist/via/classified/presets.d.ts

@@ -0,0 +1,65 @@
+/** The preset catalog (stage 1). Presets are hub-owned; devs get declarative
+ *  knobs, not read-side callbacks (design law D2/D3). @module */
+import type { ClassifiedFieldSpec, ClassifiedGroup } from './descriptor.js';
+export declare const classified: {
+    /** Composite card type. PAN sealed + last4/bin riders; CVC is storage:'never' (PCI-aware). */
+    creditCard(fields: {
+        pan: string;
+        expiry?: string;
+        cvc?: string;
+    }): ClassifiedGroup;
+    birthDate(): ClassifiedFieldSpec;
+    email(): ClassifiedFieldSpec;
+    phone(): ClassifiedFieldSpec;
+    /** Digest-only password: verify-without-reveal; never listed, never revealed.
+     *  Enumeration math is on the caller for low-entropy values — see the
+     *  per-preset docs; the hub ships no rate limiter in this slice (spec §5).
+     *
+     *  @param opts.equatable — emit a store-visible `_bidx` equality tag (enables
+     *  `findByDigest`). Cost band you are accepting:
+     *
+     *  equal values produce equal store-visible tags: anyone with store access
+     *  learns which records share this secret and how many share each value —
+     *  never the value itself. A collection-DEK holder can additionally test
+     *  candidate values offline: the tag's inner digest is PBKDF2-SHA256 (600K),
+     *  which is GPU/ASIC-friendly — an offline attacker runs on the order of
+     *  10⁴–10⁸ guesses/second, so for low-entropy secrets (PINs, casefolded secret
+     *  answers) offline recovery of the equality partition is seconds-to-hours, not
+     *  years. `crypto.subtle` exposes no memory-hard KDF (no scrypt/argon2) and the
+     *  family's no-crypto-deps law forbids adding one, so PBKDF2-SHA256 is the
+     *  hardest primitive available; the iteration count raises the price but does
+     *  not make a low-entropy field safe. The real control for low-entropy fields
+     *  is the DOOR — do not enable `equatable` for them unless the partition being
+     *  learnable is acceptable — not the iteration count. Pre-forget backups retain
+     *  tags. */
+    password(opts?: {
+        minLength?: number;
+        rotateDays?: number;
+        notLastN?: number;
+        equatable?: true;
+    }): ClassifiedFieldSpec;
+    /** Digest-only secret answer: normalized (casefold/trim/collapse), groupable
+     *  into k-of-n matchGroup challenges. Low-entropy by nature — document the
+     *  enumeration math to your users; add app-side rate limiting.
+     *
+     *  @param opts.equatable — emit a store-visible `_bidx` equality tag (enables
+     *  `findByDigest`). Cost band you are accepting:
+     *
+     *  equal values produce equal store-visible tags: anyone with store access
+     *  learns which records share this secret and how many share each value —
+     *  never the value itself. A collection-DEK holder can additionally test
+     *  candidate values offline: the tag's inner digest is PBKDF2-SHA256 (600K),
+     *  which is GPU/ASIC-friendly — an offline attacker runs on the order of
+     *  10⁴–10⁸ guesses/second, so for low-entropy secrets (PINs, casefolded secret
+     *  answers) offline recovery of the equality partition is seconds-to-hours, not
+     *  years. `crypto.subtle` exposes no memory-hard KDF (no scrypt/argon2) and the
+     *  family's no-crypto-deps law forbids adding one, so PBKDF2-SHA256 is the
+     *  hardest primitive available; the iteration count raises the price but does
+     *  not make a low-entropy field safe. The real control for low-entropy fields
+     *  is the DOOR — do not enable `equatable` for them unless the partition being
+     *  learnable is acceptable — not the iteration count. Pre-forget backups retain
+     *  tags. */
+    secretAnswer(opts?: {
+        equatable?: true;
+    }): ClassifiedFieldSpec;
+};

package/dist/via/classified/resolve.d.ts

@@ -0,0 +1,9 @@
+/** Flatten a classifiedFields config into a per-field map + rider computed entries. @module */
+import { type ClassifiedEntry, type ClassifiedFieldSpec } from './descriptor.js';
+export type { ClassifiedEntry, ClassifiedFieldSpec, ClassifiedGroup, ClassifiedList } from './descriptor.js';
+export { ClassifiedConfigError } from './errors.js';
+export interface ResolvedClassified {
+    readonly byField: Record<string, ClassifiedFieldSpec>;
+    readonly riderComputed: Record<string, (record: Record<string, unknown>) => unknown>;
+}
+export declare function resolveClassifiedFields(collection: string, config: Record<string, ClassifiedEntry>): ResolvedClassified;

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

@@ -0,0 +1,11 @@
+/**
+ * The ② capability seam for classified read-egress ops (stage 1: reveal;
+ * stage 2: verify). `ClassifiedStrategy` + `ClassifiedRevealCtx` +
+ * `ClassifiedVerifyCtx` + `NO_CLASSIFIED` now live on the kernel port
+ * (`port/with/classified-strategy.ts`, #629 Task 5) — re-exported here for
+ * compat with existing importers of this module.
+ *
+ * @internal
+ */
+export type { ClassifiedStrategy, ClassifiedRevealCtx, ClassifiedVerifyCtx, ClassifiedVerdict } from '../../port/with/classified-strategy.js';
+export { NO_CLASSIFIED } from '../../port/with/classified-strategy.js';

package/dist/via/classified/validators.d.ts

@@ -0,0 +1,3 @@
+/** Pure write-time validators. Exported so userland can validate storage:'never'
+ *  fields (e.g. CVC) at capture, before dropping them. @module */
+export declare function luhnCheck(pan: string): boolean;

package/dist/via/classified/write.d.ts

@@ -0,0 +1,4 @@
+/** Write-path enforcement: storage:'never' rejection + preset validators.
+ *  Runs BEFORE riders/computed and BEFORE schema validation. Pure. @module */
+import type { ClassifiedFieldSpec } from './descriptor.js';
+export declare function enforceClassifiedWrite(record: Record<string, unknown>, byField: Record<string, ClassifiedFieldSpec>, collection: string): void;

package/dist/via/computed/binding.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `computed` via-binding (#638 Task 7) — covers ONLY `mode: 'virtual'`
+ * fields. Materialized entries never reach here: they compile into
+ * `mergedComputed` (`kernel/collection-config.ts`) and run through the
+ * EXISTING stage-5 `evalComputedFields` write path, byte-for-byte unchanged
+ * (the behavior lock).
+ *
+ * A virtual field is computed on READ, inside `present()` — the money-
+ * `Formatted`/i18n-`Label` precedent (seam map Part 4) generalized to a
+ * user-declared function. It is NEVER stored (no `encodeAtRest`/
+ * `decodeAtRest` — the field never appears in `_data` or any `_sealed`
+ * slot), and its posture is fixed `queryable: 'none'` — there is no stored/
+ * indexed form to query against, regardless of what its sources would
+ * otherwise permit (`ViaGraph`'s grain-'virtual' clamp, `kernel/via/graph.ts`,
+ * is the belt; this binding's own static posture is the suspenders for a
+ * depsless virtual field, which registers no graph edge at all).
+ *
+ * Export/read redaction for a TAINTED virtual field (sourced from a
+ * classified/sealed field) is NOT this binding's job — it stays ignorant of
+ * taint, exactly like `evalComputedFields` stays ignorant of it for
+ * materialized fields. `kernel/via/taint-binding.ts#taintBinding` (appended
+ * to the pipeline by `via/graph-wiring.ts#applyTaintOverlay`, AFTER this
+ * binding) overwrites a tainted virtual field's value with the same
+ * `EXPORT_REDACTION_MARKER` on every present() — the one enforcement seam
+ * every via feature's taint already routes through.
+ */
+import type { ViaBinding } from '../../kernel/via/index.js';
+import type { ComputedDescriptor } from './descriptor.js';
+export interface ComputedViaConfig {
+    /** field name -> its virtual-mode descriptor. Materialized entries are never present here. */
+    readonly virtualFields: ReadonlyMap<string, ComputedDescriptor>;
+}
+export declare function computedBinding(cfg: ComputedViaConfig): ViaBinding;
+export declare function linkComputedVia(): void;

package/dist/via/computed/descriptor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * computed() — the declaration factory for a field whose value is DERIVED
+ * from other fields on the same record (#638 Task 7, spec §6). Composes
+ * with `via()` (the locked grammar since phase A: `via(computed(fn, { deps,
+ * mode }), money('EUR'))`), grouped by `_viaBrand` like every other via
+ * feature (`kernel/via/compose.ts#mergeViaFields`).
+ *
+ * `mode` picks where the function runs:
+ *  - `'materialized'` (default) — TODAY's stage-5 write-time eager compute
+ *    (`with-formula/computed/index.ts#evalComputedFields`), stored like any
+ *    other field. Byte-for-byte the existing `computed: { field: fn }` sugar.
+ *  - `'virtual'` — rides the `present` read phase (the money-`Formatted`/
+ *    i18n-`Label` precedent, seam map Part 4): computed fresh on every
+ *    read, NEVER stored, `queryable: 'none'`, excluded from export unless
+ *    its declared `deps` permit (identical taint rule to materialized —
+ *    see `via/computed/binding.ts`).
+ *
+ * `deps` names the OTHER fields `fn` reads — feeds `ViaGraph` (Task 1/2) so
+ * a source's taint (e.g. a classified field) propagates to this derived
+ * field. A depsless entry is fine UNLESS the collection also declares
+ * classified fields (`kernel/collection-config.ts#resolveComputedEdges`
+ * refuses it — closes the #636 opaque-function leak).
+ */
+import type { ViaDescriptor } from '../../kernel/via/index.js';
+export interface ComputedDescriptor extends ViaDescriptor {
+    readonly _viaBrand: 'computed';
+    readonly fn: (record: Record<string, unknown>) => unknown;
+    readonly deps?: readonly string[];
+    readonly mode: 'materialized' | 'virtual';
+}
+export declare function computed(fn: (record: Record<string, unknown>) => unknown, opts?: {
+    readonly deps?: readonly string[];
+    readonly mode?: 'materialized' | 'virtual';
+}): ComputedDescriptor;
+export declare function isComputedDescriptor(x: unknown): x is ComputedDescriptor;

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

@@ -0,0 +1,28 @@
+/**
+ * Active i18n strategy — `withI18n()` returns the real implementation
+ * that wires multi-locale resolution, i18nText validation, and the
+ * `DictionaryHandle` for `dictKey` fields into the core read/write
+ * paths.
+ *
+ * Consumers opt in by:
+ *
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withI18n } from '@noy-db/hub/i18n'
+ *
+ * const db = await createNoydb({
+ *   store: ...,
+ *   user: ...,
+ *   i18nStrategy: withI18n(),
+ * })
+ * ```
+ *
+ * The factory delegates to the existing `core.ts` and `dictionary.ts`
+ * modules. Splitting the import chain through this file is what lets
+ * tsup tree-shake the `~854 LOC` of dictionary + locale resolution
+ * out of the default bundle when no `withI18n()` import is present.
+ *
+ * @public
+ */
+import type { I18nStrategy } from './strategy.js';
+export declare function withI18n(): I18nStrategy;

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

@@ -0,0 +1,36 @@
+/**
+ * The i18n `ViaBinding` — wires the i18n engine (auto-translate/script
+ * enforcement/validation/densify on write; locale + dict-label presentation
+ * on read) into the kernel's generic Via port. Mirrors
+ * `via/money/binding.ts`'s #553 static-link pattern.
+ *
+ * LIVE (#623 Task 8 wired the cutover): `i18nBinding()`/`linkI18nVia()` are
+ * the real put/read path for every i18n-declaring collection —
+ * `collection.ts`'s `_putInternal`/`applyLocaleToRecord` (the call sites
+ * this file's bodies were moved/adapted from) now delegate their i18n
+ * stages to `this.via.encodeWrite`/`this.via.present` instead of running
+ * the hand-wired i18n logic inline.
+ *
+ * `i18nText()`, `dictKey()`, `staticDict()` each call {@link linkI18nVia}
+ * first — the same #553 pattern `money()` uses.
+ */
+import type { ViaBinding } from '../../kernel/via/index.js';
+/**
+ * Config a collection's i18n declarations resolve to — the binding's
+ * construction input. Fields are loosely typed (`unknown`) at this seam
+ * because the kernel's `ViaBinder` contract is opaque-config-in; the
+ * concrete i18n types are applied inside the binding's own functions.
+ */
+export interface I18nViaConfig {
+    i18nFields?: Record<string, unknown>;
+    dictKeyFields?: Record<string, unknown>;
+    i18nDensifyFields?: Record<string, unknown>;
+    strategy: unknown;
+    defaultLocale?: string;
+    autoTranslateHook?: (...args: unknown[]) => Promise<string>;
+    dictLabelResolver?: (...args: unknown[]) => Promise<string | undefined>;
+    i18nPutValidator?: (record: unknown) => void;
+    collectionName: string;
+}
+export declare function i18nBinding(cfg: I18nViaConfig): ViaBinding;
+export declare function linkI18nVia(): void;

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;