@objectstack/service-analytics 17.1.0 → 17.3.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { IAnalyticsService, Logger, AnalyticsDriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, DatasetSelection, CubeMeta, DatasetCompareTo, StrategyContext } from '@objectstack/spec/contracts';
 export { AnalyticsDriverCapabilities, AnalyticsStrategy, DatasetSelection, StrategyContext } from '@objectstack/spec/contracts';
-import { Cube, FilterCondition } from '@objectstack/spec/data';
+import { Cube, FilterCondition, AggregationFunction } from '@objectstack/spec/data';
 import { ExecutionContext } from '@objectstack/spec/kernel';
 import { Dataset } from '@objectstack/spec/ui';
 import { Plugin, PluginContext } from '@objectstack/core';
@@ -328,10 +328,28 @@ interface AnalyticsServiceConfig {
      */
     executeAggregate?: (objectName: string, options: {
         groupBy?: string[];
+        /**
+         * The local mirror of `StrategyContext.executeAggregate`'s aggregation
+         * entries (`packages/spec/src/contracts/analytics-service.ts`), kept in
+         * lockstep with it member by member. The two that lockstep is load-bearing
+         * for:
+         *
+         * - `filter` (#10576, the #10413 phase-2 contract field) — a bridge that
+         *   reconstructs the aggregation entries (as `AnalyticsServicePlugin`'s
+         *   auto-bridge does, to rename `method` → the engine's `function`) MUST
+         *   forward this field or a measure-scoped filter `ObjectQLStrategy`
+         *   lowers never reaches storage.
+         * - `method` is the spec's OWN six-value `AggregationFunction`, not
+         *   `string`: #12776 narrowed the contract, #12940 brought this mirror
+         *   back into line. Widening it here again would not be a local matter —
+         *   a bridge author types their handler against THIS declaration, so what
+         *   they would get is a vocabulary the contract no longer has.
+         */
         aggregations?: Array<{
             field: string;
-            method: string;
+            method: AggregationFunction;
             alias: string;
+            filter?: Record<string, unknown>;
         }>;
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
@@ -619,6 +637,27 @@ declare class AnalyticsService implements IAnalyticsService {
      * `getReadScope(objectName)` that already knows the active tenant.
      */
     private callCtx;
+    /**
+     * [#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.
+     */
+    private resolveQueryTokens;
+    /**
+     * [#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.
+     */
+    private resolvedDatasetScopeGetter;
     /**
      * 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
@@ -644,7 +683,7 @@ declare class AnalyticsService implements IAnalyticsService {
      * aggregate bridge) instead of failing — or worse, fabricating empty rows.
      * Any other error propagates untouched.
      */
-    query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
+    query(queryInput: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
     /**
      * [#8286] Withhold the executed statement unless this host enabled the echo.
      *
@@ -686,7 +725,7 @@ declare class AnalyticsService implements IAnalyticsService {
     /**
      * Generate SQL for a query without executing it (dry-run).
      */
-    generateSql(query: AnalyticsQuery, context?: ExecutionContext): Promise<{
+    generateSql(queryInput: AnalyticsQuery, context?: ExecutionContext): Promise<{
         sql: string;
         params: unknown[];
     }>;
@@ -922,10 +961,28 @@ interface AnalyticsServicePluginOptions {
      */
     executeAggregate?: (objectName: string, options: {
         groupBy?: string[];
+        /**
+         * The CUSTOM bridge's view of the aggregation entries — an app author's
+         * own `executeAggregate`, as opposed to the auto-bridge below. Mirrors
+         * `StrategyContext.executeAggregate`
+         * (`packages/spec/src/contracts/analytics-service.ts`) and must stay in
+         * lockstep with it; the two members that lockstep is load-bearing for:
+         *
+         * - `filter` (#10576, the #10413 contract field) — a custom bridge MUST
+         *   forward it to the real engine the same way the auto-bridge does, or a
+         *   measure-scoped filter this plugin lowers onto the aggregation
+         *   silently never reaches storage.
+         * - `method` is the spec's OWN six-value `AggregationFunction`, not
+         *   `string`: #12776 narrowed the contract, #12940 brought this mirror
+         *   back into line. This is the declaration a custom-bridge author types
+         *   their handler against, so it is where the compile-time vocabulary
+         *   #12776 bought for strategy authors reaches them too.
+         */
         aggregations?: Array<{
             field: string;
-            method: string;
+            method: AggregationFunction;
             alias: string;
+            filter?: Record<string, unknown>;
         }>;
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
@@ -1308,6 +1365,11 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      */
     private lookupMember;
     private resolveDimensionSql;
+    /**
+     * @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.
+     */
     private resolveMeasureSql;
     private resolveFieldSql;
     /**
@@ -1443,6 +1505,92 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private withReadScope;
     /** Is `field` a resolved cross-object (relationship-traversal) reference? */
     private isCrossObjectField;
+    /**
+     * 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.
+     *
+     * ## 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
+     * `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.
+     *
+     * [#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
+     * 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.
+     *
+     * 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
+     * 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.
+     */
+    private filterMemberView;
     /**
      * Plan how to serve cross-object references on this join-less path (#3654).
      *
@@ -1453,21 +1601,39 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
-     * 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.
-     *
-     * [#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.
+     * (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 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 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); 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
+     * 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, #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 their neighbours — this engine cannot join this
+     * member — and splitting the code by PROVENANCE would make a caller branch on
+     * 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.
@@ -1485,6 +1651,23 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * are simply absent from the map (⇒ RESTRICTED bucket downstream).
      */
     private resolveFkAttr;
+    /**
+     * 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.
+     */
+    private conditionalAggregateSql;
     /**
      * Render one normalized filter as a display SQL predicate for `generateSql`.
      *

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { IAnalyticsService, Logger, AnalyticsDriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, DatasetSelection, CubeMeta, DatasetCompareTo, StrategyContext } from '@objectstack/spec/contracts';
 export { AnalyticsDriverCapabilities, AnalyticsStrategy, DatasetSelection, StrategyContext } from '@objectstack/spec/contracts';
-import { Cube, FilterCondition } from '@objectstack/spec/data';
+import { Cube, FilterCondition, AggregationFunction } from '@objectstack/spec/data';
 import { ExecutionContext } from '@objectstack/spec/kernel';
 import { Dataset } from '@objectstack/spec/ui';
 import { Plugin, PluginContext } from '@objectstack/core';
@@ -328,10 +328,28 @@ interface AnalyticsServiceConfig {
      */
     executeAggregate?: (objectName: string, options: {
         groupBy?: string[];
+        /**
+         * The local mirror of `StrategyContext.executeAggregate`'s aggregation
+         * entries (`packages/spec/src/contracts/analytics-service.ts`), kept in
+         * lockstep with it member by member. The two that lockstep is load-bearing
+         * for:
+         *
+         * - `filter` (#10576, the #10413 phase-2 contract field) — a bridge that
+         *   reconstructs the aggregation entries (as `AnalyticsServicePlugin`'s
+         *   auto-bridge does, to rename `method` → the engine's `function`) MUST
+         *   forward this field or a measure-scoped filter `ObjectQLStrategy`
+         *   lowers never reaches storage.
+         * - `method` is the spec's OWN six-value `AggregationFunction`, not
+         *   `string`: #12776 narrowed the contract, #12940 brought this mirror
+         *   back into line. Widening it here again would not be a local matter —
+         *   a bridge author types their handler against THIS declaration, so what
+         *   they would get is a vocabulary the contract no longer has.
+         */
         aggregations?: Array<{
             field: string;
-            method: string;
+            method: AggregationFunction;
             alias: string;
+            filter?: Record<string, unknown>;
         }>;
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
@@ -619,6 +637,27 @@ declare class AnalyticsService implements IAnalyticsService {
      * `getReadScope(objectName)` that already knows the active tenant.
      */
     private callCtx;
+    /**
+     * [#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.
+     */
+    private resolveQueryTokens;
+    /**
+     * [#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.
+     */
+    private resolvedDatasetScopeGetter;
     /**
      * 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
@@ -644,7 +683,7 @@ declare class AnalyticsService implements IAnalyticsService {
      * aggregate bridge) instead of failing — or worse, fabricating empty rows.
      * Any other error propagates untouched.
      */
-    query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
+    query(queryInput: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
     /**
      * [#8286] Withhold the executed statement unless this host enabled the echo.
      *
@@ -686,7 +725,7 @@ declare class AnalyticsService implements IAnalyticsService {
     /**
      * Generate SQL for a query without executing it (dry-run).
      */
-    generateSql(query: AnalyticsQuery, context?: ExecutionContext): Promise<{
+    generateSql(queryInput: AnalyticsQuery, context?: ExecutionContext): Promise<{
         sql: string;
         params: unknown[];
     }>;
@@ -922,10 +961,28 @@ interface AnalyticsServicePluginOptions {
      */
     executeAggregate?: (objectName: string, options: {
         groupBy?: string[];
+        /**
+         * The CUSTOM bridge's view of the aggregation entries — an app author's
+         * own `executeAggregate`, as opposed to the auto-bridge below. Mirrors
+         * `StrategyContext.executeAggregate`
+         * (`packages/spec/src/contracts/analytics-service.ts`) and must stay in
+         * lockstep with it; the two members that lockstep is load-bearing for:
+         *
+         * - `filter` (#10576, the #10413 contract field) — a custom bridge MUST
+         *   forward it to the real engine the same way the auto-bridge does, or a
+         *   measure-scoped filter this plugin lowers onto the aggregation
+         *   silently never reaches storage.
+         * - `method` is the spec's OWN six-value `AggregationFunction`, not
+         *   `string`: #12776 narrowed the contract, #12940 brought this mirror
+         *   back into line. This is the declaration a custom-bridge author types
+         *   their handler against, so it is where the compile-time vocabulary
+         *   #12776 bought for strategy authors reaches them too.
+         */
         aggregations?: Array<{
             field: string;
-            method: string;
+            method: AggregationFunction;
             alias: string;
+            filter?: Record<string, unknown>;
         }>;
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
@@ -1308,6 +1365,11 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      */
     private lookupMember;
     private resolveDimensionSql;
+    /**
+     * @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.
+     */
     private resolveMeasureSql;
     private resolveFieldSql;
     /**
@@ -1443,6 +1505,92 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private withReadScope;
     /** Is `field` a resolved cross-object (relationship-traversal) reference? */
     private isCrossObjectField;
+    /**
+     * 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.
+     *
+     * ## 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
+     * `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.
+     *
+     * [#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
+     * 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.
+     *
+     * 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
+     * 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.
+     */
+    private filterMemberView;
     /**
      * Plan how to serve cross-object references on this join-less path (#3654).
      *
@@ -1453,21 +1601,39 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
-     * 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.
-     *
-     * [#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.
+     * (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 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 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); 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
+     * 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, #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 their neighbours — this engine cannot join this
+     * member — and splitting the code by PROVENANCE would make a caller branch on
+     * 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.
@@ -1485,6 +1651,23 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * are simply absent from the map (⇒ RESTRICTED bucket downstream).
      */
     private resolveFkAttr;
+    /**
+     * 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.
+     */
+    private conditionalAggregateSql;
     /**
      * Render one normalized filter as a display SQL predicate for `generateSql`.
      *