@sema-agent/server 7.82.1 → 7.84.0

package/dist/plugins/image-index-sql.d.ts

@@ -2,11 +2,14 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient } from "pg";
 import { type ImageStatus, type ImageIndexEntry, type ImageIndexUpsert, type ImageViewer, type ImageListFilter } from "./store-contracts.js";
 import { type SqlDriver } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 export type { ImageNestedBuildMode, ImageCapabilities, ImagePodContract, ImageStatus, ImageVisibility, ImageIndexEntry, ImageIndexUpsert, ImageViewer, ImageListFilter, ImageRow, } from "./store-contracts.js";
 /** PG translation of the `sandbox_image_index` DDL in tidb-pool.ts (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
  *  TINYINT(1)→SMALLINT(布尔列 PG 映射归一,clay 批 2026-07-26 —— 两方言读回同为 number,写入 0/1,
  *  读侧 `!!` 保持,出口 JS 类型不变), inline UNIQUE KEY/KEY → separate CREATE UNIQUE INDEX / CREATE INDEX). */
 export declare const PG_IMAGE_INDEX_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensureSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const IMAGE_INDEX_INDEXES: readonly IndexSpec[];
 /** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
 export declare function ensureSchema(pool: PgPool | PoolClient): Promise<void>;
 /** Dual-dialect INDEX store. See the file header for the dialect-delta ledger. */

package/dist/plugins/image-index-sql.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { pgSafeJsonStringify, pgSanitizeText, pgHasUnstorable, PgUnstorableError } from "./pg-safe-json.js";
 import { mapImageRow as mapRow, } from "./store-contracts.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const PG_IMAGE_INDEX_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS sandbox_image_index (
      id                 VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -27,14 +28,17 @@ export const PG_IMAGE_INDEX_SCHEMA = [
      updated_at         TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (id)
    )`,
-    `CREATE UNIQUE INDEX IF NOT EXISTS uq_repo_digest ON sandbox_image_index (repo, digest)`,
-    `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_profile_status ON sandbox_image_index (profile, status, visibility)`,
-    `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_digest ON sandbox_image_index (digest)`,
-    `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_tenant ON sandbox_image_index (tenant_id, status)`,
+];
+export const IMAGE_INDEX_INDEXES = [
+    { table: "sandbox_image_index", name: "uq_repo_digest", columns: ["repo", "digest"], unique: true },
+    { table: "sandbox_image_index", name: "idx_sandbox_image_index_profile_status", columns: ["profile", "status", "visibility"] },
+    { table: "sandbox_image_index", name: "idx_sandbox_image_index_digest", columns: ["digest"] },
+    { table: "sandbox_image_index", name: "idx_sandbox_image_index_tenant", columns: ["tenant_id", "status"] },
 ];
 export async function ensureSchema(pool) {
     for (const stmt of PG_IMAGE_INDEX_SCHEMA)
         await pool.query(stmt);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", IMAGE_INDEX_INDEXES);
 }
 const MAX_LIMIT = 200;
 const DEFAULT_LIMIT = 50;

package/dist/plugins/leader-run-store-sql.d.ts

@@ -1,6 +1,7 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+import { type IndexSpec } from "./ensure-index.js";
 /** 表名([ref] 单数纪律;`schema-naming-invariants` 的闭集词表执法)。 */
 export declare const LEADER_RUN_TABLE = "leader_run";
 /** leader run 的四态 —— 与 `leader/endpoint.ts` 的 `LeaderRun["status"]` 同词表(闭集)。 */
@@ -47,6 +48,8 @@ export declare function leaderIdemKey(raw: string, owner: string | null): string
 export declare const TIDB_LEADER_RUN_STATEMENTS: readonly string[];
 /** PG 方言的建表语句(MySQL 孪生的逐条翻译:JSON→JSONB,逐列 `COLLATE "C"`,内联 KEY→独立 CREATE INDEX)。 */
 export declare const PG_LEADER_RUN_SCHEMA: readonly string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgLeaderRunSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const LEADER_RUN_INDEXES: readonly IndexSpec[];
 /** 幂等的 PG schema 应用(中央 `ensurePgSchema` 组合它;集成套件也直接调)。 */
 export declare function ensurePgLeaderRunSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
 /** 清算腿写进 `error` 列的 WHY(消费方读到的就是这句;不是一个空的 failed)。 */

package/dist/plugins/leader-run-store-sql.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { isDupKeyError } from "./sql-errors.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { parseJsonOr } from "./sql-row-helpers.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const LEADER_RUN_TABLE = "leader_run";
 const LEADER_RUN_STATUSES = new Set(["running", "completed", "failed", "needs_human"]);
 export const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
@@ -46,12 +47,15 @@ export const PG_LEADER_RUN_SCHEMA = [
      PRIMARY KEY (leader_run_id),
      CONSTRAINT uq_leader_run_idem UNIQUE (idem_key)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_leader_run_owner ON ${LEADER_RUN_TABLE} (owner)`,
-    `CREATE INDEX IF NOT EXISTS idx_leader_run_started ON ${LEADER_RUN_TABLE} (started_at_ms)`,
+];
+export const LEADER_RUN_INDEXES = [
+    { table: `${LEADER_RUN_TABLE}`, name: "idx_leader_run_owner", columns: ["owner"] },
+    { table: `${LEADER_RUN_TABLE}`, name: "idx_leader_run_started", columns: ["started_at_ms"] },
 ];
 export async function ensurePgLeaderRunSchema(q) {
     for (const stmt of PG_LEADER_RUN_SCHEMA)
         await q(stmt);
+    await ensureIndexes(q, "pg", LEADER_RUN_INDEXES);
 }
 export const STALE_SWEEP_REASON = "leader run went stale: no replica settled it within LEADER_RUN_STALE_MS (the replica driving it most likely died). " +
     "The run was NOT taken over — re-submit with a NEW Idempotency-Key to run it again.";

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

@@ -45,6 +45,7 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
+import { type IndexSpec } from "./ensure-index.js";
 export declare const MAILBOX_TABLE = "mailbox";
 export declare const MAILBOX_MSG_TABLE = "mailbox_message";
 /** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏 `peer_meta` 行的 fail-closed 抛必须**响亮**——core 唯一的
@@ -54,6 +55,8 @@ export interface MailboxStoreLogger {
     warn(event: string, fields: Record<string, unknown>): void;
 }
 export declare function ensureTiDBMailboxSchema(pool: MySqlPool): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgMailboxSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const MAILBOX_INDEXES: readonly IndexSpec[];
 export declare function ensurePgMailboxSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
 export declare class TiDBMailboxStore implements MailboxStore {
     private readonly pool;

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

@@ -1,5 +1,6 @@
 import { MAILBOX_INVALID_PEER_META_CODE, MailboxStoreError, readMailboxPeerMeta } from "@sema-agent/core";
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const MAILBOX_TABLE = "mailbox";
 export const MAILBOX_MSG_TABLE = "mailbox_message";
 function assertScope(scope) {
@@ -131,7 +132,11 @@ export async function ensureTiDBMailboxSchema(pool) {
     PRIMARY KEY (scope_key, handle, seq),
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", MAILBOX_INDEXES);
 }
+export const MAILBOX_INDEXES = [
+    { table: `${MAILBOX_MSG_TABLE}`, name: "idx_mbm_sent", columns: ["scope_key", "handle", "sent_at_ms"] },
+];
 export async function ensurePgMailboxSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
     scope_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -154,7 +159,7 @@ export async function ensurePgMailboxSchema(q) {
     peer_meta TEXT COLLATE "C", -- S-90 core fc52b4d4 design/385 片2b(TiDB twin 同注:typed peer 记录 JSON;NULL = 缺席且有语义)
     PRIMARY KEY (scope_key, handle, seq)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_mbm_sent ON ${MAILBOX_MSG_TABLE} (scope_key, handle, sent_at_ms)`);
+    await ensureIndexes(q, "pg", MAILBOX_INDEXES);
 }
 export class TiDBMailboxStore {
     pool;

package/dist/plugins/memory-engine-pg.d.ts

@@ -1,6 +1,7 @@
 import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
 import type { PgEmbedder, PgQueryFn } from "./pg-query.js";
 import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "@sema-agent/core";
+import { type IndexSpec } from "./ensure-index.js";
 /** Table names (single source). Deliberately DISJOINT from the legacy `agent_memory*` tables —
  *  the retired MemoryStore plane and this entry plane must never cross-write. */
 export declare const PG_MEMORY_ENGINE_TABLES: {
@@ -16,6 +17,9 @@ export interface PgMemoryEngineSchemaOptions {
         pgvector?: boolean;
     };
 }
+/** S-287:记忆引擎 PG 面的索引**声明**(MySQL 孪生是 `memory-engine-tidb.ts` 的内联 `KEY`/`UNIQUE KEY`,
+ *  由 `tidb-pool.ts` 的中央 `ensureSchema` 用同一份声明补存量库)。 */
+export declare const MEMORY_ENGINE_INDEXES: readonly IndexSpec[];
 /** Idempotent DDL for the entry plane. Call once at startup (or run through your migration tool). */
 export declare function ensurePgMemoryEngineSchema(query: PgQueryFn, opts?: PgMemoryEngineSchemaOptions): Promise<void>;
 /** Options for {@link PgMemoryEngineBackend}. */

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

@@ -4,10 +4,15 @@ import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgSafeJsonStringify, pgHasUnstorable } from "./pg-safe-json.js";
 import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
 import { ambiguousOriginRefusal, createBatchCommittedBaseline, exposureBandOf, exposureCarriage, originMarkedSqlPredicate, originWhitewashRefusal, rememberBatchCommitted, distilledWhitewashRefusal, distilledCarriage, unknownPatchOpRefusal, } from "./memory-origin-law.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const PG_MEMORY_ENGINE_TABLES = {
     entry: "agent_memory_engine_entry",
     cursor: "agent_memory_engine_cursor",
 };
+export const MEMORY_ENGINE_INDEXES = [
+    { table: `${PG_MEMORY_ENGINE_TABLES.entry}`, name: `idx_${PG_MEMORY_ENGINE_TABLES.entry}_scope`, columns: ["scope"] },
+    { table: `${PG_MEMORY_ENGINE_TABLES.entry}`, name: `uq_${PG_MEMORY_ENGINE_TABLES.entry}_scope_slug`, columns: ["scope", "slug"], unique: true },
+];
 export async function ensurePgMemoryEngineSchema(query, opts = {}) {
     const vec = opts.memoryVector;
     if (vec !== undefined && (!Number.isInteger(vec.dimensions) || vec.dimensions < 1)) {
@@ -27,16 +32,11 @@ export async function ensurePgMemoryEngineSchema(query, opts = {}) {
     size_bytes integer NOT NULL,
     embedding ${embeddingCol}
   )`);
-    try {
-        await query(`CREATE INDEX IF NOT EXISTS idx_${PG_MEMORY_ENGINE_TABLES.entry}_scope ON ${PG_MEMORY_ENGINE_TABLES.entry} (scope)`);
-    }
-    catch {
-    }
-    await query(`CREATE UNIQUE INDEX IF NOT EXISTS uq_${PG_MEMORY_ENGINE_TABLES.entry}_scope_slug ON ${PG_MEMORY_ENGINE_TABLES.entry} (scope, slug)`);
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.cursor} (
     scope varchar(190) COLLATE "C" PRIMARY KEY,
     cursor text COLLATE "C" NOT NULL
   )`);
+    await ensureIndexes(query, "pg", MEMORY_ENGINE_INDEXES);
 }
 function vectorLiteral(v) {
     return `[${v.join(",")}]`;

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