@sema-agent/server 7.4.0 → 7.6.0

package/dist/plugins/image-bake-store-sql.js

@@ -26,7 +26,7 @@
  *   - `?` placeholders vs `$n`                        - `CAST(? AS JSON)` vs `$n::jsonb` (argv equality)
  *   - `INSERT IGNORE` vs `ON CONFLICT DO NOTHING`     - affectedRows vs rowCount (via SqlDriver)
  *   - dup-key `ER_DUP_ENTRY` vs SQLSTATE `23505`      - which UNIQUE collided: mysql2 `sqlMessage` text
- *                                                       vs pg `err.constraint` (uq_line naming differs)
+ *                                                       vs pg `err.constraint` (#192 A5 归一后两条方言同名 uq_image_bake_event_line)
  *   - `BEGIN PESSIMISTIC` (TiDB current read) vs `BEGIN` (PG READ COMMITTED under the sentinel lock)
  *   - the ADMISSION statement itself differs (see createBakeIfIdle) — both are correct under the
  *     sentinel lock, and both are preserved verbatim because the real-DB suites are the oracle
@@ -46,34 +46,34 @@ import { mapBakeRow as mapRow, BAKE_SELECT_COLS as SELECT_COLS, } from "./store-
  *  TINYINT(1) 归一(clay 批 2026-07-26):布尔列的 PG 映射统一 SMALLINT 0/1(此前本家族用 BOOLEAN)——
  *  两方言驱动读回同为 number ⇒ 不再存在「忘了配的适配器」这个病族;写入参与 SQL 字面量一律 0/1,
  *  读侧 `!!`/`Boolean()` 保持,store 出口 JS 类型逐字节不变(真双库套件的严格值断言为证)。
- *  The uq_line UNIQUE is given an explicit name so a 23505 can be attributed to it via err.constraint. */
+ *  The line UNIQUE is given the explicit name uq_image_bake_event_line so a 23505 can be attributed to it via err.constraint. */
 export const PG_IMAGE_BAKE_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS image_bake (
-     bake_id          VARCHAR(64)  NOT NULL,
-     profile          VARCHAR(128) NOT NULL,
+     bake_id          VARCHAR(64) COLLATE "C"  NOT NULL,
+     profile          VARCHAR(128) COLLATE "C" NOT NULL,
      bands            JSONB        NULL,
-     base_ref         VARCHAR(255) NULL,
+     base_ref         VARCHAR(255) COLLATE "C" NULL,
      push             SMALLINT     NOT NULL DEFAULT 0,
      dry_run          SMALLINT     NOT NULL DEFAULT 0,
      logs             SMALLINT     NOT NULL DEFAULT 0,
      argv             JSONB        NOT NULL,
-     status           VARCHAR(16)  NOT NULL,
-     state            VARCHAR(16)  NULL,
-     digest           VARCHAR(255) NULL,
-     repo             VARCHAR(255) NULL,
-     ref              VARCHAR(320) NULL,
-     index_id         VARCHAR(64)  NULL,
+     status           VARCHAR(16) COLLATE "C"  NOT NULL,
+     state            VARCHAR(16) COLLATE "C"  NULL,
+     digest           VARCHAR(255) COLLATE "C" NULL,
+     repo             VARCHAR(255) COLLATE "C" NULL,
+     ref              VARCHAR(320) COLLATE "C" NULL,
+     index_id         VARCHAR(64) COLLATE "C"  NULL,
      exit_code        INT          NULL,
-     error            TEXT         NULL,
-     error_code       VARCHAR(32)  NULL,
-     manifest_sha     VARCHAR(64)  NULL,
-     tag              VARCHAR(255) NULL,
-     idem_key         VARCHAR(255) NULL,
-     ingest_secret    VARCHAR(64)  NULL,
-     runner_id        VARCHAR(64)  NULL,
+     error            TEXT COLLATE "C"         NULL,
+     error_code       VARCHAR(32) COLLATE "C"  NULL,
+     manifest_sha     VARCHAR(64) COLLATE "C"  NULL,
+     tag              VARCHAR(255) COLLATE "C" NULL,
+     idem_key         VARCHAR(255) COLLATE "C" NULL,
+     ingest_secret    VARCHAR(64) COLLATE "C"  NULL,
+     runner_id        VARCHAR(64) COLLATE "C"  NULL,
      lease_until      TIMESTAMPTZ(3) NULL,
      cancel_requested SMALLINT     NOT NULL DEFAULT 0,
-     requested_by     VARCHAR(128) NULL,
+     requested_by     VARCHAR(128) COLLATE "C" NULL,
      created_at       TIMESTAMPTZ(3) NOT NULL,
      updated_at       TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (bake_id),
@@ -82,19 +82,19 @@ export const PG_IMAGE_BAKE_SCHEMA = [
     `CREATE INDEX IF NOT EXISTS idx_image_bake_status ON image_bake (status)`,
     `CREATE INDEX IF NOT EXISTS idx_image_bake_created ON image_bake (created_at)`,
     `CREATE TABLE IF NOT EXISTS image_bake_event (
-     bake_id  VARCHAR(64) NOT NULL,
+     bake_id  VARCHAR(64) COLLATE "C" NOT NULL,
      seq      INT         NOT NULL,
      line_ord INT         NULL,
-     kind     VARCHAR(24) NOT NULL,
-     level    VARCHAR(8)  NULL,
+     kind     VARCHAR(24) COLLATE "C" NOT NULL,
+     level    VARCHAR(8) COLLATE "C"  NULL,
      data     JSONB       NULL,
      ts       TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (bake_id, seq),
      CONSTRAINT uq_image_bake_event_line UNIQUE (bake_id, line_ord)
    )`,
     `CREATE TABLE IF NOT EXISTS image_bake_lease (
-     pool        VARCHAR(32) NOT NULL DEFAULT 'standard',
-     bake_id     VARCHAR(64) NOT NULL,
+     pool        VARCHAR(32) COLLATE "C" NOT NULL DEFAULT 'standard',
+     bake_id     VARCHAR(64) COLLATE "C" NOT NULL,
      acquired_at TIMESTAMPTZ(3) NOT NULL,
      expires_at  TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (pool)
@@ -104,7 +104,7 @@ export const PG_IMAGE_BAKE_SCHEMA = [
     // NOT EXISTS that two concurrent READ COMMITTED txns both pass — see createBakeIfIdle). Dialect-uniform with
     // the TiDB twin so a future divergence FAILS LOUD in the shared real-DB suite.
     `CREATE TABLE IF NOT EXISTS image_bake_admit (
-     pool VARCHAR(32) NOT NULL,
+     pool VARCHAR(32) COLLATE "C" NOT NULL,
      PRIMARY KEY (pool)
    )`,
 ];
@@ -121,7 +121,7 @@ function isDupKey(dialect, err) {
     return Boolean(err) && code === (dialect === "tidb" ? "ER_DUP_ENTRY" : "23505");
 }
 /** Which UNIQUE key did the dup collide on? The ATTRIBUTION CHANNEL differs by engine: mysql2 names the key in
- *  `sqlMessage` ("Duplicate entry '…' for key 'image_bake_event.uq_line'" vs "…'image_bake_event.PRIMARY'");
+ *  `sqlMessage` ("Duplicate entry '…' for key 'image_bake_event.uq_image_bake_event_line'" vs "…'image_bake_event.PRIMARY'");
  *  PG names the violated constraint in `err.constraint` (the PK is auto-named `image_bake_event_pkey`, the line
  *  UNIQUE is explicitly named `uq_image_bake_event_line` so it is attributable at all).
  *  M2: a line-unique dup is a BENIGN at-least-once re-send (already stored → no-op); a `PRIMARY` (bake_id,seq)
@@ -129,7 +129,7 @@ function isDupKey(dialect, err) {
 function dupKeyName(dialect, err) {
     if (dialect === "tidb") {
         const msg = String(err?.sqlMessage ?? err?.message ?? "");
-        if (/uq_line/i.test(msg))
+        if (/uq_image_bake_event_line/i.test(msg))
             return "uq_line";
         if (/PRIMARY/i.test(msg))
             return "primary";

package/dist/plugins/image-index-sql.js

@@ -52,33 +52,33 @@ import { mysqlDriver, pgDriver } from "./sql-driver.js";
  *  读侧 `!!` 保持,出口 JS 类型不变), inline UNIQUE KEY/KEY → separate CREATE UNIQUE INDEX / CREATE INDEX). */
 export const PG_IMAGE_INDEX_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS sandbox_image_index (
-     id                 VARCHAR(64)  NOT NULL,
-     profile            VARCHAR(64)  NOT NULL,
+     id                 VARCHAR(64) COLLATE "C"  NOT NULL,
+     profile            VARCHAR(64) COLLATE "C"  NOT NULL,
      bands              JSONB,
-     repo               VARCHAR(255) NOT NULL,
-     tag                VARCHAR(128) NOT NULL,
-     digest             VARCHAR(80)  NOT NULL,
+     repo               VARCHAR(255) COLLATE "C" NOT NULL,
+     tag                VARCHAR(128) COLLATE "C" NOT NULL,
+     digest             VARCHAR(80) COLLATE "C"  NOT NULL,
      toolchain_versions JSONB,
      capabilities       JSONB,
      pod_contract       JSONB,
      size_bytes         BIGINT,
-     status             VARCHAR(16)  NOT NULL DEFAULT 'building',
-     visibility         VARCHAR(16)  NOT NULL DEFAULT 'public',
-     tenant_id          VARCHAR(64),
-     manifest_sha       VARCHAR(64),
-     recipe_git_sha     VARCHAR(64),
-     generator_version  VARCHAR(32),
+     status             VARCHAR(16) COLLATE "C"  NOT NULL DEFAULT 'building',
+     visibility         VARCHAR(16) COLLATE "C"  NOT NULL DEFAULT 'public',
+     tenant_id          VARCHAR(64) COLLATE "C",
+     manifest_sha       VARCHAR(64) COLLATE "C",
+     recipe_git_sha     VARCHAR(64) COLLATE "C",
+     generator_version  VARCHAR(32) COLLATE "C",
      build_date         TIMESTAMPTZ(3),
-     supersedes         VARCHAR(64),
+     supersedes         VARCHAR(64) COLLATE "C",
      signed             SMALLINT     NOT NULL DEFAULT 0,
      created_at         TIMESTAMPTZ(3) NOT NULL,
      updated_at         TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (id)
    )`,
     `CREATE UNIQUE INDEX IF NOT EXISTS uq_repo_digest ON sandbox_image_index (repo, digest)`,
-    `CREATE INDEX IF NOT EXISTS idx_profile_status ON sandbox_image_index (profile, status, visibility)`,
-    `CREATE INDEX IF NOT EXISTS idx_digest ON sandbox_image_index (digest)`,
-    `CREATE INDEX IF NOT EXISTS idx_tenant ON sandbox_image_index (tenant_id, status)`,
+    `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_profile_status ON sandbox_image_index (profile, status, visibility)`,
+    `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_digest ON sandbox_image_index (digest)`,
+    `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_tenant ON sandbox_image_index (tenant_id, status)`,
 ];
 /** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
 export async function ensureSchema(pool) {

package/dist/plugins/local-checkpoint-store.d.ts

@@ -1,4 +1,4 @@
-import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointSummary, type CheckpointToken, type PendingSteerInput, type ReopenReason, type ResolveExpectation, type ResumeOutcome, type StoreDurability, type StoreFidelity } from "@sema-agent/core";
 import { type PendingCheckpoint } from "./checkpoint-store-sql.js";
 export interface LocalCheckpointStoreOptions {
     /** taskId join for the pending card (the local FileRunStore's `getActiveTaskId`). Absent ⇒ `taskId: null`. */
@@ -8,6 +8,25 @@ export interface LocalCheckpointStoreOptions {
     ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
 }
 export declare class LocalCheckpointStore {
+    /**
+     * `CheckpointStore.durability` 声明(#167 欠账,#168 件5)——**如实按内核判**:本类的内核是 core 的
+     * `FileCheckpointStore`(crash-safe ledger + snapshot,自身声明 `"durable"`),本地 scope 注册表也落
+     * 在同一个盘上目录里 ⇒ 进程重启后 park 全部还在、还赎得回,`"durable"` 是诚实读数而不是抬举。
+     *
+     * 它与「session store 的 local 形声明 durable 就拒启」不矛盾:那条判据管的是**声明 vs 介质**,而这里
+     * 的介质就是盘。真正的 process-local 形(`InMemoryCheckpointStore`)由 core 自己声明 `"process-local"`。
+     */
+    readonly durability: StoreDurability;
+    /**
+     * `CheckpointStore.fidelity` 声明(core 5.17.0 [3052] 提货批 #172)——**如实按内核判**,与 durability
+     * 同一条判据:本类的读写内核是 core 的 `FileCheckpointStore`,它自己声明 `"json"`(盘上是 JSON 行),
+     * 包装层只加 scope/session 索引与 ctx 附属文件,不改这条 round-trip 的宽度 ⇒ 抄内核的读数是诚实的。
+     *
+     * ⚠️ 包装类**不继承**被包装者的声明(本类是委派不是子类),所以这一格必须自己写。它与内核那一格
+     * 是否仍然一致由测试盯着(`wiring-governance-operator.test.ts` 的 #172 组直接读内核那一格对表)——
+     * 内核哪天改宽度,包装层的声明会被那条钉当场揪出来,而不是靠人记得同步。
+     */
+    readonly fidelity: StoreFidelity;
     private readonly inner;
     private readonly scopesPath;
     private readonly sessionTokensPath;

package/dist/plugins/local-checkpoint-store.js

@@ -34,6 +34,25 @@ function ctxFileOf(sessionId) {
     return `${sanitizePathComponent(sessionId).slice(0, 48)}-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}.json`;
 }
 export class LocalCheckpointStore {
+    /**
+     * `CheckpointStore.durability` 声明(#167 欠账,#168 件5)——**如实按内核判**:本类的内核是 core 的
+     * `FileCheckpointStore`(crash-safe ledger + snapshot,自身声明 `"durable"`),本地 scope 注册表也落
+     * 在同一个盘上目录里 ⇒ 进程重启后 park 全部还在、还赎得回,`"durable"` 是诚实读数而不是抬举。
+     *
+     * 它与「session store 的 local 形声明 durable 就拒启」不矛盾:那条判据管的是**声明 vs 介质**,而这里
+     * 的介质就是盘。真正的 process-local 形(`InMemoryCheckpointStore`)由 core 自己声明 `"process-local"`。
+     */
+    durability = "durable";
+    /**
+     * `CheckpointStore.fidelity` 声明(core 5.17.0 [3052] 提货批 #172)——**如实按内核判**,与 durability
+     * 同一条判据:本类的读写内核是 core 的 `FileCheckpointStore`,它自己声明 `"json"`(盘上是 JSON 行),
+     * 包装层只加 scope/session 索引与 ctx 附属文件,不改这条 round-trip 的宽度 ⇒ 抄内核的读数是诚实的。
+     *
+     * ⚠️ 包装类**不继承**被包装者的声明(本类是委派不是子类),所以这一格必须自己写。它与内核那一格
+     * 是否仍然一致由测试盯着(`wiring-governance-operator.test.ts` 的 #172 组直接读内核那一格对表)——
+     * 内核哪天改宽度,包装层的声明会被那条钉当场揪出来,而不是靠人记得同步。
+     */
+    fidelity = "json";
     inner;
     scopesPath;
     sessionTokensPath;

package/dist/plugins/mailbox-store-sql.d.ts

@@ -38,6 +38,7 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { MailboxLease, MailboxStore } from "@sema-agent/core";
+type MailboxAppendMessage = Parameters<MailboxStore["append"]>[2];
 export declare const MAILBOX_TABLE = "mailboxes";
 export declare const MAILBOX_MSG_TABLE = "mailbox_messages";
 export declare function ensureTiDBMailboxSchema(pool: MySqlPool): Promise<void>;
@@ -46,11 +47,7 @@ export declare class TiDBMailboxStore implements MailboxStore {
     private readonly pool;
     constructor(pool: MySqlPool);
     private tx;
-    append(scope: string, handle: string, msg: {
-        from?: string;
-        content: string;
-        sentAt: number;
-    }): Promise<number>;
+    append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
@@ -66,11 +63,7 @@ export declare class PgMailboxStore implements MailboxStore {
     private tx;
     /** 身份键拒绝式([1439] 协议纪律):scope/handle/owner/from 清洗形变 = 路由/attribution 错位。 */
     private assertIdentity;
-    append(scope: string, handle: string, msg: {
-        from?: string;
-        content: string;
-        sentAt: number;
-    }): Promise<number>;
+    append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
@@ -80,4 +73,5 @@ export declare class PgMailboxStore implements MailboxStore {
         maxAgeMs?: number;
     }): Promise<number>;
 }
+export {};
 //# sourceMappingURL=mailbox-store-sql.d.ts.map

package/dist/plugins/mailbox-store-sql.js

@@ -25,12 +25,58 @@ function assertKeyBytes(what, v) {
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
 }
+/** `hopChain` 的 JSON 文本列上界(TiDB `TEXT` = 65535 字节)。core 侧链本就有界
+ *  (`PEER_ADMISSION_DEFAULTS.maxChainLength` = 28,`PEER_HOP_CHAIN_WINDOW` = 32,元素是 peerAxisToken
+ *  短串)⇒ 正常形离这个数几个数量级远;守卫存在的理由是**关掉 MySQL 的静默截断类**(非严格模式下
+ *  超长 TEXT 写入只发 warning),截断后的 JSON 文本读侧 parse 失败 = 整条链静默变缺席,而缺席在
+ *  mailbox 上是有语义的(见下 encodeHopChain 注)。同 assertKeyBytes 精神:写入面 fail-loud。 */
+const HOP_CHAIN_MAX_BYTES = 60_000;
+/**
+ * `hopChain` 存取(core 5.17.0 design/176)。**JSON 文本列**,不是清洗面也不是身份键面:
+ *
+ *  - 为什么不清洗:链元素参与 core 的 `hop_loop` **等值比对**。内容面的 lossy 清洗(pgSanitizeText 的
+ *    U+FFFD 标记)会让两个不同 token 塌成同一个(误报环路)或让一个 token 变形(漏判环路)——两个
+ *    方向都是把准入判决改错,与 `content` 那种「读者读到近似文本仍可用」的容忍面性质不同。
+ *  - 为什么也不需要拒绝:`JSON.stringify` 是 **well-formed**(ES2019)——NUL 转义成 `\u0000`、lone
+ *    surrogate 转义成 `\udXXX`,产物恒是 ASCII 可存字节。于是 PG 的 unstorable 面根本不会被触及,
+ *    两方言都拿到逐字 round-trip,不必像 `from`/`scope`/`handle` 那样走拒绝式。
+ *  - **缺席 ≠ 空数组**:core 明示 mailbox 的 `hopChain` 在场性本身携带语义(「经 sema 准入门录入」vs
+ *    「外部/存量写入」,是整份契约里唯一允许从在场性推断的例外)。所以 NULL 读回 = 不铸键,`[]` 读回
+ *    = 铸一个空数组键,两者绝不互相折叠。
+ */
+function encodeHopChain(hopChain) {
+    if (hopChain === undefined)
+        return null;
+    const text = JSON.stringify(hopChain);
+    if (Buffer.byteLength(text, "utf8") > HOP_CHAIN_MAX_BYTES) {
+        throw new Error(`MailboxStore: hopChain exceeds the ${HOP_CHAIN_MAX_BYTES}-byte column (refusing — a truncated chain would silently read back as ABSENT, which mailbox treats as "not gate-admitted")`);
+    }
+    return text;
+}
+/** 读侧:NULL/缺席 ⇒ undefined(不铸键);坏行(非 JSON / 非字符串数组)⇒ 同样 undefined —— 一条读不
+ *  懂的链只能诚实降级成「没有链」,绝不半解析出一条会被拿去做环路比对的残链。 */
+function decodeHopChain(raw) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(bufToStr(raw));
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed) || parsed.some((x) => typeof x !== "string"))
+        return undefined;
+    return parsed;
+}
 function rowToMessage(r) {
+    const hopChain = decodeHopChain(r.hop_chain);
     return {
         seq: Number(r.seq),
         ...(r.from_id !== null && r.from_id !== undefined ? { from: bufToStr(r.from_id) } : {}),
         content: String(r.content),
         sentAt: Number(r.sent_at_ms),
+        ...(hopChain !== undefined ? { hopChain } : {}),
     };
 }
 export async function ensureTiDBMailboxSchema(pool) {
@@ -53,6 +99,10 @@ export async function ensureTiDBMailboxSchema(pool) {
     from_id VARBINARY(255) NULL,
     content LONGTEXT NOT NULL,
     sent_at_ms BIGINT NOT NULL,
+    -- hop_chain(core 5.17.0 design/176):peer 准入的 hop 链,JSON 文本;NULL = 缺席(**有语义**,
+    -- 见 encodeHopChain 头注:缺席 vs 空数组绝不互折)。TEXT 而非 LONGTEXT——链上界在 core(28 跳,
+    -- 短 token),写入面另有 HOP_CHAIN_MAX_BYTES fail-loud 守卫关掉静默截断类。
+    hop_chain TEXT NULL,
     PRIMARY KEY (scope_key, handle, seq),
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
   ) COLLATE utf8mb4_bin`);
@@ -61,7 +111,7 @@ export async function ensurePgMailboxSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
     scope_key VARCHAR(190) COLLATE "C" NOT NULL,
     handle VARCHAR(190) COLLATE "C" NOT NULL,
-    scope VARCHAR(190) NOT NULL,
+    scope VARCHAR(190) COLLATE "C" NOT NULL,
     next_seq BIGINT NOT NULL,
     lease_owner VARCHAR(190) COLLATE "C",
     lease_expires_at_ms BIGINT,
@@ -73,8 +123,9 @@ export async function ensurePgMailboxSchema(q) {
     handle VARCHAR(190) COLLATE "C" NOT NULL,
     seq BIGINT NOT NULL,
     from_id VARCHAR(255) COLLATE "C",
-    content TEXT NOT NULL,
+    content TEXT COLLATE "C" NOT NULL,
     sent_at_ms BIGINT NOT NULL,
+    hop_chain TEXT COLLATE "C", -- core 5.17.0 design/176(TiDB twin 同注:NULL = 缺席且有语义)
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_mbm_sent ON ${MAILBOX_MSG_TABLE} (scope_key, handle, sent_at_ms)`);
@@ -106,6 +157,7 @@ export class TiDBMailboxStore {
         assertIdentityChars("handle", handle);
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
+        const hopChain = encodeHopChain(msg.hopChain); // 事务外先编码:超界 fail-loud 必须在建盒/分配 seq 之前
         // ensure-first 形:先幂等 INSERT IGNORE 建盒(next_seq=1,首条/drop 后重建同臂)再 FOR UPDATE——
         // 「无行 FOR UPDATE + INSERT」的并发死锁/dup 撞车形整个消掉;seq 分配与 append 同事务(定谳 2)。
         return this.tx(async (c) => {
@@ -119,7 +171,7 @@ export class TiDBMailboxStore {
             }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = ? WHERE scope_key = ? AND handle = ?`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms) VALUES (?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain) VALUES (?, ?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt, hopChain]);
             return seq;
         });
     }
@@ -139,7 +191,7 @@ export class TiDBMailboxStore {
             }
             // FOR UPDATE = 当前读:TiDB 悲观事务的普通 SELECT 按 start_ts 快照(task-list twin 同案)——
             // 锁到 box 行后消息集必须读「现在」,否则 drop+重建窗内老消息混进新盒 lease(maxSeq 错位)。
-            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
+            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
                 return null; // 定谳 5:空盒 claim = null(box 行在也 null)
             const maxSeq = Number(msgs[msgs.length - 1].seq);
@@ -241,6 +293,7 @@ export class PgMailboxStore {
         const content = pgSanitizeText(msg.content); // 内容面 lossy(U+FFFD 标记,与 PG 转录 payload 同族)
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
+        const hopChain = encodeHopChain(msg.hopChain); // TiDB 同注:事务外先编码,超界 fail-loud 不留半个盒
         // ensure-first 形(TiDB 同注):幂等建盒再 FOR UPDATE,死锁/dup 撞车形消。
         return this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
@@ -260,7 +313,7 @@ export class PgMailboxStore {
             }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = $1 WHERE scope_key = $2 AND handle = $3`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms) VALUES ($1, $2, $3, $4, $5, $6)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain) VALUES ($1, $2, $3, $4, $5, $6, $7)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt, hopChain]);
             return seq;
         });
     }
@@ -273,7 +326,7 @@ export class PgMailboxStore {
             const box = boxes[0];
             if (box.lease_owner !== null && Number(box.lease_expires_at_ms) > now && String(box.lease_owner) !== owner)
                 return null;
-            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
+            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);

package/dist/plugins/memory-engine-pg.js

@@ -42,18 +42,18 @@ export async function ensurePgMemoryEngineSchema(query, opts = {}) {
         await query("CREATE EXTENSION IF NOT EXISTS vector");
     const embeddingCol = vec?.pgvector ? `vector(${vec.dimensions})` : "jsonb";
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.entries} (
-    id text PRIMARY KEY,
-    scope text NOT NULL,
-    slug text NOT NULL,
+    id text COLLATE "C" PRIMARY KEY,
+    scope text COLLATE "C" NOT NULL,
+    slug text COLLATE "C" NOT NULL,
     frontmatter jsonb NOT NULL,
-    body text NOT NULL,
-    rev text NOT NULL,
+    body text COLLATE "C" NOT NULL,
+    rev text COLLATE "C" NOT NULL,
     mtime_ms bigint NOT NULL,
     size_bytes integer NOT NULL,
     embedding ${embeddingCol}
   )`);
     try {
-        await query(`CREATE INDEX IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.entries}_scope_idx ON ${PG_MEMORY_ENGINE_TABLES.entries} (scope)`);
+        await query(`CREATE INDEX IF NOT EXISTS idx_${PG_MEMORY_ENGINE_TABLES.entries}_scope ON ${PG_MEMORY_ENGINE_TABLES.entries} (scope)`);
     }
     catch {
         /* pg-mem: partial CREATE INDEX support — the index is a perf add-on, never correctness */
@@ -63,10 +63,10 @@ export async function ensurePgMemoryEngineSchema(query, opts = {}) {
     // insert, leaving two entries whose file projections overwrite each other at materialize. The DB
     // constraint is the only true arbiter; the add path catches the violation and retries the next
     // suffix. NOT wrapped in try/catch — if this constraint cannot be created, the backend is unsafe.
-    await query(`CREATE UNIQUE INDEX IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.entries}_scope_slug_uq ON ${PG_MEMORY_ENGINE_TABLES.entries} (scope, slug)`);
+    await query(`CREATE UNIQUE INDEX IF NOT EXISTS uq_${PG_MEMORY_ENGINE_TABLES.entries}_scope_slug ON ${PG_MEMORY_ENGINE_TABLES.entries} (scope, slug)`);
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.cursors} (
-    scope text PRIMARY KEY,
-    cursor text NOT NULL
+    scope text COLLATE "C" PRIMARY KEY,
+    cursor text COLLATE "C" NOT NULL
   )`);
 }
 /** pgvector input literal — the same `[…]` string JSON.parse reads back from jsonb (one format, two columns). */

package/dist/plugins/memory-engine-tidb.js

@@ -12,7 +12,7 @@
 //   - add 路径 Pg 用 `INSERT … ON CONFLICT (id) DO UPDATE`(冲突靶=仅 PK)。MySQL 的 ON DUPLICATE KEY
 //     UPDATE 会被 **任意** 唯一键触发——(scope,slug) 撞键时它会把竞争对手的行改写成本 entry 的 id(数据毁),
 //     不能用;拆成「不存在→INSERT / 已存在→UPDATE by id」,两条腿的 ER_DUP_ENTRY 都按键名分诊(PRIMARY=
-//     并发同 id add → 转 UPDATE 腿;uk_scope_slug=并发 slug 竞争 → 下一个 -n 后缀重试);
+//     并发同 id add → 转 UPDATE 腿;uq_agent_memory_engine_entries_scope_slug=并发 slug 竞争 → 下一个 -n 后缀重试);
 //   - unique violation 判定:ER_DUP_ENTRY(errno 1062),不是 Pg 的 23505;
 //   - pg-mem 伪影 workaround(索引列 ANY 零行/重复占位符重复行)不抄——MySQL 本就走 IN-list,dedupe 保留
 //     是因为它同时是诚实语义(重复 key 问的是同一个 entry,契约锁死 once-per-entry);
@@ -45,9 +45,9 @@ export async function ensureTiDBMemoryEngineSchema(pool) {
     size_bytes  INT          NOT NULL,
     embedding   JSON         NULL,
     PRIMARY KEY (id),
-    KEY idx_scope (scope),
-    UNIQUE KEY uk_scope_slug (scope, slug)
-  )`);
+    KEY idx_agent_memory_engine_entries_scope (scope),
+    UNIQUE KEY uq_agent_memory_engine_entries_scope_slug (scope, slug)
+  ) COLLATE utf8mb4_bin`);
     // The (scope, slug) UNIQUE key above is CORRECTNESS, not perf (Pg 版同注):two
     // instances racing an add of one scope+slug (different ids) can both probe "free" and both insert;
     // the DB constraint is the only true arbiter and the add path retries the next suffix on violation.
@@ -55,14 +55,14 @@ export async function ensureTiDBMemoryEngineSchema(pool) {
     scope  VARCHAR(190) NOT NULL,
     \`cursor\` TEXT     NOT NULL,
     PRIMARY KEY (scope)
-  )`);
+  ) COLLATE utf8mb4_bin`);
 }
 function isDupEntry(err) {
     if (typeof err !== "object" || err === null)
         return false;
     return err.code === "ER_DUP_ENTRY" || err.errno === 1062;
 }
-/** ER_DUP_ENTRY messages name the violated key (`… for key 'tbl.PRIMARY'` / `… for key 'tbl.uk_scope_slug'`)
+/** ER_DUP_ENTRY messages name the violated key (`… for key 'tbl.PRIMARY'` / `… for key 'tbl.uq_agent_memory_engine_entries_scope_slug'`)
  *  — the add path uses this to tell "id already exists (→ overwrite leg)" from "slug race (→ -n retry)". */
 function isPrimaryKeyDup(err) {
     return isDupEntry(err) && /for key '[^']*PRIMARY'/i.test(String(err.message ?? ""));
@@ -263,7 +263,7 @@ export class TiDBMemoryEngineBackend {
                 }
             }
             // Slug collision with a DIFFERENT entry → deterministic `-n` suffix (file-backend parity); the
-            // probe is only an optimization — the write INSIDE the loop is arbitrated by uk_scope_slug, and
+            // probe is only an optimization — the write INSIDE the loop is arbitrated by uq_agent_memory_engine_entries_scope_slug, and
             // a concurrent loser retries the next suffix (Pg 版同注).
             let slug = entry.slug;
             for (let n = 2;; n++) {

package/dist/plugins/memory-sync-store-pg.js

@@ -8,23 +8,23 @@ export const PG_MEMORY_SYNC_TABLES = {
 /** Idempotent DDL for the sync plane (PG dialect). Call once at startup. */
 export async function ensurePgMemorySyncSchema(query) {
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.syncCursors} (
-    scope         varchar(190) NOT NULL,
-    peer          varchar(190) NOT NULL,
+    scope         varchar(190) COLLATE "C" NOT NULL,
+    peer          varchar(190) COLLATE "C" NOT NULL,
     base_revs     jsonb        NOT NULL,
     updated_at_ms bigint       NOT NULL,
     PRIMARY KEY (scope, peer)
   )`);
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.pushQueue} (
-    id              char(36)     PRIMARY KEY,
-    scope           varchar(190) NOT NULL,
-    entry_id        char(36)     NOT NULL,
+    id              char(36) COLLATE "C"     PRIMARY KEY,
+    scope           varchar(190) COLLATE "C" NOT NULL,
+    entry_id        char(36) COLLATE "C"     NOT NULL,
     payload         jsonb        NOT NULL,
     attempts        integer      NOT NULL DEFAULT 0,
     next_attempt_at bigint       NOT NULL,
-    last_error      text         NULL
+    last_error      text COLLATE "C"         NULL
   )`);
     // Scan face (§1.2): the reaper/consumer sweeps by due time. Perf add-on, never correctness.
-    await query(`CREATE INDEX IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.pushQueue}_next_attempt_idx ON ${PG_MEMORY_SYNC_TABLES.pushQueue} (next_attempt_at)`);
+    await query(`CREATE INDEX IF NOT EXISTS idx_${PG_MEMORY_SYNC_TABLES.pushQueue}_next_attempt ON ${PG_MEMORY_SYNC_TABLES.pushQueue} (next_attempt_at)`);
 }
 /** jsonb defense: node-pg hands back parsed objects, but a text-typed round-trip (or a foreign
  *  writer) may yield a string — same posture as parseJson in run-store-sql.ts. */
@@ -135,17 +135,17 @@ export async function ensurePgMemoryHistorySchema(query) {
     // (caller-injected epoch ms) instead of the draft's TIMESTAMP — the family's clock discipline
     // (sync_cursors.updated_at_ms precedent; DB clocks never judge anything).
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.history} (
-    id            char(36)     NOT NULL,
-    rev           varchar(128) NOT NULL,
-    prev_rev      varchar(128) NULL,
-    op            varchar(16)  NOT NULL,
-    scope         varchar(190) NOT NULL,
+    id            char(36) COLLATE "C"     NOT NULL,
+    rev           varchar(128) COLLATE "C" NOT NULL,
+    prev_rev      varchar(128) COLLATE "C" NULL,
+    op            varchar(16) COLLATE "C"  NOT NULL,
+    scope         varchar(190) COLLATE "C" NOT NULL,
     snapshot      jsonb        NULL,
     written_at_ms bigint       NOT NULL,
     PRIMARY KEY (id, rev)
   )`);
     // countByScope / future per-scope export-with-history scan face. Perf add-on, never correctness.
-    await query(`CREATE INDEX IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.history}_scope_idx ON ${PG_MEMORY_SYNC_TABLES.history} (scope)`);
+    await query(`CREATE INDEX IF NOT EXISTS idx_${PG_MEMORY_SYNC_TABLES.history}_scope ON ${PG_MEMORY_SYNC_TABLES.history} (scope)`);
 }
 export class PgMemoryHistoryStore {
     query;

package/dist/plugins/memory-sync-store-tidb.js

@@ -15,7 +15,7 @@ export async function ensureTiDBMemorySyncSchema(pool) {
     base_revs     JSON         NOT NULL,
     updated_at_ms BIGINT       NOT NULL,
     PRIMARY KEY (scope, peer)
-  )`);
+  ) COLLATE utf8mb4_bin`);
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_SYNC_TABLES.pushQueue} (
     id              CHAR(36)     NOT NULL,
     scope           VARCHAR(190) NOT NULL,
@@ -25,8 +25,8 @@ export async function ensureTiDBMemorySyncSchema(pool) {
     next_attempt_at BIGINT       NOT NULL,
     last_error      TEXT         NULL,
     PRIMARY KEY (id),
-    KEY idx_next_attempt (next_attempt_at)
-  )`);
+    KEY idx_agent_memory_engine_push_queue_next_attempt (next_attempt_at)
+  ) COLLATE utf8mb4_bin`);
 }
 /** JSON-column defense: mysql2 normally hands back parsed objects for JSON columns, but string
  *  shapes leak through (connection flags/proxies) — same posture as memory-engine-tidb.ts. */
@@ -138,8 +138,8 @@ export async function ensureTiDBMemoryHistorySchema(pool) {
     snapshot      JSON         NULL,
     written_at_ms BIGINT       NOT NULL,
     PRIMARY KEY (id, rev),
-    KEY idx_history_scope (scope)
-  )`);
+    KEY idx_agent_memory_engine_history_scope (scope)
+  ) COLLATE utf8mb4_bin`);
 }
 export class TiDBMemoryHistoryStore {
     pool;

package/dist/plugins/outcome-ledger-sql.js

@@ -113,12 +113,12 @@ export function coreOutcomeToLedgerRow(o) {
  */
 export const PG_OUTCOME_LEDGER_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS outcome_ledger (
-     id             VARCHAR(64)  NOT NULL,
-     task_signature VARCHAR(190) NOT NULL,
-     model          VARCHAR(190) NOT NULL,
-     task_id        VARCHAR(64),
-     run_status     VARCHAR(20)  NOT NULL DEFAULT 'completed-graded',
-     route          VARCHAR(16),
+     id             VARCHAR(64) COLLATE "C"  NOT NULL,
+     task_signature VARCHAR(190) COLLATE "C" NOT NULL,
+     model          VARCHAR(190) COLLATE "C" NOT NULL,
+     task_id        VARCHAR(64) COLLATE "C",
+     run_status     VARCHAR(20) COLLATE "C"  NOT NULL DEFAULT 'completed-graded',
+     route          VARCHAR(16) COLLATE "C",
      worker_count   INTEGER,
      oracle_passed  INTEGER,
      oracle_total   INTEGER,
@@ -128,7 +128,7 @@ export const PG_OUTCOME_LEDGER_SCHEMA = [
      replan_triggers JSONB,
      cost_micro_usd BIGINT,
      turns          INTEGER,
-     outcome        VARCHAR(8),
+     outcome        VARCHAR(8) COLLATE "C",
      llm_assisted   JSONB,
      signature_inputs JSONB,
      -- design/73 §1 bridge: the VERBATIM core TaskOutcome fact (oracleHadRedRun / status / oracle blob) as it

package/dist/plugins/pg-cost-quota.js

@@ -1,6 +1,6 @@
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
 /** The counter's table binding for the cumulative cost quota (mirror of the TiDB twin's binding). */
-const COST_QUOTA_TABLE = { table: "cost_quota", keyCol: "scope_key", valCol: "micro" };
+const COST_QUOTA_TABLE = { table: "cost_quota", keyCol: "scope_key", valCol: "micro_usd" };
 export class PgCostQuota {
     limitMicroUsd;
     counter;
@@ -39,9 +39,9 @@ export class PgCostQuota {
  *  tables, so a self-contained ensureSchema is safe (the central pg-pool aggregation is done separately). */
 export const PG_COST_QUOTA_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS cost_quota (
-     scope_key     VARCHAR(190) NOT NULL,
+     scope_key     VARCHAR(190) COLLATE "C" NOT NULL,
      window_bucket BIGINT       NOT NULL,
-     micro         BIGINT       NOT NULL DEFAULT 0,
+     micro_usd         BIGINT       NOT NULL DEFAULT 0,
      updated_at    TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (scope_key, window_bucket)
    )`,