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

package/dist/index.js

@@ -128,7 +128,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 "";
@@ -137,55 +138,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)) {
@@ -317,6 +365,18 @@ function compileOperator(col, op, val, field, params) {
 }
 
 // src/strategies/native-sql-strategy.ts
+import { nextUtcCalendarDay } from "@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";
@@ -371,15 +431,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);
@@ -387,11 +447,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 = 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})`);
+            }
           }
         }
       }
@@ -489,6 +555,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);
@@ -548,24 +615,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");
@@ -618,7 +680,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: "!=",
@@ -627,26 +735,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}`;
+    }
+    if (operator === "lte") {
+      const nextDay = nextUtcCalendarDay(values[0]);
+      if (nextDay != null) {
+        params.push(this.coerceTemporal(ctx, target, nextDay));
+        return `${this.temporalColumn(ctx, target, rawCol)} < $${params.length}`;
+      }
     }
-    return `${col} ${sqlOp} $${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();
@@ -669,6 +793,72 @@ var NativeSQLStrategy = class {
 };
 
 // src/strategies/objectql-strategy.ts
+import { nextUtcCalendarDay as nextUtcCalendarDay2 } from "@objectstack/core";
+
+// src/strategies/cross-object-rebucket.ts
+var RECOMBINABLE_METHODS = /* @__PURE__ */ new Set([
+  "sum",
+  "count",
+  "min",
+  "max"
+]);
+var RESTRICTED_BUCKET = "(restricted)";
+function orderableValue(v) {
+  if (v == null) return NaN;
+  if (typeof v === "number") return v;
+  if (v instanceof Date) return v.getTime();
+  const n = Number(v);
+  if (Number.isFinite(n)) return n;
+  return Date.parse(String(v));
+}
+function recombine(method, acc, next) {
+  if (method === "min" || method === "max") {
+    if (acc === void 0) return next ?? 0;
+    const a = orderableValue(acc);
+    const n2 = orderableValue(next);
+    if (Number.isNaN(n2)) return acc;
+    if (Number.isNaN(a)) return next;
+    const nextWins = method === "min" ? n2 < a : n2 > a;
+    return nextWins ? next : acc;
+  }
+  const n = Number(next ?? 0);
+  return acc === void 0 ? n : Number(acc) + n;
+}
+function rebucketCrossObject(baseRows, baseDimFields, crossDims, measures) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const row of baseRows) {
+    const resolved = {};
+    for (const cd of crossDims) {
+      const fk = row[cd.fkField];
+      resolved[cd.outputName] = cd.fkToAttr.has(fk) ? cd.fkToAttr.get(fk) : RESTRICTED_BUCKET;
+    }
+    const keyParts = [];
+    for (const f of baseDimFields) keyParts.push(`${f}=${JSON.stringify(row[f] ?? null)}`);
+    for (const cd of crossDims) keyParts.push(`${cd.outputName}=${String(resolved[cd.outputName])}`);
+    const key = keyParts.join("
");
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = {};
+      for (const f of baseDimFields) bucket[f] = row[f];
+      for (const cd of crossDims) bucket[cd.outputName] = resolved[cd.outputName];
+      buckets.set(key, bucket);
+    }
+    for (const m of measures) {
+      bucket[m.alias] = recombine(m.method, bucket[m.alias], row[m.alias]);
+    }
+  }
+  return [...buckets.values()];
+}
+
+// src/strategies/objectql-strategy.ts
+var SCALAR_SQL_OPS = {
+  equals: "=",
+  notEquals: "!=",
+  gt: ">",
+  gte: ">=",
+  lt: "<",
+  lte: "<="
+};
 var ObjectQLStrategy = class {
   constructor() {
     this.name = "ObjectQLStrategy";
@@ -706,15 +896,18 @@ var ObjectQLStrategy = class {
       }
     }
     const filter = {};
-    const normalizedFilters = normalizeAnalyticsFilters(query);
-    if (normalizedFilters.length > 0) {
-      for (const f of normalizedFilters) {
-        const fieldName = this.resolveFieldName(cube, f.member, "any");
-        const converted = this.convertFilter(f.operator, f.values);
-        const existing = filter[fieldName];
-        const mergeable = (v) => !!v && typeof v === "object" && !Array.isArray(v);
-        filter[fieldName] = mergeable(existing) && mergeable(converted) ? { ...existing, ...converted } : converted;
-      }
+    const conjuncts = [];
+    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);
+    }
+    if (conjuncts.length > 0) {
+      filter.$and = [...Array.isArray(filter.$and) ? filter.$and : [], ...conjuncts];
+    }
+    const plan = this.planCrossObject(cube, query, filter);
+    if (plan) {
+      return this.executeCrossObject(cube, query, aggregations, filter, plan, ctx);
     }
     const rows = await ctx.executeAggregate(objectName, {
       // Structured groupBy items ({field, dateGranularity}) pass through the
@@ -722,19 +915,23 @@ var ObjectQLStrategy = class {
       // contract types groupBy as string[]; the cast carries the richer shape.
       groupBy: groupBy.length > 0 ? groupBy : void 0,
       aggregations: aggregations.length > 0 ? aggregations : void 0,
-      filter: Object.keys(filter).length > 0 ? filter : void 0,
+      filter: this.withReadScope(objectName, filter, ctx),
       // ADR-0053 Phase 2 (D2): forward the reference tz so date buckets resolve
       // on that zone's calendar days. A non-UTC zone makes the engine bucket
       // in-memory (uniform across drivers); UTC/unset keeps the DB fast path.
-      timezone: query.timezone
+      timezone: query.timezone,
+      // ADR-0021 D-C (#3602): the second belt. `withReadScope` above is this
+      // layer's own scoping; handing the engine the context makes ITS middleware
+      // inject RLS too, so a future strategy that forgets `withReadScope` still
+      // cannot read across tenants. Without it the operation reaches the engine
+      // principal-less and plugin-security falls open — the #3597 shape.
+      context: ctx.context
     });
     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) {
@@ -744,8 +941,28 @@ var ObjectQLStrategy = class {
       return mapped;
     });
     const fields = this.buildFieldMeta(query, cube);
-    return { rows: mappedRows, fields };
+    let sql;
+    try {
+      sql = (await this.generateSql(query, ctx)).sql;
+    } catch {
+      sql = void 0;
+    }
+    return sql ? { rows: mappedRows, fields, sql } : { rows: mappedRows, fields };
   }
+  /**
+   * 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.
+   */
   async generateSql(query, ctx) {
     const cube = ctx.getCube(query.cube);
     if (!cube) {
@@ -753,28 +970,302 @@ var ObjectQLStrategy = class {
     }
     const selectParts = [];
     const groupByParts = [];
+    const params = [];
+    const granByDim = /* @__PURE__ */ new Map();
+    for (const td of query.timeDimensions ?? []) {
+      if (td.granularity) granByDim.set(td.dimension, td.granularity);
+    }
+    const tableName = this.extractObjectName(cube);
+    const plan = this.planCrossObject(cube, query, Object.fromEntries(
+      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 = [];
+    const dimExpr = (dim) => {
+      const cd = crossByDim.get(dim);
+      if (cd) {
+        joinClauses.push(
+          `LEFT JOIN "${cd.refObject}" ON "${tableName}"."${cd.fkField}" = "${cd.refObject}"."id"`
+        );
+        return `"${cd.refObject}"."${cd.attr}"`;
+      }
+      const col = this.resolveFieldName(cube, dim, "dimension");
+      const gran = granByDim.get(dim);
+      return gran ? `date_trunc('${gran}', ${col})` : col;
+    };
     if (query.dimensions) {
       for (const dim of query.dimensions) {
-        const col = this.resolveFieldName(cube, dim, "dimension");
-        selectParts.push(`${col} AS "${dim}"`);
-        groupByParts.push(col);
+        const expr = dimExpr(dim);
+        selectParts.push(`${expr} AS "${dim}"`);
+        groupByParts.push(expr);
       }
     }
+    for (const [dim] of granByDim) {
+      if (query.dimensions?.includes(dim)) continue;
+      const expr = dimExpr(dim);
+      selectParts.push(`${expr} AS "${dim}"`);
+      groupByParts.push(expr);
+    }
     if (query.measures) {
       for (const m of query.measures) {
         const { field, method } = this.resolveMeasureAggregation(cube, m);
-        const aggSql = method === "count" ? "COUNT(*)" : `${method.toUpperCase()}(${field})`;
+        const aggSql = method === "count" ? "COUNT(*)" : method === "count_distinct" ? `COUNT(DISTINCT ${field})` : `${method.toUpperCase()}(${field})`;
         selectParts.push(`${aggSql} AS "${m}"`);
       }
     }
-    const tableName = this.extractObjectName(cube);
+    const whereParts = [];
+    const filterClause = this.renderFilterNodeSql(
+      normalizeAnalyticsFilterTree(query),
+      cube,
+      params
+    );
+    if (filterClause) whereParts.push(filterClause);
+    for (const { field, bounds } of this.dateRangeBounds(cube, query)) {
+      const nextDay = nextUtcCalendarDay2(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) {
+      const { sql: scopeSql, params: scopeParams } = compileScopedFilterToSql(scope, tableName);
+      if (scopeSql) {
+        let i = 0;
+        const rendered = scopeSql.replace(/\?/g, () => {
+          params.push(scopeParams[i++]);
+          return `$${params.length}`;
+        });
+        whereParts.push(`(${rendered})`);
+      }
+    }
     let sql = `SELECT ${selectParts.join(", ")} FROM "${tableName}"`;
+    if (joinClauses.length > 0) sql += " " + joinClauses.join(" ");
+    if (whereParts.length > 0) {
+      sql += ` WHERE ${whereParts.join(" AND ")}`;
+    }
     if (groupByParts.length > 0) {
       sql += ` GROUP BY ${groupByParts.join(", ")}`;
     }
-    return { sql, params: [] };
+    if (query.order && Object.keys(query.order).length > 0) {
+      const orderClauses = Object.entries(query.order).map(([f, d]) => `"${f}" ${d.toUpperCase()}`);
+      sql += ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+    if (query.limit != null) sql += ` LIMIT ${query.limit}`;
+    if (query.offset != null) sql += ` OFFSET ${query.offset}`;
+    return { sql, params };
   }
   // ── Helpers ──────────────────────────────────────────────────────
+  /**
+   * 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.
+   */
+  withReadScope(objectName, filter, ctx) {
+    const userFilter = Object.keys(filter).length > 0 ? filter : void 0;
+    if (typeof ctx.getReadScope !== "function") return userFilter;
+    const scope = ctx.getReadScope(objectName);
+    if (scope === void 0 || scope === null) return userFilter;
+    const scopeFilter = scope;
+    if (!userFilter) return scopeFilter;
+    return { $and: [userFilter, scopeFilter] };
+  }
+  /** Is `field` a resolved cross-object (relationship-traversal) reference? */
+  isCrossObjectField(cube, field, baseObject) {
+    if (!field.includes(".")) return false;
+    const alias = field.split(".")[0];
+    const joinedObject = cube.joins?.[alias]?.name ?? alias;
+    return joinedObject !== baseObject;
+  }
+  /**
+   * 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.
+   */
+  planCrossObject(cube, query, filter) {
+    const baseObject = this.extractObjectName(cube);
+    for (const td of query.timeDimensions ?? []) {
+      const field = this.resolveFieldName(cube, td.dimension, "dimension");
+      if (this.isCrossObjectField(cube, field, baseObject)) {
+        throw new Error(
+          `[Analytics] ObjectQLStrategy cannot bucket a cross-object time dimension ("${field}").`
+        );
+      }
+    }
+    const nonDim = [
+      ...(query.measures ?? []).map((m) => ({ where: "measure", field: this.resolveMeasureAggregation(cube, m).field })),
+      ...Object.keys(filter).map((f) => ({ where: "filter", field: f }))
+    ].filter((r) => this.isCrossObjectField(cube, r.field, baseObject));
+    if (nonDim.length > 0) {
+      throw new Error(
+        `[Analytics] ObjectQLStrategy cannot evaluate a cross-object ${nonDim[0].where} ("${nonDim[0].field}") \u2014 the engine cannot join in an aggregate. Run this query on a native-SQL driver, or remove the cross-object ${nonDim[0].where}.`
+      );
+    }
+    const crossDims = [];
+    for (const dim of query.dimensions ?? []) {
+      const field = this.resolveFieldName(cube, dim, "dimension");
+      if (!this.isCrossObjectField(cube, field, baseObject)) continue;
+      const [alias, ...rest] = field.split(".");
+      const attr = rest.join(".");
+      if (attr.includes(".")) {
+        throw new Error(
+          `[Analytics] ObjectQLStrategy supports only single-hop cross-object dimensions; "${field}" traverses more than one relationship.`
+        );
+      }
+      crossDims.push({ outputName: dim, fkField: alias, attr, refObject: cube.joins?.[alias]?.name ?? alias });
+    }
+    if (crossDims.length === 0) return null;
+    for (const m of query.measures ?? []) {
+      const { method } = this.resolveMeasureAggregation(cube, m);
+      if (!RECOMBINABLE_METHODS.has(method)) {
+        throw new Error(
+          `[Analytics] ObjectQLStrategy cannot group by a cross-object dimension with a "${method}" measure ("${m}") \u2014 its value cannot be recombined across the intermediate FK grouping. Use sum/count/min/max, or run on a native-SQL driver.`
+        );
+      }
+    }
+    return { crossDims };
+  }
+  /**
+   * Serve a cross-object-dimension query by FK-expand (#3654). The pure
+   * re-bucketing step lives in `cross-object-rebucket.ts`.
+   */
+  async executeCrossObject(cube, query, aggregations, filter, plan, ctx) {
+    const baseObject = this.extractObjectName(cube);
+    const crossByDim = new Map(plan.crossDims.map((cd) => [cd.outputName, cd]));
+    const granByDim = /* @__PURE__ */ new Map();
+    for (const td of query.timeDimensions ?? []) {
+      if (td.granularity) granByDim.set(td.dimension, td.granularity);
+    }
+    const groupBy = [];
+    const baseDimFields = [];
+    for (const dim of query.dimensions ?? []) {
+      const cd = crossByDim.get(dim);
+      if (cd) {
+        groupBy.push(cd.fkField);
+        continue;
+      }
+      const field = this.resolveFieldName(cube, dim, "dimension");
+      const gran = granByDim.get(dim);
+      groupBy.push(gran ? { field, dateGranularity: gran } : field);
+      baseDimFields.push(field);
+      granByDim.delete(dim);
+    }
+    for (const [dim, gran] of granByDim) {
+      const field = this.resolveFieldName(cube, dim, "dimension");
+      groupBy.push({ field, dateGranularity: gran });
+      baseDimFields.push(field);
+    }
+    const baseRows = await ctx.executeAggregate(baseObject, {
+      groupBy: groupBy.length > 0 ? groupBy : void 0,
+      aggregations: aggregations.length > 0 ? aggregations : void 0,
+      filter: this.withReadScope(baseObject, filter, ctx),
+      timezone: query.timezone,
+      context: ctx.context
+    });
+    const resolvedDims = [];
+    for (const cd of plan.crossDims) {
+      const fkValues = [...new Set(baseRows.map((r) => r[cd.fkField]).filter((v) => v != null))];
+      const fkToAttr = await this.resolveFkAttr(cd.refObject, cd.attr, fkValues, ctx);
+      resolvedDims.push({ outputName: cd.outputName, fkField: cd.fkField, fkToAttr });
+    }
+    const measures = (query.measures ?? []).map((m) => ({
+      alias: m,
+      // planCrossObject already asserted every measure is recombinable.
+      method: this.resolveMeasureAggregation(cube, m).method
+    }));
+    const merged = rebucketCrossObject(baseRows, baseDimFields, resolvedDims, measures);
+    const mappedRows = merged.map((row) => {
+      const out = {};
+      for (const dim of this.projectedDimensions(query)) {
+        if (crossByDim.has(dim)) {
+          if (dim in row) out[dim] = row[dim];
+        } else {
+          const field = this.resolveFieldName(cube, dim, "dimension");
+          if (field in row) out[dim] = row[field];
+        }
+      }
+      for (const m of query.measures ?? []) {
+        if (m in row) out[m] = row[m];
+      }
+      return out;
+    });
+    return { rows: mappedRows, fields: this.buildFieldMeta(query, cube) };
+  }
+  /**
+   * 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).
+   */
+  async resolveFkAttr(refObject, attr, fkValues, ctx) {
+    const map = /* @__PURE__ */ new Map();
+    if (fkValues.length === 0 || typeof ctx.executeAggregate !== "function") return map;
+    const idFilter = { id: { $in: fkValues } };
+    const scope = typeof ctx.getReadScope === "function" ? ctx.getReadScope(refObject) : null;
+    const filter = scope != null ? { $and: [idFilter, scope] } : idFilter;
+    const rows = await ctx.executeAggregate(refObject, {
+      groupBy: ["id", attr],
+      aggregations: [{ field: "id", method: "count", alias: "_c" }],
+      filter,
+      context: ctx.context
+    });
+    for (const r of rows) {
+      if (r.id != null) map.set(r.id, r[attr]);
+    }
+    return map;
+  }
+  /**
+   * 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.
+   */
+  buildFilterClauseSql(col, operator, values, params) {
+    if (operator === "set") return `${col} IS NOT NULL`;
+    if (operator === "notSet") return `${col} IS NULL`;
+    if (!values || values.length === 0) return null;
+    if (operator === "in" || operator === "notIn") {
+      const placeholders = values.map((v) => {
+        params.push(coerceFilterValueForObjectQL(v));
+        return `$${params.length}`;
+      }).join(", ");
+      return `${col} ${operator === "in" ? "IN" : "NOT IN"} (${placeholders})`;
+    }
+    if (operator === "contains" || operator === "notContains") {
+      params.push(`%${values[0]}%`);
+      return `${col} ${operator === "contains" ? "LIKE" : "NOT LIKE"} $${params.length}`;
+    }
+    const op = SCALAR_SQL_OPS[operator];
+    if (!op) return null;
+    params.push(coerceFilterValueForObjectQL(values[0]));
+    return `${col} ${op} $${params.length}`;
+  }
   /**
    * Resolve a member ref to a `{ sql, type? }` definition.
    *
@@ -839,6 +1330,162 @@ var ObjectQLStrategy = class {
     }
     return { field: "*", method: "count" };
   }
+  /**
+   * 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.
+   */
+  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) {
+      filter[field] = operand;
+      return null;
+    }
+    const mergeable = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+    if (!mergeable(existing) || !mergeable(operand)) return { [field]: operand };
+    if (Object.keys(operand).some((op) => op in existing)) return { [field]: operand };
+    filter[field] = { ...existing, ...operand };
+    return null;
+  }
+  /**
+   * 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.
+   */
+  dateRangeBounds(cube, query) {
+    const out = [];
+    for (const td of query.timeDimensions ?? []) {
+      if (!td.dateRange) continue;
+      const range = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
+      const [start, end = start] = range;
+      if (start == null) continue;
+      out.push({
+        field: this.resolveFieldName(cube, td.dimension, "dimension"),
+        bounds: {
+          $gte: coerceFilterValueForObjectQL(String(start)),
+          $lte: coerceFilterValueForObjectQL(String(end))
+        }
+      });
+    }
+    return out;
+  }
   convertFilter(operator, values) {
     if (operator === "set") return { $ne: null };
     if (operator === "notSet") return null;
@@ -860,24 +1507,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) {
@@ -889,14 +1572,16 @@ var ObjectQLStrategy = class {
 };
 
 // src/dataset-compiler.ts
+import { AggregationFunction } from "@objectstack/spec/data";
 var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set(["array_agg", "string_agg"]);
+var SUPPORTED_AGGREGATES = 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;
@@ -1023,6 +1708,23 @@ function compileDataset(dataset, resolver) {
 }
 
 // src/dataset-executor.ts
+import { filterTokenContextFrom, resolveFilterTokens } from "@objectstack/core";
+function resolveSelectionTokens(compiled, selection, context) {
+  const tokenCtx = filterTokenContextFrom(context, /* @__PURE__ */ new Date());
+  const resolve = (v) => resolveFilterTokens(v, tokenCtx);
+  const filter = resolve(compiled.filter);
+  const measureFilters = resolve(compiled.measureFilters);
+  const runtimeFilter = resolve(selection.runtimeFilter);
+  const timeDimensions = selection.timeDimensions?.map(
+    (td) => td.dateRange == null ? td : { ...td, dateRange: resolve(td.dateRange) }
+  );
+  const compiledChanged = filter !== compiled.filter || measureFilters !== compiled.measureFilters;
+  const selectionChanged = runtimeFilter !== selection.runtimeFilter || timeDimensions !== void 0 && timeDimensions.some((td, i) => td !== selection.timeDimensions[i]);
+  return {
+    compiled: compiledChanged ? { ...compiled, filter, measureFilters } : compiled,
+    selection: selectionChanged ? { ...selection, runtimeFilter, timeDimensions } : selection
+  };
+}
 function combineFilters(a, b) {
   if (a && b) return { $and: [a, b] };
   return a ?? b;
@@ -1061,6 +1763,76 @@ function computeDerived(d, row) {
       return null;
   }
 }
+function resolveDimensionGranularity(selection, dimension, datasetDefault) {
+  const stated = (selection.timeDimensions ?? []).find((t) => t.dimension === dimension)?.granularity;
+  if (stated) return stated;
+  return selection.dateGranularity ?? datasetDefault;
+}
+function compareValues(a, b) {
+  const aNull = a == null || a === "";
+  const bNull = b == null || b === "";
+  if (aNull || bNull) return aNull && bNull ? 0 : aNull ? 1 : -1;
+  if (a instanceof Date || b instanceof Date) {
+    return Number(a instanceof Date ? a.getTime() : a) - Number(b instanceof Date ? b.getTime() : b);
+  }
+  if (typeof a === "boolean" || typeof b === "boolean") {
+    return Number(a) - Number(b);
+  }
+  const an = typeof a === "number" ? a : Number(a);
+  const bn = typeof b === "number" ? b : Number(b);
+  if (Number.isFinite(an) && Number.isFinite(bn)) return an - bn;
+  return String(a).localeCompare(String(b));
+}
+function applyOrdering(rows, order, sortKeys) {
+  const keys = Object.entries(order ?? {});
+  if (keys.length === 0 || rows.length < 2) return rows;
+  return [...rows].sort((ra, rb) => {
+    for (const [key, dir] of keys) {
+      const map = sortKeys?.[key];
+      const av = map?.get(ra[key]) ?? ra[key];
+      const bv = map?.get(rb[key]) ?? rb[key];
+      const aNull = av == null || av === "";
+      const bNull = bv == null || bv === "";
+      if (aNull || bNull) {
+        if (aNull && bNull) continue;
+        return aNull ? 1 : -1;
+      }
+      const c = compareValues(av, bv);
+      if (c !== 0) return dir === "desc" ? -c : c;
+    }
+    return 0;
+  });
+}
+function applyWindow(rows, limit, offset) {
+  const start = offset != null && offset > 0 ? offset : 0;
+  if (start === 0 && limit == null) return rows;
+  return rows.slice(start, limit != null ? start + limit : void 0);
+}
+function resolveOrdering(selection, dimensions, timeDimensions = []) {
+  const order = selection.order;
+  if (order && Object.keys(order).length > 0) {
+    const selectable = /* @__PURE__ */ new Set([
+      ...dimensions,
+      ...selection.measures,
+      ...selection.measures.map((m) => `${m}__compare`)
+    ]);
+    const unknown = Object.keys(order).filter((k) => !selectable.has(k));
+    if (unknown.length) {
+      throw new Error(
+        `[dataset-executor] order key(s) ${unknown.map((k) => `"${k}"`).join(", ")} \u2014 not a selected dimension or measure. Selectable here: ${[...selectable].join(", ") || "(none)"}.`
+      );
+    }
+    return order;
+  }
+  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) {
   const ms = Date.parse(date.length === 10 ? `${date}T00:00:00Z` : date);
   if (Number.isNaN(ms)) throw new Error(`[dataset-executor] invalid date in dateRange: "${date}"`);
@@ -1088,8 +1860,17 @@ function shiftRange(range, kind) {
   return [toISODate(prevStartMs), toISODate(prevEndMs)];
 }
 var DatasetExecutor = class {
-  constructor(service) {
+  /**
+   * @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, orderLabels) {
     this.service = service;
+    this.orderLabels = orderLabels;
   }
   /**
    * Execute a dataset selection and return the shaped rows (+ field metadata).
@@ -1098,7 +1879,8 @@ var DatasetExecutor = class {
    *   underlying `IAnalyticsService.query` so the tenant/RLS read scope is
    *   applied per request (ADR-0021 D-C).
    */
-  async execute(compiled, selection, context) {
+  async execute(compiledInput, selectionInput, context) {
+    const { compiled, selection } = resolveSelectionTokens(compiledInput, selectionInput, context);
     const result = await this.executeSelection(compiled, selection, context);
     const groupings = selection.totals?.groupings;
     if (groupings?.length) {
@@ -1142,6 +1924,14 @@ var DatasetExecutor = class {
     }
     const baseFilter = combineFilters(compiled.filter, selection.runtimeFilter);
     const dimensions = 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)
+    ) : [];
+    const singleQuery = filtered.length === 0 && !selection.compareTo && selectedDerived.length === 0;
+    const pushDownKeys = /* @__PURE__ */ new Set([...dimensions, ...unfiltered]);
+    const canPushDownWindow = singleQuery && labelOrderKeys.length === 0 && Object.keys(order ?? {}).every((k) => pushDownKeys.has(k));
+    const windowQuery = canPushDownWindow ? { order, limit: selection.limit, offset: selection.offset } : void 0;
     let result;
     if (unfiltered.length > 0 || filtered.length === 0) {
       result = await this.service.query(this.buildQuery(compiled, {
@@ -1149,7 +1939,8 @@ var DatasetExecutor = class {
         dimensions,
         where: baseFilter,
         selection,
-        contextTimezone: context?.timezone
+        contextTimezone: context?.timezone,
+        window: windowQuery
       }), context);
     } else {
       result = { rows: [], fields: [] };
@@ -1178,8 +1969,30 @@ var DatasetExecutor = class {
     }
     result.rows = evaluateDerivedMeasures(result.rows, selectedDerived);
     for (const d of selectedDerived) result.fields.push({ name: d.name, type: "number" });
+    let sortKeys;
+    for (const key of labelOrderKeys) {
+      const values = [...new Set(result.rows.map((r) => r[key]).filter((v) => v != null))];
+      if (values.length === 0) continue;
+      const labels = await this.orderLabels.resolveLabels(key, values);
+      if (labels && labels.size > 0) (sortKeys ?? (sortKeys = {}))[key] = labels;
+    }
+    result.rows = applyOrdering(result.rows, order, sortKeys);
+    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,
@@ -1192,18 +2005,28 @@ var DatasetExecutor = class {
     if (opts.where) q.where = opts.where;
     const selTimeDims = opts.selection.timeDimensions ?? [];
     const selDims = new Set(selTimeDims.map((t) => t.dimension));
+    const granularityFor = (name) => {
+      const cd = compiled.cube.dimensions[name];
+      if (cd?.type !== "time") return void 0;
+      const datasetDefault = cd.granularities?.length === 1 ? String(cd.granularities[0]) : void 0;
+      return resolveDimensionGranularity(opts.selection, name, datasetDefault);
+    };
+    const resolvedTimeDims = selTimeDims.map((t) => {
+      if (t.granularity) return t;
+      const granularity = granularityFor(t.dimension);
+      return granularity ? { ...t, granularity } : t;
+    });
     const explicitTimeDims = [];
     for (const name of opts.dimensions) {
-      const cd = compiled.cube.dimensions[name];
-      if (cd?.type === "time" && cd.granularities?.length === 1 && !selDims.has(name)) {
-        explicitTimeDims.push({ dimension: name, granularity: String(cd.granularities[0]) });
-      }
+      if (selDims.has(name)) continue;
+      const granularity = granularityFor(name);
+      if (granularity) explicitTimeDims.push({ dimension: name, granularity });
     }
-    const mergedTimeDims = [...selTimeDims, ...explicitTimeDims];
+    const mergedTimeDims = [...resolvedTimeDims, ...explicitTimeDims];
     if (mergedTimeDims.length > 0) q.timeDimensions = mergedTimeDims;
-    if (opts.selection.order) q.order = opts.selection.order;
-    if (opts.selection.limit != null) q.limit = opts.selection.limit;
-    if (opts.selection.offset != null) q.offset = opts.selection.offset;
+    if (opts.window?.order && Object.keys(opts.window.order).length > 0) q.order = opts.window.order;
+    if (opts.window?.limit != null) q.limit = opts.window.limit;
+    if (opts.window?.offset != null) q.offset = opts.window.offset;
     return q;
   }
   async runCompare(compiled, selection, measures, dimensions, baseFilter, context) {
@@ -1219,14 +2042,13 @@ var DatasetExecutor = class {
     const shiftedTd = (selection.timeDimensions ?? []).map(
       (t) => t.dimension === cmp.dimension ? { ...t, dateRange: shifted } : t
     );
-    const sub = await this.service.query({
-      cube: compiled.cube.name,
+    const sub = await this.service.query(this.buildQuery(compiled, {
       measures,
       dimensions,
       where: baseFilter,
-      timeDimensions: shiftedTd,
-      timezone: selection.timezone ?? context?.timezone ?? "UTC"
-    }, context);
+      selection: { ...selection, timeDimensions: shiftedTd },
+      contextTimezone: context?.timezone
+    }), context);
     return sub.rows.map((row) => {
       const out = {};
       for (const dim of dimensions) out[dim] = row[dim];
@@ -1257,11 +2079,77 @@ function mergeByDimensions(base, extra, dimensions, valueColumns) {
 
 // src/dimension-labels.ts
 var LOOKUP_TYPES = /* @__PURE__ */ new Set(["lookup", "master_detail"]);
+function createOrderLabelResolver(baseObject, dims, deps, resolveScope, context) {
+  const dimByName = new Map(dims.map((d) => [d.name, d]));
+  const metaFor = (dimension) => {
+    const dim = dimByName.get(dimension);
+    return dim ? deps.getObjectFields(baseObject)?.[dim.field] : void 0;
+  };
+  return {
+    isLabelBearing(dimension) {
+      const meta = metaFor(dimension);
+      if (!meta) return false;
+      if (Array.isArray(meta.options) && meta.options.length > 0) return true;
+      return !!(meta.type && LOOKUP_TYPES.has(meta.type) && meta.reference);
+    },
+    async resolveLabels(dimension, values) {
+      const meta = metaFor(dimension);
+      if (!meta) return void 0;
+      if (Array.isArray(meta.options) && meta.options.length > 0) {
+        const labelByValue = /* @__PURE__ */ new Map();
+        for (const opt of meta.options) {
+          if (opt && opt.label != null) labelByValue.set(opt.value, String(opt.label));
+        }
+        return labelByValue;
+      }
+      if (meta.type && LOOKUP_TYPES.has(meta.type) && meta.reference) {
+        let scope;
+        if (resolveScope) {
+          try {
+            scope = await resolveScope(meta.reference);
+          } catch {
+            return void 0;
+          }
+        }
+        return deps.fetchRecordLabels(meta.reference, values, scope ?? void 0, context);
+      }
+      return void 0;
+    }
+  };
+}
+function withLabelFetchCache(deps) {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    getObjectFields: (objectName) => deps.getObjectFields(objectName),
+    async fetchRecordLabels(targetObject, ids, scope, context) {
+      let known = cache.get(targetObject);
+      if (!known) {
+        known = /* @__PURE__ */ new Map();
+        cache.set(targetObject, known);
+      }
+      const missing = ids.filter((id) => !known.has(id));
+      if (missing.length > 0) {
+        const fetched = await deps.fetchRecordLabels(targetObject, missing, scope, context);
+        for (const id of missing) known.set(id, fetched.get(id) ?? null);
+      }
+      const out = /* @__PURE__ */ new Map();
+      for (const id of ids) {
+        const label = known.get(id);
+        if (label != null) out.set(id, label);
+      }
+      return out;
+    }
+  };
+}
 var pad = (n) => String(n).padStart(2, "0");
 function formatDateBucket(value, granularity) {
   if (value == null || value instanceof Date === false) {
     if (typeof value !== "number" && typeof value !== "string") return value;
   }
+  if (granularity === "year") {
+    const y2 = typeof value === "number" ? value : Number(String(value).trim());
+    if (Number.isInteger(y2) && y2 >= 1e3 && y2 <= 9999) return String(y2);
+  }
   let d;
   if (value instanceof Date) d = value;
   else if (typeof value === "number") d = new Date(value);
@@ -1285,7 +2173,7 @@ function formatDateBucket(value, granularity) {
       return `${y}-${pad(m + 1)}-${pad(d.getUTCDate())}`;
   }
 }
-async function resolveDimensionLabels(baseObject, dims, rows, deps) {
+async function resolveDimensionLabels(baseObject, dims, rows, deps, resolveScope, context) {
   if (!rows.length || !dims.length) return;
   const fields = deps.getObjectFields(baseObject);
   if (!fields) return;
@@ -1317,7 +2205,15 @@ async function resolveDimensionLabels(baseObject, dims, rows, deps) {
         new Set(rows.map((r) => r[dim.name]).filter((v) => v != null))
       );
       if (ids.length === 0) continue;
-      const labelById = await deps.fetchRecordLabels(meta.reference, ids);
+      let scope;
+      if (resolveScope) {
+        try {
+          scope = await resolveScope(meta.reference);
+        } catch {
+          continue;
+        }
+      }
+      const labelById = await deps.fetchRecordLabels(meta.reference, ids, scope ?? void 0, context);
       if (!labelById || labelById.size === 0) continue;
       for (const row of rows) {
         const label = labelById.get(row[dim.name]);
@@ -1338,11 +2234,21 @@ function pickDisplayField(fields) {
 }
 
 // src/preview-evaluator.ts
-import { calendarPartsInTzOrUtc } from "@objectstack/core";
+import { calendarPartsInTzOrUtc, nextUtcCalendarDay as nextUtcCalendarDay3, utcInstantMs } from "@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 = utcInstantMs(a);
+    const bi = 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 = nextUtcCalendarDay3(bound);
+  if (nextDay != null) return compare(value, nextDay) < 0;
+  return compare(value, bound) <= 0;
+}
 function matchOp(value, op, expected) {
   switch (op) {
     case "$eq":
@@ -1355,8 +2261,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":
@@ -1443,7 +2357,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 = nextUtcCalendarDay3(end);
+      const inUpper = nextDay != null ? v < nextDay : v <= `${end}~`;
+      return v >= String(start) && inUpper;
     });
   }
   const dimensions = query.dimensions ?? [];
@@ -1511,6 +2427,8 @@ var AnalyticsService = class {
   constructor(config = {}) {
     /** Compiled datasets by name — feeds the join allowlist (D-C) and queryDataset. */
     this.datasetRegistry = /* @__PURE__ */ new Map();
+    /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
+    this.warnedNoObjectRegistry = false;
     this.logger = config.logger || createLogger({ level: "info", format: "pretty" });
     this.cubeRegistry = new CubeRegistry();
     if (config.cubes) {
@@ -1521,6 +2439,7 @@ var AnalyticsService = class {
     this.measureCurrency = config.measureCurrency;
     this.labelResolver = config.labelResolver;
     this.draftRowsResolver = config.draftRowsResolver;
+    this.isRegisteredObject = config.isRegisteredObject;
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -1540,6 +2459,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 = [
@@ -1561,10 +2481,11 @@ var AnalyticsService = class {
    * `getReadScope(objectName)` that already knows the active tenant.
    */
   async callCtx(query, context) {
-    if (!this.readScopeProvider) return this.baseCtx;
+    if (!this.readScopeProvider) return { ...this.baseCtx, context };
     const scopes = await this.resolveReadScopes(query, context);
     return {
       ...this.baseCtx,
+      context,
       getReadScope: (objectName) => scopes.get(objectName) ?? null
     };
   }
@@ -1685,9 +2606,19 @@ var AnalyticsService = class {
         return previewResult;
       }
     }
+    const provider = this.readScopeProvider;
+    const resolveScope = provider ? (targetObject) => provider(targetObject, context) : void 0;
+    const labelDeps = this.labelResolver ? withLabelFetchCache(this.labelResolver) : void 0;
+    const orderLabels = labelDeps && dataset.dimensions?.length ? createOrderLabelResolver(
+      dataset.object,
+      dataset.dimensions.filter((d) => !!d.field).map((d) => ({ name: d.name, field: d.field })),
+      labelDeps,
+      resolveScope,
+      context
+    ) : void 0;
     let result;
     try {
-      result = await new DatasetExecutor(this).execute(compiled, selection, context);
+      result = await new DatasetExecutor(this, orderLabels).execute(compiled, selection, context);
     } catch (err) {
       if (isMissingSourceError(err)) {
         this.logger.warn(
@@ -1723,18 +2654,20 @@ var AnalyticsService = class {
     const rangeTz = selection.timezone ?? context?.timezone ?? "UTC";
     const rangeDims = [];
     for (const d of selectedDims) {
-      if (!d.field || d.type !== "date" || !d.dateGranularity) continue;
+      if (!d.field || d.type !== "date") continue;
+      const granularity = resolveDimensionGranularity(selection, d.name, d.dateGranularity);
+      if (!granularity) continue;
       const ftype = this.measureCurrency?.(dataset.object, d.field)?.type;
-      if (ftype === "datetime") rangeDims.push({ d, instant: true });
-      else if (ftype === "date") rangeDims.push({ d, instant: false });
-      else if (rangeTz === "UTC") rangeDims.push({ d, instant: false });
+      if (ftype === "datetime") rangeDims.push({ d, granularity, instant: true });
+      else if (ftype === "date") rangeDims.push({ d, granularity, instant: false });
+      else if (rangeTz === "UTC") rangeDims.push({ d, granularity, instant: false });
     }
     if (rangeDims.length && result.rows.length) {
       const bound = (ymd, instant) => instant ? new Date(zonedDateStartToUtcMs(ymd, rangeTz)).toISOString() : ymd;
       result.drillRanges = result.rows.map((row) => {
         const ranges = {};
-        for (const { d, instant } of rangeDims) {
-          const cal = bucketKeyToCalendarRange(row[d.name], d.dateGranularity);
+        for (const { d, granularity, instant } of rangeDims) {
+          const cal = bucketKeyToCalendarRange(row[d.name], granularity);
           if (cal) {
             ranges[d.name] = { field: d.field, gte: bound(cal.start, instant), lt: bound(cal.end, instant) };
           }
@@ -1743,15 +2676,20 @@ var AnalyticsService = class {
       });
       result.object = dataset.object;
     }
-    if (this.labelResolver && selectedDims.length) {
-      const dims = selectedDims.filter((d) => !!d.field).map((d) => ({ name: d.name, field: d.field, type: d.type, dateGranularity: d.dateGranularity }));
+    if (labelDeps && selectedDims.length) {
+      const dims = selectedDims.filter((d) => !!d.field).map((d) => ({
+        name: d.name,
+        field: d.field,
+        type: d.type,
+        dateGranularity: resolveDimensionGranularity(selection, d.name, d.dateGranularity)
+      }));
       if (dims.length) {
         try {
-          await resolveDimensionLabels(dataset.object, dims, result.rows, this.labelResolver);
+          await resolveDimensionLabels(dataset.object, dims, result.rows, labelDeps, resolveScope, context);
           for (const total of result.totals ?? []) {
             const subset = dims.filter((d) => total.dimensions.includes(d.name));
             if (subset.length) {
-              await resolveDimensionLabels(dataset.object, subset, total.rows, this.labelResolver);
+              await resolveDimensionLabels(dataset.object, subset, total.rows, labelDeps, resolveScope, context);
             }
           }
         } catch (e) {
@@ -1839,6 +2777,7 @@ var AnalyticsService = class {
     const name = query.cube;
     let cube = this.cubeRegistry.get(name);
     if (!cube) {
+      this.assertInferableCube(name);
       cube = this.inferCubeFromQuery(query);
       this.cubeRegistry.register(cube);
       const isScalarMetric = (query.dimensions?.length ?? 0) === 0 && (query.timeDimensions?.length ?? 0) === 0;
@@ -1865,6 +2804,39 @@ var AnalyticsService = class {
       );
     }
   }
+  /**
+   * [#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.
+   */
+  assertInferableCube(name) {
+    const isRegisteredObject = this.isRegisteredObject;
+    if (!isRegisteredObject) {
+      if (!this.warnedNoObjectRegistry) {
+        this.warnedNoObjectRegistry = true;
+        this.logger.warn(
+          "[Analytics] no object-registry hook configured \u2014 the cube-inference existence gate (#3867) is INACTIVE for this service; an unregistered cube name reaches the driver as a raw table name."
+        );
+      }
+      return;
+    }
+    if (isRegisteredObject(name)) return;
+    const err = new Error(
+      `Cube '${name}' not found: no cube is registered under that name, and it is not a registered object either (a cube can only be auto-inferred from a registered object). Define a Cube in your stack, or check the object name.`
+    );
+    err.code = "CUBE_NOT_FOUND";
+    err.status = 404;
+    err.cube = name;
+    throw err;
+  }
   /** Build a minimal Cube from the fields referenced by an AnalyticsQuery. */
   inferCubeFromQuery(query) {
     const cubeName = query.cube;
@@ -1975,6 +2947,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 = [];
@@ -2006,7 +2983,7 @@ var AnalyticsServicePlugin = class {
           '[Analytics] No "data" service registered yet at init; will retry per-query. Register ObjectQLPlugin or pass executeAggregate.'
         );
       }
-      executeAggregate = async (objectName, { groupBy, aggregations, filter, timezone }) => {
+      executeAggregate = async (objectName, { groupBy, aggregations, filter, timezone, context }) => {
         const engine = tryGetDataEngine();
         if (!engine) {
           throw new Error(
@@ -2023,7 +3000,13 @@ var AnalyticsServicePlugin = class {
           })),
           // ADR-0053 Phase 2: thread the reference tz so date buckets resolve on
           // that zone's calendar days (engine buckets in-memory when non-UTC).
-          timezone
+          timezone,
+          // ADR-0021 D-C (#3602): thread the caller's identity so the engine's
+          // middleware chain scopes the read itself. `BaseEngineOptions.context`
+          // is `.optional()`, so nothing ever forced this bridge to pass it —
+          // and it did not, which is how an authenticated aggregate reached the
+          // engine with no principal and plugin-security fell open (#3597).
+          context
         });
         return rows;
       };
@@ -2071,6 +3054,7 @@ var AnalyticsServicePlugin = class {
     }));
     let getReadScope = this.options.getReadScope;
     let autoBridgedReadScope = false;
+    let securityPresentAtInit = false;
     if (!getReadScope) {
       const trySecurity = () => {
         try {
@@ -2080,10 +3064,9 @@ var AnalyticsServicePlugin = class {
           return void 0;
         }
       };
-      if (trySecurity()) {
-        getReadScope = (object, context) => trySecurity()?.getReadFilter(object, context);
-        autoBridgedReadScope = true;
-      }
+      securityPresentAtInit = !!trySecurity();
+      getReadScope = (object, context) => trySecurity()?.getReadFilter(object, context);
+      autoBridgedReadScope = true;
     }
     const relationshipResolver = (baseObject, relationshipName) => {
       const engine = (() => {
@@ -2111,17 +3094,26 @@ var AnalyticsServicePlugin = class {
     };
     const labelResolver = {
       getObjectFields: (objectName) => dataEngine()?.getObject?.(objectName)?.fields,
-      fetchRecordLabels: async (targetObject, ids) => {
+      fetchRecordLabels: async (targetObject, ids, scope, context) => {
         const map = /* @__PURE__ */ new Map();
         const displayField = pickDisplayField(dataEngine()?.getObject?.(targetObject)?.fields);
         if (!displayField || !executeAggregate || ids.length === 0) return map;
-        const rows = await executeAggregate(targetObject, {
-          groupBy: ["id", displayField],
-          aggregations: [{ field: "id", method: "count", alias: "_c" }],
-          filter: { id: { $in: ids } }
-        });
-        for (const r of rows) {
-          if (r.id != null && r[displayField] != null) map.set(r.id, String(r[displayField]));
+        const CHUNK = 500;
+        for (let i = 0; i < ids.length; i += CHUNK) {
+          const idFilter = { id: { $in: ids.slice(i, i + CHUNK) } };
+          const filter = scope ? { $and: [idFilter, scope] } : idFilter;
+          const rows = await executeAggregate(targetObject, {
+            groupBy: ["id", displayField],
+            aggregations: [{ field: "id", method: "count", alias: "_c" }],
+            filter,
+            // #3602 second belt — `scope` above is the analytics layer's own
+            // predicate on this per-record read; the context makes the engine's
+            // middleware scope it as well.
+            context
+          });
+          for (const r of rows) {
+            if (r.id != null && r[displayField] != null) map.set(r.id, String(r[displayField]));
+          }
         }
         return map;
       }
@@ -2162,6 +3154,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,
@@ -2172,6 +3175,7 @@ var AnalyticsServicePlugin = class {
       getReadScope,
       getAllowedRelationships: this.options.getAllowedRelationships,
       coerceTemporalFilterValue,
+      coerceTemporalFilterColumn,
       relationshipResolver,
       labelResolver,
       // ADR-0053 — source-field currency metadata for the measure currency chain.
@@ -2186,13 +3190,31 @@ var AnalyticsServicePlugin = class {
         const obj = dataEngine()?.getObject?.(objectName);
         return !!(obj && obj.external != null);
       },
+      // [#3867] Existence probe for the cube auto-inference gate. Reads the
+      // same schema registry the data path's #3770 gate consults, through the
+      // engine accessor this bridge already uses above — so "which objects
+      // exist" has one answer across /data and /analytics.
+      //
+      // `dataEngine()` resolves lazily and may be absent entirely (analytics
+      // installed without a data engine). Reporting `false` there would 404
+      // every cube, so an unresolvable engine reports `true` — "cannot answer,
+      // do not block" — mirroring the tiering #3770 took on the data path.
+      isRegisteredObject: (name) => {
+        const engine = dataEngine();
+        if (!engine) return true;
+        return engine.getObject?.(name) != null;
+      },
       draftRowsResolver
     };
-    if (autoBridgedReadScope) {
+    if (autoBridgedReadScope && securityPresentAtInit) {
       ctx.logger.info('[Analytics] Auto-bridged getReadScope \u2192 "security" service (getReadFilter)');
+    } else if (autoBridgedReadScope) {
+      ctx.logger.info(
+        '[Analytics] getReadScope bridged to the "security" service; that service is not registered yet at init and will be resolved per query (plugin order is not significant).'
+      );
     } else if (!getReadScope) {
       ctx.logger.warn(
-        '[Analytics] No getReadScope configured and no "security" service with getReadFilter found \u2014 the raw-SQL analytics path will NOT enforce tenant/RLS scoping on joined objects (ADR-0021 D-C). Supply getReadScope or register a security service in multi-tenant deployments.'
+        '[Analytics] No getReadScope configured and no "security" service with getReadFilter found \u2014 analytics queries will NOT enforce tenant/RLS scoping (ADR-0021 D-C). Supply getReadScope or register a security service in multi-tenant deployments.'
       );
     }
     if (autoBridged) {
@@ -2235,10 +3257,12 @@ export {
   combineFilters,
   compileDataset,
   compileScopedFilterToSql,
+  createOrderLabelResolver,
   evaluateDerivedMeasures,
   mergeByDimensions,
   pickDisplayField,
   resolveDimensionLabels,
-  shiftRange
+  shiftRange,
+  withLabelFetchCache
 };
 //# sourceMappingURL=index.js.map