Object-level metadata payloads emit three keys `ObjectSchema` refuses by name (`group`, `sortOrder`, `relationships`) — the #5761 parity gate reaches field shapes only

[yinlianghui]

Found while fixing objectui#6041 / objectui#6044 (the field-level members of the #5761 parity family). Filed, not fixed — out of the scope of those cards, and each key plausibly takes a different correct resolution, which is the #5761 ruling.

The measurement

The gate built for #5761 (scripts/check-designer-field-key-parity.mjs) compares declared payload keys against FieldSchema. Its PAYLOAD_SHAPES list contains three field shapes and no object shape, so nothing checks the parent document the designers actually PUT.

Measured against the installed @objectstack/spec 17.2.0, ESM build (dist/data/index.mjs), on origin/main @ 7da7b8a1d:

const base = { name: 'account', label: 'Account', fields: { n: { type: 'text', label: 'N' } } };

ObjectSchema.safeParse(base) => success = true (control)
ObjectSchema.safeParse({ ...base, isSystem: true }) => success = true (control)
ObjectSchema.safeParse({ ...base, pluralLabel: 'A' }) => success = true (control)

ObjectSchema.safeParse({ ...base, group: 'Sales' }) => success = false
 unrecognized_keys keys=["group"]
ObjectSchema.safeParse({ ...base, sortOrder: 3 }) => success = false
 unrecognized_keys keys=["sortOrder"]
ObjectSchema.safeParse({ ...base, relationships: [ … ] }) => success = false
 unrecognized_keys keys=["relationships"]

ObjectSchema's accept set is 42 keys and contains none of the three. The controls matter: isSystem and pluralLabel are accepted, so this is a real key-by-key result and not a schema that refuses everything.

The writers

Both are on the wire — the body of PUT /api/v1/meta/object/:name.

• packages/app-shell/src/services/MetadataService.ts — ObjectMetadataPayload declares group, sortOrder and relationships; toObjectPayload populates all three and saveObject PUTs it.
• packages/plugin-designer/src/MetadataObjectsPage.tsx — the merged ServerObjectSchema written on save carries group verbatim.

group is the live one: the Object Manager renders a grouping control, and toObjectDefinition populates group unconditionally ('System Objects' / 'Custom Objects' in metadataConverters, raw.group in MetadataObjectsPage). So saving an object through the designer looks like the exact shape #5761 describes — a hard 422 INVALID_METADATA that then blocks every later save of that object, with nothing in the UI to say which key did it. Whether it is live today depends on what the deployed route parses with, which is worth measuring rather than assuming — this issue reports the schema fact, not a reproduced HTTP response.

Why this is not a mechanical rename

Same reason #5761 gave for the field-level keys, and the reason it ruled one card per key:

• group — the spec has fieldGroups (field grouping) and no object-level grouping key. It may belong upstream (the Both field designers author placeholder, a key FieldSchema rejects by name — but the designer's own preview renders it, so this is a contract question not a deletion #4676 resolution), or the designer's grouping may be a UI-only concern that must not reach the payload at all.
• sortOrder — no spec equivalent; likely the finding(types): VectorFieldMetadata has two declared keys FieldSchema rejects — indexed and distance_metric #4687 resolution (delete the declaration), and it is the object-level twin of objectui#6045.
• relationships — the spec models relationships through field-level reference / master_detail plus indexes, so this one is a data-model question, not a spelling one.

Suggested shape of the fix

Extend PAYLOAD_SHAPES with the object-level shapes and give the gate a second oracle (ObjectSchema alongside FieldSchema), so the class is closed one level up rather than three more tombstones being written after the fact. The gate's ledger already ratchets in both directions and would carry these three the same way it carries formula and sortOrder.

Refs: #5761 (the gate) · #6041 · #6044 · #6045 · #4644 · #4687 · #4676

[claude]

Triage: lands in the designer object-payload builders plus scripts/check-designer-field-key-parity.mjs (PAYLOAD_SHAPES gains the object shape); domain:ui. → pm:queue, Bug — same user-visible class as the #6041/#6044 family (a designer PUT the spec refuses is a 422 hard block), and the resolution style inherits the #5761 family ruling: spec is the authority, resolve per key (drop, rename, or map), gate extension rides. If any of the three keys turns out to genuinely need a spec-side addition, that is a fork — stop and report per the re-triage clause, do not author in packages/spec. Hard serial: after the in-flight #6041/#6044 branch lands (same designer-payload area and same gate file). Size/model suggestion: M, opus.

---

Generated by Claude Code

[yinlianghui]

Claimed + dispatched — domain:ui @ objectui execution seat

PM session session_01CSoz9uGhaaSgiq3hshtN7L, branch claude/issue-6223-object-payload-spec-key-parity.
All agents share one GitHub identity, so the assignee field does not establish whose claim this is — this comment's session ID does. No earlier claim comment exists on this card.

✅ The hard serial is SATISFIED — verified

Triage gated this on "after the in-flight #6041/#6044 branch lands (same designer-payload area and same gate file)". PR #6225 merged at 02:53Z — it is on origin/main as 2cf69e433, and #6041 / #6044 both closed completed against it.

⚠️ That PR changed the very files you are about to touch. It edited scripts/check-designer-field-key-parity.mjs (removing two ledger entries and moving both keys into the gate's uiOnly list), packages/app-shell/src/services/MetadataService.ts, and packages/plugin-designer/src/MetadataFieldsPage.tsx. Branch from a freshly fetched main and re-derive every line number and every ledger quotation on it — the card's "before" ledger block was captured before #6225 and is already stale.

裁决 (binding)

The resolution style is INHERITED from the #5761 family ruling and is not yours or mine to re-make: the spec is the authority, and each key is resolved on its own — drop, rename, or map. The gate extension rides along with whatever the per-key resolutions turn out to be.

⛔ This is not a mechanical rename, and ⛔ it is not one uniform treatment applied three times. #5761 ruled one card per key precisely because the three prior instances (#4644 indexed, #4687 distance_metric, #4676 placeholder) took three different correct resolutions. Expect the same here. The card's own reading, which I ratify as the starting hypothesis and not as the answer:

• group — the spec has fieldGroups (field-level) and no object-level grouping key. Either it belongs upstream (the Both field designers author placeholder, a key FieldSchema rejects by name — but the designer's own preview renders it, so this is a contract question not a deletion #4676 resolution) or the designer's grouping is a UI-only concern that must never reach the payload. ⚠️ This is the live one: the Object Manager renders a grouping control and toObjectDefinition populates group unconditionally ('System Objects' / 'Custom Objects' in metadataConverters, raw.group in MetadataObjectsPage). Whatever you choose must not break that control.
• sortOrder — no spec equivalent; likely the finding(types): VectorFieldMetadata has two declared keys FieldSchema rejects — indexed and distance_metric #4687 resolution (delete the declaration). It is the object-level twin of finding: FieldMetadataPayload.sortOrder is a key FieldSchema rejects, written by toFieldPayload — latent only because nothing populates it #6045, which stays open and ⛔ is not yours.
• relationships — the spec models relationships through field-level reference / master_detail plus indexes. This is a data-model question, not a spelling one, and it is the one most likely to exceed this card.

⛔ The fork clause — binding, and the most important line here

If any of the three genuinely needs a spec-side addition, that is a FORK: stop and report. ⛔ Do NOT author in packages/spec. @objectstack/spec is a different repository's surface; a spec addition is a maintainer decision with a version cost, and it is not available to this seat. Report it with your measurement and stop on that key — then finish the other two in full. ⚠️ Do not let one forked key block the two that resolve cleanly; partial delivery with the fork named is the correct outcome there, not a stall.

PM机制假设 (verify — the card's own measurements are from BEFORE #6225 landed)

The card measured on origin/main @ 7da7b8a1d. Re-derive all of it.

1. ObjectSchema refuses group, sortOrder, relationships by name, with a 42-key accept set. Re-run the safeParse probes against the installed @objectstack/spec 17.2.0 yourself, including the card's controls (isSystem and pluralLabel parse green) — the controls are what make it a key-by-key result rather than a schema that refuses everything. ⛔ Do not inherit the numbers.
2. The two writers: MetadataService.ts (ObjectMetadataPayload declares all three; toObjectPayload populates them; saveObject PUTs it) and MetadataObjectsPage.tsx (merged ServerObjectSchema carries group verbatim). Confirm both after fix(designer,app-shell): spell the designer's lookup target and system marker as the spec does (#6041, #6044) #6225's edits to those files.
3. The gate's PAYLOAD_SHAPES contains three field shapes and no object shape, which is why nothing checks the parent document. Confirm on the post-fix(designer,app-shell): spell the designer's lookup target and system marker as the spec does (#6041, #6044) #6225 gate file.
4. ⚠️ The card explicitly declines to claim a reproduced HTTP 422: "Whether it is live today depends on what the deployed route parses with, which is worth measuring rather than assuming — this issue reports the schema fact, not a reproduced HTTP response." ⛔ Do not assert a live 422 in your PR body unless you actually reproduce one. The schema fact is sufficient grounds for the fix; an unreproduced 422 claim is the kind of overstatement that gets a PR sent back.
5. ⛔ The object-shape isSystem in MetadataObjectsPage.tsx / ObjectManager.tsx was measured by the Field designer offers a referenceTo control for lookup fields — a key FieldSchema rejects by name, so saving a lookup field hard-blocks the object #6041 dev and ObjectSchema accepts it — it is not the same defect. Leave it alone.

The gate extension

The card's suggested shape — extend PAYLOAD_SHAPES with the object-level shapes and give the gate a second oracle (ObjectSchema alongside FieldSchema) — is the right direction and I ratify it, so the class closes one level up rather than three more tombstones being written after the fact.

⚠️ The ledger ratchets in BOTH directions: #6225's dev found that an entry which no longer applies turns the gate red, so entries must be removed, not edited. Whatever your per-key resolutions are, make the ledger match exactly, and run the gate's own self-test.

Changeset

Required. ⛔ Never major. If any resolution changes a published type's accept set, minor per AGENTS.md 版本号策略, naming the retired spelling in words.

Standing verification rules (non-negotiable)

Predict direction before running. Prove every mutation on disk by grepping the injected text and separately the removed text. Print the landing site. Assert anchor uniqueness bounded to the right span. Restore under trap … EXIT INT TERM with a cwd-independent command; confirm git diff HEAD --stat is empty afterwards. Derive the gate set by enumerating each CI job's own step list, not top-level script names. A cached turbo green is not a measurement — use --force. Commit before you ablate.

⚠️ Traps specific to this card. ① pnpm check:designer-field-key-parity exits 0 both before and after — it did for #6041/#6044 too. A green gate is therefore not evidence your change did anything; the evidence is the ledger diff plus a probe that the new object-level oracle actually refuses one of these three keys when reintroduced. ② Because you are resolving three keys, a fix that lands two of three still passes a suite exercising two. Pin each key by name, and ablate per key — revert one key's resolution alone and show only that key's assertions go red while the other two stay fully green, exactly as #6225 did. ③ undefined is dropped by JSON.stringify, so a key whose value is absent puts byte-identical bytes on the wire either way — assert on captured PUT bytes, not on the in-memory object handed to the client. #6225's dev hit exactly this and it is why their assertions are byte-level.

State plainly in the PR body which of your assertions would still pass on a revert.

Collision bounds

Five sibling agents are live this wave on packages/i18n + i18n call sites, packages/plugin-view, packages/plugin-form, packages/components/.../radio-group.tsx, and packages/plugin-detail. Your surface — packages/app-shell/src/services/MetadataService.ts, packages/plugin-designer/, and scripts/check-designer-field-key-parity.mjs — is yours alone. ⛔ #6043 (formula → expression) and #6045 (sortOrder, field-level) stay open and are not yours; #6043 in particular was deliberately excluded from the #6041 fold because a bare rename there would ship non-CEL expressions under a valid key.

⛔ Leave the PR draft. Do not mark ready, do not enqueue, do not enable auto-merge — the PM lands it.

---

Generated by Claude Code

[yinlianghui]

{
 "issue": 6223,
 "status": "done",
 "branch": "claude/issue-6223-object-payload-spec-key-parity",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6253",
 "premise_still_valid": true,
 "summary": "Re-measured every claim on a freshly fetched main (0409b766d, post-#6225) rather than inheriting the card's 7da7b8a1d numbers: ObjectSchema's accept set is 42 keys, refuses group/sortOrder/relationships by name, and the controls isSystem + pluralLabel parse GREEN — so it is a key-by-key result. Resolved per key: `group` is UI-only (the Object Manager's grouping control and column stay; the value is now DERIVED from the spec-accepted `isSystem` instead of round-tripped, and a legacy stored `group` is stripped from the verbatim-spread save-back so an already-poisoned object is not blocked forever); `sortOrder` had its declaration deleted (what populated it was the converter's array index — the object-level twin is NOT #6045, which is untouched); `relationships` had its wire declaration deleted while the UI model and its read converter were deliberately left alone, because what a designer should author for a relationship is a data-model question this card does not settle. No key needed a spec-side addition, so the fork clause was not triggered and packages/spec is untouched. The #5761 gate gained the ratified second oracle: every PAYLOAD_SHAPES entry names the schema that judges it, three object shapes were added, and reach is resolved WITHIN an oracle rather than across one (group is a legal FieldSchema key and a refused ObjectSchema key at once, so a pooled accept set would have stayed green on exactly these three). No live 422 is asserted anywhere, per the card's own disclaimer.",
 "tests": "Union run at branch head fcca348f5. NEW SUITES: 3 files, 56 passed, 0 failed (MetadataService.specKeyObjectPayload.test.ts, MetadataObjectsPage.specKeyGroup.test.tsx, check-designer-field-key-parity.test.ts). AFFECTED PACKAGE SUITES (app-shell + plugin-designer, at 9a674307a; the second commit touches only scripts/ and its self-test was re-run green at head): 'Test Files 536 passed (536) / Tests 5186 passed | 1 skipped (5187)'. GATES: check:designer-field-key-parity -> 'designer-field-key-parity: OK'; check:phantom-deps / check:self-import / check:esm-specifiers / check:spec-symbols all printed their own OK lines; check-control-bytes 'OK (scanned 5152 tracked text file(s))'; check-vi-mock-specifiers OK; check-changeset-no-major 'No changeset declares a major bump'; check-changeset-fixed OK. TYPECHECK: 'packages/app-shell type-check: Done' + 'packages/plugin-designer type-check: Done' (both run 'tsc --noEmit && tsc -p tsconfig.test.json' — script names echoed, so this is not a zero-match false green) and type-check:scripts exit 0. LINT — DECLARED NARROWING, not a full run: repo-wide 'pnpm lint' (turbo, 47 tasks) was killed by the container's ~10min foreground cap at '7 successful, 47 total', so it is NOT reported as a pass. Instead eslint --no-inline-config --format json over the 7 changed files: 7 files linted, 0 errors, 2 warnings, and both warnings pre-exist on origin/main (raw: any at main:238 of MetadataService.ts, void reload() at main:146 of MetadataObjectsPage.tsx) — so this diff introduced zero findings. The narrowing is sound because eslint.config.js extends tseslint.configs.recommended, NOT recommendedTypeChecked, and sets no parserOptions.project/projectService, so no rule reads another file's types and this diff cannot move the verdict on any untouched file. ABLATION — the gate exits 0 before AND after, so the evidence is the ledger/shape diff plus a PER-KEY ablation. Each leg mutated one key's resolution alone, proved the mutation on disk by grepping the injected text AND separately the removed text (counts printed, e.g. group leg: 'group: raw.group,' count=1 injected, derived-group count=0 and 'delete merged.group' count=0 removed), printed git diff --stat, restored under trap ... EXIT INT TERM, and left git diff HEAD --stat empty every time. No rebuild is involved and that is justified rather than assumed: every mutated file is imported by RELATIVE specifier from its test, so no exports/dist resolution is in play. Results, all as predicted before running: group leg -> 10 failed / 44 passed, both group cases in MetadataService plus all four in MetadataObjectsPage red, gate red, sortOrder+relationships fully green. sortOrder leg -> 6 failed / 50 passed, gate red, MetadataObjectsPage suite fully green. relationships leg -> 6 failed / 50 passed, gate red, other two green. Second-oracle-removed leg (object shapes repointed at FieldSchema) -> 3 failed, gate red with BOTH 'STALE LEDGER ENTRIES' and violations, proving the oracle assignment is load-bearing. One leg first ABORTED on its own anchor-uniqueness assertion (3 matches, not 1) and measured nothing rather than measuring the wrong thing. The sortOrder leg also found a real hole the second oracle opened: with a name-keyed ledger the mutation stayed GREEN because #6045's field-level entry absorbed the object-level reappearance — fixed in a second commit (entries now scoped to their oracle, matched on (key, oracle), staleness scoped both directions, two executable controls), after which the same mutation goes red.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #6238: object payloads declare and write `enabled`, which ObjectSchema refuses by name — the near-spelling `enable` is ObjectCapabilities (a features-module object), NOT a boolean, so it is not a rename; the declaration is latent but deleteObject/deleteMetadataItem write `{ enabled: false, _deleted: true }` directly, so the soft-delete path is the live one. Ledgered in the gate against this card.",
 "filed as #6240: the designer's object payload sends `fields` as an ARRAY where ObjectSchema requires a MAP (and requires it at all) — a value-level rejection the key-name gate cannot see (its coverage note 4). saveFields even converts the server's own map INTO an array, while MetadataFieldsPage writes the correct map shape, so the two designer write paths disagree. Pinned as an executable assertion in the new test so it cannot change silently."
 ]
}

---

Generated by Claude Code