finding: `preview` / `trial` 是 EnvironmentType 的一等成员,但 NODE_ENV_TO_DISCOVERY_ENVIRONMENT 没有条目 —— 靠 `?? 'development'` 兜底,折叠方向没被声明

[qq9340100]

范围外发现,记录于 #6243 sweep 的 #5676 一项(为两个环境枚举补双向交叉引用 + 子集 pin)实施过程。不夹带修复 —— #5676 的既定边界是「docs 交叉引用 + 子集 pin,⛔ 明确不改契约」,而这条要动的是映射表本身,属另一处判断。

事实(origin/main @ 2598216 实读)

packages/spec/src/api/discovery.zod.ts:320-328:

const NODE_ENV_TO_DISCOVERY_ENVIRONMENT: Readonly<Record<string, DiscoveryEnvironment>> = {
  production: 'production',
  prod: 'production',
  sandbox: 'sandbox',
  staging: 'sandbox',
  development: 'development',
  dev: 'development',
  test: 'development',
};

EnvironmentTypeSchema(cloud/environment.zod.ts)的七个成员里,preview 与 trial 在这张表上没有条目。resolveDiscoveryEnvironment 的末行是

return NODE_ENV_TO_DISCOVERY_ENVIRONMENT[raw.trim().toLowerCase()] ?? 'development';

所以这两个值折叠到 development —— 但是走兜底,不是走一条被写下来的决定。表上其余五个 EnvironmentType 成员(production / sandbox / development / test / staging)都有显式条目。

危害程度:低,故只登记不排期

preview 与 trial 都是非生产环境,development 也是,所以 discovery 面要回答的那个粗粒度问题(「我是不是在跟生产说话」)今天答得是对的 —— 这不是 #5673 点名的那个危险方向(把生产错报成非生产)。真正的问题是形式上的:

1. 同一张表里两种机制。 五个成员的折叠是声明,两个成员的折叠是兜底的副作用。读表的人(两个 discovery 生产者都在线上返回 schema 未声明的顶层字段(scoping / features / endpoints),且 REST 形状永远无法通过 DiscoverySchema #4828 的注释明说这张表就是给后来者读的)会以为表是全的。
2. 下一次给 EnvironmentTypeSchema 加桶时没有提示。 加一个成员不会让任何门变红,它会静静落进 development —— 而如果那个新桶是生产侧的(比如某种 production_replica),这就是 NODE_ENV 未设置时 /discovery 广播 environment=development,而 os start 默认 NODE_ENV=production、CLI doctor 也按 production 解析 #5673 的危险方向了。兜底的存在正是让这一类新增不响。

与既有单的关系(已逐一核过,均非重复)

• NODE_ENV 未设置时 /discovery 广播 environment=development,而 os start 默认 NODE_ENV=production、CLI doctor 也按 production 解析 #5673(已 closed):讲的是 NODE_ENV 未设置时三处默认不一致,不是成员覆盖度。
• 「环境类别」这一个概念在 spec 里有两个枚举:DiscoverySchema.environment(3 成员)与 EnvironmentTypeSchema(7 成员) #5676(在 sweep(spec-surface): 5-item description-surface truth sweep — one claim, one PR, per-item checklist review (#6085 #6081 #6137 #6065 #5676) #6243 sweep 中修复):确立了 discovery 3 成员 ⊂ EnvironmentType 7 成员的关系,并加了子集 pin。本条正是那次收编之后剩下的唯一一条隐式边 —— 子集 pin 钉的是「三个在七个里」,钉不到「七个各自折向哪里」。
• 两个 discovery 生产者都在线上返回 schema 未声明的顶层字段(scoping / features / endpoints),且 REST 形状永远无法通过 DiscoverySchema #4828:引入这张表与 resolveDiscoveryEnvironment 的来源单。

建议的修法(供分诊参考,未实施)

最小改动是给 preview / trial 补两条显式条目(值仍是 development,行为零变化),再加一条测试断言每个 EnvironmentTypeSchema 成员在表上都有条目 —— 这样折叠方向从兜底变成声明,而下一个新桶会在测试里被问一次「它折向哪」。⛔ 不建议删掉 ?? 'development' 兜底:它服务的是任意 operator 提供的字符串(不只是 EnvironmentType 成员),那个职责是真的。

未加标签、未认领,交发现分诊轮定级。