`ServiceStatus` 在 ./api 与 ./system 各有一个不同声明,#4593 的别名补齐卡在这个名字上

[qq9340100]

发现于 #4593 的类型别名补齐(PR 见该 issue)。这条不是 #4593 剩下那 40 条的同类,它自成一类:这个名字根本不能补,先要有人决定改哪一边。

事实

@objectstack/spec 现在有两个语义不同的 ServiceStatus:

• packages/spec/src/api/discovery.zod.ts:18 — export const ServiceStatus = z.enum([...]),discovery 的健康状态枚举,并且在 :29 已经有 export type ServiceStatus,经 ./api 导出。
• packages/spec/src/system/core-services.zod.ts — ServiceStatusSchema,一个描述内核服务状态的 object,经 ./system 导出。它的参考页在 content/docs/references/system/core-services.mdx。

docs-import-surface.baseline.json 里 system/ServiceStatus — no type export 这一行,正是因为 system 这一侧只有 schema const、没有裸名别名。

为什么今天是哑的

check:dual-source-exports 按"两个入口点导出同名但不同声明"判定。system 侧没有 type 别名,所以两侧目前只有一侧有 ServiceStatus 这个类型名,门看不见。一旦按 #4593 的做法补上 export type ServiceStatus = z.input< typeof ServiceStatusSchema >,门当场判红:

❌ 1 NEW dual-source export name(s) — two entry points now export the same name for different declarations:
 • ServiceStatus — [./api (type)] ≠ [./system (type)]

实测如此(#4593 的分支上补了又撤)。dual-source-exports.baseline.json 的 entries 目前是空的,是条干净棘轮,不该为这条破例。

要决定的事

两个名字里有一个是错的,选哪个是改名决定,不是补齐动作:

• A: 改 ./api 的。它是 discovery 的健康枚举,DiscoveryServiceStatus / ServiceHealth 更准;但 ./api 侧那个名字已经发布,改名是破坏性的。
• B: 改 ./system 的。KernelServiceStatus 与同文件的 KernelServiceMapSchema 更一致;system 侧还没有该名的类型导出,改名的成本只落在 schema const 与它的参考页名字上,明显更小。
• C: 判定两者其实是一个概念,合并成一个声明、另一个入口点 re-export(gate 明确说 re-export 不算 dual-source)。读下来不像:一个是 z.enum 的健康值,一个是带 features 数组的 object。

倾向 B,理由是破坏面最小且命名更准;但这是公开导出面的命名决定,按仓规不猜。

定下来之后,system/ServiceStatus 那条基线行才能跟着 #4593 的方式删掉。

影响

今天没有用户可见故障 —— 两个名字目前不会在同一个 import 里相遇。这是 #4593 完成范围里的一个卡口,不是一个在线上的 bug。

[os-zhuang]

Triage: needs-user-decision + domain:spec + target:v17.

• Why decision box: a published-export naming choice (A: rename the ./api enum — breaking; B: rename the ./system schema const — smallest blast; C: merge) on the public contract surface. The card's lean (B) is well-argued but this is exactly the "public export naming" class the repo does not guess on.
• Landing anchor (re-verified on origin/main @ 04476e7): both declarations live — packages/spec/src/api/discovery.zod.ts:22 (export const ServiceStatus = z.enum) and packages/spec/src/system/core-services.zod.ts:229 (ServiceStatusSchema object). The dual-source gate's clean ratchet (empty baseline) confirms the card's mechanism.
• target:v17 by propagation: this card is a hard prerequisite of one name in 150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例 #4593, which is on the v17 board — a release-blocking card's contract-first prerequisite is itself release-blocking. Maintainer may strike both together if 150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例 #4593 is re-scoped.
• Dedup: filed from 150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例 #4593's own implementation; no other open card on this name.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling (2026-08-08): Option B — rename the ./system side to KernelServiceStatus.

Scope: rename the schema const (matching the sibling KernelServiceMapSchema naming), update the reference pages, add the type alias per the #4593 standing rule, delete the baseline row (system/ServiceStatus — no type export), run the gen chain. The ./api discovery health enum keeps its published ServiceStatus name — no breaking rename. Option C stays rejected: the two are different concepts (a health enum vs a features-bearing object); merging would be false unification.

Rationale (three-axis review):

• Business: B is the smallest blast radius — the system side has no type export yet, so the name has not petrified; this unblocks the last 150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例 #4593-family baseline row.
• Long-term: the published ./api name stays stable, avoiding a major-cost rename for marginal naming gain.
• AI-error containment: two different concepts sharing one name in one package is a classic AI-consumer confusion trap; B disambiguates at the cheapest possible point.

Label note: target:v17 removed together with this ruling — it was inherited as "hard prerequisite of the v17 board card #4593", and #4593 closed and exited the board this morning (Option B there), so the propagation basis is gone; the rename itself blocks no release criterion. Applied under the maintainer's label authorization from earlier today.

State: needs-user-decision removed; pm:queue restored — spec lane.

Maintainer directive (verbatim, covering this batch of 6 inbox cards): 「接受你的建议」. Recorded by PM session session_01JaVVMrSxt7Tgi1uwEuDtH7.

---

Generated by Claude Code

[os-zhuang]

CLAIM — spec-lane PM seat (#6017), session session_01PiRUoQkTSBBmpyXBY3cVn2. Branch: claude/issue-6604-kernel-service-status. Dispatching a dev agent now, executing the maintainer's 2026-08-08 Option-B ruling above verbatim.

Scope from the ruling, unchanged: rename the ./system side to KernelServiceStatus — schema const ServiceStatusSchema → KernelServiceStatusSchema (matching sibling KernelServiceMapSchema naming), add the type alias per the #4593 standing rule, update the reference page(s), delete the system/ServiceStatus — no type export row from docs-import-surface.baseline.json (shrink-only ratchet), run the gen chain. The ./api discovery health enum keeps its published ServiceStatus name untouched, and the dual-source-exports baseline stays empty.

Export-surface note for the dev: this is an export remove+add on the ./system entry point ⇒ the dual-snapshot rule applies in full (api-surface/ + export-origins/, regenerated only after a real spec build). Any in-repo consumers of the old const name are in-scope to re-point; if a gate demands something the ruling didn't anticipate (e.g. a deprecation alias or a changeset class conflict), STOP and report rather than improvise.

---

Generated by Claude Code