@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/blob-backend.js

@@ -1,7 +1,50 @@
+/**
+ * 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) {
@@ -12,7 +55,11 @@ 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 () => {
@@ -23,15 +70,33 @@ 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);
@@ -42,6 +107,8 @@ 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]);
@@ -50,14 +117,22 @@ 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();
@@ -71,10 +146,16 @@ 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) {
@@ -94,6 +175,10 @@ 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 [];
@@ -101,6 +186,8 @@ 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)))
@@ -119,10 +206,30 @@ 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.
+ */
 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) {
@@ -138,6 +245,8 @@ 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,
@@ -149,6 +258,14 @@ 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");
         const res = await fetch(url, { method: "PUT", body: bytes });
@@ -156,6 +273,9 @@ export class MinioBlobBackend {
             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()]);
@@ -165,6 +285,12 @@ 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;
@@ -175,19 +301,24 @@ export class MinioBlobBackend {
             throw new Error(`MinioBlobBackend.getBlob ${hash}: transient fetch failure: ${err.message}`);
         }
         if (res.status === 404)
-            return undefined;
+            return undefined; // genuinely absent
         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) => {
@@ -197,13 +328,22 @@ 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 {
@@ -224,14 +364,15 @@ 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;
+                    continue; // prefix 外键(理论不可达)跳过
                 const ms = lm ? Date.parse(lm) : NaN;
-                yield { hash: key.slice(this.keyPrefix.length), lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() };
+                yield { hash: key.slice(this.keyPrefix.length), lastModifiedMs: Number.isFinite(ms) ? ms : Date.now() }; // 坏时间戳=按「新」处理(grace 保护,宁漏勿误删)
             }
             const truncated = /<IsTruncated>true<\/IsTruncated>/.test(xml);
             token = truncated ? /<NextContinuationToken>([^<]*)<\/NextContinuationToken>/.exec(xml)?.[1] : undefined;
@@ -239,6 +380,8 @@ 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" });
@@ -246,17 +389,28 @@ 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)];
+            toDelete = [...new Set(hashes)]; // object-only mode (migration/unit cleanup): no grace, delete all given
         }
         if (toDelete.length === 0)
             return 0;
@@ -264,13 +418,16 @@ 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" });
+                // 🔴 复审 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;
+        return okCount; // the index rows we removed = the work done (best-effort object deletes follow async)
     }
 }
 //# sourceMappingURL=blob-backend.js.map

package/dist/plugins/breaker-state-sql.d.ts

@@ -1,28 +1,92 @@
+/**
+ * Cross-replica circuit-breaker state (core 1.38 `BreakerState`) — SINGLE-FILE DUAL-DIALECT
+ * (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical `TiDBBreakerState` /
+ * `PgBreakerState` class names survive as thin ctor subclasses (src/plugins/tidb-breaker-state.ts +
+ * src/plugins/pg-breaker-state.ts are now re-export shims) so every consumer (store-backend.ts, the
+ * fake-pool unit suites, the real dual-DB integration suite) is untouched.
+ *
+ * core's `createCircuitBreakerBrain` defaults to a per-PROCESS Map → on a multi-replica deployment
+ * every replica re-discovers a provider outage independently (slow fleet-wide reaction). This backs
+ * the breaker with the shared `circuit_breaker` table so a trip on one replica is learned by the others.
+ *
+ * IMPORTANT — `BreakerState.get/set` are **synchronous** (core calls them on the hot path of every
+ * brain invocation; a DB round-trip per call is untenable). So this is a **write-through cache**:
+ *   - `get` / `set` operate on an in-process Map synchronously (so the local breaker is always correct);
+ *   - `set` ALSO fires an async write-through to the shared table (best-effort; a DB hiccup must never
+ *     break the request path — breaker state is advisory);
+ *   - a periodic `refresh()` pulls the shared table back into the cache so this replica learns peers'
+ *     trips. Consistency is therefore **eventual** (a replica may send a few extra requests before it
+ *     learns a peer already opened the breaker — self-healing, never wrong in a dangerous direction).
+ *
+ * Strict per-call linearizable state would need an async `BreakerState` from core (a separate effort);
+ * for a consultative breaker, eventually-consistent write-through is the right trade (see core design/20).
+ *
+ * ── Dialect deltas, kept EXPLICIT (the ONLY place the two engines actually differ) ─────────────────
+ *   - placeholders `?` vs `$n`
+ *   - upsert form: `ON DUPLICATE KEY UPDATE … VALUES(col)` vs `ON CONFLICT (breaker_key) DO UPDATE SET
+ *     … EXCLUDED.col`
+ *   - schema ownership: TiDB DDL lives centrally in tidb-pool.ts; PG DDL is self-contained here
+ *     (`PG_BREAKER_STATE_SCHEMA` / `ensureSchema`, re-exported off pg-breaker-state.ts) — disjoint table,
+ *     so a standalone idempotent apply is safe (no central-schema shadowing), mirroring every other PG store.
+ * Everything else (write-through logic, the pending-guard race fix, refresh/prune, row→snapshot mapping,
+ * opened_at Date handling) is IDENTICAL — the SqlDriver seam (result unwrapping) is what let the row
+ * mapping collapse to one body; both drivers hand back the same `SqlRow` shape.
+ *
+ * Kept in lock-step with the real engines by test/pg-breaker-state-integration.test.ts (runs the SAME
+ * scenarios on BOTH real engines) and the cross-instance concurrency pin in
+ * test/file-stores-cross-instance-concurrency.test.ts (last-writer-wins overwrite semantics — a design
+ * question, not a defect; see that file's comment for the full reasoning).
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient } from "pg";
 import type { BreakerSnapshot, BreakerState } from "@sema-agent/core";
 import { type SqlDriver } 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 declare const PG_BREAKER_STATE_SCHEMA: string[];
+/** Idempotent schema apply for the breaker table (the PG twin of tidb-pool.ts ensureSchema, scoped to this store). */
 export declare function ensureSchema(pool: PgPool | PoolClient): Promise<void>;
+/** Dual-dialect cross-replica BreakerState. See the file header for the dialect-delta ledger. */
 export declare class SqlBreakerState implements BreakerState {
     protected readonly db: SqlDriver;
+    /** LOW (SILENT-FALLBACK P1): write-through failure tap — streak per call, 0 on the recovery edge. */
     private readonly onWriteFail?;
     private cache;
     private 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). */
     private readonly pending;
     private writeFailStreak;
-    constructor(db: SqlDriver, onWriteFail?: ((streak: number) => void) | undefined);
+    constructor(db: SqlDriver, 
+    /** LOW (SILENT-FALLBACK P1): write-through failure tap — streak per call, 0 on the recovery edge. */
+    onWriteFail?: ((streak: number) => void) | undefined);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     get(key: string): BreakerSnapshot | undefined;
     set(key: string, snap: BreakerSnapshot): void;
     private writeThrough;
+    /**
+     * 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).
+     */
     refresh(): Promise<void>;
+    /** Start the periodic refresh loop. `unref` so it never holds the process open. Returns `this`. */
     startRefresh(intervalMs?: number): this;
     stop(): void;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBBreakerState extends SqlBreakerState {
     constructor(pool: MySqlPool, onWriteFail?: (streak: number) => void);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgBreakerState extends SqlBreakerState {
     constructor(pool: PgPool, onWriteFail?: (streak: number) => void);
 }

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

@@ -1,4 +1,7 @@
 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)   NOT NULL,
@@ -9,21 +12,29 @@ 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, onWriteFail) {
+    constructor(db, 
+    /** LOW (SILENT-FALLBACK P1): write-through failure tap — streak per call, 0 on the recovery edge. */
+    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;
     }
@@ -31,9 +42,9 @@ export class SqlBreakerState {
         return this.cache.get(key);
     }
     set(key, snap) {
-        this.cache.set(key, snap);
-        this.pending.add(key);
-        void this.writeThrough(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
     }
     async writeThrough(key, snap) {
         try {
@@ -46,18 +57,41 @@ export class SqlBreakerState {
                 try {
                     this.onWriteFail?.(0);
                 }
-                catch { }
-            }
+                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 {
             try {
                 this.onWriteFail?.(++this.writeFailStreak);
             }
-            catch { }
+            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.
         }
     }
+    /**
+     * 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");
@@ -66,7 +100,7 @@ export class SqlBreakerState {
                 const key = String(r.breaker_key);
                 seen.add(key);
                 if (guarded(key))
-                    continue;
+                    continue; // don't clobber a locally-pending newer value (#5)
                 this.cache.set(key, {
                     phase: r.phase,
                     failures: Number(r.failures),
@@ -78,8 +112,10 @@ 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?.();
@@ -91,11 +127,13 @@ 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);