@sema-agent/settings-schema 15.2.0 → 17.0.0

package/dist/execution-lanes.js

@@ -17,6 +17,8 @@
  *  · `tenantSeparation`:同文件 `executionLaneCaps` 每臂的 `tenantSeparation` 位(:209 host / :230 e2b / :249 k8s /
  *    :269 ssh / :288 adb / :308 local-docker / :327 device)。`tenantSeparationBasis`(11.0.0):分租户的那几臂凭什么分 ——
  *    e2b / k8s / local-docker 每任务一只隔离目标(`isolation`),device 是发起者自己的设备(`principal-binding`)。
+ *  · `singleReplica`(16.0.0):这条车道的执行目标挂在**一个副本**上 —— host 是副本自己的文件系统,device 是设备连上的那一个副本
+ *    (设备的连接落在一个副本上,跨副本把会话送到它的设备今天没有)。表里有一条这种车道的 worker 只能一个副本(写闸按这一列判,不点名车道词)。
  *  · `requiredEnv ∪ requiredSecretEnv`:这条车道缺了就起不了服的键。最初逐字抄自 `src/config.ts` 的手写表 `REQUIRED_ENVS_BY_LANE`(:1054),
  *    那张手写表已退役 —— 服务端的必需 env 门按本表行的这两栏拒启,部署面的车道清单读同一行,所以今天**本表就是**必需键的唯一来源。按 `src/config-catalog.ts`
  *    该键那一行的值类型分栏 —— 类型 `secret` / `opaque`(目录自己「绝不回显值」的两类)进 `*SecretEnv`,其余进 `*Env`。
@@ -56,6 +58,7 @@ const LANE_ROWS = {
     /** server `config.ts` :4014 臂(无必需键);`execution-lane-caps.ts` :209 `single-user-only`(所有任务落 worker 宿主)。 */
     host: {
         tenantSeparation: "single-user-only",
+        singleReplica: true,
         requiredEnv: [],
         requiredSecretEnv: [],
         optionalEnv: ["HOST_WORKSPACE_BASE", "HOST_COMMAND_TIMEOUT_MS"],
@@ -66,6 +69,7 @@ const LANE_ROWS = {
     e2b: {
         tenantSeparation: "supported",
         tenantSeparationBasis: "isolation",
+        singleReplica: false,
         requiredEnv: [],
         requiredSecretEnv: ["E2B_API_KEY"],
         optionalEnv: ["E2B_TEMPLATE", "E2B_TIMEOUT_MS", "E2B_LIVENESS_MS", "E2B_ALLOW_NET", "E2B_MOUNT_PATH", "E2B_ORPHAN_RECLAIM"],
@@ -78,6 +82,7 @@ const LANE_ROWS = {
     k8s: {
         tenantSeparation: "supported",
         tenantSeparationBasis: "isolation",
+        singleReplica: false,
         requiredEnv: ["K8S_SANDBOX_IMAGE", "K8S_NAMESPACE"],
         requiredSecretEnv: [],
         optionalEnv: [
@@ -98,6 +103,7 @@ const LANE_ROWS = {
      *  `execution-lane-caps.ts` :269 `single-user-only`(一台跨任务共享的常驻真机)。 */
     ssh: {
         tenantSeparation: "single-user-only",
+        singleReplica: false,
         requiredEnv: ["SSH_HOST", "SSH_USER"],
         requiredSecretEnv: ["SSH_PRIVATE_KEY"],
         optionalEnv: ["SSH_PORT", "SSH_MOUNT_PATH", "SSH_HOST_FINGERPRINT", "SSH_KNOWN_HOSTS"],
@@ -106,6 +112,7 @@ const LANE_ROWS = {
     /** server `config.ts` :4006 臂;`execution-lane-caps.ts` :288 `single-user-only`(一台跨任务共享的设备)。 */
     adb: {
         tenantSeparation: "single-user-only",
+        singleReplica: false,
         requiredEnv: ["ADB_SERIAL"],
         requiredSecretEnv: [],
         optionalEnv: ["ADB_PATH", "ADB_MOUNT_PATH"],
@@ -116,6 +123,7 @@ const LANE_ROWS = {
     "local-docker": {
         tenantSeparation: "supported",
         tenantSeparationBasis: "isolation",
+        singleReplica: false,
         requiredEnv: ["DOCKER_IMAGE"],
         requiredSecretEnv: [],
         optionalEnv: [
@@ -131,12 +139,14 @@ const LANE_ROWS = {
         ],
         optionalSecretEnv: ["DOCKER_SANDBOX_ENV"],
     },
-    /** server `config.ts` :4055 臂 + `parseDevicePreAuthPerRemoteEnv` :871 / `parseDeviceEnrollTokenTtlEnv` :857(无必需键:设备是运行期
-     *  连进来的);`execution-lane-caps.ts` :327 `supported`(发起者自己的设备)。 */
+    /** server `config.ts` :4055 臂 + `parseDevicePreAuthPerRemoteEnv` :871 / `parseDeviceEnrollTokenTtlEnv` :857;`execution-lane-caps.ts` :327
+     *  `supported`(发起者自己的设备)。16.0.0:`DEVICE_RELAY_URL`(设备拨哪里)是**必需**坐标 —— 引擎的 device 臂缺它即拒启
+     *  (`parseDeviceRelayUrlEnv`;此前它是 device 臂读而本表漏登记的键),值只有两种:ws(s) 绝对 URL 或字面 `none`(值的文法见 `./device-relay`)。 */
     device: {
         tenantSeparation: "supported",
         tenantSeparationBasis: "principal-binding",
-        requiredEnv: [],
+        singleReplica: true,
+        requiredEnv: ["DEVICE_RELAY_URL"],
         requiredSecretEnv: [],
         optionalEnv: [
             "DEVICE_DELIVERY_TIMEOUT_MS",
@@ -157,6 +167,7 @@ export const EXECUTION_LANES = Object.freeze(EXECUTION_LANE_WORDS.map((lane) =>
     return Object.freeze({
         lane,
         ...tenancy,
+        singleReplica: row.singleReplica,
         requiredEnv: Object.freeze([...row.requiredEnv]),
         requiredSecretEnv: Object.freeze([...row.requiredSecretEnv]),
         optionalEnv: Object.freeze([...row.optionalEnv]),
@@ -166,7 +177,7 @@ export const EXECUTION_LANES = Object.freeze(EXECUTION_LANE_WORDS.map((lane) =>
 /**
  * 车道坐标的**唯一判官**:一个必需坐标「未设 / 空串 / 只含空白」一律算缺。本函数判其中的后两种,且只看**已经有的字符串值**:空串,或只含空白(`String.prototype.trim` 认的空白:空格 / 制表 / 换行 / 不换行空格 / 字节序标记 …)⇒ `true`;
  * 「这一键根本没设」由调用方先判(写闸对没设的键另有一句 `requires coords.<键>`,两种缺法同样被拒)。
- * 写闸对所有车道、所有必需坐标同判这一只;它只判「是不是空白」,不 trim 值、不管值的格式(格式不在这一条的范围:`" sandboxes "` 不是空白)。
+ * 写闸对所有车道、所有必需坐标同判这一只;本地文件契约 `RemoteExecSpec`(`config.d/remote-exec.json`)的每个非空串字段(镜像 / 命名空间 / 主机 / 路径 / …)问的也是这一只(16.0.0 起:同一个部署声明在两处说,「空白」不再有两种读法);它只判「是不是空白」,不 trim 值、不管值的格式(格式不在这一条的范围:`" sandboxes "` 不是空白)。
  * 它只答「这个值是不是空白」,不管这个键是必需还是可选:据它**拒不拒**一个坐标,由调用方按键的必需 / 可选决定 —— 写闸只对必需坐标据它拒;个别可选坐标上空串有语义(如 `K8S_RUNTIME_CLASS` 的空串 = 不用 Kata),可选坐标的空串照收。
  *
  * 住在这个零依赖的叶模块里:包根(`export *`)与 `./execution-lanes` 子路径是**同一个函数对象** —— 只想问这一个问题的消费方走子路径,不必冷载入整只契约包桶;
@@ -180,5 +191,6 @@ export const STORE_BACKENDS = ["mysql", "pg", "local", "memory"];
 /** session 店(→ `SESSION_BACKEND`)。= server `src/config.ts` :1760 `enumEnv("SESSION_BACKEND", …)` 的词表逐字同序
  *  (`tidb` 不在集内:引擎见之拒启)。 */
 export const SESSION_BACKENDS = ["memory", "mysql", "auto"];
-/** 记忆持久面方言(→ `MEMORY_ENGINE_BACKEND`)。= server `src/config.ts` :3436 闭集 / 目录 :468 `enumValues` 逐字同序。 */
-export const MEMORY_ENGINE_BACKENDS = ["file", "pg", "tidb"];
+/** 记忆持久面方言(→ `MEMORY_ENGINE_BACKEND`)。16.0.0:MySQL 族那一只叫 `mysql`(此前 `tidb` —— 同一只 SQL 店有店词 `mysql` 与方言 `tidb` 两个字;
+ *  收成一个字,与 {@link STORE_BACKENDS} 同字;硬破坏,`tidb` 读写两面拒、指路一次性迁移 SS-M12)。次序 file → pg → mysql。 */
+export const MEMORY_ENGINE_BACKENDS = ["file", "pg", "mysql"];

package/dist/file-store.d.ts

@@ -1,10 +1,11 @@
 import { type EffectiveReadWarning } from "./config-fns.js";
+import type { ConfigDocumentRefusal } from "./config-document-refusal.js";
 import type { ConfigReader } from "./reader.js";
 import { type DomainConfig, type DomainName, type EffectiveConfig, type RetiredDomainName } from "./types.js";
 export { NON_PORTABLE_DOMAIN_REASONS, PORTABLE_DOMAINS, type PortableDomain } from "./portable-domains.js";
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
- *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
+ *  ——**它有自己的校验路径**(读盘与域文档同一只 `config.d` 文档读法,值判是 `RemoteExecSpec`),所以既不是「未知文件」也不是「域文件」。
  *
  *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
  *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
@@ -21,6 +22,23 @@ export type TolerantEffective = {
     effective: EffectiveConfig;
     domainErrors: DomainReadError[];
 };
+/** 单读口 {@link FileConfigStore.read} 的答案(按 `kind` 判别的闭集两臂;消费方 `switch` 穷举)。两臂都带 `warnings`(读侧告警交成数据,不经 `onWarning`)。 */
+export type FileConfigRead = 
+/** 每份文档都读得进:`effective` 与严读 `getEffective()` 逐位同(同一份快照、同一个版本);`warnings` = 没人读的文件 + 装配时的读侧告警。 */
+{
+    readonly kind: "effective";
+    readonly effective: EffectiveConfig;
+    readonly warnings: readonly EffectiveReadWarning[];
+}
+/** 至少一份文档在文件层被拒:`refusals` = 整棵目录的拒单(次序确定:retired 域文档在前,按墓碑表的声明次序;便携域按 `PORTABLE_DOMAINS` 的次序);
+ *  `version` = 这一次读到的整棵目录的内容版本(被拒的文档以坏文档的指纹参与 —— 与宽容读的坏文件哨兵同一只:同样的坏内容同一个数、坏内容变了换数、
+ *  绝不与「文件缺席」同数);`warnings` = 没人读的文件(装配没有发生)。 */
+ | {
+    readonly kind: "refused";
+    readonly refusals: readonly ConfigDocumentRefusal[];
+    readonly version: number;
+    readonly warnings: readonly EffectiveReadWarning[];
+};
 export declare class FileConfigStore implements ConfigReader {
     #private;
     private readonly root;
@@ -37,9 +55,10 @@ export declare class FileConfigStore implements ConfigReader {
     domainPath(domain: DomainName | RetiredDomainName): string;
     /** Read+parse one domain (validated, defaults filled), or `undefined` if the domain is ABSENT — matching
      *  the {@link ConfigReader} contract (reader.ts: absent domain → undefined) and the server stores'
-     *  `has(domain) ? parse : undefined`. A present-but-empty file (`{}` / whitespace) IS a set domain → parsed
-     *  with defaults; a missing file is absence → undefined. (getEffective still fills defaults for absent
-     *  domains; getDomain is the per-domain "was this ever set?" probe.) */
+     *  `has(domain) ? parse : undefined`. Only an ABSENT file (ENOENT with nothing at the path; a dangling symlink is not absence) is absence → undefined. A present `{}` IS a set
+     *  domain → parsed with defaults. A present file that is empty or whitespace-only (a half-write) throws as a corrupt file,
+     *  as do bad JSON, a non-object, an unreadable file and one nested too deep (the same reading as getEffective / readBundle).
+     *  (getEffective still fills defaults for absent domains; getDomain is the per-domain "was this ever set?" probe.) */
     getDomain<K extends DomainName>(domain: K): Promise<DomainConfig[K] | undefined>;
     /** All portable domains → EffectiveConfig. The PAYLOAD and its `version` come from ONE raws snapshot (no
      *  re-read between them — else a concurrent atomic rename could pair payload A with version B and a consumer
@@ -64,4 +83,12 @@ export declare class FileConfigStore implements ConfigReader {
     /** Stable version number for the current files: same files ⇒ same number ⇒ a consumer's "skip re-apply if
      *  version unchanged" works locally too. */
     getVersion(): Promise<number>;
+    /**
+     * **单读口**(16.0.0):一次读整棵 `config.d`(全部便携域 + retired 域的墓碑文档,每份只读一次),交一个结局({@link FileConfigRead})——
+     *  · 每份文档在文件层都读得进 ⇒ `effective`:与严读 `getEffective()` 逐位同;读侧告警交成数据(没人读的文件 + 装配告警,不经 `onWarning`);
+     *  · 有文档在文件层被拒(空 / 坏 JSON / 不是对象 / 读不出 / 过深;带事实的 retired 域文档是墓碑拒,带迁移编号)⇒ `refused`:整棵目录的拒单与这一次读到的内容版本。
+     * 严读与 `readBundle` 读的是同一只文件读法(`./config-d-file` 的读数)—— 同一种坏形同一个词、同一句话;区别只在渲染:严读遇到第一份坏文档就抛,本方法把整个目录读完、逐份交出。
+     * 文件层之外的拒(读得出、过不了门控域的 schema)照严读抛 —— 那是判形,不在拒单里。拒单、版本、effective、告警都出自这一次读到的字节:没有「先抛、再重探」的第二次读。
+     */
+    read(): Promise<FileConfigRead>;
 }

package/dist/file-store.js

@@ -11,9 +11,12 @@
  *   <root>/.env        secret VALUES (KEY=value) — the ONLY file holding secrets; gitignored, never read here.
  *
  * Rules:
- *  - A MISSING file (ENOENT) → the domain is absent → schema defaults fill in (parseDomain tolerates undefined).
+ *  - An ABSENT file (nothing at the path: ENOENT, and neither the file nor `config.d` is a dangling symlink) → the domain is absent → schema defaults
+ *    fill in (parseDomain tolerates undefined). A DANGLING symlink is present-but-unreadable (a refusal, `io`), never absence.
  *    A present-but-EMPTY/whitespace file is a half-write → THROW (fail-closed, like remote-exec); to mean
  *    "absent/defaults" the file must be missing, not empty. A valid `{}` object IS a set domain (→ defaults).
+ *  - `read()` (16.0.0) is the ONE read that answers both ways: the effective config + its read warnings as data when every
+ *    document reads, or the typed refusal list of the whole directory + its version when one does not — every document read once.
  *  - Non-portable domains are OMITTED on a single machine and resolve to their schema defaults (`{workers:[]}`
  *    etc.) — no stubbing needed. 逐域为什么被排除见 {@link NON_PORTABLE_DOMAIN_REASONS}(禁裸排除)。
  *  - A RETIRED domain's file (`config.d/runtime.json`, see `RETIRED_DOMAINS`) is read only for its tombstone: carrying facts ⇒
@@ -26,7 +29,7 @@
  */
 import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
-import { buildEffective, DOMAIN_READ_FALLBACK, parseDomainLoud } from "./config-fns.js";
+import { RetiredDomainError, buildEffective, DOMAIN_READ_FALLBACK, parseDomainLoud, refuseRetiredDomain } from "./config-fns.js";
 import { RETIRED_DOMAIN_NAMES, configDPath, configDVersionOf, corruptDocumentRaw, readConfigDFile, readConfigDFileReading, refuseRetiredDomainFiles } from "./config-d-file.js";
 import { PORTABLE_DOMAINS } from "./portable-domains.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
@@ -35,7 +38,7 @@ import { isDomainName, isRetiredDomainName } from "./types.js";
 export { NON_PORTABLE_DOMAIN_REASONS, PORTABLE_DOMAINS } from "./portable-domains.js";
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
- *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
+ *  ——**它有自己的校验路径**(读盘与域文档同一只 `config.d` 文档读法,值判是 `RemoteExecSpec`),所以既不是「未知文件」也不是「域文件」。
  *
  *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
  *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
@@ -57,7 +60,7 @@ export class FileConfigStore {
         return configDPath(this.root, domain); // the one name guard (no traversal) lives there
     }
     /** Read + JSON.parse one domain file —— the ONE `config.d/` file reading (`./config-d-file`, shared with `readBundle`): a MISSING
-     *  file (ENOENT) → undefined = the domain is ABSENT (the ONLY way to mean "use defaults"); a present file that is EMPTY/whitespace-only,
+     *  file (nothing at the path — ENOENT and not a dangling symlink) → undefined = the domain is ABSENT (the ONLY way to mean "use defaults"); a present file that is EMPTY/whitespace-only,
      *  or parses to anything but a JSON OBJECT, is CORRUPT → throw, FAIL CLOSED (an empty present file is a half-write/truncation, NOT
      *  "absent": treating it as absent would silently DROP a published domain — e.g. a truncated governance.json drops its
      *  commandPolicy/autonomy guardrails). This also keeps getVersion in lock-step with getEffective/getDomain: stableStringify collapses
@@ -84,6 +87,11 @@ export class FileConfigStore {
         const onWarning = this.opts.onWarning;
         if (!onWarning)
             return;
+        for (const w of await this.#unreadFiles())
+            onWarning(w);
+    }
+    /** {@link #warnUnreadFiles} 的扫描本体:没人读的 `*.json` 逐个一条告警(单读口 `read()` 把它们交成数据,所以它总扫)。 */
+    async #unreadFiles() {
         let names;
         try {
             names = await readdir(path.join(this.root, "config.d"));
@@ -91,8 +99,9 @@ export class FileConfigStore {
         catch {
             // 目录读不了(不存在 / 只有 x 没有 r 的目录权限)⇒ 本次扫不了,**不抛**:这条是尽力而为的审计线,
             // 绝不能把一次本来能成功的 getEffective 拖成失败(域文件本身仍按名逐个打开,该失败的自然会失败)。
-            return;
+            return [];
         }
+        const out = [];
         for (const name of names) {
             if (name.startsWith(".") || !name.endsWith(".json") || NON_DOMAIN_CONFIG_FILES.has(name))
                 continue;
@@ -101,10 +110,11 @@ export class FileConfigStore {
                 continue; // 真被读的域
             if (isRetiredDomainName(base))
                 continue; // retired 域:由墓碑判(带事实 ⇒ getEffective 抛),不是「没人读的文件」
-            onWarning(isDomainName(base)
+            out.push(isDomainName(base)
                 ? { kind: "unread-config-file", file: name, domain: base, why: "non-portable-domain" }
                 : { kind: "unread-config-file", file: name, why: "not-a-domain" });
         }
+        return out;
     }
     /** Raw (unparsed) values for every PORTABLE domain and every retired domain (the latter for the tombstone), keyed by
      *  name (absent → undefined). Both feed the version hash: a retired file appearing / changing flips `getEffective`
@@ -133,21 +143,22 @@ export class FileConfigStore {
     }
     /** Read+parse one domain (validated, defaults filled), or `undefined` if the domain is ABSENT — matching
      *  the {@link ConfigReader} contract (reader.ts: absent domain → undefined) and the server stores'
-     *  `has(domain) ? parse : undefined`. A present-but-empty file (`{}` / whitespace) IS a set domain → parsed
-     *  with defaults; a missing file is absence → undefined. (getEffective still fills defaults for absent
-     *  domains; getDomain is the per-domain "was this ever set?" probe.) */
+     *  `has(domain) ? parse : undefined`. Only an ABSENT file (ENOENT with nothing at the path; a dangling symlink is not absence) is absence → undefined. A present `{}` IS a set
+     *  domain → parsed with defaults. A present file that is empty or whitespace-only (a half-write) throws as a corrupt file,
+     *  as do bad JSON, a non-object, an unreadable file and one nested too deep (the same reading as getEffective / readBundle).
+     *  (getEffective still fills defaults for absent domains; getDomain is the per-domain "was this ever set?" probe.) */
     async getDomain(domain) {
         await refuseRetiredDomainFiles(this.root); // every read entry asks the tombstone first (exportBundle reads through here)
         const raw = await this.#readDomainRaw(domain);
         if (raw === undefined)
-            return undefined; // missing/empty file → domain absent (not schema defaults)
+            return undefined; // absent file (nothing at the path) → domain absent (not schema defaults); a corrupt or unreadable file (empty, bad JSON, dangling symlink …) threw above
         // 0.19.0(对抗复审 复审 round2 F3):与 buildEffective **同一条** parse-and-warn 判据。此前本方法直接
         // parseDomain,于是 `exportBundle`(它就是逐域走 getDomain 读的)会把一份携带未知键的域**静默剥**
         // 成一份"干净"的 bundle —— 再 import 回去就是一次持久的配置丢失,全程零告警。
         return parseDomainLoud(domain, raw, this.opts.onWarning);
     }
     /** Content hash of a raws snapshot → a stable u53-ish version number (≤ Number.MAX_SAFE_INTEGER). The one reading is `configDVersionOf`
-     *  (`./config-d-file`) — `inspectBundle` asks the same function, so a clean tree has the same version from either. */
+     *  (`./config-d-file`) — `read()` asks the same function, so a clean tree has the same version from either. */
     #versionOf(raws) {
         return configDVersionOf(raws);
     }
@@ -191,4 +202,60 @@ export class FileConfigStore {
     async getVersion() {
         return this.#versionOf(await this.#readAllRaw());
     }
+    /**
+     * **单读口**(16.0.0):一次读整棵 `config.d`(全部便携域 + retired 域的墓碑文档,每份只读一次),交一个结局({@link FileConfigRead})——
+     *  · 每份文档在文件层都读得进 ⇒ `effective`:与严读 `getEffective()` 逐位同;读侧告警交成数据(没人读的文件 + 装配告警,不经 `onWarning`);
+     *  · 有文档在文件层被拒(空 / 坏 JSON / 不是对象 / 读不出 / 过深;带事实的 retired 域文档是墓碑拒,带迁移编号)⇒ `refused`:整棵目录的拒单与这一次读到的内容版本。
+     * 严读与 `readBundle` 读的是同一只文件读法(`./config-d-file` 的读数)—— 同一种坏形同一个词、同一句话;区别只在渲染:严读遇到第一份坏文档就抛,本方法把整个目录读完、逐份交出。
+     * 文件层之外的拒(读得出、过不了门控域的 schema)照严读抛 —— 那是判形,不在拒单里。拒单、版本、effective、告警都出自这一次读到的字节:没有「先抛、再重探」的第二次读。
+     */
+    async read() {
+        const documents = [...RETIRED_DOMAIN_NAMES, ...PORTABLE_DOMAINS];
+        const [readings, unread] = await Promise.all([Promise.all(documents.map((d) => readConfigDFileReading(this.root, d))), this.#unreadFiles()]);
+        const raws = {};
+        const refusals = [];
+        documents.forEach((document, i) => {
+            const reading = readings[i];
+            switch (reading.status) {
+                case "absent":
+                    raws[document] = undefined;
+                    return;
+                case "refused":
+                    raws[document] = corruptDocumentRaw(reading);
+                    refusals.push({ document, reason: reading.reason, error: reading.error });
+                    return;
+                case "present":
+                    raws[document] = reading.value;
+                    if (isRetiredDomainName(document)) {
+                        const tombstone = tombstoneOf(document, reading.value);
+                        if (tombstone !== undefined)
+                            refusals.push(tombstone);
+                    }
+                    return;
+                default: {
+                    const unhandled = reading;
+                    throw new Error(`FileConfigStore.read: unhandled reading ${String(unhandled)}`);
+                }
+            }
+        });
+        const version = this.#versionOf(raws);
+        if (refusals.length > 0)
+            return { kind: "refused", refusals, version, warnings: unread };
+        const warnings = [...unread];
+        const updatedAt = await this.#maxMtimeIso();
+        const effective = buildEffective(version, (d) => raws[d], updatedAt, (w) => warnings.push(w));
+        return { kind: "effective", effective, warnings };
+    }
+}
+/** 墓碑判一次(与严读同一只判官 `refuseRetiredDomain`、同一句):retired 域文档带事实 ⇒ 一条 `retired_domain` 拒;缺席 / `{}` ⇒ `undefined`。 */
+function tombstoneOf(domain, raw) {
+    try {
+        refuseRetiredDomain(domain, raw);
+        return undefined;
+    }
+    catch (e) {
+        if (e instanceof RetiredDomainError)
+            return { document: e.domain, reason: "retired_domain", error: e.message, migration: e.migration };
+        throw e;
+    }
 }

package/dist/fleet.d.ts

@@ -166,12 +166,13 @@ export type RestartSignal = z.infer<typeof RestartSignal>;
  *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary;
  *    `config.catalog_replaces_env_models` ({@link CATALOG_REPLACES_ENV_MODELS_CODE}) — on the LOCAL config leg, a candidate that
  *    manages the model plane would replace a declared env model table (`MODEL_ID` …) while the config root's decision document
- *    (`config.env-models.json`, read by `readEnvModelsDecision`) does not say `replaced` — the env models keep serving;
- *    `config.summarize_model_missing` ({@link SUMMARIZE_MODEL_MISSING_CODE}) — the summarize role, which every task resolves,
- *    would land on no servable entry (every task would be refused after adoption).
+ *    (`config.env-models.json`, read by `readEnvModelsDecision`) does not say `replaced` — the env models keep serving.
  *    Source (engine): the first two in `src/model-entry-refusal.ts`, the next two in `src/model-route-endpoint.ts:40,42`
  *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`); the
- *    last two are named HERE first (the code is a contract word: this package names it and exports the two constants for the engine to read; the engine does not mint them today).
+ *    last one is named HERE first (the code is a contract word: this package names it and exports the constant for the engine to read; the engine does not mint it today).
+ *    16.0.0 retired `config.summarize_model_missing` (and its constant) from this set: a role seat naming an entry the catalog does not serve
+ *    reads as unset (it falls back down the role chain and the engine says so once) — no reading refuses a model plane for it, so it was never
+ *    an engine group refusal. A reader still holding it gets it dropped by {@link readModelRefusals} like any code outside the set.
  */
 export declare const MODEL_ENTRY_REFUSAL_CODES: readonly ["config.model_no_brain", "config.model_entry_invalid"];
 export declare const ModelEntryRefusalCode: z.ZodEnum<{
@@ -181,12 +182,9 @@ export declare const ModelEntryRefusalCode: z.ZodEnum<{
 export type ModelEntryRefusalCode = z.infer<typeof ModelEntryRefusalCode>;
 /** The env-model-table confirmation gate's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}). */
 export declare const CATALOG_REPLACES_ENV_MODELS_CODE: "config.catalog_replaces_env_models";
-/** The summarize invariant's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}); a writer's plan answers `fix_first` with it. */
-export declare const SUMMARIZE_MODEL_MISSING_CODE: "config.summarize_model_missing";
-export declare const MODEL_PLANE_REFUSAL_CODES: readonly ["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary", "config.catalog_replaces_env_models", "config.summarize_model_missing"];
+export declare const MODEL_PLANE_REFUSAL_CODES: readonly ["config.default_model_missing", "config.model_refused_name_minted", "config.model_route_endpoint_missing", "config.gateway_fallback_without_primary", "config.catalog_replaces_env_models"];
 export declare const ModelPlaneRefusalCode: z.ZodEnum<{
     "config.catalog_replaces_env_models": "config.catalog_replaces_env_models";
-    "config.summarize_model_missing": "config.summarize_model_missing";
     "config.default_model_missing": "config.default_model_missing";
     "config.model_refused_name_minted": "config.model_refused_name_minted";
     "config.model_route_endpoint_missing": "config.model_route_endpoint_missing";

package/dist/fleet.js

@@ -234,26 +234,24 @@ function readSignalBody(body, pick, schema) {
  *    `config.gateway_fallback_without_primary` — fallback gateways are declared without a primary;
  *    `config.catalog_replaces_env_models` ({@link CATALOG_REPLACES_ENV_MODELS_CODE}) — on the LOCAL config leg, a candidate that
  *    manages the model plane would replace a declared env model table (`MODEL_ID` …) while the config root's decision document
- *    (`config.env-models.json`, read by `readEnvModelsDecision`) does not say `replaced` — the env models keep serving;
- *    `config.summarize_model_missing` ({@link SUMMARIZE_MODEL_MISSING_CODE}) — the summarize role, which every task resolves,
- *    would land on no servable entry (every task would be refused after adoption).
+ *    (`config.env-models.json`, read by `readEnvModelsDecision`) does not say `replaced` — the env models keep serving.
  *    Source (engine): the first two in `src/model-entry-refusal.ts`, the next two in `src/model-route-endpoint.ts:40,42`
  *    (invariant `model-route-endpoint`, judged by the model-plane stage in `src/config-center/apply-effective.ts:664-665`); the
- *    last two are named HERE first (the code is a contract word: this package names it and exports the two constants for the engine to read; the engine does not mint them today).
+ *    last one is named HERE first (the code is a contract word: this package names it and exports the constant for the engine to read; the engine does not mint it today).
+ *    16.0.0 retired `config.summarize_model_missing` (and its constant) from this set: a role seat naming an entry the catalog does not serve
+ *    reads as unset (it falls back down the role chain and the engine says so once) — no reading refuses a model plane for it, so it was never
+ *    an engine group refusal. A reader still holding it gets it dropped by {@link readModelRefusals} like any code outside the set.
  */
 export const MODEL_ENTRY_REFUSAL_CODES = ["config.model_no_brain", "config.model_entry_invalid"];
 export const ModelEntryRefusalCode = z.enum(MODEL_ENTRY_REFUSAL_CODES);
 /** The env-model-table confirmation gate's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}). */
 export const CATALOG_REPLACES_ENV_MODELS_CODE = "config.catalog_replaces_env_models";
-/** The summarize invariant's group-refusal code (see {@link MODEL_PLANE_REFUSAL_CODES}); a writer's plan answers `fix_first` with it. */
-export const SUMMARIZE_MODEL_MISSING_CODE = "config.summarize_model_missing";
 export const MODEL_PLANE_REFUSAL_CODES = [
     "config.default_model_missing",
     "config.model_refused_name_minted",
     "config.model_route_endpoint_missing",
     "config.gateway_fallback_without_primary",
     CATALOG_REPLACES_ENV_MODELS_CODE,
-    SUMMARIZE_MODEL_MISSING_CODE,
 ];
 export const ModelPlaneRefusalCode = z.enum(MODEL_PLANE_REFUSAL_CODES);
 /**

package/dist/hooks.d.ts

@@ -78,8 +78,8 @@ export declare const HookEventName: z.ZodEnum<{
 }>;
 export type HookEventName = z.infer<typeof HookEventName>;
 export declare const HookOwner: z.ZodEnum<{
-    engine: "engine";
     shell: "shell";
+    engine: "engine";
 }>;
 export type HookOwner = z.infer<typeof HookOwner>;
 /**

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from "./types.js";
 export * from "./execution-lanes.js";
 export * from "./config-document-refusal.js";
 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";

package/dist/index.js

@@ -5,7 +5,8 @@
 export * from "./types.js";
 export * from "./execution-lanes.js"; // 7.0.0 M-R2: the ONE lane / store vocabulary (EXECUTION_LANE_WORDS / EXECUTION_LANES / STORE_BACKENDS / SESSION_BACKENDS / MEMORY_ENGINE_BACKENDS) + THE lane-coordinate blank judge isBlankCoordinate (empty or whitespace-only = absent; the write gate and every consumer ask this one function; whether a key is set, and whether an optional key may be empty, stays the caller's call; the same function object as on the `./execution-lanes` subpath) — a zero-import leaf, pure/browser-safe
 export * from "./config-document-refusal.js"; // 15.2.0: the typed refusal of one config.d document (CONFIG_DOCUMENT_REFUSAL_REASONS = empty / invalid_json / not_object / io / retired_domain; ConfigDocumentRefusal { document, reason, error } + the tombstone arm's migration) — the reading is `inspectBundle` in ./node; pure/browser-safe
-export * from "./url-shape.js"; // 11.0.0: THE URL shape judge (httpUrlFlaws / httpUrlRule / isHierarchicalUrl), pure/browser-safe
+export * from "./url-shape.js"; // 11.0.0: THE URL shape judge (httpUrlFlaws / httpUrlRule / isHierarchicalUrl; 16.0.0 + wsUrlFlaws), pure/browser-safe
+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

package/dist/local-load.d.ts

@@ -2,17 +2,25 @@ import { type RequiredEnvName } from "./file-edit.js";
 import { type EffectiveReadWarning } from "./config-fns.js";
 import { type RemoteExecSpec } from "./remote-exec.js";
 import type { EffectiveConfig } from "./types.js";
-/** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
+/** The remoteExec file path under a config root (under config.d/, beside the per-domain files) — the ONE config.d path builder (`configDPath`) answers it. */
 export declare function remoteExecPath(root: string): string;
-/** Read `<root>/config.d/remote-exec.json` → a VALIDATED RemoteExecSpec, or undefined if the file is absent
- *  (→ the engine defaults to `host` under CONFIG_PROVIDER=local). Throws (zod) on a present-but-invalid file. */
+/** Read `<root>/config.d/remote-exec.json` → a VALIDATED RemoteExecSpec, or undefined if there is NOTHING at that path
+ *  (→ the engine defaults to `host` under CONFIG_PROVIDER=local). Throws (zod) on a present-but-invalid file.
+ *
+ *  ABSENT means no entry on the path — nothing else. A present-but-empty file is a corruption/half-write, NOT "use the default" — FAIL CLOSED (an empty file
+ *  silently falling back to the host lane would be an isolation DOWNGRADE if the user meant local-docker); so is a DANGLING symbolic link, at the file or at
+ *  `config.d` itself (the kernel follows the link and answers ENOENT, but the entry is there: present and unreadable — it throws the same one sentence the directory
+ *  migration prints, with its way out: repair or remove the link). To get the host default, the file must be ABSENT, not empty and not a broken link.
+ *  This function has no read of its own: it is THE `config.d` document reading (`readConfigDFile`, one absence rule, one text judge — empty / bad JSON / not an object, one sentence
+ *  each — shared with FileConfigStore, readBundle and the directory migration); the sanitized value judge is the migration's too (`./config-d-file`). */
 export declare function loadRemoteExec(root: string): Promise<RemoteExecSpec | undefined>;
 /** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (the package's one atomic writer, `./atomic-write`; never a half file). The
  *  client's `config` editor writes the exec backend through this; the engine reads it via loadRemoteExec. */
 export declare function writeRemoteExec(root: string, spec: unknown): Promise<RemoteExecSpec>;
 /** Parse `<root>/.env` (KEY=VALUE, `#` comments, optional surrounding quotes) MERGED OVER process.env (the
  *  file wins). The ONLY place secret VALUES live — the contract files carry env-NAMEs only. A `KEY=` with an
- *  empty value IS present (the caller may treat empty as a weak warning). Absent .env → just process.env.
+ *  empty value IS present (the caller may treat empty as a weak warning). Absent .env → just process.env — absent
+ *  means no entry on the path (the one absence rule, `readTextIfPresent`): a DANGLING symbolic link at `.env` is present and unreadable, so it throws.
  *  A `.env` value of `file:<path>` resolves to that file's trimmed content (file-NAME ref — key stays out of
  *  env, contract stays env-NAME-only). Schema still rejects pasted plaintext (the contract field is a NAME). */
 export declare function loadEnvFile(root: string): Promise<Record<string, string>>;

package/dist/local-load.js

@@ -10,34 +10,28 @@
 import { mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
-import { writeFileAtomic } from "./atomic-write.js";
+import { readTextIfPresent, writeFileAtomic } from "./atomic-write.js";
 import { FileConfigStore } from "./file-store.js";
 import { listRequiredEnvNames } from "./file-edit.js";
 import {} from "./config-fns.js";
-import { configDDocumentText, judgeConfigDText, parseRemoteExecDocument } from "./config-d-file.js";
+import { configDDocumentText, configDPath, parseRemoteExecDocument, readConfigDFile } from "./config-d-file.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
-/** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
+/** The remoteExec file path under a config root (under config.d/, beside the per-domain files) — the ONE config.d path builder (`configDPath`) answers it. */
 export function remoteExecPath(root) {
-    return path.join(root, "config.d", `${REMOTE_EXEC_DOCUMENT}.json`);
+    return configDPath(root, REMOTE_EXEC_DOCUMENT);
 }
-/** Read `<root>/config.d/remote-exec.json` → a VALIDATED RemoteExecSpec, or undefined if the file is absent
- *  (→ the engine defaults to `host` under CONFIG_PROVIDER=local). Throws (zod) on a present-but-invalid file. */
+/** Read `<root>/config.d/remote-exec.json` → a VALIDATED RemoteExecSpec, or undefined if there is NOTHING at that path
+ *  (→ the engine defaults to `host` under CONFIG_PROVIDER=local). Throws (zod) on a present-but-invalid file.
+ *
+ *  ABSENT means no entry on the path — nothing else. A present-but-empty file is a corruption/half-write, NOT "use the default" — FAIL CLOSED (an empty file
+ *  silently falling back to the host lane would be an isolation DOWNGRADE if the user meant local-docker); so is a DANGLING symbolic link, at the file or at
+ *  `config.d` itself (the kernel follows the link and answers ENOENT, but the entry is there: present and unreadable — it throws the same one sentence the directory
+ *  migration prints, with its way out: repair or remove the link). To get the host default, the file must be ABSENT, not empty and not a broken link.
+ *  This function has no read of its own: it is THE `config.d` document reading (`readConfigDFile`, one absence rule, one text judge — empty / bad JSON / not an object, one sentence
+ *  each — shared with FileConfigStore, readBundle and the directory migration); the sanitized value judge is the migration's too (`./config-d-file`). */
 export async function loadRemoteExec(root) {
-    const file = remoteExecPath(root);
-    let text;
-    try {
-        text = await readFile(file, "utf8");
-    }
-    catch (e) {
-        if (e.code === "ENOENT")
-            return undefined;
-        throw e;
-    }
-    // A present-but-empty file is a corruption/half-write, NOT "use the default" — FAIL CLOSED (an empty file
-    // silently falling back to the host lane would be an isolation DOWNGRADE if the user meant local-docker).
-    // To get the host default, the file must be ABSENT, not empty. The text judge is THE config.d one (empty / bad JSON / not an object, one sentence
-    // each — the same judge FileConfigStore and the directory migration read with); the sanitized value judge is the migration's too (`./config-d-file`).
-    return parseRemoteExecDocument(judgeConfigDText(REMOTE_EXEC_DOCUMENT, text, file));
+    const doc = await readConfigDFile(root, REMOTE_EXEC_DOCUMENT);
+    return doc === undefined ? undefined : parseRemoteExecDocument(doc);
 }
 /** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (the package's one atomic writer, `./atomic-write`; never a half file). The
  *  client's `config` editor writes the exec backend through this; the engine reads it via loadRemoteExec. */
@@ -77,7 +71,8 @@ async function resolveFileRef(spec, root) {
 }
 /** Parse `<root>/.env` (KEY=VALUE, `#` comments, optional surrounding quotes) MERGED OVER process.env (the
  *  file wins). The ONLY place secret VALUES live — the contract files carry env-NAMEs only. A `KEY=` with an
- *  empty value IS present (the caller may treat empty as a weak warning). Absent .env → just process.env.
+ *  empty value IS present (the caller may treat empty as a weak warning). Absent .env → just process.env — absent
+ *  means no entry on the path (the one absence rule, `readTextIfPresent`): a DANGLING symbolic link at `.env` is present and unreadable, so it throws.
  *  A `.env` value of `file:<path>` resolves to that file's trimmed content (file-NAME ref — key stays out of
  *  env, contract stays env-NAME-only). Schema still rejects pasted plaintext (the contract field is a NAME). */
 export async function loadEnvFile(root) {
@@ -85,15 +80,9 @@ export async function loadEnvFile(root) {
     for (const [k, v] of Object.entries(process.env))
         if (v !== undefined)
             merged[k] = v;
-    let text;
-    try {
-        text = await readFile(path.join(root, ".env"), "utf8");
-    }
-    catch (e) {
-        if (e.code === "ENOENT")
-            return merged;
-        throw e;
-    }
+    const text = await readTextIfPresent(path.join(root, ".env"));
+    if (text === undefined)
+        return merged;
     for (const raw of text.split("\n")) {
         const line = raw.trim();
         if (!line || line.startsWith("#"))

package/dist/migration-receipt.d.ts

@@ -7,7 +7,7 @@ import type { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import type { DomainName, RetiredDomainName } from "./types.js";
 /** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
  *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
-export declare const ONE_TIME_MIGRATION_IDS: readonly ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M8", "SS-M9", "SS-M10", "SS-M11"];
+export declare const ONE_TIME_MIGRATION_IDS: readonly ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M8", "SS-M9", "SS-M10", "SS-M11", "SS-M12"];
 export type OneTimeMigrationId = (typeof ONE_TIME_MIGRATION_IDS)[number];
 /**
  * 一条收据说迁移**对一个坐标做了什么**(闭集,每词一义):

package/dist/migration-receipt.js

@@ -1,6 +1,6 @@
 /** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
  *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
-export const ONE_TIME_MIGRATION_IDS = ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M8", "SS-M9", "SS-M10", "SS-M11"];
+export const ONE_TIME_MIGRATION_IDS = ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M8", "SS-M9", "SS-M10", "SS-M11", "SS-M12"];
 /**
  * 一条收据说迁移**对一个坐标做了什么**(闭集,每词一义):
  *  - `moved`            — 值搬到新位(`to`),义不变;

package/dist/one-time-migrations.d.ts

@@ -41,7 +41,7 @@ export type StoredDocuments = Readonly<Partial<Record<DomainName | RetiredDomain
 export interface StoredDocumentsMigration {
     /** 迁移后的文档集:没改的文档是**同一引用**;被移除的(retired 域)不在;新建的(例:迁出的 `governance` / `limits`)在。 */
     readonly docs: Readonly<Record<string, unknown>>;
-    /** 逐条收据(步序 SS-M1 → SS-M2 → SS-M5 → SS-M6 → SS-M8 → SS-M9 → SS-M10 → SS-M7 → SS-M4:纯改写步在前,用新 schema 终判的 SS-M4 最后;步内按坐标)。
+    /** 逐条收据(步序 SS-M1 → SS-M2 → SS-M5 → SS-M6 → SS-M8 → SS-M9 → SS-M10 → SS-M7 → workers 行步〔SS-M12 改写 → SS-M4 改写 → 一次终判〕:纯改写步在前,用新 schema 终判的 workers 行步最后;步内按坐标)。
      *  只有 `refused` 的收据 = 什么都没改。 */
     readonly receipts: readonly MigrationReceipt[];
 }