fix(rest): 两个端点契约面只宣告匹配器实际会服务的集合 (#5224)

[baozhoutao]

Fixes #5224

前提重核（STEP 0，真实 boot 实测，先于任何编码）

在 origin/main（含 #5464 577cd27be）上重跑了 issue body 的三条探针 —— 断链完全复现，前提成立：

PUT /api/v1/meta/api/e8_backdoor            → 200 {"success":true,"version":"sha256:9ad721f4...","seq":1,"state":"active"}
GET /api/v1/apps/showcase/backdoor  (匿名)  → 404 {"error":"Not found"}
GET /api/v1/apps/showcase/backdoor  (鉴权)  → 404 {"error":"Not found"}
GET /api/v1/meta/api                        → 3 条，含 e8_backdoor GET /api/v1/apps/showcase/backdoor authRequired=false
GET /api/v1/openapi.json                    → paths 含 /api/v1/apps/showcase/backdoor
                                              {"get":{"operationId":"e8_backdoor","responses":{"200":...},"security":[]}}

对派发词里点名的两处漂移的实测结论：

1. 写入口仍然 200。feat(spec): api 补进 DEFAULT_METADATA_TYPE_REGISTRY 与 BUILTIN_METADATA_TYPE_SCHEMAS (#5271) #5312 / api 不在 metadata 类型注册表里 —— Studio 直写路径完全不校验端点,publishPackageDrafts 也没有 E7 门 #5206 step 2（PR fix(metadata-protocol): publishPackageDrafts 对 api draft 跑 ADR-0121 端点发布门 (#5206 step 2) #5279）之后，直写 PUT /meta/api/{name} 依旧成功，version 哈希与 body 记录的一模一样（sha256:9ad721f4...）。原因也查清了：api 现在是注册表条目，且带 allowRuntimeCreate: true（packages/spec/src/kernel/metadata-plugin.zod.ts:760）—— 运行时创建是被声明允许的，所以不需要换合法写入路径复测。
2. 不是 E7b 的门在挡。整轮 dev 日志里 [EndpointMatcher] ... EXCLUDED 一行都没有 —— 那条 row 压根没走到门口。E7b 依然正确必要；断链在它下面一层。

同一时刻两条 stack artifact 端点服务正常（/apps/showcase/tasks 鉴权 200 / 匿名 401），确认「不误伤」这一侧有真实基线。

改动（方向裁定：面只宣告匹配器实际会服务的集合）

两个面在宣告前问匹配器，只宣告问回来的那一条。

• 新增 packages/rest/src/served-endpoints.ts —— selectServedEndpoints(items, authority, logger)。它不复刻匹配器的判据（parse、ADR-0121 identity-free 发布门、重复路由裁决），而是逐条调用已有契约方法 IMetadataService.matchEndpoint。这是「不引入第二真相源」的唯一形状：判据只有一处，改了那一处两个面自动跟随。
• 按 name 确认，不是「有人占这条路由就算」：重复声明由匹配器裁决出唯一 owner，落败方不该被宣告。重复规则因此仍然只写在 buildEndpointIndex 一处。
• outage 不等于空集：matchEndpoint 读不到 store 时抛错，这里原样上抛。吞成「什么都没声明」是同一类谎言的反向。
• 每条被略去的声明都被点名（error，每次调用聚合成一行）：说明它的路由 404、以及怎样把它变成真的（走 stack artifact 或 publishPackage）。
• 接缝形状：RestServer 新增最后一个可选构造参数 metadataServiceProvider，rest-api-plugin 接线；解析链与 resolveProtocol / resolveI18nService 同款（多租户先问本请求的 kernel）。⛔ matchEndpoint / EndpointMatcher 的取数逻辑一行未动，packages/runtime 未动 —— 需要的只读接缝已经存在，不必新开。

两处刻意保留原行为，都写在测试里

• GET /meta/api?preview=draft 不过滤：这个面回答的是「什么在待发布」，按定义就不是服务集合，过滤会把它想展示的东西清空。codegen / SDK 读的是不带参数的那条。
• 单条 GET|PUT|DELETE /meta/api/{name} 不过滤：一条不被服务的声明仍然要能被看到和删掉。

为什么 /meta/:type 只对 api 特判

对其他每一个 type，「列出来」和「生效」是同一个事实，由列出它的那个 reader 自己回答完了。api 不是：一条声明式路由由 matchEndpoint 服务，那是另一个 reader、另一个可见范围，并且是该判据的唯一持有者。所以特判的理由不是「api 特殊」，而是「api 是唯一一个服务判据不在本路由视野内的 type」。

反向验证（方向先判后跑）

预判：撤掉收窄 → 面①③ 变红；面② 本来就绿、且应当保持绿，因为它是「不误伤」的守卫 —— 一个会随修复变色的守卫是在钉修复而不是钉不变量。跑完与预判一致：

撤掉两处收窄后（12 个用例）：6 failed | 6 passed
  × omits the runtime-written row the matcher cannot see, and the gate-excluded one
  × applies to the PLURAL spelling too
  × drops the runtime-written path that used to ship with `security: []`
  × ships a document with no declared paths when the matcher serves nothing
  × reports a store outage rather than an empty declaration set
  × keeps enumerating and says so once when no matcher is reachable
  ✓ keeps the served endpoint fully described — no collateral damage   ← 前后都绿，正确
  ✓ leaves `?preview=draft` unfiltered                                  ← 前后都绿，正确
  ✓ does not narrow any OTHER metadata type                             ← 前后都绿，正确

写这份报告时抓到一条本来会绿得没有意义的用例：原先那条「documents the matcher's parsed value, so authRequired is materialized」前后都绿 —— 因为 enrichment 自己也 parse，默认值两条路径都补得出来，它根本区分不了改动。已改写成真正有判别力的形状：让两个 reader 对同一条路由持有不同状态（枚举侧 summary: 'STALE' + authRequired: false，匹配器侧是真值），断言文档描述的是匹配器那一份。单独复跑确认它在撤掉收窄后确实变红。

测试

• packages/rest/src/served-endpoints.test.ts（10 例）—— 收窄语义：保留 / 丢弃 / 重复落败方 / 无 name 或 method 或 path / 空输入 / outage 上抛 / 日志形状。
• packages/rest/src/rest-endpoint-surfaces-served-only.test.ts（12 例，各自 }, 60_000)）—— 用真实 MetadataManager 而不是 stub，因为面①（manager 真的看不见）和面③（E7b 门真的排除）只有对真匹配器才有意义。日志里能看到真实的 [EndpointMatcher] ... EXCLUDED ... ADR-0121 D6 ... 那一行。
• 全包：pnpm --filter @objectstack/rest test → 47 files / 698 tests passed（合入 origin/main（含 chore(ci): job 级 if: 读 needs.*.outputs.* 必须显式点名状态函数 (#5343) #5477、fix(spec): OpenAPI components.schemas 不再是空的 —— lazySchema Proxy 撞上 typeof === 'object',并补上产物自洽门禁 #5459 —— 后者同改 openapi-endpoints.ts）之后复跑仍绿）。
• 消费半径清扫：packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts → 14 passed（它正是「两条 stack artifact 端点必须出现在 openapi 文档里」的既有 pin）。
• npx tsc --noEmit（packages/rest）：只剩 package-routes.ts 那两条既有 TS2345，新文件零错。
• node scripts/check-nul-bytes.mjs OK；另对本 PR 全部改动文件自查 [\x00-\x08\x0b\x0c\x0e-\x1f]，无命中。

打完补丁后的真实 boot 复测（同一套探针）

PUT /api/v1/meta/api/e8_backdoor            → 200（写入口不变，方向三是 #5206 的领地）
GET /api/v1/apps/showcase/backdoor          → 404（匿名 / 鉴权，不变）
GET /api/v1/meta/api                        → 2 条，e8_backdoor 已消失
GET /api/v1/openapi.json                    → declared paths 2 条，/apps/showcase/backdoor 已消失
GET /api/v1/apps/showcase/tasks             → 鉴权 200 / 匿名 401（合法端点照常服务、照常宣告）
dev 日志                                     → "declared api item(s) are OMITTED from this surface ...
                                               'e8_backdoor' (GET /api/v1/apps/showcase/backdoor)"

契约点：隐藏 vs 标注（按裁定实现了隐藏，但这里是代价）

/openapi.json 这一侧没有第二种选择：一个 operation 要么在要么不在，「declared but not served」在 codegen 眼里表达不出来。/meta/api 这一侧本可以标注（items 已经带 _diagnostics），选择隐藏是为了和 OpenAPI 对称。

代价说清楚：api 的注册表条目声明了 allowRuntimeCreate: true，所以运行时创建一条 api 是被允许的，而它永远不会被服务 —— 收窄之后作者在列表里也看不到自己刚存的那条了（单条 GET/DELETE 仍可达，日志也点名了它）。这不是本 PR 造成的破损：那条路由在改动前后都是 404，改的只是面不再谎报。真正的矛盾是「注册表允许运行时创建 / 匹配器永远看不见运行时创建的条目」，已按 Prime Directive #10 另行立项，也就是 issue 里的方向一。

范围

packages/rest/src/** + 测试 + changeset。未动 matchEndpoint / EndpointMatcher 取数逻辑，未动写入口，未动 packages/runtime。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 5, 2026 2:12pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/rest.

11 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/connect-mcp.mdx (via @objectstack/rest)
• content/docs/api/error-handling-server.mdx (via @objectstack/rest)
• content/docs/api/index.mdx (via @objectstack/rest)
• content/docs/permissions/authentication.mdx (via @objectstack/rest)
• content/docs/plugins/index.mdx (via @objectstack/rest)
• content/docs/plugins/packages.mdx (via @objectstack/rest)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/rest)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/rest)
• content/docs/releases/implementation-status.mdx (via @objectstack/rest)
• content/docs/releases/v12.mdx (via @objectstack/rest)
• content/docs/releases/v17.mdx (via @objectstack/rest)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[baozhoutao]

越界发现,已按 Prime Directive #10 单独立项(均未指派,查重含已关闭 issues,无命中):

• api 注册表条目声明 allowRuntimeCreate: true,但运行时创建的端点匹配器永远看不见 —— 声明的能力运行时不兑现(真实 boot 实测) #5488 —— api 注册表条目声明 allowRuntimeCreate: true,而运行时创建的端点匹配器永远看不见。这就是本 issue body 里的方向一,PM 在解锁裁定里留作「另行立项」的那条。本 PR 之后症状更尖锐:作者写入得到 "Saved",列表里也不再有它 —— 面诚实了,底下的能力仍是空的。三条可能的收口(收敛取数源 / 改成 allowRuntimeCreate: false 走 ADR-0049 remove / 写入口大声拒绝)代价不同,列在单里请维护者裁决。
• /meta/:type 上一个未分类的服务端故障被报成 HTTP 400 —— handleRouteError 的兜底把 outage 说成客户端错误 #5489(finding 标签,观察类)—— /meta/:type 上一个未分类的服务端故障被 mapDataError 的终局兜底报成 HTTP 400。与 sendError 的显式状态直通覆盖 400–599,5xx 的原始驱动报错绕过全部泄漏启发式直达客户端(metadata-protocol 有活体产出方) #5437 / PR fix(rest): a declared 5xx no longer ships its own message to the client (#5437) #5464 同一片领地,但那一单看的是 message 侧。本 PR 的用例因此只钉「请求失败、而不是返回一个集合」,注释里写明了不去钉 5xx —— 断言 5xx 会把别人的 bug 钉成好像已经修好。

两条都不在本 PR 里修。

---

Generated by Claude Code

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31015336942 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (3/3) — 失败步骤: Run this shard's tests

  �[41m�[1m FAIL �[22m�[49m src/commands/serve-email-config-parity.contract.test.ts�[2m > �[22ma config the schema accepts reaches the plugin intact�[2m > �[22mspreads defaultTemplateContext OVER the re
  

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 8 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)