@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/store-contracts.d.ts

@@ -21,6 +21,7 @@
 import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core";
 import type { RunIdentity } from "../identity-source.js";
 import type { SessionUnreadable } from "../session-error-wire.js";
+import type { ReadDenyFloorSummary } from "../read-deny-floor-notice.js";
 /**
  * **File 店族的 boot 期拒启基类**([ref];把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
  *
@@ -50,6 +51,19 @@ export declare class StoreBootRefusalError extends Error {
  * 会话部署格旁表建不出(`session-ext-table.ts`)、local 数据根的严格边档对账(`local-session-store.ts`)。码住在族基类旁边:读它的几只模块彼此不必互相 import。
  */
 export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
+/**
+ * **SQL 库的列形不是本构建读得动的形 ⇒ 起服拒**的唯一出口:整库列册对账的三条拒(列集不符 / information_schema 读不出 / 整库零行,`schema-consistency.ts`)与六只单表探针的拒启
+ * (`checkpoint` · `tool_result` · `file_history_*` · `approval_ask` · `permission_rule_approval` · `permission_rule_ticket`)都经这一只类抛 —— 运维按码(`code` 字段 + 消息首词,同一个
+ * {@link SCHEMA_MISMATCH_ERROR_CODE})判「要跑 ALTER」,不必先猜是哪一只判官拒的。两只判官答同一问(这张表缺不缺列),出口只有一个。
+ *
+ * 属 {@link StoreBootRefusalError} 族:这是一句**确定**的拒启表态(再等也等不来另一个答案)—— 判官万一挪进 `ensureSchema()` 的开库等待窗,它不被重试、不被改写成「库打不开」。
+ * 消息**必须**以码领头:调用方交整句(对账的 `describeSchemaMismatch`、探针的 `probedMissingColumnRefusal` 都是码领头的整句),构造期核一次 —— 缺码 = 编程错,当场响,不是静默补一个。
+ */
+export declare class SchemaMismatchRefusedError extends StoreBootRefusalError {
+    /** 机读码(与退役 schema / 旁表建不出 / local 数据根的拒启同一个)。 */
+    readonly code = "config.schema_mismatch";
+    constructor(message: string, options?: ErrorOptions);
+}
 /**
  * 取消便签里的**大脑相位**快照 —— core `BrainStatus` 帧经 `brainStatusEventData` 投影后的五键子集。
  *
@@ -115,7 +129,10 @@ export interface RunCancelContext {
  *                                  (`http/routes/tasks.ts` 的断连臂,立即中止);
  *  · `ask_park_grace_exhausted` —— 同一断连臂,但断连那一刻有流内未决 ask、已按窗到期同路转 park,宽限计时器用尽时 park 仍没落成;
  *  · `cancel_verb`              —— `POST /v1/runs/:id/cancel`:同副本快路、跨副本耐久取消旗的轮询(四条腿的心跳 / 登记追平),
- *                                  以及 park 中的 run 被它直接终局化(那一形不经 abort,成因照样是这条动词)。
+ *                                  以及 park 中的 run 被它直接终局化(那一形不经 abort,成因照样是这条动词);
+ *  · `stall_verdict`            —— 持有者自己的心跳答「这条 run 的行已不在跑」(被观察口 / 认领冲突 / 收割器判死,`run.stalled`):持有者停下自己的腿
+ *                                  (四条腿的心跳拍与认领心跳,判法一处 `runs.ts` 的 `beatRunHeartbeat`)。行上的终局是那份死亡判决(这条腿的终局写 CAS 打空),
+ *                                  本成因只落在这条腿自己铸的取消终局上(账本行 / 本连接的流)。
  * **刻意不在表里**(普查过、没有真站点):抢占(`preempt` 是优雅让出,终局是 `paused`,不是取消)、有序关停
  * ([ref] 只把未决卡转 park,从不中止活 run;进程退出后的行由收割器落「持有者死亡」判决,那不是本仓铸的取消终局)、
  * `interrupt`(引擎的 turn 动词,终局 `completed` + `haltedByUser`)、detach 断连(不中止)。
@@ -124,7 +141,7 @@ export interface RunCancelContext {
  * (中止那一刻登记)与 `mintCancelledResult`(终局铸点读它),自铸 wire 值登记 = `trace/self-minted-wire.ts` 的 `abortCause`
  * (`satisfies Record<AbortCause, …>`:加 / 删一个词而登记没跟 ⇒ tsc 红)。
  */
-export declare const ABORT_CAUSES: readonly ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
+export declare const ABORT_CAUSES: readonly ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb", "stall_verdict"];
 export type AbortCause = (typeof ABORT_CAUSES)[number];
 /**
  * server 自铸、挂在终局结果上的**侧记键**全集(都描述「server 这一侧发生了什么」,core 那一侧无从知道)。
@@ -139,6 +156,14 @@ export type AbortCause = (typeof ABORT_CAUSES)[number];
 export interface PersistedResultSideKeys {
     cancelContext?: RunCancelContext;
     abortCause?: AbortCause;
+    /**
+     * 这条 run **照跑了**,而它的读拒行不按字节守:读拒表有行、执行环境不守读拒字节地板、部署没要求地板(`READ_DENY_FLOOR_REQUIRED` 未设)。
+     * `{ code: "config.read_deny_floor_unkept", message }` —— 与这条 run 事件流上那一帧 `engine_notice` 同码同句(句子点名 `REMOTE_EXEC=<车道>` 与出路
+     * `READ_DENY_FLOOR_REQUIRED=true`)。判官是引擎(每 run 准备期一次,结果按 `runId` 接上);说法的唯一属主 `read-deny-floor-notice.ts`,挂点 = 出口封口
+     * (`terminal.ts` 的 `sealResultForExit`)。拒起的 run 不带它(那一句在失败终局的句子里)。为什么属于 run 账本而不属于 core 的任务结果:引擎只发通告、
+     * 不在结果上留这件事,而句子里的执行环境与旋钮名是本仓的部署事实。
+     */
+    readDenyFloor?: ReadDenyFloorSummary;
 }
 /**
  * 落库/上 wire 的终局结果 = core 的 `TaskResult` **加上** server 自铸的可缺席侧记键({@link PersistedResultSideKeys})。
@@ -151,8 +176,8 @@ export type PersistedTaskResult = TaskResult & PersistedResultSideKeys;
 /**
  * 🔴 run 店「持有它的实例丢了」那一判的**行上落款**([ref] codex r1-F1 提为常量):三只 run 店的 `reapStale` 把心跳过期的 running 行翻成
  * `failed` 并写下这一句。它是 run 店死亡判决留在行上的证据之一(另一只 = {@link RUN_ORPHANED_ERROR})—— 用户输入受理账本的收敛判词
- * ([ref] L8 起两车道同一只)据 {@link isHolderDeathVerdict} 在 reap **之后**仍能判出「写者死了」—— 7.116.0 起判据是同行的机读码 `run.stalled`({@link RUN_HOLDER_DEATH_CODES}),本句只给人读;三个写者同写句子与码。读时折叠成同一句话的 wire 展示站点
- * (`routes/runs.ts` 的 stale 折叠、`routes/trace-usage.ts` 的 WORKER_DOWN 帧)刻意留字面量:它们由文案冻结门逐字钉着,且不参与任何判据。
+ * ([ref] L8 起两车道同一只)据 {@link isHolderDeathVerdict} 在 reap **之后**仍能判出「写者死了」—— 7.116.0 起判据是同行的机读码 `run.stalled`({@link RUN_HOLDER_DEATH_CODES}),本句只给人读;三个落判决处(收割器 / 观察口 / 认领冲突)同写句子与码,同一只语句。
+ * 两条流的死亡终帧(run 流 `failed`、trace 流 `WORKER_DOWN`)读的是**行上**的这一句,不再各留字面量。
  */
 export declare const RUN_STALLED_ERROR = "run stalled (instance lost?)";
 /**
@@ -223,11 +248,15 @@ export interface RunRecord {
      *  MY replica" (consult the in-process inflight/steerable map authoritatively) from "held elsewhere" (fall
      *  back to the durable cross-replica flag). null for pre-column rows. */
     instanceId: string | null;
+    /** **持有腿**(`task_run.leg_id`):此刻持有这条行的那一条腿的身份 —— 认领铸它({@link mintRunLegId}:建行 = 首腿、续跑认领 = 新腿),交回给认领者;
+     *  停驻写的 CAS 只许持有腿落下(`setSuspended` / `setNeedsReview` 的 `legId`)。与 {@link instanceId} 是两件事:那一列答「活腿在哪台副本上」(路由),
+     *  这一列答「是不是这一条腿」。`null` = 没有持有腿的记录(列之前的行;更早版本的副本建 / 认领的行)—— 本版的腿从不持有它。不上 wire。 */
+    legId: string | null;
     /** 🔴 [ref] P-45 —— 这条 run 上**挂没挂着取消请求**(耐久 `cancel_requested` 列的投影,跨副本)。
      *
      *  语义就是那一列的字节:`POST /v1/runs/:id/cancel` 的 running 臂 CAS 成功即置位,持有副本的心跳拍
-     *  poll 到它就 abort;`markResuming`(续跑认领)把它清零 —— 一次撞上 suspend 的取消不许在恢复之后
-     *  再杀一遍(那条 reset 的理由逐字在 run-store-sql `markResuming` 上)。
+     *  poll 到它就 abort;旗是对**持有腿**的请求 —— 停驻写不落在挂着的旗上(停驻 CAS 认它,停驻提交读到旗就以取消收场),
+     *  `markResuming`(续跑认领 = 换持有腿)把它清零,旗随旧腿去。
      *
      *  为什么是**行上的一位**而不是读面再查一次:列早就在(三个后端同名),只是行投影没带它 —— 正是
      *  本仓 L1 键集门盯的那族「投影剥键」。读面每次 poll 再发一条 `isCancelRequested` 查询,是给热路径
@@ -272,19 +301,23 @@ export interface NewRunMeta {
     objectivePreview?: string | null;
     idem?: RunIdemBinding | null;
 }
+/** 铸一只持有腿({@link RunRecord.legId})—— 三只 run 店的两个认领口(`createRun` / `markResuming`)都调它,别处不铸。唯一值而非计数:同一 `taskId` 的行被删后重建,
+ *  新行的持有腿与旧腿的永不相等(旧腿迟到的停驻写不会落到新行上);认领者随写拿到它,不必读回。 */
+export declare function mintRunLegId(): string;
 /**
  * `RunStore.createRun` 的结局 —— 四形,一形一句话:
- *  · `{ ok: true }` —— 新行已建、会话 claim 已拿;
+ *  · `{ ok: true, legId }` —— 新行已建、会话 claim 已拿;`legId` = 这次认领铸下的持有腿({@link RunRecord.legId}),首腿的停驻写凭它;
  *  · `{ ok: false, existing }` —— 这次提交的一把**幂等钥匙**已经指向一条行:`idem_key`(`Idempotency-Key`)或
  *    `task_id`(调用方自铸的 `body.taskId`)—— 两把钥匙是**同一条律**(资源行上的唯一键),先认 `idem_key` 再认 `task_id`。
  *    这是「原子赢或观察」的**观察**臂:行原样交回,没建新行、没动会话;回执由提交面的唯一回执函数判。
  *  · `{ ok: false, activeTaskId }` —— 会话被**别的** run 占着(双发守卫),没建行;
- *  · `{ ok: false, sessionAbsent: true }` —— 根会话行不在(SQL 孪生在认领事务里锁根行读到零行:受理之后会话被删),没建行、没认领。
- *    进程内两孪生(File / Memory)的账本里没有会话行,不答这一形。
+ *  · `{ ok: false, sessionAbsent: true }` —— 根会话行不在(受理之后会话被删),没建行、没认领。SQL 孪生 = 认领事务里锁根行读到零行;
+ *    File 孪生 = 在根行面({@link SessionRootRows},装配 = local 会话店)的锁里判这一行不在。Memory 孪生不接会话店(配它的引擎内存会话店没有根行),不答这一形。
  * 其余几位在每一形上恒 `undefined`(读 `created.existing` / `created.activeTaskId` / `created.sessionAbsent` 不用先窄化,判别仍是穷举的)。
  */
 export type CreateRunOutcome = {
     ok: true;
+    legId: string;
     existing?: undefined;
     activeTaskId?: undefined;
     sessionAbsent?: undefined;
@@ -337,6 +370,20 @@ export type FenceLanded = typeof FENCE_LANDED;
 export interface InProcessClaimFence {
     whileHoldingClaim(sessionId: string, taskId: string, write: (run: FencedRun) => FenceLanded): boolean;
 }
+/** 认领栅栏的两形(闭集):SQL 孪生一只事务(`SqlRunStore`)/ 进程内同步(File / Memory 孪生)。判的都是「`taskId` 此刻持有 `sessionId` 的认领且在跑」。
+ *  两形的判别位 = `db`(SQL 形带它的驱动,进程内形没有):店按 `"db" in fence` 分形,不必为判形去值引用 SQL run 店的类。 */
+export type ClaimFenceStore = import("./run-store-sql.js").SqlRunStore | InProcessClaimFence;
+/**
+ * 🔴 [ref] **一笔续跑输入写所凭的那只认领**(检查点店的写口 `putCtx` 交认领的那一形与 `rewriteCtxWhileClaimed` 收它):
+ * `fence` = 写者持认领的那只 run 店(栅栏的来源就是认领本身 —— 检查点店不在构造期另绑一份 run 店),`taskId` = 持认领的 run,
+ * `legHolds` = 腿判据(在栅栏里对锁住 / 同步段里那一行同步问一次,只读、不许 await)。
+ * 装配契约:SQL 检查点店只收同一库上的 SQL run 店(两店出自同一后端;店按判别位 `db` 判 SQL 形且方言同,错形响亮抛),local 检查点店只收进程内栅栏。
+ */
+export interface CtxWriteClaim {
+    readonly fence: ClaimFenceStore;
+    readonly taskId: string;
+    readonly legHolds: (run: FencedRun) => boolean;
+}
 /**
  * `RunRecord["status"]`(= `"running" | TaskStatus`)的**唯一分类表** —— 词表的属主 = 判据的属主,
  * 与类型定义同住一个文件。四个类:
@@ -382,6 +429,31 @@ export type UnsuccessfulRunStatus = {
 export type ParkedRunStatus = {
     [K in RunRecord["status"]]: (typeof RUN_STATUS_CLASS)[K] extends "parked" ? K : never;
 }[RunRecord["status"]];
+/**
+ * 🔴 **「这条 run 死了没」的唯一判决**(纯函数,闭集五词)。输入只有行(`status` / `updatedAt`)、时钟、窗(`REAP_RUN_STALE_SEC` × 1000,活配置);
+ * 认领、turn 活性、「这一拍有没有新事件」都**不是**输入。按状态类判,类只问词表属主 {@link runStatusClassOf}:
+ *  · `live` 类:最后一次心跳早于 `nowMs − windowMs` ⇒ `due`(该落死亡判决了),否则 `live`。边界与收割器的 `updated_at < cutoff` 逐字相同;解析不出的时间戳 ⇒ `live`(少动一次);
+ *  · `parked` 类 ⇒ `parked`(停驻不在心跳判据的射程里);终局两类 ⇒ `settled`;
+ *  · **表外词 ⇒ `unknown`**(滚动升级里更新副本写下的新状态,`rowToRun` 是裸 cast):不落、不抛、按行原样答 —— 与属主「读不懂就少动」同方向。
+ * **只在落判决处用**(三只 run 店:收割器 `reapStale`、观察口 `observeRun`、认领冲突);店外没有任何代码拿心跳去比时钟(源码门 `test/run-liveness-single-source-gate.test.ts`)。
+ */
+export type RunLiveness = "live" | "due" | "parked" | "settled" | "unknown";
+export declare function runLivenessOf(row: Pick<RunRecord, "status" | "updatedAt">, nowMs: number, windowMs: number): RunLiveness;
+/**
+ * run 店落死亡判决要的两样(店在构造时拿到,三只店同形):判活窗(getter —— 生产装配读活配置 `runStaleSec`,热发布原地改写的值下一读就见)
+ * 与落判决计数(每次落下 n 条:`runs_reaped_total{kind:"stale"}`,收割器 / 观察口 / 认领冲突同一只)。
+ */
+export interface RunStallWiring {
+    readonly windowMs: () => number;
+    readonly onVerdicts: (landed: number) => void;
+}
+/** 不经后端装配、直接构造的店(测试 / 嵌入方)的缺省:窗 = 配置缺省值,计数不记。生产装配(`store-backend.ts`)一律递活的两样。 */
+export declare const RUN_STALL_DEFAULT_WIRING: RunStallWiring;
+/**
+ * 观察口落判决写失败的 F 类标签(行原样交回,收割器下一拍补落;`observability/fail-open.ts` 登记,`docs/FAIL-OPEN-CENSUS.md` 一行)。
+ * 三只店与认领冲突臂同一只。
+ */
+export declare const RUN_STALL_VERDICT_UNLANDED_TAG = "server.run-store.stall-verdict-unlanded";
 /**
  * 一个状态词的类;**表里没有的词 ⇒ `undefined`**。
  *
@@ -498,17 +570,19 @@ export declare function sessionTempoOfRunStatus(lastStatus: string): PeerSession
 export declare function runProvenElsewhere(run: {
     instanceId?: string | null;
 }, thisInstanceId: string | undefined): boolean;
-/** One row of the GET /v1/sessions list (CC /resume picker): a DISTINCT session (sessionId) aggregated from its
- *  task_run rows — newest-first by last activity. The preview/status are the LATEST run's ("continue where I left
- *  off"); the counts/timestamps span the whole session. Owner included so a fleet-wide (ops) listing is attributable. */
+/** One row of the GET /v1/sessions list (CC /resume picker): one session ROW of the session store (the only session lister) with the
+ *  run-derived half ({@link SessionRunRollup}) joined from its task_run rows — newest-first by last activity. Owner included so a
+ *  fleet-wide (ops) listing is attributable. */
 export interface SessionSummary {
     sessionId: string;
     owner: string | null;
-    /** The most recent run's create time (the keyset sort key) and the session's first run's create time. */
+    /** The session row's last-activity time (the keyset sort key) and its creation time. */
     lastActivityAt: string;
     firstActivityAt: string;
     runCount: number;
-    /** The LATEST run's objective preview + status — what the session was last doing. */
+    /** [ref]:the most recent run (`created_at DESC, task_id DESC`) whose preview column is a non-empty string (by character length) — that column;
+     *  no such run ⇒ `null`. The preview is minted when the run row is written (injected blocks stripped → redacted → cut to 120), so the list and
+     *  `GET /v1/tasks` read ONE column; the session transcript is not read. `lastStatus` stays the LATEST run's (rn=1) — the two are decoupled. */
     objectivePreview: string | null;
     lastStatus: string;
     /** K-5c (shell §K): the LATEST run's task_id — the anchor the shell uses to re-attach the live event tail in ONE
@@ -519,40 +593,56 @@ export interface SessionSummary {
      *  wire 半场见 `security.ts SessionListItem.lastTaskRunId`(同名同义)。 */
     lastTaskRunId?: string;
     /** The session's title: the user's (`writeSessionRowCells`; `null` clears it back to automatic) or the auto-titler's
-     *  (cheap-model one-liner, `setTitleIfNull` — fills NULL only). null = not (yet) titled OR the lister face has no session_meta (the legacy
-     *  task_run aggregate / memory twins — honest degrade). Writer order: `src/session-row.ts`. */
+     *  (cheap-model one-liner, `setTitleIfNull` — fills NULL only). null = not (yet) titled. Writer order: `src/session-row.ts`. */
     title: string | null;
-    /** Pinned by the user (`writeSessionRowCells`). Always present, `false` by default; the legacy task_run aggregate / memory
-     *  twins answer `false` (no session_meta ⇒ nothing there can pin it). */
+    /** Pinned by the user (`writeSessionRowCells`). Always present, `false` by default. */
     pinned: boolean;
     /** 行标签(`src/session-row.ts` 的 `sessionRowTagOf`):这一位住客「PATCH 能写的每一格」的单向摘要,present-iff 这一行可被条件写(店有行格写原语 ∧ 行上有化身);
-     *  只经店的列表行映射铸(`sessionRowTagKey`)。没有会话行的 lister(legacy task_run 聚合 / 内存孪生)缺席。wire 半场见 `security.ts SessionListItem.rowTag`(同名同义)。 */
+     *  只经店的列表行映射铸(`sessionRowTagKey`)。wire 半场见 `security.ts SessionListItem.rowTag`(同名同义)。 */
     rowTag?: string;
     /** 这只会话的存档读不出:present-iff 头的叶子读不出(唯一铸点 `session-error-wire.ts` 的 `sessionUnreadableOf`;码与读口同表)。叶子是行上一列的店(SQL 孪生)
-     *  与没有会话行的 lister 恒缺席。wire 半场见 `security.ts SessionListItem.unreadable`(同名同义)。 */
+     *  恒缺席。wire 半场见 `security.ts SessionListItem.unreadable`(同名同义)。 */
     unreadable?: SessionUnreadable;
+    /** fork 谱系:建这一行的那次 fork 的源会话 id(core `SessionMetadata.forkedFrom` 原词)—— present-iff 这一行是 fork 建的、且建于谱系落地之后(更早的 fork 不回填:源已不可知)。
+     *  三店从行上读(谱系的唯一读法 `session-incarnation.ts` 的 `forkLineageOfRow`);来源住客(`forkedFromIncarnation`)不上列表行。wire 半场见 `security.ts SessionListItem.forkedFrom`(同名同义)。 */
+    forkedFrom?: string;
 }
 /**
- * [ref] —— 会话**枚举面**读 run 账里「每会话的 run 投影」的窄读面:`runCount` / `lastStatus` / `lastRunId` / `lastTaskRunId` 四位,
- * 同一次读、同一条「最新一条」的口径。
+ * run 账里「每会话的 run 投影」的五位([ref] 四位 + [ref] 预览位)—— 会话列表行上出自 run 行的那一半:
+ *  · `runCount` = 这只会话的 run 行数;`lastStatus` / `lastRunId` / `lastTaskRunId` = 最新一条(`created_at DESC, task_id DESC`,rn=1)的状态 / task_id / `result.runId`;
+ *  · `objectivePreview` = 同一排序下第一条「预览列是串且长度 > 0」的那一列(按字符长度判,不按与 `""` 比较 —— SQL 孪生同一谓词 `CHAR_LENGTH(…) > 0`),没有 ⇒ `null`。
+ * 规则在 JS 侧只有一份:`plugins/session-run-rollup.ts` 的 {@link buildSessionRunRollups};SQL 侧是会话店列表投影里的子查询文本(`plugins/session-store-sql.ts`)。
+ */
+export type SessionRunRollup = Pick<SessionSummary, "runCount" | "lastStatus" | "lastRunId" | "lastTaskRunId" | "objectivePreview">;
+/**
+ * 会话**枚举面**读 run 账的窄读面([ref] 立、[ref] 改名并加预览位与 `q`):一次读交回「有 run 行的每只会话 → 它的 {@link SessionRunRollup}」。
  *
- * 为什么是 run 店自己的 `listSessions`、不另造一只读口:这四位在 SQL 双生里就是 `task_run` 的 `rn=1` JOIN(计数、最新一条的状态与 task_id、
- * 最新一条 `result.runId`),在文件 / 内存 run 店里就是 `listSessions` 的同口径聚合(`created_at DESC, task_id DESC` 取最新一条、数全部)——
- * 它们本来就是**同一个问题的同一份答案**。local 会话店(会话身份来自会话仓、不是 run 账)读这一只,一行里就不会出现两个来源各答一遍
- * 「最新一条是谁」(此前 `runCount` / `lastStatus` 读 run 店、`lastRunId` / `lastTaskRunId` 读进程内座:重启后同一行「有终态词、`lastRunId` 为 null」);
- * 不另造的另一半理由:再造一只 `listBySession` 就要在三个孪生里各落一遍并重新证一遍同口径。
+ * 唯一的消费方 = local 会话店(会话身份来自会话仓、不是 run 账):列表 / 单行读 / `?q=` 一次列表一次读(不随会话数 N+1);行上出自 run 行的五位全读这一只,
+ * 于是一行里不会出现两个来源各答一遍「最新一条是谁」或「预览是哪一句」。实现 = 文件 / 内存两只 run 店,都调同一只纯函数;SQL 双生不实现它 ——
+ * SQL 会话店的列表投影在同一条 SELECT 里 JOIN `task_run`,同一条规则。
  *
- * 只收四位:`Pick` 把读面钉死在它真用的键上(其余键 —— 预览 / 属主 / 时刻 —— 在会话仓那边另有来源,不许从这里混读)。
+ * `q`(路由归一化之后的非空串)在场 ⇒ 只交「有一条 run 行的预览列含 q(大小写不敏感、字面)」的会话 —— 与 SQL 孪生的 `EXISTS` 同一条谓词;缺席 ⇒ 交全部有 run 行的会话。
+ * 会话店的 `listSessions` 是唯一的会话 lister;run 店不再列会话([ref] 删除半)。
  */
 export interface SessionRunRollupSource {
-    listSessions(opts: {
-        limit: number;
-    }): Promise<ReadonlyArray<Pick<SessionSummary, "sessionId" | "runCount" | "lastStatus" | "lastRunId" | "lastTaskRunId">>>;
+    sessionRunRollups(opts?: {
+        readonly q?: string;
+    }): Promise<ReadonlyMap<string, SessionRunRollup>>;
+}
+/**
+ * **根行锁**的窄面(规则 L:改根行在不在 / 住客 / 认领的每个写者,先取根行锁、再碰认领 —— SQL 孪生 = 认领事务里先 `session_meta … FOR UPDATE`,
+ * 删除 / 导入的事务内钩在锁根行之后锁定读 `task_active`,全局锁序 根行 → 认领)。`withRootRow` 在这只根的行锁里跑 `body`,交给它**此刻**这一行在不在;
+ * 锁里的读数到 `body` 完成都稳定(改行在不在的写者都排在这把锁上)。实现 = local 会话店(这只会话的写锁 + 它的在场读法);唯一的消费方 = 文件 run 店的 `createRun`:
+ * 不在 ⇒ `sessionAbsent`,在 ⇒ 锁里再取认领锁。锁不可重入:持着根行锁的节不调 `createRun`。
+ */
+export interface SessionRootRows {
+    withRootRow<T>(sessionId: string, body: (present: boolean) => Promise<T>): Promise<T>;
 }
 /**
  * 会话**此刻的 run 认领**(单活槽)的窄读面 —— run 店的 `getActiveTaskId`,同一个问题在 SQL 孪生里是写事务内对 `task_active` 的锁定读。
- * local 会话店在写锁内读它:执行席的 `markMirror`(判序与 SQL 孪生同:行不在 / 住客不同 / writer / mirror 先判,认领只拦「absent → mirror」这一笔写),
- * 与导入三写口(整段 `importEntries` / `replaceEntries` / 暂存提交;判官 `judgeImportWrite` 与 SQL 事务内钩的 `import` 臂同一只:先认领后本处写者)。
+ * local 会话店在写锁(= 根行锁,{@link SessionRootRows})内读它:执行席的 `markMirror`(判序与 SQL 孪生同:行不在 / 住客不同 / writer / mirror 先判,认领只拦「absent → mirror」这一笔写)、
+ * 导入三写口与删除(判官 `judgeSessionWrite` 与 SQL 事务内钩同一只:先认领后本处写者)、placed 行的 `release`。认领唯一的运行期写者(`createRun`)排在同一把锁后面,
+ * 所以锁内读到的认领是稳定的(释放只会让读数更保守)。
  */
 export interface SessionRunClaimSource {
     getActiveTaskId(sessionId: string): Promise<string | undefined>;

package/dist/plugins/store-contracts.js

@@ -1,7 +1,21 @@
+import { RUN_STALE_SEC_DEFAULT } from "../run-stale-default.js";
+import { randomUUID } from "node:crypto";
 export class StoreBootRefusalError extends Error {
 }
 export const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
-export const ABORT_CAUSES = ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
+export class SchemaMismatchRefusedError extends StoreBootRefusalError {
+    code = SCHEMA_MISMATCH_ERROR_CODE;
+    constructor(message, options) {
+        super(codeLed(message), options);
+        this.name = "SchemaMismatchRefusedError";
+    }
+}
+function codeLed(message) {
+    if (!message.startsWith(`${SCHEMA_MISMATCH_ERROR_CODE}: `))
+        throw new TypeError(`a ${SCHEMA_MISMATCH_ERROR_CODE} refusal must lead with its code`);
+    return message;
+}
+export const ABORT_CAUSES = ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb", "stall_verdict"];
 export const RUN_STALLED_ERROR = "run stalled (instance lost?)";
 export const RUN_ORPHANED_ERROR = "run orphaned by engine restart";
 export function buildRunOrphanedError(heldBy) {
@@ -12,6 +26,9 @@ const RUN_HOLDER_DEATH_CODE_WORDS = new Set(Object.values(RUN_HOLDER_DEATH_CODES
 export function isHolderDeathVerdict(run) {
     return run.status === "failed" && run.errorCode !== null && RUN_HOLDER_DEATH_CODE_WORDS.has(run.errorCode);
 }
+export function mintRunLegId() {
+    return randomUUID();
+}
 export const FENCE_LANDED = Symbol("in-process-claim-fence.landed");
 export const RUN_STATUS_CLASS = {
     running: "live",
@@ -22,6 +39,26 @@ export const RUN_STATUS_CLASS = {
     needs_review: "parked",
 };
 const RUN_STATUS_CLASS_LOOKUP = Object.assign(Object.create(null), RUN_STATUS_CLASS);
+export function runLivenessOf(row, nowMs, windowMs) {
+    const cls = runStatusClassOf(row.status);
+    if (cls === undefined)
+        return "unknown";
+    switch (cls) {
+        case "live":
+            return Date.parse(row.updatedAt) < nowMs - windowMs ? "due" : "live";
+        case "parked":
+            return "parked";
+        case "succeeded":
+        case "unsuccessful":
+            return "settled";
+        default: {
+            const unhandled = cls;
+            throw new Error(`runLivenessOf: unknown run status class ${String(unhandled)}`);
+        }
+    }
+}
+export const RUN_STALL_DEFAULT_WIRING = { windowMs: () => RUN_STALE_SEC_DEFAULT * 1000, onVerdicts: () => undefined };
+export const RUN_STALL_VERDICT_UNLANDED_TAG = "server.run-store.stall-verdict-unlanded";
 export function runStatusClassOf(status) {
     return RUN_STATUS_CLASS_LOOKUP[status];
 }

package/dist/plugins/store-fault.d.ts

@@ -1,4 +1,30 @@
-export type StoreFaultClass = "corrupt" | "connection" | "deployment" | "unclassified";
-/** 判官本体。纯函数、不抛;只看被抛出的这一只对象(不沿 `cause` 链找)。两张识别表互斥,判序不影响结果(`test/store-fault-judge.test.ts` 钉互斥)。 */
+export type StoreFaultClass = "corrupt" | "connection" | "deployment" | "defect" | "unclassified";
+/**
+ * 程序错的识别(闭集按类):运行时自己抛的六只原生错误类之一 —— 运行时为代码缺陷抛的错**从不带 `cause`**;带 `cause` 的原生错误类是某一层把下面的失败
+ * 包了一层报上来(undici 的 `fetch failed` 就是 `TypeError` 包着套接字错),说的是被包的那件事,不是这一层的缺陷 ⇒ 不认(落 `unclassified`)——;
+ * 或读腿漂移 `SqlJsonColumnError` 的 `not-text`。只看这一只对象,不沿 `cause` 链找。
+ */
+export declare function isCodeDefect(err: unknown): boolean;
+/** 判官本体。纯函数、不抛;只看被抛出的这一只对象(不沿 `cause` 链找)。连接类与部署错配两张识别表互斥,两者之间判序不影响结果(`test/store-fault-judge.test.ts` 钉互斥);
+ *  程序错排在它们之后(带那两类归因键的对象按那两类认)。 */
 export declare function storeFaultClassOf(err: unknown): StoreFaultClass;
+/**
+ * 判官每个词的**对外句**(闭集 `Record`:判官加一个词而不在这里写出它对外怎么说 = 编译错)。这是本判官唯一的一张「对外怎么说」的表 ——
+ * 失败要出 wire 时,调用方只拿**类别**说话,不把驱动的原句(带库用户名 / 主机 / 表名 / 约束名)交出去;驱动原句只进运维日志
+ * (`terminal.ts` 的折码处),出口脱敏器是模式脱敏、认不出「这是库账号 / 表名」。每句只说两件事:**坏在哪一类** + **重试有没有用**,不带任何实例化的名字。
+ *
+ * 🔴 **句子只断言码本身证明得了的事**:判官读到的只有一个码,而同一个码形可以出自库驱动,也可以出自别的系统调用(`ECONNREFUSED` 出自任何一个套接字、`ENOENT` 出自文件系统),
+ * 所以 `connection` 说「一条连接」而不说「数据库的连接」;`unclassified` 只说「带了一个本服务不公布的码」。只有 `deployment` 的两类码(缺表、权限拒:`42P01` / `42501` /
+ * `ER_NO_SUCH_TABLE` / `ER_TABLEACCESS_DENIED_ERROR`)是库专有的,它才说「数据库」。
+ *
+ * `corrupt` / `defect` 两句对**只有一个码**的读法(见 {@link storeFaultSentenceOfCode})结构上不会命中(前者要店自己的 {@link StoreCorruptError} 类的实例,后者要原生错误类的实例,
+ * 一个 `{ code }` 两者都不是);它们留在表里只为「判官的词与对外句一一对应」—— 将来哪条腿拿真错误对象问判官,这两句就是它们的对外说法。
+ */
+export declare const STORE_FAULT_OUTWARD_SENTENCE: Readonly<Record<StoreFaultClass, string>>;
+/**
+ * 一个**失败码**的对外句 —— 终局因由只带码(引擎把错压成 `code` + `message` 两格,类型与 `cause` 链已不在)的那些站点用:判官读 `{ code }`(识别表按 `code` 字符串登记,
+ * 数字 `errno` 只是同一件事的另一种写法,这里读不到也不影响:每个登记行都有 `code`),交回的词按 {@link STORE_FAULT_OUTWARD_SENTENCE} 说一句。
+ * 判官是整仓一只,这里不第二次认「什么算连接类 / 部署错配类」。
+ */
+export declare function storeFaultSentenceOfCode(code: string): string;
 //# sourceMappingURL=store-fault.d.ts.map

package/dist/plugins/store-fault.js

@@ -1,10 +1,28 @@
 import { isConnectionFaultError, isDeploymentFaultError } from "./sql-errors.js";
-import { StoreCorruptError } from "./sql-json-column.js";
+import { SqlJsonColumnError, StoreCorruptError } from "./sql-json-column.js";
+const RUNTIME_DEFECT_CLASSES = [TypeError, ReferenceError, RangeError, SyntaxError, EvalError, URIError];
+export function isCodeDefect(err) {
+    if (err instanceof SqlJsonColumnError)
+        return err.problem === "not-text";
+    return RUNTIME_DEFECT_CLASSES.some((cls) => err instanceof cls) && !Object.hasOwn(err, "cause");
+}
 export function storeFaultClassOf(err) {
     if (err instanceof StoreCorruptError)
         return "corrupt";
     if (isConnectionFaultError(err))
         return "connection";
-    return isDeploymentFaultError(err) ? "deployment" : "unclassified";
+    if (isDeploymentFaultError(err))
+        return "deployment";
+    return isCodeDefect(err) ? "defect" : "unclassified";
+}
+export const STORE_FAULT_OUTWARD_SENTENCE = {
+    corrupt: "a stored row could not be read; retrying fails the same way until an operator repairs or deletes the row",
+    connection: "a connection failed or the peer is not accepting connections; retrying later may succeed",
+    deployment: "a database table is missing or the database account lacks a grant; retrying will not help until an operator fixes it",
+    defect: "the service failed on an internal error; retrying fails the same way until the service is fixed",
+    unclassified: "the failure carried a code this service does not publish; the operator log carries the original sentence",
+};
+export function storeFaultSentenceOfCode(code) {
+    return STORE_FAULT_OUTWARD_SENTENCE[storeFaultClassOf({ code })];
 }
 //# sourceMappingURL=store-fault.js.map

package/dist/plugins/task-attachment-store.d.ts

@@ -68,6 +68,14 @@ export interface TaskAttachmentStore {
      * 属主门在店里(owner 不匹配 / 不存在的 id 两边都不出现,无 oracle)。`bound` 按请求序、不重复。
      */
     bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
+    /**
+     * 释放字节:给定哈希中**已没有任何行引用**的对象删掉(跨行去重共享 ⇒ 仍被引用的保留;best-effort,不抛 —— 孤儿 GC 兜底)。
+     * 回 `failed` = 这次没能核 / 没能删的哈希(调用方决定告不告知:删净会话的收尾逐次告知,店内的行删除口照旧不告知)。
+     * 删净会话的收尾调它(`session-erase.ts`:执行体在事务里删了附件行、读出它们的哈希,提交之后交这里)。
+     */
+    releaseBytes(shas: readonly string[]): Promise<{
+        readonly failed: readonly string[];
+    }>;
     /** 物化输入(env 建立时)——按 session 单键查(绑定时已 owner 验过;session uuid 不可枚举)。 */
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
@@ -234,9 +242,11 @@ export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
     /** 零引用对象删除(best-effort):meta 已删后,sha 仍被其他行引用则对象保留(跨行去重共享)。
-     *  失败只吞不抛——E21 purge 不被对象存储抖动卡死(blob-backend 异步删裁定同旨);无 meta 的对象
+     *  失败不抛、交回哈希——E21 purge 不被对象存储抖动卡死(blob-backend 异步删裁定同旨);无 meta 的对象
      *  经 API 不可达,彻底清收敛记 follow-up。 */
-    private deleteBytesIfUnreferenced;
+    releaseBytes(shas: readonly string[]): Promise<{
+        readonly failed: readonly string[];
+    }>;
     bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
@@ -264,7 +274,9 @@ export declare class PgTaskAttachmentStore implements TaskAttachmentStore {
     }): Promise<void>;
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
-    private deleteBytesIfUnreferenced;
+    releaseBytes(shas: readonly string[]): Promise<{
+        readonly failed: readonly string[];
+    }>;
     bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;

package/dist/plugins/task-attachment-store.js

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import { attachmentKindOf, PROJECT_BUNDLE_MIME } from "../project-bundle.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError, retryOnDeadlock } from "./sql-errors.js";
+import { countClientWriteOn } from "./session-withdraw-sql.js";
 import { readAtAddress } from "./blob-backend.js";
 export const TaskAttachmentRecordSchema = z.object({
     id: z.string(),
@@ -239,7 +240,13 @@ async function bindOnSql(db, owner, ids, sessionId, boundAtMs) {
     const q = (mysqlSql, pgSql) => (mysql ? mysqlSql : pgSql);
     const ownRows = (columns, of) => db.query(q(`SELECT ${columns} FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = ? AND id IN (${of.map(() => "?").join(",")})`, `SELECT ${columns} FROM ${TASK_ATTACHMENT_TABLE} WHERE owner = $1 AND id = ANY($2::varchar[])`), mysql ? [owner, ...of] : [owner, of]);
     const kindOf = new Map((await ownRows("id, mime", list)).rows.map((r) => [String(r.id), attachmentKindOf(String(r.mime))]));
-    const claim = (of) => retryOnDeadlock(db.dialect, () => inTransaction(db, (conn) => conn.query(q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN ? ELSE bound_at_ms END, session_id = ? WHERE owner = ? AND id IN (${of.map(() => "?").join(",")}) AND (session_id IS NULL OR session_id = ?)`, `UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN $2::bigint ELSE bound_at_ms END, session_id = $1::varchar WHERE owner = $3 AND id = ANY($4::varchar[]) AND (session_id IS NULL OR session_id = $1::varchar)`), mysql ? [boundAtMs, sessionId, owner, ...of, sessionId] : [sessionId, boundAtMs, owner, of])));
+    const claim = (of) => retryOnDeadlock(db.dialect, () => inTransaction(db, async (conn) => {
+        const root = await conn.query(q("SELECT session_id FROM session_meta WHERE session_id = ? FOR UPDATE", "SELECT session_id FROM session_meta WHERE session_id = $1 FOR UPDATE"), [sessionId]);
+        const res = await conn.query(q(`UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN ? ELSE bound_at_ms END, session_id = ? WHERE owner = ? AND id IN (${of.map(() => "?").join(",")}) AND (session_id IS NULL OR session_id = ?)`, `UPDATE ${TASK_ATTACHMENT_TABLE} SET bound_at_ms = CASE WHEN session_id IS NULL THEN $2::bigint ELSE bound_at_ms END, session_id = $1::varchar WHERE owner = $3 AND id = ANY($4::varchar[]) AND (session_id IS NULL OR session_id = $1::varchar)`), mysql ? [boundAtMs, sessionId, owner, ...of, sessionId] : [sessionId, boundAtMs, owner, of]);
+        if (root.rows.length > 0 && res.affected > 0)
+            await countClientWriteOn(conn, db.dialect, sessionId);
+        return res;
+    }));
     const attachments = list.filter((id) => kindOf.get(id) === "attachment");
     if (attachments.length > 0)
         await claim(attachments);
@@ -316,7 +323,8 @@ export class TiDBTaskAttachmentStore {
         const b = await readAtAddress(this.bytes, meta.sha256);
         return b && b.byteLength === meta.sizeBytes ? b : null;
     }
-    async deleteBytesIfUnreferenced(shas) {
+    async releaseBytes(shas) {
+        const failed = [];
         for (const sha of new Set(shas)) {
             try {
                 const [cnt] = await this.pool.query(`SELECT COUNT(*) AS n FROM ${TASK_ATTACHMENT_TABLE} WHERE sha256 = ?`, [sha]);
@@ -324,8 +332,10 @@ export class TiDBTaskAttachmentStore {
                     await this.bytes.delete([sha]);
             }
             catch {
+                failed.push(sha);
             }
         }
+        return { failed };
     }
     bind(owner, ids, sessionId, boundAtMs) {
         return bindOnSql(this.db, owner, ids, sessionId, boundAtMs);
@@ -341,19 +351,19 @@ export class TiDBTaskAttachmentStore {
         const [res] = await this.pool.query(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE id = ? AND owner = ?`, [id, owner]);
         if ((res.affectedRows ?? 0) === 0)
             return false;
-        await this.deleteBytesIfUnreferenced([meta.sha256]);
+        await this.releaseBytes([meta.sha256]);
         return true;
     }
     async deleteBySession(sessionId) {
         const [rows] = await this.pool.query(`SELECT sha256 FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = ?`, [sessionId]);
         const [res] = await this.pool.query(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = ?`, [sessionId]);
-        await this.deleteBytesIfUnreferenced(rows.map((r) => r.sha256));
+        await this.releaseBytes(rows.map((r) => r.sha256));
         return res.affectedRows ?? 0;
     }
     async reapUnbound(olderThanMs) {
         const [rows] = await this.pool.query(`SELECT sha256 FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id IS NULL AND created_at_ms < ?`, [olderThanMs]);
         const [res] = await this.pool.query(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id IS NULL AND created_at_ms < ?`, [olderThanMs]);
-        await this.deleteBytesIfUnreferenced(rows.map((r) => r.sha256));
+        await this.releaseBytes(rows.map((r) => r.sha256));
         return res.affectedRows ?? 0;
     }
     async sweepOrphanObjects(graceMs, nowMs = Date.now()) {
@@ -434,7 +444,8 @@ export class PgTaskAttachmentStore {
         const b = await readAtAddress(this.bytes, meta.sha256);
         return b && b.byteLength === meta.sizeBytes ? b : null;
     }
-    async deleteBytesIfUnreferenced(shas) {
+    async releaseBytes(shas) {
+        const failed = [];
         for (const sha of new Set(shas)) {
             try {
                 const res = await this.q(`SELECT COUNT(*) AS n FROM ${TASK_ATTACHMENT_TABLE} WHERE sha256 = $1`, [sha]);
@@ -442,8 +453,10 @@ export class PgTaskAttachmentStore {
                     await this.bytes.delete([sha]);
             }
             catch {
+                failed.push(sha);
             }
         }
+        return { failed };
     }
     bind(owner, ids, sessionId, boundAtMs) {
         return bindOnSql(this.db, owner, ids, sessionId, boundAtMs);
@@ -456,17 +469,17 @@ export class PgTaskAttachmentStore {
         const res = await this.q(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE id = $1 AND owner = $2 RETURNING sha256`, [id, owner]);
         if (res.rows.length === 0)
             return false;
-        await this.deleteBytesIfUnreferenced([res.rows[0].sha256]);
+        await this.releaseBytes([res.rows[0].sha256]);
         return true;
     }
     async deleteBySession(sessionId) {
         const res = await this.q(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id = $1 RETURNING sha256`, [sessionId]);
-        await this.deleteBytesIfUnreferenced(res.rows.map((r) => r.sha256));
+        await this.releaseBytes(res.rows.map((r) => r.sha256));
         return res.rows.length;
     }
     async reapUnbound(olderThanMs) {
         const res = await this.q(`DELETE FROM ${TASK_ATTACHMENT_TABLE} WHERE session_id IS NULL AND created_at_ms < $1 RETURNING sha256`, [olderThanMs]);
-        await this.deleteBytesIfUnreferenced(res.rows.map((r) => r.sha256));
+        await this.releaseBytes(res.rows.map((r) => r.sha256));
         return res.rows.length;
     }
     async sweepOrphanObjects(graceMs, nowMs = Date.now()) {

package/dist/plugins/tidb-pool.d.ts

@@ -51,7 +51,7 @@ export declare function createTidbPool(config: ServiceConfig): Pool;
  *  3. 生成的全集 SQL 基线导出到 `docs/schema/baseline-mysql.sql`(由本数组机器生成;它是**产物**,不是真源
  *     —— 冲突时以本文件为准并重新生成)。
  *
- * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + image_bake_admit 种子行),语句数组是纯 CREATE。数组之外只有一只只读探针:会话部署格旁表
+ * 注意:`ensureSchema` 仍然保留(建表 + advisory lock + 两只种子行:image_bake_admit 与 `Skill` 豁免截点),语句数组是纯 CREATE。数组之外只有一只只读探针:会话部署格旁表
  * `session_ext` 的外键列要抄被引列 `session_meta.session_id` 的字符集 / 排序规则(MySQL 外键两侧必须相同,而存量库上它随建库年代不同),建它之前读一次
  * `information_schema.COLUMNS`(`session-ext-table.ts` 的 `ensureSessionExtTableMysql`;探针只读、不导出任何 ALTER)。
  */
@@ -59,17 +59,22 @@ export declare const SCHEMA_STATEMENTS: readonly string[];
 /** Named MySQL/TiDB advisory lock that serializes the whole `ensureSchema` DDL run (see below). */
 export declare const ENSURE_SCHEMA_LOCK = "sema_ensure_schema";
 /** Acquire {@link ENSURE_SCHEMA_LOCK} on `conn` (the lock is CONNECTION-level, so the caller MUST then run all the
- *  serialized work on this SAME connection and release with {@link releaseEnsureSchemaLock}). Returns whether it was
- *  acquired. Exported so test setup that does ad-hoc DDL (e.g. a DROP-then-recreate) can serialize against
+ *  serialized work on this SAME connection and release with {@link releaseEnsureSchemaLock}). Resolves once the lock is
+ *  held. Exported so test setup that does ad-hoc DDL (e.g. a DROP-then-recreate) can serialize against
  *  ensureSchema runs using the IDENTICAL lock.
  *
  *  Under heavy concurrency (the integration suite fans ~20 callers at the SAME named lock; or a fleet boots N
  *  replicas at once) a BLOCKING GET_LOCK(name, 30) would park ~19 sessions in a pessimistic WAIT on TiDB's advisory-
  *  lock row — which both exhausts TiDB's "pessimistic lock retry limit" (surfacing as a thrown error) AND starves the
- *  app's OWN `SELECT … FOR UPDATE` paths (image-bake admission/lease) of pessimistic-lock budget. So we acquire
- *  NON-BLOCKING (GET_LOCK(name, 0) returns 0 immediately if held) and POLL with jittered backoff: one holder, the
+ *  app's OWN `SELECT … FOR UPDATE` paths (image-bake admission/lease) of pessimistic-lock budget. So the lock is taken
+ *  NON-BLOCKING (GET_LOCK(name, 0) returns 0 immediately if held) and POLLED with jittered backoff: one holder, the
  *  rest sleeping (not blocked in-DB). Polls until acquired (7.83.0: never degrades to unserialized — the [ref]
- *  `ADD INDEX` leg is not race-safe); a connection whose probe keeps throwing surfaces as a boot failure. */
+ *  `ADD INDEX` leg is not race-safe); a connection whose probe keeps throwing surfaces as a boot failure.
+ *
+ *  The probe statement, the reading of its answer, the engine's "pessimistic lock retry limit reached" sentence (read as
+ *  "somebody else is on the lock row" — the same fact as `got = 0`, NOT a broken connection) and the polling law all
+ *  live in ONE place, `ensure-schema-lock-policy.ts`; every other lock in this repo (the adoption arc lock) is taken
+ *  through the same acquirer. */
 export declare function acquireEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;
 /** Release {@link ENSURE_SCHEMA_LOCK} on `conn` (best-effort — the lock also auto-frees when the connection closes). */
 export declare function releaseEnsureSchemaLock(conn: PoolConnection, tag?: string): Promise<void>;