@sema-agent/settings-schema 14.7.0 → 14.8.0

package/dist/catalog-manages.js

@@ -0,0 +1,60 @@
+/**
+ * 「一份 models 文档管不管模型面」—— **原文半场的唯一判官**(纯、零依赖、浏览器安全)。
+ *
+ * ## 律(一条)
+ * **文档的 `models` 里至少一条不是「显式停用」的条目 ⇔ 管。** 「显式停用」= 纯 JSON 对象、自有数据属性 `enabled` 恰为 `false`
+ * ({@link ownEnabledFlag} 是这一读法的**唯一**实现:被丢条目身份的 `enabled`(`./config-fns` 的 `readEntryIdentity`)读的是同一只;{@link entryEnabledFlag} 只是它前面判一次形的入口)。
+ * 判官 = 计数 > 0:「管不管」与「几条在管」是同一个事实的两种问法,只有一种读法。
+ *
+ *  · 文档不是纯对象、`models` 缺席或不是数组 ⇒ 0 条(不管);数组里的洞不是条目;
+ *  · 条目本身不是对象(坏条目)⇒ 不是「显式停用」⇒ 计入 —— 引擎读腿那一半(被丢条目载体:形不对 ⇒ 算管)同答;
+ *  · 读不出的值(撤销的 Proxy、访问器 / 隐藏的自有键、类实例 —— JSON 解析不出这些)⇒ 抛 `TypeError`,带全包那一句:判官的两个调用方失败方向相反
+ *    (写者的计划助手:「管」= 要问人;一次性迁移:「管」= 替人铸确认),不替它们猜。
+ *
+ * 读后表示(引擎的读腿载体半场)不在本包:那一半读的是引擎自己的被丢条目载体,由引擎在本判官之上 ∨ 一格。
+ */
+import { captureJson, isAccessorDescriptor } from "./own-key-read.js";
+import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js";
+/**
+ * 一个**已核过是纯 JSON 对象**的条目的 `enabled`:自有数据属性且是布尔 ⇒ 它;其余(缺席、只靠继承、访问器、不是布尔)⇒ `undefined`。不调 getter。
+ * 反射本身抛(Proxy 的描述符陷阱)⇒ **照抛**,由调用方的失败臂收:被丢条目身份整份按读不出处置(不带半份身份);原文判官读的是捕获出来的快照,不会走到这里。
+ * 包内私有(不进包根):这是「`enabled` 怎么读」的**唯一实现**;条目的形由调用方判一次(被丢条目身份在读 `name` / `id` 之前已判过,这里不再问第二次)。
+ */
+export function ownEnabledFlag(entry) {
+    const d = Object.getOwnPropertyDescriptor(entry, "enabled");
+    const value = d !== undefined && !isAccessorDescriptor(d) ? d.value : undefined; // 访问器不调(描述符的字段只认自有的,见内核)
+    return typeof value === "boolean" ? value : undefined;
+}
+/** 一条目录条目**原文**的 `enabled`:先判形(不是纯 JSON 对象 ⇒ `undefined`),再读 {@link ownEnabledFlag}。「显式停用」与计划助手的启用过滤都调它。 */
+export function entryEnabledFlag(entry) {
+    return isPlainJsonObject(entry) ? ownEnabledFlag(entry) : undefined;
+}
+/** 「显式停用」:{@link entryEnabledFlag} 恰为 `false`。 */
+const isExplicitlyDisabled = (entry) => entryEnabledFlag(entry) === false;
+/**
+ * 文档里**不是显式停用**的条目数(日志计数用;判官 {@link catalogManagesModelPlane} 就是它 > 0)。入参是 models 文档原文或读过的 `ModelsConfig`(两者同形)。
+ * 读不出 ⇒ `TypeError`(见文件头)。
+ */
+export function enabledEntryCount(doc) {
+    const copy = captureJson(doc); // 一次自有键快照:之后的读都在副本上(不调 getter、不读继承)
+    if (!copy.ok)
+        throw new TypeError(`enabledEntryCount: the models document could not be read — ${copy.sentence}`);
+    const snapshot = copy.value;
+    if (!isPlainJsonObject(snapshot))
+        return 0;
+    const models = snapshot.models; // 副本是隔离原型的袋:没有继承成员可读
+    if (!isJsonArray(models))
+        return 0;
+    let count = 0;
+    for (let i = 0; i < models.length; i++) {
+        if (!Object.hasOwn(models, i))
+            continue; // 洞不是条目:只认自有下标(`forEach` / `for…of` 会读到被污染的 `Array.prototype[i]`)
+        if (!isExplicitlyDisabled(models[i]))
+            count++;
+    }
+    return count;
+}
+/** 这份 models 文档管模型面吗(见文件头的律)。读不出 ⇒ `TypeError`。 */
+export function catalogManagesModelPlane(doc) {
+    return enabledEntryCount(doc) > 0;
+}

package/dist/center-refs.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 中心引用的**解析口** `resolveCenterRefs(refs, lookup)` —— 纯函数、浏览器安全。
+ *
+ * 中心名册里 MCP server 的传输带两张**引用表**:stdio 的 `envRefs`(目标 env 键 → 变量名)、http 的 `headerRefs`(目标头名 → 变量名)。名册只存**变量名**、从不存值;
+ * 值要在消费方自己的宿主环境里读。此前本包只发引用表的形、不发读它的法:变量没设、设了但读到的不是串、读它的时候抛了,留给每个宿主自己写 —— 各按各的口径处置、各留各的句子。
+ * 现在一个读法:**每个成员一句判定,整台一个结论;本口只判,不决定挂不挂**(挂不挂是调用方按自己那条腿的规则定的事)。
+ *
+ * ## 律(一条)
+ * 引用表怎么读、每个变量怎么问、读不出怎么说,只有这一处:
+ *  · **引用表经公开的记录读器读**({@link readPlainStringRecord}:同一个函数、同一张原因词表 {@link PLAIN_STRING_RECORD_FAULTS}),不另写形状 / 描述符判据。读不出(整张不是纯数据、有成员的变量名不是串、
+ *    读成员就抛、叫 `__proto__` 的成员)⇒ 整台结论 `refs_unreadable`,带读器的词,**一个变量都不问** —— 引用表本身不可信时,问了的值也没有可以挂的地方。
+ *    读器会把叫 `__proto__` 的串值成员**剔出副本**交其余;本口不许这样悄悄丢一条引用再挂一台少了鉴权的 server,所以同样答 `refs_unreadable`、词 `member_name_reserved`。
+ *  · **查找函数 `lookup(name)` 由调用方给**,本口**不读 `process.env`**(源里没有 `process` / `globalThis`;宿主怎么读环境、读哪一层环境、要不要缓存,都是调用方的事)。没给 / 不是函数 ⇒ `TypeError`
+ *    (这是调用方的编程错,不是数据错:不折成成员的 `read_threw`,更不回落任何环境)。
+ *  · 每个成员恰问一次 `lookup`(按引用表副本的自有键序 —— 整数形的键在前、其余按记录列出的次序;实参只有变量名一个),判成**一个词**({@link CenterRefMemberVerdict}):
+ *    `resolved`(答了串,空串也是串)· `missing_name`(答 `undefined`:变量没设)· `not_a_string`(答了别的种类 —— 例如对普通对象做 `obj[name]` 读到继承来的函数)· `read_threw`(`lookup` 抛了,不传出)。
+ *    一个成员坏了**不早停**:每个成员都有自己的判定,调用方可以一次点名所有缺的变量。同一个变量被两个目标键引用就问两次(缓存是查找函数的事)。
+ *  · 整台结论只有三个词({@link CenterRefsVerdict}):`resolved`(每个成员都是 `resolved`;零成员也是)· `unresolved`(有成员不是)· `refs_unreadable`(引用表读不出)。
+ *    **值只在 `resolved` 臂的 `values` 里**;`unresolved` 臂的行只有词,没有任何变量的值(失败读数会进日志)。
+ *
+ * ## 引用表缺席
+ * `refs` 是 `undefined`(这台 server 没声明引用)⇒ `resolved`、零成员、一次都不问 —— 与「空表」同一个答案。别的不是纯数据记录的值(`null`、数组、串……)是 `refs_unreadable`,不当缺席。
+ *
+ * ## 读数的构造
+ * 成员表用 `map`,`values` 用 `Object.defineProperty` + 零原型描述符({@link dataDescriptor})逐键写进一个新对象(定义语义,不走 [[Set]]):`Object.prototype` 上挂了数字键 setter 时目标键 `"0"` 的值也不会被吞;
+ * `constructor` / `toString` 这类原型链上的名字作目标键照落成自有数据属性。交出的 `values` 原型是 `Object.prototype`,与读器交出的副本同形。
+ */
+import { type PlainStringRecordFault } from "./mcp-request-entry.js";
+/** 一个成员没解到的**原因词**,闭集,三个:`missing_name`(查找函数答 `undefined` —— 变量没设)· `not_a_string`(答了别的种类)· `read_threw`(查找函数抛了)。消费方按词分派,穷尽 `switch`,不读句子(本口没有句子)。 */
+export declare const CENTER_REF_FAULTS: readonly ["missing_name", "not_a_string", "read_threw"];
+export type CenterRefFault = (typeof CENTER_REF_FAULTS)[number];
+/** 一个成员的判定词:解到了(`resolved`)或{@link CenterRefFault}之一。 */
+export type CenterRefMemberVerdict = "resolved" | CenterRefFault;
+/** 整台结论的词,闭集,三个:`resolved` · `unresolved`(有成员没解到)· `refs_unreadable`(引用表读不出)。 */
+export declare const CENTER_REFS_VERDICTS: readonly ["resolved", "unresolved", "refs_unreadable"];
+export type CenterRefsVerdict = (typeof CENTER_REFS_VERDICTS)[number];
+/** 调用方给的查找函数:变量名 → 它的值(没设 ⇒ `undefined`)。可以抛(本口接住,判 `read_threw`)。本口不替它读任何环境。 */
+export type CenterRefLookup = (name: string) => string | undefined;
+/** 一个成员的判定:`key` = 目标键(env 键 / 头名,按引用表所写)、`ref` = 它引用的变量名(按所写)、`verdict` = 判定词。行里没有值。 */
+export interface CenterRefMember {
+    readonly key: string;
+    readonly ref: string;
+    readonly verdict: CenterRefMemberVerdict;
+}
+/**
+ * {@link resolveCenterRefs} 的读数,按 `verdict` 分三臂(穷尽 `switch`):
+ *  · `resolved`:`members` 每行都是 `resolved`;`values` = 目标键 → 解到的串(新铸的朴素对象);
+ *  · `unresolved`:`members` 里至少一行不是 `resolved`(行的次序 = 询问的次序,见文件头注);没有 `values`;
+ *  · `refs_unreadable`:引用表没读成 —— `fault` = 读器的原因词({@link PlainStringRecordFault}),坏在某个成员时 `member` 点名它的回显形;没问过任何变量。
+ */
+export type CenterRefsResolution = {
+    readonly verdict: "resolved";
+    readonly members: readonly CenterRefMember[];
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly verdict: "unresolved";
+    readonly members: readonly CenterRefMember[];
+} | {
+    readonly verdict: "refs_unreadable";
+    readonly fault: PlainStringRecordFault;
+    readonly member?: string;
+};
+/**
+ * 解析一张中心引用表(见文件头注的律)。`refs` 是名册里 `envRefs` / `headerRefs` 的值(`undefined` = 没声明);`lookup` 是调用方给的查找函数(必给)。
+ * 判而不决:`resolved` 之外的两个结论,调用方按自己那条腿的规则处置(例如整台不挂、并点名没解到的成员)。
+ * `lookup` 不是函数 ⇒ `TypeError`;别的一切输入都得到一个读数,不抛。
+ */
+export declare function resolveCenterRefs(refs: unknown, lookup: CenterRefLookup): CenterRefsResolution;

package/dist/center-refs.js

@@ -0,0 +1,70 @@
+/**
+ * 中心引用的**解析口** `resolveCenterRefs(refs, lookup)` —— 纯函数、浏览器安全。
+ *
+ * 中心名册里 MCP server 的传输带两张**引用表**:stdio 的 `envRefs`(目标 env 键 → 变量名)、http 的 `headerRefs`(目标头名 → 变量名)。名册只存**变量名**、从不存值;
+ * 值要在消费方自己的宿主环境里读。此前本包只发引用表的形、不发读它的法:变量没设、设了但读到的不是串、读它的时候抛了,留给每个宿主自己写 —— 各按各的口径处置、各留各的句子。
+ * 现在一个读法:**每个成员一句判定,整台一个结论;本口只判,不决定挂不挂**(挂不挂是调用方按自己那条腿的规则定的事)。
+ *
+ * ## 律(一条)
+ * 引用表怎么读、每个变量怎么问、读不出怎么说,只有这一处:
+ *  · **引用表经公开的记录读器读**({@link readPlainStringRecord}:同一个函数、同一张原因词表 {@link PLAIN_STRING_RECORD_FAULTS}),不另写形状 / 描述符判据。读不出(整张不是纯数据、有成员的变量名不是串、
+ *    读成员就抛、叫 `__proto__` 的成员)⇒ 整台结论 `refs_unreadable`,带读器的词,**一个变量都不问** —— 引用表本身不可信时,问了的值也没有可以挂的地方。
+ *    读器会把叫 `__proto__` 的串值成员**剔出副本**交其余;本口不许这样悄悄丢一条引用再挂一台少了鉴权的 server,所以同样答 `refs_unreadable`、词 `member_name_reserved`。
+ *  · **查找函数 `lookup(name)` 由调用方给**,本口**不读 `process.env`**(源里没有 `process` / `globalThis`;宿主怎么读环境、读哪一层环境、要不要缓存,都是调用方的事)。没给 / 不是函数 ⇒ `TypeError`
+ *    (这是调用方的编程错,不是数据错:不折成成员的 `read_threw`,更不回落任何环境)。
+ *  · 每个成员恰问一次 `lookup`(按引用表副本的自有键序 —— 整数形的键在前、其余按记录列出的次序;实参只有变量名一个),判成**一个词**({@link CenterRefMemberVerdict}):
+ *    `resolved`(答了串,空串也是串)· `missing_name`(答 `undefined`:变量没设)· `not_a_string`(答了别的种类 —— 例如对普通对象做 `obj[name]` 读到继承来的函数)· `read_threw`(`lookup` 抛了,不传出)。
+ *    一个成员坏了**不早停**:每个成员都有自己的判定,调用方可以一次点名所有缺的变量。同一个变量被两个目标键引用就问两次(缓存是查找函数的事)。
+ *  · 整台结论只有三个词({@link CenterRefsVerdict}):`resolved`(每个成员都是 `resolved`;零成员也是)· `unresolved`(有成员不是)· `refs_unreadable`(引用表读不出)。
+ *    **值只在 `resolved` 臂的 `values` 里**;`unresolved` 臂的行只有词,没有任何变量的值(失败读数会进日志)。
+ *
+ * ## 引用表缺席
+ * `refs` 是 `undefined`(这台 server 没声明引用)⇒ `resolved`、零成员、一次都不问 —— 与「空表」同一个答案。别的不是纯数据记录的值(`null`、数组、串……)是 `refs_unreadable`,不当缺席。
+ *
+ * ## 读数的构造
+ * 成员表用 `map`,`values` 用 `Object.defineProperty` + 零原型描述符({@link dataDescriptor})逐键写进一个新对象(定义语义,不走 [[Set]]):`Object.prototype` 上挂了数字键 setter 时目标键 `"0"` 的值也不会被吞;
+ * `constructor` / `toString` 这类原型链上的名字作目标键照落成自有数据属性。交出的 `values` 原型是 `Object.prototype`,与读器交出的副本同形。
+ */
+import { PLAIN_STRING_RECORD_RESERVED_MEMBER, readPlainStringRecord } from "./mcp-request-entry.js";
+import { dataDescriptor, inspect } from "./own-key-read.js";
+/** 一个成员没解到的**原因词**,闭集,三个:`missing_name`(查找函数答 `undefined` —— 变量没设)· `not_a_string`(答了别的种类)· `read_threw`(查找函数抛了)。消费方按词分派,穷尽 `switch`,不读句子(本口没有句子)。 */
+export const CENTER_REF_FAULTS = ["missing_name", "not_a_string", "read_threw"];
+/** 整台结论的词,闭集,三个:`resolved` · `unresolved`(有成员没解到)· `refs_unreadable`(引用表读不出)。 */
+export const CENTER_REFS_VERDICTS = ["resolved", "unresolved", "refs_unreadable"];
+/** 问一次 `lookup(ref)` 并判成一个词。抛了 ⇒ `read_threw`(经内核的检视口,不另包 `try`);答 `undefined` ⇒ `missing_name`;答串 ⇒ 解到;答别的 ⇒ `not_a_string`。 */
+function answerOf(ref, lookup) {
+    const asked = inspect(() => lookup(ref));
+    if (!asked.ok)
+        return { verdict: "read_threw" };
+    const answer = asked.value;
+    if (typeof answer === "string")
+        return { verdict: "resolved", value: answer };
+    return { verdict: answer === undefined ? "missing_name" : "not_a_string" };
+}
+/**
+ * 解析一张中心引用表(见文件头注的律)。`refs` 是名册里 `envRefs` / `headerRefs` 的值(`undefined` = 没声明);`lookup` 是调用方给的查找函数(必给)。
+ * 判而不决:`resolved` 之外的两个结论,调用方按自己那条腿的规则处置(例如整台不挂、并点名没解到的成员)。
+ * `lookup` 不是函数 ⇒ `TypeError`;别的一切输入都得到一个读数,不抛。
+ */
+export function resolveCenterRefs(refs, lookup) {
+    if (typeof lookup !== "function") {
+        throw new TypeError("resolveCenterRefs: `lookup` must be a function (variable name => string | undefined) supplied by the caller — this function reads no environment of its own");
+    }
+    if (refs === undefined)
+        return { verdict: "resolved", members: [], values: {} };
+    const read = readPlainStringRecord(refs);
+    if (!read.ok)
+        return { verdict: "refs_unreadable", fault: read.fault, ...(read.member !== undefined ? { member: read.member } : {}) };
+    if (read.reservedMember)
+        return { verdict: "refs_unreadable", fault: "member_name_reserved", member: PLAIN_STRING_RECORD_RESERVED_MEMBER };
+    const judged = Object.entries(read.record).map((pair) => ({ key: pair[0], ref: pair[1], answer: answerOf(pair[1], lookup) }));
+    const members = judged.map((j) => ({ key: j.key, ref: j.ref, verdict: j.answer.verdict }));
+    if (judged.some((j) => j.answer.verdict !== "resolved"))
+        return { verdict: "unresolved", members };
+    const values = {};
+    for (const j of judged) {
+        if (j.answer.verdict === "resolved")
+            Object.defineProperty(values, j.key, dataDescriptor(j.answer.value));
+    }
+    return { verdict: "resolved", members, values };
+}

package/dist/config-dir-migration.js

@@ -56,6 +56,7 @@ export function reportReceipt(r) {
         case "rewritten":
         case "dropped-shadowed":
         case "dropped-inert":
+        case "minted":
             return base;
         default: {
             const unhandled = r;

package/dist/config-fns.js

@@ -18,6 +18,7 @@
 import { z } from "zod";
 import { MODEL_ENTRY_REFUSAL_CODES, ModelRefusalsWire } from "./fleet.js";
 import { UNINSPECTABLE, dataDescriptor, emptyDocument, guardedSafeParse, inspect, isAccessorDescriptor, isolatedObject, ownEntriesOf, ownRow, ownValueOf } from "./own-key-read.js";
+import { ownEnabledFlag } from "./catalog-manages.js";
 import { isJsonArray, isPlainJsonObject, jsonShapeOf } 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";
@@ -362,7 +363,8 @@ export function withheldNameToken(name) {
     return `withheld:${sha256Hex(`${WITHHELD_NAME_TOKEN_DOMAIN}${JSON.stringify(name)}`).slice(0, 12)}`;
 }
 /** 一条被丢条目原文的身份({@link DroppedEntryIdentity} 的**唯一**读法)。只看纯 JSON 对象的**自有数据
- *  属性**;任何反射/陷阱抛错 ⇒ 当作读不出(身份是诊断面的附件,绝不许把抢救拖下水)。 */
+ *  属性**;任何反射/陷阱抛错 ⇒ 当作读不出(身份是诊断面的附件,绝不许把抢救拖下水)。`enabled` 读的是「显式停用」的那一只
+ *  ({@link ownEnabledFlag},`./catalog-manages`):目录管不管模型面的原文判官与这里同一份读法。 */
 function readEntryIdentity(entry) {
     try {
         if (!isPlainJsonObject(entry))
@@ -373,11 +375,11 @@ function readEntryIdentity(entry) {
         };
         const name = own("name");
         const id = own("id");
-        const enabled = own("enabled");
+        const enabled = ownEnabledFlag(entry); // 形上面已判过一次(`isPlainJsonObject`):不再经判形的入口问第二次
         const identity = {
             ...(typeof name === "string" ? (isDisclosableIdentity(name) ? { name } : { nameWithheld: true, token: withheldNameToken(name) }) : {}),
             ...(typeof id === "string" ? (isDisclosableIdentity(id) ? { id } : { idWithheld: true }) : {}),
-            ...(typeof enabled === "boolean" ? { enabled } : {}),
+            ...(enabled === undefined ? {} : { enabled }),
         };
         return Object.keys(identity).length > 0 ? identity : undefined;
     }

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

@@ -0,0 +1,106 @@
+/**
+ * 配置根上的**根级文档**(纯、零 I/O、浏览器安全;读写函数在 `./node`,见 `./config-root-node`)。
+ *
+ * ```
+ * <根>/
+ *   config.d/…                       便携域文档(文件仓库只扫这一个目录)
+ *   config.env-models.json           env 模型表被目录顶替的部署决定  {"envModels":"replaced"|"kept"}
+ *   config.migration.SS-M11.json     一次性迁移 SS-M11 的运行记录      {"migration":"SS-M11"}(按 id 一份)
+ *   .env                             秘密值(不归本包读)
+ * ```
+ *
+ * ## 律
+ *  · **根归客户端(TOC)所有**,引擎在根上只写这两份文档;两份都在 `config.d/` 之外 —— 已核的各版文件仓库都只扫 `<根>/config.d`(抽样,不证全称),
+ *    被检视的配置读者不把这两份当域文档、不因它们在场拒配置,所以写者不探引擎版本。
+ *    离线预置(引擎在本根起服之前铺好:镜像 / ConfigMap / 还原)时两份文档与域文档可按任意顺序写;运行时写序是定的:写者先写决定、再写 `config.d/models.json`
+ *    (都在它对 models.json 的那把锁里),迁移先建运行记录、再铸决定。
+ *  · **一份读法、一张闭集答案表**:决定只有 {@link EnvModelsDecision} 这一种答案(从字节读出的带同一次读的 `digest`,读不到字节的带 `errno`),
+ *    读这份决定的三方 —— 引擎(本地配置腿强制这道闸之后;今天引擎还不读它)、一次性迁移 SS-M11、写者的计划助手 —— 吃同一个答案;它的身份(告警去重键、本地 etag 的贡献)只有一种拼法 {@link envModelsDecisionTag}。
+ *  · **运行记录按 id 一份**:「迁移 X 跑过」⇔ `<根>/config.migration.<X>.json` 在场({@link MigrationMarker});没有聚合文件、没有追加写;
+ *    读不懂的记录按「跑过」处置(fail-closed)。记录由迁移以「不存在才建」写:同一个 id 只有一个进程建得成 —— 它是那条迁移在本根上唯一的执行者。
+ *  · 两份文档的形都是 strict 的:多一个键(含自有 `__proto__`)、拼错的词都读成 `bad_shape`,不剥、不猜;digest 对读到的**字节**求。名字只在这里定一次(引擎的目录信任判官取 {@link CONFIG_ROOT_DOCUMENTS})。
+ */
+import type { OneTimeMigrationId } from "./migration-receipt.js";
+/** 配置根上的 env 模型表决定文档的名字(文件 `<根>/config.env-models.json`)。 */
+export declare const ENV_MODELS_DOCUMENT: "config.env-models";
+/** 运行记录文档名的前缀(包内:名字 = 前缀 + 迁移 id,文件 = 名字 + `.json`)。 */
+declare const MIGRATION_MARKER_PREFIX: "config.migration.";
+/** 一条一次性迁移的运行记录文档名(包内)。 */
+export declare const migrationMarkerDocument: <I extends OneTimeMigrationId>(id: I) => `${typeof MIGRATION_MARKER_PREFIX}${I}`;
+/**
+ * 根级文档名单(闭集、序固定;文件 = 名字 + `.json`,与 `config.d` 文档同一拼法):决定文档,与今天唯一会写运行记录的迁移 SS-M11 的那一份。
+ * 引擎对配置根的目录信任判官、客户端的持久文件登记都取这一张,不手抄。判法与 `config.d` 里的文档**同一条律**(属主可信、路径上非链接组件不得组 / 他人可写、
+ * 常规文件、有大小上界)—— 一条律、两张名单(`config.d` 读回面一张,本张一张);`config.d` 不在时也照判。
+ * `<根>/.env` **不在**这张名单:引擎今天的目录信任判官只判 `config.d` 与它的读回面,不判 `.env`(秘密值文件,本包的文件仓库不读它);本名单只登记引擎会读的根级文档。
+ */
+export declare const CONFIG_ROOT_DOCUMENTS: readonly ["config.env-models", "config.migration.SS-M11"];
+export type ConfigRootDocument = (typeof CONFIG_ROOT_DOCUMENTS)[number];
+/** 有运行记录的迁移 id(由 {@link CONFIG_ROOT_DOCUMENTS} 派生:名单里有它的记录文档 ⇔ 它写记录)。 */
+export type MarkedMigrationId = {
+    [I in OneTimeMigrationId]: `${typeof MIGRATION_MARKER_PREFIX}${I}` extends ConfigRootDocument ? I : never;
+}[OneTimeMigrationId];
+/** 包内:`id` 是写运行记录的迁移吗(读运行记录之前判:别的 id 没有记录可读,更不许拿它拼路径)。 */
+export declare const isMarkedMigrationId: (id: unknown) => id is MarkedMigrationId;
+/** 决定文档里能写的两个词(闭集):`replaced` = 目录管模型面时顶替 env 模型表;`kept` = 不顶替(与缺席同义,运行记录在场之后)。 */
+export declare const ENV_MODELS_DECISIONS: readonly ["replaced", "kept"];
+export type EnvModelsDecisionWord = (typeof ENV_MODELS_DECISIONS)[number];
+/** 包内:是不是决定词(闭集,判法只此一只;写函数与读法同调)。 */
+export declare const isDecisionWord: (v: unknown) => v is EnvModelsDecisionWord;
+/** 根级文档读不懂的三种原因(闭集):`bad_json` = 空 / 纯空白 / 不是 JSON;`bad_shape` = 是 JSON 但不是这份文档的形;`io` = 字节读不出(权限 —— 可信属主的 0000 文件读恒 `EACCES`,是持久的 —— 不是常规文件、悬空链接、瞬时读错)。 */
+export declare const ROOT_DOCUMENT_UNREADABLE_REASONS: readonly ["bad_json", "bad_shape", "io"];
+export type RootDocumentUnreadableReason = (typeof ROOT_DOCUMENT_UNREADABLE_REASONS)[number];
+/**
+ * 决定文档的读数(闭集;三方穷举 `switch`)。`absent` 只在文件不存在时答 —— 读不出的字节是 `unreadable`,不是缺席。
+ * 有字节的四臂(`replaced` / `kept` / `unreadable{bad_json|bad_shape}`)带 `digest` = **同一次读**得到的字节的 SHA-256 前 16 位十六进制;
+ * 读不到字节的 `unreadable{io}` 带 `errno`(错误上没有 errno ⇒ `uncoded`)。`{` 改成 `[` 这种「答案同为 bad_json、字节不同」的改动 digest 也变。digest 不可逆,不带内容。
+ */
+export type EnvModelsDecision = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "replaced";
+    readonly digest: string;
+} | {
+    readonly kind: "kept";
+    readonly digest: string;
+} | {
+    readonly kind: "unreadable";
+    readonly reason: "bad_json" | "bad_shape";
+    readonly digest: string;
+} | {
+    readonly kind: "unreadable";
+    readonly reason: "io";
+    readonly errno: string;
+};
+/**
+ * 一份决定读数的**身份**(带标签的一种拼法):`absent` / `d:<digest>`(有字节的四臂)/ `io:<errno>`。引擎读这份决定时(今天引擎还不读),「每份内容只告警一次」的去重键与本地 etag 的贡献都取它 ——
+ * 来自同一次读,不再开文件(那就是第二个读者)。
+ */
+export declare function envModelsDecisionTag(decision: EnvModelsDecision): string;
+/** 一份运行记录的读数(闭集):`present` = 那条迁移跑过(或正被它的执行者跑);读不懂的按「跑过」处置(fail-closed)。 */
+export type MigrationMarker = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "present";
+} | {
+    readonly kind: "unreadable";
+    readonly reason: RootDocumentUnreadableReason;
+};
+/** 包内:决定文档的**字节读法**(唯一一份;`./config-root-node` 的读者在拿到字节之后调它)—— 字节 → 答案(带这些字节的 digest)。 */
+export declare function readEnvModelsDecisionBytes(bytes: Uint8Array): Exclude<EnvModelsDecision, {
+    readonly kind: "absent";
+} | {
+    readonly reason: "io";
+}>;
+/** 包内:字节没读到时的决定读数(errno 的拼法只在本文件)。 */
+export declare function ioDecision(errno: string | undefined): Extract<EnvModelsDecision, {
+    readonly reason: "io";
+}>;
+/** 包内:运行记录文档的值(`{"migration":<id>}`,写与读同一只形)。 */
+export declare const migrationMarkerValue: (id: MarkedMigrationId) => {
+    readonly migration: MarkedMigrationId;
+};
+/** 包内:运行记录的**字节读法**(唯一一份):`{"migration":<这条记录的 id>}` strict ⇒ `present`;别的 ⇒ 读不懂(id 对不上也是坏形)。 */
+export declare function readMigrationMarkerBytes(id: MarkedMigrationId, bytes: Uint8Array): MigrationMarker;
+/** 包内:字节 → 文本(`config.d/models.json` 的读也经它,与上面两份同一解码)。 */
+export declare const decodeRootBytes: (bytes: Uint8Array) => string;
+export {};

package/dist/config-root-documents.js

@@ -0,0 +1,93 @@
+import { isPlainJsonObject } from "./plain-json-object.js";
+import { sha256Digest, toHex } from "./sha256-core.js";
+/** 配置根上的 env 模型表决定文档的名字(文件 `<根>/config.env-models.json`)。 */
+export const ENV_MODELS_DOCUMENT = "config.env-models";
+/** 运行记录文档名的前缀(包内:名字 = 前缀 + 迁移 id,文件 = 名字 + `.json`)。 */
+const MIGRATION_MARKER_PREFIX = "config.migration.";
+/** 一条一次性迁移的运行记录文档名(包内)。 */
+export const migrationMarkerDocument = (id) => `${MIGRATION_MARKER_PREFIX}${id}`;
+/**
+ * 根级文档名单(闭集、序固定;文件 = 名字 + `.json`,与 `config.d` 文档同一拼法):决定文档,与今天唯一会写运行记录的迁移 SS-M11 的那一份。
+ * 引擎对配置根的目录信任判官、客户端的持久文件登记都取这一张,不手抄。判法与 `config.d` 里的文档**同一条律**(属主可信、路径上非链接组件不得组 / 他人可写、
+ * 常规文件、有大小上界)—— 一条律、两张名单(`config.d` 读回面一张,本张一张);`config.d` 不在时也照判。
+ * `<根>/.env` **不在**这张名单:引擎今天的目录信任判官只判 `config.d` 与它的读回面,不判 `.env`(秘密值文件,本包的文件仓库不读它);本名单只登记引擎会读的根级文档。
+ */
+export const CONFIG_ROOT_DOCUMENTS = [ENV_MODELS_DOCUMENT, migrationMarkerDocument("SS-M11")];
+/** 包内:`id` 是写运行记录的迁移吗(读运行记录之前判:别的 id 没有记录可读,更不许拿它拼路径)。 */
+export const isMarkedMigrationId = (id) => typeof id === "string" && CONFIG_ROOT_DOCUMENTS.includes(`${MIGRATION_MARKER_PREFIX}${id}`);
+/** 决定文档里能写的两个词(闭集):`replaced` = 目录管模型面时顶替 env 模型表;`kept` = 不顶替(与缺席同义,运行记录在场之后)。 */
+export const ENV_MODELS_DECISIONS = ["replaced", "kept"];
+/** 包内:是不是决定词(闭集,判法只此一只;写函数与读法同调)。 */
+export const isDecisionWord = (v) => ENV_MODELS_DECISIONS.includes(v);
+/** 根级文档读不懂的三种原因(闭集):`bad_json` = 空 / 纯空白 / 不是 JSON;`bad_shape` = 是 JSON 但不是这份文档的形;`io` = 字节读不出(权限 —— 可信属主的 0000 文件读恒 `EACCES`,是持久的 —— 不是常规文件、悬空链接、瞬时读错)。 */
+export const ROOT_DOCUMENT_UNREADABLE_REASONS = ["bad_json", "bad_shape", "io"];
+/**
+ * 一份决定读数的**身份**(带标签的一种拼法):`absent` / `d:<digest>`(有字节的四臂)/ `io:<errno>`。引擎读这份决定时(今天引擎还不读),「每份内容只告警一次」的去重键与本地 etag 的贡献都取它 ——
+ * 来自同一次读,不再开文件(那就是第二个读者)。
+ */
+export function envModelsDecisionTag(decision) {
+    switch (decision.kind) {
+        case "absent":
+            return "absent";
+        case "replaced":
+        case "kept":
+            return `d:${decision.digest}`;
+        case "unreadable":
+            return decision.reason === "io" ? `io:${decision.errno}` : `d:${decision.digest}`;
+        default: {
+            const unhandled = decision;
+            throw new Error(`envModelsDecisionTag: unhandled decision ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/** 同一次读得到的**字节**的 digest(见 {@link EnvModelsDecision};对字节求,不对解码后的文本 —— 非法 UTF-8 解码成 U+FFFD 之后不同的字节会同 digest)。 */
+const digestOf = (bytes) => toHex(sha256Digest(bytes)).slice(0, 16);
+/** 字节 → 文本(UTF-8;非法序列换 U+FFFD;BOM 留在文本里,由 {@link parseJsonText} 的 trim 去掉 —— 与 `config.d` 文档的文本读法同一结果)。 */
+const textOf = (bytes) => new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
+/**
+ * 一个 JSON 值若是「恰好这一个自有键」的纯对象 ⇒ 那个键的值;否则(多一个键 —— 含 `JSON.parse` 铸出的自有 `__proto__` 键 —— 少一个键、不是纯对象)⇒ `undefined`。
+ * 两份文档的形都是 strict 的,判在这里一处;不交给 zod 的 strict:它对自有 `__proto__` 键的处置随版本变(4.4.x 跳过它、4.6.x 拒它),本包的 zod 区间两端答案会不同。
+ * 文档是 `JSON.parse` 的产物,自有键都是可枚举数据属性,`Object.keys` 就是它的全部键。
+ */
+function soleOwnValue(v, key) {
+    if (!isPlainJsonObject(v))
+        return undefined;
+    const keys = Object.keys(v);
+    return keys.length === 1 && keys[0] === key ? v[key] : undefined;
+}
+/** 文本 → JSON 值:空 / 纯空白 / 坏 JSON ⇒ 读不成(一份被截断的文件不是缺席)。 */
+function parseJsonText(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return { ok: false };
+    try {
+        return { ok: true, value: JSON.parse(trimmed) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** 包内:决定文档的**字节读法**(唯一一份;`./config-root-node` 的读者在拿到字节之后调它)—— 字节 → 答案(带这些字节的 digest)。 */
+export function readEnvModelsDecisionBytes(bytes) {
+    const digest = digestOf(bytes);
+    const json = parseJsonText(textOf(bytes));
+    if (!json.ok)
+        return { kind: "unreadable", reason: "bad_json", digest };
+    const word = soleOwnValue(json.value, "envModels");
+    return isDecisionWord(word) ? { kind: word, digest } : { kind: "unreadable", reason: "bad_shape", digest };
+}
+/** 包内:字节没读到时的决定读数(errno 的拼法只在本文件)。 */
+export function ioDecision(errno) {
+    return { kind: "unreadable", reason: "io", errno: errno ?? "uncoded" };
+}
+/** 包内:运行记录文档的值(`{"migration":<id>}`,写与读同一只形)。 */
+export const migrationMarkerValue = (id) => ({ migration: id });
+/** 包内:运行记录的**字节读法**(唯一一份):`{"migration":<这条记录的 id>}` strict ⇒ `present`;别的 ⇒ 读不懂(id 对不上也是坏形)。 */
+export function readMigrationMarkerBytes(id, bytes) {
+    const json = parseJsonText(textOf(bytes));
+    if (!json.ok)
+        return { kind: "unreadable", reason: "bad_json" };
+    return soleOwnValue(json.value, "migration") === id ? { kind: "present" } : { kind: "unreadable", reason: "bad_shape" };
+}
+/** 包内:字节 → 文本(`config.d/models.json` 的读也经它,与上面两份同一解码)。 */
+export const decodeRootBytes = textOf;

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>;