docs(client-sdk): 合规矩阵链接如实标注为已退役,并指向真正的事实源 (#5878)

[hotlong]

Fixes #5878

问题

content/docs/api/client-sdk.mdx 的 "Protocol Compliance Documentation" 一节把 packages/client/CLIENT_SPEC_COMPLIANCE.md 描述成:

Method-by-method verification of all API methods across 13 namespaces

而该文件今天第一行就是 # @objectstack/client — Spec Compliance Matrix (RETIRED)。正文自述:2026-07-27 已被 #3563 路由审计退役;当年 "FULLY COMPLIANT" 结论是拿 DEFAULT_DISPATCHER_ROUTES(一张运行时无人消费的表,列了 2 个不存在的域、漏了 8 个存在的域)量出来的;按服务端真实路由面重测,审计当天有 27 条路由没有 SDK 表达。

被链接方已自我否定,链接方仍按它退役前的口径宣传它。 危害在点进去之前就已发生:读者(尤其是照 backlog 找「协议覆盖在哪看」的 agent)先信这条,再发现白跑。

改动

一行,按立单者倾向的方向 1(保留链接 + 如实描述):

• 链接文字加 (retired),链接本身保留 —— 墓碑文件的存在理由就是「不断入链」;
• 描述改为如实陈述:何时、被谁退役,以及当年结论为何不成立;
• 补上「今天覆盖在哪断言」的去处:packages/runtime/src/route-ledger.ts 与两侧 conformance 测试。

事实核实(逐条对 origin/main)

写进文档的事实	核实结果
2026-07-27 被 #3563 路由审计退役	CLIENT_SPEC_COMPLIANCE.md 首段原文
27 条路由无 SDK 表达	同上,原文
packages/runtime/src/route-ledger.ts	存在
packages/runtime/src/route-ledger.conformance.test.ts	存在(dispatcher 侧 guard)
packages/client/src/route-ledger-coverage.test.ts	存在(client 侧 guard)

措辞与本页上方 #5874 已落地的 Callout("Coverage is CI-enforced, not hand-asserted")保持同口径,不新增第二套说法。

范围纪律

• ⛔ 未动 packages/client/CLIENT_SPEC_COMPLIANCE.md —— 它是有意保留的墓碑,自述 "Hand-maintained compliance tables drift; this one is not coming back";
• ⛔ 未重建任何合规矩阵 —— 那正是被退役的做法。若认为读者仍需要一个独立的「协议覆盖导航页」,建议独立立单,不作本单 rider;
• 申报文件面之外零改动:1 file changed, 1 insertion(+), 1 deletion(-)。

同日 churn 核对(前提验证)

本页今日已被 PR #5874(7357130,#5824)碰过,行号已移位,故按内容而非行号定位。核对结论:#5874 没有顺带改掉本单这条 —— 其 commit message 原文写明「同一节里那条仍把该退役文件宣传成『逐方法验证 13 个 namespace』的链接不在本单范围,已按 Prime Directive #10 另行立单:#5878」。前提成立。

自验(前台执行,build 持共享 flock)

• pnpm --filter @objectstack/docs build → exit 0;新文案已进入构建产物(.next/server/app/en/docs/api/client-sdk.rsc 与 .next/server/app/llms.mdx/docs/api/client-sdk.body)
• pnpm check:nul-bytes → OK(扫描 5763 个受追踪文本文件,无裸控制字节)
• pnpm check:doc-authoring → OK(362 files clean)
• pnpm check:docs-audit-scope → OK(178 hand-written docs 与 content/docs/ 同步)
• pnpm check:role-word → OK(no new occurrences)

ESLint 与 TypeScript Type Check 不覆盖 content/**/*.mdx(eslint.config.mjs 无 mdx/content 相关配置),本改动不在其扫描面内;Check Links 当前为 workflow_dispatch only,不在 PR 上跑,新增链接已人工确认在 main 上存在。

Changeset

docs-only,不发布任何包 → 不提交空 changeset,PR 打 skip-changeset。

---

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 6, 2026 3:04pm

[github-actions]

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

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

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

• Dogfood Regression Gate (3/3) — 失败步骤: Set up job（日志不可读，点进 job 看）

历史信号：

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

分诊清单：

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

---

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

[github-actions]

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

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

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

• Temporal Conformance (live PG + MySQL) — 失败步骤: Set up job（日志不可读，点进 job 看）

历史信号：

• ⚠️ 本 PR 过去 24h 已在队列失败 1 次（不含本次）。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突，重排不解决。
• 过去 24h 队列共有 20 个失败构建（不含本次）。

分诊清单：

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

---

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