@objectstack/service-analytics 17.0.0-rc.1 → 17.0.0-rc.2

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { IAnalyticsService, Logger, DriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, DatasetSelection, CubeMeta, DatasetCompareTo, StrategyContext } from '@objectstack/spec/contracts';
-export { AnalyticsStrategy, DatasetSelection, DriverCapabilities, StrategyContext } from '@objectstack/spec/contracts';
+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 { ExecutionContext } from '@objectstack/spec/kernel';
 import { Dataset } from '@objectstack/spec/ui';
@@ -268,7 +268,7 @@ interface AnalyticsServiceConfig {
      * Probe driver capabilities for the object that backs a cube.
      * The service calls this function to decide which strategy can handle a query.
      */
-    queryCapabilities?: (cubeName: string) => DriverCapabilities;
+    queryCapabilities?: (cubeName: string) => AnalyticsDriverCapabilities;
     /**
      * Execute raw SQL on the driver for a given object.
      * Required for NativeSQLStrategy.
@@ -370,6 +370,26 @@ interface AnalyticsServiceConfig {
      * always wires it.
      */
     isRegisteredObject?: (name: string) => boolean;
+    /**
+     * [#4437] The FIELD NAMES `objectName` declares, or `undefined` when nothing
+     * authoritative can answer.
+     *
+     * Consulted by {@link AnalyticsService.ensureCube} to validate the SOURCE
+     * FIELD a measure resolves to BEFORE any SQL is built. `inferMeasure` maps a
+     * suffix convention onto a field name (`ghost_sum` → `SUM(ghost)`) and used
+     * to accept any spelling, so a typo'd measure reached the driver as a column
+     * and came back as an opaque `500 SQLITE_ERROR` — a driver error class on the
+     * wire for a caller-shaped mistake (ADR-0112). The DATA route already refuses
+     * the same mistake with a `400 INVALID_FIELD` naming the field (#4315/#4254);
+     * this hook is what lets the ANALYTICS route give the same answer.
+     *
+     * Same tiering as {@link isRegisteredObject}: absence means "skip the check"
+     * (registry-less hosts, engine doubles, external datasources whose columns
+     * are not mirrored locally). The production bridge in `plugin.ts` wires it
+     * from the same schema registry the data path's gate reads, so "which fields
+     * exist" has ONE answer across `/data` and `/analytics`.
+     */
+    getObjectFieldNames?: (objectName: string) => readonly string[] | undefined;
     /**
      * ADR-0021 — optional object-graph resolver used when compiling datasets:
      * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -377,15 +397,23 @@ interface AnalyticsServiceConfig {
      */
     relationshipResolver?: RelationshipResolver;
     /**
-     * ADR-0053 currency chain — resolve a measure's SOURCE FIELD currency
-     * metadata so a monetary measure that omits an explicit `currency` falls back
-     * to the field's declared currency, then the tenant default (`ctx.currency`).
-     * Returns the source field's `type` and (fixed-mode) `defaultCurrency`;
-     * `undefined` for an unknown field. Non-`currency` fields never get a code.
+     * Resolve the metadata of a dimension's or measure's SOURCE FIELD on the
+     * dataset's base object — the one seam through which display semantics that
+     * live on the field reach the result columns. `undefined` for an unknown
+     * field. Feeds three chains:
+     *
+     * - ADR-0053 currency: a monetary measure that omits an explicit `currency`
+     *   falls back to the field's declared currency, then the tenant default
+     *   (`ctx.currency`). Non-`currency` fields never get a code.
+     * - Percent scale (objectui#3136): a measure over a `percent` field inherits
+     *   that field's storage scale via `percentScaleOf`, so a renderer scales by
+     *   declared metadata instead of guessing from the value.
+     * - Date bucketing: a date vs datetime dimension drills by the right bound.
      */
-    measureCurrency?: (object: string, field: string) => {
+    sourceFieldMeta?: (object: string, field: string) => {
         type?: string;
         defaultCurrency?: string;
+        max?: number;
     } | undefined;
     /** Pre-defined datasets to compile + register at construction (ADR-0021). */
     datasets?: Dataset[];
@@ -436,13 +464,15 @@ declare class AnalyticsService implements IAnalyticsService {
     private readonly datasetRegistry;
     /** Optional object-graph resolver used when compiling datasets. */
     private readonly relationshipResolver?;
-    private readonly measureCurrency?;
+    private readonly sourceFieldMeta?;
     /** Optional dimension display-label resolver (select options / lookup names). */
     private readonly labelResolver?;
     /** ADR-0037 P3: pending-seed row resolver for draft data preview. */
     private readonly draftRowsResolver?;
     /** [#3867] Schema-registry probe gating cube auto-inference. */
     private readonly isRegisteredObject?;
+    /** [#4437] Field-name probe gating measure source-field resolution. */
+    private readonly getObjectFieldNames?;
     /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
     private warnedNoObjectRegistry;
     readonly cubeRegistry: CubeRegistry;
@@ -519,6 +549,35 @@ declare class AnalyticsService implements IAnalyticsService {
      *   strategies pick the right aggregation function and field.
      */
     private ensureCube;
+    /**
+     * [#4437] Reject a measure whose SOURCE FIELD the backing object does not
+     * have, BEFORE the strategy compiles it into SQL.
+     *
+     * `inferMeasure` maps a suffix convention onto a field name and has no way to
+     * know whether that field exists: `ghost_sum` happily became `SUM(ghost)`, the
+     * driver threw `no such column`, and the caller got
+     * `500 {"code":"SQLITE_ERROR","message":"Internal server error"}` — a driver
+     * error class on the wire, and nothing actionable, for what is a plain typo.
+     * The DATA route has refused the same mistake with a `400 INVALID_FIELD`
+     * naming the field since #4315/#4254; this is the analytics half of that
+     * answer, and it is deliberately the SAME envelope (`code`/`field`/`object`/
+     * `param`) so one mistake has one shape across both routes.
+     *
+     * What it checks, and what it deliberately does not:
+     *
+     * - Only when the cube's `sql` is a bare OBJECT NAME. An authored cube whose
+     *   `sql` is a real SQL expression has no field list to check against.
+     * - Only when {@link AnalyticsServiceConfig.getObjectFieldNames} answers.
+     *   Absent hook / unknown object → stand down (see the config field's doc).
+     * - Only measures whose source is a BARE COLUMN. `count(*)` has no source
+     *   field, and a dotted reference (`account.industry`) resolves through a
+     *   join whose target this check cannot see — both pass through untouched.
+     * - `id` / `created_at` / `updated_at` are admitted unconditionally, matching
+     *   the data path's `resolveQueryFields`: they are engine-assigned rather than
+     *   declared, and a gate stricter than the engine it guards would reject
+     *   queries that used to work.
+     */
+    private assertMeasureFields;
     /**
      * [#3867] Gate on the cube auto-inference path: a name with no registered
      * Cube may only be inferred into one if it is a registered object.
@@ -553,7 +612,7 @@ interface AnalyticsServicePluginOptions {
      * Probe driver capabilities for a given cube.
      * When omitted, defaults to in-memory only.
      */
-    queryCapabilities?: (cubeName: string) => DriverCapabilities;
+    queryCapabilities?: (cubeName: string) => AnalyticsDriverCapabilities;
     /**
      * Execute raw SQL on a driver. Enables NativeSQLStrategy.
      */
@@ -633,6 +692,14 @@ declare class AnalyticsServicePlugin implements Plugin {
     version: string;
     type: "standard";
     dependencies: string[];
+    /**
+     * init() probes the `data` engine ObjectQLPlugin provides for the
+     * auto-bridge — order-if-present so the probe verdict is deterministic
+     * (ADR-0116, #4471). Soft, not hard: without an engine the plugin
+     * degrades on purpose (per-query lazy resolution / explicit
+     * `executeAggregate`).
+     */
+    optionalDependencies: string[];
     private service?;
     private readonly options;
     constructor(options?: AnalyticsServicePluginOptions);
@@ -650,6 +717,50 @@ declare function combineFilters(a?: FilterCondition, b?: FilterCondition): Filte
  * Division by zero (and missing operands) yields `null` rather than Infinity/NaN.
  */
 declare function evaluateDerivedMeasures(rows: Record<string, unknown>[], derived: DerivedMeasureSpec[]): Record<string, unknown>[];
+/**
+ * Fill the EMPTY-GROUP value into every measure column the assembled grid
+ * LISTS but no query REPORTED — by aggregate kind (#4708, objectui#3136).
+ *
+ * The grid is assembled from several results: the primary query, one
+ * supplementary query per measure-scoped filter, and (for `compareTo`) a
+ * shifted pass. {@link mergeByDimensions} writes a measure's column only onto
+ * rows its source result returned, and a `GROUP BY` over a filtered row set
+ * emits NO group at all for a dimension value the filter excludes entirely.
+ * The column therefore comes back **absent**, not `0` — and absent renders as
+ * "no data for this row", which for a count is the opposite of what the row
+ * means. A derived ratio over it goes null as well ({@link computeDerived}
+ * treats a missing operand as unknowable), so the blank spreads.
+ *
+ * The bias runs the worst possible way: the rows that blank are the ones whose
+ * numerator the filter excluded — the WORST-performing rows. A `lead_source`
+ * that won nothing renders as "no data" while one that won everything renders
+ * fine.
+ *
+ * **Filled strictly by aggregate kind**, never wholesale. `count` /
+ * `count_distinct` over an excluded group is unambiguously `0` ("how many rows
+ * matched" has an exact answer when the answer is none), and `sum` over the
+ * empty set is its identity `0`. `avg` / `min` / `max` are genuinely null —
+ * there is nothing to average — and flattening those to `0` would trade this
+ * lie for the opposite one, reporting a measurement nobody made. The
+ * kind→identity mapping is `emptyGroupValueFor` in `@objectstack/spec/data`,
+ * shared with the authoring-side coherence checks so the two cannot drift.
+ *
+ * **Only rows that already exist are touched** — no group is invented. A
+ * dimension value no query reported at all has genuinely no data and stays out
+ * of the grid; this fills the cell, never the row.
+ *
+ * Deliberately NOT a `?? 0` in the widget or a `coalesce` in the measure: a
+ * consumer-side patch must be repeated by every author of every ratio widget
+ * forever, and forgetting it is silent. Only the executor knows which aggregate
+ * produced the gap, so only the executor can tell `0` from unknown.
+ *
+ * Mutates `rows` in place (they are already this pipeline's own copies) and
+ * returns them for chaining.
+ *
+ * @param columnAggregates - Grid column → the aggregate that produced it.
+ *   Includes `<measure>__compare` columns, which merge through the same seam.
+ */
+declare function fillEmptyGroups(rows: Record<string, unknown>[], columnAggregates: Record<string, string | undefined>): Record<string, unknown>[];
 /** Compute the comparison window for a [start,end] range. */
 declare function shiftRange(range: [string, string], kind: CompareTo['kind']): [string, string];
 declare class DatasetExecutor {
@@ -673,6 +784,37 @@ declare class DatasetExecutor {
      */
     execute(compiledInput: CompiledDataset, selectionInput: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     private executeSelection;
+    /**
+     * Run ONE grouped pass over a set of base measures, honouring each measure's
+     * own scoped `filter`: the unfiltered measures in a single query, plus one
+     * supplementary query per filter-scoped measure, merged back by dimension key.
+     *
+     * **This is the executor's only implementation of "how a measure filter is
+     * applied", and every window goes through it** — the current period, each
+     * `totals` subset (which re-enters via `executeSelection`), and the
+     * `compareTo` window. Before #4820 the comparison window had its own,
+     * simpler answer: one shifted query over all base measures with only the
+     * base filter, so `compiled.measureFilters` was never read on that path.
+     * `won_count` counted won deals and `won_count__compare` counted every deal,
+     * under one label, in adjacent columns. Only measures carrying a filter were
+     * wrong — which is what made it survive: the unfiltered ones next to them
+     * compared correctly.
+     *
+     * The caller supplies the `selection` this pass queries under, which is how
+     * the comparison window differs at all: same measures, same dimensions, same
+     * filters — a `timeDimensions` shifted by {@link shiftRange}. Nothing else
+     * about the two passes may drift, because anything that does becomes a
+     * discrepancy between two columns the reader is invited to subtract.
+     *
+     * Cost: one extra query per filter-scoped measure when `compareTo` is set.
+     * The alternative — declaring the discrepancy in the response — is not one,
+     * since the two columns exist to be directly comparable.
+     *
+     * @param window - Ordering/window to push into the SQL. Only ever set for a
+     *   selection the caller proved is a single self-sufficient query; a pass
+     *   that fans out must return its whole grid for the merge.
+     */
+    private runMeasurePass;
     /**
      * The selected dimensions the compiled cube types as `time`, in selection
      * order (#3916) — the axis {@link resolveOrdering} defaults to ascending.
@@ -1038,4 +1180,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type OrderLabelResolver, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, createOrderLabelResolver, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange, withLabelFetchCache };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type OrderLabelResolver, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, createOrderLabelResolver, evaluateDerivedMeasures, fillEmptyGroups, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange, withLabelFetchCache };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { IAnalyticsService, Logger, DriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, DatasetSelection, CubeMeta, DatasetCompareTo, StrategyContext } from '@objectstack/spec/contracts';
-export { AnalyticsStrategy, DatasetSelection, DriverCapabilities, StrategyContext } from '@objectstack/spec/contracts';
+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 { ExecutionContext } from '@objectstack/spec/kernel';
 import { Dataset } from '@objectstack/spec/ui';
@@ -268,7 +268,7 @@ interface AnalyticsServiceConfig {
      * Probe driver capabilities for the object that backs a cube.
      * The service calls this function to decide which strategy can handle a query.
      */
-    queryCapabilities?: (cubeName: string) => DriverCapabilities;
+    queryCapabilities?: (cubeName: string) => AnalyticsDriverCapabilities;
     /**
      * Execute raw SQL on the driver for a given object.
      * Required for NativeSQLStrategy.
@@ -370,6 +370,26 @@ interface AnalyticsServiceConfig {
      * always wires it.
      */
     isRegisteredObject?: (name: string) => boolean;
+    /**
+     * [#4437] The FIELD NAMES `objectName` declares, or `undefined` when nothing
+     * authoritative can answer.
+     *
+     * Consulted by {@link AnalyticsService.ensureCube} to validate the SOURCE
+     * FIELD a measure resolves to BEFORE any SQL is built. `inferMeasure` maps a
+     * suffix convention onto a field name (`ghost_sum` → `SUM(ghost)`) and used
+     * to accept any spelling, so a typo'd measure reached the driver as a column
+     * and came back as an opaque `500 SQLITE_ERROR` — a driver error class on the
+     * wire for a caller-shaped mistake (ADR-0112). The DATA route already refuses
+     * the same mistake with a `400 INVALID_FIELD` naming the field (#4315/#4254);
+     * this hook is what lets the ANALYTICS route give the same answer.
+     *
+     * Same tiering as {@link isRegisteredObject}: absence means "skip the check"
+     * (registry-less hosts, engine doubles, external datasources whose columns
+     * are not mirrored locally). The production bridge in `plugin.ts` wires it
+     * from the same schema registry the data path's gate reads, so "which fields
+     * exist" has ONE answer across `/data` and `/analytics`.
+     */
+    getObjectFieldNames?: (objectName: string) => readonly string[] | undefined;
     /**
      * ADR-0021 — optional object-graph resolver used when compiling datasets:
      * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -377,15 +397,23 @@ interface AnalyticsServiceConfig {
      */
     relationshipResolver?: RelationshipResolver;
     /**
-     * ADR-0053 currency chain — resolve a measure's SOURCE FIELD currency
-     * metadata so a monetary measure that omits an explicit `currency` falls back
-     * to the field's declared currency, then the tenant default (`ctx.currency`).
-     * Returns the source field's `type` and (fixed-mode) `defaultCurrency`;
-     * `undefined` for an unknown field. Non-`currency` fields never get a code.
+     * Resolve the metadata of a dimension's or measure's SOURCE FIELD on the
+     * dataset's base object — the one seam through which display semantics that
+     * live on the field reach the result columns. `undefined` for an unknown
+     * field. Feeds three chains:
+     *
+     * - ADR-0053 currency: a monetary measure that omits an explicit `currency`
+     *   falls back to the field's declared currency, then the tenant default
+     *   (`ctx.currency`). Non-`currency` fields never get a code.
+     * - Percent scale (objectui#3136): a measure over a `percent` field inherits
+     *   that field's storage scale via `percentScaleOf`, so a renderer scales by
+     *   declared metadata instead of guessing from the value.
+     * - Date bucketing: a date vs datetime dimension drills by the right bound.
      */
-    measureCurrency?: (object: string, field: string) => {
+    sourceFieldMeta?: (object: string, field: string) => {
         type?: string;
         defaultCurrency?: string;
+        max?: number;
     } | undefined;
     /** Pre-defined datasets to compile + register at construction (ADR-0021). */
     datasets?: Dataset[];
@@ -436,13 +464,15 @@ declare class AnalyticsService implements IAnalyticsService {
     private readonly datasetRegistry;
     /** Optional object-graph resolver used when compiling datasets. */
     private readonly relationshipResolver?;
-    private readonly measureCurrency?;
+    private readonly sourceFieldMeta?;
     /** Optional dimension display-label resolver (select options / lookup names). */
     private readonly labelResolver?;
     /** ADR-0037 P3: pending-seed row resolver for draft data preview. */
     private readonly draftRowsResolver?;
     /** [#3867] Schema-registry probe gating cube auto-inference. */
     private readonly isRegisteredObject?;
+    /** [#4437] Field-name probe gating measure source-field resolution. */
+    private readonly getObjectFieldNames?;
     /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
     private warnedNoObjectRegistry;
     readonly cubeRegistry: CubeRegistry;
@@ -519,6 +549,35 @@ declare class AnalyticsService implements IAnalyticsService {
      *   strategies pick the right aggregation function and field.
      */
     private ensureCube;
+    /**
+     * [#4437] Reject a measure whose SOURCE FIELD the backing object does not
+     * have, BEFORE the strategy compiles it into SQL.
+     *
+     * `inferMeasure` maps a suffix convention onto a field name and has no way to
+     * know whether that field exists: `ghost_sum` happily became `SUM(ghost)`, the
+     * driver threw `no such column`, and the caller got
+     * `500 {"code":"SQLITE_ERROR","message":"Internal server error"}` — a driver
+     * error class on the wire, and nothing actionable, for what is a plain typo.
+     * The DATA route has refused the same mistake with a `400 INVALID_FIELD`
+     * naming the field since #4315/#4254; this is the analytics half of that
+     * answer, and it is deliberately the SAME envelope (`code`/`field`/`object`/
+     * `param`) so one mistake has one shape across both routes.
+     *
+     * What it checks, and what it deliberately does not:
+     *
+     * - Only when the cube's `sql` is a bare OBJECT NAME. An authored cube whose
+     *   `sql` is a real SQL expression has no field list to check against.
+     * - Only when {@link AnalyticsServiceConfig.getObjectFieldNames} answers.
+     *   Absent hook / unknown object → stand down (see the config field's doc).
+     * - Only measures whose source is a BARE COLUMN. `count(*)` has no source
+     *   field, and a dotted reference (`account.industry`) resolves through a
+     *   join whose target this check cannot see — both pass through untouched.
+     * - `id` / `created_at` / `updated_at` are admitted unconditionally, matching
+     *   the data path's `resolveQueryFields`: they are engine-assigned rather than
+     *   declared, and a gate stricter than the engine it guards would reject
+     *   queries that used to work.
+     */
+    private assertMeasureFields;
     /**
      * [#3867] Gate on the cube auto-inference path: a name with no registered
      * Cube may only be inferred into one if it is a registered object.
@@ -553,7 +612,7 @@ interface AnalyticsServicePluginOptions {
      * Probe driver capabilities for a given cube.
      * When omitted, defaults to in-memory only.
      */
-    queryCapabilities?: (cubeName: string) => DriverCapabilities;
+    queryCapabilities?: (cubeName: string) => AnalyticsDriverCapabilities;
     /**
      * Execute raw SQL on a driver. Enables NativeSQLStrategy.
      */
@@ -633,6 +692,14 @@ declare class AnalyticsServicePlugin implements Plugin {
     version: string;
     type: "standard";
     dependencies: string[];
+    /**
+     * init() probes the `data` engine ObjectQLPlugin provides for the
+     * auto-bridge — order-if-present so the probe verdict is deterministic
+     * (ADR-0116, #4471). Soft, not hard: without an engine the plugin
+     * degrades on purpose (per-query lazy resolution / explicit
+     * `executeAggregate`).
+     */
+    optionalDependencies: string[];
     private service?;
     private readonly options;
     constructor(options?: AnalyticsServicePluginOptions);
@@ -650,6 +717,50 @@ declare function combineFilters(a?: FilterCondition, b?: FilterCondition): Filte
  * Division by zero (and missing operands) yields `null` rather than Infinity/NaN.
  */
 declare function evaluateDerivedMeasures(rows: Record<string, unknown>[], derived: DerivedMeasureSpec[]): Record<string, unknown>[];
+/**
+ * Fill the EMPTY-GROUP value into every measure column the assembled grid
+ * LISTS but no query REPORTED — by aggregate kind (#4708, objectui#3136).
+ *
+ * The grid is assembled from several results: the primary query, one
+ * supplementary query per measure-scoped filter, and (for `compareTo`) a
+ * shifted pass. {@link mergeByDimensions} writes a measure's column only onto
+ * rows its source result returned, and a `GROUP BY` over a filtered row set
+ * emits NO group at all for a dimension value the filter excludes entirely.
+ * The column therefore comes back **absent**, not `0` — and absent renders as
+ * "no data for this row", which for a count is the opposite of what the row
+ * means. A derived ratio over it goes null as well ({@link computeDerived}
+ * treats a missing operand as unknowable), so the blank spreads.
+ *
+ * The bias runs the worst possible way: the rows that blank are the ones whose
+ * numerator the filter excluded — the WORST-performing rows. A `lead_source`
+ * that won nothing renders as "no data" while one that won everything renders
+ * fine.
+ *
+ * **Filled strictly by aggregate kind**, never wholesale. `count` /
+ * `count_distinct` over an excluded group is unambiguously `0` ("how many rows
+ * matched" has an exact answer when the answer is none), and `sum` over the
+ * empty set is its identity `0`. `avg` / `min` / `max` are genuinely null —
+ * there is nothing to average — and flattening those to `0` would trade this
+ * lie for the opposite one, reporting a measurement nobody made. The
+ * kind→identity mapping is `emptyGroupValueFor` in `@objectstack/spec/data`,
+ * shared with the authoring-side coherence checks so the two cannot drift.
+ *
+ * **Only rows that already exist are touched** — no group is invented. A
+ * dimension value no query reported at all has genuinely no data and stays out
+ * of the grid; this fills the cell, never the row.
+ *
+ * Deliberately NOT a `?? 0` in the widget or a `coalesce` in the measure: a
+ * consumer-side patch must be repeated by every author of every ratio widget
+ * forever, and forgetting it is silent. Only the executor knows which aggregate
+ * produced the gap, so only the executor can tell `0` from unknown.
+ *
+ * Mutates `rows` in place (they are already this pipeline's own copies) and
+ * returns them for chaining.
+ *
+ * @param columnAggregates - Grid column → the aggregate that produced it.
+ *   Includes `<measure>__compare` columns, which merge through the same seam.
+ */
+declare function fillEmptyGroups(rows: Record<string, unknown>[], columnAggregates: Record<string, string | undefined>): Record<string, unknown>[];
 /** Compute the comparison window for a [start,end] range. */
 declare function shiftRange(range: [string, string], kind: CompareTo['kind']): [string, string];
 declare class DatasetExecutor {
@@ -673,6 +784,37 @@ declare class DatasetExecutor {
      */
     execute(compiledInput: CompiledDataset, selectionInput: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     private executeSelection;
+    /**
+     * Run ONE grouped pass over a set of base measures, honouring each measure's
+     * own scoped `filter`: the unfiltered measures in a single query, plus one
+     * supplementary query per filter-scoped measure, merged back by dimension key.
+     *
+     * **This is the executor's only implementation of "how a measure filter is
+     * applied", and every window goes through it** — the current period, each
+     * `totals` subset (which re-enters via `executeSelection`), and the
+     * `compareTo` window. Before #4820 the comparison window had its own,
+     * simpler answer: one shifted query over all base measures with only the
+     * base filter, so `compiled.measureFilters` was never read on that path.
+     * `won_count` counted won deals and `won_count__compare` counted every deal,
+     * under one label, in adjacent columns. Only measures carrying a filter were
+     * wrong — which is what made it survive: the unfiltered ones next to them
+     * compared correctly.
+     *
+     * The caller supplies the `selection` this pass queries under, which is how
+     * the comparison window differs at all: same measures, same dimensions, same
+     * filters — a `timeDimensions` shifted by {@link shiftRange}. Nothing else
+     * about the two passes may drift, because anything that does becomes a
+     * discrepancy between two columns the reader is invited to subtract.
+     *
+     * Cost: one extra query per filter-scoped measure when `compareTo` is set.
+     * The alternative — declaring the discrepancy in the response — is not one,
+     * since the two columns exist to be directly comparable.
+     *
+     * @param window - Ordering/window to push into the SQL. Only ever set for a
+     *   selection the caller proved is a single self-sufficient query; a pass
+     *   that fans out must return its whole grid for the merge.
+     */
+    private runMeasurePass;
     /**
      * The selected dimensions the compiled cube types as `time`, in selection
      * order (#3916) — the axis {@link resolveOrdering} defaults to ascending.
@@ -1038,4 +1180,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type OrderLabelResolver, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, createOrderLabelResolver, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange, withLabelFetchCache };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type OrderLabelResolver, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, createOrderLabelResolver, evaluateDerivedMeasures, fillEmptyGroups, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange, withLabelFetchCache };