@sema-agent/settings-schema 14.4.0 → 14.6.0

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,34 +24,60 @@
  * (语义逐字搬),是一项已知待收的分歧。
  */
 import { echoCallerText } from "./caller-text-echo.js";
+import { captureStringArray, dataDescriptor } from "./definition-copy.js";
+import { isPlainJsonObject, jsonShapeOf } from "./plain-json-object.js";
 import { MCP_CONTENT_ORIGINS } from "./types.js";
 import { startsWithHttpScheme } from "./url-shape.js";
 // ── 值的种类描述(拒句只说「你写的是什么形」,不回显值:值可能带凭据、可能任意长)──────────────────────────────────────
-/** 值的**种类**(不回显值本身)。 */
+/** 撤销 / 读不出的 Proxy 的拒句(`got ` 之后的名词短语)—— **全包唯一的一句**:`Array.isArray` 对已撤销的 Proxy 抛 `TypeError`,陷阱抛出来也一样,读器与描述器都不能因此被带出去。 */
+const UNINSPECTABLE = "an object that could not be inspected (a proxy trap threw)";
+/**
+ * 唯一的**安全检视内核**:读器与描述器要碰不可信的值(`Array.isArray` 对已撤销的 Proxy 抛、`get` / 原型陷阱抛、会抛的自有 getter)都经它 ——
+ * 「检视不了」的**律与句都单源**:抛了 ⇒ `ok:false` 带 {@link UNINSPECTABLE} 那一句,不再各处各包一个 try、各写一句。
+ */
+function inspect(read) {
+    try {
+        return { ok: true, value: read() };
+    }
+    catch {
+        return { ok: false, sentence: UNINSPECTABLE };
+    }
+}
+/** 三只描述器的壳:检视抛了就说「检视不了」那一句(经 {@link inspect})。 */
+function inspectSafely(describe) {
+    const read = inspect(describe);
+    return read.ok ? read.value : read.sentence;
+}
+/** 值的**种类**(不回显值本身)。总(不抛):经 {@link inspectSafely}。 */
 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}。 */
+    return inspectSafely(() => {
+        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}。总(不抛):经 {@link inspectSafely}。 */
 export function describeNotStringArray(v) {
-    return Array.isArray(v) ? "an array with a non-string element" : describeValueShape(v);
+    return inspectSafely(() => (Array.isArray(v) ? "an array with a non-string element" : describeValueShape(v)));
 }
-/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。 */
+/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。总(不抛):经 {@link inspectSafely}。 */
 export function describeNotStringRecord(v) {
-    return isRecord(v) ? "an object with a non-string value" : describeValueShape(v);
+    return inspectSafely(() => (isPlainJsonObject(v) ? "an object with a non-string value" : describeValueShape(v)));
 }
-/** 字符串数组(空数组合法)。 */
+/**
+ * 字符串数组(空数组合法)。与传输读器读 `args` 是**同一只读法**(`./definition-copy` 的 `captureStringArray`:按下标、自有下标、一次读、非串即坏、不走迭代协议):
+ * 稀疏数组(洞)、`length` 读不出安全非负整数的数组、读元素时抛的数组都不是 —— 洞不顺原型链读到 `Object.prototype` / `Array.prototype` 上的数字键。
+ */
 export function isStringArray(v) {
-    return Array.isArray(v) && v.every((a) => typeof a === "string");
+    return captureStringArray(v) !== undefined;
 }
 /**
  * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)。与传输读器读 `env` / `headers` 是**同一个**定义
@@ -61,9 +87,6 @@ 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);
-}
 // ── 调用方写的串的回显口径 ──────────────────────────────────────────────────────────────────────────
 /** 句子里点名一个值的写法:{@link echoCallerText} 外加一对双引号;内部的引号与反斜杠逐字(不转义)。 */
 function quotedCallerText(text) {
@@ -120,94 +143,198 @@ export function describeBadContentOrigin(v) {
  * `assertionHeader` 不收。所以读后的形**结构上不可能同带两键**;同设(一份声明给出两个答案)由调用方在读之前对**原始**传输判(判的是写了什么,不是读后留下什么)。
  */
 export function readMcpIdentityHeaders(transport) {
+    const ids = identityFieldsOf(transport);
+    if (!ids.ok)
+        return {}; // 读不出 ⇒ 身份头整体读不出(传输读器对同样的输入是整只不交)
+    const { principalHeader, assertionHeader } = ids.value;
     return {
-        ...(typeof transport.principalHeader === "string" ? { principalHeader: transport.principalHeader } : {}),
-        ...(transport.principalHeader === undefined && typeof transport.assertionHeader === "string" ? { assertionHeader: transport.assertionHeader } : {}),
+        ...(typeof principalHeader === "string" ? { principalHeader } : {}),
+        ...(typeof assertionHeader === "string" ? { assertionHeader } : {}),
     };
 }
+/**
+ * 两个身份头的**唯一读法**(公开读者与传输快照共用):只有 `principalHeader` **干净地读成缺席**时才读 `assertionHeader`;`principalHeader` 在场(不论值形)⇒ `assertionHeader` 一次不读;
+ * 任何一个读不出 ⇒ 整体读不出(`ok:false`,向上传),不折成 `undefined` —— 不然「principal 读不出」会落到 assertion、读它的 getter。
+ */
+function identityFieldsOf(record) {
+    const principal = ownValueOf(record, "principalHeader");
+    if (!principal.ok)
+        return principal;
+    if (principal.value !== undefined)
+        return { ok: true, value: { principalHeader: principal.value, assertionHeader: undefined } };
+    const assertion = ownValueOf(record, "assertionHeader");
+    if (!assertion.ok)
+        return assertion;
+    return { ok: true, value: { principalHeader: undefined, assertionHeader: assertion.value } };
+}
+/** 一个字段的值,**只读自有属性**(`Object.hasOwn`):原型链上的值 / 被污染的 getter 一律当缺席。**自身就是守护读**(经 `inspect`):`getOwnPropertyDescriptor` 陷阱抛、会抛的自有 getter、
+ *  已撤销的 Proxy ⇒ `ok:false`(读不出),调用方各自决定怎么办、不再各包一层。 */
+function ownValueOf(record, key) {
+    return inspect(() => (Object.hasOwn(record, key) ? record[key] : undefined));
+}
+/** 按顺序读若干字段,**第一个读不出的就停**(后面的一个不读),整体读不出向上传。 */
+function ownFieldsOf(record, keys) {
+    const out = Object.create(null);
+    for (const key of keys) {
+        const read = ownValueOf(record, key);
+        if (!read.ok)
+            return read;
+        Object.defineProperty(out, key, dataDescriptor(read.value));
+    }
+    return { ok: true, value: out };
+}
 const transportBad = (path, reason) => ({ ok: false, issue: { path, reason } });
 /**
  * 请求面 `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;
+    // 字段只读一次:同一个检视里把「这一种传输要读的字段」读成局部快照(`get` 陷阱抛的 Proxy / 会抛的自有 getter ⇒ 整只不交,不抛),之后只读快照;这一种传输用不到的字段一次也不读
+    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);
+            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),
+            };
         }
-        return {
-            ok: true,
-            transport: {
-                kind: "http",
-                url: tr.url,
-                ...(headers !== undefined ? { headers } : {}),
-                ...ids,
-            },
-            lost,
-        };
+        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),
+            };
+        }
+        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)}`);
+        }
+    }
+}
+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 } };
     }
-    return transportBad("transport.kind", `must be "stdio" or "http" — got ${describeValueShape(tr.kind)}`);
+    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`、类实例、建在原型上的记录都不是),
+ * 读一份「名 → 串」记录。记录交不交:是朴素 JSON 对象(座位的判据,见 `./plain-json-object`:原型是 `null`,或原型自己的原型是 `null`;纯数据 —— `Map`、`Set`、类实例、建在原型上的记录都不是),
  * 且每个成员的值都是串。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算 —— 引擎的收据按全部自有属性名读),值按属性描述读:数据属性取值,访问器调一次(访问器或描述 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;
@@ -232,23 +359,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" }] : [],
+    };
 }

package/dist/node.d.ts

@@ -9,5 +9,6 @@ export * from "./file-edit.js";
 export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js";
-export { migrateConfigDirectory, type ConfigDirectoryDocument, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type MigrateConfigDirectoryOptions } from "./config-dir-migration.js";
+export { migrateConfigDirectory, migrateConfigDocuments, // 14.5.0:同一段「迁 → 整域终判」的同步口(入参是已有的存量文档,无 io)—— 目录形调的就是它的内核
+type ConfigDirectoryDocument, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type ConfigDocumentsMigration, type MigrateConfigDirectoryOptions, type MigrateConfigDocumentsOptions, } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js";

package/dist/node.js

@@ -10,5 +10,6 @@ export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js"; // R7 self-wake scheduler store — fs binding of the ./scheduler-store contract
 // 目录形的一次性迁移(读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件)—— 语义只此一处,命令行是它的渲染器、引擎起服调同一只。显式列名:该模块的包内私有件(出门形/拼路径)不外泄。
-export { migrateConfigDirectory } from "./config-dir-migration.js";
+export { migrateConfigDirectory, migrateConfigDocuments, // 14.5.0:同一段「迁 → 整域终判」的同步口(入参是已有的存量文档,无 io)—— 目录形调的就是它的内核
+ } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js"; // 上面那只函数的真 I/O 绑定:node:fs + 本包唯一的原子写器(config-document 模式规则)