@sema-agent/settings-schema 11.0.0 → 11.2.0

package/dist/cli.js

@@ -1,37 +1,43 @@
 /**
  * `settings-schema` 命令行的核心(11.0.0)—— 子命令只有一个:`migrate <config.d 目录> [--check]`,即一次性迁移
  * `migrateStoredDocuments`(`./one-time-migrations`)的目录形(本地 config.d / 离线文件用;web-admin 在它起服时直接调同一只函数)。
+ * 目录形的语义(读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件)只有一处实现:`migrateConfigDirectory`(`./config-dir-migration`,`./node` 导出,引擎起服调同一只);
+ * 本模块是它的**渲染器**:把它的结果闭集渲染成退出码、报告行与 stderr 句子。命令行的覆盖面是全部配置域加 retired 域。
  * 目录被当作**一个 scope 的全集**(`coverage: "scope"`):目录里没有的域文件就是从未设过。
  *
- * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(那是本包唯一用 fs 写文件的地方),所以测试可以直接驱动它。
+ * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(真绑定是 `./config-dir-io` 的 `nodeConfigDirectoryIo`,写盘用的是 `./atomic-write` 那一只原子写器 —— 写法与文件模式在那里一处定),所以测试可以直接驱动它。
  * 不进主桶 —— 它是 bin 的实现,不是契约面。
  *
- * 读哪些文件:目录里 `<名>.json`,名是配置域或retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁);别的文件
+ * 读哪些文件:目录里 `<名>.json`,名是配置域或 retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁);别的文件
  * (`remote-exec.json`、隐藏文件、不认识的名)不读不动。
  *
- * 退出码:0 = 已写回 / 无事可做;1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 {@link verdictOf}),**一字不写**;
- * 2 = 用法 / 读目录 / 读文件错,或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
+ * 零域文档分两形:**有条目却没有域文档**(任何非 `.` 开头的条目 —— 子目录、说明文件、不认识的名)⇒ 退出 2;**目录真空**(零条目,或只有以 `.` 开头的条目)⇒ 照常走判定,
+ * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
+ *
+ * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
+ * 2 = 用法 / 读目录 / 读文件错,或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
+ * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
  *
  * ## 报告形(让「没写」在机读上不可能被读成「写了」)
  * 退出码 0 / 1 / 3 时 stdout 恰两行:第 1 行 = **唯一结论行** `outcome=<refused|applied|noop|pending> written=<true|false>`;第 2 行 = JSON 报告
  * (`event: "stored_documents_migrated"`,逐条收据只点名坐标与处置、不带值),同带 `outcome` / `written`。`written` 由 `outcome` 派生
  * (只有 `applied` 写盘)。**键名带时态**:`written=true` 才有 `applied`;没写(refused / noop / pending)时是 `wouldApply`。
- * 结论行在**写盘成功之后**才出(写盘抛错 ⇒ 没有 `outcome=applied`)。写盘次序:先写改过 / 新建的文件,最后删被移除的retired 域文件 ——
+ * 结论行在**写盘成功之后**才出(写盘抛错 ⇒ 没有 `outcome=applied`)。写盘次序:先写改过 / 新建的文件,最后删被移除的 retired 域文件 ——
  * 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
  */
-import { z } from "zod";
-import { formatConfigPath, parseDomain } from "./config-fns.js";
-import { judgeConfigDText } from "./config-d-file.js";
-import { migrateStoredDocuments } from "./one-time-migrations.js";
-import { MIGRATE_COMMAND } from "./retired-form.js";
-import { isDomainName, isRetiredDomainName } from "./types.js";
+import { reportReceipt, joinDirPath, migrateConfigDirectory } from "./config-dir-migration.js";
+import { MIGRATE_COMMAND_TEMPLATE, migrateCommandFor } from "./retired-form.js";
+import { DOMAINS, RETIRED_DOMAINS } from "./types.js";
+/** 命令行的覆盖面:全部配置域加 retired 域(便携与否不论 —— 离线的 `workers.json` 一样迁)。 */
+const COVERED_DOCUMENTS = [...DOMAINS, ...Object.keys(RETIRED_DOMAINS)];
 const USAGE = [
-    `usage: ${MIGRATE_COMMAND} <config.d directory> [--check]`,
+    `usage: ${MIGRATE_COMMAND_TEMPLATE} [--check]`,
     "  Runs the one-time migrations (@sema-agent/settings-schema/one-time-migrations) over every <domain>.json in the directory, read as one",
     "  scope (a missing domain file = never set): writes the rewritten files in place and removes retired-domain files (runtime.json) only when",
     "  nothing is refused and every document it would write reads as a whole domain; --check runs the same verdict and only reports (exit 3",
-    "  if something would change).",
+    "  if something would change). The argument is the config.d directory itself; a directory that has entries but no <domain>.json among them is",
+    "  refused (exit 2); an empty directory has nothing to migrate (exit 0).",
     "  stdout (exit 0 / 1 / 3): line 1 = outcome=<refused|applied|noop|pending> written=<true|false>, line 2 = the JSON report",
     "  (applied only when written=true; otherwise wouldApply).",
 ].join("\n");
@@ -50,61 +56,6 @@ function writtenOf(outcome) {
         }
     }
 }
-/** 报告里的一张收据(坐标出门形;不带值)。 */
-function reportReceipt(r) {
-    const base = { migration: r.migration, document: r.document, path: formatConfigPath(r.path), appliedAs: r.appliedAs };
-    switch (r.appliedAs) {
-        case "moved":
-            return { ...base, to: `${r.to.document}:${formatConfigPath(r.to.path)}` };
-        case "refused":
-            return { ...base, reason: r.reason };
-        case "rewritten":
-        case "dropped-shadowed":
-        case "dropped-inert":
-            return base;
-        default: {
-            const unhandled = r;
-            throw new Error(`settings-schema: unhandled receipt ${JSON.stringify(unhandled)}`);
-        }
-    }
-}
-/** 整域终判的一条拒(issue 来自 `parseDomain`,已过本包唯一的脱敏器 —— 坐标段与句子都是出门形)。 */
-function wholeDomainRefusal(document, path, reason) {
-    return { migration: null, document, path: formatConfigPath(path), appliedAs: "refused", reason };
-}
-/**
- * 迁移结果 → 结论。顺序:迁移步拒 → 无改动 ⇒ noop → **整域终判**(要写回的每个域文档 —— 改过的、新建的 —— 过读侧那一只
- * `parseDomain`:名字 / 路由唯一这类跨行规则只有整域判得出)→ 有改动。整域终判在 `--check` 之前:否则同一个目录 `--check` 报 pending、
- * 真跑写出一份读侧必拒的文档。没改的文件不归这里判(迁移不碰它,它读不读得进是读者的事)。
- */
-function verdictOf(input, migrated, receipts) {
-    const refusedReceipts = receipts.filter((r) => r.appliedAs === "refused");
-    if (refusedReceipts.length > 0) {
-        return { kind: "refused", refused: refusedReceipts.map(reportReceipt), why: `${refusedReceipts.length} coordinate(s) cannot be migrated (see "refused") — fix them by hand and re-run` };
-    }
-    if (receipts.length === 0)
-        return { kind: "noop" };
-    const refused = [];
-    for (const [name, doc] of Object.entries(migrated)) {
-        if (!isDomainName(name) || (Object.prototype.hasOwnProperty.call(input, name) && input[name] === doc))
-            continue;
-        try {
-            parseDomain(name, doc);
-        }
-        catch (err) {
-            if (err instanceof z.ZodError)
-                for (const i of err.issues)
-                    refused.push(wholeDomainRefusal(name, i.path, i.message));
-            else
-                refused.push(wholeDomainRefusal(name, [], err instanceof Error ? err.message : String(err)));
-        }
-    }
-    if (refused.length > 0) {
-        const documents = [...new Set(refused.map((r) => String(r.document)))];
-        return { kind: "refused", refused, why: `the migrated ${documents.join(" / ")} document(s) do not read as a whole domain (see "refused") — fix them by hand and re-run` };
-    }
-    return { kind: "changes" };
-}
 /** 一次发出报告:结论行 + JSON 行(一次 `stdout` 调用)。 */
 function reportOf(outcome, dir, applied, refused) {
     const written = writtenOf(outcome);
@@ -113,12 +64,18 @@ function reportOf(outcome, dir, applied, refused) {
         outcome,
         written,
         dir,
-        [written ? "applied" : "wouldApply"]: applied.map(reportReceipt),
+        [written ? "applied" : "wouldApply"]: applied.map((r) => reportReceipt(r)),
         refused,
     });
     return `outcome=${outcome} written=${written}\n${json}\n`;
 }
-const join = (dir, name) => `${dir.replace(/[\\/]+$/, "")}/${name}`;
+/** 「有条目却没有域文档」的拒句:点名这个目录、说要的是 `config.d` 目录本身;`<dir>/config.d` 在场(探一次)就直接点它 —— 最常见的错是填了它的上一层。指路的命令里路径过 shell 引用,可直接粘贴。 */
+async function noDomainDocumentsSentence(dir, io) {
+    const nested = joinDirPath(dir, "config.d");
+    const nestedExists = await io.readDir(nested).then(() => true, () => false);
+    const base = `settings-schema: no domain documents in ${dir} (a domain document is <domain>.json, e.g. models.json) — the argument is the config.d directory itself`;
+    return nestedExists ? `${base}; ${nested} exists — run: ${migrateCommandFor(nested)}` : base;
+}
 export async function runSettingsSchemaCli(argv, io) {
     const [command, ...rest] = argv;
     const check = rest.includes("--check");
@@ -128,67 +85,36 @@ export async function runSettingsSchemaCli(argv, io) {
         io.stderr(`${USAGE}\n`);
         return 2;
     }
-    let names;
-    try {
-        names = await io.readDir(dir);
-    }
-    catch (err) {
-        io.stderr(`settings-schema: cannot read directory ${dir}: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 2;
-    }
-    const docs = {};
-    for (const name of [...names].sort()) {
-        if (name.startsWith(".") || !name.endsWith(".json"))
-            continue;
-        const base = name.slice(0, -".json".length);
-        if (!isDomainName(base) && !isRetiredDomainName(base))
-            continue;
-        let text;
-        try {
-            text = await io.readFile(join(dir, name));
-        }
-        catch (err) {
-            io.stderr(`settings-schema: cannot read ${name}: ${err instanceof Error ? err.message : String(err)}\n`);
+    const m = await migrateConfigDirectory(dir, { documents: COVERED_DOCUMENTS, io, check });
+    switch (m.kind) {
+        case "unreadable":
+            io.stderr(`settings-schema: ${m.reason}\n`);
             return 2;
-        }
-        try {
-            docs[base] = judgeConfigDText(base, text); // the one config.d file judge: empty / whitespace / bad JSON / not an object ⇒ same sentence as FileConfigStore
-        }
-        catch (err) {
-            io.stderr(`settings-schema: ${err instanceof Error ? err.message : String(err)}\n`);
-            return 2;
-        }
-    }
-    const m = migrateStoredDocuments(docs, { coverage: "scope" });
-    const applied = m.receipts.filter((r) => r.appliedAs !== "refused");
-    const verdict = verdictOf(docs, m.docs, m.receipts);
-    switch (verdict.kind) {
+        case "no-documents":
+            if (m.entries.some((name) => !name.startsWith("."))) {
+                // The directory has entries and none of them is a domain document: a no-op report (rc 0) would read as "this scope is migrated" for a
+                // directory the command never looked into. A directory with nothing visible in it (empty, or only dot entries) is a legitimate scope.
+                io.stderr(`${await noDomainDocumentsSentence(dir, io)}\n`);
+                return 2;
+            }
+            io.stdout(reportOf("noop", dir, [], []));
+            return 0;
         case "refused":
-            io.stdout(reportOf("refused", dir, applied, verdict.refused));
-            io.stderr(`settings-schema: ${verdict.why}; nothing was written\n`);
+            io.stdout(reportOf("refused", dir, m.applied, m.refused));
+            io.stderr(`settings-schema: ${m.why}; nothing was written\n`);
             return 1;
         case "noop":
             io.stdout(reportOf("noop", dir, [], []));
             return 0;
-        case "changes":
-            break;
+        case "pending":
+            io.stdout(reportOf("pending", dir, m.applied, []));
+            return 3;
+        case "applied":
+            io.stdout(reportOf("applied", dir, m.applied, [])); // 写盘成功之后才报 applied
+            return 0;
         default: {
-            const unhandled = verdict;
-            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+            const unhandled = m;
+            throw new Error(`settings-schema: unhandled migration result ${JSON.stringify(unhandled)}`);
         }
     }
-    if (check) {
-        io.stdout(reportOf("pending", dir, applied, []));
-        return 3;
-    }
-    for (const [name, doc] of Object.entries(m.docs)) {
-        if (Object.prototype.hasOwnProperty.call(docs, name) && docs[name] === doc)
-            continue;
-        await io.writeFileAtomic(join(dir, `${name}.json`), `${JSON.stringify(doc, null, 2)}\n`);
-    }
-    for (const name of Object.keys(docs))
-        if (!Object.prototype.hasOwnProperty.call(m.docs, name))
-            await io.removeFile(join(dir, `${name}.json`));
-    io.stdout(reportOf("applied", dir, applied, [])); // 写盘成功之后才报 applied
-    return 0;
 }

package/dist/config-dir-io.d.ts

@@ -0,0 +1,2 @@
+import type { ConfigDirectoryIo } from "./config-dir-migration.js";
+export declare const nodeConfigDirectoryIo: ConfigDirectoryIo;

package/dist/config-dir-io.js

@@ -0,0 +1,13 @@
+/**
+ * `migrateConfigDirectory`(`./config-dir-migration`)的**真 I/O 绑定**(Node 专用):读目录 / 读文件 / 删文件走 `node:fs/promises`,写盘走本包唯一的原子写器
+ * `./atomic-write`(同目录临时文件 → rename;`config-document` 类的模式规则:新建 0o644 经 umask、已有的沿用原模式;目标是符号链接则写到它指向的真文件)。
+ * 命令行入口与引擎起服的目录迁移注入同一份,写法与文件模式因此只在原子写器那一处定。
+ */
+import { readdir, readFile, unlink } from "node:fs/promises";
+import { writeFileAtomic } from "./atomic-write.js";
+export const nodeConfigDirectoryIo = {
+    readDir: (path) => readdir(path),
+    readFile: (path) => readFile(path, "utf8"),
+    writeFileAtomic: async (path, text) => writeFileAtomic(path, text, "config-document"), // the files this migration writes are config.d domain documents
+    removeFile: (path) => unlink(path),
+};

package/dist/config-dir-migration.d.ts

@@ -0,0 +1,64 @@
+import { type MigrationReceipt } from "./one-time-migrations.js";
+import { type DomainName, type RetiredDomainName } from "./types.js";
+/** 注入的 I/O(本模块不碰 `node:fs`)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟。 */
+export interface ConfigDirectoryIo {
+    readDir(path: string): Promise<string[]>;
+    readFile(path: string): Promise<string>;
+    writeFileAtomic(path: string, text: string): Promise<void>;
+    removeFile(path: string): Promise<void>;
+}
+/** 一条拒绝 —— 迁移步的拒(收据 `refused`)与整域终判的拒**同一套形**:`migration`(整域终判拒为 `null`)/ `document` / `path`(相对该域文档,出门形)/ `appliedAs: "refused"` / `reason`。
+ *  句子来自本包唯一的脱敏器,坐标段与句子都是出门形、不带值。 */
+export type ConfigDirectoryRefusal = {
+    readonly migration: string | null;
+    readonly document: string;
+    readonly path: string;
+    readonly appliedAs: "refused";
+    readonly reason: string;
+};
+export type ConfigDirectoryMigration = {
+    readonly kind: "unreadable";
+    readonly reason: string;
+} | {
+    readonly kind: "no-documents";
+    readonly entries: readonly string[];
+} | {
+    readonly kind: "refused";
+    readonly read: readonly string[];
+    readonly applied: readonly MigrationReceipt[];
+    readonly refused: readonly ConfigDirectoryRefusal[];
+    readonly why: string;
+} | {
+    readonly kind: "noop";
+    readonly read: readonly string[];
+} | {
+    readonly kind: "pending";
+    readonly read: readonly string[];
+    readonly applied: readonly MigrationReceipt[];
+} | {
+    readonly kind: "applied";
+    readonly read: readonly string[];
+    readonly applied: readonly MigrationReceipt[];
+    readonly written: readonly string[];
+    readonly removed: readonly string[];
+};
+export interface MigrateConfigDirectoryOptions {
+    /** 覆盖面:调用方读的域名集(配置域或 retired 域)。拼错的名字 ⇒ 抛 `TypeError`,不让它悄悄变成「什么都没覆盖」。 */
+    readonly documents: readonly (DomainName | RetiredDomainName)[];
+    readonly io: ConfigDirectoryIo;
+    /** 只判、不写:有改动且整域判得过 ⇒ `pending`。默认 `false`。 */
+    readonly check?: boolean;
+}
+/** 目录加文件名(目录尾部的分隔符折掉)。包内私有(不进 `./node`)。 */
+export declare const joinDirPath: (dir: string, name: string) => string;
+type RefusedReceipt = Extract<MigrationReceipt, {
+    readonly appliedAs: "refused";
+}>;
+/** 一张收据的出门形(坐标只点名、不带值):`refused` 带 `reason`(= {@link ConfigDirectoryRefusal} 的形),`moved` 带 `to`。包内私有 —— 命令行报告用它渲染 `applied`。 */
+export declare function reportReceipt(r: RefusedReceipt): ConfigDirectoryRefusal;
+export declare function reportReceipt(r: MigrationReceipt): Record<string, unknown>;
+/**
+ * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
+ */
+export declare function migrateConfigDirectory(dir: string, opts: MigrateConfigDirectoryOptions): Promise<ConfigDirectoryMigration>;
+export {};

package/dist/config-dir-migration.js

@@ -0,0 +1,167 @@
+/**
+ * **一个 `config.d` 目录的一次性迁移** —— 「读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件」这一条语义的唯一实现。命令行(`migrate <config.d 目录> [--check]`,
+ * 见 `./cli`)是它的渲染器(退出码 + 报告行);引擎起服时对本地 `config.d` 的迁移调同一只函数,不按同语义自写一份。
+ *
+ * **覆盖面 = 调用方读的域名集**({@link MigrateConfigDirectoryOptions.documents}):覆盖面内没有的域文件就是从未设过(一次性迁移的 `coverage: "scope"`);
+ * 覆盖面外的文件不读、不判、不写、不删 —— 本调用方没有资格改写它从不消费的数据,它们是坏文件也挡不住覆盖面内的迁移。命令行的覆盖面是全部配置域加 retired 域;
+ * 引擎的覆盖面是它本地读腿会读的那几份。**迁移不许越过覆盖面去写**:retired 的 `runtime` 域迁出时要写 `governance` 与 `limits`(`RUNTIME_LIFT_TARGETS`),
+ * 覆盖面没把这两个域一并包进来时,目录算不上「一个 scope 的全集」—— 迁移按 `coverage: "partial"` 走(`runtime` 在那一支上以收据 `refused` 拒迁、一字不写),
+ * 不会把覆盖面外已有的 `governance.json` / `limits.json` 当作「从未设过」覆盖掉;日后若别的迁移步新建覆盖面外的文档,函数响亮抛(守卫),不静默写。
+ *
+ * 本模块不碰 `node:fs`:读写由注入的 {@link ConfigDirectoryIo} 做(真绑定是 `./config-dir-io` 的 `nodeConfigDirectoryIo`,写盘用 `./atomic-write` 那一只原子写器与它的模式表),
+ * 所以测试可以直接喂内存实现。
+ *
+ * ## 结果是一个闭集({@link ConfigDirectoryMigration}),调用方穷举
+ *  · `unreadable`  —— 读不了目录 / 某份文件,或某份文档是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象,与 `FileConfigStore` 同一只判、同一句)。一字不写。
+ *  · `no-documents`—— 覆盖面内一份文档都没找到;带回目录清单 `entries`(调用方自己判这是「填错了目录」还是「真空的新目录」)。一字不写。
+ *  · `refused`     —— 迁移步拒(收据 `refused`:要猜才改得动的形)**或**要写回的文档整域读不进(整域终判:名字 / 路由唯一这类跨行规则只有整域判得出)。一字不写。
+ *  · `noop`        —— 读到了文档、没有要改的。
+ *  · `pending`     —— `check: true` 且有改动、整域判得过:一字不写。
+ *  · `applied`     —— 已写回:先写改过 / 新建的文档,最后删被移除的 retired 域文件 —— 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
+ * 写盘阶段的 I/O 错误**原样抛出**(不吞、不改写):已写完的文档留在新位上,再跑一次幂等收尾。
+ */
+import { z } from "zod";
+import { formatConfigPath, parseDomain } from "./config-fns.js";
+import { judgeConfigDText } from "./config-d-file.js";
+import { migrateStoredDocuments } from "./one-time-migrations.js";
+import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
+import { isDomainName, isRetiredDomainName } from "./types.js";
+/** 目录加文件名(目录尾部的分隔符折掉)。包内私有(不进 `./node`)。 */
+export const joinDirPath = (dir, name) => `${dir.replace(/[\\/]+$/, "")}/${name}`;
+export function reportReceipt(r) {
+    const base = { migration: r.migration, document: r.document, path: formatConfigPath(r.path), appliedAs: r.appliedAs };
+    switch (r.appliedAs) {
+        case "moved":
+            return { ...base, to: `${r.to.document}:${formatConfigPath(r.to.path)}` };
+        case "refused":
+            return { ...base, reason: r.reason };
+        case "rewritten":
+        case "dropped-shadowed":
+        case "dropped-inert":
+            return base;
+        default: {
+            const unhandled = r;
+            throw new Error(`settings-schema: unhandled receipt ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/** 整域终判的一条拒(issue 来自 `parseDomain`,已过本包唯一的脱敏器 —— 坐标段与句子都是出门形)。 */
+function wholeDomainRefusal(document, path, reason) {
+    return { migration: null, document, path: formatConfigPath(path), appliedAs: "refused", reason };
+}
+/**
+ * 迁移结果 → 结论。顺序:迁移步拒 → 无改动 ⇒ noop → **整域终判**(要写回的每个域文档 —— 改过的、新建的 —— 过读侧那一只
+ * `parseDomain`:名字 / 路由唯一这类跨行规则只有整域判得出)→ 有改动。整域终判在 `check` 之前:否则同一个目录 `check` 报 pending、
+ * 真跑写出一份读侧必拒的文档。没改的文件不归这里判(迁移不碰它,它读不读得进是读者的事)。
+ */
+function verdictOf(input, migrated, receipts) {
+    const refusedReceipts = receipts.filter((r) => r.appliedAs === "refused");
+    if (refusedReceipts.length > 0) {
+        return { kind: "refused", refused: refusedReceipts.map((r) => reportReceipt(r)), why: `${refusedReceipts.length} coordinate(s) cannot be migrated (see "refused") — fix them by hand and re-run` };
+    }
+    if (receipts.length === 0)
+        return { kind: "noop" };
+    const refused = [];
+    for (const [name, doc] of Object.entries(migrated)) {
+        if (!isDomainName(name) || (Object.prototype.hasOwnProperty.call(input, name) && input[name] === doc))
+            continue;
+        try {
+            parseDomain(name, doc);
+        }
+        catch (err) {
+            if (err instanceof z.ZodError)
+                for (const i of err.issues)
+                    refused.push(wholeDomainRefusal(name, i.path, i.message));
+            else
+                refused.push(wholeDomainRefusal(name, [], err instanceof Error ? err.message : String(err)));
+        }
+    }
+    if (refused.length > 0) {
+        const documents = [...new Set(refused.map((r) => r.document))];
+        return { kind: "refused", refused, why: `the migrated ${documents.join(" / ")} document(s) do not read as a whole domain (see "refused") — fix them by hand and re-run` };
+    }
+    return { kind: "changes" };
+}
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
+ */
+export async function migrateConfigDirectory(dir, opts) {
+    const covered = new Set();
+    for (const name of opts.documents) {
+        if (!isDomainName(name) && !isRetiredDomainName(name))
+            throw new TypeError(`migrateConfigDirectory: "${String(name)}" is not a config domain or a retired domain — the coverage names the documents the caller reads`);
+        covered.add(name);
+    }
+    const { io } = opts;
+    let names;
+    try {
+        names = await io.readDir(dir);
+    }
+    catch (err) {
+        return { kind: "unreadable", reason: `cannot read directory ${dir}: ${messageOf(err)}` };
+    }
+    const docs = {};
+    for (const name of [...names].sort()) {
+        if (name.startsWith(".") || !name.endsWith(".json"))
+            continue;
+        const base = name.slice(0, -".json".length);
+        if (!covered.has(base))
+            continue;
+        let text;
+        try {
+            text = await io.readFile(joinDirPath(dir, name));
+        }
+        catch (err) {
+            return { kind: "unreadable", reason: `cannot read ${name}: ${messageOf(err)}` };
+        }
+        try {
+            docs[base] = judgeConfigDText(base, text); // the one config.d file judge: empty / whitespace / bad JSON / not an object ⇒ same sentence as FileConfigStore
+        }
+        catch (err) {
+            return { kind: "unreadable", reason: messageOf(err) };
+        }
+    }
+    const read = Object.keys(docs);
+    if (read.length === 0)
+        return { kind: "no-documents", entries: names };
+    // 目录是不是「一个 scope 的全集」只看一件事:SS-M1 要写的目标域是不是都在覆盖面里(见文件头);不是 ⇒ partial,runtime 的迁移被它自己拒掉。
+    const coverage = RUNTIME_LIFT_TARGETS.every((target) => covered.has(target)) ? "scope" : "partial";
+    const m = migrateStoredDocuments(docs, { coverage });
+    const outside = Object.keys(m.docs).filter((name) => !Object.prototype.hasOwnProperty.call(docs, name) && !covered.has(name));
+    if (outside.length > 0) {
+        // 守卫:迁移新建了覆盖面外的文档。那份文件调用方没读过,「从未设过」只对覆盖面内成立 —— 写下去会覆盖它。今天不会发生(见文件头);发生了就是迁移步的写入域变了,这里先红。
+        throw new Error(`migrateConfigDirectory: the migration produced document(s) outside the coverage (${outside.join(", ")}) — refusing to write files the caller did not read`);
+    }
+    const applied = m.receipts.filter((r) => r.appliedAs !== "refused");
+    const verdict = verdictOf(docs, m.docs, m.receipts);
+    switch (verdict.kind) {
+        case "refused":
+            return { kind: "refused", read, applied, refused: verdict.refused, why: verdict.why };
+        case "noop":
+            return { kind: "noop", read };
+        case "changes":
+            break;
+        default: {
+            const unhandled = verdict;
+            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+        }
+    }
+    if (opts.check === true)
+        return { kind: "pending", read, applied };
+    const written = [];
+    const removed = [];
+    for (const [name, doc] of Object.entries(m.docs)) {
+        if (Object.prototype.hasOwnProperty.call(docs, name) && docs[name] === doc)
+            continue;
+        await io.writeFileAtomic(joinDirPath(dir, `${name}.json`), `${JSON.stringify(doc, null, 2)}\n`);
+        written.push(`${name}.json`);
+    }
+    for (const name of Object.keys(docs)) {
+        if (Object.prototype.hasOwnProperty.call(m.docs, name))
+            continue;
+        await io.removeFile(joinDirPath(dir, `${name}.json`));
+        removed.push(`${name}.json`);
+    }
+    return { kind: "applied", read, applied, written, removed };
+}

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,8 +5,9 @@
  *
  * 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 { RetiredDomainError, parseDomain, sanitizeZodError } from "./config-fns.js";
@@ -25,8 +26,6 @@ function assertDomainName(domain) {
     }
 }
 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). */
@@ -61,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.js

@@ -18,7 +18,7 @@
  *    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
- *    <dir>` rewrites the directory); `{}` carries nothing and is left alone. It is never an "unread file".
+ *    <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,

package/dist/index.d.ts

@@ -29,4 +29,5 @@ export * from "./api/pull-token.js";
 export * from "./api/feedback.js";
 export * from "./web-admin-env.js";
 export * from "./web-admin-credential.js";
+export * from "./web-admin-session-url.js";
 export * from "./retired-envs.js";

package/dist/index.js

@@ -29,6 +29,7 @@ export * from "./api/pull-token.js"; // scope-bound token FORM + minting rule (o
 export * from "./api/feedback.js"; // /bug report wire contract: FeedbackSubmitRequest (POST body) + FeedbackWire / FeedbackListResponse + the two caps, pure/browser-safe
 export * from "./web-admin-env.js"; // WEB_ADMIN_ENV — every env name an engine reads to reach web-admin (one table; a leaf module), pure/browser-safe
 export * from "./web-admin-credential.js"; // S-698 web-admin credential FILE contract: WebAdminCredentialEnvelope (user-session envelope, strict) + parseWebAdminCredentialFile (bare / envelope / unreadable — the one discrimination law) + judgeWebAdminCredentialDeclaration(env, credential) (pick-exactly-one over the credential's WEB_ADMIN_ENV pair; WEB_ADMIN_CREDENTIALS = access | assertion), pure/browser-safe
+export * from "./web-admin-session-url.js"; // webAdminSessionUrl(webBaseUrl, { worker, sessionId }) — THE web-admin session link template (<webBaseUrl>/chat?agent=<worker>&session=<sessionId>) + parseWebAdminSessionUrl(link) its paired reader, pure/browser-safe
 export * from "./retired-envs.js"; // the retired-env TOMBSTONE table (renamed / replaced / removed, closed set) + retiredEnvRefusal(env) (the one refusal sentence) + buildRetiredEnvWire() — engine boot, catalog wire, shell and web-admin read this one table, pure/browser-safe
 // NOTE: the Node-fs-backed helpers (FileConfigStore + the file editor) are NOT in this barrel — they pull
 // `node:fs`/`node:path` and would break a browser/client bundle that only wants the contract (e.g.

package/dist/local-load.d.ts

@@ -7,7 +7,7 @@ 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. */
 export declare function loadRemoteExec(root: string): Promise<RemoteExecSpec | undefined>;
-/** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (tmp → rename; never a half file). The
+/** 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

package/dist/local-load.js

@@ -7,9 +7,10 @@
  * `<root>/config.d/remote-exec.json` (service vote), loaded/validated by loadRemoteExec — distinct from
  * the per-domain `config.d/<domain>.json` the resolver reads. getEffective never reads it (not a DomainName).
  */
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { writeFileAtomic } from "./atomic-write.js";
 import { FileConfigStore } from "./file-store.js";
 import { listRequiredEnvNames } from "./file-edit.js";
 import { sanitizeZodError } from "./config-fns.js";
@@ -28,9 +29,6 @@ function parseRemoteExec(raw) {
         return r.data;
     throw sanitizeZodError(r.error);
 }
-// Monotonic suffix so two atomic writes in the SAME process+millisecond can't collide on the tmp name (which
-// would make one rename hit ENOENT / lose a write). pid+Date.now() alone isn't unique under concurrency.
-let tmpSeq = 0;
 /** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
 export function remoteExecPath(root) {
     return path.join(root, "config.d", "remote-exec.json");
@@ -62,21 +60,13 @@ export async function loadRemoteExec(root) {
     }
     return parseRemoteExec(json);
 }
-/** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (tmp → rename; never a half file). The
+/** 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 async function writeRemoteExec(root, spec) {
     const parsed = parseRemoteExec(spec);
     const dir = path.join(root, "config.d");
     await mkdir(dir, { recursive: true });
-    const tmp = path.join(dir, `.remote-exec.json.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
-    try {
-        await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", "utf8");
-        await rename(tmp, remoteExecPath(root));
-    }
-    catch (e) {
-        await unlink(tmp).catch(() => { }); // never leave a half-written tmp behind
-        throw e;
-    }
+    writeFileAtomic(remoteExecPath(root), JSON.stringify(parsed, null, 2) + "\n", "config-document");
     return parsed;
 }
 /** Resolve a `file:<path>` .env VALUE → the file's trimmed content (the file-NAME secret ref, config-research