@sema-agent/server 1.323.0 → 2.0.1

package/dist/plugins/file-snapshot-store-sql.d.ts

@@ -1,37 +1,169 @@
+/**
+ * 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 { type FileSnapshotBounds, type FileSnapshotStore, type FileSnapshotResult, type ExecutionEnv } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type BlobBackend } from "./blob-backend.js";
 import { type SqlDriver } from "./sql-driver.js";
+/** Dual-dialect durable FileSnapshotStore. See the file header for the dialect-delta ledger. */
 export declare class SqlFileSnapshotStore implements FileSnapshotStore {
     protected readonly db: SqlDriver;
+    /** 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`). */
     protected readonly pool: MySqlPool | PgPool;
     protected readonly bounds: FileSnapshotBounds;
+    /** 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.) */
     private readonly inFlight;
+    /** 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. */
     private readonly 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: ((count: number) => void | Promise<void>) | undefined;
-    constructor(db: SqlDriver, pool: MySqlPool | PgPool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
+    constructor(db: SqlDriver, 
+    /** 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: MySqlPool | PgPool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** 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). */
     private putBlobRow;
+    /** 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. */
     putBlob(hash: string, bytes: Uint8Array): Promise<FileSnapshotResult>;
+    /** CREATE-ONCE: an entryId's tree is immutable, so a 2nd snapshot for an existing key is a no-op {ok:true}. */
     snapshot(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
+    /** 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. */
     importManifest(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
+    /** Converge `root` back to the snapshot (applyManifest: PHASE-1 remove symlinks/strays, PHASE-2 write captured). */
     restore(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
     has(scope: string, key: string): Promise<boolean>;
+    /** 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. */
     listKeys(scope: string): Promise<string[]>;
+    /** 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). */
     exportManifest(scope: string, key: string): Promise<Map<string, string> | null>;
+    /** 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). */
     getBlob(hash: string): Promise<Uint8Array | undefined>;
+    /** 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). */
     hasBlobs(hashes: string[]): Promise<Set<string>>;
+    /** workspace 浏览面(#3,[1894]②):per-blob 字节数——读 SQL INDEX 的 byte_len(单 IN 查询;
+     *  MinIO 后端的索引行同带 byte_len,两后端同源)。tree 的 size 投影 + file 面「超限先拒后拉」用。 */
     blobSizes(hashes: string[]): Promise<Map<string, number>>;
+    /** 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). */
     reap(scope: string, keepKeys: string[]): Promise<number>;
+    /** 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. */
     deleteBySession(scope: string): Promise<number>;
+    /** 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). */
     private gcOrphanBlobs;
+    /** 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. */
     sweepOrphanBlobs(): Promise<number>;
+    /** Run statements atomically; rolls back on failure. */
     private tx;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBFileSnapshotStore extends SqlFileSnapshotStore {
     constructor(pool: MySqlPool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgFileSnapshotStore extends SqlFileSnapshotStore {
     constructor(pool: PgPool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
 }

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

@@ -1,27 +1,103 @@
+/**
+ * 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;
-    onSkippedVanished = undefined;
-    constructor(db, pool, blobBackend, bounds = DEFAULT_SNAPSHOT_BOUNDS) {
+    /** [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) {
         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` } };
         }
@@ -30,20 +106,35 @@ 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}`;
+        const flightKey = `${scope}\x00${key}`; // harmonized separator — see file header (not a dialect concern)
         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);
                 });
             }
@@ -52,16 +143,21 @@ 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 { }
+                catch { /* observer must not break the seam */ }
             }
+            // 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;
+                    return; // a concurrent snapshot won — create-once
                 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]);
                 }
@@ -69,39 +165,68 @@ 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 };
+            return { ok: true }; // create-once (mirrors snapshot)
         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())) {
                 let bytes;
                 try {
                     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);
+                await this.putBlobRow(hash, bytes); // the SAME created_at-refreshing upsert snapshot()/putBlob use (no SQL drift)
             }
+            // 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;
+                    return; // a concurrent import/snapshot won — create-once
                 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]);
                 }
@@ -109,13 +234,19 @@ 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)
@@ -131,25 +262,40 @@ 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;
+            return null; // absent (an empty-tree snapshot still has ≥1 row; 0 rows ⇒ no such snapshot)
         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]);
@@ -160,10 +306,24 @@ 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)")
@@ -171,11 +331,16 @@ export class SqlFileSnapshotStore {
         const orphans = rows.map((r) => String(r.blob_hash));
         if (orphans.length === 0)
             return 0;
-        return this.blobs.deleteBlobs(orphans);
+        return this.blobs.deleteBlobs(orphans); // grace-passed subset actually deleted (bounded concurrency inside)
     }
+    /** 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 {
@@ -189,6 +354,7 @@ export class SqlFileSnapshotStore {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -197,11 +363,13 @@ 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/file-workflow-journal-store.d.ts

@@ -1,2 +1,12 @@
+/**
+ * SVC-2 — FILE-backed durable WorkflowJournalStore for the LOCAL (TOC) backend.
+ *
+ * Now a RE-EXPORT of core's copy (the write-here-then-core-adopts 剧本): the implementation was written here for server
+ * 1.89.0, then adopted verbatim by core (`@sema-agent/core` 1.223.0, file
+ * `src/stores/file/workflow-journal-store.ts` — crash-safe per-run JSONL, scope-guarded [CORE-9],
+ * idempotent-per-ordinal, oversize skip-journal, traversal-runId load degrade, 0o600/0o700). One source of
+ * truth in core; the SQL twins (tidb/pg) stay service-side (dialect = deployment glue). The service test
+ * suite (test/file-workflow-journal-store.test.ts) keeps pinning the contract through this re-export.
+ */
 export { FileWorkflowJournalStore } from "@sema-agent/core";
 //# sourceMappingURL=file-workflow-journal-store.d.ts.map

package/dist/plugins/file-workflow-journal-store.js

@@ -1,2 +1,12 @@
+/**
+ * SVC-2 — FILE-backed durable WorkflowJournalStore for the LOCAL (TOC) backend.
+ *
+ * Now a RE-EXPORT of core's copy (the write-here-then-core-adopts 剧本): the implementation was written here for server
+ * 1.89.0, then adopted verbatim by core (`@sema-agent/core` 1.223.0, file
+ * `src/stores/file/workflow-journal-store.ts` — crash-safe per-run JSONL, scope-guarded [CORE-9],
+ * idempotent-per-ordinal, oversize skip-journal, traversal-runId load degrade, 0o600/0o700). One source of
+ * truth in core; the SQL twins (tidb/pg) stay service-side (dialect = deployment glue). The service test
+ * suite (test/file-workflow-journal-store.test.ts) keeps pinning the contract through this re-export.
+ */
 export { FileWorkflowJournalStore } from "@sema-agent/core";
 //# sourceMappingURL=file-workflow-journal-store.js.map