@objectstack/service-datasource 10.0.0 → 10.3.0

package/src/datasource-connection-service.ts

@@ -0,0 +1,364 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * 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.
+ */
+
+import type {
+  IDatasourceDriverFactory,
+  DatasourceConnectionSpec,
+} from './contracts/datasource-driver-factory.js';
+import {
+  allowAllConnectPolicy,
+  type DatasourceConnectPolicy,
+  type DatasourceConnectContext,
+} from './contracts/connect-policy.js';
+import type { Logger } from './logger.js';
+
+/** A datasource definition this service can connect (code- or runtime-origin). */
+export 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. */
+export interface DatasourceBoundObject {
+  name?: string;
+  /** The object's explicit `datasource` binding (ADR-0015 federation). */
+  datasource?: string;
+}
+
+/** Engine surface this service drives (the ObjectQL `'data'` engine). */
+export interface ConnectionEngineLike {
+  registerDriver?: (driver: unknown, isDefault?: boolean) => void;
+  registerDatasourceDef?: (def: {
+    name: string;
+    schemaMode?: string;
+    external?: { allowWrites?: boolean };
+  }) => void;
+  getDriverByName?: (name: string) => unknown;
+  /**
+   * Register read metadata (DDL-free) for a federated object so its physical
+   * remote table/columns resolve for queries. Idempotent; called per bound
+   * external object after the driver is registered, because boot schema-sync
+   * ran before this driver existed (ADR-0015 §18; matches what the legacy
+   * `onEnable` bridge does manually).
+   */
+  syncObjectSchema?: (objectName: string) => Promise<void>;
+}
+
+/** Secret dereference surface (the `SecretBinder.resolve`, Phase 2 / D3). */
+export interface ConnectionSecretResolver {
+  resolve?: (credentialsRef: string) => Promise<string | undefined>;
+}
+
+export 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. */
+export type ConnectStatus =
+  | 'connected'
+  | 'already-registered'
+  | 'skipped-policy'
+  | 'skipped-no-infra'
+  | 'skipped-unsupported'
+  | 'failed-credentials'
+  | 'failed-degraded';
+
+export 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.
+ */
+export function isDatasourceAddressed(
+  ds: Pick<ConnectableDatasource, 'name' | 'schemaMode' | 'autoConnect'>,
+  ctx: { objects?: readonly DatasourceBoundObject[] },
+): boolean {
+  if (ds.schemaMode && ds.schemaMode !== 'managed') return true; // (a)
+  if (ds.autoConnect === true) return true; // (c)
+  if (ctx.objects?.some((o) => o?.datasource === ds.name)) return true; // (b)
+  return false;
+}
+
+export class DatasourceConnectionService {
+  private readonly cfg: DatasourceConnectionServiceConfig;
+  private readonly policy: DatasourceConnectPolicy;
+  private readonly logger?: Logger;
+
+  constructor(cfg: DatasourceConnectionServiceConfig) {
+    this.cfg = cfg;
+    this.policy = cfg.policy ?? allowAllConnectPolicy;
+    this.logger = cfg.logger;
+  }
+
+  /**
+   * 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.
+   */
+  async connectDeclared(input: {
+    datasources: readonly ConnectableDatasource[];
+    objects?: readonly DatasourceBoundObject[];
+  }): Promise<ConnectResult[]> {
+    const objects = input.objects ?? [];
+    const results: ConnectResult[] = [];
+    for (const ds of input.datasources) {
+      if (!ds?.name) continue;
+      if (ds.active === false) continue;
+      if (!isDatasourceAddressed(ds, { objects })) continue; // D2 gate
+      const bound = objects
+        .filter((o) => o?.datasource === ds.name && typeof o?.name === 'string')
+        .map((o) => o.name as string);
+      results.push(
+        await this.connect(ds, { objects: bound, context: { origin: ds.origin ?? 'code', trigger: 'declared-auto' } }),
+      );
+    }
+    return results;
+  }
+
+  /**
+   * 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.
+   */
+  async connect(
+    record: ConnectableDatasource,
+    opts: { objects?: readonly string[]; context?: DatasourceConnectContext } = {},
+  ): Promise<ConnectResult> {
+    const name = record.name;
+    const engine = this.cfg.engine();
+    const factory = this.cfg.factory();
+
+    // Idempotent: never double-register (e.g. a legacy `onEnable` bridge already
+    // registered this driver — the D8 escape hatch).
+    if (engine?.getDriverByName?.(name)) {
+      return { name, status: 'already-registered' };
+    }
+
+    // Policy gate (fail-closed on throw).
+    let decision;
+    try {
+      decision = await this.policy.canConnect(
+        { name, driver: record.driver, schemaMode: record.schemaMode, external: record.external },
+        opts.context,
+      );
+    } catch (err) {
+      decision = { allow: false, reason: `connect policy threw: ${errMsg(err)}` };
+    }
+    if (!decision.allow) {
+      this.logger?.info?.(`datasource '${name}': connect denied by policy${decision.reason ? ` (${decision.reason})` : ''}`);
+      return { name, status: 'skipped-policy', reason: decision.reason };
+    }
+
+    if (!factory || !engine?.registerDriver) {
+      this.logger?.debug?.(`datasource '${name}': no driver factory / engine — left metadata-only`);
+      return { name, status: 'skipped-no-infra' };
+    }
+    if (!factory.supports(record.driver)) {
+      return this.handleFailure(
+        record,
+        'skipped-unsupported',
+        `no driver factory supports driver '${record.driver}'`,
+        opts.context,
+      );
+    }
+
+    // Credential resolution (ADR-0062 D3) — FAIL-CLOSED, and done *before* the
+    // build try-block so a fail-fast verdict propagates (rather than being
+    // swallowed and re-classified by the catch below). A declared
+    // `external.credentialsRef` MUST resolve to a cleartext secret before we
+    // open a connection: building a driver without it would silently connect
+    // with no/wrong auth (or fail later with a confusing driver error). So an
+    // absent secret store, or an unresolvable/undecryptable ref, leaves the
+    // datasource unconnected with a clear message — never a silent skip.
+    let secret: string | undefined;
+    const credentialsRef = record.external?.credentialsRef;
+    if (credentialsRef) {
+      const resolver = this.cfg.secrets?.resolve;
+      if (!resolver) {
+        return this.handleFailure(
+          record,
+          'failed-credentials',
+          `requires credential '${credentialsRef}' but no secret store (SecretBinder/ICryptoProvider) is configured`,
+          opts.context,
+        );
+      }
+      try {
+        secret = await resolver(credentialsRef);
+      } catch (err) {
+        return this.handleFailure(record, 'failed-credentials', `resolving credential '${credentialsRef}' threw: ${errMsg(err)}`, opts.context);
+      }
+      if (secret == null || secret === '') {
+        return this.handleFailure(
+          record,
+          'failed-credentials',
+          `credential '${credentialsRef}' could not be resolved or decrypted (missing sys_secret row, or the encryption key changed)`,
+          opts.context,
+        );
+      }
+    }
+
+    try {
+      const handle = await factory.create({ ...toSpec(record), ...(secret ? { secret } : {}) });
+      if (typeof handle?.connect === 'function') await handle.connect();
+
+      // The engine routes a datasource to a driver by `driver.name === <datasource>`.
+      // Prefer the factory's underlying engine driver (the `driver` escape hatch);
+      // fall back to the handle. Stamp the name so routing resolves to this pool.
+      const engineDriver = (handle.driver ?? handle) as { name?: string };
+      try {
+        engineDriver.name = name;
+      } catch {
+        /* frozen driver — registration may still work if name already matches */
+      }
+      engine.registerDriver(engineDriver);
+      engine.registerDatasourceDef?.({
+        name,
+        schemaMode: record.schemaMode,
+        external: record.external as { allowWrites?: boolean } | undefined,
+      });
+
+      // Register read metadata for bound federated objects (DDL-free). Boot
+      // schema-sync ran before this driver existed, so do it on-demand now.
+      for (const objectName of opts.objects ?? []) {
+        try {
+          await engine.syncObjectSchema?.(objectName);
+        } catch (err) {
+          this.logger?.warn?.(`datasource '${name}': syncObjectSchema('${objectName}') failed: ${errMsg(err)}`);
+        }
+      }
+
+      this.logger?.info?.(`datasource '${name}': connected (driver=${record.driver}, schemaMode=${record.schemaMode ?? 'managed'})`);
+      return { name, status: 'connected' };
+    } catch (err) {
+      return this.handleFailure(record, 'failed-degraded', errMsg(err), opts.context);
+    }
+  }
+
+  /** Gracefully disconnect a previously-registered datasource pool. */
+  async disconnect(name: string): Promise<void> {
+    const driver = this.cfg.engine()?.getDriverByName?.(name) as { disconnect?: () => Promise<void> } | undefined;
+    if (typeof driver?.disconnect === 'function') {
+      try {
+        await driver.disconnect();
+      } catch (err) {
+        this.logger?.warn?.(`datasource '${name}': disconnect failed: ${errMsg(err)}`);
+      }
+    }
+  }
+
+  /**
+   * 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(
+    record: ConnectableDatasource,
+    status: ConnectStatus,
+    reason: string,
+    context?: DatasourceConnectContext,
+  ): ConnectResult {
+    const isExternal = record.schemaMode && record.schemaMode !== 'managed';
+    const failFast =
+      context?.trigger === 'declared-auto' &&
+      isExternal &&
+      record.external?.validation?.onMismatch === 'fail';
+    const msg = `datasource '${record.name}': connect failed — ${reason}`;
+    if (failFast) {
+      throw new Error(
+        `${msg}. (schemaMode=${record.schemaMode}, validation.onMismatch='fail' ⇒ fail-fast per ADR-0062 D5)`,
+      );
+    }
+    this.logger?.warn?.(`${msg} — degrading (datasource left unconnected)`);
+    return { name: record.name, status, reason };
+  }
+}
+
+function toSpec(record: ConnectableDatasource): DatasourceConnectionSpec {
+  return {
+    name: record.name,
+    driver: record.driver,
+    config: record.config ?? {},
+    external: record.external,
+    pool: record.pool,
+  };
+}
+
+function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/default-datasource-driver-factory.ts

@@ -113,7 +113,19 @@ function buildMongoUrl(spec: DatasourceConnectionSpec): string {
  * lazily so a host that never builds (e.g.) a mongo connection doesn't pay for
  * the mongo SDK.
  */
-export function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory {
+export 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;
+}
+
+export function createDefaultDatasourceDriverFactory(
+  options: DefaultDatasourceDriverFactoryOptions = {},
+): IDatasourceDriverFactory {
   return {
     supports(driverId: string): boolean {
       return resolveKind(driverId) !== undefined;
@@ -140,14 +152,19 @@ export function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory
       }
 
       if (kind === 'sqlite') {
-        const { SqlDriver } = await import('@objectstack/driver-sql');
-        const driver = new SqlDriver({
-          client: 'better-sqlite3',
-          connection: buildSqlConnection(spec, 'better-sqlite3') as any,
-          useNullAsDefault: true,
-          ...(schemaMode ? { schemaMode: schemaMode as any } : {}),
-        } as any);
-        return toHandle(driver, () => sqlServerVersion(driver, 'sqlite'));
+        // better-sqlite3 loads its native addon lazily (first query), so an ABI
+        // mismatch is invisible at construction and crashes later. resolveSqliteDriver
+        // probes up-front and, IN DEV ONLY, steps down to wasm SQLite (real SQL +
+        // on-disk persistence) then in-memory; in production it returns the native
+        // driver unprobed so a failure surfaces loudly (fail-closed). (#2229)
+        const conn = buildSqlConnection(spec, 'better-sqlite3') as { filename?: string };
+        const { resolveSqliteDriver } = await import('./sqlite-driver-fallback.js');
+        const resolved = await resolveSqliteDriver({
+          filename: conn.filename ?? ':memory:',
+          dev: options.dev,
+          ...(schemaMode ? { schemaMode } : {}),
+        });
+        return toHandle(resolved.driver, () => sqlServerVersion(resolved.driver, 'sqlite'));
       }
 
       if (kind === 'mongodb') {

package/src/index.ts

@@ -39,7 +39,25 @@ export type {
   DatasourceConnectionSpec,
   DatasourceDriverHandle,
   IDatasourceDriverFactory,
+  // Connect policy (ADR-0062 D5 / epic #2163 seam).
+  DatasourceConnectPolicy,
+  DatasourceConnectDecision,
+  DatasourceConnectContext,
+  DatasourceConnectSubject,
 } from './contracts/index.js';
+export { allowAllConnectPolicy } from './contracts/index.js';
+
+// Shared "definition → live driver" path (ADR-0062 D1).
+export { DatasourceConnectionService, isDatasourceAddressed } from './datasource-connection-service.js';
+export type {
+  DatasourceConnectionServiceConfig,
+  ConnectableDatasource,
+  DatasourceBoundObject,
+  ConnectionEngineLike,
+  ConnectionSecretResolver,
+  ConnectResult,
+  ConnectStatus,
+} from './datasource-connection-service.js';
 
 // Decoupled lifecycle service + injected-config shape.
 export { DatasourceAdminService } from './datasource-admin-service.js';
@@ -58,6 +76,17 @@ export type {
 
 // Host glue: dev driver factory + fail-closed secret binder.
 export { createDefaultDatasourceDriverFactory } from './default-datasource-driver-factory.js';
+// Shared native-better-sqlite3 → wasm → in-memory step-down (#2229).
+export {
+  resolveSqliteDriver,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+} from './sqlite-driver-fallback.js';
+export type {
+  ResolveSqliteDriverOptions,
+  ResolvedSqliteDriver,
+  SqliteFallbackEngine,
+} from './sqlite-driver-fallback.js';
 export {
   createDatasourceSecretBinder,
   toCredentialsRef,

package/src/logger.ts

@@ -8,4 +8,6 @@
 export 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;
 }

package/src/sqlite-driver-fallback.test.ts

@@ -0,0 +1,184 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach, afterAll, vi } from 'vitest';
+import {
+  resolveSqliteDriver,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+} from './sqlite-driver-fallback.js';
+
+// Shared, mutable test state read by the mocked driver constructors. `vi.hoisted`
+// makes it available inside the hoisted `vi.mock` factories below.
+const state = vi.hoisted(() => ({
+  /** Make the native better-sqlite3 driver throw a NODE_MODULE_VERSION-style error. */
+  nativeFails: false,
+  /** Make the wasm SQLite driver fail to connect (forces the in-memory last resort). */
+  wasmFails: false,
+  nativeConfigs: [] as any[],
+  wasmConfigs: [] as any[],
+  memoryCount: 0,
+}));
+
+const ABI_ERROR_MESSAGE =
+  "The module '/x/better_sqlite3.node' was compiled against a different Node.js version " +
+  'using NODE_MODULE_VERSION 141. This version of Node.js requires NODE_MODULE_VERSION 127. ' +
+  'Please try re-compiling or re-installing the module.';
+
+vi.mock('@objectstack/driver-sql', () => {
+  class SqlDriver {
+    public readonly name = 'com.objectstack.driver.sql';
+    constructor(public readonly config: any) {
+      state.nativeConfigs.push(config);
+    }
+    async connect(): Promise<void> {
+      // Mirrors the real driver: connect() runs mkdir + a PRAGMA whose error it
+      // swallows — so it is NOT where the ABI failure surfaces.
+    }
+    async execute(_sql: string): Promise<unknown> {
+      // better-sqlite3 loads its native addon lazily at the first query, so the
+      // ABI mismatch surfaces here (the SELECT 1 probe), not at construction.
+      if (state.nativeFails) throw new Error(ABI_ERROR_MESSAGE);
+      return [{ ok: 1 }];
+    }
+    async disconnect(): Promise<void> {}
+  }
+  return { SqlDriver };
+});
+
+vi.mock('@objectstack/driver-sqlite-wasm', () => {
+  class SqliteWasmDriver {
+    public readonly name = 'com.objectstack.driver.sqlite-wasm';
+    constructor(public readonly config: any) {
+      state.wasmConfigs.push(config);
+    }
+    async connect(): Promise<void> {
+      if (state.wasmFails) throw new Error('wasm sqlite failed to initialise');
+    }
+    async execute(): Promise<unknown> {
+      return [];
+    }
+    async disconnect(): Promise<void> {}
+  }
+  return { SqliteWasmDriver };
+});
+
+vi.mock('@objectstack/driver-memory', () => {
+  class InMemoryDriver {
+    public readonly name = 'com.objectstack.driver.memory';
+    constructor() {
+      state.memoryCount += 1;
+    }
+  }
+  return { InMemoryDriver };
+});
+
+describe('resolveSqliteDriver — native better-sqlite3 → wasm → in-memory step-down (#2229)', () => {
+  beforeEach(() => {
+    state.nativeFails = false;
+    state.wasmFails = false;
+    state.nativeConfigs = [];
+    state.wasmConfigs = [];
+    state.memoryCount = 0;
+  });
+
+  it('uses native better-sqlite3 on the happy path (no fallback, no warning)', async () => {
+    const warn = vi.fn();
+    const resolved = await resolveSqliteDriver({ filename: ':memory:', dev: true, warn });
+
+    expect(resolved.engine).toBe('better-sqlite3');
+    expect(resolved.label).toBe('SqlDriver(sqlite)');
+    expect(resolved.driver.name).toBe('com.objectstack.driver.sql');
+    expect(warn).not.toHaveBeenCalled();
+    expect(state.wasmConfigs).toHaveLength(0);
+    expect(state.memoryCount).toBe(0);
+  });
+
+  it('falls back to wasm SQLite when the native addon fails to load, emitting the warning', async () => {
+    state.nativeFails = true;
+    const warn = vi.fn();
+
+    const resolved = await resolveSqliteDriver({
+      filename: '/tmp/proj/.objectstack/data/dev.db',
+      dev: true,
+      warn,
+    });
+
+    expect(resolved.engine).toBe('sqlite-wasm');
+    expect(resolved.label).toBe('SqliteWasmDriver');
+    expect(resolved.driver.name).toBe('com.objectstack.driver.sqlite-wasm');
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith(NATIVE_SQLITE_WASM_FALLBACK_WARNING);
+    // The persistent file path is preserved (real on-disk persistence via wasm).
+    expect(state.wasmConfigs[0].filename).toBe('/tmp/proj/.objectstack/data/dev.db');
+    expect(state.wasmConfigs[0].persist).toBe('on-write');
+    expect(state.memoryCount).toBe(0);
+  });
+
+  it('uses on-disconnect persistence for an ephemeral :memory: wasm fallback', async () => {
+    state.nativeFails = true;
+    const resolved = await resolveSqliteDriver({ filename: ':memory:', dev: true, warn: vi.fn() });
+
+    expect(resolved.engine).toBe('sqlite-wasm');
+    expect(state.wasmConfigs[0].filename).toBe(':memory:');
+    expect(state.wasmConfigs[0].persist).toBe('on-disconnect');
+  });
+
+  it('drops to InMemoryDriver as a dev-only last resort when neither native nor wasm load', async () => {
+    state.nativeFails = true;
+    state.wasmFails = true;
+    const warn = vi.fn();
+
+    const resolved = await resolveSqliteDriver({ filename: ':memory:', dev: true, warn });
+
+    expect(resolved.engine).toBe('memory');
+    expect(resolved.label).toBe('InMemoryDriver');
+    expect(state.memoryCount).toBe(1);
+    expect(warn).toHaveBeenCalledWith(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);
+  });
+
+  it('forwards autoMigrate / schemaMode to the native driver', async () => {
+    await resolveSqliteDriver({ filename: ':memory:', dev: true, autoMigrate: 'safe', schemaMode: 'managed' });
+    expect(state.nativeConfigs[0]).toMatchObject({
+      client: 'better-sqlite3',
+      useNullAsDefault: true,
+      autoMigrate: 'safe',
+      schemaMode: 'managed',
+    });
+  });
+
+  it('production (dev=false) is fail-closed — returns native unprobed, never degrades', async () => {
+    state.nativeFails = true;
+    const warn = vi.fn();
+
+    const resolved = await resolveSqliteDriver({ filename: '/tmp/prod.db', dev: false, warn });
+
+    // The native driver is handed back as-is so the ABI failure surfaces loudly
+    // at first use — we must NOT swap in wasm/mingo behind the operator's back.
+    expect(resolved.engine).toBe('better-sqlite3');
+    expect(resolved.label).toBe('SqlDriver(sqlite)');
+    expect(warn).not.toHaveBeenCalled();
+    expect(state.wasmConfigs).toHaveLength(0);
+    expect(state.memoryCount).toBe(0);
+  });
+
+  describe('dev gate defaults to NODE_ENV when not passed explicitly', () => {
+    const originalNodeEnv = process.env.NODE_ENV;
+    afterAll(() => {
+      process.env.NODE_ENV = originalNodeEnv;
+    });
+
+    it('falls back to wasm when dev is omitted and NODE_ENV=development', async () => {
+      state.nativeFails = true;
+      process.env.NODE_ENV = 'development';
+      const resolved = await resolveSqliteDriver({ filename: ':memory:', warn: vi.fn() });
+      expect(resolved.engine).toBe('sqlite-wasm');
+    });
+
+    it('is fail-closed when dev is omitted and NODE_ENV=production', async () => {
+      state.nativeFails = true;
+      process.env.NODE_ENV = 'production';
+      const resolved = await resolveSqliteDriver({ filename: ':memory:', warn: vi.fn() });
+      expect(resolved.engine).toBe('better-sqlite3');
+    });
+  });
+});