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

package/dist/with-formula/derivations/types.d.ts

@@ -0,0 +1,248 @@
+import type { ReadOnlyVaultFacade } from '../../with-audit/guards/types.js';
+/**
+ * Runtime context handed to `derive(source, ctx)`. Mirrors `GuardContext`'s
+ * narrow shape: read-only vault access, no write capability, no
+ * transaction handle. Determinism is the consumer's responsibility — the
+ * strategy hash includes `derive.toString()`, so the source string fixes
+ * the function's inputs; whatever sibling reads `derive` performs must
+ * yield the same outputs for the same source.
+ */
+export interface DerivationContext {
+    vault: ReadOnlyVaultFacade;
+}
+/**
+ * Metadata that travels inside the `_data` payload of a derived record.
+ * Lives in encrypted payload, not in the unencrypted envelope — the
+ * storage backend cannot infer the derivation graph from listing.
+ */
+export interface DerivedFromMeta {
+    /** Source collection name. */
+    readonly source: string;
+    /** Source record id. */
+    readonly sourceId: string;
+    /** `_v` of the source at derivation time. */
+    readonly sourceVersion: number;
+    /** ISO timestamp when this output was derived. */
+    readonly derivedAt: string;
+    /**
+     * SHA-256 of (source + outputs map keys + derive function source).
+     * Changes when the strategy changes → forces `vault.deriveAll` to
+     * recompute on next visit.
+     */
+    readonly strategyHash: string;
+}
+/** Record-shape output — one source row produces (optionally) one output row at the source's id. */
+export interface RecordOutputSpec {
+    shape: 'record';
+    collection: string;
+    /**
+     * When `true`, the `derive` function may return `null` (or
+     * `undefined`) for this output key. The executor interprets that as
+     * "no output for this invocation": a previously-emitted output at
+     * the same id is deleted (mirroring the empty-group / empty-aggregate
+     * semantics for empty groups); a never-emitted output is a silent
+     * no-op. When `false` (default), returning `null` throws
+     * `DerivationOutputShapeError` — same as v1.
+     */
+    optional?: boolean;
+    /**
+     * Field-level provenance for a **self-write** output — an output
+     * whose `collection` equals the strategy's `source`, used by
+     * reverse-denormalization (`triggerBy`) to patch a denormalized field
+     * back onto the source record.
+     *
+     * `denorm` names the ONLY top-level fields the derivation owns on that
+     * record. The engine merges just those fields from the `derive` return
+     * value onto the current stored record (`{ ...current, ...pick(out, denorm) }`)
+     * — the rest of the user's record is never clobbered by a stale snapshot.
+     * The whole-record `_derivedFrom` provenance tag is NOT applied (the
+     * record stays user-owned); the derivation only claims `denorm`.
+     *
+     * Cycle break is value-level: if the patch changes nothing, no write is
+     * issued — so the self-write that re-fires the source-path derivation
+     * terminates after one idempotent pass.
+     *
+     * REQUIRED when `collection === source` (validated at construction);
+     * ignored for outputs to a different collection.
+     */
+    denorm?: readonly string[];
+}
+/**
+ * Array-shape output — one source row produces a variable-length
+ * list of output rows, each with its own id (from the `key` extractor).
+ *
+ * On every source-row change, the dispatcher diffs the previously
+ * emitted key set against the new one: removed keys are deleted via
+ * `_internalDelete`, new and unchanged keys are upserted via
+ * `Collection.put`. Strict-mode rollback is preserved via the existing
+ * `_executed` tracking.
+ *
+ * Storage of the per-source-row key set lives at
+ * `_meta/derivations-fanout/<source>/<sourceId>/<outputKey>` as a
+ * plain JSON sidecar — keeps dispatch cost O(1) per source row.
+ *
+ * **Slice 1 limitation**: only `lifecycle: 'eager'` is supported.
+ * Registering an array-shape output with `lifecycle: 'lazy'` throws
+ * at `withDerivation` construction time.
+ */
+export interface ArrayOutputSpec {
+    shape: 'array';
+    collection: string;
+    /**
+     * Stable identity extractor for each derived row. Called on every
+     * row returned by `derive`. The string MUST be unique within a
+     * single invocation — duplicate keys throw
+     * `DerivationOutputShapeError`.
+     *
+     * Type is intentionally `(out: Record<string, unknown>) => string`
+     * (not generic) because OutputSpec is type-erased at the registry
+     * level. Strategy-level inference still produces typed `out`
+     * through the strategy's `outputs` map.
+     */
+    key: (output: Record<string, unknown>) => string;
+    /**
+     * Cap on derived rows per source-row invocation. Defaults to 64.
+     * Raise for carry-forward cases (e.g. monthly expansion of
+     * multi-year contracts). Exceeding the cap throws
+     * `DerivationCapExceededError` BEFORE any writes — partial fanout
+     * is never persisted.
+     */
+    maxFanout?: number;
+}
+/** Discriminated union — record + array. */
+export type OutputSpec = RecordOutputSpec | ArrayOutputSpec;
+/**
+ * Registration shape passed to `withDerivation()`.
+ *
+ * @typeParam TSource - the source record type
+ * @typeParam TOutputs - map of output-key → output record type. An output
+ *   value may be a single record, or — for `shape: 'array'` outputs — an
+ *   array of records (the fanout sidecar upserts/deletes each row).
+ */
+export interface DerivationStrategy<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>> {
+    /** Source collection name. */
+    source: string;
+    /**
+     * Additional collections whose writes ALSO re-fire this derivation.
+     * By default only writes to the single declared
+     * `source` re-trigger a derivation; a `derive` that reads sibling
+     * collections via `ctx.vault` therefore goes stale when those
+     * siblings change. Declare those sibling collections here to wire
+     * them as extra triggers.
+     *
+     * **SAME-ID assumption (load-bearing):** when a write lands on one of
+     * these declared collections, the derivation re-fires with the
+     * PRIMARY `source` record read at the SAME id as the written record
+     * — NOT the written sibling record itself. If no primary `source`
+     * record exists at that id, the re-fire is a silent no-op (no throw,
+     * no output mutation). Model your collections so the sibling and the
+     * primary share an id (the common money/accounting case: an
+     * `allocations` row and its `payments`/`bills` keyed by the same id),
+     * or trigger off a collection you control the id-space of.
+     *
+     * Declared collections participate in cycle detection and are indexed
+     * in the registry's `_bySource` exactly like `source`, so a sibling
+     * that is also a derivation output forms a detectable cycle.
+     *
+     * Each entry must be a non-empty string and must not equal `source`
+     * (validated at `withDerivation()` construction time).
+     */
+    sources?: ReadonlyArray<string>;
+    /**
+     * Foreign-key-keyed triggers for reverse-denormalization. Unlike
+     * `sources[]` (which re-fires at the SAME id), a `triggerBy` entry fans a
+     * write to a PARENT collection OUT to every source record whose FK matches
+     * the written parent's id.
+     *
+     * `{ collection, on }`: a write to `collection` (the parent, e.g.
+     * `'buyers'`) re-fires this derivation once per source record where
+     * `source[on] === writtenParentId` (`on` is the FK field ON the source,
+     * e.g. `'buyerId'`). The matched source record — not the parent — is
+     * passed to `derive`.
+     *
+     * Typical use: keep a denormalized field on the source in sync with a
+     * parent change (a buyer rename → refresh `buyerName` on all their sales),
+     * via a self-write output (`collection === source`) declaring `denorm`.
+     *
+     * Fan-out runs through `ctx.vault.collection(source).query().where(on,'==',id)`,
+     * which uses the FK index when the source declares `withIndexing()` on
+     * `on` (O(children)) and otherwise scans (O(N) — fine for small child
+     * sets). Set `maxFanout` as a safety rail; exceeding it throws
+     * `DerivationCapExceededError` before any write. `triggerBy` collections
+     * participate in cycle detection like `source`/`sources`.
+     *
+     * Each `collection` must be non-empty and not equal `source`; `on` must
+     * be a non-empty field name (validated at construction).
+     */
+    triggerBy?: ReadonlyArray<{
+        collection: string;
+        on: string;
+        maxFanout?: number;
+    }>;
+    /**
+     * @internal — set by `withRollup()`. Marks this strategy as
+     * an aggregate-onto-parent rollup: a write OR delete of a `from` (child)
+     * record recomputes `compute(children where child[key] === parentId)` and
+     * patches it onto `source[field]` of the parent at `parentId` (= child[key]).
+     * `source` is the parent (`into`) collection; the synthetic self-write
+     * output carries `denorm: [field]`. Dispatch handles rollup specially (it
+     * does not run the executor). Eager-only in this slice.
+     */
+    rollup?: {
+        readonly from: string;
+        readonly key: string;
+        readonly field: string;
+        readonly compute: (children: any[]) => unknown;
+    };
+    /** v1: only deterministic derivations supported. */
+    deterministic: true;
+    /**
+     * Output declarations keyed by name. The `derive` function's return
+     * value must have the same keys.
+     */
+    outputs: {
+        [K in keyof TOutputs]: OutputSpec;
+    };
+    /**
+     * Pure function from source to outputs. Runs on plaintext, after DEK
+     * unwrap. Returns a map of named outputs. Each output is encrypted +
+     * stored via the existing `Collection.put` pipeline.
+     *
+     * `ctx.vault` is the same `ReadOnlyVaultFacade` guards see — fetch
+     * sibling records via `ctx.vault.collection<T>(name).get(id)` /
+     * `.list()` / `.query()`. The vault accessor is read-only; there is
+     * no path to a writer from `ctx`.
+     *
+     * **Per-output omission (runtime-supported):** returning `null` or
+     * `undefined` for an individual output key is handled at runtime via
+     * the `optional: true` flag on the output's `RecordOutputSpec` —
+     * the executor deletes any previously-emitted output at that id, or
+     * silently no-ops if none exists. For `shape: 'array'` outputs, null
+     * / undefined is treated as an empty array (clears all prior rows for
+     * that source). The *top-level* return must always be a `TOutputs`
+     * object; returning `null` for the whole result is not supported.
+     * (MV `unionSources` map drop-row is the analogous feature for
+     * materialized views.)
+     */
+    derive: (source: TSource, ctx: DerivationContext) => Promise<TOutputs> | TOutputs;
+    /**
+     * `'eager'` runs `derive` synchronously inside the source-write
+     * transaction. `'lazy'` marks outputs stale on source-change and
+     * derives on first read.
+     */
+    lifecycle: 'eager' | 'lazy' | {
+        mode: 'eager' | 'lazy';
+        maxDepth?: number;
+    };
+    /**
+     * `true` = any output failure rolls back the source write (only with
+     * `withTransactions`). `false` = isolate per-output failure, log,
+     * continue. Default `false`.
+     */
+    strict?: boolean;
+}
+/** Returned by `withDerivation()` and consumed by `createNoydb`. */
+export interface DerivationStrategyHandle {
+    readonly __noydb_strategy: 'derivation';
+    readonly spec: DerivationStrategy<any, any>;
+}

package/dist/with-formula/derivations/with-derivation.d.ts

@@ -0,0 +1,10 @@
+import type { DerivationStrategy, DerivationStrategyHandle } from './types.js';
+/**
+ * Register a deterministic derivation: one source collection → one or
+ * more typed outputs, computed by the user's `derive` function on
+ * plaintext after DEK unwrap. Outputs are encrypted with the same DEK
+ * as the source and written via the standard `Collection.put` path.
+ *
+ * See docs/superpowers/specs/2026-05-01-dim14-derivation-v1-design.md.
+ */
+export declare function withDerivation<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>>(spec: DerivationStrategy<TSource, TOutputs>): DerivationStrategyHandle;

package/dist/with-formula/derivations/with-rollup.d.ts

@@ -0,0 +1,34 @@
+import type { DerivationStrategyHandle } from './types.js';
+/**
+ * `withRollup` — aggregate many child records onto a single field of their
+ * parent. The reverse of a join: instead of reading children
+ * on demand, the parent carries a maintained summary.
+ *
+ * ```ts
+ * withRollup<Sale, Buyer>({
+ *   from: 'sales',          // child collection (the trigger)
+ *   key: 'buyerId',         // FK on the child → parent id
+ *   into: 'buyers',         // parent collection
+ *   field: 'revenueByYear', // field on the parent to maintain
+ *   compute: (sales) => groupSumByYear(sales, 'total'),
+ * })
+ * ```
+ *
+ * On every write OR delete of a `from` record, the parent at id `child[key]`
+ * is recomputed: `compute(allChildren where child[key] === parentId)` is
+ * patched onto `parent[field]`. A parent write also recomputes its own
+ * aggregate (so a parent created after its children still fills in). Only the
+ * `field` is touched — the rest of the parent record is never clobbered — and
+ * a value-equality guard suppresses no-op writes. The aggregate is gap-free
+ * with respect to child inserts, updates, and deletes.
+ *
+ * Desugars to a `withDerivation` strategy carrying a `rollup` marker; dispatch
+ * handles it without invoking the executor. Eager-only in this slice.
+ */
+export declare function withRollup<TChild extends Record<string, unknown> = Record<string, unknown>, TParent extends Record<string, unknown> = Record<string, unknown>>(config: {
+    from: string;
+    key: keyof TChild & string;
+    into: string;
+    field: keyof TParent & string;
+    compute: (children: TChild[]) => unknown;
+}): DerivationStrategyHandle;

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,80 @@
+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;
+    /** #782/#785 — `outputCollection:id` entries from the tombstone pass whose ownership stamp
+     *  couldn't be decoded under the collection's default DEK (undecodable, mirroring
+     *  `invalidateMVAtRest`'s #776 posture) — ownership UNCONFIRMED. Only populated when
+     *  `onEmpty: 'delete'`. */
+    residueUndecodable: string[];
+    /** #782/#785 — `outputCollection:id` entries that decoded, stamp-matched this MV, but
+     *  `_internalDelete` declined (the #718 tier-elevation gate) — ownership CONFIRMED, a real
+     *  silent survival, surfaced rather than dropped. Only populated when `onEmpty: 'delete'`. */
+    residueDeclined: string[];
+}
+/**
+ * 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;