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

package/dist/index.cjs

@@ -40,7 +40,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/analytics-service.ts
-var import_core3 = require("@objectstack/core");
+var import_core5 = require("@objectstack/core");
 
 // src/cube-registry.ts
 var CubeRegistry = class {
@@ -169,7 +169,8 @@ var MONGO_TO_CUBE_OP = {
   $nin: "notIn",
   $contains: "contains",
   $notContains: "notContains",
-  $exists: "set"
+  $startsWith: "startsWith",
+  $endsWith: "endsWith"
 };
 function stringifyForCube(v) {
   if (v == null) return "";
@@ -178,55 +179,102 @@ function stringifyForCube(v) {
   if (typeof v === "object") return JSON.stringify(v);
   return String(v);
 }
-function flattenCondition(cond, out) {
-  for (const [key, raw] of Object.entries(cond)) {
-    if (raw === void 0) continue;
-    if (key === "$and" && Array.isArray(raw)) {
-      for (const sub of raw) {
-        if (sub && typeof sub === "object") {
-          flattenCondition(sub, out);
+function andOf(children) {
+  if (children.length === 0) return null;
+  if (children.length === 1) return children[0];
+  return { kind: "and", children };
+}
+function fieldLeaves(key, raw) {
+  const out = [];
+  const leaf = (operator, values) => {
+    out.push({ kind: "leaf", member: key, operator, values });
+  };
+  if (raw === null) {
+    leaf("notSet", []);
+    return out;
+  }
+  if (typeof raw === "object" && !Array.isArray(raw) && !(raw instanceof Date)) {
+    const wrapper = raw;
+    const opKeys = Object.keys(wrapper).filter((k) => k.startsWith("$"));
+    if (opKeys.length > 0) {
+      for (const opKey of opKeys) {
+        if (opKey === "$between") {
+          const v2 = wrapper[opKey];
+          if (!Array.isArray(v2) || v2.length !== 2) {
+            throw new Error(
+              `[analytics] "$between" on "${key}" needs a two-element [min, max] array, got ${JSON.stringify(v2)}. Dropping the predicate would silently widen the query to every row.`
+            );
+          }
+          leaf("gte", [stringifyForCube(v2[0])]);
+          leaf("lte", [stringifyForCube(v2[1])]);
+          continue;
+        }
+        if (opKey === "$null" || opKey === "$exists") {
+          const isNull = opKey === "$null" ? wrapper[opKey] === true : wrapper[opKey] === false;
+          leaf(isNull ? "notSet" : "set", []);
+          continue;
         }
+        const cubeOp = MONGO_TO_CUBE_OP[opKey];
+        if (!cubeOp) {
+          throw new Error(
+            `[analytics] Unsupported filter operator "${opKey}" on "${key}". Supported: ${Object.keys(MONGO_TO_CUBE_OP).join(", ")}, $between, $null, $exists, and the $and/$or/$not combinators. Dropping it would silently widen the query to rows the filter excludes.`
+          );
+        }
+        const v = wrapper[opKey];
+        leaf(cubeOp, Array.isArray(v) ? v.map(stringifyForCube) : [stringifyForCube(v)]);
       }
-      continue;
+      return out;
     }
-    if (key === "$or" || key === "$not") continue;
-    if (raw === null) {
-      out.push({ member: key, operator: "notSet", values: [] });
-      continue;
+    for (const [nestedKey, nestedVal] of Object.entries(wrapper)) {
+      out.push(...fieldLeaves(`${key}.${nestedKey}`, nestedVal));
     }
-    if (typeof raw === "object" && !Array.isArray(raw) && !(raw instanceof Date)) {
-      const wrapper = raw;
-      const opKeys = Object.keys(wrapper).filter((k) => k.startsWith("$"));
-      if (opKeys.length > 0) {
-        for (const opKey of opKeys) {
-          const cubeOp = MONGO_TO_CUBE_OP[opKey];
-          if (!cubeOp) continue;
-          const v = wrapper[opKey];
-          const values = Array.isArray(v) ? v.map(stringifyForCube) : [stringifyForCube(v)];
-          out.push({ member: key, operator: cubeOp, values });
-        }
-        continue;
-      }
-      for (const [nestedKey, nestedVal] of Object.entries(wrapper)) {
-        flattenCondition({ [`${key}.${nestedKey}`]: nestedVal }, out);
+    return out;
+  }
+  if (Array.isArray(raw)) leaf("in", raw.map(stringifyForCube));
+  else leaf("equals", [stringifyForCube(raw)]);
+  return out;
+}
+function buildNode(cond) {
+  const children = [];
+  for (const [key, raw] of Object.entries(cond)) {
+    if (raw === void 0) continue;
+    if (key === "$and" || key === "$or") {
+      if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error(
+          `[analytics] "${key}" requires a non-empty array. An empty combinator has no defensible reading \u2014 dropping it widens the query, and treating it as "match nothing" silently empties a chart.`
+        );
       }
+      const branches = raw.map((sub) => sub && typeof sub === "object" ? buildNode(sub) : null).filter((n) => n !== null);
+      if (branches.length === 0) continue;
+      if (key === "$and") children.push(...branches);
+      else children.push(branches.length === 1 ? branches[0] : { kind: "or", children: branches });
       continue;
     }
-    if (Array.isArray(raw)) {
-      out.push({ member: key, operator: "in", values: raw.map(stringifyForCube) });
-    } else {
-      out.push({ member: key, operator: "equals", values: [stringifyForCube(raw)] });
+    if (key === "$not") {
+      const inner = raw && typeof raw === "object" ? buildNode(raw) : null;
+      if (inner) children.push({ kind: "not", child: inner });
+      continue;
     }
+    if (key.startsWith("$")) {
+      throw new Error(
+        `[analytics] Unsupported top-level filter operator "${key}". Dropping it would silently widen the query to rows the filter excludes.`
+      );
+    }
+    children.push(...fieldLeaves(key, raw));
   }
+  return andOf(children);
 }
-function normalizeAnalyticsFilters(query) {
-  if (!query || typeof query !== "object") return [];
-  const out = [];
+function normalizeAnalyticsFilterTree(query) {
+  if (!query || typeof query !== "object") return null;
   const where = query.where;
-  if (where && typeof where === "object" && !Array.isArray(where)) {
-    flattenCondition(where, out);
-  }
-  return out;
+  if (!where || typeof where !== "object" || Array.isArray(where)) return null;
+  return buildNode(where);
+}
+function collectFilterLeaves(node) {
+  if (!node) return [];
+  if (node.kind === "leaf") return [{ member: node.member, operator: node.operator, values: node.values }];
+  if (node.kind === "not") return collectFilterLeaves(node.child);
+  return node.children.flatMap(collectFilterLeaves);
 }
 function recoverNumber(s) {
   if (/^-?\d+(\.\d+)?$/.test(s)) {
@@ -358,6 +406,18 @@ function compileOperator(col, op, val, field, params) {
 }
 
 // src/strategies/native-sql-strategy.ts
+var import_core = require("@objectstack/core");
+var AGGREGATE_SQL = {
+  "count": () => "COUNT(*)",
+  "sum": (col) => `SUM(${col})`,
+  "avg": (col) => `AVG(${col})`,
+  "min": (col) => `MIN(${col})`,
+  "max": (col) => `MAX(${col})`,
+  "count_distinct": (col) => `COUNT(DISTINCT ${col})`
+};
+var SUPPORTED_AGGREGATE_SQL_KEYS = Object.keys(AGGREGATE_SQL);
+var EXPRESSION_METRIC_TYPES = /* @__PURE__ */ new Set(["number", "string", "boolean"]);
+var IDENTIFIER_PATH = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
 var NativeSQLStrategy = class {
   constructor() {
     this.name = "NativeSQLStrategy";
@@ -412,15 +472,15 @@ var NativeSQLStrategy = class {
       }
     }
     const whereClauses = [];
-    const normalizedFilters = normalizeAnalyticsFilters(query);
-    if (normalizedFilters.length > 0) {
-      for (const filter of normalizedFilters) {
-        const colExpr = this.resolveFieldSql(cube, filter.member, tableName, joins);
-        const target = this.resolveStorageTarget(cube, filter.member, tableName);
-        const clause = this.buildFilterClause(colExpr, filter.operator, filter.values, params, ctx, target);
-        if (clause) whereClauses.push(clause);
-      }
-    }
+    const filterSql = this.compileFilterNode(
+      normalizeAnalyticsFilterTree(query),
+      cube,
+      tableName,
+      joins,
+      params,
+      ctx
+    );
+    if (filterSql) whereClauses.push(filterSql);
     if (query.timeDimensions && query.timeDimensions.length > 0) {
       for (const td of query.timeDimensions) {
         const colExpr = this.resolveFieldSql(cube, td.dimension, tableName, joins);
@@ -428,11 +488,17 @@ var NativeSQLStrategy = class {
           const range = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
           if (range.length === 2) {
             const td2 = this.resolveStorageTarget(cube, td.dimension, tableName);
-            params.push(
-              this.coerceTemporal(ctx, td2, range[0]),
-              this.coerceTemporal(ctx, td2, range[1])
-            );
-            whereClauses.push(`${colExpr} BETWEEN $${params.length - 1} AND $${params.length}`);
+            const column = this.temporalColumn(ctx, td2, colExpr);
+            const nextDay = (0, import_core.nextUtcCalendarDay)(range[1]);
+            params.push(this.coerceTemporal(ctx, td2, range[0]));
+            const lower = `${column} >= $${params.length}`;
+            if (nextDay != null) {
+              params.push(this.coerceTemporal(ctx, td2, nextDay));
+              whereClauses.push(`(${lower} AND ${column} < $${params.length})`);
+            } else {
+              params.push(this.coerceTemporal(ctx, td2, range[1]));
+              whereClauses.push(`(${lower} AND ${column} <= $${params.length})`);
+            }
           }
         }
       }
@@ -530,6 +596,7 @@ var NativeSQLStrategy = class {
       }
       return rawSql;
     }
+    if (!IDENTIFIER_PATH.test(rawSql)) return rawSql;
     const segments = rawSql.split(".");
     const column = segments[segments.length - 1];
     const hops = segments.slice(0, -1);
@@ -589,24 +656,19 @@ var NativeSQLStrategy = class {
   }
   resolveMeasureSql(cube, member, parentTable, joins) {
     const measure = this.lookupMember(cube, member, "measure");
-    if (!measure) return `COUNT(*)`;
-    const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins, cube);
-    switch (measure.type) {
-      case "count":
-        return "COUNT(*)";
-      case "sum":
-        return `SUM(${col})`;
-      case "avg":
-        return `AVG(${col})`;
-      case "min":
-        return `MIN(${col})`;
-      case "max":
-        return `MAX(${col})`;
-      case "count_distinct":
-        return `COUNT(DISTINCT ${col})`;
-      default:
-        return `COUNT(*)`;
+    if (!measure) {
+      const declared = Object.keys(cube.measures ?? {});
+      throw new Error(
+        `[native-sql-strategy] cube "${cube.name}" declares no measure "${member}"` + (declared.length ? ` (declared: ${declared.join(", ")})` : " (it declares none)")
+      );
     }
+    const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins, cube);
+    const wrap = AGGREGATE_SQL[measure.type];
+    if (wrap) return wrap(col);
+    if (EXPRESSION_METRIC_TYPES.has(measure.type)) return col;
+    throw new Error(
+      `[native-sql-strategy] measure "${member}" on cube "${cube.name}" has unrecognised type "${measure.type}" \u2014 expected an aggregate (${SUPPORTED_AGGREGATE_SQL_KEYS.join(", ")}) or a custom-expression type (${[...EXPRESSION_METRIC_TYPES].join(", ")}).`
+    );
   }
   resolveFieldSql(cube, member, parentTable, joins) {
     const dim = this.lookupMember(cube, member, "dimension");
@@ -659,7 +721,53 @@ var NativeSQLStrategy = class {
     }
     return coerceFilterValueForSql(value);
   }
-  buildFilterClause(col, operator, values, params, ctx, target) {
+  /**
+   * 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.
+   */
+  temporalColumn(ctx, target, col) {
+    if (typeof ctx.coerceTemporalFilterColumn !== "function") return col;
+    return ctx.coerceTemporalFilterColumn(target.object, target.field, col) || col;
+  }
+  /**
+   * 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.
+   */
+  compileFilterNode(node, cube, parentTable, joins, params, ctx) {
+    if (!node) return null;
+    if (node.kind === "leaf") {
+      const colExpr = this.resolveFieldSql(cube, node.member, parentTable, joins);
+      const target = this.resolveStorageTarget(cube, node.member, parentTable);
+      return this.buildFilterClause(colExpr, node.operator, node.values, params, ctx, target);
+    }
+    if (node.kind === "not") {
+      const inner = this.compileFilterNode(node.child, cube, parentTable, joins, params, ctx);
+      return inner ? `NOT (${inner})` : null;
+    }
+    const parts = node.children.map((child) => this.compileFilterNode(child, cube, parentTable, joins, params, ctx)).filter((s) => !!s);
+    if (parts.length === 0) return null;
+    if (parts.length === 1) return parts[0];
+    return `(${parts.join(node.kind === "or" ? " OR " : " AND ")})`;
+  }
+  buildFilterClause(rawCol, operator, values, params, ctx, target) {
     const opMap = {
       equals: "=",
       notEquals: "!=",
@@ -668,26 +776,42 @@ var NativeSQLStrategy = class {
       lt: "<",
       lte: "<=",
       contains: "LIKE",
-      notContains: "NOT LIKE"
+      notContains: "NOT LIKE",
+      startsWith: "LIKE",
+      endsWith: "LIKE"
     };
-    if (operator === "set") return `${col} IS NOT NULL`;
-    if (operator === "notSet") return `${col} IS NULL`;
+    const likePattern = {
+      contains: (v) => `%${v}%`,
+      notContains: (v) => `%${v}%`,
+      startsWith: (v) => `${v}%`,
+      endsWith: (v) => `%${v}`
+    };
+    if (operator === "set") return `${rawCol} IS NOT NULL`;
+    if (operator === "notSet") return `${rawCol} IS NULL`;
     if (operator === "in" || operator === "notIn") {
       if (!values || values.length === 0) return null;
       const placeholders = values.map((v) => {
         params.push(this.coerceTemporal(ctx, target, v));
         return `$${params.length}`;
       }).join(", ");
-      return `${col} ${operator === "in" ? "IN" : "NOT IN"} (${placeholders})`;
+      return `${this.temporalColumn(ctx, target, rawCol)} ${operator === "in" ? "IN" : "NOT IN"} (${placeholders})`;
     }
     const sqlOp = opMap[operator];
     if (!sqlOp || !values || values.length === 0) return null;
-    if (operator === "contains" || operator === "notContains") {
-      params.push(`%${values[0]}%`);
-    } else {
-      params.push(this.coerceTemporal(ctx, target, values[0]));
+    const pattern = likePattern[operator];
+    if (pattern) {
+      params.push(pattern(values[0]));
+      return `${rawCol} ${sqlOp} $${params.length}`;
     }
-    return `${col} ${sqlOp} $${params.length}`;
+    if (operator === "lte") {
+      const nextDay = (0, import_core.nextUtcCalendarDay)(values[0]);
+      if (nextDay != null) {
+        params.push(this.coerceTemporal(ctx, target, nextDay));
+        return `${this.temporalColumn(ctx, target, rawCol)} < $${params.length}`;
+      }
+    }
+    params.push(this.coerceTemporal(ctx, target, values[0]));
+    return `${this.temporalColumn(ctx, target, rawCol)} ${sqlOp} $${params.length}`;
   }
   extractObjectName(cube) {
     return cube.sql.trim();
@@ -709,6 +833,9 @@ var NativeSQLStrategy = class {
   }
 };
 
+// src/strategies/objectql-strategy.ts
+var import_core2 = require("@objectstack/core");
+
 // src/strategies/cross-object-rebucket.ts
 var RECOMBINABLE_METHODS = /* @__PURE__ */ new Set([
   "sum",
@@ -811,11 +938,7 @@ var ObjectQLStrategy = class {
     }
     const filter = {};
     const conjuncts = [];
-    for (const f of normalizeAnalyticsFilters(query)) {
-      const fieldName = this.resolveFieldName(cube, f.member, "any");
-      const extra = this.mergeFilterOperand(filter, fieldName, this.convertFilter(f.operator, f.values));
-      if (extra) conjuncts.push(extra);
-    }
+    this.applyFilterNode(normalizeAnalyticsFilterTree(query), cube, filter, conjuncts);
     for (const { field, bounds } of this.dateRangeBounds(cube, query)) {
       const extra = this.mergeFilterOperand(filter, field, bounds);
       if (extra) conjuncts.push(extra);
@@ -847,11 +970,9 @@ var ObjectQLStrategy = class {
     });
     const mappedRows = rows.map((row) => {
       const mapped = {};
-      if (query.dimensions) {
-        for (const dim of query.dimensions) {
-          const shortName = this.resolveFieldName(cube, dim, "dimension");
-          if (shortName in row) mapped[dim] = row[shortName];
-        }
+      for (const dim of this.projectedDimensions(query)) {
+        const shortName = this.resolveFieldName(cube, dim, "dimension");
+        if (shortName in row) mapped[dim] = row[shortName];
       }
       if (query.measures) {
         for (const m of query.measures) {
@@ -897,7 +1018,7 @@ var ObjectQLStrategy = class {
     }
     const tableName = this.extractObjectName(cube);
     const plan = this.planCrossObject(cube, query, Object.fromEntries(
-      normalizeAnalyticsFilters(query).map((f) => [this.resolveFieldName(cube, f.member, "any"), true])
+      collectFilterLeaves(normalizeAnalyticsFilterTree(query)).map((f) => [this.resolveFieldName(cube, f.member, "any"), true])
     ));
     const crossByDim = new Map((plan?.crossDims ?? []).map((cd) => [cd.outputName, cd]));
     const joinClauses = [];
@@ -934,18 +1055,18 @@ var ObjectQLStrategy = class {
       }
     }
     const whereParts = [];
-    for (const f of normalizeAnalyticsFilters(query)) {
-      const clause = this.buildFilterClauseSql(
-        this.resolveFieldName(cube, f.member, "any"),
-        f.operator,
-        f.values,
-        params
-      );
-      if (clause) whereParts.push(clause);
-    }
+    const filterClause = this.renderFilterNodeSql(
+      normalizeAnalyticsFilterTree(query),
+      cube,
+      params
+    );
+    if (filterClause) whereParts.push(filterClause);
     for (const { field, bounds } of this.dateRangeBounds(cube, query)) {
-      params.push(bounds.$gte, bounds.$lte);
-      whereParts.push(`${field} BETWEEN $${params.length - 1} AND $${params.length}`);
+      const nextDay = (0, import_core2.nextUtcCalendarDay)(bounds.$lte);
+      params.push(bounds.$gte, nextDay ?? bounds.$lte);
+      whereParts.push(
+        `(${field} >= $${params.length - 1} AND ${field} ${nextDay ? "<" : "<="} $${params.length})`
+      );
     }
     const scope = ctx.getReadScope?.(tableName);
     if (scope != null) {
@@ -1119,7 +1240,7 @@ var ObjectQLStrategy = class {
     const merged = rebucketCrossObject(baseRows, baseDimFields, resolvedDims, measures);
     const mappedRows = merged.map((row) => {
       const out = {};
-      for (const dim of query.dimensions ?? []) {
+      for (const dim of this.projectedDimensions(query)) {
         if (crossByDim.has(dim)) {
           if (dim in row) out[dim] = row[dim];
         } else {
@@ -1127,11 +1248,6 @@ var ObjectQLStrategy = class {
           if (field in row) out[dim] = row[field];
         }
       }
-      for (const td of query.timeDimensions ?? []) {
-        if (query.dimensions?.includes(td.dimension)) continue;
-        const field = this.resolveFieldName(cube, td.dimension, "dimension");
-        if (field in row) out[td.dimension] = row[field];
-      }
       for (const m of query.measures ?? []) {
         if (m in row) out[m] = row[m];
       }
@@ -1274,6 +1390,75 @@ var ObjectQLStrategy = class {
    * 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.
+   */
+  applyFilterNode(node, cube, filter, conjuncts) {
+    if (!node) return;
+    if (node.kind === "leaf") {
+      const fieldName = this.resolveFieldName(cube, node.member, "any");
+      const extra = this.mergeFilterOperand(filter, fieldName, this.convertFilter(node.operator, node.values));
+      if (extra) conjuncts.push(extra);
+      return;
+    }
+    if (node.kind === "and") {
+      for (const child of node.children) this.applyFilterNode(child, cube, filter, conjuncts);
+      return;
+    }
+    const rendered = this.filterNodeToCondition(node, cube);
+    if (rendered) conjuncts.push(rendered);
+  }
+  /** A node as a standalone `FilterCondition` the engine can consume. */
+  filterNodeToCondition(node, cube) {
+    if (!node) return null;
+    if (node.kind === "not") {
+      const inner = this.filterNodeToCondition(node.child, cube);
+      return inner ? { $not: inner } : null;
+    }
+    if (node.kind === "or") {
+      const branches = node.children.map((child) => this.filterNodeToCondition(child, cube)).filter((c) => !!c);
+      return branches.length > 0 ? { $or: branches } : null;
+    }
+    const filter = {};
+    const conjuncts = [];
+    this.applyFilterNode(node, cube, filter, conjuncts);
+    if (conjuncts.length > 0) {
+      filter.$and = [...Array.isArray(filter.$and) ? filter.$and : [], ...conjuncts];
+    }
+    return Object.keys(filter).length > 0 ? filter : null;
+  }
+  /**
+   * 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.
+   */
+  renderFilterNodeSql(node, cube, params) {
+    if (!node) return null;
+    if (node.kind === "leaf") {
+      return this.buildFilterClauseSql(
+        this.resolveFieldName(cube, node.member, "any"),
+        node.operator,
+        node.values,
+        params
+      );
+    }
+    if (node.kind === "not") {
+      const inner = this.renderFilterNodeSql(node.child, cube, params);
+      return inner ? `NOT (${inner})` : null;
+    }
+    const parts = node.children.map((child) => this.renderFilterNodeSql(child, cube, params)).filter((s) => !!s);
+    if (parts.length === 0) return null;
+    if (parts.length === 1) return parts[0];
+    return `(${parts.join(node.kind === "or" ? " OR " : " AND ")})`;
+  }
   mergeFilterOperand(filter, field, operand) {
     const existing = filter[field];
     if (existing === void 0) {
@@ -1297,9 +1482,13 @@ var ObjectQLStrategy = class {
    * 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 — the same `$gte`/`$lte` pair
-   * `NativeSQLStrategy` binds as `BETWEEN` and the memory driver builds as a
-   * `$match`, so one dashboard reads the same on every driver.
+   * 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
@@ -1359,24 +1548,60 @@ var ObjectQLStrategy = class {
         return { $lte: v0 };
       case "contains":
         return { $regex: values[0] };
+      // `notContains` had no arm and fell to the `default` below, which returns
+      // a BARE VALUE — i.e. `{field: 'x'}`, an equality. "does not contain x"
+      // was compiled as "equals x". These three pass through as the canonical
+      // spec operators every driver implements directly, so an anchored match
+      // stays anchored rather than depending on regex dialect (#4128).
+      case "notContains":
+        return { $notContains: values[0] };
+      case "startsWith":
+        return { $startsWith: values[0] };
+      case "endsWith":
+        return { $endsWith: values[0] };
       case "in":
         return { $in: all };
       case "notIn":
         return { $nin: all };
       default:
-        return v0;
+        throw new Error(
+          `[analytics] ObjectQL strategy cannot express filter operator "${operator}". Treating it as an equality would silently query something the author did not ask for.`
+        );
     }
   }
   extractObjectName(cube) {
     return cube.sql.trim();
   }
+  /**
+   * 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.
+   */
+  projectedDimensions(query) {
+    const out = [...query.dimensions ?? []];
+    for (const td of query.timeDimensions ?? []) {
+      if (td.granularity && !out.includes(td.dimension)) out.push(td.dimension);
+    }
+    return out;
+  }
   buildFieldMeta(query, cube) {
     const fields = [];
-    if (query.dimensions) {
-      for (const dim of query.dimensions) {
-        const d = this.lookupMember(cube, dim, "dimension");
-        fields.push({ name: dim, type: d?.type || "string" });
-      }
+    for (const dim of this.projectedDimensions(query)) {
+      const d = this.lookupMember(cube, dim, "dimension");
+      fields.push({ name: dim, type: d?.type || "string" });
     }
     if (query.measures) {
       for (const m of query.measures) {
@@ -1388,14 +1613,16 @@ var ObjectQLStrategy = class {
 };
 
 // src/dataset-compiler.ts
+var import_data = require("@objectstack/spec/data");
 var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set(["array_agg", "string_agg"]);
+var SUPPORTED_AGGREGATES = import_data.AggregationFunction.options.filter((a) => !UNSUPPORTED_AGGREGATES.has(a));
 function aggregateToMetricType(m) {
   if (!m.aggregate) {
     throw new Error(`[dataset-compiler] non-derived measure "${m.name}" has no aggregate`);
   }
   if (UNSUPPORTED_AGGREGATES.has(m.aggregate)) {
     throw new Error(
-      `[dataset-compiler] measure "${m.name}" uses aggregate "${m.aggregate}" which is not supported by the v1 dataset runtime (supported: count, sum, avg, min, max, count_distinct).`
+      `[dataset-compiler] measure "${m.name}" uses aggregate "${m.aggregate}" which is not supported by the v1 dataset runtime (supported: ${SUPPORTED_AGGREGATES.join(", ")}).`
     );
   }
   return m.aggregate;
@@ -1522,10 +1749,10 @@ function compileDataset(dataset, resolver) {
 }
 
 // src/dataset-executor.ts
-var import_core = require("@objectstack/core");
+var import_core3 = require("@objectstack/core");
 function resolveSelectionTokens(compiled, selection, context) {
-  const tokenCtx = (0, import_core.filterTokenContextFrom)(context, /* @__PURE__ */ new Date());
-  const resolve = (v) => (0, import_core.resolveFilterTokens)(v, tokenCtx);
+  const tokenCtx = (0, import_core3.filterTokenContextFrom)(context, /* @__PURE__ */ new Date());
+  const resolve = (v) => (0, import_core3.resolveFilterTokens)(v, tokenCtx);
   const filter = resolve(compiled.filter);
   const measureFilters = resolve(compiled.measureFilters);
   const runtimeFilter = resolve(selection.runtimeFilter);
@@ -1622,7 +1849,7 @@ function applyWindow(rows, limit, offset) {
   if (start === 0 && limit == null) return rows;
   return rows.slice(start, limit != null ? start + limit : void 0);
 }
-function resolveOrdering(selection, dimensions) {
+function resolveOrdering(selection, dimensions, timeDimensions = []) {
   const order = selection.order;
   if (order && Object.keys(order).length > 0) {
     const selectable = /* @__PURE__ */ new Set([
@@ -1641,6 +1868,10 @@ function resolveOrdering(selection, dimensions) {
   if ((selection.limit != null || selection.offset != null) && dimensions.length > 0) {
     return Object.fromEntries(dimensions.map((d) => [d, "asc"]));
   }
+  const timeKeys = timeDimensions.filter((d) => dimensions.includes(d));
+  if (timeKeys.length > 0) {
+    return Object.fromEntries(timeKeys.map((d) => [d, "asc"]));
+  }
   return void 0;
 }
 function parseUTC(date) {
@@ -1734,7 +1965,7 @@ var DatasetExecutor = class {
     }
     const baseFilter = combineFilters(compiled.filter, selection.runtimeFilter);
     const dimensions = selection.dimensions ?? [];
-    const order = resolveOrdering(selection, dimensions);
+    const order = resolveOrdering(selection, dimensions, this.timeDimensionsOf(compiled, dimensions));
     const labelOrderKeys = this.orderLabels ? Object.keys(order ?? {}).filter(
       (k) => dimensions.includes(k) && this.orderLabels.isLabelBearing(k)
     ) : [];
@@ -1790,6 +2021,19 @@ var DatasetExecutor = class {
     result.rows = applyWindow(result.rows, selection.limit, selection.offset);
     return result;
   }
+  /**
+   * 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.)
+   */
+  timeDimensionsOf(compiled, dimensions) {
+    return dimensions.filter((d) => compiled.cube.dimensions[d]?.type === "time");
+  }
   buildQuery(compiled, opts) {
     const q = {
       cube: compiled.cube.name,
@@ -2031,11 +2275,21 @@ function pickDisplayField(fields) {
 }
 
 // src/preview-evaluator.ts
-var import_core2 = require("@objectstack/core");
+var import_core4 = require("@objectstack/core");
 function compare(a, b) {
   if (typeof a === "number" && typeof b === "number") return a - b;
+  if (a instanceof Date || b instanceof Date) {
+    const ai = (0, import_core4.utcInstantMs)(a);
+    const bi = (0, import_core4.utcInstantMs)(b);
+    if (ai !== null && bi !== null) return ai - bi;
+  }
   return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
 }
+function lteBound(value, bound) {
+  const nextDay = (0, import_core4.nextUtcCalendarDay)(bound);
+  if (nextDay != null) return compare(value, nextDay) < 0;
+  return compare(value, bound) <= 0;
+}
 function matchOp(value, op, expected) {
   switch (op) {
     case "$eq":
@@ -2048,8 +2302,16 @@ function matchOp(value, op, expected) {
       return value != null && compare(value, expected) >= 0;
     case "$lt":
       return value != null && compare(value, expected) < 0;
-    case "$lte":
-      return value != null && compare(value, expected) <= 0;
+    case "$lte": {
+      if (value == null) return false;
+      return lteBound(value, expected);
+    }
+    case "$between": {
+      if (value == null || !Array.isArray(expected) || expected.length !== 2) return false;
+      const [min, max] = expected;
+      if (min == null || max == null) return false;
+      return compare(value, min) >= 0 && lteBound(value, max);
+    }
     case "$in":
       return Array.isArray(expected) && expected.some((e) => value === e || String(value) === String(e));
     case "$nin":
@@ -2082,7 +2344,7 @@ function matchesWhere(row, where) {
 function bucketDate(value, granularity, timezone) {
   const d = new Date(String(value));
   if (Number.isNaN(d.getTime())) return null;
-  const { year: y, month, day: dayNum } = (0, import_core2.calendarPartsInTzOrUtc)(d, timezone);
+  const { year: y, month, day: dayNum } = (0, import_core4.calendarPartsInTzOrUtc)(d, timezone);
   const m = `${month}`.padStart(2, "0");
   const day = `${dayNum}`.padStart(2, "0");
   switch (granularity) {
@@ -2136,7 +2398,9 @@ function evaluateAnalyticsQueryOverRows(query, cube, rows) {
     const [start, end] = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
     filtered = filtered.filter((r) => {
       const v = String(r[field] ?? "");
-      return v >= String(start) && v <= `${end}~`;
+      const nextDay = (0, import_core4.nextUtcCalendarDay)(end);
+      const inUpper = nextDay != null ? v < nextDay : v <= `${end}~`;
+      return v >= String(start) && inUpper;
     });
   }
   const dimensions = query.dimensions ?? [];
@@ -2206,7 +2470,7 @@ var AnalyticsService = class {
     this.datasetRegistry = /* @__PURE__ */ new Map();
     /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
     this.warnedNoObjectRegistry = false;
-    this.logger = config.logger || (0, import_core3.createLogger)({ level: "info", format: "pretty" });
+    this.logger = config.logger || (0, import_core5.createLogger)({ level: "info", format: "pretty" });
     this.cubeRegistry = new CubeRegistry();
     if (config.cubes) {
       this.cubeRegistry.registerAll(config.cubes);
@@ -2236,6 +2500,7 @@ var AnalyticsService = class {
       // fall back to any explicitly-configured provider for legacy cubes.
       getAllowedRelationships: (cubeName) => this.datasetRegistry.get(cubeName)?.allowedRelationships ?? config.getAllowedRelationships?.(cubeName),
       coerceTemporalFilterValue: config.coerceTemporalFilterValue,
+      coerceTemporalFilterColumn: config.coerceTemporalFilterColumn,
       isExternalObject: config.isExternalObject
     };
     const builtIn = [
@@ -2439,11 +2704,11 @@ var AnalyticsService = class {
       else if (rangeTz === "UTC") rangeDims.push({ d, granularity, instant: false });
     }
     if (rangeDims.length && result.rows.length) {
-      const bound = (ymd, instant) => instant ? new Date((0, import_core3.zonedDateStartToUtcMs)(ymd, rangeTz)).toISOString() : ymd;
+      const bound = (ymd, instant) => instant ? new Date((0, import_core5.zonedDateStartToUtcMs)(ymd, rangeTz)).toISOString() : ymd;
       result.drillRanges = result.rows.map((row) => {
         const ranges = {};
         for (const { d, granularity, instant } of rangeDims) {
-          const cal = (0, import_core3.bucketKeyToCalendarRange)(row[d.name], granularity);
+          const cal = (0, import_core5.bucketKeyToCalendarRange)(row[d.name], granularity);
           if (cal) {
             ranges[d.name] = { field: d.field, gte: bound(cal.start, instant), lt: bound(cal.end, instant) };
           }
@@ -2723,6 +2988,11 @@ var FallbackDelegateStrategy = class {
 var AnalyticsServicePlugin = class {
   constructor(options = {}) {
     this.name = "com.objectstack.service-analytics";
+    /**
+     * Services init() registers on every path (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires one before it inits.
+     */
+    this.providesServices = ["analytics"];
     this.version = "1.0.0";
     this.type = "standard";
     this.dependencies = [];
@@ -2925,6 +3195,17 @@ var AnalyticsServicePlugin = class {
       }
       return value;
     };
+    const coerceTemporalFilterColumn = (objectName, fieldName, columnSql) => {
+      try {
+        const svc = ctx.getService("data");
+        const driver = svc?.getDriverForObject?.(objectName);
+        if (driver && typeof driver.temporalFilterColumnSql === "function") {
+          return driver.temporalFilterColumnSql(objectName, fieldName, columnSql);
+        }
+      } catch {
+      }
+      return columnSql;
+    };
     const config = {
       cubes: this.options.cubes,
       logger: ctx.logger,
@@ -2935,6 +3216,7 @@ var AnalyticsServicePlugin = class {
       getReadScope,
       getAllowedRelationships: this.options.getAllowedRelationships,
       coerceTemporalFilterValue,
+      coerceTemporalFilterColumn,
       relationshipResolver,
       labelResolver,
       // ADR-0053 — source-field currency metadata for the measure currency chain.