@sema-agent/settings-schema 17.1.0 → 17.2.0

package/CHANGELOG.md

@@ -8,6 +8,52 @@
 
 ## Unreleased
 
+## 17.2.0 — 2026-11-02 — minor:`./node` 出三只同步读写口(`config.d` 文档读数 · 决定文档读 / 写)· 根桶出「显式停用」谓词 `isExplicitlyDisabledEntry` · settings 单元读不进的处置律 · 关停位值域的实现差登记
+
+> 档位(按发版纪律):**minor** —— 新导出(`./node` 三个函数加四个类型,根桶一个函数)是加性的,既有导出的答案逐格不变;零别名、零双读。三只同步口与各自的异步口读 / 写同一份判据:读数、拒句、落盘字节、文件模式逐项相同(对拍钉)。
+> 谁需要:在**同步具名锁**里读写配置根的壳(CLI):读 `config.d/<名>.json` 要和包同一套的悬空符号链接 / 空白 / 过深判,写模型池要在锁里先写决定、再写目录;包里此前只有异步口,壳只好自读文本(第四只缺席读法)。
+> 谁受伤:无 —— 加性。壳把自读文本换成同步读口时有三处**可见差**(= 它与包的分叉清零):纯空白 / 零字节的文档由「缺席」变 `empty` 拒;悬空符号链接变 `io` 拒;嵌得过深变 `too_deep` 拒。补偿:拒句点名路径与出路(删掉它回到缺省,或写一个合法对象)。
+> 导出面:`./node` +3 函数 +4 类型,根桶 +1 函数(登记表 `docs/API-SURFACE.md` 已重生)。`entryEnabledFlag`(三态读数)收回成模块私有 —— 它从未在任何子路径上可达,所以不是导出面变化。
+
+- **`readConfigDFileReadingSync(root, name)`(`./node`)与类型 `ConfigDReading` / `ConfigDRefused` / `ConfigDFileReason` / `ConfigDDocumentName`**。读一个 `config.d/<名>.json` → 读数(`absent` / `present{value}` / `refused{reason, error, thrown, fingerprint}`),与包内异步读口**共用同一只纯判** `judgeConfigDTextReading` 与**同一个缺席尾**:
+  缺席尾抽成一只 `absentUnlessDangling`(`ENOENT` ⇒ 对文档与 `config.d` 目录各问一次链接判法 ⇒ 悬空抛那一句 ⇒ 否则缺席),`readTextIfPresent` 与新的同步孪生 `readTextIfPresentSync` 各留一行读文本的 I/O;`config-d-file` 里读口的函数体只剩「摆路径、读一次文本、交给同一只 `readingOfText` / `refusedIo`」。
+  **不**在根桶出裸纯判(壳自读文本 = 第四只缺席读法;`config-d-file` 依赖 `node:path` 与原子写器,不是浏览器安全叶),异步读口也仍包内私有 —— 本版只出壳要的同步口。名字不是 `config.d` 里能放的文档名 ⇒ 同步抛(与异步口的拒绝同一个错)。
+  钉:`test/config-d-sync-reading-17.2.0.test.ts`(同步 / 异步逐格对拍〔缺席 / 在场各形 / 空与纯空白 / 坏 JSON / 非对象五形 / 过深 / 目录 / 悬空链接 / 成环 / 权限〕+ 每格绝对答案 + 指纹绝对值 · 结构:判官 `JSON.parse` 恰一处、缺席臂恰一处、两口函数体只留一行 I/O · 出口:根桶不出)。
+- **`readEnvModelsDecisionSync(root)` / `writeEnvModelsDecisionSync(root, word, { write })`(`./node`)**。配置根上 env 模型表决定文档的同步读 / 写:同一个字节读法(`readEnvModelsDecisionBytes`)、同一个缺席律(只有 `ENOENT` 算缺席,别的读不出带 errno)、同一份答案表;
+  写口与异步口共用**同一份写计划**(决定词与写法的闭集校验 · 文本铸造 · 失败包成本包的文件系统失败句)和**同一对同步原子写原语**(异步座 `nodeConfigRootIo` 的两只写本来就是它们的异步包装,现在与同步写口调同一对,模式类表只经这一对取:新建 0o644 经进程 umask,已有的沿用原模式)。
+  读写真文件系统,**不收注入座**(`ConfigRootIo` 不动,异步形不变)。读数从不抛;写失败抛文件系统失败句,词 / 写法不在闭集抛 `TypeError`、一字不写。写序契约不变:先写决定 `replaced`、再写 `config.d/models.json`,两次写在写者对 models.json 的同一把锁里。
+  钉:`test/env-models-decision-sync-17.2.0.test.ts`(读口逐格对拍;写口〔文件不在 / 已有的各形 / 目录 / 悬空链接 / 根不存在 / 根是文件 / 根不可写〕× 两个词 × 两种写法的两棵同构树对拍:返回值 / 抛的错的类与整句 / 落盘字节 / 模式 / 残片 / 事后读数;结构:缺席律、字节读法、写计划、原子写原语各一处;`ConfigRootIo` 不动)。
+- **根桶 `isExplicitlyDisabledEntry(entry)`**。一条目录条目**原文**是不是「显式停用」(纯 JSON 对象、自有数据属性 `enabled` 恰为 `false`):「恰为 `false`」这条律此前在包内两处、壳一处(`enabledEntryCount({ models: [entry] }) === 0`)各复述一遍;现在谓词是唯一一处写它,
+  `catalogManagesModelPlane` / `enabledEntryCount` 与 `planEnvModelTableWrite` 的启用过滤都读它(`env-model-table` 的 `entryEnabledFlag(m) !== false` 改读 `!isExplicitlyDisabledEntry(m)`)。**三态读数不出口**:出三态就是把这条律交给每个消费者各写一遍 `=== false`。
+  在 JSON 数据上与壳今天的写法逐格同答。非纯 JSON 对象的值、`enabled` 缺席 / 只靠继承 / 是访问器(不调)/ 不是布尔 ⇒ `false`;读 `enabled` 的反射本身抛(Proxy 的描述符陷阱)⇒ 照抛,不吞成 `false`(`ownEnabledFlag` 的既有臂);要整份文档的口径(读不出 ⇒ `TypeError`)问 `enabledEntryCount` / `catalogManagesModelPlane`。
+  钉:`test/explicitly-disabled-entry-17.2.0.test.ts`(真值表 · 与壳旧写法逐格同答 · 自有数据属性 / 访问器不调 / 原型污染 / 非朴素 · 三态不出口 · 「`=== false`」在 `src/` 恰一处 · 两处消费者读谓词)。
+- **settings 单元读不进的处置律(文字律 + 全员表驱动钉;零代码、零新导出)**。`member` / `members` 单元里 `readSettingsUnit` 答 `unreadable` 的成员**不是缺席**(缺席 = 文档没设,读不进 = 设了但设成契约放不进的形)。类目 `fail` 为 `closed` 的成员:
+  方向 `loosen` ⇒ 调用方可丢(丢了授得更少),但要响;方向 `tighten` ⇒ 必须持住、在它自己的面上给最严的答案(规则面拒一切放不进的调用、关停位当开、沙箱开关取严极),不得丢、不得读成缺席 —— 丢掉它 = 把一条读不懂的限制当成没有限制,只有最严的答案不会比作者的本意松。
+  律的两个输入**已经是表**:方向 = `memberAdmission(category, member).direction`,失败方向 = `SAFETY_MERGE_SPEC[category].fail`;**读数上不加 `direction` 字段**(`whole` 单元没有方向来源,字段只能可选、每个消费者仍要对缺席分支;且与成员行是同一行的第二个读者)。文字在 `src/settings-units.ts` 头注、`readSettingsUnit` 文档与 `docs/CONSUMER-INTEGRATION.md` §15。
+  钉:`test/member-unreadable-law-17.2.0.test.ts`(枚举每个 `member` / `members` 行的每个成员:类目 `fail` 是 `closed`、成员行有合法 `direction` 且 `memberAdmission` 同读、界内值读得进、一组界外探针恒 `unreadable` 不抛;合成的坏表上当场见红 · 读数键恒为 `ok` + `value` | `reason` · 文字在三处)。
+  **未闭环(如实)**:`whole` 单元(`permissionMode` / `additionalDirectories` / `hooks` / `env` / `model` / `outputStyle`)没有方向列,「读不进即缺席」对它们是否闭合取决于各自值域的次序 —— 另一个设计题,本版没有答案;真正的 fail-closed 执法钉在读它的壳 / 服务端,本包不执法。
+- **关停位值域的实现差登记(`docs/CC-DIVERGENCE.md`;零代码、零新导出)**。`disableBypassPermissionsMode` / `disableAutoMode` 的读法 `readSettingsUnit` 读**布尔超集** —— `"disable"`(CC 的「开」的拼写)≡ `true`,`false` 是一个值(比较器的最松极、折叠的单位元,不改变有效值),别的 `unreadable`;
+  CC 的文件面只认字符串 `"disable"`。这是实现差、不是行为偏离(合并语义无偏差)。把值写回 CC 拼写面是壳 / 服务端的渲染(开 → `"disable"`,关 → 缺席),**本包不出反向拼写函数**(把 CC 的拼写表再搬一份进来就是第二个陈述)。钉:`test/kill-switch-spelling-17.2.0.test.ts`。
+- **订正四处过期注释**(随包源注释,无行为变化):`config-root-documents` 的两处与 `config-root-node` 的一处、`env-model-table` 头注里的「今天引擎还不读它 / 还不强制」—— 服务端的本地配置腿读这份决定并强制这道闸。
+
+**自 v17.1.0 起运行期代码有改动的公开导出(机器重算;上界 —— 可达 ≠ 一定变,不可达 ⇒ 一定不变;本版新增的导出不入表)**
+
+```text
+FileConfigStore [./node]
+catalogManagesModelPlane [.]
+enabledEntryCount [.]
+loadEnvFile [./node]
+loadLocalConfig [./node]
+loadRemoteExec [./node]
+migrateEnvModelsDecision [./node]
+nodeConfigRootIo [./node]
+planEnvModelTableWrite [.]
+readBundle [./node]
+readEnvModelsDecision [./node]
+readMigrationMarker [./node]
+writeEnvModelsDecision [./node]
+```
+
 ## 17.1.0 — 2026-11-02 — minor:车道表 device 行的可选栏登记 `DEVICE_TRUSTED_PROXY_CIDRS`(引擎读它作设备 WS 未鉴权握手 per-remote 帽键的可信代理名单)
 
 > 档位(按发版纪律):**minor** —— 车道表一行加一个 env 名(加性):写闸自此受理 `runtime.execution.coords.DEVICE_TRUSTED_PROXY_CIDRS`(此前判「不是任何车道的坐标」)。导出面零变化(没有导出增删,签名不变)。

package/README.md

@@ -47,6 +47,38 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
 > zod 3, nested inside every zod-4 host). The move to zod 4 did not change what any schema accepts or produces —
 > the conformance corpus reads byte-identically on both — only the wording of validation errors (see CHANGELOG 11.0.0).
 
+## 升级指引:17.1.x → 17.2.0(加性,零动作可升)
+
+`./node` 多三只**同步**读写口,根桶多一只谓词;既有导出的答案逐格不变。在同步具名锁里读写配置根的壳(CLI)用得上 —— 以前包里只有异步口,壳只好自读文本(一只多出来的缺席读法:没有悬空符号链接判、空白读成缺席、过深不判)。
+
+```ts
+import { readConfigDFileReadingSync, readEnvModelsDecisionSync, writeEnvModelsDecisionSync } from "@sema-agent/settings-schema/node";
+import { catalogManagesModelPlane, isExplicitlyDisabledEntry } from "@sema-agent/settings-schema";
+
+// 1. 在你的同步锁里读 config.d/models.json —— 三态读数,拒句点名路径与出路
+const reading = readConfigDFileReadingSync(configRoot, "models");
+switch (reading.status) {
+  case "absent": /* 路径上没有任何条目 */ break;
+  case "present": /* reading.value:一个 JSON 对象 */ break;
+  case "refused": /* reading.reason ∈ empty | invalid_json | not_object | too_deep | io;reading.error 是整句 */ break;
+}
+
+// 2. 整份文档管不管模型面 —— 用文档级判官(读不出抛 TypeError),不要自己数条目
+const manages = reading.status === "present" && catalogManagesModelPlane(reading.value);
+//    逐条问「这一条停用了吗」(例如给界面标灰)—— 不要自己写 `entry.enabled === false`;`models` 不一定是数组,先判
+const models: unknown[] = reading.status === "present" && Array.isArray(reading.value.models) ? reading.value.models : [];
+const disabledEntries = models.filter((m) => isExplicitlyDisabledEntry(m));
+
+// 3. 写模型池的序(同一把锁里):先写决定 replaced,再写 models.json
+const decision = readEnvModelsDecisionSync(configRoot); // absent | replaced | kept | unreadable;读数从不抛
+void [manages, disabledEntries];
+if (decision.kind !== "replaced") writeEnvModelsDecisionSync(configRoot, "replaced", { write: "overwrite" }); // 写失败抛文件系统失败句
+```
+
+把自读文本换成同步读口时的**可见差**(= 与包的分叉清零):纯空白 / 零字节的文档由「缺席」变 `empty` 拒;悬空符号链接变 `io` 拒;嵌得过深变 `too_deep` 拒。
+同步口与异步口读 / 写同一份判据(同一只纯判、同一个缺席尾、同一份写计划、同一对原子写原语),读数 / 拒句 / 落盘字节 / 文件模式逐项相同;同步口读写真文件系统,不收注入座(`ConfigRootIo` 不动)。
+settings 单元读不进的成员**不是缺席**(`loosen` 可丢且要响,`tighten` 必须持住并给最严答案)的处置律在 `docs/CONSUMER-INTEGRATION.md` §15,同步读写口的契约在 §16;关停位值域的实现差登在 `docs/CC-DIVERGENCE.md`。导出面:`./node` +3 函数 +4 类型,根桶 +1 函数。逐条见 CHANGELOG 17.2.0。
+
 ## 升级指引:17.0.x → 17.1.0(加性,零动作可升)
 
 车道表 `EXECUTION_LANES` 的 device 行在可选栏多一个非密坐标 `DEVICE_TRUSTED_PROXY_CIDRS`(在 `DEVICE_SUPERSEDE` 之前):引擎读它作设备 WS 未鉴权握手 per-remote 帽键的可信代理名单(CIDR 逗号分隔,缺省空 = 不读任何代理头)。

package/conformance/VERSION

@@ -1 +1 @@
-17.1.0
+17.2.0

package/dist/atomic-write.d.ts

@@ -16,10 +16,11 @@ export declare function danglingSymlinkSentence(link: string, pointsAt: string):
 /** 读写的真目标 —— **一只判法**(写器与目录迁移的读口共用):`target` 是符号链接 ⇒ 解析到它指向的真文件(悬空 ⇒ 抛 {@link danglingSymlinkSentence});
  *  不是链接或不存在 ⇒ 原样(不存在的由调用方的读 / 写照常报)。 */
 export declare function resolveSymlinkTarget(target: string): string;
-/** 读一份**可以缺席**的 UTF-8 文本 —— `config.d` 文档与 `.env` 的缺席律在这里:读得到 ⇒ 文本;`ENOENT` ⇒ 先在缺席臂里对 `file` 自己与 `dirSeats`(这份文件所在、包把它当布局座的目录,如 `config.d`)各问一次
- *  {@link resolveSymlinkTarget}(与目录迁移的读口同一只判官):任一座是悬空链接 ⇒ 抛 {@link danglingSymlinkSentence} 那一句(在场却读不出,不是缺席);都不是 ⇒ `undefined`(路径上真的没有条目)。
- *  别的读不出(`EACCES` / `EISDIR` / `ELOOP` …)原样抛。配置根自己是悬空链接(祖先座)不在问的范围内:`dirSeats` 只列文件所在的那一级布局座。 */
+/** 读一份**可以缺席**的 UTF-8 文本 —— `config.d` 文档与 `.env` 的缺席律在 {@link absentUnlessDangling}:读得到 ⇒ 文本;读不出 ⇒ 缺席尾(`ENOENT` 且无座位是悬空链接 ⇒ `undefined`;悬空 ⇒ 抛那一句;别的读不出原样抛)。
+ *  配置根自己是悬空链接(祖先座)不在问的范围内:`dirSeats` 只列文件所在的那一级布局座。 */
 export declare function readTextIfPresent(file: string, dirSeats?: readonly string[]): Promise<string | undefined>;
+/** {@link readTextIfPresent} 的同步孪生(壳在同步具名锁里读 `config.d` 文档要它):同一个缺席尾,只有读文本那一行 I/O 不同。 */
+export declare function readTextIfPresentSync(file: string, dirSeats?: readonly string[]): string | undefined;
 /** 原子写 `text`(UTF-8)到 `target`(符号链接则写到它指向的真文件,见文件头);模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
 export declare function writeFileAtomic(target: string, text: string, kind: AtomicFileClass): void;
 /**

package/dist/atomic-write.js

@@ -20,9 +20,9 @@
  * 「链接 ⇒ 真文件、悬空 ⇒ 响亮抛」这一只判法是 {@link resolveSymlinkTarget}:目录迁移的读口(`./config-dir-io`)读目录 / 读文件前也问它,
  * 悬空链接在读阶段与写阶段是**同一句**({@link danglingSymlinkSentence})。
  *
- * ## `config.d` 文档与 `.env` 的缺席只有一种读法({@link readTextIfPresent})
+ * ## `config.d` 文档与 `.env` 的缺席只有一种读法({@link absentUnlessDangling})
  * **缺席 = 路径上没有任何条目。** `readFile` 跟着符号链接走,链接在而目标不在时内核同样答 `ENOENT`:那是在场却读不出,不是缺席。读一份可以缺席的文本(`config.d` 的文档、配置根下的 `.env`)
- * 因此都过同一只读者 —— 读不出且是 `ENOENT` ⇒ 在**缺席臂里**问一次链接判法再答「缺席」,悬空 ⇒ 抛那一句(同一句,不带 errno 码)。判在缺席臂而不在读前:读得到的路径零变化(不多一次系统调用);读之后目标恰好出现仍答缺席 —— 读的那一刻它确实不在,与旧读法同一边界,不是放宽。
+ * 因此都过同一只缺席尾({@link absentUnlessDangling};异步读者 {@link readTextIfPresent} 与同步读者 {@link readTextIfPresentSync} 各留一行读文本的 I/O) —— 读不出且是 `ENOENT` ⇒ 在**缺席臂里**问一次链接判法再答「缺席」,悬空 ⇒ 抛那一句(同一句,不带 errno 码)。判在缺席臂而不在读前:读得到的路径零变化(不多一次系统调用);读之后目标恰好出现仍答缺席 —— 读的那一刻它确实不在,与旧读法同一边界,不是放宽。
  *
  * ## 不存在才建({@link createFileExclusive})
  * 另一种写法只有一处不同:最后一步不是 `rename` 盖过目标,而是把(已 fsync 的)临时文件 `link` 成目标名 —— 目标名已在(任何东西:文件、目录、哪怕是悬空的符号链接)⇒
@@ -43,7 +43,7 @@
  */
 import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import { chmodSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import path from "node:path";
 import { FsFailure } from "./fs-failure.js";
 /** 按文档类的模式表(闭集)。 */
@@ -80,20 +80,34 @@ export function resolveSymlinkTarget(target) {
         throw e;
     }
 }
-/** 读一份**可以缺席**的 UTF-8 文本 —— `config.d` 文档与 `.env` 的缺席律在这里:读得到 ⇒ 文本;`ENOENT` ⇒ 先在缺席臂里对 `file` 自己与 `dirSeats`(这份文件所在、包把它当布局座的目录,如 `config.d`)各问一次
- *  {@link resolveSymlinkTarget}(与目录迁移的读口同一只判官):任一座是悬空链接 ⇒ 抛 {@link danglingSymlinkSentence} 那一句(在场却读不出,不是缺席);都不是 ⇒ `undefined`(路径上真的没有条目)。
- *  别的读不出(`EACCES` / `EISDIR` / `ELOOP` …)原样抛。配置根自己是悬空链接(祖先座)不在问的范围内:`dirSeats` 只列文件所在的那一级布局座。 */
+/** 读一份**可以缺席**的文本之后,「读不出」怎么答的**缺席尾**(异步 {@link readTextIfPresent} 与同步 {@link readTextIfPresentSync} 共用,缺席律只此一处):读失败 `e` 不是 `ENOENT` ⇒ 原样抛(`EACCES` / `EISDIR` / `ELOOP` …);
+ *  是 `ENOENT` ⇒ 先在缺席臂里对 `file` 自己与 `dirSeats`(这份文件所在、包把它当布局座的目录,如 `config.d`)各问一次 {@link resolveSymlinkTarget}(与目录迁移的读口同一只判官):任一座是悬空链接 ⇒ 抛
+ *  {@link danglingSymlinkSentence} 那一句(在场却读不出,不是缺席);都不是 ⇒ `undefined`(路径上真的没有条目)。 */
+function absentUnlessDangling(e, file, dirSeats) {
+    if (e.code !== "ENOENT")
+        throw e;
+    for (const seat of [file, ...dirSeats])
+        resolveSymlinkTarget(seat);
+    return undefined;
+}
+/** 读一份**可以缺席**的 UTF-8 文本 —— `config.d` 文档与 `.env` 的缺席律在 {@link absentUnlessDangling}:读得到 ⇒ 文本;读不出 ⇒ 缺席尾(`ENOENT` 且无座位是悬空链接 ⇒ `undefined`;悬空 ⇒ 抛那一句;别的读不出原样抛)。
+ *  配置根自己是悬空链接(祖先座)不在问的范围内:`dirSeats` 只列文件所在的那一级布局座。 */
 export async function readTextIfPresent(file, dirSeats = []) {
     try {
         return await readFile(file, "utf8");
     }
     catch (e) {
-        if (e.code !== "ENOENT")
-            throw e;
+        return absentUnlessDangling(e, file, dirSeats);
+    }
+}
+/** {@link readTextIfPresent} 的同步孪生(壳在同步具名锁里读 `config.d` 文档要它):同一个缺席尾,只有读文本那一行 I/O 不同。 */
+export function readTextIfPresentSync(file, dirSeats = []) {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch (e) {
+        return absentUnlessDangling(e, file, dirSeats);
     }
-    for (const seat of [file, ...dirSeats])
-        resolveSymlinkTarget(seat);
-    return undefined;
 }
 /** 原子写 `text`(UTF-8)到 `target`(符号链接则写到它指向的真文件,见文件头);模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
 export function writeFileAtomic(target, text, kind) {

package/dist/catalog-manages.d.ts

@@ -4,10 +4,15 @@
  * 包内私有(不进包根):这是「`enabled` 怎么读」的**唯一实现**;条目的形由调用方判一次(被丢条目身份在读 `name` / `id` 之前已判过,这里不再问第二次)。
  */
 export declare function ownEnabledFlag(entry: object): boolean | undefined;
-/** 一条目录条目**原文**的 `enabled`:先判形(不是纯 JSON 对象 ⇒ `undefined`),再读 {@link ownEnabledFlag}。「显式停用」与计划助手的启用过滤都调它。 */
-export declare function entryEnabledFlag(entry: unknown): boolean | undefined;
 /**
- * 文档里**不是显式停用**的条目数(日志计数用;判官 {@link catalogManagesModelPlane} 就是它 > 0)。入参是 models 文档原文或读过的 `ModelsConfig`(两者同形)。
+ * 一条目录条目**原文**是不是「显式停用」—— **根桶出口**,「显式停用」这条律(纯 JSON 对象、自有数据属性 `enabled` 恰为 `false`)全包只在这里写一次。
+ * 入参是解析出来的 JSON(models 文档里的一项);**不是**纯 JSON 对象的值(串 / 数 / `null` / 数组 / 类实例 / `Map` / 函数 / 撤销的 Proxy)、`enabled` 缺席、只靠继承、是访问器(不调)、不是布尔 ⇒ `false`
+ * (不是显式停用 ⇒ 在管文档里计入,与判官同答)。读 `enabled` 的反射本身抛(Proxy 的描述符陷阱,JSON 解析不出这种值)⇒ 照抛,不吞成 `false`({@link ownEnabledFlag} 的既有臂);要整份文档的口径(读不出 ⇒ `TypeError`)
+ * 问 {@link enabledEntryCount} / {@link catalogManagesModelPlane}。纯、浏览器安全。
+ */
+export declare function isExplicitlyDisabledEntry(entry: unknown): boolean;
+/**
+ * 文档里**不是显式停用**({@link isExplicitlyDisabledEntry})的条目数(日志计数用;判官 {@link catalogManagesModelPlane} 就是它 > 0)。入参是 models 文档原文或读过的 `ModelsConfig`(两者同形)。
  * 读不出 ⇒ `TypeError`(见文件头)。
  */
 export declare function enabledEntryCount(doc: unknown): number;

package/dist/catalog-manages.js

@@ -3,7 +3,8 @@
  *
  * ## 律(一条)
  * **文档的 `models` 里至少一条不是「显式停用」的条目 ⇔ 管。** 「显式停用」= 纯 JSON 对象、自有数据属性 `enabled` 恰为 `false`
- * ({@link ownEnabledFlag} 是这一读法的**唯一**实现:被丢条目身份的 `enabled`(`./config-fns` 的 `readEntryIdentity`)读的是同一只;{@link entryEnabledFlag} 只是它前面判一次形的入口)。
+ * ({@link ownEnabledFlag} 是这一读法的**唯一**实现:被丢条目身份的 `enabled`(`./config-fns` 的 `readEntryIdentity`)读的是同一只;{@link entryEnabledFlag} 是它前面判一次形的入口,**模块私有**;
+ * 「恰为 `false`」这一句只在 {@link isExplicitlyDisabledEntry} 写一次,它是出口 —— 判官、计数、`./env-model-table` 的启用过滤与每个要问「这一条停用了吗」的消费者都读它,不各写一份 `=== false`)。
  * 判官 = 计数 > 0:「管不管」与「几条在管」是同一个事实的两种问法,只有一种读法。
  *
  *  · 文档不是纯对象、`models` 缺席或不是数组 ⇒ 0 条(不管);数组里的洞不是条目;
@@ -25,14 +26,22 @@ export function ownEnabledFlag(entry) {
     const value = d !== undefined && !isAccessorDescriptor(d) ? d.value : undefined; // 访问器不调(描述符的字段只认自有的,见内核)
     return typeof value === "boolean" ? value : undefined;
 }
-/** 一条目录条目**原文**的 `enabled`:先判形(不是纯 JSON 对象 ⇒ `undefined`),再读 {@link ownEnabledFlag}。「显式停用」与计划助手的启用过滤都调它。 */
-export function entryEnabledFlag(entry) {
+/** 一条目录条目**原文**的 `enabled`:先判形(不是纯 JSON 对象 ⇒ `undefined`),再读 {@link ownEnabledFlag}。**模块私有** —— 三态读数不出门:出三态就是把「显式停用 ⇔ flag 恰为 false」这条律交给每个消费者各复述一遍,
+ *  消费者问的是 {@link isExplicitlyDisabledEntry}。 */
+function entryEnabledFlag(entry) {
     return isPlainJsonObject(entry) ? ownEnabledFlag(entry) : undefined;
 }
-/** 「显式停用」:{@link entryEnabledFlag} 恰为 `false`。 */
-const isExplicitlyDisabled = (entry) => entryEnabledFlag(entry) === false;
 /**
- * 文档里**不是显式停用**的条目数(日志计数用;判官 {@link catalogManagesModelPlane} 就是它 > 0)。入参是 models 文档原文或读过的 `ModelsConfig`(两者同形)。
+ * 一条目录条目**原文**是不是「显式停用」—— **根桶出口**,「显式停用」这条律(纯 JSON 对象、自有数据属性 `enabled` 恰为 `false`)全包只在这里写一次。
+ * 入参是解析出来的 JSON(models 文档里的一项);**不是**纯 JSON 对象的值(串 / 数 / `null` / 数组 / 类实例 / `Map` / 函数 / 撤销的 Proxy)、`enabled` 缺席、只靠继承、是访问器(不调)、不是布尔 ⇒ `false`
+ * (不是显式停用 ⇒ 在管文档里计入,与判官同答)。读 `enabled` 的反射本身抛(Proxy 的描述符陷阱,JSON 解析不出这种值)⇒ 照抛,不吞成 `false`({@link ownEnabledFlag} 的既有臂);要整份文档的口径(读不出 ⇒ `TypeError`)
+ * 问 {@link enabledEntryCount} / {@link catalogManagesModelPlane}。纯、浏览器安全。
+ */
+export function isExplicitlyDisabledEntry(entry) {
+    return entryEnabledFlag(entry) === false;
+}
+/**
+ * 文档里**不是显式停用**({@link isExplicitlyDisabledEntry})的条目数(日志计数用;判官 {@link catalogManagesModelPlane} 就是它 > 0)。入参是 models 文档原文或读过的 `ModelsConfig`(两者同形)。
  * 读不出 ⇒ `TypeError`(见文件头)。
  */
 export function enabledEntryCount(doc) {
@@ -49,7 +58,7 @@ export function enabledEntryCount(doc) {
     for (let i = 0; i < models.length; i++) {
         if (!Object.hasOwn(models, i))
             continue; // 洞不是条目:只认自有下标(`forEach` / `for…of` 会读到被污染的 `Array.prototype[i]`)
-        if (!isExplicitlyDisabled(models[i]))
+        if (!isExplicitlyDisabledEntry(models[i]))
             count++;
     }
     return count;

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

@@ -41,9 +41,11 @@ export declare function judgeConfigDText(name: ConfigDDocumentName, text: string
  *  非朴素对象、嵌得过深 ⇒ 抛。{@link judgeConfigDText} 的最后一道判就是这只(文本解析出来之后过它),所以「不是对象」「过深」各一种坏形一句话,不论文档是从文件文本来的还是调用方直接给的;
  *  `label` = 句首的称呼(文本路径给文件的真实路径,值路径给 `the <名> document`)。 */
 export declare function judgeConfigDValue(name: ConfigDDocumentName, value: unknown, label: string): Record<string, unknown>;
-/** 读一个 `config.d/<名>.json` → 读数:路径上没有任何条目 ⇒ 缺席;在场 ⇒ {@link judgeConfigDTextReading};在场却读不出 ⇒ 被拒,词 `io` —— 非 ENOENT 的 fs 错误,以及悬空的符号链接
- *  (文档本身或 `config.d` 目录:内核跟链接读到 ENOENT,但条目在场;句子是 `danglingSymlinkSentence`(`./atomic-write`)那一句,与目录迁移的读口同一句)。缺席与悬空的分辨在 `readTextIfPresent`。 */
+/** 读一个 `config.d/<名>.json` → 读数:路径上没有任何条目 ⇒ 缺席;在场 ⇒ {@link judgeConfigDTextReading};在场却读不出 ⇒ 被拒,词 `io`({@link refusedIo})。缺席与悬空的分辨在 `readTextIfPresent` 的缺席尾。 */
 export declare function readConfigDFileReading(root: string, name: ConfigDDocumentName): Promise<ConfigDReading>;
+/** {@link readConfigDFileReading} 的同步孪生(`./node` 出口;壳在同步具名锁里读 `config.d` 文档要它):**同一只纯判**({@link readingOfText} → {@link judgeConfigDTextReading})、**同一个缺席尾**
+ *  (`readTextIfPresentSync` 与异步读者共用 `absentUnlessDangling`),只有读文本那一行 I/O 不同。名字不是 `config.d` 里能放的文档名 ⇒ 同步抛(与异步口的拒绝同一个错)。 */
+export declare function readConfigDFileReadingSync(root: string, name: ConfigDDocumentName): ConfigDReading;
 /** 抛出口:读一个 `config.d/<名>.json`:路径上没有任何条目 ⇒ `undefined`;在场 ⇒ 它的值;被拒 ⇒ 抛读数的 `thrown`(见 {@link readConfigDFileReading})。 */
 export declare function readConfigDFile(root: string, name: ConfigDDocumentName): Promise<Record<string, unknown> | undefined>;
 /** 一棵 `config.d` 的原文快照:便携域与 retired 域的文档原文(缺席 ⇒ `undefined`),版本哈希的入参。 */

package/dist/config-d-file.js

@@ -16,7 +16,7 @@
  * 句尾出路按文档类({@link documentWayOut}),从不回显文件原文。
  */
 import path from "node:path";
-import { readTextIfPresent } from "./atomic-write.js";
+import { readTextIfPresent, readTextIfPresentSync } from "./atomic-write.js";
 import { refuseRetiredDomain, sanitizeZodError } from "./config-fns.js";
 import { MAX_HASH_DEPTH, stableHash } from "./hash.js";
 import { UNINSPECTABLE, guardedSafeParse, ownElementsOf, ownEntriesOf } from "./own-key-read.js";
@@ -156,8 +156,17 @@ function configDValueFlaw(name, value, label) {
     }
     return { reason: "not_object", error: new Error(`${label} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`) };
 }
-/** 读一个 `config.d/<名>.json` → 读数:路径上没有任何条目 ⇒ 缺席;在场 ⇒ {@link judgeConfigDTextReading};在场却读不出 ⇒ 被拒,词 `io` —— 非 ENOENT 的 fs 错误,以及悬空的符号链接
- *  (文档本身或 `config.d` 目录:内核跟链接读到 ENOENT,但条目在场;句子是 `danglingSymlinkSentence`(`./atomic-write`)那一句,与目录迁移的读口同一句)。缺席与悬空的分辨在 `readTextIfPresent`。 */
+/** 在场却读不出的读数:词 `io`(非 `ENOENT` 的 fs 错误,以及悬空的符号链接 —— 文档本身或 `config.d` 目录:内核跟链接读到 `ENOENT`,但条目在场;句子是 `danglingSymlinkSentence`(`./atomic-write`)那一句,
+ *  与目录迁移的读口同一句)。`thrown` 是读文本抛的那个错原样,指纹取整句的哈希。异步 / 同步两条读口共用。 */
+function refusedIo(thrown) {
+    const error = messageOf(thrown);
+    return { status: "refused", reason: "io", error, thrown, fingerprint: stableHash(error) };
+}
+/** 读文本之后的读数(异步 / 同步两条读口共用,**判官只此一处**):没有文本(路径上没有任何条目)⇒ 缺席;有 ⇒ {@link judgeConfigDTextReading}。 */
+function readingOfText(name, file, text) {
+    return text === undefined ? { status: "absent" } : judgeConfigDTextReading(name, text, file);
+}
+/** 读一个 `config.d/<名>.json` → 读数:路径上没有任何条目 ⇒ 缺席;在场 ⇒ {@link judgeConfigDTextReading};在场却读不出 ⇒ 被拒,词 `io`({@link refusedIo})。缺席与悬空的分辨在 `readTextIfPresent` 的缺席尾。 */
 export async function readConfigDFileReading(root, name) {
     const file = configDPath(root, name);
     let text;
@@ -165,10 +174,22 @@ export async function readConfigDFileReading(root, name) {
         text = await readTextIfPresent(file, [path.dirname(file)]);
     }
     catch (e) {
-        const error = messageOf(e);
-        return { status: "refused", reason: "io", error, thrown: e, fingerprint: stableHash(error) };
+        return refusedIo(e);
     }
-    return text === undefined ? { status: "absent" } : judgeConfigDTextReading(name, text, file);
+    return readingOfText(name, file, text);
+}
+/** {@link readConfigDFileReading} 的同步孪生(`./node` 出口;壳在同步具名锁里读 `config.d` 文档要它):**同一只纯判**({@link readingOfText} → {@link judgeConfigDTextReading})、**同一个缺席尾**
+ *  (`readTextIfPresentSync` 与异步读者共用 `absentUnlessDangling`),只有读文本那一行 I/O 不同。名字不是 `config.d` 里能放的文档名 ⇒ 同步抛(与异步口的拒绝同一个错)。 */
+export function readConfigDFileReadingSync(root, name) {
+    const file = configDPath(root, name);
+    let text;
+    try {
+        text = readTextIfPresentSync(file, [path.dirname(file)]);
+    }
+    catch (e) {
+        return refusedIo(e);
+    }
+    return readingOfText(name, file, text);
 }
 /** 抛出口:读一个 `config.d/<名>.json`:路径上没有任何条目 ⇒ `undefined`;在场 ⇒ 它的值;被拒 ⇒ 抛读数的 `thrown`(见 {@link readConfigDFileReading})。 */
 export async function readConfigDFile(root, name) {

package/dist/config-root-documents.d.ts

@@ -15,7 +15,7 @@
  *    离线预置(引擎在本根起服之前铺好:镜像 / ConfigMap / 还原)时两份文档与域文档可按任意顺序写;运行时写序是定的:写者先写决定、再写 `config.d/models.json`
  *    (都在它对 models.json 的那把锁里),迁移先建运行记录、再铸决定。
  *  · **一份读法、一张闭集答案表**:决定只有 {@link EnvModelsDecision} 这一种答案(从字节读出的带同一次读的 `digest`,读不到字节的带 `errno`),
- *    读这份决定的三方 —— 引擎(本地配置腿强制这道闸之后;今天引擎还不读它)、一次性迁移 SS-M11、写者的计划助手 —— 吃同一个答案;它的身份(告警去重键、本地 etag 的贡献)只有一种拼法 {@link envModelsDecisionTag}。
+ *    读这份决定的三方 —— 服务端的本地配置腿(读它并强制这道闸)、一次性迁移 SS-M11、写者的计划助手 —— 吃同一个答案;它的身份(告警去重键、本地 etag 的贡献)只有一种拼法 {@link envModelsDecisionTag}。
  *  · **运行记录按 id 一份**:「迁移 X 跑过」⇔ `<根>/config.migration.<X>.json` 在场({@link MigrationMarker});没有聚合文件、没有追加写;
  *    读不懂的记录按「跑过」处置(fail-closed)。记录由迁移以「不存在才建」写:同一个 id 只有一个进程建得成 —— 它是那条迁移在本根上唯一的执行者。
  *  · 两份文档的形都是 strict 的:多一个键(含自有 `__proto__`)、拼错的词都读成 `bad_shape`,不剥、不猜;digest 对读到的**字节**求。名字只在这里定一次(引擎的目录信任判官取 {@link CONFIG_ROOT_DOCUMENTS})。
@@ -72,7 +72,7 @@ export type EnvModelsDecision = {
     readonly errno: string;
 };
 /**
- * 一份决定读数的**身份**(带标签的一种拼法):`absent` / `d:<digest>`(有字节的四臂)/ `io:<errno>`。引擎读这份决定时(今天引擎还不读),「每份内容只告警一次」的去重键与本地 etag 的贡献都取它 ——
+ * 一份决定读数的**身份**(带标签的一种拼法):`absent` / `d:<digest>`(有字节的四臂)/ `io:<errno>`。服务端的本地配置腿读这份决定时,「每份内容只告警一次」的去重键与本地 etag 的贡献都取它 ——
  * 来自同一次读,不再开文件(那就是第二个读者)。
  */
 export declare function envModelsDecisionTag(decision: EnvModelsDecision): string;

package/dist/config-root-documents.js

@@ -22,7 +22,7 @@ export const isDecisionWord = (v) => ENV_MODELS_DECISIONS.includes(v);
 /** 根级文档读不懂的三种原因(闭集):`bad_json` = 空 / 纯空白 / 不是 JSON;`bad_shape` = 是 JSON 但不是这份文档的形;`io` = 字节读不出(权限 —— 可信属主的 0000 文件读恒 `EACCES`,是持久的 —— 不是常规文件、悬空链接、瞬时读错)。 */
 export const ROOT_DOCUMENT_UNREADABLE_REASONS = ["bad_json", "bad_shape", "io"];
 /**
- * 一份决定读数的**身份**(带标签的一种拼法):`absent` / `d:<digest>`(有字节的四臂)/ `io:<errno>`。引擎读这份决定时(今天引擎还不读),「每份内容只告警一次」的去重键与本地 etag 的贡献都取它 ——
+ * 一份决定读数的**身份**(带标签的一种拼法):`absent` / `d:<digest>`(有字节的四臂)/ `io:<errno>`。服务端的本地配置腿读这份决定时,「每份内容只告警一次」的去重键与本地 etag 的贡献都取它 ——
  * 来自同一次读,不再开文件(那就是第二个读者)。
  */
 export function envModelsDecisionTag(decision) {

package/dist/config-root-node.d.ts

@@ -16,6 +16,8 @@ export interface ConfigRootIo {
 export declare const nodeConfigRootIo: ConfigRootIo;
 /** 配置根上 env 模型表决定的**唯一读者**(闭集答案见 `EnvModelsDecision`;从字节读出的答案带同一次读的 `digest`,io 带 `errno`)。从不抛。 */
 export declare function readEnvModelsDecision(root: string, io?: ConfigRootIo): Promise<EnvModelsDecision>;
+/** {@link readEnvModelsDecision} 的**同步孪生**(壳在同步具名锁里写模型池,要在锁里读决定):同一个字节读法、同一个缺席律、同一个答案表;读真文件系统(不收注入座 —— 注入座是异步的)。从不抛。 */
+export declare function readEnvModelsDecisionSync(root: string): EnvModelsDecision;
 /**
  * 一条一次性迁移的运行记录的**唯一读者**(文件 `<根>/config.migration.<id>.json`):不存在 ⇒ `absent`;`{"migration":<id>}` ⇒ `present`;别的 ⇒ `unreadable`
  * (坏 JSON / 坏形 —— id 对不上也算 / 读不出)。「跑过」只问这一份文件在不在、读不读得懂,不读任何聚合文件。读数从不抛;`id` 不是写运行记录的迁移(根级文档名单里没有它的记录)⇒
@@ -31,6 +33,11 @@ export type EnvModelsDecisionWrite = "overwrite" | "createIfAbsent";
 export declare function writeEnvModelsDecision(root: string, decision: EnvModelsDecisionWord, opts: {
     readonly write: EnvModelsDecisionWrite;
 }, io?: ConfigRootIo): Promise<"written" | "present">;
+/** {@link writeEnvModelsDecision} 的**同步孪生**(壳在同步具名锁里写模型池:先写决定 `replaced`、再写目录,两次写在同一把锁里):同一份计划({@link planDecisionWrite})、同一对同步原子写原语(异步座调的也是它们);
+ *  写真文件系统(不收注入座)。返回值、抛的错与落盘结果与异步口逐项同。 */
+export declare function writeEnvModelsDecisionSync(root: string, decision: EnvModelsDecisionWord, opts: {
+    readonly write: EnvModelsDecisionWrite;
+}): "written" | "present";
 /** SS-M11 的结局(闭集,调用方穷举;本函数不出声,告警由调用方按结局发)。 */
 export type EnvModelsMigration = 
 /** 运行记录已在:不跑。 */
@@ -107,7 +114,7 @@ export type EnvModelsMint =
  *  4. **独占创建运行记录** `{"migration":"SS-M11"}`:建成 ⇒ 本进程是本根**唯一的铸造者**;已在(`EEXIST`)⇒ `not_minter`,永不铸;别的失败 ⇒ `marker_write_failed`,不铸。
  *  5. 仅铸造者:D0 不是 `absent` ⇒ 不铸(读不懂的也不覆盖);M0 不管 ⇒ 不铸;M0 读不出 ⇒ 不铸(`models_unreadable`,带 errno(若有)与手工恢复句);否则**独占创建** `{"envModels":"replaced"}` —— 结局三词:`minted` / `exists`(只有 `EEXIST`)/
  *     `failed`(带 errno 与手工恢复句)。铸不铸不看 env;env 只在铸成之后读一次、只读两槽,用来点名被顶替的 env 模型。
- * 运行记录在场之后,确认缺席 ≡ kept(读这份决定的一律这么读:引擎强制这道闸之后、迁移、写者)。
+ * 运行记录在场之后,确认缺席 ≡ kept(读这份决定的一律这么读:服务端的本地配置腿、迁移、写者)。
  * 撤销的终局按运行记录的创建者算:只有创建者能写确认;以运行记录在场为前提,创建者写完 / 判定不写 / 失败(结局 `minted` / `exists` / `skipped` / `models_unreadable` / `failed`,调用方各记一行)之后,删掉决定文件就是撤销且是终局(删掉运行记录再起服 ⇒ 迁移重跑,决定缺席即重铸);其它副本读到记录在场 = 已跑、跳过(或得 `EEXIST` 答 `not_minter`),它们的返回不构成终局;创建者当选到结局落定之间的窗口在挂起 / I/O 卡顿下无上界,窗口内唯一安全的撤销是写 `kept`(独占创建护住它;删掉的会被创建者照它先读的 D0 铸回);创建者在写确认之前崩溃 ⇒ 永久 `kept`(fail-closed,披露)。
  */
 export declare function migrateEnvModelsDecision(input: {

package/dist/config-root-node.js

@@ -8,6 +8,8 @@
  *    读恒 `EACCES`,是**持久**的 —— 不是常规文件、悬空符号链接、瞬时错)⇒ `unreadable io`;字节在 ⇒ 文本读法(`./config-root-documents`;决定的答案带同一次读的 `digest`)。
  *    读数从不抛(`readMigrationMarker` 只对不写运行记录的 id 抛 `TypeError` —— 调用方的错,不拿它拼路径)。**引擎在读之前先过它自己的目录信任判官**(属主 / 写位 / 常规文件);
  *    本函数不判属主。确认文件的字节只在这里被打开。
+ *  · {@link readEnvModelsDecisionSync} / {@link writeEnvModelsDecisionSync} —— 决定文档读 / 写的**同步孪生**(壳在同步具名锁里写模型池:先写决定 `replaced`、再写目录,两次写在同一把锁里 —— 要在锁里读、在锁里写):
+ *    同一个字节读法、同一个缺席律、同一份答案表、同一份写计划、同一对同步原子写原语(异步座的写本来就是它们的异步包装);读写真文件系统,不收注入座(注入座是异步的,`ConfigRootIo` 不动)。
  *  · {@link writeEnvModelsDecision} —— 决定文件的唯一写函数(迁移铸确认也经它):写者(用户确认之后)用 `overwrite`(原子改名覆盖,读不懂的旧文件整份换掉);
  *    `createIfAbsent` 不存在才建(已在 ⇒ `present`;迁移铸确认用的就是这一种)。运行记录不经它 —— 由迁移独占创建。
  *    模式与 `config.d` 域文档同一条规则(原子写器的 `config-document` 类:新建 0o644 经进程 umask、更严的 umask 只会更严;已有的文件沿用它原来的模式)—— 写者不要自己写这份文件:
@@ -16,6 +18,7 @@
  *    运行记录 `config.migration.SS-M11.json` —— 建成的那个进程是本根唯一的铸造者,且只按它选举之前读到的决定铸;别的进程见记录已在即停、永不铸。
  *    撤销的终局按创建者算(见 {@link migrateEnvModelsDecision}):运行记录在场、创建者的结局落定之后,删掉决定文件与写 `kept` 同义、是终局(删掉运行记录再起服会重跑迁移);其它副本的返回不构成终局。
  */
+import { readFileSync, statSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { createFileExclusive, ensureOwnerOnlyDirectory, resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
@@ -31,19 +34,32 @@ const ROOT_DOCUMENT_CLASS = {
     [ENV_MODELS_DOCUMENT]: "config-document",
     [migrationMarkerDocument("SS-M11")]: "config-document",
 };
+/** 「不是常规文件」的拒句(异步读座与同步读口共用一句)。 */
+const notRegularFile = (file) => new Error(`${file} is not a regular file`);
+/** 真文件系统上的两只**同步**写原语(模式类表 {@link ROOT_DOCUMENT_CLASS} 只经这一对取):原子覆盖写 / 独占创建。异步座 {@link nodeConfigRootIo} 与同步写口 {@link writeEnvModelsDecisionSync} 调的是同一对 ——
+ *  原子写器本来就是同步实现,异步座的两只写只是它的异步包装。 */
+const writeRootDocumentSync = (document, file, text) => writeFileAtomic(file, text, ROOT_DOCUMENT_CLASS[document]);
+const createRootDocumentSync = (document, file, text) => createFileExclusive(file, text, ROOT_DOCUMENT_CLASS[document]);
 /** 真文件系统的绑定:读先过本包的符号链接判法(链接 ⇒ 它指向的真文件;悬空 ⇒ 抛,不是缺席),只读常规文件;写走本包唯一的原子写器。 */
 export const nodeConfigRootIo = {
     readFile: async (file) => {
         const real = resolveSymlinkTarget(file);
         const st = await stat(real);
         if (!st.isFile())
-            throw new Error(`${file} is not a regular file`);
+            throw notRegularFile(file);
         return readFile(real);
     },
-    writeDocument: async (document, file, text) => writeFileAtomic(file, text, ROOT_DOCUMENT_CLASS[document]),
-    createDocument: async (document, file, text) => createFileExclusive(file, text, ROOT_DOCUMENT_CLASS[document]),
+    writeDocument: async (document, file, text) => writeRootDocumentSync(document, file, text),
+    createDocument: async (document, file, text) => createRootDocumentSync(document, file, text),
     ensureDirectory: async (dir) => ensureOwnerOnlyDirectory(dir),
 };
+/** {@link nodeConfigRootIo}`.readFile` 的同步孪生(同步读口 {@link readEnvModelsDecisionSync} 用):同一条判法(符号链接 ⇒ 真文件,悬空抛;只读常规文件),只有读字节那一步同步。 */
+function readRootFileSync(file) {
+    const real = resolveSymlinkTarget(file);
+    if (!statSync(real).isFile())
+        throw notRegularFile(file);
+    return readFileSync(real);
+}
 const decisionFile = (root) => path.join(root, `${ENV_MODELS_DOCUMENT}.json`);
 const markerFile = (root, id) => path.join(root, `${migrationMarkerDocument(id)}.json`);
 /** 一个被抛出的东西的 errno:**只认自有的**字符串 `code`(经内核的键读法);读不出(会抛的 `code` getter、已撤销的 Proxy)、只靠继承、不是串 ⇒ `undefined`。从不抛(读者「从不抛」靠它)。 */
@@ -66,33 +82,52 @@ const errnoOf = (e) => {
         }
     }
 };
-/** 配置根下一份文件(两份根级文档与 `config.d/models.json`)的字节 —— 本文件唯一的缺席律:不存在(只有 `ENOENT`)⇒ `absent`;
- *  别的读不出 ⇒ `io`(带 errno 与捕获的错,调用方要句子时据它铸)。 */
+/** 读字节失败之后怎么答 —— 本文件唯一的缺席律(异步 {@link readRootBytes} 与同步 {@link readRootBytesSync} 共用):不存在(只有 `ENOENT`)⇒ `absent`;别的读不出 ⇒ `io`(带 errno 与捕获的错,调用方要句子时据它铸)。 */
+function rootBytesFailure(e) {
+    const errno = errnoOf(e);
+    return errno === "ENOENT" ? { kind: "absent" } : { kind: "io", errno, cause: e };
+}
+/** 经注入座读一份文件的字节(异步);失败的分类是 {@link rootBytesFailure}。 */
 async function readRootBytes(io, file) {
     try {
         return { kind: "bytes", bytes: await io.readFile(file) };
     }
     catch (e) {
-        const errno = errnoOf(e);
-        return errno === "ENOENT" ? { kind: "absent" } : { kind: "io", errno, cause: e };
+        return rootBytesFailure(e);
     }
 }
-/** 配置根上 env 模型表决定的**唯一读者**(闭集答案见 `EnvModelsDecision`;从字节读出的答案带同一次读的 `digest`,io 带 `errno`)。从不抛。 */
-export async function readEnvModelsDecision(root, io = nodeConfigRootIo) {
-    const bytes = await readRootBytes(io, decisionFile(root));
-    switch (bytes.kind) {
+/** 真文件系统上读一份文件的字节(同步);失败的分类是 {@link rootBytesFailure}。 */
+function readRootBytesSync(file) {
+    try {
+        return { kind: "bytes", bytes: readRootFileSync(file) };
+    }
+    catch (e) {
+        return rootBytesFailure(e);
+    }
+}
+/** 决定文档的字节读数 → 答案(异步 / 同步两只读者共用,字节读法 {@link readEnvModelsDecisionBytes} 只在这里被调)。 */
+function decisionOfBytes(read) {
+    switch (read.kind) {
         case "absent":
             return { kind: "absent" };
         case "io":
-            return ioDecision(bytes.errno);
+            return ioDecision(read.errno);
         case "bytes":
-            return readEnvModelsDecisionBytes(bytes.bytes);
+            return readEnvModelsDecisionBytes(read.bytes);
         default: {
-            const unhandled = bytes;
+            const unhandled = read;
             throw new Error(`readEnvModelsDecision: unhandled reading ${JSON.stringify(unhandled)}`);
         }
     }
 }
+/** 配置根上 env 模型表决定的**唯一读者**(闭集答案见 `EnvModelsDecision`;从字节读出的答案带同一次读的 `digest`,io 带 `errno`)。从不抛。 */
+export async function readEnvModelsDecision(root, io = nodeConfigRootIo) {
+    return decisionOfBytes(await readRootBytes(io, decisionFile(root)));
+}
+/** {@link readEnvModelsDecision} 的**同步孪生**(壳在同步具名锁里写模型池,要在锁里读决定):同一个字节读法、同一个缺席律、同一个答案表;读真文件系统(不收注入座 —— 注入座是异步的)。从不抛。 */
+export function readEnvModelsDecisionSync(root) {
+    return decisionOfBytes(readRootBytesSync(decisionFile(root)));
+}
 /**
  * 一条一次性迁移的运行记录的**唯一读者**(文件 `<根>/config.migration.<id>.json`):不存在 ⇒ `absent`;`{"migration":<id>}` ⇒ `present`;别的 ⇒ `unreadable`
  * (坏 JSON / 坏形 —— id 对不上也算 / 读不出)。「跑过」只问这一份文件在不在、读不读得懂,不读任何聚合文件。读数从不抛;`id` 不是写运行记录的迁移(根级文档名单里没有它的记录)⇒
@@ -115,13 +150,12 @@ export async function readMigrationMarker(root, id, io = nodeConfigRootIo) {
         }
     }
 }
-/**
- * 写配置根上的 env 模型表决定 —— 决定文件的**唯一写函数**(迁移铸确认也经它的 `createIfAbsent`;运行记录不归它,见文件头)。`overwrite` 恒答 `written`;`createIfAbsent` 在文档已在(`EEXIST`)时答 `present`(一字不动)。
- * 决定词 / 写法不在闭集 ⇒ `TypeError`(一字不写)。写失败 ⇒ 抛本包的文件系统失败句(点名路径)。根须已存在。
- */
-export async function writeEnvModelsDecision(root, decision, opts, io = nodeConfigRootIo) {
+/** 写决定的**计划**(异步 {@link writeEnvModelsDecision} 与同步 {@link writeEnvModelsDecisionSync} 共用,三件事只在这里):决定词与写法都在闭集里(不在 ⇒ `TypeError`,调用方的错,一字不写)· 铸文本 · 写失败 ⇒ 本包的文件系统失败句(点名路径)。
+ *  `who` 只用来在 `TypeError` 里点名调用的是哪一只。 */
+function planDecisionWrite(who, root, decision, opts) {
+    // 校验次序 = 上一个已发版本里异步口的次序(决定词 → 取路径 → 写法),逐位不动:两处同时坏的输入,先抛的错不变
     if (!isDecisionWord(decision))
-        throw new TypeError(`writeEnvModelsDecision: decision must be one of ${ENV_MODELS_DECISIONS.join(" / ")} (got ${JSON.stringify(decision)})`);
+        throw new TypeError(`${who}: decision must be one of ${ENV_MODELS_DECISIONS.join(" / ")} (got ${JSON.stringify(decision)})`);
     const file = decisionFile(root);
     const text = configDDocumentText({ envModels: decision });
     const loud = (e) => {
@@ -130,16 +164,64 @@ export async function writeEnvModelsDecision(root, decision, opts, io = nodeConf
     const write = opts.write;
     switch (write) {
         case "overwrite":
-            await io.writeDocument(ENV_MODELS_DOCUMENT, file, text).catch(loud);
+        case "createIfAbsent":
+            break;
+        default: {
+            const unhandled = write;
+            throw new TypeError(`${who}: write must be "overwrite" or "createIfAbsent" (got ${JSON.stringify(unhandled)})`);
+        }
+    }
+    return { write, file, text, loud };
+}
+/**
+ * 写配置根上的 env 模型表决定 —— 决定文件的**唯一写函数**(迁移铸确认也经它的 `createIfAbsent`;运行记录不归它,见文件头)。`overwrite` 恒答 `written`;`createIfAbsent` 在文档已在(`EEXIST`)时答 `present`(一字不动)。
+ * 决定词 / 写法不在闭集 ⇒ `TypeError`(一字不写)。写失败 ⇒ 抛本包的文件系统失败句(点名路径)。根须已存在。
+ */
+export async function writeEnvModelsDecision(root, decision, opts, io = nodeConfigRootIo) {
+    const plan = planDecisionWrite("writeEnvModelsDecision", root, decision, opts);
+    const write = plan.write;
+    switch (write) {
+        case "overwrite":
+            await io.writeDocument(ENV_MODELS_DOCUMENT, plan.file, plan.text).catch(plan.loud);
             return "written";
         case "createIfAbsent":
-            return (await io.createDocument(ENV_MODELS_DOCUMENT, file, text).catch(loud)) === "created" ? "written" : "present";
+            return (await io.createDocument(ENV_MODELS_DOCUMENT, plan.file, plan.text).catch(plan.loud)) === "created" ? "written" : "present";
         default: {
             const unhandled = write;
             throw new TypeError(`writeEnvModelsDecision: write must be "overwrite" or "createIfAbsent" (got ${JSON.stringify(unhandled)})`);
         }
     }
 }
+/** {@link writeEnvModelsDecision} 的**同步孪生**(壳在同步具名锁里写模型池:先写决定 `replaced`、再写目录,两次写在同一把锁里):同一份计划({@link planDecisionWrite})、同一对同步原子写原语(异步座调的也是它们);
+ *  写真文件系统(不收注入座)。返回值、抛的错与落盘结果与异步口逐项同。 */
+export function writeEnvModelsDecisionSync(root, decision, opts) {
+    const plan = planDecisionWrite("writeEnvModelsDecisionSync", root, decision, opts);
+    const write = plan.write;
+    switch (write) {
+        case "overwrite":
+            try {
+                writeRootDocumentSync(ENV_MODELS_DOCUMENT, plan.file, plan.text);
+            }
+            catch (e) {
+                return plan.loud(e);
+            }
+            return "written";
+        case "createIfAbsent": {
+            let created;
+            try {
+                created = createRootDocumentSync(ENV_MODELS_DOCUMENT, plan.file, plan.text);
+            }
+            catch (e) {
+                return plan.loud(e);
+            }
+            return created === "created" ? "written" : "present";
+        }
+        default: {
+            const unhandled = write;
+            throw new TypeError(`writeEnvModelsDecisionSync: write must be "overwrite" or "createIfAbsent" (got ${JSON.stringify(unhandled)})`);
+        }
+    }
+}
 /** 手工恢复句(迁移建不成收据 / 建不成决定时随结局交出;调用方原样放进它那一行告警):点名决定文件与两种写法。 */
 const wayOutFor = (root) => `write ${decisionFile(root)} by hand — {"envModels":"replaced"} lets the catalog replace the env models, {"envModels":"kept"} keeps them`;
 /** 读 `config.d/models.json` 一次(字节经 {@link readRootBytes} —— 与两份根级文档同一条缺席律;文本过 `config.d` 文档的那一只文本判 —— 与文件仓库同一读法):
@@ -179,7 +261,7 @@ async function readModelsDocument(io, root) {
  *  4. **独占创建运行记录** `{"migration":"SS-M11"}`:建成 ⇒ 本进程是本根**唯一的铸造者**;已在(`EEXIST`)⇒ `not_minter`,永不铸;别的失败 ⇒ `marker_write_failed`,不铸。
  *  5. 仅铸造者:D0 不是 `absent` ⇒ 不铸(读不懂的也不覆盖);M0 不管 ⇒ 不铸;M0 读不出 ⇒ 不铸(`models_unreadable`,带 errno(若有)与手工恢复句);否则**独占创建** `{"envModels":"replaced"}` —— 结局三词:`minted` / `exists`(只有 `EEXIST`)/
  *     `failed`(带 errno 与手工恢复句)。铸不铸不看 env;env 只在铸成之后读一次、只读两槽,用来点名被顶替的 env 模型。
- * 运行记录在场之后,确认缺席 ≡ kept(读这份决定的一律这么读:引擎强制这道闸之后、迁移、写者)。
+ * 运行记录在场之后,确认缺席 ≡ kept(读这份决定的一律这么读:服务端的本地配置腿、迁移、写者)。
  * 撤销的终局按运行记录的创建者算:只有创建者能写确认;以运行记录在场为前提,创建者写完 / 判定不写 / 失败(结局 `minted` / `exists` / `skipped` / `models_unreadable` / `failed`,调用方各记一行)之后,删掉决定文件就是撤销且是终局(删掉运行记录再起服 ⇒ 迁移重跑,决定缺席即重铸);其它副本读到记录在场 = 已跑、跳过(或得 `EEXIST` 答 `not_minter`),它们的返回不构成终局;创建者当选到结局落定之间的窗口在挂起 / I/O 卡顿下无上界,窗口内唯一安全的撤销是写 `kept`(独占创建护住它;删掉的会被创建者照它先读的 D0 铸回);创建者在写确认之前崩溃 ⇒ 永久 `kept`(fail-closed,披露)。
  */
 export async function migrateEnvModelsDecision(input) {

package/dist/env-model-table.js

@@ -5,7 +5,7 @@
  * ## 律
  *  · **env 两槽只在这里读一次**({@link readEnvModelSlots}):`MODEL_ID` 缺席或空串 = 没有主槽(纯空白算在场 —— 与引擎的 env 路由读口同尺);
  *    cheap 槽四态({@link EnvCheapSlot})。「env 模型表已声明」({@link envModelTableDeclared})与角色底({@link buildEnvModelBaseline})都由它派生 ——
- *    这道闸的执行方(引擎一侧;今天引擎还不强制)与写者的计划助手调同一份(一次性迁移 SS-M11 只用两槽点名被顶替的 env 模型,铸不铸不看它),不各写一份。env 快照按「读到即算」(下标读;原型分层的快照里继承来的键算在场)。
+ *    这道闸的执行方(服务端的本地配置腿)与写者的计划助手调同一份(一次性迁移 SS-M11 只用两槽点名被顶替的 env 模型,铸不铸不看它),不各写一份。env 快照按「读到即算」(下标读;原型分层的快照里继承来的键算在场)。
  *    引擎另有「名册占位 ⇒ env 表算空」一格,那是引擎自己的部署事实,不在本包。
  *  · **计划助手判序**({@link planEnvModelTableWrite}):目标腿不读 `config.d`(remote / none)⇒ 照写 → 候选不管模型面 ⇒ 照写 →
  *    env 表未声明 ⇒ 照写、**不写确认** → 配置根的决定是 `replaced` ⇒ 照写 →
@@ -18,7 +18,7 @@
  *    读成未设、按角色回退链落下一级并说一次 —— 没有哪种读法因它拒组;它照样写在回执里(`dangles`),要确认的写法把它给用户看。
  */
 import { z } from "zod";
-import { entryEnabledFlag, catalogManagesModelPlane } from "./catalog-manages.js";
+import { catalogManagesModelPlane, isExplicitlyDisabledEntry } from "./catalog-manages.js";
 import { parseDomainSalvaged, isDisclosableIdentity, resolveActiveTiers, withheldNameToken } from "./config-fns.js";
 import { ENV_MODELS_DOCUMENT } from "./config-root-documents.js";
 import { resolveCatalogDefaultModel } from "./default-model.js";
@@ -128,7 +128,7 @@ function candidateView(candidate) {
     }
 }
 function buildReceipt(baseline, view, decision) {
-    const enabled = view.models.filter((m) => entryEnabledFlag(m) !== false).map((m) => ({ name: m.name, id: m.id }));
+    const enabled = view.models.filter((m) => !isExplicitlyDisabledEntry(m)).map((m) => ({ name: m.name, id: m.id }));
     const byName = new Map(enabled.map((e) => [e.name, e]));
     const tiers = resolveActiveTiers(view);
     /** 一个名采纳后落到哪条:经与引擎同一张档位展开(目录键先赢;env 底继承来的 `flash` 一类档位词按活跃组解)。 */

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export * from "./url-shape.js";
 export * from "./device-relay.js";
 export * from "./url-credential.js";
 export * from "./default-model.js";
-export { catalogManagesModelPlane, enabledEntryCount } from "./catalog-manages.js";
+export { catalogManagesModelPlane, enabledEntryCount, isExplicitlyDisabledEntry } from "./catalog-manages.js";
 export { DEFAULT_MODEL_KEY, ENV_MODEL_TABLE_KEYS, buildEnvModelBaseline, envModelTableDeclared, envModelTableWriteRefusal, mintedCheapId, planEnvModelTableWrite, readEnvModelSlots, type EnvCheapSlot, type EnvModelBaseline, type EnvModelTableEntry, type EnvModelTableKey, type EnvModelTableLanding, type EnvModelTableReceipt, type EnvModelTableRoleRow, type EnvModelTableTarget, type EnvModelTableWriteInput, type EnvModelTableWriteIntent, type EnvModelTableWritePlan, type EnvRoleBinding, type EnvSnapshot, } from "./env-model-table.js";
 export { CONFIG_ROOT_DOCUMENTS, ENV_MODELS_DECISIONS, ENV_MODELS_DOCUMENT, ROOT_DOCUMENT_UNREADABLE_REASONS, envModelsDecisionTag, type ConfigRootDocument, type EnvModelsDecision, type EnvModelsDecisionWord, type MarkedMigrationId, type MigrationMarker, type RootDocumentUnreadableReason } from "./config-root-documents.js";
 export * from "./loopback.js";

package/dist/index.js

@@ -9,7 +9,7 @@ export * from "./url-shape.js"; // 11.0.0: THE URL shape judge (httpUrlFlaws / h
 export * from "./device-relay.js"; // 16.0.0: THE value grammar of the device lane's DEVICE_RELAY_URL (DEVICE_RELAY_NONE / deviceRelayFlaws / DEVICE_RELAY_RULE), pure/browser-safe
 export * from "./url-credential.js"; // 14.5.0: THE "does this URL carry a credential" judge (findUrlCredential / findUrlUserinfo / URL_CREDENTIAL_REASONS / CREDENTIAL_PARAM_NAMES …), pure/browser-safe
 export * from "./default-model.js"; // 11.0.0: THE catalog-default resolver (roles.default → active tier ladder → fallback), pure/browser-safe
-export { catalogManagesModelPlane, enabledEntryCount } from "./catalog-manages.js"; // THE "does this models document manage the model plane" judge (raw half: at least one entry not explicitly disabled) + the log count it is derived from, pure/browser-safe
+export { catalogManagesModelPlane, enabledEntryCount, isExplicitlyDisabledEntry } from "./catalog-manages.js"; // THE "does this models document manage the model plane" judge (raw half: at least one entry not explicitly disabled) + the log count it is derived from + THE "is this one entry explicitly disabled" predicate they (and every per-entry consumer) read (the three-state `enabled` reading stays package-private), pure/browser-safe
 export { DEFAULT_MODEL_KEY, ENV_MODEL_TABLE_KEYS, buildEnvModelBaseline, envModelTableDeclared, envModelTableWriteRefusal, mintedCheapId, planEnvModelTableWrite, readEnvModelSlots, } from "./env-model-table.js"; // the env model table (MODEL_ID / MODEL_CHEAP_ID) read once: readEnvModelSlots / envModelTableDeclared / buildEnvModelBaseline + the writer's plan planEnvModelTableWrite (receipt by id, confirmKey) + envModelTableWriteRefusal, pure/browser-safe (named: the env snapshot helper stays package-private)
 export { CONFIG_ROOT_DOCUMENTS, ENV_MODELS_DECISIONS, ENV_MODELS_DOCUMENT, ROOT_DOCUMENT_UNREADABLE_REASONS, envModelsDecisionTag } from "./config-root-documents.js"; // the config-root documents (config.env-models.json + the per-id migration marker config.migration.<id>.json): names + closed answer tables + the one tagged identity of a decision reading (envModelsDecisionTag); the readers / writer are in ./node
 export * from "./loopback.js"; // 11.0.0: the two「本机」predicates (auth relaxation — narrow / connection routing — wide), pure/browser-safe

package/dist/node.d.ts

@@ -8,8 +8,11 @@ export * from "./file-store.js";
 export * from "./file-edit.js";
 export * from "./bundle.js";
 export * from "./local-load.js";
+export { readConfigDFileReadingSync, type ConfigDDocumentName, type ConfigDFileReason, type ConfigDReading, type ConfigDRefused } from "./config-d-file.js";
 export * from "./scheduler-store-node.js";
 export { migrateConfigDirectory, migrateConfigDocuments, // 14.5.0:同一段「迁 → 整域终判」的同步口(入参是已有的存量文档,无 io)—— 目录形调的就是它的内核
 type ConfigDirectoryDocument, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type ConfigDocumentsMigration, type MigrateConfigDirectoryOptions, type MigrateConfigDocumentsOptions, } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js";
-export { migrateEnvModelsDecision, nodeConfigRootIo, readEnvModelsDecision, readMigrationMarker, writeEnvModelsDecision, type ConfigRootIo, type EnvModelsDecisionWrite, type EnvModelsMigration, type EnvModelsMint, } from "./config-root-node.js";
+export { migrateEnvModelsDecision, nodeConfigRootIo, readEnvModelsDecision, readEnvModelsDecisionSync, // 同步孪生:同一个字节读法 / 缺席律 / 答案表(壳在同步具名锁里写模型池要在锁里读决定)
+readMigrationMarker, writeEnvModelsDecision, writeEnvModelsDecisionSync, // 同步孪生:同一份写计划 + 同一对同步原子写原语
+type ConfigRootIo, type EnvModelsDecisionWrite, type EnvModelsMigration, type EnvModelsMint, } from "./config-root-node.js";

package/dist/node.js

@@ -8,10 +8,14 @@ export * from "./file-store.js";
 export * from "./file-edit.js";
 export * from "./bundle.js";
 export * from "./local-load.js";
+// 一份 `config.d/<名>.json` 的读数(缺席 / 在场 / 被拒)的**同步读口**:与包内异步读口同一只纯判、同一个缺席尾(壳在同步具名锁里读 `config.d` 文档用它,不自读文本);纯判本身与异步读口不出门。显式列名。
+export { readConfigDFileReadingSync } from "./config-d-file.js";
 export * from "./scheduler-store-node.js"; // R7 self-wake scheduler store — fs binding of the ./scheduler-store contract
 // 目录形的一次性迁移(读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件)—— 语义只此一处,命令行是它的渲染器、引擎起服调同一只。显式列名:该模块的包内私有件(出门形/拼路径)不外泄。
 export { migrateConfigDirectory, migrateConfigDocuments, // 14.5.0:同一段「迁 → 整域终判」的同步口(入参是已有的存量文档,无 io)—— 目录形调的就是它的内核
  } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js"; // 上面那只函数的真 I/O 绑定:node:fs + 本包唯一的原子写器(config-document 模式规则)
-// 配置根上的决定文档(config.env-models.json)与按 id 的运行记录(config.migration.<id>.json)的两只读者、决定文档的唯一写函数(运行记录由迁移独占创建),与一次性迁移 SS-M11 的迁移体(名字与闭集答案表在包根)。显式列名。
-export { migrateEnvModelsDecision, nodeConfigRootIo, readEnvModelsDecision, readMigrationMarker, writeEnvModelsDecision, } from "./config-root-node.js";
+// 配置根上的决定文档(config.env-models.json)与按 id 的运行记录(config.migration.<id>.json)的两只读者、决定文档的唯一写函数(运行记录由迁移独占创建;决定文档的读写各有同步孪生),与一次性迁移 SS-M11 的迁移体(名字与闭集答案表在包根)。显式列名。
+export { migrateEnvModelsDecision, nodeConfigRootIo, readEnvModelsDecision, readEnvModelsDecisionSync, // 同步孪生:同一个字节读法 / 缺席律 / 答案表(壳在同步具名锁里写模型池要在锁里读决定)
+readMigrationMarker, writeEnvModelsDecision, writeEnvModelsDecisionSync, // 同步孪生:同一份写计划 + 同一对同步原子写原语
+ } from "./config-root-node.js";

package/dist/settings-units.d.ts

@@ -75,6 +75,9 @@ export declare function unitTighten(unit: SettingsUnitName, member?: string): Ti
  * are `"manual"` ⇒ `"default"` (permissionMode) and `"disable"` ⇒ `true` (kill-switches); `"bypassPermissions"` is `launch_only`.
  * The last step of every reading is the unit comparator's own domain: whatever reads, compares (file header).
  * Addressing is {@link unitTighten}'s (same RangeErrors: a `members` unit needs a declared member, …).
+ * `unreadable` on a `member` / `members` unit is NOT absence, and the reading carries no direction: what the caller does with it depends on the member's
+ * `memberAdmission(category, member).direction` (`loosen` ⇒ may be dropped, loudly; `tighten` ⇒ must be kept and answered strictest on its own surface) —
+ * see WHEN A MEMBER DOES NOT READ in the file header.
  */
 export declare function readSettingsUnit(unit: SettingsUnitName, raw: unknown, member?: string): {
     readonly ok: true;

package/dist/settings-units.js

@@ -38,6 +38,21 @@
  * owner, the comparator; a reading only adds what it needs on top (non-empty list elements, the hooks judge, …). So a value the
  * shape half accepts but the comparator cannot place — a hooks document the hooks judge loads while a key it strips hides data
  * nested deeper than `MAX_HASH_DEPTH`, or an `undefined` — is `unreadable`, never "read but not comparable".
+ * WHEN A MEMBER DOES NOT READ (the disposition law). On a `member` / `members` unit, `unreadable` is NOT absence: absence is "the document does
+ * not set this member", `unreadable` is "the document sets it, in a form the contract cannot place". The two facts a caller needs to dispose of
+ * it are already tables, and neither is carried by the reading (a reading has no `direction`: a `whole` unit has no direction source, so the field
+ * could only be optional and every consumer would still branch on its absence — and it would be a second reader of a member row's `direction`):
+ * the member's direction is `memberAdmission(category, member).direction`, and the category's failure direction is `SAFETY_MERGE_SPEC[category].fail`.
+ * For a member of a category whose `fail` is `closed` (today every category that declares members: `permissions`, `sandboxNetwork`, `killSwitches`):
+ *  · a `loosen` member — the caller MAY drop it (dropping grants less), loudly: it says which member of which layer was dropped and why;
+ *  · a `tighten` member — the caller must NOT drop it and must NOT read it as absent: it keeps the member and answers on ITS surface with the
+ *    strictest answer it has (the rules surface refuses every call it cannot place; a kill-switch counts as ON; a sandbox switch takes its strict
+ *    pole), because dropping a tighten member reads a restriction its author wrote — in a form the contract cannot place — as no restriction at all;
+ *    the contract cannot tell what it was meant to forbid, and the strictest answer is the only one that cannot be looser than what the author meant.
+ * The package enforces nothing here (the surfaces are the consumers'); what it pins is that both inputs exist for every such member and that every
+ * out-of-domain value reads `unreadable` without throwing. Not covered, and not settled here: the `whole` units (`permissionMode`, `additionalDirectories`,
+ * `hooks`, `env`, `model`, `outputStyle`) have no direction column; whether "unreadable = absent" closes for them depends on the order of the
+ * unit's own value domain, which is a design question of its own.
  * The env DOCUMENT's literal grammar (boolean words, csv + empty-set sentinel, a "≤ 0 means off" cap) is not here: it belongs to
  * the engine's env catalog, whose one implementation is the server's.
  */
@@ -165,6 +180,9 @@ function shapedReading(unit, row, rule, raw) {
  * are `"manual"` ⇒ `"default"` (permissionMode) and `"disable"` ⇒ `true` (kill-switches); `"bypassPermissions"` is `launch_only`.
  * The last step of every reading is the unit comparator's own domain: whatever reads, compares (file header).
  * Addressing is {@link unitTighten}'s (same RangeErrors: a `members` unit needs a declared member, …).
+ * `unreadable` on a `member` / `members` unit is NOT absence, and the reading carries no direction: what the caller does with it depends on the member's
+ * `memberAdmission(category, member).direction` (`loosen` ⇒ may be dropped, loudly; `tighten` ⇒ must be kept and answered strictest on its own surface) —
+ * see WHEN A MEMBER DOES NOT READ in the file header.
  */
 export function readSettingsUnit(unit, raw, member) {
     const t = unitTarget(unit, member);

package/docs/API-SURFACE.md

@@ -4,9 +4,9 @@
 > 每次全量重算并逐名比对 —— 加 / 删 / 改形一个导出而不重生成本档 ⇒ 红。导出面的每次变动因此以本档的 diff 出现在评审里。
 > 形:`value` = 运行期拿得到的值;`type` = 只在类型层;`value+type` = 同名的值与类型(zod schema 与它推出的类型)。
 
-子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1472 个(同名在多条子路径上各计一次)。
+子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1480 个(同名在多条子路径上各计一次)。
 
-## `.`(772)
+## `.`(773)
 
 - `ABSOLUTE_HOST_PATH_MAX` — value
 - `ACCESS_TOKEN_TTL_SECONDS` — value
@@ -660,6 +660,7 @@
 - `isCredentialParamName` — value
 - `isDisclosableIdentity` — value
 - `isDomainName` — value
+- `isExplicitlyDisabledEntry` — value
 - `isHierarchicalUrl` — value
 - `isInstanceStale` — value
 - `isLoopbackAuthHost` — value
@@ -1176,9 +1177,13 @@
 - `tightenVerdict` — value
 - `trustRank` — value
 
-## `./node`(49)
+## `./node`(56)
 
 - `ConfigBundle` — type
+- `ConfigDDocumentName` — type
+- `ConfigDFileReason` — type
+- `ConfigDReading` — type
+- `ConfigDRefused` — type
 - `ConfigDirectoryDocument` — type
 - `ConfigDirectoryIo` — type
 - `ConfigDirectoryMigration` — type
@@ -1217,7 +1222,9 @@
 - `nodeConfigDirectoryIo` — value
 - `nodeConfigRootIo` — value
 - `readBundle` — value
+- `readConfigDFileReadingSync` — value
 - `readEnvModelsDecision` — value
+- `readEnvModelsDecisionSync` — value
 - `readMigrationMarker` — value
 - `remoteExecPath` — value
 - `saveSchedulerStore` — value
@@ -1226,6 +1233,7 @@
 - `writeBundle` — value
 - `writeDomainFile` — value
 - `writeEnvModelsDecision` — value
+- `writeEnvModelsDecisionSync` — value
 - `writeRemoteExec` — value
 
 ## `./one-time-migrations`(18)

package/docs/CC-DIVERGENCE.md

@@ -46,3 +46,9 @@
 | SS-CCD-08 | 仓库里写给 CC 的 `.claude/settings.json` / `.claude/settings.local.json` | 那就是 CC 自己的项目层 / 本地层:工作区受信时整份读(hooks / env / allow 规则 / MCP 服务器……) | 源 `foreignProjectSettings`(`tightenOnly`):不论工作区读数只读收紧方向(deny / ask 规则、关停位的开、沙箱收紧极),其余答 `tighten_only` 或 `below_trust_floor`,一行披露没读的部分 | 更严 | 对本工具它是另一个工具的配置:用户接受本工具的工作区,不等于同意把另一个工具的 hooks、环境变量与 allow 规则搬进来;收紧方向不需要信任 | 壳与服务端读仓库设置文件的那一腿 |
 
 关停位(`SAFETY_MERGE_SPEC.killSwitches`)无偏差:任一层可写「开」、合并严者胜,与限制性键表 `{path:["permissions","disableBypassPermissionsMode"],restrictive:"disable"}`(`:237449`)同形。
+
+关停位的值域(**实现差**,不是行为偏离,登在这里免得被当成偏离;与上面 SS-CCD-07 后那段同体例):读法 `readSettingsUnit`(单元 `disableBypassPermissionsMode` / `disableAutoMode`)读**布尔超集** ——
+`"disable"`(CC 的「开」的拼写)≡ `true`;`true`;`false` 是一个值 —— 合并比较器 `boolStricter` 的最松极、折叠的单位元,不改变任何有效值,不是缺席;别的一律 `unreadable`。
+CC 的文件面只认字符串 `"disable"`(2.1.309 语料 `cli309.js:258025`:`permissions?.disableBypassPermissionsMode==="disable"`),桌面端管理策略项的文案把同一个键写作 `true`(同一份语料 `:214806`)—— CC 自己也有两种拼写。
+所以把值写回 CC 的拼写面是壳 / 服务端的**渲染**(开 → `"disable"`,关 → 缺席;CC 里缺席 = 未禁用,对 CC 无损),不是第二个读法;本包不出反向拼写函数(把 CC 的拼写表再搬一份进来就是第二个陈述,而读法已经是单源 `readSettingsUnit`)。
+渲染时显式 `false` 变成缺席丢的是文档层的「显式关」,不是有效值;壳若在入闸前就删掉仓库层的 `false`,层准入对它本会答的 `below_trust_floor` 披露不被问到 —— 无效果差。

package/docs/CONSUMER-INTEGRATION.md

@@ -10,6 +10,7 @@
 > **14.7.0** 的沙箱 git 凭据平面(取值口 wire 型、有效配置块 `sandboxGit`、`VerifiedIdentity.principalInc`)在 §12。
 > **14.7.0** 的路径基址判官(`PATH_BASE_URL_FORBIDDEN_PARTS` / `pathBaseUrlFlaws`)与公告地址 env 名(`FLEET_ADVERTISE_ADDRESS_ENV`)在 §13。
 > 中心引用解析口 `resolveCenterRefs` 与记录读器 `readPlainStringRecord`(原因词表 `PLAIN_STRING_RECORD_FAULTS`)在 §14。
+> **17.2.0** 的 settings 单元读不进处置律在 §15,`./node` 的同步读写口(`config.d` 文档读数、决定文档读 / 写)与根桶的「显式停用」谓词在 §16。
 
 ---
 
@@ -531,3 +532,74 @@ fleet 成员对中心公告的可达地址(`FLEET_ADVERTISE_ADDRESS`,中心往
 - **挂不挂**:读数是判决,不是处置。
 - **变量名的形**:名册的 schema 已把变量名限在 env 名的字符集内;本口把变量名当不透明串交给 `lookup`,不再判一遍形。
 - **值的好坏**:解到串就是 `resolved`,空串、很长的串都不另判;值是不是凭据、扣不扣留,是读数之后的另一道判官的事。
+
+## 15. settings 单元读不进时的处置律(17.2.0 起)—— 读设置文件的壳与服务端两方
+
+**一句话:** `member` / `members` 单元里 `readSettingsUnit` 答 `unreadable` 的成员**不是缺席**。缺席 = 文档没设这个成员;读不进 = 文档设了,但设成了契约放不进的形。
+把它当缺席丢掉 = 当作「没设」,而对收紧方向的成员,「没设」比「设了」更松。
+
+### 15.1 本包给什么(律的两个输入都已经是表;读数上不带方向)
+
+| 要问的 | 从哪读 |
+|---|---|
+| 这个值读不读得进 | `readSettingsUnit(unit, raw, member?)` → `{ ok: true, value }` 或 `{ ok: false, reason: "unreadable" \| "launch_only" }` |
+| 这个成员往哪个方向动(`loosen` 放宽 / `tighten` 收紧) | `memberAdmission(category, member).direction`(成员行的 `direction`;层准入已经在读它) |
+| 读不进时这个类目往哪边失败 | `SAFETY_MERGE_SPEC[category].fail`(`closed` / `open`;今天有成员的三个类目 —— `permissions`、`sandboxNetwork`、`killSwitches` —— 全是 `closed`) |
+
+### 15.2 律(类目 `fail` 为 `closed` 的成员)
+
+| 成员方向 | 读不进时调用方做什么 |
+|---|---|
+| `loosen`(今天:`permissions.allow`) | **可以丢**(丢了授得更少),但要响:点名哪一层、哪个成员、为什么丢 |
+| `tighten`(今天:`permissions.deny` / `ask`、`sandbox` 的各成员、两个关停位) | **必须持住,不得丢,不得读成缺席**;在它自己的面上给最严的答案 —— 规则面对放不进的条目拒一切它放不进的调用、关停位当「开」、沙箱开关取严极 |
+
+为什么不能丢收紧成员:丢掉它 = 把作者写下的、但契约放不进的一条限制当成「没有限制」。契约读不出它本想禁什么,唯一不会比作者本意松的答案是最严的那个。
+
+### 15.3 为什么读数上不带 `direction` 字段(显式拒)
+
+- `whole` 单元(`permissionMode`、`additionalDirectories`、`hooks`、`env`、`model`、`outputStyle`)没有成员行,没有方向来源 —— 字段只能是可选的,每个消费者仍要对它缺席的分支写一遍处置;
+- 方向是成员行的属性,`memberAdmission(...).direction` 已经是它的读口;读数再带一份 = 同一行有第二个读者。
+- 要方向就读 `memberAdmission`,要失败方向就读 `SAFETY_MERGE_SPEC[category].fail`;读数只回答「读得进读不进」。
+
+### 15.4 本包做什么、不做什么(如实)
+
+- **不执法**:读不进的成员落在哪个面、怎么拒,是读它的壳 / 服务端的事。本包的钉保证两件:① 每个 `member` / `members` 单元的每个成员都有合法的 `direction`,类目是 `closed`(表里加成员而漏方向、或类目被改成 `open` ⇒ 红);
+  ② 对一组界外值(`undefined` / `null` / 错类型 / 空串 / 稀疏数组 / 读就抛的对象 …)`readSettingsUnit` 恒 `unreadable`、不抛,界内值读得进。收紧成员读不进时不放宽的执法钉,落在消费方自己的测试里。
+- **`whole` 单元不在律内**:`permissionMode` 读不进当缺席会落到系统缺省档,`hooks` / `env` / `model` 同理 —— 「读不进即缺席」对它们是否闭合,取决于各自值域的次序而不是成员方向,是另一个设计题,本版没有答案,也不假装有。
+
+## 16. 同步读写口与「显式停用」谓词(17.2.0 起)—— 在同步具名锁里读写配置根的壳
+
+**一句话:** 以前包里只有异步读写口,壳只好自读文本;现在 `./node` 有同步孪生,读 / 写**同一份判据**。读写示例见 README 的 17.1.x → 17.2.0 升级指引。
+
+### 16.1 本包发什么
+
+| 名字 | 子路径 | 作用 |
+|---|---|---|
+| `readConfigDFileReadingSync(root, name)` + 类型 `ConfigDReading` / `ConfigDRefused` / `ConfigDFileReason` / `ConfigDDocumentName` | `./node` | 读 `config.d/<名>.json` → `absent` / `present{value}` / `refused{reason, error, thrown, fingerprint}` |
+| `readEnvModelsDecisionSync(root)` | `./node` | 配置根上 env 模型表决定的读数(`absent` / `replaced` / `kept` / `unreadable{bad_json \| bad_shape \| io}`),从不抛 |
+| `writeEnvModelsDecisionSync(root, word, { write })` | `./node` | 写决定:`overwrite` 恒 `written`;`createIfAbsent` 已在则 `present`;词 / 写法不在闭集抛 `TypeError`;写失败抛文件系统失败句 |
+| `isExplicitlyDisabledEntry(entry)` | 根桶 | 一条目录条目原文是不是「显式停用」(自有数据属性 `enabled` 恰为 `false`) |
+
+### 16.2 与异步口是同一份判据(不是「差不多」)
+
+- 读:同一只纯判(`judgeConfigDTextReading`)、同一个缺席尾(只有 `ENOENT` 算缺席,且文档与 `config.d` 目录都不是悬空符号链接;悬空 ⇒ `io` 拒)。决定文档同一个字节读法、同一个缺席律、同一份答案表。
+- 写:同一份写计划(闭集校验 · 文本铸造 · 失败句)、同一对同步原子写原语;模式规则不变(新建 0o644 经进程 umask,已有的文件沿用原模式)。同步写口与异步口写出的字节、模式、抛的错逐项相同。
+- 同步口读写**真文件系统**,不收注入座;`ConfigRootIo`(异步注入座)类型不变。
+
+### 16.3 把自读文本换成同步读口:三处可见差
+
+纯空白 / 零字节的文档由「缺席」变 `empty` 拒;悬空符号链接变 `io` 拒;嵌得过深变 `too_deep` 拒。拒句点名路径与出路。壳需要原数组形的旧文件迁移(裸数组旧形)时,`ConfigDReading` 的 `not_object` 拒不带原值 —— 那条迁移在壳自己的退役线上。
+
+### 16.4 写模型池的序(不变)
+
+先写决定 `replaced`、再写 `config.d/models.json`,两次写在写者对 models.json 的同一把锁里(`planEnvModelTableWrite` 给出的 `write_with_decision` 一步)。**不要自己写决定文件**:写函数给的模式与 `config.d` 域文档同一条规则,自写在 umask 002 下落 0664,引擎的目录信任判官会拒。
+
+### 16.5 谓词:不要自己写 `=== false`
+
+「显式停用 ⇔ `enabled` 恰为 `false`」这条律只在 `isExplicitlyDisabledEntry` 写一次;`catalogManagesModelPlane` / `enabledEntryCount` 与计划助手都读它。三态读数(`enabled` 缺席 / `true` / `false`)**不出口** —— 出三态就是把这条律交给每个消费者各写一遍。
+条目不是纯 JSON 对象 / `enabled` 不是自有数据属性或不是布尔 ⇒ `false`(不是显式停用,在管文档里计入);要整份文档口径(读不出 ⇒ `TypeError`)问 `enabledEntryCount`。
+
+### 16.6 本包不做的(如实)
+
+- 不出裸纯判 `judgeConfigDTextReading` 与异步的 `readConfigDFileReading`(壳自读文本 = 第四只缺席读法;前者依赖 `node:path` 与原子写器,不是浏览器安全叶)。
+- 不替壳决定「读不进」之后挂不挂:读数是判决,不是处置(settings 单元的处置律见 §15)。

package/llms-full.txt

@@ -1,6 +1,6 @@
 <!--
 llms-full.txt — 自包含全文 · 消费方(使用者)视角 · @sema-agent/settings-schema
-重写日期: 2026-11-02 | 包版本: 17.1.0
+重写日期: 2026-11-02 | 包版本: 17.2.0
 生成方式: 无生成脚本——按当前树 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版。
 证据约定: 每条"它怎么工作"的断言附 (文件: 符号) 坐标,刻意不用行号(行号逐版腐烂;符号名由
 typecheck 与 test/package-surface.test.ts、test/docs-hygiene.test.ts 等常驻门钉住)。无证据推断显式标【推断】。
@@ -364,6 +364,7 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
 - settings 单元表(14.6.0,`src/settings-units.ts`,主 barrel):`SETTINGS_UNITS` 十单元(path / category / reads / reading)、
   `unitTighten(unit, member?)`、`readSettingsUnit(unit, raw, member?)`(manual ⇒ default、"disable" ⇒ true、false 仍 false、
   bypassPermissions ⇒ launch_only;表外与 undefined / null ⇒ unreadable;收下原样返回)。
+  `member` / `members` 单元里 `unreadable` 的成员**不是缺席**:类目 `fail:closed` 时 `loosen` 成员可丢(要响)、`tighten` 成员必须持住并给最严答案;方向读 `memberAdmission(category, member).direction`,读数不带方向(docs/CONSUMER-INTEGRATION.md §15)。
 - 信任阶梯(1.2.0):`trustRank`(managed 6 > global 5 > project 4 > local 3 > session 2 > task 1)、
   `isAtLeast`;`MinTrust` 含 `task`(声明序非阶梯,阶梯唯一真源是 `trustRank`)。
   词表是一只纯常量 `MIN_TRUST_WORDS`(`local, session, project, global, managed, task`;`MinTrust` zod 枚举由它派生):`trustRank` 的闭包自由名 = `MIN_TRUST_WORDS` + JS 内建
@@ -529,6 +530,9 @@ entitlement/execution/limits = `none`;`projects` = `salvage`,整域档位仍 `"t
 - `validateDomain`/`validateRemoteExec` → `ValidateResult`(不 throw 用户数据)、`writeDomainFile`/
   `domainFilePath`、`listRequiredEnvNames` → `RequiredEnvName[]`。
 - `exportBundle`/`writeBundle`/`readBundle`(`ConfigBundle` 的键 = `PortableDomain`;11.0.0 起三只函数类型层只收可搬域,非便携域在运行期也拒)。
+- 同步孪生(17.2.0,`./node`):`readConfigDFileReadingSync(root, name)` → `ConfigDReading`(`absent` / `present{value}` / `refused{reason,error,thrown,fingerprint}`;与包内异步读口同一只纯判、同一个缺席尾)、
+  `readEnvModelsDecisionSync(root)` / `writeEnvModelsDecisionSync(root, word, { write })`(决定文档;与异步口同字节读法 / 缺席律 / 写计划 / 原子写原语;不收注入座)。
+  根桶 `isExplicitlyDisabledEntry(entry)` = 「显式停用」(自有数据属性 `enabled` 恰为 `false`)的唯一写处,三态读数不出口。(src/config-d-file.ts: readConfigDFileReadingSync;src/config-root-node.ts: readEnvModelsDecisionSync / writeEnvModelsDecisionSync;src/catalog-manages.ts: isExplicitlyDisabledEntry)
 - `FileConfigStore.read()` → `FileConfigRead`(16.0.0,`./node`;单读口,取代 15.2.0 的 `inspectBundle`):一次读完 `config.d` 里契约读的每一份文档(全部便携域 + retired 域的墓碑文档,每份只读一次),
   交一个结局 —— 文件层都读得进 ⇒ `{ kind: "effective", effective, warnings }`(effective 与严读 `getEffective()` 逐位同;读侧告警交成数据,不经 `onWarning`);
   有文档被拒 ⇒ `{ kind: "refused", refusals, version, warnings }`。每条拒 `ConfigDocumentRefusal`(包根的类型,按 `reason` 判别):`{ document, reason, error }`,`reason` ∈ 闭集词 `CONFIG_DOCUMENT_REFUSAL_REASONS`

package/llms.txt

@@ -1,6 +1,6 @@
 <!--
 llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
-重写日期: 2026-11-02 | 包版本: 17.1.0
+重写日期: 2026-11-02 | 包版本: 17.2.0
 生成方式: 无生成脚本——按当前树的 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版;
 每条断言附证据坐标(文件:符号),刻意不用行号(行号随每版腐烂,符号名由 typecheck/test 钉住)。
 刷新触发: package.json 版号变更(test/docs-hygiene.test.ts D 组钉「包版本:」与 package.json 相等、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "17.1.0",
+  "version": "17.2.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, 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",