@objectstack/service-analytics 17.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,200 @@
 # Changelog — @objectstack/service-analytics
 
+## 17.2.0
+
+### Minor Changes
+
+- 57e4571: **BREAKING**: `/analytics/query` now refuses a cross-object filter nested inside a
+  combinator on the ObjectQL path, instead of silently answering the wrong number
+  (#10759).
+  
+  `ObjectQLStrategy` runs one cross-object envelope check, from two call sites.
+  `generateSql()` (the `/analytics/sql` preview) asked it about every member the
+  `where` touches, flattened out of the filter tree. `execute()` asked it about the
+  built engine filter — where an AND-ed leaf sits at the top level and is seen, but
+  anything structural (an `$or`, a `$not`, a nested `$and` that cannot merge) has
+  been folded into `filter.$and`, so the only key readable for it was the literal
+  `$and`, which is never a field name.
+  
+  One query therefore got two answers, measured over one fixture in one run:
+  
+  ```
+  where: { $or: [{ 'account.region': 'West' }, { stage: 'won' }] }
+  
+  before   /analytics/sql     400 INVALID_FIELD  cross-object filter "account.region"
+           /analytics/query   200, rows
+  after    both               400 INVALID_FIELD  cross-object filter "account.region"
+  ```
+  
+  `engine.aggregate` cannot join. The half that returned rows was not answering the
+  cross-object query: the disjunct naming a column the base object does not have
+  can never match, so the query silently collapsed to its remaining branches and
+  reported a narrower figure as if it were the answer. Both call sites now derive
+  the member list from one shared view, so the invariant the strategy already
+  stated for itself — the preview accepts and rejects the same set the execution
+  door does — holds by construction rather than by two call sites agreeing.
+  
+  Who is affected: a deployment whose driver reports `objectqlAggregate` but not
+  `nativeSql` (Mongo, the memory driver), running an analytics query that puts a
+  related object's field inside `$or` or `$not`. Such a query now returns
+  `400 INVALID_FIELD` naming the member. The refusal already existed and already
+  had these words; what changed is that the execution door reaches it too. Nothing
+  an author writes in metadata changes, no stored shape is affected, and queries
+  whose combinators name only base-object fields are untouched — that set is pinned
+  in `crossobject-conjunct-refusal.test.ts` alongside the new refusal, because a
+  fix that refused every combinator would have looked identical from the refusal
+  side alone.
+  
+  The remedy for an affected query is the one the error message has always carried:
+  run it on a native-SQL driver, which can join, or drop the cross-object member
+  from the filter.
+  
+  <!-- adr-0087: not-required (no-migration-prescription) A runtime query-shape refusal on /analytics/query, not a metadata surface: no authorable key, export or config field is removed or renamed, so `objectstack migrate meta` has nothing to rewrite and an upgrader has no stored shape to convert. The affected input is an ad-hoc request body, and the error itself names the member and the two ways out. -->
+- 13a3dca: **BREAKING**: on the ObjectQL path, a compiled dataset whose definition-level
+  `filter` is itself cross-object is now refused by both analytics doors instead
+  of reaching `engine.aggregate` with a predicate it cannot join (#10861).
+  
+  PR #10758 gave the dataset's own definition-level `filter` a route onto this
+  door for the first time. That route was outside the member view the cross-object
+  envelope check judges, so nothing ever saw it:
+  
+  ```
+  dataset: object 'opportunity', include: ['account'],
+           filter: { 'account.region': 'West' }
+  
+  before   /analytics/query   200, rows   -> engine.aggregate received
+                                             {"$and":[{"account.region":"West"}]}
+           /analytics/sql     200, SQL
+  after    both               400 INVALID_FIELD, member "account.region",
+                              cube "<dataset>"; the engine is never reached
+  ```
+  
+  `engine.aggregate` cannot join. `account.region` is not a column of
+  `opportunity`, so on any driver that evaluates the predicate honestly it matches
+  nothing, and the widget answered a number that was neither the scoped number nor
+  the unscoped one — with no error anywhere. That is the silent mis-bucket #3654's
+  loud refusal exists to prevent, arriving through a producer #3654 predates.
+  
+  **Breaking, and argued rather than assumed.** A query that returns `200` with
+  rows today starts answering `400`, on a *saved* dataset rather than on anything
+  in the request — a dashboard that renders today can start showing an error. That
+  is the strongest reading of "breaking" and it is why this is called out here
+  rather than filed as a quiet fix. What is *not* lost is any correct answer: the
+  rows that stop being served were already wrong, and wrong in the way that hides
+  itself. The refusal names the member, names the dataset, and says the same
+  definition is valid on a native-SQL deployment, so the operator has somewhere to
+  go; the previous behaviour gave them a plausible number and nothing to notice.
+  Rejecting the dataset at compile time in `dataset-compiler.ts` was considered and
+  not taken (maintainer ruling, 2026-08-22): the compiler cannot see which driver
+  will serve the dataset, and the same definition is legal on a native-SQL one.
+  
+  Who is affected: a deployment whose driver reports `objectqlAggregate` but not
+  `nativeSql` (Mongo, the memory driver), serving a dataset whose definition-level
+  `filter` names a field on a related object. Nothing an author writes changes
+  shape, no stored document is rewritten, and an **ordinary** dataset scope
+  (`filter: { is_deleted: false }`) still passes both doors and still reaches the
+  engine carrying its predicate — that direction is pinned one character away from
+  the new refusal in `crossobject-conjunct-refusal.test.ts`, because an
+  implementation that refused *every* dataset scope would look identical from the
+  refusal side alone and would break every scoped dataset shipping today.
+  
+  <!-- adr-0087: not-required (no-migration-prescription) No authorable surface is
+  retired, renamed or re-shaped: `DatasetSchema`'s `filter` key stays exactly as it
+  is, every stored dataset document stays valid as written, and the very same
+  document remains correct on a native-SQL deployment. There is therefore nothing
+  `objectstack migrate meta` could rewrite — a mechanical rewrite would have to
+  know which driver will serve the dataset, which is precisely the capability the
+  2026-08-22 ruling records as invisible to the compile-time placement. This is a
+  query-time refusal on one driver family, not a surface retirement, so the ledger
+  has no entry to carry and the upgrade guide has no prescription to print. -->
+
+### Patch Changes
+
+- 7bf3fb7: Point every documentation link in these packages' published READMEs — and in
+  the project `create-objectstack` scaffolds — at the canonical docs origin
+  `https://objectstack.ai`, replacing the `docs.objectstack.ai` spelling.
+  
+  Both spellings reach the same pages (the alias redirects to the apex,
+  path-preserving), so no link was broken. The reason it needs a release rather
+  than an in-repo fix alone: a README ships inside the npm tarball, so the
+  version already on npm keeps showing the old host to every reader of the
+  package page until a new one is published.
+- 112a8c6: Apply a dataset's definition-level `filter` on the ObjectQL analytics path
+  (#10413, phase 1). `/api/v1/analytics/query` served by a driver that reports
+  `objectqlAggregate` but not `nativeSql` (MongoDB, the memory driver) reached
+  `engine.aggregate` with no `filter` key at all: the dataset's own scope — a
+  `filter: { is_deleted: false }` on the dataset definition — was dropped, so
+  every measure aggregated the whole table while the dashboard door, on the same
+  cube and the same measure names, answered the scoped numbers. The scope is now
+  ANDed into the strategy's whole-call filter (never merged key-by-key, so a
+  caller's own `where` and the time windows cannot be overwritten by it), and the
+  representative SQL echo renders it too.
+  
+  Per-MEASURE `filter`s on this path are still not applied: an
+  `engine.aggregate` aggregation is `{ field, method, alias }` and cannot carry a
+  predicate of its own. Widening that contract is #10576; lowering the measure
+  filters into it is phase 2 of #10413. The native-SQL path already applies both
+  (#10298).
+- 6439f8b: Analytics measures are now compiled from everything they declare — `aggregate`, `field` **and** `filter` — on both the dashboard path and `POST /api/v1/analytics/query`.
+  
+  **Reported figures change, and the new ones are the declared ones.** Two corrections, both of which move numbers a dashboard or an API consumer is already reading:
+  
+  - A measure written `{ aggregate: 'count', field: 'some_column' }` used to compile to `COUNT(*)` and count **rows**. It now compiles to `COUNT("some_column")` and counts **non-null values**. Any such measure will report the same number as before or a **smaller** one, and a rate built on top of it (a numerator over a total) will drop accordingly — a "100%" tile whose column was mostly empty was reading its own denominator.
+  - `POST /api/v1/analytics/query` used to drop every per-measure `filter`, and the dataset's definition-level `filter` with it, returning unfiltered aggregates under the author's measure names. It now applies both, so the endpoint answers what the dashboard already answered for the same cube. Figures pulled through the API — agent tools, exports, downstream reports — will move to the filtered values; a measure declaring `filter: { stage: 'closed_won' }` stops counting every row.
+  
+  Measures that declare no `field` still compile to `COUNT(*)`, and a cube that is not a compiled dataset (an inferred or manifest cube) emits byte-for-byte the statement it did before. Measure filters lower to portable `CASE WHEN` conditional aggregates rather than `FILTER (WHERE …)`, which MySQL does not have.
+  
+  If a saved figure or a screenshot disagrees with what the platform now reports, the new number is the one the metadata declares.
+- Updated dependencies [6936d07]
+- Updated dependencies [59eb04d]
+- Updated dependencies [9f05b7d]
+- Updated dependencies [3b2af5e]
+- Updated dependencies [7d2d112]
+- Updated dependencies [5fa0d72]
+- Updated dependencies [02b3b07]
+- Updated dependencies [46d34ab]
+- Updated dependencies [914c413]
+- Updated dependencies [55809a0]
+- Updated dependencies [ee2ff45]
+- Updated dependencies [47cd3ec]
+- Updated dependencies [52db1d1]
+- Updated dependencies [5649efb]
+- Updated dependencies [9d7d2de]
+- Updated dependencies [c815c50]
+- Updated dependencies [795ea05]
+- Updated dependencies [2306a76]
+- Updated dependencies [e5ea701]
+- Updated dependencies [a40dcc1]
+- Updated dependencies [def0d3e]
+- Updated dependencies [8d0bb79]
+- Updated dependencies [5acb58d]
+- Updated dependencies [2e3cf95]
+- Updated dependencies [4c93387]
+- Updated dependencies [504c8d5]
+- Updated dependencies [a037f7c]
+- Updated dependencies [3ee8ddf]
+- Updated dependencies [16cef97]
+- Updated dependencies [a79bd35]
+- Updated dependencies [6ceaa4b]
+- Updated dependencies [15ea214]
+- Updated dependencies [de19489]
+- Updated dependencies [c684d00]
+- Updated dependencies [923c424]
+- Updated dependencies [1ec36b7]
+- Updated dependencies [5f2e54c]
+- Updated dependencies [189373b]
+- Updated dependencies [35ad101]
+- Updated dependencies [ceb33a9]
+- Updated dependencies [73d9795]
+- Updated dependencies [8012960]
+- Updated dependencies [f34f56b]
+- Updated dependencies [f399618]
+- Updated dependencies [75e9301]
+- Updated dependencies [2810695]
+  - @objectstack/spec@17.2.0
+  - @objectstack/core@17.2.0
+  - @objectstack/types@17.2.0
+
 ## 17.1.0
 
 ### Patch Changes

package/README.md

@@ -103,8 +103,10 @@ is rejected rather than dropped.
 | `timezone` | `string?` | IANA name. No default — an absent timezone means the engine resolves it. |
 
 There is no `filters` key and no `aggregations` key. `filters` is rejected at the REST
-door with a 400 naming `where`; per-metric filtering lives on the cube metric's own
-`filters`.
+door with a 400 naming `where`. There is no per-metric filter key either — the cube
+metric's `filters` was removed (#10414: no strategy ever read it); fold a per-metric
+condition into the metric's own `sql` expression, or use an ADR-0021 dataset measure's
+structured `filter`.
 
 ```typescript
 const revenueByStatus = await analytics.query({
@@ -191,4 +193,4 @@ Apache-2.0. See [LICENSING.md](../../../LICENSING.md).
 
 - [@objectstack/objectql](../../objectql/)
 - [@objectstack/driver-memory](../../drivers/driver-memory/) — ships `InMemoryStrategy`
-- [Analytics Guide](https://docs.objectstack.ai/docs/data-modeling/analytics)
+- [Analytics Guide](https://objectstack.ai/docs/data-modeling/analytics)

package/dist/index.cjs

@@ -1063,14 +1063,31 @@ function invalidMemberError(message, meta) {
 // src/strategies/native-sql-strategy.ts
 var import_core2 = require("@objectstack/core");
 var AGGREGATE_SQL = {
-  "count": () => "COUNT(*)",
+  // [#10298] `count` takes its COLUMN when the measure declares one. The
+  // wrapper used to discard `col` and always emit `COUNT(*)`, so a measure
+  // written `{ aggregate: 'count', field: 'resolved_by_article' }` counted
+  // ROWS instead of non-null values — and a deflection rate built as
+  // `kb_resolved_count / closed_count` read 100% where the truth was 12.5%,
+  // with the numerator and denominator printed beside it as 8 and 8. `*` is
+  // still `COUNT(*)`: the compiler writes `sql: m.field ?? '*'`, so the star
+  // IS the "no field declared" spelling and must keep counting rows.
+  "count": (col) => col === "*" ? "COUNT(*)" : `COUNT(${col})`,
   "sum": (col) => `SUM(${col})`,
   "avg": (col) => `AVG(${col})`,
   "min": (col) => `MIN(${col})`,
   "max": (col) => `MAX(${col})`,
   "count_distinct": (col) => `COUNT(DISTINCT ${col})`
 };
+var CONDITIONAL_AGGREGATE_SQL = {
+  "count": (col, pred) => `COUNT(CASE WHEN ${pred} THEN ${col === "*" ? "1" : col} END)`,
+  "sum": (col, pred) => `SUM(CASE WHEN ${pred} THEN ${col} END)`,
+  "avg": (col, pred) => `AVG(CASE WHEN ${pred} THEN ${col} END)`,
+  "min": (col, pred) => `MIN(CASE WHEN ${pred} THEN ${col} END)`,
+  "max": (col, pred) => `MAX(CASE WHEN ${pred} THEN ${col} END)`,
+  "count_distinct": (col, pred) => `COUNT(DISTINCT CASE WHEN ${pred} THEN ${col} END)`
+};
 var SUPPORTED_AGGREGATE_SQL_KEYS = Object.keys(AGGREGATE_SQL);
+var CONDITIONAL_AGGREGATE_SQL_KEYS = Object.keys(CONDITIONAL_AGGREGATE_SQL);
 var EXPRESSION_METRIC_TYPES = /* @__PURE__ */ new Set(["number", "string", "boolean"]);
 var IDENTIFIER_PATH = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
 var NativeSQLStrategy = class {
@@ -1236,9 +1253,19 @@ var NativeSQLStrategy = class {
         groupByClauses.push(colExpr);
       }
     }
+    const datasetScope = ctx.getDatasetScope?.(query.cube);
     if (query.measures && query.measures.length > 0) {
       for (const measure of query.measures) {
-        const aggExpr = this.resolveMeasureSql(cube, measure, tableName, joins);
+        const measureFilter = datasetScope?.measureFilters?.[measure];
+        const predicate = measureFilter ? this.compileFilterNode(
+          normalizeAnalyticsFilterTree({ where: measureFilter }),
+          cube,
+          tableName,
+          joins,
+          params,
+          ctx
+        ) : null;
+        const aggExpr = this.resolveMeasureSql(cube, measure, tableName, joins, predicate);
         selectClauses.push(`${aggExpr} AS "${measure}"`);
       }
     }
@@ -1252,6 +1279,17 @@ var NativeSQLStrategy = class {
       ctx
     );
     if (filterSql) whereClauses.push(filterSql);
+    if (datasetScope?.filter) {
+      const scopeSql = this.compileFilterNode(
+        normalizeAnalyticsFilterTree({ where: datasetScope.filter }),
+        cube,
+        tableName,
+        joins,
+        params,
+        ctx
+      );
+      if (scopeSql) whereClauses.push(scopeSql);
+    }
     if (query.timeDimensions && query.timeDimensions.length > 0) {
       for (const td of query.timeDimensions) {
         const colExpr = this.resolveFieldSql(cube, td.dimension, tableName, joins);
@@ -1425,7 +1463,12 @@ var NativeSQLStrategy = class {
     const raw = dim ? dim.sql : member.includes(".") ? member.split(".")[1] : member;
     return this.qualifyAndRegisterJoin(raw, parentTable, joins, cube);
   }
-  resolveMeasureSql(cube, member, parentTable, joins) {
+  /**
+   * @param predicate - The measure's own scoped filter, already compiled to a
+   *   SQL boolean (`null` = the measure declares none, or declares one that
+   *   constrains nothing — `compileFilterNode`'s TRUE). #10298.
+   */
+  resolveMeasureSql(cube, member, parentTable, joins, predicate = null) {
     const measure = this.lookupMember(cube, member, "measure");
     if (!measure) {
       const declared = Object.keys(cube.measures ?? {});
@@ -1435,6 +1478,13 @@ var NativeSQLStrategy = class {
       );
     }
     const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins, cube);
+    if (predicate !== null) {
+      const wrapConditional = CONDITIONAL_AGGREGATE_SQL[measure.type];
+      if (wrapConditional) return wrapConditional(col, predicate);
+      throw new Error(
+        `[native-sql-strategy] measure "${member}" on cube "${cube.name}" carries a scoped filter, but its type "${measure.type}" has no conditional form (conditional: ${CONDITIONAL_AGGREGATE_SQL_KEYS.join(", ")}).`
+      );
+    }
     const wrap = AGGREGATE_SQL[measure.type];
     if (wrap) return wrap(col);
     if (EXPRESSION_METRIC_TYPES.has(measure.type)) return col;
@@ -1781,10 +1831,18 @@ 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 }),
+        cube
+      );
+      if (scopeCondition) conjuncts.push(scopeCondition);
+    }
     if (conjuncts.length > 0) {
       filter.$and = [...Array.isArray(filter.$and) ? filter.$and : [], ...conjuncts];
     }
-    const plan = this.planCrossObject(cube, query, filter);
+    const plan = this.planCrossObject(cube, query, this.filterMemberView(cube, query, ctx));
     if (plan) {
       return this.executeCrossObject(cube, query, aggregations, filter, plan, ctx);
     }
@@ -1861,9 +1919,7 @@ var ObjectQLStrategy = class {
       if (td.granularity) granByDim.set(td.dimension, td.granularity);
     }
     const tableName = this.extractObjectName(cube);
-    const plan = this.planCrossObject(cube, query, Object.fromEntries(
-      collectFilterLeaves(normalizeAnalyticsFilterTree(query)).map((f) => [this.resolveFieldName(cube, f.member, "any"), true])
-    ));
+    const plan = this.planCrossObject(cube, query, this.filterMemberView(cube, query, ctx));
     const crossByDim = new Map((plan?.crossDims ?? []).map((cd) => [cd.outputName, cd]));
     const joinClauses = [];
     const dimExpr = (dim) => {
@@ -1905,6 +1961,15 @@ var ObjectQLStrategy = class {
       params
     );
     if (filterClause) whereParts.push(filterClause);
+    const echoedDatasetFilter = ctx.getDatasetScope?.(query.cube)?.filter;
+    if (echoedDatasetFilter) {
+      const scopeSql = this.renderFilterNodeSql(
+        normalizeAnalyticsFilterTree({ where: echoedDatasetFilter }),
+        cube,
+        params
+      );
+      if (scopeSql) whereParts.push(scopeSql);
+    }
     for (const { field, bounds } of this.dateRangeBounds(cube, query)) {
       const nextDay = (0, import_core3.nextUtcCalendarDay)(bounds.$lte);
       params.push(bounds.$gte, nextDay ?? bounds.$lte);
@@ -1972,6 +2037,68 @@ var ObjectQLStrategy = class {
     const joinedObject = cube.joins?.[alias]?.name ?? alias;
     return joinedObject !== baseObject;
   }
+  /**
+   * The member view {@link planCrossObject} judges a filter by: EVERY member
+   * that will end up in the engine's predicate, structure discarded, keyed by
+   * RESOLVED field name (#10759), valued by WHERE THE MEMBER CAME FROM
+   * (#10861).
+   *
+   * Both call sites — `execute()` and `generateSql()` — are handed this and
+   * nothing else, which is what makes the invariant `planCrossObject` states
+   * for itself ("the preview accepts/rejects the same set") structural rather
+   * than a coincidence maintained by hand. They used to build the view
+   * separately: the echo flattened the tree, `execute()` passed the ENGINE
+   * FILTER, and a filter record answers a different question — it is a
+   * predicate to evaluate, not an inventory of members. An `$or`, a `$not` or
+   * an unmergeable nested `$and` travels in it as one opaque `$and` entry, so
+   * 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)
+   *
+   * 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
+   * `filter` is lowered onto `execute()`'s `conjuncts` and rendered by
+   * `generateSql()`, so a dataset declaring `filter: { 'account.region': 'West' }`
+   * sent `{"$and":[{"account.region":"West"}]}` to an engine that cannot join —
+   * measured on both doors, which AGREED in accepting it, so #10759's
+   * preview/execution symmetry had nothing to restore. Refusing it is a
+   * widening of the refusal set, ruled by the maintainer on 2026-08-22 (Option
+   * A, query-time refusal): fold the scope's leaves in HERE, where driver
+   * capability is known, rather than in `dataset-compiler.ts`, which cannot see
+   * which driver will serve the dataset and would refuse a dataset that is
+   * perfectly legal on a native-SQL deployment.
+   *
+   * 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
+   * decides what the refusal can tell the caller to go fix: `AnalyticsRequestKey`
+   * is the analytics REQUEST vocabulary and a dataset's `filter` is not in it,
+   * so a scope-borne member must not be reported as `param: 'where'` — see
+   * `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.
+   *
+   * Time-dimension WINDOWS are deliberately absent (they live in
+   * `dateRangeBounds`, not in `where`). They need no arm here: a cross-object
+   * time dimension is refused by `planCrossObject`'s own first loop, over
+   * `query.timeDimensions`, and refused as the time dimension the author wrote
+   * rather than as the lowered predicate it becomes — which is the better
+   * diagnostic and the reason that loop runs first.
+   */
+  filterMemberView(cube, query, ctx) {
+    const datasetFilter = ctx.getDatasetScope?.(query.cube)?.filter;
+    const leaves = (node, origin) => collectFilterLeaves(node).map(
+      (f) => [this.resolveFieldName(cube, f.member, "any"), origin]
+    );
+    return Object.fromEntries([
+      ...datasetFilter ? leaves(normalizeAnalyticsFilterTree({ where: datasetFilter }), "dataset-filter") : [],
+      ...leaves(normalizeAnalyticsFilterTree(query), "where")
+    ]);
+  }
   /**
    * Plan how to serve cross-object references on this join-less path (#3654).
    *
@@ -1982,21 +2109,36 @@ var ObjectQLStrategy = class {
    * query (direct path), a plan for an in-envelope cross-object query.
    *
    * THROWS for anything outside the envelope — a cross-object MEASURE or FILTER
-   * (needs a real join to evaluate), a MULTI-HOP dimension (`a.b.c`), or a
+   * (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.
-   * `generateSql()` calls this too, so the preview accepts/rejects the same set.
+   * `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 four refusals below are `invalidMemberError` — `INVALID_FIELD` /
-   * 400, naming the member — and the MESSAGES are unchanged (they are good
-   * diagnostics, and #5923's tests read them). Each is decided by two caller-side
-   * facts and nothing else: a member the query named, 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 what the "run this on a native-SQL driver" half of each
-   * message says. They are member-level rather than dataset-level (hence not
-   * `datasetInvalidError`) because the fix is always to change or drop ONE named
-   * member, and because they fire on `/analytics/query` where no dataset exists.
+   * [#5716] All five 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
+   * 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
+   * what the "run this on a native-SQL driver" half of every message says. They
+   * are member-level rather than dataset-level (hence not `datasetInvalidError`)
+   * 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
+   * `INVALID_FIELD` rather than becoming `DATASET_INVALID` because the verdict
+   * is the same physical one as its neighbour — 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.
    *
    * Detection is on RESOLVED field names, so a dotted dimension the cube
    * flattens to a real column is treated as base, not cross-object.
@@ -2018,7 +2160,7 @@ var ObjectQLStrategy = class {
         member: m,
         field: this.resolveMeasureAggregation(cube, m).field
       })),
-      ...Object.keys(filter).map((f) => ({ where: "filter", member: f, field: f }))
+      ...Object.entries(filter).filter(([, origin]) => origin === "where").map(([f]) => ({ where: "filter", member: f, field: f }))
     ].filter((r) => this.isCrossObjectField(cube, r.field, baseObject));
     if (nonDim.length > 0) {
       throw invalidMemberError(
@@ -2032,6 +2174,13 @@ var ObjectQLStrategy = class {
         }
       );
     }
+    const scopeCross = Object.entries(filter).filter(([field, origin]) => origin === "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 crossDims = [];
     for (const dim of query.dimensions ?? []) {
       const field = this.resolveFieldName(cube, dim, "dimension");
@@ -3786,6 +3935,16 @@ var AnalyticsService = class {
       // Prefer a compiled dataset's declared relationships (D-C join allowlist);
       // fall back to any explicitly-configured provider for legacy cubes.
       getAllowedRelationships: (cubeName) => this.datasetRegistry.get(cubeName)?.allowedRelationships ?? config.getAllowedRelationships?.(cubeName),
+      // [#10298] The compiled dataset's definition-level filter and its
+      // per-measure filters — the half of the declaration the Cube model has
+      // no room for. Same shape and same registry as `getAllowedRelationships`
+      // directly above: answered for a cube that IS a compiled dataset,
+      // `undefined` for every other cube.
+      getDatasetScope: (cubeName) => {
+        const compiled = this.datasetRegistry.get(cubeName);
+        if (!compiled) return void 0;
+        return { filter: compiled.filter, measureFilters: compiled.measureFilters };
+      },
       coerceTemporalFilterValue: config.coerceTemporalFilterValue,
       coerceTemporalFilterColumn: config.coerceTemporalFilterColumn,
       isExternalObject: config.isExternalObject