@objectstack/service-analytics 17.0.0-rc.4 → 17.0.0-rc.6

package/dist/index.js

@@ -1,6 +1,8 @@
 // src/analytics-service.ts
 import { percentScaleOf } from "@objectstack/spec/data";
-import { createLogger, bucketKeyToCalendarRange, zonedDateStartToUtcMs } from "@objectstack/core";
+import { resolveI18nLabel as resolveI18nLabel2 } from "@objectstack/spec/ui";
+import { createLogger, bucketKeyToCalendarRange as bucketKeyToCalendarRange2, zonedDateStartToUtcMs } from "@objectstack/core";
+import { matchMissingColumnOfRelation } from "@objectstack/types";
 
 // src/cube-registry.ts
 var CubeRegistry = class {
@@ -120,6 +122,43 @@ var CubeRegistry = class {
 // src/strategies/filter-normalizer.ts
 import { isFilterAST, parseFilterAST, VALID_AST_OPERATORS } from "@objectstack/spec/data";
 import { StandardErrorCode } from "@objectstack/spec/api";
+
+// src/comparand-shape.ts
+function isBindableComparand(value) {
+  if (value === null || value === void 0) return true;
+  const kind = typeof value;
+  if (kind === "string" || kind === "number" || kind === "bigint" || kind === "boolean") return true;
+  return value instanceof Date || ArrayBuffer.isView(value);
+}
+function isRenderableTextComparand(value) {
+  if (value === null || value === void 0) return true;
+  const kind = typeof value;
+  if (kind === "string" || kind === "number" || kind === "bigint" || kind === "boolean") return true;
+  return value instanceof Date;
+}
+var TEXT_PATTERN_OPERATORS = /* @__PURE__ */ new Set([
+  "$contains",
+  "$notContains",
+  "$startsWith",
+  "$endsWith"
+]);
+function shapePreview(value) {
+  try {
+    const json = JSON.stringify(value);
+    if (typeof json !== "string") return typeof value;
+    return json.length > 80 ? `${json.slice(0, 77)}...` : json;
+  } catch {
+    return typeof value;
+  }
+}
+function unrenderableTextComparandMessage(op, field, value) {
+  return `"${op}" on "${field}" matches against the TEXT of a pattern, but its comparand is ${Array.isArray(value) ? "an array" : "an object"} (${shapePreview(value)}). filter.zod.ts declares it a string (StringOperatorSchema); a string, number, boolean, null or Date is accepted. Refusing rather than stringifying it: String({}) is "[object Object]", so the pattern that ran would be one nobody wrote \u2014 and a row storing that literal text matches it.`;
+}
+function unbindableListMemberMessage(op, field, value, index) {
+  return `"${op}" on "${field}" has a value at index ${index} of its list that cannot be bound as a SQL parameter: ${shapePreview(value)}. Every member of an $in/$nin/$between list is a comparand in its own right \u2014 use a string, number, boolean, null, Date or binary value. Refusing rather than binding it: the member can equal no stored value, so the list silently loses that entry (and a $nin loses the exclusion the caller wrote).`;
+}
+
+// src/strategies/filter-normalizer.ts
 function invalidFilterError(message) {
   const err = new Error(message);
   err.code = StandardErrorCode.enum.INVALID_FILTER;
@@ -138,7 +177,11 @@ var MONGO_TO_CUBE_OP = {
   $contains: "contains",
   $notContains: "notContains",
   $startsWith: "startsWith",
-  $endsWith: "endsWith"
+  $endsWith: "endsWith",
+  // [#6520] The case-INSENSITIVE twin, ASCII fold only. A separate cube operator
+  // rather than a flag on `contains`, because the two compile to different SQL
+  // and one name would make the renderers guess which was meant.
+  $icontains: "icontains"
 };
 function comparand(v) {
   return v === void 0 ? null : v;
@@ -161,7 +204,64 @@ function andOf(children) {
   if (children.length === 1) return children[0];
   return { kind: "and", children };
 }
+function assertCompilableComparand(opKey, field, value) {
+  if (TEXT_PATTERN_OPERATORS.has(opKey)) {
+    if (!isRenderableTextComparand(value)) {
+      throw invalidFilterError(`[analytics] ${unrenderableTextComparandMessage(opKey, field, value)}`);
+    }
+    return;
+  }
+  if ((opKey === "$in" || opKey === "$nin") && Array.isArray(value)) {
+    value.forEach((member, index) => {
+      if (!isBindableComparand(member)) {
+        throw invalidFilterError(`[analytics] ${unbindableListMemberMessage(opKey, field, member, index)}`);
+      }
+    });
+  }
+}
+function undefinedComparandError(field, path) {
+  return invalidFilterError(
+    `[analytics] comparand at ${path} is undefined \u2014 refusing to compile this filter. @objectstack/spec FieldOperatorsSchema declares no undefined comparand, and in JavaScript a key whose value is undefined cannot be told apart from an ABSENT key \u2014 yet the two mean OPPOSITE things (a predicate versus no constraint at all), so there is no reading of it that is not a guess. It used to compile, two ways: in a FIELD position the key was dropped outright, so a single-key where ran with no filter at all and the chart was drawn over every row (#3650's widening, which this module refuses everywhere else); in an OPERATOR or list position it became a comparison against null, which is UNKNOWN for every row and charts nothing. Write null if the null predicate was meant ({ "${field}": null } or { "${field}": { "$null": true } }), or omit the key entirely when the value is genuinely absent \u2014 an omitted key is the same "no constraint" without the ambiguity. The producer to fix is whoever BUILT this where: undefined cannot cross JSON, so it is in-process code spreading a possibly-absent value into a filter object (#6050 ruling B, pushed down to this door by #6386).`
+  );
+}
+function assertDefinedComparands(field, spec) {
+  const root = `"${field}"`;
+  if (spec === void 0) throw undefinedComparandError(field, root);
+  if (Array.isArray(spec)) {
+    spec.forEach((member, index) => {
+      if (member === void 0) throw undefinedComparandError(field, `${root}[${index}]`);
+    });
+    return;
+  }
+  if (!isFilterObject(spec)) return;
+  for (const [op, opValue] of Object.entries(spec)) {
+    if (!op.startsWith("$") || op === "$null" || op === "$exists") continue;
+    const opPath = `${root}.${op}`;
+    if (opValue === void 0) throw undefinedComparandError(field, opPath);
+    if (!Array.isArray(opValue)) continue;
+    opValue.forEach((member, index) => {
+      if (member === void 0) throw undefinedComparandError(field, `${opPath}[${index}]`);
+    });
+  }
+}
+function mixedFieldWrapperError(field, opKeys, nonOpKeys) {
+  const offending = nonOpKeys.map((k) => `"${k}"`).join(", ");
+  const rewrites = nonOpKeys.map((k) => `"${k}" \u2192 "$${k}"`).join(", ");
+  const example = nonOpKeys[0];
+  return invalidFilterError(
+    `[analytics] "${field}" mixes $-operator keys (${opKeys.join(", ")}) with non-$ sibling key(s) ${offending} in ONE field constraint \u2014 refusing to compile this filter. A $-prefixed key is an OPERATOR and a bare key is a NESTED-RELATION member; the two readings of ${offending} lead to different predicates and this module cannot tell which was meant, so any silent choice is a guess. If an operator missing its "$" was meant \u2014 the usual authoring slip \u2014 spell it with the prefix: ${rewrites}, as in { "${field}": { "$${example}": ... } }. If a nested-relation member was meant, give it a wrapper of its OWN with no $ siblings \u2014 { "${field}": { "${example}": ... } } compiles to the member "${field}.${example}" \u2014 and AND it with the operator constraint explicitly: { "$and": [{ "${field}": { "$op": ... } }, { "${field}": { "${example}": ... } }] }. This shape used to compile by silently DROPPING every non-$ sibling, and a dropped conjunct does not narrow the query, it WIDENS it: the chart included rows the author excluded, with nothing to read (#3650's failure mode, which this module refuses everywhere else). The sibling door in this package (read-scope-sql.ts) already fails closed on this exact shape \u2014 one shape, one answer (#6444).`
+  );
+}
+function assertUnmixedFieldWrapper(field, wrapper) {
+  const keys = Object.keys(wrapper);
+  const opKeys = keys.filter((k) => k.startsWith("$"));
+  if (opKeys.length === 0) return;
+  const nonOpKeys = keys.filter((k) => !k.startsWith("$"));
+  if (nonOpKeys.length === 0) return;
+  throw mixedFieldWrapperError(field, opKeys, nonOpKeys);
+}
 function fieldLeaves(key, raw) {
+  assertDefinedComparands(key, raw);
   const out = [];
   const leaf = (operator, values) => {
     out.push({ kind: "leaf", member: key, operator, values });
@@ -177,6 +277,7 @@ function fieldLeaves(key, raw) {
         `[analytics] "${key}" carries a field constraint with zero operators ({}). Refusing rather than reading it as "every row" or "no row" \u2014 #5240 ruled this shape refused on every backend.`
       );
     }
+    assertUnmixedFieldWrapper(key, wrapper);
     const opKeys = Object.keys(wrapper).filter((k) => k.startsWith("$"));
     if (opKeys.length > 0) {
       for (const opKey of opKeys) {
@@ -211,6 +312,7 @@ function fieldLeaves(key, raw) {
           );
         }
         const v = wrapper[opKey];
+        assertCompilableComparand(opKey, key, v);
         const values = Array.isArray(v) ? v.map(comparand) : [comparand(v)];
         if (nullValueSatisfiesOperator(opKey, v) && !operatorIsNullTotal(opKey, v)) {
           out.push({
@@ -240,7 +342,6 @@ function fieldLeaves(key, raw) {
 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)) {
         throw invalidFilterError(
@@ -456,6 +557,11 @@ function likePattern(shape, value) {
   const escaped = escapeLikePattern(value);
   return shape === "starts" ? `${escaped}%` : shape === "ends" ? `%${escaped}` : `%${escaped}%`;
 }
+var ASCII_UPPER_LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+var ASCII_LOWER_LETTERS = "abcdefghijklmnopqrstuvwxyz";
+function asciiLowerSqlExpr(expr) {
+  return `translate(${expr}, '${ASCII_UPPER_LETTERS}', '${ASCII_LOWER_LETTERS}')`;
+}
 
 // src/read-scope-sql.ts
 var IDENT = /^[a-z_][a-z0-9_]*$/i;
@@ -527,6 +633,8 @@ function compileNode(node, qAlias, params) {
 }
 function compileField(field, value, qAlias, params) {
   const col = `${qAlias}.${quoteIdent(field, "field")}`;
+  assertDefinedComparands2(field, value);
+  assertBooleanFlagComparands(field, value);
   if (value === null) return `${col} IS NULL`;
   if (typeof value !== "object" || value instanceof Date) {
     params.push(value);
@@ -556,6 +664,49 @@ function bindLike(params, pattern) {
 function nullSafeNegative(col, test) {
   return `(${col} IS NULL OR ${test})`;
 }
+function assertCompilableMembers(op, field, members) {
+  members.forEach((member, index) => {
+    if (!isBindableComparand(member)) {
+      throw readScopeCompileError(`[read-scope-sql] ${unbindableListMemberMessage(op, field, member, index)}`);
+    }
+  });
+}
+function assertRenderableText(op, field, val) {
+  if (isRenderableTextComparand(val)) return;
+  throw readScopeCompileError(`[read-scope-sql] ${unrenderableTextComparandMessage(op, field, val)}`);
+}
+function undefinedComparandError2(field, path) {
+  return readScopeCompileError(
+    `[read-scope-sql] comparand at ${path} is undefined \u2014 refusing to build read scope (fail-closed). @objectstack/spec FieldOperatorsSchema declares no undefined comparand, and in JavaScript a key whose value is undefined cannot be told apart from an ABSENT key \u2014 yet the two mean OPPOSITE things (a predicate versus no constraint at all), so there is no reading of it that is not a guess. It used to compile: undefined went into the bind list, the driver read it as SQL NULL, every comparison against NULL is UNKNOWN, and the scope matched ZERO rows in silence. Write null if the null predicate was meant ({ "${field}": null } or { "${field}": { "$null": true } }), or omit the key when the value is genuinely absent. The producer to fix is whoever BUILT this read scope \u2014 an admin-authored sharing rule / permission set, its CEL lowering, or the in-process code that assembled the FilterCondition \u2014 never the caller of this query, who cannot author it (#6050 ruling B, pushed down to this compiler by #6125).`
+  );
+}
+function assertDefinedComparands2(field, spec) {
+  const root = `"${field}"`;
+  if (spec === void 0) throw undefinedComparandError2(field, root);
+  if (!isFilterNode(spec)) return;
+  for (const [op, opValue] of Object.entries(spec)) {
+    if (!op.startsWith("$") || op === "$null" || op === "$exists") continue;
+    const opPath = `${root}.${op}`;
+    if (opValue === void 0) throw undefinedComparandError2(field, opPath);
+    if (!Array.isArray(opValue)) continue;
+    opValue.forEach((member, index) => {
+      if (member === void 0) throw undefinedComparandError2(field, `${opPath}[${index}]`);
+    });
+  }
+}
+function nonBooleanFlagComparandError(op, field, path) {
+  return readScopeCompileError(
+    `[read-scope-sql] comparand for "${op}" at ${path} is not a boolean \u2014 refusing to build read scope (fail-closed). @objectstack/spec FieldOperatorsSchema declares both $null and $exists as z.boolean(), and this compiler used to read the comparand by TRUTHINESS instead \u2014 so a non-boolean was silently sorted into one of the two declared answers rather than refused. The string "false" is TRUTHY, which is the case that matters: it landed on the side OPPOSITE the false it was written to mean, turning "rows with no ${field}" into "rows that have one" \u2014 a read scope that ADMITS the rows the policy excludes. Write the boolean itself (true or false), not a string, a number, null or undefined. The producer to fix is whoever BUILT this read scope \u2014 an admin-authored sharing rule / permission set, its CEL lowering, or the in-process code (a getReadScope option) that assembled the FilterCondition \u2014 never the caller of this query, who cannot author it (#5347 / #5369, pushed down to this compiler by #6387).`
+  );
+}
+function assertBooleanFlagComparands(field, spec) {
+  if (!isFilterNode(spec)) return;
+  for (const op of ["$null", "$exists"]) {
+    if (!Object.prototype.hasOwnProperty.call(spec, op)) continue;
+    if (typeof spec[op] === "boolean") continue;
+    throw nonBooleanFlagComparandError(op, field, `"${field}".${op}`);
+  }
+}
 function compileOperator(col, op, val, field, params) {
   switch (op) {
     case "$eq":
@@ -575,33 +726,70 @@ function compileOperator(col, op, val, field, params) {
     case "$in": {
       if (!Array.isArray(val)) throw readScopeCompileError(`[read-scope-sql] $in for "${field}" needs an array (fail-closed).`);
       if (val.length === 0) return FALSE_CLAUSE;
+      assertCompilableMembers(op, field, val);
       return `${col} IN (${val.map((v) => bind(params, v)).join(", ")})`;
     }
     case "$nin": {
       if (!Array.isArray(val)) throw readScopeCompileError(`[read-scope-sql] $nin for "${field}" needs an array (fail-closed).`);
       if (val.length === 0) return "1 = 1";
+      assertCompilableMembers(op, field, val);
       return nullSafeNegative(col, `${col} NOT IN (${val.map((v) => bind(params, v)).join(", ")})`);
     }
     case "$between": {
       if (!Array.isArray(val) || val.length !== 2) throw readScopeCompileError(`[read-scope-sql] $between for "${field}" needs [min,max] (fail-closed).`);
+      assertCompilableMembers(op, field, val);
       return `${col} BETWEEN ${bind(params, val[0])} AND ${bind(params, val[1])}`;
     }
     // [#5567] The comparand is a LITERAL, so it is escaped and the escape
     // character is bound with it. See {@link bindLike}.
+    // [#5234] …and it must be a value `String()` can render, which is asserted
+    // BEFORE `likePattern` sees it — see {@link assertRenderableText}.
     case "$contains":
+      assertRenderableText(op, field, val);
       return `${col} LIKE ${bindLike(params, likePattern("contains", val))}`;
+    /**
+     * [#6520] `$icontains` on the READ-SCOPE lowering — the one compiler in this
+     * package where a wrong answer is an ADR-0021 scope over-reach rather than a
+     * loose chart filter, which is why the fold is the spec's ruled one and not
+     * `LOWER()`.
+     *
+     * `assertRenderableText` first, exactly as its case-exact twin above: the
+     * comparand has to be something `String()` renders faithfully before a
+     * pattern is built from it (#5234).
+     *
+     * The fold wraps BOTH the column and the bound pattern. Folding one side
+     * only would compare a folded needle against a raw column — matching just
+     * the rows already lower-case — and on a read scope that is a row set the
+     * policy author never wrote, in the narrowing direction here but in the
+     * WIDENING direction under a `$not`.
+     */
+    case "$icontains": {
+      assertRenderableText(op, field, val);
+      const patternRef = asciiLowerSqlExpr(bind(params, likePattern("contains", val)));
+      return `${asciiLowerSqlExpr(col)} LIKE ${patternRef} ESCAPE ${bind(params, LIKE_ESCAPE_CHAR)}`;
+    }
     // [#5298] NULL-safe: `NOT LIKE` is UNKNOWN for a NULL column, and "does not
     // contain" is true of a value that is not there.
     case "$notContains":
+      assertRenderableText(op, field, val);
       return nullSafeNegative(col, `${col} NOT LIKE ${bindLike(params, likePattern("contains", val))}`);
     case "$startsWith":
+      assertRenderableText(op, field, val);
       return `${col} LIKE ${bindLike(params, likePattern("starts", val))}`;
     case "$endsWith":
+      assertRenderableText(op, field, val);
       return `${col} LIKE ${bindLike(params, likePattern("ends", val))}`;
+    // [#6387] `val` is a boolean here — {@link assertBooleanFlagComparands}
+    // refused anything else at {@link compileField}, before this emitter runs.
+    // So `=== true` is an exhaustive TWO-WAY choice over the declared domain,
+    // not the "anything truthy is IS NULL" rule it used to be. That old rule is
+    // what put the STRING `"false"` on the side opposite the `false` it was
+    // written to mean; the identity spelling cannot, and it is the spelling
+    // {@link nullValueSatisfiesOperator} now mirrors (#5146 / #5298).
     case "$null":
-      return val ? `${col} IS NULL` : `${col} IS NOT NULL`;
+      return val === true ? `${col} IS NULL` : `${col} IS NOT NULL`;
     case "$exists":
-      return val ? `${col} IS NOT NULL` : `${col} IS NULL`;
+      return val === true ? `${col} IS NOT NULL` : `${col} IS NULL`;
     default:
       throw readScopeCompileError(`[read-scope-sql] unsupported operator "${op}" on "${field}" (fail-closed).`);
   }
@@ -614,11 +802,22 @@ function nullValueSatisfiesOperator2(op, value) {
     // Mirror image: `$ne: null` compiles to `IS NOT NULL`, which a NULL fails.
     case "$ne":
       return value !== null;
-    // Truthiness, matching this file's emitter (see the note above).
+    // [#6387] Identity, matching this file's emitter (see the note above).
+    // `assertBooleanFlagComparands` refuses anything but `true` / `false` before
+    // this table is consulted, so each arm is an exhaustive TWO-WAY choice over
+    // the declared domain — and the strict spelling is chosen over the lenient
+    // one it replaces for the reason #5347 gave: `Boolean(value)` and
+    // `value === true` are equivalent only while the gate upstream holds, and
+    // the lenient spelling would quietly resume answering for shapes nobody
+    // ruled on if that gate were ever moved. A NULL column satisfies `$null`
+    // exactly when the author asked for null…
     case "$null":
-      return Boolean(value);
+      return value === true;
+    // …and satisfies `$exists` exactly when the author asked for "no value".
+    // `$null: true` and `$exists: false` are the same question, so these two
+    // arms are correctly each other's MIRROR, not each other's copy (#5369).
     case "$exists":
-      return !value;
+      return value === false;
     // Negative-polarity set / substring tests hold vacuously for an absent value.
     case "$nin":
       return true;
@@ -1124,13 +1323,19 @@ var NativeSQLStrategy = class {
       contains: "LIKE",
       notContains: "NOT LIKE",
       startsWith: "LIKE",
-      endsWith: "LIKE"
+      endsWith: "LIKE",
+      // [#6520] `$icontains` — `LIKE` like its neighbours; what separates it is
+      // the ASCII fold applied below, not the keyword.
+      icontains: "LIKE"
     };
     const likeShape = {
       contains: "contains",
       notContains: "contains",
       startsWith: "starts",
-      endsWith: "ends"
+      endsWith: "ends",
+      // [#6520] Same wildcard placement as `contains`; the case fold is what
+      // differs, and it is applied to both sides of the comparison below.
+      icontains: "contains"
     };
     if (operator === "set") return `${rawCol} IS NOT NULL`;
     if (operator === "notSet") return `${rawCol} IS NULL`;
@@ -1149,6 +1354,9 @@ var NativeSQLStrategy = class {
       params.push(likePattern(shape, values[0]));
       const patternRef = `$${params.length}`;
       params.push(LIKE_ESCAPE_CHAR);
+      if (operator === "icontains") {
+        return `${asciiLowerSqlExpr(rawCol)} ${sqlOp} ${asciiLowerSqlExpr(patternRef)} ESCAPE $${params.length}`;
+      }
       return `${rawCol} ${sqlOp} ${patternRef} ESCAPE $${params.length}`;
     }
     if (operator === "lte") {
@@ -1252,7 +1460,12 @@ var LIKE_SQL_OPS = {
   contains: { sql: "LIKE", shape: "contains" },
   notContains: { sql: "NOT LIKE", shape: "contains" },
   startsWith: { sql: "LIKE", shape: "starts" },
-  endsWith: { sql: "LIKE", shape: "ends" }
+  endsWith: { sql: "LIKE", shape: "ends" },
+  // [#6520] `$icontains`: the same escaped pattern and bound `ESCAPE` as its
+  // four case-EXACT neighbours, with `fold` adding the ASCII-only case fold to
+  // both sides of the comparison. The flag is on this row alone — the family
+  // above it is case-sensitive by ruling (#4706 Q2 = A).
+  icontains: { sql: "LIKE", shape: "contains", fold: true }
 };
 var ObjectQLStrategy = class {
   constructor() {
@@ -1693,7 +1906,9 @@ var ObjectQLStrategy = class {
       params.push(likePattern(like.shape, values[0]));
       const patternRef = `$${params.length}`;
       params.push(LIKE_ESCAPE_CHAR);
-      return `${col} ${like.sql} ${patternRef} ESCAPE $${params.length}`;
+      const lhs = like.fold ? asciiLowerSqlExpr(col) : col;
+      const rhs = like.fold ? asciiLowerSqlExpr(patternRef) : patternRef;
+      return `${lhs} ${like.sql} ${rhs} ESCAPE $${params.length}`;
     }
     const op = SCALAR_SQL_OPS[operator];
     if (!op) {
@@ -1979,6 +2194,14 @@ var ObjectQLStrategy = class {
    * string — `String(…)`, the same normalisation `like-pattern.ts` applies at the
    * two SQL emitters and `driver-sql`'s `applyLike` applies at the driver, so one
    * `$contains` means one thing on every face (#5567's invariant).
+   *
+   * [#5234] Those four `String(…)` calls now only ever see a value that renders
+   * faithfully: `fieldLeaves` refuses an object comparand on this family before a
+   * leaf exists. That ordering is load-bearing rather than incidental — this arm
+   * is a PRODUCER for the engine, so stringifying an object here would have
+   * laundered it into `'[object Object]'` and handed a driver a perfectly
+   * well-typed string. A strict driver downstream could never have seen the shape
+   * it was strict about, which is why the guard sits at the door and not here.
    */
   convertFilter(operator, values) {
     if (operator === "set") return { $ne: null };
@@ -2090,7 +2313,8 @@ var ObjectQLStrategy = class {
 
 // src/dataset-compiler.ts
 import { AggregationFunction } from "@objectstack/spec/data";
-var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set(["array_agg", "string_agg"]);
+import { resolveI18nLabel } from "@objectstack/spec/ui";
+var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set();
 var SUPPORTED_AGGREGATES = AggregationFunction.options.filter((a) => !UNSUPPORTED_AGGREGATES.has(a));
 function aggregateToMetricType(m) {
   if (!m.aggregate) {
@@ -2125,6 +2349,7 @@ function fieldRelationshipPath(field) {
 }
 var MAX_JOIN_HOPS = 3;
 var joinAlias = (path) => path.replace(/\./g, "__");
+var REGISTRY_LOCALE = void 0;
 function compileDataset(dataset, resolver, options) {
   const include = dataset.include ?? [];
   const declaredDatasource = (objectName) => {
@@ -2196,7 +2421,11 @@ function compileDataset(dataset, resolver, options) {
     assertDeclared(d.field, "dimension", d.name);
     const dim = {
       name: d.name,
-      label: typeof d.label === "string" ? d.label : d.name,
+      // [#6761] An inline locale map is a label, not a missing one. Before this,
+      // the `typeof === 'string'` test dropped the map and substituted the
+      // machine name, which `/analytics/meta` then published as a display title
+      // (`title: 'owner'` for a dimension labelled `{ en: 'Owner', … }`).
+      label: resolveI18nLabel(d.label, REGISTRY_LOCALE) ?? d.name,
       type: dimensionType(d),
       sql: d.field
     };
@@ -2216,7 +2445,8 @@ function compileDataset(dataset, resolver, options) {
     if (m.field) assertDeclared(m.field, "measure", m.name);
     const metric = {
       name: m.name,
-      label: typeof m.label === "string" ? m.label : m.name,
+      // [#6761] Same as the dimension label above — see {@link REGISTRY_LOCALE}.
+      label: resolveI18nLabel(m.label, REGISTRY_LOCALE) ?? m.name,
       type: aggregateToMetricType(m),
       // `count` with no field aggregates over rows (*).
       sql: m.field ?? "*"
@@ -2227,7 +2457,10 @@ function compileDataset(dataset, resolver, options) {
   }
   const cube = {
     name: dataset.name,
-    title: typeof dataset.label === "string" ? dataset.label : dataset.name,
+    // [#6761] The cube's own display title, same rule. `Cube.title` is optional
+    // in the schema, but an absent dataset label already produced the machine
+    // name here and that is not what this card changes — only the map case moves.
+    title: resolveI18nLabel(dataset.label, REGISTRY_LOCALE) ?? dataset.name,
     sql: dataset.object,
     measures,
     dimensions,
@@ -2245,7 +2478,7 @@ function compileDataset(dataset, resolver, options) {
 
 // src/dataset-executor.ts
 import { emptyGroupValueFor } from "@objectstack/spec/data";
-import { filterTokenContextFrom, resolveFilterTokens } from "@objectstack/core";
+import { bucketKeyToCalendarRange, filterTokenContextFrom, resolveFilterTokens } from "@objectstack/core";
 function resolveSelectionTokens(compiled, selection, context) {
   const tokenCtx = filterTokenContextFrom(context, /* @__PURE__ */ new Date());
   const resolve = (v) => resolveFilterTokens(v, tokenCtx);
@@ -2436,6 +2669,62 @@ function shiftRange(range, kind) {
   const prevStartMs = prevEndMs - (lengthDays - 1) * DAY_MS;
   return [toISODate(prevStartMs), toISODate(prevEndMs)];
 }
+function isoWeekKeyOfUtcMs(ms) {
+  const target = new Date(ms);
+  const dayNum = (target.getUTCDay() + 6) % 7;
+  target.setUTCDate(target.getUTCDate() - dayNum + 3);
+  const firstThursday = new Date(Date.UTC(target.getUTCFullYear(), 0, 4));
+  const weekNo = 1 + Math.round(
+    ((target.getTime() - firstThursday.getTime()) / DAY_MS - 3 + (firstThursday.getUTCDay() + 6) % 7) / 7
+  );
+  return `${target.getUTCFullYear()}-W${String(weekNo).padStart(2, "0")}`;
+}
+function bucketOrdinalOfDay(ymd, granularity) {
+  const ms = parseUTC(ymd);
+  const d = new Date(ms);
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth();
+  switch (granularity) {
+    case "year":
+      return y;
+    case "quarter":
+      return y * 4 + Math.floor(m / 3);
+    case "month":
+      return y * 12 + m;
+    // 1970-01-01 was a Thursday, so shifting by 3 days puts the Monday boundary
+    // on a multiple of 7 and the ordinal advances exactly at each ISO week start.
+    case "week":
+      return Math.floor((ms + 3 * DAY_MS) / (7 * DAY_MS));
+    case "day":
+    default:
+      return Math.floor(ms / DAY_MS);
+  }
+}
+function bucketKeyAtOrdinal(ordinal, granularity) {
+  switch (granularity) {
+    case "year":
+      return String(ordinal);
+    case "quarter":
+      return `${Math.floor(ordinal / 4)}-Q${ordinal % 4 + 1}`;
+    case "month":
+      return `${Math.floor(ordinal / 12)}-${String(ordinal % 12 + 1).padStart(2, "0")}`;
+    case "week":
+      return isoWeekKeyOfUtcMs(ordinal * 7 * DAY_MS - 3 * DAY_MS);
+    case "day":
+    default:
+      return toISODate(ordinal * DAY_MS);
+  }
+}
+function alignedCompareBucketKey(key, granularity, kind, currentRange, shiftedRange) {
+  if (typeof key !== "string" || key.length === 0) return null;
+  const span = bucketKeyToCalendarRange(key, granularity);
+  if (!span) return null;
+  const targetOrdinal = kind === "previousYear" ? bucketOrdinalOfDay(shiftYear(span.start, 1), granularity) : bucketOrdinalOfDay(span.start, granularity) + (bucketOrdinalOfDay(currentRange[0], granularity) - bucketOrdinalOfDay(shiftedRange[0], granularity));
+  const first = bucketOrdinalOfDay(currentRange[0], granularity);
+  const last = bucketOrdinalOfDay(currentRange[1], granularity);
+  if (targetOrdinal < first || targetOrdinal > last) return null;
+  return bucketKeyAtOrdinal(targetOrdinal, granularity);
+}
 var DatasetExecutor = class {
   /**
    * @param service - The analytics service the executor issues its queries to.
@@ -2622,6 +2911,24 @@ var DatasetExecutor = class {
   timeDimensionsOf(compiled, dimensions) {
     return dimensions.filter((d) => compiled.cube.dimensions[d]?.type === "time");
   }
+  /**
+   * The EFFECTIVE bucket size one dimension is grouped at for this selection,
+   * or `undefined` when it is not a date dimension or nothing states a size (in
+   * which case the runtime groups the raw column).
+   *
+   * One definition, two readers, deliberately: {@link buildQuery} uses it to
+   * decide the `GROUP BY`, and {@link runCompare} uses it to realign the
+   * comparison pass's bucket keys (#6007). Those two MUST agree — realigning
+   * `month` keys a query grouped by `quarter` would move every comparison value
+   * onto a bucket that does not exist — and the way to make them agree is to
+   * have one of them, not two that look alike.
+   */
+  granularityOf(compiled, selection, 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(selection, name, datasetDefault);
+  }
   buildQuery(compiled, opts) {
     const q = {
       cube: compiled.cube.name,
@@ -2635,12 +2942,7 @@ var DatasetExecutor = class {
     const selTimeDims = opts.selection.timeDimensions ?? [];
     const selDims = new Set(selTimeDims.map((t) => t.dimension));
     const groupedDims = new Set(opts.dimensions);
-    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 granularityFor = (name) => this.granularityOf(compiled, opts.selection, name);
     const bucketsUnstatedEntry = (dimension) => groupedDims.has(dimension) || opts.selection.dateGranularity != null;
     const resolvedTimeDims = selTimeDims.map((t) => {
       if (t.granularity) return t;
@@ -2675,9 +2977,14 @@ var DatasetExecutor = class {
       { ...selection, timeDimensions: shiftedTd },
       { measures, dimensions, baseFilter, context }
     );
+    const granularity = dimensions.includes(dimension) ? this.granularityOf(compiled, selection, dimension) : void 0;
     return sub.rows.map((row) => {
       const out = {};
       for (const dim of dimensions) out[dim] = row[dim];
+      if (granularity) {
+        const aligned = alignedCompareBucketKey(row[dimension], granularity, cmp.kind, range, shifted);
+        if (aligned != null) out[dimension] = aligned;
+      }
       for (const m of measures) out[`${m}__compare`] = row[m];
       return out;
     });
@@ -3054,8 +3361,12 @@ function hasDeclaredErrorEnvelope(err) {
   const e = err;
   return typeof e?.status === "number" && typeof e?.code === "string" && e.code.length > 0;
 }
+function isMissingColumnOfRelation(message) {
+  return matchMissingColumnOfRelation(message) !== void 0;
+}
 function isMissingSourceError(err) {
   const raw = String(err?.message ?? err ?? "");
+  if (isMissingColumnOfRelation(raw)) return false;
   const msg = raw.toLowerCase();
   return msg.includes("no such table") || // sqlite / libsql
   /relation\s+[`"']?[A-Za-z0-9_$.]+[`"']?\s+does not exist/i.test(raw) || // postgres
@@ -3065,6 +3376,7 @@ function isMissingSourceError(err) {
 }
 function missingSourceRelation(err) {
   const msg = String(err?.message ?? err ?? "");
+  if (isMissingColumnOfRelation(msg)) return void 0;
   const patterns = [
     /no such table:\s*[`"'[]?([A-Za-z0-9_$.]+)/i,
     // sqlite / libsql
@@ -3309,6 +3621,7 @@ var AnalyticsService = class {
         return previewResult;
       }
     }
+    const requestLocale = context?.locale;
     const provider = this.readScopeProvider;
     const resolveScope = provider ? (targetObject) => provider(targetObject, context) : void 0;
     const labelDeps = this.labelResolver ? withLabelFetchCache(this.labelResolver) : void 0;
@@ -3383,7 +3696,7 @@ var AnalyticsService = class {
       result.drillRanges = result.rows.map((row) => {
         const ranges = {};
         for (const { d, granularity, instant } of rangeDims) {
-          const cal = bucketKeyToCalendarRange(row[d.name], granularity);
+          const cal = bucketKeyToCalendarRange2(row[d.name], granularity);
           if (cal) {
             ranges[d.name] = { field: d.field, gte: bound(cal.start, instant), lt: bound(cal.end, instant) };
           }
@@ -3418,7 +3731,10 @@ var AnalyticsService = class {
       for (const f of result.fields) {
         const m = measureByName.get(f.name) ?? measureByName.get(f.name.replace(/__compare$/, ""));
         if (!m) continue;
-        if (f.label == null && typeof m.label === "string") f.label = m.label;
+        if (f.label == null) {
+          const label = resolveI18nLabel2(m.label, requestLocale);
+          if (label !== void 0) f.label = label;
+        }
         if (f.format == null && m.format) f.format = m.format;
         const fc = f;
         const mc = m;
@@ -3447,7 +3763,9 @@ var AnalyticsService = class {
       for (const f of result.fields) {
         if (f.label != null) continue;
         const d = dimByName.get(f.name) ?? dimByField.get(f.name);
-        if (d && typeof d.label === "string") f.label = d.label;
+        if (!d) continue;
+        const label = resolveI18nLabel2(d.label, requestLocale);
+        if (label !== void 0) f.label = label;
       }
     }
     return result;
@@ -3527,10 +3845,10 @@ var AnalyticsService = class {
       else this.logger.warn(message);
       return;
     }
-    const stripPrefix = (m) => m.includes(".") ? m.split(".").slice(1).join(".") : m;
     const extraMeasures = {};
     for (const m of query.measures || []) {
-      const key = stripPrefix(m);
+      if (cube.measures[m] || extraMeasures[m]) continue;
+      const key = mintableMeasureKey(m, name);
       if (cube.measures[key] || extraMeasures[key]) continue;
       extraMeasures[key] = inferMeasure(key);
     }
@@ -3579,6 +3897,13 @@ var AnalyticsService = class {
    *   the data path's `resolveQueryFields`: they are engine-assigned rather than
    *   declared, and a gate stricter than the engine it guards would reject
    *   queries that used to work.
+   *
+   * [#5918] Its `stripPrefix` below is deliberately NOT narrowed the way the two
+   * MINTS were. This is a RESOLVER — it mirrors `lookupMember`'s tiers to answer
+   * "which Metric will the strategy read", and that tier order did not change.
+   * What changed is what can reach it: a dotted measure is now either a
+   * `<cube>.` qualifier or a key the cube itself declares, because every other
+   * dotted spelling is refused at the mint before this gate runs.
    */
   assertMeasureFields(query, cube, declaredMeasures) {
     const probe = this.getObjectFieldNames;
@@ -3867,7 +4192,7 @@ var AnalyticsService = class {
     };
     measures.count = { name: "count", label: "Count", type: "count", sql: "*" };
     for (const m of query.measures || []) {
-      const key = m.includes(".") ? m.split(".").slice(1).join(".") : m;
+      const key = mintableMeasureKey(m, cubeName);
       if (measures[key]) continue;
       const inferred = inferMeasure(key);
       measures[key] = inferred;
@@ -3926,6 +4251,15 @@ var AnalyticsService = class {
     );
   }
 };
+function mintableMeasureKey(member, cubeName) {
+  const dot = member.indexOf(".");
+  if (dot < 0) return member;
+  if (member.slice(0, dot) === cubeName) return member.slice(dot + 1);
+  throw invalidMemberError(
+    `[Analytics] Measure '${member}' on cube '${cubeName}' is a DOTTED member, and measures do not traverse relationships \u2014 only dimensions do \u2014 so there is no related column for this to aggregate. Until #5918 the prefix was silently dropped, so the aggregate ran against '${cubeName}' itself while the result column kept the label '${member}'. Aggregate one of the object's OWN fields instead ('<field>_sum' / '_avg' / '_min' / '_max' / '_count_distinct'), or declare a Cube whose measure names the related column in its own 'sql'. The only dot a measure may carry is the '${cubeName}.' qualifier.`,
+    { member, param: "measures", cube: cubeName }
+  );
+}
 function inferMeasure(key) {
   if (key === "count") {
     return { name: "count", label: "Count", type: "count", sql: "*" };
@@ -4224,7 +4558,17 @@ var AnalyticsServicePlugin = class {
       // datasource the query was routed to. Undefined ⇒ the object rides the
       // default datasource (or the engine cannot answer), and the diagnostic
       // says so rather than inventing a name.
-      getObjectDatasource: (objectName) => dataEngine()?.getObject?.(objectName)?.datasource,
+      //
+      // [#5288] Asked of the ENGINE's resolver, not of the object's declaration.
+      // `getObject(name).datasource` is the declared value — step 1 of the five
+      // `getDriver` routes by — so an object placed by a `datasourceMapping`
+      // rule, by the ADR-0057 §3.6 lifecycle split, or by its package's
+      // `defaultDatasource` answered `'default'`, and the diagnostic named a
+      // database the rows are not in. Recomputing those rules here instead would
+      // be the second implementation `resolveMappedDatasource` (#4462) exists to
+      // prevent: it drifts by one step, silently, and the drift only surfaces as
+      // an error message pointing at the wrong database.
+      getObjectDatasource: (objectName) => dataEngine()?.resolveEffectiveDatasource?.(objectName),
       // ADR-0062 D6 — a federated object carries an `external` block (ADR-0015).
       // Reported so NativeSQLStrategy declines it (its hand-compiled FROM would
       // hit the wrong physical table) and the driver-correct ObjectQL path runs.