@sema-agent/server 7.145.0 → 7.147.0

package/dist/{plugins → stores-sql}/checkpoint-store-sql.js

@@ -1,23 +1,18 @@
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
-import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, judgeCheckpointIndexCells } from "./checkpoint-index-columns.js";
-import { CheckpointError, isGateKind, MAX_RULE_TEXT_CHARS, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
-import { redactDeep, redactSecrets } from "../trace/redact.js";
-import { MAX_RULE_OFFERS, MAX_RULE_OFFER_BATCH_MEMBERS, countKindlessBatchOffers, parkRowFacts, readRuleOfferList, skillCardFacts } from "../approval-card.js";
-import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readJsonObjectColumn, readNonNullJsonValueColumn, } from "./sql-json-column.js";
+import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, judgeCheckpointIndexCells } from "../plugins/checkpoint-index-columns.js";
+import { CheckpointError, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
+import { parkRowFacts, skillCardFacts } from "../approval-card.js";
+import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
-import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
-import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "./sql-errors.js";
-import { describeProbedTableDrift } from "./schema-drift-sentence.js";
-import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
-import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
+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-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;
-const KINDLESS_SCAN_PAGE = 200;
-export { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
-const MAX_TOOL_INPUT_CHARS = 8192;
-export const TERMINAL_BACKSTOP_MS = Math.max(60_000, (Number.isFinite(Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS)) ? Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) : 0) || 30 * 86_400_000);
-export const TERMINAL_GRACE_MS = 3_600_000;
 export function tokenFingerprint(token) {
     return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
 }
@@ -50,21 +45,6 @@ class StoredRowProjectionMemo {
 }
 const STORED_ROW_READ_BATCH = 100;
 const CHECKPOINT_SHA256_AS = "checkpoint_sha256";
-const GATE_KIND_IS_LIVE_RUN_PARK = {
-    human: true,
-    irreversible_ask: true,
-    resource_limit: true,
-    needs_review: true,
-    plan_review: true,
-    task_done: false,
-};
-export const LIVE_RUN_GATE_KINDS = Object.keys(GATE_KIND_IS_LIVE_RUN_PARK).filter((k) => GATE_KIND_IS_LIVE_RUN_PARK[k]);
-export const TERMINAL_PARK_GATE_KINDS = Object.keys(GATE_KIND_IS_LIVE_RUN_PARK).filter((k) => !GATE_KIND_IS_LIVE_RUN_PARK[k]);
-export function pendingRowPrecedes(a, b, pick) {
-    if (pick === "oldest")
-        return a.createdAt < b.createdAt || (a.createdAt === b.createdAt && a.token < b.token);
-    return a.createdAt > b.createdAt || (a.createdAt === b.createdAt && a.token > b.token);
-}
 export const CHECKPOINT_ADDED_COLUMNS = [
     {
         column: "has_bidi_controls",
@@ -99,53 +79,6 @@ export async function assertCheckpointColumnSchema(query, dialect) {
         }
     }
 }
-const MAX_RULE_OFFER_SCAN = 32;
-function preboundBatchMembers(item) {
-    if (typeof item !== "object" || item === null)
-        return item;
-    const candidate = item;
-    if (candidate.kind !== "batch" || !Array.isArray(candidate.rules) || candidate.rules.length <= MAX_RULE_OFFER_BATCH_MEMBERS)
-        return item;
-    return { ...candidate, rules: candidate.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS) };
-}
-export function boundedReaderInput(raw) {
-    return Array.isArray(raw) ? raw.slice(0, MAX_RULE_OFFER_SCAN).map(preboundBatchMembers) : raw;
-}
-export function boundedRuleOffers(raw, opts = {}) {
-    const observe = opts.countRedactions ?? true;
-    const scrub = (text) => redactSecrets(text, { observe }).slice(0, MAX_RULE_TEXT_CHARS);
-    const read = readRuleOfferList(boundedReaderInput(raw));
-    const out = [];
-    for (const { offer } of read) {
-        if (out.length >= MAX_RULE_OFFERS)
-            break;
-        switch (offer.kind) {
-            case "single":
-                out.push({ kind: "single", rule: scrub(offer.rule), match: offer.match, command: scrub(offer.command) });
-                break;
-            case "batch":
-                out.push({
-                    kind: "batch",
-                    rules: offer.rules.slice(0, MAX_RULE_OFFER_BATCH_MEMBERS).map((r) => {
-                        switch (r.kind) {
-                            case "command":
-                                return { kind: "command", rule: scrub(r.rule), match: r.match, command: scrub(r.command), segment: scrub(r.segment) };
-                            case "directoryRead":
-                                return { kind: "directoryRead", rule: scrub(r.rule), directory: scrub(r.directory), segment: scrub(r.segment) };
-                            default:
-                                throw new Error(`unknown rule-offer batch member kind: ${JSON.stringify(r)}`);
-                        }
-                    }),
-                    uncoveredSegments: offer.uncoveredSegments,
-                    ...(offer.uncoveredDetail !== undefined ? { uncoveredDetail: offer.uncoveredDetail.map((d) => ({ segment: scrub(d.segment), reason: d.reason })) } : {}),
-                });
-                break;
-            default:
-                throw new Error(`unknown rule-offer kind: ${JSON.stringify(offer)}`);
-        }
-    }
-    return out.length > 0 ? out : undefined;
-}
 const readCheckpointBlobBody = createObjectColumnReader();
 const readResumeOutcomeBody = createObjectColumnReader();
 const readGateOutcomeBody = createObjectColumnReader();
@@ -156,6 +89,19 @@ function decodeCheckpointColumn(cell, where) {
 function verdictOfUnreadableBody(cell) {
     return judgeCheckpointRow(cell);
 }
+const UNREADABLE_SUMMARY_MEMBERS = new Set(["token", "rowVerdict", "sessionId", "scope", "gateKind", "createdAt", "deadline"]);
+function isUnreadableSummaryForm(summary) {
+    const names = UNREADABLE_SUMMARY_MEMBERS;
+    return summary.rowVerdict.kind !== "ok" && Object.keys(summary).every((member) => names.has(member));
+}
+function readCheckpointBodyOrRefuse(cell, where) {
+    try {
+        return refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(cell, where));
+    }
+    catch (e) {
+        throw e instanceof StoreCorruptError ? new UnreadableCheckpointRowError(e, verdictOfUnreadableBody(cell)) : e;
+    }
+}
 function decodeOutcomeColumn(cell, where) {
     return decodeNullableJsonColumn(cell, readResumeOutcomeBody, `checkpoint.outcome ${where}`);
 }
@@ -228,80 +174,7 @@ function readCheckpointIdCell(cell) {
         return null;
     }
 }
-export function queueRowGateKind(kind) {
-    if (isGateKind(kind))
-        return kind;
-    recordFailOpen("server.approvals.queue-row-gate-kind-missing", `gate_kind=${kind === null || kind === undefined ? "NULL" : redactSecrets(String(kind)).slice(0, 40)}`);
-    return undefined;
-}
 const readPendingActionMemberBody = createObjectColumnReader();
-export function boundedToolInput(args) {
-    if (args === undefined)
-        return null;
-    const redacted = redactDeep(args);
-    const json = JSON.stringify(redacted);
-    if (json === undefined)
-        return null;
-    if (json.length > MAX_TOOL_INPUT_CHARS)
-        return { truncated: true, bytes: json.length };
-    return redacted;
-}
-export const DECIDED_REPLAY_SCAN_CAP = 8;
-export function approvalDecisionOfWinner(winner, boundCallId) {
-    if (winner === undefined)
-        return null;
-    if (winner.boundCallId !== boundCallId)
-        return null;
-    switch (winner.decision) {
-        case "allow":
-            return "approve";
-        case "deny":
-            return "deny";
-        case "approve":
-        case "reject":
-        case "edit":
-            return null;
-        default: {
-            const unhandled = winner.decision;
-            void unhandled;
-            return null;
-        }
-    }
-}
-function pendingActionToolCallId(body) {
-    if (typeof body !== "object" || body === null)
-        return { readable: false };
-    if ("sourceTaskId" in body)
-        return { readable: false };
-    const rawSource = "sourceSessionId" in body ? body.sourceSessionId : null;
-    if (rawSource !== null && rawSource !== undefined && typeof rawSource !== "string")
-        return { readable: false };
-    const sourceSessionId = typeof rawSource === "string" ? rawSource : null;
-    if (!("pendingAction" in body))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind: null, sourceSessionId };
-    const pa = body.pendingAction;
-    if (typeof pa !== "object" || pa === null)
-        return { readable: false };
-    const kind = "kind" in pa ? pa.kind : null;
-    if (kind !== null && typeof kind !== "string")
-        return { readable: false };
-    if (!("toolCallId" in pa))
-        return { readable: true, toolCallId: null, boundInputHash: null, kind, sourceSessionId };
-    const id = pa.toolCallId;
-    if (typeof id !== "string")
-        return { readable: false };
-    if (kind !== "tool_approval")
-        return { readable: false };
-    const bih = "boundInputHash" in pa ? pa.boundInputHash : null;
-    if (bih !== null && typeof bih !== "string")
-        return { readable: false };
-    return { readable: true, toolCallId: id, boundInputHash: bih, kind, sourceSessionId };
-}
-export function candidateIdentityOf(cp) {
-    if (judgeCheckpointRow(cp).kind === "lacking")
-        return { readable: false };
-    return pendingActionToolCallId(cp);
-}
 function candidateIdentityOfColumn(cell, where) {
     let cp;
     try {
@@ -314,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;
@@ -374,7 +231,6 @@ export function readPendingSteerQueueColumn(queueRaw) {
 }
 const STEER_CAS_ATTEMPTS = 8;
 const EXECUTION_RECORD_CAS_ATTEMPTS = 8;
-export const CTX_CLAIM_REWRITES = ["written", "claim_released", "context_absent"];
 export class SqlCheckpointStore {
     db;
     logger;
@@ -477,7 +333,7 @@ export class SqlCheckpointStore {
         const r = rows[0];
         if (!r)
             return null;
-        const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `for token ${tokenFingerprint(token)}`));
+        const cp = readCheckpointBodyOrRefuse(r.checkpoint, `for token ${tokenFingerprint(token)}`);
         cp.status = r.status;
         const outcomeRaw = refusing("a decision record nobody can read", () => decodeOutcomeColumn(r.outcome, `for token ${tokenFingerprint(token)}`));
         if (outcomeRaw)
@@ -679,13 +535,21 @@ export class SqlCheckpointStore {
             return { rowVerdict: verdictOfUnreadableBody(r.checkpoint) };
         }
         let summary;
+        const disclosed = [];
         try {
-            summary = summarizeCheckpoint(cp, discloseFor?.(cp), memo?.rowVerdict);
+            summary = summarizeCheckpoint(cp, (sentence) => disclosed.push(sentence), memo?.rowVerdict);
         }
         catch {
             recordFailOpen("server.approvals.park-row-blob-unreadable");
             return { rowVerdict: judgeCheckpointRow(cp) };
         }
+        if (isUnreadableSummaryForm(summary)) {
+            recordFailOpen("server.approvals.park-row-blob-unreadable");
+            return { rowVerdict: summary.rowVerdict };
+        }
+        const seat = discloseFor?.(cp);
+        for (const sentence of disclosed)
+            seat?.(sentence);
         if (memo === undefined)
             this.storedRowMemo.set(sha256, { rowVerdict: summary.rowVerdict, skillCardFacts: skillCardFacts(summary) });
         return { rowVerdict: summary.rowVerdict, summary };
@@ -894,47 +758,6 @@ export class SqlCheckpointStore {
         }
         return out;
     }
-    async scanKindlessBatchRows() {
-        const out = [];
-        let unreadableCells = 0;
-        const tolerant = (read) => {
-            try {
-                return read();
-            }
-            catch (e) {
-                if (!isJsonColumnBodyProblem(e))
-                    throw e;
-                unreadableCells += 1;
-                return undefined;
-            }
-        };
-        const prefilter = (d) => `(rule_suggestions IS NOT NULL OR ${jsonColumnTextExpr(d, "checkpoint", PARK_ROW_PENDING_ACTION.key)} LIKE '%"batch"%')`;
-        let after = "";
-        for (;;) {
-            const { rows } = await this.db.query(this.q(`SELECT token, ${jsonColumnText("mysql", "rule_suggestions")}, ${jsonColumnText("mysql", "checkpoint", PARK_ROW_PENDING_ACTION)} FROM checkpoint WHERE token > ? AND ${prefilter("mysql")} ORDER BY token LIMIT ${KINDLESS_SCAN_PAGE}`, `SELECT token, ${jsonColumnText("pg", "rule_suggestions")}, ${jsonColumnText("pg", "checkpoint", PARK_ROW_PENDING_ACTION)} FROM checkpoint WHERE token > $1 AND ${prefilter("pg")} ORDER BY token LIMIT ${KINDLESS_SCAN_PAGE}`), [after]);
-            for (const row of rows) {
-                const token = String(row.token);
-                after = token;
-                const carriers = [];
-                const column = tolerant(() => decodeNullableJsonColumn(row.rule_suggestions, readJsonArrayColumn, "checkpoint.rule_suggestions (kind-less batch census)"));
-                if (countKindlessBatchOffers(boundedReaderInput(column)) > 0)
-                    carriers.push("rule_suggestions");
-                const pendingAction = tolerant(() => decodeNullableJsonColumn(row[PARK_ROW_PENDING_ACTION.as], readJsonObjectColumn, "checkpoint.checkpoint pendingAction member (kind-less batch census)"));
-                if (typeof pendingAction === "object" && pendingAction !== null) {
-                    const blobOffers = Reflect.get(pendingAction, "ruleOffers");
-                    if (blobOffers !== undefined && !Array.isArray(blobOffers))
-                        unreadableCells += 1;
-                    else if (countKindlessBatchOffers(blobOffers) > 0)
-                        carriers.push("pendingAction.ruleOffers");
-                }
-                if (carriers.length > 0)
-                    out.push({ ref: tokenFingerprint(token), carriers });
-            }
-            if (rows.length < KINDLESS_SCAN_PAGE)
-                break;
-        }
-        return { rows: out, unreadableCells };
-    }
     async reapCtx(cutoff) {
         const res = await this.db.query(this.q("DELETE FROM checkpoint_ctx WHERE updated_at_ms < ? " +
             "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +

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

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

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, annulProofFailure, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
-import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isMissingColumnError, retryOnDeadlock } from "./sql-errors.js";
-import { describeProbedTableDrift } from "./schema-drift-sentence.js";
+import { BlobTooLargeError, SqlBlobIndex } from "./blob-index-sql.js";
+import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
+import { isMissingColumnError, retryOnDeadlock } from "../plugins/sql-errors.js";
+import { describeProbedTableDrift } from "../plugins/schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
 export const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -28,17 +28,22 @@ export class SqlFileHistoryStore {
     pool;
     blobExchange = {
         put: (hash, bytes) => this.putExchangedBlob(hash, bytes),
-        get: (hash) => this.blobs.getBlob(hash),
-        has: (hashes) => this.blobs.hasBlobs([...hashes]),
+        get: (hash) => this.blobs.get(hash),
+        has: (hashes) => this.blobs.has([...hashes]),
     };
     blobs;
     spentAttempts = new Set();
     activeAttempts = new Set();
     boundaryKeep;
-    constructor(db, pool, blobBackend, opts) {
+    constructor(db, pool, opts) {
         this.db = db;
         this.pool = pool;
-        this.blobs = blobBackend ?? new SqlBlobBackend(this.db.dialect, this.pool, undefined, FILE_HISTORY_BLOB_TABLE);
+        this.blobs = new SqlBlobIndex(this.db.dialect, this.pool, {
+            table: FILE_HISTORY_BLOB_TABLE,
+            ...(opts?.blobs !== undefined ? { bytes: opts.blobs } : {}),
+            ...(opts?.blobSqlMaxBytes !== undefined ? { maxBytes: opts.blobSqlMaxBytes } : {}),
+            ...(opts?.log !== undefined ? { log: opts.log } : {}),
+        });
         this.boundaryKeep = resolveFileHistoryRetention(this.db.dialect === "mysql" ? "TiDBFileHistoryStore" : "PgFileHistoryStore", opts?.retention);
     }
     q(mysql, pg) {
@@ -95,7 +100,7 @@ export class SqlFileHistoryStore {
                 const baseAvailable = cap.state !== "unreadable";
                 let v1;
                 if (cap.state === "file") {
-                    await this.blobs.putBlob(cap.hash, cap.bytes);
+                    await this.blobs.put(cap.hash, cap.bytes);
                     v1 = { blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) };
                 }
                 else if (cap.state === "absent") {
@@ -344,7 +349,7 @@ export class SqlFileHistoryStore {
                     staged.set(t.keyHash, { kind: "unchanged", version: last.version });
                     continue;
                 }
-                await this.blobs.putBlob(cap.hash, cap.bytes);
+                await this.blobs.put(cap.hash, cap.bytes);
                 staged.set(t.keyHash, { kind: "changed", blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) });
             }
             const verdict = boundaryPublishVerdict({ aborted: signal?.aborted === true });
@@ -471,7 +476,7 @@ export class SqlFileHistoryStore {
                     if (rec.blobHash === null)
                         target = { absent: true };
                     else {
-                        const bytes = await this.blobs.getBlob(rec.blobHash);
+                        const bytes = await this.blobs.get(rec.blobHash);
                         if (bytes === undefined) {
                             ledger.failed.push({ path: t.trackKey, reason: `blob ${rec.blobHash} missing (store integrity)` });
                             continue;
@@ -594,14 +599,14 @@ export class SqlFileHistoryStore {
         const orphans = rows.map((r) => String(r.blob_hash));
         if (orphans.length === 0)
             return 0;
-        return this.blobs.deleteBlobs(orphans);
+        return this.blobs.sweep(orphans);
     }
     async putExchangedBlob(hash, bytes) {
         if (sha256hex(bytes) !== hash) {
             return { ok: false, error: { code: "adopt_failed", message: `blob ${hash}: the bytes do not hash to this address — nothing stored`, permanence: "terminal" } };
         }
         try {
-            await this.blobs.putBlob(hash, bytes);
+            await this.blobs.put(hash, bytes);
             return { ok: true };
         }
         catch (err) {
@@ -760,7 +765,7 @@ export class SqlFileHistoryStore {
             if (existing !== null && !sameGraph) {
                 return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" already holds a DIFFERENT history — a first import requires an empty target and a retry is legal only for the identical envelope (atomic visibility prevents half-graphs; this law prevents publishing the wrong complete graph over locally-grown history)` } };
             }
-            const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.putBlob(hash, bytes));
+            const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.put(hash, bytes));
             if (!verified.ok)
                 return verified;
             if (sameGraph)
@@ -813,13 +818,13 @@ export class SqlFileHistoryStore {
     }
 }
 export class TiDBFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool, blobBackend, opts) {
-        super(mysqlDriver(pool), pool, blobBackend, opts);
+    constructor(pool, opts) {
+        super(mysqlDriver(pool), pool, opts);
     }
 }
 export class PgFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool, blobBackend, opts) {
-        super(pgDriver(pool), pool, blobBackend, opts);
+    constructor(pool, opts) {
+        super(pgDriver(pool), pool, opts);
     }
 }
 export async function assertFileHistorySchema(query, dialect) {

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

@@ -1,8 +1,8 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { MailboxAckResult, MailboxAppendMessage, MailboxDecision, MailboxDecisionOutcome, MailboxLease, MailboxRecipientTombstone, MailboxStore } from "@sema-agent/core";
-import { type IndexSpec } from "./ensure-index.js";
-import type { SqlDialect } from "./sql-driver.js";
+import { type IndexSpec } from "../plugins/ensure-index.js";
+import type { SqlDialect } from "../plugins/sql-driver.js";
 export declare const MAILBOX_TABLE = "mailbox";
 export declare const MAILBOX_MSG_TABLE = "mailbox_message";
 /** [ref] 收件人墓碑表(预删除态的**唯一**真源;形与理由见 `mailbox-recipient-lifecycle.ts` 模块头)。

package/dist/{plugins → stores-sql}/mailbox-store-sql.js

@@ -1,10 +1,10 @@
 import { isUtf8 } from "node:buffer";
 import { MAILBOX_CONSUMED_ID_WINDOW, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_RECORD_ID_MAX_CHARS, MAILBOX_REPLAY_FACETS, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MailboxStoreError, assertMailboxDecisionMove, judgeMailboxAppendById, mailboxReplayDigests, readMailboxAppend, readMailboxPeerMeta, readStoredMailboxDecision } from "@sema-agent/core";
-import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
+import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "../plugins/pg-safe-json.js";
 import { isWellFormedUnicode } from "../principal-jwt.js";
-import { ensureIndexes } from "./ensure-index.js";
-import { escapeLike } from "./sql-escape.js";
-import { SqlJsonColumnError, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readStringArrayColumn } from "./sql-json-column.js";
+import { ensureIndexes } from "../plugins/ensure-index.js";
+import { escapeLike } from "../plugins/sql-escape.js";
+import { SqlJsonColumnError, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readStringArrayColumn } from "../plugins/sql-json-column.js";
 export const MAILBOX_TABLE = "mailbox";
 export const MAILBOX_MSG_TABLE = "mailbox_message";
 export const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";