@sema-agent/settings-schema 10.1.1 → 11.1.0

package/dist/execution-lanes.js

@@ -4,9 +4,9 @@
  *
  * ## 为什么在这里
  * 车道词、每条车道读哪些 env、哪条车道分租户、存储后端词 —— 这几张表以前在四处各抄一份(引擎的能力表、
- * 部署面的车道清单、中心表单、本包 `RemoteExecSpec`),任何一处改了别处都不红。从本版起**只有这一份**:
- *  · 中心写闸 = `WorkerSpec.safeParse`(本包 schema 读这张表判 `runtime.execution` / `runtime.store`);
- *  · 中心渲染器按这张表把结构块渲成 env(唯一写者);
+ * 部署面的车道清单、web-admin 表单、本包 `RemoteExecSpec`),任何一处改了别处都不红。从本版起**只有这一份**:
+ *  · web-admin 写闸 = `WorkerSpec.safeParse`(本包 schema 读这张表判 `runtime.execution` / `runtime.store`);
+ *  · web-admin 渲染器按这张表把结构块渲成 env(唯一写者);
  *  · 引擎提货时从这张表派生自己的车道词表 / 必需键表 / 租户分离位(引擎只留运行期事实,按导入联合类型穷举);
  *  · 部署面车道清单由这张表生成。
  * 写闸与起服读同一张表 ⇒ 不会分叉。
@@ -15,7 +15,8 @@
  *  · 车道词与次序:`src/execution-lane-caps.ts` `EXECUTION_LANE_WORDS`(:335)去掉 `in-process` =
  *    `REMOTE_EXEC_PROVIDER_WORDS`(:366)。次序照抄,于是引擎改派生之后,拒启句里的 `valid:` 列表与出路列表逐字不变。
  *  · `tenantSeparation`:同文件 `executionLaneCaps` 每臂的 `tenantSeparation` 位(:209 host / :230 e2b / :249 k8s /
- *    :269 ssh / :288 adb / :308 local-docker / :327 device)。
+ *    :269 ssh / :288 adb / :308 local-docker / :327 device)。`tenantSeparationBasis`(11.0.0):分租户的那几臂凭什么分 ——
+ *    e2b / k8s / local-docker 每任务一只隔离目标(`isolation`),device 是发起者自己的设备(`principal-binding`)。
  *  · `requiredEnv ∪ requiredSecretEnv`:`src/config.ts` `REQUIRED_ENVS_BY_LANE`(:1054)逐字;按 `src/config-catalog.ts`
  *    该键那一行的值类型分栏 —— 类型 `secret` / `opaque`(目录自己「绝不回显值」的两类)进 `*SecretEnv`,其余进 `*Env`。
  *  · `optionalEnv ∪ optionalSecretEnv`:`src/config.ts` `parseOrchestrationDomain` 的 `REMOTE_EXEC` 三元链里**该车道那一臂**
@@ -31,12 +32,24 @@
  *    仍回 completed + 零工具,就是那个病换了个合法名字。要无手 worker 先另立设计、定用户面行为再给词。
  *  · `remote-docker`:引擎有一只没接线的适配器工厂,但没有任何读点能把这个词变成一条在跑的车道
  *    (`REMOTE_EXEC=remote-docker` 起服即拒;远端 docker 守护进程今天的真形 = `local-docker` + `DOCKER_HOST`)。
+ *    它在退役词墓碑 {@link RETIRED_LANE_WORDS} 里:读到即拒,拒句带出路。
  */
 /** 可声明的执行车道闭集(= 引擎 `REMOTE_EXEC` 收的词,逐字同序)。 */
 export const EXECUTION_LANE_WORDS = ["host", "e2b", "k8s", "ssh", "adb", "local-docker", "device"];
+export const RETIRED_LANE_WORDS = Object.freeze([
+    Object.freeze(["remote-docker", "local-docker", "point it at the remote docker daemon with DOCKER_HOST (in a worker spec: runtime.execution.coords.DOCKER_HOST)"]),
+]);
+/** 一个车道值是不是退役词:是 ⇒ 带出路的整句;否(现行词、不认识的词、非串)⇒ `undefined`。纯函数。 */
+export function retiredLaneWordRefusal(word) {
+    const row = RETIRED_LANE_WORDS.find(([old]) => old === word);
+    return row === undefined ? undefined : `execution lane ${row[0]} was retired — use ${row[1]}: ${row[2]}`; // no quotes: the sentence survives a JSON-rendered issue list verbatim
+}
 /** 车道分不分租户(引擎能力表的 `tenantSeparation` 位,两档,没有「不表态」)。
  *  `supported` = 每个租户的命令落在各自的目标上;`single-user-only` = 所有任务落同一个共享目标 ⇒ 只许单用户 worker。 */
 export const TENANT_SEPARATION_WORDS = ["supported", "single-user-only"];
+/** 分租户车道**凭什么**分租户(两档):`isolation` = 每个任务一只隔离的目标(microVM / pod / 容器);`principal-binding` = 目标绑在
+ *  发起者身上(设备 ↔ principal 绑定),目标本身不隔离。只有 `tenantSeparation: "supported"` 的车道有依据。 */
+export const TENANT_SEPARATION_BASES = ["isolation", "principal-binding"];
 /** 逐车道一行。`satisfies Record<ExecutionLane, …>` = 词表加词而这里不加行 ⇒ 编译红。 */
 const LANE_ROWS = {
     /** server `config.ts` :4014 臂(无必需键);`execution-lane-caps.ts` :209 `single-user-only`(所有任务落 worker 宿主)。 */
@@ -51,6 +64,7 @@ const LANE_ROWS = {
      *  `execution-lane-caps.ts` :230 `supported`(每任务一只 microVM)。 */
     e2b: {
         tenantSeparation: "supported",
+        tenantSeparationBasis: "isolation",
         requiredEnv: [],
         requiredSecretEnv: ["E2B_API_KEY"],
         optionalEnv: ["E2B_TEMPLATE", "E2B_TIMEOUT_MS", "E2B_LIVENESS_MS", "E2B_ALLOW_NET", "E2B_MOUNT_PATH", "E2B_ORPHAN_RECLAIM"],
@@ -60,6 +74,7 @@ const LANE_ROWS = {
      *  `execution-lane-caps.ts` :249 `supported`(每任务一只 pod)。`MINIO_*` 刻意不收(见文件头)。 */
     k8s: {
         tenantSeparation: "supported",
+        tenantSeparationBasis: "isolation",
         requiredEnv: ["K8S_SANDBOX_IMAGE"],
         requiredSecretEnv: [],
         optionalEnv: [
@@ -98,6 +113,7 @@ const LANE_ROWS = {
      *  (每任务一只容器)。`DOCKER_HOST` 在本行:远端 docker 守护进程 = 本车道 + `coords.DOCKER_HOST`。 */
     "local-docker": {
         tenantSeparation: "supported",
+        tenantSeparationBasis: "isolation",
         requiredEnv: ["DOCKER_IMAGE"],
         requiredSecretEnv: [],
         optionalEnv: [
@@ -117,6 +133,7 @@ const LANE_ROWS = {
      *  连进来的);`execution-lane-caps.ts` :327 `supported`(发起者自己的设备)。 */
     device: {
         tenantSeparation: "supported",
+        tenantSeparationBasis: "principal-binding",
         requiredEnv: [],
         requiredSecretEnv: [],
         optionalEnv: [
@@ -134,9 +151,10 @@ const LANE_ROWS = {
 /** 车道表(次序 = {@link EXECUTION_LANE_WORDS})。整张表深冻结 —— 它是唯一正本,消费方拿到的不许被改。 */
 export const EXECUTION_LANES = Object.freeze(EXECUTION_LANE_WORDS.map((lane) => {
     const row = LANE_ROWS[lane];
+    const tenancy = row.tenantSeparation === "supported" ? { tenantSeparation: row.tenantSeparation, tenantSeparationBasis: row.tenantSeparationBasis } : { tenantSeparation: row.tenantSeparation };
     return Object.freeze({
         lane,
-        tenantSeparation: row.tenantSeparation,
+        ...tenancy,
         requiredEnv: Object.freeze([...row.requiredEnv]),
         requiredSecretEnv: Object.freeze([...row.requiredSecretEnv]),
         optionalEnv: Object.freeze([...row.optionalEnv]),

package/dist/file-edit.d.ts

@@ -17,9 +17,9 @@ export declare function validateRemoteExec(raw: unknown): ValidateResult<RemoteE
 /** Absolute path to a domain's JSON file under a config root (mirrors FileConfigStore.domainPath). Guards the
  *  name (no `../../secret` traversal even if a caller bypasses the DomainName type). */
 export declare function domainFilePath(root: string, domain: DomainName): string;
-/** WRITE a domain file ATOMICALLY (write a tmp in the same dir → rename) so a crash never leaves a half-written
- *  config.d/<domain>.json. VALIDATES first (throws on invalid — never persists garbage); persists the parsed +
- *  defaulted value so the file is canonical. */
+/** WRITE a domain file ATOMICALLY (the package's one atomic writer, `./atomic-write`: tmp in the same dir → rename) so a crash never
+ *  leaves a half-written config.d/<domain>.json; a new file takes the contract-document mode (0o644), an existing one keeps its own.
+ *  VALIDATES first (throws on invalid — never persists garbage); persists the parsed + defaulted value so the file is canonical. */
 export declare function writeDomainFile<K extends DomainName>(root: string, domain: K, value: unknown): Promise<DomainConfig[K]>;
 export interface RequiredEnvName {
     envName: string;

package/dist/file-edit.js

@@ -5,25 +5,27 @@
  *
  * Validation uses the SAME zod schemas as the server's parseDomain → identical rules on both sides.
  */
-import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import path from "node:path";
+import { writeFileAtomic } from "./atomic-write.js";
 import { collectEnvRefs } from "./secret-refs.js";
 import { RemoteExecSpec } from "./remote-exec.js";
-import { parseDomain, sanitizeZodError } from "./config-fns.js";
-import { DOMAIN_SCHEMAS, isDomainName } from "./types.js";
+import { RetiredDomainError, parseDomain, sanitizeZodError } from "./config-fns.js";
+import { DOMAIN_SCHEMAS, isDomainName, isRetiredDomainName } from "./types.js";
 /** Throw a CLEAR error for a non-domain key instead of the cryptic `undefined.parse(...)` you'd get from
  *  `DOMAIN_SCHEMAS[badKey]`. The classic trip-wire: a consumer scans `config.d/*.json` and feeds every file
  *  (incl. the non-domain `remote-exec.json`) into writeBundle/writeDomainFile. `remote-exec` is the exec
  *  backend, NOT a domain — write it via writeRemoteExec. Filter arbitrary keys with `isDomainName` first. */
 function assertDomainName(domain) {
+    // A retired domain is refused by its tombstone (the sentence names where its keys went), like every other reader / writer.
+    if (isRetiredDomainName(domain))
+        throw new RetiredDomainError(domain);
     if (!isDomainName(domain)) {
         const hint = domain === "remote-exec" ? " — the exec backend is NOT a domain; use writeRemoteExec (config.d/remote-exec.json)" : "";
         throw new Error(`"${domain}" is not a config domain (expected one of: ${DOMAINS_LIST})${hint}`);
     }
 }
 const DOMAINS_LIST = Object.keys(DOMAIN_SCHEMAS).join(", ");
-// Monotonic suffix so concurrent same-domain atomic writes in one process+ms can't collide on the tmp name.
-let tmpSeq = 0;
 /** VALIDATE a domain payload against its zod schema WITHOUT writing — the editor's "is this form valid?" check.
  *  Returns the parsed+defaulted value or the zod issues. Identical rules to the server's parseDomain. Throws
  *  (clear message) if `domain` is not a real domain name (a misuse, not invalid user data). */
@@ -58,24 +60,15 @@ export function domainFilePath(root, domain) {
     assertDomainName(domain);
     return path.join(root, "config.d", `${domain}.json`);
 }
-/** WRITE a domain file ATOMICALLY (write a tmp in the same dir → rename) so a crash never leaves a half-written
- *  config.d/<domain>.json. VALIDATES first (throws on invalid — never persists garbage); persists the parsed +
- *  defaulted value so the file is canonical. */
+/** WRITE a domain file ATOMICALLY (the package's one atomic writer, `./atomic-write`: tmp in the same dir → rename) so a crash never
+ *  leaves a half-written config.d/<domain>.json; a new file takes the contract-document mode (0o644), an existing one keeps its own.
+ *  VALIDATES first (throws on invalid — never persists garbage); persists the parsed + defaulted value so the file is canonical. */
 export async function writeDomainFile(root, domain, value) {
     assertDomainName(domain); // a stray non-domain key (e.g. "remote-exec" from a config.d scan) fails LOUD + clear
     const parsed = parseDomain(domain, value); // routes through the SANITIZED parser (explicit-null reject R4 + no secret echo R14)
     const dir = path.join(root, "config.d");
     await mkdir(dir, { recursive: true });
-    const dest = path.join(dir, `${domain}.json`);
-    const tmp = path.join(dir, `.${domain}.json.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
-    try {
-        await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", "utf8");
-        await rename(tmp, dest);
-    }
-    catch (e) {
-        await unlink(tmp).catch(() => { }); // never leave a half-written tmp behind on a write/rename failure
-        throw e;
-    }
+    writeFileAtomic(path.join(dir, `${domain}.json`), JSON.stringify(parsed, null, 2) + "\n", "config-document");
     return parsed;
 }
 /** LIST every env-NAME the current local config requires (across models/workers/mcp + the

package/dist/file-store.d.ts

@@ -1,6 +1,6 @@
 import { type EffectiveReadWarning } from "./config-fns.js";
 import type { ConfigReader } from "./reader.js";
-import { type DomainConfig, type DomainName, type EffectiveConfig } from "./types.js";
+import { type DomainConfig, type DomainName, type EffectiveConfig, type RetiredDomainName } from "./types.js";
 /** The domains a single-machine TOC carries: what `FileConfigStore` reads out of `config.d/`, and the
  *  **default**域集 of the bundle helpers (`exportBundle`/`readBundle`). 每个被排除的域必须在
  *  {@link NON_PORTABLE_DOMAIN_REASONS} 里有一条成文理由(禁裸排除,#282 件5 附带裁定)。
@@ -15,7 +15,7 @@ import { type DomainConfig, type DomainName, type EffectiveConfig } from "./type
  *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
  *  今日的兜底:漏登记的文件会被 {@link FileConfigStore} 的 `"unread-config-file"` 警告点名(fail-loud,
  *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
-export declare const PORTABLE_DOMAINS: readonly ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "runtime", "governance", "execution", "prompts", "limits"];
+export declare const PORTABLE_DOMAINS: readonly ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits"];
 export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
@@ -35,9 +35,9 @@ export declare const NON_DOMAIN_CONFIG_FILES: ReadonlySet<string>;
 export declare const NON_PORTABLE_DOMAIN_REASONS: {
     readonly workers: "FLEET-only:单机没有 reconciler,`{workers:[]}` 的 schema 默认就是正确语义(缺席不需要 stub)。";
     readonly hosts: "FLEET-only:同 workers —— 单机无机器注册表/自动排布,空注册表即正确语义。";
-    readonly systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 center 侧生命周期,单机 lane 无对应执法点。";
+    readonly systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 web-admin 侧生命周期,单机 lane 无对应执法点。";
     readonly projects: "TENANT IDENTITY DATA,不是可搬运的配置:登记簿随包复制进另一个部署 = 凭空多出的身份登记(design/142 §1.4 威胁模型①「carried-in foreign projectId」换了身 import 的衣服)。要带走走 142 §5 的导出面(service 半场)。";
-    readonly entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service/center 边界)。缺席语义如实:本地 buildEffective 给它 schema 默认值(空表),这**不等于**把远端 kill-switch/预算上限搬到了本地 —— 单机 lane 本就没有那个执法点。";
+    readonly entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service / web-admin 边界)。缺席语义如实:本地 buildEffective 给它 schema 默认值(空表),这**不等于**把远端 kill-switch/预算上限搬到了本地 —— 单机 lane 本就没有那个执法点。";
 };
 /** One unreadable/corrupt domain FILE surfaced by `getEffective({tolerant:true})`(0.10.12,[897]②)。
  *  `error` 是 #readDomainRaw 的 sanitized 文案(带文件路径语境、绝不回显文件内容)。 */
@@ -62,8 +62,9 @@ export declare class FileConfigStore implements ConfigReader {
         onWarning?: (w: EffectiveReadWarning) => void;
     });
     /** Absolute path to a domain's JSON file. Guards the name (defence in depth — a non-domain string like
-     *  `../../secret` must never be joined into a filesystem path, even if a caller bypasses the type). */
-    domainPath(domain: DomainName): string;
+     *  `../../secret` must never be joined into a filesystem path, even if a caller bypasses the type). A retired domain's
+     *  name is accepted: its file is read for the tombstone. */
+    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

package/dist/file-store.js

@@ -16,6 +16,9 @@
  *    "absent/defaults" the file must be missing, not empty. A valid `{}` object IS a set domain (→ defaults).
  *  - 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 ⇒
+ *    every read entry (`getDomain`, `getEffective` — and so `exportBundle`) throws `RetiredDomainError` (`refuseRetiredDomainFiles`, shared with `readBundle`) (the sentence names the one-time migration — `npx @sema-agent/settings-schema migrate
+ *    <config.d directory>` rewrites the directory); `{}` carries nothing and is left alone. It is never an "unread file".
  *  - The JSON files only ever carry env-NAMEs (the ENV_NAME boundary holds locally too); `.env` holds values.
  *  - `getVersion()` = a stable content hash of all portable files → a u53 number, so a consumer's
  *    "skip re-apply if version unchanged" works locally. `getEffective().updatedAt` = the max file mtime,
@@ -24,8 +27,11 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { buildEffective, DOMAIN_READ_FALLBACK, parseDomainLoud } from "./config-fns.js";
+import { configDPath, readConfigDFile, refuseRetiredDomainFiles } from "./config-d-file.js";
 import { stableHash } from "./hash.js";
-import { isDomainName } from "./types.js";
+import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
+/** The retired domain names (`RETIRED_DOMAINS` keys) — read from `config.d/` for their tombstone only. */
+const RETIRED_DOMAIN_NAMES = Object.keys(RETIRED_DOMAINS);
 /** The domains a single-machine TOC carries: what `FileConfigStore` reads out of `config.d/`, and the
  *  **default**域集 of the bundle helpers (`exportBundle`/`readBundle`). 每个被排除的域必须在
  *  {@link NON_PORTABLE_DOMAIN_REASONS} 里有一条成文理由(禁裸排除,#282 件5 附带裁定)。
@@ -40,7 +46,7 @@ import { isDomainName } from "./types.js";
  *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
  *  今日的兜底:漏登记的文件会被 {@link FileConfigStore} 的 `"unread-config-file"` 警告点名(fail-loud,
  *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
-export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "runtime", "governance", "execution", "prompts", "limits"];
+export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits"];
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
  *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
@@ -59,9 +65,9 @@ export const NON_DOMAIN_CONFIG_FILES = new Set(["remote-exec.json"]);
 export const NON_PORTABLE_DOMAIN_REASONS = {
     workers: "FLEET-only:单机没有 reconciler,`{workers:[]}` 的 schema 默认就是正确语义(缺席不需要 stub)。",
     hosts: "FLEET-only:同 workers —— 单机无机器注册表/自动排布,空注册表即正确语义。",
-    systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 center 侧生命周期,单机 lane 无对应执法点。",
+    systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 web-admin 侧生命周期,单机 lane 无对应执法点。",
     projects: "TENANT IDENTITY DATA,不是可搬运的配置:登记簿随包复制进另一个部署 = 凭空多出的身份登记(design/142 §1.4 威胁模型①「carried-in foreign projectId」换了身 import 的衣服)。要带走走 142 §5 的导出面(service 半场)。",
-    entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service/center 边界)。缺席语义如实:本地 buildEffective 给它 schema 默认值(空表),这**不等于**把远端 kill-switch/预算上限搬到了本地 —— 单机 lane 本就没有那个执法点。",
+    entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service / web-admin 边界)。缺席语义如实:本地 buildEffective 给它 schema 默认值(空表),这**不等于**把远端 kill-switch/预算上限搬到了本地 —— 单机 lane 本就没有那个执法点。",
 };
 export class FileConfigStore {
     root;
@@ -74,50 +80,20 @@ export class FileConfigStore {
         this.opts = opts;
     }
     /** Absolute path to a domain's JSON file. Guards the name (defence in depth — a non-domain string like
-     *  `../../secret` must never be joined into a filesystem path, even if a caller bypasses the type). */
+     *  `../../secret` must never be joined into a filesystem path, even if a caller bypasses the type). A retired domain's
+     *  name is accepted: its file is read for the tombstone. */
     domainPath(domain) {
-        if (!isDomainName(domain))
-            throw new Error(`"${domain}" is not a config domain — refusing to build a config.d path (no traversal)`);
-        return path.join(this.root, "config.d", `${domain}.json`);
+        return configDPath(this.root, domain); // the one name guard (no traversal) lives there
     }
-    /** Read + JSON.parse one domain file. A MISSING file (ENOENT) → 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 (literal `null`, an array, a number/string/bool), is CORRUPT → throw, FAIL CLOSED — identical
-     *  discipline to loadRemoteExec + the `file:` ref (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 runtime.json
-     *  drops its commandPolicy/autonomy guardrails and the consumer falls back to env). This also keeps
-     *  getVersion in lock-step with getEffective/getDomain: stableStringify collapses `undefined` (absent) and
-     *  `null` to the SAME bytes, so an empty/null file that resolved to undefined would hash IDENTICALLY to
-     *  "domain absent" and a version-gated poller would skip a change getEffective/getDomain actually FAIL on.
-     *  Every domain schema is a z.object, so a non-object/empty file is never valid — reject all those shapes
-     *  here, once. R17 + R(0.1.27 整体复审). */
+    /** 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,
+     *  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
+     *  `undefined` (absent) and `null` to the SAME bytes, so an empty/null file that resolved to undefined would hash IDENTICALLY to
+     *  "domain absent" and a version-gated poller would skip a change getEffective/getDomain actually FAIL on. R17 + R(0.1.27 整体复审). */
     async #readDomainRaw(domain) {
-        let text;
-        try {
-            text = await readFile(this.domainPath(domain), "utf8");
-        }
-        catch (e) {
-            if (e.code === "ENOENT")
-                return undefined;
-            throw e;
-        }
-        const trimmed = text.trim();
-        // FAIL CLOSED on an empty/whitespace present file (half-write/truncation), same as loadRemoteExec/file: —
-        // to mean "absent → defaults" the file must be MISSING (ENOENT), never present-but-empty.
-        if (!trimmed)
-            throw new Error(`config.d/${domain}.json is empty/whitespace — delete it for the domain default, or write a valid object`);
-        let parsed;
-        try {
-            parsed = JSON.parse(trimmed);
-        }
-        catch {
-            throw new Error(`invalid JSON in config.d/${domain}.json`); // sanitized: never echo the raw file text into the error
-        }
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            const kind = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
-            throw new Error(`config.d/${domain}.json must be a JSON object (got ${kind}) — delete the file for the domain default, or write a valid object`);
-        }
-        return parsed;
+        return readConfigDFile(this.root, domain); // the shared reader guards the name (configDPath)
     }
     /**
      * FAIL-LOUD 扫描(0.19.0):`config.d/` 里存在、但本地读取集**永远不会读**的 `*.json` 文件,逐个经
@@ -152,15 +128,19 @@ export class FileConfigStore {
             const base = name.slice(0, -".json".length);
             if (PORTABLE_DOMAINS.includes(base))
                 continue; // 真被读的域
+            if (isRetiredDomainName(base))
+                continue; // retired 域:由墓碑判(带事实 ⇒ getEffective 抛),不是「没人读的文件」
             onWarning(isDomainName(base)
                 ? { kind: "unread-config-file", file: name, domain: base, why: "non-portable-domain" }
                 : { kind: "unread-config-file", file: name, why: "not-a-domain" });
         }
     }
-    /** Raw (unparsed) values for every PORTABLE domain, keyed by domain name (absent → undefined). */
+    /** 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`
+     *  between a refusal and a read, so a version-gated poller must see it. */
     async #readAllRaw() {
         const out = {};
-        await Promise.all(PORTABLE_DOMAINS.map(async (d) => { out[d] = await this.#readDomainRaw(d); }));
+        await Promise.all([...PORTABLE_DOMAINS, ...RETIRED_DOMAIN_NAMES].map(async (d) => { out[d] = await this.#readDomainRaw(d); }));
         return out;
     }
     /** The max mtime (ISO) across the present portable files, or the epoch when none exist — so `updatedAt`
@@ -186,6 +166,7 @@ export class FileConfigStore {
      *  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.) */
     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)
@@ -199,14 +180,20 @@ export class FileConfigStore {
         return parseInt(stableHash(raws).slice(0, 13), 16); // 13 hex digits ≤ 2^52, safely within u53
     }
     async getEffective(opts) {
+        // Every read entry asks the tombstone first (the same check getDomain runs); what it read (absent / `{}`) joins the version hash.
         if (opts?.tolerant !== true) {
-            const [raws] = await Promise.all([this.#readAllRaw(), this.#warnUnreadFiles()]); // 两条读法同一门(0.19.0)
+            const [retired] = await Promise.all([refuseRetiredDomainFiles(this.root), this.#warnUnreadFiles()]); // 两条读法同一门(0.19.0)
+            const raws = { ...retired };
+            await Promise.all(PORTABLE_DOMAINS.map(async (d) => { raws[d] = await this.#readDomainRaw(d); }));
             const updatedAt = await this.#maxMtimeIso();
             return buildEffective(this.#versionOf(raws), (d) => raws[d], updatedAt, this.opts.onWarning);
         }
         await this.#warnUnreadFiles();
-        const raws = {};
-        const hashRaws = {};
+        // A retired domain's file is read strictly (no tolerance): it exists only to be refused, and an unreadable one is still
+        // an unmigrated document sitting in the directory.
+        const retired = await refuseRetiredDomainFiles(this.root);
+        const raws = { ...retired };
+        const hashRaws = { ...retired };
         const domainErrors = [];
         await Promise.all(PORTABLE_DOMAINS.map(async (d) => {
             try {