@narumitw/pi-sync 0.51.0 → 0.52.0

package/src/sync/merge-apply.ts

@@ -0,0 +1,380 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { agentDir } from "../snapshot/session-paths.js";
+import { createSnapshot, snapshotTarget } from "../snapshot/snapshot.js";
+import { preflightSnapshotApply, preflightSnapshotMutations } from "../snapshot/snapshot-apply.js";
+import { sessionStorageRoot } from "../snapshot/snapshot-paths.js";
+import type { Snapshot, SnapshotOptions } from "../snapshot/snapshot-types.js";
+import { syncDirectory } from "../state/json-file.js";
+import { syncMutationParents } from "../state/mutation-directory-sync.js";
+import { mergePathIdentity } from "./file-merge-planner.js";
+import { fileHashMap } from "./sync-state.js";
+
+/** Read-only filesystem applicability check before publishing a combined result. */
+export async function preflightMergedTargets(
+  before: Snapshot,
+  after: Snapshot,
+  options: SnapshotOptions,
+  protectedTarget?: string,
+) {
+  const root = agentDir();
+  const beforeHashes: Record<string, string> = Object.assign(Object.create(null), fileHashMap(before));
+  const afterHashes: Record<string, string> = Object.assign(Object.create(null), fileHashMap(after));
+  const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
+  const changed = new Set(paths.filter((item) => beforeHashes[item] !== afterHashes[item]));
+  await assertCanonicalMergedTargets(root, changed, options);
+  await assertDistinctMergedTargets(root, paths, changed, options, protectedTarget, new Set(Object.keys(afterHashes)));
+  const removed = replacementPaths(
+    new Set(paths.filter((item) => changed.has(item) && !afterHashes[item])),
+    afterHashes,
+  );
+  const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
+  for (const relative of paths) {
+    if (changed.has(relative)) await assertFilesystemTarget(root, relative, options, removedTargets, beforeHashes);
+  }
+}
+
+function replacementPaths(removed: Set<string>, afterHashes: Readonly<Record<string, string>>) {
+  for (const relative of [...removed]) {
+    let parent = path.posix.dirname(relative);
+    while (parent !== ".") {
+      if (afterHashes[parent]) {
+        for (
+          let directory = path.posix.dirname(relative);
+          directory !== parent;
+          directory = path.posix.dirname(directory)
+        )
+          removed.add(directory);
+        removed.add(parent);
+        break;
+      }
+      parent = path.posix.dirname(parent);
+    }
+  }
+  return removed;
+}
+
+/** Snapshot collection canonicalizes top-level names, but merged journals own exact physical paths. */
+async function assertCanonicalMergedTargets(root: string, changed: Iterable<string>, options: SnapshotOptions) {
+  const topLevel = new Map(
+    [...changed].filter((relative) => !relative.includes("/")).map((relative) => [relative.toLowerCase(), relative]),
+  );
+  if (topLevel.size === 0) return;
+  options.signal?.throwIfAborted();
+  options.validateMutation?.();
+  let names: string[];
+  try {
+    names = await fs.readdir(root);
+  } catch (error) {
+    options.signal?.throwIfAborted();
+    options.validateMutation?.();
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    return;
+  }
+  options.signal?.throwIfAborted();
+  options.validateMutation?.();
+  for (const name of names) {
+    const canonical = topLevel.get(name.toLowerCase());
+    if (canonical !== undefined && name !== canonical)
+      throw new Error(
+        "Merged target has a noncanonical case variant; normalize selected top-level file spelling before retrying. Journal retained if already committed.",
+      );
+  }
+}
+
+/** Even an unchanged virtual alias must not describe different bytes for a changed physical file. */
+async function assertDistinctMergedTargets(
+  root: string,
+  paths: string[],
+  changed: ReadonlySet<string>,
+  options: SnapshotOptions,
+  protectedTarget?: string,
+  finalPaths: ReadonlySet<string> = new Set(paths),
+) {
+  const protectedKey = protectedTarget
+    ? mergePathIdentity(await resolvedTargetIdentity(path.resolve(protectedTarget), options))
+    : undefined;
+  options.signal?.throwIfAborted();
+  options.validateMutation?.();
+  const keys = new Map<string, string>();
+  for (const relative of paths) {
+    options.signal?.throwIfAborted();
+    const target = snapshotTarget(root, relative, options.sessionDir);
+    const key = mergePathIdentity(await resolvedTargetIdentity(target, options));
+    options.signal?.throwIfAborted();
+    options.validateMutation?.();
+    const existing = keys.get(key);
+    if (
+      existing &&
+      (mergePathIdentity(existing) !== mergePathIdentity(relative) ||
+        (finalPaths.has(existing) && finalPaths.has(relative)))
+    )
+      throw new Error("Merged paths resolve to the same file; reviewed directional recovery is required.");
+    if (key === protectedKey && changed.has(relative))
+      throw new Error("A merged transfer targets the current session; review is required.");
+    keys.set(key, relative);
+  }
+}
+
+async function assertReviewedTree(directory: string, relative: string, beforeHashes: Readonly<Record<string, string>>) {
+  for (const name of await fs.readdir(directory)) {
+    const child = path.join(directory, name);
+    const childRelative = `${relative}/${name}`;
+    const stat = await fs.lstat(child);
+    if (stat.isDirectory()) {
+      await assertReviewedTree(child, childRelative, beforeHashes);
+    } else if (
+      stat.isFile() &&
+      stat.nlink === 1 &&
+      beforeHashes[childRelative] ===
+        createHash("sha256")
+          .update(await fs.readFile(child))
+          .digest("hex")
+    ) {
+      continue;
+    } else {
+      throw new Error("Reviewed directory contains unknown or changed files; publication refused.");
+    }
+  }
+}
+
+function hasBlockingFileAncestor(target: string, files: ReadonlySet<string>) {
+  for (let parent = path.dirname(target); parent !== path.dirname(parent); parent = path.dirname(parent))
+    if (files.has(parent)) return true;
+  return false;
+}
+
+async function resolvedTargetIdentity(target: string, options: SnapshotOptions) {
+  // Resolve the nearest existing ancestor too: roots may alias even when a target is absent.
+  let ancestor = target;
+  while (true) {
+    options.signal?.throwIfAborted();
+    try {
+      const resolved = await fs.realpath(ancestor);
+      return path.resolve(resolved, path.relative(ancestor, target));
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) return target;
+      ancestor = parent;
+    }
+  }
+}
+
+async function assertFilesystemTarget(
+  root: string,
+  relative: string,
+  options: SnapshotOptions,
+  removedTargets: ReadonlySet<string> = new Set(),
+  beforeHashes?: Readonly<Record<string, string>>,
+) {
+  const target = snapshotTarget(root, relative, options.sessionDir);
+  const boundary =
+    relative.startsWith("sessions/") && options.sessionDir
+      ? path.resolve(sessionStorageRoot(root, options.sessionDir))
+      : path.resolve(root);
+  for (
+    let parent = path.dirname(target);
+    mergePathIdentity(parent) !== mergePathIdentity(boundary);
+    parent = path.dirname(parent)
+  ) {
+    options.signal?.throwIfAborted();
+    if (path.dirname(parent) === parent) throw new Error("Unowned merged target.");
+    try {
+      const stat = await fs.lstat(parent);
+      if (
+        (!stat.isDirectory() || stat.isSymbolicLink()) &&
+        !(stat.isFile() && stat.nlink === 1 && removedTargets.has(parent))
+      )
+        throw new Error("Unsafe merge filesystem layout; review the selected paths before transfer.");
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT") throw error;
+    }
+  }
+  options.signal?.throwIfAborted();
+  try {
+    const stat = await fs.lstat(target);
+    if ((!stat.isFile() && !removedTargets.has(target)) || (stat.isFile() && stat.nlink > 1))
+      throw new Error("Merge target is non-regular or hard-linked; review a directional operation before transfer.");
+    if (stat.isDirectory() && beforeHashes) await assertReviewedTree(target, relative, beforeHashes);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT" && !(code === "ENOTDIR" && removedTargets.size > 0)) throw error;
+  }
+}
+
+/** Roll forward only while each target is still its reviewed preimage or committed postimage. */
+export async function applyMergedSnapshot(
+  before: Snapshot,
+  after: Snapshot,
+  protectedPaths: Set<string>,
+  options: SnapshotOptions,
+  validate: () => Promise<void>,
+  protectedTarget?: string,
+) {
+  const root = agentDir();
+  const beforeHashes: Record<string, string> = Object.assign(Object.create(null), fileHashMap(before));
+  const afterHashes: Record<string, string> = Object.assign(Object.create(null), fileHashMap(after));
+  const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
+  const replacements = replacementPaths(
+    new Set(paths.filter((item) => beforeHashes[item] && !afterHashes[item])),
+    afterHashes,
+  );
+  const intermediateDirectories = [...replacements].filter((item) => !beforeHashes[item] && !afterHashes[item]);
+  const changed = [
+    ...new Set([...paths.filter((item) => beforeHashes[item] !== afterHashes[item]), ...intermediateDirectories]),
+  ].sort();
+  const protectedKeys = new Set([...protectedPaths].map(mergePathIdentity));
+  if (changed.some((item) => protectedKeys.has(mergePathIdentity(item)))) {
+    throw new Error("A merged transfer targets the current session; review is required.");
+  }
+  // Exact file queues, not a directory pseudo-lock: Pi edit/write tools use these keys.
+  const targets = changed.map((item) => snapshotTarget(root, item, options.sessionDir));
+  const relativeByTarget = new Map(targets.map((target, index) => [target, changed[index]]));
+  const targetSet = new Set(targets);
+  await assertDistinctMergedTargets(
+    root,
+    paths,
+    new Set(changed),
+    options,
+    protectedTarget,
+    new Set(Object.keys(afterHashes)),
+  );
+  async function acquire(index: number): Promise<void> {
+    const target = targets[index];
+    if (target) return withFileMutationQueue(target, () => acquire(index + 1));
+    await validate();
+    await assertCanonicalMergedTargets(root, changed, options);
+    await validate();
+    const current = await createSnapshot(before.profile, options);
+    const currentHashes: Record<string, string> = Object.assign(Object.create(null), fileHashMap(current));
+    const blockingFiles = new Set(
+      paths
+        .filter(
+          (relative) =>
+            (beforeHashes[relative] && !afterHashes[relative]) ||
+            (afterHashes[relative] && currentHashes[relative] === afterHashes[relative]),
+        )
+        .map((relative) => snapshotTarget(root, relative, options.sessionDir)),
+    );
+    for (const item of changed) {
+      if (currentHashes[item] !== beforeHashes[item] && currentHashes[item] !== afterHashes[item]) {
+        throw new Error(
+          "Local content changed during merged transfer; journal retained for review. No newer bytes were replaced.",
+        );
+      }
+      const target = snapshotTarget(root, item, options.sessionDir);
+      try {
+        const stat = await fs.lstat(target);
+        if ((!stat.isFile() && !stat.isDirectory()) || (stat.isFile() && stat.nlink > 1))
+          throw new Error("Merged transfer target is no longer an independent regular file.");
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT" && !(code === "ENOTDIR" && hasBlockingFileAncestor(target, blockingFiles))) throw error;
+      }
+    }
+    const plan = preflightSnapshotApply(root, after, current, options);
+    plan.writes = plan.writes.filter((item) => targetSet.has(item.target));
+    plan.deletes = plan.deletes.filter((target) => targetSet.has(target));
+    await preflightSnapshotMutations(root, plan, options.sessionDir, options);
+    const deletedTargets = new Set(plan.deletes);
+    for (const relative of intermediateDirectories) {
+      for (let parent = path.posix.dirname(relative); parent !== "."; parent = path.posix.dirname(parent)) {
+        if (afterHashes[parent] && deletedTargets.has(snapshotTarget(root, parent, options.sessionDir))) {
+          plan.deletes.push(snapshotTarget(root, relative, options.sessionDir));
+          break;
+        }
+      }
+    }
+    // A parent must remain until every reviewed leaf and intermediate directory is gone.
+    plan.deletes.sort(
+      (left, right) => right.split(path.sep).length - left.split(path.sep).length || left.localeCompare(right),
+    );
+    const removed = replacementPaths(
+      new Set(paths.filter((relative) => deletedTargets.has(snapshotTarget(root, relative, options.sessionDir)))),
+      afterHashes,
+    );
+    const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
+    await assertCanonicalMergedTargets(root, changed, options);
+    await validate();
+    const revalidateTarget = async (target: string) => {
+      await validate();
+      const relative = relativeByTarget.get(target);
+      if (!relative) throw new Error("Unowned merge target.");
+      await assertFilesystemTarget(root, relative, options, removedTargets, currentHashes);
+      await validate();
+      let hash: string | undefined;
+      try {
+        const stat = await fs.lstat(target);
+        if (stat.isDirectory() && removed.has(relative)) {
+          if ((await fs.readdir(target)).length)
+            throw new Error("Reviewed directory has remaining contents; journal retained for review.");
+        } else {
+          if (!stat.isFile() || stat.nlink > 1)
+            throw new Error("Merged transfer target is no longer an independent regular file.");
+          hash = createHash("sha256")
+            .update(await fs.readFile(target))
+            .digest("hex");
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      options.signal?.throwIfAborted();
+      options.validateMutation?.();
+      if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
+        throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
+    };
+    for (const target of plan.deletes) {
+      await revalidateTarget(target);
+      try {
+        const stat = await fs.lstat(target);
+        await validate();
+        if (stat.isDirectory())
+          await fs.rmdir(target); // Only an empty, reviewed directory may be replaced.
+        else await fs.rm(target, { force: true });
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      await syncDirectory(path.dirname(target));
+    }
+    for (const item of plan.writes) {
+      await validate();
+      const relative = relativeByTarget.get(item.target);
+      if (!relative) throw new Error("Unowned merge write target.");
+      await assertFilesystemTarget(root, relative, options, new Set());
+      await fs.mkdir(path.dirname(item.target), { recursive: true });
+      const temporary = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
+      let mode = 0o600;
+      try {
+        mode = (await fs.stat(item.target)).mode & 0o777;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+      try {
+        const handle = await fs.open(temporary, "wx", mode);
+        try {
+          await handle.writeFile(item.content);
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        await revalidateTarget(item.target);
+        await fs.rename(temporary, item.target);
+        await syncDirectory(path.dirname(item.target));
+      } finally {
+        await fs.rm(temporary, { force: true });
+      }
+    }
+    await syncMutationParents(
+      targets,
+      [root, ...(options.sessionDir ? [sessionStorageRoot(root, options.sessionDir)] : [])],
+      options,
+    );
+    await validate();
+  }
+  await acquire(0);
+}

package/src/sync/merge-journal.ts

@@ -0,0 +1,219 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { RemoteHead } from "../backends/sync-backend.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { Snapshot } from "../snapshot/snapshot-types.js";
+import { readJsonIfExists, syncDirectory, writeJson } from "../state/json-file.js";
+import { statePathForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
+import { planFileMerge } from "./file-merge-planner.js";
+import {
+  portableSnapshot,
+  sameLocalFields,
+  validatePortableSnapshot,
+  validateSnapshotFieldPolicy,
+} from "./local-fields.js";
+import type { PartialProgress } from "./partial-progress.js";
+import { fileHashMap, sameHashes } from "./sync-state.js";
+
+export interface MergeJournal {
+  version: 1;
+  identity: string;
+  before: Snapshot;
+  after: Snapshot;
+  accepted?: Snapshot;
+  progress?: PartialProgress;
+  upload: Snapshot;
+  expectedHead: RemoteHead;
+  committedHead?: RemoteHead;
+  /** No remote publication was attempted; a stale candidate can retire if local preimages remain intact. */
+  applyOnly?: boolean;
+  backup: string;
+  stateIdentity: string;
+  /** Effective collection/apply root; absent legacy evidence cannot authorize session recovery. */
+  sessionRoot?: string;
+  warnings?: string[];
+}
+
+export function mergeJournalIdentity(config: AnySyncConfig, backendIdentity: string) {
+  return JSON.stringify([config.setupName, backendIdentity, [...config.include].sort(), config.localFields ?? null]);
+}
+
+export function mergeJournalPath(config: AnySyncConfig) {
+  return `${statePathForConfig(config)}.merge-journal.json`;
+}
+
+export async function readMergeJournal(config: AnySyncConfig): Promise<MergeJournal | undefined> {
+  let journal: MergeJournal | undefined;
+  try {
+    const stat = await fs.lstat(mergeJournalPath(config));
+    if (!stat.isFile() || stat.size > 384 * 1024 * 1024) throw new Error("Unsafe or oversized journal.");
+    journal = await readJsonIfExists<MergeJournal>(mergeJournalPath(config));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    // A JSON parser error may quote sensitive journal contents; do not retain it in a public error.
+    throw new Error("Cannot read the private merge journal; preserve it and review recovery.");
+  }
+  if (!journal) return;
+  if (
+    journal.version !== 1 ||
+    typeof journal.identity !== "string" ||
+    typeof journal.backup !== "string" ||
+    typeof journal.stateIdentity !== "string" ||
+    (journal.applyOnly !== undefined &&
+      (journal.applyOnly !== true ||
+        !journal.committedHead ||
+        journal.committedHead.revision !== journal.expectedHead?.revision ||
+        journal.committedHead.snapshotId !== journal.expectedHead?.snapshotId ||
+        journal.upload?.id !== journal.expectedHead?.snapshotId)) ||
+    (journal.sessionRoot !== undefined &&
+      (typeof journal.sessionRoot !== "string" ||
+        !path.isAbsolute(journal.sessionRoot) ||
+        path.resolve(journal.sessionRoot) !== journal.sessionRoot)) ||
+    (journal.warnings !== undefined &&
+      (!Array.isArray(journal.warnings) ||
+        journal.warnings.length > 64 ||
+        journal.warnings.some((item) => typeof item !== "string"))) ||
+    !journal.expectedHead ||
+    typeof journal.expectedHead.revision !== "string" ||
+    !journal.before ||
+    !journal.after ||
+    !journal.upload ||
+    !Array.isArray(journal.before.files) ||
+    !Array.isArray(journal.after.files) ||
+    !Array.isArray(journal.upload.files)
+  )
+    throw new Error("Unsupported or damaged merge journal; preserve it and review recovery before syncing.");
+  // Verify every path and byte, including the unmanaged remote files retained for publication.
+  try {
+    const pinnedPaths = new Set(journal.progress?.groups.flatMap((group) => group.paths) ?? []);
+    for (const snapshot of [
+      journal.before,
+      journal.after,
+      journal.upload,
+      ...(journal.accepted ? [journal.accepted] : []),
+    ]) {
+      validateSnapshotFieldPolicy(snapshot);
+      if (
+        (snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3) ||
+        typeof snapshot.id !== "string" ||
+        typeof snapshot.profile !== "string" ||
+        snapshot.files.length > 16_384 ||
+        snapshot.files.reduce(
+          (bytes, file) =>
+            bytes + (typeof file?.contentBase64 === "string" ? file.contentBase64.length * 0.75 : Infinity),
+          0,
+        ) >
+          64 * 1024 * 1024
+      )
+        throw new Error("Invalid journal input.");
+      const plan = planFileMerge({ baseline: {}, local: snapshot.files, remote: [], selectionCompatible: true });
+      if (
+        plan.kind !== "planned" ||
+        plan.conflicts.some((conflict) => conflict.reason !== "path-collision" || !pinnedPaths.has(conflict.path))
+      )
+        throw new Error("Invalid journal collision group.");
+    }
+    validatePortableSnapshot(journal.upload);
+    if ((journal.upload.version === 2 || journal.upload.version === 3) && !journal.accepted)
+      throw new Error("Portable merge journal requires an explicit accepted projection.");
+    if (journal.accepted) validatePortableSnapshot(journal.accepted);
+  } catch {
+    throw new Error("Invalid merge journal paths, metadata, or bytes; preserve evidence for review.");
+  }
+  // Integrity is intrinsic to the recorded transaction, not the user's current recovery policy.
+  // completeJournal separately checks that the recorded policy matches the current setup.
+  try {
+    if (
+      journal.accepted &&
+      (!sameLocalFields(journal.accepted.localFields, journal.upload.localFields) ||
+        !sameHashes(
+          fileHashMap(portableSnapshot(journal.after, journal.upload.localFields)),
+          fileHashMap(portableSnapshot(journal.accepted, journal.upload.localFields)),
+        ))
+    )
+      throw new Error("Projection mismatch.");
+  } catch {
+    throw new Error("Invalid accepted merge projection; preserve journal evidence.");
+  }
+  if (journal.progress) {
+    const known = new Set([
+      ...Object.keys(journal.progress.previous?.lastFileHashes ?? {}),
+      ...[...journal.before.files, ...journal.after.files, ...journal.upload.files].map((file) => file.path),
+    ]);
+    const progress = journal.progress;
+    if (
+      !config.partialSync ||
+      !progress.previous ||
+      syncStateFingerprint(progress.previous) !== journal.stateIdentity ||
+      !Array.isArray(progress.groups) ||
+      progress.groups.length > 16_384 ||
+      progress.groups.some(
+        (group) =>
+          !Array.isArray(group.paths) ||
+          !group.paths.length ||
+          group.paths.length > 16_384 ||
+          group.paths.some((filePath) => !known.has(filePath)) ||
+          !/^[a-f0-9-]{36}$/u.test(group.artifact),
+      )
+    )
+      throw new Error("Invalid partial acceptance metadata; preserve journal evidence.");
+  }
+  if (journal.progress) {
+    const before = fileHashMap(journal.before);
+    const after = fileHashMap(journal.after);
+    const { readConflictArtifact } = await import("./conflict-artifacts.js");
+    const backendIdentity = (JSON.parse(journal.identity) as unknown[])[1];
+    if (typeof backendIdentity !== "string") throw new Error("Invalid partial backend identity.");
+    const byArtifact = new Map<string, typeof journal.progress.groups>();
+    for (const group of journal.progress.groups) {
+      const groups = byArtifact.get(group.artifact) ?? [];
+      groups.push(group);
+      byArtifact.set(group.artifact, groups);
+    }
+    for (const [token, groups] of byArtifact) {
+      const artifact = await readConflictArtifact(config, backendIdentity, token);
+      const retainedGroups = new Set(artifact.groups.map((group) => JSON.stringify(group.paths)));
+      const remote = fileHashMap(artifact.remote);
+      const upload = fileHashMap(journal.upload);
+      for (const group of groups) {
+        if (!retainedGroups.has(JSON.stringify(group.paths)))
+          throw new Error("Partial group does not match retained artifact evidence.");
+        for (const filePath of group.paths)
+          if (
+            before[filePath] !== after[filePath] ||
+            remote[filePath] !== upload[filePath] ||
+            journal.progress.previous.lastFileHashes[filePath] !== artifact.state.lastFileHashes[filePath]
+          )
+            throw new Error("Withheld version changed in journal; preserve evidence.");
+      }
+    }
+  }
+  return journal;
+}
+
+export async function writeMergeJournal(config: AnySyncConfig, journal: MergeJournal) {
+  await writeJson(mergeJournalPath(config), journal, { maxBytes: 384 * 1024 * 1024 });
+}
+
+export async function clearMergeJournal(config: AnySyncConfig) {
+  await fs.rm(mergeJournalPath(config), { force: true });
+  await syncDirectory(path.dirname(mergeJournalPath(config)));
+}
+
+export async function retireMergeJournal(config: AnySyncConfig) {
+  if (!(await readMergeJournal(config))) return;
+  const file = mergeJournalPath(config);
+  await fs.rename(file, `${file}.${randomUUID()}.resolved`);
+  await syncDirectory(path.dirname(file));
+}
+
+export async function requireNoMergeJournal(config: AnySyncConfig, options: { force?: boolean } = {}) {
+  const journal = await readMergeJournal(config);
+  if (options.force || !journal) return;
+  if (journal) {
+    throw new Error(
+      "A merged transfer needs recovery. Run /sync sync to reconcile it. If newer local edits or remote revisions prevent recovery, review /sync diff and explicitly choose push --force or pull --force; the selected directional result will archive the old journal, not restore old bytes. Keep its backup; do not downgrade while recovery is pending.",
+    );
+  }
+}