@sema-agent/server 7.146.0 → 7.148.0

package/dist/{plugins → stores-sql}/tidb-session-store.js

@@ -1,38 +1,71 @@
 import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./tidb-session-storage.js";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
-import { jsonColumnText } from "./sql-json-column.js";
-import { escapeLike } from "./sql-escape.js";
-import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
-import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
-import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
-import { carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
-import { sessionRowTagKey } from "../session-row.js";
-import { writeSessionRowCellsSql } from "./session-row-sql.js";
+import { jsonColumnText } from "../plugins/sql-json-column.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
+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, placementInsertValues, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "./session-placement.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 { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "./session-ownership.js";
-import { selectForkRows } from "@sema-agent/core";
-import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf } from "./session-fork.js";
-import { isMysqlDupKeyError } from "./sql-errors.js";
-import { mysqlDriver } from "./sql-driver.js";
-import { MIRROR_ON_COMMIT_GUARD, MIRROR_ON_COMMIT_SET, SESSION_META_PLACEMENT_READ_COLUMNS, createSqlExecutionPlacementSeat, importedRowCells, lockRootAndReadClaim, placementCellFromRow, readPlacementRowStatement } from "./execution-placement-sql.js";
-import { SessionActiveRunError, SessionWriterPresentError } from "../execution-placement.js";
-const rowsOnConnection = (conn) => async (sql, values) => (await conn.query(sql, [...values]))[0];
+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";
+import { isMysqlDupKeyError } from "../plugins/sql-errors.js";
+const statementsOn = (conn) => ({
+    async query(sql, params) {
+        const [res] = await conn.query(sql, params ?? []);
+        return Array.isArray(res) ? { rows: res, affected: 0 } : { rows: [], affected: res.affectedRows };
+    },
+});
+function withdrawPlaceholders(dialect, from, count) {
+    return Array.from({ length: count }, (_, i) => (dialect === "pg" ? `$${from + i}` : "?"));
+}
+const keptAs = (word) => ({ withdrawn: false, kept: word });
+export async function withdrawSessionOn(tx, dialect, hooks, sessionId, cond) {
+    const [p1] = withdrawPlaceholders(dialect, 1, 1);
+    const root = (await tx.query(`SELECT owner, incarnation FROM session_meta WHERE session_id = ${p1} FOR UPDATE`, [sessionId])).rows[0];
+    if (root === undefined)
+        return keptAs("absent");
+    const owner = root.owner === null || root.owner === undefined ? null : String(root.owner);
+    if (String(root.incarnation ?? "") !== cond.expect.incarnation || owner !== cond.expect.owner)
+        return keptAs("incarnation");
+    const types = withdrawPlaceholders(dialect, 2, cond.withdrawableEntryTypes.length);
+    const content = await tx.query(`SELECT type FROM session_event WHERE session_id = ${p1} AND type NOT IN (${types.join(", ")}) LIMIT 1 FOR UPDATE`, [sessionId, ...cond.withdrawableEntryTypes]);
+    if (content.rows.length > 0)
+        return keptAs("content");
+    if ((await hooks.beforeCommit(tx, { op: "delete", rootSessionId: sessionId })) !== "proceed")
+        return keptAs("claim");
+    const judged = await cond.judge(tx);
+    if (judged !== "proceed")
+        return keptAs(judged.keep);
+    await tx.query(`DELETE FROM session_event WHERE session_id = ${p1}`, [sessionId]);
+    const [q1, q2] = withdrawPlaceholders(dialect, 1, 2);
+    const gone = await tx.query(`DELETE FROM session_meta WHERE session_id = ${q1} AND incarnation = ${q2}`, [sessionId, cond.expect.incarnation]);
+    if (gone.affected !== 1)
+        throw new Error(`withdraw of session ${sessionId}: the root row this transaction holds locked matched ${gone.affected} rows on delete — engine/driver anomaly, refusing to commit`);
+    return { withdrawn: true };
+}
+class HookRefusal {
+    refuse;
+    constructor(refuse) {
+        this.refuse = refuse;
+    }
+}
+function settleHookVerdict(verdict) {
+    if (verdict !== "proceed")
+        throw new HookRefusal(verdict.refuse);
+}
 export class TiDBSessionStore {
     pool;
     retention;
     placements = SESSION_PLACEMENTS;
     durability = SESSION_DURABILITY;
     pending = new Map();
-    executionPlacement;
-    db;
-    constructor(pool, opts = {}) {
+    hooks;
+    constructor(pool, opts) {
         this.pool = pool;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
-        this.db = mysqlDriver(pool);
-        this.executionPlacement = createSqlExecutionPlacementSeat(this.db);
+        this.hooks = opts.hooks;
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -69,21 +102,45 @@ export class TiDBSessionStore {
         return { session: new StoredSession(storage), sessionId };
     }
     async register(sessionId, owner) {
+        await this.registerWithReceipt(sessionId, owner);
+    }
+    async registerWithReceipt(sessionId, owner) {
         if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
-                return;
+                return {};
             assertFirstOwnerWritable(sessionId, owner);
         }
-        await this.insertMeta(sessionId, owner, undefined);
+        const incarnation = mintSessionIncarnation();
+        await this.insertMeta(sessionId, owner, undefined, incarnation);
+        return { minted: { sessionId, owner, incarnation } };
+    }
+    async deleteSessionIf(sessionId, cond) {
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            const outcome = await withdrawSessionOn(statementsOn(conn), "mysql", this.hooks, sessionId, cond);
+            if (outcome.withdrawn)
+                await conn.commit();
+            else
+                await conn.rollback();
+            return outcome;
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
     }
     async createOnAcquire(sessionId, placement) {
         await this.insertMeta(sessionId, placement === undefined ? null : placedSessionOwnerOf(sessionId, placement), placement);
     }
-    async insertMeta(sessionId, owner, placement) {
+    async insertMeta(sessionId, owner, placement, incarnation = mintSessionIncarnation()) {
         const now = new Date();
-        await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
-            "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +
-            "VALUES (?,?,?,?,NULL,0,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE session_id = session_id", [sessionId, owner, now, now, mintSessionIncarnation(), ...placementInsertValues(placement, now)]);
+        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}) ` +
+            "VALUES (?,?,?,?,NULL,0,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [sessionId, owner, now, now, incarnation, ...placed.values]);
     }
     async placementOf(sessionId) {
         const [rows] = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = ?`, [sessionId]);
@@ -151,104 +208,6 @@ export class TiDBSessionStore {
             conn.release();
         }
     }
-    async listSessions(opts) {
-        return (await this.listSessionRows(opts)).map((a) => a.row);
-    }
-    async listSessionRows(opts) {
-        const params = [];
-        const where = ["sm.placement_kind IS NULL"];
-        if (opts.owner !== undefined) {
-            where.push(opts.includeUnowned ? "(sm.owner = ? OR sm.owner IS NULL)" : "sm.owner = ?");
-            params.push(opts.owner);
-        }
-        if (opts.q) {
-            where.push("EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(?) ESCAPE '\\\\')");
-            params.push(`%${escapeLike(opts.q)}%`);
-        }
-        if (opts.cursor) {
-            where.push("(sm.updated_at < ? OR (sm.updated_at = ? AND sm.session_id < ?))");
-            params.push(new Date(opts.cursor.lastActivityAt), new Date(opts.cursor.lastActivityAt), opts.cursor.sessionId);
-        }
-        return this.selectListRows({ where, params, limit: opts.limit });
-    }
-    async sessionSummaryOf(sessionId) {
-        return (await this.listRowOf(sessionId))?.row;
-    }
-    async listRowOf(sessionId) {
-        return (await this.selectListRows({ where: ["sm.placement_kind IS NULL", "sm.session_id = ?"], params: [sessionId], limit: 1, runSessionId: sessionId }))[0];
-    }
-    async writeSessionRowCells(sessionId, cells, how) {
-        return writeSessionRowCellsSql(this.db, sessionId, cells, how, (id) => this.listRowOf(id));
-    }
-    async selectListRows(q) {
-        const runWhere = q.runSessionId !== undefined ? " WHERE session_id = ?" : "";
-        const runParams = q.runSessionId !== undefined ? [q.runSessionId, q.runSessionId] : [];
-        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, sm.pinned, " +
-            "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
-            "FROM session_meta sm " +
-            "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run" + runWhere + " GROUP BY session_id) r ON r.session_id = sm.session_id " +
-            "LEFT JOIN (SELECT session_id, objective_preview, status, task_id, last_task_run_id FROM (" +
-            "    SELECT session_id, objective_preview, status, task_id, JSON_UNQUOTE(JSON_EXTRACT(result, '$.runId')) AS last_task_run_id, " +
-            "      ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn FROM task_run" + runWhere +
-            "  ) lr WHERE rn = 1) latest ON latest.session_id = sm.session_id " +
-            (q.where.length ? "WHERE " + q.where.join(" AND ") + " " : "") +
-            "ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ?";
-        const [rows] = await this.pool.query(sql, [...runParams, ...q.params, q.limit]);
-        return rows.map((r) => {
-            const runId = r.last_task_run_id;
-            const sessionId = String(r.session_id);
-            const owner = r.owner ?? null;
-            const incarnation = incarnationFromCell(sessionId, r.incarnation, "absent");
-            const title = r.title ?? null;
-            const pinned = Number(r.pinned) === 1;
-            const row = {
-                sessionId,
-                owner,
-                lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
-                firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
-                runCount: Number(r.run_count),
-                objectivePreview: r.objective_preview ?? null,
-                lastStatus: r.status == null ? "" : String(r.status),
-                lastRunId: r.last_run_id ?? null,
-                ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
-                title,
-                pinned,
-                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
-            };
-            return { row, occupant: { owner, incarnation } };
-        });
-    }
-    async probeTitle(sessionId) {
-        const [rows] = await this.pool.query("SELECT title FROM session_meta WHERE session_id = ?", [sessionId]);
-        if (!rows[0])
-            return "none";
-        return rows[0].title == null ? "untitled" : "titled";
-    }
-    async setTitleIfNull(sessionId, title) {
-        const [r] = await this.pool.query("UPDATE session_meta SET title = ? WHERE session_id = ? AND title IS NULL", [title, sessionId]);
-        return r.affectedRows > 0;
-    }
-    async readInstructionSource(sessionId) {
-        const [rows] = await this.pool.query({ sql: "SELECT instruction_source FROM session_meta WHERE session_id = ?", timeout: BASELINE_IO_DEADLINE_MS }, [sessionId]);
-        return decodeInstructionSource(rows[0]?.instruction_source);
-    }
-    async recordInstructionSource(sessionId, expected, source) {
-        const next = encodeInstructionSource(source);
-        if (expected.recorded) {
-            await this.pool.query({ sql: "UPDATE session_meta SET instruction_source = ? WHERE session_id = ? AND instruction_source = ?", timeout: BASELINE_IO_DEADLINE_MS }, [next, sessionId, encodeInstructionSource(expected.source)]);
-        }
-        else {
-            await this.pool.query({ sql: "UPDATE session_meta SET instruction_source = ? WHERE session_id = ? AND instruction_source IS NULL", timeout: BASELINE_IO_DEADLINE_MS }, [next, sessionId]);
-        }
-    }
-    async readSessionWorkspace(sessionId) {
-        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("mysql", "workspace")} FROM session_meta WHERE session_id = ?`, [sessionId]);
-        const row = rows[0];
-        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
-    }
-    async recordSessionWorkspace(sessionId, incarnation, workspace) {
-        await this.pool.query("UPDATE session_meta SET workspace = ? WHERE session_id = ? AND incarnation = ?", [encodeSessionWorkspaceCell(workspace, JSON.stringify, sessionId), sessionId, incarnation]);
-    }
     async fork(sourceId, owner, opts) {
         return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner, opts);
     }
@@ -261,7 +220,8 @@ export class TiDBSessionStore {
         throw new ForkTargetUnsettledError(target.id);
     }
     async forkToOnce(sourceId, owner, target) {
-        const [metaRows] = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = ?", [sourceId]);
+        const sourceRow = "SELECT leaf_id, owner, incarnation FROM session_meta WHERE session_id = ?";
+        const [metaRows] = await this.pool.query(sourceRow, [sourceId]);
         if (!metaRows[0])
             return null;
         const leafId = metaRows[0].leaf_id ?? null;
@@ -270,16 +230,20 @@ export class TiDBSessionStore {
         if (storage === null)
             return null;
         const point = await forkPointOf(storage);
+        const cells = forkRowCells(await storage.getMetadata());
         const [allRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("mysql", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
+        const [afterRows] = await this.pool.query(sourceRow, [sourceId]);
+        if (!sameSourceGeneration(cells.forkedFromIncarnation, metaRows[0].incarnation, afterRows[0]?.incarnation))
+            return null;
         const { rows: eventRows, leafId: forkLeafId } = selectForkRows(allRows, leafId, point, FORK_LOG_ROW_SHAPE);
         const now = new Date();
         const conn = await this.pool.getConnection();
         let collided = false;
         try {
             await conn.beginTransaction();
+            const placed = placementInsertCells(target.placement, now);
             try {
-                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, fork_key, " +
-                    "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)", [target.id, forkOwner, now, now, forkLeafId, eventRows.length, mintSessionIncarnation(), target.key ?? null, ...placementInsertValues(target.placement, now)]);
+                await conn.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}, forked_from, forked_from_incarnation) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [target.id, forkOwner, now, now, forkLeafId, eventRows.length, mintSessionIncarnation(), ...placed.values, cells.forkedFrom, cells.forkedFromIncarnation ?? null]);
             }
             catch (err) {
                 if (!isMysqlDupKeyError(err))
@@ -287,6 +251,8 @@ export class TiDBSessionStore {
                 collided = true;
             }
             if (!collided) {
+                if (target.key !== undefined)
+                    await this.hooks.keyedFork.record(statementsOn(conn), { rootSessionId: target.id, forkKey: target.key });
                 for (let seq = 0; seq < eventRows.length; seq++) {
                     const r = eventRows[seq];
                     const payload = String(r.payload);
@@ -303,14 +269,15 @@ export class TiDBSessionStore {
             }
             catch {
             }
+            if (err instanceof HookRefusal)
+                throw err.refuse;
             throw err instanceof SessionError ? err : new SessionError("storage", `fork of session ${sourceId} failed`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
         }
-        const [existing] = await this.pool.query("SELECT owner, fork_key FROM session_meta WHERE session_id = ?", [target.id]);
-        const row = existing[0];
-        return row === undefined ? "unsettled" : classifyForkTarget(target, { owner: row.owner ?? null, forkKey: row.fork_key ?? null }, forkOwner);
+        const existing = await this.hooks.keyedFork.targetOf(target.id);
+        return existing === undefined ? "unsettled" : classifyForkTarget(target, existing, forkOwner);
     }
     async exportEntries(sessionId) {
         const [metaRows] = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = ?", [sessionId]);
@@ -350,7 +317,7 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            await this.writeImportedLog(conn, sessionId, owner, validated, { incarnation: mintSessionIncarnation(), forkKey: null }, "create");
+            await this.writeImportedLog(conn, sessionId, owner, validated, "create");
             await conn.commit();
         }
         catch (err) {
@@ -359,7 +326,9 @@ export class TiDBSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `import of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -373,21 +342,13 @@ export class TiDBSessionStore {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            const [placedRows] = await conn.query(`SELECT ${SESSION_META_PLACEMENT_READ_COLUMNS}, fork_key FROM session_meta WHERE session_id = ? FOR UPDATE`, [sessionId]);
-            const prior = placedRows[0];
+            const [lockedRows] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
+            const prior = lockedRows[0];
             if (prior?.placement_kind != null) {
                 await conn.rollback();
                 throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${String(prior.placement_kind)} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
             }
-            const [purged] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
-            const swapped = purged.affectedRows === 1 ? prior : undefined;
-            const cells = carriedRowCells(sessionId, swapped === undefined ? undefined : { incarnation: swapped.incarnation, forkKey: swapped.fork_key });
-            const priorCell = swapped === undefined ? undefined : placementCellFromRow(sessionId, swapped);
-            if (priorCell?.role === "writer") {
-                await conn.rollback();
-                throw new SessionWriterPresentError(sessionId, priorCell.lane);
-            }
-            await this.writeImportedLog(conn, sessionId, owner, validated, cells, "replace");
+            await this.writeImportedLog(conn, sessionId, owner, validated, prior === undefined ? "create" : "replace");
             await conn.commit();
         }
         catch (err) {
@@ -396,7 +357,9 @@ export class TiDBSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `replace of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -404,23 +367,26 @@ export class TiDBSessionStore {
             conn.release();
         }
     }
-    async writeImportedLog(conn, sessionId, owner, validated, cells, mode) {
+    async writeImportedLog(conn, sessionId, owner, validated, mode) {
         let leafId = null;
         for (const e of validated)
             leafId = leafIdAfterEntry(e);
         const now = new Date();
-        const imported = importedRowCells(cells.forkKey);
-        await conn.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${imported.columns}) VALUES (?,?,?,?,?,?,?,?,?)` +
-            (mode === "create" ? " ON DUPLICATE KEY UPDATE session_id = session_id" : ""), [sessionId, owner, now, now, leafId, validated.length, cells.incarnation, ...imported.values]);
         if (mode === "create") {
+            const minted = mintSessionIncarnation();
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [sessionId, owner, now, now, leafId, validated.length, minted]);
             const [held] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
-            if (String(held[0]?.incarnation) !== cells.incarnation) {
+            if (String(held[0]?.incarnation) !== minted) {
                 throw new SessionError("storage", `import of session ${sessionId} failed`, new Error(`session ${sessionId} already exists — importEntries only creates a session (replaceEntries rewrites one); nothing was written`));
             }
         }
-        const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", sessionId);
-        if (claim.activeTaskId !== null)
-            throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+        else {
+            const [rewritten] = await conn.query("UPDATE session_meta SET owner = ?, created_at = ?, updated_at = ?, leaf_id = ?, leaf_seq = ? WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [owner, now, now, leafId, validated.length, sessionId, owner]);
+            if (rewritten.affectedRows !== 1) {
+                throw new SessionError("storage", `replace of session ${sessionId} failed`, new Error(`session ${sessionId} belongs to another owner — a replace rewrites only the importer's own session; nothing was written`));
+            }
+        }
+        settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: sessionId }));
         if (mode === "replace")
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
         for (let seq = 0; seq < validated.length; seq++) {
@@ -429,7 +395,7 @@ export class TiDBSessionStore {
         }
     }
     beginImportStaging(realSessionId, token) {
-        return new TiDBStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
+        return new TiDBStagingHandle(this.pool, this.hooks, realSessionId, stagingIdFor(realSessionId, token));
     }
     async assertNotPlaced(sessionId, what) {
         const placed = await this.placementOf(sessionId);
@@ -453,33 +419,6 @@ export class TiDBSessionStore {
         }
         return removed;
     }
-    async deleteSession(sessionId, owner) {
-        const conn = await this.pool.getConnection();
-        try {
-            await conn.beginTransaction();
-            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", sessionId);
-            if (claim.activeTaskId !== null) {
-                await conn.rollback();
-                throw new SessionActiveRunError(sessionId, claim.activeTaskId);
-            }
-            const [metaRes] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ?", [sessionId, owner]);
-            if (metaRes.affectedRows > 0)
-                await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
-            await conn.commit();
-            return metaRes.affectedRows > 0;
-        }
-        catch (err) {
-            try {
-                await conn.rollback();
-            }
-            catch {
-            }
-            throw err;
-        }
-        finally {
-            conn.release();
-        }
-    }
     get size() {
         return this.pending.size;
     }
@@ -489,12 +428,14 @@ export class TiDBSessionStore {
 }
 class TiDBStagingHandle {
     pool;
+    hooks;
     realSessionId;
     stagingId;
     nextSeq = 0;
     seen = new Set();
-    constructor(pool, realSessionId, stagingId) {
+    constructor(pool, hooks, realSessionId, stagingId) {
         this.pool = pool;
+        this.hooks = hooks;
         this.realSessionId = realSessionId;
         this.stagingId = stagingId;
     }
@@ -533,18 +474,14 @@ class TiDBStagingHandle {
                 }
             }
             else {
-                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,NULL,0,?) ON DUPLICATE KEY UPDATE session_id = session_id", [this.realSessionId, owner, now, now, minted]);
+                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES (?,?,?,?,NULL,0,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [this.realSessionId, owner, now, now, minted]);
                 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);
                 }
             }
-            const claim = await lockRootAndReadClaim(rowsOnConnection(conn), "mysql", this.realSessionId);
-            if (claim.activeTaskId !== null) {
-                await conn.rollback();
-                throw new SessionActiveRunError(this.realSessionId, claim.activeTaskId);
-            }
+            settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: this.realSessionId }));
             const [stagedRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const [dstRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const [dstMeta] = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = ?", [this.realSessionId]);
@@ -579,16 +516,7 @@ class TiDBStagingHandle {
             let leafId = null;
             if (lastRow[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRow[0].payload, this.realSessionId, "last staged row"));
-            const [settle] = await conn.query(`UPDATE session_meta SET owner = ?, updated_at = ?, leaf_id = ?, leaf_seq = ?, ${MIRROR_ON_COMMIT_SET} WHERE session_id = ? AND ${MIRROR_ON_COMMIT_GUARD}`, [owner, now, leafId, srcIds.length, this.realSessionId]);
-            if (settle.affectedRows !== 1) {
-                const locked = readPlacementRowStatement("mysql", this.realSessionId, { lock: true });
-                const [lockedRows] = await conn.query(locked.text, [...locked.values]);
-                const cell = lockedRows[0] === undefined ? undefined : placementCellFromRow(this.realSessionId, lockedRows[0]);
-                await conn.rollback();
-                if (cell?.role === "writer")
-                    throw new SessionWriterPresentError(this.realSessionId, cell.lane);
-                throw new SessionError("storage", `staged commit for ${this.realSessionId}: the commit point matched no row under a held row lock and the row is not a writer — refusing to guess`);
-            }
+            await conn.query("UPDATE session_meta SET owner = ?, updated_at = ?, leaf_id = ?, leaf_seq = ? WHERE session_id = ?", [owner, now, leafId, srcIds.length, this.realSessionId]);
             const [afterMeta] = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = ?", [this.realSessionId]);
             if (afterMeta[0]?.placement_kind != null) {
                 await conn.rollback();
@@ -603,7 +531,9 @@ class TiDBStagingHandle {
                 await conn.rollback();
             }
             catch { }
-            if (err instanceof SyncConflictError || err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SyncConflictError || err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `staged commit for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
         }

package/dist/stores-sql/tool-result-store-sql.d.ts

@@ -31,7 +31,7 @@ export declare function assertToolResultProvenanceSchema(query: (sql: string) =>
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
     /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
-     *  `retention-store-sql.ts`」逐字见 {@link MANAGED_RETENTION}(扫车道开着时本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
+     *  `retention-store-sql.ts`」逐字见 `plugins/retention-declaration.ts` 的 {@link MANAGED_RETENTION}(扫车道开着时本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
     readonly retention: RetentionDeclaration;
     constructor(db: SqlDriver, opts?: {
         readonly retention?: RetentionDeclaration;

package/dist/stores-sql/tool-result-store-sql.js

@@ -1,7 +1,7 @@
 import { MAX_MINTED_TOOL_RESULT_REF_CHARS, assertSafeToolResultRef, assertToolResultProvenanceMatch, normalizeToolResultProvenance } from "@sema-agent/core";
 import { pgSanitizeText } from "../plugins/pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
-import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-store-sql.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { ensureIndexes } from "../plugins/ensure-index.js";
 import { describeProbedTableDrift, schemaWaysOut } from "../plugins/schema-drift-sentence.js";
 import { isMissingColumnError } from "../plugins/sql-errors.js";

package/dist/stores-sql/windowed-session-storage.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 两只 SQL 会话存储(`tidb-session-storage.ts` / `pg-session-storage.ts`)共用的**窗口视图** —— 一次唤醒读出的有界日志 `[floor .. leaf]`。
+ *
+ * ## 组合,不继承
+ * 会话树的读法(按 id 取、按类型找、标签、到根的路径、叶子、日志标记、地板、回放丢失)只有引擎那一份:本类把唤醒读出的窗口交给引擎的
+ * `InMemorySessionStorage`(组合),每个读都转给它;方言孪生只说两件 SQL 的事 —— 一笔写怎么落库({@link persist}),地板之下按 id 回读一条
+ * ({@link readBelowFloor})。不再 `extends` 引擎的存储基类:方言店继承引擎的店基类造第二份店,是依赖方向门 R5′ 拒的形。
+ *
+ * ## 写序
+ * 先落库(方言孪生在自己的事务里按叶子 CAS),落成才记进窗口 —— 与引擎存储「先判后记」同序;落库被拒(CAS 输)时窗口一个字节不动。
+ * 记进窗口走引擎存储的追加口(不带期望叶:CAS 已在库里判过,窗口只是跟上那一笔)。
+ *
+ * ## 叶子是行说的那一格
+ * 叶子 = 库里那一格(`session_meta.leaf_id`,引擎存储契约里「后端说出的头」),不是窗口末条之后的叶子(fork 拷整份日志带着别的分支时两者不同)。
+ * 窗口(引擎的存储)从条目推叶子、不收后端说的头 ⇒ 叶子由本类自己持有:唤醒时取行上那一格(它不在窗口里 ⇒ `corrupt_session`,与引擎存储基类同一判、同一句),
+ * 之后每落一笔前进到「这一笔之后的叶子」(与库里同一事务写下的值同一读法)。窗口里那只按条目推出的叶子不被读。
+ */
+import { InMemorySessionStorage, type SessionLogMark, type SessionMetadata, type SessionStorage, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+export declare abstract class WindowedSessionStorage implements SessionStorage {
+    /** 唤醒读出的窗口(引擎的存储;叶子以外的每个读都是它的读)。 */
+    private readonly view;
+    /** 叶子(头注「叶子是行说的那一格」)。 */
+    private leaf;
+    /**
+     * `entries` = 窗口(按 `seq` 升序);`statedLeafId` = 行上那一格叶子;`floorEntryId` = 窗口的地板(没有压缩 ⇒ `null`,整条日志都在窗口里)。
+     * 地板不在窗口里 ⇒ 引擎存储拒 `corrupt_session`;行上的叶子不在窗口里 ⇒ 本类拒 `corrupt_session`(引擎存储基类的同一判、同一句)。
+     */
+    protected constructor(metadata: SessionMetadata, entries: SessionTreeEntry[], statedLeafId: string | null, floorEntryId: string | null);
+    /** 一笔写落库(方言孪生的事务:叶子 CAS + 追加事件)。抛 ⇒ 窗口不记。 */
+    protected abstract persist(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
+    /** 地板之下按 id 回读一条(窗口里没有的;标签目标等)。没有 ⇒ `undefined`。 */
+    protected abstract readBelowFloor(id: string): Promise<SessionTreeEntry | undefined>;
+    getMetadata(): Promise<SessionMetadata>;
+    getLeafId(): Promise<string | null>;
+    createEntryId(): Promise<string>;
+    findEntries<TType extends SessionTreeEntry["type"]>(type: TType): Promise<Array<Extract<SessionTreeEntry, {
+        type: TType;
+    }>>>;
+    getLabel(id: string): Promise<string | undefined>;
+    getPathToRoot(leafId: string | null): Promise<SessionTreeEntry[]>;
+    getEntries(): Promise<SessionTreeEntry[]>;
+    /** 窗口的地板(没有压缩 ⇒ `null`)。 */
+    getFloorId(): string | null;
+    /** SQL 唤醒没有回放可丢(行是逐条读的):恒 `undefined`,经引擎存储原样答。 */
+    getReplayLoss(): ReturnType<InMemorySessionStorage["getReplayLoss"]>;
+    /** 窗口此刻的日志标记(同步读;引擎存储的读法)。 */
+    logMarkNow(): SessionLogMark;
+    /**
+     * 窗口的地板那一条(窗口里就有,不另读库)—— 地板之下的 epoch 锚从它的父起沿分支走(`plugins/session-epoch-anchor.ts` 的 `epochFloorOf`)。
+     * 没有地板(整条日志都在窗口里)⇒ `undefined`;地板 id 指向窗口里没有的条目 ⇒ 坏会话(响亮)。
+     */
+    protected windowFloorEntry(): Promise<SessionTreeEntry | undefined>;
+    /** 窗口里没有的 id(地板之下)回落到库。 */
+    getEntry(id: string): Promise<SessionTreeEntry | undefined>;
+    appendEntry(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
+    /** 落成的一笔记进窗口,叶子前进到这一笔之后的叶子。 */
+    private record;
+    /** 叶子移动本身是一条落库的 `leaf` 条目,父 = 当前叶子(引擎存储的同一形:目标不在窗口里 ⇒ `not_found`,id 由引擎的铸法给)。 */
+    setLeafId(leafId: string | null, opts?: SessionWriteOptions): Promise<void>;
+}
+//# sourceMappingURL=windowed-session-storage.d.ts.map