@objectstack/service-analytics 17.0.0-rc.5 → 17.0.0

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, getEnv, bucketKeyToCalendarRange as bucketKeyToCalendarRange2, zonedDateStartToUtcMs } from "@objectstack/core";
+import { matchMissingColumnOfRelation } from "@objectstack/types";
 
 // src/cube-registry.ts
 var CubeRegistry = class {
@@ -120,6 +122,84 @@ 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;
+}
+function isFieldReference(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return typeof value.$field === "string";
+}
+var CROSS_FIELD_COMPARISON_OPERATORS = /* @__PURE__ */ new Set([
+  "$eq",
+  "$ne",
+  "$gt",
+  "$gte",
+  "$lt",
+  "$lte"
+]);
+function findCrossFieldComparand(filter) {
+  return findIn(filter, "");
+}
+function findIn(node, field) {
+  if (!node || typeof node !== "object") return null;
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const hit = findIn(child, field);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (node instanceof Date || ArrayBuffer.isView(node)) return null;
+  for (const [key, value] of Object.entries(node)) {
+    if (CROSS_FIELD_COMPARISON_OPERATORS.has(key) && isFieldReference(value)) {
+      return { op: key, field, ref: value.$field };
+    }
+    const hit = findIn(value, key.startsWith("$") ? field : key);
+    if (hit) return hit;
+  }
+  return null;
+}
+var TEXT_PATTERN_OPERATORS = /* @__PURE__ */ new Set([
+  "$contains",
+  "$notContains",
+  "$startsWith",
+  "$endsWith",
+  "$icontains"
+]);
+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 fieldReferenceComparandMessage(op, field, ref, position) {
+  return `"${op}" on "${field}"${position ? ` (${position})` : ""} compares against the field reference { "$field": "${ref}" }, which this compiler does not lower into a column-to-column comparison. Refusing rather than binding it: the reference object used to become the BOUND VALUE of the comparison, so the emitted predicate compared "${field}" against the reference itself \u2014 a value no row can hold \u2014 and a read scope built from it answered the wrong row set with nothing to read. \u26A0\uFE0F This is NOT the platform declining the rule. @objectstack/spec declares this shape (FieldReferenceSchema), @objectstack/formula resolves it per record in memory, driver-sql / driver-sqlite-wasm compile it to a same-table column comparison for the six scalar operators since #5222, and since the 2026-08-12 ruling on #7598 the analytics native-SQL strategy DECLINES such a query so it routes to the ObjectQL engine path and runs there \u2014 the driver enforcing declared-only enumeration, the tenant-isolation ban and the comparison class with metadata it owns. What refuses here is this SQL lowering, whose only remaining caller is the /analytics/sql display echo; it has no faithful rendering of the predicate the engine path actually runs, and half-rendering one would describe a query that returns different rows. Run the query itself (/analytics/query) to get its rows (#7598).`;
+}
+function fieldReferenceBetweenBoundMessage(op, field, ref, index) {
+  return `"${op}" on "${field}" has the field reference { "$field": "${ref}" } at index ${index} of its [min, max] bounds. A range BOUND may not be a field reference on any backend: driver-sql and driver-sqlite-wasm refuse both endpoints (#5222), @objectstack/formula does not resolve a reference inside a list either \u2014 it orders the bounds against the raw reference object, which no value compares meaningfully to \u2014 and @objectstack/spec no longer declares the position at all (#7596 removed FieldReferenceSchema from the $between endpoint union, ADR-0049 declared = enforced). Refusing rather than lowering it: this compiler splits $between into its two bounds, so the reference would arrive at the driver under a "$gte" / "$lte" the author never wrote \u2014 a position the SQL drivers DO compile \u2014 and the range would quietly succeed here while the identical filter is refused everywhere else. Use a literal bound, or spell the comparison you meant as a scalar one ({ "${field}": { "$gte": { "$field": "${ref}" } } }), which IS served \u2014 on the ObjectQL engine path, where the driver enforces the #5222 rulings (#7598).`;
+}
+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 +218,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 +245,73 @@ 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 assertNoFieldReferenceComparand(opKey, field, value) {
+  if (opKey !== "$between" || !Array.isArray(value)) return;
+  value.forEach((member, index) => {
+    if (!isFieldReference(member)) return;
+    throw invalidFilterError(
+      `[analytics] ${fieldReferenceBetweenBoundMessage(opKey, field, member.$field, 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 +327,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) {
@@ -187,6 +338,7 @@ function fieldLeaves(key, raw) {
               `[analytics] "$between" on "${key}" needs a two-element [min, max] array, got ${JSON.stringify(v2)}. Dropping the predicate would silently widen the query to every row.`
             );
           }
+          assertNoFieldReferenceComparand(opKey, key, v2);
           leaf("gte", [comparand(v2[0])]);
           leaf("lte", [comparand(v2[1])]);
           continue;
@@ -211,6 +363,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 +393,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(
@@ -314,6 +466,7 @@ function nullValueSatisfiesOperator(op, value) {
   }
 }
 function operatorIsNullTotal(op, value) {
+  if (CROSS_FIELD_COMPARISON_OPERATORS.has(op) && isFieldReference(value)) return true;
   switch (op) {
     // Compile to `set` / `notSet` — `IS NULL` / `IS NOT NULL`, two-valued by
     // construction, on every strategy that compiles this tree.
@@ -456,6 +609,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 +685,9 @@ function compileNode(node, qAlias, params) {
 }
 function compileField(field, value, qAlias, params) {
   const col = `${qAlias}.${quoteIdent(field, "field")}`;
+  assertDefinedComparands2(field, value);
+  assertBooleanFlagComparands(field, value);
+  assertNoFieldReferenceComparand2(field, value);
   if (value === null) return `${col} IS NULL`;
   if (typeof value !== "object" || value instanceof Date) {
     params.push(value);
@@ -556,6 +717,66 @@ 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 assertNoFieldReferenceComparand2(field, spec) {
+  if (!isFilterNode(spec)) return;
+  for (const [op, opValue] of Object.entries(spec)) {
+    if (CROSS_FIELD_COMPARISON_OPERATORS.has(op) && isFieldReference(opValue)) {
+      throw readScopeCompileError(
+        `[read-scope-sql] ${fieldReferenceComparandMessage(op, field, opValue.$field)}`
+      );
+    }
+    if (op !== "$between" || !Array.isArray(opValue)) continue;
+    opValue.forEach((member, index) => {
+      if (!isFieldReference(member)) return;
+      throw readScopeCompileError(
+        `[read-scope-sql] ${fieldReferenceBetweenBoundMessage(op, field, member.$field, index)}`
+      );
+    });
+  }
+}
 function compileOperator(col, op, val, field, params) {
   switch (op) {
     case "$eq":
@@ -575,33 +796,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 +872,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;
@@ -739,9 +1008,82 @@ var NativeSQLStrategy = class {
         }
       }
     }
+    if (this.carriesCrossFieldComparison(query, ctx)) return false;
     const caps = ctx.queryCapabilities(query.cube);
     return caps.nativeSql && typeof ctx.executeRawSql === "function";
   }
+  /**
+   * [#7598] Does serving this query require the cross-field capability this
+   * strategy declines? See the ruling recorded at {@link canHandle}.
+   *
+   * ⚠️ This and {@link assertNoCrossFieldComparison} read the SAME inputs
+   * through the SAME detector, which is what makes the decline and the
+   * fail-closed backstop unable to drift: a shape one of them recognises is a
+   * shape the other recognises.
+   */
+  carriesCrossFieldComparison(query, ctx) {
+    return this.crossFieldComparisonIn(query, ctx) !== null;
+  }
+  crossFieldComparisonIn(query, ctx) {
+    let where = null;
+    try {
+      where = lowerAnalyticsWhere(query);
+    } catch {
+      return null;
+    }
+    const inWhere = findCrossFieldComparand(where);
+    if (inWhere) return { source: "the query's `where`", ...inWhere };
+    if (typeof ctx.getReadScope !== "function") return null;
+    const cube = query.cube ? ctx.getCube(query.cube) : void 0;
+    if (!cube) return null;
+    const objects = [this.extractObjectName(cube)];
+    for (const alias of Object.keys(cube.joins ?? {})) {
+      objects.push(cube.joins?.[alias]?.name ?? alias);
+    }
+    for (const objectName of objects) {
+      const scope = ctx.getReadScope(objectName);
+      if (scope === void 0 || scope === null) continue;
+      const inScope = findCrossFieldComparand(scope);
+      if (inScope) return { source: `the read scope of "${objectName}"`, ...inScope };
+    }
+    return null;
+  }
+  /**
+   * [#7598] The fail-closed backstop at the door that BINDS.
+   *
+   * ⚠️ **Unreachable by construction, and kept deliberately** — saying so
+   * because #7598's brief asks that a refusal arm which has become unreachable
+   * be named rather than left to be re-discovered. {@link canHandle} declines
+   * every query this would fire on, and it declines using
+   * {@link crossFieldComparisonIn} — the same walk over the same two inputs —
+   * so `resolveStrategy` cannot hand this strategy a query carrying one.
+   *
+   * It is kept because of what the failure mode is if that ever stops being
+   * true. The defect #7598 measured was not a missing error: it was a SILENT
+   * BIND — `toSqlBindValue` JSON-stringifies the reference object, so the
+   * statement compiled perfectly and compared a column against the text
+   * `{"$field":"budget"}`, a value no row can hold. A routing gate that misses
+   * a shape therefore degrades to a wrong ANSWER rather than to an error, and
+   * that is the one class this package refuses to leave to a single guard
+   * (Prime Directive #12 — refuse at the door, do not tolerate at the
+   * consumer). One line, no measurable cost, and it turns a routing regression
+   * into a loud refusal instead of an empty chart.
+   *
+   * Deliberately BARE — an undeclared 500, not `INVALID_FILTER` / 400 — for the
+   * reason `buildFilterClauseSql`'s #5333 exit in `objectql-strategy.ts` gives
+   * for the same class: the caller's filter is legal and is served on the
+   * engine path, so an arrival here is drift between our own routing gate and
+   * our own emitter. Billing the caller 400 for that would hide a platform bug
+   * from 5xx alerting and tell a dashboard user to fix a filter that is fine.
+   * Same tier as `resolveMeasureSql`'s unrecognised-`Metric.type` throw below.
+   */
+  assertNoCrossFieldComparison(query, ctx) {
+    const hit = this.crossFieldComparisonIn(query, ctx);
+    if (!hit) return;
+    throw new Error(
+      `[native-sql-strategy] ${hit.source} carries a field reference { "$field": "${hit.ref}" } under "${hit.op}" on "${hit.field}", which this strategy does not compile into a column-to-column comparison \u2014 it would BIND the reference object as the comparison's value and answer a wrong row set silently (#7598). \`canHandle\` declines such a query so it routes to the ObjectQL/engine path, whose driver compiles it and enforces the #5222 rulings with metadata it owns; reaching this throw means the decline and this emitter stopped agreeing, which is our bug and must never degrade to a silent answer.`
+    );
+  }
   async execute(query, ctx) {
     const { sql, params } = await this.generateSql(query, ctx);
     const cube = ctx.getCube(query.cube);
@@ -755,6 +1097,7 @@ var NativeSQLStrategy = class {
     if (!cube) {
       throw new Error(`Cube not found: ${query.cube}`);
     }
+    this.assertNoCrossFieldComparison(query, ctx);
     const params = [];
     const selectClauses = [];
     const groupByClauses = [];
@@ -1124,13 +1467,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 +1498,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") {
@@ -1182,6 +1534,7 @@ var NativeSQLStrategy = class {
 };
 
 // src/strategies/objectql-strategy.ts
+import { markFilterSubtreeProvenance } from "@objectstack/spec/data";
 import { nextUtcCalendarDay as nextUtcCalendarDay2 } from "@objectstack/core";
 
 // src/strategies/cross-object-rebucket.ts
@@ -1252,7 +1605,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() {
@@ -1363,6 +1721,12 @@ var ObjectQLStrategy = class {
     if (!cube) {
       throw new Error(`Cube not found: ${query.cube}`);
     }
+    const crossField = findCrossFieldComparand(this.loweredWhere(query));
+    if (crossField) {
+      throw invalidFilterError(
+        `[analytics] cannot render display SQL for the field reference { "$field": "${crossField.ref}" } under "${crossField.op}" on "${crossField.field}". The query itself is SERVED \u2014 \`NativeSQLStrategy.canHandle\` declines a cross-field comparison so it routes to the ObjectQL engine path, where driver-sql compiles it into a column-to-column predicate written TOTAL across NULLs and enforces the #5222 rulings (#7598, maintainer ruling 2026-08-12). This renderer has no faithful rendering of that predicate: what it can emit is a comparison against the reference object as a bound VALUE, which reproduces none of the rows the query returns. Refusing rather than half-rendering \u2014 an echo that contradicts execution is worse than no echo (#3601 / #3602 / #3650). Run the query itself (/analytics/query) to get its rows.`
+      );
+    }
     const selectParts = [];
     const groupByParts = [];
     const params = [];
@@ -1467,11 +1831,11 @@ var ObjectQLStrategy = class {
    * predicate. `$and` makes that structurally impossible.
    */
   withReadScope(objectName, filter, ctx) {
-    const userFilter = Object.keys(filter).length > 0 ? filter : void 0;
+    const userFilter = Object.keys(filter).length > 0 ? markFilterSubtreeProvenance(filter, "author") : 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;
+    const scopeFilter = markFilterSubtreeProvenance(scope, "policy");
     if (!userFilter) return scopeFilter;
     return { $and: [userFilter, scopeFilter] };
   }
@@ -1645,6 +2009,7 @@ var ObjectQLStrategy = class {
     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;
+    if (scope != null) markFilterSubtreeProvenance(scope, "policy");
     const filter = scope != null ? { $and: [idFilter, scope] } : idFilter;
     const rows = await ctx.executeAggregate(refObject, {
       groupBy: ["id", attr],
@@ -1693,7 +2058,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 +2346,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 };
@@ -1987,8 +2362,27 @@ var ObjectQLStrategy = class {
     const v0 = values[0];
     const all = [...values];
     switch (operator) {
+      // [#7598] IMPLICIT equality for a literal, EXPLICIT `$eq` for a field
+      // reference — the branch is on the COMPARAND, not on the operator, which
+      // is the same fix and the same reasoning #7597 applied to
+      // `parseFilterAST`, the spec's own lowering sink.
+      //
+      // `{ amount: 5 }` is implicit equality and every backend reads it that
+      // way. `{ amount: { $field: 'budget' } }` is NOT: it is a field-spec
+      // object whose only key is `$field`, which no backend reads as an
+      // equality — `driver-sql` sees an unrecognised operator key and the
+      // memory evaluator sees a comparand it never resolves. So the bare return
+      // was correct for four years' worth of literals and silently wrong for
+      // the one comparand the 2026-08-12 ruling routes HERE on purpose: with it,
+      // `{ amount: { $eq: { $field: 'budget' } } }` — the shape
+      // `compileCelToFilter` emits for a field-to-field CEL rule, and the shape
+      // `canHandle` now declines native SQL for — would arrive at the driver as
+      // something the driver cannot read, so the capability B exists to serve
+      // would fail on its single most important spelling. Its five siblings
+      // (`$ne`/`$gt`/`$gte`/`$lt`/`$lte`) were never affected: they emit their
+      // operator explicitly two lines down.
       case "equals":
-        return v0;
+        return isFieldReference(v0) ? { $eq: v0 } : v0;
       case "notEquals":
         return { $ne: v0 };
       case "gt":
@@ -2048,6 +2442,24 @@ var ObjectQLStrategy = class {
   extractObjectName(cube) {
     return cube.sql.trim();
   }
+  /**
+   * [#7598] The query's `where`, lowered — the same input
+   * `NativeSQLStrategy.canHandle` scans, so the strategy that DECLINED and the
+   * echo that refuses read one shape rather than two.
+   *
+   * A throw from the lowering is swallowed for the same reason it is there: the
+   * `where` is malformed either way and `normalizeAnalyticsFilterTree` below
+   * refuses it with the message and envelope it has always had. This helper's
+   * only job is finding a reference, and there is none to find in a filter that
+   * does not lower.
+   */
+  loweredWhere(query) {
+    try {
+      return lowerAnalyticsWhere(query);
+    } catch {
+      return null;
+    }
+  }
   /**
    * The dimensions this query PROJECTS, in the order the result carries them:
    * every `dimensions` entry, then every granular `timeDimensions` entry that
@@ -2090,7 +2502,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 +2538,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 +2610,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 +2634,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 +2646,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 +2667,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 +2858,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 +3100,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 +3131,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 +3166,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 +3550,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 +3565,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
@@ -3140,6 +3641,7 @@ var AnalyticsService = class {
     this.getObjectFieldNames = config.getObjectFieldNames;
     this.getObjectDatasource = config.getObjectDatasource;
     this.isExternalObject = config.isExternalObject;
+    this.debugSql = config.debugSql ?? getEnv("NODE_ENV") === "development";
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -3257,7 +3759,7 @@ var AnalyticsService = class {
       const strategy = this.resolveStrategy(query, ctx, skip);
       this.logger.debug(`[Analytics] Query on cube "${query.cube}" \u2192 ${strategy.name}`);
       try {
-        return await strategy.execute(query, ctx);
+        return this.applySqlEchoPolicy(await strategy.execute(query, ctx));
       } catch (e) {
         if (e?.code === "RAW_SQL_UNSUPPORTED") {
           this.logger.warn(
@@ -3270,6 +3772,30 @@ var AnalyticsService = class {
       }
     }
   }
+  /**
+   * [#8286] Withhold the executed statement unless this host enabled the echo.
+   *
+   * Applied at {@link query}, which is the response-assembly seam for BOTH
+   * faces that serve callers: `/api/v1/analytics/query` calls it directly, and
+   * `queryDataset` reaches it through `DatasetExecutor`, so a dataset response
+   * inherits the same verdict without a second gate to keep in step.
+   * `generateSql` — the dedicated `/api/v1/analytics/sql` dry-run route — is
+   * deliberately NOT gated: asking for the statement is that route's entire
+   * purpose, and it is the surface a debugging author is meant to use.
+   *
+   * What the echo disclosed, and why "it is only a table name" understates it:
+   * the statement carries the compiled read scope, i.e. the SHAPE of the
+   * isolation predicate (`"sys_user"."id" IN ($2, $3, …)` rather than an
+   * `organization_id` comparison) plus its bound-parameter arity, which counts
+   * the caller's own org membership. No wall was breached by it — the echo is
+   * information disclosure, and this is the disclosure closing.
+   */
+  applySqlEchoPolicy(result) {
+    if (this.debugSql || result?.sql === void 0) return result;
+    const withheld = { ...result };
+    delete withheld.sql;
+    return withheld;
+  }
   /**
    * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
    * can be queried by name. Idempotent (re-registering overwrites). Returns the
@@ -3309,6 +3835,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 +3910,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 +3945,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 +3977,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 +4059,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 +4111,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 +4406,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;
@@ -3921,11 +4460,28 @@ var AnalyticsService = class {
         return strategy;
       }
     }
+    const crossField = findCrossFieldComparand(lowerAnalyticsWhereQuietly(query));
     throw new Error(
-      `[Analytics] No strategy can handle query for cube "${query.cube}". Checked: ${this.strategies.map((s) => s.name).join(", ")}${skip?.size ? ` (skipped at runtime: ${[...skip].map((s) => s.name).join(", ")})` : ""}. Ensure a compatible driver is configured or a fallback service is registered.`
+      `[Analytics] No strategy can handle query for cube "${query.cube}". Checked: ${this.strategies.map((s) => s.name).join(", ")}${skip?.size ? ` (skipped at runtime: ${[...skip].map((s) => s.name).join(", ")})` : ""}. ` + (crossField ? `This query's filter compares against the field reference { "$field": "${crossField.ref}" } under "${crossField.op}" on "${crossField.field}", and NativeSQLStrategy DECLINES a cross-field comparison so that it routes to the ObjectQL engine path \u2014 whose driver compiles it and enforces the #5222 rulings with metadata it owns (#7598). No such path is configured here, so the capability is unavailable on this deployment: supply an \`executeAggregate\` bridge (the plugin auto-wires one from the engine), or compare against a literal value. Every other query on this cube is unaffected. ` : "") + "Ensure a compatible driver is configured or a fallback service is registered."
     );
   }
 };
+function lowerAnalyticsWhereQuietly(query) {
+  try {
+    return lowerAnalyticsWhere(query);
+  } catch {
+    return null;
+  }
+}
+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: "*" };
@@ -4212,6 +4768,11 @@ var AnalyticsServicePlugin = class {
       coerceTemporalFilterColumn,
       relationshipResolver,
       labelResolver,
+      // [#8286] Passed through as authored — `undefined` is "this host did not
+      // choose", which the service resolves to development-only. Defaulting it
+      // here would be a second copy of that decision, drifting the moment one
+      // of the two moves.
+      debugSql: this.options.debugSql,
       // Source-field metadata behind the display chains on result columns:
       // ADR-0053 currency (`currencyConfig.defaultCurrency`) and percent scale
       // (`max`, which is what marks whole-percent storage — objectui#3136).
@@ -4224,7 +4785,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.