Merge remote-tracking branch 'origin/main' into claude/issue-21898-builtin-node-config-values-judged

Author: claude

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

@@ -0,0 +1,29 @@
+---
+"@objectstack/service-datasource": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/runtime": minor
+---
+
+fix(service-datasource,runtime,metadata-protocol)!: a stored datasource row no longer displaces a code-defined datasource at boot, and the metadata door refuses edits to the host's `default` (#21922, #21944)
+
+Clause-②: no (narrowing)
+
+A code-defined datasource (one the installed artifact declares in `*.datasource.ts`, or the host's own `default`) is read-only: `DatasourceSchema.origin` publishes it as "GitOps-owned, read-only in the UI", and the datasource-admin service states "code wins on collision". The boot restore broke both. It registered every stored `datasource` row in `sys_metadata` over whatever the runtime had registered from code, so after a restart a row left under a code-defined name was served by the admin door, editable there when it carried `origin: 'runtime'`, and handed to pool rehydration. A stored `default` row opened a second live pool named `default` on the row's own connection. The metadata door also still saved edits to `default`, the one code-defined datasource no package declares.
+
+The runtime now keeps one in-memory set of the datasource names it registers from code, on the kernel service `code-datasource-names`: `AppPlugin` adds the datasources the artifact declares and `DefaultDatasourcePlugin` adds `default`, both in `init()`, so the set is complete before any `start()` runs. The boot restore skips a stored row under a name in that set, and the metadata door's code-datasource check reads the same set.
+
+**BREAKING — what moves for consumers.**
+
+- 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`. 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.**
+
+- To change a code-defined datasource, change its code definition and redeploy: its `*.datasource.ts` source, or the host's database configuration for `default`.
+- A row the boot warning names is removable, and removing it is the repair: `DELETE /api/v1/meta/datasource/:name` answers 200 and deletes it.
+
+**Unchanged.** A runtime datasource with no code twin restores, saves and deletes through both doors as before. A host that composes neither `AppPlugin` nor `DefaultDatasourcePlugin` registers no set, and its stored rows restore as before. While a stored row exists under a code-defined name, `GET /api/v1/meta/datasource/:name` still serves that row (the metadata door reads its stored overlay first); after the `DELETE` above it serves the code definition, in the same boot.
+
+<!-- adr-0087: not-required (no-migration-prescription) a boot-restore verdict and a metadata-door verdict on datasources the host registers from code, which the published contract already calls read-only: no authorable key, spelling, export or stored shape moves, and no stored row is rewritten, converted or dropped. A row an earlier runtime write left under a code-defined name stays in sys_metadata and is removed by the operator with the metadata door's own DELETE; which stored edit an operator meant to keep is not something a ledger entry can rewrite. The other categories are closed on facts: every bumped package publishes (not unpublished); no ADR-0087 id covers this restore or this door (not already-registered); and the change is a verdict, not a declaration (not runtime-interface-only or type-surface-only). -->

.changeset/21955-spec-redaction-driver-identity.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/spec': patch
+---
+
+The datasource read redaction resolves a driver's identity the way its sibling helper does. The per-driver half of `redactableConfigKeys` now looks a driver up through `resolveDriverId`, the resolver `passthroughSecretPaths` and the write door's contract lookup already use. So every spelling the write door accepts as a builtin driver is redacted as that driver.
+
+Clause-②: no
+
+- The still-writable credential key is withheld on the datasource admin read (`GET /api/v1/datasources/:name`) and on the metadata read under every accepted spelling of its driver, and `redactedConfigKeys` names it.
+- A crafted driver id that made the read throw now answers as a driver the platform ships no contract for: the canonical credential spellings and the former aliases are withheld, and the read succeeds.
+- `restoreRedactedConfig` and the credential migration read the same list, so an untouched Save still restores the stored value under every accepted spelling, and the migration names the still-writable key as residue there too.
+- Unchanged: what the write door accepts, every export and its type, and the answer for a canonical spelling.

docs/qa/platform-checklist/areas/studio-authoring.json

@@ -1451,6 +1451,103 @@
       "history": [
         { "revision": 1, "date": "2026-09-30", "change": "new — the 清单项待写 row of docs/NORTH-STAR.md beside platform-core.docs-audience-gate and platform-core.docs-portal-render; drafted with objectui#10188 and corrected by the at-tier review of objectui PR 11258 (the UI-mirror clause scoped to entries naming an installed doc or book; no signed-out persona — /docs sits behind ProtectedRoute)", "ref": "#20939" }
       ]
+    },
+    {
+      "id": "studio-authoring.picklist-bound-select",
+      "title": "A picklist authored in a package is used by two objects' select fields from the designer: both forms offer its options, the bound field refuses inline options, and a GET → edit → PUT of an object with a bound field saves",
+      "since": "v17.7",
+      "status": "active",
+      "revision": 1,
+      "priority": "P2",
+      "surface": "mixed",
+      "personas": [
+        "seeded admin (authors the objects in Studio; the picklist is authored in a package)"
+      ],
+      "fixtures": {
+        "app": "showcase",
+        "requires": [
+          "a package that declares a picklist and one picklistExtensions entry adding one option to it; the stock showcase declares none, and the kind is package-owned (allowRuntimeCreate false), so add both in the run's own checkout, uncommitted: inside the defineStack call of examples/app-showcase/objectstack.config.ts add `picklists: [definePicklist({ name: NAME, label: LABEL, options: [two or more { label, value }] })]` (definePicklist is exported from '@objectstack/spec') and `picklistExtensions: [{ extend: NAME, options: [{ label, value }] }]`, whose one value the list does not already carry (a repeated value is refused at load with INVALID_METADATA). The extension may sit in the same defineStack as the list; it merges the same way as one from another package. Boot with `--compile` so the artifact carries the edit (os dev otherwise serves an existing dist/objectstack.json), and revert the file after the run",
+          "a writable project package with two runtime objects, each with a sharingModel and one select field carrying inline options; one of them published with a field already bound (picklist: NAME, no options)",
+          "the console under test carries objectui#10202's build (objectui PR 11669, merged as objectui c3623eb1). While .objectui-sha predates that merge (it does at objectstack 80f9f7e6, pin 0abd4f9f), flow it back with `pnpm objectui:refresh` from a ../objectui at or after the merge, per the multi-repo rule, and name the console revision in the run record"
+        ]
+      },
+      "steps": [
+        "boot the showcase isolated with the console under test; sign in as the seeded admin",
+        "GET /api/v1/meta/picklist and GET /api/v1/meta/picklist/NAME — the list is served with name, label, its own options and _packageId",
+        "GET /api/v1/meta/object/OBJ_A/layers for the object whose field is already bound — record the bound field as served (picklist + resolved options, the extension's option included)",
+        "metadata admin (Setup → Metadata → Object → OBJ_A): select an UNRELATED field, rename its label, let the autosave run; record the PUT body and status",
+        "select the bound field: record what the select-field editor shows (Options from = the picklist; the values read-only; no inline options editor)",
+        "open OBJ_B, select its inline select field, open 'Options from', choose the picklist; record the PUT body and status",
+        "Studio → the package → Data → OBJ_A: add a field and let the autosave run; record the PUT body and status",
+        "publish both objects; open the new-record form of each and open the bound select",
+        "Setup → Metadata → Picklist → NAME: record what the page shows and offers"
+      ],
+      "acceptance": [
+        {
+          "clause": "the metadata-admin edit of an unrelated field saves: PUT 200, and no picklist-bound field in the body carries options; every other field (an inline select included) is sent byte-identical",
+          "oracle": "api",
+          "verify": "the captured PUT body and status",
+          "evidence": "the PUT body"
+        },
+        {
+          "clause": "the designer shows no live 'picklist and options cannot both be declared' issue on an object loaded with a served bound field",
+          "oracle": "dom",
+          "verify": "page text after load",
+          "evidence": "screenshot"
+        },
+        {
+          "clause": "the select-field editor offers the served picklists by name",
+          "oracle": "dom",
+          "verify": "picker options vs GET /meta/picklist",
+          "evidence": "picker screenshot"
+        },
+        {
+          "clause": "choosing a picklist PUTs the field with picklist and WITHOUT options (200)",
+          "oracle": "api",
+          "verify": "the captured PUT body and status",
+          "evidence": "the PUT body"
+        },
+        {
+          "clause": "a bound field refuses inline options: no inline options editor (no 'Add value'), the list's values shown read-only with the reason",
+          "oracle": "dom",
+          "verify": "the field inspector",
+          "evidence": "screenshot"
+        },
+        {
+          "clause": "the Studio data page's autosave of an object with a bound field is accepted (200), the bound field sent without options",
+          "oracle": "api",
+          "verify": "the captured PUT",
+          "evidence": "the PUT body"
+        },
+        {
+          "clause": "after publish, both objects' new-record forms offer the picklist's options, the extension's option included",
+          "oracle": "dom",
+          "verify": "open each bound select",
+          "evidence": "the two option lists"
+        },
+        {
+          "clause": "the picklist page shows label, name, owning package, each option with its label and value, and each extension under its declaring package — and offers no create, edit or delete (no New on the list; every control on the detail page disabled or read-only; no write request)",
+          "oracle": "dom",
+          "verify": "list + detail page, network log",
+          "evidence": "screenshots + the empty write log"
+        }
+      ],
+      "negative": [
+        "any PUT of an object with a bound field answered 422 INVALID_METADATA at fields.FIELD.options — FAIL (the served-options producer obligation)",
+        "an inline options editor, or a free-text name box, offered on a bound field — FAIL",
+        "a New / Save / Delete on the picklist list or detail page — FAIL (the kind is package-owned, allowRuntimeCreate false)",
+        "the picklist page saying 'no package extends this picklist' when the package read failed — FAIL"
+      ],
+      "traps": ["stale-console-bundle", "cache-staleness"],
+      "source": [
+        "objectui#10202 ruling 6006062645 (A′): (a) use picklist, (b) served options dropped before the PUT, (c) read-only page, (d) this item",
+        "objectstack#18164; producer obligation 5925784898 on objectui#10202; server pin packages/objectql/src/protocol-picklist-served-roundtrip.test.ts",
+        "packages/spec/src/data/picklist.zod.ts#PicklistSchema, packages/spec/src/data/picklist.zod.ts#PicklistExtensionSchema, packages/spec/src/data/picklist.zod.ts#PicklistServedFieldSchema; packages/spec/src/data/field.zod.ts#FieldSchema.picklist refinement",
+        "the fixture's spelling: packages/spec/src/data/picklist.zod.ts#definePicklist, the defineStack keys packages/spec/src/stack.zod.ts#picklists and packages/spec/src/stack.zod.ts#picklistExtensions; an extension in the list's own package merges (packages/objectql/src/engine-picklist.test.ts, the nested-plugin case)"
+      ],
+      "history": [
+        { "revision": 1, "date": "2026-10-06", "change": "new — drafted with objectui#10202 against the measured run of its PR; filed by the seat. Authored from that draft with these changes: since v17.7, because 17.6.0 shipped before objectui PR 11669 merged; the picker clause split in two, one oracle each; the picklist fixture spelled with its export, its stack keys and the reload it needs; the console fixture naming the merge it must carry; the spec citations written as anchors the gate resolves", "ref": "#21957" }
+      ]
     }
   ]
 }

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);
 }