@sema-agent/settings-schema 14.6.0 → 14.8.0

package/dist/types.js

@@ -22,6 +22,7 @@ import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody dep
 import { DispatchPolicy, FLEET_GENERATION_ENV, FLEET_SCOPE_ENV } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
 import { isLoopbackAuthHost } from "./loopback.js";
 import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js"; // THE "is this a JSON object" predicate + the total array test
+import { appendOwn, guardedSafeParse, isAccessorDescriptor } from "./own-key-read.js"; // the one spelling of "is this descriptor an accessor" (its own fields only) + the one guarded zod verdict
 import { httpUrlFlaws, httpUrlRule } from "./url-shape.js"; // 11.0.0: THE URL shape judge // 11.0.0: the one narrow「本机」predicate (auth relaxation)
 import { secretScanForms } from "./secret-scan.js"; // package-private normalization — the one set of forms both scanners read (not in the barrel)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js"; // the three connection keys the config renderer writes are reserved worker env
@@ -255,9 +256,9 @@ export function extraBodyUnsafe(v) {
                 for (const [k, desc] of Object.entries(Object.getOwnPropertyDescriptors(cur))) {
                     if (k === "length")
                         continue; // the array's own `length` data prop — not an element
-                    if (!Object.hasOwn(desc, "value"))
+                    if (isAccessorDescriptor(desc))
                         return true; // accessor element — do NOT invoke
-                    stack.push([desc.value, depth + 1]);
+                    appendOwn(stack, [desc.value, depth + 1]); // 定义语义压栈:`push` 会被继承的数字键 setter 吞掉,遍历一层都不下、秘密静默漏判
                 }
                 continue;
             }
@@ -265,11 +266,11 @@ export function extraBodyUnsafe(v) {
                 return true; // Map/Set/Date/class/toJSON-bearing → not plain
             // descriptor walk: never read a value via [] (would invoke a getter); reject accessors outright.
             for (const [k, desc] of Object.entries(Object.getOwnPropertyDescriptors(cur))) {
-                if (!Object.hasOwn(desc, "value"))
+                if (isAccessorDescriptor(desc))
                     return true; // accessor (get/set) — do NOT invoke
                 if (containsSecretToken(k))
                     return true; // secret-shaped KEY (tokenized). R8
-                stack.push([desc.value, depth + 1]);
+                appendOwn(stack, [desc.value, depth + 1]); // 定义语义压栈:`push` 会被继承的数字键 setter 吞掉,遍历一层都不下、秘密静默漏判
             }
         }
         return false;
@@ -455,6 +456,20 @@ export const PARSE_TRANSPARENT_KEYS = [
         validatedBy: "consumer",
         why: "它的形由同一条 override 的 `key` 决定(一个 key 一种形),执法点在读那个 key 的消费方;在这里写死形等于把所有可覆盖键的形表搬进本包。",
     },
+    {
+        domain: "mcp",
+        path: "servers[].sessionMetaKey",
+        since: "14.8.0",
+        validatedBy: "engine-ingest",
+        why: "引擎在发给这台服务器的请求 `_meta` 里放发送腿会话 id 的那把键;它只有一只判官 = 引擎根导出 `judgeSessionMetaKey`(类型、非空、上界、MCP `_meta` 键名文法、MCP 保留前缀、`progressToken`、引擎的 `sema/` 命名空间一并判;坏键在引擎的准备门整条拒、点名这把键),投影它的消费方在交给引擎之前可调同一只;本包只承载 —— 这里哪怕只判类型与长度,也是第二只判官的一部分,与引擎那只各答各的。",
+    },
+    {
+        domain: "mcp",
+        path: "servers[].startupTimeoutMs",
+        since: "14.8.0",
+        validatedBy: "engine-ingest",
+        why: "引擎的逐服务器启动界(握手与首次工具列举各带它);它只有一只判官 = 引擎根导出的 `mcpStartupTimeoutMs`(是不是数、整数性、范围一并判;坏值在引擎的拨号门拒这一台服务器、点名 `config.mcp_startup_timeout_invalid`,其余服务器照挂),投影它的消费方在交给引擎之前可调同一只;本包只承载 —— 这里哪怕只判「是不是数」,也是第二只判官的一部分,与引擎那只各答各的。",
+    },
 ];
 /** A catalog model's price / capability tier — fuels core 1.25 `selectModel({ tier })` role resolution. ONE closed set for both
  *  places that name it (`ModelEntry.tier`, `RoleTarget.select.tier`). Not the tier-group ladder of {@link TierBindings}
@@ -605,7 +620,7 @@ const RoleMap = z.partialRecord(ModelRole, RoleTarget, {
     // 枚举键的 record 在运行期以 `unrecognized_keys`(带 `keys`)报未知键,zod 的型面只列了 invalid_type / invalid_key —— 按运行期形读(钉:role-words-12.0.0)。
     error: (iss) => {
         const raw = iss;
-        return raw.code === "unrecognized_keys" && Array.isArray(raw.keys) ? retiredRoleWordsRefusal(raw.keys) : undefined;
+        return raw.code === "unrecognized_keys" && isJsonArray(raw.keys) ? retiredRoleWordsRefusal(raw.keys) : undefined;
     },
 });
 /** {@link AtMention} 的模式闭集:`all` = 每个启用的模型都可 `@`;`none` = 一个都不许;`only` = 只许 `models` 里点名的那几个。 */
@@ -1607,7 +1622,11 @@ export function applyProjectPatch(doc, projectId, patch) {
     const current = Object.prototype.hasOwnProperty.call(doc.projects, projectId) ? doc.projects[projectId] : undefined;
     if (current === undefined)
         throw new Error(`applyProjectPatch: project "${projectId}" is not registered in this document`);
-    const parsed = ProjectRegistrationPatch.safeParse(patch);
+    // the patch is the caller's value: the parse and the first read of its error sit in one guard (another realm's odd value, a getter / trap that throws) ⇒ a rejection, never a throw
+    const patchRead = guardedSafeParse(() => ProjectRegistrationPatch.safeParse(patch));
+    if (!patchRead.ok)
+        return { success: false, error: new z.ZodError([{ code: "custom", ...buildQuotedIssue `the patch could not be read during validation`, path: ["projects", projectId], input: undefined }]) };
+    const parsed = patchRead.value;
     if (!parsed.success) {
         const issues = parsed.error.issues.map((i) => ({ ...i, path: ["projects", projectId, ...i.path] }));
         return { success: false, error: new z.ZodError(issues) };
@@ -2481,6 +2500,16 @@ export const McpServerSpec = z.object({
      *  declared `"local"`, the engine read ABSENT. A value outside the table is REJECTED at parse — a mistyped trust
      *  word must never be read as a legal one (the consumer's gate is equally severe: no case-folding). */
     contentOrigin: z.enum(MCP_CONTENT_ORIGINS).optional(),
+    /** 引擎在发给这台服务器的每个 `tools/call` / `resources/read` 的 `params._meta[key]` 里放发送腿自己的会话 id 的那把键 —— 一一对应引擎的
+     *  `McpServerSpec.sessionMetaKey`。缺席 = 什么都不送(`.optional()`,不铸默认:会话 id 出进程是部署自己选的关联)。
+     *
+     *  **解析透明** —— 形归谁校验、为什么不放这里:{@link PARSE_TRANSPARENT_KEYS}(`mcp.servers[].sessionMetaKey`)。 */
+    sessionMetaKey: z.unknown().optional(),
+    /** 这一台服务器自己的启动界(整数毫秒):握手(连接 + initialize)与首次工具列举各带它 —— 一一对应引擎的 `McpServerSpec.startupTimeoutMs`。
+     *  缺席 = 引擎读进程级的缺省界(`.optional()`,不铸默认:没声明就是没声明);它只界启动阶段,不动单次调用的超时。
+     *
+     *  **解析透明** —— 形归谁校验、为什么不放这里:{@link PARSE_TRANSPARENT_KEYS}(`mcp.servers[].startupTimeoutMs`)。 */
+    startupTimeoutMs: z.unknown().optional(),
     /** Declaration-plane GROUPING LABEL for this server — maps 1:1 onto the engine's `McpServerSpec.source`
      *  (core ≥7.5.0 echoes it verbatim on `wiring_manifest.mcp[].source`, single-line + 80-char cap, so a
      *  consumer can group servers by where they were declared). An OPEN set: CC's `plugin` / `user` /

package/dist/url-shape.d.ts

@@ -41,6 +41,22 @@ export declare function isHierarchicalUrl(raw: string): boolean;
  * 层级式非 http(s) ⇒ `not-http-url` 之后照判部件。返回类型按 `forbid` 收窄:座位没禁的部件不会出现在答案里。
  */
 export declare function httpUrlFlaws<P extends HttpUrlPart>(raw: string, forbid: readonly P[]): ReadonlyArray<"not-http-url" | P>;
+/**
+ * **「后面要拼路径的基址」座位禁用的部件**(闭集、冻结、判序)—— 14.7.0 起的唯一一张。一个值若是别人要往它后面拼路径的基址
+ * (中心基址三席、本实例对中心公告的地址、会话网页链接的基址……):`userinfo` 把凭据放进一个会被记日志、转述、拼路径的值;`query` / `fragment`
+ * 挂在基址上,一拼路径就落到错的位置(`http://x?a=1` + `/v1/…` = `http://x?a=1/v1/…`)。**路径前缀不禁** —— 要拼的路径接在前缀后面。
+ * 这是**策略集,独立于判官词表**({@link HTTP_URL_PARTS} 说的是 URL 有哪些成分,本集说的是这种座位禁哪些):今天两者碰巧同三词,但本集不由词表派生 ——
+ * 词表加词时此处要显式裁(加进来还是明确不加),不会静默多禁一件。冻结:判官读的就是消费方手里的这一只。
+ * 按座位的本质命名,不按某个消费键名:谁的座位是「后面要拼路径的基址」,谁读它,不各自抄词。
+ */
+export declare const PATH_BASE_URL_FORBIDDEN_PARTS: readonly ["userinfo", "query", "fragment"];
+/**
+ * 「后面要拼路径的基址」座位的判:`[]` = 合格,否则按判序交回规则词 —— 就是 {@link httpUrlFlaws} 配 {@link PATH_BASE_URL_FORBIDDEN_PARTS},
+ * 不另写判法;规则词的句子取 {@link httpUrlRule}。答案只有词,不含值的任何片段。判**占位展开之后**的值:`http://$(POD_IP):8090` 过
+ * (占位在主机位),`http://[$(POD_IP)]:8090` 拒(方括号里必须是 IPv6 字面量),展开后的 `http://[fd00::1]:8090` 过。
+ * 缺席 / 空串由调用方在判之前处理(对 `""` 本函数答 `not-http-url`)。
+ */
+export declare function pathBaseUrlFlaws(url: string): ReadonlyArray<HttpUrlFlaw>;
 /** 以 `http://` / `https://` 起头(大小写不敏感)—— 一道**语法前缀**守卫,不是形判官:不解析、不看 host / 部件,所以 `https://` 这样的裸 scheme 它也收(见头注「第二个答案」)。
  *  唯一读者是请求面 MCP 传输读器(`readRequestMcpTransport`);S-2106 收口时它退成那个读器座位的「照字面写全」规则,与形判官合取。 */
 export declare function startsWithHttpScheme(raw: string): boolean;

package/dist/url-shape.js

@@ -57,6 +57,24 @@ export function httpUrlFlaws(raw, forbid) {
     const shape = u.protocol === "http:" || u.protocol === "https:" ? [] : ["not-http-url"];
     return [...shape, ...HTTP_URL_PARTS.filter((p) => forbid.includes(p) && present[p])];
 }
+/**
+ * **「后面要拼路径的基址」座位禁用的部件**(闭集、冻结、判序)—— 14.7.0 起的唯一一张。一个值若是别人要往它后面拼路径的基址
+ * (中心基址三席、本实例对中心公告的地址、会话网页链接的基址……):`userinfo` 把凭据放进一个会被记日志、转述、拼路径的值;`query` / `fragment`
+ * 挂在基址上,一拼路径就落到错的位置(`http://x?a=1` + `/v1/…` = `http://x?a=1/v1/…`)。**路径前缀不禁** —— 要拼的路径接在前缀后面。
+ * 这是**策略集,独立于判官词表**({@link HTTP_URL_PARTS} 说的是 URL 有哪些成分,本集说的是这种座位禁哪些):今天两者碰巧同三词,但本集不由词表派生 ——
+ * 词表加词时此处要显式裁(加进来还是明确不加),不会静默多禁一件。冻结:判官读的就是消费方手里的这一只。
+ * 按座位的本质命名,不按某个消费键名:谁的座位是「后面要拼路径的基址」,谁读它,不各自抄词。
+ */
+export const PATH_BASE_URL_FORBIDDEN_PARTS = Object.freeze(["userinfo", "query", "fragment"]);
+/**
+ * 「后面要拼路径的基址」座位的判:`[]` = 合格,否则按判序交回规则词 —— 就是 {@link httpUrlFlaws} 配 {@link PATH_BASE_URL_FORBIDDEN_PARTS},
+ * 不另写判法;规则词的句子取 {@link httpUrlRule}。答案只有词,不含值的任何片段。判**占位展开之后**的值:`http://$(POD_IP):8090` 过
+ * (占位在主机位),`http://[$(POD_IP)]:8090` 拒(方括号里必须是 IPv6 字面量),展开后的 `http://[fd00::1]:8090` 过。
+ * 缺席 / 空串由调用方在判之前处理(对 `""` 本函数答 `not-http-url`)。
+ */
+export function pathBaseUrlFlaws(url) {
+    return httpUrlFlaws(url, PATH_BASE_URL_FORBIDDEN_PARTS);
+}
 /** 以 `http://` / `https://` 起头(大小写不敏感)—— 一道**语法前缀**守卫,不是形判官:不解析、不看 host / 部件,所以 `https://` 这样的裸 scheme 它也收(见头注「第二个答案」)。
  *  唯一读者是请求面 MCP 传输读器(`readRequestMcpTransport`);S-2106 收口时它退成那个读器座位的「照字面写全」规则,与形判官合取。 */
 export function startsWithHttpScheme(raw) {

package/dist/web-admin-credential.js

@@ -25,6 +25,7 @@ import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
 import { buildQuotedIssue } from "./quoted-issue.js";
 import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (a project registration's `archivedAt` reads the same one)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
+import { guardedSafeParse } from "./own-key-read.js"; // the one guarded zod verdict (parse + building its error in one guard)
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
 export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
 /** 一枚**令牌串**的形 —— 裸行 bearer、信封里的 `accessToken` / `refreshToken` 共用这**一条**律:可打印 ASCII
@@ -99,8 +100,10 @@ export function parseWebAdminCredentialFile(text) {
             // JSON.parse 的报错会引用出错位置附近的原文 —— 不转述它。
             return { kind: "unreadable", reason: "envelope is not valid JSON" };
         }
-        const parsed = WebAdminCredentialEnvelope.safeParse(json);
-        return parsed.success ? { kind: "envelope", envelope: parsed.data } : { kind: "unreadable", reason: envelopeRejection(parsed.error) };
+        const parsed = guardedSafeParse(() => WebAdminCredentialEnvelope.safeParse(json)); // 拼拒句时抛(被污染的运行时)⇒ 读不出,不抛出去
+        if (!parsed.ok)
+            return { kind: "unreadable", reason: "envelope could not be read during validation" };
+        return parsed.value.success ? { kind: "envelope", envelope: parsed.value.data } : { kind: "unreadable", reason: envelopeRejection(parsed.value.error) };
     }
     const firstLine = trimmed.split(/[\r\n]/, 1)[0].trim(); // 行尾 = 第一个 CR 或 LF(CRLF / LF / 孤 CR 同判)
     if (!TOKEN_CHARS.test(firstLine))

package/dist/web-admin-session-url.js

@@ -11,7 +11,7 @@
  * 会话不在那一台上就落空。所以模板函数拒绝铸只带一位的链接;解析却**宽读**(旧链接、手输的链接可能缺 `agent`),缺的那一位就是缺席。
  * 链接没有 scope 位(跨空间深链不在这一形里);日后加 scope 时作可选第三位、同一函数,不另开函数。
  */
-import { httpUrlFlaws, httpUrlRule } from "./url-shape.js";
+import { httpUrlRule, pathBaseUrlFlaws } from "./url-shape.js";
 /** 链接的路径与两个参数名 —— 本文件私有,唯一一处。 */
 const SESSION_LINK_PATH = "/chat";
 const WORKER_PARAM = "agent";
@@ -29,7 +29,7 @@ function requiredPart(label, value) {
 export function webAdminSessionUrl(webBaseUrl, target) {
     if (typeof webBaseUrl !== "string")
         throw new TypeError("webAdminSessionUrl: webBaseUrl must be a string (an absolute http(s) URL)");
-    const flaws = httpUrlFlaws(webBaseUrl, ["userinfo", "query", "fragment"]);
+    const flaws = pathBaseUrlFlaws(webBaseUrl); // 「后面要拼路径的基址」座位的唯一判官(禁 userinfo / query / fragment,路径前缀放行)
     if (flaws.length > 0)
         throw new TypeError(`webAdminSessionUrl: webBaseUrl ${httpUrlRule(flaws[0])}`);
     const worker = requiredPart("worker", target?.worker);

package/dist/worker-row-verdict.d.ts

@@ -9,6 +9,17 @@
 import { type ConfigPath } from "./config-fns.js";
 /** 判的是哪一形的行(闭集):`stored` = 店里存着的那一行;`migrated` = 一次性迁移改写出来、还没写回的那一行。 */
 export type WorkerRowForm = "stored" | "migrated";
+/**
+ * zod 的 `invalid_type` 句子(`Invalid input: expected <类型>, received <类型>`)—— 与 zod 自己的话**逐字同**(对每种 JSON 值;`test/migration-row-verdict-14.7.0` 逐值对着 zod 的原句核,升级 zod 改措辞即红),
+ * 区别只有一处:zod 对「原型不是 Object.prototype 的对象」读 `input.constructor.name` 当类型名 —— 原型不是 `Object.prototype` 的(隔离原型)行快照上,用户写的**自有 `constructor` 键**就成了类型名:
+ * 整次调用抛(`constructor.name` 是个对象)、用户文本进拒因(`received hello world`)、句子变样。这里不读 constructor。别的 issue 不管(返回 `undefined` ⇒ 沿用 zod 的 / 包自己写的句子)。
+ * 只给本文件的终判调用(`safeParse` 的 `error` 参数);它在 schema 自带的句子之后、zod 内置句子之前生效。
+ */
+export declare function safeIssueMessage(issue: {
+    readonly code: string;
+    readonly expected?: unknown;
+    readonly input?: unknown;
+}): string | undefined;
 /** 一行的终判:读得进 ⇒ `undefined`;读不进 ⇒ 第一条 issue 的路径(相对该行)+ 拒句(见文件头)。 */
 export declare function workerRowVerdict(row: Readonly<Record<string, unknown>>, form: WorkerRowForm): {
     readonly field: ConfigPath;

package/dist/worker-row-verdict.js

@@ -8,23 +8,79 @@
  */
 import { formatConfigPath, outgoingPath } from "./config-fns.js";
 import { issuePath } from "./issue-path.js";
+import { guardedSafeParse } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
+import { retiredKeyHeldSentence, retiredKeyOfSentence } from "./retired-form.js";
 import { WorkersConfig } from "./types.js";
 /** 每一形的拒句主语 —— 穷举映射型:加一形不补这里即编译红。 */
 const SUBJECT = {
     stored: "the stored worker",
     migrated: "after migration the worker",
 };
+/** 输入的「类型名」(zod 的 `invalid_type` 句子里 `received` 后面那个词):typeof / array / null,**从不读 `constructor`**。形状只问座位;数恒答 `number`
+ *  (非有限的数到不了这里:{@link safeIssueMessage} 把它交还 zod 自己的句子)。 */
+function receivedWord(input) {
+    switch (typeof input) {
+        case "number":
+            return "number";
+        case "object": {
+            const shape = jsonShapeOf(input);
+            switch (shape) {
+                case "null":
+                    return "null";
+                case "array":
+                    return "array";
+                case "plain":
+                case "non_plain_object":
+                case "uninspectable":
+                case "primitive":
+                    return "object";
+                default: {
+                    const unhandled = shape;
+                    throw new Error(`receivedWord: unhandled shape ${String(unhandled)}`);
+                }
+            }
+        }
+        default:
+            return typeof input;
+    }
+}
+/**
+ * zod 的 `invalid_type` 句子(`Invalid input: expected <类型>, received <类型>`)—— 与 zod 自己的话**逐字同**(对每种 JSON 值;`test/migration-row-verdict-14.7.0` 逐值对着 zod 的原句核,升级 zod 改措辞即红),
+ * 区别只有一处:zod 对「原型不是 Object.prototype 的对象」读 `input.constructor.name` 当类型名 —— 原型不是 `Object.prototype` 的(隔离原型)行快照上,用户写的**自有 `constructor` 键**就成了类型名:
+ * 整次调用抛(`constructor.name` 是个对象)、用户文本进拒因(`received hello world`)、句子变样。这里不读 constructor。别的 issue 不管(返回 `undefined` ⇒ 沿用 zod 的 / 包自己写的句子)。
+ * 只给本文件的终判调用(`safeParse` 的 `error` 参数);它在 schema 自带的句子之后、zod 内置句子之前生效。
+ */
+export function safeIssueMessage(issue) {
+    if (issue.code !== "invalid_type")
+        return undefined;
+    // 非有限的数(`NaN` / `±Infinity` —— JSON 写不出 `NaN`;`±Infinity` 只由溢出的数字字面量如 `1e400` 解析出来)的类型名 zod 自己怎么说各版本不同:不抢,交还 zod 自己的句子(它不读 constructor)
+    if (typeof issue.input === "number" && !Number.isFinite(issue.input))
+        return undefined;
+    const expected = issue.expected === "nan" ? "NaN" : String(issue.expected);
+    return `Invalid input: expected ${expected}, received ${receivedWord(issue.input)}`;
+}
 /** 一只单行域里的 issue 路径 → 相对那一行(去掉 `["workers", 0]` 前缀;不在那一行下的 issue 原样)。 */
 function rowRelative(path) {
     return path[0] === "workers" && path[1] === 0 ? path.slice(2) : path;
 }
+/** 一条 issue 在拒句里的样子:`<坐标>: <句子>`;墓碑 issue(旧形字段还在盘上)换成读面的说法 —— 坐标就是退役键名,拒句的文字里不点名它(结构化的 `field` 已经指到它),指现行位与出路。 */
+function issueText(i) {
+    const tombstone = retiredKeyOfSentence(i.message);
+    return tombstone !== undefined ? retiredKeyHeldSentence(tombstone.form) : `${formatConfigPath(outgoingPath(rowRelative(issuePath(i))))}: ${i.message}`;
+}
 /** 一行的终判:读得进 ⇒ `undefined`;读不进 ⇒ 第一条 issue 的路径(相对该行)+ 拒句(见文件头)。 */
 export function workerRowVerdict(row, form) {
-    const verdict = WorkersConfig.safeParse({ workers: [row] });
+    // 校验过程抛(会抛的 getter / 陷阱:读侧交进来的是调用方的活对象;zod 4.6 首读 `error` 时拼句子抛 —— 被污染的运行时、另一 realm 的怪形值)⇒ 这一行判「读不出」
+    // (定句,不含任何用户文本),不抛出调用。首读 `error` 与 `safeParse` 同在一只守护里(`guardedSafeParse`),两版 zod 同答
+    const judged = guardedSafeParse(() => WorkersConfig.safeParse({ workers: [row] }, { error: (iss) => safeIssueMessage(iss) }));
+    if (!judged.ok)
+        return { field: [], reason: `${SUBJECT[form]} is not a valid WorkerSpec — a value could not be read during validation` };
+    const verdict = judged.value;
     if (verdict.success)
         return undefined;
     const issues = verdict.error.issues;
-    const shown = issues.slice(0, 3).map((i) => `${formatConfigPath(outgoingPath(rowRelative(issuePath(i))))}: ${i.message}`);
+    const shown = issues.slice(0, 3).map(issueText);
     const more = issues.length > shown.length ? ` (+${issues.length - shown.length} more)` : "";
     const first = issues[0];
     return { field: first === undefined ? [] : rowRelative(issuePath(first)), reason: `${SUBJECT[form]} is not a valid WorkerSpec — ${shown.join("; ")}${more}` };

package/dist/workers-rows.js

@@ -15,29 +15,57 @@
  * web-admin 在列表里标红点名 `field` / `reason`。拒因只点名字段、不回显值。
  */
 import { outgoingPath, redactSecrets } from "./config-fns.js";
+import { appendOwn, dataDescriptor, ownDeclaredValueOf, ownElementsOf, ownEntriesOf } from "./own-key-read.js";
 import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js";
 import { workerRowVerdict } from "./worker-row-verdict.js";
+/**
+ * 扣下坏行后的文档:调用方文档的其余自有键 + 换掉的 `workers`。**不对调用方的整份文档做展开**(`{ ...raw }` 会对它做 `[[OwnPropertyKeys]]` + 逐键 `[[Get]]`:无关键上会抛的 getter / `ownKeys` 陷阱
+ * 把嵌入方自己抛的值带出调用)—— 其余键经内核的 `ownEntriesOf` 读(整容器律:每个自有串键一份描述符、只从描述符取值,全或无):**其余键里只要有一个读不成纯数据**(访问器 / 隐藏键)
+ * 或整份读不出(`ownKeys` / `getOwnPropertyDescriptor` 陷阱抛)⇒ 其余键**一个都不带出**,只剩 `workers`;符号键从不带出(内核只认串键)。workers 域只有 `workers` 一个键,
+ * 其余键本来就是未知键(读侧剥掉、只进未知键告警),所以这一答只影响那条告警点名哪些键。交出的是寻常对象。
+ */
+function withWorkers(raw, kept) {
+    const doc = {};
+    const entries = ownEntriesOf(raw);
+    // 键序同展开(`{ ...raw, workers: kept }`):`workers` 留在它原来的位置
+    if (entries.ok)
+        for (const [key, value] of entries.value)
+            Object.defineProperty(doc, key, dataDescriptor(key === "workers" ? kept : value));
+    if (!Object.hasOwn(doc, "workers"))
+        Object.defineProperty(doc, "workers", dataDescriptor(kept));
+    return doc;
+}
 /**
  * 逐行读一份 workers 域**原始**文档(`{ workers: [...] }`)。不是这个形 ⇒ 原样返回、零扣下(判形是 `parseDomain` 的事)。
  * 规则见文件头。
  */
 export function readWorkersRows(raw) {
-    if (!isPlainJsonObject(raw) || !isJsonArray(raw.workers))
+    // 读调用方的对象一律经内核(一份描述符里取值,不问 `get` 陷阱;原型链上被污染的 `workers` / `name` 不是文档里写着的):
+    //  · `workers` 键与每行的 `name` —— 严归类(逐键一次描述符,键缺席时再问一次 `has`;访问器 / 隐藏键 ⇒ 读不成纯数据);
+    //  · `workers` 数组的元素 —— 按校验器解析数组的读法(内核的 `ownElementsOf`:只看下标键,数据下标取值、隐藏下标照读、访问器下标调它自己的 getter 一次;挂在数组上的非下标键不看)。
+    // `workers` 读不成纯数据 / 元素读不出(结构陷阱抛、下标的 getter 抛)⇒ 「不是这个形」,原样放行交整域读侧判(不按条丢:丢一行 = 对账方把那只 worker 当作已撤销);行的 `name` 读不出 ⇒ 「认不出名字」,该行原样留在 doc
+    if (!isPlainJsonObject(raw))
+        return { doc: raw, held: [] };
+    const workers = ownDeclaredValueOf(raw, "workers");
+    if (!workers.ok || !isJsonArray(workers.value))
+        return { doc: raw, held: [] };
+    const rows = ownElementsOf(workers.value);
+    if (!rows.ok)
         return { doc: raw, held: [] };
-    const rows = raw.workers;
     const kept = [];
     const held = [];
-    rows.forEach((row, index) => {
-        if (!isPlainJsonObject(row) || typeof row.name !== "string") {
-            kept.push(row); // 认不出名字:整域读侧判
-            return;
+    for (const [index, row] of rows.value) {
+        const name = isPlainJsonObject(row) ? ownDeclaredValueOf(row, "name") : undefined;
+        if (!isPlainJsonObject(row) || name === undefined || !name.ok || typeof name.value !== "string") {
+            appendOwn(kept, row); // 认不出名字:整域读侧判(这一读口的追加都走定义语义:`push` 会被继承的数字键 setter 吞掉)
+            continue;
         }
         const v = workerRowVerdict(row, "stored");
         // 坐标与拒因都走出门那一道:issue 路径里的 Record 键是用户写的(例:一个不合法的 env 键名可能就是粘错位置的凭据)。
         if (v === undefined)
-            kept.push(row);
+            appendOwn(kept, row);
         else
-            held.push({ name: row.name, index, field: outgoingPath(v.field), reason: redactSecrets(v.reason), original: row });
-    });
-    return held.length === 0 ? { doc: raw, held } : { doc: { ...raw, workers: kept }, held };
+            appendOwn(held, { name: name.value, index, field: outgoingPath(v.field), reason: redactSecrets(v.reason), original: row });
+    }
+    return held.length === 0 ? { doc: raw, held } : { doc: withWorkers(raw, kept), held };
 }

package/dist/zod-unwrap.d.ts

@@ -9,3 +9,9 @@ import { z } from "zod";
  *  不是变换的那一侧。两侧都是 schema 的管道(`a.pipe(b)`)不是包装:到此为止(按它本身的形判,认不出就不抢救)。
  *  `.refine()` / `.superRefine()` 在 zod 4 里不是包装层(判据挂在同一只 schema 上),无须展开。 */
 export declare function unwrapSchema(schema: z.ZodType): z.ZodType;
+/** 剥一层包装:`wrapper` = `.optional()` 一类(`.unwrap()`);`preprocess` = `z.preprocess(f, schema)`(变换在**输入**侧,先于里面的 schema);`postprocess` = `.transform(f)`(变换在输出侧)。不是包装 ⇒ `undefined`。
+ *  `unwrapSchema` 把三种都一视同仁地剥掉(「条目能不能单独解析」与变换无关);要区分的读者(按声明键投影:输入侧的变换会看到整个值,投影不了)用它。 */
+export declare function unwrapOnce(cur: z.ZodType): {
+    readonly next: z.ZodType;
+    readonly via: "wrapper" | "preprocess" | "postprocess";
+} | undefined;

package/dist/zod-unwrap.js

@@ -12,14 +12,21 @@ export function unwrapSchema(schema) {
     let cur = schema;
     // 有界:包装层数是 schema 作者写出来的常数,8 层远超实际(防被畸形 schema 拖住)。
     for (let i = 0; i < 8; i++) {
-        if (cur instanceof z.ZodOptional || cur instanceof z.ZodNullable || cur instanceof z.ZodDefault || cur instanceof z.ZodPrefault || cur instanceof z.ZodCatch)
-            cur = cur.unwrap();
-        else if (cur instanceof z.ZodPipe && cur.in instanceof z.ZodTransform)
-            cur = cur.out;
-        else if (cur instanceof z.ZodPipe && cur.out instanceof z.ZodTransform)
-            cur = cur.in;
-        else
+        const step = unwrapOnce(cur);
+        if (step === undefined)
             return cur;
+        cur = step.next;
     }
     return cur;
 }
+/** 剥一层包装:`wrapper` = `.optional()` 一类(`.unwrap()`);`preprocess` = `z.preprocess(f, schema)`(变换在**输入**侧,先于里面的 schema);`postprocess` = `.transform(f)`(变换在输出侧)。不是包装 ⇒ `undefined`。
+ *  `unwrapSchema` 把三种都一视同仁地剥掉(「条目能不能单独解析」与变换无关);要区分的读者(按声明键投影:输入侧的变换会看到整个值,投影不了)用它。 */
+export function unwrapOnce(cur) {
+    if (cur instanceof z.ZodOptional || cur instanceof z.ZodNullable || cur instanceof z.ZodDefault || cur instanceof z.ZodPrefault || cur instanceof z.ZodCatch)
+        return { next: cur.unwrap(), via: "wrapper" };
+    if (cur instanceof z.ZodPipe && cur.in instanceof z.ZodTransform)
+        return { next: cur.out, via: "preprocess" };
+    if (cur instanceof z.ZodPipe && cur.out instanceof z.ZodTransform)
+        return { next: cur.in, via: "postprocess" };
+    return undefined;
+}