@sema-agent/settings-schema 14.6.0 → 14.8.0

package/dist/config-root-node.d.ts

@@ -0,0 +1,117 @@
+import { type ConfigRootDocument, type EnvModelsDecision, type EnvModelsDecisionWord, type MarkedMigrationId, type MigrationMarker, type RootDocumentUnreadableReason } from "./config-root-documents.js";
+import { type EnvModelTableEntry, type EnvSnapshot } from "./env-model-table.js";
+import type { MigrationReceipt } from "./migration-receipt.js";
+/** 根级文档读写的 I/O 座(注入;真绑定 {@link nodeConfigRootIo})。写的两只按文档名取模式类({@link ROOT_DOCUMENT_CLASS},类的规则见原子写器的模式表)。 */
+export interface ConfigRootIo {
+    /** 读一份文件的**字节**(digest 对字节求;解码由本包做);不存在 ⇒ 抛 `code: "ENOENT"` 的错,别的读不出照常抛(带 errno)。 */
+    readFile(file: string): Promise<Uint8Array>;
+    /** 原子覆盖写一份根级文档(同目录临时文件 → 改名;模式按该文档的类:新建经 umask、已有的沿用)。父目录须已存在。 */
+    writeDocument(document: ConfigRootDocument, file: string, text: string): Promise<void>;
+    /** 原子地**独占创建**一份根级文档(独占建临时文件、fsync → `link`;新建模式同 {@link writeDocument}):建成 ⇒ `created`;目标名已在(只有 `EEXIST`)⇒ `present`(一字不动);别的失败照常抛。 */
+    createDocument(document: ConfigRootDocument, file: string, text: string): Promise<"created" | "present">;
+    /** 目录不在就建(仅属主可进,连同缺的上级):建了 ⇒ `created`;已在 ⇒ `present`。 */
+    ensureDirectory(dir: string): Promise<"created" | "present">;
+}
+/** 真文件系统的绑定:读先过本包的符号链接判法(链接 ⇒ 它指向的真文件;悬空 ⇒ 抛,不是缺席),只读常规文件;写走本包唯一的原子写器。 */
+export declare const nodeConfigRootIo: ConfigRootIo;
+/** 配置根上 env 模型表决定的**唯一读者**(闭集答案见 `EnvModelsDecision`;从字节读出的答案带同一次读的 `digest`,io 带 `errno`)。从不抛。 */
+export declare function readEnvModelsDecision(root: string, io?: ConfigRootIo): Promise<EnvModelsDecision>;
+/**
+ * 一条一次性迁移的运行记录的**唯一读者**(文件 `<根>/config.migration.<id>.json`):不存在 ⇒ `absent`;`{"migration":<id>}` ⇒ `present`;别的 ⇒ `unreadable`
+ * (坏 JSON / 坏形 —— id 对不上也算 / 读不出)。「跑过」只问这一份文件在不在、读不读得懂,不读任何聚合文件。读数从不抛;`id` 不是写运行记录的迁移(根级文档名单里没有它的记录)⇒
+ * `TypeError`,不拿它拼路径。
+ */
+export declare function readMigrationMarker(root: string, id: MarkedMigrationId, io?: ConfigRootIo): Promise<MigrationMarker>;
+/** {@link writeEnvModelsDecision} 的写法(闭集):`overwrite` = 写者(用户确认之后,整份覆盖);`createIfAbsent` = 不存在才建。 */
+export type EnvModelsDecisionWrite = "overwrite" | "createIfAbsent";
+/**
+ * 写配置根上的 env 模型表决定 —— 决定文件的**唯一写函数**(迁移铸确认也经它的 `createIfAbsent`;运行记录不归它,见文件头)。`overwrite` 恒答 `written`;`createIfAbsent` 在文档已在(`EEXIST`)时答 `present`(一字不动)。
+ * 决定词 / 写法不在闭集 ⇒ `TypeError`(一字不写)。写失败 ⇒ 抛本包的文件系统失败句(点名路径)。根须已存在。
+ */
+export declare function writeEnvModelsDecision(root: string, decision: EnvModelsDecisionWord, opts: {
+    readonly write: EnvModelsDecisionWrite;
+}, io?: ConfigRootIo): Promise<"written" | "present">;
+/** SS-M11 的结局(闭集,调用方穷举;本函数不出声,告警由调用方按结局发)。 */
+export type EnvModelsMigration = 
+/** 运行记录已在:不跑。 */
+{
+    readonly kind: "already_ran";
+}
+/** 运行记录读不懂:按已跑处理(读不懂记录就不替人铸确认),一字不写。调用方告警。 */
+ | {
+    readonly kind: "marker_unreadable";
+    readonly reason: RootDocumentUnreadableReason;
+}
+/** 独占创建运行记录时它已在(`EEXIST`):别的进程已是本根的铸造者 ⇒ 本进程永不铸。 */
+ | {
+    readonly kind: "not_minter";
+}
+/** 运行记录建不成(只读根、根建不出、`ENOSPC`、文件系统不支持硬链接 —— `ENOTSUP` / `EPERM` …):不铸 —— 缺席照旧读作 kept。
+ *  记录始终建不成 ⇒ 每次起服都重跑、都答这一格(调用方每次告警;手写的决定照常生效,告警不因它停)。`error` 点名记录文件,`wayOut` 是手工恢复句。 */
+ | {
+    readonly kind: "marker_write_failed";
+    readonly errno: string | undefined;
+    readonly error: string;
+    readonly wayOut: string;
+}
+/** 本进程独占创建了运行记录 = 本根唯一的铸造者;`decision` = 选举**之前**读到的决定(铸只按它),`mint` = 铸没铸。 */
+ | {
+    readonly kind: "recorded";
+    readonly createdRoot: boolean;
+    readonly decision: EnvModelsDecision;
+    readonly mint: EnvModelsMint;
+};
+/**
+ * SS-M11 铸确认的结局(闭集)。**披露**:运行记录先于确认建;进程在两者之间中断,或铸失败、或 models.json 读不出 ⇒ 此后无人再铸、决定缺席读作 kept ——
+ * 升级前由目录服务的根这时换成 env 模型服务,旧目录不会自动保住;出路是 `wayOut` 那一句(手写决定文件)。
+ */
+export type EnvModelsMint = 
+/** 铸了 `replaced`:`replacedEnvModels` = 从此被目录顶替的 env 模型(名 + 槽 + 来源键;env 表没声明 ⇒ 空)—— 非空时调用方据此发一行一次性告警,点名它们与出路(删掉 / 写 kept)。 */
+{
+    readonly kind: "minted";
+    readonly receipt: MigrationReceipt;
+    readonly replacedEnvModels: readonly EnvModelTableEntry[];
+}
+/** 独占创建决定时它已在(只有 `EEXIST` 算):期间有人写了决定(用户的 kept / 写者的 replaced)⇒ 一字不动。 */
+ | {
+    readonly kind: "exists";
+}
+/** 决定建不成(`ENOSPC` / `EIO` / `EPERM` / 文件系统不支持硬链接 …):缺席照旧读作 kept,记录在 ⇒ 此后不再尝试。`error` 点名决定文件,`wayOut` 是手工恢复句。 */
+ | {
+    readonly kind: "failed";
+    readonly errno: string | undefined;
+    readonly error: string;
+    readonly wayOut: string;
+}
+/** 不铸:选举前读到的决定已在(replaced / kept / 读不懂 —— 读不懂的不覆盖;它之后被删也不重铸)/ 目录不管模型面(没有 models.json —— 只有 `ENOENT` 算没有 —— 或坏文件)。
+ *  判序:决定 → 目录。铸不铸不看 env 表:迁移保的是升级前「管模型面的目录整表顶替 env」这个读法,与 env 声没声明无关。 */
+ | {
+    readonly kind: "skipped";
+    readonly why: "decision_present" | "not_managing";
+}
+/** 不铸,且要运维动手:决定缺席,而 models.json 读不出(`EACCES` / `EIO` / `ESTALE` / 悬空符号链接 / 不是常规文件 …)—— 管不管判不了,不替人铸(fail-closed)。
+ *  运行记录已在 ⇒ 此后不再尝试:与 `failed` 同一出路(`wayOut`,手写决定文件);`error` 点名 models.json 与读错,`errno` 只在底层错误带码时有
+ *  (悬空链接 / 不是常规文件 ⇒ `undefined`),调用方告警。 */
+ | {
+    readonly kind: "models_unreadable";
+    readonly errno: string | undefined;
+    readonly error: string;
+    readonly wayOut: string;
+};
+/**
+ * **一次性迁移 SS-M11**(登记见 `ONE_TIME_MIGRATIONS`;起服、第一次读本地配置之前调,只在配置源是本地时):
+ *  1. 读运行记录:`present` ⇒ `already_ran`;读不懂 ⇒ `marker_unreadable`(按已跑处理)。
+ *  2. **先读**:决定 D0 = `readEnvModelsDecision`,M0 = `config.d/models.json` 管不管模型面(管 / 不管 / 读不出)。此后的铸只按 D0 / M0 决定,不再读决定 ——
+ *     D0 是 replaced(预置)而它在选举之后被删 ⇒ 不重铸;D0 是 absent 而选举之后有人写了决定 ⇒ 第 5 步的独占创建守住它。
+ *  3. 根缺席 ⇒ 建(仅属主可进,连同缺的上级,模式恰是 0o700);**不建 `config.d`**。
+ *  4. **独占创建运行记录** `{"migration":"SS-M11"}`:建成 ⇒ 本进程是本根**唯一的铸造者**;已在(`EEXIST`)⇒ `not_minter`,永不铸;别的失败 ⇒ `marker_write_failed`,不铸。
+ *  5. 仅铸造者:D0 不是 `absent` ⇒ 不铸(读不懂的也不覆盖);M0 不管 ⇒ 不铸;M0 读不出 ⇒ 不铸(`models_unreadable`,带 errno(若有)与手工恢复句);否则**独占创建** `{"envModels":"replaced"}` —— 结局三词:`minted` / `exists`(只有 `EEXIST`)/
+ *     `failed`(带 errno 与手工恢复句)。铸不铸不看 env;env 只在铸成之后读一次、只读两槽,用来点名被顶替的 env 模型。
+ * 运行记录在场之后,确认缺席 ≡ kept(读这份决定的一律这么读:引擎强制这道闸之后、迁移、写者)。
+ * 撤销的终局按运行记录的创建者算:只有创建者能写确认;以运行记录在场为前提,创建者写完 / 判定不写 / 失败(结局 `minted` / `exists` / `skipped` / `models_unreadable` / `failed`,调用方各记一行)之后,删掉决定文件就是撤销且是终局(删掉运行记录再起服 ⇒ 迁移重跑,决定缺席即重铸);其它副本读到记录在场 = 已跑、跳过(或得 `EEXIST` 答 `not_minter`),它们的返回不构成终局;创建者当选到结局落定之间的窗口在挂起 / I/O 卡顿下无上界,窗口内唯一安全的撤销是写 `kept`(独占创建护住它;删掉的会被创建者照它先读的 D0 铸回);创建者在写确认之前崩溃 ⇒ 永久 `kept`(fail-closed,披露)。
+ */
+export declare function migrateEnvModelsDecision(input: {
+    readonly root: string;
+    readonly env: EnvSnapshot;
+    readonly io?: ConfigRootIo;
+}): Promise<EnvModelsMigration>;

package/dist/config-root-node.js

@@ -0,0 +1,260 @@
+/**
+ * 配置根两份根级文档的**读写函数**与一次性迁移 SS-M11 的迁移体(Node 专用,经 `./node` 出口;名字、形与闭集答案表在 `./config-root-documents`)。
+ *
+ * 读写都经一只注入的 I/O 座 {@link ConfigRootIo}(真绑定 {@link nodeConfigRootIo}:读走 `node:fs/promises`,写走本包唯一的原子写器与它的模式表),
+ * 所以单元层能把任意读写失败造出来;调用方不传就是真文件系统。
+ *
+ *  · {@link readEnvModelsDecision} / {@link readMigrationMarker} —— 唯一的读者:不存在(`ENOENT`)⇒ `absent`;别的读错(权限 —— 可信属主的 0000 文件过得了引擎的目录信任判官、
+ *    读恒 `EACCES`,是**持久**的 —— 不是常规文件、悬空符号链接、瞬时错)⇒ `unreadable io`;字节在 ⇒ 文本读法(`./config-root-documents`;决定的答案带同一次读的 `digest`)。
+ *    读数从不抛(`readMigrationMarker` 只对不写运行记录的 id 抛 `TypeError` —— 调用方的错,不拿它拼路径)。**引擎在读之前先过它自己的目录信任判官**(属主 / 写位 / 常规文件);
+ *    本函数不判属主。确认文件的字节只在这里被打开。
+ *  · {@link writeEnvModelsDecision} —— 决定文件的唯一写函数(迁移铸确认也经它):写者(用户确认之后)用 `overwrite`(原子改名覆盖,读不懂的旧文件整份换掉);
+ *    `createIfAbsent` 不存在才建(已在 ⇒ `present`;迁移铸确认用的就是这一种)。运行记录不经它 —— 由迁移独占创建。
+ *    模式与 `config.d` 域文档同一条规则(原子写器的 `config-document` 类:新建 0o644 经进程 umask、更严的 umask 只会更严;已有的文件沿用它原来的模式)—— 写者不要自己写这份文件:
+ *    自写在 umask 002 下落 0664,引擎的目录信任判官会拒。
+ *  · {@link migrateEnvModelsDecision} —— SS-M11(窗与删法见 `ONE_TIME_MIGRATIONS` 登记表那一行)。**先读后选举**:先读决定与 models.json,再以「不存在才建」写
+ *    运行记录 `config.migration.SS-M11.json` —— 建成的那个进程是本根唯一的铸造者,且只按它选举之前读到的决定铸;别的进程见记录已在即停、永不铸。
+ *    撤销的终局按创建者算(见 {@link migrateEnvModelsDecision}):运行记录在场、创建者的结局落定之后,删掉决定文件与写 `kept` 同义、是终局(删掉运行记录再起服会重跑迁移);其它副本的返回不构成终局。
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { createFileExclusive, ensureOwnerOnlyDirectory, resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
+import { catalogManagesModelPlane } from "./catalog-manages.js";
+import { configDDocumentText, configDPath, judgeConfigDText } from "./config-d-file.js";
+import { ENV_MODELS_DECISIONS, ENV_MODELS_DOCUMENT, decodeRootBytes, ioDecision, isDecisionWord, isMarkedMigrationId, migrationMarkerDocument, migrationMarkerValue, readEnvModelsDecisionBytes, readMigrationMarkerBytes, } from "./config-root-documents.js";
+import { ENV_MODEL_TABLE_KEYS, buildEnvModelBaseline, snapshotEnvModelTable } from "./env-model-table.js";
+import { FsFailure, fsFailureMessage } from "./fs-failure.js";
+import { readKey } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
+/** 根级文档 → 原子写器的模式类(穷举:加一份根级文档不补这一行 ⇒ 编译红,逼着为它选一类)。两份现有的根级文档都是契约文档(只带固定词,不带秘密值),与 `config.d` 域文档同属 `config-document`。 */
+const ROOT_DOCUMENT_CLASS = {
+    [ENV_MODELS_DOCUMENT]: "config-document",
+    [migrationMarkerDocument("SS-M11")]: "config-document",
+};
+/** 真文件系统的绑定:读先过本包的符号链接判法(链接 ⇒ 它指向的真文件;悬空 ⇒ 抛,不是缺席),只读常规文件;写走本包唯一的原子写器。 */
+export const nodeConfigRootIo = {
+    readFile: async (file) => {
+        const real = resolveSymlinkTarget(file);
+        const st = await stat(real);
+        if (!st.isFile())
+            throw new Error(`${file} is not a regular file`);
+        return readFile(real);
+    },
+    writeDocument: async (document, file, text) => writeFileAtomic(file, text, ROOT_DOCUMENT_CLASS[document]),
+    createDocument: async (document, file, text) => createFileExclusive(file, text, ROOT_DOCUMENT_CLASS[document]),
+    ensureDirectory: async (dir) => ensureOwnerOnlyDirectory(dir),
+};
+const decisionFile = (root) => path.join(root, `${ENV_MODELS_DOCUMENT}.json`);
+const markerFile = (root, id) => path.join(root, `${migrationMarkerDocument(id)}.json`);
+/** 一个被抛出的东西的 errno:**只认自有的**字符串 `code`(经内核的键读法);读不出(会抛的 `code` getter、已撤销的 Proxy)、只靠继承、不是串 ⇒ `undefined`。从不抛(读者「从不抛」靠它)。 */
+const errnoOf = (e) => {
+    const shape = jsonShapeOf(e); // 形状只问座位(总、不抛);穷举 switch:座位加一个词这里编译红
+    switch (shape) {
+        case "plain":
+        case "non_plain_object": {
+            const code = readKey(e, "code"); // Error 实例是 non_plain_object;读不出 ⇒ unreadable(不抛)
+            return code.presence === "own" && typeof code.value === "string" ? code.value : undefined;
+        }
+        case "array":
+        case "null":
+        case "primitive":
+        case "uninspectable": // 检视不了(撤销的 Proxy / 陷阱抛)的东西没有 errno,不是读者的错
+            return undefined;
+        default: {
+            const unhandled = shape;
+            throw new Error(`errnoOf: unhandled shape ${String(unhandled)}`);
+        }
+    }
+};
+/** 配置根下一份文件(两份根级文档与 `config.d/models.json`)的字节 —— 本文件唯一的缺席律:不存在(只有 `ENOENT`)⇒ `absent`;
+ *  别的读不出 ⇒ `io`(带 errno 与捕获的错,调用方要句子时据它铸)。 */
+async function readRootBytes(io, file) {
+    try {
+        return { kind: "bytes", bytes: await io.readFile(file) };
+    }
+    catch (e) {
+        const errno = errnoOf(e);
+        return errno === "ENOENT" ? { kind: "absent" } : { kind: "io", errno, cause: e };
+    }
+}
+/** 配置根上 env 模型表决定的**唯一读者**(闭集答案见 `EnvModelsDecision`;从字节读出的答案带同一次读的 `digest`,io 带 `errno`)。从不抛。 */
+export async function readEnvModelsDecision(root, io = nodeConfigRootIo) {
+    const bytes = await readRootBytes(io, decisionFile(root));
+    switch (bytes.kind) {
+        case "absent":
+            return { kind: "absent" };
+        case "io":
+            return ioDecision(bytes.errno);
+        case "bytes":
+            return readEnvModelsDecisionBytes(bytes.bytes);
+        default: {
+            const unhandled = bytes;
+            throw new Error(`readEnvModelsDecision: unhandled reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/**
+ * 一条一次性迁移的运行记录的**唯一读者**(文件 `<根>/config.migration.<id>.json`):不存在 ⇒ `absent`;`{"migration":<id>}` ⇒ `present`;别的 ⇒ `unreadable`
+ * (坏 JSON / 坏形 —— id 对不上也算 / 读不出)。「跑过」只问这一份文件在不在、读不读得懂,不读任何聚合文件。读数从不抛;`id` 不是写运行记录的迁移(根级文档名单里没有它的记录)⇒
+ * `TypeError`,不拿它拼路径。
+ */
+export async function readMigrationMarker(root, id, io = nodeConfigRootIo) {
+    if (!isMarkedMigrationId(id))
+        throw new TypeError(`readMigrationMarker: ${JSON.stringify(id)} is not a migration that writes a run marker (the root documents list it) — no path is built from it`);
+    const bytes = await readRootBytes(io, markerFile(root, id));
+    switch (bytes.kind) {
+        case "absent":
+            return { kind: "absent" };
+        case "io":
+            return { kind: "unreadable", reason: "io" };
+        case "bytes":
+            return readMigrationMarkerBytes(id, bytes.bytes);
+        default: {
+            const unhandled = bytes;
+            throw new Error(`readMigrationMarker: unhandled reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/**
+ * 写配置根上的 env 模型表决定 —— 决定文件的**唯一写函数**(迁移铸确认也经它的 `createIfAbsent`;运行记录不归它,见文件头)。`overwrite` 恒答 `written`;`createIfAbsent` 在文档已在(`EEXIST`)时答 `present`(一字不动)。
+ * 决定词 / 写法不在闭集 ⇒ `TypeError`(一字不写)。写失败 ⇒ 抛本包的文件系统失败句(点名路径)。根须已存在。
+ */
+export async function writeEnvModelsDecision(root, decision, opts, io = nodeConfigRootIo) {
+    if (!isDecisionWord(decision))
+        throw new TypeError(`writeEnvModelsDecision: decision must be one of ${ENV_MODELS_DECISIONS.join(" / ")} (got ${JSON.stringify(decision)})`);
+    const file = decisionFile(root);
+    const text = configDDocumentText({ envModels: decision });
+    const loud = (e) => {
+        throw e instanceof FsFailure ? e : new FsFailure({ landing: "write", path: file }, e);
+    };
+    const write = opts.write;
+    switch (write) {
+        case "overwrite":
+            await io.writeDocument(ENV_MODELS_DOCUMENT, file, text).catch(loud);
+            return "written";
+        case "createIfAbsent":
+            return (await io.createDocument(ENV_MODELS_DOCUMENT, file, text).catch(loud)) === "created" ? "written" : "present";
+        default: {
+            const unhandled = write;
+            throw new TypeError(`writeEnvModelsDecision: write must be "overwrite" or "createIfAbsent" (got ${JSON.stringify(unhandled)})`);
+        }
+    }
+}
+/** 手工恢复句(迁移建不成收据 / 建不成决定时随结局交出;调用方原样放进它那一行告警):点名决定文件与两种写法。 */
+const wayOutFor = (root) => `write ${decisionFile(root)} by hand — {"envModels":"replaced"} lets the catalog replace the env models, {"envModels":"kept"} keeps them`;
+/** 读 `config.d/models.json` 一次(字节经 {@link readRootBytes} —— 与两份根级文档同一条缺席律;文本过 `config.d` 文档的那一只文本判 —— 与文件仓库同一读法):
+ *  缺席 / 坏文件 ⇒ 不管;别的读错 ⇒ 读不出(不折成不管)。 */
+async function readModelsDocument(io, root) {
+    const file = configDPath(root, "models");
+    const read = await readRootBytes(io, file);
+    let bytes;
+    switch (read.kind) {
+        case "absent":
+            return { kind: "not_managing" };
+        case "io":
+            return { kind: "unreadable", errno: read.errno, error: fsFailureMessage({ landing: "read", path: file, of: "file" }, read.cause) };
+        case "bytes":
+            bytes = read.bytes;
+            break;
+        default: {
+            const unhandled = read;
+            throw new Error(`readModelsDocument: unhandled reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+    let doc;
+    try {
+        doc = judgeConfigDText("models", decodeRootBytes(bytes), file);
+    }
+    catch {
+        return { kind: "not_managing" }; // a bad file manages nothing; the file store refuses it loudly on its own read
+    }
+    return catalogManagesModelPlane(doc) ? { kind: "manages" } : { kind: "not_managing" }; // JSON 解析出来的值恒是纯数据:判官不会抛
+}
+/**
+ * **一次性迁移 SS-M11**(登记见 `ONE_TIME_MIGRATIONS`;起服、第一次读本地配置之前调,只在配置源是本地时):
+ *  1. 读运行记录:`present` ⇒ `already_ran`;读不懂 ⇒ `marker_unreadable`(按已跑处理)。
+ *  2. **先读**:决定 D0 = `readEnvModelsDecision`,M0 = `config.d/models.json` 管不管模型面(管 / 不管 / 读不出)。此后的铸只按 D0 / M0 决定,不再读决定 ——
+ *     D0 是 replaced(预置)而它在选举之后被删 ⇒ 不重铸;D0 是 absent 而选举之后有人写了决定 ⇒ 第 5 步的独占创建守住它。
+ *  3. 根缺席 ⇒ 建(仅属主可进,连同缺的上级,模式恰是 0o700);**不建 `config.d`**。
+ *  4. **独占创建运行记录** `{"migration":"SS-M11"}`:建成 ⇒ 本进程是本根**唯一的铸造者**;已在(`EEXIST`)⇒ `not_minter`,永不铸;别的失败 ⇒ `marker_write_failed`,不铸。
+ *  5. 仅铸造者:D0 不是 `absent` ⇒ 不铸(读不懂的也不覆盖);M0 不管 ⇒ 不铸;M0 读不出 ⇒ 不铸(`models_unreadable`,带 errno(若有)与手工恢复句);否则**独占创建** `{"envModels":"replaced"}` —— 结局三词:`minted` / `exists`(只有 `EEXIST`)/
+ *     `failed`(带 errno 与手工恢复句)。铸不铸不看 env;env 只在铸成之后读一次、只读两槽,用来点名被顶替的 env 模型。
+ * 运行记录在场之后,确认缺席 ≡ kept(读这份决定的一律这么读:引擎强制这道闸之后、迁移、写者)。
+ * 撤销的终局按运行记录的创建者算:只有创建者能写确认;以运行记录在场为前提,创建者写完 / 判定不写 / 失败(结局 `minted` / `exists` / `skipped` / `models_unreadable` / `failed`,调用方各记一行)之后,删掉决定文件就是撤销且是终局(删掉运行记录再起服 ⇒ 迁移重跑,决定缺席即重铸);其它副本读到记录在场 = 已跑、跳过(或得 `EEXIST` 答 `not_minter`),它们的返回不构成终局;创建者当选到结局落定之间的窗口在挂起 / I/O 卡顿下无上界,窗口内唯一安全的撤销是写 `kept`(独占创建护住它;删掉的会被创建者照它先读的 D0 铸回);创建者在写确认之前崩溃 ⇒ 永久 `kept`(fail-closed,披露)。
+ */
+export async function migrateEnvModelsDecision(input) {
+    const { root, env } = input;
+    const io = input.io ?? nodeConfigRootIo;
+    const marker = await readMigrationMarker(root, "SS-M11", io);
+    switch (marker.kind) {
+        case "present":
+            return { kind: "already_ran" };
+        case "unreadable":
+            return { kind: "marker_unreadable", reason: marker.reason };
+        case "absent":
+            break;
+        default: {
+            const unhandled = marker;
+            throw new Error(`migrateEnvModelsDecision: unhandled marker ${JSON.stringify(unhandled)}`);
+        }
+    }
+    const decision = await readEnvModelsDecision(root, io);
+    const models = await readModelsDocument(io, root);
+    const file = markerFile(root, "SS-M11");
+    let createdRoot;
+    let created;
+    try {
+        createdRoot = (await io.ensureDirectory(root)) === "created";
+        created = await io.createDocument(migrationMarkerDocument("SS-M11"), file, configDDocumentText(migrationMarkerValue("SS-M11")));
+    }
+    catch (e) {
+        return { kind: "marker_write_failed", errno: errnoOf(e), error: fsFailureMessage({ landing: "write", path: file }, e), wayOut: wayOutFor(root) };
+    }
+    if (created === "present")
+        return { kind: "not_minter" };
+    return { kind: "recorded", createdRoot, decision, mint: await mintDecision(io, root, env, decision, models) };
+}
+async function mintDecision(io, root, env, decision, models) {
+    switch (decision.kind) {
+        case "absent":
+            break;
+        case "replaced":
+        case "kept":
+        case "unreadable":
+            return { kind: "skipped", why: "decision_present" };
+        default: {
+            const unhandled = decision;
+            throw new Error(`migrateEnvModelsDecision: unhandled decision ${JSON.stringify(unhandled)}`);
+        }
+    }
+    switch (models.kind) {
+        case "manages":
+            break;
+        case "not_managing":
+            return { kind: "skipped", why: "not_managing" };
+        case "unreadable":
+            return { kind: "models_unreadable", errno: models.errno, error: models.error, wayOut: wayOutFor(root) };
+        default: {
+            const unhandled = models;
+            throw new Error(`migrateEnvModelsDecision: unhandled models reading ${JSON.stringify(unhandled)}`);
+        }
+    }
+    let wrote;
+    try {
+        wrote = await writeEnvModelsDecision(root, "replaced", { write: "createIfAbsent" }, io);
+    }
+    catch (e) {
+        // the write function throws only its file-system failure (it names the decision file and carries the errno)
+        return { kind: "failed", errno: errnoOf(e), error: fsFailureMessage({ landing: "write", path: decisionFile(root) }, e), wayOut: wayOutFor(root) };
+    }
+    if (wrote === "present")
+        return { kind: "exists" };
+    // env is read only now, once, and only the two slot keys: it names the env models the minted decision replaces (none when no table is declared);
+    // a run that stops earlier reads no env at all
+    const slots = snapshotEnvModelTable(env, [ENV_MODEL_TABLE_KEYS.mainId, ENV_MODEL_TABLE_KEYS.cheapId]);
+    return {
+        kind: "minted",
+        receipt: { migration: "SS-M11", document: ENV_MODELS_DOCUMENT, path: ["envModels"], appliedAs: "minted" },
+        replacedEnvModels: buildEnvModelBaseline(slots).entries,
+    };
+}

package/dist/conformance/canonical.js

@@ -10,7 +10,7 @@
  * `stableKey` 是唯一一处把值转成串的地方,它只用来给**多重集计数**当哈希键 —— 用的是 JSON 编码,
  * 数组边界与段类型(`"1"` vs `1`)在编码里都还在,所以它不是那种有损的点号串。
  */
-import { isPlainJsonObject } from "../plain-json-object.js";
+import { isJsonArray, isPlainJsonObject } from "../plain-json-object.js";
 /**
  * 「这个对象**在场**的键」—— 本文件里唯一一处判键在不在 / 取键的值的地方。
  *
@@ -37,7 +37,7 @@ function presentKeys(o) {
  * 「键不在场」与「键在场但值是 undefined」在比对上分成两件事,而 wire 上它们同形)。
  */
 export function canonicalize(value) {
-    if (Array.isArray(value))
+    if (isJsonArray(value))
         return value.map(canonicalize);
     if (isPlainJsonObject(value)) {
         // `Object.fromEntries`,**不是**逐键 `out[k] = …`:后者对 `"__proto__"` 走的是原型 setter(改掉对象的
@@ -55,7 +55,7 @@ export function stableKey(value) {
 export function deepEqual(a, b) {
     if (Object.is(a, b))
         return true;
-    if (Array.isArray(a) && Array.isArray(b))
+    if (isJsonArray(a) && isJsonArray(b))
         return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
     if (isPlainJsonObject(a) && isPlainJsonObject(b)) {
         const ka = presentKeys(a);
@@ -78,7 +78,7 @@ export function diffJson(expected, actual, at = []) {
     const path = at.length === 0 ? "" : "/" + at.map(pointerSegment).join("/");
     if (deepEqual(expected, actual))
         return [];
-    if (Array.isArray(expected) && Array.isArray(actual)) {
+    if (isJsonArray(expected) && isJsonArray(actual)) {
         const out = [];
         for (let i = 0; i < Math.max(expected.length, actual.length); i++) {
             if (i >= expected.length)

package/dist/conformance/contract-adapter.js

@@ -24,8 +24,33 @@
 import { materializeLocalRoot } from "./run.js";
 import { contractOwnedEntry, contractOwnedEntryWhy } from "./entry-origin.js";
 import { LEG_NAMES, REF_INTEGRITY_REJECT_CODE } from "./types.js";
+import { inspect } from "../own-key-read.js";
+import { isJsonArray, jsonShapeOf } from "../plain-json-object.js";
 /** ZodError 形(鸭子判,不用 `instanceof` —— historical 模式下旧版 dist 可能挂在另一份 zod 上)。 */
-const isZodLike = (e) => e !== null && typeof e === "object" && Array.isArray(e.issues);
+/** A thrown value that looks like a zod error (an object — not a function — with an `issues` array on it; v14.6.0's `typeof e === "object"` test, nothing more). Shape from the seat;
+ *  the one member read goes through the inspection kernel. The seat reads the prototype once to classify, but the answer never depends on it: an object whose shape cannot
+ *  be read (a `getPrototypeOf` trap that throws) is still asked for `issues` — a thrown proxy whose `issues` cannot be read is not zod-like. */
+const isZodLike = (e) => {
+    const shape = jsonShapeOf(e);
+    switch (shape) {
+        case "null":
+        case "primitive":
+            return false;
+        case "array":
+        case "plain":
+        case "non_plain_object":
+        case "uninspectable": {
+            if (typeof e === "function")
+                return false; // 被抛的函数不是 zod 错(v14.6.0 的 `typeof e === "object"` 前置判把函数排除在外)
+            const issues = inspect(() => e.issues);
+            return issues.ok && isJsonArray(issues.value);
+        }
+        default: {
+            const unhandled = shape;
+            throw new Error(`isZodLike: unhandled shape ${String(unhandled)}`);
+        }
+    }
+};
 /** 内容哈希那一层拒绝的自述 —— `stableStringify` 的深度闸是**本包自己**抛的、也只有它会抛这一句;
  *  适配器给自家流水线分层,认得自家那句话是合理的(消费方的适配器认它自己那几层的错)。 */
 const HASH_STAGE_MARK = "stableStringify:";

package/dist/conformance/corpus.js

@@ -20,7 +20,7 @@ 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";
+import { isJsonArray, isPlainJsonObject } from "../plain-json-object.js";
 /** 本包的根目录 —— `src/conformance/*.ts` 与 `dist/conformance/*.js` 距根同深,两处求值同一个地方。 */
 export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 /** 语料目录(默认 = 本包的 `conformance/`)。 */
@@ -45,7 +45,7 @@ function checkLegExpectation(v, where) {
     }
     if (r.outcome === "effective") {
         requireRecord(r.effective, `${where}.effective`);
-        if (!Array.isArray(r.warnings))
+        if (!isJsonArray(r.warnings))
             throw new Error(`conformance corpus: ${where}.warnings must be an array`);
         const meta = requireRecord(r.metadata, `${where}.metadata`);
         if (typeof meta.updatedAt !== "string")
@@ -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) => isPlainJsonObject(x) && Array.isArray(x.path) && x.path.every((seg) => typeof seg === "string" || typeof seg === "number"));
+            const ok = isJsonArray(r.refIssues) && r.refIssues.every((x) => isPlainJsonObject(x) && isJsonArray(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)[] }`);
         }
@@ -76,7 +76,7 @@ export async function loadCase(dir, id) {
     requireRecord(input.domains, `${id}/input.json#domains`);
     if (typeof meta.claim !== "string" || meta.claim.trim().length === 0)
         throw new Error(`conformance corpus: ${id}/meta.json#claim is empty — 每条语料必须写它想打谁`);
-    if (!Array.isArray(meta.firstRedOn))
+    if (!isJsonArray(meta.firstRedOn))
         throw new Error(`conformance corpus: ${id}/meta.json#firstRedOn must be an array`);
     const legs = {};
     for (const leg of LEG_NAMES) {

package/dist/conformance/derive.js

@@ -36,7 +36,7 @@
  */
 import { NON_DOMAIN_CONFIG_FILES } from "../file-store.js";
 import { PORTABLE_DOMAINS } from "../portable-domains.js";
-import { isPlainJsonObject } from "../plain-json-object.js";
+import { isJsonArray, 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` 都读它)。 */
@@ -72,7 +72,7 @@ export const foreignKeysOf = (docs) => Object.keys(docs).filter((k) => !isDomain
 /** T2 的**入参**半场:域形的 skills 文档 → wire 形的 manifest 文档。结构变换,不解析 —— 坏形原样传下去,
  *  让 wire 腿自己的判据去裁(否则语料就没法喂一份坏 manifest 了)。 */
 export function toManifestDoc(doc) {
-    if (!isPlainJsonObject(doc) || !Array.isArray(doc.skills))
+    if (!isPlainJsonObject(doc) || !isJsonArray(doc.skills))
         return doc;
     return {
         ...doc,

package/dist/conformance/run.d.ts

@@ -6,6 +6,9 @@ import { type ConformanceAdapter, type ConformanceOptions, type ConformanceRepor
  * mtime 怎么设、目录怎么建就会各不相同,而 `updatedAt` 正是按 mtime 算的)。
  *
  * 返回 `root` 与 `cleanup`;所有文件的 mtime 统一设成 `mtime`,于是 `updatedAt` 对同一份快照恒定。
+ *
+ * 临时根只在 `./temp-roots` 里铸、只在那里删:进程在 `cleanup()` 之前死掉(`process.exit`、未捕获异常、信号、SIGKILL)时根留在 tmp 下,
+ * 根里的 `.alive` 超过 60 分钟没更新之后,由下一轮第一次铸根的清扫收走 —— 这里不碰临时目录的路径、前缀和清理,也不在进程上装任何监听。
  */
 export declare function materializeLocalRoot(files: Readonly<Record<string, string>>, mtime: string): Promise<{
     root: string;