ADR-0049:spec 两份 RateLimitConfig 全仓零 reader,真正在限流的是 runtime 自己的第三份形状

[os-zhuang]

在 #4684(双源清账 C9)的调研中发现,记录备查,未认领。

事实

packages/spec 声明了两份 RateLimitConfig,两份都没有任何运行时读者:

$ grep -rn "RateLimitConfig" --include=*.ts packages/ core/ examples/ apps/ \
    | grep -v node_modules | grep -v /dist/ | grep -v "packages/spec/"
(无输出)

对具体键做同样的扫描(windowMs / windowSeconds / maxRequests / burstCapacity / respectUpstreamLimits),packages/spec/src/** 自己的测试之外同样零命中。

四个嵌入点因此全部是「声明了但没人执行」:

嵌入点	声明来源
ApiEndpointSchema.rateLimit(api/endpoint.zod.ts:47)	shared/http.zod.ts
ApiEndpointRegistrationSchema.rateLimit(api/registry.zod.ts:379)	shared/http.zod.ts
HttpServerConfigSchema.security.rateLimit(system/http-server.zod.ts:71)	shared/http.zod.ts
ConnectorSchema.rateLimitConfig(integration/connector.zod.ts:674)	integration/connector.zod.ts

前三个从 stack.zod.ts 的 apis: 可达,第四个从 connectors: 可达 —— 都是真实的作者面,作者写下去解析通过,然后什么也不发生。

更值得注意的:真正干活的是第三份形状

packages/runtime/src/security/rate-limit.ts 有一个手写的 in-memory token bucket,它不 import spec,自带一套接口:

export interface RateLimitBucketConfig {
  capacity: number;       // 对应不上 maxRequests
  refillPerSec: number;   // 对应不上 windowMs / windowSeconds
  defaultCost?: number;   // 两侧 spec 都没有
}

所以现状是 三份 rate-limit 形状、零条从作者面到执行面的通路:两份在 spec 里给作者写,一份在 runtime 里真正限流,互不相识。这正是 Prime Directive #10 的「declared ≠ enforced」与 ADR-0049 的 enforce-or-remove 场景。

建议(留给维护者裁决,不要顺手做)

三选一,都是协议级决定:

1. 接上执行 —— 让 dispatcher 从 ApiEndpoint.rateLimit / HttpServerConfig.security.rateLimit 推导出 RateLimitBucketConfig(capacity = maxRequests,refillPerSec = maxRequests / (windowMs / 1000)),connector 侧同理接到出站调用上。
2. 按 ADR-0049 摘掉 —— 走完整退休套件(tombstone + D2/D3 + changeset)。
3. 先只修 connector 侧,API 侧接执行 —— 出站/入站两个方向的执行者本来就不是同一个。

⚠️ 与 #4684 / #4535 的关系:C9 簇正在裁决这两份声明的命名/收敛路线。本单是执行面的问题,与命名路线正交,但两者的答案会互相影响 —— 如果结论是 2(摘掉一侧),C9 的双源就自动消失了。建议一起排期看。

关联:#4684、#4535、ADR-0049、Prime Directive #10

[xuyushun441-sys]

分诊 + 维护者裁决落档(2026-08-03,PM 会话 session_01Ehu85kbvMcrNTUJjwxvLJ9):

裁决:拆向 —— 入站接执行,出站摘除(经交互确认,三选一里的方案 3 变体)。

分诊时实测更新(立单于 8-02 17:10,C9 #4684 于 19:17 关闭,前提已漂移):

• C9 走的是改名收敛:connector 侧现为 ConnectorRateLimitConfigSchema(connector.zod.ts:337 声明、:711 嵌入),shared 侧仍是 RateLimitConfigSchema(http.zod.ts:127)。正文「结论是 2 则 C9 双源自动消失」的联动已失效 —— C9 已自行了结。
• 零 reader 事实仍成立:spec 之外零命中,同扫描形状对已知被消费符号的阳性对照有命中(扫描器有效)。
• runtime 的 token bucket(rate-limit.ts)只服务入站 dispatcher;出站限流引擎不存在 —— 这是拆向的事实根据:入站是「接线」(执行器已在),出站是「给不存在的引擎养词表」(ADR-0049:plugin-runtime.zod.ts 剩余家族(DynamicLoadRequest / DynamicUnloadRequest / DynamicPluginResult / PluginSource / DynamicPluginOperation)四仓零 runtime consumer —— enforce-or-remove 悬置待裁 #4834 同形状)。

结构:本单转为协调节点(⛔ 不派发),两个子单各自入队、相互独立、文件面不相交:

• 「v17」入站 rateLimit 接执行:ApiEndpoint / HttpServer 的 RateLimitConfig 推导为 runtime token bucket 配置,dispatcher 生效(#4686 拆向之一) #4910 —— 入站接执行(domain:cli,落 runtime/dispatcher;⚠️ 激活语义 = 存量配置升级即生效,D3 + major changeset,v17 窗口)
• 「v17」ConnectorRateLimitConfig 出站限流词表按 ADR-0049 摘除 —— 执行引擎不存在(#4686 拆向之二) #4911 —— 出站摘除(domain:spec,完整退役套件,v17 窗口)

最后一个子单关闭时由 PM 总结关本单。

---

Generated by Claude Code