@sema-agent/settings-schema 14.6.0 → 14.8.0

package/dist/config-fns.js

@@ -17,7 +17,9 @@
 // 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 { 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";
 import { unwrapSchema } from "./zod-unwrap.js"; // package-private: the ONE reading of zod's wrapper layers (salvage + the one-time migrations share it)
@@ -103,12 +105,12 @@ function boundIssueIdentifiers(rec) {
             changed.set(v, out);
         return out;
     };
-    if (Array.isArray(rec.path))
+    if (isJsonArray(rec.path))
         rec.path = rec.path.map(bound);
-    if (Array.isArray(rec.keys))
+    if (isJsonArray(rec.keys))
         rec.keys = rec.keys.map(bound);
     const params = rec.params;
-    if (params !== undefined && Array.isArray(params.template) && Array.isArray(params.operands)) {
+    if (params !== undefined && isJsonArray(params.template) && isJsonArray(params.operands)) {
         const quoted = { template: params.template, operands: params.operands.map((o) => bound(o)) };
         rec.params = { ...params, ...quoted };
         rec.message = renderQuotedSentence(quoted);
@@ -124,14 +126,31 @@ function sanitizeIssueValue(v, depth) {
         return redactSecrets(v);
     if (typeof v === "symbol")
         return redactSecrets(String(v));
-    if (v === null || typeof v !== "object")
-        return v;
-    if (depth > SANITIZE_MAX_DEPTH)
-        return "[redacted-secret]";
-    if (Array.isArray(v))
-        return v.map((el) => sanitizeIssueValue(el, depth + 1));
-    sanitizeIssueFields(v, depth);
-    return v;
+    const shape = jsonShapeOf(v);
+    switch (shape) {
+        case "null":
+        case "primitive":
+            return v;
+        case "uninspectable":
+            return "[redacted-secret]"; // a value the walk cannot read is withheld, like one the depth bound does not reach
+        case "array": {
+            if (depth > SANITIZE_MAX_DEPTH)
+                return "[redacted-secret]";
+            const items = inspect(() => v.map((el) => sanitizeIssueValue(el, depth + 1))); // a member that cannot be read (a getter / trap that throws) ⇒ the whole value is withheld
+            return items.ok ? items.value : "[redacted-secret]";
+        }
+        case "plain":
+        case "non_plain_object": {
+            if (depth > SANITIZE_MAX_DEPTH)
+                return "[redacted-secret]";
+            const walked = inspect(() => sanitizeIssueFields(v, depth)); // same: a member read or write that throws ⇒ the whole value is withheld
+            return walked.ok ? v : "[redacted-secret]";
+        }
+        default: {
+            const unhandled = shape;
+            throw new Error(`sanitizeIssueValue: unhandled shape ${String(unhandled)}`);
+        }
+    }
 }
 export const ROLE_RANK = { viewer: 0, editor: 1, publisher: 2, admin: 3 };
 export const USER_ROLES = ["viewer", "editor", "publisher", "admin"];
@@ -181,7 +200,7 @@ export const DOMAIN_WRITE_ROLE = {
 };
 /** The minimum role required to write `domain` (the raised gate for skills/mcp, else editor). */
 export function domainWriteRole(domain) {
-    return DOMAIN_WRITE_ROLE[domain] ?? DEFAULT_DOMAIN_WRITE_ROLE;
+    return ownRow(DOMAIN_WRITE_ROLE, domain) ?? DEFAULT_DOMAIN_WRITE_ROLE;
 }
 /** The empty/defaults effective config at version 0 — what publish mode serves before the first publish.
  *  Seeds the epoch (`new Date(0)`) so it's deterministic (the wall-clock default was the original store.ts
@@ -230,17 +249,20 @@ export function parseDomain(domain, raw) {
         throw new Error(`"${outgoingSegment(String(domain))}" is not a config domain`);
     // ONLY true absence (undefined) defaults; an explicit `null` (e.g. a `config.d/<d>.json` containing JSON
     // `null`) is corrupt input → let zod reject it ("expected object, received null"), not silently default. R4.
-    let r;
-    try {
-        r = DOMAIN_SCHEMAS[domain].safeParse(raw === undefined ? {} : raw);
-    }
-    catch {
-        // a hostile getter/Proxy trap threw during traversal — its message may carry a secret; never surface it. R13.
-        throw new Error(`invalid "${domain}" config (a value could not be read during validation)`);
-    }
-    if (r.success)
-        return r.data;
-    throw sanitizeZodError(r.error); // recursive redaction (message / every issue field / nested issues) — no secret echo. R13/R14.
+    return strictParse(DOMAIN_SCHEMAS[domain], domain, raw === undefined ? emptyDocument() : raw);
+}
+/**
+ * 一次**整份严判**(域文档与 wire 上的 skills 清单共用这一只 —— 清单的读法与非门控域同一臂,见 `readSkillsManifest`):过 ⇒ 数据;
+ * 不过 ⇒ 抛脱敏后的 ZodError(逐字段递归脱敏,不回显秘密;R13/R14);校验过程抛(含首读 `error` 时抛,见 {@link guardedSafeParse})⇒ 抛 {@link unreadableDomainError}
+ * (抛出值的文案可能带秘密,从不转述;R13)。
+ */
+function strictParse(schema, label, doc) {
+    const judged = guardedSafeParse(() => schema.safeParse(doc), sanitizeZodError);
+    if (!judged.ok)
+        throw unreadableDomainError(label);
+    if (judged.value.success)
+        return judged.value.data;
+    throw judged.value.error;
 }
 /** 一个**逐字出门**的字符串段的样子 —— 一条判据,不是一串特例:**逐字写出去之后读回来只能是它自己**。
  *  所以四类字符串段必须改走引号形:空串、含 `.`(段分隔符)、含 `"`(引号形自身)或控制字符的,以及
@@ -341,22 +363,23 @@ 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))
             return undefined;
         const own = (k) => {
             const d = Object.getOwnPropertyDescriptor(entry, k);
-            return d !== undefined && Object.hasOwn(d, "value") ? d.value : undefined; // 描述符本身也只读自有键
+            return d !== undefined && !isAccessorDescriptor(d) ? d.value : undefined; // 访问器不调(描述符的字段只认自有的,见内核)
         };
         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;
     }
@@ -385,17 +408,18 @@ function droppedEntry(path, verdict, entry) {
 }
 /** 一次「什么都没丢」的抢救的位移表(冻结的共享空表 —— {@link rebaseWarningPaths} 对它恒等)。 */
 const NO_ENTRIES_DROPPED = Object.freeze({});
+/** 一个域的校验过程抛了(恶意 getter / Proxy 陷阱 / 校验器自己对怪形值做类型转换)⇒ 给调用方的那一句中性话:不带抛出值的文案(可能带 secret),类是 `TypeError`(调用方给的值读不出是调用方的错)。 */
+function unreadableDomainError(domain) {
+    return new TypeError(`invalid "${domain}" config (a value could not be read during validation)`);
+}
 /** 一条条目的 parse —— 坏就返回它的判决(脱敏错误 + 闭集词)。`rejectedAs` = 调用点在集合里的位置赋予「schema 没过」的那个词
  *  (条目 / Record 值 ⇒ `entry-schema-invalid`;Record 键 ⇒ `entry-key-invalid`);判的过程抛了则恒为 `entry-unreadable`,与位置无关。
  *  恶意 getter/Proxy 在遍历中抛错时**绝不**外泄其文案(可能带 secret,与 parseDomain 的 R13 同纪律),只留一句中性话。 */
 function judgeEntry(schema, value, rejectedAs) {
-    try {
-        const r = schema.safeParse(value);
-        return r.success ? undefined : { error: sanitizeZodError(r.error), reasonCode: rejectedAs };
-    }
-    catch {
-        return { error: new Error("entry could not be read during validation"), reasonCode: "entry-unreadable" };
-    }
+    const judged = guardedSafeParse(() => schema.safeParse(value), sanitizeZodError); // 脱敏也在守护里:issue 读不完(`params` 里会抛的 getter)⇒ 这一条读不出(v14.6.0 同)
+    if (!judged.ok)
+        return { error: new TypeError("entry could not be read during validation"), reasonCode: "entry-unreadable" }; // 同一原因(校验时值读不出)一种错类:与 `domain-defaulted` 告警的 error 同为 TypeError
+    return judged.value.success ? undefined : { error: judged.value.error, reasonCode: rejectedAs };
 }
 /**
  * 从**schema 自身**派生条目集合(数组字段 / Record 字段),逐条判,坏的丢掉并逐条记账。
@@ -441,12 +465,8 @@ export function salvageEntries(schema, raw) {
 /** 一层抢救,抢不动就当没抢救(反射 / 访问器抛错:绝不外泄其文案)。最外层与每一条条目体内走的是**同一只** —— 一条条目体内抢不动,
  *  只是这一条不下钻、照原样去判,不连坐它所在的那一层。 */
 function salvageLayer(schema, raw) {
-    try {
-        return salvageLayerUnsafe(schema, raw);
-    }
-    catch {
-        return { raw, dropped: [], shifts: [] };
-    }
+    const layer = inspect(() => salvageLayerUnsafe(schema, raw));
+    return layer.ok ? layer.value : { raw, dropped: [], shifts: [] };
 }
 /** 集合字段的值 → 它的位置表;值的形与 schema 对不上(schema 说数组、文档给对象)⇒ `undefined`(不抢救,交给整域档位)。
  *  数组走 `forEach`(不是手写 `for (i < value.length)`):它在**进入时**就钉死了长度,而重读 `value.length` 会跟着一个在校验期间
@@ -454,7 +474,7 @@ function salvageLayer(schema, raw) {
  *  位置表在任何判定之前就收齐了,之后数组再怎么长都与本次抢救无关。`forEach` 跳过空洞,与此前的 `filter` 同。 */
 function collectionSlots(value, isArray) {
     if (isArray) {
-        if (!Array.isArray(value))
+        if (!isJsonArray(value))
             return undefined;
         const slots = [];
         value.forEach((entry, i) => void slots.push([i, entry]));
@@ -478,7 +498,10 @@ function salvageLayerUnsafe(schema, raw) {
         const isArray = collection instanceof z.ZodArray;
         if (!isArray && !(collection instanceof z.ZodRecord))
             continue; // 不是条目集合:连读都不读(少触发一次访问器)
-        const slots = collectionSlots(raw[field], isArray);
+        const held = ownValueOf(raw, field); // the field is read from the document's OWN keys (a polluted `Object.prototype.<field>` is not a collection the document holds); unreadable ⇒ nothing to salvage here
+        if (!held.ok)
+            return untouched;
+        const slots = collectionSlots(held.value, isArray);
         if (slots === undefined)
             continue;
         const element = (collection instanceof z.ZodArray ? collection.element : collection.valueType);
@@ -729,13 +752,13 @@ export const EXTENSION_NAMESPACES = {
  *  本身——键名里可以含 `.`(`semaX.foo` 是一个键不是两层),段形让这件事不必再靠文法猜;前缀契约就是前缀
  *  契约(`semaGPT_5` / `semaX-v2` 都是成员,后缀不设未声明的文法)。 */
 export function isReservedExtensionKey(domain, parent, key) {
-    const rules = EXTENSION_NAMESPACES[domain];
+    const rules = ownRow(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));
 }
 function collectDropped(domain, raw, parsed, prefix, depth, acc) {
     if (depth > DROP_SCAN_MAX_DEPTH)
         return;
-    if (Array.isArray(raw) && Array.isArray(parsed)) {
+    if (isJsonArray(raw) && isJsonArray(parsed)) {
         // 长度不同 = 整条元素被丢(`entry-dropped` 有自己的警告),不在本判据内,别造重复噪声。
         if (raw.length !== parsed.length)
             return;
@@ -818,13 +841,18 @@ const OPEN_WORLD_KNOWN_KEYS = {
  * 子树)不再下探,那本就是消费方自定义的内容,逐层猜没有意义。
  */
 function carriedUnknownKeys(domain, parsed) {
-    const table = OPEN_WORLD_KNOWN_KEYS[domain];
+    const table = ownRow(OPEN_WORLD_KNOWN_KEYS, domain);
     const acc = { keys: [], total: 0 };
     if (table === undefined)
         return acc;
     for (const [at, known] of table) {
         // 段形下探:`[]` 落在文档根上,所以「顶层 vs 嵌套」不再是两条分支(规则少一条)。
-        const node = at.reduce((cur, seg) => (isPlainJsonObject(cur) ? cur[String(seg)] : undefined), parsed);
+        const node = at.reduce((cur, seg) => {
+            if (!isPlainJsonObject(cur))
+                return undefined;
+            const read = ownValueOf(cur, String(seg));
+            return read.ok ? read.value : undefined;
+        }, parsed);
         if (!isPlainJsonObject(node))
             continue;
         for (const k of Object.keys(node)) {
@@ -892,16 +920,7 @@ function readDomainDocument(domain, raw, onWarning, whenUnreadable) {
 function parseSalvaged(domain, raw, unreadable, onWarning) {
     if (DOMAIN_ENTRY_SALVAGE[domain] !== "salvage")
         throw unreadable;
-    const salvage = salvageEntries(DOMAIN_SCHEMAS[domain], raw);
-    if (salvage.dropped.length === 0)
-        throw unreadable;
-    let parsed;
-    try {
-        parsed = parseDomain(domain, salvage.raw);
-    }
-    catch {
-        throw unreadable; // 条目之外还有毛病(重名 / 悬空 ref / 域级判据)—— 丢条目救不了它
-    }
+    const { parsed, salvage } = salvageThenParse(DOMAIN_SCHEMAS[domain], raw, (doc) => parseDomain(domain, doc), unreadable);
     if (onWarning) {
         // 坐标律(S-323b):一条告警用「铸它的那一层所见文档」的坐标表达;哪一层压缩了文档,哪一层就把从它下方上来的告警回写一次。
         // `entry-dropped` 是本层(salvage)铸的,用的就是本层入参那份文档的坐标 ⇒ 原样出门;未知键扫描是对本层**压缩后**文档的诊断 ⇒ 过本层的位移表。
@@ -911,6 +930,23 @@ function parseSalvaged(domain, raw, unreadable, onWarning) {
     }
     return parsed;
 }
+/**
+ * 逐条抢救的**那一步**(域面 {@link parseSalvaged} 与 wire 面 skills 清单 `readSkillsManifest` 共用 —— 一条律,两个调用点):整份严判已经失败
+ * (校验不过,或校验过程抛 —— 同一条臂:{@link salvageEntries} 逐条判,抛的那一条记 `entry-unreadable` 丢它自己)之后,丢掉坏条目再严判一次。
+ * 什么都没丢 / 丢了仍读不进(条目之外还有毛病:重名 / 悬空 ref / 域级判据;或抢救后的文档在重判时读不出)⇒ 抛 `unreadable`(第一次严判的原错)——
+ * 一个文档一个结论,没救活就不留「丢了某条」的半路叙述。
+ */
+function salvageThenParse(schema, raw, parse, unreadable) {
+    const salvage = salvageEntries(schema, raw);
+    if (salvage.dropped.length === 0)
+        throw unreadable;
+    try {
+        return { parsed: parse(salvage.raw), salvage };
+    }
+    catch {
+        throw unreadable;
+    }
+}
 /** 未知键两条告警(剥掉的 / 承运的)—— `raw` 是这次真被 parse 的那份文档,`emit` 决定坐标出门前要不要回写。 */
 function announceUnknownKeys(domain, raw, parsed, emit) {
     const dropped = droppedKeys(domain, raw, parsed);
@@ -1098,9 +1134,31 @@ 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 (!isPlainJsonObject(raw))
-        throw new Error("effective wire payload is not a JSON object");
-    const r = raw;
+    // 判形只问座位:读不出(撤销的 Proxy / 陷阱抛)是「读不出」—— 与下面读键读不出同一类同一句,不是「不是对象」;不是对象(null / 数组 / 原始值 / 类实例)才是既有的那句
+    const rawShape = jsonShapeOf(raw);
+    switch (rawShape) {
+        case "plain":
+            break;
+        case "uninspectable":
+            throw new TypeError(`effective wire payload could not be read — ${UNINSPECTABLE}`);
+        case "non_plain_object":
+        case "array":
+        case "null":
+        case "primitive":
+            throw new Error("effective wire payload is not a JSON object");
+        default: {
+            const unhandled = rawShape;
+            throw new Error(`readEffectiveWire: unhandled shape ${String(unhandled)}`);
+        }
+    }
+    // 载荷只读一次,读成它自有的键值快照(隔离原型 `COPY_PROTOTYPE` 的袋):信封键(`version` / `updatedAt`)、域键、`skills` / `prompts` 与未知键都从快照里取 ——
+    // 键只靠继承可见(`Object.prototype.models` 被污染成数据值)不算载荷里写着的;读不出(`get` 陷阱 / 会抛的 getter)⇒ 抛本函数自己的那一句,不是引擎的错
+    const entries = ownEntriesOf(raw); // 自有串键里有不可枚举的 ⇒ 整份读不出(不当缺席、不静默丢)
+    if (!entries.ok)
+        throw new TypeError(`effective wire payload could not be read — ${entries.sentence}`);
+    const r = isolatedObject(); // 载荷的袋:与所有副本同一只原型
+    for (const [k, v] of entries.value)
+        Object.defineProperty(r, k, dataDescriptor(v));
     if (typeof r.version !== "number" || !Number.isFinite(r.version))
         throw new Error("effective wire payload has no numeric version");
     const updatedAt = typeof r.updatedAt === "string" ? r.updatedAt : "";
@@ -1112,26 +1170,12 @@ export function readEffectiveWire(raw, onWarning) {
     // downstream as "the center withdrew its layer" — the consumer's judge refuses it loudly instead. verbatim, by presence(见 return)。
     const built = buildEffective(r.version, (d) => (d === "skills" || d === "prompts" ? undefined : r[d]), updatedAt, onWarning);
     // retired 域名不是 open-world 的未知键:墓碑已在 buildEffective 里判过(带事实 ⇒ 抛),剩下的 `{}` 没有可承运的东西。
-    let skills;
-    const manifest = SkillsManifestSchema.safeParse(r.skills ?? {});
-    if (manifest.success) {
-        skills = manifest.data;
-    }
-    else {
-        // 逐条容错律的 wire 腿:manifest 走的是另一张 schema,但**同一个**抢救点 —— 一条坏条目只丢它自己,
-        // 整张 skill 清单不再因此蒸发(零幸存者仍整份退默认,见 salvageEntries 头注)。
-        const salvage = salvageEntries(SkillsManifestSchema, r.skills);
-        const retry = salvage.dropped.length > 0 ? SkillsManifestSchema.safeParse(salvage.raw) : undefined;
-        if (retry?.success) {
-            for (const d of salvage.dropped)
-                onWarning?.(entryDroppedWarning("skills", d));
-            skills = retry.data;
-        }
-        else {
-            onWarning?.({ domain: "skills", kind: "domain-defaulted", error: sanitizeZodError(manifest.error) });
-            skills = { skills: [] };
-        }
-    }
+    const manifest = readSkillsManifest(r.skills);
+    // 告警在判完之后、读法之外发:`onWarning` 自己抛的错不会被当成「清单读不进」
+    if (onWarning)
+        for (const w of manifest.warnings)
+            onWarning(w);
+    const skills = manifest.skills;
     // Open-world passthrough: keys that are neither validated domains nor the envelope fields ride verbatim.
     // `hasOwnProperty.call(built, k)`,**不是** `k in built`(S-332):`in` 会一路问到 `Object.prototype`,
     // 于是 `constructor` / `toString` / `hasOwnProperty` / `__proto__` 这些**原型链上的名字**作未知顶层键时
@@ -1143,7 +1187,29 @@ export function readEffectiveWire(raw, onWarning) {
     // prompts:剥掉 buildEffective 恒物化的 `{}` 底座,按 wire 在场性 verbatim 挂回(#100:
     // 缺席进缺席出——发布闸关是常态形,物化会让消费端「缺席」分支永不可达)。
     const { prompts: _promptsMaterialized, ...builtSansPrompts } = built;
-    return { ...passthrough, ...builtSansPrompts, skills, ...("prompts" in r ? { prompts: r.prompts } : {}) };
+    return { ...passthrough, ...builtSansPrompts, skills, ...(Object.hasOwn(r, "prompts") ? { prompts: r.prompts } : {}) };
+}
+/**
+ * wire 上 skills 清单的读法 —— **与非门控域同一臂**,只是判的是清单 schema({@link SkillsManifestSchema}):整份严判({@link strictParse})→ 读不进
+ * (校验不过,或校验器自己抛 —— 合法 JSON 里的怪形值、嵌入方对象的 getter / 陷阱 —— 同一条臂)⇒ 逐条抢救({@link salvageThenParse}:坏条目丢它自己 + `entry-dropped`,
+ * 其余合法条目保留;零幸存者不凭空造空集合)→ 仍读不进 ⇒ 整份退默认(空清单)+ `domain-defaulted`(`error` = 第一次严判的原错:脱敏的 ZodError,或包自己那一句的 TypeError)。
+ * 缺席 ⇒ 按包自己造的空文档判(`COPY_PROTOTYPE`,读不到污染值)。告警交回给调用方发。
+ */
+function readSkillsManifest(raw) {
+    const parse = (doc) => strictParse(SkillsManifestSchema, "skills", doc);
+    try {
+        return { skills: parse(raw ?? emptyDocument()), warnings: [] };
+    }
+    catch (unreadable) {
+        try {
+            const { parsed, salvage } = salvageThenParse(SkillsManifestSchema, raw, parse, unreadable);
+            return { skills: parsed, warnings: salvage.dropped.map((d) => entryDroppedWarning("skills", d)) };
+        }
+        catch {
+            // 救不回 ⇒ 告警带第一次严判的原错(salvageThenParse 只重抛它;salvageEntries 是总的)—— 在结构上就是它,不靠「被捕获的恰好是它」
+            return { skills: { skills: [] }, warnings: [{ domain: "skills", kind: "domain-defaulted", error: unreadable }] };
+        }
+    }
 }
 /** 档位组→引擎单表的唯一解析点(0.9.0)。返回 ACTIVE 档位组的绑定表(剔除未绑档),即 core
  *  `RunnerDeps.tiers` 要吃的那张单表——组切换=web-admin 换这张表下发,零新引擎机制。无 active 组/未命中/

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;