@sema-agent/server 7.138.0 → 7.140.0

package/dist/plugins/schema-consistency.d.ts

@@ -8,14 +8,14 @@
  * `errorCode` 直接是裸 `42703` / `ER_BAD_FIELD_ERROR`。
  *
  * ── 与 SCHEMA POLICY(`tidb-pool.ts` 顶注,clay 裁 2026-07-26)不冲突 ─────────────────────────────
- * 那条口径禁的是 **ALTER seam**:「代码是 schema 的唯一真源、存量库删库重建、`ensure*` 里不许再出现
- * `ALTER TABLE`」。本探针**一条 DDL 都不发**,它是只读的 information_schema 对账 —— 恰恰是那条口径的
+ * 那条口径禁的是 **ALTER seam**:「代码是 schema 的唯一真源、不做增量(缺列由部署者按拒启句打印的 ALTER 自己执行)、
+ * `ensure*` 里不许再出现 `ALTER TABLE`」。本探针**一条 DDL 都不发**,它是只读的 information_schema 对账 —— 恰恰是那条口径的
  * **执行面**:口径说「库必须等于代码」,在此之前没有任何东西检查过这句话是不是真的。两者一个是禁令
  * (不许代码偷改库)、一个是对账(库偏离了就别起),同向不同面。
  *
  * ── 为什么两个方向都拒(缺列 **和** 多列)──────────────────────────────────────────────────────
- * 缺列 = 库比代码旧(升级没重建库):读写会在用户路径上炸。多列 = 库比代码**新** —— 滚动升级窗里一个
- * **旧副本**连上了已被新副本重建过的库;它按旧列集读写,新列上的不变量(本例:`gen` 血统)在它眼里
+ * 缺列 = 库比代码旧(升级时库没跟上):读写会在用户路径上炸。多列 = 库比代码**新** —— 滚动升级窗里一个
+ * **旧副本**连上了已被新副本升过的库;它按旧列集读写,新列上的不变量(本例:`gen` 血统)在它眼里
  * 根本不存在,于是它会悄悄写出违反新契约的行。后者比前者更隐蔽,所以不做「幽灵列只警告」。
  * ⇒ 运维顺序因此是**先升库再升副本**(见 `docs/DEPLOY-PREREQS.md` 滚动升级窗那一节)。
  *
@@ -50,7 +50,7 @@
  */
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type SchemaDialect } from "./schema-ensure-legs.js";
+import type { SqlDialect } from "./sql-driver.js";
 import { type SchemaProbeRead } from "./schema-live-columns.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 /** 一列:名字 + 它在 `CREATE TABLE` 里的**原样定义文本**(生成 ADD COLUMN 指路用,不另手写)。 */
@@ -72,7 +72,7 @@ export interface ParsedTable {
  */
 export declare function parseCreateTable(stmt: string): ParsedTable | undefined;
 /** 启动时真会建出来的**全部**表形(录制 → 解析)。同名表二次出现以**先到**为准(`IF NOT EXISTS` 的真语义)。 */
-export declare function expectedTableShapes(dialect: SchemaDialect): Promise<Map<string, ParsedTable>>;
+export declare function expectedTableShapes(dialect: SqlDialect): Promise<Map<string, ParsedTable>>;
 /** 拒启码(机读)。附录 A / 拒启码表的登记名。 */
 export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
 /** 一张表的对账结论。 */
@@ -85,14 +85,24 @@ export interface TableMismatch {
 }
 /** 对账(纯函数:期望 × 实况 → 不符表清单)。 */
 export declare function diffSchema(expected: Map<string, ParsedTable>, live: Map<string, Set<string>>): TableMismatch[];
-/** 拒启文案(表名 + 缺/多列 + 两条路;ADD COLUMN 句由解析结果**生成**)。 */
-export declare function describeSchemaMismatch(dialect: SchemaDialect, mismatches: readonly TableMismatch[]): string;
+/**
+ * 逐表段 + 闭集出路段(多行):整库对账的拒启句与单表探针的拒因共用这一份句形(`schema-drift-sentence.ts` 的 `describeProbedTableDrift` 读它)。
+ * ADD COLUMN 句由解析结果**生成**,不手写。
+ *
+ * 出路段 = {@link SCHEMA_MISMATCH_WAYS_OUT}(**闭集三条**,常量;句子的属主在 `schema-drift-sentence.ts`):
+ * ① 部署与这个库匹配的构建;② 库比构建旧(缺列)⇒ 部署者自己执行上面逐字打印的 `ALTER TABLE … ADD COLUMN …`(列集对账与拒启句永不改库);
+ * ③ 库比构建新(多列)⇒ 部署持有那些列的构建(先升库、再升副本)。
+ * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据 —— 这里不写,拒启句的钉也守着(`test/schema-consistency.test.ts` ⑤)。
+ */
+export declare function describeMismatchedTables(mismatches: readonly TableMismatch[]): string[];
+/** 拒启文案(表头 + 逐表段与闭集三条出路 {@link describeMismatchedTables})。 */
+export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string;
 /**
  * 启动期对账:**建表之后**跑,不符即抛(= 拒启)。两方言 + InnoDB 同腿(MySQL 协议共用 `mysql` 臂)。
  *
  * 失败方向见文件头注:读抛 / 整库零行 ⇒ 拒。
  */
-export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SchemaDialect): Promise<void>;
+export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SqlDialect): Promise<void>;
 /**
  * 跳版升级的库的拒启:退役 schema(快照索引表 / 单座列)任一仍在。**具名类型**:锚类型不锚文案(日志消费端与测试按 `code` / 类型分派);
  * 码取列册对账同一个 `config.schema_mismatch`,运维面一个拒启码一个读法。拒句点名在场的坐标、说明第三条(旧拼法改写)同样没跑过、给出路。
@@ -109,10 +119,10 @@ export declare class RetiredSchemaPresentError extends StoreBootRefusalError {
  * 快照索引表 / 单座列任一在场 ⇒ 抛 {@link RetiredSchemaPresentError}。新库(建表之前一列都没有)⇒ 不在场、过。读抛 ⇒ 原样上抛(拒启;不是确定的拒启表态,
  * 开库等待窗照常重试 —— 与修前两条目录探针抛出时同一个去向)。
  */
-export declare function assertRetiredSchemaAbsent(read: SchemaProbeRead, dialect: SchemaDialect): Promise<void>;
+export declare function assertRetiredSchemaAbsent(read: SchemaProbeRead, dialect: SqlDialect): Promise<void>;
 /** 探针口的池参数:方言与它的池一起走(判别联合 ⇒ 不靠调用方断言「这个池是哪种」)。 */
 export type RetiredSchemaProbeTarget = {
-    readonly dialect: "tidb";
+    readonly dialect: "mysql";
     readonly pool: MysqlPool;
 } | {
     readonly dialect: "pg";

package/dist/plugins/schema-consistency.js

@@ -1,5 +1,6 @@
 import { recordEnsureStatements } from "./schema-ensure-legs.js";
 import { readLiveColumns } from "./schema-live-columns.js";
+import { SCHEMA_MISMATCH_WAYS_OUT } from "./schema-drift-sentence.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 const QUOTES = new Set(["'", '"', "`"]);
 function stripLineComments(sql) {
@@ -120,13 +121,8 @@ export function diffSchema(expected, live) {
     }
     return out;
 }
-export function describeSchemaMismatch(dialect, mismatches) {
-    const lines = [
-        `${SCHEMA_MISMATCH_ERROR_CODE}: the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database does not match this build's schema — refusing to start.`,
-        "This repo ships no ALTER seam (schema policy: the code is the single source of truth), so a drifted database is",
-        "a deployment-order problem, not something the process may quietly work around.",
-        "",
-    ];
+export function describeMismatchedTables(mismatches) {
+    const lines = [];
     for (const m of mismatches) {
         if (m.missing.length > 0) {
             lines.push(`  table ${m.table}: MISSING column(s) ${m.missing.map((c) => c.name).join(", ")} — the database is OLDER than this build.`);
@@ -138,7 +134,17 @@ export function describeSchemaMismatch(dialect, mismatches) {
             lines.push(`    No ALTER is suggested for this direction: deploy the build that owns those columns (upgrade the database FIRST, then the replicas).`);
         }
     }
-    lines.push("", "  Two ways out: (1) deploy the build whose code matches this database; (2) rebuild the database from this build", "  (DROP DATABASE <name>; CREATE DATABASE <name>; restart — every table is recreated by ensure*Schema at boot).");
+    lines.push("", ...SCHEMA_MISMATCH_WAYS_OUT);
+    return lines;
+}
+export function describeSchemaMismatch(dialect, mismatches) {
+    const lines = [
+        `${SCHEMA_MISMATCH_ERROR_CODE}: the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database does not match this build's schema — refusing to start.`,
+        "Schema policy: the code is the single source of truth, and the column check that produced this refusal never alters a database —",
+        "so a drifted database is a deployment-order problem, not something the process may quietly work around.",
+        "",
+        ...describeMismatchedTables(mismatches),
+    ];
     return lines.join("\n");
 }
 export async function assertSchemaMatchesCode(read, dialect) {
@@ -193,7 +199,7 @@ export async function assertRetiredSchemaAbsent(read, dialect) {
         throw new RetiredSchemaPresentError(found);
 }
 export async function assertRetiredSchemaAbsentOnPool(target) {
-    if (target.dialect === "tidb") {
+    if (target.dialect === "mysql") {
         const conn = await target.pool.getConnection();
         try {
             await assertRetiredSchemaAbsent(async (sql) => (await conn.query(sql))[0], "mysql");

package/dist/plugins/schema-drift-sentence.d.ts

@@ -0,0 +1,27 @@
+import type { SqlDialect } from "./sql-driver.js";
+/** 「库比构建旧」那一条出路的两个可变件:旧在哪(括注)、部署者要自己做的那件事。其余字一个不变。 */
+export interface OlderWayOut {
+    /** 括注:库旧在哪(例:`missing columns`)。 */
+    readonly when: string;
+    /** 部署者自己执行的动作(接在冒号后;句尾的「列集对账不改库」声明由本函数补)。 */
+    readonly action: string;
+}
+/**
+ * 出路段:**闭集三条**,编号 (1)(2)(3) 与顺序固定,与不符的方向无关(每一条自带适用条件)。
+ * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据。
+ */
+export declare function schemaWaysOut(older: OlderWayOut): readonly string[];
+/** 缺列方向的出路段(整库对账与单表探针共用;逐字钉在 `test/schema-consistency.test.ts` ⑤)。 */
+export declare const SCHEMA_MISMATCH_WAYS_OUT: readonly string[];
+/** 探针读口:一条 SQL → `{ rows }`(各 `assert*Schema` 的 `query` 形)。 */
+export type ProbeQuery = (sql: string) => Promise<{
+    rows: Record<string, unknown>[];
+}>;
+/**
+ * 单表探针抓到可证缺列后,拒因里「哪几列缺、该跑哪几条 ALTER」+ 闭集出路这一整段(多行文本,不含探针自己的首句与底层错误)。
+ *
+ * 读不出库的列册(权限 / 超时)或对账看不到探针点名的表有缺列(探针与建表语句互相矛盾)⇒ **响亮**地说「ALTER 没能打印」及原因,
+ * 出路仍是同一份闭集(旧一条改成「按建表语句自己加」)—— 绝不退回销毁性指路,也不悄悄吞掉这一段。
+ */
+export declare function describeProbedTableDrift(query: ProbeQuery, dialect: SqlDialect, tables: readonly string[]): Promise<string>;
+//# sourceMappingURL=schema-drift-sentence.d.ts.map

package/dist/plugins/schema-drift-sentence.js

@@ -0,0 +1,38 @@
+import { readLiveColumns } from "./schema-live-columns.js";
+export function schemaWaysOut(older) {
+    return [
+        "  Ways out (these three and no others):",
+        "    (1) deploy the build whose code matches this database;",
+        `    (2) the database is OLDER than this build (${older.when}): ${older.action} — the column check and this refusal never alter a database (the only DDL this service runs by itself on a table that already exists is idempotent index creation and the registered one-time migrations, see MIGRATION.md);`,
+        "    (3) the database is NEWER than this build (unknown columns): deploy the build that owns those columns — upgrade the database first, then the replicas.",
+    ];
+}
+export const SCHEMA_MISMATCH_WAYS_OUT = schemaWaysOut({
+    when: "missing columns",
+    action: "run the ALTER TABLE … ADD COLUMN statements printed above yourself",
+});
+export async function describeProbedTableDrift(query, dialect, tables) {
+    const d = dialect === "pg" ? "pg" : "mysql";
+    const read = async (sql) => (await query(sql)).rows;
+    let why;
+    try {
+        const sc = await import("./schema-consistency.js");
+        const diff = sc.diffSchema(await sc.expectedTableShapes(d), await readLiveColumns(read, d));
+        const missingOnly = diff.filter((m) => tables.includes(m.table) && m.missing.length > 0).map((m) => ({ ...m, ghost: [] }));
+        if (missingOnly.length > 0)
+            return sc.describeMismatchedTables(missingOnly).join("\n");
+        why = "this build's table definitions list no column that the database lacks on that table, so the probe and the definitions disagree";
+    }
+    catch (err) {
+        why = `information_schema.columns could not be read (${err instanceof Error ? err.message : String(err)})`;
+    }
+    return [
+        `  table ${tables.join(", ")}: a column this build reads is MISSING — the database is OLDER than this build; the ALTER statements could not be printed: ${why}.`,
+        "",
+        ...schemaWaysOut({
+            when: "missing columns",
+            action: "add each missing column yourself with an ALTER TABLE … ADD COLUMN statement built from this build's definition of the table",
+        }),
+    ].join("\n");
+}
+//# sourceMappingURL=schema-drift-sentence.js.map

package/dist/plugins/schema-ensure-legs.d.ts

@@ -1,6 +1,5 @@
 import type { PgQueryFn } from "./pg-query.js";
-/** 录制的方言。`mysql` = MySQL 协议(TiDB / InnoDB 同腿),`pg` = PostgreSQL。 */
-export type SchemaDialect = "mysql" | "pg";
+import type { SqlDialect } from "./sql-driver.js";
 /** advisory lock 语句 —— 与 schema 无关,录制时跳过(但要答成功,否则 ensure* 走降级告警路径)。 */
 export declare const LOCK_RE: RegExp;
 /**
@@ -51,5 +50,5 @@ export declare const DRIVEN_ENSURES: {
     readonly pg: readonly string[];
 };
 /** 跑一遍一条方言的真 `ensure*` 全腿,返回**录制到的语句流**(顺序即执行顺序)。纯内存,不碰数据库。 */
-export declare function recordEnsureStatements(dialect: SchemaDialect): Promise<string[]>;
+export declare function recordEnsureStatements(dialect: SqlDialect): Promise<string[]>;
 //# sourceMappingURL=schema-ensure-legs.d.ts.map

package/dist/plugins/schema-ensure-legs.js

@@ -6,10 +6,10 @@ import { ensurePgMemoryEmbedderMetaSchema } from "./memory-embedder-fingerprint.
 import { ensureTiDBMemorySyncSchema, ensureTiDBMemoryHistorySchema } from "./memory-sync-store-tidb.js";
 import { ensurePgMemorySyncSchema, ensurePgMemoryHistorySchema } from "./memory-sync-store-pg.js";
 import { ensureTiDBRosterSchema, ensurePgRosterSchema } from "./roster-store-sql.js";
-import { ensureTiDBBackgroundAgentSchema, ensurePgBackgroundAgentSchema } from "./background-agent-store-sql.js";
+import { ensureTiDBBackgroundAgentSchema, ensurePgBackgroundAgentSchema } from "../stores-sql/background-agent-store-sql.js";
 import { ensureTiDBMailboxSchema, ensurePgMailboxSchema } from "./mailbox-store-sql.js";
 import { ensureTiDBTaskAttachmentSchema, ensurePgTaskAttachmentSchema } from "./task-attachment-store.js";
-import { ensureTiDBUsageWindowSchema, ensurePgUsageWindowSchema } from "./usage-window-store-sql.js";
+import { ensureTiDBUsageWindowSchema, ensurePgUsageWindowSchema } from "../stores-sql/usage-window-store-sql.js";
 import { ensureTiDBTaskListSchema, ensurePgTaskListSchema } from "./task-list-store-sql.js";
 import { ensureTiDBDeviceSchema, ensurePgDeviceSchema } from "./device-store-sql.js";
 export const LOCK_RE = /GET_LOCK|RELEASE_LOCK|pg_(try_)?advisory/i;

package/dist/plugins/schema-live-columns.d.ts

@@ -3,7 +3,7 @@
  * 缺这条索引的列」也读它)。叶子模块:不值依赖任何模块(列册探针那边经录制驱动 / 建表腿值依赖 `ensure-index.ts`,读者若住在那边,
  * `ensure-index.ts` 读它就是一个运行时环)。方言词是 `ensure-index.ts` 的闭集(类型边,擦除)。
  */
-import type { SqlDialect } from "./ensure-index.js";
+import type { SqlDialect } from "./sql-driver.js";
 /** 探针读口:一条 SQL → 行数组(两方言由调用方各自绑)。 */
 export type SchemaProbeRead = (sql: string) => Promise<Array<Record<string, unknown>>>;
 /**

package/dist/plugins/session-capture-record-store-sql.js

@@ -83,7 +83,7 @@ export class SqlSessionCaptureRecordStore {
 }
 export class TiDBSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {
     constructor(pool) {
-        super(mysqlDriver(pool), "tidb");
+        super(mysqlDriver(pool), "mysql");
     }
 }
 export class PgSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {

package/dist/plugins/session-fork.d.ts

@@ -11,6 +11,10 @@
  * ## 为什么拷贝仍读整份日志、判官却读唤醒出来的会话
  * 拷贝要的是**整份**持久日志(压缩地板绕过 —— 唤醒只装 `[地板..叶]`,从唤醒里拷会丢地板之前的全部历史);判官要的只是叶链上最近几条(它是引擎的一份纯函数,
  * 吃一只 `Session`):唤醒出来的会话 `getEntry` 在地板之下会回读持久日志,所以判官在压缩过的会话上也看得见整条叶链。
+ *
+ * ## fork 续写的店契约(本文件下半)
+ * 三店同一只私有体 `forkTo(sourceId, owner, { id, key? })`:目标行原子新建(唯一创建点)· 撞已在按属主与 fork 键分类({@link classifyForkTarget})·
+ * local 崩溃中间态 `forking` 只许同键重试补齐 · fork 键此后每个写携带(整段换装经 `carriedRowCells`)。core 契约 `fork(sourceId, owner?)` = {@link forkByFreshId}。
  */
 import { type ForkPoint, type ForkRowShape, type SessionStorage } from "@sema-agent/core";
 /** 问引擎:这只(已唤醒的)源会话从哪里拷。SQL 孪生用它;local 店手里就是引擎的 `Session`,直接调 `settledForkOptions`。 */
@@ -28,4 +32,54 @@ export interface ForkLogRow {
  * 引擎的原词原句)。本仓不再自写父链走法 —— 那曾是与引擎 `getPathToRoot` 同义的第二份。
  */
 export declare const FORK_LOG_ROW_SHAPE: ForkRowShape<ForkLogRow>;
+/**
+ * `forkTo` 的目标:调用方给的新会话 id 与(可选)fork 键。`key` 是服务端拼的不透明串(路由按「源 + 调用方 nonce」派生),存进新行那一格
+ * `fork_key`(SQL)/ `forkKey`(local):一个事实 = 「建这一行的那次 fork 请求的键」。缺 = 非键控 fork(core 契约的现铸形)。
+ */
+export interface ForkTarget {
+    readonly id: string;
+    readonly key?: string;
+}
+/**
+ * fork 键的**唯一**拼法(路由带键 ⇒ `forkTo(…, { id: forkId, key: forkKeyOf(源, forkNonce) })`):服务端拼的不透明串 —— 源 id 与调用方 nonce 的摘要,
+ * 定长(远短于 `fork_key` 的 255),源进摘要 ⇒ 「异源同 nonce」拼出不同的键(撞同一只目标即 409,不当重放)。调用方不读它,只靠同键重试同答。
+ */
+export declare function forkKeyOf(sourceId: string, forkNonce: string): string;
+/**
+ * `forkTo` 的结果(`null` = 源不在,与 core `fork` 的 `null` 同义):
+ *  · `created` —— 目标行由这一次新建(唯一创建点:SQL 事务首句 INSERT 主键排他;local 两把写锁内「目标格不在 ∧ 目标存档不在」才写目标格);
+ *  · `replayed` —— 目标已在,属主 = 本次新属主 ∧ fork 键相等(同键重试同答;local `forking` 中间态在两把锁内补拷存档后也答它);
+ *  · `occupied` —— 目标已在而不是这次请求的那一行:`sameOwner: false` ⇒ 路由答与未知源同形的 404(不泄存在),`true` ⇒ 409 `conflict.fork_id_taken`(终局)。
+ */
+export type ForkToOutcome = {
+    readonly outcome: "created";
+    readonly id: string;
+} | {
+    readonly outcome: "replayed";
+    readonly id: string;
+} | {
+    readonly outcome: "occupied";
+    readonly sameOwner: boolean;
+};
+/** 撞上已在的目标时的唯一分类(三店同调):属主不同 ⇒ `occupied{sameOwner:false}`;属主同 ∧ 本次带键 ∧ 键相等 ⇒ `replayed`;其余(含无键的普通会话、无键请求)⇒ `occupied{sameOwner:true}`。 */
+export declare function classifyForkTarget(target: ForkTarget, existing: {
+    readonly owner: string | null | undefined;
+    readonly forkKey: string | null | undefined;
+}, forkOwner: string | null | undefined): ForkToOutcome;
+/**
+ * SQL 输方回滚后在新视图里读不到目标(赢方在分类之前回滚或被删),整笔重跑一次之后仍读不到 —— 不猜,响亮抛;路由答 503 `permanence: "transient"`。
+ * 具名类型:按类型认,不按文案。
+ */
+export declare class ForkTargetUnsettledError extends Error {
+    readonly targetId: string;
+    readonly code = "state.fork_target_unsettled";
+    constructor(targetId: string);
+}
+/** 三店的 `forkTo` 形(私有体,经店面 `forkTo` 交出)。 */
+export type ForkToFn = (sourceId: string, owner: string | null, target: ForkTarget) => Promise<ForkToOutcome | null>;
+/**
+ * core 契约 `fork(sourceId, owner?) → string | null` = `forkTo(…, { id: uuidv7() })` 的投影(三店同一只):`created` ⇒ 新 id;源不在 ⇒ `null`。
+ * 新铸的 uuidv7 撞上已在的行(`occupied` / `replayed`)不是一个答案,是不变量破 ⇒ 响亮抛 —— 无键请求永不答 `replayed`。
+ */
+export declare function forkByFreshId(forkTo: ForkToFn, sourceId: string, owner: string | null | undefined): Promise<string | null>;
 //# sourceMappingURL=session-fork.d.ts.map

package/dist/plugins/session-fork.js

@@ -1,4 +1,5 @@
-import { StoredSession, settledForkOptions } from "@sema-agent/core";
+import { SessionError, StoredSession, settledForkOptions, uuidv7 } from "@sema-agent/core";
+import { createHash } from "node:crypto";
 export async function forkPointOf(storage) {
     return settledForkOptions(new StoredSession(storage));
 }
@@ -6,4 +7,40 @@ export const FORK_LOG_ROW_SHAPE = {
     idOf: (row) => row.entry_id,
     parentOf: (row) => row.parent_id,
 };
+export function forkKeyOf(sourceId, forkNonce) {
+    return `fork1:${createHash("sha256").update(sourceId).update("\u0000").update(forkNonce).digest("hex")}`;
+}
+export function classifyForkTarget(target, existing, forkOwner) {
+    if ((existing.owner ?? null) !== (forkOwner ?? null))
+        return { outcome: "occupied", sameOwner: false };
+    if (target.key !== undefined && existing.forkKey === target.key)
+        return { outcome: "replayed", id: target.id };
+    return { outcome: "occupied", sameOwner: true };
+}
+export class ForkTargetUnsettledError extends Error {
+    targetId;
+    code = "state.fork_target_unsettled";
+    constructor(targetId) {
+        super(`fork target ${targetId} collided with another writer twice and could not be read back either time — retry the fork`);
+        this.targetId = targetId;
+        this.name = "ForkTargetUnsettledError";
+    }
+}
+export async function forkByFreshId(forkTo, sourceId, owner) {
+    const id = uuidv7();
+    const out = await forkTo(sourceId, owner ?? null, { id });
+    if (out === null)
+        return null;
+    switch (out.outcome) {
+        case "created":
+            return out.id;
+        case "replayed":
+        case "occupied":
+            throw new SessionError("storage", `fork of session ${sourceId}: a freshly minted id ${id} collided with an existing session (${out.outcome}) — nothing was written`);
+        default: {
+            const unknownOutcome = out;
+            throw new Error(`forkByFreshId: no arm for ${JSON.stringify(unknownOutcome)}`);
+        }
+    }
+}
 //# sourceMappingURL=session-fork.js.map

package/dist/plugins/session-row-sql.d.ts

@@ -0,0 +1,22 @@
+/**
+ * **会话行格写原语的 SQL 半** —— 两孪生(`tidb-session-store.ts` / `pg-session-storage.ts`)同一只实现,方言只在语句文本里。规则在 `src/session-row.ts`
+ * 头注「写原语」;判序只在那里的判官 `judgeSessionRowWrite`,本模块只说事务与语句。
+ *
+ * ## 一只事务(经 `SqlDriver.connect()`)
+ *  ① `SELECT … FROM session_meta WHERE session_id = ? FOR UPDATE` —— 判定读 = 锁读(当前读;连接初始化钉住读语义:TiDB 悲观、设不上拒启,
+ *     `sql-driver.ts` 的 `@contract txn.read-semantics`);行期望带 `log` 时,同锁下读日志的 mark:长度 = 锁住的行上的 `leaf_seq`(每次追加与
+ *     `leaf_id` 同句 +1,导入 / 换装 / fork 写成条目数),末条 = `session_event` 按 `seq` 倒序第一行(锁读)。追加者先锁这一行再插事件,所以持锁期间 mark 不动。
+ *  ② 判官(行期望 → 写者身份 → 标签);不是 `write` ⇒ 回滚、一个字节不写。
+ *  ③ `write` ⇒ 按 `session_id` 写(行已被本事务锁住)→ 提交。`updated_at` 不动(改名不是活动 —— 列表的新近序不变)。
+ * 应答行在**提交 / 回滚之后**由调用方的列表行读另读(新语句、新快照 —— 不在事务内用普通 `SELECT` 读:TiDB 悲观事务的普通读钉 `start_ts`,
+ * 等锁之后会读回判定之前的旧值),再交 `settleSessionRowWrite` 复核住客。
+ * 全局锁序:只锁根 `session_meta` 一行(读日志 mark 时再锁它的末条事件),不碰 `task_*`,不进放置写者「根 meta → `task_*`」锁序的后段。
+ */
+import type { SqlDriver } from "./sql-driver.js";
+import { type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome } from "../session-row.js";
+/**
+ * 写原语(头注):一只事务里锁根行 → 判官 → 写 / 不写;提交 / 回滚之后经 `readAnswer`(调用方店的列表行读 + 行上的住客)另读应答行。
+ * `db` = 店自己的池包成的 SqlDriver(连接经它的初始化);`readAnswer` 只在判官答 `write` / `changed` 时被调。
+ */
+export declare function writeSessionRowCellsSql<Row>(db: Pick<SqlDriver, "dialect" | "connect">, sessionId: string, cells: SessionRowPatch, how: SessionRowWrite, readAnswer: (sessionId: string) => Promise<SessionRowAnswer<Row> | undefined>): Promise<SessionRowWriteOutcome<Row>>;
+//# sourceMappingURL=session-row-sql.d.ts.map

package/dist/plugins/session-row-sql.js

@@ -0,0 +1,81 @@
+import { incarnationFromCell } from "../session-incarnation.js";
+import { judgeSessionRowWrite, settleSessionRowWrite, } from "../session-row.js";
+function binder(dialect) {
+    const values = [];
+    return {
+        values,
+        p: (v) => {
+            values.push(v);
+            return dialect === "pg" ? `$${values.length}` : "?";
+        },
+    };
+}
+function lockedRowFrom(dialect, sessionId, row) {
+    return {
+        owner: row.owner === null || row.owner === undefined ? null : String(row.owner),
+        incarnation: incarnationFromCell(sessionId, row.incarnation, "absent"),
+        placed: row.placement_kind !== null && row.placement_kind !== undefined,
+        mirror: row.execution_role === "mirror",
+        cells: {
+            title: row.title === null || row.title === undefined ? null : String(row.title),
+            pinned: dialect === "pg" ? row.pinned === true : Number(row.pinned) === 1,
+        },
+    };
+}
+async function lockedLogMark(conn, dialect, sessionId, leafSeq) {
+    const b = binder(dialect);
+    const last = await conn.query(`SELECT entry_id FROM session_event WHERE session_id = ${b.p(sessionId)} ORDER BY seq DESC LIMIT 1 FOR UPDATE`, b.values);
+    const id = last.rows[0]?.entry_id;
+    return { length: Number(leafSeq), lastEntryId: id === undefined || id === null ? null : String(id) };
+}
+export async function writeSessionRowCellsSql(db, sessionId, cells, how, readAnswer) {
+    const dialect = db.dialect;
+    let verdict;
+    const conn = await db.connect();
+    try {
+        await conn.begin();
+        const read = binder(dialect);
+        const locked = (await conn.query(`SELECT owner, incarnation, placement_kind, execution_role, title, pinned, leaf_seq FROM session_meta WHERE session_id = ${read.p(sessionId)} FOR UPDATE`, read.values)).rows[0];
+        const mark = how.row.log === undefined || locked === undefined ? undefined : await lockedLogMark(conn, dialect, sessionId, locked.leaf_seq);
+        verdict = judgeSessionRowWrite(sessionId, how, locked === undefined ? undefined : lockedRowFrom(dialect, sessionId, locked), () => {
+            if (mark === undefined)
+                throw new Error(`writeSessionRowCellsSql: the judge asked session ${sessionId}'s log mark, but the expectation carries none`);
+            return mark;
+        });
+        if (verdict !== "write") {
+            await conn.rollback();
+        }
+        else {
+            const w = binder(dialect);
+            const sets = [];
+            if (cells.title !== undefined)
+                sets.push(`title = ${w.p(cells.title)}`);
+            if (cells.pinned !== undefined)
+                sets.push(`pinned = ${w.p(cells.pinned)}`);
+            if (sets.length > 0)
+                await conn.query(`UPDATE session_meta SET ${sets.join(", ")} WHERE session_id = ${w.p(sessionId)}`, w.values);
+            await conn.commit();
+        }
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+    switch (verdict) {
+        case "absent":
+            return { kind: "absent" };
+        case "mirror":
+            return { kind: "mirror" };
+        case "write":
+        case "changed":
+            return settleSessionRowWrite(how, verdict, await readAnswer(sessionId));
+        default: {
+            const unknownVerdict = verdict;
+            throw new Error(`writeSessionRowCellsSql: no verdict ${JSON.stringify(unknownVerdict)}`);
+        }
+    }
+}
+//# sourceMappingURL=session-row-sql.js.map

package/dist/plugins/session-rules-column.d.ts

@@ -10,7 +10,7 @@
  */
 export declare const SESSION_RULES_COLUMN: {
     readonly name: "rule_entries";
-    readonly tidb: "rule_entries JSON NOT NULL";
+    readonly mysql: "rule_entries JSON NOT NULL";
     readonly pg: "rule_entries JSONB NOT NULL";
 };
 //# sourceMappingURL=session-rules-column.d.ts.map

package/dist/plugins/session-rules-column.js

@@ -1,6 +1,6 @@
 export const SESSION_RULES_COLUMN = {
     name: "rule_entries",
-    tidb: "rule_entries JSON NOT NULL",
+    mysql: "rule_entries JSON NOT NULL",
     pg: "rule_entries JSONB NOT NULL",
 };
 //# sourceMappingURL=session-rules-column.js.map

package/dist/plugins/session-store.d.ts

@@ -46,7 +46,7 @@ export declare function ensureSessionDurable(hostStore: SessionStore, sessionId:
  * 恒否决 park——bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,core 收 veto 即 expire checkpoint
  * (14ms~2s)+ settle failed,赎回窗口不存在):
  *   0. 属主([ref],`delegated-session-owner.ts`):按委派继承律判一次(唯一判据 `judgeDelegatedOwner`)—— 来源集 = 见证的根这一只(调用方交出的委派树根 + 调用方判断那一刻
- *      读到的根行住客:请求腿 = 本请求经鉴权解析的会话与受理时那一读,`/decide` 赎回腿 = 行上的 `rootSessionId` 与 claim 前后两读的那一位;core 的挂点签名只给子代 id,
+ *      读到的根行住客:请求腿 = 本请求经鉴权解析的会话与受理时那一读,`/decide` 赎回腿 = 行上的 `rootSessionId` 与写口放行的那一位(认领之前解析器那一读);core 的挂点签名只给子代 id,
  *      场景层把见证绑进闭包交下来)。此刻根行在而住客不是见证的那一位(删了、同 id 被重新登记)⇒ **拒**(`assertRootStillWitnessed`:不按新住客晋升 / 认领);
  *      缺席(行上没有根)或根行此刻不在 ⇒ 孤行哨兵。
  *   1. 快路:已在 host 店且有真内容 → 通过,**前提是那一行的属主按律定得下来**(`settleDelegatedOwner`:记着别的委派树 ⇒ 抛;记着这一棵 ⇒ 按它记录的根、父再判一次

package/dist/plugins/session-workspace-cell.d.ts

@@ -3,7 +3,7 @@ import { type JsonColumnReader } from "./sql-json-column.js";
 /** 列定义的唯一属主(两方言 DDL 内插它;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由建表语句生成)。 */
 export declare const SESSION_META_WORKSPACE_COLUMN: {
     readonly name: "workspace";
-    readonly tidb: "workspace JSON NULL";
+    readonly mysql: "workspace JSON NULL";
     readonly pg: "workspace JSONB";
 };
 /** 这一格的形读者(三只店与帧投影同一只;写前也过它 —— 写得进的就是读得出的)。 */

package/dist/plugins/session-workspace-cell.js

@@ -4,7 +4,7 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { assertJsonColumnWritable, createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem } from "./sql-json-column.js";
 export const SESSION_META_WORKSPACE_COLUMN = {
     name: "workspace",
-    tidb: "workspace JSON NULL",
+    mysql: "workspace JSON NULL",
     pg: "workspace JSONB",
 };
 const SESSION_WORKSPACE_SHAPE = z.object({

package/dist/plugins/shared-memory-store-sql.js

@@ -106,8 +106,8 @@ export class SqlSharedMemoryStore {
         this.now = opts.now ?? Date.now;
         this.maxListLimit = opts.maxListLimit ?? DEFAULT_MAX_LIST_LIMIT;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     async snapshot(ctx, opts) {
         throwIfAborted(opts.signal);

package/dist/plugins/sql-driver.d.ts

@@ -68,7 +68,7 @@
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
  * Reference collapses: image-bake-store-sql.ts (class + transactions) and checkpoint-store-sql.ts
  * (class, no transactions). Function-style stores follow task-list-store-sql.ts instead (inline
- * `dialect === "tidb" ? … : …` ternaries, no driver object) — pick the shape the pair already has.
+ * `dialect === "mysql" ? … : …` ternaries, no driver object) — pick the shape the pair already has.
  *
  * STEPS
  *  1. Read BOTH twins end to end first. List every method and mark it identical / SQL-text-only /
@@ -79,7 +79,7 @@
  *  3. Per statement, write BOTH texts at the call site via a 2-arg `q(tidbSql, pgSql)` helper.
  *     Never build one text with a placeholder-numbering loop — the point is that a reviewer sees
  *     the two statements adjacent.
- *  4. Genuinely-divergent algorithms get an `if (dialect === "tidb") { … } else { … }` block with a
+ *  4. Genuinely-divergent algorithms get an `if (dialect === "mysql") { … } else { … }` block with a
  *     🔴 comment saying WHY both are correct. Never "unify" them by picking one engine's algorithm.
  *  5. Old files become thin re-export shims. Class names, ctor arity, exported constants/types and
  *     helper names stay EXACTLY as they were — consumers and tests must not move.
@@ -98,7 +98,7 @@
  *   (pgSafeJsonStringify / pgProtocolJsonStringify / pgSanitizeText / pgHasUnstorable) · DDL. Each arm's
  *   BEHAVIOR (what pgSafeJsonStringify/pgProtocolJsonStringify actually do to the bytes) stays written out
  *   in `pg-safe-json.ts`, untouched — `dialectJsonEncoder`/`dialectProtocolJsonEncoder` below ([ref]
- *   redesign①) only collect the identical `dialect === "tidb" ? JSON.stringify(v) : pgSafe…(v)` DISPATCH
+ *   redesign①) only collect the identical `dialect === "mysql" ? JSON.stringify(v) : pgSafe…(v)` DISPATCH
  *   ternary that five call sites duplicated verbatim; they are not a new abstraction over the encodings
  *   themselves, so this does not violate the rule above.
  *
@@ -112,7 +112,12 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { Logger } from "../observability/logger.js";
-export type SqlDialect = "tidb" | "pg";
+/**
+ * SQL **文本**的语法族(调用方说,不探):`mysql` = MySQL 协议(TiDB / MySQL InnoDB / MariaDB 同一套语句),`pg` = PostgreSQL。
+ * 与 `@sema-agent/core-stores-sql` 公面的 `SqlDialect` 同词同集 —— 部署词 / 引擎词都不是它的别名:谁在答是另一轴 {@link SqlEngine}(驱动探)。
+ * 本仓只这一份方言闭集(加腿 = 编译错,不是运行期的 `default` 臂)。
+ */
+export type SqlDialect = "mysql" | "pg";
 export type SqlRow = Record<string, unknown>;
 /** Normalized statement result: `rows` for SELECTs, `affected` for INSERT/UPDATE/DELETE. */
 export interface SqlResult {
@@ -337,7 +342,7 @@ export declare function sqlWallsOf(engine: SqlEngineReading | undefined): SqlWal
  * 放在某一只店里会让下一个需要它的店要么 import 一整只无关的店、要么自己抄一份(抄出来的两份会漂)。
  */
 export declare const SQL_DB_NOW_MS: {
-    readonly tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)";
+    readonly mysql: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)";
     readonly pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint";
 };
 /**

package/dist/plugins/sql-driver.js

@@ -48,7 +48,7 @@ export function sqlWallsOf(engine) {
     switch (engine.dialect) {
         case "pg":
             return NO_WALLS;
-        case "tidb":
+        case "mysql":
             return SQL_FACTS_ABSENT_WALLS;
         default: {
             const unhandled = engine.dialect;
@@ -57,11 +57,11 @@ export function sqlWallsOf(engine) {
     }
 }
 export const SQL_DB_NOW_MS = {
-    tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)",
+    mysql: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)",
     pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint",
 };
 export async function sqlDbNowMs(db, subject) {
-    const sql = db.dialect === "tidb" ? `SELECT ${SQL_DB_NOW_MS.tidb} AS db_now_ms` : `SELECT ${SQL_DB_NOW_MS.pg} AS db_now_ms`;
+    const sql = `SELECT ${SQL_DB_NOW_MS[db.dialect]} AS db_now_ms`;
     const { rows } = await db.query(sql, []);
     const n = Number(rows[0]?.["db_now_ms"] ?? Number.NaN);
     if (!Number.isFinite(n))
@@ -375,7 +375,7 @@ export function createCloseAwarePool(pool) {
 export function mysqlDriver(pool) {
     const session = poolSession(pool);
     return {
-        dialect: "tidb",
+        dialect: "mysql",
         get facts() {
             return session.facts;
         },
@@ -471,6 +471,6 @@ export function pgDriver(pool) {
         },
     };
 }
-export const dialectJsonEncoder = (dialect) => dialect === "tidb" ? JSON.stringify : pgSafeJsonStringify;
-export const dialectProtocolJsonEncoder = (dialect) => dialect === "tidb" ? (v) => JSON.stringify(v) : pgProtocolJsonStringify;
+export const dialectJsonEncoder = (dialect) => dialect === "mysql" ? JSON.stringify : pgSafeJsonStringify;
+export const dialectProtocolJsonEncoder = (dialect) => dialect === "mysql" ? (v) => JSON.stringify(v) : pgProtocolJsonStringify;
 //# sourceMappingURL=sql-driver.js.map

package/dist/plugins/sql-errors.js

@@ -13,7 +13,7 @@ export function isPgUniqueViolation(err) {
     return String(keyOf(err, "code")) === PG_UNIQUE_VIOLATION_SQLSTATE;
 }
 export function isDupKeyError(dialect, err) {
-    return dialect === "tidb" ? isMysqlDupKeyError(err) : isPgUniqueViolation(err);
+    return dialect === "mysql" ? isMysqlDupKeyError(err) : isPgUniqueViolation(err);
 }
 export const PG_UNDEFINED_COLUMN_SQLSTATE = "42703";
 export const MYSQL_ER_BAD_FIELD_ERRNO = 1054;