@sema-agent/settings-schema 9.0.0 → 10.1.0

package/CHANGELOG.md

@@ -6,6 +6,107 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 10.1.0 — 2026-10-10 — 被丢条目带机读原因 `reasonCode`(minor,additive:新导出 + 可选新键,零删零改名)
+
+> 本节一件,additive(新导出 + 新字段),零删零改名。判档口径见下方「发版纪律」:新键 / 新导出 = minor。
+
+### S-1295 · 被丢条目带**机读原因**(`reasonCode`,闭集,additive)
+
+`DroppedEntry`(`salvageEntries` 的逐条记账行)与 `EffectiveReadWarning` 的 `entry-dropped` 臂各加可选键 `reasonCode?: DroppedEntryReasonCode`
+(本包铸的每一条都带 —— 铸点返回型是必填窄型,漏带词编译红;公开型上可选只为让手工构造这两个公开型的消费方不因本版编译红 —— 新键按发版纪律是可选键)。
+新导出 `DROPPED_ENTRY_REASON_CODES`(闭集常量)与 `DroppedEntryReasonCode`(型)。`error` 句照旧,不属本件。
+
+**词与丢弃点一一对应,没有 other 兜底**(`DroppedEntry` 只有一个铸点,它的判据 `judgeEntry` 按「谁判、判成什么样」分三种丢法,读实现所得):
+
+| 词 | 丢弃点 |
+|---|---|
+| `entry-schema-invalid` | 条目(数组元素 / Record 的值)没过它自己的条目 schema |
+| `entry-key-invalid` | Record 的**键**没过键 schema(键先判:键坏的条目不再算值) |
+| `entry-unreadable` | 判的过程抛了(病态访问器 / Proxy 陷阱);文案可能带秘密,`error` 只留一句中性话,词本身是闭集字面 |
+
+投影(`projectWarning`)把 `reasonCode` 带进去(缺席不铸键),一致性门比它;historical 模式的归一器与 `identity` 一同两侧剥掉(旧版铸不出)。
+
+- **谁需要** = server `GET /v1/models` 的丢弃条目自报(S-1295):wire 上只许闭集词,不许 zod 句子;词随告警过境,server 不手抄。之后 client-core / cli 读出。
+- **谁受伤** = 无。两处都是可选键:10.0.0 形的 `DroppedEntry` / `EntrySalvageResult` / `entry-dropped` 告警字面量照常编译(`test/dropped-entry-reason-code-s1295.test.ts` 的编译格咬着,
+  server 测试里手写的 `entry-dropped` 字面量同属此形);`DroppedEntry` 在 server / web-admin / sdk / client-core / cli / core 的 `src` 与 `test` 里零引用(逐仓 grep 核过)。
+  自己**重铸** `entry-dropped` 告警再交给一致性 kit 的读腿会在告警面报 `missing` / `extra`。
+- **谁补偿** = 一致性语料已再加冕(`npm run conformance:bless`,16 条 case 的 40 处告警投影(跨腿计)多出 `reasonCode`,零删、零改其它字段,`baseline.json` 零变化),消费方跑 release 门前随包拿到新语料;
+  消费方**自己入库**的语料(例:web-admin `wa05-*`)提货时要按新读数重新加冕。
+- **边界(如实登记)**:① 本表只管 `DroppedEntry`;读路径上另一条按名剔条目的臂(`hosts-grandfathered`,主机名超长)是它自己的告警臂,不带词;② 词按**丢弃点**分,
+  不按 schema 里「哪个字段为什么没过」细分(那是 `error` 句的事,句子不是契约);③ `entry-unreadable` 的病态访问器 JSON 语料表达不出,由
+  `test/dropped-entry-reason-code-s1295.test.ts` 看着(语料里 `entry-key-invalid` / `entry-schema-invalid` 由 `conformance/cases` 的金样与变异靶压着)。
+- **红先**:`test/dropped-entry-reason-code-s1295.test.ts` 对 10.0.0 源 **16 红 / 0 绿**(`reasonCode` 字段不存在、`DROPPED_ENTRY_REASON_CODES` 未导出),改源后 16 / 16;
+  逐点变异自证(8 处变异全杀)。codex 一审 [medium] 后补两格(旧形字面量编译格 + 本包铸的行恒带词):对「公开型必填」的中间稿 `tsc` 红(TS2741),改可选后绿。
+
+## 10.0.0 — 2026-10-09 — 私钥 PEM 头认串中任意位置(BREAKING:写入校验认串中任意位置的私钥 PEM 头;读侧同套 schema ⇒ 存量私钥串的条目被丢 / 域 throw)
+
+> **判档 = major**(README「发版纪律」:校验收紧、让同一份配置读写出不同结果 ⇒ major)。破坏的是**持久数据面**,不是类型面:导出面登记表零 diff(没有新增 / 删除 / 改形的导出),
+> 但读侧与写侧共用同一套 schema,存量配置里已经带着私钥串的部署,升级后读侧丢条目 / 整域 throw(下面「谁受伤」)。硬 breaking:无别名、无开关、无兼容读。
+
+### 一、病
+
+校验侧探测器 `containsSecretToken`(经 `scanForSecret`)读私钥 PEM 头只认**串首**:头里带空格,按令牌切开的那一遍永远隔不出它;头在串首时靠 `SECRET_LITERAL_RE` 的行首锚分支。
+`"x -----BEGIN PRIVATE KEY-----"` / `"key: -----BEGIN RSA PRIVATE KEY-----"` / `"…\n-----BEGIN OPENSSH PRIVATE KEY-----"` 因此都答 `false` —— 凡走这只探测器的自由文本写口,都能把整把私钥写进配置、
+进域行 / 变更历史 / 发布快照 / `/effective`。展示侧 `redactSecrets` 读的是同一只 `PRIVATE_KEY_PEM_HEADER`,却早已在串中任意位置、任一归一化形上判阳 —— **写与显两只判官对「头在串中」这一格答案不一致**。
+
+### 二、改(一处)
+
+`scanForSecret` 加一条:私钥 PEM 头(`PRIVATE_KEY_PEM_HEADER`,`-----BEGIN[A-Z0-9 ]*PRIVATE KEY`,大小写不敏感,既有全部变体 —— 裸 `PRIVATE KEY` / `RSA` / `EC` / `DSA` / `OPENSSH` / `ENCRYPTED` / `PGP …`)在串中**任意位置**命中即判阳。
+`containsSecretToken` 对原文与前三层百分号解码都跑 `scanForSecret`,所以编码过的头(`x%20-----BEGIN%20PRIVATE%20KEY`,三层之内)同样命中。**同一只正则**:展示侧在读的就是它,包内没有第二份(`src/` 里非注释行出现私钥头字样的只有那一处定义,有测试钉着)。
+公钥 / 证书头照旧不命中;其余令牌形(`sk-` / `ghp_` / JWT / Bearer / AKIA / AIza …)一字不动。`SECRET_LITERAL_RE` 的源串逐字不变(它是导出的单令牌字面形,下游据它的源串生成表)。
+`redactSecrets` 行为不变(同三形读数仍是整串 `[redacted-secret]`);它头注里「`containsSecretToken` 刻意不在这里放宽」那一句随之改真,`containsSecretToken` / `PRIVATE_KEY_PEM_HEADER` 头注里「只认串首」的说法同改。
+
+### 三、一处改全部受益的写口(逐个核过,都在测试里灌同一张表)
+
+经 `containsSecretToken` 的写口(源:`src/types.ts`、`src/remote-exec.ts`):
+- `ModelEntry.extraBody` / `compat` / `headers` —— 经 `vetFreeFormJson`(`extraBodyUnsafe` 描述符走查读每个字符串值与每个键;序列化克隆再扫一遍);
+- URL 面 `NON_SECRET_URL`(路径 / 查询 / 片段,`urlQueryFragmentHasSecret`):`ModelEntry.baseUrl`、mcp http `url`、worker `coords.gitApiBaseUrl`、会话镜像引擎 URL、`remoteExec` 的 `apiUrl` / `s3Snapshot.endpoint`、中心凭证 `issuer`;
+- mcp stdio `command` / `args[]`;
+- 插件源 `PLUGIN_ORIGIN`;
+- `remoteExec` ssh 的 `host` / `username`;
+- `WorkerSpec.env` 值;`runtime.execution.coords` 值(含远端 docker 守护进程的 `DOCKER_HOST`)与 `runtime.store.db` 的 `host` / `user` / `database`(车道 / SQL 坐标);
+- 授权覆盖值 `EntitlementOverride.value`(串,或 JSON 序列化后的串)。
+
+不受影响:HTTP 头名(字符集本就不收空格,私钥头不可能写进去);`ENV_NAME` 字段(字符集与 AKIA 形判据,不走这只探测器)。
+
+### 四、三问
+
+- **谁需要**:把凭据误写进自由文本键的部署 —— 例如把整把私钥贴进 `extraBody` 的某个值、mcp 参数、worker `env` 值,或带前缀(`key: …`)/ 换行后贴;这些以前都被放行并落进持久层。
+- **谁受伤**:新写入不会有人受伤(只收紧)。**存量里已经带着这种串的配置**,读写都会变:下一次写回被拒;读侧同一只判官也拒 —— 可降级域(`models` / `mcp` / `plugins` 等)该条按坏条目逐条丢并报 `entry-dropped`(同域其余条目存活),
+  `workers` / `entitlement` 等 gate 域沿用既有 fail-closed(整域读拒,拒句点名字段、不带值)。这是读侧的真实后果,不只是「写回被拒」—— 也是本版判 major 的原因。
+- **补偿**:拒句是固定句、不回显值,zod issue 的 `path` 指到字段,运维据此找到并删掉那个值;把私钥挪到 `secretRefs` / `secretEnv`(env-NAME)并**轮换这把密钥**(它已经进过配置)。展示侧本来就把这类串整串扣成 `[redacted-secret]`,所以日志 / 告警里没有泄露面;泄露面是持久层里那份原文。没有开关可以关掉这条拒 —— 刻意不留旋钮(私钥进配置不是可调的偏好)。
+  **升级前先清存量**(本包没有现成的清单命令 —— CLI 只有 `migrate-workers`,所以是人工步骤):① 在要升级的配置源(本地 `config.d/*.json`、中心的域行 / 变更历史导出)里不分大小写搜 `-----BEGIN` 后接 `PRIVATE KEY`
+  (正则 `-----BEGIN[A-Z0-9 ]*PRIVATE KEY`,另搜百分号编码形 `PRIVATE%20KEY`);`.env` 本来就是放秘密值的地方,里面的值不经这只探测器,不在此列。② 或写几行脚本:用 `@sema-agent/settings-schema/types` 的 `containsSecretToken`
+  对每份 JSON 里的每个字符串值与键各跑一遍,命中的就是存量私钥串;要把命中打印出来,过 `redactSecrets`(它把命中的串读成 `[redacted-secret]`,清单里不会再抄一份私钥)。③ 命中的值挪进 `secretEnv` / `secretRefs` 所指的 env-NAME,轮换这把密钥,再升级。
+
+### 用户可见变化(谁受影响 / 怎么改 / 不改会怎样)
+
+1. **自由文本写口的提交方(管理面 / CLI / 手写 `config.d`)**:带私钥头的串 —— 不论头在串首、前缀文字之后、`key: ` 之后还是换行之后 —— 现在都被拒;公钥 / 证书照旧过。不改会怎样:提交被拒,按拒句修。
+2. **持有存量这类串的部署**:见「谁受伤」与「补偿」。升级前先按「补偿」里的人工步骤清单,把私钥挪进 `secretEnv` 并轮换;不清就升级,读侧会丢条目 / 整域 throw。
+3. **读侧消费方(server 读 `/effective`、`loadLocalConfig`)**:对干净配置零变化。
+4. **共用 `containsSecretToken` 做展示 / 门判的其它仓**:它们对带私钥头的串现在也判阳(更严,方向一致);未在这里逐仓核对其断言 —— 提货时跑自己的套件。
+5. **持有导出面快照的测试 / 脚本**:无变化(导出面零 diff)。
+
+### 红先 / 门
+
+- 先写钉、对着改前的树跑红,再实现:`test/private-key-anywhere-10.0.0.test.ts` —— 探测器本身(三形 × 全部既有头变体 × 百分号层 × 负控)、二十个写口位置各灌同一张表(中间形拒 / 串首形照旧拒 / 公钥与证书照旧放 / 不含 PEM 的长串照旧放)、
+  自由文本写口的拒句不回显值、展示侧同三形读数不变、读侧后果(可降级域逐条丢、gate 域整域读拒)、单源钉、2 MB 对抗串线性钉、一格 🚧 缺口特征钉。写钉时对改前的树 96 格里 33 红;终稿 103 格(后补写口与缺口钉),把 `scanForSecret` 那一行拿掉复跑 37 红 66 绿,实装后 103 绿。
+- 既有钉随之改真(都是借「探测器只认串首」这个缺口触发的格,按缺口登记规矩翻;实装后这两格先红,翻后绿):`test/disclosable-identity-6.3.0.test.ts` 的 R1 前提格(`containsSecretToken(encoded)` 由判阴翻判阳)与 R3 附的冻结 oracle
+  (由「与 6.2.0 逐格相同」改为「6.2.0 ∪ 私钥头任意位置」,头的正则在 oracle 里冻一份字面,不读 src 导出)。
+- 一致性语料的变异律随之红了两个靶,按「活着的变异 = 语料缺口」补语料而不是删靶:展示侧脱敏器的「归一化没走完 ⇒ 整串扣」与「私钥头判在原文的归一化形上」这两面墙,此前分别靠
+  c43 的五层编码私钥头与 c41 / c43 的编码私钥头压着 —— 探测器认任意位置之后,那几条被探测器那一遍先扣下,两面墙失去杀手。新增 `c69-deep-encoded-token-past-every-reading`(九层编码的 `sk-` 形令牌)与
+  `c70-rewritten-token-in-front-of-encoded-pem-header`(`sk-note:` 紧贴编码私钥头、私钥体在换行之后),加冕脚本只加冕这两条;既有金样(`expected.json`)一字未动,只有 c43 的 `meta.json` 里一句已不成立的现在时说明(「五层那条只有『没走完』这一位扣得住」)订正。语料版本戳随包版本。
+- 导出面登记表(`docs/API-SURFACE.md`)重生成:零 diff。
+
+### 未闭环(如实)
+
+- **写与显对私钥头的读法宽度仍不一致 —— 这是缺陷,不是立场**:`containsSecretToken`(写侧)只读原文 + 前三层宽容百分号解码;**四层及更深**的编码、`+` 代空格(`-----BEGIN+PRIVATE+KEY-----`,form-urlencoded 读法)的头,
+  写侧今天判阴(放行),展示侧整串扣。本版只把「头位置」这一维收到任意位置,没动读法宽度;同一个问题两只读法(`percentLayers` 与 `secretScanForms`)作答,收口方向是并成一只读法(写侧读展示侧那一组形),
+  那是另一件设计,不在这次改里临时加探测臂。`test/private-key-anywhere-10.0.0.test.ts` 有一格 🚧 特征钉登记它,翻转条件写在钉里。这条缺口对其它令牌形(`sk-` 等)同样存在、早已如此,并非本版引入。
+- **`SECRET_LITERAL_RE` 仍带串首锚的私钥头一支**:它是导出面,下游(例如按它的源串生成匹配表的展示层)据此判串首形;`scanForSecret` 里新加的任意位置判先于它,这一支在探测器内部已是冗余,但改它是导出正则的变更。
+  直接用 `SECRET_LITERAL_RE` 整串判定的消费方,串中的私钥头仍看不见 —— 它们应改用 `containsSecretToken`。
+- **存量数据没有迁移器**:升级不动持久层里已有的串;处置是运维删值 + 轮换密钥(见补偿)。本版不提供自动清洗(自动改写配置里的值不是契约层的事)。
+
 ## 9.0.0 — 2026-10-09 — 能力读数三态读器 · 世代账两键由串改数(BREAKING)
 
 > **判档 = major**(README「发版纪律」:导出删除 / 改名、类型 retype ⇒ major)。**硬 breaking:删改直接做,零别名,消费方 tsc 红即通知。** 两件:

package/README.md

@@ -48,6 +48,13 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 > a zod-3 host (today the config-center product) still dedups to one instance. Moving this package to zod 4 is a major
 > of its own (S-777); 6.2.0 does not touch the dependency or peer range.
 
+## 升级指引:9.0.0 → 10.0.0(BREAKING:写入校验认串中任意位置的私钥 PEM 头;读侧同套 schema ⇒ 存量私钥串的条目被丢 / 域 throw;导出面零变化)
+
+自由文本写口(`extraBody` / `compat` / `headers`、URL、mcp stdio 参数、插件源、ssh 登录、worker env、车道坐标、覆盖值)此前只在私钥 PEM 头位于**串首**时拒;`"x -----BEGIN PRIVATE KEY-----"` / `"key: -----BEGIN RSA PRIVATE KEY-----"` / 换行之后的头都放行,而展示侧 `redactSecrets` 早就认串中任意位置。10.0.0 起 `containsSecretToken` 在原文与前三层百分号解码上都认串中任意位置的头(与展示侧读同一只 `PRIVATE_KEY_PEM_HEADER`),头的**位置**写与显同判;公钥 / 证书头照旧不拒,其余令牌形不变。⚠️ 读法的**宽度**写侧仍窄于展示侧:四层及更深的百分号编码、`+` 代空格的头,写侧今天仍放行(展示侧整串扣),见 CHANGELOG 10.0.0「未闭环」。**代码动作:无**(导出面零变化)。**存量配置里若已有这种串 —— 这就是本版判 major 的原因**:下一次写回被拒(拒句固定、不回显值,`path` 指到字段);读侧同一只判官也拒 ——
+`models` / `mcp` / `plugins` 等可降级域该条按坏条目逐条丢并报 `entry-dropped`(同域其余条目存活),`workers` / `entitlement` 等 gate 域沿用既有的 fail-closed(整域读拒)。
+**升级前先清存量**(本包没有现成的清单命令,人工步骤):不分大小写搜配置源里的 `-----BEGIN[A-Z0-9 ]*PRIVATE KEY`(另搜 `PRIVATE%20KEY`),或用 `@sema-agent/settings-schema/types` 的 `containsSecretToken` 对每份 JSON 的字符串值与键各跑一遍(打印命中时过 `redactSecrets`,清单里不再抄一份私钥);
+命中的值挪进 `secretEnv` / `secretRefs`(env-NAME)并轮换这把密钥(它已经进过配置)。逐条见 CHANGELOG 10.0.0。
+
 ## 升级指引:8.3.1 → 9.0.0(BREAKING:两件,硬 breaking —— 删改直接做,零别名)
 
 **① 能力读数改三态读器**:`readCenterCapabilities(body)` 删,换 `readCapabilityReading(reply): CapabilityReading`(类型 `CapabilityReading` 同入)。输入改成心跳 **2xx 的整只答复体**(键查找进读器),
@@ -300,7 +307,16 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   dropped without re-reading the source document by coordinate (the document it holds may not be the one this
   read saw). `identity` is part of the warning projection, so the conformance gate compares it (corpus
   cases `c40` / `c41` pin the laws JSON can express; the historical normalizer strips it, since older versions cannot
-  mint it — `ConformanceNormalizer.warning?`). **3.0.0** re-casts every coordinate these warnings
+  mint it — `ConformanceNormalizer.warning?`). **S-1295** (additive) adds `reasonCode` — WHY the entry was
+  dropped, as a machine-readable CLOSED word (`DROPPED_ENTRY_REASON_CODES` / `DroppedEntryReasonCode`; also on
+  `DroppedEntry` from `salvageEntries`): `entry-schema-invalid` (the entry — array element or Record value — failed its
+  own entry schema), `entry-key-invalid` (a Record key failed the key schema), `entry-unreadable` (validation threw while
+  reading it — a hostile accessor / Proxy trap; its message is never surfaced). One word per drop point, no `other`
+  fallback; the `error` sentence is unchanged and stays free text, so a consumer that must put a reason on a wire
+  reads the word, not the sentence. Every `entry-dropped` this package mints carries it (the key is optional on the
+  warning type only so consumers that hand-build that union keep compiling); like `identity` it is part of the warning
+  projection, compared by the conformance gate and stripped by the historical normalizer. The set covers `DroppedEntry`
+  only — the host-name clamp (`hosts-grandfathered`) is its own warning arm and carries no word. **3.0.0** re-casts every coordinate these warnings
   carry (`entry-dropped.path`, `unknown-keys-*.keys`) from a dot-joined STRING to a structured
   `ConfigPath = readonly (string | number)[]` — a string segment is an object key (verbatim, `.` included),
   a number segment is an array index — because the string form was a LOSSY encoding: a key literally named

package/conformance/VERSION

@@ -1 +1 @@
-9.0.0
+10.0.0

package/conformance/cases/c01-entry-salvage-then-typo/expected.json

@@ -79,7 +79,8 @@
         "path": [
           "models",
           0
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",

package/conformance/cases/c02-hosts-clamp-stacked/expected.json

@@ -81,7 +81,8 @@
         "path": [
           "hosts",
           2
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c10-record-key-secret-redacted-twice/expected.json

@@ -80,7 +80,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       },
       {
         "domain": "models",
@@ -88,7 +89,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c23-mixed-validity-models/expected.json

@@ -91,7 +91,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c40-s712-identity-only-what-reads-out/expected.json

@@ -83,7 +83,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -96,7 +97,8 @@
         "path": [
           "models",
           2
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -107,7 +109,8 @@
         "path": [
           "models",
           3
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -118,7 +121,8 @@
         "path": [
           "models",
           4
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -129,7 +133,8 @@
         "path": [
           "models",
           5
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -140,7 +145,8 @@
         "path": [
           "models",
           6
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -148,7 +154,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c41-s792-encoded-pem-identity/expected.json

@@ -83,7 +83,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -94,7 +95,8 @@
         "path": [
           "models",
           2
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -105,7 +107,8 @@
         "path": [
           "models",
           3
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -117,7 +120,8 @@
         "path": [
           "models",
           4
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -129,7 +133,8 @@
         "path": [
           "models",
           5
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -140,7 +145,8 @@
         "path": [
           "models",
           6
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -148,7 +154,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c43-s792-form-and-deep-encoded-pem/expected.json

@@ -83,7 +83,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -95,7 +96,8 @@
         "path": [
           "models",
           2
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -103,7 +105,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       },
       {
         "domain": "models",
@@ -111,7 +114,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       },
       {
         "domain": "models",
@@ -119,7 +123,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c43-s792-form-and-deep-encoded-pem/meta.json

@@ -1,6 +1,6 @@
 {
   "contributor": "contract",
-  "claim": "6.3.0(codex gpt-6-astra r1 F1 部分修,S-792):归一化那一处的两件事压在语料上。① `+` 代空格:扁平无换行的 `-----BEGIN+PRIVATE+KEY-----<base64>-----END+PRIVATE+KEY-----` 全在身份白名单字符集内,6.2.0 起它过身份与 refusal 两谓词 ⇒ 被丢条目的 id 必须不带(`secretScanForms` 把 `+` 读作空格的形交 PEM 头判,身份否决随之);URLSearchParams 形(`+` 代空格 + `%0A`)作 roles 坏键 ⇒ 坐标段整段扣、error 不带私钥。② 解码界上 fail-closed:四层 / 五层百分号编码作 roles 坏键 ⇒ 三层走完仍能再解,整串扣(codex r2 起展示侧的边界读法对末层再解一层,四层那条因此也被 PEM 头判扣下;五层那条只有「没走完」这一位扣得住 —— 变异门的 `unresolved` 靶靠它)。正控:`o3-mini+high` 作 id 逐字带出(`+` 在真实 id 里照旧可披露)。",
+  "claim": "6.3.0(codex gpt-6-astra r1 F1 部分修,S-792):归一化那一处的两件事压在语料上。① `+` 代空格:扁平无换行的 `-----BEGIN+PRIVATE+KEY-----<base64>-----END+PRIVATE+KEY-----` 全在身份白名单字符集内,6.2.0 起它过身份与 refusal 两谓词 ⇒ 被丢条目的 id 必须不带(`secretScanForms` 把 `+` 读作空格的形交 PEM 头判,身份否决随之);URLSearchParams 形(`+` 代空格 + `%0A`)作 roles 坏键 ⇒ 坐标段整段扣、error 不带私钥。② 解码界上 fail-closed:四层 / 五层百分号编码作 roles 坏键 ⇒ 三层走完仍能再解,整串扣(codex r2 起展示侧的边界读法对末层再解一层,四层那条因此也被 PEM 头判扣下;五层那条只有「没走完」这一位扣得住 —— 变异门的 `unresolved` 靶靠它)。正控:`o3-mini+high` 作 id 逐字带出(`+` 在真实 id 里照旧可披露)。 【10.0.0 订正】探测器改认串中任意位置的私钥头之后,它对每个归一化形再读三层,五层那条也被探测器那一遍扣下,「没走完」这一位不再独自承重于本条;`unresolved` 靶的语料杀手改为 c69。",
   "firstRedOn": [],
   "secrets": [
     "MC4CAQAwBQYDK2VwBCIEIFAKEC43FLATPLUSIDBODY0000000000000000000000",
@@ -8,5 +8,5 @@
     "MC4CAQAwBQYDK2VwBCIEIFAKEC43DEEPENCODEDROLEKEYBODY00000000000000",
     "MC4CAQAwBQYDK2VwBCIEIFAKEC43FIVELAYERROLEKEYBODY0000000000000000"
   ],
-  "note": "车PE(2026-09-27)红先:加本条时 6.3.0 修前(A 已修、B 未修)读腿在三腿上报告警差 + 秘密扫描命中。变异门为 `secretScanForms` 的 `+` 读法与 `redactSecrets` 的 `unresolved` 一位各登记一靶,本条杀。firstRedOn 为空:historical 阶梯证据真跑于本条入库之前,那一栏只收 historical 真跑。 codex r2 收敛(车PE 同日):边界读法上线后四层那条不再单靠 `unresolved`,追加五层一条(`FAKEC43FIVELAYER…`)使该靶仍有语料杀。"
+  "note": "车PE(2026-09-27)红先:加本条时 6.3.0 修前(A 已修、B 未修)读腿在三腿上报告警差 + 秘密扫描命中。变异门为 `secretScanForms` 的 `+` 读法与 `redactSecrets` 的 `unresolved` 一位各登记一靶,本条杀。firstRedOn 为空:historical 阶梯证据真跑于本条入库之前,那一栏只收 historical 真跑。 codex r2 收敛(车PE 同日):边界读法上线后四层那条不再单靠 `unresolved`,追加五层一条(`FAKEC43FIVELAYER…`)使该靶仍有语料杀。 【10.0.0】`unresolved` 靶改由 c69 杀,本条对该靶不再红。"
 }

package/conformance/cases/c44-s792-utf8-escape-glued-token/expected.json

@@ -80,7 +80,8 @@
         "path": [
           "roles",
           "[redacted-secret]"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       },
       {
         "domain": "models",
@@ -88,7 +89,8 @@
         "path": [
           "roles",
           "path%2Fto%E4%B8%AD"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       },
       {
         "domain": "models",

package/conformance/cases/c45-s792-identity-bounds-and-decode-depth/expected.json

@@ -110,7 +110,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -121,7 +122,8 @@
         "path": [
           "models",
           2
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -132,7 +134,8 @@
         "path": [
           "models",
           3
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -144,7 +147,8 @@
         "path": [
           "models",
           4
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -167,7 +171,8 @@
         "path": [
           "servers",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c47-s811-roles-key-url-userinfo-characterization/expected.json

@@ -80,7 +80,8 @@
         "path": [
           "roles",
           "https://admin:hunter2@db.example.com/x"
-        ]
+        ],
+        "reasonCode": "entry-key-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c49-s935-model-headers-secret-entry-dropped/expected.json

@@ -80,7 +80,8 @@
         "path": [
           "models",
           0
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/c69-deep-encoded-token-past-every-reading/expected.json

@@ -0,0 +1,104 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "models": [
+          {
+            "api": "openai-completions",
+            "apiKeyEnv": "OPENAI_API_KEY",
+            "enabled": true,
+            "id": "keep-id",
+            "name": "keep",
+            "provider": "openai",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          }
+        ],
+        "roles": {
+          "summarize": {
+            "model": "keep"
+          }
+        },
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {
+        "bindings": []
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "runtime": {},
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [
+      {
+        "domain": "models",
+        "kind": "entry-dropped",
+        "path": [
+          "roles",
+          "[redacted-secret]"
+        ],
+        "reasonCode": "entry-key-invalid"
+      }
+    ],
+    "metadata": {
+      "version": 15,
+      "updatedAt": "2026-10-09T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:roles 里的坏键读腿丢(entry-dropped,坐标整段扣);严写 ⇒ 整次不受理。"
+  },
+  "wire": {
+    "derive": true
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 2824083313848700
+  }
+}

package/conformance/cases/c69-deep-encoded-token-past-every-reading/input.json

@@ -0,0 +1,26 @@
+{
+  "meta": {
+    "version": 15,
+    "updatedAt": "2026-10-09T00:00:00.000Z"
+  },
+  "domains": {
+    "models": {
+      "models": [
+        {
+          "name": "keep",
+          "provider": "openai",
+          "id": "keep-id",
+          "apiKeyEnv": "OPENAI_API_KEY"
+        }
+      ],
+      "roles": {
+        "summarize": {
+          "model": "keep"
+        },
+        "key=%252525252525252573k-live-FAKEC69NINELAYERROLEKEYTOKEN0000000000": {
+          "model": "keep"
+        }
+      }
+    }
+  }
+}

package/conformance/cases/c69-deep-encoded-token-past-every-reading/meta.json

@@ -0,0 +1,9 @@
+{
+  "contributor": "contract",
+  "claim": "10.0.0:展示侧脱敏器的「归一化没走完 ⇒ 整串扣」这一位压在语料上。`sk-` 形令牌的首字母 `s` 被九重百分号编码(`%2525…2573`)作 roles 坏键:探测器的三层解码、边界读法再解一层、探测器对每个形再读三层都够不着它 ⇒ 令牌不被任何定点遍认出,只有「还能再解」这一位把整段坐标扣成 `[redacted-secret]`。此前这一位靠 c43 的五层私钥头压着;10.0.0 起探测器认串中任意位置的私钥头,五层那条也被探测器那一遍扣下,这一位随之没了语料杀手 —— 本条补上。",
+  "firstRedOn": [],
+  "secrets": [
+    "k-live-FAKEC69NINELAYERROLEKEYTOKEN0000000000"
+  ],
+  "note": "变异门靶:`redactSecrets` 去 `scan.unresolved || ` —— 本条杀。不是红先复现:这一位的行为 9.0.0 与 10.0.0 相同(坐标整段扣),本条只是让它在语料里再有一个承重的杀手。firstRedOn 为空:不是 historical 阶梯证据。"
+}

package/conformance/cases/c70-rewritten-token-in-front-of-encoded-pem-header/expected.json

@@ -0,0 +1,104 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "models": [
+          {
+            "api": "openai-completions",
+            "apiKeyEnv": "OPENAI_API_KEY",
+            "enabled": true,
+            "id": "keep-id",
+            "name": "keep",
+            "provider": "openai",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          }
+        ],
+        "roles": {
+          "summarize": {
+            "model": "keep"
+          }
+        },
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {
+        "bindings": []
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "runtime": {},
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [
+      {
+        "domain": "models",
+        "kind": "entry-dropped",
+        "path": [
+          "roles",
+          "[redacted-secret]"
+        ],
+        "reasonCode": "entry-key-invalid"
+      }
+    ],
+    "metadata": {
+      "version": 15,
+      "updatedAt": "2026-10-09T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:roles 里的坏键读腿丢(entry-dropped,坐标整段扣);严写 ⇒ 整次不受理。"
+  },
+  "wire": {
+    "derive": true
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 1452540247706034
+  }
+}

package/conformance/cases/c70-rewritten-token-in-front-of-encoded-pem-header/input.json

@@ -0,0 +1,26 @@
+{
+  "meta": {
+    "version": 15,
+    "updatedAt": "2026-10-09T00:00:00.000Z"
+  },
+  "domains": {
+    "models": {
+      "models": [
+        {
+          "name": "keep",
+          "provider": "openai",
+          "id": "keep-id",
+          "apiKeyEnv": "OPENAI_API_KEY"
+        }
+      ],
+      "roles": {
+        "summarize": {
+          "model": "keep"
+        },
+        "sk-note:-----BEGIN%20PRIVATE%20KEY-----\nMC4CAQAwBQYDK2VwBCIEIFAKEC70REWRITTENHEADERBODY00000000000000\n-----END%20PRIVATE%20KEY-----": {
+          "model": "keep"
+        }
+      }
+    }
+  }
+}

package/conformance/cases/c70-rewritten-token-in-front-of-encoded-pem-header/meta.json

@@ -0,0 +1,9 @@
+{
+  "contributor": "contract",
+  "claim": "10.0.0:展示侧脱敏器「私钥头判在令牌替换之前、且判在归一化形上」这两件同时压在语料上。roles 坏键 = `sk-note:` 紧贴一个 `%20` 编码的私钥头,私钥体在真实换行之后(令牌字符集之外):定点遍先把 `sk-note:-----BEGIN%20PRIVATE%20KEY-----` 整个令牌换成 `[redacted-secret]`,头就没了,换行后的体与 END 行原样留着;只有对**原文的归一化形**(`%20` 解成空格)判私钥头,才会整串扣。此前这一位靠 c41 / c43 的编码私钥头压着,10.0.0 起探测器认串中任意位置的私钥头,那两条被探测器那一遍扣下,这一位随之没了语料杀手 —— 本条补上。",
+  "firstRedOn": [],
+  "secrets": [
+    "MC4CAQAwBQYDK2VwBCIEIFAKEC70REWRITTENHEADERBODY00000000000000"
+  ],
+  "note": "变异门靶:`redactSecrets` 把原文形上的私钥头判退回只测原文(`PRIVATE_KEY_PEM_HEADER.test(text)`)—— 本条杀。不是红先复现:坐标整段扣这一行为 9.0.0 与 10.0.0 相同。firstRedOn 为空:不是 historical 阶梯证据。"
+}

package/conformance/cases/cli01-model-name-nfc-vs-nfd/expected.json

@@ -76,7 +76,8 @@
         "path": [
           "models",
           0
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -84,7 +85,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/cli02-control-and-zero-width-chars/expected.json

@@ -89,7 +89,8 @@
         "path": [
           "models",
           0
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",
@@ -97,7 +98,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       }
     ],
     "metadata": {

package/conformance/cases/t04-secret-literal-never-in-warning-value/expected.json

@@ -80,7 +80,8 @@
         "path": [
           "models",
           1
-        ]
+        ],
+        "reasonCode": "entry-schema-invalid"
       },
       {
         "domain": "models",

package/dist/config-fns.d.ts

@@ -34,11 +34,14 @@ import { type DomainConfig, type DomainName, type EffectiveConfig, type Effectiv
  *  The PEM header is judged BEFORE any replacement: the token pass can rewrite the header itself away
  *  (`sk-note:-----BEGIN` is one token-charset run that starts with `sk-`, so it becomes `[redacted-secret]` and the
  *  key body after it would ride out untouched — codex verification round). A PEM header carries spaces, so the
- *  targeted passes can never isolate it, and the detector only sees it at the very start of a string. Every
- *  free-text warning face that goes through here (coordinates, error text) inherits the same guarantee; the entry
- *  identity face additionally has to be an identifier ({@link isDisclosableIdentity}). The validation-side detector
- *  `containsSecretToken` is deliberately NOT widened here: making it reject a mid-string PEM would tighten every field
- *  it validates (a major). */
+ *  targeted passes can never isolate it. Every free-text warning face that goes through here (coordinates, error text)
+ *  inherits the same guarantee; the entry identity face additionally has to be an identifier ({@link isDisclosableIdentity}).
+ *  Write and display read the private-key header at the same PLACE and with the same regex since 10.0.0: the validation-side
+ *  detector `containsSecretToken` reads {@link PRIVATE_KEY_PEM_HEADER} anywhere in a string too, on the raw text and its first three
+ *  percent layers. They do NOT yet read the same FORMS: this redactor reads more (deeper layers, the `+` and boundary readings of
+ *  `secretScanForms`), so a header spelled only in one of those forms is withheld on display but still passes write validation —
+ *  an open gap (a pin in the 10.0.0 test file registers it), not a contract. The redactor also keeps its own PEM check on the ORIGINAL
+ *  text's forms because the token pass above can rewrite the header away before `containsSecretToken` ever sees the result. */
 export declare function redactSecrets(text: string): string;
 /** Sanitize a ZodError IN PLACE so no surfaced error (message / `received` / nested `unionErrors`) echoes a
  *  pasted secret. RECURSES into `unionErrors` (a `z.union` failure nests a ZodError per member — e.g. RoleTarget
@@ -189,12 +192,31 @@ export interface DroppedEntryIdentity {
     id?: string;
     enabled?: boolean;
 }
+/**
+ * 一条条目为什么被丢 —— **机读原因**的闭集(S-1295)。词与**丢弃点**一一对应:`DroppedEntry` 只有一个铸点
+ * (`droppedEntry`),它的上游判据(`judgeEntry`)按「谁判、判成什么样」分三种丢法,每种一个词,没有 other 兜底:
+ *  - `entry-schema-invalid` —— 条目(数组元素 / Record 的值)没过它自己的条目 schema;
+ *  - `entry-key-invalid`    —— Record 的**键**没过键 schema(键先判:键坏的条目不再算值);
+ *  - `entry-unreadable`     —— 判的过程抛了(病态访问器 / Proxy 陷阱;文案可能带秘密,所以只留一句中性话,见 {@link judgeEntry})。
+ *
+ * 为什么是词而不是 `error` 句:句子随 zod 小版本改字、可经脱敏,拿它当判据就是拿实现当契约;wire 上也不许有自由文本。
+ * 这张表由 `test/dropped-entry-reason-code-s1295.test.ts` 的两格咬住:穷举 `switch`(给表加词而不补臂 ⇒ `tsc` 红,门 = `npm run typecheck`)与
+ * 满射格(每个词至少有一个真丢弃点触发它 = 没有死词;每个被丢条目的词都在表里 = 没有无词的丢弃点)。
+ * 边界(如实登记):本表只管 `salvageEntries` 铸的 {@link DroppedEntry};读路径上另一条按名剔条目的臂
+ * (`hosts-grandfathered`,主机名超长)走它自己的告警臂,不是 `DroppedEntry`,不在本表。
+ */
+export declare const DROPPED_ENTRY_REASON_CODES: readonly ["entry-schema-invalid", "entry-key-invalid", "entry-unreadable"];
+export type DroppedEntryReasonCode = (typeof DROPPED_ENTRY_REASON_CODES)[number];
 /** 一条被丢掉的条目:`path` = 段坐标({@link ConfigPath};`["models", 3]` / `["roles", "summarize"]`),
- *  `error` 已脱敏,`identity`(S-712)见 {@link DroppedEntryIdentity}(读不出 ⇒ 键缺席)。 */
+ *  `error` 已脱敏,`identity`(S-712)见 {@link DroppedEntryIdentity}(读不出 ⇒ 键缺席),
+ *  `reasonCode`(S-1295)= 为什么丢的**机读闭集词**,见 {@link DROPPED_ENTRY_REASON_CODES}。本包铸的每一行都带(铸点是唯一的,返回型是必填窄型
+ *  {@link MintedDroppedEntry},漏带词 = 编译红);公开型上是可选键,只因为这个接口是公开导出的,手工构造它的消费方(夹具、适配器)不该被一个
+ *  additive 的 minor 编译红 —— 发版纪律:新键是可选键。 */
 export interface DroppedEntry {
     path: ConfigPath;
     error: unknown;
     identity?: DroppedEntryIdentity;
+    reasonCode?: DroppedEntryReasonCode;
 }
 /** 可披露身份的**闭形**(6.3.0):字符集 `A-Z a-z 0-9 . _ : / @ + -`、长度 1–256(上限与 web-admin 读侧名长上限 256 对齐;`ModelEntry.name`
  *  本身不设上限,超 256 字的合法名按无名处置)。身份是**标识符**不是自由文本 ——
@@ -356,13 +378,17 @@ export type EffectiveReadWarning =
  *  O(域里的条目数),与被读文档同阶,不放大,故不设条数上限(有上限的是**单条**告警里的键列表)。
  *  2.0.0 起;只可能来自 {@link DOMAIN_READ_FALLBACK} 判 `"default"` 的域,gate 域坏形仍然 throw。
  *  **S-712**(additive):`identity` = 被丢条目原文里读得出的身份({@link DroppedEntryIdentity};
- *  读不出 ⇒ 键缺席),消费方据此知道「丢的是谁」而不必拿坐标回读原文档。 */
+ *  读不出 ⇒ 键缺席),消费方据此知道「丢的是谁」而不必拿坐标回读原文档。
+ *  **S-1295**(additive):`reasonCode` = 为什么丢的机读闭集词({@link DROPPED_ENTRY_REASON_CODES}),消费方据此知道「为什么丢」
+ *  而不必解析 `error` 句。本包铸的每一条都带;类型上是可选键只因为这个联合有手工构造它的消费方(测试夹具、别家实现的适配器)——
+ *  新键按发版纪律是可选键,不因此让他们编译红。 */
  | {
     domain: DomainName;
     kind: "entry-dropped";
     path: ConfigPath;
     error: unknown;
     identity?: DroppedEntryIdentity;
+    reasonCode?: DroppedEntryReasonCode;
 }
 /** `config.d/` 里存在、但本地读取集**永远不会读**的文件(名字不是域,或是域但不便携)。 */
  | {

package/dist/config-fns.js

@@ -38,11 +38,14 @@ import { DOMAIN_SCHEMAS, GOVERNANCE_MIRROR_KEYS, HOSTS_ARRAY_MAX, HOST_NAME_MAX,
  *  The PEM header is judged BEFORE any replacement: the token pass can rewrite the header itself away
  *  (`sk-note:-----BEGIN` is one token-charset run that starts with `sk-`, so it becomes `[redacted-secret]` and the
  *  key body after it would ride out untouched — codex verification round). A PEM header carries spaces, so the
- *  targeted passes can never isolate it, and the detector only sees it at the very start of a string. Every
- *  free-text warning face that goes through here (coordinates, error text) inherits the same guarantee; the entry
- *  identity face additionally has to be an identifier ({@link isDisclosableIdentity}). The validation-side detector
- *  `containsSecretToken` is deliberately NOT widened here: making it reject a mid-string PEM would tighten every field
- *  it validates (a major). */
+ *  targeted passes can never isolate it. Every free-text warning face that goes through here (coordinates, error text)
+ *  inherits the same guarantee; the entry identity face additionally has to be an identifier ({@link isDisclosableIdentity}).
+ *  Write and display read the private-key header at the same PLACE and with the same regex since 10.0.0: the validation-side
+ *  detector `containsSecretToken` reads {@link PRIVATE_KEY_PEM_HEADER} anywhere in a string too, on the raw text and its first three
+ *  percent layers. They do NOT yet read the same FORMS: this redactor reads more (deeper layers, the `+` and boundary readings of
+ *  `secretScanForms`), so a header spelled only in one of those forms is withheld on display but still passes write validation —
+ *  an open gap (a pin in the 10.0.0 test file registers it), not a contract. The redactor also keeps its own PEM check on the ORIGINAL
+ *  text's forms because the token pass above can rewrite the header away before `containsSecretToken` ever sees the result. */
 export function redactSecrets(text) {
     const targeted = text
         .replace(/\b(bearer|basic)(\s+)\S+/gi, "$1$2[redacted-secret]")
@@ -220,6 +223,20 @@ function outgoingPath(p) {
 function outgoingSegment(seg) {
     return seg.length > DISCLOSABLE_IDENTITY_MAX ? "[redacted-secret]" : redactSecrets(seg);
 }
+/**
+ * 一条条目为什么被丢 —— **机读原因**的闭集(S-1295)。词与**丢弃点**一一对应:`DroppedEntry` 只有一个铸点
+ * (`droppedEntry`),它的上游判据(`judgeEntry`)按「谁判、判成什么样」分三种丢法,每种一个词,没有 other 兜底:
+ *  - `entry-schema-invalid` —— 条目(数组元素 / Record 的值)没过它自己的条目 schema;
+ *  - `entry-key-invalid`    —— Record 的**键**没过键 schema(键先判:键坏的条目不再算值);
+ *  - `entry-unreadable`     —— 判的过程抛了(病态访问器 / Proxy 陷阱;文案可能带秘密,所以只留一句中性话,见 {@link judgeEntry})。
+ *
+ * 为什么是词而不是 `error` 句:句子随 zod 小版本改字、可经脱敏,拿它当判据就是拿实现当契约;wire 上也不许有自由文本。
+ * 这张表由 `test/dropped-entry-reason-code-s1295.test.ts` 的两格咬住:穷举 `switch`(给表加词而不补臂 ⇒ `tsc` 红,门 = `npm run typecheck`)与
+ * 满射格(每个词至少有一个真丢弃点触发它 = 没有死词;每个被丢条目的词都在表里 = 没有无词的丢弃点)。
+ * 边界(如实登记):本表只管 `salvageEntries` 铸的 {@link DroppedEntry};读路径上另一条按名剔条目的臂
+ * (`hosts-grandfathered`,主机名超长)走它自己的告警臂,不是 `DroppedEntry`,不在本表。
+ */
+export const DROPPED_ENTRY_REASON_CODES = ["entry-schema-invalid", "entry-key-invalid", "entry-unreadable"];
 /** 可披露身份与出门坐标段的**长度上界**(一只常量,两处用:{@link DISCLOSABLE_IDENTITY_RE} 的上限、{@link outgoingSegment}
  *  的「超长不扫描」界)。与 web-admin 读侧名长上限 256 对齐。 */
 const DISCLOSABLE_IDENTITY_MAX = 256;
@@ -287,24 +304,34 @@ function readEntryIdentity(entry) {
 /** 一条记账行 → 它的 `entry-dropped` 告警。域面({@link buildEffective})与 wire 面(skills manifest)共用
  *  这**一只** —— 告警形只在这里拼,新字段不会在一条腿上漏铸。 */
 function entryDroppedWarning(domain, d) {
-    return d.identity === undefined ? { domain, kind: "entry-dropped", path: d.path, error: d.error } : { domain, kind: "entry-dropped", path: d.path, error: d.error, identity: d.identity };
+    return {
+        domain,
+        kind: "entry-dropped",
+        path: d.path,
+        error: d.error,
+        ...(d.reasonCode === undefined ? {} : { reasonCode: d.reasonCode }),
+        ...(d.identity === undefined ? {} : { identity: d.identity }),
+    };
 }
-/** 一条被丢条目的记账行 —— `salvageEntries` 两种集合形(数组 / Record)共用的**唯一**铸点。 */
-function droppedEntry(path, error, entry) {
+/** 一条被丢条目的记账行 —— `salvageEntries` 两种集合形(数组 / Record)共用的**唯一**铸点。词随判决来({@link EntryVerdict}),
+ *  不在这里另行推断:判的那一刻才知道是哪种丢法。 */
+function droppedEntry(path, verdict, entry) {
     const identity = readEntryIdentity(entry);
-    return identity === undefined ? { path, error } : { path, error, identity };
+    const base = { path, error: verdict.error, reasonCode: verdict.reasonCode };
+    return identity === undefined ? base : { ...base, identity };
 }
 /** 一次「什么都没丢」的抢救的位移表(冻结的共享空表 —— {@link rebaseWarningPaths} 对它恒等)。 */
 const NO_ENTRIES_DROPPED = Object.freeze({});
-/** 一条条目的 parse —— 坏就返回它的(脱敏)错误。恶意 getter/Proxy 在遍历中抛错时**绝不**外泄其文案
- *  (可能带 secret,与 parseDomain 的 R13 同纪律),只留一句中性话。 */
-function judgeEntry(schema, value) {
+/** 一条条目的 parse —— 坏就返回它的判决(脱敏错误 + 闭集词)。`rejectedAs` = 调用点在集合里的位置赋予「schema 没过」的那个词
+ *  (条目 / Record 值 ⇒ `entry-schema-invalid`;Record 键 ⇒ `entry-key-invalid`);判的过程抛了则恒为 `entry-unreadable`,与位置无关。
+ *  恶意 getter/Proxy 在遍历中抛错时**绝不**外泄其文案(可能带 secret,与 parseDomain 的 R13 同纪律),只留一句中性话。 */
+function judgeEntry(schema, value, rejectedAs) {
     try {
         const r = schema.safeParse(value);
-        return r.success ? undefined : sanitizeZodError(r.error);
+        return r.success ? undefined : { error: sanitizeZodError(r.error), reasonCode: rejectedAs };
     }
     catch {
-        return new Error("entry could not be read during validation");
+        return { error: new Error("entry could not be read during validation"), reasonCode: "entry-unreadable" };
     }
 }
 /**
@@ -366,12 +393,12 @@ function salvageEntriesUnsafe(schema, raw) {
             // 会跟着一个在校验期间自我增殖的数组一路跑下去(病态 getter 在 zod 读字段时往同一个数组里再 push
             // 一条)——抢救是尽力而为的旁路,绝不许把同步读挂死。下标在回调里收,`filter` 本来就给 index。
             const kept = value.filter((entry, i) => {
-                const error = judgeEntry(element, entry);
-                if (error === undefined) {
+                const verdict = judgeEntry(element, entry, "entry-schema-invalid");
+                if (verdict === undefined) {
                     keptFrom.push(i); // 压缩后第 keptFrom.length-1 条 = 原文档第 i 条
                     return true;
                 }
-                bad.push(droppedEntry(outgoingPath([field, i]), error, entry));
+                bad.push(droppedEntry(outgoingPath([field, i]), verdict, entry));
                 return false;
             });
             // 零幸存者 ⇒ 没有要抢救的东西(见头注:绝不凭空造出一个空集合)。
@@ -387,11 +414,11 @@ function salvageEntriesUnsafe(schema, raw) {
             const bad = [];
             const kept = {};
             for (const [key, entry] of Object.entries(value)) {
-                const error = judgeEntry(keySchema, key) ?? judgeEntry(valueSchema, entry);
-                if (error === undefined)
+                const verdict = judgeEntry(keySchema, key, "entry-key-invalid") ?? judgeEntry(valueSchema, entry, "entry-schema-invalid");
+                if (verdict === undefined)
                     kept[key] = entry;
                 else
-                    bad.push(droppedEntry(outgoingPath([field, key]), error, entry)); // 键是用户写的,可能就是一条粘错位置的凭据
+                    bad.push(droppedEntry(outgoingPath([field, key]), verdict, entry)); // 键是用户写的,可能就是一条粘错位置的凭据
             }
             if (bad.length > 0 && Object.keys(kept).length > 0) {
                 dropped.push(...bad);
@@ -483,7 +510,7 @@ export function projectWarning(w) {
         case "legacy-governance-lifted":
             return { kind: w.kind, domain: w.domain, keys: w.keys };
         case "entry-dropped":
-            return { kind: w.kind, domain: w.domain, path: w.path, ...(w.identity === undefined ? {} : { identity: w.identity }) };
+            return { kind: w.kind, domain: w.domain, path: w.path, ...(w.identity === undefined ? {} : { identity: w.identity }), ...(w.reasonCode === undefined ? {} : { reasonCode: w.reasonCode }) };
         case "unread-config-file":
             return { kind: w.kind, file: w.file, ...(w.domain === undefined ? {} : { domain: w.domain }), why: w.why };
         default: {

package/dist/conformance/types.d.ts

@@ -229,7 +229,7 @@ export interface ConformanceNormalizer {
     /** 把一条坐标归一到共同空间。有损归一器在这里把段拼成串。 */
     path(p: readonly (string | number)[]): unknown;
     /** 把一条**告警投影**归一到共同空间(可选;先于 {@link ConformanceNormalizer.path} 作用,期望与实际两侧同过)。
-     *  用途:剥掉旧版**铸不出**的 additive 字段(S-712 的 `entry-dropped.identity`)—— 旧版没有这个字段不是读法
+     *  用途:剥掉旧版**铸不出**的 additive 字段(S-712 的 `entry-dropped.identity`、S-1295 的 `entry-dropped.reasonCode`)—— 旧版没有这个字段不是读法
      *  分歧,不许被记成「旧版行为红」。剥掉的字段同样是有损的一部分,`why` 里写明。release 模式禁归一器,故
      *  这只钩子只作用于 historical 读数。 */
     warning?(p: WarningProjection): WarningProjection;

package/dist/types.d.ts

@@ -17,11 +17,13 @@
  */
 import { z } from "zod";
 /** A private-key PEM header (`-----BEGIN [RSA |EC |OPENSSH |ENCRYPTED ]PRIVATE KEY`), unanchored — the ONE definition
- *  of that shape: {@link SECRET_LITERAL_RE} is composed from it (anchored, as one of its branches), and
- *  `redactSecrets` (config-fns) tests it ANYWHERE in a string, on every display-side normalized form. It carries spaces,
- *  so the token-splitting detector {@link containsSecretToken} only sees it at the very start of a string; a PEM behind
- *  a newline or a `key: ` prefix slipped past (S-712 codex review [high]), and a `key=`-prefixed percent-encoded one
- *  hid it behind `%20` on the raw form, a form-urlencoded one behind `+` (6.3.0). Public keys / certificates never match. */
+ *  of that shape, read ANYWHERE in a string by BOTH judges: the validation detector {@link containsSecretToken}
+ *  (`scanForSecret`, on every percent layer — 10.0.0) and the display redactor `redactSecrets` (config-fns, on every display-side
+ *  normalized form). {@link SECRET_LITERAL_RE} is also composed from it (anchored, as one of its branches — the exported per-token
+ *  literal shape). The header carries spaces, so the token-splitting passes can never isolate it; before 10.0.0 the validation side
+ *  therefore saw it only at the very start of a string, and a PEM behind a newline, a `key: ` prefix or any other text rode past
+ *  every free-text write port while the display side already withheld it (a `key=`-prefixed percent-encoded
+ *  one hid behind `%20` on the raw form, a form-urlencoded one behind `+`, 6.3.0). Public keys / certificates never match. */
 export declare const PRIVATE_KEY_PEM_HEADER: RegExp;
 export declare const SECRET_LITERAL_RE: RegExp;
 export declare const ENV_NAME: z.ZodEffects<z.ZodString, string, string>;
@@ -32,8 +34,9 @@ export declare const ENV_NAME: z.ZodEffects<z.ZodString, string, string>;
 export declare const hasNul: (s: string) => boolean;
 /** Does `s` contain a secret-shaped token? Scans every percent layer of it — the raw string AND up to three tolerant
  *  percent-decoded layers (a secret can hide as `%73%6B-…`; the ONE definition of those layers is `percentLayers` in the
- *  package-private `./secret-scan`) — so mcp args / dockerHost / URL components all get uniform percent-decode coverage.
- *  Tokenized + JWT-aware (see scanForSecret). Shared by NON_SECRET_URL + dockerHost + mcp stdio. Round-4/5/11. (6.3.0 moved
+ *  package-private `./secret-scan`) — so mcp args / execution coords / URL components all get uniform percent-decode coverage.
+ *  Tokenized + JWT-aware (see scanForSecret), plus a private-key PEM header read ANYWHERE in any layer ({@link PRIVATE_KEY_PEM_HEADER},
+ *  10.0.0 — the display redactor reads the same regex). Shared by every free-text write port (NON_SECRET_URL, mcp stdio, execution coords, ssh login, worker env, …). Round-4/5/11. (6.3.0 moved
  *  the decode loop out, unchanged in result — same layers, same bound, same verdict — and made it exception-free; the
  *  display-side readings the redactor also judges are not this detector's.) We do NOT fail-closed on a bare `%` — that
  *  would false-reject legit values like `100%` / `%s`. A secret glued to a malformed escape (`%ZZsk-`) is an accepted
@@ -41,7 +44,7 @@ export declare const hasNul: (s: string) => boolean;
  *  R11/R13/R14. */
 export declare function containsSecretToken(s: string): boolean;
 /** Scan a URL's PATH + query + fragment (KEYS and values, decoded, tokenized) for a secret-shaped literal.
- *  Userinfo is handled separately (NON_SECRET_URL bans it; dockerHost scans the ssh user). Round-4/5. */
+ *  Userinfo is handled separately (NON_SECRET_URL bans it; the ssh username is scanned by `containsSecretToken`). Round-4/5. */
 export declare function urlQueryFragmentHasSecret(u: URL): boolean;
 export declare const NON_SECRET_URL: z.ZodEffects<z.ZodString, string, string>;
 /** Validate a free-form `extraBody`: returns true = UNSAFE (reject). A GETTER-FREE, descriptor-based, bounded

package/dist/types.js

@@ -30,11 +30,13 @@ import { LANE_ENV_OWNER, MIGRATION_SIGNPOST, isMigratableEnvKey, laneEnvSeat, la
 // 0.1.32: this is the root fix for the public-key false-positive — replaces the 0.1.31 name-based exemption,
 // which review flagged as a bypass (a private key misnamed `*_PUBKEY` skipped scanning entirely).
 /** A private-key PEM header (`-----BEGIN [RSA |EC |OPENSSH |ENCRYPTED ]PRIVATE KEY`), unanchored — the ONE definition
- *  of that shape: {@link SECRET_LITERAL_RE} is composed from it (anchored, as one of its branches), and
- *  `redactSecrets` (config-fns) tests it ANYWHERE in a string, on every display-side normalized form. It carries spaces,
- *  so the token-splitting detector {@link containsSecretToken} only sees it at the very start of a string; a PEM behind
- *  a newline or a `key: ` prefix slipped past (S-712 codex review [high]), and a `key=`-prefixed percent-encoded one
- *  hid it behind `%20` on the raw form, a form-urlencoded one behind `+` (6.3.0). Public keys / certificates never match. */
+ *  of that shape, read ANYWHERE in a string by BOTH judges: the validation detector {@link containsSecretToken}
+ *  (`scanForSecret`, on every percent layer — 10.0.0) and the display redactor `redactSecrets` (config-fns, on every display-side
+ *  normalized form). {@link SECRET_LITERAL_RE} is also composed from it (anchored, as one of its branches — the exported per-token
+ *  literal shape). The header carries spaces, so the token-splitting passes can never isolate it; before 10.0.0 the validation side
+ *  therefore saw it only at the very start of a string, and a PEM behind a newline, a `key: ` prefix or any other text rode past
+ *  every free-text write port while the display side already withheld it (a `key=`-prefixed percent-encoded
+ *  one hid behind `%20` on the raw form, a form-urlencoded one behind `+`, 6.3.0). Public keys / certificates never match. */
 export const PRIVATE_KEY_PEM_HEADER = /-----BEGIN[A-Z0-9 ]*PRIVATE KEY/i;
 export const SECRET_LITERAL_RE = new RegExp(`^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\\s|basic\\s|eyJ[A-Za-z0-9_-]{10,}\\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|${PRIVATE_KEY_PEM_HEADER.source})`, "i");
 // 所有 *Env / *tokenEnv 字段的值是宿主机 env 变量的 NAME（不是值）。合法 env 变量名 + 拒绝 secret 形状的值（AKIA…
@@ -48,6 +50,10 @@ export const ENV_NAME = z
     // GITHUB_PAT_TOKEN / GHU_TOKEN (which the full SECRET_LITERAL_RE would). Round-5.
     .refine((s) => !/^AKIA[0-9A-Z]{12,}$/.test(s), "looks like an AWS access-key id, not an env-NAME — put the NAME of the env var here (the value lives in .env)");
 function scanForSecret(s) {
+    // A private-key PEM header ANYWHERE in the string (the one regex the display redactor reads too). The header carries spaces, so
+    // neither the start-anchored SECRET_LITERAL_RE below nor the tokenizer at the bottom can see it behind a prefix / newline. 10.0.0.
+    if (PRIVATE_KEY_PEM_HEADER.test(s))
+        return true;
     if (SECRET_LITERAL_RE.test(s))
         return true;
     // HTTP auth scheme + an opaque token, at a token boundary. SECRET_LITERAL_RE's `bearer\s`/`basic\s` only fire
@@ -77,8 +83,9 @@ function scanForSecret(s) {
 export const hasNul = (s) => s.includes("\0");
 /** Does `s` contain a secret-shaped token? Scans every percent layer of it — the raw string AND up to three tolerant
  *  percent-decoded layers (a secret can hide as `%73%6B-…`; the ONE definition of those layers is `percentLayers` in the
- *  package-private `./secret-scan`) — so mcp args / dockerHost / URL components all get uniform percent-decode coverage.
- *  Tokenized + JWT-aware (see scanForSecret). Shared by NON_SECRET_URL + dockerHost + mcp stdio. Round-4/5/11. (6.3.0 moved
+ *  package-private `./secret-scan`) — so mcp args / execution coords / URL components all get uniform percent-decode coverage.
+ *  Tokenized + JWT-aware (see scanForSecret), plus a private-key PEM header read ANYWHERE in any layer ({@link PRIVATE_KEY_PEM_HEADER},
+ *  10.0.0 — the display redactor reads the same regex). Shared by every free-text write port (NON_SECRET_URL, mcp stdio, execution coords, ssh login, worker env, …). Round-4/5/11. (6.3.0 moved
  *  the decode loop out, unchanged in result — same layers, same bound, same verdict — and made it exception-free; the
  *  display-side readings the redactor also judges are not this detector's.) We do NOT fail-closed on a bare `%` — that
  *  would false-reject legit values like `100%` / `%s`. A secret glued to a malformed escape (`%ZZsk-`) is an accepted
@@ -88,7 +95,7 @@ export function containsSecretToken(s) {
     return percentLayers(s).some((form) => scanForSecret(form));
 }
 /** Scan a URL's PATH + query + fragment (KEYS and values, decoded, tokenized) for a secret-shaped literal.
- *  Userinfo is handled separately (NON_SECRET_URL bans it; dockerHost scans the ssh user). Round-4/5. */
+ *  Userinfo is handled separately (NON_SECRET_URL bans it; the ssh username is scanned by `containsSecretToken`). Round-4/5. */
 export function urlQueryFragmentHasSecret(u) {
     let pathname = u.pathname;
     try {
@@ -160,7 +167,7 @@ export function extraBodyUnsafe(v) {
         const t = typeof cur;
         if (t === "string") {
             if (containsSecretToken(cur))
-                return true; // tokenized (mid-string secret too) — sibling of URL/dockerHost/mcp. R8
+                return true; // tokenized (mid-string secret too) — sibling of URL/coords/mcp. R8
             continue;
         }
         if (t === "number") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "9.0.0",
+  "version": "10.1.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",