@sema-agent/server 7.146.0 → 7.148.0

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

@@ -12,19 +12,41 @@
  */
 import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
-import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
-import type { SessionWorkspace } from "../session-workspace.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-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 { type RegisterReceipt, type WithdrawJudgeVerdict, type WithdrawOutcome } from "../session-incarnation.js";
+import type { SessionTxStatements, SessionWriteHooks } from "./session-write-hooks.js";
+import { type PlacementAcquireOpts } from "../plugins/session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
-import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "./session-fork.js";
-import { type ExecutionPlacementSeat } from "../execution-placement.js";
+import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "../plugins/session-fork.js";
+/**
+ * **条件撤回的店那一半**(两方言一形;TiDB 孪生与 PG 孪生 `pg-session-storage.ts` 同调;撤回的规则在 `plugins/session-birth.ts` 头注)。
+ * 店拿根行、化身、内容、认领;部署交入的条件({@link SessionDeleteCondition})带可撤条目型名单与部署判据(启用标记、客户端写计数、别的 run、本次 run 的部署行),
+ * 判据跑在**同一事务、同一连接**的语句面上。每一读都是锁定读(`FOR UPDATE`):TiDB 悲观事务里普通 SELECT 读的是事务开始时的快照,
+ * 等根锁期间别人提交的写(导入的内容、计数 +1、新 run 行)它看不到 —— 锁定读是当前读;PG 读已提交下每一句新快照,同一形照写。
+ */
+export interface SessionDeleteCondition {
+    /** 候选那一位(这一笔 INSERT 铸下的属主 + 化身)。 */
+    readonly expect: {
+        readonly owner: string | null;
+        readonly incarnation: string;
+    };
+    /** 可撤集合 A 组的条目型(部署交入;名单的唯一属主在部署,店只拿它做锁定读的 `NOT IN`)。 */
+    readonly withdrawableEntryTypes: readonly string[];
+    /** 部署判据(同一语句面;放行时已在同一事务里删掉本次 run 的部署行)。 */
+    readonly judge: (tx: SessionTxStatements) => Promise<WithdrawJudgeVerdict>;
+}
+/** 两孪生的方言词(店只用它挑占位符形)。 */
+type WithdrawDialect = "mysql" | "pg";
+/**
+ * 店的那一半(调用方已开事务、持着这只连接;答 `withdrawn` ⇒ 调用方提交,否则回滚):
+ * 锁根行 → 不在 ⇒ `absent`;属主 / 化身不是候选 ⇒ `incarnation` → 锁定读一条可撤集合之外的会话条目 ⇒ `content` → 部署钩 `delete` 臂(认领在 ⇒ 拒)⇒ `claim`
+ * → 部署判据 → 删会话条目 + 按化身删根行(旁表随外键级联)。
+ */
+export declare function withdrawSessionOn(tx: SessionTxStatements, dialect: WithdrawDialect, hooks: SessionWriteHooks, sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
 export declare class TiDBSessionStore implements SessionStore {
     private readonly pool;
     /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法逐字见
-     *  `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+     *  `retention-declaration.ts` 的 {@link MANAGED_RETENTION}。 */
     readonly retention: RetentionDeclaration;
     /** [ref] C18(core 5.48.0 [ref]):placement **声明**。六条义务的实装点逐条见
      *  {@link SESSION_PLACEMENTS} 顶注与本类的 acquire / listSessions / release / listPlaced /
@@ -39,20 +61,23 @@ export declare class TiDBSessionStore implements SessionStore {
     readonly durability: "durable";
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
-    /**
-     * 执行席 —— 根会话行上这一位住客的那一格的唯一读口与 place / markMirror 两只写口(规则在 `src/execution-placement.ts`;
-     * 实现与语句的唯一属主 = `execution-placement-sql.ts`,两孪生同一只实现,本店只交自己的池)。
-     */
-    readonly executionPlacement: ExecutionPlacementSeat;
-    /** 本店的池包成的 SqlDriver:执行席与会话行格写原语的事务都经它借连接(连接初始化钉住事务读语义,`sql-driver.ts`)。 */
-    private readonly db;
-    constructor(pool: Pool, opts?: {
+    /** 部署的事务内钩(组合座交入;导入 / 删除 / fork 的写事务锁住根行之后、写之前调,`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>;
+    /**
+     * 出生回执面(`plugins/session-birth.ts`):与 {@link register} 同一笔 INSERT;候选化身 = 这一次 INSERT 入参里铸的那一只(不复读)。
+     * 已在的行上 INSERT 是 no-op 臂 ⇒ 行上的化身不是候选 ⇒ 撤回在锁内比对时判「留」—— 出生事实只在那里判,这里不分新旧行。
+     */
+    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    /** 条件删除(`plugins/session-birth.ts` 的撤回;本连接开事务 → 店与部署两半同一语句面 → 撤回才提交,否则回滚)。 */
+    deleteSessionIf(sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
     /**
      * acquire 的建行(唯一一处):普通会话 ⇒ 无主(按 id 首建的既有读法);placed 会话 ⇒ 属主 = `placement.owner` 原样,与元组同一条 INSERT 落库
      * (core 7.62.0 [ref] 盒义务 7:委派树的属主是引擎判的,店只记、不判、不推断;唯一读法 `placedSessionOwnerOf`,值不是主体名也不是 null ⇒ 响亮拒、不留行。PG 孪生同调)。
@@ -109,90 +134,8 @@ export declare class TiDBSessionStore implements SessionStore {
      */
     forget(sessionId: string): void;
     /** 真删除一只 placed 会话的两张表(条件删门在 `placement_kind IS NOT NULL`;事务内 meta 先删=提交点,
-     *  与 {@link deleteSession} 同序)。任何 I/O 失败上浮成 `SessionError("storage")`,绝不吞。 */
+     *  会话删除执行体同序:行先删 = 提交点)。任何 I/O 失败上浮成 `SessionError("storage")`,绝不吞。 */
     private deletePlacedSession;
-    /**
-     * E16 — list the caller's sessions (CC /resume picker), keyset-paginated newest-first by last activity.
-     * Session IDENTITY/enumeration comes from `session_meta` (owner-filtered on the service's OWN owner column);
-     * a LEFT JOIN onto the `task_run` runs ledger supplies run-level PREVIEW (latest run's objective/status,
-     * run count) but never gates which sessions exist — a session with zero runs still lists (preview null/0).
-     * Keyset on `(updated_at, session_id)`; `updated_at` is the session's last-activity marker (touch on every
-     * run/append). The shipped {@link SessionSummary} shape is preserved (additive): `lastActivityAt` =
-     * `session_meta.updated_at`, `firstActivityAt` = `session_meta.created_at`.
-     */
-    listSessions(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
-    /** {@link listSessions} with each row's occupant (owner + incarnation) from the same SELECT — `OwnerAwareSessionStore.listSessionRows`; the incarnation never enters the row. */
-    listSessionRows(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<Array<SessionRowAnswer<SessionSummary>>>;
-    /** ONE session's list row — {@link listSessions}' projection (same SELECT, same mapper) scoped to one id; `undefined` = not a
-     *  row of the list face (no such session / placed). The run-preview subqueries are scoped to the same id (an index read on
-     *  `task_run.session_id`, not the whole-ledger aggregate the list pays). */
-    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
-    /** {@link sessionSummaryOf} 那一读 + 读到它时行上的住客(写原语的应答行要复核住客,`settleSessionRowWrite`)。 */
-    private listRowOf;
-    /**
-     * 会话行格写原语 —— 用户标题 / 置顶的唯一写口(规则与判序:`src/session-row.ts` 头注「写原语」;事务与语句:`session-row-sql.ts`,PG 孪生同一只实现)。
-     * 一只经 `SqlDriver.connect()` 的事务锁住根行、交 core 判官判行期望(属主 + 化身)→ 写者身份(客户端写在镜像上 ⇒ `mirror`)→ 标签 → 写;
-     * 应答行在提交 / 回滚之后另读(列表行同一只投影,含新 `rowTag`)、复核仍是判过的那一位住客。只写列表面上的行(委派分区行 ⇒ `absent`);
-     * `updated_at` 不动(改名不是活动)。重载按入口分:`replay` 的结局只有 `written` / `absent`。
-     */
-    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
-    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
-    /**
-     * The list projection's ONE SELECT + row mapper ({@link listSessions} and {@link sessionSummaryOf} both read through it).
-     * `runSessionId` scopes the two run-preview subqueries to one session (the single-row read); the list leaves them whole.
-     * Placeholder order follows the text: subquery params, then `where` params, then the LIMIT.
-     * `sm.incarnation` is read for the row tag only (`rowTag`, `sessionRowTagKey` — present-iff the row has a token) and the answer row's occupant
-     * check; it never enters the list row itself.
-     */
-    private selectListRows;
-    /** Cheap pre-LLM probe: "none" = session_meta row not yet REGISTERED (createRun fires
-     *  before the Runner's session acquire — the titler retries), "untitled" / "titled" as read. */
-    probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
-    /** The auto-titler's write: lands ONLY when title IS NULL (a concurrent/prior title — the user's included — wins;
-     *  writer order: `src/session-row.ts`). Returns whether this call set it. */
-    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
-    /**
-     * [ref] —— 换源通告的基线读(一行 PK SELECT;列的三态读法见 `tidb-pool.ts` 的列注)。行不在 ⇒ 读作「没记过」
-     * (loader 跑在 acquire 之后,行恒在;不在 = 被带外删了,没有下一 run 可比)。
-     */
-    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
-    /**
-     * [ref] —— CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。
-     * **不**碰 `updated_at`(那是会话活动时刻,留存腿按它判龄;记基线不是一次会话活动)。
-     * 两条基线查询都带每查询超时(`BASELINE_IO_DEADLINE_MS`,mysql2 的 `{sql, timeout}` 形):被行锁卡住的写由查询自己
-     * 在期限内拒。⚠️ mysql2 的超时是客户端侧的 —— 拒之后那条连接仍被挂着的命令占到服务端结束(S-9 同形,如实披露)。
-     */
-    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
-    /**
-     * 会话行的位置与项目那一格(`session_meta.workspace`;域律 `src/session-workspace.ts`,列属主 `session-workspace-cell.ts`)。
-     * 一行 PK 读,按文本投影、恰好解一次;行不在 / 格为 NULL ⇒ `undefined`;格读不出 ⇒ 读作没有记录并计一次(F 类,见列属主头注)。
-     */
-    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
-    /**
-     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座,它在腿的流循环里一笔一笔等写完)。**住客围栏**:只写化身仍是 `incarnation` 的那一行 ——
-     * 行不在、或同 id 已换了住客 ⇒ 0 行、不抛(那一行不是这条腿的)。**不**碰 `updated_at`(那是会话活动时刻,留存腿按它判龄;记下站在哪里不是一次会话活动)。
-     * 走店的一般查询面(与腿循环里的账本追加同一形,不另设每查询的客户端超时):mysql2 的客户端超时只是不再等,服务端照把那条 UPDATE 跑完 ——
-     * 一笔「放弃等待却仍会落地」的写正是这条腿离开之后还能盖掉下一条腿的那一形。卡住的上界归服务端(锁等待超时)与部署的池策略。
-     */
-    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
     /**
      * E17 — fork a session: copy its WHOLE durable history to a NEW uuidv7 session owned by `owner`, mirroring
      * core's `PgSessionRepo.fork`. Entry ids / parent links are per-session and copy VERBATIM; only `seq` is
@@ -210,11 +153,12 @@ export declare class TiDBSessionStore implements SessionStore {
     }): Promise<string | null>;
     /**
      * **fork 续写的店契约**(三店同一只私有体;core `fork` 是它的投影):把源会话的整份历史拷进调用方给的目标 id。
-     *  1. **原子目标创建**:事务首句 `INSERT INTO session_meta (…, fork_key) VALUES (:target, …)`,主键即排他(meta 先,随后拷事件、COMMIT);
-     *  2. **赢家分类**:撞上已在的目标 ⇒ 输方整笔回滚,在新视图里读目标、按属主与 fork 键分类({@link classifyForkTarget});读不到(赢方在分类前回滚或被删)
+     *  1. **原子目标创建**:事务首句 `INSERT INTO session_meta (…) VALUES (:target, …)`,主键即排他(meta 先,随后事务内钩 `fork` —— 部署在同一事务里记下 fork 键
+     *     (部署格,旁表)—— 再拷事件、COMMIT);
+     *  2. **赢家分类**:撞上已在的目标 ⇒ 输方整笔回滚,经钩读目标那一行的属主与 fork 键(一次读)、分类({@link classifyForkTarget});读不到(赢方在分类前回滚或被删)
      *     ⇒ 整笔重跑一次,再撞而仍读不到 ⇒ {@link ForkTargetUnsettledError}(不猜);
-     *  3. 单事务 ⇒ 无中间态;`fork_key` 只由这里写(此后每个写携带:UPDATE 只碰点名列,整段换装经 `carriedRowCells` 带回)。
-     * 源不在 ⇒ `null`(先于目标判:源被删之后的同键重试答「源不在」)。新行 = 新住客(化身新铸),执行格 absent(INSERT 列名显式)。
+     *  3. 单事务 ⇒ 无中间态;fork 键只由这一钩写。
+     * 源不在 ⇒ `null`(先于目标判:源被删之后的同键重试答「源不在」)。新行 = 新住客(化身新铸),部署格全缺省(执行格 absent)。
      */
     forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
     /** {@link forkTo} 的一次尝试:`"unsettled"` = 撞上目标而回滚之后读不到它(交给外层重跑一次)。 */
@@ -266,33 +210,32 @@ export declare class TiDBSessionStore implements SessionStore {
      *       re-implement any of those checks in SQL ([[core-service-boundary]]; the same discipline fork's hand-SQL
      *       was warned about). A violation throws `SessionError("invalid_session")` and NOTHING is written.
      * The write: re-seq dense from 0, entry_id/parent_id/payload/ts verbatim, in ONE txn (COMMIT is the sole commit point), written
-     * **lock-or-create, meta first** (读写序律,`execution-placement-sql.ts` 头注):the `session_meta` row is occupied first (an existing row ⇒
-     * refused before anything else about it is read), locked, the run claim on the root is read on THIS connection (a claim ⇒
-     * `SessionActiveRunError`, nothing written), then the entries. The leaf is the replayed leaf (core's `leafIdAfterEntry`), matching core's import.
+     * **lock-or-create, meta first**:the `session_meta` row is occupied first (an existing row ⇒ refused before anything else about it is read), locked,
+     * then the deployment's transaction hook `import` runs on THIS connection (its run claim on the root ⇒ refused, nothing written; its cells for an
+     * imported row), then the entries. The leaf is the replayed leaf (core's `leafIdAfterEntry`), matching core's import.
      */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /**
-     * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE: purge any existing conversation log for `sessionId` then re-import
-     * `entries` verbatim under `owner`, ALL in ONE txn. Unlike {@link importEntries} (fresh-only: an existing session at the
-     * destination is refused), replace is safe to run OVER an existing session
-     * — the §7 fast-forward path and a §8 retry-to-completion both land on it. The validate gate runs FIRST (fail-closed,
-     * before any write), then the OWNER-GUARDED meta delete (defense-in-depth, mirrors {@link deleteSession}
-     * — a wrong-owner caller can never replace another tenant's session: its delete matches nothing and the re-insert collides on the PK),
-     * then the SAME shared write body importEntries uses (session_meta first, the in-txn claim read, then the events swapped) — ONE source of
-     * the write logic, no copy-paste drift. COMMIT is the sole commit point: a mid-replace crash rolls the whole swap back.
+     * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE: rewrite the conversation log of `sessionId` with `entries` verbatim under `owner`, ALL in ONE txn.
+     * Unlike {@link importEntries} (fresh-only: an existing session at the destination is refused), replace is safe to run OVER an existing
+     * session — the §7 fast-forward path and a §8 retry-to-completion both land on it. The validate gate runs FIRST (fail-closed, before any write),
+     * then the row: an absent id is created (a fresh occupant, like {@link importEntries}); an existing row is rewritten IN PLACE only when it is the
+     * importer's (`owner <=> ?`, defense-in-depth — a wrong-owner caller can never replace another tenant's session: nothing is written) and not a
+     * delegation transcript — the same occupant keeps its incarnation and its deployment cells (the side table row is not touched by the store), its
+     * created time is the replace's (the log is new). Then the SAME shared write body importEntries uses (the hook, then the events swapped) —
+     * ONE source of the write logic. COMMIT is the sole commit point: a mid-replace crash rolls the whole swap back.
      */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /**
      * Shared write half of {@link importEntries} / {@link replaceEntries} (ONE source of the write logic, no drift), in the global lock
-     * order (根 `session_meta` 先于 `task_*` 与 `session_event`):
-     *  ① session_meta FIRST — `create` occupies the row (`ON DUPLICATE KEY UPDATE session_id = session_id`: an existing row is left as it is),
-     *     `replace` is a plain INSERT after the caller's owner-guarded delete (a foreign row collides on the PK — the existing refusal);
-     *     owner = the RE-STAMPED authenticated principal (never the bundle's); 化身与 fork 键按 `carriedRowCells`(或新铸),执行格 = mirror
-     *     —— 导入落下的行是「写者在别处」(列名与值同出 `importedRowCells`);
-     *  ② `create`: lock the row and judge it is the one this call occupied (化身 = 本次铸的)— a row that existed before ⇒ refused before
-     *     anything else about it is read (no claim read on someone else's row);
-     *  ③ 读写序律:the run claim on the root, read on THIS connection after the row lock (`lockRootAndReadClaim`) — a claim ⇒ `SessionActiveRunError`;
-     *  ④ the validated entries re-seq dense from 0 (entry_id/parent_id/type/ts verbatim); `replace` drops the old log first.
+     * order (根 `session_meta` 先于 `task_*`、部署格与 `session_event`):
+     *  ① session_meta FIRST — `create` occupies the row (`ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq`: an existing row is left as it is) and then
+     *     locks it and judges it is the one this call occupied (化身 = 本次铸的;a row that existed before ⇒ refused before anything else about it is
+     *     read — no hook on someone else's row); `replace` rewrites the locked row in place (owner-guarded, not placed — 0 rows = another owner's row,
+     *     refused, nothing written). owner = the RE-STAMPED authenticated principal (never the bundle's);
+     *  ② the deployment's transaction hook `import` on THIS connection after the row lock (`session-write-hooks.ts`):its run claim on the root ⇒
+     *     refused; its cells for an imported row (a writer here ⇒ refused; otherwise the row is a mirror —「写者在别处」);
+     *  ③ the validated entries re-seq dense from 0 (entry_id/parent_id/type/ts verbatim); `replace` drops the old log first.
      * Runs inside the caller's open transaction (`conn`) so the caller owns begin/commit/rollback (COMMIT is the sole commit point).
      * `validated` is the OUTPUT of {@link validateEntriesForImport} (the caller runs the gate before opening the txn).
      */
@@ -323,22 +266,8 @@ export declare class TiDBSessionStore implements SessionStore {
      * stream is never reaped while another abandoned one is. Returns the affected row count. Driven by main.ts's reaper.
      */
     sweepStagingSessions(): Promise<number>;
-    /**
-     * E21 — purge a session's CONVERSATION HISTORY (session_meta + session_event). Idempotent: a missing
-     * session is a no-op (returns false). The service's OWN run-ledger / checkpoint / tool-result rows are
-     * purged separately by the route's `purgeSession` coordinator — this method owns only the session
-     * abstraction's tables (the `SessionRepo.delete` half).
-     *
-     * `owner` is the single-DB-fleet null-safe SQL owner guard on `session_meta.owner` (defense-in-depth — the
-     * route already owner-gates; `<=>` so a legacy null-owner session matches owner=null). session_event carries
-     * no owner column, so its purge is GATED on the owner-matched meta delete: if the meta DELETE matched 0 rows
-     * (wrong owner / already gone) we skip the event delete — so a wrong-owner caller can never strand-delete
-     * another tenant's events. Meta is deleted FIRST (mirrors core BUG-2: once it's gone, wake is `null`
-     * regardless of leftover events; if a crash interleaves, orphan events with NO meta are invisible, never a
-     * half-session), and the event purge only runs after that owner-matched commit point.
-     */
-    deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     get size(): number;
     dispose(): void;
 }
+export {};
 //# sourceMappingURL=tidb-session-store.d.ts.map