@sema-agent/settings-schema 14.5.0 → 14.7.0

package/dist/types.js

@@ -21,6 +21,8 @@ import { INTEGER } from "./integer.js";
 import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody depth cap with the hash cap (R18)
 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
@@ -216,62 +218,66 @@ export const NON_SECRET_URL_NO_MIGRATION = createNonSecretUrl(false);
  *  is proven plain JSON (no toJSON/getters), the stored original == what JSON.stringify persists — closing the
  *  non-idempotent-toJSON / accessor-leak / non-plain-container bypasses. Round 2-5 hardening. */
 export function extraBodyUnsafe(v) {
-    const stack = [[v, 0]];
-    const seen = new WeakSet();
-    let budget = 100_000;
-    while (stack.length) {
-        if (budget-- <= 0)
-            return true; // too large to vet → fail-closed
-        const [cur, depth] = stack.pop();
-        if (depth > MAX_EXTRA_BODY_DEPTH)
-            return true; // too deep to hash later — cap = hash cap MINUS the wrapper reserve, since extraBody is always hashed NESTED (R18: a value passing at the raw hash cap would still overflow once wrapped → write fail-open + read hard-DoS)
-        if (cur === null)
-            continue;
-        const t = typeof cur;
-        if (t === "string") {
-            if (containsSecretToken(cur))
-                return true; // tokenized (mid-string secret too) — sibling of URL/coords/mcp. R8
-            continue;
-        }
-        if (t === "number") {
-            if (!Number.isFinite(cur))
-                return true; // Infinity/NaN → JSON null on persist
-            continue;
-        }
-        if (t === "boolean")
-            continue;
-        if (t !== "object")
-            return true; // undefined / function / symbol / bigint
-        if (seen.has(cur))
-            return true; // cycle → reject (would also break stableStringify)
-        seen.add(cur);
-        if (Array.isArray(cur)) {
-            if (cur.length !== Object.keys(cur).length)
-                return true; // sparse array (holes → null on persist)
-            // descriptor walk for arrays too (NOT `for…of`/index access — that would INVOKE an accessor index's
-            // getter, which could throw a secret-bearing message). Reject accessor elements. R11.
+    try {
+        const stack = [[v, 0]];
+        const seen = new WeakSet();
+        let budget = 100_000;
+        while (stack.length) {
+            if (budget-- <= 0)
+                return true; // too large to vet → fail-closed
+            const [cur, depth] = stack.pop();
+            if (depth > MAX_EXTRA_BODY_DEPTH)
+                return true; // too deep to hash later — cap = hash cap MINUS the wrapper reserve, since extraBody is always hashed NESTED (R18: a value passing at the raw hash cap would still overflow once wrapped → write fail-open + read hard-DoS)
+            if (cur === null)
+                continue;
+            const t = typeof cur;
+            if (t === "string") {
+                if (containsSecretToken(cur))
+                    return true; // tokenized (mid-string secret too) — sibling of URL/coords/mcp. R8
+                continue;
+            }
+            if (t === "number") {
+                if (!Number.isFinite(cur))
+                    return true; // Infinity/NaN → JSON null on persist
+                continue;
+            }
+            if (t === "boolean")
+                continue;
+            if (t !== "object")
+                return true; // undefined / function / symbol / bigint
+            if (seen.has(cur))
+                return true; // cycle → reject (would also break stableStringify)
+            seen.add(cur);
+            if (isJsonArray(cur)) {
+                if (cur.length !== Object.keys(cur).length)
+                    return true; // sparse array (holes → null on persist)
+                // descriptor walk for arrays too (NOT `for…of`/index access — that would INVOKE an accessor index's
+                // getter, which could throw a secret-bearing message). Reject accessor elements. R11.
+                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 (isAccessorDescriptor(desc))
+                        return true; // accessor element — do NOT invoke
+                    appendOwn(stack, [desc.value, depth + 1]); // 定义语义压栈:`push` 会被继承的数字键 setter 吞掉,遍历一层都不下、秘密静默漏判
+                }
+                continue;
+            }
+            if (!isPlainJsonObject(cur))
+                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 (k === "length")
-                    continue; // the array's own `length` data prop — not an element
-                if (!("value" in desc))
-                    return true; // accessor element — do NOT invoke
-                stack.push([desc.value, depth + 1]);
+                if (isAccessorDescriptor(desc))
+                    return true; // accessor (get/set) — do NOT invoke
+                if (containsSecretToken(k))
+                    return true; // secret-shaped KEY (tokenized). R8
+                appendOwn(stack, [desc.value, depth + 1]); // 定义语义压栈:`push` 会被继承的数字键 setter 吞掉,遍历一层都不下、秘密静默漏判
             }
-            continue;
-        }
-        const proto = Object.getPrototypeOf(cur);
-        if (proto !== Object.prototype && proto !== null)
-            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 (!("value" in 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]);
         }
+        return false;
+    }
+    catch {
+        return true; // a value the walk cannot read (a proxy that has been revoked, a trap that throws) cannot be vetted ⇒ UNSAFE (fail-closed), never a throw
     }
-    return false;
 }
 /** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`,
  *  `ModelEntry.compat` and `ModelEntry.headers` share this ONE function (1.10.0; before that it was inline in `extraBody`
@@ -518,8 +524,7 @@ export const ModelEntry = z.object({
         .transform((v, ctx) => {
         if (v === undefined)
             return undefined;
-        const proto = typeof v === "object" && v !== null ? Object.getPrototypeOf(v) : undefined;
-        if (typeof v !== "object" || v === null || Array.isArray(v) || (proto !== Object.prototype && proto !== null)) {
+        if (!isPlainJsonObject(v)) {
             ctx.addIssue({ code: "custom", ...buildQuotedIssue `extraBody must be a plain JSON object` });
             return z.NEVER;
         }
@@ -601,7 +606,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` 里点名的那几个。 */
@@ -1603,7 +1608,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) };

package/dist/url-shape.d.ts

@@ -13,10 +13,16 @@
  *
  * 拒句里值的样子(展示铸点)不在本模块:那是各宿主自己的展示律(server `buildRefusalShownUrl`)。本模块零 import,纯函数,浏览器安全。
  *
- * ## 本模块里的第二个答案(如实,14.0.0)
+ * ## 本模块里的第二个答案(如实,14.0.0 起;14.6.0 把分歧写成读数)
  * 请求面 MCP 传输的 url(任务提交体 `mcpServers[i].transport.url`,`./mcp-request-entry`)今天不走上面的形判官,而是只看前缀
- * ({@link startsWithHttpScheme}):那是消费方请求腿既有的读法,入包时语义逐字冻结。两者对同一个值可以答得不同(空 host、带 userinfo 的
- * url 前缀判收、形判官拒)—— 一项已知待收的分歧;放在这里,是为了让「本包里判 URL 的正则」只有这一个模块。
+ * ({@link startsWithHttpScheme}):那是消费方请求腿既有的读法,入包时语义逐字冻结。两者对同一个串的答案是两张表(读数逐串钉在 `test/request-url-two-answers-14.6.0.test.ts`):
+ *  · **读器收、判官拒** —— 前缀对、WHATWG 解析不了的串:裸 scheme `https://`、host 里有空格、未闭合的 IPv6 字面量、非法端口……读器收下,判官答 `not-http-url`;
+ *  · **判官收、读器拒** —— 不是照字面写全 `http(s)://` 的串:`https:host`、前导空白。WHATWG 会把它们修成合法 URL,读器按字面规则拒;
+ *  · **部件** —— 读器的座位今天不禁 userinfo / query / fragment(全收),判官在禁这些部件的座位上点名它们。
+ * 这是一项**已知待收、收口是收紧所以不走 minor** 的分歧(S-2106):读器收下的是此前能解析出传输的提交体(含重放存量提交体时读它的那一路),把读器收严 = 同一份配置解析出不同结果,发版纪律里是 major,
+ * 不是 minor;而「读器直接换成判官」还会放宽第二张表,更不行。S-2106 的收口形与 `PLUGIN_ORIGIN` 座位(`./types`)同构 —— 读器收 ⟺ `startsWithHttpScheme(url)`(座位自己的「照字面写全」规则)∧
+ * `httpUrlFlaws(url, [座位禁的部件]).length === 0`(形与部件归本判官)—— 只收紧,不放宽;座位禁不禁 userinfo 是同一次 major 里要定的另一格(读器的拒句已写着凭据别放 URL)。
+ * 这个前缀守卫放在这里,是为了让「本包里判 URL 的正则」只有这一个模块。
  */
 /** 座位可以禁掉的部件(闭集;判序 = 本数组序)。 */
 export declare const HTTP_URL_PARTS: readonly ["userinfo", "query", "fragment"];
@@ -35,8 +41,24 @@ 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>;
-/** 以 `http://` / `https://` 起头(大小写不敏感)—— 一道**语法前缀**守卫,不是形判官:不解析、不看 host / 部件(见头注「第二个答案」)。
- *  唯一读者是请求面 MCP 传输读器(`readRequestMcpTransport`)。 */
+/**
+ * **「后面要拼路径的基址」座位禁用的部件**(闭集、冻结、判序)—— 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;
 /** 一个拒因词的规则句(穷举;新词不补 = 编译红)。句子只说规则,不含值。 */
 export declare function httpUrlRule(flaw: HttpUrlFlaw): string;

package/dist/url-shape.js

@@ -13,10 +13,16 @@
  *
  * 拒句里值的样子(展示铸点)不在本模块:那是各宿主自己的展示律(server `buildRefusalShownUrl`)。本模块零 import,纯函数,浏览器安全。
  *
- * ## 本模块里的第二个答案(如实,14.0.0)
+ * ## 本模块里的第二个答案(如实,14.0.0 起;14.6.0 把分歧写成读数)
  * 请求面 MCP 传输的 url(任务提交体 `mcpServers[i].transport.url`,`./mcp-request-entry`)今天不走上面的形判官,而是只看前缀
- * ({@link startsWithHttpScheme}):那是消费方请求腿既有的读法,入包时语义逐字冻结。两者对同一个值可以答得不同(空 host、带 userinfo 的
- * url 前缀判收、形判官拒)—— 一项已知待收的分歧;放在这里,是为了让「本包里判 URL 的正则」只有这一个模块。
+ * ({@link startsWithHttpScheme}):那是消费方请求腿既有的读法,入包时语义逐字冻结。两者对同一个串的答案是两张表(读数逐串钉在 `test/request-url-two-answers-14.6.0.test.ts`):
+ *  · **读器收、判官拒** —— 前缀对、WHATWG 解析不了的串:裸 scheme `https://`、host 里有空格、未闭合的 IPv6 字面量、非法端口……读器收下,判官答 `not-http-url`;
+ *  · **判官收、读器拒** —— 不是照字面写全 `http(s)://` 的串:`https:host`、前导空白。WHATWG 会把它们修成合法 URL,读器按字面规则拒;
+ *  · **部件** —— 读器的座位今天不禁 userinfo / query / fragment(全收),判官在禁这些部件的座位上点名它们。
+ * 这是一项**已知待收、收口是收紧所以不走 minor** 的分歧(S-2106):读器收下的是此前能解析出传输的提交体(含重放存量提交体时读它的那一路),把读器收严 = 同一份配置解析出不同结果,发版纪律里是 major,
+ * 不是 minor;而「读器直接换成判官」还会放宽第二张表,更不行。S-2106 的收口形与 `PLUGIN_ORIGIN` 座位(`./types`)同构 —— 读器收 ⟺ `startsWithHttpScheme(url)`(座位自己的「照字面写全」规则)∧
+ * `httpUrlFlaws(url, [座位禁的部件]).length === 0`(形与部件归本判官)—— 只收紧,不放宽;座位禁不禁 userinfo 是同一次 major 里要定的另一格(读器的拒句已写着凭据别放 URL)。
+ * 这个前缀守卫放在这里,是为了让「本包里判 URL 的正则」只有这一个模块。
  */
 /** 座位可以禁掉的部件(闭集;判序 = 本数组序)。 */
 export const HTTP_URL_PARTS = ["userinfo", "query", "fragment"];
@@ -51,8 +57,26 @@ 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])];
 }
-/** 以 `http://` / `https://` 起头(大小写不敏感)—— 一道**语法前缀**守卫,不是形判官:不解析、不看 host / 部件(见头注「第二个答案」)。
- *  唯一读者是请求面 MCP 传输读器(`readRequestMcpTransport`)。 */
+/**
+ * **「后面要拼路径的基址」座位禁用的部件**(闭集、冻结、判序)—— 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) {
     return /^https?:\/\//i.test(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,19 +8,69 @@
  */
 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 { 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;
 }
 /** 一行的终判:读得进 ⇒ `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;

package/dist/workers-rows.d.ts

@@ -7,7 +7,8 @@
  * web-admin 的 workers 读口先过本函数:每一只**认得出名字**的 worker 单独过读侧自己的判据(只含这一行的 workers 域读不读得进,
  * `WorkersConfig` —— 与 `parseDomain("workers")` 同一只 schema,不另抄任何规则;判据与拒句拼装在包内私有的 `./worker-row-verdict`,
  * 一次性迁移 SS-M4 判改写后的行调同一只);读不进的那一行扣下(`held`,带原文与拒因),
- * 其余照常进 `doc`。整域读侧仍是最后围栏,只剩两类归它:认不出名字的条目(不是对象 / 没有字符串名字 —— 原样留在 `doc`)与跨行规则
+ * 其余照常进 `doc`。整域读侧仍是最后围栏,只剩两类归它:认不出名字的条目(不是朴素 JSON 对象〔类实例 / `Map` / `Date` 一类,JSON 解析不出来,走到这里只能是程序拼的〕/ 没有字符串名字 —— 原样留在 `doc`;
+ * 非朴素的**坏**行因此不在这里单行扣下,而是交整域 `parseDomain("workers")` 判,整张舰队清单读不出 —— 响亮、fail-closed,只落在非 JSON 值上)与跨行规则
  * (名字 / 路由前缀唯一 —— 两行单独都读得进、合起来才不行,这里不替运维挑留哪一行)。
  *
  * 被扣下的行**不进** `doc`,但随 `held[].original` 逐字带回:`doc` ∪ `held[].original` 覆盖输入的全部 worker。读口不写回 —— 原文留在盘上,

package/dist/workers-rows.js

@@ -7,36 +7,65 @@
  * web-admin 的 workers 读口先过本函数:每一只**认得出名字**的 worker 单独过读侧自己的判据(只含这一行的 workers 域读不读得进,
  * `WorkersConfig` —— 与 `parseDomain("workers")` 同一只 schema,不另抄任何规则;判据与拒句拼装在包内私有的 `./worker-row-verdict`,
  * 一次性迁移 SS-M4 判改写后的行调同一只);读不进的那一行扣下(`held`,带原文与拒因),
- * 其余照常进 `doc`。整域读侧仍是最后围栏,只剩两类归它:认不出名字的条目(不是对象 / 没有字符串名字 —— 原样留在 `doc`)与跨行规则
+ * 其余照常进 `doc`。整域读侧仍是最后围栏,只剩两类归它:认不出名字的条目(不是朴素 JSON 对象〔类实例 / `Map` / `Date` 一类,JSON 解析不出来,走到这里只能是程序拼的〕/ 没有字符串名字 —— 原样留在 `doc`;
+ * 非朴素的**坏**行因此不在这里单行扣下,而是交整域 `parseDomain("workers")` 判,整张舰队清单读不出 —— 响亮、fail-closed,只落在非 JSON 值上)与跨行规则
  * (名字 / 路由前缀唯一 —— 两行单独都读得进、合起来才不行,这里不替运维挑留哪一行)。
  *
  * 被扣下的行**不进** `doc`,但随 `held[].original` 逐字带回:`doc` ∪ `held[].original` 覆盖输入的全部 worker。读口不写回 —— 原文留在盘上,
  * 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";
-const isRec = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/**
+ * 扣下坏行后的文档:调用方文档的其余自有键 + 换掉的 `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 (!isRec(raw) || !Array.isArray(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 (!isRec(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;
+}