integration/connector.zod.ts 的 20 个裸名别名仍是 z.infer,与 #4963 确立的 X / XParsed house convention 相反(作者写的是 ConnectorInput)

[os-zhuang]

从 #5515 拆出。#5515 的第四条诊断(syncConfig.schedule 的裸 cron 字符串编译不过)在那张单里是按"改示例注解"解的(PR 把 SYNC_ARCHITECTURE.md 的 L3 示例改成 const sapConnector: ConnectorInput = …),根因没有动 —— 这里记的就是根因。

事实

packages/spec/src/integration/connector.zod.ts:742/744:

export type Connector = z.infer< typeof ConnectorSchema >;
/** Authoring input for {@link Connector} — defaulted fields are optional. */
export type ConnectorInput = z.input< typeof ConnectorSchema >;

即裸名 = parsed 形状,作者形状挂在 XInput 上。这是仓库里的第三种命名:

文件	裸名	作者形状	出处
shared/retry-policy.zod.ts 及绝大多数兄弟	z.input(作者写的)	裸名	house convention
automation/etl.zod.ts	z.input	裸名,parse 结果是 XParsed	#4963 / PR #5514 翻过来的
integration/connector.zod.ts	z.infer	ConnectorInput	本单

后果和 #4963 一模一样:const c: Connector = { … } 这条唯一的裸注解authoring 门编译不过,因为 enabled / status / connectionTimeoutMs / syncConfig.strategy / syncConfig.direction / syncConfig.batchSize / syncConfig.deleteMode / syncConfig.realtimeSync / syncConfig.conflictResolution / 字段映射的 required / syncMode / webhook 的 method / timeoutMs / isActive / signatureAlgorithm 在 z.infer 下全是必填,且 syncConfig.schedule 是 CronExpressionInputSchema 的 transform 输出({ dialect, source } 信封),裸 cron 字符串被拒。文档示例照抄进去就是这个后果,#5515 的红证据是逐字量出来的四条诊断之一。

与 #4963 的差别:迁移面不为空

etl.zod.ts 当时可以直接翻,因为 objectstack / objectui / cloud 里都没有 parse 站点。本文件不是:

• 该文件有 20 个 z.infer 裸名别名(Connector / ConnectorFieldMapping / DataSyncConfig / WebhookConfig / SyncStrategy / ConnectorConflictResolution / …)。
• ConnectorSchema 是 live parse path:defineConnector() 就在同文件 748 行 return ConnectorSchema.parse(config),返回类型标的是裸 Connector;DeclarativeConnectorEntrySchema 走 stack.zod.ts。
• 枚举类别名(SyncStrategy 等)z.input 与 z.infer 同构,翻不翻都一样;真正有形状差的是对象类。

所以这是一次真实的 breaking rename,需要按 #4963 的路数单独裁定后再做,不能顺手带过。

建议的处置

按 #4963 的结论迁移:裸名改为 z.input(作者形状),parse 结果改名 XParsed,ConnectorInput 作为过渡别名保留一版还是直接删,连同 defineConnector 的返回类型一起在同一个 PR 里定。需要先确认 20 个别名里哪些真有形状差(枚举可豁免),以及 objectstack / objectui / cloud 三仓的 importer 面。

现状不是无人看守

#5515 的 PR 加了 packages/spec/src/integration/connector-author-shape.test.ts,里面有一组探针把"同一份字面量在 ConnectorInput 下绿、在 Connector 下红"钉死了。真做这次翻转时,那组探针会直接变红,是迁移的第一处落点。

---

Blocked-by: #5515

[os-zhuang]

分诊:pm:queue + domain:spec,同时挂 pm:blocked(正文已加 Blocked-by: #5515)。

• 落点锚定:packages/spec/src/integration/connector.zod.ts(origin/main:742 实测仍是 z.infer 裸名)+ 三仓 importer 面核对,归 domain:spec。
• 为什么入队而不是决策箱:X / XParsed house convention 已由 automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963 裁定并经 PR fix(spec): automation/etl.zod.ts 的九个别名回到 X / XParsed house convention (#4963) #5514 落地为先例,本单是把既定惯例应用到第三个偏离文件;与 automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963 的差别(迁移面不为空、defineConnector live parse path、ConnectorInput 过渡别名去留)属实现内决策,在 PR 里定即可,不需要新的产品拍板。
• 串行理由:SYNC_ARCHITECTURE.md 的 L3 Connector 示例不可编译,且写的是 schema 会**拒收**的键名(sourceField / targetField / transform.type: 'custom' / webhook retryPolicy) #5515 的 PR 携带 connector-author-shape.test.ts 探针组,是本迁移的第一处落点 —— 必须等它 MERGED 后开工,故 Blocked-by: #5515;解锁后回队。
• 查重:三仓检索 ConnectorInput 仅命中本单与 SYNC_ARCHITECTURE.md 的 L3 Connector 示例不可编译,且写的是 schema 会**拒收**的键名(sourceField / targetField / transform.type: 'custom' / webhook retryPolicy) #5515,无影子单。
• 派发提示:枚举类别名 input/infer 同构可豁免,先量 20 个别名的形状差与三仓 importer 面再动手。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-zhuang]

解锁(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-06):Blocked-by: #5515 已随 PR #5603 落地,摘 pm:blocked 回队。派发注记:integration/connector.zod.ts 20 个裸名别名翻 X/XParsed 约定,迁移面不为空(defineConnector 是 live parse path)——派发时 dev 须先测量全部消费方对类型别名更名的影响面(#5678 CLI pin 教训同型),connector-author-shape.test.ts 的 ConnectorInput/Connector 探针组是第一落点。排队序:第三轮后。

---

Generated by Claude Code

[os-zhuang]

PM 认领(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-06,#5731 落地后队列补位)

• 分支:claude/issue-5551-connector-input-convention;工作树:../objectstack-5551-connector-convention(基于最新 origin/main);域:domain:spec
• 文件面:packages/spec/src/integration/connector.zod.ts(20 个别名翻转)+ connector-author-shape.test.ts(第一落点)+ 三仓 importer 面 + 生成物(走生成器)
• 裁定依据:automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963 X/XParsed house convention(PR fix(spec): automation/etl.zod.ts 的九个别名回到 X / XParsed house convention (#4963) #5514 先例);ConnectorInput 过渡别名去留、defineConnector 返回类型属实现内决策,按测量在 PR 里定
• 硬前置:先测量 20 个别名的形状差(枚举 input≡infer 豁免)与三仓全部消费方对更名的影响面(ADR-0117 D1 声明面:ownership 枚举扩展 'business_unit'(须与列注入同 PR 或严格后置) #5678 CLI pin 教训同型);测量出预期外的 live 依赖即停手回报
• 在飞不触面:filter 词表族(spec: $regex 按 ADR-0049 退役 + $icontains 入算子词表与 FILTER_LOGIC_CASES(#4706 裁决 B 案 · 契约半边,先行) #5701)、data/object.zod.ts(TenancyConfigSchema.tenantField 的默认值是 'tenant_id',但平台的租户列叫 organization_id —— 两个 spec 文件对「默认值」的说法互相矛盾 #5315)、ui/component.zod.ts(feat(spec)!: RecordDetailsProps.sections 改为真实的对象形式,并补声明 hideFields (#5611) #5734 在飞)、api routes/mcp(routes.mcp 是 REST /discovery 发出、objectui 真实消费、但 ApiRoutesSchema 从未声明的键(#4828 同族,低一层) #5679)
• 派发:os-dev(opus)。更早不同 session 认领者优先,本认领作废。

---

Generated by Claude Code

[os-zhuang]

实测回报:前提被证伪,零文件改动,回报 needs_decision

开发 session session_018fxLGQdatPbBUvCgiVxg6D,分支 claude/issue-5551-connector-input-convention(工作树已建,未提交任何改动),基线 origin/main@5e3c83bd0。

按派发单的硬前置先做测量。本单关于 connector.zod.ts 的事实全部属实,但它的定性——「这是仓库里的第三种命名 / 与已确立的 house convention 相反 / 本单是把既定惯例应用到第三个偏离文件」——与 origin/main 实测相反。因此我没有动手翻转,把测量交回分诊。

---

测量一:仓库里这两种惯例的真实分布(这条推翻了本单的前提)

对 packages/spec/src/**/*.zod.ts 全量统计裸名别名的方向:

	数量
裸名 = z.infer(即 connector.zod.ts 的写法)	1384
裸名 = z.input(即 #4963 的写法)	86

再按「作者形状挂在哪个名字上」分两族:

族	形态	别名数	文件数	覆盖域
A(#4963)	裸名 = z.input,parse 结果 = XParsed	36	8	automation/ 7 个 + shared/retry-policy.zod.ts
B(connector 现状)	裸名 = z.infer,作者形状 = XInput	108	55	api/、automation/、data/、identity/、integration/、kernel/、security/、shared/、system/、ui/ —— 几乎每个域

A 族 8 个文件全名单:automation/{builtin-node-config,control-flow,etl,execution,flow,io-node-config,schemaless-node-config}.zod.ts + shared/retry-policy.zod.ts。

也就是说 integration/connector.zod.ts 不是「第三种命名」,而是 55 个文件里的一员;#4963 那种才是 8 个文件的少数派。 本单表格里「shared/retry-policy.zod.ts 及绝大多数兄弟」这一行,与实测的 86 : 1384 相反。

测量二:这三处一手材料都把 A 族惯例限定在 automation/,没有任何一处说它是全仓惯例

1. shared/retry-policy.zod.ts:171 的 JSDoc(automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963 引为「写得最清楚」的出处),原文限定语是:

   matching the house X / XParsed convention used by the sibling control-flow configs.

2. automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963 正文自述:「etl 是 automation/ 里最后一个没跟上的文件」。
3. 仍开着的 automation/ 里还有两处 X / XParsed 未兑现:execution.zod.ts 的七对别名两边都是 z.infer,ScreenFieldConfig 缺 Parsed #5507(finding)标题:「automation/ 里还有两处 X / XParsed 未兑现」。

docs/adr/ 全量检索:没有任何 ADR 记载这条命名惯例(A 族、B 族都没有)。所以不存在一条「已定裁决」可以援引来把 A 族推到 integration/。

测量三:B 族的 XInput 不是随手写的,它被下游契约钉着

packages/qa/downstream-contract/src/additional-domains.fixtures.ts 同时 import 了 11 个域的 XInput,ConnectorInput 是其中之一:

DatasourceInput, MappingInput, CubeInput, ObjectExtensionInput,
ConnectorInput, SharingRuleInput, PermissionSetInput, PositionInput,
EmailTemplateDefinitionInput, TranslationBundleInput, WebhookInput, ThemeInput

该文件头部写着「the spec's own input aliases. DO NOT migrate these to the defineX factories and DO NOT edit them to make a failing spec change pass」。单独翻转 connector,会让它成为这份 fixture 里唯一没有 XInput 的域。

---

附:派发单要求的两份测量(已完成,供再分诊使用)

20 个别名的形状差(用编译器探针逐个断言 z.input 与 z.infer 是否同构,双向反证:枚举全绿、带默认值的对象全红,说明探针不空转):

• 真有形状差(10):ConnectorFieldMapping、DataSyncConfig、WebhookConfig、RetryConfig、ErrorMappingConfig、HealthCheckConfig、CircuitBreakerConfig、ConnectorHealth、Connector、DeclarativeConnectorEntry
• 同构可豁免(9):8 个枚举(SyncStrategy、ConnectorConflictResolution、WebhookEvent、WebhookSignatureAlgorithm、ConnectorRetryStrategy、ConnectorErrorCategory、ConnectorType、ConnectorStatus)+ ErrorMappingRule(无 .default()、无 transform)
• 第 20 个是 ConnectorInput,本就是 z.input。(顺带更正:本单说「20 个 z.infer 裸名别名」,实际是 19 个 z.infer + 1 个 z.input。)

三仓 importer 面(若将来真要翻,这是完整迁移面;没有发现预期外的 live 依赖):

• objectstack:裸 Connector 的类型位用法分两类角色,翻转后可机械二分——
  • parse 输入角色(翻转后保持裸名):engine.registerConnector(def) / registerDegradedConnector(def)(两者内部都是 ConnectorSchema.parse(def))、4 个 connector 插件的 ConnectorRegistrySurface.registerConnector(def)、createXConnector() 手写字面量、ConnectorMaterialization.def(经 { ...materialization.def, name } 喂回 registerConnector)
  • parse 结果角色(须改名 ConnectorParsed):RegisteredConnector.def(engine.ts:442,存的是 parsed)、showcase 的 allConnectors: Connector[](装的是 defineConnector() 返回值)
  • 其余 18 个别名在 packages/spec 之外零类型位 importer(命中的全是 CHANGELOG / changeset 叙述文字)
• objectui:0。9 处命中全是英文 UI 文案(如 connector: 'Connector'),无一是该类型别名。
• cloud:2,均在 plugins/connector-stripe(stripe-connector.ts 的 def: Connector 构造、stripe-plugin.ts 的 registry surface),都是 parse 输入角色。

另注:defineConnector() 现状其实已经是对的——入参 z.input、返回 z.infer,与 B 族自洽;RegisteredConnector.def 标 z.infer 也与它存 parsed 的事实一致。按 B 族读,本文件内部无矛盾。

---

需要维护者裁决的问题

全仓到底以哪一族为准? 这不是本单预设的「实现内决策」,它决定 @objectstack/spec 55 个文件的公开类型契约,且要反转或确认一条已落地的决定(#4963 / PR #5514),按 Prime Directive #13 需要 ADR。

• A. 照本单原样翻转 connector 一个文件
  • 长期正确性:负分。把一个文件从 55 人的多数派搬进 8 人的少数派,仓库整体一致性下降,却付出一次 breaking 类型改名;而援引的「既定惯例」并无 ADR,且三处一手材料都限定在 automation/。
  • 让 AI 写的 metadata 不易出错:中性偏负。作者门今天并没有关着——ConnectorInput 和 defineConnector() 都在,SYNC_ARCHITECTURE.md 也已按 PR docs(spec): 修正 SYNC_ARCHITECTURE.md 的 L3 Connector 示例并为其加编译门 (#5515) #5603 写清。翻转不会让门更宽,反而让从另外 54 个文件学到 XInput 的 LLM 在 connector 上单点写错。
• B. 判定 connector 现状正确,关掉本单
  • 长期正确性:局部合理,但仓库仍留着两套并存的方言;且 packages/spec/docs/SYNC_ARCHITECTURE.md:224-226 现在写着 connector「has not been moved onto that house convention yet (integration/connector.zod.ts 的 20 个裸名别名仍是 z.infer,与 #4963 确立的 X / XParsed house convention 相反(作者写的是 ConnectorInput) #5551)」,这句话对「哪一族才是 house convention」的陈述与实测相反,需随裁决一并更正。
  • 让 AI 写的 metadata 不易出错:中性。
• C. 先立 ADR 定一族,再单向收敛(推荐)
  • C1 多数派胜:全仓统一为 裸名 = z.infer + XInput,则 automation/ 那 8 个文件反而要收敛回来(需新 ADR 推翻 automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963,automation/ 里还有两处 X / XParsed 未兑现:execution.zod.ts 的七对别名两边都是 z.infer,ScreenFieldConfig 缺 Parsed #5507 随之改向)。
  • C2 少数派胜:全仓统一为 裸名 = z.input + XParsed,108 个别名 / 55 个文件,面很大,可先纯增量补 XParsed(非 breaking),下一个 major 再翻裸名。
  • 长期正确性:最佳。一条契约写进 ADR,替掉两套 de-facto 方言——正是 Prime Directive Add comprehensive test suite for Zod schema validation #12「one strict contract beats N dialects」用在类型面上。
  • 让 AI 写的 metadata 不易出错:C2 最佳(裸名即作者形状,LLM 顺手写 const c: Connector = { … } 默认就是对的),C1 次之(XInput 全仓一致也可学)。两者都优于现状:今天两套并存,LLM 在某一族上必然猜错。

我的建议:C,且倾向 C2,但无论选哪个,本单按原样单独翻转 connector 都不该做——它在两轴上都不占优,且会让仓库更不一致。若维护者确认 C2 并愿意分期,connector 可以作为增量阶段的一站(先加 ConnectorParsed,不动裸名),那是非 breaking 的,我可以立刻执行。

未新开 issue:本条与 #5551 同题,按查重纪律就地评论而非开孪生单。工作树将拆除,分支无提交。

---

Generated by Claude Code

[os-zhuang]

PM 复审(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-06):dev 的 needs_decision 成立,前提证伪采信(测量见上一条评论:裸名方向 1384 z.infer vs 86 z.input;connector 形态 = 55 文件/108 别名多数派,#4963 形态 = 8 文件少数派且三个一手来源均自限于 automation/;两个约定都无 ADR 记录)。

为什么升级而不当场裁:本题不是派发时授权的实现内决策(过渡别名去留),而是在两个并存的类型面约定之间为 55 个 spec 文件定契约,且任一方向都等于确认或推翻已落地的 #4963/PR #5514——按 Prime Directive #13,推翻已录决定本身是一项需要 ADR 的决定,超出 PM 决断线。

选项(dev 测量给出,PM 附倾向):

• A. 按原单翻 connector 一个文件:⛔ 不建议——多数派搬少数派,付 breaking 代价换一致性下降,两轴全输。
• B. 判 connector 本来就对,关单 + 修正 SYNC_ARCHITECTURE.md:224-226 的误导句:最便宜,但两方言并存的根子留着,automation/ 里还有两处 X / XParsed 未兑现:execution.zod.ts 的七对别名两边都是 z.infer,ScreenFieldConfig 缺 Parsed #5507 类的单还会再来。
• C. 立 ADR 择一约定后单向收敛:
  • C1(多数派胜):裸名=z.infer + XInput 全仓统一;automation/ 8 文件翻回,推翻昨天的 automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963。迁移最小,但「裸名注解 = 作者形状」这扇门在全仓默认关闭,SYNC_ARCHITECTURE.md 的 L3 Connector 示例不可编译,且写的是 schema 会**拒收**的键名(sourceField / targetField / transform.type: 'custom' / webhook retryPolicy) #5515 第四诊断那类缺陷会持续再生。
  • C2(少数派胜):裸名=z.input(作者形状)+ XParsed 全仓;108 别名/55 文件,可分期——先加性铺 XParsed(不破坏,minor),裸名翻转攒到 major。
• PM 倾向 C2:长远轴——用一条被记录的契约取代两套事实方言;防 AI 写错轴——const c: Connector = {...} 这个每个作者(尤其 LLM)默认写出的形状在全仓变成默认正确,C1 只能做到「统一但默认错」。如实呈报成本:55 文件,分期后首期无破坏。

附带:无论裁哪个,SYNC_ARCHITECTURE.md:224-226 那句都要随裁修正;#5507(automation/ 内两处未跟进,finding)与本单同题,裁后一并重分诊(C1 反向、C2 扩面)。

标签转 needs-user-decision,认领保留,裁后按裁定重派(20 别名形状差表 + 三仓 importer 清单可原样复用)。

---

Generated by Claude Code