@sema-agent/settings-schema 1.0.0

package/dist/file-edit.d.ts

@@ -0,0 +1,36 @@
+import type { z } from "zod";
+import { RemoteExecSpec } from "./remote-exec.js";
+import { type DomainConfig, type DomainName, type EffectiveConfig } from "./types.js";
+export type ValidateResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: z.ZodIssue[];
+};
+/** 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). */
+export declare function validateDomain<K extends DomainName>(domain: K, raw: unknown): ValidateResult<DomainConfig[K]>;
+/** Same, for the remote-exec contract (a standalone contract, not a DOMAIN_SCHEMAS member). */
+export declare function validateRemoteExec(raw: unknown): ValidateResult<RemoteExecSpec>;
+/** 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. */
+export declare function writeDomainFile<K extends DomainName>(root: string, domain: K, value: unknown): Promise<DomainConfig[K]>;
+export interface RequiredEnvName {
+    envName: string;
+    refs: {
+        domain: string;
+        detail: string;
+    }[];
+    /** true if this env-NAME resolves in the supplied environment (.env merged over process.env). */
+    present: boolean;
+}
+/** LIST every env-NAME the current local config requires (across models/workers/mcp + the
+ *  remote-exec backend), marking which are MISSING from the resolved env — the TOC "you still need to set
+ *  these secrets" panel. Reuses collectEnvRefs for the domain side, then appends the remoteExec secret refs. */
+export declare function listRequiredEnvNames(eff: EffectiveConfig, remoteExec: RemoteExecSpec | undefined, resolvedEnv: Record<string, string | undefined>): RequiredEnvName[];

package/dist/file-edit.js

@@ -0,0 +1,125 @@
+/**
+ * TOC editor helpers — the read/write/VALIDATE surface the desktop/CLI builds its OWN config UX on top of
+ * (Clay's decision: only the LIB is shared, the TOC builds its own UI). These expose write/validate, not just
+ * read, so a single-machine consumer never needs the server's routes.
+ *
+ * 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 path from "node:path";
+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";
+/** 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) {
+    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). */
+export function validateDomain(domain, raw) {
+    assertDomainName(domain);
+    let r;
+    try {
+        r = DOMAIN_SCHEMAS[domain].safeParse(raw === undefined ? {} : raw); // explicit null is corrupt, not defaults (R4)
+    }
+    catch {
+        // a hostile getter/Proxy trap threw during traversal — never surface its (secret-bearing) message. R13.
+        return { ok: false, issues: [{ code: "custom", message: `invalid "${domain}" config (a value could not be read during validation)`, path: [] }] };
+    }
+    if (r.success)
+        return { ok: true, value: r.data };
+    return { ok: false, issues: sanitizeZodError(r.error).issues }; // recursive redaction (R13/R14) — no secret echo
+}
+/** Same, for the remote-exec contract (a standalone contract, not a DOMAIN_SCHEMAS member). */
+export function validateRemoteExec(raw) {
+    let r;
+    try {
+        r = RemoteExecSpec.safeParse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ code: "custom", message: "invalid remoteExec (a value could not be read during validation)", path: [] }] };
+    }
+    return r.success ? { ok: true, value: r.data } : { ok: false, issues: sanitizeZodError(r.error).issues }; // no secret echo (R14)
+}
+/** 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 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. */
+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;
+    }
+    return parsed;
+}
+/** LIST every env-NAME the current local config requires (across models/workers/mcp + the
+ *  remote-exec backend), marking which are MISSING from the resolved env — the TOC "you still need to set
+ *  these secrets" panel. Reuses collectEnvRefs for the domain side, then appends the remoteExec secret refs. */
+export function listRequiredEnvNames(eff, remoteExec, resolvedEnv) {
+    const map = new Map();
+    const add = (envName, domain, detail) => {
+        if (!envName)
+            return;
+        const list = map.get(envName) ?? [];
+        list.push({ domain, detail });
+        map.set(envName, list);
+    };
+    for (const r of collectEnvRefs(eff))
+        for (const use of r.refs)
+            add(r.envName, use.domain, use.detail);
+    if (remoteExec) {
+        const re = remoteExec;
+        if (re.provider === "e2b") {
+            add(re.apiKeyEnv, "remoteExec", "e2b.apiKeyEnv");
+            for (const e of re.sandboxEnv ?? [])
+                add(e, "remoteExec", "e2b.sandboxEnv[]");
+        }
+        else if (re.provider === "k8s") {
+            add(re.tokenEnv, "remoteExec", "k8s.tokenEnv");
+            add(re.caCertEnv, "remoteExec", "k8s.caCertEnv");
+            if (re.s3Snapshot) {
+                add(re.s3Snapshot.accessKeyEnv, "remoteExec", "k8s.s3Snapshot.accessKeyEnv");
+                add(re.s3Snapshot.secretKeyEnv, "remoteExec", "k8s.s3Snapshot.secretKeyEnv");
+            }
+        }
+        else if (re.provider === "ssh") {
+            add(re.privateKeyEnv, "remoteExec", "ssh.privateKeyEnv");
+        }
+        else if (re.provider === "remote-docker") {
+            add(re.tlsCertEnv, "remoteExec", "remote-docker.tlsCertEnv");
+            add(re.tlsKeyEnv, "remoteExec", "remote-docker.tlsKeyEnv");
+            add(re.tlsCaEnv, "remoteExec", "remote-docker.tlsCaEnv");
+            add(re.sshKeyEnv, "remoteExec", "remote-docker.sshKeyEnv");
+        }
+        // adb / host / local-docker carry no secret env-NAME refs.
+    }
+    return [...map.entries()]
+        .map(([envName, refs]) => ({ envName, refs, present: resolvedEnv[envName] !== undefined }))
+        .sort((a, b) => a.envName.localeCompare(b.envName));
+}

package/dist/file-store.d.ts

@@ -0,0 +1,89 @@
+import { type EffectiveReadWarning } from "./config-fns.js";
+import type { ConfigReader } from "./reader.js";
+import { type DomainConfig, type DomainName, type EffectiveConfig } 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 附带裁定)。
+ *
+ *  ⚠️ 口径诚实(codex 复审 round1 F4):这是**默认集与本地读取集,不是 API 级硬边界** —— `exportBundle`
+ *  / `readBundle` 的 `domains` 参数可显式传任意 `DomainName`(bundle.ts 不拒非便携域)。把非便携域搬进
+ *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
+ *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
+ *
+ *  🔴 **开新顶层域时必须同步登记本表**(成案 = sema-server #322 真事故):域表是**闭集**,不在这里的
+ *  域名,`config.d/<域>.json` 不会被读进 effective —— 消费方拿到的是「该域缺席」,和文件不存在**逐字
+ *  同形**。当年 `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 type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
+/**
+ * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
+ *
+ * `satisfies Record<Exclude<DomainName, PortableDomain>, string>` 让键集在**编译期**双向咬死:新开一个
+ * 域却不放进 PORTABLE_DOMAINS ⇒ 这里缺行 ⇒ 编译错;把某域改成便携却忘了删行 ⇒ 多余键 ⇒ 编译错。
+ * (此前是「理由写在注释里」,机器只能做子串匹配——域名出现在文件任何角落都算数,等于没门;codex
+ * 复审 round1 F3。)理由要写**为什么它不该被单机/跨部署搬运**,带出处。
+ */
+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 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 本就没有那个执法点。";
+};
+/** One unreadable/corrupt domain FILE surfaced by `getEffective({tolerant:true})`(0.10.12,[897]②)。
+ *  `error` 是 #readDomainRaw 的 sanitized 文案(带文件路径语境、绝不回显文件内容)。 */
+export type DomainReadError = {
+    domain: DomainName;
+    error: string;
+};
+/** `getEffective({tolerant:true})` 的返回:好域照常装配的 effective + 坏文件清单(空数组=全部健康,
+ *  effective 与 strict getEffective() 逐字节一致、version 同值)。 */
+export type TolerantEffective = {
+    effective: EffectiveConfig;
+    domainErrors: DomainReadError[];
+};
+export declare class FileConfigStore implements ConfigReader {
+    #private;
+    private readonly root;
+    private readonly opts;
+    /** `opts.onWarning` (0.8.1): receives buildEffective's read-degradation warnings (grandfathered hosts /
+     *  domain defaulted — see {@link EffectiveReadWarning}) so a TOC shell can surface them; omit = resilient
+     *  but silent. Additive — existing `new FileConfigStore(root)` callers are unchanged. */
+    constructor(root: string, opts?: {
+        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;
+    /** 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.) */
+    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
+     *  would skip the change). `updatedAt` = max file mtime (informational; the content-hash version is the
+     *  authoritative change-detector).
+     *
+     *  TOLERANT MODE(0.10.12,server 接单 seam):strict getEffective 对任何一个坏形 domain 文件
+     *  throw,消费者(server main 单点 catch)只能整包回落 env——models.json 一个坏文件把 skills/mcp/
+     *  scenarios 全域连坐。`getEffective({tolerant:true})` 把 READ 层的坏文件按 parse 层既有的
+     *  {@link DOMAIN_READ_FALLBACK} 同一张表处置:
+     *    - `"default"` 域(models/skills/mcp/… 追加型 capability 目录):该域按 schema default 落 +
+     *      错误单列进 `domainErrors`(fail-closed:default 只会移除能力),其余好域照常生效;
+     *    - `"throw"` 域(governance/rosters/entitlement/…):坏文件仍然 throw——READ 容错绝不放宽
+     *      gate 域的 fail-loud(与 parse 层同一条纪律,defaulting=放权,不许)。
+     *  版本语义:坏域在 version hash 里以 `{__corruptDomainFile: <文件文本 hash>}` 哨兵参与——绝不与
+     *  「文件缺失(absent)」同 bytes(#readDomainRaw 头注的 lock-step 要求),坏→修好、好→坏、
+     *  坏内容 A→坏内容 B 均 bump version,version-gated poller 不漏拍。 */
+    getEffective(): Promise<EffectiveConfig>;
+    getEffective(opts: {
+        tolerant: true;
+    }): Promise<TolerantEffective>;
+    /** 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>;
+}

package/dist/file-store.js

@@ -0,0 +1,238 @@
+/**
+ * FileConfigStore — a local, single-machine config source for the TOC desktop/CLI. Reads the PORTABLE domains
+ * from `<root>/config.d/<domain>.json` (one file per domain, each = exactly that domain's zod object) and
+ * resolves them into an {@link EffectiveConfig} via the SAME pure `buildEffective`/`parseDomain` the server
+ * stores use. Implements ONLY the narrow {@link ConfigReader} (3 methods) — no publish/RBAC/worker-status.
+ *
+ * LOCAL FILE LAYOUT (the TOC owns the root, e.g. `~/.ai-agent/` or a project-local `.ai-agent/`):
+ *   <root>/config.d/<domain>.json   for every domain in {@link PORTABLE_DOMAINS} — that constant is the
+ *                    AUTHORITY; do NOT hand-copy the list here (the hand-written enumeration that used to sit
+ *                    on this line silently missed `prompts` for three releases — codex 复审 round2 F5).
+ *   <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).
+ *    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).
+ *  - 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}(禁裸排除)。
+ *  - 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,
+ *    passed EXPLICITLY into buildEffective (the determinism refactor) so identical files ⇒ identical bytes.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { buildEffective, DOMAIN_READ_FALLBACK, parseDomainLoud } from "./config-fns.js";
+import { stableHash } from "./hash.js";
+import { isDomainName } 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 附带裁定)。
+ *
+ *  ⚠️ 口径诚实(codex 复审 round1 F4):这是**默认集与本地读取集,不是 API 级硬边界** —— `exportBundle`
+ *  / `readBundle` 的 `domains` 参数可显式传任意 `DomainName`(bundle.ts 不拒非便携域)。把非便携域搬进
+ *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
+ *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
+ *
+ *  🔴 **开新顶层域时必须同步登记本表**(成案 = sema-server #322 真事故):域表是**闭集**,不在这里的
+ *  域名,`config.d/<域>.json` 不会被读进 effective —— 消费方拿到的是「该域缺席」,和文件不存在**逐字
+ *  同形**。当年 `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"];
+/** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
+ *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读。 */
+const NON_DOMAIN_CONFIG_FILES = new Set(["remote-exec.json"]);
+/**
+ * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
+ *
+ * `satisfies Record<Exclude<DomainName, PortableDomain>, string>` 让键集在**编译期**双向咬死:新开一个
+ * 域却不放进 PORTABLE_DOMAINS ⇒ 这里缺行 ⇒ 编译错;把某域改成便携却忘了删行 ⇒ 多余键 ⇒ 编译错。
+ * (此前是「理由写在注释里」,机器只能做子串匹配——域名出现在文件任何角落都算数,等于没门;codex
+ * 复审 round1 F3。)理由要写**为什么它不该被单机/跨部署搬运**,带出处。
+ */
+export const NON_PORTABLE_DOMAIN_REASONS = {
+    workers: "FLEET-only:单机没有 reconciler,`{workers:[]}` 的 schema 默认就是正确语义(缺席不需要 stub)。",
+    hosts: "FLEET-only:同 workers —— 单机无机器注册表/自动排布,空注册表即正确语义。",
+    systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 center 侧生命周期,单机 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 本就没有那个执法点。",
+};
+export class FileConfigStore {
+    root;
+    opts;
+    /** `opts.onWarning` (0.8.1): receives buildEffective's read-degradation warnings (grandfathered hosts /
+     *  domain defaulted — see {@link EffectiveReadWarning}) so a TOC shell can surface them; omit = resilient
+     *  but silent. Additive — existing `new FileConfigStore(root)` callers are unchanged. */
+    constructor(root, opts = {}) {
+        this.root = root;
+        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). */
+    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`);
+    }
+    /** 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 整体复审). */
+    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;
+    }
+    /**
+     * FAIL-LOUD 扫描(0.19.0):`config.d/` 里存在、但本地读取集**永远不会读**的 `*.json` 文件,逐个经
+     * `onWarning` 点名(`"unread-config-file"`)。
+     *
+     * 成案 = sema-server #322:消费方开了新顶层域 `limits` 并发布 `config.d/limits.json`,而本包的域表是
+     * 闭集 —— 文件在、进程跑、限额还是 env 老值,**零告警**(「域缺席」与「文件不存在」在下游逐字同形)。
+     * 修法方向是**响亮,不是收紧**:未登记文件照旧不读(拒收会让一个无害的散落文件打死整个部署),但必须
+     * 说出来。两类分开报,因为处置不同:`not-a-domain` = 名字打错 / 消费方开了本包还不认识的域(要来本包
+     * 登记);`non-portable-domain` = 域认识但单机 lane 刻意不读(理由见 {@link NON_PORTABLE_DOMAIN_REASONS})。
+     *
+     * 只在挂了 `onWarning` 时才 readdir —— 没接通道的调用方不该为一条没人听的警告付 IO(诚实登记:
+     * 因此本门的响亮程度取决于消费方接不接这个座)。忽略:隐藏文件(含 file-edit 原子写的 `.<域>.json.*.tmp`
+     * 中间态)、非 `.json`、{@link NON_DOMAIN_CONFIG_FILES}。
+     */
+    async #warnUnreadFiles() {
+        const onWarning = this.opts.onWarning;
+        if (!onWarning)
+            return;
+        let names;
+        try {
+            names = await readdir(path.join(this.root, "config.d"));
+        }
+        catch {
+            // 目录读不了(不存在 / 只有 x 没有 r 的目录权限)⇒ 本次扫不了,**不抛**:这条是尽力而为的审计线,
+            // 绝不能把一次本来能成功的 getEffective 拖成失败(域文件本身仍按名逐个打开,该失败的自然会失败)。
+            return;
+        }
+        for (const name of names) {
+            if (name.startsWith(".") || !name.endsWith(".json") || NON_DOMAIN_CONFIG_FILES.has(name))
+                continue;
+            const base = name.slice(0, -".json".length);
+            if (PORTABLE_DOMAINS.includes(base))
+                continue; // 真被读的域
+            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). */
+    async #readAllRaw() {
+        const out = {};
+        await Promise.all(PORTABLE_DOMAINS.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`
+     *  is deterministic for a given set of files (not the wall clock). */
+    async #maxMtimeIso() {
+        let maxMs = 0;
+        await Promise.all(PORTABLE_DOMAINS.map(async (d) => {
+            try {
+                const s = await stat(this.domainPath(d));
+                if (s.mtimeMs > maxMs)
+                    maxMs = s.mtimeMs;
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    throw e;
+            }
+        }));
+        return new Date(maxMs).toISOString();
+    }
+    /** 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.) */
+    async getDomain(domain) {
+        const raw = await this.#readDomainRaw(domain);
+        if (raw === undefined)
+            return undefined; // missing/empty file → domain absent (not schema defaults)
+        // 0.19.0(codex 复审 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). */
+    #versionOf(raws) {
+        return parseInt(stableHash(raws).slice(0, 13), 16); // 13 hex digits ≤ 2^52, safely within u53
+    }
+    async getEffective(opts) {
+        if (opts?.tolerant !== true) {
+            const [raws] = await Promise.all([this.#readAllRaw(), this.#warnUnreadFiles()]); // 两条读法同一门(0.19.0)
+            const updatedAt = await this.#maxMtimeIso();
+            return buildEffective(this.#versionOf(raws), (d) => raws[d], updatedAt, this.opts.onWarning);
+        }
+        await this.#warnUnreadFiles();
+        const raws = {};
+        const hashRaws = {};
+        const domainErrors = [];
+        await Promise.all(PORTABLE_DOMAINS.map(async (d) => {
+            try {
+                const v = await this.#readDomainRaw(d);
+                raws[d] = v;
+                hashRaws[d] = v;
+            }
+            catch (e) {
+                if (DOMAIN_READ_FALLBACK[d] === "throw")
+                    throw e; // gate 域:READ 容错也不放宽 fail-loud
+                domainErrors.push({ domain: d, error: e instanceof Error ? e.message : String(e) });
+                raws[d] = undefined; // buildEffective 按 absent → schema default 落(fail-closed)
+                // 哨兵进 hash:用文件文本 hash 区分不同坏内容;读不回文本(竞态删除等)退回错误文案。
+                let textHash;
+                try {
+                    textHash = stableHash((await readFile(this.domainPath(d), "utf8")).trim());
+                }
+                catch {
+                    textHash = stableHash(e instanceof Error ? e.message : String(e));
+                }
+                hashRaws[d] = { __corruptDomainFile: textHash };
+            }
+        }));
+        const updatedAt = await this.#maxMtimeIso();
+        const effective = buildEffective(this.#versionOf(hashRaws), (d) => raws[d], updatedAt, this.opts.onWarning);
+        return { effective, domainErrors };
+    }
+    /** Stable version number for the current files: same files ⇒ same number ⇒ a consumer's "skip re-apply if
+     *  version unchanged" works locally too. */
+    async getVersion() {
+        return this.#versionOf(await this.#readAllRaw());
+    }
+}