@sema-agent/server 7.139.0 → 7.141.0

package/dist/session-sync.js

@@ -1,4 +1,5 @@
-import { classifySyncRelationship } from "./session-sync-kernel.js";
+import { anchorEntryDeclared, classifySyncRelationship } from "./session-sync-kernel.js";
+import { recordFailOpen } from "./observability/fail-open.js";
 import { loosenReasons, normalizeRules } from "@sema-agent/core";
 import { headReadOf } from "./session-incarnation.js";
 import { judgeSessionRulesWrite } from "@sema-agent/core";
@@ -60,8 +61,14 @@ export async function replayFileHistory(store, scope, envelope, srcGetBlob, opts
 function ownerAware(backend) {
     return backend.session();
 }
+const DIAG_VALUE_MAX = 96;
+function brief(value) {
+    return JSON.stringify(value.length > DIAG_VALUE_MAX ? `${value.slice(0, DIAG_VALUE_MAX)}…(${value.length} chars)` : value);
+}
 export async function exportSessionManifest(sessionId, srcBackend, historyStore) {
     const session = ownerAware(srcBackend);
+    const anchorStore = srcBackend.resumeAnchor();
+    const anchors = await anchorStore.listBySession(sessionId);
     const listEntryIds = session.listEntryIds?.bind(session);
     if (!listEntryIds)
         return null;
@@ -76,15 +83,20 @@ export async function exportSessionManifest(sessionId, srcBackend, historyStore)
     const policy = typeof policyStore.listBySession === "function"
         ? await policyStore.listBySession(sessionId)
         : [];
-    const anchorStore = srcBackend.resumeAnchor();
-    const anchors = await anchorStore.listBySession(sessionId);
     const summaryOf = session.sessionSummaryOf?.bind(session);
     if (summaryOf === undefined)
         throw new Error("exportSessionManifest: the session store has no row read face (sessionSummaryOf) — the sessionSync fact should have refused this deployment");
     const row = await summaryOf(sessionId);
     const getBlob = blobGetterOf(fs);
+    const declared = new Set(entryIds);
+    const soundAnchors = anchors.filter((a) => {
+        if (anchorEntryDeclared(declared, a.entryId))
+            return true;
+        recordFailOpen("server.session-sync.dangling-anchor-export", `sessionId=${brief(sessionId)} eventId=${brief(a.eventId)} entryId=${brief(a.entryId)}`);
+        return false;
+    });
     return {
-        manifest: { sessionId, entryIds, entryCount: entryIds.length, leafId, fileHistory, policy, anchors, ...(row !== undefined ? { title: row.title, pinned: row.pinned } : {}) },
+        manifest: { sessionId, entryIds, entryCount: entryIds.length, leafId, fileHistory, policy, anchors: soundAnchors, ...(row !== undefined ? { title: row.title, pinned: row.pinned } : {}) },
         getBlob,
     };
 }

package/dist/sql-engine-coordinates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 一只 SQL 引擎「开店所需的坐标」—— 单一来源(纯叶,零依赖)。
+ *
+ * ## 病
+ * 显式 `DB_BACKEND=pg|mysql` 是运维在说「我要这只持久引擎」。可是坐标缺席时,起服在三种 `SESSION_BACKEND` 写法下走三条路:
+ * 未设 / `mysql` ⇒ 读坐标抛 `missing required env`(响亮);`auto` ⇒ 「坐标不在就不探测」,**静默落内存**,姿态位却照报 `declared: "pg"` ——
+ * 一个自以为在持久化的部署跑在内存里,`/health` 照样 200。`REQUIRE_PRINCIPAL=true` 同形。同一个声明,拒不拒取决于第二个旋钮怎么写。
+ *
+ * ## 药
+ * 声明 ∧ 坐标缺席 ⇒ 配置期拒启,**不看** `SESSION_BACKEND`(判官在 `config.ts` 的 store 域,一只):三种写法同一句拒句,
+ * 拒句点名缺的坐标**键名**(不回显值,也读不到值)与两条出路。本模块只出两样东西:各引擎的必需坐标键表,与按这张表铸的两句话
+ * ({@link buildDeclaredEngineWithoutCoordinatesRefusal} 给配置判官、{@link buildSqlPoolMissingRefusal} 给 `boot/stores.ts` 的记忆引擎同池门)。
+ *
+ * ## 为什么键表在这里、`config.ts` 的 `env("MYSQL_HOST")` 读法不动
+ * 配置目录的对账门按名字面扫 `env("NAME")` 与 `process.env.NAME`,把读法改成按表取名会让它看不见这些键;所以两块 `env()` 读仍是字面读,
+ * 本表与它们的一致由 `test/sql-engine-coordinates.test.ts` 的源码钉守(表里每个键在 `config.ts` 里恰有一处 `env("KEY")` 必需读)。
+ */
+/** SQL 引擎词(`DB_BACKEND` 闭集里的两只持久引擎;`local` / `memory` 没有坐标)。 */
+export type SqlEngine = "mysql" | "pg";
+/**
+ * 每只引擎开店**必需**的坐标键(缺一 `config.ts` 的对应块抛 `missing required env`)。可选键(`*_PORT` / `*_PASSWORD` / `*_POOL_SIZE`)不在表里 ——
+ * 它们缺席有缺省,不是「没有坐标」。主机键是首位:它是「SQL 信号」与 `auto` 探测的唯一判据(`config.ts` `dbHostSet`)。
+ */
+export declare const SQL_ENGINE_COORDINATE_KEYS: {
+    readonly mysql: readonly ["MYSQL_HOST", "MYSQL_USER", "MYSQL_DATABASE"];
+    readonly pg: readonly ["PG_HOST", "PG_USER", "PG_DATABASE"];
+};
+/** 该引擎的主机键(`SQL_ENGINE_COORDINATE_KEYS` 的首位)。 */
+export declare function sqlEngineHostKey(engine: SqlEngine): string;
+/** 必需坐标键里此刻缺席(未设或空串 —— 空串在本仓一律等同未设)的那几个,表序。只读键名,不读值。 */
+export declare function missingSqlCoordinateKeys(engine: SqlEngine, env: NodeJS.ProcessEnv): readonly string[];
+/**
+ * 显式 `DB_BACKEND=<engine>` 而该引擎的坐标缺席 ⇒ 配置期拒启句(唯一铸点;**与 `SESSION_BACKEND` 无关**,所以句子里没有它)。
+ * `missing` 是 {@link missingSqlCoordinateKeys} 的读数(此时至少含主机键)。
+ */
+export declare function buildDeclaredEngineWithoutCoordinatesRefusal(engine: SqlEngine, missing: readonly string[]): string;
+/**
+ * 记忆引擎要绑 `<engine>` 的池而店后端没给 ⇒ `boot/stores.ts` 的拒句。记忆持久面的 SQL 方言词与店的引擎词是**同一个字**(`MEMORY_ENGINE_BACKEND=pg|mysql`
+ * ↔ `DB_BACKEND=pg|mysql`),所以拒句只收引擎词。分两形(`DB_BACKEND` 是否已经点名该引擎):
+ *  · 没点名 ⇒ 缺的是声明:`MEMORY_ENGINE_BACKEND=<engine>` 要 `DB_BACKEND=<engine>`;
+ *  · 已点名 ⇒ 声明没缺,「要 DB_BACKEND=<engine>」指错了修法 —— 点名真正开店的两个条件(持久会话后端、必需坐标)与此刻缺的坐标键。
+ *    坐标缺席本身在配置期已被 {@link buildDeclaredEngineWithoutCoordinatesRefusal} 拒掉,走到这里的已点名形 = 坐标齐(或只缺非主机键)而会话后端是 `memory`。
+ */
+export declare function buildSqlPoolMissingRefusal(args: {
+    readonly engine: SqlEngine;
+    readonly declared: boolean;
+    readonly missing: readonly string[];
+}): string;
+//# sourceMappingURL=sql-engine-coordinates.d.ts.map

package/dist/sql-engine-coordinates.js

@@ -0,0 +1,27 @@
+export const SQL_ENGINE_COORDINATE_KEYS = {
+    mysql: ["MYSQL_HOST", "MYSQL_USER", "MYSQL_DATABASE"],
+    pg: ["PG_HOST", "PG_USER", "PG_DATABASE"],
+};
+export function sqlEngineHostKey(engine) {
+    return SQL_ENGINE_COORDINATE_KEYS[engine][0];
+}
+export function missingSqlCoordinateKeys(engine, env) {
+    return SQL_ENGINE_COORDINATE_KEYS[engine].filter((key) => env[key] === undefined || env[key] === "");
+}
+const ENGINE_LABEL = { mysql: "MySQL-protocol", pg: "PostgreSQL" };
+export function buildDeclaredEngineWithoutCoordinatesRefusal(engine, missing) {
+    const required = SQL_ENGINE_COORDINATE_KEYS[engine];
+    return (`DB_BACKEND=${engine} declares the ${ENGINE_LABEL[engine]} engine, but its connection coordinates are not set (missing: ${missing.join(", ")}) — ` +
+        `no session store can open, so the deployment would run IN MEMORY while declaring a durable engine. ` +
+        `Refusing to boot rather than starting non-durable under that declaration (whatever SESSION_BACKEND says). ` +
+        `To persist: set ${required.join(", ")} (optional: ${engine === "pg" ? "PG_PORT, PG_PASSWORD" : "MYSQL_PORT, MYSQL_PASSWORD"}); ` +
+        `to run without SQL: DB_BACKEND=local (single-user file store) or DB_BACKEND=memory.`);
+}
+export function buildSqlPoolMissingRefusal(args) {
+    const { engine, declared, missing } = args;
+    if (!declared)
+        return `MEMORY_ENGINE_BACKEND=${engine} requires DB_BACKEND=${engine} (the memory engine binds the same ${ENGINE_LABEL[engine]} pool) — refusing to start half-configured`;
+    return (`MEMORY_ENGINE_BACKEND=${engine} binds the ${ENGINE_LABEL[engine]} pool of the deployment's store, but none is open although the effective DB_BACKEND is ${engine}: the SQL store opens only under a durable session backend (SESSION_BACKEND unset, mysql or auto — not memory) ` +
+        `with ${SQL_ENGINE_COORDINATE_KEYS[engine].join(", ")} set${missing.length > 0 ? ` (not set now: ${missing.join(", ")})` : ""} — refusing to start half-configured`);
+}
+//# sourceMappingURL=sql-engine-coordinates.js.map

package/dist/sql-engine-posture.d.ts

@@ -38,7 +38,7 @@ export declare function sqlPoolsOf(backend: Pick<StoreBackend, "mysqlPool" | "pg
     pgPool: PgPool | undefined;
 };
 /**
- * `ServiceDeps.sqlEngine` 座的**值形**判:`{ dialect: "tidb" | "pg", facts }`,`facts` 是 `null`(池上连接初始化还没成功)或一份引擎事实 —— 判到墙判官 `sqlWallsOf` 读的那几位
+ * `ServiceDeps.sqlEngine` 座的**值形**判:`{ dialect: "mysql" | "pg", facts }`,`facts` 是 `null`(池上连接初始化还没成功)或一份引擎事实 —— 判到墙判官 `sqlWallsOf` 读的那几位
  * (`maxRowBytes` / `maxPacketBytes` 是 `null` 或数,`wallSources` 两位是出处词)。一个函数(7.131.x 的事实读口 `() => facts` 只改了键名)、缺 `facts` 的对象、错方言词都不是它。
  * `facts` 是活读(getter):这里读一次,判的是装配这一刻看得到的那一份。
  */

package/dist/sql-engine-posture.js

@@ -2,7 +2,7 @@ import { mysqlDriver, pgDriver } from "./plugins/sql-driver.js";
 export function sqlPoolsOf(backend) {
     return { mysqlPool: backend?.mysqlPool?.(), pgPool: backend?.pgPool?.() };
 }
-const DIALECT_WORDS = { tidb: true, pg: true };
+const DIALECT_WORDS = { mysql: true, pg: true };
 const WALL_SOURCE_WORDS = { reported: true, assumed: true };
 const isWallBytes = (v) => v === null || (typeof v === "number" && Number.isFinite(v) && v >= 0);
 const isWallSourceWord = (v) => typeof v === "string" && Object.hasOwn(WALL_SOURCE_WORDS, v);

package/dist/standing-answer-grant.d.ts

@@ -1,3 +1,23 @@
+/**
+ * 站着的答案的**授予绑定**的唯一读口:这一问的应答授不授予「这一次调用」之外的东西,授予的话绑定是什么。
+ *
+ * 站着的答案(活的「本会话放行」、耐久的 `remember:"session"`)记下的是**上一次**应答;它只配代答「上一次应答覆盖得到」的问。
+ * 有一类卡的应答还**授予**别的东西:批准引擎的 `Skill` = 激活那只技能 + 本 run 内它 `allowedTools` 上的工具免问。这类卡的答案只能按
+ * 「工具 + 授予绑定」记、只代答绑定相同的问(core 原句「an answer is remembered by "this tool + this binding"」)。判据本身在
+ * `tool-approval.ts` 的 `standingAnswerHome`(本读口是它的一位);本文件只回答「授不授予、绑定是什么」,是叶模块。
+ *
+ * 🔴 **一条律:只读引擎的词,载体不论**。引擎的绑定工厂给一次调用的每一个载体盖**同一组词**、恰带一臂:`boundGrantDigest`(对引擎 `Skill` 工具的
+ * 激活:技能名 + 两只清单规范拼写的摘要)或 `boundGrantAbsence`(闭集 core `BOUND_GRANT_ABSENCES`:`not_bindable` = 不绑任何授予 / `unreadable` = 绑着却读不出)。
+ * 载体 = 活的 `AskRequest`、停驻行 `PendingAction.tool_approval`、读这两者的运维队列行 / inbox 行,以及 core 7.59.0 起 Runner 交给策略层的 `ToolCallRequest`
+ * (部署名单门、workflow 问句门在交出自己的问之前读它)。读法与 core 自己的 inbox 投影逐臂同一条:摘要是串 ⇒ `bound`;否则摘要不在且词是 `not_bindable`
+ * ⇒ `none`;其余(词是 `unreadable`、摘要在而不是串、集外词、两者都不说)⇒ `unreadable`。**不读工具名**。
+ *  · 两者都不说的载体:7.51.0 之前停驻的行(core:「it does not say」)、宿主不经 Runner 自建的请求 —— 读作 `unreadable`:不可记、不被代答(fail-closed)。
+ *  · 读面上的那一臂({@link grantBindingArm})是本读口的逆像:停驻行的运维队列行 / `/stream` 的 `pending` 帧投的就是 `grantBindingArm(grantBindingOf(行))` ——
+ *    恰带摘要与缺席词之一,与 core 投收件箱行的那一臂同值;卡上显示的臂与「本会话放行」记不记得住由同一次读定,不会两答。
+ *  · 部署名单自己的问(答案记在 server 的会话豁免店,按 (会话, 工具名))的写侧、名单门的读侧、豁免列表三处读同一组词 —— 7.129.0–7.137.x 读侧手里的请求
+ *    不带词,三处只好按工具名读调用载体;那只读口随 core 7.59.0 退役。
+ */
+import type { BoundGrantAbsence } from "@sema-agent/core";
 /** 载体:引擎给一次调用盖过绑定词的任何形(活的 `AskRequest`、停驻行的 `tool_approval` 臂、运维队列行、策略层的 `ToolCallRequest` 都结构上满足)。 */
 export interface StandingAnswerCard {
     readonly boundGrantDigest?: unknown;
@@ -12,6 +32,15 @@ export type GrantBinding = {
 } | {
     readonly kind: "unreadable";
 };
-/** 载体上的授予绑定 —— 只读引擎的词(读法见文件头注):摘要是串 ⇒ bound;摘要不在且词是 `not_bindable` ⇒ none;其余 ⇒ unreadable。 */
-export declare function grantBindingOf(card: StandingAnswerCard): GrantBinding;
+/** 载体上的授予绑定 —— 只读引擎的词(读法见文件头注):摘要是串 ⇒ bound;摘要不在且词是 `not_bindable` ⇒ none;其余 ⇒ unreadable。
+ *  形参是任意对象(载体不论):读自持久层的停驻行(运维队列行的投影、`/decide` 的原始行)两座都按 `unknown` 读,结构上满足 {@link StandingAnswerCard} 的载体照传。 */
+export declare function grantBindingOf(card: StandingAnswerCard | object): GrantBinding;
+/** 授予绑定在读面上的形:恰一臂 —— 摘要,或缺席词(闭集 core `BOUND_GRANT_ABSENCES`)。 */
+export type GrantBindingArm = {
+    readonly boundGrantDigest: string;
+} | {
+    readonly boundGrantAbsence: BoundGrantAbsence;
+};
+/** {@link GrantBinding} 投回读面的那一臂(逐臂穷尽:core 给绑定加一态而这里不跟 ⇒ 编译红):bound ⇒ 摘要;none ⇒ `not_bindable`;unreadable ⇒ `unreadable`。 */
+export declare function grantBindingArm(binding: GrantBinding): GrantBindingArm;
 //# sourceMappingURL=standing-answer-grant.d.ts.map

package/dist/standing-answer-grant.js

@@ -1,8 +1,20 @@
 const NOT_BINDABLE = "not_bindable";
+const UNREADABLE = "unreadable";
 export function grantBindingOf(card) {
-    const digest = card.boundGrantDigest;
+    const digest = "boundGrantDigest" in card ? card.boundGrantDigest : undefined;
     if (typeof digest === "string")
         return { kind: "bound", digest };
-    return digest === undefined && card.boundGrantAbsence === NOT_BINDABLE ? { kind: "none" } : { kind: "unreadable" };
+    const word = "boundGrantAbsence" in card ? card.boundGrantAbsence : undefined;
+    return digest === undefined && word === NOT_BINDABLE ? { kind: "none" } : { kind: "unreadable" };
+}
+export function grantBindingArm(binding) {
+    switch (binding.kind) {
+        case "bound":
+            return { boundGrantDigest: binding.digest };
+        case "none":
+            return { boundGrantAbsence: NOT_BINDABLE };
+        case "unreadable":
+            return { boundGrantAbsence: UNREADABLE };
+    }
 }
 //# sourceMappingURL=standing-answer-grant.js.map

package/dist/store-posture.d.ts

@@ -8,7 +8,7 @@
  *
  * ## 形
  * `declared` = 运维的声明(`DB_BACKEND` 词,含缺省推导);`backend` = **装配出的**后端 kind(没装出后端 = `memory`);两者不等是合法的
- * 形(`DB_BACKEND=pg` + `SESSION_BACKEND=memory` = 声明 pg、刻意不持久;缺省推导 local 起不来)—— 两位都上 wire,
+ * 形(`DB_BACKEND=pg` + 坐标在场 + `SESSION_BACKEND=memory` = 声明 pg、刻意不持久 —— 坐标缺席的声明在配置期拒启,见 `sql-engine-coordinates.ts`;缺省推导 local 起不来)—— 两位都上 wire,
  * 由调用方自己读出落差。`degradedReason` present-iff 降级臂走过(按后端族定词,{@link storeDegradedReasonFor})。
  * 顶层 `sql` 并入 `store.sql`(硬 breaking,零别名;对象逐字同形)。
  */

package/dist/{plugins → stores-sql}/background-agent-store-sql.d.ts

@@ -31,8 +31,8 @@
  */
 import type { Pool } from "mysql2/promise";
 import { type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentStore } from "@sema-agent/core";
-import type { PgQueryFn } from "./pg-query.js";
-import { type IndexSpec } from "./ensure-index.js";
+import type { PgQueryFn } from "../plugins/pg-query.js";
+import { type IndexSpec } from "../plugins/ensure-index.js";
 export declare const BACKGROUND_AGENT_TABLE = "background_agent";
 type ReapOpts = {
     maxAgeMs?: number;

package/dist/{plugins → stores-sql}/background-agent-store-sql.js

@@ -1,8 +1,8 @@
 import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, } from "@sema-agent/core";
-import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
-import { isMysqlDupKeyError } from "./sql-errors.js";
-import { ensureIndexes } from "./ensure-index.js";
-import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
+import { pgSafeJsonStringify, pgSanitizeText } from "../plugins/pg-safe-json.js";
+import { isMysqlDupKeyError } from "../plugins/sql-errors.js";
+import { ensureIndexes } from "../plugins/ensure-index.js";
+import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText } from "../plugins/sql-json-column.js";
 import { backgroundAgentNameOf } from "../background-agent-name.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
 function summaryCols(dialect) {
@@ -215,7 +215,7 @@ export class TiDBBackgroundAgentStore {
         }
     }
     async get(handle, scope) {
-        const [rows] = (await this.pool.query(`SELECT ${jsonColumnText("tidb", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]));
+        const [rows] = (await this.pool.query(`SELECT ${jsonColumnText("mysql", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]));
         return rows.length > 0 ? readRecordColumn(rows[0].record_json, handle) : null;
     }
     async update(handle, scope, record, expect) {
@@ -234,12 +234,12 @@ export class TiDBBackgroundAgentStore {
         return res.affectedRows === 1;
     }
     async listBySession(scope, sessionId, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${summaryCols("tidb")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
+        const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
        ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]));
         return rows.map(rowToSummary);
     }
     async listByScope(scope, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${summaryCols("tidb")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
+        const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
        ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]));
         return rows.map(rowToSummary);
     }
@@ -252,7 +252,7 @@ export class TiDBBackgroundAgentStore {
             return 0;
         const flipped = new Set();
         if (opts.staleRunningMaxAgeMs !== undefined) {
-            const [stale] = (await this.pool.query(`SELECT handle, ${jsonColumnText("tidb", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
+            const [stale] = (await this.pool.query(`SELECT handle, ${jsonColumnText("mysql", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
             for (const row of stale) {
                 const live = readRecordColumn(row.record_json, String(row.handle));
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))

package/dist/{plugins → stores-sql}/session-policy-store-sql.d.ts

@@ -1,9 +1,8 @@
 import { type SessionPolicyStore, type SessionPermissionRules, type StoredSessionRules, type SessionRulesRecord, type PutRulesOptions } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type JsonColumnShape } from "./sql-json-column.js";
-import { type SqlDriver } from "./sql-driver.js";
-import type { Logger } from "../observability/logger.js";
+import { type JsonColumnShape } from "../plugins/sql-json-column.js";
+import { type SqlDriver } from "../plugins/sql-driver.js";
 /** `session_policy.policy_key` 的**唯一铸造点**(core 复合键的 sha256)。
  *
  *  🔴 导出而不是让收编腿再抄一份(clay 宪法「schema 单一属主禁复制」):[ref] form b 的身份重绑要
@@ -45,8 +44,11 @@ export type StoredSessionRulesBody = SessionPermissionRules & Pick<StoredSession
  * + 恰好解一次 `decodeJsonColumn` + 折码 `foldJsonColumn`);本店只留「形判据是哪一只」与「坏体折成哪个码」。
  */
 export declare function readSessionRulesBody(body: unknown): JsonColumnShape<StoredSessionRulesBody>;
-/** 本店唯一的日志口:抹除封键那一臂([ref])的点名。缺席 ⇒ 退回 `console.warn`(不静默)。 */
-export type SessionPolicyStoreLogger = Pick<Logger, "warn">;
+/** 本店唯一的日志口:抹除封键那一臂([ref])的点名。缺席 ⇒ 退回 `console.warn`(不静默)。
+ *  结构型,与服务日志口的 `warn` 逐位同形:本目录对服务的观测模块零依赖(目录的可搬性),服务的日志口照样直接交进来。 */
+export type SessionPolicyStoreLogger = {
+    warn(msg: string, fields?: Record<string, unknown>): void;
+};
 /** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     private readonly db;

package/dist/{plugins → stores-sql}/session-policy-store-sql.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { judgeSessionRulesWrite, readSessionRulesShape, SessionPolicyError } from "@sema-agent/core";
-import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
-import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText } from "./sql-json-column.js";
-import { pgHasUnstorable } from "./pg-safe-json.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isDeadlockError, isDupKeyError } from "./sql-errors.js";
+import { SESSION_RULES_COLUMN } from "../plugins/session-rules-column.js";
+import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText } from "../plugins/sql-json-column.js";
+import { pgHasUnstorable } from "../plugins/pg-safe-json.js";
+import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
+import { isDeadlockError, isDupKeyError } from "../plugins/sql-errors.js";
 export const policyKeyFor = (sessionId, principal) => createHash("sha256").update(JSON.stringify([sessionId, principal ?? null])).digest("hex");
 const policyKey = policyKeyFor;
 const RETRY_LIMIT = 8;
@@ -63,15 +63,15 @@ export class SqlSessionPolicyStore {
         this.db = db;
         this.logger = logger;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     isDupKey(e) {
         return isDupKeyError(this.db.dialect, e);
     }
     async getRules(sessionId, principal) {
         const key = policyKey(sessionId, principal);
-        const { rows } = await this.db.query(this.q(`SELECT 'row' AS src, ${jsonColumnText("tidb", RULES)}, rev, gen FROM session_policy WHERE policy_key = ?` +
+        const { rows } = await this.db.query(this.q(`SELECT 'row' AS src, ${jsonColumnText("mysql", RULES)}, rev, gen FROM session_policy WHERE policy_key = ?` +
             " UNION ALL SELECT 'seal', NULL, rev, gen FROM session_policy_rev_mark WHERE policy_key = ? AND rev = ?", `SELECT 'row' AS src, ${jsonColumnText("pg", RULES)}, rev, gen FROM session_policy WHERE policy_key = $1` +
             " UNION ALL SELECT 'seal', NULL, rev, gen FROM session_policy_rev_mark WHERE policy_key = $2 AND rev = $3"), [key, key, SEALED_MARK_REV]);
         if (rows.some((r) => r.src === "seal"))
@@ -82,7 +82,7 @@ export class SqlSessionPolicyStore {
         return rowToStored(row, `for session ${JSON.stringify(sessionId)}`);
     }
     async listBySession(sessionId) {
-        const { rows } = await this.db.query(this.q(`SELECT 'row' AS src, principal, ${jsonColumnText("tidb", RULES)}, rev, gen FROM session_policy WHERE session_id = ?` +
+        const { rows } = await this.db.query(this.q(`SELECT 'row' AS src, principal, ${jsonColumnText("mysql", RULES)}, rev, gen FROM session_policy WHERE session_id = ?` +
             " UNION ALL SELECT 'seal', NULL, NULL, rev, gen FROM session_policy_rev_mark WHERE session_id = ? AND rev = ?", `SELECT 'row' AS src, principal, ${jsonColumnText("pg", RULES)}, rev, gen FROM session_policy WHERE session_id = $1` +
             " UNION ALL SELECT 'seal', NULL, NULL, rev, gen FROM session_policy_rev_mark WHERE session_id = $2 AND rev = $3"), [sessionId, sessionId, SEALED_MARK_REV]);
         if (rows.some((r) => r.src === "seal"))
@@ -95,7 +95,7 @@ export class SqlSessionPolicyStore {
     async putRules(sessionId, principal, rules, opts) {
         const key = policyKey(sessionId, principal);
         return this.retrying(() => this.tx(async (conn) => {
-            const { rows } = await conn.query(this.q(`SELECT ${jsonColumnText("tidb", RULES)}, rev, gen FROM session_policy WHERE policy_key = ? FOR UPDATE`, `SELECT ${jsonColumnText("pg", RULES)}, rev, gen FROM session_policy WHERE policy_key = $1 FOR UPDATE`), [key]);
+            const { rows } = await conn.query(this.q(`SELECT ${jsonColumnText("mysql", RULES)}, rev, gen FROM session_policy WHERE policy_key = ? FOR UPDATE`, `SELECT ${jsonColumnText("pg", RULES)}, rev, gen FROM session_policy WHERE policy_key = $1 FOR UPDATE`), [key]);
             const prior = rows[0] ? rowToStored(rows[0], `for session ${JSON.stringify(sessionId)} (pre-write snapshot)`) : undefined;
             const priorRev = prior?.rev ?? 0;
             if (opts?.expectedRev !== undefined && priorRev !== opts.expectedRev) {
@@ -157,12 +157,12 @@ export class SqlSessionPolicyStore {
                     sealedKeys.push({ policyKey: String(r.policy_key), rev: String(r.rev), gen: String(r.gen) });
                 params.push(String(r.policy_key), sessionId, readable ? counters.rev : SEALED_MARK_REV, readable ? counters.gen + 1 : 0, now);
                 const base = params.length - 5;
-                return this.db.dialect === "tidb" ? "(?,?,?,?,?)" : `($${base + 1},$${base + 2},$${base + 3},$${base + 4},$${base + 5})`;
+                return this.db.dialect === "mysql" ? "(?,?,?,?,?)" : `($${base + 1},$${base + 2},$${base + 3},$${base + 4},$${base + 5})`;
             });
             await conn.query(this.q(`INSERT INTO session_policy_rev_mark (policy_key, session_id, rev, gen, erased_at) VALUES ${tuples.join(",")}` +
                 " ON DUPLICATE KEY UPDATE rev = GREATEST(session_policy_rev_mark.rev, VALUES(rev)), gen = GREATEST(session_policy_rev_mark.gen + 1, VALUES(gen)), erased_at = VALUES(erased_at)", `INSERT INTO session_policy_rev_mark (policy_key, session_id, rev, gen, erased_at) VALUES ${tuples.join(",")}` +
                 " ON CONFLICT (policy_key) DO UPDATE SET rev = GREATEST(session_policy_rev_mark.rev, EXCLUDED.rev), gen = GREATEST(session_policy_rev_mark.gen + 1, EXCLUDED.gen), erased_at = EXCLUDED.erased_at"), params);
-            const holes = keys.map((_, i) => (this.db.dialect === "tidb" ? "?" : `$${i + 1}`)).join(",");
+            const holes = keys.map((_, i) => (this.db.dialect === "mysql" ? "?" : `$${i + 1}`)).join(",");
             await conn.query(`DELETE FROM session_policy WHERE policy_key IN (${holes})`, keys);
             return sealedKeys;
         }));

package/dist/{plugins → stores-sql}/usage-window-store-sql.d.ts

@@ -26,7 +26,7 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { UsageWindow, UsageWindowReading, UsageWindowRecord, UsageWindowStore } from "@sema-agent/core";
-import { type JsonColumnShape } from "./sql-json-column.js";
+import { type JsonColumnShape } from "../plugins/sql-json-column.js";
 export declare const USAGE_WINDOW_TABLE = "usage_window";
 /**
  * `usage_window.record` 的**形读者**([ref] 车③a:本店既有的那一份深度判据逐字搬进来,一个字没改判)。

package/dist/{plugins → stores-sql}/usage-window-store-sql.js

@@ -1,5 +1,5 @@
 import { EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord } from "@sema-agent/core";
-import { decodeJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
+import { decodeJsonColumn, foldJsonColumn, jsonColumnText } from "../plugins/sql-json-column.js";
 export const USAGE_WINDOW_TABLE = "usage_window";
 class UsageRecordShapeProblem extends Error {
 }
@@ -84,7 +84,7 @@ export class TiDBUsageWindowStore {
         try {
             await c.beginTransaction();
             await c.query(`INSERT INTO ${USAGE_WINDOW_TABLE} (usage_key, record, updated_at_ms) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE usage_key = usage_key`, [key, JSON.stringify(EMPTY_USAGE_WINDOW_RECORD), at]);
-            const [rows] = (await c.query(`SELECT ${jsonColumnText("tidb", "record")} FROM ${USAGE_WINDOW_TABLE} WHERE usage_key = ? FOR UPDATE`, [key]));
+            const [rows] = (await c.query(`SELECT ${jsonColumnText("mysql", "record")} FROM ${USAGE_WINDOW_TABLE} WHERE usage_key = ? FOR UPDATE`, [key]));
             if (rows.length === 0) {
                 throw new Error(`usage_window row for key "${key}" vanished between ensure and lock — refusing to drop a governance charge`);
             }
@@ -102,7 +102,7 @@ export class TiDBUsageWindowStore {
         }
     }
     async read(key, windows, now) {
-        const [rows] = (await this.pool.query(`SELECT ${jsonColumnText("tidb", "record")} FROM ${USAGE_WINDOW_TABLE} WHERE usage_key = ?`, [key]));
+        const [rows] = (await this.pool.query(`SELECT ${jsonColumnText("mysql", "record")} FROM ${USAGE_WINDOW_TABLE} WHERE usage_key = ?`, [key]));
         const record = rows.length === 0 ? EMPTY_USAGE_WINDOW_RECORD : parseRecord(rows[0].record, key);
         return readUsageRecord(record, windows, now);
     }

package/dist/task-a2a.d.ts

@@ -57,7 +57,7 @@ export declare const A2A_PEER_DISPOSITION: {
     readonly toolAxes: "engine";
 };
 /** 请求体 `a2aPeers[i]` 的键闭集 = 处置表的键(书写序即判序)。 */
-export declare const A2A_PEER_ENTRY_KEYS: readonly ("name" | "headers" | "principalHeader" | "toolAxes" | "url" | "cardUrl" | "allowSkills")[];
+export declare const A2A_PEER_ENTRY_KEYS: readonly ("name" | "headers" | "url" | "principalHeader" | "toolAxes" | "cardUrl" | "allowSkills")[];
 /**
  * **请求入口的一次读**(`boot/resolve-spec.ts` 在腿首铸一份,受理门与读器——续跑重放腿只有读器——都吃这一份):`body.a2aPeers` 若是数组,返回同形数组
  * (每个对象条目换成它的 {@link PeerSnapshot};非对象条目原样;长度保真 —— 界外的条数仍是受理门撞帽拒与读器丢弃留声的依据,只快照界内的条目);不是数组(缺席 / `null` / 别的形)原样返回。

package/dist/task-a2a.js

@@ -8,7 +8,7 @@ import { readRequestToolAxes } from "./request-tool-axes.js";
 import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyNames } from "./request-key-closure.js";
 import { urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential-refusal.js";
 import { declarationEntryNotObject, declarationIssueFacts, declarationNameIssue, declarationOverCapFacts, declaredName, judgeDeclarationKeys, requestDeclarationRefusal, throwDeclarationRefusal, } from "./request-declaration-refusal.js";
-import { principalHeaderOwnershipIssue } from "./task-mcp.js";
+import { sendHeaderOwnershipIssue } from "./task-mcp.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export const MAX_REQUEST_A2A_PEERS = 32;
 export function a2aInjectionHonored(config) {
@@ -52,6 +52,7 @@ function peerUrlIssue(key) {
         return found === undefined ? undefined : { path: key, reason: urlCredentialRefusalReason(found, urlCredentialHeaderExit(`${at}.headers`)), credential: found };
     };
 }
+const A2A_SEND_HEADER_PATHS = { headers: "headers", principalHeader: "principalHeader" };
 const HEADERS_RESERVED_MEMBER_PATH = "headers.__proto__";
 const PEER_SNAPSHOT = Symbol("a2aPeerSnapshot");
 function openCloneNode(v, ancestors) {
@@ -170,11 +171,9 @@ const A2A_PEER_KEY_JUDGES = {
         const reserved = read.stripped[0];
         return reserved === undefined ? undefined : { path: HEADERS_RESERVED_MEMBER_PATH, reason: reserved.fault };
     },
-    principalHeader: (o) => o.principalHeader === undefined
-        ? undefined
-        : typeof o.principalHeader !== "string"
-            ? { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }
-            : principalHeaderOwnershipIssue(o.principalHeader, "a2a", "principalHeader"),
+    principalHeader: (o) => o.principalHeader !== undefined && typeof o.principalHeader !== "string"
+        ? { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }
+        : sendHeaderOwnershipIssue({ headers: o.headers?.ok === true ? o.headers.record : undefined, principalHeader: o.principalHeader }, "a2a", A2A_SEND_HEADER_PATHS),
     allowSkills: (o) => o.allowSkills === undefined || isStringArray(o.allowSkills)
         ? undefined
         : { path: "allowSkills", reason: `must be an array of strings (omit the key to leave the peer's skills unrestricted) — got ${describeNotStringArray(o.allowSkills)}` },

package/dist/task-mcp.d.ts

@@ -71,7 +71,7 @@ export declare const MCP_SERVER_ENTRY_KEYS: readonly ["allowTools", "contentOrig
 /** `transport.kind:"stdio"` 的键闭集 = stdio 臂处置表的键(`env` 是件,其余进声明)。 */
 export declare const STDIO_MCP_TRANSPORT_KEYS: readonly ("env" | "kind" | "args" | "command")[];
 /** `transport.kind:"http"` 的键闭集 = http 臂处置表的键(`headers` 是件,`assertionHeader` 承载不发送,其余进声明)。 */
-export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ("headers" | "kind" | "principalHeader" | "url" | "assertionHeader")[];
+export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ("headers" | "kind" | "url" | "principalHeader" | "assertionHeader")[];
 /**
  * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
  * (deployment-shape row `multiTenant` does not hold) — the requester is the super-admin of their own worker, so their `.mcp.json` is
@@ -158,7 +158,7 @@ export declare function requestEntryIdentityIssue(entry: unknown): McpIdentityHe
  *     `name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = 契约包读器 {@link readRequestMcpTransport} 的纯数据记录读法;`elicitation` = {@link isElicitationFlag};
  *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestMcpTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`;读器在契约包,本仓只据 `lost[0]` 拒、据 `lost` 在重放腿逐处点名);
  *     读器交回的 http `url` 再问「带不带凭据」= 契约包根的 `findUrlCredential`([ref];拒体另带机读 `field` + `reason`,见 {@link transportUrlCredentialIssue});
- *     http `principalHeader` 再问「这个名有没有别的属主」= 引擎包根的 `headerOwnershipCollision`(见 {@link principalHeaderOwnershipIssue})。
+ *     http 这次发送的头集合(件头 + `principalHeader`)再问「有没有一个头名两个属主」= 引擎包根的 `headerOwnershipCollision`(见 {@link sendHeaderOwnershipIssue})。
  * 于是判官受理的条目,读器({@link normalizeServer})交回的就是申报本身(只差判官自己的合法归一:空容器 / `skillScopeEligible:false` 折成缺席、`toolAxes` 取引擎的拷贝)——
  * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(本部署不发送断言,
  * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `specWithholdsMcpAssertionHeader`(开关 `MCP_ASSERTION_HEADER_SENT` 假时「声明了」即「被扣下」),不是第二份判法(见 `readMcpProbeBody`)。
@@ -185,14 +185,27 @@ export declare function requestMcpDeclarationRefusal(list: unknown): Declaration
  * 交出去的剔掉 `__proto__` 名成员),server 照挂,运维 warn `mcp_transport_members_dropped` 逐处点名 —— 续跑重放腿不静默丢声明。
  */
 export declare function assertRequestMcpEntries(bodyMcp: unknown): void;
+/** 一次发送从一份声明里带出的头:件头(调用方原样写的名 → 值,由对端座按原字节作答)与身份头名(引擎按主体写值)。 */
+export interface DeclaredSendHeaders {
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly principalHeader?: string | undefined;
+}
 /**
- * `principalHeader` 的**名**有没有别的属主:判官是引擎包根的 `headerOwnershipCollision`(拨号时判同一条的那一只;这里只问身份头这一个名,件头名由引擎在发送时判)——
- * 名(任何大小写)是这一协议的传输自己写的头(MCP:`mcp-session-id` · `mcp-protocol-version` · `content-type` · `accept` · `last-event-id`;A2A 没有),或是引擎的断言头
- * (`connector-assertion`)⇒ 这一台拨号时必被拒,新提交在门上按名拒。原因句只点名**属主的拼写**(引擎固定表里的规范化小写头名),不回显调用方写的原串 / 大小写形(调用方写的恰是小写时,句里的名与所写相同)。
- * 新提交腿上按名 400(MCP 门表的 `transport`、A2A 判官表的 `principalHeader`)。续跑重放腿不 4xx:MCP 的读器不问它 —— 存量体里这一形照挂,由引擎在拨号时拒那一台、兄弟照挂;
- * A2A 的读器问同一张判官表 —— 这一条对端整条不进、`a2a_injection_dropped` 点名原因(引擎物化时同样拒那一台;结局同,原因说在本仓这一行)。
+ * 一次发送的**头属主** —— 一条规则:这次发送会带的头集合(件头 + 身份头名)只有一只属主判官,引擎包根的 `headerOwnershipCollision`(引擎每次发送时判同一组的那一只);
+ * 受理口用**全部**问它一次。MCP 与 A2A 两座都调这一只:MCP 门表的 `transport` 格,A2A 判官表的 `principalHeader` 格(两键里判序靠后的那一格,读两键的读数)。
+ * 判官答撞 ⇒ 这一台拨号即拒(`config.protocol_header_collision`)或此后每一次发送都被拒(`credential_unavailable`)⇒ 新提交在门上按格 400:
+ *  · 身份头名本身是这一协议的传输自己写的头(MCP:`mcp-session-id` · `mcp-protocol-version` · `content-type` · `accept` · `last-event-id`,任何大小写;A2A 没有),或是引擎的断言头
+ *    (`connector-assertion`)⇒ `paths.principalHeader`;
+ *  · 件头名是传输自己写的头 ⇒ `paths.headers`;件里同一头名两个拼写、件头名撞身份头名 ⇒ `paths.headers`。
+ * 件里名叫 `connector-assertion` 的头不撞(断言头在件里是座的;引擎只在它作身份头名时保留这个名)。原因句只点名**规范化小写**的头名(属主拼写,或调用方所写名字的小写形、经回显清洗),
+ * 不回显调用方的大小写形,从不带值。
+ * 不在本规则里的件形 —— 件值字节(CR / LF / NUL)、头名不是 HTTP token、stdio 变量名 —— 只由引擎内部的答案读器判(包根不导出),受理口没有同一只判官可问,照旧运行期 `credential_unavailable`。
+ * 续跑重放腿不 4xx:MCP 的读器不问门表 —— 存量体里撞属主的那一台照挂,由引擎拨号 / 发送时拒、兄弟照挂;A2A 的读器问同一张判官表 —— 这一条对端整条不进、`a2a_injection_dropped` 点名原因。
  */
-export declare function principalHeaderOwnershipIssue(principalHeader: string | undefined, protocol: "mcp" | "a2a", path: string): DeclarationKeyIssue | undefined;
+export declare function sendHeaderOwnershipIssue(send: DeclaredSendHeaders, protocol: "mcp" | "a2a", paths: {
+    readonly headers: string;
+    readonly principalHeader: string;
+}): DeclarationKeyIssue | undefined;
 /**
  * The ONE predicate for "this MCP server name belongs to the deployment": the scenario baseline (what mounted for
  * this scenario) ∪ every name the deployment DECLARED (`CenterMcp.reservedNames` — mounted or not, any scenario).

package/dist/task-mcp.js

@@ -171,17 +171,25 @@ function transportUrlCredentialIssue(url) {
         return undefined;
     return { path: "transport.url", reason: urlCredentialRefusalReason(found, urlCredentialHeaderExit("transport.headers")), credential: found };
 }
-export function principalHeaderOwnershipIssue(principalHeader, protocol, path) {
-    if (principalHeader === undefined)
-        return undefined;
-    const collision = headerOwnershipCollision({ principalHeader }, protocol);
+export function sendHeaderOwnershipIssue(send, protocol, paths) {
+    const collision = headerOwnershipCollision({ headers: send.headers === undefined ? undefined : { ...send.headers }, principalHeader: send.principalHeader }, protocol);
     if (collision === undefined)
         return undefined;
-    return {
-        path,
-        reason: `names the header "${collision.first}" (header names are case-insensitive), which is not the principal header's to own — it is ${protocol === "mcp" && collision.first !== MCP_ASSERTION_HEADER ? "a header the MCP transport writes itself" : "the engine's connector assertion header"}; name the principal header something of its own`,
-    };
+    if (collision.engineOwned) {
+        const owner = echoKeyName("", collision.first);
+        const ownedBy = collision.first === MCP_ASSERTION_HEADER ? "the engine's connector assertion header" : "a header the MCP transport writes itself";
+        if (collision.second === send.principalHeader) {
+            return { path: paths.principalHeader, reason: `names the header "${owner}" (header names are case-insensitive), which is not the principal header's to own — it is ${ownedBy}; name the principal header something of its own` };
+        }
+        return { path: paths.headers, reason: `carries the header "${owner}" (header names are case-insensitive), which is not this declaration's to send — it is ${ownedBy}; leave it out` };
+    }
+    const name = echoKeyName("", collision.first.toLowerCase());
+    if (collision.first === send.principalHeader || collision.second === send.principalHeader) {
+        return { path: paths.headers, reason: `carries a header named as the principal header "${name}" (header names are case-insensitive) — the engine writes the principal under that name; rename one of them` };
+    }
+    return { path: paths.headers, reason: `carries the header "${name}" under two spellings (header names are case-insensitive) — one send carries one value per header name; keep one` };
 }
+const MCP_SEND_HEADER_PATHS = { headers: "transport.headers", principalHeader: "transport.principalHeader" };
 const ENTRY_KEY_JUDGES = {
     allowTools: (o) => o.allowTools === undefined || isStringArray(o.allowTools)
         ? undefined
@@ -231,7 +239,7 @@ const ENTRY_KEY_JUDGES = {
             return read.lost[0];
         if (read.transport.kind !== "http")
             return undefined;
-        return transportUrlCredentialIssue(read.transport.url) ?? principalHeaderOwnershipIssue(read.transport.principalHeader, "mcp", "transport.principalHeader");
+        return transportUrlCredentialIssue(read.transport.url) ?? sendHeaderOwnershipIssue({ headers: read.transport.headers, principalHeader: read.transport.principalHeader }, "mcp", MCP_SEND_HEADER_PATHS);
     },
 };
 function requestEntryRefusal(entry, at) {