@sema-agent/settings-schema 17.1.0 → 18.0.0

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/center-refs.d.ts

@@ -8,8 +8,9 @@
  * ## 律(一条)
  * 引用表怎么读、每个变量怎么问、读不出怎么说,只有这一处:
  *  · **引用表经公开的记录读器读**({@link readPlainStringRecord}:同一个函数、同一张原因词表 {@link PLAIN_STRING_RECORD_FAULTS}),不另写形状 / 描述符判据。读不出(整张不是纯数据、有成员的变量名不是串、
- *    读成员就抛、叫 `__proto__` 的成员)⇒ 整台结论 `refs_unreadable`,带读器的词,**一个变量都不问** —— 引用表本身不可信时,问了的值也没有可以挂的地方。
- *    读器会把叫 `__proto__` 的串值成员**剔出副本**交其余;本口不许这样悄悄丢一条引用再挂一台少了鉴权的 server,所以同样答 `refs_unreadable`、词 `member_name_reserved`。
+ *    读成员就抛、叫保留名 `__proto__` / `constructor` / `prototype` 的成员)⇒ 整台结论 `refs_unreadable`,带读器的词,**一个变量都不问** —— 引用表本身不可信时,问了的值也没有可以挂的地方。
+ *    读器会把叫保留名的串值成员**剔出副本**交其余;本口不许这样悄悄丢一条引用再挂一台少了鉴权的 server,所以同样答 `refs_unreadable`、词 `member_name_reserved`,点名第一个(自有键序)。
+ *    保留名只有一张表(`./reserved-member-name`):域 schema 的凭据引用集合拒同一组名字,两个读口同答。
  *  · **查找函数 `lookup(name)` 由调用方给**,本口**不读 `process.env`**(源里没有 `process` / `globalThis`;宿主怎么读环境、读哪一层环境、要不要缓存,都是调用方的事)。没给 / 不是函数 ⇒ `TypeError`
  *    (这是调用方的编程错,不是数据错:不折成成员的 `read_threw`,更不回落任何环境)。
  *  · 每个成员恰问一次 `lookup`(按引用表副本的自有键序 —— 整数形的键在前、其余按记录列出的次序;实参只有变量名一个),判成**一个词**({@link CenterRefMemberVerdict}):
@@ -23,7 +24,7 @@
  *
  * ## 读数的构造
  * 成员表用 `map`,`values` 用 `Object.defineProperty` + 零原型描述符({@link dataDescriptor})逐键写进一个新对象(定义语义,不走 [[Set]]):`Object.prototype` 上挂了数字键 setter 时目标键 `"0"` 的值也不会被吞;
- * `constructor` / `toString` 这类原型链上的名字作目标键照落成自有数据属性。交出的 `values` 原型是 `Object.prototype`,与读器交出的副本同形。
+ * `toString` / `hasOwnProperty` 这类不在保留名表里的原型链名字作目标键照落成自有数据属性。交出的 `values` 原型是 `Object.prototype`,与读器交出的副本同形。
  */
 import { type PlainStringRecordFault } from "./mcp-request-entry.js";
 /** 一个成员没解到的**原因词**,闭集,三个:`missing_name`(查找函数答 `undefined` —— 变量没设)· `not_a_string`(答了别的种类)· `read_threw`(查找函数抛了)。消费方按词分派,穷尽 `switch`,不读句子(本口没有句子)。 */

package/dist/center-refs.js

@@ -8,8 +8,9 @@
  * ## 律(一条)
  * 引用表怎么读、每个变量怎么问、读不出怎么说,只有这一处:
  *  · **引用表经公开的记录读器读**({@link readPlainStringRecord}:同一个函数、同一张原因词表 {@link PLAIN_STRING_RECORD_FAULTS}),不另写形状 / 描述符判据。读不出(整张不是纯数据、有成员的变量名不是串、
- *    读成员就抛、叫 `__proto__` 的成员)⇒ 整台结论 `refs_unreadable`,带读器的词,**一个变量都不问** —— 引用表本身不可信时,问了的值也没有可以挂的地方。
- *    读器会把叫 `__proto__` 的串值成员**剔出副本**交其余;本口不许这样悄悄丢一条引用再挂一台少了鉴权的 server,所以同样答 `refs_unreadable`、词 `member_name_reserved`。
+ *    读成员就抛、叫保留名 `__proto__` / `constructor` / `prototype` 的成员)⇒ 整台结论 `refs_unreadable`,带读器的词,**一个变量都不问** —— 引用表本身不可信时,问了的值也没有可以挂的地方。
+ *    读器会把叫保留名的串值成员**剔出副本**交其余;本口不许这样悄悄丢一条引用再挂一台少了鉴权的 server,所以同样答 `refs_unreadable`、词 `member_name_reserved`,点名第一个(自有键序)。
+ *    保留名只有一张表(`./reserved-member-name`):域 schema 的凭据引用集合拒同一组名字,两个读口同答。
  *  · **查找函数 `lookup(name)` 由调用方给**,本口**不读 `process.env`**(源里没有 `process` / `globalThis`;宿主怎么读环境、读哪一层环境、要不要缓存,都是调用方的事)。没给 / 不是函数 ⇒ `TypeError`
  *    (这是调用方的编程错,不是数据错:不折成成员的 `read_threw`,更不回落任何环境)。
  *  · 每个成员恰问一次 `lookup`(按引用表副本的自有键序 —— 整数形的键在前、其余按记录列出的次序;实参只有变量名一个),判成**一个词**({@link CenterRefMemberVerdict}):
@@ -23,9 +24,9 @@
  *
  * ## 读数的构造
  * 成员表用 `map`,`values` 用 `Object.defineProperty` + 零原型描述符({@link dataDescriptor})逐键写进一个新对象(定义语义,不走 [[Set]]):`Object.prototype` 上挂了数字键 setter 时目标键 `"0"` 的值也不会被吞;
- * `constructor` / `toString` 这类原型链上的名字作目标键照落成自有数据属性。交出的 `values` 原型是 `Object.prototype`,与读器交出的副本同形。
+ * `toString` / `hasOwnProperty` 这类不在保留名表里的原型链名字作目标键照落成自有数据属性。交出的 `values` 原型是 `Object.prototype`,与读器交出的副本同形。
  */
-import { PLAIN_STRING_RECORD_RESERVED_MEMBER, readPlainStringRecord } from "./mcp-request-entry.js";
+import { readPlainStringRecord } from "./mcp-request-entry.js";
 import { dataDescriptor, inspect } from "./own-key-read.js";
 /** 一个成员没解到的**原因词**,闭集,三个:`missing_name`(查找函数答 `undefined` —— 变量没设)· `not_a_string`(答了别的种类)· `read_threw`(查找函数抛了)。消费方按词分派,穷尽 `switch`,不读句子(本口没有句子)。 */
 export const CENTER_REF_FAULTS = ["missing_name", "not_a_string", "read_threw"];
@@ -55,8 +56,9 @@ export function resolveCenterRefs(refs, lookup) {
     const read = readPlainStringRecord(refs);
     if (!read.ok)
         return { verdict: "refs_unreadable", fault: read.fault, ...(read.member !== undefined ? { member: read.member } : {}) };
-    if (read.reservedMember)
-        return { verdict: "refs_unreadable", fault: "member_name_reserved", member: PLAIN_STRING_RECORD_RESERVED_MEMBER };
+    const [reserved] = read.reservedMembers;
+    if (reserved !== undefined)
+        return { verdict: "refs_unreadable", fault: "member_name_reserved", member: reserved };
     const judged = Object.entries(read.record).map((pair) => ({ key: pair[0], ref: pair[1], answer: answerOf(pair[1], lookup) }));
     const members = judged.map((j) => ({ key: j.key, ref: j.ref, verdict: j.answer.verdict }));
     if (judged.some((j) => j.answer.verdict !== "resolved"))

package/dist/cli.d.ts

@@ -35,5 +35,5 @@ export interface SettingsSchemaCliIo extends ConfigDirectoryIo {
     stderr(text: string): void;
 }
 /** 命令行的覆盖面:全部配置域、retired 域(便携与否不论 —— 离线的 `workers.json` 一样迁)与 `remote-exec.json`。 */
-export declare const COVERED_DOCUMENTS: ("remote-exec" | "models" | "rosters" | "scenarios" | "skills" | "execution" | "plugins" | "systems" | "limits" | "runtime" | "workers" | "hosts" | "projects" | "mcp" | "collab" | "governance" | "entitlement" | "prompts")[];
+export declare const COVERED_DOCUMENTS: ("remote-exec" | "models" | "rosters" | "scenarios" | "skills" | "execution" | "plugins" | "systems" | "limits" | "runtime" | "workers" | "hosts" | "projects" | "mcp" | "collab" | "governance" | "entitlement" | "prompts" | "a2a")[];
 export declare function runSettingsSchemaCli(argv: readonly string[], io: SettingsSchemaCliIo): Promise<number>;

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-fns.d.ts

@@ -570,6 +570,7 @@ export declare const DOMAIN_READ_FALLBACK: {
     readonly projects: "throw";
     readonly prompts: "default";
     readonly limits: "throw";
+    readonly a2a: "default";
 };
 /** Per-domain ENTRY-SALVAGE policy (12.3.0, S-1494) — may the view-face domain reader ({@link parseDomainSalvaged}) drop single bad
  *  entries (an array element, a Record value, and — recursively — a bad entry inside a surviving entry) and read the rest?
@@ -605,7 +606,10 @@ export declare const DOMAIN_READ_FALLBACK: {
  *    - governance: NONE — a dropped commandPolicy / approvalRequire row is a guardrail silently gone (放权,不许).
  *    - entitlement: NONE — a dropped tier / subject / binding / budget group changes who may do what (放权,不许).
  *    - execution: NONE — a dropped lane / public key changes the execution mandate (放权,不许).
- *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings). */
+ *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings).
+ *    - a2a: SALVAGE (18.0.0) — the peer roster is a capability catalog like mcp: a dropped peer is one remote agent fewer. A peer's
+ *      credential references (`headerRefs`) are in {@link ATOMIC_SALVAGE}: a bad reference drops the whole peer, never the reference
+ *      alone (a peer kept with half of its credentials is the wrong failure direction). */
 export declare const DOMAIN_ENTRY_SALVAGE: {
     readonly models: "salvage";
     readonly rosters: "none";
@@ -623,6 +627,7 @@ export declare const DOMAIN_ENTRY_SALVAGE: {
     readonly projects: "salvage";
     readonly prompts: "none";
     readonly limits: "none";
+    readonly a2a: "salvage";
 };
 /** 一个读者向店要文档的口:配置域,以及墓碑表里的retired 域({@link RETIRED_DOMAINS})—— 后者只为让墓碑看见没迁的旧文档。 */
 export type StoredDocumentReader = (d: DomainName | RetiredDomainName) => unknown;

package/dist/config-fns.js

@@ -23,7 +23,7 @@ import { isJsonArray, isPlainJsonObject, jsonShapeOf } from "./plain-json-object
 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)
-import { DOMAIN_SCHEMAS, InfraCostRates, LimitsConfig, PRIVATE_KEY_PEM_HEADER, RETIRED_DOMAINS, SkillsManifestSchema, containsSecretToken, isDomainName, isRetiredDomainName, renderQuotedSentence, retiredDomainSentence } from "./types.js";
+import { ATOMIC_SALVAGE, DOMAIN_SCHEMAS, InfraCostRates, LimitsConfig, PRIVATE_KEY_PEM_HEADER, RETIRED_DOMAINS, SkillsManifestSchema, containsSecretToken, isDomainName, isRetiredDomainName, renderQuotedSentence, retiredDomainSentence } from "./types.js";
 /** Redact secret-shaped tokens from a validation MESSAGE — a zod error echoes the offending value (e.g.
  *  `received 'sk-live-…'`), so a secret pasted into the WRONG field would leak via the error string. Redacts
  *  space-spanning auth credentials (`Bearer <token>`) FIRST (the token pass can't see across the space), then
@@ -197,6 +197,10 @@ export const DOMAIN_WRITE_ROLE = {
     // limits (0.19.0): editor —— 与它的前身 runtime 域(11.0.0 retired)同档,刻意不抬 publisher:本域是纯数值
     // 旋钮,无 prompt 注入面、无凭据、无可执行内容;真正的执法点在消费方的限额闸,发布闸(PUBLISH_MODE /
     // 审批流)才是"要不要多一道人"的属主。default 即 editor,故不列条目;此注释即该裁定的落点。
+    // a2a (18.0.0): a peer is a remote agent whose skills are mounted into the agent's tool surface, plus the env-NAMEs that
+    // carry its credentials — the same executable-surface + credential-reference profile as mcp, so the same raised gate.
+    // Written out (not left to the default) because the default would be the WRONG answer here.
+    a2a: "publisher",
 };
 /** The minimum role required to write `domain` (the raised gate for skills/mcp, else editor). */
 export function domainWriteRole(domain) {
@@ -495,6 +499,9 @@ function salvageLayerUnsafe(schema, raw) {
     const patch = {};
     for (const [field, fieldSchema] of Object.entries(shape)) {
         const collection = unwrapSchema(fieldSchema);
+        // 凭据引用集合(按 schema 身份,见 ATOMIC_SALVAGE)不下钻:它是一个值,坏一项 ⇒ 它所属的条目在上一层整条判不过、整条丢。
+        if (ATOMIC_SALVAGE.has(collection))
+            continue;
         const isArray = collection instanceof z.ZodArray;
         if (!isArray && !(collection instanceof z.ZodRecord))
             continue; // 不是条目集合:连读都不读(少触发一次访问器)
@@ -1006,6 +1013,8 @@ export const DOMAIN_READ_FALLBACK = {
     // 降级成空域 = 中央发布的成本/限流天花板整片蒸发,消费方回自己的 env 底(可能宽得多)= 预算轴放权。
     // 消费方 fail-static 在上一份好配置严格更好。
     limits: "throw",
+    // a2a(18.0.0):能力目录(同 mcp)—— 整域读不进 ⇒ 空名册 = 不拨任何对端(能力消失,fail-closed;没有闸因此丢掉)。
+    a2a: "default",
 };
 /** Per-domain ENTRY-SALVAGE policy (12.3.0, S-1494) — may the view-face domain reader ({@link parseDomainSalvaged}) drop single bad
  *  entries (an array element, a Record value, and — recursively — a bad entry inside a surviving entry) and read the rest?
@@ -1041,7 +1050,10 @@ export const DOMAIN_READ_FALLBACK = {
  *    - governance: NONE — a dropped commandPolicy / approvalRequire row is a guardrail silently gone (放权,不许).
  *    - entitlement: NONE — a dropped tier / subject / binding / budget group changes who may do what (放权,不许).
  *    - execution: NONE — a dropped lane / public key changes the execution mandate (放权,不许).
- *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings). */
+ *    - limits: NONE — a dropped allowlist row changes a published ceiling (the domain is the one publishing seat of those ceilings).
+ *    - a2a: SALVAGE (18.0.0) — the peer roster is a capability catalog like mcp: a dropped peer is one remote agent fewer. A peer's
+ *      credential references (`headerRefs`) are in {@link ATOMIC_SALVAGE}: a bad reference drops the whole peer, never the reference
+ *      alone (a peer kept with half of its credentials is the wrong failure direction). */
 export const DOMAIN_ENTRY_SALVAGE = {
     models: "salvage",
     rosters: "none",
@@ -1059,6 +1071,7 @@ export const DOMAIN_ENTRY_SALVAGE = {
     projects: "salvage",
     prompts: "none",
     limits: "none",
+    a2a: "salvage",
 };
 /**
  * Merge every domain into the effective config a consumer pulls. Shared by all store impls.
@@ -1111,6 +1124,7 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
         // `{}` 不下发中心层,default 不扩权)。
         prompts: parseOr("prompts", getRaw("prompts")),
         limits: parseOr("limits", getRaw("limits")),
+        a2a: parseOr("a2a", getRaw("a2a")),
     };
 }
 /** READ-side tolerant judgment for a GET /effective **wire payload**(the {@link EffectiveWire} contract)at

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) {