@sema-agent/settings-schema 14.4.0 → 14.6.0

package/dist/config-d-file.js

@@ -12,6 +12,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { refuseRetiredDomain, sanitizeZodError } from "./config-fns.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
 /** 一份 `config.d` 文档写盘的**文本形** —— 两格缩进的 JSON 加一个换行。写域文件(`writeDomainFile`)、写 `remote-exec.json`(`writeRemoteExec`)与目录迁移写回
@@ -57,11 +58,17 @@ export function judgeConfigDText(name, text, file) {
     catch {
         throw new Error(`invalid JSON in ${file} — ${documentWayOut(name)}`); // 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(`${file} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`);
+    return judgeConfigDValue(name, parsed, file);
+}
+/** 一份**已解析的**存量文档在场时的值(同步口 `migrateConfigDocuments` 收的是各层的文档原文,不是文件文本)→ 它自己:一个 JSON 对象 ⇒ 它;`null` / 数组 / 数 / 串 / 布尔 /
+ *  非朴素对象 ⇒ 抛。{@link judgeConfigDText} 的最后一道判就是这只(文本解析出来之后过它),所以「不是对象」一种坏形一句话,不论文档是从文件文本来的还是调用方直接给的;
+ *  `label` = 句首的称呼(文本路径给文件的真实路径,值路径给 `the <名> document`)。 */
+export function judgeConfigDValue(name, value, label) {
+    if (!isPlainJsonObject(value)) {
+        const kind = value === null ? "null" : Array.isArray(value) ? "array" : typeof value === "object" ? "non-plain object" : typeof value;
+        throw new Error(`${label} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`);
     }
-    return parsed;
+    return value;
 }
 /** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
 export async function readConfigDFile(root, name) {

package/dist/config-dir-io.js

@@ -5,10 +5,20 @@
  * 命令行入口与引擎起服的目录迁移注入同一份,写法与文件模式因此只在原子写器那一处定。
  */
 import { readdir, readFile, unlink } from "node:fs/promises";
-import { resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
+import { dirname } from "node:path";
+import { directoryAdmitsWrite, resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
+import { FsFailure } from "./fs-failure.js";
 export const nodeConfigDirectoryIo = {
     readDir: async (path) => readdir(resolveSymlinkTarget(path)),
     readFile: async (path) => readFile(resolveSymlinkTarget(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),
+    // a failed removal is minted here, where the directory's mode can be read (`./fs-failure` is pure): the same `FsFailure` the atomic writer throws, so the command line prints it as is
+    removeFile: async (file) => {
+        try {
+            await unlink(file);
+        }
+        catch (e) {
+            throw new FsFailure({ landing: "remove", path: file, directoryWritable: directoryAdmitsWrite(dirname(file)) }, e);
+        }
+    },
 };

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

@@ -49,6 +49,45 @@ export interface MigrateConfigDirectoryOptions {
     /** 只判、不写:有改动且整域判得过 ⇒ `pending`。默认 `false`。 */
     readonly check?: boolean;
 }
+export interface MigrateConfigDocumentsOptions {
+    /** 覆盖面:调用方读的文档名集 —— 与 {@link MigrateConfigDirectoryOptions.documents} 同一个词、同一个律(覆盖面内没给的文档 = 从未设过;覆盖面外的键不读、不判、不进结果;拼错的名字 ⇒ 抛 `TypeError`)。 */
+    readonly documents: readonly ConfigDirectoryDocument[];
+}
+/**
+ * 同步口的结果 —— {@link ConfigDirectoryMigration} 的无 io 形,**同一个闭集的词**,调用方穷举:
+ *  · `unreadable`  —— 覆盖面内某份文档不是 JSON 对象(`null` / 数组 / 数 / 串 / 布尔):`document` 点名是哪一份,`reason` 与坏文件同一句式。不抛、不迁(其余文档是别的调用的事:一层一次调用)。
+ *  · `no-documents`—— 覆盖面内一份文档都没给(缺席与 `undefined` 同)。
+ *  · `refused`     —— 迁移步拒(收据 `refused`)**或**改过的文档整域读不进(整域终判)。`docs` 仍交回迁移后的那一份(迁得动的坐标改新形、迁不动的原样 ——
+ *                     写手要的是这一份;落不落盘、引擎认不认是 `kind` 的事:`refused` ⇒ 引擎同样不写回、整域落缺省;反向不成立 —— 引擎对整个目录一判,别的文档被拒也会让整目录不写)。
+ *  · `noop`        —— 零改动:`docs` 里每份文档都是入参里的**同一引用**;没改的文档不终判(读不读得进是读者的事,与目录形同一律)。
+ *  · `migrated`    —— 有改动、整域判得过:`docs` 是迁移后的覆盖面内文档全集,`changed` = 改过 / 新建的文档名,`removed` = 被移除的(retired 域),`applied` = 逐条收据。
+ * `read` = 覆盖面内在场的文档名(升序)。入参从不被改;重跑 `docs` ⇒ `noop`。
+ */
+export type ConfigDocumentsMigration = {
+    readonly kind: "unreadable";
+    readonly document: ConfigDirectoryDocument;
+    readonly reason: string;
+} | {
+    readonly kind: "no-documents";
+} | {
+    readonly kind: "refused";
+    readonly read: readonly string[];
+    readonly docs: Readonly<Record<string, unknown>>;
+    readonly applied: readonly MigrationReceipt[];
+    readonly refused: readonly ConfigDirectoryRefusal[];
+    readonly why: string;
+} | {
+    readonly kind: "noop";
+    readonly read: readonly string[];
+    readonly docs: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "migrated";
+    readonly read: readonly string[];
+    readonly docs: Readonly<Record<string, unknown>>;
+    readonly applied: readonly MigrationReceipt[];
+    readonly changed: readonly string[];
+    readonly removed: readonly string[];
+};
 /** 目录迁移能读写的文档名:配置域、retired 域、`remote-exec`(`config.d/remote-exec.json`)—— 就是 `config.d` 里能放的文档名。 */
 export type ConfigDirectoryDocument = ConfigDDocumentName;
 /** 目录加文件名(目录尾部的分隔符折掉)。包内私有(不进 `./node`)。 */
@@ -59,6 +98,11 @@ type RefusedReceipt = Extract<MigrationReceipt, {
 /** 一张收据的出门形(坐标只点名、不带值):`refused` 带 `reason`(= {@link ConfigDirectoryRefusal} 的形),`moved` 带 `to`。包内私有 —— 命令行报告用它渲染 `applied`。 */
 export declare function reportReceipt(r: RefusedReceipt): ConfigDirectoryRefusal;
 export declare function reportReceipt(r: MigrationReceipt): Record<string, unknown>;
+/**
+ * 对一组**已有的**存量文档(`docs`:文档名 → 文档,例:一层 `settings` 里的 `models` 域原文)跑一次一次性迁移 + 整域终判 —— 同步、无 io;语义与结果见文件头「同步口」与 {@link ConfigDocumentsMigration}。
+ * 覆盖面外的键不读、不判、不进结果;覆盖面内在场(非 `undefined`)的文档必须是 JSON 对象,否则回 `unreadable`(不抛)。`docs` 不是对象 / 覆盖面拼错 ⇒ `TypeError`(调用方的错,不是数据的错)。
+ */
+export declare function migrateConfigDocuments(docs: Readonly<Partial<Record<ConfigDirectoryDocument, unknown>>>, opts: MigrateConfigDocumentsOptions): ConfigDocumentsMigration;
 /**
  * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
  */

package/dist/config-dir-migration.js

@@ -20,11 +20,18 @@
  *  · `pending`     —— `check: true` 且有改动、整域判得过:一字不写。
  *  · `applied`     —— 已写回:先写改过 / 新建的文档,最后删被移除的 retired 域文件 —— 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
  * 写盘阶段的 I/O 错误**原样抛出**(不吞、不改写):已写完的文档留在新位上,再跑一次幂等收尾。
+ *
+ * ## 同步口 {@link migrateConfigDocuments}(14.5.0)
+ * 「迁 → 整域终判」那一段就是一只同步函数:入参是调用方手里**已有**的存量文档原文(域名 → 文档),出参是同一个闭集的无 io 形 —— 迁移后的文档、逐条收据、
+ * 整域终判的拒。目录形读完目录后调的就是它的内核(语义只此一处);不经目录的调用方(例:命令行壳按层读 `settings` 文档)调它,不再自己把
+ * `migrateStoredDocuments`(纯改写)与 `parseDomain`(整域终判)按「迁移步拒 → 无改动 ⇒ noop → 改过的文档整域终判」的序再组装一遍。
+ * 覆盖面、`coverage` 的判、「没改的文档不判」「迁移不许越过覆盖面去写」与目录形逐字同;层的合并(层序 / 覆盖 / 托管锁)不在这里 —— 一层一次调用。
  */
 import { z } from "zod";
 import { formatConfigPath, parseDomain } from "./config-fns.js";
-import { configDDocumentText, judgeConfigDText, parseRemoteExecDocument } from "./config-d-file.js";
+import { configDDocumentText, judgeConfigDText, judgeConfigDValue, parseRemoteExecDocument } from "./config-d-file.js";
 import { fsFailureMessage } from "./fs-failure.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { migrateStoredDocuments } from "./one-time-migrations.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
@@ -94,16 +101,78 @@ function verdictOf(input, migrated, receipts) {
     return { kind: "changes" };
 }
 const messageOf = (err) => (err instanceof Error ? err.message : String(err));
-/**
- * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
- */
-export async function migrateConfigDirectory(dir, opts) {
+/** 覆盖面的名字集(校验在这一处):拼错的名字 ⇒ `TypeError`,不让它悄悄变成「什么都没覆盖」。 */
+function coveredDocuments(caller, documents) {
     const covered = new Set();
-    for (const name of opts.documents) {
+    for (const name of documents) {
         if (!isConfigDirectoryDocument(name))
-            throw new TypeError(`migrateConfigDirectory: "${String(name)}" is not a config domain, a retired domain or remote-exec — the coverage names the documents the caller reads`);
+            throw new TypeError(`${caller}: "${String(name)}" is not a config domain, a retired domain or remote-exec — the coverage names the documents the caller reads`);
         covered.add(name);
     }
+    return covered;
+}
+/**
+ * 「迁 → 整域终判」的内核(语义只此一处):`docs` = 覆盖面内**在场且已判过形**的文档(都是 JSON 对象),`covered` = 覆盖面。目录形读完目录后调它,同步口 {@link migrateConfigDocuments} 判完形后调它。
+ */
+function migrateCovered(caller, docs, covered) {
+    const read = Object.keys(docs);
+    if (read.length === 0)
+        return { kind: "no-documents" };
+    // 目录/文档集是不是「一个 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(`${caller}: 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, docs: m.docs, applied, refused: verdict.refused, why: verdict.why };
+        case "noop":
+            return { kind: "noop", read, docs: m.docs };
+        case "changes":
+            break;
+        default: {
+            const unhandled = verdict;
+            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+        }
+    }
+    const changed = Object.entries(m.docs)
+        .filter(([name, doc]) => !(Object.prototype.hasOwnProperty.call(docs, name) && docs[name] === doc))
+        .map(([name]) => name);
+    const removed = Object.keys(docs).filter((name) => !Object.prototype.hasOwnProperty.call(m.docs, name));
+    return { kind: "migrated", read, docs: m.docs, applied, changed, removed };
+}
+/**
+ * 对一组**已有的**存量文档(`docs`:文档名 → 文档,例:一层 `settings` 里的 `models` 域原文)跑一次一次性迁移 + 整域终判 —— 同步、无 io;语义与结果见文件头「同步口」与 {@link ConfigDocumentsMigration}。
+ * 覆盖面外的键不读、不判、不进结果;覆盖面内在场(非 `undefined`)的文档必须是 JSON 对象,否则回 `unreadable`(不抛)。`docs` 不是对象 / 覆盖面拼错 ⇒ `TypeError`(调用方的错,不是数据的错)。
+ */
+export function migrateConfigDocuments(docs, opts) {
+    if (!isPlainJsonObject(docs))
+        throw new TypeError("migrateConfigDocuments: `docs` must be a { document: value } object");
+    const covered = coveredDocuments("migrateConfigDocuments", opts.documents);
+    const present = {};
+    for (const name of [...covered].sort()) {
+        const value = Object.prototype.hasOwnProperty.call(docs, name) ? docs[name] : undefined;
+        if (value === undefined)
+            continue;
+        try {
+            present[name] = judgeConfigDValue(name, value, `the ${name} document`); // the one config.d "is it an object" judge (the file-text path ends in the same one)
+        }
+        catch (err) {
+            return { kind: "unreadable", document: name, reason: messageOf(err) };
+        }
+    }
+    return migrateCovered("migrateConfigDocuments", present, covered);
+}
+/**
+ * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
+ */
+export async function migrateConfigDirectory(dir, opts) {
+    const covered = coveredDocuments("migrateConfigDirectory", opts.documents);
     const { io } = opts;
     let names;
     try {
@@ -117,7 +186,7 @@ export async function migrateConfigDirectory(dir, opts) {
         if (name.startsWith(".") || !name.endsWith(".json"))
             continue;
         const base = name.slice(0, -".json".length);
-        if (!covered.has(base) || !isConfigDirectoryDocument(base))
+        if (!isConfigDirectoryDocument(base) || !covered.has(base))
             continue;
         let text;
         const file = joinDirPath(dir, name);
@@ -134,46 +203,32 @@ export async function migrateConfigDirectory(dir, opts) {
             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) {
+    const m = migrateCovered("migrateConfigDirectory", docs, covered);
+    switch (m.kind) {
+        case "no-documents":
+            return { kind: "no-documents", entries: names };
         case "refused":
-            return { kind: "refused", read, applied, refused: verdict.refused, why: verdict.why };
+            return { kind: "refused", read: m.read, applied: m.applied, refused: m.refused, why: m.why };
         case "noop":
-            return { kind: "noop", read };
-        case "changes":
+            return { kind: "noop", read: m.read };
+        case "migrated":
             break;
         default: {
-            const unhandled = verdict;
-            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+            const unhandled = m;
+            throw new Error(`settings-schema: unhandled migration ${JSON.stringify(unhandled)}`);
         }
     }
     if (opts.check === true)
-        return { kind: "pending", read, applied };
+        return { kind: "pending", read: m.read, applied: m.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`), configDDocumentText(doc)); // the one config.d document text (writeDomainFile / writeRemoteExec write the same)
+    for (const name of m.changed) {
+        await io.writeFileAtomic(joinDirPath(dir, `${name}.json`), configDDocumentText(m.docs[name])); // the one config.d document text (writeDomainFile / writeRemoteExec write the same)
         written.push(`${name}.json`);
     }
-    for (const name of Object.keys(docs)) {
-        if (Object.prototype.hasOwnProperty.call(m.docs, name))
-            continue;
+    for (const name of m.removed) {
         await io.removeFile(joinDirPath(dir, `${name}.json`));
         removed.push(`${name}.json`);
     }
-    return { kind: "applied", read, applied, written, removed };
+    return { kind: "applied", read: m.read, applied: m.applied, written, removed };
 }

package/dist/config-fns.js

@@ -17,6 +17,7 @@
 // its entry collections. zod is this package's one runtime dependency, so this costs nothing new.
 import { z } from "zod";
 import { MODEL_ENTRY_REFUSAL_CODES, ModelRefusalsWire } from "./fleet.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { carriesUserinfo, secretScanForms } from "./secret-scan.js"; // package-private normalization (both scanners read it) + the userinfo judgement (not in the barrel)
 import { sha256Hex } from "./sha256.js";
 import { unwrapSchema } from "./zod-unwrap.js"; // package-private: the ONE reading of zod's wrapper layers (salvage + the one-time migrations share it)
@@ -347,7 +348,7 @@ function readEntryIdentity(entry) {
             return undefined;
         const own = (k) => {
             const d = Object.getOwnPropertyDescriptor(entry, k);
-            return d !== undefined && "value" in d ? d.value : undefined;
+            return d !== undefined && Object.hasOwn(d, "value") ? d.value : undefined; // 描述符本身也只读自有键
         };
         const name = own("name");
         const id = own("id");
@@ -731,13 +732,6 @@ export function isReservedExtensionKey(domain, parent, key) {
     const rules = EXTENSION_NAMESPACES[domain];
     return rules !== undefined && rules.some((r) => r.at.length === parent.length && r.at.every((seg, i) => (seg === ANY_INDEX ? typeof parent[i] === "number" : seg === parent[i])) && r.key.test(key));
 }
-/** 纯 JSON 对象(不是数组、不是类实例/带原型的东西)——只对这种做键集对比,别的形状交给 parse 判。 */
-function isPlainJsonObject(v) {
-    if (v === null || typeof v !== "object" || Array.isArray(v))
-        return false;
-    const proto = Object.getPrototypeOf(v);
-    return proto === Object.prototype || proto === null;
-}
 function collectDropped(domain, raw, parsed, prefix, depth, acc) {
     if (depth > DROP_SCAN_MAX_DEPTH)
         return;
@@ -1104,7 +1098,7 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
  *  and so does any key no domain names(the 0.6-era `teams` key included — not a domain since 0.7, and no engine reads it). Throws ONLY on garbage no caller can partially trust: a non-object payload, or a missing/
  *  non-finite `version` — that is not "a bad domain", it is not an effective config at all. */
 export function readEffectiveWire(raw, onWarning) {
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    if (!isPlainJsonObject(raw))
         throw new Error("effective wire payload is not a JSON object");
     const r = raw;
     if (typeof r.version !== "number" || !Number.isFinite(r.version))

package/dist/conformance/canonical.js

@@ -10,10 +10,7 @@
  * `stableKey` 是唯一一处把值转成串的地方,它只用来给**多重集计数**当哈希键 —— 用的是 JSON 编码,
  * 数组边界与段类型(`"1"` vs `1`)在编码里都还在,所以它不是那种有损的点号串。
  */
-/** 纯 JSON 对象(不是数组、不是类实例)。 */
-function isPlainObject(v) {
-    return v !== null && typeof v === "object" && !Array.isArray(v);
-}
+import { isPlainJsonObject } from "../plain-json-object.js";
 /**
  * 「这个对象**在场**的键」—— 本文件里唯一一处判键在不在 / 取键的值的地方。
  *
@@ -42,7 +39,7 @@ function presentKeys(o) {
 export function canonicalize(value) {
     if (Array.isArray(value))
         return value.map(canonicalize);
-    if (isPlainObject(value)) {
+    if (isPlainJsonObject(value)) {
         // `Object.fromEntries`,**不是**逐键 `out[k] = …`:后者对 `"__proto__"` 走的是原型 setter(改掉对象的
         // 原型,既不产生自有键、还污染返回值),于是规范化会把一个叫 `__proto__` 的顶层键**吃掉** —— 两边
         // 同样被吃掉 = 比对器对它全盲 = 一格假绿。与 S-332 在 wire 透传处修的是同一条「键就是键」的律。
@@ -60,7 +57,7 @@ export function deepEqual(a, b) {
         return true;
     if (Array.isArray(a) && Array.isArray(b))
         return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
-    if (isPlainObject(a) && isPlainObject(b)) {
+    if (isPlainJsonObject(a) && isPlainJsonObject(b)) {
         const ka = presentKeys(a);
         const kb = presentKeys(b);
         return ka.length === kb.length && ka.every((k, i) => k === kb[i]) && ka.every((k) => deepEqual(ownValue(a, k), ownValue(b, k)));
@@ -93,7 +90,7 @@ export function diffJson(expected, actual, at = []) {
         }
         return out;
     }
-    if (isPlainObject(expected) && isPlainObject(actual)) {
+    if (isPlainJsonObject(expected) && isPlainJsonObject(actual)) {
         const out = [];
         const keys = [...new Set([...presentKeys(expected), ...presentKeys(actual)])].sort();
         for (const k of keys) {

package/dist/conformance/corpus.js

@@ -20,14 +20,14 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { LEG_NAMES, REJECT_STAGES } from "./types.js";
 import { LEG_EXPECTATION } from "./derive.js";
+import { isPlainJsonObject } from "../plain-json-object.js";
 /** 本包的根目录 —— `src/conformance/*.ts` 与 `dist/conformance/*.js` 距根同深,两处求值同一个地方。 */
 export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 /** 语料目录(默认 = 本包的 `conformance/`)。 */
 export const DEFAULT_CORPUS_DIR = join(PACKAGE_ROOT, "conformance");
 const readJson = async (p) => JSON.parse(await readFile(p, "utf8"));
-const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 function requireRecord(v, where) {
-    if (!isRecord(v))
+    if (!isPlainJsonObject(v))
         throw new Error(`conformance corpus: ${where} must be a JSON object`);
     return v;
 }
@@ -56,7 +56,7 @@ function checkLegExpectation(v, where) {
         if (!REJECT_STAGES.includes(r.stage))
             throw new Error(`conformance corpus: ${where}.stage must be one of ${REJECT_STAGES.join("|")}`);
         if (r.refIssues !== undefined) {
-            const ok = Array.isArray(r.refIssues) && r.refIssues.every((x) => isRecord(x) && Array.isArray(x.path) && x.path.every((seg) => typeof seg === "string" || typeof seg === "number"));
+            const ok = Array.isArray(r.refIssues) && r.refIssues.every((x) => isPlainJsonObject(x) && Array.isArray(x.path) && x.path.every((seg) => typeof seg === "string" || typeof seg === "number"));
             if (!ok)
                 throw new Error(`conformance corpus: ${where}.refIssues must be an array of { path: (string|number)[] }`);
         }

package/dist/conformance/derive.js

@@ -34,7 +34,9 @@
  * 严写的结局不是读结局的一种表示变换,而是另一个判断(读腿抢救的地方严写拒)。把它写成「从 domains 期望派生」
  * 就等于让 domains 金样的一处错同时改写两条腿的期望 —— 两条腿同错、门照绿。它的金样逐条显式入库、各自冻结。
  */
-import { NON_DOMAIN_CONFIG_FILES, PORTABLE_DOMAINS } from "../file-store.js";
+import { NON_DOMAIN_CONFIG_FILES } from "../file-store.js";
+import { PORTABLE_DOMAINS } from "../portable-domains.js";
+import { isPlainJsonObject } from "../plain-json-object.js";
 import { skillContentHash } from "../skills-manifest.js";
 import { DOMAINS, isDomainName } from "../types.js";
 /** 变换表(本文件头注的机器形;`docs/CONFORMANCE.md` 与 `test/conformance-coverage.test.ts` 都读它)。 */
@@ -65,18 +67,17 @@ export const LEG_EXPECTATION = {
 };
 /** 非便携域 —— 由 {@link PORTABLE_DOMAINS} 派生,零手抄。 */
 export const NON_PORTABLE_DOMAINS = DOMAINS.filter((d) => !PORTABLE_DOMAINS.includes(d));
-const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 /** 一份 `domains` 文档集里,**不是域名**的那些顶层键(T4 的触发面)。 */
 export const foreignKeysOf = (docs) => Object.keys(docs).filter((k) => !isDomainName(k));
 /** T2 的**入参**半场:域形的 skills 文档 → wire 形的 manifest 文档。结构变换,不解析 —— 坏形原样传下去,
  *  让 wire 腿自己的判据去裁(否则语料就没法喂一份坏 manifest 了)。 */
 export function toManifestDoc(doc) {
-    if (!isPlainObject(doc) || !Array.isArray(doc.skills))
+    if (!isPlainJsonObject(doc) || !Array.isArray(doc.skills))
         return doc;
     return {
         ...doc,
         skills: doc.skills.map((entry) => {
-            if (!isPlainObject(entry) || typeof entry.content !== "string")
+            if (!isPlainJsonObject(entry) || typeof entry.content !== "string")
                 return entry;
             const { content, ...rest } = entry;
             return { ...rest, contentHash: skillContentHash(content) };
@@ -131,7 +132,7 @@ export const EPOCH_ISO = new Date(0).toISOString();
  *  `conformance/baseline.json`),非便携域取它的那一格 —— 不现算,免得 schema 默认一改 golden 就跟着动。 */
 export function deriveLocalExpectation(source, docs, baseline, localVersion) {
     // T5:文件层先判 —— 任何一个**便携**域的文档不是 JSON 对象 ⇒ 整条腿在解析层被拒。
-    const badFile = PORTABLE_DOMAINS.find((d) => Object.prototype.hasOwnProperty.call(docs, d) && !isPlainObject(docs[d]));
+    const badFile = PORTABLE_DOMAINS.find((d) => Object.prototype.hasOwnProperty.call(docs, d) && !isPlainJsonObject(docs[d]));
     if (badFile !== undefined)
         return { outcome: "rejected", stage: "parse" };
     const effective = clone(source.effective);

package/dist/conformance/run.js

@@ -14,6 +14,7 @@
 import { mkdtemp, mkdir, readFile, realpath, rm, stat, writeFile, utimes } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, extname, isAbsolute, join, resolve, sep } from "node:path";
+import { isPlainJsonObject } from "../plain-json-object.js";
 import { canonicalize, deepEqual, diffJson, stableKey } from "./canonical.js";
 import { diffWarningMultiset, findSecretLeaks, projectWarning } from "./warnings.js";
 import { deriveLocalExpectation, deriveLocalInput, deriveWireExpectation, deriveWireInput, toManifestDoc } from "./derive.js";
@@ -133,7 +134,7 @@ function sameRefIssueBag(expected, actual) {
 /** effective 里的元数据两键(独立断言,不进结构比对)。 */
 const METADATA_KEYS = ["version", "updatedAt"];
 function splitMetadata(effective) {
-    if (effective === null || typeof effective !== "object" || Array.isArray(effective))
+    if (!isPlainJsonObject(effective))
         return { body: effective };
     const src = effective;
     // fromEntries(不是逐键赋值):`__proto__` 作自有键时逐键赋值会走原型 setter,把它从比对面上抹掉。

package/dist/definition-copy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):**定义语义的复制**。读不可信的串数组、写读出来的副本,都不许走 `[[Set]]` 与继承的成员 ——
+ * `Object.prototype` / `Array.prototype` 上被污染的数字键(getter / setter)、`get` / `set` 键、数组实例上被替换的 `Symbol.iterator`,
+ * 在下标赋值、`push`、展开、描述符对象字面量上各有一条路能把条目吞掉、替换或抛出去。本模块是这件事的唯一读法,读者只调它:
+ *  · {@link captureStringArray}:一份串数组的捕获副本(按下标、`hasOwn`、一次读、非串即坏、`defineProperty` 写入);
+ *  · {@link dataDescriptor}:写副本用的描述符,零原型(`{ value, writable, enumerable, configurable }` 字面量继承 `Object.prototype`,
+ *    `Object.prototype.get` / `set` 被污染时它会被读成访问器描述符)。
+ * 零 import。
+ */
+/** 数据属性描述符(可写 / 可枚举 / 可配置),**零原型**:不继承 `Object.prototype` 上被污染的 `get` / `set` 等键,也不靠对象字面量。 */
+export declare function dataDescriptor(value: unknown): PropertyDescriptor;
+/**
+ * 一份**串数组的捕获副本**;不是串数组 ⇒ `undefined`(调用方据此读成坏形 —— 名单读成 `[]` 并点名,`args` 丢键并进 `lost`)。
+ * **取值 + 检视 + 复制整段在一个 try 里**,`length` 与每个元素都只读一次(检视与后续使用不会读到两个答案):
+ *  · 不是数组,或 `length` 不是安全非负整数(读成字符串的 Proxy 等)⇒ 坏形,不按 `length` 物化;
+ *  · 逐下标先问 `Object.hasOwn` 再读 —— 洞(不是自有下标)⇒ 坏形,不顺原型链读到 `Object.prototype` / `Array.prototype` 上的数字键(数据属性或访问器);
+ *  · 条目不是串 ⇒ 坏形;遇到第一个坏处就退出(`length` 很大的稀疏数组立即判坏形);
+ *  · 副本用 `Object.defineProperty` + {@link dataDescriptor} 写(`push` / 下标赋值是 `[[Set]]`,会命中继承的数字键 setter、吞掉条目);
+ *  · 不走迭代协议(展开 / `for…of` 会让数组实例上被替换的 `Symbol.iterator` 供出别的条目);
+ *  · 读 `length` / 元素时抛(getter、Proxy 陷阱)⇒ 坏形,不抛出去。
+ * 交出去的是**副本**(不是调用方数组的原引用):调用方之后改原数组,副本不变。
+ */
+export declare function captureStringArray(v: unknown): string[] | undefined;

package/dist/definition-copy.js

@@ -0,0 +1,52 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):**定义语义的复制**。读不可信的串数组、写读出来的副本,都不许走 `[[Set]]` 与继承的成员 ——
+ * `Object.prototype` / `Array.prototype` 上被污染的数字键(getter / setter)、`get` / `set` 键、数组实例上被替换的 `Symbol.iterator`,
+ * 在下标赋值、`push`、展开、描述符对象字面量上各有一条路能把条目吞掉、替换或抛出去。本模块是这件事的唯一读法,读者只调它:
+ *  · {@link captureStringArray}:一份串数组的捕获副本(按下标、`hasOwn`、一次读、非串即坏、`defineProperty` 写入);
+ *  · {@link dataDescriptor}:写副本用的描述符,零原型(`{ value, writable, enumerable, configurable }` 字面量继承 `Object.prototype`,
+ *    `Object.prototype.get` / `set` 被污染时它会被读成访问器描述符)。
+ * 零 import。
+ */
+/** 数据属性描述符(可写 / 可枚举 / 可配置),**零原型**:不继承 `Object.prototype` 上被污染的 `get` / `set` 等键,也不靠对象字面量。 */
+export function dataDescriptor(value) {
+    const descriptor = Object.create(null);
+    descriptor.value = value;
+    descriptor.writable = true;
+    descriptor.enumerable = true;
+    descriptor.configurable = true;
+    return descriptor;
+}
+/**
+ * 一份**串数组的捕获副本**;不是串数组 ⇒ `undefined`(调用方据此读成坏形 —— 名单读成 `[]` 并点名,`args` 丢键并进 `lost`)。
+ * **取值 + 检视 + 复制整段在一个 try 里**,`length` 与每个元素都只读一次(检视与后续使用不会读到两个答案):
+ *  · 不是数组,或 `length` 不是安全非负整数(读成字符串的 Proxy 等)⇒ 坏形,不按 `length` 物化;
+ *  · 逐下标先问 `Object.hasOwn` 再读 —— 洞(不是自有下标)⇒ 坏形,不顺原型链读到 `Object.prototype` / `Array.prototype` 上的数字键(数据属性或访问器);
+ *  · 条目不是串 ⇒ 坏形;遇到第一个坏处就退出(`length` 很大的稀疏数组立即判坏形);
+ *  · 副本用 `Object.defineProperty` + {@link dataDescriptor} 写(`push` / 下标赋值是 `[[Set]]`,会命中继承的数字键 setter、吞掉条目);
+ *  · 不走迭代协议(展开 / `for…of` 会让数组实例上被替换的 `Symbol.iterator` 供出别的条目);
+ *  · 读 `length` / 元素时抛(getter、Proxy 陷阱)⇒ 坏形,不抛出去。
+ * 交出去的是**副本**(不是调用方数组的原引用):调用方之后改原数组,副本不变。
+ */
+export function captureStringArray(v) {
+    try {
+        if (!Array.isArray(v))
+            return undefined;
+        const source = v;
+        const n = source.length;
+        if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 0)
+            return undefined;
+        const copy = [];
+        for (let i = 0; i < n; i++) {
+            if (!Object.hasOwn(source, i))
+                return undefined;
+            const entry = source[i];
+            if (typeof entry !== "string")
+                return undefined;
+            Object.defineProperty(copy, i, dataDescriptor(entry));
+        }
+        return copy;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/file-store.d.ts

@@ -1,22 +1,7 @@
 import { type EffectiveReadWarning } from "./config-fns.js";
 import type { ConfigReader } from "./reader.js";
 import { type DomainConfig, type DomainName, type EffectiveConfig, type RetiredDomainName } from "./types.js";
-/** The domains a single-machine TOC carries: what `FileConfigStore` reads out of `config.d/`, and the
- *  **default**域集 of the bundle helpers (`exportBundle`/`readBundle`). 每个被排除的域必须在
- *  {@link NON_PORTABLE_DOMAIN_REASONS} 里有一条成文理由(禁裸排除,#282 件5 附带裁定)。
- *
- *  ⚠️ 口径诚实(对抗复审 复审 round1 F4):这是**默认集与本地读取集,不是 API 级硬边界** —— `exportBundle`
- *  / `readBundle` 的 `domains` 参数可显式传任意 `DomainName`(bundle.ts 不拒非便携域)。把非便携域搬进
- *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
- *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
- *
- *  🔴 **开新顶层域时必须同步登记本表**(成案 = 消费方 #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", "governance", "execution", "prompts", "limits"];
-export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
+export { NON_PORTABLE_DOMAIN_REASONS, PORTABLE_DOMAINS, type PortableDomain } from "./portable-domains.js";
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
  *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
@@ -24,21 +9,6 @@ export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
  *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
  *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
 export declare const NON_DOMAIN_CONFIG_FILES: ReadonlySet<string>;
-/**
- * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
- *
- * `satisfies Record<Exclude<DomainName, PortableDomain>, string>` 让键集在**编译期**双向咬死:新开一个
- * 域却不放进 PORTABLE_DOMAINS ⇒ 这里缺行 ⇒ 编译错;把某域改成便携却忘了删行 ⇒ 多余键 ⇒ 编译错。
- * (此前是「理由写在注释里」,机器只能做子串匹配——域名出现在文件任何角落都算数,等于没门;对抗复审
- * 复审 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+路由)属于 web-admin 侧生命周期,单机 lane 无对应执法点。";
-    readonly projects: "TENANT IDENTITY DATA,不是可搬运的配置:登记簿随包复制进另一个部署 = 凭空多出的身份登记(design/142 §1.4 威胁模型①「carried-in foreign projectId」换了身 import 的衣服)。要带走走 142 §5 的导出面(service 半场)。";
-    readonly entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service / web-admin 边界)。缺席语义如实:本地 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 = {