@sema-agent/settings-schema 10.1.0 → 11.0.0

package/dist/url-shape.d.ts

@@ -0,0 +1,34 @@
+/**
+ * **「这个配置值是不是一个交给 `fetch` 的 http(s) URL、哪些部件禁」的唯一形判官**(11.0.0;lift 自 server `src/url-shape.ts`,
+ * 规则与拒因词闭集逐字搬)。本包 `NON_SECRET_URL` 由它定义;server 的同名判官改 re-export 本模块,client-core 改 import ——
+ * 同一个值在 web-admin 目录、server env 与客户端只有一个答案。
+ *
+ * ## 规则(一条)
+ * 一个座位问的只有两件事:① 它是不是一个**层级式的 http(s) URL**(`http(s)://host[:port][/path]` —— `//` authority 在场、
+ * scheme ∈ {http, https});② 这个座位禁掉的那几件部件(userinfo / query / fragment,闭集)在不在。答案是一串**规则词**
+ * ({@link httpUrlFlaws}),规则句由 {@link httpUrlRule} 给,句子只说规则、不含值。
+ *
+ * 部件按 WHATWG 序列化串(`href`)认:空 query `x?` 与空 fragment `x#` 在 `href` 里保留分隔符,`search` / `hash` 却是空串 ——
+ * 只看后者会把它们放过去(改前本包 `NON_SECRET_URL` 正是这样收下了 `https://gw/v1#`)。
+ *
+ * 拒句里值的样子(展示铸点)不在本模块:那是各宿主自己的展示律(server `buildRefusalShownUrl`)。本模块零 import,纯函数,浏览器安全。
+ */
+/** 座位可以禁掉的部件(闭集;判序 = 本数组序)。 */
+export declare const HTTP_URL_PARTS: readonly ["userinfo", "query", "fragment"];
+export type HttpUrlPart = (typeof HTTP_URL_PARTS)[number];
+/** 判官的拒因词(闭集):形不对,或一件被禁的部件在场。 */
+export type HttpUrlFlaw = "not-http-url" | HttpUrlPart;
+/** 「不是一个 http(s) URL」的规则句 —— 不透明形、不可解析、层级式非 http(s) 同一句;只点名规则,不回显 scheme。 */
+export declare const HTTP_URL_SHAPE_RULE = "is not a parseable http(s) URL (scheme must be http or https; it must look like http(s)://host[:port][/path])";
+/**
+ * 层级式绝对 URL(`scheme://host…`,任意 scheme):能解析、且序列化后 `scheme:` 之后紧跟 `//`。`host:8888` / `alice:pw@host`
+ * 这类会被解析成**不透明** URL 的形(冒号前那一段被读成 scheme)不算。特殊 scheme(http / https …)恒层级式(WHATWG 补 `//`)。
+ */
+export declare function isHierarchicalUrl(raw: string): boolean;
+/**
+ * 判:合格 ⇒ `[]`;否则按判序交回规则词。形不对且不透明 ⇒ 只有 `not-http-url`(部件在不透明形上无从判,也不需要判 —— 那一形整只不收);
+ * 层级式非 http(s) ⇒ `not-http-url` 之后照判部件。返回类型按 `forbid` 收窄:座位没禁的部件不会出现在答案里。
+ */
+export declare function httpUrlFlaws<P extends HttpUrlPart>(raw: string, forbid: readonly P[]): ReadonlyArray<"not-http-url" | P>;
+/** 一个拒因词的规则句(穷举;新词不补 = 编译红)。句子只说规则,不含值。 */
+export declare function httpUrlRule(flaw: HttpUrlFlaw): string;

package/dist/url-shape.js

@@ -0,0 +1,61 @@
+/**
+ * **「这个配置值是不是一个交给 `fetch` 的 http(s) URL、哪些部件禁」的唯一形判官**(11.0.0;lift 自 server `src/url-shape.ts`,
+ * 规则与拒因词闭集逐字搬)。本包 `NON_SECRET_URL` 由它定义;server 的同名判官改 re-export 本模块,client-core 改 import ——
+ * 同一个值在 web-admin 目录、server env 与客户端只有一个答案。
+ *
+ * ## 规则(一条)
+ * 一个座位问的只有两件事:① 它是不是一个**层级式的 http(s) URL**(`http(s)://host[:port][/path]` —— `//` authority 在场、
+ * scheme ∈ {http, https});② 这个座位禁掉的那几件部件(userinfo / query / fragment,闭集)在不在。答案是一串**规则词**
+ * ({@link httpUrlFlaws}),规则句由 {@link httpUrlRule} 给,句子只说规则、不含值。
+ *
+ * 部件按 WHATWG 序列化串(`href`)认:空 query `x?` 与空 fragment `x#` 在 `href` 里保留分隔符,`search` / `hash` 却是空串 ——
+ * 只看后者会把它们放过去(改前本包 `NON_SECRET_URL` 正是这样收下了 `https://gw/v1#`)。
+ *
+ * 拒句里值的样子(展示铸点)不在本模块:那是各宿主自己的展示律(server `buildRefusalShownUrl`)。本模块零 import,纯函数,浏览器安全。
+ */
+/** 座位可以禁掉的部件(闭集;判序 = 本数组序)。 */
+export const HTTP_URL_PARTS = ["userinfo", "query", "fragment"];
+/** 「不是一个 http(s) URL」的规则句 —— 不透明形、不可解析、层级式非 http(s) 同一句;只点名规则,不回显 scheme。 */
+export const HTTP_URL_SHAPE_RULE = "is not a parseable http(s) URL (scheme must be http or https; it must look like http(s)://host[:port][/path])";
+/**
+ * 层级式绝对 URL(`scheme://host…`,任意 scheme):能解析、且序列化后 `scheme:` 之后紧跟 `//`。`host:8888` / `alice:pw@host`
+ * 这类会被解析成**不透明** URL 的形(冒号前那一段被读成 scheme)不算。特殊 scheme(http / https …)恒层级式(WHATWG 补 `//`)。
+ */
+export function isHierarchicalUrl(raw) {
+    if (!URL.canParse(raw))
+        return false;
+    const u = new URL(raw);
+    return u.href.startsWith(`${u.protocol}//`);
+}
+/**
+ * 判:合格 ⇒ `[]`;否则按判序交回规则词。形不对且不透明 ⇒ 只有 `not-http-url`(部件在不透明形上无从判,也不需要判 —— 那一形整只不收);
+ * 层级式非 http(s) ⇒ `not-http-url` 之后照判部件。返回类型按 `forbid` 收窄:座位没禁的部件不会出现在答案里。
+ */
+export function httpUrlFlaws(raw, forbid) {
+    if (!isHierarchicalUrl(raw))
+        return ["not-http-url"];
+    const u = new URL(raw);
+    // 分隔符按 WHATWG 序列化串认:userinfo / path / query 里的 `#`、userinfo / path 里的 `?` 都被百分号编码,
+    // 所以 href 里第一个 `#` 就是 fragment 的分隔符、它之前第一个 `?` 就是 query 的分隔符。
+    const hashAt = u.href.indexOf("#");
+    const present = {
+        userinfo: u.username !== "" || u.password !== "",
+        query: (hashAt < 0 ? u.href : u.href.slice(0, hashAt)).includes("?"),
+        fragment: hashAt >= 0,
+    };
+    const shape = u.protocol === "http:" || u.protocol === "https:" ? [] : ["not-http-url"];
+    return [...shape, ...HTTP_URL_PARTS.filter((p) => forbid.includes(p) && present[p])];
+}
+/** 一个拒因词的规则句(穷举;新词不补 = 编译红)。句子只说规则,不含值。 */
+export function httpUrlRule(flaw) {
+    switch (flaw) {
+        case "not-http-url":
+            return HTTP_URL_SHAPE_RULE;
+        case "userinfo":
+            return "must not carry userinfo (credentials in the URL are logged, reported and handed to fetch; they belong in a credential setting)";
+        case "query":
+            return "must not carry a query (request paths are appended to this base)";
+        case "fragment":
+            return "must not carry a fragment (it is never sent, and anything appended after it is dropped with it)";
+    }
+}

package/dist/web-admin-credential.d.ts

@@ -0,0 +1,96 @@
+/**
+ * web-admin 凭证的**文件形契约** —— S-698(design/325 §1)。
+ *
+ * 引擎向 web-admin 出站时用的凭证由部署声明(见 server 的凭证模块,单属主);声明成文件时
+ * (`SEMA_WEB_ADMIN_TOKEN_FILE`),文件内容有两种**种类**,不是一种语义的两种拼法:
+ *
+ *  · **裸行**(一个静态令牌):首行 = 静态 bearer,只收可打印 ASCII({@link TokenString} 的律)。它是用户 JWT 还是 worker
+ *    拉取令牌,由读方用 `looksLikeJwt`(`./api/auth-bridge`)自判 —— 本文件不重判种类。
+ *  · **信封**:一个 JSON 对象,形 = {@link WebAdminCredentialEnvelope}。今只有一员 `kind:"user-session"`
+ *    (人的登录会话:可轮换的访问令牌 + 单次有效的刷新令牌 + 到期时刻 + 签发它的 web-admin 根 URL)。worker 拉取
+ *    令牌**不进信封**:它不轮换、不属于人,保持裸行。
+ *
+ * 判别律(一条,{@link parseWebAdminCredentialFile} 是它的**唯一**实现):内容 `trim()` 后以 `{` 开头 ⇒ 只按
+ * 信封读,读不成 = `unreadable`(**不回落**成裸行 —— 一个 `{` 开头的裸 token 不存在,回落只会把一段坏 JSON
+ * 当 bearer 发出去);否则裸行;空 = `unreadable`。同一份内容只有一种读法(零双读)。
+ *
+ * 声明面(本文件尾段):凭证的二选一判官 {@link judgeWebAdminCredentialDeclaration},读 env 名表 {@link WEB_ADMIN_ENV}
+ * (`./web-admin-env`,八键)里的 `token` / `tokenFile` 两键。
+ *
+ * 纯契约:零 IO(读文件、写文件、续签都是消费方的事),browser-safe,与本包其余部分同一条纯度律。
+ */
+import { z } from "zod";
+/** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
+export declare const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND: "user-session";
+/**
+ * web-admin 凭证**信封**(`SEMA_WEB_ADMIN_TOKEN_FILE` 指向的文件是一个 JSON 对象时的唯一形)。`.strict()`:
+ * 多一个键就不是这份契约(拼错的 `refresh_token` 被静默剥掉,续签就会拿着缺席的刷新令牌去撞 web-admin)。
+ *
+ *  · `accessToken` —— 出站 bearer(web-admin 签的用户 JWT,形判 `looksLikeJwt`);读方拿它做身份分箱的方式与裸行
+ *    `user-jwt` 逐字同。令牌形与裸行同一条律({@link TokenString})。
+ *  · `refreshToken` —— 单次有效、严格轮换(`POST /api/v1/auth/token/refresh`,见 `./api/auth`);续签前**重读
+ *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
+ *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
+ *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
+ *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ */
+export declare const WebAdminCredentialEnvelope: z.ZodObject<{
+    kind: z.ZodLiteral<"user-session">;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    issuer: z.ZodString;
+}, z.core.$strict>;
+export type WebAdminCredentialEnvelope = z.infer<typeof WebAdminCredentialEnvelope>;
+/** {@link parseWebAdminCredentialFile} 的三态结果(判别键 `kind`)。`unreadable.reason` 只说**哪里**不对
+ *  (信封字段名 / zod 问题码 / 未知键**个数**),从不回显文件内容 —— 文件里装的就是凭据。 */
+export type WebAdminCredentialFile = {
+    kind: "bare";
+    bearer: string;
+} | {
+    kind: "envelope";
+    envelope: WebAdminCredentialEnvelope;
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+/**
+ * 凭证文件内容 → 三态({@link WebAdminCredentialFile})。判别律见模块头注,本函数是它的唯一实现:
+ *
+ *  1. `trim()`(含 BOM);空 ⇒ `unreadable("empty")`。
+ *  2. 以 `{` 开头 ⇒ 只按 {@link WebAdminCredentialEnvelope} 读:JSON 不成立或 schema 不过 ⇒ `unreadable`
+ *     (**不回落**裸行)。
+ *  3. 否则 ⇒ 首行(第一个 CR 或 LF 之前,再剥一次空白)。它是令牌({@link TokenString} 的律)⇒ `bare`;
+ *     不是 ⇒ `unreadable`(放不进 Authorization 头的行不是 bearer)。多行文件只认首行。
+ *
+ * 纯函数、零 IO;读方负责读文件(以及文件不可读时自己的那条 `unreadable` 臂)。
+ */
+export declare function parseWebAdminCredentialFile(text: string): WebAdminCredentialFile;
+/** 引擎向 web-admin 出示的凭证 —— 闭集;每一份由 {@link WEB_ADMIN_ENV} 里的**一对** env 名声明(值键 | 文件键):
+ *  `access` = 主凭证(`token` / `tokenFile`),`assertion` = 断言令牌(`assertionToken` / `assertionTokenFile`)。 */
+export declare const WEB_ADMIN_CREDENTIALS: readonly ["access", "assertion"];
+export type WebAdminCredential = (typeof WEB_ADMIN_CREDENTIALS)[number];
+/** {@link judgeWebAdminCredentialDeclaration} 的结果:凭证在哪里声明。`env` 形带**值** —— 它就是凭据,只在读方
+ *  自己的凭证模块里流转,不进日志。 */
+export type WebAdminCredentialDeclaration = {
+    from: "env";
+    token: string;
+} | {
+    from: "file";
+    path: string;
+} | {
+    from: "absent";
+};
+/**
+ * 读 `credential` 那一对声明键,判这份凭证在哪里声明 —— 二选一规则的**唯一**实现(每份凭证同一条规则、同一句拒句,只换键名):
+ *
+ *  · 空串 = 未设(`undefined` 同);其余一律算「设了」(不 trim —— 与规则上提前 server 的读法逐字同)。
+ *  · 两个都设 ⇒ **throw**(读方拒启):两个写者写同一个语义面,哪个赢都是猜。拒句点名两个键、不回显值。
+ *  · 只设 `tokenFile` ⇒ `{from:"file", path}`,`path` **原样**:相对路径按 cwd 解析是读方的事(纯契约不碰
+ *    `node:path`,也不知道读方的 cwd)。
+ *  · 只设 `token` ⇒ `{from:"env", token}`;都不设 ⇒ `{from:"absent"}`。
+ *
+ * 只读这一对键,别的 env(另一份凭证的那一对也在内)一概不看。判哪一份由调用方说 —— 没有缺省。
+ */
+export declare function judgeWebAdminCredentialDeclaration(env: Readonly<Record<string, string | undefined>>, credential: WebAdminCredential): WebAdminCredentialDeclaration;

package/dist/{center-credential.js → web-admin-credential.js}

@@ -1,61 +1,61 @@
 /**
- * 中心(config-center 产品)凭证的**文件形契约** —— S-698(design/325 §1)。
+ * web-admin 凭证的**文件形契约** —— S-698(design/325 §1)。
  *
- * 引擎向中心出站时用的凭证由部署声明(见 server `src/center-credential.ts`,单属主);声明成文件时
- * (`SEMA_REGISTRY_TOKEN_FILE`),文件内容有两种**种类**,不是一种语义的两种拼法:
+ * 引擎向 web-admin 出站时用的凭证由部署声明(见 server 的凭证模块,单属主);声明成文件时
+ * (`SEMA_WEB_ADMIN_TOKEN_FILE`),文件内容有两种**种类**,不是一种语义的两种拼法:
  *
- *  · **裸行**(一个静态令牌,种类与今天相同):首行 = 静态 bearer,只收可打印 ASCII({@link TokenString} 的律)。它是用户 JWT 还是 worker
+ *  · **裸行**(一个静态令牌):首行 = 静态 bearer,只收可打印 ASCII({@link TokenString} 的律)。它是用户 JWT 还是 worker
  *    拉取令牌,由读方用 `looksLikeJwt`(`./api/auth-bridge`)自判 —— 本文件不重判种类。
- *  · **信封**(新):一个 JSON 对象,形 = {@link CenterCredentialEnvelope}。今只有一员 `kind:"user-session"`
- *    (人的登录会话:可轮换的访问令牌 + 单次有效的刷新令牌 + 到期时刻 + 签发它的中心根 URL)。worker 拉取
+ *  · **信封**:一个 JSON 对象,形 = {@link WebAdminCredentialEnvelope}。今只有一员 `kind:"user-session"`
+ *    (人的登录会话:可轮换的访问令牌 + 单次有效的刷新令牌 + 到期时刻 + 签发它的 web-admin 根 URL)。worker 拉取
  *    令牌**不进信封**:它不轮换、不属于人,保持裸行。
  *
- * 判别律(一条,{@link parseCenterCredentialFile} 是它的**唯一**实现):内容 `trim()` 后以 `{` 开头 ⇒ 只按
+ * 判别律(一条,{@link parseWebAdminCredentialFile} 是它的**唯一**实现):内容 `trim()` 后以 `{` 开头 ⇒ 只按
  * 信封读,读不成 = `unreadable`(**不回落**成裸行 —— 一个 `{` 开头的裸 token 不存在,回落只会把一段坏 JSON
  * 当 bearer 发出去);否则裸行;空 = `unreadable`。同一份内容只有一种读法(零双读)。
  *
- * 声明面(S-742,本文件尾段):两个声明键名 {@link CENTER_CREDENTIAL_ENV} 与二选一判官
- * {@link judgeCenterCredentialDeclaration} —— 规则此前只活在 server,管理面 / 壳各自手抄键名。
+ * 声明面(本文件尾段):凭证的二选一判官 {@link judgeWebAdminCredentialDeclaration},读 env 名表 {@link WEB_ADMIN_ENV}
+ * (`./web-admin-env`,八键)里的 `token` / `tokenFile` 两键。
  *
  * 纯契约:零 IO(读文件、写文件、续签都是消费方的事),browser-safe,与本包其余部分同一条纯度律。
  */
 import { z } from "zod";
 import { looksLikeJwt } from "./api/auth-bridge.js";
 import { NON_SECRET_URL } from "./types.js";
+import { WEB_ADMIN_ENV } from "./web-admin-env.js";
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
-export const CENTER_CREDENTIAL_ENVELOPE_KIND = "user-session";
-/** RFC 3339 `date-time` 的**剖面**:zod 的 `datetime({offset:true})` 管日历有效性(月日范围、闰年、时分秒范围),
- *  这里再补它放过的三处 —— 秒必备、数字偏移必须是 `±hh:mm`、偏移的时 00–23 / 分 00–59(zod 也收 `10:00Z`、
- *  `+0800` 与 `+99:99`,都不是 RFC 3339,后者 `Date.parse` 读成 NaN)。大写 `T` / `Z`、不收闰秒 `:60`:读方普遍用
+export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
+/** RFC 3339 `date-time` 的**剖面**:zod 的 `z.iso.datetime({offset:true})` 管日历有效性(月日范围、闰年、时分秒范围),
+ *  这里的正则自己判另三处 —— 秒必备、数字偏移必须是 `±hh:mm`、偏移的时 00–23 / 分 00–59(`10:00Z`、`+0800` 与 `+99:99`
+ *  都不是 RFC 3339,后者 `Date.parse` 读成 NaN)。这三处的判据在本正则,不随 zod 哪一版收不收而变。大写 `T` / `Z`、不收闰秒 `:60`:读方普遍用
  *  `Date.parse` 取时刻,这是那组形里它处处读得准的子集。 */
-const RFC3339_DATE_TIME = z
-    .string()
+const RFC3339_DATE_TIME = z.iso
     .datetime({ offset: true })
     .regex(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/, "must be an RFC 3339 date-time: seconds and a Z / ±hh:mm offset (hh 00-23, mm 00-59) are required");
 /** 一枚**令牌串**的形 —— 裸行 bearer、信封里的 `accessToken` / `refreshToken` 共用这**一条**律:可打印 ASCII
  *  (0x20–0x7E),首尾是可见字符(0x21–0x7E)、中间可有空格(共享令牌可以是一句口令 —— 验修轮 N2:今天走得通的
  *  这种令牌不许被本律拒掉)。控制字符、制表、非 ASCII、不可见字符一律不是令牌:判别器把它判 `unreadable`,而不是
  *  发出去 —— 更不会把一段前面粘了不可见字符的信封 JSON 当 bearer 送出门(对抗轮 #7)。刻意比 RFC 6750 `b64token`
- *  宽:部署手写的静态令牌可以带 `!` / `%` / 空格之类。**如实登记**:Latin-1 令牌(HTTP 头的 ByteString 收、中心也
+ *  宽:部署手写的静态令牌可以带 `!` / `%` / 空格之类。**如实登记**:Latin-1 令牌(HTTP 头的 ByteString 收、web-admin 也
  *  逐字比得上)在这里判 `unreadable` —— 非 ASCII 与不可见字符(`\u0085` / `\u00AD`)分不开,取 fail-closed。 */
 const TOKEN_CHARS = /^[\x21-\x7E](?:[\x20-\x7E]*[\x21-\x7E])?$/;
 const TokenString = z.string().regex(TOKEN_CHARS, "must be a token: printable ASCII, no leading / trailing space, no control or non-ASCII characters");
 /**
- * 中心凭证**信封**(`SEMA_REGISTRY_TOKEN_FILE` 指向的文件是一个 JSON 对象时的唯一形)。`.strict()`:
- * 多一个键就不是这份契约(拼错的 `refresh_token` 被静默剥掉,续签就会拿着缺席的刷新令牌去撞中心)。
+ * web-admin 凭证**信封**(`SEMA_WEB_ADMIN_TOKEN_FILE` 指向的文件是一个 JSON 对象时的唯一形)。`.strict()`:
+ * 多一个键就不是这份契约(拼错的 `refresh_token` 被静默剥掉,续签就会拿着缺席的刷新令牌去撞 web-admin)。
  *
- *  · `accessToken` —— 出站 bearer(中心签的用户 JWT,形判 `looksLikeJwt`);读方拿它做身份分箱的方式与裸行
+ *  · `accessToken` —— 出站 bearer(web-admin 签的用户 JWT,形判 `looksLikeJwt`);读方拿它做身份分箱的方式与裸行
  *    `user-jwt` 逐字同。令牌形与裸行同一条律({@link TokenString})。
  *  · `refreshToken` —— 单次有效、严格轮换(`POST /api/v1/auth/token/refresh`,见 `./api/auth`);续签前**重读
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
- *  · `issuer` —— 签发它的中心的**基础 URL**(与读方 `configCenter.url` 同形,可带路径前缀):续签只向同源的中心发,
+ *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
  *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
  *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
  */
-export const CenterCredentialEnvelope = z
+export const WebAdminCredentialEnvelope = z
     .object({
-    kind: z.literal(CENTER_CREDENTIAL_ENVELOPE_KIND),
+    kind: z.literal(WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND),
     accessToken: TokenString.refine(looksLikeJwt, "must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope"),
     refreshToken: TokenString,
     expiresAt: RFC3339_DATE_TIME,
@@ -63,13 +63,13 @@ export const CenterCredentialEnvelope = z
 })
     .strict();
 /** 信封自己的字段名(schema 的键 —— reason 里只许出现这几个名字,不许出现用户写的键)。 */
-const ENVELOPE_FIELDS = new Set(Object.keys(CenterCredentialEnvelope.shape));
+const ENVELOPE_FIELDS = new Set(Object.keys(WebAdminCredentialEnvelope.shape));
 /** 一次 schema 失败 → 不含文件内容的一句话。 */
 function envelopeRejection(error) {
     const fields = new Set(); // 一个字段挂两道判据(datetime + 剖面正则)时只说一次
     let unknownKeys = 0;
     for (const issue of error.issues) {
-        if (issue.code === z.ZodIssueCode.unrecognized_keys) {
+        if (issue.code === "unrecognized_keys") {
             unknownKeys += issue.keys.length;
             continue;
         }
@@ -78,20 +78,20 @@ function envelopeRejection(error) {
         fields.add(`${field} (${issue.code})`);
     }
     const parts = [...(fields.size > 0 ? [`fields rejected: ${[...fields].join(", ")}`] : []), ...(unknownKeys > 0 ? [`unknown keys: ${unknownKeys}`] : [])];
-    return `envelope does not match CenterCredentialEnvelope — ${parts.join("; ")}`;
+    return `envelope does not match WebAdminCredentialEnvelope — ${parts.join("; ")}`;
 }
 /**
- * 凭证文件内容 → 三态({@link CenterCredentialFile})。判别律见模块头注,本函数是它的唯一实现:
+ * 凭证文件内容 → 三态({@link WebAdminCredentialFile})。判别律见模块头注,本函数是它的唯一实现:
  *
  *  1. `trim()`(含 BOM);空 ⇒ `unreadable("empty")`。
- *  2. 以 `{` 开头 ⇒ 只按 {@link CenterCredentialEnvelope} 读:JSON 不成立或 schema 不过 ⇒ `unreadable`
+ *  2. 以 `{` 开头 ⇒ 只按 {@link WebAdminCredentialEnvelope} 读:JSON 不成立或 schema 不过 ⇒ `unreadable`
  *     (**不回落**裸行)。
  *  3. 否则 ⇒ 首行(第一个 CR 或 LF 之前,再剥一次空白)。它是令牌({@link TokenString} 的律)⇒ `bare`;
  *     不是 ⇒ `unreadable`(放不进 Authorization 头的行不是 bearer)。多行文件只认首行。
  *
  * 纯函数、零 IO;读方负责读文件(以及文件不可读时自己的那条 `unreadable` 臂)。
  */
-export function parseCenterCredentialFile(text) {
+export function parseWebAdminCredentialFile(text) {
     const trimmed = text.trim();
     if (trimmed === "")
         return { kind: "unreadable", reason: "empty" };
@@ -104,7 +104,7 @@ export function parseCenterCredentialFile(text) {
             // JSON.parse 的报错会引用出错位置附近的原文 —— 不转述它。
             return { kind: "unreadable", reason: "envelope is not valid JSON" };
         }
-        const parsed = CenterCredentialEnvelope.safeParse(json);
+        const parsed = WebAdminCredentialEnvelope.safeParse(json);
         return parsed.success ? { kind: "envelope", envelope: parsed.data } : { kind: "unreadable", reason: envelopeRejection(parsed.error) };
     }
     const firstLine = trimmed.split(/[\r\n]/, 1)[0].trim(); // 行尾 = 第一个 CR 或 LF(CRLF / LF / 孤 CR 同判)
@@ -112,18 +112,17 @@ export function parseCenterCredentialFile(text) {
         return { kind: "unreadable", reason: "bare line is not a token — printable ASCII only (no control or non-ASCII characters)" };
     return { kind: "bare", bearer: firstLine };
 }
-// ── S-742:凭证的两个声明键 + 二选一判官 ─────────────────────────────────────────────────────────────
+// ── 凭证二选一判官(每份凭证读 {@link WEB_ADMIN_ENV} 里的一对键:值键 | 文件键)────────────────────────────
+/** 引擎向 web-admin 出示的凭证 —— 闭集;每一份由 {@link WEB_ADMIN_ENV} 里的**一对** env 名声明(值键 | 文件键):
+ *  `access` = 主凭证(`token` / `tokenFile`),`assertion` = 断言令牌(`assertionToken` / `assertionTokenFile`)。 */
+export const WEB_ADMIN_CREDENTIALS = ["access", "assertion"];
+/** 每份凭证的那一对键名。键是闭集的每一员(`Record` 穷举:闭集加一员而这里不给一对 = 编译错)。 */
+const CREDENTIAL_ENV_PAIRS = {
+    access: { value: WEB_ADMIN_ENV.token, file: WEB_ADMIN_ENV.tokenFile },
+    assertion: { value: WEB_ADMIN_ENV.assertionToken, file: WEB_ADMIN_ENV.assertionTokenFile },
+};
 /**
- * 中心凭证的两个**声明键名**(部署 env)。一处定义、三方 import(server 读、管理面给 worker 渲染、壳给本机
- * 引擎写)—— 键名是 wire 面,手抄的键名会静默漂。
- *
- *  · `token`(`SEMA_REGISTRY_TOKEN`)—— 值即凭证(部署注入;读方在进程生命期内读一次)。
- *  · `tokenFile`(`SEMA_REGISTRY_TOKEN_FILE`)—— 凭证文件的路径,读方**每次取值都读文件**(轮换 / 换账号只需
- *    改写文件,不重启);文件内容的读法见 {@link parseCenterCredentialFile}。
- */
-export const CENTER_CREDENTIAL_ENV = { token: "SEMA_REGISTRY_TOKEN", tokenFile: "SEMA_REGISTRY_TOKEN_FILE" };
-/**
- * 读两个声明键,判凭证在哪里声明 —— 二选一规则的**唯一**实现:
+ * 读 `credential` 那一对声明键,判这份凭证在哪里声明 —— 二选一规则的**唯一**实现(每份凭证同一条规则、同一句拒句,只换键名):
  *
  *  · 空串 = 未设(`undefined` 同);其余一律算「设了」(不 trim —— 与规则上提前 server 的读法逐字同)。
  *  · 两个都设 ⇒ **throw**(读方拒启):两个写者写同一个语义面,哪个赢都是猜。拒句点名两个键、不回显值。
@@ -131,10 +130,14 @@ export const CENTER_CREDENTIAL_ENV = { token: "SEMA_REGISTRY_TOKEN", tokenFile:
  *    `node:path`,也不知道读方的 cwd)。
  *  · 只设 `token` ⇒ `{from:"env", token}`;都不设 ⇒ `{from:"absent"}`。
  *
- * 只读这两个键,别的 env 一概不看。
+ * 只读这一对键,别的 env(另一份凭证的那一对也在内)一概不看。判哪一份由调用方说 —— 没有缺省。
  */
-export function judgeCenterCredentialDeclaration(env) {
-    const { token: tokenKey, tokenFile: fileKey } = CENTER_CREDENTIAL_ENV;
+export function judgeWebAdminCredentialDeclaration(env, credential) {
+    const pair = CREDENTIAL_ENV_PAIRS[credential];
+    // 类型面上不可达;JS 调用方漏传 / 传错第二参时响亮拒(不猜是哪一份凭证)。
+    if (pair === undefined)
+        throw new Error(`unknown web-admin credential ${JSON.stringify(credential)} — one of ${WEB_ADMIN_CREDENTIALS.join(" / ")}`);
+    const { value: tokenKey, file: fileKey } = pair;
     const token = env[tokenKey] ?? "";
     const file = env[fileKey] ?? "";
     if (token !== "" && file !== "") {

package/dist/web-admin-env.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 引擎连 web-admin 读的**全部 env 名** —— 一处定义(叶模块,零 import:凭证判官、墓碑表与 worker 保留名表都引它);server 读、web-admin 给 worker 渲染、壳给本机引擎写,三方 import。
+ * 键名是部署面,手抄的键名会静默漂(此前只有 `token` / `tokenFile` 有契约位,其余六个各仓手抄)。读方只读这张表里的名字,
+ * 旧名一概不读(零双读):旧名是 `RETIRED_ENVS` 里的墓碑,在场即拒启。
+ *
+ *  · `url` —— web-admin 的根 URL(在场 = 配置走远端:引擎向它拉 effective)。
+ *  · `token` —— 值即凭证(部署注入;读方在进程生命期内读一次)。与 `tokenFile` 二选一(判官
+ *    `judgeWebAdminCredentialDeclaration(env, "access")`)。
+ *  · `tokenFile` —— 凭证文件的路径,读方**每次取值都读文件**(轮换 / 换账号只需改写文件,不重启);文件内容的读法见
+ *    `parseWebAdminCredentialFile`。
+ *  · `assertionToken` / `assertionTokenFile` —— web-admin 断言令牌(`wat_` 前缀)的值 / 文件路径:与 `token` / `tokenFile` 同一条
+ *    二选一规则、同一只判官(`judgeWebAdminCredentialDeclaration(env, "assertion")`),两个都设 ⇒ 拒;文件同样每次取值都读。
+ *  · `worker` —— 本引擎在 web-admin 上的 worker 名(按 worker 取 effective、实例登记、公钥上报)。
+ *  · `liveUrl` —— fleet 活性路由组(`FLEET_LIVE_PATHS`:心跳 / 注销 / 续租)另走一条不看就绪的入口时的根 URL;缺席 = 用 `url`。
+ *  · `webUrl` —— web-admin 人用的界面根 URL(引擎原样自报到 `/health`,壳按它拼深链;缺席即缺席)。
+ *  · `dryRun` —— 只拉取,不应用。
+ *  · `adminToken` —— 引擎以管理身份写 web-admin 时用的令牌(起服上报执行公钥)。
+ *
+ * 渲染器给每台 worker 写的三键(`url` / `worker` / `token`)同时是 worker env 的**保留名**(`RESERVED_WORKER_ENV`):运维在 worker 规格的
+ * `env` 里写它们,会与渲染器写的值打架。
+ */
+export declare const WEB_ADMIN_ENV: {
+    readonly url: "SEMA_WEB_ADMIN_URL";
+    readonly token: "SEMA_WEB_ADMIN_TOKEN";
+    readonly tokenFile: "SEMA_WEB_ADMIN_TOKEN_FILE";
+    readonly worker: "SEMA_WEB_ADMIN_WORKER";
+    readonly liveUrl: "SEMA_WEB_ADMIN_LIVE_URL";
+    readonly webUrl: "SEMA_WEB_ADMIN_WEB_URL";
+    readonly dryRun: "SEMA_WEB_ADMIN_DRY_RUN";
+    readonly adminToken: "SEMA_WEB_ADMIN_ADMIN_TOKEN";
+    readonly assertionToken: "SEMA_WEB_ADMIN_ASSERTION_TOKEN";
+    readonly assertionTokenFile: "SEMA_WEB_ADMIN_ASSERTION_TOKEN_FILE";
+};

package/dist/web-admin-env.js

@@ -0,0 +1,33 @@
+/**
+ * 引擎连 web-admin 读的**全部 env 名** —— 一处定义(叶模块,零 import:凭证判官、墓碑表与 worker 保留名表都引它);server 读、web-admin 给 worker 渲染、壳给本机引擎写,三方 import。
+ * 键名是部署面,手抄的键名会静默漂(此前只有 `token` / `tokenFile` 有契约位,其余六个各仓手抄)。读方只读这张表里的名字,
+ * 旧名一概不读(零双读):旧名是 `RETIRED_ENVS` 里的墓碑,在场即拒启。
+ *
+ *  · `url` —— web-admin 的根 URL(在场 = 配置走远端:引擎向它拉 effective)。
+ *  · `token` —— 值即凭证(部署注入;读方在进程生命期内读一次)。与 `tokenFile` 二选一(判官
+ *    `judgeWebAdminCredentialDeclaration(env, "access")`)。
+ *  · `tokenFile` —— 凭证文件的路径,读方**每次取值都读文件**(轮换 / 换账号只需改写文件,不重启);文件内容的读法见
+ *    `parseWebAdminCredentialFile`。
+ *  · `assertionToken` / `assertionTokenFile` —— web-admin 断言令牌(`wat_` 前缀)的值 / 文件路径:与 `token` / `tokenFile` 同一条
+ *    二选一规则、同一只判官(`judgeWebAdminCredentialDeclaration(env, "assertion")`),两个都设 ⇒ 拒;文件同样每次取值都读。
+ *  · `worker` —— 本引擎在 web-admin 上的 worker 名(按 worker 取 effective、实例登记、公钥上报)。
+ *  · `liveUrl` —— fleet 活性路由组(`FLEET_LIVE_PATHS`:心跳 / 注销 / 续租)另走一条不看就绪的入口时的根 URL;缺席 = 用 `url`。
+ *  · `webUrl` —— web-admin 人用的界面根 URL(引擎原样自报到 `/health`,壳按它拼深链;缺席即缺席)。
+ *  · `dryRun` —— 只拉取,不应用。
+ *  · `adminToken` —— 引擎以管理身份写 web-admin 时用的令牌(起服上报执行公钥)。
+ *
+ * 渲染器给每台 worker 写的三键(`url` / `worker` / `token`)同时是 worker env 的**保留名**(`RESERVED_WORKER_ENV`):运维在 worker 规格的
+ * `env` 里写它们,会与渲染器写的值打架。
+ */
+export const WEB_ADMIN_ENV = {
+    url: "SEMA_WEB_ADMIN_URL",
+    token: "SEMA_WEB_ADMIN_TOKEN",
+    tokenFile: "SEMA_WEB_ADMIN_TOKEN_FILE",
+    worker: "SEMA_WEB_ADMIN_WORKER",
+    liveUrl: "SEMA_WEB_ADMIN_LIVE_URL",
+    webUrl: "SEMA_WEB_ADMIN_WEB_URL",
+    dryRun: "SEMA_WEB_ADMIN_DRY_RUN",
+    adminToken: "SEMA_WEB_ADMIN_ADMIN_TOKEN",
+    assertionToken: "SEMA_WEB_ADMIN_ASSERTION_TOKEN",
+    assertionTokenFile: "SEMA_WEB_ADMIN_ASSERTION_TOKEN_FILE",
+};

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

@@ -0,0 +1,16 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):workers 域**一行**的终判与它的拒句拼装 —— 只此一处。两个调用方各判一种形:读口 `readWorkersRows`
+ * 判**存储形**的行(读不进 ⇒ 扣下),一次性迁移 SS-M4 判**改写后**的行(读不进 ⇒ 不写回半成品,收据 `refused`)。
+ *
+ * 判据只有读侧那一只 schema:只含这一行的 workers 域读不读得进(`WorkersConfig` —— 与 `parseDomain("workers")` 同一只,不另抄任何规则)。
+ * 拒句 = `<主语> is not a valid WorkerSpec — <至多三条 issue 的「坐标: 句子」>( (+n more))`,主语点名判的是哪一形(闭集两词);句中坐标已过出门那一道。
+ * 交回的 `field`(第一条 issue 的路径,相对该行)与整句**还没**过出门:出门归各自的铸点(读口的 `held`、迁移的收据),各过一次。
+ */
+import { type ConfigPath } from "./config-fns.js";
+/** 判的是哪一形的行(闭集):`stored` = 店里存着的那一行;`migrated` = 一次性迁移改写出来、还没写回的那一行。 */
+export type WorkerRowForm = "stored" | "migrated";
+/** 一行的终判:读得进 ⇒ `undefined`;读不进 ⇒ 第一条 issue 的路径(相对该行)+ 拒句(见文件头)。 */
+export declare function workerRowVerdict(row: Readonly<Record<string, unknown>>, form: WorkerRowForm): {
+    readonly field: ConfigPath;
+    readonly reason: string;
+} | undefined;

package/dist/worker-row-verdict.js

@@ -0,0 +1,31 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):workers 域**一行**的终判与它的拒句拼装 —— 只此一处。两个调用方各判一种形:读口 `readWorkersRows`
+ * 判**存储形**的行(读不进 ⇒ 扣下),一次性迁移 SS-M4 判**改写后**的行(读不进 ⇒ 不写回半成品,收据 `refused`)。
+ *
+ * 判据只有读侧那一只 schema:只含这一行的 workers 域读不读得进(`WorkersConfig` —— 与 `parseDomain("workers")` 同一只,不另抄任何规则)。
+ * 拒句 = `<主语> is not a valid WorkerSpec — <至多三条 issue 的「坐标: 句子」>( (+n more))`,主语点名判的是哪一形(闭集两词);句中坐标已过出门那一道。
+ * 交回的 `field`(第一条 issue 的路径,相对该行)与整句**还没**过出门:出门归各自的铸点(读口的 `held`、迁移的收据),各过一次。
+ */
+import { formatConfigPath, outgoingPath } from "./config-fns.js";
+import { issuePath } from "./issue-path.js";
+import { WorkersConfig } from "./types.js";
+/** 每一形的拒句主语 —— 穷举映射型:加一形不补这里即编译红。 */
+const SUBJECT = {
+    stored: "the stored worker",
+    migrated: "after migration the worker",
+};
+/** 一只单行域里的 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] });
+    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 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.d.ts

@@ -0,0 +1,34 @@
+/**
+ * workers 域的**逐行终判**(11.0.0 从 7.0.0 的一次性迁移里拆出 —— 那只函数同时装着「6.x 形改写」与「逐行终判」两件事;改写搬进
+ * 一次性迁移 SS-M4,终判留在这里,是 workers 域的**永久读语义**,不是迁移)。纯函数、无 I/O、不改入参。
+ *
+ * ## 为什么要逐行
+ * workers 是 gate 域(读即抛):整域 `parseDomain("workers")` 遇一行坏就整域抛,舰队清单整份读不出 —— 一只坏 worker 拖黑整个舰队。
+ * web-admin 的 workers 读口先过本函数:每一只**认得出名字**的 worker 单独过读侧自己的判据(只含这一行的 workers 域读不读得进,
+ * `WorkersConfig` —— 与 `parseDomain("workers")` 同一只 schema,不另抄任何规则;判据与拒句拼装在包内私有的 `./worker-row-verdict`,
+ * 一次性迁移 SS-M4 判改写后的行调同一只);读不进的那一行扣下(`held`,带原文与拒因),
+ * 其余照常进 `doc`。整域读侧仍是最后围栏,只剩两类归它:认不出名字的条目(不是对象 / 没有字符串名字 —— 原样留在 `doc`)与跨行规则
+ * (名字 / 路由前缀唯一 —— 两行单独都读得进、合起来才不行,这里不替运维挑留哪一行)。
+ *
+ * 被扣下的行**不进** `doc`,但随 `held[].original` 逐字带回:`doc` ∪ `held[].original` 覆盖输入的全部 worker。读口不写回 —— 原文留在盘上,
+ * web-admin 在列表里标红点名 `field` / `reason`。拒因只点名字段、不回显值。
+ */
+import { type ConfigPath } from "./config-fns.js";
+/** 被扣下的一行:`field` 相对该 worker 条目(读侧 schema issue 的路径),`reason` 只点名字段、不回显值,`original` = 输入里那一行逐字(同一个值)。 */
+export interface HeldWorkerRow {
+    readonly name: string;
+    readonly index: number;
+    readonly field: ConfigPath;
+    readonly reason: string;
+    readonly original: unknown;
+}
+/** {@link readWorkersRows} 的结果:`doc` = 扣下坏行后的文档(什么都没扣 ⇒ 输入的同一引用),`held` = 被扣下的行。 */
+export interface WorkersRowsRead {
+    readonly doc: unknown;
+    readonly held: readonly HeldWorkerRow[];
+}
+/**
+ * 逐行读一份 workers 域**原始**文档(`{ workers: [...] }`)。不是这个形 ⇒ 原样返回、零扣下(判形是 `parseDomain` 的事)。
+ * 规则见文件头。
+ */
+export declare function readWorkersRows(raw: unknown): WorkersRowsRead;

package/dist/workers-rows.js

@@ -0,0 +1,42 @@
+/**
+ * workers 域的**逐行终判**(11.0.0 从 7.0.0 的一次性迁移里拆出 —— 那只函数同时装着「6.x 形改写」与「逐行终判」两件事;改写搬进
+ * 一次性迁移 SS-M4,终判留在这里,是 workers 域的**永久读语义**,不是迁移)。纯函数、无 I/O、不改入参。
+ *
+ * ## 为什么要逐行
+ * workers 是 gate 域(读即抛):整域 `parseDomain("workers")` 遇一行坏就整域抛,舰队清单整份读不出 —— 一只坏 worker 拖黑整个舰队。
+ * web-admin 的 workers 读口先过本函数:每一只**认得出名字**的 worker 单独过读侧自己的判据(只含这一行的 workers 域读不读得进,
+ * `WorkersConfig` —— 与 `parseDomain("workers")` 同一只 schema,不另抄任何规则;判据与拒句拼装在包内私有的 `./worker-row-verdict`,
+ * 一次性迁移 SS-M4 判改写后的行调同一只);读不进的那一行扣下(`held`,带原文与拒因),
+ * 其余照常进 `doc`。整域读侧仍是最后围栏,只剩两类归它:认不出名字的条目(不是对象 / 没有字符串名字 —— 原样留在 `doc`)与跨行规则
+ * (名字 / 路由前缀唯一 —— 两行单独都读得进、合起来才不行,这里不替运维挑留哪一行)。
+ *
+ * 被扣下的行**不进** `doc`,但随 `held[].original` 逐字带回:`doc` ∪ `held[].original` 覆盖输入的全部 worker。读口不写回 —— 原文留在盘上,
+ * web-admin 在列表里标红点名 `field` / `reason`。拒因只点名字段、不回显值。
+ */
+import { outgoingPath, redactSecrets } from "./config-fns.js";
+import { workerRowVerdict } from "./worker-row-verdict.js";
+const isRec = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/**
+ * 逐行读一份 workers 域**原始**文档(`{ workers: [...] }`)。不是这个形 ⇒ 原样返回、零扣下(判形是 `parseDomain` 的事)。
+ * 规则见文件头。
+ */
+export function readWorkersRows(raw) {
+    if (!isRec(raw) || !Array.isArray(raw.workers))
+        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;
+        }
+        const v = workerRowVerdict(row, "stored");
+        // 坐标与拒因都走出门那一道:issue 路径里的 Record 键是用户写的(例:一个不合法的 env 键名可能就是粘错位置的凭据)。
+        if (v === undefined)
+            kept.push(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 };
+}

package/dist/zod-unwrap.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 包内私有(不进主桶):zod 包装层的**一只**读法 —— 逐条容错(`salvageEntries`,config-fns)与一次性迁移(SS-M7 找 URL 座位)共用。
+ */
+import { z } from "zod";
+/** 展开 zod 的包装层,拿到里面真正的那个 schema。包装不改变「条目能不能单独解析」这件事。
+ *
+ *  包装层闭集:`.optional()` / `.nullable()` / `.default()` / `.prefault()` / `.catch()`(都是 `.unwrap()` 一层),以及
+ *  **一侧是变换**的管道 —— `.transform(f)` 是「schema → 变换」、`z.preprocess(f, schema)` 是「变换 → schema」,两者都取
+ *  不是变换的那一侧。两侧都是 schema 的管道(`a.pipe(b)`)不是包装:到此为止(按它本身的形判,认不出就不抢救)。
+ *  `.refine()` / `.superRefine()` 在 zod 4 里不是包装层(判据挂在同一只 schema 上),无须展开。 */
+export declare function unwrapSchema(schema: z.ZodType): z.ZodType;

package/dist/zod-unwrap.js

@@ -0,0 +1,25 @@
+/**
+ * 包内私有(不进主桶):zod 包装层的**一只**读法 —— 逐条容错(`salvageEntries`,config-fns)与一次性迁移(SS-M7 找 URL 座位)共用。
+ */
+import { z } from "zod";
+/** 展开 zod 的包装层,拿到里面真正的那个 schema。包装不改变「条目能不能单独解析」这件事。
+ *
+ *  包装层闭集:`.optional()` / `.nullable()` / `.default()` / `.prefault()` / `.catch()`(都是 `.unwrap()` 一层),以及
+ *  **一侧是变换**的管道 —— `.transform(f)` 是「schema → 变换」、`z.preprocess(f, schema)` 是「变换 → schema」,两者都取
+ *  不是变换的那一侧。两侧都是 schema 的管道(`a.pipe(b)`)不是包装:到此为止(按它本身的形判,认不出就不抢救)。
+ *  `.refine()` / `.superRefine()` 在 zod 4 里不是包装层(判据挂在同一只 schema 上),无须展开。 */
+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
+            return cur;
+    }
+    return cur;
+}