fix(spec): the drivers-name refusal names only the offending name

Build the sentence from the input (zod 4 error function) instead of once for
the whole list, pin that it names only itself, and correct the NAME_RE
docblock in the admin service, which describes the first of the two patterns.

Claude-Session: https://claude.ai/code/session_01ADHkmS1mEJA9L4pTrajNhU
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/services/service-datasource/src/datasource-admin-service.ts

@@ -54,7 +54,11 @@ import type {
 } from './contracts/index.js';
 import type { Logger } from './logger.js';
 
-/** Datasource name rule (mirrors `DatasourceSchema.name`). */
+/**
+ * Datasource name rule: the identifier pattern, the first of the two patterns on
+ * `DatasourceSchema.name`. The second, the route-shadowed names, is refused by
+ * name in `assertValidName` from the spec's `ROUTE_SHADOWED_DATASOURCE_NAMES`.
+ */
 const NAME_RE = /^[a-z_][a-z0-9_]*$/;
 
 /**

packages/spec/src/data/datasource-route-shadowed-name.test.ts

@@ -83,6 +83,13 @@ describe('DatasourceSchema.name refuses a route-shadowed name', () => {
       expect(message).toContain('could never be read by name');
       expect(message).not.toMatch(/#\d{3,}/);
     });
+
+    it(`the refusal for '${name}' names only that name: built from the input, never from the whole list`, () => {
+      const message = DatasourceSchema.safeParse(sqlite(name)).error!.issues[0]!.message;
+      // Every quoted name and every literal route the sentence carries is this one.
+      expect([...message.matchAll(/'([a-z0-9_]+)'/g)].map((m) => m[1])).toEqual([name]);
+      expect([...message.matchAll(/\/api\/v1\/datasources\/([a-z0-9_]+)/g)].map((m) => m[1])).toEqual([name]);
+    });
   }
 
   it('the code door: defineStack refuses it with STACK_SCHEMA_INVALID / 422 at datasources.0.name', () => {

packages/spec/src/data/datasource.zod.ts

@@ -616,14 +616,16 @@ export const ROUTE_SHADOWED_DATASOURCE_NAMES = Object.freeze(['drivers'] as cons
 const quotedRouteShadowedNames = ROUTE_SHADOWED_DATASOURCE_NAMES.map((name) => `'${name}'`).join(', ');
 
 /**
- * The refusal `DatasourceSchema.name` answers for a route-shadowed name: it
- * names the name and why, in the admin create door's sentence family.
+ * The refusal `DatasourceSchema.name` answers for a route-shadowed name: built
+ * from the offending input, so it names that one name and its route (never the
+ * whole list), in the admin create door's sentence family.
  */
-const ROUTE_SHADOWED_NAME_REFUSAL =
-  `Datasource name ${quotedRouteShadowedNames} is reserved: the datasource admin API serves its own route `
-  + `at /api/v1/datasources/${ROUTE_SHADOWED_DATASOURCE_NAMES.join(' and /api/v1/datasources/')}, 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.';
+function routeShadowedNameRefusal(issue: { input?: unknown }): string {
+  const name = String(issue.input);
+  return `Datasource name '${name}' is reserved: the datasource admin API serves its own route at `
+    + `/api/v1/datasources/${name}, 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.';
+}
 
 /**
  * A second pattern on `name`, not a refinement: zod emits both patterns into
@@ -699,7 +701,7 @@ export const DatasourceSchema = lazySchema(() => strictObject(
    */
   name: z.string()
     .regex(/^[a-z_][a-z0-9_]*$/)
-    .regex(NOT_ROUTE_SHADOWED_NAME, ROUTE_SHADOWED_NAME_REFUSAL)
+    .regex(NOT_ROUTE_SHADOWED_NAME, { error: routeShadowedNameRefusal })
     .describe(
       `Unique datasource identifier (snake_case). Reserved: ${quotedRouteShadowedNames}, a path the `
       + 'datasource admin API serves itself, so a datasource of that name could never be read by name.',