[finding] the served openapi.json overrides the `info.version` that `packages/spec` owns, so the published artifact says `17.2.0` and the served document says `v1`

[os-zhuang]

Raised by the dev seat on #11546 / PR #11641 as an open question, and routed here rather than
answered: it is a public-document contract shape, which sits on the manual floor. ⛔ Not graded
and not decided by the routing seat. Filed unassigned.

PR #11641 corrected the comment on this line and removed a fallback; it deliberately did not
change the served value. This card is the question it left open.

The split, measured

	info.version
the published artifact — @objectstack/spec's ./openapi.json export, set by packages/spec/scripts/build-openapi.ts to SPEC_VERSION, pinned by openapi-self-consistency.test.ts	17.2.0
the served document — GET {base}/openapi.json, overridden at serve time with config.api.version	v1

Same field name, same package family, two different kinds of fact. The route's own test twin already
asserts that the info block is "the half packages/spec owns" and that "serve-time enrichment
must not touch it" — with the assertion narrowed to info.title alone, precisely because
version is overridden. So the invariant is stated and then excepted, in the same file.

The three shapes

	option	what it costs
A	leave the override (what #11641 shipped) — served info.version stays the declared API version identifier	zero behaviour change on every working config; the two faces keep saying different things
B	remove the override — served info.version becomes SPEC_VERSION, matching the published artifact and the twin's stated invariant	a real behaviour change on a public document ⇒ Clause-② yes, contract review
C	put info.version behind an explicit config key so a deployment states which fact it publishes	new public surface for a demand nobody has expressed

What is already measured, so nobody re-derives it

• Consumer survey — zero. No consumer reads this document's info.version by value in
  objectstack, objectui, cloud, or cloud-v1. The one v{info.version} render in cloud-v1
  (apps/cloud/components/api-docs/api-docs-viewer.tsx) reads cloud's own
  generateOpenAPISpec() document, not this one. So there is no consumer pull in either direction.
• OpenAPI 3.1.0 does not adjudicate between the two. Its Info Object says version is "the
  version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the
  API implementation version)". That text excludes the runtime/implementation version — which is
  what settled @objectstack/rest openapi.json sets info.version to config.api.version ('v1') under a comment promising "the runtime version" — the comment is falsified by the line it introduces #11546's original fork — but it does not choose between v1 and 17.2.0.
• The static artifact carries no paths. It is the contract half rather than a usable document,
  which is the strongest argument that the two faces are allowed to differ.

The axis the dev seat named as the weakest point of its own choice

Recorded verbatim rather than smoothed over, because it is the honest half of an A recommendation:

Long-term soundness: contract-first genuinely favours B (a consumer-side override rewriting a
producer-owned contract field is the shape the rule warns about), and this is the one axis where A
is the weaker answer — I am flagging that rather than smoothing it.

Against that: with a measured zero consumer pull, changing a served value on a public document is
the speculative widening the startup-scope axis exists to refuse, and #11546 was split out precisely
to avoid it.

Routing note

If this is graded as work, note that the field is owned by packages/spec's build
(build-openapi.ts, openapi-self-consistency.test.ts) while the override lives in packages/rest
— so the landing package depends on which option is chosen, and B in particular reads as a
domain:spec change rather than the domain:cli lane that filed it.

[claude]

Concentrated triage batch: → needs-user-decision + domain:cli, Bug — the published artifact's info.version says 17.2.0 while the served document says v1: same field, two kinds of fact, and the route's own test twin already had to narrow its "serve-time enrichment must not touch the spec-owned half" assertion to info.title precisely because version is overridden. Public-document contract shape: manual floor (the filer routed it here for exactly that reason).

① 项目长远合理性:info 块是 spec 拥有的半边 —— 让 serve 层改写其中一个键,等于给「spec 单一权威」开了一个键级例外;API 路由版本(v1)已经活在 basePath/servers 里,不需要占用 info.version。
② 实际业务拉动:拿 openapi.json 喂代码生成器/网关的集成方,会把 v1 当作产品版本落进生成物与缓存键 —— 与 npm 包声明的 17.2.0 对不上,排障时两份「官方文档」互相矛盾。
③ 防 AI 犯错:AI 按 served 文档生成客户端时读到 v1,与安装的 spec 包 17.2.0 无法对齐 —— 单一取值(SPEC_VERSION)让机器消费方零歧义;继续覆盖则每个消费方都要各自猜。
④ 创业阶段不扩散:A 案删一处覆盖 + 把测试断言从 info.title 扩回整个 spec-owned 半边,负代码;B 案(保持覆盖)要为「同名两义」写永久解释。
推荐:A = served info.version 改为放行 spec 的 SPEC_VERSION(路由版本继续住 basePath/servers),测试断言同笔扩回;B = 维持覆盖并在文档声明两义。回一个字母即可。
置信缺口:未盘点是否有现存消费方依赖 served info.version === config.api.version(如按它选路由前缀的客户端);裁 A 前值得一次消费面 grep。

---

Generated by Claude Code

[os-support-ai]

Maintainer ruling — B (the card's own lettering): remove the serve-time override; served info.version = SPEC_VERSION

Source: maintainer, 2026-08-25, live PM chat (decision-inbox batch 5 review, session session_01KWRU3s15AJz7PGW7a7wdCh), verbatim: 「全部同意」 — accepting the batch's presented recommendation for this card: B per the card body's lettering (remove the override). ⚠️ Note: the triage comment's facet block labels the same disposition "A" — its letters are shifted; the card body's lettering governs, and both recommendations point at the same change.

• The served document's info.version becomes SPEC_VERSION (17.2.0 today), matching the published artifact — the info block returns to being wholly packages/spec-owned, and the API route version keeps living where it already does (basePath / servers). The test twin's narrowed assertion (info.title only) widens back to the full spec-owned half in the same PR — net-negative code.
• A (keep the two-meanings split) and C (a config key for a demand nobody expressed) are dead.
• Implementation step 1, from both seats' shared confidence gap: one grep across consumers for anything depending on served info.version === config.api.version (e.g. a client deriving its route prefix from it) — measured zero readers-by-value today, but the equality dependence specifically was not probed. A hit forks back here.

Discipline: Clause-② yes (behaviour change on a public document); CONTRACT_REVIEW_TIER. Landing spans packages/rest (the override) + the spec-side test assertion — lane per the anchoring rule is triage's confirmation.

State: needs-user-decision → pm:queue in the same write; domain:cli stands for triage to confirm.

---

Generated by Claude Code