[P2] objectui: a spec-named symbol must be an import, not a declaration — make "derived vs hand-written" a CI rule, not a review convention

[os-zhuang]

Systematizes what #4074 / objectui#3003 / objectui#3009 did by hand for the third time. Filed so the rule outlives the sessions that keep rediscovering it.

The failure class

objectui declares local types/consts under the same names as @objectstack/spec exports, with doc comments claiming spec canonicity. Every audited instance had either drifted or was one spec release away from it:

symbol	comment claimed	code did	found
ActionType	"canonical definition from @objectstack/spec"	hand union, missing form	#2231/#2901
ChartType	(sibling schema re-exported under spec's name)	7 of 19 members	objectui#2944
ActionLocation + 2	"single source of truth… re-export here"	re-declared union + tuple + z.enum	#4074
ActionParamFieldType	"aligned with the field types available in spec"	16 of 49 members	#4074

The mechanism that makes this class expensive is specific to agent-driven development: an agent reads the comment, takes it as ground truth, and builds on it. #2901 was literally filed with a backwards premise because the fork was re-exported under the spec's own symbol name. A wrong canonical-claim is not stale documentation — it is a planted premise for the next session.

And the absence of derivation is what made #3856 silent: spec 17 removed action.execute and objectui produced zero compile errors, because nothing was bound to the spec's z.infer.

The rule

Any exported type or const in objectui whose name matches a @objectstack/spec export must be an import/re-export of it — or carry an allowlist entry with a reason.

Enforced by a CI script (~100 lines), not prose:

1. Enumerate spec's export names per subpath (@objectstack/spec/ui, /data, …) at runtime.
2. Grep objectui packages/*/src for export (type|const|interface) <SameName> declarations not backed by an import from spec.
3. Fail with the symbol, the file, and the fix ("import it, or add an allowlist entry with a reason").

Value exports additionally pin by reference identity (expect(X).toBe(SpecX)), because a faithful copy passes every value comparison — identity is the only check that distinguishes a re-export from a fork. This insight is already written down in objectui's spec-subschema-parity.test.ts and already applied to ACTION_LOCATIONS / ActionLocationSchema / ACTION_PARAM_FIELD_TYPES (objectui#3003); this issue is about applying it uniformly instead of one symbol per incident.

The allowlist (what keeps this from being a nuisance)

Same governance as check-type-check-coverage.mjs's DEBT map — declared, reasoned, shrink-only. Known-legitimate first entries:

• @object-ui/types ActionSchema — a deliberate objectui-side view over the spec's action (carries renderer-only fields like openIn); documented as such.
• ObjectUiLocalActionType / ObjectUiLocalParamFieldType — named local dialects, each with a tripwire test asserting the spec does not own the name (so the day spec adopts it, CI names the alias to retire). This is the sanctioned escape hatch for "implementation accepts more than spec": declare the dialect next to the vocabulary it extends, never hide it in a Record<string, string> in another package.
• The legacy ActionSchema in crud.ts and similar explicitly-legacy shapes, if any collide.

A same-name symbol that is narrower or wider on purpose belongs in the allowlist with that purpose written down — at which point the comment is load-bearing instead of decorative.

One meta-rule

This rule must land as the check, not as an AGENTS.md paragraph. A prose-only rule is precisely the "declared ≠ enforced" landmine this whole thread is about (#4074, objectui#3009 — where a guard file's own header falsely claimed its checks were "the real enforcement" for the entire interval nothing compiled it).

Refs #4074, #3856, objectui#3003, objectui#3009, objectui#2944, #2901, #2231.

[os-zhuang]

The rule landed as CI in objectui#3032 (62311b6) — scripts/check-spec-symbol-derivation.mjs, in the type-check job, 5.5s.

One implementation note that mattered. The issue's step 1 says "enumerate spec's export names per subpath at runtime." That doesn't work: a runtime import() sees only values, and the drifted symbols in the table above are mostly types — ActionType, ChartType, ActionParamFieldType would all have been invisible. The script goes through the compiler's view of each subpath's .d.ts instead, which yields 4231 export names, types and values alike.

The three allowlist forms are supported as prescribed: re-export, z.infer derivation, or a ledger entry. Derivation must sit in a structural position — a type alias's own type node, an interface's extends, a const's initializer — because a spec name merely mentioned inside a members block is what a fork looks like. Consts are stricter still: array and object literals aren't descended into, so export const ACTION_LOCATIONS = [...SpecLocations] is flagged. That is the reference-identity argument from objectui#3003 applied statically — a faithful copy passes every value comparison.

Leaving this open, because the allowlist is not the size this issue imagined. The ask sketched "known-legitimate first entries" — roughly the three named above. The measured reality is 156 collisions across 19 packages. So what shipped is a debt ledger, not a small permanent exception list, and the governance detail matters more than expected: it names symbols, not per-package counts. A count would be a budget — it would let a new fork land as long as an unrelated one was fixed in the same PR, and it would make the failure message point at whichever symbol sorts first rather than the one just written. --ledger regenerates the block, so burning entries down is mechanical.

Each of the 156 resolves one of three ways: it's a fork (→ re-export, delete the declaration), it needs local shaping (→ z.infer), or it's a genuine dialect (→ stays, but with a written reason and the tripwire test this issue prescribes, so the day spec adopts the name CI says which alias to retire). Starting the burn-down at @object-ui/types, since that's where the repo takes its vocabulary from and a fork there travels furthest.

---

Generated by Claude Code

[os-zhuang]

@object-ui/types 全量分诊完成:73 条碰撞,55 条已经漂了

承 objectui#3017(「手抄 spec 清单」模式排查)的收尾结论 —— 本 issue 的债务台账是同一失效类的超集,且 @object-ui/types 占最大一块、又是全仓传播根(其他包都 import 它),所以先从它开刀。对 73 条碰撞记录(71 个唯一名)逐条两边对读:

判决	数量
FORK_DRIFTED — 与 spec 已经不一致	55
COINCIDENCE — 真撞名,概念不同	17
FORK_IDENTICAL	1

本 issue 正文说这批是「已漂移或离漂移只差一个 spec 版本」。实测明显偏前者:四分之三已经漂了,而且不止是「少几个枚举成员」——有几处是活的缺陷。

已落地(objectui#3057,台账 149 → 144)

只取可证明安全的一档(本地是 spec 严格子集,或逐成员相同),其中两条是活缺陷:

• PageVariableSchema 漏 source,即整个 ADR-0049 写绑定 —— spec 写法 {name:'selectedProjectId', source:'project_picker'} 解析后变成谁也写不了的变量;type 枚举还漏 record_id。同一文件下三行的 PageTypeSchema 已是 spec 引用,注释写着「镜像漏了 list 导致 spec 合法页面校验失败」——修了一个、漏了隔壁那个。这是本 issue 描述的失效模式最干净的一个现场。
• FeedItemType 7/13。缺的 6 个(file/sharing/note/record_create/record_delete/approval)在 RecordActivityTimeline 里既无图标也无颜色 —— 服务端发出即渲染不出。因为两张表是 Record<FeedItemType,…> 全键映射,widen 后编译器直接把缺口报出来。
• PermissionAction 8/11(漏 execute/manage/configure)、ObjectIndex(漏 fulltext/unique:'global'/partial)、PageVariable(与 spec 逐成员相同)。

剩余 50 条 drifted:按修法难度分三组

A 组 · 需要重命名(概念真不同,名字撞了) —— 正解是改本地名,但多数从 barrel 公开导出,是 breaking change,需先定约定:
FilterCondition(本地是 FilterBuilder 的一行 {field,operator,value},spec 是递归 ObjectQL AST)、FilterOperator、EventHandler(SDUI 事件绑定 vs 内核事件总线订阅)、CacheStrategy(service-worker 取数策略 vs 缓存淘汰策略)、MutationEvent(对象 payload vs 字符串枚举)、SpanSchema(HTML <span> vs OpenTelemetry span)、ValidationRule(×2)、BatchOperationResult(本地是整批汇总,spec 是单条结果 —— 本地形状其实精确对应 spec 的 BatchUpdateResponse)、ReportSchedule、WidgetManifest/WidgetSource、GestureType/GestureConfig 等。

B 组 · 渲染节点 vs 元数据文档(type 语义冲突) —— PageSchema/AppSchema/DashboardSchema/ReportSchema,TS + Zod 各一份共 8 处。核心冲突:spec 的 type 是页面/报表的种类(record|app|utility|list|home),objectui 的 type 是渲染器判别式(z.literal('page')),种类被挪到 pageType。所以 spec 页面 {type:'list'} 在本地直接 fail,本地页面在 spec 侧 pageType 被静默丢弃。得先定命名约定(*NodeSchema?)才能动。

C 组 · .passthrough() 静默放行(建议优先) —— 这是 objectstack#4120 那个失效形态在 objectui 的等价物,且不需要重命名决策:AppSchema/DashboardSchema/PageSchema 的 Zod 侧继承 BaseSchema.passthrough(),而 spec 侧是 .strict()。后果是 spec 独有的 22/13/15 个键未经任何校验穿过去 —— branding/sharing/protection/_lock* 全部不验,brading: 这种拼写错误完全隐形。

已有范式可抄,不必新发明

zod/objectql.zod.ts 的 ListViewSchema 是全场最佳实践:spec 字段经 SpecListViewFields.shape 按引用流入,配 list-view-spec-parity.test.ts 漂移守卫(spec 长出新字段而 objectui 未分诊即报红),注释所述与代码所做完全一致。B/C 两组应向它收敛,而不是各自发明。

顺带:守卫本身工作良好,值得说一句

烧掉 5 个名字后跑守卫,它主动报红说台账里有 5 个「不再碰撞」的条目、要求删除 —— 也就是登记表自身的腐烂被防住了(这正是 #4120 抓到的那个终末形态:注释指向一个早已删除的符号)。两个方向都做了变异测试:重新 fork 一个已烧名字 → 按名报红;烧掉的名字留在台账 → 按腐烂报红。--ledger 重生成 + 逐条 diff 也确认没误抹其他包的债务。

[os-zhuang]

C 组已落地(objectui#3063)

分诊评论里划出的三组中,C 组(.passthrough() 静默放行)已合入 main。选它先做的理由成立:它是本 issue 失效类里唯一不需要重命名决策的一组,A/B 两组都得先定命名约定。

实际规模比分诊估计的大

AppSchema/DashboardSchema/PageSchema 都 extend 自 .passthrough() 的 BaseSchema,spec 侧是 strict —— 合计 39 个 spec 键完全不经校验穿过去:App 23(branding/sharing/embed/objects/apis/requiredPermissions/homePageId/protection + 整个 _lock*/_package*/_provenance 包锁封套)、Dashboard 10、Page 6。

Page 那 6 个里有一个活缺陷:source 从未被声明,而 kind: 'html' | 'react' 的页面正是把正文放在 source 里 —— 这类页面在 objectui 里根本无法表达。

修法要点(两条值得记下)

1. 没有加 .strict(),那是错解。这三个是组件节点,开放封套是有意为之(渲染器属性该穿透)。正解是让 spec 字段按引用流入 —— 即 zod/objectql.zod.ts 的 ListViewSchema 已在用的范式。收紧的只是 spec 拥有的那部分,并专门加了断言守住「未知渲染器属性仍然放行」。

2. zod 4 拒绝对带 refinement 的对象调 .omit(),而 spec 的 PageSchema 恰好有一个 —— 所以本 issue 里到处推荐的惯用写法 SpecSchema.omit({…}).partial() 会在 import 期直接抛异常,不是运行期。新的 specFieldsExcept()(objectui base.zod.ts)改读 .shape 绕开,坑记在它的文档注释里。后续给其他 schema 加派生的人会再撞上这个,建议在本 issue 正文的修法模板里补一句。

闸门

新增 page-app-dashboard-spec-parity.test.ts(19 断言),覆盖三个方向 + 一组「这些键现在真的被校验了」的钉扎(branding: 'blue' 从通过变拒绝、kind: 'nonsense' 从通过变拒绝、kind:'html' + source 现在能表达)。变异测试两个方向都红:偷偷 omit 掉 branding → 3 个测试按名报红;加未登记的本地键 → rogue-key 断言报红。

验证:全仓 type-check 78/78,types 271 断言,下游 app-shell/plugin-dashboard/plugin-list/core 共 3626 断言全绿 —— 收紧校验没挡住任何现有渲染路径。

剩下的 A/B 两组需要先拍板

两组都卡在命名决策上,不适合由实现方自行决定:

• A 组(约 17 条真撞名):FilterCondition/FilterOperator/EventHandler/CacheStrategy/MutationEvent/ValidationRule×2/BatchOperationResult 等,正解是改本地名,但多数从 barrel 公开导出 —— 是 breaking change,得先定是直接改、还是先加别名过渡。
• B 组(8 处,TS+Zod 各一份):type 语义冲突 —— spec 的 type 是页面/报表种类,objectui 的是渲染器判别式。需要先定约定(*NodeSchema 之类)才能动。本 PR 已把 Page 的这处冲突在代码注释里写明并 omit 掉,没有擅自调和。

[os-zhuang]

A 组已落地(objectui#3068)—— types 侧从 71 降到 44

按维护者指示直接改名、不做别名过渡。这 15 个是分诊里的 COINCIDENCE 判决:本地概念与 spec 某个导出同名但建模的是别的东西 —— 也就是本 issue 正文点名的那类「名字本身就是缺陷」。

几个对照值得记录(左本地、右 spec 同名符号的真实含义):
SpanSchema = HTML <span> ↔ OpenTelemetry 追踪 span;CacheStrategy = service-worker 取数顺序 ↔ 缓存淘汰策略;MutationEvent = 对象 payload ↔ 字符串枚举;BatchOperationResult = 整批汇总 ↔ 单条记录结果;EventHandler = SDUI 事件绑定 ↔ 内核事件总线订阅。全部改为 FilterBuilderCondition/FetchCacheStrategy/TextSpanSchema/BatchOperationSummary/UIEventHandler 等。

改名过程暴露的两个既有问题

1. objectui 自己有两个互相冲突的 ValidationRule:field-types.ts 是扁平约束包(minLength?: number),form.ts 是 RHF 风格包装形(minLength?: {value, message})—— 键名全同、值形状不兼容。barrel 只导出后者,前者是被刻意从导出块省掉以躲开碰撞的,所以深引 field-types 的消费者会静默拿到另一个类型。这个碰撞在本仓内部藏了很久,是被 spec 改名工作顺带挖出来的。

2. zod/reports.zod.ts 的 ReportComponentSchema 已被判别联合占用,而 zod/theme.zod.ts 早已在用「节点 = *ComponentSchema、联合 = *UnionSchema」的约定 —— 两个文件的命名约定原本就不一致。借这次统一了。

方法上的一条建议,值得写进本 issue 的修法模板

不要对这类改名做全局字符串替换。 FilterCondition/ValidationRule/ThemeSchema/ReportSchema/SpanSchema 这些名字两边都有,盲替会把消费 spec 的引用一并改错 —— 那正好制造出本 issue 要消灭的那种「名字说的和实际指的不是一回事」。

可靠做法是先改声明与 barrel,让 tsc 把所有断裂点列出来逐个判定。这次人工排除的真危险点有三处(clientValidation.ts 从 @objectstack/spec/ui 导入 ReportSchema/ThemeSchema、report-schema.ts、spec-report.ts 的 ReportSchema as SpecReportSchema_ 导入别名),同时 tsc 也确实抓到了 3 处我漏改的引用。

验证

台账 144 → 129(types 侧 71 → 44),--ledger 重生成后逐条 diff:removed 恰为这 15 个、added 为空。变异测试:把 FilterBuilderCondition 改回 FilterCondition → 守卫按名+按文件报红。全仓 type-check 78/78,全量测试 8696 断言绿(752 文件)。

本仓进度小结

组	状态	台账变化
先导(安全派生)	objectui#3057	64 → 59(types)
C(.passthrough() 静默放行)	objectui#3063	结构性修复,无台账变化
A(纯撞名改名)	objectui#3068	59 → 44(types);全仓 144 → 129
B(type 语义冲突)	待拍板	8 处,TS+Zod 各一份

B 组仍需先定命名约定:spec 的 type 是页面/报表种类,objectui 的是渲染器判别式。注意 A 组已经把 *ComponentSchema(节点)/ *UnionSchema(联合)这套约定在 report/theme 两处统一了,B 组若沿用同一套会比较自洽 —— 但那是维护者的决定,本轮没有擅自扩大。

[os-zhuang]

B 组已落地(objectui#3074)—— objectui 侧四组全部处理完

B 组是 type 的语义冲突:spec 的 type 是页面/仪表盘的种类(record|app|utility|list|home),objectui 的 type 是组件判别式('page'),种类被挪到 pageType。所以 spec 写法 {type:'list'} 的页面在 objectui 直接校验失败,objectui 的 pageType 在 spec 那边被静默丢弃 —— 而两者顶着同一个名字。

AppSchema → AppComponentSchema,DashboardSchema → DashboardComponentSchema,PageSchema → PageNodeSchema。

一个值得写进 issue 正文的教训:改名也会撞名

Page 本来要叫 PageComponentSchema(维护者钦定的约定)。但 PageComponentSchema 本身已经是 @objectstack/spec/ui 的导出,而且它指的是页面区域内部的一个组件({type: PageComponentType, properties, …}),不是页面本身。用它等于把本 issue 要消灭的缺陷原样搬到隔壁概念上。

这不是推演 —— 那个 PR 的第一版真的用了 PageComponentSchema,被守卫按名拦下。 所以:给撞名符号挑新名字时,新名字必须先过一遍守卫,否则很容易从一个碰撞滑进另一个。建议在修法模板里补一句。

方法上的两个坑(都被工具抓到,不是靠眼睛)

1. 多行 import 块:import {\n PageSchema as SpecPageSchema,\n} from '@objectstack/spec/ui' —— 成员行本身不含 spec 路径,所以任何「跳过含 @objectstack/spec 的行」的启发式都会漏。4 处 spec 导入别名被误改,特征是 …ComponentSchema as Spec…。
2. apps/ 目录:objectui 的消费者不只在 packages/ 下,apps/console 也有引用。tsc 抓到了。

再次印证前一条评论的建议:不要做全局字符串替换,先改声明和 barrel、让 tsc 列出断裂点逐个判定。这一轮 tsc + 守卫合计抓到我 3 类疏漏。

objectui 侧总账

组	PR	台账
先导(安全派生)	objectui#3057	types 64 → 59
C(.passthrough() 静默放行)	objectui#3063	结构性修复(39 个 spec 键从不校验变为校验)
A(纯撞名改名,15 个)	objectui#3068	types 59 → 44
B(type 语义冲突,3 个)	objectui#3074	types 44 → 41

全仓台账 156 → 126,@object-ui/types 71 → 41。

余下的性质变了

types 剩的 41 条不再有「纯撞名」这一类 —— 全是 FORK_DRIFTED,即同一个概念但两边形状已经不一致(FormField/SelectOption/ActionParam/NavigationItem/ObjectPermission/SharingRule/五个 *Validation/QueryAST/DriverInterface 等)。每一条都要单独决定「派生 + 收敛差异」还是「保留差异 + 记录理由」,没有机械做法,也不适合再按组批量推进。

其中有几条我在分诊时标注过、值得优先看:

• ObjectPermission —— objectui 内部有两个互不兼容的版本,而 app-shell/…/PermissionPreview.tsx 里那个恰恰是 spec 形状的手抄件;
• NavigationItem/NavigationItemSchema —— spec 侧是 9 个变体的判别联合且每个目标字段必填,objectui 是一个全可选的扁平接口,badgeVariant 少了 secondary、group 展开键名不同(expanded vs defaultOpen);
• 五个 *Validation(Script/StateMachine/CrossField/Conditional/Format)—— 注释都写着 "ObjectStack Spec v2.0.1",而装的是 17.0.0-rc.0,condition 在 spec 已是 Expression 对象而本地仍是裸字符串。