@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/tidb-session-store.js

@@ -1,10 +1,27 @@
+/**
+ * TiDB-backed Session event-log center (L1) — the durable "persistence center".
+ *
+ * Implements core's `SessionStore`. `acquire` rebuilds a session from its append-only event log
+ * (= wake/resume), so any stateless runner instance can continue it. Cross-instance write safety is
+ * enforced by the storage layer's compare-and-set (core's F2 seam); crash consistency (orphan
+ * tool-call after a mid-turn crash) is handled by the Runner calling `reconcileInterruptedSession`
+ * on acquire (core's F1).
+ *
+ * Persistence only. **Tenant authorization (who may wake which session) lives in the service layer**
+ * (`src/security.ts`), which uses `ownerOf` / `register` below. The store does not infer identity.
+ */
+// 🔴 core 1.403 迁移(2026-07-25):runtime 构造用法,`Session` → `StoredSession`(见 audit.ts 同款注释)。
 import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./tidb-session-storage.js";
 import { escapeLike } from "./sql-escape.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, } from "../session-sync-kernel.js";
+/** Staging-row reaper grace window — a staging session's rows are GC'able only if it has NO session_meta (never
+ *  committed) AND its OLDEST row is older than this (an in-flight stream keeps appending fresh rows → safe). Mirrors
+ *  the file-snapshot store's BLOB_GC_GRACE_MS discipline (an in-flight import must never be reaped mid-stream). */
 const STAGING_GC_GRACE_MS = 3_600_000;
 export class TiDBSessionStore {
     pool;
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     pending = new Map();
     constructor(pool) {
         this.pool = pool;
@@ -15,6 +32,10 @@ export class TiDBSessionStore {
             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. Two concurrent requireExisting opens each just
+        // wake independently (both resolve or both fail loud) — harmless (it only opens, never double-creates).
         if (opts?.requireExisting)
             return this.load(sessionId, true);
         const inflight = this.pending.get(sessionId);
@@ -27,18 +48,25 @@ export class TiDBSessionStore {
     async load(sessionId, requireExisting = false) {
         let storage = await TiDBSessionStorage.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 that turns a reuse-style warm-resume into a fresh empty run. core's
+            // prepare-task maps this store `not_found` to the caller-facing `resume.session_not_found`.
             if (requireExisting)
                 throw new SessionError("not_found", `session ${sessionId} not found`);
+            // No meta row yet (a caller-chosen brand-new id the service didn't pre-register). Create it
+            // ownerless; only the caller who chose this id can reach it, and it holds no prior data.
             await this.register(sessionId, null);
             storage = await TiDBSessionStorage.wake(this.pool, sessionId);
         }
         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 (?,?,?,?,NULL,0) ON DUPLICATE KEY UPDATE session_id = session_id", [sessionId, owner, now, now]);
     }
+    /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     async ownerOf(sessionId) {
         const [rows] = await this.pool.query("SELECT owner FROM session_meta WHERE session_id = ?", [sessionId]);
         if (rows.length === 0)
@@ -51,39 +79,73 @@ export class TiDBSessionStore {
             sessionId,
         ]);
     }
+    /** E18 — the session's current leaf `SessionTreeEntry.id` (`session_meta.leaf_id`, set transactionally on every
+     *  persist). A single SELECT, NO acquire/lock/CAS — safe to call mid-run (write-safety is the append-time CAS, not
+     *  an acquire lease) and cache-bypassing (the resume-at turn-capture reads it without touching the warm session).
+     *  Returns the leaf id, or null when the session has none / no such session. */
     async getLeafId(sessionId) {
         const [rows] = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = ?", [sessionId]);
         return rows[0] ? (rows[0].leaf_id ?? null) : null;
     }
+    /** [1196] 六轮复审:owner+leafId **单行原子快照**(SSE watch 探针的租户围栏读)——两独立 SELECT 在
+     *  delete/reclaim 缝里可拼出「旧 owner+新 leaf」混世代组合;单 SELECT 单行=天然一致。undefined=无此会话。 */
     async getHead(sessionId) {
         const [rows] = await this.pool.query("SELECT owner, leaf_id FROM session_meta WHERE session_id = ?", [sessionId]);
         if (rows.length === 0)
             return undefined;
         return { owner: rows[0].owner ?? null, leafId: 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 session-ownership) ─────────────────────────
+    // E16/E17/E21: the service EXTENDS core's `SessionRepo` (list/fork/delete) over its OWN session_meta /
+    // session_event tables — a `TiDBSessionRepo`-style implementation (core's `PgSessionRepo` targets core's
+    // own `agent_*` tables, so it can't be consumed directly; the dossier §0.5 prescribes a backend-mirrored
+    // impl here). Enumeration + lifecycle now come from the SESSION abstraction (session identity), not the
+    // `task_run` runs ledger; `task_run` retreats to a pure runs ledger that only SUPPLIES run-level preview.
+    /**
+     * E16 — list the caller's sessions (CC /resume picker), keyset-paginated newest-first by last activity.
+     * Session IDENTITY/enumeration comes from `session_meta` (owner-filtered on the service's OWN owner column);
+     * a LEFT JOIN onto the `task_run` runs ledger supplies run-level PREVIEW (latest run's objective/status,
+     * run count) but never gates which sessions exist — a session with zero runs still lists (preview null/0).
+     * Keyset on `(updated_at, session_id)`; `updated_at` is the session's last-activity marker (touch on every
+     * run/append). The shipped {@link SessionSummary} shape is preserved (additive): `lastActivityAt` =
+     * `session_meta.updated_at`, `firstActivityAt` = `session_meta.created_at`.
+     */
     async listSessions(opts) {
         const params = [];
         const where = [];
         if (opts.owner) {
-            where.push("sm.owner = ?");
+            where.push("sm.owner = ?"); // idx_owner — the per-user view (a principal is PINNED to its own at the route)
             params.push(opts.owner);
         }
         if (opts.q) {
+            // `?q=` search: match sessions where ANY run's objective preview contains q (EXISTS on the
+            // runs ledger — better recall than latest-run-only, still session-granular). LOWER-LIKE = collation-proof
+            // case-insensitivity (TiDB table collation may be _bin); escapeLike + ESCAPE pins the wildcard semantics
+            // (deployment baseline: default sql_mode — under NO_BACKSLASH_ESCAPES the '\\' literal would break, a
+            // known escapeLike-family boundary shared with the tool-result store).
+            // No tr.owner predicate BY DESIGN: the outer WHERE already proves the session is the caller's;
+            // a same-session_id foreign-owner run requires DB write access to fabricate (session_meta PK + uuidv7),
+            // and an owner predicate would drop the LEGITIMATE mixed-owner form (anonymous run → principal attach,
+            // the E21 diverged-owner case) — recall loss for a 1-bit defense against an attacker who can already write.
             where.push("EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(?) ESCAPE '\\\\')");
             params.push(`%${escapeLike(opts.q)}%`);
         }
         if (opts.cursor) {
-            where.push("(sm.updated_at < ? OR (sm.updated_at = ? AND sm.session_id < ?))");
+            where.push("(sm.updated_at < ? OR (sm.updated_at = ? AND sm.session_id < ?))"); // keyset: strictly older, ties by id
             params.push(new Date(opts.cursor.lastActivityAt), new Date(opts.cursor.lastActivityAt), opts.cursor.sessionId);
         }
+        // The run-preview JOIN: the LATEST run per session (rn=1, ties broken by task_id so EXACTLY one row joins —
+        // a bare MAX(created_at) JOIN would fan out the outer row when two runs share a created_at) + a count rollup.
+        // A LEFT JOIN keeps sessions with NO runs (preview NULL, run_count 0). Bounded by per-tenant data today.
         const sql = "SELECT sm.session_id, sm.owner, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, " +
             "  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 session_id, objective_preview, status, task_id FROM (" +
+            "LEFT JOIN (SELECT session_id, objective_preview, status, task_id FROM (" + // K-5c: carry the rn=1 run's task_id
             "    SELECT session_id, objective_preview, status, task_id, " +
             "      ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn FROM task_run" +
             "  ) lr WHERE rn = 1) latest ON latest.session_id = sm.session_id " +
@@ -99,33 +161,55 @@ export class TiDBSessionStore {
             runCount: Number(r.run_count),
             objectivePreview: r.objective_preview ?? null,
             lastStatus: r.status == null ? "" : String(r.status),
-            lastRunId: r.last_run_id ?? null,
-            title: r.title ?? 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, // auto-generated title (null = not yet titled)
         }));
     }
+    /** Cheap pre-LLM probe: "none" = session_meta row not yet REGISTERED (createRun fires
+     *  before the Runner's session acquire — the titler retries), "untitled" / "titled" as read. */
     async probeTitle(sessionId) {
         const [rows] = await this.pool.query("SELECT title FROM session_meta WHERE session_id = ?", [sessionId]);
         if (!rows[0])
             return "none";
         return rows[0].title == null ? "untitled" : "titled";
     }
+    /** Write-once auto-title: lands ONLY when title IS NULL (a concurrent/prior title wins;
+     *  the user-facing rename layer is BFF-side). Returns whether this call set it. */
     async setTitleIfNull(sessionId, title) {
         const [r] = await this.pool.query("UPDATE session_meta SET title = ? WHERE session_id = ? AND title IS NULL", [title, sessionId]);
         return r.affectedRows > 0;
     }
+    /**
+     * E17 — fork a session: copy its WHOLE durable history to a NEW uuidv7 session owned by `owner`, mirroring
+     * core's `PgSessionRepo.fork`. Entry ids / parent links are per-session and copy VERBATIM; only `seq` is
+     * re-densified from 0 in the new session. The new leaf = the source leaf (session_meta.leaf_id).
+     * Returns the new sessionId, or null if the source does not exist (the route maps that to 404).
+     *
+     * 🔴 FULL history, NOT `wake().getEntries()` (adversarial-review MEDIUM): `wake` loads only the bounded tail
+     * `[floor..leaf]` from the latest compaction floor (F3), so forking via it would copy only the active tail of a
+     * COMPACTED session and SILENTLY LOSE all pre-compaction history (contradicting the whole-history-copy intent).
+     * We instead SELECT the entire `session_event` log ordered by seq — every durable entry, compaction floor
+     * bypassed — and re-seq it dense from 0 into the new session, ids/parents/payload byte-verbatim.
+     */
     async fork(sourceId, owner) {
+        // The source's authoritative leaf (and existence check) come from session_meta — null meta ⇒ unknown source.
         const [metaRows] = await this.pool.query("SELECT leaf_id FROM session_meta WHERE session_id = ?", [sourceId]);
         if (!metaRows[0])
             return null;
         const leafId = metaRows[0].leaf_id ?? null;
+        // FULL durable history (compaction floor bypassed) — every entry, oldest first. payload is the stored entry blob.
         const [eventRows] = await this.pool.query("SELECT entry_id, parent_id, type, payload, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC", [sourceId]);
         const newId = uuidv7();
         const now = new Date();
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            // Entries land BEFORE the session_meta row (mirrors core BUG-1): the meta row is the commit point —
+            // a mid-fork failure leaves orphan events with NO meta row (invisible to wake), never a half-session.
             for (let seq = 0; seq < eventRows.length; seq++) {
                 const r = eventRows[seq];
+                // Copy the payload blob VERBATIM (string or already-parsed object); re-stringify only an object so the
+                // INSERT binds a JSON string. entry_id/parent_id/type/ts are carried over unchanged; only seq is re-densified.
                 const payload = typeof r.payload === "string" ? r.payload : JSON.stringify(r.payload);
                 await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [newId, seq, r.entry_id, r.parent_id ?? null, r.type, payload, r.ts]);
             }
@@ -138,6 +222,7 @@ export class TiDBSessionStore {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err instanceof SessionError ? err : new SessionError("storage", `fork of session ${sourceId} failed`, err instanceof Error ? err : undefined);
         }
@@ -145,46 +230,100 @@ export class TiDBSessionStore {
             conn.release();
         }
     }
+    /**
+     * 2c session-sync — EXPORT a session's full durable entry log for cross-backend migration. This is the
+     * READ half of {@link fork}, surfaced as the core `SessionRepo.exportEntries` seam: the WHOLE `session_event` log,
+     * oldest-first, ids/parents/payload/ts VERBATIM, with the compaction floor BYPASSED (NOT `wake().getEntries()`,
+     * which returns only the bounded `[floor..leaf]` tail and would silently truncate pre-floor history — see fork's
+     * note at :149-152). Returns `null` if the source does not exist (no `session_meta` row), mirroring fork's null
+     * semantics; an existing-but-empty session returns `[]`. The owner is NOT exported — import re-stamps it (§9).
+     */
     async exportEntries(sessionId) {
+        // Existence check = session_meta (a session with zero events but a meta row is a real, empty session ⇒ []).
         const [metaRows] = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = ?", [sessionId]);
         if (!metaRows[0])
             return null;
+        // FULL durable log (compaction floor bypassed) — every entry, oldest first. payload is the stored entry blob.
         const [eventRows] = await this.pool.query("SELECT entry_id, parent_id, type, payload, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC", [sessionId]);
+        // The export contract is `SessionTreeEntry[]` (the full entry blob), not the column projection. The stored
+        // `payload` IS the verbatim entry (id/parentId/timestamp + variant fields) — parse a string blob, pass an
+        // already-parsed object (mysql2 returns JSON columns parsed) through.
         return eventRows.map((r) => (typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload));
     }
+    /**
+     * 2c session-sync P1d-α (PULL streaming) — the IDS-ONLY projection of {@link exportEntries}: the entry ids of the
+     * WHOLE durable log, oldest-first (`SELECT entry_id … ORDER BY seq ASC`), with no payloads. Small even for a huge
+     * session, so the PULL `GET /sync/manifest` can carry it (and feed it to `classifySyncRelationshipByIds`) instead of
+     * the entries. Returns `null` if the source does not exist (no `session_meta` row), mirroring {@link exportEntries}.
+     */
     async listEntryIds(sessionId) {
         const [metaRows] = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = ?", [sessionId]);
         if (!metaRows[0])
-            return null;
+            return null; // no such session (mirror exportEntries' null)
         const [rows] = await this.pool.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC", [sessionId]);
         return rows.map((r) => String(r.entry_id));
     }
+    /**
+     * 2c session-sync P1d-α (PULL streaming) — STREAM the WHOLE durable log (compaction floor bypassed), oldest-first,
+     * as an async generator that KEYSET-PAGES the `session_event` table: mysql2 buffers a plain SELECT, so a 1M-row
+     * session would OOM if read in one shot. Instead the generator loops `… WHERE seq > cursor ORDER BY seq ASC LIMIT K`
+     * (K = `opts.batchSize ?? 500`), advancing the cursor to the last `seq` of each batch, until a SHORT page (fewer than
+     * K rows) ends the stream. Each batch is its OWN `pool.query` (a pooled connection acquired + released per batch), so
+     * a slow NDJSON consumer can NEVER pin one connection across the whole stream (the clay-mandated concurrency
+     * discipline). Start cursor = `opts.afterSeq ?? -1` (seq is 0-based dense, so `> -1` = from seq 0).
+     *
+     * Resolves to `null` (NOT an empty async-iterable) when the session does not exist — checked via `session_meta`
+     * EAGERLY here (before returning the iterable), exactly like {@link exportEntries}, so a missing session is distinct
+     * from a real-but-empty one (an empty stream). payload is parsed like {@link exportEntries} (string → JSON.parse,
+     * object passthrough). 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.
+     */
     async exportEntriesStream(sessionId, opts) {
         const [metaRows] = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = ?", [sessionId]);
         if (!metaRows[0])
-            return null;
+            return null; // no such session (mirror exportEntries' null) — 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 (;;) {
+                // ONE pooled query per batch (NOT a held connection across the whole stream) — keyset on (session_id, seq).
                 const [rows] = await pool.query("SELECT seq, payload FROM session_event WHERE session_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?", [sessionId, cursor, batchSize]);
                 for (const r of rows) {
                     const p = r.payload;
                     yield (typeof p === "string" ? JSON.parse(p) : p);
                 }
                 if (rows.length < batchSize)
-                    return;
-                cursor = Number(rows[rows.length - 1].seq);
+                    return; // short page = end of log (no further round-trip)
+                cursor = Number(rows[rows.length - 1].seq); // advance the keyset cursor to the last seq seen
             }
         }
         return gen();
     }
+    /**
+     * 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`,
+     * with two 2c-mandated differences from fork:
+     *   (a) OWNER RE-STAMP (§9): `owner` is the AUTHENTICATED importing principal passed by the caller; the bundle's
+     *       own owner is NEVER trusted (a local push is always owner=null → would become an ownerless cloud session
+     *       any anonymous caller could attach to). Mirrors the fork route's server-side `scope.gateOwner`.
+     *   (b) the single INVARIANT GATE is core's {@link validateEntriesForImport} (unique ids / parent-before-child /
+     *       exactly-one-root / leaf-resolvable / structural refs present) — we persist its VERBATIM output and do NOT
+     *       re-implement any of those checks in SQL ([[core-service-boundary]]; the same discipline fork's hand-SQL
+     *       was warned about). A violation throws `SessionError("invalid_session")` and NOTHING is written.
+     * The write itself mirrors fork: re-seq dense from 0, entry_id/parent_id/payload/ts verbatim, in ONE txn with
+     * `session_meta` LAST as the commit point (a mid-import crash leaves orphan events with no meta = invisible to
+     * wake, never a half-session). The leaf is the replayed leaf (core's `leafIdAfterEntry`), matching core's import.
+     */
     async importEntries(sessionId, owner, entries) {
+        // Fail-CLOSED invariant gate FIRST (before any write) — returns the entries verbatim or throws invalid_session.
         const validated = validateEntriesForImport(entries);
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            // The shared insert body (entries re-seq dense from 0, then session_meta LAST as the commit point). A plain
+            // INSERT — assumes a FRESH sessionId; a duplicate (session already present) crashes on the PK. replaceEntries
+            // is the idempotent-over-existing path (it DELETEs first inside the same txn).
             await this.insertValidatedLog(conn, sessionId, owner, validated);
             await conn.commit();
         }
@@ -193,22 +332,36 @@ export class TiDBSessionStore {
                 await conn.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();
         }
     }
+    /**
+     * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE: purge any existing conversation log for `sessionId` then re-import
+     * `entries` verbatim under `owner`, ALL in ONE txn. Unlike {@link importEntries} (a plain INSERT that crashes on a
+     * duplicate PK when the session already exists at the destination), replace is safe to run OVER an existing session
+     * — the §7 fast-forward path and a §8 retry-to-completion both land on it. The validate gate runs FIRST (fail-closed,
+     * before any write), then DELETE events + the OWNER-GUARDED meta delete (defense-in-depth, mirrors {@link deleteSession}
+     * — a wrong-owner caller can never replace another tenant's session), then the SAME shared insert body importEntries
+     * uses (so there is ONE source of the insert logic, no copy-paste drift). session_meta is still written LAST = commit
+     * point, so a mid-replace crash (post-delete, pre-insert) leaves orphan-free state (no meta = invisible to wake).
+     */
     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.getConnection();
         try {
             await conn.beginTransaction();
+            // Purge the existing log first (idempotent: a missing session deletes 0 rows). Events first, then the
+            // owner-guarded meta delete (`owner <=> ?` — a legacy null-owner session matches owner=null), defense-in-depth.
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
             await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ?", [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.commit();
         }
@@ -217,35 +370,70 @@ export class TiDBSessionStore {
                 await conn.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();
         }
     }
+    /**
+     * Shared insert half of {@link importEntries} / {@link replaceEntries} (ONE source of the insert logic, no drift):
+     * write the validated entries re-seq dense from 0 (entry_id/parent_id/type/ts verbatim), THEN session_meta LAST as
+     * the commit point. Runs inside the caller's open transaction (`conn`) so the caller owns begin/commit/rollback.
+     * `validated` is the OUTPUT of {@link validateEntriesForImport} (the caller runs the gate before opening the txn).
+     */
     async insertValidatedLog(conn, sessionId, owner, validated) {
+        // The replayed leaf (last entry's leaf target, mirroring core resolveLeafId / validateEntriesForImport).
         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();
+        // Entries land BEFORE session_meta (mirrors fork / core BUG-1): the meta row is the commit point.
         for (let seq = 0; seq < validated.length; seq++) {
             const e = validated[seq];
+            // payload = the verbatim entry blob (stringified for the JSON column bind); entry_id/parent_id/type/ts carried
+            // over unchanged from the entry; only seq is re-densified. ts comes from the entry's own ISO timestamp.
             await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [sessionId, seq, e.id, e.parentId ?? null, e.type, JSON.stringify(e), new Date(e.timestamp)]);
         }
+        // session_meta LAST = commit point. owner = the RE-STAMPED authenticated principal (never the bundle's).
         await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq) VALUES (?,?,?,?,?,?)", [sessionId, owner, now, now, leafId, validated.length]);
     }
+    /**
+     * 2c session-sync P1d-β (PUSH streaming, §15) — begin a STAGED import into `realSessionId` under the shadow id
+     * `${realSessionId}#stg-${token}`. The route mints the uuidv7 `token` (the store never calls uuidv7/Date.now itself
+     * → the staging id is deterministic + the route owns the lease key). Returns a {@link TiDBStagingHandle} the route
+     * streams entry batches into ({@link StagingHandle.appendBatch}) then commits ({@link StagingHandle.commit}, the
+     * atomic swap) or aborts. No row is touched here — the handle is a stateless cursor over this pool.
+     */
     beginImportStaging(realSessionId, token) {
         return new TiDBStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
     }
+    /**
+     * 2c session-sync P1d-β (staged-row inspection) — read the rows STAGED under `stagingId` (NO session_meta probe — a
+     * staging id has no meta row by construction, so {@link exportEntries} would return null), oldest-first. The Phase-B
+     * import gate is now the per-line {@link StreamingImportValidator} (core 1.143.0) run during the stream, so this
+     * is no longer the validation path; it remains the staged-row inspection seam (tests/diagnostics). Returns `[]` for an
+     * empty/unknown staging id.
+     */
     async readStagedEntries(stagingId) {
         const [rows] = await this.pool.query("SELECT payload FROM session_event WHERE session_id = ? ORDER BY seq ASC", [stagingId]);
         return rows.map((r) => (typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload));
     }
+    /**
+     * 2c session-sync P1d-β (§4) — reaper for ABANDONED staging sessions: DELETE session_event rows under a staging id
+     * (`session_id LIKE '%#stg-%'`) that has NO session_meta (never committed → invisible orphans) AND whose OLDEST
+     * staged row is older than the grace window (an IN-FLIGHT stream keeps appending fresh `ts` rows → its MIN(ts) is
+     * recent → it is NOT reaped, exactly like sweepOrphanBlobs' created_at grace). Per-staging-id, so a slow but live
+     * stream is never reaped while another abandoned one is. Returns the affected row count. Driven by main.ts's reaper.
+     */
     async sweepStagingSessions() {
         const cutoff = new Date(Date.now() - STAGING_GC_GRACE_MS);
+        // Candidate staging ids = those with rows older than the cutoff AND no meta row. GROUP BY so an in-flight id (its
+        // MIN(ts) recent) is excluded; LEFT JOIN session_meta so a (defensively) committed staging id is never touched.
         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 " +
             "WHERE se.session_id LIKE ? AND sm.session_id IS NULL " +
             "GROUP BY se.session_id HAVING MIN(se.ts) < ?", [`%${STAGING_ID_MARKER}%`, cutoff]);
@@ -256,11 +444,28 @@ export class TiDBSessionStore {
         }
         return removed;
     }
+    /**
+     * E21 — purge a session's CONVERSATION HISTORY (session_meta + session_event). Idempotent: a missing
+     * session is a no-op (returns false). The service's OWN run-ledger / checkpoint / tool-result rows are
+     * purged separately by the route's `purgeSession` coordinator — this method owns only the session
+     * abstraction's tables (the `SessionRepo.delete` half).
+     *
+     * `owner` is the single-DB-fleet null-safe SQL owner guard on `session_meta.owner` (defense-in-depth — the
+     * route already owner-gates; `<=>` so a legacy null-owner session matches owner=null). session_event carries
+     * no owner column, so its purge is GATED on the owner-matched meta delete: if the meta DELETE matched 0 rows
+     * (wrong owner / already gone) we skip the event delete — so a wrong-owner caller can never strand-delete
+     * another tenant's events. Meta is deleted FIRST (mirrors core BUG-2: once it's gone, wake is `null`
+     * regardless of leftover events; if a crash interleaves, orphan events with NO meta are invisible, never a
+     * half-session), and the event purge only runs after that owner-matched commit point.
+     */
     async deleteSession(sessionId, owner) {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            // Meta row FIRST + owner-guarded: once it's gone, wake is `null` regardless of leftover events.
             const [metaRes] = await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ?", [sessionId, owner]);
+            // Only purge events when the OWNER-matched meta row was removed — gates the un-owner-columned event table
+            // through the meta owner check (a wrong-owner / already-gone session removes 0 meta rows → skip the events).
             if (metaRes.affectedRows > 0)
                 await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
             await conn.commit();
@@ -271,6 +476,7 @@ export class TiDBSessionStore {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -279,30 +485,53 @@ export class TiDBSessionStore {
         }
     }
     get size() {
+        // Best-effort: durable store reloads per acquire (no long-lived cache), so report in-flight only.
         return this.pending.size;
     }
     dispose() {
+        // The pool is owned by main.ts and closed there; nothing process-local to release.
         this.pending.clear();
     }
 }
+/**
+ * 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, with session_meta written LAST = the sole commit point.
+ */
 class TiDBStagingHandle {
     pool;
     realSessionId;
     stagingId;
+    /** 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). */
     nextSeq = 0;
+    /** Entry ids already staged by THIS handle — a resume re-streams from the start, so dedup keeps seqs dense + idempotent. */
     seen = new Set();
     constructor(pool, realSessionId, stagingId) {
         this.pool = pool;
         this.realSessionId = realSessionId;
         this.stagingId = stagingId;
     }
+    /** 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). */
     async appendBatch(entries) {
+        // Build the NEW rows (skip already-staged ids — resume dedup keeps seqs dense), then ONE multi-row INSERT for the
+        // whole batch (bounded → bounded packet/txn) instead of N round-trips. ON DUPLICATE KEY UPDATE is the durable
+        // backstop for the rare case a dup slips past `seen` (e.g. a concurrent re-stream).
         const rows = [];
         const tuples = [];
         for (const e of entries) {
             if (this.seen.has(e.id))
                 continue;
             tuples.push("(?,?,?,?,?,?,?)");
+            // 对抗复查 A-1(CRITICAL):staging 行的 ts 必须是「行插入时间」——写源 entry 的历史 timestamp 会让
+            // reaper 的 MIN(ts)<cutoff 判据把「正在导入的历史会话」当成弃置 staging 删掉(导入 1 小时前的会话
+            // =导入中被 reap)。真时间源恒在 payload(e.timestamp);ts 列的唯一读消费=fork 的行拷贝(carry-over
+            // 一致)与 reaper 活性判据,写 now 零语义破坏。
             rows.push(this.stagingId, this.nextSeq, e.id, e.parentId ?? null, e.type, JSON.stringify(e), new Date());
             this.seen.add(e.id);
             this.nextSeq++;
@@ -317,22 +546,40 @@ class TiDBStagingHandle {
             throw err instanceof SessionError ? err : new SessionError("storage", `staged append for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
         }
     }
+    /**
+     * The ATOMIC swap (ONE txn), §15 commit:
+     *  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. INSERT/UPSERT session_meta(real, owner, leaf_id=replayedLeaf, leaf_seq=N) LAST = 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).
+     */
     async commit(owner, opts) {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
+            // (1) in-commit re-classify — read BOTH logs' ids oldest-first under FOR UPDATE (serialize against a racing
+            // commit/append to the dst). The staged ids ARE the source (already dense 0..N-1 under the staging id).
             const [stagedRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const [dstRows] = await conn.query("SELECT entry_id FROM session_event WHERE session_id = ? ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const [dstMeta] = await conn.query("SELECT 1 FROM session_meta WHERE session_id = ?", [this.realSessionId]);
             const srcIds = stagedRows.map((r) => String(r.entry_id));
-            const dstIds = dstMeta[0] ? dstRows.map((r) => String(r.entry_id)) : null;
+            const dstIds = dstMeta[0] ? dstRows.map((r) => String(r.entry_id)) : null; // no dst meta ⇒ fresh (no dst log to relate to)
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
             if ((rel.relation === "fork" || rel.relation === "stale") && opts?.resolution !== "overwrite-dst") {
                 await conn.rollback();
                 throw new SyncConflictError(this.realSessionId, rel);
             }
+            // (2) purge the dst's existing log (the replaceEntries purge; idempotent — fresh deletes 0).
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [this.realSessionId]);
+            // (3) RENAME the staged rows onto the real session id (row-key UPDATE — metadata only, NO payload re-copy). seq is
+            // already dense 0..N-1 under the staging id (appendBatch re-seq'd it), so no re-densify is needed on rename.
             await conn.query("UPDATE session_event SET session_id = ? WHERE session_id = ?", [this.realSessionId, this.stagingId]);
+            // (4) session_meta LAST = the sole commit point. The replayed leaf = the last staged entry's leaf target — read
+            // the last staged payload (now renamed) to compute leafIdAfterEntry (core's helper; no service re-statement).
             const [lastRow] = await conn.query("SELECT payload FROM session_event WHERE session_id = ? ORDER BY seq DESC LIMIT 1", [this.realSessionId]);
             let leafId = null;
             if (lastRow[0]) {
@@ -350,7 +597,7 @@ class TiDBStagingHandle {
             try {
                 await conn.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);
@@ -359,6 +606,7 @@ class TiDBStagingHandle {
             conn.release();
         }
     }
+    /** Drop the staging rows (Phase B aborted before commit). Idempotent (a missing staging id deletes 0). */
     async abort() {
         await this.pool.query("DELETE FROM session_event WHERE session_id = ?", [this.stagingId]);
     }

package/dist/plugins/tidb-tool-result-store.d.ts

@@ -1,3 +1,8 @@
+/**
+ * MySQL-protocol (TiDB) `ToolResultStore` — the implementation now lives in the single-file dual-dialect
+ * `tool-result-store-sql.ts` (design/158 A12 定型半场). This file is the historical import path: the class
+ * name and ctor shape are re-exported unchanged, so store-backend.ts and every suite are untouched.
+ */
 export { TiDBToolResultStore, SqlToolResultStore } from "./tool-result-store-sql.js";
 export { escapeLike } from "./sql-escape.js";
 //# sourceMappingURL=tidb-tool-result-store.d.ts.map

package/dist/plugins/tidb-tool-result-store.js

@@ -1,3 +1,10 @@
+/**
+ * MySQL-protocol (TiDB) `ToolResultStore` — the implementation now lives in the single-file dual-dialect
+ * `tool-result-store-sql.ts` (design/158 A12 定型半场). This file is the historical import path: the class
+ * name and ctor shape are re-exported unchanged, so store-backend.ts and every suite are untouched.
+ */
 export { TiDBToolResultStore, SqlToolResultStore } from "./tool-result-store-sql.js";
+// Back-compat re-export: escapeLike LIVES in sql-escape.ts (design/158 A3, backend-neutral leaf);
+// import from there in new code.
 export { escapeLike } from "./sql-escape.js";
 //# sourceMappingURL=tidb-tool-result-store.js.map

package/dist/plugins/tidb-workflow-journal-store.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 collapse). The real implementation is the single-file dual-dialect
+ * {@link import("./workflow-journal-store-sql.js").SqlWorkflowJournalStore} — see that file for the durable
+ * {@link WorkflowJournalStore} contract, the schema, and the TiDB/PG dialect-delta ledger. This name (and ctor
+ * arity: `(pool: MySqlPool)`) survives unchanged so every consumer (store-backend.ts, the extreme/integration/
+ * resume-fork-probe suites) is untouched.
+ */
 export { TiDBWorkflowJournalStore } from "./workflow-journal-store-sql.js";
 //# sourceMappingURL=tidb-workflow-journal-store.d.ts.map

package/dist/plugins/tidb-workflow-journal-store.js

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 collapse). The real implementation is the single-file dual-dialect
+ * {@link import("./workflow-journal-store-sql.js").SqlWorkflowJournalStore} — see that file for the durable
+ * {@link WorkflowJournalStore} contract, the schema, and the TiDB/PG dialect-delta ledger. This name (and ctor
+ * arity: `(pool: MySqlPool)`) survives unchanged so every consumer (store-backend.ts, the extreme/integration/
+ * resume-fork-probe suites) is untouched.
+ */
 export { TiDBWorkflowJournalStore } from "./workflow-journal-store-sql.js";
 //# sourceMappingURL=tidb-workflow-journal-store.js.map

package/dist/plugins/tidb-workflow-run-store.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Thin re-export shim (design/158 A12 扇出): the TiDB `WorkflowRunStore`/`WorkflowCompletionInbox`/
+ * `WorkflowNotifyJournalStore` twins now live collapsed with their PG dialect siblings in the
+ * single-file dual-dialect `workflow-run-store-sql.ts`. Class names, ctor arity, and the exported
+ * `MAX_RUN_BLOB_BYTES` / `slimOversizeRun` / `InboxWarn` surface stay EXACTLY as they were — every
+ * consumer (store-backend.ts, the DB-integration + slim-oversize-run suites) imports from THIS path
+ * unchanged.
+ */
 export { MAX_RUN_BLOB_BYTES, slimOversizeRun, type InboxWarn, TiDBWorkflowRunStore, TiDBWorkflowCompletionInbox, TiDBWorkflowNotifyJournalStore, } from "./workflow-run-store-sql.js";
 //# sourceMappingURL=tidb-workflow-run-store.d.ts.map