@objectstack/service-datasource 10.0.0 → 10.3.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}
@@ -137,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;
 }
 
 /**
@@ -176,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;
@@ -276,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;
 }
 /**
@@ -301,6 +472,8 @@ 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>;
@@ -318,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;
 }
@@ -351,7 +523,100 @@ declare class DatasourceAdminServicePlugin implements Plugin {
  * lazily so a host that never builds (e.g.) a mongo connection doesn't pay for
  * the mongo SDK.
  */
-declare function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory;
+interface DefaultDatasourceDriverFactoryOptions {
+    /**
+     * Enables the dev-only native-`better-sqlite3` → wasm → in-memory step-down
+     * for sqlite construction (#2229). When omitted, defaults per call to
+     * `process.env.NODE_ENV === 'development'`. In production a native load
+     * failure is NOT silently swapped for a different engine (fail-closed).
+     */
+    dev?: boolean;
+}
+declare function createDefaultDatasourceDriverFactory(options?: DefaultDatasourceDriverFactoryOptions): IDatasourceDriverFactory;
+
+/**
+ * Shared native-`better-sqlite3` → wasm SQLite → in-memory step-down for any
+ * sqlite-via-`better-sqlite3` construction (issue #2229).
+ *
+ * ## Why a probe is necessary
+ *
+ * `better-sqlite3` loads its native `.node` addon LAZILY — not at
+ * `require('better-sqlite3')`, and not even at knex construction, but at the
+ * first pool-connection acquire (`new Database(file)`), i.e. the first query.
+ * So an ABI mismatch (a cached prebuilt binary built for a different Node
+ * version — `NODE_MODULE_VERSION` mismatch) is invisible at boot and only
+ * surfaces much later as a runtime `Find operation failed` on the first read.
+ *
+ * This helper makes the failure observable up-front by actively probing: it
+ * opens a connection and runs a cheap `SELECT 1`, which forces the native addon
+ * to load. (`connect()` alone is NOT a reliable probe: for SQLite it only runs
+ * `mkdir` + a `PRAGMA` whose error is swallowed internally — so we additionally
+ * issue a raw `SELECT 1`, which propagates the load error.) On failure it steps
+ * down:
+ *
+ *   1. native `better-sqlite3`  — fast, real SQL
+ *   2. wasm SQLite              — pure-JS, real SQL + on-disk persistence, slower   [dev only]
+ *   3. in-memory (mingo)        — neither real SQL nor persistent                   [dev only, last resort]
+ *
+ * ## Dev vs production
+ *
+ * The wasm + in-memory step-down is GATED to dev. In production a native load
+ * failure is NOT silently swapped for a different engine: the error is re-thrown
+ * so it surfaces loudly (fail-closed) instead of an operator unknowingly running
+ * on wasm/mingo. This mirrors the existing `serve.ts` default-dev fallback and
+ * hoists it into one place shared by every sqlite construction site.
+ */
+/** Which engine the resolver ultimately produced. */
+type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';
+interface ResolveSqliteDriverOptions {
+    /**
+     * SQLite filename — `:memory:` for an ephemeral database, or an absolute /
+     * relative path for a persistent file. Preserved across the wasm fallback so
+     * a persistent `file:` database keeps its on-disk persistence through wasm.
+     * Pass the raw filename (callers strip any `file:` / `sqlite:` scheme first).
+     */
+    filename: string;
+    /**
+     * Gates the wasm + in-memory step-down. When `true` (dev) a native ABI/load
+     * failure steps down the chain with a warning. When `false` (production) the
+     * native driver is returned unprobed so a failure surfaces loudly at first use
+     * (fail-closed) — we never silently degrade behind the operator's back.
+     * Defaults to `process.env.NODE_ENV === 'development'`.
+     */
+    dev?: boolean;
+    /** Forwarded to the native SqlDriver (dev loosen-only self-heal, #2186). */
+    autoMigrate?: 'off' | 'safe';
+    /** Forwarded to the SQL drivers (external schema mode, ADR-0015). */
+    schemaMode?: string;
+    /**
+     * Warning sink for the step-down messages. Defaults to `console.warn`.
+     * `serve.ts` passes a `chalk.yellow` wrapper so the banner stays consistent.
+     */
+    warn?: (message: string) => void;
+}
+interface ResolvedSqliteDriver {
+    /** The concrete engine driver to register (e.g. via `DriverPlugin`). */
+    driver: any;
+    /** Which engine actually resolved. */
+    engine: SqliteFallbackEngine;
+    /** Banner label, matching `serve.ts`'s existing strings. */
+    label: string;
+}
+/**
+ * Warning emitted when native `better-sqlite3` is unavailable but wasm SQLite
+ * loads. Kept byte-for-byte identical to the original `serve.ts` text so the
+ * dev experience is the same regardless of which construction site triggers it.
+ */
+declare const NATIVE_SQLITE_WASM_FALLBACK_WARNING: string;
+/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */
+declare const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING: string;
+/**
+ * Probe a `better-sqlite3` SQLite construction and, in dev, step down to wasm
+ * SQLite (then in-memory) when the native addon cannot load.
+ *
+ * @see {@link ResolveSqliteDriverOptions}
+ */
+declare function resolveSqliteDriver(opts: ResolveSqliteDriverOptions): Promise<ResolvedSqliteDriver>;
 
 /**
  * Default datasource SecretBinder — persists a runtime datasource's cleartext
@@ -439,4 +704,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, NATIVE_SQLITE_MEMORY_FALLBACK_WARNING, NATIVE_SQLITE_WASM_FALLBACK_WARNING, type ObjectLike, type ProbeInput, type ResolveSqliteDriverOptions, type ResolvedSqliteDriver, type SecretBinder, SecretInput, type SecretStoreEngineLike, type SqliteFallbackEngine, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, resolveSqliteDriver, 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}
@@ -137,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;
 }
 
 /**
@@ -176,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;
@@ -276,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;
 }
 /**
@@ -301,6 +472,8 @@ 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>;
@@ -318,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;
 }
@@ -351,7 +523,100 @@ declare class DatasourceAdminServicePlugin implements Plugin {
  * lazily so a host that never builds (e.g.) a mongo connection doesn't pay for
  * the mongo SDK.
  */
-declare function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory;
+interface DefaultDatasourceDriverFactoryOptions {
+    /**
+     * Enables the dev-only native-`better-sqlite3` → wasm → in-memory step-down
+     * for sqlite construction (#2229). When omitted, defaults per call to
+     * `process.env.NODE_ENV === 'development'`. In production a native load
+     * failure is NOT silently swapped for a different engine (fail-closed).
+     */
+    dev?: boolean;
+}
+declare function createDefaultDatasourceDriverFactory(options?: DefaultDatasourceDriverFactoryOptions): IDatasourceDriverFactory;
+
+/**
+ * Shared native-`better-sqlite3` → wasm SQLite → in-memory step-down for any
+ * sqlite-via-`better-sqlite3` construction (issue #2229).
+ *
+ * ## Why a probe is necessary
+ *
+ * `better-sqlite3` loads its native `.node` addon LAZILY — not at
+ * `require('better-sqlite3')`, and not even at knex construction, but at the
+ * first pool-connection acquire (`new Database(file)`), i.e. the first query.
+ * So an ABI mismatch (a cached prebuilt binary built for a different Node
+ * version — `NODE_MODULE_VERSION` mismatch) is invisible at boot and only
+ * surfaces much later as a runtime `Find operation failed` on the first read.
+ *
+ * This helper makes the failure observable up-front by actively probing: it
+ * opens a connection and runs a cheap `SELECT 1`, which forces the native addon
+ * to load. (`connect()` alone is NOT a reliable probe: for SQLite it only runs
+ * `mkdir` + a `PRAGMA` whose error is swallowed internally — so we additionally
+ * issue a raw `SELECT 1`, which propagates the load error.) On failure it steps
+ * down:
+ *
+ *   1. native `better-sqlite3`  — fast, real SQL
+ *   2. wasm SQLite              — pure-JS, real SQL + on-disk persistence, slower   [dev only]
+ *   3. in-memory (mingo)        — neither real SQL nor persistent                   [dev only, last resort]
+ *
+ * ## Dev vs production
+ *
+ * The wasm + in-memory step-down is GATED to dev. In production a native load
+ * failure is NOT silently swapped for a different engine: the error is re-thrown
+ * so it surfaces loudly (fail-closed) instead of an operator unknowingly running
+ * on wasm/mingo. This mirrors the existing `serve.ts` default-dev fallback and
+ * hoists it into one place shared by every sqlite construction site.
+ */
+/** Which engine the resolver ultimately produced. */
+type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';
+interface ResolveSqliteDriverOptions {
+    /**
+     * SQLite filename — `:memory:` for an ephemeral database, or an absolute /
+     * relative path for a persistent file. Preserved across the wasm fallback so
+     * a persistent `file:` database keeps its on-disk persistence through wasm.
+     * Pass the raw filename (callers strip any `file:` / `sqlite:` scheme first).
+     */
+    filename: string;
+    /**
+     * Gates the wasm + in-memory step-down. When `true` (dev) a native ABI/load
+     * failure steps down the chain with a warning. When `false` (production) the
+     * native driver is returned unprobed so a failure surfaces loudly at first use
+     * (fail-closed) — we never silently degrade behind the operator's back.
+     * Defaults to `process.env.NODE_ENV === 'development'`.
+     */
+    dev?: boolean;
+    /** Forwarded to the native SqlDriver (dev loosen-only self-heal, #2186). */
+    autoMigrate?: 'off' | 'safe';
+    /** Forwarded to the SQL drivers (external schema mode, ADR-0015). */
+    schemaMode?: string;
+    /**
+     * Warning sink for the step-down messages. Defaults to `console.warn`.
+     * `serve.ts` passes a `chalk.yellow` wrapper so the banner stays consistent.
+     */
+    warn?: (message: string) => void;
+}
+interface ResolvedSqliteDriver {
+    /** The concrete engine driver to register (e.g. via `DriverPlugin`). */
+    driver: any;
+    /** Which engine actually resolved. */
+    engine: SqliteFallbackEngine;
+    /** Banner label, matching `serve.ts`'s existing strings. */
+    label: string;
+}
+/**
+ * Warning emitted when native `better-sqlite3` is unavailable but wasm SQLite
+ * loads. Kept byte-for-byte identical to the original `serve.ts` text so the
+ * dev experience is the same regardless of which construction site triggers it.
+ */
+declare const NATIVE_SQLITE_WASM_FALLBACK_WARNING: string;
+/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */
+declare const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING: string;
+/**
+ * Probe a `better-sqlite3` SQLite construction and, in dev, step down to wasm
+ * SQLite (then in-memory) when the native addon cannot load.
+ *
+ * @see {@link ResolveSqliteDriverOptions}
+ */
+declare function resolveSqliteDriver(opts: ResolveSqliteDriverOptions): Promise<ResolvedSqliteDriver>;
 
 /**
  * Default datasource SecretBinder — persists a runtime datasource's cleartext
@@ -439,4 +704,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, NATIVE_SQLITE_MEMORY_FALLBACK_WARNING, NATIVE_SQLITE_WASM_FALLBACK_WARNING, type ObjectLike, type ProbeInput, type ResolveSqliteDriverOptions, type ResolvedSqliteDriver, type SecretBinder, SecretInput, type SecretStoreEngineLike, type SqliteFallbackEngine, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, resolveSqliteDriver, toCredentialsRef };