fix(metadata-protocol): the default datasource's refusal names the host's database configuration, not a *.datasource.ts that does not exist

The origin-gated datasource row gains `hostOwned`: names the host defines
from its own configuration. `default` is the one, reserved by contract
(AppPlugin refuses an artifact declaring it, the admin service refuses to
create it), so its PUT / no-row DELETE refusal now says what defines it and
to restart the server; every package-declared datasource's sentence is
byte-identical. Code, status and the refused set are unchanged.

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

Author: claude

.changeset/21922-code-datasource-wins-at-restore.md

@@ -16,7 +16,7 @@ The runtime now keeps one in-memory set of the datasource names it registers fro
 
 - After a restart over a stored row under a code-defined datasource's name, `GET /api/v1/datasources` serves the code definition (`origin: code`) instead of the row, and `PATCH /api/v1/datasources/:name` answers `400 DATASOURCE_ADMIN_ERROR` ("… is code-defined and cannot be edited at runtime.") where it answered 200 for a row that carried `origin: 'runtime'`.
 - No live pool is opened from such a row at boot.
-- `PUT /api/v1/meta/datasource/default` answered 200 and now answers `403 NOT_OVERRIDABLE`. `DELETE /api/v1/meta/datasource/default` with no stored row answered 200 and now answers the same `403`.
+- `PUT /api/v1/meta/datasource/default` answered 200 and now answers `403 NOT_OVERRIDABLE`. `DELETE /api/v1/meta/datasource/default` with no stored row answered 200 and now answers the same `403`. The refusal's remedy names the host's database configuration (the database URL the server starts with), which is what defines `default`; every other code-defined datasource's refusal still names its `*.datasource.ts` source.
 - The skipped row is kept, and the boot logs one warning naming it.
 
 **Remedy.**

packages/metadata-protocol/src/packaged-base-regime.ts

@@ -77,6 +77,11 @@
  * remedy. The two doors keep their own codes (`NOT_OVERRIDABLE` / 403 here,
  * `DATASOURCE_ADMIN_ERROR` / 400 there); the verdict and the remedy agree.
  *
+ * [#21944] One code-defined datasource has no source file: the host's
+ * `default`, defined by the database the server starts with. The row lists it
+ * under `hostOwned`, and its sentence names that configuration instead of a
+ * `*.datasource.ts` nobody can find. Every other name keeps the source remedy.
+ *
  * The row is also what {@link isOriginGatedType} answers from, for the one
  * removal both the protocol's delete door and the repository's delete gate
  * allow on such a type: deleting a STORED row under a code-defined name. The
@@ -127,6 +132,13 @@ export type PackagedBaseRegimeRow =
         readonly source: string;
         /** The decision record the sentence cites. */
         readonly docs: string;
+        /**
+         * [#21944] Names the HOST defines from its own configuration rather than
+         * from a {@link source} file, each with what defines it. For such a name
+         * the source-file remedy is false — no such file exists, and an artifact
+         * may not declare the name at all — so its sentence names this instead.
+         */
+        readonly hostOwned?: Readonly<Record<string, string>>;
     };
 
 /** The table. Keyed by the canonical (singular) metadata type. */
@@ -159,6 +171,14 @@ export const PACKAGED_BASE_REGIME: Readonly<Record<string, PackagedBaseRegimeRow
         noun: 'Datasource',
         source: '*.datasource.ts',
         docs: 'docs/adr/0062-external-datasource-runtime.md',
+        // [#21944] `default` is the host's primary datasource: the runtime's
+        // DefaultDatasourcePlugin builds it from the database the server is
+        // started with (a URL flag or config, OS_DATABASE_URL, a default-routing
+        // rule, or the unified default file — `resolve-project-database.ts`).
+        // The name is reserved for it: AppPlugin refuses an artifact that
+        // declares `default`, and the datasource-admin service refuses to create
+        // one. So no `*.datasource.ts` declares it, and its remedy says so.
+        hostOwned: { default: "the host's database configuration (the database URL the server starts with)" },
     },
 };
 
@@ -197,12 +217,19 @@ function regimeCPrescription(routes: PackagedBaseRegimeCRoutes): string {
  * origin-gated row's owning source — the only remedy such a type has — and the
  * row's citation.
  */
-function rowPrescription(row: PackagedBaseRegimeRow): string {
+function rowPrescription(row: PackagedBaseRegimeRow, name?: string): string {
     switch (row.regime) {
         case 'C':
             return regimeCPrescription(row.routes);
-        case 'origin-gated':
-            return `Edit the ${row.source} source that declares it and redeploy. See ${row.docs}.`;
+        case 'origin-gated': {
+            const host = name !== undefined && row.hostOwned !== undefined
+                && Object.prototype.hasOwnProperty.call(row.hostOwned, name)
+                ? row.hostOwned[name]
+                : undefined;
+            return host !== undefined
+                ? `It is defined by ${host}: change that configuration and restart the server. See ${row.docs}.`
+                : `Edit the ${row.source} source that declares it and redeploy. See ${row.docs}.`;
+        }
     }
 }
 
@@ -247,7 +274,8 @@ export function isOriginGatedType(type: string): boolean {
  * `flow` 411 / 404, `action` 365 / 358, `permission` 317 / 310, `datasource`
  * 192 / 193 — so a name of up to 88 characters arrives whole for every row
  * (pinned). A `flow`'s sentence is byte-identical to the one the row table
- * replaced (pinned literally).
+ * replaced (pinned literally). [#21944] A row's `hostOwned` name is a fixed,
+ * short name with its own remedy (`default`: under 300 characters whole).
  */
 export function packagedBaseRegimeSentence(
     type: string, name: string, operation: 'save' | 'delete',
@@ -260,5 +288,5 @@ export function packagedBaseRegimeSentence(
             + (operation === 'delete' ? 'removed' : 'edited') + ' at runtime: it is read-only. '
         : `Metadata item '${singular}/${name}' is provided by a code package, and its packaged base is locked `
             + (operation === 'delete' ? `against removal. ` : `against in-place edits. `);
-    return lock + rowPrescription(row);
+    return lock + rowPrescription(row, name);
 }

packages/metadata-protocol/src/protocol.code-defined-datasource-door.test.ts

@@ -434,6 +434,19 @@ const CODE_NAMES_SERVICE = 'code-datasource-names';
 const DEFAULT_SAVE_VERDICT = "Datasource 'default' is code-defined and cannot be edited at runtime: it is read-only.";
 const DEFAULT_DELETE_VERDICT = "Datasource 'default' is code-defined and cannot be removed at runtime: it is read-only.";
 const hostServices = (names: string[]) => new Map<string, unknown>([[CODE_NAMES_SERVICE, new Set(names)]]);
+/**
+ * The remedy `default`'s refusal must carry: no `*.datasource.ts` declares
+ * `default` — the host defines it from the database the server starts with —
+ * so the sentence names that, and never the source-file remedy.
+ */
+const HOST_REMEDY = "It is defined by the host's database configuration";
+const expectHostRemedy = (message: unknown) => {
+    const text = String(message);
+    expect(text).toContain(HOST_REMEDY);
+    expect(text).toContain('restart the server');
+    expect(text).not.toContain('.datasource.ts');
+    expect(text).not.toContain('OS_METADATA_WRITABLE');
+};
 
 describe('[#21944] the resolver reads the host\'s code-datasource set', () => {
     it('sees a name the host registers from code, and only the `datasource` type', () => {
@@ -471,6 +484,7 @@ for (const { label, environmentId } of KERNELS) {
 
             expect({ code: err?.code, status: err?.status }).toEqual({ code: 'NOT_OVERRIDABLE', status: 403 });
             expect(String(err?.message).startsWith(`${DEFAULT_SAVE_VERDICT} `), String(err?.message)).toBe(true);
+            expectHostRemedy(err?.message);
             expect(rows.size).toBe(0);
             expect(historyRows).toEqual([]);
         });
@@ -482,6 +496,7 @@ for (const { label, environmentId } of KERNELS) {
 
             expect({ code: err?.code, status: err?.status }).toEqual({ code: 'NOT_OVERRIDABLE', status: 403 });
             expect(String(err?.message).startsWith(`${DEFAULT_DELETE_VERDICT} `), String(err?.message)).toBe(true);
+            expectHostRemedy(err?.message);
             expect(rows.size).toBe(0);
         });
 
@@ -494,6 +509,19 @@ for (const { label, environmentId } of KERNELS) {
             expect(Array.from(rows.values()).filter((r) => r.name === 'default')).toEqual([]);
         });
 
+        it('side by side: `default` names the host\'s configuration, a package-declared datasource still names its source', async () => {
+            const { protocol } = session();
+
+            const host = await refusalOf(protocol.saveMetaItem({ type: 'datasource', name: 'default', item: body('default', 'x') }));
+            const packaged = await refusalOf(protocol.saveMetaItem({ type: 'datasource', name: CODE_DS, item: body(CODE_DS, 'x') }));
+
+            expect({ code: host?.code, status: host?.status }).toEqual({ code: 'NOT_OVERRIDABLE', status: 403 });
+            expect({ code: packaged?.code, status: packaged?.status }).toEqual({ code: 'NOT_OVERRIDABLE', status: 403 });
+            expectHostRemedy(host?.message);
+            expectVerdict(packaged?.message, SAVE_VERDICT);
+            expect(String(packaged?.message)).not.toContain(HOST_REMEDY);
+        });
+
         it('control: a runtime datasource still saves with the set registered', async () => {
             const { protocol, rows } = session();
             const saved = await protocol.saveMetaItem({ type: 'datasource', name: RUNTIME_DS, item: body(RUNTIME_DS, 'Runtime') });

packages/qa/dogfood/test/datasource-restore-code-wins.dogfood.test.ts

@@ -29,7 +29,9 @@
 //   - the `/meta` door's `DELETE` of such a row (the repair) removes it, and
 //     what the admin door serves does not change;
 //   - `PUT` and `DELETE` on `/api/v1/meta/datasource/default` are refused with
-//     the answer the door gives every code-defined datasource;
+//     the answer the door gives every code-defined datasource, its remedy
+//     naming the host's database configuration — no `*.datasource.ts`
+//     declares `default`;
 //   - a runtime datasource with no code twin still restores, and one still
 //     saves through the `/meta` door.
 //
@@ -178,6 +180,13 @@ describe('[#21922 / #21944] a stored datasource row never displaces a code datas
     expect({ status: del.status, code: del.code }).toEqual({ status: 403, code: 'NOT_OVERRIDABLE' });
     expect(del.message.startsWith("Datasource 'default' is code-defined and cannot be removed at runtime: it is read-only."), del.message).toBe(true);
 
+    // The remedy tells the truth about `default`: no `*.datasource.ts` declares
+    // it — the host defines it from the database the server starts with.
+    for (const message of [put.message, del.message]) {
+      expect(message).toContain("It is defined by the host's database configuration");
+      expect(message).not.toContain('.datasource.ts');
+    }
+
     expect(await storedRows('default')).toEqual([]);
   });