@sema-agent/core 7.54.1 → 7.56.0

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

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, closeSync, existsSync, fsyncSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { thrownText } from "../../core/thrown-value.js";
-import { applyFileRestoreViaEnv, boundaryPublishVerdict, worldStillMatchesMint, captureFileBackupViaEnv, modeProvenDifferent, previewFileDelta, describeTrackKey, fileHistoryExportDigest, resolveTrackKey, trackKeyOf, validateFileHistoryExport, } from "../../core/file-history-store.js";
+import { applyFileRestoreViaEnv, boundaryPublishVerdict, worldStillMatchesMint, annulProofFailure, captureFileBackupViaEnv, modeProvenDifferent, previewFileDelta, describeTrackKey, fileHistoryExportDigest, caughtFault, DAMAGED_RECORD, resolveTrackKey, trackKeyOf, validateFileHistoryExport, } from "../../core/file-history-store.js";
 import { fileHistoryBoundariesToKeep, resolveFileHistoryRetention } from "../../core/file-history-retention.js";
 import { atomicWriteFile, ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
@@ -109,6 +109,12 @@ function nestedMapSet(map, scope, key, value) {
         map.set(scope, (inner = new Map()));
     inner.set(key, value);
 }
+function worstFault(faults) {
+    const terminal = faults.find((f) => f.permanence === "terminal");
+    if (terminal !== undefined)
+        return terminal;
+    return faults.length > 0 && faults.every((f) => f.permanence === "transient") ? faults[0] : {};
+}
 function safeRm(path) {
     try {
         rmSync(path, { force: true, recursive: true });
@@ -227,21 +233,21 @@ export class FileFileHistoryStore {
             if (err.code === "ENOENT")
                 return { corrupt: false, tracked: new Map() };
             this.disclose(path, `tracked set unreadable (${err.code ?? "unknown"}) — this scope's history is UNUSABLE until it is repaired`);
-            return { corrupt: true, tracked: new Map() };
+            return { corrupt: true, tracked: new Map(), fault: caughtFault(err) };
         }
         const parsed = parseJsonRecord(raw);
         if (parsed === null) {
             this.disclose(path, "unparseable tracked set (torn/zero-byte write?) — this scope's history is UNUSABLE until it is repaired");
-            return { corrupt: true, tracked: new Map() };
+            return { corrupt: true, tracked: new Map(), fault: DAMAGED_RECORD };
         }
         const rows = trackedRowsOf(parsed);
         if (rows === null) {
             this.disclose(path, "tracked set is not a pair array of [key, record] rows — this scope's history is UNUSABLE until it is repaired");
-            return { corrupt: true, tracked: new Map() };
+            return { corrupt: true, tracked: new Map(), fault: DAMAGED_RECORD };
         }
         if (parsed.digest !== undefined && (typeof parsed.digest !== "string" || parsed.digest !== trackedDigest(rows))) {
             this.disclose(path, "tracked set fails its own integrity digest (edited in place, or written by something that is not this store) — this scope's history is UNUSABLE until it is repaired");
-            return { corrupt: true, tracked: new Map() };
+            return { corrupt: true, tracked: new Map(), fault: DAMAGED_RECORD };
         }
         return { corrupt: false, tracked: new Map(rows) };
     }
@@ -256,6 +262,10 @@ export class FileFileHistoryStore {
         atomicWriteFile(join(this.base, "tmp"), this.trackedPath(scope), JSON.stringify(doc));
     }
     readBoundary(path) {
+        const read = this.readBoundaryState(path);
+        return read instanceof Map ? read : null;
+    }
+    readBoundaryState(path) {
         let raw;
         try {
             raw = readFileSync(path, "utf8");
@@ -263,33 +273,33 @@ export class FileFileHistoryStore {
         catch (err) {
             if (err.code === "ENOENT")
                 return null;
-            this.disclose(path, `boundary unreadable (${err.code ?? "unknown"}) — read as no boundary`);
-            return null;
+            this.disclose(path, `boundary unreadable (${err.code ?? "unknown"}) — not a usable boundary`);
+            return caughtFault(err);
         }
         {
             const doc = parseJsonRecord(raw);
             if (doc === null) {
-                this.disclose(path, "unparseable boundary (torn/zero-byte write?) — read as no boundary");
-                return null;
+                this.disclose(path, "unparseable boundary (torn/zero-byte write?) — not a usable boundary");
+                return DAMAGED_RECORD;
             }
             if (doc.formatVersion !== "file-history/1" || !Array.isArray(doc.files)) {
-                this.disclose(path, "boundary is not a file-history/1 pair array — read as no boundary");
-                return null;
+                this.disclose(path, "boundary is not a file-history/1 pair array — not a usable boundary");
+                return DAMAGED_RECORD;
             }
             const parsed = { formatVersion: doc.formatVersion, files: doc.files, digest: doc.digest };
             for (const pair of parsed.files) {
                 if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string" || !Number.isInteger(pair[1]) || pair[1] < 1) {
-                    this.disclose(path, "boundary carries a malformed mapping row — read as no boundary");
-                    return null;
+                    this.disclose(path, "boundary carries a malformed mapping row — not a usable boundary");
+                    return DAMAGED_RECORD;
                 }
             }
             if (new Set(parsed.files.map(([k]) => k)).size !== parsed.files.length) {
-                this.disclose(path, "boundary maps the same path twice — read as no boundary");
-                return null;
+                this.disclose(path, "boundary maps the same path twice — not a usable boundary");
+                return DAMAGED_RECORD;
             }
             if (typeof parsed.digest !== "string" || parsed.digest !== boundaryDigest(parsed.files)) {
-                this.disclose(path, "boundary fails its own integrity digest (rows added or dropped?) — read as no boundary");
-                return null;
+                this.disclose(path, "boundary fails its own integrity digest (rows added or dropped?) — not a usable boundary");
+                return DAMAGED_RECORD;
             }
             return new Map(parsed.files);
         }
@@ -304,23 +314,11 @@ export class FileFileHistoryStore {
             return undefined;
         }
     }
-    unjudgeableBoundaryIdsOf(scope) {
-        const dir = this.boundaryDir(scope);
-        let names;
-        try {
-            names = readdirSync(dir);
-        }
-        catch (err) {
-            return err.code === "ENOENT" ? null : [];
-        }
-        const bad = names.filter((f) => f.endsWith(".json") && this.readBoundary(join(dir, f)) === null).map((f) => f.slice(0, -".json".length));
-        return bad.length > 0 ? bad : null;
-    }
     carryConsumedIds(fromScope, toScope) {
         const spent = this.readReapedIds(fromScope);
-        if (spent === null) {
+        if (!(spent instanceof Set)) {
             this.disclose(this.reapedLogPath(fromScope), "source consumed-id ledger unreadable — the adoption is refused rather than published without its lineage's tombstones");
-            return false;
+            return spent;
         }
         if (spent.size === 0)
             return true;
@@ -339,7 +337,7 @@ export class FileFileHistoryStore {
             if (err.code === "ENOENT")
                 return new Set();
             this.disclose(path, `consumed-id ledger unreadable (${err.code ?? "unknown"})`);
-            return null;
+            return caughtFault(err);
         }
         const cached = this.reapedCache.get(scope);
         if (cached !== undefined && cached.size === size)
@@ -354,7 +352,7 @@ export class FileFileHistoryStore {
         }
         catch (err) {
             this.disclose(path, `consumed-id ledger unreadable (${err.code ?? "unknown"})`);
-            return null;
+            return caughtFault(err);
         }
     }
     markReaped(scope, ids) {
@@ -381,7 +379,7 @@ export class FileFileHistoryStore {
         }
         catch (err) {
             this.disclose(path, `consumed-id ledger could not be appended (${err.code ?? "unknown"}) — the boundaries it names are NOT being reaped, so this scope is not bounded until it can be written`);
-            return false;
+            return caughtFault(err);
         }
     }
     boundaryOrderOf(path) {
@@ -409,7 +407,7 @@ export class FileFileHistoryStore {
             const { key, kind, family } = describeTrackKey(root, absPath);
             const before = this.readTrackedState(scope);
             if (before.corrupt)
-                return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" is unreadable — refusing to mint a first-touch record over an unusable graph` } };
+                return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" is unreadable — refusing to mint a first-touch record over an unusable graph`, ...before.fault } };
             const existing = before.tracked.get(key);
             if (existing !== undefined) {
                 if (existing.observedByLaterTouch !== true) {
@@ -421,7 +419,7 @@ export class FileFileHistoryStore {
             const cap = await captureFileBackupViaEnv(env, absPath, root, signal);
             const after = this.readTrackedState(scope);
             if (after.corrupt)
-                return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" became unreadable during the first-touch capture — nothing was recorded` } };
+                return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" became unreadable during the first-touch capture — nothing was recorded`, ...after.fault } };
             const tracked = after.tracked;
             const raced = tracked.get(key);
             if (raced !== undefined) {
@@ -452,7 +450,7 @@ export class FileFileHistoryStore {
             return { ok: true, minted: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async annulTrack(scope, absPath, root, verify) {
@@ -460,13 +458,16 @@ export class FileFileHistoryStore {
             const key = trackKeyOf(root, absPath);
             const state = this.readTrackedState(scope);
             if (state.corrupt) {
-                return { ok: false, error: { code: "conflict", message: `file history for scope "${scope}" is unreadable — the first-touch record (if any) was left in place; repair the graph before retraction can be judged` } };
+                return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" is unreadable — the first-touch record (if any) was left in place; repair the graph before retraction can be judged`, ...state.fault } };
             }
             const tracked = state.tracked;
             const rec = tracked.get(key);
             if (rec === undefined)
                 return { ok: true };
-            for (const entryId of this.listBoundaryIds(scope)) {
+            const listed = this.listBoundaryIds(scope);
+            if (!Array.isArray(listed))
+                return { ok: false, error: { code: "track_failed", message: `scope "${scope}" has ${listed.what} — the first-touch record for ${absPath} was left in place, since whether a boundary references it cannot be judged`, ...listed.fault } };
+            for (const entryId of listed) {
                 const bp = this.tryBoundaryPath(scope, entryId);
                 const mapping = bp === null ? null : this.readBoundary(bp);
                 if (mapping?.has(key) === true) {
@@ -480,12 +481,11 @@ export class FileFileHistoryStore {
                 return { ok: false, error: { code: "conflict", message: `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` } };
             }
             const proof = verify === undefined ? undefined : await worldStillMatchesMint(verify.env, absPath, root, rec.baseAvailable, rec.versions[0]?.blobHash ?? null, verify.signal);
-            if (proof !== undefined && !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` } };
-            }
+            if (proof !== undefined && proof.verdict !== "unchanged")
+                return annulProofFailure(proof, absPath);
             const fresh = this.readTrackedState(scope);
             if (fresh.corrupt)
-                return { ok: false, error: { code: "conflict", message: `file history for scope "${scope}" became unreadable — the record was left in place` } };
+                return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" became unreadable — the record was left in place`, ...fresh.fault } };
             const still = fresh.tracked.get(key);
             if (still === undefined)
                 return { ok: true };
@@ -495,7 +495,10 @@ export class FileFileHistoryStore {
             if (still.mintId !== rec.mintId || still.baseAvailable !== rec.baseAvailable || still.versions.length !== rec.versions.length || still.versions[0]?.blobHash !== rec.versions[0]?.blobHash || still.versions[0]?.backupTime !== rec.versions[0]?.backupTime) {
                 return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} was replaced while this retraction was being proven — the record now there belongs to a newer edit` } };
             }
-            for (const entryId of this.listBoundaryIds(scope)) {
+            const relisted = this.listBoundaryIds(scope);
+            if (!Array.isArray(relisted))
+                return { ok: false, error: { code: "track_failed", message: `scope "${scope}" came to have ${relisted.what} while this retraction was being proven — the record was left in place`, ...relisted.fault } };
+            for (const entryId of relisted) {
                 const bp2 = this.tryBoundaryPath(scope, entryId);
                 const mapping2 = bp2 === null ? null : this.readBoundary(bp2);
                 if (mapping2?.has(key) === true) {
@@ -507,53 +510,65 @@ export class FileFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "track_failed", message: `annulling the first-touch record for ${absPath} failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "track_failed", message: `annulling the first-touch record for ${absPath} failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     scopeIsEmptySync(scope) {
         const state = this.readTrackedState(scope);
         if (state.corrupt)
-            return false;
-        return state.tracked.size === 0 && this.listBoundaryIds(scope).length === 0;
+            return { fault: state.fault, what: "an unreadable tracked set" };
+        const listed = this.listBoundaryIds(scope);
+        if (!Array.isArray(listed))
+            return listed;
+        return state.tracked.size === 0 && listed.length === 0 ? "empty" : "not_empty";
+    }
+    async importTargetOf(scope, data, when) {
+        const emptiness = this.scopeIsEmptySync(scope);
+        if (emptiness === "empty")
+            return "empty";
+        if (emptiness !== "not_empty") {
+            return { ok: false, error: { code: "adopt_failed", message: `importHistory target "${scope}" ${when === "before" ? "has" : "came to have"} ${emptiness.what} — a scope whose history cannot be judged is not an empty target; nothing was ${when === "before" ? "fetched or " : ""}published`, ...emptiness.fault } };
+        }
+        const existing = await this.exportHistory(scope);
+        if (existing.ok && existing.history !== null && fileHistoryExportDigest(existing.history) === fileHistoryExportDigest(data))
+            return "identical";
+        const message = when === "before"
+            ? `importHistory target "${scope}" was judged not empty and not this envelope — it holds a DIFFERENT history, or it changed (or could not be read) between the two reads that judge it — 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)`
+            : `importHistory target "${scope}" changed while this import was fetching blobs — it gained a DIFFERENT history, or changed (or could not be read) between the two reads that judge it — nothing was published`;
+        return { ok: false, error: { code: "conflict", message } };
     }
     publishStagedScopeSync(scope, staging) {
-        if (!this.scopeIsEmptySync(scope))
-            return "not_empty";
-        const target = this.scopeDir(scope);
-        const destroyed = [];
-        for (const f of (() => {
-            try {
-                return readdirSync(this.boundaryDir(scope));
-            }
-            catch {
-                return [];
-            }
-        })()) {
-            if (f.endsWith(".json"))
-                destroyed.push(f.slice(0, -".json".length));
-        }
-        if (!this.markReaped(scope, destroyed))
-            return "ledger_failed";
-        safeRm(target);
-        renameSync(staging, target);
+        const emptiness = this.scopeIsEmptySync(scope);
+        if (emptiness !== "empty")
+            return emptiness;
+        safeRm(this.scopeDir(scope));
+        renameSync(staging, this.scopeDir(scope));
         return "published";
     }
     listBoundaryIds(scope) {
         const dir = this.boundaryDir(scope);
-        let entries;
+        let names;
         try {
-            entries = readdirSync(dir);
+            names = readdirSync(dir).filter((f) => f.endsWith(".json"));
         }
         catch (err) {
-            if (err.code !== "ENOENT") {
-                this.disclose(dir, `boundary directory unreadable (${err.code ?? "unknown"}) — listed as no boundaries`);
-            }
-            return [];
-        }
-        return entries
-            .filter((f) => f.endsWith(".json"))
-            .filter((f) => this.readBoundary(join(dir, f)) !== null)
-            .map((f) => f.slice(0, -".json".length));
+            if (err.code === "ENOENT")
+                return [];
+            this.disclose(dir, `boundary directory unreadable (${err.code ?? "unknown"}) — this scope's history cannot be judged until it can be listed`);
+            return { fault: caughtFault(err), what: "a boundary directory that cannot be listed" };
+        }
+        const ids = [];
+        const unusable = [];
+        const faults = [];
+        for (const f of names) {
+            const read = this.readBoundaryState(join(dir, f));
+            (read instanceof Map ? ids : unusable).push(f.slice(0, -".json".length));
+            if (!(read instanceof Map))
+                faults.push(read ?? {});
+        }
+        if (unusable.length === 0)
+            return ids;
+        return { fault: worstFault(faults), what: `boundaries that cannot be used (${unusable.slice(0, 3).map((i) => JSON.stringify(i)).join(", ")}${unusable.length > 3 ? ", …" : ""})` };
     }
     async snapshot(scope, entryId, env, root, signal) {
         const bpath = this.tryBoundaryPath(scope, entryId);
@@ -562,8 +577,8 @@ export class FileFileHistoryStore {
         if (this.readBoundary(bpath) !== null)
             return { ok: true };
         const consumed = this.readReapedIds(scope);
-        if (consumed === null) {
-            return { ok: false, error: { code: "snapshot_failed", message: `the consumed-entry ledger for scope "${scope}" cannot be read — refusing to mint a boundary while it is impossible to tell a fresh entry id from one retention already reaped` } };
+        if (!(consumed instanceof Set)) {
+            return { ok: false, error: { code: "snapshot_failed", message: `the consumed-entry ledger for scope "${scope}" cannot be read — refusing to mint a boundary while it is impossible to tell a fresh entry id from one retention already reaped`, ...consumed } };
         }
         if (consumed.has(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` } };
@@ -582,7 +597,7 @@ export class FileFileHistoryStore {
             const state = this.readTrackedState(scope);
             if (state.corrupt) {
                 nestedSetAdd(this.spentAttempts, scope, entryId);
-                return { ok: false, error: { code: "snapshot_failed", message: `file history for scope "${scope}" is unreadable — a boundary minted over an unusable graph would claim to restore state that is not there` } };
+                return { ok: false, error: { code: "snapshot_failed", message: `file history for scope "${scope}" is unreadable — a boundary minted over an unusable graph would claim to restore state that is not there`, ...state.fault } };
             }
             const tracked = state.tracked;
             const staged = new Map();
@@ -628,7 +643,7 @@ export class FileFileHistoryStore {
             const currentState = this.readTrackedState(scope);
             if (currentState.corrupt) {
                 nestedSetAdd(this.spentAttempts, scope, entryId);
-                return { ok: false, error: { code: "snapshot_failed", message: `file history for scope "${scope}" became unreadable during the capture — no boundary was published` } };
+                return { ok: false, error: { code: "snapshot_failed", message: `file history for scope "${scope}" became unreadable during the capture — no boundary was published`, ...currentState.fault } };
             }
             const current = currentState.tracked;
             for (const [key, cap] of staged) {
@@ -663,9 +678,10 @@ export class FileFileHistoryStore {
             catch (err) {
                 if (err.code !== "EEXIST")
                     throw err;
-                if (this.readBoundary(bpath) === null) {
+                const existing = this.readBoundaryState(bpath);
+                if (!(existing instanceof Map)) {
                     nestedSetAdd(this.spentAttempts, scope, entryId);
-                    return { ok: false, error: { code: "snapshot_failed", message: `a boundary file for entry "${entryId}" already exists but cannot be read — this turn has no usable boundary (the unreadable file is left in place for an operator rather than silently replaced)` } };
+                    return { ok: false, error: { code: "snapshot_failed", message: `a boundary file for entry "${entryId}" already exists but cannot be read — this turn has no usable boundary (the unreadable file is left in place for an operator rather than silently replaced)`, ...existing } };
                 }
             }
             this.applyBoundaryRetention(scope, entryId);
@@ -673,7 +689,7 @@ export class FileFileHistoryStore {
         }
         catch (err) {
             nestedSetAdd(this.spentAttempts, scope, entryId);
-            return { ok: false, error: { code: "snapshot_failed", message: `boundary for entry "${entryId}" could not be committed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "snapshot_failed", message: `boundary for entry "${entryId}" could not be committed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
         finally {
             this.activeCaptures.get(scope)?.delete(entryId);
@@ -685,13 +701,16 @@ export class FileFileHistoryStore {
         let modeNotPreserved = 0;
         try {
             const bpath = this.tryBoundaryPath(scope, entryId);
-            const boundary = bpath === null ? null : this.readBoundary(bpath);
+            const boundary = bpath === null ? null : this.readBoundaryState(bpath);
             if (boundary === null) {
                 return { outcome: "failed", ...ledger, error: { code: "not_found", message: `no history boundary for entry "${entryId}"` } };
             }
+            if (!(boundary instanceof Map)) {
+                return { outcome: "failed", ...ledger, error: { code: "restore_failed", message: `the history boundary for entry "${entryId}" is there but cannot be used — NOTHING was restored`, ...boundary } };
+            }
             const state = this.readTrackedState(scope);
             if (state.corrupt) {
-                return { outcome: "failed", ...ledger, error: { code: "restore_failed", message: `file history for scope "${scope}" is unreadable — the boundary exists but its version records cannot be read, so NOTHING was restored` } };
+                return { outcome: "failed", ...ledger, error: { code: "restore_failed", message: `file history for scope "${scope}" is unreadable — the boundary exists but its version records cannot be read, so NOTHING was restored`, ...state.fault } };
             }
             const tracked = state.tracked;
             for (const key of [...tracked.keys()].sort()) {
@@ -703,7 +722,7 @@ export class FileFileHistoryStore {
                 let targetVersion = boundary.get(key);
                 if (targetVersion === undefined) {
                     if (!rec.baseAvailable) {
-                        ledger.refused.push({ path: key, reason: "base_unavailable" });
+                        ledger.refused.push({ path: key, reason: "base_unavailable", class: "base_unavailable" });
                         continue;
                     }
                     targetVersion = 1;
@@ -715,7 +734,7 @@ export class FileFileHistoryStore {
                 }
                 const resolved = resolveTrackKey(root, key, descriptorOf(rec));
                 if (!resolved.ok) {
-                    ledger.refused.push({ path: key, reason: resolved.reason });
+                    ledger.refused.push({ path: key, reason: resolved.reason, class: resolved.class });
                     continue;
                 }
                 let target;
@@ -757,7 +776,7 @@ export class FileFileHistoryStore {
                 else if (applied.outcome === "identical")
                     ledger.identicalSkipped.push(key);
                 else if (applied.outcome === "refused")
-                    ledger.refused.push({ path: key, reason: applied.reason });
+                    ledger.refused.push({ path: key, reason: applied.reason, class: applied.class });
                 else
                     ledger.failed.push({ path: key, reason: applied.reason });
                 if ((applied.outcome === "applied" || applied.outcome === "identical") && applied.modeNotPreserved === true)
@@ -767,7 +786,7 @@ export class FileFileHistoryStore {
         }
         catch (err) {
             const touched = ledger.filesChanged.length > 0 || ledger.identicalSkipped.length > 0 || ledger.refused.length > 0 || ledger.failed.length > 0;
-            return { outcome: touched ? "partial" : "failed", ...ledger, error: { code: "restore_failed", message: thrownText(err) } };
+            return { outcome: touched ? "partial" : "failed", ...ledger, error: { code: "restore_failed", message: thrownText(err), ...caughtFault(err) } };
         }
     }
     async canRestore(scope, entryId) {
@@ -854,7 +873,7 @@ export class FileFileHistoryStore {
             const id = file.slice(0, -".json".length);
             if (keep.has(id))
                 continue;
-            if (!this.markReaped(scope, [id])) {
+            if (this.markReaped(scope, [id]) !== true) {
                 survivors.add(id);
                 continue;
             }
@@ -1006,28 +1025,25 @@ export class FileFileHistoryStore {
         try {
             if (fromScope === toScope)
                 return { ok: true };
-            const targetState = this.readTrackedState(toScope);
-            if (targetState.corrupt) {
-                return { ok: false, error: { code: "adopt_failed", message: `adoptScope target "${toScope}" has an unreadable tracked set — a scope whose bytes cannot be judged is not an empty target` } };
-            }
-            const targetTracked = targetState.tracked;
-            const targetBoundaries = this.listBoundaryIds(toScope);
-            if (targetTracked.size > 0 || targetBoundaries.length > 0) {
+            const target = this.scopeIsEmptySync(toScope);
+            if (target === "not_empty") {
                 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 (target !== "empty")
+                return { ok: false, error: { code: "adopt_failed", message: `adoptScope target "${toScope}" has ${target.what} — a scope whose history cannot be judged is not an empty target; nothing was published`, ...target.fault } };
             const sourceState = this.readTrackedState(fromScope);
             if (sourceState.corrupt) {
-                return { ok: false, error: { code: "adopt_failed", message: `adoptScope source "${fromScope}" has an unreadable tracked set — adopting it would publish boundaries with no version records behind them` } };
+                return { ok: false, error: { code: "adopt_failed", message: `adoptScope source "${fromScope}" has an unreadable tracked set — adopting it would publish boundaries with no version records behind them`, ...sourceState.fault } };
             }
             const source = sourceState.tracked;
-            const unjudgeable = this.unjudgeableBoundaryIdsOf(fromScope);
-            if (unjudgeable !== null) {
-                return { ok: false, error: { code: "adopt_failed", message: `adoptScope source "${fromScope}" has ${unjudgeable.length > 0 ? `boundaries that cannot be judged (${unjudgeable.slice(0, 3).map((i) => JSON.stringify(i)).join(", ")}${unjudgeable.length > 3 ? ", …" : ""})` : "a boundary directory that cannot be listed"} — adopting it would publish a graph that silently drops those turns and hands their entry ids back to the fork; nothing was published` } };
-            }
             const sourceBoundaries = this.listBoundaryIds(fromScope);
+            if (!Array.isArray(sourceBoundaries)) {
+                return { ok: false, error: { code: "adopt_failed", message: `adoptScope source "${fromScope}" has ${sourceBoundaries.what} — adopting it would publish a graph that silently drops those turns and hands their entry ids back to the fork; nothing was published`, ...sourceBoundaries.fault } };
+            }
             if (source.size === 0 && sourceBoundaries.length === 0) {
-                if (!this.carryConsumedIds(fromScope, toScope)) {
-                    return { ok: false, error: { code: "adopt_failed", message: `adoptScope could not carry the consumed-entry ledger from "${fromScope}" to "${toScope}" — refusing rather than reporting a carry that would let an already-consumed entry id be minted again in the fork` } };
+                const carried = this.carryConsumedIds(fromScope, toScope);
+                if (carried !== true) {
+                    return { ok: false, error: { code: "adopt_failed", message: `adoptScope could not carry the consumed-entry ledger from "${fromScope}" to "${toScope}" — refusing rather than reporting a carry that would let an already-consumed entry id be minted again in the fork`, ...carried } };
                 }
                 return { ok: true };
             }
@@ -1035,15 +1051,16 @@ export class FileFileHistoryStore {
                 for (const v of rec.versions) {
                     if (v.blobHash === null)
                         continue;
-                    let bytes;
+                    let fault;
                     try {
-                        bytes = readFileSync(this.blobPath(v.blobHash));
+                        if (createHash("sha256").update(readFileSync(this.blobPath(v.blobHash))).digest("hex") !== v.blobHash)
+                            fault = DAMAGED_RECORD;
                     }
-                    catch {
-                        bytes = undefined;
+                    catch (err) {
+                        fault = err.code === "ENOENT" ? DAMAGED_RECORD : caughtFault(err);
                     }
-                    if (bytes === undefined || createHash("sha256").update(bytes).digest("hex") !== v.blobHash) {
-                        return { ok: false, error: { code: "adopt_failed", message: `adoptScope source "${fromScope}" references blob ${v.blobHash} for ${key}@v${v.version}, which is missing or fails content-address integrity — nothing was published` } };
+                    if (fault !== undefined) {
+                        return { ok: false, error: { code: "adopt_failed", message: `adoptScope source "${fromScope}" references blob ${v.blobHash} for ${key}@v${v.version}, which is missing or fails content-address integrity — nothing was published`, ...fault } };
                     }
                 }
             }
@@ -1068,16 +1085,17 @@ export class FileFileHistoryStore {
                     const bdoc = { formatVersion: "file-history/1", files: [...mapping], digest: boundaryDigest([...mapping]), ...(sourceCommittedAt !== undefined ? { committedAt: sourceCommittedAt } : {}) };
                     atomicWriteFile(join(this.base, "tmp"), join(staging, "boundaries", `${historyPathComponent(id)}.json`), JSON.stringify(bdoc));
                 }
-                if (!this.carryConsumedIds(fromScope, toScope)) {
+                const carried = this.carryConsumedIds(fromScope, toScope);
+                if (carried !== true) {
                     safeRm(staging);
-                    return { ok: false, error: { code: "adopt_failed", message: `adoptScope could not carry the consumed-entry ledger from "${fromScope}" to "${toScope}" — nothing was published, because a fork missing its lineage's tombstones can mint an already-consumed entry id` } };
+                    return { ok: false, error: { code: "adopt_failed", message: `adoptScope could not carry the consumed-entry ledger from "${fromScope}" to "${toScope}" — nothing was published, because a fork missing its lineage's tombstones can mint an already-consumed entry id`, ...carried } };
                 }
                 const published = this.publishStagedScopeSync(toScope, staging);
                 if (published !== "published") {
                     safeRm(staging);
                     return published === "not_empty"
                         ? { ok: false, error: { code: "conflict", message: `adoptScope target "${toScope}" gained history of its own while this adoption was being staged — nothing was published` } }
-                        : { ok: false, error: { code: "adopt_failed", message: `adoptScope could not record the consumed-entry tombstones for target "${toScope}"'s unreadable boundary residue — nothing was published, because replacing records nothing remembers would hand their already-consumed entry ids back to the fork` } };
+                        : { ok: false, error: { code: "adopt_failed", message: `adoptScope target "${toScope}" came to have ${published.what} while this adoption was being staged — a scope whose history cannot be judged is not an empty target; nothing was published`, ...published.fault } };
                 }
             }
             catch (err) {
@@ -1087,27 +1105,29 @@ export class FileFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "adopt_failed", message: `adoptScope failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "adopt_failed", message: `adoptScope failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async exportHistory(scope) {
+        const unexportable = (what, fault) => ({ ok: false, error: { code: "adopt_failed", message: `exportHistory scope "${scope}" has ${what} — its history cannot be exported whole, so nothing was exported`, ...fault } });
         const state = this.readTrackedState(scope);
-        if (state.corrupt) {
-            return null;
-        }
+        if (state.corrupt)
+            return unexportable("an unreadable tracked set", state.fault);
         const tracked = state.tracked;
         const boundaryIds = this.listBoundaryIds(scope);
+        if (!Array.isArray(boundaryIds))
+            return unexportable(boundaryIds.what, boundaryIds.fault);
         if (tracked.size === 0 && boundaryIds.length === 0)
-            return null;
+            return { ok: true, history: null };
         const boundaries = [];
         for (const entryId of [...boundaryIds].sort()) {
             const bp = this.tryBoundaryPath(scope, entryId);
             const mapping = bp === null ? null : this.readBoundary(bp);
             if (mapping === null)
-                continue;
+                return unexportable(`a boundary ("${entryId}") that stopped being usable while it was exported`, {});
             boundaries.push({ entryId, files: [...mapping.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([relOrAbsPath, version]) => ({ relOrAbsPath, version })) });
         }
-        return {
+        const history = {
             formatVersion: "file-history/1",
             tracked: [...tracked.entries()]
                 .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
@@ -1120,20 +1140,17 @@ export class FileFileHistoryStore {
             })),
             boundaries,
         };
+        return { ok: true, history };
     }
     async importHistory(scope, data, srcGetBlob) {
         try {
             const shaped = validateFileHistoryExport(data);
             if (!shaped.ok)
                 return shaped;
-            const existing = await this.exportHistory(scope);
-            let identicalRepublish = false;
-            if (existing !== null) {
-                if (fileHistoryExportDigest(existing) === fileHistoryExportDigest(data))
-                    identicalRepublish = true;
-                else
-                    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 target = await this.importTargetOf(scope, data, "before");
+            if (typeof target === "object")
+                return target;
+            const identicalRepublish = target === "identical";
             const importJournal = join(this.scopeDir(scope), "staging", `import-${Date.now().toString(36)}-${randomBytes(6).toString("hex")}.jsonl`);
             ensureDir(join(this.scopeDir(scope), "staging"));
             appendFileSync(importJournal, `${JSON.stringify({ entryId: `import:${scope}`, pid: process.pid, startedAt: new Date().toISOString() })}\n`);
@@ -1147,7 +1164,7 @@ export class FileFileHistoryStore {
             return await this.runImport(scope, data, srcGetBlob, importJournal, identicalRepublish);
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async runImport(scope, data, srcGetBlob, importJournal, identicalRepublish) {
@@ -1174,10 +1191,10 @@ export class FileFileHistoryStore {
                         bytes = await srcGetBlob(v.blobHash);
                     }
                     catch (err) {
-                        return { ok: false, error: { code: "unsupported_format", message: `source blob ${v.blobHash} fetch failed: ${thrownText(err)}` } };
+                        return { ok: false, error: { code: "unsupported_format", message: `source blob ${v.blobHash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
                     }
                     if (bytes === undefined)
-                        return { ok: false, error: { code: "not_found", message: `source blob ${v.blobHash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
+                        return { ok: false, error: { code: "adopt_failed", message: `source blob ${v.blobHash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
                     if (createHash("sha256").update(bytes).digest("hex") !== v.blobHash) {
                         return { ok: false, error: { code: "unsupported_format", message: `source blob ${v.blobHash} fails content-address integrity — refused, nothing published` } };
                     }
@@ -1186,12 +1203,11 @@ export class FileFileHistoryStore {
             }
             if (identicalRepublish)
                 return { ok: true };
-            const now = await this.exportHistory(scope);
-            if (now !== null) {
-                if (fileHistoryExportDigest(now) === fileHistoryExportDigest(data))
-                    return { ok: true };
-                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 = await this.importTargetOf(scope, data, "after");
+            if (now === "identical")
+                return { ok: true };
+            if (now !== "empty")
+                return now;
             const staging = `${this.scopeDir(scope)}.importing-${process.pid}-${randomBytes(6).toString("hex")}`;
             safeRm(staging);
             try {
@@ -1218,13 +1234,13 @@ export class FileFileHistoryStore {
                 }
                 catch (err) {
                     safeRm(staging);
-                    return { ok: false, error: { code: "adopt_failed", message: `importHistory could not publish the staged graph for "${scope}": ${thrownText(err)} — nothing was published (a local storage fault, not a malformed envelope)` } };
+                    return { ok: false, error: { code: "adopt_failed", message: `importHistory could not publish the staged graph for "${scope}": ${thrownText(err)} — nothing was published (a local storage fault, not a malformed envelope)`, ...caughtFault(err) } };
                 }
                 if (published !== "published") {
                     safeRm(staging);
                     return published === "not_empty"
                         ? { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" gained history of its own while this import was being staged — nothing was published` } }
-                        : { ok: false, error: { code: "adopt_failed", message: `importHistory could not record the consumed-entry tombstones for target "${scope}"'s unreadable boundary residue — nothing was published, because replacing records nothing remembers would hand their already-consumed entry ids back to this scope` } };
+                        : { ok: false, error: { code: "adopt_failed", message: `importHistory target "${scope}" came to have ${published.what} while this import was being staged — a scope whose history cannot be judged is not an empty target; nothing was published`, ...published.fault } };
                 }
             }
             catch (err) {
@@ -1234,7 +1250,7 @@ export class FileFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}` } };
+            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
         finally {
             safeRm(importJournal);