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 default

[objectstack-fleet]

Part of #21922
Fixes #21944
Clause-②: no (narrowing)

What changes

A code-defined datasource (a *.datasource.ts the installed artifact declares, or the host's own default) is read-only by published contract: DatasourceSchema.origin says "code — authored as *.datasource.ts, GitOps-owned, read-only in the UI", the datasource registry entry in metadata-plugin.zod.ts says code-defined datasources "win on name collision", and datasource-admin-service.ts says "A runtime datasource never shadows a code one (code wins on collision)". The datasource-admin plugin's boot restore broke all three, and the metadata door could not see default at all.

The fix is the one host-owned set of code datasources the two cards' triage asked for ("One set serves both, so do not build two"):

• The set (packages/runtime/src/code-datasource-names.ts, new). One in-memory Set of the datasource names the host registers from code, on the kernel service code-datasource-names. contributeCodeDatasourceNames registers it on first use and adds to it after that, the shape seed-summary uses.
• Its producers, both in init(). AppPlugin.init() adds every datasource the artifact declares: the same list its start() registers in the MetadataService, now memoized so the two phases read one answer. DefaultDatasourcePlugin.init() adds default. Phase 1 completes before any start(), so the set is whole before the restore runs, whatever order the plugins were composed in.
• The restore (restoreRuntimeDatasources, packages/services/service-datasource/src/datasource-admin-plugin.ts). A stored row under a name in the set is not registered over the code definition. It is kept, and one boot warning names it with the repair. The warning goes to the host's options.logger, or to the kernel logger when the host passes none (os serve passes none).
• The resolver (isDeclaredCodeDatasource, packages/metadata-protocol/src/protocol.ts, nothing else in that file). It reads the same set beside the installed packages, so the metadata door answers default the way it answers every code-defined datasource since PR fix(metadata-protocol)!: the metadata door refuses an edit of a code-defined datasource, and removes only a stored row left under one #21942.

⛔ "Code" is never read from a stored row's origin, the MetadataService slot's origin, the connection service's ConnectResult, or a request body's origin.

Measured on a booted showcase

The harness is the @objectstack/verify bootStack with the datasource-admin routes mounted the way serve.ts mounts them, in a temp cwd. The stored rows assert origin: 'runtime' and their own config.filename (the cards' case (b)). They were written through the metadata door's repository on the runtime-only intent, then the stack restarted. BEFORE is 76fec88b16; AFTER is this branch at 1d840709ae. The readings come from a throwaway probe that was never committed; the committed pins below assert the AFTER column.

Reading after the restart	BEFORE	AFTER
admin list, showcase_external	origin: runtime, label "Shadow 21922"	origin: code, "External Analytics (SQLite)"
PATCH /api/v1/datasources/showcase_external	200	400 DATASOURCE_ADMIN_ERROR "… is code-defined and cannot be edited at runtime."
live pool named default	a second pool opened on the stored row's file; verdict already-registered became connected	none; verdict stays already-registered
showcase_ext_customer read	3 rows (code fixture)	3 rows (code fixture)
boot warning naming each stored row	none	one per row
PUT /api/v1/meta/datasource/default	200 "Saved datasource 'default'"	403 NOT_OVERRIDABLE
DELETE /api/v1/meta/datasource/default, no stored row	200	403 NOT_OVERRIDABLE
DELETE /api/v1/meta/datasource/showcase_external (repair), then meta GET in the same boot	200, but the meta GET kept serving the stored edit until the next restart	200, and the meta GET serves the code definition

The dispatch's mechanism hypotheses

• H1, start order. In all three compositions that load service-datasource (serve.ts, standalone-stack.ts, the verify harness), DefaultDatasourcePlugin and AppPlugin are use()d before DatasourceAdminServicePlugin. None of the three declares an ordering edge to another, so their start()s run in insertion order: the code registrations did land before the restore, but by list position alone, which ADR-0116 says proves nothing. The answer is the first branch: the set is filled by a phase that precedes the restore (init()). It is pinned by a boot whose reader plugin is composed first, ahead of every producer. The restore pin also covers a code registration that lands after it.
• H2, the seam. It is a kernel service read through the services registry the protocol already resolves (getServicesRegistry()), with no packages/spec change. The ObjectQL registry was rejected: the engine's datasource definitions mix both origins, and a host package record would be a fabricated provenance.
• H3, the admin refusal. Measured, not assumed. The pins' stored rows carry origin: 'runtime', and the slot the refusal reads holds AppPlugin's explicit origin: 'code'. Under ablation A the admin door served the stored row as origin: runtime, so the refusal cannot come from the admin read's origin ?? 'code' default.
• H4, the live pool. For default: yes. The restored row reached rehydratePools, which opened a second pool named default on the row's file. Routing did not move, because the engine never routes to a driver named default; the default driver keeps its natural name. It is the same defect and the same decision fixes it, pinned by getDriverByName('default') and the connect verdict. For showcase_external, nothing was re-pointed at boot in this composition: AppPlugin's connect ran first, so the rehydrate answered already-registered. The admin PATCH 200 was the open door to a re-point (an update that changes connectivity rebuilds the pool), and it is now refused.

Seam and the Clause-② limb (for the seat)

• Published exports added: none. code-datasource-names.ts is not re-exported from packages/runtime/src/index.ts. service-datasource and metadata-protocol spell the service name privately and read the value structurally as has(name), the way 'datasource-connection' is read today.
• What the seam does add is one kernel service entry, code-datasource-names, which two packages read by name. Whether that is the claim's "service contract" limb is the seat's call. The line above stays as the claim wrote it, and the changeset grades all three packages minor, which holds under either reading.

Named gap: the metadata door's read while a stored row exists

GET /api/v1/meta/datasource/:name still serves a stored row under a code-defined name for as long as the row exists. The door reads its stored overlay first (ADR-0005's read order), whatever the MetadataService holds. The AFTER boot measured it: the admin door served the code definition while the meta GET served the stored row, for showcase_external and for default. So triage's pins "both doors serve the code definition" and "removes it with no change to what is served" hold for the admin door. For the metadata door they hold once the repair DELETE has run, in the same boot. That read lives in getMetaItem's overlay step, outside isDeclaredCodeDatasource, and protocol.ts is held by #21934 in other regions, so it is left to the seat. meta-door-code-datasource.dogfood.test.ts already pins that read as it is.

#21922 stays open for that read: this PR is Part of it, and the seat routes the remaining half through triage when it merges.

Landing beyond the claim's named files

packages/runtime/src/app-plugin.ts is the producer of the packages' half of the set, in the declared runtime package. The memo also makes its residual-owner warning print once instead of once per phase. packages/runtime/src/code-datasource-names.ts is new in the same package.

Patch round 1 (head d77e150701)

Review 6011282321 on #21922. The Tests, Ablations and Gates sections below are round 0's, at 80fbcfdea6; this section carries the readings on the current head.

• The plugin-dev pin (CI red on round 0). AppPlugin.init() now contributes its datasource names as a function that the host's code-datasource set resolves at its first read. The set is still contributed to only in Phase 1, before any start(). The resolution is deferred because the names come from the artifact's collections, which walk packages[]. AppPlugin.init()'s manifest registration is the one thing in init() allowed to touch packages[], pinned by plugin-dev's malformed-stack falsifier, which this PR's first head turned red. The kernel service now holds a CodeDatasourceNames, a set with pending contributions; readers still use has(name) only. A contribution that throws stays pending and rethrows to every reader.
• The default refusal names what defines it: the host's database configuration (the database URL the server starts with). It names no *.datasource.ts, because none declares default. Every package-declared datasource's sentence is byte-identical, and code, status and the refused set are unchanged (packaged-base-regime.ts, the datasource row's hostOwned).
• const listOf = ( spacing restored in app-plugin.ts. Merged origin/main 80f9f7e6ba as 49421a8fe6.
• Ablation D: the old sentence put back for default turned 6 unit cases and 1 dogfood case red, and was restored by blob.
• Tests at d77e150701 (each VERDICT command-exit 0):
  • service-datasource: 748 / 748;
  • metadata-protocol: 27978 passed, 19 skipped;
  • runtime local: 4668 passed, 19 skipped;
  • plugin-dev: 86 / 86;
  • the two dogfood files: 11 / 11;
  • downstream consumers of runtime (cli, client, verify, http-conformance, cloud-connection): all passed;
  • typechecks for the five packages: green.
• Gates at d77e150701: dispatch-gates --commands derived 72, reconciled with --ran as 72 run and 0 not measured, plus check:init-service-contract and check:startup-registry-verdict. All exit 0.
• Docs: the 18 hand-written pages the Docs Drift Check lists were read page by page. None states anything this PR makes false, so no docs are edited.

Tests (head 80fbcfdea6)

• pnpm --filter @objectstack/service-datasource exec vitest run --maxWorkers=2: 41 files, 748 passed.
• pnpm --filter @objectstack/metadata-protocol exec vitest run --maxWorkers=2: 218 files passed, 3 skipped; 27976 tests passed, 19 skipped.
• pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 --project local: 331 files, 4658 passed, 19 skipped.
• Dogfood, --project isolated: datasource-restore-code-wins.dogfood.test.ts (new) and meta-door-code-datasource.dogfood.test.ts, 2 files, 11 passed.
• typecheck green for service-datasource, metadata-protocol, runtime (including its check:test-typecheck ledger, held) and dogfood. tsc --listFiles counts each touched test file once in its program.
• Each package's run includes its new pins: 5 in datasource-admin-plugin.test.ts (the restore), 4 in code-datasource-names.test.ts (the set and its phase), and 2 resolver plus 8 door cases in protocol.code-defined-datasource-door.test.ts (default, on both kernel shapes).

Ablations

Each one was committed first and mutated with scripts/ablation-replace.mjs in wrap mode, under a shell trap. For subjects resolved through dist/, the package was rebuilt and ablation-dist-preflight.mjs proved the marker was present. The restore leg was rebuilt and proven --absent, the blob equalled HEAD, git diff HEAD was empty, and the tree was clean.

• A, the restore registers over a code name (datasource-admin-plugin.ts; marker in 2 files of service-datasource/dist). Unit: 3 failed, 16 passed. The slot served the stored row, the warning was not called, and the order-independent case registered the row. Dogfood: 2 failed, 3 passed. The admin list served showcase_external as the stored row, and the repair case read the same.
• B, the resolver does not know the set (protocol.ts; marker in 2 files of metadata-protocol/dist). Unit: 5 failed, 30 passed (the resolver case, and PUT plus no-row DELETE of default on both kernels). Dogfood: PUT /meta/datasource/default answered 200. The next case then failed as a cascade, because the row that PUT stored made the seed conflict. The repair DELETE and runtime controls stayed green, as expected.
• C, AppPlugin's init() contribution deleted (app-plugin.ts; the subject resolves from source). The reader-first boot saw ['default'], not ['app_wh', 'default']. So the set comes from init(); the start() registration never fills it.

Gates (head 80fbcfdea6)

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 72 commands on the actual change, a superset of the 52 at dispatch. All 72 ran with exit codes captured before any pipe. --ran printed "72 derived famil(ies) accounted for — 72 run, 0 NOT-MEASURED".

• check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (exit 3) because eight packages outside this diff had no dist/. After building them it measured green.
• Two families the derivation does not name were also run, both green: check:init-service-contract ("34 declared / 1 self-provided / 3 without a workspace provider") and check:startup-registry-verdict ("none recording a verdict the boot can contradict").
• check-changeset-no-major's level axis needs a PR payload, so CI reads it.
• Lint is a proven narrowing, not the repo-wide run. eslint --no-inline-config --format json on the 9 touched source and test files reported 9 files, 0 errors and 0 warnings. eslint.config.mjs never enables type-aware linting (no parserOptions.project, no typed rules, as its own comment states), so this diff cannot move any untouched file's verdict.

Acceptance notes

• The default refusal's remedy names the host's database configuration (patch round 1).
• Cluster convergence. convergePool reads a stored row directly and is unchanged. Its signals come from peer admin writes, and the admin door now refuses those for code names.
• The restore's other warnings (a failed read, a failed register) still go only to options.logger, which os serve does not pass. They are unchanged here.
• finding(service-datasource): a datasource created through the metadata door is missing from the admin door until restart, then reads as code-defined because the admin read defaults a missing origin to code #21923 remains open. This diff does not touch listDatasourceRecords, getDatasourceRecord or persistDatasourceRow. One interaction: a metadata-door-created datasource with no origin still restores, and is still read as code by the admin door's default.
• Main drift. origin/main gained fix(spec): serve a field's translated help on description, never on an undeclared help #21956, docs(qa): checklist item for public-form withdrawal layering (17.7 security follow-up) #21964 and test(spec): the first api/ file group's test titles state each cited decision in words instead of a tracker number (stage 24) #21961 (spec and docs-qa only) after the round-1 merge. None touches a file here, and the queue's merged generation is the check.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/metadata-protocol, @objectstack/runtime, @objectstack/service-datasource, touching 23 documentable anchor(s).

18 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 80f9f7e6ba5d2097a4cb32ca696908dcf9678102.

⛔ 5 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 6 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 31 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 80f9f7e6ba5d2097a4cb32ca696908dcf9678102 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 9fe98ea34f3e235cbf284678fcec055b824cd7e2 — the merge of head d77e15070132990d8f99405b33e22afd4256abb5 into base 80f9f7e6ba5d2097a4cb32ca696908dcf9678102, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 9fe98ea34f3e235cbf284678fcec055b824cd7e2 && git checkout 9fe98ea34f3e235cbf284678fcec055b824cd7e2
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 80f9f7e6ba5d2097a4cb32ca696908dcf9678102 d77e15070132990d8f99405b33e22afd4256abb5 && git checkout -B drift-repro 80f9f7e6ba5d2097a4cb32ca696908dcf9678102 && git merge --no-ff d77e15070132990d8f99405b33e22afd4256abb5

node scripts/docs-audit/affected-docs.mjs --json 80f9f7e6ba5d2097a4cb32ca696908dcf9678102

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 80f9f7e6ba5d2097a4cb32ca696908dcf9678102 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

CI status · domain:services seat 2 (#21118) · session_01WMQprn46CND82KmY8sZWBu · 2026-10-06T07:14Z

• Red on 80fbcfdea6: Test Core (4/6) fails in @objectstack/plugin-dev, at src/dev-plugin-malformed-stack-posture.test.ts:210. That pin holds where a malformed packages[] entry's INVALID_ARTIFACT_PACKAGE_ENTRY refusal surfaces, and it went red because this PR's AppPlugin.init() now resolves the code-defined datasources in Phase 1.
• It is this PR's to fix, not a flake. The other packages in the shard were cancelled after it, not failed.
• The fix rides patch round 1 (review 6011282321 on finding(service-datasource): a stored datasource row overrides a code-defined datasource at boot, so after a restart the admin door serves and edits it at runtime (restoreRuntimeDatasources has no code-collision check) #21922), on the original dev's next push. The pin is not to be edited, and the refusal's position must stay as on main.

---

Generated by Claude Code