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

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/analytics-service.ts
 import { percentScaleOf } from "@objectstack/spec/data";
 import { resolveI18nLabel as resolveI18nLabel2 } from "@objectstack/spec/ui";
-import { createLogger, bucketKeyToCalendarRange as bucketKeyToCalendarRange2, zonedDateStartToUtcMs } from "@objectstack/core";
+import { createLogger, getEnv, bucketKeyToCalendarRange as bucketKeyToCalendarRange2, zonedDateStartToUtcMs } from "@objectstack/core";
 import { matchMissingColumnOfRelation } from "@objectstack/types";
 
 // src/cube-registry.ts
@@ -136,11 +136,46 @@ function isRenderableTextComparand(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"
+  "$endsWith",
+  "$icontains"
 ]);
 function shapePreview(value) {
   try {
@@ -154,6 +189,12 @@ function shapePreview(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).`;
 }
@@ -219,6 +260,15 @@ function assertCompilableComparand(opKey, field, value) {
     });
   }
 }
+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).`
@@ -288,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;
@@ -415,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.
@@ -635,6 +687,7 @@ 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);
@@ -707,6 +760,23 @@ function assertBooleanFlagComparands(field, spec) {
     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":
@@ -938,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);
@@ -954,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 = [];
@@ -1390,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
@@ -1576,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 = [];
@@ -1680,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] };
   }
@@ -1858,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],
@@ -2210,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":
@@ -2271,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
@@ -3452,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 {
@@ -3569,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(
@@ -3582,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
@@ -4246,11 +4460,19 @@ 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;
@@ -4546,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).