@objectstack/service-analytics 17.0.0 → 17.2.0

package/dist/index.d.cts

@@ -1186,6 +1186,33 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#8690] Does the query's `where` compare a declared TIME dimension against
+     * a value no temporal storage rule can read? See the ruling at
+     * {@link canHandle}.
+     *
+     * The classification comes from the CUBE, the only metadata this package has:
+     * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+     * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+     * member lookup in this strategy uses, so "the member the gate classified"
+     * and "the member the compiler emits" cannot drift apart.
+     *
+     * A `time` dimension is read with the DATETIME rule — the permissive one of
+     * the three. That is the right direction because this is a routing decision,
+     * not a verdict: the engine door re-judges with the field's real declared
+     * type and has the final say, so under-classifying an exotic spelling merely
+     * leaves today's behaviour, while over-classifying would silently move a
+     * working dashboard off the fast path. The comparands this card measured
+     * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+     * so the decline fires for them whichever backing type the dimension has.
+     *
+     * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+     * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+     * lowering is not this gate's to answer — the filter is malformed either way
+     * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+     * message and envelope it has always had.
+     */
+    private carriesUninterpretableTemporalComparand;
     /**
      * [#7598] Does serving this query require the cross-field capability this
      * strategy declines? See the ruling recorded at {@link canHandle}.
@@ -1281,6 +1308,11 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      */
     private lookupMember;
     private resolveDimensionSql;
+    /**
+     * @param predicate - The measure's own scoped filter, already compiled to a
+     *   SQL boolean (`null` = the measure declares none, or declares one that
+     *   constrains nothing — `compileFilterNode`'s TRUE). #10298.
+     */
     private resolveMeasureSql;
     private resolveFieldSql;
     /**
@@ -1416,6 +1448,59 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private withReadScope;
     /** Is `field` a resolved cross-object (relationship-traversal) reference? */
     private isCrossObjectField;
+    /**
+     * The member view {@link planCrossObject} judges a filter by: EVERY member
+     * that will end up in the engine's predicate, structure discarded, keyed by
+     * RESOLVED field name (#10759), valued by WHERE THE MEMBER CAME FROM
+     * (#10861).
+     *
+     * Both call sites — `execute()` and `generateSql()` — are handed this and
+     * nothing else, which is what makes the invariant `planCrossObject` states
+     * for itself ("the preview accepts/rejects the same set") structural rather
+     * than a coincidence maintained by hand. They used to build the view
+     * separately: the echo flattened the tree, `execute()` passed the ENGINE
+     * FILTER, and a filter record answers a different question — it is a
+     * predicate to evaluate, not an inventory of members. An `$or`, a `$not` or
+     * an unmergeable nested `$and` travels in it as one opaque `$and` entry, so
+     * the members inside were unreadable from the outside and the envelope check
+     * could not reject what it could not see.
+     *
+     * ## Two producers, one inventory (#10861)
+     *
+     * The caller's `where` is not the only thing that reaches `engine.aggregate`
+     * as a predicate. Since PR #10758 the compiled dataset's own definition-level
+     * `filter` is lowered onto `execute()`'s `conjuncts` and rendered by
+     * `generateSql()`, so a dataset declaring `filter: { 'account.region': 'West' }`
+     * sent `{"$and":[{"account.region":"West"}]}` to an engine that cannot join —
+     * measured on both doors, which AGREED in accepting it, so #10759's
+     * preview/execution symmetry had nothing to restore. Refusing it is a
+     * widening of the refusal set, ruled by the maintainer on 2026-08-22 (Option
+     * A, query-time refusal): fold the scope's leaves in HERE, where driver
+     * capability is known, rather than in `dataset-compiler.ts`, which cannot see
+     * which driver will serve the dataset and would refuse a dataset that is
+     * perfectly legal on a native-SQL deployment.
+     *
+     * Structure is discarded on purpose — a member is cross-object or it is not,
+     * and which branch of a disjunction it sits in cannot make
+     * `engine.aggregate` able to join it. PROVENANCE is not discarded, because it
+     * decides what the refusal can tell the caller to go fix: `AnalyticsRequestKey`
+     * is the analytics REQUEST vocabulary and a dataset's `filter` is not in it,
+     * so a scope-borne member must not be reported as `param: 'where'` — see
+     * `planCrossObject`. The value slot carries that and nothing else; it never
+     * reaches a driver.
+     *
+     * Dataset leaves are inserted FIRST so a member named by BOTH producers keeps
+     * the caller's provenance (last write wins on a duplicate key): if it is in
+     * the request too, the request is the actionable place to fix it.
+     *
+     * Time-dimension WINDOWS are deliberately absent (they live in
+     * `dateRangeBounds`, not in `where`). They need no arm here: a cross-object
+     * time dimension is refused by `planCrossObject`'s own first loop, over
+     * `query.timeDimensions`, and refused as the time dimension the author wrote
+     * rather than as the lowered predicate it becomes — which is the better
+     * diagnostic and the reason that loop runs first.
+     */
+    private filterMemberView;
     /**
      * Plan how to serve cross-object references on this join-less path (#3654).
      *
@@ -1426,21 +1511,36 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * query (direct path), a plan for an in-envelope cross-object query.
      *
      * THROWS for anything outside the envelope — a cross-object MEASURE or FILTER
-     * (needs a real join to evaluate), a MULTI-HOP dimension (`a.b.c`), or a
+     * (needs a real join to evaluate), a cross-object leaf in the DATASET's own
+     * definition-level `filter` (#10861 — same join it does not have, arriving
+     * from the producer PR #10758 added), a MULTI-HOP dimension (`a.b.c`), or a
      * non-recombinable measure (`avg`/`count_distinct`, whose sub-bucket values
      * cannot be merged). A loud error beats the silent mis-bucket #3654 kills.
-     * `generateSql()` calls this too, so the preview accepts/rejects the same set.
-     *
-     * [#5716] All four refusals below are `invalidMemberError` — `INVALID_FIELD` /
-     * 400, naming the member — and the MESSAGES are unchanged (they are good
-     * diagnostics, and #5923's tests read them). Each is decided by two caller-side
-     * facts and nothing else: a member the query named, and whether that member
-     * resolves across a join. Neither is an internal invariant — a cube where the
-     * member exists and a driver that could serve it are both perfectly ordinary,
-     * which is exactly what the "run this on a native-SQL driver" half of each
-     * message says. They are member-level rather than dataset-level (hence not
-     * `datasetInvalidError`) because the fix is always to change or drop ONE named
-     * member, and because they fire on `/analytics/query` where no dataset exists.
+     * `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` /
+     * 400, naming the member — and the four that predate #10861 keep their
+     * MESSAGES unchanged (they are good diagnostics, and #5923's tests read
+     * them). Each is decided by two facts and nothing else: a member that will
+     * reach the engine's predicate, and whether that member resolves across a
+     * join. Neither is an internal invariant — a cube where the member exists and
+     * a driver that could serve it are both perfectly ordinary, which is exactly
+     * what the "run this on a native-SQL driver" half of every message says. They
+     * are member-level rather than dataset-level (hence not `datasetInvalidError`)
+     * because the fix is always to change or drop ONE named member, and because
+     * four of them fire on `/analytics/query` where no dataset exists.
+     *
+     * [#10861] The fifth is the exception that proves the rule and is written to
+     * it: it can only fire where a dataset DOES exist, and it is the one refusal
+     * here whose member no request key named — so it carries `cube` and no
+     * `param`, and says in its own words which document to go and edit. It stays
+     * `INVALID_FIELD` rather than becoming `DATASET_INVALID` because the verdict
+     * is the same physical one as its neighbour — this engine cannot join this
+     * member — and splitting the code by PROVENANCE would make a caller branch on
+     * two wire shapes for one capability limit.
      *
      * Detection is on RESOLVED field names, so a dotted dimension the cube
      * flattens to a real column is treated as base, not cross-object.

package/dist/index.d.ts

@@ -1186,6 +1186,33 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#8690] Does the query's `where` compare a declared TIME dimension against
+     * a value no temporal storage rule can read? See the ruling at
+     * {@link canHandle}.
+     *
+     * The classification comes from the CUBE, the only metadata this package has:
+     * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+     * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+     * member lookup in this strategy uses, so "the member the gate classified"
+     * and "the member the compiler emits" cannot drift apart.
+     *
+     * A `time` dimension is read with the DATETIME rule — the permissive one of
+     * the three. That is the right direction because this is a routing decision,
+     * not a verdict: the engine door re-judges with the field's real declared
+     * type and has the final say, so under-classifying an exotic spelling merely
+     * leaves today's behaviour, while over-classifying would silently move a
+     * working dashboard off the fast path. The comparands this card measured
+     * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+     * so the decline fires for them whichever backing type the dimension has.
+     *
+     * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+     * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+     * lowering is not this gate's to answer — the filter is malformed either way
+     * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+     * message and envelope it has always had.
+     */
+    private carriesUninterpretableTemporalComparand;
     /**
      * [#7598] Does serving this query require the cross-field capability this
      * strategy declines? See the ruling recorded at {@link canHandle}.
@@ -1281,6 +1308,11 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      */
     private lookupMember;
     private resolveDimensionSql;
+    /**
+     * @param predicate - The measure's own scoped filter, already compiled to a
+     *   SQL boolean (`null` = the measure declares none, or declares one that
+     *   constrains nothing — `compileFilterNode`'s TRUE). #10298.
+     */
     private resolveMeasureSql;
     private resolveFieldSql;
     /**
@@ -1416,6 +1448,59 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private withReadScope;
     /** Is `field` a resolved cross-object (relationship-traversal) reference? */
     private isCrossObjectField;
+    /**
+     * The member view {@link planCrossObject} judges a filter by: EVERY member
+     * that will end up in the engine's predicate, structure discarded, keyed by
+     * RESOLVED field name (#10759), valued by WHERE THE MEMBER CAME FROM
+     * (#10861).
+     *
+     * Both call sites — `execute()` and `generateSql()` — are handed this and
+     * nothing else, which is what makes the invariant `planCrossObject` states
+     * for itself ("the preview accepts/rejects the same set") structural rather
+     * than a coincidence maintained by hand. They used to build the view
+     * separately: the echo flattened the tree, `execute()` passed the ENGINE
+     * FILTER, and a filter record answers a different question — it is a
+     * predicate to evaluate, not an inventory of members. An `$or`, a `$not` or
+     * an unmergeable nested `$and` travels in it as one opaque `$and` entry, so
+     * the members inside were unreadable from the outside and the envelope check
+     * could not reject what it could not see.
+     *
+     * ## Two producers, one inventory (#10861)
+     *
+     * The caller's `where` is not the only thing that reaches `engine.aggregate`
+     * as a predicate. Since PR #10758 the compiled dataset's own definition-level
+     * `filter` is lowered onto `execute()`'s `conjuncts` and rendered by
+     * `generateSql()`, so a dataset declaring `filter: { 'account.region': 'West' }`
+     * sent `{"$and":[{"account.region":"West"}]}` to an engine that cannot join —
+     * measured on both doors, which AGREED in accepting it, so #10759's
+     * preview/execution symmetry had nothing to restore. Refusing it is a
+     * widening of the refusal set, ruled by the maintainer on 2026-08-22 (Option
+     * A, query-time refusal): fold the scope's leaves in HERE, where driver
+     * capability is known, rather than in `dataset-compiler.ts`, which cannot see
+     * which driver will serve the dataset and would refuse a dataset that is
+     * perfectly legal on a native-SQL deployment.
+     *
+     * Structure is discarded on purpose — a member is cross-object or it is not,
+     * and which branch of a disjunction it sits in cannot make
+     * `engine.aggregate` able to join it. PROVENANCE is not discarded, because it
+     * decides what the refusal can tell the caller to go fix: `AnalyticsRequestKey`
+     * is the analytics REQUEST vocabulary and a dataset's `filter` is not in it,
+     * so a scope-borne member must not be reported as `param: 'where'` — see
+     * `planCrossObject`. The value slot carries that and nothing else; it never
+     * reaches a driver.
+     *
+     * Dataset leaves are inserted FIRST so a member named by BOTH producers keeps
+     * the caller's provenance (last write wins on a duplicate key): if it is in
+     * the request too, the request is the actionable place to fix it.
+     *
+     * Time-dimension WINDOWS are deliberately absent (they live in
+     * `dateRangeBounds`, not in `where`). They need no arm here: a cross-object
+     * time dimension is refused by `planCrossObject`'s own first loop, over
+     * `query.timeDimensions`, and refused as the time dimension the author wrote
+     * rather than as the lowered predicate it becomes — which is the better
+     * diagnostic and the reason that loop runs first.
+     */
+    private filterMemberView;
     /**
      * Plan how to serve cross-object references on this join-less path (#3654).
      *
@@ -1426,21 +1511,36 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * query (direct path), a plan for an in-envelope cross-object query.
      *
      * THROWS for anything outside the envelope — a cross-object MEASURE or FILTER
-     * (needs a real join to evaluate), a MULTI-HOP dimension (`a.b.c`), or a
+     * (needs a real join to evaluate), a cross-object leaf in the DATASET's own
+     * definition-level `filter` (#10861 — same join it does not have, arriving
+     * from the producer PR #10758 added), a MULTI-HOP dimension (`a.b.c`), or a
      * non-recombinable measure (`avg`/`count_distinct`, whose sub-bucket values
      * cannot be merged). A loud error beats the silent mis-bucket #3654 kills.
-     * `generateSql()` calls this too, so the preview accepts/rejects the same set.
-     *
-     * [#5716] All four refusals below are `invalidMemberError` — `INVALID_FIELD` /
-     * 400, naming the member — and the MESSAGES are unchanged (they are good
-     * diagnostics, and #5923's tests read them). Each is decided by two caller-side
-     * facts and nothing else: a member the query named, and whether that member
-     * resolves across a join. Neither is an internal invariant — a cube where the
-     * member exists and a driver that could serve it are both perfectly ordinary,
-     * which is exactly what the "run this on a native-SQL driver" half of each
-     * message says. They are member-level rather than dataset-level (hence not
-     * `datasetInvalidError`) because the fix is always to change or drop ONE named
-     * member, and because they fire on `/analytics/query` where no dataset exists.
+     * `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` /
+     * 400, naming the member — and the four that predate #10861 keep their
+     * MESSAGES unchanged (they are good diagnostics, and #5923's tests read
+     * them). Each is decided by two facts and nothing else: a member that will
+     * reach the engine's predicate, and whether that member resolves across a
+     * join. Neither is an internal invariant — a cube where the member exists and
+     * a driver that could serve it are both perfectly ordinary, which is exactly
+     * what the "run this on a native-SQL driver" half of every message says. They
+     * are member-level rather than dataset-level (hence not `datasetInvalidError`)
+     * because the fix is always to change or drop ONE named member, and because
+     * four of them fire on `/analytics/query` where no dataset exists.
+     *
+     * [#10861] The fifth is the exception that proves the rule and is written to
+     * it: it can only fire where a dataset DOES exist, and it is the one refusal
+     * here whose member no request key named — so it carries `cube` and no
+     * `param`, and says in its own words which document to go and edit. It stays
+     * `INVALID_FIELD` rather than becoming `DATASET_INVALID` because the verdict
+     * is the same physical one as its neighbour — this engine cannot join this
+     * member — and splitting the code by PROVENANCE would make a caller branch on
+     * two wire shapes for one capability limit.
      *
      * Detection is on RESOLVED field names, so a dotted dimension the cube
      * flattens to a real column is treated as base, not cross-object.