fix(metadata-protocol)!: the metadata door refuses an edit of a code-defined datasource, and removes only a stored row left under one

[objectstack-fleet]

Fixes #21899
Clause-②: no (narrowing)

What changes

The metadata door now answers a code-defined datasource the way the published contract (DatasourceSchema.origin: "code — authored as *.datasource.ts, GitOps-owned, read-only in the UI") and the datasource-admin door already did: read-only. Triage ruled Q1-A and Q2-B in 6006929054; this PR implements both, in packages/metadata-protocol only.

• The resolver (Q1-A). isArtifactBacked (packages/metadata-protocol/src/protocol.ts) gains a second non-standalone-artifact resolver, isDeclaredCodeDatasource, in the isNestedArtifactField shape from org-override-registry-gate: the field overlay lock is not enforced — an artifact-backed field PUT is accepted 200 (and is inert) #7743. It reads the installed packages' declared datasources (registry.getAllPackages(), each record's manifest.datasources, in the canonical array form defineStack leaves). datasource is added to that docblock's census. It never reads a MetadataService slot's origin or a request body's origin; a unit case pins a body asserting origin: 'runtime' on a code datasource as still refused, and one asserting origin: 'code' on a runtime name as still saved.
• The package door's answer. With the resolver in place, the existing door refuses the save on both kernel shapes: refusePackagedBaseOverride on an environment kernel, and the repository write intent (override-artifact into SysMetadataRepository.assertAllowed) on a host-config kernel, which is the showcase's shape. The answer is NOT_OVERRIDABLE / 403. The sentence comes from the packaged-base sentence table (packaged-base-regime.ts), which gains one origin-gated row for datasource. ADR-0126 §3 records datasource outside the three regimes, as "origin-gated: code-defined read-only, runtime-created free", so the row is not a Regime C row. It carries no routes, only the owning source.
• DELETE as repair (Q2-B). A DELETE that would remove nothing is refused with the same verdict. A DELETE of an existing stored row answers 200. Where the carve-out lives:
  • ObjectStackProtocolImplementation.originGatedRemovalRefusal (new, beside refusePackagedBaseRemoval) holds the package door's removal verdict. deleteMetaItem answers it at its row probe: it throws when no stored row exists and lifts it when one does.
  • SysMetadataRepository.assertDeleteAllowed mirrors the lift for the same type through isOriginGatedType. This is the topology-independent gate a host-config kernel asks.
  • The reasoning is reused, not invented. It is saveMetaItem's metadata: allowRuntimeCreate:false is not enforced — PUT /meta creates job and agent items the registry declares code-only #5086 record ("removing a code-only row that predates this refusal is repair, and must stay possible") and the A legacy env overlay on an artifact-backed item of a rolled-back type can no longer be REMOVED through the ordinary delete path (403) — only via OS_METADATA_WRITABLE #6960 ruling (removal restores the code-declared state, which is the narrowing direction). A legacy env overlay on an artifact-backed item of a rolled-back type can no longer be REMOVED through the ordinary delete path (403) — only via OS_METADATA_WRITABLE #6960's own supportsOverlay boundary is not widened: object, which shares datasource's registry flags, keeps refusing both verbs, and a guard pins that.
• The read envelope. servedLockState reports what the doors do: editable: false, and deletable true only while the read found a stored row to remove.

The two doors' codes differ, by ruling

Triage's answer 6006929054: "The two doors' codes differ, and that is accepted. Each door speaks its own vocabulary; the verdict and the remedy agree." Measured on a real showcase boot at this branch:

• metadata door PUT: 403 NOT_OVERRIDABLE — Datasource 'showcase_external' is code-defined and cannot be edited at runtime: it is read-only. Edit the *.datasource.ts source that declares it and redeploy. See docs/adr/0062-external-datasource-runtime.md.
• admin door PATCH: 400 DATASOURCE_ADMIN_ERROR — Datasource 'showcase_external' is code-defined and cannot be edited at runtime.
• metadata door DELETE with no stored row: 403 NOT_OVERRIDABLE — Datasource 'showcase_external' is code-defined and cannot be removed at runtime: it is read-only. Edit the *.datasource.ts source that declares it and redeploy. See docs/adr/0062-external-datasource-runtime.md.
• admin door DELETE: 400 DATASOURCE_ADMIN_ERROR — Datasource 'showcase_external' is code-defined and cannot be removed at runtime.

The host's default datasource (H4): the admin door treats it as code-defined; covering it here is a named gap

• Measured on a real showcase boot (bootStack, admin routes mounted as serve.ts mounts them):
  • PATCH /api/v1/datasources/default answers 400 DATASOURCE_ADMIN_ERROR "Datasource 'default' is code-defined and cannot be edited at runtime.", and DELETE answers "… cannot be removed at runtime.".
  • On the metadata door, PUT /api/v1/meta/datasource/default answers 200 "Saved datasource 'default' (env-wide, state=active)" and the read then serves the edit. DELETE answers 200.
  • This PR leaves default unchanged: PUT answers 200 on this branch too, which is measured.
• Why it is not covered here. The host's code datasource set is not readable from metadata-protocol without a runtime or service-datasource change:
  • DefaultDatasourcePlugin registers default only through MetadataService.registerInMemory. That is the slot whose origin triage ruled unsound, because a stored row overwrites it.
  • The connection service's retained state carries no origin (ConnectResult: name, status, reason, ownership).
  • The engine's listDatasourceDefs() mixes code and runtime definitions.
  • No package declares default.
• What follows. Under the claim's stop condition, no runtime or service-datasource file is edited. This is reported for a follow-up card, and the changeset names it.

Pins, before and after (real showcase boot, showcase_external)

"Before" is the reverse-verification leg below (the base isArtifactBacked on committed HEAD) and the first run's measurements at 54fb60ac3f (6006105473). "After" is this branch.

Pin	Before	After
PUT /meta/datasource/showcase_external	200 "Saved datasource 'showcase_external' (env-wide, state=active)", a row persisted, the read served the edit	403 NOT_OVERRIDABLE with the verdict and remedy above; no sys_metadata row; the read serves the code label
DELETE, no stored row	200 "No datasource 'showcase_external' found - nothing to delete."	403 NOT_OVERRIDABLE, "cannot be removed at runtime"
DELETE, a pre-existing stored row (seeded as a pre-fix save wrote it, across a restart)	200, reset true	200, reset true, row gone; a second DELETE answers 403
after the repair and one more restart	—	both doors serve "External Analytics (SQLite)", origin code, _packageId com.example.showcase; no row
runtime datasource	admin door: POST 201, PATCH 200, DELETE 204; metadata door: PUT 200, PUT 200, DELETE 200	the same

Reverse verification

Run on committed HEAD 8413b4622d, through scripts/ablation-replace.mjs (WRAP mode, its own restore trap, plus a git checkout HEAD trap):

• The mutation restores the base form of isArtifactBacked's last line, dropping || this.isDeclaredCodeDatasource(type, name). On disk the anchor went 1 to 0 and the replacement 0 to 1. The blob went 8e2d759618ba to 51f36f712468.
• Unit suite (src): protocol.code-defined-datasource-door.test.ts showed 14 failed and 11 passed. The red cases are the resolver, PUT refused (both kernels), DELETE with no row refused, the repair's second DELETE, the read envelope, and the 500-character bound. The green cases are the runtime controls, the hatch guard and the repository gate cases, which do not route through isArtifactBacked.
• Dogfood (dist):
  • pnpm --filter @objectstack/metadata-protocol build emitted ESM/CJS and failed only DTS on TS6133, because the mutation leaves the new method unused.
  • node scripts/ablation-dist-preflight.mjs @objectstack/metadata-protocol '...' --absent confirmed the marker absent from all 22 built files.
  • meta-door-code-datasource.dogfood.test.ts showed 4 failed and 2 passed. The PUT pin read expected { status: 200, code: undefined } to deeply equal { status: 403, code: 'NOT_OVERRIDABLE' }.
• Restore: the blob after restore equals HEAD (8e2d759618ba), git diff HEAD is empty, and git status --porcelain is empty. A rebuild put the marker back in both built entry files (preflight: present). The unit file then passed 25/25 and the dogfood file 6/6.

Tests (HEAD dd81fb50d5)

• pnpm --filter @objectstack/metadata-protocol exec vitest run --maxWorkers=2: 217 files passed (3 skipped), 27941 tests passed.
• pnpm --filter @objectstack/metadata-protocol typecheck and pnpm --filter @objectstack/dogfood typecheck are green. tsc --listFiles includes every touched test file.
• Dogfood: meta-door-code-datasource.dogfood.test.ts (6/6) and external-import-code-datasource-namespace.dogfood.test.ts.
• Consumer files touching the datasource /meta door were run, all green:
  • runtime: datasource-visibility, meta-type-write-capability-parity, stored-metadata-reader-contexts.pin, standalone-stack-hydrate-metadata, meta-write-org-scope, dispatcher-plugin.declared-5xx-prose-withhold.
  • rest: meta-type-read-capability, meta-type-write-capability, rest-server-meta-write-org-scope, meta-unknown-type-read-refusal, rest-server-meta-org-scope-url-spelling, rest.
  • service-datasource: datasource-admin-record-judgement.
  • objectql: overlay-precedence.
• Three existing sweeps had pinned the old datasource delete refusal and were triaged. protocol.delete-rewrap-envelope, protocol.legacy-overlay-delete and protocol.read-lock-flags-write-door exclude the origin-gated type from the derived refusal sweeps or measure it at the protocol's delete door. Each change points at the new pin file.

Gates (HEAD dd81fb50d5)

• node scripts/pm/dispatch-gates.mjs --commands derived 76 commands, and all 76 were run with exit 0. --ran reconciliation reports "76 derived famil(ies) accounted for — 76 run, 0 NOT-MEASURED".
• check:engine-double-contract asked for its ledger to learn the new file's pinned doubles (--write, +3 rows, committed).
• The artifact-roster block (53) ran: 50 exited 0. check-closing-target-claim, check-partof-closing-keyword and check-single-claim-paths exited 2 with no PR context (NOT MEASURED locally); they run on this PR in CI.
• The four symbol-anchor sweeps (check:adr-symbol-anchors, check:scripts-symbol-anchors, check:spec-docblock-symbol-anchors, check:adr-anchors) exited 0.
• check:adr-0087-registration --base origin/main: one declared-breaking changeset, not-required (no-migration-prescription). check-changeset-no-major reports no major.

Acceptance notes

• Same boot after the repair DELETE. The read keeps serving the stored copy until the next restart, because the datasource-admin plugin's boot restore registered it in the MetadataService. The receipt still reads "reset to artifact default". That is 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's in-memory half, so the repair pin holds across a restart. Measured: in the same boot, GET after the repair served "Shadow 21899"; after the restart it served the code label.
• An admin-created runtime datasource cannot be edited or deleted through the metadata door. Both answer 409 METADATA_CONFLICT, whether or not the version token is sent, because the admin door's sys_metadata row carries a null checksum. This is pre-existing and untouched here (runtime names are not artifact-backed). It is reported for filing in the dev report. The PM's hypothesis that sending the version makes it pass was measured false.
• H2's "packaged-base sentence table". The table gains an origin-gated row rather than a Regime C row, per ADR-0126 §3. Its module header now scopes the "no redeploy prescription" rule to Regime C sentences.
• The operator hatch. OS_METADATA_WRITABLE=datasource still opens the lock exactly as before; a guard case pins it.
• Not measured. An artifact whose top-level datasources no package body declares (AppPlugin warns about this composition at boot) registers code datasources the resolver does not see, because no package record carries them.

Changeset

.changeset/21899-meta-door-code-datasource-read-only.md: @objectstack/metadata-protocol minor, BREAKING, Clause-②: no (narrowing). It states the remedy: edit the *.datasource.ts source, and delete a stored row through the metadata door to repair. It carries one ADR-0087 marker.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 26 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class), SysMetadataRepository (symbol, a top-level class), getMetaItemLayered (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/data-modeling/drivers.mdx (via getMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/data-modeling/external-datasources.mdx (via showcase_external (literal, a string literal in a comment in ObjectStackProtocolImplementation))
• content/docs/kernel/contracts/metadata-service.mdx (via getPublished (sdk, the bare tail of client method meta.getPublished, bound to GET /api/v1/meta/:type/:name/published; the bare tail of client method meta.getPublished, bound to GET /meta/:type/:name/published))
• content/docs/kernel/services-checklist.mdx (via deleteMetaItem (symbol, a method of class ObjectStackProtocolImplementation), getMetaItem (symbol, a method of class ObjectStackProtocolImplementation))

⛔ 4 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/releases/v17/17-3.mdx (via /:type/:name/published (route, bridged from symbol getMetaItemLayered — its route source's handler names it))
• content/docs/releases/v17/17-6.mdx (via /api/v1/meta/datasource/:name (route, a path literal in a comment in ObjectStackProtocolImplementation))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 5 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 — 11 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 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5ce9eece1832504aecb46ded9ebed94d3ada5621 — the merge of head dd81fb50d5ad7bf85b6d9c65db325866a7890def into base 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8, 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 5ce9eece1832504aecb46ded9ebed94d3ada5621 && git checkout 5ce9eece1832504aecb46ded9ebed94d3ada5621
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8 dd81fb50d5ad7bf85b6d9c65db325866a7890def && git checkout -B drift-repro 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8 && git merge --no-ff dd81fb50d5ad7bf85b6d9c65db325866a7890def

node scripts/docs-audit/affected-docs.mjs --json 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8

⚠️ 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 9e33ee7c5936e35a38158a7f9fdbcbd4445797a8 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

ACCEPT (seat review) — PR #21942 at head dd81fb50d5

domain:engine#1 · session_017ErfyP2Rx7XWHJA27QjyUi · read at 2026-10-06T03:11Z. The os-dev report is on #21899 (6008535605). Judged against GitHub and the branch, not against the report.

• Shape: draft, base main.
  • Title fix(metadata-protocol)!: …. The first lines are Fixes #21899 and Clause-②: no (narrowing).
  • Assignee: os-project-manager.
• Scope: 10 files, +1080/-55, all in metadata-protocol except the dogfood pin and the engine-double ledger rows the gate demanded. No runtime or service-datasource file is touched, as the order required.
• The diff, read: triage's answer (6006929054), Q1-A and Q2-B, as ruled.
  • isArtifactBacked gains a second non-standalone-artifact resolver, isDeclaredCodeDatasource, in the isNestedArtifactField shape. It reads the installed packages' declared datasources.
  • ⛔ It never reads a MetadataService slot's origin or a body's origin.
  • The existing package door (environment kernel) and the repository write intent (host-config kernel) then refuse PUT with NOT_OVERRIDABLE/403.
  • The packaged-base sentence table gains an origin-gated row, which follows ADR-0126 §3's placement of datasource outside the regimes. It speaks the admin door's verdict and remedy: "Datasource '…' is code-defined and cannot be edited at runtime: it is read-only. Edit the *.datasource.ts source that declares it and redeploy."
  • The two doors' codes differ, as triage accepted.
  • Q2-B, the carve-out: originGatedRemovalRefusal refuses a DELETE that would remove nothing, and lifts the refusal when a stored row exists (repair, on the metadata: allowRuntimeCreate:false is not enforced — PUT /meta creates job and agent items the registry declares code-only #5086 / A legacy env overlay on an artifact-backed item of a rolled-back type can no longer be REMOVED through the ordinary delete path (403) — only via OS_METADATA_WRITABLE #6960 reasoning). SysMetadataRepository.assertDeleteAllowed mirrors that through isOriginGatedType. A legacy env overlay on an artifact-backed item of a rolled-back type can no longer be REMOVED through the ordinary delete path (403) — only via OS_METADATA_WRITABLE #6960's supportsOverlay boundary is not widened: object still refuses, and a guard case pins it.
  • servedLockState reports deletable only while a stored row is served, so the read envelope agrees with the doors ([finding] The layered metadata read reports lock none, editable true and deletable true for packaged flows and actions that the write doors refuse with NOT_OVERRIDABLE #21670).
• Public surface: packaged-base-regime.ts is not re-exported from @objectstack/metadata-protocol's entry, so (narrowing) is the only arm. It is BREAKING, with minor, a ! subject, the remedy, and ADR-0087 not-required (no-migration-prescription), which check:adr-0087-registration reads.
• Door readings (dogfood on a showcase boot):
  • PUT on showcase_external: 200 → 403 NOT_OVERRIDABLE, with no row written.
  • DELETE with no row: 200 → 403.
  • DELETE of a pre-existing shadow row: 200 reset: true. The row is gone, and after a restart both doors serve the code definition.
  • A runtime datasource still writes through each door.
  • The admin door is unchanged.
• H4, the host's default datasource: the admin door treats it as code-defined (measured). Its code set is not readable from metadata-protocol without a runtime or service-datasource edit. As triage directed, it is a named gap in the PR body, and the seat files its follow-up card in this act.
• H5, falsified and recorded: a meta-door PUT or DELETE of an ADMIN-created runtime datasource answers 409 METADATA_CONFLICT with or without If-Match, because the admin door stores a null checksum. That is pre-existing, and it is folded into 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's family, noted on that card in this act.
• Fixture triage: 5 pre-existing sweeps pinned the old datasource delete refusal (delete-rewrap-envelope, legacy-overlay-delete ×3, read-lock-flags). Each now excludes the origin-gated type and points at the new pin file. Every other assertion is untouched.
• Reverse verification, from committed 8413b4622d: the resolver term was dropped and rebuilt. 14 unit and 4 dogfood pins went red, and the PUT pin read { status: 200 } vs { status: 403, code: NOT_OVERRIDABLE }. Restore was proved by blob equality.
• Evidence:
  • metadata-protocol passes 27941 tests in 217 files;
  • the /meta door's consumers in runtime, rest, service-datasource and objectql pass;
  • metadata-protocol and dogfood typecheck exit 0.
• Gates:
  • dispatch-gates --ran: 76 of 76 exit 0.
  • The roster (53), the four symbol-anchor sweeps and the 3 PR-context guards against this PR pass.
  • check-changeset-no-major passes.
• CI: read at landing.

---

Generated by Claude Code