@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/pg-session-storage.js

@@ -1,47 +1,17 @@
-/**
- * PostgreSQL-backed {@link BaseSessionStorage} — the PG twin of {@link TiDBSessionStorage}
- * (src/plugins/tidb-session-storage.ts; clay 2026-06-21, the second session backend).
- *
- * A behavioural TWIN: identical class/method surface + identical semantics (the F2 optimistic-lock CAS on
- * `leaf_id`/`leaf_seq`, the F3 bounded `[floor..leaf]` wake, the sub-floor durable getEntry fallback), only the
- * SQL dialect differs. Kept in lock-step with the TiDB store by ONE shared real-DB integration suite
- * (test/pg-session-storage-integration.test.ts) that drives the SAME scenarios against BOTH engines. Dialect deltas:
- *   - placeholders `$1..$n` (not `?`)                      - affected rows = `result.rowCount` (not affectedRows)
- *   - `leaf_id IS NOT DISTINCT FROM $n` (not `<=>`)        - dup-key SQLSTATE `23505` (not ER_DUP_ENTRY)
- *   - `payload` is `jsonb`, bound `$n::jsonb`; node-pg PARSES jsonb → object on read (parseJson passes objects through)
- *   - BIGINT (`seq`/`leaf_seq`) comes back as a STRING → always `Number(...)`
- *   - transaction via `pool.connect()` + BEGIN/COMMIT/ROLLBACK/release (not getConnection/beginTransaction)
- *
- * Unlike the run/checkpoint PG stores, this store carries its OWN schema (PG_SESSION_SCHEMA + ensureSchema): the
- * session_meta/session_event tables are DISJOINT from the centrally-owned run-store/checkpoint tables, so a
- * self-contained CREATE IF NOT EXISTS cannot shadow another store's table. (Central aggregation into pg-pool is
- * done separately afterward.)
- */
 import { emitLeafAdvance } from "../session-leaf-bus.js";
-// 🔴 core 1.403 迁移(2026-07-25):runtime 构造用法,`Session` → `StoredSession`(见 audit.ts 同款注释)。
 import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, normalizePromptEpoch, } from "@sema-agent/core";
 import { escapeLike } from "./sql-escape.js";
 import { pgSafeJsonStringify } from "./pg-safe-json.js";
 import { toIso } from "./sql-row-helpers.js";
 import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
-import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, // 两孪生店同源(理由见 kernel 处顶注)
- } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
-/** 判据属主 = `sql-errors.ts`(A-032 P1-①)。 */
 const isDupKey = isPgUniqueViolation;
-/** node-pg parses jsonb → object already; only strings need JSON.parse, everything else passes through. */
 function parseEntry(p) {
     return (typeof p === "string" ? JSON.parse(p) : p);
 }
-/**
- * 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).
- *
- * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
- * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
- */
 export const PG_SESSION_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS session_meta (
      session_id  VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -67,7 +37,6 @@ export const PG_SESSION_SCHEMA = [
      PRIMARY KEY (session_id)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_session_meta_owner ON session_meta (owner)`,
-    // listPlaced 的检索腿(TiDB 孪生的 KEY idx_session_meta_placement 同形)。
     `CREATE INDEX IF NOT EXISTS idx_session_meta_placement ON session_meta (placement_kind, placement_scope, placed_at)`,
     `CREATE TABLE IF NOT EXISTS session_event (
      session_id  VARCHAR(64) COLLATE "C" NOT NULL,
@@ -81,17 +50,10 @@ export const PG_SESSION_SCHEMA = [
    )`,
     `CREATE UNIQUE INDEX IF NOT EXISTS uq_session_event_entry ON session_event (session_id, entry_id)`,
 ];
-/** Idempotent schema apply for this store's tables (the test calls this; production aggregation is separate). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_SESSION_SCHEMA)
         await pool.query(stmt);
 }
-/**
- * PostgreSQL-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
- *
- * 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 class PgSessionStorage extends BaseSessionStorage {
     pool;
     sessionId;
@@ -102,17 +64,14 @@ export class PgSessionStorage extends BaseSessionStorage {
         this.sessionId = sessionId;
         this.floorSeq = floorSeq;
     }
-    /** @see TiDBSessionStorage.getEpochAnchor — [976] S3 RB-14 pull seam, PG dialect twin
-     *  (keyset-paged to exhaustion: a bounded scan over restatement-less pre-epoch compactions would
-     *  misreport an epoch-bearing session as pre-epoch — codex HIGH). */
     async getEpochAnchor() {
         if (this.floorSeq <= 0)
-            return undefined; // full load — the walk already reaches the root pin
+            return undefined;
         let cursor = this.floorSeq;
         for (;;) {
             const res = await this.pool.query("SELECT seq, payload FROM session_event WHERE session_id = $1 AND seq < $2 AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100", [this.sessionId, cursor]);
             if (res.rows.length === 0)
-                return undefined; // exhausted — a genuine pre-epoch session
+                return undefined;
             for (const r of res.rows) {
                 const e = parseEntry(r.payload);
                 const d = e.type === "prompt_epoch" ? normalizePromptEpoch(e) : normalizePromptEpoch(e.details?.promptEpoch);
@@ -122,23 +81,18 @@ export class PgSessionStorage extends BaseSessionStorage {
             cursor = Number(res.rows[res.rows.length - 1].seq);
         }
     }
-    /** @see TiDBSessionStorage.wake — F3 bounded `[floor..leaf]` rebuild; null if the session does not exist. */
     static async wake(pool, sessionId) {
-        const metaRes = await pool.query(
-        // #292 C18(TiDB 孪生同形):placement 六列捎带在既有 meta SELECT 上,acquire 热路径零额外往返。
-        `SELECT created_at, leaf_id, leaf_seq, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
+        const metaRes = await pool.query(`SELECT created_at, leaf_id, leaf_seq, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
         const meta = metaRes.rows[0];
         if (!meta)
             return null;
         const { floorEntryId, floorSeq } = await PgSessionStorage.computeFloor(pool, sessionId);
         const eventRes = await pool.query("SELECT payload FROM session_event WHERE session_id = $1 AND seq >= $2 ORDER BY seq ASC", [sessionId, floorSeq]);
         const entries = eventRes.rows.map((r) => parseEntry(r.payload));
-        // #292 C18:持久化元组骑 core 5.48 的 `SessionMetadata.placement`(TiDB 孪生逐字同义)。
         const placement = placementFromRow(meta);
         const metadata = { id: sessionId, createdAt: toIso(meta.created_at), ...(placement !== undefined ? { placement } : {}) };
         return new PgSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, floorEntryId, floorSeq);
     }
-    /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). @see TiDBSessionStorage.computeFloor */
     static async computeFloor(pool, sessionId) {
         const compRes = await pool.query("SELECT payload FROM session_event WHERE session_id = $1 AND type = 'compaction' ORDER BY seq DESC LIMIT 1", [sessionId]);
         if (!compRes.rows[0])
@@ -148,12 +102,10 @@ export class PgSessionStorage extends BaseSessionStorage {
         if (!fk)
             return { floorEntryId: null, floorSeq: 0 };
         const seqRes = await pool.query("SELECT seq FROM session_event WHERE session_id = $1 AND entry_id = $2", [sessionId, fk]);
-        // firstKeptEntryId missing from the log (shouldn't happen) → degrade to full load.
         if (!seqRes.rows[0])
             return { floorEntryId: null, floorSeq: 0 };
         return { floorEntryId: fk, floorSeq: Number(seqRes.rows[0].seq) };
     }
-    /** Sub-floor lookups (e.g. a label target) aren't in the loaded tail — fall back to the durable log. */
     async getEntry(id) {
         const inMem = await super.getEntry(id);
         if (inMem)
@@ -169,16 +121,10 @@ export class PgSessionStorage extends BaseSessionStorage {
         this.recordEntry(entry);
     }
     async setLeafId(leafId, opts) {
-        // A leaf move is itself a persisted `leaf` entry whose parent is the current leaf.
         const leafEntry = this.createLeafEntry(leafId);
         await this.persist(leafEntry, opts);
         this.recordEntry(leafEntry);
     }
-    /**
-     * 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.
-     */
     async persist(entry, opts) {
         const newLeaf = leafIdAfterEntry(entry);
         const conditional = opts !== undefined && opts.expectedLeafId !== undefined;
@@ -195,17 +141,16 @@ export class PgSessionStorage extends BaseSessionStorage {
             }
             const seqRes = await conn.query("SELECT leaf_seq, owner FROM session_meta WHERE session_id = $1", [this.sessionId]);
             const seq = Number(seqRes.rows[0].leaf_seq);
-            const commitOwner = seqRes.rows[0].owner ?? null; // codex-2:S2 发射 owner=本事务当前行(tidb twin 同注)
+            const commitOwner = seqRes.rows[0].owner ?? null;
             await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [this.sessionId, seq, entry.id, entry.parentId ?? null, entry.type, pgSafeJsonStringify(entry), new Date(entry.timestamp)]);
             await conn.query("COMMIT");
-            emitLeafAdvance(this.sessionId, newLeaf, commitOwner, seq); // S2 fast path — post-commit only, fire-and-forget (session-leaf-bus 契约;tidb twin 同点)
+            emitLeafAdvance(this.sessionId, newLeaf, commitOwner, seq);
         }
         catch (err) {
             try {
                 await conn.query("ROLLBACK");
             }
             catch {
-                /* ignore rollback error */
             }
             if (err instanceof SessionError)
                 throw err;
@@ -219,19 +164,10 @@ export class PgSessionStorage extends BaseSessionStorage {
         }
     }
 }
-// ────────────────────────────────── PG twin of TiDBSessionStore ──────────────────────────────────
-/**
- * PostgreSQL-backed {@link SessionStore} — the PG twin of {@link TiDBSessionStore}. Maps the
- * `SessionStore` surface (acquire / register / ownerOf / touch / release) onto {@link PgSessionStorage}.
- */
 export class PgSessionStore {
     pool;
-    /** #270 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
     retention = MANAGED_RETENTION;
-    /** #292 C18(core 5.48.0 design/323):placement 声明(TiDB 孪生同格,义务逐条见
-     *  `src/plugins/session-placement.ts` 顶注)。 */
     placements = SQL_SESSION_PLACEMENTS;
-    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     pending = new Map();
     constructor(pool) {
         this.pool = pool;
@@ -239,15 +175,11 @@ export class PgSessionStore {
     async acquire(sessionId, opts) {
         if (!sessionId) {
             const id = uuidv7();
-            await this.register(id, null, opts?.placement); // #292:元组与行同一条 INSERT(TiDB 孪生同义)
+            await this.register(id, null, opts?.placement);
             return this.load(id, false, opts);
         }
-        // design/114 Phase3 (F1): a `requireExisting` acquire NEVER creates and can REJECT (not_found) — it MUST bypass
-        // the shared create-dedup `pending`, else a concurrent create-capable waiter awaiting that same promise would
-        // inherit the not_found rejection instead of creating-on-miss. (Twin of TiDBSessionStore.acquire.)
         if (opts?.requireExisting)
             return this.load(sessionId, true, opts);
-        // #292:准入按调用方逐一判(共享 promise 不许让 claim 形继承可信创建方的准入;TiDB 孪生同义)。
         const inflight = this.pending.get(sessionId);
         if (inflight) {
             const acquired = await inflight;
@@ -261,39 +193,29 @@ export class PgSessionStore {
     async load(sessionId, requireExisting = false, opts) {
         let storage = await PgSessionStorage.wake(this.pool, sessionId);
         if (storage) {
-            assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts); // #292 claim 关门
+            assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
             return { session: new StoredSession(storage), sessionId };
         }
-        // design/114 Phase3: `requireExisting` ⇒ FAIL LOUD on a genuinely missing session (no session_meta row),
-        // never the silent create-on-miss. core's prepare-task maps this `not_found` to `resume.session_not_found`.
         if (requireExisting)
             throw new SessionError("not_found", `session ${sessionId} not found`);
         await this.register(sessionId, null, opts?.placement);
         storage = await PgSessionStorage.wake(this.pool, sessionId);
-        // 刚 register 完却唤不醒 = 并发 purge 抢在两步之间(TiDB 孪生同款注:旧形的 `storage!` 断言会炸成
-        // 一条无信息的 TypeError)。
         if (!storage) {
             throw new SessionError("storage", `session ${sessionId} vanished between register and wake (a concurrent purge won the race) — retry`);
         }
-        // #292 镜像方向(pre-claim squat):回读缺失/异组 ⇒ 响亮拒(TiDB 孪生同义)。
         assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
         return { session: new StoredSession(storage), sessionId };
     }
-    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
-     *  #292:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
     async register(sessionId, owner, placement) {
         const now = new Date();
         await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, " +
             "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +
             "VALUES ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, ...placementInsertValues(placement, now)]);
     }
-    /** #292 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
     async placementOf(sessionId) {
         const res = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
         return placementFromRow(res.rows[0]);
     }
-    /** #292 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
-     *  见 {@link TiDBSessionStore.listPlaced})。 */
     async listPlaced(kind, opts) {
         const params = [kind];
         const ph = (v) => {
@@ -309,7 +231,6 @@ export class PgSessionStore {
         const res = await this.pool.query(sql, params);
         return res.rows.map((r) => placedRowFromRow(String(r.session_id), r, r.updated_at instanceof Date ? r.updated_at.getTime() : undefined));
     }
-    /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     async ownerOf(sessionId) {
         const res = await this.pool.query("SELECT owner FROM session_meta WHERE session_id = $1", [sessionId]);
         if (res.rows.length === 0)
@@ -322,34 +243,26 @@ export class PgSessionStore {
             sessionId,
         ]);
     }
-    /** E18 — the session's current leaf SessionTreeEntry.id (session_meta.leaf_id). @see TiDBSessionStore.getLeafId
-     *  (single SELECT, no acquire/lock, cache-bypassing — safe to read mid-run for the resume-at turn-capture). */
     async getLeafId(sessionId) {
         const r = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = $1", [sessionId]);
         return r.rows[0] ? (r.rows[0].leaf_id ?? null) : null;
     }
-    /** [1196] 六轮复审:owner+leafId 单行原子快照(@see TiDBSessionStore.getHead——混世代组合防)。 */
     async getHead(sessionId) {
         const r = await this.pool.query("SELECT owner, leaf_id FROM session_meta WHERE session_id = $1", [sessionId]);
         if (r.rows.length === 0)
             return undefined;
         return { owner: r.rows[0].owner ?? null, leafId: r.rows[0].leaf_id ?? null };
     }
-    /** Durable history is retained; just drop any in-flight cache entry.
-     *  🔴 #292 义务 4:**placed 会话例外 —— release 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
-     *  {@link TiDBSessionStore.release},本腿是它的 PG 孪生)。 */
     async release(sessionId) {
         this.pending.delete(sessionId);
         const placed = await this.placementOf(sessionId);
         if (placed === undefined)
-            return; // 普通会话:语义逐字节不变(义务 3)
+            return;
         await this.deletePlacedSession(sessionId);
     }
-    /** @see TiDBSessionStore.forget — 丢引用不动 durable 史(preflight 纪律的落点;PG 孪生)。 */
     forget(sessionId) {
         this.pending.delete(sessionId);
     }
-    /** @see TiDBSessionStore.deletePlacedSession — PG 孪生(条件删门 + meta 先删 + 失败上浮同义)。 */
     async deletePlacedSession(sessionId) {
         const conn = await this.pool.connect();
         try {
@@ -364,7 +277,6 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
-                /* ignore */
             }
             throw err instanceof SessionError
                 ? err
@@ -374,29 +286,21 @@ export class PgSessionStore {
             conn.release();
         }
     }
-    /** #292:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
     async assertNotPlaced(sessionId, what) {
         const placed = await this.placementOf(sessionId);
         if (placed !== undefined) {
             throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placed.kind} placement partition — a session-sync ${what} cannot overwrite a delegation transcript`);
         }
     }
-    // ───────────────────────── SessionRepo seam (§0.5) — PG twin of TiDBSessionStore ─────────────────────────
-    // Behaviourally identical to {@link TiDBSessionStore.listSessions/fork/deleteSession}; only the SQL dialect
-    // differs ($n placeholders, jsonb, rowCount, BEGIN/COMMIT handle). Kept in lock-step by the shared real-DB suite.
-    /** @see TiDBSessionStore.listSessions — session identity from session_meta (owner-filtered), task_run LEFT JOIN for preview. */
     async listSessions(opts) {
         const params = [];
         const ph = (v) => {
             params.push(v);
             return `$${params.length}`;
         };
-        // 🔴 #292 义务 2:placed 会话不上宿主枚举面(TiDB 孪生逐字同义,理由见那里)。
         const where = ["sm.placement_kind IS NULL"];
-        // [4198] 窄互认第二臂的第三条件(TiDB 孪生逐字同义):`includeUnowned` ⇒「本人的 ∪ 无主的」。
         if (opts.owner)
             where.push(opts.includeUnowned ? `(sm.owner = ${ph(opts.owner)} OR sm.owner IS NULL)` : `sm.owner = ${ph(opts.owner)}`);
-        // `?q=` — the PG twin of the TiDB EXISTS predicate (LOWER-LIKE + ESCAPE, dialect-mirrored).
         if (opts.q)
             where.push(`EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(${ph(`%${escapeLike(opts.q)}%`)}) ESCAPE '\\')`);
         if (opts.cursor) {
@@ -409,7 +313,7 @@ export class PgSessionStore {
             "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id " +
             "FROM session_meta sm " +
             "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run GROUP BY session_id) r ON r.session_id = sm.session_id " +
-            "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id FROM task_run " + // K-5c: latest run's task_id
+            "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id FROM task_run " +
             "  ORDER BY session_id, created_at DESC, task_id DESC) latest ON latest.session_id = sm.session_id " +
             (where.length ? "WHERE " + where.join(" AND ") + " " : "") +
             `ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ${ph(opts.limit)}`;
@@ -422,11 +326,10 @@ export class PgSessionStore {
             runCount: Number(r.run_count),
             objectivePreview: r.objective_preview ?? null,
             lastStatus: r.status == null ? "" : String(r.status),
-            lastRunId: r.last_run_id ?? null, // K-5c: latest run id = the live-tail re-attach anchor (null if no runs)
+            lastRunId: r.last_run_id ?? null,
             title: r.title ?? null,
         }));
     }
-    /** @see TiDBSessionStore.probeTitle — the PG twin. */
     async probeTitle(sessionId) {
         const res = await this.pool.query("SELECT title FROM session_meta WHERE session_id = $1", [sessionId]);
         const row = res.rows[0];
@@ -434,19 +337,15 @@ export class PgSessionStore {
             return "none";
         return row.title == null ? "untitled" : "titled";
     }
-    /** @see TiDBSessionStore.setTitleIfNull — the PG twin (write-once auto-title). */
     async setTitleIfNull(sessionId, title) {
         const res = await this.pool.query("UPDATE session_meta SET title = $1 WHERE session_id = $2 AND title IS NULL", [title, sessionId]);
         return (res.rowCount ?? 0) > 0;
     }
-    /** @see TiDBSessionStore.fork — copy the WHOLE durable history (full session_event log, compaction floor bypassed,
-     *  NOT wake's bounded tail) to a NEW uuidv7 session, re-seq dense from 0, ids/parents verbatim, owner=caller. */
     async fork(sourceId, owner) {
         const metaRes = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = $1", [sourceId]);
         if (!metaRes.rows[0])
             return null;
         const leafId = metaRes.rows[0].leaf_id ?? null;
-        // FULL durable history (compaction floor bypassed) — every entry, oldest first. node-pg parses jsonb → object.
         const eventRes = await this.pool.query("SELECT entry_id, parent_id, type, payload, ts FROM session_event WHERE session_id = $1 ORDER BY seq ASC", [sourceId]);
         const rows = eventRes.rows;
         const newId = uuidv7();
@@ -456,8 +355,6 @@ export class PgSessionStore {
             await conn.query("BEGIN");
             for (let seq = 0; seq < rows.length; seq++) {
                 const r = rows[seq];
-                // Copy the payload blob VERBATIM; re-stringify only an object so $6::jsonb binds a JSON string (node-pg
-                // returns jsonb already parsed, so a string here means it was stored stringly — rare; pass either through).
                 const payload = typeof r.payload === "string" ? r.payload : pgSafeJsonStringify(r.payload);
                 await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES ($1,$2,$3,$4,$5,$6::jsonb,$7)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
             }
@@ -470,7 +367,6 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
-                /* ignore */
             }
             throw err instanceof SessionError ? err : new SessionError("storage", `fork of session ${sourceId} failed`, err instanceof Error ? err : undefined);
         }
@@ -478,60 +374,44 @@ export class PgSessionStore {
             conn.release();
         }
     }
-    /** @see TiDBSessionStore.exportEntries — 2c session-sync EXPORT: the FULL durable session_event log (compaction floor
-     *  bypassed, NOT wake's tail) as `SessionTreeEntry[]`, oldest-first, verbatim. null if the source is unknown. */
     async exportEntries(sessionId) {
         const metaRes = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = $1", [sessionId]);
         if (metaRes.rows.length === 0)
             return null;
         const eventRes = await this.pool.query("SELECT payload FROM session_event WHERE session_id = $1 ORDER BY seq ASC", [sessionId]);
-        // node-pg parses jsonb → object already (parseEntry passes objects through; a string would be rare/legacy).
         return eventRes.rows.map((r) => parseEntry(r.payload));
     }
-    /** @see TiDBSessionStore.listEntryIds — 2c P1d-α (PULL streaming): the IDS-ONLY projection of the full durable log,
-     *  oldest-first (`SELECT entry_id … ORDER BY seq ASC`), no payloads. null if the source is unknown. */
     async listEntryIds(sessionId) {
         const metaRes = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = $1", [sessionId]);
         if (metaRes.rows.length === 0)
-            return null; // no such session (mirror exportEntries' null)
+            return null;
         const res = await this.pool.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC", [sessionId]);
         return res.rows.map((r) => String(r.entry_id));
     }
-    /** @see TiDBSessionStore.exportEntriesStream — 2c P1d-α (PULL streaming): KEYSET-paged async generator over the full
-     *  durable log (node-pg also buffers a plain SELECT → page it). `… WHERE seq > cursor ORDER BY seq ASC LIMIT K`
-     *  (K = batchSize ?? 500), advancing the cursor to the last seq each batch, ONE pooled `pool.query` per batch (no
-     *  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). */
     async exportEntriesStream(sessionId, opts) {
         const metaRes = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = $1", [sessionId]);
         if (metaRes.rows.length === 0)
-            return null; // no such session — NOT an empty iterable
+            return null;
         const pool = this.pool;
         const batchSize = opts?.batchSize ?? 500;
         async function* gen() {
-            let cursor = opts?.afterSeq ?? -1; // seq is 0-based dense → > -1 starts at seq 0
+            let cursor = opts?.afterSeq ?? -1;
             for (;;) {
                 const res = await pool.query("SELECT seq, payload FROM session_event WHERE session_id = $1 AND seq > $2 ORDER BY seq ASC LIMIT $3", [sessionId, cursor, batchSize]);
                 for (const r of res.rows)
                     yield parseEntry(r.payload);
                 if (res.rows.length < batchSize)
-                    return; // short page = end of log
-                cursor = Number(res.rows[res.rows.length - 1].seq); // BIGINT seq → STRING in node-pg → Number(...)
+                    return;
+                cursor = Number(res.rows[res.rows.length - 1].seq);
             }
         }
         return gen();
     }
-    /** @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 with
-     *  session_meta LAST as the commit point; owner = the RE-STAMPED authenticated principal (never the bundle's). */
     async importEntries(sessionId, owner, entries) {
-        const validated = validateEntriesForImport(entries); // fail-closed invariant gate BEFORE any write
+        const validated = validateEntriesForImport(entries);
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            // Shared insert body (entries re-seq dense from 0 + session_meta LAST = commit point). Plain INSERT (fresh-only);
-            // replaceEntries is the idempotent-over-existing path (DELETEs first inside the same txn). @see TiDB twin.
             await this.insertValidatedLog(conn, sessionId, owner, validated);
             await conn.query("COMMIT");
         }
@@ -540,37 +420,28 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
-                /* ignore */
             }
             if (err instanceof SessionError)
-                throw err; // invalid_session (gate) / conflict — pass through
+                throw err;
             throw new SessionError("storage", `import of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
         }
     }
-    /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST
-     *  (fail-closed), then DELETE events + the owner-guarded meta delete (`owner IS NOT DISTINCT FROM $n` = the PG `<=>`,
-     *  defense-in-depth), then re-insert via the SHARED body (entries + session_meta LAST as the commit point), ALL in
-     *  ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry) — unlike importEntries' fresh-only INSERT. */
     async replaceEntries(sessionId, owner, entries) {
-        await this.assertNotPlaced(sessionId, "replace"); // 快路(事务外,零工拒);真门在事务内(TiDB 孪生同款注)
-        const validated = validateEntriesForImport(entries); // fail-closed gate BEFORE any write (mirrors importEntries)
+        await this.assertNotPlaced(sessionId, "replace");
+        const validated = validateEntriesForImport(entries);
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            // #292(codex R1-[high] 同族窗):事务内锁读 + DELETE 的 `placement_kind IS NULL` 硬条件
-            // (TiDB 孪生逐字同义 —— placed 行 owner 恒 NULL,而 replace(owner=null) 的属主门恰好匹配它)。
             const placedRes = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
             if (placedRes.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");
                 throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placedRes.rows[0].placement_kind} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
             }
-            // Purge first (idempotent: a missing session deletes 0 rows). Events, then the owner-guarded meta delete.
             await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
             await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND placement_kind IS NULL", [sessionId, owner]);
-            // …then re-insert the validated log (entries + meta-as-commit-point) via the SHARED body.
             await this.insertValidatedLog(conn, sessionId, owner, validated);
             await conn.query("COMMIT");
         }
@@ -579,23 +450,19 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
-                /* ignore */
             }
             if (err instanceof SessionError)
-                throw err; // invalid_session (gate) / conflict — pass through
+                throw err;
             throw new SessionError("storage", `replace of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
         }
     }
-    /** @see TiDBSessionStore.insertValidatedLog — shared insert half of importEntries / replaceEntries (ONE source, no
-     *  drift): entries re-seq dense from 0 (ids/parents/payload/ts verbatim), THEN session_meta LAST as the commit point.
-     *  Runs inside the caller's open txn (`conn` already in BEGIN); the caller owns COMMIT/ROLLBACK + the validate gate. */
     async insertValidatedLog(conn, sessionId, owner, validated) {
         let leafId = null;
         for (const e of validated)
-            leafId = leafIdAfterEntry(e); // replayed leaf — core's exported helper (no service copy)
+            leafId = leafIdAfterEntry(e);
         const now = new Date();
         for (let seq = 0; seq < validated.length; seq++) {
             const e = validated[seq];
@@ -603,21 +470,13 @@ export class PgSessionStore {
         }
         await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES ($1,$2,$3,$4,$5,$6)", [sessionId, owner, now, now, leafId, validated.length]);
     }
-    /** @see TiDBSessionStore.beginImportStaging — 2c P1d-β PUSH staging: stream batches into the shadow id
-     *  `${realSessionId}#stg-${token}` (route-minted token), then commit (atomic swap) / abort. */
     beginImportStaging(realSessionId, token) {
         return new PgStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
     }
-    /** @see TiDBSessionStore.readStagedEntries — 2c P1d-β staged-row inspection: the staged rows under `stagingId`, oldest-
-     *  first, no session_meta probe (a staging id has no meta row). No longer the import gate (the per-line
-     *  StreamingImportValidator validates during the stream); a tests/diagnostics seam. Returns [] for an empty/unknown id. */
     async readStagedEntries(stagingId) {
         const res = await this.pool.query("SELECT payload FROM session_event WHERE session_id = $1 ORDER BY seq ASC", [stagingId]);
         return res.rows.map((r) => parseEntry(r.payload));
     }
-    /** @see TiDBSessionStore.sweepStagingSessions — reaper for abandoned staging sessions: DELETE session_event rows
-     *  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. */
     async sweepStagingSessions() {
         const cutoff = new Date(Date.now() - STAGING_GC_GRACE_MS);
         const cands = await this.pool.query("SELECT se.session_id FROM session_event se LEFT JOIN session_meta sm ON sm.session_id = se.session_id " +
@@ -630,9 +489,6 @@ export class PgSessionStore {
         }
         return removed;
     }
-    /** @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). */
     async deleteSession(sessionId, owner) {
         const conn = await this.pool.connect();
         try {
@@ -648,7 +504,6 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -663,28 +518,18 @@ export class PgSessionStore {
         this.pending.clear();
     }
 }
-/**
- * 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 with session_meta LAST = the commit point.
- */
 class PgStagingHandle {
     pool;
     realSessionId;
     stagingId;
     nextSeq = 0;
-    seen = new Set(); // staged ids (resume dedup → dense seqs); @see TiDBStagingHandle
+    seen = new Set();
     constructor(pool, realSessionId, stagingId) {
         this.pool = pool;
         this.realSessionId = realSessionId;
         this.stagingId = stagingId;
     }
-    /** @see TiDBStagingHandle.appendBatch — DENSE re-seq (skip already-staged ids), idempotent ON CONFLICT (session_id,
-     *  entry_id) DO NOTHING, one txn/batch. */
     async appendBatch(entries) {
-        // ONE multi-row INSERT per batch (bounded) — @see TiDBStagingHandle.appendBatch. Build $-placeholders for the NEW
-        // rows (skip already-staged ids → dense seqs), ON CONFLICT (session_id, entry_id) DO NOTHING as the durable backstop.
         const params = [];
         const tuples = [];
         for (const e of entries) {
@@ -692,7 +537,7 @@ class PgStagingHandle {
                 continue;
             const b = params.length;
             tuples.push(`($${b + 1},$${b + 2},$${b + 3},$${b + 4},$${b + 5},$${b + 6}::jsonb,$${b + 7})`);
-            params.push(this.stagingId, this.nextSeq, e.id, e.parentId ?? null, e.type, pgSafeJsonStringify(e), new Date() /* A-1: row-insert time, not source-history — reaper liveness; payload keeps e.timestamp */);
+            params.push(this.stagingId, this.nextSeq, e.id, e.parentId ?? null, e.type, pgSafeJsonStringify(e), new Date());
             this.seen.add(e.id);
             this.nextSeq++;
         }
@@ -706,15 +551,12 @@ class PgStagingHandle {
             throw err instanceof SessionError ? err : new SessionError("storage", `staged append for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
         }
     }
-    /** @see TiDBStagingHandle.commit — the atomic swap: in-commit re-classify (FOR UPDATE) → purge dst → rename
-     *  staging→real → session_meta LAST. Throws SyncConflictError on an unconsented fork/stale flip. */
     async commit(owner, opts) {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
             const staged = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const dst = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
-            // `placement_kind` 捎带在存在性探针上(#292:placed 目的地拒整段换装;TiDB 孪生同形)。
             const dstMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
             if (dstMeta.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");
@@ -727,8 +569,6 @@ class PgStagingHandle {
                 await conn.query("ROLLBACK");
                 throw new SyncConflictError(this.realSessionId, rel);
             }
-            // 🔴 [2557] A5/F2(2026-08-05):fast_forward 的**载荷**判据(tidb twin 同注)——共享段分叉 ⇒ 409,
-            // 除非显式 overwrite-dst;载荷只在这条臂上读,行已被 FOR UPDATE 锁住,同 txn 重读是一致读。
             if (rel.relation === "fast_forward" && opts?.resolution !== "overwrite-dst" && dstIds !== null && dstIds.length > 0) {
                 const dstFull = await conn.query("SELECT payload FROM session_event WHERE session_id = $1 ORDER BY seq ASC", [this.realSessionId]);
                 const stagedFull = await conn.query("SELECT entry_id, payload FROM session_event WHERE session_id = $1 ORDER BY seq ASC", [this.stagingId]);
@@ -750,9 +590,6 @@ class PgStagingHandle {
             const now = new Date();
             await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES ($1,$2,$3,$4,$5,$6) " +
                 "ON CONFLICT (session_id) DO UPDATE SET owner = EXCLUDED.owner, updated_at = EXCLUDED.updated_at, leaf_id = EXCLUDED.leaf_id, leaf_seq = EXCLUDED.leaf_seq", [this.realSessionId, owner, now, now, leafId, srcIds.length]);
-            // 🔴 #292(codex R1-[high]):**提交前的最后一道门** —— upsert 之后这一行必被本事务锁住,故这次
-            // 复读是权威的;它关的是「探针时行还不存在、并发方随后把同 id 铸成 placed」那半个窗(PG 的
-            // FOR UPDATE 对缺席行不锁任何东西)。理由与失败经济学逐字见 TiDB 孪生同处的注。
             const afterMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
             if (afterMeta.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");
@@ -765,7 +602,7 @@ class PgStagingHandle {
             try {
                 await conn.query("ROLLBACK");
             }
-            catch { /* ignore */ }
+            catch { }
             if (err instanceof SyncConflictError || err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `staged commit for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
@@ -774,7 +611,6 @@ class PgStagingHandle {
             conn.release();
         }
     }
-    /** @see TiDBStagingHandle.abort — DELETE the staging rows. Idempotent. */
     async abort() {
         await this.pool.query("DELETE FROM session_event WHERE session_id = $1", [this.stagingId]);
     }