@objectstack/service-analytics 17.2.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. */
@@ -1465,7 +1522,7 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
@@ -1480,6 +1537,36 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
@@ -1489,9 +1576,12 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * `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
@@ -1513,18 +1603,20 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
@@ -1533,14 +1625,15 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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.
@@ -1558,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. */
@@ -1465,7 +1522,7 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
@@ -1480,6 +1537,36 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
@@ -1489,9 +1576,12 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * `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
@@ -1513,18 +1603,20 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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
@@ -1533,14 +1625,15 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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.
@@ -1558,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`.
      *