@sema-agent/settings-schema 15.2.0 → 17.0.0

package/conformance/cases/c55-s784-lane-local-docker-legal/input.json

@@ -13,7 +13,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "local-docker",
+              "lanes": [
+                "local-docker"
+              ],
               "coords": {
                 "DOCKER_IMAGE": "registry.internal/sandbox:1",
                 "DOCKER_HOST": "tcp://docker.internal:2376"

package/conformance/cases/c56-s784-lane-device-legal/expected.json

@@ -63,9 +63,12 @@
             "runtime": {
               "execution": {
                 "coords": {
+                  "DEVICE_RELAY_URL": "none",
                   "DEVICE_SUPERSEDE": "deny"
                 },
-                "lane": "device",
+                "lanes": [
+                  "device"
+                ],
                 "secretRefs": {}
               },
               "rateLimitRpm": 0,
@@ -113,9 +116,12 @@
             "runtime": {
               "execution": {
                 "coords": {
+                  "DEVICE_RELAY_URL": "none",
                   "DEVICE_SUPERSEDE": "deny"
                 },
-                "lane": "device",
+                "lanes": [
+                  "device"
+                ],
                 "secretRefs": {}
               },
               "rateLimitRpm": 0,

package/conformance/cases/c56-s784-lane-device-legal/input.json

@@ -14,9 +14,12 @@
           },
           "runtime": {
             "execution": {
-              "lane": "device",
+              "lanes": [
+                "device"
+              ],
               "coords": {
-                "DEVICE_SUPERSEDE": "deny"
+                "DEVICE_SUPERSEDE": "deny",
+                "DEVICE_RELAY_URL": "none"
               }
             },
             "store": {

package/conformance/cases/c57-s784-g1-enabled-no-lane/meta.json

@@ -1,5 +1,5 @@
 {
   "contributor": "contract",
-  "claim": "G1:enabled 的 worker 没有 runtime.execution ⇒ 拒(拒因点名 runtime.execution.lane)。打「声明不了车道也能过闸、起服落进程内 stub、无手照回 completed」那条静默路(WA-49)。",
+  "claim": "G1:enabled 的 worker 没有 runtime.execution ⇒ 拒(拒因点名 runtime.execution.lanes —— 16.0.0 起车道集)。打「声明不了车道也能过闸、起服落进程内 stub、无手照回 completed」那条静默路(WA-49)。",
   "firstRedOn": []
 }

package/conformance/cases/c58-s784-g2-multitenant-host/input.json

@@ -14,7 +14,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "host"
+              "lanes": [
+                "host"
+              ]
             },
             "store": {
               "backend": "mysql",

package/conformance/cases/c59-s784-g3-k8s-missing-image/input.json

@@ -13,7 +13,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "k8s",
+              "lanes": [
+                "k8s"
+              ],
               "coords": {
                 "K8S_NAMESPACE": "sandboxes"
               }

package/conformance/cases/c60-s784-g3-e2b-missing-key/input.json

@@ -13,7 +13,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "e2b"
+              "lanes": [
+                "e2b"
+              ]
             },
             "store": {
               "backend": "local"

package/conformance/cases/c61-s784-g3-other-lane-key/input.json

@@ -13,7 +13,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "k8s",
+              "lanes": [
+                "k8s"
+              ],
               "coords": {
                 "K8S_SANDBOX_IMAGE": "img",
                 "K8S_NAMESPACE": "sandboxes",

package/conformance/cases/c62-s784-g7a-session-tidb/input.json

@@ -13,7 +13,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "host"
+              "lanes": [
+                "host"
+              ]
             },
             "store": {
               "backend": "local",

package/conformance/cases/c63-s784-host-two-replicas/input.json

@@ -13,7 +13,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "host"
+              "lanes": [
+                "host"
+              ]
             },
             "store": {
               "backend": "local"

package/conformance/cases/c64-s784-multitenant-local-store/input.json

@@ -13,7 +13,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "k8s",
+              "lanes": [
+                "k8s"
+              ],
               "coords": {
                 "K8S_SANDBOX_IMAGE": "img",
                 "K8S_NAMESPACE": "sandboxes"

package/conformance/cases/c65-s784-pg-without-db/input.json

@@ -14,7 +14,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "host"
+              "lanes": [
+                "host"
+              ]
             },
             "store": {
               "backend": "pg"

package/conformance/cases/c66-s784-memory-backend-mismatch/input.json

@@ -14,7 +14,9 @@
           },
           "runtime": {
             "execution": {
-              "lane": "host"
+              "lanes": [
+                "host"
+              ]
             },
             "store": {
               "backend": "mysql",

package/conformance/cases/c66-s784-memory-backend-mismatch/meta.json

@@ -1,5 +1,5 @@
 {
   "contributor": "contract",
-  "claim": "store.memory.backend pg 而 store.backend mysql ⇒ 拒(pg 记忆面要 pg 店;tidb 要 mysql)。",
+  "claim": "store.memory.backend pg 而 store.backend mysql ⇒ 拒(pg 记忆面要 pg 店;mysql 记忆面要 mysql 店)。",
   "firstRedOn": []
 }

package/conformance/cases/c68-s784-device-local-store/input.json

@@ -13,7 +13,12 @@
           },
           "runtime": {
             "execution": {
-              "lane": "device"
+              "lanes": [
+                "device"
+              ],
+              "coords": {
+                "DEVICE_RELAY_URL": "none"
+              }
             },
             "store": {
               "backend": "local"

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

@@ -67,7 +67,9 @@
             "runtime": {
               "execution": {
                 "coords": {},
-                "lane": "host",
+                "lanes": [
+                  "host"
+                ],
                 "secretRefs": {}
               },
               "rateLimitRpm": 0,
@@ -112,7 +114,9 @@
             "runtime": {
               "execution": {
                 "coords": {},
-                "lane": "host",
+                "lanes": [
+                  "host"
+                ],
                 "secretRefs": {}
               },
               "rateLimitRpm": 0,

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

@@ -10,7 +10,9 @@
           "name": "w1",
           "runtime": {
             "execution": {
-              "lane": "host"
+              "lanes": [
+                "host"
+              ]
             },
             "store": {
               "backend": "local"

package/dist/atomic-write.d.ts

@@ -16,6 +16,10 @@ 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` 只列文件所在的那一级布局座。 */
+export declare function readTextIfPresent(file: string, dirSeats?: readonly string[]): Promise<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,6 +20,10 @@
  * 「链接 ⇒ 真文件、悬空 ⇒ 响亮抛」这一只判法是 {@link resolveSymlinkTarget}:目录迁移的读口(`./config-dir-io`)读目录 / 读文件前也问它,
  * 悬空链接在读阶段与写阶段是**同一句**({@link danglingSymlinkSentence})。
  *
+ * ## `config.d` 文档与 `.env` 的缺席只有一种读法({@link readTextIfPresent})
+ * **缺席 = 路径上没有任何条目。** `readFile` 跟着符号链接走,链接在而目标不在时内核同样答 `ENOENT`:那是在场却读不出,不是缺席。读一份可以缺席的文本(`config.d` 的文档、配置根下的 `.env`)
+ * 因此都过同一只读者 —— 读不出且是 `ENOENT` ⇒ 在**缺席臂里**问一次链接判法再答「缺席」,悬空 ⇒ 抛那一句(同一句,不带 errno 码)。判在缺席臂而不在读前:读得到的路径零变化(不多一次系统调用);读之后目标恰好出现仍答缺席 —— 读的那一刻它确实不在,与旧读法同一边界,不是放宽。
+ *
  * ## 不存在才建({@link createFileExclusive})
  * 另一种写法只有一处不同:最后一步不是 `rename` 盖过目标,而是把(已 fsync 的)临时文件 `link` 成目标名 —— 目标名已在(任何东西:文件、目录、哪怕是悬空的符号链接)⇒
  * 内核拒(`EEXIST`),答 `present`、一字不动。读到「缺席」与写入之间别人写下的东西因此不会被吞(一次性迁移铸配置根的决定文档时用它)。
@@ -38,6 +42,7 @@
  * 写器在建临时文件那一步读了经落点递给铸点(`EPERM` ∧ 可写 ⇒ 真因是不可变标志,首选出路是清标志;`EACCES` ∧ 可写 ⇒ 真因是 ACL / 安全模块;不可写 ⇒ 先让目录可写);`chmod` / `rename` 那两步不读 —— 临时文件刚在同目录建成,可写是已证明的事实,铸点自己给。
  */
 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 path from "node:path";
 import { FsFailure } from "./fs-failure.js";
@@ -75,6 +80,21 @@ 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` 只列文件所在的那一级布局座。 */
+export async function readTextIfPresent(file, dirSeats = []) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    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) {
     const real = resolveSymlinkTarget(target);

package/dist/bundle.d.ts

@@ -1,6 +1,5 @@
 import { type PortableDomain } from "./portable-domains.js";
 import type { ConfigReader } from "./reader.js";
-import type { ConfigDocumentRefusal } from "./config-document-refusal.js";
 /** A bundle carries PORTABLE domains only — the non-portable ones (`NON_PORTABLE_DOMAIN_REASONS`: workers / hosts / systems / projects /
  *  entitlement) never travel, and the three bundle functions are that table's other face (types narrow to {@link PortableDomain}; a
  *  JS / `as` caller is refused at run time). */
@@ -20,20 +19,3 @@ export declare function writeBundle(root: string, bundle: ConfigBundle): Promise
  *  `FileConfigStore`: carrying facts ⇒ `RetiredDomainError` (a bundle assembled from the remaining files would silently drop those
  *  facts); absent / `{}` ⇒ left alone. */
 export declare function readBundle(root: string, domains?: readonly PortableDomain[]): Promise<ConfigBundle>;
-/** {@link inspectBundle} 的答案:`refusals` = 文件层拒了的每一份文档(空 ⇒ 这棵目录在文件层干净);`version` = 这一次读到的整棵目录的内容版本。 */
-export interface BundleInspection {
-    /** 被拒的文档,逐份一条,次序确定:retired 域文档在前(墓碑表的声明次序),便携域按 `PORTABLE_DOMAINS` 的次序。 */
-    readonly refusals: readonly ConfigDocumentRefusal[];
-    /** 这一次读到的整棵目录(便携域 + retired 域的文档)的内容版本(稳定的 u53 整数):文档都干净时 = `FileConfigStore.getVersion()`;被拒的文档以「坏文档的指纹」参与
-     *  (与 `getEffective({ tolerant: true })` 对坏文件的版本哨兵同一只),所以同样的坏内容同一个数、坏内容变了换数(指纹取 trim 之后的文本:只差首尾空白的两份坏文件同数)、修好后回到内容版本,绝不与「文件缺席」同数。 */
-    readonly version: number;
-}
-/**
- * 一次读完 `<root>/config.d/` 里契约读的每一份文档(全部便携域 + retired 域的墓碑文档),**不抛**文件层的拒,把它们交成类型化的拒单({@link BundleInspection})。
- * 与 {@link readBundle} / `FileConfigStore` 的严读读的是同一只文件读法(`./config-d-file` 的读数)—— 同一种坏形同一个词、同一句话;区别只在渲染:严读遇到第一份坏文档就抛,
- * 本函数把整个目录读完、逐份交出(retired 域文档带事实 ⇒ 一条 `retired_domain` 墓碑拒,带迁移编号;retired 域文档自己读不出 ⇒ 归到那一份的文件层拒)。
- *
- * 只覆盖**文件层与墓碑**:文档读得出、却过不了域的 schema(门控域判形失败)、内容哈希深度闸这类拒,不在这里 —— 它们属于严读的后半段(`getEffective` 抛的)。
- * 目录读口自己的错(路径不是合法的域名这类调用错)照旧抛。每份文档只读一次,答案出自这一次读到的字节(没有「先抛、再重探」的第二次读)。
- */
-export declare function inspectBundle(root: string): Promise<BundleInspection>;

package/dist/bundle.js

@@ -10,9 +10,7 @@
  */
 import { writeDomainFile } from "./file-edit.js";
 import { PORTABLE_DOMAINS } from "./portable-domains.js";
-import { RETIRED_DOMAIN_NAMES, configDPath, configDVersionOf, corruptDocumentRaw, readConfigDFile, readConfigDFileReading, refuseRetiredDomainFiles } from "./config-d-file.js";
-import { RetiredDomainError, refuseRetiredDomain } from "./config-fns.js";
-import { isRetiredDomainName } from "./types.js";
+import { configDPath, readConfigDFile, refuseRetiredDomainFiles } from "./config-d-file.js";
 /** The runtime guard of the same rule (a name that is not even a domain is refused first — no path traversal). */
 function assertPortable(d) {
     if (!PORTABLE_DOMAINS.includes(d)) {
@@ -68,54 +66,3 @@ export async function readBundle(root, domains = PORTABLE_DOMAINS) {
     }));
     return out;
 }
-/**
- * 一次读完 `<root>/config.d/` 里契约读的每一份文档(全部便携域 + retired 域的墓碑文档),**不抛**文件层的拒,把它们交成类型化的拒单({@link BundleInspection})。
- * 与 {@link readBundle} / `FileConfigStore` 的严读读的是同一只文件读法(`./config-d-file` 的读数)—— 同一种坏形同一个词、同一句话;区别只在渲染:严读遇到第一份坏文档就抛,
- * 本函数把整个目录读完、逐份交出(retired 域文档带事实 ⇒ 一条 `retired_domain` 墓碑拒,带迁移编号;retired 域文档自己读不出 ⇒ 归到那一份的文件层拒)。
- *
- * 只覆盖**文件层与墓碑**:文档读得出、却过不了域的 schema(门控域判形失败)、内容哈希深度闸这类拒,不在这里 —— 它们属于严读的后半段(`getEffective` 抛的)。
- * 目录读口自己的错(路径不是合法的域名这类调用错)照旧抛。每份文档只读一次,答案出自这一次读到的字节(没有「先抛、再重探」的第二次读)。
- */
-export async function inspectBundle(root) {
-    const documents = [...RETIRED_DOMAIN_NAMES, ...PORTABLE_DOMAINS];
-    const readings = await Promise.all(documents.map((d) => readConfigDFileReading(root, d)));
-    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(`inspectBundle: unhandled reading ${String(unhandled)}`);
-            }
-        }
-    });
-    return { refusals, version: configDVersionOf(raws) };
-}
-/** 墓碑判一次(与严读同一只判官 `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/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: ("models" | "rosters" | "scenarios" | "skills" | "execution" | "plugins" | "systems" | "limits" | "runtime" | "workers" | "hosts" | "projects" | "mcp" | "collab" | "governance" | "entitlement" | "prompts" | "remote-exec")[];
+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 function runSettingsSchemaCli(argv: readonly string[], io: SettingsSchemaCliIo): Promise<number>;

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

@@ -7,11 +7,11 @@ export declare function configDDocumentText(value: unknown): string;
 /** 判一份 remote-exec 文档的值(`RemoteExecSpec`),错误**脱敏**(zod 会回显出错的值 —— 粘错位置的密钥不许随抛出的错走);反射访问抛(恶意 getter /
  *  Proxy)⇒ 定句。`loadRemoteExec` / `writeRemoteExec` 与目录迁移的整文档终判调同一只。 */
 export declare function parseRemoteExecDocument(raw: unknown): RemoteExecSpec;
-/** `<root>/config.d/<名>.json` 的路径 —— 名字的判也在这里(**一处**):不是配置域也不是 retired 域 ⇒ 拒(不拿用户给的名拼路径,防 `../` 穿越)。 */
-export declare function configDPath(root: string, name: string): string;
 /** `config.d` 里能放的文档名:配置域、retired 域、`remote-exec`(`config.d/remote-exec.json`,不是配置域)。 */
 export type ConfigDDocumentName = DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT;
-/** 文件层的拒因(闭集词里除墓碑外的四个)。 */
+/** `<root>/config.d/<名>.json` 的路径 —— 名字的判也在这里(**一处**):不是 `config.d` 里能放的文档名(配置域、retired 域、`remote-exec`)⇒ 拒(不拿用户给的名拼路径,防 `../` 穿越)。 */
+export declare function configDPath(root: string, name: string): string;
+/** 文件层的拒因(闭集词里除墓碑外的五个)。 */
 export type ConfigDFileReason = Exclude<ConfigDocumentRefusalReason, "retired_domain">;
 /** 一份在场文档被拒的读数:`reason` 闭集词 · `error` 整句 · `thrown` 旧抛出口抛的那个对象(渲染成抛时原样抛它)· `fingerprint` 这份坏文档的指纹(版本哈希里的坏文件哨兵用它:
  *  文本路径取 trim 后原文的哈希 —— 不同坏内容不同数;读不出文本的 `io` 取错误文案的哈希)。 */
@@ -30,24 +30,25 @@ export type ConfigDReading = {
     readonly value: Record<string, unknown>;
 } | ConfigDRefused;
 /** 一个 `config.d/<名>.json` 在场时的**文本** → 读数(纯判,零 I/O;见文件头的律):一个 JSON 对象 ⇒ 在场;空 / 纯空白、坏 JSON、
- *  不是对象 ⇒ 被拒,每种一个词一句话(点名 `file` —— 调用方读的那份文件的真实路径 —— 与形,句尾 {@link documentWayOut})。 */
+ *  不是对象、嵌得过深({@link MAX_CONFIG_D_DOCUMENT_DEPTH})⇒ 被拒,每种一个词一句话(点名 `file` —— 调用方读的那份文件的真实路径 —— 与形,句尾 {@link documentWayOut})。 */
 export declare function judgeConfigDTextReading(name: ConfigDDocumentName, text: string, file: string): Exclude<ConfigDReading, {
     readonly status: "absent";
 }>;
-/** 抛出口:一个 `config.d/<名>.json` 在场时的**文本** → 它的值:读数是被拒 ⇒ 抛它的 `thrown`(空 / 坏 JSON / 不是对象各一句)。读盘的入口(`readConfigDFile`、`loadRemoteExec`)
+/** 抛出口:一个 `config.d/<名>.json` 在场时的**文本** → 它的值:读数是被拒 ⇒ 抛它的 `thrown`(空 / 坏 JSON / 不是对象各一句)。读盘的入口(`readConfigDFile`)
  *  与自己读文本的命令行(`migrate`)都过它 —— 一种坏形一句话,不论是哪份文档。 */
 export declare function judgeConfigDText(name: ConfigDDocumentName, text: string, file: string): Record<string, unknown>;
-/** 一份**已解析的**存量文档在场时的值(同步口 `migrateConfigDocuments` 收的是各层的文档原文,不是文件文本)→ 它自己:一个 JSON 对象 ⇒ 它;`null` / 数组 / 数 / 串 / 布尔 /
- *  非朴素对象 ⇒ 抛。{@link judgeConfigDText} 的最后一道判就是这只(文本解析出来之后过它),所以「不是对象」一种坏形一句话,不论文档是从文件文本来的还是调用方直接给的;
+/** 一份**已解析的**存量文档在场时的值(同步口 `migrateConfigDocuments` 收的是各层的文档原文,不是文件文本)→ 它自己:一个嵌得不过深的 JSON 对象 ⇒ 它;`null` / 数组 / 数 / 串 / 布尔 /
+ *  非朴素对象、嵌得过深 ⇒ 抛。{@link judgeConfigDText} 的最后一道判就是这只(文本解析出来之后过它),所以「不是对象」「过深」各一种坏形一句话,不论文档是从文件文本来的还是调用方直接给的;
  *  `label` = 句首的称呼(文本路径给文件的真实路径,值路径给 `the <名> document`)。 */
 export declare function judgeConfigDValue(name: ConfigDDocumentName, value: unknown, label: string): Record<string, unknown>;
-/** 读一个 `config.d/<名>.json` → 读数:不存在(ENOENT)⇒ 缺席;在场 ⇒ {@link judgeConfigDTextReading};在场却读不出(非 ENOENT 的 fs 错误)⇒ 被拒,词 `io`。 */
-export declare function readConfigDFileReading(root: string, name: DomainName | RetiredDomainName): Promise<ConfigDReading>;
-/** 抛出口:读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ 它的值;被拒 ⇒ 抛读数的 `thrown`(见 {@link readConfigDFileReading})。 */
-export declare function readConfigDFile(root: string, name: DomainName | RetiredDomainName): Promise<Record<string, unknown> | undefined>;
+/** 读一个 `config.d/<名>.json` → 读数:路径上没有任何条目 ⇒ 缺席;在场 ⇒ {@link judgeConfigDTextReading};在场却读不出 ⇒ 被拒,词 `io` —— 非 ENOENT 的 fs 错误,以及悬空的符号链接
+ *  (文档本身或 `config.d` 目录:内核跟链接读到 ENOENT,但条目在场;句子是 `danglingSymlinkSentence`(`./atomic-write`)那一句,与目录迁移的读口同一句)。缺席与悬空的分辨在 `readTextIfPresent`。 */
+export declare function readConfigDFileReading(root: string, name: ConfigDDocumentName): Promise<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`),版本哈希的入参。 */
 export type ConfigDRaws = Partial<Record<DomainName | RetiredDomainName, unknown>>;
-/** 一棵 `config.d` 原文快照的内容版本(稳定的 u53 整数):同样的文档 ⇒ 同一个数。`FileConfigStore.getVersion()` 与 `inspectBundle` 读同一只。 */
+/** 一棵 `config.d` 原文快照的内容版本(稳定的 u53 整数):同样的文档 ⇒ 同一个数。`FileConfigStore` 的 `getVersion()` / `getEffective()` / `read()` 读同一只。 */
 export declare function configDVersionOf(raws: ConfigDRaws): number;
 /** 一份被拒文档在版本哈希里的哨兵:`{ __corruptDomainFile: <坏文档的指纹> }` —— 绝不与「文件缺席」同字节(`stableStringify` 把 `undefined` 与 `null` 折成同样的字节,
  *  一份空 / 坏文件若读成缺席,会与「域缺席」同哈希,按版本轮询的消费方就漏掉一次变化),而且不同的坏内容换数:坏→修好、好→坏、坏内容 A→坏内容 B 都换版本。 */