@@ -0,0 +1,21 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-datasource': patch
+---
+
+fix(spec)!: a datasource named `drivers` is refused at every door that parses a datasource, not only at the admin create door
+
+Clause-②: no (narrowing)
+Metadata-protocol: narrowed
+Skills-docs: none in `skills/**` — `skills/objectstack-data/rules/datasources.md` teaches `default` as host-reserved and no file under `skills/**` declares or shows a datasource named `drivers`; every taught use stays true. Docs: `content/docs/data-modeling/drivers.mdx` said `drivers` was reserved at the admin API only; it now names the schema refusal and every door.
+
+**BREAKING** for a datasource named `drivers`.
+
+- **Before.** The datasource admin API mounts the driver catalog at `GET /api/v1/datasources/drivers`, ahead of the by-name read `GET /api/v1/datasources/:name`, so a datasource named `drivers` can never be read by name (its Setup edit form never loads). The admin create door (`POST /api/v1/datasources`) refused the name, but `DatasourceSchema.name` accepted it, so the same unreachable datasource was still declared in code (`defineDatasource`, a stack's `datasources`) and saved through the metadata save door (`PUT /api/v1/meta/datasource/drivers` answered 200).
+- **Now.** `DatasourceSchema.name` refuses every name in the new export `ROUTE_SHADOWED_DATASOURCE_NAMES` (`@objectstack/spec/data`, today `['drivers']`) with one `invalid_format` issue at `name`: `Datasource name 'drivers' is reserved: the datasource admin API serves its own route at /api/v1/datasources/drivers, ahead of the by-name read /api/v1/datasources/:name, so a datasource of that name could never be read by name. Pick another name.` So `defineStack`, `os validate`, `os build` and the metadata save door (422 `INVALID_METADATA`, nothing stored) all refuse it. The published JSON Schema carries the refusal as a second `pattern` on `name`.
+- **One list.** `@objectstack/service-datasource` now reads the spec's list: the admin registrar mounts the driver catalog from a segment typed as a member of it, and the create door refuses each name in it, as before.
+- **Not changed.** `default` (the host's primary datasource row still parses; a stack still may not declare it), `test`, and names that only contain the word (`driver`, `drivers_archive`, `my_drivers`).
+- **Stored rows.** A stored datasource row named `drivers` still loads, with `_diagnostics` reading `valid: false` and carrying the refusal, and its next metadata save is refused. Through the admin door it stays listed and removable, and a `label`/`active`-only edit still saves. Nothing rewrites it: the new name, and every object that routes to it, are the author's call. The upgrade guide entry is `datasource-name-route-shadowed-refused`.
+- **The remedy.** Rename the datasource (for example to `driver_registry`) and point every object `datasource` / `datasourceMapping` rule that names it at the new name.
+
+<!-- adr-0087: registered datasource-name-route-shadowed-refused -->
@@ -278,9 +278,12 @@ through the same datasource connection path — one failure verdict, one escape
 hatch, and a real `status` for the primary DB in **Setup → Datasources**. The
 name `default` is host-reserved: an app bundle declaring a datasource with that
 name is rejected at load.
-The name `drivers` is reserved at the datasource admin API: creating a runtime
-datasource under it is refused, because `GET /api/v1/datasources/drivers` is the
-driver catalog, so a datasource of that name could never be opened by name.
+The name `drivers` is reserved too, because `GET /api/v1/datasources/drivers`
+is the driver catalog, so a datasource of that name could never be opened by
+name. `DatasourceSchema.name` refuses every name in `ROUTE_SHADOWED_DATASOURCE_NAMES`
+(`@objectstack/spec/data`), so `defineDatasource`, `defineStack`, `os validate`
+and the metadata save door refuse it, and so does the datasource admin API's
+create door.
 
 <Callout type="warn">
 `OS_ALLOW_DRIVER_CONNECT_FAILURE=1` boots anyway, in an explicitly degraded
 
@@ -28,7 +28,7 @@ const result = DatasourceSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **name** | `string` | ✅ | Unique datasource identifier |
+| **name** | `string` | ✅ | Unique datasource identifier (snake_case). Reserved: 'drivers', a path the datasource admin API serves itself, so a datasource of that name could never be read by name. |
 | **label** | `string` | optional | Display label |
 | **driver** | `string` | ✅ | Underlying driver type |
 | **config** | `Record<string, any>` | ✅ | Driver specific configuration |
 
@@ -627,6 +627,7 @@
     "RETIRED_FILTER_OPERATORS (const)",
     "RETIRED_SUB_DAY_INTERVALS (const)",
     "RLS_DENY_FILTER (const)",
+    "ROUTE_SHADOWED_DATASOURCE_NAMES (const)",
     "RPC_QUERY_ALIAS_SLOTS (const)",
     "RUNTIME_OWNED_FIELD_TYPES (const)",
     "RangeOperatorSchema (const)",
 
@@ -616,6 +616,7 @@
     "RETIRED_FILTER_OPERATORS": "src/data/filter.zod.ts#RETIRED_FILTER_OPERATORS (const)",
     "RETIRED_SUB_DAY_INTERVALS": "src/data/analytics.zod.ts#RETIRED_SUB_DAY_INTERVALS (const)",
     "RLS_DENY_FILTER": "src/data/readable-ids.ts#RLS_DENY_FILTER (const)",
+    "ROUTE_SHADOWED_DATASOURCE_NAMES": "src/data/datasource.zod.ts#ROUTE_SHADOWED_DATASOURCE_NAMES (const)",
     "RPC_QUERY_ALIAS_SLOTS": "src/data/data-engine.zod.ts#RPC_QUERY_ALIAS_SLOTS (const)",
     "RUNTIME_OWNED_FIELD_TYPES": "src/data/field.zod.ts#RUNTIME_OWNED_FIELD_TYPES (const)",
     "RangeOperatorSchema": "src/data/filter.zod.ts#RangeOperatorSchema (const)",
 
@@ -0,0 +1,36 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+// #29308. An accept-set narrowing of `DatasourceSchema.name` with no
+// conversion: a datasource named after a literal the datasource admin API
+// mounts beside its by-name read (`drivers`, the driver catalog) is refused.
+// The new name, and every object `datasource` / `datasourceMapping` rule that
+// routes to it, only the author can pick. Same class as
+// stack-datasource-host-reserved-name-refused.
+export const entry: SemanticMigration = {
+  id: 'datasource-name-route-shadowed-refused',
+  surface: 'a datasource whose `name` is one of `ROUTE_SHADOWED_DATASOURCE_NAMES` (today `drivers`), '
+    + 'e.g. defineDatasource({ name: \'drivers\', driver: \'postgres\', config: { … } }), in '
+    + '`defineDatasource`, a stack\'s `datasources`, `os validate`, `os build` and the metadata save door '
+    + '(`PUT /api/v1/meta/datasource/drivers`)',
+  replacement: 'The same datasource under another snake_case name (e.g. `driver_registry`), with every '
+    + 'object that names it (`datasource`, or a `datasourceMapping` rule) pointed at the new name. ⛔ NOT '
+    + 'mechanically convertible: the new name is the author\'s call.',
+  reason:
+    'The datasource admin API mounts the driver catalog at `GET /api/v1/datasources/drivers`, ahead of '
+    + 'the by-name read `GET /api/v1/datasources/:name`, so a datasource named `drivers` was stored and '
+    + 'listed while its detail read (the load of its Setup edit form) always answered the catalog. The '
+    + 'admin create door already refused the name; `DatasourceSchema.name` accepted it, so the same '
+    + 'unreachable datasource was still minted from code and through the metadata save door. The schema '
+    + 'now refuses every name in `ROUTE_SHADOWED_DATASOURCE_NAMES`, the one list the admin routes mount '
+    + 'from, with an `invalid_format` issue at `name` naming the name and the route; the published JSON '
+    + 'Schema carries the refusal as a second `pattern`. Measured producers: none in this repository.',
+  acceptanceCriteria:
+    'No datasource is named `drivers`; `defineStack`, `os validate` and `os build` report no issue at '
+    + '`name` (or `datasources.N.name`) reading "Datasource name \'drivers\' is reserved", and the '
+    + 'metadata save door answers 200 for the renamed datasource. A stored `sys_metadata` datasource row '
+    + 'named `drivers` still loads, with `_diagnostics` reading `valid: false` and carrying this refusal, '
+    + 'and its next metadata save is refused; nothing rewrites it. Through the admin door that row stays '
+    + 'listed and removable, and a `label`/`active`-only edit still saves.',
+};