@sema-agent/server 7.150.0 → 7.151.0

package/dist/stores-sql/session-policy-store-sql.js

@@ -87,11 +87,11 @@ export async function eraseSessionPolicyRowsOn(conn, dialect, sessionIds) {
 }
 export class SqlSessionPolicyStore {
     db;
-    countClientWrite;
+    root;
     logger;
-    constructor(db, countClientWrite, logger) {
+    constructor(db, root, logger) {
         this.db = db;
-        this.countClientWrite = countClientWrite;
+        this.root = root;
         this.logger = logger;
     }
     q(mysql, pg) {
@@ -124,50 +124,67 @@ export class SqlSessionPolicyStore {
         }));
     }
     async putRules(sessionId, principal, rules, opts) {
-        const key = policyKey(sessionId, principal);
         return this.retrying(() => this.tx(async (conn) => {
-            const root = await conn.query(this.q("SELECT session_id FROM session_meta WHERE session_id = ? FOR UPDATE", "SELECT session_id FROM session_meta WHERE session_id = $1 FOR UPDATE"), [sessionId]);
-            const { rows } = await conn.query(this.q(`SELECT ${jsonColumnText("mysql", RULES)}, rev, gen FROM session_policy WHERE policy_key = ? FOR UPDATE`, `SELECT ${jsonColumnText("pg", RULES)}, rev, gen FROM session_policy WHERE policy_key = $1 FOR UPDATE`), [key]);
-            const prior = rows[0] ? rowToStored(rows[0], `for session ${JSON.stringify(sessionId)} (pre-write snapshot)`) : undefined;
-            const priorRev = prior?.rev ?? 0;
-            if (opts?.expectedRev !== undefined && priorRev !== opts.expectedRev) {
-                throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${priorRev})`);
-            }
-            const { rows: markRows } = await conn.query(this.q("SELECT rev, gen FROM session_policy_rev_mark WHERE policy_key = ? FOR UPDATE", "SELECT rev, gen FROM session_policy_rev_mark WHERE policy_key = $1 FOR UPDATE"), [key]);
-            const markRev = markRows[0] ? Number(markRows[0].rev) : 0;
-            const markGen = markRows[0] ? Number(markRows[0].gen) : 0;
-            if (markRows[0] !== undefined && (!isStoredCounter(markGen, 0) || !isStoredCounter(markRev, 0))) {
-                throw new SessionPolicyError("corrupt", `the session rules rev mark for session ${JSON.stringify(sessionId)} is unreadable (rev ${String(markRows[0].rev)}, gen ${String(markRows[0].gen)}) — refusing rather than stamp a rev/lineage nothing proves`);
-            }
-            const clean = judgeSessionRulesWrite(prior ?? null, rules, opts);
-            if (this.db.dialect === "pg" && pgHasUnstorable(clean)) {
-                throw new SessionPolicyError("loosen_forbidden", "rules contain unstorable bytes (NUL / lone surrogate) — refused; strip them at the source (authorization rules are never rewritten by the store)");
-            }
-            const nextRev = Math.max(priorRev, markRev) + 1;
-            const nextGen = prior?.gen ?? markGen;
-            if (!isStoredCounter(nextRev, 1) || !isStoredCounter(nextGen, 0)) {
-                throw new SessionPolicyError("corrupt", `session rules for session ${JSON.stringify(sessionId)}: the next stamp (rev ${nextRev}, gen ${nextGen}) would leave the safe-integer range this store reads back — refusing before writing a row nothing could read`);
-            }
-            if (root.rows.length > 0)
-                await this.countClientWrite(conn, this.db.dialect, sessionId);
-            const json = JSON.stringify(clean);
-            const now = new Date();
-            if (prior) {
-                const upd = await conn.query(this.q(`UPDATE session_policy SET principal = ?, ${RULES} = ?, rev = ?, gen = ?, updated_at = ? WHERE policy_key = ? AND rev = ?`, `UPDATE session_policy SET principal = $1, ${RULES} = $2::jsonb, rev = $3, gen = $4, updated_at = $5 WHERE policy_key = $6 AND rev = $7`), [principal ?? null, json, nextRev, nextGen, now, key, priorRev]);
-                if (upd.affected !== 1)
-                    throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts?.expectedRev ?? priorRev}, have ${priorRev})`);
-            }
-            else {
-                await conn.query(this.q(`INSERT INTO session_policy (policy_key, session_id, principal, ${RULES}, rev, gen, created_at, updated_at) VALUES (?,?,?,?,?,?,?,?)`, `INSERT INTO session_policy (policy_key, session_id, principal, ${RULES}, rev, gen, created_at, updated_at) VALUES ($1,$2,$3,$4::jsonb,$5,$6,$7,$8)`), [key, sessionId, principal ?? null, json, nextRev, nextGen, now, now]);
-            }
-            return structuredClone({ ...clean, rev: nextRev, gen: nextGen });
+            const present = await this.root.lockRoot(conn, this.db.dialect, sessionId);
+            const out = await this.putRulesOn(conn, sessionId, principal, rules, opts, { count: present });
+            if ("skipped" in out)
+                throw new Error("SqlSessionPolicyStore.putRules: no skip predicate was given, yet the write was skipped");
+            return out;
         }));
     }
+    async putRulesOn(conn, sessionId, principal, rules, opts, how) {
+        const key = policyKey(sessionId, principal);
+        const { rows } = await conn.query(this.q(`SELECT ${jsonColumnText("mysql", RULES)}, rev, gen FROM session_policy WHERE policy_key = ? FOR UPDATE`, `SELECT ${jsonColumnText("pg", RULES)}, rev, gen FROM session_policy WHERE policy_key = $1 FOR UPDATE`), [key]);
+        const prior = rows[0] ? rowToStored(rows[0], `for session ${JSON.stringify(sessionId)} (pre-write snapshot)`) : undefined;
+        if (how.skip?.(prior ?? null) === true)
+            return { skipped: true };
+        const priorRev = prior?.rev ?? 0;
+        if (opts?.expectedRev !== undefined && priorRev !== opts.expectedRev) {
+            throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${priorRev})`);
+        }
+        const { rows: markRows } = await conn.query(this.q("SELECT rev, gen FROM session_policy_rev_mark WHERE policy_key = ? FOR UPDATE", "SELECT rev, gen FROM session_policy_rev_mark WHERE policy_key = $1 FOR UPDATE"), [key]);
+        const markRev = markRows[0] ? Number(markRows[0].rev) : 0;
+        const markGen = markRows[0] ? Number(markRows[0].gen) : 0;
+        if (markRows[0] !== undefined && (!isStoredCounter(markGen, 0) || !isStoredCounter(markRev, 0))) {
+            throw new SessionPolicyError("corrupt", `the session rules rev mark for session ${JSON.stringify(sessionId)} is unreadable (rev ${String(markRows[0].rev)}, gen ${String(markRows[0].gen)}) — refusing rather than stamp a rev/lineage nothing proves`);
+        }
+        const clean = judgeSessionRulesWrite(prior ?? null, rules, opts);
+        if (this.db.dialect === "pg" && pgHasUnstorable(clean)) {
+            throw new SessionPolicyError("loosen_forbidden", "rules contain unstorable bytes (NUL / lone surrogate) — refused; strip them at the source (authorization rules are never rewritten by the store)");
+        }
+        const nextRev = Math.max(priorRev, markRev) + 1;
+        const nextGen = prior?.gen ?? markGen;
+        if (!isStoredCounter(nextRev, 1) || !isStoredCounter(nextGen, 0)) {
+            throw new SessionPolicyError("corrupt", `session rules for session ${JSON.stringify(sessionId)}: the next stamp (rev ${nextRev}, gen ${nextGen}) would leave the safe-integer range this store reads back — refusing before writing a row nothing could read`);
+        }
+        if (how.count)
+            await this.root.countClientWrite(conn, this.db.dialect, sessionId);
+        const json = JSON.stringify(clean);
+        const now = new Date();
+        if (prior) {
+            const upd = await conn.query(this.q(`UPDATE session_policy SET principal = ?, ${RULES} = ?, rev = ?, gen = ?, updated_at = ? WHERE policy_key = ? AND rev = ?`, `UPDATE session_policy SET principal = $1, ${RULES} = $2::jsonb, rev = $3, gen = $4, updated_at = $5 WHERE policy_key = $6 AND rev = $7`), [principal ?? null, json, nextRev, nextGen, now, key, priorRev]);
+            if (upd.affected !== 1)
+                throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts?.expectedRev ?? priorRev}, have ${priorRev})`);
+        }
+        else {
+            await conn.query(this.q(`INSERT INTO session_policy (policy_key, session_id, principal, ${RULES}, rev, gen, created_at, updated_at) VALUES (?,?,?,?,?,?,?,?)`, `INSERT INTO session_policy (policy_key, session_id, principal, ${RULES}, rev, gen, created_at, updated_at) VALUES ($1,$2,$3,$4::jsonb,$5,$6,$7,$8)`), [key, sessionId, principal ?? null, json, nextRev, nextGen, now, now]);
+        }
+        return structuredClone({ ...clean, rev: nextRev, gen: nextGen });
+    }
+    isDupKeyError(e) {
+        return this.isDupKey(e);
+    }
     retrying(attempt) {
         return retryOnDeadlock(this.db.dialect, attempt, (e) => this.isDupKey(e));
     }
     async deleteBySession(sessionId) {
-        const sealed = await this.retrying(() => this.tx((conn) => eraseSessionPolicyRowsOn(conn, this.db.dialect, [sessionId])));
+        const sealed = await this.retrying(() => this.tx((conn) => this.eraseOn(conn, sessionId)));
+        this.discloseErased(sessionId, sealed);
+    }
+    eraseOn(conn, sessionId) {
+        return eraseSessionPolicyRowsOn(conn, this.db.dialect, [sessionId]);
+    }
+    discloseErased(sessionId, sealed) {
         if (sealed.length > 0)
             this.discloseSealed(sessionId, sealed);
     }
@@ -206,13 +223,13 @@ export class SqlSessionPolicyStore {
     }
 }
 export class TiDBSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool, countClientWrite, logger) {
-        super(mysqlDriver(pool), countClientWrite, logger);
+    constructor(pool, root, logger) {
+        super(mysqlDriver(pool), root, logger);
     }
 }
 export class PgSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool, countClientWrite, logger) {
-        super(pgDriver(pool), countClientWrite, logger);
+    constructor(pool, root, logger) {
+        super(pgDriver(pool), root, logger);
     }
 }
 //# sourceMappingURL=session-policy-store-sql.js.map

package/dist/stores-sql/session-write-hooks.d.ts

@@ -13,6 +13,10 @@
  * 不对别的表的行加锁,也不在 EvalPlanQual 里复判它们。所以是**两句**:店先 `FOR UPDATE` 锁根行(删除 / 重登记 / 改属主都要先拿这把锁),
  * 再在**同一连接**上交出语句面,部署用新语句锁定读(PG 新快照、TiDB 当前读)。钩里的写随店的事务提交或回滚(店拒、或任何一步抛,一起撤)。
  *
+ * ## 建行钩(服务扩展,包里没有)
+ * 带种类的登记(`registerWithReceipt` 的第三参;会话种类的律在 `session-kind.ts`):店在一只事务里 INSERT、锁定读回化身,读回的 = 本次铸的(这一笔真建了行)⇒
+ * {@link SessionWriteHooks.birth} 在同一事务里记下种类;别的(已在的行 / 并发登记里输的那一只)⇒ 零写。包随店搬家时这一组同是向引擎的请托。
+ *
  * ## 键控 fork(服务扩展,包里没有)
  * 调用方给目标 id 与键的 fork(`forkTo`)是本服务的扩展:键是部署格,在建目标行的同一事务里由 {@link SessionWriteHooks.keyedFork} 记下;撞上已在的目标时
  * 读它的属主与键。包随店搬家时这一组是向引擎的请托(带目标 id 与键的 fork,或钩表多一组)。
@@ -61,5 +65,12 @@ export interface SessionWriteHooks {
         }): Promise<void>;
         targetOf(sessionId: string): Promise<ForkTargetReading | undefined>;
     };
+    /** 建行钩(服务扩展,与键控 fork 同族):带种类的登记里,本事务的 INSERT 真建了这一行(锁定读回的化身 = 本次铸的)⇒ 在同一事务里记下它的种类(部署格的值,座原样转交、不解读;律在部署那一侧)。 */
+    readonly birth: {
+        record(txn: SessionTxStatements, born: {
+            readonly rootSessionId: string;
+            readonly kind: string;
+        }): Promise<void>;
+    };
 }
 //# sourceMappingURL=session-write-hooks.d.ts.map

package/dist/stores-sql/tidb-session-store.d.ts

@@ -13,10 +13,10 @@
 import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type RegisterReceipt, type WithdrawJudgeVerdict, type WithdrawOutcome } from "../session-incarnation.js";
+import { type RegisterReceipt, type SessionFace, type WithdrawJudgeVerdict, type WithdrawOutcome } from "../session-incarnation.js";
 import type { SessionTxStatements, SessionWriteHooks } from "./session-write-hooks.js";
 import { type PlacementAcquireOpts } from "../plugins/session-placement.js";
-import { type StagingHandle } from "../session-sync-kernel.js";
+import { type EntriesStreamOptions, type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "../plugins/session-fork.js";
 /**
  * **条件撤回的店那一半**(两方言一形;TiDB 孪生与 PG 孪生 `pg-session-storage.ts` 同调;撤回的规则在 `plugins/session-birth.ts` 头注)。
@@ -75,7 +75,7 @@ export declare class TiDBSessionStore implements SessionStore {
      * 出生回执面(`plugins/session-birth.ts`):与 {@link register} 同一笔 INSERT;候选化身 = 这一次 INSERT 入参里铸的那一只(不复读)。
      * 已在的行上 INSERT 是 no-op 臂 ⇒ 行上的化身不是候选 ⇒ 撤回在锁内比对时判「留」—— 出生事实只在那里判,这里不分新旧行。
      */
-    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: string): Promise<RegisterReceipt>;
     /** 条件删除(`plugins/session-birth.ts` 的撤回;本连接开事务 → 店与部署两半同一语句面 → 撤回才提交,否则回滚)。 */
     deleteSessionIf(sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
     /**
@@ -88,6 +88,8 @@ export declare class TiDBSessionStore implements SessionStore {
      *  **永不被重写**(first-write 不可变,义务 5 的写侧半场)。
      *  [ref]:化身与属主同一条 first-write 律 —— 新行铸一只(`mintSessionIncarnation`),已存在的行 no-op 臂一个字节不动。 */
     private insertMeta;
+    /** {@link insertMeta} 那一句,发在给定的连接上(带种类的登记在自己的事务连接上发,与锁定读、建行钩同一事务)。 */
+    private insertMetaOn;
     /**
      * [ref] 义务 6 的廉价探针 —— 一行 PK SELECT:`undefined` = 普通会话或无此行。
      * (release 的冷缓存腿、包装店的暖命中准入判、诊断面共用这一只。)
@@ -194,10 +196,7 @@ export declare class TiDBSessionStore implements SessionStore {
      * (按文本投影 + `decodeSessionEventPayload` 恰好解一次码,坏体当场拒). The check is eager (the method is async) because a generator body is lazy — it can't decide
      * `null` vs. iterable on its own first pull.
      */
-    exportEntriesStream(sessionId: string, opts?: {
-        afterSeq?: number;
-        batchSize?: number;
-    }): Promise<AsyncIterable<SessionTreeEntry> | null>;
+    exportEntriesStream(sessionId: string, opts: EntriesStreamOptions): Promise<AsyncIterable<SessionTreeEntry> | null>;
     /**
      * 2c session-sync — IMPORT a verbatim entry log (from another backend's {@link exportEntries}) into a
      * (typically NEW) `sessionId`. This is the WRITE half of {@link fork}, surfaced as `SessionRepo.importEntries`,
@@ -269,5 +268,57 @@ export declare class TiDBSessionStore implements SessionStore {
     get size(): number;
     dispose(): void;
 }
+/**
+ * 2c session-sync P1d-β (PUSH streaming, §15 + §4) — a TiDB {@link StagingHandle}: stream entry batches into a SHADOW
+ * `session_event` partition (the staging id, NO meta row → invisible to wake), then atomically SWAP them into the real
+ * session id. Server memory is bounded by the in-flight batch (one txn per batch), not the whole log. The swap is a
+ * row-key RENAME (`UPDATE session_event SET session_id`) — metadata-only, NO payload re-copy — so the commit cost is
+ * the rename + a DELETE of the (purged) dst rows, in ONE txn; the session_meta row is locked (or, for a fresh push, claimed) first and
+ * settled last, and COMMIT is the sole commit point.
+ */
+/** 暂存句柄(会话同步的推送腿逐批写、提交、撤销;由本店的 `stageImport` 交出)。导出只为组合座给它封口(店边界)。 */
+export declare class TiDBStagingHandle implements StagingHandle {
+    private readonly pool;
+    private readonly hooks;
+    readonly realSessionId: string;
+    readonly stagingId: string;
+    /** Running DENSE seq counter for the staging rows. Advanced ONLY for a logically-NEW entry id (tracked in `seen`), so
+     *  a re-streamed entry (Phase-B resume) is skipped and the staged seqs stay dense 0..N-1 (NO holes that would collide
+     *  with a future F2 leaf_seq append on the committed session). */
+    private nextSeq;
+    /** Entry ids already staged by THIS handle — a resume re-streams from the start, so dedup keeps seqs dense + idempotent. */
+    private readonly seen;
+    constructor(pool: Pool, hooks: SessionWriteHooks, realSessionId: string, stagingId: string);
+    /** Append a batch to the staging id, re-seq'd DENSE from the running counter (skipping ids already staged), IDEMPOTENTLY
+     *  (ON DUPLICATE KEY UPDATE on the `(session_id, entry_id)` uk is the durable backstop too). One txn per batch
+     *  (bounded). NO meta row is written (the staging id stays invisible). ts is the entry's own ISO timestamp (verbatim). */
+    appendBatch(entries: SessionTreeEntry[]): Promise<void>;
+    /**
+     * The ATOMIC swap (ONE txn), §15 commit:
+     *  0. OWNER CAS FIRST ([ref] — one gate predicate, two phases): the session's owner cell must still be the one the import's gate
+     *     judged (`opts.expectedOccupant`: owner ∧ incarnation). Like every other writer of a session (append, replace, delete) the staged commit takes the
+     *     session_meta row FIRST, then the logs — one lock order. A present cell: one conditioned UPDATE (current read; takes the row lock
+     *     until COMMIT); it bumps `leaf_seq` only as the CAS's always-changing column (a same-value UPDATE can read 0 affected rows on the
+     *     MySQL protocol depending on driver flags), and step 4 overwrites that column with the real value in the same txn. An absent cell
+     *     (a fresh push) cannot be locked, so it is CLAIMED: insert this commit's row now (a no-op on an existing key), then a locking read
+     *     must show the incarnation this commit minted — anything else is a row somebody else created. Either miss ⇒ ROLLBACK → throw
+     *     StagedCommitOccupantChangedError (route → 409), before anything about the row is read or reported (no placement, no relation,
+     *     no entry ids).
+     *  1. IN-COMMIT RE-CLASSIFY (closes the Phase-A plan→commit TOCTOU): read the dst's CURRENT entry ids + the staged
+     *     ids under `FOR UPDATE` (row-locks serialize a concurrent commit/run) → classifySyncRelationshipByIds. A flip
+     *     to fork/stale WITHOUT `resolution:"overwrite-dst"` → ROLLBACK → throw SyncConflictError (route → 409).
+     *  2. DELETE the dst's existing session_event rows (the replaceEntries purge).
+     *  3. UPDATE session_event SET session_id = real WHERE session_id = staging (the row-key RENAME — metadata only).
+     *  4. UPDATE session_meta(owner, leaf_id=replayedLeaf, leaf_seq=N) on the row step 0 locked or claimed; COMMIT is the sole commit point.
+     * A crash before COMMIT: the DELETE+rename roll back (dst untouched) and the staging rows keep no meta = invisible
+     * orphans (reaped by sweepStagingSessions). `owner` is the re-stamped importing principal (§9).
+     */
+    commit(owner: string | null, opts: StagedCommitOptions): Promise<{
+        relation: SyncRelation["relation"];
+        face: SessionFace;
+    }>;
+    /** Drop the staging rows (Phase B aborted before commit). Idempotent (a missing staging id deletes 0). */
+    abort(): Promise<void>;
+}
 export {};
 //# sourceMappingURL=tidb-session-store.d.ts.map

package/dist/stores-sql/tidb-session-store.js

@@ -6,7 +6,7 @@ import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-dec
 import { headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertCells, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "../plugins/session-placement.js";
-import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOccupantChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "../plugins/session-ownership.js";
 import { forkRowCells, selectForkRows } from "@sema-agent/core";
 import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf, sameSourceGeneration } from "../plugins/session-fork.js";
@@ -104,14 +104,33 @@ export class TiDBSessionStore {
     async register(sessionId, owner) {
         await this.registerWithReceipt(sessionId, owner);
     }
-    async registerWithReceipt(sessionId, owner) {
+    async registerWithReceipt(sessionId, owner, kind) {
         if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
                 return {};
             assertFirstOwnerWritable(sessionId, owner);
         }
         const incarnation = mintSessionIncarnation();
-        await this.insertMeta(sessionId, owner, undefined, incarnation);
+        if (kind === undefined) {
+            await this.insertMeta(sessionId, owner, undefined, incarnation);
+            return { minted: { sessionId, owner, incarnation } };
+        }
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            await this.insertMetaOn(conn, sessionId, owner, undefined, incarnation);
+            const [rows] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
+            if (rows[0]?.incarnation === incarnation)
+                await this.hooks.birth.record(statementsOn(conn), { rootSessionId: sessionId, kind });
+            await conn.commit();
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
         return { minted: { sessionId, owner, incarnation } };
     }
     async deleteSessionIf(sessionId, cond) {
@@ -137,9 +156,12 @@ export class TiDBSessionStore {
         await this.insertMeta(sessionId, placement === undefined ? null : placedSessionOwnerOf(sessionId, placement), placement);
     }
     async insertMeta(sessionId, owner, placement, incarnation = mintSessionIncarnation()) {
+        await this.insertMetaOn(this.pool, sessionId, owner, placement, incarnation);
+    }
+    async insertMetaOn(on, sessionId, owner, placement, incarnation) {
         const now = new Date();
         const placed = placementInsertCells(placement, now);
-        await this.pool.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
+        await on.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
             "VALUES (?,?,?,?,NULL,0,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [sessionId, owner, now, now, incarnation, ...placed.values]);
     }
     async placementOf(sessionId) {
@@ -202,7 +224,7 @@ export class TiDBSessionStore {
             }
             throw err instanceof SessionError
                 ? err
-                : new SessionError("storage", `placed session ${sessionId} could not be deleted: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
+                : new SessionError("storage", `placed session ${sessionId} could not be deleted`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
@@ -298,11 +320,13 @@ export class TiDBSessionStore {
         if (!metaRows[0])
             return null;
         const pool = this.pool;
-        const batchSize = opts?.batchSize ?? 500;
+        const batchSize = opts.batchSize ?? 500;
         async function* gen() {
-            let cursor = opts?.afterSeq ?? -1;
+            let cursor = opts.afterSeq ?? -1;
             for (;;) {
                 const [rows] = await pool.query(`SELECT seq, ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?`, [sessionId, cursor, batchSize]);
+                if (rows.length > 0)
+                    await opts.recheck();
                 for (const r of rows)
                     yield decodeSessionEventPayload(r.payload, sessionId, r.seq);
                 if (rows.length < batchSize)
@@ -426,7 +450,7 @@ export class TiDBSessionStore {
         this.pending.clear();
     }
 }
-class TiDBStagingHandle {
+export class TiDBStagingHandle {
     pool;
     hooks;
     realSessionId;
@@ -466,11 +490,11 @@ class TiDBStagingHandle {
             await conn.beginTransaction();
             const now = new Date();
             const minted = mintSessionIncarnation();
-            if (opts.expectedOwner !== undefined) {
-                const [cas] = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = ? AND owner <=> ?", [this.realSessionId, opts.expectedOwner]);
+            if (opts.expectedOccupant !== undefined) {
+                const [cas] = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = ? AND owner <=> ? AND incarnation = ?", [this.realSessionId, opts.expectedOccupant.owner, opts.expectedOccupant.incarnation]);
                 if (cas.affectedRows !== 1) {
                     await conn.rollback();
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             else {
@@ -478,7 +502,7 @@ class TiDBStagingHandle {
                 const [claimed] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [this.realSessionId]);
                 if (String(claimed[0]?.incarnation) !== minted) {
                     await conn.rollback();
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: this.realSessionId }));
@@ -490,7 +514,7 @@ class TiDBStagingHandle {
                 throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${String(dstMeta[0].placement_kind)} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
             }
             const srcIds = stagedRows.map((r) => String(r.entry_id));
-            const dstIds = opts.expectedOwner !== undefined ? dstRows.map((r) => String(r.entry_id)) : null;
+            const dstIds = opts.expectedOccupant !== undefined ? dstRows.map((r) => String(r.entry_id)) : null;
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
             if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 await conn.rollback();

package/dist/submission-exit.d.ts

@@ -2,6 +2,7 @@ import type { DeploymentShapeInput } from "./deployment-shape.js";
 import type { RunAcceptance } from "./run-acceptance.js";
 import type { SessionWithdrawFace } from "./plugins/session-birth.js";
 import type { SessionBirth, StoreKeptWord } from "./session-incarnation.js";
+import type { BindingReceiptSink } from "./session-bindings.js";
 /** 收场词(闭集;加词 ⇒ {@link SubmissionSeat.close} 的穷尽 switch 编译红)。 */
 export type SubmissionEnd = "accepted" | "record" | "refused";
 /** 「留」的词:店内七词 + 座内四词(`withdraw_failed` = 撤回事务抛了,按留答)。 */
@@ -25,7 +26,7 @@ export interface SubmissionSeatDeps {
     };
 }
 /** 一次提交的出口座(提交门在授权之前铸;三条提交腿只喂它、收它)。 */
-export interface SubmissionSeat {
+export interface SubmissionSeat extends BindingReceiptSink {
     /** 授权器登记新行时交来的候选与店的撤回面(只有新行臂调;调多次以第一次为准)。 */
     noteBirth(birth: SessionBirth, face: SessionWithdrawFace): void;
     /** 提交门铸好 spec 之后挂上受理座(闩的唯一读者在 {@link close})。 */
@@ -36,7 +37,7 @@ export interface SubmissionSeat {
     markRecord(): void;
     /** 执行环境为这次提交留下了按会话键的持久物。 */
     noteEnvWitness(): void;
-    /** 此刻判不判得出「留」而不必走店(闩上 / record / 没有候选 / 有见证)。 */
+    /** 此刻判不判得出「什么都不撤」而不必收场(闩上 / record / 没有候选也没有回执 / 有见证也没有回执)。 */
     readonly keepsWithoutWithdraw: boolean;
     /** 收场(幂等、先到者定;不抛)。 */
     close(): Promise<SubmissionVerdict>;

package/dist/submission-exit.js

@@ -4,6 +4,7 @@ import { retireSessionId } from "./deleted-session-ids.js";
 import { seatText } from "./trace/exit-seat.js";
 export function createSubmissionSeat(deps) {
     let birth;
+    let bindings;
     let acceptance;
     let ownTaskId;
     let recorded = false;
@@ -16,12 +17,15 @@ export function createSubmissionSeat(deps) {
         let verdict;
         switch (end) {
             case "accepted":
+                bindings?.face.settleSessionBindings(bindings.receipt);
                 verdict = "kept_accepted";
                 break;
             case "record":
+                bindings?.face.settleSessionBindings(bindings.receipt);
                 verdict = "kept_record";
                 break;
             case "refused":
+                bindings?.face.withdrawSessionBindings(bindings.receipt);
                 verdict = await withdrawOrKeep();
                 break;
             default: {
@@ -60,6 +64,10 @@ export function createSubmissionSeat(deps) {
             if (birth === undefined)
                 birth = { birth: b, face };
         },
+        noteBindings(receipt, face) {
+            if (bindings === undefined)
+                bindings = { receipt, face };
+        },
         attachAcceptance(a) {
             acceptance = a;
         },
@@ -77,7 +85,7 @@ export function createSubmissionSeat(deps) {
             witnessed = true;
         },
         get keepsWithoutWithdraw() {
-            return birth === undefined || witnessed || endNow() !== "refused";
+            return endNow() !== "refused" || (bindings === undefined && (birth === undefined || witnessed));
         },
         close() {
             if (closing === undefined) {

package/dist/task-cwd.d.ts

@@ -115,8 +115,8 @@ export declare function effectiveHostWorkspace(sessionCwd: string | undefined, c
  * 为什么组合腿要它:梯子的每一级是在引擎**现铸的会话**里冷跑(core `runCascade` 剥掉 spec 的 `sessionId`),验证门的验证器腿的 spec 不带会话 ——
  * 工厂按腿的会话查登记表(第 1 臂)查不到提交登记在根会话上的那一枚,不交就落第 3 臂(临时目录):用户让梯子在项目里改文件,改到了别处;验证器验的是一只空目录。
  * 跑在根会话上的腿(验证门的实现腿 / 修复腿)第 1 臂先命中,同一个值。
- * 没登记(`registeredCwd` 缺席:非 host / device 车道、多租户、根会话的提交从没带过 `cwd`、嵌入方装配器没铸事实)⇒ 空对象 —— 每一条腿照旧落临时目录、收场由托管表删。
- * 登记粘在会话上(`setSessionCwd` 只在请求带 `cwd` 时写):同一会话之前带过、这次不带 ⇒ 交的仍是那一枚 —— 与第 1 臂对同一会话上普通 run 的读法一致。
+ * 没登记(这条腿的会话绑定没有工作目录:非 host / device 车道、多租户、根会话的提交从没带过 `cwd`、嵌入方装配器没铸事实)⇒ 空对象 —— 每一条腿照旧落临时目录、收场由托管表删。
+ * 登记粘在会话上(会话绑定的 `cwd` 一格 = 这条腿跑在的那一枚 —— 请求带的 ?? 项目继承来的 ?? 会话上已登记的 —— 受理之后写回会话,`session-bindings.ts`):同一会话之前带过、这次不带 ⇒ 交的仍是那一枚 —— 与第 1 臂对同一会话上普通 run 的读法一致。
  */
 export declare function compositionLegRoot(registeredCwd: string | undefined): Pick<RunInternals, "parentCwd">;
 /** {@link launchWorkspaceOf} 读到的那一格出自哪里(闭集;起服那一行日志与随包文档的 `workspaceFrom` 词)。 */

package/dist/task-settings.d.ts

@@ -122,11 +122,12 @@ export declare function planReviewDecisionExitsPlan(decision: "approve" | "edit"
  * 新体 `{ ...body, permissionMode: entry.effective }`,调用方的对象不改;bundle 的 `settings.permissions.defaultMode` 不动 —— 顶层赢过它
  * ({@link effectivePermissionMode} 的优先序),再改它就是同一语义的第二个写者。披露这一折的通告(`entry-mode-clamp-notice.ts`)读的也是同一份 `entry`。
  *
- * 调用点一个:提交入口的那一步 `permission-mode-admission.ts` `stampSubmissionEntryMode`(受理判官的入口一步;`http/admission.ts` 的 `prepareSpec` 调它:值形门全部判完之后、`resolveSpec` 之前)。那一份体就是首跑装配读的体,也是
- * `buildCheckpointCtx` 持久化的体 ⇒ 一处盖章同时覆盖首跑与每一次续跑重建;装配腿与续跑腿都不读地板(两处读 = 两个源)。
- * 另外两个写者是 `plan_review` 写回(`http/resume-legs.ts` `drivePlanReview`,判据 {@link planReviewDecisionExitsPlan})与在飞 run 的切档口写回
- * (`http/routes/run-permission-mode.ts`,写的是同一只判官准入的词)。
- * 热改 `AUTONOMY` 只影响之后提交的任务与之后的切档:续跑腿保持存储体里的词。地板的属主是 `runtime-governance.ts` 的 `autonomyModeFloor`。
+ * 调用点两个,都是受理判官的入口一步(`permission-mode-admission.ts`,同一只 `bodyEntry`):提交口 `stampSubmissionEntryMode`(`http/admission.ts` 的 `prepareSpec` 调它:
+ * 值形门全部判完之后、`resolveSpec` 之前 —— 那一份体就是首跑装配读的体,也是 `buildCheckpointCtx` 持久化的体)与续跑口 `stampReplayEntryMode`(`http/resume-legs.ts`
+ * 的 `replayCtxOf`:停驻 run 的存储体被重放之前过一次**现**地板,地板的出口词原样;钳过的体随 CAS 赢点写回)。装配腿不读地板;每一腿读一次地板、写进体,
+ * run 的模式词仍只有存储体一个源。另外两个写者是 `plan_review` 写回(`http/resume-legs.ts` `drivePlanReview`,判据 {@link planReviewDecisionExitsPlan};
+ * 写下的是 plan 地板的出口词)与在飞 run 的切档口写回(`http/routes/run-permission-mode.ts`,写的是同一只判官准入的词)。
+ * 热改 `AUTONOMY` 对之后的提交、切档与停驻 run 的下一次续跑都生效。地板的属主是 `runtime-governance.ts` 的 `autonomyModeFloor`。
  */
 export declare function stampEntryPermissionMode<B extends {
     permissionMode?: unknown;

package/dist/terminal.d.ts

@@ -1,4 +1,5 @@
 import { terminalProjection, type PausedCause, type TaskStatus, type TerminalCause } from "@sema-agent/core";
+import { StoreBoundaryFault, type StoreFaultClass } from "./plugins/store-fault.js";
 /**
  * 这次失败带的**机器码**(`terminal.failed.code`);非失败终局 ⇒ `undefined`。
  *
@@ -129,9 +130,12 @@ export declare function mapPauseSeats<T>(result: T, f: (seat: SeatObject, keys:
  *
  * ── 折码的运维线索:一句定形字段,两只入口各说一只词 ──
  * 字段 `original=<码 | <not-a-code>> outward=<对外词> messageBytes=<n> at=<观看点>`,只有闭集词、数字与码({@link isCodeToken});码形座里装着文字的、长得像码的秘密同理只报 `<not-a-code>`。
- * 失败句(库驱动原句,自由文本:可以有连接串 / 口令 / 库账号 / 表名)**不上 wire**({@link outwardStoreFailure}),只进**写入口**那一行的末尾格 `message=<JSON 串>` ——
- * 经出口座的一句话行(`operator-log-text`:凭据形换记号、剥控制字符、有界),读座的再观看不带(同一行存量行每读一次就重放一次)。`at` 说这是哪一次观看,**一个入口一只词**(类型给定,不靠记得传):
+ * 失败句**不上 wire**({@link outwardStoreFailure});店起源的失败到这里时句子已是店边界换过的对外句({@link storeBoundaryFault}:库驱动原句 —— 自由文本,可以有连接串 / 口令 / 库账号 / 表名 ——
+ * 只进店边界那一行 `at=store`),写入口那一行的末尾格 `message=<JSON 串>` 对它们带的就是对外句;不经店边界的抛出物(fs / 网络 / 第三方码)带的仍是它自己的句子 ——
+ * 都经出口座的一句话行(`operator-log-text`:凭据形换记号、剥控制字符、有界),读座的再观看不带(同一行存量行每读一次就重放一次)。`at` 说这是哪一次观看,**一个入口一只词**(类型给定,不靠记得传):
  *  · 本函数 = 结果**第一次**离开引擎(店的写口 / 出口铸体)⇒ `at=exit`,每折一次一行 `[terminal] outward_failure_code_folded <字段>[ message=<句>]` —— 每次都是一件新的失败;
+ *  · {@link storeBoundaryFault} = 失败**离开本服务的店**(SQL 店的出口)⇒ `at=store`,每次一行,多两格 `site=<店>.<方法> class=<判官词>`,`message=` 是原错与其 `cause` 链各层的句子(逐层过座);
+ *    查库的原话读这一行,按 `original=` 与时间对 `at=exit` / `request_error` 行;
  *  · {@link sealStoredResult} = 存量行的**再观看**(读座必填)⇒ 走 fail-open 纪律(登记 tag `server.terminal.stored-result-code-folded`):
  *    逐读计数 + 逐读探针行 + 每进程一次 warn,detail 即上面那句字段。读面每次轮询 / 每个观看者 / 每次重连都重放同一批行 ——
  *    计数让「旧失败被读了多少次」看得见,一次 warn 让日志不随读次放大;去重归记录器一只,不另造表。
@@ -148,12 +152,39 @@ export declare function sealResultForExit<T extends {
 export declare function sealStoredResult<T extends {
     readonly terminal?: unknown;
 }>(result: T, seat: StoredResultReadSeat): T;
+/**
+ * 一个折掉的码在出口上的对外句(纯函数、无副作用)—— 出口四入口的**唯一**读法:{@link outwardStoreFailure}(封口 / 抛出臂,带运维线索)、{@link outwardPlane}
+ * (投影出口,纯读、不出线索)与 {@link persistedPlaneOf} 的旧形臂。句子已是「某个类别句 + 本码尾注」⇒ 原样(店边界换过的句子,词在原错上判,见 {@link storeBoundaryFault});
+ * 否则 = 判官读 `{ code }` 的类别句 + 尾注(拼法 `outwardStoreSentence`,一只拼法两种输入)。任何一张脸上折过码的 `errorMessage` 都不可能是驱动的原句,不论这条因由封过口没有、存的是哪一代形。
+ * 店边界之前落盘的存量子代句的一次性改写(M53,`store-fault-sentence-m53.ts`)读同一只。
+ */
+export declare function outwardStoreMessageOf(code: string, message: unknown): string;
 /**
  * 腿**抛出**的错落进 run 行 `error` 列时的对外句(没有终局结果、没有因由的那一臂:`runs.ts` 后台腿的兜底腿与它的孪生 `resume-legs.ts` 兜底腿)—— 与终局因由是**同一只**
  * 铸点({@link outwardStoreFailure}):抛出物自带的 `code`({@link errorCodeOf},字符串)出了本仓词法 ⇒ 同码同句;没有码 / 码在词法内(本仓与引擎自己的错、普通 `Error`)⇒ 文本逐字,非库错误照旧。
  * `message` 是调用方已取出的抛出文本({@link errorText} 的产物,不抛);本函数不抛(读码口不抛)。
  */
 export declare function outwardThrownMessage(err: unknown, message: string): string;
+/**
+ * 🔴 **店边界 —— 驱动原句越出 SQL 店的唯一读者**。律:一只 SQL 店的任何出口(抛出值、包装错误的 `cause`、抛出或返回值里的失败文本、交给调用方的可调用对象)
+ * 只带「原码 + 稳定句」({@link StoreBoundaryFault});驱动的原句在这里记一次运维日志,不随错误走。店的出口在 `plugins/store-boundary.ts` 封口(逐生产者、编译期穷尽的出口表),
+ * 店里自己拼句 / 拼值 / 包 `cause` 的地方先读本函数、再用它交回的形。交回:
+ *  · 已是边界形 ⇒ 同一引用(嵌套店:最里层出口换过、记过,外层同一引用放行、不再记);
+ *  · typed 失败(顶层自带词法内的码:`SessionError("storage")`、`store.row_too_large` …)⇒ 同一引用,它的类、码与句子原样;它 `cause` 链上的驱动错**就地**换成边界形
+ *    (typed 层往下走,第一只不是 typed 而带驱动证据的那一段整只换;那一段的原句照样记一行 `at=store`);
+ *  · 调用方出身(`error-origin.ts` 的 `caller`:店把调用方钩子的抛出物原样还给调用方)⇒ 同一引用、不记 —— 它不是店的失败;
+ *  · 不触发扳机 ⇒ 同一引用(不带码 / 码在词法内、不带驱动出身记号的错照旧);
+ *  · 触发 ⇒ 一行运维日志(`at=store site=<店>.<方法> class=<判官词>`,`message=` 是原错与其 `cause` 链各层的句子,逐层过出口座)+ 计数,交回新铸的边界形。
+ * 扳机两条(任一):① **码出词法**:码在场且 {@link outwardFailureCode} 折它 —— fail-closed,词法外的码一律换句(驱动、套接字、对象存储、fs 都算);
+ *  ② **驱动出身**:原错或其 `cause` 链上任一层带池座打的记号(`plugins/error-origin.ts` 的 `driver`)—— 补词法看不见的无码驱动错。
+ * 链读法一律深 ≤ {@link CAUSE_CHAIN_DEPTH};链比这更深 ⇒ 当作带驱动证据(fail-closed:看不到底的链不放行)。
+ * 码的读法({@link driverCodeOf}):沿 `cause` 链(深 ≤ 8)取第一个非空串 `code`,`"unknown"` 只作兜底(与 core 的码链读法同读);一条串码都没有、而某一层带整数 `errno`
+ * ⇒ 码 = 那个 `errno` 的十进制串 —— 这是本仓的规则(引擎不读 errno):只带 errno 的驱动错(TiDB 自有号,mysql2 的码表里没有符号)于是进同一只扳机、说同一句,出口照折。
+ * 判官(`storeFaultClassOf`)在**原错**上判一次(连接类整句、errno 臂、1005 内层号都只在原错上读得到),词随形带走。不抛。
+ * `site` = 封口调用点的字面店词 + 方法名(源码里的标识符,不是外部输入)。
+ */
+export declare function storeBoundaryFault<E>(err: E, site: string): E | StoreBoundaryFault;
+export declare function setStoreBoundaryObserver(fn: ((site: string, faultClass: StoreFaultClass) => void) | undefined): void;
 /**
  * **投影出口的唯一属主**([ref])—— core 的 `terminalProjection` + 对外码归一,一次。
  *