@sema-agent/server 7.146.0 → 7.148.0

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

@@ -37,13 +37,19 @@ import type { SessionUnreadable } from "../session-error-wire.js";
  * F1 [high] 实测:`DB_BACKEND` 未设时坏账本 ⇒ `{backend: undefined, degraded: true}`,不是拒启)。
  * 收法:**一个基类,一条重抛**。新 File 店的拒启只要 `extends StoreBootRefusalError` 就自动落在正确的
  * 一侧;忘了继承是**可见**的(它是一个必须显式选择的父类),而忘了往 if 链里加一行是不可见的。
- * (core 的 `AdoptionError` 不在本仓,改不了它的继承链 ⇒ 降级臂保留它那一条 `instanceof`,共两条。)
+ * (core 的 `AdoptionError` 不在本族:它的标记住在数据根里,而降级臂只对**空 / 不存在**的数据根开(`openStoreBackendWithFallback` 的数据根判据),
+ * 它到不了降级那一步 ⇒ 降级臂不为它单开一条。local 形上本族同样先被那条判据兜住;族规仍在,管的是拒句的属主与 SQL 族。)
  *
  * 族的含义是「**确定的拒启表态**」,不限 File 店:SQL `ensureSchema()` 里库带着已退役 schema 的拒启(`RetiredSchemaPresentError`)也属此族。三处读它,读法一致 ——
  * 降级臂不吞(穿过 `mayFallback`)、SQL 开库的等待窗不重试它(`store-open-wait.ts`:再等也等不来另一个答案)、「库打不开」的拒句不改写它(它自己的拒句才是真话)。
  */
 export declare class StoreBootRefusalError extends Error {
 }
+/**
+ * 起服对账一族的拒启码(机读;附录 A / 拒启码表的登记名)。含义 = 「本构建读不出 / 建不出的持久形,开始服务之前判」:SQL 列册对账与退役 schema 两道(`schema-consistency.ts`)、
+ * 会话部署格旁表建不出(`session-ext-table.ts`)、local 数据根的严格边档对账(`local-session-store.ts`)。码住在族基类旁边:读它的几只模块彼此不必互相 import。
+ */
+export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
 /**
  * 取消便签里的**大脑相位**快照 —— core `BrainStatus` 帧经 `brainStatusEventData` 投影后的五键子集。
  *
@@ -109,7 +115,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 断连(不中止)。
@@ -118,7 +127,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 那一侧无从知道)。
@@ -145,8 +154,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?)";
 /**
@@ -273,8 +282,8 @@ export interface NewRunMeta {
  *    `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 = {
@@ -331,6 +340,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`)的**唯一分类表** —— 词表的属主 = 判据的属主,
  * 与类型定义同住一个文件。四个类:
@@ -376,6 +399,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`**。
  *
@@ -492,17 +540,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
@@ -513,39 +563,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」这一笔写)。
+ * 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,6 +1,8 @@
+import { RUN_STALE_SEC_DEFAULT } from "../run-stale-default.js";
 export class StoreBootRefusalError extends Error {
 }
-export const ABORT_CAUSES = ["client_disconnected", "ask_park_grace_exhausted", "cancel_verb"];
+export const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
+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) {
@@ -21,6 +23,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

@@ -2,7 +2,7 @@
  * TaskAttachmentStore —— D-1 通用文件上传的**独立附件 store**(clay 拍 2026-07-27:不复用 fileSnapshot
  * 的 content-addressed blob 面,新建)。TiDB/PG 双方言 + local 文件店(local-task-attachment-store.ts)。
  *
- * 为什么独立而不是骑 SqlBlobBackend/snapshot_blob:那套的引用追踪=「本域 manifest 里没有的即 orphan」,
+ * 为什么独立而不是骑快照 blob 的索引(snapshot_blob):那套的引用追踪=「本域 manifest 里没有的即 orphan」,
  * 附件不在任何一域的 manifest 里 ⇒ 会被孤儿扫在 1h grace 后误收。生命周期也不同:
  * snapshot blob 跟 session 的工作树;**附件跟 task/session 的绑定**(上传先行、提交时绑定、E21 随会话
  * 级联删、未绑定的按 TTL 收割)。
@@ -11,8 +11,8 @@
  *  - `owner` = auth principal ?? "default"(单库 tenant 轴;无 principal 部署全 default = 单用户语义)。
  *    读/删门在 SQL WHERE 完成(filter-before-reduce,roster 语义条 1 同姿)——他人行连结果集都不进。
  *  - **字节本体在对象存储(clay 裁 2026-07-27:云形态对象存储必配,「现在就接」)**:SQL 只存 meta
- *    (索引/owner 门/生命周期),bytes 走 {@link AttachmentBytesStore}(生产=既有 MinioBlobBackend,
- *    读侧内建 sha 校验)。对象键=**sha256**(同内容天然去重;跨 owner 共享对象 ⇒ 对象删除必须过
+ *    (索引/owner 门/生命周期),bytes 走 {@link AttachmentBytesStore}(字节口 {@link BlobBackend} —— 生产 = 对象存储
+ *    MinioBlobBackend;读侧的 sha 校验是本店作为索引属主的事:{@link readAtAddress})。对象键=**sha256**(同内容天然去重;跨 owner 共享对象 ⇒ 对象删除必须过
  *    零引用检查)+ **附件专属 keyPrefix**(与快照 blob 命名空间隔离——同 sha 不同生命周期,混用会互删)。
  *    删除次序:meta 先(E21 purge 永不被 MinIO 网络抖动卡死,blob-backend 异步删裁定同旨),对象删
  *    =零引用检查后 best-effort(失败只 log:无 meta 的对象经 API 不可达;彻底清收敛作 follow-up 记账)。
@@ -32,6 +32,7 @@ import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
 import type { Pool as PgPool } from "pg";
 import { type IndexSpec } from "./ensure-index.js";
+import { type BlobBackend } from "./blob-backend.js";
 /**
  * 一条附件 meta 的**形属主**(整仓唯一那份键集)。
  *
@@ -67,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>;
@@ -79,12 +88,9 @@ export interface TaskAttachmentStore {
     sweepOrphanObjects?(graceMs: number, nowMs?: number): Promise<number>;
 }
 export declare const TASK_ATTACHMENT_TABLE = "task_attachment";
-/** 字节面 seam —— MinioBlobBackend 的结构子集(hash 键控;读侧 sha 校验在实现内)。`listObjects` 可选
+/** 字节面 = 字节口 {@link BlobBackend}(sha256 键控;读侧 sha 校验在本店,{@link readAtAddress})+ 对象存储的两只可选读面。`listObjects` 可选
  *  (D-1 孤儿对象 GC 的列举面;测试桩/无列举后端缺席=sweep 诚实 0,不装作扫过)。 */
-export interface AttachmentBytesStore {
-    putBlob(hash: string, bytes: Uint8Array): Promise<void>;
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    deleteBlobs(hashes: string[]): Promise<number>;
+export interface AttachmentBytesStore extends BlobBackend {
     listObjects?(): AsyncGenerator<{
         hash: string;
         lastModifiedMs: number;
@@ -236,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>;
@@ -266,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,8 @@ 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(),
     owner: z.string(),
@@ -238,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);
@@ -301,7 +309,7 @@ export class TiDBTaskAttachmentStore {
         this.db = mysqlDriver(pool);
     }
     async put(rec) {
-        await this.bytes.putBlob(rec.sha256, rec.content);
+        await this.bytes.put(rec.sha256, rec.content);
         await this.pool.execute(`INSERT INTO ${TASK_ATTACHMENT_TABLE} (${COLS}) VALUES (?,?,?,?,?,?,?,?,?)`, [rec.id, rec.owner, rec.name, rec.mime, rec.sha256, rec.sizeBytes, rec.sessionId ?? null, rec.createdAtMs, rec.boundAtMs ?? null]);
     }
     async get(owner, id) {
@@ -312,19 +320,22 @@ export class TiDBTaskAttachmentStore {
         const meta = await this.get(owner, id);
         if (!meta)
             return null;
-        const b = await this.bytes.getBlob(meta.sha256);
+        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]);
                 if (Number(cnt[0].n) === 0)
-                    await this.bytes.deleteBlobs([sha]);
+                    await this.bytes.delete([sha]);
             }
             catch {
+                failed.push(sha);
             }
         }
+        return { failed };
     }
     bind(owner, ids, sessionId, boundAtMs) {
         return bindOnSql(this.db, owner, ids, sessionId, boundAtMs);
@@ -340,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()) {
@@ -367,8 +378,10 @@ export class TiDBTaskAttachmentStore {
             const referenced = await this.referencedShas(batch);
             const orphans = batch.filter((h) => !referenced.has(h));
             const safe = await this.filterStillOrphan(orphans, graceMs, nowMs);
-            if (safe.length > 0)
-                removed += await this.bytes.deleteBlobs(safe);
+            if (safe.length > 0) {
+                await this.bytes.delete(safe);
+                removed += safe.length;
+            }
             batch = [];
         };
         for await (const o of lister.listObjects()) {
@@ -417,7 +430,7 @@ export class PgTaskAttachmentStore {
         this.q = async (text, params) => ({ rows: (await pool.query(text, params)).rows });
     }
     async put(rec) {
-        await this.bytes.putBlob(rec.sha256, rec.content);
+        await this.bytes.put(rec.sha256, rec.content);
         await this.q(`INSERT INTO ${TASK_ATTACHMENT_TABLE} (${COLS}) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`, [rec.id, rec.owner, rec.name, rec.mime, rec.sha256, rec.sizeBytes, rec.sessionId ?? null, rec.createdAtMs, rec.boundAtMs ?? null]);
     }
     async get(owner, id) {
@@ -428,19 +441,22 @@ export class PgTaskAttachmentStore {
         const meta = await this.get(owner, id);
         if (!meta)
             return null;
-        const b = await this.bytes.getBlob(meta.sha256);
+        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]);
                 if (Number(res.rows[0].n) === 0)
-                    await this.bytes.deleteBlobs([sha]);
+                    await this.bytes.delete([sha]);
             }
             catch {
+                failed.push(sha);
             }
         }
+        return { failed };
     }
     bind(owner, ids, sessionId, boundAtMs) {
         return bindOnSql(this.db, owner, ids, sessionId, boundAtMs);
@@ -453,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()) {
@@ -478,8 +494,10 @@ export class PgTaskAttachmentStore {
             const referenced = await this.referencedShas(batch);
             const orphans = batch.filter((h) => !referenced.has(h));
             const safe = await this.filterStillOrphan(orphans, graceMs, nowMs);
-            if (safe.length > 0)
-                removed += await this.bytes.deleteBlobs(safe);
+            if (safe.length > 0) {
+                await this.bytes.delete(safe);
+                removed += safe.length;
+            }
             batch = [];
         };
         for await (const o of lister.listObjects()) {

package/dist/plugins/task-list-store-sql.d.ts

@@ -22,7 +22,7 @@ export declare const TASK_LIST_ITEM_TABLE = "task_list_item";
  * 同族先例 = `env-facts.ts` 的 `scratchpadSessionSegment`(文件名面)——刻意**不**复用彼此的实现:
  * 一个键空间改了算法不该把另一个键空间的存量行全孤儿化。
  *
- * 🔴 属主在**本文件**(而不是消费它的 boot 车道):留存腿(`retention-store-sql.ts`)按同一派生式
+ * 🔴 属主在**本文件**(而不是消费它的 boot 车道):留存腿(`retention-deployment.ts`)按同一派生式
  * 批量删本表的行,两个消费点必须读同一个函数 —— 键派生有两份就是「在线删除删得掉、留存腿删不掉」。
  */
 export declare function taskListKeyFor(sessionId: string): string;

package/dist/plugins/text-column-capacity.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 中央 DDL 用到的**文本列类型的容量**(UTF-8 字节),按方言各一张 —— 「这一列装得下多少字节」这件事实的唯一一处。
+ *
+ * MySQL 协议(TiDB / MySQL)的 `TEXT` 上限 65,535 字节:严格模式下超长写入抛 `Data too long`,非严格模式静默截断(截断后的 JSON 读侧 parse 失败)。
+ * PG 的 `TEXT` 没有每型宽(只有 1 GB 的通用字段上限,不是列型的事实)⇒ 记作无穷。
+ *
+ * 读者:列属主按自己的类型词查这张表得到列容量(`inbox-payload-column.ts` 的收件 `payload` 预算、`checkpoint-index-columns.ts` 的卡词列容量)。
+ * 只登本仓 DDL 真用的类型词:列属主换一个类型词而这里没有 ⇒ tsc 红,由人把那个类型的容量写进来(不在读者那里另抄一个数)。
+ */
+import type { SqlDialect } from "./sql-driver.js";
+export declare const TEXT_COLUMN_TYPE_MAX_BYTES: {
+    readonly mysql: {
+        readonly TEXT: 65535;
+    };
+    readonly pg: {
+        readonly TEXT: number;
+    };
+};
+/** 某方言下登记过的文本列类型词。 */
+export type TextColumnType<D extends SqlDialect> = keyof (typeof TEXT_COLUMN_TYPE_MAX_BYTES)[D];
+//# sourceMappingURL=text-column-capacity.d.ts.map

package/dist/plugins/text-column-capacity.js

@@ -0,0 +1,5 @@
+export const TEXT_COLUMN_TYPE_MAX_BYTES = {
+    mysql: { TEXT: 65_535 },
+    pg: { TEXT: Number.POSITIVE_INFINITY },
+};
+//# sourceMappingURL=text-column-capacity.js.map