@sema-agent/settings-schema 14.5.0 → 14.7.0

package/dist/cross-session.d.ts

@@ -50,11 +50,11 @@ export type CrossSessionInboundValue = (typeof CROSS_SESSION_INBOUND_VALUES)[num
 export declare const CROSS_SESSION_INBOUND_UNSET: "default";
 /** 文件层受理面:四个显式值 + `"default"`(未设)。 */
 export declare const CrossSessionInboundSetting: z.ZodEnum<{
+    refuse: "refuse";
     default: "default";
     wake: "wake";
     "next-turn": "next-turn";
     hold: "hold";
-    refuse: "refuse";
 }>;
 export type CrossSessionInboundSettingValue = z.infer<typeof CrossSessionInboundSetting>;
 /** 四值闭集(CC 逐字)。`"never"` = 不设期限。 */
@@ -64,8 +64,8 @@ export type DialogExpiryValue = (typeof DIALOG_EXPIRY_VALUES)[number];
 export declare const DIALOG_EXPIRY_DEFAULT: DialogExpiryValue;
 /** 文件层受理面:四个值 + `"default"`(未设 ⇒ 落 {@link DIALOG_EXPIRY_DEFAULT})。 */
 export declare const DialogExpirySetting: z.ZodEnum<{
-    never: "never";
     default: "default";
+    never: "never";
     "60s": "60s";
     "5m": "5m";
     "10m": "10m";
@@ -78,15 +78,15 @@ export type DialogExpirySettingValue = z.infer<typeof DialogExpirySetting>;
  */
 export declare const CrossSessionSettings: z.ZodObject<{
     crossSessionInbound: z.ZodOptional<z.ZodEnum<{
+        refuse: "refuse";
         default: "default";
         wake: "wake";
         "next-turn": "next-turn";
         hold: "hold";
-        refuse: "refuse";
     }>>;
     dialogExpiry: z.ZodOptional<z.ZodEnum<{
-        never: "never";
         default: "default";
+        never: "never";
         "60s": "60s";
         "5m": "5m";
         "10m": "10m";

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/file-store.d.ts

@@ -1,22 +1,7 @@
 import { type EffectiveReadWarning } from "./config-fns.js";
 import type { ConfigReader } from "./reader.js";
 import { type DomainConfig, type DomainName, type EffectiveConfig, type RetiredDomainName } from "./types.js";
-/** The domains a single-machine TOC carries: what `FileConfigStore` reads out of `config.d/`, and the
- *  **default**域集 of the bundle helpers (`exportBundle`/`readBundle`). 每个被排除的域必须在
- *  {@link NON_PORTABLE_DOMAIN_REASONS} 里有一条成文理由(禁裸排除,#282 件5 附带裁定)。
- *
- *  ⚠️ 口径诚实(对抗复审 复审 round1 F4):这是**默认集与本地读取集,不是 API 级硬边界** —— `exportBundle`
- *  / `readBundle` 的 `domains` 参数可显式传任意 `DomainName`(bundle.ts 不拒非便携域)。把非便携域搬进
- *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
- *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
- *
- *  🔴 **开新顶层域时必须同步登记本表**(成案 = 消费方 #322 真事故):域表是**闭集**,不在这里的
- *  域名,`config.d/<域>.json` 不会被读进 effective —— 消费方拿到的是「该域缺席」,和文件不存在**逐字
- *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
- *  今日的兜底:漏登记的文件会被 {@link FileConfigStore} 的 `"unread-config-file"` 警告点名(fail-loud,
- *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
-export declare const PORTABLE_DOMAINS: readonly ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits"];
-export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
+export { NON_PORTABLE_DOMAIN_REASONS, PORTABLE_DOMAINS, type PortableDomain } from "./portable-domains.js";
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
  *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
@@ -24,21 +9,6 @@ export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
  *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
  *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
 export declare const NON_DOMAIN_CONFIG_FILES: ReadonlySet<string>;
-/**
- * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
- *
- * `satisfies Record<Exclude<DomainName, PortableDomain>, string>` 让键集在**编译期**双向咬死:新开一个
- * 域却不放进 PORTABLE_DOMAINS ⇒ 这里缺行 ⇒ 编译错;把某域改成便携却忘了删行 ⇒ 多余键 ⇒ 编译错。
- * (此前是「理由写在注释里」,机器只能做子串匹配——域名出现在文件任何角落都算数,等于没门;对抗复审
- * 复审 round1 F3。)理由要写**为什么它不该被单机/跨部署搬运**,带出处。
- */
-export declare const NON_PORTABLE_DOMAIN_REASONS: {
-    readonly workers: "FLEET-only:单机没有 reconciler,`{workers:[]}` 的 schema 默认就是正确语义(缺席不需要 stub)。";
-    readonly hosts: "FLEET-only:同 workers —— 单机无机器注册表/自动排布,空注册表即正确语义。";
-    readonly systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 web-admin 侧生命周期,单机 lane 无对应执法点。";
-    readonly projects: "TENANT IDENTITY DATA,不是可搬运的配置:登记簿随包复制进另一个部署 = 凭空多出的身份登记(design/142 §1.4 威胁模型①「carried-in foreign projectId」换了身 import 的衣服)。要带走走 142 §5 的导出面(service 半场)。";
-    readonly entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service / web-admin 边界)。缺席语义如实:本地 buildEffective 给它 schema 默认值(空表),这**不等于**把远端 kill-switch/预算上限搬到了本地 —— 单机 lane 本就没有那个执法点。";
-};
 /** One unreadable/corrupt domain FILE surfaced by `getEffective({tolerant:true})`(0.10.12,[897]②)。
  *  `error` 是 #readDomainRaw 的 sanitized 文案(带文件路径语境、绝不回显文件内容)。 */
 export type DomainReadError = {

package/dist/file-store.js

@@ -29,25 +29,13 @@ import path from "node:path";
 import { buildEffective, DOMAIN_READ_FALLBACK, parseDomainLoud } from "./config-fns.js";
 import { configDPath, readConfigDFile, refuseRetiredDomainFiles } from "./config-d-file.js";
 import { stableHash } from "./hash.js";
+import { PORTABLE_DOMAINS } from "./portable-domains.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
 /** The retired domain names (`RETIRED_DOMAINS` keys) — read from `config.d/` for their tombstone only. */
 const RETIRED_DOMAIN_NAMES = Object.keys(RETIRED_DOMAINS);
-/** The domains a single-machine TOC carries: what `FileConfigStore` reads out of `config.d/`, and the
- *  **default**域集 of the bundle helpers (`exportBundle`/`readBundle`). 每个被排除的域必须在
- *  {@link NON_PORTABLE_DOMAIN_REASONS} 里有一条成文理由(禁裸排除,#282 件5 附带裁定)。
- *
- *  ⚠️ 口径诚实(对抗复审 复审 round1 F4):这是**默认集与本地读取集,不是 API 级硬边界** —— `exportBundle`
- *  / `readBundle` 的 `domains` 参数可显式传任意 `DomainName`(bundle.ts 不拒非便携域)。把非便携域搬进
- *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
- *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
- *
- *  🔴 **开新顶层域时必须同步登记本表**(成案 = 消费方 #322 真事故):域表是**闭集**,不在这里的
- *  域名,`config.d/<域>.json` 不会被读进 effective —— 消费方拿到的是「该域缺席」,和文件不存在**逐字
- *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
- *  今日的兜底:漏登记的文件会被 {@link FileConfigStore} 的 `"unread-config-file"` 警告点名(fail-loud,
- *  见 getEffective),但那只在消费方接了 `onWarning` 时才响 —— **登记仍是第一现场的义务**。 */
-export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "governance", "execution", "prompts", "limits"];
+// 便携域表的定义住在纯叶 ./portable-domains.ts(14.6.0;零 node 依赖,主桶模块可 import);这里原名转出口,`./node` 子路径逐名不变。
+export { NON_PORTABLE_DOMAIN_REASONS, PORTABLE_DOMAINS } from "./portable-domains.js";
 /** `config.d/` 里**合法存在但不是域文档**的文件名(不进 `"unread-config-file"` 告警)。`remote-exec`
  *  不是 `DOMAIN_SCHEMAS` 成员(resolver 不读它),按 service 表决住在这个目录,由 loadRemoteExec 读
  *  ——**它有自己的读取与校验路径**,所以既不是「未知文件」也不是「域文件」。
@@ -55,21 +43,6 @@ export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins"
  *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
  *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
 export const NON_DOMAIN_CONFIG_FILES = new Set([`${REMOTE_EXEC_DOCUMENT}.json`]);
-/**
- * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
- *
- * `satisfies Record<Exclude<DomainName, PortableDomain>, string>` 让键集在**编译期**双向咬死:新开一个
- * 域却不放进 PORTABLE_DOMAINS ⇒ 这里缺行 ⇒ 编译错;把某域改成便携却忘了删行 ⇒ 多余键 ⇒ 编译错。
- * (此前是「理由写在注释里」,机器只能做子串匹配——域名出现在文件任何角落都算数,等于没门;对抗复审
- * 复审 round1 F3。)理由要写**为什么它不该被单机/跨部署搬运**,带出处。
- */
-export const NON_PORTABLE_DOMAIN_REASONS = {
-    workers: "FLEET-only:单机没有 reconciler,`{workers:[]}` 的 schema 默认就是正确语义(缺席不需要 stub)。",
-    hosts: "FLEET-only:同 workers —— 单机无机器注册表/自动排布,空注册表即正确语义。",
-    systems: "FLEET-only:系统接入/凭据下发的元数据(nonce+路由)属于 web-admin 侧生命周期,单机 lane 无对应执法点。",
-    projects: "TENANT IDENTITY DATA,不是可搬运的配置:登记簿随包复制进另一个部署 = 凭空多出的身份登记(design/142 §1.4 威胁模型①「carried-in foreign projectId」换了身 import 的衣服)。要带走走 142 §5 的导出面(service 半场)。",
-    entitlement: "per-PRINCIPAL 商务/治理数据(tier·预算上限·kill-switch·allowlist),与 projects 同威胁模型(#282 件5 附带裁定,此前是唯一裸排除项):(a) 搬走 = 把一个租户的商务档复制进另一部署;(b) 反向也不成立 —— 单机 TOC 无 principal 轴(无鉴权语境、无 `/effective?principal=` 解析面),本地 entitlement.json 只会造出一份**永不被执法**的假管控面(真执法点在 service / web-admin 边界)。缺席语义如实:本地 buildEffective 给它 schema 默认值(空表),这**不等于**把远端 kill-switch/预算上限搬到了本地 —— 单机 lane 本就没有那个执法点。",
-};
 export class FileConfigStore {
     root;
     opts;

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