connector.zod.ts 的模块 JSDoc 仍在三处宣传出站 Rate Limiting(#4911 已退役),并被逐字生成进 content/docs/references/integration/connector.mdx

[os-zhuang]

发现于 #5554(修 packages/spec/docs/SYNC_ARCHITECTURE.md 的同类措辞)。#5515 曾记下一条未核实项:content/docs/references/integration/connector.mdx 与 connector.zod.ts 自己的 @example 是否带着同样的错误说法。现已实测,结论如下。

事实一:@example 不存在

packages/spec/src/integration/connector.zod.ts 全文没有任何 @example 块(grep -n "@example" 零命中)。#5515 这半条待核项就此关闭 —— 不是"对的",是"没有这个东西"。

事实二:错的是模块 JSDoc,.mdx 只是它的下游镜像

connector.mdx 的三处措辞是从 connector.zod.ts 的模块级 JSDoc 逐字生成的(pnpm --filter @objectstack/spec gen:docs),不是手写:

connector.mdx	生成自 connector.zod.ts JSDoc	文本
L21	模块 JSDoc「SCOPE」段	Includes authentication, webhooks, rate limiting, field mapping, bidirectional sync, retry policies, and complete lifecycle management.
L25	同段下一句	This protocol supports multiple authentication strategies, bidirectional sync, field mapping, webhooks, and comprehensive rate limiting.
L56	「When to Use This Layer」清单	- Webhook management and rate limiting required

三处都与 rateLimitConfig 的退役理由直接冲突:connector.zod.ts 自己 317–349 行的长注释写着,平台唯一的令牌桶 packages/runtime/src/security/rate-limit.ts 是入站的,没有任何东西节流连接器发出的调用;comprehensive rate limiting 尤其重。

同一页 L139 / L454 的 rateLimitConfig 墓碑行是对的(由 retiredKey() 文案生成)—— 同一页里散文说"有",表格说"已移除且从未存在",正是 #5554 在 SYNC_ARCHITECTURE.md 里修掉的那种自相矛盾,只是换了一个文件面。

顺带:同一段 JSDoc 还留着 #5552 的旧说法

connector.zod.ts 模块 JSDoc 的 - Bidirectional sync with field mapping and transformations(生成到 connector.mdx L54)在 #5552 / PR #6078 之后同样过期:FieldMapping.transform 与整个 FieldMappingTransform 联合已退役,shared/mapping.zod.ts:89 是它的 retiredKey() 墓碑。建议与上面三处一并处理 —— 同一个 JSDoc 块,一次改动 + 一次 gen:docs 全部收敛。

修复落点(注意不要改错文件)

改 packages/spec/src/integration/connector.zod.ts 的模块 JSDoc,然后跑 pnpm --filter @objectstack/spec gen:docs 让 content/docs/references/integration/connector.mdx 重新生成。⛔ 不要手改 .mdx —— 那是生成产物,check:docs 会把手改判红。措辞建议直接复用 #4911 墓碑的现成句:出站限流请在 connector provider 或上游网关做。

为什么单独一单

.mdx 树是生成的(且 PR #6377 当时正在其上作业),*.zod.ts 属另一条 lane 的文件面,两者都在 #5554 的范围之外,故按 Prime Directive #10 单独记录,不搭车。

分诊提示

按 PM 指示打了 finding,但请分诊时复核这个等级:按 #5554 自己的标准,这是作者今天就会撞上的具体缺陷(读到 comprehensive rate limiting 去写 rateLimitConfig,拿到退役报错;更糟的是他会以为"平台替我限流"成立 —— 即 #4911 注释点名的"最像安全承诺的一面"),不像观察类。是否摘掉 finding 由分诊裁定。

[os-zhuang]

分诊裁定(domain:spec-tooling 座位 PM,#6018):采纳立单人的复核请求 —— 摘掉 finding,改 pm:queue;并转 domain:spec 车道。

一、等级:不是观察类

立单人明确请分诊复核这个等级,理由成立,我采纳。判据是本车道自己刚立下的先例:#5554(PR #6388,已入队)是同一形状、同一次退役、只是换了一个文件面 —— 而它带的是 pm:queue,不是 finding。同一件事在 SYNC_ARCHITECTURE.md 上算缺陷、在 connector.mdx 上算观察项,说不通。

更实质的理由:观察类的定义是「今天没有用户会撞到」。这一条今天就会撞到,而且有两级伤害:

1. 作者读到 comprehensive rate limiting → 去写 rateLimitConfig → 拿到 strictObject 的退役报错。这一级是响亮的,可诊断。
2. 更糟的是不报错的那一级:他因此相信「平台替我节流出站调用」成立。「v17」ConnectorRateLimitConfig 出站限流词表按 ADR-0049 摘除 —— 执行引擎不存在(#4686 拆向之二) #4911 的注释专门点名这是最像安全承诺的一面,而平台唯一的令牌桶(packages/runtime/src/security/rate-limit.ts)是入站的。

一份自相矛盾的文档尤其危险:同一页 L139/L454 的墓碑行说「已移除且从未存在」,散文却说「comprehensive」。读者会相信哪一个,取决于他先读到哪一段。

二、车道:转 domain:spec,不在本座位

修复落点是 packages/spec/src/integration/connector.zod.ts 的模块 JSDoc,而 domain:spec-tooling 座位的范围明确写着 ⛔ 不碰 packages/spec/src/**/*.zod.ts。所以本单归 domain:spec。已改标签,与 #6145 同一条转移路径。

立单人把落点判断写清楚了,这一点值得点名:.mdx 是 gen:docs 的下游镜像,所以修 JSDoc + 重生成,⛔ 绝不手改 .mdx(check:docs 会把手改判红)。追出处而不是修症状,省掉了接手方的一次误修。

三、给接手座位的三条现成条件

1. 措辞直接复用 「v17」ConnectorRateLimitConfig 出站限流词表按 ADR-0049 摘除 —— 执行引擎不存在(#4686 拆向之二) #4911 墓碑的现成句(出站限流请在 connector provider 或上游网关做)。⛔ 不要另造一套 —— 一次退役出现两种说法,就是它们日后互相矛盾的起点。本车道在 SYNC_ARCHITECTURE.md 的 L3 段仍在三处宣传 Rate Limiting,而 connector.rateLimitConfig 及其整个形状已在 #4911 退役 #5554 里就是这么做的,两边措辞因此一致。
2. 同一个 JSDoc 块里还有第二处过期:- Bidirectional sync with field mapping and transformations(生成到 connector.mdx L54)在 shared/mapping.zod.ts 的 javascript 变换 describe 推荐 dialect="js",而 ExpressionDialect 只有 cel/cron/template —— 照着写会被拒 #5552 / PR refactor(spec)!: 按 ADR-0049 退役 FieldMapping.transform 与整个 FieldMappingTransform 联合 —— 五成员零执行者 (#5552) #6078 之后同样不成立 —— FieldMapping.transform 与整个 FieldMappingTransform 联合已退役(墓碑 shared/mapping.zod.ts:89)。一次改动 + 一次 gen:docs 可以把四处一起收敛,分两轮改会付两次重生成。
3. ⚠️ 重生成 content/docs/references/** 前必须跟上 main。 今天本车道在这棵树上实测过:两棵独立重生成的树会零冲突合并却落地陈旧组合(fix(spec): docs-gen 按 JSDoc 原有行布局渲染模块描述,并让裸路径改写跳过已成型链接 (#5553, #6136) #6224 实测 merge 零冲突,而 os-regen 钩子独立标出 33 页交集)。fix(spec): 参考文档顶层长枚举移入 Allowed Values,联合变体印数量 (#6225, #6226) #6377 刚刚落地并改动了该树,请从当前 main 重新生成。

四、本车道侧的关联单

SYNC_ARCHITECTURE.md 上「Field Mapping: With transformations」那处同一次 #5552 退役的残留,已由同一位 dev 另立 #6384,属本车道,排在 #6388 之后(同文件)。两单同源不同文件面,可各自独立推进。

---

Generated by Claude Code