@noy-db/hub 0.2.0-pre.9 → 0.3.0-pre.10

package/dist/{chunk-2GLDA55J.js → chunk-BUAQ7YI3.js}

@@ -1,15 +1,20 @@
+import {
+  reducerBuilder
+} from "./chunk-DFVUTGT2.js";
 import {
   evaluateClause,
+  hasFnClause,
   readPath
-} from "./chunk-TV3YZ35S.js";
+} from "./chunk-IGJCYUT5.js";
 import {
   CrossJoinSourceUnknownError,
   CrossJoinTooLargeError,
   DanglingReferenceError,
+  FieldNotQueryableError,
   JoinTooLargeError
-} from "./chunk-B6PB7JLN.js";
+} from "./chunk-S7VFUQM2.js";
 
-// src/query/join.ts
+// src/kernel/query/join.ts
 var DEFAULT_JOIN_MAX_ROWS = 5e4;
 var JOIN_WARN_FRACTION = 0.8;
 function coerceRefKey(value) {
@@ -37,15 +42,15 @@ function warnCeilingApproaching(target, side, rows, maxRows) {
     `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ceiling for target "${target}" (${rows} rows). Streaming joins over scan() are not yet supported for collections that need to exceed this.`
   );
 }
-function applyJoins(rows, joins, context) {
+function applyJoins(rows, joins, context, locale) {
   if (joins.length === 0) return [...rows];
   let result = [...rows];
   for (const leg of joins) {
-    result = applyOneJoin(result, leg, context);
+    result = applyOneJoin(result, leg, context, locale);
   }
   return result;
 }
-function applyOneJoin(leftRows, leg, context) {
+function applyOneJoin(leftRows, leg, context, locale) {
   if (leg.isDictJoin) {
     const dictSource = context.resolveDictSource?.(leg.field);
     if (!dictSource) {
@@ -100,24 +105,27 @@ function applyOneJoin(leftRows, leg, context) {
   if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
     warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
   }
+  const effLocale = locale ?? context.defaultLocale;
+  const presentResolve = effLocale !== void 0 && source.presentForJoin !== void 0 ? (right) => right !== null && typeof right === "object" ? source.presentForJoin(right, effLocale) : right : void 0;
   const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
   if (strategy === "nested" && source.lookupById) {
     const lookup = (id) => source.lookupById?.(id);
-    return nestedLoopJoin(leftRows, leg, lookup);
+    return nestedLoopJoin(leftRows, leg, lookup, presentResolve);
   }
-  return hashJoin(leftRows, leg, rightSnapshot);
+  return hashJoin(leftRows, leg, rightSnapshot, presentResolve);
 }
-function nestedLoopJoin(leftRows, leg, lookupById) {
+function nestedLoopJoin(leftRows, leg, lookupById, presentResolve) {
   const out = [];
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : lookupById(key);
+    let right = key === null ? void 0 : lookupById(key);
+    if (presentResolve && right !== void 0) right = presentResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
 }
-function hashJoin(leftRows, leg, rightSnapshot) {
+function hashJoin(leftRows, leg, rightSnapshot, presentResolve) {
   const rightMap = /* @__PURE__ */ new Map();
   for (const record of rightSnapshot) {
     const rawId = readPath(record, "id");
@@ -130,7 +138,8 @@ function hashJoin(leftRows, leg, rightSnapshot) {
   for (const left of leftRows) {
     const rawId = readPath(left, leg.field);
     const key = coerceRefKey(rawId);
-    const right = key === null ? void 0 : rightMap.get(key);
+    let right = key === null ? void 0 : rightMap.get(key);
+    if (presentResolve && right !== void 0) right = presentResolve(right);
     out.push(attachJoin(left, leg, right, rawId));
   }
   return out;
@@ -164,7 +173,7 @@ function resetJoinWarnings() {
   warnedCeilingKeys.clear();
 }
 
-// src/query/live.ts
+// src/kernel/query/live.ts
 function buildLiveQuery(recompute, upstreams) {
   return new LiveQueryImpl(recompute, upstreams);
 }
@@ -235,7 +244,7 @@ var LiveQueryImpl = class {
   }
 };
 
-// src/aggregate/strategy.ts
+// src/with-lookup/aggregate/strategy.ts
 var NOT_ENABLED = new Error(
   'Aggregate / groupBy is not enabled on this Noydb instance. Import `{ withAggregate }` from "@noy-db/hub/aggregate" and pass it to `createNoydb({ aggregateStrategy: withAggregate() })`.'
 );
@@ -254,7 +263,7 @@ var NO_AGGREGATE = {
   }
 };
 
-// src/query/builder.ts
+// src/kernel/query/builder.ts
 var EMPTY_PLAN = {
   clauses: [],
   orderBy: [],
@@ -307,6 +316,36 @@ var Query = class _Query {
       predicates
     );
   }
+  /**
+   * @internal — the ids of records matching this query's plan,
+   * recovered by reference identity: `executePlanWithSource` returns the
+   * ORIGINAL snapshot record references (money-decode and joins are applied
+   * later, in `toArray`), so each matched record is found in the id-paired
+   * `snapshotEntries()` map. Used by `collection.retrieve({ within })`.
+   * Throws if the source is not collection-backed (no `snapshotEntries`).
+   */
+  _idArray() {
+    const entries = this.source.snapshotEntries?.();
+    if (entries === void 0) {
+      throw new Error(
+        "Query._idArray(): the query source has no snapshotEntries(); retrieve({ within }) requires a collection-backed query (collection.query())."
+      );
+    }
+    if (this.plan.clauses.some((c) => c.type === "crossJoin")) {
+      throw new Error(
+        "Query._idArray(): retrieve({ within }) does not support crossJoin queries (cross-join produces new row objects, breaking id recovery). Use where/filter/and/or, or a projection .join()."
+      );
+    }
+    const refToId = /* @__PURE__ */ new Map();
+    for (const { id, record } of entries) refToId.set(record, id);
+    const matched = executePlanWithSource(this.source, this.plan, this.joinContext);
+    const ids = [];
+    for (const r of matched) {
+      const id = refToId.get(r);
+      if (id !== void 0) ids.push(id);
+    }
+    return ids;
+  }
   /**
    * Filter by a registered deterministic predicate. Requires
    * the Query to have been augmented with a predicates map (typically
@@ -346,9 +385,37 @@ var Query = class _Query {
       this.predicates
     );
   }
-  /** Add a field comparison. Multiple where() calls are AND-combined. */
+  /**
+   * Add a field comparison. Multiple where() calls are AND-combined.
+   *
+   * A declared money field compares in MAJOR units: the operand
+   * (`10000`, `'10000.00'`, or `{ amount, currency }` in multi mode) is
+   * quantized into stored scaled-int space at build time and evaluated
+   * BigInt-exact per record. A malformed operand or a string operator
+   * (`contains`/`startsWith`) throws here, at the call site.
+   *
+   * Consults the Via pipeline's posture before building a clause (#629
+   * Task 8): a field whose posture is `queryable: 'none'` (e.g. a
+   * `blobFields` slot) throws `FieldNotQueryableError` here, at the call
+   * site. Every other posture is unaffected — the existing per-binding
+   * `buildClause` machinery runs exactly as before.
+   */
   where(field, op, value) {
-    const clause = { type: "field", field, op, value };
+    const via = this.source.via;
+    if (via?.postureFor(field)?.queryable === "none") throw new FieldNotQueryableError(field);
+    const viaClause = via?.buildClause(field, op, value);
+    const clause = viaClause ? {
+      type: "field",
+      field,
+      op,
+      value,
+      via: {
+        brand: viaClause.brand,
+        payload: viaClause.payload,
+        evaluate: (actual, evalOp) => via.evaluateClause(viaClause, actual, evalOp),
+        indexValue: via.indexProbe(viaClause, op)
+      }
+    } : { type: "field", field, op, value };
     return new _Query(
       this.source,
       { ...this.plan, clauses: [...this.plan.clauses, clause] },
@@ -414,11 +481,21 @@ var Query = class _Query {
       this.predicates
     );
   }
-  /** Sort by a field. Subsequent calls are tie-breakers. */
-  orderBy(field, direction = "asc") {
+  /**
+   * Sort by a field. Subsequent calls are tie-breakers. Pass
+   * `{ by: 'label' }` to sort a `dictKey`/`staticDict` field by its resolved
+   * label at the query locale instead of the stored code.
+   *
+   * Consults the Via pipeline's posture (#629 Task 8): a field whose posture
+   * is `queryable: 'none'` throws `FieldNotQueryableError` here, at the call
+   * site — same gate as `where()`.
+   */
+  orderBy(field, direction = "asc", opts) {
+    if (this.source.via?.postureFor(field)?.queryable === "none") throw new FieldNotQueryableError(field);
+    const entry = opts?.by === "label" ? { field, direction, by: "label" } : { field, direction };
     return new _Query(
       this.source,
-      { ...this.plan, orderBy: [...this.plan.orderBy, { field, direction }] },
+      { ...this.plan, orderBy: [...this.plan.orderBy, entry] },
       this.joinContext,
       this.aggregateStrategy,
       this.predicates
@@ -621,20 +698,44 @@ var Query = class _Query {
    * carries any join legs, they are applied after `where` / `orderBy`
    * / `limit` / `offset` narrow the left set. See the `.join()` doc
    * for the ordering rationale.
+   *
+   * `opts.locale` resolves JOINED right-side i18n fields at the
+   * `join` layer to that locale; without it, the owning collection's default
+   * locale applies, and a locale-less query leaves joined i18n fields raw.
+   * (Left/base i18n fields are resolved by `get`/`list`, not here.)
    */
-  toArray() {
-    const base = executePlanWithSource(this.source, this.plan, this.joinContext);
+  toArray(opts) {
+    const base = this.decodeVia(executePlanWithSource(this.source, this.plan, this.joinContext, opts?.locale));
     if (this.plan.joins.length === 0) return base;
     if (!this.joinContext) {
       throw new Error(
         `Query.toArray(): plan carries ${this.plan.joins.length} join leg(s) but no JoinContext is attached. This usually means the Query was constructed via the raw Query constructor with a plan that had joins pre-populated. Use collection.query().join(...) instead.`
       );
     }
-    return applyJoins(base, this.plan.joins, this.joinContext);
+    return applyJoins(base, this.plan.joins, this.joinContext, opts?.locale);
   }
-  /** Return the first matching record, or null. Joins are applied. */
-  first() {
-    const arr = this.limit(1).toArray();
+  /**
+   * Decode this source's Via-covered fields on read (e.g. money: stored
+   * scaled-int → canonical decimal), so `query().toArray()` agrees with
+   * `get()`/`sum()` on the value. No-op when the source's Via pipeline
+   * declares no result decode.
+   *
+   * The query layer carries no locale context, so money decodes with
+   * `'raw'` — canonical decimal, WITHOUT fabricating locale-formatted
+   * `<field>Formatted` / `<field>Number` virtuals. Producing a
+   * guessed-locale string here would reintroduce a "two read paths
+   * disagree" failure on the virtual field (e.g. it-IT via `get()` vs
+   * en-US here). Consumers who need formatted money read through
+   * `get()`/`list()` with a locale.
+   */
+  decodeVia(records) {
+    const via = this.source.via;
+    if (!via || !via.hasResultDecode) return records;
+    return records.map((r) => via.decodeResults(r));
+  }
+  /** Return the first matching record, or null. Joins are applied. `opts.locale` resolves joined i18n fields. */
+  first(opts) {
+    const arr = this.limit(1).toArray(opts);
     return arr[0] ?? null;
   }
   /**
@@ -657,49 +758,11 @@ var Query = class _Query {
     }
     const { candidates, remainingClauses } = candidateRecords(this.source, this.plan.clauses);
     if (remainingClauses.length === 0) return candidates.length;
-    return filterRecords(candidates, remainingClauses).length;
+    return filterRecords(candidates, remainingClauses, fnViewDecoder(this.source)).length;
   }
-  /**
-   * Reduce the matching records through a named set of reducers.
-   * the aggregation terminal.
-   *
-   * ```ts
-   * const { total, n, avgAmount } = invoices.query()
-   *   .where('status', '==', 'open')
-   *   .aggregate({
-   *     total:     sum('amount'),
-   *     n:         count(),
-   *     avgAmount: avg('amount'),
-   *   })
-   *   .run()
-   * ```
-   *
-   * Returns an `Aggregation<R>` wrapper with two terminals:
-   *   - `.run(): R` — synchronous one-shot reduction
-   *   - `.live(): LiveAggregation<R>` — reactive primitive that
-   *     re-runs the reduction whenever the source notifies of a
-   *     change. Always call `live.stop()` when finished.
-   *
-   * The reducer spec is bound here once and reused by both
-   * terminals — this is why `.aggregate()` returns a wrapper instead
-   * of being a direct terminal. Consumers who only need the static
-   * value read `.run()`; consumers wiring a reactive UI read
-   * `.live()`.
-   *
-   * Joins are intentionally NOT applied to aggregations in —
-   * the same logic as `.count()`. Joins in are projection-only
-   * (they attach an aliased field and never filter), so running
-   * them just to throw the aliases away would be wasteful. If you
-   * need a reducer that reads a joined field, open an issue —
-   * aggregations-across-joins is explicitly out of scope for v1.
-   *
-   * Every reducer factory accepts an optional `{ seed }` parameter
-   * that is plumbed through the protocol but unused by the
-   * executor — that's  constraint #2. When partition-aware
-   * aggregation lands, the seed will carry running state across
-   * partition boundaries without an API break.
-   */
-  aggregate(spec) {
+  aggregate(specOrBuild) {
+    let spec = typeof specOrBuild === "function" ? specOrBuild(reducerBuilder) : specOrBuild;
+    spec = this.source.via?.wrapReducers(spec) ?? spec;
     const source = this.source;
     const clauses = this.plan.clauses;
     const joinCtx = this.joinContext;
@@ -710,7 +773,7 @@ var Query = class _Query {
         return executeClausePipeline(source, clauses, joinCtx);
       }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
-      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
     };
     const upstreams = [];
     if (source.subscribe) {
@@ -733,7 +796,7 @@ var Query = class _Query {
         return executeClausePipeline(source, clauses, joinCtx);
       }
       const { candidates, remainingClauses } = candidateRecords(source, clauses);
-      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses);
+      return remainingClauses.length === 0 ? candidates : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
     };
     const upstreams = [];
     if (source.subscribe) {
@@ -747,13 +810,15 @@ var Query = class _Query {
         executeRecords,
         field,
         upstreams,
-        dictLabelResolver
+        dictLabelResolver,
+        this.source.via
       );
     }
     return this.aggregateStrategy.groupByN(
       executeRecords,
       fields,
-      upstreams
+      upstreams,
+      this.source.via
     );
   }
   /**
@@ -871,7 +936,7 @@ var Query = class _Query {
     return serializePlan(this.plan);
   }
 };
-function executePlanWithSource(source, plan, joinContext) {
+function executePlanWithSource(source, plan, joinContext, locale) {
   const hasCrossJoins = plan.clauses.some((c) => c.type === "crossJoin");
   let result;
   if (hasCrossJoins) {
@@ -883,10 +948,11 @@ function executePlanWithSource(source, plan, joinContext) {
     result = executeClausePipeline(source, plan.clauses, joinContext);
   } else {
     const { candidates, remainingClauses } = candidateRecords(source, plan.clauses);
-    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses);
+    result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
   }
   if (plan.orderBy.length > 0) {
-    result = sortRecords(result, plan.orderBy);
+    const labelMaps = buildOrderLabelMaps(plan.orderBy, joinContext, locale, source.via);
+    result = sortRecords(result, plan.orderBy, source.via, labelMaps);
   }
   if (plan.offset > 0) {
     result = result.slice(plan.offset);
@@ -906,11 +972,13 @@ function candidateRecords(source, clauses) {
     const clause = clauses[i];
     if (clause.type !== "field") continue;
     if (!indexes.has(clause.field)) continue;
+    if (clause.via && clause.via.indexValue === void 0) continue;
+    const probeValue = clause.via ? clause.via.indexValue : clause.value;
     let ids = null;
     if (clause.op === "==") {
-      ids = indexes.lookupEqual(clause.field, clause.value);
-    } else if (clause.op === "in" && Array.isArray(clause.value)) {
-      ids = indexes.lookupIn(clause.field, clause.value);
+      ids = indexes.lookupEqual(clause.field, probeValue);
+    } else if (clause.op === "in" && Array.isArray(probeValue)) {
+      ids = indexes.lookupIn(clause.field, probeValue);
     }
     if (ids !== null) {
       const remaining = [];
@@ -951,13 +1019,20 @@ function executePlan(records, plan) {
   }
   return result;
 }
-function filterRecords(records, clauses) {
+function fnViewDecoder(source) {
+  const via = source.via;
+  if (!via || !via.hasResultDecode) return void 0;
+  return (r) => via.decodeResults(r);
+}
+function filterRecords(records, clauses, decodeForFns) {
   if (clauses.length === 0) return [...records];
+  const needsFnView = decodeForFns !== void 0 && hasFnClause(clauses);
   const out = [];
   for (const r of records) {
+    const fnView = needsFnView ? decodeForFns(r) : void 0;
     let matches = true;
     for (const clause of clauses) {
-      if (!evaluateClause(r, clause)) {
+      if (!evaluateClause(r, clause, fnView)) {
         matches = false;
         break;
       }
@@ -969,10 +1044,11 @@ function filterRecords(records, clauses) {
 function executeClausePipeline(source, clauses, joinContext) {
   let rel = [...source.snapshot()];
   let filterBatch = [];
+  const decodeForFns = fnViewDecoder(source);
   for (const clause of clauses) {
     if (clause.type === "crossJoin") {
       if (filterBatch.length > 0) {
-        rel = filterRecords(rel, filterBatch);
+        rel = filterRecords(rel, filterBatch, decodeForFns);
         filterBatch = [];
       }
       const rightSource = joinContext.resolveSource(clause.target);
@@ -985,7 +1061,7 @@ function executeClausePipeline(source, clauses, joinContext) {
     }
   }
   if (filterBatch.length > 0) {
-    rel = filterRecords(rel, filterBatch);
+    rel = filterRecords(rel, filterBatch, decodeForFns);
   }
   return rel;
 }
@@ -1034,17 +1110,55 @@ function applyCrossJoin(leftRel, clause, rightSource) {
   }
   return expanded;
 }
-function sortRecords(records, orderBy) {
+function sortRecords(records, orderBy, via, labelMaps) {
   return [...records].sort((a, b) => {
-    for (const { field, direction } of orderBy) {
-      const av = readField(a, field);
-      const bv = readField(b, field);
-      const cmp = compareValues(av, bv);
+    for (const { field, direction, by } of orderBy) {
+      let av = readField(a, field);
+      let bv = readField(b, field);
+      const labelResolver = by === "label" ? labelMaps?.get(field) : void 0;
+      if (labelResolver) {
+        av = (typeof av === "string" ? labelResolver(av) : void 0) ?? av;
+        bv = (typeof bv === "string" ? labelResolver(bv) : void 0) ?? bv;
+        const cmp2 = compareValues(av, bv);
+        if (cmp2 !== 0) return direction === "asc" ? cmp2 : -cmp2;
+        continue;
+      }
+      const viaCmp = via?.compareForOrder(field, av, bv);
+      const cmp = viaCmp !== void 0 ? viaCmp : compareValues(av, bv);
       if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
     }
     return 0;
   });
 }
+function buildOrderLabelMaps(orderBy, joinContext, locale, via) {
+  let maps;
+  for (const { field, by } of orderBy) {
+    if (by !== "label") continue;
+    const dictSource = joinContext?.resolveDictSource?.(field);
+    if (dictSource) {
+      const loc = locale ?? dictSource.displayLocale;
+      if (loc === void 0) continue;
+      const codeToLabel = /* @__PURE__ */ new Map();
+      for (const entry of dictSource.snapshot()) {
+        const k = entry["key"];
+        const labels = entry["labels"];
+        const label = labels?.[loc];
+        if (typeof k === "string" && typeof label === "string") codeToLabel.set(k, label);
+      }
+      ;
+      (maps ??= /* @__PURE__ */ new Map()).set(field, (code) => codeToLabel.get(code));
+      continue;
+    }
+    if (via) {
+      const cache = /* @__PURE__ */ new Map();
+      (maps ??= /* @__PURE__ */ new Map()).set(field, (code) => {
+        if (!cache.has(code)) cache.set(code, via.resolveOrderLabel(field, code, locale));
+        return cache.get(code);
+      });
+    }
+  }
+  return maps;
+}
 function readField(record, field) {
   if (record === null || record === void 0) return void 0;
   if (!field.includes(".")) {
@@ -1131,6 +1245,7 @@ function buildDictLabelResolver(joinCtx, field) {
   const dictSource = joinCtx.resolveDictSource(field);
   if (!dictSource) return void 0;
   const snapshot = dictSource.snapshot();
+  const displayLocale = dictSource.displayLocale;
   const dictMap = /* @__PURE__ */ new Map();
   for (const entry of snapshot) {
     const k = entry["key"];
@@ -1140,9 +1255,11 @@ function buildDictLabelResolver(joinCtx, field) {
     }
   }
   return async (key, locale, fallback) => {
+    const effLocale = locale || displayLocale;
+    if (!effLocale) return void 0;
     const labels = dictMap.get(key);
     if (!labels) return void 0;
-    if (labels[locale] !== void 0) return labels[locale];
+    if (labels[effLocale] !== void 0) return labels[effLocale];
     const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
     for (const fb of chain) {
       if (fb === "any") {
@@ -1156,7 +1273,7 @@ function buildDictLabelResolver(joinCtx, field) {
   };
 }
 
-// src/query/scan-builder.ts
+// src/kernel/query/scan-builder.ts
 var DEFAULT_SCAN_PAGE_SIZE = 100;
 var ScanBuilder = class _ScanBuilder {
   pageProvider;
@@ -1182,12 +1299,31 @@ var ScanBuilder = class _ScanBuilder {
    * context throws with an actionable error.
    */
   joinContext;
-  constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext) {
+  /**
+   * The backing collection's compiled Via pipeline (money now; more Via
+   * features later). When it declares a result decode, yielded records
+   * are decoded (e.g. money: stored scaled-int → canonical decimal) so
+   * `scan()` agrees with `get()`/`list()`/`query().toArray()`. Decoded
+   * with `'raw'` (canonical decimal, no locale-formatted virtuals) since
+   * the scan stream carries no locale context, mirroring `Query.toArray()`.
+   */
+  via;
+  constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext, via) {
     this.pageProvider = pageProvider;
     this.pageSize = pageSize;
     this.clauses = clauses;
     this.joins = joins;
     this.joinContext = joinContext;
+    this.via = via;
+  }
+  /**
+   * Decode this scan's Via-covered fields on a record (e.g. money: stored
+   * scaled-int → canonical decimal). No-op when the Via pipeline declares
+   * no result decode. See {@link via}.
+   */
+  decodeVia(record) {
+    if (!this.via || !this.via.hasResultDecode) return record;
+    return this.via.decodeResults(record);
   }
   /**
    * Add a field comparison. Runs per record as the scan stream
@@ -1201,15 +1337,34 @@ var ScanBuilder = class _ScanBuilder {
    * the in-memory cache where indexes live. Index-accelerated scans
    * are a future optimization — the current implementation
    * evaluates clauses per record in O(1) per clause.
+   *
+   * Consults the Via pipeline's posture before building a clause (#629
+   * Task 8): a field whose posture is `queryable: 'none'` throws
+   * `FieldNotQueryableError` here, at the call site — same gate as
+   * `Query.where()`.
    */
   where(field, op, value) {
-    const clause = { type: "field", field, op, value };
+    const via = this.via;
+    if (via?.postureFor(field)?.queryable === "none") throw new FieldNotQueryableError(field);
+    const viaClause = via?.buildClause(field, op, value);
+    const clause = viaClause ? {
+      type: "field",
+      field,
+      op,
+      value,
+      via: {
+        brand: viaClause.brand,
+        payload: viaClause.payload,
+        evaluate: (actual, evalOp) => via.evaluateClause(viaClause, actual, evalOp)
+      }
+    } : { type: "field", field, op, value };
     return new _ScanBuilder(
       this.pageProvider,
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.via
     );
   }
   /**
@@ -1228,7 +1383,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.via
     );
   }
   /**
@@ -1339,7 +1495,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       this.clauses,
       [...this.joins, leg],
-      this.joinContext
+      this.joinContext,
+      this.via
     );
   }
   /**
@@ -1356,10 +1513,11 @@ var ScanBuilder = class _ScanBuilder {
     while (true) {
       for (const record of page.items) {
         if (!this.recordMatches(record)) continue;
+        const decoded = this.decodeVia(record);
         if (joinResolvers === null) {
-          yield record;
+          yield decoded;
         } else {
-          let attached = record;
+          let attached = decoded;
           for (const resolver of joinResolvers) {
             attached = this.applyOneJoinStreaming(attached, resolver);
           }
@@ -1483,43 +1641,9 @@ var ScanBuilder = class _ScanBuilder {
     }
     return merged;
   }
-  /**
-   * Reduce the scan stream through a named set of reducers and
-   * return the final aggregated shape.
-   *
-   * Memory is O(reducers): one mutable state slot per spec key.
-   * Records flow through the pipeline one at a time via
-   * `for await` and are discarded after their `step()` is applied
-   * — never collected into an array. This is the distinguishing
-   * property from `Query.aggregate()`, which materializes the full
-   * match set first.
-   *
-   * Reuses the same reducer protocol as `Query.aggregate()`,
-   * so `count()`, `sum(field)`, `avg(field)`, `min(field)`,
-   * `max(field)` all work unchanged. The `{ seed }` parameter
-   * plumbing from  constraint #2 is honored transparently — the
-   * factories ignore it in and the scan executor never
-   * touches the per-reducer state construction.
-   *
-   * **Returns a Promise**, unlike `Query.aggregate().run()` which
-   * is synchronous. The scan is inherently async because it walks
-   * adapter pages, so the terminal has to be too. Consumers
-   * destructure with await:
-   *
-   * ```ts
-   * const { total, n } = await invoices.scan()
-   *   .where('year', '==', 2025)
-   *   .aggregate({ total: sum('amount'), n: count() })
-   * ```
-   *
-   * **No `.live()` in.** `scan().aggregate().live()` would
-   * require reconciling an unbounded streaming iteration with a
-   * change-stream subscription — a design problem, not just a code
-   * one. Consumers with huge collections and live needs should
-   * narrow with `.where()` enough to fit in the 50k `query()`
-   * limit and use `query().aggregate().live()` instead.
-   */
-  async aggregate(spec) {
+  async aggregate(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) {
@@ -1545,8 +1669,9 @@ var ScanBuilder = class _ScanBuilder {
    */
   recordMatches(record) {
     if (this.clauses.length === 0) return true;
+    const fnView = this.via?.hasResultDecode && hasFnClause(this.clauses) ? this.decodeVia(record) : void 0;
     for (const clause of this.clauses) {
-      if (!evaluateClause(record, clause)) return false;
+      if (!evaluateClause(record, clause, fnView)) return false;
     }
     return true;
   }
@@ -1569,4 +1694,4 @@ export {
   executePlan,
   ScanBuilder
 };
-//# sourceMappingURL=chunk-2GLDA55J.js.map
+//# sourceMappingURL=chunk-BUAQ7YI3.js.map