@sema-agent/settings-schema 2.1.0 → 3.0.1

package/dist/config-fns.js

@@ -123,7 +123,7 @@ export function parseDomain(domain, raw) {
         return r.data;
     throw sanitizeZodError(r.error); // recursive redaction (message/received/unionErrors) — no secret echo. R13/R14.
 }
-// ── 逐条容错律(1.11.0,S-144 按类修)───────────────────────────────────────────────────────────────
+// ── 逐条容错律(2.0.0,S-144 按类修)───────────────────────────────────────────────────────────────
 //
 // 病:域解析整域 all-or-nothing —— 13 个模型里坏一条,整张目录退成 schema 默认 = 一条都不剩。缓解一直
 // 是**逐键**打补丁(把新键改成 `z.unknown()` 让它别拒),那是给每个新键加特判,规则只会越来越多;
@@ -157,6 +157,22 @@ 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 在遍历中抛错时**绝不**外泄其文案
@@ -234,7 +250,7 @@ function salvageEntriesUnsafe(schema, raw) {
                     keptFrom.push(i); // 压缩后第 keptFrom.length-1 条 = 原文档第 i 条
                     return true;
                 }
-                bad.push({ path: `${field}.${i}`, error });
+                bad.push({ path: [field, i], error });
                 return false;
             });
             // 零幸存者 ⇒ 没有要抢救的东西(见头注:绝不凭空造出一个空集合)。
@@ -254,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);
@@ -290,7 +306,7 @@ export function statusRowsToPrune(rows, opts) {
  *  store upgrades with zero data migration and zero gate loss. An explicitly-set governance domain WINS
  *  (its absence-of-a-key then means "center not managing", never "fall back to legacy runtime").
  *
- *  SUNSET (1.11.0): removal is a **persistent-data** break — a store still carrying the 0.5 shape would lose
+ *  SUNSET (2.0.0): removal is a **persistent-data** break — a store still carrying the 0.5 shape would lose
  *  its guardrails silently, so this arm cannot simply be deleted at a minor. It goes at the next MAJOR, with
  *  the standard persistent-data treatment (a loud refusal naming the domain + a one-time migration on the
  *  writer side), and the closing condition is observable rather than a promise: `buildEffective` now emits
@@ -306,8 +322,8 @@ export function legacyGovernanceFromRuntime(rawRuntime) {
     return Object.keys(lifted).length ? lifted : undefined;
 }
 /**
- * 一条告警里的**点号路径**从「抢救压缩后的坐标」回写成「原文档的坐标」—— 纯函数,{@link EntryKeptIndex}
- * 是它唯一的坐标账。
+ * 一条告警里的**段坐标**({@link ConfigPath})从「抢救压缩后的坐标」回写成「原文档的坐标」—— 纯函数,
+ * {@link EntryKeptIndex} 是它唯一的坐标账。
  *
  * 成案(S-323,消费方真案):整域 parse 失败后 {@link salvageEntries} 会把坏条目从数组里剔掉,之后的
  * 诊断({@link droppedKeys} / {@link carriedUnknownKeys})是拿**压缩后**的文档做键集对比出来的,它报的
@@ -334,14 +350,14 @@ export function rebaseWarningPaths(w, keptIndex) {
         case "unknown-keys-dropped":
         case "unknown-keys-carried":
         case "legacy-governance-lifted": {
-            const keys = rebasePaths(w.keys, keptIndex, "key");
+            const keys = rebasePaths(w.keys, keptIndex);
             return keys === w.keys ? w : { ...w, keys };
         }
         case "entry-dropped": {
-            const path = rebasePath(w.path, keptIndex, "entry");
+            const path = rebasePath(w.path, keptIndex);
             return path === w.path ? w : { ...w, path };
         }
-        // 以下三臂不带任何点号路径:`hosts-grandfathered` 点名的是主机**名**,另两条点名的是错误/文件名。
+        // 以下三臂不带任何坐标:`hosts-grandfathered` 点名的是主机**名**,另两条点名的是错误/文件名。
         case "hosts-grandfathered":
         case "domain-defaulted":
         case "unread-config-file":
@@ -355,11 +371,11 @@ export function rebaseWarningPaths(w, keptIndex) {
         }
     }
 }
-/** 一组点号路径的回写。全部原样 ⇒ 返回**原数组引用**(调用方据此判「什么都没变」)。 */
-function rebasePaths(keys, keptIndex, grammar) {
+/** 一组坐标的回写。全部原样 ⇒ 返回**原数组引用**(调用方据此判「什么都没变」)。 */
+function rebasePaths(keys, keptIndex) {
     let changed = false;
     const out = keys.map((k) => {
-        const rebased = rebasePath(k, keptIndex, grammar);
+        const rebased = rebasePath(k, keptIndex);
         if (rebased !== k)
             changed = true;
         return rebased;
@@ -367,44 +383,30 @@ function rebasePaths(keys, keptIndex, grammar) {
     return changed ? out : keys;
 }
 /**
- * `field.N.rest` → `field.<原 N>.rest`。**按段比对**,不在拼好的串上做前缀匹配:`models` 的位移表绝不许
- * 动到 `modelsX.1.k`(同名前缀是两个字段)。
+ * `[field, N, ...rest]` → `[field, 原 N, ...rest]`。**一条律**(S-323c,3.0.0):`p[0]` 是字符串且在位移表里
+ * (= 那个数组字段真被压缩过)∧ `p[1]` 是**数字段** ⇔ 它是一条数组路径。不满足 ⇒ 原样。
  *
- * 回写的**定义域 = `grammar` 那一支真正铸得出来的数组路径**,不是「长得像下标就算」(两支文法的差别与
- * 合并的代价见 {@link PathGrammar})。三道门,缺一不回写:
- *   · `field` 必须在位移表里(= 那个字段真被压缩过);
- *   · 段数合文法:`"entry"` 支的数组条目**恰好两段**,`"key"` 支**至少三段**;
- *   · 下标段必须是**规范十进制**(`${i}` 的像:无前导零、无符号、无空白)且落在表长内。
- * 不满足 ⇒ 原样返回。
+ * 2.1.0 在点号串上需要三道门(字段在表里 / 段数合它那一支文法 / 下标段是规范十进制),因为串把「这一段
+ * 是下标还是键名」这个位丢了,只能靠文法猜回来;段形把那个位带在类型里,三道门收成一道 —— 判它是正确
+ * 抽象的第一判据就是**规则数变少**(`PathGrammar`、段数门、规范十进制正则三件随之删除)。
  *
- * Record 形的条目路径(`${field}.${key}`)天然不受影响:Record 字段从不进位移表(条目按键寻址,丢一条
- * 不动其余键的坐标),`hasOwnProperty` 那道门就把它挡在外面了。
+ * 字面含点的顶层键(`["models.1.k"]`)天然不受影响:它只有一段,`p[1]` 缺席。Record 形的条目坐标
+ * (`[field, key]`)同样:Record 字段从不进位移表(条目按键寻址,丢一条不动其余键的坐标),而它的第二段
+ * 是字符串键、不是下标 —— 两道判据各自都挡得住。
  *
- * 如实登记的残余歧义(S-323c,本版**不消**):点号路径是有损编码 —— 键名里本来就允许含 `.`
- * (见 {@link isReservedExtensionKey} 的分段匹配注),所以一个**字面叫 `models.1.k` 的顶层键**与
- * `models[1]` 里的未知键 `k` 仍然编码成同一个串,无从分辨(裸 `models.1` 那一半已被上面的段数门挡住)。
- * 那是编码本身的歧义(回写之前就在:两版都指不到那个字面键,只是数字不同);要消掉它得让扫描与抢救
- * 改铸**结构化路径段**、出门时才 stringify —— 那是 {@link EffectiveReadWarning} 的 BREAKING,归下一个 major。
+ * **恒等纪律**:没有任何一段真的变了(表长外、或原下标与压缩后下标相同)⇒ 返回**原引用**,不复制。
  */
-function rebasePath(key, keptIndex, grammar) {
-    const firstDot = key.indexOf(".");
-    if (firstDot <= 0)
-        return key; // 顶层键,没有下标可言
-    const field = key.slice(0, firstDot);
-    if (!Object.prototype.hasOwnProperty.call(keptIndex, field))
-        return key;
-    const rest = key.slice(firstDot + 1);
-    const secondDot = rest.indexOf(".");
-    const bare = secondDot < 0;
-    if (bare !== (grammar === "entry"))
-        return key; // 段数不合本支文法 ⇒ 它不是这一支铸出来的数组路径
-    const indexText = bare ? rest : rest.slice(0, secondDot);
-    if (!/^(?:0|[1-9]\d*)$/.test(indexText))
-        return key; // 规范十进制才是 `${i}` 的像
-    const original = keptIndex[field][Number(indexText)];
-    if (original === undefined)
-        return key;
-    return bare ? `${field}.${original}` : `${field}.${original}.${rest.slice(secondDot + 1)}`;
+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;
@@ -418,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) {
@@ -450,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))
@@ -463,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 }; // 反射/访问器抛错:告警是尽力而为的审计线,绝不能把解析拖下水,更不能回显其错误文案
@@ -480,7 +492,7 @@ function scanDropped(domain, raw, parsed) {
     return acc;
 }
 /**
- * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),点号路径形。
+ * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),段坐标形({@link ConfigPath})。
  *
  * 成案(消费方 #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
  * `domainErrors` 空、解析"成功"——配置写了、值没到、零告警。剥除行为本身是**刻意的前向兼容**
@@ -503,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)会完好穿过本包,而消费方只遍历自己的键表,于是那条天花板悄悄没生效。
@@ -514,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} 登记了的层级 —— 未登记层级(如某个未知键自己的
@@ -529,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;
@@ -622,7 +637,7 @@ export const DOMAIN_READ_FALLBACK = {
  *  everything else (regex, types, duplicates) is left for parseDomain — this is a targeted grandfather, not a
  *  lenient parser. PURE + idempotent; returns the ORIGINAL reference when nothing exceeds the bounds.
  *
- *  SUNSET (1.11.0): same persistent-data class as the governance lift — it goes at the next MAJOR. This one was
+ *  SUNSET (2.0.0): same persistent-data class as the governance lift — it goes at the next MAJOR. This one was
  *  never silent (`hosts-grandfathered` fires whenever it clamps), so the closing condition is already
  *  observable: a deployment that has not seen that warning across a full read cycle no longer needs the arm. */
 export function grandfatherHostsRead(raw) {
@@ -682,7 +697,7 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
         catch (e) {
             if (DOMAIN_READ_FALLBACK[domain] === "throw")
                 throw e;
-            // 逐条容错(1.11.0)在整域降级**之前**试一次:只丢掉真正坏掉的那几条条目,同域好兄弟活下来。
+            // 逐条容错(2.0.0)在整域降级**之前**试一次:只丢掉真正坏掉的那几条条目,同域好兄弟活下来。
             // 告警先缓存再决定 —— 一个域只给一个结论:救活了就逐条报 `entry-dropped`,没救活就只报
             // `domain-defaulted`(那一域的条目反正一条都不剩,再讲「丢了第 3 条」只会误导)。
             const salvage = salvageEntries(DOMAIN_SCHEMAS[domain], raw);
@@ -713,9 +728,9 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
     let governanceSource = governanceRaw;
     if (governanceRaw === undefined) {
         const lifted = legacyGovernanceFromRuntime(getRaw("runtime"));
-        // 兼容臂真生效时出声(1.11.0):行为一字不变,但窗要能关就得有人看得见它还开着。
+        // 兼容臂真生效时出声(2.0.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);
@@ -814,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;

package/dist/conformance/contract-adapter.js

@@ -0,0 +1,74 @@
+/**
+ * 契约仓自己的三腿适配器 —— 也是 `historical` 模式拿旧版包跑时用的同一只工厂。
+ *
+ * **它不是给消费方抄的**:消费方登记的腿必须是**自己生产代码**的入口(来源律,§2d-2);把契约包的函数
+ * 注册成腿,门证明的就只是「包等于包」。本工厂存在的理由只有两个:①契约仓自证三腿同源(对契约仓而言
+ * `buildEffective` / `readEffectiveWire` / `loadLocalConfig` **就是**它的生产入口);②historical 模式要对
+ * 一份旧版 dist 跑同样的三腿。
+ *
+ * 拒绝分层的判据(一条,不是一串特例):**ZodError 形的错 = `validate`**(某个域没通过它的 schema);
+ * 其余按腿各自的默认层 —— wire 腿是 `envelope`(它在解析任何域之前先判信封),local-root 腿是 `parse`
+ * (文件层先判:空文件 / 非 JSON / 非对象),domains 腿本来就只有校验这一层。
+ */
+import { materializeLocalRoot } from "./run.js";
+/** ZodError 形(鸭子判,不用 `instanceof` —— historical 模式下旧版 dist 可能挂在另一份 zod 上)。 */
+const isZodLike = (e) => e !== null && typeof e === "object" && Array.isArray(e.issues);
+/** 内容哈希那一层拒绝的自述 —— `stableStringify` 的深度闸是**本包自己**抛的、也只有它会抛这一句;
+ *  适配器给自家流水线分层,认得自家那句话是合理的(消费方的适配器认它自己那几层的错)。 */
+const HASH_STAGE_MARK = "stableStringify:";
+const reject = (e, fallback) => {
+    const diagnostics = e instanceof Error ? e.message : String(e);
+    const stage = isZodLike(e) ? "validate" : diagnostics.startsWith(HASH_STAGE_MARK) ? "hash" : fallback;
+    return { outcome: "rejected", stage, diagnostics };
+};
+export function createContractAdapter(opts) {
+    const { mod } = opts;
+    const run = async (input) => {
+        const warnings = [];
+        const onWarning = (w) => void warnings.push(w);
+        switch (input.leg) {
+            case "domains":
+                try {
+                    const effective = mod.buildEffective(input.version, (d) => input.docs[d], input.updatedAt, onWarning);
+                    return { outcome: "effective", effective, warnings: warnings };
+                }
+                catch (e) {
+                    return reject(e, "validate");
+                }
+            case "wire":
+                try {
+                    const effective = mod.readEffectiveWire(input.payload, onWarning);
+                    return { outcome: "effective", effective, warnings: warnings };
+                }
+                catch (e) {
+                    return reject(e, "envelope");
+                }
+            case "localRoot": {
+                const { root, cleanup } = await materializeLocalRoot(input.files, input.mtime);
+                try {
+                    const lc = await mod.loadLocalConfig(root, { onWarning });
+                    return { outcome: "effective", effective: lc.effective, warnings: lc.warnings };
+                }
+                catch (e) {
+                    return reject(e, "parse");
+                }
+                finally {
+                    await cleanup();
+                }
+            }
+            default: {
+                const unhandled = input;
+                throw new Error(`conformance: unknown leg input ${JSON.stringify(unhandled)}`);
+            }
+        }
+    };
+    return {
+        name: opts.name,
+        provenance: opts.provenance,
+        legs: {
+            domains: { entry: opts.entries.domains, run },
+            wire: { entry: opts.entries.wire, run },
+            localRoot: { entry: opts.entries.localRoot, run },
+        },
+    };
+}