@sema-agent/settings-schema 10.1.1 → 11.1.0

package/dist/api/scopes.js

@@ -1,9 +1,9 @@
 /**
- * `api/scopes` — the MULTI-TENANT SCOPE wire contract for the registry (/api/v1/scopes* +
- * /api/v1/auth/scope). Frozen here so sema-registry (the implementation), the orchestrator, workers and
+ * `api/scopes` — the MULTI-TENANT SCOPE wire contract for web-admin (/api/v1/scopes* +
+ * /api/v1/auth/scope). Frozen here so web-admin (the implementation), the orchestrator, workers and
  * the sema shell import ONE source of truth — same "契约先行" discipline as `api/auth`.
  *
- * THE SCOPE MODEL (normative — the registry implements EXACTLY this):
+ * THE SCOPE MODEL (normative — web-admin implements EXACTLY this):
  *
  *  - A **scope** is a tenant boundary: `{id, name, createdAt}`. `id` is a slug (SCOPE_ID_REGEX).
  *    The reserved id `"global"` (GLOBAL_SCOPE) is the DEFAULT scope: it always exists, is never
@@ -13,10 +13,10 @@
  *    and `viewer` in scope B.
  *  - The **instance-level** `users.role` is unchanged and orthogonal: an instance `admin` administers
  *    ALL scopes — inside any scope their effective role is always `"admin"` (see effectiveScopeRole).
- *  - The **access JWT** gains an OPTIONAL `scope` claim (SCOPE_CLAIM) binding the token to its active
- *    scope. A token WITHOUT the claim means `"global"` (tokenScopeOf) — full backward compatibility:
- *    every pre-scope token keeps working, scoped to global. The refresh token is NOT scope-bound;
- *    refresh re-mints per resolveTokenScope, and the client re-switches if it wants another scope.
+ *  - The **access JWT** carries a `scope` claim (SCOPE_CLAIM) binding the token to its active scope —
+ *    REQUIRED on read: a token without it is refused (readTokenScope ⇒ `scope_claim_missing`, answered 401);
+ *    it is not read as `"global"`. The refresh token is NOT scope-bound; refresh re-mints per
+ *    resolveTokenScope (always with the claim), and the client re-switches if it wants another scope.
  *
  * ENDPOINTS (paths in SCOPES_V1_PATHS / scopeMembersPath):
  *
@@ -37,13 +37,14 @@
  *
  * WIRE CASING: /api/v1/auth/scope is part of the OAuth face — snake_case on the wire (access_token,
  * expires_in), matching `api/auth`. The /api/v1/scopes management face uses this package's camelCase
- * (createdAt, scopeId) — it is a registry management API, not an OAuth endpoint.
+ * (createdAt, scopeId) — it is a web-admin management API, not an OAuth endpoint.
  *
  * Pure zod contract + pure decision functions — zero IO, browser-safe. The decision functions
- * (resolveTokenScope / canSwitchScope / effectiveScopeRole) are THE semantics: the registry
+ * (resolveTokenScope / canSwitchScope / effectiveScopeRole) are THE semantics: web-admin
  * implementation imports and calls these — it must not re-implement them.
  */
 import { z } from "zod";
+import { INTEGER } from "../integer.js";
 import { USER_ROLES } from "../config-fns.js";
 import { ACCESS_TOKEN_TTL_SECONDS } from "./auth.js";
 // ── constants ────────────────────────────────────────────────────────────────────────────────────────────
@@ -53,14 +54,15 @@ export const GLOBAL_SCOPE = "global";
 export const RESERVED_SCOPE_IDS = [GLOBAL_SCOPE];
 /** Slug shape for scope ids: lowercase alphanumeric + inner dashes, 1–64 chars, no leading/trailing dash. */
 export const SCOPE_ID_REGEX = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
-/** The scope endpoints, relative to the registry origin. `members` needs the scope id — use scopeMembersPath. */
+/** The scope endpoints, relative to web-admin origin. `members` needs the scope id — use scopeMembersPath. */
 export const SCOPES_V1_PATHS = {
     /** GET (list) + POST (create). */
     scopes: "/api/v1/scopes",
     /** POST — mint a new access token bound to another scope. */
     authScope: "/api/v1/auth/scope",
 };
-/** The JWT claim carrying the token's active scope. OPTIONAL — absent means GLOBAL_SCOPE (tokenScopeOf). */
+/** The JWT claim carrying the token's active scope. Every minted access token carries it; a token without it is refused on read
+ *  ({@link readTokenScope}). */
 export const SCOPE_CLAIM = "scope";
 /** `/api/v1/scopes/{id}/members` for PUT (upsert) and DELETE (remove). */
 export function scopeMembersPath(scopeId) {
@@ -124,7 +126,7 @@ export const ScopeSwitchResponse = z
     access_token: z.string().min(1),
     token_type: z.literal("Bearer"),
     /** Access-token lifetime in seconds (ACCESS_TOKEN_TTL_SECONDS — same mint as api/auth). */
-    expires_in: z.number().int().positive(),
+    expires_in: INTEGER.positive(),
     scope: ScopeId,
     role: ScopeRole,
 })
@@ -177,7 +179,7 @@ export function effectiveScopeRole(membershipRole, instanceRole) {
 }
 /**
  * THE token-minting scope decision — which scope (and role claim) a fresh access token binds to, given
- * the principal's scope memberships and instance role. Deterministic; the registry (Node/Next) imports
+ * the principal's scope memberships and instance role. Deterministic; web-admin (Node/Next) imports
  * and calls this at every mint (device-flow grant AND refresh). NORMATIVE RULES (verbatim, 任务书拍定):
  *
  *   1. **唯一成员 scope** — exactly one membership → bind that scope, role = that membership's effective
@@ -218,11 +220,14 @@ export function canSwitchScope(memberships, instanceRole, targetScope) {
         return true;
     return memberships.some((m) => m.scopeId === targetScope);
 }
+/** Why {@link readTokenScope} refuses — a CLOSED set (one word today). */
+export const TOKEN_SCOPE_REFUSALS = ["scope_claim_missing"];
 /**
- * Read the active scope off verified JWT claims: a non-empty string `scope` claim, else GLOBAL_SCOPE.
- * This is the ONE place the "missing claim = global" backward-compat rule lives — workers and the
- * registry both call this instead of defaulting ad hoc.
+ * Read the active scope off verified JWT claims — the ONE reader. A non-empty string `scope` claim ⇒ `{ scope }`; a claim that is
+ * missing, empty or not a string ⇒ `{ refused: "scope_claim_missing" }` (the reader answers 401). There is no default scope here:
+ * every access token web-admin mints carries the claim, an access token lives at most {@link ACCESS_TOKEN_TTL_SECONDS}, and a refresh
+ * re-mints one with the claim — a token without it is not a token this contract reads (it used to be read as `"global"`).
  */
-export function tokenScopeOf(claims) {
-    return typeof claims.scope === "string" && claims.scope.length > 0 ? claims.scope : GLOBAL_SCOPE;
+export function readTokenScope(claims) {
+    return typeof claims.scope === "string" && claims.scope.length > 0 ? { scope: claims.scope } : { refused: "scope_claim_missing" };
 }

package/dist/atomic-write.d.ts

@@ -0,0 +1,14 @@
+/** 按文档类的模式表(闭集)。 */
+export declare const ATOMIC_FILE_CLASSES: {
+    readonly "config-document": {
+        readonly newMode: 420;
+        readonly existing: "keep";
+    };
+    readonly "scheduler-store": {
+        readonly newMode: 384;
+        readonly existing: "reset";
+    };
+};
+export type AtomicFileClass = keyof typeof ATOMIC_FILE_CLASSES;
+/** 原子写 `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

@@ -0,0 +1,60 @@
+/**
+ * **本包写盘的唯一一只原子写器**(Node 专用,不进主桶):`writeDomainFile` / `writeRemoteExec`(`config.d` 下的契约文件)、调度店
+ * `saveSchedulerStore`、命令行迁移经 `bin/settings-schema.mjs` 注入的写器 —— 全部调它。写法只有一种:在目标同目录写一个唯一命名的隐藏
+ * 临时文件,再 `rename` 盖过目标(POSIX 上原子,并发读者永远看不到半截文件);失败时临时文件被清掉,不留残片。
+ *
+ * 同步实现(几 KB 的配置文件,一次写不到一毫秒):调度店的写口本来就是同步 API(`saveSchedulerStore(path, records): void`,
+ * `mutateSchedulerStore` 的提交点),异步调用方(`writeDomainFile` 等)直接调它 —— 一只写器,没有第二份同样的写法。
+ *
+ * ## 文件模式:一张按文档类的表({@link ATOMIC_FILE_CLASSES}),不在任何调用点另写
+ *  · `config-document` —— `config.d` 下的契约 JSON(域文档、`remote-exec.json`):只带 env-NAME、不带秘密值(README 契约),新建 = 0o644;
+ *    **已有的文件沿用它原来的模式**(运维 chmod 过的文件不被一次写回覆盖)。
+ *  · `scheduler-store` —— 调度店耐久记录(可能带 principal / session 标识):新建 = 0o600,且**每次写都回到 0o600**(已有的更宽的文件被收回)。
+ * 新建的模式照常经进程 umask 遮一道(`writeFile` 的 `mode` 语义):比表更严的 umask 只会更严,不会被这里放宽;沿用的模式原样恢复(不再过 umask)。
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** 按文档类的模式表(闭集)。 */
+export const ATOMIC_FILE_CLASSES = {
+    "config-document": { newMode: 0o644, existing: "keep" },
+    "scheduler-store": { newMode: 0o600, existing: "reset" },
+};
+/** 原子写 `text`(UTF-8)到 `target`;模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
+export function writeFileAtomic(target, text, kind) {
+    const spec = ATOMIC_FILE_CLASSES[kind];
+    let kept; // the existing file's mode, when this class keeps it
+    switch (spec.existing) {
+        case "keep":
+            try {
+                kept = statSync(target).mode & 0o777;
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    throw e;
+            }
+            break;
+        case "reset":
+            break;
+        default: {
+            const unhandled = spec.existing;
+            throw new Error(`writeFileAtomic: unhandled existing-file rule ${String(unhandled)}`);
+        }
+    }
+    const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        writeFileSync(tmp, text, { encoding: "utf8", mode: kept ?? spec.newMode });
+        if (kept !== undefined)
+            chmodSync(tmp, kept); // a kept mode is restored exactly (the creation mode above went through the umask)
+        renameSync(tmp, target);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* 临时文件没建成:没什么可清 */
+        }
+        throw e;
+    }
+}

package/dist/bundle.d.ts

@@ -1,13 +1,21 @@
+import { type PortableDomain } from "./file-store.js";
 import type { ConfigReader } from "./reader.js";
-import { type DomainName } from "./types.js";
-export type ConfigBundle = Partial<Record<DomainName, unknown>>;
+/** 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). */
+export type ConfigBundle = Partial<Record<PortableDomain, unknown>>;
 /** Read the (portable, by default) domains out of any ConfigReader → a bundle object. Absent domains are
  *  omitted (not defaulted) so a re-import doesn't fabricate domains the source never set. */
-export declare function exportBundle(reader: ConfigReader, domains?: readonly DomainName[]): Promise<ConfigBundle>;
+export declare function exportBundle(reader: ConfigReader, domains?: readonly PortableDomain[]): Promise<ConfigBundle>;
 /** Write a bundle to `<root>/config.d/<domain>.json` — each file atomic + VALIDATED (writeDomainFile parses
  *  against the domain zod, so a malformed source domain fails loudly rather than writing garbage). Returns the
  *  domains written. (The TOC owns `<root>`; secrets stay in `<root>/.env`, never in these files.) */
-export declare function writeBundle(root: string, bundle: ConfigBundle): Promise<DomainName[]>;
-/** Read a `<root>/config.d/*.json` bundle → raw domain configs (missing/empty file → omitted). The reverse of
- *  writeBundle: feed into sema-registry's per-domain PUT to import, or into the resolver to run locally. */
-export declare function readBundle(root: string, domains?: readonly DomainName[]): Promise<ConfigBundle>;
+export declare function writeBundle(root: string, bundle: ConfigBundle): Promise<PortableDomain[]>;
+/** Read a `<root>/config.d/*.json` bundle → raw domain configs. The reverse of writeBundle: feed into web-admin's per-domain PUT to
+ *  import, or into the resolver to run locally. Each file is read by the ONE `config.d/` file reading `FileConfigStore` uses
+ *  (`./config-d-file`): a missing file → omitted (not fabricated); a present file that is empty / whitespace, bad JSON or not a JSON
+ *  object is corrupt → throws (same sentence as `FileConfigStore`). A RETIRED domain's file in the directory (`config.d/runtime.json`,
+ *  see `RETIRED_DOMAINS`) is read for its tombstone, whichever `domains` were asked for — the same judge and sentence as
+ *  `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>;

package/dist/bundle.js

@@ -1,23 +1,28 @@
 /**
- * Round-trip between a config SOURCE (any {@link ConfigReader} — sema-registry's store OR a FileConfigStore)
+ * Round-trip between a config SOURCE (any {@link ConfigReader} — web-admin's store OR a FileConfigStore)
  * and a local `config.d/<domain>.json` BUNDLE. This is how a FLEET config seeds a TOC desktop (export → copy
- * the bundle + set .env → run locally) and how a local bundle seeds sema-registry (readBundle → PUT each domain
+ * the bundle + set .env → run locally) and how a local bundle seeds web-admin (readBundle → PUT each domain
  * via the existing domain API). The bundle = the RAW authorable domain configs; `skills` carry their full
  * bodies (SkillSpec.content is stored in full — NOT the /effective manifest), so there is no separate
  * body-bundling step and the round-trip is symmetric.
  *
  * Node-only (writeBundle/readBundle touch the filesystem) → imported via `@sema-agent/settings-schema/node`.
  */
-import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { writeDomainFile } from "./file-edit.js";
 import { PORTABLE_DOMAINS } from "./file-store.js";
-import { isDomainName } 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)) {
+        throw new Error(`"${d}" is not a portable domain — a bundle carries only ${PORTABLE_DOMAINS.join(" / ")} (the others never travel; see NON_PORTABLE_DOMAIN_REASONS)`);
+    }
+}
 /** Read the (portable, by default) domains out of any ConfigReader → a bundle object. Absent domains are
  *  omitted (not defaulted) so a re-import doesn't fabricate domains the source never set. */
 export async function exportBundle(reader, domains = PORTABLE_DOMAINS) {
     const out = {};
     for (const d of domains) {
+        assertPortable(d);
         const v = await reader.getDomain(d);
         if (v !== undefined)
             out[d] = v;
@@ -32,36 +37,32 @@ export async function writeBundle(root, bundle) {
     for (const [d, v] of Object.entries(bundle)) {
         if (v === undefined)
             continue;
+        assertPortable(d);
         await writeDomainFile(root, d, v);
         written.push(d);
     }
     return written;
 }
-/** Read a `<root>/config.d/*.json` bundle → raw domain configs (missing/empty file → omitted). The reverse of
- *  writeBundle: feed into sema-registry's per-domain PUT to import, or into the resolver to run locally. */
+/** Read a `<root>/config.d/*.json` bundle → raw domain configs. The reverse of writeBundle: feed into web-admin's per-domain PUT to
+ *  import, or into the resolver to run locally. Each file is read by the ONE `config.d/` file reading `FileConfigStore` uses
+ *  (`./config-d-file`): a missing file → omitted (not fabricated); a present file that is empty / whitespace, bad JSON or not a JSON
+ *  object is corrupt → throws (same sentence as `FileConfigStore`). A RETIRED domain's file in the directory (`config.d/runtime.json`,
+ *  see `RETIRED_DOMAINS`) is read for its tombstone, whichever `domains` were asked for — the same judge and sentence as
+ *  `FileConfigStore`: carrying facts ⇒ `RetiredDomainError` (a bundle assembled from the remaining files would silently drop those
+ *  facts); absent / `{}` ⇒ left alone. */
 export async function readBundle(root, domains = PORTABLE_DOMAINS) {
+    for (const d of domains) {
+        if (!PORTABLE_DOMAINS.includes(d)) {
+            configDPath(root, d); // a name that is not a domain at all is refused by the one name guard first (no `../` traversal)
+            assertPortable(d);
+        }
+    }
+    await refuseRetiredDomainFiles(root);
     const out = {};
     await Promise.all(domains.map(async (d) => {
-        if (!isDomainName(d))
-            throw new Error(`"${d}" is not a config domain — refusing to build a config.d path from it (no traversal)`);
-        let text;
-        try {
-            text = await readFile(path.join(root, "config.d", `${d}.json`), "utf8");
-        }
-        catch (e) {
-            if (e.code === "ENOENT")
-                return; // absent file → omit (not fabricated)
-            throw e;
-        }
-        const trimmed = text.trim();
-        if (!trimmed)
-            return;
-        try {
-            out[d] = JSON.parse(trimmed);
-        }
-        catch {
-            throw new Error(`invalid JSON in config.d/${d}.json`); // sanitized: never echo the raw file text
-        }
+        const v = await readConfigDFile(root, d);
+        if (v !== undefined)
+            out[d] = v;
     }));
     return out;
 }

package/dist/cli.d.ts

@@ -1,7 +1,9 @@
-/** 入口注入的 I/O(核心不碰 node:fs)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的 workers 文档比旧文档更糟。 */
+/** 入口注入的 I/O(核心不碰 node:fs)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟;入口注入的就是 `./atomic-write` 的那一只。 */
 export interface SettingsSchemaCliIo {
+    readDir(path: string): Promise<string[]>;
     readFile(path: string): Promise<string>;
     writeFileAtomic(path: string, text: string): Promise<void>;
+    removeFile(path: string): Promise<void>;
     stdout(text: string): void;
     stderr(text: string): void;
 }

package/dist/cli.js

@@ -1,34 +1,44 @@
 /**
- * `settings-schema` 命令行的核心(7.0.0)—— 子命令只有一个:`migrate-workers <workers.json> [--check]`,即
- * {@link migrateWorkersDomain} 的文件形(文件后端 / 离线用;中心在它的 workers 读口直接调同一只函数)。
+ * `settings-schema` 命令行的核心(11.0.0)—— 子命令只有一个:`migrate <config.d 目录> [--check]`,即一次性迁移
+ * `migrateStoredDocuments`(`./one-time-migrations`)的目录形(本地 config.d / 离线文件用;web-admin 在它起服时直接调同一只函数)。
+ * 目录被当作**一个 scope 的全集**(`coverage: "scope"`):目录里没有的域文件就是从未设过。
  *
- * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(那是本包唯一用 fs 写文件的地方),所以测试可以直接驱动它。
+ * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(写盘用的是 `./atomic-write` 那一只原子写器 —— 写法与文件模式在那里一处定),所以测试可以直接驱动它。
  * 不进主桶 —— 它是 bin 的实现,不是契约面。
  *
- * 退出码:0 = 已写回 / 无事可做;1 = 有 worker 迁不了(refused)或迁出的文档整域读不进 7.0.0,**一字不写**;2 = 用法 / 读文件 /
- * JSON 错(此时 stdout 为空);3 = `--check` 且会有改动(不写)。**8.0.0**:`--check` 与真跑过同一只判定({@link verdictOf}),
- * 只在「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的文档 `--check` 也报 refused / rc 1。
+ * 读哪些文件:目录里 `<名>.json`,名是配置域或retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁);别的文件
+ * (`remote-exec.json`、隐藏文件、不认识的名)不读不动。
  *
- * ## 报告形(7.0.1:让「没写」在机读上不可能被读成「写了」)
- * 退出码 0 / 1 / 3 时 stdout 恰两行:
- *  · 第 1 行 = **唯一结论行** `outcome=<refused|applied|noop|pending> written=<true|false>`;
- *  · 第 2 行 = JSON 报告(`event: "workers_domain_migrated"`,只点名字段、不带值),同带 `outcome` / `written`。
- * `written` 不是独立字段:由 `outcome` 派生({@link writtenOf};只有 `applied` 写盘)。**键名带时态**:`written=true` 才有 `changed` /
- * `dropped`;`written=false`(refused / noop / pending)时是 `wouldChange` / `wouldDrop` —— 读旧字段 `changed` 的脚本在没写的时候
- * 读不到值,而不是读到一份「已迁」名单。结论行在**写盘成功之后**才出(写盘抛错 ⇒ 没有 `outcome=applied`)。
+ * 零域文档分两形:**有条目却没有域文档**(任何非 `.` 开头的条目 —— 子目录、说明文件、不认识的名)⇒ 退出 2;**目录真空**(零条目,或只有以 `.` 开头的条目)⇒ 照常走判定,
+ * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
+ *
+ * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 {@link verdictOf}),**一字不写**;
+ * 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 域文件 ——
+ * 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
  */
-import { formatConfigPath, sanitizeZodError } from "./config-fns.js";
-import { MIGRATE_WORKERS_COMMAND } from "./execution-lane-index.js";
-import { issueText } from "./issue-text.js";
-import { migrateWorkersDomain } from "./migrate-workers.js";
-import { DOMAIN_SCHEMAS } from "./types.js";
+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";
 const USAGE = [
-    `usage: ${MIGRATE_WORKERS_COMMAND} <workers.json> [--check]`,
-    "  One-time 7.0.0 migration of a workers domain document ({ \"workers\": [...] }): env.REMOTE_EXEC + lane keys →",
-    "  runtime.execution, sessionBackend / coords.tidb* / runtime.db / tidbPasswordEnv → runtime.store. Writes the file in",
-    "  place only when every worker migrates; --check only reports (exit 3 if the file would change).",
+    `usage: ${MIGRATE_COMMAND} <config.d directory> [--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). 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",
-    "  (changed / dropped only when written=true; otherwise wouldChange / wouldDrop).",
+    "  (applied only when written=true; otherwise wouldApply).",
 ].join("\n");
 /** 这个结论写没写盘 —— 只有 `applied` 写。`written` 从这里派生,不是报告里一个可以和 `outcome` 各说各话的独立字段。 */
 function writtenOf(outcome) {
@@ -45,99 +55,158 @@ 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 };
+}
 /**
- * 迁移结果 → 结论。顺序:逐只 refused → 无改动 ⇒ noop → **整域终判**(迁出来的文档读不读得进 7.0.0:名字 / 路由唯一 …)→ 有改动。
- * 7.0.1 把整域终判放在 `--check` 之后:同一份文档 `--check` 报 pending(rc 3)、真跑报 refused(rc 1),按 `--check` 做闸的脚本会放行
- * 一次必被拒的真跑;而整域终判拒时 `refused[]` 为空、拒因只在 stderr。现在两种跑法过同一只判定,`refused[]` 逐条带出被拒项。
+ * 迁移结果 → 结论。顺序:迁移步拒 → 无改动 ⇒ noop → **整域终判**(要写回的每个域文档 —— 改过的、新建的 —— 过读侧那一只
+ * `parseDomain`:名字 / 路由唯一这类跨行规则只有整域判得出)→ 有改动。整域终判在 `--check` 之前:否则同一个目录 `--check` 报 pending、
+ * 真跑写出一份读侧必拒的文档。没改的文件不归这里判(迁移不碰它,它读不读得进是读者的事)。
  */
-function verdictOf(m) {
-    if (m.refused.length > 0) {
-        return {
-            kind: "refused",
-            refused: m.refused.map((r) => ({ name: r.name, field: r.field, reason: r.reason })),
-            why: `${m.refused.length} worker(s) cannot be migrated (see "refused") — fix them by hand and re-run`,
-        };
+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 (m.changed.length === 0)
+    if (receipts.length === 0)
         return { kind: "noop" };
-    const whole = DOMAIN_SCHEMAS.workers.safeParse(m.doc);
-    if (whole.success)
-        return { kind: "changes" };
-    const issues = sanitizeZodError(whole.error).issues;
-    const workers = isRecord(m.doc) && Array.isArray(m.doc.workers) ? m.doc.workers : [];
-    return {
-        kind: "refused",
-        refused: issues.map((i) => {
-            const [head, index, ...rest] = i.path;
-            if (head !== "workers" || typeof index !== "number")
-                return { name: null, field: i.path, reason: issueText(i) };
-            const entry = workers[index];
-            return { name: isRecord(entry) && typeof entry.name === "string" ? entry.name : null, field: rest, reason: issueText(i) };
-        }),
-        why: `the migrated document does not read as a 7.0.0 workers domain — ${issues.map((i) => `${formatConfigPath(i.path)}: ${issueText(i)}`).join("; ")}`,
-    };
+    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" };
 }
-const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-/** 一次发出报告:结论行 + JSON 行(一次 `stdout` 调用)。键名带时态:写了 ⇒ `changed` / `dropped`,没写 ⇒ `wouldChange` / `wouldDrop`。 */
-function reportOf(outcome, file, m, refused) {
+/** 一次发出报告:结论行 + JSON 行(一次 `stdout` 调用)。 */
+function reportOf(outcome, dir, applied, refused) {
     const written = writtenOf(outcome);
-    const dropped = m.dropped.map((d) => ({ name: d.name, field: formatConfigPath(d.field) }));
     const json = JSON.stringify({
-        event: "workers_domain_migrated",
+        event: "stored_documents_migrated",
         outcome,
         written,
-        file,
-        ...(written ? { changed: m.changed, dropped } : { wouldChange: m.changed, wouldDrop: dropped }),
-        refused: refused.map((r) => ({ name: r.name, field: formatConfigPath(r.field), reason: r.reason })),
+        dir,
+        [written ? "applied" : "wouldApply"]: applied.map(reportReceipt),
+        refused,
     });
     return `outcome=${outcome} written=${written}\n${json}\n`;
 }
+const join = (dir, name) => `${dir.replace(/[\\/]+$/, "")}/${name}`;
+/** 「有条目却没有域文档」的拒句:点名这个目录、说要的是 `config.d` 目录本身;`<dir>/config.d` 在场(探一次)就直接点它 —— 最常见的错是填了它的上一层。 */
+async function noDomainDocumentsSentence(dir, io) {
+    const nested = join(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: ${MIGRATE_COMMAND} ${nested}` : base;
+}
 export async function runSettingsSchemaCli(argv, io) {
     const [command, ...rest] = argv;
     const check = rest.includes("--check");
-    const files = rest.filter((a) => a !== "--check");
-    const file = files[0];
-    if (command !== "migrate-workers" || files.length !== 1 || file === undefined || file.startsWith("-")) {
+    const dirs = rest.filter((a) => a !== "--check");
+    const dir = dirs[0];
+    if (command !== "migrate" || dirs.length !== 1 || dir === undefined || dir.startsWith("-")) {
         io.stderr(`${USAGE}\n`);
         return 2;
     }
-    let text;
+    let names;
     try {
-        text = await io.readFile(file);
+        names = await io.readDir(dir);
     }
     catch (err) {
-        io.stderr(`settings-schema: cannot read ${file}: ${err instanceof Error ? err.message : String(err)}\n`);
+        io.stderr(`settings-schema: cannot read directory ${dir}: ${err instanceof Error ? err.message : String(err)}\n`);
         return 2;
     }
-    let doc;
-    try {
-        doc = JSON.parse(text);
+    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`);
+            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;
+        }
     }
-    catch {
-        io.stderr(`settings-schema: ${file} is not valid JSON\n`);
+    if (Object.keys(docs).length === 0 && names.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;
     }
-    const m = migrateWorkersDomain(doc);
-    const verdict = verdictOf(m);
+    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 "refused":
-            io.stdout(reportOf("refused", file, m, verdict.refused));
+            io.stdout(reportOf("refused", dir, applied, verdict.refused));
             io.stderr(`settings-schema: ${verdict.why}; nothing was written\n`);
             return 1;
         case "noop":
-            io.stdout(reportOf("noop", file, m, []));
+            io.stdout(reportOf("noop", dir, [], []));
             return 0;
         case "changes":
-            if (check) {
-                io.stdout(reportOf("pending", file, m, []));
-                return 3;
-            }
-            await io.writeFileAtomic(file, `${JSON.stringify(m.doc, null, 2)}\n`);
-            io.stdout(reportOf("applied", file, m, [])); // 写盘成功之后才报 applied
-            return 0;
+            break;
         default: {
             const unhandled = verdict;
             throw new Error(`settings-schema: unhandled verdict ${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-d-file.d.ts

@@ -0,0 +1,14 @@
+import { type DomainName, type RetiredDomainName } from "./types.js";
+/** `<root>/config.d/<名>.json` 的路径 —— 名字的判也在这里(**一处**):不是配置域也不是 retired 域 ⇒ 拒(不拿用户给的名拼路径,防 `../` 穿越)。 */
+export declare function configDPath(root: string, name: string): string;
+/** 一个 `config.d/<名>.json` 在场时的**文本** → 它的值(纯判,零 I/O;见文件头的律):一个 JSON 对象 ⇒ 它;空 / 纯空白、坏 JSON、
+ *  不是对象 ⇒ 抛。读盘的入口(`readConfigDFile`)与自己读文本的命令行(`migrate`)都过它,四种坏形一句话。 */
+export declare function judgeConfigDText(name: DomainName | RetiredDomainName, text: string): Record<string, unknown>;
+/** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
+export declare function readConfigDFile(root: string, name: DomainName | RetiredDomainName): Promise<Record<string, unknown> | undefined>;
+/**
+ * `config.d/` 里每个 **retired 域**的文件过一次墓碑(`refuseRetiredDomain`,与 `buildEffective` / `parseDomain` 同一只判官、同一句):带事实 ⇒
+ * `RetiredDomainError`;缺席 / `{}` ⇒ 交回读到的原文(调用方要它进版本 hash)。读 `config.d/` 的**每个入口**都先过它 —— `FileConfigStore`
+ * 的 `getDomain` / `getEffective`(于是走 `getDomain` 的 `exportBundle` 同答)与 `readBundle`;不论调用方要的是哪几个域。
+ */
+export declare function refuseRetiredDomainFiles(root: string): Promise<Partial<Record<RetiredDomainName, unknown>>>;