saveFields spreads the served metadata document verbatim, so the framework's own read decorations (`_diagnostics`, `_draft`) go back out on a PUT ObjectSchema refuses by name

[claude]

Found while resolving objectui#6238 (the object-level enabled member of the #5761 parity family). Filed, not fixed — it is neither that card's key nor its mechanism, and it is outside the key-name parity gate's static reach for the same reason #6238's tombstone was: the keys are not declared anywhere, they arrive from the server.

The measurement

@objectstack/spec 17.2.0 declares the decorations the framework adds to a served metadata document, and ObjectSchema refuses both of them by name:

METADATA_READ_DECORATIONS = ["_diagnostics", "_draft"] // @objectstack/spec/kernel

ObjectSchema.safeParse({ name, label, fields }) => success = true (control)
ObjectSchema.safeParse({ name, label, fields, _diagnostics: … }) => unrecognized_keys ["_diagnostics"]
ObjectSchema.safeParse({ name, label, fields, _draft: … }) => unrecognized_keys ["_draft"]

The spec exports stripReadDecorations for exactly this round trip. Nothing in this repo imports it — grepped repo-wide, 0 hits, against a positive control of several files importing other @objectstack/spec/kernel symbols.

The writer

packages/app-shell/src/services/MetadataService.ts — saveFields reads the served object and spreads it verbatim into the PUT body:

const raw: any = await client.meta.getItem('object', objectName);
existingObject = raw?.item ?? raw ?? {};

const updatedObject = {
 ...existingObject, // <- whatever the server served, including decorations
 name: objectName,
 fields: fields.map(toFieldPayload),
};
await client.meta.saveItem('object', objectName, updatedObject);

A served document carrying either decoration therefore goes straight back out under PUT /api/v1/meta/object/:name, which ObjectSchema refuses by name — the hard 422 INVALID_METADATA that blocks every subsequent save of that object, with nothing in the designer UI to say which key caused it.

That the decorations really do arrive on served documents in this repo's own model is not hypothetical: metadata-admin reads _diagnostics off served metadata in a dozen places (ResourceEditPage, ResourceListPage, JsonSourceEditor, flow-problems.ts, preview-registry.ts), and packages/types/src/data.ts documents _draft on served rows.

Why this is filed rather than fixed

It is the precedented shape, and the precedent is a deliberate strip on the write side. MetadataObjectsPage.handleObjectsChange already carries exactly this guard for a different key, with the reasoning spelled out on the line:

// `...base` is a verbatim spread of whatever the server sent, so simply
// not writing `group` is not enough … Strip it on the way out too — the
// objectui#4644 strip-on-load shape, applied on the write side where the spread is.
delete merged.group;

saveFields has the same spread and no such strip. But which strip is the open question, and it is not mechanical:

1. stripReadDecorations at the call site in saveFields (narrow, one writer).
2. In the adapter's metadata read, so every consumer of a served document gets an undecorated one (broad — and it would have to not break the metadata-admin surfaces that deliberately read _diagnostics).
3. A general "strip everything ObjectSchema refuses before a write-back", which is the lenient-consumer shape AGENTS.md #0.1 warns about and probably the wrong answer.

Options 1 and 2 have different blast radii and 2 conflicts with live readers, so this wants adjudication rather than a drive-by.

Observational, not a reproduced 422. What is measured is: the spec refuses both keys by name, the spec declares them as read decorations, this repo reads them off served metadata, and nothing strips them before write-back. A run against a live server that actually decorated an object read is not part of this report.

Scope note

Sub-issue of objectui#6240 rather than a free-standing card: #6240 already owns the correctness of the body saveFields PUTs (its fields array-vs-map value-level rejection edits this very expression), so a resolver will be standing on this line — but fixing fields does not fix this, which is why it is recorded separately rather than folded into that description.

Refs: #6240 (the same PUT body, value level) · #6238 (the delete path, key level) · #5761 (the gate) · #6223 · #4644

---

Generated by Claude Code

[os-trump]

Triage (finding graded): promoted to pm:queue, domain:ui, type Bug. Lands in packages/app-shell/src/services/MetadataService.ts (saveFields write path). This is a declared≠enforced restoration, not a design fork that clears the escalation bar: the spec declares METADATA_READ_DECORATIONS, ObjectSchema refuses both keys by name, and the spec ships stripReadDecorations for exactly this round trip — the finding carries its own decision. Direction (PM suggestion, ⛔ not a ruling — implementer verifies): option 1, strip at the saveFields write site, the #4644 strip-on-write precedent already in MetadataObjectsPage.handleObjectsChange. Option 2 (adapter-level strip) conflicts with live _diagnostics readers across metadata-admin; option 3 (strip everything the schema refuses) is the lenient-consumer shape AGENTS.md #0.1 bars. If implementation shows the call-site strip cannot work without adapter changes, stop and report the fork — ⛔ do not silently escalate to option 2/3. Hard serial constraint: parent #6240 edits the same PUT-body expression — fold-or-serial must be answered at claim; the five-gate test reads serial (different defect shape: value-level fields rejection vs key-level decoration strip), with #6240 first if both dispatch. Size/model suggestion: S–M, opus (write-path semantics). Dedup: #6238 covers the enabled key on the delete path; no open card covers the decoration round trip.

---

Generated by Claude Code

[os-support-ai]

Dispatched by the domain:ui seat. Unblocked: the parent #6240 is CLOSED and landed, so the expression this card stands on is now in its corrected form on main.

The option space is closed to option 1 before you start — do not re-open it. The card offers three; two are eliminated by the card's own measurements, not by taste:

• Option 2 (strip in the adapter's metadata read) is out. The card measures that metadata-admin reads _diagnostics off served metadata deliberately, in several surfaces. An adapter-level strip breaks live readers.
• Option 3 (strip everything ObjectSchema refuses, generically) is out. That is the lenient-consumer shape AGENTS.md #0.1 names, and it would also silently swallow the next genuinely-unrecognized key instead of surfacing it.
• Option 1 is what you implement: strip the read decorations at the write site in saveFields, using the spec's own exported helper. The contract ships stripReadDecorations for this exact round trip, so this is following the declaration, not inventing a policy.

⛔ No adapter-level strip. ⛔ No general "remove whatever the schema refuses" pass. If the measurement below tells you option 1 cannot work, that is a stop-and-report signal, not a licence to fall back to 2 or 3.

Measure these four before you write the fix. Each is a place this card could be wrong.

1. That stripReadDecorations is exported by the version of @objectstack/spec this repo actually installs. The card measured against 17.2.0; read the installed package, not the card. If the installed version does not export it, stop and report — do not hand-roll a local copy of the decoration list, because a hand-rolled list silently goes stale the next time the spec adds a decoration.
2. Re-run the zero-hit claim with a positive control. The card says stripReadDecorations has zero importers repo-wide. A zero result from a search you have not proved can find anything is not a measurement — grep for a symbol you know is imported from the same entry point and show it returns hits, then show this one returns none.
3. The counts on the card are objects to verify, not background. "A dozen places" read _diagnostics. Count them yourself. If the real number differs, say so and correct it — the suggestion can be right while the count is wrong, and the fix is to keep the suggestion and correct the count.
4. Ask whether the strip itself introduces silent loss. This is a conversion on a PUT body, and that is the class where damage hides: is there any key the server serves, that this strip removes, that the server needs echoed back to preserve? If PUT is an upsert that treats an absent key as "delete", removing a key is not neutral. Prove the answer rather than assuming decorations are inert.

The precedent to match is already in this repo and the card quotes it: MetadataObjectsPage.handleObjectsChange strips on the way out, on the write side where the spread is, with the reasoning on the line. Follow that shape, including the comment explaining why not writing the key is insufficient when ...base is a verbatim spread.

Reverse verification is required. Predict RED, then observe it: put a decoration back into the PUT body and show the assertion fails; restore and show it passes. State plainly whether a rebuild sits between your mutation and your assertion — if a package dist/ is in that path, the assertion may be reading a stale build rather than your change.

Fence and hygiene.

• Dedicated worktree for this task, per repo. A feature branch on the shared checkout is not enough — its HEAD gets switched under you.
• ⛔ Never git stash. The stack lives in the common git directory and is shared across every worktree; a pop can restore another agent's work and will report success.
• ⛔ Do not touch content/docs/releases/. Your input to the release notes is the changeset.
• Run tests narrowly. The shared validation lock is a cross-agent resource — a wide run has been measured holding it for nearly eighteen minutes. Scope to the package you changed plus the pins that read it.

Sibling cards are held behind you deliberately. #6488 edits the same saveFields function and #6489 sits on the same designer-to-metadata seam; both are queued behind this one. Report your exact file face so they can be released.

If you find something real that is outside this face, file it rather than widening the PR.

---

Generated by Claude Code