finding(app-shell): `saveObject` called without `existingFields` still PUTs a body `ObjectSchema` refuses — `fields` is REQUIRED, and `{}` is not a safe default

[claude]

The severable half of objectui#6240, recorded as its own card because the resolution is a public-signature judgement rather than a shape conversion.

The measurement

ObjectSchema.fields is not merely typed, it is REQUIRED. Measured against the installed @objectstack/spec 17.2.0:

ObjectSchema.safeParse({ name: 'account', label: 'Account' })
 => success = false invalid_type @ fields ("expected record, received undefined")

objectui#6240 fixed the SHAPE: when a caller passes existingFields, toObjectPayload now emits the name-keyed map and the body parses. When a caller does NOT pass it, fields is omitted and the body is still refused — unchanged from before that card, and deliberately so.

Why objectui#6240 did not simply default to {}

Because {} parses green and PUT /api/v1/meta/object/:name is an UPSERT. Emitting {} for a caller that just did not supply the argument would land as "this object has no fields" and delete every field of the object on a save that only meant to rename it — trading a loud, harmless 422 for silent data loss. That is pinned as a positive control (omits fields entirely when the caller supplied none — it does NOT write {}), with an ablation showing that defaulting to {} reds that one case.

The decision this needs

saveObject(obj, existingFields?: FieldMetadataPayload[]) is public API — MetadataService is reachable from app-shell's entry through useMetadataService(): MetadataService | null, so its signature is part of the published surface even though the class is not re-exported by name. Three readings, none of them free:

1. Make the fields argument required. Honest — the method cannot write a valid document without it — but a breaking signature change for any consumer calling saveObject(obj).
2. Fetch and merge, the way saveFields already does. saveFields GETs the current document and spreads it, so an object save could preserve the stored fields instead of asking the caller to hand them back. Costs a request; makes the parameter redundant, which then wants retiring on its own terms (ADR-0049 shape).
3. Leave it and refuse client-side. Throw before the request when no fields are supplied, so the author gets the diagnosis without a round trip. Same outcome as today, better message, still a behaviour change for callers relying on the request being issued.

No in-repo caller passes existingFields at all today (the only call sites are tests), so the population this breaks is entirely external consumers — which is what makes it a judgement rather than a mechanical fix.

Refs: objectui#6240 (the shape half, landed) · objectui#5761 (parity family, coverage note 4)

---

Generated by Claude Code

[os-trump]

Triage(小时轮 2026-08-26,session session_01QBLkaj4aAPMVk6ddNFpCgB):入决策箱 —— needs-user-decision + domain:ui,type Feature(公开签名/行为变化,人工地板)。落卡即补标准四棱块。

四棱卡面块(决策:saveObject 缺 existingFields 时的公开签名处置)

业务角度解释:app-shell 的 MetadataService.saveObject(obj) 不带字段参数时,发出的 PUT 必被 spec 拒(fields 为必填)。#6240 已修好「带参数时的形状」,并刻意不默认 {} —— 因为 {} 能通过校验并会把对象的全部字段静默删光(UPSERT 语义)。剩下的问题:这个公开方法「不带参数」的路径今天恒 422,要不要、以及怎么把它变诚实。仓内无生产调用方(只有测试调用),受影响面全部是外部消费者。

选项与真实代价:

1. 把参数改必填 —— 签名层面诚实(方法没有字段就写不出合法文档);对外部是编译期破坏,但被破坏的调用在运行期本来就恒 422 —— 只破坏已经坏的代码。
2. fetch-and-merge(照 saveFields 的既有做法) —— 不带参数的保存真正可用(改名不用回传字段);代价一次请求,且参数从此冗余、又要按 ADR-0049 走退役,是最大的一条改动链。
3. 保留签名、客户端在发请求前响亮拒绝 —— 省一次往返、报错更可读;但把一个永远失败的参数形状永久留在公开面上。

四维分析:

• 实际业务需求:无实测外部拉动(仓内零生产调用);今天撞到的人得到的是响亮 422,不是静默损伤 —— 无「正在流血」的场景。
• 项目长远合理性:选项 2 与 saveFields 模式一致,但为一个无人拉动的路径增加能力与退役义务;选项 1 让声明与强制一致,契约最干净。
• 防 AI 写代码犯错:选项 1 结构性最优 —— AI 在编译期就写不出会 422 的调用;选项 3 是运行时护栏(次优);选项 2 属于消费端宽容,恰是掩盖批量错误的温床。
• 创业阶段不扩散需求:选项 1 改动最小、零新能力;选项 2 是能力扩张,零消费者拉动下默认从紧。

推荐:1(参数改必填,一次 breaking-in-name-only 的签名收紧;changeset 里写明「原不带参调用本就恒 422」)。若维护者希望「改名不回传字段」成为真实能力,则 2 是正确形状,但建议等有真实拉动再做。推荐是输入不是放行,本卡恒交维护者。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — Option 1/A: the fields argument becomes required

Provenance: maintainer, 2026-08-27, PM chat decision-inbox batch 4 (adjudication session session_01DKWDdUJ2XNRESVVWUvcpnh), verbatim: 「其他接受」 — accepting the triage recommendation (2026-08-26T05:54Z facet block).

Ruled: saveObject's fields argument becomes REQUIRED — a compile-time tightening that only breaks calls which were already a guaranteed 422 at runtime (breaking-in-name-only). ⛔ Options declined, recorded so neither is implemented as a shortcut: fetch-and-merge (option 2) builds capability for a zero-pull path and makes the parameter redundant; defaulting to {} stays forbidden per objectui#6240's own pin — {} parses green and, under the UPSERT, deletes every field of the object on a save that meant to rename it.

Dispatch notes: changeset states in words that previously-omitted-argument calls were already a guaranteed 422 (behaviour unchanged at runtime, signature now honest); the objectui#6240 positive control ("omits fields entirely when the caller supplied none — it does NOT write {}") moves with the signature rather than being deleted; Clause-② judged at claim time by the dispatching seat (a published-surface signature narrowing whose runtime accept/reject behaviour is unchanged — the maintainer ruling here is the authority for the narrowing itself).

State: needs-user-decision → pm:queue.

---

Generated by Claude Code