@sema-agent/server 7.138.0 → 7.140.0

package/dist/plugins/org-delivery-quota-store.js

@@ -128,8 +128,8 @@ export class SqlOrgDeliveryQuotaStore {
     constructor(db) {
         this.db = db;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     async admitAttempt(fromScope, policy) {
         return this.inTx(ORG_DELIVERY_SENDER_QUOTA_TABLE, policy, (conn, at) => this.admitIn(conn, fromScope, at, policy));

package/dist/plugins/outcome-ledger-sql.d.ts

@@ -85,8 +85,8 @@ export declare function coreOutcomeToLedgerRow(o: CoreTaskOutcome): TaskOutcome;
  * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), TINYINT(1)→SMALLINT, INT→INTEGER, inline KEY→separate CREATE INDEX.
  * The table is DISJOINT from every other store's tables, so this self-contained set is safe (no shadowing).
  *
- * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
- * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
+ * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, there is no in-place
+ * migration, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_OUTCOME_LEDGER_SCHEMA: string[];
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgOutcomeLedgerSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */

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

@@ -87,8 +87,8 @@ export class SqlOutcomeLedger {
     constructor(db) {
         this.db = db;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     json(value) {
         return dialectJsonEncoder(this.db.dialect)(value);

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { type PermissionRuleWriter, type DurableRulePartition, type DurableRulePartitionProvider, type RuleScope, type RuleSyncFrontier, type RuleBehavior, type RuleCandidate, type RuleApprovalRecord, type StaleRuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
-import { type SqlDriver } from "./sql-driver.js";
+import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 import { type IndexSpec } from "./ensure-index.js";
 /**
  * 一只 durable 分区的写面,或 `undefined`(该 backend 从引擎侧看是只读的)。
@@ -73,7 +73,7 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  * [ref] 升级前置断言 —— **拒启**,不是 warn(codex 交叉复审 [high],验真后修;形照 [ref] 的
  * `assertToolResultProvenanceSchema` 先例)。
  *
- * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升
+ * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:代码是唯一真源,存量库缺列由部署者按拒启句打印的 ALTER 自己执行)。于是一台**没跟上**就升
  * 上来的部署,`CREATE TABLE IF NOT EXISTS` 对存量 `permission_rule_approval` 是空操作 —— 本车新加的
  * `command` / `edited_json` 两列不在,而 `get` / `create` / `cas` 三条语句**无条件**引用它们。
  * 后果不是「少一个新功能」,是**整条审批记录面**在那台机器上是坏的:
@@ -81,16 +81,16 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  *    `rule_store_error` —— 裁决照常 200,服务看起来完全健康;
  *  · CC 导入的 prepare 连 pending 记录都落不下;
  *  · 而 `/v1/capabilities` 的 `permissionRules` 仍然报 true ⇒ 本仓「says yes ⟺ route works」整句为假。
- * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 那正是 [ref]「禁静默降级」要挡的形态。
+ * 没有这道断言,运维得不到**任何**「这次升级必须先给表加列」的信号 —— 那正是 [ref]「禁静默降级」要挡的形态。
  *
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
  * 只判「五列在不在」(command / edited_json / offers_json 三列 TEXT 族 + version / selected_offer 两列
  * INT),不判宽度(TEXT 族无截断轴,INT 无宽度轴)。
  *
- * 🔴 **只有可证的缺列才给破坏性指路**(codex 交叉复审 round2/round3 [high],两轮收窄后的终形):
+ * 🔴 **只有可证的缺列才给「缺列」的拒因**(codex 交叉复审 round2/round3 [high],两轮收窄后的终形):
  * 「探针失败」**不等于**「列不在」。超时、连接被重置、取消、资源不足、列级权限被拒、表整个不存在 ——
- * 每一种都会让这条读抛错,而把它们诊断成「去 DROP TABLE」是一条**会真的毁掉审计记录**的建议(比它要
- * 挡的缺陷更贵)。round2 的两步探(先读一列老列)也不够:两次读之间同样可以插进一次瞬时故障。
+ * 每一种都会让这条读抛错,而把它们诊断成「缺列」是一条比它要挡的缺陷更贵的诊断(当年这句拒因还带着
+ * 一条会真的毁掉审计记录的指路;现在的出路是闭集三条,没有销毁性的一条)。round2 的两步探(先读一列老列)也不够:两次读之间同样可以插进一次瞬时故障。
  * 终形判据 = **方言的缺列错误码**,一行一方言的闭集(见 {@link isMissingColumnError});其余错误
  * **原样 rethrow**,一个字都不加工。真库两条腿各自跑过这条路径(db-integration 的存量表格),所以
  * 这张码表不是抄手册抄来的,是实测钉住的。
@@ -105,13 +105,13 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  */
 export declare function assertPermissionRuleApprovalSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
-}>, dialect: "tidb" | "pg"): Promise<void>;
+}>, dialect: SqlDialect): Promise<void>;
 /**
  * [ref] A7 升级前置断言 —— **拒启**(形与理由逐字照 {@link assertPermissionRuleApprovalSchema} 的配方,
  * 那条头注写了这道门为什么必须是拒启而不是 warn:本仓不发 `ALTER TABLE`,`CREATE TABLE IF NOT EXISTS`
  * 对存量表是空操作,而新列被**无条件**引用)。
  *
- * 病:一台没删表就升上来的部署,`permission_rule_ticket` 上没有 `redeemed_outcome` 列,而 A7 的三态
+ * 病:一台没跟上就升上来的部署,`permission_rule_ticket` 上没有 `redeemed_outcome` 列,而 A7 的三态
  * 协议(`settle` / `peek` / `reclaim`)三条语句全都引用它。后果不是"少一个新功能":
  *  · `POST /v1/rules/local-import/redeem` 的落定那一跳撞 unknown column ⇒ 票停在 CLAIMED 永不结算,
  *    属主的重放只能拿到 409,一次人的确认就此卡死到票过期;
@@ -119,16 +119,15 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
  *    的同意**被报成没发生。
  * 所以判据放在启动期、拒启,而不是等第一位用户去踩。
  *
- * 判据同款:发一条恒空的 `WHERE 1=0` 读;**只有可证的缺列**才给破坏性指路(其余错误原样 rethrow ——
- * 超时/连接重置/权限/表不在都会让这条读抛,把它们诊断成"去 DROP TABLE"是一条比缺陷更贵的建议)。
+ * 判据同款:发一条恒空的 `WHERE 1=0` 读;**只有可证的缺列**才给「缺列」的拒因(其余错误原样 rethrow ——
+ * 超时/连接重置/权限/表不在都会让这条读抛,把它们诊断成「缺列」是一条比缺陷更贵的诊断)。出路是**闭集三条**
+ * (与整库对账同一份,{@link describeProbedTableDrift}),没有销毁性的一条。
  *
- * 🔴 破坏性指路的代价在本表上**比审批表小得多**,文案照实说:票是分钟级 TTL 的治理瞬态(过期即死),
- * 删表最多让**正在预览、还没按确认**的那几个人重走一次 prepare;持久规则在 `permission_rule` 里,
- * 一行都不动。
+ * 文案照实说本表的分量:票是分钟级 TTL 的治理瞬态(过期即死),持久规则在 `permission_rule` 里,一行都不动。
  */
 export declare function assertPermissionRuleTicketSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
-}>, dialect: "tidb" | "pg"): Promise<void>;
+}>, dialect: SqlDialect): Promise<void>;
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgPermissionRuleSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const PERMISSION_RULE_INDEXES: readonly IndexSpec[];
 export declare function ensurePgPermissionRuleSchema(q: PgQueryFn): Promise<void>;
@@ -440,10 +439,9 @@ export declare const RULE_PENDING_APPROVAL_RETENTION_MS: number;
  * 处理整个积压。500 的取值:一轮的最坏工作量钉在「几百行删除」这个数量级,而常态每轮的真实行数是个位数
  * (一次 prepare 留一行);积压按轮渐进清空,每轮都是完整语义,绝不留半干净状态。
  *
- * ⚠️ 两方言的**索引到货方式不对称**,如实登记:PG 侧是独立的 `CREATE INDEX IF NOT EXISTS`,存量库
- * 下次 `ensureSchema` 就补建;MySQL 侧索引写在 `CREATE TABLE` 里,而本仓 schema 口径是「启动 DDL 是唯一
- * 真源、不发 ALTER」⇒ **存量表拿不到这两个索引**,要靠一次删库重建(与 7.8.0 / 7.10.0 两次 BREAKING 窗
- * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
+ * 索引到货:两方言的存量库都由幂等加索引原语(`ensureIndexes`)在启动时补建 —— PG 侧是独立的 `CREATE INDEX`,
+ * MySQL 协议侧先探测、缺才发在线 `ALTER TABLE … ADD INDEX`(中央 schema 的索引列表含 `PERMISSION_RULE_INDEXES`)。
+ * 补建完成之前(或某个副本还没起过新版),这条腿在存量库上仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
  */
 export declare const RULE_REAP_BATCH = 500;
 /**
@@ -504,7 +502,7 @@ export interface UndurableScopePurgeDb {
  * 读数写进调用方递进来的账(`into`,{@link UndurableScopePurgeReadings}):删掉的行在那只桶的回写提交之后追加 ⇒ 本函数半途抛出时,已删的行已经在账上;
  * 错误**原样**上抛(不加工、不自铸拒因句 —— 收据由迁移段那一只收据账随拒因带走,[ref])。
  */
-export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: "tidb" | "pg", into: UndurableScopePurgeReadings, now?: () => number): Promise<void>;
+export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: SqlDialect, into: UndurableScopePurgeReadings, now?: () => number): Promise<void>;
 /** 三个 SQL 面的一次性装配束(one driver, three faces)。`durable` = [ref] 的 durable 分区后端;
  *  引擎接缝上的统一店由 `main.ts` 用 `createPermissionRuleStoreProvider({ durable })` 合成一次。 */
 export interface PermissionRuleStores {

package/dist/plugins/permission-rule-store-sql.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, isValidDurableScope, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, principalNameOf, readRuleOffer2, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
+import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ensureIndexes } from "./ensure-index.js";
 import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, SqlJsonColumnError } from "./sql-json-column.js";
@@ -144,8 +145,8 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     -- version:**数据格式版本**(= core \`RuleApprovalRecord.schema\`,本形恒 4 —— core 7.9.0 #625 由 3 升,
     -- 代码里的单点是 RULE_APPROVAL_RECORD_SCHEMA;OCC 守卫另在 rev,两轴禁混,schema-naming 门③ 白名单
     -- 登记)。读侧对非 4 的行(含上一形的 3)交还 design/375 §4.5 的
-    -- StaleRuleApprovalRecord 信封(identity 键 only)—— 本仓 SCHEMA POLICY 是删表重建,重建后的表
-    -- 不该有这种行,这一臂是「未来再换形」的防御位,绝不静默 widen 成一条本形担保不了的记录。
+    -- StaleRuleApprovalRecord 信封(identity 键 only)—— 这一臂是「未来再换形」的防御位,
+    -- 绝不静默 widen 成一条本形担保不了的记录。
     version INT NOT NULL,
     -- offers_json:core \`RuleOffer2[]\`(design/375 §4.1)—— 按 index 引用 candidates 的 OPTION 结构,
     -- **绝不存规则文本副本**(显示三元组由 core \`ruleOffersOfRecord\` 从候选文本投影;存副本=造一个
@@ -240,13 +241,11 @@ export async function assertPermissionRuleApprovalSchema(query, dialect) {
             `#340 card-edit columns (command / edited_json) and the design/375 record-form columns ` +
             `(version / offers_json / selected_offer): the approval record now stores its OPTION structure and the ` +
             `chosen offer, and the store refuses to read rows whose record-form version it cannot vouch for. ` +
-            `This repository ships no ` +
-            `ALTER TABLE migrations, so the table must be recreated: run \`DROP TABLE ${PERMISSION_RULE_APPROVAL_TABLE};\` on the ` +
-            `${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the schema is recreated at boot. ` +
-            `The cost is bounded: this table holds pending/settled approval RECORDS (the audit trail of who said yes to which ` +
-            `rule), not the rules themselves — persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched. Dropping it ` +
-            `loses in-flight CC-import previews (re-runnable) and the historical record trail. ` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+            `This table holds pending/settled approval RECORDS (the audit trail of who said yes to which ` +
+            `rule), not the rules themselves — persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched; ` +
+            `an in-place ALTER keeps the record trail.\n` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_APPROVAL_TABLE])));
     }
 }
 export async function assertPermissionRuleTicketSchema(query, dialect) {
@@ -260,12 +259,10 @@ export async function assertPermissionRuleTicketSchema(query, dialect) {
             `the #265 A7 three-state redemption columns (MINTED → CLAIMED → SETTLED, the claim generation that fences a superseded ` +
             `claimant, and the lane binding that keeps cc-import and local-import tickets from being interchangeable): without them a ` +
             `local-import ticket can be claimed but never settled, so a redemption that already wrote rules to the store answers its ` +
-            `owner with a retry-later it can never satisfy. This repository ships no ALTER TABLE migrations, so the table must be recreated: run ` +
-            `\`DROP TABLE ${PERMISSION_RULE_TICKET_TABLE};\` on the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and ` +
-            `restart — the schema is recreated at boot. The cost is bounded and small: this table holds minute-TTL single-use import ` +
-            `tickets (a governance transient that dies on expiry), so dropping it only makes anyone mid-preview re-run prepare; ` +
-            `persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched. ` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+            `owner with a retry-later it can never satisfy. This table holds minute-TTL single-use import ` +
+            `tickets (a governance transient that dies on expiry); persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched.\n` +
+            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_TICKET_TABLE])));
     }
 }
 export const PERMISSION_RULE_INDEXES = [
@@ -413,7 +410,7 @@ function refuseRowsTheValidatorRefuses(ownerKey, rules, tombstones) {
     }
 }
 function fencedCasWhere(dialect, firstPlaceholder, ownerKey, cas) {
-    const ph = (offset) => (dialect === "tidb" ? "?" : `$${firstPlaceholder + offset}`);
+    const ph = (offset) => (dialect === "mysql" ? "?" : `$${firstPlaceholder + offset}`);
     return {
         sql: `owner_key = ${ph(0)} AND ${cas.column} = ${ph(1)} AND (grammar IS NULL OR grammar <= ${ph(2)})`,
         params: [ownerKey, cas.expected, SESSION_RULES_GRAMMAR],
@@ -433,7 +430,7 @@ async function writeBucket(exec, dialect, ownerKey, cur, next, nowMs) {
     const body = { rules: next.rules, tombstones: next.tombstones, quarantined: cur.quarantined, ...(cur.observedVector !== undefined ? { observedVector: cur.observedVector } : {}) };
     const enc = dialectProtocolJsonEncoder(dialect);
     const where = fencedCasWhere(dialect, 7, ownerKey, { column: "rev", expected: cur.rev });
-    const affected = await exec(dialect === "tidb"
+    const affected = await exec(dialect === "mysql"
         ? `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = ?, tombstones_json = ?, quarantined_json = ?, checksum = ?, grammar = ?, rev = rev + 1, updated_at_ms = ? WHERE ${where.sql}`
         : `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = $1, tombstones_json = $2, quarantined_json = $3, checksum = $4, grammar = $5, rev = rev + 1, updated_at_ms = $6 WHERE ${where.sql}`, [
         enc(next.rules, "permission_rule.rules_json"),
@@ -463,13 +460,13 @@ class SqlDurableRulePartition {
         return dialectProtocolJsonEncoder(this.db.dialect)(v, label);
     }
     q(tidbSql, pgSql) {
-        return this.db.dialect === "tidb" ? tidbSql : pgSql;
+        return this.db.dialect === "mysql" ? tidbSql : pgSql;
     }
     async read() {
         return refusingUnreadableColumns(`bucket ${this.ownerKey}`, () => this.readBucketRow());
     }
     async readBucketRow() {
-        const { rows } = await this.db.query(this.q(`SELECT ${bucketRowColumns("tidb")} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT ${bucketRowColumns("pg")} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
+        const { rows } = await this.db.query(this.q(`SELECT ${bucketRowColumns("mysql")} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT ${bucketRowColumns("pg")} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
         const row = rows[0];
         if (row === undefined)
             return { ...EMPTY_BUCKET, rules: [], tombstones: [], quarantined: [] };
@@ -537,7 +534,7 @@ class SqlDurableRulePartition {
         },
         apply: async (delta, opts) => {
             if (delta.kind === "sync-join") {
-                throw new Error("the SQL permission-rule backend does not implement the sync-join landing pipeline (core's applySyncJoin is not on the package's public export face); " +
+                throw new Error("the SQL permission-rule backend does not implement the sync-join landing arm; " +
                     "no sync client is wired in this deployment, so this arm has no caller — see permission-rule-store-sql.ts header");
             }
             assertWriteDeltaScopeDurable(delta);
@@ -607,7 +604,7 @@ export class SqlRuleApprovalRecordStore {
         this.now = now;
     }
     q(tidbSql, pgSql) {
-        return this.db.dialect === "tidb" ? tidbSql : pgSql;
+        return this.db.dialect === "mysql" ? tidbSql : pgSql;
     }
     enc(v, label) {
         return dialectProtocolJsonEncoder(this.db.dialect)(v, label);
@@ -616,7 +613,7 @@ export class SqlRuleApprovalRecordStore {
         return refusingUnreadableColumns(`approval record ${id}`, () => this.readApprovalRow(id));
     }
     async readApprovalRow(id) {
-        const { rows } = await this.db.query(this.q(`SELECT record_id, owner_kind, principal, kind, state, version, rev, ${jsonColumnText("tidb", "candidates_json")}, ${jsonColumnText("tidb", "offers_json")}, selected_offer, ${jsonColumnText("tidb", "redeemed_dots_json")}, tool_call_id, bound_input_hash, command, ${jsonColumnText("tidb", "edited_json")}, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ?`, `SELECT record_id, owner_kind, principal, kind, state, version, rev, ${jsonColumnText("pg", "candidates_json")}, ${jsonColumnText("pg", "offers_json")}, selected_offer, ${jsonColumnText("pg", "redeemed_dots_json")}, tool_call_id, bound_input_hash, command, ${jsonColumnText("pg", "edited_json")}, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1`), [id]);
+        const { rows } = await this.db.query(this.q(`SELECT record_id, owner_kind, principal, kind, state, version, rev, ${jsonColumnText("mysql", "candidates_json")}, ${jsonColumnText("mysql", "offers_json")}, selected_offer, ${jsonColumnText("mysql", "redeemed_dots_json")}, tool_call_id, bound_input_hash, command, ${jsonColumnText("mysql", "edited_json")}, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = ?`, `SELECT record_id, owner_kind, principal, kind, state, version, rev, ${jsonColumnText("pg", "candidates_json")}, ${jsonColumnText("pg", "offers_json")}, selected_offer, ${jsonColumnText("pg", "redeemed_dots_json")}, tool_call_id, bound_input_hash, command, ${jsonColumnText("pg", "edited_json")}, created_at_iso FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE record_id = $1`), [id]);
         const row = rows[0];
         if (row === undefined)
             return undefined;
@@ -720,7 +717,7 @@ export class SqlRuleImportTicketStore {
         this.db = db;
     }
     q(tidbSql, pgSql) {
-        return this.db.dialect === "tidb" ? tidbSql : pgSql;
+        return this.db.dialect === "mysql" ? tidbSql : pgSql;
     }
     async dbNowMs() {
         return sqlDbNowMs(this.db, PERMISSION_RULE_TICKET_TABLE);
@@ -758,7 +755,7 @@ export class SqlRuleImportTicketStore {
         if (row.expiresAtMs <= row.dbNowMs)
             return { ok: false, reason: "expired" };
         const claimId = randomUUID();
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.tidb}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND consumed_at_ms IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.tidb}`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND consumed_at_ms IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.pg}`), [claimId, ticketId, ownerKey, purpose]);
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.mysql}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND consumed_at_ms IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.mysql}`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND consumed_at_ms IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.pg}`), [claimId, ticketId, ownerKey, purpose]);
         if (affected === 1)
             return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId };
         const after = await this.readRow(ticketId);
@@ -771,11 +768,11 @@ export class SqlRuleImportTicketStore {
         return { ok: false, reason: "consumed" };
     }
     async release(ticketId, principal, claimId, mustRemainValidMs = 0) {
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.tidb} + ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = $1 AND owner_key = $2 AND claim_id = $3 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.pg} + $4`), [ticketId, buildRuleOwnerKey({ kind: "principal", principal }), claimId, mustRemainValidMs]);
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.mysql} + ?`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = NULL, claim_id = NULL WHERE ticket_id = $1 AND owner_key = $2 AND claim_id = $3 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND expires_at_ms > ${SQL_DB_NOW_MS.pg} + $4`), [ticketId, buildRuleOwnerKey({ kind: "principal", principal }), claimId, mustRemainValidMs]);
         return affected === 1;
     }
     async settle(ticketId, principal, claimId, outcome) {
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET redeemed_outcome = ?, settled_at_ms = ${SQL_DB_NOW_MS.tidb} WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET redeemed_outcome = $1, settled_at_ms = ${SQL_DB_NOW_MS.pg} WHERE ticket_id = $2 AND owner_key = $3 AND claim_id = $4 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL`), [
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET redeemed_outcome = ?, settled_at_ms = ${SQL_DB_NOW_MS.mysql} WHERE ticket_id = ? AND owner_key = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET redeemed_outcome = $1, settled_at_ms = ${SQL_DB_NOW_MS.pg} WHERE ticket_id = $2 AND owner_key = $3 AND claim_id = $4 AND consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL`), [
             dialectProtocolJsonEncoder(this.db.dialect)(outcome, "permission_rule_ticket.redeemed_outcome"),
             ticketId,
             buildRuleOwnerKey({ kind: "principal", principal }),
@@ -808,11 +805,11 @@ export class SqlRuleImportTicketStore {
         if (row.claimId === undefined)
             return { ok: false };
         const claimId = randomUUID();
-        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.tidb}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND consumed_at_ms <= ${SQL_DB_NOW_MS.tidb} - ? AND redeemed_outcome IS NULL`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND claim_id = $5 AND consumed_at_ms IS NOT NULL AND consumed_at_ms <= ${SQL_DB_NOW_MS.pg} - $6 AND redeemed_outcome IS NULL`), [claimId, ticketId, buildRuleOwnerKey({ kind: "principal", principal }), purpose, row.claimId, minClaimAgeMs]);
+        const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.mysql}, claim_id = ? WHERE ticket_id = ? AND owner_key = ? AND purpose = ? AND claim_id = ? AND consumed_at_ms IS NOT NULL AND consumed_at_ms <= ${SQL_DB_NOW_MS.mysql} - ? AND redeemed_outcome IS NULL`, `UPDATE ${PERMISSION_RULE_TICKET_TABLE} SET consumed_at_ms = ${SQL_DB_NOW_MS.pg}, claim_id = $1 WHERE ticket_id = $2 AND owner_key = $3 AND purpose = $4 AND claim_id = $5 AND consumed_at_ms IS NOT NULL AND consumed_at_ms <= ${SQL_DB_NOW_MS.pg} - $6 AND redeemed_outcome IS NULL`), [claimId, ticketId, buildRuleOwnerKey({ kind: "principal", principal }), purpose, row.claimId, minClaimAgeMs]);
         return affected === 1 ? { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId } : { ok: false };
     }
     async readRow(ticketId) {
-        const { rows } = await this.db.query(this.q(`SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, ${jsonColumnText("tidb", "redeemed_outcome")}, ${SQL_DB_NOW_MS.tidb} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = ?`, `SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, ${jsonColumnText("pg", "redeemed_outcome")}, ${SQL_DB_NOW_MS.pg} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = $1`), [ticketId]);
+        const { rows } = await this.db.query(this.q(`SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, ${jsonColumnText("mysql", "redeemed_outcome")}, ${SQL_DB_NOW_MS.mysql} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = ?`, `SELECT owner_key, approval_id, payload_hash, purpose, expires_at_ms, consumed_at_ms, claim_id, ${jsonColumnText("pg", "redeemed_outcome")}, ${SQL_DB_NOW_MS.pg} AS db_now_ms FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ticket_id = $1`), [ticketId]);
         const row = rows[0];
         if (row === undefined)
             return undefined;
@@ -837,7 +834,7 @@ export async function purgeUndurableScopeRows(db, dialect, into, now = Date.now)
     const cols = `owner_key, ${bucketRowColumns(dialect)}`;
     let after = "";
     for (;;) {
-        const page = await db.rows(dialect === "tidb"
+        const page = await db.rows(dialect === "mysql"
             ? `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`
             : `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`, [after]);
         for (const first of page) {
@@ -860,7 +857,7 @@ export async function purgeUndurableScopeRows(db, dialect, into, now = Date.now)
                         settled = true;
                         break;
                     case "conflict":
-                        row = (await db.rows(dialect === "tidb" ? `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?` : `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`, [ownerKey]))[0];
+                        row = (await db.rows(dialect === "mysql" ? `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?` : `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`, [ownerKey]))[0];
                         if (row === undefined)
                             settled = true;
                         break;
@@ -910,13 +907,13 @@ function contentFreeRefusal(ownerKey, e) {
     return `permission_rule bucket ${ownerKey}: the bucket judge threw ${e instanceof Error ? e.name : typeof e} (its text is withheld here: it may quote the row)`;
 }
 export function createSqlPermissionRuleStores(db, now) {
-    const q = (tidb, pg) => (db.dialect === "tidb" ? tidb : pg);
+    const q = (mysql, pg) => (db.dialect === "mysql" ? mysql : pg);
     return {
         durable: new SqlDurableRulePartitionProvider(db, now),
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db),
         reapExpired: async (nowMs) => {
-            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ${SQL_DB_NOW_MS.tidb} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.tidb} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.tidb} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.pg} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH})`), []);
+            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ${SQL_DB_NOW_MS.mysql} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.mysql} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.mysql} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE (consumed_at_ms IS NULL AND expires_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (redeemed_outcome IS NOT NULL AND settled_at_ms IS NOT NULL AND settled_at_ms <= ${SQL_DB_NOW_MS.pg} - ${RULE_IMPORT_TICKET_GC_GRACE_MS}) OR (consumed_at_ms IS NOT NULL AND redeemed_outcome IS NULL AND consumed_at_ms < ${SQL_DB_NOW_MS.pg} - ${RULE_PENDING_APPROVAL_RETENTION_MS}) LIMIT ${RULE_REAP_BATCH})`), []);
             const orphanPending = await db.query(q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < ? AND NOT EXISTS (SELECT 1 FROM ${PERMISSION_RULE_TICKET_TABLE} t WHERE t.approval_id = ${PERMISSION_RULE_APPROVAL_TABLE}.record_id) LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE ctid IN (SELECT a.ctid FROM ${PERMISSION_RULE_APPROVAL_TABLE} a WHERE a.state = 'pending' AND a.created_at_ms < $1 AND NOT EXISTS (SELECT 1 FROM ${PERMISSION_RULE_TICKET_TABLE} t WHERE t.approval_id = a.record_id) LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_PENDING_APPROVAL_RETENTION_MS]);
             return deadTickets.affected + orphanPending.affected;
         },

package/dist/plugins/pg-pool.d.ts

@@ -10,9 +10,13 @@
  * (run-store + checkpoint); the remaining tidb-* tables are added as their PG stores land (tracked).
  *
  * ─────────────────────────────── SCHEMA POLICY (clay 裁 2026-07-26) ───────────────────────────────
- * THIS CODE IS THE SINGLE SOURCE OF TRUTH for the PG schema. The stack is not yet in production and runs
- * against a single local operator's database, so a schema change is DROP-AND-RECREATE (drop the database,
- * boot, `ensurePgSchema` rebuilds it) — NOT an in-place migration.
+ * THIS CODE IS THE SINGLE SOURCE OF TRUTH for the PG schema, and there is NO in-place migration seam in this statement array: a database that
+ * lags behind the code is refused at boot with the exact `ALTER TABLE … ADD COLUMN …` statements printed, and the
+ * deployer runs them themselves: the column-set check and its refusal never alter a database. The only DDL this
+ * process runs by itself on a table that already exists is idempotent index creation (`ensureIndex`: indexes only,
+ * never a column) and the registered one-time migrations (each has a window and a registry row in
+ * `one-time-migrations.ts`) — adding / changing / renaming a column or dropping a table is done by those migrations
+ * and by nothing else.
  *
  * Consequence, and it is a hard rule: **do NOT add new `ALTER TABLE` seams here.** Every column / default /
  * constraint change is folded into its own `CREATE TABLE`, and this array stays pure `CREATE TABLE` +

package/dist/plugins/pg-session-storage.d.ts

@@ -1,21 +1,22 @@
 import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
-import { type SessionRowPatch } from "../session-row.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type OrphanOwnerLog } from "../delegated-session-owner.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import type { SessionWorkspace } from "../session-workspace.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type SessionFace } from "../session-incarnation.js";
 import { type IndexSpec } from "./ensure-index.js";
+import { type ForkTarget, type ForkToOutcome } from "./session-fork.js";
+import { type ExecutionPlacementSeat } from "../execution-placement.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
  * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), inline `KEY`/`UNIQUE KEY`→separate CREATE INDEX (UNIQUE for uq_session_event_entry).
  *
- * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
- * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
+ * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, there is no in-place
+ * migration, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_SESSION_SCHEMA: string[];
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
@@ -70,6 +71,10 @@ export declare class PgSessionStore implements SessionStore {
     private readonly pending;
     /** 委派子代孤行那一行 warn 的去处(TiDB 孪生同格)。 */
     private readonly log;
+    /** 执行席(TiDB 孪生同格;实现与语句的唯一属主 = `execution-placement-sql.ts`,本店只交自己的池)。 */
+    readonly executionPlacement: ExecutionPlacementSeat;
+    /** 本店的池包成的 SqlDriver(TiDB 孪生同格):执行席与会话行格写原语的事务都经它借连接。 */
+    private readonly db;
     constructor(pool: Pool, opts?: {
         readonly log?: OrphanOwnerLog;
         readonly retention?: RetentionDeclaration;
@@ -121,13 +126,14 @@ export declare class PgSessionStore implements SessionStore {
     }): Promise<SessionSummary[]>;
     /** @see TiDBSessionStore.sessionSummaryOf — the PG twin (same projection, run-preview subqueries scoped to the id). */
     sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
-    /** @see TiDBSessionStore.patchSessionMeta — the PG twin (the only writer of a user-set title / pin; the UPDATE and the read-back
-     *  both conditioned on the verified occupant's incarnation; `updated_at` untouched). The read-back is a second statement, not a
-     *  `RETURNING` CTE: the outer SELECT of a data-modifying CTE reads the pre-UPDATE snapshot of `session_meta`. */
-    patchSessionMeta(sessionId: string, patch: SessionRowPatch, face: SessionFace): Promise<SessionSummary | undefined>;
-    /** @see TiDBSessionStore.selectSummaries — the PG twin. `where` already carries `$n` placeholders numbered over `params`;
+    /** @see TiDBSessionStore.listRowOf — the PG twin. */
+    private listRowOf;
+    /** @see TiDBSessionStore.writeSessionRowCells — the PG twin (the same SQL half, `session-row-sql.ts`; only the statement text differs). */
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
+    /** @see TiDBSessionStore.selectListRows — the PG twin. `where` already carries `$n` placeholders numbered over `params`;
      *  the run scope and the LIMIT take the next numbers (PG binds by number, so text order does not matter). */
-    private selectSummaries;
+    private selectListRows;
     /** @see TiDBSessionStore.probeTitle — the PG twin. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
     /** @see TiDBSessionStore.setTitleIfNull — the PG twin (the auto-titler's NULL-only write). */
@@ -143,9 +149,13 @@ export declare class PgSessionStore implements SessionStore {
     /** @see TiDBSessionStore.recordSessionWorkspace — the PG twin (whole-cell overwrite fenced to the occupant; `pgSafeJsonStringify` + `::jsonb`, like every PG JSON write;
      *  the general query surface — the pool-wide `DB_QUERY_TIMEOUT_MS` server-side `statement_timeout` bounds it, no per-call client timer). */
     recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
-    /** @see TiDBSessionStore.fork — copy the WHOLE durable history (full session_event log, compaction floor bypassed,
-     *  NOT wake's bounded tail) to a NEW uuidv7 session, re-seq dense from 0, ids/parents verbatim, owner=caller. */
+    /** @see TiDBSessionStore.fork — core 契约 `fork(sourceId, owner?)` = {@link forkTo} 的投影(新铸 uuidv7 目标,`forkByFreshId`;三店同一只)。 */
     fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /** @see TiDBSessionStore.forkTo — fork 续写的店契约(PG 孪生逐字同义):目标行 meta 先、主键排他;撞已在 ⇒ 回滚后在新视图读目标按属主与 fork 键分类;
+     *  读不到 ⇒ 整笔重跑一次,再不行 ⇒ {@link ForkTargetUnsettledError}。 */
+    forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
+    /** @see TiDBSessionStore.forkToOnce — 一次尝试(PG 孪生):拷**整份**持久日志(压缩地板绕过,不是 wake 的有界尾),seq 从 0 重铸稠密,id / 父 / 载荷原样。 */
+    private forkToOnce;
     /** @see TiDBSessionStore.exportEntries — 2c session-sync EXPORT: the FULL durable session_event log (compaction floor
      *  bypassed, NOT wake's tail) as `SessionTreeEntry[]`, oldest-first, verbatim. null if the source is unknown. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
@@ -163,18 +173,19 @@ export declare class PgSessionStore implements SessionStore {
         batchSize?: number;
     }): Promise<AsyncIterable<SessionTreeEntry> | null>;
     /** @see TiDBSessionStore.importEntries — 2c session-sync IMPORT: core `validateEntriesForImport` gate FIRST (fail-closed),
-     *  then persist its verbatim output (re-seq dense from 0, ids/parents/payload/ts unchanged) in ONE txn with
-     *  session_meta LAST as the commit point; owner = the RE-STAMPED authenticated principal (never the bundle's). */
+     *  then persist its verbatim output (re-seq dense from 0, ids/parents/payload/ts unchanged) in ONE txn, **lock-or-create, meta first**
+     *  (读写序律:占行 → 锁行判是不是本次占下的 → 锁定读认领 → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST
-     *  (fail-closed), then DELETE events + the owner-guarded meta delete (`owner IS NOT DISTINCT FROM $n` = the PG `<=>`,
-     *  defense-in-depth), then re-insert via the SHARED body (entries + session_meta LAST as the commit point), ALL in
+     *  (fail-closed), then the owner-guarded meta delete (`owner IS NOT DISTINCT FROM $n` = the PG `<=>`, defense-in-depth), then the
+     *  SHARED body (session_meta first, the in-txn claim read, then the old events out and the new ones in), ALL in
      *  ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry) — unlike importEntries' fresh-only INSERT. */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** @see TiDBSessionStore.insertValidatedLog — shared insert half of importEntries / replaceEntries (ONE source, no
-     *  drift): entries re-seq dense from 0 (ids/parents/payload/ts verbatim), THEN session_meta LAST as the commit point.
+    /** @see TiDBSessionStore.writeImportedLog — the shared write half of importEntries / replaceEntries (ONE source, no drift):
+     *  session_meta FIRST (create = occupy the row, an existing one ⇒ refused; replace = plain INSERT after the caller's owner-guarded
+     *  delete), the in-txn claim read on THIS connection (读写序律), then the entries re-seq dense from 0 (ids/parents/payload/ts verbatim).
      *  Runs inside the caller's open txn (`conn` already in BEGIN); the caller owns COMMIT/ROLLBACK + the validate gate. */
-    private insertValidatedLog;
+    private writeImportedLog;
     /** @see TiDBSessionStore.beginImportStaging — 2c P1d-β PUSH staging: stream batches into the shadow id
      *  `${realSessionId}#stg-${token}` (route-minted token), then commit (atomic swap) / abort. */
     beginImportStaging(realSessionId: string, token: string): StagingHandle;
@@ -188,7 +199,7 @@ export declare class PgSessionStore implements SessionStore {
     sweepStagingSessions(): Promise<number>;
     /** @see TiDBSessionStore.deleteSession — purge session_meta + session_event; idempotent (false if absent).
      *  Owner-guarded on session_meta.owner (`IS NOT DISTINCT FROM` = the PG `<=>`); the event purge is gated on the
-     *  owner-matched meta delete (session_event has no owner column). */
+     *  owner-matched meta delete (session_event has no owner column). A live run claim read inside the txn ⇒ `SessionActiveRunError`. */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     get size(): number;
     dispose(): void;