@sema-agent/server 7.138.0 → 7.140.0

package/dist/session-row.d.ts

@@ -1,10 +1,114 @@
+import { type SessionLogMark, type SessionRowExpectation } from "@sema-agent/core";
 /** `title` 列的宽度(字符)= 用户标题的上界。两方言 DDL 内插它。 */
 export declare const SESSION_TITLE_MAX_CHARS = 120;
-/** 会话行的可写位(体闭集;两键至少一键)。会话店唯一写口 `patchSessionMeta` 的形参。`title: null` = 清回自动标题(列写 NULL)。 */
+/** 会话行的可写位(体闭集;两键至少一键)。会话店唯一行格写口 `writeSessionRowCells` 的格参。`title: null` = 清回自动标题(列写 NULL)。 */
 export interface SessionRowPatch {
     readonly title?: string | null;
     readonly pinned?: boolean;
 }
+/** 一行可写格的整组当前值(每格必在;没被写过的格 = 它的缺省值)。 */
+export type SessionRowCells = {
+    readonly [K in keyof SessionRowPatch]-?: Exclude<SessionRowPatch[K], undefined>;
+};
+/**
+ * 可写格的闭集与每格缺省值 —— **一只记录**(头注「格的闭集与缺省值是一只记录」):PATCH 体闭集的键表与 {@link sessionRowTagOf} 的取格都读它;
+ * 映射型把它与 {@link SessionRowPatch} 双向绑住(漏一键 / 多一键 = 编译红)。
+ */
+export declare const SESSION_ROW_CELL_DEFAULTS: SessionRowCells;
+/** 行标签的形:SHA-256 的 base64url(无填充)= 43 个 `[A-Za-z0-9_-]` 字符。体读者对 `expectedRowTag` 判的就是它。 */
+export declare const SESSION_ROW_TAG_SHAPE: RegExp;
+/** 算一只行标签要的四样:会话 id、属主、这一位住客的化身(非空)、可写格的整组当前值。 */
+export interface SessionRowTagInput {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly incarnation: string;
+    readonly cells: SessionRowCells;
+}
+/**
+ * 行标签 —— 唯一一只(头注「行标签」):纯函数、无进程密钥,多副本对同一行算出同一个串。格按 {@link SESSION_ROW_CELL_DEFAULTS} 的键取、
+ * 值等于缺省的不入、按键名升序成 `[[键, 值], …]`。化身只以这只单向摘要的形式出进程(`session-incarnation.ts` 头注)。
+ */
+export declare function sessionRowTagOf(row: SessionRowTagInput): string;
+/**
+ * 列表行上的 `rowTag` 键(present-iff 这一行可被条件写 = 店有行写口 ∧ 行上有化身):三只店的列表行映射都经它,化身那一格由调用方经
+ * `incarnationFromCell(…, "absent")` 解码好交进来(`undefined` = 行上没有令牌 ⇒ 键缺席,不铸)。
+ */
+export declare function sessionRowTagKey(row: {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly incarnation: string | undefined;
+    readonly cells: SessionRowCells;
+}): {
+    readonly rowTag?: string;
+};
+/** 客户端写(PATCH):行期望 + 可选的行标签(只有 PATCH 入口给)。 */
+export interface ClientSessionRowWrite {
+    readonly writer: "client";
+    readonly row: SessionRowExpectation;
+    readonly rowTag?: string;
+}
+/** 行重放(2c 导入落定后的那一笔):只有行期望 —— 它是镜像行的名写者,不判镜像、不带标签。 */
+export interface ReplaySessionRowWrite {
+    readonly writer: "replay";
+    readonly row: SessionRowExpectation;
+}
+/** 写原语的写法(写者身份闭集两员)。 */
+export type SessionRowWrite = ClientSessionRowWrite | ReplaySessionRowWrite;
+/**
+ * 写原语的结局(闭集四员):`written` / `changed` 带提交(回滚)之后另读的那一行(列表行投影,含新 `rowTag`);`mirror`(客户端写在只读镜像上)/
+ * `absent`(行期望不中 / 没有行 / 委派分区行 / 应答行已不是判过的那一位住客)一个字节没写。
+ */
+export type SessionRowWriteOutcome<Row> = {
+    readonly kind: "written";
+    readonly row: Row;
+} | {
+    readonly kind: "changed";
+    readonly row: Row;
+} | {
+    readonly kind: "mirror";
+} | {
+    readonly kind: "absent";
+};
+/** 行重放的结局:`changed` / `mirror` 对它不可达(判官对 `replay` 不判标签、不判镜像)。 */
+export type ReplaySessionRowWriteOutcome<Row> = Extract<SessionRowWriteOutcome<Row>, {
+    readonly kind: "written" | "absent";
+}>;
+/** 写原语在锁下读到的那一行 —— 三店各自读成这一形,交同一只判官 {@link judgeSessionRowWrite}。 */
+export interface LockedSessionRow {
+    readonly owner: string | null;
+    /** 化身那一格(`incarnationFromCell(…, "absent")` 解码:空 / 非串 ⇒ `undefined` = 住客未知,与 core 同读)。 */
+    readonly incarnation: string | undefined;
+    /** 委派分区行(SQL `placement_kind` 非空;local 没有)—— 不在列表面上,不写。 */
+    readonly placed: boolean;
+    /** 执行格是 `mirror`(写者在别处,本处只读)。 */
+    readonly mirror: boolean;
+    readonly cells: SessionRowCells;
+}
+/** 判官的四答(`write` = 可以写;其余三答 = 一个字节不写)。 */
+export type SessionRowVerdict = "write" | "changed" | "mirror" | "absent";
+/**
+ * 写原语的**唯一判官**(头注「写原语」):三店在各自的锁下读出那一行、交这一只,判序因此逐字同形 ——
+ *  ① **行期望**:core 的 `sessionRowMatches(how.row, 锁住的行, logNow)`;不中、没有行(`undefined`)、委派分区行 ⇒ `absent`;
+ *  ② **写者身份**:`client` ∧ 执行格为 `mirror` ⇒ `mirror`(镜像在本处只读;`replay` 是镜像的名写者,照写);
+ *  ③ **标签**:`client` 带 `rowTag` ∧ 锁住的行算出的标签({@link sessionRowTagOf})≠ 它 ⇒ `changed`(行上没有化身 ⇒ 算不出标签 ⇒ 任何标签都不中);
+ *  ④ `write`。
+ * 没有「已生效 ⇒ 写」的豁免:标签不中一律 `changed` —— 整体摘要分不出「住客换了」还是「格变了」,豁免会让恰好已有目标值的新住客拿到写。
+ * `logNow` 只在行期望带 `log` 时被调(调用方在同一把锁下先读好那只 mark)。
+ */
+export declare function judgeSessionRowWrite(sessionId: string, how: SessionRowWrite, locked: LockedSessionRow | undefined, logNow: () => SessionLogMark): SessionRowVerdict;
+/** 应答行:提交 / 回滚之后另读的那一行 + 读到它时行上的住客(属主 + 化身那一格)。 */
+export interface SessionRowAnswer<Row> {
+    readonly row: Row;
+    readonly occupant: {
+        readonly owner: string | null;
+        readonly incarnation: string | undefined;
+    };
+}
+/**
+ * 判官答 `write` / `changed` 之后的结局 —— 三店同一只:应答行(提交 / 回滚之后另读)仍是判过的那一位住客(同一只 core 判官 `sessionRowMatches`,只比行期望的住客半,
+ * 不比日志 mark —— 那一维判的是写之前)⇒ `written` / `changed` 带它;读不到、或已换了住客 / 属主 ⇒ `absent`(不把另一位住客的行答给这位调用方)。
+ */
+export declare function settleSessionRowWrite<Row>(how: SessionRowWrite, verdict: "write" | "changed", answer: SessionRowAnswer<Row> | undefined): SessionRowWriteOutcome<Row>;
 /** 一条已分类的拒:码 + 不回显输入的句子。 */
 export interface SessionRowProblem {
     readonly code: "request.body_shape" | "request.field_invalid";
@@ -27,13 +131,18 @@ export declare function readSessionPinned(v: unknown): {
 } | {
     readonly problem: SessionRowProblem;
 };
+/** PATCH 体读出来的东西:要写的格 + 可选的前置条件(客户端读到的行标签)。 */
+export interface SessionRowPatchRequest {
+    readonly patch: SessionRowPatch;
+    /** 在场 = 「这一行仍是我读到的那一份才写」(写原语在锁住的那一行上比 {@link sessionRowTagOf});缺席 = 无条件写。 */
+    readonly expectedRowTag?: string;
+}
 /**
- * `PATCH /v1/sessions/:id` 体的**唯一**读者。形不对(非对象 / 空 / 表外键)⇒ `request.body_shape`;两键各走自己那一格的读者。
+ * `PATCH /v1/sessions/:id` 体的**唯一**读者。形不对(非对象 / 表外键 / 一格可写位都没有 —— 只带 `expectedRowTag` 也算)⇒ `request.body_shape`;
+ * 各格走自己那一格的读者;`expectedRowTag` 不是 {@link SESSION_ROW_TAG_SHAPE} ⇒ `request.field_invalid`。先形后值,值的判序:`title` → `pinned` → `expectedRowTag`。
  * 拒句不回显调用方的键名或值。
  */
-export declare function readSessionRowPatch(body: unknown): {
-    readonly patch: SessionRowPatch;
-} | {
+export declare function readSessionRowPatch(body: unknown): SessionRowPatchRequest | {
     readonly problem: SessionRowProblem;
 };
 //# sourceMappingURL=session-row.d.ts.map

package/dist/session-row.js

@@ -1,7 +1,50 @@
-import { normalizePeerName } from "@sema-agent/core";
+import { createHash } from "node:crypto";
+import { normalizePeerName, sessionRowMatches } from "@sema-agent/core";
 export const SESSION_TITLE_MAX_CHARS = 120;
-const SESSION_ROW_PATCH_KEYS = { title: true, pinned: true };
-const BODY_SHAPE_MESSAGE = "the body must be a JSON object carrying at least one of `title` and `pinned`, and nothing else";
+export const SESSION_ROW_CELL_DEFAULTS = { title: null, pinned: false };
+const SESSION_ROW_TAG_DOMAIN = "sema.session-row-tag/1";
+export const SESSION_ROW_TAG_SHAPE = /^[A-Za-z0-9_-]{43}$/;
+export function sessionRowTagOf(row) {
+    const keys = Object.keys(SESSION_ROW_CELL_DEFAULTS).sort();
+    const cells = keys.filter((k) => row.cells[k] !== SESSION_ROW_CELL_DEFAULTS[k]).map((k) => [k, row.cells[k]]);
+    return createHash("sha256").update(JSON.stringify([SESSION_ROW_TAG_DOMAIN, row.sessionId, row.owner, row.incarnation, cells]), "utf8").digest("base64url");
+}
+export function sessionRowTagKey(row) {
+    return row.incarnation === undefined ? {} : { rowTag: sessionRowTagOf({ sessionId: row.sessionId, owner: row.owner, incarnation: row.incarnation, cells: row.cells }) };
+}
+export function judgeSessionRowWrite(sessionId, how, locked, logNow) {
+    if (locked === undefined || !sessionRowMatches(how.row, { owner: locked.owner, incarnation: locked.incarnation }, logNow) || locked.placed)
+        return "absent";
+    switch (how.writer) {
+        case "replay":
+            return "write";
+        case "client": {
+            if (locked.mirror)
+                return "mirror";
+            if (how.rowTag === undefined)
+                return "write";
+            const current = locked.incarnation === undefined ? undefined : sessionRowTagOf({ sessionId, owner: locked.owner, incarnation: locked.incarnation, cells: locked.cells });
+            return current === how.rowTag ? "write" : "changed";
+        }
+        default: {
+            const unknownWriter = how;
+            throw new Error(`judgeSessionRowWrite: no writer ${JSON.stringify(unknownWriter)}`);
+        }
+    }
+}
+export function settleSessionRowWrite(how, verdict, answer) {
+    const judged = how.row.row;
+    if (judged === null || answer === undefined)
+        return { kind: "absent" };
+    if (!sessionRowMatches({ row: judged }, answer.occupant, unreachableLogMark))
+        return { kind: "absent" };
+    return verdict === "write" ? { kind: "written", row: answer.row } : { kind: "changed", row: answer.row };
+}
+function unreachableLogMark() {
+    throw new Error("settleSessionRowWrite: the answer row's occupant check carries no log mark, yet the judge asked for one");
+}
+const BODY_SHAPE_MESSAGE = "the body must be a JSON object carrying at least one of `title` and `pinned` (and, optionally, `expectedRowTag`), and nothing else";
+const ROW_TAG_INVALID_MESSAGE = "expectedRowTag must be the `rowTag` string a session list row carries (43 characters: letters, digits, `-` and `_`)";
 const EMPTY_TITLE_MESSAGE = "title must not be the empty string — send `null` to clear it back to the automatic title";
 const INVISIBLE_TITLE_MESSAGE = "title must contain at least one visible character";
 const C0_CONTROL = /[\u0000-\u001f]/u;
@@ -25,11 +68,13 @@ export function readSessionTitle(v) {
 export function readSessionPinned(v) {
     return typeof v === "boolean" ? { pinned: v } : { problem: { code: "request.field_invalid", message: "pinned must be a boolean" } };
 }
+const EXPECTED_ROW_TAG_KEY = "expectedRowTag";
 export function readSessionRowPatch(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { problem: { code: "request.body_shape", message: BODY_SHAPE_MESSAGE } };
     const keys = Object.keys(body);
-    if (keys.length === 0 || keys.some((k) => !Object.hasOwn(SESSION_ROW_PATCH_KEYS, k))) {
+    const isCell = (k) => Object.hasOwn(SESSION_ROW_CELL_DEFAULTS, k);
+    if (!keys.some(isCell) || keys.some((k) => !isCell(k) && k !== EXPECTED_ROW_TAG_KEY)) {
         return { problem: { code: "request.body_shape", message: BODY_SHAPE_MESSAGE } };
     }
     const b = body;
@@ -46,6 +91,11 @@ export function readSessionRowPatch(body) {
             return read;
         patch = { ...patch, pinned: read.pinned };
     }
-    return { patch };
+    if (!(EXPECTED_ROW_TAG_KEY in b))
+        return { patch };
+    const tag = b.expectedRowTag;
+    if (typeof tag !== "string" || !SESSION_ROW_TAG_SHAPE.test(tag))
+        return { problem: { code: "request.field_invalid", message: ROW_TAG_INVALID_MESSAGE } };
+    return { patch, expectedRowTag: tag };
 }
 //# sourceMappingURL=session-row.js.map

package/dist/session-titler.d.ts

@@ -5,8 +5,8 @@
  * submission's acceptance seat (`run-acceptance.ts`: the objective entered the conversation, or a result-only verify /
  * cascade leg came back having done work). A run the engine refuses before acceptance never reaches the titler (no
  * model call for a refused input). No need to wait for the run to finish, and the web Recents gets the title sooner. Fills a NULL title only (`setTitleIfNull`,
- * store-side `WHERE title IS NULL`) — the user writes the SAME column unconditionally (`PATCH /v1/sessions/:id` →
- * `patchSessionMeta`): a user-set title is never overwritten (the probe below reads "titled" and skips the model
+ * store-side `WHERE title IS NULL`) — the user writes the SAME column (`PATCH /v1/sessions/:id` → the session row's write
+ * primitive `writeSessionRowCells`, unconditional unless the request carries `expectedRowTag`): a user-set title is never overwritten (the probe below reads "titled" and skips the model
  * call), and a title the user cleared (`title: null` ⇒ NULL) is filled again at the next submit (law: `session-row.ts`).
  * "Has it a title?" is read from the column on every submit (one point read) — the process keeps NO "already titled"
  * memo, because such a memo would be a second answer to that question that a clear turns stale. Generation = one

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/{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" | "toolAxes" | "url" | "principalHeader" | "cardUrl" | "allowSkills" | "headers")[];
+export declare const A2A_PEER_ENTRY_KEYS: readonly ("name" | "headers" | "principalHeader" | "toolAxes" | "url" | "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-cwd.d.ts

@@ -87,8 +87,13 @@ export declare function parseAdditionalDirectories(raw: unknown): string[] | und
  *      per-session choice always wins;
  *   2. the TRUSTED `ctx.parentCwd` (core threads the PARENT task's working root via `RunInternals` when this
  *      task is a delegated child — never a TaskSpec field), UNLESS the child asked for `isolation:"worktree"`
- *      (core contract: worktree wins — an isolated fan-out child must not share the parent's mutable dir);
+ *      (an isolated fan-out child must not share the parent's mutable dir) — then `undefined`;
  *   3. undefined → the factory's ephemeral per-task dir (top-level task with no registered cwd).
+ * The `isolation:"worktree"` ⇒ `undefined` rule is this function's own and holds by itself (the child never inherits the
+ * parent's dir). It is NOT what answers a worktree ask on the host lane: `boot/execution-env.ts` never reaches here with one —
+ * the worktree wrapper (one layer out) mints the tree and does not call the base factory, and without the wrapper the base
+ * factory REFUSES (`isolation.unavailable`) instead of minting the empty ephemeral dir rule 3 would give. That refusal arm is
+ * revoked when engine 7.61.0 refuses by itself; this function's rule then goes on keeping the child off the parent's dir.
  * CC parity: a Task sub-agent inherits the main session's cwd. Trust: `parentCwd` comes from core's trusted
  * run-internals channel (same posture as `isolation`), so no tenancy gate is needed here — but the HOST lane
  * itself is single-user by deployment shape, and container lanes (k8s/e2b/local-docker) never consult this.

package/dist/task-mcp.d.ts

@@ -69,9 +69,9 @@ export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
  */
 export declare const MCP_SERVER_ENTRY_KEYS: readonly ["allowTools", "contentOrigin", "elicitation", "name", "sessionMetaKey", "source", "startupTimeoutMs", "toolAxes", "toolFaces", "transport"];
 /** `transport.kind:"stdio"` 的键闭集 = stdio 臂处置表的键(`env` 是件,其余进声明)。 */
-export declare const STDIO_MCP_TRANSPORT_KEYS: readonly ("kind" | "command" | "args" | "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 ("kind" | "url" | "principalHeader" | "headers" | "assertionHeader")[];
+export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ("headers" | "kind" | "principalHeader" | "url" | "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) {