@sema-agent/server 7.82.1 → 7.84.0

package/dist/observability/run-terminal-log.js

@@ -104,7 +104,7 @@ const RESULT_KEY_TREATMENT = {
     effectiveWriteFace: "verbatim",
     effectiveReadDenyPatterns: "verbatim",
     effectiveMemoryScopes: "verbatim",
-    stats: "verbatim",
+    stats: "redacted",
 };
 const LEGACY_RESULT_LEAVES = ["errorMessage", "blockedReason", "checkpointGate"];
 export const REDACTABLE_RESULT_LEAVES = [
@@ -207,6 +207,13 @@ export function redactTerminalResult(result) {
             : r.rewindNotes;
         changed = true;
     }
+    if (r.stats !== undefined) {
+        const next = redactStats(r.stats);
+        if (next !== r.stats) {
+            out.stats = next;
+            changed = true;
+        }
+    }
     return changed ? out : result;
 }
 export function redactLedgerEventData(type, data) {
@@ -317,6 +324,108 @@ export function redactRiskDescriptor(rd) {
     }
     return changed ? out : rd;
 }
+const STATS_KEY_TREATMENT = {
+    turns: "verbatim",
+    tokens: "verbatim",
+    toolCalls: "verbatim",
+    usageMissing: "verbatim",
+    promptTokens: "verbatim",
+    cachedTokens: "verbatim",
+    cacheWriteTokens: "verbatim",
+    cacheHitRate: "verbatim",
+    totalInputTokens: "verbatim",
+    outputTokens: "verbatim",
+    cacheWriteTokensLong: "verbatim",
+    costMicroUsd: "verbatim",
+    nested: "verbatim",
+    memory: "verbatim",
+    suggestions: "verbatim",
+    costBreakdown: "verbatim",
+    mechanisms: "mechanisms",
+    humanReview: "human-review",
+};
+const STATS_MECHANISMS_TREATMENT = {
+    finalVerifyInjected: "verbatim",
+    finalVerifyInjections: "verbatim",
+    attachmentsInjected: "verbatim",
+    approachNoticesSent: "verbatim",
+    repetitionCuts: "verbatim",
+    repetitionSpared: "verbatim",
+    repetitionEvents: "repetition-rows",
+    reminderDisclosures: "verbatim",
+};
+const STATS_HUMAN_REVIEW_TREATMENT = {
+    count: "verbatim",
+    totalWaitMs: "verbatim",
+    gates: "gate-rows",
+};
+const STATS_GATE_ROW_TREATMENT = {
+    kind: "verbatim",
+    waitMs: "verbatim",
+    decision: "verbatim",
+    toolName: "verbatim",
+    toolArg: "model-text",
+};
+const STATS_REPETITION_EVENT_TREATMENT = {
+    turn: "verbatim",
+    action: "verbatim",
+    rule: "verbatim",
+    period: "verbatim",
+    reps: "verbatim",
+    segment: "model-text",
+};
+function redactStatsNode(node, table) {
+    if (node === null || typeof node !== "object" || Array.isArray(node))
+        return node;
+    const n = node;
+    let changed = false;
+    const out = { ...n };
+    const into = (v, t) => redactStatsNode(v, t);
+    const rows = (v, t) => {
+        if (!Array.isArray(v))
+            return v;
+        const next = v.map((row) => redactStatsNode(row, t));
+        return next.every((x, i) => x === v[i]) ? v : next;
+    };
+    for (const [key, treatment] of Object.entries(table)) {
+        const v = n[key];
+        if (v === undefined)
+            continue;
+        let next = v;
+        switch (treatment) {
+            case "verbatim":
+                break;
+            case "model-text":
+                if (typeof v === "string")
+                    next = redactModelText(v);
+                break;
+            case "mechanisms":
+                next = into(v, STATS_MECHANISMS_TREATMENT);
+                break;
+            case "human-review":
+                next = into(v, STATS_HUMAN_REVIEW_TREATMENT);
+                break;
+            case "gate-rows":
+                next = rows(v, STATS_GATE_ROW_TREATMENT);
+                break;
+            case "repetition-rows":
+                next = rows(v, STATS_REPETITION_EVENT_TREATMENT);
+                break;
+            default: {
+                const unhandled = treatment;
+                throw new Error(`unhandled stats treatment: ${String(unhandled)}`);
+            }
+        }
+        if (next !== v) {
+            out[key] = next;
+            changed = true;
+        }
+    }
+    return changed ? out : node;
+}
+function redactStats(stats) {
+    return redactStatsNode(stats, STATS_KEY_TREATMENT);
+}
 const CHECKPOINT_GATE_TREATMENT = {
     kind: "verbatim",
     reason: "text",
@@ -383,7 +492,6 @@ export function redactDiagnosticText(text) {
 export function redactHead(text, keep) {
     return redactDiagnosticText(text).slice(0, keep);
 }
-export const OVERSIZED_PATCH_PLACEHOLDER = "«redacted:oversized-patch-not-inlined»";
 function diffScanRefusal(patch, direct) {
     if (/^diff --(?:cc|combined) |^@{3,} /m.test(patch))
         return "combined-diff";
@@ -415,25 +523,6 @@ function diffScanRefusal(patch, direct) {
     }
     return undefined;
 }
-export function redactPatchHead(patch, keep) {
-    if (patch.length > DIAG_INPUT_CAP) {
-        recordFailOpen("server.run-terminal.patch-head-cut", `not-inlined len=${patch.length} keep=${keep}`);
-        return `${OVERSIZED_PATCH_PLACEHOLDER} [len=${patch.length}]`;
-    }
-    try {
-        const direct = redactSecrets(patch);
-        const refusal = diffScanRefusal(patch, direct);
-        if (refusal !== undefined) {
-            recordFailOpen("server.run-terminal.patch-head-cut", `${refusal} len=${patch.length} keep=${keep}`);
-            return `${OVERSIZED_PATCH_PLACEHOLDER} [len=${patch.length}]`;
-        }
-        return direct.slice(0, keep);
-    }
-    catch (err) {
-        recordFailOpen("server.run-terminal.redact-threw", `patch-head len=${patch.length} err=${err instanceof Error ? err.name : String(err)}`);
-        return OVERSIZED_REDACTION_PLACEHOLDER;
-    }
-}
 export function redactTail(text, keep) {
     return redactDiagnosticText(text).slice(-keep);
 }
@@ -506,6 +595,15 @@ export function redactLeaderResultWithFlag(result) {
             m.measure = { ...measure, reason: str(measure.reason) };
         out.merge = m;
     }
+    const conflict = obj(r.conflict);
+    if (conflict) {
+        const c = { ...conflict };
+        if (typeof conflict.rejHead === "string")
+            c.rejHead = art(conflict.rejHead);
+        if (Array.isArray(conflict.files))
+            c.files = conflict.files.map((f) => (typeof f === "string" ? str(f) : f));
+        out.conflict = c;
+    }
     const cp = obj(r.candidatePatch);
     if (cp)
         out.candidatePatch = { ...cp, ...(typeof cp.reason === "string" ? { reason: str(cp.reason) } : {}), ...(typeof cp.patch === "string" ? { patch: art(cp.patch) } : {}) };

package/dist/plugins/adoption-log-sql.d.ts

@@ -24,6 +24,7 @@ import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver, type SqlExec, type SqlTxConn } from "./sql-driver.js";
 import type { AdoptionRejectCode } from "../adoption/wire.js";
+import { type IndexSpec } from "./ensure-index.js";
 export declare const ADOPTION_LOG_TABLE = "adoption_log";
 /** 弧的阶段(183 §3.2 根级状态机的 form b 投影)。**单调**,只增不减。 */
 export declare const ADOPTION_PHASE: {
@@ -106,6 +107,8 @@ export interface AdoptionLogStore {
 /** MySQL 协议方言的建表语句(展开进 tidb-pool 的中央 `SCHEMA_STATEMENTS`,与 approval-ask 同姿势:
  *  跟着中央 ensureSchema 在 named-lock 的那条 conn 上建,不绕开 DDL 串行化)。 */
 export declare const TIDB_ADOPTION_LOG_STATEMENTS: readonly string[];
+/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgAdoptionLogSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const ADOPTION_LOG_INDEXES: readonly IndexSpec[];
 /** PostgreSQL 孪生(由 `ensurePgSchema` 在 advisory lock 的那条 client 上调用)。 */
 export declare function ensurePgAdoptionLogSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
 /**

package/dist/plugins/adoption-log-sql.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { ensureIndexes } from "./ensure-index.js";
 export const ADOPTION_LOG_TABLE = "adoption_log";
 export const ADOPTION_PHASE = {
     INTENT: 2,
@@ -30,6 +31,9 @@ export const TIDB_ADOPTION_LOG_STATEMENTS = [
      KEY idx_adoption_log_state (state)
    ) COLLATE utf8mb4_bin`,
 ];
+export const ADOPTION_LOG_INDEXES = [
+    { table: `${ADOPTION_LOG_TABLE}`, name: "idx_adoption_log_state", columns: ["state"] },
+];
 export async function ensurePgAdoptionLogSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${ADOPTION_LOG_TABLE} (
      adoption_id    VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -48,7 +52,7 @@ export async function ensurePgAdoptionLogSchema(q) {
      PRIMARY KEY (adoption_id),
      CONSTRAINT uq_adoption_log_from UNIQUE (from_principal)
    )`);
-    await q(`CREATE INDEX IF NOT EXISTS idx_adoption_log_state ON ${ADOPTION_LOG_TABLE} (state)`);
+    await ensureIndexes(q, "pg", ADOPTION_LOG_INDEXES);
 }
 const COLS = "adoption_id, from_principal, to_principal, phase, state, legs, configs, report, reject_code, reject_detail, created_at_ms, updated_at_ms";
 function toRow(r) {

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) {