fix(services,spec): reject the last two silent pool drops — turso whole-arm, mongodb's two timeouts by name (#7243) (#7600)

`datasource.pool` was already a loud authoring error on `sqlite` /
`sqlite-wasm` / `memory` (#5714 / #5931). #6214's ledger pass found two
faces the rejected set could not cover, both still silent. Measured on
origin/main before this change:

  turso   + pool{min:3,max:9,idleTimeoutMillis:30000}
              the arm never references `spec.pool` at all
  mongodb + pool{max:20,idleTimeoutMillis:30000,connectionTimeoutMillis:3000}
              driver config: url + database + maxPoolSize:20, nothing else

The mongodb one is half-effective, which is harder to notice than total
silence: `max` landed, so the author's evidence that their pool config
worked was real and half wrong.

Maintainer ruling 2026-08-11, both halves:

1. `turso` joins POOL_UNSUPPORTED_DRIVER_IDS whole-arm, no fork by url
   mode, with its own explanation rather than SQLite's borrowed one.
2. mongodb's two unread timeout keys are rejected by name, not wired
   onto MongoClient's maxIdleTimeMS / connectTimeoutMS — no measured
   consumer, so wiring would be behaviour-surface expansion.

The second half is a new shape here: a rejection scoped to individual
keys (POOL_UNREAD_KEYS_BY_DRIVER) rather than the whole block, because
`min` / `max` on mongodb are honoured and must keep working. It routes
through unsupportedPoolIssue, so all three doors — Setup wizard, boot
pre-pass, driver factory — inherit it unchanged.

Also updates liveness/datasource.json, whose four `pool.*` rows recorded
both cases as "still dropped in silence", and the drivers doc's pool
paragraph, which named only the two sqlite arms.


Claude-Session: https://claude.ai/code/session_015fkdTyGmMD5s8ZtEifvuGy

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-help

.changeset/datasource-pool-turso-mongo-timeouts-reject.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/service-datasource': patch
+'@objectstack/spec': patch
+---
+
+datasource `pool`: the last two silent drops are now loud — `turso` whole-arm, and mongodb's two timeout keys by name (#7243)
+
+`datasource.pool` is declared, strict and documented, and #5714 / #5931 already
+made it an authoring error on the three arms that cannot honour it
+(`sqlite` / `sqlite-wasm` / `memory`). #6214's ledger pass read every remaining
+arm and found two faces the rejected set could not cover, both still dropped in
+silence. Measured on `origin/main` before this change:
+
+```text
+turso   + pool{min:3,max:9,idleTimeoutMillis:30000}   the arm never references `spec.pool` at all
+mongodb + pool{max:20,idleTimeoutMillis:30000,connectionTimeoutMillis:3000}
+                       → driver config: url + database + maxPoolSize:20, and nothing else
+```
+
+The mongodb line is the harder of the two because it is **half**-effective: `max`
+took effect, so the author had real evidence their pool config worked, and the
+two timeouts vanished anyway.
+
+Maintainer ruling 2026-08-11, both halves:
+
+1. **`turso` joins `POOL_UNSUPPORTED_DRIVER_IDS` whole-arm**, with no fork by url
+   mode. `TursoDriverConfig` has no `min` / `max`; a `file:` / `:memory:` url runs
+   the same better-sqlite3 engine the set already rejects for, and a `libsql://`
+   url is a remote request transport with no persistent connections, capped by
+   `config.concurrency`. The arm carries its own explanation rather than
+   borrowing SQLite's, because an author on the remote transport told about
+   `:memory:` would be reading about somebody else's datasource.
+2. **mongodb's two unread timeout keys are rejected by name, not wired.**
+   `MongoClient` does expose `maxIdleTimeMS` / `connectTimeoutMS`, so this one
+   could have been implemented; with no measured consumer asking for it, wiring
+   would be behaviour-surface expansion. Rejection keeps declared = enforced and
+   tells the author at authoring time. It stays a one-line change on the day real
+   demand appears.
+
+The second half is a new shape for this module: a rejection scoped to individual
+**keys** rather than the whole block, because `min` / `max` on `mongodb` are
+honoured and must keep working. It is a data table (`POOL_UNREAD_KEYS_BY_DRIVER`)
+rather than a per-arm `if`, so the next arm that half-reads the block is one line
+and inherits all three doors — the Setup wizard's create/update, the boot-time
+auto-connect pre-pass, and the driver factory's last door.
+
+Both rejections name the datasource, name the offending key(s), say the rejection
+is deliberate, and give the one edit that fixes it. Neither offers an escape-hatch
+env var (#5794), and the mongodb message says what SURVIVES the edit — telling a
+mongo author to "remove `pool`" would delete two keys that do take effect.
+
+Nothing that was honoured changes: `postgres` / `mysql` still receive all four
+keys, `mongodb` still maps `min` / `max` onto `minPoolSize` / `maxPoolSize`. New
+API surface is `POOL_UNREAD_KEYS_BY_DRIVER` / `unreadPoolKeys` /
+`unreadPoolKeysMessage`; `unsupportedPoolIssue` and `assertDatasourcePoolSupported`
+keep their signatures and now cover both gates, so an injected host factory that
+already calls them inherits this with no change.
+
+`@objectstack/spec` carries the ledger half: `liveness/datasource.json`'s four
+`pool.*` rows and their block note recorded both of these as "still dropped in
+silence" — the honest record #6214 left, and false the moment this lands. They now
+state the new verdicts. No schema, type or runtime behaviour changes in `spec`.

content/docs/data-modeling/drivers.mdx

@@ -121,16 +121,33 @@ Two things live **outside** `config`, because they are not driver-specific:
 
 - **Pool sizing** — the `pool` block on the datasource (`min`, `max`,
   `idleTimeoutMillis`, `connectionTimeoutMillis`), honoured by the pooled
-  drivers: `postgres` and `mysql` pass it to Knex, `mongo` maps `min` / `max`
-  onto the client's `minPoolSize` / `maxPoolSize`. Declaring it on a **sqlite**
-  or **sqlite-wasm** datasource is rejected — by the Setup wizard when you save,
-  and by the boot when a declared datasource carries one: a SQLite connection
-  strategy is owned by the driver (one connection per database, because a second
-  connection to `:memory:` opens a separate, empty one), so a pool declared
-  there could never take effect. It used to be dropped in silence — an `app-crm`
-  datasource asking for `max: 5` measurably ran on one connection
-  ([#5714](https://github.com/objectstack-ai/objectstack/issues/5714)). The fix
-  is to delete the block; it is a no-op on SQLite either way.
+  drivers: `postgres` and `mysql` pass all four to Knex, and `mongodb` maps
+  `min` / `max` — and only those two — onto the client's `minPoolSize` /
+  `maxPoolSize`. Everywhere else the block is an **authoring error**, rejected by
+  the Setup wizard when you save and by the boot when a declared datasource
+  carries one, rather than dropped:
+
+  | Driver | Verdict on `pool` |
+  | --- | --- |
+  | `postgres`, `mysql` | all four keys honoured |
+  | `mongodb` | `min` / `max` honoured; `idleTimeoutMillis` and `connectionTimeoutMillis` **rejected by name** |
+  | `sqlite`, `sqlite-wasm` | whole block **rejected** |
+  | `memory` | whole block **rejected** |
+  | `turso` / `libsql` | whole block **rejected** |
+
+  Each arm says why in its own terms. A SQLite connection strategy is owned by
+  the driver (one connection per database, because a second connection to
+  `:memory:` opens a separate, empty one); `memory` opens no connection at all;
+  neither libSQL transport pools — a `file:` url runs that same local SQLite
+  engine and a `libsql://` url is a remote request transport capped by
+  `config.concurrency`. Every one of these used to be dropped in silence: an
+  `app-crm` datasource asking for `max: 5` measurably ran on one connection
+  ([#5714](https://github.com/objectstack-ai/objectstack/issues/5714)), and a
+  mongo datasource asking for `max: 20, idleTimeoutMillis: 30000` got the first
+  and lost the second without a word
+  ([#7243](https://github.com/objectstack-ai/objectstack/issues/7243)) — the
+  half-honoured case, which is the hardest to notice. The fix is always to
+  delete the rejected keys; they were reaching nothing either way.
 - **TLS certificates** — the `ssl` block on the datasource (`enabled`,
   `rejectUnauthorized`, `ca`, `cert`, `key`). Inside `config`, `ssl` is the
   on/off boolean shorthand.