fix(metadata-protocol): allow REMOVING a legacy env overlay on a rolled-back overlayable type (#6960)

[os-zhuang]

Fixes #6960

Base of this branch: f16e54e1d — the commit that landed ADR-0029 D9 and its pins. Every reverse-verification direction below was measured against that SHA, never a moving origin/main.

What moved, and what did not

The maintainer's ruling of 2026-08-10 moves the delete side only. Two tiers reach the same two refusal points, and the separator is the registry's own supportsOverlay flag — not allowOrgOverride:

tier	registry declaration	delete	create / update
rolled-back overlayable — permission / position / page / app / dataset / book (and tool / skill, same shape)	supportsOverlay: true + allowOrgOverride: false	now ALLOWED	refused, unchanged
object and every other supportsOverlay: false type	supportsOverlay: false	refused, unchanged	refused, unchanged

supportsOverlay is the capability of the READ path ("an overlay row under this name changes what is served"); allowOrgOverride is the permission on the WRITE path ("a tenant may author one"). #6483 / PR #6608 rolled the permission back and deliberately left the capability alone — which is exactly the state #6960 was filed about. Keying the relaxation on the capability is what makes it stop at the tier boundary: an object overlay registers as its own contributor layer (ADR-0029 D9) rather than merging, and its reset refusal is D9.6's declared, maintainer-approved cost.

Both refusal points are treated, because the second is topology-independent:

1. deleteMetaItem's environmentId !== undefined two-tier block — which refused before it ever probed for the row;
2. SysMetadataRepository's delete gate — reached by a control-plane kernel (environmentId === undefined), which skips (1) entirely. A fix pinned on only one path would have left the defect alive on one topology.

File surface, file by file

• packages/metadata-protocol/src/protocol.ts — adds the registry-derived OVERLAY_CAPABLE_TYPES set and the mergesOverlayAtRead(type) predicate beside the existing isOverlayAllowed / isRuntimeCreateAllowed family (derived, plural-normalized, no parallel whitelist — Prime Directive Convert to monorepo with scoped packages #8). Adds && !legacyOverlayRemoval to deleteMetaItem's artifactBacked && !overlayAllowed refusal, with the ruling, the boundary and the delete-only asymmetry documented at the call site. Extends deleteMetaItem's two-tier header comment with the new bullet. Extends the save-side gate's carve-out comment — the one that already promised "removing a code-only row that predates this refusal is repair, and must stay possible" — to name the artifact-backed tier it did not cover, which is the divergence between stated intent and enforced behaviour the issue opened with. saveMetaItem's gates themselves are untouched; the only edits inside saveMetaItem are comment lines.
• packages/metadata-protocol/src/sys-metadata-repository.ts — adds the registry-derived OVERLAY_CAPABLE_TYPES set and a new private assertDeleteAllowed(type, intent); delete() now calls it, put() still calls assertAllowed directly. The carve-out is scoped to the override-artifact intent (runtime-only stays governed by allowRuntimeCreate). assertAllowed itself is unchanged, byte for byte.
• packages/metadata-protocol/src/protocol.legacy-overlay-delete.test.ts — new, 101 cases.
• .changeset/legacy-overlay-delete-rolled-back-types.md — new, patch on @objectstack/metadata-protocol.

No other file is touched. packages/spec is read, never changed — the acceptance surface is untouched, which is the distinction the dispatch's STOP condition 2 draws.

Reverse verification — four categories, directions declared before running

⚠️ Zero affected rows in the corpus today (measured at PR #6608), so there is no live victim and no "it works now" demo. The pins are the deliverable.

1. Predicted red, measured red

Fix taken out with git checkout f16e54e1d -- (the two source files) (never git stash — shared stack), test file kept:

Tests  57 failed | 44 passed (101)

Predicted 56, measured 57 (the extra one is category 3). Both refusal points reproduced, one per topology, with their real messages:

project kernel  — removes a legacy env overlay on an artifact-backed permission …
Error: [not_overridable] Metadata item 'permission/legacy_permission_overlay' is provided by a code
package and the type has not opted into per-org overlay writes.
  at ObjectStackProtocolImplementation.deleteMetaItem src/protocol.ts:11932

control-plane   — removes a legacy env overlay on an artifact-backed permission …
Error: Failed to delete customization overlay: [NOT_OVERRIDABLE] 'permission' is not allowOrgOverride
in the registry. Overlay-allowed: view, dashboard, report, translation, email_template.
  at ObjectStackProtocolImplementation.deleteMetaItem src/protocol.ts:12152

That is 8 types x 3 cases x 2 topologies at the protocol layer, plus 8 SysMetadataRepository.delete cases, plus the category-3 case. Every one of them is green with the fix in place.

2. Green in BOTH directions — guards, not evidence

Labelled [GUARD] in their own test names as well as here: the object-tier delete refusals on both topologies; the same refusal for every other supportsOverlay: false type with a runtime write channel; put still refusing an override-artifact write of every rolled-back type; saveMetaItem still refusing both the plain and the org-scoped write; the runtime-only delete still judged by allowRuntimeCreate. They pass before and after — what makes them load-bearing is the variant experiment below, not this run.

3. Missed prediction — one, kept rather than tidied away

a delete with NO overlay row answers the no-op success instead of 403 was written as a guard and measured red on the project kernel. Cause identified: the refusal ran before the probe for the row (the issue's own words), so an artifact-backed item with nothing customized was refused too — the miss is real coverage the prediction did not anticipate, not a broken assertion. On the control-plane kernel it was already green: the probe returns first and repo.delete is never reached. The case keeps its corrected comment in the file.

4. Unmeasured

None. Every assertion in the new file was run in both directions.

Variant verification — the damage case, measured

The obvious over-broad fix is to relax the shared predicate for every artifact-backed type. Applied exactly that (mergesOverlayAtRead returning unconditionally true, and assertDeleteAllowed returning early for any non-runtime-only intent), rebuilt, and ran ADR-0029 D9's own pins:

packages/objectql/src/protocol-object-overlay-layer.test.ts
  Tests  2 failed | 14 passed (16)

  x  …and so is the RESET of one: deleteMetaItem answers NOT_OVERRIDABLE / 403
     AssertionError: expected null to be an instance of Error
  x  a control-plane kernel refuses at the repository, and subtracts under the hatch
     AssertionError: expected null to be an instance of Error

Exactly D9's two delete pins, one per topology, red — and 14 of this PR's own boundary guards red with them. The variant was reverted and D9's file is back to 16/16 passed under the shipped scoping. That is what makes the scoping necessary rather than merely sufficient: D9's pins were never edited, adjusted, or worked around.

Tests

pnpm --filter @objectstack/metadata-protocol test   ->  69 files, 1009 tests passed
pnpm --filter @objectstack/objectql test            -> 172 files, 3066 tests passed
pnpm --filter @objectstack/rest test                ->  79 files, 1278 tests passed
pnpm --filter @objectstack/runtime test             -> 120 files, 1906 tests passed
pnpm --filter @objectstack/metadata test            ->  30 files,  593 tests passed
pnpm --filter @objectstack/objectql typecheck       -> Done

metadata-protocol has no typecheck script by design — it carries a measured DEBT entry (63) in scripts/check-type-check-coverage.mjs. Ran tsc --noEmit -p tsconfig.json directly: 63 errors, unchanged, and zero of them in the new test file, so the ratchet is not raised.

Family gates that ride the ESLint job, all green locally: check:nul-bytes (plus a targeted control-byte self-scan over all four touched files, no hits), check:engine-double-contract, check:error-code-casing, check:route-envelope, check:meta-type-normalized, check:adr-anchors.

One finding filed, not fixed here

#7426 — deleteMetaItem's catch re-wrap carries status forward but drops code, so a repository refusal reaches the caller as a 403 with no catalogued code on the control-plane topology. It is why ADR-0029 D9's control-plane pin asserts a message substring while its project-kernel sibling asserts code + status, and why this PR's own control-plane assertions state the gap instead of asserting around it — carrying the full code + status envelope one layer down, directly against SysMetadataRepository, where nothing re-wraps it. Out of scope: fixing it changes the error envelope of every non-conflict failure on that path, which this ruling does not reach.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 10:57am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx (via @objectstack/metadata-protocol)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/metadata-protocol)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/v9.mdx (via @objectstack/metadata-protocol)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

ACCEPT — PM review (step 7)

File surface vs declaration

Four files, exactly as declared:

file
packages/metadata-protocol/src/protocol.ts	modified	+119/−2
packages/metadata-protocol/src/sys-metadata-repository.ts	modified	+74/−1
packages/metadata-protocol/src/protocol.legacy-overlay-delete.test.ts	added	+694
.changeset/legacy-overlay-delete-rolled-back-types.md	added	+48

packages/spec read but never changed. packages/objectql absent from the diff entirely, which is the mechanical proof that ADR-0029 D9's pins were not edited — the constraint this card carried above all others. No content/docs/releases/, no docs/adr/**. Changeset present and Check Changeset green; skip-changeset correctly not applied, since this ships a real behaviour change.

CI, per job

25 check runs, all completed: 23 success, 2 skipped (Build Docs, Console Pin Gate — path-filtered). No failures. Named gates: ESLint success, TypeScript Type Check success, Build Core success, Test Core 3/3 + rollup success, Dogfood Regression Gate 3/3 + rollup success, Dogfood Verify CLI, Temporal Conformance (live PG + MySQL), Check Changeset, Check PR Size, ADR maintainer approval, No other open PR may claim the same issue — all success.

What I am accepting

The tier boundary resolved into a registry-derived predicate rather than a hardcoded list, and that is the better answer. I dispatched this with an enumeration (permission / position / page / app / dataset / book) and a standing instruction to STOP if the tiers could not be separated. They separate on the registry's own supportsOverlay flag — the types whose loader merges overlays at read are exactly the types where a stuck overlay is possible, and object declares supportsOverlay: false, so the carve-out cannot reach it structurally rather than by an exclusion someone has to remember. A hardcoded six-type list would have drifted the first time another type was rolled back.

Both refusal points moved, which is what makes this a whole fix rather than half of one. deleteMetaItem's environmentId branch yields, and SysMetadataRepository.delete routes through the new assertDeleteAllowed carrying the same registry-derived rule — so the control-plane topology, which skips the first gate entirely because it has no environmentId, is released by the same rule rather than left refusing. That second path was the half most likely to be missed, and the pins cover both topologies.

Create and update are verifiably untouched: put still calls assertAllowed unchanged and saveMetaItem's gates are not in the diff. The delete-only asymmetry is recorded in both gates' doc comments — including extending the save-side carve-out that promised "removing a row that predates this refusal is repair" to name the artifact-backed tier it never covered. That divergence between stated intent and enforced behaviour is what the card opened with, so closing it in the comment is part of the fix, not decoration.

Reverse verification — the variant is what earns the ACCEPT

Reverted against the dev's own recorded base f16e54e1d (git checkout <base> -- <2 source files>, no git stash). Predicted 56 red, measured 57 red / 44 passed, with real output from both refusal points — project kernel [not_overridable] … the type has not opted into per-org overlay writes at protocol.ts:11932, control-plane Failed to delete customization overlay: [NOT_OVERRIDABLE] 'permission' is not allowOrgOverride in the registry at :12152.

The variant verification is decisive and is exactly the damage case I required. Relaxing the predicate for every artifact-backed type turned D9's own pin file to 2 failed | 14 passed — precisely its two delete pins (…and so is the RESET of one: deleteMetaItem answers NOT_OVERRIDABLE / 403, and a control-plane kernel refuses at the repository, and subtracts under the hatch), plus 14 of this PR's own boundary guards. Variant reverted, D9's file back to 16/16. That proves the scoping is necessary, not merely sufficient — the over-broad fix is not hypothetical, it is measured, and it breaks exactly the two assertions the maintainer's D9 approval made binding.

One missed prediction, reported rather than buried, and it found a second facet of the defect. The guard "a delete with NO overlay row answers the no-op success instead of 403" went red on the project kernel, because the refusal ran before the probe for the row — so pre-fix, an artifact-backed item with nothing customized at all was refused too. The card described that ordering ("throws … before any probe for the row") without drawing out the consequence. Kept in the file with a corrected comment.

Guards labelled as guards (green in both directions, marked [GUARD] in the test names and the PR body): object-tier delete refusals on both topologies, every other supportsOverlay: false type, put still refusing override-artifact writes, saveMetaItem plain and org-scoped refusals, runtime-only delete still judged by allowRuntimeCreate. Unmeasured: none.

Suites all green with the consumption radius covered: metadata-protocol 1009, objectql 3066, rest 1278 (after clearing an AGENTS.md §9 unbuilt-dependency false red — correctly diagnosed as the stale-artefact trap rather than treated as a real failure), runtime 1906, metadata 593. Type-check debt measured at 63 and unchanged, zero in the new file.

⚠️ One scope note, stated so it can be vetoed cheaply

The delivered predicate also releases tool and skill, which my dispatch did not enumerate — they carry supportsOverlay: true, so they are the same registry shape and have the identical stuck-repair problem. I am accepting this as within the ruling: the maintainer's reasoning was general ("deleting an overlay restores the code-declared state; it is the narrowing direction and cannot widen anything"), and excluding two types that share the shape would leave the same defect alive for no reason. Flagging it explicitly because the ruling's text named the rolled-back six — if the intent was narrower, this is the line to object to, and it is one predicate to change.

Filed, not fixed

#7426 — deleteMetaItem's catch re-wrap carries status forward but drops code, so a repository refusal reaches the caller as a 403 with code: undefined on the control-plane topology. That is not merely a new defect: it explains why D9's control-plane pin asserts a message substring while its project-kernel sibling asserts code + status. Correctly left out — fixing it changes the error envelope of every non-conflict failure on that path.

Ruling

ACCEPT. Flipping out of draft, enabling auto-merge (SQUASH). Landing serialises behind the in-flight #4717 through the queue; the two are region-disjoint (deleteMetaItem + the repository gate here, saveMetaItem's success return there).

---

Generated by Claude Code

[os-zhuang]

PM note — ACCEPT stands; the ready-flip is deferred on a GraphQL rate limit, not on anything about this PR.

update_pull_request (draft → ready) is a GraphQL-only write and the quota is currently exhausted (API rate limit already exceeded). The review verdict above is unchanged and final; the mechanical half is queued.

Recording the pending state here rather than only in session context, so it survives a context reset or a seat handover:

pending action	on PR	detail
1. flip draft → ready	#7429	GraphQL — blocked, retrying on a stepped timer
2. enable auto-merge SQUASH	#7429	GraphQL — after 1
3. subscribe_pr_activity	#7429	after 2
4. landing double-read	—	unbounded git log origin/main --grep='(#7429)' + single-parent check, then ledger row + confirm #6960 closed + unsubscribe

⚠️ Re-verification required before executing, not just replay: the ACCEPT is anchored to this PR's head at review time. If the head has moved when the quota returns, the gates get re-read before anything is flipped.

Nothing is required from the dev, and the PR needs no changes. Reads (REST) are on a separate quota and still working, which is why this comment posted.

---

Generated by Claude Code