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

package/dist/index.d.cts

@@ -105,23 +105,32 @@ type RelationshipResolver = (baseObject: string, relationshipName: string) => st
  */
 interface DatasetCompileOptions {
     /**
-     * [#5115] The datasource `objectName` DECLARES (`object.datasource`), or
-     * `undefined` when nothing authoritative can answer (no data engine, unknown
-     * object).
+     * [#5115] The datasource `objectName` is BOUND to, or `undefined` when nothing
+     * authoritative can answer (no data engine, unknown object) — or when nothing
+     * binds the object at all and it rides the deployment's default datasource.
      *
      * With it the compiler can settle at COMPILE time what #5033 could only
      * report at QUERY time: a dataset whose join crosses datasources declares a
      * statement no driver can execute, because the analytics engine lowers the
      * whole dataset into ONE SQL statement on the base object's datasource.
      *
-     * IMPORTANT — `'default'` is not an answer. In `ObjectQL.getDriver`'s
-     * resolution order an explicit `object.datasource` other than `'default'`
-     * wins outright (step 1); `'default'` is the schema's DEFAULT value and means
-     * only "no explicit binding", after which routing is decided by
-     * `datasourceMapping` rules, the ADR-0057 §3.6 lifecycle split, and the
-     * owning package's `defaultDatasource` — none of which are visible from here.
-     * The compiler therefore treats `'default'`/`undefined` as UNANSWERED. See
-     * {@link compileDataset}.
+     * [#5288] What the host supplies here changed shape, the rule below did not.
+     * It used to be the object's DECLARED `datasource` — step 1 of the five
+     * `ObjectQL.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 was read here as
+     * unanswered. The built-in host (`plugin.ts`) now asks the engine's own
+     * resolver instead, so those three placements ARE visible from here and a join
+     * between two objects bound to two different datasources is decidable
+     * whichever mechanism bound them.
+     *
+     * Still deliberately UNANSWERED: `'default'`, and the object that no rule
+     * places anywhere. The deployment's default driver keeps its natural name
+     * (#3826), so "rides the default" is reported as `undefined` rather than as a
+     * name — which means a join from a bound object to a default-riding one stays
+     * undecidable here and remains the query-time diagnostic's business (#5288
+     * records this boundary; widening it is #5115's follow-up, not this rule's).
+     * See {@link compileDataset}.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -407,6 +416,15 @@ interface AnalyticsServiceConfig {
      * datasources before any query is ever built. Absence keeps the pre-#5115
      * behaviour exactly ("cannot answer, do not block") — the query-time
      * diagnostic above stays as the backstop.
+     *
+     * [#5288] "Bound to" above is the whole contract, and it took until #5288 for
+     * the built-in host to honour it: `plugin.ts` answered with the object's
+     * DECLARED `datasource` — step 1 of the five `ObjectQL.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` reported
+     * `'default'` and sent the message above to the wrong database. It now asks
+     * `ObjectQL.resolveEffectiveDatasource`. A custom host owes the same answer:
+     * the datasource an object is BOUND to, `undefined` when nothing binds it.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -504,6 +522,42 @@ interface AnalyticsServiceConfig {
      * across the publish boundary. Reads only; never touches physical tables.
      */
     draftRowsResolver?: (objectName: string, context?: ExecutionContext) => Promise<Record<string, unknown>[] | null>;
+    /**
+     * [#8286] Echo the executed statement back to the CALLER in
+     * `AnalyticsResult.sql`. **Off unless this host opts in.**
+     *
+     * The contract has always declared the echo debug-only —
+     * `AnalyticsResultResponseSchema.data.sql` (`spec/api/analytics.zod.ts`) is
+     * `optional()` and describes itself as "Executed SQL (if debug enabled)" —
+     * but no implementation ever read a debug switch, so every `/analytics/query`
+     * response carried the statement, on production deployments included. This
+     * field is that switch: declared = enforced, restored at the one seam the
+     * response leaves through ({@link AnalyticsService.query}).
+     *
+     * **Default** — `NODE_ENV === 'development'`, and nothing else. In
+     * particular an UNSET `NODE_ENV` counts as production and the echo stays
+     * off: that is the maintainer's 2026-08-06 ruling for machine-readable
+     * environment answers (see `resolveDiscoveryEnvironment` and the note at
+     * `runtime/src/http-dispatcher.ts`), and of the two ways to be wrong,
+     * disclosing on a production deployment whose operator forgot the variable
+     * is the dangerous one. `os start` forces `NODE_ENV='production'` when
+     * unset, `os serve` resolves `NODE_ENV || 'production'`, `os doctor` derives
+     * the same expression — this switch now reads the absence the same way.
+     *
+     * **Why not a request field.** There is none, deliberately: a caller-set
+     * debug flag would let any tenant re-open the disclosure on demand, which is
+     * the shape of the defect rather than a fix for it. The echo is a HOST
+     * decision, and the caller-facing surface for "show me the SQL" already
+     * exists as the dedicated dry-run route `/api/v1/analytics/sql`
+     * (`generateSql`), which this switch does not touch.
+     *
+     * **Why not the plugin's `debug` (log) option.** Server-side log verbosity
+     * and what travels to a caller are different decisions with different blast
+     * radii; folding them together means a support engineer raising log level on
+     * a live deployment silently reopens the disclosure. Two switches, named for
+     * what they open.
+     */
+    debugSql?: boolean;
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -551,6 +605,11 @@ declare class AnalyticsService implements IAnalyticsService {
     private readonly isExternalObject?;
     /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
     private warnedNoObjectRegistry;
+    /**
+     * [#8286] Does the executed statement travel back to the caller?
+     * See {@link AnalyticsServiceConfig.debugSql} for the switch and its default.
+     */
+    private readonly debugSql;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -586,6 +645,25 @@ declare class AnalyticsService implements IAnalyticsService {
      * Any other error propagates untouched.
      */
     query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
+    /**
+     * [#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.
+     */
+    private applySqlEchoPolicy;
     /**
      * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
      * can be queried by name. Idempotent (re-registering overwrites). Returns the
@@ -665,6 +743,13 @@ declare class AnalyticsService implements IAnalyticsService {
      *   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.
      */
     private assertMeasureFields;
     /**
@@ -868,6 +953,17 @@ interface AnalyticsServicePluginOptions {
     getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
     /** Enable debug logging. */
     debug?: boolean;
+    /**
+     * [#8286] Echo the executed statement back to CALLERS in
+     * `AnalyticsResult.sql` (`/api/v1/analytics/query`).
+     *
+     * Distinct from {@link AnalyticsServicePluginOptions.debug} above, which is
+     * server-side log verbosity only: raising log level must never widen what
+     * travels to a tenant. Default and rationale live with the service config —
+     * see `AnalyticsServiceConfig.debugSql`. Undefined here means "no host
+     * choice", which the service resolves to development-only.
+     */
+    debugSql?: boolean;
 }
 /**
  * AnalyticsServicePlugin — Kernel plugin for multi-driver analytics.
@@ -1041,6 +1137,19 @@ declare class DatasetExecutor {
      * ISO strings chronologically, and bucket keys are minted sort-stable.)
      */
     private timeDimensionsOf;
+    /**
+     * 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.
+     */
+    private granularityOf;
     private buildQuery;
     private runCompare;
 }
@@ -1077,6 +1186,47 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#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.
+     */
+    private carriesCrossFieldComparison;
+    private crossFieldComparisonIn;
+    /**
+     * [#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.
+     */
+    private assertNoCrossFieldComparison;
     execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult>;
     generateSql(query: AnalyticsQuery, ctx: StrategyContext): Promise<{
         sql: string;
@@ -1464,9 +1614,29 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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.
      */
     private convertFilter;
     private extractObjectName;
+    /**
+     * [#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.
+     */
+    private loweredWhere;
     /**
      * The dimensions this query PROJECTS, in the order the result carries them:
      * every `dimensions` entry, then every granular `timeDimensions` entry that

package/dist/index.d.ts

@@ -105,23 +105,32 @@ type RelationshipResolver = (baseObject: string, relationshipName: string) => st
  */
 interface DatasetCompileOptions {
     /**
-     * [#5115] The datasource `objectName` DECLARES (`object.datasource`), or
-     * `undefined` when nothing authoritative can answer (no data engine, unknown
-     * object).
+     * [#5115] The datasource `objectName` is BOUND to, or `undefined` when nothing
+     * authoritative can answer (no data engine, unknown object) — or when nothing
+     * binds the object at all and it rides the deployment's default datasource.
      *
      * With it the compiler can settle at COMPILE time what #5033 could only
      * report at QUERY time: a dataset whose join crosses datasources declares a
      * statement no driver can execute, because the analytics engine lowers the
      * whole dataset into ONE SQL statement on the base object's datasource.
      *
-     * IMPORTANT — `'default'` is not an answer. In `ObjectQL.getDriver`'s
-     * resolution order an explicit `object.datasource` other than `'default'`
-     * wins outright (step 1); `'default'` is the schema's DEFAULT value and means
-     * only "no explicit binding", after which routing is decided by
-     * `datasourceMapping` rules, the ADR-0057 §3.6 lifecycle split, and the
-     * owning package's `defaultDatasource` — none of which are visible from here.
-     * The compiler therefore treats `'default'`/`undefined` as UNANSWERED. See
-     * {@link compileDataset}.
+     * [#5288] What the host supplies here changed shape, the rule below did not.
+     * It used to be the object's DECLARED `datasource` — step 1 of the five
+     * `ObjectQL.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 was read here as
+     * unanswered. The built-in host (`plugin.ts`) now asks the engine's own
+     * resolver instead, so those three placements ARE visible from here and a join
+     * between two objects bound to two different datasources is decidable
+     * whichever mechanism bound them.
+     *
+     * Still deliberately UNANSWERED: `'default'`, and the object that no rule
+     * places anywhere. The deployment's default driver keeps its natural name
+     * (#3826), so "rides the default" is reported as `undefined` rather than as a
+     * name — which means a join from a bound object to a default-riding one stays
+     * undecidable here and remains the query-time diagnostic's business (#5288
+     * records this boundary; widening it is #5115's follow-up, not this rule's).
+     * See {@link compileDataset}.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -407,6 +416,15 @@ interface AnalyticsServiceConfig {
      * datasources before any query is ever built. Absence keeps the pre-#5115
      * behaviour exactly ("cannot answer, do not block") — the query-time
      * diagnostic above stays as the backstop.
+     *
+     * [#5288] "Bound to" above is the whole contract, and it took until #5288 for
+     * the built-in host to honour it: `plugin.ts` answered with the object's
+     * DECLARED `datasource` — step 1 of the five `ObjectQL.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` reported
+     * `'default'` and sent the message above to the wrong database. It now asks
+     * `ObjectQL.resolveEffectiveDatasource`. A custom host owes the same answer:
+     * the datasource an object is BOUND to, `undefined` when nothing binds it.
      */
     getObjectDatasource?: (objectName: string) => string | undefined;
     /**
@@ -504,6 +522,42 @@ interface AnalyticsServiceConfig {
      * across the publish boundary. Reads only; never touches physical tables.
      */
     draftRowsResolver?: (objectName: string, context?: ExecutionContext) => Promise<Record<string, unknown>[] | null>;
+    /**
+     * [#8286] Echo the executed statement back to the CALLER in
+     * `AnalyticsResult.sql`. **Off unless this host opts in.**
+     *
+     * The contract has always declared the echo debug-only —
+     * `AnalyticsResultResponseSchema.data.sql` (`spec/api/analytics.zod.ts`) is
+     * `optional()` and describes itself as "Executed SQL (if debug enabled)" —
+     * but no implementation ever read a debug switch, so every `/analytics/query`
+     * response carried the statement, on production deployments included. This
+     * field is that switch: declared = enforced, restored at the one seam the
+     * response leaves through ({@link AnalyticsService.query}).
+     *
+     * **Default** — `NODE_ENV === 'development'`, and nothing else. In
+     * particular an UNSET `NODE_ENV` counts as production and the echo stays
+     * off: that is the maintainer's 2026-08-06 ruling for machine-readable
+     * environment answers (see `resolveDiscoveryEnvironment` and the note at
+     * `runtime/src/http-dispatcher.ts`), and of the two ways to be wrong,
+     * disclosing on a production deployment whose operator forgot the variable
+     * is the dangerous one. `os start` forces `NODE_ENV='production'` when
+     * unset, `os serve` resolves `NODE_ENV || 'production'`, `os doctor` derives
+     * the same expression — this switch now reads the absence the same way.
+     *
+     * **Why not a request field.** There is none, deliberately: a caller-set
+     * debug flag would let any tenant re-open the disclosure on demand, which is
+     * the shape of the defect rather than a fix for it. The echo is a HOST
+     * decision, and the caller-facing surface for "show me the SQL" already
+     * exists as the dedicated dry-run route `/api/v1/analytics/sql`
+     * (`generateSql`), which this switch does not touch.
+     *
+     * **Why not the plugin's `debug` (log) option.** Server-side log verbosity
+     * and what travels to a caller are different decisions with different blast
+     * radii; folding them together means a support engineer raising log level on
+     * a live deployment silently reopens the disclosure. Two switches, named for
+     * what they open.
+     */
+    debugSql?: boolean;
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -551,6 +605,11 @@ declare class AnalyticsService implements IAnalyticsService {
     private readonly isExternalObject?;
     /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
     private warnedNoObjectRegistry;
+    /**
+     * [#8286] Does the executed statement travel back to the caller?
+     * See {@link AnalyticsServiceConfig.debugSql} for the switch and its default.
+     */
+    private readonly debugSql;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -586,6 +645,25 @@ declare class AnalyticsService implements IAnalyticsService {
      * Any other error propagates untouched.
      */
     query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
+    /**
+     * [#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.
+     */
+    private applySqlEchoPolicy;
     /**
      * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
      * can be queried by name. Idempotent (re-registering overwrites). Returns the
@@ -665,6 +743,13 @@ declare class AnalyticsService implements IAnalyticsService {
      *   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.
      */
     private assertMeasureFields;
     /**
@@ -868,6 +953,17 @@ interface AnalyticsServicePluginOptions {
     getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
     /** Enable debug logging. */
     debug?: boolean;
+    /**
+     * [#8286] Echo the executed statement back to CALLERS in
+     * `AnalyticsResult.sql` (`/api/v1/analytics/query`).
+     *
+     * Distinct from {@link AnalyticsServicePluginOptions.debug} above, which is
+     * server-side log verbosity only: raising log level must never widen what
+     * travels to a tenant. Default and rationale live with the service config —
+     * see `AnalyticsServiceConfig.debugSql`. Undefined here means "no host
+     * choice", which the service resolves to development-only.
+     */
+    debugSql?: boolean;
 }
 /**
  * AnalyticsServicePlugin — Kernel plugin for multi-driver analytics.
@@ -1041,6 +1137,19 @@ declare class DatasetExecutor {
      * ISO strings chronologically, and bucket keys are minted sort-stable.)
      */
     private timeDimensionsOf;
+    /**
+     * 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.
+     */
+    private granularityOf;
     private buildQuery;
     private runCompare;
 }
@@ -1077,6 +1186,47 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#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.
+     */
+    private carriesCrossFieldComparison;
+    private crossFieldComparisonIn;
+    /**
+     * [#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.
+     */
+    private assertNoCrossFieldComparison;
     execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult>;
     generateSql(query: AnalyticsQuery, ctx: StrategyContext): Promise<{
         sql: string;
@@ -1464,9 +1614,29 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * 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.
      */
     private convertFilter;
     private extractObjectName;
+    /**
+     * [#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.
+     */
+    private loweredWhere;
     /**
      * The dimensions this query PROJECTS, in the order the result carries them:
      * every `dimensions` entry, then every granular `timeDimensions` entry that