@sema-agent/server 7.82.0 → 7.83.0

package/dist/plugins/memory-engine-tidb.js

@@ -4,10 +4,14 @@ import { pgHasUnstorable } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
 import { ambiguousOriginRefusal, createBatchCommittedBaseline, exposureBandOf, exposureCarriage, originWhitewashRefusal, rememberBatchCommitted, distilledWhitewashRefusal, distilledCarriage, unknownPatchOpRefusal, } from "./memory-origin-law.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
+import { ensureIndexes } from "./ensure-index.js";
+import { MEMORY_ENGINE_INDEXES, PG_MEMORY_ENGINE_TABLES } from "./memory-engine-pg.js";
 export const TIDB_MEMORY_ENGINE_TABLES = {
     entry: "agent_memory_engine_entry",
     cursor: "agent_memory_engine_cursor",
 };
+TIDB_MEMORY_ENGINE_TABLES;
+PG_MEMORY_ENGINE_TABLES;
 export async function ensureTiDBMemoryEngineSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_ENGINE_TABLES.entry} (
     id          VARCHAR(64)  NOT NULL,
@@ -28,6 +32,7 @@ export async function ensureTiDBMemoryEngineSchema(pool) {
     \`cursor\` TEXT     NOT NULL,
     PRIMARY KEY (scope)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", MEMORY_ENGINE_INDEXES);
 }
 const isDupEntry = isMysqlDupKeyError;
 function isPrimaryKeyDup(err) {

package/dist/plugins/memory-sync-store-pg.d.ts

@@ -1,5 +1,6 @@
 import type { MemorySyncCursor } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
+import { type IndexSpec } from "./ensure-index.js";
 /** Table names (single source). SAME names as the TiDB twin (the two dialects never share one DB). */
 export declare const PG_MEMORY_SYNC_TABLES: {
     readonly syncCursor: "agent_memory_engine_sync_cursor";
@@ -45,6 +46,8 @@ export interface MemorySyncStore {
     /** Transient failure: attempts+1 (SQL-atomic), record the error, schedule the next attempt. */
     fail(id: string, error: string, nextAttemptAtMs: number): Promise<void>;
 }
+/** S-287:push queue 的索引**声明**(MySQL 孪生 = `memory-sync-store-tidb.ts` 的内联 `KEY`)。 */
+export declare const MEMORY_SYNC_INDEXES: readonly IndexSpec[];
 /** Idempotent DDL for the sync plane (PG dialect). Call once at startup. */
 export declare function ensurePgMemorySyncSchema(query: PgQueryFn): Promise<void>;
 /** Options for {@link PgMemorySyncStore}. */
@@ -106,6 +109,8 @@ export interface MemoryHistoryStore {
     /** Ops read face (§1.3 保留策略: v1 无界 + 运维计数 — quota/pruning waits for a demand signal). */
     countByScope(scope: string): Promise<number>;
 }
+/** S-287:history 表的索引**声明**(MySQL 孪生 = `memory-sync-store-tidb.ts` 的内联 `KEY`)。 */
+export declare const MEMORY_HISTORY_INDEXES: readonly IndexSpec[];
 /** Idempotent DDL for the history table (PG dialect). Separate from the sync-plane ensure so S5.1
  *  can wire the write point independently of the S4 sync wiring. */
 export declare function ensurePgMemoryHistorySchema(query: PgQueryFn): Promise<void>;

package/dist/plugins/memory-sync-store-pg.js

@@ -1,3 +1,4 @@
+import { ensureIndexes } from "./ensure-index.js";
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth } from "./memory-key-guards.js";
 export const PG_MEMORY_SYNC_TABLES = {
@@ -5,6 +6,9 @@ export const PG_MEMORY_SYNC_TABLES = {
     pushQueue: "agent_memory_engine_push_queue",
     history: "agent_memory_engine_history",
 };
+export const MEMORY_SYNC_INDEXES = [
+    { table: `${PG_MEMORY_SYNC_TABLES.pushQueue}`, name: `idx_${PG_MEMORY_SYNC_TABLES.pushQueue}_next_attempt_ms`, columns: ["next_attempt_at_ms"] },
+];
 export async function ensurePgMemorySyncSchema(query) {
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.syncCursor} (
     scope         varchar(190) COLLATE "C" NOT NULL,
@@ -22,7 +26,7 @@ export async function ensurePgMemorySyncSchema(query) {
     next_attempt_at_ms bigint       NOT NULL,
     last_error         text COLLATE "C"         NULL
   )`);
-    await query(`CREATE INDEX IF NOT EXISTS idx_${PG_MEMORY_SYNC_TABLES.pushQueue}_next_attempt_ms ON ${PG_MEMORY_SYNC_TABLES.pushQueue} (next_attempt_at_ms)`);
+    await ensureIndexes(query, "pg", MEMORY_SYNC_INDEXES);
 }
 function fromJsonb(v) {
     if (typeof v === "string")
@@ -99,6 +103,9 @@ export class PgMemorySyncStore {
        WHERE id = $1`, [id, error, nextAttemptAtMs]);
     }
 }
+export const MEMORY_HISTORY_INDEXES = [
+    { table: `${PG_MEMORY_SYNC_TABLES.history}`, name: `idx_${PG_MEMORY_SYNC_TABLES.history}_scope`, columns: ["scope"] },
+];
 export async function ensurePgMemoryHistorySchema(query) {
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_SYNC_TABLES.history} (
     id            char(36) COLLATE "C"     NOT NULL,
@@ -110,7 +117,7 @@ export async function ensurePgMemoryHistorySchema(query) {
     written_at_ms bigint       NOT NULL,
     PRIMARY KEY (id, rev)
   )`);
-    await query(`CREATE INDEX IF NOT EXISTS idx_${PG_MEMORY_SYNC_TABLES.history}_scope ON ${PG_MEMORY_SYNC_TABLES.history} (scope)`);
+    await ensureIndexes(query, "pg", MEMORY_HISTORY_INDEXES);
 }
 export class PgMemoryHistoryStore {
     query;

package/dist/plugins/memory-sync-store-tidb.js

@@ -1,10 +1,14 @@
 import { historyRowFrom } from "./memory-sync-store-pg.js";
+import { ensureIndexes } from "./ensure-index.js";
+import { MEMORY_SYNC_INDEXES, MEMORY_HISTORY_INDEXES, PG_MEMORY_SYNC_TABLES } from "./memory-sync-store-pg.js";
 import { assertMemoryScopeWidth } from "./memory-key-guards.js";
 export const TIDB_MEMORY_SYNC_TABLES = {
     syncCursor: "agent_memory_engine_sync_cursor",
     pushQueue: "agent_memory_engine_push_queue",
     history: "agent_memory_engine_history",
 };
+TIDB_MEMORY_SYNC_TABLES;
+PG_MEMORY_SYNC_TABLES;
 export async function ensureTiDBMemorySyncSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_SYNC_TABLES.syncCursor} (
     scope         VARCHAR(190) NOT NULL,
@@ -24,6 +28,7 @@ export async function ensureTiDBMemorySyncSchema(pool) {
     PRIMARY KEY (id),
     KEY idx_agent_memory_engine_push_queue_next_attempt_ms (next_attempt_at_ms)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", MEMORY_SYNC_INDEXES);
 }
 function fromJson(v) {
     if (typeof v === "string")
@@ -116,6 +121,7 @@ export async function ensureTiDBMemoryHistorySchema(pool) {
     PRIMARY KEY (id, rev),
     KEY idx_agent_memory_engine_history_scope (scope)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", MEMORY_HISTORY_INDEXES);
 }
 export class TiDBMemoryHistoryStore {
     pool;

package/dist/plugins/one-time-migrations.d.ts

@@ -39,7 +39,7 @@ export declare class RetiredSteerSeatError extends Error {
  *
  * ## 并发(codex r1 [medium],亲核复现后修)
  * 一次滚动升级会让 N 个副本同时跑到这里。整段因此跑在**一条连接**上、握着**与 `ensureSchema` 同一把**
- * advisory 锁(MySQL 具名锁 / PG `pg_advisory_lock`):本段是「启动期改 schema 的活」,与 ensure 属同一类,
+ * advisory 锁(MySQL 具名锁 / PG `pg_try_advisory_lock`,两方言都是非阻塞轮询形):本段是「启动期改 schema 的活」,与 ensure 属同一类,
  * 复用同一把锁 ⇒ 本仓这一类工作只有**一个**锁身份,而且本段也不会与另一个副本的 ensure 交错。
  * 锁拿不到时按既有先例**降级**(不阻塞启动),但降级不等于放任:每条破坏性 DDL 的成功判据是它的
  * **后置条件**({@link execUntil}),所以「另一个副本抢先删掉了同一列」不会把滚动升级变成启动失败循环。

package/dist/plugins/one-time-migrations.js

@@ -1,5 +1,5 @@
 import { acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
-import { ENSURE_SCHEMA_LOCK_KEY } from "./pg-pool.js";
+import { acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
 export const NO_SQL_MIGRATIONS = {
     retiredSnapshotTable: "absent",
     retiredSnapshotRows: 0,
@@ -82,7 +82,8 @@ async function withMysqlLock(pool, run) {
     const conn = await pool.getConnection();
     let locked = false;
     try {
-        locked = await acquireEnsureSchemaLock(conn, "oneTimeMigrations");
+        await acquireEnsureSchemaLock(conn, "oneTimeMigrations");
+        locked = true;
         return await run(mysqlDb(conn));
     }
     finally {
@@ -95,21 +96,13 @@ async function withPgLock(pool, run) {
     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(`[oneTimeMigrations] pg_advisory_lock(${ENSURE_SCHEMA_LOCK_KEY}) failed; running the migration unserialized:`, err);
-        }
+        await acquirePgEnsureSchemaLock(client, "oneTimeMigrations");
+        locked = true;
         return await run(pgDb(client));
     }
     finally {
-        if (locked) {
-            await client
-                .query("SELECT pg_advisory_unlock($1)", [ENSURE_SCHEMA_LOCK_KEY])
-                .catch((err) => void console.warn(`[oneTimeMigrations] pg_advisory_unlock(${ENSURE_SCHEMA_LOCK_KEY}) failed (auto-freed on connection close):`, err));
-        }
+        if (locked)
+            await releasePgEnsureSchemaLock(client, "oneTimeMigrations");
         client.release();
     }
 }

package/dist/plugins/outcome-ledger-sql.d.ts

@@ -2,6 +2,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient } from "pg";
 import type { TaskOutcome as CoreTaskOutcome } from "@sema-agent/core";
 import { type SqlDriver } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 /** Mechanical signals — the ONLY tier a future self-scheduler may read (council blocker 1). */
 export interface MechanicalOutcome {
     route?: "single" | "fanout";
@@ -88,6 +89,8 @@ export declare function coreOutcomeToLedgerRow(o: CoreTaskOutcome): TaskOutcome;
  * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_OUTCOME_LEDGER_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgOutcomeLedgerSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const OUTCOME_LEDGER_INDEXES: readonly IndexSpec[];
 /** Idempotent self-contained PG schema apply (for the integration test; central aggregation via pg-pool.ts). */
 export declare function ensurePgOutcomeLedgerSchema(pool: PgPool | PoolClient): Promise<void>;
 /** Dual-dialect outcome ledger. See the file header for the dialect-delta ledger. */

package/dist/plugins/outcome-ledger-sql.js

@@ -1,5 +1,6 @@
 import { randomUUID, createHash } from "node:crypto";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
+import { ensureIndexes } from "./ensure-index.js";
 export function taskSignature(s) {
     if (s.tag)
         return `tag:${s.tag}`;
@@ -70,13 +71,16 @@ export const PG_OUTCOME_LEDGER_SCHEMA = [
      created_at     TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (id)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_sig_model ON outcome_ledger (task_signature, model, run_status)`,
-    `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_outcome ON outcome_ledger (outcome)`,
-    `CREATE INDEX IF NOT EXISTS idx_outcome_ledger_created ON outcome_ledger (created_at)`,
+];
+export const OUTCOME_LEDGER_INDEXES = [
+    { table: "outcome_ledger", name: "idx_outcome_ledger_sig_model", columns: ["task_signature", "model", "run_status"] },
+    { table: "outcome_ledger", name: "idx_outcome_ledger_outcome", columns: ["outcome"] },
+    { table: "outcome_ledger", name: "idx_outcome_ledger_created", columns: ["created_at"] },
 ];
 export async function ensurePgOutcomeLedgerSchema(pool) {
     for (const stmt of PG_OUTCOME_LEDGER_SCHEMA)
         await pool.query(stmt);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", OUTCOME_LEDGER_INDEXES);
 }
 export class SqlOutcomeLedger {
     db;

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -3,6 +3,7 @@ import { type PermissionRuleWriter, type DurableRulePartition, type DurableRuleP
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
 import { type SqlDriver } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 /**
  * 一只 durable 分区的写面,或 `undefined`(该 backend 从引擎侧看是只读的)。
  *
@@ -105,6 +106,8 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
 export declare function assertPermissionRuleTicketSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>, dialect: "tidb" | "pg"): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgPermissionRuleSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const PERMISSION_RULE_INDEXES: readonly IndexSpec[];
 export declare function ensurePgPermissionRuleSchema(q: PgQueryFn): Promise<void>;
 /**
  * 一只桶的**存储键**(纯数据 ⇒ `build*`)。

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>;
 /**