settings 消费缝丢弃 ResolvedSettingValue.source —— 服务无法区分「管理员写过的值」和「schema 默认值」

[os-zhuang]

分诊来源:核对 #4968 时的诊断副产物(该单的根因分析见 #4968 的核对评论)。observation-class:除 storage 一处已有具体受害路径(在 #4968 里处理)外,其余消费者今天没有已证实的用户可见故障,故打 finding、不进 pm:queue,留给 PM 分诊定级。

事实

SettingsService.get() 解析出的 ResolvedSettingValue 带三个字段:value、source('env' | 'global' | 'tenant' | 'user' | 'default')、cascadeChain。source 是 spec 里的一等字段:

• packages/spec/src/system/settings-manifest.zod.ts:461 — source: z.enum(['env','global','tenant','user','default']).describe('Resolution source')
• packages/spec/src/system/settings-client.zod.ts:51 的注释明说它的用途:"tells the consumer which scope row was actually mutated; this allows finer-grained reaction"

但每一个消费缝都只取 .value,把 source 丢掉:

位置	代码
packages/services/service-settings/src/settings-service.ts:472	for (const [k, v] of Object.entries(payload.values)) raw[k] = v.value;(snapshotOf,即 createClient 快照的来源)
packages/services/service-storage/src/storage-service-plugin.ts:397	values[k] = v?.value;
packages/services/service-sms/src/sms-plugin.ts:157	values[k] = v?.value;

plugin-email(packages/plugins/plugin-email/src/email-plugin.ts:306)走 createClient,因此经由 snapshotOf 同样看不到 source。

为什么这是缺陷,而不只是一个没用到的字段

丢掉 source 之后,消费者无法回答一个它必须回答的问题:这个值是有人真的配过,还是根本没人配、它只是 manifest 的 schema 默认值?

两者在 .value 上完全不可区分(schema 默认值同样非空),于是「没人配过」被当成「配成了这个值」,一个从未被授权的默认值就能覆盖宿主在构造期显式给出的配置。storage 是已证实的受害路径:--fresh 传入的 uploads 根目录被 storage.local_root 的 schema 默认值顶掉(实测证据与完整链路在 #4968)。

同一形状的判据在 storage 里被写成了「值非空」:

const hasAny = Object.values(values).some((v) => v !== undefined && v !== null && v !== '');
if (!hasAny) return;

紧邻的注释写的却是 "No persisted values yet → keep the constructor-built adapter" —— 注释说 persisted,代码测 present。它真正想表达的判据是 source !== 'default',而这个信息在上面三行就被丢掉了。

建议方向(不在本单实施)

消费缝保留 source(或至少派生一个 authored: boolean),让 settings-bound 服务能按「被授权过的值」而不是「非空的值」做决策。这条语义是平台级的(storage / sms / email 吃同一套),值得先定清楚再落地 —— 见 #4968 里给维护者的两个选项与三轴分析。

[os-zhuang]

发现分诊轮判级(services 车道 PM,2026-08-05):持有(留 finding),锚定维护者 #4968 裁决的 Q2 条款 —— storage 受害路径由 #4968-B(生产者侧统一 env 通道)修复,「消费缝保留 source」的平台级语义待第二个实证受害路径出现再立 ADR/实施。sms/email 目前无已证实的用户可见故障。下轮分诊轮复核;#4968-B 落地后顺带复验 storage 侧是否仍需读 source。

---

Generated by Claude Code

[claude]

发现分诊轮(#4949 纪律):维持持有(留 finding),域维持 domain:services。上一轮留的「#4968-B 落地后顺带复验」本轮已执行,结果记录如下。

复验结果(origin/main @ 9e3709a)

• OS_STORAGE_ROOT 对任何非默认值不生效:CLI 与设置服务的 env 通道错位,schema 默认值覆盖宿主构造配置(原报「swap 假警告」归因已被 #4096 时间线推翻,警告本身是准确的) #4968 已 closed/completed ⇒ 复验触发;
• 三个消费缝一处未变,source 仍在同样的位置被丢掉:service-storage/src/storage-service-plugin.ts:397(values[k] = v?.value;)、service-sms/src/sms-plugin.ts:157(同形)、settings-service.ts 的 snapshotOf —— 正文的 :472 现为 :696(raw[k] = v.value,行号漂移,形状一致);
• storage 的判据也未变:hasAny 仍是「值非空」测试(:400-401),紧邻注释仍写 “No persisted values yet → keep the constructor-built adapter” ⇒ 注释说 persisted、代码测 present 这一处注释与代码的错位仍在。

⇒ 读数很明确:#4968 是在生产者侧(统一 env 通道)把 storage 那条受害路径修掉的,没有让消费缝开始读 source。所以本单的平台级语义(消费缝保留 source / 派生 authored)一条也没被顺带解决,原持有理由完整存续。

判级:持有 —— 重启条件(维持维护者 #4968 Q2 口径,并补一条可机械判定的)

1. 出现第二个实证受害路径(sms / email / 任一 settings-bound 服务上,「schema 默认值被当成有人配过的值」造成用户可见故障)⇒ 平台级语义有了第二个证据点,按 OS_STORAGE_ROOT 对任何非默认值不生效:CLI 与设置服务的 env 通道错位,schema 默认值覆盖宿主构造配置(原报「swap 假警告」归因已被 #4096 时间线推翻,警告本身是准确的) #4968 的两选项立 ADR 并晋级;
2. 或下一次有人动这三个缝中任意一个所在文件时,把 source 的保留作为同函数收尾一并做掉(那时它不需要单独立项,只需在那单里点名本条);
3. ⛔ 不要只修 storage 的 hasAny 判据 —— 单点把「非空」换成「非默认」会让三个缝的口径进一步分叉,而分叉正是本单要治的东西。

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

---

Generated by Claude Code

[claude]

Findings triage round (#4949 discipline): HOLD maintained (finding kept), domain stays domain:services. Stale-premise check @ origin/main 80f7dc6. Restart condition ② fired since the last grading and was not taken — recorded here so it is a fact on the issue rather than a missed window nobody can see.

Restart condition ② — fired, missed

The 08-06 18:01Z grading wrote: "or the next time anyone touches one of these three seam files, keep source as a same-function wrap-up in that PR."

• packages/services/service-sms/src/sms-plugin.ts was touched: 9c90ea0b (feat(sms): 短信全局/每租户日发送配额（成本总量闸） #2814 / PR feat(sms): 短信全局日发送配额 —— 成本总量闸 (#2814) #6042, 2026-08-06T19:59:31Z, SMS global daily send quota) — after the 18:01Z grading;
• the seam is unchanged by it: still values[k] = v?.value;, line drifted 157 → 197;
• the other two seams did not move at all (REST commit list for service-storage/src/storage-service-plugin.ts and service-settings/src/settings-service.ts since 2026-08-06T13:00Z is empty), and both read as they did last round: storage-service-plugin.ts:397 (values[k] = v?.value;) with hasAny still the value-is-non-empty test at :400-401, and settings-service.ts:696 (raw[k] = v.value inside snapshotOf).

Condition ② is opportunistic and does not expire — a missed window costs only the marginal cost of the next one, so this does not change the grade. But it is worth one line on the record: the condition has now demonstrably fired once without being noticed, which is the failure mode of any "someone will do it while they are in there" condition. The mechanism available to this seat is exactly this comment; the executing lane that next claims work in service-sms / service-storage / service-settings should be pointed at this issue at claim time.

Verdict: HOLD — restart conditions unchanged

1. A second demonstrated victim path (sms / email / any settings-bound service, where "the schema default was taken for a value someone configured" causes a user-visible fault) ⇒ the platform-level semantics have their second evidence point; open the ADR per OS_STORAGE_ROOT 对任何非默认值不生效:CLI 与设置服务的 env 通道错位,schema 默认值覆盖宿主构造配置(原报「swap 假警告」归因已被 #4096 时间线推翻,警告本身是准确的) #4968's two options and promote.
2. Or the next PR that touches any of the three seam files keeps source (or derives authored: boolean) as a same-function wrap-up — fired once already (feat(sms): 短信全局日发送配额 —— 成本总量闸 (#2814) #6042), still available.
3. ⛔ Still do not fix only storage's hasAny predicate — swapping "non-empty" for "non-default" at one seam widens the divergence between the three, and the divergence is the thing this issue exists to treat.

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

---

Generated by Claude Code