@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/blob-backend.d.ts

@@ -1,153 +1,31 @@
-import type { Pool as MysqlPool } from "mysql2/promise";
-import type { Pool as PgPool } from "pg";
-import { type SqlEngineFacts, type SqlEngineReading, type SqlWallSource, type SqlWallsReading, type SqlDialect } from "./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 SqlBlobBackend.putBlob}),传的读口({@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 content-addressed byte store. All four methods are keyed on the sha256 `hash` of the bytes:
- *  - putBlob: store bytes (idempotent — a repeat for the same hash is a no-op-equivalent; the SQL twin refreshes
- *    created_at so a just-written/re-used blob is GC-grace-protected). MinIO PUTs the object AND upserts the SQL INDEX.
- *  - getBlob: the bytes for `hash`, or undefined if absent. A TRANSIENT backend fault THROWS (so a restore/import fails
- *    LOUD, not a silent "missing blob"); only a genuine absence / corruption is undefined.
- *  - hasBlobs: the subset of `hashes` that already exist — a single SQL `IN(...)` over the index for BOTH backends
- *    (migration idempotency + reap probing + the §10 import presence pre-check; cheaper than a HEAD-per-hash on MinIO).
- *  - deleteBlobs: byte-delete the given hashes (called ONLY by the async sweep reaper). Honors the SAME created_at
- *    grace window as the SQL backend (MinIO reads the index's created_at) — delete-in-use is impossible. Returns the
- *    count ACTUALLY deleted (the grace-passed subset), so the sweep reports real work, not the pre-grace orphan count.
+ * The byte port. Keys are opaque to it (today every index owner keys a blob by its sha256 hash).
+ *  - `put`: store `bytes` under `key`. Idempotent (a repeat for the same key overwrites with the identical bytes); a rejection is a
+ *    failed write.
+ *  - `get`: the bytes under `key`, or `undefined` when nothing is there. A TRANSIENT fault THROWS (so a restore / import fails LOUD,
+ *    not as a silent "missing blob"). The index owner checks the bytes against the hash ({@link readAtAddress}).
+ *  - `delete`: remove the bytes under each key. Idempotent — a key with nothing under it is a success; a key that could not be removed
+ *    makes the call reject (after every key was tried).
  */
 export interface BlobBackend {
-    putBlob(hash: string, bytes: Uint8Array): Promise<void>;
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    hasBlobs(hashes: string[]): Promise<Set<string>>;
-    deleteBlobs(hashes: string[]): Promise<number>;
+    put(key: string, bytes: Uint8Array): Promise<void>;
+    get(key: string): Promise<Uint8Array | undefined>;
+    delete(keys: readonly string[]): Promise<void>;
 }
 /**
- * SQL BlobBackend — the `snapshot_blob` table ops EXTRACTED VERBATIM from the tidb/pg file-snapshot stores (the
- * created_at-refreshing upsert, the bytes SELECT, the grace-window orphan DELETE→deleteBlobs, a has via SELECT). Two
- * dialect twins selected by `dialect`. Keeping the SQL byte-identical means the existing behaviour + the env-gated
- * real-DB integration suite are unchanged when MinIO is unset (the DEFAULT backend the file-snapshot stores construct).
- *
- * NOTE deleteBlobs here is the BYTE delete ONLY — it does NOT do the reference (`not in the manifest`) filter: that
- * check stays in the owning store, which computes the orphan hash SET from its own domain's manifest and hands it here. The grace-window `created_at < cutoff` guard is RETAINED on the delete so a just-written blob
- * that a concurrent in-flight snapshot still needs is never byte-deleted (delete-in-use is data loss; under-delete is
- * harmless — the next sweep collects it).
+ * A content-addressed read through a port — the index owner's ONE reading of `get`: the bytes under `hash`, or `undefined` when the
+ * port has none OR when the bytes it serves do not hash to `hash` (corruption on the wire, or a POISONED object written under a hash
+ * it does not match): fail-closed, never wrong bytes. A content-addressed store's whole safety rests on bytes-match-hash; this is
+ * where both index owners judge it (the file-history blob index, the attachment store).
  */
-export declare class SqlBlobBackend implements BlobBackend {
-    private readonly dialect;
-    private readonly pool;
-    /** Explicit per-blob cap (the operator's `SNAPSHOT_BLOB_SQL_MAX_BYTES`); absent ⇒ the derivation in {@link sqlBlobCapOf} over the walls of the connection each write borrows. */
-    private readonly explicitCapBytes;
-    /** Blob-domain table ([ref] blob 域隔离:file-history 域用自己的表,reap/GC 不跨域)。代码内字面量,非用户输入。 */
-    private readonly table;
-    /** The write path's connection source: every `putBlob` borrows ONE connection from it (through {@link connectJudged}), judges on that connection's walls, writes on it. */
-    private readonly db;
-    /** Where a stale connection's replacement is logged ({@link connectJudged}); the boot assembly passes the service logger. */
-    private readonly log;
-    constructor(dialect: SqlDialect, pool: MysqlPool | PgPool, maxBytes?: number, table?: string, log?: Pick<Logger, "warn">);
-    /** The created_at-refreshing content-addressed upsert — VERBATIM the tidb/pg stores' `putBlobRow`. Refreshes
-     *  created_at even on a dedup hit so a re-used/just-written blob is "touched=now" and GC-grace-protected.
-     *  (a): an over-cap blob is REJECTED (typed {@link BlobTooLargeError}) BEFORE the driver ever sees the bytes —
-     *  the alternative is an inscrutable packet-limit error deep in the driver, and on the HTTP face a 502 that
-     *  invites the peer to retry a blob that can never land.
-     *  🔴 The cap is judged ON THE CONNECTION THAT WRITES ([ref]): `max_allowed_packet` is a session value, fixed per
-     *  connection, 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. Never a pool-level reading, never a bare `pool.query`. */
-    putBlob(hash: string, bytes: Uint8Array): Promise<void>;
-    /** The bytes for `hash` (undefined if absent) — VERBATIM the tidb/pg stores' getBlob SELECT. A pool/query error
-     *  PROPAGATES (a transient DB fault is loud, not a silent "missing blob" — parity with the MinIO backend's throw). */
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    /** The subset of `hashes` that exist — a single `blob_hash IN (...)` SELECT (idempotency / reap probe). */
-    hasBlobs(hashes: string[]): Promise<Set<string>>;
-    /** Byte-delete the given hashes (the orphan SET is computed by the CALLER from its own domain's manifest). Retains
-     *  the grace-window guard so a just-written blob a concurrent in-flight write needs is never delete-in-use — VERBATIM
-     *  the tidb/pg stores' gcOrphanBlobs delete, minus the reference clause (the caller already excluded referenced
-     *  hashes). Best-effort: a delete error is swallowed (under-delete is harmless). */
-    deleteBlobs(hashes: string[]): Promise<number>;
-}
-/** SHARED index op(workspace 浏览面 #3,[ref]②)—— per-blob 字节数,读 SQL INDEX 的 `byte_len`
- *  列(sqlHasBlobs 同款单 IN 查询;MinIO 后端的 bytes-NULL 索引行同样带 byte_len,两后端同源)。
- *  tree/file 面的 size 投影与「超限先拒后拉」都靠它——绝不为拿大小去 getBlob 整块字节。 */
-export declare function sqlBlobSizes(dialect: SqlDialect, pool: MysqlPool | PgPool, hashes: string[]): Promise<Map<string, number>>;
+export declare function readAtAddress(port: Pick<BlobBackend, "get">, hash: string): Promise<Uint8Array | undefined>;
 export interface MinioBlobBackendConfig {
     endpoint: string;
     bucket: string;
     accessKey: string;
     secretKey: string;
     region?: string;
-    /** Key prefix for blob objects, e.g. "blobs/". Object key = keyPrefix + hash. Default "blobs/". */
+    /** Key prefix for blob objects, e.g. "blobs/". Object key = keyPrefix + key. Default "blobs/". */
     keyPrefix?: string;
     /** Presigned-URL TTL (seconds). Default 3600 (1h) — must comfortably exceed a ~64 MiB single-PUT/GET on a slow link
      *  (a SigV4 X-Amz-Expires bounds the WHOLE transfer from X-Amz-Date; a too-short TTL fails mid-stream). */
@@ -155,22 +33,6 @@ export interface MinioBlobBackendConfig {
     /** 测试注入口(listObjects 分页钉用);生产缺省 global fetch。 */
     fetchImpl?: typeof fetch;
 }
-/**
- * MinIO BlobBackend — content-addressed bytes in an S3-compatible object store, via the zero-dependency
- * {@link presignS3Url} SigV4 generator + `fetch` (NO S3 SDK; the repo's no-SDK posture). The object key is
- * `keyPrefix + hash` (content-addressed → idempotent PUT, dedup across snapshots is automatic).
- *
- * THE SQL INDEX: the bytes go to MinIO, but a `snapshot_blob` INDEX row `(blob_hash, byte_len, created_at)` with bytes
- * NULL is kept in SQL (same pool/dialect). This is what makes the orphan-reference computation + the created_at grace
- * window + the §10 presence pre-check work identically to the SQL backend (see the file header). hasBlobs reads the
- * index; putBlob PUTs then upserts the index (created_at-refresh on conflict); deleteBlobs deletes the grace-passed
- * index rows AND the matching MinIO objects (called ONLY from the async sweep reaper).
- *
- * INTEGRITY (security-critical): getBlob VERIFIES sha256(bytes) === hash before returning. A content-addressed store's
- * whole safety rests on bytes-match-hash; a mismatch means corruption (network) or POISONING (a hostile object written
- * under a hash it doesn't match) — treated as ABSENT (undefined), NEVER returning wrong bytes. This mirrors the
- * importManifest content-address check the SQL stores already do.
- */
 /** 鲁棒性批2 C2/C3/C6(2026-08-03):S3 兼容端点 IO 的统一 abort 上界(fleet-client C1 定常量形
  *  先例)。半开端点此前各挂 undici 默认 ~300s headersTimeout——blob GET 卡住 restore/session-import
  *  同步路径,SendUserFile 工具调用永不返回。120s 对慢链路 ~64MiB 单 PUT/GET 仍宽裕(presignTtlSec
@@ -185,45 +47,36 @@ export type BucketProbe = {
     readonly state: "unknown";
     readonly detail: string;
 };
+/**
+ * The object-storage port: bytes in an S3-compatible store under `keyPrefix + key` (content-addressed keys ⇒ an idempotent PUT and
+ * dedup across writers). Object I/O only — no SQL, no index, no grace window, no content-address check (those are the index
+ * owner's). Beyond the port's three members it carries the object store's own reads a deployment needs: `listObjects` / `headObject`
+ * (the attachment store's orphan-object sweep) and `probeBucket` (the boot-time bucket check).
+ */
 export declare class MinioBlobBackend implements BlobBackend {
     private readonly cfg;
     private readonly keyPrefix;
     private readonly ttl;
-    /** The SQL index pool+dialect, or undefined for an index-LESS backend (the migration script + the unit suite, which
-     *  exercise ONLY the object I/O — put/get/has-by-HEAD/delete — with no DB). When undefined, hasBlobs falls back to a
-     *  HEAD-per-hash probe and deleteBlobs ignores the grace window (the script is a stop-the-world copy, not the live GC
-     *  path). The file-snapshot stores ALWAYS pass the pool, so the live reference-tracking always has the index. */
-    private readonly indexPool?;
-    private readonly indexDialect?;
-    /** Blob-domain index table ([ref] 域隔离,SqlBlobBackend.table 同款;默认 = E19 纪元的 snapshot_blob)。 */
-    private readonly indexTable;
-    constructor(cfg: MinioBlobBackendConfig, index?: {
-        dialect: SqlDialect;
-        pool: MysqlPool | PgPool;
-        table?: string;
-    });
+    /** 六个站点(put / get / delete / listObjects / headObject / probeBucket)的唯一出口:端点回重定向 ⇒ 拒,预签名 URL 与对象体不被带去 `Location`。 */
+    private readonly egressFetch;
+    constructor(cfg: MinioBlobBackendConfig);
     private objectKey;
     private presign;
-    /** PUT the bytes under the content-addressed key, THEN upsert the SQL INDEX row (bytes NULL, created_at refresh on
-     *  conflict — the SAME grace discipline as SqlBlobBackend, so a just-PUT blob an in-flight snapshot needs is touched=
-     *  now and protected). Idempotent (same hash ⇒ overwrite-with-identical-bytes + created_at bump). A non-2xx PUT throws
-     *  (an upload failure must surface — a silent drop would later read_failed on restore). The PUT happens BEFORE the
-     *  index upsert so an index row never claims a blob the object store doesn't hold (an index row with no object would
-     *  let hasBlobs report a phantom present; the reverse — an object with no index — is harmless and pruned by a bucket
-     *  lifecycle if it ever happens). NOTE no post-PUT read-back verify on the LIVE path (perf): content-addressing
-     *  catches a corrupted PUT at the next getBlob sha-check (fail-closed); the one-time migration script DOES read-back. */
-    putBlob(hash: string, bytes: Uint8Array): Promise<void>;
-    /** GET the bytes for `hash`, then VERIFY content-address (sha256(bytes)===hash). THREE branches (finding 11):
-     *   - 404 → undefined (genuinely ABSENT — the file-snapshot store treats undefined as a missing blob).
-     *   - sha256 MISMATCH → undefined (corruption/poisoning; treat corrupt-as-absent, fail-CLOSED, NEVER wrong bytes).
-     *   - a NON-2xx-NON-404 (5xx/throttle) OR a network/fetch REJECT → THROW (a TRANSIENT fault must fail LOUD so the
-     *     restore/import surfaces an error, NOT silently drop a file as "missing"; the SQL backend likewise propagates a
-     *     pool error). The snapshot store's restore() wraps applyManifest so this throw becomes a {ok:false} restore_failed. */
-    getBlob(hash: string): Promise<Uint8Array | undefined>;
-    /** The subset of `hashes` present — reads the SQL INDEX (cheaper than a HEAD-per-hash AND consistent with the SQL
-     *  backend). Falls back to a presigned HEAD per hash ONLY in object-only mode (no index pool: the migration / unit
-     *  path). The caller passes DISTINCT hashes (migration idempotency batch / reap orphan set / §10 presence pre-check). */
-    hasBlobs(hashes: string[]): Promise<Set<string>>;
+    /** PUT the bytes under the key. A non-2xx PUT throws (an upload failure must surface — a silent drop would later read_failed on
+     *  restore). NOTE no post-PUT read-back verify on the live path (perf): a corrupted PUT is caught at the next read's content-address
+     *  check (fail-closed). */
+    put(key: string, bytes: Uint8Array): Promise<void>;
+    /** GET the bytes under the key. THREE branches (finding 11):
+     *   - 404 → undefined (genuinely ABSENT).
+     *   - 2xx → the bytes, unjudged (the index owner checks them against the hash: {@link readAtAddress}).
+     *   - a NON-2xx-NON-404 (5xx/throttle) OR a network/fetch REJECT → THROW (a TRANSIENT fault must fail LOUD so the restore/import
+     *     surfaces an error, NOT silently drop a file as "missing"). */
+    get(key: string): Promise<Uint8Array | undefined>;
+    /** DELETE every key's object, at most {@link MINIO_OP_CONCURRENCY} in flight (no FD / throttle storm). Each key is independent: a
+     *  2xx or a 404 (already gone) is a success; any other answer or a network failure is a failure. Every key is tried; then, if any
+     *  failed, the call REJECTS naming how many (🔴 复审 F4 的同一判据:对象存储完全不可写时绝不报「清理成功」—— 失败只在这里说出来,
+     *  调用方据此记账,不吞)。 */
+    delete(keys: readonly string[]): Promise<void>;
     /** D-1 孤儿对象 GC(clay 拍 2026-07-28):列举本后端 keyPrefix 下的全部对象(ListObjectsV2 分页,
      *  零依赖 XML 取 <Key>/<LastModified>/<NextContinuationToken>)。**server 端 sweep 专用**——presign 的
      *  bucket-GET 列举能力绝不外发。响应非 2xx 即 throw(sweep 调用方自 catch:列举失败=本轮跳过,
@@ -241,13 +94,5 @@ export declare class MinioBlobBackend implements BlobBackend {
      *  🔴 只有「404 且体里是 `NoSuchBucket`」才算缺桶;网络不通 / 403(凭据不能列举 ≠ 桶不在)/ 5xx / 没有 NoSuchBucket 的 404(代理 / 路径错)
      *  都**证明不了**缺桶 ⇒ `unknown`,调用方不拒启、只报一次。总函数:不抛。`timeoutMs`:boot 期调用方给的单次上界(黑洞端点不许把起服拖到 120s)。 */
     probeBucket(timeoutMs?: number): Promise<BucketProbe>;
-    /** Byte-delete the given hashes — called ONLY from the async sweepOrphanBlobs reaper (NEVER the synchronous purge
-     *  path). Honors the SAME created_at grace window as the SQL backend: with an index, DELETE the grace-passed index
-     *  rows first (the index's created_at is the authoritative age — an S3 object carries no service-controlled timestamp
-     *  the backend reads), then delete the MinIO objects ONLY for those grace-passed hashes (so a just-PUT blob an
-     *  in-flight snapshot needs is NOT delete-in-use). ERROR-TOLERANT + BOUNDED: each object delete is independent (a
-     *  failure is skipped → retried next sweep), at most MINIO_OP_CONCURRENCY in flight (no FD/throttle storm). In
-     *  object-only mode (no index pool: the migration/unit cleanup path) it deletes every given hash with no grace. */
-    deleteBlobs(hashes: string[]): Promise<number>;
 }
 //# sourceMappingURL=blob-backend.d.ts.map

package/dist/plugins/blob-backend.js

@@ -1,57 +1,12 @@
 import { createHash } from "node:crypto";
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
 import { isNoSuchBucketAnswer } from "./s3-answer.js";
-import { connectJudged, mysqlDriver, packetWallStatementBytes, pgDriver, rowWallPayloadBytes, sqlWallsOf } from "./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";
-    }
+import { createEgressFetch } from "../egress-redirect.js";
+export async function readAtAddress(port, hash) {
+    const bytes = await port.get(hash);
+    if (bytes === undefined)
+        return undefined;
+    return createHash("sha256").update(bytes).digest("hex") === hash ? bytes : undefined;
 }
 const MINIO_OP_CONCURRENCY = 16;
 async function mapBounded(items, limit, fn) {
@@ -64,143 +19,26 @@ async function mapBounded(items, limit, fn) {
     });
     await Promise.all(workers);
 }
-export class SqlBlobBackend {
-    dialect;
-    pool;
-    explicitCapBytes;
-    table;
-    db;
-    log;
-    constructor(dialect, pool, maxBytes, table = "snapshot_blob", log) {
-        this.dialect = dialect;
-        this.pool = pool;
-        this.explicitCapBytes = maxBytes;
-        this.table = table;
-        this.db = dialect === "mysql" ? mysqlDriver(pool) : pgDriver(pool);
-        this.log = log ?? createLogger();
-    }
-    async putBlob(hash, bytes) {
-        const judged = await connectJudged(this.db, (facts) => {
-            const connection = { dialect: this.dialect, facts };
-            const cap = sqlBlobCapOf(this.explicitCapBytes, 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.table} (blob_hash, byte_len, bytes, created_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)`
-                : `INSERT INTO ${this.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 getBlob(hash) {
-        if (this.dialect === "mysql") {
-            const [rows] = await this.pool.query(`SELECT bytes FROM ${this.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.table} WHERE blob_hash = $1`, [hash]);
-        return b.rows[0]?.bytes != null ? new Uint8Array(b.rows[0].bytes) : undefined;
-    }
-    async hasBlobs(hashes) {
-        return sqlHasBlobs(this.dialect, this.pool, hashes, this.table);
-    }
-    async deleteBlobs(hashes) {
-        const deleted = await sqlDeleteIndexRowsPastGrace(this.dialect, this.pool, hashes, this.table);
-        return deleted.length;
-    }
-}
-async function sqlHasBlobs(dialect, pool, hashes, table = "snapshot_blob") {
-    if (hashes.length === 0)
-        return new Set();
-    const distinct = [...new Set(hashes)];
-    if (dialect === "mysql") {
-        const ph = distinct.map(() => "?").join(",");
-        const [rows] = await pool.query(`SELECT blob_hash FROM ${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 pool.query(`SELECT blob_hash FROM ${table} WHERE blob_hash IN (${ph})`, distinct);
-    return new Set(r.rows.map((row) => row.blob_hash));
-}
-export async function sqlBlobSizes(dialect, pool, hashes) {
-    if (hashes.length === 0)
-        return new Map();
-    const distinct = [...new Set(hashes)];
-    const CHUNK = 1000;
-    const out = new Map();
-    for (let i = 0; i < distinct.length; i += CHUNK) {
-        const part = distinct.slice(i, i + CHUNK);
-        if (dialect === "mysql") {
-            const ph = part.map(() => "?").join(",");
-            const [rows] = await pool.query(`SELECT blob_hash, byte_len FROM snapshot_blob WHERE blob_hash IN (${ph})`, part);
-            for (const r of rows)
-                out.set(String(r.blob_hash), Number(r.byte_len));
-        }
-        else {
-            const ph = part.map((_, j) => `$${j + 1}`).join(",");
-            const r = await pool.query(`SELECT blob_hash, byte_len FROM snapshot_blob WHERE blob_hash IN (${ph})`, part);
-            for (const row of r.rows)
-                out.set(row.blob_hash, Number(row.byte_len));
-        }
-    }
-    return out;
-}
-async function sqlDeleteIndexRowsPastGrace(dialect, pool, hashes, table = "snapshot_blob") {
-    if (hashes.length === 0)
-        return [];
-    const distinct = [...new Set(hashes)];
-    const cutoff = new Date(Date.now() - BLOB_GC_GRACE_MS);
-    if (dialect === "mysql") {
-        const ph = distinct.map(() => "?").join(",");
-        const grace = await pool
-            .query(`SELECT blob_hash FROM ${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 pool
-            .query(`DELETE FROM ${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 pool
-        .query(`DELETE FROM ${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);
-}
 export const OBJECT_STORE_IO_TIMEOUT_MS = 120_000;
 export class MinioBlobBackend {
     cfg;
     keyPrefix;
     ttl;
-    indexPool;
-    indexDialect;
-    indexTable;
-    constructor(cfg, index) {
+    egressFetch;
+    constructor(cfg) {
         this.cfg = cfg;
         this.keyPrefix = cfg.keyPrefix ?? "blobs/";
         this.ttl = cfg.presignTtlSec ?? 3600;
-        this.indexTable = index?.table ?? "snapshot_blob";
-        if (index) {
-            this.indexDialect = index.dialect;
-            this.indexPool = index.pool;
-        }
+        this.egressFetch = createEgressFetch("declare the final object-store address as MINIO_ENDPOINT / S3_ENDPOINT", cfg.fetchImpl);
     }
-    objectKey(hash) {
-        return `${this.keyPrefix}${hash}`;
+    objectKey(key) {
+        return `${this.keyPrefix}${key}`;
     }
-    presign(hash, method) {
+    presign(key, method) {
         return presignS3Url({
             endpoint: this.cfg.endpoint,
             bucket: this.cfg.bucket,
-            key: this.objectKey(hash),
+            key: this.objectKey(key),
             method: method,
             accessKey: this.cfg.accessKey,
             secretKey: this.cfg.secretKey,
@@ -208,60 +46,53 @@ export class MinioBlobBackend {
             expiresSec: this.ttl,
         });
     }
-    async putBlob(hash, bytes) {
-        const url = this.presign(hash, "PUT");
-        const res = await (this.cfg.fetchImpl ?? fetch)(url, { method: "PUT", body: bytes, signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
+    async put(key, bytes) {
+        const url = this.presign(key, "PUT");
+        const res = await this.egressFetch(url, { method: "PUT", body: bytes, signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
         if (!res.ok) {
             const detail = await res.text().catch(() => "");
-            throw new Error(`MinioBlobBackend.putBlob ${hash}: HTTP ${res.status} ${detail.slice(0, 200)}`);
-        }
-        if (this.indexPool && this.indexDialect) {
-            if (this.indexDialect === "mysql") {
-                await this.indexPool.query(`INSERT INTO ${this.indexTable} (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.indexPool.query(`INSERT INTO ${this.indexTable} (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()]);
-            }
+            throw new Error(`MinioBlobBackend.put ${key}: HTTP ${res.status} ${detail.slice(0, 200)}`);
         }
     }
-    async getBlob(hash) {
-        const url = this.presign(hash, "GET");
+    async get(key) {
+        const url = this.presign(key, "GET");
         let res;
         try {
-            res = await (this.cfg.fetchImpl ?? fetch)(url, { method: "GET", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
+            res = await this.egressFetch(url, { method: "GET", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
         }
         catch (err) {
-            throw new Error(`MinioBlobBackend.getBlob ${hash}: transient fetch failure: ${err.message}`);
+            throw new Error(`MinioBlobBackend.get ${key}: transient fetch failure: ${err.message}`);
         }
         if (res.status === 404)
             return undefined;
         if (!res.ok) {
             const detail = await res.text().catch(() => "");
-            throw new Error(`MinioBlobBackend.getBlob ${hash}: transient HTTP ${res.status} ${detail.slice(0, 200)}`);
+            throw new Error(`MinioBlobBackend.get ${key}: transient HTTP ${res.status} ${detail.slice(0, 200)}`);
         }
-        const buf = new Uint8Array(await res.arrayBuffer());
-        if (createHash("sha256").update(buf).digest("hex") !== hash)
-            return undefined;
-        return buf;
+        return new Uint8Array(await res.arrayBuffer());
     }
-    async hasBlobs(hashes) {
-        if (this.indexPool && this.indexDialect)
-            return sqlHasBlobs(this.indexDialect, this.indexPool, hashes, this.indexTable);
-        const distinct = [...new Set(hashes)];
-        const present = new Set();
-        await mapBounded(distinct, MINIO_OP_CONCURRENCY, async (hash) => {
+    async delete(keys) {
+        const distinct = [...new Set(keys)];
+        let failed = 0;
+        let firstFailure;
+        await mapBounded(distinct, MINIO_OP_CONCURRENCY, async (key) => {
             try {
-                const res = await (this.cfg.fetchImpl ?? fetch)(this.presign(hash, "HEAD"), { method: "HEAD", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
-                if (res.ok)
-                    present.add(hash);
+                const res = await this.egressFetch(this.presign(key, "DELETE"), { method: "DELETE", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
+                if (res.ok || res.status === 404)
+                    return;
+                failed++;
+                firstFailure ??= `${key}: HTTP ${res.status}`;
             }
-            catch {
+            catch (err) {
+                failed++;
+                firstFailure ??= `${key}: ${err instanceof Error ? err.message : String(err)}`;
             }
         });
-        return present;
+        if (failed > 0)
+            throw new Error(`MinioBlobBackend.delete: ${failed} of ${distinct.length} object(s) could not be deleted (first: ${firstFailure})`);
     }
     async *listObjects() {
-        const f = this.cfg.fetchImpl ?? fetch;
+        const f = this.egressFetch;
         let token;
         const MAX_PAGES = 1000;
         let pages = 0;
@@ -299,7 +130,7 @@ export class MinioBlobBackend {
         } while (token !== undefined);
     }
     async headObject(hash) {
-        const f = this.cfg.fetchImpl ?? fetch;
+        const f = this.egressFetch;
         const res = await f(this.presign(hash, "HEAD"), { method: "HEAD", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
         if (!res.ok)
             return undefined;
@@ -308,7 +139,7 @@ export class MinioBlobBackend {
         return { lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() };
     }
     async probeBucket(timeoutMs = OBJECT_STORE_IO_TIMEOUT_MS) {
-        const f = this.cfg.fetchImpl ?? fetch;
+        const f = this.egressFetch;
         const url = presignS3ListUrl({
             endpoint: this.cfg.endpoint,
             bucket: this.cfg.bucket,
@@ -333,29 +164,5 @@ export class MinioBlobBackend {
             return { state: "missing" };
         return { state: "unknown", detail: `HTTP ${res.status}` };
     }
-    async deleteBlobs(hashes) {
-        if (hashes.length === 0)
-            return 0;
-        let toDelete;
-        if (this.indexPool && this.indexDialect) {
-            toDelete = await sqlDeleteIndexRowsPastGrace(this.indexDialect, this.indexPool, hashes, this.indexTable);
-        }
-        else {
-            toDelete = [...new Set(hashes)];
-        }
-        if (toDelete.length === 0)
-            return 0;
-        let okCount = 0;
-        await mapBounded(toDelete, MINIO_OP_CONCURRENCY, async (hash) => {
-            try {
-                const res = await (this.cfg.fetchImpl ?? fetch)(this.presign(hash, "DELETE"), { method: "DELETE", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
-                if (res.ok || res.status === 404)
-                    okCount++;
-            }
-            catch {
-            }
-        });
-        return okCount;
-    }
 }
 //# sourceMappingURL=blob-backend.js.map