@sema-agent/server 7.51.0 → 7.52.0

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

@@ -0,0 +1,827 @@
+import { createHash } from "node:crypto";
+import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
+import { SqlBlobBackend } from "./blob-backend.js";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { isMissingColumnError } from "./sql-errors.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+export const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
+export const FILE_HISTORY_BLOB_KEY_PREFIX = "file-history/";
+const sha256hex = (s) => createHash("sha256").update(s).digest("hex");
+const truthy = (v) => v === true || v === 1 || v === "1";
+class StagedRefGoneError extends Error {
+}
+function reapedEntryRefusal(entryId) {
+    return {
+        ok: false,
+        error: {
+            code: "snapshot_failed",
+            message: `entry "${entryId}" already had a boundary and it was reaped by retention — a fresh capture now would record post-turn bytes under a pre-turn key, so this entry has no boundary and cannot get one back`,
+        },
+    };
+}
+export class SqlFileHistoryStore {
+    db;
+    pool;
+    syncBlobFaces = true;
+    blobs;
+    spentAttempts = new Set();
+    activeAttempts = new Set();
+    boundaryKeep;
+    constructor(db, pool, blobBackend, opts) {
+        this.db = db;
+        this.pool = pool;
+        this.blobs = blobBackend ?? new SqlBlobBackend(this.db.dialect, this.pool, undefined, FILE_HISTORY_BLOB_TABLE);
+        this.boundaryKeep = resolveFileHistoryRetention(this.db.dialect === "tidb" ? "TiDBFileHistoryStore" : "PgFileHistoryStore", opts?.retention);
+    }
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    bool(v) {
+        return this.db.dialect === "tidb" ? (v ? 1 : 0) : v;
+    }
+    leaseKey(scope, entryId) {
+        return `${scope}\x00${entryId}`;
+    }
+    async beforeMint(_scope, _keyHash) { }
+    async beforeObserve(_scope, _keyHash) { }
+    async beforePublish(_scope) { }
+    async lockScope(conn, ...scopes) {
+        for (const scope of [...new Set(scopes)].sort()) {
+            let locked = false;
+            for (let i = 0; i < 3 && !locked; i++) {
+                await conn.query(this.q("INSERT IGNORE INTO file_history_scope (scope, created_at_ms) VALUES (?,?)", "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]);
+                locked = Boolean(r.rows[0]);
+            }
+            if (!locked)
+                throw new Error(`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;
+    }
+    async trackEdit(scope, absPath, env, root, signal) {
+        try {
+            const { key, ...keyDesc } = fileHistoryDescribeTrackKey(root, absPath);
+            const keyHash = sha256hex(key);
+            for (let attempt = 0; attempt < 3; attempt++) {
+                const pre = await this.db.query(this.q("SELECT observed_later FROM file_history_tracked WHERE scope = ? AND key_hash = ?", "SELECT observed_later FROM file_history_tracked WHERE scope = $1 AND key_hash = $2"), [scope, keyHash]);
+                if (pre.rows[0]) {
+                    if (truthy(pre.rows[0].observed_later))
+                        return { ok: true, minted: false };
+                    await this.beforeObserve(scope, keyHash);
+                    if ((await this.markObserved(scope, keyHash)) === 1)
+                        return { ok: true, minted: false };
+                    continue;
+                }
+                const cap = await captureFileBackupViaEnv(env, absPath, root, signal);
+                if (cap.state === "aborted") {
+                    return { ok: false, error: { code: "aborted", message: `first-touch backup of ${absPath} aborted` } };
+                }
+                const baseAvailable = cap.state !== "unreadable";
+                let v1;
+                if (cap.state === "file") {
+                    await this.blobs.putBlob(cap.hash, cap.bytes);
+                    v1 = { blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) };
+                }
+                else if (cap.state === "absent") {
+                    v1 = { blobHash: null, ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) };
+                }
+                await this.beforeMint(scope, keyHash);
+                const conn = await this.db.connect();
+                let minted = false;
+                try {
+                    await conn.beginPessimistic();
+                    await this.lockScope(conn, scope);
+                    const ins = await conn.query(this.q("INSERT IGNORE 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) ON CONFLICT (scope, key_hash) DO NOTHING"), [scope, keyHash, key, keyDesc.kind, keyDesc.family, this.bool(baseAvailable), Date.now()]);
+                    minted = ins.affected === 1;
+                    if (minted && v1 !== undefined) {
+                        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, 1, v1.blobHash, v1.mode ?? null, v1.parentIdent ?? null, new Date().toISOString()]);
+                    }
+                    await conn.commit();
+                }
+                catch (err) {
+                    await conn.rollback().catch(() => undefined);
+                    throw err;
+                }
+                finally {
+                    conn.release();
+                }
+                if (minted)
+                    return { ok: true, minted: true };
+                if ((await this.markObserved(scope, keyHash)) === 1)
+                    return { ok: true, minted: false };
+            }
+            return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} kept racing a concurrent retraction — retry` } };
+        }
+        catch (err) {
+            return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${err.message}` } };
+        }
+    }
+    async annulIneligibleReason(scope, keyHash, absPath) {
+        const ref = await this.db.query(this.q("SELECT 1 FROM file_history_boundary_file WHERE scope = ? AND key_hash = ? LIMIT 1", "SELECT 1 FROM file_history_boundary_file WHERE scope = $1 AND key_hash = $2 LIMIT 1"), [scope, keyHash]);
+        if (ref.rows[0])
+            return `first-touch record for ${absPath} is referenced by a committed boundary — it is history now, not a retractable mint`;
+        const grown = await this.db.query(this.q("SELECT 1 FROM file_history_version WHERE scope = ? AND key_hash = ? AND version > 1 LIMIT 1", "SELECT 1 FROM file_history_version WHERE scope = $1 AND key_hash = $2 AND version > 1 LIMIT 1"), [scope, keyHash]);
+        if (grown.rows[0])
+            return `first-touch record for ${absPath} has grown past its first version — only the mint itself is retractable`;
+        const row = await this.db.query(this.q("SELECT observed_later FROM file_history_tracked WHERE scope = ? AND key_hash = ?", "SELECT observed_later FROM file_history_tracked WHERE scope = $1 AND key_hash = $2"), [scope, keyHash]);
+        if (row.rows[0] && truthy(row.rows[0].observed_later)) {
+            return `first-touch record for ${absPath} has since been served to another edit of the same path — it is that edit's baseline now, not a retractable mint`;
+        }
+        return undefined;
+    }
+    async annulTrack(scope, absPath, root, verify) {
+        try {
+            const key = fileHistoryTrackKeyOf(root, absPath);
+            const keyHash = sha256hex(key);
+            const t = await this.db.query(this.q("SELECT base_available FROM file_history_tracked WHERE scope = ? AND key_hash = ?", "SELECT base_available FROM file_history_tracked WHERE scope = $1 AND key_hash = $2"), [scope, keyHash]);
+            if (!t.rows[0])
+                return { ok: true };
+            const before = await this.annulIneligibleReason(scope, keyHash, absPath);
+            if (before !== undefined)
+                return { ok: false, error: { code: "conflict", message: before } };
+            if (verify !== undefined) {
+                const v1 = await this.db.query(this.q("SELECT blob_hash FROM file_history_version WHERE scope = ? AND key_hash = ? AND version = 1", "SELECT blob_hash FROM file_history_version WHERE scope = $1 AND key_hash = $2 AND version = 1"), [scope, keyHash]);
+                const baseAvailable = truthy(t.rows[0].base_available);
+                const mintedBlobHash = v1.rows[0]?.blob_hash != null ? String(v1.rows[0].blob_hash) : null;
+                const proof = await worldStillMatchesMint(verify.env, absPath, root, baseAvailable, mintedBlobHash, verify.signal);
+                if (!proof.unchanged) {
+                    return {
+                        ok: false,
+                        error: {
+                            code: "conflict",
+                            message: `first-touch record for ${absPath} is NOT retractable: ${proof.reason} — the write this retraction compensates for may have changed the file, and deleting the only baseline of a modified file is worse than keeping a stale record`,
+                        },
+                    };
+                }
+            }
+            const conn = await this.db.connect();
+            try {
+                await conn.beginPessimistic();
+                await this.lockScope(conn, scope);
+                const del = await conn.query(this.q(`DELETE FROM file_history_tracked WHERE scope = ? AND key_hash = ? AND observed_later = 0
+               AND NOT EXISTS (SELECT 1 FROM file_history_boundary_file bf WHERE bf.scope = ? AND bf.key_hash = ?)
+               AND NOT EXISTS (SELECT 1 FROM file_history_version v WHERE v.scope = ? AND v.key_hash = ? AND v.version > 1)`, `DELETE FROM file_history_tracked WHERE scope = $1 AND key_hash = $2 AND observed_later = FALSE
+               AND NOT EXISTS (SELECT 1 FROM file_history_boundary_file bf WHERE bf.scope = $3 AND bf.key_hash = $4)
+               AND NOT EXISTS (SELECT 1 FROM file_history_version v WHERE v.scope = $5 AND v.key_hash = $6 AND v.version > 1)`), [scope, keyHash, scope, keyHash, scope, keyHash]);
+                if (del.affected === 1) {
+                    await conn.query(this.q("DELETE FROM file_history_version WHERE scope = ? AND key_hash = ?", "DELETE FROM file_history_version WHERE scope = $1 AND key_hash = $2"), [scope, keyHash]);
+                    await conn.commit();
+                    return { ok: true };
+                }
+                await conn.commit();
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+            const after = await this.annulIneligibleReason(scope, keyHash, absPath);
+            if (after !== undefined)
+                return { ok: false, error: { code: "conflict", message: after } };
+            const still = await this.db.query(this.q("SELECT 1 FROM file_history_tracked WHERE scope = ? AND key_hash = ?", "SELECT 1 FROM file_history_tracked WHERE scope = $1 AND key_hash = $2"), [scope, keyHash]);
+            if (!still.rows[0])
+                return { ok: true };
+            return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} was replaced while this retraction was being proven` } };
+        }
+        catch (err) {
+            return { ok: false, error: { code: "track_failed", message: `annulling the first-touch record for ${absPath} failed: ${err.message}` } };
+        }
+    }
+    async loadTracked(exec, scope, forUpdate = false) {
+        const suffix = forUpdate ? " FOR UPDATE" : "";
+        const r = await exec.query(this.q(`SELECT key_hash, track_key, key_kind, key_family, base_available FROM file_history_tracked WHERE scope = ?${suffix}`, `SELECT key_hash, track_key, key_kind, key_family, base_available FROM file_history_tracked WHERE scope = $1${suffix}`), [scope]);
+        return r.rows.map((row) => ({
+            keyHash: String(row.key_hash),
+            trackKey: String(row.track_key),
+            keyDesc: { kind: String(row.key_kind), family: String(row.key_family) },
+            baseAvailable: truthy(row.base_available),
+        }));
+    }
+    async loadVersions(exec, scope) {
+        const r = await exec.query(this.q("SELECT key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = ? ORDER BY version", "SELECT key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = $1 ORDER BY version"), [scope]);
+        const out = new Map();
+        for (const row of r.rows) {
+            const kh = String(row.key_hash);
+            let list = out.get(kh);
+            if (list === undefined)
+                out.set(kh, (list = []));
+            list.push({
+                version: Number(row.version),
+                blobHash: row.blob_hash != null ? String(row.blob_hash) : null,
+                ...(row.mode != null ? { mode: Number(row.mode) } : {}),
+                ...(row.parent_ident != null ? { parentIdent: String(row.parent_ident) } : {}),
+                backupTime: String(row.backup_time),
+            });
+        }
+        return out;
+    }
+    async entryReaped(exec, scope, entryId, forUpdate = false) {
+        const suffix = forUpdate ? " FOR UPDATE" : "";
+        const r = await exec.query(this.q(`SELECT 1 FROM file_history_reaped_entry WHERE scope = ? AND entry_id = ? LIMIT 1${suffix}`, `SELECT 1 FROM file_history_reaped_entry WHERE scope = $1 AND entry_id = $2 LIMIT 1${suffix}`), [scope, entryId]);
+        return r.rows[0] !== undefined;
+    }
+    async copyReapedEntries(conn, fromScope, toScope) {
+        await conn.query(this.q("INSERT IGNORE INTO file_history_reaped_entry (scope, entry_id, reaped_at_ms) SELECT ?, entry_id, reaped_at_ms FROM file_history_reaped_entry WHERE scope = ?", "INSERT INTO file_history_reaped_entry (scope, entry_id, reaped_at_ms) SELECT $1, entry_id, reaped_at_ms FROM file_history_reaped_entry WHERE scope = $2 ON CONFLICT (scope, entry_id) DO NOTHING"), [toScope, fromScope]);
+    }
+    async beforeRetentionPass(_scope) { }
+    async duringRetentionPass(_scope) { }
+    async duringRestorePlan(_scope, _entryId) { }
+    async beforePublishLock(_scope) { }
+    async duringExportGraph(_scope) { }
+    async applyBoundaryRetention(scope, justCommitted) {
+        if (this.boundaryKeep === null)
+            return;
+        try {
+            await this.beforeRetentionPass(scope);
+            const conn = await this.db.connect();
+            try {
+                await conn.beginPessimistic();
+                await this.lockScope(conn, scope);
+                const { rows } = await conn.query(this.q("SELECT entry_id, publish_seq FROM file_history_boundary WHERE scope = ? ORDER BY publish_seq ASC", "SELECT entry_id, publish_seq FROM file_history_boundary WHERE scope = $1 ORDER BY publish_seq ASC"), [scope]);
+                const ordered = rows.map((r) => ({ id: String(r.entry_id), seq: Number(r.publish_seq) }));
+                if (ordered.length === 0) {
+                    await conn.rollback();
+                    return;
+                }
+                const mine = ordered.find((b) => b.id === justCommitted);
+                const pin = mine ?? ordered[ordered.length - 1];
+                const keepIds = fileHistoryBoundariesToKeep(ordered.map((b) => b.id), pin.id, this.boundaryKeep);
+                if (keepIds === null) {
+                    await conn.rollback();
+                    return;
+                }
+                const keep = new Set(keepIds);
+                for (const b of ordered)
+                    if (b.seq > pin.seq)
+                        keep.add(b.id);
+                await this.duringRetentionPass(scope);
+                await this.reapWithin(conn, scope, keep, ordered.map((b) => b.id));
+                await conn.commit();
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+        }
+        catch (err) {
+            recordFailOpen("server.file-history.retention-trim-failed", `scope=${scope} entry=${justCommitted}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async boundaryExists(exec, scope, entryId) {
+        const r = await exec.query(this.q("SELECT 1 FROM file_history_boundary WHERE scope = ? AND entry_id = ? LIMIT 1", "SELECT 1 FROM file_history_boundary WHERE scope = $1 AND entry_id = $2 LIMIT 1"), [scope, entryId]);
+        return Boolean(r.rows[0]);
+    }
+    async snapshot(scope, entryId, env, root, signal) {
+        const lease = this.leaseKey(scope, entryId);
+        try {
+            if (await this.boundaryExists(this.db, scope, entryId))
+                return { ok: true };
+            if (await this.entryReaped(this.db, scope, entryId))
+                return reapedEntryRefusal(entryId);
+            if (this.spentAttempts.has(lease)) {
+                return { ok: false, error: { code: "snapshot_failed", message: `capture lease for entry "${entryId}" is closed (a prior attempt failed); no complete pre-close staging exists, so this turn has no boundary` } };
+            }
+            if (this.activeAttempts.has(lease)) {
+                return { ok: false, error: { code: "snapshot_failed", message: `a capture attempt for entry "${entryId}" is already in flight — concurrent same-key capture is refused (the in-flight attempt owns the lease)` } };
+            }
+        }
+        catch (err) {
+            return { ok: false, error: { code: "snapshot_failed", message: err.message } };
+        }
+        this.activeAttempts.add(lease);
+        try {
+            const tracked = await this.loadTracked(this.db, scope);
+            const versions = await this.loadVersions(this.db, scope);
+            const staged = new Map();
+            for (const t of tracked) {
+                if (signal?.aborted) {
+                    this.spentAttempts.add(lease);
+                    return { ok: false, error: { code: "aborted", message: `boundary capture for entry "${entryId}" aborted` } };
+                }
+                const resolved = fileHistoryResolveTrackKey(root, t.trackKey, t.keyDesc);
+                if (!resolved.ok) {
+                    this.spentAttempts.add(lease);
+                    return { ok: false, error: { code: "snapshot_failed", message: resolved.reason } };
+                }
+                const cap = await captureFileBackupViaEnv(env, resolved.abs, root, signal);
+                if (cap.state === "aborted") {
+                    this.spentAttempts.add(lease);
+                    return { ok: false, error: { code: "aborted", message: `boundary capture for entry "${entryId}" aborted` } };
+                }
+                if (cap.state === "unreadable") {
+                    this.spentAttempts.add(lease);
+                    return { ok: false, error: { code: "snapshot_failed", message: cap.cause } };
+                }
+                const chain = versions.get(t.keyHash) ?? [];
+                const last = chain[chain.length - 1];
+                if (cap.state === "absent") {
+                    if (last !== undefined && last.blobHash === null)
+                        staged.set(t.keyHash, { kind: "unchanged", version: last.version });
+                    else
+                        staged.set(t.keyHash, { kind: "changed", blobHash: null, ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) });
+                    continue;
+                }
+                if (last !== undefined && last.blobHash === cap.hash && !fileHistoryModeProvenDifferent(last.mode, cap.mode)) {
+                    staged.set(t.keyHash, { kind: "unchanged", version: last.version });
+                    continue;
+                }
+                await this.blobs.putBlob(cap.hash, cap.bytes);
+                staged.set(t.keyHash, { kind: "changed", blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) });
+            }
+            const verdict = boundaryPublishVerdict({ aborted: signal?.aborted === true });
+            if (!verdict.publish) {
+                this.spentAttempts.add(lease);
+                return { ok: false, error: { code: "aborted", message: `boundary capture for entry "${entryId}" aborted (fenced — never committed)` } };
+            }
+            await this.beforePublish(scope);
+            const conn = await this.db.connect();
+            try {
+                await conn.beginPessimistic();
+                await this.beforePublishLock(scope);
+                await this.lockScope(conn, scope);
+                if (signal?.aborted) {
+                    await conn.rollback();
+                    this.spentAttempts.add(lease);
+                    return { ok: false, error: { code: "aborted", message: `boundary capture for entry "${entryId}" aborted (fenced — never committed)` } };
+                }
+                if (await this.entryReaped(conn, scope, entryId, true)) {
+                    await conn.rollback();
+                    return reapedEntryRefusal(entryId);
+                }
+                const seqRow = await conn.query(this.q("SELECT publish_seq FROM file_history_boundary WHERE scope = ? ORDER BY publish_seq DESC LIMIT 1 FOR UPDATE", "SELECT publish_seq FROM file_history_boundary WHERE scope = $1 ORDER BY publish_seq DESC LIMIT 1"), [scope]);
+                const publishSeq = (seqRow.rows[0] !== undefined ? Number(seqRow.rows[0].publish_seq) : 0) + 1;
+                const ins = await conn.query(this.q("INSERT IGNORE INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES (?,?,CAST(UNIX_TIMESTAMP(NOW(3))*1000 AS SIGNED),?)", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES ($1,$2,(EXTRACT(EPOCH FROM clock_timestamp())*1000)::bigint,$3) ON CONFLICT (scope, entry_id) DO NOTHING"), [scope, entryId, publishSeq]);
+                if (ins.affected !== 1) {
+                    const won = await conn.query(this.q("SELECT 1 FROM file_history_boundary WHERE scope = ? AND entry_id = ? FOR UPDATE", "SELECT 1 FROM file_history_boundary WHERE scope = $1 AND entry_id = $2 FOR UPDATE"), [scope, entryId]);
+                    if (!won.rows[0]) {
+                        throw new Error(`boundary publish for entry "${entryId}" was suppressed without a same-entry winner (publish_seq allocation invariant breach) — refusing to report a boundary that was not stored`);
+                    }
+                    await conn.rollback();
+                    return { ok: true };
+                }
+                for (const [keyHash, cap] of staged) {
+                    let version;
+                    if (cap.kind === "unchanged") {
+                        const still = await conn.query(this.q("SELECT 1 FROM file_history_version WHERE scope = ? AND key_hash = ? AND version = ? FOR UPDATE", "SELECT 1 FROM file_history_version WHERE scope = $1 AND key_hash = $2 AND version = $3 FOR UPDATE"), [scope, keyHash, cap.version]);
+                        if (!still.rows[0])
+                            throw new StagedRefGoneError(`staged reference ${keyHash}@v${cap.version} no longer exists (reaped mid-capture)`);
+                        version = cap.version;
+                    }
+                    else {
+                        const stillTracked = await conn.query(this.q("SELECT base_available FROM file_history_tracked WHERE scope = ? AND key_hash = ? FOR UPDATE", "SELECT base_available FROM file_history_tracked WHERE scope = $1 AND key_hash = $2 FOR UPDATE"), [scope, keyHash]);
+                        if (!stillTracked.rows[0])
+                            continue;
+                        const tail = await conn.query(this.q("SELECT version FROM file_history_version WHERE scope = ? AND key_hash = ? ORDER BY version DESC LIMIT 1 FOR UPDATE", "SELECT version FROM file_history_version WHERE scope = $1 AND key_hash = $2 ORDER BY version DESC LIMIT 1 FOR UPDATE"), [scope, keyHash]);
+                        const last = tail.rows[0] !== undefined ? Number(tail.rows[0].version) : undefined;
+                        version = last !== undefined ? last + 1 : truthy(stillTracked.rows[0].base_available) ? 1 : 2;
+                        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, version, cap.blobHash, cap.mode ?? null, cap.parentIdent ?? null, new Date().toISOString()]);
+                    }
+                    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, entryId, keyHash, version]);
+                }
+                if (signal?.aborted) {
+                    await conn.rollback();
+                    this.spentAttempts.add(lease);
+                    return { ok: false, error: { code: "aborted", message: `boundary capture for entry "${entryId}" aborted (fenced — never committed)` } };
+                }
+                await conn.commit();
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                this.spentAttempts.add(lease);
+                return { ok: false, error: { code: "snapshot_failed", message: `boundary for entry "${entryId}" could not be committed: ${err.message}` } };
+            }
+            finally {
+                conn.release();
+            }
+            await this.applyBoundaryRetention(scope, entryId);
+            return { ok: true };
+        }
+        catch (err) {
+            this.spentAttempts.add(lease);
+            return { ok: false, error: { code: "snapshot_failed", message: err.message } };
+        }
+        finally {
+            this.activeAttempts.delete(lease);
+        }
+    }
+    async restore(scope, entryId, env, root, signal) {
+        const empty = { filesChanged: [], identicalSkipped: [], refused: [], failed: [] };
+        try {
+            if (!(await this.boundaryExists(this.db, scope, entryId))) {
+                return { outcome: "failed", ...empty, error: { code: "not_found", message: `no history boundary for entry "${entryId}"` } };
+            }
+            const plan = await this.restorePlan(scope, entryId);
+            if (plan === null) {
+                return { outcome: "failed", ...empty, error: { code: "not_found", message: `no history boundary for entry "${entryId}"` } };
+            }
+            const { tracked, versions, boundary } = plan;
+            const ledger = empty;
+            let modeNotPreserved = 0;
+            for (const t of tracked) {
+                if (signal?.aborted) {
+                    ledger.failed.push({ path: t.trackKey, reason: "aborted before attempt" });
+                    continue;
+                }
+                let targetVersion = boundary.get(t.keyHash);
+                if (targetVersion === undefined) {
+                    if (!t.baseAvailable) {
+                        ledger.refused.push({ path: t.trackKey, reason: "base_unavailable" });
+                        continue;
+                    }
+                    targetVersion = 1;
+                }
+                const rec = (versions.get(t.keyHash) ?? []).find((v) => v.version === targetVersion);
+                if (rec === undefined) {
+                    ledger.failed.push({ path: t.trackKey, reason: `version ${targetVersion} record missing (store integrity)` });
+                    continue;
+                }
+                if (rec.mode !== undefined && !(Number.isInteger(rec.mode) && rec.mode >= 0 && rec.mode <= 0o7777)) {
+                    ledger.refused.push({ path: t.trackKey, reason: `recorded mode ${String(rec.mode)} is not a valid POSIX permission value — refusing to apply a corrupted permission record` });
+                    continue;
+                }
+                const resolved = fileHistoryResolveTrackKey(root, t.trackKey, t.keyDesc);
+                if (!resolved.ok) {
+                    ledger.refused.push({ path: t.trackKey, reason: resolved.reason });
+                    continue;
+                }
+                let applied;
+                try {
+                    let target;
+                    if (rec.blobHash === null)
+                        target = { absent: true };
+                    else {
+                        const bytes = await this.blobs.getBlob(rec.blobHash);
+                        if (bytes === undefined) {
+                            ledger.failed.push({ path: t.trackKey, reason: `blob ${rec.blobHash} missing (store integrity)` });
+                            continue;
+                        }
+                        target = { bytes, hash: rec.blobHash };
+                    }
+                    applied = await applyFileRestoreViaEnv(env, resolved.abs, target, {
+                        root,
+                        ...(rec.parentIdent !== undefined ? { parentIdent: rec.parentIdent } : {}),
+                        ...(rec.mode !== undefined ? { mode: rec.mode } : {}),
+                        ...(signal !== undefined ? { signal } : {}),
+                    });
+                }
+                catch (err) {
+                    applied = { outcome: "failed", reason: err.message };
+                }
+                if (applied.outcome === "applied")
+                    ledger.filesChanged.push(t.trackKey);
+                else if (applied.outcome === "identical")
+                    ledger.identicalSkipped.push(t.trackKey);
+                else if (applied.outcome === "refused")
+                    ledger.refused.push({ path: t.trackKey, reason: applied.reason });
+                else
+                    ledger.failed.push({ path: t.trackKey, reason: applied.reason });
+                if ((applied.outcome === "applied" || applied.outcome === "identical") && applied.modeNotPreserved === true)
+                    modeNotPreserved++;
+            }
+            return { outcome: ledger.refused.length > 0 || ledger.failed.length > 0 ? "partial" : "complete", ...ledger, ...(modeNotPreserved > 0 ? { modeNotPreserved } : {}) };
+        }
+        catch (err) {
+            const touched = empty.filesChanged.length > 0 || empty.identicalSkipped.length > 0 || empty.refused.length > 0 || empty.failed.length > 0;
+            return { outcome: touched ? "partial" : "failed", ...empty, error: { code: "restore_failed", message: err.message } };
+        }
+    }
+    async restorePlan(scope, entryId) {
+        const conn = await this.db.connect();
+        try {
+            await conn.beginPessimistic();
+            await this.lockScope(conn, scope);
+            if (!(await this.boundaryExists(conn, scope, entryId))) {
+                await conn.rollback();
+                return null;
+            }
+            await this.duringRestorePlan(scope, entryId);
+            const tracked = (await this.loadTracked(conn, scope)).sort((a, b) => (a.trackKey < b.trackKey ? -1 : a.trackKey > b.trackKey ? 1 : 0));
+            const versions = await this.loadVersions(conn, scope);
+            const mapRows = await conn.query(this.q("SELECT key_hash, version FROM file_history_boundary_file WHERE scope = ? AND entry_id = ?", "SELECT key_hash, version FROM file_history_boundary_file WHERE scope = $1 AND entry_id = $2"), [scope, entryId]);
+            const boundary = new Map(mapRows.rows.map((r) => [String(r.key_hash), Number(r.version)]));
+            await conn.commit();
+            return { tracked, versions, boundary };
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async canRestore(scope, entryId) {
+        return this.boundaryExists(this.db, scope, entryId);
+    }
+    async reap(scope, keepEntryIds) {
+        const conn = await this.db.connect();
+        try {
+            await conn.beginPessimistic();
+            await this.lockScope(conn, scope);
+            const ids = await conn.query(this.q("SELECT entry_id FROM file_history_boundary WHERE scope = ?", "SELECT entry_id FROM file_history_boundary WHERE scope = $1"), [scope]);
+            const dropped = await this.reapWithin(conn, scope, new Set(keepEntryIds), ids.rows.map((r) => String(r.entry_id)));
+            await conn.commit();
+            return dropped;
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async reapWithin(conn, scope, keep, present) {
+        {
+            const drop = present.filter((id) => !keep.has(id));
+            const reapedAtMs = Date.now();
+            for (const id of drop) {
+                await conn.query(this.q("INSERT IGNORE INTO file_history_reaped_entry (scope, entry_id, reaped_at_ms) VALUES (?,?,?)", "INSERT INTO file_history_reaped_entry (scope, entry_id, reaped_at_ms) VALUES ($1,$2,$3) ON CONFLICT (scope, entry_id) DO NOTHING"), [scope, id, reapedAtMs]);
+                await conn.query(this.q("DELETE FROM file_history_boundary WHERE scope = ? AND entry_id = ?", "DELETE FROM file_history_boundary WHERE scope = $1 AND entry_id = $2"), [scope, id]);
+                await conn.query(this.q("DELETE FROM file_history_boundary_file WHERE scope = ? AND entry_id = ?", "DELETE FROM file_history_boundary_file WHERE scope = $1 AND entry_id = $2"), [scope, id]);
+            }
+            await conn.query(this.q(`DELETE FROM file_history_version WHERE scope = ? AND version <> 1
+             AND NOT EXISTS (SELECT 1 FROM file_history_boundary_file bf WHERE bf.scope = ? AND bf.key_hash = file_history_version.key_hash AND bf.version = file_history_version.version)`, `DELETE FROM file_history_version WHERE scope = $1 AND version <> 1
+             AND NOT EXISTS (SELECT 1 FROM file_history_boundary_file bf WHERE bf.scope = $2 AND bf.key_hash = file_history_version.key_hash AND bf.version = file_history_version.version)`), [scope, scope]);
+            return drop.length;
+        }
+    }
+    async deleteBySession(scope) {
+        const conn = await this.db.connect();
+        try {
+            await conn.beginPessimistic();
+            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;
+            }
+            await conn.commit();
+            return total;
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            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.deleteBlobs(orphans);
+    }
+    async putBlob(hash, bytes) {
+        if (sha256hex(bytes) !== hash) {
+            return { ok: false, error: { code: "unsupported_format", message: `putBlob ${hash} fails content-address integrity — nothing stored` } };
+        }
+        try {
+            await this.blobs.putBlob(hash, bytes);
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: { code: "snapshot_failed", message: `putBlob ${hash} write/upload failed: ${err.message}` } };
+        }
+    }
+    async getBlob(hash) {
+        return this.blobs.getBlob(hash);
+    }
+    async hasBlobs(hashes) {
+        return this.blobs.hasBlobs(hashes);
+    }
+    async adoptScope(fromScope, toScope) {
+        try {
+            if (fromScope === toScope)
+                return { ok: true };
+            const conn = await this.db.connect();
+            try {
+                await conn.beginPessimistic();
+                await this.lockScope(conn, fromScope, toScope);
+                if (!(await this.scopeEmpty(conn, toScope, true))) {
+                    await conn.rollback();
+                    return { ok: false, error: { code: "conflict", message: `adoptScope target "${toScope}" already has history of its own — adoption is legal only onto an EMPTY scope (the fork/resume boundary before the new session's first turn)` } };
+                }
+                if (await this.scopeEmpty(conn, fromScope)) {
+                    await this.copyReapedEntries(conn, fromScope, toScope);
+                    await conn.commit();
+                    return { ok: true };
+                }
+                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) SELECT ?, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms FROM file_history_tracked WHERE scope = ?", "INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) SELECT $1, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms FROM file_history_tracked WHERE scope = $2"), [toScope, fromScope]);
+                await conn.query(this.q("INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) SELECT ?, key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = ?", "INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) SELECT $1, key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = $2"), [toScope, fromScope]);
+                await conn.query(this.q("INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) SELECT ?, entry_id, published_at_ms, publish_seq FROM file_history_boundary WHERE scope = ?", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) SELECT $1, entry_id, published_at_ms, publish_seq FROM file_history_boundary WHERE scope = $2"), [toScope, fromScope]);
+                await conn.query(this.q("INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) SELECT ?, entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = ?", "INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) SELECT $1, entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = $2"), [toScope, fromScope]);
+                await this.copyReapedEntries(conn, fromScope, toScope);
+                await conn.commit();
+                return { ok: true };
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+        }
+        catch (err) {
+            return { ok: false, error: { code: "conflict", message: `adoptScope failed: ${err.message}` } };
+        }
+    }
+    async scopeEmpty(exec, scope, forUpdate = false) {
+        const suffix = forUpdate ? " FOR UPDATE" : "";
+        const t = await exec.query(this.q(`SELECT 1 FROM file_history_tracked WHERE scope = ? LIMIT 1${suffix}`, `SELECT 1 FROM file_history_tracked WHERE scope = $1 LIMIT 1${suffix}`), [scope]);
+        if (t.rows[0])
+            return false;
+        const b = await exec.query(this.q(`SELECT 1 FROM file_history_boundary WHERE scope = ? LIMIT 1${suffix}`, `SELECT 1 FROM file_history_boundary WHERE scope = $1 LIMIT 1${suffix}`), [scope]);
+        return !b.rows[0];
+    }
+    async exportOf(exec, scope) {
+        const tracked = await this.loadTracked(exec, scope);
+        const versions = await this.loadVersions(exec, scope);
+        const headers = await exec.query(this.q("SELECT entry_id FROM file_history_boundary WHERE scope = ?", "SELECT entry_id FROM file_history_boundary WHERE scope = $1"), [scope]);
+        if (tracked.length === 0 && headers.rows.length === 0)
+            return null;
+        await this.duringExportGraph(scope);
+        const files = await exec.query(this.q("SELECT entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = ?", "SELECT entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = $1"), [scope]);
+        const keyOfHash = new Map(tracked.map((t) => [t.keyHash, t.trackKey]));
+        const byEntry = new Map();
+        for (const row of files.rows) {
+            const entry = String(row.entry_id);
+            let list = byEntry.get(entry);
+            if (list === undefined)
+                byEntry.set(entry, (list = []));
+            list.push({ relOrAbsPath: keyOfHash.get(String(row.key_hash)) ?? String(row.key_hash), version: Number(row.version) });
+        }
+        const sortStr = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+        return {
+            formatVersion: "file-history/1",
+            tracked: [...tracked]
+                .sort((a, b) => sortStr(a.trackKey, b.trackKey))
+                .map((t) => ({
+                relOrAbsPath: t.trackKey,
+                keyKind: t.keyDesc.kind,
+                keyFamily: t.keyDesc.family,
+                baseAvailable: t.baseAvailable,
+                versions: (versions.get(t.keyHash) ?? []).map((v) => ({
+                    version: v.version,
+                    blobHash: v.blobHash,
+                    ...(v.mode !== undefined ? { mode: v.mode } : {}),
+                    ...(v.parentIdent !== undefined ? { parentIdent: v.parentIdent } : {}),
+                    backupTime: v.backupTime,
+                })),
+            })),
+            boundaries: [...headers.rows.map((r) => String(r.entry_id))]
+                .sort(sortStr)
+                .map((entryId) => ({ entryId, files: (byEntry.get(entryId) ?? []).sort((a, b) => sortStr(a.relOrAbsPath, b.relOrAbsPath)) })),
+        };
+    }
+    async exportHistory(scope) {
+        const conn = await this.db.connect();
+        try {
+            await conn.beginPessimistic();
+            await this.lockScope(conn, scope);
+            const out = await this.exportOf(conn, scope);
+            await conn.commit();
+            return out;
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async importHistory(scope, data, srcGetBlob) {
+        try {
+            const shaped = validateFileHistoryExport(data);
+            if (!shaped.ok)
+                return shaped;
+            for (const t of data.tracked) {
+                for (const v of t.versions) {
+                    const m = v.mode;
+                    if (m !== undefined && !(typeof m === "number" && Number.isInteger(m) && m >= 0 && m <= 0o7777)) {
+                        return { ok: false, error: { code: "unsupported_format", message: `tracked row ${t.relOrAbsPath} v${v.version} carries an invalid POSIX mode ${JSON.stringify(m)} — a permission value outside integer [0, 0o7777] is refused, never masked (an imported mode becomes filesystem permission bits on restore)` } };
+                    }
+                }
+            }
+            const existing = await this.exportHistory(scope);
+            if (existing !== null) {
+                if (fileHistoryExportDigest(existing) === fileHistoryExportDigest(data))
+                    return { ok: true };
+                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 needed = new Set();
+            for (const t of data.tracked)
+                for (const v of t.versions)
+                    if (v.blobHash !== null)
+                        needed.add(v.blobHash);
+            for (const hash of needed) {
+                let bytes;
+                try {
+                    bytes = await srcGetBlob(hash);
+                }
+                catch (err) {
+                    return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fetch failed: ${err.message}` } };
+                }
+                if (bytes === undefined)
+                    return { ok: false, error: { code: "not_found", message: `source blob ${hash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
+                if (sha256hex(bytes) !== hash) {
+                    return { ok: false, error: { code: "unsupported_format", message: `source blob ${hash} fails content-address integrity — refused, nothing published` } };
+                }
+                await this.blobs.putBlob(hash, bytes);
+            }
+            const conn = await this.db.connect();
+            try {
+                await conn.beginPessimistic();
+                await this.lockScope(conn, scope);
+                if (!(await this.scopeEmpty(conn, scope, true))) {
+                    const now = await this.exportOf(conn, scope);
+                    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 };
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+        }
+        catch (err) {
+            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${err.message}` } };
+        }
+    }
+}
+export class TiDBFileHistoryStore extends SqlFileHistoryStore {
+    constructor(pool, blobBackend, opts) {
+        super(mysqlDriver(pool), pool, blobBackend, opts);
+    }
+}
+export class PgFileHistoryStore extends SqlFileHistoryStore {
+    constructor(pool, blobBackend, opts) {
+        super(pgDriver(pool), pool, blobBackend, opts);
+    }
+}
+export async function assertFileHistorySchema(query, dialect) {
+    const probes = [
+        ["file_history_tracked", "SELECT scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms FROM file_history_tracked WHERE 1=0"],
+        ["file_history_version", "SELECT scope, key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE 1=0"],
+        ["file_history_boundary", "SELECT scope, entry_id, published_at_ms, publish_seq FROM file_history_boundary WHERE 1=0"],
+        ["file_history_boundary_file", "SELECT scope, entry_id, key_hash, version FROM file_history_boundary_file WHERE 1=0"],
+        ["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`],
+    ];
+    for (const [table, sql] of probes) {
+        try {
+            await query(sql);
+        }
+        catch (err) {
+            if (!isMissingColumnError(err, dialect))
+                throw err;
+            throw new Error(`${table} is missing required columns — refusing to start. This build's per-file rewind history (S-15) ` +
+                `references every probed column unconditionally; a partial table would fail mid-write and could publish a ` +
+                `half-shaped history graph. This repository ships no ALTER TABLE migrations, so the table must be recreated: run ` +
+                `\`DROP TABLE ${table};\` on the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the ` +
+                `schema is recreated at boot. Cost, honestly stated: dropping file_history_* tables loses per-file REWIND history ` +
+                `(working-tree convenience state); session transcripts and all other durable subsystems are untouched. ` +
+                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=file-history-store-sql.js.map