@sema-agent/settings-schema 14.4.0 → 14.6.0

package/dist/types.js

@@ -21,6 +21,7 @@ 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 { 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
@@ -193,6 +194,10 @@ function createNonSecretUrl(reachedByMigration) {
  *  echoed; a fragment's also names its migration, {@link nonSecretUrlIssue}); `params` carries the sentence (`template` / `operands`,
  *  no operands) and `flaw`, the rule word.
  *
+ *  Scope of the secret test: it judges the VALUE's shape (a value that looks like a secret, whatever the parameter is called) — the sibling
+ *  name-shaped judge `findUrlCredential` (`./url-credential`) asks the other question (a parameter whose NAME is on the credential-name table,
+ *  whatever the value looks like). Neither contains the other: `?key=abc` passes here and is a hit there; `?x=sk-live-…` is the reverse.
+ *
  *  This is the seat of every URL in a STORED document the one-time migration rewrites: the domain documents (models `baseUrl`, mcp `url`,
  *  `sessionMirror.engineUrl`, workers `gitApiBaseUrl`) and `config.d/remote-exec.json` (k8s `apiUrl`, `s3Snapshot.endpoint`). A URL
  *  that is not stored data — the web-admin credential envelope's `issuer`, a wire input — uses {@link NON_SECRET_URL_NO_MIGRATION}.
@@ -212,62 +217,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 (!Object.hasOwn(desc, "value"))
+                        return true; // accessor element — do NOT invoke
+                    stack.push([desc.value, depth + 1]);
+                }
+                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
+                if (!Object.hasOwn(desc, "value"))
+                    return true; // accessor (get/set) — do NOT invoke
+                if (containsSecretToken(k))
+                    return true; // secret-shaped KEY (tokenized). R8
                 stack.push([desc.value, depth + 1]);
             }
-            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`
@@ -514,8 +523,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;
         }

package/dist/url-credential.d.ts

@@ -0,0 +1,41 @@
+/** 拒因词(闭集;判序 = 本数组序;词只在这一处写 —— {@link UrlCredentialReason} 与 {@link UrlCredential} 的成员都从它派生)。 */
+export declare const URL_CREDENTIAL_REASONS: readonly ["url_userinfo", "url_credential_param"];
+export type UrlCredentialReason = (typeof URL_CREDENTIAL_REASONS)[number];
+/**
+ * 凭据参数名表(闭集,23 词,全部是小写 ASCII `[a-z][a-z0-9_-]*`)。query / fragment 里名字整名(ASCII 大小写不敏感)在这张表上的参数就是凭据。
+ * 加一个词 = 表里加一格(minor);判官与 {@link isCredentialParamName} 现算,不手抄第二份。
+ */
+export declare const CREDENTIAL_PARAM_NAMES: readonly ["api_key", "apikey", "api-key", "key", "token", "access_token", "refresh_token", "id_token", "auth", "authorization", "proxy-authorization", "password", "passwd", "pwd", "secret", "client_secret", "private_key", "signature", "sig", "x-amz-signature", "x-amz-security-token", "x-amz-credential", "sas"];
+export type CredentialParamName = (typeof CREDENTIAL_PARAM_NAMES)[number];
+/**
+ * 「这个**已解码**的参数名是不是凭据名」。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字):整名在 {@link CREDENTIAL_PARAM_NAMES} 里(ASCII 大小写不敏感)才算。
+ */
+export declare function isCredentialParamName(decodedName: string): boolean;
+/** 每个拒因词带的细节(键集必须覆盖 {@link URL_CREDENTIAL_REASONS} 的每个词:数组里加一个词而这里没跟 ⇒ 下面的映射型编译红,{@link urlCredentialRule} 的穷举 switch 也红)。 */
+interface UrlCredentialDetail {
+    readonly url_userinfo: unknown;
+    readonly url_credential_param: {
+        readonly at: "query" | "fragment";
+        readonly name: CredentialParamName;
+    };
+}
+/** 一处命中:`url_userinfo`,或 `url_credential_param` + 它在哪一段、表里的哪个词(小写;不是调用方的原字节)。成员从 {@link URL_CREDENTIAL_REASONS} 派生。 */
+export type UrlCredential = {
+    readonly [R in UrlCredentialReason]: {
+        readonly reason: R;
+    } & UrlCredentialDetail[R];
+}[UrlCredentialReason];
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带 **userinfo**(判官的第一问,也是 {@link findUrlCredential} 的第一步)。只问这一件的座位 —— 运行时本就拒带 userinfo 的 URL、
+ * 而凭据名参数不由它拒的载体 —— 问这一只,不在座位里另写一份 userinfo 谓词。纯函数。
+ */
+export declare function findUrlUserinfo(raw: string): Extract<UrlCredential, {
+    readonly reason: "url_userinfo";
+}> | undefined;
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带凭据。首个命中(userinfo → query → fragment);没有(含不透明 / 解析不了的值)⇒ `undefined`。纯函数。
+ */
+export declare function findUrlCredential(raw: string): UrlCredential | undefined;
+/** 一处命中的规则句(穷举;新拒因词不补 = 编译红)。只说规则与表词,不含值。 */
+export declare function urlCredentialRule(c: UrlCredential): string;
+export {};

package/dist/url-credential.js

@@ -0,0 +1,95 @@
+/**
+ * **「这个 URL 的 userinfo 或 query / fragment 里,有没有名字在凭据名表上的参数」的名形判官**(14.5.0;lift 自 server `src/url-credential.ts`,规则、拒因词闭集与规则句逐字搬)。纯函数,零 import(除同包的 `./url-shape`),浏览器安全。
+ *
+ * ## 与 `NON_SECRET_URL`(`./types`)的关系:两个问题,互补,不是一个包含另一个
+ * 本判官按**名**判 —— 参数叫什么(名字整名在 {@link CREDENTIAL_PARAM_NAMES} 上就是凭据,不论值长什么样);`NON_SECRET_URL` 的 `urlQueryFragmentHasSecret` 按**值形**判密钥 —— 值长得像密钥
+ * (不论参数叫什么)。所以 `?key=abc` 本判官命中而 `NON_SECRET_URL` 放行(值不像密钥),`?x=sk-live-…` 反之;userinfo 两边都判。存量域文档位(`mcp` 的 `transport.url` 等)读 `NON_SECRET_URL`,
+ * 请求面等座位读本判官。把两个问题合成一只定义是另一件事,这里不做。
+ *
+ * ## 规则(一条):URL 里的凭据 = 日志脱敏器已经在用的那一个定义
+ * 一个 URL 里凭据住三个位置:
+ *  · **userinfo**(`scheme://<这一段>@host`,只有用户名也算)—— 判由本包的 URL 形判官 {@link httpUrlFlaws}(`["userinfo"]`),本模块不留第二份谓词;
+ *  · **query 参数**、**fragment 参数**(同一段文法)里名字整名在 {@link CREDENTIAL_PARAM_NAMES} 上的那一个 —— 名字按收方的读法读:WHATWG `URLSearchParams` 解一次码,
+ *    ASCII 大小写不敏感(不做 Unicode 折叠),整名在表里才算(`db_password` / `tokens` / `keyword` 是另一个名字)。
+ * 答首个命中(判序 = 上面的序),拒因闭集两词 {@link URL_CREDENTIAL_REASONS};**值从不进答案**,参数名只回显表里的那个词(小写)。
+ * 不透明形 / 解析不了的值没有可读的部件 ⇒ 答「没有」—— 这一形收不收是**座位**自己的律,不在本判官里。
+ *
+ * ## 判官只判「有没有」;座位决定怎么用
+ * 本模块不决定哪个载体拒、哪个载体放:同一个键在不同载体上的律可以不同(例:新提交的请求面拒,续跑重放存量体的腿不拒 —— 拒会砖死升级前停驻的任务;
+ * 部署 env 与续跑重放只因 userinfo 拒,凭据名参数只在新提交门拒)。所以判官**不**接进任何一份读已落盘 / 重放字节的 schema 或读器 —— 那会把载体律焊死成
+ * 读器律;座位在自己的新提交门调 {@link findUrlCredential} / {@link findUrlUserinfo},拒句 / 拒体的形(HTTP 码、字段坐标、出路句)是座位自己的铸点。
+ *
+ * ## 名表的来源
+ * {@link CREDENTIAL_PARAM_NAMES} 是 server 日志脱敏器名表(锚强度表的键)的 23 词。脱敏器另有一列「自由文本里这个词的锚强度」,那一列是脱敏器的事,不在这里;
+ * 词表本身在这里成为契约面 —— 脱敏器与本判官读同一张词表(同一个定义)靠消费方把它的表键钉在本导出上(例:`Record<CredentialParamName, …>` 的穷尽映射 ⇒ 加 / 删词不同步即编译红)。
+ */
+import { httpUrlFlaws, httpUrlRule, isHierarchicalUrl } from "./url-shape.js";
+/** 拒因词(闭集;判序 = 本数组序;词只在这一处写 —— {@link UrlCredentialReason} 与 {@link UrlCredential} 的成员都从它派生)。 */
+export const URL_CREDENTIAL_REASONS = Object.freeze(["url_userinfo", "url_credential_param"]);
+/**
+ * 凭据参数名表(闭集,23 词,全部是小写 ASCII `[a-z][a-z0-9_-]*`)。query / fragment 里名字整名(ASCII 大小写不敏感)在这张表上的参数就是凭据。
+ * 加一个词 = 表里加一格(minor);判官与 {@link isCredentialParamName} 现算,不手抄第二份。
+ */
+export const CREDENTIAL_PARAM_NAMES = Object.freeze([
+    "api_key", "apikey", "api-key", "key",
+    "token", "access_token", "refresh_token", "id_token",
+    "auth", "authorization", "proxy-authorization",
+    "password", "passwd", "pwd",
+    "secret", "client_secret", "private_key",
+    "signature", "sig",
+    "x-amz-signature", "x-amz-security-token", "x-amz-credential",
+    "sas",
+]);
+/** 名表的查找形(`Set`,不拿普通对象当查表:`constructor` / `__proto__` 会读到原型链上的东西)。 */
+const CREDENTIAL_PARAM_NAME_SET = new Set(CREDENTIAL_PARAM_NAMES);
+/** ASCII 大小写折叠(只折 `A-Z`,不做 Unicode 折叠:`ＴＯＫＥＮ` 不是 `token`)。 */
+const asciiLower = (s) => s.replace(/[A-Z]/g, (c) => c.toLowerCase());
+/**
+ * 「这个**已解码**的参数名是不是凭据名」。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字):整名在 {@link CREDENTIAL_PARAM_NAMES} 里(ASCII 大小写不敏感)才算。
+ */
+export function isCredentialParamName(decodedName) {
+    return CREDENTIAL_PARAM_NAME_SET.has(asciiLower(decodedName));
+}
+/** 一段参数串(`?` / `#` 之后)里第一个凭据名参数的表词(小写);没有 ⇒ `undefined`。 */
+function credentialParamIn(params) {
+    for (const name of new URLSearchParams(params).keys()) {
+        const word = asciiLower(name);
+        if (CREDENTIAL_PARAM_NAME_SET.has(word))
+            return word;
+    }
+    return undefined;
+}
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带 **userinfo**(判官的第一问,也是 {@link findUrlCredential} 的第一步)。只问这一件的座位 —— 运行时本就拒带 userinfo 的 URL、
+ * 而凭据名参数不由它拒的载体 —— 问这一只,不在座位里另写一份 userinfo 谓词。纯函数。
+ */
+export function findUrlUserinfo(raw) {
+    return isHierarchicalUrl(raw) && httpUrlFlaws(raw, ["userinfo"]).includes("userinfo") ? { reason: "url_userinfo" } : undefined;
+}
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带凭据。首个命中(userinfo → query → fragment);没有(含不透明 / 解析不了的值)⇒ `undefined`。纯函数。
+ */
+export function findUrlCredential(raw) {
+    if (!isHierarchicalUrl(raw))
+        return undefined;
+    const userinfo = findUrlUserinfo(raw);
+    if (userinfo !== undefined)
+        return userinfo;
+    const u = new URL(raw);
+    const inQuery = credentialParamIn(u.search);
+    if (inQuery !== undefined)
+        return { reason: "url_credential_param", at: "query", name: inQuery };
+    const inFragment = credentialParamIn(u.hash.slice(1));
+    if (inFragment !== undefined)
+        return { reason: "url_credential_param", at: "fragment", name: inFragment };
+    return undefined;
+}
+/** 一处命中的规则句(穷举;新拒因词不补 = 编译红)。只说规则与表词,不含值。 */
+export function urlCredentialRule(c) {
+    switch (c.reason) {
+        case "url_userinfo":
+            return httpUrlRule("userinfo"); // 与形判官诸座同一句(不写第二句)
+        case "url_credential_param":
+            return `must not carry a credential parameter (the ${c.at} names "${c.name}", a name the service's log redactor treats as a credential)`;
+    }
+}

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,8 @@ 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`)。 */
+/** 以 `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,8 @@ 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`)。 */
+/** 以 `http://` / `https://` 起头(大小写不敏感)—— 一道**语法前缀**守卫,不是形判官:不解析、不看 host / 部件,所以 `https://` 这样的裸 scheme 它也收(见头注「第二个答案」)。
+ *  唯一读者是请求面 MCP 传输读器(`readRequestMcpTransport`);S-2106 收口时它退成那个读器座位的「照字面写全」规则,与形判官合取。 */
 export function startsWithHttpScheme(raw) {
     return /^https?:\/\//i.test(raw);
 }

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,27 +7,28 @@
  * 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 { 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 域**原始**文档(`{ workers: [...] }`)。不是这个形 ⇒ 原样返回、零扣下(判形是 `parseDomain` 的事)。
  * 规则见文件头。
  */
 export function readWorkersRows(raw) {
-    if (!isRec(raw) || !Array.isArray(raw.workers))
+    if (!isPlainJsonObject(raw) || !isJsonArray(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") {
+        if (!isPlainJsonObject(row) || typeof row.name !== "string") {
             kept.push(row); // 认不出名字:整域读侧判
             return;
         }

package/docs/API-SURFACE.md

@@ -4,9 +4,9 @@
 > 每次全量重算并逐名比对 —— 加 / 删 / 改形一个导出而不重生成本档 ⇒ 红。导出面的每次变动因此以本档的 diff 出现在评审里。
 > 形:`value` = 运行期拿得到的值;`type` = 只在类型层;`value+type` = 同名的值与类型(zod schema 与它推出的类型)。
 
-子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1339 个(同名在多条子路径上各计一次)。
+子路径 24 条(资产出口 `./package.json` / `./fleet-paths.json` 不是模块,不列),导出名合计 1365 个(同名在多条子路径上各计一次)。
 
-## `.`(662)
+## `.`(680)
 
 - `ABSOLUTE_HOST_PATH_MAX` — value
 - `ACCESS_TOKEN_TTL_SECONDS` — value
@@ -36,6 +36,7 @@
 - `COMMAND_DECISIONS` — value
 - `CONFIG_CHANGE_SOURCES` — value
 - `CONTROL_AND_BIDI_CHARS` — value
+- `CREDENTIAL_PARAM_NAMES` — value
 - `CROSS_SESSION_INBOUND_UNSET` — value
 - `CROSS_SESSION_INBOUND_VALUES` — value
 - `CancelSource` — value+type
@@ -55,6 +56,7 @@
 - `ConfigChangeHookInput` — value
 - `ConfigPath` — type
 - `ConfigReader` — type
+- `CredentialParamName` — type
 - `CrossSessionInboundSetting` — value
 - `CrossSessionInboundSettingValue` — type
 - `CrossSessionInboundValue` — type
@@ -393,6 +395,7 @@
 - `SESSION_MIRROR_ENGINE_URL` — value
 - `SETTINGS_SOURCES` — value
 - `SETTINGS_SOURCE_CONTRACT` — value
+- `SETTINGS_UNITS` — value
 - `SHA256_DIGEST_RE` — value
 - `STALE_HEARTBEAT_MULTIPLIER` — value
 - `STALE_SESSION_RECORD_MS` — value
@@ -440,6 +443,7 @@
 - `SettingSource` — value+type
 - `SettingsSource` — type
 - `SettingsSourceContract` — type
+- `SettingsUnitName` — type
 - `SetupHookInput` — value
 - `Sha256Digest` — value
 - `SiblingResolver` — type
@@ -463,6 +467,7 @@
 - `TCP_PORT` — value
 - `TENANT_SEPARATION_BASES` — value
 - `TENANT_SEPARATION_WORDS` — value
+- `TIGHTEN_VERDICTS` — value
 - `TOKEN_SCOPE_REFUSALS` — value
 - `TOOL_WIRE_NAME_MAX_CHARS` — value
 - `TaskCompletedHookInput` — value
@@ -473,16 +478,20 @@
 - `TierBindings` — value+type
 - `TierGroup` — value+type
 - `TightenRule` — value+type
+- `TightenVerdict` — type
 - `TokenGrantResponse` — value+type
 - `TokenQuota` — value+type
 - `TokenRefreshRequest` — value+type
 - `TokenScopeRefusal` — type
 - `UI_LANGUAGE_SETTING` — value
 - `UI_LANGUAGE_VALUES` — value
+- `URL_CREDENTIAL_REASONS` — value
 - `USER_ROLES` — value
 - `UiLanguageSetting` — value
 - `UiLanguageSettings` — value+type
 - `UiLanguageValue` — type
+- `UrlCredential` — type
+- `UrlCredentialReason` — type
 - `UsageEntry` — value+type
 - `UsageReport` — value+type
 - `User` — type
@@ -548,6 +557,8 @@
 - `emptyEffective` — value
 - `extraBodyUnsafe` — value
 - `findSkillContent` — value
+- `findUrlCredential` — value
+- `findUrlUserinfo` — value
 - `fnv1a64` — value
 - `formatConfigPath` — value
 - `hasControlOrBidi` — value
@@ -563,6 +574,7 @@
 - `isAtLeast` — value
 - `isCanonicalGeneration` — value
 - `isContentOriginWord` — value
+- `isCredentialParamName` — value
 - `isDisclosableIdentity` — value
 - `isDomainName` — value
 - `isHierarchicalUrl` — value
@@ -593,6 +605,7 @@
 - `mcpServerPolicyVerdict` — value
 - `memberAdmission` — value
 - `memberMinTrust` — value
+- `memberTighten` — value
 - `membersOf` — value
 - `mintScopedToken` — value
 - `narrowAtMention` — value
@@ -623,6 +636,7 @@
 - `readScopedTokenBinding` — value
 - `readServingLeaseRequest` — value
 - `readServingLeaseResponse` — value
+- `readSettingsUnit` — value
 - `readTokenScope` — value
 - `readUiLanguage` — value
 - `readWorkersRows` — value
@@ -637,6 +651,7 @@
 - `resolveCatalogDefaultModel` — value
 - `resolveEffectiveForWorker` — value
 - `resolveMemberAdmission` — value
+- `resolveMemberTighten` — value
 - `resolveTokenScope` — value
 - `retiredDomainSentence` — value
 - `retiredEnvRefusal` — value
@@ -659,10 +674,13 @@
 - `statusRowsToPrune` — value
 - `stopAttributionText` — value
 - `stripControlAndBidi` — value
+- `tightenVerdict` — value
 - `toSkillsManifest` — value
 - `toVerifiedIdentity` — value
 - `trustRank` — value
+- `unitTighten` — value
 - `urlAllowPatternMatches` — value
+- `urlCredentialRule` — value
 - `urlDenyPatternMatches` — value
 - `urlQueryFragmentHasSecret` — value
 - `verifyScopedToken` — value
@@ -1038,7 +1056,7 @@
 - `REMOTE_EXEC_DOCUMENT` — value
 - `RemoteExecSpec` — value+type
 
-## `./safety-merge-spec`(19)
+## `./safety-merge-spec`(24)
 
 - `FailMode` — value+type
 - `MIN_TRUST_WORDS` — value
@@ -1052,25 +1070,32 @@
 - `SafetyMergeCategory` — type
 - `SafetyMergeMember` — type
 - `SpecEnforcement` — value+type
+- `TIGHTEN_VERDICTS` — value
 - `TightenRule` — value+type
+- `TightenVerdict` — type
 - `isAtLeast` — value
 - `memberAdmission` — value
 - `memberMinTrust` — value
+- `memberTighten` — value
 - `membersOf` — value
 - `resolveMemberAdmission` — value
+- `resolveMemberTighten` — value
+- `tightenVerdict` — value
 - `trustRank` — value
 
-## `./node`(36)
+## `./node`(39)
 
 - `ConfigBundle` — type
 - `ConfigDirectoryDocument` — type
 - `ConfigDirectoryIo` — type
 - `ConfigDirectoryMigration` — type
 - `ConfigDirectoryRefusal` — type
+- `ConfigDocumentsMigration` — type
 - `DomainReadError` — type
 - `FileConfigStore` — value+type
 - `LocalConfig` — type
 - `MigrateConfigDirectoryOptions` — type
+- `MigrateConfigDocumentsOptions` — type
 - `NON_DOMAIN_CONFIG_FILES` — value
 - `NON_PORTABLE_DOMAIN_REASONS` — value
 - `PORTABLE_DOMAINS` — value
@@ -1088,6 +1113,7 @@
 - `loadRemoteExec` — value
 - `loadSchedulerStore` — value
 - `migrateConfigDirectory` — value
+- `migrateConfigDocuments` — value
 - `mutateSchedulerStore` — value
 - `nodeConfigDirectoryIo` — value
 - `readBundle` — value

package/docs/CONSUMER-INTEGRATION.md

@@ -234,6 +234,8 @@ server 直接拒启,不是静默降级。上一代 `SEMA_REGISTRY_*` 八名(`URL
 - **本地 `config.d` 的一次性迁移(引擎起服)**:调 `@sema-agent/settings-schema/node` 的 `migrateConfigDirectory(dir, { documents, io: nodeConfigDirectoryIo })`,`documents` 填你本地读腿会读的域名集
   (覆盖面外的文件不读不判不写不删;要迁 retired 的 `runtime` 域就得把 `governance` 与 `limits` 一并放进来 —— 迁出的旧值要写那两份,缺了 `runtime` 按 `partial` 拒迁、一字不写);按返回的 `kind` 穷举处置(`applied` / `noop` / `pending` / `refused` / `no-documents` / `unreadable`)。**别按同语义自写**读目录、迁、整域终判、原子写、删退役域文件那一串 ——
   命令行 `migrate` 与这只函数同一份实现;写盘用的就是本包那一只原子写器(契约文档新建 0o644、已有的沿用原模式、符号链接保留)。
+  手里已有存量文档原文、不经目录的消费方(例:命令行壳按层读 `settings` 里的 models 域,要的是「引擎起服那一次迁移之后这份文档整域读不读得进」)调同一个内核的同步口 `migrateConfigDocuments(docs, { documents })`(14.5.0,`./node`):
+  同一个闭集的无 io 形(`refused` ⇒ 引擎同样不写回、整域落缺省;**反向不成立** —— 引擎对整个目录一判,别的文档被拒也会让整目录不写,单层单域的 `noop` / `migrated` 不保证引擎那一次放行;`docs` 是壳的写手要的迁移后那一份)。一层一次调用;**别自己把 `migrateStoredDocuments` 与 `parseDomain` 按这个顺序再组装一遍**。
 - **会话网页链接**:要给用户一个 web-admin 里的会话链接,调 `webAdminSessionUrl(webBaseUrl, { worker, sessionId })`(`webBaseUrl` 取引擎 `/health` 自报的人用界面根 URL,
   `worker` 取引擎向 web-admin 登记用的 worker 名),得到 `<webBaseUrl>/chat?agent=<worker>&session=<sessionId>`;**别按地址形手拼** —— 路由属于 web-admin,模板与读回的
   `parseWebAdminSessionUrl(link)` 同在本包,路径与参数名只此一份。两位必填:只带 `session` 的链接会落到页面自己挑的 worker 上、可能找不到会话。