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

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

@@ -0,0 +1,113 @@
+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, RegisteredMV } from './registry.js';
+import type { MVQueryContext } from './types.js';
+import type { NoydbStore } from '../../kernel/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;
+/**
+ * Reserved collection holding CONTENT-FREE lazy-stale markers (record id =
+ * MV name, plaintext `_iv: ''` envelope, no payload) — mirrors the
+ * `_meta`/schema-fence marker envelope shape. Written only from the
+ * delete/forget/elevate dispatcher (#736); ordinary source writes stay
+ * in-memory-only (the cheap path). Read via the adapter directly, never
+ * through `vault.collection()` — same reserved-collection convention as
+ * `_subject_index`/`_meta`.
+ */
+export declare const MV_STALE_COLLECTION = "_mv_stale";
+/**
+ * Invalidate an MV from the delete/forget/elevate dispatcher (#736) — the ordinary
+ * source-write path (`dispatchMaterializedViews`) never calls this. Deletes EVERY
+ * persisted row in `reg.outputCollection` via `_internalDelete` (the at-rest law: a
+ * stale mark alone leaves the elevated/forgotten source's plaintext sitting in the
+ * output row) using the adapter directly so the read-path's `resolveStaleMVOnRead`
+ * isn't triggered mid-invalidation. `mode: 'lazy'` also persists the stale mark so a
+ * cold session recomputes on next read; `'manual'` gets the purge only — the MV
+ * serves empty until an explicit `vault.refreshView()` (erasure wins). Deletion is
+ * stamp-scoped (`_materializedFrom.mvName === reg.spec.name` — see the loop below),
+ * so another registered MV sharing this output collection keeps its own rows intact:
+ * no cross-MV re-marking is needed here, only `reg` itself is marked stale.
+ *
+ * Returns the count of rows actually `_internalDelete`d (#761 item 1) — folded by the
+ * caller into `dispatchMaterializedViewsOnDelete`'s `deleted` so `ForgetResult.derivedRecordsErased`
+ * counts lazy/manual purges too, not just the eager executor's tombstone leg — plus
+ * `residueUndecodable`, the bare ids whose ownership stamp could NOT be decoded (#776): a
+ * candidate row that fails to decode under the collection's default DEK (e.g. elevated above
+ * tier 0 on a tiered output collection) has UNKNOWN ownership — it might be this MV's own
+ * output, or (same-collection shape) a plain user record — so it is never erased, but it must
+ * be SURFACED rather than silently skipped (the #724 posture), since it may still hold the
+ * forgotten/pre-elevation contribution, decryptable by tier-holders — and `residueDeclined`
+ * (#785), the bare ids that DID decode and stamp-match but whose `_internalDelete` declined
+ * (ownership CONFIRMED, erasure declined).
+ *
+ * @internal
+ */
+export declare function invalidateMVAtRest(accessor: MVStaleAccessor, reg: RegisteredMV, mode: 'lazy' | 'manual'): Promise<{
+    deleted: number;
+    residueUndecodable: string[];
+    residueDeclined: string[];
+}>;
+/**
+ * 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;
+/**
+ * `clearMVStale` plus the persisted marker (#736) — `Vault.refreshView()`'s
+ * completion path. A lingering persisted marker after a manual refresh would
+ * make the NEXT cold session recompute redundantly.
+ *
+ * @internal
+ */
+export declare function clearMVStaleFully(adapter: NoydbStore, vault: string, registry: MaterializedViewRegistry, mvName: string): Promise<void>;

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

@@ -0,0 +1,399 @@
+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;
+}
+/**
+ * Projection-form registration (#810): one output row per record of a
+ * primary `source` collection, enriched with forward FK legs and
+ * reverse one-to-many "collect" legs BEFORE `map` shapes the MV row.
+ * The niwat federated read-model shape — a bill row carrying its
+ * client lookup plus the receipt / application / credit-note sets
+ * that point back at it.
+ */
+export interface ProjectionSpec<TRow extends Record<string, unknown>> {
+    /** Primary collection. One output row per primary record (unless {@link map} omits). */
+    readonly source: string;
+    /** Join legs attached to each primary row BEFORE {@link map} runs. */
+    readonly joins: ReadonlyArray<ProjectionJoinLeg>;
+    /**
+     * Pure projection: primary row + leg attachments → MV row. Called
+     * once per primary record at materialization time, AFTER every leg
+     * has attached under its `as` alias.
+     *
+     * Returning `null` or `undefined` **omits** the primary record from
+     * the materialized output entirely (same contract as the UNION arm
+     * `map`) — filtering lives here; there is no `where` on the
+     * projection form.
+     */
+    readonly map: (row: Record<string, unknown>) => TRow | null | undefined;
+}
+/**
+ * One join leg of a projection MV. Discriminated by the presence of
+ * `collect` (reverse leg) vs `field` (forward leg); `as` aliases must
+ * be unique across legs and non-empty.
+ *
+ * - **Forward FK leg** — identical shape + machinery as
+ *   {@link UnionArmJoin} / `Query.join()`: resolves a `ref()`-declared
+ *   FK on the projection source into an attached right-side record
+ *   (record | null) under `as`.
+ * - **Reverse "collect" leg** — every row of `collect` whose `on`
+ *   field references the primary record's id, attached as a
+ *   possibly-empty ARRAY under `as`. `on` must carry a `ref()`
+ *   declared on the `collect` collection targeting the projection
+ *   `source` — checked at first materialization (parity with
+ *   join-time ref errors). `maxRows` here is a PER-PRIMARY-ROW
+ *   fan-out ceiling (default: the join default); exceeding it throws
+ *   `JoinTooLargeError`.
+ */
+export type ProjectionJoinLeg = {
+    /** FK field on the projection source (must have a `ref()` declared). */
+    readonly field: string;
+    /** Alias under which the resolved right-side record attaches. */
+    readonly as: string;
+    /** Per-side row ceiling override. `undefined` → the join default. */
+    readonly maxRows?: number;
+    /** Planner strategy override. `undefined` → auto-select. */
+    readonly strategy?: JoinStrategy;
+} | {
+    /** Sibling collection to collect from. */
+    readonly collect: string;
+    /** FK field on `collect` (`ref()` targeting the projection source required). */
+    readonly on: string;
+    /** Alias under which the collected array attaches. */
+    readonly as: string;
+    /** Per-primary-row fan-out ceiling. `undefined` → the join default. */
+    readonly maxRows?: number;
+};
+/**
+ * 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>>;
+    /**
+     * Projection-form registration (#810): one output row per primary
+     * record of `projection.source`, enriched with forward FK legs and
+     * reverse one-to-many "collect" legs before `projection.map` shapes
+     * the MV row. Post-map {@link groupBy} + {@link aggregate} are
+     * supported exactly as in UNION mode.
+     *
+     * Mutually exclusive with {@link query} and {@link unionSources} —
+     * a strategy must declare exactly one of the three forms.
+     * Registration throws `MaterializedViewConfigError` otherwise.
+     *
+     * Dependencies are all AUTO: `{source} ∪ forward ref() targets ∪
+     * collect collections` (explicit {@link sources} remains additive).
+     * Forward targets resolve from the source collection's `ref()`
+     * declarations; those are declared by user code AFTER the vault
+     * opens (registration time), so the registry folds them into the
+     * dependency set on the first MV dispatch that finds them declared.
+     */
+    projection?: ProjectionSpec<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,28 @@
+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.
+ *
+ * Three 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.
+ *   - **projection** (#810) — declare `projection: { source, joins,
+ *     map }`; one output row per primary record, enriched with
+ *     forward FK legs and reverse "collect" legs before `map` runs.
+ *
+ * The three modes are mutually exclusive — exactly one of `query` /
+ * `unionSources` / `projection` must be set at registration time.
+ *
+ * See docs/superpowers/specs/2026-05-20-dim14-mv-v2-design.md (single-source v2),
+ * docs/superpowers/specs/2026-05-21-dim14-mv-multikey-and-union.md (UNION),
+ * and docs/superpowers/specs/2026-07-25-join-projection-mv-design.md (projection).
+ */
+export declare function withMaterializedView<TRow extends Record<string, unknown>>(spec: MaterializedViewStrategy<TRow>): MaterializedViewStrategyHandle;

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

@@ -0,0 +1,5 @@
+export { withOverlayedView } from './with-overlayed-view.js';
+export { OverlayedViewRegistry } from './registry.js';
+export { OverlayedCollection } from './virtual-collection.js';
+export type { OverlayedViewStrategy, OverlayedViewStrategyHandle, OverlayFieldMergeRule, OverlayFieldMergeMode, } from './types.js';
+export { OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, } from '../../kernel/errors.js';

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

@@ -0,0 +1,42 @@
+import type { MaterializedViewRegistry } from '../materialized-views/registry.js';
+import type { OverlayedViewStrategy } from './types.js';
+/**
+ * Vault-internal registry of overlay strategies. Resolves the base
+ * MV's `rowKey` lazily so virtual-collection writes can derive ids
+ * from the row.
+ *
+ * @internal
+ */
+export declare class OverlayedViewRegistry {
+    private readonly _byName;
+    /**
+     * Register an overlay. Validates name uniqueness, base concreteness,
+     * and overlay availability AGAINST the MV registry — overlays
+     * declared without the MV registry context skip cross-registry
+     * checks but still validate self-consistency.
+     */
+    register(spec: OverlayedViewStrategy, options: {
+        isOverlayName?: (name: string) => boolean;
+        isMVOutput?: (name: string) => boolean;
+        isKnownCollection?: (name: string) => boolean;
+    }): void;
+    byName(name: string): OverlayedViewStrategy | undefined;
+    /** All overlay virtual names. */
+    names(): ReadonlySet<string>;
+    isOverlay(name: string): boolean;
+    /**
+     * All registered overlay strategies as a flat array.
+     * Each strategy carries `name`, `base`, and `overlay` fields that
+     * `describeOverlays()` in the introspection walker reads directly.
+     *
+     * Used by `dumpSchema()` to populate the `overlayViews` map.
+     */
+    all(): ReadonlyArray<OverlayedViewStrategy>;
+    /**
+     * Resolve the `rowKey` function for an overlay's base MV. Returns
+     * `undefined` if the base isn't an MV (raw source collection) or
+     * if the MV registry isn't supplied. Used by the virtual-collection
+     * proxy to derive ids from `put(record)` calls.
+     */
+    resolveBaseRowKey(name: string, mvRegistry: MaterializedViewRegistry | null): ((row: Record<string, unknown>) => string) | undefined;
+}