@sema-agent/server 7.150.0 → 7.152.0

package/dist/stores-sql/file-history-store-sql.js

@@ -1,18 +1,27 @@
 import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, annulProofFailure, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
-import { BlobTooLargeError, SqlBlobIndex } from "./blob-index-sql.js";
+import { BlobTooLargeError, SqlBlobIndex, blobGcCutoffAt, hashBatches } from "./blob-index-sql.js";
 import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
-import { isMissingColumnError, retryOnDeadlock } from "../plugins/sql-errors.js";
+import { isMissingColumnError, retryOnDeadlock, SqlArbitrationLostError } from "../plugins/sql-errors.js";
 import { probedMissingColumnRefusal } from "../plugins/schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
 export const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
-export const FILE_HISTORY_BLOB_KEY_PREFIX = "file-history/";
+export const FILE_HISTORY_BLOB_GRANT_TABLE = "file_history_blob_grant";
+export const FILE_HISTORY_SCOPED_TABLES = [
+    "file_history_boundary_file",
+    "file_history_boundary",
+    "file_history_reaped_entry",
+    "file_history_version",
+    "file_history_tracked",
+    FILE_HISTORY_BLOB_GRANT_TABLE,
+    "file_history_scope",
+];
 const sha256hex = (s) => createHash("sha256").update(s).digest("hex");
 const truthy = (v) => v === true || v === 1 || v === "1";
 class StagedRefGoneError extends Error {
 }
-class ScopeSentinelVanishedError extends Error {
+class ScopeSentinelVanishedError extends SqlArbitrationLostError {
 }
 function reapedEntryRefusal(entryId) {
     return {
@@ -23,14 +32,89 @@ function reapedEntryRefusal(entryId) {
         },
     };
 }
+export class SqlBlobExchange {
+    blobs;
+    constructor(blobs) {
+        this.blobs = blobs;
+    }
+    async put(hash, bytes) {
+        if (sha256hex(bytes) !== hash) {
+            return { ok: false, error: { code: "adopt_failed", message: `blob ${hash}: the bytes do not hash to this address — nothing stored`, permanence: "terminal" } };
+        }
+        try {
+            await this.blobs.put(hash, bytes);
+            return { ok: true };
+        }
+        catch (err) {
+            if (err instanceof BlobTooLargeError)
+                return { ok: false, error: { code: "adopt_failed", message: err.message, permanence: "terminal", blobCap: { wallSource: err.cap.source } } };
+            const f = foldCaughtFailure(err, "sql-blob-exchange.put");
+            return { ok: false, error: { code: "snapshot_failed", message: `blob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
+        }
+    }
+    get(hash) {
+        return this.blobs.get(hash);
+    }
+    has(hashes) {
+        return this.blobs.has([...hashes]);
+    }
+}
+export class SqlBlobLanding {
+    db;
+    exchange;
+    constructor(db, exchange) {
+        this.db = db;
+        this.exchange = exchange;
+    }
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
+    }
+    static ownerKey(landing) {
+        return landing.owner ?? "";
+    }
+    async putAt(landing, hash, bytes) {
+        const stored = await this.exchange.put(hash, bytes);
+        if (!stored.ok)
+            return stored;
+        try {
+            await this.db.query(this.q(`INSERT INTO ${FILE_HISTORY_BLOB_GRANT_TABLE} (scope, landing_owner, blob_hash, granted_at) VALUES (?,?,?,?) ON DUPLICATE KEY UPDATE granted_at = GREATEST(granted_at, VALUES(granted_at))`, `INSERT INTO ${FILE_HISTORY_BLOB_GRANT_TABLE} (scope, landing_owner, blob_hash, granted_at) VALUES ($1,$2,$3,$4) ON CONFLICT (scope, landing_owner, blob_hash) DO UPDATE SET granted_at = GREATEST(${FILE_HISTORY_BLOB_GRANT_TABLE}.granted_at, EXCLUDED.granted_at)`), [landing.sessionId, SqlBlobLanding.ownerKey(landing), hash, new Date()]);
+            return { ok: true };
+        }
+        catch (err) {
+            const f = foldCaughtFailure(err, "sql-blob-landing.putAt");
+            return { ok: false, error: { code: "snapshot_failed", message: `blob ${hash} was stored but its upload grant could not be recorded: ${f.text}`, ...f.fault } };
+        }
+    }
+    async visibleAt(landing, hashes) {
+        const wanted = new Set(hashes);
+        if (wanted.size === 0)
+            return new Set();
+        const candidates = new Set();
+        if (landing.occupied) {
+            const graph = await this.db.query(this.q("SELECT DISTINCT blob_hash FROM file_history_version WHERE scope = ? AND blob_hash IS NOT NULL", "SELECT DISTINCT blob_hash FROM file_history_version WHERE scope = $1 AND blob_hash IS NOT NULL"), [landing.sessionId]);
+            for (const r of graph.rows) {
+                const h = String(r.blob_hash);
+                if (wanted.has(h))
+                    candidates.add(h);
+            }
+        }
+        const ungranted = [...wanted].filter((h) => !candidates.has(h));
+        for (const batch of hashBatches(ungranted)) {
+            const ph = batch.map((_, i) => (this.db.dialect === "mysql" ? "?" : `$${i + 3}`)).join(",");
+            const granted = await this.db.query(this.q(`SELECT blob_hash FROM ${FILE_HISTORY_BLOB_GRANT_TABLE} WHERE scope = ? AND landing_owner = ? AND blob_hash IN (${ph})`, `SELECT blob_hash FROM ${FILE_HISTORY_BLOB_GRANT_TABLE} WHERE scope = $1 AND landing_owner = $2 AND blob_hash IN (${ph})`), [landing.sessionId, SqlBlobLanding.ownerKey(landing), ...batch]);
+            for (const r of granted.rows)
+                candidates.add(String(r.blob_hash));
+        }
+        if (candidates.size === 0)
+            return new Set();
+        return this.exchange.has([...candidates]);
+    }
+}
 export class SqlFileHistoryStore {
     db;
     pool;
-    blobExchange = {
-        put: (hash, bytes) => this.putExchangedBlob(hash, bytes),
-        get: (hash) => this.blobs.get(hash),
-        has: (hashes) => this.blobs.has([...hashes]),
-    };
+    blobExchange;
+    blobLanding;
     blobs;
     spentAttempts = new Set();
     activeAttempts = new Set();
@@ -44,6 +128,8 @@ export class SqlFileHistoryStore {
             ...(opts?.blobSqlMaxBytes !== undefined ? { maxBytes: opts.blobSqlMaxBytes } : {}),
             ...(opts?.log !== undefined ? { log: opts.log } : {}),
         });
+        this.blobExchange = new SqlBlobExchange(this.blobs);
+        this.blobLanding = new SqlBlobLanding(this.db, this.blobExchange);
         this.boundaryKeep = resolveFileHistoryRetention(this.db.dialect === "mysql" ? "TiDBFileHistoryStore" : "PgFileHistoryStore", opts?.retention);
     }
     q(mysql, pg) {
@@ -67,14 +153,17 @@ export class SqlFileHistoryStore {
                 await conn.begin();
             }
             restart = true;
-            for (const scope of ordered) {
-                await conn.query(this.q("INSERT INTO file_history_scope (scope, created_at_ms) VALUES (?,?) ON DUPLICATE KEY UPDATE scope = scope", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
-                const r = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
-                if (!r.rows[0])
-                    throw new ScopeSentinelVanishedError(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
-            }
+            await this.lockScopeOn(conn, ordered);
         }, (err) => err instanceof ScopeSentinelVanishedError);
     }
+    async lockScopeOn(conn, scopes) {
+        for (const scope of [...new Set(scopes)].sort()) {
+            await conn.query(this.q("INSERT INTO file_history_scope (scope, created_at_ms) VALUES (?,?) ON DUPLICATE KEY UPDATE scope = scope", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
+            const r = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
+            if (!r.rows[0])
+                throw new ScopeSentinelVanishedError(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
+        }
+    }
     async markObserved(scope, keyHash) {
         const r = await this.db.query(this.q("UPDATE file_history_tracked SET observed_later = 1 WHERE scope = ? AND key_hash = ? AND observed_later = 0", "UPDATE file_history_tracked SET observed_later = TRUE WHERE scope = $1 AND key_hash = $2 AND observed_later = FALSE"), [scope, keyHash]);
         return r.affected;
@@ -134,7 +223,7 @@ export class SqlFileHistoryStore {
             return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} kept racing a concurrent retraction — retry` } };
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.trackEdit");
             return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${f.text}`, ...f.fault } };
         }
     }
@@ -201,7 +290,7 @@ export class SqlFileHistoryStore {
             return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} was replaced while this retraction was being proven` } };
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.annulTrack");
             return { ok: false, error: { code: "track_failed", message: `annulling the first-touch record for ${absPath} failed: ${f.text}`, ...f.fault } };
         }
     }
@@ -309,7 +398,7 @@ export class SqlFileHistoryStore {
             }
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.snapshot");
             return { ok: false, error: { code: "snapshot_failed", message: f.text, ...f.fault } };
         }
         this.activeAttempts.add(lease);
@@ -412,7 +501,7 @@ export class SqlFileHistoryStore {
             catch (err) {
                 await conn.rollback().catch(() => undefined);
                 this.spentAttempts.add(lease);
-                const f = foldCaughtFailure(err);
+                const f = foldCaughtFailure(err, "sql-file-history-store.snapshot");
                 return { ok: false, error: { code: "snapshot_failed", message: `boundary for entry "${entryId}" could not be committed: ${f.text}`, ...f.fault } };
             }
             finally {
@@ -423,7 +512,7 @@ export class SqlFileHistoryStore {
         }
         catch (err) {
             this.spentAttempts.add(lease);
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.snapshot");
             return { ok: false, error: { code: "snapshot_failed", message: f.text, ...f.fault } };
         }
         finally {
@@ -491,7 +580,7 @@ export class SqlFileHistoryStore {
                     });
                 }
                 catch (err) {
-                    applied = { outcome: "failed", reason: foldCaughtFailure(err).text };
+                    applied = { outcome: "failed", reason: foldCaughtFailure(err, "sql-file-history-store.restore").text };
                 }
                 if (applied.outcome === "applied")
                     ledger.filesChanged.push(t.trackKey);
@@ -508,7 +597,7 @@ export class SqlFileHistoryStore {
         }
         catch (err) {
             const touched = empty.filesChanged.length > 0 || empty.identicalSkipped.length > 0 || empty.refused.length > 0 || empty.failed.length > 0;
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.restore");
             return { outcome: touched ? "partial" : "failed", ...empty, error: { code: "restore_failed", message: f.text, ...f.fault } };
         }
     }
@@ -578,11 +667,7 @@ export class SqlFileHistoryStore {
         try {
             await conn.begin();
             await this.lockScope(conn, scope);
-            let total = 0;
-            for (const table of ["file_history_boundary_file", "file_history_boundary", "file_history_reaped_entry", "file_history_version", "file_history_tracked", "file_history_scope"]) {
-                const r = await conn.query(this.q(`DELETE FROM ${table} WHERE scope = ?`, `DELETE FROM ${table} WHERE scope = $1`), [scope]);
-                total += r.affected;
-            }
+            const total = await this.deleteScopeRowsOn(conn, scope, FILE_HISTORY_SCOPED_TABLES);
             await conn.commit();
             return total;
         }
@@ -594,27 +679,25 @@ export class SqlFileHistoryStore {
             conn.release();
         }
     }
-    async sweepOrphanBlobs() {
-        const { rows } = await this.db.query("SELECT blob_hash FROM file_history_blob WHERE blob_hash NOT IN (SELECT blob_hash FROM file_history_version WHERE blob_hash IS NOT NULL)");
-        const orphans = rows.map((r) => String(r.blob_hash));
-        if (orphans.length === 0)
-            return 0;
-        return this.blobs.sweep(orphans);
+    async deleteScopeOn(conn, scope) {
+        await this.lockScopeOn(conn, [scope]);
+        return this.deleteScopeRowsOn(conn, scope, FILE_HISTORY_SCOPED_TABLES);
     }
-    async putExchangedBlob(hash, bytes) {
-        if (sha256hex(bytes) !== hash) {
-            return { ok: false, error: { code: "adopt_failed", message: `blob ${hash}: the bytes do not hash to this address — nothing stored`, permanence: "terminal" } };
-        }
-        try {
-            await this.blobs.put(hash, bytes);
-            return { ok: true };
-        }
-        catch (err) {
-            if (err instanceof BlobTooLargeError)
-                return { ok: false, error: { code: "adopt_failed", message: err.message, permanence: "terminal", blobCap: { wallSource: err.cap.source } } };
-            const f = foldCaughtFailure(err);
-            return { ok: false, error: { code: "snapshot_failed", message: `blob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
+    async deleteScopeRowsOn(conn, scope, tables) {
+        let total = 0;
+        for (const table of tables) {
+            const r = await conn.query(this.q(`DELETE FROM ${table} WHERE scope = ?`, `DELETE FROM ${table} WHERE scope = $1`), [scope]);
+            total += r.affected;
         }
+        return total;
+    }
+    async sweepOrphanBlobs() {
+        const cutoff = blobGcCutoffAt(Date.now());
+        return this.blobs.sweep(async () => {
+            await this.db.query(this.q(`DELETE FROM ${FILE_HISTORY_BLOB_GRANT_TABLE} WHERE granted_at < ?`, `DELETE FROM ${FILE_HISTORY_BLOB_GRANT_TABLE} WHERE granted_at < $1`), [cutoff]);
+            const { rows } = await this.db.query(`SELECT blob_hash FROM ${FILE_HISTORY_BLOB_TABLE} WHERE blob_hash NOT IN (SELECT blob_hash FROM file_history_version WHERE blob_hash IS NOT NULL) AND blob_hash NOT IN (SELECT blob_hash FROM ${FILE_HISTORY_BLOB_GRANT_TABLE})`);
+            return rows.map((r) => String(r.blob_hash));
+        }, cutoff);
     }
     async adoptScope(fromScope, toScope) {
         try {
@@ -650,7 +733,7 @@ export class SqlFileHistoryStore {
             }
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.adoptScope");
             return { ok: false, error: { code: "adopt_failed", message: `adoptScope failed: ${f.text}`, ...f.fault } };
         }
     }
@@ -707,10 +790,10 @@ export class SqlFileHistoryStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            await this.lockScope(conn, scope);
-            const out = await this.exportOf(conn, scope, true);
+            const held = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
+            const history = held.rows[0] === undefined ? null : await this.exportOf(conn, scope, true);
             await conn.commit();
-            return { ok: true, history: out };
+            return { ok: true, history };
         }
         catch (err) {
             await conn.rollback().catch(() => undefined);
@@ -732,7 +815,7 @@ export class SqlFileHistoryStore {
                 bytes = await srcGetBlob(hash);
             }
             catch (err) {
-                const f = foldCaughtFailure(err);
+                const f = foldCaughtFailure(err, "sql-file-history-store.verifySourceBlobs");
                 return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${f.text}`, ...f.fault } };
             }
             if (bytes === undefined)
@@ -745,6 +828,40 @@ export class SqlFileHistoryStore {
         return { ok: true };
     }
     async importHistory(scope, data, srcGetBlob) {
+        const plan = await this.prepareImport(scope, data, srcGetBlob, { replace: false });
+        if (!plan.ok)
+            return plan;
+        if (plan.mode === "same")
+            return { ok: true };
+        try {
+            const conn = await this.db.connect();
+            try {
+                await conn.begin();
+                await this.lockScope(conn, scope);
+                const out = await this.publishImportLockedOn(conn, scope, data, { replace: false });
+                if (out.ok)
+                    await conn.commit();
+                else
+                    await conn.rollback();
+                return out;
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+        }
+        catch (err) {
+            return { ok: false, error: this.importFailureOf(err) };
+        }
+    }
+    importFailureOf(err) {
+        const f = foldCaughtFailure(err, "sql-file-history-store.importHistory");
+        return { code: "adopt_failed", message: `importHistory failed: ${f.text}`, ...f.fault };
+    }
+    async prepareImport(scope, data, srcGetBlob, opts) {
         try {
             const shaped = validateFileHistoryExport(data);
             if (!shaped.ok)
@@ -762,59 +879,51 @@ export class SqlFileHistoryStore {
                 return exported;
             const existing = exported.history;
             const sameGraph = existing !== null && fileHistoryExportDigest(existing) === fileHistoryExportDigest(data);
-            if (existing !== null && !sameGraph) {
+            if (existing !== null && !sameGraph && !opts.replace) {
                 return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" already holds a DIFFERENT history — a first import requires an empty target and a retry is legal only for the identical envelope (atomic visibility prevents half-graphs; this law prevents publishing the wrong complete graph over locally-grown history)` } };
             }
             const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.put(hash, bytes));
             if (!verified.ok)
                 return verified;
-            if (sameGraph)
-                return { ok: true };
-            const conn = await this.db.connect();
-            try {
-                await conn.begin();
-                await this.lockScope(conn, scope);
-                if (!(await this.scopeEmpty(conn, scope, true))) {
-                    const now = await this.exportOf(conn, scope, true);
-                    if (now !== null && fileHistoryExportDigest(now) === fileHistoryExportDigest(data)) {
-                        await conn.commit();
-                        return { ok: true };
-                    }
-                    await conn.rollback();
-                    return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" gained a DIFFERENT history while this import was fetching blobs — nothing was published` } };
-                }
-                const now = Date.now();
-                for (const t of data.tracked) {
-                    const keyHash = sha256hex(t.relOrAbsPath);
-                    await conn.query(this.q("INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES (?,?,?,?,?,?,0,?)", "INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES ($1,$2,$3,$4,$5,$6,FALSE,$7)"), [scope, keyHash, t.relOrAbsPath, t.keyKind, t.keyFamily, this.bool(t.baseAvailable), now]);
-                    for (const v of t.versions) {
-                        await conn.query(this.q("INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES (?,?,?,?,?,?,?)", "INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [scope, keyHash, v.version, v.blobHash, v.mode ?? null, v.parentIdent ?? null, v.backupTime]);
-                    }
-                }
-                const seqBase = await conn.query(this.q("SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = ?", "SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = $1"), [scope]);
-                let publishSeq = Number(seqBase.rows[0].s);
-                for (const b of data.boundaries) {
-                    publishSeq += 1;
-                    await conn.query(this.q("INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, now, publishSeq]);
-                    for (const f of b.files) {
-                        await conn.query(this.q("INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, sha256hex(f.relOrAbsPath), f.version]);
-                    }
-                }
-                await conn.commit();
+            return { ok: true, mode: sameGraph ? "same" : "publish" };
+        }
+        catch (err) {
+            return { ok: false, error: this.importFailureOf(err) };
+        }
+    }
+    async publishImportOn(conn, scope, data, plan, opts) {
+        if (plan.mode === "same")
+            return { ok: true };
+        await this.lockScopeOn(conn, [scope]);
+        return this.publishImportLockedOn(conn, scope, data, opts);
+    }
+    async publishImportLockedOn(conn, scope, data, opts) {
+        if (!(await this.scopeEmpty(conn, scope, true))) {
+            const held = await this.exportOf(conn, scope, true);
+            if (held !== null && fileHistoryExportDigest(held) === fileHistoryExportDigest(data))
                 return { ok: true };
-            }
-            catch (err) {
-                await conn.rollback().catch(() => undefined);
-                throw err;
-            }
-            finally {
-                conn.release();
+            if (!opts.replace)
+                return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" gained a DIFFERENT history while this import was fetching blobs — nothing was published` } };
+            await this.deleteScopeRowsOn(conn, scope, FILE_HISTORY_SCOPED_TABLES.filter((t) => t !== "file_history_scope"));
+        }
+        const now = Date.now();
+        for (const t of data.tracked) {
+            const keyHash = sha256hex(t.relOrAbsPath);
+            await conn.query(this.q("INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES (?,?,?,?,?,?,0,?)", "INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES ($1,$2,$3,$4,$5,$6,FALSE,$7)"), [scope, keyHash, t.relOrAbsPath, t.keyKind, t.keyFamily, this.bool(t.baseAvailable), now]);
+            for (const v of t.versions) {
+                await conn.query(this.q("INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES (?,?,?,?,?,?,?)", "INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [scope, keyHash, v.version, v.blobHash, v.mode ?? null, v.parentIdent ?? null, v.backupTime]);
             }
         }
-        catch (err) {
-            const f = foldCaughtFailure(err);
-            return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${f.text}`, ...f.fault } };
+        const seqBase = await conn.query(this.q("SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = ?", "SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = $1"), [scope]);
+        let publishSeq = Number(seqBase.rows[0].s);
+        for (const b of data.boundaries) {
+            publishSeq += 1;
+            await conn.query(this.q("INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, now, publishSeq]);
+            for (const f of b.files) {
+                await conn.query(this.q("INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, sha256hex(f.relOrAbsPath), f.version]);
+            }
         }
+        return { ok: true };
     }
 }
 export class TiDBFileHistoryStore extends SqlFileHistoryStore {
@@ -836,6 +945,7 @@ export async function assertFileHistorySchema(query, dialect) {
         ["file_history_scope", "SELECT scope, created_at_ms FROM file_history_scope WHERE 1=0"],
         ["file_history_reaped_entry", "SELECT scope, entry_id, reaped_at_ms FROM file_history_reaped_entry WHERE 1=0"],
         [FILE_HISTORY_BLOB_TABLE, `SELECT blob_hash, byte_len, bytes, created_at FROM ${FILE_HISTORY_BLOB_TABLE} WHERE 1=0`],
+        [FILE_HISTORY_BLOB_GRANT_TABLE, `SELECT scope, landing_owner, blob_hash, granted_at FROM ${FILE_HISTORY_BLOB_GRANT_TABLE} WHERE 1=0`],
     ];
     for (const [table, sql] of probes) {
         try {

package/dist/stores-sql/pg-session-storage.d.ts

@@ -2,9 +2,9 @@ import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type Ses
 import type { Pool, PoolClient } from "pg";
 import { WindowedSessionStorage } from "./windowed-session-storage.js";
 import { type PlacementAcquireOpts } from "../plugins/session-placement.js";
-import { type StagingHandle } from "../session-sync-kernel.js";
+import { type EntriesStreamOptions, type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type RegisterReceipt, type WithdrawOutcome } from "../session-incarnation.js";
+import { type RegisterReceipt, type SessionFace, type WithdrawOutcome } from "../session-incarnation.js";
 import type { SessionWriteHooks } from "./session-write-hooks.js";
 import { type IndexSpec } from "../plugins/ensure-index.js";
 import { type SessionDeleteCondition } from "./tidb-session-store.js";
@@ -78,7 +78,7 @@ export declare class PgSessionStore implements SessionStore {
     /** Idempotently create a session_meta row with an owner (core `SessionStore.register`). Existing owner is never overwritten. */
     register(sessionId: string, owner: string | null): Promise<void>;
     /** 出生回执面(TiDB 孪生 {@link TiDBSessionStore.registerWithReceipt} 同义:候选 = 这一次 INSERT 入参里铸的化身)。 */
-    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: string): Promise<RegisterReceipt>;
     /** 条件删除(TiDB 孪生 {@link TiDBSessionStore.deleteSessionIf} 同义)。 */
     deleteSessionIf(sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
     /** acquire 的建行(唯一一处;placed 会话的属主 = `placement.owner` 原样,core 7.62.0 [ref] 盒义务 7 —— TiDB 孪生同名方法同注)。 */
@@ -86,6 +86,8 @@ export declare class PgSessionStore implements SessionStore {
     /** The one session_meta INSERT. Existing owner is never overwritten.
      *  [ref]:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
     private insertMeta;
+    /** {@link insertMeta} 那一句,发在给定的连接上(带种类的登记在自己的事务连接上发)。 */
+    private insertMetaOn;
     /** [ref] 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
     /** [ref] 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
@@ -128,10 +130,7 @@ export declare class PgSessionStore implements SessionStore {
      *  held connection across the stream → a slow consumer can't pin one). Start cursor = afterSeq ?? -1 (0-based dense).
      *  Resolves to null (NOT an empty iterable) for a missing session — eager `session_meta` probe (BIGINT seq comes
      *  back as a STRING in node-pg → always Number(...) the cursor advance). */
-    exportEntriesStream(sessionId: string, opts?: {
-        afterSeq?: number;
-        batchSize?: number;
-    }): Promise<AsyncIterable<SessionTreeEntry> | null>;
+    exportEntriesStream(sessionId: string, opts: EntriesStreamOptions): Promise<AsyncIterable<SessionTreeEntry> | null>;
     /** @see TiDBSessionStore.importEntries — 2c session-sync IMPORT: core `validateEntriesForImport` gate FIRST (fail-closed),
      *  then persist its verbatim output (re-seq dense from 0, ids/parents/payload/ts unchanged) in ONE txn, **lock-or-create, meta first**
      *  (占行 → 锁行判是不是本次占下的 → 部署的事务内钩 `import` → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
@@ -160,4 +159,32 @@ export declare class PgSessionStore implements SessionStore {
     get size(): number;
     dispose(): void;
 }
+/**
+ * 2c session-sync P1d-β — the PG twin of {@link TiDBStagingHandle} (behaviourally identical; only the SQL dialect
+ * differs: `$n` placeholders, `$n::jsonb`, `ON CONFLICT (session_id, entry_id) DO NOTHING`, rowCount, FOR UPDATE,
+ * BEGIN/COMMIT handle). Streams entry batches into a shadow session_event partition, then atomically RENAMEs them
+ * onto the real session id in ONE txn; session_meta is locked (or claimed, for a fresh push) first and settled last, COMMIT = the commit point.
+ */
+/** 暂存句柄(会话同步的推送腿逐批写、提交、撤销;由本店的 `stageImport` 交出)。导出只为组合座给它封口(店边界)。 */
+export declare class PgStagingHandle implements StagingHandle {
+    private readonly pool;
+    private readonly hooks;
+    readonly realSessionId: string;
+    readonly stagingId: string;
+    private nextSeq;
+    private readonly seen;
+    constructor(pool: Pool, hooks: SessionWriteHooks, realSessionId: string, stagingId: string);
+    /** @see TiDBStagingHandle.appendBatch — DENSE re-seq (skip already-staged ids), idempotent ON CONFLICT (session_id,
+     *  entry_id) DO NOTHING, one txn/batch. */
+    appendBatch(entries: SessionTreeEntry[]): Promise<void>;
+    /** @see TiDBStagingHandle.commit — the atomic swap: owner CAS first (lock / claim the session_meta row) → in-commit re-classify (FOR UPDATE)
+     *  → purge dst → rename staging→real → settle session_meta. Throws StagedCommitOccupantChangedError when the owner cell is not the judged one,
+     *  SyncConflictError on an unconsented fork/stale flip. */
+    commit(owner: string | null, opts: StagedCommitOptions): Promise<{
+        relation: SyncRelation["relation"];
+        face: SessionFace;
+    }>;
+    /** @see TiDBStagingHandle.abort — DELETE the staging rows. Idempotent. */
+    abort(): Promise<void>;
+}
 //# sourceMappingURL=pg-session-storage.d.ts.map