docs(plugin-auth,client): 退役两份已脱节的仓内开发文档快照 (#5824)

[baozhoutao]

Fixes #5824

docs-only (deletions), skip-changeset requested —— 两份被删的文件都不在各自包 package.json 的 files 发布清单里(plugin-auth / client 均为 ["dist","README.md","CHANGELOG.md"]),本 PR 不发布任何包,故不提交空 changeset,改由 skip-changeset 标签走豁免(#5804 先例)。

裁决与前提

PM 已裁决取退役路线(不选「重写并挂门」)。实做前逐条核对 origin/main@e2bfa6ce3,issue 前提全部成立:

• packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md 在,陈旧标记原样存续::43 All tests passing (11/11)、:191 🔄 **Phase 3: IN PROGRESS** 配「Placeholder responses implemented / Need to connect actual better-auth API calls」、:213 **Version**: 2.0.2、:214 11/11 tests passing (100%);File Structure 只列 3 个 src 文件,而实际 src/ 下有 61 个文件(含 auth-route-ledger.ts 与其 conformance 测试)。
• packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md 在,Test Suite Structure 列 01…13 一整套 + helpers/,而 packages/client/tests/integration/ 下实际只有 01-discovery.test.ts 与 README.md。

改动逐个文件

删除(2)

• packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md(-216)
• packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md(-808)

承接价值内容(2)

• packages/plugins/plugin-auth/README.md —— README 原本已有 API Routes 一节且四条真名(sign-in/email / sign-up/email / sign-out / get-session)已经正确,唯一缺的是事实源指引,也正是让这份手抄不再漂移的那半句。补上:单一事实源 = src/auth-route-ledger.ts(Enumerate the /auth/** dynamic route family — 54 SDK methods rest on a prefix claim, not a route #3656,由 src/auth-route-ledger.conformance.test.ts 对 auth.api 实表校验),README 下方列表明确降级为 reading aid,并写明与台账冲突时以台账为准 + 那四条假路由的由来(/auth/* 转发层把内部请求对象直接交给 better-auth:未知 auth 子路径(如 POST /api/v1/auth/login)返回 500 并外漏内部 TypeError,而非干净 404/405 #5085 / 仓内两处文档仍把 /api/v1/auth/login(及 /register、/logout、/session)列为已注册 auth 路由 —— 四条端点均不存在 #5772)。⛔ 阶段小结 / 版本号 / 测试计数一律不搬。
• packages/client/tests/integration/README.md —— 这份接收文档自己也带着一份虚构清单(17 个测试文件,含 21 client SDK methods target routes no server surface mounts — delete on the open major train, or build the servers (#3587 finding) #3612 已删除的 permissions / workflow / realtime / views),把假规格删了却留下它,等于换个地方放。故:实际清单改成如实的一行 01-discovery.test.ts 并写明「按清单读,不要从编号推断套件」;未实现部分落成主题级 TODO(⛔ 不抄旧断言 —— 旧断言与 SDK 实际返回形状已对不齐,例如 TC-AUTH-001 断言 session.token / session.expiresAt 在顶层,而 SessionResponse 把 token / user 归一进 data),并要求按当前 packages/client/src/index.ts 的返回形状写、路由名取自 auth 台账;显式标注 21 client SDK methods target routes no server surface mounts — delete on the open major train, or build the servers (#3587 finding) #3612 已删的四个 namespace 不要补测试;末尾注明旧全文可查 git 历史(附 git log --diff-filter=D 命令)。CI 那节删掉「见 CLIENT_SERVER_INTEGRATION_TESTS.md 的示例 workflow」,改为如实说明今天没有 workflow 在跑。

引用面清理(3 个文件 / 5 处) —— git grep -n "IMPLEMENTATION_SUMMARY\|CLIENT_SERVER_INTEGRATION_TESTS" origin/main 全仓 7 处命中,除 1 处在被删文件自身外逐条处置:

• content/docs/api/client-sdk.mdx:148 —— Callout 里「Integration test specifications live in …」改指 packages/client/tests/integration/README.md。
• content/docs/api/client-sdk.mdx:690 —— 这句 Test coverage 声称集成测试覆盖 15 个 namespace,其中 permissions / workflow 是同一份文档上方(:138)刚说过「21 client SDK methods target routes no server surface mounts — delete on the open major train, or build the servers (#3587 finding) #3612 已删除,从无服务端路由」的两个 —— 即被删规格的转述,本身就是一句假覆盖声明。改成如实:namespace 的广覆盖来自单元测试,活服务器集成测试今天只有 discovery 一项,其余在 backlog;逐方法的协议覆盖看下方 compliance matrix。
• content/docs/api/client-sdk.mdx:700 —— 「Integration Test Specifications」条目改指同一个 README 并改写描述。
• packages/client/README.md:306 —— 链接改指 ./tests/integration/README.md。
• packages/client/tests/integration/01-discovery.test.ts:7 —— @see 注释改指同目录 README(本 PR 唯一的非 md 改动,纯注释)。

清理后全树重扫,仅剩接收文档里那段墓碑说明文字(纯 code span,非链接),⛔ 无悬空链接。

发布清单 / 门禁核查

• 两份被删文件均不在 files 发布清单(见开头),删除不改变任何已发布产物;pnpm check:published-files 绿。
• 不在任何门禁脚本的扫描清单里:check-doc-authoring 的 ROOT 是 skills / content / docs / .claude,不含 packages/**;docs-audit 的 scope 由 content/docs/**/*.mdx 派生,本 PR 只改 mdx 内容、不增删 mdx 文件,scope 不变。

验证(全部前台跑完,真实输出)

pnpm check:nul-bytes        ✓ self-test 56 assertions;OK (scanned 5695 tracked text file(s) … no raw ASCII control bytes)
pnpm check:doc-authoring    ✓ 362 files clean — no bare metadata literals
pnpm check:docs-audit-scope ✓ scope is in sync with content/docs/: 178 hand-written doc(s)
pnpm check:published-files  ✓ 69 publishable package(s) … declare a `files` whitelist
pnpm --filter @objectstack/client test        Test Files 19 passed (19) / Tests 236 passed (236)
pnpm --filter @objectstack/client typecheck   tsc --noEmit 通过;check:test-typecheck OK(3 file(s)/6 error(s) 为既有 debt,未增)
pnpm --filter @objectstack/plugin-auth test   Test Files 36 passed (36) / Tests 820 passed (820)
pnpm --filter @objectstack/plugin-auth typecheck  tsc --noEmit 通过

plugin-auth 的 36 个测试文件里包含 auth-route-ledger.conformance.test.ts —— README 新指的事实源本身仍被守着。

另:新增/改写的每一个相对链接目标都实测存在(auth-route-ledger.ts、auth-route-ledger.conformance.test.ts、CLIENT_SPEC_COMPLIANCE.md、tests/integration/README.md)。

范围外

packages/plugins/plugin-auth/ARCHITECTURE.md 按裁决不在本单范围(其 "Before" 框定正确,#5772 已论证)。

关联:#5772(本次退役文档里那两处假路由的窄修)、#5085(假路由发现现场)、#3656(auth 路由台账)、#3612(client 四个 namespace 的删除)。

🤖 Generated with Claude Code

https://claude.ai/code/session_01JwwiU9bjhwy2SWj13ho8uv

---

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 10:48am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/client, @objectstack/plugin-auth.

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

• content/docs/ai/skills-reference.mdx (via packages/client)
• content/docs/api/client-sdk.mdx (via @objectstack/client)
• content/docs/api/data-flow.mdx (via @objectstack/client)
• content/docs/api/environment-routing.mdx (via @objectstack/client)
• content/docs/api/error-catalog.mdx (via @objectstack/client)
• content/docs/deployment/cli.mdx (via @objectstack/plugin-auth)
• content/docs/deployment/production-readiness.mdx (via @objectstack/plugin-auth)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/client)
• content/docs/kernel/contracts/cache-service.mdx (via @objectstack/plugin-auth)
• content/docs/kernel/runtime-services/data-service.mdx (via packages/client)
• content/docs/kernel/runtime-services/index.mdx (via packages/client)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-auth)
• content/docs/permissions/authentication.mdx (via @objectstack/client, @objectstack/plugin-auth)
• content/docs/permissions/sso.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/index.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/packages.mdx (via @objectstack/client, @objectstack/plugin-auth)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/client)
• content/docs/releases/implementation-status.mdx (via @objectstack/client, @objectstack/plugin-auth)
• content/docs/releases/v16.mdx (via @objectstack/client)
• content/docs/releases/v17.mdx (via @objectstack/client)
• content/docs/releases/v9.mdx (via @objectstack/plugin-auth)

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]

追加提交 714722c5 —— 自查发现上一版改写把读者引向了另一份已退役文档

第一版对 content/docs/api/client-sdk.mdx:690 的改写,末句写成「逐方法的协议覆盖看下方 compliance matrix」。核查那条链接的落点时发现:packages/client/CLIENT_SPEC_COMPLIANCE.md 今天第一行就是

# @objectstack/client — Spec Compliance Matrix (RETIRED)

它 2026-07-27 已被 #3563 路由审计退役,并自述当年那个 "FULLY COMPLIANT" 结论是拿一张运行时无人消费的表量出来的(按真实路由面重测,当天有 27 条路由没有 SDK 表达)。把读者指过去,等于用一份自我否定的表替换掉刚删掉的那份假规格 —— 与本 PR 的目的正相反。

已改指真正在 CI 里断言覆盖的 packages/runtime/src/route-ledger.ts 及其两侧 conformance 测试。三个文档门禁在追加提交后重跑,均绿:

pnpm check:docs-audit-scope  ✓ scope is in sync with content/docs/: 178 hand-written doc(s)
pnpm check:nul-bytes         ✓ OK (scanned 5695 tracked text file(s) … no raw ASCII control bytes)
pnpm check:doc-authoring     ✓ 362 files clean — no bare metadata literals

范围外发现,已另行立单

同一节里紧邻的另一条链接仍把这份 (RETIRED) 文件宣传成「Method-by-method verification of all API methods across 13 namespaces」。那是另一个文件、另一处事实,不在本单的引用面(本单被限定为指向被删那两个文件的链接),故按 Prime Directive #10 立为 #5878(observation-class,finding,未认领),不在本 PR 修。

标签与 CI 现状(读回为准)

• 标签读回(等 bot 落定后): size/xl, skip-changeset —— 以并集方式写入,size/xl 未被覆盖。
• 首个 opened run 的 Check Changeset 红:它 10:38:50 启动,标签 10:39:5x 才落地,是 chore(ci): lint.yml 的 typecheck 补 build-core 的 turbo 缓存回退 (#5401) #5542 记录过的那场「首跑 vs 标签落地」赛跑。其后由 labeled 事件触发的三个 Check Changeset run 全部 skipped(豁免生效)。
• 其余 33 项检查全绿,含 Build Docs、TypeScript Type Check、ESLint、Test Core ×3、Dogfood Regression Gate ×3、Temporal Conformance。

---

Generated by Claude Code

---

Generated by Claude Code