@noy-db/hub 0.1.0-pre.9 → 0.2.0-pre.10

package/dist/{index-DJTf9yxn.d.ts → index-B8bjExET.d.cts}

@@ -1,5 +1,5 @@
-import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-SBHmi6D0.js';
-import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery } from './strategy-D-SrOLCl.js';
+import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-Bt5ft-9c.cjs';
+import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery, h as GroupedQueryN } from './strategy-CT2LCKAX.cjs';
 
 /**
  * All NOYDB error classes — a single import surface for `catch` blocks and
@@ -29,11 +29,15 @@ import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as Aggr
  *       │    ├─ ValidationError        — application-level guard failed
  *       │    └─ SchemaValidationError  — Standard Schema v1 rejection
  *       ├─ Query errors
- *       │    ├─ JoinTooLargeError      — join row ceiling exceeded
- *       │    ├─ DanglingReferenceError — strict ref() points at nothing
- *       │    ├─ GroupCardinalityError  — groupBy bucket cap exceeded
- *       │    ├─ IndexRequiredError      — lazy-mode query touches unindexed field
- *       │    └─ IndexWriteFailureError       — index side-car put/delete failed post-main
+ *       │    ├─ JoinTooLargeError                — join row ceiling exceeded
+ *       │    ├─ CrossJoinTooLargeError            — cross-join row ceiling exceeded
+ *       │    ├─ CrossJoinSourceUnknownError       — target collection not in vault
+ *       │    ├─ DanglingReferenceError            — strict ref() points at nothing
+ *       │    ├─ GroupCardinalityError             — groupBy bucket cap exceeded
+ *       │    ├─ IndexRequiredError                — lazy-mode query touches unindexed field
+ *       │    ├─ IndexWriteFailureError            — index side-car put/delete failed post-main
+ *       │    ├─ UniqueConstraintError             — duplicate value on unique index
+ *       │    └─ UnsupportedIndexOptionError       — unique+lazy or unique+crdt at registration
  *       ├─ i18n / Dictionary errors
  *       │    ├─ ReservedCollectionNameError
  *       │    ├─ DictKeyMissingError
@@ -46,10 +50,12 @@ import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as Aggr
  *       │    └─ BackupCorruptedError   — envelope hash mismatch in dump
  *       ├─ Bundle errors
  *       │    └─ BundleIntegrityError   — .noydb body sha256 mismatch
- *       └─ Session errors
- *            ├─ SessionExpiredError
- *            ├─ SessionNotFoundError
- *            └─ SessionPolicyError
+ *       ├─ Session errors
+ *       │    ├─ SessionExpiredError
+ *       │    ├─ SessionNotFoundError
+ *       │    └─ SessionPolicyError
+ *       └─ Snapshot errors
+ *            └─ SnapshotNotFoundError  — snapshot key absent from snapshot store
  * ```
  *
  * ## Catching all NOYDB errors
@@ -116,6 +122,26 @@ declare class TamperedError extends NoydbError {
 declare class InvalidKeyError extends NoydbError {
     constructor(message?: string);
 }
+/**
+ * Thrown when a keyring's wrapped-DEK set unwraps partially — at least
+ * one DEK succeeds (proving the KEK is correct) but at least one fails.
+ * The passphrase is right; the failed entries are corrupted.
+ *
+ * This is distinct from {@link InvalidKeyError} so that
+ * `NoydbOptions.onInvalidKey: 'reset'` does NOT fire — resetting on
+ * partial corruption would destroy the still-valid DEKs and the data
+ * they protect, which is silent data loss in response to a feature
+ * designed for stale-credential recovery.
+ */
+declare class KeyringCorruptError extends NoydbError {
+    readonly failedCollections: readonly string[];
+    readonly intactCount: number;
+    constructor(opts: {
+        failedCollections: readonly string[];
+        intactCount: number;
+        message?: string;
+    });
+}
 /**
  * Thrown when the authenticated user does not have a DEK for the requested
  * collection — i.e. the collection is not in their keyring at all.
@@ -229,7 +255,7 @@ declare class KeyringExpiredError extends NoydbError {
 }
 /**
  * Thrown when an `@noy-db/as-*` import is attempted but the invoking
- * keyring lacks the required import-capability bit (issue ).
+ * keyring lacks the required import-capability bit.
  *
  * - `tier: 'plaintext'` — a plaintext-tier import (`as-csv`, `as-json`,
  *   `as-ndjson`, `as-zip`, …) was attempted but the keyring's
@@ -327,6 +353,64 @@ declare class PeriodClosedError extends NoydbError {
     readonly recordTs: string;
     constructor(periodName: string, endDate: string, recordTs: string);
 }
+/**
+ * Thrown when a `put()` or `delete()` is rejected by a guard's `check`
+ * function. The `reason` is the message the guard supplied — typically a
+ * short business description (e.g. "invoice is issued"). The full
+ * collection + id are surfaced so audit UIs can link back to the record.
+ */
+declare class RecordLockedError extends NoydbError {
+    readonly collection: string;
+    readonly id: string;
+    readonly reason: string;
+    constructor(collection: string, id: string, reason: string);
+}
+/**
+ * Thrown when a `put()` changes one or more fields that are frozen by a
+ * `frozenFields` guard. The `fields` list contains the specific paths
+ * that were detected as changed.
+ */
+declare class FieldFrozenError extends NoydbError {
+    readonly collection: string;
+    readonly id: string;
+    readonly fields: readonly string[];
+    constructor(collection: string, id: string, fields: readonly string[]);
+}
+/**
+ * Thrown by an amendment invariant when the proposed change-set violates
+ * the declared business rule (e.g. disbursement total not preserved).
+ * Triggers a full transaction rollback via the existing revert pass.
+ */
+declare class InvariantError extends NoydbError {
+    constructor(message: string);
+}
+/**
+ * Thrown at `withTransactions({ amendment: true })` open if the caller's
+ * role is not in the guard's allowed amendment roles. Fail-fast: thrown
+ * before any writes are attempted.
+ */
+declare class AmendmentForbiddenError extends NoydbError {
+    readonly userId: string;
+    readonly role: string;
+    constructor(userId: string, role: string);
+}
+/**
+ * Thrown by `listUsersWithEnvelopes` when the vault's user directory
+ * has been disabled (via `db.setDirectoryEnabled(vault, false)`) and
+ * the caller's role is neither `owner` nor `admin`. Owner/admin can
+ * still enumerate users — the toggle is a UX privacy switch, not a
+ * security boundary.
+ *
+ * Honest caveat: this is a UX flag, not a privacy guarantee. The
+ * envelope ciphertext is still in the store, the keyring file is
+ * still listed at `_keyring/*`, and anyone with direct store read
+ * access can count keyrings without going through the hub. See
+ * `docs/subsystems/user-envelope.md` → "Directory visibility".
+ */
+declare class DirectoryDisabledError extends NoydbError {
+    readonly vault: string;
+    constructor(vault: string);
+}
 /**
  * Thrown when a user tries to act at a tier they are not cleared for.
  *
@@ -480,6 +564,30 @@ declare class SchemaValidationError extends NoydbError {
     readonly direction: 'input' | 'output';
     constructor(message: string, issues: readonly unknown[], direction: 'input' | 'output');
 }
+/** Base for schema-evolution strategy rejections. */
+declare class SchemaUpdateError extends NoydbError {
+    constructor(code: string, message: string);
+}
+/** A non-additive schema change was rejected by the `additiveOnly()` strategy. */
+declare class NonAdditiveSchemaChangeError extends SchemaUpdateError {
+    constructor(message: string);
+}
+/** A schema change was rejected by the `lockSchema()` strategy. */
+declare class SchemaLockedError extends SchemaUpdateError {
+    constructor(message: string);
+}
+/** Write attempted while a schema cutover fence is up (draining/migrating, or this collection has a pending cutover). */
+declare class SchemaFenceError extends SchemaUpdateError {
+    constructor(message: string);
+}
+/** Write attempted by a client whose generation snapshot is behind the live fence — reload required. */
+declare class MigrationRequiredError extends SchemaUpdateError {
+    constructor(message: string);
+}
+/** A coordinated cutover timed out waiting for active clients to quiesce. */
+declare class QuiesceTimeoutError extends SchemaUpdateError {
+    constructor(message: string);
+}
 /**
  * Thrown when `.groupBy().aggregate()` produces more than the hard
  * cardinality cap (default 100_000 groups)..
@@ -534,6 +642,51 @@ declare class IndexRequiredError extends NoydbError {
         missingFields: readonly string[];
     });
 }
+/**
+ * Thrown by `Collection.put()` when writing a record would violate a
+ * unique-index constraint — the same field value (or composite field
+ * tuple) is already held by a *different* record id in the collection.
+ *
+ * Properties:
+ * - `collection` — name of the collection the write was targeting
+ * - `recordId` — the id of the record being written (the would-be violator)
+ * - `fields` — the constrained field(s), e.g. `['taxId']` or `['workerId','employerEntityId']`
+ * - `conflictingId` — the id of the record already holding the value
+ *
+ * Null-distinct semantics: if any constrained field is `null`/`undefined`,
+ * the row is exempt (the constraint does not fire). This matches standard
+ * SQL NULL-distinct behavior.
+ */
+declare class UniqueConstraintError extends NoydbError {
+    readonly collection: string;
+    readonly recordId: string;
+    readonly fields: readonly string[];
+    readonly conflictingId: string;
+    constructor(collection: string, recordId: string, fields: readonly string[], conflictingId: string);
+}
+/**
+ * Thrown at collection registration when an index option is declared that
+ * is incompatible with the collection's operating mode.
+ *
+ * Currently covers two cases:
+ * - `unique: true` on a lazy-mode (`prefetch: false`) collection — lazy mode
+ *   does not pre-load all records, so an in-memory uniqueness map cannot be
+ *   maintained reliably.
+ * - `unique: true` on a CRDT collection (`crdt: 'lww-map' | 'rga' | 'yjs'`) —
+ *   CRDT put() short-circuits the unique-constraint check, so enforcement would
+ *   silently not fire.
+ *
+ * Both cases are caught eagerly at `vault.collection()` time so the developer
+ * sees the incompatibility immediately rather than shipping silently-ignored
+ * constraints.
+ *
+ * The `option` field names the incompatible option (`'unique'`) so catch blocks
+ * can pattern-match without inspecting the error message.
+ */
+declare class UnsupportedIndexOptionError extends NoydbError {
+    readonly option: string;
+    constructor(option: string, message: string);
+}
 /**
  * Thrown (or surfaced via the `index:write-partial` event) when one or more
  * per-indexed-field side-car writes fail after the main record write has
@@ -584,6 +737,33 @@ declare class IndexWriteFailureError extends NoydbError {
 declare class BundleIntegrityError extends NoydbError {
     constructor(message: string);
 }
+/**
+ * Thrown by `readNoydbBundle` when the bundle carries
+ * sealed per-user passphrases but no supplied `SealingKeyProvider`
+ * has a `.id` (= `pid`) matching the sealed entry's `pid`.
+ *
+ * Carries the failing pid + the user id so the recipient can
+ * surface an actionable prompt:
+ *
+ * ```
+ * BundleSealMismatchError: bundle carries sealed passphrase for user "alice"
+ *   under provider "macos-keychain:com.acme.app/alice@acme.example",
+ *   but no registered provider matches that pid.
+ * ```
+ *
+ * Three resolution paths the message names (per foundation §11.9.4):
+ *
+ * 1. Configure a provider matching the pid and retry import.
+ * 2. Pass `attemptUnsealAcrossProviders: true` to try each
+ *    registered provider regardless of pid.
+ * 3. Inspect without unsealing — pass no `sealingProviders` to
+ *    receive the sealed entries unmodified for offline analysis.
+ */
+declare class BundleSealMismatchError extends NoydbError {
+    readonly userId: string;
+    readonly pid: string;
+    constructor(userId: string, pid: string);
+}
 /**
  * Thrown when `vault.collection()` is called with a name that is
  * reserved for NOYDB internal use (any name starting with `_dict_`).
@@ -663,6 +843,26 @@ declare class LocaleNotSpecifiedError extends NoydbError {
     readonly field: string;
     constructor(field: string, message?: string);
 }
+/**
+ * Thrown at write time when an `i18nText` slot's value contains
+ * characters outside the script set allowed for that locale, and the
+ * field's `onScriptViolation` policy is `'reject'` (the default).
+ *
+ * Distinct from {@link MissingTranslationError} (write-shape) and
+ * {@link LocaleNotSpecifiedError} (read-hole) so callers can tell a
+ * wrong-script value from a missing one.
+ */
+declare class ScriptViolationError extends NoydbError {
+    /** The field whose value violated its script constraint. */
+    readonly field: string;
+    /** The locale slot (e.g. `'en'`) that was checked. */
+    readonly locale: string;
+    /** The Unicode scripts allowed for this slot. */
+    readonly expected: readonly string[];
+    /** A short sample of the offending characters, for diagnostics. */
+    readonly sample: string;
+    constructor(field: string, locale: string, expected: readonly string[], sample: string, message?: string);
+}
 /**
  * Thrown when a collection has an `i18nText` field with
  * `autoTranslate: true` but no `plaintextTranslator` was configured
@@ -707,6 +907,34 @@ declare class BackupCorruptedError extends NoydbError {
     readonly id: string;
     constructor(collection: string, id: string, message: string);
 }
+/**
+ * Thrown by partition-extraction primitives when the
+ * transitive-closure walk fails — e.g. the FK graph is deeper than
+ * `maxDepth`, signalling a runaway or unexpectedly cyclic graph.
+ */
+declare class PartitionExtractionError extends NoydbError {
+    constructor(message: string);
+}
+/**
+ * Thrown by `adoptPartition` when the transfer seal can't be
+ * opened — a wrong/short transfer key (AES-GCM auth-tag failure) or a
+ * malformed sealed payload.
+ */
+declare class TransferSealError extends NoydbError {
+    constructor(message: string);
+}
+/**
+ * Thrown when an adoption-lifecycle precondition fails — re-adopting a
+ * partition already consumed in this store, or owner-creation on a
+ * vault that isn't in the adopted-unowned state.
+ */
+declare class AdoptionStateError extends NoydbError {
+    constructor(message: string);
+}
+/** Document-attestation failures: undeclared field-schema, non-owner issue, missing field, signer failure. */
+declare class AttestationError extends NoydbError {
+    constructor(message: string);
+}
 /**
  * Thrown by `resolveSession()` when the session token's `expiresAt`
  * timestamp is in the past. The session key is also removed from the
@@ -782,6 +1010,34 @@ declare class JoinTooLargeError extends NoydbError {
         message: string;
     });
 }
+/**
+ * Thrown by `.crossJoin()` when the cumulative cartesian product (or lateral
+ * filtered count) exceeds the configured ceiling. Check before allocating.
+ * Mirrors the pattern of `JoinTooLargeError` and the `.join()` row ceiling.
+ *
+ * @see CrossJoinClause.maxRows — per-clause override
+ * @see DEFAULT_CROSS_JOIN_MAX_ROWS — package default (50_000)
+ */
+declare class CrossJoinTooLargeError extends NoydbError {
+    readonly target: string;
+    readonly expected: number;
+    readonly limit: number;
+    constructor(opts: {
+        target: string;
+        expected: number;
+        limit: number;
+    });
+}
+/**
+ * Thrown at cross-join execution time when the target collection is not
+ * reachable from the current vault. The left collection is included in the
+ * message for context.
+ */
+declare class CrossJoinSourceUnknownError extends NoydbError {
+    readonly target: string;
+    readonly leftCollection: string;
+    constructor(target: string, leftCollection: string);
+}
 /**
  * Thrown by `.join()` in strict `ref()` mode when a left-side record
  * points at a right-side id that does not exist in the target
@@ -830,6 +1086,169 @@ declare class PathEscapeError extends NoydbError {
         targetDir: string;
     });
 }
+/**
+ * Thrown at vault open if the derivation graph contains a cycle.
+ * `path` is the offending chain (e.g. `['a', 'b', 'c', 'a']`).
+ */
+declare class DerivationCycleError extends NoydbError {
+    readonly path: readonly string[];
+    constructor(path: readonly string[]);
+}
+/**
+ * Thrown when a cascade of source → output → source → … exceeds the
+ * configured `maxDepth` (default 5).
+ */
+declare class DerivationDepthError extends NoydbError {
+    readonly limit: number;
+    readonly attempted: number;
+    constructor(limit: number, attempted: number);
+}
+/**
+ * Thrown at registration if a `withDerivation` strategy references an
+ * output `collection` that isn't otherwise declared (no schema, no use
+ * elsewhere). Surfacing this early catches typos in collection names.
+ */
+declare class DerivationOutputUnknownError extends NoydbError {
+    readonly collection: string;
+    constructor(collection: string);
+}
+/**
+ * Thrown when the user's `derive` function returns a value that doesn't
+ * match the declared output spec (e.g. wrong shape, wrong key set).
+ */
+declare class DerivationOutputShapeError extends NoydbError {
+    readonly outputKey: string;
+    constructor(outputKey: string, detail: string);
+}
+/**
+ * Thrown by array-shape derivations when the `derive` function
+ * returns more rows than the output's `maxFanout` cap. The cap exists
+ * to keep dispatch cost bounded — without it a single source-row
+ * update could fan out to thousands of derived rows, dominating the
+ * write path.
+ *
+ * Defaults to `maxFanout: 64`. Raise on the output spec for
+ * carry-forward expansion cases (e.g. monthly rows across multi-year
+ * contracts).
+ */
+declare class DerivationCapExceededError extends NoydbError {
+    readonly outputKey: string;
+    readonly returned: number;
+    readonly maxFanout: number;
+    constructor(outputKey: string, returned: number, maxFanout: number);
+}
+/**
+ * Thrown at vault open if the materialized-view graph contains a
+ * cycle. `path` is the offending chain (e.g. `['a-mv', 'b-mv', 'a-mv']`).
+ * Detected by the same shared DFS that catches `DerivationCycleError`;
+ * surfaces with a distinct error type so consumers can disambiguate.
+ */
+declare class MaterializedViewCycleError extends NoydbError {
+    readonly path: readonly string[];
+    constructor(path: readonly string[]);
+}
+/**
+ * Thrown at MV registration if the query references a source
+ * collection that isn't declared on the vault. Surfacing this early
+ * catches typos in collection names.
+ */
+declare class MaterializedViewSourceUnknownError extends NoydbError {
+    readonly mvName: string;
+    readonly collection: string;
+    constructor(mvName: string, collection: string);
+}
+/**
+ * Thrown by the MV executor when a refresh produces more rows than
+ * the configured ceiling. Default ceiling is 100k rows; override
+ * per-MV via `maxRows`. Mirrors `JoinTooLargeError` /
+ * `GroupCardinalityError` from the query DSL — the explosion is
+ * detected BEFORE writes hit the store, so the source-write
+ * transaction can roll back cleanly via strict-mode.
+ */
+declare class MaterializedViewTooLargeError extends NoydbError {
+    readonly mvName: string;
+    readonly expected: number;
+    readonly limit: number;
+    constructor(mvName: string, expected: number, limit: number);
+}
+/**
+ * Thrown by `withMaterializedView()` at registration time when the
+ * strategy is structurally malformed. Distinct from
+ * `MaterializedViewSourceUnknownError` (the source list is well-formed
+ * but names a collection the vault doesn't know) and
+ * `MaterializedViewCycleError` (the source graph has a cycle): this
+ * error fires before either check, at the moment the spec is being
+ * normalized.
+ *
+ * Today the trigger cases are all about the `query` / `unionSources`
+ * dichotomy:
+ *   - both `query` and `unionSources` were set (mutually exclusive),
+ *   - neither `query` nor `unionSources` was set,
+ *   - `unionSources` has fewer than 2 arms,
+ *   - two arms in `unionSources` reference the same `collection`.
+ *
+ * The error message is prefixed with `[noy-db] withMaterializedView:`
+ * so it's grep-friendly in logs and looks consistent with the existing
+ * `ValidationError` messages from the same factory.
+ */
+declare class MaterializedViewConfigError extends NoydbError {
+    constructor(message: string);
+}
+/**
+ * Thrown at vault open when a `withOverlayedView` declaration uses
+ * another virtual-overlay name as its `base`. Multi-overlay stacking
+ * is a v2 non-goal — the shallow expansion in
+ * `QueryDependencyAnalyzer` would truncate at the inner overlay
+ * name, leaving downstream MVs silently stale.
+ */
+declare class OverlayBaseIsVirtualError extends NoydbError {
+    readonly overlayName: string;
+    readonly base: string;
+    constructor(overlayName: string, base: string);
+}
+/**
+ * Thrown at vault open when a `withOverlayedView`'s `overlay`
+ * references an unknown collection or an MV-owned collection. The
+ * overlay collection is user-writable; MV-owned collections aren't.
+ */
+declare class OverlayCollectionUnavailableError extends NoydbError {
+    readonly overlayName: string;
+    readonly overlay: string;
+    constructor(overlayName: string, overlay: string);
+}
+/**
+ * Thrown at vault open when a `withOverlayedView`'s virtual `name`
+ * collides with an MV output or a concrete source collection.
+ */
+declare class OverlayNameCollisionError extends NoydbError {
+    readonly overlayName: string;
+    constructor(overlayName: string);
+}
+/**
+ * Thrown by the virtual overlay's `put(id, record)` when the
+ * consumer-supplied `id` doesn't match `rowKey(record)`. Catches
+ * fat-finger separator typos that would otherwise silently produce
+ * orphaned overlay rows. Direct writes to the underlying overlay
+ * collection (bypass the virtual layer) skip this validation.
+ */
+declare class OverlayIdMismatchError extends NoydbError {
+    readonly actual: string;
+    readonly expected: string;
+    constructor(actual: string, expected: string);
+}
+/**
+ * Thrown when a requested snapshot version does not exist in the
+ * snapshot store — either it was never created, was pruned by the
+ * retention policy, or was deleted manually.
+ *
+ * The `version` field carries the key that was looked up so callers
+ * can surface an actionable "snapshot X not found" message without
+ * parsing the error string.
+ */
+declare class SnapshotNotFoundError extends NoydbError {
+    readonly version: string;
+    constructor(version: string);
+}
 
 /**
  * Foreign-key references — the soft-FK mechanism.
@@ -1325,6 +1744,8 @@ interface QueryPlan {
      */
     readonly joins: readonly JoinLeg[];
 }
+/** Default row ceiling for cross-join expansion. Matches JoinTooLargeError's ceiling. */
+declare const DEFAULT_CROSS_JOIN_MAX_ROWS = 50000;
 /**
  * Source of records that a query executes against.
  *
@@ -1361,12 +1782,54 @@ interface QuerySource<T> {
  * joinContext, and calling `.join()` on it throws with an actionable
  * error. See `query/join.ts` for the full design.
  */
+/**
+ * Declared deterministic predicate. Carries the consumer's
+ * stable `hash` (for function-body identity), the function itself,
+ * and is keyed by name when registered on a `Query<T>` via
+ * `_withPredicates()`.
+ */
+interface DeclaredPredicate {
+    hash: string;
+    fn: (record: unknown, ctx?: unknown) => boolean;
+}
 declare class Query<T> {
     private readonly source;
     private readonly plan;
     private readonly joinContext;
     private readonly aggregateStrategy;
-    constructor(source: QuerySource<T>, plan?: QueryPlan, joinContext?: JoinContext, aggregateStrategy?: AggregateStrategy);
+    private readonly predicates;
+    constructor(source: QuerySource<T>, plan?: QueryPlan, joinContext?: JoinContext, aggregateStrategy?: AggregateStrategy, predicates?: ReadonlyMap<string, DeclaredPredicate>);
+    /**
+     * @internal — accessor for the materialized-view dependency
+     * analyzer. Not part of the public API; consumers should use the
+     * builder methods, not inspect the plan directly.
+     */
+    _plan(): QueryPlan;
+    /**
+     * @internal — accessor for the materialized-view dependency
+     * analyzer. Returns the join resolution context (or `undefined` for
+     * queries constructed without a Collection backing).
+     */
+    _joinContext(): JoinContext | undefined;
+    /**
+     * @internal — clone this Query with a declared-predicate map
+     * attached. Used by the materialized-view registry to enable
+     * `.wherePredicate(name, ctx?)` for the MV's query callback.
+     * Consumers don't call this directly.
+     */
+    _withPredicates(predicates: ReadonlyMap<string, DeclaredPredicate>): Query<T>;
+    /**
+     * Filter by a registered deterministic predicate. Requires
+     * the Query to have been augmented with a predicates map (typically
+     * via the materialized-view registry — bare Queries constructed
+     * outside an MV throw on `.wherePredicate()`).
+     *
+     * `ctx` is an optional opaque value passed verbatim to the predicate
+     * function. Both `predicateHash` (from the registration) and a
+     * canonical-JSON hash of `ctx` fold into the MV's `queryHash`, so
+     * either changing forces refresh on next visit.
+     */
+    wherePredicate(name: string, ctx?: unknown): Query<T>;
     /** Add a field comparison. Multiple where() calls are AND-combined. */
     where(field: string, op: Operator, value: unknown): Query<T>;
     /**
@@ -1451,6 +1914,36 @@ declare class Query<T> {
         strategy?: JoinStrategy;
         maxRows?: number;
     }): Query<T & Record<As, R | null>>;
+    /**
+     * Cartesian-product cross-join against `target` collection. Each result row
+     * carries the original `T` fields plus `result[as]` populated from every
+     * right-side row (or the filtered subset when `on:` is supplied).
+     *
+     * **Order matters:** `.where().crossJoin()` filters BEFORE expanding (cheaper);
+     * `.crossJoin().where('alias.field', ...)` filters AFTER (required when the
+     * where clause references the aliased fields).
+     *
+     * **Cost ceiling:** `CrossJoinTooLargeError` fires before allocation when
+     * `leftRows × rightRows` (or the cumulative lateral count) exceeds the limit.
+     * Default: 50,000 rows. Override per-clause with `{ maxRows: N }`.
+     *
+     * **`on:` shapes:**
+     *   - `on: (left) => TTarget[]`              — subset form (most efficient)
+     *   - `on: (left) => (right) => boolean`     — predicate form
+     *   - `on: { predicate: 'name' }`            — MV-safe, hash-tracked form
+     *     (requires the Query to have been augmented via `_withPredicates`)
+     *
+     * Requires a JoinContext (constructed via `collection.query()`).
+     */
+    crossJoin<TTarget = unknown, As extends string = string>(target: string, opts: {
+        as: As;
+        on?: ((left: T) => unknown[] | ((right: TTarget) => boolean)) | {
+            readonly predicate: string;
+        };
+        maxRows?: number;
+    }): Query<T & {
+        [K in As]: TTarget;
+    }>;
     /**
      * Execute the plan and return the matching records. When the plan
      * carries any join legs, they are applied after `where` / `orderBy`
@@ -1558,6 +2051,7 @@ declare class Query<T> {
      * per record and can't be index-accelerated.
      */
     groupBy<F extends string>(field: F): GroupedQuery<T, F>;
+    groupBy<F extends readonly [string, string, ...string[]]>(...fields: F): GroupedQueryN<T, F>;
     /**
      * Re-run the query whenever the source notifies of changes.
      * Returns an unsubscribe function. The callback receives the latest result.
@@ -1937,4 +2431,4 @@ declare class ScanBuilder<T> implements AsyncIterable<T> {
     private recordMatches;
 }
 
-export { ScanBuilder as $, AlreadyElevatedError as A, BackupCorruptedError as B, ConflictError as C, DEFAULT_JOIN_MAX_ROWS as D, ElevationExpiredError as E, FilenameSanitizationError as F, GroupCardinalityError as G, type QuerySource as H, ImportCapabilityError as I, type JoinContext as J, KeyringExpiredError as K, LedgerContentionError as L, MissingTranslationError as M, NoydbError as N, type OrderBy as O, PathEscapeError as P, Query as Q, ReadOnlyAtInstantError as R, ReadOnlyError as S, ReadOnlyFrameError as T, type RefDescriptor as U, RefIntegrityError as V, type RefMode as W, RefRegistry as X, RefScopeError as Y, type RefViolation as Z, ReservedCollectionNameError as _, BackupLedgerError as a, type ScanPageProvider as a0, SchemaValidationError as a1, SessionExpiredError as a2, SessionNotFoundError as a3, SessionPolicyError as a4, StoreCapabilityError as a5, TamperedError as a6, TierDemoteDeniedError as a7, TierNotGrantedError as a8, TranslatorNotConfiguredError as a9, ValidationError as aa, applyJoins as ab, buildLiveQuery as ac, executePlan as ad, ref as ae, resetJoinWarnings as af, BundleIntegrityError as b, BundleVersionConflictError as c, DanglingReferenceError as d, DecryptionError as e, DelegationTargetMissingError as f, DictKeyInUseError as g, DictKeyMissingError as h, ExportCapabilityError as i, IndexRequiredError as j, IndexWriteFailureError as k, InvalidKeyError as l, type JoinLeg as m, type JoinStrategy as n, JoinTooLargeError as o, type JoinableSource as p, type LiveQuery as q, type LiveUpstream as r, LocaleNotSpecifiedError as s, NetworkError as t, NoAccessError as u, NotFoundError as v, PeriodClosedError as w, PermissionDeniedError as x, PrivilegeEscalationError as y, type QueryPlan as z };
+export { ImportCapabilityError as $, AmendmentForbiddenError as A, BackupCorruptedError as B, ConflictError as C, DictKeyInUseError as D, CrossJoinSourceUnknownError as E, FieldFrozenError as F, CrossJoinTooLargeError as G, DEFAULT_CROSS_JOIN_MAX_ROWS as H, InvariantError as I, DEFAULT_JOIN_MAX_ROWS as J, DanglingReferenceError as K, LocaleNotSpecifiedError as L, MissingTranslationError as M, NoydbError as N, OverlayBaseIsVirtualError as O, PartitionExtractionError as P, Query as Q, ReservedCollectionNameError as R, ScriptViolationError as S, TranslatorNotConfiguredError as T, DecryptionError as U, DelegationTargetMissingError as V, DirectoryDisabledError as W, ElevationExpiredError as X, ExportCapabilityError as Y, FilenameSanitizationError as Z, GroupCardinalityError as _, DictKeyMissingError as a, IndexRequiredError as a0, IndexWriteFailureError as a1, InvalidKeyError as a2, type JoinContext as a3, type JoinLeg as a4, type JoinStrategy as a5, JoinTooLargeError as a6, type JoinableSource as a7, KeyringCorruptError as a8, KeyringExpiredError as a9, type ScanPageProvider as aA, SchemaFenceError as aB, SchemaLockedError as aC, SchemaUpdateError as aD, SchemaValidationError as aE, StoreCapabilityError as aF, TamperedError as aG, TierDemoteDeniedError as aH, TierNotGrantedError as aI, UniqueConstraintError as aJ, UnsupportedIndexOptionError as aK, ValidationError as aL, applyJoins as aM, buildLiveQuery as aN, executePlan as aO, ref as aP, resetJoinWarnings as aQ, LedgerContentionError as aa, type LiveQuery as ab, type LiveUpstream as ac, MigrationRequiredError as ad, NetworkError as ae, NoAccessError as af, NonAdditiveSchemaChangeError as ag, NotFoundError as ah, type OrderBy as ai, PathEscapeError as aj, PeriodClosedError as ak, PermissionDeniedError as al, PrivilegeEscalationError as am, type QueryPlan as an, type QuerySource as ao, QuiesceTimeoutError as ap, ReadOnlyAtInstantError as aq, ReadOnlyError as ar, ReadOnlyFrameError as as, type RefDescriptor as at, RefIntegrityError as au, type RefMode as av, RefRegistry as aw, RefScopeError as ax, type RefViolation as ay, ScanBuilder as az, SessionExpiredError as b, SessionNotFoundError as c, SessionPolicyError as d, RecordLockedError as e, SnapshotNotFoundError as f, DerivationCapExceededError as g, DerivationCycleError as h, DerivationDepthError as i, DerivationOutputShapeError as j, DerivationOutputUnknownError as k, OverlayCollectionUnavailableError as l, OverlayIdMismatchError as m, OverlayNameCollisionError as n, AttestationError as o, AdoptionStateError as p, BackupLedgerError as q, BundleIntegrityError as r, BundleSealMismatchError as s, BundleVersionConflictError as t, TransferSealError as u, MaterializedViewConfigError as v, MaterializedViewCycleError as w, MaterializedViewSourceUnknownError as x, MaterializedViewTooLargeError as y, AlreadyElevatedError as z };