meta-field-write-inert: an accepted `field` PUT never reaches the object — a runtime-created field is stored `valid=true` and is absent from `fields` forever

[huangyiirene]

Summary

Split out of #7743, which recorded two entangled defects. #7743's PR closes the first (an artifact-backed field override is now refused 403 NOT_OVERRIDABLE). This is the second, and it is independent: a field write that is entirely legitimate under the registry declaration is accepted, persisted, reported valid — and read by nothing.

The registry declares field with allowRuntimeCreate: true, so authoring a brand-new field through PUT /api/v1/meta/field/<object>.<name> is a supported capability. It just does not work. declared ≠ enforced, Prime Directive #10.

Why this is its own card, not part of #7743

#7743's dispatch predicted that refusing the override would destroy the evidence for the inertness. Measured: it does not. The inertness has two halves and only one of them is behind the new refusal:

• override half (showcase_task.title) — now 403, no longer observable. ✔ expected
• create half (showcase_task.zz_new_probe) — still 200, still inert, still reproducible on main after org-override-registry-gate: the field overlay lock is not enforced — an artifact-backed field PUT is accepted 200 (and is inert) #7743's PR lands.

So this card has a live repro, not archived evidence.

Measured (booted showcase, admin bearer)

Before #7743's fix — both halves:

PUT /api/v1/meta/field/showcase_task.title {name:'title', label:'Tampered', type:'text'}
 → 200 {"success":true,"state":"active","message":"Saved field 'showcase_task.title' (env-wide…)"}
GET /api/v1/meta/field/showcase_task.title
 → {"item":{"name":"title","label":"Tampered","type":"text","_diagnostics":{"valid":true}}}
GET /api/v1/meta/object/showcase_task
 → title.label === 'Title' ← unchanged. 24 fields.

After #7743's fix — the create half, unchanged:

PUT /api/v1/meta/field/showcase_task.zz_new_probe {name:'zz_new_probe', label:'Probe', type:'text'}
 → 200 {"success":true,"state":"active","message":"Saved field 'showcase_task.zz_new_probe' (env-wide…)"}
GET /api/v1/meta/field/showcase_task.zz_new_probe
 → {"item":{…,"_diagnostics":{"valid":true}}}
GET /api/v1/meta/object/showcase_task
 → fields count === 24, 'zz_new_probe' in fields === false ← the field does not exist

The row answers success twice over — accepted, and stored valid — for a document no consumer reads.

Where to look

A field write lands in sys_metadata as a standalone row type='field', name='<object>.<field>'. Nothing merges standalone field rows into an object's effective schema: the object's fields come from the object artifact plus its own overlay row, and applyRegistryWriteThrough routes only type === 'object' into applyObjectRegistryMutation. A field row takes the generic hydrateOverlayIntoRegistry branch, and field is supportsOverlay: false, so there is no overlay merge for it either.

Consistent with field having no standalone artifact loader at all (filePatterns: ['**/*.field.ts'] matches nothing in any app — fields are authored inside ObjectSchema.fields), which is the same structural fact #7743's root cause turned on.

The decision this needs

Three coherent outcomes; this is a maintainer call, not a mechanical fix:

1. Implement it — a field write composes into the parent object (registry write-through + read-path merge + column sync), making allowRuntimeCreate: true true.
2. Retire the write channel — ADR-0049 enforce-or-remove: if a field is only ever authored as part of its object, field should not carry allowRuntimeCreate: true, and the route should refuse with a sentence pointing at PUT /meta/object/<name>.
3. Keep the row, document it as inert — the weakest, and it is the shape ADR-0049 forbids.

⚠️ If (1) is ever chosen, note that #7743's overlay refusal must stay: making field overrides legal is a separate decision from making field creates work, and #7743 pins the override as refused in both topologies.

Source

Extracted from #7743 (itself from the QA run #7695). Measured on origin/main at bcea363 plus #7743's fix, on the showcase with writable runtime packages.

[huangyiirene]

Claim — domain:metadata PM seat (#6367). Session session_01AmES43BMDg4bPrxTdi5q7t, branch claude/issue-7893-field-write-inert. No competing claim. pm:queue → pm:dispatched.

⚠️ This card's body is TRUNCATED when read through the GitHub API — reproducibly

Read twice, hours apart. Both times the body stops mid-sentence at exactly the same point:

The registry declares field with allowRuntimeCreate: true, so authoring a brand-new field through PUT /api/v1/meta/field/

…and ends. Nothing after that character reaches an API reader. The likely mechanism is the angle-bracketed path template that follows (<object>.<field> or similar) breaking the response encoding — the same shape that makes this body read back HTML-escaped elsewhere.

Consequences I am handling rather than papering over:

• I have not read this card in full, and I am saying so instead of writing a brief that implies I did. Building a dispatch on a silently-truncated card is the same class of error as inheriting a stale code snippet — which this seat already made once today (Product question: an uninstall with no organizationId deletes EVERY organization's rows for that package (measured 5 of 5, including a foreign org's) #7780's brief quoted a pre-protocol.deletePackage finds zero sys_metadata rows the data plane finds 3 of — uninstall leaves orphaned rows (persistence half of #7557) #7705 predicate).
• The dev is told the body is truncated, told to read it on the web UI where the full text renders, and told to reconstruct the surrounding detail from org-override-registry-gate: the field overlay lock is not enforced — an artifact-backed field PUT is accepted 200 (and is inert) #7743 (this card's parent, which recorded both entangled defects) plus the code itself.
• ⛔ If the dev cannot recover the full card, it is instructed to STOP and report rather than guess at the missing half.

⚠️ Anyone reading this card through an API client should assume they are seeing a partial body. The web UI shows it whole.

What is legible, and is enough to start

Split from #7743, which recorded two entangled defects. #7743's PR closed the first (an artifact-backed field override is now refused 403 NOT_OVERRIDABLE). This is the second, and it is independent:

a field write that is entirely legitimate under the registry declaration is accepted, persisted, reported valid — and read by nothing.

The registry declares field with allowRuntimeCreate: true, so authoring a brand-new field at runtime is a sanctioned operation — and the title records the outcome: the row is stored valid=true and the field is absent from fields forever.

That is a complete defect statement: the write door accepts and persists something the read path never surfaces. What is missing from my copy is the reproduction detail and whatever the filer measured about where the chain breaks — which is exactly what the dev must recover rather than invent.

Region declared (mutually-exclusive-region exemption)

The field write door in packages/metadata-protocol/src/protocol.ts and whatever read path is supposed to surface a runtime-created field.

⚠️ Concurrently held in that file: #8027 (the sys_metadata overlay path in getMetaItem / getMetaItems / getMetaItemLayered). That is this lane's cap of 2 — no third editor. Both briefs order: anchor on function names, never line numbers, merge origin/main before opening the PR, and merge again after the sibling lands.

⚠️ Its sibling #7894 (the plural-URL bypass) is cross-seat blocked — PLURAL_TO_SINGULAR lives in packages/spec, which is the acceptance face and belongs to domain:spec (#6017). ⛔ Not to be fixed here. If this card's remedy starts reaching into that map, that is a stop-and-report, not a widening.

Brief carried inline in the dev's prompt.

---

Generated by Claude Code

[huangyiirene]

⛔ DESIGN EXIT — pm:dispatched → needs-user-decision. The read path was never built.

The dev's verdict:

field authoring write path works; read path doesn't exist — no fix possible without PM decision

No branch pushed, which is the correct state for a design exit. ⚠️ Its full report is not yet posted (cloud containers still get 403 on every GitHub API call — measured three times since the App was connected at ~12:00Z). I have asked it to hand the text over and will append it.

Why this is a decision and not a bug

The brief named this outcome in advance as the second thing to establish:

Whether a runtime-created field is supposed to be readable at all, and by what path. allowRuntimeCreate: true says the write is sanctioned; it does not by itself say the read path was ever built. ⚠️ If the honest answer is "this capability was declared but never implemented", that is a finding and possibly a needs-user-decision, not a bug to patch quietly.

That is exactly what came back. So the card's framing — "an accepted field PUT never reaches the object" — describes a real symptom but implies a broken link in an existing chain. There is no chain. The registry declares field with allowRuntimeCreate: true, the write door honours it, the row persists with valid=true, and nothing was ever written to serve it.

⇒ Fixing "the bug" means building a capability, which is a different size and a different decision.

The question for the maintainer

Is runtime field creation a capability this platform intends to have?

• Yes ⇒ this is a build, not a patch — it needs its own card, scoped as new work, with the read path designed rather than repaired. And valid=true on a row nothing consumes needs deciding too: does that flag assert well-formed, or in effect?
• No ⇒ then allowRuntimeCreate: true on field is declared-but-unenforced in the other direction — the platform accepts, persists and validates a write it can never honour. Under the repo's enforce-or-remove posture that argues for refusing the write, which is a much smaller change and turns a silent no-op into a loud one.

⛔ I am not choosing. Both readings are defensible, and the second is only obviously right if nobody intends the capability.

⚠️ Note the shape: "a 200 that means nothing happened" is the same failure family as #8018 (recordIdField not projected ⇒ "Revoke Session" reports success and revokes nothing) and the reassignOrphanedMetadata no-op behind #7780. Three instances today of an operation reporting success while doing nothing. That may be worth a convention rather than three separate rulings.

⚠️ Manual unlock owed — the blocker is a ruling, not a merged PR, so no sweep returns this card.

---

Generated by Claude Code