@sema-agent/server 7.82.1 → 7.83.0

package/dist/plugins/permission-rule-store-sql.js

@@ -5,6 +5,7 @@ import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-dri
 import { isMissingColumnError } from "./sql-errors.js";
 import { canonicalJson } from "../canonical-json.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, isPersistedRuleTool, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
+import { ensureIndexes } from "./ensure-index.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -247,6 +248,13 @@ export async function assertPermissionRuleTicketSchema(query, dialect) {
             `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+export const PERMISSION_RULE_INDEXES = [
+    { table: `${PERMISSION_RULE_APPROVAL_TABLE}`, name: "idx_permission_rule_approval_owner", columns: ["owner_key"] },
+    { table: `${PERMISSION_RULE_APPROVAL_TABLE}`, name: "idx_permission_rule_approval_sweep", columns: ["state", "created_at_ms"] },
+    { table: `${PERMISSION_RULE_TICKET_TABLE}`, name: "idx_permission_rule_ticket_owner", columns: ["owner_key"] },
+    { table: `${PERMISSION_RULE_TICKET_TABLE}`, name: "idx_permission_rule_ticket_approval", columns: ["approval_id"] },
+    { table: `${PERMISSION_RULE_TICKET_TABLE}`, name: "idx_permission_rule_ticket_expires", columns: ["expires_at_ms"] },
+];
 export async function ensurePgPermissionRuleSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TABLE} (
     owner_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -293,8 +301,6 @@ export async function ensurePgPermissionRuleSchema(q) {
     updated_at_ms BIGINT NOT NULL,
     PRIMARY KEY (record_id)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_owner ON ${PERMISSION_RULE_APPROVAL_TABLE} (owner_key)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_sweep ON ${PERMISSION_RULE_APPROVAL_TABLE} (state, created_at_ms)`);
     await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
     ticket_id VARCHAR(190) COLLATE "C" NOT NULL,
     owner_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -315,9 +321,7 @@ export async function ensurePgPermissionRuleSchema(q) {
     created_at_ms BIGINT NOT NULL,
     PRIMARY KEY (ticket_id)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_owner ON ${PERMISSION_RULE_TICKET_TABLE} (owner_key)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_approval ON ${PERMISSION_RULE_TICKET_TABLE} (approval_id)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_expires ON ${PERMISSION_RULE_TICKET_TABLE} (expires_at_ms)`);
+    await ensureIndexes(q, "pg", PERMISSION_RULE_INDEXES);
 }
 export function buildRuleOwnerKey(owner) {
     const material = owner.kind === "principal" ? `principal:${owner.principal}` : "local-owner";

package/dist/plugins/pg-cost-quota.d.ts

@@ -14,6 +14,7 @@
 import type { Pool, PoolClient } from "pg";
 import type { QuotaDecision, QuotaLimits, QuotaTracker } from "../observability/cost-quota.js";
 import { type CounterDegradeHook } from "./write-behind-counter.js";
+import { type IndexSpec } from "./ensure-index.js";
 export declare class PgCostQuota implements QuotaTracker {
     private readonly counter;
     /** [ref]:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
@@ -35,6 +36,8 @@ export declare class PgCostQuota implements QuotaTracker {
  *  DATETIME(3)→TIMESTAMPTZ(3), inline `KEY idx_window`→separate CREATE INDEX). DISJOINT from other stores'
  *  tables, so a self-contained ensureSchema is safe (the central pg-pool aggregation is done separately). */
 export declare const PG_COST_QUOTA_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const COST_QUOTA_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for the cost_quota table (the PG twin of tidb-pool.ts ensureSchema). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
 //# sourceMappingURL=pg-cost-quota.d.ts.map

package/dist/plugins/pg-cost-quota.js

@@ -1,4 +1,5 @@
 import { PgWriteBehindCounter } from "./write-behind-counter.js";
+import { ensureIndexes } from "./ensure-index.js";
 const COST_QUOTA_TABLE = { table: "cost_quota", keyCol: "scope_key", valCol: "micro_usd" };
 export class PgCostQuota {
     counter;
@@ -62,10 +63,13 @@ export const PG_COST_QUOTA_SCHEMA = [
      updated_at    TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (scope_key, window_bucket)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_cost_quota_window ON cost_quota (window_bucket)`,
+];
+export const COST_QUOTA_INDEXES = [
+    { table: "cost_quota", name: "idx_cost_quota_window", columns: ["window_bucket"] },
 ];
 export async function ensureSchema(pool) {
     for (const stmt of PG_COST_QUOTA_SCHEMA)
         await pool.query(stmt);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", COST_QUOTA_INDEXES);
 }
 //# sourceMappingURL=pg-cost-quota.js.map

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

@@ -75,14 +75,35 @@ export declare function createPgPool(opts: string | pg.PoolConfig, onIdleClientE
  *  one lock identity for the whole class (the one-time migration段 is the current user; it runs after ensure and
  *  must not interleave with another replica's ensure). */
 export declare const ENSURE_SCHEMA_LOCK_KEY = 4906;
+/**
+ * {@link ENSURE_SCHEMA_LOCK_KEY} 的**非阻塞**获取(轮询 + 抖动退避)—— MySQL 孪生
+ * `tidb-pool.ts acquireEnsureSchemaLock` 的逐条同形(循环共用 `ensure-schema-lock-policy.ts`)。轮到拿到为止;坏连接连续抛上抛
+ * (每条 DDL 本来就各自幂等),而不是把启动挂死。
+ *
+ * 🔴 **为什么不能再用阻塞的 `pg_advisory_lock()`**(S-287 复审 H1,对 7.82.1 的回归):本仓自 S-287 起在
+ * 锁窗内发 `CREATE INDEX CONCURRENTLY`,而 CIC 的末相要**等掉同库里所有 xmin 比它老的运行中后端**
+ * (`WaitForOlderSnapshots`)。一条卡在 `SELECT pg_advisory_lock($1)` 里的副本**正是**一条持着快照的运行中
+ * 查询 —— 它等锁、锁等 CIC、CIC 等它:三方互等。命中形是「全新 PG 库 + 多副本同时起」(表刚建完 ⇒ 索引
+ * 必缺 ⇒ 必走 CIC)。非阻塞轮询把等待挪到**库外**:每次尝试都是一条立刻返回的独立语句,轮询间隙进程
+ * 不持任何快照,CIC 因此永远等得到头。旧的普通 `CREATE INDEX` 不做 WaitForOlderSnapshots,所以这条病
+ * 是随 CIC 一起进来的,修也必须和它同批。
+ *
+ * ⚠️ 锁是 **session(连接)级**:调用方必须把锁与其后**全部**被串行化的语句跑在**同一条** client 上
+ * (走 `pool.query` 可能落到别的池连接,那把锁就静默作废了)。
+ */
+export declare function acquirePgEnsureSchemaLock(client: pg.PoolClient, tag: string): Promise<void>;
+/** {@link acquirePgEnsureSchemaLock} 的释放(尽力而为 —— 锁随连接归还自动释放)。 */
+export declare function releasePgEnsureSchemaLock(client: pg.PoolClient, tag: string): Promise<void>;
 /** Idempotent central schema apply (the PG twin of tidb-pool.ts ensureSchema): the run/checkpoint tables here +
  *  every PG store's own (disjoint) tables. Order is irrelevant (CREATE IF NOT EXISTS, no cross-table FKs).
  *
  *  Concurrency: callers run this concurrently — tests fan ALL integration suites out in parallel (each beforeAll
  *  calls ensurePgSchema), and in production every replica calls it at boot. Concurrent DDL on the SAME table makes
  *  PG raise `tuple concurrently updated` in its catalog. We serialize the entire run behind a session-level
- *  `pg_advisory_lock`: the first caller does the real CREATE/ALTER, the rest block until it unlocks then find every
- *  statement already satisfied (IF NOT EXISTS ⇒ no-op), so there is no catalog race. The DDL semantics are
+ *  advisory lock, acquired NON-BLOCKINGLY with polling ({@link acquirePgEnsureSchemaLock} — 阻塞形会与本函数
+ *  自 S-287 起发的 `CREATE INDEX CONCURRENTLY` 三方互等,理由写在那只函数的头注里): the first caller does
+ *  the real CREATE/index work, the rest poll from OUTSIDE the database then find every statement already
+ *  satisfied (IF NOT EXISTS ⇒ no-op), so there is no catalog race. The DDL semantics are
  *  unchanged — only its timing is serialized. The advisory lock is SESSION (connection)-level, so the lock and
  *  ALL the DDL MUST run on the one client we hold; routing DDL through `pool.query` could land on a different
  *  pooled connection and silently void the lock. */

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;