发现于 #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 是否有同样的键名错误,没查。
发现于 #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']),报四条诊断:逐条对照 schema:
fieldMappings[].sourceField/targetFieldsource/targetpackages/spec/src/shared/mapping.zod.ts:101起(ConnectorFieldMappingSchemaextends 它,connector.zod.ts:121)transform: { type: 'custom', function: … }type只接受map/lookup/constant/cast/javascriptshared/mapping.zod.ts的FieldMappingTransformSchemawebhooks[].retryPolicy: { … }WebhookConfigSchema没有这个键connector.zod.ts:284–309syncConfig.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是否有同样的键名错误,没查。