fix(service-datasource): derive ConnectionEngineLike from the engine contract, and stop promising registerDriver accepts any value (#13391)

* fix(service-datasource): derive ConnectionEngineLike from the engine contract (#12010)

Replace the seven hand-declared engine members on the exported
`ConnectionEngineLike` with `Partial<Pick<IObjectQLEngine, ...>>` — the #4251
B3 move `datasource-admin-plugin.ts` already made for its sibling
`DataEngineLike`.

The load-bearing half is `registerDriver`, which the seam declared as
`(driver: unknown, isDefault?: boolean) => void` against the contract's
`(driver: IDataDriver, isDefault?: boolean) => void`. Under
`strictFunctionTypes` the real engine was therefore not assignable to this
view, and the exported type promised the engine accepts any value as a driver.

Adds `connection-engine-like-contract.test.ts`, whose assertions fail if the
type is ever hand-written back.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012WkdHQwHr2KQmaX7P1BHzi

* test(runtime): narrow the degraded-boot parity engine double's getDriverByName

The consumer half of the ConnectionEngineLike derivation. This double answers
`unknown` where the derived seam member now answers the contract's
`IDataDriver | undefined`, which `check:type-check-debt` measured as
@objectstack/runtime TEST_DEBT 217 -> 218 (the package's own `typecheck`
excludes `**/*.test.ts`, so nothing else in the local family sees it).

Same triage as the three service-datasource fixtures: the double keeps its
minimal stand-ins and narrows on the way out.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012WkdHQwHr2KQmaX7P1BHzi

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: Elon Musk

.changeset/connection-engine-like-derived.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/service-datasource": patch
+---
+
+fix(service-datasource): derive `ConnectionEngineLike` from the engine contract instead of re-declaring it, and stop promising `registerDriver` accepts any value (#12010)
+
+`ConnectionEngineLike` — the exported view `DatasourceConnectionService` drives
+the ObjectQL `'data'` engine through — hand-declared seven engine members. The
+#12010 inventory measured what that cost, and one half of it was unsafe rather
+than merely duplicated.
+
+**The unsafe half.** The seam declared
+`registerDriver?: (driver: unknown, isDefault?: boolean) => void`,
+while the engine contract declares `registerDriver(driver: IDataDriver,
+isDefault?: boolean): void`. Under `strictFunctionTypes` that made the real
+engine **not assignable** to this view, and it told every consumer of the
+exported type that the engine accepts *any* value as a driver — which it does
+not, so a mis-shaped driver reaching `registerDriver` was a runtime problem the
+type was structured not to see. The parameter is now the contract's
+`IDataDriver`, which repairs both halves at once: the seam stops over-promising
+AND the engine becomes assignable to it.
+
+**The duplicated half.** Three members (`registerDatasourceDef`,
+`markDatasourceUnavailable`, `clearDatasourceUnavailable`) were declared by no
+contract at all when the card was filed — real `ObjectQL` methods, called
+across a package boundary, meeting no compiler on the producer side. #12248
+adjudicated all three onto `IDataEngine`, and #12482 followed with
+`syncObjectSchema`. All seven members are now **derived**
+(`Partial<Pick<IObjectQLEngine, …>>`) rather than re-written, the same #4251 B3
+move `datasource-admin-plugin.ts` already made for its sibling `DataEngineLike`
+one file over. Drift now lands as a build error here instead of a silent
+disagreement.
+
+`Partial` is preserved deliberately: `registerDriver` is required on the
+contract, while this service treats its absence as graceful degradation (the
+datasource is left metadata-only, `'skipped-no-infra'`). Making it required
+would change what a lightweight kernel does at boot.
+
+No runtime behaviour changes. The one cast the factory escape hatch still needs
+(`DatasourceDriverHandle.driver` is declared `unknown`, open to any host-built
+driver) moved to the single call site that constructs the value, and the
+`disconnect()` path dropped its cast entirely now that `getDriverByName` answers
+the contract's `IDataDriver | undefined`.
+
+**For hosts:** if you implement `ConnectionEngineLike` directly, its members are
+now the engine contract's members. An implementation whose `registerDriver`
+takes a wider parameter (`unknown`, `any`) is still accepted; one that returns a
+narrower value from `getDriverByName` than `IDataDriver | undefined` is not, and
+should answer the contract type.

packages/runtime/src/degraded-boot-parity.test.ts

@@ -31,6 +31,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { ObjectQL } from '@objectstack/objectql';
 import { DatasourceConnectionService } from '@objectstack/service-datasource';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 
 const ENV = 'OS_ALLOW_DRIVER_CONNECT_FAILURE';
 
@@ -85,7 +86,12 @@ async function bootDatasource(): Promise<Error | undefined> {
     }) as any,
     engine: () => ({
       registerDriver: (d: any) => drivers.set(d.name, d),
-      getDriverByName: (n: string) => drivers.get(n),
+      // [#12010] The double stores a bare `{ name: 'd' }` stand-in, while
+      // `ConnectionEngineLike.getDriverByName` is now derived from the engine
+      // contract and answers `IDataDriver | undefined`. Narrowing on the way
+      // out keeps the double as loose as this parity test needs it without
+      // re-widening the seam.
+      getDriverByName: (n: string) => drivers.get(n) as IDataDriver | undefined,
     }),
     logger: { warn() {} },
   });

packages/services/service-datasource/src/__tests__/connection-engine-like-contract.test.ts

@@ -0,0 +1,114 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#12010] The seam pin for `ConnectionEngineLike`.
+ *
+ * `ConnectionEngineLike` is the exported view `DatasourceConnectionService`
+ * drives the ObjectQL `'data'` engine through. It used to re-declare seven
+ * engine members by hand; it is now derived from {@link IObjectQLEngine}. The
+ * assertions below are the ones that FAIL if it is ever hand-written back.
+ *
+ * Enforced by `tsc --noEmit` (this package's `typecheck` includes `src`, and
+ * `src/__tests__` is inside it), not by the vitest run: vitest strips types.
+ * The `expect`s exist so the file is also a real, running test — but the
+ * measurement that matters here is the typecheck.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { IDataDriver, IObjectQLEngine } from '@objectstack/spec/contracts';
+import type { ConnectionEngineLike } from '../datasource-connection-service.js';
+
+describe('ConnectionEngineLike is the contract, not a fork of it (#12010)', () => {
+  it('the real engine contract is assignable to this view', () => {
+    // The defect this card measured, stated as a compile: with
+    // `registerDriver?: (driver: unknown, …)` the engine was NOT assignable
+    // here, because `unknown` is not assignable to the parameter's
+    // `IDataDriver` under `strictFunctionTypes`. Cast-free by construction.
+    const asConnectionEngine = (engine: IObjectQLEngine): ConnectionEngineLike => engine;
+    expect(typeof asConnectionEngine).toBe('function');
+  });
+
+  it('registerDriver takes a DRIVER, not any value', () => {
+    type RegisterDriver = NonNullable<ConnectionEngineLike['registerDriver']>;
+    type DriverParam = Parameters<RegisterDriver>[0];
+    // Exactly the contract's parameter — not a supertype of it. A widening
+    // back to `unknown` collapses the second leg.
+    const exact: [DriverParam] extends [IDataDriver]
+      ? [IDataDriver] extends [DriverParam]
+        ? 'exact'
+        : never
+      : never = 'exact';
+    expect(exact).toBe('exact');
+  });
+
+  it('refuses a value that is not a driver, at the call site', () => {
+    const engine = {} as ConnectionEngineLike;
+    // @ts-expect-error - a bare `{ name }` is not an `IDataDriver`. This call
+    // compiled before #12010, which is precisely the hole: the seam promised
+    // the engine accepts any value as a driver, and it does not.
+    engine.registerDriver?.({ name: 'com.example.not-a-driver' });
+    expect(engine).toBeTruthy();
+  });
+
+  it('getDriverByName answers the contract driver, not `unknown`', () => {
+    type Answer = ReturnType<NonNullable<ConnectionEngineLike['getDriverByName']>>;
+    // `unknown` would satisfy neither leg; this is what lets `disconnect()`
+    // reach `driver.disconnect` without the local re-derivation it used to
+    // cast through.
+    const exact: [Answer] extends [IDataDriver | undefined]
+      ? [IDataDriver | undefined] extends [Answer]
+        ? 'exact'
+        : never
+      : never = 'exact';
+    expect(exact).toBe('exact');
+  });
+
+  it('declares exactly the seven derived members, each identical to its contract member', () => {
+    type Declared = keyof ConnectionEngineLike;
+    type Expected =
+      | 'registerDriver'
+      | 'registerDatasourceDef'
+      | 'getDriverByName'
+      | 'syncObjectSchema'
+      | 'getDefaultDriverName'
+      | 'markDatasourceUnavailable'
+      | 'clearDatasourceUnavailable';
+    // Both directions: a member added by hand fails the first leg, a member
+    // dropped fails the second.
+    const roster: [Declared] extends [Expected]
+      ? [Expected] extends [Declared]
+        ? 'exact'
+        : never
+      : never = 'exact';
+
+    type Same<K extends Expected> =
+      NonNullable<ConnectionEngineLike[K]> extends NonNullable<IObjectQLEngine[K]>
+        ? NonNullable<IObjectQLEngine[K]> extends NonNullable<ConnectionEngineLike[K]>
+          ? 'same'
+          : never
+        : never;
+    const members: { [K in Expected]: Same<K> } = {
+      registerDriver: 'same',
+      registerDatasourceDef: 'same',
+      getDriverByName: 'same',
+      syncObjectSchema: 'same',
+      getDefaultDriverName: 'same',
+      markDatasourceUnavailable: 'same',
+      clearDatasourceUnavailable: 'same',
+    };
+
+    expect(roster).toBe('exact');
+    expect(Object.keys(members)).toHaveLength(7);
+  });
+
+  it('every member stays OPTIONAL — the graceful-degradation seam', () => {
+    // `registerDriver` is REQUIRED on the contract; `Partial<…>` is what keeps
+    // `if (!factory || !engine?.registerDriver) → 'skipped-no-infra'` a live
+    // runtime branch rather than dead code.
+    type AllOptional = {
+      [K in keyof ConnectionEngineLike]-?: undefined extends ConnectionEngineLike[K] ? true : false;
+    }[keyof ConnectionEngineLike];
+    const optional: AllOptional extends true ? 'optional' : never = 'optional';
+    expect(optional).toBe('optional');
+  });
+});

packages/services/service-datasource/src/__tests__/datasource-connection-service.test.ts

@@ -8,6 +8,7 @@ import {
   type ConnectionEngineLike,
 } from '../datasource-connection-service.js';
 import type { IDatasourceDriverFactory } from '../contracts/datasource-driver-factory.js';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 import type { DatasourceConnectPolicy } from '../contracts/connect-policy.js';
 import {
   GENERIC_CONNECT_FAILURE_REMEDY,
@@ -44,7 +45,12 @@ function fakeEngine() {
     registerDatasourceDef: (def) => {
       defs.push(def);
     },
-    getDriverByName: (name) => drivers.get(name),
+    // [#12010] The double deliberately stores MINIMAL stand-ins (a bare
+    // `{ name }` is how these tests simulate an `onEnable`-registered
+    // driver), while the derived seam member answers the contract's
+    // `IDataDriver | undefined`. Narrowing on the way out keeps the double
+    // loose where it is meant to be loose without re-widening the seam.
+    getDriverByName: (name) => drivers.get(name) as IDataDriver | undefined,
     syncObjectSchema: async (name) => {
       synced.push(name);
     },

packages/services/service-datasource/src/__tests__/datasource-pool-support.test.ts

@@ -64,6 +64,7 @@ import {
 } from '../datasource-connection-service.js';
 import { DatasourceAdminService, type StoredDatasource } from '../datasource-admin-service.js';
 import type { IDatasourceDriverFactory } from '../contracts/datasource-driver-factory.js';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 
 describe('#5714 — which driver arms read a declared `pool`', () => {
   it('names the two sqlite arms, `memory` and `turso` as unable to honour it (#5931 / #7243)', () => {
@@ -304,7 +305,12 @@ function fakeEngine() {
     drivers,
     registerDriver: (driver: any) => { drivers.set(driver.name, driver); },
     registerDatasourceDef: () => {},
-    getDriverByName: (name) => drivers.get(name),
+    // [#12010] The double deliberately stores MINIMAL stand-ins (a bare
+    // `{ name }` is how these tests simulate an `onEnable`-registered
+    // driver), while the derived seam member answers the contract's
+    // `IDataDriver | undefined`. Narrowing on the way out keeps the double
+    // loose where it is meant to be loose without re-widening the seam.
+    getDriverByName: (name) => drivers.get(name) as IDataDriver | undefined,
   };
   return engine;
 }

packages/services/service-datasource/src/__tests__/prebuilt-driver-factory.test.ts

@@ -11,6 +11,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { createPrebuiltDriverFactory } from '../prebuilt-driver-factory.js';
 import { DatasourceConnectionService } from '../datasource-connection-service.js';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 
 // The fail-fast case below asserts the default (no-escape-hatch) verdict.
 const ENV = 'OS_ALLOW_DRIVER_CONNECT_FAILURE';
@@ -91,7 +92,12 @@ describe('createPrebuiltDriverFactory — through DatasourceConnectionService (t
           drivers.set(d.name, d);
           if (isDefault) defaultName = d.name;
         },
-        getDriverByName: (n: string) => drivers.get(n),
+        // [#12010] The double deliberately stores MINIMAL stand-ins (a bare
+        // `{ name }` is how these tests simulate an `onEnable`-registered
+        // driver), while the derived seam member answers the contract's
+        // `IDataDriver | undefined`. Narrowing on the way out keeps the double
+        // loose where it is meant to be loose without re-widening the seam.
+        getDriverByName: (n: string) => drivers.get(n) as IDataDriver | undefined,
         getDefaultDriverName: () => defaultName,
       }),
       logger: { warn() {} },

packages/services/service-datasource/src/datasource-connection-service.ts

@@ -45,6 +45,7 @@ import {
 } from './datasource-pool-support.js';
 import { connectFailureRemedy } from './connect-failure-remedy.js';
 import type { Logger } from './logger.js';
+import type { IDataDriver, IObjectQLEngine } from '@objectstack/spec/contracts';
 
 /** A datasource definition this service can connect (code- or runtime-origin). */
 export interface ConnectableDatasource {
@@ -85,48 +86,57 @@ export interface DatasourceBoundObject {
   datasource?: string;
 }
 
-/** Engine surface this service drives (the ObjectQL `'data'` engine). */
-export interface ConnectionEngineLike {
-  registerDriver?: (driver: unknown, isDefault?: boolean) => void;
-  registerDatasourceDef?: (def: {
-    name: string;
-    schemaMode?: string;
-    external?: { allowWrites?: boolean };
-  }) => void;
-  getDriverByName?: (name: string) => unknown;
-  /**
-   * Register read metadata (DDL-free) for a federated object so its physical
-   * remote table/columns resolve for queries. Idempotent; called per bound
-   * external object after the driver is registered, because boot schema-sync
-   * ran before this driver existed (ADR-0015 §18; matches what the legacy
-   * `onEnable` bridge does manually).
-   */
-  syncObjectSchema?: (objectName: string) => Promise<void>;
-  /**
-   * Name of the engine's DEFAULT driver, when one is set. Used by the
-   * `asDefault` connect path's idempotency guard (#3826): the default driver
-   * keeps its natural name, so `getDriverByName('default')` can never detect a
-   * prior registration.
-   */
-  getDefaultDriverName?: () => string | undefined;
-  /**
-   * Tell the engine a datasource was *declared* but is not connected, and why
-   * (framework#3828). Without this the engine cannot distinguish "the app
-   * misspelled a datasource name" from "the host's policy refused it" from "it
-   * failed to connect and the operator set OS_ALLOW_DRIVER_CONNECT_FAILURE" —
-   * all three used to surface as the same bare `is not registered`.
-   *
-   * `publicDetail` is the only part safe to echo to an end user; the operator
-   * -facing reason stays in the logs and the datasource-admin list.
-   */
-  markDatasourceUnavailable?: (info: {
-    name: string;
-    kind: 'blocked' | 'failed';
-    publicDetail?: string;
-  }) => void;
-  /** Drop a previous {@link markDatasourceUnavailable} record (reconnect / removal). */
-  clearDatasourceUnavailable?: (name: string) => void;
-}
+/**
+ * Engine surface this service drives (the ObjectQL `'data'` engine), DERIVED
+ * from the published contracts rather than re-declared structurally — the
+ * #4251 B3 sweep pattern, applied here exactly as `datasource-admin-plugin.ts`
+ * applied it to its own `DataEngineLike` one file over, under #11493's ruling.
+ *
+ * [#12010] Every member was hand-written here until this change, and the
+ * inventory that filed that card measured what it cost. Three of them —
+ * `registerDatasourceDef`, `markDatasourceUnavailable`,
+ * `clearDatasourceUnavailable` — were declared by NO contract at all: real
+ * `ObjectQL` methods, called across a package boundary, meeting no compiler on
+ * the producer side, so drift landed silently in this consumer. #12248
+ * adjudicated all three onto {@link IDataEngine} and #12482 followed with
+ * `syncObjectSchema`; deriving is what makes the next drift a build error here
+ * instead of a re-declaration that quietly disagrees.
+ *
+ * One member was not merely a duplicate but wrong in the unsafe direction.
+ * `registerDriver?: (driver: unknown, isDefault?: boolean) => void` promised
+ * this seam accepts *any* value as a driver. The engine does not —
+ * {@link IObjectQLEngine.registerDriver} takes an {@link IDataDriver} — so
+ * under `strictFunctionTypes` the real engine was measurably NOT assignable to
+ * this view, and a mis-shaped driver reaching `registerDriver` was a runtime
+ * problem the type was structured not to see. Deriving repairs both halves at
+ * once; `__tests__/connection-engine-like-contract.test.ts` pins them.
+ *
+ * Anchored on {@link IObjectQLEngine} rather than {@link IDataEngine} for one
+ * member: `registerDriver` is declared only on the full engine contract. The
+ * two describe the same instance — `packages/objectql`'s plugin registers one
+ * object under both the `'data'` and `'objectql'` slots — but the `'data'`
+ * slot's declared type is the data plane alone, which is why
+ * `datasource-admin-plugin.ts` still reaches this type through a cast.
+ *
+ * `Partial<…>` is load-bearing, not shorthand — the same reason the sibling
+ * `DataEngineLike` carries it. `registerDriver` is REQUIRED on the contract,
+ * while this service treats its absence as a graceful-degradation signal
+ * (`if (!factory || !engine?.registerDriver)` leaves the datasource
+ * metadata-only, status `'skipped-no-infra'`). Making it required here would
+ * change what a lightweight kernel does at boot.
+ */
+export type ConnectionEngineLike = Partial<
+  Pick<
+    IObjectQLEngine,
+    | 'registerDriver'
+    | 'registerDatasourceDef'
+    | 'getDriverByName'
+    | 'syncObjectSchema'
+    | 'getDefaultDriverName'
+    | 'markDatasourceUnavailable'
+    | 'clearDatasourceUnavailable'
+  >
+>;
 
 /** Secret dereference surface (the `SecretBinder.resolve`, Phase 2 / D3). */
 export interface ConnectionSecretResolver {
@@ -588,10 +598,19 @@ export class DatasourceConnectionService {
       // `default` goes through the engine's default-driver fallback, never
       // `drivers.get('default')`, and the natural name keeps logs/lookups
       // byte-for-byte with the pre-#3826 boot.
-      const engineDriver = (handle.driver ?? handle) as { name?: string };
+      // [#12010] `DatasourceDriverHandle.driver` is declared `unknown` — the
+      // factory escape hatch is open to any host-built driver — so a cast is
+      // unavoidable somewhere on this path. It belongs HERE, at the one call
+      // site that constructs the value, not widened into the exported seam
+      // type where it told every consumer the engine accepts any value as a
+      // driver.
+      const engineDriver = (handle.driver ?? handle) as IDataDriver;
       if (!opts.asDefault) {
         try {
-          engineDriver.name = name;
+          // `IDataDriver.name` is `readonly`, and the engine routes by
+          // `driver.name === <datasource>`, so the stamp goes through a
+          // writable view (a frozen driver throws and is tolerated below).
+          (engineDriver as { name?: string }).name = name;
         } catch {
           /* frozen driver — registration may still work if name already matches */
         }
@@ -648,9 +667,11 @@ export class DatasourceConnectionService {
   async disconnect(name: string, opts: { asDefault?: boolean } = {}): Promise<void> {
     const engine = this.cfg.engine();
     const driverName = opts.asDefault ? engine?.getDefaultDriverName?.() : name;
-    const driver = (driverName ? engine?.getDriverByName?.(driverName) : undefined) as
-      | { disconnect?: () => Promise<void> }
-      | undefined;
+    // [#12010] Cast-free: `getDriverByName` now answers the contract's
+    // `IDataDriver | undefined` instead of a locally re-declared `unknown`.
+    // The `typeof … === 'function'` guard below stays — a host-built driver in
+    // the registry satisfies the contract only structurally.
+    const driver = driverName ? engine?.getDriverByName?.(driverName) : undefined;
     if (this.states.get(name)?.ownership === 'host') {
       this.logger?.debug?.(`datasource '${name}': adopted (host-owned) instance — pool left to the host, clearing state only`);
     } else if (typeof driver?.disconnect === 'function') {