@sema-agent/server 7.146.0 → 7.148.0

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

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, annulProofFailure, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
-import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isMissingColumnError, retryOnDeadlock } from "./sql-errors.js";
-import { describeProbedTableDrift } from "./schema-drift-sentence.js";
+import { BlobTooLargeError, SqlBlobIndex } from "./blob-index-sql.js";
+import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
+import { isMissingColumnError, retryOnDeadlock } from "../plugins/sql-errors.js";
+import { describeProbedTableDrift } from "../plugins/schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
 export const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -28,17 +28,22 @@ export class SqlFileHistoryStore {
     pool;
     blobExchange = {
         put: (hash, bytes) => this.putExchangedBlob(hash, bytes),
-        get: (hash) => this.blobs.getBlob(hash),
-        has: (hashes) => this.blobs.hasBlobs([...hashes]),
+        get: (hash) => this.blobs.get(hash),
+        has: (hashes) => this.blobs.has([...hashes]),
     };
     blobs;
     spentAttempts = new Set();
     activeAttempts = new Set();
     boundaryKeep;
-    constructor(db, pool, blobBackend, opts) {
+    constructor(db, pool, opts) {
         this.db = db;
         this.pool = pool;
-        this.blobs = blobBackend ?? new SqlBlobBackend(this.db.dialect, this.pool, undefined, FILE_HISTORY_BLOB_TABLE);
+        this.blobs = new SqlBlobIndex(this.db.dialect, this.pool, {
+            table: FILE_HISTORY_BLOB_TABLE,
+            ...(opts?.blobs !== undefined ? { bytes: opts.blobs } : {}),
+            ...(opts?.blobSqlMaxBytes !== undefined ? { maxBytes: opts.blobSqlMaxBytes } : {}),
+            ...(opts?.log !== undefined ? { log: opts.log } : {}),
+        });
         this.boundaryKeep = resolveFileHistoryRetention(this.db.dialect === "mysql" ? "TiDBFileHistoryStore" : "PgFileHistoryStore", opts?.retention);
     }
     q(mysql, pg) {
@@ -95,7 +100,7 @@ export class SqlFileHistoryStore {
                 const baseAvailable = cap.state !== "unreadable";
                 let v1;
                 if (cap.state === "file") {
-                    await this.blobs.putBlob(cap.hash, cap.bytes);
+                    await this.blobs.put(cap.hash, cap.bytes);
                     v1 = { blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) };
                 }
                 else if (cap.state === "absent") {
@@ -344,7 +349,7 @@ export class SqlFileHistoryStore {
                     staged.set(t.keyHash, { kind: "unchanged", version: last.version });
                     continue;
                 }
-                await this.blobs.putBlob(cap.hash, cap.bytes);
+                await this.blobs.put(cap.hash, cap.bytes);
                 staged.set(t.keyHash, { kind: "changed", blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) });
             }
             const verdict = boundaryPublishVerdict({ aborted: signal?.aborted === true });
@@ -471,7 +476,7 @@ export class SqlFileHistoryStore {
                     if (rec.blobHash === null)
                         target = { absent: true };
                     else {
-                        const bytes = await this.blobs.getBlob(rec.blobHash);
+                        const bytes = await this.blobs.get(rec.blobHash);
                         if (bytes === undefined) {
                             ledger.failed.push({ path: t.trackKey, reason: `blob ${rec.blobHash} missing (store integrity)` });
                             continue;
@@ -594,14 +599,14 @@ export class SqlFileHistoryStore {
         const orphans = rows.map((r) => String(r.blob_hash));
         if (orphans.length === 0)
             return 0;
-        return this.blobs.deleteBlobs(orphans);
+        return this.blobs.sweep(orphans);
     }
     async putExchangedBlob(hash, bytes) {
         if (sha256hex(bytes) !== hash) {
             return { ok: false, error: { code: "adopt_failed", message: `blob ${hash}: the bytes do not hash to this address — nothing stored`, permanence: "terminal" } };
         }
         try {
-            await this.blobs.putBlob(hash, bytes);
+            await this.blobs.put(hash, bytes);
             return { ok: true };
         }
         catch (err) {
@@ -760,7 +765,7 @@ export class SqlFileHistoryStore {
             if (existing !== null && !sameGraph) {
                 return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" already holds a DIFFERENT history — a first import requires an empty target and a retry is legal only for the identical envelope (atomic visibility prevents half-graphs; this law prevents publishing the wrong complete graph over locally-grown history)` } };
             }
-            const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.putBlob(hash, bytes));
+            const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.put(hash, bytes));
             if (!verified.ok)
                 return verified;
             if (sameGraph)
@@ -813,13 +818,13 @@ export class SqlFileHistoryStore {
     }
 }
 export class TiDBFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool, blobBackend, opts) {
-        super(mysqlDriver(pool), pool, blobBackend, opts);
+    constructor(pool, opts) {
+        super(mysqlDriver(pool), pool, opts);
     }
 }
 export class PgFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool, blobBackend, opts) {
-        super(pgDriver(pool), pool, blobBackend, opts);
+    constructor(pool, opts) {
+        super(pgDriver(pool), pool, opts);
     }
 }
 export async function assertFileHistorySchema(query, dialect) {

package/dist/stores-sql/mailbox-store-sql.d.ts

@@ -16,10 +16,6 @@ export declare const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";
  *  是**盒**事实(与 `next_seq` 同生命周期):`drop` 随盒删、`reap` 留着(它清掉的东西从没被收过)。新表而不是 `mailbox` 加列,理由同墓碑表(存量库零运维动作)。
  *  `digests` = 引擎 `mailboxReplayDigests` 的四面摘要 JSON(只读那一只函数,不另算)。 */
 export declare const MAILBOX_CONSUMED_TABLE = "mailbox_consumed";
-/**
- * 身份键(`scope` / `handle` / lease `owner`)的 UTF-8 字节上界 = 键列宽(TiDB `VARBINARY(190)`;PG 列按字符,本判官在两方言上都按字节拒)。
- */
-export declare const MAILBOX_KEY_MAX_UTF8_BYTES = 190;
 /**
  * 🔴 **「这只串能当收件箱的身份键吗」的唯一判官**(三只键列:`scope` / `handle` / lease `owner`;两方言同一只、同一句拒因)。一只串当得了键 ⇔
  *  ⓪ `scope` 非空(引擎 InMemory 同一句「without a scope」:没有箱址;handle / owner 空照引擎参照形放行);
@@ -46,6 +42,13 @@ export declare const MAILBOX_KEYED_TABLES: readonly ["mailbox", "mailbox_message
 export type MailboxKeyedTable = (typeof MAILBOX_KEYED_TABLES)[number];
 /** 按键删收件箱表族的一张表(两方言;参数 = [scope_key, handle])。 */
 export declare function mailboxKeyDeleteSql(dialect: SqlDialect, table: MailboxKeyedTable): string;
+/**
+ * **整盒删**(盒行先删 → 消息 → 消费记录 → 墓碑,{@link MAILBOX_KEYED_TABLES} 序;锁序与理由见店的 `drop`)发在调用方事务的连接上。
+ * 语句源唯一:店的 `drop` 与删净会话的执行体(`plugins/retention-deployment.ts` 的部署行,在执行体那一个事务里)同调。判官拒的键没有箱 ⇒ 零语句。
+ */
+export declare function dropMailboxBoxOn(exec: {
+    query(sql: string, params: unknown[]): Promise<unknown>;
+}, dialect: SqlDialect, scope: string, handle: string): Promise<void>;
 /** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏行的 fail-closed 抛必须**响亮**——core 唯一的
  *  claimLease 调用方(peer-session-drain)吞掉该错,店不记这一笔就成了「静默永久卡箱」。抛之前记
  *  `mailbox_message_column_corrupt`(scope/handle/seq/column/code),运维按 seq 修行。

package/dist/stores-sql/mailbox-store-sql.js

@@ -1,7 +1,7 @@
 import { isUtf8 } from "node:buffer";
 import { MAILBOX_CONSUMED_ID_WINDOW, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_RECORD_ID_MAX_CHARS, MAILBOX_REPLAY_FACETS, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MailboxStoreError, assertMailboxDecisionMove, judgeMailboxAppendById, mailboxReplayDigests, readMailboxAppend, readMailboxPeerMeta, readStoredMailboxDecision } from "@sema-agent/core";
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "../plugins/pg-safe-json.js";
-import { isWellFormedUnicode } from "../principal-jwt.js";
+import { PRINCIPAL_MAX_BYTES, isWellFormedUnicode } from "../principal-shape.js";
 import { ensureIndexes } from "../plugins/ensure-index.js";
 import { escapeLike } from "../plugins/sql-escape.js";
 import { SqlJsonColumnError, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readStringArrayColumn } from "../plugins/sql-json-column.js";
@@ -22,15 +22,14 @@ function rowToTombstone(r) {
     const label = r.label === null || r.label === undefined ? undefined : bufToStr(r.label);
     return { handle: bufToStr(r.handle), retiredAt: Number(r.retired_at_ms), ...(label !== undefined ? { label } : {}) };
 }
-export const MAILBOX_KEY_MAX_UTF8_BYTES = 190;
 export function mailboxKeyProblem(what, v) {
     if (what === "scope" && (v === undefined || v === ""))
         return "MailboxStore: refusing a message without a scope (an empty scope addresses no box)";
     const unaddressable = byteExactIdentityProblem(what, v);
     if (unaddressable !== undefined)
         return unaddressable;
-    if (Buffer.byteLength(v, "utf8") > MAILBOX_KEY_MAX_UTF8_BYTES) {
-        return `MailboxStore: ${what} exceeds the ${MAILBOX_KEY_MAX_UTF8_BYTES}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`;
+    if (Buffer.byteLength(v, "utf8") > PRINCIPAL_MAX_BYTES) {
+        return `MailboxStore: ${what} exceeds the ${PRINCIPAL_MAX_BYTES}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`;
     }
     return undefined;
 }
@@ -122,6 +121,12 @@ export const MAILBOX_KEYED_TABLES = [MAILBOX_TABLE, MAILBOX_MSG_TABLE, MAILBOX_C
 export function mailboxKeyDeleteSql(dialect, table) {
     return dialect === "mysql" ? `DELETE FROM ${table} WHERE scope_key = ? AND handle = ?` : `DELETE FROM ${table} WHERE scope_key = $1 AND handle = $2`;
 }
+export async function dropMailboxBoxOn(exec, dialect, scope, handle) {
+    if (keyless(scope, handle))
+        return;
+    for (const table of MAILBOX_KEYED_TABLES)
+        await exec.query(mailboxKeyDeleteSql(dialect, table), [scope, handle]);
+}
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
 }
@@ -223,18 +228,18 @@ function decisionMoveVerdict(rows, expect) {
 }
 export async function ensureTiDBMailboxSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
-    scope VARCHAR(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    scope VARCHAR(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     next_seq BIGINT NOT NULL,
-    lease_owner VARBINARY(190) NULL,
+    lease_owner VARBINARY(${PRINCIPAL_MAX_BYTES}) NULL,
     lease_expires_at_ms BIGINT NULL,
     lease_max_seq BIGINT NULL,
     PRIMARY KEY (scope_key, handle)
   ) COLLATE utf8mb4_bin`);
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_MSG_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     seq BIGINT NOT NULL,
     from_id VARBINARY(255) NULL,
     content LONGTEXT NOT NULL,
@@ -259,16 +264,16 @@ export async function ensureTiDBMailboxSchema(pool) {
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
   ) COLLATE utf8mb4_bin`);
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_CONSUMED_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     seq BIGINT NOT NULL,
     record_id VARCHAR(${MAILBOX_RECORD_ID_MAX_CHARS}) NOT NULL,
     digests TEXT NOT NULL,
     PRIMARY KEY (scope_key, handle, seq)
   ) COLLATE utf8mb4_bin`);
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TOMBSTONE_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     retired_at_ms BIGINT NOT NULL,
     -- 退役前的显示名(会话的删前 title)。纯显示面:目录据它铸 PeerSessionRecord.name;NULL = 当时无名可用。
     label TEXT NULL,
@@ -281,18 +286,18 @@ export const MAILBOX_INDEXES = [
 ];
 export async function ensurePgMailboxSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
-    scope VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    scope VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     next_seq BIGINT NOT NULL,
-    lease_owner VARCHAR(190) COLLATE "C",
+    lease_owner VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C",
     lease_expires_at_ms BIGINT,
     lease_max_seq BIGINT,
     PRIMARY KEY (scope_key, handle)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_MSG_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     seq BIGINT NOT NULL,
     from_id VARCHAR(255) COLLATE "C",
     content TEXT COLLATE "C" NOT NULL,
@@ -304,16 +309,16 @@ export async function ensurePgMailboxSchema(q) {
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_CONSUMED_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     seq BIGINT NOT NULL,
     record_id VARCHAR(${MAILBOX_RECORD_ID_MAX_CHARS}) COLLATE "C" NOT NULL,
     digests TEXT COLLATE "C" NOT NULL, -- TiDB twin 同注:已收窗(core 7.61.0),四面摘要 JSON
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TOMBSTONE_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     retired_at_ms BIGINT NOT NULL,
     label TEXT COLLATE "C", -- TiDB twin 同注:纯显示面,NULL = 无名可用
     PRIMARY KEY (scope_key, handle)
@@ -441,10 +446,7 @@ export class TiDBMailboxStore {
     async drop(scope, handle) {
         if (keyless(scope, handle))
             return;
-        await this.tx(async (c) => {
-            for (const table of MAILBOX_KEYED_TABLES)
-                await c.query(mailboxKeyDeleteSql("mysql", table), [scope, handle]);
-        });
+        await this.tx((c) => dropMailboxBoxOn(c, "mysql", scope, handle));
     }
     async reap(scope, now, opts) {
         if (opts?.maxAgeMs === undefined || mailboxKeyProblem("scope", scope) !== undefined)
@@ -617,10 +619,7 @@ export class PgMailboxStore {
     async drop(scope, handle) {
         if (keyless(scope, handle))
             return;
-        await this.tx(async (c) => {
-            for (const table of MAILBOX_KEYED_TABLES)
-                await c.query(mailboxKeyDeleteSql("pg", table), [scope, handle]);
-        });
+        await this.tx((c) => dropMailboxBoxOn(c, "pg", scope, handle));
     }
     async reap(scope, now, opts) {
         if (opts?.maxAgeMs === undefined || mailboxKeyProblem("scope", scope) !== undefined)

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

@@ -1,15 +1,14 @@
-import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
-import type { SessionSummary } from "./store-contracts.js";
-import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
-import { type PlacementAcquireOpts } from "./session-placement.js";
+import { WindowedSessionStorage } from "./windowed-session-storage.js";
+import { type PlacementAcquireOpts } from "../plugins/session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
-import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
-import type { SessionWorkspace } from "../session-workspace.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type IndexSpec } from "./ensure-index.js";
-import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "./session-fork.js";
-import { type ExecutionPlacementSeat } from "../execution-placement.js";
+import { type RegisterReceipt, type WithdrawOutcome } from "../session-incarnation.js";
+import type { SessionWriteHooks } from "./session-write-hooks.js";
+import { type IndexSpec } from "../plugins/ensure-index.js";
+import { type SessionDeleteCondition } from "./tidb-session-store.js";
+import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "../plugins/session-fork.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
  * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), inline `KEY`/`UNIQUE KEY`→separate CREATE INDEX (UNIQUE for uq_session_event_entry).
@@ -23,33 +22,31 @@ export declare const SESSION_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for this store's tables (the test calls this; production aggregation is separate). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
 /**
- * PostgreSQL-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
+ * PostgreSQL-backed session storage — the durable L1 event log for one session (the window view and its reads: {@link WindowedSessionStorage}).
  *
  * Behaviourally identical to {@link TiDBSessionStorage}; see that file's class doc for the F2/F3 seams. The only
  * differences are dialectal (placeholders, `IS NOT DISTINCT FROM`, jsonb, rowCount, transaction handle).
  */
-export declare class PgSessionStorage extends BaseSessionStorage {
+export declare class PgSessionStorage extends WindowedSessionStorage {
     private readonly pool;
     private readonly sessionId;
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
     /** @see TiDBSessionStorage.getEpochAnchor — [ref] S3 [ref] pull seam, PG dialect twin: the same reading
-     *  ({@link scanEpochAnchor}, the record as stored), this backend's page query. */
+     *  ({@link scanEpochAnchor}: the floor's parent chain, the record as stored), the same page in this dialect's spelling. */
     getEpochAnchor(): Promise<unknown>;
     /** @see TiDBSessionStorage.wake — F3 bounded `[floor..leaf]` rebuild; null if the session does not exist. */
     static wake(pool: Pool, sessionId: string): Promise<PgSessionStorage | null>;
     /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). @see TiDBSessionStorage.computeFloor */
     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 (23505), which we translate to a conflict too.
      */
-    private persist;
+    protected persist(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
 }
 /**
  * PostgreSQL-backed {@link SessionStore} — the PG twin of {@link TiDBSessionStore}. Maps the
@@ -57,7 +54,7 @@ export declare class PgSessionStorage extends BaseSessionStorage {
  */
 export declare class PgSessionStore implements SessionStore {
     private readonly pool;
-    /** 托管留存声明 = 装配交给它的词(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    /** 托管留存声明 = 装配交给它的词(TiDB 孪生同格)。读法见 `retention-declaration.ts` 的 {@link MANAGED_RETENTION}。 */
     readonly retention: RetentionDeclaration;
     /** [ref] C18(core 5.48.0 [ref]):placement 声明(TiDB 孪生同格,义务逐条见
      *  `src/plugins/session-placement.ts` 顶注)。 */
@@ -70,17 +67,20 @@ export declare class PgSessionStore implements SessionStore {
     readonly durability: "durable";
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
-    /** 执行席(TiDB 孪生同格;实现与语句的唯一属主 = `execution-placement-sql.ts`,本店只交自己的池)。 */
-    readonly executionPlacement: ExecutionPlacementSeat;
-    /** 本店的池包成的 SqlDriver(TiDB 孪生同格):执行席与会话行格写原语的事务都经它借连接。 */
-    private readonly db;
-    constructor(pool: Pool, opts?: {
+    /** 部署的事务内钩(TiDB 孪生同格,`session-write-hooks.ts`)。 */
+    private readonly hooks;
+    constructor(pool: Pool, opts: {
         readonly retention?: RetentionDeclaration;
+        readonly hooks: SessionWriteHooks;
     });
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
     /** Idempotently create a session_meta row with an owner (core `SessionStore.register`). Existing owner is never overwritten. */
     register(sessionId: string, owner: string | null): Promise<void>;
+    /** 出生回执面(TiDB 孪生 {@link TiDBSessionStore.registerWithReceipt} 同义:候选 = 这一次 INSERT 入参里铸的化身)。 */
+    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    /** 条件删除(TiDB 孪生 {@link TiDBSessionStore.deleteSessionIf} 同义)。 */
+    deleteSessionIf(sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
     /** acquire 的建行(唯一一处;placed 会话的属主 = `placement.owner` 原样,core 7.62.0 [ref] 盒义务 7 —— TiDB 孪生同名方法同注)。 */
     private createOnAcquire;
     /** The one session_meta INSERT. Existing owner is never overwritten.
@@ -107,53 +107,6 @@ export declare class PgSessionStore implements SessionStore {
     private deletePlacedSession;
     /** [ref]:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
     private assertNotPlaced;
-    /** @see TiDBSessionStore.listSessions — session identity from session_meta (owner-filtered), task_run LEFT JOIN for preview. */
-    listSessions(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
-    /** @see TiDBSessionStore.listSessionRows — the PG twin. */
-    listSessionRows(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<Array<SessionRowAnswer<SessionSummary>>>;
-    /** @see TiDBSessionStore.sessionSummaryOf — the PG twin (same projection, run-preview subqueries scoped to the id). */
-    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
-    /** @see TiDBSessionStore.listRowOf — the PG twin. */
-    private listRowOf;
-    /** @see TiDBSessionStore.writeSessionRowCells — the PG twin (the same SQL half, `session-row-sql.ts`; only the statement text differs). */
-    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
-    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
-    /** @see TiDBSessionStore.selectListRows — the PG twin. `where` already carries `$n` placeholders numbered over `params`;
-     *  the run scope and the LIMIT take the next numbers (PG binds by number, so text order does not matter). */
-    private selectListRows;
-    /** @see TiDBSessionStore.probeTitle — the PG twin. */
-    probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
-    /** @see TiDBSessionStore.setTitleIfNull — the PG twin (the auto-titler's NULL-only write). */
-    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
-    /** @see TiDBSessionStore.readInstructionSource — the PG twin. */
-    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
-    /** @see TiDBSessionStore.recordInstructionSource — the PG twin (same CAS predicate, same per-query timeout; node-pg's
-     *  `query_timeout` rejects AND pg-pool destroys that client, so a lock-stuck baseline write does not keep a pooled
-     *  connection). */
-    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
-    /** @see TiDBSessionStore.readSessionWorkspace — the PG twin (same projection-as-text, same cell owner). */
-    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
-    /** @see TiDBSessionStore.recordSessionWorkspace — the PG twin (whole-cell overwrite fenced to the occupant; `pgSafeJsonStringify` + `::jsonb`, like every PG JSON write;
-     *  the general query surface — the pool-wide `DB_QUERY_TIMEOUT_MS` server-side `statement_timeout` bounds it, no per-call client timer). */
-    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
     /** @see TiDBSessionStore.fork — core 契约 `fork(sourceId, owner?, opts?)` = {@link forkTo} 的投影(新铸 uuidv7 目标,`forkByFreshId`;三店同一只;`opts.placement` 进委派分区)。 */
     fork(sourceId: string, owner?: string | null, opts?: {
         placement?: ForkPlacement;
@@ -181,16 +134,16 @@ export declare class PgSessionStore implements SessionStore {
     }): Promise<AsyncIterable<SessionTreeEntry> | null>;
     /** @see TiDBSessionStore.importEntries — 2c session-sync IMPORT: core `validateEntriesForImport` gate FIRST (fail-closed),
      *  then persist its verbatim output (re-seq dense from 0, ids/parents/payload/ts unchanged) in ONE txn, **lock-or-create, meta first**
-     *  (读写序律:占行 → 锁行判是不是本次占下的 → 锁定读认领 → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
+     *  (占行 → 锁行判是不是本次占下的 → 部署的事务内钩 `import` → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST
-     *  (fail-closed), then the owner-guarded meta delete (`owner IS NOT DISTINCT FROM $n` = the PG `<=>`, defense-in-depth), then the
-     *  SHARED body (session_meta first, the in-txn claim read, then the old events out and the new ones in), ALL in
-     *  ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry) — unlike importEntries' fresh-only INSERT. */
+    /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST (fail-closed), then the row
+     *  (absent ⇒ created as a fresh occupant; existing ⇒ rewritten in place only when it is the importer's — `owner IS NOT DISTINCT FROM $n`, the PG
+     *  `<=>` — and not a delegation transcript; the occupant keeps its incarnation and deployment cells), then the SHARED body (the hook, then the old
+     *  events out and the new ones in), ALL in ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry). */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /** @see TiDBSessionStore.writeImportedLog — the shared write half of importEntries / replaceEntries (ONE source, no drift):
-     *  session_meta FIRST (create = occupy the row, an existing one ⇒ refused; replace = plain INSERT after the caller's owner-guarded
-     *  delete), the in-txn claim read on THIS connection (读写序律), then the entries re-seq dense from 0 (ids/parents/payload/ts verbatim).
+     *  session_meta FIRST (create = occupy the row, an existing one ⇒ refused; replace = owner-guarded in-place rewrite of the locked row),
+     *  the deployment's transaction hook `import` on THIS connection, then the entries re-seq dense from 0 (ids/parents/payload/ts verbatim).
      *  Runs inside the caller's open txn (`conn` already in BEGIN); the caller owns COMMIT/ROLLBACK + the validate gate. */
     private writeImportedLog;
     /** @see TiDBSessionStore.beginImportStaging — 2c P1d-β PUSH staging: stream batches into the shadow id
@@ -204,10 +157,6 @@ export declare class PgSessionStore implements SessionStore {
      *  under a `%#stg-%` id with NO session_meta whose oldest row is older than the grace window (in-flight stays fresh).
      *  Returns the affected row count. Driven by main.ts's reaper. */
     sweepStagingSessions(): Promise<number>;
-    /** @see TiDBSessionStore.deleteSession — purge session_meta + session_event; idempotent (false if absent).
-     *  Owner-guarded on session_meta.owner (`IS NOT DISTINCT FROM` = the PG `<=>`); the event purge is gated on the
-     *  owner-matched meta delete (session_event has no owner column). A live run claim read inside the txn ⇒ `SessionActiveRunError`. */
-    deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     get size(): number;
     dispose(): void;
 }