@sema-agent/server 7.82.1 → 7.84.0

package/dist/plugins/pg-pool.js

@@ -1,5 +1,6 @@
 import pg from "pg";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
 import { ensureSchema as ensureSessionSchema } from "./pg-session-storage.js";
 import { ensureSchema as ensureToolResultSchema } from "./tool-result-store-sql.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
@@ -15,6 +16,8 @@ import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
 import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
 import { ensurePgRetentionSchema } from "./retention-store-sql.js";
+import { ensureIndexes } from "./ensure-index.js";
+import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 export const PG_SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS task_run (
      task_id     VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -43,10 +46,6 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at  TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (task_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_task_run_session_status ON task_run (session_id, status)`,
-    `CREATE INDEX IF NOT EXISTS idx_task_run_owner ON task_run (owner)`,
-    `CREATE INDEX IF NOT EXISTS idx_task_run_created ON task_run (created_at)`,
-    `CREATE INDEX IF NOT EXISTS idx_task_run_job ON task_run (job_id)`,
     `CREATE TABLE IF NOT EXISTS task_event (
      task_id VARCHAR(64) COLLATE "C" NOT NULL,
      seq     BIGINT      NOT NULL,
@@ -61,7 +60,6 @@ export const PG_SCHEMA_STATEMENTS = [
      since      TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (session_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_task_active_task ON task_active (task_id)`,
     `CREATE TABLE IF NOT EXISTS checkpoint (
      token        VARCHAR(120) COLLATE "C" NOT NULL,
      scope        VARCHAR(190) COLLATE "C" NOT NULL,
@@ -101,8 +99,6 @@ export const PG_SCHEMA_STATEMENTS = [
      execution_at_ms   BIGINT,
      PRIMARY KEY (token)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_checkpoint_status_deadline ON checkpoint (status, deadline)`,
-    `CREATE INDEX IF NOT EXISTS idx_checkpoint_session_status ON checkpoint (session_id, status)`,
     `CREATE TABLE IF NOT EXISTS checkpoint_ctx (
      session_id    VARCHAR(190) COLLATE "C" NOT NULL,
      ctx           JSONB        NOT NULL,
@@ -117,7 +113,6 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (session_id, event_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_resume_anchor_session ON resume_anchor (session_id)`,
     `CREATE TABLE IF NOT EXISTS approval_exemption (
      session_id VARCHAR(64) COLLATE "C"    NOT NULL,
      tool_name  VARCHAR(190) COLLATE "C"   NOT NULL,
@@ -132,7 +127,6 @@ export const PG_SCHEMA_STATEMENTS = [
      expires_at_ms  BIGINT         NOT NULL,
      PRIMARY KEY (session_id, nonce)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_approval_nonce_expires ON approval_nonce (expires_at_ms)`,
     `CREATE TABLE IF NOT EXISTS sendfile_link (
      id         VARCHAR(64) COLLATE "C"    NOT NULL,
      scope      VARCHAR(190) COLLATE "C"   NOT NULL,
@@ -147,7 +141,6 @@ export const PG_SCHEMA_STATEMENTS = [
      created_at TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_sendfile_link_scope ON sendfile_link (scope, id)`,
     `CREATE TABLE IF NOT EXISTS session_policy (
      policy_key CHAR(64) COLLATE "C"       NOT NULL,
      session_id VARCHAR(64) COLLATE "C"    NOT NULL,
@@ -161,7 +154,6 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (policy_key)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_session_policy_session ON session_policy (session_id)`,
     `CREATE TABLE IF NOT EXISTS snapshot_blob (
      blob_hash  CHAR(64) COLLATE "C"       PRIMARY KEY,
      byte_len   BIGINT         NOT NULL,
@@ -174,7 +166,6 @@ export const PG_SCHEMA_STATEMENTS = [
      bytes      BYTEA          NULL,
      created_at TIMESTAMPTZ(3) NOT NULL
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_snapshot_blob_created ON snapshot_blob (created_at)`,
     `CREATE TABLE IF NOT EXISTS file_history_scope (
      scope         VARCHAR(64) COLLATE "C" NOT NULL,
      created_at_ms BIGINT                  NOT NULL,
@@ -201,7 +192,6 @@ export const PG_SCHEMA_STATEMENTS = [
      backup_time  VARCHAR(40) COLLATE "C" NOT NULL,
      PRIMARY KEY (scope, key_hash, version)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_file_history_version_blob ON file_history_version (blob_hash)`,
     `CREATE TABLE IF NOT EXISTS file_history_boundary (
      scope           VARCHAR(64) COLLATE "C" NOT NULL,
      entry_id        VARCHAR(64) COLLATE "C" NOT NULL,
@@ -217,7 +207,6 @@ export const PG_SCHEMA_STATEMENTS = [
      version  INT                     NOT NULL,
      PRIMARY KEY (scope, entry_id, key_hash)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_file_history_bf_key ON file_history_boundary_file (scope, key_hash)`,
     `CREATE TABLE IF NOT EXISTS file_history_reaped_entry (
      scope        VARCHAR(64) COLLATE "C" NOT NULL,
      entry_id     VARCHAR(64) COLLATE "C" NOT NULL,
@@ -231,7 +220,6 @@ export const PG_SCHEMA_STATEMENTS = [
      bytes      BYTEA          NULL,
      created_at TIMESTAMPTZ(3) NOT NULL
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_file_history_blob_created ON file_history_blob (created_at)`,
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id        VARCHAR(191) COLLATE "C" NOT NULL,
      ordinal       INT          NOT NULL,
@@ -263,8 +251,6 @@ export const PG_SCHEMA_STATEMENTS = [
      ended_at_ms   BIGINT,
      PRIMARY KEY (id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_wfrun_scope_created ON workflow_run (scope, created_at_ms)`,
-    `CREATE INDEX IF NOT EXISTS idx_wfrun_scope_status ON workflow_run (scope, status)`,
     `CREATE TABLE IF NOT EXISTS workflow_agent_session (
      session_id VARCHAR(190) COLLATE "C" NOT NULL,
      run_id     VARCHAR(191) COLLATE "C" NOT NULL,
@@ -272,7 +258,6 @@ export const PG_SCHEMA_STATEMENTS = [
      scope      VARCHAR(190) COLLATE "C" NOT NULL,
      PRIMARY KEY (session_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_wfagentsess_run ON workflow_agent_session (run_id)`,
     `CREATE TABLE IF NOT EXISTS workflow_completion_inbox (
      seq            BIGSERIAL,
      session_id     VARCHAR(190) COLLATE "C" NOT NULL,
@@ -295,7 +280,6 @@ export const PG_SCHEMA_STATEMENTS = [
      -- becomes MACHINE-ENFORCED rather than merely conventional, in both engines.
      CONSTRAINT uq_wfinbox_seq UNIQUE (seq)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_wfinbox_session_seq ON workflow_completion_inbox (session_id, seq)`,
     `CREATE TABLE IF NOT EXISTS workflow_inbox_fence (
      session_id  VARCHAR(190) COLLATE "C" NOT NULL,
      kind        VARCHAR(8) COLLATE "C"   NOT NULL,
@@ -305,7 +289,6 @@ export const PG_SCHEMA_STATEMENTS = [
      until_ms    BIGINT       NOT NULL,
      PRIMARY KEY (session_id, kind, run_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_wffence_until ON workflow_inbox_fence (until_ms)`,
     `CREATE TABLE IF NOT EXISTS workflow_notify_journal (
      run_id         VARCHAR(191) COLLATE "C" NOT NULL,
      scope          VARCHAR(190) COLLATE "C" NOT NULL,
@@ -316,7 +299,6 @@ export const PG_SCHEMA_STATEMENTS = [
      acked_at_ms    BIGINT,
      PRIMARY KEY (run_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_wfnotify_acked ON workflow_notify_journal (acked)`,
     `CREATE TABLE IF NOT EXISTS shared_memory_scope (
      scope_key     VARCHAR(190) COLLATE "C" NOT NULL,
      state         VARCHAR(16) COLLATE "C"  NOT NULL,
@@ -332,7 +314,6 @@ export const PG_SCHEMA_STATEMENTS = [
      updated_at_ms BIGINT       NOT NULL,
      PRIMARY KEY (store_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_shared_memory_store_scope ON shared_memory_store (scope_key, store_id)`,
     `CREATE TABLE IF NOT EXISTS shared_memory_entry (
      store_id       VARCHAR(64) COLLATE "C"  NOT NULL,
      path           VARCHAR(512) COLLATE "C" NOT NULL,
@@ -400,17 +381,26 @@ export function createPgPool(opts, onIdleClientError) {
     return pool;
 }
 export const ENSURE_SCHEMA_LOCK_KEY = 4906;
+export async function acquirePgEnsureSchemaLock(client, tag) {
+    await pollUntilLocked(async () => {
+        const res = await client.query("SELECT pg_try_advisory_lock($1) AS got", [ENSURE_SCHEMA_LOCK_KEY]);
+        return res.rows[0]?.got === true;
+    }, { tag, label: `pg advisory lock ${ENSURE_SCHEMA_LOCK_KEY}` });
+}
+export async function releasePgEnsureSchemaLock(client, tag) {
+    try {
+        await client.query("SELECT pg_advisory_unlock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
+    }
+    catch (err) {
+        console.warn(`[${tag}] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (lock auto-frees on connection close):`, err);
+    }
+}
 export async function ensurePgSchema(pool) {
     const client = await pool.connect();
     let locked = false;
     try {
-        try {
-            await client.query("SELECT pg_advisory_lock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
-            locked = true;
-        }
-        catch (err) {
-            console.warn(`[ensurePgSchema] pg_advisory_lock(${ENSURE_SCHEMA_LOCK_KEY}) failed; running DDL unserialized:`, err);
-        }
+        await acquirePgEnsureSchemaLock(client, "ensurePgSchema");
+        locked = true;
         for (const stmt of PG_SCHEMA_STATEMENTS)
             await client.query(stmt);
         await ensureSessionSchema(client);
@@ -428,16 +418,11 @@ export async function ensurePgSchema(pool) {
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
         await ensurePgLeaderRunSchema((text, params) => client.query(text, params));
         await ensurePgRetentionSchema((text, params) => client.query(text, params));
+        await ensureIndexes((text, params) => client.query(text, params), "pg", CENTRAL_SCHEMA_INDEXES);
     }
     finally {
-        if (locked) {
-            try {
-                await client.query("SELECT pg_advisory_unlock($1)", [ENSURE_SCHEMA_LOCK_KEY]);
-            }
-            catch (err) {
-                console.warn(`[ensurePgSchema] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (lock auto-frees on connection close):`, err);
-            }
-        }
+        if (locked)
+            await releasePgEnsureSchemaLock(client, "ensurePgSchema");
         client.release();
     }
 }

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

@@ -16,6 +16,7 @@
 import type { Pool, PoolClient } from "pg";
 import type { RateDecision, RateGate, RateLimits } from "../observability/rate-limit.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
+import { type IndexSpec } from "./ensure-index.js";
 export declare class PgRateLimiter implements RateGate {
     private readonly counter;
     /** [ref]:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
@@ -39,6 +40,8 @@ export declare class PgRateLimiter implements RateGate {
  * atomic ON CONFLICT increment.
  */
 export declare const PG_RATE_LIMITER_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const RATE_LIMIT_INDEXES: readonly IndexSpec[];
 /** Self-contained schema bootstrap for tests (the rate_limit table is disjoint from other stores). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
 //# sourceMappingURL=pg-rate-limiter.d.ts.map

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

@@ -1,4 +1,5 @@
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
+import { ensureIndexes } from "./ensure-index.js";
 const RATE_LIMIT_TABLE = { table: "rate_limit", keyCol: "limit_key", valCol: "hits" };
 export class PgRateLimiter {
     counter;
@@ -57,10 +58,13 @@ export const PG_RATE_LIMITER_SCHEMA = [
      updated_at    TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (limit_key, window_bucket)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_rate_limit_window ON rate_limit (window_bucket)`,
+];
+export const RATE_LIMIT_INDEXES = [
+    { table: "rate_limit", name: "idx_rate_limit_window", columns: ["window_bucket"] },
 ];
 export async function ensureSchema(pool) {
     for (const stmt of PG_RATE_LIMITER_SCHEMA)
         await pool.query(stmt);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", RATE_LIMIT_INDEXES);
 }
 //# sourceMappingURL=pg-rate-limiter.js.map

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

@@ -3,6 +3,7 @@ import type { Pool, PoolClient } from "pg";
 import type { SessionSummary } from "./store-contracts.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
+import { type IndexSpec } from "./ensure-index.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
  * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), inline `KEY`/`UNIQUE KEY`→separate CREATE INDEX (UNIQUE for uq_session_event_entry).
@@ -11,6 +12,8 @@ import { type StagingHandle } from "../session-sync-kernel.js";
  * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_SESSION_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const SESSION_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for this store's tables (the test calls this; production aggregation is separate). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
 /**

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

@@ -8,6 +8,7 @@ import { contentForkRelation, fastForwardSharedContentDiverged } from "../sessio
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "./sql-errors.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
+import { ensureIndexes } from "./ensure-index.js";
 const isDupKey = isPgUniqueViolation;
 function parseEntry(p) {
     return (typeof p === "string" ? JSON.parse(p) : p);
@@ -36,8 +37,6 @@ export const PG_SESSION_SCHEMA = [
      placed_at                   TIMESTAMPTZ(3),
      PRIMARY KEY (session_id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_session_meta_owner ON session_meta (owner)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_meta_placement ON session_meta (placement_kind, placement_scope, placed_at)`,
     `CREATE TABLE IF NOT EXISTS session_event (
      session_id  VARCHAR(64) COLLATE "C" NOT NULL,
      seq         BIGINT      NOT NULL,
@@ -48,12 +47,17 @@ export const PG_SESSION_SCHEMA = [
      ts          TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (session_id, seq)
    )`,
-    `CREATE UNIQUE INDEX IF NOT EXISTS uq_session_event_entry ON session_event (session_id, entry_id)`,
-    `CREATE INDEX IF NOT EXISTS idx_session_event_type ON session_event (session_id, type, seq)`,
+];
+export const SESSION_INDEXES = [
+    { table: "session_meta", name: "idx_session_meta_owner", columns: ["owner"] },
+    { table: "session_meta", name: "idx_session_meta_placement", columns: ["placement_kind", "placement_scope", "placed_at"] },
+    { table: "session_event", name: "uq_session_event_entry", columns: ["session_id", "entry_id"], unique: true },
+    { table: "session_event", name: "idx_session_event_type", columns: ["session_id", "type", "seq"] },
 ];
 export async function ensureSchema(pool) {
     for (const stmt of PG_SESSION_SCHEMA)
         await pool.query(stmt);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", SESSION_INDEXES);
 }
 export class PgSessionStorage extends BaseSessionStorage {
     pool;

package/dist/plugins/retention-store-sql.d.ts

@@ -49,6 +49,7 @@ import type { ManagedRetentionCapability, RetentionDeclaration, RetentionReceipt
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 /**
  * 三只**被托管**的 SQL 店(session / checkpoint / tool-result)共用的 `retention` 声明常量。
  *
@@ -90,6 +91,8 @@ export declare const TIDB_RETENTION_STATEMENTS: readonly string[];
 /** PG 方言的建表语句(MySQL 孪生的逐条翻译:AUTO_INCREMENT→BIGSERIAL,逐列 `COLLATE "C"`,内联 KEY→独立
  *  CREATE INDEX)。语义逐字见 MySQL 孪生的行内注,此处不复述(两份注释迟早分叉)。 */
 export declare const PG_RETENTION_SCHEMA: readonly string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgRetentionSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const RETENTION_INDEXES: readonly IndexSpec[];
 /** PG 侧的幂等 schema apply(由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合;裸 `PgQueryFn` 形,与
  *  approval-ask / leader-run 同姿势 —— DDL 仍跑在中央那条 client 上,advisory lock 的 session 语义不受影响)。 */
 export declare function ensurePgRetentionSchema(query: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;

package/dist/plugins/retention-store-sql.js

@@ -1,5 +1,6 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const MANAGED_RETENTION = "managed";
 export const UNMANAGED_RETENTION = "none";
 export const RETENTION_AUDIT_TABLE = "retention_audit";
@@ -93,8 +94,6 @@ export const PG_RETENTION_SCHEMA = [
      error         TEXT COLLATE "C"         NULL,
      PRIMARY KEY (id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_retention_audit_domain ON ${RETENTION_AUDIT_TABLE} (domain, id)`,
-    `CREATE INDEX IF NOT EXISTS idx_retention_audit_executed ON ${RETENTION_AUDIT_TABLE} (executed_at_ms)`,
     `CREATE TABLE IF NOT EXISTS ${RETENTION_HOLD_TABLE} (
      domain       VARCHAR(190) COLLATE "C" NOT NULL,
      -- held:1 = 冻结中,0 = 只是那把域级互斥行锁的哨兵。完整判据(为什么 presence 形不成立)见 MySQL 孪生。
@@ -119,11 +118,16 @@ export const PG_RETENTION_SCHEMA = [
      -- 主键带 domain(理由逐字见 MySQL 孪生:会话 id 是调用方可自选的,跨租户同名合法)。
      PRIMARY KEY (domain, kind, row_key)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_retention_tombstone_key ON ${RETENTION_TOMBSTONE_TABLE} (kind, row_key)`,
+];
+export const RETENTION_INDEXES = [
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_domain", columns: ["domain", "id"] },
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_executed", columns: ["executed_at_ms"] },
+    { table: `${RETENTION_TOMBSTONE_TABLE}`, name: "idx_retention_tombstone_key", columns: ["kind", "row_key"] },
 ];
 export async function ensurePgRetentionSchema(query) {
     for (const stmt of PG_RETENTION_SCHEMA)
         await query(stmt);
+    await ensureIndexes(query, "pg", RETENTION_INDEXES);
 }
 class RetentionAborted extends Error {
     why;

package/dist/plugins/roster-store-sql.d.ts

@@ -23,8 +23,11 @@
 import type { Pool } from "mysql2/promise";
 import { type RosterStore, type RosterEntry, type RosterAccess } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
+import { type IndexSpec } from "./ensure-index.js";
 export declare const ROSTER_TABLE = "agent_roster";
 export declare function ensureTiDBRosterSchema(pool: Pool): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgRosterSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const ROSTER_INDEXES: readonly IndexSpec[];
 export declare function ensurePgRosterSchema(q: PgQueryFn): Promise<void>;
 export declare class TiDBRosterStore implements RosterStore {
     private readonly pool;

package/dist/plugins/roster-store-sql.js

@@ -1,4 +1,5 @@
 import { normalizeAgentName } from "@sema-agent/core";
+import { ensureIndexes } from "./ensure-index.js";
 export const ROSTER_TABLE = "agent_roster";
 function rowToEntry(r) {
     return {
@@ -42,7 +43,11 @@ export async function ensureTiDBRosterSchema(pool) {
     PRIMARY KEY (name_key, owner_key, scope_key),
     KEY idx_roster_agent (agent_id)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", ROSTER_INDEXES);
 }
+export const ROSTER_INDEXES = [
+    { table: `${ROSTER_TABLE}`, name: "idx_roster_agent", columns: ["agent_id"] },
+];
 export async function ensurePgRosterSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${ROSTER_TABLE} (
     name_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -66,7 +71,7 @@ export async function ensurePgRosterSchema(q) {
     recorded_at_ms BIGINT NOT NULL,
     PRIMARY KEY (name_key, owner_key, scope_key)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_roster_agent ON ${ROSTER_TABLE} (agent_id)`);
+    await ensureIndexes(q, "pg", ROSTER_INDEXES);
 }
 function upsertParams(entry, now) {
     return [

package/dist/plugins/schema-indexes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 中央 schema(`tidb-pool.ts` 的 `SCHEMA_STATEMENTS` ⇄ `pg-pool.ts` 的 `PG_SCHEMA_STATEMENTS` 这一对孪生)
+ * 所拥有的那批表的索引**声明** —— S-287,两方言**共用同一份**。
+ *
+ * ## 为什么自成一个模块
+ * 两只池各自 `import` 了自己的驱动(`mysql2/promise` / `pg`,都是**值**导入)。若把这份声明放进其中一只,
+ * 另一只就得把对方的驱动一起拖进进程 —— 单后端部署因此多驮一个它永远用不到的驱动。声明是纯数据、零驱动
+ * 依赖,所以它住在两只池**之外**,谁都可以白拿。
+ *
+ * ## 谁应用它
+ *  · **PG**:`pg-pool.ts` 的 `ensurePgSchema`,在所有 `CREATE TABLE` 之后(PG 方言没有内联 `KEY`);
+ *  · **MySQL/TiDB**:`tidb-pool.ts` 的 `ensureSchema`,同样在所有 `CREATE TABLE` 之后 —— 新建库上这批索引
+ *    早已随 `CREATE TABLE` 的内联 `KEY` 到货,`ensureIndex` 的探测因此**一条 DDL 都不发**;只有存量库
+ *    (建表那天还没有这条索引)才真的发一次 `ALTER TABLE … ADD INDEX`。
+ *
+ * 🔴 每条声明的**列序**必须与 `tidb-pool.ts` 那张表的内联 `KEY` 逐字一致(等值前缀在前、排序列在后);
+ *    两处列序分叉 = 两方言的访问路径分叉,而探测只看索引名、看不出列序不同。
+ */
+import type { IndexSpec } from "./ensure-index.js";
+export declare const CENTRAL_SCHEMA_INDEXES: readonly IndexSpec[];
+//# sourceMappingURL=schema-indexes.d.ts.map

package/dist/plugins/schema-indexes.js

@@ -0,0 +1,25 @@
+export const CENTRAL_SCHEMA_INDEXES = [
+    { table: "task_run", name: "idx_task_run_session_status", columns: ["session_id", "status"] },
+    { table: "task_run", name: "idx_task_run_owner", columns: ["owner"] },
+    { table: "task_run", name: "idx_task_run_created", columns: ["created_at"] },
+    { table: "task_run", name: "idx_task_run_job", columns: ["job_id"] },
+    { table: "task_active", name: "idx_task_active_task", columns: ["task_id"] },
+    { table: "checkpoint", name: "idx_checkpoint_status_deadline", columns: ["status", "deadline"] },
+    { table: "checkpoint", name: "idx_checkpoint_session_status", columns: ["session_id", "status"] },
+    { table: "resume_anchor", name: "idx_resume_anchor_session", columns: ["session_id"] },
+    { table: "approval_nonce", name: "idx_approval_nonce_expires", columns: ["expires_at_ms"] },
+    { table: "sendfile_link", name: "idx_sendfile_link_scope", columns: ["scope", "id"] },
+    { table: "session_policy", name: "idx_session_policy_session", columns: ["session_id"] },
+    { table: "snapshot_blob", name: "idx_snapshot_blob_created", columns: ["created_at"] },
+    { table: "file_history_version", name: "idx_file_history_version_blob", columns: ["blob_hash"] },
+    { table: "file_history_boundary_file", name: "idx_file_history_bf_key", columns: ["scope", "key_hash"] },
+    { table: "file_history_blob", name: "idx_file_history_blob_created", columns: ["created_at"] },
+    { table: "workflow_run", name: "idx_wfrun_scope_created", columns: ["scope", "created_at_ms"] },
+    { table: "workflow_run", name: "idx_wfrun_scope_status", columns: ["scope", "status"] },
+    { table: "workflow_agent_session", name: "idx_wfagentsess_run", columns: ["run_id"] },
+    { table: "workflow_completion_inbox", name: "idx_wfinbox_session_seq", columns: ["session_id", "seq"] },
+    { table: "workflow_inbox_fence", name: "idx_wffence_until", columns: ["until_ms"] },
+    { table: "workflow_notify_journal", name: "idx_wfnotify_acked", columns: ["acked"] },
+    { table: "shared_memory_store", name: "idx_shared_memory_store_scope", columns: ["scope_key", "store_id"] },
+];
+//# sourceMappingURL=schema-indexes.js.map

package/dist/plugins/task-attachment-store.d.ts

@@ -26,6 +26,7 @@
  */
 import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
+import { type IndexSpec } from "./ensure-index.js";
 export interface TaskAttachmentRecord {
     id: string;
     owner: string;
@@ -116,6 +117,8 @@ export declare function materializeAttachmentsInto(env: {
     }>;
 }, store: TaskAttachmentStore, sessionId: string): Promise<number>;
 export declare function ensureTiDBTaskAttachmentSchema(pool: Pool): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgTaskAttachmentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const TASK_ATTACHMENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgTaskAttachmentSchema(q: PgQueryFn): Promise<void>;
 /** bytes → 4 MiB 块序列(共享切块器,两方言 + 完整性校验共用)。 */
 export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {

package/dist/plugins/task-attachment-store.js

@@ -1,3 +1,4 @@
+import { ensureIndexes } from "./ensure-index.js";
 export const TASK_ATTACHMENT_TABLE = "task_attachment";
 export function materializedRelPaths(atts) {
     const used = new Set();
@@ -76,7 +77,12 @@ export async function ensureTiDBTaskAttachmentSchema(pool) {
     KEY idx_att_session (session_id),
     KEY idx_att_unbound (created_at_ms)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", TASK_ATTACHMENT_INDEXES);
 }
+export const TASK_ATTACHMENT_INDEXES = [
+    { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_session", columns: ["session_id"] },
+    { table: `${TASK_ATTACHMENT_TABLE}`, name: "idx_att_unbound", columns: ["created_at_ms"] },
+];
 export async function ensurePgTaskAttachmentSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${TASK_ATTACHMENT_TABLE} (
     id VARCHAR(64) COLLATE "C" NOT NULL,
@@ -91,8 +97,7 @@ export async function ensurePgTaskAttachmentSchema(q) {
     bound_at_ms BIGINT,
     PRIMARY KEY (id)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_att_session ON ${TASK_ATTACHMENT_TABLE} (session_id)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_att_unbound ON ${TASK_ATTACHMENT_TABLE} (created_at_ms)`);
+    await ensureIndexes(q, "pg", TASK_ATTACHMENT_INDEXES);
 }
 export class TiDBTaskAttachmentStore {
     pool;

package/dist/plugins/tidb-pool.d.ts

@@ -1,6 +1,7 @@
 import mysql from "mysql2/promise";
 import type { Pool, PoolConnection } from "mysql2/promise";
 import type { ServiceConfig } from "../config-types.js";
+import { type IndexSpec } from "./ensure-index.js";
 /**
  * Shared TiDB (MySQL wire-compatible) connection pool for the durable Session center (L1).
  * Owned by `main.ts`; closed on shutdown.
@@ -57,11 +58,22 @@ export declare const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
  *  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 declare function acquireEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<boolean>;
+ *  rest sleeping (not blocked in-DB). Polls until acquired (7.83.0: never degrades to unserialized — the S-287
+ *  `ADD INDEX` leg is not race-safe); a connection whose probe keeps throwing surfaces as a boot failure. */
+export declare function acquireEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;
 /** Release {@link ENSURE_SCHEMA_LOCK} on `conn` (best-effort — the lock also auto-frees when the connection closes). */
 export declare function releaseEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;
+/**
+ * S-287:`SCHEMA_STATEMENTS` 建的那批表**在存量库上可能缺的索引**(声明与 PG 侧逐条共用同一份 —— 见
+ * `plugins/ensure-index.ts` 头注与 `plugins/schema-indexes.ts`)。
+ *
+ * 组合口径与 `SCHEMA_STATEMENTS` **一一对应**:凡是它建的表,索引声明就进这个数组;它不建的表
+ * (device / roster / background-agent / mailbox / task-attachment / memory 两族……由 `boot/stores.ts`
+ * 各自的 `ensureTiDB*Schema` 腿建)由那条腿自己应用自己的声明 —— 否则这里会对一张还不存在的表发 ALTER。
+ *
+ * 新建库上这批索引早已随 `CREATE TABLE` 的内联 `KEY` 到货 ⇒ `ensureIndex` 的探测全部命中、**零 DDL**。
+ */
+export declare const SCHEMA_INDEXES: readonly IndexSpec[];
 /** 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

package/dist/plugins/tidb-pool.js

@@ -6,6 +6,21 @@ 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";
+import { ensureIndexes } from "./ensure-index.js";
+import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
+import { SESSION_INDEXES } from "./pg-session-storage.js";
+import { TOOL_RESULT_INDEXES } from "./tool-result-store-sql.js";
+import { COST_QUOTA_INDEXES } from "./pg-cost-quota.js";
+import { RATE_LIMIT_INDEXES } from "./pg-rate-limiter.js";
+import { OUTCOME_LEDGER_INDEXES } from "./outcome-ledger-sql.js";
+import { IMAGE_INDEX_INDEXES } from "./image-index-sql.js";
+import { IMAGE_BAKE_INDEXES } from "./image-bake-store-sql.js";
+import { APPROVAL_ASK_INDEXES } from "./approval-ask-store-sql.js";
+import { ADOPTION_LOG_INDEXES } from "./adoption-log-sql.js";
+import { PERMISSION_RULE_INDEXES } from "./permission-rule-store-sql.js";
+import { RETENTION_INDEXES } from "./retention-store-sql.js";
+import { LEADER_RUN_INDEXES } from "./leader-run-store-sql.js";
+import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
 export function tidbPoolOptions(tidb) {
     const { host, port, user, password, database, connectionLimit } = tidb;
     const limit = connectionLimit ?? 10;
@@ -670,20 +685,10 @@ export const SCHEMA_STATEMENTS = [
 ];
 export const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
 export async function acquireEnsureSchemaLock(conn, tag = "ensureSchema") {
-    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;
-        }
-        catch (err) {
-            console.warn(`[${tag}] GET_LOCK('${ENSURE_SCHEMA_LOCK}') attempt ${attempt + 1}/40:`, err?.message ?? err);
-        }
-        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;
+    await pollUntilLocked(async () => {
+        const [rows] = await conn.query("SELECT GET_LOCK(?, 0) AS got", [ENSURE_SCHEMA_LOCK]);
+        return Number(rows[0]?.got) === 1;
+    }, { tag, label: `GET_LOCK('${ENSURE_SCHEMA_LOCK}')` });
 }
 export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
     try {
@@ -693,14 +698,32 @@ export async function releaseEnsureSchemaLock(conn, tag = "ensureSchema") {
         console.warn(`[${tag}] RELEASE_LOCK('${ENSURE_SCHEMA_LOCK}') failed (lock auto-frees on connection close):`, err);
     }
 }
+export const SCHEMA_INDEXES = [
+    ...CENTRAL_SCHEMA_INDEXES,
+    ...SESSION_INDEXES,
+    ...TOOL_RESULT_INDEXES,
+    ...COST_QUOTA_INDEXES,
+    ...RATE_LIMIT_INDEXES,
+    ...OUTCOME_LEDGER_INDEXES,
+    ...IMAGE_INDEX_INDEXES,
+    ...IMAGE_BAKE_INDEXES,
+    ...APPROVAL_ASK_INDEXES,
+    ...ADOPTION_LOG_INDEXES,
+    ...PERMISSION_RULE_INDEXES,
+    ...RETENTION_INDEXES,
+    ...LEADER_RUN_INDEXES,
+];
 export async function ensureSchema(pool) {
     const conn = await pool.getConnection();
-    const locked = await acquireEnsureSchemaLock(conn);
+    let locked = false;
     try {
+        await acquireEnsureSchemaLock(conn);
+        locked = true;
         for (const stmt of SCHEMA_STATEMENTS) {
             await conn.query(stmt);
         }
         await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES ('standard')");
+        await ensureIndexes((text, params) => conn.query(text, params), "mysql", SCHEMA_INDEXES);
     }
     finally {
         if (locked)

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

@@ -2,10 +2,13 @@ import type { ToolResultProvenance, ToolResultStore, ToolResultSlice, ToolResult
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 /** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
  *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
  *  tables, so a self-contained ensureSchema is safe (central pg-pool aggregation is done separately). */
 export declare const PG_TOOL_RESULT_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const TOOL_RESULT_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for the tool_result table (for the integration test to call). */
 export declare function ensureSchema(pool: PgPool | PgPoolClient): Promise<void>;
 /**

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

@@ -2,6 +2,7 @@ import { MAX_MINTED_TOOL_RESULT_REF_CHARS, assertSafeToolResultRef, assertToolRe
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const PG_TOOL_RESULT_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS tool_result (
      ref              VARCHAR(518) COLLATE "C" NOT NULL,
@@ -11,11 +12,14 @@ export const PG_TOOL_RESULT_SCHEMA = [
      created_at       TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (ref)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_tool_result_created ON tool_result (created_at)`,
+];
+export const TOOL_RESULT_INDEXES = [
+    { table: "tool_result", name: "idx_tool_result_created", columns: ["created_at"] },
 ];
 export async function ensureSchema(pool) {
     for (const stmt of PG_TOOL_RESULT_SCHEMA)
         await pool.query(stmt);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", TOOL_RESULT_INDEXES);
 }
 export async function assertToolResultProvenanceSchema(query, dialect) {
     const widthRow = await query(dialect === "tidb"