@sema-agent/settings-schema 17.1.0 → 18.0.0

package/conformance/cases/c86-a2a-peers-legal/expected.json

@@ -0,0 +1,135 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "a2a": {
+        "peers": [
+          {
+            "allowSkills": [
+              "search"
+            ],
+            "enabled": true,
+            "headerRefs": {
+              "Authorization": "KB_TOKEN"
+            },
+            "name": "kb",
+            "principalHeader": "X-Principal",
+            "scenarios": [],
+            "url": "https://kb.example/a2a"
+          },
+          {
+            "cardUrl": "https://ops.example/agent-card.json",
+            "enabled": false,
+            "name": "ops",
+            "scenarios": [
+              "oncall"
+            ],
+            "url": "https://ops.example/"
+          }
+        ]
+      },
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {},
+      "rosters": {
+        "rosters": []
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-11-03T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {
+      "a2a": {
+        "peers": [
+          {
+            "allowSkills": [
+              "search"
+            ],
+            "enabled": true,
+            "headerRefs": {
+              "Authorization": "KB_TOKEN"
+            },
+            "name": "kb",
+            "principalHeader": "X-Principal",
+            "scenarios": [],
+            "url": "https://kb.example/a2a"
+          },
+          {
+            "cardUrl": "https://ops.example/agent-card.json",
+            "enabled": false,
+            "name": "ops",
+            "scenarios": [
+              "oncall"
+            ],
+            "url": "https://ops.example/"
+          }
+        ]
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-11-03T00:00:00.000Z"
+    },
+    "why": "受理:两个对端都合 `A2aPeerSpec`(URL 不带凭据与 fragment、头名合 token 文法、引用是 env-NAME、对端名可当线上名且不重名);严写收下的就是读腿 a2a 那一格。"
+  },
+  "wire": {
+    "derive": true
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 206605001400842
+  }
+}

package/conformance/cases/c86-a2a-peers-legal/input.json

@@ -0,0 +1,32 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-11-03T00:00:00.000Z"
+  },
+  "domains": {
+    "a2a": {
+      "peers": [
+        {
+          "name": "kb",
+          "url": "https://kb.example/a2a",
+          "headerRefs": {
+            "Authorization": "KB_TOKEN"
+          },
+          "principalHeader": "X-Principal",
+          "allowSkills": [
+            "search"
+          ]
+        },
+        {
+          "name": "ops",
+          "url": "https://ops.example/",
+          "cardUrl": "https://ops.example/agent-card.json",
+          "scenarios": [
+            "oncall"
+          ],
+          "enabled": false
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c86-a2a-peers-legal/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "`a2a`(常驻出站 A2A 对端名册)是便携域:两个合法对端在四条腿上同读 —— 缺省物化(缺 `scenarios` ⇒ `[]`、缺 `enabled` ⇒ `true`),停用的对端照样在表里(`enabled: false` 由读方过滤,不是读腿丢),header 值只以 env-NAME 引用出现(`headerRefs`),零告警。本地腿读 `config.d/a2a.json`:在没有这个域的包上,同一份文件报 `unread-config-file`、远端 `/effective.a2a` 原样透传 —— 一个仍按旧读法的读腿会把这条读成「对端名册缺席」或「未校验的原文」。",
+  "firstRedOn": []
+}

package/conformance/cases/c87-a2a-credential-refs-not-partially-salvaged/expected.json

@@ -0,0 +1,123 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "a2a": {
+        "peers": [
+          {
+            "enabled": true,
+            "headerRefs": {
+              "Authorization": "KB_TOKEN"
+            },
+            "name": "kb",
+            "scenarios": [],
+            "url": "https://kb.example/a2a"
+          },
+          {
+            "allowSkills": [
+              "search"
+            ],
+            "enabled": true,
+            "name": "narrow",
+            "scenarios": [],
+            "url": "https://narrow.example/a2a"
+          }
+        ]
+      },
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {},
+      "rosters": {
+        "rosters": []
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [
+      {
+        "domain": "a2a",
+        "identity": {
+          "name": "half"
+        },
+        "kind": "entry-dropped",
+        "path": [
+          "peers",
+          1
+        ],
+        "reasonCode": "entry-schema-invalid"
+      },
+      {
+        "domain": "a2a",
+        "kind": "entry-dropped",
+        "path": [
+          "peers",
+          2,
+          "allowSkills",
+          1
+        ],
+        "reasonCode": "entry-schema-invalid"
+      }
+    ],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-11-03T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:`half` 的一条 header 引用不是 env-NAME、`half` 与 `narrow` 的 `allowSkills` 各有一个空串 —— 写是一个动作,一处坏整份不受理。"
+  },
+  "wire": {
+    "derive": true
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 3675868689326288
+  }
+}

package/conformance/cases/c87-a2a-credential-refs-not-partially-salvaged/input.json

@@ -0,0 +1,39 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-11-03T00:00:00.000Z"
+  },
+  "domains": {
+    "a2a": {
+      "peers": [
+        {
+          "name": "kb",
+          "url": "https://kb.example/a2a",
+          "headerRefs": {
+            "Authorization": "KB_TOKEN"
+          }
+        },
+        {
+          "name": "half",
+          "url": "https://half.example/a2a",
+          "headerRefs": {
+            "Authorization": "HALF_TOKEN",
+            "X-Tenant": "not an env name"
+          },
+          "allowSkills": [
+            "search",
+            ""
+          ]
+        },
+        {
+          "name": "narrow",
+          "url": "https://narrow.example/a2a",
+          "allowSkills": [
+            "search",
+            ""
+          ]
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c87-a2a-credential-refs-not-partially-salvaged/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "凭据引用集合不可部分抢救:对端 `half` 的 `headerRefs` 里一条引用坏形(值不是 env-NAME)⇒ **整个对端** `entry-dropped`(域 `a2a`、坐标 `[\"peers\",1]`、身份 `half`),不是只丢那一条引用、留下一个带着一半凭据去拨远端的对端;兄弟 `kb` 原样保留。对照组 `narrow`:非凭据集合(`allowSkills`)里的坏元素照旧逐条丢(坐标 `[\"peers\",2,\"allowSkills\",1]`;丢了只会更窄),对端本身活下来。严写腿整份拒。一个对每个 Record 都逐条抢救的读腿会把 `half` 读成「只带 Authorization 的对端」。",
+  "firstRedOn": []
+}

package/conformance/cases/cc01-mcp-toolfaces-non-object/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -161,6 +164,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 197807763204275
+    "localVersion": 3253988119103129
   }
 }

package/conformance/cases/cc02-mcp-source-key-is-transported/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -107,6 +110,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 2482576595667034
+    "localVersion": 3591318400132154
   }
 }

package/conformance/cases/cc03-model-compat-unknown-subkey/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -116,6 +119,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 4345724001787046
+    "localVersion": 1663867526020649
   }
 }

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

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -112,6 +115,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 694685728514477
+    "localVersion": 2654544430240950
   }
 }

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

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -125,6 +128,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 4213710307592750
+    "localVersion": 3769852229872529
   }
 }

package/conformance/cases/cli03-credential-pasted-into-unknown-key/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -121,6 +124,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 2617555914511015
+    "localVersion": 1531100058823047
   }
 }

package/conformance/cases/cli04-env-value-with-newline/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -149,6 +152,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 2617555914511015
+    "localVersion": 1531100058823047
   }
 }

package/conformance/cases/cli05-long-and-prefix-colliding-names/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -148,6 +151,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 1318036626730287
+    "localVersion": 3555569200054848
   }
 }

package/conformance/cases/t01-absent-domain-key-not-null/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -91,6 +94,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 2247688933988744
+    "localVersion": 1409565868890479
   }
 }

package/conformance/cases/t03-prototype-name-key-not-swallowed/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -152,6 +155,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 3232605402901914
+    "localVersion": 3557208461559525
   }
 }

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

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -108,6 +111,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 2614200563056761
+    "localVersion": 3944259292559843
   }
 }

package/conformance/cases/z01-every-domain-empty-object/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -131,6 +134,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 499959296543014
+    "localVersion": 3006809479574243
   }
 }

package/conformance/cases/z02-every-domain-unknown-key/expected.json

@@ -2,6 +2,9 @@
   "domains": {
     "outcome": "effective",
     "effective": {
+      "a2a": {
+        "peers": []
+      },
       "collab": {
         "templates": []
       },
@@ -425,6 +428,6 @@
   },
   "localRoot": {
     "derive": true,
-    "localVersion": 567413778934550
+    "localVersion": 1287865876181806
   }
 }

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