@sema-agent/server 7.145.0 → 7.147.0

package/dist/plugins/retention-lane-store-sql.d.ts

@@ -23,14 +23,84 @@
  *     自增判据在**应用层**算,因为它同时要产出返回给调用方的 token);
  *   - 事务动词:只有 `begin()` 一个;读语义的判据在 {@link SqlTxConn.begin} 的 `@contract txn.read-semantics`
  *     (本店唯一的读是 `acquire` 的租约行 `FOR UPDATE` —— 锁读在两引擎都是当前读)。
- *   - schema 属主:**四张表全部由车1 的 `retention-store-sql.ts` 建**(`TIDB_RETENTION_STATEMENTS` /
- *     `PG_RETENTION_SCHEMA`)。本文件一条 DDL 都不发 —— 「一张表恰好一个 DDL 属主」(db-gate.ts 顶注
+ *   - schema 属主:**审计 / hold / 租约三张表由本文件建**(`TIDB_RETENTION_LANE_STATEMENTS` / `PG_RETENTION_LANE_SCHEMA`,
+ *     中央 ensure 组合);墓碑表是执行器的(`stores-sql/retention-store-sql.ts`)。「一张表恰好一个 DDL 属主」(db-gate.ts 顶注
  *     的实测结论:第二个属主的 `IF NOT EXISTS` 会静默吞掉列/索引差异)。
+ *   - 执行器破坏性事务里的两句也写在这里(`lockHoldSentinel` 首句 / `appendDestructiveAuditRow` 末句):hold / 审计是**调度方语义**,
+ *     经执行器的事务内钩(K4)参与,不住在执行器里。
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type SqlDriver, type SqlExec } from "./sql-driver.js";
-import { type RetentionAuditAction } from "./retention-store-sql.js";
+import { type SqlDialect, type SqlDriver, type SqlExec } from "./sql-driver.js";
+import type { IndexSpec } from "./ensure-index.js";
+import type { RetentionMode } from "../config-types.js";
+/** 追加式审计表(设计稿 §6)。 */
+export declare const RETENTION_AUDIT_TABLE = "retention_audit";
+/** per-domain 法务保留标记(设计稿 §5)——**行在 = 该域整体冻结**。 */
+export declare const RETENTION_HOLD_TABLE = "retention_hold";
+/** sweep 互斥的单行租约表(设计稿 §3)。表建在车1(schema 一次齐),抢/续租的逻辑归车2。 */
+export declare const RETENTION_LEASE_TABLE = "retention_lease";
+/**
+ * 审计行的 `action` 闭集(设计稿 §6 逐字)。**破坏性三词**在执行器的删除事务里由 audit 钩写({@link appendDestructiveAuditRow});其余五词
+ * (`audit_only` / `skipped_legal_hold` / `failed` / `hold_placed` / `hold_released`)属主是 lane/路由(车2)
+ * —— 它们没有「删了没记」的窗口。词表与审计表同住本文件:一份真源。
+ */
+export type RetentionAuditAction = "expired_checkpoints" | "deleted_sessions" | "deleted_tool_results" | "audit_only" | "skipped_legal_hold" | "failed" | "hold_placed" | "hold_released";
+/** MySQL 协议方言的建表语句(本模块是这三张表的唯一 DDL 属主;由 `tidb-pool.ts` 展开进中央 `SCHEMA_STATEMENTS`,紧挨执行器的墓碑表那一句、次序不变)。 */
+export declare const TIDB_RETENTION_LANE_STATEMENTS: readonly string[];
+/** PG 方言的建表语句(MySQL 孪生的逐条翻译:AUTO_INCREMENT→BIGSERIAL,逐列 `COLLATE "C"`,内联 KEY→独立
+ *  CREATE INDEX)。语义逐字见 MySQL 孪生的行内注,此处不复述(两份注释迟早分叉)。由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合(紧挨墓碑表那一句)。 */
+export declare const PG_RETENTION_LANE_SCHEMA: readonly string[];
+/** [ref]:三张表的索引**声明**(两方言共用一份)。PG 侧由 `pg-pool.ts` 的中央 ensure 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const RETENTION_LANE_INDEXES: readonly IndexSpec[];
+/**
+ * 一次破坏性留存调用的**审计上下文**——判定时点的三格,由调用方(lane)随每次破坏性调用交给组合座(`plugins/store-backend.ts`
+ * `createSqlRetentionExecutor`),组合座把它绑进**这一次**调用的 audit 钩(执行器入参只有 core 的 `{domain, cutoffMs}`,不认识它)。
+ *
+ * 🔴 为什么必须由调用方传、而不是店自己去读配置:`mode`/`policyDays` 是**判定时点**的事实(策略是部署
+ * env、模式是灰度旋钮,两者都会在两次 sweep 之间被改),`fencingToken` 更是本轮租约的身份。店去现读
+ * 配置 = 审计行记的是「写这行的那一刻的配置」,而不是「按哪档删的」,那正好把审计的意义抹掉。
+ */
+export interface RetentionAuditContext {
+    /** 判定时点的灰度档。词表闭集(与 §4 同一张表);`audit-only` 档下 lane 不该调破坏性方法,但如果调了,
+     *  审计行会如实记下这个矛盾(而不是被悄悄改写成 enforce)。 */
+    mode: RetentionMode;
+    /** 判定时点的策略值(天)。 */
+    policyDays: number;
+    /** 本轮 sweep lease 的 fencing token(§3)。`null` = 调用方没有租约面(单机/测试);破坏性行仍会落
+     *  审计,只是这一位为空 —— 「没有轮次身份」本身也是审计要记的事实。 */
+    fencingToken: number | null;
+}
+/**
+ * 破坏性事务的**首句**(K4 `holdLock`):拿本域的互斥行锁,并读出「这个域是不是冻结中」(§5 F2 承重)。持有到提交,无复核。
+ *
+ * 两步,缺一不可:
+ *  ① 幂等建一条 `held = 0` 的**哨兵行**(形 A,[ref]:MySQL `ON DUPLICATE KEY UPDATE domain = domain` /
+ *     PG `ON CONFLICT DO NOTHING`)—— 它永远不会改写一条既存的 hold(两方言的这两个动词都只在缺行时
+ *     写),只保证**接下来那把行锁有东西可锁**;重复键取的是 **X** 锁,与 ② 的 `FOR UPDATE` 同锁模式
+ *     (`INSERT IGNORE` 在这里取 S 再升 X = InnoDB 上两个并发 sweep 互等的死锁形,[ref]);
+ *  ② `SELECT held … FOR UPDATE` —— 现在这行必定存在,于是锁真的拿到了。
+ *
+ * 🔴 为什么必须先造行(codex 交叉复审 R1-[high],验真后改):`FOR UPDATE` 锁不住缺席行(TiDB 无 gap
+ * lock;PG READ COMMITTED 同样)。presence 形(「行在 = 冻结」)下,operator 的 PUT 与本事务可以**同时**
+ * 都读到「没有 hold」,PUT 提交返回成功之后本事务照删不误 —— 设计稿 §5 声称由行锁给出的串行化在那一形
+ * 上根本不存在。哨兵行把 hold 的写点与删除的读点压到**同一把行锁**上,那句承诺才成立。
+ * ⚠️ PUT/DELETE hold 必须走**同一 PK 的 upsert 改 `held` 列**(本模块 `setHoldOn`,不是 INSERT/DELETE 行),
+ * 否则这把锁又会退回缺席形。
+ */
+export declare function lockHoldSentinel(txn: SqlExec, dialect: SqlDialect, domain: string): Promise<boolean>;
+/**
+ * 破坏性审计行的**唯一**写点 —— 执行器事务里提交前的**末句**(K4 `audit`;§6 F5:与删除同一个事务,先删后补记 = 崩在中间会留下无证删除)。
+ * 三个数字 = 这一次调用的回执(执行器交给 audit 钩的那一份),判定时点三格 = 这一次调用的 {@link RetentionAuditContext}。
+ */
+export declare function appendDestructiveAuditRow(txn: SqlExec, dialect: SqlDialect, row: {
+    domain: string;
+    action: Extract<RetentionAuditAction, "expired_checkpoints" | "deleted_sessions" | "deleted_tool_results">;
+    audit: RetentionAuditContext;
+    deleted: number;
+    skipped: number;
+    tombstones: number;
+}): Promise<void>;
 /** 审计读面的单页上界(与 roster 名册窗同姿势:读面要有界)。 */
 export declare const RETENTION_AUDIT_MAX_LIMIT = 200;
 /** 审计读面的缺省页大小。 */

package/dist/plugins/retention-lane-store-sql.js

@@ -1,5 +1,107 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { RETENTION_AUDIT_TABLE, RETENTION_HOLD_TABLE, RETENTION_LEASE_TABLE } from "./retention-store-sql.js";
+export const RETENTION_AUDIT_TABLE = "retention_audit";
+export const RETENTION_HOLD_TABLE = "retention_hold";
+export const RETENTION_LEASE_TABLE = "retention_lease";
+export const TIDB_RETENTION_LANE_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_AUDIT_TABLE} (
+     id            BIGINT       NOT NULL AUTO_INCREMENT,
+     domain        VARCHAR(190) NOT NULL,
+     -- action:闭集词表见 RetentionAuditAction。前三词 = 破坏性行(本店写),其余 = lane/路由写。
+     action        VARCHAR(32)  NOT NULL,
+     -- mode:判定时点的灰度档(audit-only | enforce)——「按哪档跑的」必须与计数同行,否则事后无法解释
+     -- 一行 deleted=0 是"没有候选"还是"当时是 audit-only"。
+     mode          VARCHAR(16)  NOT NULL,
+     -- policy_days:判定时点的策略值(按哪版策略删的)。策略是部署 env,会被改;计数离开它就没有意义。
+     policy_days   INT          NOT NULL,
+     -- fencing_token:本轮 sweep lease 的 fencing token(§3;**破坏性行必填**,非破坏行可空)。丢租后
+     -- 在飞的旧轮仍可能提交一条审计行,靠这一位判别新旧轮。
+     fencing_token BIGINT       NULL,
+     -- 三数字 = RetentionReceipt(audit_only 行 = previewRetention 的三候选数)。
+     deleted       INT          NOT NULL DEFAULT 0,
+     skipped       INT          NOT NULL DEFAULT 0,
+     tombstones    INT          NOT NULL DEFAULT 0,
+     executed_at_ms BIGINT      NOT NULL,
+     error         TEXT         NULL,
+     PRIMARY KEY (id),
+     KEY idx_retention_audit_domain (domain, id),
+     KEY idx_retention_audit_executed (executed_at_ms)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_HOLD_TABLE} (
+     domain       VARCHAR(190) NOT NULL,
+     -- held:**1 = 冻结中,0 = 只是一把锁**。
+     -- 🔴 为什么冻结不能用「行在/行不在」表达(codex 对抗复审 R1-[high],验真后改的**承重**形):
+     -- 设计稿 §5 声称「PUT hold 的 commit 一旦完成,其后任何删除事务都必然看见它,串行化由行锁给出」——
+     -- 而 SELECT … FOR UPDATE **锁不住一条不存在的行**(TiDB 无 gap lock;PG 的 READ COMMITTED 同样
+     -- 不锁缺席行)。presence 形下两边都读到「没有 hold」是完全可能的,于是 operator 拿到成功回执之后
+     -- 数据仍被删 —— 那正是 F2 要消灭的那件事,只是换了个位置复发。
+     -- ⇒ 行**恒存在**(破坏性事务首步幂等建一条 held=0 的哨兵),冻结与否写在这一列上。
+     -- 于是 hold 的放置(同一 PK 的 upsert)与三只破坏性事务抢的是**同一把行锁**,串行化由引擎给出:
+     -- PUT 提交完成 ⇒ 其后每一个破坏性事务的首读必见 held=1。放置/解除都必须走这一列(车2 交接件)。
+     held         TINYINT(1)   NOT NULL DEFAULT 0,
+     placed_by    VARCHAR(190) NULL,
+     placed_at_ms BIGINT       NULL,
+     note         TEXT         NULL,
+     PRIMARY KEY (domain)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_LEASE_TABLE} (
+     -- singleton:恒 'x' 的单行键(全局唯一一只 sweep 租约)。用定值列而不是 id=1,是为了让"这张表只能有
+     -- 一行"写在**主键**上而不是写在注释里。
+     singleton     CHAR(1)      NOT NULL DEFAULT 'x',
+     holder        VARCHAR(190) NOT NULL,
+     -- fencing_token:每次**抢租**(而非续租)自增;随本轮全部审计行走,旧轮的写因此可判别。
+     fencing_token BIGINT       NOT NULL DEFAULT 0,
+     expires_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (singleton)
+   ) COLLATE utf8mb4_bin`,
+];
+export const PG_RETENTION_LANE_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_AUDIT_TABLE} (
+     id            BIGSERIAL,
+     domain        VARCHAR(190) COLLATE "C" NOT NULL,
+     action        VARCHAR(32) COLLATE "C"  NOT NULL,
+     mode          VARCHAR(16) COLLATE "C"  NOT NULL,
+     policy_days   INT          NOT NULL,
+     fencing_token BIGINT       NULL,
+     deleted       INT          NOT NULL DEFAULT 0,
+     skipped       INT          NOT NULL DEFAULT 0,
+     tombstones    INT          NOT NULL DEFAULT 0,
+     executed_at_ms BIGINT      NOT NULL,
+     error         TEXT COLLATE "C"         NULL,
+     PRIMARY KEY (id)
+   )`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_HOLD_TABLE} (
+     domain       VARCHAR(190) COLLATE "C" NOT NULL,
+     -- held:1 = 冻结中,0 = 只是那把域级互斥行锁的哨兵。完整判据(为什么 presence 形不成立)见 MySQL 孪生。
+     held         SMALLINT     NOT NULL DEFAULT 0,
+     placed_by    VARCHAR(190) COLLATE "C" NULL,
+     placed_at_ms BIGINT       NULL,
+     note         TEXT COLLATE "C"         NULL,
+     PRIMARY KEY (domain)
+   )`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_LEASE_TABLE} (
+     singleton     CHAR(1) COLLATE "C"      NOT NULL DEFAULT 'x',
+     holder        VARCHAR(190) COLLATE "C" NOT NULL,
+     fencing_token BIGINT       NOT NULL DEFAULT 0,
+     expires_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (singleton)
+   )`,
+];
+export const RETENTION_LANE_INDEXES = [
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_domain", columns: ["domain", "id"] },
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_executed", columns: ["executed_at_ms"] },
+];
+export async function lockHoldSentinel(txn, dialect, domain) {
+    const key = domain;
+    const q = (mysql, pg) => (dialect === "mysql" ? mysql : pg);
+    await txn.query(q(`INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES (?,0,NULL,NULL,NULL) ON DUPLICATE KEY UPDATE domain = domain`, `INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES ($1,0,NULL,NULL,NULL) ON CONFLICT (domain) DO NOTHING`), [key]);
+    const { rows } = await txn.query(q(`SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = ? FOR UPDATE`, `SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = $1 FOR UPDATE`), [key]);
+    return Number(rows[0]?.held ?? 0) === 1;
+}
+export async function appendDestructiveAuditRow(txn, dialect, row) {
+    await txn.query(dialect === "mysql"
+        ? `INSERT INTO ${RETENTION_AUDIT_TABLE} (domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms) VALUES (?,?,?,?,?,?,?,?,?)`
+        : `INSERT INTO ${RETENTION_AUDIT_TABLE} (domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`, [row.domain, row.action, row.audit.mode, row.audit.policyDays, row.audit.fencingToken, row.deleted, row.skipped, row.tombstones, Date.now()]);
+}
 export const RETENTION_AUDIT_MAX_LIMIT = 200;
 export const RETENTION_AUDIT_DEFAULT_LIMIT = 50;
 export class SqlRetentionLaneStore {

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

@@ -0,0 +1,29 @@
+/**
+ * 托管留存的两只 SQL 谓词 —— 执行器(`stores-sql/retention-store-sql.ts`,引擎座表那一半)与部署的事务内钩(`plugins/retention-deployment.ts`,
+ * 部署表那一半)对**同一条域律**发谓词,只从这里取:一条律一个读法,两半不各写一份(分家的方向是多删或漏删)。
+ *
+ * 域 = 租户键:`COALESCE(session_meta.owner, '')` / `checkpoint.scope` 原样;**空串 `''` = 无主(anonymous/dev)桶**,谓词写成
+ * `(owner IS NULL OR owner = '')` —— 合并只发生在无主侧,永远伸不进一个真租户;拆成两个桶才会漏(NULL 那半永不被枚举)。
+ */
+import type { SqlDialect } from "./sql-driver.js";
+/**
+ * 域谓词。**四种写法逐条写出来**(方言 × 有主/无主):
+ *  · 有主:`col = ?` / `col = $n`;
+ *  · 无主(域键 `""`):`(col IS NULL OR col = ?)` / `(col IS NULL OR col = $n)`。
+ * 🔴 两支的**占位符数量刻意相同**(无主支也绑一个 `""`):arity 一变,PG 的 `$n` 编号就会在同一条 SQL 的
+ * 后续参数上错位——那是一类只在某个域值上才复现的 bug,不许存在。
+ */
+export declare function retentionDomainWhere(dialect: SqlDialect, col: string, domain: string, pgIndex: number): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * 多值集合谓词 —— **真方言分叉**(不是 SQL 文本差):MySQL 展开 N 个 `?`,PG 用**一枚**数组参数
+ * `= ANY($n::text[])`。占位符数量因此不同(N vs 1),这是先例(workflow-run-store-sql 的 reap)也是
+ * 必然:把 500 个 id 展开成 500 个 `$n` 会让语句文本随批量变形,PG 的预编译缓存跟着退化。
+ */
+export declare function retentionIdSet(dialect: SqlDialect, col: string, ids: readonly string[], pgIndex: number): {
+    sql: string;
+    params: unknown[];
+};
+//# sourceMappingURL=retention-sql.d.ts.map

package/dist/plugins/retention-sql.js

@@ -0,0 +1,8 @@
+export function retentionDomainWhere(dialect, col, domain, pgIndex) {
+    const ph = dialect === "mysql" ? "?" : `$${pgIndex}`;
+    return domain === "" ? { sql: `(${col} IS NULL OR ${col} = ${ph})`, params: [""] } : { sql: `${col} = ${ph}`, params: [domain] };
+}
+export function retentionIdSet(dialect, col, ids, pgIndex) {
+    return dialect === "mysql" ? { sql: `${col} IN (${ids.map(() => "?").join(",")})`, params: [...ids] } : { sql: `${col} = ANY($${pgIndex}::text[])`, params: [ids] };
+}
+//# sourceMappingURL=retention-sql.js.map

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

@@ -6,7 +6,7 @@ import { pgSanitizeText } from "./pg-safe-json.js";
 import { toIso as iso } from "./sql-row-helpers.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonObjectColumn, readNonNullJsonValueColumn } from "./sql-json-column.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, readLegacyHolderDeathCode, settledLegObservationOf } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, settledLegObservationOf } from "./store-contracts.js";
 import { notifyRunTerminal, runTerminalLogLevel } from "../observability/run-terminal.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder, SQL_DB_NOW_MS, sqlDbNowMs } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
@@ -310,7 +310,7 @@ export class SqlRunStore {
             status: r.status,
             result: refusing("serve a finished run as if it had produced nothing", () => decodeResultColumn(r.result, String(r.task_id))) ?? null,
             error: r.error ?? null,
-            errorCode: readLegacyHolderDeathCode({ status: String(r.status), error: r.error ?? null, errorCode: r.error_code ?? null }),
+            errorCode: r.error_code ?? null,
             jobId: r.job_id ?? null,
             source: r.source ?? null,
             identity: readRunIdentityCells(r.identity_source, r.identity_scope, r.identity_principal_inc),

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

@@ -73,12 +73,6 @@ export interface ParsedTable {
 export declare function parseCreateTable(stmt: string): ParsedTable | undefined;
 /** 启动时真会建出来的**全部**表形(录制 → 解析)。同名表二次出现以**先到**为准(`IF NOT EXISTS` 的真语义)。 */
 export declare function expectedTableShapes(dialect: SqlDialect): Promise<Map<string, ParsedTable>>;
-/**
- * 拒启码(机读)。附录 A / 拒启码表的登记名。含义 = 「本构建读不出的持久形,开始服务之前判」,一个码三只臂:本文件的列册对账与退役 schema 两道(SQL),
- * 以及 local 数据根的严格边档对账(`local-session-store.ts` 的 `LocalDataRootSchemaMismatchError`,`LocalBackend.ensureSchema()` 调;拒句同形:
- * 码开头的表头 · 逐坐标一段 · 「NEWER than this build」方向句 · 闭集出路)。
- */
-export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
 /** 一张表的对账结论。 */
 export interface TableMismatch {
     readonly table: string;

package/dist/plugins/schema-consistency.js

@@ -1,7 +1,7 @@
 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";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
 const QUOTES = new Set(["'", '"', "`"]);
 function stripLineComments(sql) {
     let out = "";
@@ -106,7 +106,6 @@ export async function expectedTableShapes(dialect) {
     }
     return shapes;
 }
-export const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
 export function diffSchema(expected, live) {
     const out = [];
     for (const [table, shape] of expected) {

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

@@ -6,7 +6,7 @@ export declare const LOCK_RE: RegExp;
  * **「一个新库对 ensure 探针怎么答」的唯一属主**(合并复审 车HB 后收口:此前生成器录制器、`test/ensure-schema.test.ts`
  * 的假池、`test/schema-baseline-generated.test.ts` ③c 的假驱动各抄一份,[ref] 加了索引探针 + PG 锁改 `got === true`
  * 之后三份各漂一处 —— 假池答零行诱发 68 条 ALTER、③c 答 `got: 1` 让 PG 锁永远拿不到)。
- * 返回 `undefined` = 不是探针,由调用方录制 / 执行;三条例外的理由见上面三条正则的注。
+ * 返回 `undefined` = 不是探针,由调用方录制 / 执行;四条例外的理由见上面三条正则与 {@link newDatabaseSessionMetaKeyCollation} 的注。
  */
 export declare function answerEnsureProbe(text: string): {
     rows: Record<string, unknown>[];

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

@@ -1,13 +1,14 @@
-import { ensureSchema } from "./tidb-pool.js";
+import { SCHEMA_STATEMENTS, ensureSchema } from "./tidb-pool.js";
+import { SESSION_META_KEY_COLLATION_PROBE } from "./session-ext-table.js";
 import { ensurePgSchema } from "./pg-pool.js";
 import { ensureTiDBMemoryEngineSchema } from "./memory-engine-tidb.js";
 import { ensurePgMemoryEngineSchema } from "./memory-engine-pg.js";
 import { ensurePgMemoryEmbedderMetaSchema } from "./memory-embedder-fingerprint.js";
 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 { ensureTiDBRosterSchema, ensurePgRosterSchema } from "../stores-sql/roster-store-sql.js";
 import { ensureTiDBBackgroundAgentSchema, ensurePgBackgroundAgentSchema } from "../stores-sql/background-agent-store-sql.js";
-import { ensureTiDBMailboxSchema, ensurePgMailboxSchema } from "./mailbox-store-sql.js";
+import { ensureTiDBMailboxSchema, ensurePgMailboxSchema } from "../stores-sql/mailbox-store-sql.js";
 import { ensureTiDBTaskAttachmentSchema, ensurePgTaskAttachmentSchema } from "./task-attachment-store.js";
 import { ensureTiDBUsageWindowSchema, ensurePgUsageWindowSchema } from "../stores-sql/usage-window-store-sql.js";
 import { ensureTiDBTaskListSchema, ensurePgTaskListSchema } from "./task-list-store-sql.js";
@@ -15,6 +16,13 @@ import { ensureTiDBDeviceSchema, ensurePgDeviceSchema } from "./device-store-sql
 export const LOCK_RE = /GET_LOCK|RELEASE_LOCK|pg_(try_)?advisory/i;
 const INDEX_PROBE_RE = /FROM information_schema\.statistics\b/i;
 const PG_INDEX_VALID_RE = /FROM pg_index i WHERE i\.indexrelid = to_regclass/i;
+function newDatabaseSessionMetaKeyCollation() {
+    const stmt = SCHEMA_STATEMENTS.find((s) => s.includes("CREATE TABLE IF NOT EXISTS session_meta ("));
+    const m = stmt === undefined ? null : /\)\s*COLLATE\s+([A-Za-z0-9_]+)\s*$/.exec(stmt);
+    if (m === null)
+        throw new Error("schema-ensure-legs: the central session_meta statement carries no table-level COLLATE — cannot answer the session_ext key-collation probe for a new database");
+    return { cs: m[1].split("_")[0], coll: m[1] };
+}
 export function answerEnsureProbe(text) {
     if (LOCK_RE.test(text))
         return { rows: [{ got: true }] };
@@ -22,6 +30,8 @@ export function answerEnsureProbe(text) {
         return { rows: [{ present: 1 }] };
     if (PG_INDEX_VALID_RE.test(text))
         return { rows: [{ indisvalid: true }] };
+    if (text === SESSION_META_KEY_COLLATION_PROBE)
+        return { rows: [newDatabaseSessionMetaKeyCollation()] };
     return undefined;
 }
 function recorder() {

package/dist/plugins/session-ext-table.d.ts

@@ -0,0 +1,74 @@
+import { StoreBootRefusalError } from "./store-contracts.js";
+import type { SqlDialect, SqlDriver } from "./sql-driver.js";
+/** 表名(建表句、语句模块、迁移同读)。 */
+export declare const SESSION_EXT_TABLE = "session_ext";
+/** 一列:名字 + 两方言定义。 */
+export interface SessionExtColumn {
+    readonly name: string;
+    readonly mysql: string;
+    readonly pg: string;
+}
+/**
+ * 执行放置七列 + `fork_key` —— 宽度:车道词 ≤ 32、设备 id 与 `device` 表同宽 64、属主两列与设备店同宽 190、fork 键 255(服务端拼的不透明串)。
+ * 全部可空:NULL = absent / 非键控 fork。一次性迁移 M32(7.139–7.146 形:这八列在 `session_meta` 上)读同一份定义。
+ */
+export declare const EXECUTION_PLACEMENT_COLUMNS: readonly SessionExtColumn[];
+/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的就是这一组。 */
+export declare const SESSION_EXT_COLUMNS: readonly SessionExtColumn[];
+/** 外键约束名(两方言同名;起服探针与迁移的后置条件按名读)。 */
+export declare const SESSION_EXT_FOREIGN_KEY = "fk_session_ext_session";
+/** 被引列 `session_meta.session_id` 的字符集与排序规则(MySQL 协议方言;外键列逐字带上,见顶注「外键列的字符集与排序规则取自被引列」)。 */
+export interface ReferencedKeyCollation {
+    readonly characterSet: string;
+    readonly collation: string;
+}
+/** 读被引列字符集 / 排序规则的那一句(只读;当前库、表 `session_meta`、列 `session_id`)。录制驱动按这一串认它、答新库的真相(`schema-ensure-legs.ts`)。 */
+export declare const SESSION_META_KEY_COLLATION_PROBE = "SELECT CHARACTER_SET_NAME AS cs, COLLATION_NAME AS coll FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'session_meta' AND COLUMN_NAME = 'session_id'";
+/** 探针读数 → 被引列的字符集与排序规则;恰一行、两格都是合形的名字才算读出,否则 `undefined`(调用方拒启,不猜)。 */
+export declare function readReferencedKeyCollation(rows: readonly unknown[]): ReferencedKeyCollation | undefined;
+/**
+ * 建表句(两方言;中央 `ensureSchema` 在 `session_meta` 之后发)。MySQL 协议方言必须给被引列的字符集与排序规则(外键列逐字带上它们);PostgreSQL 一形不收它。
+ */
+export declare function sessionExtDdl(dialect: "pg"): string;
+export declare function sessionExtDdl(dialect: "mysql", referenced: ReferencedKeyCollation): string;
+/** 旁表建不出 —— 起服拒(确定的拒启表态,起服对账一族同一个码 `config.schema_mismatch`):点名表名、外键列按被引列写下的字符集 / 排序规则(读得出时)与库的原句。 */
+export declare class SessionExtTableRefusedError extends StoreBootRefusalError {
+    readonly code = "config.schema_mismatch";
+    constructor(detail: string);
+}
+/**
+ * MySQL 协议方言建旁表(中央 `ensureSchema` 在 `session_meta` 建好之后调):读被引列的字符集 / 排序规则 → 按它铸建表句 → 建。`query` = 那条 DDL 连接上的一次查询(交回行)。
+ * 读不出被引列 ⇒ {@link SessionExtTableRefusedError};「库确定拒了这条建表句」只按本仓唯一判官的闭集认(`sql-errors.ts` 的 `isDeploymentFaultError`:外键两侧不相容 / 加不上外键 /
+ * 被引列缺索引 / 建表被存储引擎拒 / 表级权限拒 …)⇒ 同一只拒,原句随拒句;认不出的错(连接类故障、TiDB 的瞬时错、锁等待超时 …,带不带 SQL 状态码都一样)原样上抛 —— 开库等待窗重试它。
+ * 本模块不自带分类:判官加一码,这里随之。
+ */
+export declare function ensureSessionExtTableMysql(query: (sql: string) => Promise<readonly unknown[]>): Promise<void>;
+/** 一条语句:文本 + 按序的参数。 */
+export interface SessionExtStatement {
+    readonly text: string;
+    readonly values: readonly unknown[];
+}
+/**
+ * 补行(行在 ⇒ 不动):旁表写者在锁住根 `session_meta` 行之后、写格之前发。MySQL 协议方言的重复键臂改一只非键列成它自己(不碰主键 —— 子表主键即外键列,
+ * 改它会让引擎做一次外键检查);PG `ON CONFLICT DO NOTHING`。外键:根行必须在(调用方锁着它)。
+ */
+export declare function ensureSessionExtRowStatement(dialect: SqlDialect, sessionId: string): SessionExtStatement;
+/**
+ * 补行的**一批**形:按一句 SELECT(交回一列 `session_id`)补旁表行,行已在 ⇒ 不动任何格 —— 与 {@link ensureSessionExtRowStatement} 同一只冲突子句。
+ * SELECT 包成派生表 `picked`(只露 `session_id`)⇒ 冲突子句里的列名只可能指本表。只给一次性迁移用(运行期的写者一律按单行补,在锁住根行之后)。
+ */
+export declare function ensureSessionExtRowsStatement(dialect: SqlDialect, selectSessionIds: string): SessionExtStatement;
+/** 旁表的外键级联在这只库上不生效 —— 起服拒的机读码(确定的拒启表态,与 `config.schema_mismatch` 同一族)。 */
+export declare const SESSION_EXT_CASCADE_REFUSED_CODE = "config.session_ext_cascade_absent";
+/** 起服拒:旁表行没有随根行删掉。继承 {@link StoreBootRefusalError}(确定的拒启表态:再等也等不来另一个答案)。 */
+export declare class SessionExtCascadeAbsentError extends StoreBootRefusalError {
+    readonly dialect: SqlDialect;
+    readonly code = "config.session_ext_cascade_absent";
+    constructor(dialect: SqlDialect);
+}
+/**
+ * 起服能力探针(fail-closed):一只事务里插一行根会话 + 一行旁表、删根行、读旁表行,**回滚**(库零写)。旁表行还在 ⇒ {@link SessionExtCascadeAbsentError}。
+ * 读不到 / 写不进 ⇒ 原样上抛(证不出级联 ≠ 通过)。调用点:起服序列在建表之后、一次性迁移之前(`boot/stores.ts`)。
+ */
+export declare function assertSessionExtCascadeOn(db: Pick<SqlDriver, "dialect" | "connect">): Promise<void>;
+//# sourceMappingURL=session-ext-table.d.ts.map

package/dist/plugins/session-ext-table.js

@@ -0,0 +1,121 @@
+import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
+import { SESSION_WORKSPACE_COLUMN } from "./session-workspace-cell.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
+import { isDeploymentFaultError } from "./sql-errors.js";
+export const SESSION_EXT_TABLE = "session_ext";
+export const EXECUTION_PLACEMENT_COLUMNS = [
+    { name: "execution_role", mysql: "execution_role VARCHAR(16) NULL", pg: `execution_role VARCHAR(16) COLLATE "C"` },
+    { name: "execution_lane", mysql: "execution_lane VARCHAR(32) NULL", pg: `execution_lane VARCHAR(32) COLLATE "C"` },
+    { name: "execution_device_id", mysql: "execution_device_id VARCHAR(64) NULL", pg: `execution_device_id VARCHAR(64) COLLATE "C"` },
+    { name: "execution_device_owner_tenant", mysql: "execution_device_owner_tenant VARCHAR(190) NULL", pg: `execution_device_owner_tenant VARCHAR(190) COLLATE "C"` },
+    { name: "execution_device_owner_subject", mysql: "execution_device_owner_subject VARCHAR(190) NULL", pg: `execution_device_owner_subject VARCHAR(190) COLLATE "C"` },
+    { name: "execution_placed_at", mysql: "execution_placed_at DATETIME(3) NULL", pg: "execution_placed_at TIMESTAMPTZ(3)" },
+    { name: "execution_rev", mysql: "execution_rev BIGINT NULL", pg: "execution_rev BIGINT" },
+    { name: "fork_key", mysql: "fork_key VARCHAR(255) NULL", pg: `fork_key VARCHAR(255) COLLATE "C"` },
+];
+const PRODUCT_COLUMNS = [
+    { name: "title", mysql: `title VARCHAR(${SESSION_TITLE_MAX_CHARS}) NULL`, pg: `title VARCHAR(${SESSION_TITLE_MAX_CHARS}) COLLATE "C"` },
+    { name: "pinned", mysql: "pinned BOOLEAN NOT NULL DEFAULT FALSE", pg: "pinned BOOLEAN NOT NULL DEFAULT FALSE" },
+    { name: "instruction_source", mysql: "instruction_source VARCHAR(64) NULL", pg: `instruction_source VARCHAR(64) COLLATE "C"` },
+    SESSION_WORKSPACE_COLUMN,
+];
+export const SESSION_EXT_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_COLUMNS];
+export const SESSION_EXT_FOREIGN_KEY = "fk_session_ext_session";
+export const SESSION_META_KEY_COLLATION_PROBE = "SELECT CHARACTER_SET_NAME AS cs, COLLATION_NAME AS coll FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'session_meta' AND COLUMN_NAME = 'session_id'";
+const COLLATION_NAME_RE = /^[A-Za-z0-9_]{1,64}$/;
+export function readReferencedKeyCollation(rows) {
+    if (rows.length !== 1)
+        return undefined;
+    const row = rows[0];
+    const cs = row?.cs;
+    const coll = row?.coll;
+    return typeof cs === "string" && typeof coll === "string" && COLLATION_NAME_RE.test(cs) && COLLATION_NAME_RE.test(coll) ? { characterSet: cs, collation: coll } : undefined;
+}
+export function sessionExtDdl(dialect, referenced) {
+    if (dialect === "mysql" && referenced === undefined)
+        throw new Error("sessionExtDdl(mysql): the referenced column's character set and collation are required (the foreign key column copies them)");
+    const key = dialect === "pg" ? `session_id  VARCHAR(64) COLLATE "C" NOT NULL` : `session_id  VARCHAR(64) CHARACTER SET ${referenced.characterSet} COLLATE ${referenced.collation} NOT NULL`;
+    return (`CREATE TABLE IF NOT EXISTS ${SESSION_EXT_TABLE} (\n` +
+        `     ${key},\n` +
+        SESSION_EXT_COLUMNS.map((c) => `     ${c[dialect]},\n`).join("") +
+        "     PRIMARY KEY (session_id),\n" +
+        `     CONSTRAINT ${SESSION_EXT_FOREIGN_KEY} FOREIGN KEY (session_id) REFERENCES session_meta (session_id) ON DELETE CASCADE\n` +
+        (dialect === "pg" ? "   )" : "   ) COLLATE utf8mb4_bin"));
+}
+export class SessionExtTableRefusedError extends StoreBootRefusalError {
+    code = SCHEMA_MISMATCH_ERROR_CODE;
+    constructor(detail) {
+        super(`${SCHEMA_MISMATCH_ERROR_CODE}: this MySQL-protocol database cannot create table ${SESSION_EXT_TABLE} — refusing to start. ${detail} ` +
+            `The table's foreign key ${SESSION_EXT_FOREIGN_KEY} references session_meta (session_id) with ON DELETE CASCADE; its key column copies the character set and collation of session_meta.session_id. ` +
+            "Check that session_meta is an InnoDB table on MySQL (foreign keys need InnoDB on both sides), that the database supports foreign keys (TiDB from v6.6.0), " +
+            "and that session_meta.session_id is a character column. This check changed nothing in the database.");
+        this.name = "SessionExtTableRefusedError";
+    }
+}
+export async function ensureSessionExtTableMysql(query) {
+    const rows = await query(SESSION_META_KEY_COLLATION_PROBE);
+    const referenced = readReferencedKeyCollation(rows);
+    if (referenced === undefined) {
+        throw new SessionExtTableRefusedError(`Reading the character set and collation of session_meta.session_id from information_schema.COLUMNS gave ${rows.length} row(s) without two readable names, so the foreign key column cannot be declared to match it.`);
+    }
+    try {
+        await query(sessionExtDdl("mysql", referenced));
+    }
+    catch (err) {
+        if (!isDeploymentFaultError(err))
+            throw err;
+        const { sqlState, sqlMessage: said } = err;
+        const sentence = typeof said === "string" ? said : err instanceof Error ? err.message : String(err);
+        throw new SessionExtTableRefusedError(`The foreign key column was declared CHARACTER SET ${referenced.characterSet} COLLATE ${referenced.collation} (read from session_meta.session_id); the database answered: ${sentence.split(/\r?\n/, 1)[0] ?? ""}${typeof sqlState === "string" ? ` (SQLSTATE ${sqlState})` : ""}.`);
+    }
+}
+export function ensureSessionExtRowStatement(dialect, sessionId) {
+    return { text: `INSERT INTO ${SESSION_EXT_TABLE} (session_id) VALUES (${dialect === "pg" ? "$1" : "?"}) ${ensureConflictClause(dialect)}`, values: [sessionId] };
+}
+export function ensureSessionExtRowsStatement(dialect, selectSessionIds) {
+    return { text: `INSERT INTO ${SESSION_EXT_TABLE} (session_id) SELECT picked.session_id FROM (${selectSessionIds}) picked ${ensureConflictClause(dialect)}`, values: [] };
+}
+function ensureConflictClause(dialect) {
+    return dialect === "pg" ? "ON CONFLICT (session_id) DO NOTHING" : "ON DUPLICATE KEY UPDATE pinned = pinned";
+}
+export const SESSION_EXT_CASCADE_REFUSED_CODE = "config.session_ext_cascade_absent";
+export class SessionExtCascadeAbsentError extends StoreBootRefusalError {
+    dialect;
+    code = SESSION_EXT_CASCADE_REFUSED_CODE;
+    constructor(dialect) {
+        super(`${SESSION_EXT_CASCADE_REFUSED_CODE}: on this ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database, deleting a session row did not delete its ${SESSION_EXT_TABLE} row ` +
+            `(the foreign key ${SESSION_EXT_FOREIGN_KEY} … ON DELETE CASCADE is not enforced) — refusing to start: a session id registered again would inherit the previous occupant's ` +
+            "title, pin, instruction baseline and execution placement. " +
+            (dialect === "pg"
+                ? "Check that the constraint exists on the table (it is created with the table) and that no session_replication_role / trigger setting disables it."
+                : "On TiDB, foreign keys are enforced from v6.6.0 with the session variable foreign_key_checks=ON (the default; a DSN or global setting may turn it OFF); " +
+                    `on MySQL, the table must be InnoDB. If the table was created while foreign keys were not enforced, drop the (empty) ${SESSION_EXT_TABLE} table and start again.`));
+        this.dialect = dialect;
+        this.name = "SessionExtCascadeAbsentError";
+    }
+}
+const CASCADE_PROBE_ID = "~session-ext-cascade-probe";
+export async function assertSessionExtCascadeOn(db) {
+    const conn = await db.connect();
+    try {
+        await conn.begin();
+        const p = db.dialect === "pg" ? (n) => `$${n}` : () => "?";
+        const now = new Date();
+        await conn.query(`INSERT INTO session_meta (session_id, created_at, updated_at) VALUES (${p(1)}, ${p(2)}, ${p(3)})`, [CASCADE_PROBE_ID, now, now]);
+        const ensure = ensureSessionExtRowStatement(db.dialect, CASCADE_PROBE_ID);
+        await conn.query(ensure.text, [...ensure.values]);
+        await conn.query(`DELETE FROM session_meta WHERE session_id = ${p(1)}`, [CASCADE_PROBE_ID]);
+        const left = await conn.query(`SELECT session_id FROM ${SESSION_EXT_TABLE} WHERE session_id = ${p(1)}`, [CASCADE_PROBE_ID]);
+        await conn.rollback();
+        if (left.rows.length !== 0)
+            throw new SessionExtCascadeAbsentError(db.dialect);
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+}
+//# sourceMappingURL=session-ext-table.js.map

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

@@ -13,10 +13,15 @@
  * 吃一只 `Session`):唤醒出来的会话 `getEntry` 在地板之下会回读持久日志,所以判官在压缩过的会话上也看得见整条叶链。
  *
  * ## fork 续写的店契约(本文件下半)
- * 三店同一只私有体 `forkTo(sourceId, owner, { id, key? })`:目标行原子新建(唯一创建点)· 撞已在按属主与 fork 键分类({@link classifyForkTarget})·
- * local 崩溃中间态 `forking` 只许同键重试补齐 · fork 键此后每个写携带(整段换装经 `carriedRowCells`)。core 契约 `fork(sourceId, owner?)` = {@link forkByFreshId}。
+ * 三店同一只私有体 `forkTo(sourceId, owner, target)`:目标行原子新建(唯一创建点)· 撞已在按属主与 fork 键分类({@link classifyForkTarget})·
+ * local 崩溃中间态 `forking` 只许同键重试补齐 · fork 键此后每个写携带(整段换装:local 经 `carriedRowCells`,SQL 就地改写、旁表行不动)。core 契约 `fork(sourceId, owner?, opts?)` = {@link forkByFreshId}。
+ *
+ * ## fork 进委派分区(core `SessionStore.fork` 的 `opts.placement`)
+ * fork 的创建那一笔就是一次建行:带元组的 fork 与带 placement 的 acquire 落**同一组**元组(六列 / 存档行头,first-write 不可变,`placedAt` 由店铸),
+ * 此后这一行欠 placed 行的每一条义务(不上宿主列表 · claim 形 acquire 拒 · 进分区枚举 · release = 真删除)。元组不带属主:行的属主仍是 fork 的属主参数
+ * 按 `forkOwnerOf` 的那一读(core 句:元组没有属主)。没声明分区的店照常 fork、不落元组(core 句:忽略合法,拒 fork 不合法)。
  */
-import { type ForkPoint, type ForkRowShape, type SessionStorage } from "@sema-agent/core";
+import { type ForkPoint, type ForkRowShape, type SessionStorage, type SessionStore } from "@sema-agent/core";
 /** 问引擎:这只(已唤醒的)源会话从哪里拷。SQL 孪生用它;local 店手里就是引擎的 `Session`,直接调 `settledForkOptions`。 */
 export declare function forkPointOf(storage: SessionStorage): Promise<ForkPoint>;
 /** 两只 SQL 孪生整份日志里的一行(两孪生选同一组列):父链两键交引擎挑行,其余三列原样搬进新会话、不读内容。 */
@@ -33,13 +38,27 @@ export interface ForkLogRow {
  */
 export declare const FORK_LOG_ROW_SHAPE: ForkRowShape<ForkLogRow>;
 /**
- * `forkTo` 的目标:调用方给的新会话 id 与(可选)fork 键。`key` 是服务端拼的不透明串(路由按「源 + 调用方 nonce」派生),存进新行那一格
- * `fork_key`(SQL)/ `forkKey`(local):一个事实 = 「建这一行的那次 fork 请求的键」。缺 = 非键控 fork(core 契约的现铸形)。
+ * fork 进委派分区时落的元组 —— core `SessionStore.fork` 第三参 `opts.placement` 的那一形,**直接取 core 的型、不复述**(core 当前写作 `SessionPlacement` 去掉属主:行的属主是
+ * fork 的属主参数的那一读)。本仓里这个元组型只有这一处定义:三店(local · pg · tidb)、路由店、`forkByFreshId`、引擎面声明的 fork 形参,以及建行绑定值
+ * `placementInsertValues`(`session-placement.ts`)都读它 —— core 再改 `fork` 的第三参,型面在这里一处跟着动(`SessionStore.fork` 是可选成员,所以取参数前先 `NonNullable`)。
+ */
+export type ForkPlacement = NonNullable<NonNullable<Parameters<NonNullable<SessionStore["fork"]>>[2]>["placement"]>;
+/**
+ * `forkTo` 的目标:调用方给的新会话 id,外加两者之一(或都没有):
+ *  · `key` —— 服务端拼的不透明串(路由按「源 + 调用方 nonce」派生),存进新行那一格 `fork_key`(SQL)/ `forkKey`(local):一个事实 = 「建这一行的那次 fork 请求的键」;
+ *  · `placement` —— 新行落进委派分区的元组(见文件头「fork 进委派分区」)。
+ * 两者互斥由型面说:带键的是客户端经路由的 fork(一位用户续一只会话,永不 placed —— placement 只走引擎的可信内部链),placed 的是引擎的 fork(后台 fork 子代的转录,
+ * 现铸 id、永不带键)⇒ {@link classifyForkTarget} 的重放判(键相等)永远碰不到 placed 目标。都缺 = 非键控、普通的 fork(core 契约的现铸形)。
  */
-export interface ForkTarget {
+export type ForkTarget = {
     readonly id: string;
     readonly key?: string;
-}
+    readonly placement?: undefined;
+} | {
+    readonly id: string;
+    readonly placement: ForkPlacement;
+    readonly key?: undefined;
+};
 /**
  * fork 键的**唯一**拼法(路由带键 ⇒ `forkTo(…, { id: forkId, key: forkKeyOf(源, forkNonce) })`):服务端拼的不透明串 —— 源 id 与调用方 nonce 的摘要,
  * 定长(远短于 `fork_key` 的 255),源进摘要 ⇒ 「异源同 nonce」拼出不同的键(撞同一只目标即 409,不当重放)。调用方不读它,只靠同键重试同答。
@@ -78,8 +97,11 @@ export declare class ForkTargetUnsettledError extends Error {
 /** 三店的 `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`。
+ * core 契约 `fork(sourceId, owner?, opts?) → string | null` = `forkTo(…, { id: uuidv7(), placement? })` 的投影(三店同一只):`created` ⇒ 新 id;源不在 ⇒ `null`。
+ * `opts.placement` 原样进目标(落不落由店判:声明了分区的店落,没声明的忽略 —— 各店 `forkTo` 一处)。
  * 新铸的 uuidv7 撞上已在的行(`occupied` / `replayed`)不是一个答案,是不变量破 ⇒ 响亮抛 —— 无键请求永不答 `replayed`。
  */
-export declare function forkByFreshId(forkTo: ForkToFn, sourceId: string, owner: string | null | undefined): Promise<string | null>;
+export declare function forkByFreshId(forkTo: ForkToFn, sourceId: string, owner: string | null | undefined, opts?: {
+    placement?: ForkPlacement;
+}): Promise<string | null>;
 //# sourceMappingURL=session-fork.d.ts.map

package/dist/plugins/session-fork.js

@@ -26,9 +26,10 @@ export class ForkTargetUnsettledError extends Error {
         this.name = "ForkTargetUnsettledError";
     }
 }
-export async function forkByFreshId(forkTo, sourceId, owner) {
+export async function forkByFreshId(forkTo, sourceId, owner, opts) {
     const id = uuidv7();
-    const out = await forkTo(sourceId, owner ?? null, { id });
+    const placement = opts?.placement;
+    const out = await forkTo(sourceId, owner ?? null, placement !== undefined ? { id, placement } : { id });
     if (out === null)
         return null;
     switch (out.outcome) {