@objectstack/service-datasource 10.0.0 → 10.3.0

package/dist/sqlite-driver-fallback-BPFQYLX7.js

@@ -0,0 +1,11 @@
+import {
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  resolveSqliteDriver
+} from "./chunk-JRBGOCRJ.js";
+export {
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  resolveSqliteDriver
+};
+//# sourceMappingURL=sqlite-driver-fallback-BPFQYLX7.js.map

package/dist/sqlite-driver-fallback-BPFQYLX7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sqlite-driver-fallback-JX4XOICD.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunk76HQ74MXcjs = require('./chunk-76HQ74MX.cjs');
+
+
+
+
+exports.NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = _chunk76HQ74MXcjs.NATIVE_SQLITE_MEMORY_FALLBACK_WARNING; exports.NATIVE_SQLITE_WASM_FALLBACK_WARNING = _chunk76HQ74MXcjs.NATIVE_SQLITE_WASM_FALLBACK_WARNING; exports.resolveSqliteDriver = _chunk76HQ74MXcjs.resolveSqliteDriver;
+//# sourceMappingURL=sqlite-driver-fallback-JX4XOICD.cjs.map

package/dist/sqlite-driver-fallback-JX4XOICD.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-datasource/dist/sqlite-driver-fallback-JX4XOICD.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACF,kRAAC","file":"/home/runner/work/framework/framework/packages/services/service-datasource/dist/sqlite-driver-fallback-JX4XOICD.cjs"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-datasource",
-  "version": "10.0.0",
+  "version": "10.3.0",
   "license": "Apache-2.0",
   "description": "The datasource service (ADR-0015): external-table federation (introspect/draft/import/validate) + runtime UI datasource lifecycle (list/test/create/update/remove + REST routes). Open-source mechanism; the tier line falls on which ICryptoProvider / driver factory a host injects.",
   "type": "module",
@@ -19,18 +19,19 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "10.0.0",
-    "@objectstack/spec": "10.0.0"
+    "@objectstack/core": "10.3.0",
+    "@objectstack/spec": "10.3.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@objectstack/driver-memory": "10.0.0",
-    "@objectstack/driver-sql": "10.0.0",
-    "@objectstack/plugin-hono-server": "10.0.0",
-    "@objectstack/driver-mongodb": "10.0.0"
+    "@objectstack/driver-memory": "10.3.0",
+    "@objectstack/driver-sql": "10.3.0",
+    "@objectstack/driver-sqlite-wasm": "10.3.0",
+    "@objectstack/plugin-hono-server": "10.3.0",
+    "@objectstack/driver-mongodb": "10.3.0"
   },
   "keywords": [
     "objectstack",

package/src/__tests__/datasource-connection-service.test.ts

@@ -0,0 +1,294 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  DatasourceConnectionService,
+  isDatasourceAddressed,
+  type ConnectableDatasource,
+  type ConnectionEngineLike,
+} from '../datasource-connection-service.js';
+import type { IDatasourceDriverFactory } from '../contracts/datasource-driver-factory.js';
+import type { DatasourceConnectPolicy } from '../contracts/connect-policy.js';
+
+/** A fake engine recording driver registration + schema syncs. */
+function fakeEngine() {
+  const drivers = new Map<string, { name?: string }>();
+  const defs: Array<{ name: string; schemaMode?: string }> = [];
+  const synced: string[] = [];
+  const engine: ConnectionEngineLike & { drivers: typeof drivers; defs: typeof defs; synced: string[] } = {
+    drivers,
+    defs,
+    synced,
+    registerDriver: (driver: any) => {
+      if (drivers.has(driver.name)) return; // mirror engine's skip-if-present
+      drivers.set(driver.name, driver);
+    },
+    registerDatasourceDef: (def) => {
+      defs.push(def);
+    },
+    getDriverByName: (name) => drivers.get(name),
+    syncObjectSchema: async (name) => {
+      synced.push(name);
+    },
+  };
+  return engine;
+}
+
+/** A fake factory that builds a trivial connectable handle. */
+function fakeFactory(opts: { supports?: (id: string) => boolean; connectThrows?: boolean } = {}): IDatasourceDriverFactory {
+  return {
+    supports: opts.supports ?? (() => true),
+    create: vi.fn(async () => {
+      const driver: any = { name: 'com.fake.driver' };
+      return {
+        driver,
+        connect: opts.connectThrows
+          ? async () => {
+              throw new Error('connection refused');
+            }
+          : async () => {
+              driver.connected = true;
+            },
+      };
+    }),
+  };
+}
+
+function svc(over: {
+  factory?: IDatasourceDriverFactory | undefined;
+  engine?: ConnectionEngineLike | undefined;
+  policy?: DatasourceConnectPolicy;
+  secrets?: { resolve?: (ref: string) => Promise<string | undefined> };
+} = {}) {
+  const engine = over.engine === undefined ? fakeEngine() : over.engine;
+  const factory = over.factory === undefined ? fakeFactory() : over.factory;
+  const service = new DatasourceConnectionService({
+    factory: () => factory ?? undefined,
+    engine: () => engine ?? undefined,
+    policy: over.policy,
+    secrets: over.secrets,
+  });
+  return { service, engine: engine as ReturnType<typeof fakeEngine> | undefined, factory };
+}
+
+const externalDs: ConnectableDatasource = {
+  name: 'warehouse',
+  driver: 'sqlite',
+  schemaMode: 'external',
+  config: { filename: '/tmp/w.db' },
+  external: { allowWrites: false, validation: { onMismatch: 'warn' } },
+};
+
+describe('isDatasourceAddressed (ADR-0062 D2 gate)', () => {
+  it('connects external datasources (a)', () => {
+    expect(isDatasourceAddressed({ name: 'x', schemaMode: 'external' }, { objects: [] })).toBe(true);
+    expect(isDatasourceAddressed({ name: 'x', schemaMode: 'validate-only' }, { objects: [] })).toBe(true);
+  });
+
+  it('connects when an object explicitly binds via object.datasource (b)', () => {
+    expect(
+      isDatasourceAddressed({ name: 'reporting', schemaMode: 'managed' }, { objects: [{ name: 'o', datasource: 'reporting' }] }),
+    ).toBe(true);
+  });
+
+  it('connects when autoConnect:true (c)', () => {
+    expect(isDatasourceAddressed({ name: 'x', schemaMode: 'managed', autoConnect: true }, { objects: [] })).toBe(true);
+  });
+
+  it('does NOT connect a managed datasource that is only mapped / unrouted (app-crm byte-for-byte unchanged)', () => {
+    // app-crm: crm_primary is managed + referenced by datasourceMapping only,
+    // crm_analytics is managed + unrouted. Neither has an object binding.
+    expect(isDatasourceAddressed({ name: 'crm_primary', schemaMode: 'managed' }, { objects: [] })).toBe(false);
+    expect(isDatasourceAddressed({ name: 'crm_analytics', schemaMode: 'managed' }, { objects: [] })).toBe(false);
+    // An object bound to a DIFFERENT datasource must not flip the gate.
+    expect(
+      isDatasourceAddressed({ name: 'crm_primary', schemaMode: 'managed' }, { objects: [{ name: 'acct', datasource: 'default' }] }),
+    ).toBe(false);
+  });
+});
+
+describe('DatasourceConnectionService.connect', () => {
+  it('builds, connects, stamps the datasource name, and registers the driver + def', async () => {
+    const { service, engine, factory } = svc();
+    const result = await service.connect(externalDs, { objects: ['ext_customer'] });
+    expect(result.status).toBe('connected');
+    expect(factory.create).toHaveBeenCalledOnce();
+    // Driver registered under the DATASOURCE name (engine routes by driver.name).
+    expect(engine!.drivers.has('warehouse')).toBe(true);
+    expect(engine!.drivers.get('warehouse')!.name).toBe('warehouse');
+    // Datasource definition recorded for the write gate.
+    expect(engine!.defs).toEqual([{ name: 'warehouse', schemaMode: 'external', external: externalDs.external }]);
+    // Bound external objects got read metadata synced (DDL-free).
+    expect(engine!.synced).toEqual(['ext_customer']);
+  });
+
+  it('is idempotent — an already-registered driver is skipped (onEnable escape hatch)', async () => {
+    const { service, engine, factory } = svc();
+    engine!.drivers.set('warehouse', { name: 'warehouse' }); // pretend onEnable registered it
+    const result = await service.connect(externalDs, { objects: ['ext_customer'] });
+    expect(result.status).toBe('already-registered');
+    expect(factory.create).not.toHaveBeenCalled();
+    expect(engine!.synced).toEqual([]); // no double sync
+  });
+
+  it('resolves external.credentialsRef via the secret resolver before building', async () => {
+    const resolve = vi.fn(async () => 's3cr3t');
+    const create = vi.fn(async () => ({ driver: { name: 'd' }, connect: async () => {} }));
+    const factory: IDatasourceDriverFactory = { supports: () => true, create };
+    const { service } = svc({ factory, secrets: { resolve } });
+    await service.connect({ ...externalDs, external: { ...externalDs.external, credentialsRef: 'secret:wh/pw' } });
+    expect(resolve).toHaveBeenCalledWith('secret:wh/pw');
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ secret: 's3cr3t' }));
+  });
+
+  it('respects a deny policy — left unconnected, metadata-only', async () => {
+    const policy: DatasourceConnectPolicy = { canConnect: () => ({ allow: false, reason: 'egress blocked' }) };
+    const { service, engine, factory } = svc({ policy });
+    const result = await service.connect(externalDs);
+    expect(result.status).toBe('skipped-policy');
+    expect(result.reason).toBe('egress blocked');
+    expect(factory.create).not.toHaveBeenCalled();
+    expect(engine!.drivers.size).toBe(0);
+  });
+
+  it('treats a throwing policy as a denial (fail-closed)', async () => {
+    const policy: DatasourceConnectPolicy = {
+      canConnect: () => {
+        throw new Error('policy backend down');
+      },
+    };
+    const { service, engine } = svc({ policy });
+    const result = await service.connect(externalDs);
+    expect(result.status).toBe('skipped-policy');
+    expect(engine!.drivers.size).toBe(0);
+  });
+
+  it('degrades (no throw) when there is no factory / engine', async () => {
+    const noFactory = new DatasourceConnectionService({ factory: () => undefined, engine: () => fakeEngine() });
+    expect((await noFactory.connect(externalDs)).status).toBe('skipped-no-infra');
+    const noEngine = new DatasourceConnectionService({ factory: () => fakeFactory(), engine: () => undefined });
+    expect((await noEngine.connect(externalDs)).status).toBe('skipped-no-infra');
+  });
+
+  describe('D5 connect-failure policy', () => {
+    const failExternal: ConnectableDatasource = {
+      ...externalDs,
+      external: { allowWrites: false, validation: { onMismatch: 'fail' } },
+    };
+
+    it('fail-fast: a declared-auto external + onMismatch:fail re-throws (bricks boot)', async () => {
+      const { service } = svc({ factory: fakeFactory({ connectThrows: true }) });
+      await expect(
+        service.connect(failExternal, { context: { trigger: 'declared-auto' } }),
+      ).rejects.toThrow(/fail-fast/);
+    });
+
+    it('degrade: the SAME datasource connected via runtime-admin never bricks the server', async () => {
+      const { service } = svc({ factory: fakeFactory({ connectThrows: true }) });
+      const result = await service.connect(failExternal, { context: { trigger: 'runtime-admin' } });
+      expect(result.status).toBe('failed-degraded');
+    });
+
+    it('degrade: external + onMismatch:warn degrades even at boot', async () => {
+      const { service } = svc({ factory: fakeFactory({ connectThrows: true }) });
+      const result = await service.connect(externalDs, { context: { trigger: 'declared-auto' } });
+      expect(result.status).toBe('failed-degraded');
+    });
+  });
+});
+
+describe('D3 credential resolution — fail-closed', () => {
+  const credExternal: ConnectableDatasource = {
+    name: 'warehouse',
+    driver: 'sqlite',
+    schemaMode: 'external',
+    config: {},
+    external: { allowWrites: false, credentialsRef: 'sys_secret:abc', validation: { onMismatch: 'warn' } },
+  };
+
+  it('fails closed when a credentialsRef is declared but NO secret store is configured', async () => {
+    const factory = fakeFactory();
+    const { service, engine } = svc({ factory }); // no `secrets`
+    const result = await service.connect(credExternal, { context: { trigger: 'runtime-admin' } });
+    expect(result.status).toBe('failed-credentials');
+    expect(result.reason).toMatch(/no secret store/);
+    expect(factory.create).not.toHaveBeenCalled(); // never built without the secret
+    expect(engine!.drivers.size).toBe(0);
+  });
+
+  it('fails closed when the credentialsRef cannot be resolved/decrypted (undefined)', async () => {
+    const factory = fakeFactory();
+    const { service } = svc({ factory, secrets: { resolve: async () => undefined } });
+    const result = await service.connect(credExternal, { context: { trigger: 'runtime-admin' } });
+    expect(result.status).toBe('failed-credentials');
+    expect(result.reason).toMatch(/could not be resolved or decrypted/);
+    expect(factory.create).not.toHaveBeenCalled();
+  });
+
+  it('fails closed when the resolver throws', async () => {
+    const factory = fakeFactory();
+    const { service } = svc({
+      factory,
+      secrets: {
+        resolve: async () => {
+          throw new Error('kms unreachable');
+        },
+      },
+    });
+    const result = await service.connect(credExternal, { context: { trigger: 'runtime-admin' } });
+    expect(result.status).toBe('failed-credentials');
+    expect(factory.create).not.toHaveBeenCalled();
+  });
+
+  it('fail-fast: a declared-auto external + onMismatch:fail with an unresolvable credential re-throws', async () => {
+    const failCred: ConnectableDatasource = {
+      ...credExternal,
+      external: { allowWrites: false, credentialsRef: 'sys_secret:abc', validation: { onMismatch: 'fail' } },
+    };
+    const { service } = svc({ secrets: { resolve: async () => undefined } });
+    await expect(service.connect(failCred, { context: { trigger: 'declared-auto' } })).rejects.toThrow(/fail-fast/);
+  });
+
+  it('connects when the credential resolves to a secret', async () => {
+    const create = vi.fn(async () => ({ driver: { name: 'd' }, connect: async () => {} }));
+    const factory: IDatasourceDriverFactory = { supports: () => true, create };
+    const { service } = svc({ factory, secrets: { resolve: async () => 's3cr3t' } });
+    const result = await service.connect(credExternal);
+    expect(result.status).toBe('connected');
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ secret: 's3cr3t' }));
+  });
+});
+
+describe('DatasourceConnectionService.connectDeclared', () => {
+  it('connects only the gated datasources and syncs each one’s bound objects', async () => {
+    const { service, engine, factory } = svc();
+    const datasources: ConnectableDatasource[] = [
+      externalDs, // external → connect
+      { name: 'crm_primary', driver: 'sqlite', schemaMode: 'managed', config: { filename: ':memory:' } }, // managed+unrouted → skip
+      { name: 'reporting', driver: 'sqlite', schemaMode: 'managed', config: {} }, // managed but object-bound → connect
+    ];
+    const objects = [
+      { name: 'ext_customer', datasource: 'warehouse' },
+      { name: 'report_row', datasource: 'reporting' },
+      { name: 'account', datasource: 'default' }, // routes to default → no effect
+    ];
+    const results = await service.connectDeclared({ datasources, objects });
+    const byName = Object.fromEntries(results.map((r) => [r.name, r.status]));
+    expect(byName).toEqual({ warehouse: 'connected', reporting: 'connected' });
+    expect(engine!.drivers.has('crm_primary')).toBe(false); // unchanged
+    expect(engine!.drivers.has('warehouse')).toBe(true);
+    expect(engine!.drivers.has('reporting')).toBe(true);
+    expect(engine!.synced.sort()).toEqual(['ext_customer', 'report_row']);
+    expect(factory.create).toHaveBeenCalledTimes(2);
+  });
+
+  it('skips inactive datasources', async () => {
+    const { service, engine } = svc();
+    const results = await service.connectDeclared({
+      datasources: [{ ...externalDs, active: false }],
+      objects: [],
+    });
+    expect(results).toEqual([]);
+    expect(engine!.drivers.size).toBe(0);
+  });
+});

package/src/contracts/connect-policy.ts

@@ -0,0 +1,69 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * DatasourceConnectPolicy — host-injectable gate consulted *before*
+ * {@link DatasourceConnectionService} builds and registers a live driver
+ * (ADR-0062 D1/D5, and the epic #2163 "connect-policy seam" note).
+ *
+ * The framework ships a permissive default ({@link allowAllConnectPolicy}) so a
+ * self-hosted single-environment runtime connects external datasources out of
+ * the box (subject to the D2 auto-connect gate, which is applied separately by
+ * {@link DatasourceConnectionService.connectDeclared}). A multi-tenant host
+ * (shared-container cloud) binds a stricter policy that can *fail-close* on the
+ * shared runtime — e.g. checking `sys_environment.plan`, an egress allow-list,
+ * and per-tenant quota — to enforce SSRF / egress isolation.
+ *
+ * This keeps a single connect path for code- and runtime-origin datasources
+ * (D1): the host injects a policy rather than forking a second connect path.
+ * No plan coupling lives in the open framework.
+ */
+
+/** Why a connect is being attempted — lets a policy treat origins differently. */
+export interface DatasourceConnectContext {
+  /** Provenance of the datasource being connected. */
+  origin?: 'code' | 'runtime';
+  /**
+   * What triggered this connect:
+   *  - `declared-auto`  — code-defined datasource auto-connected at boot (D2 gate passed).
+   *  - `runtime-admin`  — UI "Add/Update Datasource" hot pool registration.
+   *  - `rehydrate`      — boot rehydration of a persisted runtime datasource.
+   */
+  trigger?: 'declared-auto' | 'runtime-admin' | 'rehydrate';
+}
+
+/** A policy verdict. `allow:false` leaves the datasource unconnected (metadata-only). */
+export interface DatasourceConnectDecision {
+  allow: boolean;
+  /** Human-readable reason, surfaced in logs when a connect is denied. */
+  reason?: string;
+}
+
+/** The minimal datasource shape a policy inspects (never a secret). */
+export interface DatasourceConnectSubject {
+  name: string;
+  driver: string;
+  schemaMode?: 'managed' | 'external' | 'validate-only';
+  external?: Record<string, unknown>;
+}
+
+/** Host-provided policy gate consulted before opening a connection. */
+export interface DatasourceConnectPolicy {
+  /**
+   * Decide whether `ds` may be connected. Sync or async. Throwing is treated
+   * as a denial (fail-closed) by {@link DatasourceConnectionService}.
+   */
+  canConnect(
+    ds: DatasourceConnectSubject,
+    ctx?: DatasourceConnectContext,
+  ): DatasourceConnectDecision | Promise<DatasourceConnectDecision>;
+}
+
+/**
+ * Open-core default: allow every connect. The D2 auto-connect gate (external /
+ * explicitly-routed / `autoConnect:true`) still applies on top of this for
+ * code-defined datasources, so a managed, unrouted datasource is never
+ * connected even under the permissive policy.
+ */
+export const allowAllConnectPolicy: DatasourceConnectPolicy = {
+  canConnect: () => ({ allow: true }),
+};

package/src/contracts/index.ts

@@ -16,3 +16,14 @@ export type {
   DatasourceDriverHandle,
   IDatasourceDriverFactory,
 } from './datasource-driver-factory.js';
+
+// Host-injectable connect policy (ADR-0062 D5 / epic #2163 seam).
+export {
+  allowAllConnectPolicy,
+} from './connect-policy.js';
+export type {
+  DatasourceConnectPolicy,
+  DatasourceConnectDecision,
+  DatasourceConnectContext,
+  DatasourceConnectSubject,
+} from './connect-policy.js';

package/src/datasource-admin-plugin.ts

@@ -4,7 +4,6 @@ import type { Plugin, PluginContext } from '@objectstack/core';
 import { registerMetadataTypeActions } from '@objectstack/spec/kernel';
 import type {
   IDatasourceDriverFactory,
-  DatasourceConnectionSpec,
   TestConnectionResult,
 } from './contracts/index.js';
 import {
@@ -13,6 +12,11 @@ import {
   type StoredDatasource,
   type ProbeInput,
 } from './datasource-admin-service.js';
+import {
+  DatasourceConnectionService,
+  type ConnectionEngineLike,
+} from './datasource-connection-service.js';
+import type { DatasourceConnectPolicy } from './contracts/connect-policy.js';
 import type { Logger } from './logger.js';
 
 /**
@@ -135,6 +139,13 @@ export interface DatasourceAdminServicePluginOptions {
   secrets?: SecretBinder;
   /** Override the driver factory (defaults to the `'datasource-driver-factory'` service). */
   driverFactory?: IDatasourceDriverFactory;
+  /**
+   * Host-injectable connect policy consulted before opening any datasource
+   * connection (ADR-0062 D5 / epic #2163 seam). Open-core default is permissive
+   * (allow); a multi-tenant host binds a stricter, fail-closed policy. Shared by
+   * both code-defined auto-connect and runtime-admin pool registration.
+   */
+  connectPolicy?: DatasourceConnectPolicy;
   logger?: Logger;
 }
 
@@ -162,6 +173,8 @@ export class DatasourceAdminServicePlugin implements Plugin {
 
   private service?: DatasourceAdminService;
   private config?: DatasourceAdminServiceConfig;
+  /** Shared "definition → live driver" path (ADR-0062 D1); also exposed as the `'datasource-connection'` service. */
+  private connection?: DatasourceConnectionService;
   private readonly options: DatasourceAdminServicePluginOptions;
 
   constructor(options: DatasourceAdminServicePluginOptions = {}) {
@@ -204,6 +217,19 @@ export class DatasourceAdminServicePlugin implements Plugin {
     const factory = (): IDatasourceDriverFactory | undefined =>
       this.options.driverFactory ?? safeGetService<IDatasourceDriverFactory>(ctx, 'datasource-driver-factory');
 
+    // The single "definition → live driver" path (ADR-0062 D1). Built here so
+    // the admin pool registration (runtime origin) and the app-plugin
+    // auto-connect (code origin) share one connect + lifecycle + policy path.
+    // Registered as a kernel service so `AppPlugin.start()` can resolve it.
+    this.connection = new DatasourceConnectionService({
+      factory,
+      engine: () => engineOf() as ConnectionEngineLike | undefined,
+      secrets: { resolve: (ref) => this.options.secrets?.resolve?.(ref) ?? Promise.resolve(undefined) },
+      policy: this.options.connectPolicy,
+      logger: this.options.logger,
+    });
+    ctx.registerService('datasource-connection', this.connection);
+
     const config: DatasourceAdminServiceConfig = {
       probe: (input) => this.probe(factory(), input),
 
@@ -261,40 +287,21 @@ export class DatasourceAdminServicePlugin implements Plugin {
         return objects.filter((o) => o?.datasource === datasource).length;
       },
 
+      // Hot pool (de)registration converges on the shared
+      // DatasourceConnectionService (ADR-0062 D1) — one connect path for code-
+      // and runtime-origin datasources. `connect()` builds the driver via the
+      // factory, dereferences `external.credentialsRef` through the SecretBinder,
+      // opens the connection, and registers the live driver + datasource def.
+      // Runtime-admin connects always degrade-with-warning on failure (never
+      // fail-fast), preserving the pre-ADR-0062 admin behavior.
       registerPool: async (record) => {
-        const f = factory();
-        const engine = engineOf();
-        if (!f || !engine?.registerDriver || !f.supports(record.driver)) return;
-        // Recover the cleartext credential from `sys_secret` so the pool opens
-        // with the real password. The cleartext is never persisted on the
-        // record (only `credentialsRef`), so it must be dereferenced here —
-        // both on create/update and on boot rehydration. Credential-less
-        // drivers (sqlite/memory) simply have no ref and skip this.
-        const credentialsRef = record.external?.credentialsRef;
-        const secret = credentialsRef ? await this.options.secrets?.resolve?.(credentialsRef) : undefined;
-        const handle = await f.create({ ...this.toSpec(record), ...(secret ? { secret } : {}) });
-        if (typeof handle?.connect === 'function') await handle.connect();
-        // The engine routes a datasource to a driver by `driver.name === <datasource name>`
-        // (see ObjectQL engine.getDriver). Prefer the factory's underlying engine
-        // driver (the `driver` escape hatch); fall back to the handle itself. Stamp
-        // the name so routing resolves to this pool.
-        const engineDriver = (handle.driver ?? handle) as { name?: string };
-        try {
-          engineDriver.name = record.name;
-        } catch {
-          /* frozen driver — registration may still work if name already matches */
-        }
-        engine.registerDriver(engineDriver);
-        engine.registerDatasourceDef?.({
-          name: record.name,
-          schemaMode: record.schemaMode,
-          external: record.external as { allowWrites?: boolean } | undefined,
+        await this.connection?.connect(record, {
+          context: { origin: record.origin ?? 'runtime', trigger: 'runtime-admin' },
         });
       },
 
       unregisterPool: async (name) => {
-        const driver = engineOf()?.getDriverByName?.(name) as { disconnect?: () => Promise<void> } | undefined;
-        if (typeof driver?.disconnect === 'function') await driver.disconnect();
+        await this.connection?.disconnect(name);
       },
 
       logger,
@@ -426,16 +433,6 @@ export class DatasourceAdminServicePlugin implements Plugin {
 
   // --- internals -----------------------------------------------------------
 
-  private toSpec(record: StoredDatasource): DatasourceConnectionSpec {
-    return {
-      name: record.name,
-      driver: record.driver,
-      config: record.config ?? {},
-      external: record.external,
-      pool: record.pool,
-    };
-  }
-
   /** Probe a connection via the driver factory: build → connect → ping → close. */
   private async probe(
     factory: IDatasourceDriverFactory | undefined,

package/src/datasource-admin-service.ts

@@ -47,6 +47,8 @@ export interface StoredDatasource {
   external?: (Record<string, unknown> & { credentialsRef?: string }) | undefined;
   pool?: Record<string, unknown>;
   active?: boolean;
+  /** Force a live connection at boot even when managed + unrouted (ADR-0062 D2(c)). */
+  autoConnect?: boolean;
   origin?: 'code' | 'runtime';
   /** Package that defines a code-origin datasource, when known. */
   definedIn?: string;