@sema-agent/server 7.146.0 → 7.147.0

package/dist/session-workspace.js

@@ -52,6 +52,11 @@ export function createSessionWorkspaceRecorder(store, witness) {
         },
     };
 }
+export async function readSessionProjectId(store, sessionId) {
+    if (store === undefined)
+        return undefined;
+    return (await store.readSessionWorkspace(sessionId))?.project?.id;
+}
 export async function legProjectIdOf(submitted, store, sessionId) {
     if (submitted !== undefined)
         return submitted;

package/dist/sighup-idle.d.ts

@@ -4,7 +4,7 @@
  * SIGHUP(壳窗口关闭打到整个进程组)≠「没人在用这只引擎」:共享引擎形态(同 config 多壳会话,引擎按
  * T11 防孤儿拍骑在首壳进程组里)下 peer 会话还活着——无条件 drain 会把 peer mid-turn 斩掉(499)且窗内
  * 新提交 503。这里改为:SIGHUP 不翻 draining(peer 零感知),armed 一只空闲窗——工作谓词连续 idleGraceMs
- * 为假才 shutdown,任何工作重置窗口(谓词的在飞格读阻断集 `drainState.blockingInflight` = `http + leader`;会话驻留的后台 shell / monitor
+ * 为假才 shutdown,任何工作重置窗口(谓词的在飞格读阻断集 `drainState.blockingInflight` = `http + leader + backgroundAgents`;会话驻留的后台 shell / monitor
  * 在 `/health.inflight` 总数里、不阻断)。真孤儿(最后一窗关掉)
  * 有界自灭=T11 保留;第二个 SIGHUP 升级 escalate(既有 drain 路径,操作员硬梯子)。
  *

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-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/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

package/dist/stores-sql/checkpoint-store-sql.d.ts

@@ -85,7 +85,7 @@ export declare class SqlCheckpointStore implements CheckpointStore {
         info?(msg: string, meta?: unknown): void;
     } | undefined;
     /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
-     *  `retention-store-sql.ts`」逐字见 {@link MANAGED_RETENTION}(扫车道开着时本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
+     *  `retention-store-sql.ts`」逐字见 `plugins/retention-declaration.ts` 的 {@link MANAGED_RETENTION}(扫车道开着时本店的 `checkpoint`/`checkpoint_ctx` 两表由那只聚合店按期清)。 */
     readonly retention: RetentionDeclaration;
     /**
      * `CheckpointStore.durability` 声明([ref] 欠账,[ref] 件5)—— 行落在 MySQL-protocol / PostgreSQL 的

package/dist/stores-sql/checkpoint-store-sql.js

@@ -9,7 +9,7 @@ import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identi
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "../plugins/sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "../plugins/sql-errors.js";
 import { describeProbedTableDrift } from "../plugins/schema-drift-sentence.js";
-import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-store-sql.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { approvalPayloadFingerprint } from "../plugins/approval-payload-fingerprint.js";
 import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DECIDED_REPLAY_SCAN_CAP, queueRowGateKind, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, UnreadableCheckpointRowError, } from "../plugins/checkpoint-store-face.js";
 const CTX_REWRITE_PAGE = 500;
@@ -187,39 +187,23 @@ function candidateIdentityOfColumn(cell, where) {
     }
     return candidateIdentityOf(cp);
 }
-function readActorAssertion(v) {
-    if (typeof v !== "object" || v === null)
-        return undefined;
-    const id = "id" in v ? v.id : undefined;
-    const hostAsserted = "hostAsserted" in v ? v.hostAsserted : undefined;
-    if (typeof id !== "string" || typeof hostAsserted !== "boolean")
-        return undefined;
-    const issuer = "issuer" in v ? v.issuer : undefined;
-    return { id, hostAsserted, ...(typeof issuer === "string" ? { issuer } : {}) };
-}
 function readQueueEntry(v) {
     if (typeof v !== "object" || v === null)
         return undefined;
-    const text = "text" in v ? v.text : undefined;
-    const trusted = "trusted" in v ? v.trusted : undefined;
     const seq = "seq" in v ? v.seq : undefined;
-    const inputId = "inputId" in v ? v.inputId : undefined;
-    if (typeof text !== "string" || typeof trusted !== "boolean")
-        return undefined;
     if (typeof seq !== "number" || !Number.isFinite(seq))
         return undefined;
-    if (typeof inputId !== "string" || inputId === "")
+    if (!("inputId" in v) || v.inputId === undefined)
         return undefined;
-    const priority = "priority" in v ? v.priority : undefined;
-    const actor = readActorAssertion("actor" in v ? v.actor : undefined);
-    return {
-        text,
-        trusted,
-        seq,
-        inputId,
-        ...(actor !== undefined ? { actor } : {}),
-        ...(priority === "now" || priority === "next" || priority === "later" ? { priority } : {}),
-    };
+    const carried = Object.fromEntries(Object.entries(v).filter(([key]) => key !== "seq"));
+    try {
+        return { ...validatePendingSteer(carried), seq };
+    }
+    catch (e) {
+        if (e instanceof CheckpointError && e.code === "steering.invalid_content")
+            return undefined;
+        throw e;
+    }
 }
 export function readPendingSteerQueueColumn(queueRaw) {
     let lossy = false;

package/dist/{plugins → stores-sql}/file-history-store-sql.d.ts

@@ -1,10 +1,11 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport, type FileHistoryExportResult } from "@sema-agent/core";
-import { type BlobBackend } from "./blob-backend.js";
-import type { ServiceBlobExchange } from "./store-backend.js";
-import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
-/** The file-history blob domain's SQL table (BlobBackend `table`/MinIO index binding + the A7 assert). */
+import type { BlobBackend } from "../plugins/blob-backend.js";
+import { SqlBlobIndex } from "./blob-index-sql.js";
+import type { ServiceBlobExchange } from "../plugins/store-backend.js";
+import { type SqlDriver, type SqlDialect } from "../plugins/sql-driver.js";
+/** The file-history blob domain's SQL table (this store's blob index + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
 /** MinIO object-key prefix for this domain (snapshot epoch used "blobs/"; a separate prefix keeps the
  *  two domains' objects disjoint so neither sweep can see the other's keys). */
@@ -17,18 +18,29 @@ export declare const FILE_HISTORY_BLOB_KEY_PREFIX = "file-history/";
  */
 export interface SqlFileHistoryStoreOptions {
     retention?: FileHistoryRetentionPolicy;
+    /** Where the blob bytes go — the shape of the engine package's `fileHistory.blobs`: absent ⇒ in this store's own
+     *  `file_history_blob` rows (SQL, capped per blob); a byte port ⇒ the port holds them and the rows keep bytes NULL. */
+    blobs?: BlobBackend;
+    /** The operator's explicit per-blob cap for SQL-kept bytes (`SNAPSHOT_BLOB_SQL_MAX_BYTES`); absent ⇒ derived from the walls of
+     *  the connection that writes. Not read with a byte port. */
+    blobSqlMaxBytes?: number;
+    /** Where a stale connection's replacement on an SQL-kept blob write is logged. */
+    log?: {
+        warn(msg: string, meta?: Record<string, unknown>): void;
+    };
 }
 /** Dual-dialect durable FileHistoryStore. See the file header for posture + dialect-delta ledger. */
 export declare class SqlFileHistoryStore implements FileHistoryStore {
     protected readonly db: SqlDriver;
-    /** RAW native pool — handed to blob-backend.ts (outside the SqlDriver seam, dialect-switches on
+    /** RAW native pool — handed to the blob index (`blob-index-sql.ts`, outside the SqlDriver seam, dialect-switches on
      *  its own string). Not used for this class's own statements (those go through `db`). */
     protected readonly pool: MySqlPool | PgPool;
     /** The blob exchange (core's `FileHistoryStore.blobExchange` group, see {@link ServiceBlobExchange}): how another machine's bytes
      *  come in ahead of an `importHistory`, go out to a puller, and are asked about. Its presence IS the capability — read through
      *  `blobExchangeOf` (`session-sync.ts`), which defers to core's judge; there is no second word for it on this class. */
     readonly blobExchange: ServiceBlobExchange;
-    protected readonly blobs: BlobBackend;
+    /** This store's blob index (the `file_history_blob` rows; the byte port, when given, behind it). */
+    protected readonly blobs: SqlBlobIndex;
     /** §10 S-6 in-process lease state (design v1 D2: NOT persisted). Keys = `${scope}\x00${entryId}`. */
     private readonly spentAttempts;
     private readonly activeAttempts;
@@ -36,9 +48,9 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      *  由 core 的 `resolveFileHistoryRetention` 在构造期裁定 —— 与两只内置后端同一道门、同一句拒绝。 */
     private readonly boundaryKeep;
     constructor(db: SqlDriver, 
-    /** RAW native pool — handed to blob-backend.ts (outside the SqlDriver seam, dialect-switches on
+    /** RAW native pool — handed to the blob index (`blob-index-sql.ts`, outside the SqlDriver seam, dialect-switches on
      *  its own string). Not used for this class's own statements (those go through `db`). */
-    pool: MySqlPool | PgPool, blobBackend?: BlobBackend, opts?: SqlFileHistoryStoreOptions);
+    pool: MySqlPool | PgPool, opts?: SqlFileHistoryStoreOptions);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     private bool;
@@ -174,18 +186,18 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
     /**
      * Fetch + content-address verify EVERY blob the envelope references from the source, one at a time (memory bounded by one blob) —— 首推与同图重推共用的**唯一**取值校验;
      * 任何一枚取不出 / 核不过 ⇒ 整信封典型拒,什么都不发布。`onVerified` = 校验过的这一枚拿来做什么:首推传「续租式 upsert」(delete-in-use 租约 —— 发布前的孤儿清扫不许收走
-     * 这次导入正要引用的字节);同图重推不传 —— 已发布的图的版本行本身就是引用,租约无事可护,而回写会把每只对象重传一遍(MinIO 的 `putBlob` 是整体 PUT)。
+     * 这次导入正要引用的字节);同图重推不传 —— 已发布的图的版本行本身就是引用,租约无事可护,而回写会把每只对象重传一遍(对象存储字节口的 `put` 是整体 PUT)。
      */
     private verifySourceBlobs;
     importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
 }
 /** MySQL-protocol (TiDB) binding. */
 export declare class TiDBFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool: MySqlPool, blobBackend?: BlobBackend, opts?: SqlFileHistoryStoreOptions);
+    constructor(pool: MySqlPool, opts?: SqlFileHistoryStoreOptions);
 }
 /** PostgreSQL binding. */
 export declare class PgFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool: PgPool, blobBackend?: BlobBackend, opts?: SqlFileHistoryStoreOptions);
+    constructor(pool: PgPool, opts?: SqlFileHistoryStoreOptions);
 }
 /**
  * [ref] D1② — A7-recipe upgrade precondition assert (**refuse to start**, never a warn; the form and