@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/file-snapshot-store-sql.js

@@ -1,103 +1,27 @@
-/**
- * Durable `FileSnapshotStore` (E19 rewind-files) — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场).
- * ONE implementation, TWO dialects; the historical `TiDBFileSnapshotStore` / `PgFileSnapshotStore` class
- * names survive as thin ctor subclasses so every consumer (store-backend.ts, the migration script, the
- * contract/integration/minio-equivalence suites) is untouched.
- *
- * Cross-replica working-tree snapshots keyed by `(scope=sessionId, key=SessionTreeEntry.id)`, the SAME
- * entryId anchor as E18 resume-at. Used for (a) rewind (restore a PAST turn's tree in the same env) and
- * (b) the seamless local↔cloud work-artifact transfer (2c: a snapshot synced to the cloud, restored in the
- * other environment — conversation + files in lockstep).
- *
- * The env-operating + security-critical half (the tree walk + the symlink-neutralizing restore
- * convergence) is core's `captureManifest`/`applyManifest` — REUSED verbatim (re-implementing risks
- * re-introducing the symlink-escape / fail-closed bugs core's dual-review fixed). This store provides ONLY
- * the durable persistence: content-addressed blobs (sha256 → bytes, deduped across all snapshots, via the
- * shared {@link BlobBackend} seam — SQL by default, MinIO when configured) + a per-`(scope,key)` manifest
- * (relPath → blobHash) that stays in SQL either way (`snapshot_manifest`).
- *
- * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
- *   - `?` placeholders vs `$n` on every `snapshot_manifest` statement (exists-check, insert, selects, the
- *     scoped/keyed deletes) — every statement stays written out at the call site via `q()`, never a single
- *     text with a numbering loop.
- *   - result unwrapping (`rows`/`affected`) and transaction control (mysql2 native begin/commit/rollback vs
- *     PG statement form) go through the shared `SqlDriver`/`SqlTxConn` seam (sql-driver.ts) — same
- *     normalization the other A12 collapses use; NOT a store-specific concern.
- *   - the default {@link BlobBackend} (`SqlBlobBackend`) and `blobSizes` (`sqlBlobSizes`) take the RAW pool
- *     + a `"tidb"|"pg"` dialect string directly (blob-backend.ts predates/sits outside this seam — it is a
- *     sibling module, not part of this collapse), so this store keeps BOTH the `SqlDriver` (for its own
- *     `snapshot_manifest` statements) and the raw native pool (to hand to blob-backend.ts unchanged).
- *   - in-flight guard key separator: the TiDB twin used `\x00`, the PG twin used a plain space — NOT a
- *     dialect requirement (this key never leaves the process or touches SQL), just accidental drift.
- *     Harmonized to `\x00` (can't collide with a normal scope/key string) — zero observable behavior change
- *     either way, since the key only dedups concurrent calls on THIS replica within THIS process.
- *   - `gcOrphanBlobs`'s orphan-SET query text is IDENTICAL for both dialects (no placeholders) — kept as one
- *     shared statement, not a `q()` pair.
- */
 import { captureManifest, applyManifest, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
 import { createHash } from "node:crypto";
 import { SqlBlobBackend, sqlBlobSizes } from "./blob-backend.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-/** Dual-dialect durable FileSnapshotStore. See the file header for the dialect-delta ledger. */
 export class SqlFileSnapshotStore {
     db;
     pool;
     bounds;
-    /** In-flight create-once guard (per process) — mirrors InMemoryFileSnapshotStore: a concurrent 2nd
-     *  snapshot/import of the same (scope,key) on THIS replica is a no-op, not a re-capture. CROSS-REPLICA dup
-     *  is HARMLESS here: the key is an immutable SessionTreeEntry.id (one settled turn → one fixed tree), so
-     *  two replicas capture the SAME relPath→hash rows → restore's Map dedups them identically. (A
-     *  snapshot_header(scope,snap_key) claim row would serialize one winner + drop dup rows — a follow-on
-     *  hardening for if same-session-multi-replica ever happens; v1 is single-replica affinity so it doesn't.) */
     inFlight = new Set();
-    /** The content-addressed BYTE store (clay 2026-06-26 object-store offload). DEFAULT = the SqlBlobBackend
-     *  over THIS pool — so a MINIO-unset deployment is byte-identical to before this refactor (the
-     *  `snapshot_blob` table). When MinIO is configured the StoreBackend passes a MinioBlobBackend, moving ONLY
-     *  the heavy bytes off-DB; the MANIFEST (snapshot_manifest) + the orphan-reference computation STAY in SQL. */
     blobs;
-    /** [805]③a/[806]④: core 1.287's captureManifest counts enumerate→read-window vanished files it TOLERATED
-     *  (E19 fix — skipped, not failed). The count rides ONLY the captureManifest return value; without this
-     *  sink it is silently dropped. Optional observer set by main.ts (metrics face) — never throws into the
-     *  seam. codex F8: the type admits an ASYNC sink (`void | Promise<void>`) — the call site swallows a
-     *  rejected promise too (a bare try/catch only caught sync throws, so an async observer's rejection
-     *  surfaced as an unhandledRejection and could pierce the never-throw posture process-wide). */
-    onSkippedVanished = undefined; // explicit initializer: the key must EXIST on the instance (main.ts feature-detects via `in`)
-    constructor(db, 
-    /** The RAW native pool — handed to blob-backend.ts (SqlBlobBackend / sqlBlobSizes), which sits OUTSIDE
-     *  the SqlDriver seam and dialect-switches on its own `"tidb"|"pg"` string. Not used for this class's OWN
-     *  `snapshot_manifest` statements (those go through `db`). */
-    pool, blobBackend, bounds = DEFAULT_SNAPSHOT_BOUNDS) {
+    onSkippedVanished = undefined;
+    constructor(db, pool, blobBackend, bounds = DEFAULT_SNAPSHOT_BOUNDS) {
         this.db = db;
         this.pool = pool;
         this.bounds = bounds;
         this.blobs = blobBackend ?? new SqlBlobBackend(this.db.dialect, this.pool);
     }
-    /** 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;
     }
-    /** THE ONE content-addressed blob write — the SINGLE source `snapshot()`, `importManifest()`, and the
-     *  `putBlob` seam all funnel through (no drift across the three writers). Routes the bytes through the
-     *  BlobBackend (SQL default or MinIO); the SqlBlobBackend's upsert REFRESHES `created_at` even on a dedup
-     *  hit so a re-used/just-written blob is "touched=now" and GC-grace-protected until a manifest row commits
-     *  (closes the delete-in-use race). */
     async putBlobRow(hash, bytes) {
         await this.blobs.putBlob(hash, bytes);
     }
-    /** 2c session-sync PUSH side — upload ONE content-addressed blob to the cloud's snapshot store AHEAD of a
-     *  bundle import (§5 streamed blob negotiation: the local peer PUTs only the blobs the cloud is missing,
-     *  then commits the bundle via importSession, whose getBlob reads the cloud's OWN store). A SERVICE method
-     *  (NOT on core's FileSnapshotStore interface — core was asked, non-blocking; the route feature-detects
-     *  `typeof fs.putBlob`). Reuses {@link putBlobRow} VERBATIM (the SAME created_at-refreshing upsert
-     *  importManifest uses), so a PUT and a concurrent reap can't race: the just-PUT blob's created_at=now
-     *  keeps it inside the GC grace window until the import references it from a manifest. Idempotent
-     *  (content-addressed). The route verifies sha256(bytes)===hash BEFORE this. core 1.142.0 made this a
-     *  fail-closed never-throw seam (Promise<FileSnapshotResult>): a BlobBackend write error (e.g. a
-     *  MinioBlobBackend non-2xx PUT) is caught + encoded as `restore_failed`, NEVER thrown out of the seam. */
     async putBlob(hash, bytes) {
-        // M3(接入审计 2026-07-08):sha256 自校验是契约的【store 级】强制不变量("VERIFIES content-address
-        // integrity … a mismatch → read_failed, nothing stored")——不外包给调用方(HTTP 路由前置校验保留=双保险;
-        // 绕过路由的内部新调用方不再能用错配 hash 污染 content-addressed store)。镜像 core InMemory 参考实现。
         if (createHash("sha256").update(bytes).digest("hex") !== hash) {
             return { ok: false, error: { code: "read_failed", message: `putBlob ${hash} fails content-address integrity — nothing stored` } };
         }
@@ -106,35 +30,20 @@ export class SqlFileSnapshotStore {
             return { ok: true };
         }
         catch (err) {
-            // A WRITE/upload failure. core's FileSnapshotError code enum has no dedicated write code; `restore_failed` is the
-            // code core's OWN File backend uses for a putBlob PERSIST failure (vs `read_failed` = content-address integrity),
-            // so we match it + make the MESSAGE explicit that this is a write/upload failure (finding 19).
             return { ok: false, error: { code: "restore_failed", message: `putBlob ${hash} write/upload failed: ${err.message}` } };
         }
     }
-    /** CREATE-ONCE: an entryId's tree is immutable, so a 2nd snapshot for an existing key is a no-op {ok:true}. */
     async snapshot(scope, key, env, root, signal) {
-        const flightKey = `${scope}\x00${key}`; // harmonized separator — see file header (not a dialect concern)
+        const flightKey = `${scope}\x00${key}`;
         if (this.inFlight.has(flightKey))
             return { ok: true };
         this.inFlight.add(flightKey);
         try {
-            // M4(接入审计):create-once 前置 has() 探针必须在 try 【内】——DB 瞬态错(连接池抖动)曾从这里
-            // reject 逃逸 never-throw seam,击穿 core 引擎的裸 await。
             if (await this.has(scope, key))
                 return { ok: true };
-            // captureManifest walks `root` via the env, hands each file's bytes to putBlob (content-addressed dedup), and
-            // returns relPath→hash. Fail-CLOSED: on an enumerate/read/bound error we DON'T persist a partial manifest.
-            // NEVER-THROW: captureManifest invokes the putBlob callback UN-try/caught, so a throwing BlobBackend (a MinIO
-            // non-2xx PUT / network blip — far likelier than a DB error) would escape this never-throw seam. Wrap the whole
-            // capture: a putBlob/MinIO throw → {ok:false, restore_failed}, the contract every caller (E19 auto-snapshot, the
-            // rewind/2c path) relies on (findings 4/9). The already-PUT distinct blobs are orphans (no manifest references
-            // them) → collected by the async sweepOrphanBlobs reaper.
             let cap;
             try {
                 cap = await captureManifest(env, root, this.bounds, signal, async (hash, bytes) => {
-                    // The shared content-addressed blob write (created_at-refreshing upsert) — so a re-used old blob this in-flight
-                    // snapshot needs is "touched" to now and protected by the GC grace window until its manifest row commits.
                     await this.putBlobRow(hash, bytes);
                 });
             }
@@ -143,21 +52,16 @@ export class SqlFileSnapshotStore {
             }
             if (!cap.ok)
                 return { ok: false, error: cap.error };
-            // Observability tail ([805]③a): surface tolerated-vanished counts (metric sink; observer errors swallowed —
-            // an observer must never break the never-throw snapshot seam).
             if (cap.skippedVanished > 0 && this.onSkippedVanished) {
-                // codex F8: Promise.resolve(...) absorbs an ASYNC sink's rejection (else it's an unhandledRejection);
-                // the outer try still absorbs a SYNC throw. Observer errors never break the never-throw seam either way.
                 try {
                     void Promise.resolve(this.onSkippedVanished(cap.skippedVanished)).catch(() => { });
                 }
-                catch { /* observer must not break the seam */ }
+                catch { }
             }
-            // Persist the manifest atomically (re-check has() under the txn so a concurrent winner isn't duplicated).
             await this.tx(async (conn) => {
                 const exists = await conn.query(this.q("SELECT 1 FROM snapshot_manifest WHERE scope = ? AND snap_key = ? LIMIT 1", "SELECT 1 FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2 LIMIT 1"), [scope, key]);
                 if (exists.rows[0])
-                    return; // a concurrent snapshot won — create-once
+                    return;
                 for (const [relPath, hash] of cap.value) {
                     await conn.query(this.q("INSERT INTO snapshot_manifest (scope, snap_key, rel_path, blob_hash) VALUES (?,?,?,?)", "INSERT INTO snapshot_manifest (scope, snap_key, rel_path, blob_hash) VALUES ($1,$2,$3,$4)"), [scope, key, relPath, hash]);
                 }
@@ -165,49 +69,21 @@ export class SqlFileSnapshotStore {
             return { ok: true };
         }
         catch (err) {
-            // The manifest-persist tx (or has()) raised — encode it (never throw out of the seam), parity with importManifest.
             return { ok: false, error: { code: "restore_failed", message: `snapshot persist failed: ${err.message}` } };
         }
         finally {
             this.inFlight.delete(flightKey);
         }
     }
-    /** 2c session-sync IMPORT side — the inverse of `exportManifest`/`getBlob`: persist a snapshot's content
-     *  (manifest + content-addressed blobs) that was EXPORTED from ANOTHER backend (the local→cloud transfer: a src
-     *  snapshot's manifest+blobs land here as a NEW `(scope,key)`). Unlike `snapshot()` this does NOT walk an env — the
-     *  manifest is given; bytes come from `srcGetBlob(blobHash)`. Mirrors core's InMemory/File `importManifest` fail-closed
-     *  matrix verbatim (core 1.141.0). Reuses snapshot()'s EXACT putBlob (created_at-refreshing upsert, GC-grace-safe)
-     *  + manifest-tx (re-check under txn) patterns.
-     *
-     *  NEVER-throws + FAIL-CLOSED (the matrix core's dual-review fixed, point-named to the durable twins):
-     *   - CREATE-ONCE: an entryId's tree is immutable → an existing OR in-flight `(scope,key)` is a no-op `{ok:true}`.
-     *   - `srcGetBlob` is a CROSS-BACKEND fetch (remote/IPC) that CAN REJECT (timeout/ECONNRESET/query error) — caught and
-     *     encoded as `read_failed`, NEVER thrown out of the seam.
-     *   - a MISSING blob (`bytes===undefined`) → `read_failed`.
-     *   - content-address INTEGRITY: `sha256(bytes) !== hash` → `read_failed` (a 2c transfer can cross net/IPC; a corrupt
-     *     blob stored under a mismatched hash would let a later restore silently write WRONG bytes — verify, don't trust).
-     *   - ANY blob failure → EARLY-RETURN `{ok:false}` and the manifest tx is NEVER run, so `has()` stays false (no
-     *     half-snapshot). The DISTINCT blobs already staged before the failing one are orphans (no manifest references
-     *     them) — their snapshot_blob INDEX rows are reaped (and, under MinIO, the objects deleted) by the async grace-
-     *     window sweepOrphanBlobs reaper; they never make this `(scope,key)` visible. */
     async importManifest(scope, key, manifest, srcGetBlob) {
-        // flightKey 分隔符统一 \x00(与 snapshot 一致;此前 pg 双胞用空格=两方法 in-flight 互斥键空间分裂,
-        // 并发 snapshot/import 同一 (scope,key) 不互斥——create-once tx 兜底故无损坏,但键空间应当同一)。
         const flightKey = `${scope}\x00${key}`;
         if (this.inFlight.has(flightKey))
-            return { ok: true }; // create-once (mirrors snapshot)
+            return { ok: true };
         this.inFlight.add(flightKey);
         try {
-            // M4(接入审计):同 snapshot——create-once 前置 has() 探针在 try 内,DB 瞬态错不逃逸 never-throw seam。
             if (await this.has(scope, key))
                 return { ok: true };
-            // STAGE every DISTINCT blob first (content-addressed: fetch each hash once). Any failure here EARLY-RETURNS before
-            // the manifest tx runs → fail-closed: no manifest row ⇒ has() false ⇒ never a half-snapshot a restore would
-            // silently truncate. Upsert REFRESHES created_at (incl dedup hits) → blobs touched=now, GC-grace-protected.
             for (const hash of new Set(manifest.values())) {
-                // D2(试剂盒揪出,RB-361 同源):路径逃逸型 hash 在任何 fetch **之前**拒,文案逐字同 core
-                // File/InMemory 后端(消费方按文案分支不劈叉);SQL 侧 hash 虽只是字符串键,但 srcGetBlob
-                // 是跨后端回调(2c 传输面可能远端),可疑值不外递。
                 if (hash === "" || hash === "." || hash === ".." || !/^[A-Za-z0-9_.-]+$/.test(hash)) {
                     return { ok: false, error: { code: "read_failed", message: `unsafe blob hash ${JSON.stringify(hash)}` } };
                 }
@@ -216,23 +92,19 @@ export class SqlFileSnapshotStore {
                     bytes = await srcGetBlob(hash);
                 }
                 catch (err) {
-                    // NEVER throw out of the seam — a rejecting cross-backend fetch is `read_failed` (parity with InMemory/File).
                     return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fetch failed: ${err.message}` } };
                 }
                 if (!bytes)
                     return { ok: false, error: { code: "read_failed", message: `missing source blob ${hash}` } };
-                // Content-address integrity — verify ONCE here (the durable backend doesn't blindly trust the transferred bytes).
                 if (createHash("sha256").update(bytes).digest("hex") !== hash) {
                     return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fails content-address integrity` } };
                 }
-                await this.putBlobRow(hash, bytes); // the SAME created_at-refreshing upsert snapshot()/putBlob use (no SQL drift)
+                await this.putBlobRow(hash, bytes);
             }
-            // Commit the manifest atomically ONLY after every distinct blob is staged+verified (re-check has() under the txn so
-            // a concurrent winner isn't duplicated) — the SAME tx pattern as snapshot().
             await this.tx(async (conn) => {
                 const exists = await conn.query(this.q("SELECT 1 FROM snapshot_manifest WHERE scope = ? AND snap_key = ? LIMIT 1", "SELECT 1 FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2 LIMIT 1"), [scope, key]);
                 if (exists.rows[0])
-                    return; // a concurrent import/snapshot won — create-once
+                    return;
                 for (const [relPath, hash] of manifest) {
                     await conn.query(this.q("INSERT INTO snapshot_manifest (scope, snap_key, rel_path, blob_hash) VALUES (?,?,?,?)", "INSERT INTO snapshot_manifest (scope, snap_key, rel_path, blob_hash) VALUES ($1,$2,$3,$4)"), [scope, key, relPath, hash]);
                 }
@@ -240,19 +112,13 @@ export class SqlFileSnapshotStore {
             return { ok: true };
         }
         catch (err) {
-            // A persist (manifest tx) fs/db error must NOT throw out of the never-throw seam either — encode it. `restore_failed`
-            // mirrors core's File backend's outer catch (the manifest-PERSIST failure code, distinct from the fetch-side read_failed).
             return { ok: false, error: { code: "restore_failed", message: `import persist failed: ${err.message}` } };
         }
         finally {
             this.inFlight.delete(flightKey);
         }
     }
-    /** Converge `root` back to the snapshot (applyManifest: PHASE-1 remove symlinks/strays, PHASE-2 write captured). */
     async restore(scope, key, env, root, signal) {
-        // never-throw seam 全覆盖(L5,接入审计):入口 SELECT 也在 try 内——DB 层异常编码为 restore_failed。
-        // applyManifest calls getBlob UN-try/caught; a TRANSIENT MinIO fault THROWS from getBlob (so a restore fails LOUD,
-        // not silently-as-missing — finding 11). The same wrap turns that throw into {ok:false, restore_failed}.
         try {
             const { rows } = await this.db.query(this.q("SELECT rel_path, blob_hash FROM snapshot_manifest WHERE scope = ? AND snap_key = ?", "SELECT rel_path, blob_hash FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2"), [scope, key]);
             if (rows.length === 0)
@@ -268,40 +134,25 @@ export class SqlFileSnapshotStore {
         const { rows } = await this.db.query(this.q("SELECT 1 FROM snapshot_manifest WHERE scope = ? AND snap_key = ? LIMIT 1", "SELECT 1 FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2 LIMIT 1"), [scope, key]);
         return Boolean(rows[0]);
     }
-    /** 2c session-sync: enumerate every snapshot key (entryId) in a scope — the SAME enumeration reap()
-     *  does (`SELECT DISTINCT snap_key`), exposed so 2c can export a session's full set of file snapshots. */
     async listKeys(scope) {
         const { rows } = await this.db.query(this.q("SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = ?", "SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = $1"), [scope]);
         return rows.map((r) => String(r.snap_key));
     }
-    /** 2c session-sync: the manifest (relPath → blobHash) for one snapshot — to EXPORT its content to another
-     *  backend byte-for-byte (paired with getBlob for content-addressed transfer). Reads the STORED manifest rows (never
-     *  re-hashes). 0 rows = no snapshot (a real snapshot always has ≥1 manifest row) → null (parity with InMemory). */
     async exportManifest(scope, key) {
         const { rows } = await this.db.query(this.q("SELECT rel_path, blob_hash FROM snapshot_manifest WHERE scope = ? AND snap_key = ?", "SELECT rel_path, blob_hash FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2"), [scope, key]);
         if (rows.length === 0)
-            return null; // absent (an empty-tree snapshot still has ≥1 row; 0 rows ⇒ no such snapshot)
+            return null;
         return new Map(rows.map((r) => [String(r.rel_path), String(r.blob_hash)]));
     }
-    /** 2c session-sync: the content-addressed bytes for `hash` (undefined if absent) — reads via the BlobBackend
-     *  (SQL default or MinIO, where getBlob also verifies content-address integrity). */
     async getBlob(hash) {
         return this.blobs.getBlob(hash);
     }
-    /** The subset of `hashes` already present in the blob store — reads the SQL INDEX (one IN(...) for BOTH backends),
-     *  so the §10 import blob-presence pre-check is a cheap index probe, NOT N full-object getBlob GETs (finding 12). */
     async hasBlobs(hashes) {
         return this.blobs.hasBlobs(hashes);
     }
-    /** workspace 浏览面(#3,[1894]②):per-blob 字节数——读 SQL INDEX 的 byte_len(单 IN 查询;
-     *  MinIO 后端的索引行同带 byte_len,两后端同源)。tree 的 size 投影 + file 面「超限先拒后拉」用。 */
     async blobSizes(hashes) {
         return sqlBlobSizes(this.db.dialect, this.pool, hashes);
     }
-    /** GC: drop every snapshot in `scope` whose key is NOT in keepKeys. Drops ONLY the SQL manifest rows synchronously —
-     *  the now-unreferenced blobs become ORPHANS (their snapshot_blob INDEX rows survive) and are collected LATER by the
-     *  async sweepOrphanBlobs reaper (NEVER a synchronous external-store delete that could block/fail this reap on a MinIO
-     *  blip — clay 2026-06-26 async-purge design). */
     async reap(scope, keepKeys) {
         return this.tx(async (conn) => {
             const { rows: keys } = await conn.query(this.q("SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = ?", "SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = $1"), [scope]);
@@ -312,24 +163,10 @@ export class SqlFileSnapshotStore {
             return drop.length;
         });
     }
-    /** E21 purge — drop ALL snapshots for a session (every key). Drops ONLY the SQL manifest rows synchronously → the
-     *  session is immediately gone + its blobs become orphans; the actual MinIO/SQL BYTE deletion is the async
-     *  sweepOrphanBlobs reaper's job (bounded-window EVENTUAL CONSISTENCY satisfies the E21 privacy/compliance "really
-     *  delete the bytes" requirement WITHOUT a fragile synchronous object-store delete on the purge path). Scoped by sessionId. */
     async deleteBySession(scope) {
         const { affected } = await this.db.query(this.q("DELETE FROM snapshot_manifest WHERE scope = ?", "DELETE FROM snapshot_manifest WHERE scope = $1"), [scope]);
         return affected;
     }
-    /** Content-addressed blobs are shared across snapshots → GC only those NO manifest references. The orphan-hash SET is
-     *  computed from the `snapshot_blob` INDEX in SQL (reference tracking stays in the DB — works for BOTH the SQL backend
-     *  AND MinIO, whose index rows are kept bytes-NULL); the BlobBackend's deleteBlobs applies the grace window (a just-
-     *  written blob a concurrent in-flight snapshot needs is never delete-in-use) and, for MinIO, deletes the objects.
-     *  Returns the count ACTUALLY deleted (the grace-passed subset deleteBlobs reports — NOT the pre-grace orphan count,
-     *  finding 13). Called ONLY from the async sweepOrphanBlobs reaper (never the synchronous purge path).
-     *
-     *  The orphan-SET query text is IDENTICAL for both dialects (no placeholders) — a single shared statement, not a `q()`
-     *  pair. A query error degrades to "zero orphans this sweep" (both twins already treated it that way — the reaper
-     *  retries next tick, so under-collecting once is harmless; never surfaced as a hard failure). */
     async gcOrphanBlobs() {
         const { rows } = await this.db
             .query("SELECT blob_hash FROM snapshot_blob WHERE blob_hash NOT IN (SELECT blob_hash FROM snapshot_manifest)")
@@ -337,16 +174,11 @@ export class SqlFileSnapshotStore {
         const orphans = rows.map((r) => String(r.blob_hash));
         if (orphans.length === 0)
             return 0;
-        return this.blobs.deleteBlobs(orphans); // grace-passed subset actually deleted (bounded concurrency inside)
+        return this.blobs.deleteBlobs(orphans);
     }
-    /** 2c session-sync DoS bound + the ASYNC byte-GC for reap/deleteBySession orphans — GLOBALLY GC grace-passed
-     *  orphan blobs (standalone PUTs never imported AND the blobs a purge/reap left orphaned). The driver is the main.ts
-     *  reaper (scheduled, error-tolerant: a per-object MinIO delete failure is skipped + retried next sweep → bounded-
-     *  window eventual consistency). Reuses {@link gcOrphanBlobs} VERBATIM; returns the count actually deleted this sweep. */
     async sweepOrphanBlobs() {
         return this.gcOrphanBlobs();
     }
-    /** Run statements atomically; rolls back on failure. */
     async tx(fn) {
         const conn = await this.db.connect();
         try {
@@ -360,7 +192,6 @@ export class SqlFileSnapshotStore {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -369,13 +200,11 @@ export class SqlFileSnapshotStore {
         }
     }
 }
-/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBFileSnapshotStore extends SqlFileSnapshotStore {
     constructor(pool, blobBackend, bounds = DEFAULT_SNAPSHOT_BOUNDS) {
         super(mysqlDriver(pool), pool, blobBackend, bounds);
     }
 }
-/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgFileSnapshotStore extends SqlFileSnapshotStore {
     constructor(pool, blobBackend, bounds = DEFAULT_SNAPSHOT_BOUNDS) {
         super(pgDriver(pool), pool, blobBackend, bounds);

package/dist/plugins/fork-routing-session-store.js

@@ -1,28 +1,3 @@
-/**
- * ForkRoutingSessionStore — the subRunner's session backing after core 1.350's fork 终修([1364]①/[1367]①).
- *
- * 问题形:core 的 `hostSessionFork` 在 HOST runner 的店里 fork,fork 子任务带 `requireExistingSession:true`
- * 在 opts.runner(subRunner)上执行——subRunner 拆店时子任务查不到刚 fork 出的会话,响亮失败
- * `resume.session_not_found`(cli 真机复现)。
- *
- * 但把 host durable 店**整个**给 subRunner(第一版修)被 codex 判两 high:普通子任务(council 镜头/
- * team/子代理)会把每次运行都铸成 committed durable 会话——sweepStagingSessions 只扫**无 session_meta**
- * 的 staging 弃置行,committed 子会话没有 reaper=无界增长;且进 owner 过滤的会话枚举(零 run 的内部
- * 会话污染 /v1/sessions)。
- *
- * 此包装店按**会话的真居所**路由,两边语义都保住:
- *  - `acquire(id, {requireExisting})`(fork 子 + retained-child resume 的形)→ **host 店优先**,miss 落
- *    transient(retained 瞬态子的 resume 仍走私店);两边都 miss=抛 host 侧错误(fail-loud 原语义)。
- *  - `acquire()`(无 id=普通子任务铸新会话)→ **transient**(throwaway 姿势保留:council/team 子会话
- *    不落 durable、不进枚举、TTL 自清)。
- *  - `acquire(id)`(带 id 不 requireExisting)→ 已有路由按路由走;未知 id 落 transient(claim-create
- *    绝不打到 durable 店——那是 authorizer 的职权)。
- *  - `fork(sourceId)` → 源在哪店在哪店 fork(路由未知时 host 先试,null 再 transient);新 id 记路由。
- *  - `list`/`size`/`dispose` = transient 侧(host 店归 main runner 所有;不双列、不双清)。
- *
- * 路由表 LRU 上限 {@link ROUTE_MAX}:满额逐最老(refresh-on-use);被逐后下次 `acquire` 按上述规则重derive
- * (requireExisting 的 host-first 重试仍落对店),中途 touch/noteTaskRun 缺路由=落 transient(no-op 级)。
- */
 import { SessionError } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
 const ROUTE_MAX = 8192;
@@ -30,36 +5,20 @@ export class ForkRoutingSessionStore {
     host;
     transient;
     route = new Map();
-    /** pin 时的店归属——unpin 恒回同店(LRU 逐出不拆对,见 pin/unpin)。 */
     pinnedAt = new Map();
-    /** [1593] 晋升名册(探针 Finding A 修):已 promoteToHost 的 id **永久**钉 host——路由表会被 LRU
-     *  逐出,而私店的 forget 只清 entries 缓存行、底层 repo 行不清且 sweep 扫不到(core session-store.js
-     *  亲读),逐出后 transient-first 的 requireExisting 会把陈旧快照端回给 revive。本集不逐出(上界=
-     *  parked 子代数,天然小);pick/acquire 首查。 */
     promoted = new Set();
-    /** #292 placement 半场:placed id 名册(与 promoted 同姿势——不随路由 LRU 逐出)。placed 会话的
-     *  真居所恒=host(分区在 durable 店),任何形的 acquire/touch/release 都不得落 transient——
-     *  否则 transient 的 claim-create 会铸出同 id 影子会话,requireExisting 的 transient-first 顺序
-     *  会让影子遮蔽真转录(F-7 顺序对 placed 反向成害)。 */
     placed = new Set();
-    /** #292:host 店的 placements 声明透传(声明制——包装层不 duck-type,host 声明了才武装 placed
-     *  路由;host 不声明时本店全行为与 5.47 前逐字节同)。 */
     placements;
-    /** #292:分区枚举透传(host 有才有——恒在的空实现会把「不能枚举」谎报成「没有 placed 会话」)。 */
     listPlaced;
     constructor(host, transient) {
         this.host = host;
         this.transient = transient;
-        // #292 声明/枚举面:host 声明什么透传什么(transient 永不声明 placements——分区住 durable 店)。
         if (host.placements !== undefined)
             this.placements = host.placements;
         const hostListPlaced = host.listPlaced;
         if (typeof hostListPlaced === "function") {
             this.listPlaced = (kind, o) => hostListPlaced.call(host, kind, o);
         }
-        // backlog(hasSessionFork 恒真):两 backing 都无 fork 面时,包装店的 fork 方法**摘除**——core 的
-        // fork 门(hasSessionFork(opts.runner.sessions))才能诚实报 fork.unavailable,而不是放行后折叠成
-        // 误导性的「source not found」。现三 backing 均有 fork,此臂为接入无 fork durable backend 备。
         if (host.fork === undefined && transient.fork === undefined) {
             this.fork = undefined;
         }
@@ -75,16 +34,12 @@ export class ForkRoutingSessionStore {
     }
     pick(id) {
         if (this.promoted.has(id) || this.placed.has(id))
-            return this.host; // 名册优先(路由可被 LRU 逐出,名册不逐;placed 同姿势 #292)
+            return this.host;
         const r = this.route.get(id);
         if (r !== undefined)
-            this.remember(id, r); // refresh recency
+            this.remember(id, r);
         return r === "host" ? this.host : this.transient;
     }
-    /** #292:host 声明分区时的冷缓存判位探针。判据=host `requireExisting` acquire 的 `SessionMetadata.placement`
-     *  (5.48 additive,File/SQL/Ttl 三形都带——比 `placementOf` 面更普适:Ttl 缓存层不透传 placementOf)。
-     *  placed 命中把 acquired 会话一并交回(调用方正需要它时零二次 acquire);非 placed/absent 的探针
-     *  acquire 一律 **forget** 收尾([4743] 义务①:验存在的 acquire 禁 release——release(placed)=真删)。 */
     async hostPlacedProbe(id) {
         if (this.placed.has(id)) {
             const acquired = await this.host.acquire(id, { requireExisting: true });
@@ -97,9 +52,6 @@ export class ForkRoutingSessionStore {
             acquired = await this.host.acquire(id, { requireExisting: true });
         }
         catch (err) {
-            // not_found=常态(绝大多数 id 非 placed),静默折 absent;**真故障**(host 不可达/读错)同样折
-            // absent 但计数留痕(#191 门②:F 类兜底必走 recordFailOpen)——放行的是 transient 腿在 host
-            // 故障窗内保持独立可用,代价与恢复路径见 tag 注册表。
             if (!(err instanceof SessionError && err.code === "not_found")) {
                 recordFailOpen("server.fork-routing.placed-probe-host-error", err instanceof Error ? err.message : String(err));
             }
@@ -110,7 +62,7 @@ export class ForkRoutingSessionStore {
             this.placed.add(id);
             return { state: "placed", acquired };
         }
-        await this.host.forget?.(id); // 只为验居所:丢缓存引用,内容不动(禁 release)
+        await this.host.forget?.(id);
         return { state: "unplaced" };
     }
     async acquire(sessionId, opts) {
@@ -119,9 +71,6 @@ export class ForkRoutingSessionStore {
             this.remember(a.sessionId, "transient");
             return a;
         }
-        // #292 建会话入分区形(受信 spawner:带 placement、不 requireExisting)——分区住 host durable 店;
-        // host 不声明 placements 时按旧行为落 transient(core 铸造门本就不会给这种部署铸 placement,
-        // 这臂只是防御性一致)。
         if (opts?.placement !== undefined && opts.requireExisting !== true && this.placements?.subagent !== undefined) {
             const a = await this.host.acquire(sessionId, opts);
             this.placed.add(sessionId);
@@ -129,8 +78,6 @@ export class ForkRoutingSessionStore {
             return a;
         }
         if (this.promoted.has(sessionId) || this.placed.has(sessionId)) {
-            // [1593] 晋升名册:恒走 host——绝不能让 transient-first 把 forget 后仍活在私店 repo 里的陈旧
-            // 快照端给 revive(探针 Finding A)。placed 名册同规则(#292:影子遮蔽真转录的反向 F-7)。
             const a = await this.host.acquire(sessionId, opts);
             this.remember(sessionId, "host");
             return a;
@@ -142,19 +89,13 @@ export class ForkRoutingSessionStore {
             return a;
         }
         if (opts?.requireExisting) {
-            // PAIR-REVIEW F-7(codex 过审):**transient-first**——retained 瞬态子 resume 直达私店;fork 子恒不在
-            // transient(miss)→ fallback host 命中,语义不变。顺序反转封住 F-7 组合链:同 id 在两店并存时
-            // (child uuid 被同租户误提交到主 API 而 host 店 claim-create 出空壳),真子会话(transient)赢,
-            // 空壳不遮蔽。双 miss 抛 host 侧错误(响亮,fail-closed 到「真不存在」)。
-            // #292 例外:transient 命中且 host 声明分区时,还要过一次 placed 判位——同 id 若在 host 是 placed
-            // 会话,transient 那份是影子(claim-create 铸的),真转录必须赢(F-7 顺序对 placed 反向成害)。
             let transientErr;
             try {
                 const a = await this.transient.acquire(sessionId, opts);
                 if (this.placements?.subagent !== undefined) {
                     const probe = await this.hostPlacedProbe(sessionId);
                     if (probe.state === "placed" && probe.acquired !== undefined) {
-                        await this.transient.forget?.(sessionId); // 影子只丢引用(私店 repo 行本就 sweep 不到,名册是真防线)
+                        await this.transient.forget?.(sessionId);
                         this.remember(sessionId, "host");
                         return probe.acquired;
                     }
@@ -167,8 +108,6 @@ export class ForkRoutingSessionStore {
             }
             try {
                 const a = await this.host.acquire(sessionId, opts);
-                // 顺手:host 端回的会话若带 placement 元组,入名册(后续零探针直达)。只在声明分区的部署上读
-                // (非声明形零行为差),且 meta 读失败不阻断 acquire(名册只是省探针的缓存,不是判定)。
                 if (this.placements?.subagent !== undefined) {
                     try {
                         const meta = await a.session.getMetadata();
@@ -176,8 +115,6 @@ export class ForkRoutingSessionStore {
                             this.placed.add(sessionId);
                     }
                     catch (err) {
-                        // 名册只是省探针的缓存,不是判定——缺一条=该 id 下次多付一次 hostPlacedProbe,正确性零影响;
-                        // 计数留痕(#191 门②)让「meta 一直读失败」的环境病在遥测显形。
                         recordFailOpen("server.fork-routing.placed-roster-meta-unreadable", err instanceof Error ? err.message : String(err));
                     }
                 }
@@ -189,16 +126,13 @@ export class ForkRoutingSessionStore {
                 throw hostErr;
             }
         }
-        // 带 id 但不要求已存在:claim-create 只允许落 transient(durable 店的 claim-create 是 authorizer 的职权)。
-        // #292 claim closure(义务⑥过墙形):id 若已是 host 分区的 placed 会话,claim-create 落 transient 会
-        // 铸同 id 影子——委托给 host claim 形,让其 placement_refused 响亮拒(绝不静默铸影子)。
         if (this.placements?.subagent !== undefined) {
             const probe = await this.hostPlacedProbe(sessionId);
             if (probe.state === "placed") {
-                await this.host.forget?.(sessionId); // 探针引用丢弃(refusal 路径不把会话交出)
-                const a = await this.host.acquire(sessionId, opts); // claim 形打声明店 ⇒ placement_refused(义务⑥)
+                await this.host.forget?.(sessionId);
+                const a = await this.host.acquire(sessionId, opts);
                 this.remember(sessionId, "host");
-                return a; // 不可达(上一行必抛);保留形以防 host 语义演化时静默吞
+                return a;
             }
         }
         const a = await this.transient.acquire(sessionId, opts);
@@ -212,16 +146,11 @@ export class ForkRoutingSessionStore {
         return this.pick(sessionId).release(sessionId);
     }
     forget(sessionId) {
-        // PAIR-REVIEW F-8:forget=显式移除 → 路由项同步清(死 id 不再占 LRU 槽挤活路由);release 保留
-        // 路由(retained 子 resume 会再 acquire,清了只是多付一次 derive)。
         const target = this.pick(sessionId);
         this.route.delete(sessionId);
         return target.forget?.(sessionId);
     }
     pin(sessionId) {
-        // backlog 潜伏钉(pin/unpin 路由不对称):pin 时 refresh 路由近度(remember 已在 pick 内做)+把
-        // pinned id 记入独立集合——unpin 优先按 pin 时的店走,LRU 逐出不再能把 pin/unpin 拆到两家店
-        // (host 店永久 pinned 不可回收的潜伏形就此封死)。
         const r = this.route.get(sessionId);
         if (r !== undefined)
             this.pinnedAt.set(sessionId, r);
@@ -241,23 +170,6 @@ export class ForkRoutingSessionStore {
     list() {
         return this.transient.list?.() ?? Promise.resolve([]);
     }
-    /**
-     * [1593] 子代 park 晋升:把住在 transient(TTL)店的子会话**整树拷贝**进 host durable 店,然后
-     * 让该 id 从此路由到 host——`ensureChildSessionDurable` 的「主动晋升」半场(1.263 的只查不迁形在
-     * 拆店生产形下恒否决 park:子会话从不在 host 店,core 收 veto 即 expire checkpoint + settle failed,
-     * cli 真机 14ms~2s expired 即此)。
-     *
-     * 三步缺一不可:
-     *  1. 拷贝:transient 读整树(getEntries)+ 源 leaf → host 店 acquire(id)(durable 店的 acquire
-     *     缺行即建行)→ storage.appendEntry 逐条 verbatim(重复 id 容忍=幂等续迁:上次晋升半途崩的
-     *     残留行跳过)→ setLeafId(源 leaf)(分支树以源为准,不信 append 推进的 leaf)。
-     *  2. transient.forget(id):`requireExisting` 的 acquire 是 **transient-first**(F-7 裁定)——私店
-     *     副本不移除,revive 会续写进 1h TTL 副本,durable park 名存实亡。
-     *  3. 路由记 host(此后 touch/pin/release 全走 host;pinnedAt 若记着 transient 一并改写,
-     *     unpin 不落错店)。
-     *
-     * 已在 host(路由或真行)⇒ 幂等直返。两店都无此会话 ⇒ 抛(调用方=park veto,诚实 fail-closed)。
-     */
     async promoteToHost(sessionId) {
         if (this.promoted.has(sessionId))
             return;
@@ -270,26 +182,17 @@ export class ForkRoutingSessionStore {
             src = await this.transient.acquire(sessionId, { requireExisting: true });
         }
         catch {
-            // 私店无此会话:可能已在 host(直查确认=幂等),否则如实抛(host 侧错误响亮上浮)
             const probe = await this.host.acquire(sessionId, { requireExisting: true });
-            // #292 preflight 纪律([4743] 义务①):**只为验存在**的 acquire 收尾一律 forget —— host 店的
-            // release 对 placed 会话是真删除(core 5.48 义务 4),用它给一次探活收尾就是拿删除当探针。
             await this.host.forget?.(probe.sessionId);
             this.promoted.add(sessionId);
             this.remember(sessionId, "host");
             return;
         }
-        // ⚠️ 私店源在此**不 release**:TtlSessionStore.release 对非 pinned 会话=整删(F3 教训)——拷贝
-        // 失败时删源=毁掉仍在跑/仍可赎回的子会话。成功路径由下方 forget(纯 entries 移除,无 repo 删)收尾;
-        // 失败路径源原样留活,veto 如实上浮。
         const entries = await src.session.getEntries();
         const leaf = await src.session.getLeafId();
         const dst = await this.host.acquire(sessionId);
         try {
             const storage = dst.session.getStorage();
-            // 探针 Finding B 修:core 各 storage 的 appendEntry 对重复 id **不抛不查**(storage-base 亲读)
-            // ——靠 try/catch 实现幂等是空想,断续晋升会把同 id 双写成脏树(且脏树会被 import-validate 的
-            // 重复 id 门拒)。真幂等 = 先读 dst 现存 id 集,set-diff 后只补缺。
             const existing = new Set((await dst.session.getEntries()).map((e) => e.id));
             for (const entry of entries) {
                 if (existing.has(entry.id))
@@ -302,18 +205,12 @@ export class ForkRoutingSessionStore {
                 throw new Error(`session "${sessionId}" promotion verification failed (leaf mismatch after import)`);
         }
         finally {
-            // #292:晋升写完只需**丢引用**(内容必须留下,那正是晋升的目的)⇒ forget,不是 release
-            // (同上:release 对 placed 会话已是真删除,而这条 finally 连失败路径都会走)。
             await this.host.forget?.(sessionId);
         }
         try {
             await this.transient.forget?.(sessionId);
         }
         catch {
-            // forget 失败不阻断晋升。⚠️ forget 本就只清私店的 entries 缓存行——底层 repo 行不清、sweep 也
-            // 扫不到(探针 Finding A 取证),陈旧快照在私店**永生**;对 revive 的真防线是上面的晋升名册
-            // (promoted 集恒指 host,不随路由 LRU 逐出),forget 只是缩内存的 best-effort。transient.pinned
-            // 可能残留该 id(forget 不清 pin 集)——unpin 已随 pinnedAt 改写落 host,残留仅是空集合项。
         }
         if (this.pinnedAt.get(sessionId) === "transient")
             this.pinnedAt.set(sessionId, "host");
@@ -340,7 +237,7 @@ export class ForkRoutingSessionStore {
         return this.transient.size;
     }
     dispose() {
-        return this.transient.dispose(); // host 店归 main runner 所有,绝不在此清
+        return this.transient.dispose();
     }
 }
 //# sourceMappingURL=fork-routing-session-store.js.map