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

package/dist/i18n/index.d.cts

@@ -1,10 +1,11 @@
-import { I as I18nStrategy } from '../types-Bnb82f5R.cjs';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nTextDescriptor, f as I18nTextOptions, g as applyI18nLocale, h as dictCollectionName, i as dictKey, j as i18nText, k as isDictCollectionName, l as isDictKeyDescriptor, m as isI18nTextDescriptor, r as resolveI18nText, v as validateI18nTextValue } from '../types-Bnb82f5R.cjs';
-import '../lazy-builder-CZVLKh0Z.cjs';
-import '../predicate-SBHmi6D0.cjs';
-import '../strategy-D-SrOLCl.cjs';
+import { I as I18nStrategy } from '../types-DJG8HG6F.cjs';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nTextDescriptor, f as I18nTextOptions, g as applyI18nLocale, h as dictCollectionName, i as dictKey, j as i18nText, k as isDictCollectionName, l as isDictKeyDescriptor, m as isI18nTextDescriptor, r as resolveI18nText, v as validateI18nTextValue } from '../types-DJG8HG6F.cjs';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, T as TranslatorNotConfiguredError } from '../index-BMjrzNZr.cjs';
+import '../lazy-builder-C-rPfWG0.cjs';
+import '../predicate-Dnu81tsS.cjs';
+import '../strategy-DSTrsZ8t.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-6xNpPsxR.cjs';
+import '@noy-db/attestation';
 
 /**
  * Active i18n strategy — `withI18n()` returns the real implementation

package/dist/i18n/index.d.ts

@@ -1,10 +1,11 @@
-import { I as I18nStrategy } from '../types-Bo7NSXJr.js';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nTextDescriptor, f as I18nTextOptions, g as applyI18nLocale, h as dictCollectionName, i as dictKey, j as i18nText, k as isDictCollectionName, l as isDictKeyDescriptor, m as isI18nTextDescriptor, r as resolveI18nText, v as validateI18nTextValue } from '../types-Bo7NSXJr.js';
-import '../lazy-builder-BwEoBQZ9.js';
-import '../predicate-SBHmi6D0.js';
-import '../strategy-D-SrOLCl.js';
+import { I as I18nStrategy } from '../types-BoFFiskX.js';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nTextDescriptor, f as I18nTextOptions, g as applyI18nLocale, h as dictCollectionName, i as dictKey, j as i18nText, k as isDictCollectionName, l as isDictKeyDescriptor, m as isI18nTextDescriptor, r as resolveI18nText, v as validateI18nTextValue } from '../types-BoFFiskX.js';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, T as TranslatorNotConfiguredError } from '../index-BCKdioeh.js';
+import '../lazy-builder-Rpd-V3jP.js';
+import '../predicate-Dnu81tsS.js';
+import '../strategy-DSTrsZ8t.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-DJTf9yxn.js';
+import '@noy-db/attestation';
 
 /**
  * Active i18n strategy — `withI18n()` returns the real implementation

package/dist/i18n/index.js

@@ -1,21 +1,30 @@
 import {
-  DICT_COLLECTION_PREFIX,
-  DictionaryHandle,
   applyI18nLocale,
-  dictCollectionName,
-  dictKey,
   i18nText,
-  isDictCollectionName,
-  isDictKeyDescriptor,
   isI18nTextDescriptor,
   resolveI18nText,
   validateI18nTextValue
-} from "../chunk-MDDTIZUO.js";
-import "../chunk-WDM5XGGS.js";
-import "../chunk-CIMZBAZB.js";
-import "../chunk-RKJ6OL7K.js";
-import "../chunk-MR4424N3.js";
-import "../chunk-ACLDOTNQ.js";
+} from "../chunk-3XHOCQK4.js";
+import {
+  DICT_COLLECTION_PREFIX,
+  DictionaryHandle,
+  dictCollectionName,
+  dictKey,
+  isDictCollectionName,
+  isDictKeyDescriptor
+} from "../chunk-LRAZDV5X.js";
+import "../chunk-Q6W2CMEJ.js";
+import "../chunk-XG3PTSCD.js";
+import "../chunk-YS3POABP.js";
+import "../chunk-2PAQNPE3.js";
+import {
+  DictKeyInUseError,
+  DictKeyMissingError,
+  LocaleNotSpecifiedError,
+  MissingTranslationError,
+  ReservedCollectionNameError,
+  TranslatorNotConfiguredError
+} from "../chunk-W3XXT26A.js";
 
 // src/i18n/active.ts
 function withI18n() {
@@ -40,7 +49,13 @@ function withI18n() {
 }
 export {
   DICT_COLLECTION_PREFIX,
+  DictKeyInUseError,
+  DictKeyMissingError,
   DictionaryHandle,
+  LocaleNotSpecifiedError,
+  MissingTranslationError,
+  ReservedCollectionNameError,
+  TranslatorNotConfiguredError,
   applyI18nLocale,
   dictCollectionName,
   dictKey,

package/dist/i18n/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/i18n/active.ts"],"sourcesContent":["/**\n * Active i18n strategy — `withI18n()` returns the real implementation\n * that wires multi-locale resolution, i18nText validation, and the\n * `DictionaryHandle` for `dictKey` fields into the core read/write\n * paths.\n *\n * Consumers opt in by:\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withI18n } from '@noy-db/hub/i18n'\n *\n * const db = await createNoydb({\n *   store: ...,\n *   user: ...,\n *   i18nStrategy: withI18n(),\n * })\n * ```\n *\n * The factory delegates to the existing `core.ts` and `dictionary.ts`\n * modules. Splitting the import chain through this file is what lets\n * tsup tree-shake the `~854 LOC` of dictionary + locale resolution\n * out of the default bundle when no `withI18n()` import is present.\n *\n * @public\n */\n\nimport type { I18nStrategy, BuildDictionaryHandleOptions } from './strategy.js'\nimport { applyI18nLocale, validateI18nTextValue } from './core.js'\nimport { DictionaryHandle } from './dictionary.js'\n\nexport function withI18n(): I18nStrategy {\n  return {\n    applyI18nLocale,\n    validateI18nTextValue,\n    buildDictionaryHandle<Keys extends string = string>(\n      opts: BuildDictionaryHandleOptions<Keys>,\n    ): DictionaryHandle<Keys> {\n      return new DictionaryHandle<Keys>(\n        opts.adapter,\n        opts.compartmentName,\n        opts.dictionaryName,\n        opts.keyring,\n        opts.getDEK,\n        opts.encrypted,\n        opts.ledger,\n        opts.options,\n        opts.findAndUpdateReferences,\n        opts.emitter,\n      )\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA+BO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,sBACE,MACwB;AACxB,aAAO,IAAI;AAAA,QACT,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MACP;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/i18n/active.ts"],"sourcesContent":["/**\n * Active i18n strategy — `withI18n()` returns the real implementation\n * that wires multi-locale resolution, i18nText validation, and the\n * `DictionaryHandle` for `dictKey` fields into the core read/write\n * paths.\n *\n * Consumers opt in by:\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withI18n } from '@noy-db/hub/i18n'\n *\n * const db = await createNoydb({\n *   store: ...,\n *   user: ...,\n *   i18nStrategy: withI18n(),\n * })\n * ```\n *\n * The factory delegates to the existing `core.ts` and `dictionary.ts`\n * modules. Splitting the import chain through this file is what lets\n * tsup tree-shake the `~854 LOC` of dictionary + locale resolution\n * out of the default bundle when no `withI18n()` import is present.\n *\n * @public\n */\n\nimport type { I18nStrategy, BuildDictionaryHandleOptions } from './strategy.js'\nimport { applyI18nLocale, validateI18nTextValue } from './core.js'\nimport { DictionaryHandle } from './dictionary.js'\n\nexport function withI18n(): I18nStrategy {\n  return {\n    applyI18nLocale,\n    validateI18nTextValue,\n    buildDictionaryHandle<Keys extends string = string>(\n      opts: BuildDictionaryHandleOptions<Keys>,\n    ): DictionaryHandle<Keys> {\n      return new DictionaryHandle<Keys>(\n        opts.adapter,\n        opts.compartmentName,\n        opts.dictionaryName,\n        opts.keyring,\n        opts.getDEK,\n        opts.encrypted,\n        opts.ledger,\n        opts.options,\n        opts.findAndUpdateReferences,\n        opts.emitter,\n      )\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,sBACE,MACwB;AACxB,aAAO,IAAI;AAAA,QACT,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MACP;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/{index-6xNpPsxR.d.cts → index-BCKdioeh.d.ts}

@@ -1,5 +1,5 @@
-import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-SBHmi6D0.cjs';
-import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery } from './strategy-D-SrOLCl.cjs';
+import { C as CollectionIndexes, a as Clause, O as Operator } from './predicate-Dnu81tsS.js';
+import { A as AggregateStrategy, b as AggregateSpec, c as Aggregation, a as AggregateResult, g as GroupedQuery, h as GroupedQueryN } from './strategy-DSTrsZ8t.js';
 
 /**
  * All NOYDB error classes — a single import surface for `catch` blocks and
@@ -116,6 +116,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 +249,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 +347,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.
  *
@@ -584,6 +662,33 @@ declare class IndexWriteFailureError extends NoydbError {
 declare class BundleIntegrityError extends NoydbError {
     constructor(message: string);
 }
+/**
+ * Thrown by `readNoydbBundle` (#197) 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_`).
@@ -707,6 +812,34 @@ declare class BackupCorruptedError extends NoydbError {
     readonly id: string;
     constructor(collection: string, id: string, message: string);
 }
+/**
+ * Thrown by partition-extraction primitives (#198 epic) 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` (#207) 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 (#207), or owner-creation on a
+ * vault that isn't in the adopted-unowned state (#208).
+ */
+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
@@ -830,6 +963,156 @@ 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 (#200) 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 introduced by #165:
+ *   - 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);
+}
 
 /**
  * Foreign-key references — the soft-FK mechanism.
@@ -1361,12 +1644,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 (#153). 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 (#153).
+     * Consumers don't call this directly.
+     */
+    _withPredicates(predicates: ReadonlyMap<string, DeclaredPredicate>): Query<T>;
+    /**
+     * Filter by a registered deterministic predicate (#153). 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>;
     /**
@@ -1558,6 +1883,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 +2263,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 { type JoinLeg as $, AmendmentForbiddenError as A, BackupCorruptedError as B, ConflictError as C, DictKeyInUseError as D, DecryptionError as E, FieldFrozenError as F, DelegationTargetMissingError as G, DirectoryDisabledError as H, InvariantError as I, ElevationExpiredError as J, ExportCapabilityError as K, LocaleNotSpecifiedError as L, MissingTranslationError as M, NoydbError as N, OverlayBaseIsVirtualError as O, PartitionExtractionError as P, Query as Q, ReservedCollectionNameError as R, SessionExpiredError as S, TranslatorNotConfiguredError as T, FilenameSanitizationError as U, GroupCardinalityError as V, ImportCapabilityError as W, IndexRequiredError as X, IndexWriteFailureError as Y, InvalidKeyError as Z, type JoinContext as _, DictKeyMissingError as a, type JoinStrategy as a0, JoinTooLargeError as a1, type JoinableSource as a2, KeyringCorruptError as a3, KeyringExpiredError as a4, LedgerContentionError as a5, type LiveQuery as a6, type LiveUpstream as a7, NetworkError as a8, NoAccessError as a9, buildLiveQuery as aA, executePlan as aB, ref as aC, resetJoinWarnings as aD, NotFoundError as aa, type OrderBy as ab, PathEscapeError as ac, PeriodClosedError as ad, PermissionDeniedError as ae, PrivilegeEscalationError as af, type QueryPlan as ag, type QuerySource as ah, ReadOnlyAtInstantError as ai, ReadOnlyError as aj, ReadOnlyFrameError as ak, type RefDescriptor as al, RefIntegrityError as am, type RefMode as an, RefRegistry as ao, RefScopeError as ap, type RefViolation as aq, ScanBuilder as ar, type ScanPageProvider as as, SchemaValidationError as at, StoreCapabilityError as au, TamperedError as av, TierDemoteDeniedError as aw, TierNotGrantedError as ax, ValidationError as ay, applyJoins as az, SessionNotFoundError as b, SessionPolicyError as c, RecordLockedError as d, DerivationCapExceededError as e, DerivationCycleError as f, DerivationDepthError as g, DerivationOutputShapeError as h, DerivationOutputUnknownError as i, OverlayCollectionUnavailableError as j, OverlayIdMismatchError as k, OverlayNameCollisionError as l, AttestationError as m, AdoptionStateError as n, BackupLedgerError as o, BundleIntegrityError as p, BundleSealMismatchError as q, BundleVersionConflictError as r, TransferSealError as s, MaterializedViewConfigError as t, MaterializedViewCycleError as u, MaterializedViewSourceUnknownError as v, MaterializedViewTooLargeError as w, AlreadyElevatedError as x, DEFAULT_JOIN_MAX_ROWS as y, DanglingReferenceError as z };