@sema-agent/server 7.149.0 → 7.151.0

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

@@ -2,9 +2,9 @@ import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type Ses
 import type { Pool, PoolClient } from "pg";
 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 EntriesStreamOptions, type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type RegisterReceipt, type WithdrawOutcome } from "../session-incarnation.js";
+import { type RegisterReceipt, type SessionFace, 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";
@@ -78,7 +78,7 @@ export declare class PgSessionStore implements SessionStore {
     /** 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>;
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: string): Promise<RegisterReceipt>;
     /** 条件删除(TiDB 孪生 {@link TiDBSessionStore.deleteSessionIf} 同义)。 */
     deleteSessionIf(sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
     /** acquire 的建行(唯一一处;placed 会话的属主 = `placement.owner` 原样,core 7.62.0 [ref] 盒义务 7 —— TiDB 孪生同名方法同注)。 */
@@ -86,6 +86,8 @@ export declare class PgSessionStore implements SessionStore {
     /** The one session_meta INSERT. Existing owner is never overwritten.
      *  [ref]:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
     private insertMeta;
+    /** {@link insertMeta} 那一句,发在给定的连接上(带种类的登记在自己的事务连接上发)。 */
+    private insertMetaOn;
     /** [ref] 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
     /** [ref] 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
@@ -128,10 +130,7 @@ export declare class PgSessionStore implements SessionStore {
      *  held connection across the stream → a slow consumer can't pin one). Start cursor = afterSeq ?? -1 (0-based dense).
      *  Resolves to null (NOT an empty iterable) for a missing session — eager `session_meta` probe (BIGINT seq comes
      *  back as a STRING in node-pg → always Number(...) the cursor advance). */
-    exportEntriesStream(sessionId: string, opts?: {
-        afterSeq?: number;
-        batchSize?: number;
-    }): Promise<AsyncIterable<SessionTreeEntry> | null>;
+    exportEntriesStream(sessionId: string, opts: EntriesStreamOptions): 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**
      *  (占行 → 锁行判是不是本次占下的 → 部署的事务内钩 `import` → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
@@ -160,4 +159,32 @@ export declare class PgSessionStore implements SessionStore {
     get size(): number;
     dispose(): void;
 }
+/**
+ * 2c session-sync P1d-β — the PG twin of {@link TiDBStagingHandle} (behaviourally identical; only the SQL dialect
+ * differs: `$n` placeholders, `$n::jsonb`, `ON CONFLICT (session_id, entry_id) DO NOTHING`, rowCount, FOR UPDATE,
+ * BEGIN/COMMIT handle). Streams entry batches into a shadow session_event partition, then atomically RENAMEs them
+ * onto the real session id in ONE txn; session_meta is locked (or claimed, for a fresh push) first and settled last, COMMIT = the commit point.
+ */
+/** 暂存句柄(会话同步的推送腿逐批写、提交、撤销;由本店的 `stageImport` 交出)。导出只为组合座给它封口(店边界)。 */
+export declare class PgStagingHandle implements StagingHandle {
+    private readonly pool;
+    private readonly hooks;
+    readonly realSessionId: string;
+    readonly stagingId: string;
+    private nextSeq;
+    private readonly seen;
+    constructor(pool: Pool, hooks: SessionWriteHooks, realSessionId: string, stagingId: string);
+    /** @see TiDBStagingHandle.appendBatch — DENSE re-seq (skip already-staged ids), idempotent ON CONFLICT (session_id,
+     *  entry_id) DO NOTHING, one txn/batch. */
+    appendBatch(entries: SessionTreeEntry[]): Promise<void>;
+    /** @see TiDBStagingHandle.commit — the atomic swap: owner CAS first (lock / claim the session_meta row) → in-commit re-classify (FOR UPDATE)
+     *  → purge dst → rename staging→real → settle session_meta. Throws StagedCommitOccupantChangedError when the owner cell is not the judged one,
+     *  SyncConflictError on an unconsented fork/stale flip. */
+    commit(owner: string | null, opts: StagedCommitOptions): Promise<{
+        relation: SyncRelation["relation"];
+        face: SessionFace;
+    }>;
+    /** @see TiDBStagingHandle.abort — DELETE the staging rows. Idempotent. */
+    abort(): Promise<void>;
+}
 //# sourceMappingURL=pg-session-storage.d.ts.map

package/dist/stores-sql/pg-session-storage.js

@@ -8,7 +8,7 @@ import { pgSafeJsonStringify } from "../plugins/pg-safe-json.js";
 import { toIso } from "../plugins/sql-row-helpers.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertCells, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "../plugins/session-placement.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
-import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOccupantChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "../plugins/sql-errors.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { SESSION_META_INCARNATION_COLUMN, SESSION_META_LINEAGE_COLUMNS, forkLineageOfRow, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
@@ -224,14 +224,33 @@ export class PgSessionStore {
     async register(sessionId, owner) {
         await this.registerWithReceipt(sessionId, owner);
     }
-    async registerWithReceipt(sessionId, owner) {
+    async registerWithReceipt(sessionId, owner, kind) {
         if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
                 return {};
             assertFirstOwnerWritable(sessionId, owner);
         }
         const incarnation = mintSessionIncarnation();
-        await this.insertMeta(sessionId, owner, undefined, incarnation);
+        if (kind === undefined) {
+            await this.insertMeta(sessionId, owner, undefined, incarnation);
+            return { minted: { sessionId, owner, incarnation } };
+        }
+        const conn = await this.pool.connect();
+        try {
+            await conn.query("BEGIN");
+            await this.insertMetaOn(conn, sessionId, owner, undefined, incarnation);
+            const res = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
+            if (res.rows[0]?.incarnation === incarnation)
+                await this.hooks.birth.record(statementsOn(conn), { rootSessionId: sessionId, kind });
+            await conn.query("COMMIT");
+        }
+        catch (err) {
+            await conn.query("ROLLBACK").catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
         return { minted: { sessionId, owner, incarnation } };
     }
     async deleteSessionIf(sessionId, cond) {
@@ -254,9 +273,12 @@ export class PgSessionStore {
         await this.insertMeta(sessionId, placement === undefined ? null : placedSessionOwnerOf(sessionId, placement), placement);
     }
     async insertMeta(sessionId, owner, placement, incarnation = mintSessionIncarnation()) {
+        await this.insertMetaOn(this.pool, sessionId, owner, placement, incarnation);
+    }
+    async insertMetaOn(on, sessionId, owner, placement, incarnation) {
         const now = new Date();
         const placed = placementInsertCells(placement, now);
-        await this.pool.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
+        await on.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
             "VALUES ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10,$11) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, incarnation, ...placed.values]);
     }
     async placementOf(sessionId) {
@@ -318,7 +340,7 @@ export class PgSessionStore {
             }
             throw err instanceof SessionError
                 ? err
-                : new SessionError("storage", `placed session ${sessionId} could not be deleted: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
+                : new SessionError("storage", `placed session ${sessionId} could not be deleted`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
@@ -420,11 +442,13 @@ export class PgSessionStore {
         if (metaRes.rows.length === 0)
             return null;
         const pool = this.pool;
-        const batchSize = opts?.batchSize ?? 500;
+        const batchSize = opts.batchSize ?? 500;
         async function* gen() {
-            let cursor = opts?.afterSeq ?? -1;
+            let cursor = opts.afterSeq ?? -1;
             for (;;) {
                 const res = await pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq > $2 ORDER BY seq ASC LIMIT $3`, [sessionId, cursor, batchSize]);
+                if (res.rows.length > 0)
+                    await opts.recheck();
                 for (const r of res.rows)
                     yield decodeSessionEventPayload(r.payload, sessionId, r.seq);
                 if (res.rows.length < batchSize)
@@ -542,7 +566,7 @@ export class PgSessionStore {
         this.pending.clear();
     }
 }
-class PgStagingHandle {
+export class PgStagingHandle {
     pool;
     hooks;
     realSessionId;
@@ -583,11 +607,11 @@ class PgStagingHandle {
             await conn.query("BEGIN");
             const now = new Date();
             const minted = mintSessionIncarnation();
-            if (opts.expectedOwner !== undefined) {
-                const cas = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2", [this.realSessionId, opts.expectedOwner]);
+            if (opts.expectedOccupant !== undefined) {
+                const cas = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND incarnation = $3", [this.realSessionId, opts.expectedOccupant.owner, opts.expectedOccupant.incarnation]);
                 if (cas.rowCount !== 1) {
                     await conn.query("ROLLBACK");
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             else {
@@ -595,7 +619,7 @@ class PgStagingHandle {
                 const claimed = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [this.realSessionId]);
                 if (String(claimed.rows[0]?.incarnation) !== minted) {
                     await conn.query("ROLLBACK");
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: this.realSessionId }));
@@ -607,7 +631,7 @@ class PgStagingHandle {
                 throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${dstMeta.rows[0].placement_kind} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
             }
             const srcIds = staged.rows.map((r) => String(r.entry_id));
-            const dstIds = opts.expectedOwner !== undefined ? dst.rows.map((r) => String(r.entry_id)) : null;
+            const dstIds = opts.expectedOccupant !== undefined ? dst.rows.map((r) => String(r.entry_id)) : null;
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
             if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 await conn.query("ROLLBACK");

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

@@ -1,7 +1,7 @@
 /**
  * 托管留存(managed retention)的**执行器** —— 引擎座表那一半(阶段三逐字搬进 `@sema-agent/core-stores-sql` 的那一半)。
  * SINGLE-FILE DUAL-DIALECT([ref] A12 定型半场;先例 = `checkpoint-store-sql.ts`)。[ref] 车1,设计稿
- * `docs/DESIGN-270-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的 `core/retention.d.ts`
+ * `docs/[ref]-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的 `core/retention.d.ts`
  * (`ManagedRetentionCapability` / `RetentionReceipt`);事务内钩表的形 = core-stores-sql 的 `SqlTransactionHooks`(本文件的同名型是它的形,见下)。
  *
  * ── 一个事务、两个属主:执行器 + 部署钩 ─────────────────────────────────────────────────────────────
@@ -301,15 +301,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * background-agent 活锚 / checkpoint 的 scope+status+deadline 复合索引)是独立一车,已进交接清单。
      */
     private countPinnedExpiryCandidates;
-    /**
-     * 会话树的**四条活引用腿**的 SQL 谓词(`sm` = session_meta 的别名)。写成一处的理由与 {@link horizonArms}
-     * 相同,而且更重:它同时是「可删候选」的否定谓词与「被保护计数」的肯定谓词,两份手抄必然在某次改动后分家,
-     * 而分家的方向是**多删**(候选放宽、计数收紧,两边都不会有人红)。
-     *
-     * 腿的词表:活跑 claim / 挂起 park / 活着的后台子代(running|parked,三根会话锚)/ 在跑的 workflow
-     * (`originatingSessionId` 住在 run blob 里 ⇒ JSON 提取是真方言分叉)。fork 子代**结构上没有边**,
-     * 理由见 {@link SqlRetentionStore.deleteExpiredSessions} 的头注。
-     */
+    /** 会话树的活引用谓词(`sm` = session_meta 的别名):唯一写法在 `plugins/retention-sql.ts` 的 `sessionLiveReferenceSql`(候选的否定与被保护计数的肯定同读;会话老化的候选面与锁内重判同读)。 */
     private liveReferenceExists;
     /**
      * 本域过视界、**当下被活引用护住**的会话数 = receipt 的 `skipped`。

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

@@ -1,7 +1,7 @@
 import { peerSessionBoxHandle } from "@sema-agent/core";
 import { incarnationFromCell } from "../session-incarnation.js";
 import { MANAGED_RETENTION } from "../plugins/retention-declaration.js";
-import { retentionDomainWhere, retentionIdSet } from "../plugins/retention-sql.js";
+import { retentionDomainWhere, retentionIdSet, sessionLiveReferenceSql } from "../plugins/retention-sql.js";
 import { dropMailboxBoxOn } from "./mailbox-store-sql.js";
 import { SEALED_EVENT, eraseSessionPolicyRowsOn } from "./session-policy-store-sql.js";
 export const RETENTION_TOMBSTONE_TABLE = "retention_tombstone";
@@ -217,15 +217,7 @@ export class SqlRetentionStore {
         return Number(rows[0]?.n ?? 0);
     }
     liveReferenceExists() {
-        const workflow = this.db.dialect === "mysql"
-            ? `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND JSON_UNQUOTE(JSON_EXTRACT(wr.run, '$.originatingSessionId')) = sm.session_id)`
-            : `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND wr.run::json->>'originatingSessionId' = sm.session_id)`;
-        return (`(sm.placement_kind IS NOT NULL` +
-            ` OR EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = sm.session_id)` +
-            ` OR EXISTS (SELECT 1 FROM checkpoint c2 WHERE c2.session_id = sm.session_id AND c2.status = 'pending')` +
-            ` OR EXISTS (SELECT 1 FROM background_agent ba WHERE ba.status IN ('running','parked')` +
-            `   AND (ba.session_id = sm.session_id OR ba.parent_session_id = sm.session_id OR ba.root_session_id = sm.session_id))` +
-            ` OR ${workflow})`);
+        return sessionLiveReferenceSql(this.db.dialect);
     }
     async countProtectedSessions(exec, input) {
         const w = this.domainWhere("sm.owner", input.domain, 1);

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

@@ -59,10 +59,16 @@ export type SessionPolicyStoreLogger = {
     warn(msg: string, fields?: Record<string, unknown>): void;
 };
 /**
- * 一次客户端写的计数(部署的格:会话规则是客户端可见的会话态,提交出口撤回一只刚铸的会话之前读这只计数)。组合座交入;店只在锁住根行、根行在、
- * 所有拒判之后、规则落行之前,同一事务、同一连接调它一次 —— 计数住部署的旁表,店目录不认识那张表。
+ * 会话根行的部署格(组合座交入;店目录不认识 `session_meta` 的列,也不认识客户端写计数住的旁表):
+ *  · `lockRoot` —— 同一连接上锁会话根行(全局锁序首句:根 `session_meta` → 别的表),答行在不在。语句是部署的「锁根行读住客」那一句
+ *    (组合座交 `plugins/session-row-sql.ts` 的 `SQL_SESSION_ROOT_SEAT`,与落定段、行格写原语、执行放置同一句),店不自写第二份;
+ *  · `countClientWrite` —— 一次客户端写的计数(会话规则是客户端可见的会话态,提交出口撤回一只刚铸的会话之前读这只计数)。店只在锁住根行、根行在、
+ *    所有拒判之后、规则落行之前,同一事务、同一连接调它一次。
  */
-export type SessionClientWriteCounter = (conn: SqlTxConn, dialect: SqlDriver["dialect"], sessionId: string) => Promise<void>;
+export interface SessionRootSeat {
+    lockRoot(conn: SqlTxConn, dialect: SqlDriver["dialect"], sessionId: string): Promise<boolean>;
+    countClientWrite(conn: SqlTxConn, dialect: SqlDriver["dialect"], sessionId: string): Promise<void>;
+}
 /**
  * 按会话抹除规则行的**唯一语句源**(店的 `deleteBySession` 在自己的事务里调;会话删除执行体 `retention-store-sql.ts` 在会话树事务里对一批会话调 ——
  * 同一组语句,`session_policy_rev_mark` 的高水位律只写这一处,core 契约 `session_policy.rev_survives_delete`)。调用方持事务。
@@ -73,9 +79,9 @@ export declare function eraseSessionPolicyRowsOn(conn: Pick<SqlTxConn, "query">,
 /** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     private readonly db;
-    private readonly countClientWrite;
+    private readonly root;
     private readonly logger;
-    constructor(db: SqlDriver, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
+    constructor(db: SqlDriver, root: SessionRootSeat, logger: SessionPolicyStoreLogger);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** 判据属主 = `sql-errors.ts`([ref] P1-①;本站点旧形已是并集形,收编后语义不变)。 */
@@ -92,6 +98,19 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     listBySession(sessionId: string): Promise<SessionRulesRecord[]>;
     /** Operator/owner write: CAS + tighten-only (unless operator) + rev bump, atomic in one txn; first-write race retried. */
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
+    /**
+     * 一次规则写的**语句源**(read-check-write 全在调用方的事务里;调用方已锁根行 —— {@link putRules} 自己锁,落定段在段首锁并判过住客):锁读 prior 与记号 →
+     * CAS → 引擎写口判官 → 号 → 计客户端写(`how.count`)→ 写。`how.skip(prior)` 为真 ⇒ 不写、不计,答 `{ skipped: true }`(落定重放的等内容跳过)。
+     * 首写撞主键(并发首写赢了)照旧抛出,由事务主人的重来臂接住({@link retrying} / 落定段的 `alsoRetry` 读同一只 {@link isDupKey})。
+     */
+    putRulesOn(conn: SqlTxConn, sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts: PutRulesOptions | undefined, how: {
+        readonly count: boolean;
+        readonly skip?: (prior: StoredSessionRules | null) => boolean;
+    }): Promise<StoredSessionRules | {
+        readonly skipped: true;
+    }>;
+    /** 判据属主 = `sql-errors.ts`:并发首写撞主键(落定段的重来臂读它)。 */
+    isDupKeyError(e: unknown): boolean;
     /**
      * The store's ONE retry arm: re-run the whole read-check-write transaction while the failure is an engine
      * ARBITRATION artifact rather than an answer. Two such artifacts, and only two:
@@ -164,6 +183,10 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
      *  残余(如实):记号里**已有**的世代若被列外改到 BIGINT 上界,冲突臂的 `记号.gen + 1` 在库里溢出 ⇒ 这次抹除响亮失败
      *  (驱动错误;那只记号本来就读不回,`putRules` 同样拒)—— 抹除不读记号,这一形不在本判词射程内。 */
     deleteBySession(sessionId: string): Promise<void>;
+    /** 抹除的语句源(调用方的事务里;落定段的擦除腿与 {@link deleteBySession} 同一只):交回被封的键 —— 提交**之后**经 {@link discloseErased} 报。 */
+    eraseOn(conn: SqlTxConn, sessionId: string): Promise<readonly SealedEraseKey[]>;
+    /** 抹除提交之后的响亮面(封键 ⇒ 一条 warn;无封键 ⇒ 什么都不做)。 */
+    discloseErased(sessionId: string, sealed: readonly SealedEraseKey[]): void;
     /**
      * [ref] 封键的响亮面:一次抹除至多一条 warn。走到这里删除已经提交,一次日志故障不许把它报成失败(E21 会因此 500、
      * overwrite-dst 会因此中止;codex 7.105.0 修复验证轮 [medium] 同形)⇒ 日志座抛不往外抛;**也不吞披露**:同一行落日志出口接缝的
@@ -183,10 +206,10 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool: MySqlPool, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
+    constructor(pool: MySqlPool, root: SessionRootSeat, logger: SessionPolicyStoreLogger);
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool: PgPool, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
+    constructor(pool: PgPool, root: SessionRootSeat, logger: SessionPolicyStoreLogger);
 }
 //# sourceMappingURL=session-policy-store-sql.d.ts.map

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

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

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

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

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

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