The metadata write refusal answers a different code per TOPOLOGY: `saveMetaItem`'s scoped-kernel branch refuses before the repository's package door ever runs

[huangyiirene]

What this is

Fallout found while implementing #7682 (package-writability discrimination in SysMetadataRepository.assertAllowed). Filed rather than fixed: #7682's dispatch declared sys-metadata-repository.ts as its file surface and explicitly forbade editing protocol.ts, which two other cards (#8136, #8003) are editing concurrently.

The two refusal points

An artifact-backed write of a type without allowOrgOverride is refused twice over, and which one answers depends on the kernel's environmentId — a row-scoping key, not a topology declaration:

1. packages/metadata-protocol/src/protocol.ts, inside saveMetaItem, guarded by if (this.environmentId !== undefined) (search for the not_overridable message beginning "is provided by a code package and the type has not opted into per-org overlay writes"). Emits 403 NOT_OVERRIDABLE, reads no package.
2. packages/metadata-protocol/src/sys-metadata-repository.ts — assertAllowed, the topology-INDEPENDENT gate. After readonly-package-locks-studio: the read-only metadata refusal keys on the metadata type's overlay policy, not package writability (ITEM_LOCKED / WRITABLE_PACKAGE_REQUIRED never emitted) #7682 this one reads the base the caller named and answers 403 ITEM_LOCKED (read-only base) / 422 WRITABLE_PACKAGE_REQUIRED (runtime-only into a read-only base) / 403 NOT_OVERRIDABLE (writable or unnamed base).

Point 1 shadows point 2 whenever it runs. So after #7682, the SAME request answers differently per deployment shape:

kernel	PUT /api/v1/meta/object/showcase_task?package=READONLY_PKG
host-config / CLI lightweight assembler (environmentId undefined — the flagship showcase, self-hosted servers)	403 ITEM_LOCKED, lockSource: package
project/cloud per-env kernel (environmentId set)	403 NOT_OVERRIDABLE — package never read

The QA run behind #7682 (#7637) measured the first row, which is why #7682's fix lands there.

Why it is worth closing

This is the same class of finding #5086 and #6710 already closed twice in this method: "keying authorization off a row-scoping key is what made a type-level declaration depend on deployment topology" (protocol.ts, the #5086 block comment). The refusal VOCABULARY now depends on it too — a cloud tenant and a self-hosted tenant get different machine-readable codes for the same refused write, and a client that learns to handle ITEM_LOCKED on one will not see it on the other.

Note it is not a regression: point 1 answered NOT_OVERRIDABLE before #7682 as well. #7682 makes the divergence visible rather than creating it.

Suggested shape (not a ruling)

Have point 1 consult the same shared isWritablePackage predicate (packages/metadata-protocol/src/package-writability.ts) that the ADR-0070 D1 gate a few hundred lines below it and the repository door both use, so one condition keeps one vocabulary on every kernel. The alternative — deleting point 1 and letting the repository answer on all topologies — is the larger change and would need its own reading of why the scoped branch exists.

packages/metadata-protocol/src/sys-metadata-repository.package-writability.test.ts (added by #7682) states this boundary in its final describe block, so whoever picks this up has the reachability argument and a harness already written.

Related

• readonly-package-locks-studio: the read-only metadata refusal keys on the metadata type's overlay policy, not package writability (ITEM_LOCKED / WRITABLE_PACKAGE_REQUIRED never emitted) #7682 — the repository half, fixed.
• [Decision] OS_METADATA_WRITABLE unlocks a write on a read-only package while Studio renders a "Read-only" badge — which one is telling the truth? #8146 — the separate OS_METADATA_WRITABLE hatch vs Studio "Read-only" badge decision.

[hotlong]

Triage: lands in packages/metadata-protocol (protocol.ts saveMetaItem scoped-kernel branch) ⇒ domain:metadata, type Bug, pm:queue. One refused write answering different machine-readable codes per deployment topology is declared≠enforced on the refusal vocabulary #7682 just established; the card's suggested narrow shape (point 1 consults the shared isWritablePackage predicate) keeps one vocabulary on every kernel without re-litigating why the scoped branch exists.

⚠️ Serial constraint for the metadata seat: protocol.ts is named as concurrently edited by in-flight #8136 and #8003 — this card must not enter a batch until those land or the file surfaces are confirmed disjoint. The larger alternative (delete point 1 entirely) needs its own reading and is NOT queued here; if the dev finds the narrow shape untenable, stop and report rather than widening scope.

Size/model suggestion: M / opus. #7682's own test file states the boundary in its final describe block, so the harness exists.

---

Generated by Claude Code

[os-zhuang]

Held this round — behind #8136. Recording it now so the hold reads as a decision rather than an oversight.

This card's defect lives in saveMetaItem's scoped-kernel branch (environmentId !== undefined) in packages/metadata-protocol/src/protocol.ts — a refusal path. #8136 is dispatched this round (comment 5275484126) as a file-wide producer sweep of exactly that file's error/catch/refusal message construction. Concurrent restructuring of the same refusal paths is the failure mode this lane has already paid for once, so this card waits for the file rather than racing it.

For contrast, so the rule is legible: #7654 was dispatched into protocol.ts this round as a second concurrent editor under the region exemption, because its region is the getMetaItems read merge — genuinely disjoint from the refusal paths. This card is not.

Release condition: dispatched as soon as #8136 lands. State stays pm:queue, unassigned.

Context this card gained since it was filed — read before implementing

• Its parent readonly-package-locks-studio: the read-only metadata refusal keys on the metadata type's overlay policy, not package writability (ITEM_LOCKED / WRITABLE_PACKAGE_REQUIRED never emitted) #7682 is now closed as completed: PR fix(metadata-protocol): the metadata write refusal reports the package door — ITEM_LOCKED / WRITABLE_PACKAGE_REQUIRED are emitted where they apply #8185 landed (ebf7d98) and fixed the repository-door half. This card is one of that card's two named remainders. It is not a regression from fix(metadata-protocol): the metadata write refusal reports the package door — ITEM_LOCKED / WRITABLE_PACKAGE_REQUIRED are emitted where they apply #8185 — the scoped-kernel branch answered the undiscriminated NOT_OVERRIDABLE before that PR too; fix(metadata-protocol): the metadata write refusal reports the package door — ITEM_LOCKED / WRITABLE_PACKAGE_REQUIRED are emitted where they apply #8185 made the divergence visible and its suite's final describe states the boundary so it does not read as coverage.
• ⚠️ Coupled to [Decision] OS_METADATA_WRITABLE unlocks a write on a read-only package while Studio renders a "Read-only" badge — which one is telling the truth? #8146, which is in flight right now. [Decision] OS_METADATA_WRITABLE unlocks a write on a read-only package while Studio renders a "Read-only" badge — which one is telling the truth? #8146 is implementing the NARROW package-door ruling in SysMetadataRepository.assertAllowed — and that fix will not be reachable on a scoped kernel, because saveMetaItem refuses earlier, here. Whoever takes this card should read [Decision] OS_METADATA_WRITABLE unlocks a write on a read-only package while Studio renders a "Read-only" badge — which one is telling the truth? #8146's landed shape first and make this the same rule at the second refusal point, ⛔ not a second, independently-invented one.
• Every line number on this card is stale by construction — protocol.ts has moved under several merges. Anchor on function names.

---

Generated by Claude Code