`api` 注册表条目声明 allowRuntimeCreate: true,但运行时创建的端点匹配器永远看不见 —— 声明的能力运行时不兑现(真实 boot 实测)

[baozhoutao]

发现于 #5224 / PR #5487 的前提重核(真实 showcase boot,objectstack dev --fresh,47 plugins)。不在该单文件面内,按 Prime Directive #10 单独立项。这就是 #5224 body 里列的方向一(收敛取数源),PM 在 #5224 的解锁裁定里明确留作「更大的架构统一,另行立项」。

事实

DEFAULT_METADATA_TYPE_REGISTRY 里 api 的条目声明:

packages/spec/src/kernel/metadata-plugin.zod.ts:760
{ type: 'api', label: 'API Endpoint', ..., allowRuntimeCreate: true, ... }

allowRuntimeCreate: true = 平台声明允许在运行时(Studio / 元数据写入口)创建一条 api。实测确实允许:

PUT /api/v1/meta/api/e8_backdoor  {...}  → HTTP/1.1 200 OK
   {"success":true,"version":"sha256:9ad721f4...","seq":1,"state":"active",
    "message":"Saved customization overlay (env-wide, state=active) — type=api ..."}

但这条端点永远不会被服务:

GET /api/v1/apps/showcase/backdoor   (匿名)  → 404
GET /api/v1/apps/showcase/backdoor   (已鉴权) → 404

而且不是被门拒的 —— 整轮 dev 日志里没有 [EndpointMatcher] ... EXCLUDED 那一行(#5189/#5203 的 E7b 装载期门压根没被走到)。

原因(与 #5224 同一条断链,另一个方向)

服务判据的持有者是 IMetadataService.matchEndpoint → EndpointMatcher → MetadataManager.listForIndex('api'),它只读 manager 自己的 registry + 已注册 loader(dev/serve 上是 ["filesystem","memory"])。运行时写入落的是 sys_metadata,不在这两者之中,所以匹配器的索引里根本不存在这一条。

#5224 修的是「面不许谎报」(PR #5487 已让两个面只宣告匹配器会服务的集合)。本单是反方向:注册表声明了「可以运行时创建」这一能力,而运行时不兑现它。PR #5487 之后症状更清楚也更尖锐 —— 作者写入得到 "Saved",随后那条在 /meta/api 列表里也不见了(单条 GET|PUT|DELETE /meta/api/{name} 仍可达,服务端日志会点名它),因为面已经诚实了,而底下的能力仍然是空的。

三种可能的收口(不预设结论,判据不同)

1. 收敛取数源:让 matchEndpoint 与 getMetaItems 读同一个库(一条路由一个所有者的元数据版本)。最彻底,兑现 allowRuntimeCreate: true,让 Studio 创作声明式端点真正可用;代价是匹配器要读 sys_metadata(以及随之而来的失效/缓存/多租户语义,和 ADR-0110 D3 的 miss vs outage 之分必须在新取数路径上重新成立)。
2. allowRuntimeCreate: false:承认 17.x 的声明式端点只能由 stack artifact / publishPackage 落地,注册表如实声明,写入口按 metadata: allowRuntimeCreate:false is not enforced — PUT /meta creates job and agent items the registry declares code-only #5086 的既有机制拒收。最省,但等于关掉一条已经写进注册表的能力 —— 属于 ADR-0049 enforce-or-remove 的 remove 侧,要走对应的退役流程。
3. 保持现状但让写入口大声拒绝:与 api 不在 metadata 类型注册表里 —— Studio 直写路径完全不校验端点,publishPackageDrafts 也没有 E7 门 #5206 同侧(它的领地是 publishPackageDrafts 的 E7 门 + Studio 直写校验),把「你可以存,但它永远不会生效」在写入的那一刻就说清楚。

三条的长期代价不同,请维护者裁决。相关:#5224 / PR #5487(面侧已修)、#5206(写入口)、#5311、#5086(allowRuntimeCreate:false 未被强制执行 —— 本单是它的镜像:true 未被兑现)、ADR-0121、ADR-0049。

复现

pnpm dev:showcase -- --fresh -p 39720 --seed-admin
# 登录取 token
curl -X PUT .../api/v1/meta/api/e8_backdoor -d '{"name":"e8_backdoor","path":"/api/v1/apps/showcase/backdoor","method":"GET","type":"object_operation","target":"showcase_task","objectParams":{"object":"showcase_task","operation":"find"},"authRequired":false}'   # → 200
curl .../api/v1/apps/showcase/backdoor    # → 404,且日志中无 EXCLUDED 行

[os-zhuang]

分诊结论(triage-only PM 座位,#5474 试点):needs-user-decision + domain:engine。

分类理由:本单是 #5224 PM 解锁裁定中明确留白的「方向一 —— 收敛取数源」,与另外两条(allowRuntimeCreate: false 退役 / 写入口在写入当场拒绝)并列的产品语义 / 公共契约裁决,三条路线长期代价不同(是否要让 Studio 运行时创作声明式端点真正生效、是否要关闭已写入注册表的能力、还是仅在写入口加大声拒绝)。issue 正文本身写明「请维护者裁决」,不是一个有单一正确修法的具体缺陷,故不适用 pm:queue。

前提重核(未过时):git -C objectstack fetch origin main 后核对——packages/spec/src/kernel/metadata-plugin.zod.ts:760 的 api 条目仍声明 allowRuntimeCreate: true;packages/metadata/src/metadata-manager.ts 的 listForIndex()(EndpointMatcher.matchEndpoint 的唯一数据源)仍只遍历 this.registry + this.loaders,不读写入口落库的 sys_metadata,与正文描述的断链完全一致。

跨仓/跨单去重:org 内搜索 EndpointMatcher/allowRuntimeCreate 未发现在飞的 open issue 或 PR。#5224(两面不得说谎)已由 PR #5487 落地关闭,其 PM 验收评论原文将「方向一」的立项工作明确甩给本单,故非影子重复而是既定衍生单。#5206(注册表+schema 绑定)、#5311(saveMetaItem 门外通路)、#5086(allowRuntimeCreate:false 未强制)均是同一问题族里相邻但不重叠的写入口领地,且均已 completed 关闭,不构成阻塞。

域标签理由:无论维护者最终选哪条路线,主要改动面都落在 packages/metadata(EndpointMatcher / MetadataManager.listForIndex)和/或 packages/metadata-protocol(saveMetaItem 写入口),两者均属 packages/metadata* 通配,对应 domain:engine。若维护者选择方向二(改注册表声明为 allowRuntimeCreate: false),该改动会先落 packages/spec(domain:spec),存在跨域可能——已在 PM 报告中注明,留给维护者/PM 决定是否需要按 spec-first 顺序拆分为两单。

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

---

Generated by Claude Code

[claude]

裁决(2026-08-06):方案 2——退役 api 的运行时创建,allowRuntimeCreate: false。

注册表如实声明(metadata-plugin.zod.ts:760 翻 false),写入口由 #5086 既有机制当场响亮拒绝;stack 工件路线不动(它有真实消费:showcase apis:、#5040 E8 已 LIVE)。依据:实测全仓 0 个 .api.* 工件、运行时创建零消费;#5021/#4988/#4834 判例——已发布零消费能力不因沉没成本豁免;可逆(将来 Studio 端点创作有真实拉动时,注册表翻回 + 走方案 1 收敛取数源)。

实施:spec-first,动 packages/spec 走 ADR-0049/0087 退役流程;按「shared contract surfaces have one owner」,spec 半边归 spec 车道(本单 domain 标签由分诊座位复核)。⚠️ 本裁决同时决定 #5311:落地后该单直接关闭。量级 S。

经办:PM 会话 session_01GcjbQLUQKysMU9uXB34iyv;维护者 2026-08-06 审阅决策简报后授权按建议执行(否决窗口:可评论/重开推翻)。

---

Generated by Claude Code

[os-zhuang]

【裁决落地】维护者 2026-08-06 批复全舰队决策箱评估报告(批复「同意」),本单裁定:

裁 2——allowRuntimeCreate 改声明 false,走 ADR-0049 remove 侧退役流程(spec-first:先落 spec 声明变更,再清 engine 侧死路与写入口)。理由:该能力从未兑现过(matcher 只读 registry+loaders,运行时创建的端点永远 404)——无存量用户依赖,诚实退役优于兑现大工程;将来真要 runtime create 再走新 ADR 立项。

与 #5311(裁 B:直写 active 不算发布,强制 draft→publish) 同场落地,构成一致世界观:api 端点只经 publish 流。写入口按 #5206 同侧「大声拒绝」处理运行时 PUT。

流转:摘 needs-user-decision → pm:queue,归 engine-core 车道,与 #5311 同批派发或串行。

评估与落地会话:session_01N3uGFF8teXbpgtbEJ1aYXu

---

Generated by Claude Code