@sema-agent/server 7.82.1 → 7.83.0

package/dist/plugins/ensure-index.js

@@ -0,0 +1,81 @@
+import { recordFailOpen } from "../observability/fail-open.js";
+function rowsOf(res) {
+    if (Array.isArray(res)) {
+        const first = res[0];
+        return Array.isArray(first) ? first : [];
+    }
+    if (res && typeof res === "object" && Array.isArray(res.rows)) {
+        return res.rows;
+    }
+    return [];
+}
+const quoteId = (dialect, id) => dialect === "mysql" ? `\`${id.replace(/`/g, "``")}\`` : `"${id.replace(/"/g, '""')}"`;
+const quoteLiteral = (s) => `'${s.replace(/'/g, "''")}'`;
+const columnList = (dialect, spec) => spec.columns.map((c) => quoteId(dialect, c)).join(", ");
+function lacksConcurrentlySupport(err) {
+    const code = err?.code;
+    if (code === "0A000" || code === "42601")
+        return true;
+    return typeof code !== "string";
+}
+async function pgIndexValid(q, name) {
+    const rows = rowsOf(await q(`SELECT i.indisvalid FROM pg_index i WHERE i.indexrelid = to_regclass(${quoteLiteral(name)})`));
+    if (rows.length === 0)
+        return undefined;
+    return rows[0].indisvalid !== false;
+}
+const refusal = (spec, unique, what) => `ensureIndex: PostgreSQL 索引 ${spec.name}(表 ${spec.table})${what} —— 拒绝带病启动。` +
+    "(一个 INVALID 索引会让此后每一次 CREATE INDEX … IF NOT EXISTS 静默跳过它,而规划器永不使用它。)" +
+    ` 运维配方:DROP INDEX CONCURRENTLY IF EXISTS ${quoteId("pg", spec.name)}; 然后在维护窗口手工 ` +
+    `CREATE ${unique}INDEX CONCURRENTLY ${quoteId("pg", spec.name)} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)});` +
+    " 常见根因 = 池级 statement_timeout(DB_QUERY_TIMEOUT_MS)把构建切断(见 cause),或 UNIQUE 索引撞上存量重复行。";
+export async function ensureIndex(q, dialect, spec) {
+    switch (dialect) {
+        case "mysql": {
+            const present = rowsOf(await q("SELECT 1 AS present FROM information_schema.statistics WHERE table_schema = DATABASE() " +
+                `AND table_name = ${quoteLiteral(spec.table)} AND index_name = ${quoteLiteral(spec.name)} LIMIT 1`));
+            if (present.length > 0)
+                return;
+            await q(`ALTER TABLE ${quoteId("mysql", spec.table)} ADD ${spec.unique ? "UNIQUE " : ""}INDEX ` +
+                `${quoteId("mysql", spec.name)} (${columnList("mysql", spec)})`);
+            return;
+        }
+        case "pg": {
+            const unique = spec.unique ? "UNIQUE " : "";
+            const name = quoteId("pg", spec.name);
+            const tail = `${unique}INDEX CONCURRENTLY IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`;
+            try {
+                await q(`CREATE ${tail}`);
+            }
+            catch (err) {
+                if (!lacksConcurrentlySupport(err))
+                    throw err;
+                recordFailOpen("server.ensure-index.concurrently-unsupported", `${spec.table}.${spec.name}`);
+                await q(`CREATE ${unique}INDEX IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`);
+                return;
+            }
+            const valid = await pgIndexValid(q, spec.name);
+            if (valid !== false)
+                return;
+            await q(`DROP INDEX CONCURRENTLY IF EXISTS ${name}`);
+            try {
+                await q(`CREATE ${tail}`);
+            }
+            catch (err) {
+                throw new Error(refusal(spec, unique, "重建时失败"), { cause: err });
+            }
+            if ((await pgIndexValid(q, spec.name)) === false)
+                throw new Error(refusal(spec, unique, "重建后仍是 INVALID"));
+            return;
+        }
+        default: {
+            const _never = dialect;
+            throw new Error(`ensureIndex: 未知方言 ${String(_never)}`);
+        }
+    }
+}
+export async function ensureIndexes(q, dialect, specs) {
+    for (const spec of specs)
+        await ensureIndex(q, dialect, spec);
+}
+//# sourceMappingURL=ensure-index.js.map

package/dist/plugins/ensure-schema-lock-policy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 两方言启动锁(`ensureSchema` / `oneTimeMigrations` 的 MySQL `GET_LOCK(?,0)` 与 PG `pg_try_advisory_lock`)的
+ * **轮询策略唯一属主**(7.83.0 修复验证 车HC HC-1/HC-2 后收口:此前两只孪生各抄一份循环,一份改了「永不放弃」
+ * 另一份还是「40 次放弃后无锁跑」,而 S-287 之后无锁跑的那条腿发的是不带 `IF NOT EXISTS` 的 `ADD INDEX`,两副本
+ * 双发 ⇒ 输的那只拒启)。方言只提供「试一次」的探针,循环、抖动、退避、进展 warn、坏连接上抛全在这里。
+ *
+ * 三条律:
+ *  · **按进展轮询,不按次数放弃** —— 持锁方还活着(两方言的锁都是连接级,随连接消失,不会遗留)就一直等,
+ *    每 {@link LOCK_PROBE_WARN_EVERY} 次 warn 一行说明在等谁;**永不**无锁跑(「响亮地等」严格优于「静默地竞争 DDL」)。
+ *  · **坏连接不是争用**(HC-2,对 7.82.1 的回归):探针自己**连续**抛 {@link MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} 次 =
+ *    这条连接已不可用(`_queryable=false` / 半开 TCP),与「谁持锁」无关 ⇒ 上抛让启动响亮失败,不许无界轮。
+ *    偶发一次抛(TiDB 悲观锁抖动)照旧继续轮,计数在一次成功探针后归零。
+ *  · 轮询间隙进程不持任何快照(每次探针是亚毫秒的独立语句)⇒ 与 PG `CREATE INDEX CONCURRENTLY` 的
+ *    `WaitForOlderSnapshots` 永不互等(理由全文见 `pg-pool.ts` `acquirePgEnsureSchemaLock` 头注)。
+ */
+export declare const LOCK_PROBE_INITIAL_JITTER_MS = 400;
+export declare const LOCK_PROBE_WARN_EVERY = 40;
+export declare const MAX_CONSECUTIVE_LOCK_PROBE_ERRORS = 5;
+/** 抖动退避(~0.1s..0.4s + 至多 0.15s 抖动)—— 两方言同一条曲线。 */
+export declare function lockProbeBackoffMs(attempt: number): number;
+/**
+ * 轮到拿到为止。`tryOnce` = 方言自己的非阻塞探针:`true` 拿到、`false` 别人持着(继续轮)、抛 = 探针本身失败。
+ * 初始抖动把 ~20 个在 t=0 同时开火的调用方(集成套扇出 / 同步的舰队启动)铺开。
+ */
+export declare function pollUntilLocked(tryOnce: () => Promise<boolean>, opts: {
+    tag: string;
+    label: string;
+}): Promise<void>;
+//# sourceMappingURL=ensure-schema-lock-policy.d.ts.map

package/dist/plugins/ensure-schema-lock-policy.js

@@ -0,0 +1,31 @@
+export const LOCK_PROBE_INITIAL_JITTER_MS = 400;
+export const LOCK_PROBE_WARN_EVERY = 40;
+export const MAX_CONSECUTIVE_LOCK_PROBE_ERRORS = 5;
+export function lockProbeBackoffMs(attempt) {
+    return 100 + Math.min(attempt, 3) * 100 + Math.floor(Math.random() * 150);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function pollUntilLocked(tryOnce, opts) {
+    await sleep(Math.floor(Math.random() * LOCK_PROBE_INITIAL_JITTER_MS));
+    let consecutiveErrors = 0;
+    for (let attempt = 0;; attempt++) {
+        try {
+            if (await tryOnce())
+                return;
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            consecutiveErrors += 1;
+            const msg = err?.message ?? String(err);
+            console.warn(`[${opts.tag}] ${opts.label} probe attempt ${attempt + 1} threw (${consecutiveErrors}/${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS}):`, msg);
+            if (consecutiveErrors >= MAX_CONSECUTIVE_LOCK_PROBE_ERRORS) {
+                throw new Error(`[${opts.tag}] ${opts.label}: lock probe threw ${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} times in a row — the connection itself is unusable, refusing to poll forever (last: ${msg})`, { cause: err });
+            }
+        }
+        if (attempt > 0 && attempt % LOCK_PROBE_WARN_EVERY === 0) {
+            console.warn(`[${opts.tag}] still waiting for ${opts.label} (another replica is running the serialized DDL; attempt ${attempt})`);
+        }
+        await sleep(lockProbeBackoffMs(attempt));
+    }
+}
+//# sourceMappingURL=ensure-schema-lock-policy.js.map

package/dist/plugins/image-bake-store-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 SqlDriver } from "./sql-driver.js";
 import { type BakeStatus, type BakeState, type BakeRecord, type BakeEvent, type CreateBakeInput, type BakeTerminal } from "./store-contracts.js";
+import { type IndexSpec } from "./ensure-index.js";
 /** PG translation of the image_bake / image_bake_event / image_bake_lease DDL in tidb-pool.ts SCHEMA_STATEMENTS
  *  (JSON→JSONB, TINYINT→SMALLINT, DATETIME(3)→TIMESTAMPTZ(3), inline UNIQUE/KEY→named CONSTRAINT + CREATE INDEX).
  *  TINYINT(1) 归一(clay 批 2026-07-26):布尔列的 PG 映射统一 SMALLINT 0/1(此前本家族用 BOOLEAN)——
@@ -9,6 +10,8 @@ import { type BakeStatus, type BakeState, type BakeRecord, type BakeEvent, type
  *  读侧 `!!`/`Boolean()` 保持,store 出口 JS 类型逐字节不变(真双库套件的严格值断言为证)。
  *  The line UNIQUE is given the explicit name uq_image_bake_event_line so a 23505 can be attributed to it via err.constraint. */
 export declare const PG_IMAGE_BAKE_SCHEMA: string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgImageBakeSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const IMAGE_BAKE_INDEXES: readonly IndexSpec[];
 /** Idempotent self-contained PG schema apply (for the integration test; central aggregation is done separately). */
 export declare function ensurePgImageBakeSchema(pool: PgPool | PoolClient, poolName?: string): Promise<void>;
 /** Dual-dialect BAKE store. See the file header for the dialect-delta ledger. */

package/dist/plugins/image-bake-store-sql.js

@@ -5,6 +5,7 @@ import { parseJsonOr as parseJson, toIso as iso } from "./sql-row-helpers.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { mapBakeRow as mapRow, BAKE_SELECT_COLS as SELECT_COLS, } from "./store-contracts.js";
 import { isDupKeyError } from "./sql-errors.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const PG_IMAGE_BAKE_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS image_bake (
      bake_id          VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -37,8 +38,6 @@ export const PG_IMAGE_BAKE_SCHEMA = [
      PRIMARY KEY (bake_id),
      CONSTRAINT uq_image_bake_idem UNIQUE (idem_key)
    )`,
-    `CREATE INDEX IF NOT EXISTS idx_image_bake_status ON image_bake (status)`,
-    `CREATE INDEX IF NOT EXISTS idx_image_bake_created ON image_bake (created_at)`,
     `CREATE TABLE IF NOT EXISTS image_bake_event (
      bake_id  VARCHAR(64) COLLATE "C" NOT NULL,
      seq      INT         NOT NULL,
@@ -62,10 +61,15 @@ export const PG_IMAGE_BAKE_SCHEMA = [
      PRIMARY KEY (pool)
    )`,
 ];
+export const IMAGE_BAKE_INDEXES = [
+    { table: "image_bake", name: "idx_image_bake_status", columns: ["status"] },
+    { table: "image_bake", name: "idx_image_bake_created", columns: ["created_at"] },
+];
 export async function ensurePgImageBakeSchema(pool, poolName = "standard") {
     for (const stmt of PG_IMAGE_BAKE_SCHEMA)
         await pool.query(stmt);
     await pool.query("INSERT INTO image_bake_admit (pool) VALUES ($1) ON CONFLICT (pool) DO NOTHING", [poolName]);
+    await ensureIndexes((t, p) => pool.query(t, p), "pg", IMAGE_BAKE_INDEXES);
 }
 const isDupKey = isDupKeyError;
 function dupKeyName(dialect, err) {

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*`)。