@ebay-dt/bonfire-node 0.2.0-alpha.10 → 0.2.0-alpha.11

package/dist/lifecycle/repository-synchronization.js

@@ -1,6 +1,8 @@
-import { lstat } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
-import { GitRepositoryError, restorePathFromRef, } from "../git-repository.js";
+import { lstat, mkdir, mkdtemp, open, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { GitRepositoryError } from "../git-repository.js";
+import { isProtectedPrototypePath, isRegularPrototypeMode, } from "./prototype-path-policy.js";
 const OPERATION_MARKERS = [
     "MERGE_HEAD",
     "CHERRY_PICK_HEAD",
@@ -8,6 +10,17 @@ const OPERATION_MARKERS = [
     "rebase-merge",
     "rebase-apply",
 ];
+const DEPENDENCY_NAMES = new Set([
+    "package.json",
+    "pnpm-lock.yaml",
+    "pnpm-lock.yml",
+    "pnpm-workspace.yaml",
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+]);
 function assertBranch(value, option) {
     if (value.length === 0 ||
         value.startsWith("-") ||
@@ -18,14 +31,34 @@ function assertBranch(value, option) {
         throw new GitRepositoryError("invalid-configuration", option);
     }
 }
+function normalize(path) {
+    return path.replaceAll("\\", "/").replace(/^\.\//u, "");
+}
+function namespaceFor(repository, root, login) {
+    if (root.length === 0 ||
+        root.includes("\0") ||
+        root.split(/[\\/]/u).some((segment) => segment === "..")) {
+        throw new GitRepositoryError("invalid-configuration", "prototype-root");
+    }
+    assertBranch(login, "identity-login");
+    const absolute = isAbsolute(root)
+        ? resolve(root, login)
+        : resolve(repository.repositoryRoot, root, login);
+    const relativePath = normalize(relative(repository.repositoryRoot, absolute));
+    if (relativePath.length === 0 ||
+        relativePath === ".." ||
+        relativePath.startsWith("../")) {
+        throw new GitRepositoryError("invalid-configuration", "prototype-root");
+    }
+    return relativePath;
+}
 function remoteRef(remote, branch) {
     return `remotes/${remote}/${branch}`;
 }
 function branchRef(branch) {
     return `refs/heads/${branch}`;
 }
-async function markerExists(repository, marker) {
-    const markerPath = (await repository.raw(["rev-parse", "--git-path", marker])).trim();
+async function markerPathExists(repository, markerPath) {
     if (markerPath.length === 0)
         return false;
     const absolutePath = isAbsolute(markerPath)
@@ -39,121 +72,337 @@ async function markerExists(repository, marker) {
         if (error &&
             typeof error === "object" &&
             "code" in error &&
-            error.code === "ENOENT") {
+            error.code === "ENOENT")
             return false;
-        }
         throw error;
     }
 }
-export async function hasUnresolvedRepositoryOperation(repository) {
-    for (const marker of OPERATION_MARKERS) {
-        if (await markerExists(repository, marker))
+/** Resolve every marker path in one Git process; each is still checked on disk. */
+async function anyMarkerExists(repository, markers) {
+    const markerPaths = (await repository.raw([
+        "rev-parse",
+        ...markers.flatMap((marker) => ["--git-path", marker]),
+    ]))
+        .split("\n")
+        .map((markerPath) => markerPath.trim());
+    for (const markerPath of markerPaths)
+        if (await markerPathExists(repository, markerPath))
             return true;
-    }
-    const status = await repository.status();
-    return hasUnmergedFiles(status.files);
+    return false;
 }
 function hasUnmergedFiles(files) {
     return files.some((file) => file.index.includes("U") || file.workingDirectory.includes("U"));
 }
+export async function hasUnresolvedRepositoryOperation(repository) {
+    if (await anyMarkerExists(repository, OPERATION_MARKERS))
+        return true;
+    return hasUnmergedFiles((await repository.status()).files);
+}
+function assertNoUnresolved(status) {
+    if (hasUnmergedFiles(status.files))
+        throw new GitRepositoryError("conflict", "unresolved-operation");
+}
 async function refCommit(repository, ref) {
-    const value = await repository.raw([
-        "rev-parse",
-        "--verify",
-        `${ref}^{commit}`,
-    ]);
-    const commit = value.trim();
-    if (!/^[0-9a-f]{40}$/iu.test(commit)) {
+    const value = (await repository.raw(["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+    if (!/^[0-9a-f]{40}$/iu.test(value))
         throw new GitRepositoryError("malformed-output", "ref-commit");
+    return value;
+}
+/** Hold Git's own ref lock so another Git process cannot move a checkout target. */
+async function withLockedBranch(repository, branch, action) {
+    const gitPath = (await repository.raw([
+        "rev-parse",
+        "--git-path",
+        `${branchRef(branch)}.lock`,
+    ])).trim();
+    if (gitPath.length === 0)
+        throw new GitRepositoryError("malformed-output", "branch-lock");
+    const lockPath = resolve(repository.repositoryRoot, gitPath);
+    await mkdir(dirname(lockPath), { recursive: true });
+    // Exclusive creation also respects a lock already held by an external writer.
+    const lock = await open(lockPath, "wx");
+    try {
+        await action();
+    }
+    finally {
+        await lock.close();
+        await rm(lockPath);
     }
-    return commit;
 }
 async function compareRefs(repository, left, right) {
-    const output = await repository.raw([
+    const values = (await repository.raw([
         "rev-list",
         "--left-right",
         "--count",
         `${left}...${right}`,
-    ]);
-    const values = output.trim().split(/\s+/u).map(Number);
+    ]))
+        .trim()
+        .split(/\s+/u)
+        .map(Number);
     if (values.length !== 2 ||
         values.some((value) => !Number.isSafeInteger(value) || value < 0)) {
         throw new GitRepositoryError("malformed-output", "ref-relation");
     }
     return { ahead: values[0], behind: values[1] };
 }
-async function safelyAdvanceLocalPrimary(repository, primaryBranch, primaryRemoteRef, localPrimaryCommit) {
-    await repository.raw([
-        "update-ref",
-        branchRef(primaryBranch),
-        primaryRemoteRef,
-        localPrimaryCommit,
-    ]);
+function pathsFromStatus(files) {
+    return [
+        ...new Set(files.flatMap((file) => [
+            normalize(file.path),
+            ...(file.from ? [normalize(file.from)] : []),
+        ])),
+    ];
+}
+function isWithin(path, parent) {
+    return path === parent || path.startsWith(`${parent}/`);
+}
+function dependencyPath(path) {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    return DEPENDENCY_NAMES.has(name);
 }
-function deferred(branch, reason, affectedPaths = []) {
+function resultBase(branch, values = {}) {
     return {
-        status: "deferred",
         branch,
-        changed: false,
+        changed: values.changed ?? false,
         pushed: false,
-        affectedPaths,
-        reason,
+        affectedPaths: values.affectedPaths ?? [],
+        platformPaths: values.platformPaths ?? [],
+        dependencyPaths: values.dependencyPaths ?? [],
+        restartRequired: values.restartRequired ?? false,
+        preparationRequired: values.preparationRequired ?? false,
     };
 }
-function unsafe(branch, reason, options = {}) {
-    return {
-        status: "unsafe",
-        branch,
-        changed: options.changed ?? false,
-        pushed: options.pushed ?? false,
-        affectedPaths: options.affectedPaths ?? [],
-        reason,
-    };
+function deferred(branch, reason, values = {}) {
+    return { ...resultBase(branch, values), status: "deferred", reason };
 }
-export async function assertIdentityBranchReady(repository, identityBranch) {
-    assertBranch(identityBranch, "identity-branch");
-    const currentBranch = await repository.currentBranch();
-    if (currentBranch === "HEAD" || currentBranch.length === 0) {
-        throw new GitRepositoryError("conflict", "current-branch");
+function unsafe(branch, reason, values = {}) {
+    return { ...resultBase(branch, values), status: "unsafe", reason };
+}
+function parseTree(output) {
+    return output
+        .split("\0")
+        .filter(Boolean)
+        .flatMap((entry) => {
+        const tab = entry.indexOf("\t");
+        if (tab < 0)
+            return [];
+        const header = entry.slice(0, tab).split(/\s+/u);
+        const mode = header[0];
+        const object = header[2];
+        const path = normalize(entry.slice(tab + 1));
+        return mode && object && path ? [{ mode, object, path }] : [];
+    });
+}
+async function treeEntries(repository, tree, namespace) {
+    const args = ["ls-tree", "-r", "-z", tree];
+    if (namespace)
+        args.push("--", namespace);
+    return parseTree(await repository.raw(args));
+}
+function parseIndex(output) {
+    return output
+        .split("\0")
+        .filter(Boolean)
+        .flatMap((entry) => {
+        const tab = entry.indexOf("\t");
+        if (tab < 0)
+            return [];
+        const header = entry.slice(0, tab).split(/\s+/u);
+        const [mode, object, stage] = header;
+        const path = normalize(entry.slice(tab + 1));
+        return mode && object && stage && path
+            ? [{ mode, object, stage, path }]
+            : [];
+    });
+}
+async function rawWithIndex(repository, indexFile, args) {
+    if (!repository.rawWithEnv)
+        throw new GitRepositoryError("invalid-configuration", "private-index");
+    return repository.rawWithEnv(args, { GIT_INDEX_FILE: indexFile });
+}
+async function privateTree(repository, baseTree, namespace, replacement) {
+    const directory = await mkdtemp(join(tmpdir(), "bonfire-index-"));
+    const indexFile = join(directory, "index");
+    try {
+        await rawWithIndex(repository, indexFile, [
+            "read-tree",
+            "--reset",
+            baseTree,
+        ]);
+        const loaded = parseIndex(await rawWithIndex(repository, indexFile, [
+            "ls-files",
+            "-s",
+            "-z",
+            "--",
+            namespace,
+        ]));
+        for (const entry of loaded) {
+            await rawWithIndex(repository, indexFile, [
+                "update-index",
+                "--force-remove",
+                "--",
+                entry.path,
+            ]);
+        }
+        for (const entry of replacement) {
+            if (entry.stage !== "0")
+                throw new GitRepositoryError("conflict", "unmerged-index");
+            await rawWithIndex(repository, indexFile, [
+                "update-index",
+                "--add",
+                "--cacheinfo",
+                `${entry.mode},${entry.object},${entry.path}`,
+            ]);
+        }
+        return (await rawWithIndex(repository, indexFile, ["write-tree"])).trim();
     }
-    if (currentBranch !== identityBranch) {
-        throw new GitRepositoryError("conflict", "identity-branch");
+    finally {
+        await rm(directory, { recursive: true, force: true });
     }
-    if (await hasUnresolvedRepositoryOperation(repository)) {
-        throw new GitRepositoryError("conflict", "unresolved-operation");
+}
+/** Replace the complete namespace, rather than only paths found in HEAD. */
+async function overlayIndexNamespace(repository, baseTree, namespace, replacement) {
+    return privateTree(repository, baseTree, namespace, replacement);
+}
+async function indexNamespace(repository, namespace) {
+    return parseIndex(await repository.raw(["ls-files", "-s", "-z", "--", namespace]));
+}
+async function composeTree(repository, primary, ownTree, namespace) {
+    // The replacement is loaded from the committed identity tree.  In
+    // particular, removing the complete namespace of `primary` prevents
+    // primary-only paths from leaking into the designer-owned baseline.
+    return overlayIndexNamespace(repository, primary, namespace, (await treeEntries(repository, ownTree, namespace)).map((entry) => ({
+        ...entry,
+        stage: "0",
+    })));
+}
+async function treeChanges(repository, from, to, namespace) {
+    const output = await repository.raw([
+        "diff",
+        "--name-only",
+        "-z",
+        `${from}..${to}`,
+        "--",
+        ".",
+    ]);
+    return output
+        .split("\0")
+        .filter(Boolean)
+        .map(normalize)
+        .filter((path) => namespace === undefined || !isWithin(path, namespace));
+}
+async function platformChanges(repository, head, primary, namespace) {
+    return treeChanges(repository, head, primary, namespace);
+}
+async function filesystemPlatformCollision(repository, head, primary, paths) {
+    const headEntries = new Map((await treeEntries(repository, head)).map((entry) => [entry.path, entry]));
+    const primaryEntries = new Map((await treeEntries(repository, primary)).map((entry) => [
+        entry.path,
+        entry,
+    ]));
+    const collisions = [];
+    for (const path of paths) {
+        const segments = path.split("/");
+        for (let index = 1; index < segments.length; index += 1) {
+            const ancestor = segments.slice(0, index).join("/");
+            try {
+                const stats = await lstat(resolve(repository.repositoryRoot, ...ancestor.split("/")));
+                if (stats.isSymbolicLink() || !stats.isDirectory())
+                    collisions.push(path);
+            }
+            catch (error) {
+                if (!(error &&
+                    typeof error === "object" &&
+                    "code" in error &&
+                    error.code === "ENOENT"))
+                    collisions.push(path);
+            }
+        }
+        const before = headEntries.get(path);
+        const after = primaryEntries.get(path);
+        const absolute = resolve(repository.repositoryRoot, ...path.split("/"));
+        let current;
+        try {
+            current = await lstat(absolute);
+        }
+        catch (error) {
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT")
+                continue;
+            collisions.push(path);
+            continue;
+        }
+        // A path absent from HEAD is not necessarily safe merely because status
+        // omits it: ignored files and symlink/special parents are real state.
+        const trackedRegular = before !== undefined && isRegularPrototypeMode(before.mode);
+        const desiredRegular = after !== undefined && isRegularPrototypeMode(after.mode);
+        if (current.isSymbolicLink() ||
+            (!current.isFile() && !current.isDirectory())) {
+            collisions.push(path);
+            continue;
+        }
+        if (current.isDirectory()) {
+            // A tracked file-to-directory replacement is only safe when the
+            // destination path is absent; even an empty directory can make restore
+            // fail midway, while a non-empty one may contain ignored state.
+            if (desiredRegular)
+                collisions.push(path);
+            continue;
+        }
+        // A tracked regular file may be removed by the guarded tree transition;
+        // an untracked/ignored file is never safe to overwrite or remove.
+        if (!trackedRegular)
+            collisions.push(path);
     }
-    const status = await repository.status();
-    if (hasUnmergedFiles(status.files)) {
+    return [...new Set(collisions)];
+}
+async function protectedPlatformCollision(repository, head, primary, namespace, paths, excludeNamespace = true) {
+    const headEntries = new Map((await treeEntries(repository, head)).map((entry) => [entry.path, entry]));
+    const primaryEntries = new Map((await treeEntries(repository, primary)).map((entry) => [
+        entry.path,
+        entry,
+    ]));
+    return paths.filter((path) => {
+        if (excludeNamespace && isWithin(path, namespace))
+            return false;
+        const before = headEntries.get(path);
+        const after = primaryEntries.get(path);
+        const typeChangedToUnsafe = (before !== undefined && !isRegularPrototypeMode(before.mode)) ||
+            (after !== undefined && !isRegularPrototypeMode(after.mode));
+        return (typeChangedToUnsafe ||
+            (isProtectedPrototypePath(path) &&
+                (before?.mode !== after?.mode || before?.object !== after?.object)));
+    });
+}
+export async function assertIdentityBranchReady(repository, identityBranch) {
+    assertBranch(identityBranch, "identity-branch");
+    const branch = await repository.currentBranch();
+    if (branch === "HEAD" || branch.length === 0 || branch !== identityBranch)
+        throw new GitRepositoryError("conflict", "identity-branch");
+    if (await hasUnresolvedRepositoryOperation(repository))
         throw new GitRepositoryError("conflict", "unresolved-operation");
-    }
 }
 /**
- * Synchronize an identity branch from primary without checking out local
- * primary. Remote-tracking refs are the source of truth whenever a configured
- * remote is available. The result distinguishes non-blocking attention from
- * unsafe repository state so callers can keep authentication/read-only flows
- * available.
+ * Reconcile only the committed platform baseline. Tree composition uses
+ * private indexes; the guarded Git index/worktree patch then updates the
+ * active index and platform worktree while leaving the namespace layer alone.
  */
 export async function synchronizeIdentityBranch(repository, options) {
     assertBranch(options.identityBranch, "identity-branch");
     assertBranch(options.primaryBranch, "primary-branch");
     assertBranch(options.remote, "remote");
-    if (options.identityBranch === options.primaryBranch) {
+    if (options.identityBranch === options.primaryBranch)
         throw new GitRepositoryError("invalid-configuration", "identity-primary-branch");
-    }
-    const currentBranch = await repository.currentBranch();
-    if (currentBranch === "HEAD" || currentBranch.length === 0) {
+    const namespace = namespaceFor(repository, options.prototypeRoot, options.identityBranch);
+    let currentBranch = await repository.currentBranch();
+    if (currentBranch === "HEAD" || currentBranch.length === 0)
         return unsafe(null, "detached-head");
-    }
-    if (await hasUnresolvedRepositoryOperation(repository)) {
+    const originalBranch = currentBranch;
+    const originalHead = await refCommit(repository, "HEAD");
+    if (await hasUnresolvedRepositoryOperation(repository))
         return unsafe(currentBranch, "unresolved-operation");
-    }
-    let status = await repository.status();
-    if (hasUnmergedFiles(status.files)) {
-        return unsafe(currentBranch, "unresolved-operation", {
-            affectedPaths: status.files.map((file) => file.path),
-        });
-    }
     const configuredRemote = (await repository.remotes()).some((remote) => remote.name === options.remote);
     if (configuredRemote) {
         try {
@@ -161,154 +410,402 @@ export async function synchronizeIdentityBranch(repository, options) {
         }
         catch (error) {
             if (error instanceof GitRepositoryError &&
-                error.kind === "invalid-configuration") {
+                error.kind === "invalid-configuration")
                 throw error;
-            }
             return deferred(currentBranch, "fetch-failed");
         }
     }
+    const afterFetchBranch = await repository.currentBranch();
+    if (afterFetchBranch !== currentBranch)
+        return unsafe(afterFetchBranch, "branch-changed");
+    currentBranch = afterFetchBranch;
+    if (await hasUnresolvedRepositoryOperation(repository))
+        return unsafe(currentBranch, "unresolved-operation");
     const branches = await repository.branches();
     const localPrimary = branches.all.includes(options.primaryBranch);
     const primaryRemote = remoteRef(options.remote, options.primaryBranch);
     const remotePrimary = configuredRemote && branches.all.includes(primaryRemote);
-    if (configuredRemote ? !remotePrimary : !localPrimary) {
+    if (configuredRemote ? !remotePrimary : !localPrimary)
         return unsafe(currentBranch, "missing-primary");
-    }
+    const sourceRef = remotePrimary ? primaryRemote : options.primaryBranch;
+    // Pin the source before planning.  Never compose from a mutable remote ref.
+    const primarySha = await refCommit(repository, sourceRef);
     const localIdentity = branches.all.includes(options.identityBranch);
     const identityRemote = remoteRef(options.remote, options.identityBranch);
     const remoteIdentity = configuredRemote && branches.all.includes(identityRemote);
+    // Match the legacy branch-preparation behavior: a remote-only identity is
+    // based on its remote namespace, not silently recreated from primary.
+    const identityBaseRef = localIdentity
+        ? options.identityBranch
+        : remoteIdentity
+            ? identityRemote
+            : sourceRef;
     if (localIdentity && remoteIdentity) {
         const relation = await compareRefs(repository, options.identityBranch, identityRemote);
-        if (relation.ahead > 0 && relation.behind > 0) {
+        if (relation.ahead > 0 && relation.behind > 0)
             return unsafe(currentBranch, "identity-divergence");
-        }
     }
-    let primaryAdvance;
-    if (localPrimary && remotePrimary) {
-        const relation = await compareRefs(repository, options.primaryBranch, primaryRemote);
-        if (relation.ahead === 0 && relation.behind > 0) {
-            primaryAdvance = {
-                localCommit: await refCommit(repository, options.primaryBranch),
-                remoteRef: primaryRemote,
-            };
-        }
+    let status = await repository.status();
+    assertNoUnresolved(status);
+    const dirtyPaths = pathsFromStatus(status.files);
+    const dirtyOutside = dirtyPaths.filter((path) => !isWithin(path, namespace));
+    if (dirtyOutside.length > 0 || (!status.clean && dirtyPaths.length === 0)) {
+        return deferred(currentBranch, "dirty-worktree", {
+            affectedPaths: dirtyPaths,
+        });
     }
-    const sourceRef = remotePrimary ? primaryRemote : options.primaryBranch;
-    const managedPaths = new Set(options.managedPaths ?? []);
-    const managedChanges = status.files.flatMap((file) => [file.path, ...(file.from === undefined ? [] : [file.from])].filter((path) => managedPaths.has(path)));
-    if (managedChanges.length > 0) {
-        for (const path of managedChanges) {
-            await restorePathFromRef(repository, sourceRef, path);
-        }
-        status = await repository.status();
+    // A checkout is itself a tree transition. Even namespace-only dirt is not
+    // safe to carry across it: checkout can replace ignored files that status
+    // does not report. Defer before selecting/creating the identity branch.
+    if (!localIdentity && dirtyPaths.length > 0) {
+        return deferred(currentBranch, "dirty-worktree", {
+            affectedPaths: dirtyPaths,
+        });
+    }
+    const head = await refCommit(repository, "HEAD");
+    const primaryPaths = await platformChanges(repository, head, primarySha, namespace);
+    const protectedPaths = await protectedPlatformCollision(repository, head, primarySha, namespace, primaryPaths);
+    const filesystemPaths = await filesystemPlatformCollision(repository, head, primarySha, primaryPaths);
+    if (protectedPaths.length > 0 || filesystemPaths.length > 0)
+        return deferred(currentBranch, "protected-collision", {
+            affectedPaths: [...new Set([...protectedPaths, ...filesystemPaths])],
+        });
+    const targetHead = await refCommit(repository, identityBaseRef);
+    const checkoutPaths = targetHead === originalHead
+        ? []
+        : await treeChanges(repository, originalHead, targetHead);
+    const checkoutPlatformPaths = checkoutPaths.filter((path) => !isWithin(path, namespace));
+    const checkoutDependencyPaths = checkoutPlatformPaths.filter(dependencyPath);
+    if (targetHead !== originalHead) {
+        // This preflight includes the target identity namespace. In particular,
+        // ignored files absent from the current tree must not be overwritten by
+        // selecting an existing remote/local identity branch.
+        const checkoutCollisions = await filesystemPlatformCollision(repository, originalHead, targetHead, checkoutPaths);
+        const checkoutProtected = await protectedPlatformCollision(repository, originalHead, targetHead, namespace, checkoutPaths, false);
+        if (checkoutCollisions.length > 0 || checkoutProtected.length > 0)
+            return deferred(currentBranch, "protected-collision", {
+                affectedPaths: [
+                    ...new Set([...checkoutCollisions, ...checkoutProtected]),
+                ],
+            });
     }
-    const remainingDirtyPaths = status.files
-        .flatMap((file) => [
-        file.path,
-        ...(file.from === undefined ? [] : [file.from]),
-    ])
-        .filter((path) => !managedPaths.has(path));
-    if (remainingDirtyPaths.length > 0 ||
-        (!status.clean && status.files.length === 0)) {
-        return deferred(currentBranch, "dirty-worktree", remainingDirtyPaths);
+    if (currentBranch !== options.identityBranch && dirtyPaths.length > 0) {
+        return deferred(currentBranch, "dirty-worktree", {
+            affectedPaths: dirtyPaths,
+        });
     }
-    let identityCreated = false;
     if (!localIdentity) {
-        identityCreated = true;
-        if (remoteIdentity) {
+        try {
+            // Create from the exact preflighted commit, never a moving remote ref.
+            // -b refuses a concurrently created local branch instead of replacing it.
             await repository.checkout([
+                "--no-overwrite-ignore",
+                "--no-track",
                 "-b",
                 options.identityBranch,
-                "--track",
-                `${options.remote}/${options.identityBranch}`,
+                targetHead,
             ]);
+            currentBranch = options.identityBranch;
+            if (remoteIdentity)
+                await repository.raw([
+                    "branch",
+                    `--set-upstream-to=${identityRemote}`,
+                    options.identityBranch,
+                ]);
         }
-        else {
-            await repository.checkout(["-b", options.identityBranch, sourceRef]);
+        catch {
+            const observedBranch = await repository.currentBranch();
+            return unsafe(observedBranch || currentBranch, "reconciliation-failed", {
+                changed: observedBranch !== originalBranch,
+                affectedPaths: checkoutPaths,
+                platformPaths: checkoutPlatformPaths,
+                dependencyPaths: checkoutDependencyPaths,
+                restartRequired: checkoutPlatformPaths.length > 0,
+                preparationRequired: checkoutDependencyPaths.length > 0,
+            });
         }
     }
     else if (currentBranch !== options.identityBranch) {
-        await repository.checkout([options.identityBranch]);
-    }
-    if (primaryAdvance && currentBranch !== options.primaryBranch) {
-        await safelyAdvanceLocalPrimary(repository, options.primaryBranch, primaryAdvance.remoteRef, primaryAdvance.localCommit);
-    }
-    if (localIdentity && remoteIdentity) {
-        const relation = await compareRefs(repository, options.identityBranch, identityRemote);
-        if (relation.ahead === 0 && relation.behind > 0) {
-            await repository.merge([identityRemote, "--ff-only"]);
-        }
-    }
-    const beforeMerge = await refCommit(repository, options.identityBranch);
-    try {
-        await repository.merge([sourceRef, "--no-edit"]);
-    }
-    catch (error) {
-        if (!(error instanceof GitRepositoryError) || error.kind !== "conflict") {
-            return unsafe(options.identityBranch, "merge-failed");
-        }
-        let affectedPaths = [];
         try {
-            affectedPaths = (await repository.status()).files.map((file) => file.path);
-        }
-        catch {
-            // Preserve the conflict classification even if status cannot be read.
-        }
-        try {
-            await repository.raw(["merge", "--abort"]);
+            await withLockedBranch(repository, options.identityBranch, async () => {
+                // Validation without the lock would leave another check/use race.
+                // Existing-branch checkout does not write the branch ref, so Git's ref
+                // lock can remain held throughout the checkout itself.
+                if ((await refCommit(repository, branchRef(options.identityBranch))) !==
+                    targetHead ||
+                    (await repository.currentBranch()) !== originalBranch ||
+                    (await refCommit(repository, "HEAD")) !== originalHead ||
+                    !(await repository.status()).clean)
+                    throw new GitRepositoryError("conflict", "checkout-target-changed");
+                await repository.checkout([
+                    "--no-overwrite-ignore",
+                    options.identityBranch,
+                ]);
+                currentBranch = options.identityBranch;
+            });
         }
         catch {
-            return unsafe(options.identityBranch, "failed-abort", {
-                affectedPaths,
+            const observedBranch = await repository.currentBranch();
+            return unsafe(observedBranch || currentBranch, "reconciliation-failed", {
+                changed: observedBranch !== originalBranch,
+                affectedPaths: checkoutPaths,
+                platformPaths: checkoutPlatformPaths,
+                dependencyPaths: checkoutDependencyPaths,
+                restartRequired: checkoutPlatformPaths.length > 0,
+                preparationRequired: checkoutDependencyPaths.length > 0,
             });
         }
-        return deferred(options.identityBranch, "merge-conflict", affectedPaths);
     }
-    const afterMerge = await refCommit(repository, options.identityBranch);
-    const changed = beforeMerge !== afterMerge;
-    const mergedPaths = changed
-        ? (await repository.raw([
-            "diff",
-            "--name-only",
-            "-z",
-            `${beforeMerge}..${afterMerge}`,
-        ]))
-            .split("\0")
-            .filter((path) => path.length > 0)
-        : [];
-    const affectedPaths = [
+    // Re-read after branch movement and before touching the index.  This catches
+    // an external command or a fetch hook that changed the checkout meanwhile.
+    const branchBeforeMutation = await repository.currentBranch();
+    const checkoutChanged = currentBranch !== originalBranch;
+    const checkoutEffects = {
+        changed: checkoutChanged,
+        affectedPaths: checkoutPaths,
+        platformPaths: checkoutPlatformPaths,
+        dependencyPaths: checkoutDependencyPaths,
+        restartRequired: checkoutPlatformPaths.length > 0,
+        preparationRequired: checkoutDependencyPaths.length > 0,
+    };
+    if (branchBeforeMutation !== currentBranch ||
+        branchBeforeMutation === "HEAD") {
+        return unsafe(branchBeforeMutation || null, "branch-changed", {
+            ...checkoutEffects,
+        });
+    }
+    status = await repository.status();
+    if (!status.clean &&
+        pathsFromStatus(status.files).some((path) => !isWithin(path, namespace))) {
+        return deferred(currentBranch, "dirty-worktree", {
+            ...checkoutEffects,
+            affectedPaths: [
+                ...new Set([...checkoutPaths, ...pathsFromStatus(status.files)]),
+            ],
+        });
+    }
+    if (await hasUnresolvedRepositoryOperation(repository))
+        return unsafe(currentBranch, "unresolved-operation", checkoutEffects);
+    const latestHead = await refCommit(repository, "HEAD");
+    if (latestHead !== targetHead)
+        return unsafe(currentBranch, "reconciliation-failed", {
+            ...checkoutEffects,
+            changed: true,
+        });
+    const latestPrimarySha = await refCommit(repository, sourceRef);
+    const branchSelectionChanged = currentBranch !== originalBranch || latestHead !== originalHead;
+    if (latestPrimarySha !== primarySha)
+        return unsafe(currentBranch, "reconciliation-failed", {
+            ...checkoutEffects,
+            affectedPaths: [...new Set([...checkoutPaths, ...primaryPaths])],
+        });
+    const latestPrimaryPaths = await platformChanges(repository, latestHead, primarySha, namespace);
+    const latestProtected = await protectedPlatformCollision(repository, latestHead, primarySha, namespace, latestPrimaryPaths);
+    const latestFilesystem = await filesystemPlatformCollision(repository, latestHead, primarySha, latestPrimaryPaths);
+    if (latestProtected.length > 0 || latestFilesystem.length > 0)
+        return deferred(currentBranch, "protected-collision", {
+            ...checkoutEffects,
+            affectedPaths: [
+                ...new Set([...checkoutPaths, ...latestProtected, ...latestFilesystem]),
+            ],
+        });
+    const plannedPlatformPaths = [
+        ...new Set([...latestPrimaryPaths, ...checkoutPlatformPaths]),
+    ];
+    const plannedDependencyPaths = [
         ...new Set([
-            ...managedChanges,
-            ...mergedPaths,
-            ...(identityCreated ? [...managedPaths] : []),
+            ...checkoutDependencyPaths,
+            ...latestPrimaryPaths.filter(dependencyPath),
         ]),
     ];
-    if (!changed || !configuredRemote) {
+    if (latestPrimaryPaths.length === 0) {
         return {
+            ...resultBase(currentBranch, {
+                changed: branchSelectionChanged,
+                affectedPaths: checkoutPaths,
+                platformPaths: checkoutPlatformPaths,
+                dependencyPaths: checkoutDependencyPaths,
+                restartRequired: checkoutPlatformPaths.length > 0,
+                preparationRequired: checkoutDependencyPaths.length > 0,
+            }),
             status: "synchronized",
-            branch: options.identityBranch,
-            changed,
-            pushed: false,
-            affectedPaths,
         };
     }
+    const indexTree = (await repository.raw(["write-tree"])).trim();
+    const stagedNamespace = await indexNamespace(repository, namespace);
+    let baselineCommit;
+    let desiredIndexTree;
+    let patchDirectory;
+    let patchFile;
+    const dependencies = plannedDependencyPaths;
     try {
-        await repository.push(options.remote, options.identityBranch, [
-            "--set-upstream",
+        // All object creation and tree composition happen in temporary indexes.
+        // The live index is never used as a tree builder.
+        const composedTree = await composeTree(repository, primarySha, latestHead, namespace);
+        baselineCommit = (await repository.raw([
+            "commit-tree",
+            composedTree,
+            "-p",
+            latestHead,
+            "-m",
+            "chore: update committed platform baseline",
+        ])).trim();
+        if (!/^[0-9a-f]{40}$/iu.test(baselineCommit))
+            throw new GitRepositoryError("malformed-output", "baseline-commit");
+        if ((await repository.currentBranch()) !== currentBranch ||
+            (await refCommit(repository, "HEAD")) !== latestHead ||
+            (await refCommit(repository, sourceRef)) !== primarySha ||
+            (await repository.raw(["write-tree"])).trim() !== indexTree) {
+            throw new GitRepositoryError("conflict", "external-state");
+        }
+        desiredIndexTree = await overlayIndexNamespace(repository, baselineCommit, namespace, stagedNamespace);
+        // Apply the tree delta through Git's guarded index/worktree primitive.
+        // Unlike checkout/read-tree -u, git apply --index refuses to overwrite an
+        // untracked or ignored path that appears between preflight and mutation.
+        // The trees carry the same staged namespace, and the patch excludes that
+        // namespace, so staged and unstaged prototype files are not touched.
+        if ((await repository.raw(["write-tree"])).trim() !== indexTree)
+            throw new GitRepositoryError("conflict", "external-index");
+        patchDirectory = await mkdtemp(join(tmpdir(), "bonfire-patch-"));
+        patchFile = join(patchDirectory, "platform.patch");
+        const patch = await repository.raw([
+            "diff",
+            "--binary",
+            indexTree,
+            desiredIndexTree,
+            "--",
+            ".",
+            `:(exclude)${namespace}`,
+        ]);
+        await writeFile(patchFile, patch);
+        await repository.raw(["apply", "--index", patchFile]);
+        if ((await repository.currentBranch()) !== currentBranch ||
+            (await refCommit(repository, "HEAD")) !== latestHead ||
+            (await refCommit(repository, sourceRef)) !== primarySha ||
+            (await repository.raw(["write-tree"])).trim() !== desiredIndexTree)
+            throw new GitRepositoryError("conflict", "external-state");
+        // Ref movement is last. The expected old value is a CAS guard against an
+        // external branch writer.
+        await repository.raw([
+            "update-ref",
+            branchRef(options.identityBranch),
+            baselineCommit,
+            latestHead,
         ]);
+        const landedHead = await refCommit(repository, "HEAD");
+        if (landedHead !== baselineCommit)
+            throw new GitRepositoryError("conflict", "ref-transition");
+        if ((await repository.currentBranch()) !== currentBranch ||
+            (await refCommit(repository, sourceRef)) !== primarySha ||
+            (await repository.raw(["write-tree"])).trim() !== desiredIndexTree)
+            throw new GitRepositoryError("conflict", "external-state");
+        const finalStatus = await repository.status();
+        const unexpectedFinalPaths = pathsFromStatus(finalStatus.files).filter((path) => !isWithin(path, namespace));
+        if (unexpectedFinalPaths.length > 0)
+            throw new GitRepositoryError("conflict", "external-worktree");
     }
     catch {
-        return unsafe(options.identityBranch, "push-failed", {
+        // A command wrapper may throw after running a command. First try the
+        // narrowly guarded inverse of our original patch. This is allowed only
+        // while the original branch/ref/source and exact intended index/worktree
+        // state still hold; git apply itself then protects intervening edits.
+        let recovered = false;
+        if (patchFile !== undefined && desiredIndexTree !== undefined) {
+            try {
+                const sameState = (await repository.currentBranch()) === currentBranch &&
+                    (await refCommit(repository, "HEAD")) === latestHead &&
+                    (await refCommit(repository, sourceRef)) === primarySha &&
+                    (await repository.raw(["write-tree"])).trim() === desiredIndexTree;
+                if (sameState) {
+                    await repository.raw([
+                        "diff",
+                        "--quiet",
+                        desiredIndexTree,
+                        "--",
+                        ".",
+                        `:(exclude)${namespace}`,
+                    ]);
+                    const observed = await repository.status();
+                    const unexpected = pathsFromStatus(observed.files).filter((path) => !isWithin(path, namespace) &&
+                        !latestPrimaryPaths.some((expected) => isWithin(path, expected) || isWithin(expected, path)));
+                    if (unexpected.length === 0) {
+                        await repository.raw(["apply", "--reverse", "--index", patchFile]);
+                        const restored = await repository.status();
+                        recovered =
+                            (await repository.raw(["write-tree"])).trim() === indexTree &&
+                                (await refCommit(repository, "HEAD")) === latestHead &&
+                                (await repository.currentBranch()) === currentBranch &&
+                                (await repository.raw([
+                                    "diff",
+                                    "--quiet",
+                                    indexTree,
+                                    "--",
+                                    ".",
+                                    `:(exclude)${namespace}`,
+                                ])) === "" &&
+                                pathsFromStatus(restored.files).every((path) => isWithin(path, namespace));
+                    }
+                }
+            }
+            catch {
+                // Preserve the partial transition. Manual recovery must begin from
+                // the reported old HEAD and inspect the exact platform paths before
+                // applying the original patch in reverse; never reset or clean here.
+            }
+        }
+        if (patchDirectory !== undefined)
+            await rm(patchDirectory, { recursive: true, force: true }).catch(() => undefined);
+        let landed;
+        let indexChanged = false;
+        let worktreeChanged = false;
+        try {
+            landed = (await refCommit(repository, "HEAD")) !== latestHead;
+        }
+        catch {
+            // A malformed/missing ref is itself an incomplete transition.
+            landed = true;
+        }
+        if (desiredIndexTree !== undefined) {
+            try {
+                indexChanged =
+                    (await repository.raw(["write-tree"])).trim() !== indexTree;
+            }
+            catch {
+                indexChanged = true;
+            }
+            // The guarded --index patch changes the index and worktree as one Git
+            // operation. An index-tree change is therefore the reliable
+            // observable for a transition that ran before an acknowledgement failed;
+            // a pure pre-side-effect rejection leaves both layers unchanged.
+            worktreeChanged = indexChanged;
+        }
+        const changed = recovered
+            ? branchSelectionChanged
+            : branchSelectionChanged || landed || indexChanged || worktreeChanged;
+        return unsafe(currentBranch, "reconciliation-failed", {
             changed,
-            affectedPaths,
+            affectedPaths: [...new Set([...checkoutPaths, ...latestPrimaryPaths])],
+            dependencyPaths: dependencies,
+            platformPaths: plannedPlatformPaths,
+            restartRequired: checkoutPlatformPaths.length > 0 ||
+                (!recovered && (worktreeChanged || landed)),
+            preparationRequired: dependencies.length > 0 &&
+                (checkoutDependencyPaths.length > 0 ||
+                    (!recovered && (landed || worktreeChanged))),
         });
     }
+    if (patchDirectory !== undefined)
+        await rm(patchDirectory, { recursive: true, force: true });
     return {
+        ...resultBase(currentBranch, {
+            changed: true,
+            affectedPaths: [...new Set([...checkoutPaths, ...latestPrimaryPaths])],
+            platformPaths: plannedPlatformPaths,
+            dependencyPaths: dependencies,
+            restartRequired: plannedPlatformPaths.length > 0,
+            preparationRequired: dependencies.length > 0,
+        }),
         status: "synchronized",
-        branch: options.identityBranch,
-        changed: true,
-        pushed: true,
-        affectedPaths,
     };
 }
 //# sourceMappingURL=repository-synchronization.js.map