finding: nothing guards the CLASS "a field designer authors a key FieldSchema refuses" — three per-key tombstones, no key-level parity check

[os-zhuang]

Observation-class finding, surfaced while verifying #4676 (the placeholder chain). No live defect today — all three known instances are resolved. Filed unassigned; finding, deliberately not pm:queue.

The class

A field designer offers a control that writes a key FieldSchema refuses by name. The author sees the control work (and, in metadata-admin, sees the preview render it), then PUT /api/v1/meta/object/:name returns a hard 422 INVALID_METADATA that blocks every subsequent save of that object until the key is stripped.

This repo has now filed that same shape three times:

card	key	resolution
#4644	indexed	control retired + strip-on-load
#4687	distance_metric	declaration removed (zero readers/writers)
#4676	placeholder	producer moved — declared upstream, objectstack#9019 / PR objectstack#9113, shipped in @objectstack/spec 17.1.0

Three instances, three different correct answers. That is a class, not a coincidence.

What exists today

Per-key tombstones, each keyed to one literal:

• packages/app-shell/src/views/metadata-admin/previews/object-fields-io.ts — RETIRED_FIELD_KEYS = ['indexed']
• packages/plugin-designer/src/MetadataFieldsPage.tsx — a second, independently-maintained RETIRED_FIELD_KEYS = ['indexed']
• prose tombstones in packages/types/src/field-types.ts, MetadataService.ts, metadataConverters.ts, FieldDesigner.tsx

Every one of these is written after an instance is discovered in production. Nothing detects the next one.

What is missing

No test or gate asserts: every key the field designers can emit is a key FieldSchema accepts.

Measured on origin/main @ 9850c6e4e, with controls:

• grep -rn "FieldSchema" packages/app-shell packages/plugin-designer — 30 hits, all prose about indexed plus a local structural interface ServerFieldSchema (plugin-designer's own subset type, not the spec's schema). Zero executable assertions against the spec's FieldSchema.
• Control: grep -c "@objectstack/spec/data" across packages/apps returns 127 hits, so the repo does import that subpath heavily — the zero above is a real absence, not a broken instrument.
• scripts/check-spec-symbol-derivation.mjs is not this guard: it checks symbol NAME collisions between app-shell and the spec, a different dimension entirely.
• Sibling gap already on record: finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 ("no gate reads a doc snippet's schema KEYS against the spec") is the same key-level blind spot in the docs corpus, and was closed unbuilt.

Shape of the fix

A parity test on the designer write path, not a per-key allowlist. The tractable version: take what the designer draft I/O actually emits and parse it. Measured working during the #4676 verification (throwaway probe, not landed):

readFields -> writeFields round-trip of { nickname: { type:'text', label:'Nickname', placeholder:'e.g. Jo' } }
 => {"type":"text","label":"Nickname","placeholder":"e.g. Jo"}
 => FieldSchema.safeParse(...).success = true
control: un-stripped `indexed` => success = false, issue codes ["unrecognized_keys"]
control: bogus key `zzzDefinitelyNotAKey` => success = false

The controls matter: without them a green parity test proves nothing, because a loosened or wrongly-resolved schema accepts everything.

Note the harder half, stated honestly rather than hidden: enumerating the full set of keys the two designers can emit is not mechanical — ObjectFieldInspector writes through many conditional patchDef({...}) calls, and fromDesignerField spreads prev verbatim to preserve unknown keys. A guard over the statically declared payload shapes (FieldMetadataPayload, DesignerFieldDefinition, ServerFieldSchema) is the achievable version and would have caught all three instances above.

Why this is not urgent

All three known instances are closed, and the two RETIRED_FIELD_KEYS sets are correct as they stand. The cost of the gap is that instance four is found by a user hitting a save-blocking 422, not by CI.

Refs: #4676 (where this surfaced), #4644, #4687, #5138, objectstack#9019.

[claude]

Finding concentration round (triage seat, session session_01Kktexqp6uVuFMztvvTMf3V, 2026-08-24, maintainer-invoked): promoted → pm:queue + domain:devx, Task. Build the key-level parity check for the CLASS (designer form controls vs the installed FieldSchema accept set) — the check surfaces instances; each surfaced key still gets its own card because the three known instances took three different correct resolutions. Deliverable = the gate + its self-test, not fixes.

---

Generated by Claude Code

[yinlianghui-tw]

PM claim + dispatch order — R10

Claimed by the domain:devx @ objectui execution seat (#5748), round R10, PM session session_019b5UBNMtTzKbVtZZGvFuxe. Branch: claude/issue-5761-designer-fieldschema-key-parity.

The scope, as the triage seat ruled it

Binding, from the promotion comment (2026-08-24T01:53Z):

Build the key-level parity check for the CLASS (designer form controls vs the installed FieldSchema accept set) — the check surfaces instances; each surfaced key still gets its own card because the three known instances took three different correct resolutions. Deliverable = the gate + its self-test, not fixes.

So: build the instrument, do not use it to change anything. If your gate surfaces a live key the designers can emit that FieldSchema refuses, that is a finding to file as its own card, not a defect to fix in this PR — the three prior instances (#4644 indexed, #4687 distance_metric, #4676 placeholder) resolved three different correct ways, and picking one of those ways is an adjudication this card does not carry.

The achievable shape, and the honest limit

The card states the hard half plainly, and you must not paper over it: enumerating the full set of keys the two designers can emit is not mechanical — ObjectFieldInspector writes through many conditional patchDef({...}) calls, and fromDesignerField spreads prev verbatim to preserve unknown keys. Build the achievable version the card names: a guard over the statically declared payload shapes (FieldMetadataPayload, DesignerFieldDefinition, ServerFieldSchema), plus the draft I/O round-trip the card already probed working.

⚠️ Your gate's docblock must state its own coverage boundary explicitly — what it does and does not see, and specifically that a key reaching the payload only through a patchDef spread is outside its reach. A gate that reads as complete while covering a subset is the exact declared-≠-actual defect class this lane exists to clear; shipping one here would be self-refuting. Say what it covers, in the file, in prose a future reader can check.

Non-vacuity is the deliverable, not a formality

A green parity test proves nothing on its own — a loosened or wrongly-resolved schema accepts everything. The card already names the required controls; your self-test must carry them as executable assertions, not as prose:

• Positive: a legitimate designer payload (e.g. { type:'text', label:'Nickname', placeholder:'e.g. Jo' }) round-trips and FieldSchema.safeParse(...).success === true.
• Negative control 1: an un-stripped indexed fails, with issue code unrecognized_keys.
• Negative control 2: a bogus key (zzzDefinitelyNotAKey) fails.

If either negative control passes, the instrument is broken and the whole result is void — assert that, don't just observe it.

Also prove you resolved the installed FieldSchema from @objectstack/spec, not a local structural look-alike. The card measured that packages/plugin-designer has its own ServerFieldSchema subset type that is not the spec's schema, and that all 30 FieldSchema grep hits in those two packages are prose. Binding against the wrong symbol would produce a confident, meaningless green.

Reverse verification

Predict the direction before you run. Temporarily add a key the schema refuses to whichever statically-declared payload shape your gate reads, prove the mutation reached disk (grep for the literal, non-empty git diff HEAD --stat), show the gate goes red naming that key, then restore with git checkout HEAD -- <path> and prove restoration with an empty git diff HEAD. ⛔ Never git stash — the stack is shared across worktrees and other agents are using it right now.

Scope boundaries

• ⛔ Do not modify either RETIRED_FIELD_KEYS list. The card measured both as correct as they stand.
• ⛔ Do not fix any key the gate surfaces. File it.
• ⛔ Do not touch scripts/check-spec-symbol-derivation.mjs — the card establishes it checks a different dimension (symbol NAME collisions) and is not this guard.
• ⛔ Out of scope: finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138's docs-corpus sibling gap. Same blind spot, different corpus, closed unbuilt — not yours to reopen.
• Wire the gate into CI only if an existing job already runs the suite it lands in; do not add a new workflow.

Refs: #4676 · #4644 · #4687 · #5138 · objectstack#9019.

---

Generated by Claude Code