@noy-db/hub 0.1.0-pre.3

package/dist/aggregate/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/aggregate/index.ts","../../src/aggregate/aggregation.ts","../../src/query/predicate.ts","../../src/errors.ts","../../src/aggregate/groupby.ts","../../src/aggregate/active.ts","../../src/aggregate/reducers.ts"],"sourcesContent":["/**\n * @noy-db/hub/aggregate — opt-in aggregation + groupBy subsystem.\n *\n * @category capability\n *\n * Groups every file whose reason-for-existing is record reduction:\n *   - `aggregation` (`Aggregation<R>`, `reduceRecords`, `buildLiveAggregation`)\n *   - `groupby` (`GroupedQuery`, `GroupedAggregation`, cardinality guards)\n *   - `reducers` (`count`, `sum`, `avg`, `min`, `max` factories)\n *\n * The root barrel (`@noy-db/hub`) and the `@noy-db/hub/query` subpath\n * continue to re-export the same symbols for backward compatibility\n * with consumers written before the relocation. New code should\n * prefer this subpath.\n */\n\nexport { withAggregate } from './active.js'\nexport type { AggregateStrategy } from './strategy.js'\n\nexport { Aggregation, reduceRecords, buildLiveAggregation } from './aggregation.js'\nexport type {\n  AggregateSpec,\n  AggregateResult,\n  AggregationUpstream,\n  LiveAggregation,\n} from './aggregation.js'\n\nexport {\n  GroupedQuery,\n  GroupedAggregation,\n  groupAndReduce,\n  resetGroupByWarnings,\n  GROUPBY_WARN_CARDINALITY,\n  GROUPBY_MAX_CARDINALITY,\n} from './groupby.js'\nexport type { GroupedRow } from './groupby.js'\n\nexport { count, sum, avg, min, max } from './reducers.js'\nexport type { Reducer, ReducerOptions } from './reducers.js'\n","/**\n * Aggregate execution — the runtime behind `Query.aggregate()`.\n *\n * takes an `AggregateSpec` (a record of named reducers\n * built from `reducers.ts`) and runs every reducer over the records\n * produced by the underlying query. Two terminal surfaces:\n *\n *   - `.run(): R` — synchronous one-shot reduction. Matches the\n *     existing `Query.toArray()` / `.first()` / `.count()` style.\n *   - `.live(): LiveAggregation<R>` — reactive primitive that\n *     re-runs the reduction whenever the query's source notifies of\n *     a change. uses naive full re-run; incremental delta\n *     maintenance is admitted by the reducer protocol (`remove()`)\n *     but not wired to the executor yet — a follow-up optimization\n *     can switch from full re-run to delta-based without breaking\n *     the public API. Consumers get correct, reactive values today.\n *\n * The `Aggregation<R>` wrapper is deliberately tiny — it exists so\n * `.aggregate(spec)` can be chained with either `.run()` or `.live()`\n * without the builder needing two separate terminal methods. It\n * holds the closure over the query execution (produces the current\n * matching record set) and the spec, and stitches them together in\n * either mode.\n *\n * This file depends ONLY on `reducers.ts` — it has no knowledge of\n * the `Query` class. Tests can therefore exercise the reduction\n * surface with plain record arrays, without spinning up a Collection.\n */\n\nimport type { Reducer } from './reducers.js'\n\n/**\n * A named set of reducers, keyed by output field name. Each key\n * becomes a field on the aggregated result.\n *\n * ```ts\n * const spec = {\n *   total: sum('amount'),\n *   n:     count(),\n *   avgAmount: avg('amount'),\n * }\n * ```\n */\nexport type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>\n\n/**\n * Map an `AggregateSpec` to its reduced result shape — each key\n * carries the finalized result type from its reducer. A spec built\n * from `{ total: sum('amount'), n: count() }` yields a result of\n * `{ total: number, n: number }`.\n *\n * This uses a mapped type with a conditional to extract `R` from\n * each `Reducer<R, _>`. The `infer` captures the user-visible result\n * type, discarding the internal state type `S`.\n */\nexport type AggregateResult<Spec extends AggregateSpec> = {\n  [K in keyof Spec]: Spec[K] extends Reducer<infer R, unknown> ? R : never\n}\n\n/**\n * Pure reduction over a record array. Runs every reducer's\n * `init → step* → finalize` pipeline exactly once over the records.\n *\n * Called by `Aggregation.run()` and by the live-mode refresh path.\n * Exported for tests and for future `scan().aggregate()` reuse\n * — the streaming path will call the same reducer protocol with a\n * per-page loop instead of a single array.\n */\nexport function reduceRecords<Spec extends AggregateSpec>(\n  records: readonly unknown[],\n  spec: Spec,\n): AggregateResult<Spec> {\n  // Per-slot state, keyed by the spec's output field name.\n  const state: Record<string, unknown> = {}\n  for (const key of Object.keys(spec)) {\n    state[key] = spec[key]!.init()\n  }\n  for (const record of records) {\n    for (const key of Object.keys(spec)) {\n      state[key] = spec[key]!.step(state[key], record)\n    }\n  }\n  const result: Record<string, unknown> = {}\n  for (const key of Object.keys(spec)) {\n    result[key] = spec[key]!.finalize(state[key])\n  }\n  return result as AggregateResult<Spec>\n}\n\n/**\n * A minimal reactive primitive for aggregation results.\n *\n * Same spirit as the `LiveQuery` in : frame-agnostic, a plain\n * object with `value` / `error` fields and a `subscribe(cb)`\n * notification channel that Vue / React / Solid adapters wrap in\n * their own primitive. Intentionally NOT a Promise — aggregations\n * have a well-defined \"current value\" at every instant, and the\n * reactive consumer wants to read that value synchronously.\n *\n * Error semantics mirror `LiveQuery`: if a re-run throws, the\n * previous successful `value` is preserved and the error is stored\n * in `error` so consumers can render an error state without losing\n * the last-known-good result. The throw does NOT propagate out of\n * the source's change handler (which would tear down the upstream\n * emitter).\n *\n * `stop()` tears down the upstream subscription. It is idempotent —\n * calling it multiple times is safe — and subscribe calls after\n * stop are no-ops (they immediately return a no-op unsubscribe).\n * Always call `stop()` when done; Vue's `onUnmounted` is the\n * canonical place. Raw consumers must do it themselves.\n */\nexport interface LiveAggregation<R> {\n  /** Current reduced value. Undefined only if the first compute threw. */\n  readonly value: R | undefined\n  /** Last execution error, if any. Cleared on the next successful run. */\n  readonly error: unknown\n  /** Notify on every recomputation (success or error). Returns unsubscribe. */\n  subscribe(cb: () => void): () => void\n  /** Tear down the upstream subscription. Idempotent. */\n  stop(): void\n}\n\n/**\n * Upstream change-notification hook for live aggregation.\n *\n * Matches the shape that `QuerySource.subscribe` already uses — a\n * single method that accepts a callback and returns an unsubscribe\n * function. The `Aggregation` wrapper collects upstreams from the\n * query's source and wires them into a single re-run trigger.\n */\nexport interface AggregationUpstream {\n  subscribe(cb: () => void): () => void\n}\n\n/**\n * Internal implementation of `LiveAggregation`. Not exported —\n * consumers get the interface only. The class wraps a `recompute`\n * closure (which runs the full reduction and returns the new value)\n * and a list of upstreams (sources whose changes should trigger a\n * re-run).\n *\n * Error isolation: if an individual listener callback throws, the\n * other listeners still fire and the error is logged to the warn\n * channel. This matches `LiveQuery` from  and keeps one misbehaving\n * consumer from tearing down the whole live aggregation.\n */\nclass LiveAggregationImpl<R> implements LiveAggregation<R> {\n  public value: R | undefined\n  public error: unknown\n  private readonly listeners = new Set<() => void>()\n  private readonly unsubscribes: Array<() => void> = []\n  private stopped = false\n\n  constructor(\n    private readonly recompute: () => R,\n    upstreams: readonly AggregationUpstream[],\n  ) {\n    // Initial computation — surface any error through the `error`\n    // field rather than letting the constructor throw, so consumers\n    // can always construct a LiveAggregation and check its state\n    // afterwards. Throwing from a constructor would force every\n    // caller to wrap in try/catch, which is the opposite of the\n    // \"reactive value with error state\" ergonomics we want.\n    try {\n      this.value = recompute()\n      this.error = undefined\n    } catch (err) {\n      this.value = undefined\n      this.error = err\n    }\n\n    // Wire up upstream subscriptions. Each one triggers a full\n    // recomputation; we don't attempt incremental updates in.\n    for (const upstream of upstreams) {\n      const unsub = upstream.subscribe(() => this.refresh())\n      this.unsubscribes.push(unsub)\n    }\n  }\n\n  private refresh(): void {\n    if (this.stopped) return\n    try {\n      this.value = this.recompute()\n      this.error = undefined\n    } catch (err) {\n      // Preserve the previous successful value — consumers render an\n      // error state using `error` without losing the last-known-good\n      // number. This matches LiveQuery's error-preservation contract.\n      this.error = err\n    }\n    for (const listener of this.listeners) {\n      try {\n        listener()\n      } catch (err) {\n        // Isolate listener errors so one bad consumer can't tear\n        // down every other subscriber on the same aggregation.\n        console.warn('[noy-db] LiveAggregation listener threw:', err)\n      }\n    }\n  }\n\n  subscribe(cb: () => void): () => void {\n    if (this.stopped) {\n      // No-op after stop. Returning a harmless unsubscribe lets\n      // consumers use the same teardown pattern unconditionally.\n      return () => {}\n    }\n    this.listeners.add(cb)\n    return () => {\n      this.listeners.delete(cb)\n    }\n  }\n\n  stop(): void {\n    if (this.stopped) return\n    this.stopped = true\n    for (const unsub of this.unsubscribes) {\n      try {\n        unsub()\n      } catch (err) {\n        console.warn('[noy-db] LiveAggregation upstream unsubscribe threw:', err)\n      }\n    }\n    this.unsubscribes.length = 0\n    this.listeners.clear()\n  }\n}\n\n/**\n * Chainable wrapper returned by `Query.aggregate(spec)`. Holds the\n * execute-records closure and the spec; terminal methods (`run`,\n * `live`) stitch them together in either mode.\n *\n * Why a wrapper instead of two terminal methods on `Query` directly?\n *\n * The `.aggregate(spec)` call is where the spec is bound — both\n * `.run()` and `.live()` need the same spec, and the consumer's\n * fluent style is `query.where(...).aggregate(spec).run()` or\n * `.aggregate(spec).live()`. Wrapping lets the spec be named once\n * and reused for either terminal, and keeps the `Query` class\n * from growing a pair of near-duplicate method overloads\n * (`aggregateRun` / `aggregateLive`) that would be harder to\n * discover.\n */\nexport class Aggregation<R> {\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    private readonly spec: AggregateSpec,\n    private readonly upstreams: readonly AggregationUpstream[],\n  ) {}\n\n  /**\n   * Execute the query and reduce the results synchronously.\n   * Returns the reduced shape matching the spec — e.g. a spec of\n   * `{ total: sum('amount'), n: count() }` returns\n   * `{ total: number, n: number }`.\n   */\n  run(): R {\n    return reduceRecords(this.executeRecords(), this.spec) as unknown as R\n  }\n\n  /**\n   * Build a reactive `LiveAggregation<R>` that re-runs the reduction\n   * whenever any upstream source notifies of a change. The initial\n   * value is computed eagerly in the constructor, so consumers can\n   * read `live.value` immediately after calling `.live()`.\n   *\n   * Always call `live.stop()` when finished — it tears down the\n   * upstream subscriptions. Vue's `onUnmounted` is the canonical\n   * place.\n   *\n   * **Implementation note:** every upstream change triggers a full\n   * re-reduction. Incremental maintenance (O(1) per delta for\n   * sum/count/avg via the reducer protocol's `remove()` method) is a\n   * planned follow-up optimization — the protocol already supports\n   * it, but the executor doesn't drive it yet. Consumers get\n   * correct, reactive values today; future PRs can switch to\n   * delta-based maintenance without changing this API.\n   */\n  live(): LiveAggregation<R> {\n    const recompute = (): R =>\n      reduceRecords(this.executeRecords(), this.spec) as unknown as R\n    return new LiveAggregationImpl<R>(recompute, this.upstreams)\n  }\n}\n\n/**\n * Build a `LiveAggregation<V>` from a recompute closure and a list\n * of upstreams. Exposed so sibling files in the query DSL\n * (currently `groupby.ts`) can reuse the reactive primitive\n * without reaching into `LiveAggregationImpl` directly. This keeps\n * the implementation class private while still allowing planned\n * composition with `.groupBy().aggregate().live()`.\n */\nexport function buildLiveAggregation<V>(\n  recompute: () => V,\n  upstreams: readonly AggregationUpstream[],\n): LiveAggregation<V> {\n  return new LiveAggregationImpl<V>(recompute, upstreams)\n}\n","/**\n * Operator implementations for the query DSL.\n *\n * All predicates run client-side, AFTER decryption — they never see ciphertext.\n * This file is dependency-free and tree-shakeable.\n */\n\n/** Comparison operators supported by the where() builder. */\nexport type Operator =\n  | '=='\n  | '!='\n  | '<'\n  | '<='\n  | '>'\n  | '>='\n  | 'in'\n  | 'contains'\n  | 'startsWith'\n  | 'between'\n\n/**\n * A single field comparison clause inside a query plan.\n * Plans are JSON-serializable, so this type uses primitives only.\n */\nexport interface FieldClause {\n  readonly type: 'field'\n  readonly field: string\n  readonly op: Operator\n  readonly value: unknown\n}\n\n/**\n * A user-supplied predicate function escape hatch. Not serializable.\n *\n * The predicate accepts `unknown` at the type level so the surrounding\n * Clause type can stay non-parametric — this keeps Collection<T> covariant\n * in T at the public API surface. Builder methods cast user predicates\n * (typed `(record: T) => boolean`) into this shape on the way in.\n */\nexport interface FilterClause {\n  readonly type: 'filter'\n  readonly fn: (record: unknown) => boolean\n}\n\n/** A logical group of clauses combined by AND or OR. */\nexport interface GroupClause {\n  readonly type: 'group'\n  readonly op: 'and' | 'or'\n  readonly clauses: readonly Clause[]\n}\n\nexport type Clause = FieldClause | FilterClause | GroupClause\n\n/**\n * Read a possibly nested field path like \"address.city\" from a record.\n * Returns undefined if any segment is missing.\n */\nexport function readPath(record: unknown, path: string): unknown {\n  if (record === null || record === undefined) return undefined\n  if (!path.includes('.')) {\n    return (record as Record<string, unknown>)[path]\n  }\n  const segments = path.split('.')\n  let cursor: unknown = record\n  for (const segment of segments) {\n    if (cursor === null || cursor === undefined) return undefined\n    cursor = (cursor as Record<string, unknown>)[segment]\n  }\n  return cursor\n}\n\n/**\n * Evaluate a single field clause against a record.\n * Returns false on type mismatches rather than throwing — query results\n * exclude non-matching records by definition.\n */\nexport function evaluateFieldClause(record: unknown, clause: FieldClause): boolean {\n  const actual = readPath(record, clause.field)\n  const { op, value } = clause\n\n  switch (op) {\n    case '==':\n      return actual === value\n    case '!=':\n      return actual !== value\n    case '<':\n      return isComparable(actual, value) && (actual as number) < (value as number)\n    case '<=':\n      return isComparable(actual, value) && (actual as number) <= (value as number)\n    case '>':\n      return isComparable(actual, value) && (actual as number) > (value as number)\n    case '>=':\n      return isComparable(actual, value) && (actual as number) >= (value as number)\n    case 'in':\n      return Array.isArray(value) && value.includes(actual)\n    case 'contains':\n      if (typeof actual === 'string') return typeof value === 'string' && actual.includes(value)\n      if (Array.isArray(actual)) return actual.includes(value)\n      return false\n    case 'startsWith':\n      return typeof actual === 'string' && typeof value === 'string' && actual.startsWith(value)\n    case 'between': {\n      if (!Array.isArray(value) || value.length !== 2) return false\n      const [lo, hi] = value\n      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false\n      return (actual as number) >= (lo as number) && (actual as number) <= (hi as number)\n    }\n    default: {\n      // Exhaustiveness — TS will error if a new operator is added without a case.\n      const _exhaustive: never = op\n      void _exhaustive\n      return false\n    }\n  }\n}\n\n/**\n * Two values are \"comparable\" if they share an order-defined runtime type.\n * Strings compare lexicographically; numbers and Dates numerically; otherwise false.\n */\nfunction isComparable(a: unknown, b: unknown): boolean {\n  if (typeof a === 'number' && typeof b === 'number') return true\n  if (typeof a === 'string' && typeof b === 'string') return true\n  if (a instanceof Date && b instanceof Date) return true\n  return false\n}\n\n/**\n * Evaluate any clause (field / filter / group) against a record.\n * The recursion depth is bounded by the user's query expression — no risk of\n * blowing the stack on a 50K-record collection.\n */\nexport function evaluateClause(record: unknown, clause: Clause): boolean {\n  switch (clause.type) {\n    case 'field':\n      return evaluateFieldClause(record, clause)\n    case 'filter':\n      return clause.fn(record)\n    case 'group':\n      if (clause.op === 'and') {\n        for (const child of clause.clauses) {\n          if (!evaluateClause(record, child)) return false\n        }\n        return true\n      } else {\n        for (const child of clause.clauses) {\n          if (evaluateClause(record, child)) return true\n        }\n        return false\n      }\n  }\n}\n","/**\n * All NOYDB error classes — a single import surface for `catch` blocks and\n * `instanceof` checks.\n *\n * ## Class hierarchy\n *\n * ```\n * Error\n *  └─ NoydbError (code: string)\n *       ├─ Crypto errors\n *       │    ├─ DecryptionError        — AES-GCM tag failure\n *       │    ├─ TamperedError          — ciphertext modified after write\n *       │    └─ InvalidKeyError        — wrong passphrase / corrupt keyring\n *       ├─ Access errors\n *       │    ├─ NoAccessError          — no DEK for this collection\n *       │    ├─ ReadOnlyError          — ro permission, write attempted\n *       │    ├─ PermissionDeniedError  — role too low for operation\n *       │    ├─ PrivilegeEscalationError — grant wider than grantor holds\n *       │    └─ StoreCapabilityError   — optional store method missing\n *       ├─ Sync errors\n *       │    ├─ ConflictError          — optimistic-lock version mismatch\n *       │    ├─ BundleVersionConflictError — bundle push rejected by remote\n *       │    └─ NetworkError           — push/pull network failure\n *       ├─ Data errors\n *       │    ├─ NotFoundError          — get(id) on missing record\n *       │    ├─ ValidationError        — application-level guard failed\n *       │    └─ SchemaValidationError  — Standard Schema v1 rejection\n *       ├─ Query errors\n *       │    ├─ JoinTooLargeError      — join row ceiling exceeded\n *       │    ├─ DanglingReferenceError — strict ref() points at nothing\n *       │    ├─ GroupCardinalityError  — groupBy bucket cap exceeded\n *       │    ├─ IndexRequiredError      — lazy-mode query touches unindexed field\n *       │    └─ IndexWriteFailureError       — index side-car put/delete failed post-main\n *       ├─ i18n / Dictionary errors\n *       │    ├─ ReservedCollectionNameError\n *       │    ├─ DictKeyMissingError\n *       │    ├─ DictKeyInUseError\n *       │    ├─ MissingTranslationError\n *       │    ├─ LocaleNotSpecifiedError\n *       │    └─ TranslatorNotConfiguredError\n *       ├─ Backup errors\n *       │    ├─ BackupLedgerError      — hash-chain verification failed\n *       │    └─ BackupCorruptedError   — envelope hash mismatch in dump\n *       ├─ Bundle errors\n *       │    └─ BundleIntegrityError   — .noydb body sha256 mismatch\n *       └─ Session errors\n *            ├─ SessionExpiredError\n *            ├─ SessionNotFoundError\n *            └─ SessionPolicyError\n * ```\n *\n * ## Catching all NOYDB errors\n *\n * ```ts\n * import { NoydbError, InvalidKeyError, ConflictError } from '@noy-db/hub'\n *\n * try {\n *   await vault.unlock(passphrase)\n * } catch (e) {\n *   if (e instanceof InvalidKeyError) { showBadPassphraseUI(); return }\n *   if (e instanceof NoydbError) { logToSentry(e.code, e); return }\n *   throw e  // unexpected — re-throw\n * }\n * ```\n *\n * @module\n */\n\n/**\n * Base class for all NOYDB errors.\n *\n * Every error thrown by `@noy-db/hub` extends this class, so consumers can\n * catch all NOYDB errors in a single `catch (e) { if (e instanceof NoydbError) ... }`\n * block. The `code` field is a machine-readable string (e.g. `'DECRYPTION_FAILED'`)\n * suitable for `switch` statements and logging pipelines.\n */\nexport class NoydbError extends Error {\n  /** Machine-readable error code. Stable across library versions. */\n  readonly code: string\n\n  constructor(code: string, message: string) {\n    super(message)\n    this.name = 'NoydbError'\n    this.code = code\n  }\n}\n\n// ─── Crypto Errors ─────────────────────────────────────────────────────\n\n/**\n * Thrown when AES-GCM decryption fails.\n *\n * The most common cause is a wrong passphrase or a corrupted ciphertext.\n * A `DecryptionError` at the wrong passphrase level is caught internally\n * and re-thrown as `InvalidKeyError` — so in practice this surfaces for\n * per-record corruption rather than authentication failures.\n */\nexport class DecryptionError extends NoydbError {\n  constructor(message = 'Decryption failed') {\n    super('DECRYPTION_FAILED', message)\n    this.name = 'DecryptionError'\n  }\n}\n\n/**\n * Thrown when GCM tag verification fails, indicating the ciphertext was\n * modified after encryption.\n *\n * AES-256-GCM is authenticated encryption — the tag over the ciphertext\n * is checked on every decrypt. If any byte was flipped (accidental\n * corruption or deliberate tampering), decryption throws this error.\n * Treat it as a security alert: the stored bytes are not what NOYDB wrote.\n */\nexport class TamperedError extends NoydbError {\n  constructor(message = 'Data integrity check failed — record may have been tampered with') {\n    super('TAMPERED', message)\n    this.name = 'TamperedError'\n  }\n}\n\n/**\n * Thrown when key unwrapping fails, typically because the passphrase is wrong\n * or the keyring file is corrupted.\n *\n * NOYDB uses AES-KW (RFC 3394) to wrap DEKs with the KEK. If AES-KW\n * unwrapping fails, it means either the KEK was derived from the wrong\n * passphrase (PBKDF2 with 600K iterations) or the keyring bytes are\n * corrupted. This is the error shown to the user on a failed unlock attempt.\n */\nexport class InvalidKeyError extends NoydbError {\n  constructor(message = 'Invalid key — wrong passphrase or corrupted keyring') {\n    super('INVALID_KEY', message)\n    this.name = 'InvalidKeyError'\n  }\n}\n\n// ─── Access Errors ─────────────────────────────────────────────────────\n\n/**\n * Thrown when the authenticated user does not have a DEK for the requested\n * collection — i.e. the collection is not in their keyring at all.\n *\n * This is the \"no key for this door\" error. It is different from\n * `ReadOnlyError` (user has a key but it only grants ro) and from\n * `PermissionDeniedError` (user's role doesn't allow the operation).\n */\nexport class NoAccessError extends NoydbError {\n  constructor(message = 'No access — user does not have a key for this collection') {\n    super('NO_ACCESS', message)\n    this.name = 'NoAccessError'\n  }\n}\n\n/**\n * Thrown when a user with read-only (`ro`) permission attempts a write\n * operation (`put` or `delete`) on a collection.\n *\n * The user has a DEK for the collection (they can decrypt and read), but\n * their keyring grants only `ro`. To fix: re-grant the user with `rw`\n * permission, or do not attempt writes as a viewer/client role.\n */\nexport class ReadOnlyError extends NoydbError {\n  constructor(message = 'Read-only — user has ro permission on this collection') {\n    super('READ_ONLY', message)\n    this.name = 'ReadOnlyError'\n  }\n}\n\n/**\n * Thrown when a write is attempted against a historical view produced\n * by `vault.at(timestamp)`. Time-machine views are read-only by\n * contract — mutating the past would require either the shadow-vault\n * mechanism or a ledger-history rewrite (which breaks\n * the tamper-evidence guarantee).\n *\n * Distinct from {@link ReadOnlyError} (keyring-level) and\n * {@link PermissionDeniedError} (role-level): this error is about the\n * *view* being historical, independent of the caller's permissions.\n */\nexport class ReadOnlyAtInstantError extends NoydbError {\n  constructor(operation: string, timestamp: string) {\n    super(\n      'READ_ONLY_AT_INSTANT',\n      `Cannot ${operation}() on a vault view anchored at ${timestamp} — time-machine views are read-only`,\n    )\n    this.name = 'ReadOnlyAtInstantError'\n  }\n}\n\n/**\n * Thrown when a write is attempted against a shadow-vault frame\n * produced by `vault.frame()`. Frames are read-only by contract —\n * the use case is screen-sharing / demos / compliance review where\n * the operator wants to prevent accidental edits.\n *\n * Behavioural enforcement only — the underlying keyring still holds\n * write-capable DEKs. See {@link VaultFrame} for the full caveat.\n */\nexport class ReadOnlyFrameError extends NoydbError {\n  constructor(operation: string) {\n    super(\n      'READ_ONLY_FRAME',\n      `Cannot ${operation}() on a vault frame — frames are read-only presentations of the current vault`,\n    )\n    this.name = 'ReadOnlyFrameError'\n  }\n}\n\n/**\n * Thrown when the authenticated user's role does not permit the requested\n * operation — e.g. a `viewer` calling `grantAccess()`, or an `operator`\n * calling `rotateKeys()`.\n *\n * This is a role-level check (what the user's role allows), distinct from\n * `NoAccessError` (collection not in keyring) and `ReadOnlyError` (in\n * keyring, but write not allowed).\n */\nexport class PermissionDeniedError extends NoydbError {\n  constructor(message = 'Permission denied — insufficient role for this operation') {\n    super('PERMISSION_DENIED', message)\n    this.name = 'PermissionDeniedError'\n  }\n}\n\n/**\n * Thrown when an `@noy-db/as-*` export is attempted without the\n * required capability bit on the invoking keyring.\n *\n * Two sub-cases discriminated by the `tier` field:\n *\n * - `tier: 'plaintext'` — a plaintext-tier export (`as-xlsx`,\n *   `as-csv`, `as-blob`, `as-zip`, …) was attempted but the\n *   keyring's `exportCapability.plaintext` does not include the\n *   requested `format` (nor the `'*'` wildcard). Default for every\n *   role is `plaintext: []` — the owner must positively grant.\n * - `tier: 'bundle'` — an encrypted `as-noydb` bundle export was\n *   attempted but the keyring's `exportCapability.bundle` is\n *   `false`. Default for `owner`/`admin` is `true`; for\n *   `operator`/`viewer`/`client` it is `false`.\n *\n * Distinct from `PermissionDeniedError` (role-level check) and\n * `NoAccessError` (collection not readable). Surfaces separately so\n * UI layers can show a \"request the export capability from your\n * admin\" flow rather than a generic permission error.\n */\nexport class ExportCapabilityError extends NoydbError {\n  readonly tier: 'plaintext' | 'bundle'\n  readonly format?: string\n  readonly userId: string\n\n  constructor(opts: {\n    tier: 'plaintext' | 'bundle'\n    userId: string\n    format?: string\n    message?: string\n  }) {\n    const msg =\n      opts.message ??\n      (opts.tier === 'plaintext'\n        ? `Export capability denied — keyring \"${opts.userId}\" is not granted plaintext-export capability for format \"${opts.format ?? '<unknown>'}\". Ask a vault owner or admin to grant it via vault.grant({ exportCapability: { plaintext: ['${opts.format ?? '<format>'}'] } }).`\n        : `Export capability denied — keyring \"${opts.userId}\" is not granted encrypted-bundle export capability. Ask a vault owner or admin to grant it via vault.grant({ exportCapability: { bundle: true } }).`)\n    super('EXPORT_CAPABILITY', msg)\n    this.name = 'ExportCapabilityError'\n    this.tier = opts.tier\n    this.userId = opts.userId\n    if (opts.format !== undefined) this.format = opts.format\n  }\n}\n\n/**\n * Thrown when a keyring file's `expires_at` cutoff has passed.\n * Surfaced by `loadKeyring` before any DEK unwrap is attempted —\n * past the cutoff the slot refuses to open even with the right\n * passphrase. Distinct from PBKDF2 / unwrap errors so consumer code\n * can show a precise \"this bundle slot has expired\" message instead\n * of the generic decryption-failure UX.\n *\n * Used predominantly on `BundleRecipient` slots produced by\n * `writeNoydbBundle({ recipients: [...] })` to time-box audit access.\n */\nexport class KeyringExpiredError extends NoydbError {\n  readonly userId: string\n  readonly expiresAt: string\n  constructor(opts: { userId: string; expiresAt: string }) {\n    super(\n      'KEYRING_EXPIRED',\n      `Keyring \"${opts.userId}\" expired at ${opts.expiresAt}. ` +\n        'The slot refuses to unlock past its expiry timestamp.',\n    )\n    this.name = 'KeyringExpiredError'\n    this.userId = opts.userId\n    this.expiresAt = opts.expiresAt\n  }\n}\n\n/**\n * Thrown when an `@noy-db/as-*` import is attempted but the invoking\n * keyring lacks the required import-capability bit (issue ).\n *\n * - `tier: 'plaintext'` — a plaintext-tier import (`as-csv`, `as-json`,\n *   `as-ndjson`, `as-zip`, …) was attempted but the keyring's\n *   `importCapability.plaintext` does not include the requested\n *   `format` (nor the `'*'` wildcard).\n * - `tier: 'bundle'` — a `.noydb` bundle import was attempted but the\n *   keyring's `importCapability.bundle` is not `true`.\n *\n * Default for every role on every dimension is closed — owners and\n * admins must positively grant the capability. Distinct from\n * `PermissionDeniedError` and `NoAccessError` so UI layers can show a\n * specific \"request the import capability\" flow.\n */\nexport class ImportCapabilityError extends NoydbError {\n  readonly tier: 'plaintext' | 'bundle'\n  readonly format?: string\n  readonly userId: string\n\n  constructor(opts: {\n    tier: 'plaintext' | 'bundle'\n    userId: string\n    format?: string\n    message?: string\n  }) {\n    const msg =\n      opts.message ??\n      (opts.tier === 'plaintext'\n        ? `Import capability denied — keyring \"${opts.userId}\" is not granted plaintext-import capability for format \"${opts.format ?? '<unknown>'}\". Ask a vault owner or admin to grant it via vault.grant({ importCapability: { plaintext: ['${opts.format ?? '<format>'}'] } }).`\n        : `Import capability denied — keyring \"${opts.userId}\" is not granted encrypted-bundle import capability. Ask a vault owner or admin to grant it via vault.grant({ importCapability: { bundle: true } }).`)\n    super('IMPORT_CAPABILITY', msg)\n    this.name = 'ImportCapabilityError'\n    this.tier = opts.tier\n    this.userId = opts.userId\n    if (opts.format !== undefined) this.format = opts.format\n  }\n}\n\n/**\n * Thrown when a grant would give the grantee a permission the grantor\n * does not themselves hold — the \"admin cannot grant what admin cannot\n * do\" rule from the admin-delegation work.\n *\n * Distinct from `PermissionDeniedError` so callers can tell the two\n * cases apart in logs and tests:\n *\n *   - `PermissionDeniedError` — \"you are not allowed to perform this\n *     operation at all\" (wrong role).\n *   - `PrivilegeEscalationError` — \"you are allowed to grant, but not\n *     with these specific permissions\" (widening attempt).\n *\n * Under the admin model the grantee of an admin-grants-admin call\n * inherits the caller's entire DEK set by construction, so this error\n * is structurally unreachable in typical flows. The check and error\n * class exist so that future per-collection admin scoping cannot\n * accidentally bypass the subset rule — the guard is already wired in.\n *\n * `offendingCollection` carries the first collection name that failed\n * the subset check, to make the violation actionable in error output.\n */\n/**\n * Thrown when a caller invokes an API that requires an optional\n * store capability the active store does not implement.\n *\n * Today the only call site is `Noydb.listAccessibleVaults()`,\n * which depends on the optional `NoydbStore.listVaults()`\n * method. The error message names the missing method and the calling\n * API so consumers know exactly which combination is unsupported,\n * and the `capability` field is machine-readable so library code can\n * pattern-match in catch blocks (e.g. fall back to a candidate-list\n * shape).\n *\n * The class lives in `errors.ts` rather than as a generic\n * `ValidationError` because the diagnostic shape is different: a\n * `ValidationError` says \"the inputs you passed are wrong\"; this\n * error says \"the inputs are fine, but the store you wired up\n * doesn't support what you're asking for.\" Different fix, different\n * documentation.\n */\nexport class StoreCapabilityError extends NoydbError {\n  /** The store method/capability that was missing. */\n  readonly capability: string\n\n  constructor(capability: string, callerApi: string, storeName?: string) {\n    super(\n      'STORE_CAPABILITY',\n      `${callerApi} requires the optional store capability \"${capability}\" ` +\n        `but the active store${storeName ? ` (${storeName})` : ''} does not implement it. ` +\n        `Use a store that supports \"${capability}\" (store-memory, store-file) or pass an explicit ` +\n        `vault list to bypass enumeration.`,\n    )\n    this.name = 'StoreCapabilityError'\n    this.capability = capability\n  }\n}\n\nexport class PrivilegeEscalationError extends NoydbError {\n  readonly offendingCollection: string\n\n  constructor(offendingCollection: string, message?: string) {\n    super(\n      'PRIVILEGE_ESCALATION',\n      message ??\n        `Privilege escalation: grantor has no DEK for collection \"${offendingCollection}\" and cannot grant access to it.`,\n    )\n    this.name = 'PrivilegeEscalationError'\n    this.offendingCollection = offendingCollection\n  }\n}\n\n/**\n * Thrown by `Collection.put` / `.delete` when the target record's\n * envelope `_ts` falls within a closed accounting period.\n *\n * Distinct from `ReadOnlyError` (keyring-level), `ReadOnlyAtInstantError`\n * (historical view), and `ReadOnlyFrameError` (shadow vault): this\n * error is about the STORED RECORD being sealed by an operator call\n * to `vault.closePeriod()`, independent of caller permissions or\n * view type. The `periodName` and `endDate` fields name the sealing\n * period so audit UIs can surface a \"this record is locked in\n * FY2026-Q1 (closed 2026-03-31)\" message without parsing the error\n * string.\n *\n * To apply a correction after close, book a compensating entry in a\n * new period rather than unlocking the old one. Re-opening a closed\n * period is deliberately unsupported.\n */\nexport class PeriodClosedError extends NoydbError {\n  readonly periodName: string\n  readonly endDate: string\n  readonly recordTs: string\n\n  constructor(periodName: string, endDate: string, recordTs: string) {\n    super(\n      'PERIOD_CLOSED',\n      `Cannot modify record (last written ${recordTs}) — sealed by closed period ` +\n        `\"${periodName}\" (endDate: ${endDate}). Post a compensating entry in a ` +\n        `new period instead.`,\n    )\n    this.name = 'PeriodClosedError'\n    this.periodName = periodName\n    this.endDate = endDate\n    this.recordTs = recordTs\n  }\n}\n\n// ─── Hierarchical Access Errors ─────────────────────\n\n/**\n * Thrown when a user tries to act at a tier they are not cleared for.\n *\n * This is the umbrella error for tier write refusals:\n *   - `put({ tier: N })` when the user's keyring lacks tier-N DEK.\n *   - `elevate(id, N)` when the caller cannot reach tier N.\n *\n * Distinct from `TierAccessDeniedError` which covers *read* refusals on\n * the invisibility/ghost path.\n */\nexport class TierNotGrantedError extends NoydbError {\n  readonly tier: number\n  readonly collection: string\n\n  constructor(collection: string, tier: number) {\n    super(\n      'TIER_NOT_GRANTED',\n      `User has no DEK for tier ${tier} in collection \"${collection}\"`,\n    )\n    this.name = 'TierNotGrantedError'\n    this.collection = collection\n    this.tier = tier\n  }\n}\n\n/**\n * Thrown when an elevated-handle operation runs after the elevation's\n * TTL expired. Reads continue at the original tier; only writes\n * through the scoped handle flip to throwing once expired.\n */\nexport class ElevationExpiredError extends NoydbError {\n  readonly tier: number\n  readonly expiresAt: number\n\n  constructor(opts: { tier: number; expiresAt: number }) {\n    super(\n      'ELEVATION_EXPIRED',\n      `Elevation to tier ${opts.tier} expired at ${new Date(opts.expiresAt).toISOString()}`,\n    )\n    this.name = 'ElevationExpiredError'\n    this.tier = opts.tier\n    this.expiresAt = opts.expiresAt\n  }\n}\n\n/**\n * Thrown by `vault.elevate(...)` when an elevation is already active\n * on the vault. Adopters must `release()` the existing handle before\n * starting a new elevation.\n */\nexport class AlreadyElevatedError extends NoydbError {\n  readonly activeTier: number\n\n  constructor(activeTier: number) {\n    super(\n      'ALREADY_ELEVATED',\n      `Vault is already elevated to tier ${activeTier}; release the existing handle first`,\n    )\n    this.name = 'AlreadyElevatedError'\n    this.activeTier = activeTier\n  }\n}\n\n/**\n * Thrown when `demote()` is called by someone who is not the original\n * elevator and not an owner.\n */\nexport class TierDemoteDeniedError extends NoydbError {\n  constructor(id: string, tier: number) {\n    super(\n      'TIER_DEMOTE_DENIED',\n      `Only the original elevator or an owner can demote record \"${id}\" from tier ${tier}`,\n    )\n    this.name = 'TierDemoteDeniedError'\n  }\n}\n\n/**\n * Thrown when `db.delegate()` is called against a user that has no\n * keyring in the target vault — the delegation token cannot be\n * constructed without the target user's KEK wrap.\n */\nexport class DelegationTargetMissingError extends NoydbError {\n  readonly toUser: string\n\n  constructor(toUser: string) {\n    super(\n      'DELEGATION_TARGET_MISSING',\n      `Delegation target user \"${toUser}\" has no keyring in this vault`,\n    )\n    this.name = 'DelegationTargetMissingError'\n    this.toUser = toUser\n  }\n}\n\n// ─── Sync Errors ───────────────────────────────────────────────────────\n\n/**\n * Thrown when a `put()` detects an optimistic concurrency conflict.\n *\n * NOYDB uses version numbers (`_v`) for optimistic locking. If a `put()`\n * is called with `expectedVersion: N` but the stored record is at version\n * `M ≠ N`, the write is rejected and the caller must re-read, re-apply their\n * change, and retry. The `version` field carries the actual stored version\n * so callers can decide whether to retry or surface the conflict to the user.\n */\nexport class ConflictError extends NoydbError {\n  /** The actual stored version at the time of conflict. */\n  readonly version: number\n\n  constructor(version: number, message = 'Version conflict') {\n    super('CONFLICT', message)\n    this.name = 'ConflictError'\n    this.version = version\n  }\n}\n\n/**\n * Thrown by `LedgerStore.append()` after exhausting its CAS retry\n * budget under multi-writer contention. Two browser tabs, a\n * web app + an offline mobile peer, or a server worker pool all\n * producing ledger entries against the same vault can race on the\n * \"read head, write head+1\" cycle; the optimistic-CAS retry loop\n * resolves the race for `casAtomic: true` stores, but pathological\n * contention (or a buggy peer) can still exhaust the budget. When\n * that happens, the chain is intact — the failed writer simply\n * couldn't claim a slot. Caller's choice whether to retry, queue,\n * or surface the failure to the user.\n */\nexport class LedgerContentionError extends NoydbError {\n  readonly attempts: number\n\n  constructor(attempts: number) {\n    super(\n      'LEDGER_CONTENTION',\n      `LedgerStore.append: failed to claim a chain slot after ${attempts} optimistic-CAS retries`,\n    )\n    this.name = 'LedgerContentionError'\n    this.attempts = attempts\n  }\n}\n\n/**\n * Thrown when a bundle push is rejected because the remote has been updated\n * since the local bundle was last pulled.\n *\n * Unlike `ConflictError` (per-record), this is a whole-bundle conflict —\n * the remote's bundle handle has changed. The caller must pull the new\n * bundle, merge, and re-push. `remoteVersion` is the handle of the newer\n * remote bundle for use in diagnostics.\n */\nexport class BundleVersionConflictError extends NoydbError {\n  /** The bundle handle of the newer remote version that rejected the push. */\n  readonly remoteVersion: string\n\n  constructor(remoteVersion: string, message = 'Bundle version conflict — remote has been updated') {\n    super('BUNDLE_VERSION_CONFLICT', message)\n    this.name = 'BundleVersionConflictError'\n    this.remoteVersion = remoteVersion\n  }\n}\n\n/**\n * Thrown when a sync operation (push or pull) fails due to a network error.\n *\n * NOYDB's offline-first design means network errors are expected during sync.\n * Callers should catch `NetworkError`, surface connectivity status in the UI,\n * and rely on the `SyncScheduler` to retry when connectivity is restored.\n */\nexport class NetworkError extends NoydbError {\n  constructor(message = 'Network error') {\n    super('NETWORK_ERROR', message)\n    this.name = 'NetworkError'\n  }\n}\n\n// ─── Data Errors ───────────────────────────────────────────────────────\n\n/**\n * Thrown when `collection.get(id)` is called with an ID that does not exist.\n *\n * NOYDB collections are memory-first, so this error is synchronous and cheap —\n * it does not make a network round-trip. Callers that expect the record to be\n * absent should use `collection.getOrNull(id)` instead.\n */\nexport class NotFoundError extends NoydbError {\n  constructor(message = 'Record not found') {\n    super('NOT_FOUND', message)\n    this.name = 'NotFoundError'\n  }\n}\n\n/**\n * Thrown when application-level validation fails before encryption.\n *\n * Distinct from `SchemaValidationError` (Standard Schema v1 validator)\n * and `MissingTranslationError` (i18nText). `ValidationError` is the\n * general-purpose validation base — use it for custom guards in `put()`\n * hooks or store middleware.\n */\nexport class ValidationError extends NoydbError {\n  constructor(message = 'Validation error') {\n    super('VALIDATION_ERROR', message)\n    this.name = 'ValidationError'\n  }\n}\n\n/**\n * Thrown when a Standard Schema v1 validator rejects a record on\n * `put()` (input validation) or on read (output validation). Carries\n * the raw issue list so callers can render field-level errors.\n *\n * `direction` distinguishes the two cases:\n *   - `'input'`: the user passed bad data into `put()`. This is a\n *     normal error case that application code should handle — typically\n *     by showing validation messages in the UI.\n *   - `'output'`: stored data does not match the current schema. This\n *     indicates a schema drift (the schema was changed without\n *     migrating the existing records) and should be treated as a bug\n *     — the application should not swallow it silently.\n *\n * The `issues` type is deliberately `readonly unknown[]` on this class\n * so that `errors.ts` doesn't need to import from `schema.ts` (and\n * create a dependency cycle). Callers who know they're holding a\n * `SchemaValidationError` can cast to the more precise\n * `readonly StandardSchemaV1Issue[]` from `schema.ts`.\n */\nexport class SchemaValidationError extends NoydbError {\n  readonly issues: readonly unknown[]\n  readonly direction: 'input' | 'output'\n\n  constructor(\n    message: string,\n    issues: readonly unknown[],\n    direction: 'input' | 'output',\n  ) {\n    super('SCHEMA_VALIDATION_FAILED', message)\n    this.name = 'SchemaValidationError'\n    this.issues = issues\n    this.direction = direction\n  }\n}\n\n// ─── Query DSL Errors ─────────────────────────────────────────────────\n\n/**\n * Thrown when `.groupBy().aggregate()` produces more than the hard\n * cardinality cap (default 100_000 groups)..\n *\n * The cap exists because `.groupBy()` materializes one bucket per\n * distinct key value in memory, and runaway cardinality — a groupBy\n * on a high-uniqueness field like `id` or `createdAt` — is almost\n * always a query mistake rather than legitimate use. A hard error is\n * better than silent OOM: the consumer sees an actionable message\n * naming the field and the observed cardinality, with guidance to\n * either narrow the query with `.where()` or accept the ceiling\n * override.\n *\n * A separate one-shot warning fires at 10% of the cap (10_000\n * groups) so consumers get a heads-up before the hard error — same\n * pattern as `JoinTooLargeError` and the `.join()` row ceiling.\n *\n * **Not overridable in.** The 100k cap is a fixed constant so\n * the failure mode is consistent across the codebase; a\n * `{ maxGroups }` override can be added later without a break if a\n * real consumer asks.\n */\nexport class GroupCardinalityError extends NoydbError {\n  /** The field being grouped on. */\n  readonly field: string\n  /** Observed number of distinct groups at the moment the cap tripped. */\n  readonly cardinality: number\n  /** The cap that was exceeded. */\n  readonly maxGroups: number\n\n  constructor(field: string, cardinality: number, maxGroups: number) {\n    super(\n      'GROUP_CARDINALITY',\n      `.groupBy(\"${field}\") produced ${cardinality} distinct groups, ` +\n        `exceeding the ${maxGroups}-group ceiling. This is almost always a ` +\n        `query mistake — grouping on a high-uniqueness field like \"id\" or ` +\n        `\"createdAt\" produces one bucket per record. Narrow the query with ` +\n        `.where() before grouping, or group on a lower-cardinality field ` +\n        `(status, category, clientId). If you genuinely need high-cardinality ` +\n        `grouping, file an issue with your use case.`,\n    )\n    this.name = 'GroupCardinalityError'\n    this.field = field\n    this.cardinality = cardinality\n    this.maxGroups = maxGroups\n  }\n}\n\n/**\n * Thrown in lazy mode when a `.query()` / `.where()` / `.orderBy()` clause\n * references a field that does not have a declared index.\n *\n * Lazy-mode queries only work when every touched field is indexed.\n * This is deliberate — silent scan-fallback would hide the performance\n * cliff that lazy-mode indexes exist to prevent.\n *\n * Payload:\n * - `collection` — name of the collection queried\n * - `touchedFields` — every field referenced by the query (filter + order)\n * - `missingFields` — subset of `touchedFields` that have no declared index\n */\nexport class IndexRequiredError extends NoydbError {\n  readonly collection: string\n  readonly touchedFields: readonly string[]\n  readonly missingFields: readonly string[]\n\n  constructor(args: { collection: string; touchedFields: readonly string[]; missingFields: readonly string[] }) {\n    super(\n      'INDEX_REQUIRED',\n      `Collection \"${args.collection}\": query references unindexed fields in lazy mode ` +\n      `(missing: ${args.missingFields.join(', ')}). ` +\n      `Declare an index on each field, or use collection.scan() for non-indexed iteration.`,\n    )\n    this.name = 'IndexRequiredError'\n    this.collection = args.collection\n    this.touchedFields = [...args.touchedFields]\n    this.missingFields = [...args.missingFields]\n  }\n}\n\n/**\n * Thrown (or surfaced via the `index:write-partial` event) when one or more\n * per-indexed-field side-car writes fail after the main record write has\n * already succeeded.\n *\n * Not thrown out of `.put()` / `.delete()` directly — those succeed when the\n * main record succeeds. Instead, `IndexWriteFailureError` instances are collected\n * into the session-scoped reconcile queue and emitted on the Collection\n * emitter as `index:write-partial`.\n *\n * Payload:\n * - `recordId` — the id of the main record whose side-car writes failed\n * - `field` — the indexed field whose side-car write failed\n * - `op` — `'put'` or `'delete'`, indicating which mutation was in flight\n * - `cause` — the underlying error from the store\n */\nexport class IndexWriteFailureError extends NoydbError {\n  readonly recordId: string\n  readonly field: string\n  readonly op: 'put' | 'delete'\n  override readonly cause: unknown\n\n  constructor(args: { recordId: string; field: string; op: 'put' | 'delete'; cause: unknown }) {\n    super(\n      'INDEX_WRITE_FAILURE',\n      `Index side-car ${args.op} failed for field \"${args.field}\" on record \"${args.recordId}\"`,\n    )\n    this.name = 'IndexWriteFailureError'\n    this.recordId = args.recordId\n    this.field = args.field\n    this.op = args.op\n    this.cause = args.cause\n  }\n}\n\n// ─── Bundle Format Errors ─────────────────────────────────\n\n/**\n * Thrown by `readNoydbBundle()` when the body bytes don't match\n * the integrity hash declared in the bundle header — i.e. someone\n * modified the bytes between write and read.\n *\n * Distinct from a generic `Error` (which would be thrown for\n * format violations like a missing magic prefix or malformed\n * header JSON) so consumers can pattern-match the corruption case\n * and handle it differently from a producer bug. A\n * `BundleIntegrityError` indicates \"the bytes you got are not\n * what was written\"; a plain `Error` from `parsePrefixAndHeader`\n * indicates \"what was written wasn't a valid bundle in the first\n * place.\"\n *\n * Also thrown when decompression fails after the integrity hash\n * passed — that's a producer bug (the wrong algorithm byte was\n * written) but it surfaces with the same error class because the\n * end result is \"the body cannot be turned back into a dump.\"\n */\nexport class BundleIntegrityError extends NoydbError {\n  constructor(message: string) {\n    super('BUNDLE_INTEGRITY', `.noydb bundle integrity check failed: ${message}`)\n    this.name = 'BundleIntegrityError'\n  }\n}\n\n// ─── i18n / Dictionary Errors ──────────────────────────\n\n/**\n * Thrown when `vault.collection()` is called with a name that is\n * reserved for NOYDB internal use (any name starting with `_dict_`).\n *\n * Dictionary collections are accessed exclusively via\n * `vault.dictionary(name)` — attempting to open one as a regular\n * collection would bypass the dictionary invariants (ACL, rename\n * tracking, reserved-name policy).\n */\nexport class ReservedCollectionNameError extends NoydbError {\n  /** The rejected collection name. */\n  readonly collectionName: string\n\n  constructor(collectionName: string) {\n    super(\n      'RESERVED_COLLECTION_NAME',\n      `\"${collectionName}\" is a reserved collection name. ` +\n        `Use vault.dictionary(\"${collectionName.replace(/^_dict_/, '')}\") ` +\n        `to access dictionary collections.`,\n    )\n    this.name = 'ReservedCollectionNameError'\n    this.collectionName = collectionName\n  }\n}\n\n/**\n * Thrown by `DictionaryHandle.get()` and `DictionaryHandle.delete()` when\n * the requested key does not exist in the dictionary.\n *\n * Distinct from `NotFoundError` (which is for data records) so callers\n * can distinguish \"data record missing\" from \"dictionary key missing\"\n * without inspecting error messages.\n */\nexport class DictKeyMissingError extends NoydbError {\n  /** The dictionary name. */\n  readonly dictionaryName: string\n  /** The key that was not found. */\n  readonly key: string\n\n  constructor(dictionaryName: string, key: string) {\n    super(\n      'DICT_KEY_MISSING',\n      `Dictionary \"${dictionaryName}\" has no entry for key \"${key}\".`,\n    )\n    this.name = 'DictKeyMissingError'\n    this.dictionaryName = dictionaryName\n    this.key = key\n  }\n}\n\n/**\n * Thrown by `DictionaryHandle.delete()` in strict mode when the key to\n * be deleted is still referenced by one or more records.\n *\n * The caller must either rename the key first (the only sanctioned\n * mass-mutation path) or pass `{ mode: 'warn' }` to skip the check\n * (development only).\n */\nexport class DictKeyInUseError extends NoydbError {\n  /** The dictionary name. */\n  readonly dictionaryName: string\n  /** The key that is still referenced. */\n  readonly key: string\n  /** Name of the first collection found to reference this key. */\n  readonly usedBy: string\n  /** Number of records in `usedBy` that reference this key. */\n  readonly count: number\n\n  constructor(\n    dictionaryName: string,\n    key: string,\n    usedBy: string,\n    count: number,\n  ) {\n    super(\n      'DICT_KEY_IN_USE',\n      `Cannot delete key \"${key}\" from dictionary \"${dictionaryName}\": ` +\n        `${count} record(s) in \"${usedBy}\" still reference it. ` +\n        `Use dictionary.rename(\"${key}\", newKey) to rewrite references first.`,\n    )\n    this.name = 'DictKeyInUseError'\n    this.dictionaryName = dictionaryName\n    this.key = key\n    this.usedBy = usedBy\n    this.count = count\n  }\n}\n\n/**\n * Thrown by `Collection.put()` when an `i18nText` field is missing one\n * or more required translations.\n *\n * The `missing` array names each locale code that was absent from the\n * field value. The `field` property names the field so callers can\n * render a field-level error message without parsing the string.\n */\nexport class MissingTranslationError extends NoydbError {\n  /** The field name whose translation(s) are missing. */\n  readonly field: string\n  /** Locale codes that were required but absent. */\n  readonly missing: readonly string[]\n\n  constructor(field: string, missing: readonly string[], message?: string) {\n    super(\n      'MISSING_TRANSLATION',\n      message ??\n        `Field \"${field}\": missing required translation(s): ${missing.join(', ')}.`,\n    )\n    this.name = 'MissingTranslationError'\n    this.field = field\n    this.missing = missing\n  }\n}\n\n/**\n * Thrown when reading an `i18nText` field without specifying a locale —\n * either at the call site (`get(id, { locale })`) or on the vault\n * (`openVault(name, { locale })`).\n *\n * Also thrown when `resolveI18nText()` exhausts the fallback chain and\n * no translation is available for the requested locale.\n *\n * The `field` property names the field that triggered the error so the\n * caller can surface it in the UI.\n */\nexport class LocaleNotSpecifiedError extends NoydbError {\n  /** The field name that required a locale. */\n  readonly field: string\n\n  constructor(field: string, message?: string) {\n    super(\n      'LOCALE_NOT_SPECIFIED',\n      message ??\n        `Cannot read i18nText field \"${field}\" without a locale. ` +\n        `Pass { locale } to get()/list()/query() or set a default via ` +\n        `openVault(name, { locale }).`,\n    )\n    this.name = 'LocaleNotSpecifiedError'\n    this.field = field\n  }\n}\n\n// ─── Translator Errors ─────────────────────────────────────\n\n/**\n * Thrown when a collection has an `i18nText` field with\n * `autoTranslate: true` but no `plaintextTranslator` was configured\n * on `createNoydb()`.\n *\n * The error is raised at `put()` time (not at schema construction) so\n * the mis-configuration is surfaced by the first write rather than\n * silently at startup.\n */\nexport class TranslatorNotConfiguredError extends NoydbError {\n  /** The field that requested auto-translation. */\n  readonly field: string\n  /** The collection the put was targeting. */\n  readonly collection: string\n\n  constructor(field: string, collection: string) {\n    super(\n      'TRANSLATOR_NOT_CONFIGURED',\n      `Field \"${field}\" in collection \"${collection}\" has autoTranslate: true, ` +\n        `but no plaintextTranslator was configured on createNoydb(). ` +\n        `Either configure a plaintextTranslator or remove autoTranslate from the schema.`,\n    )\n    this.name = 'TranslatorNotConfiguredError'\n    this.field = field\n    this.collection = collection\n  }\n}\n\n// ─── Backup Errors ─────────────────────────────────────────\n\n/**\n * Thrown when `Vault.load()` finds that a backup's hash chain\n * doesn't verify, or that its embedded `ledgerHead.hash` doesn't\n * match the chain head reconstructed from the loaded entries.\n *\n * Distinct from `BackupCorruptedError` so callers can choose to\n * recover from one but not the other (e.g., a corrupted JSON file is\n * unrecoverable; a chain mismatch might mean the backup is from an\n * incompatible noy-db version).\n */\nexport class BackupLedgerError extends NoydbError {\n  /** First-broken-entry index, if known. */\n  readonly divergedAt?: number\n\n  constructor(message: string, divergedAt?: number) {\n    super('BACKUP_LEDGER', message)\n    this.name = 'BackupLedgerError'\n    if (divergedAt !== undefined) this.divergedAt = divergedAt\n  }\n}\n\n/**\n * Thrown when `Vault.load()` finds that the backup's data\n * collection content doesn't match the ledger's recorded\n * `payloadHash`es. This is the \"envelope was tampered with after\n * dump\" detection — the chain itself can be intact, but if any\n * encrypted record bytes were swapped, this check catches it.\n */\nexport class BackupCorruptedError extends NoydbError {\n  /** The (collection, id) pair whose envelope failed the hash check. */\n  readonly collection: string\n  readonly id: string\n\n  constructor(collection: string, id: string, message: string) {\n    super('BACKUP_CORRUPTED', message)\n    this.name = 'BackupCorruptedError'\n    this.collection = collection\n    this.id = id\n  }\n}\n\n// ─── Session Errors ───────────────────────────────────────\n\n/**\n * Thrown by `resolveSession()` when the session token's `expiresAt`\n * timestamp is in the past. The session key is also removed from the\n * in-memory store when this is thrown, so retrying with the same sessionId\n * will produce `SessionNotFoundError`.\n *\n * Separate from `SessionNotFoundError` so callers can distinguish between\n * \"session is gone\" (key store cleared, tab reloaded) and \"session is\n * still in the store but has exceeded its lifetime\" (idle timeout, absolute\n * timeout, policy-driven expiry). The remediation differs: expired sessions\n * should prompt a fresh unlock; not-found sessions may indicate a bug or a\n * cross-tab scenario where the session was never established.\n */\nexport class SessionExpiredError extends NoydbError {\n  readonly sessionId: string\n\n  constructor(sessionId: string) {\n    super('SESSION_EXPIRED', `Session \"${sessionId}\" has expired. Re-unlock to continue.`)\n    this.name = 'SessionExpiredError'\n    this.sessionId = sessionId\n  }\n}\n\n/**\n * Thrown by `resolveSession()` when the session key cannot be found in\n * the module-level store. This happens when:\n *   - The session was explicitly revoked via `revokeSession()`.\n *   - The JS context was reloaded (tab navigation, page refresh, worker restart).\n *   - `Noydb.close()` was called (which calls `revokeAllSessions()`).\n *   - The sessionId is wrong or was generated by a different JS context.\n *\n * The session token (if the caller holds it) is permanently useless after\n * this error — the key is gone and cannot be recovered.\n */\nexport class SessionNotFoundError extends NoydbError {\n  readonly sessionId: string\n\n  constructor(sessionId: string) {\n    super('SESSION_NOT_FOUND', `Session key for \"${sessionId}\" not found. The session may have been revoked or the page reloaded.`)\n    this.name = 'SessionNotFoundError'\n    this.sessionId = sessionId\n  }\n}\n\n/**\n * Thrown when a session policy blocks an operation — for example,\n * `requireReAuthFor: ['export']` is set and the caller attempts to\n * call `exportStream()` without re-authenticating for this session.\n *\n * The `operation` field names the specific operation that was blocked\n * (e.g. `'export'`, `'grant'`, `'rotate'`) so the caller can surface\n * a targeted prompt (\"Please re-enter your passphrase to export data\").\n */\nexport class SessionPolicyError extends NoydbError {\n  readonly operation: string\n\n  constructor(operation: string, message?: string) {\n    super(\n      'SESSION_POLICY',\n      message ?? `Operation \"${operation}\" requires re-authentication per the active session policy.`,\n    )\n    this.name = 'SessionPolicyError'\n    this.operation = operation\n  }\n}\n\n// ─── Query / Join Errors ────────────────────────────────────\n\n/**\n * Thrown when a `.join()` would exceed its configured row ceiling on\n * either side. The ceiling defaults to 50,000 per side and can be\n * overridden via the `{ maxRows }` option on `.join()`.\n *\n * Carries both row counts so the error message can show which side\n * tripped the limit (e.g. \"left had 60,000 rows, right had 1,200,\n * max was 50,000\"). The `side` field is machine-readable so test\n * code and devtools can match on it without regex-parsing the\n * message.\n *\n * The row ceiling exists because joins are bounded in-memory\n * operations over materialized record sets. Consumers whose\n * collections genuinely exceed the ceiling should track \n * (streaming joins over `scan()`) or filter the left side further\n * with `where()` / `limit()` before joining.\n */\nexport class JoinTooLargeError extends NoydbError {\n  readonly leftRows: number\n  readonly rightRows: number\n  readonly maxRows: number\n  readonly side: 'left' | 'right'\n\n  constructor(opts: {\n    leftRows: number\n    rightRows: number\n    maxRows: number\n    side: 'left' | 'right'\n    message: string\n  }) {\n    super('JOIN_TOO_LARGE', opts.message)\n    this.name = 'JoinTooLargeError'\n    this.leftRows = opts.leftRows\n    this.rightRows = opts.rightRows\n    this.maxRows = opts.maxRows\n    this.side = opts.side\n  }\n}\n\n/**\n * Thrown by `.join()` in strict `ref()` mode when a left-side record\n * points at a right-side id that does not exist in the target\n * collection.\n *\n * Distinct from `RefIntegrityError` so test code can pattern-match\n * on the *read-time* dangling case without catching *write-time*\n * integrity violations. Both indicate \"ref points at nothing\" but\n * happen at different lifecycle phases and deserve different\n * remediation in documentation: a RefIntegrityError on `put()`\n * means the input is invalid; a DanglingReferenceError on `.join()`\n * means stored data has drifted and `vault.checkIntegrity()`\n * is the right tool to find the full set of orphans.\n */\nexport class DanglingReferenceError extends NoydbError {\n  readonly field: string\n  readonly target: string\n  readonly refId: string\n\n  constructor(opts: {\n    field: string\n    target: string\n    refId: string\n    message: string\n  }) {\n    super('DANGLING_REFERENCE', opts.message)\n    this.name = 'DanglingReferenceError'\n    this.field = opts.field\n    this.target = opts.target\n    this.refId = opts.refId\n  }\n}\n\n/**\n * Thrown by {@link sanitizeFilename} when an input filename cannot be\n * made safe — NUL byte, empty after normalization, missing\n * `opaqueId` for the opaque profile, `..` segment, or a `maxBytes`\n * cap too small to hold a single code point.\n */\nexport class FilenameSanitizationError extends NoydbError {\n  constructor(message: string) {\n    super('FILENAME_SANITIZATION', message)\n    this.name = 'FilenameSanitizationError'\n  }\n}\n\n/**\n * Thrown when a write target resolves OUTSIDE the requested\n * directory after sanitization — the canonical Zip-Slip class. The\n * sanitizer's job is to strip path-traversal segments; this error\n * is the defense-in-depth fallback at the FS write site.\n */\nexport class PathEscapeError extends NoydbError {\n  readonly attempted: string\n  readonly targetDir: string\n\n  constructor(opts: { attempted: string; targetDir: string }) {\n    super(\n      'PATH_ESCAPE',\n      `Sanitized filename \"${opts.attempted}\" resolves outside target dir \"${opts.targetDir}\"`,\n    )\n    this.name = 'PathEscapeError'\n    this.attempted = opts.attempted\n    this.targetDir = opts.targetDir\n  }\n}\n","/**\n * Query DSL `.groupBy()` —.\n *\n * Chains after `.where()` / `.filter()` / `.or()` / `.and()` on a\n * Query and before a reducer spec, so consumers can compute\n * per-bucket aggregates without folding in userland:\n *\n * ```ts\n * const byClient = invoices.query()\n *   .where('status', '==', 'open')\n *   .groupBy('clientId')\n *   .aggregate({ total: sum('amount'), n: count() })\n *   .run()\n * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]\n * ```\n *\n * Execution pipeline:\n *\n *   1. Run the query's where/filter clauses (same candidate /\n *      filter pipeline as `.aggregate()` directly on Query).\n *   2. Partition the matching records into buckets keyed by\n *      `readPath(record, field)`. JS `Map` preserves insertion\n *      order, so the first-seen key for a bucket determines its\n *      position in the result array — consumers who want a\n *      specific ordering should `.sort()` downstream.\n *   3. Enforce cardinality: warn once per field at 10% of the cap\n *      (10_000 buckets), throw `GroupCardinalityError` at 100% of\n *      the cap (100_000 buckets).\n *   4. For each bucket, build a per-group reducer state and\n *      step every record in the bucket through it.\n *   5. Emit one result row per bucket, shaped as\n *      `{ [field]: key, ...reduced }`.\n *\n * **Null / undefined keys:** `Map` distinguishes `null` from\n * `undefined`, so records with a missing group field get their own\n * bucket, and records with an explicit `null` value get a separate\n * bucket from that. Consumers who want them merged can coalesce\n * upstream with `.filter()`.\n *\n * **Live mode:** `.groupBy().aggregate().live()` re-runs the full\n * grouping pipeline on every source change. Per-bucket incremental\n * delta maintenance is a future optimization — the reducer\n * protocol's `remove()` hook admits it, but ships naive\n * re-grouping for simplicity.\n *\n * **Type-level stable-key narrowing:** when\n * `dictKey` lands, `groupBy<DictField>()` will narrow the group key\n * type to the stable dictionary key rather than the resolved locale\n * label. That prevents grouping by the locale-resolved label,\n * which would produce different buckets per reader. types the\n * key as `unknown` at the result shape; the dictKey narrowing\n * layers on top without an API break.\n *\n * Partition-awareness seam: when partitioned collections land,\n * per-partition grouping will need to merge sub-results across\n * partitions. The reducer protocol's `{ seed }` parameter\n * (already plumbed through in `reducers.ts`) is the mechanism —\n * groupBy doesn't need its own seam for the moment, because it\n * delegates to the reducer protocol for all per-bucket state.\n */\n\nimport { readPath } from '../query/predicate.js'\nimport type {\n  AggregateSpec,\n  AggregateResult,\n  AggregationUpstream,\n  LiveAggregation,\n} from './aggregation.js'\nimport { buildLiveAggregation } from './aggregation.js'\nimport { GroupCardinalityError } from '../errors.js'\n\n/**\n * Cardinality thresholds for `.groupBy()`. The warn threshold gives\n * consumers a heads-up before the hard error; the cap is a fixed\n * constant in (not overridable). A `{ maxGroups }` override\n * can be added later without a break if a real consumer asks.\n */\nexport const GROUPBY_WARN_CARDINALITY = 10_000\nexport const GROUPBY_MAX_CARDINALITY = 100_000\n\n/**\n * One-shot warning dedup per-field — reactive dashboards\n * re-executing the same grouped query should produce the warning\n * once, not once per re-fire. Keyed on the grouping field name\n * because \"this field has high cardinality on your current data\"\n * is a field-level property, not a per-query one.\n */\nconst warnedCardinalityFields = new Set<string>()\nfunction warnCardinalityApproaching(field: string, observed: number): void {\n  if (warnedCardinalityFields.has(field)) return\n  warnedCardinalityFields.add(field)\n  console.warn(\n    `[noy-db] .groupBy(\"${field}\") produced ${observed} distinct groups, ` +\n      `${Math.round((observed / GROUPBY_MAX_CARDINALITY) * 100)}% of the ` +\n      `${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with ` +\n      `.where() before grouping, or switch to a lower-cardinality field.`,\n  )\n}\n\n/**\n * Test-only: clear the per-field cardinality warning dedup between\n * tests. Production code never calls this — matching the\n * `resetJoinWarnings` pattern in `join.ts`.\n */\nexport function resetGroupByWarnings(): void {\n  warnedCardinalityFields.clear()\n}\n\n/**\n * Result row shape for a grouped aggregation. Each row carries the\n * group key value under the grouping field name plus every reducer\n * output from the spec.\n *\n * types the group key as `unknown` at the result shape — the\n * runtime read via `readPath` can return any value, and narrowing\n * to a specific type would require the caller to assert at the\n * call site. `dictKey` narrowing layers on top of this by\n * adding an overload that constrains `F` when the grouping field\n * is a `dictKey`.\n */\nexport type GroupedRow<F extends string, R> = { [K in F]: unknown } & R\n\n/**\n * Chainable wrapper returned by `Query.groupBy(field)`. Terminates\n * with `.aggregate(spec)` which returns a `GroupedAggregation`.\n *\n * Kept minimal — the only operation on a grouped query is\n * aggregation. Ordering, limiting, and further filtering belong on\n * the underlying `Query` before `.groupBy()` is called; applying\n * them post-group would be a different operation (`having` /\n * `groupOrderBy`), out of scope for.\n */\nexport class GroupedQuery<T, F extends string> {\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    private readonly field: F,\n    private readonly upstreams: readonly AggregationUpstream[],\n    /**\n     * Optional dict label resolver attached by the query builder when\n     * the grouping field is a dictKey.\n     */\n    private readonly dictLabelResolver?: (\n      key: string,\n      locale: string,\n      fallback?: string | readonly string[],\n    ) => Promise<string | undefined>,\n  ) {\n    // T is phantom on the wrapper so consumers can still see the\n    // source row type on hover. Reference it to keep lint quiet.\n    void undefined as T | undefined\n  }\n\n  /**\n   * Build a grouped aggregation. Returns a `GroupedAggregation`\n   * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape\n   * as the non-grouped `.aggregate()` wrapper, just with an array\n   * result (one row per bucket) instead of a single reduced object.\n   */\n  aggregate<Spec extends AggregateSpec>(\n    spec: Spec,\n  ): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>> {\n    return new GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>(\n      this.executeRecords,\n      this.field,\n      spec,\n      this.upstreams,\n      this.dictLabelResolver,\n    )\n  }\n}\n\n/**\n * Execute the group-and-reduce pipeline. Pure function over a\n * record array and a spec — shared by `GroupedAggregation.run()`\n * and the live-mode refresh path. Exported for tests and for any\n * future `scan().groupBy().aggregate()` reuse.\n *\n * Enforces the cardinality cap incrementally during the partition\n * loop, so a runaway grouping throws at the moment the 100_001st\n * bucket would be created — the consumer doesn't have to wait for\n * the full partition to materialize before the error fires.\n */\nexport function groupAndReduce<R>(\n  records: readonly unknown[],\n  field: string,\n  spec: AggregateSpec,\n): R[] {\n  // Map preserves insertion order natively (ES2015), so first-seen\n  // keys determine output ordering without a parallel order array.\n  const buckets = new Map<unknown, unknown[]>()\n  for (const record of records) {\n    const key = readPath(record, field)\n    let bucket = buckets.get(key)\n    if (bucket === undefined) {\n      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {\n        throw new GroupCardinalityError(\n          field,\n          buckets.size + 1,\n          GROUPBY_MAX_CARDINALITY,\n        )\n      }\n      bucket = []\n      buckets.set(key, bucket)\n    }\n    bucket.push(record)\n  }\n\n  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {\n    warnCardinalityApproaching(field, buckets.size)\n  }\n\n  // Reduce each bucket through the spec. Same init/step/finalize\n  // pipeline as `reduceRecords` in aggregate.ts, but one state per\n  // bucket. Inlining the loop here keeps the per-bucket path tight\n  // — calling `reduceRecords` per bucket would recompute\n  // `Object.keys(spec)` once per bucket unnecessarily.\n  const keys = Object.keys(spec)\n  const out: R[] = []\n  for (const [groupKey, bucketRecords] of buckets) {\n    const state: Record<string, unknown> = {}\n    for (const key of keys) {\n      state[key] = spec[key]!.init()\n    }\n    for (const record of bucketRecords) {\n      for (const key of keys) {\n        state[key] = spec[key]!.step(state[key], record)\n      }\n    }\n    const row: Record<string, unknown> = { [field]: groupKey }\n    for (const key of keys) {\n      row[key] = spec[key]!.finalize(state[key])\n    }\n    out.push(row as unknown as R)\n  }\n  return out\n}\n\n/**\n * Grouped aggregation wrapper — the `.groupBy(field).aggregate(spec)`\n * terminal. Shape mirrors `Aggregation<R>` from aggregate.ts: two\n * terminals (`.run()` and `.live()`), spec bound at construction\n * time, upstreams collected for live mode.\n *\n * The generic `R` is the per-row result shape (i.e. a single\n * grouped row), and the terminals return `R[]` — one row per\n * bucket.\n */\nexport class GroupedAggregation<R> {\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    private readonly field: string,\n    private readonly spec: AggregateSpec,\n    private readonly upstreams: readonly AggregationUpstream[],\n    /**\n     * Optional dict label resolver for `<field>Label` projection\n     *. Present when the grouping field is a dictKey.\n     */\n    private readonly dictLabelResolver?: (\n      key: string,\n      locale: string,\n      fallback?: string | readonly string[],\n    ) => Promise<string | undefined>,\n  ) {}\n\n  /** Execute the query, group, reduce, and return an array of rows. */\n  run(): R[] {\n    return groupAndReduce<R>(this.executeRecords(), this.field, this.spec)\n  }\n\n  /**\n   * Execute the query, group, reduce, and resolve `<field>Label` for\n   * each result row when the grouping field is a `dictKey` and a\n   * `locale` is provided. Returns `R[]` synchronously when\n   * no locale is specified (identical to `.run()`).\n   *\n   * The `<field>Label` field is appended to each row. Rows whose group\n   * key has no dictionary entry get `<field>Label: undefined`.\n   */\n  async runAsync(opts?: {\n    locale?: string\n    fallback?: string | readonly string[]\n  }): Promise<R[]> {\n    const rows = groupAndReduce<R>(this.executeRecords(), this.field, this.spec)\n    if (!opts?.locale || !this.dictLabelResolver) return rows\n\n    const resolve = this.dictLabelResolver\n    const locale = opts.locale\n    const fallback = opts.fallback\n    const labelKey = `${this.field}Label`\n\n    return Promise.all(\n      rows.map(async (row) => {\n        const key = (row as Record<string, unknown>)[this.field]\n        if (typeof key !== 'string') return row\n        const label = await resolve(key, locale, fallback)\n        return { ...(row as Record<string, unknown>), [labelKey]: label } as unknown as R\n      }),\n    )\n  }\n\n  /**\n   * Build a reactive `LiveAggregation<R[]>` that re-runs the full\n   * group-and-reduce pipeline whenever any upstream source notifies\n   * of a change. Same error-isolation and idempotent-stop contract\n   * as `Aggregation.live()` — the implementation delegates to the\n   * same `LiveAggregationImpl` class by threading a fresh\n   * recompute closure through the existing constructor.\n   *\n   * uses naive full re-run on every change. Incremental\n   * per-bucket maintenance (apply `step` on inserted records,\n   * `remove` on deleted records, route by bucket key) is a future\n   * optimization — the reducer protocol admits it, but wiring\n   * delta-aware source subscriptions is a separate PR.\n   *\n   * Always call `live.stop()` when finished.\n   */\n  live(): LiveAggregation<R[]> {\n    const recompute = (): R[] =>\n      groupAndReduce<R>(this.executeRecords(), this.field, this.spec)\n    return buildLiveAggregation<R[]>(recompute, this.upstreams)\n  }\n}\n","/**\n * Active aggregate strategy factory. Calling `withAggregate()` returns\n * an `AggregateStrategy` whose methods construct real `Aggregation` /\n * `GroupedQuery` instances and run the streaming reducer protocol.\n *\n * This module is only reachable through the `@noy-db/hub/aggregate`\n * subpath — a consumer that never imports the subpath ships none of\n * this (ESM tree-shaking + hub's `\"sideEffects\": false`).\n */\n\nimport { Aggregation, reduceRecords } from './aggregation.js'\nimport type { AggregateSpec, AggregateResult } from './aggregation.js'\nimport { GroupedQuery } from './groupby.js'\nimport type { AggregateStrategy } from './strategy.js'\n\n/**\n * Build the default aggregate strategy. Pass into\n * `createNoydb({ aggregateStrategy: withAggregate() })` to light up\n * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.\n *\n * @example\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withAggregate, sum, count } from '@noy-db/hub/aggregate'\n *\n * const db = await createNoydb({\n *   store, user, secret,\n *   aggregateStrategy: withAggregate(),\n * })\n *\n * const totals = invoices.query()\n *   .where('status', '==', 'paid')\n *   .groupBy('clientId')\n *   .aggregate({ amount: sum('amount'), n: count() })\n *   .run()\n * ```\n */\nexport function withAggregate(): AggregateStrategy {\n  return {\n    aggregate(executeRecords, spec, upstreams) {\n      return new Aggregation(executeRecords, spec as unknown as AggregateSpec, upstreams) as unknown as Aggregation<AggregateResult<typeof spec>>\n    },\n    groupBy(executeRecords, field, upstreams, dictLabelResolver) {\n      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver)\n    },\n    async scanAggregate(iter, spec) {\n      const collected: unknown[] = []\n      for await (const record of iter) collected.push(record)\n      return reduceRecords(collected, spec as unknown as AggregateSpec) as unknown as AggregateResult<typeof spec>\n    },\n  }\n}\n","/**\n * Aggregation reducers for the query DSL.\n *\n * the reducer protocol plus five built-in factories\n * (`count`, `sum`, `avg`, `min`, `max`) consumed by `Query.aggregate()`\n * and, in the future, `Scan.aggregate()`. Every factory accepts\n * an optional `{ seed }` parameter that is plumbed through the\n * protocol but unused by the executor — that's the load-bearing\n * half of  constraint #2. When partition-aware aggregation\n * lands, the seed carries the previous partition's running total into\n * the next partition without requiring a protocol change.\n *\n * Reducers are intentionally generic over their internal state type\n * `S` so compound reducers (avg keeps `{sum, count}`, min/max keep a\n * value bag) can model internal bookkeeping without leaking the\n * implementation through the accumulator's public shape. `finalize`\n * collapses `S` back into the user-visible `R`.\n *\n * Reducers are pure data — `init` / `step` / `finalize` / optional\n * `remove` are stateless functions that receive and return `S`. This\n * is the shape that admits O(1) incremental maintenance in a future\n * optimization (delta-aware `LiveAggregation` applies `step` or\n * `remove` per delta), without blocking the simpler \"full re-run on\n * source change\" that ships.\n */\n\nimport { readPath } from '../query/predicate.js'\n\n/**\n * A single reducer: factory-produced, ready to plug into an\n * `.aggregate()` spec.\n *\n * Type parameters:\n *   - `R` — user-visible result type (what the aggregation returns\n *     for this slot, e.g. `number` for `sum()`)\n *   - `S` — internal state type, defaults to `R` for simple reducers\n *     that don't need compound bookkeeping\n *\n * A reducer is stateless: every method is pure over `S`. `init()` is\n * called once per aggregation run to build the initial state; `step()`\n * folds a record into the state; `remove()` (optional) un-folds a\n * record, enabling incremental live maintenance; `finalize()` reads\n * the final answer out of the state at the end of the run.\n */\nexport interface Reducer<R, S = R> {\n  /** Build the initial state for a fresh aggregation run. */\n  init(): S\n  /** Fold a record into the state. Returns the new state. */\n  step(state: S, record: unknown): S\n  /**\n   * Un-fold a record from the state. Returns the new state.\n   *\n   * Optional — reducers without `remove` cannot be maintained\n   * incrementally and must be re-run from scratch when the underlying\n   * record set changes. `sum`, `count`, `avg` implement `remove` in\n   * O(1); `min` and `max` implement it in O(N) worst case (when the\n   * extremum itself is removed and the next extremum must be\n   * recomputed from the remaining contributing values).\n   */\n  remove?(state: S, record: unknown): S\n  /** Collapse the internal state into the user-visible result. */\n  finalize(state: S): R\n}\n\n/**\n * Common options accepted by every reducer factory.\n *\n * `seed` — optional initial value for the internal state. **Unused by\n * the executor**, plumbed through the protocol for  constraint\n * #2 (partition-aware aggregation seam). In, partitioned\n * aggregations will pass the previous partition's carry as `seed` so\n * a long time series can be rolled forward one partition at a time\n * without re-aggregating closed partitions.\n *\n * always uses `init()` with the factory's zero value, regardless\n * of whether `seed` was passed. Do not remove the parameter — that's\n * the whole point of having it exist now.\n */\nexport interface ReducerOptions<TSeed = unknown> {\n  /**  constraint #2 — seed is plumbed through but unused in. */\n  readonly seed?: TSeed\n}\n\n// ---------------------------------------------------------------------------\n// Factories\n// ---------------------------------------------------------------------------\n\n/**\n * Count the number of records that match the query. Ignores field\n * values entirely — the count is over the number of records, not over\n * the number of non-null field values in any column.\n */\nexport function count(opts?: ReducerOptions<number>): Reducer<number> {\n  // Seed captured on the closure but unused at execution time in\n  //. The reference in _seed keeps lint happy.\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => 0,\n    step: (state) => state + 1,\n    remove: (state) => state - 1,\n    finalize: (state) => state,\n  }\n}\n\n/**\n * Sum a numeric field across all matching records. Non-number values\n * at the field path are coerced to 0 — consumers who want a different\n * behavior (throw, skip, treat as NaN) should filter upstream via\n * `.where()` or write a custom reducer.\n */\nexport function sum(\n  field: string,\n  opts?: ReducerOptions<number>,\n): Reducer<number> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => 0,\n    step: (state, record) => state + readNumber(record, field),\n    remove: (state, record) => state - readNumber(record, field),\n    finalize: (state) => state,\n  }\n}\n\n/**\n * Arithmetic mean of a numeric field across all matching records.\n *\n * Returns `null` for an empty result set (zero records is not a\n * well-defined denominator — returning NaN would poison downstream\n * arithmetic, and throwing would force every consumer to wrap in\n * try/catch just to handle \"no matches\"). Consumers who want an\n * explicit zero should coalesce with `?? 0`.\n *\n * Internal state is `{sum, count}` so the running average can be\n * maintained incrementally — on each delta, both fields update in\n * O(1) and `finalize` divides. Directly storing `avg` as state would\n * not admit incremental removal without also tracking count.\n */\nexport function avg(\n  field: string,\n  opts?: ReducerOptions<{ sum: number; count: number }>,\n): Reducer<number | null, { sum: number; count: number }> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => ({ sum: 0, count: 0 }),\n    step: (state, record) => ({\n      sum: state.sum + readNumber(record, field),\n      count: state.count + 1,\n    }),\n    remove: (state, record) => ({\n      sum: state.sum - readNumber(record, field),\n      count: state.count - 1,\n    }),\n    finalize: (state) => (state.count === 0 ? null : state.sum / state.count),\n  }\n}\n\ninterface MinMaxState {\n  /**\n   * Multiset of contributing field values. Stored as a plain array\n   * because we need to support `remove` and a plain array gives us\n   * O(1) push + O(N) worst-case removal — which matches the\n   * documented min/max removal complexity. A sorted structure would\n   * let us drop the O(N) rescan but adds complexity that doesn't\n   * need; consumers hitting the O(N) ceiling should file an issue.\n   */\n  readonly values: number[]\n}\n\nfunction pushValue(state: MinMaxState, value: number): MinMaxState {\n  return { values: [...state.values, value] }\n}\n\nfunction removeValue(state: MinMaxState, value: number): MinMaxState {\n  // Remove the first matching value — duplicates are fine, we only\n  // need to drop one instance per `remove()` call so the multiset\n  // count stays consistent with the record count.\n  const idx = state.values.indexOf(value)\n  if (idx < 0) return state\n  const next = state.values.slice()\n  next.splice(idx, 1)\n  return { values: next }\n}\n\n/**\n * Smallest numeric value of a field across all matching records.\n * Returns `null` for an empty result set. See `avg()` for the\n * reasoning on `null` vs NaN vs throwing.\n *\n * Incremental complexity: O(1) for `step`, O(N) worst case for\n * `remove` when the current minimum is removed (the state holds the\n * full multiset of contributing values and `finalize` scans for the\n * new minimum). Consumers with very large result sets and frequent\n * removals of the current extremum should either accept the cost or\n * wait for a future optimization.\n */\nexport function min(\n  field: string,\n  opts?: ReducerOptions<number>,\n): Reducer<number | null, MinMaxState> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => ({ values: [] }),\n    step: (state, record) => pushValue(state, readNumber(record, field)),\n    remove: (state, record) => removeValue(state, readNumber(record, field)),\n    finalize: (state) => {\n      if (state.values.length === 0) return null\n      let out = state.values[0]!\n      for (let i = 1; i < state.values.length; i++) {\n        const v = state.values[i]!\n        if (v < out) out = v\n      }\n      return out\n    },\n  }\n}\n\n/**\n * Largest numeric value of a field across all matching records.\n * Mirror of `min()` — see that doc for semantics, null-on-empty\n * behavior, and the O(N) removal caveat.\n */\nexport function max(\n  field: string,\n  opts?: ReducerOptions<number>,\n): Reducer<number | null, MinMaxState> {\n  const _seed = opts?.seed\n  void _seed\n  return {\n    init: () => ({ values: [] }),\n    step: (state, record) => pushValue(state, readNumber(record, field)),\n    remove: (state, record) => removeValue(state, readNumber(record, field)),\n    finalize: (state) => {\n      if (state.values.length === 0) return null\n      let out = state.values[0]!\n      for (let i = 1; i < state.values.length; i++) {\n        const v = state.values[i]!\n        if (v > out) out = v\n      }\n      return out\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Read a numeric field from a record. Non-number values (null,\n * undefined, strings, objects) coerce to 0 so sum/avg/min/max don't\n * produce NaN on one bad row. Consumers who want strict typing should\n * validate upstream with Standard Schema, which NOYDB already runs on\n * every `put()`.\n */\nfunction readNumber(record: unknown, field: string): number {\n  const value = readPath(record, field)\n  return typeof value === 'number' && Number.isFinite(value) ? value : 0\n}\n"],"mappings":"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","names":[]}

package/dist/aggregate/index.d.cts

@@ -0,0 +1,38 @@
+import { A as AggregateStrategy } from '../strategy-D-SrOLCl.cjs';
+export { a as AggregateResult, b as AggregateSpec, c as Aggregation, d as AggregationUpstream, G as GROUPBY_MAX_CARDINALITY, e as GROUPBY_WARN_CARDINALITY, f as GroupedAggregation, g as GroupedQuery, h as GroupedRow, L as LiveAggregation, R as Reducer, i as ReducerOptions, j as avg, k as buildLiveAggregation, l as count, m as groupAndReduce, n as max, o as min, r as reduceRecords, p as resetGroupByWarnings, s as sum } from '../strategy-D-SrOLCl.cjs';
+
+/**
+ * Active aggregate strategy factory. Calling `withAggregate()` returns
+ * an `AggregateStrategy` whose methods construct real `Aggregation` /
+ * `GroupedQuery` instances and run the streaming reducer protocol.
+ *
+ * This module is only reachable through the `@noy-db/hub/aggregate`
+ * subpath — a consumer that never imports the subpath ships none of
+ * this (ESM tree-shaking + hub's `"sideEffects": false`).
+ */
+
+/**
+ * Build the default aggregate strategy. Pass into
+ * `createNoydb({ aggregateStrategy: withAggregate() })` to light up
+ * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.
+ *
+ * @example
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withAggregate, sum, count } from '@noy-db/hub/aggregate'
+ *
+ * const db = await createNoydb({
+ *   store, user, secret,
+ *   aggregateStrategy: withAggregate(),
+ * })
+ *
+ * const totals = invoices.query()
+ *   .where('status', '==', 'paid')
+ *   .groupBy('clientId')
+ *   .aggregate({ amount: sum('amount'), n: count() })
+ *   .run()
+ * ```
+ */
+declare function withAggregate(): AggregateStrategy;
+
+export { AggregateStrategy, withAggregate };

package/dist/aggregate/index.d.ts

@@ -0,0 +1,38 @@
+import { A as AggregateStrategy } from '../strategy-D-SrOLCl.js';
+export { a as AggregateResult, b as AggregateSpec, c as Aggregation, d as AggregationUpstream, G as GROUPBY_MAX_CARDINALITY, e as GROUPBY_WARN_CARDINALITY, f as GroupedAggregation, g as GroupedQuery, h as GroupedRow, L as LiveAggregation, R as Reducer, i as ReducerOptions, j as avg, k as buildLiveAggregation, l as count, m as groupAndReduce, n as max, o as min, r as reduceRecords, p as resetGroupByWarnings, s as sum } from '../strategy-D-SrOLCl.js';
+
+/**
+ * Active aggregate strategy factory. Calling `withAggregate()` returns
+ * an `AggregateStrategy` whose methods construct real `Aggregation` /
+ * `GroupedQuery` instances and run the streaming reducer protocol.
+ *
+ * This module is only reachable through the `@noy-db/hub/aggregate`
+ * subpath — a consumer that never imports the subpath ships none of
+ * this (ESM tree-shaking + hub's `"sideEffects": false`).
+ */
+
+/**
+ * Build the default aggregate strategy. Pass into
+ * `createNoydb({ aggregateStrategy: withAggregate() })` to light up
+ * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.
+ *
+ * @example
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withAggregate, sum, count } from '@noy-db/hub/aggregate'
+ *
+ * const db = await createNoydb({
+ *   store, user, secret,
+ *   aggregateStrategy: withAggregate(),
+ * })
+ *
+ * const totals = invoices.query()
+ *   .where('status', '==', 'paid')
+ *   .groupBy('clientId')
+ *   .aggregate({ amount: sum('amount'), n: count() })
+ *   .run()
+ * ```
+ */
+declare function withAggregate(): AggregateStrategy;
+
+export { AggregateStrategy, withAggregate };

package/dist/aggregate/index.js

@@ -0,0 +1,53 @@
+import {
+  Aggregation,
+  GROUPBY_MAX_CARDINALITY,
+  GROUPBY_WARN_CARDINALITY,
+  GroupedAggregation,
+  GroupedQuery,
+  avg,
+  buildLiveAggregation,
+  count,
+  groupAndReduce,
+  max,
+  min,
+  reduceRecords,
+  resetGroupByWarnings,
+  sum
+} from "../chunk-TDR6T5CJ.js";
+import "../chunk-M5INGEFC.js";
+import "../chunk-ACLDOTNQ.js";
+
+// src/aggregate/active.ts
+function withAggregate() {
+  return {
+    aggregate(executeRecords, spec, upstreams) {
+      return new Aggregation(executeRecords, spec, upstreams);
+    },
+    groupBy(executeRecords, field, upstreams, dictLabelResolver) {
+      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver);
+    },
+    async scanAggregate(iter, spec) {
+      const collected = [];
+      for await (const record of iter) collected.push(record);
+      return reduceRecords(collected, spec);
+    }
+  };
+}
+export {
+  Aggregation,
+  GROUPBY_MAX_CARDINALITY,
+  GROUPBY_WARN_CARDINALITY,
+  GroupedAggregation,
+  GroupedQuery,
+  avg,
+  buildLiveAggregation,
+  count,
+  groupAndReduce,
+  max,
+  min,
+  reduceRecords,
+  resetGroupByWarnings,
+  sum,
+  withAggregate
+};
+//# sourceMappingURL=index.js.map

package/dist/aggregate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/aggregate/active.ts"],"sourcesContent":["/**\n * Active aggregate strategy factory. Calling `withAggregate()` returns\n * an `AggregateStrategy` whose methods construct real `Aggregation` /\n * `GroupedQuery` instances and run the streaming reducer protocol.\n *\n * This module is only reachable through the `@noy-db/hub/aggregate`\n * subpath — a consumer that never imports the subpath ships none of\n * this (ESM tree-shaking + hub's `\"sideEffects\": false`).\n */\n\nimport { Aggregation, reduceRecords } from './aggregation.js'\nimport type { AggregateSpec, AggregateResult } from './aggregation.js'\nimport { GroupedQuery } from './groupby.js'\nimport type { AggregateStrategy } from './strategy.js'\n\n/**\n * Build the default aggregate strategy. Pass into\n * `createNoydb({ aggregateStrategy: withAggregate() })` to light up\n * `.aggregate()` and `.groupBy()` on `Query` and `ScanBuilder`.\n *\n * @example\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withAggregate, sum, count } from '@noy-db/hub/aggregate'\n *\n * const db = await createNoydb({\n *   store, user, secret,\n *   aggregateStrategy: withAggregate(),\n * })\n *\n * const totals = invoices.query()\n *   .where('status', '==', 'paid')\n *   .groupBy('clientId')\n *   .aggregate({ amount: sum('amount'), n: count() })\n *   .run()\n * ```\n */\nexport function withAggregate(): AggregateStrategy {\n  return {\n    aggregate(executeRecords, spec, upstreams) {\n      return new Aggregation(executeRecords, spec as unknown as AggregateSpec, upstreams) as unknown as Aggregation<AggregateResult<typeof spec>>\n    },\n    groupBy(executeRecords, field, upstreams, dictLabelResolver) {\n      return new GroupedQuery(executeRecords, field, upstreams, dictLabelResolver)\n    },\n    async scanAggregate(iter, spec) {\n      const collected: unknown[] = []\n      for await (const record of iter) collected.push(record)\n      return reduceRecords(collected, spec as unknown as AggregateSpec) as unknown as AggregateResult<typeof spec>\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAqCO,SAAS,gBAAmC;AACjD,SAAO;AAAA,IACL,UAAU,gBAAgB,MAAM,WAAW;AACzC,aAAO,IAAI,YAAY,gBAAgB,MAAkC,SAAS;AAAA,IACpF;AAAA,IACA,QAAQ,gBAAgB,OAAO,WAAW,mBAAmB;AAC3D,aAAO,IAAI,aAAa,gBAAgB,OAAO,WAAW,iBAAiB;AAAA,IAC7E;AAAA,IACA,MAAM,cAAc,MAAM,MAAM;AAC9B,YAAM,YAAuB,CAAC;AAC9B,uBAAiB,UAAU,KAAM,WAAU,KAAK,MAAM;AACtD,aAAO,cAAc,WAAW,IAAgC;AAAA,IAClE;AAAA,EACF;AACF;","names":[]}