@sema-agent/server 7.146.0 → 7.148.0

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

@@ -1,13 +1,6 @@
-import { HOOK_ENTRY_TYPES } from "@sema-agent/settings-schema/hooks";
-import { hooksCoordinate, parseHooksConfig } from "./hooks/hook-runner.js";
+import { HOOK_ENTRY_FIELDS, HOOK_ENTRY_TYPES } from "@sema-agent/settings-schema/hooks";
+import { hooksFieldCoordinate, 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;
@@ -108,7 +113,7 @@ export function rereadStoredHooksM20(raw, read = parseHooksConfig) {
         for (const target of targets) {
             if (!removeKeyAt(doc, target))
                 continue;
-            stripped.push(hooksCoordinate(["hooks", ...target]));
+            stripped.push(hooksFieldCoordinate(["hooks", ...target]));
             removedAny = true;
         }
         if (!removedAny)

package/dist/stores-sql/background-agent-store-sql.d.ts

@@ -43,13 +43,21 @@ type ListOpts = {
     status?: BackgroundAgentRecord["status"];
     limit?: number;
 };
+declare const CORRUPT_TAG: "server.sql-json.background-agent.unreadable-row-skipped";
+/**
+ * 本店容忍臂(上面规则里的「跳过 + 计 tag」)的 **F 类披露口** —— `recordFailOpen` 形,由组合座注入(生产装配 = `boot/stores.ts` 交
+ * `observability/fail-open.ts` 的 `recordFailOpen`):店不直引服务的披露座(本目录对 server 其余部分零依赖,要能原样搬进 core 包)。
+ * 两只店的构造参里**必填**:缺席是编译错,不存在一只静默跳行的实例。
+ */
+export type BackgroundAgentRowDisclosure = (tag: typeof CORRUPT_TAG, detail: string) => void;
 export declare function ensureTiDBBackgroundAgentSchema(pool: Pool): Promise<void>;
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgBackgroundAgentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const BACKGROUND_AGENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgBackgroundAgentSchema(q: PgQueryFn): Promise<void>;
 export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
     private readonly pool;
-    constructor(pool: Pool);
+    private readonly disclose;
+    constructor(pool: Pool, disclose: BackgroundAgentRowDisclosure);
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
@@ -89,7 +97,8 @@ export declare class TiDBBackgroundAgentStore implements BackgroundAgentStore {
 }
 export declare class PgBackgroundAgentStore implements BackgroundAgentStore {
     private readonly q;
-    constructor(q: PgQueryFn);
+    private readonly disclose;
+    constructor(q: PgQueryFn, disclose: BackgroundAgentRowDisclosure);
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {

package/dist/stores-sql/background-agent-store-sql.js

@@ -2,8 +2,8 @@ import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, } from "@sem
 import { pgSafeJsonStringify, pgSanitizeText } from "../plugins/pg-safe-json.js";
 import { isMysqlDupKeyError } from "../plugins/sql-errors.js";
 import { ensureIndexes } from "../plugins/ensure-index.js";
-import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText } from "../plugins/sql-json-column.js";
-import { backgroundAgentNameOf } from "../background-agent-name.js";
+import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, SqlJsonColumnError, StoreCorruptError } from "../plugins/sql-json-column.js";
+import { backgroundAgentNameOf, readBackgroundAgentName } from "../background-agent-name.js";
 export const BACKGROUND_AGENT_TABLE = "background_agent";
 function summaryCols(dialect) {
     return ("handle, owner, session_scoped, session_id, parent_session_id, root_session_id, name, agent_type, status, " +
@@ -19,7 +19,15 @@ function readRecordColumn(v, handle) {
     catch (e) {
         throw foldJsonColumn(e, (m) => `BackgroundAgentStore: ${m} — refusing rather than serve a hollow agent record`);
     }
-    return { ...record, name: backgroundAgentNameOf(record) };
+    return { ...record, name: agentNameOrRefuse(record, `${BACKGROUND_AGENT_TABLE}.record_json for handle ${handle}`) };
+}
+const TERMINAL_STATUSES = new Set(["completed", "failed", "killed"]);
+const CORRUPT_TAG = "server.sql-json.background-agent.unreadable-row-skipped";
+function agentNameOrRefuse(row, where) {
+    const read = readBackgroundAgentName(row);
+    if (read.ok)
+        return read.name;
+    throw new StoreCorruptError(new SqlJsonColumnError("malformed", where, read.problem), `BackgroundAgentStore: ${where}: ${read.problem} — refusing rather than serve an agent row without a name`);
 }
 function readUsageColumn(v, handle) {
     try {
@@ -71,7 +79,7 @@ function rowToSummary(r) {
         ...(r.session_id !== null && r.session_id !== undefined ? { sessionId: String(r.session_id) } : {}),
         ...(r.parent_session_id !== null && r.parent_session_id !== undefined ? { parentSessionId: String(r.parent_session_id) } : {}),
         ...(r.root_session_id !== null && r.root_session_id !== undefined ? { rootSessionId: String(r.root_session_id) } : {}),
-        name: backgroundAgentNameOf({ handle: String(r.handle), ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}) }),
+        name: agentNameOrRefuse({ handle: String(r.handle), ...(r.name !== null && r.name !== undefined ? { name: String(r.name) } : {}) }, `${BACKGROUND_AGENT_TABLE}.name for handle ${String(r.handle)}`),
         ...(r.agent_type !== null && r.agent_type !== undefined ? { agentType: String(r.agent_type) } : {}),
         status: String(r.status),
         spawnedAt: Number(r.spawned_at_ms),
@@ -80,6 +88,41 @@ function rowToSummary(r) {
         ...((u) => (u === undefined ? {} : { usage: u }))(readUsageColumn(r.usage_json, String(r.handle))),
     };
 }
+async function listReadable(fetchRows, limit, op, disclose) {
+    const want = limit === undefined || limit === Infinity ? undefined : Number.isFinite(Math.floor(limit)) ? Math.max(0, Math.floor(limit)) : 0;
+    for (let extra = 0;;) {
+        const rows = await fetchRows(want === undefined ? limit : want + extra);
+        const out = [];
+        const skipped = [];
+        for (const r of rows) {
+            try {
+                out.push(rowToSummary(r));
+            }
+            catch (e) {
+                if (!(e instanceof StoreCorruptError) || !TERMINAL_STATUSES.has(String(r.status)))
+                    throw e;
+                skipped.push(`table=${BACKGROUND_AGENT_TABLE} op=${op} handle=${String(r.handle)} status=${String(r.status)} ${e.message}`);
+            }
+        }
+        if (want === undefined || out.length >= want || rows.length < want + extra || skipped.length === 0) {
+            for (const detail of skipped)
+                disclose(CORRUPT_TAG, detail);
+            return want === undefined ? out : out.slice(0, want);
+        }
+        extra = skipped.length;
+    }
+}
+function staleRowOrSkip(row, disclose) {
+    try {
+        return readRecordColumn(row.record_json, String(row.handle));
+    }
+    catch (e) {
+        if (!(e instanceof StoreCorruptError))
+            throw e;
+        disclose(CORRUPT_TAG, `table=${BACKGROUND_AGENT_TABLE} op=reap handle=${String(row.handle)} status=running ${e.message}`);
+        return undefined;
+    }
+}
 function flippedForm(live, now) {
     return {
         ...live,
@@ -198,8 +241,10 @@ export async function ensurePgBackgroundAgentSchema(q) {
 }
 export class TiDBBackgroundAgentStore {
     pool;
-    constructor(pool) {
+    disclose;
+    constructor(pool, disclose) {
         this.pool = pool;
+        this.disclose = disclose;
     }
     async put(record) {
         assertScope(record);
@@ -234,14 +279,18 @@ export class TiDBBackgroundAgentStore {
         return res.affectedRows === 1;
     }
     async listBySession(scope, sessionId, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]));
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => {
+            const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND (session_anchor = ? OR root_session_id = ?)${opts?.status !== undefined ? " AND status = ?" : ""}
+         ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]));
+            return rows;
+        }, opts?.limit, "listBySession", this.disclose);
     }
     async listByScope(scope, opts) {
-        const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]));
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => {
+            const [rows] = (await this.pool.query(`SELECT ${summaryCols("mysql")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ?${opts?.status !== undefined ? " AND status = ?" : ""}
+         ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]));
+            return rows;
+        }, opts?.limit, "listByScope", this.disclose);
     }
     async delete(handle, scope, expect) {
         const [res] = (await this.pool.query(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND handle = ?${expect !== undefined ? " AND rev = ?" : ""}`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]));
@@ -254,7 +303,9 @@ export class TiDBBackgroundAgentStore {
         if (opts.staleRunningMaxAgeMs !== undefined) {
             const [stale] = (await this.pool.query(`SELECT handle, ${jsonColumnText("mysql", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = ? AND status = 'running' AND updated_at_ms < ?`, [scope, now - opts.staleRunningMaxAgeMs]));
             for (const row of stale) {
-                const live = readRecordColumn(row.record_json, String(row.handle));
+                const live = staleRowOrSkip(row, this.disclose);
+                if (live === undefined)
+                    continue;
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     flipped.add(String(row.handle));
             }
@@ -281,8 +332,10 @@ export class TiDBBackgroundAgentStore {
 }
 export class PgBackgroundAgentStore {
     q;
-    constructor(q) {
+    disclose;
+    constructor(q, disclose) {
         this.q = q;
+        this.disclose = disclose;
     }
     async put(record) {
         assertScope(record);
@@ -316,14 +369,12 @@ export class PgBackgroundAgentStore {
         return rows.length === 1;
     }
     async listBySession(scope, sessionId, opts) {
-        const { rows } = await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND (session_anchor = $2 OR root_session_id = $3)${opts?.status !== undefined ? " AND status = $4" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId]);
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => (await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND (session_anchor = $2 OR root_session_id = $3)${opts?.status !== undefined ? " AND status = $4" : ""}
+       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, sessionId, sessionId, opts.status] : [scope, sessionId, sessionId])).rows, opts?.limit, "listBySession", this.disclose);
     }
     async listByScope(scope, opts) {
-        const { rows } = await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1${opts?.status !== undefined ? " AND status = $2" : ""}
-       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(opts?.limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope]);
-        return rows.map(rowToSummary);
+        return listReadable(async (limit) => (await this.q(`SELECT ${summaryCols("pg")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1${opts?.status !== undefined ? " AND status = $2" : ""}
+       ORDER BY spawned_at_ms DESC, handle DESC${limitClause(limit)}`, opts?.status !== undefined ? [scope, opts.status] : [scope])).rows, opts?.limit, "listByScope", this.disclose);
     }
     async delete(handle, scope, expect) {
         const { rows } = await this.q(`DELETE FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND handle = $2${expect !== undefined ? " AND rev = $3" : ""} RETURNING handle`, expect !== undefined ? [scope, handle, expect.rev] : [scope, handle]);
@@ -336,7 +387,9 @@ export class PgBackgroundAgentStore {
         if (opts.staleRunningMaxAgeMs !== undefined) {
             const { rows: stale } = await this.q(`SELECT handle, ${jsonColumnText("pg", "record_json")} FROM ${BACKGROUND_AGENT_TABLE} WHERE scope_key = $1 AND status = 'running' AND updated_at_ms < $2`, [scope, now - opts.staleRunningMaxAgeMs]);
             for (const row of stale) {
-                const live = readRecordColumn(row.record_json, String(row.handle));
+                const live = staleRowOrSkip(row, this.disclose);
+                if (live === undefined)
+                    continue;
                 if (await this.update(String(row.handle), scope, flippedForm(live, now), { rev: live.rev }))
                     affected.add(String(row.handle));
             }

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