@noy-db/hub 0.3.0-pre.8 → 0.3.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,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;

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;
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Read-shadow overlay primitive. Binds an MV's read-only base output
+ * to a separate user-writable overlay collection; reads merge via a
+ * single shadow predicate, writes route to the overlay.
+ *
+ * v2 ships the read-shadow variant only — arbitrary `mergePolicy`
+ * callbacks are deferred to v3.
+ */
+export interface OverlayedViewStrategy {
+    /**
+     * Virtual collection name. `vault.collection(name)` returns a
+     * proxy that merges `base` and `overlay` per the shadow rule.
+     * Writes to the proxy route to the `overlay` collection. The name
+     * must be unique within the vault — collisions with MV outputs or
+     * concrete source collections throw `OverlayNameCollisionError` at
+     * vault open.
+     */
+    name: string;
+    /**
+     * The collection providing the default rows. Typically an MV's
+     * output collection. Must be a CONCRETE collection (a real source
+     * or an MV output) — not itself another overlay's virtual name.
+     * Multi-overlay stacking is a v3 non-goal; the constraint is
+     * enforced at vault open via `OverlayBaseIsVirtualError`.
+     */
+    base: string;
+    /**
+     * User-writable collection that carries overrides. Must be a real,
+     * vault-known collection that is NOT an MV-output collection. The
+     * overlay's `withGuard` / `withDerivation` registrations apply to
+     * direct writes; the virtual layer's `put(record)` also flows
+     * through the overlay's normal write pipeline.
+     */
+    overlay: string;
+    /**
+     * Single-field shadow predicate. When `overlay[shadowField] ===
+     * shadowValue` for a given id, virtual-collection reads of that id
+     * return the overlay row; otherwise reads return the base row.
+     *
+     * Niwat's canonical example: `dataStatus === 'override'` flips a
+     * row into operator-controlled mode.
+     *
+     * No callback merge, no priority lattice, no field-level merge —
+     * v2 stays explicitly narrow.
+     */
+    shadowField: string;
+    shadowValue: unknown;
+    /**
+     * Optional field-level merge mode. When present, a
+     * row whose `shadowField` does NOT equal `shadowValue` is no longer
+     * forced all-base: the rules below let an intermediate status pull a
+     * declared subset of fields from the overlay while every other field
+     * still comes from the base row.
+     *
+     * Absent `mergeMode` preserves the original binary behaviour
+     * exactly — overlay wins entirely iff `shadowField === shadowValue`,
+     * otherwise base wins.
+     */
+    mergeMode?: OverlayFieldMergeMode;
+}
+/**
+ * One field-level merge rule. When the overlay row's `shadowField`
+ * equals `whenStatus`, the merged row takes `overlayFields` from the
+ * overlay and every other field from the base row.
+ *
+ * Always include `shadowField` in `overlayFields` so the status value
+ * itself propagates to the merged read (otherwise the merged row would
+ * carry the base's status, which is usually `undefined`).
+ */
+export interface OverlayFieldMergeRule {
+    /** The `overlay[shadowField]` value this rule matches. */
+    readonly whenStatus: unknown;
+    /**
+     * Field names pulled from the overlay row when this rule matches.
+     * Fields absent on the overlay row are skipped (base value kept).
+     */
+    readonly overlayFields: readonly string[];
+}
+/**
+ * Field-level merge configuration. `rules` are evaluated in
+ * declaration order and the FIRST rule whose `whenStatus` matches the
+ * overlay's `shadowField` wins; later rules are not consulted.
+ *
+ * The binary shadow check (`shadowField === shadowValue` → overlay
+ * wins entirely) is always the implicit, highest-priority rule applied
+ * BEFORE any `rules` entry, so adding `mergeMode` never changes the
+ * full-override path.
+ */
+export interface OverlayFieldMergeMode {
+    readonly kind: 'field-merge';
+    readonly rules: readonly OverlayFieldMergeRule[];
+}
+/** Returned by `withOverlayedView()` and consumed by `createNoydb`. */
+export interface OverlayedViewStrategyHandle {
+    readonly __noydb_strategy: 'overlayed-view';
+    readonly spec: OverlayedViewStrategy;
+}