rest/metadata-protocol: one unique conflict, two wire spellings on ONE route — a batch/import ROW reports `DUPLICATE_RECORD` while the whole-request failure on the same route reports `UNIQUE_VIOLATION`

[os-trump]

Filed under the contract review on #14541 (verdict PASS WITH CONDITIONS, condition 2), which required the residue to be disclosed and given a card rather than implied away. ⛔ This card does not pick a winner; that is the decision it exists to carry.

The fork

Two spellings of one condition — a driver's unique-constraint refusal — reach a client on the same route, chosen by whether the failure was whole-request or per-row.

Row level — DUPLICATE_RECORD. packages/metadata-protocol/src/protocol.ts's toRowApiError puts a thrown REGISTERED code on the row verbatim (ErrorCode.safeParse(err.code).success ? err.code : …), so a DuplicateRecordError raised for one row of POST /api/v1/data/:object/batch or POST /api/v1/batch reports code: 'DUPLICATE_RECORD', httpStatus: 409. Pinned at packages/runtime/src/batch-row-driver-text-real-driver.integration.test.ts:282. packages/rest/src/import-runner.ts:293 (first?.code ?? e?.code ?? 'IMPORT_ROW_FAILED') does the same for import row reports, and #14095's changeset records that as deliberate ("Import row reports improve … now DUPLICATE_RECORD").

Whole-request level — UNIQUE_VIOLATION. The single-record /data door has answered UNIQUE_VIOLATION since #6250/#7821, and #14389 restored it there for the envelope; #14541 restores it on the bulk / import / metadata / UI doors. So after #14541 a whole-request failure on POST /data/:object/batch or POST /data/:object/import answers UNIQUE_VIOLATION while a row-level failure on that same route answers DUPLICATE_RECORD.

Neither half is a regression and neither was introduced by #14541 — the fork has existed between the single door and the rows since #14389. What #14541 does is move the UNIQUE_VIOLATION side onto the routes whose ROWS speak the other spelling, so the two now sit side by side in one response for the first time, and that is why it wants deciding rather than living on.

The text this sits against

packages/spec/src/api/error-code-ledger.zod.ts's header:

a code either IS the standard member for its condition, or it is registered here — and if it merely re-spells a standard member, that registration is a recorded waiver

There is no waiver pairing UNIQUE_VIOLATION with DUPLICATE_RECORD, and standardSynonymOf('UNIQUE_VIOLATION') answers undefined because the token prong under-matches by design. ADR-0112's "one name per concept" is the other half.

What a decision has to weigh (not decided here)

• DUPLICATE_RECORD wins. It is what an application is told to branch on for the engine envelope (DuplicateRecordError's own docblock: "branch on code === 'DUPLICATE_RECORD' (ADR-0112) rather than on a dialect's code or message"), and it is already what the rows say. Cost: it moves the wire code on the single-record door, which mapDataError has no DUPLICATE_RECORD arm: the engine's insert conflict envelope reaches the wire through the generic passthrough, dropping the field key and the user-facing conflict sentence #14389 explicitly refused to do on the grounds that "every consumer branching on this conflict today reads UNIQUE_VIOLATION, and renaming a wire code under existing consumers is a published-contract change, not a door's call".
• UNIQUE_VIOLATION wins. It is the published spelling — content/docs/protocol/kernel/http-protocol.mdx documents the 409 "Constraint Violations" body with it, it is the standard-catalog member, and it is what the doors answer. Cost: it moves the row-level code that An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app #14095 deliberately introduced, and the row pin above changes.
• Both stay, with a recorded waiver. Cheapest, and the ledger header names it as a legitimate shape — but it fixes the ADR-0112 objection by declaring the duplication rather than removing it, on a surface where the two spellings now appear in one response body.

Not claimed

• No measurement here says a consumer is broken today. Both codes are registered, both bodies parse, and the fork is stable rather than newly introduced.
• I did not census out-of-repo consumers of either spelling.

[huangyiirene]

Triage — graded p2, needs-user-decision, routed domain:spec. Applied and read back first.

domain:spec because all three outcomes land on packages/spec/src/api/error-code-ledger.zod.ts — a waiver is a ledger entry, and either convergence moves a catalog member. That anchor holds whichever way it is ruled; the door and row sites follow from it.

<!-- os-decision-facets -->

四棱分析(分诊席出具,供裁决)

① 长期健全性(权重 ≥50%,主导)—— 指向「收敛到一个名字」,反对豁免。 ADR-0112「一个概念一个名字」与台账自己的表头(「若只是重拼一个标准成员,那条注册就是一份记录在案的豁免」)是同一条规则的两半。⭐ 关键在于 #14541 之后两种拼法第一次同时出现在一个响应体里 —— 豁免能消掉规则上的反对意见,却消不掉「同一个响应里两个名字指同一件事」这个事实。①⛔ 不支持第三选项。

② 真实业务拉力 —— 微弱,方向偏 UNIQUE_VIOLATION。 没有实测到任何消费者今天是坏的,分叉是稳定的而非新引入的。但已发布文档用的是 UNIQUE_VIOLATION(content/docs/protocol/kernel/http-protocol.mdx 的 409「Constraint Violations」体),它也是标准目录成员、也是各扇门今天的答案 —— 一个照文档接的外部集成方会分支在它上面。

③ 防 AI 编码错误 —— 强,且指向「必须收敛」。 现状里平台自己在说反话:DuplicateRecordError 的 docblock 教作者「branch on code === 'DUPLICATE_RECORD'(ADR-0112)」,而同一条路由的整请求失败答的是 UNIQUE_VIOLATION。⚠️ 无论裁哪个名字,那句 docblock 都必须同笔修正 —— 它现在是一条平台自我否证的指令,这是本卡最便宜也最容易漏掉的一半。

④ 创业阶段不增殖 —— 明确反对豁免。 豁免把两种拼法永久化并额外增加一条注册项;收敛是净减。

建议:收敛到 UNIQUE_VIOLATION,移动行级码。 理由不是它「更好」,而是不对称:#14389 已经就另一个方向立过一条站得住的理由 ——「今天分支在这个冲突上的每个消费者读的都是 UNIQUE_VIOLATION,在既有消费者底下改线上码是已发布契约的变更,不是某扇门自己能决定的」。那条理由至今成立;而行级码更新、更窄(仅 batch/import 的行),#14095 引入它是刻意的、但影响面小得多。同笔:改 DuplicateRecordError 的 docblock,翻转 batch-row-driver-text-real-driver.integration.test.ts:282 的钉子,并核 import-runner.ts:293。

回退:记录在案的豁免。 若维护者判断移动行级码的破坏面不可接受,那就走台账表头明写认可的那条路 —— 但豁免必须写明为什么两种拼法必须共存,而不只是记录它们共存。⛔ 三个选项里唯一不可接受的是维持现状不作声明:那正是台账表头与 ADR-0112 共同禁止的形状。

⚠️ 置信缺口(必录): 我没有、也无法做仓外消费者普查 —— 两种拼法各自被哪些外部集成方分支,我读不到,而这正是「移动哪一个更便宜」的决定性数字。卡面自己也声明未做这项普查。裁决前若能对 hotcrm / objectui 各扫一次两种码的出现,建议是可以被推翻的。

落卡

⛔ 本卡不选赢家 —— 卡面自己就是这么写的,而且是对的。⭐ 值得留档的是它为什么现在必须裁:两半都不是回归,#14541 也没有引入任何一半;它做的是把 UNIQUE_VIOLATION 那一侧挪到了行已经说另一种拼法的路由上。分叉从「两扇门不一致」变成「一个响应体内不一致」,这是量变到质变的那一步。

⛔ 不要把这张卡折进 #14541。那张卡的 PASS WITH CONDITIONS 第 2 条要求的正是「披露并给一张卡」,而不是「顺手解决」。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — A: converge on UNIQUE_VIOLATION; a batch/import ROW reports the same wire code as the whole-request failure on the same route, and DuplicateRecordError's docblock stops teaching the other spelling

Director seat (objectstack #12708), summon #10, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-03.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, replying to decision batch #16 in which this card was item 2 with the recommendation A (fallback C: a recorded waiver; B, converging on DUPLICATE_RECORD, refused on #14389's standing reason), the same recommendation triage attached in 5518018636. Verbatim reply: 「同意，然后执行契约复审」 — "同意" adopts A.

Downstream measurement taken by the director seat before presenting (git grep, non-test sources): hotcrm and objectui carry zero consumers branching on either UNIQUE_VIOLATION or DUPLICATE_RECORD. The out-of-repo migration face is zero on both sides, so the cheaper side is decided by the published docs and the standard catalog, both of which spell UNIQUE_VIOLATION.

Ruled: A. A unique-constraint refusal has one wire spelling on every route: UNIQUE_VIOLATION, the standard-catalog member content/docs/protocol/kernel/http-protocol.mdx documents for the 409 constraint-violation body and what every whole-request door answers. Row-level reports on POST /api/v1/data/:object/batch, POST /api/v1/batch and the import runner report the same member instead of the engine's DUPLICATE_RECORD spelling. In the same stroke: DuplicateRecordError's docblock ("branch on code === 'DUPLICATE_RECORD'") is corrected to name the wire spelling a client branches on; the row pin at packages/runtime/src/batch-row-driver-text-real-driver.integration.test.ts:282 flips; packages/rest/src/import-runner.ts:293 is checked for the same mapping. No waiver entry is added to error-code-ledger.zod.ts: the duplication is removed, not declared.

Not taken: B (moving the single-record door's code under existing consumers — #14389's refusal stands), C (a recorded waiver that leaves two names for one concept in one response body).

Execution: domain:spec lane. A wire code on a published route changes ⇒ Clause-② yes, needs:contract-review on the card and the PR at CONTRACT_REVIEW_TIER; @objectstack/rest and @objectstack/metadata-protocol changesets (minor, BREAKING banner naming the row-level spelling that moves, under the launch-window convention). ⛔ Not folded into #14541: its PASS WITH CONDITIONS condition 2 asked for disclosure and a card, which this is.

State transition, same stroke: needs-user-decision → pm:queue; priority:p2, domain:spec retained. Ledger: objectstack director seat post #12708, summon #10.

---

Generated by Claude Code