「环境类别」这一个概念在 spec 里有两个枚举:DiscoverySchema.environment(3 成员)与 EnvironmentTypeSchema(7 成员)

[os-zhuang]

发现于 #4828 的实施(界外发现,查重无命中故新开;未认领;observation-class)。

现象

packages/spec 里有两个枚举描述同一个概念:

声明	位置	成员
DiscoverySchema.environment	src/api/discovery.zod.ts	production、sandbox、development
EnvironmentTypeSchema	src/cloud/environment.zod.ts	production、sandbox、development、test、staging、preview、trial

后者的注释写着「canonical buckets per industry convention (Salesforce, Power Platform, ServiceNow all use this taxonomy)」,即它自认是这个分类法的正本。前者是后者的真子集,两者之间没有任何引用关系,也没有任何东西保证它们同步演进。

影响

#4828 因此必须引入一个有损映射:NODE_ENV=staging 和 test 都是 EnvironmentTypeSchema 里的一等成员,但在 discovery 面上必须被折叠进 3 个桶(staging → sandbox、test → development)。这个映射本身是维护者裁定认可的(discovery 只需回答「我在不在生产」这种粗粒度问题),但「同一个词在两个 schema 里含义不同」这件事本身是漂移。

具体的坑:一个读了 EnvironmentTypeSchema 的作者会以为 staging 是合法的 environment 取值,而 DiscoverySchema 会拒绝它(discovery.test.ts 里就有一条 should reject invalid environment 用的正是 'staging')。

可能的处置

1. 维持两个,但写清楚关系:在 DiscoverySchema.environment 的 .describe() 里点名 EnvironmentTypeSchema 是更细的分类法(两个 discovery 生产者都在线上返回 schema 未声明的顶层字段(scoping / features / endpoints),且 REST 形状永远无法通过 DiscoverySchema #4828 已经加了这句),并在 EnvironmentTypeSchema 那边回指;再加一条测试钉住「discovery 的 3 个成员是 EnvironmentType 的子集」,这样后者改名/删成员时前者会红。
2. 让 discovery 复用 EnvironmentTypeSchema:去掉有损映射,但这会放宽一个响应枚举 —— 对按 3 个值做 switch 的消费者是前向不兼容的。两个 discovery 生产者都在线上返回 schema 未声明的顶层字段(scoping / features / endpoints),且 REST 形状永远无法通过 DiscoverySchema #4828 的裁定明确要求生产者取值落在 3 成员枚举内,所以这条需要新的裁定才能走。

选 1 的话是小活;选 2 是契约变更。倾向 1 + 那条子集测试:成本极低,而且能把「两个枚举」从沉默的漂移变成有闸门看着的关系。

参考:#4828(引入了映射函数 resolveDiscoveryEnvironment 与映射表)。

[os-zhuang]

发现分诊(#4949 纪律):持有,保留 finding,补 domain:spec(两个枚举都在 packages/spec——src/api/discovery.zod.ts 与 src/cloud/environment.zod.ts)。

一行理由:方向 1(注释互指 + 「discovery 3 成员是 EnvironmentType 子集」pin 测试)是低成本收编且不动契约,方向 2 是放宽响应枚举的契约变更、正文已自述需新裁定——倾向认可方向 1,但其一半(describe 互指)已由在飞的 #4828 携带,现在动手必撞面。重启条件:#4828 落地后由 spec 车道按方向 1 晋级收编(届时只剩回指注释 + 子集 pin 测试)。相邻单互链:#5673(NODE_ENV 默认值分歧,决策箱)与本条同源不同轴,若维护者在 #5673 走「未知」成员方向,两单应一并考虑。

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

---

Generated by Claude Code

[os-zhuang]

发现分诊(#4949 纪律):重启条件已触发,晋级 —— 摘 finding 换 pm:queue,domain:spec 已在,交 spec 车道按方向 1 收编。

依据与余量:重启条件 = #4828 落地(2026-08-06 00:24Z closed)。方向 1 的前一半已随 #4828 到位 —— discovery.zod.ts:240 的 describe 已互指(「that is sys_environment / EnvironmentTypeSchema, a richer 7-member taxonomy」);余量只剩后一半:cloud/environment.zod.ts 零处回指 discovery(已核),且全 packages/spec/src/api 无「discovery 3 成员 ⊂ EnvironmentType」子集 pin 测试。范围就这两件,不动契约。相邻:#5673(NODE_ENV 默认值,决策箱)同源不同轴,维护者若在该单走「未知」成员方向,两单一并考虑的提示仍有效。

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

---

Generated by Claude Code

[qq9340100]

Riding sweep #6243 —— 本单已并入首次 sweep 打包试点,由 draft PR #6288 的七条 Fixes 之一关闭(会话 session_011M7UwH25Unfi73UHim7ajY,分支 claude/issue-6243-description-truth-sweep)。按方向 1 收编,即分诊记的那两件余量:

1. cloud/environment.zod.ts 的 JSDoc 补反向回指(点明 staging 在这边一等、在 discovery 侧被 DiscoveryEnvironmentSchema 拒,必须走 resolveDiscoveryEnvironment 折叠);正向引用已随 两个 discovery 生产者都在线上返回 schema 未声明的顶层字段(scoping / features / endpoints),且 REST 形状永远无法通过 DiscoverySchema #4828 到位,未再改动其 .describe()。
2. 新增子集 pin packages/spec/src/api/discovery-environment-subset.pin.test.ts:钉 discovery 3 成员 ⊂ EnvironmentType 7 成员,含反空断言、safeParse 行为断言(不只比字符串数组),以及一条负对照(多出的四个桶必须被 discovery 拒 —— 否则两个枚举被合并了也会假绿)。反向验证已做:把 EnvironmentTypeSchema 的 sandbox 改名,该 pin 如期变红并点名。

⛔ 不动契约:两个枚举的成员一个没动,方向 2 未触碰。

一条范围外发现已单开 #6287(⛔ 未夹带):preview / trial 是 EnvironmentTypeSchema 的一等成员却不在 NODE_ENV_TO_DISCOVERY_ENVIRONMENT 上,靠 ?? 'development' 兜底折叠 —— 子集 pin 钉的是「三个在七个里」,钉不到「七个各自折向哪里」,这是本次收编之后剩下的唯一一条隐式边。与 #5673(已 closed)不重复。

---

Generated by Claude Code