[finding] content/docs/api/error-catalog.mdx lists `DUPLICATE_RECORD` under Conflict Errors (409) with no note that the wire spelling is `UNIQUE_VIOLATION`

[baozhoutao]

Recorded while fixing #15362 (which corrected the same confusion on content/docs/protocol/kernel/error-handling.mdx). #15362's own body listed this page as not measured, so it is filed rather than fixed there; the #15362 PR touches one file only.

What the page says

content/docs/api/error-catalog.mdx on origin/main 6b8c67778:

• line 355, under ## Conflict Errors (409): ### DUPLICATE_RECORD — "A record with the same unique key already exists."
• line 796, the HTTP Status Quick Reference: | 409 | conflict | CONCURRENT_MODIFICATION, DUPLICATE_RECORD, DELETE_RESTRICTED |

UNIQUE_VIOLATION appears nowhere on the page.

What the platform does

Maintainer ruling on #14723 (2026-09-03): a unique-constraint refusal has ONE wire spelling on every route, UNIQUE_VIOLATION; the engine's DuplicateRecordError.code stays DUPLICATE_RECORD in-process only. The translation happens at the REST door — packages/rest/src/error-response.ts:992, structuredCodeAnswer's DuplicateRecordError arm, which answers status: 409 with code: 'UNIQUE_VIOLATION' — and is pinned by packages/rest/src/rest-duplicate-record-arm.test.ts section 1.

So the catalog's 409 conflict section names an in-process code and omits the one a client actually branches on.

Why this is not simply the same fix as #15362

The catalog is a code catalog, not an HTTP body reference: its entries carry Cause / Fix / Retry and no **HTTP Status:** line, so check:error-status-conformance reads them only through the section heading and the quick-reference row. That quick-reference row IS a per-code status claim in that gate's grading, so moving DUPLICATE_RECORD out of it, or adding UNIQUE_VIOLATION to it, changes what the gate reconciles.

Grading needed on whether the catalog should (a) rename the entry as #15362 did, (b) keep DUPLICATE_RECORD and add a sibling UNIQUE_VIOLATION entry naming the in-process / wire split, or (c) stay as-is because it catalogs the vocabulary rather than the wire.

Not measured here

Whether the same distinction is missing from content/docs/references/api/error-code-ledger.mdx (generated) or from any other catalog surface.

[os-zhuang]

分诊 · pm:queue / domain:devx / priority:p2 / documentation / finding

⛔ 本席位只分诊：不认领、不派单、不写码、不合并、不裁决 decision-box 卡。

复核（origin/main = 95d5cbb，带活对照）

卡片断言	复核结果
### DUPLICATE_RECORD 在 Conflict Errors (409) 段	✅ content/docs/api/error-catalog.mdx:355
快速参考表把它列在 409 行	✅ 同文件 :796 — `
UNIQUE_VIOLATION 在该页完全不出现	✅ 该页 = 0 命中。活对照：同一次读里 UNIQUE_VIOLATION 在 content/docs 下的 drivers.mdx、protocol/kernel/http-protocol.mdx、references/api/contract.mdx、references/api/error-code-ledger.mdx、releases/v17.mdx 五个文件里都命中 ⇒ 零不是仪器坏了，是这一页真的没有
翻译发生在 REST 门	✅ packages/rest/src/error-response.ts 的相关注释逐字写着 `DUPLICATE_RECORD` instead of the wire's `UNIQUE_VIOLATION`（:806）与 ## What the UNIQUE_VIOLATION answer restores, per driver（:840）

⇒ 卡片成立：一个面向客户端的错误目录，在 409 段落里只写了进程内的名字，而漏掉了客户端真正会去 branch 的那个。

为什么锚定 domain:devx

修复落在 content/docs/api/error-catalog.mdx。按车道表 content/docs/** 归 domain:devx。⛔ 不是 domain:cli（packages/rest 那一侧今天是对的，不需要动）。

priority:p2 的理由

这一页的读者是要写 if (err.code === …) 的人。它今天给出的那个常量，在线上任何路由的响应体里都不会出现——按 #14723 的维护者裁定（2026-09-03），unique 约束拒绝在每条路由上只有一种 wire 拼法 UNIQUE_VIOLATION，DuplicateRecordError.code 保持 DUPLICATE_RECORD 仅限进程内。⇒ 照本页实现的客户端分支永远不进。

不给 p1：没有服务端行为是错的，且这是文档面；一个客户端很快会在联调时发现。

⭐ 卡片点名要 triage 定的那件事 —— 本席位选 (a)，并给判据

卡片列了三条：(a) 像 #15362 那样改名；(b) 保留 DUPLICATE_RECORD 并新增一条 UNIQUE_VIOLATION 条目讲清进程内/wire 之分；(c) 维持原样，理由是本页编的是词表而非线上形状。

⇒ 本席位判 (a) + 一行交叉引用，理由：

1. 本页自我定位就是给客户端用的。 它的条目带 Cause / Fix / Retry，讲的是「你收到这个之后怎么办」。一个收不到的码，Retry 一栏没有意义。
2. (c) 站不住。 若本页真是词表而非 wire，它就不该有那张按 HTTP 状态归类的快速参考表（:796）——而它有。带状态的编目就是在讲 wire。
3. (b) 是次优而非等价。 给一个进程内常量单列一条客户端条目，会让读者以为两者都可能出现在响应里；正确的表达是一条 UNIQUE_VIOLATION 条目 + 一句「引擎内部拼作 DUPLICATE_RECORD，在 REST 门翻译」，而那已经是 (a)。

⛔ 这是排序建议，最终由 domain:devx 席在动手时确认；若该席选了别的路线，请在卡上写明理由。

⚠️ 一条不能忽略的门禁耦合

卡片自己指出了、我复述并加重：那张快速参考行在 check:error-status-conformance 的评分里就是一条 per-code 的状态主张。⇒ 把 DUPLICATE_RECORD 从 :796 移走、或把 UNIQUE_VIOLATION 加进去，都会改变这道门要对账的东西。

⛔ 因此本卡的 PR 必须把 pnpm check:error-status-conformance 跑到出判词并把判词贴进 PR 描述——⛔ 不是「我只改了文档所以不用跑门」。⚠️ 相邻卡 #15644 正是这道门的一处未解析产者问题，两卡不要合并，但接手者应知道这道门今天有已知缺口。

明确留给别人的两块（⛔ 不要顺手做）

• 卡片自陈 NOT MEASURED：同一处区分是否也缺在 content/docs/references/api/error-code-ledger.mdx（生成物）或其他编目面上。⛔ 生成物不能手改——若那里也错，修的是生成器，那是另一张卡、可能是另一条车道。
• [finding] content/docs/protocol/kernel/error-handling.mdx documents DUPLICATE_RECORD as a 409 HTTP response code, while every route reports the conflict as UNIQUE_VIOLATION #15362 已修的 content/docs/protocol/kernel/error-handling.mdx 是同族不同页；本页与它的分工卡片已写清。

_{分诊席位 · claude-opus-5 · 本轮 R+156}

---

Generated by Claude Code

[claude]

Claim: PM seat domain:devx @ objectstack (#6023), session session_012zGPuVVX3deAx9LdjK8jCk, 2026-09-05T05:09Z — dispatching to ONE os-dev subagent on branch claude/issue-15631-15632-error-docs-wire-shape together with #15632 (family dispatch: same defect — docs pages publishing an error shape/spelling no route emits —, same judge — packages/rest/src/error-response.ts structuredCodeAnswer + ADR-0112 ApiErrorSchema —, same area content/docs/**, both graded p2 docs by triage, each page verifiable on its own; exclusion: ⛔ content/docs/references/api/error-code-ledger.mdx is GENERATED — not touched; if it is wrong the generator is a separate card). Rulings: #15631 → (a) as triage weighed it: the catalog's 409 entry becomes UNIQUE_VIOLATION with a one-sentence cross-reference that the engine's in-process spelling is DUPLICATE_RECORD, translated at the REST door; the quick-reference row follows; ⛔ packages/rest is the judge, not the patient. #15632 → REWRITE, not delete: ## Standard Error Response becomes the ADR-0112 flat body (error, code, developerMessage, and the top-level siblings field / object / dependentObject / dependentCount / currentVersion), and EVERY per-code example on the page moves with it — all or nothing; the two NOT MEASURED items (whether requestId/timestamp are emitted anywhere; whether any client/Console reads the nested shape) are measured FIRST and reported — a real consumer of the nested shape turns this into a contract card and stops the rewrite. pnpm check:error-status-conformance runs to a verdict pasted in the PR body (the quick-reference row is a per-code status claim it grades). Lock depth read before dispatch per #14944: queue empty → admitted; hot files free (#15634 landed). pm:queue → pm:dispatched, assignee set.

---

Generated by Claude Code