@sema-agent/server 7.145.0 → 7.147.0

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

@@ -1,72 +1,8 @@
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
-import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
-import { ensureIndexes } from "./ensure-index.js";
 import { incarnationFromCell } from "../session-incarnation.js";
-import { lockRootAndReadClaim, rowsOnSqlExec } from "./execution-placement-sql.js";
-export const MANAGED_RETENTION = "managed";
-export const UNMANAGED_RETENTION = "none";
-export function retentionSweepRuns(sweep) {
-    return sweep.intervalSec > 0;
-}
-export function sqlStoreRetention(sweep) {
-    return retentionSweepRuns(sweep) ? MANAGED_RETENTION : UNMANAGED_RETENTION;
-}
-export const RETENTION_AUDIT_TABLE = "retention_audit";
-export const RETENTION_HOLD_TABLE = "retention_hold";
-export const RETENTION_LEASE_TABLE = "retention_lease";
+import { MANAGED_RETENTION } from "../plugins/retention-declaration.js";
+import { retentionDomainWhere, retentionIdSet } from "../plugins/retention-sql.js";
 export const RETENTION_TOMBSTONE_TABLE = "retention_tombstone";
-export const TIDB_RETENTION_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 TIDB_RETENTION_TOMBSTONE_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${RETENTION_TOMBSTONE_TABLE} (
      domain        VARCHAR(190) NOT NULL,
      -- kind:闭集(session | tool_result),见 RetentionTombstoneKind。
@@ -88,37 +24,7 @@ export const TIDB_RETENTION_STATEMENTS = [
      KEY idx_retention_tombstone_key (kind, row_key)
    ) COLLATE utf8mb4_bin`,
 ];
-export const PG_RETENTION_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 PG_RETENTION_TOMBSTONE_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS ${RETENTION_TOMBSTONE_TABLE} (
      domain        VARCHAR(190) COLLATE "C" NOT NULL,
      kind          VARCHAR(32) COLLATE "C"  NOT NULL,
@@ -128,16 +34,9 @@ export const PG_RETENTION_SCHEMA = [
      PRIMARY KEY (domain, kind, row_key)
    )`,
 ];
-export const RETENTION_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 const RETENTION_TOMBSTONE_INDEXES = [
     { table: `${RETENTION_TOMBSTONE_TABLE}`, name: "idx_retention_tombstone_key", columns: ["kind", "row_key"] },
 ];
-export async function ensurePgRetentionSchema(query) {
-    for (const stmt of PG_RETENTION_SCHEMA)
-        await query(stmt);
-    await ensureIndexes(query, "pg", RETENTION_INDEXES);
-}
 class RetentionAborted extends Error {
     why;
     constructor(why) {
@@ -151,7 +50,7 @@ export class SqlRetentionStore {
     db;
     opts;
     retention = MANAGED_RETENTION;
-    constructor(db, opts) {
+    constructor(db, opts = {}) {
         this.db = db;
         this.opts = opts;
     }
@@ -159,14 +58,10 @@ export class SqlRetentionStore {
         return this.db.dialect === "mysql" ? mysql : pg;
     }
     domainWhere(col, domain, pgIndex) {
-        return domain === ""
-            ? { sql: this.q(`(${col} IS NULL OR ${col} = ?)`, `(${col} IS NULL OR ${col} = $${pgIndex})`), params: [""] }
-            : { sql: this.q(`${col} = ?`, `${col} = $${pgIndex}`), params: [domain] };
+        return retentionDomainWhere(this.db.dialect, col, domain, pgIndex);
     }
     idSet(col, ids, pgIndex) {
-        return this.db.dialect === "mysql"
-            ? { sql: `${col} IN (${ids.map(() => "?").join(",")})`, params: [...ids] }
-            : { sql: `${col} = ANY($${pgIndex}::text[])`, params: [ids] };
+        return retentionIdSet(this.db.dialect, col, ids, pgIndex);
     }
     async tx(fn) {
         const conn = await this.db.connect();
@@ -189,22 +84,42 @@ export class SqlRetentionStore {
             conn.release();
         }
     }
-    requireAudit(input, action) {
-        if (!input.audit) {
-            throw new Error(`retention: refusing a destructive call (${action}) with no audit context — every destructive retention ` +
-                `transaction must persist its {mode, policyDays, fencingToken} alongside the deletion (DESIGN-270 §6 F5). ` +
-                `Pass \`audit\` from the sweep lane's current round.`);
+    statementFace(conn) {
+        return { query: (sql, params) => conn.query(sql, params) };
+    }
+    async heldBy(face, call) {
+        const holdLock = this.opts.transactionHooks?.retention?.holdLock;
+        if (holdLock === undefined)
+            return false;
+        const answer = await holdLock(face, call);
+        switch (answer) {
+            case "proceed":
+                return false;
+            case "held":
+                return true;
+            default: {
+                const unknown = answer;
+                throw new Error(`retention: holdLock answered ${JSON.stringify(unknown)} for ${call.op} in domain ${JSON.stringify(call.domain)} — the closed answer set is "proceed" | "held"; rolling back.`);
+            }
         }
-        return input.audit;
     }
-    async holdInForce(conn, domain) {
-        const key = domain;
-        await conn.query(this.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 conn.query(this.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;
+    async admittedBy(face, rootSessionId) {
+        const beforeCommit = this.opts.transactionHooks?.session?.beforeCommit;
+        if (beforeCommit === undefined)
+            return true;
+        const answer = await beforeCommit(face, { op: "retention-delete", rootSessionId });
+        if (answer === "proceed")
+            return true;
+        if (typeof answer === "object" && answer !== null && answer.refuse instanceof Error)
+            return false;
+        throw new Error(`retention: session.beforeCommit answered ${JSON.stringify(answer)} for root ${JSON.stringify(rootSessionId)} — the closed answer set is "proceed" | { refuse }; rolling back.`);
+    }
+    async referencedBy(face, candidates) {
+        const liveReferences = this.opts.transactionHooks?.retention?.liveReferences;
+        return liveReferences === undefined || candidates.length === 0 ? new Set() : liveReferences(face, candidates);
     }
-    async writeAuditRow(conn, row) {
-        await conn.query(this.q(`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()]);
+    async auditedBy(face, call, receipt) {
+        await this.opts.transactionHooks?.retention?.audit?.(face, call, receipt);
     }
     async writeTombstones(conn, domain, kind, keys) {
         if (keys.length === 0)
@@ -236,11 +151,12 @@ export class SqlRetentionStore {
         return { checkpoints, sessions, toolResults };
     }
     async expireCheckpoints(input) {
-        const audit = this.requireAudit(input, "expired_checkpoints");
+        const call = { domain: input.domain, op: "expireCheckpoints" };
         let skippedOnAbort = 0;
         try {
             return await this.tx(async (conn) => {
-                if (await this.holdInForce(conn, input.domain)) {
+                const face = this.statementFace(conn);
+                if (await this.heldBy(face, call)) {
                     skippedOnAbort = (await this.expiryCandidates(conn, input)).length + (await this.countPinnedExpiryCandidates(conn, input));
                     throw new RetentionAborted("hold_in_force");
                 }
@@ -256,8 +172,9 @@ export class SqlRetentionStore {
                         `AND NOT EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = checkpoint.session_id)`), [Date.now(), ...w.params, ...set.params]);
                     expired = res.affected;
                 }
-                await this.writeAuditRow(conn, { domain: input.domain, action: "expired_checkpoints", audit, deleted: expired, skipped: pinned, tombstones: 0 });
-                return { domain: input.domain, deleted: expired, skipped: pinned, tombstones: 0 };
+                const receipt = { domain: input.domain, deleted: expired, skipped: pinned, tombstones: 0 };
+                await this.auditedBy(face, call, receipt);
+                return receipt;
             });
         }
         catch (err) {
@@ -329,32 +246,35 @@ export class SqlRetentionStore {
         return rows.map((r) => String(r.ref));
     }
     async deleteExpiredSessions(input) {
-        const audit = this.requireAudit(input, "deleted_sessions");
+        const call = { domain: input.domain, op: "deleteExpiredSessions" };
         let skippedOnAbort = 0;
         try {
             return await this.tx(async (conn) => {
-                if (await this.holdInForce(conn, input.domain)) {
+                const face = this.statementFace(conn);
+                if (await this.heldBy(face, call)) {
                     skippedOnAbort = (await this.sessionCandidates(conn, input)).length + (await this.countProtectedSessions(conn, input));
                     throw new RetentionAborted("hold_in_force");
                 }
                 const candidates = await this.sessionCandidates(conn, input, true);
-                const rowsOn = rowsOnSqlExec(conn);
-                const doomed = [];
+                const admitted = [];
                 for (const c of candidates)
-                    if ((await lockRootAndReadClaim(rowsOn, this.db.dialect, c.id)).activeTaskId === null)
-                        doomed.push(c);
-                const skipped = await this.countProtectedSessions(conn, input);
+                    if (await this.admittedBy(face, c.id))
+                        admitted.push(c);
+                const referenced = await this.referencedBy(face, admitted.map((c) => c.id));
+                const doomed = admitted.filter((c) => !referenced.has(c.id));
+                const skipped = (await this.countProtectedSessions(conn, input)) + (candidates.length - doomed.length);
                 skippedOnAbort = doomed.length + skipped;
                 let deleted = 0;
                 let tombstones = 0;
                 const ids = doomed.map((d) => d.id);
                 if (ids.length > 0) {
+                    await this.opts.transactionHooks?.retention?.beforeDelete?.(face, doomed.map((d) => ({ sessionId: d.id, incarnation: d.incarnation })));
                     deleted = await this.purgeSessionTrees(conn, input.domain, ids);
                     tombstones = await this.writeTombstones(conn, input.domain, "session", ids);
                 }
-                await this.writeAuditRow(conn, { domain: input.domain, action: "deleted_sessions", audit, deleted, skipped, tombstones });
-                const endedSpaces = doomed.flatMap((d) => (d.incarnation === undefined ? [] : [{ sessionId: d.id, spaceKey: d.incarnation }]));
-                return { domain: input.domain, deleted, skipped, tombstones, ...(endedSpaces.length > 0 ? { endedSpaces } : {}) };
+                const receipt = { domain: input.domain, deleted, skipped, tombstones };
+                await this.auditedBy(face, call, receipt);
+                return receipt;
             });
         }
         catch (err) {
@@ -365,28 +285,11 @@ export class SqlRetentionStore {
     }
     async purgeSessionTrees(conn, domain, ids) {
         const set = (col, pgIndex) => this.idSet(col, ids, pgIndex);
-        {
-            const s = set("tr.session_id", 1);
-            await conn.query(this.q(`DELETE te FROM task_event te JOIN task_run tr ON te.task_id = tr.task_id WHERE ${s.sql}`, `DELETE FROM task_event te USING task_run tr WHERE te.task_id = tr.task_id AND ${s.sql}`), [...s.params]);
-        }
-        {
-            const s = set("tr.session_id", 1);
-            await conn.query(this.q(`DELETE ta FROM task_active ta JOIN task_run tr ON ta.task_id = tr.task_id WHERE ${s.sql}`, `DELETE FROM task_active ta USING task_run tr WHERE ta.task_id = tr.task_id AND ${s.sql}`), [...s.params]);
-        }
-        {
-            const s = set("session_id", 1);
-            await conn.query(`DELETE FROM task_run WHERE ${s.sql}`, [...s.params]);
-        }
         {
             const s = set("checkpoint.session_id", 1);
             const w = this.domainWhere("sm.owner", domain, 2);
             await conn.query(`DELETE FROM checkpoint WHERE ${s.sql} AND EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = checkpoint.session_id AND ${w.sql})`, [...s.params, ...w.params]);
         }
-        {
-            const s = set("checkpoint_ctx.session_id", 1);
-            const w = this.domainWhere("sm.owner", domain, 2);
-            await conn.query(`DELETE FROM checkpoint_ctx WHERE ${s.sql} AND EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = checkpoint_ctx.session_id AND ${w.sql})`, [...s.params, ...w.params]);
-        }
         {
             const s = set("owner_session_id", 1);
             await conn.query(`DELETE FROM tool_result WHERE ${s.sql}`, s.params);
@@ -396,12 +299,8 @@ export class SqlRetentionStore {
             await conn.query(`SELECT scope FROM file_history_scope WHERE ${s.sql} ORDER BY scope FOR UPDATE`, s.params);
         }
         for (const [table, col] of [
-            ["resume_anchor", "session_id"],
-            ["approval_exemption", "session_id"],
             ["session_policy", "session_id"],
             ["session_policy_rev_mark", "session_id"],
-            ...(this.opts.taskAttachmentTable ? [["task_attachment", "session_id"]] : []),
-            [USER_INPUT_ACCEPTANCE_TABLE, "session_id"],
             ["file_history_tracked", "scope"],
             ["file_history_version", "scope"],
             ["file_history_boundary", "scope"],
@@ -412,21 +311,6 @@ export class SqlRetentionStore {
             const s = set(col, 1);
             await conn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
         }
-        if (this.opts.taskListTables) {
-            const listKeys = ids.map((id) => taskListKeyFor(id)).sort();
-            {
-                const s = this.idSet("list_key", listKeys, 1);
-                await conn.query(`SELECT list_key FROM ${TASK_LIST_META_TABLE} WHERE ${s.sql} ORDER BY list_key FOR UPDATE`, s.params);
-            }
-            for (const table of [TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE]) {
-                const s = this.idSet("list_key", listKeys, 1);
-                await conn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
-            }
-        }
-        {
-            const s = set("session_id", 1);
-            await conn.query(`DELETE FROM workflow_completion_inbox WHERE ${s.sql}`, s.params);
-        }
         const s = set("session_id", 1);
         const w = this.domainWhere("owner", domain, 2);
         const metaRes = await conn.query(`DELETE FROM session_meta WHERE ${s.sql} AND ${w.sql}`, [...s.params, ...w.params]);
@@ -440,11 +324,12 @@ export class SqlRetentionStore {
         return metaRes.affected;
     }
     async deleteOrphanToolResults(input) {
-        const audit = this.requireAudit(input, "deleted_tool_results");
+        const call = { domain: input.domain, op: "deleteOrphanToolResults" };
         let skippedOnAbort = 0;
         try {
             return await this.tx(async (conn) => {
-                if (await this.holdInForce(conn, input.domain)) {
+                const face = this.statementFace(conn);
+                if (await this.heldBy(face, call)) {
                     skippedOnAbort = (await this.orphanToolResultCandidates(conn, input)).length + (await this.countLiveReachableToolResults(conn, input));
                     throw new RetentionAborted("hold_in_force");
                 }
@@ -458,8 +343,9 @@ export class SqlRetentionStore {
                     deleted = res.affected;
                     tombstones = await this.writeTombstones(conn, input.domain, "tool_result", refs);
                 }
-                await this.writeAuditRow(conn, { domain: input.domain, action: "deleted_tool_results", audit, deleted, skipped: reachable, tombstones });
-                return { domain: input.domain, deleted, skipped: reachable, tombstones };
+                const receipt = { domain: input.domain, deleted, skipped: reachable, tombstones };
+                await this.auditedBy(face, call, receipt);
+                return receipt;
             });
         }
         catch (err) {
@@ -474,14 +360,4 @@ export class SqlRetentionStore {
         return Number(rows[0]?.n ?? 0);
     }
 }
-export class TiDBRetentionStore extends SqlRetentionStore {
-    constructor(pool, opts) {
-        super(mysqlDriver(pool), opts);
-    }
-}
-export class PgRetentionStore extends SqlRetentionStore {
-    constructor(pool, opts) {
-        super(pgDriver(pool), opts);
-    }
-}
 //# sourceMappingURL=retention-store-sql.js.map

package/dist/{plugins → stores-sql}/roster-store-sql.d.ts

@@ -22,8 +22,8 @@
  */
 import type { Pool } from "mysql2/promise";
 import { type RosterStore, type RosterEntry, type RosterAccess } from "@sema-agent/core";
-import type { PgQueryFn } from "./pg-query.js";
-import { type IndexSpec } from "./ensure-index.js";
+import type { PgQueryFn } from "../plugins/pg-query.js";
+import { type IndexSpec } from "../plugins/ensure-index.js";
 export declare const ROSTER_TABLE = "agent_roster";
 export declare function ensureTiDBRosterSchema(pool: Pool): Promise<void>;
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgRosterSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */

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

@@ -1,5 +1,5 @@
 import { normalizeAgentName } from "@sema-agent/core";
-import { ensureIndexes } from "./ensure-index.js";
+import { ensureIndexes } from "../plugins/ensure-index.js";
 export const ROSTER_TABLE = "agent_roster";
 function rowToEntry(r) {
     return {

package/dist/{plugins → stores-sql}/session-event-payload.d.ts

@@ -28,7 +28,7 @@
  * `isJsonColumnBodyProblem`,不另写一份。
  */
 import { type SessionTreeEntry } from "@sema-agent/core";
-import { type JsonColumnReader } from "./sql-json-column.js";
+import { type JsonColumnReader } from "../plugins/sql-json-column.js";
 /**
  * 形读者:core 自己声明的 `SessionTreeEntryBase` 里那两把**不可省**的串键。
  *

package/dist/{plugins → stores-sql}/session-event-payload.js

@@ -1,5 +1,5 @@
 import { SessionError } from "@sema-agent/core";
-import { decodeJsonColumn, isJsonColumnBodyProblem } from "./sql-json-column.js";
+import { decodeJsonColumn, isJsonColumnBodyProblem } from "../plugins/sql-json-column.js";
 export const readSessionEventPayload = (body) => {
     if (typeof body !== "object" || body === null || Array.isArray(body))
         return { problem: "expected a JSON object (a SessionTreeEntry)" };

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

@@ -106,7 +106,7 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
      *      order. This is the SAME lock order putRules uses (policy row → mark row), which is the whole point: the
      *      obvious shape (`INSERT … SELECT` the marks, then DELETE) locks the MARK first and takes only a SHARED lock
      *      on the policy rows it reads, i.e. a reversed order PLUS an S→X upgrade — the textbook deadlock this repo
-     *      已经吃过两次(retention-store-sql.ts ④a/④b 的 [ref] 案:一边持 boundary 等哨兵,一边持哨兵等 boundary)。
+     *      已经吃过两次(留存会话树删除的 file-history 哨兵腿与任务清单腿的 [ref] 案:一边持 boundary 等哨兵,一边持哨兵等 boundary)。
      *   ② the marks (their revs come from ①'s already-locked rows) — `GREATEST` merge, so a mark only ever RISES and
      *      repeated erases never walk the line back.
      *   ③ the DELETE — scoped to ①'s POLICY_KEY SET, never re-scanned by `session_id`. 🔴 This is the whole of

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

@@ -0,0 +1,59 @@
+/**
+ * 会话店的**事务内钩**(部署在店的写事务里参与的唯一一扇门)—— 店写的是引擎座表(`session_meta` / `session_event`),部署记在会话上的格与认领住部署自己的表;
+ * 跨两边的「同一事务」只经这里:店锁住根 `session_meta` 行之后、写之前,把**本事务的语句面**交给部署,部署读自己的认领、写自己的格,答放行或拒。
+ *
+ * ## 形 = 引擎 SQL 店包的钩表(`@sema-agent/core-stores-sql` 的 `SqlTransactionHooks.session.beforeCommit`)
+ * {@link SessionWriteHooks.beforeCommit} 与包里那一只同名、同调用时刻(根行锁住之后、写之前)、同语句面(本事务连接的 `query`)、同写闭集
+ * (`import` / `delete` / `retention-delete`)。本仓还不依赖那只包 ⇒ 型在这里声明;店随包搬家时改从包根取型。与包的形只差一处,是向引擎的请托:
+ * 拒的载荷 —— 包里是一句话(`{ refuse: string }`),这里是部署的具名错误(`{ refuse: Error }`):导入 / 删除的调用方按错误的型答各自的 wire 码
+ * (409 `session_active` / `conflict.session_writer`),一句话答不出。
+ *
+ * ## 同事务两句,不是同一句 UPDATE
+ * 认领(`task_active`)与部署格住的表都不是根行所在的表 ⇒ 一句 UPDATE 里拿不到「锁住根行 + 当前读别的表」:PG 读已提交下子查询读的是语句快照、
+ * 不对别的表的行加锁,也不在 EvalPlanQual 里复判它们。所以是**两句**:店先 `FOR UPDATE` 锁根行(删除 / 重登记 / 改属主都要先拿这把锁),
+ * 再在**同一连接**上交出语句面,部署用新语句锁定读(PG 新快照、TiDB 当前读)。钩里的写随店的事务提交或回滚(店拒、或任何一步抛,一起撤)。
+ *
+ * ## 键控 fork(服务扩展,包里没有)
+ * 调用方给目标 id 与键的 fork(`forkTo`)是本服务的扩展:键是部署格,在建目标行的同一事务里由 {@link SessionWriteHooks.keyedFork} 记下;撞上已在的目标时
+ * 读它的属主与键。包随店搬家时这一组是向引擎的请托(带目标 id 与键的 fork,或钩表多一组)。
+ */
+/** 店交给钩的语句面:本事务自己的连接(与包的 `SqlStatementFace` 同形:`query` 答行 + 受影响行数)。 */
+export interface SessionTxStatements {
+    query(sql: string, params?: unknown[]): Promise<{
+        readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+        readonly affected: number;
+    }>;
+}
+/**
+ * 改动会话树根的写(闭集,与包同一组词):
+ *  · `import` —— 导入写口(整段新建、整段换装、暂存提交)落定这一行:根行已被本事务锁住 / 占下;
+ *  · `delete` —— 属主删除:根行已被本事务锁住;
+ *  · `retention-delete` —— 留存删除一棵会话树的根(留存座的事务;根行已锁)。
+ */
+export interface SessionWrite {
+    readonly op: "import" | "delete" | "retention-delete";
+    readonly rootSessionId: string;
+}
+/** 钩的答案:放行,或拒(店回滚、一个字节不写、原样抛这只错)。 */
+export type SessionWriteVerdict = "proceed" | {
+    readonly refuse: Error;
+};
+/** 键控 fork 撞上已在的目标时,那一行的属主与 fork 键(一次读;`undefined` = 行不在)。 */
+export interface ForkTargetReading {
+    readonly owner: string | null;
+    readonly forkKey: string | null;
+}
+/** 部署交给会话店的钩表(组合座装配)。 */
+export interface SessionWriteHooks {
+    /** 根行锁住之后、写之前调(同一事务、同一连接)。 */
+    beforeCommit(txn: SessionTxStatements, write: SessionWrite): Promise<SessionWriteVerdict>;
+    /** 键控 fork(服务扩展):`record` 在建目标行的同一事务里记下键(目标行是本事务刚插下的);`targetOf` = 撞上已在的目标时那一行的属主与键。 */
+    readonly keyedFork: {
+        record(txn: SessionTxStatements, fork: {
+            readonly rootSessionId: string;
+            readonly forkKey: string;
+        }): Promise<void>;
+        targetOf(sessionId: string): Promise<ForkTargetReading | undefined>;
+    };
+}
+//# sourceMappingURL=session-write-hooks.d.ts.map

package/dist/stores-sql/session-write-hooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-write-hooks.js.map

package/dist/{plugins → stores-sql}/tidb-session-storage.d.ts

@@ -1,11 +1,12 @@
-import { BaseSessionStorage, type SessionMetadata, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { type SessionMetadata, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
+import { WindowedSessionStorage } from "./windowed-session-storage.js";
 export declare const SESSION_EVENT_LATEST_BY_TYPE_SQL: {
     readonly floor: `SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ ${string} FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1`;
     readonly epochAnchor: `SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ seq, ${string} FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`;
 };
 /**
- * TiDB-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
+ * TiDB-backed session storage — the durable L1 event log for one session (the window view and its reads: {@link WindowedSessionStorage}).
  *
  * - `appendEntry` / `setLeafId` persist under an **atomic compare-and-set on `leaf_id`** (core's F2
  *   optimistic-lock seam): the conditional UPDATE's only predicate is `leaf_id <=> ?`, so a write lands
@@ -14,11 +15,11 @@ export declare const SESSION_EVENT_LATEST_BY_TYPE_SQL: {
  *   `isSessionConflict`), with the `(session_id, seq)` primary key as the backstop for a racing writer
  *   that grabbed the same seq. ([ref] 件2 更正:`leaf_seq` **不是**判据 —— 它是无条件的 `SET leaf_seq =
  *   leaf_seq + 1` 计数器,在同一事务内重读出来给事件铸 `seq`,从不进 WHERE。)
- * - The in-memory base tree is the wake-time snapshot; every write is also mirrored into it so the
- *   live harness keeps reading a consistent view. Wake is **bounded** to `[floor .. leaf]` (F3,
+ * - The window (core's in-memory storage, composed) is the wake-time snapshot; every write lands here first and is then
+ *   recorded into it so the live harness keeps reading a consistent view. Wake is **bounded** to `[floor .. leaf]` (F3,
  *   core 1.6.0 branch-floor seam); older history is covered by the last compaction's summary.
  */
-export declare class TiDBSessionStorage extends BaseSessionStorage {
+export declare class TiDBSessionStorage extends WindowedSessionStorage {
     private readonly pool;
     private readonly sessionId;
     private readonly floorSeq;
@@ -43,21 +44,19 @@ export declare class TiDBSessionStorage extends BaseSessionStorage {
      * helper trims a FULL-loaded path in memory, whereas we compute the floor seq first and only `SELECT
      * seq >= floorSeq` — so the head never leaves cold storage. Our sessions are LINEAR (no fork), so
      * seq-order == root→leaf path-order and our `seq >= floorSeq` tail is byte-identical to
-     * `boundedTail(path).tail`; the resulting floored `BaseSessionStorage.buildContext()` matches a
+     * `boundedTail(path).tail`; the resulting floored window's `buildContext()` matches a
      * full-tree wake (core's `session-floor.test.ts`). If branching is ever added, switch to `boundedTail`.
      */
     static wake(pool: Pool, sessionId: string): Promise<TiDBSessionStorage | null>;
     /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). */
     private static computeFloor;
-    /** Sub-floor lookups (e.g. a label target) aren't in the loaded tail — fall back to the durable log. */
-    getEntry(id: string): Promise<SessionTreeEntry | undefined>;
-    appendEntry(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
-    setLeafId(leafId: string | null, opts?: SessionWriteOptions): Promise<void>;
+    /** Sub-floor lookups (e.g. a label target) aren't in the loaded tail — read the durable log. */
+    protected readBelowFloor(id: string): Promise<SessionTreeEntry | undefined>;
     /**
      * Atomically: CAS the meta leaf (+bump leaf_seq), then append the event at the new seq.
      * The `(session_id, seq)` primary key is the backstop — a racing writer that grabbed the same
      * seq makes our INSERT fail with a duplicate-key, which we translate to a conflict too.
      */
-    private persist;
+    protected persist(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
 }
 //# sourceMappingURL=tidb-session-storage.d.ts.map

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

@@ -1,24 +1,25 @@
 import { emitLeafAdvance } from "../session-leaf-bus.js";
-import { BaseSessionStorage, SessionError, leafIdAfterEntry, } from "@sema-agent/core";
-import { toIso } from "./sql-row-helpers.js";
-import { isMysqlDupKeyError } from "./sql-errors.js";
-import { PLACEMENT_SELECT_COLUMNS, placementFromRow } from "./session-placement.js";
+import { SessionError, leafIdAfterEntry, } from "@sema-agent/core";
+import { toIso } from "../plugins/sql-row-helpers.js";
+import { isMysqlDupKeyError } from "../plugins/sql-errors.js";
+import { PLACEMENT_SELECT_COLUMNS, placementFromRow } from "../plugins/session-placement.js";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
-import { scanEpochAnchor } from "./session-epoch-anchor.js";
-import { jsonColumnText } from "./sql-json-column.js";
+import { scanEpochAnchor } from "../plugins/session-epoch-anchor.js";
+import { jsonColumnText } from "../plugins/sql-json-column.js";
 import { incarnationFromCell } from "../session-incarnation.js";
+import { WindowedSessionStorage } from "./windowed-session-storage.js";
 const SESSION_EVENT_BY_TYPE_HINT = "/*+ USE_INDEX(session_event, idx_session_event_type) */";
 export const SESSION_EVENT_LATEST_BY_TYPE_SQL = {
     floor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1`,
     epochAnchor: `SELECT ${SESSION_EVENT_BY_TYPE_HINT} seq, ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`,
 };
 const isDupKey = isMysqlDupKeyError;
-export class TiDBSessionStorage extends BaseSessionStorage {
+export class TiDBSessionStorage extends WindowedSessionStorage {
     pool;
     sessionId;
     floorSeq;
     constructor(pool, sessionId, metadata, entries, leafId, floorEntryId = null, floorSeq = 0) {
-        super(metadata, entries, leafId, { floorEntryId });
+        super(metadata, entries, leafId, floorEntryId);
         this.pool = pool;
         this.sessionId = sessionId;
         this.floorSeq = floorSeq;
@@ -54,24 +55,12 @@ export class TiDBSessionStorage extends BaseSessionStorage {
             return { floorEntryId: null, floorSeq: 0 };
         return { floorEntryId: fk, floorSeq: Number(seqRows[0].seq) };
     }
-    async getEntry(id) {
-        const inMem = await super.getEntry(id);
-        if (inMem)
-            return inMem;
+    async readBelowFloor(id) {
         const [rows] = await this.pool.query(`SELECT ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? AND entry_id = ?`, [this.sessionId, id]);
         if (rows[0] === undefined)
             return undefined;
         return decodeSessionEventPayload(rows[0].payload, this.sessionId, id);
     }
-    async appendEntry(entry, opts) {
-        await this.persist(entry, opts);
-        this.recordEntry(entry);
-    }
-    async setLeafId(leafId, opts) {
-        const leafEntry = this.createLeafEntry(leafId);
-        await this.persist(leafEntry, opts);
-        this.recordEntry(leafEntry);
-    }
     async persist(entry, opts) {
         const newLeaf = leafIdAfterEntry(entry);
         const conditional = opts !== undefined && opts.expectedLeafId !== undefined;