@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/checkpoint-store-face.d.ts

@@ -3,8 +3,9 @@
  * (运维队列 / 审批决断 / 续跑腿 / 流内审批收敛器 / 起服普查)共同读的那一层 —— 引擎的 `CheckpointStore` 契约之外、本服务自己定的东西:
  *  · 行形:运维队列行 {@link PendingCheckpoint}、流内审批候选行 {@link CheckpointAskCandidate}、已决回放行 {@link DecidedApprovalRecord};
  *  · 读口的行绑定 {@link PendingRowBinding} 与门型两分({@link LIVE_RUN_GATE_KINDS} / {@link TERMINAL_PARK_GATE_KINDS}),两孪生同序判据 {@link pendingRowPrecedes};
- *  · 两孪生同调的纯判据与投影:{@link queueRowGateKind}、{@link boundedToolInput}、{@link boundedRuleOffers}、
- *    {@link approvalDecisionOfWinner}、{@link candidateIdentityOf};常量 {@link TERMINAL_BACKSTOP_MS} / {@link TERMINAL_GRACE_MS} / {@link DECIDED_REPLAY_SCAN_CAP};
+ *  · 两孪生同调的纯判据与投影:{@link queueRowGateKind}、{@link isUnreadableSummaryForm}、{@link readRiskDescriptorBody}、{@link boundedToolInput}、{@link boundedRuleOffers}、
+ *    {@link approvalDecisionOfWinner}、{@link candidateIdentityOf};待决行的分诊序 {@link pendingTriageOrder} / {@link queueTriageOrder}(两孪生 + 助手收件箱);
+ *    常量 {@link TERMINAL_BACKSTOP_MS} / {@link TERMINAL_GRACE_MS} / {@link DECIDED_REPLAY_SCAN_CAP} / {@link DENY_SWEEP_PAGE_ROWS};SLA 拒扫选行读口的行形与游标 {@link ExpiredApprovalGate} / {@link ExpiredGatePosition};
  *  · ctx 两口的结局词 {@link CtxClaimRewrite} 与一次性迁移的 ctx 行改写店腿的型(随最后一条用它的迁移删,见 {@link CheckpointCtxRowsRewriter});
  *  · 店拒绝契约里「一行字节读不成检查点」那一只 {@link UnreadableCheckpointRowError}(SQL 孪生抛、续跑腿认)。
  *
@@ -13,7 +14,7 @@
  * SQL 孪生的文件里;它住这里,SQL 孪生经一条点名的已知欠边借它 —— 这一条边就是阶段三搬家时「服务特有面」的清单(向引擎请托的候选,只列不发)。
  * 这里零 SQL:SQL 文本、列读法与行投影仍在 SQL 孪生里。
  */
-import { type Checkpoint, type CheckpointGate, type CheckpointRowVerdict, type GateOutcome, type ResolvedOutcome, type RiskDescriptor, type ToolApprovalCard } from "@sema-agent/core";
+import { type Checkpoint, type CheckpointGate, type CheckpointRowVerdict, type CheckpointSummary, type GateOutcome, type ResolvedOutcome, type RiskDescriptor, type ToolApprovalCard } from "@sema-agent/core";
 import { type ParkRowFacts, type RuleOfferProjection, type SkillCardFacts } from "../approval-card.js";
 import { StoreCorruptError } from "./sql-json-column.js";
 import type { SealedCheckpointCtx } from "../http/checkpoint-ctx.js";
@@ -58,6 +59,25 @@ export declare const TERMINAL_BACKSTOP_MS: number;
  * it never meaningfully delays the eventual crash-safe GC.
  */
 export declare const TERMINAL_GRACE_MS = 3600000;
+/**
+ * SLA 拒扫的一页(行数):每拍至多续跑尝试这么多张过期审批(每张是一次续跑 —— 拒扫的限流界)。唯一属主:两孪生选行读口的缺省页长与拒扫判「这一页满了没有」读同一个数。
+ */
+export declare const DENY_SWEEP_PAGE_ROWS = 100;
+/**
+ * 一张过期审批在 SLA 拒扫选行序上的位置 —— 两孪生同序:截止升序,同截止按 token 升序(SQL 孪生按列的排序规则比 token,LOCAL 孪生按 UTF-16 码元比;
+ * 各孪生的游标只回到它自己,所以只要各自的序与各自的「之后」谓词同一把尺子)。LOCAL 孪生的截止读不成有限数时取 `-Infinity`(引擎读作已过 ⇒ 排最前)。
+ * **进程内的游标**:拒扫腿拿它从上一拍读到的最后一行之后接着读,不上 wire、不落盘。
+ */
+export interface ExpiredGatePosition {
+    readonly deadline: number;
+    readonly token: string;
+}
+/** SLA 拒扫选行读口(`listExpiredApprovalGates`)的一行:会话、scope、它在选行序上的位置({@link ExpiredGatePosition})。 */
+export interface ExpiredApprovalGate {
+    readonly sessionId: string;
+    readonly scope: string;
+    readonly position: ExpiredGatePosition;
+}
 /** Non-secret view of a pending checkpoint for the operator approval queue — deliberately NO token.
  *
  *  🔴 [ref]:行**顶层**另带 {@link ParkRowFacts}(`requiresRealApproval` / `ruleOffersAbsence`,真才带、缺席 ≠ false)——
@@ -97,13 +117,24 @@ export interface PendingCheckpoint extends ParkRowFacts, SkillCardFacts {
      *  ([ref], 7.132.0): every park stamps it, the one-time migration M21 filled any row without it from the row's gate,
      *  and a SQL row that still carries none is not listed by `listPending` (counted: `server.approvals.queue-row-gate-kind-missing`; no decide route binds it either). */
     gateKind: CheckpointGate["kind"];
-    /** The suspended run's taskId (task_active join) — the key to the run/trace ("view task context"). */
+    /**
+     * 🔴 [ref] —— **停在这道门上的那条腿以哪个 task 在跑**(唯一写者 {@link parkedLegTaskId};两只孪生各交自己手里的两格读数):
+     * 引擎铸这只停驻行时记下的那条腿的登记行(core `CheckpointState.rowTaskId` —— 后台委派子代的 `a…` 句柄,`/decide` 复活它的回执上的同一个 `taskId`;
+     * 不是 `/v1/runs/:id` 的键)⇒ 它;否则 = 持着这一行会话认领的那条 run(run 自己的停驻;停驻 / 待审的 run 不放认领;`/v1/runs/:id` 与 trace 的键);
+     * 两者都没有(同步 / workflow 委派子代、终局后的纯停驻)⇒ `null`。
+     */
     taskId: string | null;
     /** The pending tool call's args (post-hook), redacted + bounded — for tool_approval the write payload, for a
      *  durable AskUserQuestion the question itself. Lets the approval card render WITHOUT an N+1 trace.turns
      *  fetch. `null` for pre-migration rows (suspended before the column existed) ⇒ consumer falls back. */
     input: unknown;
-    createdAt: number;
+    /**
+     * 建行时刻(epoch ms)。SQL 孪生恒在场(本服务在存储体之外握着的建行时刻列)。LOCAL 孪生读引擎对这一行投的摘要(core `CheckpointSummary.createdAt`,同一可选性):
+     * 摘要读得出有限数才在场,读不出(存储体里不是有限数 —— 那一行判官判坏、`rowVerdict` 非 `ok`)⇒ **缺席**,从不把存储体里的原值搬上 wire。
+     * 排序读法见 {@link queueTriageOrder}(缺席计 0 = 档内最老)。
+     */
+    createdAt?: number;
+    /** 截止(epoch ms);没有截止 ⇒ `null`。LOCAL 孪生同读摘要:读不成有限数 ⇒ `null`(摘要不带它;到期两扫按引擎 `checkpointDeadlinePassed` 把它读作已过)。 */
     deadline: number | null;
     /** [ref] riskDescriptor inbox: core's INERT triage descriptor ({severity 1-5, axes, toolName, redacted
      *  summary, touchedPaths}) for human/irreversible_ask gates. listPending returns the queue severity-sorted
@@ -187,6 +218,19 @@ export interface PendingCheckpoint extends ParkRowFacts, SkillCardFacts {
      */
     rowVerdict?: CheckpointRowVerdict;
 }
+/**
+ * 🔴 [ref] —— 停驻行 {@link PendingCheckpoint.taskId} 的**唯一写者**:停在这道门上的那条腿以哪个 task 在跑。
+ *
+ * 两格读数,两只孪生各交自己手里的那一份(SQL 孪生:`checkpoint` 列的 `$.state.rowTaskId` 成员 + `task_active` 联结;local 孪生:同一行的
+ * `state.rowTaskId` + 文件 run 店的 `getActiveTaskId`):
+ *  · `recorded` —— 引擎铸这只停驻行时记下的那条腿的登记行(core `CheckpointState.rowTaskId`,每个铸点盖;只在后台车道的腿上在场 ——
+ *    顶层 run、同步子代、workflow 子代不盖)。它与行的会话(铸停驻那条腿的会话,[ref])是同一次铸、同一条腿的身份;本服务不另读后台 agent 行、
+ *    不按 scope 扫、不经会话元组(行上的 `agent.id`)回填;
+ *  · `claimHolder` —— 持着这一行会话认领的那条 run(顶层 run 引擎不盖登记行:那条腿就是 run 本身,本服务的 run 账本知道它)。
+ * 记录是一只非空串 ⇒ 它(行自己点名停在这道门上的那条腿;认领可能属于同会话上另一条 run)。构造上两者不同时在场:后台子代的会话不进 run 账本、不持认领。
+ * 记录读不成非空串(数 / 对象 / 空串 —— 被改过的行)⇒ 与没记同答:方向是少一个路由键,不放宽任何判;那一行续不续得了由它的 `rowVerdict` 另说。
+ */
+export declare function parkedLegTaskId(recorded: unknown, claimHolder: string | null): string | null;
 /**
  * [ref]([ref] / DEBTS [ref]):session 键读口(`findPendingTokenBySession` / `peekPendingScope`)的**行绑定**。
  *
@@ -228,6 +272,14 @@ export interface PendingRowBinding {
      *    赢家卡与被消费卡恒同一张(FIFO 顺带成立)。
      */
     pick?: "newest" | "oldest";
+    /**
+     * 按哪一只会话找(缺省 `"card"`)。一张卡的行上有两个会话事实,两个问题各读一只:
+     *  · `"card"`(缺省)—— 卡**自己的对话**(`checkpoint.session_id`):决断口 URL 里的会话、SLA 拒扫的复核、按会话唤醒 —— 地址就是卡停在的那段对话;
+     *  · `"run"` —— 卡**归属的那条 run 的会话**(`checkpoint.host_session_id`,读法 `checkpoint-index-columns.ts` 的 `hostSessionOf`):从 run 一侧找它等着的那张卡
+     *    (取消、steer 停放、活跃 run 409 的门材料、起服收回、本地收割探针、续跑输入回收、按 task 续跑的两扇门)。cascade 的级上卡两者不同:
+     *    卡在级自己现铸的对话里,归调用方的会话;其余每一张卡两者同值。
+     */
+    axis?: "card" | "run";
 }
 /** [ref]:一条**仍持有 claim 的 run** 可能停在的全部门型(= 除 `task_done` 外全部;派生自上表,不手抄)。
  *  给「按 run 行动」的读口用:cancel / steer 的 park 落点、409 `pendingGate` 材料 —— 这些腿手里有 run 行,
@@ -300,13 +352,32 @@ export declare class UnreadableCheckpointRowError extends StoreCorruptError {
 }
 /**
  * [ref] —— 运维队列行的门型:**两只孪生同一只判官**(SQL 孪生读 `gate_kind` 列 —— put 时从同一只门反范式下来的那一格,每次停驻都盖,一次性迁移 M21 把没有它的
- * 存量行从门子树补齐;local 孪生读快照上的门 `cp.gate.kind`)。
+ * 存量行从门子树补齐;local 孪生读引擎对这一行投的摘要上的 `gateKind` —— 门不是 core 登记的门型时摘要不带它)。
  * 读到的值是 NULL / 缺席 / 不是 core 登记的门型 ⇒ `undefined`:这一行**不列**(响亮:计一次 `server.approvals.queue-row-gate-kind-missing`)—— 与每一条决断口同一个读法:
  * 按门型绑定取行的读口对这种行本来就不命中(`pendingRowQuery` 的 `gate_kind IN (…)`,证不出门型就不当它是这道门),队列不再把一行谁也决不了的行投出去,
  * 也不按缺键投(消费方按 `gateKind` 路由、缺键即 fail-closed)。不整只拒:一行坏行不许让整个租户的队列(列表 500、SSE 心跳照常而队列永远停在旧帧)消失。
  * 按构造不可达(写口恒盖、M21 补齐);计数非零 = 写腿或手改出了错,按 `SELECT … WHERE status = 'pending' AND gate_kind IS NULL` 查那一行。
  */
 export declare function queueRowGateKind(kind: unknown): CheckpointGate["kind"] | undefined;
+export declare function isUnreadableSummaryForm(summary: CheckpointSummary): boolean;
+/**
+ * 运维队列行 `riskDescriptor` 那一格的**形读者**(两孪生同调这一只):SQL 孪生对 `risk_descriptor` 列解出来的体(`decodeJsonColumn`)、LOCAL 孪生对存储体里门上的
+ * `gate.riskDescriptor`。判到「是不是一只对象」为止 —— 描述符的键表属主在 core,core 没有导出它的验证器,手写一份就是第二份键集。读不出 ⇒ 这一行的描述符 `null` +
+ * 计 `server.approvals.risk-descriptor-cell-unreadable`(两孪生同一个 tag、同一失败方向;放行理由见登记表)。
+ */
+export declare const readRiskDescriptorBody: import("./sql-json-column.js").JsonColumnReader<RiskDescriptor>;
+/** 分诊序读的两格(运维队列行 = 描述符里的严重度;收件箱行 = 引擎摘要的严重度)。 */
+export interface TriageKeys {
+    readonly severity?: number | undefined;
+    readonly createdAt?: number | undefined;
+}
+/**
+ * 待决停驻行的**分诊序** —— 一只比较器,运维队列两孪生({@link queueTriageOrder})与助手收件箱同调:严重度降序,同档内 `createdAt` 升序(最老在前);
+ * 一格缺席或读不成有限数按 0 计 —— 确定性优于「看它恰好落在哪」,也不让一个非数让整只排序失去全序。与店的返回顺序无关(core 的 `listByScope` 零顺序声明)。
+ */
+export declare function pendingTriageOrder(a: TriageKeys, b: TriageKeys): number;
+/** 运维队列行的分诊序 = {@link pendingTriageOrder} 读行上描述符的严重度(两孪生的 `listPending` 同调)。 */
+export declare function queueTriageOrder(a: PendingCheckpoint, b: PendingCheckpoint): number;
 /** Redact + size-bound a pending tool call's args for persistence/serving. JSON-roundtrips so the stored shape
  *  matches what the operator queue serves; oversized payloads collapse to a marker rather than bloating the row.
  *  Exported for the LOCAL twin (local-checkpoint-store.ts) so the operator-queue projection can't drift. */
@@ -325,10 +396,10 @@ export interface CheckpointAskCandidate {
      * 🔴 和解三元组的第一维([ref] 件1,黑板 [ref]③①)—— checkpoint 自己带的 `sourceSessionId`(core 在
      * suspendAsk 铸行时恒填该腿的 `sessionId`)。**没有对应的列**,只能从 blob 窄读;读不出/缺席 = null。
      *
-     * 为什么必须进候选集:读口按 `(scope, session_id, tool_call_id)` 查,而委派子代那条腿的 ask 落行时
-     * `session_id` 记的是**投递上下文**(根会话),park 却发生在**子代自己**的 sessionId 上 —— 只靠
-     * (toolCallId, hash) 两维,一条根腿的 park 会被一只子代的 ask 认领(摘要相同的两次同 args 调用完全
-     * 正常)。三元组全同才算同一件事。
+     * 为什么必须进候选集:收敛器按 `(scope, session_id = 问的 sourceSessionId, tool_call_id)` 查,`session_id` 列是这只停车行
+     * 自己落在哪个会话(core 铸行时同一只变量也写进 blob 的 `sourceSessionId`)—— 列与 blob 两份陈述,身份等式比的是 blob 那一份:
+     * 列被外部改写 / 两份分家时,只靠 (toolCallId, hash) 两维会让别的会话的 park 被认领(摘要相同的两次同 args 调用完全正常)。
+     * 三元组全同才算同一件事。
      */
     sourceSessionId: string | null;
     /** 该 park 绑定的 tool call(= `pendingAction.toolCallId`)。`unparseable` 行为 null。 */
@@ -423,4 +494,6 @@ export declare function candidateIdentityOf(cp: Checkpoint): CandidateIdentity;
  *  `context_absent` 持有、但会话没有 ctx 行 ⇒ 零写(不建行)。 */
 export declare const CTX_CLAIM_REWRITES: readonly ["written", "claim_released", "context_absent"];
 export type CtxClaimRewrite = (typeof CTX_CLAIM_REWRITES)[number];
+/** 认领栅栏下**建或换**一行 ctx 的结局([ref];`putCtx` 的结局 —— 交认领的提交腿与续跑腿的写;不交认领恒 `written`):同一张词表去掉 `context_absent`(这一口没有行就建)。 */
+export type CtxClaimPut = Exclude<CtxClaimRewrite, "context_absent">;
 //# sourceMappingURL=checkpoint-store-face.d.ts.map

package/dist/plugins/checkpoint-store-face.js

@@ -1,11 +1,15 @@
 import { isGateKind, judgeCheckpointRow, MAX_RULE_TEXT_CHARS, } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "../trace/redact.js";
 import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, readRuleOfferList } from "../approval-card.js";
-import { StoreCorruptError } from "./sql-json-column.js";
+import { createObjectColumnReader, StoreCorruptError } from "./sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 const MAX_TOOL_INPUT_CHARS = 8192;
 export const TERMINAL_BACKSTOP_MS = Math.max(60_000, (Number.isFinite(Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS)) ? Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) : 0) || 30 * 86_400_000);
 export const TERMINAL_GRACE_MS = 3_600_000;
+export const DENY_SWEEP_PAGE_ROWS = 100;
+export function parkedLegTaskId(recorded, claimHolder) {
+    return typeof recorded === "string" && recorded.length > 0 ? recorded : claimHolder;
+}
 const GATE_KIND_IS_LIVE_RUN_PARK = {
     human: true,
     irreversible_ask: true,
@@ -81,6 +85,19 @@ export function queueRowGateKind(kind) {
     recordFailOpen("server.approvals.queue-row-gate-kind-missing", `gate_kind=${kind === null || kind === undefined ? "NULL" : redactSecrets(String(kind)).slice(0, 40)}`);
     return undefined;
 }
+const UNREADABLE_SUMMARY_MEMBERS = new Set(["token", "rowVerdict", "sessionId", "scope", "gateKind", "createdAt", "deadline"]);
+export function isUnreadableSummaryForm(summary) {
+    const names = UNREADABLE_SUMMARY_MEMBERS;
+    return summary.rowVerdict.kind !== "ok" && Object.keys(summary).every((member) => names.has(member));
+}
+export const readRiskDescriptorBody = createObjectColumnReader();
+const triageKey = (v) => (v !== undefined && Number.isFinite(v) ? v : 0);
+export function pendingTriageOrder(a, b) {
+    return triageKey(b.severity) - triageKey(a.severity) || triageKey(a.createdAt) - triageKey(b.createdAt);
+}
+export function queueTriageOrder(a, b) {
+    return pendingTriageOrder({ severity: a.riskDescriptor?.severity, createdAt: a.createdAt }, { severity: b.riskDescriptor?.severity, createdAt: b.createdAt });
+}
 export function boundedToolInput(args) {
     if (args === undefined)
         return null;

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

@@ -80,6 +80,7 @@ export async function ensureTiDBDeviceSchema(pool) {
 }
 export const DEVICE_INDEXES = [
     { table: `${DEVICES_TABLE}`, name: "idx_device_owner", columns: ["owner_tenant", "owner_subject"] },
+    { table: `${DEVICES_TABLE}`, name: UQ_DEVICES_PUBKEY, columns: ["owner_tenant", "pubkey"], unique: true },
     { 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"] },
 ];

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

@@ -1,4 +1,5 @@
 import type { SqlDialect } from "./sql-driver.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 /**
  * 一条索引的**声明**(纯数据)。两方言共用同一份声明 —— 这就是"一处属主"的兑现物:
  * per-store 文件各导出自己那份 `readonly IndexSpec[]`,PG 侧由该 store 的 `ensurePg*Schema` 应用,
@@ -11,7 +12,7 @@ export interface IndexSpec {
     readonly name: string;
     /** 列序(等值前缀在前、排序列在后;与 MySQL 内联 `KEY` 的列序**必须**逐字一致)。 */
     readonly columns: readonly string[];
-    /** UNIQUE 索引(MySQL 内联 `UNIQUE KEY` 的孪生)。缺省 = 普通索引。 */
+    /** UNIQUE 索引(MySQL 内联 `UNIQUE KEY` / PG 表约束 `CONSTRAINT … UNIQUE` 的孪生)。缺省 = 普通索引。唯一索引多一道判形(头注「唯一索引」),列集按**集合**比。 */
     readonly unique?: boolean;
 }
 /**
@@ -28,6 +29,17 @@ export interface IndexSpec {
  *     不带参 ⇒ 这一整类接缝脆弱性结构上不存在。两方言同律,不留一边带参一边不带的不对称。
  */
 export type IndexQueryFn = (sql: string, params?: unknown[]) => Promise<unknown>;
+/**
+ * 唯一索引的确定拒启(头注「唯一索引」)。`kind`:`shape` = 同名在场而形不对;`duplicates` = 存量重复行让建索引失败。
+ * 继承 {@link StoreBootRefusalError}:SQL 开库的等待窗不重试它、「库打不开」的拒句不改写它。
+ */
+export declare class UniqueIndexRefusalError extends StoreBootRefusalError {
+    readonly kind: "shape" | "duplicates";
+    readonly spec: IndexSpec;
+    constructor(kind: "shape" | "duplicates", spec: IndexSpec, message: string, options?: {
+        readonly cause: unknown;
+    });
+}
 /**
  * 幂等地保证一条索引在场。**这是本仓唯一允许发加索引 DDL 的地方**(SCHEMA POLICY 窄放的全部内容)。
  *

package/dist/plugins/ensure-index.js

@@ -1,5 +1,7 @@
 import { recordFailOpen } from "../observability/fail-open.js";
 import { readLiveColumns } from "./schema-live-columns.js";
+import { isDupKeyErrorOfWrappedQuery } from "./sql-errors.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 function rowsOf(res) {
     if (Array.isArray(res)) {
         const first = res[0];
@@ -19,11 +21,120 @@ function lacksConcurrentlySupport(err) {
         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)})`));
+const EXPRESSION_PART = "<expression>";
+async function pgIndexLive(q, spec) {
+    const rows = rowsOf(await q("SELECT i.indisvalid AS indisvalid, i.indisunique AS indisunique, " +
+        "(i.indpred IS NULL AND i.indexprs IS NULL) AS whole, " +
+        "(SELECT c.relname::text FROM pg_class c WHERE c.oid = i.indrelid) AS tbl, " +
+        "(SELECT n.nspname::text FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = i.indrelid) AS nsp, " +
+        "COALESCE((SELECT string_agg(a.attname::text, ',' ORDER BY a.attname::text) FROM generate_series(0, i.indnkeyatts - 1) AS k(n) " +
+        "JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = i.indkey[k.n]), '') AS cols, " +
+        "EXISTS (SELECT 1 FROM pg_constraint k WHERE k.conindid = i.indexrelid AND k.contype = 'u') AS backs_constraint " +
+        "FROM pg_index i WHERE i.indexrelid = to_regclass(quote_ident((SELECT n.nspname FROM pg_class t JOIN pg_namespace n ON n.oid = t.relnamespace " +
+        `WHERE t.oid = to_regclass(${quoteLiteral(quoteId("pg", spec.table))}))) || '.' || quote_ident(${quoteLiteral(spec.name)}))`));
     if (rows.length === 0)
         return undefined;
-    return rows[0].indisvalid !== false;
+    const row = rows[0];
+    const schema = typeof row.nsp === "string" ? row.nsp : undefined;
+    const shape = typeof row.cols === "string" && typeof row.tbl === "string" && typeof row.indisunique === "boolean"
+        ? {
+            table: row.tbl,
+            schema,
+            unique: row.indisunique,
+            columns: row.cols === "" ? [] : row.cols.split(","),
+            whole: row.whole !== false,
+            constraint: row.backs_constraint === true,
+        }
+        : undefined;
+    return { valid: row.indisvalid !== false, schema, shape };
+}
+async function mysqlIndexRows(q, spec) {
+    const rows = rowsOf(await q(`SHOW INDEX FROM ${quoteId("mysql", spec.table)} WHERE Key_name = ${quoteLiteral(spec.name)}`));
+    return rows.map((r) => Object.fromEntries(Object.entries(r).map(([k, v]) => [k.toLowerCase(), v])));
+}
+function mysqlShapeOf(spec, rows) {
+    if (!rows.every((r) => "column_name" in r && "non_unique" in r))
+        return undefined;
+    const keyParts = [...rows].sort((a, b) => Number(a.seq_in_index) - Number(b.seq_in_index));
+    return {
+        table: spec.table,
+        schema: undefined,
+        unique: keyParts.every((r) => Number(r.non_unique) === 0),
+        columns: keyParts.map((r) => (isExpressionPart(r) ? EXPRESSION_PART : r.column_name)),
+        whole: keyParts.every((r) => r.sub_part === null || r.sub_part === undefined),
+        constraint: false,
+    };
+}
+const isExpressionPart = (r) => (typeof r.expression === "string" && r.expression !== "") || typeof r.column_name !== "string";
+const columnSet = (dialect, cols) => [...new Set(dialect === "mysql" ? cols.map((c) => c.toLowerCase()) : cols)].sort();
+function shapeProblem(dialect, spec, live) {
+    const problems = [];
+    if (live.table !== spec.table)
+        problems.push(`it is on table ${live.table}`);
+    if (!live.unique)
+        problems.push("it is not UNIQUE");
+    if (columnSet(dialect, live.columns).join(",") !== columnSet(dialect, spec.columns).join(",")) {
+        problems.push(`it covers (${live.columns.length === 0 ? "no plain key column" : live.columns.join(", ")})`);
+    }
+    if (!live.whole)
+        problems.push(dialect === "pg" ? "it is a partial or expression index" : "it is a prefix or expression index");
+    return problems.length === 0 ? undefined : problems.join("; ");
+}
+export class UniqueIndexRefusalError extends StoreBootRefusalError {
+    kind;
+    spec;
+    constructor(kind, spec, message, options) {
+        super(message, options);
+        this.kind = kind;
+        this.spec = spec;
+        this.name = "UniqueIndexRefusalError";
+    }
+}
+const declaredShape = (spec) => `UNIQUE (${spec.columns.join(", ")})`;
+function shapeRefusal(dialect, spec, live, problem) {
+    const name = quoteId(dialect, spec.name);
+    const where = live.schema === undefined ? "" : `${quoteId("pg", live.schema)}.`;
+    const drop = dialect === "mysql"
+        ? `ALTER TABLE ${quoteId("mysql", spec.table)} DROP INDEX ${name};`
+        : live.constraint
+            ? `ALTER TABLE ${where}${quoteId("pg", live.table)} DROP CONSTRAINT ${name};`
+            : `DROP INDEX CONCURRENTLY IF EXISTS ${where}${name};`;
+    return new UniqueIndexRefusalError("shape", spec, `ensureIndex: unique index ${spec.name} on table ${spec.table} is not the shape this build declares (${declaredShape(spec)}): ${problem} — refusing to start. ` +
+        "The name is taken, so the index is not rebuilt, and this build relies on it to reject duplicate rows. " +
+        `Way out: stop writers to ${spec.table}, run ${drop} and start again — the next start builds the index with the declared shape ` +
+        "(if rows already break it, that start refuses and names the duplicates). Until it is rebuilt nothing enforces the uniqueness.");
+}
+function duplicatesRefusal(dialect, spec, cause) {
+    const cols = columnList(dialect, spec);
+    const notNull = spec.columns.map((c) => `${quoteId(dialect, c)} IS NOT NULL`).join(" AND ");
+    const leftover = dialect === "pg" ? " The failed build leaves an INVALID index of that name; the next start drops and rebuilds it by itself." : "";
+    return new UniqueIndexRefusalError("duplicates", spec, `ensureIndex: unique index ${spec.name} on table ${spec.table} cannot be built — ${spec.table} already holds rows that share (${spec.columns.join(", ")}) — refusing to start, ` +
+        "because this build relies on this index to reject duplicate rows. " +
+        `Way out: find them with SELECT ${cols}, COUNT(*) FROM ${quoteId(dialect, spec.table)} WHERE ${notNull} GROUP BY ${cols} HAVING COUNT(*) > 1 ` +
+        "(rows with a NULL in any of these columns never conflict, so they are left out), remove or merge the extra rows — this build cannot choose which row survives — and start again; " +
+        `the next start builds the index.${leftover}`, { cause });
+}
+function isDuplicateKeyFailure(dialect, err) {
+    if (!isDupKeyErrorOfWrappedQuery(dialect, err))
+        return false;
+    switch (dialect) {
+        case "pg":
+            return Reflect.get(err, "constraint") !== "pg_class_relname_nsp_index";
+        case "mysql":
+            return true;
+        default: {
+            const _never = dialect;
+            throw new Error(`ensureIndex: 未知方言 ${String(_never)}`);
+        }
+    }
+}
+const failureOfBuild = (dialect, spec, err) => spec.unique === true && isDuplicateKeyFailure(dialect, err) ? duplicatesRefusal(dialect, spec, err) : err;
+function assertUniqueShape(dialect, spec, live) {
+    if (live === undefined)
+        return;
+    const problem = shapeProblem(dialect, spec, live);
+    if (problem !== undefined)
+        throw shapeRefusal(dialect, spec, live, problem);
 }
 const refusal = (spec, unique, what) => `ensureIndex: PostgreSQL 索引 ${spec.name}(表 ${spec.table})${what} —— 拒绝带病启动。` +
     "(一个 INVALID 索引会让此后每一次 CREATE INDEX … IF NOT EXISTS 静默跳过它,而规划器永不使用它。)" +
@@ -35,6 +146,8 @@ export async function ensureIndex(q, dialect, spec) {
         await applyIndex(q, dialect, spec);
     }
     catch (err) {
+        if (err instanceof UniqueIndexRefusalError)
+            throw err;
         let live;
         try {
             live = await readLiveColumns(async (sql) => rowsOf(await q(sql)), dialect);
@@ -54,40 +167,60 @@ function indexColumnMissing(live, spec) {
 async function applyIndex(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)
+            const present = await mysqlIndexRows(q, spec);
+            if (present.length > 0) {
+                if (spec.unique === true)
+                    assertUniqueShape("mysql", spec, mysqlShapeOf(spec, present));
                 return;
-            await q(`ALTER TABLE ${quoteId("mysql", spec.table)} ADD ${spec.unique ? "UNIQUE " : ""}INDEX ` +
-                `${quoteId("mysql", spec.name)} (${columnList("mysql", spec)})`);
+            }
+            try {
+                await q(`ALTER TABLE ${quoteId("mysql", spec.table)} ADD ${spec.unique ? "UNIQUE " : ""}INDEX ` +
+                    `${quoteId("mysql", spec.name)} (${columnList("mysql", spec)})`);
+            }
+            catch (err) {
+                throw failureOfBuild("mysql", spec, err);
+            }
             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)})`;
+            const build = async (sql) => {
+                try {
+                    await q(sql);
+                }
+                catch (err) {
+                    throw failureOfBuild("pg", spec, err);
+                }
+            };
             try {
-                await q(`CREATE ${tail}`);
+                await build(`CREATE ${tail}`);
             }
             catch (err) {
-                if (!lacksConcurrentlySupport(err))
+                if (err instanceof UniqueIndexRefusalError || !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)})`);
+                await build(`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)
+            let live = await pgIndexLive(q, spec);
+            if (live === undefined)
                 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 (!live.valid) {
+                await q(`DROP INDEX CONCURRENTLY IF EXISTS ${live.schema === undefined ? "" : `${quoteId("pg", live.schema)}.`}${name}`);
+                try {
+                    await build(`CREATE ${tail}`);
+                }
+                catch (err) {
+                    throw err instanceof UniqueIndexRefusalError ? err : new Error(refusal(spec, unique, "重建时失败"), { cause: err });
+                }
+                live = await pgIndexLive(q, spec);
+                if (live?.valid === false)
+                    throw new Error(refusal(spec, unique, "重建后仍是 INVALID"));
             }
-            if ((await pgIndexValid(q, spec.name)) === false)
-                throw new Error(refusal(spec, unique, "重建后仍是 INVALID"));
+            if (spec.unique === true)
+                assertUniqueShape("pg", spec, live?.shape);
             return;
         }
         default: {

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

@@ -1,29 +1,47 @@
-/**
- * 两方言启动锁(`ensureSchema` / `oneTimeMigrations` 的 MySQL `GET_LOCK(?,0)` 与 PG `pg_try_advisory_lock`)的
- * **轮询策略唯一属主**(7.83.0 修复验证 车HC HC-1/HC-2 后收口:此前两只孪生各抄一份循环,一份改了「永不放弃」
- * 另一份还是「40 次放弃后无锁跑」,而 [ref] 之后无锁跑的那条腿发的是不带 `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 抖动)—— 两方言同一条曲线。 */
+/** 抖动退避(~0.1s..0.4s + 至多 0.15s 抖动)—— 启动锁的曲线。 */
 export declare function lockProbeBackoffMs(attempt: number): number;
 /**
- * 轮到拿到为止。`tryOnce` = 方言自己的非阻塞探针:`true` 拿到、`false` 别人持着(继续轮)、抛 = 探针本身失败。
- * 初始抖动把 ~20 个在 t=0 同时开火的调用方(集成套扇出 / 同步的舰队启动)铺开。
+ * 一把库内具名锁的身份。两方言的「名字」不同形(引擎事实,不是口味):MySQL 协议一个字符串(服务器实例**全局**,上限 64 字符),
+ * PG 一个 bigint 键或一对 int4 键(**每库**;单键与双键是两个互不相交的键空间)。身份由属主模块各自铸(启动锁:`tidb-pool.ts` / `pg-pool.ts`;弧锁:`adoption-log-sql.ts`),
+ * 本模块只负责怎么取、怎么放。
+ */
+export type AdvisoryLockId = {
+    readonly dialect: "mysql";
+    readonly name: string;
+} | {
+    readonly dialect: "pg";
+    readonly keys: readonly [number] | readonly [number, number];
+};
+/**
+ * 取锁要的最小连接面:发一句带参 SQL、读回行。锁是**连接级**的 —— 调用方必须把取、放与锁罩住的全部语句跑在**同一条**连接上。
+ * `SqlTxConn`(`{ rows, affected }`)与 node-pg 的 `PoolClient`(`{ rows }`)天然满足;mysql2 的 `[rows, fields]` 由调用方一行适配。
+ */
+export interface LockConn {
+    query(sql: string, params: unknown[]): Promise<{
+        readonly rows: ReadonlyArray<Record<string, unknown>>;
+    }>;
+}
+/**
+ * 轮到拿到为止(启动锁的预算)。`tryOnce` = 方言自己的非阻塞探针:`true` 拿到、`false` 别人持着(继续轮)、抛 = 探针本身失败。
+ * 取锁调用方走 {@link acquireAdvisoryLock};本函数留给只想验循环律、不带连接的单测。
  */
 export declare function pollUntilLocked(tryOnce: () => Promise<boolean>, opts: {
     tag: string;
     label: string;
 }): Promise<void>;
+/**
+ * 在 `conn` 上取 `id`,**轮到拿到为止**(永不无锁跑;一条探针连续抛的连接上抛成起服失败)。
+ * 锁是连接级的:调用方必须把锁罩住的全部语句跑在这条 `conn` 上,并用 {@link releaseAdvisoryLock} 放。
+ */
+export declare function acquireAdvisoryLock(conn: LockConn, id: AdvisoryLockId, tag: string): Promise<void>;
+/**
+ * 在 `conn` 上取 `id`,**最多探 `attempts` 次、每次没拿到睡 `sleepMs`**(无开跑抖动:常路零额外延迟)。
+ * `true` = 拿到(调用方负责放);`false` = 用尽次数仍是「别人持着」(调用方按「在飞」应答)。其余同 {@link acquireAdvisoryLock}。
+ */
+export declare function acquireAdvisoryLockWithin(conn: LockConn, id: AdvisoryLockId, tag: string, attempts: number, sleepMs: number): Promise<boolean>;
+/** {@link acquireAdvisoryLock} / {@link acquireAdvisoryLockWithin} 的释放(尽力而为 —— 锁随连接关闭自动释放;失败留一行,不盖掉真正的结果)。 */
+export declare function releaseAdvisoryLock(conn: LockConn, id: AdvisoryLockId, tag: string): Promise<void>;
 //# sourceMappingURL=ensure-schema-lock-policy.d.ts.map