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

package/dist/{chunk-NKHRDYOR.js → chunk-FQ5VRHIB.js}

@@ -4,13 +4,13 @@ import {
 import {
   buildRecordAad,
   openEnvelopeJson
-} from "./chunk-77K4PG6P.js";
+} from "./chunk-KJFW62P4.js";
 import {
   buildRecordEnvelope
-} from "./chunk-SZJ3DLZA.js";
+} from "./chunk-SEE332EV.js";
 import {
   encrypt
-} from "./chunk-SL3JAAKN.js";
+} from "./chunk-UYB234ZR.js";
 
 // src/with-audit/consent/consent.ts
 var CONSENT_AUDIT_COLLECTION = "_consent_audit";
@@ -66,4 +66,4 @@ export {
   writeConsentEntry,
   loadConsentEntries
 };
-//# sourceMappingURL=chunk-NKHRDYOR.js.map
+//# sourceMappingURL=chunk-FQ5VRHIB.js.map

package/dist/{chunk-FAHMLERK.js → chunk-FW22ZCXT.js}

@@ -1,6 +1,6 @@
 import {
   ValidationError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-audit/periods/window.ts
 var PERIODS_COLLECTION = "_periods";
@@ -23,4 +23,4 @@ export {
   PERIOD_REOPENS_COLLECTION,
   periodExclusiveUpperBound
 };
-//# sourceMappingURL=chunk-FAHMLERK.js.map
+//# sourceMappingURL=chunk-FW22ZCXT.js.map

package/dist/chunk-FXQBGFOX.js

@@ -0,0 +1,524 @@
+import {
+  bindDistinctReducers,
+  reducerBuilder
+} from "./chunk-F2TDU7MQ.js";
+import {
+  ViaPipeline
+} from "./chunk-ORDURZBU.js";
+import {
+  distinctKeyOf
+} from "./chunk-SUZKW6UR.js";
+import {
+  MaintenanceMethods
+} from "./chunk-BJ2IXQ5Q.js";
+import {
+  groupKeyName,
+  isDateTruncKey,
+  projectDateTruncKeys
+} from "./chunk-XBKH4FOC.js";
+import {
+  ScanBuilder
+} from "./chunk-F24ZZTHQ.js";
+import {
+  installMethods
+} from "./chunk-F6NCB7KT.js";
+import {
+  Query,
+  buildDictLabelResolver,
+  candidateRecords,
+  executeClausePipeline,
+  filterRecords,
+  fnViewDecoder
+} from "./chunk-7JE7BDYJ.js";
+import {
+  readPath
+} from "./chunk-HLEK5VAN.js";
+import {
+  FieldNotQueryableError,
+  GroupCardinalityError
+} from "./chunk-244VXYPG.js";
+
+// src/kernel/query/relate/join-reduce.ts
+function liftToAlias(alias, path, inner) {
+  const under = (record) => record === null || typeof record !== "object" ? void 0 : record[alias];
+  return {
+    ...inner,
+    // The dotted path, so anything reading `.field` for a label or a
+    // dependency still sees the field the CALLER named.
+    field: path,
+    init: () => inner.init(),
+    step: (state, record) => inner.step(state, under(record)),
+    ...inner.remove ? { remove: (state, record) => inner.remove(state, under(record)) } : {},
+    finalize: (state) => inner.finalize(state)
+  };
+}
+function joinAliasBinding(aliasVia) {
+  return {
+    brand: "join-alias",
+    posture: { encryptedAtRest: "envelope", queryable: "full", exportable: true, forgettable: true },
+    // Claims no field: this binding must never shadow a left-side posture.
+    covers: () => false,
+    wrapReducers: (spec) => {
+      let changed = false;
+      const out = {};
+      for (const [key, reducer] of Object.entries(spec)) {
+        const field = reducer.field;
+        const dot = field === void 0 ? -1 : field.indexOf(".");
+        const via = dot > 0 ? aliasVia.get(field.slice(0, dot)) : void 0;
+        if (!via) {
+          out[key] = reducer;
+          continue;
+        }
+        const bare = field.slice(dot + 1);
+        const wrapped = via.wrapReducers({ [key]: { ...reducer, field: bare } })[key];
+        if (wrapped === reducer || wrapped.field !== bare) {
+          out[key] = reducer;
+          continue;
+        }
+        changed = true;
+        out[key] = liftToAlias(field.slice(0, dot), field, wrapped);
+      }
+      return changed ? out : spec;
+    }
+  };
+}
+function reduceViaFor(leftVia, aliasVia) {
+  if (aliasVia === void 0 || aliasVia.size === 0) return leftVia;
+  return ViaPipeline.build([...leftVia?.bindings ?? [], joinAliasBinding(aliasVia)], leftVia?.taint);
+}
+function refuseAliasBinding(aliases) {
+  return {
+    brand: "join-alias-refuse",
+    posture: { encryptedAtRest: "envelope", queryable: "full", exportable: true, forgettable: true },
+    covers: () => false,
+    wrapReducers: (spec) => {
+      for (const reducer of Object.values(spec)) {
+        const field = reducer.field;
+        if (field === void 0) continue;
+        const head = field.split(".")[0];
+        if (!aliases.has(head)) continue;
+        throw new Error(
+          `Query.groupBy().aggregate(): reducer field "${field}" addresses the join alias "${head}", but the GROUP KEY does not \u2014 so the join legs are not applied for this grouping and the reducer would fold undefined into every bucket. Group by a field on "${head}" (then the legs run), or aggregate without grouping, where an aliased reducer is applied directly.`
+        );
+      }
+      return spec;
+    }
+  };
+}
+function refuseAliasReduceVia(leftVia, aliases) {
+  if (aliases.size === 0) return leftVia;
+  return ViaPipeline.build([...leftVia?.bindings ?? [], refuseAliasBinding(aliases)], leftVia?.taint);
+}
+
+// src/kernel/query/reduce/methods.ts
+function assertNoJoinAliasField(fields, joins, terminal) {
+  if (joins.length === 0) return;
+  const aliases = new Set(joins.map((leg) => leg.as));
+  for (const field of fields) {
+    const head = field.split(".")[0];
+    if (!aliases.has(head)) continue;
+    throw new Error(
+      `Query.${terminal}(): field "${field}" addresses the join alias "${head}", but ${terminal}() does not apply join legs \u2014 it would silently group every row under undefined. Joined aggregation is not supported. Either aggregate over the left collection's own fields, or use .crossJoin("${head}", { as: \u2026 }), whose expansion IS visible to ${terminal}().`
+    );
+  }
+}
+var ReduceMethods = class {
+  /**
+   * The right-side change streams a joined query has to merge (#1338), deduped
+   * by target the way `live()` does — a chain joining the same collection
+   * twice must not double-fire. Extracted so a joined REDUCTION and a joined
+   * live query cannot disagree on what "the sources of this result" means.
+   */
+  rightSideUpstreams() {
+    const ctx = this.joinContext;
+    if (!ctx) return [];
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const leg of this.plan.joins) {
+      if (seen.has(leg.target)) continue;
+      seen.add(leg.target);
+      const right = ctx.resolveSource(leg.target);
+      if (!right?.subscribe) continue;
+      const subscribe = right.subscribe.bind(right);
+      out.push({ subscribe: (cb) => subscribe(cb) });
+    }
+    return out;
+  }
+  /**
+   * Every alias this plan can produce, pipeline or not (#1338).
+   *
+   * `aliasVia()` above holds only the aliases whose collection compiles a Via
+   * pipeline; refusal has to know about ALL of them, or an aliased reducer
+   * over a plain right-side collection stays silent.
+   */
+  aliasNames() {
+    const out = /* @__PURE__ */ new Set();
+    for (const clause of this.plan.clauses) {
+      if (clause.type !== "crossJoin") continue;
+      out.add(clause.as);
+      if (clause.leftAs !== void 0) out.add(clause.leftAs);
+    }
+    for (const leg of this.plan.joins) out.add(leg.as);
+    return out;
+  }
+  /** Is `field` rooted at an alias this plan produces? */
+  addressesAlias(field, aliases) {
+    const dot = field.indexOf(".");
+    return dot > 0 && aliases.has(field.slice(0, dot));
+  }
+  /**
+   * The distinct values of `field` across the match set (#1347) — the
+   * declarative form of `new Set(q.toArray().map(r => r[field]))`, which is
+   * what consumers write today and which is wrong in two ways this is not.
+   *
+   * **Distinctness is decided on the canonical index key, not on the value
+   * you get back.** For a Via-covered field that is the difference between a
+   * right answer and a plausible one: money stores a scaled integer, and a
+   * row written before the field was declared can spell it non-canonically
+   * (`'0100'` for `'100'`). Deduping the stored strings reports two values
+   * where there is one; deduping the FORMATTED strings makes the answer
+   * depend on a locale this layer does not have (`'10.00'` vs `'10,00'`).
+   * See `distinct-key.ts`. The values RETURNED are the decoded ones, so they
+   * match what `toArray()` hands back for the same field.
+   *
+   * **Nullish values are excluded** — `null`/`undefined`/missing is the
+   * absence of a value, not a distinct one. That is also the only choice
+   * under which the index-backed and scanned paths can agree, since the hash
+   * index does not hold nullish keys; see `distinctKeyOf`.
+   *
+   * Same match set as `count()`: where/filter apply, orderBy/limit/offset do
+   * not. Values come back in first-encountered order.
+   *
+   * ⭐ INDEX-BACKED when the field carries a hash index AND the plan narrows
+   * nothing — the buckets ARE the distinct key set, so the answer costs
+   * O(distinct values) instead of O(records) and never decrypts a snapshot.
+   * The guard is deliberately all-or-nothing: with a where clause the whole
+   * collection's buckets are not the answer, and intersecting a candidate id
+   * set with every bucket would cost more than the scan it replaced.
+   *
+   * ⛔ THE RETURN TYPE IS `(T & Record<F, unknown>)[F][]`, NOT
+   * `F extends keyof T ? T[F][] : unknown[]` — and it must stay that way. The
+   * conditional form reads better and type-checks at every call site, but a
+   * DEFERRED conditional over `T` makes TypeScript give up relating
+   * `Query<T>` to `Query<unknown>`, which makes `Collection<T>` invariant in
+   * `T`, which breaks `vault.ts`'s `Map<string, Collection<unknown>>` cache
+   * with four errors that name neither this method nor this file. The
+   * intersection form resolves to the same thing (`T[F]` for a literal key,
+   * `unknown` for a `string`-typed one) and stays covariant.
+   */
+  distinct(field) {
+    const name = field;
+    assertNoJoinAliasField([name], this.plan.joins, "distinct");
+    const via = this.source.via;
+    if (via?.postureFor(name)?.queryable === "none") throw new FieldNotQueryableError(name);
+    const decode = via?.hasResultDecode ? (r) => via.decodeResults(r) : (r) => r;
+    const indexes = this.plan.clauses.length === 0 && this.plan.joins.length === 0 ? this.source.getIndexes?.() : void 0;
+    if (indexes && this.source.lookupById) {
+      const lookupById = (id) => this.source.lookupById?.(id);
+      const reps = indexes.bucketRepresentatives(name);
+      if (reps) {
+        const fromIndex = [];
+        for (const id of reps) {
+          const record = lookupById(id);
+          if (record === void 0) continue;
+          fromIndex.push(readPath(decode(record), name));
+        }
+        return fromIndex;
+      }
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const record of this.matchedRecords("distinct")) {
+      const key = distinctKeyOf(name, readPath(record, name), via);
+      if (key === void 0 || seen.has(key)) continue;
+      seen.add(key);
+      out.push(readPath(decode(record), name));
+    }
+    return out;
+  }
+  aggregate(specOrBuild) {
+    let spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    const aliases = this.aliasNames();
+    const aliasedReducer = this.plan.joins.length > 0 && Object.values(spec).some((r) => {
+      const f = r.field;
+      return typeof f === "string" && this.addressesAlias(f, aliases);
+    });
+    spec = (aliasedReducer ? reduceViaFor(this.source.via, this.aliasVia()) : this.source.via)?.wrapReducers(spec) ?? spec;
+    spec = bindDistinctReducers(spec, this.source.via);
+    const source = this.source;
+    const clauses = this.plan.clauses;
+    const joinCtx = this.joinContext;
+    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
+    const fullScan = aliasedReducer ? () => this.matchedRecords("aggregate", true) : () => {
+      if (hasCrossJoins) {
+        if (!joinCtx) throw new Error("Query.aggregate(): crossJoin requires a join context");
+        return executeClausePipeline(source, clauses, joinCtx);
+      }
+      const { candidates, remainingClauses } = candidateRecords(source, clauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
+    };
+    const maintainer = this.incrementalMaintainer("records");
+    const executeRecords = maintainer ? () => maintainer.rows() : fullScan;
+    const upstreams = [];
+    if (aliasedReducer) upstreams.push(...this.rightSideUpstreams());
+    if (source.subscribe) {
+      const subscribe = source.subscribe.bind(source);
+      upstreams.push(
+        maintainer ? {
+          // The maintainer folds the delta in BEFORE the reduction reads,
+          // which is why it is wrapped here rather than subscribed
+          // separately — emitter callback order would otherwise decide
+          // whether the reduction saw the new record.
+          subscribe: (cb) => {
+            maintainer.attach();
+            const unsubscribe = subscribe((change) => {
+              try {
+                maintainer.apply(change);
+              } catch {
+                maintainer.invalidate();
+              }
+              cb();
+            });
+            return () => {
+              maintainer.detach();
+              unsubscribe();
+            };
+          }
+        } : { subscribe: (cb) => subscribe(cb) }
+      );
+    }
+    return this.reduceStrategy.aggregate(executeRecords, spec, upstreams, this.source.hydration);
+  }
+  groupBy(...keys) {
+    if (keys.length === 0) {
+      throw new Error(".groupBy() requires at least one field");
+    }
+    const derived = keys.filter(isDateTruncKey);
+    const fields = keys.map(groupKeyName);
+    const aliases = this.aliasNames();
+    const keyIsAliased = this.plan.joins.length > 0 && fields.some((f) => this.addressesAlias(f, aliases));
+    const source = this.source;
+    const clauses = this.plan.clauses;
+    const joinCtx = this.joinContext;
+    const hasCrossJoins = clauses.some((c) => c.type === "crossJoin");
+    const executeRecords = keyIsAliased ? () => this.matchedRecords("groupBy", true) : () => {
+      if (hasCrossJoins) {
+        if (!joinCtx) throw new Error("Query.groupBy(): crossJoin requires a join context");
+        return executeClausePipeline(source, clauses, joinCtx);
+      }
+      const { candidates, remainingClauses } = candidateRecords(source, clauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
+    };
+    const executeGroupRecords = derived.length === 0 ? executeRecords : () => projectDateTruncKeys(executeRecords(), derived);
+    const upstreams = [];
+    if (source.subscribe) {
+      const subscribe = source.subscribe.bind(source);
+      upstreams.push({ subscribe: (cb) => subscribe(cb) });
+    }
+    if (keyIsAliased) upstreams.push(...this.rightSideUpstreams());
+    const maintenance = keyIsAliased ? void 0 : this.groupMaintenance(derived);
+    const reduceVia = keyIsAliased ? reduceViaFor(this.source.via, this.aliasVia()) : refuseAliasReduceVia(this.source.via, aliases);
+    if (fields.length === 1) {
+      const field = fields[0];
+      const dictLabelResolver = derived.length > 0 ? void 0 : buildDictLabelResolver(this.joinContext, field);
+      return this.reduceStrategy.groupBy(
+        executeGroupRecords,
+        field,
+        upstreams,
+        dictLabelResolver,
+        reduceVia,
+        maintenance
+      );
+    }
+    return this.reduceStrategy.groupByN(
+      executeGroupRecords,
+      fields,
+      upstreams,
+      reduceVia,
+      maintenance
+    );
+  }
+  /**
+   * SQL window functions over the query's result rows (#1349) — terminate with
+   * `.select(spec)`.
+   *
+   * ```ts
+   * invoices.query()
+   *   .where('status', '==', 'open')
+   *   .window({ partitionBy: 'clientId', orderBy: 'date' })
+   *   .select({ balance: runningSum('amount'), prev: lag('amount', 1), n: rowNumber() })
+   *   .run()
+   * ```
+   *
+   * ⭐ Distinguished from `.groupBy()` by ARITY, not by capability: grouping
+   * emits one row per bucket and drops the source rows; a window keeps EVERY
+   * row and attaches per-row values computed over its partition.
+   *
+   * **The record set is `toArray()`'s** — the full pipeline, including joins,
+   * `orderBy`, `offset`/`limit` and the Via decode. That differs deliberately
+   * from `.groupBy()`, which reads the candidate/filter pipeline only: a
+   * window returns ROWS, so the query's own ordering and paging are exactly
+   * what decides which rows there are and how they are presented. `orderBy`
+   * inside the window decides only how a partition is WALKED.
+   *
+   * **Frame:** `rows unbounded preceding → current row`, and only that in v1.
+   *
+   * `partitionBy` / `orderBy` accept a `dateTrunc()` key (#1350) alongside
+   * plain field names; the derived bucket is used for partitioning and is not
+   * stamped on the output row. A sealed (`sensitive`) field is refused at
+   * compile time, same as `.groupBy()`.
+   *
+   * ⛔ **Not an `explain()` node.** `explain()` is a terminal on `Query`;
+   * `.window()` leaves `Query` for `WindowedQuery`, so there is nothing past
+   * here to add a node to — the same reason #1336's post-group ops are absent.
+   */
+  window(spec) {
+    const upstreams = [];
+    if (this.source.subscribe) {
+      const subscribe = this.source.subscribe.bind(this.source);
+      upstreams.push({ subscribe: (cb) => subscribe(cb) });
+    }
+    return this.reduceStrategy.window(
+      () => this.toArray(),
+      spec,
+      upstreams,
+      this.source.via
+    );
+  }
+};
+
+// src/kernel/query/reduce/scan-methods.ts
+var ScanReduceMethods = class {
+  async aggregate(specOrBuild) {
+    if (Array.isArray(specOrBuild)) return this.aggregateMany(specOrBuild);
+    const spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    this.via?.refuseUnqueryableReducers(spec);
+    const keys = Object.keys(spec);
+    const state = {};
+    for (const key of keys) {
+      state[key] = spec[key].init();
+    }
+    for await (const record of this) {
+      for (const key of keys) {
+        state[key] = spec[key].step(state[key], record);
+      }
+    }
+    const result = {};
+    for (const key of keys) {
+      result[key] = spec[key].finalize(state[key]);
+    }
+    return result;
+  }
+  /**
+   * The multi-spec `.aggregate([specA, specB, …])` executor (#1340).
+   *
+   * One iteration of the scan, `Σ|spec|` reducer states — memory stays
+   * O(reducers) exactly as the single-spec terminal's does, with the sum taken
+   * across specs instead of within one. Every spec's state is stepped from the
+   * SAME yielded record, so the page provider is read once per page.
+   *
+   * Semantics per spec are identical to the single-spec form, deliberately:
+   * the posture gate is `refuseUnqueryableReducers` (metadata only), NOT the
+   * full `wrapReducers` — so `aggregate([a, b])` returns exactly what
+   * `aggregate(a)` and `aggregate(b)` return, and the array form is a pure
+   * cost optimisation with no behavioural delta to reason about. (The grouped
+   * scan path DOES wrap — it has to agree with the eager grouped path, which
+   * wraps. See `scan-groupby.ts`.)
+   */
+  async aggregateMany(specs) {
+    for (const spec of specs) this.via?.refuseUnqueryableReducers(spec);
+    const keysPerSpec = specs.map((spec) => Object.keys(spec));
+    const states = specs.map((spec, i) => {
+      const state = {};
+      for (const key of keysPerSpec[i]) state[key] = spec[key].init();
+      return state;
+    });
+    for await (const record of this) {
+      for (let i = 0; i < specs.length; i++) {
+        const spec = specs[i];
+        const state = states[i];
+        for (const key of keysPerSpec[i]) state[key] = spec[key].step(state[key], record);
+      }
+    }
+    return specs.map((spec, i) => {
+      const result = {};
+      for (const key of keysPerSpec[i]) result[key] = spec[key].finalize(states[i][key]);
+      return result;
+    });
+  }
+  groupBy(key, opts) {
+    return new ScanGroupedScan(
+      this,
+      key,
+      opts?.maxGroups ?? SCAN_GROUPBY_DEFAULT_MAX_GROUPS,
+      this.via
+    );
+  }
+};
+var SCAN_GROUPBY_DEFAULT_MAX_GROUPS = 1e5;
+function scanGroupKey(field, value) {
+  return `${field}=${value === void 0 ? "undefined" : JSON.stringify(value)}`;
+}
+var ScanGroupedScan = class {
+  constructor(stream, key, maxGroups, via) {
+    this.stream = stream;
+    this.key = key;
+    this.maxGroups = maxGroups;
+    this.via = via;
+    if (!Number.isInteger(maxGroups) || maxGroups < 1) {
+      throw new Error(
+        `scan().groupBy(): { maxGroups: ${String(maxGroups)} } must be a positive integer \u2014 it is the declared ceiling on how many reducer states the grouped scan may hold.`
+      );
+    }
+  }
+  stream;
+  key;
+  maxGroups;
+  via;
+  async aggregate(specOrBuild) {
+    const raw = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    const spec = bindDistinctReducers(this.via ? this.via.wrapReducers(raw) : raw, this.via);
+    const keys = Object.keys(spec);
+    const field = groupKeyName(this.key);
+    const derived = isDateTruncKey(this.key) ? [this.key] : [];
+    const groups = /* @__PURE__ */ new Map();
+    for await (const record of this.stream) {
+      const row = derived.length === 0 ? record : projectDateTruncKeys([record], derived)[0];
+      const keyValue = readPath(row, field);
+      const dedupKey = scanGroupKey(field, keyValue);
+      let group = groups.get(dedupKey);
+      if (group === void 0) {
+        if (groups.size >= this.maxGroups) {
+          throw new GroupCardinalityError(field, groups.size + 1, this.maxGroups, "scan");
+        }
+        const state = {};
+        for (const k of keys) state[k] = spec[k].init();
+        group = { keyValue, state };
+        groups.set(dedupKey, group);
+      }
+      for (const k of keys) group.state[k] = spec[k].step(group.state[k], row);
+    }
+    const out = [];
+    for (const group of groups.values()) {
+      const outRow = { [field]: group.keyValue };
+      for (const k of keys) outRow[k] = spec[k].finalize(group.state[k]);
+      out.push(outRow);
+    }
+    return out;
+  }
+};
+
+// src/kernel/query/reduce/install.ts
+var done = false;
+function installReduce() {
+  if (done) return;
+  done = true;
+  installMethods(Query.prototype, MaintenanceMethods);
+  installMethods(Query.prototype, ReduceMethods);
+  installMethods(ScanBuilder.prototype, ScanReduceMethods);
+}
+
+export {
+  installReduce
+};
+//# sourceMappingURL=chunk-FXQBGFOX.js.map