@sema-agent/settings-schema 14.6.0 → 14.7.0

package/dist/declared-capture.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 包内私有(不进主桶):**按声明键投影的快照,与校验合在一起** —— 校验器(zod)读一个对象时只读它声明的键、剥掉其余;要保护它别读到 `Object.prototype` 上被污染的继承值、别碰会抛的 getter,
+ * 就得给它一份**自有键副本**。整份深拷({@link captureJson})会把「校验器根本不读」的键(没声明的键里放着 `Date` / `Map` / 函数 / 环 / 一个会抛的 getter)也读进来 ——
+ * 一个本来读得通的 body 变成整体读不出。所以:**只捕获校验器会读的键**,而「会读哪些键」随联合选哪一臂而定,所以投影与校验一起走({@link parseDeclared})。
+ *
+ *  · 对象形(`z.object`,没有 catchall —— 即「剥掉没声明的键」那一种):只读它声明的键(`shape` 的键),每个声明键的值按**对应子 schema** 递归;没声明的键一个都不读不拷;
+ *  · **判别联合**:先按判别键(与声明键同一只描述符读)选臂,**只投影选中那一臂**的声明键;判别键**只读一次** —— 选臂的那个词就是快照里交给校验器的那个词;
+ *    判别键缺席 / 不是任何一臂的词 ⇒ 只交过去判别键(校验器只看它就拒);
+ *  · **普通联合**(顶层):按序逐臂 —— 一臂一份只含该臂声明键的快照、**只拿该臂的 schema 校验**,该臂通过才接受、**第一臂通过即止**,没通过才轮到下一臂(与 zod 按序试臂一致;不取并集;
+ *    拿整个联合去校验的话,后臂会用默认值接受前一臂的残缺投影);**互斥联合**(`z.xor`)所有臂都走一遍、恰一臂通过才接受(两臂都通过 zod 拒,这里同样拒)。
+ *    嵌在对象里的普通联合、以及套着包装层的联合当不透明:整个值深拷、对整只 schema 校验;
+ *  · `unknown` / `any`(投影走到的位置上):校验器自己不看它的内容 ⇒ 调用方的原值原样交过去(后面接的 transform 是包自己写的);
+ *  · 其余(标量、`record`、数组、`strict` 的对象 —— 校验器要读全部键):整个值深拷(不透明)。
+ * 声明键的律与内核同:自有但不可枚举 ⇒ 读不成纯数据、整份拒({@link NOT_PLAIN_DATA}),**不当缺席**;自有 getter 抛 / 陷阱抛 ⇒ {@link UNINSPECTABLE};只靠继承 ⇒ 缺席。
+ * 任何一份快照拿不到(读不出 / 拒)⇒ 整个读不出(不再试后面的臂:v14.6.0 里校验器在那里读到的会抛)。守护在 {@link parseDeclared} 入口一处:门的 schema 内省、快照递归与校验同在里面。
+ *
+ * **门 = 闭集白名单**(`admit`,每只 schema 第一次进来时走一遍整棵 schema 树,通过的记下;递归 schema 按「节点 × 位置」只判一次):只放行**与 zod 同答**(判决与数据,对 JSON 输入)的节点种类
+ * —— 每一种都按 zod 4.4 / 4.6 的读法推过、有对 zod 逐例比判决与数据的钉;反例搜索不是穷举,找到不同答的形就从放行单拿掉 ——
+ * 叶子(不跑用户函数、没有子 schema)· 不跑看得见输入的函数的包装层(`optional` / `nullable` / `default` / `prefault`)· 后处理 `.transform(f)`(`f` 看到的是里面那只 schema 的输出,两边同一份)·
+ * 对象(声明键不是符号、也不叫寻常对象从 `Object.prototype` 继承来的名字 —— zod 在原值上读到继承的成员,投影读成缺席)· 判别联合(不带 `unionFallback`)· 普通 / 互斥联合 · `record` · 数组 ·
+ * 投影走到的位置上的 `unknown` / `any`。对象 / 数组 / record 上挂的检查(refine / superRefine / 长度 …)看到的是 zod 自己铸的新输出,两边同一份。
+ * 其余一律**响亮拒**(抛 `parseDeclared: unsupported schema shape — …`;这是包自己的 schema 选错了读法,不是调用方的值读不出):`.catch`(兜底函数看到整个原值 —— zod ≥ 4.6 交 `ctx.input`)·
+ * 输入侧变换(`z.preprocess`、字段位上单独的 `z.transform`、两侧都是 schema 的管道)· `z.custom`(谓词看到的是副本)· 深拷节点之下的 `unknown` / `any`(副本会进输出;passthrough 对象同因)·
+ * 声明键叫继承名 / 是符号(有限键集 record 的键同此)· loose record · 顶层普通联合自己挂的检查 · 带 `unionFallback` 的判别联合 · `tuple` / `intersection` / `map` / `set` / `lazy` / `readonly` …(没推过)。
+ * 不逐形补黑名单:新形默认拒。校验只问判决、不要句子(`evaluate` 给 zod 逐次 `error` 参数):副本的原型不是 `Object.prototype`,zod 拼拒句时会读副本上用户写的自有 `constructor`。
+ */
+import { z } from "zod";
+/**
+ * 对 `value` 校验的守护读法(`schema` 的 safeParse):校验器读的是投影后的自有键快照,不是调用方的对象。读不出 / 不是纯数据 / 校验不过 ⇒ `{ ok: false }`(不抛);
+ * 联合按 {@link evaluate} 的语义逐臂。`schema` 不在白名单里(见文件头)⇒ 抛 `parseDeclared: unsupported schema shape — …`(不论输入)。
+ * **守护边界就在这里一处**(内核的 `inspect`):白名单门对 schema 的内省(zod 的惰性属性 —— 声明键表、判别联合的 `propValues` —— 第一次被读时才物化,物化时 zod 用字面量描述符调
+ * `defineProperty`、往 `{}` 上按键名累加:`Object.prototype` 被污染成 `get` / `set` / `value` / 判别键名时,物化在这一步抛)、投影快照的递归(递归 schema × 很深的数据会爆栈)与校验,
+ * 全在同一只守护里 —— 抛了 ⇒ `{ ok: false }`(与 v14.6.0 那一层守护同向:读口答「读不出」,不把引擎的错 / 嵌入方的抛出值带出去)。
+ * 「不支持」是门**交回**的判语、在守护外抛:它是包自己的 schema 选错了读法,与输入无关。
+ */
+export declare function parseDeclared<S extends z.ZodType>(schema: S, value: unknown): {
+    readonly ok: true;
+    readonly data: z.output<S>;
+} | {
+    readonly ok: false;
+};

package/dist/declared-capture.js

@@ -0,0 +1,344 @@
+/**
+ * 包内私有(不进主桶):**按声明键投影的快照,与校验合在一起** —— 校验器(zod)读一个对象时只读它声明的键、剥掉其余;要保护它别读到 `Object.prototype` 上被污染的继承值、别碰会抛的 getter,
+ * 就得给它一份**自有键副本**。整份深拷({@link captureJson})会把「校验器根本不读」的键(没声明的键里放着 `Date` / `Map` / 函数 / 环 / 一个会抛的 getter)也读进来 ——
+ * 一个本来读得通的 body 变成整体读不出。所以:**只捕获校验器会读的键**,而「会读哪些键」随联合选哪一臂而定,所以投影与校验一起走({@link parseDeclared})。
+ *
+ *  · 对象形(`z.object`,没有 catchall —— 即「剥掉没声明的键」那一种):只读它声明的键(`shape` 的键),每个声明键的值按**对应子 schema** 递归;没声明的键一个都不读不拷;
+ *  · **判别联合**:先按判别键(与声明键同一只描述符读)选臂,**只投影选中那一臂**的声明键;判别键**只读一次** —— 选臂的那个词就是快照里交给校验器的那个词;
+ *    判别键缺席 / 不是任何一臂的词 ⇒ 只交过去判别键(校验器只看它就拒);
+ *  · **普通联合**(顶层):按序逐臂 —— 一臂一份只含该臂声明键的快照、**只拿该臂的 schema 校验**,该臂通过才接受、**第一臂通过即止**,没通过才轮到下一臂(与 zod 按序试臂一致;不取并集;
+ *    拿整个联合去校验的话,后臂会用默认值接受前一臂的残缺投影);**互斥联合**(`z.xor`)所有臂都走一遍、恰一臂通过才接受(两臂都通过 zod 拒,这里同样拒)。
+ *    嵌在对象里的普通联合、以及套着包装层的联合当不透明:整个值深拷、对整只 schema 校验;
+ *  · `unknown` / `any`(投影走到的位置上):校验器自己不看它的内容 ⇒ 调用方的原值原样交过去(后面接的 transform 是包自己写的);
+ *  · 其余(标量、`record`、数组、`strict` 的对象 —— 校验器要读全部键):整个值深拷(不透明)。
+ * 声明键的律与内核同:自有但不可枚举 ⇒ 读不成纯数据、整份拒({@link NOT_PLAIN_DATA}),**不当缺席**;自有 getter 抛 / 陷阱抛 ⇒ {@link UNINSPECTABLE};只靠继承 ⇒ 缺席。
+ * 任何一份快照拿不到(读不出 / 拒)⇒ 整个读不出(不再试后面的臂:v14.6.0 里校验器在那里读到的会抛)。守护在 {@link parseDeclared} 入口一处:门的 schema 内省、快照递归与校验同在里面。
+ *
+ * **门 = 闭集白名单**(`admit`,每只 schema 第一次进来时走一遍整棵 schema 树,通过的记下;递归 schema 按「节点 × 位置」只判一次):只放行**与 zod 同答**(判决与数据,对 JSON 输入)的节点种类
+ * —— 每一种都按 zod 4.4 / 4.6 的读法推过、有对 zod 逐例比判决与数据的钉;反例搜索不是穷举,找到不同答的形就从放行单拿掉 ——
+ * 叶子(不跑用户函数、没有子 schema)· 不跑看得见输入的函数的包装层(`optional` / `nullable` / `default` / `prefault`)· 后处理 `.transform(f)`(`f` 看到的是里面那只 schema 的输出,两边同一份)·
+ * 对象(声明键不是符号、也不叫寻常对象从 `Object.prototype` 继承来的名字 —— zod 在原值上读到继承的成员,投影读成缺席)· 判别联合(不带 `unionFallback`)· 普通 / 互斥联合 · `record` · 数组 ·
+ * 投影走到的位置上的 `unknown` / `any`。对象 / 数组 / record 上挂的检查(refine / superRefine / 长度 …)看到的是 zod 自己铸的新输出,两边同一份。
+ * 其余一律**响亮拒**(抛 `parseDeclared: unsupported schema shape — …`;这是包自己的 schema 选错了读法,不是调用方的值读不出):`.catch`(兜底函数看到整个原值 —— zod ≥ 4.6 交 `ctx.input`)·
+ * 输入侧变换(`z.preprocess`、字段位上单独的 `z.transform`、两侧都是 schema 的管道)· `z.custom`(谓词看到的是副本)· 深拷节点之下的 `unknown` / `any`(副本会进输出;passthrough 对象同因)·
+ * 声明键叫继承名 / 是符号(有限键集 record 的键同此)· loose record · 顶层普通联合自己挂的检查 · 带 `unionFallback` 的判别联合 · `tuple` / `intersection` / `map` / `set` / `lazy` / `readonly` …(没推过)。
+ * 不逐形补黑名单:新形默认拒。校验只问判决、不要句子(`evaluate` 给 zod 逐次 `error` 参数):副本的原型不是 `Object.prototype`,zod 拼拒句时会读副本上用户写的自有 `constructor`。
+ */
+import { z } from "zod";
+import { NOT_PLAIN_DATA, NO_PRIOR_READS, UNINSPECTABLE, captureJson, dataDescriptor, inspect, isolatedObject, readDeclaredKey } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
+import { unwrapOnce } from "./zod-unwrap.js";
+const failed = (sentence) => ({ ok: false, sentence });
+/** 判语的句子(只在这里拼一次)。 */
+const unsupportedShape = (what) => `parseDeclared: unsupported schema shape — ${what}`;
+/** 包装层的层数界(schema 作者写出来的常数,8 层远超实际)。 */
+const WRAPPER_BOUND = 8;
+/** 剥掉投影会穿过的包装层拿内里的 schema:`optional` / `nullable` / `default` / `prefault` 与后处理 `.transform(f)`。`.catch` 与输入侧的变换不穿 —— 停在它们身上(白名单门拒它们)。 */
+function innerOf(schema) {
+    let cur = schema;
+    for (let i = 0; i < WRAPPER_BOUND; i++) {
+        const step = unwrapOnce(cur);
+        if (step === undefined || step.via === "preprocess" || cur instanceof z.ZodCatch)
+            return cur;
+        cur = step.next;
+    }
+    return cur;
+}
+/**
+ * 对象 schema 的声明键表:读 `def.shape` —— zod 自己校验时读的就是这一份(它在第一次被读时才物化,物化失败下次再试);**不读** classic 面的 `object.shape`:
+ * 那是 zod 4.4 的另一只惰性属性,物化时抛(例:`Object.prototype` 被污染)就永远答 `undefined`,而 zod 自己校验从不读它 —— 读它会让门在污染撤掉之后仍读不出,v14.6.0 不会。
+ */
+const shapeOf = (object) => object._zod.def.shape;
+/** 普通联合(含互斥联合 `z.xor`),不是判别联合 —— `evaluate` 逐臂走它;白名单门按同一个判据认它。 */
+const isPlainUnion = (schema) => schema instanceof z.ZodUnion && !(schema instanceof z.ZodDiscriminatedUnion);
+/** 寻常对象从 `Object.prototype` 继承来的成员名(ES 规定的闭集)。声明键叫这些名字时,zod 在调用方的值上 `[[Get]]` 读到继承来的成员,投影把它读成缺席 —— 两边不同答。 */
+const ORDINARY_OBJECT_MEMBERS = new Set(["constructor", "hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable", "toLocaleString", "toString", "valueOf", "__proto__", "__defineGetter__", "__defineSetter__", "__lookupGetter__", "__lookupSetter__"]);
+/** 走过白名单门的 schema(按根;fleet 每次请求都是那七只,不重走)。 */
+const ADMITTED = new WeakSet();
+/** 白名单门(见文件头):整棵 schema 树只含放行的形 ⇒ 记下、交回 `undefined`;否则交回不支持的那一句(见 {@link Refusal})。与 `evaluate` / `snapshotOf` 同一套判据(`isPlainUnion` / `innerOf`)。 */
+function admit(schema) {
+    if (ADMITTED.has(schema))
+        return undefined;
+    const refusal = admitEvaluated(schema, new Map());
+    if (refusal === undefined)
+        ADMITTED.add(schema);
+    return refusal;
+}
+/** 一串子节点逐个过门,第一句不支持就停(交回它)。 */
+function admitEach(children, at, seen) {
+    for (const child of children) {
+        const refusal = admitAt(child, at, seen);
+        if (refusal !== undefined)
+            return refusal;
+    }
+    return undefined;
+}
+/** `evaluate` 走的那一层:普通联合逐臂;其余是一份投影。 */
+function admitEvaluated(schema, seen) {
+    if (isPlainUnion(schema)) {
+        // `evaluate` 逐臂拿**臂的** schema 校验:挂在联合本身上的检查(`.refine` / `.superRefine`)一次都不跑 —— zod 会跑,两边不同答
+        if ((schema._zod.def.checks ?? []).length > 0)
+            return "a union with checks of its own at the top (`.refine` on the union: the per-arm evaluation validates with each arm's schema, so the union's own checks would never run)";
+        for (const option of schema._zod.def.options) {
+            const refusal = admitEvaluated(option, seen);
+            if (refusal !== undefined)
+                return refusal;
+        }
+        return undefined;
+    }
+    return admitAt(schema, "projected", seen);
+}
+function admitAt(schema, at, seen) {
+    const inner = innerOf(schema);
+    const positions = seen.get(inner) ?? new Set();
+    if (positions.has(at))
+        return undefined;
+    seen.set(inner, positions.add(at));
+    const kind = inner._zod.def.type;
+    switch (kind) {
+        // 叶子:不跑用户函数、没有子 schema —— 校验器只看这个值本身(原始值两边是同一个;对象两边都按形拒)
+        case "string":
+        case "number":
+        case "int":
+        case "boolean":
+        case "bigint":
+        case "symbol":
+        case "null":
+        case "undefined":
+        case "void":
+        case "never":
+        case "nan":
+        case "date":
+        case "literal":
+        case "enum":
+        case "template_literal":
+        case "file":
+            return undefined;
+        case "unknown":
+        case "any":
+            return at === "copied" ? "`unknown` / `any` under a copied node (record / array / a union inside a field / a catchall — passthrough included): the copy, not the caller's value, would reach the output" : undefined;
+        case "object": {
+            const object = inner;
+            const shape = shapeOf(object);
+            if (Object.getOwnPropertySymbols(shape).length > 0)
+                return "a symbol key (the projection reads string keys only)";
+            const catchall = object._zod.def.catchall;
+            for (const key of Object.keys(shape)) {
+                if (ORDINARY_OBJECT_MEMBERS.has(key))
+                    return `a declared key named \`${key}\` (zod reads the member an ordinary object inherits; the projection reads it as absent)`;
+                const refusal = admitAt(shape[key], catchall === undefined ? at : "copied", seen);
+                if (refusal !== undefined)
+                    return refusal;
+            }
+            return catchall !== undefined ? admitAt(catchall, "copied", seen) : undefined;
+        }
+        case "union": {
+            const options = inner._zod.def.options;
+            if (inner instanceof z.ZodDiscriminatedUnion) {
+                if (inner._zod.def.unionFallback === true)
+                    return "a discriminated union with `unionFallback` (zod falls back to trying every arm on the full value; the projection of one arm's declared keys cannot say what it would do)";
+                return admitEach(options, at, seen);
+            }
+            return admitEach(options, "copied", seen); // 走到这里的普通联合是不透明的(嵌在字段里 / 套着包装层):整个值深拷
+        }
+        case "record": {
+            const record = inner;
+            if (record._zod.def.mode === "loose")
+                return "a loose record (keys the key schema does not match ride through by reference — the copy, not the caller's value, would reach the output)";
+            // 有限键集(枚举 / 字面量键):zod 逐个按键名在值上 `[[Get]]` —— 键名是继承名时读到继承的成员,副本上读成缺席(与对象声明键同一条)
+            for (const key of record._zod.def.keyType._zod.values ?? []) {
+                if (typeof key === "string" && ORDINARY_OBJECT_MEMBERS.has(key))
+                    return `a record key named \`${key}\` in a finite key set (zod reads the member an ordinary object inherits; the copy reads it as absent)`;
+            }
+            return admitEach([record._zod.def.keyType, record._zod.def.valueType], "copied", seen);
+        }
+        case "array":
+            return admitAt(inner.element, "copied", seen);
+        case "catch":
+            return "`.catch` (its fallback sees the caller's whole value — zod ≥ 4.6 hands it `ctx.input`; a projection changes what it sees)";
+        case "pipe":
+            return `a pipe the projection does not pass through — an input-side \`z.preprocess(f, …)\` or \`a.pipe(b)\` (the function / the second schema would see a projection or a copy, not what zod sees), or wrappers nested deeper than ${WRAPPER_BOUND} layers`;
+        case "transform":
+            return "a bare `z.transform(f)` (an input-side function: it would see the projection, not the caller's value)";
+        case "custom":
+            return "`z.custom` / `z.instanceof` (the predicate would see the projection, not the caller's value)";
+        case "optional":
+        case "nullable":
+        case "default":
+        case "prefault":
+            return `wrappers nested deeper than ${WRAPPER_BOUND} layers`;
+        case "tuple":
+        case "intersection":
+        case "map":
+        case "set":
+        case "lazy":
+        case "promise":
+        case "function":
+        case "readonly":
+        case "nonoptional":
+        case "success":
+            return `\`${kind}\` (not on the allow-list: the projection has not been proven to answer as zod does)`;
+        default: {
+            const unhandled = kind;
+            return `an unknown schema kind \`${String(unhandled)}\``;
+        }
+    }
+}
+/** 一个值要不要进对象投影:是朴素对象 ⇒ `undefined`(继续投影);不是对象(`null` / 原始值)⇒ 原样交过去(校验器自己拒);数组 / 类实例 / 读不出 ⇒ 深拷(同一套坏形与句子)。 */
+function nonObjectSnapshot(value) {
+    const kind = jsonShapeOf(value);
+    switch (kind) {
+        case "plain":
+            return undefined;
+        case "null":
+        case "primitive":
+            return { ok: true, value };
+        case "array":
+        case "non_plain_object":
+        case "uninspectable":
+            return captureJson(value);
+        default: {
+            const unhandled = kind;
+            throw new Error(`declared-capture: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
+/** 对象形投影:声明键逐个读(自有可枚举数据属性 ⇒ 取值按子 schema 递归;继承 / 缺席 ⇒ 跳过;隐藏 / 访问器 / 读不出 ⇒ 整份拒)。`prior` 里已有的键用那一次的读数,不再读。 */
+function objectSnapshot(shape, value, prior) {
+    const skip = nonObjectSnapshot(value);
+    if (skip !== undefined)
+        return skip;
+    const copy = isolatedObject();
+    for (const key of Object.keys(shape)) {
+        const read = prior.get(key) ?? readDeclaredKey(value, key);
+        switch (read.presence) {
+            case "own": {
+                const child = snapshotOf(shape[key], read.value, NO_PRIOR_READS);
+                if (!child.ok)
+                    return child;
+                Object.defineProperty(copy, key, dataDescriptor(child.value));
+                break;
+            }
+            case "inherited":
+            case "absent":
+                break;
+            case "hidden":
+                return failed(NOT_PLAIN_DATA);
+            case "unreadable":
+                return failed(UNINSPECTABLE);
+            default: {
+                const unhandled = read;
+                throw new Error(`declared-capture: unhandled presence ${String(unhandled.presence)}`);
+            }
+        }
+    }
+    return { ok: true, value: copy };
+}
+/**
+ * 判别联合:按判别键选臂,只投影那一臂;判别键缺席 / 不是任何一臂的词 ⇒ 只交过去判别键。**判别键只读一次**:这一次的读数交给选中那一臂的投影复用(`prior`),
+ * 所以快照里的判别词就是选臂的那个词 —— 校验器拿快照按判别键派发,落到的就是选中的这一臂(没有第二次读,也就没有「第二次读到另一个词、落到另一臂」)。
+ */
+function discriminatedSnapshot(union, value, prior) {
+    const skip = nonObjectSnapshot(value);
+    if (skip !== undefined)
+        return skip;
+    const discriminator = union._zod.def.discriminator;
+    const read = prior.get(discriminator) ?? readDeclaredKey(value, discriminator);
+    if (read.presence === "hidden")
+        return failed(NOT_PLAIN_DATA);
+    if (read.presence === "unreadable")
+        return failed(UNINSPECTABLE);
+    const word = read.presence === "own" ? read.value : undefined;
+    const arms = union._zod.def.options;
+    const chosen = arms.find((arm) => innerOf(arm)._zod.propValues?.[discriminator]?.has(word) === true);
+    if (chosen !== undefined)
+        return snapshotOf(chosen, value, new Map(prior).set(discriminator, read));
+    // 没有一臂认这个词(或键缺席):校验器只看判别键就拒,别的键一个都不碰
+    const only = isolatedObject();
+    if (read.presence === "own") {
+        const kept = captureJson(word);
+        if (!kept.ok)
+            return kept;
+        Object.defineProperty(only, discriminator, dataDescriptor(kept.value));
+    }
+    return { ok: true, value: only };
+}
+/**
+ * `schema` 在 `value` 上会读的键的快照(恰一份;普通联合不在这里 —— 它逐臂各走一遍,见 `evaluate`;嵌在对象里的普通联合当不透明,整个值深拷)。
+ * `prior`:同一个值上已经读过的声明键(判别联合读过的判别键;投影走进字段值时是一张新的空表)—— **快照里这些键的在场与值恒是那一次的读数,不读第二次**:投影直接复用;
+ * 整份深拷的臂(`strict` / 带 catchall 的对象)把它交给 `captureJson`,列成员时这些键取那一次的读数、不再问描述符(所以判别联合选臂的词就是交给校验器的词,不论臂怎么拍快照)。
+ */
+function snapshotOf(schema, value, prior) {
+    const inner = innerOf(schema);
+    if (inner instanceof z.ZodUnknown || inner instanceof z.ZodAny)
+        return { ok: true, value };
+    if (inner instanceof z.ZodDiscriminatedUnion)
+        return discriminatedSnapshot(inner, value, prior);
+    if (inner instanceof z.ZodObject && inner._zod.def.catchall === undefined)
+        return objectSnapshot(shapeOf(inner), value, prior);
+    return captureJson(value, "isolated", prior);
+}
+/**
+ * 按 zod 的联合语义逐臂各走一遍:一臂 = 只含该臂声明键的快照 + **只拿该臂的 schema 校验**(拿整个联合去校验的话,后臂会用默认值接受前一臂的残缺投影)。
+ *  · 普通联合:按序,第一臂通过即止(不取并集);
+ *  · 互斥联合(`z.xor`:`def.inclusive === false`):**所有**臂都走一遍,恰一臂通过才接受 —— 两臂都通过 zod 拒(这里同样拒,不是取第一臂丢掉另一臂的键);
+ *  · 其余(含判别联合:它按判别键选臂,见 `discriminatedSnapshot`):恰一份快照、拿整只 schema 校验。
+ * 联合外面套着包装层(`optional` / `default` / `catch` …)⇒ 当不透明(整个值深拷、对整只 schema 校验),包装层的语义由 zod 自己走。
+ */
+function evaluate(schema, value) {
+    if (isPlainUnion(schema)) {
+        const exclusive = schema._zod.def.inclusive === false;
+        let accepted;
+        for (const option of schema._zod.def.options) {
+            const verdict = evaluate(option, value);
+            if (verdict.kind === "unreadable")
+                return verdict;
+            if (verdict.kind !== "ok")
+                continue;
+            if (!exclusive)
+                return verdict;
+            if (accepted !== undefined)
+                return { kind: "rejected" }; // xor:两臂都通过 ⇒ 拒
+            accepted = verdict;
+        }
+        return accepted ?? { kind: "rejected" };
+    }
+    const snapshot = snapshotOf(schema, value, NO_PRIOR_READS);
+    if (!snapshot.ok)
+        return { kind: "unreadable" };
+    // 只问判决、不要句子(parseDeclared 从不交出拒因):逐次 `error` 参数让 zod 不进 locale 拼句 —— 拼句会对副本做 `parsedType`(副本的原型不是 Object.prototype,
+    // 用户写的自有 `constructor` 键会被读成类型名、转串时抛),联合 / 互斥联合会因此把一臂判成「读不出」、不再试后面的臂,与 zod 在原值上的判决不同。只读 `success` / `data`,
+    // 不构造错误对象(所以不用 `guardedSafeParse`);校验过程抛 ⇒ 入口那一只守护(`inspect`)接住
+    const parsed = schema.safeParse(snapshot.value, { error: () => "rejected" });
+    return parsed.success ? { kind: "ok", data: parsed.data } : { kind: "rejected" };
+}
+/**
+ * 对 `value` 校验的守护读法(`schema` 的 safeParse):校验器读的是投影后的自有键快照,不是调用方的对象。读不出 / 不是纯数据 / 校验不过 ⇒ `{ ok: false }`(不抛);
+ * 联合按 {@link evaluate} 的语义逐臂。`schema` 不在白名单里(见文件头)⇒ 抛 `parseDeclared: unsupported schema shape — …`(不论输入)。
+ * **守护边界就在这里一处**(内核的 `inspect`):白名单门对 schema 的内省(zod 的惰性属性 —— 声明键表、判别联合的 `propValues` —— 第一次被读时才物化,物化时 zod 用字面量描述符调
+ * `defineProperty`、往 `{}` 上按键名累加:`Object.prototype` 被污染成 `get` / `set` / `value` / 判别键名时,物化在这一步抛)、投影快照的递归(递归 schema × 很深的数据会爆栈)与校验,
+ * 全在同一只守护里 —— 抛了 ⇒ `{ ok: false }`(与 v14.6.0 那一层守护同向:读口答「读不出」,不把引擎的错 / 嵌入方的抛出值带出去)。
+ * 「不支持」是门**交回**的判语、在守护外抛:它是包自己的 schema 选错了读法,与输入无关。
+ */
+export function parseDeclared(schema, value) {
+    const run = inspect(() => {
+        const refusal = admit(schema);
+        return refusal !== undefined ? { kind: "unsupported", what: refusal } : evaluate(schema, value);
+    });
+    if (!run.ok)
+        return { ok: false };
+    const verdict = run.value;
+    switch (verdict.kind) {
+        case "unsupported":
+            throw new Error(unsupportedShape(verdict.what));
+        case "ok":
+            return { ok: true, data: verdict.data };
+        case "rejected":
+        case "unreadable":
+            return { ok: false };
+        default: {
+            const unhandled = verdict;
+            throw new Error(`parseDeclared: unhandled verdict ${String(unhandled.kind)}`);
+        }
+    }
+}

package/dist/file-edit.js

@@ -8,6 +8,7 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
+import { emptyDocument, guardedSafeParse } from "./own-key-read.js";
 import { collectEnvRefs } from "./secret-refs.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { configDDocumentText } from "./config-d-file.js";
@@ -33,28 +34,23 @@ const DOMAINS_LIST = Object.keys(DOMAIN_SCHEMAS).join(", ");
  *  (clear message) if `domain` is not a real domain name (a misuse, not invalid user data). */
 export function validateDomain(domain, raw) {
     assertDomainName(domain);
-    let r;
-    try {
-        r = DOMAIN_SCHEMAS[domain].safeParse(raw === undefined ? {} : raw); // explicit null is corrupt, not defaults (R4)
-    }
-    catch {
+    // explicit null is corrupt, not defaults (R4); the first read of `error` sits in the same guard as `safeParse` (zod 4.6 builds the sentences on that read)
+    const schema = DOMAIN_SCHEMAS[domain];
+    const judged = guardedSafeParse(() => schema.safeParse(raw === undefined ? emptyDocument() : raw), sanitizeZodError);
+    if (!judged.ok) {
         // a hostile getter/Proxy trap threw during traversal — never surface its (secret-bearing) message. R13.
         return { ok: false, issues: [{ code: "custom", ...buildQuotedIssue `invalid "${fixed(domain)}" config (a value could not be read during validation)`, path: [] }] };
     }
-    if (r.success)
-        return { ok: true, value: r.data };
-    return { ok: false, issues: sanitizeZodError(r.error).issues }; // recursive redaction (R13/R14) — no secret echo
+    if (judged.value.success)
+        return { ok: true, value: judged.value.data };
+    return { ok: false, issues: judged.value.error.issues }; // redacted inside the guard (R13/R14) — no secret echo
 }
 /** Same, for the remote-exec contract (a standalone contract, not a DOMAIN_SCHEMAS member). */
 export function validateRemoteExec(raw) {
-    let r;
-    try {
-        r = RemoteExecSpec.safeParse(raw);
-    }
-    catch {
+    const judged = guardedSafeParse(() => RemoteExecSpec.safeParse(raw), sanitizeZodError);
+    if (!judged.ok)
         return { ok: false, issues: [{ code: "custom", ...buildQuotedIssue `invalid remoteExec (a value could not be read during validation)`, path: [] }] };
-    }
-    return r.success ? { ok: true, value: r.data } : { ok: false, issues: sanitizeZodError(r.error).issues }; // no secret echo (R14)
+    return judged.value.success ? { ok: true, value: judged.value.data } : { ok: false, issues: judged.value.error.issues }; // redacted inside the guard (R14)
 }
 /** Absolute path to a domain's JSON file under a config root (mirrors FileConfigStore.domainPath). Guards the
  *  name (no `../../secret` traversal even if a caller bypasses the DomainName type). */

package/dist/fleet.d.ts

@@ -548,6 +548,17 @@ export declare const FLEET_GENERATION_ENV = "FLEET_GENERATION";
  * {@link FLEET_GENERATION_ENV} it is a reserved worker env name (`WorkerSpec.env` / `secretEnv` cannot set it).
  */
 export declare const FLEET_SCOPE_ENV = "FLEET_SCOPE";
+/**
+ * The env name a fleet member's advertise address travels under — the base URL this instance tells the control plane it can be
+ * reached at; the control plane appends request paths to it. The operator or the config renderer sets it (on Kubernetes the renderer
+ * writes a `$(POD_IP)` placeholder in the value and the kubelet expands it), and the engine reads it back. Both sides import THIS
+ * constant; neither spells the name. The address is a base that request paths are appended to, so a reader judges a present, non-empty
+ * value with `pathBaseUrlFlaws` (main barrel) — the one judge of every such seat, which forbids a credential, a
+ * query and a fragment there and allows a path prefix; judge the value AFTER the deployment has expanded its placeholders. Absent or
+ * the empty string means "no address declared" (the `${NAME:-}` idiom of a compose file), and that reading is the caller's, not the
+ * judge's.
+ */
+export declare const FLEET_ADVERTISE_ADDRESS_ENV = "FLEET_ADVERTISE_ADDRESS";
 /**
  * The serving lease — the ONE fence between a superseded generation and the traffic it must stop taking. A fleet-member
  * engine renews it with web-admin; web-admin answers per the lifecycle object it holds for that instance. Three constants

package/dist/fleet.js

@@ -20,6 +20,8 @@
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
 import { fnv1a64 } from "./hash.js";
+import { parseDeclared } from "./declared-capture.js";
+import { readDeclaredKey, ownValueOf } from "./own-key-read.js";
 import { isPlainJsonObject } from "./plain-json-object.js";
 import { buildQuotedIssue } from "./quoted-issue.js";
 // ── Web-admin's fleet endpoints (paths, one spelling) ─────────────────────────────────────────────────────
@@ -164,24 +166,41 @@ export const RestartSignal = z.object({
     since: EpochMs,
     withheld: z.boolean().optional(),
 });
-/**
- * The ONE guarded body judgement behind every wire-shape read in this file: `pick(body)` — one key of the body, or the body itself —
- * is judged against that shape's one schema, and the verdict says WHY when it is not a read: `not-an-object` (the body is null, an
- * array or a scalar) or `invalid` (the shape rejected it, or an accessor threw). It never throws (a probe must not die on one odd
- * body). Almost every reader wants only "a read or nothing" and goes through {@link readSignalBody}; the one reader whose
- * failure direction matters ({@link readCapabilityReading}) takes the reason. A second hand-written guard anywhere else in this
- * package is the defect, not a convenience.
- */
+const WHOLE_BODY = Symbol("whole body");
 function judgeSignalBody(body, pick, schema) {
-    try {
-        if (!isPlainJsonObject(body))
-            return { kind: "not-an-object" };
-        const parsed = schema.safeParse(pick(body));
-        return parsed.success ? { kind: "read", value: parsed.data } : { kind: "invalid" };
+    if (!isPlainJsonObject(body))
+        return { kind: "not-an-object" };
+    // the carrier key is read from the body's OWN keys (a polluted `Object.prototype.engineSignal` is not a signal the body carries) with the SAME descriptor check as a declared key:
+    // an own key that cannot be read as plain data (hidden — non-enumerable —, or an accessor that throws) is no readable signal, never "absent"
+    let target = body;
+    if (pick !== WHOLE_BODY) {
+        const carried = readDeclaredKey(body, pick);
+        switch (carried.presence) {
+            case "own":
+                target = carried.value;
+                break;
+            case "inherited":
+            case "absent":
+                target = undefined;
+                break;
+            case "hidden":
+            case "unreadable":
+                return { kind: "invalid" };
+            default: {
+                const unhandled = carried;
+                throw new Error(`judgeSignalBody: unhandled presence ${String(unhandled.presence)}`);
+            }
+        }
     }
-    catch {
+    // the validator reads members with `[[Get]]`, required keys included: a key the body does not carry would be filled from a polluted `Object.prototype` (a granted lease from an empty reply, a
+    // ready signal from `{}`, a "declared" capability from nothing) — so it never sees the caller's object: it reads an own-key snapshot of exactly the keys it declares (for a union: of
+    // the arm it will try), on the kernel's isolated prototype `COPY_PROTOTYPE` (no inherited members; it still answers `toString` / `valueOf`), and a value that cannot be captured
+    // (an accessor — throwing or not —, a hidden own key, a trap that throws, a cycle, not plain data) is `invalid`. `parseDeclared` admits only a closed allow-list of schema shapes, each
+    // reasoned and pinned against zod's own verdict and data; any other shape is a loud throw — the package chose the wrong reader, not a caller value that cannot be read
+    const parsed = parseDeclared(schema, target);
+    if (!parsed.ok)
         return { kind: "invalid" };
-    }
+    return { kind: "read", value: parsed.data };
 }
 /**
  * The reader behind every wire-shape read in this file that has no use for a reason: the engine-owned signals on /health
@@ -193,8 +212,6 @@ function readSignalBody(body, pick, schema) {
     const judged = judgeSignalBody(body, pick, schema);
     return judged.kind === "read" ? judged.value : undefined;
 }
-/** `pick` for a shape whose keys sit flat on the body itself (as opposed to under one key of it). */
-const wholeBody = (body) => body;
 /**
  * The model-refusal cause codes (S-768) — CLOSED sets, owned HERE, never a hand-copied second list. Adding a code is
  * one edit in this file; who goes red at compile time: a reader that switches on the code exhaustively (a web-admin), and
@@ -285,11 +302,14 @@ const isModelPlaneRefusalCode = (c) => MODEL_PLANE_REFUSAL_CODES.includes(c);
  * at all — it answers the key only and never judges the engine's version (see {@link InstanceAnnouncement}`.modelRefusals`).
  */
 export function readModelRefusals(body) {
-    const wire = readSignalBody(body, (b) => b.modelRefusals, ModelRefusalsWire);
+    const wire = readSignalBody(body, "modelRefusals", ModelRefusalsWire);
     if (wire === undefined)
         return undefined;
     const entries = Object.fromEntries(Object.entries(wire.entries).filter((e) => isModelEntryRefusalCode(e[1])));
-    const plane = wire.plane !== undefined && isModelPlaneRefusalCode(wire.plane) ? wire.plane : undefined;
+    // the validated output is an ordinary object: an absent optional `plane` stays absent (own key only), never read off a polluted `Object.prototype`
+    const planeRead = ownValueOf(wire, "plane");
+    const planeWord = planeRead.ok ? planeRead.value : undefined;
+    const plane = typeof planeWord === "string" && isModelPlaneRefusalCode(planeWord) ? planeWord : undefined;
     if (Object.keys(entries).length === 0 && plane === undefined)
         return undefined;
     return plane === undefined ? { entries } : { entries, plane };
@@ -363,7 +383,7 @@ export const ENGINE_SIGNAL_KEY = "engineSignal";
  * dialect; the carrier is the one key).
  */
 export function readEngineSignal(body) {
-    return readSignalBody(body, (b) => b[ENGINE_SIGNAL_KEY], EngineSignal);
+    return readSignalBody(body, ENGINE_SIGNAL_KEY, EngineSignal);
 }
 /** The `/health` self-description every orchestrator reads. Liveness and readiness are deliberately SPLIT: `status` stays ok while
  *  draining (the process is alive); readiness is {@link judgeReadiness} over the engine signal the body carries under
@@ -556,6 +576,17 @@ export const FLEET_GENERATION_ENV = "FLEET_GENERATION";
  * {@link FLEET_GENERATION_ENV} it is a reserved worker env name (`WorkerSpec.env` / `secretEnv` cannot set it).
  */
 export const FLEET_SCOPE_ENV = "FLEET_SCOPE";
+/**
+ * The env name a fleet member's advertise address travels under — the base URL this instance tells the control plane it can be
+ * reached at; the control plane appends request paths to it. The operator or the config renderer sets it (on Kubernetes the renderer
+ * writes a `$(POD_IP)` placeholder in the value and the kubelet expands it), and the engine reads it back. Both sides import THIS
+ * constant; neither spells the name. The address is a base that request paths are appended to, so a reader judges a present, non-empty
+ * value with `pathBaseUrlFlaws` (main barrel) — the one judge of every such seat, which forbids a credential, a
+ * query and a fragment there and allows a path prefix; judge the value AFTER the deployment has expanded its placeholders. Absent or
+ * the empty string means "no address declared" (the `${NAME:-}` idiom of a compose file), and that reading is the caller's, not the
+ * judge's.
+ */
+export const FLEET_ADVERTISE_ADDRESS_ENV = "FLEET_ADVERTISE_ADDRESS";
 /**
  * The serving lease — the ONE fence between a superseded generation and the traffic it must stop taking. A fleet-member
  * engine renews it with web-admin; web-admin answers per the lifecycle object it holds for that instance. Three constants
@@ -647,14 +678,14 @@ export const SERVING_LEASE_VERDICTS = ["granted", "denied", "unknown"];
 /** Web-admin side: the request body of a serving-lease renewal. Shape mismatch / non-object / throwing accessor ⇒ `undefined`,
  *  never throws (same guarded reader as every other read in this file). */
 export function readServingLeaseRequest(body) {
-    return readSignalBody(body, wholeBody, ServingLeaseRequest);
+    return readSignalBody(body, WHOLE_BODY, ServingLeaseRequest);
 }
 /** Engine side: the reply to a renewal, judged by its `verdict` key: `granted` needs a valid `ttlMs`, `denied` is `denied`
  *  whatever its `reason` (see {@link ServingLeaseReading}), `unknown` is `unknown`. A non-object, a throwing accessor, a
  *  `verdict` outside the three words or a `granted` without a valid `ttlMs` ⇒ `undefined`, never throws — and `undefined`
  *  is read like an unreachable web-admin, never like `denied` and never like `granted`. */
 export function readServingLeaseResponse(body) {
-    return readSignalBody(body, wholeBody, ServingLeaseReadFace);
+    return readSignalBody(body, WHOLE_BODY, ServingLeaseReadFace);
 }
 /**
  * What web-admin says it can do: capability bits an engine reads before it starts using a web-admin-side endpoint.
@@ -704,14 +735,16 @@ const CapabilitiesCarrier = z.object({ [HEARTBEAT_REPLY_CAPABILITIES_KEY]: WebAd
  * other reader here.
  */
 export function readCapabilityReading(reply) {
-    const judged = judgeSignalBody(reply, wholeBody, CapabilitiesCarrier);
+    const judged = judgeSignalBody(reply, WHOLE_BODY, CapabilitiesCarrier);
     switch (judged.kind) {
         case "not-an-object":
             return { kind: "unreadable", why: "not-an-object" };
         case "invalid":
             return { kind: "unreadable", why: "invalid-capabilities" };
         case "read": {
-            const capabilities = judged.value[HEARTBEAT_REPLY_CAPABILITIES_KEY];
+            // the validated output is an ordinary object: an absent optional key must stay absent, not be read off a polluted `Object.prototype` — own key only (it was parsed from a snapshot, so it cannot be unreadable)
+            const carried = ownValueOf(judged.value, HEARTBEAT_REPLY_CAPABILITIES_KEY);
+            const capabilities = carried.ok ? carried.value : undefined;
             return capabilities === undefined ? { kind: "undeclared" } : { kind: "declared", capabilities };
         }
         default: {
@@ -755,11 +788,11 @@ export const DrainReceiptState = z.enum(DRAIN_RECEIPT_STATES);
 export const DrainReceipt = EngineDraining.extend({ state: DrainReceiptState });
 /** Engine side: the request body of the drain endpoint. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
 export function readDrainRequest(body) {
-    return readSignalBody(body, wholeBody, DrainRequest);
+    return readSignalBody(body, WHOLE_BODY, DrainRequest);
 }
 /** Caller side: the drain endpoint's answer. Shape mismatch / non-object / throwing accessor ⇒ `undefined`, never throws. */
 export function readDrainReceipt(body) {
-    return readSignalBody(body, wholeBody, DrainReceipt);
+    return readSignalBody(body, WHOLE_BODY, DrainReceipt);
 }
 // ── Domain 3: dispatch policy (traffic + failover + LB — three domains, one gateway) ──────────────────────
 export const DISPATCH_STRATEGIES = ["round-robin", "least-inflight", "consistent-hash"];