@sema-agent/settings-schema 2.0.0 → 3.0.0

package/dist/config-fns.js

@@ -157,6 +157,24 @@ function unwrapSchema(schema) {
     }
     return cur;
 }
+/** 一个**逐字出门**的字符串段的样子 —— 一条判据,不是一串特例:**逐字写出去之后读回来只能是它自己**。
+ *  所以四类字符串段必须改走引号形:空串、含 `.`(段分隔符)、含 `"`(引号形自身)或控制字符的,以及
+ *  **文本恰好是某个数字段会出成的样子**(规范十进制)—— 一个字面叫 `"1"` 的对象键若逐字出门,就与下标
+ *  `1` 同形,而「这一段是下标还是键名」正是本版改铸要带回来的那个位。(`"01"` 不是任何数字段的文本,
+ *  照旧逐字。) */
+const PLAIN_PATH_SEGMENT = /^(?!(?:0|[1-9]\d*)$)[^."\u0000-\u001f]+$/;
+/** 一条 {@link ConfigPath} 的出门形(日志 / UI / 人读的告警文本)—— 本包**唯一**的 stringify 点,
+ *  消费方零复述。段间 `.`;数字段十进制;字符串段{@link PLAIN_PATH_SEGMENT 能逐字出门}就逐字,否则按
+ *  JSON 字符串字面量加引号(`models.1."a.b"` / `models."1".k`)—— 不加引号的话,含点的键段会与数组路径
+ *  出成同一个串、字面叫 `"1"` 的键会与下标 `1` 同形,那正是 S-323c 要消掉的二义。
+ *
+ *  **刻意不提供 parse 反函数**:2.1.0 起没有任何一处把坐标读回来(回写走 `keptIndex` 那本账),给它
+ *  一个反函数就是给下一个人一条「在串上做事」的路。 */
+export function formatConfigPath(p) {
+    return p.map((seg) => (typeof seg === "number" ? String(seg) : PLAIN_PATH_SEGMENT.test(seg) ? seg : JSON.stringify(seg))).join(".");
+}
+/** 一次「什么都没丢」的抢救的位移表(冻结的共享空表 —— {@link rebaseWarningPaths} 对它恒等)。 */
+const NO_ENTRIES_DROPPED = Object.freeze({});
 /** 一条条目的 parse —— 坏就返回它的(脱敏)错误。恶意 getter/Proxy 在遍历中抛错时**绝不**外泄其文案
  *  (可能带 secret,与 parseDomain 的 R13 同纪律),只留一句中性话。 */
 function judgeEntry(schema, value) {
@@ -201,18 +219,19 @@ export function salvageEntries(schema, raw) {
         return salvageEntriesUnsafe(schema, raw);
     }
     catch {
-        return { raw, dropped: [] }; // 反射/访问器抛错:抢不动就当没抢救,绝不外泄其文案
+        return { raw, dropped: [], keptIndex: NO_ENTRIES_DROPPED }; // 反射/访问器抛错:抢不动就当没抢救,绝不外泄其文案
     }
 }
 function salvageEntriesUnsafe(schema, raw) {
     if (!isPlainJsonObject(raw))
-        return { raw, dropped: [] };
+        return { raw, dropped: [], keptIndex: NO_ENTRIES_DROPPED };
     const root = unwrapSchema(schema);
     if (!(root instanceof z.ZodObject))
-        return { raw, dropped: [] };
+        return { raw, dropped: [], keptIndex: NO_ENTRIES_DROPPED };
     const shape = root.shape;
     const dropped = [];
     const patch = {};
+    const keptIndex = {};
     for (const [field, fieldSchema] of Object.entries(shape)) {
         const value = raw[field];
         if (value === undefined)
@@ -221,17 +240,24 @@ function salvageEntriesUnsafe(schema, raw) {
         if (collection instanceof z.ZodArray && Array.isArray(value)) {
             const element = collection.element;
             const bad = [];
+            const keptFrom = [];
+            // `filter`(不是手写 `for (i < value.length)`):它在**进入时**就钉死了长度,而重读 `value.length`
+            // 会跟着一个在校验期间自我增殖的数组一路跑下去(病态 getter 在 zod 读字段时往同一个数组里再 push
+            // 一条)——抢救是尽力而为的旁路,绝不许把同步读挂死。下标在回调里收,`filter` 本来就给 index。
             const kept = value.filter((entry, i) => {
                 const error = judgeEntry(element, entry);
-                if (error === undefined)
+                if (error === undefined) {
+                    keptFrom.push(i); // 压缩后第 keptFrom.length-1 条 = 原文档第 i 条
                     return true;
-                bad.push({ path: `${field}.${i}`, error });
+                }
+                bad.push({ path: [field, i], error });
                 return false;
             });
             // 零幸存者 ⇒ 没有要抢救的东西(见头注:绝不凭空造出一个空集合)。
             if (bad.length > 0 && kept.length > 0) {
                 dropped.push(...bad);
                 patch[field] = kept;
+                keptIndex[field] = keptFrom; // 只在真压缩了的字段上登记(见 {@link EntryKeptIndex})
             }
         }
         else if (collection instanceof z.ZodRecord && isPlainJsonObject(value)) {
@@ -244,7 +270,7 @@ function salvageEntriesUnsafe(schema, raw) {
                 if (error === undefined)
                     kept[key] = entry;
                 else
-                    bad.push({ path: `${field}.${redactSecrets(key)}`, error }); // 键是用户写的,可能就是一条粘错位置的凭据
+                    bad.push({ path: [field, redactSecrets(key)], error }); // 键是用户写的,可能就是一条粘错位置的凭据
             }
             if (bad.length > 0 && Object.keys(kept).length > 0) {
                 dropped.push(...bad);
@@ -253,8 +279,8 @@ function salvageEntriesUnsafe(schema, raw) {
         }
     }
     if (dropped.length === 0)
-        return { raw, dropped };
-    return { raw: { ...raw, ...patch }, dropped };
+        return { raw, dropped, keptIndex: NO_ENTRIES_DROPPED };
+    return { raw: { ...raw, ...patch }, dropped, keptIndex };
 }
 /**
  * Shared GC predicate for worker-status rows (F10) — keeps memory/sqlite/tidb identical. Given the rows'
@@ -295,6 +321,93 @@ export function legacyGovernanceFromRuntime(rawRuntime) {
             lifted[k] = r[k];
     return Object.keys(lifted).length ? lifted : undefined;
 }
+/**
+ * 一条告警里的**段坐标**({@link ConfigPath})从「抢救压缩后的坐标」回写成「原文档的坐标」—— 纯函数,
+ * {@link EntryKeptIndex} 是它唯一的坐标账。
+ *
+ * 成案(S-323,消费方真案):整域 parse 失败后 {@link salvageEntries} 会把坏条目从数组里剔掉,之后的
+ * 诊断({@link droppedKeys} / {@link carriedUnknownKeys})是拿**压缩后**的文档做键集对比出来的,它报的
+ * `models.1` 指的是压缩后的第 1 条。运维照着这条告警去改原文档的第 1 条 —— 改的是别人的行,而且改完
+ * 告警还在(他以为改对了)。**告警必须说运维看得见的那份文档里的坐标**。
+ *
+ * 为什么回写在这里、而不是让扫描函数认识原文档:给 `scanDropped` / `scanCarried` 加一个「原始 raw」
+ * 第二入参,等于让扫描同时持有两套坐标,每条新告警都要自己决定用哪套。回写是**告警出门前**的一次
+ * 坐标换算,与诊断本身正交 —— 一个铸点,所有臂一次表态。
+ *
+ * **闭集穷举**:`switch` 覆盖 {@link EffectiveReadWarning} 的每个 `kind`,新 kind 不声明处置 = 编译红
+ * (#157 的闭集纪律)。只分两类,没有第三类:**带坐标的回写,不带坐标的原样返回**。
+ *
+ * 为什么 `entry-dropped` 也回写:它**不是**「恒为原坐标」,只是不经**铸它那一层自己**的表 —— 上面那条律
+ * 说的就是这件事。{@link salvageEntries} 铸 `entry-dropped` 时用的是它**入参**那份文档的坐标;如果那份
+ * 文档本身已被外层(hosts 的 {@link grandfatherHostsRead})压缩过,外层照样要回写它一次。把「不动」写成
+ * 一条臂的性质,就是把「哪一层」这件事错记在了「哪个 kind」上。
+ *
+ * **恒等纪律**:没有任何一条路径真的变了(含 `keptIndex` 为空)⇒ 返回**同一个对象引用**,连 `keys`
+ * 数组也不复制(与 {@link grandfatherHostsRead} 的「没夹紧就返回原引用」同一条 byte 不变律)。
+ */
+export function rebaseWarningPaths(w, keptIndex) {
+    switch (w.kind) {
+        case "unknown-keys-dropped":
+        case "unknown-keys-carried":
+        case "legacy-governance-lifted": {
+            const keys = rebasePaths(w.keys, keptIndex);
+            return keys === w.keys ? w : { ...w, keys };
+        }
+        case "entry-dropped": {
+            const path = rebasePath(w.path, keptIndex);
+            return path === w.path ? w : { ...w, path };
+        }
+        // 以下三臂不带任何坐标:`hosts-grandfathered` 点名的是主机**名**,另两条点名的是错误/文件名。
+        case "hosts-grandfathered":
+        case "domain-defaulted":
+        case "unread-config-file":
+            return w;
+        default: {
+            // 闭集穷举门:新 kind 必须在上面表态,否则这里编译红。运行期到不了(本联合由本模块铸造);万一
+            // 到了就**原样返回** —— 回写是诊断面的尽力而为,这里抛异常会被调用点的 catch 吞成「整域降级」,
+            // 那比不回写坏得多(一条不认识的告警 ⇒ 整张目录蒸发)。
+            const unhandled = w;
+            return unhandled;
+        }
+    }
+}
+/** 一组坐标的回写。全部原样 ⇒ 返回**原数组引用**(调用方据此判「什么都没变」)。 */
+function rebasePaths(keys, keptIndex) {
+    let changed = false;
+    const out = keys.map((k) => {
+        const rebased = rebasePath(k, keptIndex);
+        if (rebased !== k)
+            changed = true;
+        return rebased;
+    });
+    return changed ? out : keys;
+}
+/**
+ * `[field, N, ...rest]` → `[field, 原 N, ...rest]`。**一条律**(S-323c,3.0.0):`p[0]` 是字符串且在位移表里
+ * (= 那个数组字段真被压缩过)∧ `p[1]` 是**数字段** ⇔ 它是一条数组路径。不满足 ⇒ 原样。
+ *
+ * 2.1.0 在点号串上需要三道门(字段在表里 / 段数合它那一支文法 / 下标段是规范十进制),因为串把「这一段
+ * 是下标还是键名」这个位丢了,只能靠文法猜回来;段形把那个位带在类型里,三道门收成一道 —— 判它是正确
+ * 抽象的第一判据就是**规则数变少**(`PathGrammar`、段数门、规范十进制正则三件随之删除)。
+ *
+ * 字面含点的顶层键(`["models.1.k"]`)天然不受影响:它只有一段,`p[1]` 缺席。Record 形的条目坐标
+ * (`[field, key]`)同样:Record 字段从不进位移表(条目按键寻址,丢一条不动其余键的坐标),而它的第二段
+ * 是字符串键、不是下标 —— 两道判据各自都挡得住。
+ *
+ * **恒等纪律**:没有任何一段真的变了(表长外、或原下标与压缩后下标相同)⇒ 返回**原引用**,不复制。
+ */
+function rebasePath(p, keptIndex) {
+    const field = p[0];
+    if (typeof field !== "string" || !Object.prototype.hasOwnProperty.call(keptIndex, field))
+        return p;
+    const index = typeof p[1] === "number" ? p[1] : undefined;
+    if (index === undefined)
+        return p;
+    const original = keptIndex[field][index];
+    if (original === undefined || original === index)
+        return p; // 表长外 ⇒ 原样(与 2.1.0「越界原样」同律)
+    return [field, original, ...p.slice(2)];
+}
 /** 扫描深度上限(嵌套再深的配置文档不存在;有上限才不会被恶意深链拖住)。 */
 const DROP_SCAN_MAX_DEPTH = 8;
 /** 一条警告最多点名多少个键(告警载荷有界;超界时警告带 `truncatedFrom` = 真实总数,见 {@link droppedKeys})。 */
@@ -307,22 +420,32 @@ const DROP_SCAN_MAX_KEYS = 64;
  * 满额特判,四层各被下一轮复审打穿)。意图只能在**声明处**说清:写者在这里登记自己的命名空间,之后
  * 所有未被登记的未知键都是拼错,消费方一条规则:未知键 = 错误,零特例。
  *
- * 登记形(分段):`at` = 父路径正则(点号形含尾点,顶层 `""`,首尾锚定,test 有门)+ `key` = 键名前缀正则;`owner` = 写者;
+ * 登记形(分段):`at` = 父路径的**段模式**({@link ConfigPath} 的形加一个通配哨兵 {@link ANY_INDEX} =
+ * 任一数组下标,顶层 = `[]`;逐段全等,天然闭合——没有正则可以锚歪,test 有门)+ `key` = 键名前缀正则;
+ * `owner` = 写者;
  * `since` = 契约出处。新写者/新层级来这里加行,并在 CHANGELOG 点名——这是 additive(minor)。
  *
  *  · `models` 条目级 `sema[A-Z]…`:壳(cli)的自留字段族(`semaChannel`/`semaLabel`/`semaProbe`/`semaProbeAt`/
  *    `semaEffortDefault`/`semaVision`,壳侧 models.json 实键清单 design/cli-190c:「`sema` 前缀是壳侧自留字段的既定
  *    约定」,**全条目级、顶层零装饰键**)。顶层 `sema*` 不在此列 ⇒ 仍是未知键(拼错或越界)。
  */
+/** {@link EXTENSION_NAMESPACES} 段模式里的**通配段**:匹配任一数组下标。
+ *
+ *  刻意是 `unique symbol` 而不是一个约定字符串(如 `"#"`):文档键只可能是 `string | number`
+ *  ({@link ConfigPath} 的值域),所以哨兵**不可能**与任何文档键相等 —— 通配与字面「一个叫 `#` 的键」
+ *  这两件事零二义,而且字面 `"#"` 仍然是一个可登记的普通段。类型上也不塌:`readonly (string | "#")[]`
+ *  会被 TS 收成 `readonly string[]`(写错通配不编译红),`readonly (string | typeof ANY_INDEX)[]` 不会。 */
+export const ANY_INDEX = Symbol("settings-schema/any-index");
 export const EXTENSION_NAMESPACES = {
-    models: [{ at: /^models\.\d+\.$/, key: /^sema[A-Z]/, owner: "cli", since: "shell key census design/cli-190c (2026-08-26)" }],
+    models: [{ at: ["models", ANY_INDEX], key: /^sema[A-Z]/, owner: "cli", since: "shell key census design/cli-190c (2026-08-26)" }],
 };
-/** 该键是否落在 {@link EXTENSION_NAMESPACES} 登记的扩展命名空间里(⇒ 不是未知键)。**分段匹配**:`at` 对父路径(点号形,含尾点;
- *  顶层 = `""`),`key` 对键名本身——不在拼好的点号路径上猜(键名里可以含 `.`,`semaX.foo` 是一个键不是两层),前缀契约就是
- *  前缀契约(`semaGPT_5` / `semaX-v2` 都是成员,后缀不设未声明的文法)。 */
-export function isReservedExtensionKey(domain, parentPath, key) {
+/** 该键是否落在 {@link EXTENSION_NAMESPACES} 登记的扩展命名空间里(⇒ 不是未知键)。**分段匹配**:`at` 对
+ *  父路径的段(长度相等 ∧ 逐段——{@link ANY_INDEX} 匹配任一**数字**段,字符串段逐字相等;顶层 = `[]`),`key` 对键名
+ *  本身——键名里可以含 `.`(`semaX.foo` 是一个键不是两层),段形让这件事不必再靠文法猜;前缀契约就是前缀
+ *  契约(`semaGPT_5` / `semaX-v2` 都是成员,后缀不设未声明的文法)。 */
+export function isReservedExtensionKey(domain, parent, key) {
     const rules = EXTENSION_NAMESPACES[domain];
-    return rules !== undefined && rules.some((r) => r.at.test(parentPath) && r.key.test(key));
+    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) {
@@ -339,7 +462,7 @@ function collectDropped(domain, raw, parsed, prefix, depth, spared, acc) {
         if (raw.length !== parsed.length)
             return;
         for (let i = 0; i < raw.length; i++)
-            collectDropped(domain, raw[i], parsed[i], `${prefix}${i}.`, depth + 1, [], acc);
+            collectDropped(domain, raw[i], parsed[i], [...prefix, i], depth + 1, [], acc);
         return;
     }
     if (!isPlainJsonObject(raw) || !isPlainJsonObject(parsed))
@@ -352,16 +475,16 @@ function collectDropped(domain, raw, parsed, prefix, depth, spared, acc) {
                 continue; // 扩展命名空间:按契约放的键,不是未知键
             acc.total += 1;
             if (acc.keys.length < DROP_SCAN_MAX_KEYS)
-                acc.keys.push(prefix + k);
+                acc.keys.push([...prefix, k]);
             continue;
         }
-        collectDropped(domain, raw[k], parsed[k], `${prefix}${k}.`, depth + 1, spared, acc);
+        collectDropped(domain, raw[k], parsed[k], [...prefix, k], depth + 1, spared, acc);
     }
 }
 function scanDropped(domain, raw, parsed) {
     const acc = { keys: [], total: 0 };
     try {
-        collectDropped(domain, raw, parsed, "", 0, domain === "runtime" ? GOVERNANCE_MIRROR_KEYS : [], acc);
+        collectDropped(domain, raw, parsed, [], 0, domain === "runtime" ? GOVERNANCE_MIRROR_KEYS : [], acc);
     }
     catch {
         return { keys: [], total: 0 }; // 反射/访问器抛错:告警是尽力而为的审计线,绝不能把解析拖下水,更不能回显其错误文案
@@ -369,7 +492,7 @@ function scanDropped(domain, raw, parsed) {
     return acc;
 }
 /**
- * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),点号路径形。
+ * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),段坐标形({@link ConfigPath})。
  *
  * 成案(消费方 #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
  * `domainErrors` 空、解析"成功"——配置写了、值没到、零告警。剥除行为本身是**刻意的前向兼容**
@@ -392,8 +515,8 @@ export function droppedKeys(domain, raw, parsed) {
     return scanDropped(domain, raw, parsed).keys;
 }
 /**
- * open-world 域(`.passthrough()`)的**已知键表**:路径 → 该层已知键(`""` = 顶层)。键集从 schema 的
- * `shape` **单源派生**(手抄一份必然漂),路径表本身是显式的——嵌套只在真有 open-world 子对象的地方登记。
+ * open-world 域(`.passthrough()`)的**已知键表**:段坐标 → 该层已知键(`[]` = 顶层)。键集从 schema 的
+ * `shape` **单源派生**(手抄一份必然漂),层级表本身是显式的——嵌套只在真有 open-world 子对象的地方登记。
  *
  * 为什么需要它(对抗复审 复审 round2 F2):承运解决了「值到不了」,但没解决「键名拼错了没人说」——
  * `toolResultsTtlSec`(多一个 s)会完好穿过本包,而消费方只遍历自己的键表,于是那条天花板悄悄没生效。
@@ -403,10 +526,13 @@ export function droppedKeys(domain, raw, parsed) {
  * `unknownKeys === "passthrough"` 的域 schema 都必须在本表里有行(缺行 = 该域的未知键无人点名)。
  */
 const OPEN_WORLD_KNOWN_KEYS = {
-    limits: { "": Object.keys(LimitsConfig.shape), infraCostRates: Object.keys(InfraCostRates.shape) },
+    limits: [
+        [[], Object.keys(LimitsConfig.shape)],
+        [["infraCostRates"], Object.keys(InfraCostRates.shape)],
+    ],
 };
 /**
- * 一份已解析的 open-world 域文档里,**本包不认识但已承运**的键(点号路径)。非 open-world 域恒空
+ * 一份已解析的 open-world 域文档里,**本包不认识但已承运**的键(段坐标)。非 open-world 域恒空
  * (它们的未知键走 {@link droppedKeys} 那条更重的「被丢了」告警)。
  *
  * 边界(如实):只看 {@link OPEN_WORLD_KNOWN_KEYS} 登记了的层级 —— 未登记层级(如某个未知键自己的
@@ -418,21 +544,21 @@ export function carriedUnknownKeys(domain, parsed) {
 function scanCarried(domain, parsed) {
     const table = OPEN_WORLD_KNOWN_KEYS[domain];
     const acc = { keys: [], total: 0 };
-    if (!table || !isPlainJsonObject(parsed))
+    if (table === undefined)
         return acc;
-    for (const [path, known] of Object.entries(table)) {
-        const node = path === "" ? parsed : parsed[path];
+    for (const [at, known] of table) {
+        // 段形下探:`[]` 落在文档根上,所以「顶层 vs 嵌套」不再是两条分支(规则少一条)。
+        const node = at.reduce((cur, seg) => (isPlainJsonObject(cur) ? cur[String(seg)] : undefined), parsed);
         if (!isPlainJsonObject(node))
             continue;
-        const prefix = path === "" ? "" : `${path}.`;
         for (const k of Object.keys(node)) {
             if (known.includes(k))
                 continue;
-            if (isReservedExtensionKey(domain, prefix, k))
+            if (isReservedExtensionKey(domain, at, k))
                 continue;
             acc.total += 1;
             if (acc.keys.length < DROP_SCAN_MAX_KEYS)
-                acc.keys.push(prefix + k);
+                acc.keys.push([...at, k]);
         }
     }
     return acc;
@@ -516,16 +642,18 @@ export const DOMAIN_READ_FALLBACK = {
  *  observable: a deployment that has not seen that warning across a full read cycle no longer needs the arm. */
 export function grandfatherHostsRead(raw) {
     if (raw === null || typeof raw !== "object" || !Array.isArray(raw.hosts)) {
-        return { raw, droppedNames: [] }; // not the expected shape — let parseDomain rule on it
+        return { raw, droppedNames: [], keptIndex: NO_ENTRIES_DROPPED }; // not the expected shape — let parseDomain rule on it
     }
     const original = raw.hosts;
     const droppedNames = [];
-    let hosts = original.filter((h) => {
+    const keptFrom = [];
+    let hosts = original.filter((h, i) => {
         const name = h !== null && typeof h === "object" ? h.name : undefined;
         if (typeof name === "string" && name.length > HOST_NAME_MAX) {
             droppedNames.push(name.slice(0, HOST_NAME_MAX) + "…"); // audit label — clipped so the warning itself stays bounded
             return false;
         }
+        keptFrom.push(i); // 夹紧后第 keptFrom.length-1 条 = 原文档第 i 条
         return true;
     });
     let truncatedFrom;
@@ -534,20 +662,37 @@ export function grandfatherHostsRead(raw) {
         hosts = hosts.slice(0, HOSTS_ARRAY_MAX);
     }
     if (droppedNames.length === 0 && truncatedFrom === undefined)
-        return { raw, droppedNames }; // identity — byte-stable
-    return { raw: { ...raw, hosts }, droppedNames, truncatedFrom };
+        return { raw, droppedNames, keptIndex: NO_ENTRIES_DROPPED }; // identity — byte-stable
+    // 位移**只**来自按名剔条目;纯截断留下的是原数组前缀,幸存者下标不动 ⇒ 不登记(见 EntryKeptIndex)。
+    const keptIndex = droppedNames.length > 0 ? { hosts: keptFrom.slice(0, hosts.length) } : NO_ENTRIES_DROPPED;
+    return { raw: { ...raw, hosts }, droppedNames, truncatedFrom, keptIndex };
 }
 export function buildEffective(version, getRaw, updatedAt, onWarning) {
     // 0.19.0 静默剥键/静默承运门:解析**成功**的域,把 schema 丢掉的键、以及 open-world 域里承运但本包
     // 不认识的键(都含嵌套,点号路径)点名(行为不变,只是不再无声)。判据与 `getDomain` 同源
     // ({@link parseDomainLoud})。只在成功路径上报——降级路径已经有 domain-defaulted 那条更重的警告。
     const parseLoud = (domain, raw) => parseDomainLoud(domain, raw, onWarning);
+    /**
+     * 一层读的**告警出口**,外面裹了那一层的坐标换算(S-323b 统一律)。
+     *
+     * 读路径上有**两个压缩点**:{@link grandfatherHostsRead}(parse 之前按名剔 host 条目)与
+     * {@link salvageEntries}(整域 parse 失败后剔坏条目)。律只有一条:**一条告警用「铸它的那一层所见
+     * 文档」的坐标表达;哪一层压缩了文档,哪一层就把从它下方上来的告警回写一次。** 组合因此是自然的
+     * ——内层先换算、外层后换算,不重不漏,而每一层都只需要知道**自己**那本账。
+     *
+     * 位移表**空**(这一层这次什么都没压缩)⇒ 原样返回 `onWarning`,连一层闭包都不套 —— 与
+     * {@link rebaseWarningPaths} 的恒等纪律同一条律:没发生的事不留痕迹。
+     */
+    const exitOf = (keptIndex) => onWarning === undefined || Object.keys(keptIndex).length === 0 ? onWarning : (w) => onWarning(rebaseWarningPaths(w, keptIndex));
     // Generic READ guardrail (0.8.1): a domain that no longer parses degrades to its schema default + a warning
     // — but ONLY where DOMAIN_READ_FALLBACK says the default is safe; gate-bearing domains keep throwing (决策
     // 表与逐域理由见 DOMAIN_READ_FALLBACK). The success path is UNCHANGED (same parseDomain, same bytes).
-    const parseOr = (domain, raw) => {
+    //
+    // `emit` = 这一腿的告警出口(默认 = 本函数的 `onWarning`)。**刻意不收「外层压缩了多少」这种入参**:
+    // parseOr 不必知道自己上面还有没有一层,它只管把告警交给给它的那个出口 —— 换算是出口的事。
+    const parseOr = (domain, raw, emit = onWarning) => {
         try {
-            return parseLoud(domain, raw);
+            return parseDomainLoud(domain, raw, emit);
         }
         catch (e) {
             if (DOMAIN_READ_FALLBACK[domain] === "throw")
@@ -560,17 +705,20 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
                 try {
                     const buffered = [];
                     const parsed = parseDomainLoud(domain, salvage.raw, (w) => buffered.push(w));
+                    // 统一律落地:`entry-dropped` 是**本层**(salvage)铸的,用的就是本层入参那份文档的坐标 ⇒
+                    // 不过本层自己的表,直接交给出口(出口会补上更外层的换算);`buffered` 里的是对**本层压缩后**
+                    // 文档的诊断,是从下方上来的 ⇒ 先过本层的表,再交给出口。scan 函数一字不动。
                     for (const d of salvage.dropped)
-                        onWarning?.({ domain, kind: "entry-dropped", path: d.path, error: d.error });
+                        emit?.({ domain, kind: "entry-dropped", path: d.path, error: d.error });
                     for (const w of buffered)
-                        onWarning?.(w);
+                        emit?.(rebaseWarningPaths(w, salvage.keptIndex));
                     return parsed;
                 }
                 catch {
                     // 条目之外还有毛病(重名 / 悬空 ref / 域级判据)—— 丢条目救不了它,照常整域降级。
                 }
             }
-            onWarning?.({ domain, kind: "domain-defaulted", error: e });
+            emit?.({ domain, kind: "domain-defaulted", error: e });
             return parseDomain(domain, undefined); // schema default — always valid
         }
     };
@@ -582,7 +730,7 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
         const lifted = legacyGovernanceFromRuntime(getRaw("runtime"));
         // 兼容臂真生效时出声(1.11.0):行为一字不变,但窗要能关就得有人看得见它还开着。
         if (lifted !== undefined)
-            onWarning?.({ domain: "governance", kind: "legacy-governance-lifted", keys: Object.keys(lifted) });
+            onWarning?.({ domain: "governance", kind: "legacy-governance-lifted", keys: Object.keys(lifted).map((k) => [k]) });
         governanceSource = lifted;
     }
     const governance = parseLoud("governance", governanceSource);
@@ -609,7 +757,9 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
         systems: parseOr("systems", getRaw("systems")),
         collab: parseOr("collab", getRaw("collab")),
         workers: parseLoud("workers", getRaw("workers")),
-        hosts: parseOr("hosts", hostsGf.raw),
+        // hosts 是读路径上**唯一**有外层压缩点的腿:`hostsGf.raw` 已被 grandfather 按名剔过条目,所以这一腿的
+        // 告警出口要裹上它的位移表(统一律:哪一层压缩,哪一层回写从它下方上来的告警)。
+        hosts: parseOr("hosts", hostsGf.raw, exitOf(hostsGf.keptIndex)),
         runtime,
         governance,
         entitlement: parseLoud("entitlement", getRaw("entitlement")),
@@ -679,11 +829,13 @@ export function readEffectiveWire(raw, onWarning) {
         }
     }
     // Open-world passthrough: keys that are neither validated domains nor the envelope fields ride verbatim.
-    const passthrough = {};
-    for (const [k, v] of Object.entries(r)) {
-        if (!(k in built) && k !== "skills")
-            passthrough[k] = v;
-    }
+    // `hasOwnProperty.call(built, k)`,**不是** `k in built`(S-332):`in` 会一路问到 `Object.prototype`,
+    // 于是 `constructor` / `toString` / `hasOwnProperty` / `__proto__` 这些**原型链上的名字**作未知顶层键时
+    // 被判成「已知域」而整条吞掉 —— open-world 的承诺(本包不认识的键原样送达)对它们恰好失效,而且无声。
+    // 与本文件另两处自有键判据(:548 `rebasePath` 查位移表、:612 `collectDropped` 比键集)同一条律,零特判。
+    // `Object.fromEntries`,**不是**逐键 `passthrough[k] = v`:后者对 `"__proto__"` 走的是原型 setter
+    // (改掉对象的原型,而不是加一个键),fromEntries 走 CreateDataProperty —— 同一条「键就是键」的律。
+    const passthrough = Object.fromEntries(Object.entries(r).filter(([k]) => !Object.prototype.hasOwnProperty.call(built, k) && k !== "skills"));
     // prompts:剥掉 buildEffective 恒物化的 {bindings:[]} 底座,按 wire 在场性 verbatim 挂回(#100:
     // 缺席进缺席出——center worker-lane 闸关是常态形,物化会让消费端「缺席」分支永不可达)。
     const { prompts: _promptsMaterialized, ...builtSansPrompts } = built;

package/dist/conformance/canonical.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 规范化与结构化比对的**单铸点**。消费方零复述 —— 一份被各自复述的规范化就是第二份真源。
+ *
+ * 两件事,刻意分开:
+ *  · {@link canonicalize} —— 把一份 JSON 值收成**确定序**的形(对象键排序、数组保序)。它是**比对的
+ *    预处理**,不是比对本身。
+ *  · {@link deepEqual} / {@link diffEffective} —— 结构化深相等与差异定位。**绝不**把值 stringify 之后比串:
+ *    串是有损编码(`["a.b"]` 与 `["a","b"]` 拼出来同一个串),而消掉那个二义正是 3.0.0 改铸段坐标的理由。
+ *
+ * `stableKey` 是唯一一处把值转成串的地方,它只用来给**多重集计数**当哈希键 —— 用的是 JSON 编码,
+ * 数组边界与段类型(`"1"` vs `1`)在编码里都还在,所以它不是那种有损的点号串。
+ */
+/**
+ * 键排序、数组保序的规范形。`undefined` 值的键**被剔掉**(JSON 里没有 `undefined`,留着它会让
+ * 「键不在场」与「键在场但值是 undefined」在比对上分成两件事,而 wire 上它们同形)。
+ */
+export declare function canonicalize(value: unknown): unknown;
+/** 规范形的稳定串编码 —— **只**给多重集计数当键用(见本文件头注)。 */
+export declare function stableKey(value: unknown): string;
+/** 结构化深相等(数组保序、对象键集相等、标量 `Object.is`)。 */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+export interface JsonPatchOp {
+    op: "add" | "remove" | "replace";
+    path: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+/**
+ * 两份 effective 的差,按 JSON Pointer 逐处点名。**诊断输出** —— 判「相等与否」的是 {@link deepEqual},
+ * 本函数只负责把不等的地方说清楚。
+ *
+ * **结构不变式(承重面)**:`deepEqual(e, a) === false` ⇒ 返回的 patch **非空**。`run.ts` 的 judge 是按
+ * `effectivePatch.length === 0` 判 pass 的,所以空数组在那里就等于「相等」;一旦这条不变式破了,不等的
+ * 两份 effective 会静默判绿(3.0.0 发前补复审 ① 的成案形)。钉在 `test/conformance-comparator.test.ts`。
+ */
+export declare function diffJson(expected: unknown, actual: unknown, at?: readonly (string | number)[]): JsonPatchOp[];

package/dist/conformance/canonical.js

@@ -0,0 +1,114 @@
+/**
+ * 规范化与结构化比对的**单铸点**。消费方零复述 —— 一份被各自复述的规范化就是第二份真源。
+ *
+ * 两件事,刻意分开:
+ *  · {@link canonicalize} —— 把一份 JSON 值收成**确定序**的形(对象键排序、数组保序)。它是**比对的
+ *    预处理**,不是比对本身。
+ *  · {@link deepEqual} / {@link diffEffective} —— 结构化深相等与差异定位。**绝不**把值 stringify 之后比串:
+ *    串是有损编码(`["a.b"]` 与 `["a","b"]` 拼出来同一个串),而消掉那个二义正是 3.0.0 改铸段坐标的理由。
+ *
+ * `stableKey` 是唯一一处把值转成串的地方,它只用来给**多重集计数**当哈希键 —— 用的是 JSON 编码,
+ * 数组边界与段类型(`"1"` vs `1`)在编码里都还在,所以它不是那种有损的点号串。
+ */
+/** 纯 JSON 对象(不是数组、不是类实例)。 */
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * 「这个对象**在场**的键」—— 本文件里唯一一处判键在不在 / 取键的值的地方。
+ *
+ * 两条律合成一条,别处零复述:
+ *  · **只认自有键**(`Object.prototype.hasOwnProperty.call`):`__proto__` / `constructor` / `toString` /
+ *    `hasOwnProperty` 这四个名字落在 `Object.prototype` 上,裸下标 `o[k]` 会在**缺席**的那一侧读到继承值
+ *    ——`{"__proto__":{}}`(JSON.parse 得自有键)对 `{}` 于是两侧都 `!== undefined`,既不 add 也不 remove,
+ *    递归进 `diffJson({}, Object.prototype)` 又深相等 ⇒ **`deepEqual` 说不等而 `diffJson` 返回空** ⇒
+ *    judge 拿空 patch 判 pass。那正是 S-332「键就是键」要防的一类丢键,门反而对它全盲。
+ *  · **`undefined` 值 = 不在场**(JSON 里没有 `undefined`;留着它会让「键不在场」与「键在场但值 undefined」
+ *    在比对上分成两件事,而 wire 上它们同形)。
+ */
+function ownValue(o, k) {
+    return Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined;
+}
+/** 在场的自有键(排序)—— 规范化、深相等、差异定位三处共用同一份「键集」定义。 */
+function presentKeys(o) {
+    return Object.keys(o)
+        .filter((k) => ownValue(o, k) !== undefined)
+        .sort();
+}
+/**
+ * 键排序、数组保序的规范形。`undefined` 值的键**被剔掉**(JSON 里没有 `undefined`,留着它会让
+ * 「键不在场」与「键在场但值是 undefined」在比对上分成两件事,而 wire 上它们同形)。
+ */
+export function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (isPlainObject(value)) {
+        // `Object.fromEntries`,**不是**逐键 `out[k] = …`:后者对 `"__proto__"` 走的是原型 setter(改掉对象的
+        // 原型,既不产生自有键、还污染返回值),于是规范化会把一个叫 `__proto__` 的顶层键**吃掉** —— 两边
+        // 同样被吃掉 = 比对器对它全盲 = 一格假绿。与 S-332 在 wire 透传处修的是同一条「键就是键」的律。
+        return Object.fromEntries(presentKeys(value).map((k) => [k, canonicalize(ownValue(value, k))]));
+    }
+    return value;
+}
+/** 规范形的稳定串编码 —— **只**给多重集计数当键用(见本文件头注)。 */
+export function stableKey(value) {
+    return JSON.stringify(canonicalize(value));
+}
+/** 结构化深相等(数组保序、对象键集相等、标量 `Object.is`)。 */
+export function deepEqual(a, b) {
+    if (Object.is(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)) {
+        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)));
+    }
+    return false;
+}
+/** RFC 6901 的转义(`~` → `~0`,`/` → `~1`)。 */
+const pointerSegment = (s) => (typeof s === "number" ? String(s) : s.replace(/~/g, "~0").replace(/\//g, "~1"));
+/**
+ * 两份 effective 的差,按 JSON Pointer 逐处点名。**诊断输出** —— 判「相等与否」的是 {@link deepEqual},
+ * 本函数只负责把不等的地方说清楚。
+ *
+ * **结构不变式(承重面)**:`deepEqual(e, a) === false` ⇒ 返回的 patch **非空**。`run.ts` 的 judge 是按
+ * `effectivePatch.length === 0` 判 pass 的,所以空数组在那里就等于「相等」;一旦这条不变式破了,不等的
+ * 两份 effective 会静默判绿(3.0.0 发前补复审 ① 的成案形)。钉在 `test/conformance-comparator.test.ts`。
+ */
+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)) {
+        const out = [];
+        for (let i = 0; i < Math.max(expected.length, actual.length); i++) {
+            if (i >= expected.length)
+                out.push({ op: "add", path: `${path}/${i}`, actual: actual[i] });
+            else if (i >= actual.length)
+                out.push({ op: "remove", path: `${path}/${i}`, expected: expected[i] });
+            else
+                out.push(...diffJson(expected[i], actual[i], [...at, i]));
+        }
+        return out;
+    }
+    if (isPlainObject(expected) && isPlainObject(actual)) {
+        const out = [];
+        const keys = [...new Set([...presentKeys(expected), ...presentKeys(actual)])].sort();
+        for (const k of keys) {
+            // 取值走 `ownValue`(不是裸下标):缺席的那一侧对原型名键会读到 `Object.prototype` 上的继承值,
+            // 于是 add/remove 判据失效 —— 详见 `ownValue` 的注。
+            const e = ownValue(expected, k);
+            const a = ownValue(actual, k);
+            if (e === undefined && a !== undefined)
+                out.push({ op: "add", path: `${path}/${pointerSegment(k)}`, actual: a });
+            else if (e !== undefined && a === undefined)
+                out.push({ op: "remove", path: `${path}/${pointerSegment(k)}`, expected: e });
+            else
+                out.push(...diffJson(e, a, [...at, k]));
+        }
+        return out;
+    }
+    return [{ op: "replace", path, expected, actual }];
+}

package/dist/conformance/contract-adapter.d.ts

@@ -0,0 +1,20 @@
+import type { ConformanceAdapter, ConformanceProvenance, LegEntry, LegName } from "./types.js";
+/** 一份契约模块(新旧版同形 —— 三条腿的签名自 0.19.0 起没动过)。 */
+export interface ContractModule {
+    buildEffective(version: number, getRaw: (d: string) => unknown, updatedAt: string, onWarning?: (w: unknown) => void): unknown;
+    readEffectiveWire(raw: unknown, onWarning?: (w: unknown) => void): unknown;
+    loadLocalConfig(root: string, opts?: {
+        onWarning?: (w: unknown) => void;
+    }): Promise<{
+        effective: unknown;
+        warnings: unknown[];
+    }>;
+}
+export interface ContractAdapterOptions {
+    name: string;
+    provenance: ConformanceProvenance;
+    mod: ContractModule;
+    /** 三条腿各自的生产入口坐标(绝对路径)。 */
+    entries: Record<LegName, LegEntry>;
+}
+export declare function createContractAdapter(opts: ContractAdapterOptions): ConformanceAdapter;