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

package/dist/index.d.cts

@@ -522,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.
@@ -569,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);
@@ -604,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
@@ -893,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.
@@ -1115,6 +1186,74 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#8690] Does the query's `where` compare a declared TIME dimension against
+     * a value no temporal storage rule can read? See the ruling at
+     * {@link canHandle}.
+     *
+     * The classification comes from the CUBE, the only metadata this package has:
+     * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+     * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+     * member lookup in this strategy uses, so "the member the gate classified"
+     * and "the member the compiler emits" cannot drift apart.
+     *
+     * A `time` dimension is read with the DATETIME rule — the permissive one of
+     * the three. That is the right direction because this is a routing decision,
+     * not a verdict: the engine door re-judges with the field's real declared
+     * type and has the final say, so under-classifying an exotic spelling merely
+     * leaves today's behaviour, while over-classifying would silently move a
+     * working dashboard off the fast path. The comparands this card measured
+     * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+     * so the decline fires for them whichever backing type the dimension has.
+     *
+     * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+     * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+     * lowering is not this gate's to answer — the filter is malformed either way
+     * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+     * message and envelope it has always had.
+     */
+    private carriesUninterpretableTemporalComparand;
+    /**
+     * [#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;
@@ -1513,6 +1652,18 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      */
     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

@@ -522,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.
@@ -569,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);
@@ -604,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
@@ -893,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.
@@ -1115,6 +1186,74 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#8690] Does the query's `where` compare a declared TIME dimension against
+     * a value no temporal storage rule can read? See the ruling at
+     * {@link canHandle}.
+     *
+     * The classification comes from the CUBE, the only metadata this package has:
+     * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+     * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+     * member lookup in this strategy uses, so "the member the gate classified"
+     * and "the member the compiler emits" cannot drift apart.
+     *
+     * A `time` dimension is read with the DATETIME rule — the permissive one of
+     * the three. That is the right direction because this is a routing decision,
+     * not a verdict: the engine door re-judges with the field's real declared
+     * type and has the final say, so under-classifying an exotic spelling merely
+     * leaves today's behaviour, while over-classifying would silently move a
+     * working dashboard off the fast path. The comparands this card measured
+     * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+     * so the decline fires for them whichever backing type the dimension has.
+     *
+     * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+     * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+     * lowering is not this gate's to answer — the filter is malformed either way
+     * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+     * message and envelope it has always had.
+     */
+    private carriesUninterpretableTemporalComparand;
+    /**
+     * [#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;
@@ -1513,6 +1652,18 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      */
     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