@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/tidb-pool.js

@@ -1,4 +1,12 @@
 import mysql from "mysql2/promise";
+/**
+ * Shared TiDB (MySQL wire-compatible) connection pool for the durable Session center (L1).
+ * Owned by `main.ts`; closed on shutdown.
+ *
+ * Read/write pool — this is the persistence center. (The SQL *tool* given to the model must use a
+ * separate read-only pool/credential; never hand this pool to a tool.)
+ */
+/** Build the mysql2 pool options from TiDB config (pure → unit-testable apart from the live connection). */
 export function tidbPoolOptions(tidb) {
     const { host, port, user, password, database, connectionLimit } = tidb;
     const limit = connectionLimit ?? 10;
@@ -13,7 +21,15 @@ export function tidbPoolOptions(tidb) {
         maxIdle: limit,
         idleTimeout: 60_000,
         enableKeepAlive: true,
+        // Bound the acquire backlog. With waitForConnections + the mysql2 default queueLimit:0 (unlimited), a TiDB
+        // stall makes EVERY db op queue without bound → all serving hangs indefinitely instead of failing fast. A
+        // finite limit (well above a normal burst) lets a sustained stall surface as errors the HTTP layer can map
+        // to 5xx, rather than an invisible hang. (Per-query timeouts are the deeper fix: mysql2 has NO pool-level
+        // knob — `timeout` is per-query `{sql, timeout}` only — so the S9 write-behind counter family carries its
+        // own per-query timeout (write-behind-counter.ts, DB_QUERY_TIMEOUT_MS overrides); the general query surface
+        // here keeps relying on this backlog bound. The PG pool DOES have the pool-wide knob — see pgPoolOptions.)
         queueLimit: limit * 32,
+        // Persist/return DATETIME in UTC so timestamps are stable across instances/timezones.
         timezone: "Z",
         charset: "utf8mb4",
     };
@@ -25,6 +41,26 @@ export function createTidbPool(config) {
     }
     return mysql.createPool(tidbPoolOptions(config.tidb));
 }
+/**
+ * Idempotent schema. `session_event` is the append-only L1 event log (positional slicing by
+ * `(session_id, seq)`); `session_meta` holds the branch leaf + the optimistic-lock counter
+ * (`leaf_seq`) + tenant `owner`.
+ *
+ * ── SCHEMA POLICY (clay 裁,2026-07-26) ─────────────────────────────────────────────────────────────
+ * 本仓 schema 的唯一真源 = **这份代码**(此数组 + `pg-pool.ts` 的 PG 孪生)。口径:
+ *
+ *  1. **删库重建,不做增量。** 尚未上生产、单人本地,存量库一律 DROP DATABASE 重建;因此这里**不再保留
+ *     任何 `ALTER TABLE` 增量 seam**。历史上的 21 条 ADD COLUMN / 3 条 CREATE INDEX / 1 条 MODIFY COLUMN
+ *     已于 2026-07-26 全部折进下面的 `CREATE TABLE`(它们承载的语义已逐条搬成列上的行内注释 —— 那些注释
+ *     是 pre-migration 行为契约的**唯一书面记录**,删注释 = 丢语义)。
+ *  2. **不许再新增 `ALTER TABLE` seam。** 要改列/加列/改可空性 ⇒ 直接改下面的 `CREATE TABLE`,然后重建库。
+ *     (再开增量通道就等于把「代码是真源」变回「代码 + 一串按时间排的补丁才是真源」。)
+ *  3. 生成的全集 SQL 基线导出到 `docs/schema/baseline-mysql.sql`(由本数组机器生成;它是**产物**,不是真源
+ *     —— 冲突时以本文件为准并重新生成)。
+ *
+ * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + image_bake_admit 种子行),只是语句数组现在是纯
+ * CREATE,不再有 information_schema 探针。
+ */
 export const SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS session_meta (
      session_id  VARCHAR(64)  NOT NULL,
@@ -50,6 +86,8 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, seq),
      UNIQUE KEY uk_entry (session_id, entry_id)
    )`,
+    // Async run registry (S1) + replayable event log (S2). Any instance can serve a run's status /
+    // event replay because both live here, not in a single instance's memory.
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64)  NOT NULL,
      session_id  VARCHAR(64)  NOT NULL,
@@ -98,6 +136,10 @@ export const SCHEMA_STATEMENTS = [
      -- ever served an operator's ad-hoc WHERE error_code LIKE 'budget.%', while every task_run write paid its
      -- maintenance cost. If you need that ad-hoc query, build the index temporarily and drop it after.
    )`,
+    // Cross-replica circuit-breaker state (1.38). A row per breaker key ("<provider>:<id>"); each
+    // replica write-through-caches its trips here and periodically refreshes so a provider outage is
+    // learned fleet-wide instead of every replica re-discovering it. Advisory / eventually consistent
+    // (last-writer-wins): the breaker is consultative, not a linearizable lock.
     `CREATE TABLE IF NOT EXISTS circuit_breaker (
      breaker_key VARCHAR(190) NOT NULL,
      phase       VARCHAR(16)  NOT NULL,
@@ -106,6 +148,9 @@ export const SCHEMA_STATEMENTS = [
      updated_at  DATETIME(3)  NOT NULL,
      PRIMARY KEY (breaker_key)
    )`,
+    // Cross-replica per-key CUMULATIVE cost quota (design/30 P0-1). One row per (scope_key, aligned window
+    // bucket); replicas atomically `micro = micro + delta` (write-behind aggregation), so spend is summed
+    // fleet-wide without losing increments. scope_key is opaque (principal today; team/feature later).
     `CREATE TABLE IF NOT EXISTS cost_quota (
      scope_key     VARCHAR(190) NOT NULL,
      window_bucket BIGINT       NOT NULL,
@@ -114,6 +159,8 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (scope_key, window_bucket),
      KEY idx_window (window_bucket)
    )`,
+    // Cross-replica per-key request rate limit (design/30 P0-2) — same write-behind-counter shape as
+    // cost_quota (one row per key+aligned-window, atomic n = n + delta). Soft fleet-wide limiting.
     `CREATE TABLE IF NOT EXISTS rate_limit (
      limit_key     VARCHAR(190) NOT NULL,
      window_bucket BIGINT       NOT NULL,
@@ -122,6 +169,10 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (limit_key, window_bucket),
      KEY idx_window (window_bucket)
    )`,
+    // Durable backing for offloaded large tool results (core 1.47/1.49). One row per offload ref
+    // (`tr_<sessionId>_<toolCallId>`, globally unique → PK); content is the full tool output moved out of
+    // context. Write-once (INSERT IGNORE); TTL-reaped by created_at (idx_created). LONGTEXT holds large
+    // file/diff reads. Lets an async run wake on any replica and still read_tool_result the full text.
     `CREATE TABLE IF NOT EXISTS tool_result (
      ref        VARCHAR(190) NOT NULL,
      content    LONGTEXT     NOT NULL,
@@ -137,6 +188,9 @@ export const SCHEMA_STATEMENTS = [
      ts       DATETIME(3) NOT NULL,
      PRIMARY KEY (task_id, seq)
    )`,
+    // Single-active-run-per-session claim. PRIMARY KEY(session_id) makes the claim a unique-key
+    // insert: TiDB enforces it even with no prior row (it lacks InnoDB gap locks, so a
+    // SELECT…FOR UPDATE on an empty match would NOT serialize two concurrent zero-prior createRuns).
     `CREATE TABLE IF NOT EXISTS task_active (
      session_id VARCHAR(64) NOT NULL,
      task_id    VARCHAR(64) NOT NULL,
@@ -144,6 +198,8 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id),
      KEY idx_task (task_id)
    )`,
+    // Human-in-the-loop approval gate (F4). A pending row is durable so an operator's decision can
+    // arrive on any instance; the instance running the task polls this row to release its wait.
     `CREATE TABLE IF NOT EXISTS approval (
      id          VARCHAR(64)  NOT NULL,
      task_id     VARCHAR(64)  NULL,
@@ -168,6 +224,9 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_scope_status (scope, status),
      KEY idx_status (status)
    )`,
+    // Durable-checkpoint (core 1.67 / design/45): a policy `ask` persisted as a suspended task so an operator
+    // can `resume` it from any replica. `checkpoint` = core's blob + CAS status; `outcome` persisted on resolve
+    // (R20 #1). Timestamps are epoch-ms BIGINT (the core Checkpoint uses ms numbers, not DATETIME).
     `CREATE TABLE IF NOT EXISTS checkpoint (
      token        VARCHAR(120) NOT NULL,
      scope        VARCHAR(190) NOT NULL,
@@ -223,12 +282,18 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_status_deadline (status, deadline),
      KEY idx_session_status (session_id, status)
    )`,
+    // Service-side resume rebuild inputs (DURABLE-CHECKPOINT-PLAN §4.4a): sessionId-keyed because core's
+    // put(token,cp) can't carry service scenario_ctx. GC'd by the reaper once its checkpoint is gone.
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
      session_id VARCHAR(190) NOT NULL,
      ctx        JSON         NOT NULL,
      updated_at BIGINT       NOT NULL,
      PRIMARY KEY (session_id)
    )`,
+    // E18 resume-at anchor map: the shell holds live E2 eventIds (never persisted by core); TaskSpec.resumeAt takes a
+    // persisted SessionTreeEntry.id. This is the service-owned eventId→entryId translation. Keyed (session_id,event_id)
+    // so resolve is a PK point-lookup; entry_id is the resolve target. owner = single-DB-fleet defense-in-depth (the
+    // session is already owner-gated at the route + scoped by session_id). GC'd with the session (E21 delete).
     `CREATE TABLE IF NOT EXISTS resume_anchor (
      session_id VARCHAR(64)  NOT NULL,
      event_id   VARCHAR(64)  NOT NULL,
@@ -238,6 +303,9 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, event_id),
      KEY idx_resume_anchor_session (session_id)
    )`,
+    // Per-session per-toolName approval exemption ("本会话不再询问") — an APPROVAL MEMORY the
+    // F4 ask-gate consults AFTER deny/neverAuto (both always win). tool_name is CANONICAL space. GC'd with
+    // the session (E21 delete). See docs/design/APPROVAL-SESSION-EXEMPTION.md.
     `CREATE TABLE IF NOT EXISTS approval_exemption (
      session_id VARCHAR(64)  NOT NULL,
      tool_name  VARCHAR(190) NOT NULL,
@@ -245,6 +313,12 @@ export const SCHEMA_STATEMENTS = [
      created_at DATETIME(3)  NOT NULL,
      PRIMARY KEY (session_id, tool_name)
    )`,
+    // SendUserFile server-side ledger (multi-tenant governance, 1.190.0 [768]②a second half): one row per issued
+    // link — the scope↔object mapping the HASHED key segment deliberately hides from URLs (per-tenant list/revoke
+    // handle). id = uuidv7 (time-ordered PK = the keyset cursor); scope = VERIFIED principal verbatim ("_" =
+    // single-user sentinel); object_key ≤ 207 chars by construction (prefix 9 + seg 32 + uuid 36 + name ≤128 + 2 slashes).
+    // No URL column by design (public track reconstructs from bucket+key; presigned URLs decay). See
+    // send-file-ledger.ts.
     `CREATE TABLE IF NOT EXISTS sendfile_link (
      id         VARCHAR(64)  NOT NULL,
      scope      VARCHAR(190) NOT NULL,
@@ -260,6 +334,16 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (id),
      KEY idx_sendfile_link_scope (scope, id)
    )`,
+    // E6 durable SessionPolicyStore — operator-tightened per-(session,principal) tool-permission rules (CAS-versioned
+    // tighten-only; core reads them at prepare-time, subtract-only). policy_key = sha256(JSON.stringify([sessionId,
+    // principal ?? null])) — the SHA of core's exact composite key: a FIXED 64-char PK (an arbitrary-length / JSON-
+    // escapable principal can't overflow it, and no PK collation/PAD pitfalls); undefined/null principal collapse to one
+    // row, "" stays distinct. session_id is kept as a column for the E21 deleteBySession purge + index. `principal` is
+    // stored DENORMALIZED (it is ALSO inside the sha256 policy_key) ONLY so 2c session-sync's listBySession can ENUMERATE
+    // a session's per-principal rows (the hash is one-way, so the principal can't be recovered from policy_key).
+    // It is NOT part of any key/uniqueness and does NOT participate in the CAS/tighten logic — putRules just writes it.
+    // NULL = the session-wide row (principal undefined). VARCHAR(190) bounds it (a longer/escapable principal still keys
+    // by the fixed-width hash; this column is enumeration-only, so a truncated value here can't corrupt lookups).
     `CREATE TABLE IF NOT EXISTS session_policy (
      policy_key CHAR(64)     NOT NULL,
      session_id VARCHAR(64)  NOT NULL,
@@ -275,6 +359,10 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (policy_key),
      KEY idx_session_policy_session (session_id)
    )`,
+    // E19 rewind-files — durable working-tree snapshots keyed by (scope=sessionId, snap_key=SessionTreeEntry.id; same
+    // entryId anchor as E18). A per-(scope,key) manifest of relPath→blob_hash + content-addressed blobs (deduped across
+    // all snapshots). core's captureManifest/applyManifest do the env walk/restore; this is just the durable persistence.
+    // Bounded by DEFAULT_SNAPSHOT_BOUNDS (≤2000 files / 64 MiB, skips .git/node_modules). GC'd with the session (E21).
     `CREATE TABLE IF NOT EXISTS snapshot_manifest (
      scope     VARCHAR(64)   NOT NULL,
      snap_key  VARCHAR(64)   NOT NULL,
@@ -283,6 +371,11 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_snapshot_manifest_sk (scope, snap_key),
      KEY idx_snapshot_manifest_blob (blob_hash)
    )`,
+    // `bytes` is NULLABLE: a SQL-backend row carries the bytes inline; a MinIO-backend row keeps ONLY the INDEX
+    // (blob_hash, byte_len, created_at) here with bytes NULL — the bytes live in MinIO. This INDEX row is what
+    // gcOrphanBlobs / reap / deleteBySession (E21 purge) / sweepOrphanBlobs read to compute the orphan/grace SET, so
+    // reference-tracking + the created_at grace window work IDENTICALLY for both backends (and an E21 purge can delete
+    // the MinIO object, not leak it). See blob-backend.ts MinioBlobBackend.
     `CREATE TABLE IF NOT EXISTS snapshot_blob (
      blob_hash  CHAR(64)    NOT NULL,
      byte_len   BIGINT      NOT NULL,
@@ -298,6 +391,12 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (blob_hash),
      KEY idx_snapshot_blob_created (created_at)
    )`,
+    // SVC-2 (core CORE-7) durable WorkflowJournalStore — the cross-replica resume journal for an LLM-authored workflow.
+    // One row per (run_id, ordinal): `ordinal` = core's callKeyOrdinal(callKey) (the positional replay index), `result`
+    // = JSON.stringify(TaskResult). The (run_id, ordinal) PK makes append IDEMPOTENT (ON DUPLICATE KEY = OVERWRITE /
+    // last-write-wins) so a resumed run re-appending its replayed prefix verbatim leaves no dup — the byte-match of
+    // core's InMemoryWorkflowJournalStore (byOrdinal.set). LOAD-BEARING (a resume replays it), unlike the best-effort
+    // task_event observation log. GC'd by the run reaper (deleteByRun). See tidb-workflow-journal-store.ts.
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id     VARCHAR(191) NOT NULL,
      ordinal    INT          NOT NULL,
@@ -313,6 +412,9 @@ export const SCHEMA_STATEMENTS = [
      created_at BIGINT       NOT NULL,
      PRIMARY KEY (run_id, ordinal)
    )`,
+    // RB-242 / WF2 ([1981] core 拍板 a 形):cross-replica workflow resume admission lease. PK (source_run_id, scope)
+    // = the bake-store idem_key precedent — the INSERT either wins the claim or collides with the current holder.
+    // TTL is the CRASH backstop only (engine releases on terminal via releaseResumeClaim); see workflow-journal-store-sql.ts.
     `CREATE TABLE IF NOT EXISTS workflow_resume_claim (
      source_run_id VARCHAR(191) NOT NULL,
      scope         VARCHAR(190) NOT NULL,
@@ -320,6 +422,9 @@ export const SCHEMA_STATEMENTS = [
      claimed_at    BIGINT       NOT NULL,
      PRIMARY KEY (source_run_id, scope)
    )`,
+    // P1 (fleet failover, 2026-07-05): durable cross-replica WorkflowRunStore twin — one row per run, the full
+    // WorkflowRun as a JSON blob + extracted index columns; `rev` column = the OCC authority (blob rev overlaid
+    // on read). MEDIUMTEXT (16MB) >> the 4MB write guard in the store.
     `CREATE TABLE IF NOT EXISTS workflow_run (
      id         VARCHAR(191) NOT NULL,
      scope      VARCHAR(190) NOT NULL,
@@ -332,6 +437,8 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_wfrun_scope_created (scope, created_at),
      KEY idx_wfrun_scope_status (scope, status)
    )`,
+    // P1: cross-replica workflow completion inbox (the push half). seq = insertion order (re-enqueue
+    // moves to tail via DELETE+INSERT). summary is bounded upstream (core notifier ≤4000).
     `CREATE TABLE IF NOT EXISTS workflow_completion_inbox (
      seq         BIGINT       NOT NULL AUTO_INCREMENT,
      session_id  VARCHAR(190) NOT NULL,
@@ -353,6 +460,9 @@ export const SCHEMA_STATEMENTS = [
      UNIQUE KEY uq_wfinbox_seq (seq),
      KEY idx_wfinbox_session_seq (session_id, seq)
    )`,
+    // P1: inbox fences AS ROWS — the actual point of the SQL port: a poll served on replica A must fence the
+    // late notify landing on replica B (cross-replica). kind = served (per-runId) | purge (run_id='',
+    // session-wide; owner_known=0 → conservative fence-all). Swept opportunistically on every write verb.
     `CREATE TABLE IF NOT EXISTS workflow_inbox_fence (
      session_id  VARCHAR(190) NOT NULL,
      kind        VARCHAR(8)   NOT NULL,
@@ -363,6 +473,10 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, kind, run_id),
      KEY idx_wffence_until (until_ms)
    )`,
+    // 1.108 review fix (lens③ HIGH): the notify JOURNAL twin — under WORKFLOW_RUN_STORE=auto the run store +
+    // inbox were SQL but the notify journal stayed a replica-LOCAL File ledger, so a replica that died with an
+    // un-acked notify stranded it forever (at-least-once silently degraded to at-most-once across replica death).
+    // One row per STARTED run; acked flips on delivery; the recovery sweep on ANY replica walks acked=0.
     `CREATE TABLE IF NOT EXISTS workflow_notify_journal (
      run_id         VARCHAR(191) NOT NULL,
      scope          VARCHAR(190) NOT NULL,
@@ -374,6 +488,13 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (run_id),
      KEY idx_wfnotify_acked (acked)
    )`,
+    // Outcome ledger (design/73 §7) — one row per graded task run, keyed by
+    // (task_signature, model). v1 is READ-ONLY (dashboard + offline-backtest source); it drives NO
+    // automatic policy change — that is flag-gated and must first pass an offline-backtest gate
+    // (council blocker 3 / major 7). The hard-signal split is structural, not a convention: `mechanical`
+    // columns (oracle/build/merge/cost/turns/route/replan) are the ONLY ones a future self-scheduler may
+    // read; `llm_assisted` (stuck/verifier) lives in its JSON blob, dashboard-only, never co-weighted.
+    // `outcome` is DERIVED from mechanical fields only (council blocker 1).
     `CREATE TABLE IF NOT EXISTS outcome_ledger (
      id             VARCHAR(64)  NOT NULL,
      task_signature VARCHAR(190) NOT NULL,
@@ -402,6 +523,8 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_outcome (outcome),
      KEY idx_created (created_at)
    )`,
+    // sandbox-image-pool control API (IMAGE-API-DESIGN.md §1 / pool design §8). One row per image DIGEST (the
+    // immutable runtime ref); a queryable projection of build.sh's replay-sufficient manifest + the publish lifecycle.
     `CREATE TABLE IF NOT EXISTS sandbox_image_index (
      id                 VARCHAR(64)  NOT NULL,
      profile            VARCHAR(64)  NOT NULL,
@@ -430,6 +553,12 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_digest (digest),
      KEY idx_tenant (tenant_id, status)
    )`,
+    // sandbox-image-pool BAKE job (IMAGE-API-DESIGN.md §P2.6). A dedicated row table — NOT a reuse of task_run
+    // (FK-coupled to task_active + the run reaper + /v1/runs list; co-mingling bakes would leak non-task rows into
+    // reapStale/listRuns). The reader polls the COARSE 4-value `status` (queued|running|done|failed) for SSE
+    // terminality; build.sh's 8-value `state` is denormalized for the UI progress bar ONLY and must NOT drive
+    // terminality (P2.3 MUST-FIX — a non-terminal PUSHING/VERIFYING state would truncate the stream before `done`).
+    // `argv` is the VETTED, normalized build.sh argv the runner runs (operator free-text never reaches the runner).
     `CREATE TABLE IF NOT EXISTS image_bake (
      bake_id          VARCHAR(64)  NOT NULL,
      profile          VARCHAR(128) NOT NULL,
@@ -463,6 +592,11 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_status (status),
      KEY idx_created (created_at)
    )`,
+    // Per-bake replayable event log (P2.6) — run-trace event-log mechanics ((id,seq) PK, ++seq, getEvents(after),
+    // maxSeq, retainedFrom→416, heartbeat-not-persisted) WITHOUT the task_event FK coupling. image-api is the SOLE
+    // ++seq writer (seq monotonic from 1). `line_ord` is the runner's per-line ordinal — the at-least-once ingest
+    // dedupe key (uq_line): a re-sent (bakeId,line_ord) is a no-op (P2.10). `level='raw'` rows are the opt-in
+    // build.log tail (?logs=1), pruned on a tighter TTL + evicted first (P2.5/P2.9).
     `CREATE TABLE IF NOT EXISTS image_bake_event (
      bake_id  VARCHAR(64) NOT NULL,
      seq      INT         NOT NULL,
@@ -474,6 +608,9 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (bake_id, seq),
      UNIQUE KEY uq_line (bake_id, line_ord)
    )`,
+    // Single-flight build lease (P2.7, §9). ONE row per builder pool — image-api owns the authoritative lease so the
+    // one docker daemon never has two concurrent builds (a prune-behind-lock could evict layers an in-flight build
+    // needs). `expires_at` makes a crashed-runner lease stealable (CAS on expiry).
     `CREATE TABLE IF NOT EXISTS image_bake_lease (
      pool        VARCHAR(32) NOT NULL DEFAULT 'standard',
      bake_id     VARCHAR(64) NOT NULL,
@@ -481,28 +618,52 @@ export const SCHEMA_STATEMENTS = [
      expires_at  DATETIME(3) NOT NULL,
      PRIMARY KEY (pool)
    )`,
+    // Admission sentinel: ONE always-present row per builder pool, `SELECT … FOR UPDATE`-locked to SERIALIZE the
+    // createBakeIfIdle busy-check+insert. A bare conditional INSERT…SELECT WHERE NOT EXISTS does NOT serialize two
+    // concurrent admissions under TiDB's REPEATABLE READ (nor PG's READ COMMITTED), so without this lock two keyless
+    // POSTs can both admit a non-dryRun bake. Dialect-uniform with the PG twin (pg-image-bake.ts).
     `CREATE TABLE IF NOT EXISTS image_bake_admit (
      pool VARCHAR(32) NOT NULL,
      PRIMARY KEY (pool)
    )`,
 ];
+/** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
+/** Acquire {@link ENSURE_SCHEMA_LOCK} on `conn` (the lock is CONNECTION-level, so the caller MUST then run all the
+ *  serialized work on this SAME connection and release with {@link releaseEnsureSchemaLock}). Returns whether it was
+ *  acquired. Exported so test setup that does ad-hoc DDL (e.g. a DROP-then-recreate) can serialize against
+ *  ensureSchema runs using the IDENTICAL lock.
+ *
+ *  Under heavy concurrency (the integration suite fans ~20 callers at the SAME named lock; or a fleet boots N
+ *  replicas at once) a BLOCKING GET_LOCK(name, 30) would park ~19 sessions in a pessimistic WAIT on TiDB's advisory-
+ *  lock row — which both exhausts TiDB's "pessimistic lock retry limit" (surfacing as a thrown error) AND starves the
+ *  app's OWN `SELECT … FOR UPDATE` paths (image-bake admission/lease) of pessimistic-lock budget. So we acquire
+ *  NON-BLOCKING (GET_LOCK(name, 0) returns 0 immediately if held) and POLL with jittered backoff: one holder, the
+ *  rest sleeping (not blocked in-DB). Return false only after exhausting retries (the caller then DEGRADES to
+ *  unserialized rather than blocking boot forever — the DDL is still individually idempotent). */
 export async function acquireEnsureSchemaLock(conn, tag = "ensureSchema") {
+    // Initial jitter so ~20 callers firing at t=0 (the integration fan-out, or a synchronized fleet boot) don't all
+    // hit the advisory-lock row in the same instant — that synchronized burst is what most provokes TiDB's pessimistic
+    // retry-limit. Spreading the first attempt over ~0.4s lets one win cleanly while the rest find it held and poll.
     await new Promise((r) => setTimeout(r, Math.floor(Math.random() * 400)));
     for (let attempt = 0; attempt < 40; attempt++) {
         try {
             const [rows] = await conn.query("SELECT GET_LOCK(?, 0) AS got", [ENSURE_SCHEMA_LOCK]);
             if (Number(rows[0]?.got) === 1)
-                return true;
+                return true; // acquired (0 = currently held by someone else → poll again)
         }
         catch (err) {
+            // A non-blocking GET_LOCK should not normally throw, but TiDB can still surface transient pessimistic-lock
+            // contention here — tolerate it (log + keep polling); the DDL is idempotent so a degrade is at worst benign.
             console.warn(`[${tag}] GET_LOCK('${ENSURE_SCHEMA_LOCK}') attempt ${attempt + 1}/40:`, err?.message ?? err);
         }
+        // Jittered backoff (~0.1s..0.4s + up to 0.15s jitter) — capped so total worst-case wait ≈ 40 * 0.4s = 16s.
         await new Promise((r) => setTimeout(r, 100 + Math.min(attempt, 3) * 100 + Math.floor(Math.random() * 150)));
     }
     console.warn(`[${tag}] could not acquire '${ENSURE_SCHEMA_LOCK}' after retries`);
     return false;
 }
+/** Release {@link ENSURE_SCHEMA_LOCK} on `conn` (best-effort — the lock also auto-frees when the connection closes). */
 export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
     try {
         await conn.query("SELECT RELEASE_LOCK(?)", [ENSURE_SCHEMA_LOCK]);
@@ -511,13 +672,32 @@ export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
         console.warn(`[${tag}] RELEASE_LOCK('${ENSURE_SCHEMA_LOCK}') failed (lock auto-frees on connection close):`, err);
     }
 }
+/** Create tables if absent (+ seed the image-bake admission sentinel). Safe to call on every startup.
+ *
+ *  Per the SCHEMA POLICY on {@link SCHEMA_STATEMENTS} this is a pure CREATE run — there are NO additive
+ *  ALTER/CREATE-INDEX seams and no information_schema probes any more (2026-07-26): the schema contract is
+ *  drop-and-recreate, so every column / index / nullability lives in its `CREATE TABLE`. Do not reintroduce a
+ *  migration loop here; change the CREATE and rebuild the database.
+ *
+ *  Concurrency: callers run this concurrently — tests fan ALL integration suites out in parallel (each
+ *  beforeAll calls ensureSchema), and in production every replica calls it at boot (`--scale service=4`).
+ *  Concurrent DDL on the SAME table makes TiDB race in its schema catalog. We serialize the entire run
+ *  behind {@link ENSURE_SCHEMA_LOCK} (a named GET_LOCK), which is CONNECTION-level — so the lock AND every
+ *  DDL statement run on the one connection we hold here (pooled `pool.query` could land on a different
+ *  connection and silently void the lock). The DDL semantics are unchanged; only the timing is serialized.
+ */
 export async function ensureSchema(pool) {
     const conn = await pool.getConnection();
+    // Serialize the whole DDL run behind the named connection-level lock (see acquireEnsureSchemaLock). The first
+    // caller does the real CREATEs, the rest wait then find every statement already satisfied (IF NOT EXISTS ⇒ no-op)
+    // → no catalog race. On a degrade (lock unavailable after retries) the DDL runs unserialized but every statement
+    // is still individually idempotent.
     const locked = await acquireEnsureSchemaLock(conn);
     try {
         for (const stmt of SCHEMA_STATEMENTS) {
             await conn.query(stmt);
         }
+        // Seed the always-present image-bake admission sentinel (idempotent) so createBakeIfIdle can FOR UPDATE-lock it.
         await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES ('standard')");
     }
     finally {

package/dist/plugins/tidb-rate-limiter.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Cross-replica per-key request rate limiter (design/30 P0-2) — a thin {@link RateGate} over the shared
+ * {@link WriteBehindCounter}. Like the in-memory {@link RateLimiter}, `check` both COUNTS the request
+ * and decides; here the count is summed fleet-wide via atomic write-behind aggregation.
+ *
+ * **SOFT limiting** (the WriteBehindCounter is eventually consistent): a replica may briefly admit a few
+ * requests over the ceiling at a window boundary before peers' counts propagate. That is fine for a
+ * fairness / hot-caller cap (the use case here). A HARD global cap would need a linearizable CAS, not
+ * write-behind — same trade as the cross-replica circuit breaker and cost quota.
+ */
 import type { Pool } from "mysql2/promise";
 import type { RateDecision, RateGate } from "../observability/rate-limit.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
@@ -6,6 +16,7 @@ export declare class TiDBRateLimiter implements RateGate {
     private readonly counter;
     constructor(pool: Pool, limit: number, windowMs?: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
     check(key: string): RateDecision;
+    /** The flush loop self-reaps old windows; the periodic sweeper has nothing to do for this backend. */
     sweep(): void;
     flush(): Promise<void>;
     refresh(): Promise<void>;

package/dist/plugins/tidb-rate-limiter.js

@@ -9,14 +9,17 @@ export class TiDBRateLimiter {
     check(key) {
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
-        const usedBefore = this.counter.used(key);
-        this.counter.addLocal(key, 1);
+        const usedBefore = this.counter.used(key); // fleet (last refresh) + local pending — soft/eventually consistent
+        this.counter.addLocal(key, 1); // count every request, like the in-memory limiter
         return usedBefore < this.limit
             ? { allowed: true, retryAfterSec: 0, remaining: this.limit - usedBefore - 1 }
             : { allowed: false, retryAfterSec: Math.max(1, this.counter.retryAfterSec()), remaining: 0 };
     }
+    /** The flush loop self-reaps old windows; the periodic sweeper has nothing to do for this backend. */
     sweep() {
+        /* no-op */
     }
+    // write-behind lifecycle (delegated; exposed for tests/parity)
     flush() {
         return this.counter.flush();
     }

package/dist/plugins/tidb-resume-anchor-store.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation moved to the single-file
+ * dual-dialect `resume-anchor-store-sql.ts` (shared with the PG twin via `SqlDriver`). Kept so
+ * consumers importing this path (store-backend.ts, the resume-anchor integration suite) don't move.
+ */
 export { TiDBResumeAnchorStore } from "./resume-anchor-store-sql.js";
 //# sourceMappingURL=tidb-resume-anchor-store.d.ts.map

package/dist/plugins/tidb-resume-anchor-store.js

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation moved to the single-file
+ * dual-dialect `resume-anchor-store-sql.ts` (shared with the PG twin via `SqlDriver`). Kept so
+ * consumers importing this path (store-backend.ts, the resume-anchor integration suite) don't move.
+ */
 export { TiDBResumeAnchorStore } from "./resume-anchor-store-sql.js";
 //# sourceMappingURL=tidb-resume-anchor-store.js.map

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

@@ -1,3 +1,10 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场 collapse): the real implementation now lives in
+ * `run-store-sql.ts` (single-file dual-dialect — TiDB + PG share one `SqlRunStore` body, dialect deltas
+ * kept EXPLICIT per statement). `TiDBRunStore`'s class name/ctor arity/exported types are unchanged so
+ * every existing consumer (store-backend.ts, src/index.ts, the run/reaper/session/usage suites) needs
+ * ZERO changes. New code should import from `run-store-sql.ts` directly.
+ */
 export { TiDBRunStore } from "./run-store-sql.js";
 export type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
 //# sourceMappingURL=tidb-run-store.d.ts.map

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

@@ -1,2 +1,9 @@
+/**
+ * Thin re-export shim (design/158 A12 定型半场 collapse): the real implementation now lives in
+ * `run-store-sql.ts` (single-file dual-dialect — TiDB + PG share one `SqlRunStore` body, dialect deltas
+ * kept EXPLICIT per statement). `TiDBRunStore`'s class name/ctor arity/exported types are unchanged so
+ * every existing consumer (store-backend.ts, src/index.ts, the run/reaper/session/usage suites) needs
+ * ZERO changes. New code should import from `run-store-sql.ts` directly.
+ */
 export { TiDBRunStore } from "./run-store-sql.js";
 //# sourceMappingURL=tidb-run-store.js.map

package/dist/plugins/tidb-session-policy-store.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation lives in the single-file
+ * dual-dialect `session-policy-store-sql.ts` (`SqlSessionPolicyStore` + this file's historical
+ * `TiDBSessionPolicyStore` ctor subclass). Kept so every consumer's import path is untouched.
+ */
 export { TiDBSessionPolicyStore } from "./session-policy-store-sql.js";
 //# sourceMappingURL=tidb-session-policy-store.d.ts.map

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

@@ -1,2 +1,7 @@
+/**
+ * Thin re-export shim (design/158 A12 收编) — the real implementation lives in the single-file
+ * dual-dialect `session-policy-store-sql.ts` (`SqlSessionPolicyStore` + this file's historical
+ * `TiDBSessionPolicyStore` ctor subclass). Kept so every consumer's import path is untouched.
+ */
 export { TiDBSessionPolicyStore } from "./session-policy-store-sql.js";
 //# sourceMappingURL=tidb-session-policy-store.js.map

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

@@ -1,17 +1,60 @@
 import { BaseSessionStorage, type PromptEpochDescriptor, type SessionMetadata, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
+/**
+ * TiDB-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
+ *
+ * - `appendEntry` / `setLeafId` persist with an **atomic compare-and-set** on `leaf_seq` + `leaf_id`
+ *   (core's F2 optimistic-lock seam): a write only lands if the branch leaf is still what the entry
+ *   was built against. Two stateless runners that both woke the same session can't silently fork —
+ *   the loser gets `SessionError("conflict")` (catch with `isSessionConflict`).
+ * - The in-memory base tree is the wake-time snapshot; every write is also mirrored into it so the
+ *   live harness keeps reading a consistent view. Wake is **bounded** to `[floor .. leaf]` (F3,
+ *   core 1.6.0 branch-floor seam); older history is covered by the last compaction's summary.
+ */
 export declare class TiDBSessionStorage extends BaseSessionStorage {
     private readonly pool;
     private readonly sessionId;
     private leafSeq;
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, leafSeq: number, floorEntryId?: string | null, floorSeq?: number);
+    /**
+     * [976] S3 RB-14 pull seam — `SessionStorage.getEpochAnchor?()`: the nearest epoch carrier BELOW the
+     * bounded-wake floor. core's `Session.getPromptEpoch()` (≥1.305) calls this only when the in-window
+     * branch walk finds no carrier — i.e. a rewind/resumeAt cut inside the kept tail, where the compaction
+     * restatement is a DESCENDANT of the cut and the root pin sits under the floor. Semantics per core's
+     * ruling: highest-seq valid carrier below the floor (not an ancestor-chain walk — fallback of last
+     * resort); malformed rows are skipped (#13: fall back to the older valid pin — the write gate refuses
+     * malformed carriers, so these only exist via out-of-band writes); none ⇒ undefined = a genuine
+     * pre-epoch session (core mints legacy_migration, the correct meaning). core re-normalizes whatever we
+     * return, so this stays honest even if the two sides ever disagree on strictness.
+     */
     getEpochAnchor(): Promise<PromptEpochDescriptor | undefined>;
+    /**
+     * Rebuild a session from its event log (= wake). Returns null if the session does not exist.
+     *
+     * F3 bounded load: only `[floor .. leaf]` is read, where floor = the last compaction's
+     * `firstKeptEntryId` (everything older is represented by that compaction's summary, so it never
+     * enters context). No compaction yet → floor=null → full load (the session is still short).
+     *
+     * This is the durable, bounded-READ equivalent of core's `boundedTail(pathEntries)` (1.42.0): that
+     * helper trims a FULL-loaded path in memory, whereas we compute the floor seq first and only `SELECT
+     * seq >= floorSeq` — so the head never leaves cold storage. Our sessions are LINEAR (no fork), so
+     * seq-order == root→leaf path-order and our `seq >= floorSeq` tail is byte-identical to
+     * `boundedTail(path).tail`; the resulting floored `BaseSessionStorage.buildContext()` matches a
+     * full-tree wake (core's `session-floor.test.ts`). If branching is ever added, switch to `boundedTail`.
+     */
     static wake(pool: Pool, sessionId: string): Promise<TiDBSessionStorage | null>;
+    /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). */
     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, which we translate to a conflict too.
+     */
     private persist;
 }
 //# sourceMappingURL=tidb-session-storage.d.ts.map