@sema-agent/settings-schema 14.5.0 → 14.7.0

package/dist/index.js

@@ -17,7 +17,8 @@ export * from "./config-fns.js";
 export * from "./reader.js";
 export * from "./cross-domain.js"; // pure half only (no fleet placement)
 export * from "./remote-exec.js";
-export * from "./safety-merge-spec.js"; // #14 per-category safety merge-spec (settings resolver authority)
+export * from "./safety-merge-spec.js"; // #14 per-category safety merge-spec (settings resolver authority) + 14.6.0 THE comparator tightenVerdict / TIGHTEN_VERDICTS and the member comparator memberTighten / resolveMemberTighten (derived from a member row's value class)
+export * from "./settings-units.js"; // 14.6.0: SETTINGS_UNITS — the settings-document unit table (path / category / addressing / reading) + unitTighten (a unit's comparator) + readSettingsUnit (a unit's raw-value reading; spellings normalized, everything else unreadable), pure/browser-safe
 export * from "./scheduler-store.js"; // R7 self-wake scheduler store CONTRACT (pure: type + parse/serialize + SchedulerStore interface; fs binding in ./node)
 export * from "./cross-session.js"; // CC-parity `settings.json` cross-session keys (crossSessionInbound / dialogExpiry) — pure/browser-safe
 export * from "./hooks.js"; // CC-parity hooks contract (33-event set + owner map + per-event input/output shapes + the config surface: classifyHooksConfig and its zod faces HooksConfig / HookEntry …) & stop attribution (stoppedBy) — pure/browser-safe
@@ -28,6 +29,8 @@ export * from "./api/auth-bridge.js"; // 鉴权桥 contract: worker verifies web
 export * from "./api/scopes.js"; // multi-tenant scope contract: /api/v1/scopes* + /api/v1/auth/scope wire shapes + THE minting/switch decision functions (resolveTokenScope / canSwitchScope / effectiveScopeRole / readTokenScope) — web-admin imports these, never re-implements
 export * from "./api/pull-token.js"; // scope-bound token FORM + minting rule (one rule, token families are data: WORKER_PULL_TOKEN) + claimed-binding reader + verifier (re-mint + constant-time compare), pure-JS HMAC-SHA256, browser-safe
 export * from "./api/feedback.js"; // /bug report wire contract: FeedbackSubmitRequest (POST body) + FeedbackWire / FeedbackListResponse + the two caps, pure/browser-safe
+export * from "./api/credentials.js"; // 14.7.0: the credential port's `sandbox_git` wire (barrel only, no subpath): SandboxGitCredentialRequest / CredentialHandleAnswer / CredentialResolveRequest / SandboxGitCredentialAnswer (per-origin SandboxGitOriginAnswer) / SandboxGitCredentialRefusal + the three word tables (SANDBOX_GIT_ORIGIN_VERDICTS → _STATES / _REASONS, SANDBOX_GIT_REFUSALS → _ERRORS, SANDBOX_GIT_PERMANENCE), pure/browser-safe
+export * from "./sandbox-git.js"; // 14.7.0: the sandbox git plane's origin form (isSandboxGitOrigin — a string equal to its own WHATWG origin) + the `sandboxGit` effective-config block (SandboxGitConfig: origins ≤ 16, each { origin, connectUrl }), pure/browser-safe
 export * from "./web-admin-env.js"; // WEB_ADMIN_ENV — every env name an engine reads to reach web-admin (one table; a leaf module), pure/browser-safe
 export * from "./web-admin-credential.js"; // S-698 web-admin credential FILE contract: WebAdminCredentialEnvelope (user-session envelope, strict) + parseWebAdminCredentialFile (bare / envelope / unreadable — the one discrimination law) + judgeWebAdminCredentialDeclaration(env, credential) (pick-exactly-one over the credential's WEB_ADMIN_ENV pair; WEB_ADMIN_CREDENTIALS = access | assertion), pure/browser-safe
 export * from "./web-admin-session-url.js"; // webAdminSessionUrl(webBaseUrl, { worker, sessionId }) — THE web-admin session link template (<webBaseUrl>/chat?agent=<worker>&session=<sessionId>) + parseWebAdminSessionUrl(link) its paired reader, pure/browser-safe

package/dist/mcp-request-entry.d.ts

@@ -1,15 +1,20 @@
 import { type McpContentOrigin } from "./types.js";
-/** 值的**种类**(不回显值本身)。 */
+/** 值的**种类**(不回显值本身)。总(不抛):形状只问座位,读不出的对象说全包唯一的「检视不了」那一句。 */
 export declare function describeValueShape(v: unknown): string;
-/** 「不是字符串数组」的种类:数组里混了非串元素说那一句,否则回落到 {@link describeValueShape}。 */
+/** 「不是字符串数组」的种类:数组里混了非串元素说那一句,否则回落到 {@link describeValueShape}。总(不抛):`isJsonArray` 是座位的总版。 */
 export declare function describeNotStringArray(v: unknown): string;
-/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。 */
+/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。总(不抛)。 */
 export declare function describeNotStringRecord(v: unknown): string;
-/** 字符串数组(空数组合法)。 */
+/**
+ * 字符串数组(空数组合法)—— 类型守卫,所以按 `./own-key-read` 的 `captureStringArray` 的**严归类**读(整容器读,自有下标各一份描述符,非串即坏、不走迭代协议):
+ * 下标是访问器或不可枚举的数组不是(getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份);稀疏数组(洞)、`length` 读不出安全非负整数的数组、
+ * 读不出的数组都不是 —— 洞不顺原型链读到 `Object.prototype` / `Array.prototype` 上的数字键。传输读器读 `args` 交出去的是副本,用同一只函数的宽归类。
+ */
 export declare function isStringArray(v: unknown): v is string[];
 /**
- * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)。与传输读器读 `env` / `headers` 是**同一个**定义
- * ({@link readPlainStringRecord}):包内没有第二把更宽的尺。
+ * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)—— 类型守卫,所以是**严归类**:成员经内核的
+ * `ownEntriesOf` 读(整容器读的严归类:每个自有串键一份描述符;访问器成员或不可枚举的成员 ⇒ 不是,getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份)。
+ * 传输读器读 `env` / `headers`({@link readPlainStringRecord})交出去的是**副本**,按宽归类读(不可枚举的成员照读、访问器调一次);值与成员名的判据(是串、不叫 `__proto__`)两边同一条。
  */
 export declare function isStringRecord(v: unknown): v is Record<string, string>;
 /** 引擎 `TOOL_WIRE_NAME_MAX_CHARS` 的镜像:一台 MCP server(或 A2A 对端)的申报名会成为线上工具名的命名空间段,引擎对超界名是**拒**(不截断)。 */
@@ -58,7 +63,7 @@ export type RequestMcpTransport = {
  * 条目内一处坏形:`path` = 条目内的键路径(`transport.url`),`reason` = 判官的原因句(只说形与词表,不回显值)。
  *
  * `env` / `headers` 这两张「名 → 串」记录上的坏形另带两格机读位,调用方分流不必解析句子:`fault` = 闭集词 ——
- *  · `not_plain_record`:这个键的值不是纯数据记录(不是对象 / 数组 / `null`,或原型不是 `Object.prototype` 与 `null`:`Map`、`Set`、类实例);整张记录不交;
+ *  · `not_plain_record`:这个键的值不是纯数据记录(不是对象 / 数组 / `null`,或不是朴素 JSON 对象 —— 原型链比座位的判据长:`Map`、`Set`、类实例);整张记录不交;
  *  · `member_not_string`:有一个成员的值不是串(或访问器抛了);整张记录不交,`member` 点名它;
  *  · `member_name_reserved`:有一个成员叫 `__proto__`(引擎的声明收据拒这个名)。成员的值是串 ⇒ 只剔这个成员、其余照交,`path` 是成员级(`transport.env.__proto__`);
  *    成员的值也不是串 ⇒ 整张记录不交,`path` 是键级,句子一次说全两件事 —— 名坏优先、值坏并列,所以词仍是 `member_name_reserved`。
@@ -84,7 +89,7 @@ export type RequestMcpTransportRead = {
  *  · 硬坏形(`transport` 不是对象 / `kind` 出闭集 / stdio 缺 `command` / http 的 `url` 不是 http(s))⇒ `ok:false`,`path` 是读器点名的键路径;
  *  · 软坏形(`args` 不是串数组 / `env` `headers` 不是纯数据的串记录 / `principalHeader` 非串)⇒ 读器**丢这个键**(重放存量提交体时的升级前读法),并把它记进 `lost`
  *    (受理新提交的门据它响亮拒)。`assertionHeader` 不在 `lost` 里:两个身份头的键组合与 `assertionHeader` 的值形由调用方在读之前对原始传输判。
- *  · `env` / `headers` 只收**纯数据**的记录({@link readPlainStringRecord}):原型必须是 `Object.prototype` 或 `null`(`Map`、`Set`、类实例整张不收),每个自有成员的值都是串;
+ *  · `env` / `headers` 只收**纯数据**的记录({@link readPlainStringRecord}):必须是朴素 JSON 对象(`./plain-json-object` 的判据;`Map`、`Set`、类实例整张不收),每个自有成员的值都是串;
  *    交出的是**副本**(不是调用方的对象,改原对象不影响读后的形)。名叫 `__proto__` 的成员(JSON 文本铸得出这个自有键,对象字面量写不出)不进副本、单独记进 `lost`。
  *    坏形的 `lost` 条目带机读位(见 {@link McpEntryKeyIssue})。
  * url 的拒句不回显值:它常规地带凭据(userinfo)。

package/dist/mcp-request-entry.js

@@ -16,7 +16,7 @@
  *  · 申报名的线长界 {@link TOOL_WIRE_NAME_MAX_CHARS} = 引擎同名常量(值级对拍:上游漂移门 ⑧);
  *  · 请求面传输形 {@link RequestMcpTransport} = 引擎 MCP 条目的传输形,http 形多一个本包承载的 `assertionHeader`(编译期双向对拍:门 ⑧);
  *  · 内容出处词表 = {@link MCP_CONTENT_ORIGINS}(已有的镜像,门 ⑥);
- *  · url 前缀守卫 = `./url-shape` 的 `startsWithHttpScheme`(本包判 URL 的正则只在那一个模块)。
+ *  · url 前缀守卫 = `./url-shape` 的 `startsWithHttpScheme`(本包判 URL 的正则只在那一个模块)。它只看前缀,不是形判官 —— 同一个串两口可以答得不同,两张分歧表与收口形(S-2106)写在 `./url-shape` 头注「第二个答案」。
  *
  * ## 与配置面的关系(如实)
  * 配置面的 MCP 条目(`McpServerSpec`,部署声明:凭据只许 env-NAME 引用)与请求面(提交体:可带字面凭据 `env` / `headers`)是两份契约,本模块只管后者。
@@ -24,45 +24,80 @@
  * (语义逐字搬),是一项已知待收的分歧。
  */
 import { echoCallerText } from "./caller-text-echo.js";
+import { UNINSPECTABLE, captureStringArray, dataDescriptor, inspect, ownEntriesOf, ownFieldsOf, ownValueOf, readKey } from "./own-key-read.js";
+import { isJsonArray, isPlainJsonObject, jsonShapeOf } from "./plain-json-object.js";
 import { MCP_CONTENT_ORIGINS } from "./types.js";
 import { startsWithHttpScheme } from "./url-shape.js";
 // ── 值的种类描述(拒句只说「你写的是什么形」,不回显值:值可能带凭据、可能任意长)──────────────────────────────────────
-/** 值的**种类**(不回显值本身)。 */
+/** 值的**种类词**(不回显值本身):`null` / `array` / `typeof` 词(`object` / `function` / `string` …);读不出的对象 ⇒ 全包唯一的那一句。形状只问座位(总,不抛):两只坏值描述器共用这一只。 */
+function describeKindWord(v) {
+    const shape = jsonShapeOf(v);
+    switch (shape) {
+        case "null":
+            return "null";
+        case "array":
+            return "array";
+        case "uninspectable":
+            return UNINSPECTABLE;
+        case "plain":
+        case "non_plain_object":
+        case "primitive":
+            return typeof v;
+        default: {
+            const unhandled = shape;
+            throw new Error(`describeKindWord: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
+/** 值的**种类**(不回显值本身)。总(不抛):形状只问座位,读不出的对象说全包唯一的「检视不了」那一句。 */
 export function describeValueShape(v) {
     if (v === undefined)
         return "nothing (the key is absent)";
-    if (v === null)
-        return "null";
-    if (Array.isArray(v))
-        return "an array";
-    if (typeof v === "string")
-        return v.length === 0 ? "an empty string" : `a string of ${v.length} characters`;
-    if (typeof v === "object")
-        return "an object";
-    return `a ${typeof v}`;
-}
-/** 「不是字符串数组」的种类:数组里混了非串元素说那一句,否则回落到 {@link describeValueShape}。 */
+    const shape = jsonShapeOf(v);
+    switch (shape) {
+        case "null":
+            return "null";
+        case "array":
+            return "an array";
+        case "uninspectable":
+            return UNINSPECTABLE;
+        case "plain":
+        case "non_plain_object":
+            return typeof v === "function" ? "a function" : "an object";
+        case "primitive":
+            return typeof v === "string" ? (v.length === 0 ? "an empty string" : `a string of ${v.length} characters`) : `a ${typeof v}`;
+        default: {
+            const unhandled = shape;
+            throw new Error(`describeValueShape: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
+/** 「不是字符串数组」的种类:数组里混了非串元素说那一句,否则回落到 {@link describeValueShape}。总(不抛):`isJsonArray` 是座位的总版。 */
 export function describeNotStringArray(v) {
-    return Array.isArray(v) ? "an array with a non-string element" : describeValueShape(v);
+    return isJsonArray(v) ? "an array with a non-string element" : describeValueShape(v);
 }
-/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。 */
+/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。总(不抛)。 */
 export function describeNotStringRecord(v) {
-    return isRecord(v) ? "an object with a non-string value" : describeValueShape(v);
+    return isPlainJsonObject(v) ? "an object with a non-string value" : describeValueShape(v);
 }
-/** 字符串数组(空数组合法)。 */
+/**
+ * 字符串数组(空数组合法)—— 类型守卫,所以按 `./own-key-read` 的 `captureStringArray` 的**严归类**读(整容器读,自有下标各一份描述符,非串即坏、不走迭代协议):
+ * 下标是访问器或不可枚举的数组不是(getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份);稀疏数组(洞)、`length` 读不出安全非负整数的数组、
+ * 读不出的数组都不是 —— 洞不顺原型链读到 `Object.prototype` / `Array.prototype` 上的数字键。传输读器读 `args` 交出去的是副本,用同一只函数的宽归类。
+ */
 export function isStringArray(v) {
-    return Array.isArray(v) && v.every((a) => typeof a === "string");
+    return captureStringArray(v, "strict") !== undefined;
 }
 /**
- * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)。与传输读器读 `env` / `headers` 是**同一个**定义
- * ({@link readPlainStringRecord}):包内没有第二把更宽的尺。
+ * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)—— 类型守卫,所以是**严归类**:成员经内核的
+ * `ownEntriesOf` 读(整容器读的严归类:每个自有串键一份描述符;访问器成员或不可枚举的成员 ⇒ 不是,getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份)。
+ * 传输读器读 `env` / `headers`({@link readPlainStringRecord})交出去的是**副本**,按宽归类读(不可枚举的成员照读、访问器调一次);值与成员名的判据(是串、不叫 `__proto__`)两边同一条。
  */
 export function isStringRecord(v) {
-    const read = readPlainStringRecord(v);
-    return read.ok && !read.reservedMember;
-}
-function isRecord(v) {
-    return v !== null && typeof v === "object" && !Array.isArray(v);
+    if (!isPlainJsonObject(v))
+        return false;
+    const entries = ownEntriesOf(v);
+    return entries.ok && entries.value.every(([name, value]) => name !== RESERVED_MEMBER_NAME && typeof value === "string");
 }
 // ── 调用方写的串的回显口径 ──────────────────────────────────────────────────────────────────────────
 /** 句子里点名一个值的写法:{@link echoCallerText} 外加一对双引号;内部的引号与反斜杠逐字(不转义)。 */
@@ -92,7 +127,7 @@ export function isUsableWireName(v) {
  */
 export function describeBadWireName(v) {
     if (typeof v !== "string")
-        return v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+        return describeKindWord(v);
     if (v.length === 0)
         return "empty";
     const head = quotedCallerText(v);
@@ -112,7 +147,7 @@ export function isContentOriginWord(v) {
 }
 /** 坏内容出处值的**可打印**摘要:串 ⇒ 引号形的回显({@link quotedCallerText}:剥控制与双向字符、截 64 字);非串只说种类。 */
 export function describeBadContentOrigin(v) {
-    return typeof v === "string" ? quotedCallerText(v) : v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+    return typeof v === "string" ? quotedCallerText(v) : describeKindWord(v);
 }
 // ── 两个身份头 ──────────────────────────────────────────────────────────────────────────────────────
 /**
@@ -120,105 +155,204 @@ export function describeBadContentOrigin(v) {
  * `assertionHeader` 不收。所以读后的形**结构上不可能同带两键**;同设(一份声明给出两个答案)由调用方在读之前对**原始**传输判(判的是写了什么,不是读后留下什么)。
  */
 export function readMcpIdentityHeaders(transport) {
+    const ids = identityFieldsOf(transport);
+    if (!ids.ok)
+        return {}; // 读不出 ⇒ 身份头整体读不出(传输读器对同样的输入是整只不交)
+    const { principalHeader, assertionHeader } = ids.value;
+    return {
+        ...(typeof principalHeader === "string" ? { principalHeader } : {}),
+        ...(typeof assertionHeader === "string" ? { assertionHeader } : {}),
+    };
+}
+/**
+ * 两个身份头的**唯一读法**(公开读者与传输快照共用):只有 `principalHeader` **干净地读成缺席**时才读 `assertionHeader`;`principalHeader` 在场(不论值形)⇒ `assertionHeader` 一次不读;
+ * 任何一个读不出 ⇒ 整体读不出(`ok:false`,向上传),不折成 `undefined` —— 不然「principal 读不出」会落到 assertion、读它的 getter。
+ * **只读自有键**(身份只认自有键):键只靠继承可见(含 `Object.prototype` 被污染成数据值)⇒ 不读它的值、当缺席,但**记下**(`principalInherited` / `assertionInherited`)—— 传输读器据此点名,
+ * 身份轴上不静默;公开读者没有 `lost` 通道,只读值。
+ */
+function identityFieldsOf(record) {
+    const principal = readKey(record, "principalHeader");
+    if (principal.presence === "unreadable")
+        return { ok: false, sentence: UNINSPECTABLE };
+    if (principal.presence === "own" && principal.value !== undefined) {
+        return { ok: true, value: { principalHeader: principal.value, assertionHeader: undefined, principalInherited: false, assertionInherited: false } };
+    }
+    const assertion = readKey(record, "assertionHeader");
+    if (assertion.presence === "unreadable")
+        return { ok: false, sentence: UNINSPECTABLE };
     return {
-        ...(typeof transport.principalHeader === "string" ? { principalHeader: transport.principalHeader } : {}),
-        ...(transport.principalHeader === undefined && typeof transport.assertionHeader === "string" ? { assertionHeader: transport.assertionHeader } : {}),
+        ok: true,
+        value: {
+            principalHeader: undefined,
+            assertionHeader: assertion.presence === "own" ? assertion.value : undefined,
+            principalInherited: principal.presence === "inherited",
+            assertionInherited: assertion.presence === "inherited",
+        },
     };
 }
 const transportBad = (path, reason) => ({ ok: false, issue: { path, reason } });
+/** 身份头只靠继承可见时的 `lost` 条目:不读它的值,但点名(身份轴不静默;句子不回显值)。机读位不带(`fault` 的闭集不为它加词)。 */
+const inheritedIdentityIssue = (key) => ({
+    path: `transport.${key}`,
+    reason: "inherited key ignored (the key is visible only through the prototype chain; a transport's identity headers are read from its own keys)",
+});
 /**
  * 请求面 `transport` 的**唯一读器**:读器投影 transport 用它,发送前 / 受理时的判形读它报的 `lost` —— 同一只函数两个消费点,「读器丢了什么」与「门拒什么」不可能分岔。
  *  · 硬坏形(`transport` 不是对象 / `kind` 出闭集 / stdio 缺 `command` / http 的 `url` 不是 http(s))⇒ `ok:false`,`path` 是读器点名的键路径;
  *  · 软坏形(`args` 不是串数组 / `env` `headers` 不是纯数据的串记录 / `principalHeader` 非串)⇒ 读器**丢这个键**(重放存量提交体时的升级前读法),并把它记进 `lost`
  *    (受理新提交的门据它响亮拒)。`assertionHeader` 不在 `lost` 里:两个身份头的键组合与 `assertionHeader` 的值形由调用方在读之前对原始传输判。
- *  · `env` / `headers` 只收**纯数据**的记录({@link readPlainStringRecord}):原型必须是 `Object.prototype` 或 `null`(`Map`、`Set`、类实例整张不收),每个自有成员的值都是串;
+ *  · `env` / `headers` 只收**纯数据**的记录({@link readPlainStringRecord}):必须是朴素 JSON 对象(`./plain-json-object` 的判据;`Map`、`Set`、类实例整张不收),每个自有成员的值都是串;
  *    交出的是**副本**(不是调用方的对象,改原对象不影响读后的形)。名叫 `__proto__` 的成员(JSON 文本铸得出这个自有键,对象字面量写不出)不进副本、单独记进 `lost`。
  *    坏形的 `lost` 条目带机读位(见 {@link McpEntryKeyIssue})。
  * url 的拒句不回显值:它常规地带凭据(userinfo)。
  */
 export function readRequestMcpTransport(t) {
-    if (!t || typeof t !== "object")
-        return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${describeValueShape(t)}`);
-    const tr = t;
-    const lost = [];
-    if (tr.kind === "stdio") {
-        if (typeof tr.command !== "string" || tr.command.length === 0)
-            return transportBad("transport.command", `must be a non-empty string (the command to run) — got ${describeValueShape(tr.command)}`);
-        if (tr.args !== undefined && !isStringArray(tr.args))
-            lost.push({ path: "transport.args", reason: `must be an array of strings — got ${describeNotStringArray(tr.args)}` });
-        const env = readTransportRecord("transport.env", tr.env, lost);
-        return {
-            ok: true,
-            transport: {
-                kind: "stdio",
-                command: tr.command,
-                ...(isStringArray(tr.args) ? { args: tr.args } : {}),
-                ...(env !== undefined ? { env } : {}),
-            },
-            lost,
-        };
+    const shape = jsonShapeOf(t); // 总:检视就抛的对象(已撤销的 Proxy、原型陷阱抛)座位答 `uninspectable` ⇒ 下面「检视不了」那一臂,整只不交、不抛
+    switch (shape) {
+        case "plain":
+        case "array":
+            break; // 数组走下面 `kind` 缺席那一臂(JSON 面的 path / 句子逐字不变)
+        case "null":
+        case "primitive":
+            return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${describeValueShape(t)}`);
+        case "uninspectable":
+            return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${UNINSPECTABLE}`); // 读形状就抛(已撤销的 Proxy):全包唯一的「检视不了」那句
+        case "non_plain_object":
+            // 是对象但不朴素 ⇒ 硬拒;函数仍说 `a function`(14.5.0 的句子),别的非朴素对象说「不是朴素数据」
+            return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${typeof t === "function" ? describeValueShape(t) : "an object that is not plain data"}`);
+        default: {
+            const unhandled = shape;
+            throw new Error(`readRequestMcpTransport: unhandled shape ${String(unhandled)}`);
+        }
     }
-    if (tr.kind === "http") {
-        // http(s) only — never file://, never a bare host (a syntactic guard, not the URL shape judge).
-        if (typeof tr.url !== "string" || !startsWithHttpScheme(tr.url))
-            return transportBad("transport.url", "must be an absolute http(s) URL (put credentials in transport.headers, never in the URL)");
-        const ids = readMcpIdentityHeaders(tr);
-        const headers = readTransportRecord("transport.headers", tr.headers, lost);
-        if (tr.principalHeader !== undefined && ids.principalHeader === undefined) {
-            lost.push({ path: "transport.principalHeader", reason: `must be a string (the HTTP header NAME the end-user principal is injected into) — got ${describeValueShape(tr.principalHeader)}` });
+    const tr = t;
+    // 字段只读一次:经读内核把「这一种传输要读的字段」读成局部快照(描述符 / `has` 陷阱抛的 Proxy / 会抛的自有 getter ⇒ 整只不交,不抛;`get` 陷阱不被问),之后只读快照;这一种传输用不到的字段一次也不读
+    const snapshotRead = snapshotTransport(tr);
+    if (!snapshotRead.ok)
+        return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${snapshotRead.sentence}`);
+    const snap = snapshotRead.value;
+    // `lost` 不用 `push` 累加(`push` 是 [[Set]],会被 `Object.prototype` 上继承的数字键 setter 吞掉 / 读成污染值):每处诊断是一个值或 `undefined`,由 `issuesOf` 一次铸成数组(定义语义)
+    switch (snap.kind) {
+        case "stdio": {
+            if (typeof snap.command !== "string" || snap.command.length === 0)
+                return transportBad("transport.command", `must be a non-empty string (the command to run) — got ${describeValueShape(snap.command)}`);
+            const rawArgs = snap.args; // 交出去的是副本(不是调用方数组的原引用),稀疏 / 读不出的数组整键丢、进 `lost`
+            const args = rawArgs === undefined ? undefined : captureStringArray(rawArgs, "wide");
+            const argsIssue = rawArgs !== undefined && args === undefined ? { path: "transport.args", reason: `must be an array of strings — got ${describeNotStringArray(rawArgs)}` } : undefined;
+            const env = readTransportRecord("transport.env", snap.env);
+            return {
+                ok: true,
+                transport: {
+                    kind: "stdio",
+                    command: snap.command,
+                    ...(args !== undefined ? { args } : {}),
+                    ...(env.record !== undefined ? { env: env.record } : {}),
+                },
+                lost: issuesOf(argsIssue, ...env.issues),
+            };
+        }
+        case "http": {
+            // http(s) only — never file://, never a bare host (a syntactic guard, not the URL shape judge: it also lets a bare `https://` through, see ./url-shape).
+            if (typeof snap.url !== "string" || !startsWithHttpScheme(snap.url))
+                return transportBad("transport.url", "must be an absolute http(s) URL (put credentials in transport.headers, never in the URL)");
+            const ids = readMcpIdentityHeaders({ principalHeader: snap.principalHeader, assertionHeader: snap.assertionHeader });
+            const headers = readTransportRecord("transport.headers", snap.headers);
+            const principalIssue = snap.principalHeader !== undefined && ids.principalHeader === undefined
+                ? { path: "transport.principalHeader", reason: `must be a string (the HTTP header NAME the end-user principal is injected into) — got ${describeValueShape(snap.principalHeader)}` }
+                : undefined;
+            return {
+                ok: true,
+                transport: {
+                    kind: "http",
+                    url: snap.url,
+                    ...(headers.record !== undefined ? { headers: headers.record } : {}),
+                    ...ids,
+                },
+                lost: issuesOf(...headers.issues, principalIssue, snap.principalInherited ? inheritedIdentityIssue("principalHeader") : undefined, snap.assertionInherited ? inheritedIdentityIssue("assertionHeader") : undefined),
+            };
+        }
+        case "other":
+            return transportBad("transport.kind", `must be "stdio" or "http" — got ${describeValueShape(snap.value)}`);
+        default: {
+            const unhandled = snap;
+            throw new Error(`readRequestMcpTransport: unhandled transport kind ${String(unhandled.kind)}`);
         }
-        return {
-            ok: true,
-            transport: {
-                kind: "http",
-                url: tr.url,
-                ...(headers !== undefined ? { headers } : {}),
-                ...ids,
-            },
-            lost,
-        };
     }
-    return transportBad("transport.kind", `must be "stdio" or "http" — got ${describeValueShape(tr.kind)}`);
+}
+function snapshotTransport(tr) {
+    // 九字段一律只读**自有**属性(一条律):JSON 解析只铸自有键,JSON 面不变;原型链上被污染的值 / 会抛的 getter 不触发,注入的值进不来。
+    // 任何一个字段读不出 ⇒ 整只读不出(第一个读不出的就停,后面的一个不读);身份头经 `identityFieldsOf`(与公开读者同一只)。
+    const kind = ownValueOf(tr, "kind");
+    if (!kind.ok)
+        return kind;
+    if (kind.value === "stdio") {
+        const fields = ownFieldsOf(tr, ["command", "args", "env"]);
+        if (!fields.ok)
+            return fields;
+        return { ok: true, value: { kind: "stdio", command: fields.value.command, args: fields.value.args, env: fields.value.env } };
+    }
+    if (kind.value === "http") {
+        const fields = ownFieldsOf(tr, ["url", "headers"]);
+        if (!fields.ok)
+            return fields;
+        const ids = identityFieldsOf(tr);
+        if (!ids.ok)
+            return ids;
+        return { ok: true, value: { kind: "http", url: fields.value.url, headers: fields.value.headers, principalHeader: ids.value.principalHeader, assertionHeader: ids.value.assertionHeader, principalInherited: ids.value.principalInherited, assertionInherited: ids.value.assertionInherited } };
+    }
+    return { ok: true, value: { kind: "other", value: kind.value } };
 }
 // ── 「名 → 串」记录的读法(`env` / `headers`)────────────────────────────────────────────────────────
 /** 引擎的声明收据不收的成员名(core `mcp-server-spec`:按赋值拷贝它会变成原型):JSON 文本铸得出这个**自有**键,对象字面量写不出。 */
 const RESERVED_MEMBER_NAME = "__proto__";
 const RESERVED_MEMBER_FAULT = `no member of a declaration may be named "${RESERVED_MEMBER_NAME}"`;
+/** 记录不交时 `detail` 的前半句:它是哪一种不朴素(null / 数组 / 原始值各一句,对象里的非朴素一句)。`shape` 穷举 —— 新词不补 = 编译红。 */
+function notPlainDetail(shape, v) {
+    switch (shape) {
+        case "null":
+            return "got null";
+        case "array":
+            return "got an array";
+        case "primitive":
+            return `got a ${typeof v}`;
+        case "uninspectable":
+            return `got ${UNINSPECTABLE}`; // 读形状就抛(已撤销的 Proxy):全包唯一的「检视不了」那句
+        case "non_plain_object":
+            if (typeof v === "function")
+                return "got a function"; // 函数归 non_plain_object,句子仍是 14.5.0 的那一句
+            return "got an object that is not plain data (a class instance, a Map, process.env, or any object whose prototype has a prototype of its own; copy it into a plain object)";
+        default: {
+            const unhandled = shape;
+            throw new Error(`notPlainDetail: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
 /**
- * 读一份「名 → 串」记录。记录交不交:是对象(不是数组 / `null`),原型是 `Object.prototype` 或 `null`(纯数据:`Map`、`Set`、类实例、建在原型上的记录都不是),
- * 且每个成员的值都是串。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算 —— 引擎的收据按全部自有属性名读),值按属性描述读:数据属性取值,访问器调一次(访问器或描述 trap 抛了同判为坏)。
+ * 读一份「名 → 串」记录。记录交不交:是朴素 JSON 对象(座位的判据,见 `./plain-json-object`:原型是 `null`,或原型自己的原型是 `null`;纯数据 —— `Map`、`Set`、类实例、建在原型上的记录都不是),
+ * 且每个成员的值都是串。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算 —— 引擎的收据按全部自有属性名读),值经内核 `readKey` 读(一份描述符:数据属性取值,访问器调一次,不问 `get` 陷阱;访问器或描述 trap 抛了同判为坏)。
  * 读原型与成员名时代理 trap 抛了 ⇒ 整张不交(读器对调用方递来的任何对象都不抛;`JSON` 存体里不会有代理,这条只落在直接调读器的嵌入方身上)。
  * 交出去的是副本(原型 `Object.prototype`、成员全可枚举),调用方的对象不被交出去、也不被改;名叫 `__proto__` 的成员不进副本,`reservedMember` 记下它。
  * 名叫 `__proto__` 而值也坏的成员,句子一次说全两件事(名坏在前、值坏并列):调用方照值改完再撞第二条是两步才改对。
  */
 function readPlainStringRecord(v) {
-    if (v === null || typeof v !== "object" || Array.isArray(v))
-        return { ok: false, fault: "not_plain_record", detail: v === null ? "got null" : Array.isArray(v) ? "got an array" : `got a ${typeof v}` };
-    let proto;
-    let names;
-    try {
-        proto = Object.getPrototypeOf(v);
-        names = Object.getOwnPropertyNames(v);
-    }
-    catch {
-        // 代理的 trap 抛了:读不出原型与成员名的对象不是纯数据。读器不抛出去 —— 重放存量提交体的腿被一次抛错砖死比整键不交糟,而「整键不交」是响亮的(进 `lost`)。
-        return { ok: false, fault: "not_plain_record", detail: "got an object that could not be inspected (a proxy trap threw)" };
-    }
-    if (proto !== Object.prototype && proto !== null) {
-        return { ok: false, fault: "not_plain_record", detail: "got an object that is not plain data (a class instance, a Map, process.env, or a record built on a prototype; copy it into a plain object)" };
-    }
-    const record = {};
+    // 形状归座位旁的分类(不在这里再推一遍;座位总 —— 读形状就抛的对象答 `uninspectable`)。成员名的读取(`ownKeys` 陷阱抛)读不出的对象也不是纯数据。
+    // 读器不抛出去 —— 重放存量提交体的腿被一次抛错砖死比整键不交糟,而「整键不交」是响亮的(进 `lost`)。检视律与句都在 `inspect`。
+    const shape = jsonShapeOf(v);
+    if (shape !== "plain")
+        return { ok: false, fault: "not_plain_record", detail: notPlainDetail(shape, v) };
+    const namesRead = inspect(() => Object.getOwnPropertyNames(v));
+    if (!namesRead.ok)
+        return { ok: false, fault: "not_plain_record", detail: `got ${namesRead.sentence}` };
+    const names = namesRead.value;
+    // 累加器是零原型的袋、成员用 `Object.defineProperty` + 零原型描述符写(定义语义,不走 [[Set]]),最后用对象展开(同为定义语义)铸成普通对象:原型上被污染成只读的同名键不让读器抛,
+    // 原型上的数字键 setter 吞不掉成员(此前 `entries.push` + `Object.fromEntries` 被继承的数字键 getter / setter 弄抛)
+    const members = Object.create(null);
     let reservedMember = false;
     for (const name of names) {
-        let value;
-        let unreadable = false;
-        try {
-            const d = Object.getOwnPropertyDescriptor(v, name);
-            value = d === undefined ? undefined : Object.hasOwn(d, "value") ? d.value : d.get === undefined ? undefined : Reflect.apply(d.get, v, []);
-        }
-        catch {
-            unreadable = true;
-        }
+        // 成员经内核读(契约见函数头注):一份描述符里取值 —— 数据属性取值、访问器调一次、从不问 Proxy 的 `get` 陷阱;成员在两次读之间被删掉 ⇒ 不是串(不读继承来的值)
+        const read = readKey(v, name);
+        const unreadable = read.presence === "unreadable";
+        const value = read.presence === "own" ? read.value : undefined;
         if (unreadable || typeof value !== "string") {
             const valueFault = unreadable ? "could not be read (its getter threw)" : `must be a string — got ${describeValueShape(value)}`;
             const reserved = name === RESERVED_MEMBER_NAME;
@@ -232,23 +366,28 @@ function readPlainStringRecord(v) {
         if (name === RESERVED_MEMBER_NAME)
             reservedMember = true;
         else
-            record[name] = value;
+            Object.defineProperty(members, name, dataDescriptor(value));
     }
-    return { ok: true, record, reservedMember };
+    return { ok: true, record: { ...members }, reservedMember };
 }
+/** 把诊断条目铸成数组:`undefined`(这一处没有诊断)略去。`filter` 的结果走 `CreateDataProperty`,不走 `[[Set]]` —— `lost` 是「门拒什么」的读数,不能被继承的数字键 setter 吞掉。 */
+const issuesOf = (...candidates) => candidates.filter((c) => c !== undefined);
 /**
- * `transport.env` / `transport.headers` 的读法(两键同一只):缺席 ⇒ 缺席;记录不交 ⇒ `lost` 一处点名**这个键**(不交的是整张记录;坏在某个成员时句子与 `member` 点名它);
- * 交 ⇒ 纯数据副本,名叫 `__proto__` 的成员在 `lost` 里单记一处、路径 `<键>.__proto__`。
+ * `transport.env` / `transport.headers` 的读法(两键同一只):缺席 ⇒ 缺席;记录不交 ⇒ 一处诊断点名**这个键**(不交的是整张记录;坏在某个成员时句子与 `member` 点名它);
+ * 交 ⇒ 纯数据副本,名叫 `__proto__` 的成员单记一处诊断、路径 `<键>.__proto__`。
  */
-function readTransportRecord(path, raw, lost) {
+function readTransportRecord(path, raw) {
     if (raw === undefined)
-        return undefined;
+        return { record: undefined, issues: [] };
     const read = readPlainStringRecord(raw);
     if (!read.ok) {
-        lost.push({ path, reason: `must be a plain object of string values — ${read.detail}`, ...(read.member !== undefined ? { member: read.member } : {}), fault: read.fault });
-        return undefined;
+        return {
+            record: undefined,
+            issues: [{ path, reason: `must be a plain object of string values — ${read.detail}`, ...(read.member !== undefined ? { member: read.member } : {}), fault: read.fault }],
+        };
     }
-    if (read.reservedMember)
-        lost.push({ path: `${path}.${RESERVED_MEMBER_NAME}`, reason: RESERVED_MEMBER_FAULT, member: RESERVED_MEMBER_NAME, fault: "member_name_reserved" });
-    return read.record;
+    return {
+        record: read.record,
+        issues: read.reservedMember ? [{ path: `${path}.${RESERVED_MEMBER_NAME}`, reason: RESERVED_MEMBER_FAULT, member: RESERVED_MEMBER_NAME, fault: "member_name_reserved" }] : [],
+    };
 }