@sema-agent/server 7.145.0 → 7.147.0

package/dist/sighup-idle.d.ts

@@ -3,8 +3,9 @@
  *
  * SIGHUP(壳窗口关闭打到整个进程组)≠「没人在用这只引擎」:共享引擎形态(同 config 多壳会话,引擎按
  * T11 防孤儿拍骑在首壳进程组里)下 peer 会话还活着——无条件 drain 会把 peer mid-turn 斩掉(499)且窗内
- * 新提交 503。这里改为:SIGHUP 不翻 draining(peer 零感知),armed 一只空闲窗——`inflight()`(bg/resume
- * legs + live streams)连续 idleGraceMs 为 0 才 shutdown,任何在飞 leg 重置窗口。真孤儿(最后一窗关掉)
+ * 新提交 503。这里改为:SIGHUP 不翻 draining(peer 零感知),armed 一只空闲窗——工作谓词连续 idleGraceMs
+ * 为假才 shutdown,任何工作重置窗口(谓词的在飞格读阻断集 `drainState.blockingInflight` = `http + leader + backgroundAgents`;会话驻留的后台 shell / monitor
+ * 在 `/health.inflight` 总数里、不阻断)。真孤儿(最后一窗关掉)
  * 有界自灭=T11 保留;第二个 SIGHUP 升级 escalate(既有 drain 路径,操作员硬梯子)。
  *
  * 诚实边界:idle-but-live 的 peer(两 turn 之间静默超过窗口)会碰到引擎已退→壳 dead-respawn 1-2s 自愈
@@ -12,13 +13,14 @@
  * [ref]:附着(打开着的 SSE 流)是判据的第二格 `attached` —— 只读订阅自此不进 inflight(排空不该等一个看着的壳),而一个只挂着订阅流的
  * peer 壳(cli 附着形:`GET /v1/approvals/stream` 常开)仍然是「有人在用」,靠这一格不被当成孤儿。修前这一形是订阅流被算进 inflight
  * 时顺带挡住的;拆开之后两件事各有一格,规则不变:inflight = 0 ∧ attached = 0 ∧ 活性静默满窗才关。
+ * [ref]([ref] v3 §9.4):「有没有工作」不再由本文件自己拼 —— 它读附着租约的**同一只**工作谓词(`boot/engine-lease.ts` 的 `laneWork`,
+ * 读者词 `"sighup"`),装配层经 {@link SighupIdleDeps.work} 递进来。于是附着租约的车道表在这里同样成立:交接车道(壳已把引擎交给后台)那一格
+ * 对 SIGHUP 读作「有工作」—— 终端关闭不会按另一套谓词把只剩后台 shell 在跑的引擎拆掉,寿命只归租约腿;别的车道读到的仍是附着 ∨ 在飞。
  */
 export interface SighupIdleDeps {
-    /** This replica's in-flight legs (drainState.inflight). */
-    inflight: () => number;
-    /** [ref]:打开着的 SSE 流条数(drainState.attachedStreams,附着租约同一只 getter)。> 0 ⇒ 有壳挂着,同 inflight 一样重置窗口。
-     *  缺席 ⇒ 视为 0(单测 / 嵌入形)。 */
-    attached?: () => number;
+    /** 此刻有没有工作 —— 附着租约的工作谓词(`laneWork(车道, 采样, "sighup")`:附着 > 0 ∨ 阻断集在飞 > 0,交接车道恒真)。真 ⇒ 重置窗口。
+     *  本文件不自拼判据([ref] 的附着格与在飞格都在那只谓词里)。 */
+    work: () => boolean;
     /** MONOTONIC-clock ms of the last non-probe HTTP request (drainState.lastActivityAt). Covers what inflight
      *  can't: admitted-but-not-yet-registered requests (auth/prepare/claim phases) and sub-tick short requests —
      *  and keeps an idle-but-live peer (still listing/browsing) alive. Absent ⇒ inflight-only semantics.

package/dist/sighup-idle.js

@@ -21,17 +21,16 @@ export function createSighupIdleHandler(deps) {
             return;
         }
         armedAt = now();
-        const inflight = deps.inflight();
-        const attached = deps.attached?.() ?? 0;
-        idleSince = inflight === 0 && attached === 0 ? now() : null;
-        deps.log("sighup_idle_watch_armed", { inflight, attached, idleGraceMs: deps.idleGraceMs });
+        const work = deps.work();
+        idleSince = work ? null : now();
+        deps.log("sighup_idle_watch_armed", { work, idleGraceMs: deps.idleGraceMs });
         watch = setInterval(() => {
             if (deps.isStopped()) {
                 clearInterval(watch);
                 watch = undefined;
                 return;
             }
-            if (deps.inflight() > 0 || (deps.attached?.() ?? 0) > 0) {
+            if (deps.work()) {
                 idleSince = null;
                 return;
             }

package/dist/spec-fields.d.ts

@@ -206,6 +206,22 @@ export declare function promptLeanSpecFragment(body: {
 }): {
     promptLean?: boolean;
 };
+/** 请求面能写进 `TaskSpec.compaction` 的成员(其余成员是运维轴,有意不在 wire 上)。型取自引擎本体:引擎改名 / 删这两位 ⇒ 本仓编译红。 */
+export type RequestCompaction = Pick<NonNullable<TaskSpec["compaction"]>, "clampTolerance" | "autoCompact">;
+/**
+ * `TaskSpec.compaction` 的座位片段 —— 调用方拥有的**两个成员**的唯一映射(一个事实一个座位、一只读法,不分两处各铸半个对象):
+ *  · `clampTolerance` ← 顶层 `body.compaction.clampTolerance`([ref] 的配套旋钮):`[0,1]` 闭区间的有限数才收,其余丢;
+ *  · `autoCompact` ← `settings.autoCompactEnabled`(CC 同名 settings 键,CC 只拿它闸**引擎自起**的压缩):布尔**逐字**(`false` 是「关」,有意义,不当作「没说」)。
+ *    引擎座 `autoCompact` 管引擎自起的三条道(窗阈值那一遍、prompt-too-long 恢复那一遍、任务尾摘要);调用方要的那一遍(`POST /v1/runs/:id/compact` → `TaskStream.compact()`)
+ *    归另一只座 `manualCompact`,本仓不写它 ⇒ 它取部署席 / 引擎缺省(开)—— 「只关自动」不连带关手动 `/compact`。
+ * `compaction` 里别的成员(`manualCompact` / `withinTask` / `reserveTokens` / `keepRecentTokens` / `instructions` / `attachWorkingFiles` / `staleToolResultOffload`)是运维轴,有意不开。
+ * 两成员都缺席 ⇒ **整键不写**(与改前字节同;座的缺省属主是引擎与它的部署席,本仓不复刻);只有一个成员在场 ⇒ `compaction` 里只有它。
+ * 每个成员只在**自己的入口**被判一次:`clampTolerance` 直接来自体(resume 重放不过 HTTP 400 门),在这里判;`autoCompact` 来自解析层,类型 `boolean | undefined` 就是合同 ——
+ * 它的判官只有 `task-settings.ts` 的 `autoCompactEnabledOk`(受理门与宽容解析层同问它),这里不再判第二遍。
+ */
+export declare function compactionSpecFragment(clampTolerance: unknown, autoCompact: boolean | undefined): {
+    compaction?: RequestCompaction;
+};
 /** [ref]②(core 5.14.0 `TaskSpec.toolMaterializeStrategy`):deferred 工具激活后的 schema 供给策略。
  *  与 {@link promptLeanFromBody} 同姿势的**防御性归一**——提交面的 fail-loud 400 在 HTTP 门,这里
  *  只负责 resume 重放存量 body 时把不认识的值静默 DROP(回落 core 的 env/缺省链),而不是把它带上 spec。 */

package/dist/spec-fields.js

@@ -325,6 +325,13 @@ export function promptLeanSpecFragment(body) {
     const lean = promptLeanFromBody(body.promptLean);
     return lean !== undefined ? { promptLean: lean } : {};
 }
+export function compactionSpecFragment(clampTolerance, autoCompact) {
+    const seat = {
+        ...(typeof clampTolerance === "number" && Number.isFinite(clampTolerance) && clampTolerance >= 0 && clampTolerance <= 1 ? { clampTolerance } : {}),
+        ...(autoCompact !== undefined ? { autoCompact } : {}),
+    };
+    return Object.keys(seat).length > 0 ? { compaction: seat } : {};
+}
 export function toolMaterializeStrategyFromBody(raw) {
     return raw === "static" || raw === "swap" ? raw : undefined;
 }

package/dist/store-posture.d.ts

@@ -19,7 +19,8 @@ import type { SqlEngineFacts } from "./plugins/sql-driver.js";
 import { type SqlEngineCapability } from "./sql-engine-posture.js";
 /**
  * 降级词闭集(**按后端族**,不按失败发生在哪一步):
- *  · `local_unwritable` —— **缺省推导**的 local 文件店构造期失败(mkdir / 数据根锁 / 权限 / 只读挂载 / 磁盘满)。
+ *  · `local_unwritable` —— **缺省推导**的 local 文件店在**空 / 不存在**的数据根上构造期失败(mkdir / 权限 / 只读挂载 / 磁盘满)。
+ *    数据根上已有东西时开不了(含另一实例持锁)是拒启,不是降级(判据见 `openStoreBackendWithFallback`)。
  *
  * 🔴 SQL 族**没有**降级词:配了 DSN 的库当下打不开 ⇒ 窗内重试、到窗拒启(`plugins/store-open-wait.ts` / `openStoreBackendWithFallback`),
  * 从来不退成内存 —— 修前这里有第二个词 `db_unreachable`(`SESSION_BACKEND=auto` 下 SQL 族打不开 ⇒ 内存 + 本位置位),那是 [ref] P 类的静默 fail-open,随降级臂一并退役。

package/dist/stored-request-env-credentials-m38.d.ts

@@ -0,0 +1,3 @@
+/** M38 的窗在 `today`(UTC 日历日 YYYY-MM-DD)开着没有:开 ⇒ 续跑重放腿剥键照续;关 ⇒ 同一只判据拒。登记行不在 ⇒ 响亮抛(这只读者活过了它的登记行,该随那一行一起删)。 */
+export declare function storedEnvCredentialsDropM38(today: string): boolean;
+//# sourceMappingURL=stored-request-env-credentials-m38.d.ts.map

package/dist/stored-request-env-credentials-m38.js

@@ -0,0 +1,8 @@
+import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
+export function storedEnvCredentialsDropM38(today) {
+    const window = ONE_TIME_MIGRATIONS.find((w) => w.id === "M38");
+    if (window === undefined)
+        throw new Error("stored-request-env-credentials-m38: the one-time migration registry has no M38 row (the replay-leg settings.env credential drop window) — the drop arm outlived its registry row; delete it with that row");
+    return migrationWindowOpen(window, today);
+}
+//# sourceMappingURL=stored-request-env-credentials-m38.js.map

package/dist/stored-request-hooks-m20.d.ts

@@ -9,10 +9,11 @@ export type StoredHooksRereadM20 = (raw: unknown) => StoredHooksRereadM20Result
 /** 读者(= `parseHooksConfig`);作形参只为让「读者交回什么拒因」可被替身喂(默认值就是生产读者)。 */
 export type HooksReader = (raw: unknown) => ParseHooksConfigResult;
 /**
- * 重读一份存体 hooks:读者拒因全部属于两形 ⇒ 剥掉被点名的块里按类型确属未知的键、再问读者,**剥到读者受理为止**,过了就交回产物 + 被剥坐标;否则 `undefined`(原臂:整份不采纳)。
+ * 重读一份存体 hooks:读者拒因全部属于两形 ⇒ 剥掉被点名的块里该剥的键(全部未知键 + 被点名的不透明列)、再问读者,**剥到读者受理为止**,过了就交回产物 + 被剥坐标;否则 `undefined`(原臂:整份不采纳)。
  * 调用方只在读者**已经拒过**这份原值之后才来问;读者一开始就受理的值不进这里(进来也返回 `undefined`:没有可迁移的东西)。
  *
- * 终止:循环体以一次读开头(最后一次剥键之后必有一次读);继续下一轮的条件是本轮真从文档里剥掉了至少一个对象键,文档只减不增 ⇒ 必停;同一块只会被点名一次 ⇒ 轮数 ≤ 被点名的块数 + `__proto__` 键数。
+ * 终止:循环体以一次读开头(最后一次剥键之后必有一次读);继续下一轮的条件是本轮真从文档里剥掉了至少一个对象键,文档只减不增 ⇒ 必停;
+ * 同一块至多被点名 1 + 它的不透明列数次 ⇒ 轮数 ≤ Σ 被点名的块(1 + 不透明列数)+ `__proto__` 键数。
  */
 export declare function rereadStoredHooksM20(raw: unknown, read?: HooksReader): StoredHooksRereadM20Result | undefined;
 /**

package/dist/stored-request-hooks-m20.js

@@ -1,13 +1,6 @@
-import { HOOK_ENTRY_TYPES } from "@sema-agent/settings-schema/hooks";
+import { HOOK_ENTRY_FIELDS, HOOK_ENTRY_TYPES } from "@sema-agent/settings-schema/hooks";
 import { hooksCoordinate, parseHooksConfig } from "./hooks/hook-runner.js";
 import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./plugins/one-time-migrations.js";
-const ENTRY_FIELD_NAMES = {
-    command: { type: true, if: true, timeout: true, statusMessage: true, once: true, command: true, shell: true, async: true, asyncRewake: true },
-    prompt: { type: true, if: true, timeout: true, statusMessage: true, once: true, prompt: true, model: true },
-    agent: { type: true, if: true, timeout: true, statusMessage: true, once: true, prompt: true, model: true },
-    http: { type: true, if: true, timeout: true, statusMessage: true, once: true, url: true, headers: true, allowedEnvVars: true },
-    mcp_tool: { type: true, if: true, timeout: true, statusMessage: true, once: true, server: true, tool: true, input: true },
-};
 const MATCHER_FIELD_NAMES = { matcher: true, hooks: true };
 function isRecord(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
@@ -27,13 +20,24 @@ function nodeAt(node, path) {
     }
     return cur;
 }
-function contractFieldsOf(code, block) {
+const OPAQUE_KIND = "any";
+function standingOf(code, block) {
     if (!isRecord(block))
         return undefined;
     if (code === "guard-matcher-invalid")
-        return MATCHER_FIELD_NAMES;
+        return (key) => (Object.hasOwn(MATCHER_FIELD_NAMES, key) ? "read" : "unknown");
     const type = Object.hasOwn(block, "type") ? block.type : undefined;
-    return isEntryType(type) ? ENTRY_FIELD_NAMES[type] : undefined;
+    if (!isEntryType(type))
+        return undefined;
+    const row = HOOK_ENTRY_FIELDS[type];
+    return (key) => {
+        if (key === "type")
+            return "read";
+        const kind = Object.hasOwn(row, key) ? row[key] : undefined;
+        if (kind === undefined)
+            return "unknown";
+        return (kind.endsWith("?") ? kind.slice(0, -1) : kind) === OPAQUE_KIND ? "opaque" : "read";
+    };
 }
 function stripTargetsOf(piece, doc) {
     const [root, ...rel] = piece.path;
@@ -43,11 +47,12 @@ function stripTargetsOf(piece, doc) {
         return [rel];
     if ((piece.code === "guard-entry-invalid" || piece.code === "guard-matcher-invalid") && typeof piece.field === "string") {
         const block = nodeAt(doc, rel);
-        const known = contractFieldsOf(piece.code, block);
-        if (known === undefined || !isRecord(block) || Object.hasOwn(known, piece.field) || !Object.hasOwn(block, piece.field))
+        const standing = standingOf(piece.code, block);
+        const named = piece.field;
+        if (standing === undefined || !isRecord(block) || !Object.hasOwn(block, named) || standing(named) === "read")
             return undefined;
         return Object.keys(block)
-            .filter((key) => !Object.hasOwn(known, key))
+            .filter((key) => key === named || standing(key) === "unknown")
             .map((key) => [...rel, key]);
     }
     return undefined;

package/dist/stored-request-prompt-profile-m30.d.ts

@@ -23,7 +23,7 @@
  */
 import { type SealedCheckpointCtx } from "./http/checkpoint-ctx.js";
 import { type OneTimeMigrationWindow } from "./plugins/one-time-migrations.js";
-import type { CheckpointCtxRowsRewriter } from "./plugins/checkpoint-store-sql.js";
+import type { CheckpointCtxRowsRewriter } from "./plugins/checkpoint-store-face.js";
 /** M30 一次起服的读数(起服 info 行逐键打出;测试按它断言)。`window: "closed"` ⇒ 一行都没读(其余全 0)。`rowsLongFormKept` = 改写成 `promptLean: false` 的行。 */
 export interface PromptProfileRetireM30Report {
     readonly window: "open" | "closed";

package/dist/stores-sql/blob-index-sql.d.ts

@@ -0,0 +1,148 @@
+/**
+ * The SQL blob INDEX of a content-addressed blob domain — one row per blob `(blob_hash, byte_len, bytes, created_at)` in the
+ * domain's own table ([ref] D1: the file-history domain's `file_history_blob`; the retired snapshot epoch's `snapshot_blob`). The
+ * rows are the INDEX OWNER's (the store), never the byte port's: whether a blob is there, which blobs are orphans, the created_at
+ * grace window, the per-blob cap on SQL-kept bytes and the content-address check of a port read all live here. The byte port
+ * ({@link BlobBackend}, `plugins/blob-backend.ts`) only moves bytes: `put` / `get` / `delete` under a key.
+ *
+ * Where the bytes go — one option, the shape of the engine package's `fileHistory.blobs`:
+ *  - no byte port (the DEFAULT): the bytes ride the index row itself (the `bytes` column), so a deployment without object storage
+ *    keeps every blob in SQL, capped per blob ({@link sqlBlobCapOf}, judged on the connection that writes);
+ *  - a byte port (object storage): the port stores the bytes under the blob's hash and the index row keeps `bytes` NULL. The port
+ *    write lands BEFORE the index row, so an index row never claims bytes the port does not hold (an object with no row is
+ *    unreachable and harmless); a port read is checked against its hash here ({@link readAtAddress}) — a mismatch reads as absent.
+ *
+ * Deletion stays ASYNCHRONOUS (clay 2026-06-26): a purge deletes only the referencing rows, so a blob becomes an orphan; the periodic
+ * {@link SqlBlobIndex.sweep} removes the grace-passed index rows FIRST and then asks the port to delete exactly those keys. A port
+ * delete that fails surfaces (the sweep rejects — the reaper's throttled guard is the loud channel) and leaves an object with no row.
+ *
+ * The SQL statements below are the ones the retired `SqlBlobBackend` / indexed `MinioBlobBackend` sent, verbatim — this module only
+ * gathers them under their owner.
+ */
+import type { Pool as MysqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type BlobBackend } from "../plugins/blob-backend.js";
+import { type SqlEngineFacts, type SqlEngineReading, type SqlWallSource, type SqlWallsReading, type SqlDialect } from "../plugins/sql-driver.js";
+import { type Logger } from "../observability/logger.js";
+/**
+ * 文本协议的 blob 膨胀律 —— mysql2 `query()` 把 Buffer 参数写成 `X'<hex>'`,一字节两个字符,所以承载一个 blob 的语句至少是它的 2 倍。
+ * 包墙折成「能装下多大的 blob」只用这一只常量,推导里不手写 `/ 2`。
+ */
+export declare const SQL_TEXT_PROTOCOL_BLOB_INFLATION = 2;
+/**
+ * 包墙下能装多大的 blob:语句里的载荷量({@link packetWallStatementBytes})再按 {@link SQL_TEXT_PROTOCOL_BLOB_INFLATION} 折半。
+ * blob 以十六进制字面进语句、有 2× —— 膨胀律是 blob 腿自己的,余量不是。
+ */
+export declare function packetWallBlobCap(maxPacketBytes: number): number;
+/**
+ * SQL 快照 blob 的**缺省**帽(运维没设 `SNAPSHOT_BLOB_SQL_MAX_BYTES` 时)的唯一推导 —— 入参是判官 `sqlWallsOf` 给的墙(不读事实、不判缺席、不看方言),**两堵墙取最小**:
+ * 行墙腿(`SqlEngineFacts.maxRowBytes`,TiDB:{@link rowWallPayloadBytes} 的 `blob` = 行墙 − blob 行的余量 1 KiB —— 按这一行的真实形算,不借 JSON 提交体行的 64 KiB)
+ * 与包墙腿(`SqlEngineFacts.maxPacketBytes`,InnoDB 与 TiDB 都有:{@link packetWallBlobCap} = ⌊(包墙 − 1 KiB 语句余量) ÷ 2⌋)。余量只在 `sql-driver.ts` 定义一次
+ * (墙 × 行的形各一只),提交体受理口(`http/request-guards.ts` `refuseSubmitBody`)读同一张表的 `json` 那一只,不各抄。
+ * 墙的 `null` 只表示「这堵墙不存在」;两堵都不存在(PG —— 扩展协议无这两堵墙 —— 或没有 SQL 后端)⇒ `undefined` 不设帽。
+ * 「事实本身缺席」不是这里的入参:店的写前判读的是借出连接自己的事实(恒已建立,见 {@link SqlConnectionReading}),缺席的读法只在提交受理口读池级读口时出现(判官 `sqlWallsOf` 给墙)。
+ * 显式旋钮是运维的策略帽,在本推导之上(见 {@link sqlBlobCapBytes})。
+ *
+ * 两堵墙的真库读数(clay 拍 a+c,2026-07-27;k3s8 tidb-test v7.5.1 默认配置探针):7 MiB / 31 MiB = `entry too large`(行墙,默认 6291456)、
+ * 32 MiB = `max_allowed_packet`(包墙,64 MiB ÷ ~2× 文本协议膨胀)。帽=诚实拒绝:超限 blob 在 query 之前 typed 拒(消费面 HTTP 413 / capture warn
+ * 拿到可行动信息);帽与墙之间只差这一行自己的几百字节(blob 行余量),帽之下的 blob 在缺省配置下落得进。D-1 附件战役同墙教训:`task-attachment-store.ts` 头注。
+ */
+export declare function sqlBlobDefaultCapBytes(walls: SqlWallsReading): number | undefined;
+/**
+ * 一个 SQL 快照 blob 的帽 + 它**从哪来**。`operator` = 运维显式设的 `SNAPSHOT_BLOB_SQL_MAX_BYTES`(策略帽);`reported` / `assumed` = 缺省推导里**定下这个帽的那条腿**的墙数字出处
+ * ({@link SqlWallSource}:库自己报的 / 读失败或事实缺席而退的文档缺省)。机读位同 413 拒体的 `wallSource` 词,旋钮形多一个 `operator`。
+ */
+export interface SqlBlobCapReading {
+    readonly capBytes: number;
+    readonly source: "operator" | SqlWallSource;
+}
+/**
+ * 缺省帽的推导(唯一一处,{@link sqlBlobDefaultCapBytes} 是它的字节投影):两条腿各带自己那堵墙的出处,取最小的那条;两条一样小取行墙腿。两堵墙都不存在 ⇒ `undefined`。
+ */
+export declare function sqlBlobDefaultCapOf(walls: SqlWallsReading): SqlBlobCapReading | undefined;
+/**
+ * 一条**借出连接**的引擎读口:方言(装配事实)+ 它自己那次初始化回读的事实。与 {@link SqlEngineReading} 的差别只有一处 —— `facts` 恒在:连接是借出时才有的,
+ * 借出即已初始化({@link connectJudged} 交给判决的就是借出连接的 `sqlConnectionFacts`),所以「事实缺席」在这条读法上**不可表示**(编译期拒,不是运行期一个没人走的分支)。
+ * 事实缺席(池上还没建立过、或最近一次初始化被拒)只出现在读**池级**读口的地方 —— 提交受理口 —— 那一格的墙由判官 `sqlWallsOf` 给,不经过帽的推导。
+ */
+export interface SqlConnectionReading {
+    readonly dialect: SqlEngineReading["dialect"];
+    readonly facts: SqlEngineFacts;
+}
+/**
+ * 一个 SQL 快照 blob 此刻的帽 —— **显式旋钮 ?? 判官给的墙走缺省推导**的唯一一只函数。唯一读者 = 店的写前判({@link SqlBlobIndex.put} 的 SQL 存字节臂),传的读口({@link SqlConnectionReading})是
+ * **将要执行写入的那条连接**的(方言 + 它自己那次初始化回读的事实,墙经与提交受理口同一只判官 `sqlWallsOf`):包墙是连接的会话值,所以判决只在写入的那条连接上做,
+ * HTTP 面不替店另算一份帽。
+ */
+export declare function sqlBlobCapOf(explicitCapBytes: number | undefined, connection: SqlConnectionReading): SqlBlobCapReading | undefined;
+/** {@link sqlBlobCapOf} 的字节投影(同一个推导,不另读)。 */
+export declare function sqlBlobCapBytes(explicitCapBytes: number | undefined, connection: SqlConnectionReading): number | undefined;
+/**
+ * 这一拒是不是**那条连接的包墙**定的:帽是缺省推导出的(不是运维旋钮)、那条连接有包墙、且包墙腿的折算恰是这个帽(包墙腿是最矮的一腿,或与行墙腿并列)。
+ * 只有这种拒才值得问「这条连接过时了吗」({@link connectJudged}) —— 旋钮的拒、行墙的拒与连接新旧无关。`walls` = 判出这个帽的那一份墙({@link sqlWallsOf})。
+ */
+export declare function capBoundByPacketWall(cap: SqlBlobCapReading, walls: SqlWallsReading): boolean;
+/**
+ * 一次 blob 超帽的拒句 —— **唯一的组句器**(店的 typed {@link BlobTooLargeError} 调它;`PUT /sync/blobs` 的 413 原样转出它的句子):句子按帽的出处({@link SqlBlobCapReading.source})
+ * 分三形,不把假定说成库的上限、也不把运维的旋钮说成库的上限。
+ *  · `operator` —— 帽是运维设的 `SNAPSHOT_BLOB_SQL_MAX_BYTES`;
+ *  · `reported` —— 帽由库报的两堵墙推出(单行上限与包墙÷文本协议膨胀的较小者);
+ *  · `assumed` —— 库的上限没读到(事实还没建立,或这一堵读失败),帽按受支持引擎里最保守的缺省墙推出,稍后重试或由运维设旋钮。
+ */
+export declare function sqlBlobCapRefusalText(byteLen: number, cap: SqlBlobCapReading): string;
+/** typed 判别错:blob 超过 SQL 店的承载帽。判别码供店侧结果映射/HTTP 面/日志使用——绝不能与
+ *  transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)。句子是 {@link sqlBlobCapRefusalText}(带帽的出处)。 */
+export declare class BlobTooLargeError extends Error {
+    readonly cap: SqlBlobCapReading;
+    readonly code: "blob_too_large_for_sql";
+    constructor(byteLen: number, cap: SqlBlobCapReading);
+}
+/** The blob domain an index serves, and where its bytes go (see the file header). */
+export interface SqlBlobIndexOptions {
+    /** The domain's index table (a code literal, never user input). */
+    readonly table: string;
+    /** The byte port; absent ⇒ the bytes ride the index rows (SQL). */
+    readonly bytes?: BlobBackend;
+    /** The operator's explicit per-blob cap for SQL-kept bytes (`SNAPSHOT_BLOB_SQL_MAX_BYTES`); absent ⇒ the derivation in
+     *  {@link sqlBlobCapOf} over the walls of the connection each write borrows. Not read with a byte port. */
+    readonly maxBytes?: number;
+    /** Where a stale connection's replacement is logged ({@link connectJudged}). */
+    readonly log?: Pick<Logger, "warn">;
+}
+/**
+ * One blob domain's index, owned by its store: every read and write of the domain's blob rows, and the only caller of the byte port.
+ */
+export declare class SqlBlobIndex {
+    private readonly dialect;
+    private readonly pool;
+    private readonly opts;
+    /** The write path's connection source: an SQL-kept `put` borrows ONE connection from it (through {@link connectJudged}), judges on that connection's walls, writes on it. */
+    private readonly db;
+    private readonly log;
+    constructor(dialect: SqlDialect, pool: MysqlPool | PgPool, opts: SqlBlobIndexOptions);
+    /** Store `bytes` under `hash` (idempotent; a repeat refreshes created_at even on a dedup hit, so a just-written or re-used blob is
+     *  "touched = now" and grace-protected — the delete-in-use lease).
+     *  · SQL-kept: an over-cap blob is REJECTED (typed {@link BlobTooLargeError}) BEFORE the driver sees the bytes. 🔴 The cap is judged
+     *    ON THE CONNECTION THAT WRITES ([ref]): `max_allowed_packet` is a session value, so the write borrows one connection through
+     *    {@link connectJudged}, which reads ITS walls, judges, and — when the refusal is that connection's packet wall and the server's
+     *    global wall is higher — replaces the stale connection and judges once more; the INSERT runs on the connection that passed.
+     *  · Port-kept: the port write first, then the bytes-NULL index row (an index row never claims bytes the port does not hold). A
+     *    failed port write throws (a silent drop would read as `read_failed` on restore). */
+    put(hash: string, bytes: Uint8Array): Promise<void>;
+    /** The bytes for `hash`, or `undefined` when absent. SQL-kept: the row's bytes (a pool / query error PROPAGATES — a transient fault
+     *  is loud, not a silent "missing blob"). Port-kept: the port's bytes, checked against `hash` ({@link readAtAddress}: a mismatch —
+     *  corruption or a poisoned object — reads as absent, never as wrong bytes; a transient port fault throws). */
+    get(hash: string): Promise<Uint8Array | undefined>;
+    /** The subset of `hashes` with an index row — one `blob_hash IN (...)` SELECT, the same reading for both byte homes (a bytes-NULL
+     *  row counts as present). No bytes are read. */
+    has(hashes: readonly string[]): Promise<Set<string>>;
+    /** Collect orphans: the caller (the store) computes the orphan SET from its own domain's references and hands it here. Removes the
+     *  index rows past the grace window (`created_at < cutoff` — a just-written blob an in-flight write still needs is never deleted:
+     *  delete-in-use is data loss, under-delete is harmless), then — with a byte port — deletes exactly those keys' bytes. Returns the
+     *  number of blobs removed (the grace-passed subset). A port delete failure surfaces as a rejection after the rows are gone. */
+    sweep(orphans: readonly string[]): Promise<number>;
+    /** DELETE the index rows for `hashes` that have passed the grace window; returns the hashes ACTUALLY deleted. Best-effort: a DB
+     *  error is swallowed (under-delete is harmless; the next sweep retries). */
+    private deleteRowsPastGrace;
+}
+//# sourceMappingURL=blob-index-sql.d.ts.map

package/dist/stores-sql/blob-index-sql.js

@@ -0,0 +1,154 @@
+import { readAtAddress } from "../plugins/blob-backend.js";
+import { connectJudged, mysqlDriver, packetWallStatementBytes, pgDriver, rowWallPayloadBytes, sqlWallsOf } from "../plugins/sql-driver.js";
+import { createLogger } from "../observability/logger.js";
+const BLOB_GC_GRACE_MS = 3_600_000;
+export const SQL_TEXT_PROTOCOL_BLOB_INFLATION = 2;
+export function packetWallBlobCap(maxPacketBytes) {
+    return Math.floor(packetWallStatementBytes(maxPacketBytes) / SQL_TEXT_PROTOCOL_BLOB_INFLATION);
+}
+export function sqlBlobDefaultCapBytes(walls) {
+    return sqlBlobDefaultCapOf(walls)?.capBytes;
+}
+export function sqlBlobDefaultCapOf(walls) {
+    const legs = [];
+    if (walls.maxRowBytes !== null)
+        legs.push({ capBytes: rowWallPayloadBytes(walls.maxRowBytes, "blob"), source: walls.sources.maxRowBytes });
+    if (walls.maxPacketBytes !== null)
+        legs.push({ capBytes: packetWallBlobCap(walls.maxPacketBytes), source: walls.sources.maxPacketBytes });
+    return legs.reduce((best, leg) => (best === undefined || leg.capBytes < best.capBytes ? leg : best), undefined);
+}
+export function sqlBlobCapOf(explicitCapBytes, connection) {
+    return explicitCapBytes !== undefined ? { capBytes: explicitCapBytes, source: "operator" } : sqlBlobDefaultCapOf(sqlWallsOf(connection));
+}
+export function sqlBlobCapBytes(explicitCapBytes, connection) {
+    return sqlBlobCapOf(explicitCapBytes, connection)?.capBytes;
+}
+export function capBoundByPacketWall(cap, walls) {
+    return cap.source !== "operator" && walls.maxPacketBytes !== null && packetWallBlobCap(walls.maxPacketBytes) === cap.capBytes;
+}
+export function sqlBlobCapRefusalText(byteLen, cap) {
+    const objectStorage = "configure MinIO object storage (MINIO_ENDPOINT/MINIO_ACCESS_KEY/MINIO_SECRET_KEY) for large snapshot blobs";
+    const head = `blob of ${byteLen} bytes exceeds this deployment's SQL snapshot-blob cap (${cap.capBytes} bytes — `;
+    switch (cap.source) {
+        case "operator":
+            return `${head}set by the operator's SNAPSHOT_BLOB_SQL_MAX_BYTES) — ${objectStorage}, or raise SNAPSHOT_BLOB_SQL_MAX_BYTES if the database allows larger writes`;
+        case "reported":
+            return `${head}the smaller of the database's single-row limit (TiDB txn-entry-size-limit, 6MiB by default) and about half its max_allowed_packet (the text protocol doubles a blob inside the statement)) — ${objectStorage}, or raise SNAPSHOT_BLOB_SQL_MAX_BYTES if your deployment lifted those limits`;
+        case "assumed":
+            return `${head}the database's limits were not read — engine facts not read yet, or a limit could not be read — so the smallest documented default wall applies) — retry shortly, ${objectStorage}, or set SNAPSHOT_BLOB_SQL_MAX_BYTES to the limit your deployment actually has`;
+        default: {
+            const unhandled = cap.source;
+            throw new Error(`blob cap refusal without a sentence: ${String(unhandled)}`);
+        }
+    }
+}
+export class BlobTooLargeError extends Error {
+    cap;
+    code = "blob_too_large_for_sql";
+    constructor(byteLen, cap) {
+        super(sqlBlobCapRefusalText(byteLen, cap));
+        this.cap = cap;
+        this.name = "BlobTooLargeError";
+    }
+}
+export class SqlBlobIndex {
+    dialect;
+    pool;
+    opts;
+    db;
+    log;
+    constructor(dialect, pool, opts) {
+        this.dialect = dialect;
+        this.pool = pool;
+        this.opts = opts;
+        this.db = dialect === "mysql" ? mysqlDriver(pool) : pgDriver(pool);
+        this.log = opts.log ?? createLogger();
+    }
+    async put(hash, bytes) {
+        const port = this.opts.bytes;
+        if (port !== undefined) {
+            await port.put(hash, bytes);
+            if (this.dialect === "mysql") {
+                await this.pool.query(`INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,NULL,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`, [hash, bytes.byteLength, new Date()]);
+            }
+            else {
+                await this.pool.query(`INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,NULL,$3) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, new Date()]);
+            }
+            return;
+        }
+        const judged = await connectJudged(this.db, (facts) => {
+            const connection = { dialect: this.dialect, facts };
+            const cap = sqlBlobCapOf(this.opts.maxBytes, connection);
+            if (cap === undefined || bytes.byteLength <= cap.capBytes)
+                return undefined;
+            return { cap, packetBound: capBoundByPacketWall(cap, sqlWallsOf(connection)) };
+        }, (refusal) => refusal.packetBound, this.log);
+        if (judged.refusal !== undefined)
+            throw new BlobTooLargeError(bytes.byteLength, judged.refusal.cap);
+        try {
+            await judged.conn.query(this.dialect === "mysql"
+                ? `INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`
+                : `INSERT INTO ${this.opts.table} (blob_hash, byte_len, bytes, created_at) VALUES ($1,$2,$3,$4) ON CONFLICT (blob_hash) DO UPDATE SET created_at = EXCLUDED.created_at`, [hash, bytes.byteLength, Buffer.from(bytes), new Date()]);
+        }
+        finally {
+            judged.conn.release();
+        }
+    }
+    async get(hash) {
+        const port = this.opts.bytes;
+        if (port !== undefined)
+            return readAtAddress(port, hash);
+        if (this.dialect === "mysql") {
+            const [rows] = await this.pool.query(`SELECT bytes FROM ${this.opts.table} WHERE blob_hash = ?`, [hash]);
+            return rows[0]?.bytes != null ? new Uint8Array(rows[0].bytes) : undefined;
+        }
+        const b = await this.pool.query(`SELECT bytes FROM ${this.opts.table} WHERE blob_hash = $1`, [hash]);
+        return b.rows[0]?.bytes != null ? new Uint8Array(b.rows[0].bytes) : undefined;
+    }
+    async has(hashes) {
+        if (hashes.length === 0)
+            return new Set();
+        const distinct = [...new Set(hashes)];
+        if (this.dialect === "mysql") {
+            const ph = distinct.map(() => "?").join(",");
+            const [rows] = await this.pool.query(`SELECT blob_hash FROM ${this.opts.table} WHERE blob_hash IN (${ph})`, distinct);
+            return new Set(rows.map((r) => String(r.blob_hash)));
+        }
+        const ph = distinct.map((_, i) => `$${i + 1}`).join(",");
+        const r = await this.pool.query(`SELECT blob_hash FROM ${this.opts.table} WHERE blob_hash IN (${ph})`, distinct);
+        return new Set(r.rows.map((row) => row.blob_hash));
+    }
+    async sweep(orphans) {
+        const removed = await this.deleteRowsPastGrace(orphans);
+        const port = this.opts.bytes;
+        if (port !== undefined && removed.length > 0)
+            await port.delete(removed);
+        return removed.length;
+    }
+    async deleteRowsPastGrace(hashes) {
+        if (hashes.length === 0)
+            return [];
+        const distinct = [...new Set(hashes)];
+        const cutoff = new Date(Date.now() - BLOB_GC_GRACE_MS);
+        if (this.dialect === "mysql") {
+            const ph = distinct.map(() => "?").join(",");
+            const grace = await this.pool
+                .query(`SELECT blob_hash FROM ${this.opts.table} WHERE created_at < ? AND blob_hash IN (${ph})`, [cutoff, ...distinct])
+                .then(([rows]) => rows.map((r) => String(r.blob_hash)))
+                .catch(() => []);
+            if (grace.length === 0)
+                return [];
+            const gph = grace.map(() => "?").join(",");
+            await this.pool
+                .query(`DELETE FROM ${this.opts.table} WHERE created_at < ? AND blob_hash IN (${gph})`, [cutoff, ...grace])
+                .catch(() => undefined);
+            return grace;
+        }
+        const ph = distinct.map((_, i) => `$${i + 2}`).join(",");
+        const r = await this.pool
+            .query(`DELETE FROM ${this.opts.table} WHERE created_at < $1 AND blob_hash IN (${ph}) RETURNING blob_hash`, [cutoff, ...distinct])
+            .catch(() => undefined);
+        return (r?.rows ?? []).map((row) => row.blob_hash);
+    }
+}
+//# sourceMappingURL=blob-index-sql.js.map