@sema-agent/settings-schema 7.0.0 → 8.0.0

package/CHANGELOG.md

@@ -6,7 +6,179 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
-## Unreleased
+## 8.0.0 — 2026-10-04 — 一致性门第四条腿 `strictWrite`(严写受理)+ 每条腿都要表态(BREAKING,kit 类型面与 release 律)· `migrate-workers --check` 与真跑过同一只判定(BREAKING,CLI 退出码 / `refused[]`)· 导出面登记表机器门
+
+> **判档 = major**(README「发版纪律」):kit 的闭集 `LegName` 加一员、`ConformanceAdapter.legs` 从 `Partial<Record<…>>` 改成全量
+> `Record<LegName, LegStance>`(实现了 kit 适配器的消费方 tsc 红,即通知);release 律收紧(没表态的腿从「跳过、不算违例」变成违例);
+> CLI 机读契约字段 `outcome` / `refused` 在一种文档上改了值(`--check` 对整域会被拒的文档从 `pending` / 退出 3 变成 `refused` / 退出 1,
+> `refused[]` 从空变成逐条)。契约 schema、域默认值、三条读腿的读数**一字未动**:conformance 全语料重加冕,`domains` / `wire` / `localRoot`
+> 三腿金样、`baseline.json`、迁移金样 `m01–m04` 零 diff(`expected.json` 只新增 `strictWrite` 一格,82 个文件 0 行删改)。
+
+### 一、一致性门第四条腿 `strictWrite`(严写受理)
+
+**病**:写入席(管理面)判一份文档收不收,读侧(worker / CLI)逐条容错 —— 两侧此前没有任何一格放在同一份文档上对过。kit 的三条腿都是读语义:
+读腿抢救的地方(丢坏条目、整域降级、主机名夹紧)写入席**应该拒**,而这一点没有金样、没有门。
+
+**修**:
+
+- `LegName` 闭集 +1 `"strictWrite"`(`LEG_NAMES` 同步)。入参与 `domains` 腿**同一份字段表**(新导出类型 `DomainDocsInput`,两臂共用,
+  不抄第二份)。结局只用既有两类(`LegOutcome` 不动):全部受理 ⇒ `effective` = 提交的每个键 → 受理后的域文档(**只含提交的键、不补缺席域**;
+  空集受理成 `{}`),告警面为空,元数据回报 harness 注入的那一份;任何一份不受理 ⇒ `rejected{ stage: "validate" }`(写是一个动作,不逐份抢救)。
+- 契约仓自己的适配器用 `parseDomain` 接这条腿(`ContractModule` 加 `parseDomain`,`createContractAdapter` 的 `entries` 要第四个入口)。
+- **期望从哪来是一张表**:`derive.ts` 新导出 `LEG_EXPECTATION`(`Record<LegName, { source: "explicit" | "derivable"; why }>`,新开一条腿不表态
+  即编译红)。`strictWrite` 入参恒等、**期望不派生**(严写结局不是读结局的表示变换;从 `domains` 期望派生会让一份金样的错同时改写两条腿)。
+  语料加载器只按这张表判「能不能写 `{derive:true}`」—— 原来对 `domains` 的特判并进同一条规则。
+- **语料**:82 条 case 逐条加 `strictWrite` 显式金样,每条带 `why`(为什么受理 / 为什么拒):40 受理、42 拒(全在 `validate` 层)。
+  拒的 42 条 = 读腿抢救过的 22 条(全在逐条容错档的域上:models / skills / mcp / hosts)+ 读腿整条拒的 15 条 + 带非域名键的 5 条。
+- **金样逐条核**(`test/conformance-strict-write-8.0.0.test.ts`):一条**不调 `parseDomain`** 的律 ——「严写拒 ⇔ 文档集里有非域名键 ∨ 读腿整条拒 ∨
+  读腿在提交的某个域上抢救过(`entry-dropped` / `domain-defaulted` / `hosts-grandfathered`);否则受理,受理形 = 读腿 effective 里那几格」——
+  对着已冻结的 `domains` 金样逐条推导,与入库的严写金样 82/82 一致。两份金样从此互相压着。
+- **负控**(`test/conformance-mutation.test.ts` 第十一靶):把 `parseDomain` 换成读腿的宽松解析 ⇒ 严写腿**恰好**红在那 22 条读腿抢救 case 上
+  (别的腿、别的 case 一格不动);把非域名键静默跳过 ⇒ 恰好红在那 5 条上。
+- **`parseDomain` 对非域名响亮拒**:`"x" is not a config domain`(名字出门前过与告警坐标同一道脱敏)。此前 `DOMAIN_SCHEMAS[x]` 是 undefined,
+  TypeError 被 getter 守卫吞掉、说成 `invalid "x" config (a value could not be read during validation)` —— 抛还是抛,原因说错了。
+  严写腿把文档集的每个键都交给它,所以这句话现在是用户看得见的拒因。真域名的行为一字不变。
+
+### 二、每条腿都要表态:实现,或显式声明不承担(一条规则,四腿同律)
+
+**病**:3.0.0 起「未登记的腿 ⇒ `skipped: no adapter`,不算违例」。闭集加一条腿时,这条律让每个没接新腿的消费方**静默跳过、默认当通过** ——
+「这个消费方结构上没有这条写法」与「这个消费方忘了接」在报告里长一个样。
+
+**修**:
+
+- `ConformanceAdapter.legs` 改为全量 `Record<LegName, LegStance>`;`LegStance = ConformanceLeg | LegDeclined`,
+  `LegDeclined = { declined: LegDeclineReason; why: string }`。两臂**互斥**(`ConformanceLeg.declined?: never`、`LegDeclined.entry?` / `run?: never`),
+  运行期 release 门同一条律(带 `declined` 又带 `entry` 或 `run` = 形不对)—— 编译过了就证明表态形合法。收窄用 `stance.declined !== undefined`
+  (`"run" in stance` 收不窄)。理由词是闭集(`LEG_DECLINE_REASONS`),今天一个词 `"no-production-path"`
+  = 你的生产代码里结构上就没有这种读法 / 写法。刻意没有「有路径、还没接」的词:有路径就接,结局上的已知差走既有账本(带台账号、翻转条件、stale 律)。
+- release 律:**每条腿都有表态**(缺表态 / 形不对 / 理由词不在闭集 / `why` 为空 / 既实现又声明 = 违例)· 至少**实现**一条腿 · **实现的腿必须跑**。
+  声明的腿逐格记 `skipped`(detail = `consumer declines this leg (<理由词>): <why>`),报告新增 `adapter.declined` 逐条列出。historical 模式不跑这些律。
+- 新导出(`./conformance`):`LEG_DECLINE_REASONS`、`LEG_EXPECTATION`、类型 `LegStance` / `LegDeclined` / `LegDeclineReason` / `DomainDocsInput`。
+
+### 三、`migrate-workers --check` 与真跑过同一只判定
+
+**病**(7.0.0 既有,7.0.1 披露):`--check` 在整域终判**之前**就返回 —— 整域会被拒的文档(例:两只同名 worker)`--check` 报
+`outcome=pending` / 退出 3,真跑报 `outcome=refused` / 退出 1,按 `--check` 做闸的脚本会放行一次必被拒的真跑;整域终判拒时 stdout 的
+`refused[]` 为空,原因只在 stderr。
+
+**修**:写之前只有**一只**判定 —— 逐只 refused → 无改动 ⇒ noop → 整域终判 → 有改动;`--check` 不参与判定,只决定「有改动」那一支写不写
+(`pending` / `applied`)。整域终判拒时 `refused[]` 逐条带出被拒项,形与逐只 refused 同一套(`name` / `field` / `reason`;`field` 相对那只 worker;
+条目本身没有字符串名字时 `name` 为 `null`,不编名字)。stderr 两句文案、退出码的含义表、`outcome` 闭集都不变。`migrateWorkersDomain` 的输出不变。
+
+### 四、导出面登记表(API 面卫生的机器门,零新依赖)
+
+- `scripts/api-surface.mjs`(`npm run api:surface [-- --check]`)用 TypeScript 检查器(本来就在 devDependencies)列出 exports 表里 22 条模块子路径的
+  全部导出名(`export *` 展开,`value` / `type` / `value+type` 三形),写成 `docs/API-SURFACE.md`(不随包发)。
+- `test/api-surface.test.ts`:登记表逐名逐形 ≡ 真实导出面;子路径集合与次序 = exports 表;登记表 = 生成器原样输出;判据自证(每条子路径「值」形的名字
+  ≡ 运行期模块对象的键)。加 / 删 / 改形一个导出而不重生成登记表 ⇒ 红 —— 导出面的每次变动从此以登记表 diff 出现在评审里。
+- 编译器层的死代码门早已在位:`tsconfig.json` 的 `noUnusedLocals` / `noUnusedParameters`(`npm run typecheck` 覆盖 src + test),本版不重复造。
+- **`./migrate` 本版不删**:五个消费仓 `origin/main` 普查,管理面仍有三处生产 import(hosts grandfather 路由、hosts status 路由、
+  workers migrate-model 路由:`grandfatherHosts` / `planWorkerModelMigration` / `applyModelMigrationPlan` / `migrationDiffViolations` /
+  `ApplyMigrationDocs` / `LegacyWorkerModel`);server / cli / client-core / sdk 零 import。零外部消费的前提不成立 ⇒ 不删(ROADMAP 条目已按普查改写)。
+  `./api/wire` 早在 `3.0.0` 删除;`createSiblingResolver` 的工厂命名在 `2.0.0` 已改(本版核过,无动作)。
+
+### 用户可见变化(谁受影响 / 怎么改 / 不改会怎样)
+
+1. **实现了 kit 适配器的消费方**(server、管理面)—— `legs` 少任何一条腿的表态 ⇒ **tsc 红**(`Partial<Record<LegName, ConformanceLeg>>` 不再可赋给
+   `legs`)。改:每条没有的腿写 `{ declined: "no-production-path", why: "<你仓的事实>" }`。不改(用 `as` 绕过类型)⇒ release 门违例
+   「leg `<腿名>` has no stance」,`report.ok = false`。
+2. **持 `Record<LegName, …>` / 对 `LegName` 穷举 `switch` 的消费方** —— 编译红,要为 `strictWrite` 表态(实现或声明)。
+3. **读 `report.adapter.legs` 的** —— 语义从「登记的腿」变成「**实现**的腿」(声明的腿在新字段 `adapter.declined` 里);读 `skipped` 格 detail
+   文案做判断的 —— `no adapter: …` 那句不再出现,换成 `consumer declines this leg (…)` 或 `no stance: …`。
+4. **按 `migrate-workers --check` 做闸的脚本** —— 整域会被拒的文档(同名 / 同路由 / replicas 与 autoscaling 并存)现在 `--check` 也是
+   `outcome=refused` / 退出 1(以前 `pending` / 3)。退出码 3 仍只表示「会改、且写得进去」。读 `refused[]` 的 —— 这种文档上它不再是空数组,
+   项里 `name` 可以是 `null`(条目本身没有名字)。
+5. **捕 `parseDomain` 抛错文案的**(只在传入非域名时)—— 文案从 `invalid "x" config (a value could not be read during validation)` 变成
+   `"x" is not a config domain`;抛的时机不变。
+6. **装了包、只用 schema / 读写 helper 的消费方**:零变化(契约 schema、默认值、读腿读数一字未动)。
+
+### 红先 / 门
+
+- A:新腿前置格(`conformance-strict-write-8.0.0`)与表态律格(`conformance-legs-and-ledger` ①)。表态律的改前读数 = 7.0.1 同一构造
+  `violations=[]`、`ok=true`、detail `no adapter: this consumer registered no such read leg`(旧格「适配器缺一条腿 ⇒ 不算违例」钉的正是它,
+  本版按意图翻向);`parseDomain("hooks")` 改前抛 `a value could not be read`。
+- C:先只改测试、对 7.0.1 的 `cli.ts` 跑 —— 4 格红:四态表新行 `--check` 整域拒 `expected 3 to be 1`;翻钉格
+  `[3, 'outcome=pending written=false']` ≠ `[1, 'outcome=refused written=false']`;`refused[]` `expected 0 to be greater than 0`;`--check` 的 stderr 为空。
+  修后 25/25。原 🚧 特征钉(`--check` 先于整域终判)按它自己的翻转句翻成新读数。
+- B:`test/api-surface.test.ts`(五格)。
+- 全量:见收车读数(`npm test` / `npm run build` / `npm pack --dry-run`)。
+
+### 消费方(迁移句)
+
+- **server**(今天精确钉 6.4.0;一致性门实现 `wire` + `localRoot`):提货 8.x 时 `serverAdapter` 的 `legs` 改成
+  `{ domains: { declined: "no-production-path", why: "…" }, strictWrite: { declined: "no-production-path", why: "worker 只读不写:写入只经中心" },
+  localRoot: …, wire: … }` —— `Partial<Record<LegName, ConformanceLeg>>` 那一行换成 `ConformanceAdapter["legs"]`。语料新增的 82 格严写读数在你这边
+  记 `skipped`(声明不承担),既有账本不受影响。`./migrate`:零读点(你的提货门已钉零 import),删不删都不碰你。
+- **管理面(config-center 产品,今天钉 `^6.4.0`)**:提货 8.x 时 `legs` 四条表态 —— `domains` = 现在那条往返腿;**`strictWrite` = 域写受理那一段**
+  (对文档集的每个键跑写受理,任一份不受理 ⇒ `{ outcome: "rejected", stage: "validate", diagnostics }`,全部受理 ⇒
+  `{ outcome: "effective", effective: { <键>: <受理后的域文档> }, warnings: [], version: input.version, updatedAt: input.updatedAt }`);
+  `wire` / `localRoot` 声明 `no-production-path`(你生产 wire、不消费它;不读 `config.d/`)。两处已知差先看清再接:写受理剥未知键时回报的那份
+  名单在 kit 里没有位置(严写腿告警面恒空,按 `warnings: []` 交);写受理里的跨域引用完整性 `parseDomain` 不做(今天 40 条受理 case 跑过
+  `refIntegrityIssues` 零命中,所以暂不分叉)。`./migrate` 三处 import 不受影响(本版不删)。
+- **cli / client-core**(钉 `^7`,脱字号不跨 major):不提货就零动作。提货时:不实现 kit 适配器(cli 已显式拒接 kit 读腿;client-core 零 import)⇒ 零改动;
+  cli 那一格「`conformance.projectWarning === configFns.projectWarning`」同一只函数,不受影响;`./migrate` 零 import。
+- **sdk**:不依赖本包,零动作。
+
+### 订正 7.0.1 披露(test d327-schema701 验收 32 格 PASS 31 / INFO 1 / FAIL 0 后补)
+
+- **用户可见变化补一形(比字段改名更硬)**:7.0.1 起 `migrate-workers` 的 stdout **首行是结论行**(`outcome=… written=…`),整段 `JSON.parse(stdout)` 的旧脚本会抛错(test 实测 25/25 抛;7.0.0 为 0/24)—— 机读请取**最后一行**解析,或改读 `outcome` / `written` / `refused` 三个契约字段。
+- 7.0.1 披露的「已知未修」两形(`--check` 先于整域终判、整域终判拒时 `refused[]` 为空)本版已修,见上第三节。
+
+### 未闭环(如实)
+
+- 严写腿没有 historical 读数(`conformance/historical/` 是三腿时代跑的,53 条 × 三条读腿);重跑会改写一批 `firstRedOn`,本版没做。
+- 严写腿告警面恒空(`parseDomain` 不铸告警),写受理回报的剥键名单在 kit 里没有位置;严写不含跨域引用完整性。两样都是契约层的下一步,候裁。
+- 语料 c06 / c20 的严写金样是 🚧 特征格(S-1020,已定性为缺陷、下一版源头修):写入席受理 runtime 旧文档时三闸旧键被 runtime schema 静默剥掉(读腿是抬升),管理面若按受理形落库,读侧抬升此后找不到它们 = 运维护栏静默消失。修掉(写侧对这三个旧键响亮拒)时两格翻 `rejected{validate}`;在那之前,一个**正确拒收**的管理面会在这两格与金样分歧,请登记进 `knownDivergences`。
+
+## 7.0.1 — 2026-10-03 — 7.0.0 验收三件(文案 / 报告形):拒因补迁移指路、CLI 报告「没写」机读不可误读、指路写 `npx` 全名形(patch)
+
+> **判档 = patch**(README「发版纪律」:文案 / 报告形;**判据语义不变** —— 写闸的拒 / 放集合与每条 issue 的 `path` / `code` 同 7.0.0,`RESERVED_WORKER_ENV`
+> 键集不变(90 个),`migrateWorkersDomain` 输出不变;变的只有**拒因文案**与 **CLI 报告形**。conformance 重加冕:`expected.json` / `baseline.json` 零 diff,只有
+> `VERSION` 随版、c67 的 `meta.json` claim 文字改命令拼写)。来源 = test `d327-schema700` 验收的 ②③④(OBS-2 / OBS-3 与冲突 2)。
+> 判据 G7b / G7c 的拆分见 design/327 v1.2(`sessionBackend:tidb` 带全坐标 ⇒ 迁 mysql;无坐标 / 无口令引用 ⇒ refused),**实现不变**。
+
+### 病(7.0.0)
+
+- **② 车道旧形拒因不指路**:6.x 存量里最典型的一形 —— 车道只靠 `env.REMOTE_EXEC` / `K8S_*` 携带 —— 被保留名闸拒,拒因点名键与新字段,却**不提迁移命令**;
+  只有被删结构键(`sessionBackend` 等)那几形的拒因指路。运维看到「env cannot set reserved key」,不知道有一条命令能整份搬过去。
+- **③ CLI 报告歧义**:一个文件里有 worker 被 refused ⇒ rc 1、文件一字未写,但 stdout 的 JSON 把其余 worker 列在 `changed` 下;只解析 stdout 的运维脚本
+  会以为它们已迁(真案:`evidence/l1/runs.json` g5-mixed,`fx-good-k8s` 列在 `changed`、盘上 sha256 与跑前相同)。
+- **④ 指路写裸 bin 名**:拒因 / 文档里是 `settings-schema migrate-workers <file>`,没装本包的运维粘贴即 `command not found`(design/327 §3.4 的原句是 `npx` 全名形)。
+
+### 修
+
+- **② 一条规则、一个谓词**:拒因带不带迁移指路只看**这个键「旧形 ⇒ 迁移能搬」**。「迁移能搬」= 迁移自己识别的键集 —— 车道键(车道表全部 env 名 +
+  `REMOTE_EXEC` / `REQUIRE_EXECUTION_LANE`)∪ 店键(`DB_BACKEND` / `MEMORY_ENGINE` / `MEMORY_ENGINE_BACKEND`)—— 写闸读**同一只谓词**
+  (`isMigratableEnvKey`,包内私有,在 `execution-lane-index.ts`;迁移的 `laneKeysOf` / `storeKeysOf` 改读同一处),不是第二张手抄的表。命中的键,
+  `env` / `secretEnv` 两口的拒因都在键名后带指路;迁移搬不了的保留名(`PORT` / `MODEL_*` / `MYSQL_*` / `PG_*` / `SESSION_BACKEND` …)不带。句尾的
+  `— set it via <归属字段>` 一字不动(下游按它抽归属字段)。
+- **④ 指路句是一个常量**:`MIGRATION_SIGNPOST`(内含 `MIGRATE_WORKERS_COMMAND` = `npx @sema-agent/settings-schema migrate-workers`),保留名闸与删除项预处理(七个被删旧键)
+  引用同一个;迁移 / CLI 的 usage / 文档里的命令拼写同一处。全仓扫描零裸 bin 名残留(`CHANGELOG` 的 7.0.0 及更早段落是历史记录,原句不追改)。
+- **③ 报告形**:CLI 对退出码 0 / 1 / 3 的 stdout 恰两行 —— 第 1 行**唯一结论行** `outcome=<refused|applied|noop|pending> written=<true|false>`,
+  第 2 行 JSON(加 `outcome` / `written`)。`written` 由 `outcome` 派生(只有 `applied` 写盘,写盘成功之后才报;`pending` = `--check` 有改动、没写)。
+  名单键名**带时态**:`changed` / `dropped` 仅在 `written=true` 时存在,没写时是 `wouldChange` / `wouldDrop`。退出码 0 / 1 / 2 / 3 与 stderr 文案不变。
+
+### 用户可见变化(逐条;对只解析旧字段的运维脚本是**行为变化**)
+
+1. **`changed` 在没写盘时不再出现**:7.0.0 的 stdout JSON 恒有 `changed`;7.0.1 起仅 `written=true`(`outcome=applied`)时有。refused / noop / pending 三态下它换名 `wouldChange`,
+   只读 `changed` 的脚本读到 `undefined` —— 这正是要的结果(以前读到一份没落盘的「已迁」名单)。`dropped` 同理换名 `wouldDrop`。`applied` 的 `changed` / `dropped` 形与 7.0.0 相同(有正控格)。
+2. **stdout 从一行 JSON 变成两行**:第 1 行是结论行,JSON 在第 2 行(**取最后一行解析**);整段 `JSON.parse(stdout)` 的脚本要改成只解析最后一行。JSON 新增 `outcome` / `written`。
+3. **`--check` 有改动时 `outcome=pending written=false`**(退出 3,同前):结论词的第四个值,是 `--check` 专有的「有改动、没写」。
+4. **整域终判拒(迁出的文档整域读不进 7.0.0)现在也出报告**:7.0.0 此时 stdout 先打了含 `changed` 的 JSON、再在 stderr 说 nothing was written(同一个歧义);7.0.1 报 `outcome=refused written=false`,
+   `refused[]` 为空、原因仍在 stderr(那条文案不变)。
+5. **拒因文案变长**:车道键 / 店键的保留名拒因在键名后多一段指路;被删旧键的拒因把「run the one-time migration before reading this document: …」换成同一个常量的句子
+   (仍含 `migrateWorkersDomain` 与 `migrate-workers`)。读拒因文案做字符串匹配的下游:`set it via <字段>` 句尾不变。
+6. **已知(7.0.0 既有,披露、不在本 patch 改)**:`--check` 先于整域终判 —— 迁出的文档整域读不进 7.0.0(例:两只同名 worker)时,`--check` 报 `outcome=pending`(退出 3),
+   真跑才报 `outcome=refused`(退出 1)。`pending` 的意思是「迁移产出了改动、`--check` 没写」,**不保证**真跑一定写盘;要改它会动 `--check` 的退出码,另案(`test/cli-report-7.0.1.test.ts` 有一格 🚧 特征钉,修掉时翻成 refused / rc 1)。
+
+### 红先 / 门
+
+- 红先提交只含两个新测试文件 —— `test/migration-signpost-7.0.1.test.ts`(②④)、`test/cli-report-7.0.1.test.ts`(③)。修前读数:两文件 44 格 **29 红** / 15 绿(绿 = 判据语义不变的 P6 两格 +
+  不带指路的保留名 8 格 + P3「两侧非空」+ 句尾不变 + 另 3 格正控:报告 `event` / `file`、用法错 rc 2 无 stdout、refused 的 stderr 文案);P3 对拍逐个保留名:迁移会动而拒因不带指路的 57 个名(车道 52 + `REMOTE_EXEC` / `REQUIRE_EXECUTION_LANE` + 店键 3,× `env` / `secretEnv` 两口)全红,反向(拒因带指路而迁移不动)0 个。
+- **差分(车内一次性,脚本不入库)**:同一批 379 例(每个保留名 × `env` / `secretEnv` × enabled / 停用 = 360,七个删除项 × 2 = 14,非保留名 4 与合法新形 1 = 5)过 7.0.0 发布树与本树的
+  `WorkerSpec.safeParse`:`(success, issue.path, issue.code)` 零差异(374 例两边都拒、5 例两边都放);同批过 `migrateWorkersDomain`:输出逐字节相同。
+- **codex 一轮**(`adversarial-review`,`gpt-6.1-sol`,`--base 1db8e3f --scope branch`):Verdict approve、No material findings;它复现的「`--check` 跳过整域终判」即上面「用户可见变化」第 6 条(基线既有)。
+- 旧测试按意图改:`migrate-workers-7.0.0.test.ts` 一格(CLI 可迁:解析 stdout 最后一行,加结论行断言)+ describe 标题的命令拼写。
 
 ## 7.0.0 — 2026-10-03 — M-R2 WorkerSpec 结构块:执行车道 `runtime.execution` + 存储 `runtime.store`,词表单正本 `EXECUTION_LANES` 等六个导出,一次性迁移 `migrateWorkersDomain`(BREAKING)
 

package/README.md

@@ -48,6 +48,19 @@ 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.
 
+## 升级指引:7.x → 8.0.0
+
+8.0.0 的破坏面只在**一致性门 kit**(`./conformance`)的类型与 release 律、以及 CLI `migrate-workers --check` 的一种结局上;契约 schema、域默认值、
+读写 helper 的读数一字未动。逐条(谁受影响 / 怎么改 / 不改会怎样)见 CHANGELOG 8.0.0「用户可见变化」,要点:
+
+- **实现了 kit 适配器的**:`legs` 是全量 `Record<LegName, LegStance>` —— 四条腿(`domains` / `strictWrite` / `wire` / `localRoot`)每条要么实现、
+  要么写 `{ declined: "no-production-path", why: "<你仓的事实>" }`。少一条 ⇒ tsc 红;用 `as` 绕过 ⇒ release 门违例 `has no stance`。
+  只读的 worker:`domains` 与 `strictWrite` 声明不承担;写入席:实现 `strictWrite`(域写受理,任一份不受理 ⇒ `rejected{validate}`)。
+- **持 `Record<LegName, …>` / 对 `LegName` 穷举的**:为新腿 `strictWrite` 表态。
+- **按 `migrate-workers --check` 做闸的脚本**:整域会被拒的文档 `--check` 现在报 `outcome=refused` / 退出 1(以前 `pending` / 3),`refused[]`
+  逐条带出被拒项(`name` 可为 `null`)。
+- **只用 schema / helper 的**:零动作。`./migrate` 本版**没有**删(管理面仍在用)。
+
 ## What's in it
 
 - **The zod contract** (`types.ts`): `DOMAIN_SCHEMAS` (17 domains — 0.10.0 adds `projects`, the project
@@ -98,6 +111,30 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   `env.REMOTE_EXEC` — the migration never guesses a lane) come back in `refused` with the field to fix and the
   `original` row verbatim — they are NOT in the migrated `doc`, so a caller that writes `doc` back must put each
   `refused[].original` back at its `index` (or store it aside), or that worker's spec disappears.
+- **`migrate-workers` CLI: report shape + rejection signposts (7.0.1)** (`bin/settings-schema.mjs`, core in `cli.ts`):
+  `npx @sema-agent/settings-schema migrate-workers <workers.json> [--check]` prints exactly two lines on stdout (exit 0 / 1 / 3): line 1 is the
+  ONE conclusion line `outcome=<refused|applied|noop|pending> written=<true|false>`, line 2 is the JSON report (`event: "workers_domain_migrated"`,
+  `outcome`, `written`, `file`, the worker lists, `refused[]`). Only `applied` writes the file (`written` is derived from `outcome`; `pending` =
+  `--check` with changes). The list keys carry tense — `changed` / `dropped` exist **only when `written=true`**; when nothing was written
+  (refused / noop / pending) the same lists are `wouldChange` / `wouldDrop`, so a script that reads only stdout can never take a worker that was
+  not migrated for migrated. Exit codes are unchanged (0 applied or noop · 1 refused or the migrated document does not read as a 7.0.0 workers
+  domain, nothing written · 2 usage / unreadable / not JSON, empty stdout · 3 `--check` with changes).
+
+  | 7.0.0 stdout | 7.0.1 stdout |
+  |---|---|
+  | one JSON line | the conclusion line, then the JSON line (parse the **last** line) |
+  | `changed` (always) | `changed` when `written=true`, else `wouldChange` |
+  | `dropped` (always) | `dropped` when `written=true`, else `wouldDrop` |
+  | — | `outcome`, `written` |
+
+  **8.0.0**: `--check` and a real run go through ONE verdict (per-worker refusals → nothing to change ⇒ `noop` → the whole-domain final judgment →
+  changes); `--check` only decides whether the "changes" branch writes (`pending`) or not. A document the whole-domain judgment refuses (two workers
+  with one name …) is `outcome=refused` / exit 1 under `--check` too (7.x: `pending` / exit 3), and `refused[]` names the refused items in the
+  per-worker shape (`name` / `field` / `reason`; `name` is `null` for an entry that carries no string name) instead of being empty.
+
+  Rejections that a migration can lift carry ONE signpost sentence (a constant, `MIGRATION_SIGNPOST`): the seven deleted 6.x fields, and an
+  `env` / `secretEnv` key the migration moves or drops (the execution-lane keys incl. `REMOTE_EXEC` / `REQUIRE_EXECUTION_LANE`, and the store keys
+  `DB_BACKEND` / `MEMORY_ENGINE` / `MEMORY_ENGINE_BACKEND`). A reserved name the migration cannot move (`PORT`, `MODEL_*`, `MYSQL_*` …) carries none.
 - **Safety merge-spec** (`safety-merge-spec.ts`, subpath `./safety-merge-spec`): `SAFETY_MERGE_SPEC`, the ONE
   per-category merge/enforcement table every settings resolver reads (`mergeShape` / `minTrust` / `tighten` /
   `enforcement` / `fail`) — no consumer re-implements the merge law. 1.1.0 adds **member-level admission**:
@@ -250,9 +287,11 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 
 ## Cross-repo conformance gate (`./conformance`, 3.0.0)
 
-契约仓自带**金样语料 + 比对器**,随包发(`conformance/cases/**`)。每个消费方把**自己的生产读腿**塞给
+契约仓自带**金样语料 + 比对器**,随包发(`conformance/cases/**`)。每个消费方把**自己的生产入口**塞给
 kit 跑一遍 ⇒ 同一份 settings 语料在配置中心、worker、管理面、契约仓自身读出的 effective 逐字节一致、
-告警多重集一致。
+告警多重集一致;写入席对同一份文档收不收也一致。**四条腿**(8.0.0):`domains`(各域原始文档 → effective)、
+`strictWrite`(同一份文档 → 严写受理;契约仓 = `parseDomain`,任一份不受理 ⇒ `rejected{validate}`,读腿抢救处严写拒)、
+`wire`、`localRoot`。
 
 ```ts
 import { runConformance } from "@sema-agent/settings-schema/conformance";
@@ -264,13 +303,15 @@ if (!report.ok) throw new Error(report.violations.join("\n"));
   (**生产代码**的入口 —— 在测试里把契约包函数本身当读腿,门证明的只是「包等于包」)。4.0.0 起这句
   **有牙**:入口落在**本包自己的 `dist/`**(拿自己比自己)⇒ `createContractAdapter` **当场拒**;落在
   **另一份**装好的契约包里(`historical` 模式的正当目标)⇒ 工厂不拒,由 `release` 门点名。
-- **两种模式**:`release`(版本三方对齐 + 生产入口核验 + 禁 `only`/归一器 + 至少登记一条腿 + **登记的腿
-  必须跑**;未登记的腿只记 `skipped: no adapter`,不算违例)与 `historical`(对旧版包跑,只记行为 diff)。
+- **每条腿都要表态**(8.0.0):实现它,或 `{ declined: "no-production-path", why }`(你的生产代码结构上没有这种读法 / 写法)。
+  缺表态 = release 违例;声明的腿逐格 `skipped`(带理由),报告 `adapter.declined` 列出。
+- **两种模式**:`release`(版本三方对齐 + 每条腿有表态 + 生产入口核验 + 禁 `only`/归一器 + 至少实现一条腿 + **实现的腿
+  必须跑**)与 `historical`(对旧版包跑,只记行为 diff)。
 - **四律**:对抗律 / 变异律 / 覆盖律 / 来源律 —— 缺一不算「门」。
 - **已知分歧账本** `knownDivergences`:消费方对金样的**合法**差异(临时欠账 / 成文语义)登记成机器可核的
   一行,命中记 `diff-ledgered` 不阻塞;**告警差与元数据差永不可入账**,而**从未命中的一条登记本身就是
   违例**(棘轮只降不升,逼着到期翻转)。契约仓自证不许挂账本。
-- 契约形、报告形、语料贡献形、以及**三条如实登记的边界**见 `docs/CONFORMANCE.md`。
+- 契约形、报告形、语料贡献形、以及**如实登记的边界**见 `docs/CONFORMANCE.md`。
 - Node-only(语料在磁盘上,local-root 腿要落盘),不进主 barrel。
 
 ## Secret boundary
@@ -298,6 +339,7 @@ defaults. Each `config.d/<domain>.json` is exactly that domain's zod object.
 自 `1.0.0`(改名)起本包按**标准 semver** 发版;`0.x` 时代的「破坏性变更必 bump minor」规矩**已撤**
 (末条仅作历史注记)。判档看**消费方可见性**,不看 diff 大小:
 
+- **CLI 报告形的契约边界(7.0.1 起)**:`migrate-workers` 的 stdout = 结论行 + JSON;其中 `outcome` / `written` / `refused` 三字段是机读契约(再改按 minor),其余键与行形是诊断面,patch 可变(test 认定口径 2026-10-03:CLI 报告形不在 C-R197 包导出面)。机读请取最后一行解析。
 - **破坏性变更必 bump major**:字段/导出改名、改形(retype)、删除、默认值变更、校验收紧或放宽
   (例:`.passthrough()` → 默认 strip、宽读 → 严判)、枚举**重排**——凡是能让一个按上一版契约写的
   消费方在**运行期**变红、或让同一份配置解析出不同结果的改动;编译期同判,**唯一裁定例外** = 下一条的

package/conformance/VERSION

@@ -1 +1 @@
-7.0.0
+8.0.0

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

@@ -98,6 +98,11 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:读腿逐条抢救 models(丢掉缺 id 的那一条 + entry-dropped);写入席不替运维删条目 —— 同一份文档里有一条坏条目,整次不受理。"
+  },
   "wire": {
     "derive": true
   },

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

@@ -89,6 +89,11 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:读腿对 hosts 先做存量夹紧(超长名剔除,hosts-grandfathered)再逐条抢救(entry-dropped);两样都只活在读路径,严写按现行 schema 判:名长 > 63 与名字形不合法都拒。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c03-literal-dotted-top-key/expected.json

@@ -102,6 +102,47 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {
+      "models": {
+        "models": [
+          {
+            "api": "openai-completions",
+            "apiKeyEnv": "OPENAI_API_KEY",
+            "enabled": true,
+            "id": "m0-id",
+            "name": "m0",
+            "provider": "openai",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          },
+          {
+            "api": "openai-completions",
+            "apiKeyEnv": "OPENAI_API_KEY",
+            "enabled": true,
+            "id": "m1-id",
+            "name": "m1",
+            "provider": "openai",
+            "quotaWeight": 1,
+            "reasoning": false,
+            "tier": "standard",
+            "vision": false
+          }
+        ],
+        "roles": {},
+        "tierGroups": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-09-16T00:00:00.000Z"
+    },
+    "why": "受理:models 文档里字面叫 `models.1.k` 的键与条目里的未知键 `k` 都被 schema 剥掉(读腿报 unknown-keys-dropped);parseDomain 同样剥、不铸告警 —— 受理形逐字等于读腿 models 那一格,告警面为空。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c04-all-bad-collection-not-salvaged/expected.json

@@ -67,6 +67,11 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:全坏集合,读腿救不出一条幸存者、整域降级成默认(domain-defaulted);写入席不会把坏文档换成空默认存下。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c05-gate-domain-bad-entry-throws/expected.json

@@ -3,6 +3,11 @@
     "outcome": "rejected",
     "stage": "validate"
   },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:rosters 是 gate 域,读腿对坏条目(name 是数字)本就整域拒;严写同一份文档同样过不了 rosters 的 schema。"
+  },
   "wire": {
     "outcome": "rejected",
     "stage": "validate",

package/conformance/cases/c06-legacy-governance-lift/expected.json

@@ -89,6 +89,18 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {
+      "runtime": {}
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-09-16T00:00:00.000Z"
+    },
+    "why": "🚧 S-1020 特征格(已裁 = 缺陷,源头修排下一版):受理,受理形 = { runtime: {} }。读腿从 runtime 旧文档抬升 governance 三闸(legacy-governance-lifted);写入席不抬升 —— 受理的只有提交的 runtime 一份,三闸旧键被 runtime schema 静默剥掉(不拒、不告警,读腿的剥键扫描本就豁免这三个键)。写入席若按受理形落库,读侧抬升此后找不到它们。S-1020 修掉(写侧拒 runtime 上的三闸旧键)时本格翻 rejected{validate}。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c07-hooks-is-not-a-config-domain/expected.json

@@ -62,6 +62,11 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:`hooks` 不是域名(它是 settings.json 的键,不是配置域)—— 写入席没有这个域可受理;读腿各按各的处置(domains 腿按域名取文档故无声、wire 逐字承运、本地报 not-a-domain),严写不替运维把它丢掉。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c08-limits-unknown-carried-64/expected.json

@@ -326,6 +326,83 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {
+      "limits": {
+        "zzzUnknown000": 0,
+        "zzzUnknown001": 1,
+        "zzzUnknown002": 2,
+        "zzzUnknown003": 3,
+        "zzzUnknown004": 4,
+        "zzzUnknown005": 5,
+        "zzzUnknown006": 6,
+        "zzzUnknown007": 7,
+        "zzzUnknown008": 8,
+        "zzzUnknown009": 9,
+        "zzzUnknown010": 10,
+        "zzzUnknown011": 11,
+        "zzzUnknown012": 12,
+        "zzzUnknown013": 13,
+        "zzzUnknown014": 14,
+        "zzzUnknown015": 15,
+        "zzzUnknown016": 16,
+        "zzzUnknown017": 17,
+        "zzzUnknown018": 18,
+        "zzzUnknown019": 19,
+        "zzzUnknown020": 20,
+        "zzzUnknown021": 21,
+        "zzzUnknown022": 22,
+        "zzzUnknown023": 23,
+        "zzzUnknown024": 24,
+        "zzzUnknown025": 25,
+        "zzzUnknown026": 26,
+        "zzzUnknown027": 27,
+        "zzzUnknown028": 28,
+        "zzzUnknown029": 29,
+        "zzzUnknown030": 30,
+        "zzzUnknown031": 31,
+        "zzzUnknown032": 32,
+        "zzzUnknown033": 33,
+        "zzzUnknown034": 34,
+        "zzzUnknown035": 35,
+        "zzzUnknown036": 36,
+        "zzzUnknown037": 37,
+        "zzzUnknown038": 38,
+        "zzzUnknown039": 39,
+        "zzzUnknown040": 40,
+        "zzzUnknown041": 41,
+        "zzzUnknown042": 42,
+        "zzzUnknown043": 43,
+        "zzzUnknown044": 44,
+        "zzzUnknown045": 45,
+        "zzzUnknown046": 46,
+        "zzzUnknown047": 47,
+        "zzzUnknown048": 48,
+        "zzzUnknown049": 49,
+        "zzzUnknown050": 50,
+        "zzzUnknown051": 51,
+        "zzzUnknown052": 52,
+        "zzzUnknown053": 53,
+        "zzzUnknown054": 54,
+        "zzzUnknown055": 55,
+        "zzzUnknown056": 56,
+        "zzzUnknown057": 57,
+        "zzzUnknown058": 58,
+        "zzzUnknown059": 59,
+        "zzzUnknown060": 60,
+        "zzzUnknown061": 61,
+        "zzzUnknown062": 62,
+        "zzzUnknown063": 63
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-09-16T00:00:00.000Z"
+    },
+    "why": "受理:limits 是 open-world,64 个未知键原样承运(读腿报 unknown-keys-carried);严写同样承运,受理形等于读腿 limits 那一格,告警面为空。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c09-limits-unknown-carried-65/expected.json

@@ -328,6 +328,84 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {
+      "limits": {
+        "zzzUnknown000": 0,
+        "zzzUnknown001": 1,
+        "zzzUnknown002": 2,
+        "zzzUnknown003": 3,
+        "zzzUnknown004": 4,
+        "zzzUnknown005": 5,
+        "zzzUnknown006": 6,
+        "zzzUnknown007": 7,
+        "zzzUnknown008": 8,
+        "zzzUnknown009": 9,
+        "zzzUnknown010": 10,
+        "zzzUnknown011": 11,
+        "zzzUnknown012": 12,
+        "zzzUnknown013": 13,
+        "zzzUnknown014": 14,
+        "zzzUnknown015": 15,
+        "zzzUnknown016": 16,
+        "zzzUnknown017": 17,
+        "zzzUnknown018": 18,
+        "zzzUnknown019": 19,
+        "zzzUnknown020": 20,
+        "zzzUnknown021": 21,
+        "zzzUnknown022": 22,
+        "zzzUnknown023": 23,
+        "zzzUnknown024": 24,
+        "zzzUnknown025": 25,
+        "zzzUnknown026": 26,
+        "zzzUnknown027": 27,
+        "zzzUnknown028": 28,
+        "zzzUnknown029": 29,
+        "zzzUnknown030": 30,
+        "zzzUnknown031": 31,
+        "zzzUnknown032": 32,
+        "zzzUnknown033": 33,
+        "zzzUnknown034": 34,
+        "zzzUnknown035": 35,
+        "zzzUnknown036": 36,
+        "zzzUnknown037": 37,
+        "zzzUnknown038": 38,
+        "zzzUnknown039": 39,
+        "zzzUnknown040": 40,
+        "zzzUnknown041": 41,
+        "zzzUnknown042": 42,
+        "zzzUnknown043": 43,
+        "zzzUnknown044": 44,
+        "zzzUnknown045": 45,
+        "zzzUnknown046": 46,
+        "zzzUnknown047": 47,
+        "zzzUnknown048": 48,
+        "zzzUnknown049": 49,
+        "zzzUnknown050": 50,
+        "zzzUnknown051": 51,
+        "zzzUnknown052": 52,
+        "zzzUnknown053": 53,
+        "zzzUnknown054": 54,
+        "zzzUnknown055": 55,
+        "zzzUnknown056": 56,
+        "zzzUnknown057": 57,
+        "zzzUnknown058": 58,
+        "zzzUnknown059": 59,
+        "zzzUnknown060": 60,
+        "zzzUnknown061": 61,
+        "zzzUnknown062": 62,
+        "zzzUnknown063": 63,
+        "zzzUnknown064": 64
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-09-16T00:00:00.000Z"
+    },
+    "why": "受理:同上一条,65 个未知键(读腿告警截断到 64 条坐标 + truncatedFrom,那是告警面的事);严写逐字承运全部 65 个,告警面为空。"
+  },
   "wire": {
     "derive": true
   },

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

@@ -96,6 +96,11 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:models.roles 里有一个密钥形的坏键,读腿把它逐条丢掉(entry-dropped,坐标脱敏);严写不删条目 ⇒ 整次不受理。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c11-unicode-unknown-keys/expected.json

@@ -78,6 +78,20 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {
+      "scenarios": {
+        "scenarios": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-09-16T00:00:00.000Z"
+    },
+    "why": "受理:scenarios 里 CJK / emoji / 组合字符的未知键被 schema 剥掉(读腿报 unknown-keys-dropped);严写同样剥、不铸告警,受理形等于读腿 scenarios 那一格。"
+  },
   "wire": {
     "derive": true
   },

package/conformance/cases/c12-prototype-name-top-keys/expected.json

@@ -62,6 +62,11 @@
       "updatedAt": "2026-09-16T00:00:00.000Z"
     }
   },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:`constructor` / `toString` / `hasOwnProperty` / `__proto__` 都不是域名 —— 原型链上的名字在严写这里同样只是「不是域的键」,写入席没有这些域可受理(读腿:domains 无声、wire 逐字承运、本地报 not-a-domain)。"
+  },
   "wire": {
     "derive": true
   },