@noy-db/hub 0.7.1-pre.0 → 0.8.0

package/dist/chunk-4CIQDWRB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/query/relate/join-reduce.ts","../src/kernel/query/reduce/methods.ts","../src/kernel/query/reduce/scan-methods.ts","../src/kernel/query/reduce/install.ts"],"sourcesContent":["/**\n * Reducing over a JOIN ALIAS (#1338).\n *\n * `aggregate()` and `groupBy()` used to refuse any field rooted at a join\n * alias. The refusal's own doc named the real blocker, and it was never \"the\n * legs do not run\" — running them is the easy half. It was that the Via\n * pipeline is LEFT-SCOPED: `Query.aggregate()` calls\n * `this.source.via.wrapReducers(spec)`, which resolves every reducer's field\n * against the LEFT collection's map. For `sum('client.balance')` that map has\n * no entry, so two things silently did not happen — money's exact-BigInt\n * rewrite was skipped (a generic sum over stored scaled-integer strings, which\n * `readNumber` coerces to 0), and `refuseUnqueryableReducers` never fired, so\n * the `queryable: 'none'` gate that would refuse a blob field never applied.\n *\n * This module supplies the missing half as a Via BINDING rather than as a\n * special case threaded through the reduce strategy. A binding composes: the\n * pipeline handed to `GroupedQuery`/`aggregate()` is the left one plus this,\n * so every existing call site keeps its exact behaviour and the alias case\n * arrives through the same `wrapReducers` door as everything else.\n *\n * Two properties make that safe:\n *\n *  - **It delegates, it does not reimplement.** An aliased reducer is handed\n *    to the RIGHT collection's OWN pipeline under its BARE field name — which\n *    is how a pipeline is keyed (that is the whole shape of #1335) — so the\n *    right side's rewrite AND its posture gate apply together, from one call.\n *  - **`covers()` returns false**, so the binding is inert for `postureFor`,\n *    `present`, `decodeResults` and every other phase. It exists for exactly\n *    one hook.\n */\nimport type { NoydbVia } from '../../via/index.js'\nimport { ViaPipeline } from '../../via/pipeline.js'\n\n/**\n * The reducer shape this file needs, declared STRUCTURALLY rather than\n * imported from `with-lookup/reduce/`.\n *\n * Not a style choice: `check-architecture.mjs`'s port-layering guard refuses a\n * NEW static kernel→`with-*` import (its allowlist is a frozen per-file, per-\n * specifier baseline, and adding a row would be the thing the freeze exists to\n * stop). `NoydbVia.wrapReducers` is declared `(spec: unknown) => unknown`\n * precisely so a binding never has to name the service's types, and these\n * three members are all this file touches — every reducer that reaches it was\n * built by the reduce service and keeps every other member intact through the\n * spread below.\n */\ninterface AliasReducer {\n  readonly field?: string\n  init(): unknown\n  step(state: unknown, record: unknown): unknown\n  remove?(state: unknown, record: unknown): unknown\n  finalize(state: unknown): unknown\n}\ntype AliasSpec = Readonly<Record<string, AliasReducer>>\n\n/**\n * Re-aim a reducer at the sub-record under `alias`.\n *\n * The right side's pipeline rewrote the reducer for the BARE field name, so\n * its `step`/`remove` read `credit` off whatever record they are handed. On a\n * joined row that value lives at `row.client.credit`, so the row is unwrapped\n * one level on the way in rather than the field path being rewritten — the\n * rewritten reducer closes over its field name internally, so re-pointing the\n * `.field` property afterwards would change the label and not the read.\n *\n * An unmatched left row carries `null` under the alias; every reducer's read\n * already treats a nullish record as \"no value here\", so it contributes\n * nothing — the same thing a missing left-side field does.\n */\nfunction liftToAlias(alias: string, path: string, inner: AliasReducer): AliasReducer {\n  const under = (record: unknown): unknown =>\n    record === null || typeof record !== 'object' ? undefined : (record as Record<string, unknown>)[alias]\n  return {\n    ...inner,\n    // The dotted path, so anything reading `.field` for a label or a\n    // dependency still sees the field the CALLER named.\n    field: path,\n    init: () => inner.init(),\n    step: (state, record) => inner.step(state, under(record)),\n    ...(inner.remove ? { remove: (state: unknown, record: unknown) => inner.remove!(state, under(record)) } : {}),\n    finalize: (state) => inner.finalize(state),\n  }\n}\n\n/**\n * The binding: rewrite every reducer whose field is rooted at a join alias\n * through that alias's own collection pipeline, and leave everything else\n * exactly as it arrived.\n *\n * A reducer the right side does NOT rewrite (a plain `avg('client.score')`)\n * is returned untouched and keeps reading the dotted path off the joined row,\n * which is already correct — only a REWRITTEN reducer needs lifting, because\n * only a rewritten one has swapped to the bare name.\n */\nfunction joinAliasBinding(aliasVia: ReadonlyMap<string, ViaPipeline>): NoydbVia {\n  return {\n    brand: 'join-alias',\n    posture: { encryptedAtRest: 'envelope', queryable: 'full', exportable: true, forgettable: true },\n    // Claims no field: this binding must never shadow a left-side posture.\n    covers: () => false,\n    wrapReducers: (spec) => {\n      let changed = false\n      const out: Record<string, AliasReducer> = {}\n      for (const [key, reducer] of Object.entries(spec as AliasSpec)) {\n        const field = reducer.field\n        const dot = field === undefined ? -1 : field.indexOf('.')\n        const via = dot > 0 ? aliasVia.get(field!.slice(0, dot)) : undefined\n        if (!via) { out[key] = reducer; continue }\n        const bare = field!.slice(dot + 1)\n        // One call: the right side's rewrite and its `queryable: 'none'`\n        // refusal, both keyed by the bare name it actually declares.\n        const wrapped = via.wrapReducers({ [key]: { ...reducer, field: bare } } as AliasSpec)[key]!\n        if (wrapped === reducer || wrapped.field !== bare) { out[key] = reducer; continue }\n        changed = true\n        out[key] = liftToAlias(field!.slice(0, dot), field!, wrapped)\n      }\n      return changed ? out : spec\n    },\n  }\n}\n\n/**\n * The pipeline `aggregate()` / `groupBy()` should reduce THIS plan with: the\n * source's own, plus the alias binding when the plan can produce an alias.\n *\n * Returns the left pipeline unchanged when there is no alias to serve, so a\n * query with no joins — every query written before #1338 — is handed exactly\n * the object it was handed before.\n */\nexport function reduceViaFor(\n  leftVia: ViaPipeline | undefined,\n  aliasVia: ReadonlyMap<string, ViaPipeline> | undefined,\n): ViaPipeline | undefined {\n  if (aliasVia === undefined || aliasVia.size === 0) return leftVia\n  return ViaPipeline.build([...(leftVia?.bindings ?? []), joinAliasBinding(aliasVia)], leftVia?.taint)\n}\n\n/**\n * The other half, and the reason this one is not merely a missing feature:\n * a binding that REFUSES an aliased reducer instead of rewriting it.\n *\n * It is installed on the path where the legs do NOT run —\n * `groupBy('status').aggregate({ x: sum('client.credit') })`, a group key over\n * a left field with a reducer over an alias. `Query.aggregate()`'s guard never\n * saw that spec (the grouped terminal is `GroupedQuery.aggregate`, one object\n * along the chain), so it reduced `undefined` for every row and returned a\n * confident `0`. Group by the alias — then the legs run and the reducer is\n * rewritten by the branch above — or drop the grouping.\n */\nfunction refuseAliasBinding(aliases: ReadonlySet<string>): NoydbVia {\n  return {\n    brand: 'join-alias-refuse',\n    posture: { encryptedAtRest: 'envelope', queryable: 'full', exportable: true, forgettable: true },\n    covers: () => false,\n    wrapReducers: (spec) => {\n      for (const reducer of Object.values(spec as AliasSpec)) {\n        const field = reducer.field\n        if (field === undefined) continue\n        const head = field.split('.')[0]!\n        if (!aliases.has(head)) continue\n        throw new Error(\n          `Query.groupBy().aggregate(): reducer field \"${field}\" addresses the join alias ` +\n            `\"${head}\", but the GROUP KEY does not — so the join legs are not applied for ` +\n            `this grouping and the reducer would fold undefined into every bucket. ` +\n            `Group by a field on \"${head}\" (then the legs run), or aggregate without ` +\n            `grouping, where an aliased reducer is applied directly.`,\n        )\n      }\n      return spec\n    },\n  }\n}\n\n/**\n * The pipeline for a grouped plan whose GROUP KEY stays on the left: the\n * source's own, plus the refusal above so an aliased reducer is a loud error\n * rather than a confident zero. No aliases in the plan → unchanged.\n */\nexport function refuseAliasReduceVia(\n  leftVia: ViaPipeline | undefined,\n  aliases: ReadonlySet<string>,\n): ViaPipeline | undefined {\n  if (aliases.size === 0) return leftVia\n  return ViaPipeline.build([...(leftVia?.bindings ?? []), refuseAliasBinding(aliases)], leftVia?.taint)\n}\n","/**\n * #1458 — **Reduce**: a fold over a result set.\n *\n * `aggregate` · `groupBy` · `window` · `distinct`\n *\n * Bodies moved out of `kernel/query/builder.ts` unchanged; see\n * `../relate/methods.ts` for why `this.plan` still resolves.\n *\n * ⚠️ This group depends on TWO others, and both edges are real rather than\n * tidyable:\n *   - **Live**, for `incrementalMaintainer` — a live reduction maintains its\n *     state through Live's maintainer (see `../internal/maintenance.ts`);\n *   - **Relate**, for `reduceViaFor` / `refuseAliasReduceVia` — a reducer over\n *     a JOIN ALIAS has to resolve the right side's Via pipeline, and refusing\n *     it correctly is #1338's whole subject.\n * Neither is a layering accident: both are what \"reduce over a joined, live\n * result\" means.\n */\nimport type { DeclaredPredicate, InternalSource, QueryPlan } from '../builder.js'\n// @internal Find helpers. A reduce terminal narrows its record set through the\n// SAME executor the projection terminals use — sharing the functions is what\n// keeps \"which records does this terminal see\" one definition (#1347).\nimport { buildDictLabelResolver, candidateRecords, executeClausePipeline, filterRecords, fnViewDecoder } from '../builder.js'\nimport { readPath } from '../predicate.js'\nimport type { SourceChange } from '../live/incremental.js'\nimport type { QueryField } from '../../types.js'\nimport type { ViaPipeline } from '../../via/pipeline.js'\nimport type { JoinContext, JoinLeg } from '../relate/join.js'\nimport { reduceViaFor, refuseAliasReduceVia } from '../relate/join-reduce.js'\nimport type { DateTruncKey, GroupKey } from './date-trunc.js'\nimport { groupKeyName, isDateTruncKey, projectDateTruncKeys } from './date-trunc.js'\nimport { distinctKeyOf } from '../distinct-key.js'\nimport type { LiveMaintainer, GroupMaintenanceSource } from '../live/incremental.js'\nimport type { ReduceSpec, ReduceResult, ReductionUpstream, Reduction } from '../../../with-lookup/reduce/reduction.js'\nimport type { ReducerBuilder } from '../../../with-lookup/reduce/reducers.js'\nimport { bindDistinctReducers, reducerBuilder } from '../../../with-lookup/reduce/reducers.js'\nimport type { GroupedQuery, GroupedQueryN } from '../../../with-lookup/reduce/groupby.js'\nimport type { ReduceStrategy, WindowSpec, WindowedQuery } from '../../../with-lookup/reduce/strategy.js'\nimport { FieldNotQueryableError } from '../../errors.js'\n\nfunction assertNoJoinAliasField(\n  fields: readonly string[],\n  joins: readonly JoinLeg[],\n  terminal: string,\n): void {\n  if (joins.length === 0) return\n  const aliases = new Set(joins.map(leg => leg.as))\n  for (const field of fields) {\n    const head = field.split('.')[0]!\n    if (!aliases.has(head)) continue\n    throw new Error(\n      `Query.${terminal}(): field \"${field}\" addresses the join alias \"${head}\", but ` +\n        `${terminal}() does not apply join legs — it would silently group every row ` +\n        `under undefined. Joined aggregation is not supported. Either aggregate over ` +\n        `the left collection's own fields, or use .crossJoin(\"${head}\", { as: … }), ` +\n        `whose expansion IS visible to ${terminal}().`,\n    )\n  }\n}\n\n/** @internal — the mixin whose prototype `./index.ts` copies onto `Query`. */\n  /* eslint-disable @typescript-eslint/no-unused-vars -- #1458: the parameter\n     list must match `Query`'s exactly (T, S, Q, M) because `declare module`\n     merges this mixin's `Pick` into it, and TypeScript requires every\n     declaration of an interface to carry identical type parameters. A group\n     whose methods happen to use only `T` still declares all four. */\nexport class ReduceMethods<\n  T,\n  S extends keyof T = never,\n  Q extends keyof T & string = never,\n  M extends keyof T & string = never,\n  /* eslint-enable @typescript-eslint/no-unused-vars */\n> {\n  declare protected readonly source: InternalSource\n  declare protected readonly plan: QueryPlan\n  declare protected readonly joinContext: JoinContext | undefined\n  declare protected readonly reduceStrategy: ReduceStrategy\n  declare protected readonly predicates: ReadonlyMap<string, DeclaredPredicate> | undefined\n  declare protected matchedRecords: (terminal: string, forceJoins?: boolean) => readonly unknown[]\n  declare protected decodeVia: (records: readonly unknown[], locale?: string) => unknown[]\n  declare protected aliasVia: () => ReadonlyMap<string, ViaPipeline> | undefined\n  declare protected incrementalMaintainer: (mode: 'rows' | 'records') => LiveMaintainer | undefined\n  declare protected groupMaintenance: (derived: readonly DateTruncKey[]) => GroupMaintenanceSource | undefined\n  declare toArray: (opts?: { locale?: string }) => T[]\n\n  /**\n   * The right-side change streams a joined query has to merge (#1338), deduped\n   * by target the way `live()` does — a chain joining the same collection\n   * twice must not double-fire. Extracted so a joined REDUCTION and a joined\n   * live query cannot disagree on what \"the sources of this result\" means.\n   */\n  private rightSideUpstreams(): ReductionUpstream[] {\n    const ctx = this.joinContext\n    if (!ctx) return []\n    const out: ReductionUpstream[] = []\n    const seen = new Set<string>()\n    for (const leg of this.plan.joins) {\n      if (seen.has(leg.target)) continue\n      seen.add(leg.target)\n      const right = ctx.resolveSource(leg.target)\n      if (!right?.subscribe) continue\n      const subscribe = right.subscribe.bind(right)\n      out.push({ subscribe: (cb: () => void) => subscribe(cb) })\n    }\n    return out\n  }\n\n  /**\n   * Every alias this plan can produce, pipeline or not (#1338).\n   *\n   * `aliasVia()` above holds only the aliases whose collection compiles a Via\n   * pipeline; refusal has to know about ALL of them, or an aliased reducer\n   * over a plain right-side collection stays silent.\n   */\n  private aliasNames(): ReadonlySet<string> {\n    const out = new Set<string>()\n    for (const clause of this.plan.clauses) {\n      if (clause.type !== 'crossJoin') continue\n      out.add(clause.as)\n      if (clause.leftAs !== undefined) out.add(clause.leftAs)\n    }\n    for (const leg of this.plan.joins) out.add(leg.as)\n    return out\n  }\n\n  /** Is `field` rooted at an alias this plan produces? */\n\n  private addressesAlias(field: string, aliases: ReadonlySet<string>): boolean {\n    const dot = field.indexOf('.')\n    return dot > 0 && aliases.has(field.slice(0, dot))\n  }\n\n  /**\n   * The distinct values of `field` across the match set (#1347) — the\n   * declarative form of `new Set(q.toArray().map(r => r[field]))`, which is\n   * what consumers write today and which is wrong in two ways this is not.\n   *\n   * **Distinctness is decided on the canonical index key, not on the value\n   * you get back.** For a Via-covered field that is the difference between a\n   * right answer and a plausible one: money stores a scaled integer, and a\n   * row written before the field was declared can spell it non-canonically\n   * (`'0100'` for `'100'`). Deduping the stored strings reports two values\n   * where there is one; deduping the FORMATTED strings makes the answer\n   * depend on a locale this layer does not have (`'10.00'` vs `'10,00'`).\n   * See `distinct-key.ts`. The values RETURNED are the decoded ones, so they\n   * match what `toArray()` hands back for the same field.\n   *\n   * **Nullish values are excluded** — `null`/`undefined`/missing is the\n   * absence of a value, not a distinct one. That is also the only choice\n   * under which the index-backed and scanned paths can agree, since the hash\n   * index does not hold nullish keys; see `distinctKeyOf`.\n   *\n   * Same match set as `count()`: where/filter apply, orderBy/limit/offset do\n   * not. Values come back in first-encountered order.\n   *\n   * ⭐ INDEX-BACKED when the field carries a hash index AND the plan narrows\n   * nothing — the buckets ARE the distinct key set, so the answer costs\n   * O(distinct values) instead of O(records) and never decrypts a snapshot.\n   * The guard is deliberately all-or-nothing: with a where clause the whole\n   * collection's buckets are not the answer, and intersecting a candidate id\n   * set with every bucket would cost more than the scan it replaced.\n   *\n   * ⛔ THE RETURN TYPE IS `(T & Record<F, unknown>)[F][]`, NOT\n   * `F extends keyof T ? T[F][] : unknown[]` — and it must stay that way. The\n   * conditional form reads better and type-checks at every call site, but a\n   * DEFERRED conditional over `T` makes TypeScript give up relating\n   * `Query<T>` to `Query<unknown>`, which makes `Collection<T>` invariant in\n   * `T`, which breaks `vault.ts`'s `Map<string, Collection<unknown>>` cache\n   * with four errors that name neither this method nor this file. The\n   * intersection form resolves to the same thing (`T[F]` for a literal key,\n   * `unknown` for a `string`-typed one) and stays covariant.\n   */\n  distinct<F extends QueryField<T, S>>(field: F): (T & Record<F, unknown>)[F][] {\n    const name = field as string\n    assertNoJoinAliasField([name], this.plan.joins, 'distinct')\n    const via = this.source.via\n    // Same posture gate `.where()` / `.orderBy()` apply: a `queryable: 'none'`\n    // field (a blob handle) must not have its value set enumerated either.\n    if (via?.postureFor(name)?.queryable === 'none') throw new FieldNotQueryableError(name)\n    const decode = via?.hasResultDecode ? (r: unknown) => via.decodeResults(r) : (r: unknown) => r\n\n    const indexes =\n      this.plan.clauses.length === 0 && this.plan.joins.length === 0\n        ? this.source.getIndexes?.()\n        : undefined\n    if (indexes && this.source.lookupById) {\n      const lookupById = (id: string): unknown => this.source.lookupById?.(id)\n      const reps = indexes.bucketRepresentatives(name)\n      if (reps) {\n        const fromIndex: unknown[] = []\n        for (const id of reps) {\n          const record = lookupById(id)\n          if (record === undefined) continue\n          fromIndex.push(readPath(decode(record), name))\n        }\n        return fromIndex as (T & Record<F, unknown>)[F][]\n      }\n    }\n\n    const seen = new Set<string>()\n    const out: unknown[] = []\n    for (const record of this.matchedRecords('distinct')) {\n      const key = distinctKeyOf(name, readPath(record, name), via)\n      if (key === undefined || seen.has(key)) continue\n      seen.add(key)\n      out.push(readPath(decode(record), name))\n    }\n    return out as (T & Record<F, unknown>)[F][]\n  }\n\n  /**\n   * Reduce the matching records through a named set of reducers.\n   * the aggregation terminal.\n   *\n   * ```ts\n   * const { total, n, avgAmount } = invoices.query()\n   *   .where('status', '==', 'open')\n   *   .aggregate({\n   *     total:     sum('amount'),\n   *     n:         count(),\n   *     avgAmount: avg('amount'),\n   *   })\n   *   .run()\n   * ```\n   *\n   * Returns an `Reduction<R>` wrapper with two terminals:\n   *   - `.run(): R` — synchronous one-shot reduction\n   *   - `.live(): LiveReduction<R>` — reactive primitive that\n   *     re-runs the reduction whenever the source notifies of a\n   *     change. Always call `live.stop()` when finished.\n   *\n   * The reducer spec is bound here once and reused by both\n   * terminals — this is why `.aggregate()` returns a wrapper instead\n   * of being a direct terminal. Consumers who only need the static\n   * value read `.run()`; consumers wiring a reactive UI read\n   * `.live()`.\n   *\n   * Joins are NOT applied by default — the same logic as `.count()`. A leg is\n   * projection-only, so running one just to throw the alias away would be\n   * wasteful. ⭐ **The exception is a reducer that ADDRESSES an alias**\n   * (#1338): then the joined relation IS what is being reduced, so the legs\n   * run and the reducer is rewritten by the right collection's own Via\n   * pipeline — money stays exact, and the right side's `queryable: 'none'`\n   * posture refuses a field it would refuse locally. A live joined\n   * aggregation also merges every right-side change stream, so it does not\n   * quietly stop updating when the right side moves.\n   *\n   * Every reducer factory accepts an optional `{ seed }` parameter\n   * that is plumbed through the protocol but unused by the\n   * executor — that's  constraint #2. When partition-aware\n   * aggregation lands, the seed will carry running state across\n   * partition boundaries without an API break.\n   *\n   * KNOWN GAP (sealed fields, bare-spec form): `where`/`orderBy`/`groupBy`\n   * refuse a `sensitive` field at compile time, but a reducer over a sensitive\n   * field in the BARE-SPEC form (e.g. `aggregate({ x: sum('ssn') })`) is NOT\n   * refused — the reducer factories (`sum`/`min`/`max`/…) are standalone\n   * `(field: string)` functions with no collection-type context. This form is\n   * preserved as-is for backward compatibility.\n   *\n   * The BUILDER form closes this gap: `aggregate(b => ({ x: b.sum('field') }))`\n   * types the builder's field parameter as `QueryField<T, S>`, refusing any\n   * `sensitive` field at compile time. Use the builder form for new code that\n   * aggregates over a collection with sensitive fields.\n   *\n   */\n  aggregate<Spec extends ReduceSpec>(spec: Spec): Reduction<ReduceResult<Spec>>\n  aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Reduction<ReduceResult<Spec>>\n  aggregate<Spec extends ReduceSpec>(\n    specOrBuild: Spec | ((b: ReducerBuilder<T, S, M>) => Spec),\n  ): Reduction<ReduceResult<Spec>> {\n    let spec = typeof specOrBuild === 'function'\n      ? (specOrBuild as (b: ReducerBuilder<T, S, M>) => Spec)((reducerBuilder as unknown) as ReducerBuilder<T, S, M>)\n      : specOrBuild\n    // #1338 — a reducer over a joined alias used to be refused here. It now\n    // routes: the legs run (so the reducer sees the joined relation) and the\n    // spec is wrapped by a pipeline that delegates each aliased field to the\n    // RIGHT collection's own — which carries money's exact-BigInt rewrite and\n    // the `queryable: 'none'` posture gate together. Reducers without a field\n    // (e.g. `count()`) address nothing and are unaffected.\n    const aliases = this.aliasNames()\n    const aliasedReducer =\n      this.plan.joins.length > 0 &&\n      Object.values(spec).some(r => {\n        const f = (r as { field?: unknown }).field\n        return typeof f === 'string' && this.addressesAlias(f, aliases)\n      })\n    // Rewrite sum/min/max over Via-covered fields (e.g. money) into exact\n    // BigInt reducers before the strategy runs (covers static run() and\n    // live/MV paths).\n    spec = (aliasedReducer ? reduceViaFor(this.source.via, this.aliasVia()) : this.source.via)?.wrapReducers(spec) ?? spec\n    // #1347 — `countDistinct` needs the SAME canonicalizer the hash index\n    // buckets by, and only the source knows it. Bound here, beside the\n    // money rewrite, so both spec-wrapping seams stay in one place.\n    spec = bindDistinctReducers(spec, this.source.via)\n    // Closure over the current query. Produces the record set that\n    // the aggregation reduces — same pipeline as `count()`, skipping\n    // limit/offset because aggregation is over the full match set,\n    // not a paginated slice. (A paginated aggregation would be a\n    // different operation; see docs for rationale.)\n    const source = this.source\n    const clauses = this.plan.clauses\n    const joinCtx = this.joinContext\n    const hasCrossJoins = clauses.some(c => c.type === 'crossJoin')\n    const fullScan = aliasedReducer\n      // The reduced relation IS the joined one — same pipeline `count()` uses,\n      // with the legs forced on (#1338).\n      ? (): readonly unknown[] => this.matchedRecords('aggregate', true)\n      : (): readonly unknown[] => {\n        if (hasCrossJoins) {\n          if (!joinCtx) throw new Error('Query.aggregate(): crossJoin requires a join context')\n          return executeClausePipeline(source, clauses, joinCtx)\n        }\n        const { candidates, remainingClauses } = candidateRecords(source, clauses)\n        return remainingClauses.length === 0\n          ? candidates\n          : filterRecords(candidates, remainingClauses, fnViewDecoder(source))\n      }\n\n    // #1341 — when the plan admits it, the match set is MAINTAINED across\n    // change events instead of re-scanned, so a live reduction folds over an\n    // incrementally-patched array. The reducers themselves still run a full\n    // fold: the array they see is byte-for-byte the one a re-scan would\n    // produce (same records, same candidate order), so an incremental result\n    // is not merely close to a re-run's — it is the identical computation.\n    const maintainer = this.incrementalMaintainer('records')\n    const executeRecords = maintainer ? (): readonly unknown[] => maintainer.rows() : fullScan\n\n    // Upstream for live mode. The left source always subscribes; a joined\n    // aggregation ALSO merges every right-side change stream (#1338) — the\n    // refusal's own doc named a live joined aggregate that silently stops\n    // updating as half the work, and it is this half.\n    const upstreams: ReductionUpstream[] = []\n    if (aliasedReducer) upstreams.push(...this.rightSideUpstreams())\n    if (source.subscribe) {\n      const subscribe = source.subscribe.bind(source)\n      upstreams.push(\n        maintainer\n          ? {\n              // The maintainer folds the delta in BEFORE the reduction reads,\n              // which is why it is wrapped here rather than subscribed\n              // separately — emitter callback order would otherwise decide\n              // whether the reduction saw the new record.\n              subscribe: (cb: () => void) => {\n                maintainer.attach()\n                const unsubscribe = subscribe(change => {\n                  // A predicate that throws must not escape into the emitter —\n                  // the maintainer drops its state and the reduction's own\n                  // re-run raises the same error where it can be caught.\n                  try {\n                    maintainer.apply(change)\n                  } catch {\n                    maintainer.invalidate()\n                  }\n                  cb()\n                })\n                // Detach on teardown: the Reduction survives its LiveReduction\n                // (`.run()` reuses the same closure), and a maintainer with no\n                // subscription feeding it would go quietly out of date.\n                return () => {\n                  maintainer.detach()\n                  unsubscribe()\n                }\n              },\n            }\n          : { subscribe: (cb: () => void) => subscribe(cb) },\n      )\n    }\n\n    // #1414 — the gate travels INTO the reduction rather than wrapping it.\n    // `Reduction.run()` is the synchronous terminal, and `await …aggregate(\n    // spec).run()` is what an async guard's Σ-over-siblings invariant writes;\n    // gating the builder call instead would break that awaited form.\n    return this.reduceStrategy.aggregate<Spec>(executeRecords, spec, upstreams, this.source.hydration)\n  }\n\n  /**\n   * Partition matching records into buckets keyed by a field, then\n   * terminate with `.aggregate(spec)` to compute per-bucket\n   * reducers..\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   * Result rows carry the group key value under the grouping field\n   * name plus every reducer output from the spec. Buckets are\n   * emitted in first-seen order — consumers who want a specific\n   * ordering should `.sort()` downstream.\n   *\n   * **Cardinality caps:** a one-shot warning fires at 10_000\n   * distinct groups; `GroupCardinalityError` throws at 100_000.\n   * Grouping on a high-uniqueness field like `id` or `createdAt` is\n   * almost always a query mistake — the error message names the\n   * field and observed cardinality and suggests narrowing with\n   * `.where()` first.\n   *\n   * **Null / undefined keys:** records with a missing or explicitly\n   * `null` group field get their own buckets. `Map`-based\n   * partitioning distinguishes `undefined` from `null`, so the two\n   * cases do NOT merge. Consumers who want them merged should\n   * coalesce upstream with `.filter()`.\n   *\n   * **Joins are not applied unless the GROUP KEY addresses an alias** (#1338).\n   * For a left-side key the old rationale still holds — a leg is\n   * projection-only, so running one inside a grouping pipeline would be\n   * wasteful and could trigger `DanglingReferenceError` in strict mode for a\n   * call whose intent is purely to bucket-and-reduce. For an aliased key\n   * (`groupBy('client.region')`, the accounting-report shape) the legs run and\n   * the buckets are the joined relation's: the key is stamped under its DOTTED\n   * path (`row['client.region']`), and a left row whose right side is absent\n   * reads `undefined` and lands in the undefined bucket — the same bucket a\n   * missing left-side key gets, and still distinct from an explicit `null`.\n   *\n   * ⚠️ The decision is taken from the KEY, because the reducer spec arrives a\n   * call later. A reducer over an alias under a LEFT key is therefore REFUSED\n   * rather than folded as `undefined` — group by the alias, or aggregate\n   * without grouping.\n   *\n   * **Filter clauses (`.filter(fn)`):** grouped queries still\n   * support filter clauses in the underlying plan — they run in\n   * the same candidate/filter pipeline that `.aggregate()` uses.\n   * The performance caveat is the same: filter clauses cost O(N)\n   * per record and can't be index-accelerated.\n   */\n  // The `field` param is `QueryField<T, S>` so a sealed (`sensitive`) field is\n  // refused — grouping BY a sensitive field leaks its value distribution as\n  // group-key labels. With `S = never` this is exactly `string` (zero churn).\n\n  groupBy<F extends QueryField<T, S>>(field: F): GroupedQuery<T, F, S, M>\n  groupBy<F extends readonly [QueryField<T, S>, QueryField<T, S>, ...QueryField<T, S>[]]>(\n    ...fields: F\n  ): GroupedQueryN<T, F, S, M>\n  // Derived calendar keys (#1350). Listed last so the two field-name overloads\n  // above still win for plain string arguments — a `DateTruncKey` is an object\n  // and matches neither, so nothing existing re-resolves onto these.\n  groupBy(key: DateTruncKey): GroupedQuery<T, string, S, M>\n  // The string members stay `QueryField<T, S>`, so the sealed-field refusal\n  // still applies to every plain key in a mixed grouping.\n  groupBy(\n    ...keys: readonly [\n      QueryField<T, S> | DateTruncKey,\n      QueryField<T, S> | DateTruncKey,\n      ...(QueryField<T, S> | DateTruncKey)[],\n    ]\n  ): GroupedQueryN<T, readonly string[], S, M>\n  groupBy(...keys: readonly GroupKey[]): GroupedQuery<T, string, S, M> | GroupedQueryN<T, readonly string[], S, M> {\n    if (keys.length === 0) {\n      throw new Error('.groupBy() requires at least one field')\n    }\n    // A derived key is bucketed into an ordinary row field before the grouping\n    // pipeline runs, so everything downstream — cardinality caps, null/undefined\n    // bucket semantics, live re-grouping — keeps working unchanged.\n    const derived = keys.filter(isDateTruncKey)\n    const fields: readonly string[] = keys.map(groupKeyName)\n    // #1338 — a group key addressing an alias used to be refused. It now\n    // decides the shape of the whole grouped pipeline: the legs run, and the\n    // reducers are wrapped through the right side's pipeline.\n    //\n    // ⚠️ The decision is made HERE, from the group KEY alone, because the\n    // reducer spec does not exist yet — it arrives one call later, at\n    // `.aggregate()`. That is exactly why the left-key case installs a\n    // REFUSING binding rather than nothing: a reducer over an alias under a\n    // left-side key would otherwise fold undefined into every bucket, and the\n    // grouped terminal is not the one `Query.aggregate()`'s guard sees.\n    const aliases = this.aliasNames()\n    const keyIsAliased = this.plan.joins.length > 0 && fields.some(f => this.addressesAlias(f, aliases))\n    // Same record-producing closure as .aggregate() — grouped and\n    // non-grouped aggregations execute over the same candidate set.\n    // We inline the closure here instead of sharing a helper so the\n    // builder stays allocation-friendly for the hot path.\n    const source = this.source\n    const clauses = this.plan.clauses\n    const joinCtx = this.joinContext\n    const hasCrossJoins = clauses.some(c => c.type === 'crossJoin')\n    const executeRecords = keyIsAliased\n      ? (): readonly unknown[] => this.matchedRecords('groupBy', true)\n      : (): readonly unknown[] => {\n        if (hasCrossJoins) {\n          if (!joinCtx) throw new Error('Query.groupBy(): crossJoin requires a join context')\n          return executeClausePipeline(source, clauses, joinCtx)\n        }\n        const { candidates, remainingClauses } = candidateRecords(source, clauses)\n        return remainingClauses.length === 0\n          ? candidates\n          : filterRecords(candidates, remainingClauses, fnViewDecoder(source))\n      }\n    const executeGroupRecords = derived.length === 0\n      ? executeRecords\n      : (): readonly unknown[] => projectDateTruncKeys(executeRecords(), derived)\n\n    // #1341 (grouped half) — the upstream passes the DELTA through, not just a\n    // \"something changed\" ping, so `GroupedReduction.live()` can patch the one\n    // or two buckets a change touches instead of re-grouping everything. A cb\n    // that ignores the argument (every pre-#1341 caller) is unaffected.\n    const upstreams: ReductionUpstream[] = []\n    if (source.subscribe) {\n      const subscribe = source.subscribe.bind(source)\n      upstreams.push({ subscribe: (cb: (change?: SourceChange) => void) => subscribe(cb) })\n    }\n    if (keyIsAliased) upstreams.push(...this.rightSideUpstreams())\n    // Withheld for a plan the whitelist refuses, and for an aliased key (which\n    // implies joins, which the whitelist refuses anyway) — `.live()` then\n    // re-runs the whole grouping, exactly as it did before.\n    const maintenance = keyIsAliased ? undefined : this.groupMaintenance(derived)\n\n    // The pipeline the reducers are wrapped with: the right side's rewrite\n    // when the legs run, the refusal when they do not (#1338).\n    const reduceVia = keyIsAliased\n      ? reduceViaFor(this.source.via, this.aliasVia())\n      : refuseAliasReduceVia(this.source.via, aliases)\n\n    // Dict-label resolution is single-field only — the <field>Label\n    // projection has no meaningful shape for composite keys. A derived\n    // calendar key is never a dictKey, so it skips the lookup entirely.\n    if (fields.length === 1) {\n      const field = fields[0]!\n      const dictLabelResolver = derived.length > 0\n        ? undefined\n        : buildDictLabelResolver(this.joinContext, field)\n      return this.reduceStrategy.groupBy<T, string, S, M>(\n        executeGroupRecords,\n        field,\n        upstreams,\n        dictLabelResolver,\n        reduceVia,\n        maintenance,\n      )\n    }\n    return this.reduceStrategy.groupByN<T, readonly string[], S, M>(\n      executeGroupRecords,\n      fields,\n      upstreams,\n      reduceVia,\n      maintenance,\n    )\n  }\n\n  /**\n   * SQL window functions over the query's result rows (#1349) — terminate with\n   * `.select(spec)`.\n   *\n   * ```ts\n   * invoices.query()\n   *   .where('status', '==', 'open')\n   *   .window({ partitionBy: 'clientId', orderBy: 'date' })\n   *   .select({ balance: runningSum('amount'), prev: lag('amount', 1), n: rowNumber() })\n   *   .run()\n   * ```\n   *\n   * ⭐ Distinguished from `.groupBy()` by ARITY, not by capability: grouping\n   * emits one row per bucket and drops the source rows; a window keeps EVERY\n   * row and attaches per-row values computed over its partition.\n   *\n   * **The record set is `toArray()`'s** — the full pipeline, including joins,\n   * `orderBy`, `offset`/`limit` and the Via decode. That differs deliberately\n   * from `.groupBy()`, which reads the candidate/filter pipeline only: a\n   * window returns ROWS, so the query's own ordering and paging are exactly\n   * what decides which rows there are and how they are presented. `orderBy`\n   * inside the window decides only how a partition is WALKED.\n   *\n   * **Frame:** `rows unbounded preceding → current row`, and only that in v1.\n   *\n   * `partitionBy` / `orderBy` accept a `dateTrunc()` key (#1350) alongside\n   * plain field names; the derived bucket is used for partitioning and is not\n   * stamped on the output row. A sealed (`sensitive`) field is refused at\n   * compile time, same as `.groupBy()`.\n   *\n   * ⛔ **Not an `explain()` node.** `explain()` is a terminal on `Query`;\n   * `.window()` leaves `Query` for `WindowedQuery`, so there is nothing past\n   * here to add a node to — the same reason #1336's post-group ops are absent.\n   */\n  window(spec: WindowSpec<QueryField<T, S>>): WindowedQuery<T> {\n    const upstreams: ReductionUpstream[] = []\n    if (this.source.subscribe) {\n      const subscribe = this.source.subscribe.bind(this.source)\n      upstreams.push({ subscribe: (cb: () => void) => subscribe(cb) })\n    }\n    return this.reduceStrategy.window<T>(\n      () => this.toArray() as readonly unknown[],\n      spec as WindowSpec,\n      upstreams,\n      this.source.via,\n    )\n  }\n}\n\n/** The public Reduce surface — merged into `Query` by `./index.ts`. */\nexport type ReduceSurface<\n  T,\n  S extends keyof T = never,\n  Q extends keyof T & string = never,\n  M extends keyof T & string = never,\n> = Pick<ReduceMethods<T, S, Q, M>, 'aggregate' | 'groupBy' | 'window' | 'distinct'>\n\n","/**\n * #1458 — the **Reduce** half of `ScanBuilder`.\n *\n * `aggregate` · `groupBy` · the grouped-scan handle they return.\n *\n * See `../relate/scan-methods.ts` for why `ScanBuilder` is split at all.\n *\n * ⭐ **The streaming memory property travels with the code.**\n * `scan().aggregate()` is O(reducers), not O(records) — it steps every reducer\n * per record and never collects the stream — and `groupBy().aggregate()` is\n * O(groups). That is a code-level invariant visible in the bodies below, so\n * moving them wholesale is what preserves it; re-expressing them over the\n * eager reducers would have quietly turned an unbounded scan into an array.\n */\nimport type { MultiReduceResult, ScanPageProvider } from '../scan-builder.js'\nimport type { QueryField } from '../../types.js'\nimport type { Clause } from '../predicate.js'\nimport { readPath } from '../predicate.js'\nimport type { ViaPipeline } from '../../via/pipeline.js'\nimport type { JoinContext, JoinLeg } from '../relate/join.js'\nimport type { ReducerBuilder } from '../../../with-lookup/reduce/reducers.js'\nimport { bindDistinctReducers, reducerBuilder } from '../../../with-lookup/reduce/reducers.js'\nimport type { ReduceSpec, ReduceResult } from '../../../with-lookup/reduce/reduction.js'\nimport type { DateTruncKey } from './date-trunc.js'\nimport { groupKeyName, isDateTruncKey, projectDateTruncKeys } from './date-trunc.js'\nimport { GroupCardinalityError } from '../../errors.js'\n\n/** @internal — the mixin whose prototype `./index.ts` copies onto `ScanBuilder`. */\nexport class ScanReduceMethods<T, S extends keyof T = never, M extends keyof T & string = never> {\n  declare protected readonly pageProvider: ScanPageProvider<T>\n  declare protected readonly pageSize: number\n  declare protected readonly clauses: readonly Clause[]\n  declare protected readonly joins: readonly JoinLeg[]\n  declare protected readonly joinContext: JoinContext | undefined\n  declare protected readonly via: ViaPipeline | undefined\n  declare protected decodeVia: (record: T) => T\n  declare protected recordMatches: (record: T, clauses?: readonly Clause[]) => boolean\n  declare [Symbol.asyncIterator]: () => AsyncIterator<T>\n\n  async aggregate<const Specs extends readonly ReduceSpec[]>(specs: Specs): Promise<MultiReduceResult<Specs>>\n  async aggregate<Spec extends ReduceSpec>(spec: Spec): Promise<ReduceResult<Spec>>\n  async aggregate<Spec extends ReduceSpec>(build: (b: ReducerBuilder<T, S, M>) => Spec): Promise<ReduceResult<Spec>>\n  async aggregate<Spec extends ReduceSpec>(\n    specOrBuild: Spec | readonly ReduceSpec[] | ((b: ReducerBuilder<T, S, M>) => Spec),\n  ): Promise<ReduceResult<Spec> | unknown[]> {\n    // #1340 — the multi-spec form. N independent specs, ONE pass: the states\n    // for every spec are stepped from the same yielded record, so the page\n    // provider is walked exactly once no matter how many specs are passed.\n    // (Calling `.aggregate(specA)` then `.aggregate(specB)` costs two full\n    // scans — the immutable-builder docs above say so, and this is the fix.)\n    if (Array.isArray(specOrBuild)) return this.aggregateMany(specOrBuild as readonly ReduceSpec[])\n    // Opt-in builder form `aggregate(b => spec)`: `b`'s field args are\n    // `QueryField<T, S>`, refusing sensitive fields (the standalone-spec form\n    // stays unrefused for back-compat), and `sum`/`min`/`max` over a declared\n    // `moneyFields` (`M`) member return a `MoneyString`. Mirrors `Query.aggregate`.\n    const spec: Spec = typeof specOrBuild === 'function'\n      ? (specOrBuild as (b: ReducerBuilder<T, S, M>) => Spec)(reducerBuilder as unknown as ReducerBuilder<T, S, M>)\n      // `Array.isArray` above does not narrow a READONLY array out of the\n      // union, so the array arm is already returned and this cast is the\n      // remainder — a plain spec.\n      : (specOrBuild as Spec)\n    this.via?.refuseUnqueryableReducers(spec)\n    const keys = Object.keys(spec)\n    // Per-reducer state. Exactly |keys| entries, never grows with\n    // the record count — that's the O(reducers) memory guarantee.\n    const state: Record<string, unknown> = {}\n    for (const key of keys) {\n      state[key] = spec[key]!.init()\n    }\n\n    // Record-by-record streaming step. `for await (… of this)`\n    // invokes the Symbol.asyncIterator above, which honors the\n    // clause list, so filtered-out records never reach the step\n    // loop — they're dropped at the iterator boundary.\n    for await (const record of this) {\n      for (const key of keys) {\n        state[key] = spec[key]!.step(state[key], record)\n      }\n    }\n\n    const result: Record<string, unknown> = {}\n    for (const key of keys) {\n      result[key] = spec[key]!.finalize(state[key])\n    }\n    return result as ReduceResult<Spec>\n  }\n\n  /**\n   * The multi-spec `.aggregate([specA, specB, …])` executor (#1340).\n   *\n   * One iteration of the scan, `Σ|spec|` reducer states — memory stays\n   * O(reducers) exactly as the single-spec terminal's does, with the sum taken\n   * across specs instead of within one. Every spec's state is stepped from the\n   * SAME yielded record, so the page provider is read once per page.\n   *\n   * Semantics per spec are identical to the single-spec form, deliberately:\n   * the posture gate is `refuseUnqueryableReducers` (metadata only), NOT the\n   * full `wrapReducers` — so `aggregate([a, b])` returns exactly what\n   * `aggregate(a)` and `aggregate(b)` return, and the array form is a pure\n   * cost optimisation with no behavioural delta to reason about. (The grouped\n   * scan path DOES wrap — it has to agree with the eager grouped path, which\n   * wraps. See `scan-groupby.ts`.)\n   */\n  private async aggregateMany(specs: readonly ReduceSpec[]): Promise<unknown[]> {\n    for (const spec of specs) this.via?.refuseUnqueryableReducers(spec)\n    const keysPerSpec = specs.map((spec) => Object.keys(spec))\n    const states: Record<string, unknown>[] = specs.map((spec, i) => {\n      const state: Record<string, unknown> = {}\n      for (const key of keysPerSpec[i]!) state[key] = spec[key]!.init()\n      return state\n    })\n\n    for await (const record of this) {\n      for (let i = 0; i < specs.length; i++) {\n        const spec = specs[i]!\n        const state = states[i]!\n        for (const key of keysPerSpec[i]!) state[key] = spec[key]!.step(state[key], record)\n      }\n    }\n\n    return specs.map((spec, i) => {\n      const result: Record<string, unknown> = {}\n      for (const key of keysPerSpec[i]!) result[key] = spec[key]!.finalize(states[i]![key])\n      return result\n    })\n  }\n\n  /**\n   * Group the scan stream and reduce each group — `#1340`.\n   *\n   * ```ts\n   * const byClient = await invoices.scan()\n   *   .where('status', '==', 'open')\n   *   .groupBy('clientId', { maxGroups: 5_000 })\n   *   .aggregate({ total: sum('amount'), n: count() })\n   * ```\n   *\n   * ⚠️ **This is the one scan terminal whose memory is NOT O(pageSize).** It\n   * holds one reducer state per group, which is why the budget is explicit:\n   * `maxGroups` defaults to the eager path's 100_000-group ceiling and is\n   * REFUSED — never truncated — the moment a scan would exceed it. Price the\n   * budget before raising it: an exact `median`/`percentile`, a `mode` or a\n   * `countDistinct` holds O(values) per group, so an unbounded scan wants\n   * `{ approx: true }` on the quantiles. Full rationale in `scan-groupby.ts`.\n   *\n   * The key may be a field name or a `dateTrunc()` derived calendar key (the\n   * monthly-rollup shape); grouping BY a `sensitive` field is refused at\n   * compile time, same as `Query.groupBy()`.\n   */\n  groupBy<F extends QueryField<T, S>>(field: F, opts?: { maxGroups?: number }): ScanGroupedScan<T, F, S, M>\n  groupBy(key: DateTruncKey, opts?: { maxGroups?: number }): ScanGroupedScan<T, string, S, M>\n  groupBy(key: QueryField<T, S> | DateTruncKey, opts?: { maxGroups?: number }): ScanGroupedScan<T, string, S, M> {\n    return new ScanGroupedScan<T, string, S, M>(\n      this,\n      key as string | DateTruncKey,\n      opts?.maxGroups ?? SCAN_GROUPBY_DEFAULT_MAX_GROUPS,\n      this.via,\n    )\n  }\n}\n\n/** The public Reduce surface of `ScanBuilder` — merged by `./index.ts`. */\nexport type ScanReduceSurface<\n  T,\n  S extends keyof T = never,\n  M extends keyof T & string = never,\n> = Pick<ScanReduceMethods<T, S, M>, 'aggregate' | 'groupBy'>\n\n/**\n * Default group ceiling — the same constant the eager `.groupBy()` enforces.\n * Duplicated as a literal rather than imported from\n * `with-lookup/reduce/groupby.ts` on purpose: that module carries the eager\n * `groupAndReduce` + `GroupedReduction` classes, and the always-on kernel must\n * not pull them in to read one number. The pairing is asserted by a test.\n */\nexport const SCAN_GROUPBY_DEFAULT_MAX_GROUPS = 100_000\n\n/**\n * Single-field spelling of `canonicalGroupKey` (`with-lookup/reduce/canonical-key.ts`).\n *\n * ⛔ Inlined, not imported, and not by preference: `check-architecture`'s\n * `port-layering` rule grandfathers this file for exactly two\n * `with-lookup/reduce/*` specifiers (`reducers.js`, `reduction.js`), and\n * `canonical-key.js` is not one of them — a new one may not be added\n * silently. The eager helper sorts its field list and serialises\n * each value — with exactly one field, that reduces to this line, including\n * the part that matters: `undefined` gets a sentinel so a MISSING key and an\n * explicit `null` land in different buckets, as they do under\n * `Query.groupBy()`. The agreement is held by test, not by comment\n * (`query-scan-groupby.test.ts` — null/undefined bucketing, and full equality\n * with the eager path).\n */\nfunction scanGroupKey(field: string, value: unknown): string {\n  return `${field}=${value === undefined ? 'undefined' : JSON.stringify(value)}`\n}\n\n/** Group-key result-row shape: the key under its own name, plus the reducers. */\n\nexport type ScanGroupedRow<F extends string, R> = { [K in F]: unknown } & R\n\n/**\n * Chainable wrapper returned by `ScanBuilder.groupBy()`. The only operation on\n * it is `.aggregate()` — same minimal shape as `GroupedQuery`.\n */\nexport class ScanGroupedScan<\n  T,\n  F extends string,\n  S extends keyof T = never,\n  M extends keyof T & string = never,\n> {\n  constructor(\n    private readonly stream: AsyncIterable<T>,\n    private readonly key: string | DateTruncKey,\n    private readonly maxGroups: number,\n    private readonly via: ViaPipeline | undefined,\n  ) {\n    if (!Number.isInteger(maxGroups) || maxGroups < 1) {\n      throw new Error(\n        `scan().groupBy(): { maxGroups: ${String(maxGroups)} } must be a positive integer — ` +\n          `it is the declared ceiling on how many reducer states the grouped scan may hold.`,\n      )\n    }\n  }\n\n  /**\n   * Fold the scan into one row per group. Resolves to `R[]`, ordered by each\n   * group's FIRST-SEEN position in the stream (`Map` insertion order), which\n   * is the same ordering rule the eager path documents.\n   *\n   * ```ts\n   * const byMonth = await invoices.scan()\n   *   .where('status', '==', 'paid')\n   *   .groupBy(dateTrunc('closedAt', 'month', { as: 'month', timeZone: 'UTC' }), { maxGroups: 240 })\n   *   .aggregate({ total: sum('amount'), n: count() })\n   * ```\n   */\n  async aggregate<Spec extends ReduceSpec>(spec: Spec): Promise<ScanGroupedRow<F, ReduceResult<Spec>>[]>\n  async aggregate<Spec extends ReduceSpec>(\n    build: (b: ReducerBuilder<T, S, M>) => Spec,\n  ): Promise<ScanGroupedRow<F, ReduceResult<Spec>>[]>\n  async aggregate<Spec extends ReduceSpec>(\n    specOrBuild: Spec | ((b: ReducerBuilder<T, S, M>) => Spec),\n  ): Promise<ScanGroupedRow<F, ReduceResult<Spec>>[]> {\n    const raw: Spec =\n      typeof specOrBuild === 'function'\n        ? (specOrBuild as (b: ReducerBuilder<T, S, M>) => Spec)(reducerBuilder as unknown as ReducerBuilder<T, S, M>)\n        : specOrBuild\n    // Same reducer rewriting as the eager grouped path, and for the same\n    // reason: a money `sum` must accumulate per-currency BigInt totals, and a\n    // `countDistinct` must dedup on the canonical index key — otherwise a\n    // grouped scan and a grouped query disagree on identical data.\n    // `wrapReducers` runs the `queryable: 'none'` posture refusal itself.\n    const spec: ReduceSpec = bindDistinctReducers(this.via ? this.via.wrapReducers(raw) : raw, this.via)\n    const keys = Object.keys(spec)\n\n    const field = groupKeyName(this.key)\n    const derived: readonly DateTruncKey[] = isDateTruncKey(this.key) ? [this.key] : []\n    const groups = new Map<string, { keyValue: unknown; state: Record<string, unknown> }>()\n\n    for await (const record of this.stream) {\n      // A derived calendar key is stamped onto a shallow copy before bucketing\n      // — the reducers then see an ordinary row carrying an ordinary field,\n      // exactly as they do under `Query.groupBy(dateTrunc(...))`.\n      const row = derived.length === 0 ? record : projectDateTruncKeys([record], derived)[0]!\n      const keyValue = readPath(row, field)\n      const dedupKey = scanGroupKey(field, keyValue)\n      let group = groups.get(dedupKey)\n      if (group === undefined) {\n        if (groups.size >= this.maxGroups) {\n          // Loud and early: the state for this group is never allocated, so\n          // the refusal fires at the budget, not after blowing through it.\n          throw new GroupCardinalityError(field, groups.size + 1, this.maxGroups, 'scan')\n        }\n        const state: Record<string, unknown> = {}\n        for (const k of keys) state[k] = spec[k]!.init()\n        group = { keyValue, state }\n        groups.set(dedupKey, group)\n      }\n      for (const k of keys) group.state[k] = spec[k]!.step(group.state[k], row)\n    }\n\n    const out: ScanGroupedRow<F, ReduceResult<Spec>>[] = []\n    for (const group of groups.values()) {\n      // Group key first, then the reducer outputs — same row shape as the\n      // eager path, which tests assert by key order.\n      const outRow: Record<string, unknown> = { [field]: group.keyValue }\n      for (const k of keys) outRow[k] = spec[k]!.finalize(group.state[k])\n      out.push(outRow as ScanGroupedRow<F, ReduceResult<Spec>>)\n    }\n    return out\n  }\n}\n","/**\n * #1458 — the Reduce install. See `../relate/install.ts` for why this is a\n * function called from the entry rather than a module-level side effect.\n */\nimport { Query } from '../builder.js'\nimport { ScanBuilder } from '../scan-builder.js'\nimport { installMethods } from '../internal/core.js'\nimport { MaintenanceMethods } from '../internal/maintenance.js'\nimport { ReduceMethods } from './methods.js'\nimport { ScanReduceMethods } from './scan-methods.js'\n\nlet done = false\n\n/** Idempotent: the root barrel and the subpath entry both call it. */\nexport function installReduce(): void {\n  if (done) return\n  done = true\n  installMethods(Query.prototype, MaintenanceMethods)\n  installMethods(Query.prototype, ReduceMethods)\n  installMethods(ScanBuilder.prototype, ScanReduceMethods)\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-RMS3NEA3.js → chunk-4JPMZTJY.js}

@@ -1,7 +1,7 @@
 import {
   NonAdditiveSchemaChangeError,
   SchemaLockedError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-37EPTBBR.js";
 
 // src/with-shape/schema-update/strategies.ts
 function blindUpdate() {
@@ -62,4 +62,4 @@ export {
   lockSchema,
   coordinatedCutover
 };
-//# sourceMappingURL=chunk-RMS3NEA3.js.map
+//# sourceMappingURL=chunk-4JPMZTJY.js.map

package/dist/{chunk-P3MG6QCN.js → chunk-4T3SE27M.js}

@@ -3,14 +3,10 @@ import {
 } from "./chunk-4AOERLTV.js";
 import {
   buildRecordAad,
+  buildRecordEnvelope,
+  encrypt,
   openEnvelopeJson
-} from "./chunk-4ZS56W5S.js";
-import {
-  buildRecordEnvelope
-} from "./chunk-SZJ3DLZA.js";
-import {
-  encrypt
-} from "./chunk-HPVZCW43.js";
+} from "./chunk-EZGV6F47.js";
 
 // src/with-audit/consent/consent.ts
 var CONSENT_AUDIT_COLLECTION = "_consent_audit";
@@ -48,7 +44,7 @@ async function buildEnvelope(entry, encrypted, getDEK) {
   return buildRecordEnvelope(identity, { ...body, iv, data });
 }
 async function decryptEntry(id, envelope, encrypted, getDEK) {
-  if (!encrypted) return JSON.parse(envelope._data);
+  if (!encrypted) return JSON.parse(envelope._data ?? "");
   const json = await openEnvelopeJson({ collection: CONSENT_AUDIT_COLLECTION, id }, envelope, await getDEK(CONSENT_AUDIT_COLLECTION));
   return JSON.parse(json);
 }
@@ -66,4 +62,4 @@ export {
   writeConsentEntry,
   loadConsentEntries
 };
-//# sourceMappingURL=chunk-P3MG6QCN.js.map
+//# sourceMappingURL=chunk-4T3SE27M.js.map

package/dist/chunk-4T3SE27M.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-audit/consent/consent.ts"],"sourcesContent":["/**\n * Consent boundaries — per-access audit log.\n *\n * ```ts\n * const audit = await vault.withConsent(\n *   { purpose: 'quarterly-review', consentHash: '7f3a...' },\n *   async () => {\n *     const invoices = await vault.collection<Invoice>('invoices').list()\n *     return invoices\n *   },\n * )\n *\n * const log = await vault.consentAudit({ since: '2026-01-01T00:00:00Z' })\n * // → entries: { actor, purpose, consentHash, ts, op, collection, id }\n * ```\n *\n * ## Contract\n *\n * Every `get` / `put` / `delete` that happens inside a `withConsent`\n * callback writes one entry to the reserved `_consent_audit`\n * collection. Entries are encrypted with the vault's consent-audit\n * DEK (separate from per-user-collection DEKs so access-log queries\n * don't require unwrapping individual collection keys). Outside a\n * `withConsent` scope, no entries are written — consent is\n * opt-in by design (GDPR Art. 7: *demonstrable*, *specific*\n * consent).\n *\n * ## Why store the hash, not the consent text?\n *\n * The `consentHash` is the sha256 of whatever consent receipt the\n * actor presented (a signed GDPR banner click, a HIPAA authorisation\n * PDF, an API-level `X-Consent-Hash` header). Storing only the hash:\n *\n *   1. Keeps the audit log small and indexable.\n *   2. Preserves zero-knowledge at the adapter — adapters see\n *      ciphertext envelopes of `{ actor, purpose, consentHash, ts,\n *      op, collection, id }`, never the consent record itself.\n *   3. Lets the regulator verify a presented consent doc matches\n *      the logged hash at audit time without the system ever\n *      possessing the doc.\n *\n * ## Concurrency\n *\n * The consent context lives on the {@link Vault} instance. Two\n * concurrent `withConsent` calls on the same Vault would stomp each\n * other — documented limitation; adopters needing per-flight scope\n * should use separate Vault instances or an AsyncLocalStorage shim.\n *\n * @module\n */\nimport type { EncryptedEnvelope, NoydbStore } from '../../kernel/types.js'\nimport { buildRecordAad, buildRecordEnvelope, encrypt, openEnvelopeJson, type EnclaveKey } from '../../capsule/index.js'\nimport { generateULID } from '../../with-pod/ulid.js'\n\n/** Reserved collection for consent-audit entries. */\nexport const CONSENT_AUDIT_COLLECTION = '_consent_audit'\n\n/**\n * The consent scope active for a block of work. Set via\n * `vault.withConsent()`; observed by the collection's access hooks.\n */\nexport interface ConsentContext {\n  /**\n   * What this access is for. Used by the audit query (`consentAudit\n   * ({ purpose })`) and carried in the stored entry. Free-form; the\n   * regulator or compliance tooling decides the vocabulary.\n   */\n  readonly purpose: string\n  /**\n   * Hex-encoded sha256 of whatever consent artefact the actor\n   * presented. Stored as-is in each entry.\n   */\n  readonly consentHash: string\n}\n\n/**\n * Access operation recorded in an audit entry.\n *\n * Union-widening checklist (I-2) — these three sites widen together or a\n * downstream exhaustive switch breaks at its next in-range minor:\n *   1. `ConsentOp` here (public, re-exported at `index.ts`).\n *   2. `onAccess` op union on `kernel/collection-config.ts`.\n *   3. classified ctx `onAccess` op union on `port/with/classified-strategy.ts`\n *      (the `ClassifiedVerifyCtx` one — the `ClassifiedRevealCtx` one stays `'reveal'`-only).\n */\nexport type ConsentOp = 'get' | 'put' | 'delete' | 'reveal' | 'verify' | 'find'\n\n/** One consent-audit record, as decrypted for the caller. */\nexport interface ConsentAuditEntry {\n  /** ULID — stable insertion-order key. */\n  readonly id: string\n  readonly timestamp: string\n  readonly actor: string\n  readonly purpose: string\n  readonly consentHash: string\n  readonly op: ConsentOp\n  readonly collection: string\n  readonly recordId: string\n}\n\n/** Filter passed to `vault.consentAudit()`. */\nexport interface ConsentAuditFilter {\n  /** Only entries at or after this ISO timestamp. */\n  readonly since?: string\n  /** Only entries at or before this ISO timestamp. */\n  readonly until?: string\n  /** Match entries targeting this collection. */\n  readonly collection?: string\n  /** Match entries written by this actor. */\n  readonly actor?: string\n  /** Match entries with this purpose. */\n  readonly purpose?: string\n}\n\n/**\n * Write one audit entry. Called by Vault's onAccess hook when a\n * consent context is active.\n */\nexport async function writeConsentEntry(\n  adapter: NoydbStore,\n  vault: string,\n  encrypted: boolean,\n  entry: Omit<ConsentAuditEntry, 'id' | 'timestamp'>,\n  getDEK: (collection: string) => Promise<EnclaveKey>,\n): Promise<void> {\n  const id = generateULID()\n  const full: ConsentAuditEntry = {\n    id,\n    timestamp: new Date().toISOString(),\n    ...entry,\n  }\n  const envelope = await buildEnvelope(full, encrypted, getDEK)\n  await adapter.put(vault, CONSENT_AUDIT_COLLECTION, id, envelope)\n}\n\n/** Load + decrypt + filter all entries. */\nexport async function loadConsentEntries(\n  adapter: NoydbStore,\n  vault: string,\n  encrypted: boolean,\n  getDEK: (collection: string) => Promise<EnclaveKey>,\n  filter: ConsentAuditFilter = {},\n): Promise<ConsentAuditEntry[]> {\n  const ids = await adapter.list(vault, CONSENT_AUDIT_COLLECTION)\n  const entries: ConsentAuditEntry[] = []\n\n  for (const id of ids.sort()) {\n    const envelope = await adapter.get(vault, CONSENT_AUDIT_COLLECTION, id)\n    if (!envelope) continue\n    const entry = await decryptEntry(id, envelope, encrypted, getDEK)\n    if (!matchesFilter(entry, filter)) continue\n    entries.push(entry)\n  }\n  return entries\n}\n\n// ── internals ──────────────────────────────────────────────────────\n\nasync function buildEnvelope(\n  entry: ConsentAuditEntry,\n  encrypted: boolean,\n  getDEK: (collection: string) => Promise<EnclaveKey>,\n): Promise<EncryptedEnvelope> {\n  const json = JSON.stringify(entry)\n  // `entry.id` IS the record id the caller writes under, so identity needs no\n  // threading here (#1051).\n  const identity = { collection: CONSENT_AUDIT_COLLECTION, id: entry.id, version: 1 }\n  const body = { ts: entry.timestamp }\n  if (!encrypted) {\n    return buildRecordEnvelope(identity, { ...body, iv: '', data: json })\n  }\n  const dek = await getDEK(CONSENT_AUDIT_COLLECTION)\n  const { iv, data } = await encrypt(json, dek, buildRecordAad(identity))\n  return buildRecordEnvelope(identity, { ...body, iv, data })\n}\n\nasync function decryptEntry(\n  id: string,\n  envelope: EncryptedEnvelope,\n  encrypted: boolean,\n  getDEK: (collection: string) => Promise<EnclaveKey>,\n): Promise<ConsentAuditEntry> {\n  if (!encrypted) return JSON.parse(envelope._data ?? '') as ConsentAuditEntry\n  const json = await openEnvelopeJson({ collection: CONSENT_AUDIT_COLLECTION, id }, envelope, await getDEK(CONSENT_AUDIT_COLLECTION))\n  return JSON.parse(json) as ConsentAuditEntry\n}\n\nfunction matchesFilter(entry: ConsentAuditEntry, f: ConsentAuditFilter): boolean {\n  if (f.since && entry.timestamp < f.since) return false\n  if (f.until && entry.timestamp > f.until) return false\n  if (f.collection && entry.collection !== f.collection) return false\n  if (f.actor && entry.actor !== f.actor) return false\n  if (f.purpose && entry.purpose !== f.purpose) return false\n  return true\n}\n"],"mappings":";;;;;;;;;;;AAuDO,IAAM,2BAA2B;AA+DxC,eAAsB,kBACpB,SACA,OACA,WACA,OACA,QACe;AACf,QAAM,KAAK,aAAa;AACxB,QAAM,OAA0B;AAAA,IAC9B;AAAA,IACA,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,IAClC,GAAG;AAAA,EACL;AACA,QAAM,WAAW,MAAM,cAAc,MAAM,WAAW,MAAM;AAC5D,QAAM,QAAQ,IAAI,OAAO,0BAA0B,IAAI,QAAQ;AACjE;AAGA,eAAsB,mBACpB,SACA,OACA,WACA,QACA,SAA6B,CAAC,GACA;AAC9B,QAAM,MAAM,MAAM,QAAQ,KAAK,OAAO,wBAAwB;AAC9D,QAAM,UAA+B,CAAC;AAEtC,aAAW,MAAM,IAAI,KAAK,GAAG;AAC3B,UAAM,WAAW,MAAM,QAAQ,IAAI,OAAO,0BAA0B,EAAE;AACtE,QAAI,CAAC,SAAU;AACf,UAAM,QAAQ,MAAM,aAAa,IAAI,UAAU,WAAW,MAAM;AAChE,QAAI,CAAC,cAAc,OAAO,MAAM,EAAG;AACnC,YAAQ,KAAK,KAAK;AAAA,EACpB;AACA,SAAO;AACT;AAIA,eAAe,cACb,OACA,WACA,QAC4B;AAC5B,QAAM,OAAO,KAAK,UAAU,KAAK;AAGjC,QAAM,WAAW,EAAE,YAAY,0BAA0B,IAAI,MAAM,IAAI,SAAS,EAAE;AAClF,QAAM,OAAO,EAAE,IAAI,MAAM,UAAU;AACnC,MAAI,CAAC,WAAW;AACd,WAAO,oBAAoB,UAAU,EAAE,GAAG,MAAM,IAAI,IAAI,MAAM,KAAK,CAAC;AAAA,EACtE;AACA,QAAM,MAAM,MAAM,OAAO,wBAAwB;AACjD,QAAM,EAAE,IAAI,KAAK,IAAI,MAAM,QAAQ,MAAM,KAAK,eAAe,QAAQ,CAAC;AACtE,SAAO,oBAAoB,UAAU,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC;AAC5D;AAEA,eAAe,aACb,IACA,UACA,WACA,QAC4B;AAC5B,MAAI,CAAC,UAAW,QAAO,KAAK,MAAM,SAAS,SAAS,EAAE;AACtD,QAAM,OAAO,MAAM,iBAAiB,EAAE,YAAY,0BAA0B,GAAG,GAAG,UAAU,MAAM,OAAO,wBAAwB,CAAC;AAClI,SAAO,KAAK,MAAM,IAAI;AACxB;AAEA,SAAS,cAAc,OAA0B,GAAgC;AAC/E,MAAI,EAAE,SAAS,MAAM,YAAY,EAAE,MAAO,QAAO;AACjD,MAAI,EAAE,SAAS,MAAM,YAAY,EAAE,MAAO,QAAO;AACjD,MAAI,EAAE,cAAc,MAAM,eAAe,EAAE,WAAY,QAAO;AAC9D,MAAI,EAAE,SAAS,MAAM,UAAU,EAAE,MAAO,QAAO;AAC/C,MAAI,EAAE,WAAW,MAAM,YAAY,EAAE,QAAS,QAAO;AACrD,SAAO;AACT;","names":[]}

package/dist/chunk-4V3Q35WG.js

@@ -0,0 +1,204 @@
+import {
+  compareKeys,
+  toSortKey
+} from "./chunk-LGNDFRYC.js";
+import {
+  readPath
+} from "./chunk-5WWDGFOS.js";
+
+// src/kernel/query/relate/join-on.ts
+var RANGE_OPS = /* @__PURE__ */ new Set(["<", "<=", ">", ">=", "between"]);
+function isField(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function normalizeJoinOn(on, target) {
+  if (Array.isArray(on)) {
+    const pairs = on;
+    if (pairs.length === 0) {
+      throw new Error(
+        `.joinOn("${target}"): a composite \`on\` needs at least one [leftField, rightField] pair. Pass e.g. on: [['clientId', 'clientId'], ['year', 'year']].`
+      );
+    }
+    const normalized = [];
+    for (const pair of pairs) {
+      if (!Array.isArray(pair) || pair.length !== 2 || !isField(pair[0]) || !isField(pair[1])) {
+        throw new Error(
+          `.joinOn("${target}"): every composite \`on\` entry must be a [leftField, rightField] pair of non-empty field names. Received: ${JSON.stringify(pair)}.`
+        );
+      }
+      normalized.push([pair[0], pair[1]]);
+    }
+    normalized.sort((a, b) => a[0] === b[0] ? a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0 : a[0] < b[0] ? -1 : 1);
+    return { kind: "composite", pairs: normalized };
+  }
+  const spec = on;
+  if (!isField(spec.left)) {
+    throw new Error(`.joinOn("${target}"): a range \`on\` needs a non-empty \`left\` field name.`);
+  }
+  if (typeof spec.op !== "string" || !RANGE_OPS.has(spec.op)) {
+    throw new Error(
+      `.joinOn("${target}"): unknown \`on\` operator ${JSON.stringify(spec.op)}. Supported operators are ${[...RANGE_OPS].join(", ")}.`
+    );
+  }
+  if (spec.op === "between") {
+    if (!Array.isArray(spec.right) || spec.right.length !== 2 || !isField(spec.right[0]) || !isField(spec.right[1])) {
+      throw new Error(
+        `.joinOn("${target}"): \`between\` needs exactly two right-side boundary field names \u2014 on: { left: 'date', op: 'between', right: ['from', 'to'] }.`
+      );
+    }
+    return { kind: "range", left: spec.left, op: "between", right: [spec.right[0], spec.right[1]] };
+  }
+  if (!isField(spec.right)) {
+    throw new Error(`.joinOn("${target}"): the \`${spec.op}\` operator needs a single right-side field name.`);
+  }
+  return { kind: "range", left: spec.left, op: spec.op, right: [spec.right] };
+}
+function describeJoinOn(on) {
+  if (on.kind === "composite") return on.pairs.map(([l, r]) => `${l} = ${r}`).join(" AND ");
+  if (on.op === "between") return `${on.left} between [${on.right.join(", ")}]`;
+  return `${on.left} ${on.op} ${on.right[0]}`;
+}
+function joinOnDispatch(on) {
+  return on.kind === "composite" ? "join:composite-hash" : "join:sorted-range";
+}
+function tupleKey(values) {
+  let out = "";
+  for (const value of values) {
+    const sk = toSortKey(value, void 0);
+    if (!sk) return void 0;
+    const text = String(sk.key);
+    out += `${sk.kind}:${text.length}:${text}|`;
+  }
+  return out;
+}
+function matchDeclaredJoin(leftRows, on, rightSnapshot, maxRows, onOverflow) {
+  const out = [];
+  const push = (left, right) => {
+    if (out.length >= maxRows) onOverflow(out.length + 1);
+    out.push({ left, right });
+  };
+  if (on.kind === "composite") {
+    compositeHashJoin(leftRows, on, rightSnapshot, push);
+  } else {
+    sortedRangeJoin(leftRows, on, rightSnapshot, push);
+  }
+  return out;
+}
+function compositeHashJoin(leftRows, on, rightSnapshot, push) {
+  const leftFields = on.pairs.map((p) => p[0]);
+  const rightFields = on.pairs.map((p) => p[1]);
+  const buckets = /* @__PURE__ */ new Map();
+  for (const record of rightSnapshot) {
+    const key = tupleKey(rightFields.map((f) => readPath(record, f)));
+    if (key === void 0) continue;
+    const bucket = buckets.get(key);
+    if (bucket) bucket.push(record);
+    else buckets.set(key, [record]);
+  }
+  for (const left of leftRows) {
+    const key = tupleKey(leftFields.map((f) => readPath(left, f)));
+    const bucket = key === void 0 ? void 0 : buckets.get(key);
+    if (!bucket || bucket.length === 0) {
+      push(left, void 0);
+      continue;
+    }
+    for (const right of bucket) push(left, right);
+  }
+}
+function sortedRangeJoin(leftRows, on, rightSnapshot, push) {
+  const lowField = on.right[0];
+  const highField = on.op === "between" ? on.right[1] : void 0;
+  const entries = [];
+  for (const record of rightSnapshot) {
+    const key = toSortKey(readPath(record, lowField), void 0);
+    if (!key) continue;
+    const hi = highField === void 0 ? void 0 : toSortKey(readPath(record, highField), void 0);
+    if (highField !== void 0 && !hi) continue;
+    entries.push({ key, hi, record });
+  }
+  entries.sort((a, b) => compareKeys(a.key, b.key));
+  for (const left of leftRows) {
+    const probe = toSortKey(readPath(left, on.left), void 0);
+    if (!probe) {
+      push(left, void 0);
+      continue;
+    }
+    const [bandStart, bandEnd] = kindBand(entries, probe.kind);
+    const lo = lowerBound(entries, probe, bandStart, bandEnd);
+    const hi = upperBound(entries, probe, bandStart, bandEnd);
+    let matched = false;
+    const emit = (from, to, keep) => {
+      for (let i = from; i < to; i++) {
+        const entry = entries[i];
+        if (keep && !keep(entry)) continue;
+        matched = true;
+        push(left, entry.record);
+      }
+    };
+    switch (on.op) {
+      // `left.field < right.field` — the right keys strictly ABOVE the probe.
+      case "<":
+        emit(hi, bandEnd);
+        break;
+      case "<=":
+        emit(lo, bandEnd);
+        break;
+      case ">":
+        emit(bandStart, lo);
+        break;
+      case ">=":
+        emit(bandStart, hi);
+        break;
+      // `right.from <= left.field <= right.to`. Sorted by `from`, so the
+      // candidates are the prefix whose `from` is at or below the probe; the
+      // `to` bound is then a filter over that prefix, which is what makes the
+      // interval case O(p) per left row rather than O(log m).
+      case "between":
+        emit(bandStart, hi, (e) => e.hi !== void 0 && compareKeys(e.hi, probe) >= 0);
+        break;
+    }
+    if (!matched) push(left, void 0);
+  }
+}
+function kindBand(entries, kind) {
+  const bound = (strict) => {
+    let lo = 0;
+    let hi = entries.length;
+    while (lo < hi) {
+      const mid = lo + hi >>> 1;
+      const d = entries[mid].key.kind - kind;
+      if (strict ? d < 0 : d <= 0) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo;
+  };
+  return [bound(true), bound(false)];
+}
+function lowerBound(entries, probe, from = 0, to = entries.length) {
+  let lo = from;
+  let hi = to;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (compareKeys(entries[mid].key, probe) < 0) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+function upperBound(entries, probe, from = 0, to = entries.length) {
+  let lo = from;
+  let hi = to;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (compareKeys(entries[mid].key, probe) <= 0) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+export {
+  normalizeJoinOn,
+  describeJoinOn,
+  joinOnDispatch,
+  matchDeclaredJoin
+};
+//# sourceMappingURL=chunk-4V3Q35WG.js.map

package/dist/chunk-4V3Q35WG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/query/relate/join-on.ts"],"sourcesContent":["/**\n * Declared non-equi and composite joins — `.joinOn(target, { on })` (#1339).\n *\n * `join.ts` resolves a `ref()`-declared FK against the target's `id`. That is\n * one shape of join. This module is the other two the query DSL could not\n * express at all:\n *\n *   - **composite equality** — `on: [['clientId','clientId'], ['year','year']]`\n *   - **range / theta**      — `on: { left: 'date', op: 'between', right: ['from','to'] }`\n *\n * ⭐ THE DECLARED FORM IS THE WHOLE POINT, and it is the only reason this is\n * not `crossJoin({ on: fn })` with extra steps. `crossJoin`'s `on` is a\n * closure: it pairs arbitrary rows perfectly and serializes to the sentinel\n * `'[inline]'`, which is why a materialized view over one has its drift\n * detection disabled. A `JoinOnPlan` is plain JSON, so `serializePlan()`\n * emits it verbatim, `summarizeQueryPlan()` folds it into the MV\n * `queryHash`, and two plans differing only in their `on` are two different\n * queries — pinned by `__tests__/query-join-on.test.ts`.\n *\n * ⛔ THE NORMAL FORM IS PART OF THE HASH. `normalizeJoinOn` is the ONLY place\n * a `JoinOnSpec` becomes a `JoinOnPlan`, and it sorts composite pairs so two\n * logically identical joins hash identically (an AND of equalities is\n * commutative). Changing the normal form moves every stored `queryHash` for a\n * `joinOn` MV. Adding a new `on` KIND does not, because the leg is omitted\n * entirely when absent — the same discipline `direction` (#1289) and `inner`\n * (#1361) follow.\n *\n * **Key encoding.** Both strategies key on {@link SortKey} — the per-component\n * ordered key #1345's `CompoundIndex` already uses — rather than a second,\n * hand-rolled encoding. That buys the kind-ranking invariant for free: the\n * string `'2026'` and the number `2026` live in different kinds and never\n * match, exactly as `predicate.ts`'s `isComparable` refuses to compare them.\n * A component whose value has no order-defined type (nullish, boolean,\n * object, array) makes the whole record unkeyable and it drops out of the\n * probe — same rule as `CompoundIndex`, where a record is indexed only when\n * EVERY component has an ordered value.\n *\n * **Cost, stated honestly:**\n *\n * | strategy | build | per left row | total |\n * |---|---|---|---|\n * | `join:composite-hash` | O(m) one pass | O(1) + matches | **O(n + m + output)** |\n * | `join:sorted-range` (`< <= > >=`) | O(m log m) one sort | O(log m) + matches | **O(m log m + n log m + output)** |\n * | `join:sorted-range` (`between`) | O(m log m) | O(log m + p), p = rights whose `from` ≤ probe | **O(m log m + n·p)** — degrades to O(n·m) when every interval starts early |\n *\n * ⚠️ Neither is index-aware in the `lookupRange`/`lookupCompound` sense: a\n * `JoinableSource` exposes `snapshot()` and `lookupById()` and nothing else,\n * so the right collection's declared indexes are not reachable from here.\n * The sort/hash is built per execution over the right SNAPSHOT. Reaching a\n * real index would mean widening the published `JoinableSource` seam and\n * taking a kernel→`with-lookup` runtime edge for a service that is opt-in;\n * that is a separate decision, not a detail of this one.\n *\n * ⚠️ **A theta join EXPANDS rows**, which the ref join never does — so the\n * per-side `maxRows` ceilings are not sufficient on their own. The OUTPUT is\n * checked against the same ceiling as it is produced, and the join throws\n * `JoinTooLargeError` with `side: 'output'` rather than allocating an\n * unbounded cartesian product. That check is the difference between an error\n * and a hang.\n */\n\nimport { readPath } from '../predicate.js'\nimport { compareKeys, toSortKey, type SortKey } from '../sort-key.js'\n\n/** Comparison operators a declared range join understands. */\nexport type JoinOnOp = '<' | '<=' | '>' | '>=' | 'between'\n\n/**\n * The consumer-facing `on`, in either of the two shapes #1339 proposed.\n *\n *   - `[['clientId','clientId'], ['year','year']]` — composite equality; every\n *     pair must match. Each pair is `[leftField, rightField]`.\n *   - `{ left, op, right }` — a comparison of ONE left field against one right\n *     field (`< <= > >=`), or against a right INTERVAL for `between`, where\n *     `right` names the two boundary fields `[fromField, toField]` and the\n *     bounds are inclusive.\n */\nexport type JoinOnSpec =\n  | readonly (readonly [string, string])[]\n  | {\n      readonly left: string\n      readonly op: Exclude<JoinOnOp, 'between'>\n      readonly right: string\n    }\n  | {\n      readonly left: string\n      readonly op: 'between'\n      readonly right: readonly [string, string]\n    }\n\n/**\n * The normalised, serialisable form stored on the {@link JoinLeg}. This is\n * what lands in `toPlan()` and in the MV `queryHash` — see the module header\n * before changing its shape.\n */\nexport type JoinOnPlan =\n  | {\n      readonly kind: 'composite'\n      /** `[leftField, rightField]` pairs, sorted by left then right field. */\n      readonly pairs: readonly (readonly [string, string])[]\n    }\n  | {\n      readonly kind: 'range'\n      readonly left: string\n      readonly op: JoinOnOp\n      /** One right field, or the two inclusive boundary fields for `between`. */\n      readonly right: readonly string[]\n    }\n\nconst RANGE_OPS: ReadonlySet<string> = new Set(['<', '<=', '>', '>=', 'between'])\n\nfunction isField(value: unknown): value is string {\n  return typeof value === 'string' && value.length > 0\n}\n\n/**\n * Validate and normalise a consumer `on` into its plan form.\n *\n * Every refusal is at PLAN time, with the offending shape named: an `on` that\n * cannot be serialised deterministically must never reach a `queryHash`,\n * because a hash over an invalid plan is a hash nothing can reproduce.\n */\nexport function normalizeJoinOn(on: JoinOnSpec, target: string): JoinOnPlan {\n  if (Array.isArray(on)) {\n    const pairs = on as readonly unknown[]\n    if (pairs.length === 0) {\n      throw new Error(\n        `.joinOn(\"${target}\"): a composite \\`on\\` needs at least one [leftField, rightField] pair. ` +\n          `Pass e.g. on: [['clientId', 'clientId'], ['year', 'year']].`,\n      )\n    }\n    const normalized: [string, string][] = []\n    for (const pair of pairs) {\n      if (!Array.isArray(pair) || pair.length !== 2 || !isField(pair[0]) || !isField(pair[1])) {\n        throw new Error(\n          `.joinOn(\"${target}\"): every composite \\`on\\` entry must be a [leftField, rightField] pair of ` +\n            `non-empty field names. Received: ${JSON.stringify(pair)}.`,\n        )\n      }\n      normalized.push([pair[0], pair[1]])\n    }\n    // Sorted so a caller reordering the pairs does not change the queryHash —\n    // an AND of equalities is commutative, so two such plans ARE the same\n    // query and a reorder must not force every MV row to rebuild.\n    normalized.sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : a[0] < b[0] ? -1 : 1))\n    return { kind: 'composite', pairs: normalized }\n  }\n\n  const spec = on as { left?: unknown; op?: unknown; right?: unknown }\n  if (!isField(spec.left)) {\n    throw new Error(`.joinOn(\"${target}\"): a range \\`on\\` needs a non-empty \\`left\\` field name.`)\n  }\n  if (typeof spec.op !== 'string' || !RANGE_OPS.has(spec.op)) {\n    throw new Error(\n      `.joinOn(\"${target}\"): unknown \\`on\\` operator ${JSON.stringify(spec.op)}. ` +\n        `Supported operators are ${[...RANGE_OPS].join(', ')}.`,\n    )\n  }\n  if (spec.op === 'between') {\n    if (!Array.isArray(spec.right) || spec.right.length !== 2 || !isField(spec.right[0]) || !isField(spec.right[1])) {\n      throw new Error(\n        `.joinOn(\"${target}\"): \\`between\\` needs exactly two right-side boundary field names — ` +\n          `on: { left: 'date', op: 'between', right: ['from', 'to'] }.`,\n      )\n    }\n    return { kind: 'range', left: spec.left, op: 'between', right: [spec.right[0], spec.right[1]] }\n  }\n  if (!isField(spec.right)) {\n    throw new Error(`.joinOn(\"${target}\"): the \\`${spec.op}\\` operator needs a single right-side field name.`)\n  }\n  return { kind: 'range', left: spec.left, op: spec.op as JoinOnOp, right: [spec.right] }\n}\n\n/** A short, stable rendering of the predicate for `explain()`'s detail line. */\nexport function describeJoinOn(on: JoinOnPlan): string {\n  if (on.kind === 'composite') return on.pairs.map(([l, r]) => `${l} = ${r}`).join(' AND ')\n  if (on.op === 'between') return `${on.left} between [${on.right.join(', ')}]`\n  return `${on.left} ${on.op} ${on.right[0]}`\n}\n\n/** `explain()`'s dispatch label for a declared-`on` leg. */\nexport function joinOnDispatch(on: JoinOnPlan): 'join:composite-hash' | 'join:sorted-range' {\n  return on.kind === 'composite' ? 'join:composite-hash' : 'join:sorted-range'\n}\n\n/**\n * Length-prefixed tuple key. `${kind}:${len}:${value}` per component means a\n * string component may contain any byte — including the separator — without\n * colliding with a neighbouring component, which a plain `join('\u0000')`\n * cannot promise. `undefined` when ANY component has no ordered key, matching\n * `CompoundIndex`: a record with one unkeyable component is not in the index.\n */\nfunction tupleKey(values: readonly unknown[]): string | undefined {\n  let out = ''\n  for (const value of values) {\n    const sk = toSortKey(value, undefined)\n    if (!sk) return undefined\n    const text = String(sk.key)\n    out += `${sk.kind}:${text.length}:${text}|`\n  }\n  return out\n}\n\n/** One row the declared join produced: the left row and its matched right record. */\nexport interface JoinOnMatch {\n  readonly left: unknown\n  /** `undefined` when this left row matched nothing — the left-outer row. */\n  readonly right: unknown\n}\n\n/**\n * Run a declared `on` against the right snapshot, emitting one\n * {@link JoinOnMatch} per matched pair plus one `right: undefined` match per\n * left row that matched nothing (the caller applies ref-mode / inner-drop\n * semantics, exactly as it does for the ref join).\n *\n * `onOverflow` is called the moment the produced row count would exceed the\n * ceiling; it is expected to throw. Passing the check as a callback keeps the\n * error's wording — which names the leg and the ceiling — with the leg.\n */\nexport function matchDeclaredJoin(\n  leftRows: readonly unknown[],\n  on: JoinOnPlan,\n  rightSnapshot: readonly unknown[],\n  maxRows: number,\n  onOverflow: (produced: number) => never,\n): JoinOnMatch[] {\n  const out: JoinOnMatch[] = []\n  const push = (left: unknown, right: unknown): void => {\n    if (out.length >= maxRows) onOverflow(out.length + 1)\n    out.push({ left, right })\n  }\n  if (on.kind === 'composite') {\n    compositeHashJoin(leftRows, on, rightSnapshot, push)\n  } else {\n    sortedRangeJoin(leftRows, on, rightSnapshot, push)\n  }\n  return out\n}\n\n/** Hash join over a tuple key — O(n + m + output). */\nfunction compositeHashJoin(\n  leftRows: readonly unknown[],\n  on: Extract<JoinOnPlan, { kind: 'composite' }>,\n  rightSnapshot: readonly unknown[],\n  push: (left: unknown, right: unknown) => void,\n): void {\n  const leftFields = on.pairs.map(p => p[0])\n  const rightFields = on.pairs.map(p => p[1])\n  const buckets = new Map<string, unknown[]>()\n  for (const record of rightSnapshot) {\n    const key = tupleKey(rightFields.map(f => readPath(record, f)))\n    if (key === undefined) continue\n    const bucket = buckets.get(key)\n    if (bucket) bucket.push(record)\n    else buckets.set(key, [record])\n  }\n  for (const left of leftRows) {\n    const key = tupleKey(leftFields.map(f => readPath(left, f)))\n    const bucket = key === undefined ? undefined : buckets.get(key)\n    if (!bucket || bucket.length === 0) {\n      push(left, undefined)\n      continue\n    }\n    for (const right of bucket) push(left, right)\n  }\n}\n\ninterface RangeEntry {\n  readonly key: SortKey\n  /** The upper boundary key, for `between` only. */\n  readonly hi: SortKey | undefined\n  readonly record: unknown\n}\n\n/**\n * Nested loop over a right side sorted ONCE by the probed field.\n *\n * Entries are ordered by `compareKeys`, which ranks by kind first, so the\n * slice a probe may reach is clamped to the probe's own kind band — a string\n * probe cannot walk into the number entries, mirroring the linear scan.\n */\nfunction sortedRangeJoin(\n  leftRows: readonly unknown[],\n  on: Extract<JoinOnPlan, { kind: 'range' }>,\n  rightSnapshot: readonly unknown[],\n  push: (left: unknown, right: unknown) => void,\n): void {\n  const lowField = on.right[0]!\n  const highField = on.op === 'between' ? on.right[1]! : undefined\n  const entries: RangeEntry[] = []\n  for (const record of rightSnapshot) {\n    const key = toSortKey(readPath(record, lowField), undefined)\n    if (!key) continue\n    const hi = highField === undefined ? undefined : toSortKey(readPath(record, highField), undefined)\n    if (highField !== undefined && !hi) continue\n    entries.push({ key, hi, record })\n  }\n  entries.sort((a, b) => compareKeys(a.key, b.key))\n\n  for (const left of leftRows) {\n    const probe = toSortKey(readPath(left, on.left), undefined)\n    if (!probe) {\n      push(left, undefined)\n      continue\n    }\n    // The contiguous run of entries sharing the probe's kind. Everything\n    // outside it is incomparable, exactly as `isComparable` says.\n    const [bandStart, bandEnd] = kindBand(entries, probe.kind)\n    const lo = lowerBound(entries, probe, bandStart, bandEnd)\n    const hi = upperBound(entries, probe, bandStart, bandEnd)\n\n    let matched = false\n    const emit = (from: number, to: number, keep?: (e: RangeEntry) => boolean): void => {\n      for (let i = from; i < to; i++) {\n        const entry = entries[i]!\n        if (keep && !keep(entry)) continue\n        matched = true\n        push(left, entry.record)\n      }\n    }\n    switch (on.op) {\n      // `left.field < right.field` — the right keys strictly ABOVE the probe.\n      case '<': emit(hi, bandEnd); break\n      case '<=': emit(lo, bandEnd); break\n      case '>': emit(bandStart, lo); break\n      case '>=': emit(bandStart, hi); break\n      // `right.from <= left.field <= right.to`. Sorted by `from`, so the\n      // candidates are the prefix whose `from` is at or below the probe; the\n      // `to` bound is then a filter over that prefix, which is what makes the\n      // interval case O(p) per left row rather than O(log m).\n      case 'between':\n        emit(bandStart, hi, e => e.hi !== undefined && compareKeys(e.hi, probe) >= 0)\n        break\n    }\n    if (!matched) push(left, undefined)\n  }\n}\n\n/**\n * The half-open range of entries whose key has the given kind. Computed by\n * kind ALONE — a sentinel `SortKey` cannot express \"smallest of this kind\",\n * because `compareKeys` falls back to `<`/`>` on mixed key types and returns\n * 0 for a number sentinel against a string key, which would silently collapse\n * the band to nothing.\n */\nfunction kindBand(entries: readonly RangeEntry[], kind: number): [number, number] {\n  const bound = (strict: boolean): number => {\n    let lo = 0\n    let hi = entries.length\n    while (lo < hi) {\n      const mid = (lo + hi) >>> 1\n      const d = entries[mid]!.key.kind - kind\n      if (strict ? d < 0 : d <= 0) lo = mid + 1\n      else hi = mid\n    }\n    return lo\n  }\n  return [bound(true), bound(false)]\n}\n\nfunction lowerBound(entries: readonly RangeEntry[], probe: SortKey, from = 0, to = entries.length): number {\n  let lo = from\n  let hi = to\n  while (lo < hi) {\n    const mid = (lo + hi) >>> 1\n    if (compareKeys(entries[mid]!.key, probe) < 0) lo = mid + 1\n    else hi = mid\n  }\n  return lo\n}\n\nfunction upperBound(entries: readonly RangeEntry[], probe: SortKey, from = 0, to = entries.length): number {\n  let lo = from\n  let hi = to\n  while (lo < hi) {\n    const mid = (lo + hi) >>> 1\n    if (compareKeys(entries[mid]!.key, probe) <= 0) lo = mid + 1\n    else hi = mid\n  }\n  return lo\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-NQKIUNW5.js → chunk-52MGURXO.js}

@@ -1,6 +1,6 @@
 import {
   CargoNotEnabledError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-37EPTBBR.js";
 
 // src/with-cargo/strategy.ts
 var NO_CARGO = {
@@ -12,4 +12,4 @@ var NO_CARGO = {
 export {
   NO_CARGO
 };
-//# sourceMappingURL=chunk-NQKIUNW5.js.map
+//# sourceMappingURL=chunk-52MGURXO.js.map

package/dist/{chunk-EQEYOJBM.js → chunk-5A4345TG.js}

@@ -1,9 +1,9 @@
 import {
   buildRecordEnvelope
-} from "./chunk-SZJ3DLZA.js";
+} from "./chunk-EZGV6F47.js";
 import {
   ValidationError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-37EPTBBR.js";
 
 // src/with-party/directory/cover/custom.ts
 var CUSTOM_KEY_PATTERN = /^[a-z0-9]+([.-][a-z0-9]+)+$/i;
@@ -179,7 +179,7 @@ async function loadCover(store, vault) {
   const envelope = await store.get(vault, "_meta", COVER_RECORD_ID);
   if (!envelope) return void 0;
   try {
-    const parsed = JSON.parse(envelope._data);
+    const parsed = JSON.parse(envelope._data ?? "");
     if (!isCover(parsed)) return void 0;
     return parsed;
   } catch {
@@ -230,4 +230,4 @@ export {
   resolveLocale,
   pickLocale
 };
-//# sourceMappingURL=chunk-EQEYOJBM.js.map
+//# sourceMappingURL=chunk-5A4345TG.js.map

package/dist/chunk-5A4345TG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-party/directory/cover/custom.ts","../src/with-party/directory/cover/schema.ts","../src/with-party/directory/cover/storage.ts"],"sourcesContent":["/**\n * The cover's namespaced `custom` extension slot (#800) — input\n * validation, the namespace-level patch merge, and the post-merge\n * size caps.\n *\n * Like everything on the cover, `custom` is plaintext, public by\n * design, and unauthenticated — payloads are hints (display defaults,\n * routing suggestions, registry pointers), never an input to\n * security, authorization, or data-integrity decisions.\n *\n * @see https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md\n *\n * @module\n */\nimport { ValidationError } from '../../../kernel/errors.js'\nimport type { Cover, JsonValue, ResolvedCoverSchema } from './types.js'\n\n/**\n * Namespace keys must be reverse-DNS or package-style identifiers —\n * at least one dot/dash-separated segment (`noydb.viewer`,\n * `com.acme.registry` pass; a bare `config` fails), so two frameworks\n * can't collide on a bare word.\n */\nconst CUSTOM_KEY_PATTERN = /^[a-z0-9]+([.-][a-z0-9]+)+$/i\n\n/** Maximum nesting depth of a namespace payload (containers, not leaves). */\nconst MAX_CUSTOM_DEPTH = 8\n\n/**\n * Validate the owner-supplied `custom` input: the field must be a\n * plain object, every key must match {@link CUSTOM_KEY_PATTERN}, and\n * every value must be JSON-serializable (no functions, `undefined`,\n * symbols, bigints, or cycles) within the depth cap. `null` is\n * accepted — it is the delete-this-namespace directive and never\n * persists. Throws `ValidationError` on the first violation.\n */\nexport function validateCustomInput(custom: Record<string, JsonValue>): void {\n  if (custom === null || typeof custom !== 'object' || Array.isArray(custom)) {\n    throw new ValidationError(\n      `setCover: custom must be a { [namespace]: value } object, got ${\n        Array.isArray(custom) ? 'array' : typeof custom\n      }.`,\n    )\n  }\n  for (const [ns, value] of Object.entries(custom)) {\n    if (!CUSTOM_KEY_PATTERN.test(ns)) {\n      throw new ValidationError(\n        `setCover: custom namespace \"${ns}\" is invalid. Keys must be ` +\n          'reverse-DNS or package-style identifiers with at least one ' +\n          'dot/dash-separated segment (e.g. \"noydb.viewer\", \"com.acme.registry\").',\n      )\n    }\n    assertJsonValue(value, ns, 1, new Set())\n  }\n}\n\nfunction assertJsonValue(\n  value: unknown,\n  ns: string,\n  depth: number,\n  seen: Set<object>,\n): void {\n  if (value === null) return\n  const t = typeof value\n  if (t === 'string' || t === 'number' || t === 'boolean') return\n  if (t !== 'object') {\n    throw new ValidationError(\n      `setCover: custom[\"${ns}\"] contains a non-JSON value (${t}). ` +\n        'Only strings, numbers, booleans, null, arrays, and plain objects are allowed.',\n    )\n  }\n  const container = value as object\n  if (seen.has(container)) {\n    throw new ValidationError(\n      `setCover: custom[\"${ns}\"] contains a circular reference.`,\n    )\n  }\n  if (depth > MAX_CUSTOM_DEPTH) {\n    throw new ValidationError(\n      `setCover: custom[\"${ns}\"] nests deeper than the ${MAX_CUSTOM_DEPTH}-level cap.`,\n    )\n  }\n  seen.add(container)\n  const children = Array.isArray(container) ? container : Object.values(container)\n  for (const child of children) {\n    assertJsonValue(child, ns, depth + 1, seen)\n  }\n  seen.delete(container)\n}\n\n/**\n * Namespace-level patch merge for `setCover`: provided namespaces\n * replace their previous value, absent namespaces are preserved, and\n * an explicit `null` deletes that namespace (so `null` never persists\n * as a namespace value). A whole-`custom`-absent patch preserves the\n * previous custom, consistent with the other cover fields. Rationale:\n * framework A must never need read-modify-write of framework B's data.\n *\n * Returns a spreadable fragment — `{ custom }` when the merge leaves\n * at least one namespace, `{}` when it leaves none (the field is\n * dropped from the persisted document rather than stored empty).\n */\nexport function mergeCustom(\n  existing: Record<string, JsonValue> | undefined,\n  patch: Record<string, JsonValue> | undefined,\n): { custom: Record<string, JsonValue> } | Record<string, never> {\n  if (patch === undefined) {\n    return existing !== undefined ? { custom: existing } : {}\n  }\n  const merged: Record<string, JsonValue> = { ...existing }\n  for (const [ns, value] of Object.entries(patch)) {\n    if (value === null) {\n      delete merged[ns]\n    } else {\n      merged[ns] = value\n    }\n  }\n  return Object.keys(merged).length > 0 ? { custom: merged } : {}\n}\n\n/**\n * Post-merge size caps — validates the WOULD-BE-PERSISTED document\n * (after the namespace merge), so a small patch can't tip the stored\n * cover over a cap unnoticed. `maxCoverBytes` bounds the entire\n * serialized document, which also closes the unbounded locale-map\n * key-count hole for `name` / `description`. Sizes are measured as\n * `JSON.stringify` length. Throws `ValidationError` on violation.\n */\nexport function validateCoverSize(\n  cover: Cover,\n  schema: ResolvedCoverSchema,\n): void {\n  if (cover.custom !== undefined) {\n    const customSize = JSON.stringify(cover.custom).length\n    if (customSize > schema.maxCustomBytes) {\n      throw new ValidationError(\n        `setCover: custom exceeds the ${schema.maxCustomBytes}-byte cap ` +\n          `(got ${customSize} bytes serialized, after merging with the stored namespaces).`,\n      )\n    }\n  }\n  const totalSize = JSON.stringify(cover).length\n  if (totalSize > schema.maxCoverBytes) {\n    throw new ValidationError(\n      `setCover: the cover document exceeds the ${schema.maxCoverBytes}-byte cap ` +\n        `(got ${totalSize} bytes serialized).`,\n    )\n  }\n}\n","/**\n * Validate-on-write for the cover. Runs at every `setCover` call;\n * the developer's schema decides which fields are allowed and the\n * size caps that apply.\n *\n * @module\n */\nimport { ValidationError } from '../../../kernel/errors.js'\nimport { validateCustomInput } from './custom.js'\nimport type {\n  Cover,\n  CoverText,\n  JsonValue,\n  ResolvedCoverSchema,\n  CoverField,\n} from './types.js'\n\n/** Owner-supplied input — the subset of {@link Cover} the owner can set. */\nexport interface SetCoverInput {\n  readonly name?: CoverText\n  readonly description?: CoverText\n  readonly icon?: string\n  readonly defaultLocale?: string\n  /**\n   * Namespace-level patch for the cover's `custom` slot (#800):\n   * provided namespaces replace their previous value, absent\n   * namespaces are preserved, an explicit `null` deletes that\n   * namespace. Requires `'custom'` in the schema's `fields` list —\n   * the `cover: true` shorthand does NOT enable it.\n   */\n  readonly custom?: Record<string, JsonValue>\n}\n\nconst DATA_URL_PREFIX = /^data:([a-zA-Z0-9.+-]+\\/[a-zA-Z0-9.+-]+);base64,/\n\n/**\n * Validate an owner-supplied cover input against the developer's\n * resolved schema. Throws `ValidationError` on the first violation;\n * returns void on success.\n *\n * The validator is deliberately strict: every fail mode is a hard\n * error rather than a silent drop, so the owner finds out immediately\n * which field they oversized rather than discovering a truncated\n * label months later.\n */\nexport function validateCoverInput(\n  input: SetCoverInput,\n  schema: ResolvedCoverSchema,\n): void {\n  const allowed = new Set<CoverField>(schema.fields)\n\n  // Reject any key not in the schema's allowed-field list.\n  for (const key of Object.keys(input)) {\n    const known: CoverField | undefined =\n      key === 'name' || key === 'description' || key === 'icon' || key === 'defaultLocale' || key === 'custom'\n        ? key\n        : undefined\n    if (!known) {\n      throw new ValidationError(\n        `setCover: unknown field \"${key}\". ` +\n          `Allowed fields: ${[...allowed].join(', ')}.`,\n      )\n    }\n    if (!allowed.has(known)) {\n      throw new ValidationError(\n        `setCover: field \"${known}\" is not enabled in this vault's schema. ` +\n          `Allowed fields: ${[...allowed].join(', ')}.`,\n      )\n    }\n  }\n\n  if (input.name !== undefined) {\n    validateText(input.name, 'name', schema.maxStringChars)\n  }\n  if (input.description !== undefined) {\n    validateText(input.description, 'description', schema.maxStringChars)\n  }\n  if (input.icon !== undefined) {\n    validateIcon(input.icon, schema)\n  }\n  if (input.defaultLocale !== undefined && typeof input.defaultLocale !== 'string') {\n    throw new ValidationError(\n      `setCover: defaultLocale must be a string (BCP-47), got ${typeof input.defaultLocale}.`,\n    )\n  }\n  if (input.custom !== undefined) {\n    validateCustomInput(input.custom)\n  }\n}\n\nfunction validateText(\n  value: CoverText,\n  field: string,\n  maxChars: number,\n): void {\n  if (typeof value === 'string') {\n    if (value.length > maxChars) {\n      throw new ValidationError(\n        `setCover: ${field} exceeds the ${maxChars}-character cap (got ${value.length}).`,\n      )\n    }\n    return\n  }\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    throw new ValidationError(\n      `setCover: ${field} must be a string or { [locale]: string } map, got ${typeof value}.`,\n    )\n  }\n  // Locale map. Each value must be a non-empty string within the cap.\n  for (const [locale, str] of Object.entries(value)) {\n    if (typeof str !== 'string') {\n      throw new ValidationError(\n        `setCover: ${field}[${locale}] must be a string, got ${typeof str}.`,\n      )\n    }\n    if (str.length > maxChars) {\n      throw new ValidationError(\n        `setCover: ${field}[${locale}] exceeds the ${maxChars}-character cap (got ${str.length}).`,\n      )\n    }\n  }\n}\n\nfunction validateIcon(icon: string, schema: ResolvedCoverSchema): void {\n  if (typeof icon !== 'string') {\n    throw new ValidationError(\n      `setCover: icon must be a data: URL string, got ${typeof icon}.`,\n    )\n  }\n  if (icon.length > schema.maxIconBytes) {\n    throw new ValidationError(\n      `setCover: icon exceeds the ${schema.maxIconBytes}-byte cap (got ${icon.length}).`,\n    )\n  }\n  const m = DATA_URL_PREFIX.exec(icon)\n  if (!m) {\n    throw new ValidationError(\n      'setCover: icon must be a base64 data URL ' +\n        '(`data:image/png;base64,…` or `data:image/svg+xml;base64,…`). ' +\n        'External URLs are not supported in v1.',\n    )\n  }\n  const mime = m[1]!\n  if (!schema.iconMimeTypes.includes(mime)) {\n    throw new ValidationError(\n      `setCover: icon MIME type \"${mime}\" is not allowed. ` +\n        `Permitted types: ${schema.iconMimeTypes.join(', ')}.`,\n    )\n  }\n}\n\n/**\n * Lightweight runtime predicate — used by the bundle header\n * validator to recognise a cover without requiring it. (The wire\n * discriminator keeps its frozen name: `_noydb_public: 1`.)\n */\nexport function isCover(x: unknown): x is Cover {\n  if (x === null || typeof x !== 'object' || Array.isArray(x)) return false\n  const obj = x as Record<string, unknown>\n  return obj['_noydb_public'] === 1 && typeof obj['version'] === 'number'\n}\n","/**\n * Persistence helpers for `_meta/public-envelope` — the cover's\n * frozen wire location. Mirrors the bypass-AES pattern used by\n * `_meta/handle` and `_meta/policy` — the document is plaintext\n * JSON, the envelope's `_iv` field is left empty.\n *\n * @module\n */\nimport { buildRecordEnvelope } from '../../../capsule/index.js'\nimport type { NoydbStore } from '../../../kernel/types.js'\nimport type { Cover } from './types.js'\nimport { isCover } from './schema.js'\n\n/**\n * Reserved id for the vault-level cover record. The VALUE is frozen\n * wire format — the record predates the #799 rename and stays at\n * `_meta/public-envelope` so existing vaults need no migration.\n */\nexport const COVER_RECORD_ID = 'public-envelope'\n\n/**\n * Read the cover from `_meta/public-envelope`. Returns `undefined`\n * when no cover has been persisted (fresh vault, or a vault written\n * before the feature was enabled). Tolerates corrupted documents —\n * a JSON parse failure surfaces as `undefined`, not a thrown error,\n * mirroring `_meta/handle`'s contract.\n */\nexport async function loadCover(\n  store: NoydbStore,\n  vault: string,\n): Promise<Cover | undefined> {\n  const envelope = await store.get(vault, '_meta', COVER_RECORD_ID)\n  if (!envelope) return undefined\n  try {\n    const parsed = JSON.parse(envelope._data ?? '') as unknown\n    if (!isCover(parsed)) return undefined\n    return parsed\n  } catch {\n    return undefined\n  }\n}\n\n/** Persist the cover. Idempotent — overwrites any prior write. */\nexport async function saveCover(\n  store: NoydbStore,\n  vault: string,\n  cover: Cover,\n): Promise<void> {\n  const wireEnvelope = buildRecordEnvelope(\n    { collection: '_meta', id: COVER_RECORD_ID, version: 1 },\n    { iv: '', data: JSON.stringify(cover) },\n  )\n  await store.put(vault, '_meta', COVER_RECORD_ID, wireEnvelope)\n}\n\n/**\n * Public, no-key reader. Plain function, not a method on `Noydb` —\n * the whole point is it works without an authenticated session, so\n * a UI can show \"Acme 2026 Tax Records\" before unlocking.\n *\n * Resolves any `name` / `description` locale map through the supplied\n * `locale` (when provided). Omitting `locale` returns the raw\n * cover, which a multilingual picker can render as it pleases.\n */\nexport async function readCover(\n  store: NoydbStore,\n  vault: string,\n  opts: { readonly locale?: string } = {},\n): Promise<Cover | undefined> {\n  const raw = await loadCover(store, vault)\n  if (!raw) return undefined\n  if (opts.locale === undefined) return raw\n  return resolveLocale(raw, opts.locale)\n}\n\n/**\n * Resolve the locale-map fields (`name`, `description`) of a cover\n * to plain strings for the requested locale, falling back through\n * `defaultLocale` and then any available translation.\n *\n * @internal\n */\nexport function resolveLocale(\n  cover: Cover,\n  locale: string,\n): Cover {\n  return {\n    ...cover,\n    ...(cover.name !== undefined ? { name: pickLocale(cover.name, locale, cover.defaultLocale) } : {}),\n    ...(cover.description !== undefined ? { description: pickLocale(cover.description, locale, cover.defaultLocale) } : {}),\n  }\n}\n\n/**\n * Resolve a `string | { [locale]: string }` value to a string for a\n * given locale. Exported so the bundle reader can reuse it without\n * duplicating the fallback chain.\n *\n * **Looser than `resolveI18nText`** — the hub's record-field resolver\n * throws `LocaleNotSpecifiedError` when no translation matches, but\n * label semantics deliberately prefer \"show *something*\" over\n * throwing. The fallback chain is:\n *   1. Exact `locale` match.\n *   2. `defaultLocale` (when supplied on the cover).\n *   3. First non-empty value in the map.\n *   4. Empty string (only if every translation is empty — pathological).\n *\n * This deviation is documented in `https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md`.\n */\nexport function pickLocale(\n  value: string | Record<string, string>,\n  locale: string,\n  defaultLocale: string | undefined,\n): string {\n  if (typeof value === 'string') return value\n  if (value[locale] !== undefined && value[locale] !== '') return value[locale]\n  if (defaultLocale && value[defaultLocale] !== undefined && value[defaultLocale] !== '') {\n    return value[defaultLocale]\n  }\n  for (const v of Object.values(value)) {\n    if (v !== '') return v\n  }\n  return ''\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-334WSVOW.js → chunk-5FE75J4S.js}

@@ -1,16 +1,16 @@
 import {
   getHistory,
   historyIdentity
-} from "./chunk-AYX7AINO.js";
+} from "./chunk-LNSVGRHO.js";
 import {
   liveRecordIsElevated
-} from "./chunk-JMGDHKQF.js";
+} from "./chunk-FLPCETP6.js";
 import {
   openEnvelopeJson
-} from "./chunk-4ZS56W5S.js";
+} from "./chunk-EZGV6F47.js";
 import {
   ReadOnlyAtInstantError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-37EPTBBR.js";
 
 // src/with-commit/history/time-machine.ts
 var VaultInstant = class {
@@ -52,7 +52,7 @@ var CollectionInstant = class {
   async get(id) {
     const found = await this.resolveVisibleEnvelope(id);
     if (!found) return null;
-    const plaintext = this.engine.encrypted ? await openEnvelopeJson(found.ref, found.envelope, await this.engine.getDEK(this.name)) : found.envelope._data;
+    const plaintext = this.engine.encrypted ? await openEnvelopeJson(found.ref, found.envelope, await this.engine.getDEK(this.name)) : found.envelope._data ?? "";
     return JSON.parse(plaintext);
   }
   /**
@@ -208,4 +208,4 @@ export {
   VaultInstant,
   CollectionInstant
 };
-//# sourceMappingURL=chunk-334WSVOW.js.map
+//# sourceMappingURL=chunk-5FE75J4S.js.map