@sema-agent/server 7.149.0 → 7.151.0

package/dist/stores-sql/checkpoint-store-sql.js

@@ -1,9 +1,9 @@
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
 import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, checkpointSweepAfterSql, hostSessionOf, judgeCheckpointIndexCells } from "../plugins/checkpoint-index-columns.js";
-import { CheckpointError, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
+import { CheckpointError, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, readCheckpointSessionQuery, selectSessionPage, } from "@sema-agent/core";
 import { parkRowFacts, skillCardFacts } from "../approval-card.js";
-import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
+import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, isJsonObject, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "../plugins/sql-driver.js";
@@ -242,6 +242,12 @@ export function readPendingSteerQueueColumn(queueRaw) {
 }
 const STEER_CAS_ATTEMPTS = 8;
 const EXECUTION_RECORD_CAS_ATTEMPTS = 8;
+const STORED_ROW_DAMAGE = {
+    body: "its stored body is not a checkpoint object",
+    decision: "its stored decision record cannot be read",
+    execution: "its stored execution record cannot be read",
+    filing: "its stored body does not name the session the row is filed under",
+};
 export class SqlCheckpointStore {
     db;
     logger;
@@ -337,21 +343,62 @@ export class SqlCheckpointStore {
             throw rowTooLargeOrSelf(this.db.dialect, e, `the checkpoint row for session ${JSON.stringify(cp.sessionId)}`);
         }
     }
+    storedCheckpointColumns() {
+        const d = this.db.dialect;
+        return (`status, ${jsonColumnText(d, "checkpoint")}, ${jsonColumnText(d, "outcome")}, reopen_reason, rev, ` +
+            `${jsonColumnText(d, "pending_steer_queue")}, ${jsonColumnText(d, "execution_outcome")}, execution_at_ms`);
+    }
     async get(token) {
-        const { rows } = await this.db.query(this.q(`SELECT status, ${jsonColumnText("mysql", "checkpoint")}, ${jsonColumnText("mysql", "outcome")}, reopen_reason, rev, ` +
-            `${jsonColumnText("mysql", "pending_steer_queue")}, ${jsonColumnText("mysql", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = ?`, `SELECT status, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnText("pg", "outcome")}, reopen_reason, rev, ` +
-            `${jsonColumnText("pg", "pending_steer_queue")}, ${jsonColumnText("pg", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = $1`), [token]);
+        const { rows } = await this.db.query(`SELECT ${this.storedCheckpointColumns()} FROM checkpoint WHERE token = ${this.ph(1)}`, [token]);
         const r = rows[0];
         if (!r)
             return null;
-        const cp = readCheckpointBodyOrRefuse(r.checkpoint, `for token ${tokenFingerprint(token)}`);
+        const read = this.readStoredCheckpoint(r, token);
+        if (read.kind === "damaged")
+            throw read.error;
+        const cp = read.checkpoint;
+        this.logger?.info?.("checkpoint_get", {
+            tokenFp: tokenFingerprint(token),
+            status: cp.status,
+            hasWorkspaceHandle: !!cp.state?.workspaceHandle,
+            snapshotId: cp.state?.workspaceHandle?.snapshotId,
+        });
+        return cp;
+    }
+    readStoredCheckpoint(r, token) {
+        const where = `for token ${tokenFingerprint(token)}`;
+        let cp;
+        try {
+            cp = readCheckpointBodyOrRefuse(r.checkpoint, where);
+        }
+        catch (e) {
+            if (e instanceof StoreCorruptError)
+                return { kind: "damaged", member: "body", error: e };
+            throw e;
+        }
         cp.status = r.status;
-        const outcomeRaw = refusing("a decision record nobody can read", () => decodeOutcomeColumn(r.outcome, `for token ${tokenFingerprint(token)}`));
+        let outcomeRaw;
+        try {
+            outcomeRaw = refusing("a decision record nobody can read", () => decodeOutcomeColumn(r.outcome, where));
+        }
+        catch (e) {
+            if (e instanceof StoreCorruptError)
+                return { kind: "damaged", member: "decision", error: e, body: cp };
+            throw e;
+        }
         if (outcomeRaw)
             cp.resolvedOutcome = winnerFromOutcome(outcomeRaw);
         cp.reopenReason = r.reopen_reason ?? undefined;
         cp.rev = r.rev == null ? 0 : Number(r.rev);
-        const executionOutcome = refusing("an execution record nobody can read", () => decodeExecutionOutcomeColumn(r.execution_outcome, `for token ${tokenFingerprint(token)}`));
+        let executionOutcome;
+        try {
+            executionOutcome = refusing("an execution record nobody can read", () => decodeExecutionOutcomeColumn(r.execution_outcome, where));
+        }
+        catch (e) {
+            if (e instanceof StoreCorruptError)
+                return { kind: "damaged", member: "execution", error: e, body: cp };
+            throw e;
+        }
         if (executionOutcome !== undefined) {
             cp.executionOutcome = executionOutcome;
             if (r.execution_at_ms != null)
@@ -362,17 +409,58 @@ export class SqlCheckpointStore {
             recordFailOpen("server.sql-json.checkpoint.pending-steer-queue-lossy");
             this.logger?.info?.("checkpoint_pending_steer_unreadable", { tokenFp: tokenFingerprint(token) });
         }
-        if (cp.state) {
-            if (steer.state.pendingSteerQueue !== undefined)
-                cp.state.pendingSteerQueue = steer.state.pendingSteerQueue;
-        }
-        this.logger?.info?.("checkpoint_get", {
-            tokenFp: tokenFingerprint(token),
-            status: cp.status,
-            hasWorkspaceHandle: !!cp.state?.workspaceHandle,
-            snapshotId: cp.state?.workspaceHandle?.snapshotId,
+        if (isJsonObject(cp.state) && steer.state.pendingSteerQueue !== undefined)
+            cp.state.pendingSteerQueue = steer.state.pendingSteerQueue;
+        return { kind: "row", checkpoint: cp };
+    }
+    async listBySession(query) {
+        const read = readCheckpointSessionQuery(query);
+        const { rows } = await this.db.query(`SELECT token, scope, session_id, created_at_ms, ${this.storedCheckpointColumns()} FROM checkpoint WHERE session_id = ${this.ph(1)}`, [read.sessionId]);
+        const tokens = rows.map((r) => String(r.token));
+        const withoutTokens = (sentence) => tokens.reduce((out, t) => withoutCheckpointToken(out, t), sentence);
+        const damaged = new Map();
+        const candidates = [];
+        rows.forEach((r, i) => {
+            const token = tokens[i];
+            const got = this.readStoredCheckpoint(r, token);
+            const body = got.kind === "row" ? got.checkpoint : got.member === "body" ? undefined : got.body;
+            const filedHere = body !== undefined && body.sessionId === String(r.session_id);
+            if (got.kind === "row" && filedHere) {
+                candidates.push([token, body]);
+                return;
+            }
+            damaged.set(token, { problem: STORED_ROW_DAMAGE[got.kind === "damaged" ? got.member : "filing"], r, counted: filedHere });
+            if (filedHere) {
+                candidates.push([token, body]);
+                return;
+            }
+            const filing = { token: token, sessionId: String(r.session_id), scope: String(r.scope), status: String(r.status), createdAt: Number(r.created_at_ms) };
+            candidates.push([token, filing]);
         });
-        return cp;
+        const page = selectSessionPage(candidates, read, (cp) => cp, (sentence) => recordFailOpen("server.approvals.park-row-blob-unreadable", withoutTokens(sentence)));
+        if (damaged.size === 0)
+            return page;
+        return {
+            ...page,
+            rows: page.rows.map((row) => {
+                const token = row.kind === "row" ? row.checkpoint.token : row.token;
+                const hit = damaged.get(token);
+                if (hit === undefined)
+                    return row;
+                if (hit.counted && row.kind === "row")
+                    recordFailOpen("server.approvals.park-row-blob-unreadable", `session listing, session ${JSON.stringify(String(hit.r.session_id))}: ${hit.problem} — listed as unreadable`);
+                const createdAt = Number(hit.r.created_at_ms);
+                return {
+                    kind: "unreadable",
+                    token: token,
+                    scope: String(hit.r.scope),
+                    sessionId: String(hit.r.session_id),
+                    status: String(hit.r.status),
+                    createdAt: Number.isFinite(createdAt) ? createdAt : null,
+                    problem: hit.problem,
+                };
+            }),
+        };
     }
     async resolve(token, scope, outcome, expect) {
         const params = [this.json(outcome, "checkpoint outcome"), Date.now(), token, scope];

package/dist/stores-sql/file-history-store-sql.d.ts

@@ -1,15 +1,26 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport, type FileHistoryExportResult } from "@sema-agent/core";
+import { type FileHistoryRetentionPolicy, type ExecutionEnv, type FileHistoryStore, type FileHistoryError, type FileHistoryResult, type FileHistoryTrackResult, type FileHistoryRestoreResult, type FileHistoryExport, type FileHistoryExportResult } from "@sema-agent/core";
 import type { BlobBackend } from "../plugins/blob-backend.js";
 import { SqlBlobIndex } from "./blob-index-sql.js";
 import type { ServiceBlobExchange } from "../plugins/store-backend.js";
-import { type SqlDriver, type SqlDialect } from "../plugins/sql-driver.js";
+import { type SqlDriver, type SqlTxConn, type SqlDialect } from "../plugins/sql-driver.js";
 /** The file-history blob domain's SQL table (this store's blob index + the A7 assert). */
 export declare const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
 /** MinIO object-key prefix for this domain (snapshot epoch used "blobs/"; a separate prefix keeps the
  *  two domains' objects disjoint so neither sweep can see the other's keys). */
 export declare const FILE_HISTORY_BLOB_KEY_PREFIX = "file-history/";
+/**
+ * {@link SqlFileHistoryStore.prepareImport} 的答:门 / 取值校验的拒(`ok: false`,店码),或这一份信封落进目标要做什么 —— `same`(目标已是这一张图:不写)/
+ * `publish`(目标空,或 `replace` 下目标是另一张图:发布步写)。发布步({@link SqlFileHistoryStore.publishImportOn})在调用方的事务里按它做。
+ */
+export type FileHistoryImportPlan = {
+    readonly ok: false;
+    readonly error: FileHistoryError;
+} | {
+    readonly ok: true;
+    readonly mode: "same" | "publish";
+};
 /**
  * [ref] twin 保留条款(core 7.0.0 [ref] §片2 的 SQL 孪生)—— 构造期旋钮,键形与 core 内置后端
  * `FileFileHistoryStoreOptions.retention` / `FileStorageBackendOptions.fileHistory.retention` **同域同名**。
@@ -89,6 +100,13 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      * The lock order itself stays single: sentinels first (sorted), then the scope's rows.
      */
     private lockScope;
+    /**
+     * The ensure-and-lock of {@link lockScope} **without** its restart — the statement source a transaction someone else opened runs (the
+     * landed section: its first statements lock the session's root row and judge the occupant, so a restart here would drop that lock and
+     * that judgement). A lost arbitration (a deadlock victim, or {@link ScopeSentinelVanishedError}, a `SqlArbitrationLostError`) propagates;
+     * the transaction's owner restarts from ITS top. Order: sentinels sorted, then the scope's rows (the one lock order).
+     */
+    lockScopeOn(conn: SqlTxConn, scopes: readonly string[]): Promise<void>;
     /** Returns the UPDATE's affected count — 0 = the record is gone (annulled) or was already observed;
      *  the caller disambiguates by re-reading (codex R1-high: answering minted:false after the baseline
      *  vanished would let a later touch mint already-modified bytes as pristine). */
@@ -164,6 +182,12 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      *  collected by the async grace-window sweep (never a synchronous external-store delete on the purge
      *  path). Also the overwrite-dst session-sync wipe seam (import requires an EMPTY target graph). */
     deleteBySession(scope: string): Promise<number>;
+    /** The whole-scope removal as a statement source on the caller's transaction ({@link lockScopeOn} + the six tables, sentinel last):
+     *  {@link deleteBySession}'s body, and the landed section's wipe (one transaction with the session's root-row lock). Returns rows removed. */
+    deleteScopeOn(conn: SqlTxConn, scope: string): Promise<number>;
+    /** Delete one scope's rows from `tables` (caller holds the scope's sentinel lock). 第六表 `file_history_reaped_entry`(spent-entry 台账)随 scope 一起走:
+     *  E21 是删除权,台账不是例外。 */
+    private deleteScopeRowsOn;
     /** Async byte-GC: blobs referenced by NO version row (any scope), past the created_at grace window.
      *  Domain-isolated by construction (this store's blob table only — [ref] D1). Reaper-driven. */
     sweepOrphanBlobs(): Promise<number>;
@@ -190,6 +214,32 @@ export declare class SqlFileHistoryStore implements FileHistoryStore {
      */
     private verifySourceBlobs;
     importHistory(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileHistoryResult>;
+    /**
+     * 导入接住的一只故障的**唯一**折法(本店的图事务、准备步与落定段的发布步同读):core 7.55.0 —— `unsupported_format` 只说坏信封(或它的形驱动的活),
+     * 门之后撞上的故障(库拒了一份好图 / 重来用尽 / 连接断)是 `adopt_failed`,带接住的那只故障判得出的 `permanence`(判不出 ⇒ 不带)。
+     */
+    importFailureOf(err: unknown): FileHistoryError;
+    /**
+     * 导入的**事务外半**(`importHistory` 与落定段的重放同经它):门(core 的共享校验 + 本店的 mode 值域)→ 预读目标图(读不铸哨兵)判同图 / 异图 → 取值校验信封引用的每一枚 blob
+     * (首推 / 替换:校验过的字节续租进 blob 后端,发布前的孤儿清扫不收走它们;同图:只校验不回写)。`replace`(consented overwrite-dst 的落定重放)⇒ 异图不拒,按首推准备。
+     * 任何拒 ⇒ `ok: false`(店码);一个字节没发布。
+     */
+    prepareImport(scope: string, data: FileHistoryExport, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>, opts: {
+        readonly replace: boolean;
+    }): Promise<FileHistoryImportPlan>;
+    /**
+     * 导入的**发布步**,一只语句源跑在调用方的事务里(`importHistory` 自己的图事务 / 落定段):`same` ⇒ 不写;`publish` ⇒ scope 锁({@link lockScopeOn},不自己重开事务)→
+     * 事务内空目标复判(非破坏性目标律的 TOCTOU 关)→ 空 ⇒ 整图一步插入;已是这张图 ⇒ 不写;另一张图 ⇒ `replace` 下先删这一 scope 的图行(五表,哨兵留着 —— 本事务持着它)
+     * 再插(删与插同一事务:替换不会把目标留成空),否则 `conflict`、一个字节没写。
+     */
+    publishImportOn(conn: SqlTxConn, scope: string, data: FileHistoryExport, plan: Extract<FileHistoryImportPlan, {
+        ok: true;
+    }>, opts: {
+        readonly replace: boolean;
+    }): Promise<FileHistoryResult>;
+    /** The publish step's body under a held scope lock ({@link importHistory}: {@link lockScope} in the store's own transaction · {@link publishImportOn}:
+     *  {@link lockScopeOn} in the landed section). */
+    private publishImportLockedOn;
 }
 /** MySQL-protocol (TiDB) binding. */
 export declare class TiDBFileHistoryStore extends SqlFileHistoryStore {

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

@@ -2,7 +2,7 @@ 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 { 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";
@@ -12,8 +12,9 @@ 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 {
 }
+const FILE_HISTORY_SCOPED_TABLES = ["file_history_boundary_file", "file_history_boundary", "file_history_reaped_entry", "file_history_version", "file_history_tracked", "file_history_scope"];
 function reapedEntryRefusal(entryId) {
     return {
         ok: false,
@@ -67,14 +68,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 +138,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 +205,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 +313,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 +416,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 +427,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 +495,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 +512,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 +582,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,6 +594,18 @@ export class SqlFileHistoryStore {
             conn.release();
         }
     }
+    async deleteScopeOn(conn, scope) {
+        await this.lockScopeOn(conn, [scope]);
+        return this.deleteScopeRowsOn(conn, scope, FILE_HISTORY_SCOPED_TABLES);
+    }
+    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 { 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));
@@ -612,7 +624,7 @@ export class SqlFileHistoryStore {
         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);
+            const f = foldCaughtFailure(err, "sql-file-history-store.putExchangedBlob");
             return { ok: false, error: { code: "snapshot_failed", message: `blob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
         }
     }
@@ -650,7 +662,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 +719,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 +744,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 +757,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 +808,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 {