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

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;

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

@@ -0,0 +1,99 @@
+/**
+ * The `'lookup'` `ViaBinding` — wires the lookup engine (present-time label
+ * dressing across all three backing tiers) into the kernel's generic Via
+ * port. Mirrors `via/i18n/binding.ts`'s #553 static-link pattern; the
+ * present-time label-dressing algorithm below is adapted from
+ * `via-i18n/binding.ts:253-337` (the same wildcard/array/scalar handling,
+ * the same `onMissing`/`substitute` policy engine), generalized to branch on
+ * `backing` instead of a static-vs-dynamic descriptor-shape check. For the
+ * `'static'` and `'reserved'` tiers this delegates to `cfg.lookupLabelResolver`
+ * — the SAME vault-built closure the i18n binding's `dictLabelResolver` uses
+ * (static table first, else the `vault.dictionary()` handle) — so a native
+ * `dict()`/`lookup(static)` field resolves through the identical label data
+ * as its `dictKey()`/`staticDict()` alias (the byte-equivalence lock).
+ *
+ * `lookup()`/`enumOf()`/`dict()` each call {@link linkLookupVia} first — the
+ * same #553 pattern `money()`/`dictKey()` use.
+ *
+ * `buildClause` (label-predicate queries) is still undeclared — out of scope
+ * for #650. `compareForOrder` (#650 Task 6, spec §5; matrix tier added Task
+ * 7) resolves a `sortBy`-declared field's ordering via `cfg.snapshotFor`'s
+ * sync snapshot; the hook signature is UNCHANGED (`via/index.ts:128-129` — no
+ * locale param), so it closes over each descriptor's own `displayLocale`
+ * (the same locale-less-hinge default `runLookupPresent`'s
+ * `hasStaticDisplay` branch already uses). `resolveOrderLabel` (#650 Task
+ * 7) is the PER-CALL-locale sibling `orderBy(..., {by:'label'})` needs —
+ * see its own doc comment below. `describeFragment` (#650 Task 7) is the
+ * first-ever consumed `ViaBinding.describeFragment` implementation — see
+ * `with-shape/introspection/describe.ts`'s `buildDescription`.
+ */
+import type { ViaBinding } from '../../kernel/via/index.js';
+import type { LookupDescriptor, LookupBacking, Vocabulary, OnDelete } from './descriptor.js';
+import type { MaterializedBacking } from './registry.js';
+/**
+ * Config a collection's lookup declarations resolve to — the binding's
+ * construction input. `lookupLabelResolver`/`getLookupBacking`/`membership`/
+ * `snapshotFor` are vault-built closures (never a `Collection` handle,
+ * keyring, or DEK/CEK — the zero-knowledge boundary).
+ */
+export interface LookupViaConfig {
+    readonly lookupFields: Record<string, LookupDescriptor>;
+    readonly lookupLabelResolver?: (dimension: string, key: string, locale: string, fallback?: unknown) => Promise<string | undefined>;
+    /**
+     * The matrix (collection) tier's present-time backing-row source, keyed by the full
+     * descriptor (not a bare dimension name) so the closure can resolve by `descriptor.key`,
+     * not the backing row's PUT-id (#651 Task 3 — the same descriptor-gaining dispatch Task 7
+     * already applied to `snapshotFor`).
+     */
+    readonly getLookupBacking?: (descriptor: LookupDescriptor) => (key: string) => Promise<Record<string, unknown> | undefined>;
+    /** Closed-vocabulary write-time membership test (#650 Task 3) — `(field, key) => known?`. */
+    readonly membership?: (field: string, key: string) => boolean | Promise<boolean>;
+    /** Sync per-descriptor altKey index — `ingest`'s normalization source (#650 Task 3). */
+    readonly getAltIndex?: (desc: LookupDescriptor) => MaterializedBacking | undefined;
+    /**
+     * Sync materialized `key -> row` rows for a lookup descriptor (#650 Task
+     * 6, spec §5; matrix-tier routing added #650 Task 7) — `compareForOrder`
+     * and `resolveOrderLabel` below, and `snapshot.ts`'s `presentForJoin`
+     * builder, all read this same vault-built closure. Reserved AND
+     * collection (matrix) tier route here (the vault wires
+     * `dimension -> LookupHandle.snapshotEntries()` / `dimension ->
+     * collection.querySourceForJoin().snapshot()` respectively, keyed by
+     * `descriptor.key` for the matrix case — see `registry.ts`'s
+     * `buildLookupSnapshotRows`); static tier is resolved locally from
+     * `descriptor.table` without calling this.
+     */
+    readonly snapshotFor?: (descriptor: LookupDescriptor) => ReadonlyMap<string, Record<string, unknown>> | undefined;
+    readonly collectionName: string;
+}
+/**
+ * One field's `lookup` descriptor as it appears on a `ViaBinding.
+ * describeFragment()` payload (#650 Task 7 — the first real consumer,
+ * `with-shape/introspection/describe.ts`'s `buildDescription`, imports this
+ * type directly; `describe.ts` is NOT under `kernel/**`, so it's free to
+ * import concrete via/ types the way it already does for
+ * `LookupDescriptor`/`MoneyDescriptor`/etc.). `dimension` is OMITTED (not
+ * emitted as `''`) for a bare `enumOf()` descriptor — the #650 Task 2
+ * `dimension:''` sentinel resolved: no dimension name means no `dimension`
+ * key, not a meaningless empty string (T2 carry, #650 Task 7).
+ */
+export interface LookupDescribeFragmentEntry {
+    readonly dimension?: string;
+    readonly backing: LookupBacking;
+    readonly vocabulary: Vocabulary;
+    readonly key: string;
+    readonly altKeys?: readonly string[];
+    readonly present?: {
+        readonly label: string;
+        readonly by?: string;
+    };
+    readonly sortBy?: string;
+    readonly onDelete: OnDelete;
+    /** Statically-known closed-vocabulary key set (declared `keys`, or a static table's own keys). Omitted when membership lives only in the backing collection/dictionary (open vocabulary, or closed with no declared `keys`). */
+    readonly keys?: readonly string[];
+}
+/** The `'lookup'` binding's `describeFragment()` payload shape. */
+export interface LookupDescribeFragment {
+    readonly lookupFields: Record<string, LookupDescribeFragmentEntry>;
+}
+export declare function lookupBinding(cfg: LookupViaConfig): ViaBinding;
+export declare function linkLookupVia(): void;

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

@@ -0,0 +1,123 @@
+/**
+ * `lookup()` / `enumOf()` / `dict()` descriptors — the three declaration
+ * surfaces for the `'lookup'` via binding (#650 Task 2, phase D of the Via
+ * port). One `LookupDescriptor` shape; the tiers are `backing` details:
+ *
+ * - `lookup(dimension, opts?)`  — matrix tier: first-class collection backing
+ *   (default `backing:'collection'`) — a reference-collection dimension
+ *   (e.g. `countries`), open vocabulary by default.
+ * - `enumOf(keys)`              — enum tier: static in-config table, CLOSED
+ *   vocabulary, no backing store at all (no dimension name — pure inline
+ *   keys). Exported as `enumOf`; the barrel (`index.ts`) re-exports it as
+ *   `enum` (`enum` is a reserved word, so it can't be the function's own
+ *   name).
+ * - `dict(dimension, opts?)`    — dict tier: reserved `_dict_<dimension>`
+ *   micro-collection backing (the `vault.dictionary(name)` engine), open
+ *   vocabulary by default.
+ *
+ * Each factory calls {@link linkLookupVia} first — the declaration IS the
+ * via binding's opt-in unit (#553), same pattern as `money()`/`i18nText()`/
+ * `dictKey()`.
+ */
+import type { OnMissingPolicy } from '../i18n/policy.js';
+/** `'closed'` = enum semantics (membership enforced, Task 3); `'open'` permits unknown keys. */
+export type Vocabulary = 'open' | 'closed';
+/** Where a dimension's rows live: static in-config table / reserved micro-collection / first-class collection. */
+export type LookupBacking = 'static' | 'reserved' | 'collection';
+/** Delete-time referential policy for the backing dimension (default `'restrict'`, enforced in Task 5). */
+export type OnDelete = 'restrict' | 'cascade' | 'nullify';
+/** The one descriptor shape every tier compiles to — tiers differ only by `backing`. */
+export interface LookupDescriptor<Keys extends string = string> {
+    readonly _viaBrand: 'lookup';
+    /** Dimension/dictionary/target name. Empty for a bare `enumOf()` (no backing store, no name). */
+    readonly dimension: string;
+    /** Canonical key field on the row (default `'id'`). */
+    readonly key: string;
+    /** Candidate keys normalized to `key` on ingest (Task 3). */
+    readonly altKeys?: readonly string[];
+    readonly vocabulary: Vocabulary;
+    /** Dressing dimension: which backing-row field supplies `<field>Label`, optionally keyed `by` a sub-field (e.g. locale). */
+    readonly present?: {
+        readonly label: string;
+        readonly by?: string;
+    };
+    /** Field to sort by against the snapshot (Task 6). */
+    readonly sortBy?: string;
+    readonly backing: LookupBacking;
+    readonly onDelete: OnDelete;
+    /** Static/enum inline key set. */
+    readonly keys?: readonly Keys[];
+    /** Static tier only: in-code `key -> { locale -> label }` table. */
+    readonly table?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** Static hybrid hinge (the `staticDict` alias) — locale-less `<field>Label`. */
+    readonly displayLocale?: string;
+    readonly onMissing?: OnMissingPolicy;
+    readonly substitute?: readonly string[];
+    /** Inline display labels (value -> label), the dict-tier sync fallback (mirrors `dictKey`'s `labels`). */
+    readonly labels?: Record<string, string>;
+}
+/**
+ * Matrix tier — first-class collection backing (default `backing:'collection'`).
+ * `dimension` names the backing collection (e.g. `'countries'`).
+ *
+ * `backing` may be overridden to construct any tier through this one
+ * factory — e.g. `lookup(name, { backing:'static', table, displayLocale })`
+ * is the table-bearing static tier `staticDict()` compiles onto. The
+ * `table`/`displayLocale`/`keys`/`onMissing`/`substitute`/`labels` options
+ * are a superset of the brief's literal opts list: `LookupDescriptor`
+ * already carries these fields for exactly this purpose, and without them
+ * `backing:'static'` would be unreachable stand-alone through `lookup()`
+ * (see task-2-report.md's "Design decisions").
+ *
+ * **`altKeys` caveat (matrix tier only)**: normalizing an altKey candidate
+ * to its canonical `key` requires the backing `dimension` collection to be
+ * open in EAGER mode (the default; `{ prefetch: false }` — lazy mode — is
+ * unsupported). A `put()` on a field with `altKeys` whose backing collection
+ * is lazy throws a `ValidationError` naming the field and dimension; open
+ * the backing collection without `{ prefetch: false }`, or drop `altKeys`.
+ */
+export declare function lookup<Keys extends string>(dimension: string, opts?: {
+    key?: string;
+    altKeys?: readonly string[];
+    vocabulary?: Vocabulary;
+    present?: {
+        label: string;
+        by?: string;
+    };
+    sortBy?: string;
+    backing?: LookupBacking;
+    onDelete?: OnDelete;
+    keys?: readonly Keys[];
+    table?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    displayLocale?: string;
+    onMissing?: OnMissingPolicy;
+    substitute?: readonly string[];
+    labels?: Record<string, string>;
+}): LookupDescriptor<Keys>;
+/**
+ * Enum tier — static in-config table, CLOSED vocabulary, no backing store.
+ * No dimension name (pure inline keys) — `dimension` is `''`.
+ */
+export declare function enumOf<const Keys extends readonly string[]>(keys: Keys): LookupDescriptor<Keys[number]>;
+/**
+ * Dict tier — reserved `_dict_<dimension>` micro-collection backing (the
+ * `vault.dictionary(dimension)` engine), open vocabulary by default. The
+ * native equivalent of `dictKey()`.
+ *
+ * Unlike `lookup()`'s matrix tier, `dict()` has no `altKeys` option — its
+ * `_dict_<dimension>` backing is the always-synchronous `LookupHandle`
+ * write-through cache, never a `vault.collection()` that can be opened
+ * `{ prefetch: false }`, so the matrix tier's lazy-mode altKeys restriction
+ * does not apply here.
+ */
+export declare function dict<Keys extends string>(dimension: string, opts?: {
+    keys?: readonly Keys[];
+    vocabulary?: Vocabulary;
+    present?: {
+        label: string;
+        by?: string;
+    };
+    onDelete?: OnDelete;
+    onMissing?: OnMissingPolicy;
+    substitute?: readonly string[];
+}): LookupDescriptor<Keys>;

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

@@ -0,0 +1,220 @@
+/**
+ * `_dict_*` reserved-collection storage engine — `LookupHandle`.
+ *
+ * Verbatim move of `DictionaryHandle` out of `via/i18n/dictionary.ts`
+ * (#650 Task 1 — via-lookup extraction, phase D). The class is renamed to
+ * `LookupHandle` (the dict tier is one backing kind the eventual lookup
+ * layer supports); `via/i18n/dictionary.ts` re-exports it as
+ * `DictionaryHandle` for one release so existing importers compile
+ * unchanged. `DictEntry` / `DictionaryOptions` / `DICT_COLLECTION_PREFIX` /
+ * `dictCollectionName` move with it — they were exclusively consumed by
+ * this class's constructor/methods.
+ *
+ * No behavior change from the pre-move class: same encryption door
+ * (`reservedEnvelopes('_dict_')`, #629 Task 4), same ACL, same ledger
+ * shape, same sync-cache/snapshot contract for dict joins.
+ */
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
+import type { ViaCryptoCtx } from '../../kernel/via/index.js';
+import type { LedgerStore } from '../../with-commit/history/ledger/store.js';
+/** Reserved collection name prefix. Never collides with user collections. */
+export declare const DICT_COLLECTION_PREFIX = "_dict_";
+/** Return the adapter collection name for a named dictionary. */
+export declare function dictCollectionName(dictionaryName: string): string;
+/**
+ * One entry in a `_dict_*` collection. The record `id` (adapter-side
+ * key) IS the stable dictionary key (e.g. `'paid'`). The `labels`
+ * record maps locale codes to display strings.
+ */
+export interface DictEntry {
+    /** Stable key — same as the record id in the adapter. */
+    readonly key: string;
+    /** Locale → label map, e.g. `{ en: 'Paid', th: 'ชำระแล้ว' }`. */
+    readonly labels: Record<string, string>;
+}
+/**
+ * Options for `vault.dictionary(name, options?)`.
+ *
+ * `writableBy` controls the minimum role for write operations (put,
+ * putAll, delete, rename). Defaults to `'admin'` to match the standard
+ * "dictionary contents are owned by admins" convention; set to
+ * `'operator'` for user-editable dictionaries like custom tags.
+ */
+export interface DictionaryOptions {
+    /** Minimum role allowed to write dictionary entries. Default: `'admin'`. */
+    readonly writableBy?: 'owner' | 'admin' | 'operator';
+}
+/**
+ * Handle to a named dictionary within a vault.
+ *
+ * Obtained via `vault.dictionary(name)`. Provides strongly-typed
+ * CRUD for dictionary entries, plus the `rename()` operation that is the
+ * only sanctioned mass-mutation path for dictKey fields.
+ *
+ * All writes are encrypted under the compartment's DEK for the
+ * `_dict_<name>` collection. Adapters never see plaintext.
+ */
+export declare class LookupHandle<Keys extends string = string> {
+    private readonly adapter;
+    private readonly compartmentName;
+    private readonly dictionaryName;
+    private readonly keyring;
+    /**
+     * The `reservedEnvelopes('_dict_')` capability — this handle's sanctioned
+     * crypto door onto its `_dict_<name>` collection (#629 Task 4). Bound by
+     * the Vault; never a keyring, raw DEK, or enclave import.
+     */
+    private readonly reservedEnvelopes;
+    private readonly encrypted;
+    private readonly ledger;
+    private readonly options;
+    /**
+     * Callback provided by the Vault to find and rewrite records
+     * in any registered collection that has a dictKeyField pointing at
+     * this dictionary, used by `rename()`.
+     */
+    private readonly findAndUpdateReferences;
+    private readonly emitter;
+    /**
+     * #647 fix wave 1 — mints a version-ordered delete-marker envelope (the reserved-tier
+     * mirror of #589's ordinary-collection delete marker). Injected rather than imported:
+     * `buildDeleteMarker` constructs the envelope's protected-body fields (`_iv`/`_data`), and
+     * `via/lookup/**` may not reach `kernel/enclave/` directly (Check 11
+     * `enclave-body-only` / Check 15 `via-enclave-isolation`) — the Vault binds the real
+     * `kernel/enclave` function at construction time, same pattern as `reservedEnvelopes` above.
+     */
+    private readonly buildDeleteMarker;
+    /** #650 Task 4 (#647) — dirty-log participation hook (origin `local-write`), threaded from `BuildLookupHandleOptions`. */
+    private readonly onDirty?;
+    /** #650 Task 4 — thin `graphDispatch.collect`-equivalent; opens/collects/flushes a one-shot wave for this touch. */
+    private readonly onRecordMutated?;
+    /** #650 Task 5 (#648) — the real reference check `delete()`'s strict branch calls: restrict
+     *  throws `DictKeyInUseError`, cascade/nullify apply their propagation. Vault-bound; a no-op
+     *  when the dimension has no declared lookup-referencing edges. */
+    private readonly checkReferencesOnDelete?;
+    private readonly collName;
+    /**
+     * Synchronous write-through cache for dict-join support.
+     * Populated on every `put()`, `delete()`, and `rename()`. The snapshot
+     * is built from this cache by `snapshotEntries()` — the query executor
+     * calls this synchronously inside `.toArray()`.
+     *
+     * `null` means "not yet initialized" — callers should use `list()`
+     * to warm the cache before using dict joins on pre-existing data.
+     */
+    private readonly _syncCache;
+    /**
+     * Return all cached entries as `{ key, labels, ...labels }` records —
+     * usable synchronously by the join executor's `snapshot()` call.
+     * Returns an empty array when the cache has never been populated.
+     */
+    snapshotEntries(): readonly Record<string, unknown>[];
+    constructor(adapter: NoydbStore, compartmentName: string, dictionaryName: string, keyring: UnlockedKeyring, 
+    /**
+     * The `reservedEnvelopes('_dict_')` capability — this handle's sanctioned
+     * crypto door onto its `_dict_<name>` collection (#629 Task 4). Bound by
+     * the Vault; never a keyring, raw DEK, or enclave import.
+     */
+    reservedEnvelopes: ReturnType<ViaCryptoCtx['reservedEnvelopes']>, encrypted: boolean, ledger: LedgerStore | undefined, options: DictionaryOptions, 
+    /**
+     * Callback provided by the Vault to find and rewrite records
+     * in any registered collection that has a dictKeyField pointing at
+     * this dictionary, used by `rename()`.
+     */
+    findAndUpdateReferences: ((dictionaryName: string, oldKey: string, newKey: string) => Promise<void>) | undefined, emitter: NoydbEventEmitter, 
+    /**
+     * #647 fix wave 1 — mints a version-ordered delete-marker envelope (the reserved-tier
+     * mirror of #589's ordinary-collection delete marker). Injected rather than imported:
+     * `buildDeleteMarker` constructs the envelope's protected-body fields (`_iv`/`_data`), and
+     * `via/lookup/**` may not reach `kernel/enclave/` directly (Check 11
+     * `enclave-body-only` / Check 15 `via-enclave-isolation`) — the Vault binds the real
+     * `kernel/enclave` function at construction time, same pattern as `reservedEnvelopes` above.
+     */
+    buildDeleteMarker: (version: number, actor: string) => EncryptedEnvelope, 
+    /** #650 Task 4 (#647) — dirty-log participation hook (origin `local-write`), threaded from `BuildLookupHandleOptions`. */
+    onDirty?: ((collection: string, id: string, action: "put" | "delete", version: number) => Promise<void>) | undefined, 
+    /** #650 Task 4 — thin `graphDispatch.collect`-equivalent; opens/collects/flushes a one-shot wave for this touch. */
+    onRecordMutated?: ((collection: string, id: string, action: "put" | "delete", version: number) => Promise<void>) | undefined, 
+    /** #650 Task 5 (#648) — the real reference check `delete()`'s strict branch calls: restrict
+     *  throws `DictKeyInUseError`, cascade/nullify apply their propagation. Vault-bound; a no-op
+     *  when the dimension has no declared lookup-referencing edges. */
+    checkReferencesOnDelete?: ((key: string) => Promise<unknown>) | undefined);
+    private requireWriteAccess;
+    private encryptEntry;
+    private decryptEntry;
+    /** @internal #650 Task 4 — re-read `key`'s CURRENT adapter truth into `_syncCache` (delete the
+     *  cache entry when the key is now gone). Called by `Vault._invalidateSyncApplied` after a
+     *  reserved-lookup row applies via sync, so an already-warmed snapshot/membership/altIndex read
+     *  never sees a stale verdict for a pulled vocabulary edit — the same invalidation a local
+     *  put()/delete()/rename() already triggers via `_syncCache.set`/`delete` above. */
+    _refreshSyncCache(key: string): Promise<void>;
+    /**
+     * Add or overwrite a single dictionary entry.
+     *
+     * @param key    The stable key to store (e.g. `'paid'`).
+     * @param labels Locale → label map (e.g. `{ en: 'Paid', th: 'ชำระแล้ว' }`).
+     */
+    put(key: Keys, labels: Record<string, string>): Promise<void>;
+    /**
+     * Batch-add or overwrite multiple dictionary entries in one call.
+     *
+     * @param entries  `{ key: { locale: label } }` map.
+     */
+    putAll(entries: Record<Keys, Record<string, string>>): Promise<void>;
+    /**
+     * Load the label map for a single key.
+     *
+     * @returns The label map, or `null` if the key doesn't exist.
+     */
+    get(key: Keys): Promise<Record<string, string> | null>;
+    /**
+     * Delete a dictionary key.
+     *
+     * Default mode is `'strict'` — throws `DictKeyInUseError` if any
+     * registered collection has a record referencing this key. Pass
+     * `{ mode: 'warn' }` to skip the check (dev-mode cleanup only).
+     *
+     * Under sync, deletion writes a version-ordered delete-marker row rather than removing the
+     * adapter key outright (#647 fix wave 1) — markers accumulate over time; GC is future work,
+     * acceptable for vocabulary-scale data.
+     */
+    delete(key: Keys, opts?: {
+        mode?: 'strict' | 'warn';
+    }): Promise<void>;
+    /**
+     * Rename a dictionary key — the only sanctioned mass-mutation path.
+     *
+     * Atomically:
+     * 1. Adds the new key with the same labels as the old key.
+     * 2. Updates every registered record that stores the old key to
+     *    store the new key instead.
+     * 3. Deletes the old key.
+     * 4. Appends a single ledger entry recording the rename.
+     *
+     * Respects ACL: throws `PermissionDeniedError` before any mutation
+     * if the caller can't write. The cascade is best-effort atomic
+     * within this call — no two-phase commit across adapter calls.
+     *
+     * Cascade-on-delete is NOT supported. Use `rename()` when you need
+     * to change a key that records reference.
+     */
+    rename(oldKey: Keys, newKey: string): Promise<void>;
+    /**
+     * List all entries in this dictionary.
+     *
+     * @returns Array of `{ key, labels }` objects.
+     */
+    list(): Promise<DictEntry[]>;
+    /**
+     * Resolve a key to its label for the given locale.
+     *
+     * Used by the collection's locale-aware read path to populate
+     * `<field>Label` virtual fields. Returns `undefined` when the
+     * key doesn't exist or has no label for the requested locale
+     * (after exhausting the fallback chain).
+     */
+    resolveLabel(key: string, locale: string, fallback?: string | readonly string[]): Promise<string | undefined>;
+}
+export { LookupHandle as DictionaryHandle };

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

@@ -0,0 +1,17 @@
+/**
+ * `via/lookup/` barrel — the dict/enum-tier lookup engine (#650
+ * Task 1 — via-lookup extraction, phase D of the Via port).
+ *
+ * Not a dedicated public package subpath (no `@noy-db/hub/lookup` entry) —
+ * its declaration surface (`lookup`/`enumOf`/`enum`/`dict` + the public
+ * types) is re-exported from the root `@noy-db/hub` barrel (`src/index.ts`)
+ * instead. This module itself is reached from the kernel spine only through
+ * `port/with/lookup-strategy.ts`, and, for the existing `vault.dictionary()`
+ * surface, through `via/i18n/active.ts`.
+ */
+export { LookupHandle, DictionaryHandle, DICT_COLLECTION_PREFIX, dictCollectionName, type DictEntry, type DictionaryOptions } from './handle.js';
+export { enforceStaticDictOnPut, resolveDictSource, updateReferencingRecords, type DictReferencingCollection } from './registry.js';
+export { withLookup } from './active.js';
+export { lookup, enumOf, enumOf as enum, dict, type LookupDescriptor, type Vocabulary, type LookupBacking, type OnDelete } from './descriptor.js';
+export { lookupBinding, linkLookupVia, type LookupViaConfig } from './binding.js';
+export type { LookupDescribeFragment, LookupDescribeFragmentEntry } from './binding.js';