settings 的 `step` 是同族第五个声明但不执行的值约束键 —— 先要一个「它算不算值约束」的判断

[hotlong]

在实施 #5932(补 min/max/minLength/maxLength 的执行)时顺带发现,记录下来交 triage。不在 #5932 的完成范围内 —— #5932 的分诊评论按名点死了那四个键,step 是第五个。

事实

packages/spec/src/system/settings-manifest.zod.ts 的 SpecifierSchema 在同一段注释下声明了三个键:

/** `number` / `slider`: numeric bounds and step. */
min: z.number().optional(),
max: z.number().optional(),
step: z.number().optional(),

#5932 落地后,min / max 在写入路径(validatePatch)与 env 路径
(effectiveEnvOverride)都被执行了。同一行注释下的 step 仍然零读取点 ——
packages/services/service-settings/src/ 里没有任何消费者,superRefine 也不校验它
(不像 min/max 至少查了次序、minLength/maxLength 至少查了次序)。

生产侧目前只有一处声明:packages/services/service-settings/src/manifests/ai.manifest.ts:189
的 temperature(min: 0, max: 2, step: 0.1)。

为什么单独一条,而不是 #5932 的续集

因为它先需要一个产品判断,而不是一段实现。step 有两种读法,导向不同的结果:

• 它是值约束 —— 值必须落在 min + k * step 的网格上。那么 temperature: 0.15
  应当在写入时被拒(码表里 invalid_value 可用),step 就应当照 settings 写入路径只执行 required / options / pattern —— 声明的 min / max / minLength / maxLength 一条都不校验(auth.password_min_length 可被写成 1) #5932 同形补执行。
  代价:浮点网格判定需要容差策略(0.1 的整数倍在二进制浮点下不精确),这本身是个
  需要定的规格。
• 它是纯 UI affordance —— 只是 HTML input[type=number] 的 step 属性,告诉控件
  上下箭头一次走多远,从不表达「其他值非法」。那么它今天的行为就是正确的,不该补执行;
  该做的是把注释写清楚,免得下一个人按 ADR-0049「declared ≠ enforced」把它当洞来补。

我倾向第二种(HTML 语义就是这样,而且 temperature: 0.15 对 AI 服务显然是合法值),
但这是规格判断不是实现细节,所以按 #5932 分诊的同一条界线上报而不自行决定。

影响面

• 今天没有用户会撞到:唯一的声明点是 ai.temperature,step: 0.1 与 min: 0 max: 2
  并存,而越过网格的值(如 0.15)对下游是完全合法的温度。故按观察类记录
  (finding,不入 pm:queue),严重度请 triage 定。
• 若判定为「纯 UI affordance」,建议把 SpecifierSchema 的注释从
  "numeric bounds and step" 拆开,并在 step 上写明它不参与校验 —— 否则 settings 写入路径只执行 required / options / pattern —— 声明的 min / max / minLength / maxLength 一条都不校验(auth.password_min_length 可被写成 1) #5932 的
  同族记忆会让下一个 agent 再来补一次。

相关

• settings 写入路径只执行 required / options / pattern —— 声明的 min / max / minLength / maxLength 一条都不校验(auth.password_min_length 可被写成 1) #5932 —— 同族的 min/max/minLength/maxLength 执行(本条的发现上下文)。
• service-settings: select 型 specifier 的 options 在保存期完全不校验 —— 声明的枚举不被强制 #5131 —— options 表在写入路径上的执行。
• env 来源的 settings 值绕过 manifest 的 options 表校验 —— #5094 在写入 API 上堵住的洞，在 OS_* 覆盖这一侧原样敞开 #5204 —— env 侧与写入侧对齐。