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

package/dist/{index-6xNpPsxR.d.cts → index-CNwA-B6-.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_`).
@@ -830,6 +935,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 +1616,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 +1855,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 +2235,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 { KeyringCorruptError as $, AmendmentForbiddenError as A, BackupCorruptedError as B, ConflictError as C, DictKeyInUseError as D, ElevationExpiredError as E, FieldFrozenError as F, ExportCapabilityError as G, FilenameSanitizationError as H, InvariantError as I, GroupCardinalityError as J, ImportCapabilityError as K, LocaleNotSpecifiedError as L, MissingTranslationError as M, NoydbError as N, OverlayBaseIsVirtualError as O, IndexRequiredError as P, Query as Q, ReservedCollectionNameError as R, SessionExpiredError as S, TranslatorNotConfiguredError as T, IndexWriteFailureError as U, InvalidKeyError as V, type JoinContext as W, type JoinLeg as X, type JoinStrategy as Y, JoinTooLargeError as Z, type JoinableSource as _, DictKeyMissingError as a, KeyringExpiredError as a0, LedgerContentionError as a1, type LiveQuery as a2, type LiveUpstream as a3, NetworkError as a4, NoAccessError as a5, NotFoundError as a6, type OrderBy as a7, PathEscapeError as a8, PeriodClosedError as a9, PermissionDeniedError as aa, PrivilegeEscalationError as ab, type QueryPlan as ac, type QuerySource as ad, ReadOnlyAtInstantError as ae, ReadOnlyError as af, ReadOnlyFrameError as ag, type RefDescriptor as ah, RefIntegrityError as ai, type RefMode as aj, RefRegistry as ak, RefScopeError as al, type RefViolation as am, ScanBuilder as an, type ScanPageProvider as ao, SchemaValidationError as ap, StoreCapabilityError as aq, TamperedError as ar, TierDemoteDeniedError as as, TierNotGrantedError as at, ValidationError as au, applyJoins as av, buildLiveQuery as aw, executePlan as ax, ref as ay, resetJoinWarnings 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, MaterializedViewConfigError as m, MaterializedViewCycleError as n, MaterializedViewSourceUnknownError as o, MaterializedViewTooLargeError as p, AlreadyElevatedError as q, BackupLedgerError as r, BundleIntegrityError as s, BundleSealMismatchError as t, BundleVersionConflictError as u, DEFAULT_JOIN_MAX_ROWS as v, DanglingReferenceError as w, DecryptionError as x, DelegationTargetMissingError as y, DirectoryDisabledError as z };