finding: after ADR-0106, a restricted caller's GET → edit → PUT of an object schema DELETES the fields that were masked out of their read

[baozhoutao]

Filed from #3682 (ADR-0106 implementation). The write path was deliberately left untouched there — ADR-0106 is silent on the round-trip, and inventing a write-side rule inside a masking PR would be deciding something the ADR did not.

The interaction

ADR-0106 D1 removes an unreadable field whole from a served object schema. PUT /api/v1/meta/:type/:name (packages/rest/src/rest-server.ts) persists the body it is given as the item, and carries no capability gate — only enforceAuth. The neighbouring POST /meta/_migrate route's own comment says so explicitly:

…so unlike the single-item PUT /meta/:type/:name it demands an explicit capability rather than only a session. manage_metadata is ADR-0066 D1's authoring capability…

So for any authenticated caller who is not exempt under ADR-0106 D4 (isSystem, studio.access, setup.access):

1. GET /api/v1/meta/object/account → schema with salary_grade and bonus_formula absent (correct, that is the whole point);
2. the caller edits something unrelated — a label, an option order;
3. PUT /api/v1/meta/object/account with that body → the overlay is stored without salary_grade / bonus_formula.

The fields the caller was never allowed to see are the fields they just deleted, and nothing in the exchange tells them so. This is the read-side twin of the #4326 invariant applyAuditFieldGovernance is careful about on its own side ("injecting columns into the served document would rewrite what a GET → PUT round-trip persists") — ADR-0106 removes rather than injects, but the round-trip consequence is the same mechanism.

Before ADR-0106 a restricted caller round-tripped the full schema, so this could not happen. The masking is correct; what is missing is the write-side answer that has to accompany it.

Why it was not decided in #3682

ADR-0106 says nothing about writes. Its own division-of-labour table assigns "what fields can I write" to the data-plane middleware and stops there, and its Consequences section lists follow-ups that do not include this one. The dispatch options each imply a different contract, and picking one silently is precisely what AGENTS.md Prime Directive #13 warns about:

• Merge, don't replace. saveMetaItem treats a masked read as a partial document and preserves fields absent from the payload that exist in the stored item and are not readable by the caller. Safest; but "absent means keep" is a real semantic change for every other caller of PUT, and it makes field deletion unexpressible for anyone.
• Refuse the write. A non-exempt caller cannot PUT an object schema at all (manage_metadata becomes required, as it already is for _migrate). Simple, defensible, and arguably what the route should always have required — but it is an access change well beyond ADR-0106.
• Detect and 409. Refuse a PUT whose payload drops exactly the fields the caller's own projection removed, naming them. Most informative, most code.
• Accept the loss, documented. Explicitly out of the question for silent data loss (AGENTS.md's warn vs error rule names this class).

Suggested disposition

This needs a maintainer decision (or an ADR-0106 addendum) before code. My own recommendation, if it helps: refuse the write — PUT /meta/:type/:name already looks under-gated relative to every other metadata-authoring door in the repo, and the round-trip hazard disappears entirely if the only callers who can write an object schema are the ones who are exempt from the mask and therefore always hold the whole document. That makes "the caller who can write it is the caller who can see all of it" an invariant rather than a coincidence.

Related: #3682, ADR-0106 D1/D4, ADR-0066 D1 (manage_metadata), #4326 (the GET → PUT round-trip invariant), #4513.

[baozhoutao]

Escalated — needs-user-decision applied (PM, domain:metadata seat, session session_01KDU3qAuJyajAQm3GkUXdfA). This card graduates from finding straight to the decision inbox because its window opens the moment PR #6612 (ADR-0106 masking, accepted and queued) merges: a restricted caller's GET now returns a masked schema, and PUT /meta/:type/:name — which carries no capability gate, only enforceAuth — persists that masked document back, deleting the fields the caller could not see.

The decision (the four dispositions are in the body; the dev's three-axis recommendation, which this seat endorses):

• Recommended: refuse the write — require manage_metadata on PUT /meta/:type/:name, exactly as the neighbouring _migrate route already does. This makes "the caller who can write an object schema is the caller who sees all of it" an invariant, closes the round-trip hazard, AND closes the pre-existing hole that any authenticated caller can clobber schemas arbitrarily (which exists independently of masking). Smallest option: one gate, one test.
• Alternatives: merge-don't-replace (largest; changes PUT semantics for every caller and type), detect-and-409 (adds a comparison but leaves the clobber hole), accept the loss (status quo).
• Risk note: it is an access change beyond ADR-0106's scope — which is exactly why it needs your call rather than a dev's guess.

Sequencing already decided at the PM level (veto window): PR #6612 lands ahead of this ruling — rationale recorded in the #3682 acceptance comment (the PUT hole predates masking; admins are D4-exempt so the realistic schema-editing round-trips stay lossless; the disclosure fix is a ruled v17 item).

For the triage seat (single-producer labels, not applied by this seat): suggest domain:metadata... correction — the recommended fix lands in packages/rest's route gate, so domain:cli may be the right lane; and target:v17 candidacy under criterion ① once #6612 merges. Your call on both.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling (2026-08-08): Option B — refuse the write. PUT /meta/:type/:name must require the manage_metadata capability (same gate as the neighboring _migrate route), making "whoever can write a schema can see the full schema" an enforced invariant. One gate plus one test.

Rationale (three-axis review):

• Business: this is a live data-loss path, not a theoretical hole — the window opened on main when PR feat(meta): mask object schemas per caller on every /meta exit (ADR-0106) #6612 merged. A restricted caller's ordinary GET, edit, PUT round-trip silently deletes the fields masked out of their read.
• Long-term: option A (merge-don't-replace) makes field deletion inexpressible for every PUT caller; option C (detect-and-409) is the most code and still leaves the unrelated clobber hole open. B closes both with the smallest surface.
• AI-error containment: GET-edit-PUT is exactly how AI agents author metadata; today that sequence silently destroys fields the agent cannot see. B turns it into a loud 403 at write time.

For the triage seat: this card still needs its domain routing label (the fix lands in packages/rest per the thread), and it is a target:v17 candidate under criterion 1 (silent data loss).

State: needs-user-decision removed; pm:queue added — dispatchable once routed.

Maintainer directive (verbatim, covering all 14 inbox cards): 「你的建议全部接受」. Recorded by PM session session_01JaVVMrSxt7Tgi1uwEuDtH7.

---

Generated by Claude Code