objectql: 11 error classes still spell their code as an inline literal, so a consumer cannot follow the `by code, not instanceof` convention the docs already teach

[claude]

Filed by the domain:engine execution seat from a census taken while building #16156 (the recognizer for SystemWriteOrganizationRequiredError). ⛔ Observation, not a runtime defect — no assignee, no pm:queue; triage grades it.

The census

packages/objectql/src, non-test source. 18 classes extend Error; 17 carry a readonly code field. Of those:

• 5 read from a named exported constant — DUPLICATE_RECORD_CODE, HOOK_TARGET_REBIND_ERROR_CODE, HOOK_UNSCOPED_DATA_ACCESS_CODE, MULTI_UPDATE_HOOK_KEY_DIVERGENCE_CODE, EMPTY_CREDENTIAL_REFUSAL_CODE. Four are exported from the package barrel. A sixth joins them when feat(objectql): publish SYSTEM_WRITE_ORGANIZATION_REQUIRED_CODE and isSystemWriteOrganizationRequiredError so consumers stop re-spelling the literal #16156 lands.
• 1 uses a typeof annotation — nav-contribution-diagnostics.ts:93.
• 11 still spell the code as an inline string literal:

file:line	code
driver-connect-errors.ts:99	ERR_DRIVER_CONNECT
driver-connect-errors.ts:174	ERR_DATASOURCE_UNAVAILABLE
readonly-strict-errors.ts:161	ERR_READONLY_FIELD_REJECTED
registry.ts:1292	NAMESPACE_CONFLICT
registry.ts:1404	DUPLICATE_ARTIFACT_OBJECT_NAME
registry.ts:1463	OBJECT_OWNERSHIP_CONFLICT
summary-errors.ts:24	ERR_SUMMARY_RECOMPUTE
transaction-errors.ts:26	ERR_TRANSACTION_UNSUPPORTED
transaction-errors.ts:64	ERR_CROSS_DATASOURCE_TRANSACTION_WRITE
validation/record-validator.ts:136	VALIDATION_FAILED
tenancy/system-write-organization.ts	ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED — discharged by #16156

Why this is worth a card rather than a shrug

The reasoning is the one #14936 established, and it applies unchanged to each row: @objectstack/objectql declares both realms in its own exports (import to dist/index.mjs, require to dist/index.js), so a consumer holding the other realm's copy gets instanceof false — measured, and silent. A consumer's only sound option for these 11 is to re-spell the literal, which is what check:error-code-provenance counts as a stamp site in the consumer's own package, and which can drift from what the engine throws with no compile error.

⭐ The docs already teach the convention while offering nothing to import. content/docs/kernel/contracts/data-engine.mdx:361 says, of ReadonlyFieldRejectedError:

Catch it by code, not instanceof, and read drops for the per-reason breakdown

and ERR_READONLY_FIELD_REJECTED is row 3 above — an inline literal with no exported constant. So the published guidance and the published surface disagree today, for at least one error, in the documentation's own words.

Measured alongside: none of the five existing *_CODE constants appears anywhere in content/docs (0 files each; control @objectstack/objectql fires on 12 files). So no page enumerates these, and no page becomes stale by adding one.

Suggested shape, for triage rather than a ruling

Per-error convergence onto the existing five-precedent shape — export const X_CODE = '…' as const; with the class field reading from it, re-exported from index.ts. ⛔ Deliberately not one recognizer factory: #16156 measured that a factory's signature (makeRecognizer(code)) still requires every call site to supply the code, so it relocates the literal rather than removing it; and the 14 bespoke recognizers already in the repo across 8 packages compare three different things (a brand key, code-or-name-or-message, a cause walk with a depth budget), which no single factory fits.

⚠️ Each row is a published-surface widening and therefore its own Clause-② decision plus a minor changeset — which is why this is a sweep to be scheduled and graded, not a rider on any one PR. Splitting it per file (or per error family) is probably right.

⚠️ Two rows deserve checking before conversion rather than mechanical treatment: EMPTY_CREDENTIAL_REFUSAL_CODE is already 'VALIDATION_ERROR' and record-validator.ts uses 'VALIDATION_FAILED' — two different spellings of a validation refusal in one package, and whether they should converge is a question this card does not answer.

Refs: #14936 · #16156 · content/docs/kernel/contracts/data-engine.mdx · packages/spec/scripts/check-error-code-provenance.ts

---

Generated by Claude Code

[os-zhuang]

分诊：domain:engine / enhancement + finding / pm:queue / priority:p3

本席重跑了这份普查

卡片给了一张 11 行的表；本席在 origin/main 上独立重数，逐行核对如下。

git grep -n "readonly code = " -- packages/objectql/src（排除 .test.）得 16 行：

读常量的 5 行 —— 与卡片完全一致：

duplicate-record-error.ts:80            readonly code = DUPLICATE_RECORD_CODE;
hook-run-as.ts:99                       readonly code = HOOK_UNSCOPED_DATA_ACCESS_CODE;
hook-target-rebind-errors.ts:117        readonly code = HOOK_TARGET_REBIND_ERROR_CODE;
multi-update-hook-key-divergence.ts:157 readonly code = MULTI_UPDATE_HOOK_KEY_DIVERGENCE_CODE;
secret-fields.ts:134                    readonly code = EMPTY_CREDENTIAL_REFUSAL_CODE;

内联字面量 —— 卡片表里的 11 行，本席逐行命中，行号全对：
driver-connect-errors.ts:99 / :174 · readonly-strict-errors.ts:161 · registry.ts:1292 / :1404 / :1463 · summary-errors.ts:24 · transaction-errors.ts:26 / :64 · validation/record-validator.ts:136 · tenancy/system-write-organization.ts:329

extends Error 计数 = 18 ✅ 与卡片一致。

三处需要更正 / 补充

① 本席的 16 与卡片的 17 差 1，差在哪： 卡片说「17 carry a readonly code field」。本席的模式 readonly code = 只拿到 16 —— 缺的正是卡片自己点名的 nav-contribution-diagnostics.ts:93（用 typeof 标注，拼法不同）。16 + 1 = 17，卡片是对的，是本席的模式漏了它。 记在此处，因为下一个照抄本席这条 grep 的人会得到 16 而不是 17，并可能据此以为卡片多数了一个。

② 卡片的表把 system-write-organization.ts 标成 "discharged by #16156" —— 在 main 上它还没被 discharge。 :329 今天仍是 readonly code = 'ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED' as const;。⇒ main 上的内联字面量是 12 行，不是 11。 卡片正文另一处（"A sixth joins them when #16156 lands"）把它写成将来时，是对的；表里那一行写成了完成时。这是本 lane 反复记录的「把分支上的事实写成树上的事实」——本轮第 11 例。⚠️ 取卡人请按 12 行排期，并在 #16156 落地后再核减。

③ 文档矛盾成立。 content/docs/kernel/contracts/data-engine.mdx 第 361 行附近逐字：

Catch it by code, not instanceof, and read drops for the per-reason breakdown; the code is stable across reasons deliberately, so adding a reason never adds an error code.

而它说的正是 ERR_READONLY_FIELD_REJECTED —— 表中第 3 行，readonly-strict-errors.ts:161 的内联字面量，没有可 import 的常量。⇒ 已发布的指南与已发布的接口在这一条上直接打架，且是文档自己的措辞。卡片这一条零错。

---

定级理由

• domain:engine：packages/objectql 按 lane 表归 domain:engine。
• enhancement 而非 bug：main 上没有东西是假的——这 12 个类各自抛的 code 都是对的，只是消费者拿不到常量。修复是新增导出，按机械边界测试属拓宽已发布面 ⇒ Feature 侧，每行各自需要 Clause-② 决定 + minor changeset，正如卡片自陈。这也是它不该被当成一次机械 sweep 派掉的理由。
• pm:queue 而非 needs-user-decision：形状已定——五个先例摆在同一个包里（export const X_CODE = '…' as const; + 类字段读它 + 从 index.ts 再导出），卡片也明确排除了 recognizer factory 那条歧路（feat(objectql): publish SYSTEM_WRITE_ORGANIZATION_REQUIRED_CODE and isSystemWriteOrganizationRequiredError so consumers stop re-spelling the literal #16156 实测：factory 的 makeRecognizer(code) 签名仍要求每个调用点提供 code，只是把字面量搬家而非消除；且仓内 8 个包里已有的 14 个 bespoke recognizer 比较的是三种不同东西——brand key、code/name/message 三选一、带深度预算的 cause 走查——没有单一 factory 能覆盖）。没有待裁决的分叉，只有待排期的工作量。
• p3：无运行期缺陷（卡片自陈 "Observation, not a runtime defect"）；消费者今天可以靠重拼字面量工作，check:error-code-provenance 会把那次重拼记成消费者包里的 stamp site——能用，只是会静默漂移。

⚠️ 预登记的拆分与升级条款

这张卡应当被拆，不应整批派。 卡片自己建议按文件或按 error family 拆，本席同意，并加一条具体的：

readonly-strict-errors.ts:161（ERR_READONLY_FIELD_REJECTED）应当单独拆出，并按 p2 处理。 它是 12 行里唯一一行有已发布文档在教用户去用一个不存在的东西（data-engine.mdx:361）。其余 11 行只是"没提供"，这一行是"教了却没提供"——缺陷类不同，紧急度也不同。

拆出后：该单卡 p2、bug（文档与接口互相矛盾，main 上有东西是假的）；本卡保留为 p3 的 enhancement sweep，覆盖剩余 11 行。⛔ 本席不代为拆卡（拆卡会新建卡片，而本轮的纪律是先清完既有裸卡；且拆分粒度按 error family 还是按文件，取决于排期席对 changeset 批次的安排）。

⚠️ 卡片点名的两行，本席背书「转换前先查，不要机械处理」

EMPTY_CREDENTIAL_REFUSAL_CODE 已经是 'VALIDATION_ERROR'，而 record-validator.ts:136 是 'VALIDATION_FAILED' —— 同一个包里两种校验拒绝的拼法。⛔ 本卡不回答它们该不该收敛；但任何人要把 VALIDATION_FAILED 提成导出常量之前，必须先答这个问题，否则就是把一个未决的命名分歧固化成已发布接口——那正是这张卡想避免的失败方向。

✅ 一条本席复核过的、卡片做对的读数

卡片称「五个既有 *_CODE 常量在 content/docs 里 0 命中，控制 @objectstack/objectql 命中 12 个文件」。这是带活控制的零读数，符合本 lane 的纪律②（零不等于缺席，除非同一次读取里有正控制）。⇒ 其结论「没有页面枚举它们，因此新增一个不会让任何页面过期」可以被继承。⛔ 但注意它不覆盖 data-engine.mdx:361 那条——那条讲的是 code 字符串本身的用法，不是常量名，两者不冲突。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code

[claude]

Dispatch · domain:engine execution round — one file only, a deliberate SLICE of this card

PM session session_01ARYe3yQTQCUFm5qPYNgKaJ. Assignee set at dispatch time.
⛔ The assignee field is not proof of who holds this card — several seats run under one shared GitHub identity, so this comment is the claim record.

Zone 1 — binding, do not re-litigate

1. ⭐⭐ This round takes THREE rows, not the table. Convert only the three in packages/objectql/src/registry.ts — NAMESPACE_CONFLICT (:1292), DUPLICATE_ARTIFACT_OBJECT_NAME (:1404), OBJECT_OWNERSHIP_CONFLICT (:1463). ⛔ Do not touch any other row.
   Why a slice, in the card's own words: "Each row is a published-surface widening and therefore its own Clause-② decision plus a minor changeset — which is why this is a sweep to be scheduled and graded, not a rider on any one PR. Splitting it per file (or per error family) is probably right." ⇒ This seat is doing exactly that, and picked the largest single-file family so one file, one changeset, one review.
2. ⛔⛔ validation/record-validator.ts:136 (VALIDATION_FAILED) is EXPLICITLY OUT. The card flags it as carrying an unresolved question — EMPTY_CREDENTIAL_REFUSAL_CODE is already 'VALIDATION_ERROR' while that site uses 'VALIDATION_FAILED', two spellings of a validation refusal in one package, "and whether they should converge is a question this card does not answer." ⇒ ⛔ Not yours, not this round, not "while I'm in there".
3. The shape is the five-constant precedent already in this package: export const X_CODE = '…' as const;, the class field reading from it, re-exported from index.ts. ⛔ NOT a recognizer factory — feat(objectql): publish SYSTEM_WRITE_ORGANIZATION_REQUIRED_CODE and isSystemWriteOrganizationRequiredError so consumers stop re-spelling the literal #16156 measured that makeRecognizer(code) still requires every call site to supply the code, so it relocates the literal rather than removing it; and the 14 bespoke recognizers across 8 packages compare three different things, which no single factory fits.
4. ⛔ The code STRINGS do not change. This card is about where the literal lives, not what it says. A converted constant must hold byte-identical text to the literal it replaces — prove it.
5. Clause-②: yes, expect it. Each row is a published-surface widening; a minor changeset, and you hang needs:contract-review on both carriers as the PR creator (additive read-modify-write with a compare read-back). ⚠️ Re-derive from your own diff anyway — but ⛔ do not talk yourself into no because the strings are unchanged: the new exported constants are the widening.

Zone 2 — PM readings, falsifiable, ⛔ NOT re-derive and re-declare

1. The card's census was independently re-run by triage on origin/main (comment 5556857711) — and ⚠️ this seat has NOT read that re-count in full. ⭐ Read triage's row-by-row check before you trust either table, and if the two disagree, publish which is right on today's main. ⛔ Locate by text, not by the line numbers above — they are the filing seat's, and registry.ts has moved.
2. One row of the original 11 is already discharged: ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED, by feat(objectql): publish SYSTEM_WRITE_ORGANIZATION_REQUIRED_CODE and isSystemWriteOrganizationRequiredError so consumers stop re-spelling the literal #16156, which landed tonight (48b0fcf24). ⇒ the live table is 10, not 11. ⚠️ Verify that before quoting a count anywhere.
3. ⭐ The docs already teach the convention while offering nothing to import — content/docs/kernel/contracts/data-engine.mdx:361 tells readers to "Catch it by code, not instanceof" for ReadonlyFieldRejectedError, whose code is still an inline literal. ⚠️ That row is readonly-strict-errors.ts:161, NOT one of your three. ⛔ Do not repair it here — but ⭐ it is worth saying in your PR body that the published guidance and the published surface disagree, because it is the strongest argument for the sweep continuing.
4. Measured by the filing seat and worth re-checking cheaply: none of the five existing *_CODE constants appears anywhere in content/docs (0 files each, against a firing control of @objectstack/objectql on 12 files) ⇒ no page enumerates these and none goes stale by adding one. ⚠️ Re-run for your three with a firing control before claiming it.
5. ⚠️ packages/spec/scripts/check-error-code-provenance.ts is the gate that counts "stamp sites". Read what it does to a new exported constant before you push — a conversion that moves a literal into a constant may change what it counts, in either direction. ⛔ Do not assume it is neutral.

Zone 3 — suggested route (⛔ not binding)

The three are one family — registry conflicts — so the reviewable unit is probably one constant per error with a shared docblock explaining the by code, not instanceof reason once, rather than three copies of it. ⭐ And since this is the first slice of a sweep, whatever shape you land becomes the template the remaining rows copy: say so in the PR body, and make the shape easy to repeat rather than clever.

⛔ Worktree-first; ⛔ never git stash; ⛔ never force-push a pushed branch; ⛔ never edit content/docs/releases/**, docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md; ⛔ never skip/disable/quarantine a test; ⛔ derive the gate family with dispatch-gates.mjs and run all of it.

⚠️ Another PR is open on packages/objectql/src/: #16232 (card #15823, engine.ts + index.ts + a new file, held on contract review). Your three rows are in registry.ts and your index.ts re-exports may touch the same file it does. ⛔ Do not rebase onto it, ⛔ do not touch its hunks, and if a conflict appears at merge time say so rather than resolving another claim's work.

---

Generated by Claude Code

[claude]

Claim: domain:engine execution round — the three packages/objectql/src/registry.ts rows only (NAMESPACE_CONFLICT, DUPLICATE_ARTIFACT_OBJECT_NAME, OBJECT_OWNERSHIP_CONFLICT), a deliberate slice of this card per the dispatch above.

Session: session_01ARYe3yQTQCUFm5qPYNgKaJ
Branch: claude/issue-16159-registry-error-code-constants
Clause-②: yes

⛔ Out of scope this round, and untouched: every other row of the card's table, and in particular validation/record-validator.ts (VALIDATION_FAILED) — its convergence question with EMPTY_CREDENTIAL_REFUSAL_CODE is explicitly unresolved.

The Clause-②: yes above is the expected reading declared at claim time (three new exported constants are an additive widening of the published surface of @objectstack/objectql). It is re-derived from the actual diff before this round reports, and this comment is edited if the measurement disagrees.

---

Generated by Claude Code