@objectstack/service-analytics 17.2.0 → 17.3.0

package/dist/index.js

@@ -1,7 +1,14 @@
 // src/analytics-service.ts
 import { percentScaleOf } from "@objectstack/spec/data";
 import { resolveI18nLabel as resolveI18nLabel2 } from "@objectstack/spec/ui";
-import { createLogger, getEnv, bucketKeyToCalendarRange as bucketKeyToCalendarRange2, zonedDateStartToUtcMs } from "@objectstack/core";
+import {
+  createLogger,
+  getEnv,
+  bucketKeyToCalendarRange as bucketKeyToCalendarRange2,
+  zonedDateStartToUtcMs,
+  filterTokenContextFrom as filterTokenContextFrom2,
+  resolveFilterTokens as resolveFilterTokens2
+} from "@objectstack/core";
 import { matchMissingColumnOfRelation } from "@objectstack/types";
 
 // src/cube-registry.ts
@@ -687,6 +694,53 @@ function compileScopedFilterToSql(filter, alias) {
   const sql = compileNode(filter, quotedAlias, params);
   return { sql, params };
 }
+function emptyMembershipFinding(spec, negated, path) {
+  if (Array.isArray(spec)) {
+    return spec.length === 0 && negated ? { path: `${path}: []`, kind: "negatedIn" } : null;
+  }
+  if (spec === null || typeof spec !== "object") return null;
+  const rec = spec;
+  if (Array.isArray(rec.$nin) && rec.$nin.length === 0) return { path: `${path}.$nin`, kind: "nin" };
+  if (Array.isArray(rec.$in) && rec.$in.length === 0 && negated) {
+    return { path: `${path}.$in`, kind: "negatedIn" };
+  }
+  return null;
+}
+function findEmptyMembership(node, negated, path) {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) return null;
+  const rec = node;
+  const bare = emptyMembershipFinding(rec, negated, path.length > 0 ? path : "<root>");
+  if (bare) return bare;
+  for (const [key, value] of Object.entries(rec)) {
+    const here = path.length > 0 ? `${path}.${key}` : key;
+    if (key === "$not") {
+      const found = findEmptyMembership(value, !negated, here);
+      if (found) return found;
+    } else if (key === "$and" || key === "$or") {
+      if (!Array.isArray(value)) continue;
+      for (let i = 0; i < value.length; i++) {
+        const found = findEmptyMembership(value[i], negated, `${here}[${i}]`);
+        if (found) return found;
+      }
+    } else if (!key.startsWith("$")) {
+      const found = emptyMembershipFinding(value, negated, here);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+function assertReadScopeCannotVacate(scope, objectName) {
+  const found = findEmptyMembership(scope, false, "");
+  if (found === null) return;
+  if (found.kind === "nin") {
+    throw readScopeCompileError(
+      `[read-scope-sql] read scope for "${objectName}" has an empty $nin at ${found.path} \u2014 an empty exclusion excludes nothing, so the engine lowers that clause to constant TRUE and the scope does not bind as written. Refused at every polarity, matching this module's own $nin arm (fail-closed).`
+    );
+  }
+  throw readScopeCompileError(
+    `[read-scope-sql] read scope for "${objectName}" has an empty $in under negation at ${found.path} \u2014 an empty membership matches nothing, so its negation matches every row and the read scope admits the whole table (fail-closed).`
+  );
+}
 function compileSub(node, qAlias) {
   const params = [];
   const sql = compileNode(node, qAlias, params);
@@ -848,7 +902,7 @@ function compileOperator(col, op, val, field, params) {
     }
     case "$nin": {
       if (!Array.isArray(val)) throw readScopeCompileError(`[read-scope-sql] $nin for "${field}" needs an array (fail-closed).`);
-      if (val.length === 0) return "1 = 1";
+      if (val.length === 0) throw readScopeCompileError(`[read-scope-sql] $nin for "${field}" is empty \u2014 an empty exclusion excludes nothing and would compile the read scope to constant TRUE (fail-closed).`);
       assertCompilableMembers(op, field, val);
       return nullSafeNegative(col, `${col} NOT IN (${val.map((v) => bind(params, v)).join(", ")})`);
     }
@@ -1327,6 +1381,7 @@ var NativeSQLStrategy = class {
     const filter = ctx.getReadScope(objectName);
     if (filter === void 0 || filter === null) return;
     const { sql, params: scopeParams } = compileScopedFilterToSql(filter, alias);
+    assertReadScopeCannotVacate(filter, objectName);
     if (!sql) return;
     let i = 0;
     const rendered = sql.replace(/\?/g, () => {
@@ -1780,11 +1835,16 @@ var ObjectQLStrategy = class {
     for (const [dim, gran] of granByDim) {
       groupBy.push({ field: this.resolveFieldName(cube, dim, "dimension"), dateGranularity: gran });
     }
+    const datasetScope = ctx.getDatasetScope?.(query.cube);
     const aggregations = [];
     if (query.measures && query.measures.length > 0) {
       for (const measure of query.measures) {
         const { field, method } = this.resolveMeasureAggregation(cube, measure);
-        aggregations.push({ field, method, alias: measure });
+        const measureFilter = datasetScope?.measureFilters?.[measure];
+        const filterCondition = measureFilter ? this.filterNodeToCondition(normalizeAnalyticsFilterTree({ where: measureFilter }), cube) : null;
+        aggregations.push(
+          filterCondition ? { field, method, alias: measure, filter: filterCondition } : { field, method, alias: measure }
+        );
       }
     }
     const filter = {};
@@ -1794,7 +1854,6 @@ var ObjectQLStrategy = class {
       const extra = this.mergeFilterOperand(filter, field, bounds);
       if (extra) conjuncts.push(extra);
     }
-    const datasetScope = ctx.getDatasetScope?.(query.cube);
     if (datasetScope?.filter) {
       const scopeCondition = this.filterNodeToCondition(
         normalizeAnalyticsFilterTree({ where: datasetScope.filter }),
@@ -1883,6 +1942,7 @@ var ObjectQLStrategy = class {
     }
     const tableName = this.extractObjectName(cube);
     const plan = this.planCrossObject(cube, query, this.filterMemberView(cube, query, ctx));
+    const datasetScope = ctx.getDatasetScope?.(query.cube);
     const crossByDim = new Map((plan?.crossDims ?? []).map((cd) => [cd.outputName, cd]));
     const joinClauses = [];
     const dimExpr = (dim) => {
@@ -1913,7 +1973,9 @@ var ObjectQLStrategy = class {
     if (query.measures) {
       for (const m of query.measures) {
         const { field, method } = this.resolveMeasureAggregation(cube, m);
-        const aggSql = method === "count" ? "COUNT(*)" : method === "count_distinct" ? `COUNT(DISTINCT ${field})` : `${method.toUpperCase()}(${field})`;
+        const measureFilter = datasetScope?.measureFilters?.[m];
+        const predicate = measureFilter ? this.renderFilterNodeSql(normalizeAnalyticsFilterTree({ where: measureFilter }), cube, params) : null;
+        const aggSql = predicate ? this.conditionalAggregateSql(method, field, predicate) : method === "count" ? "COUNT(*)" : method === "count_distinct" ? `COUNT(DISTINCT ${field})` : `${method.toUpperCase()}(${field})`;
         selectParts.push(`${aggSql} AS "${m}"`);
       }
     }
@@ -1924,10 +1986,9 @@ var ObjectQLStrategy = class {
       params
     );
     if (filterClause) whereParts.push(filterClause);
-    const echoedDatasetFilter = ctx.getDatasetScope?.(query.cube)?.filter;
-    if (echoedDatasetFilter) {
+    if (datasetScope?.filter) {
       const scopeSql = this.renderFilterNodeSql(
-        normalizeAnalyticsFilterTree({ where: echoedDatasetFilter }),
+        normalizeAnalyticsFilterTree({ where: datasetScope.filter }),
         cube,
         params
       );
@@ -1943,6 +2004,7 @@ var ObjectQLStrategy = class {
     const scope = ctx.getReadScope?.(tableName);
     if (scope != null) {
       const { sql: scopeSql, params: scopeParams } = compileScopedFilterToSql(scope, tableName);
+      assertReadScopeCannotVacate(scope, tableName);
       if (scopeSql) {
         let i = 0;
         const rendered = scopeSql.replace(/\?/g, () => {
@@ -1989,6 +2051,7 @@ var ObjectQLStrategy = class {
     if (typeof ctx.getReadScope !== "function") return userFilter;
     const scope = ctx.getReadScope(objectName);
     if (scope === void 0 || scope === null) return userFilter;
+    assertReadScopeCannotVacate(scope, objectName);
     const scopeFilter = markFilterSubtreeProvenance(scope, "policy");
     if (!userFilter) return scopeFilter;
     return { $and: [userFilter, scopeFilter] };
@@ -2017,7 +2080,7 @@ var ObjectQLStrategy = class {
    * the members inside were unreadable from the outside and the envelope check
    * could not reject what it could not see.
    *
-   * ## Two producers, one inventory (#10861)
+   * ## Three producers, one inventory (#10861, #11461)
    *
    * The caller's `where` is not the only thing that reaches `engine.aggregate`
    * as a predicate. Since PR #10758 the compiled dataset's own definition-level
@@ -2032,6 +2095,36 @@ var ObjectQLStrategy = class {
    * which driver will serve the dataset and would refuse a dataset that is
    * perfectly legal on a native-SQL deployment.
    *
+   * [#11461] #10413 phase 2 then added a THIRD producer with the same reach and
+   * none of the coverage: a compiled measure's own `filter`, lowered onto that
+   * measure's `aggregations[].filter` entry (#10576). This view enumerated two
+   * origins, so the third was invisible to the envelope check and the arm of
+   * `planCrossObject` that inspects `query.measures` reads only each measure's
+   * resolved FIELD, never its filter. Measured on the unfixed tree, one fixture,
+   * both doors:
+   *
+   * ```
+   * BEFORE  execute()     ACCEPTED -> aggregations: [{field:"*",method:"count",
+   *                                   alias:"west_count",
+   *                                   filter:{"account.region":"West"}}]
+   *                                -> rows [{stage:"won",total_count:3,west_count:0}]
+   *                                   (the truthful west_count is 2; total_count
+   *                                    is right, so the wrong number arrived in
+   *                                    the same response shape as the right one)
+   *         generateSql() ACCEPTED -> COUNT(CASE WHEN account.region = $1 THEN 1 END)
+   *                                   over a FROM with no join in it at all
+   * AFTER   both doors    REFUSED   INVALID_FIELD / 400, engine never reached
+   * ```
+   *
+   * The same maintainer ruling covers it — same hazard, same physical verdict,
+   * one more producer — so it folds in HERE for the #10861 reason and not into
+   * `dataset-compiler.ts`, which still cannot see which driver will serve the
+   * dataset. Only the REQUESTED measures are folded: both doors' aggregation
+   * loops read `measureFilters[m]` for `m of query.measures` and nothing else,
+   * so a filter declared on a measure this query never asks for reaches no
+   * engine, and refusing on it would reject a query for a member that was never
+   * going to be evaluated.
+   *
    * Structure is discarded on purpose — a member is cross-object or it is not,
    * and which branch of a disjunction it sits in cannot make
    * `engine.aggregate` able to join it. PROVENANCE is not discarded, because it
@@ -2041,9 +2134,12 @@ var ObjectQLStrategy = class {
    * `planCrossObject`. The value slot carries that and nothing else; it never
    * reaches a driver.
    *
-   * Dataset leaves are inserted FIRST so a member named by BOTH producers keeps
-   * the caller's provenance (last write wins on a duplicate key): if it is in
-   * the request too, the request is the actionable place to fix it.
+   * Insertion order is measure-filter, then dataset-filter, then `where`, and
+   * last write wins on a duplicate key. Two things follow, in that order of
+   * importance. A member named by the request too keeps the CALLER's provenance,
+   * because if it is in the request that is the actionable place to fix it. And
+   * every shape that was refused before #11461 keeps the exact message it had:
+   * the new origin can only ever win a key no older producer names.
    *
    * Time-dimension WINDOWS are deliberately absent (they live in
    * `dateRangeBounds`, not in `where`). They need no arm here: a cross-object
@@ -2053,13 +2149,21 @@ var ObjectQLStrategy = class {
    * diagnostic and the reason that loop runs first.
    */
   filterMemberView(cube, query, ctx) {
-    const datasetFilter = ctx.getDatasetScope?.(query.cube)?.filter;
+    const datasetScope = ctx.getDatasetScope?.(query.cube);
     const leaves = (node, origin) => collectFilterLeaves(node).map(
       (f) => [this.resolveFieldName(cube, f.member, "any"), origin]
     );
+    const measureLeaves = (query.measures ?? []).flatMap((m) => {
+      const measureFilter = datasetScope?.measureFilters?.[m];
+      return measureFilter ? leaves(
+        normalizeAnalyticsFilterTree({ where: measureFilter }),
+        { kind: "measure-filter", measure: m }
+      ) : [];
+    });
     return Object.fromEntries([
-      ...datasetFilter ? leaves(normalizeAnalyticsFilterTree({ where: datasetFilter }), "dataset-filter") : [],
-      ...leaves(normalizeAnalyticsFilterTree(query), "where")
+      ...measureLeaves,
+      ...datasetScope?.filter ? leaves(normalizeAnalyticsFilterTree({ where: datasetScope.filter }), { kind: "dataset-filter" }) : [],
+      ...leaves(normalizeAnalyticsFilterTree(query), { kind: "where" })
     ]);
   }
   /**
@@ -2074,18 +2178,20 @@ var ObjectQLStrategy = class {
    * THROWS for anything outside the envelope — a cross-object MEASURE or FILTER
    * (needs a real join to evaluate), a cross-object leaf in the DATASET's own
    * definition-level `filter` (#10861 — same join it does not have, arriving
-   * from the producer PR #10758 added), a MULTI-HOP dimension (`a.b.c`), or a
-   * non-recombinable measure (`avg`/`count_distinct`, whose sub-bucket values
-   * cannot be merged). A loud error beats the silent mis-bucket #3654 kills.
+   * from the producer PR #10758 added), a cross-object leaf in ONE MEASURE's own
+   * `filter` (#11461 — the same join again, arriving from the producer #10413
+   * phase 2 added), a MULTI-HOP dimension (`a.b.c`), or a non-recombinable
+   * measure (`avg`/`count_distinct`, whose sub-bucket values cannot be merged).
+   * A loud error beats the silent mis-bucket #3654 kills.
    * `generateSql()` calls this too, so the preview accepts/rejects the same set
    * — and since #10759 both callers derive `filter` from the one
    * {@link filterMemberView}, so that sentence is enforced by construction
    * instead of restated at two call sites.
    *
-   * [#5716] All five refusals below are `invalidMemberError` — `INVALID_FIELD` /
+   * [#5716] All six refusals below are `invalidMemberError` — `INVALID_FIELD` /
    * 400, naming the member — and the four that predate #10861 keep their
    * MESSAGES unchanged (they are good diagnostics, and #5923's tests read
-   * them). Each is decided by two facts and nothing else: a member that will
+   * them); so does #10861's own, which #11461 left untouched beside it. Each is decided by two facts and nothing else: a member that will
    * reach the engine's predicate, and whether that member resolves across a
    * join. Neither is an internal invariant — a cube where the member exists and
    * a driver that could serve it are both perfectly ordinary, which is exactly
@@ -2094,14 +2200,15 @@ var ObjectQLStrategy = class {
    * because the fix is always to change or drop ONE named member, and because
    * four of them fire on `/analytics/query` where no dataset exists.
    *
-   * [#10861] The fifth is the exception that proves the rule and is written to
-   * it: it can only fire where a dataset DOES exist, and it is the one refusal
-   * here whose member no request key named — so it carries `cube` and no
-   * `param`, and says in its own words which document to go and edit. It stays
+   * [#10861, #11461] The fifth and sixth are the exceptions that prove the rule
+   * and are written to it: they can only fire where a dataset DOES exist, and
+   * they are the two refusals here whose member no request key named — so each
+   * carries `cube` and no `param`, and says in its own words which document to
+   * go and edit, the sixth naming the MEASURE inside it as well. Both stay
    * `INVALID_FIELD` rather than becoming `DATASET_INVALID` because the verdict
-   * is the same physical one as its neighbour — this engine cannot join this
+   * is the same physical one as their neighbours — this engine cannot join this
    * member — and splitting the code by PROVENANCE would make a caller branch on
-   * two wire shapes for one capability limit.
+   * three wire shapes for one capability limit.
    *
    * Detection is on RESOLVED field names, so a dotted dimension the cube
    * flattens to a real column is treated as base, not cross-object.
@@ -2123,7 +2230,7 @@ var ObjectQLStrategy = class {
         member: m,
         field: this.resolveMeasureAggregation(cube, m).field
       })),
-      ...Object.entries(filter).filter(([, origin]) => origin === "where").map(([f]) => ({ where: "filter", member: f, field: f }))
+      ...Object.entries(filter).filter(([, origin]) => origin.kind === "where").map(([f]) => ({ where: "filter", member: f, field: f }))
     ].filter((r) => this.isCrossObjectField(cube, r.field, baseObject));
     if (nonDim.length > 0) {
       throw invalidMemberError(
@@ -2137,13 +2244,23 @@ var ObjectQLStrategy = class {
         }
       );
     }
-    const scopeCross = Object.entries(filter).filter(([field, origin]) => origin === "dataset-filter" && this.isCrossObjectField(cube, field, baseObject)).map(([field]) => field);
+    const scopeCross = Object.entries(filter).filter(([field, origin]) => origin.kind === "dataset-filter" && this.isCrossObjectField(cube, field, baseObject)).map(([field]) => field);
     if (scopeCross.length > 0) {
       throw invalidMemberError(
         `[Analytics] ObjectQLStrategy cannot evaluate the cross-object filter ("${scopeCross[0]}") that dataset "${cube.name}" declares at its definition level \u2014 the engine cannot join in an aggregate, so this predicate matches nothing and the answer would be neither the scoped number nor the unscoped one. Nothing in the request names it: remove the cross-object leaf from the dataset's own \`filter\`, or serve this dataset on a native-SQL driver, where the same definition is valid.`,
         { member: scopeCross[0], cube: cube.name }
       );
     }
+    const measureCross = Object.entries(filter).flatMap(
+      ([field, origin]) => origin.kind === "measure-filter" && this.isCrossObjectField(cube, field, baseObject) ? [{ field, measure: origin.measure }] : []
+    );
+    if (measureCross.length > 0) {
+      const { field, measure } = measureCross[0];
+      throw invalidMemberError(
+        `[Analytics] ObjectQLStrategy cannot evaluate the cross-object filter ("${field}") that dataset "${cube.name}" declares on its measure "${measure}" \u2014 the engine cannot join in an aggregate, so this measure would be counted over a predicate that matches nothing and would answer 0 rather than the scoped number. Remove the cross-object leaf from that measure's own \`filter\`, or serve this dataset on a native-SQL driver, where the same definition is valid.`,
+        { member: field, cube: cube.name }
+      );
+    }
     const crossDims = [];
     for (const dim of query.dimensions ?? []) {
       const field = this.resolveFieldName(cube, dim, "dimension");
@@ -2247,6 +2364,7 @@ var ObjectQLStrategy = class {
     if (fkValues.length === 0 || typeof ctx.executeAggregate !== "function") return map;
     const idFilter = { id: { $in: fkValues } };
     const scope = typeof ctx.getReadScope === "function" ? ctx.getReadScope(refObject) : null;
+    if (scope != null) assertReadScopeCannotVacate(scope, refObject);
     if (scope != null) markFilterSubtreeProvenance(scope, "policy");
     const filter = scope != null ? { $and: [idFilter, scope] } : idFilter;
     const rows = await ctx.executeAggregate(refObject, {
@@ -2260,6 +2378,45 @@ var ObjectQLStrategy = class {
     }
     return map;
   }
+  /**
+   * A measure's aggregate, restricted to the rows its own `filter` admits
+   * (#10413 phase 2) — the same six functions `generateSql`'s unconditional
+   * branch renders, wrapped in a `CASE WHEN`.
+   *
+   * Spelled `CASE WHEN` rather than SQL-standard `FILTER (WHERE …)`, mirroring
+   * `NativeSQLStrategy.CONDITIONAL_AGGREGATE_SQL`: this string is DOCUMENTATION
+   * of an execution that really goes through `engine.aggregate`'s per-driver
+   * `aggregations[].filter` lowering (#10576), not a statement this class runs
+   * itself, so there is no reason to pick a dialect-restricted spelling over
+   * the portable one the SQL-executing sibling already settled on.
+   *
+   * `count` over `*` counts a constant (`COUNT(CASE WHEN p THEN 1 END)`, since
+   * `COUNT(CASE WHEN p THEN * END)` is not valid SQL); over a real column it
+   * counts that column's non-null values among the admitted rows.
+   */
+  conditionalAggregateSql(method, col, pred) {
+    const target = col === "*" ? "1" : col;
+    switch (method) {
+      case "count":
+        return `COUNT(CASE WHEN ${pred} THEN ${target} END)`;
+      case "count_distinct":
+        return `COUNT(DISTINCT CASE WHEN ${pred} THEN ${col} END)`;
+      case "sum":
+        return `SUM(CASE WHEN ${pred} THEN ${col} END)`;
+      case "avg":
+        return `AVG(CASE WHEN ${pred} THEN ${col} END)`;
+      case "min":
+        return `MIN(CASE WHEN ${pred} THEN ${col} END)`;
+      case "max":
+        return `MAX(CASE WHEN ${pred} THEN ${col} END)`;
+      // Closed vocabulary, same posture as `resolveMeasureAggregation`'s
+      // callers: `method` comes only from that function, whose own aggTypes
+      // list is exactly these six, so this default is unreachable rather than
+      // a silent fallback for a method this table forgot.
+      default:
+        return `${method.toUpperCase()}(CASE WHEN ${pred} THEN ${col} END)`;
+    }
+  }
   /**
    * Render one normalized filter as a display SQL predicate for `generateSql`.
    *
@@ -2351,8 +2508,20 @@ var ObjectQLStrategy = class {
   resolveMeasureAggregation(cube, measureName) {
     const direct = this.lookupMember(cube, measureName, "measure");
     if (direct) {
+      if (EXPRESSION_METRIC_TYPES.has(direct.type)) {
+        throw invalidMemberError(
+          `[Analytics] ObjectQLStrategy cannot evaluate the custom-SQL measure ("${measureName}") \u2014 its type "${direct.type}" declares a raw SQL expression, which the engine aggregate AST cannot carry; served anyway it would answer null for every bucket under the measure's own name. Use an aggregate measure (count/sum/avg/min/max/count_distinct), or run on a native-SQL driver.`,
+          { member: measureName, param: "measures", cube: cube.name }
+        );
+      }
       return {
         field: direct.sql.replace(/^\$/, ""),
+        // The assertion, not a parse: for a CubeSchema-legal cube the type
+        // partition above leaves exactly the six `AggregationFunction` values.
+        // An enum-INVALID type (host drift, the comment above) still flows
+        // through unchecked ON PURPOSE — adding a method allowlist here would
+        // re-blame the caller with a 400 for OUR bug, so the cast keeps the
+        // compile-time contract (#12776) without changing that posture.
         method: direct.type === "count_distinct" ? "count_distinct" : direct.type
       };
     }
@@ -2366,7 +2535,7 @@ var ObjectQLStrategy = class {
         if (candidate && candidate.type === type) {
           return {
             field: candidate.sql.replace(/^\$/, ""),
-            method: candidate.type === "count_distinct" ? "count_distinct" : candidate.type
+            method: type
           };
         }
       }
@@ -3930,15 +4099,59 @@ var AnalyticsService = class {
    * current request's ExecutionContext (ADR-0021 D-C). The strategy then sees a
    * `getReadScope(objectName)` that already knows the active tenant.
    */
-  async callCtx(query, context) {
-    if (!this.readScopeProvider) return { ...this.baseCtx, context };
+  async callCtx(query, context, tokenCtx) {
+    const getDatasetScope = this.resolvedDatasetScopeGetter(tokenCtx);
+    if (!this.readScopeProvider) return { ...this.baseCtx, context, getDatasetScope };
     const scopes = await this.resolveReadScopes(query, context);
     return {
       ...this.baseCtx,
       context,
+      getDatasetScope,
       getReadScope: (objectName) => scopes.get(objectName) ?? null
     };
   }
+  /**
+   * [#12230] Copy-on-write expansion of filter placeholders across everything
+   * a DIRECT analytics query compares on: `where` and each time dimension's
+   * `dateRange` — the same positions `DatasetExecutor.resolveSelectionTokens`
+   * covers for the dashboard door, minus the dataset-only channels it alone
+   * carries (measure filters ride the dataset-scope getter below).
+   *
+   * The input is never mutated: a query object can be caller-owned metadata
+   * (a saved report definition, a flow node's config) reused across requests,
+   * and resolving in place would bake one request's user id into every later
+   * render. Returns the SAME object when nothing resolved.
+   */
+  resolveQueryTokens(query, tokenCtx) {
+    const where = resolveFilterTokens2(query.where, tokenCtx);
+    const timeDimensions = query.timeDimensions?.map((td) => {
+      if (td.dateRange == null) return td;
+      const dateRange = resolveFilterTokens2(td.dateRange, tokenCtx);
+      return dateRange === td.dateRange ? td : { ...td, dateRange };
+    });
+    const tdChanged = timeDimensions !== void 0 && timeDimensions.some((td, i) => td !== query.timeDimensions[i]);
+    if (where === query.where && !tdChanged) return query;
+    const out = { ...query };
+    if (where !== query.where) out.where = where;
+    if (tdChanged) out.timeDimensions = timeDimensions;
+    return out;
+  }
+  /**
+   * [#12230] A per-request `getDatasetScope` whose answers have their filter
+   * placeholders resolved against THIS caller. See `callCtx` for why the
+   * registry's copy cannot be handed out raw. Token-free scopes pass through
+   * by reference — `resolveFilterTokens` returns its input unchanged when the
+   * tree holds no placeholder, so the common case allocates nothing.
+   */
+  resolvedDatasetScopeGetter(tokenCtx) {
+    return (cubeName) => {
+      const scope = this.baseCtx.getDatasetScope?.(cubeName);
+      if (!scope) return scope;
+      const filter = resolveFilterTokens2(scope.filter, tokenCtx);
+      const measureFilters = resolveFilterTokens2(scope.measureFilters, tokenCtx);
+      return filter === scope.filter && measureFilters === scope.measureFilters ? scope : { filter, measureFilters };
+    };
+  }
   /**
    * Resolve the read scope (tenant + RLS `FilterCondition`) for the base object
    * AND every joined object of the query's cube, keyed by object name. This is
@@ -3996,12 +4209,14 @@ var AnalyticsService = class {
    * aggregate bridge) instead of failing — or worse, fabricating empty rows.
    * Any other error propagates untouched.
    */
-  async query(query, context) {
-    if (!query.cube) {
+  async query(queryInput, context) {
+    if (!queryInput.cube) {
       throw new Error("Cube name is required in analytics query");
     }
+    const tokenCtx = filterTokenContextFrom2(context, /* @__PURE__ */ new Date());
+    const query = this.resolveQueryTokens(queryInput, tokenCtx);
     this.ensureCube(query);
-    const ctx = await this.callCtx(query, context);
+    const ctx = await this.callCtx(query, context, tokenCtx);
     let skip;
     for (; ; ) {
       const strategy = this.resolveStrategy(query, ctx, skip);
@@ -4197,6 +4412,7 @@ var AnalyticsService = class {
           const label = resolveI18nLabel2(m.label, requestLocale);
           if (label !== void 0) f.label = label;
         }
+        if (f.builtinAggregate == null && m.label == null && m.aggregate) f.builtinAggregate = m.aggregate;
         if (f.format == null && m.format) f.format = m.format;
         const fc = f;
         const mc = m;
@@ -4255,12 +4471,14 @@ var AnalyticsService = class {
   /**
    * Generate SQL for a query without executing it (dry-run).
    */
-  async generateSql(query, context) {
-    if (!query.cube) {
+  async generateSql(queryInput, context) {
+    if (!queryInput.cube) {
       throw new Error("Cube name is required for SQL generation");
     }
+    const tokenCtx = filterTokenContextFrom2(context, /* @__PURE__ */ new Date());
+    const query = this.resolveQueryTokens(queryInput, tokenCtx);
     this.ensureCube(query);
-    const ctx = await this.callCtx(query, context);
+    const ctx = await this.callCtx(query, context, tokenCtx);
     const strategy = this.resolveStrategy(query, ctx);
     this.logger.debug(`[Analytics] generateSql on cube "${query.cube}" \u2192 ${strategy.name}`);
     return strategy.generateSql(query, ctx);
@@ -4774,6 +4992,16 @@ var FallbackDelegateStrategy = class {
 };
 
 // src/plugin.ts
+import { AggregationFunction as AggregationFunction2 } from "@objectstack/spec/data";
+function parseEngineAggregateFunction(method, alias) {
+  const parsed = AggregationFunction2.safeParse(method);
+  if (!parsed.success) {
+    throw new Error(
+      `[Analytics] The aggregate bridge cannot forward the aggregation "${alias}": "${method}" is not one of the engine's aggregate functions (${AggregationFunction2.options.join(", ")}). A custom-SQL measure is refused earlier, with a caller-facing diagnostic, by ObjectQLStrategy; reaching this point means the analytics layer produced a method the engine contract does not declare.`
+    );
+  }
+  return parsed.data;
+}
 var AnalyticsServicePlugin = class {
   constructor(options = {}) {
     this.name = "com.objectstack.service-analytics";
@@ -4831,10 +5059,58 @@ var AnalyticsServicePlugin = class {
         const rows = await engine.aggregate(objectName, {
           where: filter,
           groupBy,
+          // [#10413 phase 2 / #10576] `a.filter` is the per-aggregation
+          // predicate `ObjectQLStrategy` lowers a measure's own scoped
+          // `filter` into. This map already renames `method` → `function`
+          // for the engine's own vocabulary; dropping `filter` here — as this
+          // bridge did before this line existed — would have made the
+          // strategy's lowering a NO-OP on every real deployment that boots
+          // through this auto-bridge (the default path: `new
+          // AnalyticsServicePlugin({ cubes })` with no custom
+          // `executeAggregate`), passing every unit test that stubs
+          // `executeAggregate` directly while silently dropping the filter in
+          // production — the exact declared-≠-enforced shape Prime Directive
+          // #10 calls out. Omitted (not `filter: undefined`) when the
+          // aggregation carries none, matching the engine's own
+          // vacuous-filter convention.
           aggregations: aggregations?.map((a) => ({
-            function: a.method,
+            // [#11833] `function` is the engine contract's SIX-value
+            // `AggregationFunction`. This bridge's own input declared
+            // `method: string` when that history was written
+            // (`StrategyContext.executeAggregate`, spec
+            // `contracts/analytics-service.ts`), so the two ends of this
+            // rename spoke different vocabularies: narrowing the engine side
+            // to the contract turned the forward into a compile error — the
+            // correct signal, and the one the deleted structural type hid by
+            // declaring `function: string` on both sides.
+            //
+            // Since #12776 (contract) and #12940 (this plugin's own config
+            // mirror above), BOTH ends declare the enum, so the rename is
+            // enum-to-enum and the parse below is defence in depth behind a
+            // compile-time check rather than the only check — see
+            // `parseEngineAggregateFunction` for why erased types still leave
+            // it load-bearing.
+            //
+            // It was closed by PARSING with the spec enum itself rather than
+            // by widening back to `string` (what hid it) or casting past it
+            // (which keeps the hole and adds a lie). `AggregationFunction` is
+            // the same schema `AggregationNodeSchema.function` is built from,
+            // so there is one vocabulary, and its own error map already
+            // carries the `array_agg`/`string_agg` retirement prescriptions.
+            //
+            // TIERING, deliberately: the reachable producer of a non-aggregate
+            // method — a custom-SQL measure (`AggregationMetricType`
+            // `number`/`string`/`boolean`) — is already refused upstream with a
+            // caller-blaming 400 by `ObjectQLStrategy.resolveMeasureAggregation`
+            // (#12209). Anything still arriving here is host drift, which that
+            // refusal's docblock assigns to the undeclared-500 tier — so this
+            // throws rather than re-blaming the caller, and it answers loudly
+            // instead of letting the engine answer `null` per bucket under the
+            // author's own measure name (the #4157 class).
+            function: parseEngineAggregateFunction(a.method, a.alias),
             field: a.field,
-            alias: a.alias
+            alias: a.alias,
+            ...a.filter ? { filter: a.filter } : {}
           })),
           // ADR-0053 Phase 2: thread the reference tz so date buckets resolve on
           // that zone's calendar days (engine buckets in-memory when non-UTC).
@@ -4936,6 +5212,7 @@ var AnalyticsServicePlugin = class {
         const map = /* @__PURE__ */ new Map();
         const displayField = pickDisplayField(dataEngine()?.getObject?.(targetObject)?.fields);
         if (!displayField || !executeAggregate || ids.length === 0) return map;
+        if (scope) assertReadScopeCannotVacate(scope, targetObject);
         const CHUNK = 500;
         for (let i = 0; i < ids.length; i += CHUNK) {
           const idFilter = { id: { $in: ids.slice(i, i + CHUNK) } };