@sema-agent/settings-schema 14.5.0 → 14.7.0

package/dist/one-time-migrations.js

@@ -33,7 +33,8 @@ import { outgoingPath, redactSecrets } from "./config-fns.js";
 import { LANE_ENV_OWNER, STORE_ENV_KEYS, isLaneEnvKey } from "./execution-lane-index.js";
 import { EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js";
 import { INTEGER } from "./integer.js";
-import { isPlainJsonObject } from "./plain-json-object.js";
+import { NOT_PLAIN_DATA, UNINSPECTABLE, UninspectableError, captureJson, dataDescriptor, emptyDocument, inspect, ownEntriesOf, ownOrThrow, readDeclaredKey, sentenceOfMinted } from "./own-key-read.js";
+import { isJsonArray, isPlainJsonObject, jsonShapeOf } from "./plain-json-object.js";
 import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
 import { RETIRED_ROLE_WORDS } from "./retired-role-words.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
@@ -198,8 +199,22 @@ export const ONE_TIME_MIGRATIONS = [
  * 重跑恒等:第二次跑零改动,只剩第一次就 `refused` 的那几张收据(那些坐标原样留着,读侧照旧拒)。
  */
 export function migrateStoredDocuments(docs, opts) {
-    if (!isPlainJsonObject(docs))
-        throw new TypeError("migrateStoredDocuments: `docs` must be a { domain: document } object");
+    const docsShape = jsonShapeOf(docs);
+    switch (docsShape) {
+        case "plain":
+            break;
+        case "uninspectable": // 文档集本身读不出(撤销的 Proxy / 陷阱抛):不是「形状不对」,是「读不出」—— 带全包那一句
+            throw new TypeError(`migrateStoredDocuments: the stored documents could not be read — ${UNINSPECTABLE}`);
+        case "non_plain_object":
+        case "array":
+        case "null":
+        case "primitive":
+            throw new TypeError("migrateStoredDocuments: `docs` must be a { domain: document } object");
+        default: {
+            const unhandled = docsShape;
+            throw new Error(`migrateStoredDocuments: unhandled shape ${String(unhandled)}`);
+        }
+    }
     switch (opts.coverage) {
         case "scope":
         case "partial":
@@ -209,20 +224,35 @@ export function migrateStoredDocuments(docs, opts) {
             throw new TypeError(`migrateStoredDocuments: coverage must be "scope" or "partial" (got ${JSON.stringify(unhandled)})`);
         }
     }
-    const out = { ...docs };
+    // 工作副本是**隔离原型**(`COPY_PROTOTYPE`,没有继承来的成员)的袋(它的读没有继承可说:`Object.prototype.models` 被污染成数据值时,`out.models` 不会读到一份「存储文档」),文档集只读一次(每个域文档一个值);
+    // 之后每一步对文档里固定键的读都经内核的自有键读(`ownOrThrow`),读不出的存储文档 ⇒ 下面那一处统一抛 TypeError(带全包唯一那一句)—— 迁移本来就是抛的读口,不另造失败臂
+    const entries = ownEntriesOf(docs);
+    if (!entries.ok)
+        throw new TypeError(`migrateStoredDocuments: the stored documents could not be read — ${entries.sentence}`);
+    const out = emptyDocument();
+    for (const [k, v] of entries.value)
+        Object.defineProperty(out, k, dataDescriptor(v));
     const receipts = [];
     // 步序的律:纯改写步在前,拿新 schema 终判改写结果的步(SS-M4)最后 —— 它判的是**全部**改写之后的行,别的步能修好的形(例:SS-M7 剥掉的
     // fragment)不会先被它拒掉(否则一跑 refused、二跑才过:既不是一次完成,也不幂等)。
-    stepRuntimeDomain(out, opts.coverage, receipts);
-    stepHostsBounds(out, receipts);
-    stepModelKeyOneOf(out, receipts);
-    stepAtMention(out, receipts);
-    stepRetiredRoleWords(out, receipts);
-    stepModelsDefault(out, receipts);
-    stepPromptsAxes(out, receipts);
-    stepUrlFragments(out, receipts);
-    stepWorkers6x(out, receipts);
-    return { docs: out, receipts };
+    try {
+        stepRuntimeDomain(out, opts.coverage, receipts);
+        stepHostsBounds(out, receipts);
+        stepModelKeyOneOf(out, receipts);
+        stepAtMention(out, receipts);
+        stepRetiredRoleWords(out, receipts);
+        stepModelsDefault(out, receipts);
+        stepPromptsAxes(out, receipts);
+        stepUrlFragments(out, receipts);
+        stepWorkers6x(out, receipts);
+    }
+    catch (e) {
+        const sentence = sentenceOfMinted(e);
+        if (sentence !== undefined)
+            throw new TypeError(`migrateStoredDocuments: a stored document could not be read — ${sentence}`);
+        throw e;
+    }
+    return { docs: { ...out }, receipts }; // 交出去的是寻常对象(隔离原型的袋只是工作副本)
 }
 /**
  * 迁移一份冻结的 effective(见文件头「入口」):域键过与 {@link migrateStoredDocuments} 同一组步(coverage `"scope"` —— effective 里每个域
@@ -230,29 +260,68 @@ export function migrateStoredDocuments(docs, opts) {
  * 不是对象 ⇒ 原样返回(判形是读者的事)。
  */
 export function migrateEffectiveSnapshot(effective) {
-    if (!isPlainJsonObject(effective))
-        return { effective, receipts: [] };
-    const docs = {};
-    for (const [k, v] of Object.entries(effective))
+    // 判形是读者的事:不是朴素对象(null / 数组 / 原始值 / 类实例)⇒ 原样返回;**读不出**(撤销的 Proxy / 陷阱抛)不是「不是这个形」,是读不出 ⇒ 抛(与文档集同一句)
+    const effectiveShape = jsonShapeOf(effective);
+    switch (effectiveShape) {
+        case "plain":
+            break;
+        case "uninspectable":
+            throw new TypeError(`migrateEffectiveSnapshot: the effective snapshot could not be read — ${UNINSPECTABLE}`);
+        case "non_plain_object":
+        case "array":
+        case "null":
+        case "primitive":
+            return { effective, receipts: [] };
+        default: {
+            const unhandled = effectiveShape;
+            throw new Error(`migrateEffectiveSnapshot: unhandled shape ${String(unhandled)}`);
+        }
+    }
+    const read = ownEntriesOf(effective);
+    if (!read.ok)
+        throw new TypeError(`migrateEffectiveSnapshot: the effective snapshot could not be read — ${read.sentence}`);
+    const entriesOfEffective = read.value;
+    const docs = emptyDocument();
+    for (const [k, v] of entriesOfEffective)
         if (isDomainName(k) || isRetiredDomainName(k))
-            docs[k] = v;
+            Object.defineProperty(docs, k, dataDescriptor(v));
     const m = migrateStoredDocuments(docs, { coverage: "scope" });
     const changed = Object.keys(docs).some((k) => !Object.prototype.hasOwnProperty.call(m.docs, k) || m.docs[k] !== docs[k]) || Object.keys(m.docs).some((k) => !Object.prototype.hasOwnProperty.call(docs, k));
     if (!changed)
         return { effective, receipts: m.receipts };
-    const next = {};
-    for (const [k, v] of Object.entries(effective)) {
+    const next = emptyDocument();
+    for (const [k, v] of entriesOfEffective) {
         if (!(isDomainName(k) || isRetiredDomainName(k)))
-            next[k] = v;
+            Object.defineProperty(next, k, dataDescriptor(v));
         else if (Object.prototype.hasOwnProperty.call(m.docs, k))
-            next[k] = m.docs[k];
+            Object.defineProperty(next, k, dataDescriptor(m.docs[k]));
     }
     for (const [k, v] of Object.entries(m.docs))
         if (!Object.prototype.hasOwnProperty.call(next, k))
-            next[k] = v;
-    return { effective: next, receipts: m.receipts };
+            Object.defineProperty(next, k, dataDescriptor(v));
+    return { effective: { ...next }, receipts: m.receipts };
 }
-const has = (o, k) => isPlainJsonObject(o) && Object.prototype.hasOwnProperty.call(o, k);
+/** `o` 是朴素对象且**自有**键 `k` 在场(描述符律,与 `ownOrThrow` 同一只核:访问器 / 不可枚举的自有键不当缺席 ⇒ 抛带「不是纯数据」那一句;读不出 ⇒ 抛;迁移本来就抛)。 */
+const has = (o, k) => {
+    if (!isPlainJsonObject(o))
+        return false;
+    const read = readDeclaredKey(o, k);
+    switch (read.presence) {
+        case "own":
+            return true;
+        case "inherited":
+        case "absent":
+            return false;
+        case "hidden":
+            throw new UninspectableError(NOT_PLAIN_DATA);
+        case "unreadable":
+            throw new UninspectableError();
+        default: {
+            const unhandled = read;
+            throw new Error(`has: unhandled presence ${String(unhandled.presence)}`);
+        }
+    }
+};
 const without = (o, k) => {
     const { [k]: _gone, ...rest } = o;
     return rest;
@@ -282,7 +351,7 @@ const LIMIT_KEYS = ["rateLimitPerMin", "maxTaskCostUsd", "maxTaskTokens", "maxPr
 function stepRuntimeDomain(out, coverage, receipts) {
     if (!Object.prototype.hasOwnProperty.call(out, "runtime"))
         return;
-    const raw = out.runtime;
+    const raw = ownOrThrow(out, "runtime");
     if (raw === undefined)
         return;
     const refuse = (reason) => void receipts.push(refused("SS-M1", "runtime", [], reason));
@@ -299,14 +368,14 @@ function stepRuntimeDomain(out, coverage, receipts) {
     const parsed = RUNTIME_10X.safeParse(raw);
     if (!parsed.success)
         return refuse("the stored runtime document does not read under the 10.x runtime schema — the scope does not read today either; fix it by hand");
-    const limitsRaw = out.limits;
+    const limitsRaw = ownOrThrow(out, "limits");
     if (limitsRaw !== undefined && !isPlainJsonObject(limitsRaw))
         return refuse("the scope's limits document is not a JSON object — the scope does not read today either; fix limits first");
-    const trio = GOVERNANCE_TRIO.filter((k) => has(raw, k) && raw[k] !== undefined);
+    const trio = GOVERNANCE_TRIO.filter((k) => has(raw, k) && ownOrThrow(raw, k) !== undefined);
     if (trio.length > 0) {
         // 迁移前的读法:governance 域**从未设过**(店里没有这份文档)⇒ 读侧从 runtime 抬升三闸;设过 ⇒ 设过的那份赢,runtime 上的三闸从未生效。
-        if (out.governance === undefined) {
-            out.governance = Object.fromEntries(trio.map((k) => [k, raw[k]]));
+        if (ownOrThrow(out, "governance") === undefined) {
+            out.governance = Object.fromEntries(trio.map((k) => [k, ownOrThrow(raw, k)]));
             for (const k of trio)
                 receipts.push(moved("SS-M1", "runtime", [k], { document: "governance", path: [k] }));
         }
@@ -340,14 +409,17 @@ function stepRuntimeDomain(out, coverage, receipts) {
 }
 // ── SS-M2:hosts 超界 ───────────────────────────────────────────────────────────────────────────────────
 function stepHostsBounds(out, receipts) {
-    const doc = out.hosts;
-    if (!isPlainJsonObject(doc) || !Array.isArray(doc.hosts))
+    const doc = ownOrThrow(out, "hosts");
+    if (!isPlainJsonObject(doc))
+        return;
+    const hostRows = ownOrThrow(doc, "hosts");
+    if (!isJsonArray(hostRows))
         return;
-    const rows = doc.hosts;
+    const rows = hostRows;
     let kept = [];
     const dropped = [];
     rows.forEach((row, index) => {
-        const name = isPlainJsonObject(row) ? row.name : undefined;
+        const name = isPlainJsonObject(row) ? ownOrThrow(row, "name") : undefined;
         if (typeof name === "string" && name.length > HOST_NAME_MAX)
             dropped.push(index);
         else
@@ -394,18 +466,33 @@ const UNCHANGED = { kind: "unchanged" };
  * `DB_BACKEND` / `MEMORY_ENGINE` / `MEMORY_ENGINE_BACKEND` ⇒ 搬进 `store`。表达不了 ⇒ 拒:值写错了栏、不认识的词、新旧两形并存、
  * `DB_BACKEND=pg` 配 MySQL 族坐标。不是 6.x 形的行(没有任何旧键,该有的块都在)⇒ 不动 —— 它读不读得进是 `readWorkersRows` 的事。
  */
-function migrateWorkerRow(raw) {
+function migrateWorkerRow(row) {
     const refuse = (field, reason) => ({ kind: "refused", field, reason });
-    const enabled = raw.enabled !== false;
-    const laneKeysOf = (rec) => (isPlainJsonObject(rec) ? Object.keys(rec).filter(isLaneEnvKey) : []);
-    const storeKeysOf = (rec) => (isPlainJsonObject(rec) ? STORE_ENV_KEYS.filter((k) => Object.hasOwn(rec, k)) : []);
-    const envLaneKeys = laneKeysOf(raw.env);
-    const secretLaneKeys = laneKeysOf(raw.secretEnv);
-    const envStoreKeys = storeKeysOf(raw.env);
-    const secretStoreKeys = storeKeysOf(raw.secretEnv);
-    const oldStoreFields = SIX_X_STORE_FIELDS.filter(([c, k]) => has(raw[c], k));
-    const hasExecution = has(raw.runtime, "execution");
-    const hasStore = has(raw.runtime, "store");
+    // ① 判「这一行要不要迁」只做**浅读**:行上的固定键、`env` / `secretEnv` / `runtime` / `coords` / `secretRefs` 这几块的键名与在场(自有键,读不出 ⇒ 抛)—— 不碰别的字段,更不整行深拷:
+    // 没有 6.x 键的行(绝大多数)一个字段都不动,所以一份合法的、哪个别的字段嵌了多深的存量文档都不会因为这一步抛(v14.6.0 的答案);拒因也都是浅读给得出的,不必先拷。
+    const peek = (o, k) => (isPlainJsonObject(o) ? ownOrThrow(o, k) : undefined);
+    const keysOfRec = (rec) => {
+        if (!isPlainJsonObject(rec))
+            return [];
+        const keys = inspect(() => Object.keys(rec));
+        if (!keys.ok)
+            throw new UninspectableError();
+        return keys.value;
+    };
+    const enabled = peek(row, "enabled") !== false;
+    const rawEnv = peek(row, "env");
+    const rawSecretEnv = peek(row, "secretEnv");
+    const rawRuntime = peek(row, "runtime");
+    const rawSecretRefs = peek(row, "secretRefs");
+    const laneKeysOf = (rec) => keysOfRec(rec).filter(isLaneEnvKey);
+    const storeKeysOf = (rec) => (isPlainJsonObject(rec) ? STORE_ENV_KEYS.filter((k) => has(rec, k)) : []);
+    const envLaneKeys = laneKeysOf(rawEnv);
+    const secretLaneKeys = laneKeysOf(rawSecretEnv);
+    const envStoreKeys = storeKeysOf(rawEnv);
+    const secretStoreKeys = storeKeysOf(rawSecretEnv);
+    const oldStoreFields = SIX_X_STORE_FIELDS.filter(([c, k]) => has(peek(row, c), k));
+    const hasExecution = has(rawRuntime, "execution");
+    const hasStore = has(rawRuntime, "store");
     const laneTouched = envLaneKeys.length + secretLaneKeys.length > 0;
     const storeTouched = oldStoreFields.length + envStoreKeys.length + secretStoreKeys.length > 0;
     if (!laneTouched && !storeTouched)
@@ -414,7 +501,7 @@ function migrateWorkerRow(raw) {
         return refuse(["runtime", "execution"], `declares runtime.execution AND execution-lane keys in env / secretEnv (${[...envLaneKeys, ...secretLaneKeys].join(", ")}) — keep one form; the migration does not pick a winner`);
     }
     // 新形的店字段有两处:`runtime.store` 与 `secretRefs.dbPasswordEnv`。任一在场 ∧ 还有旧店字段 ⇒ 两形并存,不挑赢家。
-    const newStoreFields = [...(hasStore ? ["runtime.store"] : []), ...(has(raw.secretRefs, "dbPasswordEnv") ? ["secretRefs.dbPasswordEnv"] : [])];
+    const newStoreFields = [...(hasStore ? ["runtime.store"] : []), ...(has(rawSecretRefs, "dbPasswordEnv") ? ["secretRefs.dbPasswordEnv"] : [])];
     if (newStoreFields.length > 0 && storeTouched) {
         const old = [...oldStoreFields.map(([c, k]) => `${c}.${k}`), ...envStoreKeys.map((k) => `env.${k}`), ...secretStoreKeys.map((k) => `secretEnv.${k}`)];
         return refuse(["runtime", "store"], `declares the 7.0.0 store fields (${newStoreFields.join(", ")}) AND 6.x store fields (${old.join(", ")}) — keep one form; the migration does not pick a winner`);
@@ -422,17 +509,25 @@ function migrateWorkerRow(raw) {
     const secretStoreKey = secretStoreKeys[0];
     if (secretStoreKey !== undefined)
         return refuse(["secretEnv", secretStoreKey], `${secretStoreKey} is set from a host secret — the migration cannot read it; declare runtime.store by hand`);
-    if (has(raw.secretEnv, "REMOTE_EXEC"))
+    if (has(rawSecretEnv, "REMOTE_EXEC"))
         return refuse(["secretEnv", "REMOTE_EXEC"], "the execution lane is set from a host secret — the migration cannot read it; declare runtime.execution.lane by hand");
     const needLane = !hasExecution && (enabled || laneTouched);
     const needStore = !hasStore && (enabled || storeTouched);
-    const w = structuredClone(raw);
-    const runtime = isPlainJsonObject(w.runtime) ? w.runtime : {};
+    // 收尾要问「原来的 env / secretEnv 有没有键」:在拷之前、浅读里问好
+    const envHadKeys = keysOfRec(rawEnv).length > 0;
+    const secretEnvHadKeys = keysOfRec(rawSecretEnv).length > 0;
+    // ② 只有**要改写的行**才拍快照:整行的自有键深副本(隔离原型,值只从每个成员那一份描述符里取,没有字面深度上限 —— JSON 往返能成的都拷得出);下面对 `env` / `coords` / `runtime` / `secretRefs` 里固定键的读
+    // 都读在副本上,没写的键不会被 `Object.prototype` 上被污染的同名数据值填上(那会把污染值写进改写后的存储行)。坏形只有三种:读不出 / 环 / 非纯数据 ⇒ 抛(迁移本来就抛,上一层统一成 TypeError)
+    const working = captureJson(row);
+    if (!working.ok)
+        throw new UninspectableError(working.sentence);
+    const w = working.value;
+    const runtime = isPlainJsonObject(w.runtime) ? w.runtime : emptyDocument();
     w.runtime = runtime;
-    const env = isPlainJsonObject(w.env) ? w.env : {};
-    const secretEnv = isPlainJsonObject(w.secretEnv) ? w.secretEnv : {};
-    const coords = isPlainJsonObject(w.coords) ? w.coords : {};
-    const secretRefs = isPlainJsonObject(w.secretRefs) ? w.secretRefs : {};
+    const env = isPlainJsonObject(w.env) ? w.env : emptyDocument();
+    const secretEnv = isPlainJsonObject(w.secretEnv) ? w.secretEnv : emptyDocument();
+    const coords = isPlainJsonObject(w.coords) ? w.coords : emptyDocument();
+    const secretRefs = isPlainJsonObject(w.secretRefs) ? w.secretRefs : emptyDocument();
     const dropped = [];
     const drop = (container, slot, key) => {
         delete container[key];
@@ -456,8 +551,8 @@ function migrateWorkerRow(raw) {
                 return refuse(["env", "REMOTE_EXEC"], `env.REMOTE_EXEC ${describeWord(rx)} is not an execution lane (${EXECUTION_LANE_WORDS.join(" | ")}) — the engine refuses to start with it; set runtime.execution.lane by hand`);
             }
             const lane = rx;
-            const laneCoords = {};
-            const laneSecretRefs = {};
+            const laneCoords = emptyDocument();
+            const laneSecretRefs = emptyDocument();
             for (const k of envLaneKeys) {
                 if (k === "REMOTE_EXEC") {
                     delete env[k];
@@ -545,7 +640,9 @@ function migrateWorkerRow(raw) {
             }
             delete env.DB_BACKEND;
             const sqlCoordsPresent = sqlCoordFields.filter(([c, , k]) => Object.hasOwn(c, k));
-            const store = { backend, session };
+            const store = emptyDocument();
+            store.backend = backend;
+            store.session = session;
             if (backend === "mysql") {
                 if (hostSet) {
                     const port = coords.tidbPort;
@@ -570,7 +667,7 @@ function migrateWorkerRow(raw) {
                 for (const [c, slot, k] of sqlCoordsPresent)
                     drop(c, slot, k); // 非 SQL 店:SQL 坐标是「声明不用」的惰性件
             }
-            const memory = {};
+            const memory = emptyDocument();
             const engineRaw = env.MEMORY_ENGINE;
             if (engineRaw !== undefined) {
                 const word = typeof engineRaw === "string" ? engineRaw.trim().toLowerCase() : undefined;
@@ -596,24 +693,30 @@ function migrateWorkerRow(raw) {
         }
     }
     // 被搬空的 env / secretEnv 整键去掉(它们是可选字段;留一个 `{}` 只是噪声)
-    if (isPlainJsonObject(w.env) && Object.keys(env).length === 0 && isPlainJsonObject(raw.env) && Object.keys(raw.env).length > 0)
+    if (isPlainJsonObject(w.env) && Object.keys(env).length === 0 && envHadKeys)
         delete w.env;
-    if (isPlainJsonObject(w.secretEnv) && Object.keys(secretEnv).length === 0 && isPlainJsonObject(raw.secretEnv) && Object.keys(raw.secretEnv).length > 0)
+    if (isPlainJsonObject(w.secretEnv) && Object.keys(secretEnv).length === 0 && secretEnvHadKeys)
         delete w.secretEnv;
     // 改写后的行仍读不进 7.x 形 ⇒ 不写回半成品:拒,原文留盘(读口 `readWorkersRows` 扣下它)。判据与拒句是读口那一只(`workerRowVerdict`)。
     const verdict = workerRowVerdict(w, "migrated");
     if (verdict !== undefined)
         return refuse(verdict.field, verdict.reason);
-    return { kind: "rewritten", row: w, dropped };
+    const out = captureJson(w, "ordinary"); // 交出去的是寻常对象(隔离原型的深副本只是工作副本)
+    if (!out.ok)
+        throw new UninspectableError(out.sentence);
+    return { kind: "rewritten", row: out.value, dropped };
 }
 function stepWorkers6x(out, receipts) {
-    const doc = out.workers;
-    if (!isPlainJsonObject(doc) || !Array.isArray(doc.workers))
+    const doc = ownOrThrow(out, "workers");
+    if (!isPlainJsonObject(doc))
+        return;
+    const workerRows = ownOrThrow(doc, "workers");
+    if (!isJsonArray(workerRows))
         return;
-    const rows = doc.workers;
+    const rows = workerRows;
     let next;
     rows.forEach((row, index) => {
-        if (!isPlainJsonObject(row) || typeof row.name !== "string")
+        if (!isPlainJsonObject(row) || typeof ownOrThrow(row, "name") !== "string")
             return; // 认不出名字:整域读侧判
         const r = migrateWorkerRow(row);
         switch (r.kind) {
@@ -640,16 +743,19 @@ function stepWorkers6x(out, receipts) {
 }
 // ── SS-M5:模型钥匙二选一 ──────────────────────────────────────────────────────────────────────────────
 function stepModelKeyOneOf(out, receipts) {
-    const doc = out.models;
-    if (!isPlainJsonObject(doc) || !Array.isArray(doc.models))
+    const doc = ownOrThrow(out, "models");
+    if (!isPlainJsonObject(doc))
+        return;
+    const modelRows = ownOrThrow(doc, "models");
+    if (!isJsonArray(modelRows))
         return;
-    const rows = doc.models;
+    const rows = modelRows;
     let next;
     rows.forEach((row, index) => {
         if (!(has(row, "sealedApiKey") && has(row, "apiKeyEnv")))
             return;
         const r = row;
-        if (r.sealedApiKey === undefined || r.apiKeyEnv === undefined)
+        if (ownOrThrow(r, "sealedApiKey") === undefined || ownOrThrow(r, "apiKeyEnv") === undefined)
             return;
         next ??= [...rows];
         next[index] = without(r, "apiKeyEnv");
@@ -663,12 +769,12 @@ function stepModelKeyOneOf(out, receipts) {
 function rewriteAtMention(holder, document, at, receipts) {
     if (!Object.prototype.hasOwnProperty.call(holder, "atModelAllowlist"))
         return undefined;
-    const list = holder.atModelAllowlist;
+    const list = ownOrThrow(holder, "atModelAllowlist");
     if (Object.prototype.hasOwnProperty.call(holder, "atMention")) {
         receipts.push(refused("SS-M6", document, [...at, "atModelAllowlist"], "both atModelAllowlist and atMention are set — keep one; the migration does not pick a winner"));
         return undefined;
     }
-    if (!Array.isArray(list) || !list.every((n) => typeof n === "string")) {
+    if (!isJsonArray(list) || !list.every((n) => typeof n === "string")) {
         receipts.push(refused("SS-M6", document, [...at, "atModelAllowlist"], "atModelAllowlist is not a list of model names — it does not read today either; fix it by hand"));
         return undefined;
     }
@@ -677,14 +783,16 @@ function rewriteAtMention(holder, document, at, receipts) {
     return { ...without(holder, "atModelAllowlist"), atMention };
 }
 function stepAtMention(out, receipts) {
-    if (isPlainJsonObject(out.models)) {
-        const next = rewriteAtMention(out.models, "models", [], receipts);
+    const modelsDoc = ownOrThrow(out, "models");
+    if (isPlainJsonObject(modelsDoc)) {
+        const next = rewriteAtMention(modelsDoc, "models", [], receipts);
         if (next !== undefined)
             out.models = next;
     }
-    const rosters = out.rosters;
-    if (isPlainJsonObject(rosters) && Array.isArray(rosters.rosters)) {
-        const rows = rosters.rosters;
+    const rosters = ownOrThrow(out, "rosters");
+    const rosterRows = isPlainJsonObject(rosters) ? ownOrThrow(rosters, "rosters") : undefined;
+    if (isPlainJsonObject(rosters) && isJsonArray(rosterRows)) {
+        const rows = rosterRows;
         let next;
         rows.forEach((row, index) => {
             if (!isPlainJsonObject(row))
@@ -715,20 +823,21 @@ function withoutRetiredRoles(roles, document, at, receipts) {
     return next;
 }
 function stepRetiredRoleWords(out, receipts) {
-    const models = out.models;
+    const models = ownOrThrow(out, "models");
     if (isPlainJsonObject(models)) {
-        const roles = withoutRetiredRoles(models.roles, "models", [], receipts);
+        const roles = withoutRetiredRoles(ownOrThrow(models, "roles"), "models", [], receipts);
         if (roles !== undefined)
             out.models = { ...models, roles };
     }
-    const rosters = out.rosters;
-    if (isPlainJsonObject(rosters) && Array.isArray(rosters.rosters)) {
-        const rows = rosters.rosters;
+    const rosters = ownOrThrow(out, "rosters");
+    const rosterRows = isPlainJsonObject(rosters) ? ownOrThrow(rosters, "rosters") : undefined;
+    if (isPlainJsonObject(rosters) && isJsonArray(rosterRows)) {
+        const rows = rosterRows;
         let next;
         rows.forEach((row, index) => {
             if (!isPlainJsonObject(row))
                 return;
-            const roles = withoutRetiredRoles(row.roles, "rosters", ["rosters", index], receipts);
+            const roles = withoutRetiredRoles(ownOrThrow(row, "roles"), "rosters", ["rosters", index], receipts);
             if (roles === undefined)
                 return;
             next ??= [...rows];
@@ -743,17 +852,18 @@ function stepRetiredRoleWords(out, receipts) {
  *  = B 时主任务跑 A,core 的 `default` 角色解到 B)。所以并过去的是 `default` 的值:`roles.default` 缺席 ⇒ 搬入;同名 ⇒ 搬入(重复的那一份
  *  消失);异名 ⇒ 原 `roles.default` 作「被压过」删掉、`default` 搬入。`default` 不是非空串 ⇒ 拒(今天它让整个 models 域读不进,不替运维猜)。 */
 function stepModelsDefault(out, receipts) {
-    const doc = out.models;
+    const doc = ownOrThrow(out, "models");
     if (!isPlainJsonObject(doc) || !Object.prototype.hasOwnProperty.call(doc, "default"))
         return;
-    const name = doc.default;
+    const name = ownOrThrow(doc, "default");
     if (typeof name !== "string" || name === "") {
         receipts.push(refused("SS-M9", "models", ["default"], "models.default is not a catalog name — it does not read today either; fix it by hand"));
         return;
     }
-    const roles = isPlainJsonObject(doc.roles) ? doc.roles : {};
-    const prior = roles.default;
-    if (prior !== undefined && !(isPlainJsonObject(prior) && prior.model === name))
+    const docRoles = ownOrThrow(doc, "roles");
+    const roles = isPlainJsonObject(docRoles) ? docRoles : emptyDocument();
+    const prior = ownOrThrow(roles, "default");
+    if (prior !== undefined && !(isPlainJsonObject(prior) && ownOrThrow(prior, "model") === name))
         receipts.push(receipt("SS-M9", "models", ["roles", "default"], "dropped-shadowed"));
     receipts.push(moved("SS-M9", "models", ["default"], { document: "models", path: ["roles", "default"] }));
     out.models = { ...without(doc, "default"), roles: { ...roles, default: { model: name } } };
@@ -763,12 +873,13 @@ function stepModelsDefault(out, receipts) {
  *  从不下发任何内容)删掉。非空 `bindings` / 不是数组的 `bindings` / `catalog` 一律 refused、原样留着 —— 声明要经中心的卡编译器才编得成
  *  overlay,catalog 的 digest 是引擎铸的,替运维机械转就是第二个编译器 / 第二个铸点。`prompts` 不是对象 ⇒ 不动(判形是读者的事)。 */
 function stepPromptsAxes(out, receipts) {
-    const doc = out.prompts;
+    const doc = ownOrThrow(out, "prompts");
     if (!isPlainJsonObject(doc))
         return;
     let next = doc;
-    if (has(doc, "bindings") && doc.bindings !== undefined) {
-        if (Array.isArray(doc.bindings) && doc.bindings.length === 0) {
+    const bindings = has(doc, "bindings") ? ownOrThrow(doc, "bindings") : undefined;
+    if (bindings !== undefined) {
+        if (isJsonArray(bindings) && bindings.length === 0) {
             next = without(next, "bindings");
             receipts.push(receipt("SS-M10", "prompts", ["bindings"], "dropped-inert"));
         }
@@ -777,7 +888,7 @@ function stepPromptsAxes(out, receipts) {
                 "(a local config.d copy was never read by the engine: delete the key)"));
         }
     }
-    if (has(doc, "catalog") && doc.catalog !== undefined) {
+    if (has(doc, "catalog") && ownOrThrow(doc, "catalog") !== undefined) {
         receipts.push(refused("SS-M10", "prompts", ["catalog"], "a v1 catalog cannot be converted (its digest is the engine's) — republish from the web-admin, or rebuild with the engine's buildPromptArtifact"));
     }
     if (next !== doc)
@@ -823,7 +934,7 @@ function stripFragments(schema, value, path, onStrip, depth = 0) {
             if (!(o instanceof z.ZodObject))
                 continue;
             const lit = unwrapSchema(o.shape[disc]);
-            if (lit instanceof z.ZodLiteral && lit.values.has(value[disc]))
+            if (lit instanceof z.ZodLiteral && lit.values.has(ownOrThrow(value, disc)))
                 return stripFragments(o, value, path, onStrip, depth + 1);
         }
         return value;
@@ -843,14 +954,15 @@ function stripFragments(schema, value, path, onStrip, depth = 0) {
         for (const [k, fieldSchema] of Object.entries(s.shape)) {
             if (!Object.prototype.hasOwnProperty.call(value, k))
                 continue;
-            const v = stripFragments(fieldSchema, value[k], [...path, k], onStrip, depth + 1);
-            if (v !== value[k])
+            const held = ownOrThrow(value, k);
+            const v = stripFragments(fieldSchema, held, [...path, k], onStrip, depth + 1);
+            if (v !== held)
                 (next ??= { ...value })[k] = v;
         }
         return next ?? value;
     }
     if (s instanceof z.ZodArray) {
-        if (!Array.isArray(value))
+        if (!isJsonArray(value))
             return value;
         let next;
         value.forEach((el, i) => {