`ApiEndpointSchema` / `ApiMappingSchema` 还有三处 `.describe()` 在向作者推销 publish 门整键拒绝的能力(`type: 'script'|'proxy'`、`target` 的 "Script Name, or Proxy URL"、`ApiMapping.transform`)

[qq9340100]

越范围发现,记录于 #5310(path 的 .describe() 举例被 ADR-0121 D1 拒)实现期。不在该 PR 内修 —— #5310 的判据是「举例失实」,下面三处不是举错例子,而是「文案推销的能力,门整键拒绝」,是另一类问题;其中一处还要连带动 packages/runtime。

事实

packages/spec/src/api/endpoint.zod.ts 里三处文案,描述的都是 endpoint-publish-gate.ts 会整键拒绝的东西:

文案	门怎么判
type: z.enum(['flow','script','object_operation','proxy']).describe('Implementation type')	targetGate:Only 'object_operation' and 'flow' endpoints execute in 17.x,script / proxy 一律拒
target: z.string().describe('Target Flow ID, Script Name, or Proxy URL')	文案里三选项中的两个(Script Name、Proxy URL)对应的 type 都会被上面那条拒掉
transform: z.string().optional().describe('Transformation function name')	mappingGate:There is no transformation-function registry anywhere in the platform,声明即拒

为什么和 #5310 是同一个要紧的理由

#5271 之后 api 是注册元数据类型,这些 .describe() 成为 metadata-admin 端点表单的字段说明,并进入生成的 JSON Schema。作者(按 ADR-0033,常常是 AI 作者)照着表单里「Target Flow ID, Script Name, or Proxy URL」写一个 proxy URL,publish 才告诉他这条路不存在 —— 一次可以在授权时就避免的往返。

门的拒绝文案本身写得很好(点名事实、给出处方),所以这不是「作者被卡死」,而是「词表在邀请一个它自己会拒的写法」。

为什么不是简单改掉就完事(需要裁决,不要预判)

1. 词表是冻结的(17.x 立项:建设声明式 ApiEndpoint 执行器(挂载 + matchEndpoint + authRequired/cacheTtl/inputMapping/outputMapping 逐键接线) #5040)。script / proxy / transform 是故意留在词表里、在门上响亮拒绝的 —— targetGate 明说 Both stay in the vocabulary and are rejected here rather than parsed and ignored。所以问题不是「删掉」,而是「一个被冻结保留、当前被拒的键,该不该在作者表单里自陈『暂不可用』」。这是产品面裁决,不是打字错误。
2. transform 的文案是被引用的规范来源。 packages/runtime/src/api-mapping.ts 的词表小节把五条 .describe() 逐字列成表格,并声明「everything below is the MINIMAL faithful reading of them」。改 transform 的文案必须同批改那张表,否则运行期的最小忠实解读引用了一段不存在的文本 —— 文件面会从 packages/spec 扩到 packages/runtime。

可能的方向(不预判,列给裁决)

• A:文案原样,靠门的拒绝文案兜底(现状)。成本零,代价是表单持续邀请被拒写法。
• B:三处文案各加一句「17.x 尚不执行,publish 会拒」,措辞复用门的拒绝文案。要同批更新 packages/runtime/src/api-mapping.ts 的引用表格 + 重生成 content/docs/references/api/endpoint.mdx。
• C:更进一步,让表单层按门的判据把这些取值置灰/标注 —— 落在 objectui,范围远大于文案。

倾向 B(在授权时结构性地防错,而不是靠消费端容忍),但 A/B 之间取舍取决于维护者对「冻结词表里的被拒键要不要自陈」的态度,故不在 #5310 里替裁决。

关联

#5310(出处,已修 path 的举例)、#5271、#5040 E7、ADR-0121 D1、ADR-0049 declared-vs-enforced。

[claude]

分诊(主分诊轮):needs-user-decision + domain:spec,⛔ 不入 pm:queue。

分类理由(为什么归决策箱)

正文自陈的裁决点是产品语义面,分诊侧核过后同意:词表是 #5040 冻结的,script / proxy / transform 是故意留在词表里、在门上响亮拒绝的(targetGate 原话 Both stay in the vocabulary and are rejected here rather than parsed and ignored)。所以问题不是打字错误、也不是「删掉」,而是「一个被冻结保留、当前被整键拒绝的键,该不该在作者表单里自陈「17.x 尚不执行」」——公共 authoring 契约的对外措辞取舍,不是 PM 可代决的技术路由。A(现状,靠门的拒绝文案兜底)/ B(三处文案各加一句,复用门的措辞)/ C(表单层置灰,落 objectui)三条路径的成本与作用域差一个量级,交维护者拍。

⚠️ 入箱前已按 #6015 的流程缺口通报读全评论流:本单 0 条评论、无任何既有裁决,不属「决定已做、标签说没做」形态(#4829 那一类)。

域/落点锚定(实读 origin/main,不按标题词汇猜)

domain:spec。三处文案在 origin/main 逐字命中,行号具体:

• packages/spec/src/api/endpoint.zod.ts:67 — type: z.enum(['flow','script','object_operation','proxy']).describe('Implementation type')
• :68 — target: z.string().describe('Target Flow ID, Script Name, or Proxy URL')
• :15 — transform: z.string().optional().describe('Transformation function name')

对应的门在 packages/spec/src/api/endpoint-publish-gate.ts(同包)。B 路线会把文件面从 packages/spec 扩到 packages/runtime/src/api-mapping.ts(它把五条 .describe() 逐字列成表格并声明为 minimal faithful reading —— 改文案必须同批改那张表,否则运行期引用一段不存在的文本)与重生成 content/docs/references/api/endpoint.mdx。跨包但主要落地站点是 packages/spec,且按跨座位转移协议「shared contract surfaces have one owner」,触 packages/spec 一律归 domain:spec 座位 —— 故不拆跨域 sub-issue,单标 domain:spec,packages/runtime 的连带修改由该座位在同一 PR 内带走。

过时前提检查

git log --oneline origin/main -- packages/spec/src/api/endpoint.zod.ts 最近一条为 7f1a635(#5904,registry-injected system columns),未触及这三条 .describe();三段文案实读仍在。前提成立。

查重(三仓 open issue + open PR 各一遍)+ 一条硬串行

不是重复单,但撞上一个在飞 PR:

• PR docs(spec): ApiEndpointSchema.path 的 .describe() 换成 ADR-0121 carve-out 形状的示例 (#5310) #6064(draft,ApiEndpointSchema.path 的 .describe() 举的例子会被 ADR-0121 D1 当场拒绝 —— 而这段文案正是 Studio 端点表单显示给作者的提示 #5310 的交付)修的正是同一个文件 —— 实读 diff:packages/spec/src/api/endpoint.zod.ts、packages/spec/src/api/apis-publish-gates.test.ts、content/docs/references/api/endpoint.mdx、.changeset/*。⇒ 本单必须排在 PR docs(spec): ApiEndpointSchema.path 的 .describe() 换成 ADR-0121 carve-out 形状的示例 (#5310) #6064 之后,B 路线的三处文案 + mdx 重生成与它逐字重叠,同批并行会撞。
• ApiEndpointSchema.path 的 .describe() 举的例子会被 ADR-0121 D1 当场拒绝 —— 而这段文案正是 Studio 端点表单显示给作者的提示 #5310 本身不与本单收敛:其判据是「举例失实」(path 的例子会被 ADR-0121 D1 当场拒),本单是「文案推销的能力被门整键拒绝」,修法与裁决点都不同 —— 正文这一点划分核过,同意,⛔ 不关 duplicate、不并入 ApiEndpointSchema.path 的 .describe() 举的例子会被 ADR-0121 D1 当场拒绝 —— 而这段文案正是 Studio 端点表单显示给作者的提示 #5310。
• 其余同区域命中均判为不同问题:ApiEndpointSchema 在 #5312 把 api 注册成元数据类型之后仍是开放 z.object —— apis: 条目的未声明键两条路都静默落地,严格性账本还把 api/ 整目录记作「wire,按设计宽容」 #5384(ApiEndpointSchema 仍是开放 z.object,pm:on-hold)、TS 作者写不出「省略 authRequired」这个安全形状:ApiEndpoint 是输出类型,authRequired 在上面是必填 #5227(authRequired 的输出类型必填,pm:queue)。objectui / cloud 侧零命中。

给裁决方的一句(不预判)

正文倾向 B。分诊侧只补一条与裁决无关的事实供定价:B 的连带面已由上面的落点段核实为三个文件 + 一份生成物,不含任何门逻辑改动 —— 即 B 是纯文案面,不改变 publish 门今天的判定行为。C 落 objectui,若取 C 需按 rule 2 拆 sub-issue(spec 先行)。

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

---

Generated by Claude Code

[claude]

Disposition (2026-08-07): returned to the queue — this did not need the maintainer.

Direction B: the three .describe() strings on type / target / transform each gain one clause saying the value is not executed in 17.x and publish will reject it. The gate's behaviour changes by exactly zero characters, so this is not a public-contract question — it is copy that repeats what endpoint-publish-gate.ts already says at rejection time, moved to where the author is writing. One sentence, reversible.

Same pass: the verbatim mirror table in packages/runtime/src/api-mapping.ts and the regenerated endpoint.mdx. Missing the mirror is how the next declared≠enforced issue gets filed.

Serialization note is now void: PR #6064 (#5310) merged, so the file is free.

Operator: PM session session_01GcjbQLUQKysMU9uXB34iyv; maintainer ruling 2026-08-07 (decision-inbox round 2). Veto window open — comment or reopen to overturn.

---

Generated by Claude Code

[qq9340100]

Riding sweep #6243 —— 本单已并入首次 sweep 打包试点,由 draft PR #6288 的七条 Fixes 之一关闭(会话 session_011M7UwH25Unfi73UHim7ajY,分支 claude/issue-6243-description-truth-sweep)。按 2026-08-07 裁决 方向 B 实施:type / target / ApiMapping.transform 三处 .describe() 各自点明 17.x 不执行、publish 会拒,措辞复用 endpoint-publish-gate.ts 的拒绝文案;packages/runtime/src/api-mapping.ts 那张逐字镜像表的 transform 行同批更新(该模块自陈是这五条 describe 的 MINIMAL faithful reading,不同批改就会引用一段不存在的文本);content/docs/references/api/endpoint.mdx 已重生成。

⛔ 词表仍冻结(#5040),门的判定行为零字符变化。一处比正文更细的实读:target 的文案里补了「object_operation 由 objectParams.object / .operation 寻址」——targetGate 与 endpoint-executor.ts 的 plan 构造均已核过,两者对该 type 都不读 target。

---

Generated by Claude Code