@objectstack/service-datasource 9.11.0 → 10.2.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { IExternalDatasourceService, IntrospectedSchema, RemoteTable, GenerateDraftOpts, ObjectDraft, ImportObjectOpts, ImportObjectResult, SchemaValidationResult, SchemaValidationReport, ICryptoProvider, IHttpServer } from '@objectstack/spec/contracts';
 import { ExternalCatalog } from '@objectstack/spec/data';
 import { Plugin, PluginContext } from '@objectstack/core';
-import { IDatasourceAdminService, TestConnectionResult, SecretInput, DatasourceSummary, DatasourceDraft, IDatasourceDriverFactory } from './contracts/index.cjs';
-export { DatasourceConnectionSpec, DatasourceDriverHandle, DatasourceOrigin } from './contracts/index.cjs';
+import { IDatasourceDriverFactory, DatasourceConnectPolicy, DatasourceConnectContext, IDatasourceAdminService, TestConnectionResult, SecretInput, DatasourceSummary, DatasourceDraft } from './contracts/index.cjs';
+export { DatasourceConnectDecision, DatasourceConnectSubject, DatasourceConnectionSpec, DatasourceDriverHandle, DatasourceOrigin, allowAllConnectPolicy } from './contracts/index.cjs';
 
 /**
  * ExternalDatasourceService — implements {@link IExternalDatasourceService}
@@ -81,6 +81,21 @@ declare class ExternalDatasourceService implements IExternalDatasourceService {
     listRemoteTables(datasource: string, opts?: {
         schema?: string;
     }): Promise<RemoteTable[]>;
+    /**
+     * Probe a *saved* datasource by name with a live round-trip. Reuses the
+     * introspection path (driver connect + schema read) as a cheap connectivity
+     * check, so the secret is resolved through the same wired pool as the rest of
+     * the introspection surface — the caller never handles cleartext. Returns a
+     * structured result rather than throwing so the route can render ok/error
+     * uniformly. This backs the `datasource` `test_connection` action
+     * (`POST /datasources/:name/test`).
+     */
+    testConnection(datasource: string): Promise<{
+        ok: boolean;
+        latencyMs?: number;
+        tableCount?: number;
+        error?: string;
+    }>;
     generateObjectDraft(datasource: string, remoteName: string, opts?: GenerateDraftOpts): Promise<ObjectDraft>;
     importObject(datasource: string, remoteName: string, opts?: ImportObjectOpts): Promise<ImportObjectResult>;
     refreshCatalog(datasource: string): Promise<ExternalCatalog>;
@@ -122,6 +137,168 @@ declare class ExternalDatasourceServicePlugin implements Plugin {
 interface Logger {
     warn: (message: string, meta?: unknown) => void;
     info?: (message: string, meta?: unknown) => void;
+    debug?: (message: string, meta?: unknown) => void;
+    error?: (message: string, meta?: unknown) => void;
+}
+
+/**
+ * DatasourceConnectionService — the single "definition → live driver" path
+ * (ADR-0062 D1).
+ *
+ * Given a datasource definition, it: consults the injectable connect policy
+ * (D5/epic seam), builds a driver via the host-provided driver factory,
+ * resolves any `external.credentialsRef` to a cleartext secret via the
+ * `SecretBinder` (D3, wired in Phase 2), opens the connection, and registers
+ * the live driver + the datasource *definition* into the ObjectQL engine under
+ * the datasource name (the engine routes by `driver.name === <datasource>`).
+ *
+ * Both origins converge here (D1):
+ *  - **code-defined** datasources auto-connect at boot via
+ *    {@link connectDeclared} (gated per D2 — see {@link isDatasourceAddressed}),
+ *    called from `AppPlugin.start()`.
+ *  - **runtime** (UI-created) datasources connect via {@link connect}, called
+ *    from `DatasourceAdminServicePlugin`'s `registerPool` (create/update + boot
+ *    rehydration).
+ *
+ * Idempotent: a datasource already registered as a live driver is skipped, so
+ * an app's legacy `onEnable` driver registration (the escape hatch, ADR-0062
+ * D8) and auto-connect never double-register.
+ */
+
+/** A datasource definition this service can connect (code- or runtime-origin). */
+interface ConnectableDatasource {
+    name: string;
+    label?: string;
+    driver: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    config?: Record<string, unknown>;
+    external?: (Record<string, unknown> & {
+        credentialsRef?: string;
+        validation?: {
+            onMismatch?: 'fail' | 'warn' | 'ignore';
+        };
+    }) | undefined;
+    pool?: Record<string, unknown>;
+    active?: boolean;
+    origin?: 'code' | 'runtime';
+    /**
+     * ADR-0062 D2(c): explicit opt-in to auto-connect even for a managed,
+     * unrouted datasource. Defaults to false.
+     */
+    autoConnect?: boolean;
+}
+/** Minimal object shape used for the D2 routing gate + post-connect schema sync. */
+interface DatasourceBoundObject {
+    name?: string;
+    /** The object's explicit `datasource` binding (ADR-0015 federation). */
+    datasource?: string;
+}
+/** Engine surface this service drives (the ObjectQL `'data'` engine). */
+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>;
+}
+/** Secret dereference surface (the `SecretBinder.resolve`, Phase 2 / D3). */
+interface ConnectionSecretResolver {
+    resolve?: (credentialsRef: string) => Promise<string | undefined>;
+}
+interface DatasourceConnectionServiceConfig {
+    /** Resolve the host driver factory (lazy — may be registered after init). */
+    factory: () => IDatasourceDriverFactory | undefined;
+    /** Resolve the ObjectQL engine (lazy). */
+    engine: () => ConnectionEngineLike | undefined;
+    /** Dereference `credentialsRef` → cleartext (Phase 2). Optional in Phase 1. */
+    secrets?: ConnectionSecretResolver;
+    /** Injectable connect policy. Defaults to {@link allowAllConnectPolicy}. */
+    policy?: DatasourceConnectPolicy;
+    logger?: Logger;
+}
+/** Outcome of a single {@link DatasourceConnectionService.connect} attempt. */
+type ConnectStatus = 'connected' | 'already-registered' | 'skipped-policy' | 'skipped-no-infra' | 'skipped-unsupported' | 'failed-credentials' | 'failed-degraded';
+interface ConnectResult {
+    name: string;
+    status: ConnectStatus;
+    reason?: string;
+}
+/**
+ * ADR-0062 D2 — is this declared datasource "meaningfully addressed", such that
+ * auto-connecting it is safe and intended?
+ *
+ * Returns true when:
+ *  - (a) it is external (`schemaMode !== 'managed'`), OR
+ *  - (b) some object **explicitly** binds to it (`object.datasource === name`), OR
+ *  - (c) it sets `autoConnect: true`.
+ *
+ * Deliberately NOT triggered by a `datasourceMapping` rule alone. A managed
+ * datasource that is only *mapped* (namespace/package/default) but has no live
+ * driver historically falls through to the `default` driver at query time
+ * (`engine.getDriver` step 4) — e.g. `examples/app-crm`'s `crm_primary`
+ * (`:memory:`, mapped + default-fallback, no `onEnable`). Connecting it would
+ * divert those objects to a fresh, empty connection and silently change app
+ * behavior. So mapping-only routing to a *managed* datasource is treated as
+ * decorative, keeping existing apps byte-for-byte unchanged (D2's load-bearing
+ * backward-compat guarantee). External datasources and explicit
+ * `object.datasource` bindings never resolved to `default` (they throw when
+ * unregistered), so auto-connecting them is a strict improvement, not a change.
+ */
+declare function isDatasourceAddressed(ds: Pick<ConnectableDatasource, 'name' | 'schemaMode' | 'autoConnect'>, ctx: {
+    objects?: readonly DatasourceBoundObject[];
+}): boolean;
+declare class DatasourceConnectionService {
+    private readonly cfg;
+    private readonly policy;
+    private readonly logger?;
+    constructor(cfg: DatasourceConnectionServiceConfig);
+    /**
+     * Auto-connect the declared (code-defined) datasources that pass the D2 gate.
+     * Called from `AppPlugin.start()` with the app bundle's datasources + objects.
+     * Each connected external datasource also has its bound objects' read metadata
+     * synced so they are immediately queryable with zero app code.
+     */
+    connectDeclared(input: {
+        datasources: readonly ConnectableDatasource[];
+        objects?: readonly DatasourceBoundObject[];
+    }): Promise<ConnectResult[]>;
+    /**
+     * Build + connect + register a single datasource's live driver. The shared
+     * core used by both auto-connect and the runtime-admin pool registration.
+     *
+     * Failure policy (ADR-0062 D5): an `external` datasource with
+     * `validation.onMismatch: 'fail'` fails fast (re-throws, bricking boot as
+     * intended); everything else degrades with a warning so an optional replica's
+     * connectivity blip never bricks boot.
+     */
+    connect(record: ConnectableDatasource, opts?: {
+        objects?: readonly string[];
+        context?: DatasourceConnectContext;
+    }): Promise<ConnectResult>;
+    /** Gracefully disconnect a previously-registered datasource pool. */
+    disconnect(name: string): Promise<void>;
+    /**
+     * Apply the D5 connect-failure policy (also covers D3 credential failures). A
+     * code-defined `external` datasource with `onMismatch:'fail'` auto-connected at
+     * boot re-throws (fail-fast, bricking boot as intended). Runtime-admin
+     * create/update + boot rehydration always degrade-with-warning — a UI action
+     * or a replica blip must never brick the running server (preserves the
+     * pre-ADR-0062 admin behavior). Either way the datasource is left unconnected
+     * with a clear message — never a silent skip.
+     */
+    private handleFailure;
 }
 
 /**
@@ -161,6 +338,8 @@ interface StoredDatasource {
     }) | 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;
@@ -209,6 +388,17 @@ declare class DatasourceAdminService implements IDatasourceAdminService {
     constructor(config: DatasourceAdminServiceConfig);
     private get logger();
     listDatasources(): Promise<DatasourceSummary[]>;
+    /**
+     * Read one datasource's full detail for editing, with the credential stripped.
+     * Returns `config` (non-sensitive — credentials live in `sys_secret`, never in
+     * config), `origin`, and a `hasSecret` flag so the UI can show "leave blank to
+     * keep" without ever receiving the `credentialsRef` or any cleartext. Returns
+     * `undefined` when the name is unknown.
+     */
+    getDatasource(name: string): Promise<(Pick<StoredDatasource, 'name' | 'label' | 'driver' | 'schemaMode' | 'config' | 'active' | 'definedIn'> & {
+        origin: 'code' | 'runtime';
+        hasSecret: boolean;
+    }) | undefined>;
     testConnection(input: DatasourceDraft, secret?: SecretInput): Promise<TestConnectionResult>;
     createDatasource(input: DatasourceDraft, secret?: SecretInput): Promise<DatasourceSummary>;
     updateDatasource(name: string, patch: Partial<DatasourceDraft>, secret?: SecretInput): Promise<DatasourceSummary>;
@@ -250,6 +440,13 @@ 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;
 }
 /**
@@ -275,10 +472,14 @@ declare class DatasourceAdminServicePlugin implements Plugin {
     dependencies: string[];
     private service?;
     private config?;
+    /** Shared "definition → live driver" path (ADR-0062 D1); also exposed as the `'datasource-connection'` service. */
+    private connection?;
     private readonly options;
     constructor(options?: DatasourceAdminServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /** Reload persisted runtime datasource rows (sys_metadata) into the registry. */
+    private restoreRuntimeDatasources;
     /**
      * Boot-time rehydration: list persisted runtime datasources and re-register
      * each one's connection pool (driver build → connect → registerDriver),
@@ -290,7 +491,6 @@ declare class DatasourceAdminServicePlugin implements Plugin {
      */
     private rehydratePools;
     destroy(): Promise<void>;
-    private toSpec;
     /** Probe a connection via the driver factory: build → connect → ping → close. */
     private probe;
 }
@@ -411,4 +611,4 @@ declare function createDatasourceSecretBinder(deps: DatasourceSecretBinderDeps):
  */
 declare function registerDatasourceAdminRoutes(server: IHttpServer, ctx: PluginContext, basePath?: string): void;
 
-export { DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, type ObjectLike, type ProbeInput, type SecretBinder, SecretInput, type SecretStoreEngineLike, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, parseCredentialsRef, registerDatasourceAdminRoutes, toCredentialsRef };
+export { type ConnectResult, type ConnectStatus, type ConnectableDatasource, type ConnectionEngineLike, type ConnectionSecretResolver, DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, type DatasourceBoundObject, DatasourceConnectContext, DatasourceConnectPolicy, DatasourceConnectionService, type DatasourceConnectionServiceConfig, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, type ObjectLike, type ProbeInput, type SecretBinder, SecretInput, type SecretStoreEngineLike, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, toCredentialsRef };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { IExternalDatasourceService, IntrospectedSchema, RemoteTable, GenerateDraftOpts, ObjectDraft, ImportObjectOpts, ImportObjectResult, SchemaValidationResult, SchemaValidationReport, ICryptoProvider, IHttpServer } from '@objectstack/spec/contracts';
 import { ExternalCatalog } from '@objectstack/spec/data';
 import { Plugin, PluginContext } from '@objectstack/core';
-import { IDatasourceAdminService, TestConnectionResult, SecretInput, DatasourceSummary, DatasourceDraft, IDatasourceDriverFactory } from './contracts/index.js';
-export { DatasourceConnectionSpec, DatasourceDriverHandle, DatasourceOrigin } from './contracts/index.js';
+import { IDatasourceDriverFactory, DatasourceConnectPolicy, DatasourceConnectContext, IDatasourceAdminService, TestConnectionResult, SecretInput, DatasourceSummary, DatasourceDraft } from './contracts/index.js';
+export { DatasourceConnectDecision, DatasourceConnectSubject, DatasourceConnectionSpec, DatasourceDriverHandle, DatasourceOrigin, allowAllConnectPolicy } from './contracts/index.js';
 
 /**
  * ExternalDatasourceService — implements {@link IExternalDatasourceService}
@@ -81,6 +81,21 @@ declare class ExternalDatasourceService implements IExternalDatasourceService {
     listRemoteTables(datasource: string, opts?: {
         schema?: string;
     }): Promise<RemoteTable[]>;
+    /**
+     * Probe a *saved* datasource by name with a live round-trip. Reuses the
+     * introspection path (driver connect + schema read) as a cheap connectivity
+     * check, so the secret is resolved through the same wired pool as the rest of
+     * the introspection surface — the caller never handles cleartext. Returns a
+     * structured result rather than throwing so the route can render ok/error
+     * uniformly. This backs the `datasource` `test_connection` action
+     * (`POST /datasources/:name/test`).
+     */
+    testConnection(datasource: string): Promise<{
+        ok: boolean;
+        latencyMs?: number;
+        tableCount?: number;
+        error?: string;
+    }>;
     generateObjectDraft(datasource: string, remoteName: string, opts?: GenerateDraftOpts): Promise<ObjectDraft>;
     importObject(datasource: string, remoteName: string, opts?: ImportObjectOpts): Promise<ImportObjectResult>;
     refreshCatalog(datasource: string): Promise<ExternalCatalog>;
@@ -122,6 +137,168 @@ declare class ExternalDatasourceServicePlugin implements Plugin {
 interface Logger {
     warn: (message: string, meta?: unknown) => void;
     info?: (message: string, meta?: unknown) => void;
+    debug?: (message: string, meta?: unknown) => void;
+    error?: (message: string, meta?: unknown) => void;
+}
+
+/**
+ * DatasourceConnectionService — the single "definition → live driver" path
+ * (ADR-0062 D1).
+ *
+ * Given a datasource definition, it: consults the injectable connect policy
+ * (D5/epic seam), builds a driver via the host-provided driver factory,
+ * resolves any `external.credentialsRef` to a cleartext secret via the
+ * `SecretBinder` (D3, wired in Phase 2), opens the connection, and registers
+ * the live driver + the datasource *definition* into the ObjectQL engine under
+ * the datasource name (the engine routes by `driver.name === <datasource>`).
+ *
+ * Both origins converge here (D1):
+ *  - **code-defined** datasources auto-connect at boot via
+ *    {@link connectDeclared} (gated per D2 — see {@link isDatasourceAddressed}),
+ *    called from `AppPlugin.start()`.
+ *  - **runtime** (UI-created) datasources connect via {@link connect}, called
+ *    from `DatasourceAdminServicePlugin`'s `registerPool` (create/update + boot
+ *    rehydration).
+ *
+ * Idempotent: a datasource already registered as a live driver is skipped, so
+ * an app's legacy `onEnable` driver registration (the escape hatch, ADR-0062
+ * D8) and auto-connect never double-register.
+ */
+
+/** A datasource definition this service can connect (code- or runtime-origin). */
+interface ConnectableDatasource {
+    name: string;
+    label?: string;
+    driver: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    config?: Record<string, unknown>;
+    external?: (Record<string, unknown> & {
+        credentialsRef?: string;
+        validation?: {
+            onMismatch?: 'fail' | 'warn' | 'ignore';
+        };
+    }) | undefined;
+    pool?: Record<string, unknown>;
+    active?: boolean;
+    origin?: 'code' | 'runtime';
+    /**
+     * ADR-0062 D2(c): explicit opt-in to auto-connect even for a managed,
+     * unrouted datasource. Defaults to false.
+     */
+    autoConnect?: boolean;
+}
+/** Minimal object shape used for the D2 routing gate + post-connect schema sync. */
+interface DatasourceBoundObject {
+    name?: string;
+    /** The object's explicit `datasource` binding (ADR-0015 federation). */
+    datasource?: string;
+}
+/** Engine surface this service drives (the ObjectQL `'data'` engine). */
+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>;
+}
+/** Secret dereference surface (the `SecretBinder.resolve`, Phase 2 / D3). */
+interface ConnectionSecretResolver {
+    resolve?: (credentialsRef: string) => Promise<string | undefined>;
+}
+interface DatasourceConnectionServiceConfig {
+    /** Resolve the host driver factory (lazy — may be registered after init). */
+    factory: () => IDatasourceDriverFactory | undefined;
+    /** Resolve the ObjectQL engine (lazy). */
+    engine: () => ConnectionEngineLike | undefined;
+    /** Dereference `credentialsRef` → cleartext (Phase 2). Optional in Phase 1. */
+    secrets?: ConnectionSecretResolver;
+    /** Injectable connect policy. Defaults to {@link allowAllConnectPolicy}. */
+    policy?: DatasourceConnectPolicy;
+    logger?: Logger;
+}
+/** Outcome of a single {@link DatasourceConnectionService.connect} attempt. */
+type ConnectStatus = 'connected' | 'already-registered' | 'skipped-policy' | 'skipped-no-infra' | 'skipped-unsupported' | 'failed-credentials' | 'failed-degraded';
+interface ConnectResult {
+    name: string;
+    status: ConnectStatus;
+    reason?: string;
+}
+/**
+ * ADR-0062 D2 — is this declared datasource "meaningfully addressed", such that
+ * auto-connecting it is safe and intended?
+ *
+ * Returns true when:
+ *  - (a) it is external (`schemaMode !== 'managed'`), OR
+ *  - (b) some object **explicitly** binds to it (`object.datasource === name`), OR
+ *  - (c) it sets `autoConnect: true`.
+ *
+ * Deliberately NOT triggered by a `datasourceMapping` rule alone. A managed
+ * datasource that is only *mapped* (namespace/package/default) but has no live
+ * driver historically falls through to the `default` driver at query time
+ * (`engine.getDriver` step 4) — e.g. `examples/app-crm`'s `crm_primary`
+ * (`:memory:`, mapped + default-fallback, no `onEnable`). Connecting it would
+ * divert those objects to a fresh, empty connection and silently change app
+ * behavior. So mapping-only routing to a *managed* datasource is treated as
+ * decorative, keeping existing apps byte-for-byte unchanged (D2's load-bearing
+ * backward-compat guarantee). External datasources and explicit
+ * `object.datasource` bindings never resolved to `default` (they throw when
+ * unregistered), so auto-connecting them is a strict improvement, not a change.
+ */
+declare function isDatasourceAddressed(ds: Pick<ConnectableDatasource, 'name' | 'schemaMode' | 'autoConnect'>, ctx: {
+    objects?: readonly DatasourceBoundObject[];
+}): boolean;
+declare class DatasourceConnectionService {
+    private readonly cfg;
+    private readonly policy;
+    private readonly logger?;
+    constructor(cfg: DatasourceConnectionServiceConfig);
+    /**
+     * Auto-connect the declared (code-defined) datasources that pass the D2 gate.
+     * Called from `AppPlugin.start()` with the app bundle's datasources + objects.
+     * Each connected external datasource also has its bound objects' read metadata
+     * synced so they are immediately queryable with zero app code.
+     */
+    connectDeclared(input: {
+        datasources: readonly ConnectableDatasource[];
+        objects?: readonly DatasourceBoundObject[];
+    }): Promise<ConnectResult[]>;
+    /**
+     * Build + connect + register a single datasource's live driver. The shared
+     * core used by both auto-connect and the runtime-admin pool registration.
+     *
+     * Failure policy (ADR-0062 D5): an `external` datasource with
+     * `validation.onMismatch: 'fail'` fails fast (re-throws, bricking boot as
+     * intended); everything else degrades with a warning so an optional replica's
+     * connectivity blip never bricks boot.
+     */
+    connect(record: ConnectableDatasource, opts?: {
+        objects?: readonly string[];
+        context?: DatasourceConnectContext;
+    }): Promise<ConnectResult>;
+    /** Gracefully disconnect a previously-registered datasource pool. */
+    disconnect(name: string): Promise<void>;
+    /**
+     * Apply the D5 connect-failure policy (also covers D3 credential failures). A
+     * code-defined `external` datasource with `onMismatch:'fail'` auto-connected at
+     * boot re-throws (fail-fast, bricking boot as intended). Runtime-admin
+     * create/update + boot rehydration always degrade-with-warning — a UI action
+     * or a replica blip must never brick the running server (preserves the
+     * pre-ADR-0062 admin behavior). Either way the datasource is left unconnected
+     * with a clear message — never a silent skip.
+     */
+    private handleFailure;
 }
 
 /**
@@ -161,6 +338,8 @@ interface StoredDatasource {
     }) | 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;
@@ -209,6 +388,17 @@ declare class DatasourceAdminService implements IDatasourceAdminService {
     constructor(config: DatasourceAdminServiceConfig);
     private get logger();
     listDatasources(): Promise<DatasourceSummary[]>;
+    /**
+     * Read one datasource's full detail for editing, with the credential stripped.
+     * Returns `config` (non-sensitive — credentials live in `sys_secret`, never in
+     * config), `origin`, and a `hasSecret` flag so the UI can show "leave blank to
+     * keep" without ever receiving the `credentialsRef` or any cleartext. Returns
+     * `undefined` when the name is unknown.
+     */
+    getDatasource(name: string): Promise<(Pick<StoredDatasource, 'name' | 'label' | 'driver' | 'schemaMode' | 'config' | 'active' | 'definedIn'> & {
+        origin: 'code' | 'runtime';
+        hasSecret: boolean;
+    }) | undefined>;
     testConnection(input: DatasourceDraft, secret?: SecretInput): Promise<TestConnectionResult>;
     createDatasource(input: DatasourceDraft, secret?: SecretInput): Promise<DatasourceSummary>;
     updateDatasource(name: string, patch: Partial<DatasourceDraft>, secret?: SecretInput): Promise<DatasourceSummary>;
@@ -250,6 +440,13 @@ 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;
 }
 /**
@@ -275,10 +472,14 @@ declare class DatasourceAdminServicePlugin implements Plugin {
     dependencies: string[];
     private service?;
     private config?;
+    /** Shared "definition → live driver" path (ADR-0062 D1); also exposed as the `'datasource-connection'` service. */
+    private connection?;
     private readonly options;
     constructor(options?: DatasourceAdminServicePluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
+    /** Reload persisted runtime datasource rows (sys_metadata) into the registry. */
+    private restoreRuntimeDatasources;
     /**
      * Boot-time rehydration: list persisted runtime datasources and re-register
      * each one's connection pool (driver build → connect → registerDriver),
@@ -290,7 +491,6 @@ declare class DatasourceAdminServicePlugin implements Plugin {
      */
     private rehydratePools;
     destroy(): Promise<void>;
-    private toSpec;
     /** Probe a connection via the driver factory: build → connect → ping → close. */
     private probe;
 }
@@ -411,4 +611,4 @@ declare function createDatasourceSecretBinder(deps: DatasourceSecretBinderDeps):
  */
 declare function registerDatasourceAdminRoutes(server: IHttpServer, ctx: PluginContext, basePath?: string): void;
 
-export { DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, type ObjectLike, type ProbeInput, type SecretBinder, SecretInput, type SecretStoreEngineLike, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, parseCredentialsRef, registerDatasourceAdminRoutes, toCredentialsRef };
+export { type ConnectResult, type ConnectStatus, type ConnectableDatasource, type ConnectionEngineLike, type ConnectionSecretResolver, DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, type DatasourceBoundObject, DatasourceConnectContext, DatasourceConnectPolicy, DatasourceConnectionService, type DatasourceConnectionServiceConfig, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, type ObjectLike, type ProbeInput, type SecretBinder, SecretInput, type SecretStoreEngineLike, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, toCredentialsRef };