@sema-agent/settings-schema 14.3.0 → 14.5.0

package/CHANGELOG.md

@@ -8,7 +8,71 @@
 
 ## Unreleased
 
-(空)
+## 14.5.0 — 2026-10-23 — minor:同步单口 `migrateConfigDocuments`(存量文档迁移 + 整域终判一次调用)· URL 内嵌凭据判官上移契约包(`findUrlCredential` 等)· 文件系统失败句的出路顺序(不可变标志先行)· `GLOBAL_SCOPE` 注释改真
+
+> 档位(按发版纪律):**minor** —— 加性:新导出 `migrateConfigDocuments` + 型 `ConfigDocumentsMigration` / `MigrateConfigDocumentsOptions`(`./node`);新导出 `findUrlCredential` · `findUrlUserinfo` · `urlCredentialRule` · `isCredentialParamName` ·
+> `URL_CREDENTIAL_REASONS` · `CREDENTIAL_PARAM_NAMES` + 型 `UrlCredential` / `UrlCredentialReason` / `CredentialParamName`(包根);文件系统失败句的出路顺序与一处 JSDoc 改真是文案(`./node` 的 `removeFile` 抛出的错对象形状变了,见第四条)。既有导出对既有输入的答案不变(文案两处见下面第三、四条)。
+
+- **同步单口 `migrateConfigDocuments(docs, { documents })`(`./node`):「存量文档迁移 + 整域终判」一次调用,无 io**。此前这件事只有目录形(`migrateConfigDirectory`,异步、带 io)一个出口;手里已经有各层存量文档原文、不经目录的调用方
+  (命令行壳按层读 `settings` 里的 models 域)只能自己把 `migrateStoredDocuments`(纯改写)与 `parseDomain`(整域终判)按「迁移步拒 → 无改动 ⇒ noop → 改过的文档整域终判」的序再组装一遍 ——
+  第二份同语义,包内那只判一变就悄悄分叉。现在目录形读完目录后调的就是这只函数的内核(语义只此一处),同步口把同一个闭集的**无 io 形**交出去:
+  `unreadable`(覆盖面内某份文档不是 JSON 对象 ⇒ 不抛,点名 `document`,句式与坏文件同一句)· `no-documents` · `refused`(迁移步拒或整域终判拒;`refused[]` 同目录形,`docs` 仍交回迁移后的那一份)· `noop`(`docs` 里每份都是入参的同一引用)·
+  `migrated`(`docs` = 迁移后的覆盖面内文档全集,`applied` 逐条收据,`changed` = 改过 / 新建的文档名,`removed` = 被移除的退役域)。覆盖面 `documents` 与 `coverage` 的判(SS-M1 要写的目标域都在覆盖面里才算「一个 scope 的全集」)、「没改的文档不终判」、
+  「迁移不许越过覆盖面去写」与目录形逐字同;入参从不被改,重跑迁移后的 `docs` ⇒ `noop`。**一层一次调用**:层序 / 覆盖 / 托管锁的合并读法不在这里。
+  三问 —— **谁需要**:命令行壳(「引擎起服那一次迁移之后,models 域整域读不读得进」的读法,今天自己组装),以及任何手里已有存量文档原文的消费方;**谁受伤**:无(新导出;目录形的返回形与行为逐字不变,由原有钉守);**补偿**:无需 ——
+  换读 = 把自己组装的那一段删掉,`refused` ⇒ 引擎同样不写回、整域落缺省(反向不成立:引擎对整个目录一判,别的文档被拒也会让整目录不写),`docs` 即壳的写手要的那一份。
+  钉:`test/config-documents-migration-14.5.0.test.ts`(models 域五形 · 坏形不抛 · 入参冻结也能迁 · 对一致性语料每个 case 目录与目录形同一个答案、真跑写出的文件 = `changed` 的文档文本)。
+- **URL 内嵌凭据判官上移契约包(包根):`findUrlCredential(raw)` · `findUrlUserinfo(raw)` · `urlCredentialRule(hit)` · `isCredentialParamName(name)` · `URL_CREDENTIAL_REASONS` · `CREDENTIAL_PARAM_NAMES`**(lift 自服务端的同名判官,规则、拒因词与规则句逐字)。
+  规则一条:URL 里的凭据 = 日志脱敏器已经在用的那个定义 —— userinfo(只有用户名也算,判由本包 URL 形判官 `httpUrlFlaws`),或 query / fragment 里名字整名在凭据名表(23 词)上的参数(名字按收方的读法读:
+  `URLSearchParams` 解一次码,ASCII 大小写不敏感)。答首个命中(userinfo → query → fragment),拒因闭集两词 `url_userinfo` / `url_credential_param`;**值从不进答案**,参数名只回显表里的那个词(小写);不透明形 / 解析不了的值答「没有」(收不收是座位自己的律)。
+  **判官只判有没有,载体律留在座位**:同一个键在新提交门拒、在续跑重放存量体的腿不拒(拒会砖死升级前停驻的任务)、部署 env 只因 userinfo 拒 —— 所以判官**没有**接进任何读已落盘 / 重放字节的 schema 或读器(`readRequestMcpTransport` · `HttpHookEntry.url`),
+  那会把载体律焊死成读器律,是破坏性变更;座位在自己的新提交门调它,拒体的形(HTTP 码、字段坐标、出路句)仍是座位自己的铸点。与 `NON_SECRET_URL` 是**两个问题、互补**:本判官按参数**名**判(名字整名在凭据名表上,不论值长什么样),`NON_SECRET_URL` 的 `urlQueryFragmentHasSecret` 按**值形**判密钥(值长得像密钥,不论参数叫什么,并禁 userinfo / fragment),所以 `?key=abc` 本判官命中而 `NON_SECRET_URL` 放行,`?x=sk-live-…` 反之,谁也不包含谁;存量域文档位(`mcp` 的 `transport.url` 等)读后者、不受本次影响,把两个问题合成一只定义是另一件事(本版不做)。
+  包里**没有**承载 A2A 对端 `url` / `cardUrl` 与搜索后端 `endpoint` 的 schema —— 这两座只有服务端的请求面,它们读这只判官即可。
+  三问 —— **谁需要**:客户端的云端腿 / 管理面等「别的消费方」(此前各自再判或不判);服务端(到货后退役本地那一份判官,拒形保留);**谁受伤**:无(新导出,既有导出行为不变);
+  **补偿**:凭据名表的第二份(服务端日志脱敏器的锚强度表)与本表须同键 —— 脱敏器的表键钉在 `CREDENTIAL_PARAM_NAMES` 上(`Record<CredentialParamName, …>` 的穷尽映射,加 / 删词不同步即编译红)是消费方的活。
+  钉:`test/url-credential-14.5.0.test.ts`(导出面 · 23 词逐字 · userinfo 三形 · 九词与整表 query / fragment · 读名同收方 · 判序 · 正控 · 不透明形 · 复合名今天不是凭据名〔🚧 held〕· 规则句逐字)。
+- **文件系统失败句的出路顺序(原子写器 / 目录迁移的 create · remove · replace 三句同一条)**。此前同一个 `EPERM` 在 create / remove 两句里仍以「make the directory writable」开头,目录模式已经可写时 chmod 无效,不可变标志只在句尾「may be」一提、不给清法;
+  replace 句则明说「clear an immutable flag」—— 三句三个序。现在三句只有一条顺序(`permissionWayOut`,句子的唯一铸点):`EPERM` ∧ 目录的权限位对本进程可写 ⇒ 真因只能是不可变标志(或粘滞位),**首选出路 = 清标志**(macOS `chflags nouchg`、Linux `chattr -i`),点名清谁,并说明 chmod 无效;
+  模式不可写,或没读过模式(注入的替身 I/O)⇒ 照旧先让目录可写,句尾提示「只读 / 不可变」的可能;`EROFS` 的出路不变(只读文件系统清不掉),create / remove 上的 `EACCES` 是纯权限位、不吃这条规则。
+  「目录权限位可写」这个事实由 Node 一侧读(`directoryAdmitsWrite`),经落点的可选格 `directoryWritable?` 递给铸点(缺席 = 没读过,按「不可写」走);**只有 create(`dir-create-temp`)与 remove 两个落点有这一格**。
+  **replace 句的改动面(如实)**:走到 `rename` 时临时文件刚在同一目录建成,「目录可写」是已证明的事实(铸点自己给,写器不对 rename 落点读模式位 —— 一个来源),所以 replace 句**不**走「先 chmod」那一支:
+  `EPERM` ⇒ 清标志先行,句子由 14.4.0 的「make the file replaceable — clear an immutable flag; in a sticky directory only the file's owner may replace it」换成「clear the immutable flag on the file or its directory (macOS: chflags nouchg; Linux: chattr -i) — the directory's permission bits already admit this process, so chmod will not help; in a sticky directory …」(多了命令与「chmod 无效」);
+  `EACCES` ⇒ 14.4.0 的原句逐字不变(文件向出路 + 粘滞目录一句,不说「make the directory writable」)。其余 errno 给 Node 自己的句子,与 14.4.0 同。
+  **另一处可见改动**:目录迁移的真 I/O 绑定 `nodeConfigDirectoryIo`(`./node`)的 `removeFile` 删失败,此前抛 `node:fs` 的原生错,现在抛 `FsFailure`(`message` 是铸点句 `cannot remove <file> from directory <dir> (<errno>): …`,`code` 照旧;`name` 由 `Error` 变 `FsFailure`;原生错对象上的 `errno` / `syscall` / `path` 不再在顶层,只在新加的 `cause` 上 —— 消费方若把 `${message} (${code})` 拼进日志会打两遍 errno,只拼 `message` 即可)—— 与原子写器同一个错型;
+  消费方若自己拼 `${message} (${code})` 会把 errno 打两遍(铸点句里已经带一遍),别再拼。
+  三问 —— **谁需要**:被不可变标志挡住写 / 删 / 换 `config.d` 文档的运维(句子第一眼就是对的命令);**谁受伤**:按失败句原文字面匹配的脚本(句子是文案,`code` / `cause` 不变,不承诺字面);自己拼 `message` + `code` 的删口消费方(见上);**补偿**:按 `code`(`EPERM` 等)分流,别拼 errno。
+  钉:`test/fs-failure-way-out-order-14.5.0.test.ts`(create / remove × 可写 / 不可写 / 未读模式 × `EPERM` / `EROFS` / `EACCES`;replace 的 `EPERM` / `EACCES` 整句逐字,以及「模式读口调成不可写,rename 失败句仍同句」的端到端一来源钉;模式读口 `directoryAdmitsWrite` 的属主 / 属组 / 其他三档与 root);`test/fs-failure-mint-12.0.1.test.ts` 的 rename 格。
+- **`GLOBAL_SCOPE` 的 JSDoc 改真(`./api/scopes`,文案)**。注释此前写「every token without a `scope` claim lives here」—— 与同一文件头 11.0.0 起的契约自相矛盾(缺 `scope` 声明的令牌被**拒**,不读成 `global`)。现在只剩「The reserved default scope. Always exists.」;
+  `docs/openapi-scopes.yaml` 无同句(其头注已写「缺声明 ⇒ 拒 401,不读成 global」)。三问 —— **谁需要**:读 `dist/api/scopes.d.ts` 接线的消费方(别照旧注释把缺声明令牌当 global);**谁受伤**:无(行为不变);**补偿**:无需。
+  钉:`test/scope-global-jsdoc-truth-14.5.0.test.ts`(紧邻 JSDoc 块不含旧话、含新句;旧话还原的变异读数 2 红)。
+
+## 14.4.0 — 2026-10-21 — minor:技能条目加两只可选工具名单 `SkillSpec.allowedTools?` / `disallowedTools?`(与引擎本地清单同名同形、逐条按作者所写承运;manifest 自动随到;读腿与兄弟列表同一条逐元素抢救律)
+
+> 档位(按发版纪律):**minor** —— 加性:`SkillSpec` 多两个可选键 `allowedTools` / `disallowedTools`;既有清单(不带这两个键)的解析结果、`/effective` 的 `skills[]`、一致性语料的读数逐字节不变。
+
+- **技能条目可以自带两只工具名单:`SkillSpec.allowedTools?` / `SkillSpec.disallowedTools?`(`string[]`,元素非空串)**。与引擎本地 `.sema/skills` 清单里同名两键同名同形(元素形与键名;读法见下) ——
+  此前中心分发的技能没有这两个位,引擎本地目录里写好的 `allowed-tools` / `disallowed-tools` 搬到中心就只剩正文,名单在 zod 的默认剥键下无声消失。
+  现在两只名单是 `SkillSpec` 的成员,**逐条按作者所写承运**:不去重、不排序、不规范化拼写,也不在这里判每一条是不是合法的规则拼写
+  (一条工具名、一段命名空间、一条带括号的规则各是什么意思,由消费方的授权判官在它那一处读;本包判的只有「非空字符串」)。
+  **消费方读法一句话**:**缺席 ⇒ 键不出现(不会被填成 `[]`);在场 ⇒ 整只数组原样交给消费方的判官**。`[]` 与缺席是两种承运形,读成什么由判官定 ——
+  引擎本地目录把空名单读作「未声明」,所以别把 `allowedTools: []` 实现成「一个工具都不许」。同一段名单文本在本地目录与中心分发两处被接受的范围也可能不同:
+  本地目录的装载器对不是规则拼写的条目会拒掉那条技能(不会以缩短的名单装上),本包照原样承运这样的条目、交给判官。
+  坏形(不是数组 / 元素不是字符串 / 元素是空串 / `null`)⇒ 写腿拒,拒句坐标点名到字段(`skills[i].allowedTools`),错在元素上时点名到元素(`skills[i].allowedTools[j]`);
+  `/effective` 的 manifest(`SkillsManifestSchema`、`toSkillsManifest`)本来就由 `SkillSpec` 派生(去掉 `content`、加 `contentHash`),所以两只名单自动随到 `skills[]`,没有第二份键表。
+  **读腿(`buildEffective` / `readEffectiveWire` 的逐条容错)里,两只名单是普通的嵌套集合,与 `scenarios` / `rosters` / MCP `allowTools` 走同一条既有律,没有为它们另立的读法**:
+  坏元素逐元素丢,告警 `entry-dropped` 的坐标到元素(`skills[i].disallowedTools[j]`),技能带着剩下的好元素存活;整只名单一个好元素都没有 ⇒ 不凭空造出 `[]`,
+  这条技能整条丢并告警 `entry-dropped`(坐标 `skills[i]`);若域里因此没有任何技能幸存(含它是唯一一条)⇒ 既有的零幸存者律:不发 `entry-dropped`,只发 `domain-defaulted`(`skills` 退成空清单)。
+  **如实披露的限度**:这条律落在拒绝名单上,意思是读腿上一只带坏元素的 `disallowedTools` 会被截短、技能照装(比作者所写更松),告警是响的;坏元素只可能来自写腿本会拒掉的文档
+  (手改的存量文件、别的写者),消费方可以把坐标落在 `…allowedTools[j]` / `…disallowedTools[j]` 的 `entry-dropped` 当硬停信号处理。纯值列表的抢救律(整只原子 vs 逐元素)在下一个 major 统一收口。
+  三问 —— **谁需要**:把引擎本地技能目录里的 `allowed-tools` / `disallowed-tools` 搬到中心分发的人(管理面写、服务端经 `/effective` 分发、worker 读);
+  **谁受伤**:① 不升级的**读取方** —— 旧读者(≤14.3.0 的 manifest 读者)不认这两个键,zod 默认剥掉,manifest 路径上没有剥键告警,于是名单在旧读者那里静默丢未知位
+  (`disallowedTools` 丢了 = 比作者所写更松);② **升了包的服务端与 client-core 的云端腿也还拿不到名单** —— 两处都是从 manifest 条目按手写键(name / description / content)建技能,没有这两个键;两位过境随各自的后续版本到货,
+  到货前,走这两条路的 worker 上两位无效;③ 存量文档里**已经有同名键但不是数组形**的技能(手写 `config.d/skills.json` 照搬引擎 frontmatter 的逗号串形
+  `allowedTools: "Read, Grep"`):此前这个键是未知键,技能存活并发 `unknown-keys-dropped`;现在这个键有了形状,不是数组 ⇒ 这条技能读腿上整条丢(`entry-dropped`,域里没有任何技能幸存则 `domain-defaulted`),写腿拒;
+  **补偿**:管理面写入名单之前,先确认读这条链的每一跳都已升级并接入这两个键 —— 升级顺序就是旋钮,本包不另设开关;存量文档先把同名键改成数组形或去掉。
+  钉:`test/skill-tool-lists-14.4.0.test.ts`(域形与 manifest 往返含空数组与缺席两形 · 重复 / 乱序 / 不配对拼写原样 · 缺席不物化键 · 域读与 `parseDomainLoud` 同一份零告警 ·
+  `buildEffective` → `resolveEffectiveForWorker` → `readEffectiveWire` 端到端 · 七种坏形 × 域形 / manifest 两条判据的坐标 · 读腿两条逐元素 ⇒ 告警到元素 · 与 `scenarios` 同一条律 ·
+  整只名单全坏 ⇒ 整条丢、域里无幸存者(唯一一条或每条都坏)⇒ `domain-defaulted` · 三份导出 schema 转 JSON Schema 两只名单零非标关键字)。
 
 ## 14.3.0 — 2026-10-21 — minor:信任阶梯词表做纯常量 `MIN_TRUST_WORDS`(`MinTrust` 由它派生;`trustRank` / `isAtLeast` 闭包零 zod,整函数抄走的消费方只登记一只全局)
 

package/README.md

@@ -92,6 +92,12 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   覆盖面要迁 `runtime` 就得把 `governance` 与 `limits` 一并放进来(迁出的旧值要写那两份,不能覆盖面外去写;缺了就按 `partial` 拒迁 `runtime`、一字不写)。
   `io` 注入 `{ readDir, readFile, writeFileAtomic, removeFile }`,真绑定是 `nodeConfigDirectoryIo`(`node:fs` + 本包唯一的原子写器与它的模式表)。返回一个闭集
   (`unreadable` / `no-documents` / `refused` / `noop` / `pending` / `applied`),调用方穷举;写盘阶段的 I/O 错误原样抛出(已写完的留在新位上,再跑一次幂等收尾)。
+- **同步单口**(`./node`,14.5.0):`migrateConfigDocuments(docs, { documents })` —— 手里已经有存量文档原文(文档名 → 文档,例:一层 `settings` 里的 models 域)、不经目录的调用方,
+  「迁 → 整域终判」一次调用、无 io;与目录形共用同一个内核(读目录之后的那一段语义只此一处),`documents` 的律逐字同。返回同一个闭集的无 io 形(`unreadable`〔覆盖面内某份文档不是 JSON 对象,不抛〕/ `no-documents` /
+  `refused`〔`docs` 仍交回迁移后的那一份〕/ `noop`〔`docs` 是入参的同一引用〕/ `migrated`〔`docs` + `applied` + `changed` + `removed`〕),调用方穷举;入参不被改,重跑 `docs` ⇒ `noop`。
+  一层一次调用:层序 / 覆盖 / 托管锁的合并读法不在这里,也别自己再把 `migrateStoredDocuments` 与 `parseDomain` 按这个顺序组装一遍。
+- **URL 内嵌凭据判官**(包根,14.5.0):`findUrlCredential(raw)` 判一个 URL 是否带凭据 —— userinfo,或 query / fragment 里名字整名在凭据名表 `CREDENTIAL_PARAM_NAMES` 上的参数(`URLSearchParams` 解一次码、ASCII 大小写不敏感);
+  首个命中 `{ reason: "url_userinfo" }` / `{ reason: "url_credential_param", at, name }`(`URL_CREDENTIAL_REASONS` 闭集两词),值从不进答案,不透明形 ⇒ `undefined`。判官只判有没有:新提交门拒、续跑重放存量体的腿不拒这类载体律是座位的事,拒体的形也是座位的铸点。
 - **迁什么**(七条,`ONE_TIME_MIGRATIONS` 每行写着改写规则、删法、删后由谁接住):退役 `runtime` 域(治理三闸 → `governance`、五个限额键 → `limits`)·
   hosts 超界 · 调度店 durable 键(读时改写,下一个写者落盘)· workers 6.x 行 · 模型钥匙双设 · `atModelAllowlist` → `atMention` · URL fragment。
 - **什么时候删**:每条的窗 = 11.0.0 发布日 + 30 天,窗关之后的那个 major 整族删(删法与删后的响亮臂见登记表那一行);本包的到期门到点即红。
@@ -645,7 +651,7 @@ defaults. Each `config.d/<domain>.json` is exactly that domain's zod object.
   minor,patch 只装 additive/修 bug/文档」。0.7.1(2026-07-10)曾携带两件预协调 BREAKING(撤 governance
   effective 双写镜像、撤 QuotaLease 0.5 `tokens` 别名 shim),名义上违反该条;当时下游(web-admin/service
   1.150.0)均已显式迁移、实际破坏面为零,PM 拍板不重发 0.8.0(纯扰动)。该例外随 1.x 政策一并归档。
-- 发布(单腿 npmjs,内网腿已废止):`npm run publish:npm`;发后必须 curl 直打 npmjs 复验 shasum。
+- 发布(单腿 npmjs,内网腿已废止):在要发的提交上打 tag `v<version>`,再 `bash scripts/publish-local.sh <version>`(先加 `--dry-run` 跑一遍:跑到包清单门止,不发、不要令牌)。构建与全量测试在远端构建机上跑(`GATE_HOST`),本机只发;令牌只从环境 `NPM_TOKEN` 读。发后复验由脚本自己做 —— curl 直打 npmjs 回读 shasum、tarball 字节与 gitHead,对不上即红。
 
 ## 贡献指引
 

package/conformance/VERSION

@@ -1 +1 @@
-14.3.0
+14.5.0

package/dist/api/scopes.d.ts

@@ -45,7 +45,7 @@
  */
 import { z } from "zod";
 import { type UserRole } from "../config-fns.js";
-/** The reserved default scope. Always exists; every token without a `scope` claim lives here. */
+/** The reserved default scope. Always exists. */
 export declare const GLOBAL_SCOPE = "global";
 /** Scope ids that can never be created (or deleted) through the API. */
 export declare const RESERVED_SCOPE_IDS: readonly ["global"];

package/dist/api/scopes.js

@@ -49,7 +49,7 @@ import { buildQuotedIssue, fixed } from "../quoted-issue.js";
 import { USER_ROLES } from "../config-fns.js";
 import { ACCESS_TOKEN_TTL_SECONDS } from "./auth.js";
 // ── constants ────────────────────────────────────────────────────────────────────────────────────────────
-/** The reserved default scope. Always exists; every token without a `scope` claim lives here. */
+/** The reserved default scope. Always exists. */
 export const GLOBAL_SCOPE = "global";
 /** Scope ids that can never be created (or deleted) through the API. */
 export const RESERVED_SCOPE_IDS = [GLOBAL_SCOPE];

package/dist/atomic-write.d.ts

@@ -18,3 +18,14 @@ export declare function danglingSymlinkSentence(link: string, pointsAt: string):
 export declare function resolveSymlinkTarget(target: string): string;
 /** 原子写 `text`(UTF-8)到 `target`(符号链接则写到它指向的真文件,见文件头);模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
 export declare function writeFileAtomic(target: string, text: string, kind: AtomicFileClass): void;
+/**
+ * **目录的权限位对本进程是否可写** —— 文件系统失败句的出路顺序要的那一个事实(`./fs-failure` 的铸点是纯函数、没有 `node:`,读模式的事在这里,事实经落点的 `directoryWritable` 递过去;
+ * 写盘的模式判与模式字面只在本文件一处,所以目录迁移的删除口 `./config-dir-io` 也从这里取)。
+ *
+ * 为什么不是 `access(2)`:不可变标志(macOS `chflags uchg` / Linux `chattr +i`)下 `access(W_OK)` 同样报 `EPERM`,分不出「模式不让写」与「标志不让写」;
+ * 这里只看**权限位**:目录对本进程的属主 / 属组 / 其他三档里适用的那一档,删建目录项要 w + x 两位都在。root(有效 uid 0)不受权限位约束 ⇒ 恒真
+ * (root 撞 `EPERM` 的常见原因恰恰是不可变标志)。没有 POSIX 身份(Windows)/ 读不到模式 ⇒ 假 —— 不替没读到的事实说「可写」。ACL 不看。
+ *
+ * 入参 `dir` 是已解析到真目录的路径;返回目录的权限位是否让本进程能增删其中的目录项。
+ */
+export declare function directoryAdmitsWrite(dir: string): boolean;

package/dist/atomic-write.js

@@ -23,7 +23,8 @@
  * ## 写失败(12.0.0;句子归文件系统失败句的唯一铸点)
  * 两步各一句({@link FsFailure},句子在 `./fs-failure`):临时文件建不出 ⇒ 「cannot write into directory <dir> (<errno>): …」(点名目录 —— 目录不可写时
  * 文件本身没错);`rename` 失败 ⇒ 「cannot replace <file> (<errno>): …」(点名真文件)。认得的 errno 给对应出路,别的给 Node 自己的句子;`code` / `cause` 留着。
- * 可写目录里的只读文件照常写得进(`rename` 换的是目录项)。
+ * 可写目录里的只读文件照常写得进(`rename` 换的是目录项)。权限类 errno 的出路顺序要一个只有 Node 一侧读得到的事实 —— 失败那一刻目录的权限位对本进程是否可写({@link directoryAdmitsWrite},模式判在本文件、与模式表同处),
+ * 写器在建临时文件那一步读了经落点递给铸点(`EPERM` ∧ 可写 ⇒ 真因是不可变标志,首选出路是清标志;否则先 chmod);`rename` 那一步不读 —— 临时文件刚在同目录建成,可写是已证明的事实,铸点自己给。
  */
 import { randomBytes } from "node:crypto";
 import { chmodSync, lstatSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -102,6 +103,35 @@ export function writeFileAtomic(target, text, kind) {
         catch {
             /* 临时文件没建成:没什么可清 */
         }
-        throw new FsFailure(site, e); // the sentence names the step that failed and its way out (`./fs-failure`, the one mint)
+        // the sentence names the step that failed and its way out (`./fs-failure`, the one mint); the way-out order needs one Node-side fact — do the directory's mode bits admit this process —
+        // read only at the create step: by the time `rename` runs the temporary file has just been created in the same directory, so "writable" is proven there and the mint says so itself
+        throw new FsFailure(site.landing === "dir-create-temp" ? { ...site, directoryWritable: directoryAdmitsWrite(dir) } : site, e);
     }
 }
+/**
+ * **目录的权限位对本进程是否可写** —— 文件系统失败句的出路顺序要的那一个事实(`./fs-failure` 的铸点是纯函数、没有 `node:`,读模式的事在这里,事实经落点的 `directoryWritable` 递过去;
+ * 写盘的模式判与模式字面只在本文件一处,所以目录迁移的删除口 `./config-dir-io` 也从这里取)。
+ *
+ * 为什么不是 `access(2)`:不可变标志(macOS `chflags uchg` / Linux `chattr +i`)下 `access(W_OK)` 同样报 `EPERM`,分不出「模式不让写」与「标志不让写」;
+ * 这里只看**权限位**:目录对本进程的属主 / 属组 / 其他三档里适用的那一档,删建目录项要 w + x 两位都在。root(有效 uid 0)不受权限位约束 ⇒ 恒真
+ * (root 撞 `EPERM` 的常见原因恰恰是不可变标志)。没有 POSIX 身份(Windows)/ 读不到模式 ⇒ 假 —— 不替没读到的事实说「可写」。ACL 不看。
+ *
+ * 入参 `dir` 是已解析到真目录的路径;返回目录的权限位是否让本进程能增删其中的目录项。
+ */
+export function directoryAdmitsWrite(dir) {
+    if (typeof process.geteuid !== "function" || typeof process.getegid !== "function")
+        return false;
+    let st;
+    try {
+        st = statSync(dir);
+    }
+    catch {
+        return false;
+    }
+    const euid = process.geteuid();
+    if (euid === 0)
+        return true;
+    const group = st.gid === process.getegid() || (typeof process.getgroups === "function" && process.getgroups().includes(st.gid));
+    const shift = st.uid === euid ? 6 : group ? 3 : 0;
+    return ((st.mode >> shift) & 0o3) === 0o3;
+}

package/dist/config-d-file.d.ts

@@ -14,6 +14,10 @@ export type ConfigDDocumentName = DomainName | RetiredDomainName | typeof REMOTE
  *  不是对象 ⇒ 抛,每种一句(点名 `file` —— 调用方读的那份文件的真实路径 —— 与形,句尾 {@link documentWayOut})。读盘的入口(`readConfigDFile`、`loadRemoteExec`)
  *  与自己读文本的命令行(`migrate`)都过它 —— 一种坏形一句话,不论是哪份文档。 */
 export declare function judgeConfigDText(name: ConfigDDocumentName, text: string, file: string): Record<string, unknown>;
+/** 一份**已解析的**存量文档在场时的值(同步口 `migrateConfigDocuments` 收的是各层的文档原文,不是文件文本)→ 它自己:一个 JSON 对象 ⇒ 它;`null` / 数组 / 数 / 串 / 布尔 /
+ *  非朴素对象 ⇒ 抛。{@link judgeConfigDText} 的最后一道判就是这只(文本解析出来之后过它),所以「不是对象」一种坏形一句话,不论文档是从文件文本来的还是调用方直接给的;
+ *  `label` = 句首的称呼(文本路径给文件的真实路径,值路径给 `the <名> document`)。 */
+export declare function judgeConfigDValue(name: ConfigDDocumentName, value: unknown, label: string): Record<string, unknown>;
 /** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
 export declare function readConfigDFile(root: string, name: DomainName | RetiredDomainName): Promise<Record<string, unknown> | undefined>;
 /**

package/dist/config-d-file.js

@@ -12,6 +12,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { refuseRetiredDomain, sanitizeZodError } from "./config-fns.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
 /** 一份 `config.d` 文档写盘的**文本形** —— 两格缩进的 JSON 加一个换行。写域文件(`writeDomainFile`)、写 `remote-exec.json`(`writeRemoteExec`)与目录迁移写回
@@ -57,11 +58,17 @@ export function judgeConfigDText(name, text, file) {
     catch {
         throw new Error(`invalid JSON in ${file} — ${documentWayOut(name)}`); // sanitized: never echo the raw file text into the error
     }
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        const kind = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
-        throw new Error(`${file} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`);
+    return judgeConfigDValue(name, parsed, file);
+}
+/** 一份**已解析的**存量文档在场时的值(同步口 `migrateConfigDocuments` 收的是各层的文档原文,不是文件文本)→ 它自己:一个 JSON 对象 ⇒ 它;`null` / 数组 / 数 / 串 / 布尔 /
+ *  非朴素对象 ⇒ 抛。{@link judgeConfigDText} 的最后一道判就是这只(文本解析出来之后过它),所以「不是对象」一种坏形一句话,不论文档是从文件文本来的还是调用方直接给的;
+ *  `label` = 句首的称呼(文本路径给文件的真实路径,值路径给 `the <名> document`)。 */
+export function judgeConfigDValue(name, value, label) {
+    if (!isPlainJsonObject(value)) {
+        const kind = value === null ? "null" : Array.isArray(value) ? "array" : typeof value === "object" ? "non-plain object" : typeof value;
+        throw new Error(`${label} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`);
     }
-    return parsed;
+    return value;
 }
 /** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
 export async function readConfigDFile(root, name) {

package/dist/config-dir-io.js

@@ -5,10 +5,20 @@
  * 命令行入口与引擎起服的目录迁移注入同一份,写法与文件模式因此只在原子写器那一处定。
  */
 import { readdir, readFile, unlink } from "node:fs/promises";
-import { resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
+import { dirname } from "node:path";
+import { directoryAdmitsWrite, resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
+import { FsFailure } from "./fs-failure.js";
 export const nodeConfigDirectoryIo = {
     readDir: async (path) => readdir(resolveSymlinkTarget(path)),
     readFile: async (path) => readFile(resolveSymlinkTarget(path), "utf8"),
     writeFileAtomic: async (path, text) => writeFileAtomic(path, text, "config-document"), // the files this migration writes are config.d domain documents
-    removeFile: (path) => unlink(path),
+    // a failed removal is minted here, where the directory's mode can be read (`./fs-failure` is pure): the same `FsFailure` the atomic writer throws, so the command line prints it as is
+    removeFile: async (file) => {
+        try {
+            await unlink(file);
+        }
+        catch (e) {
+            throw new FsFailure({ landing: "remove", path: file, directoryWritable: directoryAdmitsWrite(dirname(file)) }, e);
+        }
+    },
 };

package/dist/config-dir-migration.d.ts

@@ -49,6 +49,45 @@ export interface MigrateConfigDirectoryOptions {
     /** 只判、不写:有改动且整域判得过 ⇒ `pending`。默认 `false`。 */
     readonly check?: boolean;
 }
+export interface MigrateConfigDocumentsOptions {
+    /** 覆盖面:调用方读的文档名集 —— 与 {@link MigrateConfigDirectoryOptions.documents} 同一个词、同一个律(覆盖面内没给的文档 = 从未设过;覆盖面外的键不读、不判、不进结果;拼错的名字 ⇒ 抛 `TypeError`)。 */
+    readonly documents: readonly ConfigDirectoryDocument[];
+}
+/**
+ * 同步口的结果 —— {@link ConfigDirectoryMigration} 的无 io 形,**同一个闭集的词**,调用方穷举:
+ *  · `unreadable`  —— 覆盖面内某份文档不是 JSON 对象(`null` / 数组 / 数 / 串 / 布尔):`document` 点名是哪一份,`reason` 与坏文件同一句式。不抛、不迁(其余文档是别的调用的事:一层一次调用)。
+ *  · `no-documents`—— 覆盖面内一份文档都没给(缺席与 `undefined` 同)。
+ *  · `refused`     —— 迁移步拒(收据 `refused`)**或**改过的文档整域读不进(整域终判)。`docs` 仍交回迁移后的那一份(迁得动的坐标改新形、迁不动的原样 ——
+ *                     写手要的是这一份;落不落盘、引擎认不认是 `kind` 的事:`refused` ⇒ 引擎同样不写回、整域落缺省;反向不成立 —— 引擎对整个目录一判,别的文档被拒也会让整目录不写)。
+ *  · `noop`        —— 零改动:`docs` 里每份文档都是入参里的**同一引用**;没改的文档不终判(读不读得进是读者的事,与目录形同一律)。
+ *  · `migrated`    —— 有改动、整域判得过:`docs` 是迁移后的覆盖面内文档全集,`changed` = 改过 / 新建的文档名,`removed` = 被移除的(retired 域),`applied` = 逐条收据。
+ * `read` = 覆盖面内在场的文档名(升序)。入参从不被改;重跑 `docs` ⇒ `noop`。
+ */
+export type ConfigDocumentsMigration = {
+    readonly kind: "unreadable";
+    readonly document: ConfigDirectoryDocument;
+    readonly reason: string;
+} | {
+    readonly kind: "no-documents";
+} | {
+    readonly kind: "refused";
+    readonly read: readonly string[];
+    readonly docs: Readonly<Record<string, unknown>>;
+    readonly applied: readonly MigrationReceipt[];
+    readonly refused: readonly ConfigDirectoryRefusal[];
+    readonly why: string;
+} | {
+    readonly kind: "noop";
+    readonly read: readonly string[];
+    readonly docs: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "migrated";
+    readonly read: readonly string[];
+    readonly docs: Readonly<Record<string, unknown>>;
+    readonly applied: readonly MigrationReceipt[];
+    readonly changed: readonly string[];
+    readonly removed: readonly string[];
+};
 /** 目录迁移能读写的文档名:配置域、retired 域、`remote-exec`(`config.d/remote-exec.json`)—— 就是 `config.d` 里能放的文档名。 */
 export type ConfigDirectoryDocument = ConfigDDocumentName;
 /** 目录加文件名(目录尾部的分隔符折掉)。包内私有(不进 `./node`)。 */
@@ -59,6 +98,11 @@ type RefusedReceipt = Extract<MigrationReceipt, {
 /** 一张收据的出门形(坐标只点名、不带值):`refused` 带 `reason`(= {@link ConfigDirectoryRefusal} 的形),`moved` 带 `to`。包内私有 —— 命令行报告用它渲染 `applied`。 */
 export declare function reportReceipt(r: RefusedReceipt): ConfigDirectoryRefusal;
 export declare function reportReceipt(r: MigrationReceipt): Record<string, unknown>;
+/**
+ * 对一组**已有的**存量文档(`docs`:文档名 → 文档,例:一层 `settings` 里的 `models` 域原文)跑一次一次性迁移 + 整域终判 —— 同步、无 io;语义与结果见文件头「同步口」与 {@link ConfigDocumentsMigration}。
+ * 覆盖面外的键不读、不判、不进结果;覆盖面内在场(非 `undefined`)的文档必须是 JSON 对象,否则回 `unreadable`(不抛)。`docs` 不是对象 / 覆盖面拼错 ⇒ `TypeError`(调用方的错,不是数据的错)。
+ */
+export declare function migrateConfigDocuments(docs: Readonly<Partial<Record<ConfigDirectoryDocument, unknown>>>, opts: MigrateConfigDocumentsOptions): ConfigDocumentsMigration;
 /**
  * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
  */

package/dist/config-dir-migration.js

@@ -20,10 +20,16 @@
  *  · `pending`     —— `check: true` 且有改动、整域判得过:一字不写。
  *  · `applied`     —— 已写回:先写改过 / 新建的文档,最后删被移除的 retired 域文件 —— 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
  * 写盘阶段的 I/O 错误**原样抛出**(不吞、不改写):已写完的文档留在新位上,再跑一次幂等收尾。
+ *
+ * ## 同步口 {@link migrateConfigDocuments}(14.5.0)
+ * 「迁 → 整域终判」那一段就是一只同步函数:入参是调用方手里**已有**的存量文档原文(域名 → 文档),出参是同一个闭集的无 io 形 —— 迁移后的文档、逐条收据、
+ * 整域终判的拒。目录形读完目录后调的就是它的内核(语义只此一处);不经目录的调用方(例:命令行壳按层读 `settings` 文档)调它,不再自己把
+ * `migrateStoredDocuments`(纯改写)与 `parseDomain`(整域终判)按「迁移步拒 → 无改动 ⇒ noop → 改过的文档整域终判」的序再组装一遍。
+ * 覆盖面、`coverage` 的判、「没改的文档不判」「迁移不许越过覆盖面去写」与目录形逐字同;层的合并(层序 / 覆盖 / 托管锁)不在这里 —— 一层一次调用。
  */
 import { z } from "zod";
 import { formatConfigPath, parseDomain } from "./config-fns.js";
-import { configDDocumentText, judgeConfigDText, parseRemoteExecDocument } from "./config-d-file.js";
+import { configDDocumentText, judgeConfigDText, judgeConfigDValue, parseRemoteExecDocument } from "./config-d-file.js";
 import { fsFailureMessage } from "./fs-failure.js";
 import { migrateStoredDocuments } from "./one-time-migrations.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
@@ -94,16 +100,78 @@ function verdictOf(input, migrated, receipts) {
     return { kind: "changes" };
 }
 const messageOf = (err) => (err instanceof Error ? err.message : String(err));
-/**
- * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
- */
-export async function migrateConfigDirectory(dir, opts) {
+/** 覆盖面的名字集(校验在这一处):拼错的名字 ⇒ `TypeError`,不让它悄悄变成「什么都没覆盖」。 */
+function coveredDocuments(caller, documents) {
     const covered = new Set();
-    for (const name of opts.documents) {
+    for (const name of documents) {
         if (!isConfigDirectoryDocument(name))
-            throw new TypeError(`migrateConfigDirectory: "${String(name)}" is not a config domain, a retired domain or remote-exec — the coverage names the documents the caller reads`);
+            throw new TypeError(`${caller}: "${String(name)}" is not a config domain, a retired domain or remote-exec — the coverage names the documents the caller reads`);
         covered.add(name);
     }
+    return covered;
+}
+/**
+ * 「迁 → 整域终判」的内核(语义只此一处):`docs` = 覆盖面内**在场且已判过形**的文档(都是 JSON 对象),`covered` = 覆盖面。目录形读完目录后调它,同步口 {@link migrateConfigDocuments} 判完形后调它。
+ */
+function migrateCovered(caller, docs, covered) {
+    const read = Object.keys(docs);
+    if (read.length === 0)
+        return { kind: "no-documents" };
+    // 目录/文档集是不是「一个 scope 的全集」只看一件事:SS-M1 要写的目标域是不是都在覆盖面里(见文件头);不是 ⇒ partial,runtime 的迁移被它自己拒掉。
+    const coverage = RUNTIME_LIFT_TARGETS.every((target) => covered.has(target)) ? "scope" : "partial";
+    const m = migrateStoredDocuments(docs, { coverage });
+    const outside = Object.keys(m.docs).filter((name) => !Object.prototype.hasOwnProperty.call(docs, name) && !covered.has(name));
+    if (outside.length > 0) {
+        // 守卫:迁移新建了覆盖面外的文档。那份文档调用方没读过,「从未设过」只对覆盖面内成立 —— 写下去会覆盖它。今天不会发生(见文件头);发生了就是迁移步的写入域变了,这里先红。
+        throw new Error(`${caller}: the migration produced document(s) outside the coverage (${outside.join(", ")}) — refusing to write files the caller did not read`);
+    }
+    const applied = m.receipts.filter((r) => r.appliedAs !== "refused");
+    const verdict = verdictOf(docs, m.docs, m.receipts);
+    switch (verdict.kind) {
+        case "refused":
+            return { kind: "refused", read, docs: m.docs, applied, refused: verdict.refused, why: verdict.why };
+        case "noop":
+            return { kind: "noop", read, docs: m.docs };
+        case "changes":
+            break;
+        default: {
+            const unhandled = verdict;
+            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+        }
+    }
+    const changed = Object.entries(m.docs)
+        .filter(([name, doc]) => !(Object.prototype.hasOwnProperty.call(docs, name) && docs[name] === doc))
+        .map(([name]) => name);
+    const removed = Object.keys(docs).filter((name) => !Object.prototype.hasOwnProperty.call(m.docs, name));
+    return { kind: "migrated", read, docs: m.docs, applied, changed, removed };
+}
+/**
+ * 对一组**已有的**存量文档(`docs`:文档名 → 文档,例:一层 `settings` 里的 `models` 域原文)跑一次一次性迁移 + 整域终判 —— 同步、无 io;语义与结果见文件头「同步口」与 {@link ConfigDocumentsMigration}。
+ * 覆盖面外的键不读、不判、不进结果;覆盖面内在场(非 `undefined`)的文档必须是 JSON 对象,否则回 `unreadable`(不抛)。`docs` 不是对象 / 覆盖面拼错 ⇒ `TypeError`(调用方的错,不是数据的错)。
+ */
+export function migrateConfigDocuments(docs, opts) {
+    if (docs === null || typeof docs !== "object" || Array.isArray(docs))
+        throw new TypeError("migrateConfigDocuments: `docs` must be a { document: value } object");
+    const covered = coveredDocuments("migrateConfigDocuments", opts.documents);
+    const present = {};
+    for (const name of [...covered].sort()) {
+        const value = Object.prototype.hasOwnProperty.call(docs, name) ? docs[name] : undefined;
+        if (value === undefined)
+            continue;
+        try {
+            present[name] = judgeConfigDValue(name, value, `the ${name} document`); // the one config.d "is it an object" judge (the file-text path ends in the same one)
+        }
+        catch (err) {
+            return { kind: "unreadable", document: name, reason: messageOf(err) };
+        }
+    }
+    return migrateCovered("migrateConfigDocuments", present, covered);
+}
+/**
+ * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
+ */
+export async function migrateConfigDirectory(dir, opts) {
+    const covered = coveredDocuments("migrateConfigDirectory", opts.documents);
     const { io } = opts;
     let names;
     try {
@@ -117,7 +185,7 @@ export async function migrateConfigDirectory(dir, opts) {
         if (name.startsWith(".") || !name.endsWith(".json"))
             continue;
         const base = name.slice(0, -".json".length);
-        if (!covered.has(base) || !isConfigDirectoryDocument(base))
+        if (!isConfigDirectoryDocument(base) || !covered.has(base))
             continue;
         let text;
         const file = joinDirPath(dir, name);
@@ -134,46 +202,32 @@ export async function migrateConfigDirectory(dir, opts) {
             return { kind: "unreadable", reason: messageOf(err) };
         }
     }
-    const read = Object.keys(docs);
-    if (read.length === 0)
-        return { kind: "no-documents", entries: names };
-    // 目录是不是「一个 scope 的全集」只看一件事:SS-M1 要写的目标域是不是都在覆盖面里(见文件头);不是 ⇒ partial,runtime 的迁移被它自己拒掉。
-    const coverage = RUNTIME_LIFT_TARGETS.every((target) => covered.has(target)) ? "scope" : "partial";
-    const m = migrateStoredDocuments(docs, { coverage });
-    const outside = Object.keys(m.docs).filter((name) => !Object.prototype.hasOwnProperty.call(docs, name) && !covered.has(name));
-    if (outside.length > 0) {
-        // 守卫:迁移新建了覆盖面外的文档。那份文件调用方没读过,「从未设过」只对覆盖面内成立 —— 写下去会覆盖它。今天不会发生(见文件头);发生了就是迁移步的写入域变了,这里先红。
-        throw new Error(`migrateConfigDirectory: the migration produced document(s) outside the coverage (${outside.join(", ")}) — refusing to write files the caller did not read`);
-    }
-    const applied = m.receipts.filter((r) => r.appliedAs !== "refused");
-    const verdict = verdictOf(docs, m.docs, m.receipts);
-    switch (verdict.kind) {
+    const m = migrateCovered("migrateConfigDirectory", docs, covered);
+    switch (m.kind) {
+        case "no-documents":
+            return { kind: "no-documents", entries: names };
         case "refused":
-            return { kind: "refused", read, applied, refused: verdict.refused, why: verdict.why };
+            return { kind: "refused", read: m.read, applied: m.applied, refused: m.refused, why: m.why };
         case "noop":
-            return { kind: "noop", read };
-        case "changes":
+            return { kind: "noop", read: m.read };
+        case "migrated":
             break;
         default: {
-            const unhandled = verdict;
-            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+            const unhandled = m;
+            throw new Error(`settings-schema: unhandled migration ${JSON.stringify(unhandled)}`);
         }
     }
     if (opts.check === true)
-        return { kind: "pending", read, applied };
+        return { kind: "pending", read: m.read, applied: m.applied };
     const written = [];
     const removed = [];
-    for (const [name, doc] of Object.entries(m.docs)) {
-        if (Object.prototype.hasOwnProperty.call(docs, name) && docs[name] === doc)
-            continue;
-        await io.writeFileAtomic(joinDirPath(dir, `${name}.json`), configDDocumentText(doc)); // the one config.d document text (writeDomainFile / writeRemoteExec write the same)
+    for (const name of m.changed) {
+        await io.writeFileAtomic(joinDirPath(dir, `${name}.json`), configDDocumentText(m.docs[name])); // the one config.d document text (writeDomainFile / writeRemoteExec write the same)
         written.push(`${name}.json`);
     }
-    for (const name of Object.keys(docs)) {
-        if (Object.prototype.hasOwnProperty.call(m.docs, name))
-            continue;
+    for (const name of m.removed) {
         await io.removeFile(joinDirPath(dir, `${name}.json`));
         removed.push(`${name}.json`);
     }
-    return { kind: "applied", read, applied, written, removed };
+    return { kind: "applied", read: m.read, applied: m.applied, written, removed };
 }

package/dist/config-fns.js

@@ -17,6 +17,7 @@
 // its entry collections. zod is this package's one runtime dependency, so this costs nothing new.
 import { z } from "zod";
 import { MODEL_ENTRY_REFUSAL_CODES, ModelRefusalsWire } from "./fleet.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { carriesUserinfo, secretScanForms } from "./secret-scan.js"; // package-private normalization (both scanners read it) + the userinfo judgement (not in the barrel)
 import { sha256Hex } from "./sha256.js";
 import { unwrapSchema } from "./zod-unwrap.js"; // package-private: the ONE reading of zod's wrapper layers (salvage + the one-time migrations share it)
@@ -731,13 +732,6 @@ export function isReservedExtensionKey(domain, parent, key) {
     const rules = EXTENSION_NAMESPACES[domain];
     return rules !== undefined && rules.some((r) => r.at.length === parent.length && r.at.every((seg, i) => (seg === ANY_INDEX ? typeof parent[i] === "number" : seg === parent[i])) && r.key.test(key));
 }
-/** 纯 JSON 对象(不是数组、不是类实例/带原型的东西)——只对这种做键集对比,别的形状交给 parse 判。 */
-function isPlainJsonObject(v) {
-    if (v === null || typeof v !== "object" || Array.isArray(v))
-        return false;
-    const proto = Object.getPrototypeOf(v);
-    return proto === Object.prototype || proto === null;
-}
 function collectDropped(domain, raw, parsed, prefix, depth, acc) {
     if (depth > DROP_SCAN_MAX_DEPTH)
         return;

package/dist/fs-failure.d.ts

@@ -12,22 +12,32 @@
  * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
  *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
  *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
- * 目录落点(`dir-create-temp` / `remove`)的 `EPERM` / `EROFS` 出路句尾加「目录可能是只读 / 不可变(chflags / chattr)」—— 改权限位修不好的那两种。
+ * 三个落点(`dir-create-temp` / `remove` / `rename`)的权限类出路走**同一条顺序**(`rename` 的「可写」是已证明的事实,见下)({@link permissionWayOut}):同一个 `EPERM` 既可能是目录模式不让写,也可能是不可变标志
+ * (macOS `chflags uchg` / Linux `chattr +i`)—— 铸点是纯函数,分不清,但调用方在 Node 一侧能读目录模式,把「模式对本进程可写」这个事实经落点的 `directoryWritable` 递进来:
+ * `EPERM` ∧ 可写 ⇒ chmod 已经没用,首选出路 = 清标志(`chflags nouchg` / `chattr -i`);否则(模式不可写,或调用方没读过模式 —— 注入的替身 I/O 抛的错,包看不到它背后)⇒ 先 chmod,
+ * 句尾提示「只读 / 不可变」的可能。`EROFS` 的出路不变(只读文件系统清不掉),`EACCES` 是纯权限位,不吃这条规则。
+ * `rename` 落点的「可写」不是读出来的而是已证明的(走到 rename 时临时文件刚在同一目录建成):`EPERM` 恒为清标志先行,`EACCES` 保留 14.4.0 的文件向原句("make the file replaceable — clear an immutable flag"),
+ * 两者句尾都是粘滞目录一句,都不说「make the directory writable」。
  *
  * 原子写器抛 {@link FsFailure}(句子在 `message`,`code` 照抄底层 errno,原错误在 `cause`);它在写器内部已经按更细的落点铸过句子,
  * 命令行 / 迁移用 {@link fsFailureMessage} 取句 —— 已经是 {@link FsFailure} 的原样用,否则按它所在的口铸。
  */
 /** 一次失败发生的地方(闭集):落点加那一步交给操作系统的真实路径(`dir-create-temp` 是要建的临时文件,点名的目录是它的父目录;`rename` 是被盖过的真文件;
- *  `remove` / `write` 是那份文件;`read` 是读的目录或文件)。 */
+ *  `remove` / `write` 是那份文件;`read` 是读的目录或文件)。
+ *  `directoryWritable`(只有 `dir-create-temp` / `remove` 两个落点有)—— 失败那一刻,目录的权限位对本进程是否可写(Node 一侧读的事实,见 `./atomic-write` 的 `directoryAdmitsWrite`);
+ *  缺席 = 没读过(注入的替身 I/O),出路顺序按「不可写」走。`rename` 落点没有这一格:走到 rename 时临时文件刚在同一目录建成,目录可写是已证明的事实,由铸点按 {@link RENAME_DIRECTORY_WRITABLE} 给出。
+ */
 export type FsFailureSite = {
     readonly landing: "dir-create-temp";
     readonly path: string;
+    readonly directoryWritable?: boolean;
 } | {
     readonly landing: "rename";
     readonly path: string;
 } | {
     readonly landing: "remove";
     readonly path: string;
+    readonly directoryWritable?: boolean;
 } | {
     readonly landing: "read";
     readonly path: string;