SYNC_ARCHITECTURE.md 的 L3 Connector 示例不可编译,且写的是 schema 会**拒收**的键名(sourceField / targetField / transform.type: 'custom' / webhook retryPolicy)

发现于 #4963(修 L2 ETLPipeline 示例)时用同一套 compiler-API 探针顺手量了同文件的 L3 段,不在该 PR 范围内 —— 属主是 integration/connector.zod.ts,不是 automation/etl.zod.ts。

事实

packages/spec/docs/SYNC_ARCHITECTURE.md 的 "Level 3: Enterprise Connector → Example"(const sapConnector: Connector = { … },约 200–300 行)逐字丢给 ts.createProgram(strict: true,@objectstack/spec/* 映射到 entry barrel,types: ['node']),报四条诊断:

TS2322: Type 'string' is not assignable to type
        '{ dialect: "cel" | "cron" | "template"; source?: string | undefined; ... }'
TS2353: Object literal may only specify known properties,
        and 'sourceField' does not exist in type '{ source: string; target: string; ... }'
TS2322: Type '"custom"' is not assignable to type
        '"map" | "lookup" | "constant" | "cast" | "javascript"'
TS2353: Object literal may only specify known properties,
        and 'retryPolicy' does not exist in type
        '{ name: string; url: string; method: ...; timeoutMs: number; isActive: boolean; signatur…'

逐条对照 schema:

示例写的	schema 实际声明	位置
`fieldMappings[].sourceField` / `targetField`	`source` / `target`	`packages/spec/src/shared/mapping.zod.ts:101` 起(`ConnectorFieldMappingSchema` extends 它,`connector.zod.ts:121`)
`transform: { type: 'custom', function: … }`	`type` 只接受 `map` / `lookup` / `constant` / `cast` / `javascript`	`shared/mapping.zod.ts` 的 `FieldMappingTransformSchema`
`webhooks[].retryPolicy: { … }`	`WebhookConfigSchema` 没有这个键	`connector.zod.ts:284–309`
`syncConfig.schedule: '/15 * * *'`	见下	—

sourceField 不是"随便写错的键",它是 schema 里挂了 curated alias 的被拒键:packages/spec/src/integration/connector.test.ts:1028 的注释写着 sourceField: 'a', // a real alias, deliberately: the message must name it —— 也就是说该文档示例照抄进去会被 strict schema 明确拒收并提示改名。这正是 Prime Directive #10 里"绝不宣传运行时不兑现的能力"的反面,而且是 AI 作者最可能直接复制的那种行数。

第四条(cron 字符串)是另一个 #4963:connector.zod.ts:742 是 export type Connector = z.infer(…),而 ConnectorInput = z.input(…) 在 744 行 —— 该文件用的是第三种命名(XInput 而非 house convention 的 XParsed),而示例注解用的是 parsed 的裸名 Connector,于是 syncConfig.schedule 的裸 cron 字符串被拒。这一条改注解或改约定都能解,不必和上面三条捆绑;#4963 的裁定路线(裸名翻转 + *Parsed)在这里迁移面不为空,要单独裁定 —— connector.zod.ts 有 20 个 z.infer 裸名别名且是 live parse path(ConnectorSchema.syncConfig)。

同文件另两段 L3 片段(Migration Guide 的 "Before (L3 syncConfig)" / "After (L3)")用裸 ... 做省略,不是 TypeScript,属于示意草图,不在此列。

建议

前三条是纯文档修正(把示例改成 schema 真的接受的键名和取值),可以独立于第四条先做。#4963 的 PR 里已经加了 packages/spec/src/automation/etl-author-shape.test.ts,它把该文档的 ```typescript 块总数钉死为 6 并逐字编译其中 3 段 ETL 块;把 L3 段也纳入同一个门是自然的下一步,但需要先决定第四条怎么解,否则门进不去。

未验证的部分

只量了 SYNC_ARCHITECTURE.md。content/docs/references/integration/connector.mdx 和 connector.zod.ts 自己的 @example 是否有同样的键名错误,没查。

分诊结论

分类:pm:queue
领域:domain:spec

核对结果(对照 origin/main,均已复核):

packages/spec/src/shared/mapping.zod.ts 的 FieldMappingSchema(基,ConnectorFieldMappingSchema 在 connector.zod.ts extend 它)只声明 source/target,没有 sourceField/targetField;FieldMappingTransformSchema 是判别联合,type 只接受 constant | cast | lookup | javascript | map,没有 custom。
connector.zod.ts 的 WebhookConfigSchema(WebhookSchema.extend({ events, signatureAlgorithm }))链上确实没有 retryPolicy 键。
export type Connector = z.infer<...> / ConnectorInput = z.input<...> 属实,裸名是 parsed 形状,故文档里 syncConfig.schedule 的裸 cron 字符串编译不过。
packages/spec/docs/SYNC_ARCHITECTURE.md 在 origin/main 上 L3 sapConnector 示例(205–262 行)原样带着 sourceField/targetField/type: 'custom'/retryPolicy 四处问题,前提未过期,缺陷仍然存在。

去重:全组织搜索未发现同主题的重复 issue 或在飞 PR。唯一相关的开放 PR #5514(修 #4963)同样改了本文件,但 diff 核实过只动了 L2 ETLPipeline 段落,完全没碰 L3 Connector 段,不构成冲突或阻塞。

理由:前三条(sourceField/targetField→source/target、transform.type 去掉 'custom'、去掉 webhooks[].retryPolicy)是定位明确、可独立执行的纯文档修正,不依赖任何未决裁定。第四条(裸名 Connector vs ConnectorInput 的 house convention 选择)issue 本身已言明"改注解或改约定都能解"、可独立于前三条推进,不构成阻塞前三条排队的理由,后续 PR 里按 #4963 已确立的分析路数处理即可,不必上升为 needs-user-decision。落地文件锚点:packages/spec/docs/SYNC_ARCHITECTURE.md(主要改动)与 packages/spec/src/integration/connector.zod.ts/packages/spec/src/shared/mapping.zod.ts(比对依据),均属于 packages/spec,对应 domain:spec。

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

Generated by Claude Code

docs(spec): 说清 L3 块被跳过的真实理由,并指向 #5515

PM 认领(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05)

分支:claude/issue-5515-sync-arch-l3-sap
工作树:../objectstack-5515-sync-arch-l3(基于最新 origin/main)
域:domain:spec
文件面:packages/spec/docs/SYNC_ARCHITECTURE.md(主改动)+ L3 段编译门(etl-author-shape.test.ts 扩展或旁立 connector-author-shape.test.ts);比对依据 integration/connector.zod.ts、shared/mapping.zod.ts(只读)
范围裁定:前三条键名修正 + 第四条按改示例注解为 input 形状解(connector.zod.ts 20 个 z.infer 裸名别名的约定翻转是独立 appetite,本单不动);fix(spec): automation/etl.zod.ts 的九个别名回到 X / XParsed house convention (#4963) #5514 已合并,块数钉子(6)如变动须在 PR 里显式说明
与在飞 [spec] 退役 HookContext session.roles —— #4839 双删后零消费方零生产方(ADR-0049) #5050、docs-gen: .describe() 里的 {{var}} 在生成的参考文档里被转义成 ` {{var} + 游离的 }`(main 上现存 3 处) #5452 及同批 ChartDrillDownSchema.target 少一个成员:objectui 的 ObjectChart 现在兑现 'navigate',而 #5022 定型的联合按「chart 不读它」把它排除了 #5435、44 个 strictUnknownKeyError 直接调用点的别名表在 #5013 闸门覆盖之外(实测干净,但无人看守) #5483 文件面互不相交
派发:os-dev(opus)。若本评论之前存在不同 session 的认领,以先者为准、本认领作废。

Generated by Claude Code

验收通过(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05)—— PR #5603。

四处修正落地:source/target 规范拼写、transform 取 javascript 成员(裸串为 ExpressionInput 简写)、retryPolicy 删除 + [P2] Aspirational-config disposition: reconcile-or-prune the still-dead props from the 2026-06 liveness audit (Theme / Translation / Job / Webhook) #3494 墓碑注释(并区分下方 retryConfig)、注解改 ConnectorInput(含 Migration Guide 两处草图,避免同篇教两种注解)。
新编译门 integration/connector-author-shape.test.ts 为 etl-author-shape.test.ts 兄弟门:先证红复现 issue 四条诊断逐字一致,反向验证四探针具名变红 + 规范对照组绿;运行期措辞三键各钉(key 判决 / 静默剥离 / value 判决)。块数钉子 6 不变。
前提细节更正有价值:sourceField 在 connector 面是静默丢弃(curated alias registry 属 ./data 的 ImportFieldMappingSchema,非 ConnectorFieldMappingSchema),比 issue 描述的拒收更难自查——已按事实钉进门里。
范围外发现三单已立:integration/connector.zod.ts 的 20 个裸名别名仍是 z.infer,与 #4963 确立的 X / XParsed house convention 相反(作者写的是 ConnectorInput) #5551(20 个裸名别名翻转,Blocked-by 本单)、shared/mapping.zod.ts 的 javascript 变换 describe 推荐 dialect="js",而 ExpressionDialect 只有 cel/cron/template —— 照着写会被拒 #5552(dialect="js" 已退役却在 describe 里推荐)、SYNC_ARCHITECTURE.md 的 L3 段仍在三处宣传 Rate Limiting,而 connector.rateLimitConfig 及其整个形状已在 #4911 退役 #5554(L3 散文仍宣传已退役的 Rate Limiting)。
tests/docs-only,skip-changeset 已打并生效。

落地暂缓:ESLint job 因 #5604(main 侧 engine-double-contract 断裂,与本单无关)全仓红,修复落地后本 PR 合 main 重跑 → ready → auto-merge。

Generated by Claude Code

fix(spec): `automation/etl.zod.ts` 的九个别名回到 `X` / `XParsed` house conv…

docs(spec): fix the L3 `Connector` example in SYNC_ARCHITECTURE.md an…

test(spec): security, ai, identity, integration, migrations, marketpl…

Navigation Menu

Repository navigation

`SYNC_ARCHITECTURE.md` 的 L3 `Connector` 示例不可编译,且写的是 schema 会拒收的键名(`sourceField` / `targetField` / `transform.type: 'custom'` / webhook `retryPolicy`) #5515

事实

建议

未验证的部分

分诊结论

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

SYNC_ARCHITECTURE.md 的 L3 Connector 示例不可编译,且写的是 schema 会**拒收**的键名(sourceField / targetField / transform.type: 'custom' / webhook retryPolicy) #5515

Description

事实

建议

未验证的部分

Activity

os-zhuang commented on Aug 5, 2026

分诊结论

os-zhuang commented on Aug 5, 2026

os-zhuang commented on Aug 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`SYNC_ARCHITECTURE.md` 的 L3 `Connector` 示例不可编译,且写的是 schema 会拒收的键名(`sourceField` / `targetField` / `transform.type: 'custom'` / webhook `retryPolicy`) #5515