feat(analytics): route external objects through driver-correct path (ADR-0062 Phase 3, D6)

NativeSQLStrategy hand-compiles FROM/columns that bypass the driver's physical
resolution (remoteName/remoteSchema/columnMap), so it would aggregate against the
wrong table for a federated object. It now declines any query whose base or joined
object is external (new optional StrategyContext.isExternalObject hook, reported by
the analytics plugin from the object's external block), routing it to the
ObjectQLStrategy whose engine.aggregate goes through the driver's getBuilder
(#2138/#2149). Reuses the driver's resolution rather than re-implementing it; until
a native-SQL fast path exists, external analytics is correct (via ObjectQL) instead
of silently wrong.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/adr-0062-analytics-external.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-analytics": minor
+---
+
+feat(analytics): correct analytics over federated objects (ADR-0062 Phase 3, D6)
+
+Analytics over an external (federated) object now aggregates against the
+**correct** remote table instead of silently querying the wrong one. The
+`NativeSQLStrategy` hand-compiles `FROM "<object>"` and bare column references,
+which bypass the driver's physical-table resolution (`external.remoteName` /
+`remoteSchema` / `columnMap`). It now **declines** any query whose base or joined
+object is federated, routing it to the `ObjectQLStrategy` — whose
+`engine.aggregate()` goes through the driver's `getBuilder` and already honours
+`remoteName`/`remoteSchema` (#2138/#2149). This "reuses the driver's resolution"
+(D6) rather than re-implementing it.
+
+Adds an optional `StrategyContext.isExternalObject(objectName)` hook (reported by
+the analytics plugin from the object's `external` block). Purely additive — with
+no hook, behavior is unchanged for managed objects.

docs/adr/0062-external-datasource-runtime.md

@@ -77,6 +77,8 @@ Code-defined datasources surface in `GET /api/v1/datasources`, `GET /api/v1/meta
 
 The analytics native-SQL strategy compiles its own `FROM "<table>"` / column references outside the driver (ADR-0015 §18 noted this). It must resolve an external object's physical table (`remoteName`/`remoteSchema`) and columns (`columnMap`) the same way `SqlDriver` now does — reusing the driver's resolution (e.g. an exposed `physicalTableFor(object)` / `physicalColumnFor(object, field)`), not a second copy. Until then, analytics over external objects stays disabled rather than silently querying the wrong table.
 
+> **Phase 3 implementation note (#2163) — "reuse the driver's resolution" = route external objects to the ObjectQL path.** Rather than re-implement `remoteName`/`remoteSchema`/`columnMap` resolution inside the native-SQL strategy (a second copy — explicitly rejected), `NativeSQLStrategy.canHandle` now **declines** any query whose base or joined object is federated (new optional `StrategyContext.isExternalObject` hook, reported by the analytics plugin from the object's `external` block). Declining routes the query to the lower-priority `ObjectQLStrategy`, whose `engine.aggregate()` already goes through the driver's `getBuilder` — which honours `remoteName`/`remoteSchema` (#2138/#2149). So external analytics aggregates against the **correct** remote table via the single source of truth (the driver), and native-SQL never queries the wrong table. (A native-SQL fast path for external objects can be added later by exposing `physicalTableFor`/`physicalColumnFor` on the driver; deeper `columnMap`-in-`GROUP BY` support is a separate driver concern.)
+
 ### D7 — `columnMap` is the external mechanism; reconcile `field.columnName`
 
 `external.columnMap` ({ remoteColumn → localField }) is the supported way to map external columns (shipped #2149). `field.columnName` (localField → physicalColumn) is its inverse and is **not** applied by the driver's query pipeline for external objects. Decision: for external objects, `columnMap` is authoritative; `field.columnName` on an external object is rejected at validation (no silent dual-source) until a unified column-resolution model is designed. Managed objects' `field.columnName` semantics are untouched.

packages/services/service-analytics/src/__tests__/native-sql-strategy-external.test.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0062 D6 — the NativeSQLStrategy must DECLINE federated (external-datasource)
+// objects: its hand-compiled `FROM "<object>"` / bare column refs bypass the
+// driver's physical-table resolution (remoteName/remoteSchema/columnMap) and
+// would query the wrong table. Declining routes the query to the lower-priority
+// ObjectQL aggregate path, which goes through the driver's getBuilder (correct).
+
+import { describe, it, expect } from 'vitest';
+import { NativeSQLStrategy } from '../strategies/native-sql-strategy.js';
+import type { StrategyContext } from '../strategies/types.js';
+
+const baseCaps = { nativeSql: true, objectqlAggregate: true, inMemory: false };
+
+function ctxFor(cube: any, isExternalObject?: (o: string) => boolean): StrategyContext {
+  return {
+    getCube: () => cube,
+    queryCapabilities: () => baseCaps,
+    executeRawSql: async () => [],
+    ...(isExternalObject ? { isExternalObject } : {}),
+  } as unknown as StrategyContext;
+}
+
+const query = { cube: 'c', measures: ['cnt'], dimensions: ['region'] } as any;
+
+describe('NativeSQLStrategy external-object gate (ADR-0062 D6)', () => {
+  const strategy = new NativeSQLStrategy();
+
+  it('DECLINES when the base object is external', () => {
+    const cube = { name: 'c', sql: 'ext_customer', dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube, (o) => o === 'ext_customer');
+    expect(strategy.canHandle(query, ctx)).toBe(false);
+  });
+
+  it('ACCEPTS a managed object (native-SQL still used)', () => {
+    const cube = { name: 'c', sql: 'account', dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube, () => false);
+    expect(strategy.canHandle(query, ctx)).toBe(true);
+  });
+
+  it('DECLINES when a JOINED object is external (the join would hit the wrong table)', () => {
+    const cube = { name: 'c', sql: 'orders', joins: { customer: { name: 'ext_customer' } }, dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube, (o) => o === 'ext_customer');
+    expect(strategy.canHandle(query, ctx)).toBe(false);
+  });
+
+  it('is purely additive — with no isExternalObject hook it behaves as before (accept)', () => {
+    const cube = { name: 'c', sql: 'ext_customer', dimensions: {}, measures: {} };
+    const ctx = ctxFor(cube); // no hook
+    expect(strategy.canHandle(query, ctx)).toBe(true);
+  });
+});

packages/services/service-analytics/src/analytics-service.ts

@@ -135,6 +135,14 @@ export interface AnalyticsServiceConfig {
    * `StrategyContext.coerceTemporalFilterValue` for the full rationale.
    */
   coerceTemporalFilterValue?: (objectName: string, fieldName: string, value: unknown) => unknown;
+  /**
+   * ADR-0062 D6 — report whether an object is federated (external datasource).
+   * Threaded into the StrategyContext so `NativeSQLStrategy` declines external
+   * objects (which it would otherwise query against the wrong physical table),
+   * routing them to the driver-correct ObjectQL aggregate path instead. See
+   * `StrategyContext.isExternalObject`.
+   */
+  isExternalObject?: (objectName: string) => boolean;
   /**
    * ADR-0021 — optional object-graph resolver used when compiling datasets:
    * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -260,6 +268,7 @@ export class AnalyticsService implements IAnalyticsService {
         this.datasetRegistry.get(cubeName)?.allowedRelationships
         ?? config.getAllowedRelationships?.(cubeName),
       coerceTemporalFilterValue: config.coerceTemporalFilterValue,
+      isExternalObject: config.isExternalObject,
     };
 
     // Build strategy chain (built-in + custom, sorted by priority)

packages/services/service-analytics/src/plugin.ts

@@ -32,6 +32,10 @@ interface DataEngineLike {
       reference?: string;
       options?: Array<{ value: unknown; label?: string }>;
     }>;
+    /** Federation marker (ADR-0015): set on objects bound to an external datasource. */
+    external?: unknown;
+    /** The datasource this object is bound to (ADR-0062 D6 external detection). */
+    datasource?: string;
   } | undefined;
   /**
    * Resolve the storage driver backing an object (public ObjectQL accessor).
@@ -443,6 +447,13 @@ export class AnalyticsServicePlugin implements Plugin {
           | undefined;
         return f ? { type: f.type, defaultCurrency: f.currencyConfig?.defaultCurrency } : undefined;
       },
+      // 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.
+      isExternalObject: (objectName: string) => {
+        const obj = dataEngine()?.getObject?.(objectName);
+        return !!(obj && obj.external != null);
+      },
       draftRowsResolver,
     };
 

packages/services/service-analytics/src/strategies/native-sql-strategy.ts

@@ -28,6 +28,26 @@ export class NativeSQLStrategy implements AnalyticsStrategy {
     // query silently grouped by the raw timestamp — one bucket per row — and a
     // non-UTC reference timezone was ignored entirely (ADR-0053 Phase 2, #1982).
     if (query.timeDimensions?.some((td) => !!td.granularity)) return false;
+    // ADR-0062 D6 — DECLINE federated (external-datasource) objects. This
+    // strategy hand-compiles `FROM "<object>"` and bare column references, which
+    // bypass the driver's physical-table resolution (`external.remoteName` /
+    // `remoteSchema` / `columnMap`) and would query the WRONG table. Routing the
+    // query to the lower-priority ObjectQL aggregate path keeps it correct —
+    // that path goes through the driver's `getBuilder` (#2138/#2149). Applies to
+    // the base object AND any joined object (a join would also hit the wrong
+    // table). Until native-SQL learns the driver's resolution, "disabled" beats
+    // "silently wrong".
+    if (typeof ctx.isExternalObject === 'function') {
+      const cube = ctx.getCube(query.cube);
+      if (cube) {
+        if (ctx.isExternalObject(this.extractObjectName(cube))) return false;
+        const joinTargets = cube.joins ? Object.values(cube.joins) : [];
+        for (const j of joinTargets) {
+          const joinedObject = (j as { name?: string })?.name;
+          if (joinedObject && ctx.isExternalObject(joinedObject)) return false;
+        }
+      }
+    }
     const caps = ctx.queryCapabilities(query.cube);
     return caps.nativeSql && typeof ctx.executeRawSql === 'function';
   }

packages/spec/src/contracts/analytics-service.ts

@@ -322,6 +322,26 @@ export interface StrategyContext {
      * @param value      The stringified comparand from the normalized filter.
      */
     coerceTemporalFilterValue?(objectName: string, fieldName: string, value: unknown): unknown;
+
+    /**
+     * ADR-0062 D6 — is `objectName` a federated (external-datasource) object?
+     *
+     * The `NativeSQLStrategy` compiles its own `FROM "<object>"` and column
+     * references, which bypass the driver's physical-table resolution and so
+     * would query the WRONG table for a federated object whose `external.remoteName`
+     * / `remoteSchema` / `columnMap` differ from the logical object/field names.
+     * Until native-SQL learns the driver's physical resolution, the strategy
+     * DECLINES external objects (see its `canHandle`), so they fall through to the
+     * ObjectQL aggregate path — which routes through the driver's `getBuilder`
+     * (honouring `remoteName`/`remoteSchema`, #2138/#2149). This keeps external
+     * analytics correct ("reuse the driver's resolution") rather than silently
+     * querying the wrong table.
+     *
+     * Returns `true` for a federated object, `false`/`undefined` otherwise. When
+     * the hook is absent (legacy wiring) the strategy assumes non-external —
+     * purely additive, no behavior change for managed objects.
+     */
+    isExternalObject?(objectName: string): boolean;
 }
 
 /**