@sema-agent/settings-schema 17.2.0 → 18.0.0

package/dist/types.js

@@ -22,21 +22,24 @@ import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody dep
 import { DispatchPolicy, FLEET_GENERATION_ENV, FLEET_SCOPE_ENV } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
 import { isLoopbackAuthHost } from "./loopback.js";
 import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js"; // THE "is this a JSON object" predicate + the total array test
-import { appendOwn, guardedSafeParse, isAccessorDescriptor } from "./own-key-read.js"; // the one spelling of "is this descriptor an accessor" (its own fields only) + the one guarded zod verdict
+import { appendOwn, guardedSafeParse, isAccessorDescriptor, ownEntriesOf } 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
 import { PREVIOUS_WEB_ADMIN_ENV } from "./previous-web-admin-env.js"; // the previous generation's names of those three (the renderer still writes them for engines that read them)
 import { retiredEnvRefusal } from "./retired-envs.js"; // the worker env write gate asks the retired-env tombstone table too (one table, one refusal sentence)
 import { Sha256Digest } from "./sha256.js"; // the one `sha256:<hex>` digest form
-import { EXECUTION_LANES, EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS, isBlankCoordinate, retiredLaneWordRefusal } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
+import { EXECUTION_LANES, EXECUTION_LANE_WORDS, LANE_SET_RULE, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS, isBlankCoordinate, laneSetFlaws, retiredLaneWordRefusal } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
 import { LANE_ENV_OWNER, envKeyMigration, laneEnvSeat, laneRowOf } from "./execution-lane-index.js"; // package-private indexes derived from that table (none of them is in the barrel)
 import { migrationSignpost, retiredFormSentence, retiredKey } from "./retired-form.js"; // 11.0.0: the ONE retired-form sentence + key tombstone (package-private)
 import { retiredRoleWordsRefusal } from "./retired-role-words.js"; // 12.0.0: the retired role-word tombstone (package-private; SS-M8)
 import { buildQuotedIssue, fixed } from "./quoted-issue.js"; // THE minting point of custom issues (package-private)
+import { unwrapSchema } from "./zod-unwrap.js"; // 18.0.0: ATOMIC_SALVAGE registers the schema the salvage walker reaches (wrappers peeled with the walker's own reader)
+import { RESERVED_MEMBER_NAMES, isReservedMemberName } from "./reserved-member-name.js"; // 18.0.0: the one reserved-member-name table (the record reader and the center-refs resolver ask the same predicate)
 import { AbsoluteHostPath } from "./host-path.js"; // the one host-path shape judge (a task's cwd and a project's folder / file entries)
 import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (package-private)
 import { DEVICE_RELAY_RULE, deviceRelayFlaws } from "./device-relay.js"; // 16.0.0: the value grammar of the device lane's DEVICE_RELAY_URL (ws(s) URL or the literal none)
+import { TOOL_WIRE_NAME_MAX_CHARS, isUsableWireName } from "./wire-name.js"; // 18.0.0: the one "usable wire name" judge (the a2a peer name; the request-plane MCP / A2A readers ask the same function)
 // COARSE, best-effort literal-secret SHAPE detector (NOT exhaustive — the real boundary is the env-NAME schema
 // on structured fields). Rejected in free-form value fields (worker `env`, model `extraBody`), URL components,
 // AND as an env-NAME value (an AWS key id is a valid env-NAME charset yet is a secret VALUE, not a NAME). Case-
@@ -1476,7 +1479,11 @@ export const ExecutionPolicy = z.object({
     /** Which execution lanes are allowed. OPEN value domain — z.string(), NEVER an enum: adding a lane
      *  must not be a BREAKING schema change (promised to the service). The closed set of lanes a worker can
      *  declare is `EXECUTION_LANE_WORDS` (`execution-lanes.ts`, 7.0.0) — read it there, not from a copy in this
-     *  comment. Unknown strings are consumer-defined. */
+     *  comment. Unknown strings are consumer-defined.
+     *  18.0.0 —— the declarable word for "no execution environment" is `none`; the engine's older internal name for that state, `in-process`,
+     *  was never a declarable lane. While engines that answer with the old name and engines that answer with `none` both read a policy, the policy
+     *  DATA lists both strings (`["in-process", "none", …]` — legal content of this open list, not a second reading in code); once every engine
+     *  reading it answers `none`, delete `"in-process"` from the data. */
     allowedLanes: z.array(z.string().min(1)).prefault(["host"]),
     /** Org 默认会话镜像目标(0.10.1,附B 两层)。ABSENT = INERT(web-admin 未管镜像,壳解析序里本腿为空)。
      *  读损档随域(DOMAIN_READ_FALLBACK.execution="throw" 已覆盖:损坏绝不静默退默认放权)。 */
@@ -1796,6 +1803,8 @@ const WorkerSecretRefs = z.object({
  *  · **加** `DB_BACKEND` / `MEMORY_ENGINE` / `MEMORY_ENGINE_BACKEND` —— `runtime.store` 产出它们。
  *  · **删** `MEMORY_BACKEND`(引擎从不读的死名,渲染器不再产出)与 `TIDB_*` 族(引擎的墓碑名,见之拒启;结构字段不再产出它们)。
  *    MYSQL_* / PG_* 两族归 `runtime.store.db` + `secretRefs.dbPasswordEnv`。
+ * 18.0.0 删 `REQUIRE_EXECUTION_LANE`:每个部署都点名车道之后它恒真,不再是旋钮 —— 引擎不读、渲染器不写,名字进墓碑表 `RETIRED_ENVS`(去向 `REMOTE_EXEC`);
+ * 逃生口里写它 ⇒ 墓碑句(下一段的第二个问题)。迁移 SS-M4 识别它的键集(`LANE_WORD_KEYS`)不动。
  *
  * `env` / `secretEnv` 的写闸问**两张表**,各答一个问题,互相独立:
  *  · 本表答「规格作者可不可以自己设这个名」—— 不可以:它归某个结构字段,或归渲染器 / 编排器写,或与渲染器 / 编排器写的名互斥(拒句指路到那个写位);
@@ -1857,7 +1866,6 @@ const RESERVED_ENV_FIELD = Object.freeze({
     [WEB_ADMIN_ENV.tokenFile]: WEB_ADMIN_OPERATOR_FILE_SEAT, [PREVIOUS_WEB_ADMIN_ENV.tokenFile]: WEB_ADMIN_OPERATOR_FILE_SEAT,
     [WEB_ADMIN_ENV.assertionToken]: WEB_ADMIN_ASSERTION_SEAT.token,
     [WEB_ADMIN_ENV.assertionTokenFile]: WEB_ADMIN_OPERATOR_FILE_SEAT,
-    REQUIRE_EXECUTION_LANE: "runtime.execution.lanes (the renderer emits REQUIRE_EXECUTION_LANE=true for every declared lane set)",
     ...Object.fromEntries([...LANE_ENV_OWNER].map(([name, owner]) => [name, laneEnvSeat(name, owner)])),
 });
 /** 结构化 WorkerSpec 字段已经产出的 env 名 —— 通用 `env` / `secretEnv` 逃生口**不许**设它们(用专属字段)。由
@@ -1896,11 +1904,117 @@ const nonSecretLiteral = (minLength) => z
 const COORDINATE_VALUE_GRAMMAR = new Map([
     ["DEVICE_RELAY_URL", { flaws: deviceRelayFlaws, rule: DEVICE_RELAY_RULE }],
 ]);
-/** 车道集缺席时的那一句(块在而缺 `lanes`,与 enabled 的 worker 根本没有车道块,同一句)。 */
-const LANES_REQUIRED = `runtime.execution.lanes must be a non-empty list — the worker's ordered execution lane set (the first one is the default) of ${EXECUTION_LANE_WORDS.join(" | ")}, each at most once. There is no "no hands" lane — disable the worker instead`;
+/** 车道集缺席 / 为空时的那一句(块在而缺 `lanes`、`lanes` 是空表,与 enabled 的 worker 根本没有车道块,同一句)。规则句取判官的 {@link LANE_SET_RULE}。 */
+const LANES_REQUIRED = `runtime.execution.lanes ${LANE_SET_RULE}`;
 /**
- * `runtime.execution` —— 这台 worker 的执行车道集(16.0.0;渲染:车道表 `lanes` + `REQUIRE_EXECUTION_LANE=true` + coords / secretRefs 逐键)。
- *  - `lanes`:**有序、去重、非空**的车道表({@link EXECUTION_LANE_WORDS} 的词),首项 = 缺省。没有「无手」词。
+ * 写闸对车道表的那一读:判官 {@link laneSetFlaws} 的每条拒因一条 issue(穷举 switch:判官加一种拒因而这里不补 ⇒ 编译红)。`path` 相对 `lanes`。
+ * issue 的机读码与此前三只判据(枚举 / `.min(1)` / 去重)各自给的码逐一相同:词形坏(空白 / 不认识 / 退役)= `invalid_value`(`values` = 车道词表;退役词的句子是墓碑句),
+ * 空表 = `too_small`(句子 = 车道集必填那一句),重复 = `custom`;独占车道与别的项同集(18.0.0)= `custom`,落在整张表上。句子都经铸点 `buildQuotedIssue`(写进表里的值是洞)。
+ * 不是字符串的项也是「不是车道词」(`unknown`,同一个码,句子不回显它的值)。
+ * 可续性:表里有不是车道词的项 ⇒ 不可续(`continue: false`)—— 列表连「车道」都不是,后面按车道表行判的(坐标归属 / 必需坐标 / 租户 / 单副本 / 店)都不跑,
+ * 与此前枚举拒的读法同;空表 / 重复 / 不独占 ⇒ 可续(每一项都是车道词)。判官交回全部拒因,这里每条都出(一张表里坏词与重复同在 ⇒ 两条都报)。
+ */
+function addLaneSetIssue(ctx, lanes, flaw) {
+    const values = [...EXECUTION_LANE_WORDS];
+    switch (flaw.kind) {
+        case "empty_set":
+            return ctx.addIssue({ code: "too_small", origin: "array", minimum: 1, inclusive: true, input: lanes, ...buildQuotedIssue `${fixed(LANES_REQUIRED)}` });
+        case "blank_entry":
+            return ctx.addIssue({ code: "invalid_value", values, input: lanes[flaw.at], path: [flaw.at], continue: false, ...buildQuotedIssue `an entry of runtime.execution.lanes is empty or whitespace-only — runtime.execution.lanes ${fixed(LANE_SET_RULE)}` });
+        case "unknown": {
+            const { word } = flaw;
+            return ctx.addIssue({
+                code: "invalid_value",
+                values,
+                input: word,
+                path: [flaw.at],
+                continue: false,
+                ...(typeof word === "string"
+                    ? buildQuotedIssue `"${word}" is not an execution lane — runtime.execution.lanes ${fixed(LANE_SET_RULE)}`
+                    : buildQuotedIssue `an entry of runtime.execution.lanes is not a string — runtime.execution.lanes ${fixed(LANE_SET_RULE)}`),
+            });
+        }
+        case "retired": {
+            const refusal = retiredLaneWordRefusal(flaw.word);
+            if (refusal === undefined)
+                throw new Error("addLaneSetIssue: a retired-lane flaw names a word the tombstone has no row for (package invariant broken)", { cause: flaw });
+            // the tombstone sentence itself: its way out is given at the source, once
+            return ctx.addIssue({ code: "invalid_value", values, input: flaw.word, path: [flaw.at], continue: false, ...buildQuotedIssue `${fixed(refusal)}` });
+        }
+        case "duplicate":
+            return ctx.addIssue({ code: "custom", path: [flaw.at], ...buildQuotedIssue `lane "${flaw.lane}" is declared twice in runtime.execution.lanes — each lane appears once (the first one is the default)` });
+        case "not_alone":
+            return ctx.addIssue({
+                code: "custom",
+                ...buildQuotedIssue `runtime.execution.lanes declares ${fixed(JSON.stringify(flaw.lane))} (no execution environment for the agent's tools) together with other entries — it stands alone: declare lanes: [${fixed(JSON.stringify(flaw.lane))}], or remove it`,
+            });
+        default: {
+            const unhandled = flaw;
+            throw new Error("addLaneSetIssue: unhandled lane-set flaw", { cause: unhandled });
+        }
+    }
+}
+/**
+ * 凭据引用集合(名 → 宿主 env-NAME)的**唯一铸法**:先按**自有属性名**判保留成员名(`isReservedMemberName`,一张表,记录读器与中心引用解析口问同一个谓词;
+ * 经读内核 `ownEntriesOf` 的严归类读名:每个自有串键都读到名字,不调 getter),一条就使集合判不过、record 不再判;再交给 `record`。
+ * zod 的 record 读键前先跳过 `__proto__`(不判它的值、输出里也没有它),只靠 record 判会把「带着一条被剥掉的引用」读成「没有那条引用」,条目带着其余引用活下来。
+ * 只判朴素对象(形状问座位 `isPlainJsonObject`;别的形由 `record` 自己拒,拒句不变);成员名读不出(隐藏键 / 访问器 / 陷阱抛)⇒ 同样判坏,句子是内核那一句(fail-closed:守卫看不清名字就不担保)。
+ * 每一只成员都由它铸,所以成员复用到哪个座位,这道判据就跟到哪个座位;{@link ATOMIC_SALVAGE} 登记的是剥掉包装之后的那只 `record`(抢救走查按它判身份)。
+ */
+function credentialRefs(record) {
+    return z.preprocess((input, ctx) => {
+        if (!isPlainJsonObject(input))
+            return input;
+        const members = ownEntriesOf(input);
+        if (!members.ok) {
+            ctx.addIssue({ code: "custom", input, ...buildQuotedIssue `${fixed(members.sentence)}` });
+            return input;
+        }
+        for (const [name] of members.value)
+            if (isReservedMemberName(name))
+                ctx.addIssue({ code: "custom", input, ...buildQuotedIssue `a credential reference is named "${fixed(name)}" — a reserved member name (${fixed(RESERVED_MEMBER_NAMES.join(" | "))}) never names a reference; rename it` });
+        return input;
+    }, record);
+}
+/** 车道块的密钥引用(服务变量名 → 宿主 env-NAME)—— 一只具名 schema:它是凭据引用集合,在 {@link ATOMIC_SALVAGE} 里按身份登记。 */
+const LaneSecretRefs = credentialRefs(z.record(ENV_NAME, ENV_NAME));
+/** worker 的密钥 env 透传(服务变量名 → 宿主 env-NAME)—— 一只具名 schema:它是凭据引用集合,在 {@link ATOMIC_SALVAGE} 里按身份登记。 */
+const WorkerSecretEnv = credentialRefs(z.record(ENV_NAME, ENV_NAME).superRefine((rec, ctx) => {
+    retiredEnvIssue(rec, ctx);
+    for (const k of Object.keys(rec))
+        if (RESERVED_WORKER_ENV.has(k))
+            ctx.addIssue({ code: "custom", ...reservedKeyIssue("secretEnv", k) });
+}));
+/** 一项是不是可声明的车道词(只给下面的变换收窄类型用:判官放行之后每一项都是)。 */
+const isDeclarableLane = (v) => EXECUTION_LANE_WORDS.some((w) => w === v);
+/** 列表的一次快照(长度只读一次,空洞读成 `undefined`):判官判的与变换收窄的是同一份项,不对调用方的数组读第二遍。不是列表 ⇒ 原样(下面的判据拒)。 */
+const laneListSnapshot = (v) => (isJsonArray(v) ? Array.from({ length: v.length }, (_, i) => v[i]) : v);
+/**
+ * `runtime.execution.lanes`:写闸只判「是一个列表」(缺 ⇒ 车道集必填那一句;不是列表 ⇒ `invalid_type`),每一项是不是车道词与整张表的合法性一起交给判官
+ * {@link laneSetFlaws}(唯一一处)。不写成 `z.array(元素)`:元素 schema 先判 ⇒ 不是字符串的项得到另一个码、同表其余的项不判;元素写成什么都收的 schema,
+ * 它又成了「本包不判形的解析透明键」—— 它不是,判官判它。有不可续的拒因时 zod 不跑变换;变换只把已判过的项收窄成车道词。
+ */
+const DeclaredLanes = z.preprocess(laneListSnapshot, z
+    .unknown()
+    .superRefine((value, ctx) => {
+    if (!isJsonArray(value)) {
+        ctx.addIssue({
+            code: "invalid_type",
+            expected: "array",
+            input: value,
+            continue: false,
+            ...(value === undefined ? buildQuotedIssue `${fixed(LANES_REQUIRED)}` : buildQuotedIssue `runtime.execution.lanes is not a list — runtime.execution.lanes ${fixed(LANE_SET_RULE)}`),
+        });
+        return;
+    }
+    for (const flaw of laneSetFlaws(value))
+        addLaneSetIssue(ctx, value, flaw);
+})
+    .transform((value) => (isJsonArray(value) ? value.filter(isDeclarableLane) : [])));
+/**
+ * `runtime.execution` —— 这台 worker 的执行车道集(16.0.0;渲染:车道表 `lanes` → `REMOTE_EXEC` + coords / secretRefs 逐键;18.0.0 起不再渲总开关)。
+ *  - `lanes`:**有序、去重、非空**的车道表({@link EXECUTION_LANE_WORDS} 的词),首项 = 缺省;合不合法只问判官 {@link laneSetFlaws}。
+ *    不给智能体的工具提供执行环境的 worker 写 `lanes: ["none"]`(18.0.0;独成一集)。
  *  - `coords`:声明的车道的**非密坐标**(服务变量名 → 字面值),每个键归表里的某一条车道(车道表 `requiredEnv ∪ optionalEnv`);每条声明的车道的必需键都在场且不是空白
  *    (空串或只含空白按缺 —— 唯一判官 `isBlankCoordinate`);有文法的键({@link COORDINATE_VALUE_GRAMMAR})值还要合它的文法。可选键的空串照收(例:`K8S_RUNTIME_CLASS=""` 在引擎里是「不用 Kata」)。
  *  - `secretRefs`:声明的车道的**密钥**(服务变量名 → 宿主 env-NAME),每个键归表里的某一条车道,每条声明的车道的必需键在场。
@@ -1910,21 +2024,13 @@ const LANES_REQUIRED = `runtime.execution.lanes must be a non-empty list — the
 const ExecutionBlock = z
     .object({
     lane: retiredKey("runtime.execution.lane", { retiredIn: "16.0.0", now: "runtime.execution.lanes (an ordered lane set; the first one is the default)", migration: "SS-M12" }),
-    lanes: z
-        .array(z.enum(EXECUTION_LANE_WORDS, { error: (iss) => retiredLaneWordRefusal(iss.input) }), { error: (iss) => (iss.input === undefined ? LANES_REQUIRED : undefined) }) // a retired lane word gets its way out
-        .min(1, { error: LANES_REQUIRED }),
+    lanes: DeclaredLanes,
     coords: z.record(ENV_NAME, nonSecretLiteral(0)).prefault({}),
-    secretRefs: z.record(ENV_NAME, ENV_NAME).prefault({}),
+    secretRefs: LaneSecretRefs.prefault({}),
 })
     .superRefine((x, ctx) => {
-    // 去重:每条车道至多一次,重复的那一格(第二次出现)一条
-    const declared = [];
-    x.lanes.forEach((lane, i) => {
-        if (declared.includes(lane))
-            ctx.addIssue({ code: "custom", path: ["lanes", i], ...buildQuotedIssue `lane "${lane}" is declared twice in runtime.execution.lanes — each lane appears once (the first one is the default)` });
-        else
-            declared.push(lane);
-    });
+    // 车道表本身合不合法只问判官(`lanes` 那一格,见 DeclaredLanes);这里按去重后的车道读表行(重复是可续的拒因,所以这里可能见到重复项)。
+    const declared = x.lanes.filter((lane, i) => x.lanes.indexOf(lane) === i);
     const rows = declared.map(laneRowOf);
     const issue = (slot, key, q) => ctx.addIssue({ code: "custom", path: [slot, key], ...q });
     const owned = (secret) => rows.flatMap((row) => (secret ? [...row.requiredSecretEnv, ...row.optionalSecretEnv] : [...row.requiredEnv, ...row.optionalEnv]));
@@ -2131,15 +2237,7 @@ const WorkerSpecObject = z.object({
      * 故无法粘贴真值）。给 app 专属令牌用（如 `MY_APP_TOKEN` → 某 env-名）。在 reconciler 里于 `env` 之后解析，
      * 故密钥永不被 `env` 同名键遮蔽。`RESERVED_WORKER_ENV` 里的键被拒（那些结构化 secret 走 `secretRefs`）;墓碑表 `RETIRED_ENVS` 里的旧名被拒。
      */
-    secretEnv: z
-        .record(ENV_NAME, ENV_NAME)
-        .superRefine((rec, ctx) => {
-        retiredEnvIssue(rec, ctx);
-        for (const k of Object.keys(rec))
-            if (RESERVED_WORKER_ENV.has(k))
-                ctx.addIssue({ code: "custom", ...reservedKeyIssue("secretEnv", k) });
-    })
-        .optional(),
+    secretEnv: WorkerSecretEnv.optional(),
     /** Opaque recreate trigger (hash-INCLUDED): bump it to force the reconciler to recreate the worker — e.g. to
      *  re-project a secret VALUE that changed (a secret write doesn't alter the spec, so without this the running
      *  pod keeps the old value). Set by POST /api/config/workers/<name>/rotate. */
@@ -2180,7 +2278,7 @@ function workerSpecIssues(w, ctx) {
     const { execution, store, requirePrincipal } = w.runtime;
     // G1:enabled 的 worker 必须声明车道集与店(停用的不渲染,可缺)。
     if (w.enabled && execution === undefined) {
-        issue(["runtime", "execution", "lanes"], buildQuotedIssue `an enabled worker must declare its execution lanes (without them it would boot with no hands and still report tasks completed) — ${fixed(LANES_REQUIRED)}`);
+        issue(["runtime", "execution", "lanes"], buildQuotedIssue `an enabled worker must declare its execution lanes (the lane set is the deployment's own statement — nothing reads a missing one as some lane) — ${fixed(LANES_REQUIRED)}`);
     }
     if (w.enabled && store === undefined) {
         issue(["runtime", "store", "backend"], buildQuotedIssue `an enabled worker must declare its store — runtime.store.backend: ${fixed(STORE_BACKENDS.join(" | "))}`);
@@ -2459,7 +2557,7 @@ export const SkillsManifestSchema = z.object({
 // env-NAME references (`envRefs`/`headerRefs`: target-key → an ENV_NAME in the SERVICE's env). The service's
 // `resolveSpec` reads the real values from its own environment — this DB never holds a credential. Like
 // skills, MCP is applied at boot/reconcile (not hot) and writing is gated to `publisher` + the publish gate.
-const McpEnvRefs = z.record(ENV_NAME, ENV_NAME); // target ENV key → ENV_NAME holding its value (both env-name-shaped)
+const McpEnvRefs = credentialRefs(z.record(ENV_NAME, ENV_NAME)); // target ENV key → ENV_NAME holding its value (both env-name-shaped)
 // An HTTP header NAME: an RFC 7230 token that ALSO must not be a secret literal. A secret-SHAPED header name
 // (a headerRefs key `sk-live-…`, or principalHeader `ghp_…`) is stored + shipped verbatim on /effective — the
 // SAME invariant-① gap as worker.env / model.extraBody / mcp stdio command+args (credentials belong on the
@@ -2471,7 +2569,20 @@ const HTTP_HEADER_NAME = z
     .regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, "must be an HTTP header NAME")
     .refine((s) => !containsSecretToken(s), buildQuotedIssue `HTTP header name must not contain a secret literal — credentials go in the env-NAME value, never the header name`);
 // Header NAME → ENV_NAME holding its value. Header names are tokens (RFC 7230) — not env-name-shaped.
-const McpHeaderRefs = z.record(HTTP_HEADER_NAME, ENV_NAME);
+const McpHeaderRefs = credentialRefs(z.record(HTTP_HEADER_NAME, ENV_NAME));
+/**
+ * 18.0.0 —— **凭据引用集合不可部分抢救**(按 schema 身份的集合)。成员是「名 → 宿主 env-NAME」的凭据引用 Record:mcp 的 `envRefs` / `headerRefs`
+ * (a2a 对端的 `headerRefs` 复用后者,因此同在)、车道块的 `secretRefs` 与 worker 的 `secretEnv`。逐条抢救(`salvageEntries`)走到成员**不下钻**、把它当一个值判:
+ * 集合里任一键 / 值坏形 ⇒ 它所属的那一条条目整条 `entry-dropped`,兄弟条目保留。理由:丢掉一条坏引用不是「更窄」,而是让条目带着**一半凭据**活下来 ——
+ * 拨一个远端服务 / 智能体时错误的失败方向(读方对「任一引用的 env 缺席」本来就整条跳过,同一个方向)。
+ * 既有读数只变一处:直接对 `WorkersConfig` 调 `salvageEntries` 时,`secretEnv` 带坏引用的 worker 由「只丢那一条引用、worker 存活」变「整条丢」
+ * (各域读数不变:workers 域不逐条抢救;mcp 的两只住在传输判别联合里,走查不进联合;车道块住在不是集合的 `runtime` 对象里)
+ * —— 由 17.2.0 包的真读数逐行对拍钉住(`test/atomic-salvage-18.0.0.test.ts`,改了读数的那一行逐行登记)。别的集合字段(allowTools / scenarios / allowSkills …)照旧逐条抢救:丢坏元素只会更窄。
+ * 成员读键按自有属性名判:`__proto__` / `constructor` / `prototype` 任一在场 ⇒ 集合坏 ⇒ 条目整条丢(见 `credentialRefs`;zod 的 record 读键前跳过 `__proto__`、不判它的值)。
+ * 新的凭据引用集合必须复用这几只 schema 或由 `credentialRefs` 铸出并登记进这里(按身份判,换一只「形一样」的新 schema 不算成员)。
+ * 登记的是剥掉包装之后的那只 `record`(与抢救走查同一只读法 `unwrapSchema`)。
+ */
+export const ATOMIC_SALVAGE = new Set([McpEnvRefs, McpHeaderRefs, LaneSecretRefs, WorkerSecretEnv].map(unwrapSchema));
 export const McpTransport = z.discriminatedUnion("kind", [
     z.object({
         kind: z.literal("stdio"),
@@ -2609,6 +2720,41 @@ export const McpConfig = z
         seen.add(s.name);
     });
 });
+// ── Domain: a2a (常驻出站 A2A 对端名册 —— 18.0.0) ─────────────────────────────────────────────────────────────
+// 一个 A2A 对端 = 一个 https 端点(单一传输,没有判别);形是 mcp http 条目的近亲,判官一律复用:URL = NON_SECRET_URL(存量文档座位,与 mcp `transport.url`
+// 同座;名形判官 `findUrlCredential` 是新提交门的事,不接进读已落盘字节的 schema),`headerRefs` = mcp 的头名 → env-NAME 引用集合(凭据引用,
+// 在 ATOMIC_SALVAGE 里:坏一项 ⇒ 整个对端丢),`principalHeader` = 头名判官,`name` = 线上名判官(对端名是线上工具名 `a2a__<名>__…` 的身份片)。
+// 秘密边界同 mcp:中心只存 env-NAME,值在读方自己的环境里。写权限 publisher(一个对端就是一组新挂进智能体的远端技能,同 mcp)。
+// 首版不收 `notes` / `rosters`(按 roster 定向)/ `toolAxes`(中心面不替调用方担保远端技能的副作用轴):三者都被剥并告警。
+/** 一个常驻出站 A2A 对端。 */
+export const A2aPeerSpec = z.object({
+    /** 对端的身份:线上工具名 `a2a__<名>__…` 的命名空间段 —— 线上名判官({@link isUsableWireName}:非空、≤128、首尾无空白;不截断、不 trim)。 */
+    name: z.string().refine(isUsableWireName, buildQuotedIssue `a2a peer name must be non-empty, at most ${fixed(String(TOOL_WIRE_NAME_MAX_CHARS))} characters, with no leading or trailing whitespace — it is the peer's identity in the wire tool names (a2a__<name>__…); it is never trimmed or truncated`),
+    /** 对端的服务 URL(也是知名路径上的 agent card 相对它解析的源)。不带凭据(userinfo / 密钥形值)、不带 fragment。 */
+    url: NON_SECRET_URL,
+    /** agent card 的显式位置(对端不在知名路径上发布时);在场 ⇒ 只用它。同一只 URL 判官。 */
+    cardUrl: NON_SECRET_URL.optional(),
+    /** 头名 → 读方环境里的 env-NAME(例:`Authorization → KB_TOKEN`),**绝不是值**。任一引用坏形 ⇒ 整个对端读不进(不部分抢救);读方对任一缺席的 env 整个对端跳过。 */
+    headerRefs: McpHeaderRefs.optional(),
+    /** 读方把任务的已鉴权终端主体填进去的那个头名(不是引用 —— 值由读方逐请求填,模型碰不到)。 */
+    principalHeader: HTTP_HEADER_NAME.optional(),
+    /** 只挂这些技能 id(白名单);缺席或空 = 对端发布的全部。 */
+    allowSkills: z.array(z.string().min(1)).optional(),
+    /** 挂在哪些场景;空 = 全部(与 mcp / skills 同一条读方过滤)。 */
+    scenarios: z.array(z.string().min(1)).prefault([]),
+    enabled: z.boolean().default(true),
+});
+/** `a2a` 域:常驻出站 A2A 对端名册。空 / 缺席 = 不拨任何对端。对端名唯一(重名拒,同 mcp)。 */
+export const A2aConfig = z
+    .object({ peers: z.array(A2aPeerSpec).prefault([]) })
+    .superRefine((cfg, ctx) => {
+    const seen = new Set();
+    cfg.peers.forEach((p, i) => {
+        if (seen.has(p.name))
+            ctx.addIssue({ code: "custom", ...buildQuotedIssue `duplicate a2a peer "${p.name}"`, path: ["peers", i, "name"] });
+        seen.add(p.name);
+    });
+});
 // ── Domain: plugins (plugin SOURCE REFERENCES — C2 plugins 上云, additive 0.5.0) ──────────────────────────
 // The cloud stores WHERE a plugin comes from, NEVER its content (产品拍板): {name, source, version/sha pin}.
 // The consuming shell materializes the plugin locally from the ref (git clone / marketplace install) — the
@@ -2863,6 +3009,7 @@ export const DOMAIN_SCHEMAS = {
     projects: ProjectsConfig, // 0.10.0: 142-S3 project identity ledger + 无仓铸造权威 (scope=tenant 轴; NOT portable — 租户身份数据)
     prompts: PromptsConfig, // 0.10.18 起;14.0.0 单轴:中心 artifact 的身份(`{ artifact?, workers? }`);13.x 两轴的键是墓碑(SS-M10)
     limits: LimitsConfig, // 0.19.0: cost/限流族热更新发布位(消费方 #322 批1;本地腿闭集缺口的源头修复)
+    a2a: A2aConfig, // 18.0.0: 常驻出站 A2A 对端名册(便携;本地腿 config.d/a2a.json 与中心腿 /effective.a2a 同一个声明座)
     // integrations + access: DELETED in 0.6.0 (EXPERT-REDESIGN §9) — parseDomain/effective/路由随之 404。
 };
 // ── Effective-config PROVENANCE (the unified shape TOC `sema config --effective` and TOB `/effective?principal=`

package/dist/url-credential.d.ts

@@ -2,13 +2,23 @@
 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 大小写不敏感)在这张表上的参数就是凭据。
+ * 凭据参数名表(闭集,23 词,全部是小写 ASCII `[a-z][a-z0-9_-]*`)。query / fragment 里名字整名(ASCII 大小写不敏感)在这张表上的参数就是凭据;
+ * 18.0.0 起以其中的强档词收尾的复合名也是(`db_password` 等,判由 {@link credentialParamWordOf})。
  * 加一个词 = 表里加一格(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 大小写不敏感)才算。
+ * 🔴 **「这个已解码的参数名是不是凭据名」的唯一答者**(18.0.0):是 ⇒ 名表里的那个词(小写);不是 ⇒ `undefined`。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字)。
+ *  · 整名(ASCII 大小写不敏感)在 {@link CREDENTIAL_PARAM_NAMES} 里 ⇒ 那个词(整名优先);
+ *  · 否则末段的尾部是强档词(`password` / `passwd` / `pwd` / `secret` / `apikey`),或名字末尾是尾串闭集的一条(`secret_key` / `secret_access_key` ⇒ `secret`;`api_key` ⇒ `api_key`;`access_token` ⇒ `access_token`;答词的律见 {@link COMPOUND_TAIL_PHRASES})⇒ 那个词。
+ *    切段、粘连与对齐的律见模块头「名字判定」。
+ * 返回的词是**表词**:消费方拿它去查自己挂在名表上的那一列(例:日志脱敏器的锚强度),不对整名再查一遍表。
+ */
+export declare function credentialParamWordOf(decodedName: string): CredentialParamName | undefined;
+/**
+ * 「这个**已解码**的参数名是不是凭据名」:{@link credentialParamWordOf} 有词。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字);
+ * 整名在 {@link CREDENTIAL_PARAM_NAMES} 里、或末段 / 尾串收在强档词上(`db_password` / `PGPASSWORD` / `SECRET_KEY`)才算。
  */
 export declare function isCredentialParamName(decodedName: string): boolean;
 /** 每个拒因词带的细节(键集必须覆盖 {@link URL_CREDENTIAL_REASONS} 的每个词:数组里加一个词而这里没跟 ⇒ 下面的映射型编译红,{@link urlCredentialRule} 的穷举 switch 也红)。 */

package/dist/url-credential.js

@@ -2,16 +2,28 @@
  * **「这个 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` 按**值形**判密钥 —— 值长得像密钥
+ * 本判官按**名**判 —— 参数叫什么(名字是凭据名 = 整名在 {@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};**值从不进答案**,参数名只回显表里的那个词(小写)。
+ *  · **query 参数**、**fragment 参数**(同一段文法)里名字是凭据名的那一个(判由 {@link credentialParamWordOf},下一节)—— 名字按收方的读法读:WHATWG `URLSearchParams` 解一次码,
+ *    ASCII 大小写不敏感(不做 Unicode 折叠);`tokens` / `keyword` / `password_hash` 不是凭据名。
+ * 答首个命中(判序 = 上面的序),拒因闭集两词 {@link URL_CREDENTIAL_REASONS};**值从不进答案**,参数名只回显表里的那个词(小写;复合名回显的是它收尾的那个词,不是调用方的名字字节)。
+ *
+ * ## 名字判定:整名,或末段(18.0.0)—— 答者一只 {@link credentialParamWordOf}
+ * 「这个已解码的名字是不是凭据名」只有一个答者,{@link isCredentialParamName} 与本判官的 query / fragment 臂都读它(不留第二张表、第二条规则):
+ *  1. **整名**(ASCII 大小写不敏感)在 {@link CREDENTIAL_PARAM_NAMES} 上 ⇒ 那个词(照旧;整名优先:`client_secret` 答 `client_secret`,不答它的末段 `secret`);
+ *  2. 否则名字按 `_` / `-` / `.` 与驼峰边界切段(空段不存在),**末段**的尾部是**强档词**(`password` / `passwd` / `pwd` / `secret` / `apikey`;列在 {@link COMPOUND_TAIL_STANCE})⇒ 那个词 ——
+ *     末段整段是它(`db_password` / `dbPassword` / `x-db-secret` / `user_pwd`),或它与前缀粘连(`PGPASSWORD`)都算;词**不跨**分隔符(`app_wd` 不是 `pwd`);
+ *  3. 尾串闭集 {@link COMPOUND_TAIL_PHRASES}(逐词对齐,分隔符与大小写不论):`secret key` · `secret access key` ⇒ `secret`(`SECRET_KEY` / `AWS_SECRET_ACCESS_KEY`);`api key` ⇒ `api_key`(`x-api-key` / `X_API_KEY` / `xApiKey`);
+ *     `access token` ⇒ `access_token`(`github_access_token` / `oauth-access-token`)。答词的律只有一条:尾串用 `_` 连起来本身在整名表里 ⇒ 答那个整名词,否则答强段词。
+ * **只看末尾**:前缀 / 中段命中不算,词后还有别的字就不是(`password_hash` / `password_policy` / `secretName` / `pwd_dir` / `passwordless`);数字尾巴不剥(`password2` 的末段是 `password2`)。
+ * 名表里别的 18 个词(`token` / `key` / `refresh_token` / `private_key` …)在自由文本和路径里常是普通词、或本身带分隔符,作末尾时只认整名(上面三条的尾词与尾串除外)—— 裸 `access_key` 照整名表,不借尾串扩;
+ * 末段不是尾串的末词不命中(`api_key_count` / `token_count` / `api_key_id`)。
+ * 误报面(谁受伤):以强档词收尾、但值不是凭据的名字(`show_password=1` / `is_secret=true`)也会被判成凭据名:受理口拒这样的 URL、脱敏器遮它的值 —— 方向是多拒多遮(少洗的一侧是真钥明文)。
  * 不透明形 / 解析不了的值没有可读的部件 ⇒ 答「没有」—— 这一形收不收是**座位**自己的律,不在本判官里。
  *
  * ## 判官只判「有没有」;座位决定怎么用
@@ -22,12 +34,15 @@
  * ## 名表的来源
  * {@link CREDENTIAL_PARAM_NAMES} 是 server 日志脱敏器名表(锚强度表的键)的 23 词。脱敏器另有一列「自由文本里这个词的锚强度」,那一列是脱敏器的事,不在这里;
  * 词表本身在这里成为契约面 —— 脱敏器与本判官读同一张词表(同一个定义)靠消费方把它的表键钉在本导出上(例:`Record<CredentialParamName, …>` 的穷尽映射 ⇒ 加 / 删词不同步即编译红)。
+ * 18.0.0 起本模块同表多一列 {@link COMPOUND_TAIL_STANCE}「这个词作为更长名字的末尾时算不算」:同一个 `Record<CredentialParamName, …>` 穷尽映射,表里加一个词而这一列不表态 ⇒ 编译红。
+ * 消费方(脱敏器的三个名字读者、受理口判官)读的是 {@link credentialParamWordOf} 返回的词 —— 拿它去查自己那一列(例:锚强度),不再对整名查表。
  */
 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 大小写不敏感)在这张表上的参数就是凭据。
+ * 凭据参数名表(闭集,23 词,全部是小写 ASCII `[a-z][a-z0-9_-]*`)。query / fragment 里名字整名(ASCII 大小写不敏感)在这张表上的参数就是凭据;
+ * 18.0.0 起以其中的强档词收尾的复合名也是(`db_password` 等,判由 {@link credentialParamWordOf})。
  * 加一个词 = 表里加一格(minor);判官与 {@link isCredentialParamName} 现算,不手抄第二份。
  */
 export const CREDENTIAL_PARAM_NAMES = Object.freeze([
@@ -44,17 +59,157 @@ export const CREDENTIAL_PARAM_NAMES = Object.freeze([
 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());
+/** 名表的**唯一**查口:已折成小写的拼写是名表里的词 ⇒ 那个词,否则 `undefined`(整名臂与尾串答词的解析都经它,模块里不再有第二处读 `Set`)。 */
+function tableWordOf(lowerSpelling) {
+    return CREDENTIAL_PARAM_NAME_SET.has(lowerSpelling) ? lowerSpelling : undefined;
+}
+/**
+ * 🔴 名表的第二列:每个词作为更长名字的末尾时算不算(见 {@link CompoundTailStance})。键是 `Record<CredentialParamName, …>` 的**穷尽映射** ——
+ * 名表加一个词而这一列没给它表态 ⇒ 缺键,编译红;名表删一个词而这一列还留着 ⇒ 多余键,编译红。词表与这一列同住在本模块,消费方只读 {@link credentialParamWordOf} 的答案。
+ */
+const COMPOUND_TAIL_STANCE = {
+    api_key: "whole-name-only", apikey: "tail-word", "api-key": "whole-name-only", key: "whole-name-only",
+    token: "whole-name-only", access_token: "whole-name-only", refresh_token: "whole-name-only", id_token: "whole-name-only",
+    auth: "whole-name-only", authorization: "whole-name-only", "proxy-authorization": "whole-name-only",
+    password: "tail-word", passwd: "tail-word", pwd: "tail-word",
+    secret: "tail-word", client_secret: "whole-name-only", private_key: "whole-name-only",
+    signature: "whole-name-only", sig: "whole-name-only",
+    "x-amz-signature": "whole-name-only", "x-amz-security-token": "whole-name-only", "x-amz-credential": "whole-name-only",
+    sas: "whole-name-only",
+};
+/**
+ * 尾串闭集(多词):名表里没有、但名字末尾是这几个词的串就是凭据名。
+ *
+ * 🔴 **尾串答词只有一条律,不逐项特判**:尾串的词用 `_` 连起来,若**本身就是整名表里的词**,答那个整名词(与整名的答案同形,下游挂在名表上的列〔锚强度〕随之同形);
+ * 否则答它的**强段词**(`strong`,名表里态度为 `tail-word` 的词)。单词尾词是同一条律的退化形(一个词连起来就是它自己,它在表里)。解析在加载期做一次({@link COMPOUND_TAILS}):
+ * 既不在整名表里、又没写强段词的尾串 ⇒ 抛,不静默成死条目。
+ *  · `secret key` · `secret access key`:`secret_key` / `secret_access_key` 不在整名表 ⇒ 答 `secret` —— `SECRET_KEY` · `AWS_SECRET_ACCESS_KEY` 的真钥住在这样的名字里,而末段只是 `KEY`(常用词);
+ *  · `api key`:`api_key` 在整名表 ⇒ 答 `api_key` —— `x-api-key` · `X_API_KEY` · `xApiKey`(名表里 `api_key` 只认整名,带前缀的头名 / 参数名由这一条收);
+ *  · `access token`:`access_token` 在整名表 ⇒ 答 `access_token` —— `github_access_token` · `oauth-access-token`。
+ * 闭集,不做通配:别的名表多段词(`refresh_token` · `private_key` …)与裸 `access_key` 作末尾照今天整名表;末段不是尾串的末词不命中(`api_key_count` · `token_count`)。
+ */
+const COMPOUND_TAIL_PHRASES = [
+    { words: ["secret", "key"], strong: "secret" },
+    { words: ["secret", "access", "key"], strong: "secret" },
+    { words: ["api", "key"] },
+    { words: ["access", "token"] },
+];
+/** 这一档是不是「作为末尾算数」(穷尽 `switch`)。 */
+function endsLongerNames(stance) {
+    switch (stance) {
+        case "tail-word":
+            return true;
+        case "whole-name-only":
+            return false;
+    }
+}
+/**
+ * 全部尾串 = 名表里态度为 `tail-word` 的词(单词)+ 尾串闭集,答词按 {@link COMPOUND_TAIL_PHRASES} 头注的律解析。词必须是单段 `[a-z0-9]+`
+ * (切段切不出分隔符,带分隔符的词永远对不上 ⇒ 加载期抛,不静默成死条目)。
+ */
+const COMPOUND_TAILS = (() => {
+    const specs = [];
+    for (const w of CREDENTIAL_PARAM_NAMES) {
+        if (endsLongerNames(COMPOUND_TAIL_STANCE[w]))
+            specs.push({ words: [w] });
+    }
+    specs.push(...COMPOUND_TAIL_PHRASES);
+    return specs.map((spec) => {
+        for (const w of spec.words) {
+            if (!/^[a-z0-9]+$/.test(w))
+                throw new Error(`url-credential: compound-name tail word ${JSON.stringify(w)} must be one lowercase [a-z0-9] segment (names are cut at _ - . and camel boundaries)`);
+        }
+        const word = tableWordOf(spec.words.join("_")) ?? spec.strong;
+        if (word === undefined)
+            throw new Error(`url-credential: compound-name tail ${JSON.stringify(spec.words.join("_"))} is not a table word and names no strong word`);
+        return { words: spec.words, word };
+    });
+})();
+/** 切段只需要末尾这几段(最长的尾串有几个词就留几段)。 */
+const TAIL_SEGMENTS_KEPT = Math.max(...COMPOUND_TAILS.map((t) => t.words.length));
+/**
+ * 名字的末尾几段(小写,最多 `keep` 段,末段在最后)。切点:`_` `-` `.`(连续的、首尾的都只是分隔,空段不存在)与驼峰边界(小写字母 / 数字 → 大写字母,
+ * 大写串的最后一个大写字母若后面跟小写字母,它起新的一段:`HTTPPassword` → `HTTP` `Password`;`PGPASSWORD` 没有边界,是一段)。只折 ASCII 大小写,线性读,不用正则后顾断言(老浏览器加载期就抛)。
+ */
+function tailSegmentsOf(name, keep) {
+    const segs = [];
+    let start = 0;
+    const cut = (end) => {
+        if (end <= start)
+            return;
+        segs.push(name.slice(start, end));
+        if (segs.length > keep)
+            segs.shift();
+    };
+    const isUpper = (c) => c >= 65 && c <= 90;
+    const isLower = (c) => c >= 97 && c <= 122;
+    const isDigit = (c) => c >= 48 && c <= 57;
+    for (let i = 0; i < name.length; i++) {
+        const c = name.charCodeAt(i);
+        if (c === 95 || c === 45 || c === 46) {
+            cut(i);
+            start = i + 1;
+        }
+        else if (i > start && isUpper(c)) {
+            const prev = name.charCodeAt(i - 1);
+            if (isLower(prev) || isDigit(prev) || (isUpper(prev) && isLower(name.charCodeAt(i + 1)))) {
+                cut(i);
+                start = i;
+            }
+        }
+    }
+    cut(name.length);
+    return segs.map(asciiLower);
+}
+/**
+ * 这几段的末尾是不是这条尾串:从右往左逐词吃 —— 一段末尾能吃几个词就吃几个;吃完一段还剩词,这一段必须刚好吃光(切点落在词界上:词不跨分隔符,`app_wd` 不是 `pwd`);
+ * 词吃完时,最左那一段允许还剩前缀(`PGPASSWORD` 的 `PG`)。
+ */
+function endsWithTail(words, segs) {
+    let w = words.length;
+    let s = segs.length;
+    while (w > 0) {
+        if (s === 0)
+            return false;
+        let rest = segs[--s];
+        while (w > 0 && rest.endsWith(words[w - 1])) {
+            rest = rest.slice(0, rest.length - words[w - 1].length);
+            w--;
+        }
+        if (w > 0 && rest !== "")
+            return false;
+    }
+    return true;
+}
+/**
+ * 🔴 **「这个已解码的参数名是不是凭据名」的唯一答者**(18.0.0):是 ⇒ 名表里的那个词(小写);不是 ⇒ `undefined`。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字)。
+ *  · 整名(ASCII 大小写不敏感)在 {@link CREDENTIAL_PARAM_NAMES} 里 ⇒ 那个词(整名优先);
+ *  · 否则末段的尾部是强档词(`password` / `passwd` / `pwd` / `secret` / `apikey`),或名字末尾是尾串闭集的一条(`secret_key` / `secret_access_key` ⇒ `secret`;`api_key` ⇒ `api_key`;`access_token` ⇒ `access_token`;答词的律见 {@link COMPOUND_TAIL_PHRASES})⇒ 那个词。
+ *    切段、粘连与对齐的律见模块头「名字判定」。
+ * 返回的词是**表词**:消费方拿它去查自己挂在名表上的那一列(例:日志脱敏器的锚强度),不对整名再查一遍表。
+ */
+export function credentialParamWordOf(decodedName) {
+    const whole = tableWordOf(asciiLower(decodedName));
+    if (whole !== undefined)
+        return whole;
+    const segs = tailSegmentsOf(decodedName, TAIL_SEGMENTS_KEPT);
+    for (const tail of COMPOUND_TAILS)
+        if (endsWithTail(tail.words, segs))
+            return tail.word;
+    return undefined;
+}
 /**
- * 「这个**已解码**的参数名是不是凭据名」。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字):整名在 {@link CREDENTIAL_PARAM_NAMES} 里(ASCII 大小写不敏感)才算。
+ * 「这个**已解码**的参数名是不是凭据名」:{@link credentialParamWordOf} 有词。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字);
+ * 整名在 {@link CREDENTIAL_PARAM_NAMES} 里、或末段 / 尾串收在强档词上(`db_password` / `PGPASSWORD` / `SECRET_KEY`)才算。
  */
 export function isCredentialParamName(decodedName) {
-    return CREDENTIAL_PARAM_NAME_SET.has(asciiLower(decodedName));
+    return credentialParamWordOf(decodedName) !== undefined;
 }
 /** 一段参数串(`?` / `#` 之后)里第一个凭据名参数的表词(小写);没有 ⇒ `undefined`。 */
 function credentialParamIn(params) {
     for (const name of new URLSearchParams(params).keys()) {
-        const word = asciiLower(name);
-        if (CREDENTIAL_PARAM_NAME_SET.has(word))
+        const word = credentialParamWordOf(name);
+        if (word !== undefined)
             return word;
     }
     return undefined;

package/dist/wire-name.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 包内私有叶子模块(运行期零依赖,浏览器安全;不进 `package.json` 的 exports,主桶经 `./mcp-request-entry` 转出这里的两个公开名):
+ * **申报名能不能当线上名**的唯一判据 —— 一台 MCP server 或一个 A2A 对端的申报名会成为线上工具名的命名空间段(`mcp__<名>__…` / `a2a__<名>__…`)。
+ * 住在叶子里,是因为 `./types` 的域 schema(`a2a` 对端名)与请求面的读口(`./mcp-request-entry`)都要它,而后者反过来引 `./types` 的词表 ——
+ * 判据只有这一份函数体,两边 import 同一只。
+ */
+/** 引擎 `TOOL_WIRE_NAME_MAX_CHARS` 的镜像:一台 MCP server(或 A2A 对端)的申报名会成为线上工具名的命名空间段,引擎对超界名是**拒**(不截断)。 */
+export declare const TOOL_WIRE_NAME_MAX_CHARS = 128;
+/**
+ * 首尾带空白吗 —— 「空白」就是 `String.prototype.trim` 剥的那一组(ECMAScript 的 WhiteSpace + LineTerminator:空格 / 制表 / 换行 / NBSP / BOM / 全角空格 / 行段分隔符等)。
+ * {@link isUsableWireName} 与请求面的坏名摘要(`describeBadWireName`)共读这一个定义,判与说不会各按各的口径。
+ */
+export declare const hasEdgeWhitespace: (v: string) => boolean;
+/**
+ * 这个申报名能用吗。严判:非串、空串、超 {@link TOOL_WIRE_NAME_MAX_CHARS}、**首尾带空白**一律不可用。不截断、不 trim、不规范化 —— 截短或剥掉一个名字就是**换一个身份**,
+ * 而被换掉身份的那台 server 上挂的 allowTools / toolFaces 收窄声明会一起对不上号。首尾空白 = 坏名(它不是另一个名字:名字是 `mcp__<server>__<tool>` 的身份片,
+ * 带着空白的一端无从与不带的那个对上号);内部空白(`a b`)照旧是合法名,本判官不扩判。
+ */
+export declare function isUsableWireName(v: unknown): v is string;

package/dist/wire-name.js

@@ -0,0 +1,21 @@
+/**
+ * 包内私有叶子模块(运行期零依赖,浏览器安全;不进 `package.json` 的 exports,主桶经 `./mcp-request-entry` 转出这里的两个公开名):
+ * **申报名能不能当线上名**的唯一判据 —— 一台 MCP server 或一个 A2A 对端的申报名会成为线上工具名的命名空间段(`mcp__<名>__…` / `a2a__<名>__…`)。
+ * 住在叶子里,是因为 `./types` 的域 schema(`a2a` 对端名)与请求面的读口(`./mcp-request-entry`)都要它,而后者反过来引 `./types` 的词表 ——
+ * 判据只有这一份函数体,两边 import 同一只。
+ */
+/** 引擎 `TOOL_WIRE_NAME_MAX_CHARS` 的镜像:一台 MCP server(或 A2A 对端)的申报名会成为线上工具名的命名空间段,引擎对超界名是**拒**(不截断)。 */
+export const TOOL_WIRE_NAME_MAX_CHARS = 128;
+/**
+ * 首尾带空白吗 —— 「空白」就是 `String.prototype.trim` 剥的那一组(ECMAScript 的 WhiteSpace + LineTerminator:空格 / 制表 / 换行 / NBSP / BOM / 全角空格 / 行段分隔符等)。
+ * {@link isUsableWireName} 与请求面的坏名摘要(`describeBadWireName`)共读这一个定义,判与说不会各按各的口径。
+ */
+export const hasEdgeWhitespace = (v) => v.trim() !== v;
+/**
+ * 这个申报名能用吗。严判:非串、空串、超 {@link TOOL_WIRE_NAME_MAX_CHARS}、**首尾带空白**一律不可用。不截断、不 trim、不规范化 —— 截短或剥掉一个名字就是**换一个身份**,
+ * 而被换掉身份的那台 server 上挂的 allowTools / toolFaces 收窄声明会一起对不上号。首尾空白 = 坏名(它不是另一个名字:名字是 `mcp__<server>__<tool>` 的身份片,
+ * 带着空白的一端无从与不带的那个对上号);内部空白(`a b`)照旧是合法名,本判官不扩判。
+ */
+export function isUsableWireName(v) {
+    return typeof v === "string" && v.length > 0 && v.length <= TOOL_WIRE_NAME_MAX_CHARS && !hasEdgeWhitespace(v);
+}