@noy-db/hub 0.2.0-pre.11 → 0.2.0-pre.12

package/dist/strategy-rtpKDfTC.d.cts

@@ -0,0 +1,2029 @@
+/**
+ * Aggregation reducers for the query DSL.
+ *
+ * the reducer protocol plus five built-in factories
+ * (`count`, `sum`, `avg`, `min`, `max`) consumed by `Query.aggregate()`
+ * and, in the future, `Scan.aggregate()`. Every factory accepts
+ * an optional `{ seed }` parameter that is plumbed through the
+ * protocol but unused by the executor — that's the load-bearing
+ * half of  constraint #2. When partition-aware aggregation
+ * lands, the seed carries the previous partition's running total into
+ * the next partition without requiring a protocol change.
+ *
+ * Reducers are intentionally generic over their internal state type
+ * `S` so compound reducers (avg keeps `{sum, count}`, min/max keep a
+ * value bag) can model internal bookkeeping without leaking the
+ * implementation through the accumulator's public shape. `finalize`
+ * collapses `S` back into the user-visible `R`.
+ *
+ * Reducers are pure data — `init` / `step` / `finalize` / optional
+ * `remove` are stateless functions that receive and return `S`. This
+ * is the shape that admits O(1) incremental maintenance in a future
+ * optimization (delta-aware `LiveAggregation` applies `step` or
+ * `remove` per delta), without blocking the simpler "full re-run on
+ * source change" that ships.
+ */
+/**
+ * A single reducer: factory-produced, ready to plug into an
+ * `.aggregate()` spec.
+ *
+ * Type parameters:
+ *   - `R` — user-visible result type (what the aggregation returns
+ *     for this slot, e.g. `number` for `sum()`)
+ *   - `S` — internal state type, defaults to `R` for simple reducers
+ *     that don't need compound bookkeeping
+ *
+ * A reducer is stateless: every method is pure over `S`. `init()` is
+ * called once per aggregation run to build the initial state; `step()`
+ * folds a record into the state; `remove()` (optional) un-folds a
+ * record, enabling incremental live maintenance; `finalize()` reads
+ * the final answer out of the state at the end of the run.
+ */
+interface Reducer<R, S = R> {
+    /** Build the initial state for a fresh aggregation run. */
+    init(): S;
+    /** Fold a record into the state. Returns the new state. */
+    step(state: S, record: unknown): S;
+    /**
+     * Un-fold a record from the state. Returns the new state.
+     *
+     * Optional — reducers without `remove` cannot be maintained
+     * incrementally and must be re-run from scratch when the underlying
+     * record set changes. `sum`, `count`, `avg` implement `remove` in
+     * O(1); `min` and `max` implement it in O(N) worst case (when the
+     * extremum itself is removed and the next extremum must be
+     * recomputed from the remaining contributing values).
+     */
+    remove?(state: S, record: unknown): S;
+    /** Collapse the internal state into the user-visible result. */
+    finalize(state: S): R;
+    /**
+     * Combine two independent partial states into one (then `finalize` once).
+     * Optional. MUST be associative + commutative with `init()` as identity.
+     * Never merge finalized results — only states. Enables parallel /
+     * hierarchical aggregation (e.g. cross-shard or advisor→firm rollup).
+     */
+    merge?(a: S, b: S): S;
+    /**
+     * Identifying operation tag stamped by each built-in factory.
+     * Used by `summariseAggregateOp` in the introspection walker to
+     * render human-readable aggregate descriptors in `dumpSchema()`.
+     * Optional so third-party custom reducers are unaffected.
+     */
+    readonly op?: 'count' | 'sum' | 'avg' | 'min' | 'max';
+    /**
+     * Field name for field-based reducers (`sum`, `avg`, `min`, `max`).
+     * Absent on `count` which aggregates over record count, not a field.
+     */
+    readonly field?: string;
+    /**
+     * Money-only: target currency for `sum` over a multi-currency money
+     * field. Consumed by `wrapMoneyReducers` to convert per-currency
+     * subtotals to one figure. Ignored for non-money fields.
+     */
+    readonly convertTo?: string;
+    /**
+     * Money-only: FX rate map (`'USD->EUR' → rate`) used with `convertTo`.
+     */
+    readonly fx?: Record<string, number | string>;
+}
+/**
+ * Common options accepted by every reducer factory.
+ *
+ * `seed` — optional initial value for the internal state. **Unused by
+ * the executor**, plumbed through the protocol for  constraint
+ * #2 (partition-aware aggregation seam). In, partitioned
+ * aggregations will pass the previous partition's carry as `seed` so
+ * a long time series can be rolled forward one partition at a time
+ * without re-aggregating closed partitions.
+ *
+ * always uses `init()` with the factory's zero value, regardless
+ * of whether `seed` was passed. Do not remove the parameter — that's
+ * the whole point of having it exist now.
+ */
+interface ReducerOptions<TSeed = unknown> {
+    /**  constraint #2 — seed is plumbed through but unused in. */
+    readonly seed?: TSeed;
+    /**
+     * Money-only (honored by `sum` over a multi-currency money field):
+     * convert per-currency subtotals to this currency for a single figure.
+     */
+    readonly convertTo?: string;
+    /** Money-only: FX rate map (`'USD->EUR' → rate`) used with `convertTo`. */
+    readonly fx?: Record<string, number | string>;
+}
+/**
+ * Count the number of records that match the query. Ignores field
+ * values entirely — the count is over the number of records, not over
+ * the number of non-null field values in any column.
+ */
+declare function count(opts?: ReducerOptions<number>): Reducer<number>;
+/**
+ * Sum a numeric field across all matching records. Non-number values
+ * at the field path are coerced to 0 — consumers who want a different
+ * behavior (throw, skip, treat as NaN) should filter upstream via
+ * `.where()` or write a custom reducer.
+ */
+declare function sum(field: string, opts?: ReducerOptions<number>): Reducer<number>;
+/**
+ * Arithmetic mean of a numeric field across all matching records.
+ *
+ * Returns `null` for an empty result set (zero records is not a
+ * well-defined denominator — returning NaN would poison downstream
+ * arithmetic, and throwing would force every consumer to wrap in
+ * try/catch just to handle "no matches"). Consumers who want an
+ * explicit zero should coalesce with `?? 0`.
+ *
+ * Internal state is `{sum, count}` so the running average can be
+ * maintained incrementally — on each delta, both fields update in
+ * O(1) and `finalize` divides. Directly storing `avg` as state would
+ * not admit incremental removal without also tracking count.
+ */
+declare function avg(field: string, opts?: ReducerOptions<{
+    sum: number;
+    count: number;
+}>): Reducer<number | null, {
+    sum: number;
+    count: number;
+}>;
+interface MinMaxState {
+    /**
+     * Multiset of contributing field values. Stored as a plain array
+     * because we need to support `remove` and a plain array gives us
+     * O(1) push + O(N) worst-case removal — which matches the
+     * documented min/max removal complexity. A sorted structure would
+     * let us drop the O(N) rescan but adds complexity that doesn't
+     * need; consumers hitting the O(N) ceiling should file an issue.
+     */
+    readonly values: number[];
+}
+/**
+ * Smallest numeric value of a field across all matching records.
+ * Returns `null` for an empty result set. See `avg()` for the
+ * reasoning on `null` vs NaN vs throwing.
+ *
+ * Incremental complexity: O(1) for `step`, O(N) worst case for
+ * `remove` when the current minimum is removed (the state holds the
+ * full multiset of contributing values and `finalize` scans for the
+ * new minimum). Consumers with very large result sets and frequent
+ * removals of the current extremum should either accept the cost or
+ * wait for a future optimization.
+ */
+declare function min(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
+/**
+ * Largest numeric value of a field across all matching records.
+ * Mirror of `min()` — see that doc for semantics, null-on-empty
+ * behavior, and the O(N) removal caveat.
+ */
+declare function max(field: string, opts?: ReducerOptions<number>): Reducer<number | null, MinMaxState>;
+
+/**
+ * Aggregate execution — the runtime behind `Query.aggregate()`.
+ *
+ * takes an `AggregateSpec` (a record of named reducers
+ * built from `reducers.ts`) and runs every reducer over the records
+ * produced by the underlying query. Two terminal surfaces:
+ *
+ *   - `.run(): R` — synchronous one-shot reduction. Matches the
+ *     existing `Query.toArray()` / `.first()` / `.count()` style.
+ *   - `.live(): LiveAggregation<R>` — reactive primitive that
+ *     re-runs the reduction whenever the query's source notifies of
+ *     a change. uses naive full re-run; incremental delta
+ *     maintenance is admitted by the reducer protocol (`remove()`)
+ *     but not wired to the executor yet — a follow-up optimization
+ *     can switch from full re-run to delta-based without breaking
+ *     the public API. Consumers get correct, reactive values today.
+ *
+ * The `Aggregation<R>` wrapper is deliberately tiny — it exists so
+ * `.aggregate(spec)` can be chained with either `.run()` or `.live()`
+ * without the builder needing two separate terminal methods. It
+ * holds the closure over the query execution (produces the current
+ * matching record set) and the spec, and stitches them together in
+ * either mode.
+ *
+ * This file depends ONLY on `reducers.ts` — it has no knowledge of
+ * the `Query` class. Tests can therefore exercise the reduction
+ * surface with plain record arrays, without spinning up a Collection.
+ */
+
+/**
+ * A named set of reducers, keyed by output field name. Each key
+ * becomes a field on the aggregated result.
+ *
+ * ```ts
+ * const spec = {
+ *   total: sum('amount'),
+ *   n:     count(),
+ *   avgAmount: avg('amount'),
+ * }
+ * ```
+ */
+type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>;
+/**
+ * Map an `AggregateSpec` to its reduced result shape — each key
+ * carries the finalized result type from its reducer. A spec built
+ * from `{ total: sum('amount'), n: count() }` yields a result of
+ * `{ total: number, n: number }`.
+ *
+ * This uses a mapped type with a conditional to extract `R` from
+ * each `Reducer<R, _>`. The `infer` captures the user-visible result
+ * type, discarding the internal state type `S`.
+ */
+type AggregateResult<Spec extends AggregateSpec> = {
+    [K in keyof Spec]: Spec[K] extends Reducer<infer R, unknown> ? R : never;
+};
+/**
+ * Pure reduction over a record array. Runs every reducer's
+ * `init → step* → finalize` pipeline exactly once over the records.
+ *
+ * Called by `Aggregation.run()` and by the live-mode refresh path.
+ * Exported for tests and for future `scan().aggregate()` reuse
+ * — the streaming path will call the same reducer protocol with a
+ * per-page loop instead of a single array.
+ */
+declare function reduceRecords<Spec extends AggregateSpec>(records: readonly unknown[], spec: Spec): AggregateResult<Spec>;
+/**
+ * A minimal reactive primitive for aggregation results.
+ *
+ * Same spirit as the `LiveQuery` in : frame-agnostic, a plain
+ * object with `value` / `error` fields and a `subscribe(cb)`
+ * notification channel that Vue / React / Solid adapters wrap in
+ * their own primitive. Intentionally NOT a Promise — aggregations
+ * have a well-defined "current value" at every instant, and the
+ * reactive consumer wants to read that value synchronously.
+ *
+ * Error semantics mirror `LiveQuery`: if a re-run throws, the
+ * previous successful `value` is preserved and the error is stored
+ * in `error` so consumers can render an error state without losing
+ * the last-known-good result. The throw does NOT propagate out of
+ * the source's change handler (which would tear down the upstream
+ * emitter).
+ *
+ * `stop()` tears down the upstream subscription. It is idempotent —
+ * calling it multiple times is safe — and subscribe calls after
+ * stop are no-ops (they immediately return a no-op unsubscribe).
+ * Always call `stop()` when done; Vue's `onUnmounted` is the
+ * canonical place. Raw consumers must do it themselves.
+ */
+interface LiveAggregation<R> {
+    /** Current reduced value. Undefined only if the first compute threw. */
+    readonly value: R | undefined;
+    /** Last execution error, if any. Cleared on the next successful run. */
+    readonly error: unknown;
+    /** Notify on every recomputation (success or error). Returns unsubscribe. */
+    subscribe(cb: () => void): () => void;
+    /** Tear down the upstream subscription. Idempotent. */
+    stop(): void;
+}
+/**
+ * Upstream change-notification hook for live aggregation.
+ *
+ * Matches the shape that `QuerySource.subscribe` already uses — a
+ * single method that accepts a callback and returns an unsubscribe
+ * function. The `Aggregation` wrapper collects upstreams from the
+ * query's source and wires them into a single re-run trigger.
+ */
+interface AggregationUpstream {
+    subscribe(cb: () => void): () => void;
+}
+/**
+ * Chainable wrapper returned by `Query.aggregate(spec)`. Holds the
+ * execute-records closure and the spec; terminal methods (`run`,
+ * `live`) stitch them together in either mode.
+ *
+ * Why a wrapper instead of two terminal methods on `Query` directly?
+ *
+ * The `.aggregate(spec)` call is where the spec is bound — both
+ * `.run()` and `.live()` need the same spec, and the consumer's
+ * fluent style is `query.where(...).aggregate(spec).run()` or
+ * `.aggregate(spec).live()`. Wrapping lets the spec be named once
+ * and reused for either terminal, and keeps the `Query` class
+ * from growing a pair of near-duplicate method overloads
+ * (`aggregateRun` / `aggregateLive`) that would be harder to
+ * discover.
+ */
+declare class Aggregation<R> {
+    private readonly executeRecords;
+    private readonly spec;
+    private readonly upstreams;
+    constructor(executeRecords: () => readonly unknown[], spec: AggregateSpec, upstreams: readonly AggregationUpstream[]);
+    /**
+     * Execute the query and reduce the results synchronously.
+     * Returns the reduced shape matching the spec — e.g. a spec of
+     * `{ total: sum('amount'), n: count() }` returns
+     * `{ total: number, n: number }`.
+     */
+    run(): R;
+    /**
+     * Build a reactive `LiveAggregation<R>` that re-runs the reduction
+     * whenever any upstream source notifies of a change. The initial
+     * value is computed eagerly in the constructor, so consumers can
+     * read `live.value` immediately after calling `.live()`.
+     *
+     * Always call `live.stop()` when finished — it tears down the
+     * upstream subscriptions. Vue's `onUnmounted` is the canonical
+     * place.
+     *
+     * **Implementation note:** every upstream change triggers a full
+     * re-reduction. Incremental maintenance (O(1) per delta for
+     * sum/count/avg via the reducer protocol's `remove()` method) is a
+     * planned follow-up optimization — the protocol already supports
+     * it, but the executor doesn't drive it yet. Consumers get
+     * correct, reactive values today; future PRs can switch to
+     * delta-based maintenance without changing this API.
+     */
+    live(): LiveAggregation<R>;
+}
+/**
+ * Build a `LiveAggregation<V>` from a recompute closure and a list
+ * of upstreams. Exposed so sibling files in the query DSL
+ * (currently `groupby.ts`) can reuse the reactive primitive
+ * without reaching into `LiveAggregationImpl` directly. This keeps
+ * the implementation class private while still allowing planned
+ * composition with `.groupBy().aggregate().live()`.
+ */
+declare function buildLiveAggregation<V>(recompute: () => V, upstreams: readonly AggregationUpstream[]): LiveAggregation<V>;
+
+/**
+ * Pure fixed-point decimal core for the money descriptor.
+ *
+ * All conversion goes decimal-string ⇄ scaled `BigInt`. There is no
+ * floating-point arithmetic anywhere: a value like `123.45` becomes
+ * `12345n` purely by string manipulation, never by `value * 100` (which
+ * would reintroduce the very drift money() exists to eliminate). BigInt
+ * has no magnitude ceiling, so values past `Number.MAX_SAFE_INTEGER`
+ * stay exact end-to-end.
+ *
+ * This module knows nothing about currencies, descriptors, or storage —
+ * it is the isolated, exhaustively-tested arithmetic kernel.
+ */
+type RoundingMode = 'half-up' | 'half-even' | 'half-down' | 'up' | 'down' | 'ceil' | 'floor';
+
+/**
+ * All NOYDB error classes — a single import surface for `catch` blocks and
+ * `instanceof` checks.
+ *
+ * ## Class hierarchy
+ *
+ * ```
+ * Error
+ *  └─ NoydbError (code: string)
+ *       ├─ Crypto errors
+ *       │    ├─ DecryptionError        — AES-GCM tag failure
+ *       │    ├─ TamperedError          — ciphertext modified after write
+ *       │    └─ InvalidKeyError        — wrong passphrase / corrupt keyring
+ *       ├─ Access errors
+ *       │    ├─ NoAccessError          — no DEK for this collection
+ *       │    ├─ ReadOnlyError          — ro permission, write attempted
+ *       │    ├─ PermissionDeniedError  — role too low for operation
+ *       │    ├─ PrivilegeEscalationError — grant wider than grantor holds
+ *       │    └─ StoreCapabilityError   — optional store method missing
+ *       ├─ Sync errors
+ *       │    ├─ ConflictError          — optimistic-lock version mismatch
+ *       │    ├─ BundleVersionConflictError — bundle push rejected by remote
+ *       │    └─ NetworkError           — push/pull network failure
+ *       ├─ Data errors
+ *       │    ├─ NotFoundError          — get(id) on missing record
+ *       │    ├─ ValidationError        — application-level guard failed
+ *       │    └─ SchemaValidationError  — Standard Schema v1 rejection
+ *       ├─ Query errors
+ *       │    ├─ 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
+ *       │    ├─ DictKeyInUseError
+ *       │    ├─ MissingTranslationError
+ *       │    ├─ LocaleNotSpecifiedError
+ *       │    └─ TranslatorNotConfiguredError
+ *       ├─ Backup errors
+ *       │    ├─ BackupLedgerError      — hash-chain verification failed
+ *       │    └─ BackupCorruptedError   — envelope hash mismatch in dump
+ *       ├─ Bundle errors
+ *       │    └─ BundleIntegrityError   — .noydb body sha256 mismatch
+ *       ├─ Session errors
+ *       │    ├─ SessionExpiredError
+ *       │    ├─ SessionNotFoundError
+ *       │    └─ SessionPolicyError
+ *       ├─ Snapshot errors
+ *       │    └─ SnapshotNotFoundError  — snapshot key absent from snapshot store
+ *       └─ Computed field errors
+ *            └─ ComputedFieldError     — computed function threw during a write
+ * ```
+ *
+ * ## Catching all NOYDB errors
+ *
+ * ```ts
+ * import { NoydbError, InvalidKeyError, ConflictError } from '@noy-db/hub'
+ *
+ * try {
+ *   await vault.unlock(passphrase)
+ * } catch (e) {
+ *   if (e instanceof InvalidKeyError) { showBadPassphraseUI(); return }
+ *   if (e instanceof NoydbError) { logToSentry(e.code, e); return }
+ *   throw e  // unexpected — re-throw
+ * }
+ * ```
+ *
+ * @module
+ */
+/**
+ * Base class for all NOYDB errors.
+ *
+ * Every error thrown by `@noy-db/hub` extends this class, so consumers can
+ * catch all NOYDB errors in a single `catch (e) { if (e instanceof NoydbError) ... }`
+ * block. The `code` field is a machine-readable string (e.g. `'DECRYPTION_FAILED'`)
+ * suitable for `switch` statements and logging pipelines.
+ */
+declare class NoydbError extends Error {
+    /** Machine-readable error code. Stable across library versions. */
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown when AES-GCM decryption fails.
+ *
+ * The most common cause is a wrong passphrase or a corrupted ciphertext.
+ * A `DecryptionError` at the wrong passphrase level is caught internally
+ * and re-thrown as `InvalidKeyError` — so in practice this surfaces for
+ * per-record corruption rather than authentication failures.
+ */
+declare class DecryptionError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when GCM tag verification fails, indicating the ciphertext was
+ * modified after encryption.
+ *
+ * AES-256-GCM is authenticated encryption — the tag over the ciphertext
+ * is checked on every decrypt. If any byte was flipped (accidental
+ * corruption or deliberate tampering), decryption throws this error.
+ * Treat it as a security alert: the stored bytes are not what NOYDB wrote.
+ */
+declare class TamperedError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when key unwrapping fails, typically because the passphrase is wrong
+ * or the keyring file is corrupted.
+ *
+ * NOYDB uses AES-KW (RFC 3394) to wrap DEKs with the KEK. If AES-KW
+ * unwrapping fails, it means either the KEK was derived from the wrong
+ * passphrase (PBKDF2 with 600K iterations) or the keyring bytes are
+ * corrupted. This is the error shown to the user on a failed unlock attempt.
+ */
+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.
+ *
+ * This is the "no key for this door" error. It is different from
+ * `ReadOnlyError` (user has a key but it only grants ro) and from
+ * `PermissionDeniedError` (user's role doesn't allow the operation).
+ */
+declare class NoAccessError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a user with read-only (`ro`) permission attempts a write
+ * operation (`put` or `delete`) on a collection.
+ *
+ * The user has a DEK for the collection (they can decrypt and read), but
+ * their keyring grants only `ro`. To fix: re-grant the user with `rw`
+ * permission, or do not attempt writes as a viewer/client role.
+ */
+declare class ReadOnlyError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a write is attempted against a historical view produced
+ * by `vault.at(timestamp)`. Time-machine views are read-only by
+ * contract — mutating the past would require either the shadow-vault
+ * mechanism or a ledger-history rewrite (which breaks
+ * the tamper-evidence guarantee).
+ *
+ * Distinct from {@link ReadOnlyError} (keyring-level) and
+ * {@link PermissionDeniedError} (role-level): this error is about the
+ * *view* being historical, independent of the caller's permissions.
+ */
+declare class ReadOnlyAtInstantError extends NoydbError {
+    constructor(operation: string, timestamp: string);
+}
+/**
+ * Thrown when a write is attempted against a shadow-vault frame
+ * produced by `vault.frame()`. Frames are read-only by contract —
+ * the use case is screen-sharing / demos / compliance review where
+ * the operator wants to prevent accidental edits.
+ *
+ * Behavioural enforcement only — the underlying keyring still holds
+ * write-capable DEKs. See {@link VaultFrame} for the full caveat.
+ */
+declare class ReadOnlyFrameError extends NoydbError {
+    constructor(operation: string);
+}
+/**
+ * Thrown when the authenticated user's role does not permit the requested
+ * operation — e.g. a `viewer` calling `grantAccess()`, or an `operator`
+ * calling `rotateKeys()`.
+ *
+ * This is a role-level check (what the user's role allows), distinct from
+ * `NoAccessError` (collection not in keyring) and `ReadOnlyError` (in
+ * keyring, but write not allowed).
+ */
+declare class PermissionDeniedError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when an `@noy-db/as-*` export is attempted without the
+ * required capability bit on the invoking keyring.
+ *
+ * Two sub-cases discriminated by the `tier` field:
+ *
+ * - `tier: 'plaintext'` — a plaintext-tier export (`as-xlsx`,
+ *   `as-csv`, `as-blob`, `as-zip`, …) was attempted but the
+ *   keyring's `exportCapability.plaintext` does not include the
+ *   requested `format` (nor the `'*'` wildcard). Default for every
+ *   role is `plaintext: []` — the owner must positively grant.
+ * - `tier: 'bundle'` — an encrypted `as-noydb` bundle export was
+ *   attempted but the keyring's `exportCapability.bundle` is
+ *   `false`. Default for `owner`/`admin` is `true`; for
+ *   `operator`/`viewer`/`client` it is `false`.
+ *
+ * Distinct from `PermissionDeniedError` (role-level check) and
+ * `NoAccessError` (collection not readable). Surfaces separately so
+ * UI layers can show a "request the export capability from your
+ * admin" flow rather than a generic permission error.
+ */
+declare class ExportCapabilityError extends NoydbError {
+    readonly tier: 'plaintext' | 'bundle';
+    readonly format?: string;
+    readonly userId: string;
+    constructor(opts: {
+        tier: 'plaintext' | 'bundle';
+        userId: string;
+        format?: string;
+        message?: string;
+    });
+}
+/**
+ * Thrown when a keyring file's `expires_at` cutoff has passed.
+ * Surfaced by `loadKeyring` before any DEK unwrap is attempted —
+ * past the cutoff the slot refuses to open even with the right
+ * passphrase. Distinct from PBKDF2 / unwrap errors so consumer code
+ * can show a precise "this bundle slot has expired" message instead
+ * of the generic decryption-failure UX.
+ *
+ * Used predominantly on `BundleRecipient` slots produced by
+ * `writeNoydbBundle({ recipients: [...] })` to time-box audit access.
+ */
+declare class KeyringExpiredError extends NoydbError {
+    readonly userId: string;
+    readonly expiresAt: string;
+    constructor(opts: {
+        userId: string;
+        expiresAt: string;
+    });
+}
+/**
+ * Thrown when an `@noy-db/as-*` import is attempted but the invoking
+ * 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
+ *   `importCapability.plaintext` does not include the requested
+ *   `format` (nor the `'*'` wildcard).
+ * - `tier: 'bundle'` — a `.noydb` bundle import was attempted but the
+ *   keyring's `importCapability.bundle` is not `true`.
+ *
+ * Default for every role on every dimension is closed — owners and
+ * admins must positively grant the capability. Distinct from
+ * `PermissionDeniedError` and `NoAccessError` so UI layers can show a
+ * specific "request the import capability" flow.
+ */
+declare class ImportCapabilityError extends NoydbError {
+    readonly tier: 'plaintext' | 'bundle';
+    readonly format?: string;
+    readonly userId: string;
+    constructor(opts: {
+        tier: 'plaintext' | 'bundle';
+        userId: string;
+        format?: string;
+        message?: string;
+    });
+}
+/**
+ * Thrown when a grant would give the grantee a permission the grantor
+ * does not themselves hold — the "admin cannot grant what admin cannot
+ * do" rule from the admin-delegation work.
+ *
+ * Distinct from `PermissionDeniedError` so callers can tell the two
+ * cases apart in logs and tests:
+ *
+ *   - `PermissionDeniedError` — "you are not allowed to perform this
+ *     operation at all" (wrong role).
+ *   - `PrivilegeEscalationError` — "you are allowed to grant, but not
+ *     with these specific permissions" (widening attempt).
+ *
+ * Under the admin model the grantee of an admin-grants-admin call
+ * inherits the caller's entire DEK set by construction, so this error
+ * is structurally unreachable in typical flows. The check and error
+ * class exist so that future per-collection admin scoping cannot
+ * accidentally bypass the subset rule — the guard is already wired in.
+ *
+ * `offendingCollection` carries the first collection name that failed
+ * the subset check, to make the violation actionable in error output.
+ */
+/**
+ * Thrown when a caller invokes an API that requires an optional
+ * store capability the active store does not implement.
+ *
+ * Today the only call site is `Noydb.listAccessibleVaults()`,
+ * which depends on the optional `NoydbStore.listVaults()`
+ * method. The error message names the missing method and the calling
+ * API so consumers know exactly which combination is unsupported,
+ * and the `capability` field is machine-readable so library code can
+ * pattern-match in catch blocks (e.g. fall back to a candidate-list
+ * shape).
+ *
+ * The class lives in `errors.ts` rather than as a generic
+ * `ValidationError` because the diagnostic shape is different: a
+ * `ValidationError` says "the inputs you passed are wrong"; this
+ * error says "the inputs are fine, but the store you wired up
+ * doesn't support what you're asking for." Different fix, different
+ * documentation.
+ */
+declare class StoreCapabilityError extends NoydbError {
+    /** The store method/capability that was missing. */
+    readonly capability: string;
+    constructor(capability: string, callerApi: string, storeName?: string);
+}
+declare class PrivilegeEscalationError extends NoydbError {
+    readonly offendingCollection: string;
+    constructor(offendingCollection: string, message?: string);
+}
+/**
+ * Thrown by `Collection.put` / `.delete` when the target record's
+ * envelope `_ts` falls within a closed accounting period.
+ *
+ * Distinct from `ReadOnlyError` (keyring-level), `ReadOnlyAtInstantError`
+ * (historical view), and `ReadOnlyFrameError` (shadow vault): this
+ * error is about the STORED RECORD being sealed by an operator call
+ * to `vault.closePeriod()`, independent of caller permissions or
+ * view type. The `periodName` and `endDate` fields name the sealing
+ * period so audit UIs can surface a "this record is locked in
+ * FY2026-Q1 (closed 2026-03-31)" message without parsing the error
+ * string.
+ *
+ * To apply a correction after close, book a compensating entry in a
+ * new period rather than unlocking the old one. Re-opening a closed
+ * period is deliberately unsupported.
+ */
+declare class PeriodClosedError extends NoydbError {
+    readonly periodName: string;
+    readonly endDate: string;
+    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.
+ *
+ * This is the umbrella error for tier write refusals:
+ *   - `put({ tier: N })` when the user's keyring lacks tier-N DEK.
+ *   - `elevate(id, N)` when the caller cannot reach tier N.
+ *
+ * Distinct from `TierAccessDeniedError` which covers *read* refusals on
+ * the invisibility/ghost path.
+ */
+declare class TierNotGrantedError extends NoydbError {
+    readonly tier: number;
+    readonly collection: string;
+    constructor(collection: string, tier: number);
+}
+/**
+ * Thrown when an elevated-handle operation runs after the elevation's
+ * TTL expired. Reads continue at the original tier; only writes
+ * through the scoped handle flip to throwing once expired.
+ */
+declare class ElevationExpiredError extends NoydbError {
+    readonly tier: number;
+    readonly expiresAt: number;
+    constructor(opts: {
+        tier: number;
+        expiresAt: number;
+    });
+}
+/**
+ * Thrown by `vault.elevate(...)` when an elevation is already active
+ * on the vault. Adopters must `release()` the existing handle before
+ * starting a new elevation.
+ */
+declare class AlreadyElevatedError extends NoydbError {
+    readonly activeTier: number;
+    constructor(activeTier: number);
+}
+/**
+ * Thrown when `demote()` is called by someone who is not the original
+ * elevator and not an owner.
+ */
+declare class TierDemoteDeniedError extends NoydbError {
+    constructor(id: string, tier: number);
+}
+/**
+ * Thrown when `db.delegate()` is called against a user that has no
+ * keyring in the target vault — the delegation token cannot be
+ * constructed without the target user's KEK wrap.
+ */
+declare class DelegationTargetMissingError extends NoydbError {
+    readonly toUser: string;
+    constructor(toUser: string);
+}
+/**
+ * Thrown when a `put()` detects an optimistic concurrency conflict.
+ *
+ * NOYDB uses version numbers (`_v`) for optimistic locking. If a `put()`
+ * is called with `expectedVersion: N` but the stored record is at version
+ * `M ≠ N`, the write is rejected and the caller must re-read, re-apply their
+ * change, and retry. The `version` field carries the actual stored version
+ * so callers can decide whether to retry or surface the conflict to the user.
+ */
+declare class ConflictError extends NoydbError {
+    /** The actual stored version at the time of conflict. */
+    readonly version: number;
+    constructor(version: number, message?: string);
+}
+/**
+ * Thrown by `LedgerStore.append()` after exhausting its CAS retry
+ * budget under multi-writer contention. Two browser tabs, a
+ * web app + an offline mobile peer, or a server worker pool all
+ * producing ledger entries against the same vault can race on the
+ * "read head, write head+1" cycle; the optimistic-CAS retry loop
+ * resolves the race for `casAtomic: true` stores, but pathological
+ * contention (or a buggy peer) can still exhaust the budget. When
+ * that happens, the chain is intact — the failed writer simply
+ * couldn't claim a slot. Caller's choice whether to retry, queue,
+ * or surface the failure to the user.
+ */
+declare class LedgerContentionError extends NoydbError {
+    readonly attempts: number;
+    constructor(attempts: number);
+}
+/**
+ * Thrown by `vault.sequence(name).next()` after exhausting its CAS retry
+ * budget under contention. The counter is intact; the caller may retry.
+ */
+declare class SequenceContentionError extends NoydbError {
+    readonly sequence: string;
+    readonly attempts: number;
+    constructor(sequence: string, attempts: number);
+}
+/**
+ * Thrown by `vault.sequence(name).next()` when the backing store is not
+ * CAS-capable (`capabilities.casAtomic !== true`). Gap-free numbering
+ * requires single-authority serialization, which an offline / non-CAS
+ * store cannot provide — this is a deliberate online-only wall.
+ */
+declare class SequenceOfflineError extends NoydbError {
+    constructor();
+}
+/**
+ * Thrown when a bundle push is rejected because the remote has been updated
+ * since the local bundle was last pulled.
+ *
+ * Unlike `ConflictError` (per-record), this is a whole-bundle conflict —
+ * the remote's bundle handle has changed. The caller must pull the new
+ * bundle, merge, and re-push. `remoteVersion` is the handle of the newer
+ * remote bundle for use in diagnostics.
+ */
+declare class BundleVersionConflictError extends NoydbError {
+    /** The bundle handle of the newer remote version that rejected the push. */
+    readonly remoteVersion: string;
+    constructor(remoteVersion: string, message?: string);
+}
+/**
+ * Thrown when a sync operation (push or pull) fails due to a network error.
+ *
+ * NOYDB's offline-first design means network errors are expected during sync.
+ * Callers should catch `NetworkError`, surface connectivity status in the UI,
+ * and rely on the `SyncScheduler` to retry when connectivity is restored.
+ */
+declare class NetworkError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when `collection.get(id)` is called with an ID that does not exist.
+ *
+ * NOYDB collections are memory-first, so this error is synchronous and cheap —
+ * it does not make a network round-trip. Callers that expect the record to be
+ * absent should use `collection.getOrNull(id)` instead.
+ */
+declare class NotFoundError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when application-level validation fails before encryption.
+ *
+ * Distinct from `SchemaValidationError` (Standard Schema v1 validator)
+ * and `MissingTranslationError` (i18nText). `ValidationError` is the
+ * general-purpose validation base — use it for custom guards in `put()`
+ * hooks or store middleware.
+ */
+declare class ValidationError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a Standard Schema v1 validator rejects a record on
+ * `put()` (input validation) or on read (output validation). Carries
+ * the raw issue list so callers can render field-level errors.
+ *
+ * `direction` distinguishes the two cases:
+ *   - `'input'`: the user passed bad data into `put()`. This is a
+ *     normal error case that application code should handle — typically
+ *     by showing validation messages in the UI.
+ *   - `'output'`: stored data does not match the current schema. This
+ *     indicates a schema drift (the schema was changed without
+ *     migrating the existing records) and should be treated as a bug
+ *     — the application should not swallow it silently.
+ *
+ * The `issues` type is deliberately `readonly unknown[]` on this class
+ * so that `errors.ts` doesn't need to import from `schema.ts` (and
+ * create a dependency cycle). Callers who know they're holding a
+ * `SchemaValidationError` can cast to the more precise
+ * `readonly StandardSchemaV1Issue[]` from `schema.ts`.
+ */
+declare class SchemaValidationError extends NoydbError {
+    readonly issues: readonly unknown[];
+    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)..
+ *
+ * The cap exists because `.groupBy()` materializes one bucket per
+ * distinct key value in memory, and runaway cardinality — a groupBy
+ * on a high-uniqueness field like `id` or `createdAt` — is almost
+ * always a query mistake rather than legitimate use. A hard error is
+ * better than silent OOM: the consumer sees an actionable message
+ * naming the field and the observed cardinality, with guidance to
+ * either narrow the query with `.where()` or accept the ceiling
+ * override.
+ *
+ * A separate one-shot warning fires at 10% of the cap (10_000
+ * groups) so consumers get a heads-up before the hard error — same
+ * pattern as `JoinTooLargeError` and the `.join()` row ceiling.
+ *
+ * **Not overridable in.** The 100k cap is a fixed constant so
+ * the failure mode is consistent across the codebase; a
+ * `{ maxGroups }` override can be added later without a break if a
+ * real consumer asks.
+ */
+declare class GroupCardinalityError extends NoydbError {
+    /** The field being grouped on. */
+    readonly field: string;
+    /** Observed number of distinct groups at the moment the cap tripped. */
+    readonly cardinality: number;
+    /** The cap that was exceeded. */
+    readonly maxGroups: number;
+    constructor(field: string, cardinality: number, maxGroups: number);
+}
+/**
+ * Thrown in lazy mode when a `.query()` / `.where()` / `.orderBy()` clause
+ * references a field that does not have a declared index.
+ *
+ * Lazy-mode queries only work when every touched field is indexed.
+ * This is deliberate — silent scan-fallback would hide the performance
+ * cliff that lazy-mode indexes exist to prevent.
+ *
+ * Payload:
+ * - `collection` — name of the collection queried
+ * - `touchedFields` — every field referenced by the query (filter + order)
+ * - `missingFields` — subset of `touchedFields` that have no declared index
+ */
+declare class IndexRequiredError extends NoydbError {
+    readonly collection: string;
+    readonly touchedFields: readonly string[];
+    readonly missingFields: readonly string[];
+    constructor(args: {
+        collection: string;
+        touchedFields: readonly string[];
+        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
+ * already succeeded.
+ *
+ * Not thrown out of `.put()` / `.delete()` directly — those succeed when the
+ * main record succeeds. Instead, `IndexWriteFailureError` instances are collected
+ * into the session-scoped reconcile queue and emitted on the Collection
+ * emitter as `index:write-partial`.
+ *
+ * Payload:
+ * - `recordId` — the id of the main record whose side-car writes failed
+ * - `field` — the indexed field whose side-car write failed
+ * - `op` — `'put'` or `'delete'`, indicating which mutation was in flight
+ * - `cause` — the underlying error from the store
+ */
+declare class IndexWriteFailureError extends NoydbError {
+    readonly recordId: string;
+    readonly field: string;
+    readonly op: 'put' | 'delete';
+    readonly cause: unknown;
+    constructor(args: {
+        recordId: string;
+        field: string;
+        op: 'put' | 'delete';
+        cause: unknown;
+    });
+}
+/**
+ * Thrown by `readNoydbBundle()` when the body bytes don't match
+ * the integrity hash declared in the bundle header — i.e. someone
+ * modified the bytes between write and read.
+ *
+ * Distinct from a generic `Error` (which would be thrown for
+ * format violations like a missing magic prefix or malformed
+ * header JSON) so consumers can pattern-match the corruption case
+ * and handle it differently from a producer bug. A
+ * `BundleIntegrityError` indicates "the bytes you got are not
+ * what was written"; a plain `Error` from `parsePrefixAndHeader`
+ * indicates "what was written wasn't a valid bundle in the first
+ * place."
+ *
+ * Also thrown when decompression fails after the integrity hash
+ * passed — that's a producer bug (the wrong algorithm byte was
+ * written) but it surfaces with the same error class because the
+ * end result is "the body cannot be turned back into a dump."
+ */
+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_`).
+ *
+ * Dictionary collections are accessed exclusively via
+ * `vault.dictionary(name)` — attempting to open one as a regular
+ * collection would bypass the dictionary invariants (ACL, rename
+ * tracking, reserved-name policy).
+ */
+declare class ReservedCollectionNameError extends NoydbError {
+    /** The rejected collection name. */
+    readonly collectionName: string;
+    constructor(collectionName: string);
+}
+/**
+ * Thrown by `DictionaryHandle.get()` and `DictionaryHandle.delete()` when
+ * the requested key does not exist in the dictionary.
+ *
+ * Distinct from `NotFoundError` (which is for data records) so callers
+ * can distinguish "data record missing" from "dictionary key missing"
+ * without inspecting error messages.
+ */
+declare class DictKeyMissingError extends NoydbError {
+    /** The dictionary name. */
+    readonly dictionaryName: string;
+    /** The key that was not found. */
+    readonly key: string;
+    constructor(dictionaryName: string, key: string);
+}
+/**
+ * Thrown by `DictionaryHandle.delete()` in strict mode when the key to
+ * be deleted is still referenced by one or more records.
+ *
+ * The caller must either rename the key first (the only sanctioned
+ * mass-mutation path) or pass `{ mode: 'warn' }` to skip the check
+ * (development only).
+ */
+declare class DictKeyInUseError extends NoydbError {
+    /** The dictionary name. */
+    readonly dictionaryName: string;
+    /** The key that is still referenced. */
+    readonly key: string;
+    /** Name of the first collection found to reference this key. */
+    readonly usedBy: string;
+    /** Number of records in `usedBy` that reference this key. */
+    readonly count: number;
+    constructor(dictionaryName: string, key: string, usedBy: string, count: number);
+}
+/**
+ * Thrown by `Collection.put()` when an `i18nText` field is missing one
+ * or more required translations.
+ *
+ * The `missing` array names each locale code that was absent from the
+ * field value. The `field` property names the field so callers can
+ * render a field-level error message without parsing the string.
+ */
+declare class MissingTranslationError extends NoydbError {
+    /** The field name whose translation(s) are missing. */
+    readonly field: string;
+    /** Locale codes that were required but absent. */
+    readonly missing: readonly string[];
+    constructor(field: string, missing: readonly string[], message?: string);
+}
+/**
+ * Thrown when reading an `i18nText` field without specifying a locale —
+ * either at the call site (`get(id, { locale })`) or on the vault
+ * (`openVault(name, { locale })`).
+ *
+ * Also thrown when `resolveI18nText()` exhausts the fallback chain and
+ * no translation is available for the requested locale.
+ *
+ * The `field` property names the field that triggered the error so the
+ * caller can surface it in the UI.
+ */
+declare class LocaleNotSpecifiedError extends NoydbError {
+    /** The field name that required a locale. */
+    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
+ * on `createNoydb()`.
+ *
+ * The error is raised at `put()` time (not at schema construction) so
+ * the mis-configuration is surfaced by the first write rather than
+ * silently at startup.
+ */
+declare class TranslatorNotConfiguredError extends NoydbError {
+    /** The field that requested auto-translation. */
+    readonly field: string;
+    /** The collection the put was targeting. */
+    readonly collection: string;
+    constructor(field: string, collection: string);
+}
+/**
+ * Thrown when `Vault.load()` finds that a backup's hash chain
+ * doesn't verify, or that its embedded `ledgerHead.hash` doesn't
+ * match the chain head reconstructed from the loaded entries.
+ *
+ * Distinct from `BackupCorruptedError` so callers can choose to
+ * recover from one but not the other (e.g., a corrupted JSON file is
+ * unrecoverable; a chain mismatch might mean the backup is from an
+ * incompatible noy-db version).
+ */
+declare class BackupLedgerError extends NoydbError {
+    /** First-broken-entry index, if known. */
+    readonly divergedAt?: number;
+    constructor(message: string, divergedAt?: number);
+}
+/**
+ * Thrown when `Vault.load()` finds that the backup's data
+ * collection content doesn't match the ledger's recorded
+ * `payloadHash`es. This is the "envelope was tampered with after
+ * dump" detection — the chain itself can be intact, but if any
+ * encrypted record bytes were swapped, this check catches it.
+ */
+declare class BackupCorruptedError extends NoydbError {
+    /** The (collection, id) pair whose envelope failed the hash check. */
+    readonly collection: string;
+    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
+ * in-memory store when this is thrown, so retrying with the same sessionId
+ * will produce `SessionNotFoundError`.
+ *
+ * Separate from `SessionNotFoundError` so callers can distinguish between
+ * "session is gone" (key store cleared, tab reloaded) and "session is
+ * still in the store but has exceeded its lifetime" (idle timeout, absolute
+ * timeout, policy-driven expiry). The remediation differs: expired sessions
+ * should prompt a fresh unlock; not-found sessions may indicate a bug or a
+ * cross-tab scenario where the session was never established.
+ */
+declare class SessionExpiredError extends NoydbError {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/**
+ * Thrown by `resolveSession()` when the session key cannot be found in
+ * the module-level store. This happens when:
+ *   - The session was explicitly revoked via `revokeSession()`.
+ *   - The JS context was reloaded (tab navigation, page refresh, worker restart).
+ *   - `Noydb.close()` was called (which calls `revokeAllSessions()`).
+ *   - The sessionId is wrong or was generated by a different JS context.
+ *
+ * The session token (if the caller holds it) is permanently useless after
+ * this error — the key is gone and cannot be recovered.
+ */
+declare class SessionNotFoundError extends NoydbError {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/**
+ * Thrown when a session policy blocks an operation — for example,
+ * `requireReAuthFor: ['export']` is set and the caller attempts to
+ * call `exportStream()` without re-authenticating for this session.
+ *
+ * The `operation` field names the specific operation that was blocked
+ * (e.g. `'export'`, `'grant'`, `'rotate'`) so the caller can surface
+ * a targeted prompt ("Please re-enter your passphrase to export data").
+ */
+declare class SessionPolicyError extends NoydbError {
+    readonly operation: string;
+    constructor(operation: string, message?: string);
+}
+/**
+ * Thrown when a `.join()` would exceed its configured row ceiling on
+ * either side. The ceiling defaults to 50,000 per side and can be
+ * overridden via the `{ maxRows }` option on `.join()`.
+ *
+ * Carries both row counts so the error message can show which side
+ * tripped the limit (e.g. "left had 60,000 rows, right had 1,200,
+ * max was 50,000"). The `side` field is machine-readable so test
+ * code and devtools can match on it without regex-parsing the
+ * message.
+ *
+ * The row ceiling exists because joins are bounded in-memory
+ * operations over materialized record sets. Consumers whose
+ * collections genuinely exceed the ceiling should track
+ * (streaming joins over `scan()`) or filter the left side further
+ * with `where()` / `limit()` before joining.
+ */
+declare class JoinTooLargeError extends NoydbError {
+    readonly leftRows: number;
+    readonly rightRows: number;
+    readonly maxRows: number;
+    readonly side: 'left' | 'right';
+    constructor(opts: {
+        leftRows: number;
+        rightRows: number;
+        maxRows: number;
+        side: 'left' | 'right';
+        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
+ * collection.
+ *
+ * Distinct from `RefIntegrityError` so test code can pattern-match
+ * on the *read-time* dangling case without catching *write-time*
+ * integrity violations. Both indicate "ref points at nothing" but
+ * happen at different lifecycle phases and deserve different
+ * remediation in documentation: a RefIntegrityError on `put()`
+ * means the input is invalid; a DanglingReferenceError on `.join()`
+ * means stored data has drifted and `vault.checkIntegrity()`
+ * is the right tool to find the full set of orphans.
+ */
+declare class DanglingReferenceError extends NoydbError {
+    readonly field: string;
+    readonly target: string;
+    readonly refId: string;
+    constructor(opts: {
+        field: string;
+        target: string;
+        refId: string;
+        message: string;
+    });
+}
+/**
+ * Thrown by {@link sanitizeFilename} when an input filename cannot be
+ * made safe — NUL byte, empty after normalization, missing
+ * `opaqueId` for the opaque profile, `..` segment, or a `maxBytes`
+ * cap too small to hold a single code point.
+ */
+declare class FilenameSanitizationError extends NoydbError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a write target resolves OUTSIDE the requested
+ * directory after sanitization — the canonical Zip-Slip class. The
+ * sanitizer's job is to strip path-traversal segments; this error
+ * is the defense-in-depth fallback at the FS write site.
+ */
+declare class PathEscapeError extends NoydbError {
+    readonly attempted: string;
+    readonly targetDir: string;
+    constructor(opts: {
+        attempted: string;
+        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);
+}
+/**
+ * Thrown when a write targets a partition key that has no shard and
+ * `sharding.autoCreate` is disabled.
+ */
+declare class UnknownShardError extends NoydbError {
+    readonly partitionKey: string;
+    constructor(partitionKey: string, groupName: string);
+}
+/**
+ * Thrown by `createShard` when the registry has a row for a partition
+ * but the corresponding vault is not provisioned in the store —
+ * a registry/store divergence. Refusing to recreate avoids masking
+ * data loss.
+ */
+declare class ShardProvisioningError extends NoydbError {
+    readonly vaultId: string;
+    constructor(vaultId: string, partitionKey: string);
+}
+/** Thrown when a VaultGroup references a template name that was never registered. */
+declare class VaultTemplateNotFoundError extends NoydbError {
+    readonly templateName: string;
+    constructor(templateName: string);
+}
+
+/**
+ * The `money()` field descriptor — a branded schema-layer descriptor, a
+ * sibling of `i18nText()` / `dictKey()`. It owns currency, scale, and
+ * rounding policy for a field; the pure arithmetic lives in
+ * {@link ./fixed-point} and default scale resolution in
+ * {@link ./iso4217}.
+ *
+ * Two modes:
+ *   - **fixed**  `money({ currency: 'EUR' })` — one currency for the
+ *     field; the value stores a bare scaled-integer string.
+ *   - **multi**  `money({ currencies: 'any' | [...] })` — currency travels
+ *     per record; the value stores `{ amount, currency }`.
+ *
+ * `currency` and `currencies` are mutually exclusive.
+ */
+
+interface MoneyOptionsFixed {
+    currency: string;
+    /** Override the ISO-4217 default scale (required for unlisted codes). */
+    scale?: number;
+    rounding?: RoundingMode;
+}
+interface MoneyOptionsMulti {
+    currencies: 'any' | readonly string[];
+    /** Per-currency scale overrides (required for unlisted codes). */
+    scaleOverrides?: Record<string, number>;
+    rounding?: RoundingMode;
+}
+type MoneyOptions = MoneyOptionsFixed | MoneyOptionsMulti;
+interface MoneyDescriptor {
+    readonly _noydbMoney: true;
+    readonly mode: 'fixed' | 'multi';
+    readonly options: MoneyOptions;
+    readonly rounding: RoundingMode | undefined;
+    /** The currency for fixed mode; `undefined` in multi mode. */
+    readonly fixedCurrency: string | undefined;
+    /** Resolve the scale for a currency, throwing if not allowed / unknown. */
+    scaleFor(currency: string): number;
+    /** Whether this descriptor permits the given currency. */
+    allows(currency: string): boolean;
+    /**
+     * The single currency this descriptor implies, if any — fixed mode, or
+     * multi mode with exactly one allow-listed currency. Lets a multi field
+     * accept a bare amount unambiguously. `undefined` otherwise.
+     */
+    soleCurrency(): string | undefined;
+}
+/** Raised when a written value carries more precision than `scale` allows. */
+declare class MoneyPrecisionError extends NoydbError {
+    readonly field: string;
+    readonly value: unknown;
+    readonly scale: number;
+    constructor(field: string, value: unknown, scale: number);
+}
+/** Raised when a currency is disallowed or has no resolvable scale. */
+declare class MoneyCurrencyError extends NoydbError {
+    readonly currency: string;
+    readonly reason: 'not-allowed' | 'unknown-scale';
+    readonly field?: string | undefined;
+    constructor(currency: string, reason: 'not-allowed' | 'unknown-scale', field?: string | undefined);
+}
+/** Raised when an aggregate operation is not supported on a money field. */
+declare class MoneyUnsupportedError extends NoydbError {
+    readonly field: string;
+    constructor(field: string, message?: string);
+}
+/** Create a {@link MoneyDescriptor}. */
+declare function money(options: MoneyOptions): MoneyDescriptor;
+/** Runtime predicate for detecting a {@link MoneyDescriptor}. */
+declare function isMoneyDescriptor(x: unknown): x is MoneyDescriptor;
+
+/**
+ * Query DSL `.groupBy()` —.
+ *
+ * Chains after `.where()` / `.filter()` / `.or()` / `.and()` on a
+ * Query and before a reducer spec, so consumers can compute
+ * per-bucket aggregates without folding in userland:
+ *
+ * ```ts
+ * const byClient = invoices.query()
+ *   .where('status', '==', 'open')
+ *   .groupBy('clientId')
+ *   .aggregate({ total: sum('amount'), n: count() })
+ *   .run()
+ * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
+ * ```
+ *
+ * Execution pipeline:
+ *
+ *   1. Run the query's where/filter clauses (same candidate /
+ *      filter pipeline as `.aggregate()` directly on Query).
+ *   2. Partition the matching records into buckets keyed by
+ *      `readPath(record, field)`. JS `Map` preserves insertion
+ *      order, so the first-seen key for a bucket determines its
+ *      position in the result array — consumers who want a
+ *      specific ordering should `.sort()` downstream.
+ *   3. Enforce cardinality: warn once per field at 10% of the cap
+ *      (10_000 buckets), throw `GroupCardinalityError` at 100% of
+ *      the cap (100_000 buckets).
+ *   4. For each bucket, build a per-group reducer state and
+ *      step every record in the bucket through it.
+ *   5. Emit one result row per bucket, shaped as
+ *      `{ [field]: key, ...reduced }`.
+ *
+ * **Null / undefined keys:** `Map` distinguishes `null` from
+ * `undefined`, so records with a missing group field get their own
+ * bucket, and records with an explicit `null` value get a separate
+ * bucket from that. Consumers who want them merged can coalesce
+ * upstream with `.filter()`.
+ *
+ * **Live mode:** `.groupBy().aggregate().live()` re-runs the full
+ * grouping pipeline on every source change. Per-bucket incremental
+ * delta maintenance is a future optimization — the reducer
+ * protocol's `remove()` hook admits it, but ships naive
+ * re-grouping for simplicity.
+ *
+ * **Type-level stable-key narrowing:** when
+ * `dictKey` lands, `groupBy<DictField>()` will narrow the group key
+ * type to the stable dictionary key rather than the resolved locale
+ * label. That prevents grouping by the locale-resolved label,
+ * which would produce different buckets per reader. types the
+ * key as `unknown` at the result shape; the dictKey narrowing
+ * layers on top without an API break.
+ *
+ * Partition-awareness seam: when partitioned collections land,
+ * per-partition grouping will need to merge sub-results across
+ * partitions. The reducer protocol's `{ seed }` parameter
+ * (already plumbed through in `reducers.ts`) is the mechanism —
+ * groupBy doesn't need its own seam for the moment, because it
+ * delegates to the reducer protocol for all per-bucket state.
+ */
+
+/**
+ * Cardinality thresholds for `.groupBy()`. The warn threshold gives
+ * consumers a heads-up before the hard error; the cap is a fixed
+ * constant in (not overridable). A `{ maxGroups }` override
+ * can be added later without a break if a real consumer asks.
+ */
+declare const GROUPBY_WARN_CARDINALITY = 10000;
+declare const GROUPBY_MAX_CARDINALITY = 100000;
+/**
+ * Test-only: clear the per-field cardinality warning dedup between
+ * tests. Production code never calls this — matching the
+ * `resetJoinWarnings` pattern in `join.ts`.
+ */
+declare function resetGroupByWarnings(): void;
+/**
+ * Result row shape for a grouped aggregation. Each row carries the
+ * group key value under the grouping field name plus every reducer
+ * output from the spec.
+ *
+ * types the group key as `unknown` at the result shape — the
+ * runtime read via `readPath` can return any value, and narrowing
+ * to a specific type would require the caller to assert at the
+ * call site. `dictKey` narrowing layers on top of this by
+ * adding an overload that constrains `F` when the grouping field
+ * is a `dictKey`.
+ */
+type GroupedRow<F extends string, R> = {
+    [K in F]: unknown;
+} & R;
+/**
+ * Multi-key variant — result-row shape for variadic
+ * `.groupBy(...fields)`. Every grouped field name appears on the row
+ * (typed as `unknown` for the same reason as `GroupedRow`), plus the
+ * reducer outputs from the spec.
+ */
+type GroupedRowN<F extends readonly string[], R> = {
+    [K in F[number]]: unknown;
+} & R;
+/**
+ * Shared base class for the chainable grouped-query wrappers. Holds
+ * the constructor + protected fields that both single-key
+ * `GroupedQuery<T, F>` and variadic `GroupedQueryN<T, F>` need; each
+ * subclass only overrides `aggregate()` with its own result-row
+ * generic.
+ *
+ * Not exported — implementation detail. Adding `.having()` /
+ * `.live()` / `.orderByGroup()` etc. in the future lands here once
+ * and both subclasses pick it up automatically.
+ *
+ * @internal
+ */
+declare abstract class GroupedQueryBase {
+    protected readonly executeRecords: () => readonly unknown[];
+    protected readonly upstreams: readonly AggregationUpstream[];
+    /**
+     * Optional dict label resolver attached by the query builder when
+     * the grouping field is a dictKey. Variadic groupings always pass
+     * `undefined` — `<field>Label` projection has no meaningful shape
+     * for composite keys.
+     */
+    protected readonly dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined;
+    /**
+     * Money field descriptors for the backing collection — used to
+     * rewrite `sum`/`min`/`max` over money fields into exact BigInt
+     * reducers when `.aggregate(spec)` is terminated.
+     */
+    protected readonly moneyFields?: Record<string, MoneyDescriptor> | undefined;
+    /**
+     * Field set this grouped query buckets on. Stored in declaration
+     * order — the same order is preserved on every result row by
+     * `groupAndReduce`. For the single-field constructor, this is
+     * `[field]`.
+     */
+    protected readonly fields: readonly string[];
+    constructor(executeRecords: () => readonly unknown[], fieldOrFields: string | readonly string[], upstreams: readonly AggregationUpstream[], 
+    /**
+     * Optional dict label resolver attached by the query builder when
+     * the grouping field is a dictKey. Variadic groupings always pass
+     * `undefined` — `<field>Label` projection has no meaningful shape
+     * for composite keys.
+     */
+    dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined, 
+    /**
+     * Money field descriptors for the backing collection — used to
+     * rewrite `sum`/`min`/`max` over money fields into exact BigInt
+     * reducers when `.aggregate(spec)` is terminated.
+     */
+    moneyFields?: Record<string, MoneyDescriptor> | undefined);
+    /** Apply money-aware reducer rewriting when money fields are declared. */
+    protected wrapSpec<Spec extends AggregateSpec>(spec: Spec): Spec;
+}
+/**
+ * Chainable wrapper returned by `Query.groupBy(field)`. Terminates
+ * with `.aggregate(spec)` which returns a `GroupedAggregation`.
+ *
+ * Kept minimal — the only operation on a grouped query is
+ * aggregation. Ordering, limiting, and further filtering belong on
+ * the underlying `Query` before `.groupBy()` is called; applying
+ * them post-group would be a different operation (`having` /
+ * `groupOrderBy`), out of scope for.
+ */
+declare class GroupedQuery<T, F extends string> extends GroupedQueryBase {
+    /**
+     * Build a grouped aggregation. Returns a `GroupedAggregation`
+     * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
+     * as the non-grouped `.aggregate()` wrapper, just with an array
+     * result (one row per bucket) instead of a single reduced object.
+     */
+    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>;
+}
+/**
+ * Variadic-keyed sibling of `GroupedQuery<T, F>`. Constructed by the
+ * multi-arg `Query.groupBy(...fields)` overload. The runtime shape is
+ * identical — only the type-level result-row narrowing differs.
+ */
+declare class GroupedQueryN<T, F extends readonly string[]> extends GroupedQueryBase {
+    aggregate<Spec extends AggregateSpec>(spec: Spec): GroupedAggregation<GroupedRowN<F, AggregateResult<Spec>>>;
+}
+/**
+ * Execute the group-and-reduce pipeline. Pure function over a
+ * record array and a spec — shared by `GroupedAggregation.run()`
+ * and the live-mode refresh path. Exported for tests and for any
+ * future `scan().groupBy().aggregate()` reuse.
+ *
+ * Enforces the cardinality cap incrementally during the partition
+ * loop, so a runaway grouping throws at the moment the 100_001st
+ * bucket would be created — the consumer doesn't have to wait for
+ * the full partition to materialize before the error fires.
+ */
+declare function groupAndReduce<R>(records: readonly unknown[], fieldOrFields: string | readonly string[], spec: AggregateSpec): R[];
+/**
+ * Grouped aggregation wrapper — the `.groupBy(field).aggregate(spec)`
+ * terminal. Shape mirrors `Aggregation<R>` from aggregate.ts: two
+ * terminals (`.run()` and `.live()`), spec bound at construction
+ * time, upstreams collected for live mode.
+ *
+ * The generic `R` is the per-row result shape (i.e. a single
+ * grouped row), and the terminals return `R[]` — one row per
+ * bucket.
+ */
+declare class GroupedAggregation<R> {
+    private readonly executeRecords;
+    private readonly spec;
+    private readonly upstreams;
+    /**
+     * Optional dict label resolver for `<field>Label` projection
+     *. Present when the grouping field is a dictKey.
+     */
+    private readonly dictLabelResolver?;
+    private readonly fields;
+    constructor(executeRecords: () => readonly unknown[], fields: string | readonly string[], spec: AggregateSpec, upstreams: readonly AggregationUpstream[], 
+    /**
+     * Optional dict label resolver for `<field>Label` projection
+     *. Present when the grouping field is a dictKey.
+     */
+    dictLabelResolver?: ((key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>) | undefined);
+    /** Execute the query, group, reduce, and return an array of rows. */
+    run(): R[];
+    /**
+     * Execute the query, group, reduce, and resolve `<field>Label` for
+     * each result row when the grouping field is a `dictKey` and a
+     * `locale` is provided. Returns `R[]` synchronously when
+     * no locale is specified (identical to `.run()`).
+     *
+     * The `<field>Label` field is appended to each row. Rows whose group
+     * key has no dictionary entry get `<field>Label: undefined`.
+     *
+     * Dict-label resolution is single-field only — multi-key groupings
+     * do not produce a `<field>Label`. The resolver is only attached
+     * by the builder when `fields.length === 1`.
+     */
+    runAsync(opts?: {
+        locale?: string;
+        fallback?: string | readonly string[];
+    }): Promise<R[]>;
+    /**
+     * Build a reactive `LiveAggregation<R[]>` that re-runs the full
+     * group-and-reduce pipeline whenever any upstream source notifies
+     * of a change. Same error-isolation and idempotent-stop contract
+     * as `Aggregation.live()` — the implementation delegates to the
+     * same `LiveAggregationImpl` class by threading a fresh
+     * recompute closure through the existing constructor.
+     *
+     * uses naive full re-run on every change. Incremental
+     * per-bucket maintenance (apply `step` on inserted records,
+     * `remove` on deleted records, route by bucket key) is a future
+     * optimization — the reducer protocol admits it, but wiring
+     * delta-aware source subscriptions is a separate PR.
+     *
+     * Always call `live.stop()` when finished.
+     */
+    live(): LiveAggregation<R[]>;
+}
+
+/**
+ * Strategy seam between the core Query / ScanBuilder chain and the
+ * optional aggregate / groupBy subsystem. Core imports
+ * `AggregateStrategy` as a TYPE-ONLY symbol and `NO_AGGREGATE` as a
+ * tiny runtime stub.
+ *
+ * The heavy machinery — `Aggregation`, `GroupedQuery`, the
+ * reducer-step logic — is only reachable from `withAggregate()` in
+ * `./active.ts`, which is only exported through the
+ * `@noy-db/hub/aggregate` subpath. Consumers that don't import the
+ * subpath ship none of the ~886 LOC.
+ *
+ * @internal
+ */
+
+/**
+ * Seam interface. `@internal` — will promote to public only when the
+ * aggregate subsystem is extracted into its own package.
+ *
+ * @internal
+ */
+interface AggregateStrategy {
+    /**
+     * Build an `Aggregation<R>` for `Query.aggregate(spec)`. `executeRecords`
+     * is a closure that produces the matching record set when the
+     * aggregation runs. NO_AGGREGATE throws; the active strategy
+     * constructs a real `Aggregation`.
+     */
+    aggregate<Spec extends AggregateSpec>(executeRecords: () => readonly unknown[], spec: Spec, upstreams: readonly AggregationUpstream[]): Aggregation<AggregateResult<Spec>>;
+    /**
+     * Build a `GroupedQuery<T, F>` for `Query.groupBy(field)`. Same
+     * closure / upstream inputs as `aggregate` plus the group key field.
+     */
+    groupBy<T, F extends string>(executeRecords: () => readonly unknown[], field: F, upstreams: readonly AggregationUpstream[], dictLabelResolver?: (key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>, moneyFields?: Record<string, MoneyDescriptor>): GroupedQuery<T, F>;
+    /**
+     * Variadic-keyed sibling — builds a `GroupedQueryN<T, F>` for
+     * `Query.groupBy(...fields)`. No dictLabelResolver — `<field>Label`
+     * projection only applies to single-field groupings, which dispatch
+     * through `groupBy` above.
+     */
+    groupByN<T, F extends readonly string[]>(executeRecords: () => readonly unknown[], fields: F, upstreams: readonly AggregationUpstream[], moneyFields?: Record<string, MoneyDescriptor>): GroupedQueryN<T, F>;
+    /**
+     * Terminal streaming aggregator for `ScanBuilder.aggregate(spec)`.
+     * Takes an async iterable of decrypted records + the spec and
+     * returns the reduced result.
+     */
+    scanAggregate<Spec extends AggregateSpec>(iter: AsyncIterable<unknown>, spec: Spec): Promise<AggregateResult<Spec>>;
+}
+
+export { BundleSealMismatchError as $, type AggregateStrategy as A, AmendmentForbiddenError as B, RecordLockedError as C, DictKeyInUseError as D, SnapshotNotFoundError as E, FieldFrozenError as F, GROUPBY_MAX_CARDINALITY as G, DerivationCapExceededError as H, InvariantError as I, DerivationCycleError as J, DerivationDepthError as K, LocaleNotSpecifiedError as L, MissingTranslationError as M, DerivationOutputShapeError as N, DerivationOutputUnknownError as O, OverlayBaseIsVirtualError as P, OverlayCollectionUnavailableError as Q, ReservedCollectionNameError as R, ScriptViolationError as S, TranslatorNotConfiguredError as T, OverlayIdMismatchError as U, OverlayNameCollisionError as V, AttestationError as W, AdoptionStateError as X, BackupCorruptedError as Y, BackupLedgerError as Z, BundleIntegrityError as _, DictKeyMissingError as a, ValidationError as a$, BundleVersionConflictError as a0, PartitionExtractionError as a1, TransferSealError as a2, MaterializedViewConfigError as a3, MaterializedViewCycleError as a4, MaterializedViewSourceUnknownError as a5, MaterializedViewTooLargeError as a6, NoydbError as a7, AlreadyElevatedError as a8, ConflictError as a9, NetworkError as aA, NoAccessError as aB, NonAdditiveSchemaChangeError as aC, NotFoundError as aD, PathEscapeError as aE, PeriodClosedError as aF, PermissionDeniedError as aG, PrivilegeEscalationError as aH, QuiesceTimeoutError as aI, ReadOnlyAtInstantError as aJ, ReadOnlyError as aK, ReadOnlyFrameError as aL, type RoundingMode as aM, SchemaFenceError as aN, SchemaLockedError as aO, SchemaUpdateError as aP, SchemaValidationError as aQ, SequenceContentionError as aR, SequenceOfflineError as aS, ShardProvisioningError as aT, StoreCapabilityError as aU, TamperedError as aV, TierDemoteDeniedError as aW, TierNotGrantedError as aX, UniqueConstraintError as aY, UnknownShardError as aZ, UnsupportedIndexOptionError as a_, CrossJoinSourceUnknownError as aa, CrossJoinTooLargeError as ab, DanglingReferenceError as ac, DecryptionError as ad, DelegationTargetMissingError as ae, DirectoryDisabledError as af, ElevationExpiredError as ag, ExportCapabilityError as ah, FilenameSanitizationError as ai, GroupCardinalityError as aj, ImportCapabilityError as ak, IndexRequiredError as al, IndexWriteFailureError as am, InvalidKeyError as an, JoinTooLargeError as ao, KeyringCorruptError as ap, KeyringExpiredError as aq, LedgerContentionError as ar, MigrationRequiredError as as, MoneyCurrencyError as at, type MoneyDescriptor as au, type MoneyOptions as av, type MoneyOptionsFixed as aw, type MoneyOptionsMulti as ax, MoneyPrecisionError as ay, MoneyUnsupportedError as az, SessionExpiredError as b, VaultTemplateNotFoundError as b0, isMoneyDescriptor as b1, money as b2, SessionNotFoundError as c, SessionPolicyError as d, type AggregateResult as e, type AggregateSpec as f, Aggregation as g, type AggregationUpstream as h, GROUPBY_WARN_CARDINALITY as i, GroupedAggregation as j, GroupedQuery as k, GroupedQueryN as l, type GroupedRow as m, type GroupedRowN as n, type LiveAggregation as o, type Reducer as p, type ReducerOptions as q, avg as r, buildLiveAggregation as s, count as t, groupAndReduce as u, max as v, min as w, reduceRecords as x, resetGroupByWarnings as y, sum as z };