@noy-db/hub 0.3.0-pre.1 → 0.3.0-pre.11

package/dist/with-formula/materialized-views/dependency-analyzer.d.ts

@@ -0,0 +1,58 @@
+import type { Query } from '../../kernel/query/builder.js';
+import type { MaterializedViewStrategy } from './types.js';
+/**
+ * Walks a `Query<T>` plan and returns the set of source collection
+ * names that any source-write should trigger a refresh on.
+ *
+ * Handles:
+ *   - root collection (the one the query was built from)
+ *   - FK join targets (`.join(field, { as })`)
+ *
+ * Also handles:
+ *   - cross-join targets (`.crossJoin(target, { as })`) — v3
+ *
+ * Deferred:
+ *   - `.wherePredicate(name)` — v2 predicate primitive
+ *   - Overlay-name expansion to {base, overlay}
+ *
+ * The set is materialized at MV registration time. The MV registry
+ * uses it to (a) dispatch `onSourceWrite` only to MVs that actually
+ * care, and (b) contribute edges to the shared cycle-detection graph.
+ */
+export declare function analyzeDependencies(query: Query<any>): Set<string>;
+/**
+ * Convenience: produce a stable string summary of the query plan
+ * suitable for `queryHash` derivation. Captures everything the
+ * dependency analyzer reads + the where/orderBy/limit/offset
+ * structure that affects materialized rows.
+ *
+ * `joinContext` is intentionally NOT included — the join-resolution
+ * function references would defeat hash determinism. The set of join
+ * TARGETS (collection names) IS included via the plan.joins legs.
+ */
+export declare function summarizeQueryPlan(query: Query<any>): string;
+/**
+ * Canonical string description of a UNION MV's plan, used as input to
+ * `computeQueryHash`.
+ *
+ * Asymmetry note:
+ *   - Arm collection names are NOT sorted. Declaration order is
+ *     semantically meaningful for the dedup-only UNION path —
+ *     `materializeUnionResult` iterates `spec.unionSources` in
+ *     declaration order and keeps the first-seen row per composite key
+ *     (tie-break precedence). If we sorted arms here, a consumer who
+ *     reordered `unionSources` to change precedence would compute the
+ *     same `queryHash`, refresh would be a no-op, and stale MV rows
+ *     would persist. Hashing in declaration order makes any reorder
+ *     trigger a refresh.
+ *   - `groupBy` fields ARE sorted. Multi-key groupBy buckets are
+ *     commutative (`canonicalGroupKey` produces the same composite key
+ *     regardless of field order in the input spec).
+ *   - `aggregate` keys ARE sorted. Reducer-spec keys are independent
+ *     of each other — order of declaration doesn't change output.
+ *
+ * Per-arm `map` functions are NOT fingerprinted; consumers must bump
+ * the MV's `name` (or rely on application-level cache busting) when
+ * `map` semantics change non-equivalently.
+ */
+export declare function summarizeUnionPlan<T extends Record<string, unknown>>(spec: MaterializedViewStrategy<T>): string;

package/dist/with-formula/materialized-views/executor.d.ts

@@ -0,0 +1,71 @@
+import type { Collection } from '../../kernel/collection.js';
+import type { TxContext } from '../../with-commit/tx/transaction.js';
+import type { MVQueryContext } from './types.js';
+import type { RegisteredMV } from './registry.js';
+import { type PutDerivedOutputCtx } from '../../kernel/via/dispatch.js';
+/**
+ * Accessor shape passed in from the owning Vault. Mirrors v1's
+ * `DerivationStaleAccessor` — provides the per-collection resolver
+ * and the active TxContext so refresh writes/tombstones register on
+ * `_executed` for rollback symmetry.
+ */
+export interface MVExecutorAccessor {
+    getCollection(name: string): Collection<any>;
+    getActiveTxContext(): TxContext | null;
+    /**
+     * Vault-shaped accessor passed to the MV's `query()` callback at
+     * each refresh. Same instance the registry used at registration
+     * time; threading through the executor lets the refresh path
+     * re-evaluate the closure against the live vault state.
+     */
+    getQueryContext(): MVQueryContext;
+    /**
+     * #638 Task 5 — ctx for `putDerivedOutput`'s frozen-period skip+audit. #641: the lazy
+     * resolve-on-read caller (`stale.ts#resolveStaleMVOnRead`) now supplies one too — built at
+     * the `Collection.get()`/`list()` entry point with a `'resolve-on-read'` sentinel id (no
+     * real "reacting write" for a read-triggered materialize, mirroring `refreshView()`'s
+     * `'refreshView'` sentinel). Still declared optional here since `MVExecutorAccessor` is a
+     * general shape and a future caller could reasonably omit it.
+     */
+    dispatchCtx?: PutDerivedOutputCtx;
+}
+export interface RefreshResult {
+    /** Rows newly written / overwritten. */
+    written: number;
+    /** Rows tombstoned via `_internalDelete` (only when `onEmpty: 'delete'`). */
+    deleted: number;
+    /** Failed row writes (non-strict mode). */
+    failed: number;
+}
+/**
+ * Run an MV's `query()` and write the result rows to the output
+ * collection. Same-DEK encryption: routes through the standard
+ * `Collection.put` pipeline, so the output collection's DEK is what
+ * gets used (matches the v2 spec's "same DEK as the left-most source"
+ * invariant — `Collection.put` looks up the DEK by collection name,
+ * and the output collection IS the MV's owned collection).
+ *
+ * Stamps `_materializedFrom` onto every emitted row.
+ *
+ * **Tombstoning:** when `spec.onEmpty: 'delete'` (default), rows
+ * that existed in a prior refresh but no longer appear in the new
+ * materialized result are deleted via `Collection._internalDelete` —
+ * the housekeeping bypass primitive prevents user
+ * `onDelete` guards on the output collection from firing on these
+ * system-internal deletes. `onEmpty: 'keep'` opts out (rows from
+ * prior refreshes linger even when the new result lacks them).
+ *
+ * **Cost ceiling:** if the materialized row count exceeds
+ * `spec.maxRows` (default 100k), throws `MaterializedViewTooLargeError`
+ * before any writes hit the store — so strict-mode rollback is
+ * clean.
+ *
+ * **Strict mode:** `spec.strict === true` re-throws on any
+ * row-write failure; the active TxContext registration means the
+ * source-write rolls back atomically via `revertExecuted`.
+ *
+ * @internal
+ */
+export declare const MaterializedViewExecutor: {
+    refresh(reg: RegisteredMV, accessor: MVExecutorAccessor): Promise<RefreshResult>;
+};

package/dist/with-formula/materialized-views/index.d.ts

@@ -0,0 +1,11 @@
+export { withMaterializedView } from './with-materialized-view.js';
+export { MaterializedViewRegistry } from './registry.js';
+export { MaterializedViewExecutor } from './executor.js';
+export { analyzeDependencies, summarizeQueryPlan } from './dependency-analyzer.js';
+export { computeQueryHash, canonicalizeQueryPlan } from './query-hash.js';
+export { markMVStale, resolveStaleMVOnRead, isMVStale, clearMVStale } from './stale.js';
+export type { MVStaleAccessor } from './stale.js';
+export type { MaterializedViewStrategy, MaterializedViewStrategyHandle, MaterializedViewOutput, MaterializedFromMeta, UnionSource, UnionArmJoin, } from './types.js';
+export type { RegisteredMV } from './registry.js';
+export type { MVExecutorAccessor, RefreshResult } from './executor.js';
+export { MaterializedViewCycleError, MaterializedViewConfigError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, } from '../../kernel/errors.js';

package/dist/with-formula/materialized-views/query-hash.d.ts

@@ -0,0 +1,23 @@
+export declare function computeQueryHash(mvName: string, 
+/**
+ * Source-collection set the query depends on. Sorted before
+ * canonicalization so set iteration order doesn't affect the hash.
+ */
+dependencies: ReadonlySet<string>, 
+/**
+ * Stringified query-plan summary. The caller produces this from the
+ * `Query<T>` builder — concretely: a JSON serialization of clauses +
+ * orderBy + limit + offset + joins. Function bodies inside
+ * `wherePredicate` are NOT included here (those carry their own
+ * `predicateHash` to be folded in by a later sub-issue).
+ */
+queryPlanSummary: string): Promise<string>;
+/**
+ * Canonicalize a query plan for hashing. Walks the plan structure
+ * with sorted keys so insertion order doesn't perturb the result.
+ * Lives here rather than in `query/builder.ts` to keep that module
+ * stable across MV-specific evolutions.
+ *
+ * @internal exported for testing
+ */
+export declare function canonicalizeQueryPlan(plan: unknown): string;

package/dist/with-formula/materialized-views/registry.d.ts

@@ -0,0 +1,99 @@
+import type { ViaGraph, FieldRef, EdgeKind, Grain } from '../../kernel/via/graph.js';
+import type { FieldClause } from '../../kernel/query/predicate.js';
+import type { MaterializedViewStrategy, MVQueryContext } from './types.js';
+/**
+ * One registered MV strategy alongside its derived metadata. Stored
+ * type-erased on `TRow` so the registry can hold heterogeneous MVs.
+ */
+export interface RegisteredMV {
+    readonly spec: MaterializedViewStrategy<any>;
+    /** Output collection name (`spec.output?.collection ?? spec.name`). */
+    readonly outputCollection: string;
+    /** Set of source collections; populated at registration via the analyzer. */
+    readonly dependencies: ReadonlySet<string>;
+    /** Canonical `queryHash` — `_materializedFrom.queryHash` for every emitted row. */
+    readonly queryHash: string;
+    /**
+     * Top-level FieldClauses on the partition field, captured at
+     * registration time. Used by the cycle detector to resolve
+     * same-collection-as-source edges via the partition-discriminator
+     * check. Empty when `spec.output?.partition` is undefined.
+     */
+    readonly partitionClauses: readonly FieldClause[];
+    /**
+     * #638 Task 2 — `'record'` for a row-per-source-row Query<T> or
+     * `unionSources` MV, `'aggregate'` for a `.groupBy().aggregate()` MV
+     * (the shape that requires explicit `sources`, since the dependency
+     * analyzer can't walk an aggregate plan). Feeds `edges()`'s grain.
+     */
+    readonly grain: Grain;
+}
+/**
+ * Vault-internal registry of MV strategies. Owned by `Vault`; not
+ * exported. Parallel to v1's `DerivationRegistry`; the two graphs share
+ * a single cycle-detection pass at vault open (see `validate`).
+ *
+ * @internal
+ */
+export declare class MaterializedViewRegistry {
+    /** Keyed by `spec.name`. */
+    private readonly _byName;
+    /** Keyed by dependency source-collection → MVs that depend on it. */
+    private readonly _bySource;
+    /**
+     * Register an MV. Invokes `spec.query()` once at registration time to
+     * read the plan + join context; the resulting `Query<T>` is discarded
+     * after dependency extraction. `vault.collection(...)` must therefore
+     * be functional by the time this runs — typically wired from
+     * `Vault._initMaterializedViews` after collection bootstrap.
+     *
+     * Throws `MaterializedViewSourceUnknownError` if the analyzer
+     * surfaces a dependency the vault doesn't know about (when a
+     * `knownCollections` checker is supplied).
+     */
+    register(spec: MaterializedViewStrategy<any>, db: MVQueryContext, options?: {
+        knownCollections?: (name: string) => boolean;
+    }): Promise<void>;
+    /** All MVs that depend on `source`, in registration order. */
+    mvsForSource(source: string): ReadonlyArray<RegisteredMV>;
+    /** Single MV by name, or `undefined`. */
+    byName(name: string): RegisteredMV | undefined;
+    /** Iterate over every registered MV. */
+    all(): ReadonlyArray<RegisteredMV>;
+    /**
+     * Graph edges for #638 Task 2: one `'mv'` edge per registered MV — target
+     * = the output collection (a `WHOLE_RECORD` artifact node), sources =
+     * every dependency (also `WHOLE_RECORD` nodes). Same-collection edges
+     * (`dep === outputCollection`) are skipped IFF the MV declares an
+     * `output.partition` discriminator AND the query has a where-clause that
+     * provably excludes the partition value (`partitionDisjoint`) — the SAME
+     * condition the old local DFS used. Grain comes from the registration-time
+     * `RegisteredMV.grain`.
+     */
+    edges(): ReadonlyArray<{
+        readonly target: FieldRef;
+        readonly sources: readonly FieldRef[];
+        readonly kind: EdgeKind;
+        readonly grain: Grain;
+    }>;
+    /**
+     * Cycle detection, delegated to `ViaGraph.assertAcyclic()` (#638 Task 2 —
+     * retires the local DFS). `graph` is the caller's shared per-vault graph,
+     * ALREADY carrying this registry's `edges()` AND `DerivationRegistry`'s
+     * (registered by the caller — see `Vault._initMaterializedViews`, which
+     * runs after `_initDerivations`, so a pure-derivation cycle already threw
+     * `DerivationCycleError` there; any cycle surfacing here necessarily
+     * touches an MV edge). Throws `MaterializedViewCycleError` — SAME class as
+     * before.
+     */
+    validate(graph: ViaGraph): void;
+}
+/**
+ * Wrap an `MVQueryContext` so its `.collection().query()` returns a
+ * Query<T> with the MV's declared predicates attached. Bare Queries
+ * (outside of any MV) don't gain `.wherePredicate()` — only Queries
+ * obtained through this wrapped db do.
+ *
+ * @internal
+ */
+export declare function wrapDbWithPredicates(db: MVQueryContext, predicates: NonNullable<MaterializedViewStrategy<Record<string, unknown>>['predicates']>): MVQueryContext;

package/dist/with-formula/materialized-views/stale.d.ts

@@ -0,0 +1,62 @@
+import type { Collection } from '../../kernel/collection.js';
+import type { TxContext } from '../../with-commit/tx/transaction.js';
+import type { PutDerivedOutputCtx } from '../../kernel/via/dispatch.js';
+import type { MaterializedViewRegistry } from './registry.js';
+import type { MVQueryContext } from './types.js';
+/**
+ * Accessor shape passed in from the owning Vault. Provides the
+ * registry (used as a stable WeakMap key + to look up MVs by output
+ * collection) and the runtime context the lazy refresh needs.
+ * Mirrors v1's `DerivationStaleAccessor`.
+ */
+export interface MVStaleAccessor {
+    registry(): MaterializedViewRegistry;
+    getCollection(name: string): Collection<any>;
+    getActiveTxContext(): TxContext | null;
+    getQueryContext(): MVQueryContext;
+}
+/**
+ * Mark an MV as stale. Called from `Collection.dispatchMaterializedViews`
+ * when a source-write fires for a `refresh: 'lazy'` MV.
+ *
+ * @internal
+ */
+export declare function markMVStale(registry: MaterializedViewRegistry, mvName: string): void;
+/**
+ * Test-only: check whether a given MV name is currently flagged stale
+ * against a registry. Exported so the regression suite can pin the
+ * stale-bit lifecycle without touching the internal `WeakMap`.
+ *
+ * @internal
+ */
+export declare function isMVStale(registry: MaterializedViewRegistry, mvName: string): boolean;
+/**
+ * Called from `Collection.get` (and any reader that materializes the
+ * MV's output collection). If any MV producing `outputCollection` is
+ * flagged stale, runs the executor against the live source state
+ * before returning. No-op when there is no pending work — keeps the
+ * read fast path negligible.
+ *
+ * `dispatchCtx` (#641): threaded from the calling `Collection`'s
+ * `#dispatchCtx({ collection: outputCollection, id: 'resolve-on-read' })` — a read has no
+ * real "reacting write" record, so `'resolve-on-read'` is the sentinel id, mirroring
+ * `Vault.refreshView()`'s `'refreshView'` sentinel for the same reason. Passed straight
+ * through to the executor so a stale row whose output lands in a closed period follows the
+ * frozen-output rule (skip + `derivation:skipped-frozen`, #637) instead of throwing
+ * `PeriodClosedError` out of a read.
+ *
+ * Dynamic-imports the executor only when a stale flag actually fires
+ * (the floor-bundle isolation pattern v1 derivations established in
+ * floor-bundle isolation pattern).
+ */
+export declare function resolveStaleMVOnRead(accessor: MVStaleAccessor, outputCollection: string, dispatchCtx?: PutDerivedOutputCtx): Promise<void>;
+/**
+ * Drop every stale flag for a registry. Used after a manual
+ * `vault.refreshView(name)` runs the executor explicitly — the
+ * post-refresh state matches the registered strategies, so
+ * lingering stale bits would force a redundant refresh on the next
+ * read.
+ *
+ * @internal
+ */
+export declare function clearMVStale(registry: MaterializedViewRegistry, mvName: string): void;

package/dist/with-formula/materialized-views/types.d.ts

@@ -0,0 +1,318 @@
+import type { Query } from '../../kernel/query/builder.js';
+import type { Collection } from '../../kernel/collection.js';
+import type { AggregateSpec, Aggregation } from '../../with-lookup/aggregate/aggregation.js';
+import type { GroupedAggregation } from '../../with-lookup/aggregate/groupby.js';
+import type { JoinStrategy } from '../../kernel/query/join.js';
+import type { MoneyDescriptor } from '../../via/money/descriptor.js';
+import type { I18nTextDescriptor } from '../../via/i18n/core.js';
+/**
+ * Minimal vault-shaped accessor passed to the MV `query()` callback.
+ * Defined as a structural interface so the strategy types don't have
+ * to import the full `Vault` class (avoids a circular import). The
+ * Vault implements this shape natively.
+ */
+export interface MVQueryContext {
+    collection<T extends Record<string, unknown>>(name: string): Collection<T>;
+}
+/**
+ * Metadata that travels inside the `_data` payload of a materialized
+ * row. Lives in encrypted payload, not in the unencrypted envelope —
+ * the storage backend cannot infer the MV graph from listing.
+ *
+ * Extends the `_derivedFrom` precedent from v1: same encryption shape,
+ * same "metadata-inside-data" location.
+ */
+export interface MaterializedFromMeta {
+    /** Stable identity for the MV that emitted this row. */
+    readonly mvName: string;
+    /**
+     * SHA-256 of (mvName + canonical query plan + dependency-set).
+     * Changes when the query structure changes → forces refresh on
+     * next visit (parallels v1's `strategyHash`).
+     */
+    readonly queryHash: string;
+    /**
+     * Map from source collection name → `_v` of the source row(s) that
+     * contributed to this MV row at materialization time. For aggregates
+     * over many rows, this is `max(_v)` per source collection — coarse
+     * but sufficient for stale detection.
+     */
+    readonly sourceVersions: Record<string, number>;
+    /** ISO timestamp when this row was materialized. */
+    readonly materializedAt: string;
+}
+/** Output routing for an MV. Optional — when omitted, writes to a collection named after `name`. */
+export interface MaterializedViewOutput {
+    /** Output collection name. Defaults to `name`. */
+    collection?: string;
+    /**
+     * For same-collection-as-source MVs — see § Same-collection partition
+     * discriminator in the v2 spec. The cycle detector resolves the
+     * same-collection edge IFF the query has a where-clause that
+     * provably excludes `partition.value` (supports `==` against a
+     * different value, `!=` against the value, and `in` lists that
+     * don't contain it). Naïve same-collection MVs without a disjoint
+     * clause throw `MaterializedViewCycleError` at vault open.
+     */
+    partition?: {
+        field: string;
+        value: unknown;
+    };
+}
+/**
+ * One arm of a UNION materialized view. Reads rows from `collection`,
+ * then maps each into the MV's row shape via `map`.
+ *
+ * The per-source `map` is the schema-unification boundary — sibling
+ * collections can have different schemas, and `map` is where they
+ * meet the MV's row type. The hub does NOT compare schemas across
+ * arms; consumer responsibility is that every arm's `map` returns
+ * the same shape (the strategy's `TRow` type parameter enforces this
+ * at compile time).
+ */
+export interface UnionSource<TRow extends Record<string, unknown>> {
+    /** Source collection name. Must exist in the vault. */
+    readonly collection: string;
+    /**
+     * Pure function from a source row to the unified MV row shape.
+     * Called once per source row at materialization time. Each arm's
+     * mapped output is concatenated into a single stream before
+     * `groupBy` + `aggregate` run.
+     *
+     * Returning `null` or `undefined` **omits** the source row from the
+     * materialized output entirely — the row is not pushed into the
+     * unified stream and never reaches `groupBy` / `aggregate`. This
+     * removes the need for sentinel rows (e.g. `{ amount: 0 }`) whose
+     * sole purpose is to be aggregated away.
+     *
+     * When this arm declares {@link join}, the aliased right-side
+     * record(s) are attached to the source row under each leg's `as`
+     * BEFORE `map` runs, so `map` can read `sourceRow[leg.as]`.
+     */
+    readonly map: (sourceRow: Record<string, unknown>) => TRow | null | undefined;
+    /**
+     * Optional FK joins to apply to this arm's rows before {@link map}.
+     * Each leg resolves a `ref()`-declared foreign key on the arm's
+     * source collection into an attached right-side record under
+     * `as` — the same machinery as the query-form `Query.join()`.
+     *
+     * The right-side collections must be listed in the strategy's
+     * {@link MaterializedViewStrategy.sources} so writes to them trigger
+     * MV refresh — registration throws `MaterializedViewConfigError`
+     * otherwise (the union dependency set comes from arm `collection`s
+     * alone, which would not include join targets).
+     */
+    readonly join?: ReadonlyArray<UnionArmJoin>;
+}
+/**
+ * One FK join leg on a UNION arm. Mirrors the option shape of the
+ * query-form `Query.join(field, { as, maxRows?, strategy? })`.
+ */
+export interface UnionArmJoin {
+    /** FK field on the arm's source collection (must have a `ref()` declared). */
+    readonly field: string;
+    /** Alias under which the resolved right-side record attaches on the source row. */
+    readonly as: string;
+    /** Per-side row ceiling override. `undefined` → the join default. */
+    readonly maxRows?: number;
+    /** Planner strategy override. `undefined` → auto-select. */
+    readonly strategy?: JoinStrategy;
+}
+/**
+ * Registration shape passed to `withMaterializedView()`.
+ *
+ * @typeParam TRow - the materialized row type (the query's result row)
+ */
+export interface MaterializedViewStrategy<TRow extends Record<string, unknown>> {
+    /**
+     * Stable identity for this view. Used as the output collection name
+     * unless `output.collection` overrides. Must be unique within the vault.
+     */
+    name: string;
+    /**
+     * Declared query (single-source mode). Called at registration time
+     * with a vault-shaped accessor so the closure can compose collections
+     * without pre-existing in-scope references; called again at each
+     * refresh.
+     *
+     * Built via the same `Query<T>` chainable builder used elsewhere —
+     * `.where()`, `.join()`, `.groupBy()`, `.aggregate()`. The
+     * dependency analyzer walks the returned plan to determine source
+     * collections.
+     *
+     * Mutually exclusive with {@link unionSources}: a strategy must
+     * declare exactly one of `query` (single-source) or `unionSources`
+     * (multi-source UNION). Registration throws
+     * `MaterializedViewConfigError` if both are set or neither is set.
+     */
+    query?: (db: MVQueryContext) => Query<TRow> | Aggregation<TRow> | GroupedAggregation<TRow>;
+    /**
+     * UNION-form sources: an explicit list of sibling collections
+     * that contribute rows to a single MV. Each arm's `map` projects a
+     * source row into the MV's unified row shape; the mapped streams are
+     * concatenated, then {@link groupBy} + {@link aggregate} run on the
+     * combined output.
+     *
+     * Mutually exclusive with {@link query}. Registration throws
+     * `MaterializedViewConfigError` if both are set, if `unionSources`
+     * is empty, or if two arms name the same `collection`.
+     *
+     * A SINGLE arm is valid: it expresses map→group→aggregate
+     * over one collection with a COMPUTED bucket key (e.g. a month
+     * sliced from a date field). The query form's `.groupBy()` accepts
+     * stored field names only, so a derived key needs the arm's `map`.
+     *
+     * UNION mode replaces the dependency-analyzer path: the source
+     * collections come directly from `unionSources[].collection`, and
+     * {@link sources} is ignored.
+     */
+    unionSources?: ReadonlyArray<UnionSource<TRow>>;
+    /**
+     * Group-key field(s) for UNION mode. Applied to the
+     * concatenated mapped-row stream from {@link unionSources} before
+     * {@link aggregate} runs. Accepts a single field name or a tuple of
+     * field names for multi-key grouping (same shape as
+     * `Query.groupBy(...fields)`).
+     *
+     * UNION-mode only. Ignored if {@link query} is set — single-source
+     * grouping is expressed inside the `Query<T>` returned from `query()`
+     * via `.groupBy(...).aggregate(...)`.
+     */
+    groupBy?: string | ReadonlyArray<string>;
+    /**
+     * Aggregation spec for UNION mode. Applied per-group after
+     * {@link groupBy} buckets the concatenated mapped-row stream from
+     * {@link unionSources}. Same shape as the `AggregateSpec` passed to
+     * `Query.aggregate()`.
+     *
+     * UNION-mode only. Ignored if {@link query} is set.
+     */
+    aggregate?: AggregateSpec;
+    /**
+     * Money descriptors for the UNION-mode aggregate, keyed by the
+     * OUTPUT/intermediate field name as it appears in the mapped row and
+     * in {@link aggregate} (NOT the source collection's field name). When
+     * declared, any `sum` / `min` / `max` over a keyed field is rewritten
+     * into an exact per-currency BigInt reducer — without this, money
+     * aggregation in UNION mode silently runs in float (since the
+     * concatenated mapped stream is a plain array with no collection
+     * money context to inherit).
+     *
+     * UNION-mode only — the query form inherits its money descriptors
+     * from the source collection automatically. The descriptor's
+     * currency/scale must match what the arms' `map()` emits for that
+     * field (each arm maps into the same unified shape, so one descriptor
+     * per output field covers all arms). Meaningless without
+     * {@link aggregate}; registration throws `MaterializedViewConfigError`
+     * if declared alone.
+     */
+    moneyFields?: Record<string, MoneyDescriptor>;
+    /**
+     * Compute-time i18n resolution locale (`mv` layer). UNION-mode only.
+     *
+     * An MV that **groups by** an `i18nText` field would otherwise bucket on the
+     * raw `{ locale: string }` map — an unstable object key. Set `i18nLocale`
+     * (with {@link i18nFields} describing those fields) and, before grouping, the
+     * executor resolves each declared i18n group-key field to this locale at the
+     * `mv` layer (`resolvePolicy(onMissing, 'mv')`), so buckets are stable strings.
+     *
+     * This is the **compute** path only: i18n fields *carried through* for display
+     * stay raw — declare them on the OUTPUT collection and they resolve per-reader
+     * at read time (the resolve-at-output model). Without `i18nLocale`, grouping by
+     * a raw i18n field throws `LocaleNotSpecifiedError` (steer: group by a
+     * `dictKey`/`staticDict` code — the stable key — and label at read).
+     *
+     * Query-form MVs do their own `groupBy` inside the `Query`, which carries no
+     * locale yet — so `i18nLocale` /
+     * `i18nFields` on a query-form MV throw `MaterializedViewConfigError`.
+     */
+    i18nLocale?: string;
+    /**
+     * i18n descriptors for UNION-mode compute, keyed by the OUTPUT field
+     * name as it appears in the mapped row (NOT the source field). Mirrors
+     * {@link moneyFields}: the concatenated mapped stream is a plain array with no
+     * collection i18n context, so the descriptor (carrying `onMissing`/`substitute`
+     * /`fallback`) must be declared here for the `mv`-layer resolution that
+     * {@link i18nLocale} drives. Meaningless without `i18nLocale`.
+     */
+    i18nFields?: Record<string, I18nTextDescriptor>;
+    /**
+     * Pure function from a materialized row → stable id used in the
+     * output collection. Required — explicit always beats default-with-pitfalls
+     * (explicit always beats default-with-pitfalls; see the slash-collision rationale).
+     */
+    rowKey: (row: TRow) => string;
+    /**
+     * Explicit source collections. Required when `query()` returns
+     * an `Aggregation` or `GroupedAggregation` rather than a `Query<T>`
+     * — the dependency analyzer can't introspect through `groupBy().aggregate()`
+     * back to the source. Optional for plain `Query<T>` results — the
+     * analyzer extracts dependencies automatically from the query plan.
+     *
+     * When set, takes precedence over auto-analysis.
+     */
+    sources?: ReadonlyArray<string>;
+    /**
+     * Declared deterministic predicates. Each entry pairs a
+     * consumer-stable `hash` with a function. The `query()` callback's
+     * Query<T> can invoke them via `.wherePredicate(name, ctx?)`. The
+     * predicate's `hash` + a canonical-JSON hash of `ctx` both fold
+     * into `queryHash` — bumping either forces refresh on next visit.
+     *
+     * Consumer responsibility: bump `hash` when the function's semantics
+     * change. Failing to bump after a non-equivalent change leaves
+     * stale rows around until the next explicit refresh.
+     */
+    predicates?: {
+        [name: string]: {
+            hash: string;
+            fn: (row: TRow, ctx?: unknown) => boolean;
+        };
+    };
+    /**
+     * Refresh policy.
+     *
+     * - `'eager'` — re-materialize synchronously inside the source-write
+     *   transaction (composes with `withTransactions` for strict-mode
+     *   rollback).
+     * - `'lazy'` — mark stale on source-change; materialize on first
+     *   read of the MV.
+     * - `'manual'` — only materializes when `vault.refreshView(name)` is
+     *   called. Useful for very expensive MVs or time-dependent queries
+     *   whose `ctx` changes externally.
+     */
+    refresh: 'eager' | 'lazy' | 'manual';
+    /** Output routing. Optional; defaults to writing the collection named after `name`. */
+    output?: MaterializedViewOutput;
+    /**
+     * What to do when a re-materialization produces zero rows for a key
+     * that previously had rows.
+     *
+     * - `'delete'` (default) — tombstone the prior MV row via
+     *   `Collection._internalDelete` (system housekeeping bypasses user
+     *   `onDelete` guards on the output collection — the housekeeping
+     *   bypass composition fix).
+     * - `'keep'` — leave the prior MV row in place. Useful when zero
+     *   is a meaningful state.
+     */
+    onEmpty?: 'delete' | 'keep';
+    /**
+     * `true` re-throws on any row-write failure → composes with
+     * `withTransactions` to roll back the source-write atomically via
+     * `revertExecuted`. Default `false` (failed rows are
+     * isolated; other rows commit).
+     */
+    strict?: boolean;
+    /**
+     * Row-count ceiling for the materialized output. Throws
+     * `MaterializedViewTooLargeError` before any writes when exceeded
+     * — keeps the rollback clean. Default `100_000`; override per-MV
+     * when the domain warrants it.
+     */
+    maxRows?: number;
+}
+/** Returned by `withMaterializedView()` and consumed by `createNoydb`. */
+export interface MaterializedViewStrategyHandle {
+    readonly __noydb_strategy: 'materialized-view';
+    readonly spec: MaterializedViewStrategy<any>;
+}

package/dist/with-formula/materialized-views/with-materialized-view.d.ts

@@ -0,0 +1,24 @@
+import type { MaterializedViewStrategy, MaterializedViewStrategyHandle } from './types.js';
+/**
+ * Register a materialized view: a declared query whose result is
+ * persisted as a queryable collection and kept fresh as sources
+ * change. Writes go through the standard `Collection.put` pipeline;
+ * refresh-driven deletes route through `Collection._internalDelete` so
+ * user `onDelete` guards on the output collection aren't tripped by
+ * housekeeping.
+ *
+ * Two registration modes:
+ *   - **single-source** — declare `query: (db) => Query<TRow>`; the
+ *     dependency analyzer derives source collections from the plan.
+ *   - **UNION** — declare `unionSources: [{ collection, map }, ...]`
+ *     plus optional `groupBy` + `aggregate`; the executor reads each
+ *     arm, maps to the unified row shape, concatenates, then groups
+ *     and aggregates.
+ *
+ * The two modes are mutually exclusive — exactly one of `query` /
+ * `unionSources` must be set at registration time.
+ *
+ * See docs/superpowers/specs/2026-05-20-dim14-mv-v2-design.md (single-source v2)
+ * and docs/superpowers/specs/2026-05-21-dim14-mv-multikey-and-union.md (UNION).
+ */
+export declare function withMaterializedView<TRow extends Record<string, unknown>>(spec: MaterializedViewStrategy<TRow>): MaterializedViewStrategyHandle;