@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/tidb-pool.js

@@ -4,14 +4,6 @@ import { TIDB_LEADER_RUN_STATEMENTS } from "./leader-run-store-sql.js";
 import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
-/**
- * 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;
@@ -26,15 +18,7 @@ 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",
     };
@@ -46,26 +30,6 @@ 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,
@@ -105,8 +69,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, seq),
      UNIQUE KEY uq_session_event_entry (session_id, entry_id)
    ) COLLATE utf8mb4_bin`,
-    // 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 (
      -- ⚠️ 表级 COLLATE 的**非键列**影响(#192 A11,codex 复审 2026-08-08 round2 点名——先前"只有
      -- outcome_ledger 有聚合语义变化"的说法过窄,如实更正):
@@ -169,10 +131,6 @@ 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.
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -181,9 +139,6 @@ export const SCHEMA_STATEMENTS = [
      updated_at  DATETIME(3)  NOT NULL,
      PRIMARY KEY (breaker_key)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -192,8 +147,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (scope_key, window_bucket),
      KEY idx_cost_quota_window (window_bucket)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -202,15 +155,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (limit_key, window_bucket),
      KEY idx_rate_limit_window (window_bucket)
    ) COLLATE utf8mb4_bin`,
-    // Durable backing for offloaded large tool results (core 1.47/1.49). One row per offload ref
-    // (`tr_<sessionId>~<toolCallId>~<contentSeg>` since core 5.26.0 #119, 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.
-    // #119(core 5.26.0 提货):`ref` 从 VARCHAR(190) 抬到 518 = core 导出的 `MAX_MINTED_TOOL_RESULT_REF_CHARS`
-    // (`"tr_"` + 四段 × 128 + 三个 `~` 分隔),并新增 #119 出处两列(NULL = 该行无属主,读面 fail-closed)。
-    // 抬宽不是保守裕度:core 的 d.ts 逐字点名过旧宽度(「TiDB's was VARCHAR(191), which a long three-segment
-    // ref overruns — a truncating key aliases distinct refs」)—— 截断的主键会把两枚不同的 ref 折成同一行,
-    // 于是 A 的产物能从 B 的 ref 读出来。utf8mb4 下 518 字符 = 2072 字节,仍在 InnoDB/TiDB 3072 字节键长内。
     `CREATE TABLE IF NOT EXISTS tool_result (
      ref              VARCHAR(518) NOT NULL,
      content          LONGTEXT     NOT NULL,
@@ -228,9 +172,6 @@ export const SCHEMA_STATEMENTS = [
      ts       DATETIME(3) NOT NULL,
      PRIMARY KEY (task_id, seq)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -238,11 +179,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id),
      KEY idx_task_active_task (task_id)
    ) COLLATE utf8mb4_bin`,
-    // ([2354]/[2356] A-5,5.0.0:F4 轮询车道的 `approval` 表 DDL 已随车道退役——存量库里的旧表留置不动,
-    //  代码零读写;durable 门只用下面的 checkpoint 表。)
-    // 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,
@@ -325,18 +261,12 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_checkpoint_status_deadline (status, deadline),
      KEY idx_checkpoint_session_status (session_id, status)
    ) COLLATE utf8mb4_bin`,
-    // 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_ms BIGINT       NOT NULL,
      PRIMARY KEY (session_id)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -346,9 +276,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, event_id),
      KEY idx_resume_anchor_session (session_id)
    ) COLLATE utf8mb4_bin`,
-    // 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 sema-internal server/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,
@@ -356,12 +283,6 @@ export const SCHEMA_STATEMENTS = [
      created_at DATETIME(3)  NOT NULL,
      PRIMARY KEY (session_id, tool_name)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -377,16 +298,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (id),
      KEY idx_sendfile_link_scope (scope, id)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -402,10 +313,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (policy_key),
      KEY idx_session_policy_session (session_id)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -414,11 +321,6 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_snapshot_manifest_sk (scope, snap_key),
      KEY idx_snapshot_manifest_blob (blob_hash)
    ) COLLATE utf8mb4_bin`,
-    // `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,
@@ -434,12 +336,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (blob_hash),
      KEY idx_snapshot_blob_created (created_at)
    ) COLLATE utf8mb4_bin`,
-    // 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 workflow-journal-store-sql.ts.
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id        VARCHAR(191) NOT NULL,
      ordinal       INT          NOT NULL,
@@ -455,9 +351,6 @@ export const SCHEMA_STATEMENTS = [
      created_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (run_id, ordinal)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -465,9 +358,6 @@ export const SCHEMA_STATEMENTS = [
      claimed_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (source_run_id, scope)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -480,8 +370,6 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_wfrun_scope_created (scope, created_at_ms),
      KEY idx_wfrun_scope_status (scope, status)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -503,9 +391,6 @@ export const SCHEMA_STATEMENTS = [
      UNIQUE KEY uq_wfinbox_seq (seq),
      KEY idx_wfinbox_session_seq (session_id, seq)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -516,10 +401,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (session_id, kind, run_id),
      KEY idx_wffence_until (until_ms)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -531,13 +412,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (run_id),
      KEY idx_wfnotify_acked (acked)
    ) COLLATE utf8mb4_bin`,
-    // 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,
      -- ⚠️ 表级 COLLATE 对本表**不只是钉住隔离键**(#192 A11,codex 复审 2026-08-08 点名):下面两列是
@@ -572,8 +446,6 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_outcome_ledger_outcome (outcome),
      KEY idx_outcome_ledger_created (created_at)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -602,12 +474,6 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_sandbox_image_index_digest (digest),
      KEY idx_sandbox_image_index_tenant (tenant_id, status)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -641,11 +507,6 @@ export const SCHEMA_STATEMENTS = [
      KEY idx_image_bake_status (status),
      KEY idx_image_bake_created (created_at)
    ) COLLATE utf8mb4_bin`,
-    // 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_image_bake_event_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,
@@ -657,9 +518,6 @@ export const SCHEMA_STATEMENTS = [
      PRIMARY KEY (bake_id, seq),
      UNIQUE KEY uq_image_bake_event_line (bake_id, line_ord)
    ) COLLATE utf8mb4_bin`,
-    // 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,
@@ -667,27 +525,12 @@ export const SCHEMA_STATEMENTS = [
      expires_at  DATETIME(3) NOT NULL,
      PRIMARY KEY (pool)
    ) COLLATE utf8mb4_bin`,
-    // 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 (image-bake-store-sql.ts).
     `CREATE TABLE IF NOT EXISTS image_bake_admit (
      pool VARCHAR(32) NOT NULL,
      PRIMARY KEY (pool)
    ) COLLATE utf8mb4_bin`,
-    // #151(design/172)流内审批协议持久层的两张表。真源 = approval-ask-store-sql.ts 的
-    // `TIDB_APPROVAL_ASK_STATEMENTS`(那里与 PG twin 并排,方言差异一眼可对);展开进这个数组是为了让它们
-    // 跟着中央 `ensureSchema` 在 **named-lock 的那条 conn** 上建 —— 把 pool 级 ensure 函数塞进执行循环
-    // 会绕开 DDL 串行化。挂进来同时也是「这张表算生产 schema」的声明(基线导出按定义只收录被执行的语句)。
     ...TIDB_APPROVAL_ASK_STATEMENTS,
-    // #193 车4 件1(台账 P1-9):durable leader-run 登记表。真源 = leader-run-store-sql.ts 的
-    // `TIDB_LEADER_RUN_STATEMENTS`(那里与 PG twin 并排)。展开进这里的理由与上面 approval-ask 一条不差:
-    // 跟着中央 `ensureSchema` 在 named-lock 的那条 conn 上建,并声明「这张表算生产 schema」(基线导出按
-    // 定义只收录被执行的语句)。
     ...TIDB_LEADER_RUN_STATEMENTS,
-    // design/177 shared-memory store(#192 单数纪律)—— org 盘的三张表。消费面 = shared-memory-store-sql.ts。
-    // 🔴 与 `agent_memory_engine_*`(design/138 本地记忆链)**零关系**:不 join、不共享 scope 登记、不互写
-    // (设计 182 §13)。两族同库不同面,合表/建视图会让 harvest 的私人笔记漏进团队库。
     `CREATE TABLE IF NOT EXISTS shared_memory_scope (
      -- 一个 org scope 一行。行缺席 = 该 org 从未开通 ⇒ 语义等价于 connected 且零 store(不是故障)。
      scope_key     VARCHAR(190) NOT NULL,
@@ -721,57 +564,27 @@ export const SCHEMA_STATEMENTS = [
      updated_at_ms  BIGINT       NOT NULL,
      PRIMARY KEY (store_id, path)
    ) COLLATE utf8mb4_bin`,
-    // design/183 form b(纯身份重绑)的 **SQL 收编日志**。真源 = adoption-log-sql.ts 的
-    // `TIDB_ADOPTION_LOG_STATEMENTS`(与 PG twin 并排);展开进来的理由与 approval-ask 同款:
-    // 跟着中央 ensureSchema 在 named-lock 的那条 conn 上建,不绕开 DDL 串行化。
-    // 🔴 它**必须**与被迁的行同库(183 I2):phase 真源住别处 ⇒ 发起 host 被摧毁时与半迁移状态分家。
     ...TIDB_ADOPTION_LOG_STATEMENTS,
-    // #154 车二(core 5.18.0 design/179 + 5.22.0 design/182)持久化权限规则店的三张表。真源 =
-    // permission-rule-store-sql.ts 的 `TIDB_PERMISSION_RULE_STATEMENTS`(与 PG twin 并排);展开进这个
-    // 数组的理由与上面那族逐字相同(named-lock 的那条 conn + 「这张表算生产 schema」的声明)。
     ...TIDB_PERMISSION_RULE_STATEMENTS,
-    // #270 车1(托管留存执行面)的四张表:审计(§6)/ hold(§5)/ sweep 租约(§3)/ 墓碑(§2)。真源 =
-    // retention-store-sql.ts 的 `TIDB_RETENTION_STATEMENTS`(与 PG twin 并排);展开进这个数组的理由与
-    // 上面那几族逐字相同(named-lock 的那条 conn + 「这张表算生产 schema」的声明)。
     ...TIDB_RETENTION_STATEMENTS,
 ];
-/** 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; // acquired (0 = currently held by someone else → poll again)
+                return true;
         }
         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]);
@@ -780,32 +593,13 @@ 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.js

@@ -1,9 +1,7 @@
 import { WriteBehindCounter } from "./write-behind-counter.js";
 export class TiDBRateLimiter {
     counter;
-    /** 🔴 #322:限额是比较参数、不是行状态(SQL 腿的行里只有计数),所以换代只动它,库里一行都不用碰。 */
     limit;
-    /** 装配点表达过的运维意图(「这条腿该有刷新环」)。关断哨兵靠它把环真正停掉/重开 —— 0 态零 SQL。 */
     refreshRequested = false;
     refreshIntervalMs;
     constructor(pool, limit, windowMs = 60_000, now, onDegraded, queryTimeoutMs) {
@@ -14,7 +12,6 @@ export class TiDBRateLimiter {
         this.limit = next.rateLimitPerMin;
         this.syncRefresh();
     }
-    /** off ⇒ 停环(零 SQL);on 且装配点要过环 ⇒ 起环(幂等,counter 内部 `??=`)。 */
     syncRefresh() {
         if (!this.refreshRequested)
             return;
@@ -26,17 +23,14 @@ export class TiDBRateLimiter {
     check(key) {
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
-        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
+        const usedBefore = this.counter.used(key);
+        this.counter.addLocal(key, 1);
         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();
     }
@@ -46,7 +40,7 @@ export class TiDBRateLimiter {
     startRefresh(intervalMs) {
         this.refreshRequested = true;
         this.refreshIntervalMs = intervalMs;
-        this.syncRefresh(); // 关断态下**不起环**:恒构造的代价必须是零 SQL,否则「默认部署」白付一条后台环
+        this.syncRefresh();
         return this;
     }
     stop() {