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

package/dist/index.cjs

@@ -29,16 +29,18 @@ __export(index_exports, {
   combineFilters: () => combineFilters,
   compileDataset: () => compileDataset,
   compileScopedFilterToSql: () => compileScopedFilterToSql,
+  createOrderLabelResolver: () => createOrderLabelResolver,
   evaluateDerivedMeasures: () => evaluateDerivedMeasures,
   mergeByDimensions: () => mergeByDimensions,
   pickDisplayField: () => pickDisplayField,
   resolveDimensionLabels: () => resolveDimensionLabels,
-  shiftRange: () => shiftRange
+  shiftRange: () => shiftRange,
+  withLabelFetchCache: () => withLabelFetchCache
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/analytics-service.ts
-var import_core2 = require("@objectstack/core");
+var import_core3 = require("@objectstack/core");
 
 // src/cube-registry.ts
 var CubeRegistry = class {
@@ -707,7 +709,70 @@ var NativeSQLStrategy = class {
   }
 };
 
+// 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";
@@ -745,15 +810,22 @@ 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 = [];
+    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);
+    }
+    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
@@ -761,11 +833,17 @@ 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 = {};
@@ -783,8 +861,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) {
@@ -792,28 +890,307 @@ 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(
+      normalizeAnalyticsFilters(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 = [];
+    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);
+    }
+    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 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 query.dimensions ?? []) {
+        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 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];
+      }
+      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.
    *
@@ -878,6 +1255,89 @@ 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.
+   */
+  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 — 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.
+   *
+   * 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;
@@ -1062,6 +1522,23 @@ function compileDataset(dataset, resolver) {
 }
 
 // src/dataset-executor.ts
+var import_core = 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 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;
@@ -1100,6 +1577,72 @@ 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) {
+  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"]));
+  }
+  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}"`);
@@ -1127,8 +1670,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).
@@ -1137,7 +1689,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) {
@@ -1181,6 +1734,14 @@ var DatasetExecutor = class {
     }
     const baseFilter = combineFilters(compiled.filter, selection.runtimeFilter);
     const dimensions = selection.dimensions ?? [];
+    const order = resolveOrdering(selection, 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, {
@@ -1188,7 +1749,8 @@ var DatasetExecutor = class {
         dimensions,
         where: baseFilter,
         selection,
-        contextTimezone: context?.timezone
+        contextTimezone: context?.timezone,
+        window: windowQuery
       }), context);
     } else {
       result = { rows: [], fields: [] };
@@ -1217,6 +1779,15 @@ 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;
   }
   buildQuery(compiled, opts) {
@@ -1231,18 +1802,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) {
@@ -1258,14 +1839,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];
@@ -1296,11 +1876,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);
@@ -1324,7 +1970,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;
@@ -1356,7 +2002,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]);
@@ -1377,7 +2031,7 @@ function pickDisplayField(fields) {
 }
 
 // src/preview-evaluator.ts
-var import_core = require("@objectstack/core");
+var import_core2 = require("@objectstack/core");
 function compare(a, b) {
   if (typeof a === "number" && typeof b === "number") return a - b;
   return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
@@ -1428,7 +2082,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_core.calendarPartsInTzOrUtc)(d, timezone);
+  const { year: y, month, day: dayNum } = (0, import_core2.calendarPartsInTzOrUtc)(d, timezone);
   const m = `${month}`.padStart(2, "0");
   const day = `${dayNum}`.padStart(2, "0");
   switch (granularity) {
@@ -1550,7 +2204,9 @@ var AnalyticsService = class {
   constructor(config = {}) {
     /** Compiled datasets by name — feeds the join allowlist (D-C) and queryDataset. */
     this.datasetRegistry = /* @__PURE__ */ new Map();
-    this.logger = config.logger || (0, import_core2.createLogger)({ level: "info", format: "pretty" });
+    /** [#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.cubeRegistry = new CubeRegistry();
     if (config.cubes) {
       this.cubeRegistry.registerAll(config.cubes);
@@ -1560,6 +2216,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 {
@@ -1600,10 +2257,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
     };
   }
@@ -1724,9 +2382,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(
@@ -1762,18 +2430,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((0, import_core2.zonedDateStartToUtcMs)(ymd, rangeTz)).toISOString() : ymd;
+      const bound = (ymd, instant) => instant ? new Date((0, import_core3.zonedDateStartToUtcMs)(ymd, rangeTz)).toISOString() : ymd;
       result.drillRanges = result.rows.map((row) => {
         const ranges = {};
-        for (const { d, instant } of rangeDims) {
-          const cal = (0, import_core2.bucketKeyToCalendarRange)(row[d.name], d.dateGranularity);
+        for (const { d, granularity, instant } of rangeDims) {
+          const cal = (0, import_core3.bucketKeyToCalendarRange)(row[d.name], granularity);
           if (cal) {
             ranges[d.name] = { field: d.field, gte: bound(cal.start, instant), lt: bound(cal.end, instant) };
           }
@@ -1782,15 +2452,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) {
@@ -1878,6 +2553,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;
@@ -1904,6 +2580,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;
@@ -2045,7 +2754,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(
@@ -2062,7 +2771,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;
       };
@@ -2110,6 +2825,7 @@ var AnalyticsServicePlugin = class {
     }));
     let getReadScope = this.options.getReadScope;
     let autoBridgedReadScope = false;
+    let securityPresentAtInit = false;
     if (!getReadScope) {
       const trySecurity = () => {
         try {
@@ -2119,10 +2835,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 = (() => {
@@ -2150,17 +2865,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;
       }
@@ -2225,13 +2949,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) {
@@ -2275,10 +3017,12 @@ var AnalyticsServicePlugin = class {
   combineFilters,
   compileDataset,
   compileScopedFilterToSql,
+  createOrderLabelResolver,
   evaluateDerivedMeasures,
   mergeByDimensions,
   pickDisplayField,
   resolveDimensionLabels,
-  shiftRange
+  shiftRange,
+  withLabelFetchCache
 });
 //# sourceMappingURL=index.cjs.map