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

package/dist/index.d.ts

@@ -119,6 +119,7 @@ declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolve
  * — reading an object's field map and fetching id→label pairs — are injected via
  * {@link DimensionLabelDeps} so this module stays free of any engine dependency.
  */
+
 /** The minimal field shape this resolver needs. */
 interface FieldMetaLite {
     type?: string;
@@ -138,9 +139,90 @@ interface DimensionLabelDeps {
      * Fetch a map of `id → display label` for the given ids of a target object.
      * The implementation chooses the target's display field. Returning an empty
      * map (e.g. no display field, no data access) leaves the ids unresolved.
+     *
+     * `scope` (ADR-0021 D-C, #3602) is the TARGET object's own read scope — the
+     * RLS/tenant `FilterCondition` the implementation must AND into the label
+     * lookup so this never reveals a related record the target object's RLS would
+     * hide. The label lookup is a per-record read (`group by id`) dressed as an
+     * aggregate; without the scope it leaks display names whenever the referenced
+     * object is more restricted than the base object whose rows carry the id.
+     * `undefined` means "no scope for this object" (global table / unrestricted
+     * caller) — the same contract as the read-scope provider.
+     *
+     * `context` is the request's ExecutionContext — the SECOND belt on the same
+     * read (#3602). `scope` is the analytics layer's own predicate; forwarding the
+     * context lets the ENGINE's middleware chain scope this per-record read
+     * itself, so it stays scoped even if a caller ever reaches this hook without
+     * a resolved `scope`. Implementations bridging to an ObjectQL engine MUST
+     * forward it; a bridge with nowhere to put it may ignore it.
      */
-    fetchRecordLabels(targetObject: string, ids: unknown[]): Promise<Map<unknown, string>>;
+    fetchRecordLabels(targetObject: string, ids: unknown[], scope?: Record<string, unknown>, context?: ExecutionContext): Promise<Map<unknown, string>>;
 }
+/**
+ * Resolve the TARGET object's read scope for a label lookup (#3602). Returns the
+ * object's RLS/tenant `FilterCondition`, `null`/`undefined` when the object is
+ * unscoped, or a rejected promise when the scope cannot be resolved — in which
+ * case the resolver fails CLOSED (skips that dimension's labels) rather than
+ * fetching unscoped names.
+ */
+type LabelScopeResolver = (targetObject: string) => Promise<Record<string, unknown> | null | undefined> | Record<string, unknown> | null | undefined;
+/**
+ * Sort-key label resolution for `DatasetSelection.order` (#3680).
+ *
+ * The executor sorts the assembled grid BEFORE `queryDataset` rewrites stored
+ * dimension values into display labels, so an order key naming a `select` or
+ * `lookup`/`master_detail` dimension used to sort by the stored value / FK id —
+ * an order that presents as arbitrary once the labels render. This hook hands
+ * the executor JUST the value→label mapping for such a dimension so it can sort
+ * by what the user will actually read, while the rows keep their raw values
+ * (drill metadata depends on them) and ordering + windowing stay one adjacent
+ * step. The executor stays engine-free: it sees this interface, never the
+ * engine behind it.
+ */
+interface OrderLabelResolver {
+    /**
+     * Whether the dimension's stored value differs from the label it renders as
+     * (`select` options, `lookup`/`master_detail` FK ids). Synchronous — the
+     * executor consults it when deciding whether the window may be pushed into
+     * SQL, before any query runs.
+     */
+    isLabelBearing(dimension: string): boolean;
+    /**
+     * Map the given raw stored values of one dimension to display labels.
+     * Values missing from the map sort by their raw form — the same thing the
+     * user will see rendered for them.
+     */
+    resolveLabels(dimension: string, values: unknown[]): Promise<Map<unknown, string> | undefined>;
+}
+/**
+ * Build the executor's {@link OrderLabelResolver} from the dataset's dimension
+ * list and the injected label capabilities. Mirrors the classification in
+ * {@link resolveDimensionLabels}: a dimension is label-bearing when its field
+ * carries select `options` or is a lookup/master_detail with a `reference`.
+ *
+ * - `select` resolves from field metadata — no query at all.
+ * - `lookup`/`master_detail` costs ONE batched id→name read over the distinct
+ *   grouped values, scoped to the REFERENCED object's own RLS (#3602). Fail
+ *   closed: an unresolvable scope degrades to sorting by the stored id rather
+ *   than fetching unscoped — consistent with the display pass, which renders
+ *   the raw id in that case too.
+ */
+declare function createOrderLabelResolver(baseObject: string, dims: Array<{
+    name: string;
+    field: string;
+}>, deps: DimensionLabelDeps, resolveScope?: LabelScopeResolver, context?: ExecutionContext): OrderLabelResolver;
+/**
+ * Wrap a {@link DimensionLabelDeps} so repeated `fetchRecordLabels` calls
+ * within ONE request fetch each id at most once. A selection that sorts by a
+ * lookup dimension resolves labels twice — once PRE-window for the sort keys
+ * (#3680, over the full grid's ids), once post-window for display (a subset of
+ * the same ids) — so with this cache the display pass costs no extra query.
+ *
+ * Per-request only: entries are keyed by target object alone, which is safe
+ * because an object's read scope is constant within one request. Never share
+ * an instance across requests.
+ */
+declare function withLabelFetchCache(deps: DimensionLabelDeps): DimensionLabelDeps;
 /** Date-dimension granularity (mirrors the dataset `dateGranularity` enum). */
 type DateGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
 /**
@@ -151,13 +233,22 @@ type DateGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
  *   (row key = `name`)
  * @param rows - result rows, mutated in place
  * @param deps - injected runtime capabilities
+ * @param resolveScope - (ADR-0021 D-C, #3602) resolves the referenced object's
+ *   own read scope for a lookup/master_detail dimension's label fetch. When it
+ *   throws, that dimension's labels are SKIPPED (fail-closed — the raw id renders
+ *   instead) rather than fetched unscoped. Omit when no read-scope provider is
+ *   configured (labels then fetch unscoped, as before — no security in play).
+ * @param context - the request's ExecutionContext, forwarded to
+ *   {@link DimensionLabelDeps.fetchRecordLabels} so the engine's own middleware
+ *   scopes the per-record label read too — the second belt beside `resolveScope`
+ *   (#3602)
  */
 declare function resolveDimensionLabels(baseObject: string, dims: Array<{
     name: string;
     field: string;
     type?: string;
     dateGranularity?: DateGranularity | string;
-}>, rows: Record<string, unknown>[], deps: DimensionLabelDeps): Promise<void>;
+}>, rows: Record<string, unknown>[], deps: DimensionLabelDeps, resolveScope?: LabelScopeResolver, context?: ExecutionContext): Promise<void>;
 /**
  * Pick the display field for an object from its field map, by convention:
  * an explicit `name`/`title`/`label` field, else the first text-like field.
@@ -195,6 +286,15 @@ interface AnalyticsServiceConfig {
             alias: string;
         }>;
         filter?: Record<string, unknown>;
+        /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
+        timezone?: string;
+        /**
+         * ADR-0021 D-C (#3602) — the request's ExecutionContext. Bridges MUST
+         * forward it to `engine.aggregate` so engine-side RLS applies; see
+         * `StrategyContext.executeAggregate` for why this is a second belt rather
+         * than a replacement for `getReadScope`.
+         */
+        context?: ExecutionContext;
     }) => Promise<Record<string, unknown>[]>;
     /**
      * Fallback IAnalyticsService (e.g. MemoryAnalyticsService).
@@ -236,6 +336,14 @@ interface AnalyticsServiceConfig {
      * `StrategyContext.coerceTemporalFilterValue` for the full rationale.
      */
     coerceTemporalFilterValue?: (objectName: string, fieldName: string, value: unknown) => unknown;
+    /**
+     * Normalise the COLUMN side of the same comparison to that storage form — the
+     * other half of the fix, needed because a SQLite `Field.datetime` holds both an
+     * INTEGER epoch (a `Date` write) and ISO TEXT (a REST/JSON write, a `NOW()`
+     * default) at once, so coercing only the comparand matches one of them and
+     * misses the other (#3912). See `StrategyContext.coerceTemporalFilterColumn`.
+     */
+    coerceTemporalFilterColumn?: (objectName: string, fieldName: string, columnSql: string) => string;
     /**
      * ADR-0062 D6 — report whether an object is federated (external datasource).
      * Threaded into the StrategyContext so `NativeSQLStrategy` declines external
@@ -244,6 +352,24 @@ interface AnalyticsServiceConfig {
      * `StrategyContext.isExternalObject`.
      */
     isExternalObject?: (objectName: string) => boolean;
+    /**
+     * [#3867] Is `name` a registered object in this kernel's schema registry?
+     *
+     * Consulted by {@link AnalyticsService.ensureCube} on the auto-inference
+     * path only. When no Cube is registered under the queried name, the service
+     * infers a minimal one whose `sql` IS that name — the intended "metric over
+     * an object" path (an `object-metric` KPI widget queries `crm_account`
+     * without anyone authoring a Cube). Without this hook that inference accepts
+     * ANY string, so an arbitrary physical table name reached the driver: the
+     * analytics-side twin of the data-path gap closed in #3770.
+     *
+     * Optional, and absence means "skip the check" — same tiering as #3770's
+     * `assertObjectRegistered`: with no registry to consult the question cannot
+     * be answered, and failing closed would break every embedding that runs
+     * analytics without a data engine. The production bridge in `plugin.ts`
+     * always wires it.
+     */
+    isRegisteredObject?: (name: string) => boolean;
     /**
      * ADR-0021 — optional object-graph resolver used when compiling datasets:
      * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -315,6 +441,10 @@ declare class AnalyticsService implements IAnalyticsService {
     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?;
+    /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
+    private warnedNoObjectRegistry;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -389,6 +519,20 @@ declare class AnalyticsService implements IAnalyticsService {
      *   strategies pick the right aggregation function and field.
      */
     private ensureCube;
+    /**
+     * [#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.
+     *
+     * Rejects with `status: 404` / `code: 'CUBE_NOT_FOUND'` so the HTTP boundary
+     * answers "no such cube" instead of letting the name reach the driver as a
+     * table and surfacing whatever the driver says about it. The message names
+     * both ways the request could be made valid, because from here the two are
+     * genuinely indistinguishable: register a Cube, or register the object.
+     *
+     * Skips when `isRegisteredObject` was not supplied — see the config field's
+     * doc for why that tier is a deliberate stand-down and not a hole.
+     */
+    private assertInferableCube;
     /** Build a minimal Cube from the fields referenced by an AnalyticsQuery. */
     private inferCubeFromQuery;
     /**
@@ -427,6 +571,12 @@ interface AnalyticsServicePluginOptions {
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
         timezone?: string;
+        /**
+         * ADR-0021 D-C (#3602) — the request's ExecutionContext. A custom bridge
+         * MUST forward it to its engine so engine-side RLS applies; dropping it is
+         * what made the built-in bridge fall open in #3597.
+         */
+        context?: ExecutionContext;
     }) => Promise<Record<string, unknown>[]>;
     /**
      * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). The
@@ -475,6 +625,11 @@ interface AnalyticsServicePluginOptions {
  */
 declare class AnalyticsServicePlugin implements Plugin {
     name: string;
+    /**
+     * Services init() registers on every path (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires one before it inits.
+     */
+    providesServices: string[];
     version: string;
     type: "standard";
     dependencies: string[];
@@ -488,25 +643,6 @@ declare class AnalyticsServicePlugin implements Plugin {
 
 /** @deprecated use DatasetCompareTo from @objectstack/spec/contracts */
 type CompareTo = DatasetCompareTo;
-/**
- * Dataset executor (ADR-0021 WS2).
- *
- * Turns a compiled dataset + a presentation's selection (dimensions, measures,
- * runtime filter, compareTo) into one or more `AnalyticsQuery`s against the Cube
- * runtime, then post-processes the results:
- *   - resolves the base measures a selection needs (including derived deps),
- *   - applies measure-scoped filters via supplementary grouped queries,
- *   - evaluates derived measures (ratio/sum/difference/product) row-by-row (Q1),
- *   - shifts the query for `compareTo` (previousPeriod / previousYear) and
- *     attaches `<measure>__compare` columns,
- *   - computes server-side totals (`selection.totals.groupings`, #1753) by
- *     re-running the selection per dimension subset, so matrix subtotals and
- *     the grand total use each measure's true aggregate.
- *
- * RLS/tenant scoping is NOT handled here — it is enforced inside the strategy
- * via the StrategyContext read-scope hook (D-C). This layer is pure query
- * shaping + arithmetic.
- */
 /** AND two optional FilterConditions into one (MongoDB-style). */
 declare function combineFilters(a?: FilterCondition, b?: FilterCondition): FilterCondition | undefined;
 /**
@@ -518,7 +654,16 @@ declare function evaluateDerivedMeasures(rows: Record<string, unknown>[], derive
 declare function shiftRange(range: [string, string], kind: CompareTo['kind']): [string, string];
 declare class DatasetExecutor {
     private readonly service;
-    constructor(service: IAnalyticsService);
+    private readonly orderLabels?;
+    /**
+     * @param service - The analytics service the executor issues its queries to.
+     * @param orderLabels - Optional sort-key label hook (#3680). When provided,
+     *   an order key naming a label-bearing (`select`/`lookup`) dimension sorts
+     *   by its display label instead of the stored value. Omit to sort by stored
+     *   values everywhere (e.g. the draft-preview path, whose seed rows already
+     *   carry display names).
+     */
+    constructor(service: IAnalyticsService, orderLabels?: OrderLabelResolver | undefined);
     /**
      * Execute a dataset selection and return the shaped rows (+ field metadata).
      *
@@ -526,8 +671,19 @@ declare class DatasetExecutor {
      *   underlying `IAnalyticsService.query` so the tenant/RLS read scope is
      *   applied per request (ADR-0021 D-C).
      */
-    execute(compiled: CompiledDataset, selection: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
+    execute(compiledInput: CompiledDataset, selectionInput: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     private executeSelection;
+    /**
+     * The selected dimensions the compiled cube types as `time`, in selection
+     * order (#3916) — the axis {@link resolveOrdering} defaults to ascending.
+     *
+     * Membership is decided by the DIMENSION's declared type, not by whether the
+     * selection happens to bucket it: a `date` dimension left ungranulated groups
+     * raw timestamps, and those want chronological order every bit as much as
+     * month buckets do. (Both sort correctly — `compareValues` compares Dates and
+     * ISO strings chronologically, and bucket keys are minted sort-stable.)
+     */
+    private timeDimensionsOf;
     private buildQuery;
     private runCompare;
 }
@@ -549,6 +705,12 @@ declare function compileScopedFilterToSql(filter: FilterCondition, alias: string
  * Pushes the analytics query down to the database as a native SQL statement.
  * This is the most efficient path and is preferred whenever the backing driver
  * supports raw SQL execution (e.g. Postgres, MySQL, SQLite).
+ *
+ * `resolveMeasureSql` used to answer `COUNT(*)` to three different questions it
+ * could not otherwise answer — an undeclared measure, a custom-SQL-expression
+ * metric type, and an unrecognised type. All three returned a plausible number
+ * for a query that asked for something else. They now emit the expression or
+ * throw; see that method. #4157.
  */
 declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
@@ -635,6 +797,34 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      * correctly.
      */
     private coerceTemporal;
+    /**
+     * The column side of {@link coerceTemporal}: normalise the reference so it
+     * reads in the storage form the comparand was coerced into.
+     *
+     * A SQLite `Field.datetime` column carries an INTEGER epoch (a `Date` write)
+     * and ISO TEXT (a REST/JSON write, a `NOW()` default — including the platform's
+     * own `created_at`) at the SAME time, so coercing the value alone fixes one half
+     * and empties the other. That is #3912: a `dateRange: last_30_days` on
+     * `created_date` read 0 with 29 rows in range. Every other column and dialect
+     * gets its reference back verbatim.
+     */
+    private temporalColumn;
+    /**
+     * Compile a normalized filter node into a boolean SQL expression, recursing
+     * through the combinators. `null` = no constraint.
+     *
+     * Leaves go through {@link buildFilterClause} exactly as they did when this
+     * was a flat loop, so the storage-form coercion and the calendar-day
+     * upper-bound rule (#3777) apply at every depth — including inside an `$or`,
+     * where a second, combinator-aware implementation would have been free to
+     * drift from the first.
+     *
+     * Parenthesisation is explicit rather than left to SQL's precedence: `AND`
+     * does bind tighter than `OR`, so `a AND b OR c` happens to be right, but
+     * being right by construction is what keeps a future edit from making it
+     * wrong.
+     */
+    private compileFilterNode;
     private buildFilterClause;
     private extractObjectName;
     private buildFieldMeta;
@@ -652,10 +842,83 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     readonly priority = 20;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
     execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult>;
+    /**
+     * Render a REPRESENTATIVE SQL string for an ObjectQL aggregate query.
+     *
+     * This path executes through `engine.aggregate()`, not raw SQL, so the string
+     * is documentation rather than the literal statement — but it must be an
+     * honest account of what the query does, because dataset responses echo it
+     * and authors read it to verify their widget options landed (#3588). It
+     * therefore renders date bucketing (`date_trunc`), the WHERE predicate,
+     * ordering, and the row window.
+     *
+     * Filter VALUES are rendered as `$n` placeholders and returned in `params`,
+     * never inlined: the echoed statement travels to the browser, and a filter
+     * comparand can carry tenant data.
+     */
     generateSql(query: AnalyticsQuery, ctx: StrategyContext): Promise<{
         sql: string;
         params: unknown[];
     }>;
+    /**
+     * ADR-0021 D-C (#3597) — AND the object's read scope (tenant + RLS) into the
+     * filter handed to `engine.aggregate`.
+     *
+     * This path used to drop the scope entirely, and the engine could not make up
+     * for it: the aggregate bridge passes no `ExecutionContext`, so the security
+     * middleware's principal-less fall-open skipped its own RLS injection. Both
+     * belts were off at once — an authenticated caller received aggregates
+     * computed over EVERY tenant's rows.
+     *
+     * Composed with `$and`, never by key merge: the query's own filter and the
+     * scope can name the SAME field (e.g. a dashboard filtering `organization_id`),
+     * and a spread would let caller input silently overwrite the security
+     * predicate. `$and` makes that structurally impossible.
+     */
+    private withReadScope;
+    /** Is `field` a resolved cross-object (relationship-traversal) reference? */
+    private isCrossObjectField;
+    /**
+     * Plan how to serve cross-object references on this join-less path (#3654).
+     *
+     * `engine.aggregate()` cannot join. A cross-object DIMENSION within a
+     * supported envelope is served by an FK-expand (`executeCrossObject`): group
+     * the base aggregate on the lookup FK, resolve the FK to the related attribute
+     * with a SCOPED read, re-bucket in memory. Returns `null` for a base-only
+     * 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.
+     *
+     * Detection is on RESOLVED field names, so a dotted dimension the cube
+     * flattens to a real column is treated as base, not cross-object.
+     */
+    private planCrossObject;
+    /**
+     * Serve a cross-object-dimension query by FK-expand (#3654). The pure
+     * re-bucketing step lives in `cross-object-rebucket.ts`.
+     */
+    private executeCrossObject;
+    /**
+     * Resolve `fkValues` (ids of `refObject`) to their `attr` values, applying the
+     * referenced object's OWN read scope (#3654 / #3602). Reuses the aggregate
+     * bridge — `group by (id, attr)` is one row per record. Ids the scope hides
+     * are simply absent from the map (⇒ RESTRICTED bucket downstream).
+     */
+    private resolveFkAttr;
+    /**
+     * Render one normalized filter as a display SQL predicate for `generateSql`.
+     *
+     * Mirrors `NativeSQLStrategy.buildFilterClause`'s operator vocabulary so the
+     * two previews read alike, but binds through `coerceFilterValueForObjectQL`:
+     * the comparand shown is the one THIS path actually hands the engine (a real
+     * boolean, not SQL's 1/0). Returns null for an operator/value combination
+     * that carries no predicate, matching `execute()`, which drops it too.
+     */
+    private buildFilterClauseSql;
     /**
      * Resolve a member ref to a `{ sql, type? }` definition.
      *
@@ -671,9 +934,108 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private lookupMember;
     private resolveFieldName;
     private resolveMeasureAggregation;
+    /**
+     * AND one more operand onto `filter[field]`, merging operator objects rather
+     * than overwriting them. Returns a standalone conjunct when the two cannot
+     * share one entry, or `null` when the merge absorbed the operand.
+     *
+     * Every predicate this strategy contributes goes through here — the caller's
+     * `where` and the time-dimension `dateRange` alike. Two operands on one field
+     * are the normal case (`{$gte}` from a `where` plus `{$gte,$lte}` from a
+     * window on `close_date`), and a plain assignment would keep only the last:
+     * that is how a range used to lose a bound.
+     *
+     * Spreading is sound only while the operands name DIFFERENT operators. Where
+     * they collide — two `$gte` bounds on one field, which a window makes routine
+     * and which a `where` can already produce on its own through `$and` — the
+     * spread keeps whichever came last and WIDENS the query. Same for a bare
+     * equality meeting an operator object: neither can absorb the other. Those
+     * are handed back for the caller to AND in separately, so the engine
+     * intersects them instead of the strategy picking a winner.
+     */
+    /**
+     * Fold a normalized filter node into the engine filter being built.
+     *
+     * AND-ed LEAVES merge per field through {@link mergeFilterOperand}, exactly
+     * as the flat loop this replaced did — so a query without combinators still
+     * produces byte-identical engine input. Anything structural (`$or`, `$not`,
+     * a nested `$and` that cannot merge) becomes its own conjunct, which the
+     * caller ANDs in. The engine speaks these combinators natively
+     * (`FilterCondition` declares them and every driver compiles them), so this
+     * path hands them over rather than lowering them.
+     */
+    private applyFilterNode;
+    /** A node as a standalone `FilterCondition` the engine can consume. */
+    private filterNodeToCondition;
+    /**
+     * Render a normalized filter node as the display SQL `/analytics/sql`
+     * echoes. Values still bind as `$n` placeholders — the echo travels to the
+     * browser, so a comparand is never inlined.
+     */
+    private renderFilterNodeSql;
+    private mergeFilterOperand;
+    /**
+     * Lower `timeDimensions[].dateRange` into resolved-field bounds (#3650).
+     *
+     * `dateRange` states a WINDOW on a time dimension; it is a SIBLING of `where`,
+     * never folded into it. `normalizeAnalyticsFilters` reads only `where`, so
+     * this path used to drop the window on the floor — no error, just every row
+     * ever recorded. Nor is that a corner case: `NativeSQLStrategy.canHandle`
+     * declines any query carrying a `granularity`, so a date-bucketed trend lands
+     * HERE on every driver — and "bucketed trend" is precisely the shape that also
+     * carries a range ("last 12 months", "this quarter").
+     *
+     * Bounds are inclusive on both ends — logically "from day X through day Y".
+     * The `$lte` end is left as the bare calendar day on purpose: the driver's
+     * filter compiler owns the calendar-day → instant translation, compiling a
+     * bare-day `$lte` on a `datetime` column into the half-open `< nextDay`
+     * (#3777) while a `date` column keeps the plain `<=`. `NativeSQLStrategy`
+     * performs the same half-open translation itself because it binds into raw
+     * SQL, so one dashboard reads the same on every driver.
+     *
+     * Comparands are coerced by the SAME helper the `where` path uses, so an
+     * epoch-ms bound recovers as a number and an ISO string stays a string. No
+     * STORAGE coercion happens here, deliberately: `NativeSQLStrategy` needs
+     * `coerceTemporal` because it binds into raw SQL and had to learn that a
+     * SQLite `Field.datetime` is an INTEGER epoch (#2034); this path goes through
+     * `engine.aggregate()`, where the driver's own CRUD filter coercion applies —
+     * the very coercion that already makes a `where` bound on that same column
+     * work today.
+     *
+     * A bare-string `dateRange` degenerates to the single point `[s, s]`, matching
+     * `NativeSQLStrategy`. Relative phrases ("Last 7 days") are NOT resolved here;
+     * neither SQL path resolves them, and inventing a second interpretation on the
+     * driver-independent path is how the two would drift apart again.
+     *
+     * An oddly-sized array (the schema types `dateRange` as a plain `string[]`)
+     * takes its first two entries, a one-entry array degenerating to a point.
+     * `NativeSQLStrategy` drops such a window entirely — but "drop the window"
+     * means "plot all of history", which is the very failure this fixes, so the
+     * fallback here errs toward the narrower query instead.
+     */
+    private dateRangeBounds;
     private convertFilter;
     private extractObjectName;
+    /**
+     * The dimensions this query PROJECTS, in the order the result carries them:
+     * every `dimensions` entry, then every granular `timeDimensions` entry that
+     * is not already one of them.
+     *
+     * `timeDimensions` is not merely a filter carrier. An entry with a
+     * `granularity` is GROUPED BY — see the `td.granularity` sites that build
+     * groupBy here, in `generateSql` and in the cross-object path — so its
+     * bucket is a COLUMN of the result; an entry without one only contributes a
+     * `dateRange` predicate and must NOT be projected.
+     *
+     * Grouping, row mapping and {@link buildFieldMeta} have to agree on exactly
+     * that set. When they did not, a bucketed query returned rows carrying only
+     * the measures and a `fields` list that never mentioned the bucket — a trend
+     * chart got N values and no x-axis (#4033) — even though the SQL had
+     * selected `date_trunc(…) AS "<dim>"` all along. One definition, every
+     * consumer.
+     */
+    private projectedDimensions;
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };
+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 };