@sema-agent/server 7.82.0 → 7.83.0

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -41,6 +41,7 @@ import type { Pool as PgPool } from "pg";
 import type { PgQueryFn } from "./pg-query.js";
 import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
+import { type IndexSpec } from "./ensure-index.js";
 export type AskDecision = "approve" | "deny";
 export interface AskRow {
     askId: string;
@@ -449,6 +450,8 @@ export declare const TIDB_APPROVAL_ASK_STATEMENTS: readonly string[];
 /** {@link TIDB_APPROVAL_ASK_STATEMENTS} 的遍历壳——生产路径走 `tidb-pool.ts` 的中央 `ensureSchema`
  *  (那里展开了同一份数组),本函数留给只需要这两张表的集成测试。 */
 export declare function ensureTiDBApprovalAskSchema(pool: MySqlPool): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgApprovalAskSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const APPROVAL_ASK_INDEXES: readonly IndexSpec[];
 export declare function ensurePgApprovalAskSchema(q: PgQueryFn): Promise<void>;
 /**
  * [ref] 升级前置断言 —— **拒启**,不是 warn(形照 [ref] 的 `assertPermissionRuleApprovalSchema` /

package/dist/plugins/approval-ask-store-sql.js

@@ -1,6 +1,7 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { canAskTransition } from "../approval-ask-machine.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
+import { ensureIndexes } from "./ensure-index.js";
 export function assertIntegralEpochMs(field, value) {
     if (!Number.isSafeInteger(value)) {
         throw new TypeError(`approval-ask store: ${field} must be an integer epoch-ms (BIGINT column), got ${String(value)}`);
@@ -126,6 +127,13 @@ export async function ensureTiDBApprovalAskSchema(pool) {
     for (const stmt of TIDB_APPROVAL_ASK_STATEMENTS)
         await pool.query(stmt);
 }
+export const APPROVAL_ASK_INDEXES = [
+    { table: `${APPROVAL_BATCH_TABLE}`, name: "idx_batch_task", columns: ["task_id"] },
+    { table: `${APPROVAL_ASK_TABLE}`, name: "idx_ask_task_state", columns: ["task_id", "state"] },
+    { table: `${APPROVAL_ASK_TABLE}`, name: "idx_ask_session_state", columns: ["session_id", "state"] },
+    { table: `${APPROVAL_ASK_TABLE}`, name: "idx_ask_batch", columns: ["batch_id"] },
+    { table: `${APPROVAL_ASK_TABLE}`, name: "idx_ask_state", columns: ["state"] },
+];
 export async function ensurePgApprovalAskSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${APPROVAL_BATCH_TABLE} (
     batch_id VARCHAR(64) COLLATE "C" NOT NULL,
@@ -137,7 +145,6 @@ export async function ensurePgApprovalAskSchema(q) {
     updated_at_ms BIGINT NOT NULL,
     PRIMARY KEY (batch_id)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_batch_task ON ${APPROVAL_BATCH_TABLE} (task_id)`);
     await q(`CREATE TABLE IF NOT EXISTS ${APPROVAL_ASK_TABLE} (
     ask_id VARCHAR(64) COLLATE "C" NOT NULL,
     task_id VARCHAR(64) COLLATE "C" NOT NULL,
@@ -179,10 +186,7 @@ export async function ensurePgApprovalAskSchema(q) {
     -- (task_id, idempotency_key) 复合唯一——MySQL twin 逐字同形(改动理由见那侧注)。
     CONSTRAINT uq_approval_ask_idem UNIQUE (task_id, idempotency_key)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_ask_task_state ON ${APPROVAL_ASK_TABLE} (task_id, state)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_ask_session_state ON ${APPROVAL_ASK_TABLE} (session_id, state)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_ask_batch ON ${APPROVAL_ASK_TABLE} (batch_id)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_ask_state ON ${APPROVAL_ASK_TABLE} (state)`);
+    await ensureIndexes(q, "pg", APPROVAL_ASK_INDEXES);
 }
 export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
     try {

package/dist/plugins/background-agent-store-sql.d.ts

@@ -32,6 +32,7 @@
 import type { Pool } from "mysql2/promise";
 import { type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentStore } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
+import { type IndexSpec } from "./ensure-index.js";
 export declare const BACKGROUND_AGENT_TABLE = "background_agent";
 type ReapOpts = {
     maxAgeMs?: number;
@@ -43,6 +44,8 @@ type ListOpts = {
     limit?: number;
 };
 export declare function ensureTiDBBackgroundAgentSchema(pool: Pool): Promise<void>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgBackgroundAgentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const BACKGROUND_AGENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgBackgroundAgentSchema(q: PgQueryFn): Promise<void>;
 export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
     private readonly pool;

package/dist/plugins/background-agent-store-sql.js

@@ -1,6 +1,7 @@
 import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, } from "@sema-agent/core";
 import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
 const SUMMARY_COLS = "handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json";
 const PROJ_COLS = "scope, owner, session_scoped, session_id, parent_session_id, root_session_id, session_anchor, name, agent_type, status, spawned_at_ms, updated_at_ms, settled_at_ms, usage_json, rev, parked_checkpoint_token, park_claim_id, admitted_org_scopes, admitted_org_write_scope, record_json";
@@ -135,7 +136,12 @@ export async function ensureTiDBBackgroundAgentSchema(pool) {
     KEY idx_bga_anchor (scope_key, session_anchor, spawned_at_ms),
     KEY idx_bga_status (scope_key, status, updated_at_ms)
   ) COLLATE utf8mb4_bin`);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", BACKGROUND_AGENT_INDEXES);
 }
+export const BACKGROUND_AGENT_INDEXES = [
+    { table: `${BACKGROUND_AGENT_TABLE}`, name: "idx_bga_anchor", columns: ["scope_key", "session_anchor", "spawned_at_ms"] },
+    { table: `${BACKGROUND_AGENT_TABLE}`, name: "idx_bga_status", columns: ["scope_key", "status", "updated_at_ms"] },
+];
 export async function ensurePgBackgroundAgentSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${BACKGROUND_AGENT_TABLE} (
     scope_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -165,8 +171,7 @@ export async function ensurePgBackgroundAgentSchema(q) {
     record_json TEXT COLLATE "C" NOT NULL,
     PRIMARY KEY (scope_key, handle)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_bga_anchor ON ${BACKGROUND_AGENT_TABLE} (scope_key, session_anchor, spawned_at_ms)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_bga_status ON ${BACKGROUND_AGENT_TABLE} (scope_key, status, updated_at_ms)`);
+    await ensureIndexes(q, "pg", BACKGROUND_AGENT_INDEXES);
 }
 export class TiDBBackgroundAgentStore {
     pool;

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

@@ -47,6 +47,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 AcquireConnectionInput, type AcquireConnectionResult, type AppendAuditInput, type BindSessionInput, type BindSessionResult, type ConsumeEnrollTokenInput, type ConsumeEnrollTokenResult, type DeviceAdmissionView, type DeviceAuditRow, type DeviceEnrollTokenRow, type DeviceOwner, type DeviceRow, type DeviceSessionRow, type DeviceStore, type HeartbeatConnectionInput, type IssueEnrollTokenInput, type ListAuditFilter, type RebindSessionInput, type RebindSessionResult, type RevokeDeviceInput, type RevokeDeviceResult } from "../device-store.js";
+import { type IndexSpec } from "./ensure-index.js";
 /**
  * ── 命名(**落库一律单数**,与设计稿的复数形不同)──────────────────────────────────────────────────
  * design v2 §6 的 DDL 写的是 `devices` / `device_sessions` / `device_enrollment_tokens`(复数),但本仓有一条
@@ -63,6 +64,8 @@ export declare const TIDB_DEVICE_STATEMENTS: readonly string[];
 /** {@link TIDB_DEVICE_STATEMENTS} 的遍历壳(集成测试用;生产装配由中央 ensureSchema 展开同一份数组)。 */
 export declare function ensureTiDBDeviceSchema(pool: MySqlPool): Promise<void>;
 type PgQuery = (sql: string, params?: unknown[]) => Promise<unknown>;
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgDeviceSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const DEVICE_INDEXES: readonly IndexSpec[];
 export declare function ensurePgDeviceSchema(q: PgQuery): Promise<void>;
 /**
  * O4 升级前置探针 —— **拒启,不是 warn**([ref]/[ref]/[ref] `assert*Schema` 族先例):`device_audit` 的

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

@@ -1,6 +1,7 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isCheckViolationError } from "./sql-errors.js";
 import { DEVICE_AUDIT_EVENTS, assertAcquireShape, assertDeviceIdShape, assertDeviceOwnerShape, assertEnrollTokenHashShape, assertIssueTokenShape, assertNewDeviceShape, assertRebindShape, assertRevokeShape, assertRootSessionIdShape, assertWholeSeconds, parseDeviceAuditEvent, parseDevicePlatformOs, parseDeviceStatus, } from "../device-store.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const DEVICES_TABLE = "device";
 export const DEVICE_ENROLL_TOKENS_TABLE = "device_enroll_token";
 export const DEVICE_SESSIONS_TABLE = "device_session";
@@ -84,7 +85,14 @@ export const TIDB_DEVICE_STATEMENTS = [
 export async function ensureTiDBDeviceSchema(pool) {
     for (const stmt of TIDB_DEVICE_STATEMENTS)
         await pool.query(stmt);
+    await ensureIndexes((text, params) => pool.query(text, params), "mysql", DEVICE_INDEXES);
 }
+export const DEVICE_INDEXES = [
+    { table: `${DEVICES_TABLE}`, name: "idx_device_owner", columns: ["owner_tenant", "owner_subject"] },
+    { table: `${DEVICE_SESSIONS_TABLE}`, name: "idx_device_session_device", columns: ["device_id"] },
+    { table: `${DEVICE_AUDIT_TABLE}`, name: "idx_device_audit_device", columns: ["device_id", "at"] },
+    { table: `${DEVICE_AUDIT_TABLE}`, name: "idx_device_audit_event", columns: ["event", "at"] },
+];
 export async function ensurePgDeviceSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${DEVICES_TABLE} (
     device_id        VARCHAR(64)  COLLATE "C" NOT NULL,
@@ -112,7 +120,6 @@ export async function ensurePgDeviceSchema(q) {
     PRIMARY KEY (device_id),
     CONSTRAINT ${UQ_DEVICES_PUBKEY} UNIQUE (owner_tenant, pubkey)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_device_owner ON ${DEVICES_TABLE} (owner_tenant, owner_subject)`);
     await q(`CREATE TABLE IF NOT EXISTS ${DEVICE_ENROLL_TOKENS_TABLE} (
     token_hash        VARCHAR(128) COLLATE "C" NOT NULL,
     target_tenant     VARCHAR(190) COLLATE "C" NOT NULL,
@@ -135,7 +142,6 @@ export async function ensurePgDeviceSchema(q) {
     rev             BIGINT       NOT NULL DEFAULT 0,
     PRIMARY KEY (root_session_id)
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_device_session_device ON ${DEVICE_SESSIONS_TABLE} (device_id)`);
     await q(`CREATE TABLE IF NOT EXISTS ${DEVICE_AUDIT_TABLE} (
     id            BIGSERIAL    PRIMARY KEY,
     at            TIMESTAMPTZ(3) NOT NULL DEFAULT now(),
@@ -146,8 +152,7 @@ export async function ensurePgDeviceSchema(q) {
     detail        JSONB,
     CONSTRAINT ck_device_audit_event CHECK (event IN (${AUDIT_EVENT_CHECK}))
   )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_device_audit_device ON ${DEVICE_AUDIT_TABLE} (device_id, at)`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_device_audit_event ON ${DEVICE_AUDIT_TABLE} (event, at)`);
+    await ensureIndexes(q, "pg", DEVICE_INDEXES);
 }
 export async function assertDeviceAuditRebindEventSchema(db) {
     const conn = await db.connect();

package/dist/plugins/ensure-index.d.ts

@@ -0,0 +1,42 @@
+/** 本原语认得的两种方言(闭集;新方言进来是编译期的事,不是运行期的 `default` 臂)。 */
+export type SqlDialect = "mysql" | "pg";
+/**
+ * 一条索引的**声明**(纯数据)。两方言共用同一份声明 —— 这就是"一处属主"的兑现物:
+ * per-store 文件各导出自己那份 `readonly IndexSpec[]`,PG 侧由该 store 的 `ensurePg*Schema` 应用,
+ * MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 统一应用(与 `SCHEMA_STATEMENTS` 的组合姿势同形)。
+ */
+export interface IndexSpec {
+    /** 表名(与两方言的 `CREATE TABLE` 同名——本仓两方言表名逐字相同)。 */
+    readonly table: string;
+    /** 索引名(两方言同名;MySQL 侧它同时是 `CREATE TABLE` 里那条内联 `KEY` 的名字)。 */
+    readonly name: string;
+    /** 列序(等值前缀在前、排序列在后;与 MySQL 内联 `KEY` 的列序**必须**逐字一致)。 */
+    readonly columns: readonly string[];
+    /** UNIQUE 索引(MySQL 内联 `UNIQUE KEY` 的孪生)。缺省 = 普通索引。 */
+    readonly unique?: boolean;
+}
+/**
+ * 两方言的查询面。mysql2 的 `conn.query` 答 `[rows, fields]`,node-pg 答 `{ rows }` —— 两种形的读法
+ * 都关在本文件里(调用点只管把自己手上那只 `query` 传进来)。
+ *
+ * 🔴 **本原语一条绑定参数都不发**(探针与 DDL 全是字面量)。两条理由:
+ *  ① 它的输入是**声明**不是数据 —— `IndexSpec` 的表名/索引名都是编译期常量,没有用户输入可注入,
+ *     字面量与占位符在安全性上等价;
+ *  ② PG 那半的 `q` 是**调用方递进来的** `PgQueryFn`(十来个 `ensurePg*Schema` 都收它),而那些 ensure
+ *     腿在本批之前**从不带参**,于是仓里真有丢掉 `params` 只转发 sql 的包装(如
+ *     `test/permission-rule-store-db-integration.test.ts` 的 `(sql) => db.query(sql, [])`)。一条带 `$1`
+ *     的探针会在那种包装上报 `there is no parameter $1` —— 而那是**调用方**的形,不是本原语能管的。
+ *     不带参 ⇒ 这一整类接缝脆弱性结构上不存在。两方言同律,不留一边带参一边不带的不对称。
+ */
+export type IndexQueryFn = (sql: string, params?: unknown[]) => Promise<unknown>;
+/**
+ * 幂等地保证一条索引在场。**这是本仓唯一允许发加索引 DDL 的地方**(SCHEMA POLICY 窄放的全部内容)。
+ *
+ * @param q       方言对应的查询面(mysql2 conn/pool 的 `query`,或裸 `PgQueryFn`)
+ * @param dialect 方言闭集
+ * @param spec    索引声明(两方言共用同一份)
+ */
+export declare function ensureIndex(q: IndexQueryFn, dialect: SqlDialect, spec: IndexSpec): Promise<void>;
+/** {@link ensureIndex} 的**逐条串行**遍历(DDL 并发打同一张表会踩 catalog 竞争,故不并行)。 */
+export declare function ensureIndexes(q: IndexQueryFn, dialect: SqlDialect, specs: readonly IndexSpec[]): Promise<void>;
+//# sourceMappingURL=ensure-index.d.ts.map

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(",")}]`;