refactor(runtime)!: 退役 runtime 导出的 HttpServer 委派包装器 (#5122)

[qq9340100]

Fixes #5122

按 2026-08-06 维护者裁决退役 @objectstack/runtime 导出的 HttpServer 委派包装器(#4939「从未被装配的件退役优于修」先例 + ADR-0049 remove 侧)。⛔ 不做条件转发,⛔ 不做「维持 + 文档标注」。

前提复核(在最新 origin/main 上)

• packages/runtime/src/http-server.ts 的 class HttpServer implements IHttpServer 仍是只转发必选成员的形态(get/post/put/delete/patch/use/listen/close),getPort? / getRawApp? / setFallbackHandler? 一个都不转发 —— 与 issue 描述一致。
• 组合点仍为零:new HttpServer( 全仓(含 examples/)零命中。反查对照用同族邻居 new HonoHttpServer( 命中 20+ 处,证明搜索本身有效,不是空搜。
• 该符号在仓内的全部出现只有两处:类文件自身,和 packages/runtime/src/index.ts:48 的 barrel 导出。没有测试构造过它(packages/runtime/src/ 下无 http-server.test.ts),scripts/adr-anchors.json 未锚定它,也没有任何 baseline/ledger 记名。

改动

1. 删除 packages/runtime/src/http-server.ts。
2. 从 runtime barrel 移除导出,原地留一条 NOTE:说明为什么退役、以及正确的组合方式是直接注册 IHttpServer 适配器实例为 http.server(每个真实 host 本来就是这么做的),防止同型包装器被复刻。
3. 新增 packages/runtime/src/http-server-retirement.test.ts —— 运行期缺席钉子(3 条),带反空转守卫。
4. changeset:@objectstack/runtime major(public API 移除),正文含迁移表、以及「E7(#5040 执行器):翻转 —— publish 硬拒收窄为「不支持子集 + 命名空间门」,声明式端点随 v17 放行执行 #5111 之后 setFallbackHandler 是声明式 apis: 端点唯一通路」这一事实 —— 这句话存在的目的就是阻止未来有人再造一个丢弃可选成员的同型包装器。fix(runtime): 无 setFallbackHandler 的适配器改以 warn 宣告声明式端点不可达 (#5400) #5409 已落的 warn 宣告继续作为 runtime 侧兜底(它能点名 seam 缺席,但点不出吞掉 seam 的包装器,所以两者不重复)。

为什么钉子是运行期探测而不是类型级

packages/runtime/tsconfig.json 排除了 **/*.test.ts,tsc --noEmit 读的就是这份配置,vitest 又从不做类型检查(#4311)—— 这正是 #4642 记录的陷阱:类型级钉子在这里是空转的。所以用 namespace 探测 + 反空转守卫(barrel 导出数量下限 + Runtime 在场),并额外钉住源文件不存在(防止它以「不导出的私有包装器」形态回来),该断言自己也带路径反空转守卫(邻居 http-dispatcher.ts 必须在)。

barrel 用静态 namespace 导入而非用例内 await import():这个 barrel 冷启动要几秒,放进用例会撞 vitest 5s 默认超时 —— 那是 flake,不是发现(第一版就撞了)。

反向验证(方向在运行前先行预测)

预测:把删掉的类文件与 barrel 导出同时还原,两条移除钉子应转红(它们读的是「在场」谓词,不是可以靠「什么都不产出」蒙混过关的计数),而第三条「邻居导出仍在」应保持绿——它是反空转搭档,不是移除钉子。

实测与预测一致:

Tests  2 failed | 1 passed (3)
FAIL … > the barrel exports no `HttpServer`
  AssertionError: @objectstack/runtime must not export HttpServer: expected true to be false
FAIL … > the module file is gone, so it cannot come back as an unexported private wrapper
  AssertionError: packages/runtime/src/http-server.ts is retired (#5122) …: expected true to be false
✓  … > keeps the HTTP exports that were its neighbours — the deletion took nothing with it

随后已还原为移除态。

验证

合入 origin/main(含已合并的 #6122)后重跑:

pnpm --filter @objectstack/runtime test
  Test Files  104 passed (104)
       Tests  1490 passed (1490)

pnpm --filter '@objectstack/runtime^...' build && pnpm --filter @objectstack/runtime typecheck
  > tsc --noEmit          (无输出 = 通过)

npx eslint packages/runtime/src/index.ts packages/runtime/src/http-server-retirement.test.ts --no-inline-config
  exit 0

pnpm check:nul-bytes / check:adr-anchors / check:doc-authoring / check:published-files /
check:type-check-coverage / check:release-notes / check:route-envelope /
check:error-code-casing / check:engine-double-contract / check:empty-changeset
  全部 OK

刻意未做

• @objectstack/http-conformance 的 setFallbackHandler 断言(ADR-0076 OQ#10):裁决写的是「随退役 PR 顺手或另拆」,实测不顺手 —— 参考适配器 NodeHttpServer 目前不实现该成员,所以想让断言有意义,要么先给第二个适配器补实现(那是功能 PR,不是移除 PR),要么写一条只跑 Hono 的条件用例(那对「跨适配器一致」什么也没证明)。已另拆为 [finding] @objectstack/http-conformance 对 IHttpServer.setFallbackHandler 零断言 —— ADR-0076 OQ#10 的落点仍空着 #6143(finding,未入队)。
• docs/adr/0004-cloud-multi-kernel.md:76 提到 RestServer / HttpServer:那是一份已接受 ADR 的历史记录,退役不推翻它的决定,按 Prime Directive [WIP] Add Chinese version of the documentation #13 不在代码 PR 里改写 ADR 正文。
• packages/runtime/src/dispatcher-plugin.ts:与已合并的 fix(runtime,types)!: /analytics/query 不再回显 RLS 策略字段名 —— 声明式 server-fault withhold 提升为两个边界共享 (#5811) #6122 面不相交,本 PR 未触碰(已把 origin/main 合入本分支,fix(runtime,types)!: /analytics/query 不再回显 RLS 策略字段名 —— 声明式 server-fault withhold 提升为两个边界共享 (#5811) #6122 已在其中,零冲突)。
• content/docs/releases/:未触碰。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wbxm29qPKnLf44AbSxizqW

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 3:19am

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx (via packages/runtime)
• content/docs/api/index.mdx (via @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/runtime)
• content/docs/kernel/cluster.mdx (via @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/runtime)
• content/docs/permissions/authorization.mdx (via packages/runtime)
• content/docs/plugins/packages.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/index.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/runtime)
• content/docs/releases/implementation-status.mdx (via @objectstack/runtime)
• content/docs/releases/v17.mdx (via @objectstack/runtime)

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.