@noy-db/hub 0.1.0-pre.10

package/dist/index-CLRxPs-W.d.cts

@@ -0,0 +1,1960 @@
+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';
+
+/**
+ * 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
+ *       │    ├─ 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
+ *       ├─ 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
+ * ```
+ *
+ * ## 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 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 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');
+}
+/**
+ * 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 (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 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 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 `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 `.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;
+    });
+}
+
+/**
+ * Foreign-key references — the soft-FK mechanism.
+ *
+ * A collection declares its references as metadata at construction
+ * time:
+ *
+ * ```ts
+ * import { ref } from '@noy-db/hub'
+ *
+ * const invoices = company.collection<Invoice>('invoices', {
+ *   refs: {
+ *     clientId: ref('clients'),            // default: strict
+ *     categoryId: ref('categories', 'warn'),
+ *     parentId:  ref('invoices', 'cascade'), // self-reference OK
+ *   },
+ * })
+ * ```
+ *
+ * Three modes:
+ *
+ *   - **strict** — the default. `put()` rejects records whose
+ *     reference target doesn't exist, and `delete()` of the target
+ *     rejects if any strict-referencing records still exist.
+ *     Matches SQL's default FK semantics.
+ *
+ *   - **warn** — both operations succeed unconditionally. Broken
+ *     references surface only through
+ *     `vault.checkIntegrity()`, which walks every collection
+ *     and reports orphans. Use when you want soft validation for
+ *     imports from messy sources.
+ *
+ *   - **cascade** — `put()` is same as warn. `delete()` of the
+ *     target deletes every referencing record. Cycles are detected
+ *     and broken via an in-progress set, so mutual cascades
+ *     terminate instead of recursing forever.
+ *
+ * Cross-vault refs are explicitly rejected: if the target
+ * name contains a `/`, `ref()` throws `RefScopeError`. Cross-
+ * vault refs need an auth story (multi-keyring reads) that
+ * doesn't ship — tracked for.
+ */
+
+/** The three enforcement modes. Default for new refs is `'strict'`. */
+type RefMode = 'strict' | 'warn' | 'cascade';
+/**
+ * Descriptor returned by `ref()`. Collections accept a
+ * `Record<string, RefDescriptor>` in their options. The key is the
+ * field name on the record (top-level only — dotted paths are out of
+ * scope), the value describes which target collection the
+ * field references and under what mode.
+ *
+ * The descriptor carries only plain data so it can be serialized,
+ * passed around, and introspected without any class machinery.
+ */
+interface RefDescriptor {
+    readonly target: string;
+    readonly mode: RefMode;
+}
+/**
+ * Thrown when a strict reference is violated — either `put()` with a
+ * missing target id, or `delete()` of a target that still has
+ * strict-referencing records.
+ *
+ * Carries structured detail so UI code (and a potential future
+ * devtools panel) can render "client X cannot be deleted because
+ * invoices 1, 2, and 3 reference it" instead of a bare error string.
+ */
+declare class RefIntegrityError extends NoydbError {
+    readonly collection: string;
+    readonly id: string;
+    readonly field: string;
+    readonly refTo: string;
+    readonly refId: string | null;
+    constructor(opts: {
+        collection: string;
+        id: string;
+        field: string;
+        refTo: string;
+        refId: string | null;
+        message: string;
+    });
+}
+/**
+ * Thrown when `ref()` is called with a target name that looks like
+ * a cross-vault reference (contains a `/`). Separate error
+ * class because the fix is different: RefIntegrityError means "data
+ * is wrong"; RefScopeError means "the ref declaration is wrong".
+ */
+declare class RefScopeError extends NoydbError {
+    constructor(target: string);
+}
+/**
+ * Helper constructor. Thin wrapper around the object literal so user
+ * code reads like `ref('clients')` instead of `{ target: 'clients',
+ * mode: 'strict' }` — this is the only ergonomics reason it exists.
+ *
+ * Validates the target name eagerly so a misconfigured ref declaration
+ * fails at collection construction time, not at the first put.
+ */
+declare function ref(target: string, mode?: RefMode): RefDescriptor;
+/**
+ * Per-vault registry of reference declarations.
+ *
+ * The registry is populated by `Collection` constructors (which pass
+ * their `refs` option through the Vault) and consulted by the
+ * Vault on every `put` / `delete` and by `checkIntegrity`. A
+ * single instance lives on the Vault for its lifetime; there's
+ * no global state.
+ *
+ * The data structure is two parallel maps:
+ *
+ *   - `outbound`: `collection → { field → RefDescriptor }` — what
+ *     refs does `collection` declare? Used on put to check
+ *     strict-target-exists and on checkIntegrity to walk each
+ *     collection's outbound refs.
+ *
+ *   - `inbound`:  `target → Array<{ collection, field, mode }>` —
+ *     which collections reference `target`? Used on delete to find
+ *     the records that might be affected by cascade / strict.
+ *
+ * The two views are kept in sync by `register()` and never mutated
+ * otherwise — refs can't be unregistered at runtime in.
+ */
+declare class RefRegistry {
+    private readonly outbound;
+    private readonly inbound;
+    /**
+     * Register the refs declared by a single collection. Idempotent in
+     * the happy path — calling twice with the same data is a no-op.
+     * Calling twice with DIFFERENT data throws, because silent
+     * overrides would be confusing ("I changed the ref and it doesn't
+     * update" vs "I declared the same collection twice with different
+     * refs and the second call won").
+     */
+    register(collection: string, refs: Record<string, RefDescriptor>): void;
+    /** Get the outbound refs declared by a collection (or `{}` if none). */
+    getOutbound(collection: string): Record<string, RefDescriptor>;
+    /** Get the inbound refs that target a given collection (or `[]`). */
+    getInbound(target: string): ReadonlyArray<{
+        collection: string;
+        field: string;
+        mode: RefMode;
+    }>;
+    /**
+     * Iterate every (collection → refs) pair that has at least one
+     * declared reference. Used by `checkIntegrity` to walk the full
+     * universe of outbound refs without needing to track collection
+     * names elsewhere.
+     */
+    entries(): Array<[string, Record<string, RefDescriptor>]>;
+    /** Clear the registry. Test-only escape hatch; never called from production code. */
+    clear(): void;
+}
+/**
+ * Shape of a single violation reported by `vault.checkIntegrity()`.
+ *
+ * `refId` is the value we saw in the referencing field — it's the
+ * ID we expected to find in `refTo`, but didn't. Left as `unknown`
+ * because records are loosely typed at the integrity-check layer.
+ */
+interface RefViolation {
+    readonly collection: string;
+    readonly id: string;
+    readonly field: string;
+    readonly refTo: string;
+    readonly refId: unknown;
+    readonly mode: RefMode;
+}
+
+/**
+ * Query DSL `.join()` — eager, single-FK, intra-vault joins.
+ *
+ * resolves a ref()-declared foreign key into an attached
+ * right-side record under an alias, using one of two planner paths
+ * selected automatically:
+ *
+ *   - **nested-loop** — right-side source exposes `lookupById`, so
+ *     each left row costs O(1). This is the common path for joins
+ *     against a Collection, which backs `lookupById` with a Map
+ *     lookup.
+ *   - **hash** — right-side has only `snapshot()`. Build a
+ *     `Map<id, record>` once, probe per left row. Same asymptotic
+ *     cost for our collections, but the path exists as a fallback
+ *     for custom QuerySource implementations and as an explicit
+ *     test-only override via `{ strategy: 'hash' }`.
+ *
+ * Scope:
+ *
+ *   - Equi-joins on declared `ref()` fields only. Joins on
+ *     undeclared fields throw at plan time with an actionable error
+ *     naming the field and collection.
+ *   - Same-vault only. Cross-vault correlation goes
+ *     through `queryAcross`; this is an architectural
+ *     invariant, not a limitation we plan to lift.
+ *   - Hard row ceiling via `JoinTooLargeError` — default 50k per
+ *     side, override via `{ maxRows }`. Warns at 80% of the ceiling
+ *     on the existing warn channel.
+ *   - Three ref-mode behaviors on dangling refs:
+ *     strict → `DanglingReferenceError`,
+ *     warn → attach `null` with a one-shot warning,
+ *     cascade → attach `null` silently (cascade is a delete-time
+ *     mode; any dangling refs still present at read time are
+ *     mid-flight cascades or orphans from earlier, not a DSL error).
+ *
+ * Partition-awareness seam:
+ *
+ * Every `JoinLeg` carries a `partitionScope` field that is always
+ * `'all'` in. The executor never reads this field.
+ * partition-aware joins will start populating it from `where()`
+ * predicates on the partition key without changing the planner's
+ * external shape — this is the whole reason it exists now.
+ *
+ * Joins stay OUT of the ledger: reads don't touch `_ledger/`,
+ * including joined reads.
+ */
+
+/** Planner strategy for a single join leg. Auto-selected unless overridden. */
+type JoinStrategy = 'hash' | 'nested';
+/** Default per-side row ceiling before `.join()` throws `JoinTooLargeError`. */
+declare const DEFAULT_JOIN_MAX_ROWS = 50000;
+/**
+ * Internal representation of a single join leg in the query plan.
+ *
+ * This is the primary place where  constraint #1 is honored:
+ * every leg carries a `partitionScope` field that is always `'all'`
+ * in and is never read by the executor. partition-aware
+ * joins will start populating it from `where()` predicates on the
+ * partition key without changing the planner's external shape.
+ */
+interface JoinLeg {
+    /** Field on the left-side record holding the foreign key value. */
+    readonly field: string;
+    /** Alias key under which the joined right-side record attaches. */
+    readonly as: string;
+    /** Target collection name, resolved from the `ref()` declaration. */
+    readonly target: string;
+    /** Ref mode controlling behavior on dangling refs at read time. */
+    readonly mode: RefMode;
+    /** Manual planner strategy override. `undefined` → auto-select. */
+    readonly strategy: JoinStrategy | undefined;
+    /** Per-side row ceiling override. `undefined` → DEFAULT_JOIN_MAX_ROWS. */
+    readonly maxRows: number | undefined;
+    /**
+     * Partition scope for future partition-aware joins. Always `'all'`
+     * today — the executor never reads this field. Future versions will
+     * populate it from `where()` predicates without breaking the
+     * planner's external shape. Do not remove even though it looks
+     * unused today — that's the whole point of having it.
+     */
+    readonly partitionScope: 'all' | readonly string[];
+    /**
+     * When `true`, this is a dictionary join. The executor
+     * resolves the left-field value against the dict snapshot and
+     * attaches `{ ...labels, key }` rather than a right-side record.
+     * `target` holds the dictionary name (not a collection name).
+     */
+    readonly isDictJoin?: true;
+}
+/**
+ * Minimal shape of a joinable right-side record source.
+ *
+ * Collections implement this structurally via their `QuerySource`;
+ * sources without `lookupById` force the hash-join fallback. Kept as
+ * a thin interface so tests can wire up plain-object sources without
+ * pulling in the full Collection class.
+ *
+ * The optional `subscribe` is used by `Query.live()` to merge
+ * right-side change streams into the live re-run trigger. Sources
+ * that omit `subscribe` still work for live joins — they just
+ * don't drive re-fires when their right side mutates. Collection
+ * implements `subscribe` by hooking into the existing per-
+ * vault event emitter.
+ */
+interface JoinableSource {
+    snapshot(): readonly unknown[];
+    lookupById?(id: string): unknown;
+    /**
+     * Subscribe to mutations on this source. The callback fires
+     * AFTER the underlying record set has been updated. Returns an
+     * unsubscribe function. Optional — sources without this method
+     * cannot trigger live-join re-fires from their side.
+     */
+    subscribe?(cb: () => void): () => void;
+}
+/**
+ * Join resolution context attached to a `Query` when it's constructed
+ * from a `Collection`. Holds everything the `.join()` method needs to
+ * translate a field name into a target collection + ref mode, and
+ * everything the executor needs to read the right side.
+ *
+ * Kept as a structural interface so `Vault` can implement it
+ * without `Query` needing to import `Vault` (circular-import
+ * avoid). The Collection wires this up in its `query()` method using
+ * the `joinResolver` back-reference the Vault passes in.
+ */
+interface JoinContext {
+    /** Name of the left-side (owning) collection. */
+    readonly leftCollection: string;
+    /** Look up a `RefDescriptor` by field name on the left collection. */
+    resolveRef(field: string): RefDescriptor | null;
+    /** Resolve a right-side source by target collection name. */
+    resolveSource(collectionName: string): JoinableSource | null;
+    /**
+     * Resolve a dictKey join source. Returns a `JoinableSource`
+     * whose snapshot exposes `{ key, ...labels }` records, keyed by the
+     * stable dictionary key. `null` when the field is not a dictKey.
+     *
+     * The source is built from the compartment's in-memory dictionary
+     * snapshot — same data as `DictionaryHandle.list()`, O(1) per lookup.
+     */
+    resolveDictSource?(field: string): JoinableSource | null;
+}
+/**
+ * Apply every join leg in the plan against a base set of left-side
+ * rows. Called by the query executor after `where` / `orderBy` /
+ * `offset` / `limit` have narrowed the left set.
+ *
+ * Each leg attaches a `leg.as` field to every row. Returns a new
+ * array of plain objects — the original left rows are not mutated
+ * (structural sharing is fine for the inner fields, but the
+ * top-level object is a fresh clone so consumers can further mutate
+ * safely).
+ *
+ * **Ordering:** joins run AFTER orderBy / limit / offset in v1.
+ * This keeps the planner simple and means queries like "top 10
+ * invoices with client" sort and paginate the left side first, then
+ * join. Sorting *by* a joined field is out of scope for  — users
+ * can post-sort the result array in userland or wait for
+ * (multi-FK chaining) which can be layered on top.
+ *
+ * **Multi-FK chaining:** each leg's `maxRows` is enforced
+ * against the current left-row count independently. Because
+ * joins are equi-joins on the target's primary key (one-to-one or
+ * one-to-null), the left row count is constant across legs — no
+ * cartesian blowup. The per-leg left-side check is still necessary
+ * so that a later leg with a tighter ceiling correctly fires on a
+ * query like `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`,
+ * which should throw on the second leg if the left set exceeds 50.
+ */
+declare function applyJoins(rows: readonly unknown[], joins: readonly JoinLeg[], context: JoinContext): unknown[];
+/**
+ * Test-only: reset the join warning deduplication state between
+ * tests. Production code never calls this — the dedup state is
+ * intentionally process-scoped so a noisy query doesn't spam the
+ * console once per component render.
+ */
+declare function resetJoinWarnings(): void;
+
+/**
+ * Reactive query primitive — `query.live()`.
+ *
+ * produces a `LiveQuery<T>` that re-runs the query and
+ * updates its `value` whenever any source feeding it (the left
+ * collection AND every right-side collection a join leg points at)
+ * mutates.
+ *
+ * Framework-agnostic by design. The Vue layer wraps a `LiveQuery`
+ * in a Vue `Ref<T[]>` by subscribing once and copying `value` into
+ * the ref on every notification. React/Solid/Svelte adapters do the
+ * same with their own primitives. Core never depends on a UI
+ * framework.
+ *
+ * **Error semantics.** A `.live()` query may throw at re-run time —
+ * a strict-mode `DanglingReferenceError` is the most common case
+ * (a right-side record was deleted out-of-band, leaving a left
+ * row's FK pointing at nothing). When the re-run throws, the
+ * `LiveQuery` catches the error and stores it in the `error`
+ * field; it does NOT propagate the throw out of the source's
+ * change handler, because doing so would tear down whatever
+ * upstream emitter is dispatching. Listeners check `error` after
+ * each notification and render an error state in the UI.
+ *
+ * **Dedup of right-side subscriptions.** A multi-FK chain that
+ * joins the same target twice (e.g.
+ * `.join('billingClientId').join('shippingClientId')`, both
+ * pointing at `clients`) only subscribes to that target once. We
+ * dedup by target collection name, on the assumption that
+ * `resolveSource(name)` returns a single subscribable source per
+ * vault + name. Vault's `resolveSource` reads from
+ * `collectionCache` so this assumption holds.
+ *
+ * **What .live() does NOT do in v1:**
+ *   - No granular delta updates — the whole query re-runs on every
+ *     change. Granular delta tracking is a v2 optimization once
+ *     the API is stable.
+ *   - No batching of bursty changes — one event in, one re-run
+ *     out. Batching with microtask coalescing is a v2 enhancement.
+ *   - No async notifications — every notification is synchronous
+ *     within the source's change handler.
+ *   - No re-planning under live mutations — the planner picks once
+ *     at subscription time and reuses the same plan for every
+ *     re-run.
+ */
+/**
+ * The reactive primitive returned by `Query.live()`.
+ *
+ * Listeners can read the current `value` snapshot at any time and
+ * subscribe to changes via `.subscribe(cb)`. The `error` field
+ * carries the most recent re-run error, if any — read it after
+ * each notification to render error state.
+ *
+ * Always call `stop()` when the live query is no longer needed.
+ * Without it, the upstream change-stream subscriptions stay live
+ * forever and the query keeps re-running on every mutation.
+ */
+interface LiveQuery<T> {
+    /**
+     * Current snapshot of the query result. Updated in place on
+     * every upstream change. The reference returned is the same
+     * `readonly T[]` array — consumers that want change detection by
+     * reference should copy: `const arr = [...live.value]`.
+     */
+    readonly value: readonly T[];
+    /**
+     * Most recent re-run error, or `null` on success. Set when the
+     * executor throws (e.g. `DanglingReferenceError` in strict mode
+     * after a right-side delete). Cleared on the next successful
+     * re-run.
+     */
+    readonly error: Error | null;
+    /**
+     * Register a notification callback. Fires AFTER `value` and
+     * `error` have been updated for a given upstream change.
+     * Returns an unsubscribe function.
+     *
+     * The first call to `subscribe` does NOT fire the callback
+     * immediately — call sites that want the initial value should
+     * read `live.value` directly before subscribing.
+     */
+    subscribe(cb: () => void): () => void;
+    /**
+     * Tear down every upstream subscription and clear the listener
+     * set. Idempotent — calling twice is safe. After `stop()`, the
+     * query no longer re-runs and `subscribe()` becomes a no-op
+     * (the returned unsubscribe is still callable and is also a
+     * no-op).
+     */
+    stop(): void;
+}
+/**
+ * Internal subscription handle for an upstream source — left or
+ * right side. The contract is just `subscribe(cb): unsubscribe`,
+ * matching the existing `QuerySource.subscribe` and the new
+ * `JoinableSource.subscribe` (added in ).
+ */
+interface LiveUpstream {
+    subscribe(cb: () => void): () => void;
+}
+/**
+ * Build a LiveQuery from a `recompute` callback (typically the
+ * Query's bound `toArray`) and a list of upstream sources to
+ * subscribe to.
+ *
+ * The recompute fires once synchronously to populate the initial
+ * value, then re-fires every time any upstream notifies. Errors
+ * thrown by recompute are caught and stored in `error` instead of
+ * propagating — see the file docstring for the rationale.
+ */
+declare function buildLiveQuery<T>(recompute: () => T[], upstreams: readonly LiveUpstream[]): LiveQuery<T>;
+
+/**
+ * Chainable, immutable query builder.
+ *
+ * Each builder operation returns a NEW Query — the underlying plan is never
+ * mutated. This makes plans safe to share, cache, and serialize.
+ */
+
+interface OrderBy {
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+/**
+ * A complete query plan: zero-or-more clauses, optional ordering, pagination,
+ * and optional joins.
+ *
+ * Plans are JSON-serializable as long as no FilterClause is present and no
+ * join leg carries a manual `strategy` override (JoinLeg itself is plain
+ * data, so it serializes cleanly).
+ *
+ * Plans are intentionally NOT parametric on T — see `predicate.ts` FilterClause
+ * for the variance reasoning. The public `Query<T>` API attaches the type tag.
+ */
+interface QueryPlan {
+    readonly clauses: readonly Clause[];
+    readonly orderBy: readonly OrderBy[];
+    readonly limit: number | undefined;
+    readonly offset: number;
+    /**
+     * Zero-or-more join legs to apply after where/orderBy/limit/offset.
+     * Each leg attaches a resolved right-side record (or null) under its
+     * alias. See `query/join.ts` for the full semantics.
+     */
+    readonly joins: readonly JoinLeg[];
+}
+/**
+ * Source of records that a query executes against.
+ *
+ * The interface is non-parametric to keep variance friendly: callers cast
+ * their typed source (e.g. `QuerySource<Invoice>`) into this opaque shape.
+ *
+ * `getIndexes` and `lookupById` are optional fast-path hooks. When both are
+ * present and a where clause matches an indexed field, the executor uses
+ * the index to skip a linear scan. Sources without these methods (or with
+ * `getIndexes` returning `null`) always fall back to a linear scan.
+ */
+interface QuerySource<T> {
+    /** Snapshot of all current records. The query never mutates this array. */
+    snapshot(): readonly T[];
+    /** Subscribe to mutations; returns an unsubscribe function. */
+    subscribe?(cb: () => void): () => void;
+    /** Index store for the indexed-fast-path. Optional. */
+    getIndexes?(): CollectionIndexes | null;
+    /** O(1) record lookup by id, used to materialize index hits. */
+    lookupById?(id: string): T | undefined;
+}
+/**
+ * The chainable builder. All methods return a new Query — the original
+ * remains unchanged. Terminal methods (`toArray`, `first`, `count`,
+ * `subscribe`) execute the plan against the source.
+ *
+ * Type parameter T flows through the public API for ergonomics, but the
+ * internal storage uses `unknown` so Collection<T> stays covariant.
+ *
+ * The optional `joinContext` is attached when the Query is constructed
+ * via `Collection.query()` (Collection passes in a context built from
+ * the Vault's join resolver). A Query constructed via `new Query`
+ * directly — e.g. from tests with a plain-object source — has no
+ * joinContext, and calling `.join()` on it throws with an actionable
+ * error. See `query/join.ts` for the full design.
+ */
+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);
+    /** Add a field comparison. Multiple where() calls are AND-combined. */
+    where(field: string, op: Operator, value: unknown): Query<T>;
+    /**
+     * Logical OR group. Pass a callback that builds a sub-query.
+     * Each clause inside the callback is OR-combined; the group itself
+     * joins the parent plan with AND.
+     */
+    or(builder: (q: Query<T>) => Query<T>): Query<T>;
+    /**
+     * Logical AND group. Same shape as `or()` but every clause inside the group
+     * must match. Useful for explicit grouping inside a larger OR.
+     */
+    and(builder: (q: Query<T>) => Query<T>): Query<T>;
+    /** Escape hatch: add an arbitrary predicate function. Not serializable. */
+    filter(fn: (record: T) => boolean): Query<T>;
+    /** Sort by a field. Subsequent calls are tie-breakers. */
+    orderBy(field: string, direction?: 'asc' | 'desc'): Query<T>;
+    /** Cap the result size. */
+    limit(n: number): Query<T>;
+    /** Skip the first N matching records (after ordering). */
+    offset(n: number): Query<T>;
+    /**
+     * Resolve a `ref()`-declared foreign key and attach the right-side
+     * record under `opts.as`. — eager, single-FK, intra-
+     * vault joins.
+     *
+     * ```ts
+     * const rows = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .join('clientId', { as: 'client' })
+     *   .toArray()
+     * // → [{ id, amount, client: { id, name, ... } }, ...]
+     * ```
+     *
+     * Preconditions:
+     *   - The Query must have a `joinContext` (constructed via
+     *     `Collection.query()`, not `new Query`).
+     *   - `field` must have a matching `refs: { [field]: ref('<target>') }`
+     *     declaration on the left collection.
+     *   - The target collection must be reachable via the vault
+     *     (either currently open or openable on demand).
+     *
+     * Strategy:
+     *   - Nested-loop against `lookupById` when the target source
+     *     provides it (the common path for Collection targets).
+     *   - Hash join otherwise, or when `{ strategy: 'hash' }` is
+     *     explicitly passed for test purposes.
+     *
+     * Ref-mode semantics on dangling refs (left record has a non-null
+     * FK value pointing at a right-side id that doesn't exist):
+     *   - `strict`  → throws `DanglingReferenceError` with the full
+     *     field / target / refId context.
+     *   - `warn`    → attaches `null` and emits a one-shot warning per
+     *     unique dangling pair.
+     *   - `cascade` → attaches `null` silently. Cascade is a
+     *     delete-time mode; dangling refs visible at read time are
+     *     either mid-flight cascades or pre-existing orphans, not a
+     *     DSL-level error.
+     *
+     * A left-side record whose FK field is `null` / `undefined` is NOT
+     * a dangling ref — it's "no reference at all", always allowed
+     * regardless of mode.
+     *
+     * The return type widens `T` with `Record<As, R | null>`. The `R`
+     * parameter is optional — supply it explicitly for type-checked
+     * access to the joined fields:
+     *
+     * ```ts
+     * invoices.query().join<'client', Client>('clientId', { as: 'client' })
+     * //                 ^^^^^^^^^^^^^^^^^^^ alias literal + right-side type
+     * ```
+     *
+     * Without the generic, the joined field is typed as `unknown`, which
+     * still works but requires a cast to access its properties.
+     *
+     * Joins stay intra-vault by construction — cross-vault
+     * correlation goes through `Noydb.queryAcross`, not
+     * `.join()`.
+     */
+    join<As extends string, R = unknown>(field: string, opts: {
+        as: As;
+        strategy?: JoinStrategy;
+        maxRows?: number;
+    }): Query<T & Record<As, R | null>>;
+    /**
+     * Execute the plan and return the matching records. When the plan
+     * carries any join legs, they are applied after `where` / `orderBy`
+     * / `limit` / `offset` narrow the left set. See the `.join()` doc
+     * for the ordering rationale.
+     */
+    toArray(): T[];
+    /** Return the first matching record, or null. Joins are applied. */
+    first(): T | null;
+    /**
+     * Return the number of matching records (after where/filter,
+     * before limit). **Joins are NOT applied** — count() reports the
+     * left-side cardinality, because joins in are projection-only
+     * (they attach an aliased field; they never filter). Running joins
+     * here just to discard the aliases would be wasteful, and in strict
+     * mode it could throw `DanglingReferenceError` for a call whose
+     * intent is purely to count.
+     */
+    count(): number;
+    /**
+     * Reduce the matching records through a named set of reducers.
+     * the aggregation terminal.
+     *
+     * ```ts
+     * const { total, n, avgAmount } = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .aggregate({
+     *     total:     sum('amount'),
+     *     n:         count(),
+     *     avgAmount: avg('amount'),
+     *   })
+     *   .run()
+     * ```
+     *
+     * Returns an `Aggregation<R>` wrapper with two terminals:
+     *   - `.run(): R` — synchronous one-shot reduction
+     *   - `.live(): LiveAggregation<R>` — reactive primitive that
+     *     re-runs the reduction whenever the source notifies of a
+     *     change. Always call `live.stop()` when finished.
+     *
+     * The reducer spec is bound here once and reused by both
+     * terminals — this is why `.aggregate()` returns a wrapper instead
+     * of being a direct terminal. Consumers who only need the static
+     * value read `.run()`; consumers wiring a reactive UI read
+     * `.live()`.
+     *
+     * Joins are intentionally NOT applied to aggregations in —
+     * the same logic as `.count()`. Joins in are projection-only
+     * (they attach an aliased field and never filter), so running
+     * them just to throw the aliases away would be wasteful. If you
+     * need a reducer that reads a joined field, open an issue —
+     * aggregations-across-joins is explicitly out of scope for v1.
+     *
+     * Every reducer factory accepts an optional `{ seed }` parameter
+     * that is plumbed through the protocol but unused by the
+     * executor — that's  constraint #2. When partition-aware
+     * aggregation lands, the seed will carry running state across
+     * partition boundaries without an API break.
+     */
+    aggregate<Spec extends AggregateSpec>(spec: Spec): Aggregation<AggregateResult<Spec>>;
+    /**
+     * Partition matching records into buckets keyed by a field, then
+     * terminate with `.aggregate(spec)` to compute per-bucket
+     * reducers..
+     *
+     * ```ts
+     * const byClient = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .groupBy('clientId')
+     *   .aggregate({ total: sum('amount'), n: count() })
+     *   .run()
+     * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
+     * ```
+     *
+     * Result rows carry the group key value under the grouping field
+     * name plus every reducer output from the spec. Buckets are
+     * emitted in first-seen order — consumers who want a specific
+     * ordering should `.sort()` downstream.
+     *
+     * **Cardinality caps:** a one-shot warning fires at 10_000
+     * distinct groups; `GroupCardinalityError` throws at 100_000.
+     * Grouping on a high-uniqueness field like `id` or `createdAt` is
+     * almost always a query mistake — the error message names the
+     * field and observed cardinality and suggests narrowing with
+     * `.where()` first.
+     *
+     * **Null / undefined keys:** records with a missing or explicitly
+     * `null` group field get their own buckets. `Map`-based
+     * partitioning distinguishes `undefined` from `null`, so the two
+     * cases do NOT merge. Consumers who want them merged should
+     * coalesce upstream with `.filter()`.
+     *
+     * **Joins are not applied** — same rationale as `.count()` and
+     * `.aggregate()`. Joined fields in are projection-only, so
+     * running a join inside a grouping pipeline would be wasteful and
+     * could trigger `DanglingReferenceError` in strict mode for a
+     * call whose intent is purely to bucket-and-reduce. Grouping by
+     * a joined field is explicitly out of scope for — file an
+     * issue if a real consumer needs it.
+     *
+     * **Filter clauses (`.filter(fn)`):** grouped queries still
+     * support filter clauses in the underlying plan — they run in
+     * the same candidate/filter pipeline that `.aggregate()` uses.
+     * The performance caveat is the same: filter clauses cost O(N)
+     * per record and can't be index-accelerated.
+     */
+    groupBy<F extends string>(field: F): GroupedQuery<T, F>;
+    /**
+     * Re-run the query whenever the source notifies of changes.
+     * Returns an unsubscribe function. The callback receives the latest result.
+     * Throws if the source does not support subscriptions.
+     *
+     * **For joined queries, prefer `.live()`** — `subscribe()`
+     * only re-fires on LEFT-side changes, so joined data can be
+     * stale if the right side mutates between emissions. `.live()`
+     * merges change streams from every join target.
+     */
+    subscribe(cb: (result: T[]) => void): () => void;
+    /**
+     * Reactive terminal — returns a `LiveQuery<T>` that re-runs the
+     * query and updates its `value` whenever any source feeding it
+     * mutates..
+     *
+     * For non-joined queries, `.live()` is a convenience over the
+     * existing `.subscribe()` callback shape: a hand-rolled reactive
+     * primitive with `value` / `error` fields and a `subscribe(cb)`
+     * notification channel. Frame-agnostic — Vue / React / Solid
+     * adapters wrap it in their own primitive.
+     *
+     * For joined queries, `.live()` additionally subscribes to every
+     * join target's change stream. Mutations on a right-side
+     * collection (insert / update / delete of a client referenced by
+     * an invoice) re-fire the live query and re-evaluate every
+     * dependent left row. Right-side targets are deduped by
+     * collection name, so a chain that joins the same target twice
+     * (e.g. billing client + shipping client → both 'clients') only
+     * subscribes once.
+     *
+     * **Ref-mode behavior on right-side disappearance** — matches the
+     * eager `.toArray()` contract from :
+     *   - `strict`  → re-run throws `DanglingReferenceError`. The
+     *     LiveQuery catches the throw, stores it in `live.error`, and
+     *     notifies listeners (the throw does NOT propagate out of
+     *     the source's change handler — that would tear down the
+     *     emitter). Consumers check `live.error` after each
+     *     notification and render an error state in the UI.
+     *   - `warn`    → joined value flips to `null`; the existing
+     *     warn-channel deduplication keeps repeated re-runs from
+     *     spamming the console.
+     *   - `cascade` → no special handling needed; the cascade-
+     *     delete mechanism propagates the right-side delete into the
+     *     left collection on the next tick, and the live query
+     *     naturally re-fires with the orphaned left rows gone.
+     *
+     * Always call `live.stop()` when finished — it tears down every
+     * upstream subscription. The Vue layer's `onUnmounted` hook
+     * should call `stop()` automatically; raw consumers must do it
+     * themselves.
+     *
+     * **Limitations:**
+     *   - No granular delta updates — the whole query re-runs on
+     *     every change.
+     *   - No microtask batching — bursty changes produce one re-run
+     *     per change.
+     *   - No re-planning under live mutations — the planner picks
+     *     once at subscription time and reuses the same plan.
+     *   - Streaming live joins are deferred.
+     */
+    live(): LiveQuery<T>;
+    /**
+     * Return the plan as a JSON-friendly object. FilterClause entries are
+     * stripped (their `fn` cannot be serialized) and replaced with
+     * { type: 'filter', fn: '[function]' } so devtools can still see them.
+     */
+    toPlan(): unknown;
+}
+/**
+ * Execute a plan against a snapshot of records.
+ * Pure function — same input, same output, no side effects.
+ *
+ * Records are typed as `unknown` because plans are non-parametric; callers
+ * cast the return type at the API surface (see `Query.toArray()`).
+ */
+declare function executePlan(records: readonly unknown[], plan: QueryPlan): unknown[];
+
+/**
+ * Streaming scan builder with filter + aggregate support.
+ *
+ * `Collection.scan()` now returns a `ScanBuilder<T>` that
+ * implements `AsyncIterable<T>` (for existing `for await … of`
+ * consumers) AND exposes chainable `.where()` / `.filter()` clauses
+ * plus a `.aggregate(spec)` async terminal that reduces the scan
+ * stream through the same reducer protocol as `Query.aggregate()`
+ *.
+ *
+ * **Memory model:** O(reducers), not O(records). The aggregate
+ * terminal initializes one state per reducer, iterates through the
+ * scan one record at a time via `for await`, applies every reducer's
+ * `step` per record, and never collects the stream into an array.
+ * This is what makes `scan().aggregate()` suitable for collections
+ * that don't fit in memory — the bound is a code-level invariant
+ * visible in the function body, not a runtime assertion.
+ *
+ * **Paginated iteration:** the builder holds a `pageProvider`
+ * closure that maps `(cursor, limit) → Promise<page>`, plumbed by
+ * `Collection.scan()` to `collection.listPage(...)`. The page
+ * iterator walks cursors forward until exhaustion, same as the
+ * previous async-generator `scan()` did.
+ *
+ * **Backward compatibility:** existing `for await (const rec of
+ * collection.scan()) { … }` code continues to work because
+ * `ScanBuilder` implements `[Symbol.asyncIterator]`. The previous
+ * signature returned an `AsyncIterableIterator<T>` (which has both
+ * `[Symbol.asyncIterator]` and `.next()`). We verified at grep time
+ * that no call sites use `.next()` on the scan result directly, so
+ * the narrowed interface is safe.
+ *
+ * **Immutability:** each `.where()` / `.filter()` call returns a
+ * fresh builder sharing the same page provider and page size. This
+ * lets a base scan be reused for multiple parallel aggregations:
+ *
+ * ```ts
+ * const scan = invoices.scan()
+ * const [open, paid] = await Promise.all([
+ *   scan.where('status', '==', 'open').aggregate({ n: count() }),
+ *   scan.where('status', '==', 'paid').aggregate({ n: count() }),
+ * ])
+ * ```
+ *
+ * Note that each aggregation pays a full scan — there's no shared
+ * iteration across the two. Multi-way aggregation in a single pass
+ * is out of scope; consumers who need it should build a compound spec
+ * and run a single `.aggregate({ openN, paidN })` at the DSL level.
+ *
+ * **Out of scope for (tracked separately):**
+ *   - `scan().aggregate().live()` — unbounded scan + change-stream
+ *     reconciliation is a design problem, not just a code one
+ *   - `scan().groupBy().aggregate()` — high-cardinality grouping on
+ *     huge collections would re-introduce the O(groups) memory
+ *     problem that aggregate fixes
+ *   - Parallel scan across pages — race-safe page cursor contracts
+ *     are not in the adapter API yet
+ *   - `scan().join(...)` — tracked under  (streaming join)
+ */
+
+/**
+ * Page provider — the Collection-shaped hook the builder calls to
+ * walk cursors forward. Kept as a structural interface so tests can
+ * wire up a synthetic provider without pulling in the full
+ * Collection class. Collection's `listPage` matches this shape
+ * exactly.
+ */
+interface ScanPageProvider<T> {
+    listPage(opts: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        nextCursor: string | null;
+    }>;
+}
+/**
+ * Chainable streaming scan. Implements `AsyncIterable<T>` for
+ * drop-in use with `for await … of`; adds `.where()` / `.filter()`
+ * chainable clauses and a `.aggregate(spec)` async terminal.
+ *
+ * The builder is immutable per operation — each chained call
+ * returns a fresh `ScanBuilder` sharing the same page provider and
+ * page size. The original builder is never mutated, so it's safe
+ * to reuse across multiple parallel consumers.
+ */
+declare class ScanBuilder<T> implements AsyncIterable<T> {
+    private readonly pageProvider;
+    private readonly pageSize;
+    private readonly clauses;
+    /**
+     * Zero-or-more join legs to apply per record as the stream flows.
+     * Each leg attaches the resolved right-side record (or null) under
+     * its alias. — streaming joins.
+     *
+     * Joins are evaluated AFTER clauses, so a `where()` filtered-out
+     * record never triggers a right-side lookup. This is the same
+     * ordering as `Query.toArray()` (clauses first, joins after) and
+     * keeps the streaming path from doing wasted work.
+     */
+    private readonly joins;
+    /**
+     * Join resolution context. Required for `.join()` to translate a
+     * field name into a target collection + ref mode and to resolve
+     * the right-side `JoinableSource`. Optional because tests
+     * construct ScanBuilder directly with synthetic page providers
+     * that don't know about ref() — calling `.join()` without a
+     * context throws with an actionable error.
+     */
+    private readonly joinContext;
+    constructor(pageProvider: ScanPageProvider<T>, pageSize?: number, clauses?: readonly Clause[], joins?: readonly JoinLeg[], joinContext?: JoinContext);
+    /**
+     * Add a field comparison. Runs per record as the scan stream
+     * flows through, so non-matching records are dropped before they
+     * reach `.aggregate()` or the iteration consumer. Multiple
+     * `.where()` calls are AND-combined — same semantics as
+     * `Query.where()`.
+     *
+     * Clauses cannot use the secondary-index fast path here because
+     * the scan sources records from the adapter's paginator, not from
+     * the in-memory cache where indexes live. Index-accelerated scans
+     * are a future optimization — the current implementation
+     * evaluates clauses per record in O(1) per clause.
+     */
+    where(field: string, op: Operator, value: unknown): ScanBuilder<T>;
+    /**
+     * Escape hatch: add an arbitrary predicate function. Same
+     * non-serializable caveat as `Query.filter()` — filter clauses
+     * don't round-trip through `toPlan()`. Prefer `.where()` when
+     * possible.
+     */
+    filter(fn: (record: T) => boolean): ScanBuilder<T>;
+    /**
+     * Resolve a `ref()`-declared foreign key per record as the scan
+     * stream flows, attaching the right-side record (or null) under
+     * `opts.as`. — streaming joins over `scan()`.
+     *
+     * ```ts
+     * for await (const inv of invoices.scan().join('clientId', { as: 'client' })) {
+     *   await processInvoice(inv) // inv.client is attached
+     * }
+     *
+     * // Or terminate with .aggregate() for streaming joined aggregation
+     * const { total } = await invoices.scan()
+     *   .where('status', '==', 'open')
+     *   .join('clientId', { as: 'client' })
+     *   .aggregate({ total: sum('amount') })
+     * ```
+     *
+     * **The key difference from eager `.join()`:** the LEFT
+     * side streams page-by-page from the adapter and is never
+     * materialized. Memory ceiling on the left is O(pageSize), not
+     * O(rowCount). This is what makes streaming joins suitable for
+     * collections that exceed the eager join's 50_000-row ceiling.
+     *
+     * **Right-side strategy** is auto-selected per leg:
+     *   - **Indexed** — right source exposes `lookupById`, so each
+     *     left row costs O(1). This is the common path for
+     *     Collection right sides, which back `lookupById` with a Map
+     *     lookup over the in-memory cache. The right collection must
+     *     be in eager mode (the same constraint as eager join's
+     *     `querySourceForJoin` from ).
+     *   - **Hash** — right source has only `snapshot()`. Build a
+     *     `Map<id, record>` once at iteration start, probe per left
+     *     row. Same correctness, same per-row cost as the indexed
+     *     path; the difference is the upfront cost of materializing
+     *     the right side once.
+     *
+     * Both strategies hold the right side in memory for the duration
+     * of the iteration. The "streaming" property applies to the LEFT
+     * side only — true left-and-right streaming joins (where neither
+     * side fits in memory) require a sort-merge join planner that's
+     * out of scope for.
+     *
+     * **Ref-mode semantics** match eager `.join()` exactly:
+     *   - `strict`  → throws `DanglingReferenceError` mid-stream
+     *     when a left record points at a non-existent right id.
+     *     The throw aborts the async iterator — consumers should
+     *     wrap the `for await` in try/catch if they want to recover.
+     *   - `warn`    → attaches `null` and emits a one-shot warning
+     *     per unique dangling pair (deduped via the same warn
+     *     channel as eager join).
+     *   - `cascade` → attaches `null` silently. A delete-time mode;
+     *     dangling refs at read time are mid-flight or pre-existing
+     *     orphans, not a DSL error.
+     *
+     * Left records with null/undefined FK values attach `null`
+     * regardless of mode — same "no reference at all" policy as
+     * eager join and write-time `enforceRefsOnPut`.
+     *
+     * **Multi-FK chaining** is supported via repeated `.join()`
+     * calls: each leg resolves an independent ref. Each leg
+     * independently picks its right-side strategy and applies its
+     * own ref mode.
+     *
+     * **Joins are NOT applied** to a `.aggregate()` terminal that
+     * doesn't reference joined fields — wait, that's not quite
+     * right. The streaming path actually DOES apply joins before
+     * `.aggregate()` because the join attaches a field that the
+     * spec might reference. Unlike `Query.aggregate()` (which skips
+     * joins entirely as a projection-only short-circuit), the
+     * streaming aggregation can't know whether the spec touches a
+     * joined field, so it always applies joins. Consumers who want
+     * unjoined streaming aggregation should leave `.join()` off the
+     * chain — the chain is composable for a reason.
+     *
+     *  constraint #1 — every JoinLeg carries `partitionScope:
+     * 'all'` plumbed through but never read by. Same seam as
+     * eager join.
+     */
+    join<As extends string, R = unknown>(field: string, opts: {
+        as: As;
+    }): ScanBuilder<T & Record<As, R | null>>;
+    /**
+     * Iterate the scan as an async iterable. Walks the page
+     * provider's cursors forward until exhaustion, applying every
+     * clause per record — only matching records are yielded.
+     *
+     * Backward-compatible with the previous async-generator `scan()`
+     * return type for `for await … of` consumers.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /**
+     * Per-leg right-side resolution state. Built once at iteration
+     * start and reused for every left record. Two strategies:
+     *
+     *   - `lookupById`: present when the right source exposes the
+     *     hook directly (typical Collection right side). Per-row
+     *     cost is O(1).
+     *   - `hashByPrimaryKey`: built from `snapshot()` when no
+     *     lookupById. Per-row cost is O(1) after the upfront O(N)
+     *     materialization. Same as eager join's hash strategy.
+     *
+     * `warnedKeys` is the per-leg dedup set for ref-mode 'warn'. We
+     * key on `field→target:refId` so the same dangling pair only
+     * warns once per iteration. The dedup is per-iteration, not
+     * per-process — a long-running scan that re-iterates would warn
+     * again, which is the desired behavior (the data may have
+     * changed between iterations).
+     */
+    private buildJoinResolvers;
+    /**
+     * Resolve a single join leg for one left record and return the
+     * left record with the joined field attached under
+     * `leg.as`. Pure function over `(left, resolver)`; never
+     * mutates the input.
+     *
+     * Ref-mode dispatch matches eager `applyJoins` from :
+     *   - null/undefined FK → attach null silently (always allowed)
+     *   - dangling FK + strict → throw `DanglingReferenceError`
+     *   - dangling FK + warn → attach null, warn-once per pair
+     *   - dangling FK + cascade → attach null silently
+     */
+    private applyOneJoinStreaming;
+    /**
+     * Reduce the scan stream through a named set of reducers and
+     * return the final aggregated shape.
+     *
+     * Memory is O(reducers): one mutable state slot per spec key.
+     * Records flow through the pipeline one at a time via
+     * `for await` and are discarded after their `step()` is applied
+     * — never collected into an array. This is the distinguishing
+     * property from `Query.aggregate()`, which materializes the full
+     * match set first.
+     *
+     * Reuses the same reducer protocol as `Query.aggregate()`,
+     * so `count()`, `sum(field)`, `avg(field)`, `min(field)`,
+     * `max(field)` all work unchanged. The `{ seed }` parameter
+     * plumbing from  constraint #2 is honored transparently — the
+     * factories ignore it in and the scan executor never
+     * touches the per-reducer state construction.
+     *
+     * **Returns a Promise**, unlike `Query.aggregate().run()` which
+     * is synchronous. The scan is inherently async because it walks
+     * adapter pages, so the terminal has to be too. Consumers
+     * destructure with await:
+     *
+     * ```ts
+     * const { total, n } = await invoices.scan()
+     *   .where('year', '==', 2025)
+     *   .aggregate({ total: sum('amount'), n: count() })
+     * ```
+     *
+     * **No `.live()` in.** `scan().aggregate().live()` would
+     * require reconciling an unbounded streaming iteration with a
+     * change-stream subscription — a design problem, not just a code
+     * one. Consumers with huge collections and live needs should
+     * narrow with `.where()` enough to fit in the 50k `query()`
+     * limit and use `query().aggregate().live()` instead.
+     */
+    aggregate<Spec extends AggregateSpec>(spec: Spec): Promise<AggregateResult<Spec>>;
+    /**
+     * Evaluate the clause list against a single record. Linear in
+     * the clause count; short-circuits on first false. Clauses on a
+     * scan are always re-evaluated per record — no index-accelerated
+     * path, because the stream sources records from the adapter
+     * paginator, not from the in-memory cache where indexes live.
+     */
+    private recordMatches;
+}
+
+export { RefIntegrityError as $, AlreadyElevatedError as A, BackupCorruptedError as B, ConflictError as C, DictKeyInUseError as D, ElevationExpiredError as E, FilenameSanitizationError as F, GroupCardinalityError as G, PermissionDeniedError as H, ImportCapabilityError as I, type JoinContext as J, KeyringCorruptError as K, LocaleNotSpecifiedError as L, MissingTranslationError as M, NoydbError as N, type OrderBy as O, PathEscapeError as P, PrivilegeEscalationError as Q, ReservedCollectionNameError as R, SessionExpiredError as S, TranslatorNotConfiguredError as T, Query as U, type QueryPlan as V, type QuerySource as W, ReadOnlyAtInstantError as X, ReadOnlyError as Y, ReadOnlyFrameError as Z, type RefDescriptor as _, DictKeyMissingError as a, type RefMode as a0, RefRegistry as a1, RefScopeError as a2, type RefViolation as a3, ScanBuilder as a4, type ScanPageProvider as a5, SchemaValidationError as a6, StoreCapabilityError as a7, TamperedError as a8, TierDemoteDeniedError as a9, TierNotGrantedError as aa, ValidationError as ab, applyJoins as ac, buildLiveQuery as ad, executePlan as ae, ref as af, resetJoinWarnings as ag, SessionNotFoundError as b, SessionPolicyError as c, BackupLedgerError as d, BundleIntegrityError as e, BundleVersionConflictError as f, DEFAULT_JOIN_MAX_ROWS as g, DanglingReferenceError as h, DecryptionError as i, DelegationTargetMissingError as j, ExportCapabilityError as k, IndexRequiredError as l, IndexWriteFailureError as m, InvalidKeyError as n, type JoinLeg as o, type JoinStrategy as p, JoinTooLargeError as q, type JoinableSource as r, KeyringExpiredError as s, LedgerContentionError as t, type LiveQuery as u, type LiveUpstream as v, NetworkError as w, NoAccessError as x, NotFoundError as y, PeriodClosedError as z };