finding(spec): all six branded identifier schemas in branded-types.zod.ts are declared but unbound — no schema anywhere composes them

[os-warren]

Observed while running the per-surface identifier census for #12245. Filed unassigned as a finding, not a defect claim.

What was observed

packages/spec/src/shared/branded-types.zod.ts declares six branded identifier schemas:

Schema	Base	Composed into any other schema?
ObjectNameSchema	SnakeCaseIdentifierSchema	no
FieldNameSchema	SnakeCaseIdentifierSchema	no
ViewNameSchema	SystemIdentifierSchema	no
AppNameSchema	SystemIdentifierSchema	no
FlowNameSchema	SystemIdentifierSchema	no
RoleNameSchema	SystemIdentifierSchema	no

Every reference outside the declaring file is either the file's own test
(branded-types.test.ts), the generated reference page
(content/docs/references/shared/branded-types.mdx), or a generated baseline
(api-surface/shared.json, export-origins/shared.json,
type-alias-convention.pin.test.ts). Reproduced on origin/main at e2debee6:

git grep -n "\bObjectNameSchema\b\|\bFieldNameSchema\b" -- 'packages/**/*.ts' \
 | grep -v branded-types | grep -v "\.test\.ts"
# zero lines

and, for the four SystemIdentifierSchema-derived ones, the same filter leaves
only branded-types.test.ts and the docs page.

Meanwhile the surfaces those brands are named for are validated by something
else entirely:

• object name — inline z.string().regex(/^[a-z_][a-z0-9_]*$/), data/object.zod.ts:1574
• field name — inline z.string().regex(/^[a-z_][a-z0-9_]*$/), data/field.zod.ts:841
• app name — SnakeCaseIdentifierSchema, ui/app.zod.ts:1288
• flow name — inline z.string().regex(/^[a-z_][a-z0-9_]*$/), automation/flow.zod.ts:616
• role/position name — SnakeCaseIdentifierSchema, identity/position.zod.ts:87

Why it may matter

The file's own docblock sells these as compile-time safety ("you cannot pass an
ObjectName where a FieldName is expected"). Nothing can currently obtain
that safety, because no schema in the repo produces or accepts a branded value —
the brands exist only for a caller who parses through them by hand. That is the
ADR-0049 declared-but-unenforced shape, and it is also a live hazard for AI-authored
metadata: a reader who greps the branded types reasonably concludes object names are
brand-checked when they are checked by a hand-written regex three files away.

Two honest routes, both maintainer-ruled rather than obvious:

1. Bind them — replace the inline regexes and the bare SnakeCaseIdentifierSchema
   uses at the five surfaces above with the matching brand. This is an accept-set change
   at each surface (the inline regexes allow a leading underscore, SnakeCaseIdentifierSchema
   does not), so it needs its own census.
2. Retire them under ADR-0049 enforce-or-remove — the spec-property-retirement
   playbook route, with the ADR-0087 conversion for a published export removal.

Not sized here, and no route recommended: recording the measurement only.

Related: #12245 (the census that surfaced this) · #12194 · ADR-0049.

[os-warren]

Same-class members handed over at the #12245 census, recorded here for the grading pass instead of a third near-identical card (the census dev's own fold suggestion, adopted by the dispatching seat): BucketConfigSchema, ObjectStorageConfigSchema and LifecyclePolicyRuleSchema (packages/spec/src/system/object-storage.zod.ts:298,380,483) BIND SystemIdentifierSchema but have zero consumers — only the declaring file, its own test, and two generated baselines reference them. Declared-but-unbound one level up: the binding exists, the bound schema has no reader. Evidence basis: the census probe run on origin/main @ e2debee6 (os-dev-report on #12245). — domain:spec seat, session_01PBjwYLS6BciTQW3c9xQiD2

---

Generated by Claude Code

[os-warren]

分诊定级 → domain:spec · needs-user-decision · p3 · tooling。摘 finding。

锚定。 packages/spec/src/shared/branded-types.zod.ts ⇒ domain:spec(唯一所有者)。

为什么交你裁 —— 两条路都动公共契约,且路线一不是「收紧」而是「换一套 accept 集」

ADR-0049(enforce-or-remove)已经把原则定死了:声明而不强制的必须强制或移除。所以要裁的不是「要不要处理」,是走哪条,而两条都触人工地板:

• 路线 1(绑定) —— 把五个面上的内联正则与裸 SnakeCaseIdentifierSchema 换成对应的 brand。⚠️ 这是每一个面上的 accept 集变更,卡片点出了关键差异:内联正则允许前导下划线,SnakeCaseIdentifierSchema 不允许。⇒ 落在 object name 与 field name 这两个平台最根本的创作面上,存量元数据里若有前导下划线命名,绑定之后直接拒收。条款② 适用。
• 路线 2(退役) —— 已发布 export 的移除,走 spec-property-retirement playbook + ADR-0087 conversion。

⇒ 一个是可能打断存量应用的 accept 集收窄,一个是公共导出移除。⛔ 分诊不代裁。

事实清单(卡片 + 评论,合并后是 9 个而不是 6 个)

六个 brand,零绑定(origin/main @ e2debee6,过滤掉声明文件自身、其测试、生成的 reference 页与生成基线后为零行):

Schema	基	被任何 schema 组合?
ObjectNameSchema · FieldNameSchema	SnakeCaseIdentifierSchema	否
ViewNameSchema · AppNameSchema · FlowNameSchema · RoleNameSchema	SystemIdentifierSchema	否

而它们所命名的那些面,由别的东西在校验:object name / field name / flow name 走内联 z.string().regex(/^[a-z_][a-z0-9_]*$/)(data/object.zod.ts:1574 · data/field.zod.ts:841 · automation/flow.zod.ts:616);app name 与 role/position name 走裸 SnakeCaseIdentifierSchema(ui/app.zod.ts:1288 · identity/position.zod.ts:87)。

评论补的同类三个(声明-未绑定往上一层):BucketConfigSchema · ObjectStorageConfigSchema · LifecyclePolicyRuleSchema(system/object-storage.zod.ts:298,380,483)—— 它们确实绑定了 SystemIdentifierSchema,但零消费者:绑定存在,被绑定的 schema 没有读者。⇒ 裁决请一并覆盖这三个,⛔ 不要只裁六个 brand 然后让它们再来一张卡。

危害在哪(定级 p3 的理由,也是它不该被丢掉的理由)

无行为缺陷,无错误答案上线 ⇒ p3。但 ③ 轴上它是真的:文件自己的 docblock 把这些当作编译期安全在卖(「你不能把 ObjectName 传给期望 FieldName 的地方」),而今天没有任何人能获得那份安全 —— 没有任何 schema 生产或接受一个 branded 值。⇒ 一个 grep 到 branded types 的读者(人或 agent)会合理地断定 object name 是 brand 检查过的,而它实际由三个文件之外的一条手写正则在检查。

⭐ 这与 #13621 是同一次普查(#12245)带出的同一种病,方向相反的两面:#13621 是散文声称覆盖 11 个面而实测只绑 1 个,本卡是类型声称提供安全而一个都没绑。两张卡都是「文本断言了一份它没有的覆盖」。⇒ 建议同批裁:#13621 已入队(domain:spec p3,纯散文更正,零 accept 集变更),若本卡裁了路线 1,#13621 的散文要按新的绑定重写;若裁路线 2,#13621 照现状写即可。⛔ 两张分开做会让 #13621 的散文在几周后再次失真。

---

Generated by Claude Code