@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/pg-session-storage.d.ts

@@ -2,38 +2,75 @@ import { BaseSessionStorage, type PromptEpochDescriptor, type AcquiredSession, t
 import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
+/**
+ * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
+ * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), inline `KEY`/`UNIQUE KEY`→separate CREATE INDEX (UNIQUE for uk_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 declare const PG_SESSION_SCHEMA: string[];
+/** Idempotent schema apply for this store's tables (the test calls this; production aggregation is separate). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
+/**
+ * PostgreSQL-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
+ *
+ * Behaviourally identical to {@link TiDBSessionStorage}; see that file's class doc for the F2/F3 seams. The only
+ * differences are dialectal (placeholders, `IS NOT DISTINCT FROM`, jsonb, rowCount, transaction handle).
+ */
 export declare class PgSessionStorage extends BaseSessionStorage {
     private readonly pool;
     private readonly sessionId;
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
+    /** @see TiDBSessionStorage.getEpochAnchor — [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). */
     getEpochAnchor(): Promise<PromptEpochDescriptor | undefined>;
+    /** @see TiDBSessionStorage.wake — F3 bounded `[floor..leaf]` rebuild; null if the session does not exist. */
     static wake(pool: Pool, sessionId: string): Promise<PgSessionStorage | null>;
+    /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). @see TiDBSessionStorage.computeFloor */
     private static computeFloor;
+    /** Sub-floor lookups (e.g. a label target) aren't in the loaded tail — fall back to the durable log. */
     getEntry(id: string): Promise<SessionTreeEntry | undefined>;
     appendEntry(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
     setLeafId(leafId: string | null, opts?: SessionWriteOptions): Promise<void>;
+    /**
+     * Atomically: CAS the meta leaf (+bump leaf_seq), then append the event at the new seq.
+     * The `(session_id, seq)` primary key is the backstop — a racing writer that grabbed the same
+     * seq makes our INSERT fail with a duplicate-key (23505), which we translate to a conflict too.
+     */
     private persist;
 }
+/**
+ * PostgreSQL-backed {@link SessionStore} — the PG twin of {@link TiDBSessionStore}. Maps the
+ * `SessionStore` surface (acquire / register / ownerOf / touch / release) onto {@link PgSessionStorage}.
+ */
 export declare class PgSessionStore implements SessionStore {
     private readonly pool;
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
     constructor(pool: Pool);
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
     private load;
+    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten. */
     register(sessionId: string, owner: string | null): Promise<void>;
+    /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
     touch(sessionId: string): Promise<void>;
+    /** 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). */
     getLeafId(sessionId: string): Promise<string | null>;
+    /** [1196] 六轮复审:owner+leafId 单行原子快照(@see TiDBSessionStore.getHead——混世代组合防)。 */
     getHead(sessionId: string): Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
+    /** Durable history is retained; just drop any in-flight cache entry. */
     release(sessionId: string): Promise<void>;
+    /** @see TiDBSessionStore.listSessions — session identity from session_meta (owner-filtered), task_run LEFT JOIN for preview. */
     listSessions(opts: {
         owner?: string;
         cursor?: {
@@ -43,21 +80,56 @@ export declare class PgSessionStore implements SessionStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** @see TiDBSessionStore.probeTitle — the PG twin. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
+    /** @see TiDBSessionStore.setTitleIfNull — the PG twin (write-once auto-title). */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** @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. */
     fork(sourceId: string, owner: string | null): Promise<string | null>;
+    /** @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. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
+    /** @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. */
     listEntryIds(sessionId: string): Promise<string[] | null>;
+    /** @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). */
     exportEntriesStream(sessionId: string, opts?: {
         afterSeq?: number;
         batchSize?: number;
     }): 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 with
+     *  session_meta LAST as the commit point; owner = the RE-STAMPED authenticated principal (never the bundle's). */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST
+     *  (fail-closed), then 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. */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /** @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. */
     private insertValidatedLog;
+    /** @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: string, token: string): StagingHandle;
+    /** @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. */
     readStagedEntries(stagingId: string): Promise<SessionTreeEntry[]>;
+    /** @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. */
     sweepStagingSessions(): Promise<number>;
+    /** @see TiDBSessionStore.deleteSession — purge session_meta + session_event; idempotent (false if absent).
+     *  Owner-guarded on session_meta.owner (`IS NOT DISTINCT FROM` = the PG `<=>`); the event purge is gated on the
+     *  owner-matched meta delete (session_event has no owner column). */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     get size(): number;
     dispose(): void;

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

@@ -1,16 +1,45 @@
+/**
+ * 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 { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, } from "../session-sync-kernel.js";
+/** Staging-row reaper grace window (twin of the TiDB store's STAGING_GC_GRACE_MS) — see that store for the rationale. */
 const STAGING_GC_GRACE_MS = 3_600_000;
 function isDupKey(err) {
-    return Boolean(err) && err.code === "23505";
+    return Boolean(err) && err.code === "23505"; // PG unique_violation
 }
+/** 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 uk_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)  NOT NULL,
@@ -37,10 +66,17 @@ export const PG_SESSION_SCHEMA = [
    )`,
     `CREATE UNIQUE INDEX IF NOT EXISTS uk_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;
@@ -51,14 +87,17 @@ 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;
+            return undefined; // full load — the walk already reaches the root pin
         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;
+                return undefined; // exhausted — a genuine pre-epoch session
             for (const r of res.rows) {
                 const e = parseEntry(r.payload);
                 const d = e.type === "prompt_epoch" ? normalizePromptEpoch(e) : normalizePromptEpoch(e.details?.promptEpoch);
@@ -68,6 +107,7 @@ 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("SELECT created_at, leaf_id, leaf_seq FROM session_meta WHERE session_id = $1", [sessionId]);
         const meta = metaRes.rows[0];
@@ -79,6 +119,7 @@ export class PgSessionStorage extends BaseSessionStorage {
         const metadata = { id: sessionId, createdAt: toIso(meta.created_at) };
         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])
@@ -88,10 +129,12 @@ 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)
@@ -107,10 +150,16 @@ 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;
@@ -127,16 +176,17 @@ 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;
+            const commitOwner = seqRes.rows[0].owner ?? null; // codex-2:S2 发射 owner=本事务当前行(tidb twin 同注)
             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);
+            emitLeafAdvance(this.sessionId, newLeaf, commitOwner, seq); // S2 fast path — post-commit only, fire-and-forget (session-leaf-bus 契约;tidb twin 同点)
         }
         catch (err) {
             try {
                 await conn.query("ROLLBACK");
             }
             catch {
+                /* ignore rollback error */
             }
             if (err instanceof SessionError)
                 throw err;
@@ -150,8 +200,14 @@ 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;
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     pending = new Map();
     constructor(pool) {
         this.pool = pool;
@@ -162,6 +218,9 @@ export class PgSessionStore {
             await this.register(id, null);
             return this.load(id);
         }
+        // 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);
         const inflight = this.pending.get(sessionId);
@@ -174,6 +233,8 @@ export class PgSessionStore {
     async load(sessionId, requireExisting = false) {
         let storage = await PgSessionStorage.wake(this.pool, sessionId);
         if (!storage) {
+            // 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);
@@ -181,11 +242,13 @@ export class PgSessionStore {
         }
         return { session: new StoredSession(storage), sessionId };
     }
+    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten. */
     async register(sessionId, owner) {
         const now = new Date();
         await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) " +
             "VALUES ($1,$2,$3,$4,NULL,0) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now]);
     }
+    /** 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)
@@ -198,19 +261,27 @@ 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. */
     async release(sessionId) {
         this.pending.delete(sessionId);
     }
+    // ───────────────────────── 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) => {
@@ -220,6 +291,7 @@ export class PgSessionStore {
         const where = [];
         if (opts.owner)
             where.push(`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) {
@@ -232,7 +304,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 " +
+            "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id FROM task_run " + // K-5c: latest run's task_id
             "  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)}`;
@@ -245,10 +317,11 @@ 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,
+            lastRunId: r.last_run_id ?? null, // K-5c: latest run id = the live-tail re-attach anchor (null if no runs)
             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];
@@ -256,15 +329,19 @@ 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();
@@ -274,6 +351,8 @@ 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]);
             }
@@ -286,6 +365,7 @@ 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);
         }
@@ -293,44 +373,60 @@ 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;
+            return null; // no such session (mirror exportEntries' 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;
+            return null; // no such session — NOT an empty iterable
         const pool = this.pool;
         const batchSize = opts?.batchSize ?? 500;
         async function* gen() {
-            let cursor = opts?.afterSeq ?? -1;
+            let cursor = opts?.afterSeq ?? -1; // seq is 0-based dense → > -1 starts at seq 0
             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;
-                cursor = Number(res.rows[res.rows.length - 1].seq);
+                    return; // short page = end of log
+                cursor = Number(res.rows[res.rows.length - 1].seq); // BIGINT seq → STRING in node-pg → Number(...)
             }
         }
         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);
+        const validated = validateEntriesForImport(entries); // fail-closed invariant gate BEFORE any write
         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");
         }
@@ -339,22 +435,29 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
+                /* ignore */
             }
             if (err instanceof SessionError)
-                throw err;
+                throw err; // invalid_session (gate) / conflict — pass through
             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) {
-        const validated = validateEntriesForImport(entries);
+        const validated = validateEntriesForImport(entries); // fail-closed gate BEFORE any write (mirrors importEntries)
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
+            // 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", [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");
         }
@@ -363,19 +466,23 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
+                /* ignore */
             }
             if (err instanceof SessionError)
-                throw err;
+                throw err; // invalid_session (gate) / conflict — pass through
             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);
+            leafId = leafIdAfterEntry(e); // replayed leaf — core's exported helper (no service copy)
         const now = new Date();
         for (let seq = 0; seq < validated.length; seq++) {
             const e = validated[seq];
@@ -383,13 +490,21 @@ 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 " +
@@ -402,6 +517,9 @@ 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 {
@@ -417,6 +535,7 @@ export class PgSessionStore {
                 await conn.query("ROLLBACK");
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -431,18 +550,28 @@ 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();
+    seen = new Set(); // staged ids (resume dedup → dense seqs); @see TiDBStagingHandle
     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) {
@@ -450,7 +579,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());
+            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 */);
             this.seen.add(e.id);
             this.nextSeq++;
         }
@@ -464,6 +593,8 @@ 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 {
@@ -494,7 +625,7 @@ class PgStagingHandle {
             try {
                 await conn.query("ROLLBACK");
             }
-            catch { }
+            catch { /* ignore */ }
             if (err instanceof SyncConflictError || err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `staged commit for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
@@ -503,6 +634,7 @@ 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]);
     }