@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/blob-backend.js

@@ -1,50 +1,7 @@
-/**
- * BlobBackend — the content-addressed BYTE store for the durable FileSnapshotStore (E19 / 2c), DECOUPLED from the
- * manifest. clay 2026-06-26: the conversation TRANSCRIPT stays DB-first; the ONLY thing that moves to an object store
- * is the file-snapshot BLOBS (binary file content — a perf-suboptimal TiDB blob row; the tree bound is core's
- * DEFAULT_SNAPSHOT_BOUNDS 256 MiB with NO per-file cap, hence the (a) SQL per-blob cap below). This seam
- * lets the tidb/pg file-snapshot stores keep their MANIFEST in SQL (`snapshot_manifest`, the hot relPath→hash rows the
- * transcript read NEVER touches) while routing the heavy bytes either to SQL (`snapshot_blob.bytes`, the DEFAULT — a
- * MINIO-unset deployment is byte-identical to today) or to MinIO (the offload).
- *
- * THE SQL BLOB INDEX (clay 2026-06-26 design correction). EVEN under the MinIO backend, every blob keeps an INDEX row in
- * `snapshot_blob` — `(blob_hash, byte_len, created_at)` with `bytes` NULL (the bytes live in MinIO). This is the load-
- * bearing decision: ALL the reference-tracking (gcOrphanBlobs computes the orphan SET = `snapshot_blob` rows NOT IN
- * `snapshot_manifest`) and the created_at GRACE WINDOW (delete-in-use protection) read that index, so they work
- * IDENTICALLY for both backends. WITHOUT the index, a MinIO deployment would never GC its objects AND an E21 session
- * purge would leave the file CONTENT in MinIO forever (a privacy/compliance breach). With it, a purged session's blobs
- * become orphans (no manifest) and are EVENTUALLY collected by the async sweepOrphanBlobs reaper.
- *
- * ASYNC byte deletion (clay 2026-06-26): MinIO objects are NEVER deleted on the synchronous E21 purge / reap path (a
- * synchronous external-store delete could block/fail the whole purge on a network blip). The purge deletes ONLY the SQL
- * manifest rows → the blob becomes an orphan; the periodic `sweepOrphanBlobs` reaper (main.ts) deletes the MinIO objects
- * + the index rows LATER, error-tolerantly (a single MinIO delete failure is skipped + retried next sweep) → bounded-
- * window EVENTUAL CONSISTENCY. {@link BlobBackend.deleteBlobs} is therefore only ever called from the reaper.
- *
- * REUSE iron rule (core-service-boundary / no-stopgap): {@link SqlBlobBackend} EXTRACTS the `snapshot_blob` ops from the
- * tidb/pg stores VERBATIM (the created_at-refreshing upsert, the SELECT, the grace-window orphan DELETE), so the SQL
- * default path is byte-identical to before this refactor. {@link MinioBlobBackend} REUSES the existing zero-dependency
- * {@link presignS3Url} SigV4 generator + `fetch` (the repo's no-SDK posture — OTLP + the k8s adapter are zero-dep too);
- * it NEVER pulls in an S3 SDK, and it REUSES the SqlBlobBackend's index ops for the (blob_hash, byte_len, created_at)
- * rows (the bytes-NULL index — no SQL drift between the two backends' reference-tracking).
- */
 import { createHash } from "node:crypto";
 import { presignS3Url, presignS3ListUrl } from "./s3-presign.js";
-/** Orphan-blob GC grace (SHARED with the file-snapshot stores' BLOB_GC_GRACE_MS) — a blob is GC-eligible only if
- *  unreferenced AND untouched for this long; putBlob refreshes created_at on every touch (incl a dedup hit) so an
- *  in-flight snapshot's blobs are protected from delete-in-use. 1h ≫ any bounded snapshot. */
 const BLOB_GC_GRACE_MS = 3_600_000;
-/** (a)(clay 拍 a+c,2026-07-27)tidb 方言的默认 per-blob 帽 = **6 MiB,TiDB 自己的默认
- *  `txn-entry-size-limit`**。两堵墙真库实测(k3s8 tidb-test v7.5.1 默认配置,2026-07-27 探针):
- *  7MiB=`entry too large`(entry 墙,默认 6291456)、31MiB=同、32MiB=`max_allowed_packet`(包墙,
- *  64MiB ÷ ~2× 文本协议膨胀)——矮墙是 entry 的 6MiB,不是先前推测的包墙 ~31MiB。帽=诚实拒绝:
- *  超限 blob 在 query 之前 typed 拒(消费面 HTTP 413 / capture warn 拿到可行动信息);**帽拒绝的
- *  在默认配置下本来也落不进去 ⇒ 零回归**。调大过 entry 限/packet 的部署用 SNAPSHOT_BLOB_SQL_MAX_BYTES
- *  放宽(两方言都生效)。**pg 方言默认不设帽**(扩展协议无这两堵墙,不人为降档)。D-1 附件战役同墙
- *  教训:task-attachment-store.ts:19。 */
 export const SQL_BLOB_DEFAULT_MAX_BYTES = 6_291_456;
-/** typed 判别错:blob 超过 SQL 店的承载帽。判别码供店侧结果映射/HTTP 面/日志使用——绝不能与
- *  transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)。 */
 export class BlobTooLargeError extends Error {
     code = "blob_too_large_for_sql";
     constructor(byteLen, capBytes) {
@@ -55,11 +12,7 @@ export class BlobTooLargeError extends Error {
         this.name = "BlobTooLargeError";
     }
 }
-/** Max concurrent MinIO object ops (HEAD/DELETE) per reap/sweep batch — bound the open sockets/presigns so a sweep with
- *  tens of thousands of orphans can't exhaust FDs / throttle MinIO (finding 22). The full hash set is processed in
- *  windows of this size; a slow/failed object never blocks the others (each is independently error-tolerant). */
 const MINIO_OP_CONCURRENCY = 16;
-/** Run `fn` over `items` with at most `limit` in flight at once (a tiny bounded-concurrency pool — no dependency). */
 async function mapBounded(items, limit, fn) {
     let i = 0;
     const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
@@ -70,33 +23,15 @@ async function mapBounded(items, limit, fn) {
     });
     await Promise.all(workers);
 }
-/**
- * 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 `NOT IN (SELECT … snapshot_manifest)` orphan
- * filter (that reference check stays in the file-snapshot store, which computes the orphan hash SET from the 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).
- */
 export class SqlBlobBackend {
     dialect;
     pool;
-    /** Effective per-blob cap: explicit ctor value wins; else tidb=SQL_BLOB_DEFAULT_MAX_BYTES, pg=uncapped. */
     capBytes;
     constructor(dialect, pool, maxBytes) {
         this.dialect = dialect;
         this.pool = pool;
         this.capBytes = maxBytes ?? (dialect === "tidb" ? SQL_BLOB_DEFAULT_MAX_BYTES : Number.POSITIVE_INFINITY);
     }
-    /** 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. */
     async putBlob(hash, bytes) {
         if (bytes.byteLength > this.capBytes)
             throw new BlobTooLargeError(bytes.byteLength, this.capBytes);
@@ -107,8 +42,6 @@ export class SqlBlobBackend {
             await this.pool.query("INSERT INTO snapshot_blob (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()]);
         }
     }
-    /** 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). */
     async getBlob(hash) {
         if (this.dialect === "tidb") {
             const [rows] = await this.pool.query("SELECT bytes FROM snapshot_blob WHERE blob_hash = ?", [hash]);
@@ -117,22 +50,14 @@ export class SqlBlobBackend {
         const b = await this.pool.query("SELECT bytes FROM snapshot_blob WHERE blob_hash = $1", [hash]);
         return b.rows[0]?.bytes != null ? new Uint8Array(b.rows[0].bytes) : undefined;
     }
-    /** The subset of `hashes` that exist — a single `blob_hash IN (...)` SELECT (idempotency / reap probe). */
     async hasBlobs(hashes) {
         return sqlHasBlobs(this.dialect, this.pool, hashes);
     }
-    /** Byte-delete the given hashes (the orphan SET is computed by the caller from snapshot_manifest). Retains the
-     *  grace-window guard so a just-written blob a concurrent in-flight snapshot needs is never delete-in-use — VERBATIM
-     *  the tidb/pg stores' gcOrphanBlobs delete, minus the `NOT IN (SELECT … manifest)` clause (the caller already
-     *  excluded referenced hashes). Best-effort: a delete error is swallowed (under-delete is harmless). */
     async deleteBlobs(hashes) {
         const deleted = await sqlDeleteIndexRowsPastGrace(this.dialect, this.pool, hashes);
         return deleted.length;
     }
 }
-/** SHARED index op — the subset of `hashes` present as a `snapshot_blob` row (the SQL INDEX). Used by SqlBlobBackend
- *  AND MinioBlobBackend (the index is the single source of presence truth for both — cheaper + consistent than a
- *  HEAD-per-hash on MinIO; the bytes-NULL MinIO index row still counts as present). */
 async function sqlHasBlobs(dialect, pool, hashes) {
     if (hashes.length === 0)
         return new Set();
@@ -146,16 +71,10 @@ async function sqlHasBlobs(dialect, pool, hashes) {
     const r = await pool.query(`SELECT blob_hash FROM snapshot_blob WHERE blob_hash IN (${ph})`, distinct);
     return new Set(r.rows.map((row) => row.blob_hash));
 }
-/** SHARED index op(workspace 浏览面 #3,[1894]②)—— per-blob 字节数,读 SQL INDEX 的 `byte_len`
- *  列(sqlHasBlobs 同款单 IN 查询;MinIO 后端的 bytes-NULL 索引行同样带 byte_len,两后端同源)。
- *  tree/file 面的 size 投影与「超限先拒后拉」都靠它——绝不为拿大小去 getBlob 整块字节。 */
 export async function sqlBlobSizes(dialect, pool, hashes) {
     if (hashes.length === 0)
         return new Map();
     const distinct = [...new Set(hashes)];
-    // 🔴 复审 F7:分块。workspace list 腿对每个快照各查一次全 manifest 的 unique hash——按 core 上限
-    // (maxFiles 10000)一次就是 1 万元素的 IN,`?limit=100` 则是 100 次这样的串行往返。PG 的 65535
-    // 参数协议墙虽未触到,但 1 万元素 IN 本身对计划器/网络包就是坏形。1000/块是保守值。
     const CHUNK = 1000;
     const out = new Map();
     for (let i = 0; i < distinct.length; i += CHUNK) {
@@ -175,10 +94,6 @@ export async function sqlBlobSizes(dialect, pool, hashes) {
     }
     return out;
 }
-/** SHARED index op — DELETE the index rows for `hashes` that have passed the grace window (created_at < cutoff). Returns
- *  the hashes ACTUALLY deleted (so the MinIO backend deletes exactly the objects whose index rows it just removed — and
- *  a within-grace young orphan is left for a later sweep). Best-effort: a DB error is swallowed (under-delete is
- *  harmless; the next sweep retries). The grace guard (delete-in-use protection) is IDENTICAL across both backends. */
 async function sqlDeleteIndexRowsPastGrace(dialect, pool, hashes) {
     if (hashes.length === 0)
         return [];
@@ -186,8 +101,6 @@ async function sqlDeleteIndexRowsPastGrace(dialect, pool, hashes) {
     const cutoff = new Date(Date.now() - BLOB_GC_GRACE_MS);
     if (dialect === "tidb") {
         const ph = distinct.map(() => "?").join(",");
-        // MySQL/TiDB DELETE can't RETURNING — SELECT the grace-passed subset first, then DELETE it (the SELECT+DELETE
-        // race is benign: a row that flips referenced between them just isn't deleted = under-delete = harmless).
         const grace = await pool
             .query(`SELECT blob_hash FROM snapshot_blob WHERE created_at < ? AND blob_hash IN (${ph})`, [cutoff, ...distinct])
             .then(([rows]) => rows.map((r) => String(r.blob_hash)))
@@ -206,35 +119,11 @@ async function sqlDeleteIndexRowsPastGrace(dialect, pool, hashes) {
         .catch(() => undefined);
     return (r?.rows ?? []).map((row) => row.blob_hash);
 }
-/**
- * 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
- *  注释同口径),远小于病形。send-user-file 与 leader/diffup 同 import 此常量。 */
 export const OBJECT_STORE_IO_TIMEOUT_MS = 120_000;
 export class MinioBlobBackend {
     cfg;
     keyPrefix;
     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. */
     indexPool;
     indexDialect;
     constructor(cfg, index) {
@@ -250,8 +139,6 @@ export class MinioBlobBackend {
         return `${this.keyPrefix}${hash}`;
     }
     presign(hash, method) {
-        // presignS3Url only declares GET|PUT in its param type, but the SigV4 canonicalization is identical for any verb
-        // (host-only SignedHeaders, UNSIGNED-PAYLOAD) — HEAD/DELETE sign correctly with the same string math. Cast the verb.
         return presignS3Url({
             endpoint: this.cfg.endpoint,
             bucket: this.cfg.bucket,
@@ -263,26 +150,13 @@ export class MinioBlobBackend {
             expiresSec: this.ttl,
         });
     }
-    /** 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. */
     async putBlob(hash, bytes) {
         const url = this.presign(hash, "PUT");
-        // C2(2026-08-03):走注入座(此前直用全局 fetch=测试桩接不进的站点)+ abort 上界(半开端点
-        // 此前挂 undici ~300s;120s 对慢链路大对象仍宽裕,presignTtlSec 注释同口径)。六站点同批。
         const res = await (this.cfg.fetchImpl ?? fetch)(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)}`);
         }
-        // Upsert the bytes-NULL INDEX row (byte_len + created_at) so the orphan/grace reference-tracking + presence checks
-        // see this blob. Same created_at-refresh-on-conflict as the SQL backend. (No index pool ⇒ object-only mode = the
-        // migration/unit path; the live stores always pass it.)
         if (this.indexPool && this.indexDialect) {
             if (this.indexDialect === "tidb") {
                 await this.indexPool.query("INSERT INTO snapshot_blob (blob_hash, byte_len, bytes, created_at) VALUES (?,?,NULL,?) ON DUPLICATE KEY UPDATE created_at = VALUES(created_at)", [hash, bytes.byteLength, new Date()]);
@@ -292,12 +166,6 @@ export class MinioBlobBackend {
             }
         }
     }
-    /** 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. */
     async getBlob(hash) {
         const url = this.presign(hash, "GET");
         let res;
@@ -308,24 +176,19 @@ export class MinioBlobBackend {
             throw new Error(`MinioBlobBackend.getBlob ${hash}: transient fetch failure: ${err.message}`);
         }
         if (res.status === 404)
-            return undefined; // genuinely absent
+            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)}`);
         }
         const buf = new Uint8Array(await res.arrayBuffer());
-        // content-address integrity: the bytes MUST hash to the key. A mismatch = corrupt/poisoned → undefined (absent), NOT wrong bytes.
         if (createHash("sha256").update(buf).digest("hex") !== hash)
             return undefined;
         return buf;
     }
-    /** 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). */
     async hasBlobs(hashes) {
         if (this.indexPool && this.indexDialect)
             return sqlHasBlobs(this.indexDialect, this.indexPool, hashes);
-        // object-only mode (migration/unit): HEAD probe, bounded concurrency.
         const distinct = [...new Set(hashes)];
         const present = new Set();
         await mapBounded(distinct, MINIO_OP_CONCURRENCY, async (hash) => {
@@ -335,22 +198,13 @@ export class MinioBlobBackend {
                     present.add(hash);
             }
             catch {
-                /* treat an unreachable HEAD as absent — a false-absent only re-PUTs (idempotent) or re-checks; never a false-present */
             }
         });
         return present;
     }
-    /** D-1 孤儿对象 GC(clay 拍 2026-07-28):列举本后端 keyPrefix 下的全部对象(ListObjectsV2 分页,
-     *  零依赖 XML 取 <Key>/<LastModified>/<NextContinuationToken>)。**server 端 sweep 专用**——presign 的
-     *  bucket-GET 列举能力绝不外发。响应非 2xx 即 throw(sweep 调用方自 catch:列举失败=本轮跳过,
-     *  绝不把「列不出来」当「没有孤儿」)。 */
     async *listObjects() {
         const f = this.cfg.fetchImpl ?? fetch;
         let token;
-        // 🔴 复审 F3:分页上限。异常/代理后端回环或恒定的 continuation-token 会让本循环无界翻页
-        // (实测可翻 5001 页仍不停),叠加维护 tick 就是逐轮堆积。超限 fail-loud —— 与本函数既有的
-        // 「列不出来 ≠ 没有孤儿」口径一致(宁可整轮失败也不给出残缺的「孤儿全集」)。
-        // 1000 页 × 1000 键/页 = 100 万对象,远超任何真实附件语料;真撞上=后端异常而非规模问题。
         const MAX_PAGES = 1000;
         let pages = 0;
         do {
@@ -371,15 +225,14 @@ export class MinioBlobBackend {
             if (!res.ok)
                 throw new Error(`listObjects: MinIO ${res.status}`);
             const xml = await res.text();
-            // <Contents><Key>k</Key>…<LastModified>ISO</LastModified>…</Contents> —— 逐块取,键序无假设。
             for (const m of xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)) {
                 const block = m[1];
                 const key = /<Key>([^<]*)<\/Key>/.exec(block)?.[1];
                 const lm = /<LastModified>([^<]*)<\/LastModified>/.exec(block)?.[1];
                 if (key === undefined || !key.startsWith(this.keyPrefix))
-                    continue; // prefix 外键(理论不可达)跳过
+                    continue;
                 const ms = lm ? Date.parse(lm) : NaN;
-                yield { hash: key.slice(this.keyPrefix.length), lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() }; // 坏时间戳=按「新」处理(grace 保护,宁漏勿误删)
+                yield { hash: key.slice(this.keyPrefix.length), lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() };
             }
             const truncated = /<IsTruncated>true<\/IsTruncated>/.test(xml);
             token = truncated ? /<NextContinuationToken>([^<]*)<\/NextContinuationToken>/.exec(xml)?.[1] : undefined;
@@ -387,8 +240,6 @@ export class MinioBlobBackend {
                 throw new Error("listObjects: truncated response without NextContinuationToken");
         } while (token !== undefined);
     }
-    /** 单对象 HEAD 探针(复审 B-F1 的删前复查面):返回当前 LastModified(缺席=对象已不在)。
-     *  put 会 PUT 同键 ⇒ 刷新 LastModified,所以「删前再 HEAD 一次」能看见「刚刚被重新引用」的对象。 */
     async headObject(hash) {
         const f = this.cfg.fetchImpl ?? fetch;
         const res = await f(this.presign(hash, "HEAD"), { method: "HEAD", signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
@@ -396,28 +247,17 @@ export class MinioBlobBackend {
             return undefined;
         const lm = res.headers.get("last-modified");
         const ms = lm ? Date.parse(lm) : NaN;
-        return { lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() }; // 无/坏时间戳=按「新」处理(宁漏勿误删)
+        return { lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() };
     }
-    /** 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. */
     async deleteBlobs(hashes) {
         if (hashes.length === 0)
             return 0;
-        // Determine which hashes are grace-passed AND remove their index rows (so the index no longer claims them present).
-        // Order: index-row DELETE FIRST, then the object DELETE — if the object delete fails, the orphan re-appears only as
-        // an object with no index, which a later sweep can't re-target; acceptable (under-delete is harmless, and a bucket
-        // lifecycle rule prunes index-less objects). Doing it index-first keeps hasBlobs honest immediately.
         let toDelete;
         if (this.indexPool && this.indexDialect) {
             toDelete = await sqlDeleteIndexRowsPastGrace(this.indexDialect, this.indexPool, hashes);
         }
         else {
-            toDelete = [...new Set(hashes)]; // object-only mode (migration/unit cleanup): no grace, delete all given
+            toDelete = [...new Set(hashes)];
         }
         if (toDelete.length === 0)
             return 0;
@@ -425,16 +265,13 @@ export class MinioBlobBackend {
         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) });
-                // 🔴 复审 F4:统计**真实**删除数——index-less(附件)分支此前恒返回入参长度,MinIO 完全不可写
-                // 时指标/日志照报「清理成功」。2xx/404(已不在)都算删成功;其余=失败,不计数。
                 if (res.ok || res.status === 404)
                     okCount++;
             }
             catch {
-                /* error-tolerant: a failed/timed-out object delete is skipped → retried next sweep (eventual consistency) */
             }
         });
-        return okCount; // the index rows we removed = the work done (best-effort object deletes follow async)
+        return okCount;
     }
 }
 //# sourceMappingURL=blob-backend.js.map

package/dist/plugins/breaker-state-sql.js

@@ -1,7 +1,4 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-/** PG translation of the tidb-pool.ts `circuit_breaker` DDL (DATETIME(3)→TIMESTAMPTZ(3)). Disjoint from other
- *  stores' tables, so a self-contained ensureSchema is safe (no central-schema shadowing). TiDB's DDL lives
- *  centrally in tidb-pool.ts (no PG-side twin needed there — production wires ONE ensureTidbSchema). */
 export const PG_BREAKER_STATE_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS circuit_breaker (
      breaker_key VARCHAR(190) COLLATE "C"   NOT NULL,
@@ -12,29 +9,21 @@ export const PG_BREAKER_STATE_SCHEMA = [
      PRIMARY KEY (breaker_key)
    )`,
 ];
-/** Idempotent schema apply for the breaker table (the PG twin of tidb-pool.ts ensureSchema, scoped to this store). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_BREAKER_STATE_SCHEMA)
         await pool.query(stmt);
 }
-/** Dual-dialect cross-replica BreakerState. See the file header for the dialect-delta ledger. */
 export class SqlBreakerState {
     db;
     onWriteFail;
     cache = new Map();
     timer;
-    /** Keys with an in-flight write-through upsert. A concurrent `refresh()` must NOT overwrite or prune
-     *  these — their newer local value may not be in the DB yet. Closes the set()-vs-refresh race (core
-     *  1.40.0 council finding #5). */
     pending = new Set();
     writeFailStreak = 0;
-    constructor(db, 
-    /** LOW (SILENT-FALLBACK P1): write-through failure tap — streak per call, 0 on the recovery edge. */
-    onWriteFail) {
+    constructor(db, onWriteFail) {
         this.db = db;
         this.onWriteFail = onWriteFail;
     }
-    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
@@ -42,9 +31,9 @@ export class SqlBreakerState {
         return this.cache.get(key);
     }
     set(key, snap) {
-        this.cache.set(key, snap); // synchronous: the local breaker hot path sees it immediately
-        this.pending.add(key); // guard the in-flight write from a concurrent refresh
-        void this.writeThrough(key, snap); // async, best-effort; never throws into the caller
+        this.cache.set(key, snap);
+        this.pending.add(key);
+        void this.writeThrough(key, snap);
     }
     async writeThrough(key, snap) {
         try {
@@ -57,41 +46,18 @@ export class SqlBreakerState {
                 try {
                     this.onWriteFail?.(0);
                 }
-                catch { /* observability never breaks advisory state */ }
-            } // the new value is now in the DB → refresh may reconcile this key again
-            // KNOWN/ACCEPTED (audit B): two rapid set()s on the SAME key race their async writeThroughs — the
-            // older write can land last (no version column), so a later refresh() may briefly revert this
-            // replica to the older snapshot (e.g. re-close a just-opened breaker). Advisory state: the very
-            // next failure re-opens it locally (set() is synchronous on the hot path) and re-publishes. A
-            // monotonic guard would need versioned rows + CAS; not worth it for an advisory cache.
+                catch { }
+            }
         }
         catch {
             try {
                 this.onWriteFail?.(++this.writeFailStreak);
             }
-            catch { /* ditto */ } // LOW: previously a bare swallow
-            // Advisory state — swallow; a DB outage must not turn into a brain-call failure. Crucially we KEEP
-            // `pending` on failure: the DB still holds the OLD value, so releasing the guard here would let the
-            // next refresh() clobber this replica's just-set (correct) local value — silently resetting an open
-            // breaker toward a known-bad backend. The guard self-heals on the next successful set()/write.
+            catch { }
         }
     }
-    /**
-     * Pull the shared table into the local cache so this replica learns peers' trips, and PRUNE keys that
-     * vanished from the DB — but never touch a locally-pending write (its upsert may not have landed yet),
-     * else a just-`set` trip would be clobbered/reverted before it reaches the DB. Eventually consistent:
-     * a replica is at most one refresh interval behind a peer, never wrong in a data-losing way.
-     * `halfOpenInFlight` is intentionally not shared (it is a per-replica probe counter).
-     *
-     * SELECT text is byte-identical on both dialects (no placeholders) — written once, not through `q()`
-     * (same precedent as image-bake-store-sql.ts's queued-bake lookup).
-     */
     async refresh() {
         try {
-            // Snapshot the pending set BEFORE the read: a key whose write-through is in-flight when the SELECT starts may
-            // not be in the SELECT's snapshot yet, and its writeThrough can `pending.delete` DURING the await — so a
-            // check-after-read (`this.pending.has`) alone would let the stale row clobber the just-set local value. Skip a
-            // key pending NOW or at read-start (union) to actually close the set()-vs-refresh race (#5), not just narrow it.
             const pendingAtStart = new Set(this.pending);
             const guarded = (key) => this.pending.has(key) || pendingAtStart.has(key);
             const { rows } = await this.db.query("SELECT breaker_key, phase, failures, opened_at FROM circuit_breaker");
@@ -100,7 +66,7 @@ export class SqlBreakerState {
                 const key = String(r.breaker_key);
                 seen.add(key);
                 if (guarded(key))
-                    continue; // don't clobber a locally-pending newer value (#5)
+                    continue;
                 this.cache.set(key, {
                     phase: r.phase,
                     failures: Number(r.failures),
@@ -112,10 +78,8 @@ export class SqlBreakerState {
                     this.cache.delete(key);
         }
         catch {
-            // Keep the last-known cache on a transient read failure (fail static, don't blank the breaker).
         }
     }
-    /** Start the periodic refresh loop. `unref` so it never holds the process open. Returns `this`. */
     startRefresh(intervalMs = 5_000) {
         this.timer ??= setInterval(() => void this.refresh(), intervalMs);
         this.timer.unref?.();
@@ -127,13 +91,11 @@ export class SqlBreakerState {
         this.timer = undefined;
     }
 }
-/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBBreakerState extends SqlBreakerState {
     constructor(pool, onWriteFail) {
         super(mysqlDriver(pool), onWriteFail);
     }
 }
-/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgBreakerState extends SqlBreakerState {
     constructor(pool, onWriteFail) {
         super(pgDriver(pool), onWriteFail);