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

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';

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

@@ -0,0 +1,228 @@
+/**
+ * Pure dict-registry helpers — extracted from `kernel/vault.ts`'s dict
+ * bodies (#650 Task 1 — via-lookup extraction, phase D).
+ *
+ * These take the vault-resident registry Maps (and a couple of vault-bound
+ * callbacks) as ARGUMENTS instead of closing over `this` — no `Vault`
+ * import here, so this module stays a plain, testable function library.
+ * `kernel/vault.ts` keeps the registry Maps themselves (they're populated
+ * by `vault.collection()` and read by the backup path) and calls these
+ * helpers through the `port/with/lookup-strategy.ts` seam.
+ */
+import type { JoinableSource } from '../../kernel/query/index.js';
+import type { ViaGraph } from '../../kernel/via/graph.js';
+import type { StaticDictDescriptor } from '../../port/with/i18n-strategy.js';
+import { type LookupHandle } from './handle.js';
+import type { LookupDescriptor } from './descriptor.js';
+/**
+ * Validate staticDict codes on a `put()`. For each `staticDict()` field,
+ * every stored code must be a declared key of the descriptor's table, else
+ * `UnknownDictCodeError`. Opt out per descriptor with `{ validateCodes:
+ * false }`. Supports scalar, dotted, and `[].`-wildcard field paths via
+ * `getAtPath` (same path support as i18n validation).
+ *
+ * `staticFields` is the collection's `field → StaticDictDescriptor` map
+ * (`Vault#staticDescriptorByField.get(collectionName)`) — `undefined`/empty
+ * is a no-op.
+ */
+export declare function enforceStaticDictOnPut(staticFields: Record<string, StaticDictDescriptor> | undefined, record: unknown): void;
+/**
+ * Build a `JoinableSource` for a dictKey field, for use in dict joins.
+ * Returns a source whose snapshot contains `{ key, labels, ...labels }`
+ * records — one per dictionary entry — keyed by the stable key.
+ *
+ * staticDict: a code-table-backed source — snapshot() materialises the
+ * in-memory table into rows, mirroring `LookupHandle.snapshotEntries()`.
+ * Carries `displayLocale` so a locale-less `{ by: 'label' }` query has a
+ * default locale to resolve at.
+ *
+ * Plain dictKey: the snapshot is built synchronously from the
+ * `LookupHandle`'s write-through cache, which is populated on every
+ * `put()`, `rename()`, `delete()`, and `list()` call. For pre-existing
+ * data not yet touched this session, call `await vault.dictionary(name).list()`
+ * first to warm the cache.
+ *
+ * Returns `null` when `field` is not a dictKey in `leftCollection`.
+ */
+export declare function resolveDictSource(leftCollection: string, field: string, staticDescriptorByField: ReadonlyMap<string, Record<string, StaticDictDescriptor>>, dictKeyFieldRegistry: ReadonlyMap<string, Record<string, string>>, getDictionaryHandle: (name: string) => LookupHandle): JoinableSource | null;
+/** The minimal collection surface `updateReferencingRecords` needs. */
+export interface DictReferencingCollection {
+    list(): Promise<Record<string, unknown>[]>;
+    put(id: string, record: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Find and rewrite records in every registered collection whose
+ * dictKeyField points at `name`, replacing `oldKey` with `newKey`. Used by
+ * `LookupHandle.rename()` (the only sanctioned mass-mutation path for
+ * dictKey fields) via the vault's `findAndUpdateReferences` callback.
+ *
+ * `registry` is `Vault#dictKeyFieldRegistry` (collection name → field name
+ * → dictionary name); `getCollection` is the vault's collection accessor —
+ * rewrites go through the public `coll.put()` choke point, same as before.
+ */
+export declare function updateReferencingRecords(registry: ReadonlyMap<string, Record<string, string>>, getCollection: (collectionName: string) => DictReferencingCollection, name: string, oldKey: string, newKey: string): Promise<void>;
+/**
+ * Resolve a label from an in-memory `{ locale -> label }` map, walking the
+ * same fallback chain semantics as `LookupHandle.resolveLabel` (#650 Task 2
+ * — moved here from `kernel/vault.ts` so the SAME chain serves both the
+ * i18n binding's `dictLabelResolver` and the lookup binding's
+ * `lookupLabelResolver`, which #650 Task 2 wires to the identical closure).
+ */
+export declare function resolveLabelFromMap(labels: Readonly<Record<string, string>>, locale: string, fallback?: string | readonly string[]): string | undefined;
+/**
+ * Project a native `lookup(dimension, { backing:'static', table, … })`
+ * descriptor into the legacy `StaticDictDescriptor` shape — the
+ * alias-equivalence compat seam (#650 Task 2) that lets a native
+ * static-tier lookup field reuse the SAME vault registries
+ * (`staticByName`/`staticDescriptorByField`) — and therefore the same
+ * `dictLabelResolver`/`resolveDictSource` machinery — as its `staticDict()`
+ * alias. `vocabulary:'closed'` maps to `validateCodes:true` (closed = only
+ * declared codes are legal); `'open'` maps to `validateCodes:false`.
+ * Returns `undefined` for non-static or table-less (bare `enumOf`)
+ * descriptors — those have nothing to register.
+ */
+export declare function lookupToStaticDictCompat(desc: LookupDescriptor): StaticDictDescriptor | undefined;
+/** The vault-registry entries a collection's `lookupFields` contribute — the alias-equivalence bridge (#650 Task 2). */
+export interface LookupDictCompat {
+    /** Reserved-tier fields: field name -> dimension (dictionary) name — merges into `dictKeyFieldRegistry`. */
+    readonly dictFieldMap: Record<string, string>;
+    /** Static-tier (table-bearing) fields, projected — merges into `staticDescriptorByField`/`staticByName`. */
+    readonly staticEntries: ReadonlyArray<readonly [string, StaticDictDescriptor]>;
+}
+/**
+ * Bridge a collection's `lookupFields` into the SAME shape the legacy dict
+ * registries expect, so `resolveDictSource`/`dictLabelResolver` (and
+ * therefore `.join()`/`orderBy({by:'label'})`) serve a native `dict()`/
+ * `lookup(static)` field identically to its `dictKey()`/`staticDict()`
+ * alias — the reserved-vs-first-class-backing "matrix" tier is NOT bridged
+ * here (no vault registry backs it; Task 5/6 build its own graph edge /
+ * snapshot seam).
+ */
+export declare function collectLookupDictCompat(lookupFields: Record<string, LookupDescriptor> | undefined): LookupDictCompat;
+/**
+ * Reserved-dict deps of a set of named collections (#653) — the `_dict_*`
+ * collections partial sync must auto-include alongside a `collections`
+ * filter, mirroring `SyncEngine`'s existing satellite-pair expansion.
+ * One hop is provably complete: `vault.collection()` refuses `_dict_*`
+ * names, so a dict can never itself declare lookup fields — no
+ * dict-of-dict chain to recurse through.
+ */
+export declare function reservedDictDepsOf(names: readonly string[], dictKeyFieldRegistry: ReadonlyMap<string, Record<string, string>>): readonly string[];
+/**
+ * A lookup dimension's sync membership/altKey table, materialized from its
+ * backing rows (#650 Task 3). `keys` is every canonical key present;
+ * `altIndex` maps an altKey candidate VALUE to its owning canonical key.
+ */
+export interface MaterializedBacking {
+    /** Canonical key values present in the materialized rows. */
+    readonly keys: ReadonlySet<string>;
+    /** altKey candidate value -> canonical key. */
+    readonly altIndex: ReadonlyMap<string, string>;
+}
+/**
+ * Build a lookup dimension's altKey index from its backing rows, enforcing
+ * declare/warm-time uniqueness across `key ∪ altKeys` values (#650 Task 3 —
+ * the CHE/SWZ drift class: two different rows must never claim the same
+ * candidate key). `rows` is keyed by canonical key (`row[descriptor.key]`
+ * for the matrix tier; the dimension's own key for static/reserved).
+ * An altKey candidate VALUE may be a string or number — both normalize via
+ * `coerceLookupKey` (#651 Task 3); non-scalar/absent values are skipped.
+ * Pure — no I/O. Throws `ValidationError` on collision.
+ */
+export declare function materializeBackingTable(descriptor: LookupDescriptor, rows: ReadonlyMap<string, Record<string, unknown>>): MaterializedBacking;
+/**
+ * Closed-vocabulary membership test for one candidate key (#650 Task 3).
+ * Static tier: sync, against the in-config key set (declared `keys`, or the
+ * table's own keys when table-bearing). Reserved tier: sync — the declared
+ * `keys` union the reserved handle's live write-through snapshot (closes
+ * #649 for the native `dict()` spelling: the declared-keys promise the old
+ * `dictKey()` doc comment made falsely). Matrix (collection) tier: sync —
+ * delegates to `buildLookupAltIndex` so membership is checked against the
+ * SAME `row[descriptor.key]` keying the altKey index uses (review fix,
+ * Important 1: an earlier PUT-id `.get(key)` scan disagreed with the
+ * altIndex whenever `descriptor.key !== 'id'`, wrongly rejecting valid
+ * non-id candidates and wrongly accepting an unrelated row's PUT-id).
+ */
+export declare function checkLookupMembership(descriptor: LookupDescriptor, key: string, getDictionary: (dimension: string) => LookupHandle, getCollection: (dimension: string) => {
+    querySourceForJoin(): JoinableSource;
+}): boolean;
+/**
+ * The ONE guarded key coercion (#651 Task 3, dm12) — string/number values
+ * coerce to their canonical `String()` form; everything else (`null`,
+ * `undefined`, objects, …) coerces to `undefined`. Every consumer that turns
+ * a raw record field into a lookup key routes through this, closing the
+ * bare-`String()` `"undefined"`/`"null"`-key poisoning class (seam map
+ * finding 6): a row whose key field is genuinely absent must never mint the
+ * literal candidate string `"undefined"`.
+ */
+export declare function coerceLookupKey(raw: unknown): string | undefined;
+/**
+ * Resolve a backing row's canonical key VALUE — `coerceLookupKey(row[descriptor.key])`
+ * (#651 Task 3). The matrix tier's `row[descriptor.key]`, never the row's own PUT-id
+ * when the two differ (`descriptor.key !== 'id'`).
+ */
+export declare function resolveBackingRowKey(descriptor: LookupDescriptor, row: Record<string, unknown>): string | undefined;
+/**
+ * The referencing-side match predicate — does `rec[field]` (coerced) equal an
+ * already-coerced `compareKey` (#651 Task 3)? Shared by every site that scans a
+ * referencing collection for rows pointing at a given backing key
+ * (`with-shape/links/vault-facade.ts`'s ref-delete propagation, `kernel/via/dispatch.ts`'s
+ * forget-fanout twin).
+ */
+export declare function matchesReferencingValue(rec: Record<string, unknown>, field: string, compareKey: string): boolean;
+/**
+ * Materialize a lookup dimension's altKey index from whatever backing data
+ * is synchronously available (#650 Task 3 — the `ingest` source). Static:
+ * the in-config table. Reserved: the reserved handle's live write-through
+ * cache (the same warm-via-put()/list() cache `resolveDictSource` already
+ * relies on). Matrix (collection): the backing collection's own in-memory
+ * eager cache via `querySourceForJoin()` — already public, already the
+ * mechanism `.join()` uses (`with-shape/links/vault-facade.ts`'s
+ * `resolveSource`); no new I/O, no fire-and-forget warm step. Like that
+ * existing join precedent, a dimension collection this vault session has
+ * not yet opened/populated sees an empty snapshot (no altKey normalization
+ * until it has rows) — open/populate it first for normalization to apply.
+ * A matrix row whose `descriptor.key` field coerces to `undefined` (missing/
+ * non-scalar) is SKIPPED — never enters the index under a poisoned
+ * `"undefined"` key (#651 Task 3, dm12).
+ */
+export declare function buildLookupAltIndex(descriptor: LookupDescriptor, getDictionary: (dimension: string) => LookupHandle, getCollection: (dimension: string) => {
+    querySourceForJoin(): JoinableSource;
+}): MaterializedBacking;
+/** Thin wrapper — `collectLookupRefEdges` + one `graph.registerDerived` call per edge. Lets
+ *  `vault.collection()` (kernel-surface-budgeted, #650 Task 5) register a collection's lookup-ref
+ *  edges with a single line, keeping the ceiling-guarded call site a thin call (route logic here). */
+export declare function registerLookupRefEdges(graph: ViaGraph, collectionName: string, lookupFields: Record<string, LookupDescriptor> | undefined): void;
+/**
+ * `LookupViaConfig.snapshotFor`'s vault-built row source (#650 Task 6, spec
+ * §5; matrix-tier coverage added #650 Task 7, spec §6 — Task 6 deferred it,
+ * see `task-6-report.md`'s Concerns #1; the reviewer's Task-7 dispatch
+ * refuted the "needs a new vault-resident registry" premise: the descriptor
+ * is already in hand at both call sites, so `snapshotFor` just needs to
+ * ACCEPT it). Takes the full `descriptor` (not a bare dimension name) so it
+ * can route the matrix tier's `key` field, which — unlike reserved tier's
+ * hardcoded `'id'` — varies per collection. Routes on `descriptor.backing`:
+ *
+ * - **reserved**: rows come straight from the SAME `LookupHandle.
+ *   snapshotEntries()` write-through cache `dictLabelResolver`/
+ *   `resolveDictSource` already read (no second copy), keyed by each
+ *   entry's own canonical `key` (always `'id'` by construction for this
+ *   tier — `dict()`'s factory hardcodes it).
+ * - **collection** (matrix): rows come from `getCollection(dimension).
+ *   querySourceForJoin().snapshot()` — the SAME sync, already-live cache
+ *   `buildLookupAltIndex`'s matrix branch (above, this file) and `.join()`
+ *   itself already read — re-keyed via `resolveBackingRowKey(descriptor, row)`,
+ *   NOT the row's own PUT-id (which may differ when `key !== 'id'`; the exact
+ *   distinction the #650 Task 3 review fix already applies to
+ *   `checkLookupMembership`'s matrix branch). A row whose `descriptor.key`
+ *   field coerces to `undefined` is skipped (#651 Task 3, dm12).
+ * - **static**: never routed here — `descriptor.table` is read directly by
+ *   the caller (`binding.ts`'s `compareLookupOrder`/`resolveLookupOrderLabel`,
+ *   `snapshot.ts`'s `presentLookupForJoin`); no vault call needed.
+ *
+ * `isReservedDimension` is the vault's `reservedLookupCollections`
+ * membership test.
+ */
+export declare function buildLookupSnapshotRows(descriptor: LookupDescriptor, isReservedDimension: (dimension: string) => boolean, getDictionary: (dimension: string) => LookupHandle, getCollection: (dimension: string) => {
+    querySourceForJoin(): JoinableSource;
+}): ReadonlyMap<string, Record<string, unknown>> | undefined;

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

@@ -0,0 +1,67 @@
+/**
+ * The sync lookup snapshot + join/locale seam (#650 Task 6, spec §5 — "the
+ * snapshot+locale seam"). Retires the #626 kernel→via grandfather:
+ * `kernel/query/join.ts` no longer imports `via/i18n/core.js` directly
+ * — it calls the `presentForJoin` hook this file's `buildPresentForJoin`
+ * builds instead (seam map Part 2 item 4, the #626 reviewer-spec'd shape:
+ * a sync `presentI18nForJoin`-class hook on `JoinableSource`).
+ *
+ * `LookupSnapshot` is the sync materialized `key -> row` view over ONE
+ * lookup dimension's ALREADY-LIVE backing data (the `active.ts`
+ * `_syncCache`/`snapshotEntries` write-through-cache pattern — never a
+ * second copy of the data: `LookupViaConfig.snapshotFor`'s vault-built
+ * closure reads the SAME `LookupHandle._syncCache` /
+ * first-class-collection cache every other lookup consumer
+ * (`dictLabelResolver`, `resolveDictSource`, `getAltIndex`) already reads).
+ * Serves (reserved AND matrix tier since #650 Task 7 — `registry.ts`'s
+ * `buildLookupSnapshotRows` routes both; static tier is read straight off
+ * `descriptor.table` by every consumer below, never through this cache):
+ *   - join dressing (`presentForJoin`, consumed by `kernel/query/join.ts`
+ *     via `JoinableSource.presentForJoin`)
+ *   - dimension sort (`compareForOrder`, consumed by
+ *     `via/lookup/binding.ts`'s `ViaBinding.compareForOrder` closure)
+ *   - per-call-locale order-label resolution (`resolveOrderLabel`, #650
+ *     Task 7 — the `orderBy(..., {by:'label'})` channel `compareForOrder`
+ *     structurally can't serve, no locale param; consumed by
+ *     `kernel/query/builder.ts`'s `buildOrderLabelMaps`)
+ *   - membership: reserved/static-tier membership (#650 Task 3,
+ *     `checkLookupMembership`) already reads the identical sync caches
+ *     directly — not re-plumbed through this file; see
+ *     `.superpowers/sdd/task-6-report.md`'s "bridge disposition" section.
+ *
+ * Sync end-to-end (#553) — every function here is a pure, synchronous
+ * transform over already-materialized rows; no store read, no Promise.
+ */
+import type { LookupDescriptor } from './descriptor.js';
+import { type I18nTextDescriptor } from '../i18n/core.js';
+/** A lookup dimension's sync materialized view — see file header. */
+export interface LookupSnapshot {
+    /** The full backing row for `key`, or `undefined` when `key` isn't (yet) present in the snapshot. */
+    row(key: string): Record<string, unknown> | undefined;
+    /** The dimension's declared presentation label for `key` at `locale` — mirrors `binding.ts`'s `fetchLookupLabel` (matrix-row branch), generalized to any tier's already-materialized rows. */
+    label(key: string, locale: string, fallback?: unknown): string | undefined;
+    /**
+     * Exact ordering for two canonical keys against `descriptor.sortBy`
+     * (falls back to `present.label`, then to the raw keys) at `locale`.
+     * Never throws — degrades to comparing the raw keys when no sortable
+     * value resolves for either side.
+     */
+    compareKeys(a: string, b: string, locale: string): number;
+}
+/**
+ * Build a sync `LookupSnapshot` over one dimension's already-materialized
+ * rows (canonical-key -> row, the SAME keying `materializeBackingTable`
+ * (`registry.ts`, #650 Task 3) uses). Pure — never reads a store.
+ */
+export declare function buildLookupSnapshot(dimension: string, rows: ReadonlyMap<string, Record<string, unknown>>, descriptor: LookupDescriptor): LookupSnapshot;
+/**
+ * Build the combined sync `presentForJoin(record, locale)` hook a
+ * `Collection` attaches to the `JoinableSource` it exposes
+ * (`querySourceForJoin()`) — the i18n-text half (`presentI18nForJoin`, the
+ * exact `applyI18nLocale(..., 'join')` partial application
+ * `kernel/query/join.ts` used to call directly, #626) composed with the
+ * lookup-label half above. `undefined` when the collection declares
+ * neither — `JoinableSource.presentForJoin` then stays unset, matching
+ * today's `i18nFields`-absent behavior exactly (#626 parity lock).
+ */
+export declare function buildPresentForJoin(i18nFields: Record<string, I18nTextDescriptor> | undefined, lookupFields: Record<string, LookupDescriptor> | undefined, getSnapshotRows: ((descriptor: LookupDescriptor) => ReadonlyMap<string, Record<string, unknown>> | undefined) | undefined): ((record: unknown, locale: string) => unknown) | undefined;

package/dist/via/money/arith.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Exact money arithmetic helpers — `mulRate` and `allocate`.
+ *
+ * Both operate on the canonical decoded string form that `get()`
+ * returns (`'10000.00'`), entirely in scaled-`BigInt` space — no
+ * floating-point step anywhere, exact past 2^53. They are pure
+ * functions with no vault or descriptor dependency: the working scale
+ * is inferred from the amount's fractional digits (a canonical money
+ * string always carries exactly the field's scale) or pinned with
+ * `opts.scale`.
+ *
+ * Why these two: app-side invariants of the form
+ * `Σ parts === whole` (receipt totals, net-zero WHT pairs, proration)
+ * carry ±0.01 tolerances ONLY because the math is major-unit floats +
+ * round2. `mulRate` (VAT-style rate application with explicit
+ * rounding) and `allocate` (largest-remainder split — parts sum to the
+ * input EXACTLY, by construction) make those tolerances zero.
+ */
+import { type RoundingMode } from './fixed-point.js';
+export interface MulRateOptions {
+    /**
+     * Output scale (fraction digits). Defaults to the amount's own
+     * fractional digits — for a canonical money string that IS the
+     * field's scale.
+     */
+    readonly scale?: number;
+    /** Rounding for the final re-scale. Default `'half-up'`. */
+    readonly rounding?: RoundingMode;
+}
+export interface AllocateOptions {
+    /** Working scale. Defaults to the amount's own fractional digits. */
+    readonly scale?: number;
+}
+/**
+ * Multiply a money amount by a decimal rate, exactly.
+ *
+ * The rate is parsed at its OWN full precision (`0.07` → `7` at scale
+ * 2), the product computed in `BigInt` at `amountScale + rateScale`,
+ * then re-scaled back to the output scale with the requested rounding —
+ * one rounding step, at the very end.
+ *
+ * ```ts
+ * mulRate('10000.00', 0.07)                       // '700.00'  (VAT)
+ * mulRate('33.33', '0.07')                        // '2.33'    (half-up)
+ * mulRate('33.33', 0.07, { rounding: 'floor' })   // '2.33'
+ * mulRate(100, 0.07, { scale: 2 })                // '7.00'
+ * ```
+ */
+export declare function mulRate(amount: number | string, rate: number | string, opts?: MulRateOptions): string;
+/**
+ * Split a money amount across weighted buckets with ZERO drift: the
+ * returned parts sum to the input exactly, by construction
+ * (largest-remainder method).
+ *
+ * Each bucket gets `floor(amount × weightᵢ / Σweights)`; the leftover
+ * minor units (always fewer than the bucket count) go one each to the
+ * buckets with the largest truncated remainders — ties broken by
+ * position, earlier bucket first. Weights are parsed as exact decimals
+ * (no float division anywhere); they must be non-negative with a
+ * positive sum.
+ *
+ * ```ts
+ * allocate('100.00', [1, 1, 1])   // ['33.34', '33.33', '33.33']
+ * allocate('0.05', [3, 7])        // ['0.02', '0.03']
+ * allocate('-100.00', [1, 1, 1])  // ['-33.34', '-33.33', '-33.33']
+ * ```
+ */
+export declare function allocate(amount: number | string, weights: ReadonlyArray<number | string>, opts?: AllocateOptions): string[];

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

@@ -0,0 +1,21 @@
+/**
+ * The money `ViaBinding` — wires the money engine (normalize/paths/where/
+ * money-reducer) into the kernel's generic Via port. `money()`
+ * (descriptor.ts) calls {@link linkMoneyVia} at declaration time — the
+ * same #553 static-link pattern the retired `linkMoneyEngine()` /
+ * `kernel/money-runtime.ts` seam used, now the only one (Task 6 cut the
+ * query DSL over to this binding and deleted the legacy seam).
+ */
+import type { ViaBinding } from '../../kernel/via/index.js';
+import type { MoneyDescriptor } from './descriptor.js';
+/** #669 — the money binder's config bag. `virtualMoneyFields` is the money∩virtual-mode-
+ *  computed field-name intersection (`kernel/collection-config.ts#resolveVirtualMoneyFields`);
+ *  absent/empty means no field on this collection composes money with a virtual computed
+ *  field on itself — the pre-#669 behavior (no `presentLate`, ordinary `present()` for
+ *  every declared money field). */
+export interface MoneyBindingConfig {
+    readonly moneyFields: Record<string, MoneyDescriptor>;
+    readonly virtualMoneyFields?: ReadonlySet<string>;
+}
+export declare function moneyBinding(moneyFields: Record<string, MoneyDescriptor>, virtualMoneyFields?: ReadonlySet<string>): ViaBinding;
+export declare function linkMoneyVia(): void;