feat(datasource): reject field.columnName on external + drop showcase onEnable bridge (ADR-0062 Phase 4, D7/D8) (#2203)

Author: xuyushun441-sys

.changeset/adr-0062-reconcile-cleanup.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/cli": minor
+"@objectstack/verify": minor
+---
+
+feat(datasource): reject field.columnName on external objects + drop showcase onEnable bridge (ADR-0062 Phase 4, D7/D8)
+
+**D7 — reconcile column mapping.** `os compile`/`build` (`validateStackExpressions`)
+now rejects `field.columnName` on a federated (external) object with a corrective
+message: the driver's query pipeline ignores `field.columnName` for external
+objects, so `external.columnMap` is the single authoritative mechanism. Managed
+objects are untouched.
+
+**D8 — drop the canonical example's driver bridge.** `examples/app-showcase`
+declares its external datasource with **no** `onEnable` driver registration — the
+declared datasource auto-connects at boot (ADR-0062 D1). `onEnable` now only
+provisions the "remote" fixture tables. To cover this end-to-end, the
+`@objectstack/verify` harness wires the datasource-admin plugin (registering the
+`'datasource-connection'` service) when an app declares datasources, so it mirrors
+`objectstack dev`/serve; a new dogfood test reads the federated objects through the
+real REST stack (incl. the `remoteName` remap). `onEnable` + `ctx.drivers.register`
+remains supported as an escape hatch for drivers built dynamically at runtime.

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

@@ -83,6 +83,8 @@ The analytics native-SQL strategy compiles its own `FROM "<table>"` / column ref
 
 `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.
 
+> **Phase 4 implementation note (#2163).** *D7* is enforced at build time in `validateStackExpressions` (`os compile`/`build`): any object that declares an `external` binding and a field with `columnName` is an error with a corrective message (use `external.columnMap`). Managed objects are untouched. *D8*: `examples/app-showcase` now declares its external datasource with **no** `onEnable` driver registration — `onEnable` only provisions the "remote" fixture tables; the declared datasource auto-connects (D1). To exercise this in the dogfood gate, the `@objectstack/verify` harness now wires the datasource-admin plugin (hence the `'datasource-connection'` service) when an app declares datasources — so the harness matches `objectstack dev`/serve and the federated read is covered end-to-end (a new dogfood test reads `showcase_ext_customer`/`_order`, including the `remoteName` remap). `onEnable` + `ctx.drivers.register` remains documented as the escape hatch for drivers built dynamically at runtime.
+
 ### D8 — Drop the `onEnable` bridge from the canonical example; keep it as an escape hatch
 
 Once D1 lands, `examples/app-showcase` declares its external datasource with **no** `onEnable` driver-registration code (fixture provisioning may remain). `onEnable` + `ctx.drivers.register` stays supported for advanced/dynamic cases (drivers built at runtime from external config).

examples/app-showcase/objectstack.config.ts

@@ -129,11 +129,13 @@ export default defineStack({
   // AI-authored metadata survive restarts (a `:memory:` datasource would wipe
   // everything on every restart, which makes local app-building unusable).
   //
-  // External-datasource federation demo (ADR-0015): a second, read-only SQLite
-  // file declared as a code-defined external datasource. It appears in
-  // Setup → Datasources and its federated objects (below) are queryable via
-  // REST. The fixture file + live driver are wired by `onEnable` (bottom of
-  // this file). `os dev` needs no extra setup.
+  // External-datasource federation demo (ADR-0015 / ADR-0062): a second,
+  // read-only SQLite file declared as a code-defined external datasource. It
+  // appears in Setup → Datasources and its federated objects (below) are
+  // queryable via REST — with NO driver wiring: the declared `external`
+  // datasource AUTO-CONNECTS at boot (ADR-0062 D1/D8). `onEnable` (bottom of
+  // this file) only provisions the "remote" fixture file's tables + seed data;
+  // `os dev` needs no extra setup.
   datasources: [ShowcaseExternalDatasource],
 
   // i18n
@@ -185,11 +187,14 @@ export default defineStack({
 });
 
 /**
- * Runtime wiring for the external-datasource federation demo (ADR-0015).
+ * Provisions the "remote" fixture database for the external-datasource
+ * federation demo (ADR-0015 / ADR-0062). Creating + seeding the remote tables is
+ * CODE (DDL on a separate SQLite file), so it can't live in the declarative
+ * artifact — it runs here. The AppPlugin invokes `onEnable` at boot.
  *
- * Code (fixture provisioning + live external-driver registration) can't live in
- * the declarative artifact, so it runs here. The AppPlugin invokes `onEnable` at
- * boot (Phase 2), before the external-validation gate fires on `kernel:ready`.
+ * NOTE (ADR-0062 D8): this no longer registers the external driver. The declared
+ * `external` datasource auto-connects at boot, so the federated objects are
+ * queryable with no driver wiring.
  */
 export const onEnable = async (ctx: unknown): Promise<void> => {
   await setupShowcaseExternalDatasource(ctx as Parameters<typeof setupShowcaseExternalDatasource>[0]);

examples/app-showcase/src/datasources/external-fixture.ts

@@ -3,22 +3,22 @@
 import { SqlDriver } from '@objectstack/driver-sql';
 
 /**
- * Runtime wiring for the external-datasource federation demo (ADR-0015).
+ * Fixture provisioning for the external-datasource federation demo
+ * (ADR-0015 / ADR-0062).
  *
- * This is CODE, so it can't live in the declarative artifact — it runs from the
- * stack's `onEnable` hook, which the AppPlugin invokes at boot (Phase 2), before
- * the external-validation gate fires on `kernel:ready` (Phase 3).
+ * This is the "remote database" stand-in: it idempotently creates the separate
+ * SQLite file with `customers` / `orders` tables + a little seed data (a MANAGED
+ * driver — DDL allowed) so `os dev` needs no external server. It runs from the
+ * stack's `onEnable` hook at boot.
  *
- * It does three things, all zero-config so `os dev` "just works":
- *   1. Idempotently provisions the "remote" SQLite file with `customers` /
- *      `orders` tables + a little seed data (a MANAGED driver — DDL allowed).
- *   2. Registers a read-only `schemaMode: 'external'` driver for that same file
- *      under the datasource name `showcase_external`, so ObjectQL can route
- *      queries to it. (Declared datasources are surfaced in the metadata
- *      registry for Setup → Datasources, but a live driver must be registered
- *      for the federated objects to be queryable in standalone mode.)
- *   3. Registers the federated objects' read metadata (DDL-free) so coercion +
- *      the remote-table mapping exist immediately.
+ * **It no longer registers a driver or syncs object schemas (ADR-0062 D8).** The
+ * declared `external` datasource (see `showcase-external.datasource.ts`) now
+ * AUTO-CONNECTS: at boot the runtime's `DatasourceConnectionService` builds the
+ * read-only `schemaMode:'external'` driver, registers it under the datasource
+ * name, and registers the federated objects' read metadata — with zero app code.
+ * The old `onEnable` + `ctx.drivers.register` bridge is gone; `onEnable` +
+ * `ctx.drivers.register` remains *supported* only as an advanced escape hatch
+ * (drivers built dynamically at runtime).
  */
 
 // Same relative path as the datasource config — resolved against the project
@@ -60,15 +60,17 @@ const ORDER_ROWS = [
   { id: 'o4', customer_id: 'c3', amount: 3300, status: 'paid', placed_on: '2026-03-01' },
 ];
 
-/** Stack `onEnable` payload (subset we use). */
+/** Stack `onEnable` payload (subset we use — provisioning only logs). */
 interface OnEnableContext {
-  ql: { syncObjectSchema?: (name: string) => Promise<void> };
-  drivers: { register: (driver: unknown) => void };
   logger?: { info?: (msg: string, meta?: unknown) => void; warn?: (msg: string, meta?: unknown) => void };
 }
 
+/**
+ * Provision the "remote" fixture database. Idempotent: creates the tables and
+ * seeds them only when empty. Does NOT register a driver — the declared external
+ * datasource auto-connects at boot (ADR-0062 D1/D8).
+ */
 export async function setupShowcaseExternalDatasource(ctx: OnEnableContext): Promise<void> {
-  // 1. Provision the remote fixture with a MANAGED driver (DDL allowed). Idempotent.
   const fixture = new SqlDriver({
     client: 'better-sqlite3',
     connection: { filename: EXTERNAL_DB_FILE },
@@ -93,21 +95,7 @@ export async function setupShowcaseExternalDatasource(ctx: OnEnableContext): Pro
     await fixture.disconnect();
   }
 
-  // 2. Register the read-only EXTERNAL driver under the datasource name.
-  const ext = new SqlDriver({
-    client: 'better-sqlite3',
-    connection: { filename: EXTERNAL_DB_FILE },
-    useNullAsDefault: true,
-    schemaMode: 'external',
-  } as never) as unknown as { name: string; connect: () => Promise<void> };
-  ext.name = 'showcase_external'; // MUST equal the datasource name (ObjectQL routes by driver name).
-  await ext.connect();
-  ctx.drivers.register(ext);
-
-  // 3. Register read metadata for the federated objects (DDL-free; ADR-0015).
-  //    Needed because the driver is registered after the boot schema-sync.
-  await ctx.ql.syncObjectSchema?.('showcase_ext_customer');
-  await ctx.ql.syncObjectSchema?.('showcase_ext_order');
-
-  ctx.logger?.info?.('[showcase] external datasource "showcase_external" ready — federation demo (ADR-0015)');
+  ctx.logger?.info?.(
+    '[showcase] external fixture provisioned — datasource "showcase_external" auto-connects (ADR-0062)',
+  );
 }

packages/cli/src/utils/validate-expressions.test.ts

@@ -343,4 +343,55 @@ describe('validateStackExpressions (ADR-0032 build-time)', () => {
       expect(issues.some(i => i.where.includes('when') && /bare reference `tier`/.test(i.message))).toBe(true);
     });
   });
+
+  describe('ADR-0062 D7 — field.columnName on external objects', () => {
+    it('rejects field.columnName on a federated (external) object', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'ext_customer',
+          datasource: 'warehouse',
+          external: { remoteName: 'customers' },
+          fields: { region: { type: 'text', columnName: 'cust_region' } },
+        }],
+      });
+      const issue = issues.find(i => /columnName/.test(i.message));
+      expect(issue).toBeDefined();
+      expect(issue!.severity).toBe('error');
+      expect(issue!.where).toContain("object 'ext_customer'");
+      expect(issue!.where).toContain("field 'region'");
+      expect(issue!.message).toMatch(/external\.columnMap|ADR-0062 D7/);
+    });
+
+    it('rejects field.columnName declared as a map-shaped field too', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'ext_order',
+          external: {},
+          fields: { amount: { type: 'number', columnName: 'amt' } },
+        }],
+      });
+      expect(issues.some(i => /columnName/.test(i.message) && i.where.includes("field 'amount'"))).toBe(true);
+    });
+
+    it('leaves field.columnName on a MANAGED object untouched (no issue)', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'crm_account',
+          fields: { region: { type: 'text', columnName: 'acct_region' } },
+        }],
+      });
+      expect(issues.some(i => /columnName/.test(i.message))).toBe(false);
+    });
+
+    it('passes an external object that uses no columnName', () => {
+      const issues = validateStackExpressions({
+        objects: [{
+          name: 'ext_customer',
+          external: { remoteName: 'customers' },
+          fields: { region: { type: 'text' } },
+        }],
+      });
+      expect(issues.some(i => /columnName/.test(i.message))).toBe(false);
+    });
+  });
 });

packages/cli/src/utils/validate-expressions.ts

@@ -150,6 +150,35 @@ export function validateStackExpressions(stack: AnyRec): ExprIssue[] {
     const fieldList = Array.isArray(fields)
       ? (fields as AnyRec[])
       : (fields && typeof fields === 'object' ? Object.values(fields as AnyRec) as AnyRec[] : []);
+
+    // ── ADR-0062 D7 — reject `field.columnName` on external objects ──────
+    // `field.columnName` (localField → physicalColumn) is the managed-object
+    // mechanism; it is NOT applied by the driver's query pipeline for federated
+    // objects, where `external.columnMap` (remoteColumn → localField) is the
+    // authoritative — and inverse — mapping. Allowing both would be a silent
+    // dual-source ambiguity, so reject `columnName` on any object that declares
+    // an `external` binding (a federated object). Managed objects are untouched.
+    if (obj.external != null) {
+      const fieldEntries: Array<[string, AnyRec]> = Array.isArray(fields)
+        ? (fields as AnyRec[]).map((f) => [((f as AnyRec)?.name as string) ?? '?', f as AnyRec])
+        : (fields && typeof fields === 'object'
+            ? (Object.entries(fields as AnyRec) as Array<[string, AnyRec]>)
+            : []);
+      for (const [fname, fdef] of fieldEntries) {
+        if (fdef && typeof fdef === 'object' && (fdef as AnyRec).columnName != null) {
+          issues.push({
+            where: `object '${objectName}' · field '${fname}'`,
+            message:
+              `external object '${objectName}': field '${fname}' sets columnName='${String((fdef as AnyRec).columnName)}', ` +
+              `which is not supported on federated objects (ADR-0062 D7). The driver's query pipeline ignores ` +
+              `field.columnName for external objects; map remote columns via the datasource's external.columnMap instead.`,
+            source: `columnName='${String((fdef as AnyRec).columnName)}'`,
+            severity: 'error',
+          });
+        }
+      }
+    }
+
     for (const f of fieldList) {
       // Field-level conditional rules are server-enforced (rule-validator) and
       // record-scoped — a bare ref silently fails the rule (required/readonly

packages/dogfood/test/showcase-external-autoconnect.dogfood.test.ts

@@ -0,0 +1,59 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// ADR-0062 D1/D8 — the showcase declares its `external` datasource with NO
+// `onEnable` driver wiring (only fixture provisioning remains). This proves the
+// declared external datasource AUTO-CONNECTS at boot and its federated objects
+// are queryable end-to-end through the real REST stack — zero app code. Guards
+// against a regression where dropping the `onEnable` bridge would leave the
+// external objects unrouted ("Datasource 'showcase_external' is not registered").
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import showcaseStack, { onEnable } from '@objectstack/example-showcase';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+
+function listOf(body: unknown): Array<Record<string, unknown>> {
+  const b = body as { records?: unknown[]; data?: unknown[] } | unknown[];
+  if (Array.isArray(b)) return b as Array<Record<string, unknown>>;
+  return ((b as { records?: unknown[] }).records ?? (b as { data?: unknown[] }).data ?? []) as Array<Record<string, unknown>>;
+}
+
+describe('showcase: external datasource auto-connects with no onEnable bridge (ADR-0062 D8)', () => {
+  let stack: VerifyStack;
+  let admin: string;
+
+  beforeAll(async () => {
+    // Stand up the "remote" database (the showcase's onEnable fixture provisioner).
+    // The verify harness imports only the stack's default export, so its onEnable
+    // never runs here — we invoke it ourselves to create the remote customers/orders
+    // tables, exactly as `os dev` does at boot. Crucially this does NOT register a
+    // driver (ADR-0062 D8); auto-connect (below, during bootStack) does that.
+    await onEnable({ logger: { info() {}, warn() {} } } as never);
+    stack = await bootStack(showcaseStack);
+    admin = await stack.signIn();
+  }, 60_000);
+
+  afterAll(async () => { await stack?.stop(); });
+
+  it('federated customer object is queryable (auto-connected, seeded fixture rows returned)', async () => {
+    const res = await stack.apiAs(admin, 'GET', '/data/showcase_ext_customer');
+    expect(res.status, 'federated object must be queryable — driver auto-connected').toBe(200);
+    const rows = listOf(await res.json());
+    expect(rows.length).toBeGreaterThanOrEqual(3);
+    expect(rows.map((r) => r.name)).toContain('Aurora Labs');
+  });
+
+  it('federated order object (remoteName remap) is queryable too', async () => {
+    const res = await stack.apiAs(admin, 'GET', '/data/showcase_ext_order');
+    expect(res.status).toBe(200);
+    const rows = listOf(await res.json());
+    expect(rows.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('region filter pushes down to the remote table', async () => {
+    const res = await stack.apiAs(admin, 'GET', '/data/showcase_ext_customer?region=EU');
+    expect(res.status).toBe(200);
+    const rows = listOf(await res.json());
+    expect(rows.every((r) => r.region === 'EU')).toBe(true);
+    expect(rows.length).toBeGreaterThanOrEqual(1);
+  });
+});

packages/verify/package.json

@@ -32,7 +32,8 @@
     "@objectstack/plugin-org-scoping": "workspace:*",
     "@objectstack/service-settings": "workspace:*",
     "@objectstack/service-analytics": "workspace:*",
-    "@objectstack/service-automation": "workspace:*"
+    "@objectstack/service-automation": "workspace:*",
+    "@objectstack/service-datasource": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",

packages/verify/src/harness.ts

@@ -127,6 +127,26 @@ export async function bootStack(
   await kernel.use(new AnalyticsServicePlugin());
   await kernel.use(new AuthPlugin({ secret: opts.authSecret ?? DEFAULT_AUTH_SECRET }));
 
+  // ADR-0062 — datasource connection service (registers 'datasource-connection'),
+  // mirroring `objectstack dev`/serve. Without it, AppPlugin's declared-datasource
+  // auto-connect (D1/D2) degrades and a federated app would need an `onEnable`
+  // driver bridge — so this is what exercises the no-`onEnable` federation path
+  // end-to-end in the dogfood gate. Wired only when the app declares datasources
+  // (so the vast majority of apps are unaffected); the D2 gate then leaves
+  // managed/unrouted datasources metadata-only (e.g. app-crm — unchanged).
+  {
+    const dsDefs = (config as { datasources?: unknown }).datasources;
+    const declaresDatasources = Array.isArray(dsDefs)
+      ? dsDefs.length > 0
+      : !!dsDefs && typeof dsDefs === 'object' && Object.keys(dsDefs).length > 0;
+    if (declaresDatasources) {
+      const { DatasourceAdminServicePlugin, createDefaultDatasourceDriverFactory } = await import(
+        '@objectstack/service-datasource'
+      );
+      await kernel.use(new DatasourceAdminServicePlugin({ driverFactory: createDefaultDatasourceDriverFactory() }));
+    }
+  }
+
   // Multi-tenant: org-scoping MUST register BEFORE SecurityPlugin — the latter
   // probes the `org-scoping` service exactly once at start and caches it, then
   // keeps (vs strips) the wildcard `organization_id` RLS policies accordingly.