两个包 README 的版本宣称与自己的 package.json 不符:plugin-chatbot 的 `@ai-sdk/react` v3(实为 ^4.0.47)、layout 的 react peer 比清单更宽

[yinlianghui]

Blocked-by: #3711

在 #3697 的门禁落地过程中,对 38 个 packages/*/README.md 做「README 版本宣称 vs 本包 package.json」逐条核对时量到的。

这一类的特点是有可核实的锚(同包的 package.json),因此和 #3708(散文里没有锚的陈旧宣称)不同:它们可以被机械钉住。全 11 处 peer 重述里 9 处与清单逐字一致,下面这 2 处不一致。

事实

1. packages/plugin-chatbot/README.md:58 — 差一个大版本

using `@ai-sdk/react` v3 (Vercel UI Message Stream protocol) for streaming,

packages/plugin-chatbot/package.json → "@ai-sdk/react": "^4.0.47"。

全语料里唯一一处第三方包的版本宣称,也是唯一一处指名协议来源的宣称 —— 读者会据此去查 v3 的文档。

2. packages/layout/README.md:20 — 宣称比清单更宽

**Peer Dependencies:**
- `react` >= 18.0.0
- `react-dom` >= 18.0.0

packages/layout/package.json → "react": "^18.0.0 || ^19.0.0"。

>= 18.0.0 承诺 React 20 也行,清单的 ^18 || ^19 会拒绝。方向是过度承诺:读者按 README 装 React 20 会拿到 peer 冲突。其余 9 个包的 README 都写 ^18.0.0 || ^19.0.0,与各自清单逐字一致;react-runtime 写 react >= 18 而它的清单恰好就是 ">=18",是对的。

复核:

$ node -e "for (const p of ['layout','react-runtime','plugin-report','auth','components'])
    console.log(p, require('./packages/'+p+'/package.json').peerDependencies.react)"
layout        ^18.0.0 || ^19.0.0
react-runtime >=18
plugin-report ^18.0.0
auth          ^18.0.0 || ^19.0.0
components    ^18.0.0 || ^19.0.0

与 #3690 的边界

packages/plugin-report/README.md:24 也与清单不符(README 写 ^18.0.0 || ^19.0.0,清单只有 ^18.0.0),但那处的正确修法是改清单,已由 #3690 覆盖 —— 修好 #3690,README 自动变正确。故不在本单重复,已在 #3690 下追评说明。本单的两处反过来:清单是对的,README 是错的。

处置倾向(不替分诊拍板)

两条路,取舍留给分诊:

• A 删版本号,按 35 个包 README 的生成块 §Compatibility 版本已陈旧:声称 @objectstack/spec ^3.3.0,实际全仓锁 ^17.0.0-rc.5;部分包还列了自己并不依赖的 @objectstack/client #3645 / PR docs(packages): 退役 36 个包 README 里已死的 release-metadata §Compatibility 生成块 #3688 仓规改指 package.json(「真相已在清单里,由包管理器安装期强制」)。长期最稳,但 README 的 Installation 段落失去「装什么版本」的即答。
• B 保留并钉住:加一条测试断言每个 README 的 peer 重述与本包 peerDependencies 逐字一致。这一类有锚,所以 B 在这里是可行的(content/docs 三处版本宣称失真:architecture-overview 的 @objectstack/spec ^4.0.x(差 13 个大版本)与 architecture.md 的 TypeScript 5.0+ #3708 那一族没有锚,只有 A 可选)。代价是新增一个要维护的对照面。

倾向 B:这 11 行是读者真正会用的信息,且 9/11 今天就是对的,钉住的成本低于删掉的信息损失;#3697 的门禁已经把这 11 处枚举好了,B 只是把「记录」升级成「断言」。但这属于契约取舍,不自行拍板。

门禁现状

#3697 的 PR 已把这 2 处以 kind: 'stale'、其余 9 处以 kind: 'restatement' 记进 scripts/__tests__/doc-version-claims.test.ts。本单修好后须同步更新对应条目,否则 ratchet 测试变红。

已搜重

peerDependencies README react plugin-report(命中 #3690,边界已在上面写明)、版本 文档 失真 drift docs version(仅命中 #3697)两组关键字搜过开放 issue。

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Triage: pm:queue + pm:blocked (Blocked-by: objectstack-ai/objectui#3711). No domain:* — objectui is a whole-repo seat. No transfer: repo-local, no spec surface.

Premise re-verified on origin/main. Both cited mismatches reproduce verbatim:

• packages/plugin-chatbot/README.md:58 — prose says @ai-sdk/react v3; the manifest dependency is ^4.0.47. A whole major, and the card is right that this is the corpus's only third-party version claim and its only claim that names a protocol source, so a reader will go read the wrong spec.
• packages/layout/README.md:20 — README says react >= 18.0.0 / react-dom >= 18.0.0; the manifest peers are ^18.0.0 || ^19.0.0 for both. Over-promise: a reader who installs React 20 on the README's authority gets a peer conflict.

A third line in the same block is also wrong, and it is in neither the card nor the gate ledger. The same **Peer Dependencies:** block ends with `react-router-dom` >= 6.0.0, while packages/layout/package.json declares "react-router-dom": "^6.0.0 || ^7.0.0". Identical over-promise shape (the README admits v8, the manifest rejects it), identical fix. PR #3711's ledger has one entry for packages/layout/README.md covering the react claim only, so the react-dom and react-router-dom lines are currently unrecorded on both sides. Fold all three into this card's scope and add the matching ledger rows.

Ruling on the A/B choice the card deliberately left open — B, pin them down. Triage decides this rather than escalating, because it is a technical judgement about an internal docs surface, not a product or public-contract call.

The #3645 / PR #3688 rule is "a version number in prose is a drift guarantee", and its rationale is that nothing checks prose. That rationale does not reach this family: every one of these 11 restatements has a same-package anchor in its own package.json, so an assertion of literal equality makes drift impossible rather than merely discouraged — which is why #3708's three sites are A-only (no anchor exists) and these are not. The cost argument also favours B: PR #3711 has already enumerated all 11 sites with a kind discriminator, so B upgrades an existing ledger from record to assertion rather than standing up a new maintained surface, and 9 of the 11 are already correct — deleting them would spend real reader information (the Installation sections lose their "what version do I install" answer) to buy a guarantee the anchor can give for free.

Fallback, recorded so the implementing session need not come back to ask: if measurement shows the 11 READMEs' formatting varies enough that literal-equality assertions are brittle or produce false reds, fall back to A for the divergent sites and record which ones and why in the PR body. Do not leave a site half-pinned.

Why blocked, and on the PR. scripts/__tests__/doc-version-claims.test.ts lands with PR #3711 (open, draft, branch claude/issue-3697-version-claim-gate); it is not on origin/main. Fixing the two claims first would strand the ledger and turn #3711's ratchet red. Sequencing matters more here than on the sibling cards, since B's whole delivery is an edit to that same file.

Boundary with #3690 confirmed, not taken on trust. packages/plugin-report/README.md states ^18.0.0 || ^19.0.0 while its manifest has ^18.0.0 alone — there the manifest is the wrong side, which is #3690's fix (already pm:queue + target:v17), and the README becomes correct for free. Opposite direction from this card's two, so no overlap and no duplicate.

No target:v17. objectui reaches the board via the console bundle; package READMEs ship to npm, not in the bundle, and the two wrong claims mislead a reader without breaking an install.

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

---

Generated by Claude Code

[yinlianghui]

认领(PM 派发,并入 #3708 的三单一 PR — 详见 #3708 认领评论;plugin-report 行不碰,归 #3690)。Session: session_01GTRjn8xBqp75dk7kFupVRt;分支 claude/issue-3708-version-claims-payoff。

---

Generated by Claude Code