@@ -0,0 +1,10 @@
+---
+'@objectstack/service-datasource': patch
+---
+
+fix(service-datasource): Test connection answers `ok: false` when the driver connects but its own health check answers `false` (#30407)
+
+Clause-②: no — a served answer comes to match the driver's own health answer; no accept set changes.
+Metadata-protocol: none
+
+The datasource probe awaited the handle's `ping` (the driver's `checkHealth()`) and dropped its boolean, so a connect that only warned and then reported itself unhealthy answered Test connection `ok: true`. The probe now reads that answer: a literal `false` answers `ok: false` with a sentence saying the driver connected but its health check reported the database as unhealthy. A connect or ping that throws keeps answering the thrown message, and a handle whose `ping` answers nothing keeps answering `ok: true`.
@@ -9,6 +9,7 @@ import {
   type DatasourceAdminServicePluginOptions,
 } from '../datasource-admin-plugin.js';
 import { registerDatasourceAdminRoutes } from '../admin-routes.js';
+import { createPrebuiltDriverFactory } from '../prebuilt-driver-factory.js';
 import { ENTITLED_CREDENTIAL, createSessionAuthService, createGrantsEngine } from './entitled-caller.fixture.js';
 
 import { assertEngineFindOnePredicate, hashSpec } from '@objectstack/metadata-core';
@@ -855,3 +856,64 @@ describe('DatasourceAdminServicePlugin: objects bound external are read from the
     expect(registry.get('datasource')?.has('wh')).toBe(true);
   });
 });
+
+// The probe reads the driver's own health answer: a connect that resolves but a
+// health check answering `false` is not a usable connection, so Test connection
+// must not answer `ok: true` over it. The stub is a DRIVER (connect resolves,
+// checkHealth answers a boolean) wrapped the way production wraps one — through
+// `createPrebuiltDriverFactory`, whose handle mirrors the shared factory's
+// `toHandle` (`ping` and `checkHealth` both answer the driver's checkHealth()).
+describe('DatasourceAdminServicePlugin: probe reads the health answer', () => {
+  function stubDriver(health: boolean, over: { connect?: () => Promise<void> } = {}) {
+    const calls = { connect: 0, checkHealth: 0, disconnect: 0 };
+    const driver = {
+      name: 'stub',
+      connect: over.connect ?? (async () => { calls.connect += 1; }),
+      checkHealth: async () => { calls.checkHealth += 1; return health; },
+      disconnect: async () => { calls.disconnect += 1; },
+    };
+    return { driver, calls };
+  }
+  const draft = { name: 'reporting', driver: 'postgres', config: { host: 'db', database: 'analytics' } };
+
+  it('answers ok:false with a refusal sentence when connect resolves and the health check answers false', async () => {
+    const { driver, calls } = stubDriver(false);
+    const { service } = await boot({ driverFactory: createPrebuiltDriverFactory(driver, { driverId: 'postgres' }) });
+    const res = await service.testConnection(draft);
+    expect(res.ok).toBe(false);
+    expect(res.error).toMatch(/health check/i);
+    expect(res.latencyMs).toBeUndefined();
+    expect(calls).toEqual({ connect: 1, checkHealth: 1, disconnect: 1 });
+  });
+
+  it('answers ok:false when the handle carries only checkHealth (no ping) and it answers false', async () => {
+    const { service } = await boot({
+      driverFactory: fakeFactory({
+        create: async () => ({ connect: async () => {}, checkHealth: async () => false, disconnect: async () => {} }),
+      }),
+    });
+    const res = await service.testConnection(draft);
+    expect(res.ok).toBe(false);
+    expect(res.error).toMatch(/health check/i);
+  });
+
+  it('CONTROL: a healthy stub driver still answers ok:true', async () => {
+    const { driver, calls } = stubDriver(true);
+    const { service } = await boot({ driverFactory: createPrebuiltDriverFactory(driver, { driverId: 'postgres' }) });
+    const res = await service.testConnection(draft);
+    expect(res.ok).toBe(true);
+    expect(typeof res.latencyMs).toBe('number');
+    expect(calls).toEqual({ connect: 1, checkHealth: 1, disconnect: 1 });
+  });
+
+  it('CONTROL: a throwing connect keeps its answer (the thrown message, health never asked)', async () => {
+    const { driver, calls } = stubDriver(true, {
+      connect: async () => { throw new Error('connect ECONNREFUSED 10.0.0.5:5432'); },
+    });
+    const { service } = await boot({ driverFactory: createPrebuiltDriverFactory(driver, { driverId: 'postgres' }) });
+    const res = await service.testConnection(draft);
+    expect(res).toEqual({ ok: false, error: 'connect ECONNREFUSED 10.0.0.5:5432' });
+    expect(calls.checkHealth).toBe(0);
+    expect(calls.disconnect).toBe(1);
+  });
+});
@@ -1016,9 +1016,20 @@ export class DatasourceAdminServicePlugin implements Plugin {
       if (typeof driver?.connect === 'function') await driver.connect();
       // Prefer a cheap ping; fall back to the engine driver's health check, then
       // a schema introspection round-trip — whichever the handle exposes.
-      if (typeof driver?.ping === 'function') await driver.ping();
-      else if (typeof driver?.checkHealth === 'function') await driver.checkHealth();
+      //
+      // [#30407] The answer is read, not only awaited: the shared factory's
+      // `toHandle` (and `createPrebuiltDriverFactory`) map `ping` to the
+      // driver's own `checkHealth()`, which reports an unhealthy connection by
+      // answering `false` rather than throwing. A connect that only warns and
+      // then reports itself unhealthy answered Test connection `ok: true`.
+      // Only a literal `false` refuses: `ping` is `Promise<unknown>` on the
+      // contract, and a host-built handle's ping that answers nothing (or any
+      // other value) keeps meaning "the round-trip succeeded".
+      let health: unknown;
+      if (typeof driver?.ping === 'function') health = await driver.ping();
+      else if (typeof driver?.checkHealth === 'function') health = await driver.checkHealth();
       else if (typeof driver?.introspectSchema === 'function') await driver.introspectSchema();
+      if (health === false) return { ok: false, error: UNHEALTHY_PROBE_REFUSAL };
       const latencyMs = elapsedSince(startedAt);
       let serverVersion: string | undefined;
       try {
@@ -1039,6 +1050,16 @@ export class DatasourceAdminServicePlugin implements Plugin {
   }
 }
 
+/**
+ * [#30407] What Test connection answers when the driver connected but its own
+ * health check answered `false`. The thrown-error path keeps answering the
+ * driver's message; this is the one answer for a health check that reports
+ * failure without throwing.
+ */
+const UNHEALTHY_PROBE_REFUSAL =
+  'The driver connected, but its health check reported the database as unhealthy, so this '
+  + 'connection is not usable. Check that the database exists and accepts these settings, then test again.';
+
 function safeGetService<T>(ctx: PluginContext, name: string): T | undefined {
   try {
     return ctx.getService<T>(name);