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

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;

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

@@ -0,0 +1,61 @@
+/**
+ * Branded money output type.
+ *
+ * The decoded read shape of a money field is an exact decimal STRING
+ * (`'10000.00'`) — but a hand-written schema types it `string | number`,
+ * which is honest about the input side and unhelpful on the output
+ * side: every read site hand-coerces, and a missed coercion passes
+ * typecheck silently (then surfaces as a runtime template warning, or
+ * worse, as `'10000.00' * 100` arithmetic).
+ *
+ * {@link MoneyString} is the output-side brand: a `string` that has
+ * been through noy-db's decode (or {@link asMoney}'s guard). Branding
+ * is type-level only — zero runtime cost on the read path.
+ *
+ * ## Wiring the brand through a validator (the input/output asymmetry)
+ *
+ * Keep the permissive `string | number` on the INPUT side so write
+ * sites are untouched, and brand the OUTPUT side. With Zod:
+ *
+ * ```ts
+ * import type { MoneyString } from '@noy-db/hub'
+ *
+ * const moneyValue = z.union([z.number(), z.string()]) as unknown as
+ *   z.ZodType<MoneyString, z.ZodTypeDef, string | number>
+ *
+ * const Invoice = z.object({ id: z.string(), total: moneyValue })
+ * type InvoiceOut = z.output<typeof Invoice> // total: MoneyString
+ * type InvoiceIn  = z.input<typeof Invoice>  // total: string | number
+ * ```
+ *
+ * The cast is sound for fields declared in `moneyFields`: reads pass
+ * through `decodeMoneyFields`, which always produces the canonical
+ * decimal string.
+ */
+declare const MONEY_BRAND: unique symbol;
+/**
+ * An exact decimal string produced by noy-db's money decode
+ * (`'10000.00'`). The brand exists only at the type level — at runtime
+ * a `MoneyString` is a plain string.
+ */
+export type MoneyString = string & {
+    readonly [MONEY_BRAND]: true;
+};
+/**
+ * Runtime-guarded cast to {@link MoneyString}. Accepts a decimal string
+ * or a number, returns the canonical decimal string branded — throws
+ * `MoneyUnsupportedError` on anything non-finite / non-decimal. Use at
+ * trust boundaries (deserialized JSON, route params); values read
+ * through `get()`/`list()` are already canonical.
+ */
+export declare function asMoney(value: string | number): MoneyString;
+/** Type guard: is `value` a decimal string acceptable as money? */
+export declare function isMoneyString(value: unknown): value is MoneyString;
+/**
+ * The ONE sanctioned escape hatch to a JS `number` — explicit because
+ * the conversion is lossy past 2^53. For display math and chart axes;
+ * never feed the result back into stored amounts (use `mulRate` /
+ * `allocate` for exact arithmetic).
+ */
+export declare function moneyNumber(value: MoneyString | string | number): number;
+export {};

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

@@ -0,0 +1,73 @@
+/**
+ * The `money()` field descriptor — a branded schema-layer descriptor, a
+ * sibling of `i18nText()` / `dictKey()`. It owns currency, scale, and
+ * rounding policy for a field; the pure arithmetic lives in
+ * {@link ./fixed-point} and default scale resolution in
+ * {@link ./iso4217}.
+ *
+ * Two modes:
+ *   - **fixed**  `money({ currency: 'EUR' })` — one currency for the
+ *     field; the value stores a bare scaled-integer string.
+ *   - **multi**  `money({ currencies: 'any' | [...] })` — currency travels
+ *     per record; the value stores `{ amount, currency }`.
+ *
+ * `currency` and `currencies` are mutually exclusive.
+ */
+import type { RoundingMode } from './fixed-point.js';
+import { NoydbError } from '../../kernel/errors.js';
+export interface MoneyOptionsFixed {
+    currency: string;
+    /** Override the ISO-4217 default scale (required for unlisted codes). */
+    scale?: number;
+    rounding?: RoundingMode;
+}
+export interface MoneyOptionsMulti {
+    currencies: 'any' | readonly string[];
+    /** Per-currency scale overrides (required for unlisted codes). */
+    scaleOverrides?: Record<string, number>;
+    rounding?: RoundingMode;
+}
+export type MoneyOptions = MoneyOptionsFixed | MoneyOptionsMulti;
+export interface MoneyDescriptor {
+    readonly _noydbMoney: true;
+    /** Via port brand marker — lets a `MoneyDescriptor` satisfy the kernel's opaque `ViaDescriptor`. */
+    readonly _viaBrand: 'money';
+    readonly mode: 'fixed' | 'multi';
+    readonly options: MoneyOptions;
+    readonly rounding: RoundingMode | undefined;
+    /** The currency for fixed mode; `undefined` in multi mode. */
+    readonly fixedCurrency: string | undefined;
+    /** Resolve the scale for a currency, throwing if not allowed / unknown. */
+    scaleFor(currency: string): number;
+    /** Whether this descriptor permits the given currency. */
+    allows(currency: string): boolean;
+    /**
+     * The single currency this descriptor implies, if any — fixed mode, or
+     * multi mode with exactly one allow-listed currency. Lets a multi field
+     * accept a bare amount unambiguously. `undefined` otherwise.
+     */
+    soleCurrency(): string | undefined;
+}
+/** Raised when a written value carries more precision than `scale` allows. */
+export declare class MoneyPrecisionError extends NoydbError {
+    readonly field: string;
+    readonly value: unknown;
+    readonly scale: number;
+    constructor(field: string, value: unknown, scale: number);
+}
+/** Raised when a currency is disallowed or has no resolvable scale. */
+export declare class MoneyCurrencyError extends NoydbError {
+    readonly currency: string;
+    readonly reason: 'not-allowed' | 'unknown-scale';
+    readonly field?: string | undefined;
+    constructor(currency: string, reason: 'not-allowed' | 'unknown-scale', field?: string | undefined);
+}
+/** Raised when an aggregate operation is not supported on a money field. */
+export declare class MoneyUnsupportedError extends NoydbError {
+    readonly field: string;
+    constructor(field: string, message?: string);
+}
+/** Create a {@link MoneyDescriptor}. */
+export declare function money(options: MoneyOptions): MoneyDescriptor;
+/** Runtime predicate for detecting a {@link MoneyDescriptor}. */
+export declare function isMoneyDescriptor(x: unknown): x is MoneyDescriptor;

package/dist/via/money/fixed-point.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure fixed-point decimal core for the money descriptor.
+ *
+ * All conversion goes decimal-string ⇄ scaled `BigInt`. There is no
+ * floating-point arithmetic anywhere: a value like `123.45` becomes
+ * `12345n` purely by string manipulation, never by `value * 100` (which
+ * would reintroduce the very drift money() exists to eliminate). BigInt
+ * has no magnitude ceiling, so values past `Number.MAX_SAFE_INTEGER`
+ * stay exact end-to-end.
+ *
+ * This module knows nothing about currencies, descriptors, or storage —
+ * it is the isolated, exhaustively-tested arithmetic kernel.
+ */
+export type RoundingMode = 'half-up' | 'half-even' | 'half-down' | 'up' | 'down' | 'ceil' | 'floor';
+export type ParseResult = {
+    ok: true;
+    value: bigint;
+} | {
+    ok: false;
+    reason: 'precision' | 'nonfinite';
+};
+/**
+ * Parse a decimal (`number | string`) into a scaled `BigInt` at the
+ * given scale. When the input carries more fractional precision than
+ * `scale`:
+ *   - `rounding` omitted ⇒ `{ ok: false, reason: 'precision' }`
+ *   - `rounding` set ⇒ the tail is rounded per the mode.
+ * Non-finite / unparseable input ⇒ `{ ok: false, reason: 'nonfinite' }`.
+ */
+export declare function parseToScaledInt(input: number | string, scale: number, rounding?: RoundingMode): ParseResult;
+/**
+ * Number of fractional digits in the canonical decimal rendering of
+ * `input` (`'123.45'` → 2, `100` → 0, `'1e-7'` → 7), or `null` when the
+ * input is non-finite / not a decimal. Used to infer the working scale
+ * of arithmetic helpers from their canonical-string inputs.
+ */
+export declare function decimalScaleOf(input: number | string): number | null;
+/**
+ * Re-scale a scaled `BigInt` from `fromScale` to `toScale`. Scaling up
+ * is exact (append zeros); scaling down rounds the discarded tail per
+ * `rounding`. The rounding decision reuses the same kernel as
+ * {@link parseToScaledInt}, so `rescaleScaledInt(parse('1.005', 3), 3, 2)`
+ * and `parse('1.005', 2, mode)` agree for every mode.
+ */
+export declare function rescaleScaledInt(value: bigint, fromScale: number, toScale: number, rounding?: RoundingMode): bigint;
+/**
+ * Render a scaled `BigInt` back to its canonical decimal string at the
+ * given scale. `(12345n, 2)` → `'123.45'`; `(5n, 0)` → `'5'`;
+ * `(-1n, 2)` → `'-0.01'`. Exact for any magnitude.
+ */
+export declare function formatScaledInt(value: bigint, scale: number): string;

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

@@ -0,0 +1,15 @@
+/**
+ * `@noy-db/hub` money service — the `money()` field descriptor for
+ * currency-safe, exact decimal storage, formatting, and aggregation.
+ *
+ * @see ./descriptor for the public `money()` factory.
+ */
+export { money, isMoneyDescriptor, MoneyPrecisionError, MoneyCurrencyError, MoneyUnsupportedError } from './descriptor.js';
+export type { MoneyDescriptor, MoneyOptions, MoneyOptionsFixed, MoneyOptionsMulti, } from './descriptor.js';
+export type { RoundingMode } from './fixed-point.js';
+export { scaleForCurrency } from './iso4217.js';
+export type { FxRates } from './money-reducer.js';
+export { mulRate, allocate } from './arith.js';
+export type { MulRateOptions, AllocateOptions } from './arith.js';
+export { asMoney, isMoneyString, moneyNumber } from './branded.js';
+export type { MoneyString } from './branded.js';

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

@@ -0,0 +1,6 @@
+/**
+ * Return the ISO-4217 minor-unit scale for a currency code, or `null`
+ * when the code is not in the known set (caller must supply an explicit
+ * scale).
+ */
+export declare function scaleForCurrency(code: string): number | null;

package/dist/via/money/money-reducer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Money-aware aggregation: exact `sum` / `min` / `max` over money
+ * fields.
+ *
+ * The generic reducers (`aggregate/reducers.ts`) read a field via
+ * `readNumber`, which coerces a string (the stored scaled-integer form
+ * of money, e.g. `'12345'`) to `0` — so an un-wrapped money `sum` would
+ * silently return zero. {@link wrapMoneyReducers} rewrites any `sum` /
+ * `min` / `max` over a declared money field into a reducer that
+ * accumulates per-currency `BigInt` totals of the stored integers, so
+ * the result is exact for any magnitude (past `Number.MAX_SAFE_INTEGER`
+ * included).
+ *
+ * Results are currency-aware and never silently mix currencies:
+ *   - **fixed** mode → a single exact decimal string.
+ *   - **multi** mode → an exact `Record<currency, string>` map.
+ *   - **`sum` with `convertTo` + `fx`** → a single exact string, with
+ *     each currency converted via BigInt arithmetic (no float).
+ *
+ * `remove()` is implemented for every money reducer so they participate
+ * in incremental live-aggregation and materialized-view maintenance
+ * exactly like the generic reducers they replace.
+ */
+import type { MoneyDescriptor } from './descriptor.js';
+import type { AggregateSpec } from '../../with-lookup/aggregate/aggregation.js';
+export type FxRates = Record<string, number | string>;
+/**
+ * Rewrite any `sum` / `min` / `max` reducer over a declared money field
+ * into its exact BigInt money-aware equivalent. Other reducers (and
+ * reducers over non-money fields) pass through unchanged. Returns a new
+ * spec; the input is not mutated.
+ */
+export declare function wrapMoneyReducers(spec: AggregateSpec, moneyFields: Record<string, MoneyDescriptor>): AggregateSpec;