amalgm 0.1.238 → 0.1.240

package/runtime/scripts/amalgm-mcp/workspace/native-file-transaction/main.go

@@ -0,0 +1,2201 @@
+// amalgm-file-transaction is the descriptor-relative mutation boundary for
+// ordered workspace file applies. It never resolves a repository-relative
+// parent after opening it: every create, rename, link, unlink, and directory
+// sync is performed relative to O_NOFOLLOW directory descriptors.
+package main
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"golang.org/x/sys/unix"
+)
+
+type identity struct {
+	Kind   string `json:"kind"`
+	Exec   bool   `json:"exec,omitempty"`
+	Bytes  int64  `json:"bytes,omitempty"`
+	SHA256 string `json:"sha256,omitempty"`
+	Dev    string `json:"dev,omitempty"`
+	Ino    string `json:"ino,omitempty"`
+}
+
+type target struct {
+	Kind    string  `json:"kind"`
+	Exec    bool    `json:"exec,omitempty"`
+	Bytes   int64   `json:"bytes"`
+	SHA256  string  `json:"sha256"`
+	Content *string `json:"content,omitempty"`
+}
+
+type treeEntryIdentity struct {
+	Kind string `json:"kind"`
+	Dev  string `json:"dev"`
+	Ino  string `json:"ino"`
+}
+
+type request struct {
+	Action                         string             `json:"action"`
+	Backend                        string             `json:"backend,omitempty"`
+	Root                           string             `json:"root"`
+	RootDev                        string             `json:"rootDev"`
+	RootIno                        string             `json:"rootIno"`
+	Source                         string             `json:"source,omitempty"`
+	SourceIdentity                 *treeEntryIdentity `json:"sourceIdentity,omitempty"`
+	SourceParentIdentity           *treeEntryIdentity `json:"sourceParentIdentity,omitempty"`
+	TargetParentIdentity           *treeEntryIdentity `json:"targetParentIdentity,omitempty"`
+	Path                           string             `json:"path"`
+	ID                             string             `json:"id"`
+	Operation                      string             `json:"operation"`
+	Expected                       *identity          `json:"expected"`
+	Target                         *target            `json:"target"`
+	TestPauseAfterParentOpenMillis int                `json:"testPauseAfterParentOpenMillis,omitempty"`
+	TestPauseAfterExtractionMillis int                `json:"testPauseAfterExtractionMillis,omitempty"`
+	TestPauseBeforeInstallMillis   int                `json:"testPauseBeforeInstallMillis,omitempty"`
+	TestPauseAfterTreeMoveMillis   int                `json:"testPauseAfterTreeMoveMillis,omitempty"`
+	TestCrashAfterExtraction       bool               `json:"testCrashAfterExtraction,omitempty"`
+	TestCrashBeforeInstall         bool               `json:"testCrashBeforeInstall,omitempty"`
+	TestCrashAfterInstall          bool               `json:"testCrashAfterInstall,omitempty"`
+	TestCrashAfterTreeMove         bool               `json:"testCrashAfterTreeMove,omitempty"`
+	PID                            int                `json:"pid,omitempty"`
+}
+
+type response struct {
+	Status   string    `json:"status"`
+	Reason   string    `json:"reason,omitempty"`
+	Identity string    `json:"identity,omitempty"`
+	RootDev  string    `json:"rootDev,omitempty"`
+	RootIno  string    `json:"rootIno,omitempty"`
+	Path     string    `json:"path,omitempty"`
+	Value    *identity `json:"value,omitempty"`
+	Content  *string   `json:"content,omitempty"`
+}
+
+type openedParent struct {
+	rootFD    int
+	parentFD  int
+	parentAbs string
+	base      string
+	dev       uint64
+	ino       uint64
+}
+
+func main() {
+	var input request
+	decoder := json.NewDecoder(io.LimitReader(os.Stdin, 16*1024*1024))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&input); err != nil {
+		fail(fmt.Errorf("invalid request: %w", err))
+	}
+	if err := validateRequest(input); err != nil {
+		fail(err)
+	}
+	var result response
+	var err error
+	if input.Backend == "process-identity" {
+		switch input.Action {
+		case "identity":
+			var identity string
+			var live bool
+			identity, live, err = processIdentity(input.PID)
+			if live {
+				result = response{Status: "identified", Identity: identity}
+			} else {
+				result = response{Status: "exited"}
+			}
+		default:
+			err = fmt.Errorf("unsupported action %q", input.Action)
+		}
+	} else if input.Backend == "git-lock" {
+		switch input.Action {
+		case "apply":
+			result, err = applyGitLock(input)
+		case "recover":
+			result, err = recoverGitLock(input)
+		case "receipt":
+			result, err = readGitLockReceipt(input)
+		case "release":
+			result, err = releaseGitLockReceipt(input)
+		default:
+			err = fmt.Errorf("unsupported action %q", input.Action)
+		}
+	} else if input.Backend == "git-guard" {
+		switch input.Action {
+		case "guard":
+			result, err = guardGitLock(input)
+		case "recover", "unguard":
+			result, err = releaseGitGuard(input)
+		default:
+			err = fmt.Errorf("unsupported action %q", input.Action)
+		}
+	} else if input.Backend == "git-worktree-guard" {
+		switch input.Action {
+		case "guard":
+			result, err = guardGitWorktreeNamespace(input)
+		case "recover", "unguard":
+			result, err = releaseGitWorktreeNamespace(input)
+		default:
+			err = fmt.Errorf("unsupported action %q", input.Action)
+		}
+	} else if input.Backend == "tree-rename" {
+		switch input.Action {
+		case "move":
+			result, err = moveTreeEntryNoReplace(input)
+		default:
+			err = fmt.Errorf("unsupported action %q", input.Action)
+		}
+	} else {
+		switch input.Action {
+		case "observe":
+			result, err = observe(input)
+		case "apply":
+			result, err = apply(input)
+		case "recover":
+			result, err = recoverTransaction(input)
+		case "receipt":
+			result, err = readReceipt(input)
+		case "release":
+			result, err = releaseReceipt(input)
+		default:
+			err = fmt.Errorf("unsupported action %q", input.Action)
+		}
+	}
+	if err != nil {
+		fail(err)
+	}
+	if err := json.NewEncoder(os.Stdout).Encode(result); err != nil {
+		fail(err)
+	}
+}
+
+func fail(err error) {
+	_ = json.NewEncoder(os.Stdout).Encode(map[string]string{
+		"status": "error",
+		"reason": err.Error(),
+	})
+	os.Exit(1)
+}
+
+func validateRequest(input request) error {
+	if input.Backend == "process-identity" {
+		if input.Action != "identity" {
+			return errors.New("process identity action is invalid")
+		}
+		if input.PID < 1 {
+			return errors.New("process identity PID is invalid")
+		}
+		return nil
+	}
+	if input.Backend != "" &&
+		input.Backend != "git-lock" &&
+		input.Backend != "git-guard" &&
+		input.Backend != "git-worktree-guard" &&
+		input.Backend != "tree-rename" {
+		return errors.New("backend is invalid")
+	}
+	if !filepath.IsAbs(input.Root) {
+		return errors.New("root must be absolute")
+	}
+	if _, err := strconv.ParseUint(input.RootDev, 10, 64); err != nil {
+		return errors.New("root device identity is invalid")
+	}
+	if _, err := strconv.ParseUint(input.RootIno, 10, 64); err != nil {
+		return errors.New("root inode identity is invalid")
+	}
+	if input.Path == "" || filepath.IsAbs(input.Path) || strings.Contains(input.Path, `\`) {
+		return errors.New("path must be a Unix repository-relative path")
+	}
+	for _, component := range strings.Split(input.Path, "/") {
+		if component == "" || component == "." || component == ".." {
+			return errors.New("path contains an unsafe component")
+		}
+	}
+	if input.Backend == "tree-rename" {
+		if input.Action != "move" {
+			return errors.New("tree rename action is invalid")
+		}
+		if input.Source == "" || filepath.IsAbs(input.Source) || strings.Contains(input.Source, `\`) {
+			return errors.New("tree rename source must be a Unix root-relative path")
+		}
+		for _, component := range strings.Split(input.Source, "/") {
+			if component == "" || component == "." || component == ".." {
+				return errors.New("tree rename source contains an unsafe component")
+			}
+		}
+		if input.Expected != nil || input.Target != nil {
+			return errors.New("tree rename has unexpected byte identities")
+		}
+		if input.SourceIdentity == nil {
+			return errors.New("tree rename source identity is missing")
+		}
+		if input.SourceParentIdentity == nil || input.TargetParentIdentity == nil {
+			return errors.New("tree rename parent identities are missing")
+		}
+		if input.SourceIdentity.Kind != "file" &&
+			input.SourceIdentity.Kind != "folder" &&
+			input.SourceIdentity.Kind != "symlink" &&
+			input.SourceIdentity.Kind != "other" {
+			return errors.New("tree rename source kind is invalid")
+		}
+		if _, err := strconv.ParseUint(input.SourceIdentity.Dev, 10, 64); err != nil {
+			return errors.New("tree rename source device identity is invalid")
+		}
+		if _, err := strconv.ParseUint(input.SourceIdentity.Ino, 10, 64); err != nil {
+			return errors.New("tree rename source inode identity is invalid")
+		}
+		for label, parent := range map[string]*treeEntryIdentity{
+			"source": input.SourceParentIdentity,
+			"target": input.TargetParentIdentity,
+		} {
+			if parent.Kind != "folder" {
+				return fmt.Errorf("tree rename %s parent must be a folder", label)
+			}
+			if _, err := strconv.ParseUint(parent.Dev, 10, 64); err != nil {
+				return fmt.Errorf("tree rename %s parent device identity is invalid", label)
+			}
+			if _, err := strconv.ParseUint(parent.Ino, 10, 64); err != nil {
+				return fmt.Errorf("tree rename %s parent inode identity is invalid", label)
+			}
+		}
+	}
+	for _, pause := range []int{
+		input.TestPauseAfterParentOpenMillis,
+		input.TestPauseAfterExtractionMillis,
+		input.TestPauseBeforeInstallMillis,
+		input.TestPauseAfterTreeMoveMillis,
+	} {
+		if pause < 0 || pause > 5000 {
+			return errors.New("test pause is outside its bounded range")
+		}
+	}
+	if input.Action == "observe" {
+		if input.Backend != "" {
+			return errors.New("observation does not support a backend")
+		}
+		if input.ID != "" || input.Operation != "" || input.Expected != nil || input.Target != nil {
+			return errors.New("observation has unexpected transaction fields")
+		}
+		if input.TestPauseAfterExtractionMillis != 0 ||
+			input.TestPauseBeforeInstallMillis != 0 ||
+			input.TestCrashAfterExtraction ||
+			input.TestCrashBeforeInstall ||
+			input.TestCrashAfterInstall {
+			return errors.New("observation has unexpected mutation test hooks")
+		}
+		return nil
+	}
+	if len(input.ID) != 64 {
+		return errors.New("transaction id must be a SHA-256 string")
+	}
+	if _, err := hex.DecodeString(input.ID); err != nil {
+		return errors.New("transaction id must be hexadecimal")
+	}
+	if input.Operation == "" || len(input.Operation) > 1024 {
+		return errors.New("operation identity is invalid")
+	}
+	if input.Backend == "git-lock" {
+		if input.Path != "index" && input.Path != "HEAD" {
+			return errors.New("git-lock path must be index or HEAD")
+		}
+		if input.Target == nil || input.Target.Kind != "file" || input.Target.Exec {
+			return errors.New("git-lock target must be a non-executable file")
+		}
+		if input.Expected != nil && (input.Expected.Kind != "file" || input.Expected.Exec) {
+			return errors.New("git-lock expected value must be a non-executable file")
+		}
+	}
+	if input.Backend == "git-guard" {
+		if input.Path != "HEAD" {
+			return errors.New("git-guard path must be HEAD")
+		}
+		if input.Target == nil || input.Target.Kind != "file" || input.Target.Exec {
+			return errors.New("git-guard target must be a non-executable file")
+		}
+		if input.Expected == nil || input.Expected.Kind != "file" || input.Expected.Exec {
+			return errors.New("git-guard expected value must be a non-executable file")
+		}
+		targetIdentity, err := requestedTargetIdentity(input.Target)
+		if err != nil {
+			return err
+		}
+		if !identitiesEqual(input.Expected, targetIdentity) {
+			return errors.New("git-guard target must equal its expected HEAD")
+		}
+	}
+	if input.Backend == "git-worktree-guard" {
+		if input.Path != "worktrees" {
+			return errors.New("git-worktree-guard path must be worktrees")
+		}
+		if input.Expected == nil || input.Expected.Kind != "directory" {
+			return errors.New("git-worktree-guard expected value must be a directory")
+		}
+		if input.Target == nil || input.Target.Kind != "file" || input.Target.Exec {
+			return errors.New("git-worktree-guard target must be a non-executable file")
+		}
+	}
+	if input.Expected != nil {
+		if input.Expected.Kind == "directory" && input.Backend != "git-worktree-guard" {
+			return errors.New("directory identity is only valid for a Git worktree guard")
+		}
+		if err := validateIdentity(*input.Expected); err != nil {
+			return fmt.Errorf("invalid expected identity: %w", err)
+		}
+	}
+	if input.Target != nil {
+		if input.Target.Kind != "file" && input.Target.Kind != "symlink" {
+			return errors.New("target kind must be file or symlink")
+		}
+		if err := validateIdentity(identity{
+			Kind:   input.Target.Kind,
+			Exec:   input.Target.Exec,
+			Bytes:  input.Target.Bytes,
+			SHA256: input.Target.SHA256,
+		}); err != nil {
+			return fmt.Errorf("invalid target identity: %w", err)
+		}
+		if input.Action == "apply" && input.Backend != "git-lock" {
+			if input.Target.Content == nil {
+				return errors.New("apply target content is missing")
+			}
+			content, err := base64.StdEncoding.DecodeString(*input.Target.Content)
+			if err != nil {
+				return errors.New("target content is not base64")
+			}
+			sum := sha256.Sum256(content)
+			if int64(len(content)) != input.Target.Bytes ||
+				hex.EncodeToString(sum[:]) != input.Target.SHA256 {
+				return errors.New("target content does not match its identity")
+			}
+		}
+	}
+	return nil
+}
+
+// moveTreeEntryNoReplace is the one descriptor-relative rename boundary used
+// by workspace-tree WALs. It never overwrites a destination that appeared
+// after JavaScript observed absence. Source identity remains caller-owned WAL
+// evidence and is reclassified after this atomic namespace operation.
+func moveTreeEntryNoReplace(input request) (response, error) {
+	source, err := openParent(input.Root, input.Source, false)
+	if err != nil {
+		if errors.Is(err, unix.ENOENT) || errors.Is(err, unix.ENOTDIR) {
+			return response{Status: "changed", Reason: "source changed before exclusive move"}, nil
+		}
+		return response{}, err
+	}
+	defer source.close()
+	target, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{}, err
+	}
+	defer target.close()
+	if err := verifyRootIdentity(source, input); err != nil {
+		return response{}, err
+	}
+	if err := verifyRootIdentity(target, input); err != nil {
+		return response{}, err
+	}
+	if !openedParentMatches(source, *input.SourceParentIdentity) {
+		return response{Status: "changed", Reason: "source parent changed before exclusive move"}, nil
+	}
+	if !openedParentMatches(target, *input.TargetParentIdentity) {
+		return response{Status: "changed", Reason: "target parent changed before exclusive move"}, nil
+	}
+	matches, err := matchesTreeEntryIdentity(
+		source.parentFD,
+		source.base,
+		*input.SourceIdentity,
+	)
+	if err != nil {
+		if errors.Is(err, unix.ENOENT) || errors.Is(err, unix.ENOTDIR) {
+			return response{Status: "changed", Reason: "source changed before exclusive move"}, nil
+		}
+		return response{}, err
+	}
+	if !matches {
+		return response{Status: "changed", Reason: "source changed before exclusive move"}, nil
+	}
+	if input.TestPauseBeforeInstallMillis > 0 {
+		time.Sleep(time.Duration(input.TestPauseBeforeInstallMillis) * time.Millisecond)
+	}
+	if err := moveNoReplace(source.parentFD, source.base, target.parentFD, target.base); err != nil {
+		if errors.Is(err, unix.EEXIST) || errors.Is(err, unix.ENOTEMPTY) {
+			return response{Status: "changed", Reason: "destination changed before exclusive move"}, nil
+		}
+		if errors.Is(err, unix.ENOENT) || errors.Is(err, unix.ENOTDIR) {
+			return response{Status: "changed", Reason: "source changed before exclusive move"}, nil
+		}
+		return response{}, fmt.Errorf("exclusive tree move: %w", err)
+	}
+	if input.TestPauseAfterTreeMoveMillis > 0 {
+		time.Sleep(time.Duration(input.TestPauseAfterTreeMoveMillis) * time.Millisecond)
+	}
+	if input.TestCrashAfterTreeMove {
+		os.Exit(89)
+	}
+	matches, err = matchesTreeEntryIdentity(
+		target.parentFD,
+		target.base,
+		*input.SourceIdentity,
+	)
+	if err != nil {
+		return response{}, fmt.Errorf("verify exclusive tree move source: %w", err)
+	}
+	if !matches {
+		undoErr := moveNoReplace(
+			target.parentFD,
+			target.base,
+			source.parentFD,
+			source.base,
+		)
+		if undoErr == nil {
+			if err := unix.Fsync(source.parentFD); err != nil {
+				return response{}, fmt.Errorf("sync undone tree move source parent: %w", err)
+			}
+			if target.parentFD != source.parentFD {
+				if err := unix.Fsync(target.parentFD); err != nil {
+					return response{}, fmt.Errorf("sync undone tree move target parent: %w", err)
+				}
+			}
+			return response{
+				Status: "changed",
+				Reason: "source changed during exclusive move and was restored",
+			}, nil
+		}
+		if errors.Is(undoErr, unix.EEXIST) || errors.Is(undoErr, unix.ENOTEMPTY) {
+			return response{
+				Status: "changed",
+				Reason: "source changed during exclusive move; both entries were retained",
+			}, nil
+		}
+		return response{}, fmt.Errorf("undo changed exclusive tree move: %w", undoErr)
+	}
+	if err := unix.Fsync(source.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync tree move source parent: %w", err)
+	}
+	if target.parentFD != source.parentFD {
+		if err := unix.Fsync(target.parentFD); err != nil {
+			return response{}, fmt.Errorf("sync tree move target parent: %w", err)
+		}
+	}
+	return response{Status: "applied"}, nil
+}
+
+func openedParentMatches(opened *openedParent, expected treeEntryIdentity) bool {
+	return expected.Kind == "folder" &&
+		strconv.FormatUint(opened.dev, 10) == expected.Dev &&
+		strconv.FormatUint(opened.ino, 10) == expected.Ino
+}
+
+func matchesTreeEntryIdentity(
+	dirFD int,
+	name string,
+	expected treeEntryIdentity,
+) (bool, error) {
+	var stat unix.Stat_t
+	if err := unix.Fstatat(dirFD, name, &stat, unix.AT_SYMLINK_NOFOLLOW); err != nil {
+		return false, err
+	}
+	var kind string
+	switch uint32(stat.Mode) & unix.S_IFMT {
+	case unix.S_IFREG:
+		kind = "file"
+	case unix.S_IFDIR:
+		kind = "folder"
+	case unix.S_IFLNK:
+		kind = "symlink"
+	default:
+		kind = "other"
+	}
+	return kind == expected.Kind &&
+		strconv.FormatUint(uint64(stat.Dev), 10) == expected.Dev &&
+		strconv.FormatUint(uint64(stat.Ino), 10) == expected.Ino, nil
+}
+
+func validateIdentity(value identity) error {
+	if value.Kind == "directory" {
+		if value.Exec || value.Bytes != 0 || value.SHA256 != "" {
+			return errors.New("directory identity has unexpected byte fields")
+		}
+		if _, err := strconv.ParseUint(value.Dev, 10, 64); err != nil {
+			return errors.New("directory device identity is invalid")
+		}
+		if _, err := strconv.ParseUint(value.Ino, 10, 64); err != nil {
+			return errors.New("directory inode identity is invalid")
+		}
+		return nil
+	}
+	if value.Kind != "file" && value.Kind != "symlink" {
+		return errors.New("kind must be file, symlink, or directory")
+	}
+	if (value.Dev == "") != (value.Ino == "") {
+		return errors.New("byte identity must name both device and inode or neither")
+	}
+	if value.Dev != "" {
+		if _, err := strconv.ParseUint(value.Dev, 10, 64); err != nil {
+			return errors.New("byte device identity is invalid")
+		}
+		if _, err := strconv.ParseUint(value.Ino, 10, 64); err != nil {
+			return errors.New("byte inode identity is invalid")
+		}
+	}
+	if value.Bytes < 0 || len(value.SHA256) != 64 {
+		return errors.New("byte identity is incomplete")
+	}
+	if _, err := hex.DecodeString(value.SHA256); err != nil {
+		return errors.New("sha256 must be hexadecimal")
+	}
+	return nil
+}
+
+func scratchName(id string) string {
+	return ".amalgm-apply-" + id
+}
+
+const (
+	preparedMarker = "prepared"
+	deletedMarker  = "deleted"
+	gitReceiptDir  = "amalgm-metadata-apply"
+)
+
+func openAbsoluteDirectoryNoFollow(directory string) (int, error) {
+	clean := filepath.Clean(directory)
+	currentFD, err := unix.Open(
+		string(filepath.Separator),
+		unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0,
+	)
+	if err != nil {
+		return -1, err
+	}
+	for _, component := range strings.Split(strings.TrimPrefix(clean, string(filepath.Separator)), string(filepath.Separator)) {
+		if component == "" {
+			continue
+		}
+		nextFD, openErr := unix.Openat(
+			currentFD,
+			component,
+			unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+			0,
+		)
+		_ = unix.Close(currentFD)
+		if openErr != nil {
+			return -1, openErr
+		}
+		currentFD = nextFD
+	}
+	return currentFD, nil
+}
+
+func openParent(root, relative string, create bool) (*openedParent, error) {
+	rootFD, err := openAbsoluteDirectoryNoFollow(root)
+	if err != nil {
+		return nil, fmt.Errorf("open root: %w", err)
+	}
+	components := strings.Split(relative, "/")
+	currentFD := rootFD
+	currentAbs := root
+	for _, component := range components[:len(components)-1] {
+		nextFD, openErr := unix.Openat(
+			currentFD,
+			component,
+			unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+			0,
+		)
+		if openErr != nil && errors.Is(openErr, unix.ENOENT) && create {
+			if mkdirErr := unix.Mkdirat(currentFD, component, 0o755); mkdirErr != nil &&
+				!errors.Is(mkdirErr, unix.EEXIST) {
+				closeParentFDs(rootFD, currentFD)
+				return nil, fmt.Errorf("create parent %q: %w", component, mkdirErr)
+			}
+			if syncErr := unix.Fsync(currentFD); syncErr != nil {
+				closeParentFDs(rootFD, currentFD)
+				return nil, fmt.Errorf("sync parent after mkdir: %w", syncErr)
+			}
+			nextFD, openErr = unix.Openat(
+				currentFD,
+				component,
+				unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+				0,
+			)
+		}
+		if openErr != nil {
+			closeParentFDs(rootFD, currentFD)
+			return nil, fmt.Errorf("open parent %q without following links: %w", component, openErr)
+		}
+		if currentFD != rootFD {
+			_ = unix.Close(currentFD)
+		}
+		currentFD = nextFD
+		currentAbs = filepath.Join(currentAbs, component)
+	}
+	var stat unix.Stat_t
+	if err := unix.Fstat(currentFD, &stat); err != nil {
+		closeParentFDs(rootFD, currentFD)
+		return nil, fmt.Errorf("stat parent: %w", err)
+	}
+	return &openedParent{
+		rootFD:    rootFD,
+		parentFD:  currentFD,
+		parentAbs: currentAbs,
+		base:      components[len(components)-1],
+		dev:       uint64(stat.Dev),
+		ino:       uint64(stat.Ino),
+	}, nil
+}
+
+func verifyRootIdentity(opened *openedParent, input request) error {
+	expectedDev, _ := strconv.ParseUint(input.RootDev, 10, 64)
+	expectedIno, _ := strconv.ParseUint(input.RootIno, 10, 64)
+	var stat unix.Stat_t
+	if err := unix.Fstat(opened.rootFD, &stat); err != nil {
+		return fmt.Errorf("stat opened root: %w", err)
+	}
+	if uint64(stat.Dev) != expectedDev || uint64(stat.Ino) != expectedIno {
+		return errors.New("workspace root changed before file transaction")
+	}
+	return nil
+}
+
+func closeParentFDs(rootFD, parentFD int) {
+	if parentFD >= 0 && parentFD != rootFD {
+		_ = unix.Close(parentFD)
+	}
+	if rootFD >= 0 {
+		_ = unix.Close(rootFD)
+	}
+}
+
+func (opened *openedParent) close() {
+	closeParentFDs(opened.rootFD, opened.parentFD)
+	opened.rootFD = -1
+	opened.parentFD = -1
+}
+
+const maxObservedBytes = 16 * 1024 * 1024
+
+func readObservedFile(fd int) ([]byte, error) {
+	if _, err := unix.Seek(fd, 0, io.SeekStart); err != nil {
+		return nil, fmt.Errorf("seek observed file: %w", err)
+	}
+	content := make([]byte, 0, 64*1024)
+	buffer := make([]byte, 64*1024)
+	for {
+		count, err := unix.Read(fd, buffer)
+		if count > 0 {
+			if len(content)+count > maxObservedBytes {
+				return nil, fmt.Errorf("observed file exceeds %d bytes", maxObservedBytes)
+			}
+			content = append(content, buffer[:count]...)
+		}
+		if err != nil {
+			if errors.Is(err, unix.EINTR) {
+				continue
+			}
+			return nil, fmt.Errorf("read observed file: %w", err)
+		}
+		if count == 0 {
+			return content, nil
+		}
+	}
+}
+
+func sameObservedStat(left, right unix.Stat_t) bool {
+	return left.Dev == right.Dev &&
+		left.Ino == right.Ino &&
+		left.Mode == right.Mode &&
+		left.Size == right.Size &&
+		statChangedAt(left) == statChangedAt(right)
+}
+
+// observe is the descriptor-relative read boundary. The parent directory and
+// child file stay pinned from identity through bytes, so a rename followed by
+// a replacement at the old spelling can never combine two physical objects
+// into one observation.
+func observe(input request) (response, error) {
+	opened, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{}, err
+	}
+	defer opened.close()
+	if err := verifyRootIdentity(opened, input); err != nil {
+		return response{}, err
+	}
+	if input.TestPauseAfterParentOpenMillis > 0 {
+		time.Sleep(time.Duration(input.TestPauseAfterParentOpenMillis) * time.Millisecond)
+	}
+
+	fd, err := unix.Openat(
+		opened.parentFD,
+		opened.base,
+		unix.O_RDONLY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0,
+	)
+	if errors.Is(err, unix.ENOENT) {
+		return response{
+			Status:  "observed",
+			RootDev: input.RootDev,
+			RootIno: input.RootIno,
+			Path:    input.Path,
+		}, nil
+	}
+	if err != nil {
+		return response{}, fmt.Errorf("open observed file: %w", err)
+	}
+	defer unix.Close(fd)
+
+	var before unix.Stat_t
+	if err := unix.Fstat(fd, &before); err != nil {
+		return response{}, fmt.Errorf("stat observed file: %w", err)
+	}
+	if uint32(before.Mode)&unix.S_IFMT != unix.S_IFREG {
+		return response{}, errors.New("observed path is not a regular file")
+	}
+	first, err := readObservedFile(fd)
+	if err != nil {
+		return response{}, err
+	}
+	var middle unix.Stat_t
+	if err := unix.Fstat(fd, &middle); err != nil {
+		return response{}, fmt.Errorf("restat observed file: %w", err)
+	}
+	second, err := readObservedFile(fd)
+	if err != nil {
+		return response{}, err
+	}
+	var after unix.Stat_t
+	if err := unix.Fstat(fd, &after); err != nil {
+		return response{}, fmt.Errorf("final stat observed file: %w", err)
+	}
+	if !sameObservedStat(before, middle) ||
+		!sameObservedStat(middle, after) ||
+		int64(len(second)) != after.Size ||
+		!bytes.Equal(first, second) {
+		return response{Status: "changed", Reason: "file changed during observation"}, nil
+	}
+
+	sum := sha256.Sum256(second)
+	content := base64.StdEncoding.EncodeToString(second)
+	value := &identity{
+		Kind:   "file",
+		Exec:   uint32(after.Mode)&0o100 != 0,
+		Bytes:  int64(len(second)),
+		SHA256: hex.EncodeToString(sum[:]),
+		Dev:    strconv.FormatUint(uint64(after.Dev), 10),
+		Ino:    strconv.FormatUint(uint64(after.Ino), 10),
+	}
+	return response{
+		Status:  "observed",
+		RootDev: input.RootDev,
+		RootIno: input.RootIno,
+		Path:    input.Path,
+		Value:   value,
+		Content: &content,
+	}, nil
+}
+
+func reopenParent(input request, dev, ino uint64) (bool, error) {
+	reopened, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return false, nil
+	}
+	defer reopened.close()
+	if err := verifyRootIdentity(reopened, input); err != nil {
+		return false, nil
+	}
+	return reopened.dev == dev && reopened.ino == ino, nil
+}
+
+func apply(input request) (response, error) {
+	opened, err := openParent(input.Root, input.Path, true)
+	if err != nil {
+		return response{}, err
+	}
+	defer opened.close()
+	if err := verifyRootIdentity(opened, input); err != nil {
+		return response{}, err
+	}
+	if input.TestPauseAfterParentOpenMillis > 0 {
+		time.Sleep(time.Duration(input.TestPauseAfterParentOpenMillis) * time.Millisecond)
+	}
+	scratch := scratchName(input.ID)
+	if err := unix.Mkdirat(opened.parentFD, scratch, 0o700); err != nil {
+		return response{}, fmt.Errorf("create transaction scratch: %w", err)
+	}
+	if err := unix.Fsync(opened.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync scratch parent: %w", err)
+	}
+	scratchFD, err := unix.Openat(
+		opened.parentFD,
+		scratch,
+		unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0,
+	)
+	if err != nil {
+		return response{}, fmt.Errorf("open transaction scratch: %w", err)
+	}
+	defer unix.Close(scratchFD)
+
+	if input.Target != nil {
+		if err := prepareTarget(scratchFD, *input.Target); err != nil {
+			return response{}, err
+		}
+		if err := writeMarker(scratchFD, preparedMarker); err != nil {
+			return response{}, fmt.Errorf("record prepared target: %w", err)
+		}
+	}
+
+	if input.Expected == nil {
+		if held, err := identityAt(opened.parentFD, opened.base); err != nil {
+			return response{}, err
+		} else if held != nil {
+			if cleanupErr := cleanupScratch(opened.parentFD, scratchFD, scratch); cleanupErr != nil {
+				return response{}, cleanupErr
+			}
+			return response{Status: "changed", Reason: "destination appeared before create"}, nil
+		}
+	} else {
+		if err := unix.Renameat(opened.parentFD, opened.base, scratchFD, "source"); err != nil {
+			return response{}, fmt.Errorf("extract expected source: %w", err)
+		}
+		if err := syncBoth(opened.parentFD, scratchFD); err != nil {
+			return response{}, err
+		}
+		if input.TestCrashAfterExtraction {
+			os.Exit(86)
+		}
+		if input.TestPauseAfterExtractionMillis > 0 {
+			time.Sleep(time.Duration(input.TestPauseAfterExtractionMillis) * time.Millisecond)
+		}
+		anchored, err := reopenParent(input, opened.dev, opened.ino)
+		if err != nil {
+			return response{}, err
+		}
+		if !anchored {
+			return rollbackExtracted(
+				opened,
+				scratchFD,
+				scratch,
+				input,
+				"repository parent changed during apply",
+			)
+		}
+		writable, err := hasWritableOpen(
+			scratchFD,
+			"source",
+			filepath.Join(opened.parentAbs, scratch, "source"),
+		)
+		if err != nil {
+			return response{}, fmt.Errorf("inspect extracted source writers: %w", err)
+		}
+		if writable {
+			return rollbackExtracted(
+				opened,
+				scratchFD,
+				scratch,
+				input,
+				"pre-existing writer still owns the source inode",
+			)
+		}
+		held, err := identityAt(scratchFD, "source")
+		if err != nil {
+			return response{}, err
+		}
+		if !identitiesEqual(held, input.Expected) {
+			return rollbackExtracted(
+				opened,
+				scratchFD,
+				scratch,
+				input,
+				"source changed before ordered apply",
+			)
+		}
+	}
+
+	anchored, err := reopenParent(input, opened.dev, opened.ino)
+	if err != nil {
+		return response{}, err
+	}
+	if !anchored {
+		if input.Expected != nil {
+			return rollbackExtracted(
+				opened,
+				scratchFD,
+				scratch,
+				input,
+				"repository parent changed during apply",
+			)
+		}
+		if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+			return response{}, err
+		}
+		return response{Status: "changed", Reason: "repository parent changed during create"}, nil
+	}
+	if input.TestPauseBeforeInstallMillis > 0 {
+		time.Sleep(time.Duration(input.TestPauseBeforeInstallMillis) * time.Millisecond)
+	}
+	if input.TestCrashBeforeInstall {
+		os.Exit(87)
+	}
+
+	if input.Target != nil {
+		if err := moveNoReplace(scratchFD, "target", opened.parentFD, opened.base); err != nil {
+			if errors.Is(err, unix.EEXIST) {
+				if input.Expected != nil {
+					return rollbackExtracted(
+						opened,
+						scratchFD,
+						scratch,
+						input,
+						"destination changed before exclusive install",
+					)
+				}
+				if cleanupErr := cleanupScratch(opened.parentFD, scratchFD, scratch); cleanupErr != nil {
+					return response{}, cleanupErr
+				}
+				return response{Status: "changed", Reason: "destination changed before exclusive install"}, nil
+			}
+			return response{}, fmt.Errorf("install target: %w", err)
+		}
+		if err := syncBoth(opened.parentFD, scratchFD); err != nil {
+			return response{}, fmt.Errorf("sync installed target: %w", err)
+		}
+		if input.TestCrashAfterInstall {
+			os.Exit(88)
+		}
+	}
+
+	anchored, err = reopenParent(input, opened.dev, opened.ino)
+	if err != nil {
+		return response{}, err
+	}
+	if !anchored {
+		if input.Expected != nil {
+			return restoreSourceOverTarget(
+				opened,
+				scratchFD,
+				scratch,
+				input,
+				"repository parent changed during target install",
+			)
+		}
+		if input.Target != nil {
+			_ = unix.Unlinkat(opened.parentFD, opened.base, 0)
+			_ = unix.Fsync(opened.parentFD)
+		}
+		if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+			return response{}, err
+		}
+		return response{Status: "changed", Reason: "repository parent changed during target install"}, nil
+	}
+
+	if input.Target == nil {
+		if err := writeMarker(scratchFD, deletedMarker); err != nil {
+			return response{}, fmt.Errorf("record ordered deletion: %w", err)
+		}
+	}
+	// The scratch directory is the receipt. It survives the successful
+	// transaction and is removed only after the caller durably advances its
+	// verified cursor.
+	return response{Status: "applied"}, nil
+}
+
+func gitPreparedPath(id string) string {
+	return gitReceiptDir + "/" + id + ".target"
+}
+
+func gitClaimedName(id string) string {
+	return id + ".claimed"
+}
+
+func gitLockName(input request) string {
+	return input.Path + ".lock"
+}
+
+func openGitReceipt(input request) (*openedParent, error) {
+	receipt, err := openParent(input.Root, gitPreparedPath(input.ID), false)
+	if err != nil {
+		return nil, err
+	}
+	if err := verifyRootIdentity(receipt, input); err != nil {
+		receipt.close()
+		return nil, err
+	}
+	return receipt, nil
+}
+
+func sameInode(
+	leftFD int,
+	leftName string,
+	rightFD int,
+	rightName string,
+) (same bool, rightExists bool, err error) {
+	var left unix.Stat_t
+	if err := unix.Fstatat(leftFD, leftName, &left, unix.AT_SYMLINK_NOFOLLOW); err != nil {
+		return false, false, fmt.Errorf("stat receipt %q: %w", leftName, err)
+	}
+	var right unix.Stat_t
+	if err := unix.Fstatat(rightFD, rightName, &right, unix.AT_SYMLINK_NOFOLLOW); err != nil {
+		if errors.Is(err, unix.ENOENT) {
+			return false, false, nil
+		}
+		return false, false, fmt.Errorf("stat lock %q: %w", rightName, err)
+	}
+	return left.Dev == right.Dev && left.Ino == right.Ino, true, nil
+}
+
+func syncEntry(dirFD int, name string) error {
+	fd, err := unix.Openat(
+		dirFD,
+		name,
+		unix.O_RDONLY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0,
+	)
+	if err != nil {
+		return err
+	}
+	if err := unix.Fsync(fd); err != nil {
+		_ = unix.Close(fd)
+		return err
+	}
+	return unix.Close(fd)
+}
+
+func cleanupGitReceipt(receipt *openedParent, input request) error {
+	for _, name := range []string{receipt.base, gitClaimedName(input.ID)} {
+		if err := removeAt(receipt.parentFD, name, 0); err != nil {
+			return fmt.Errorf("remove Git metadata receipt %q: %w", name, err)
+		}
+	}
+	if err := unix.Fsync(receipt.parentFD); err != nil {
+		return fmt.Errorf("sync Git metadata receipt removal: %w", err)
+	}
+	return nil
+}
+
+func gitLockCrossed(
+	destination *openedParent,
+	receipt *openedParent,
+	input request,
+) (bool, error) {
+	claimed, err := existsAt(receipt.parentFD, gitClaimedName(input.ID))
+	if err != nil {
+		return false, err
+	}
+	if !claimed {
+		return false, nil
+	}
+	same, _, err := sameInode(
+		receipt.parentFD,
+		gitClaimedName(input.ID),
+		destination.parentFD,
+		gitLockName(input),
+	)
+	if err != nil {
+		return false, err
+	}
+	// The claimed hard link survives the canonical lock's rename. A missing
+	// lock, or a later lock with another inode, therefore proves this
+	// operation crossed without consulting the destination's current bytes.
+	return !same, nil
+}
+
+func removeOwnedGitLock(
+	destination *openedParent,
+	receipt *openedParent,
+	input request,
+) error {
+	lock := gitLockName(input)
+	for _, receiptName := range []string{gitClaimedName(input.ID), receipt.base} {
+		exists, err := existsAt(receipt.parentFD, receiptName)
+		if err != nil {
+			return err
+		}
+		if !exists {
+			continue
+		}
+		same, _, err := sameInode(
+			receipt.parentFD,
+			receiptName,
+			destination.parentFD,
+			lock,
+		)
+		if err != nil {
+			return err
+		}
+		if same {
+			if err := removeAt(destination.parentFD, lock, 0); err != nil {
+				return fmt.Errorf("remove retained Git lock: %w", err)
+			}
+			return unix.Fsync(destination.parentFD)
+		}
+	}
+	return nil
+}
+
+// applyGitLock uses the same lock name Git itself uses. The target is prepared
+// durably in the per-worktree Git directory before this process starts. An
+// exclusive hard link claims index.lock/HEAD.lock without copying large index
+// bytes through JSON. Renaming that lock over the destination is the one
+// crossing step; the retained hard link is its operation-owned receipt.
+func applyGitLock(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{}, err
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{}, err
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{}, fmt.Errorf("open prepared Git metadata: %w", err)
+	}
+	defer receipt.close()
+
+	prepared, err := identityAt(receipt.parentFD, receipt.base)
+	if err != nil {
+		return response{}, err
+	}
+	targetIdentity, err := requestedTargetIdentity(input.Target)
+	if err != nil {
+		return response{}, err
+	}
+	if !identitiesEqual(prepared, targetIdentity) {
+		return response{}, errors.New("prepared Git metadata does not match target identity")
+	}
+
+	lock := gitLockName(input)
+	if err := unix.Linkat(
+		receipt.parentFD,
+		receipt.base,
+		destination.parentFD,
+		lock,
+		0,
+	); err != nil {
+		if errors.Is(err, unix.EEXIST) {
+			return response{Status: "pending", Reason: "Git metadata lock is already held"}, nil
+		}
+		return response{}, fmt.Errorf("claim Git metadata lock: %w", err)
+	}
+	if err := syncEntry(destination.parentFD, lock); err != nil {
+		return response{}, fmt.Errorf("sync Git metadata lock: %w", err)
+	}
+	if err := unix.Fsync(destination.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync claimed Git metadata lock: %w", err)
+	}
+
+	current, err := identityAt(destination.parentFD, destination.base)
+	if err != nil {
+		return response{}, err
+	}
+	if !identitiesEqual(current, input.Expected) {
+		if err := removeOwnedGitLock(destination, receipt, input); err != nil {
+			return response{}, err
+		}
+		if err := cleanupGitReceipt(receipt, input); err != nil {
+			return response{}, err
+		}
+		return response{Status: "changed", Reason: "Git metadata changed before ordered apply"}, nil
+	}
+
+	if err := unix.Linkat(
+		destination.parentFD,
+		lock,
+		receipt.parentFD,
+		gitClaimedName(input.ID),
+		0,
+	); err != nil {
+		return response{}, fmt.Errorf("record claimed Git metadata lock: %w", err)
+	}
+	if err := unix.Fsync(receipt.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync claimed Git metadata receipt: %w", err)
+	}
+	if input.TestCrashBeforeInstall {
+		os.Exit(87)
+	}
+	if err := unix.Renameat(
+		destination.parentFD,
+		lock,
+		destination.parentFD,
+		destination.base,
+	); err != nil {
+		return response{}, fmt.Errorf("install Git metadata target: %w", err)
+	}
+	if err := unix.Fsync(destination.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync installed Git metadata: %w", err)
+	}
+	if input.TestCrashAfterInstall {
+		os.Exit(88)
+	}
+	return response{Status: "applied"}, nil
+}
+
+// guardGitLock retains Git's canonical HEAD.lock while a branch-ref
+// transaction runs. Exact HEAD bytes are verified only after the lock is
+// owned, so no checkout or symbolic-ref change can enter between that proof
+// and the guarded ref movement.
+func guardGitLock(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{}, err
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{}, err
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{}, fmt.Errorf("open prepared Git guard: %w", err)
+	}
+	defer receipt.close()
+
+	prepared, err := identityAt(receipt.parentFD, receipt.base)
+	if err != nil {
+		return response{}, err
+	}
+	targetIdentity, err := requestedTargetIdentity(input.Target)
+	if err != nil {
+		return response{}, err
+	}
+	if !identitiesEqual(prepared, targetIdentity) {
+		return response{}, errors.New("prepared Git guard does not match expected HEAD")
+	}
+
+	lock := gitLockName(input)
+	if err := unix.Linkat(
+		receipt.parentFD,
+		receipt.base,
+		destination.parentFD,
+		lock,
+		0,
+	); err != nil {
+		if errors.Is(err, unix.EEXIST) {
+			return response{Status: "pending", Reason: "Git HEAD lock is already held"}, nil
+		}
+		return response{}, fmt.Errorf("claim Git HEAD guard: %w", err)
+	}
+	if err := syncEntry(destination.parentFD, lock); err != nil {
+		return response{}, fmt.Errorf("sync Git HEAD guard: %w", err)
+	}
+	if err := unix.Fsync(destination.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync claimed Git HEAD guard: %w", err)
+	}
+	if err := unix.Linkat(
+		destination.parentFD,
+		lock,
+		receipt.parentFD,
+		gitClaimedName(input.ID),
+		0,
+	); err != nil {
+		return response{}, fmt.Errorf("record claimed Git HEAD guard: %w", err)
+	}
+	if err := unix.Fsync(receipt.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync claimed Git HEAD guard receipt: %w", err)
+	}
+
+	current, err := identityAt(destination.parentFD, destination.base)
+	if err != nil {
+		return response{}, err
+	}
+	if !identitiesEqual(current, input.Expected) {
+		if err := removeOwnedGitLock(destination, receipt, input); err != nil {
+			return response{}, err
+		}
+		if err := cleanupGitReceipt(receipt, input); err != nil {
+			return response{}, err
+		}
+		return response{Status: "changed", Reason: "HEAD changed before branch guard"}, nil
+	}
+	return response{Status: "guarded"}, nil
+}
+
+func releaseGitGuard(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{Status: "released"}, nil
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{}, err
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{Status: "released"}, nil
+	}
+	defer receipt.close()
+	if err := removeOwnedGitLock(destination, receipt, input); err != nil {
+		return response{}, err
+	}
+	if err := cleanupGitReceipt(receipt, input); err != nil {
+		return response{}, err
+	}
+	return response{Status: "released"}, nil
+}
+
+// guardGitWorktreeNamespace atomically exchanges the common `worktrees`
+// directory with an operation-owned regular file. Stock Git therefore
+// cannot register a new linked worktree until the deletion transaction
+// finishes, while the complete original directory remains recoverable at
+// the prepared receipt path.
+func guardGitWorktreeNamespace(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{}, err
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{}, err
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{}, fmt.Errorf("open prepared worktree namespace guard: %w", err)
+	}
+	defer receipt.close()
+
+	current, err := identityAt(destination.parentFD, destination.base)
+	if err != nil {
+		return response{}, err
+	}
+	if !identitiesEqual(current, input.Expected) {
+		return response{Status: "changed", Reason: "Git worktree namespace changed before guard"}, nil
+	}
+	prepared, err := identityAt(receipt.parentFD, receipt.base)
+	if err != nil {
+		return response{}, err
+	}
+	targetIdentity, err := requestedTargetIdentity(input.Target)
+	if err != nil {
+		return response{}, err
+	}
+	if !identitiesEqual(prepared, targetIdentity) {
+		return response{}, errors.New("prepared worktree namespace marker does not match target")
+	}
+
+	if err := unix.Linkat(
+		receipt.parentFD,
+		receipt.base,
+		receipt.parentFD,
+		gitClaimedName(input.ID),
+		0,
+	); err != nil {
+		if !errors.Is(err, unix.EEXIST) {
+			return response{}, fmt.Errorf("record claimed worktree namespace guard: %w", err)
+		}
+		same, _, sameErr := sameInode(
+			receipt.parentFD,
+			receipt.base,
+			receipt.parentFD,
+			gitClaimedName(input.ID),
+		)
+		if sameErr != nil {
+			return response{}, sameErr
+		}
+		if !same {
+			return response{}, errors.New("worktree namespace guard claim belongs to another inode")
+		}
+	}
+	if err := unix.Fsync(receipt.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync claimed worktree namespace guard: %w", err)
+	}
+	if err := exchangeEntries(
+		destination.parentFD,
+		destination.base,
+		receipt.parentFD,
+		receipt.base,
+	); err != nil {
+		return response{}, fmt.Errorf("guard Git worktree namespace: %w", err)
+	}
+	if err := unix.Fsync(destination.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync guarded Git worktree namespace: %w", err)
+	}
+	if err := unix.Fsync(receipt.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync retained Git worktree namespace: %w", err)
+	}
+	same, _, err := sameInode(
+		receipt.parentFD,
+		gitClaimedName(input.ID),
+		destination.parentFD,
+		destination.base,
+	)
+	if err != nil {
+		return response{}, err
+	}
+	if !same {
+		return response{}, errors.New("Git worktree namespace guard did not retain its marker")
+	}
+	return response{Status: "guarded"}, nil
+}
+
+func releaseGitWorktreeNamespace(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{}, fmt.Errorf("open guarded worktree namespace: %w", err)
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{}, err
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{Status: "released"}, nil
+	}
+	defer receipt.close()
+	claimed, err := existsAt(receipt.parentFD, gitClaimedName(input.ID))
+	if err != nil {
+		return response{}, err
+	}
+	prepared, err := existsAt(receipt.parentFD, receipt.base)
+	if err != nil {
+		return response{}, err
+	}
+	if !claimed && !prepared {
+		return response{Status: "released"}, nil
+	}
+	if !claimed && prepared {
+		if err := cleanupGitReceipt(receipt, input); err != nil {
+			return response{}, err
+		}
+		return response{Status: "released"}, nil
+	}
+	if !prepared {
+		current, err := identityAt(destination.parentFD, destination.base)
+		if err != nil {
+			return response{}, err
+		}
+		if !identitiesEqual(current, input.Expected) {
+			return response{}, errors.New("worktree namespace guard receipt is incomplete")
+		}
+		if err := cleanupGitReceipt(receipt, input); err != nil {
+			return response{}, err
+		}
+		return response{Status: "released"}, nil
+	}
+	guarded, _, err := sameInode(
+		receipt.parentFD,
+		gitClaimedName(input.ID),
+		destination.parentFD,
+		destination.base,
+	)
+	if err != nil {
+		return response{}, err
+	}
+	if guarded {
+		retained, err := identityAt(receipt.parentFD, receipt.base)
+		if err != nil {
+			return response{}, err
+		}
+		if retained == nil || retained.Kind != "directory" {
+			return response{}, errors.New("retained Git worktree namespace is not a directory")
+		}
+		if err := exchangeEntries(
+			destination.parentFD,
+			destination.base,
+			receipt.parentFD,
+			receipt.base,
+		); err != nil {
+			return response{}, fmt.Errorf("restore Git worktree namespace: %w", err)
+		}
+		if err := unix.Fsync(destination.parentFD); err != nil {
+			return response{}, fmt.Errorf("sync restored Git worktree namespace: %w", err)
+		}
+		if err := unix.Fsync(receipt.parentFD); err != nil {
+			return response{}, fmt.Errorf("sync released worktree namespace marker: %w", err)
+		}
+	} else {
+		current, err := identityAt(destination.parentFD, destination.base)
+		if err != nil {
+			return response{}, err
+		}
+		retainedMarker, _, err := sameInode(
+			receipt.parentFD,
+			gitClaimedName(input.ID),
+			receipt.parentFD,
+			receipt.base,
+		)
+		if err != nil {
+			return response{}, err
+		}
+		if current == nil || current.Kind != "directory" || !retainedMarker {
+			return response{}, errors.New("Git worktree namespace changed outside its guard")
+		}
+	}
+	if err := cleanupGitReceipt(receipt, input); err != nil {
+		return response{}, err
+	}
+	return response{Status: "released"}, nil
+}
+
+func recoverGitLock(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{Status: "pending", Reason: "Git metadata path is not safely reachable"}, nil
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{Status: "pending", Reason: err.Error()}, nil
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{Status: "changed", Reason: "operation has no Git metadata receipt"}, nil
+	}
+	defer receipt.close()
+	crossed, err := gitLockCrossed(destination, receipt, input)
+	if err != nil {
+		return response{}, err
+	}
+	if crossed {
+		return response{Status: "applied"}, nil
+	}
+	if err := removeOwnedGitLock(destination, receipt, input); err != nil {
+		return response{}, err
+	}
+	if err := cleanupGitReceipt(receipt, input); err != nil {
+		return response{}, err
+	}
+	return response{Status: "changed", Reason: "Git metadata operation stopped before crossing"}, nil
+}
+
+func readGitLockReceipt(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{Status: "not-crossed"}, nil
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{Status: "not-crossed"}, nil
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{Status: "not-crossed"}, nil
+	}
+	defer receipt.close()
+	crossed, err := gitLockCrossed(destination, receipt, input)
+	if err != nil {
+		return response{}, err
+	}
+	if crossed {
+		return response{Status: "crossed"}, nil
+	}
+	return response{Status: "not-crossed"}, nil
+}
+
+func releaseGitLockReceipt(input request) (response, error) {
+	destination, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{Status: "released"}, nil
+	}
+	defer destination.close()
+	if err := verifyRootIdentity(destination, input); err != nil {
+		return response{}, err
+	}
+	receipt, err := openGitReceipt(input)
+	if err != nil {
+		return response{Status: "released"}, nil
+	}
+	defer receipt.close()
+	prepared, err := existsAt(receipt.parentFD, receipt.base)
+	if err != nil {
+		return response{}, err
+	}
+	claimed, err := existsAt(receipt.parentFD, gitClaimedName(input.ID))
+	if err != nil {
+		return response{}, err
+	}
+	// Native cleanup is durable before the JavaScript control record is
+	// removed. A crash in that final gap leaves neither artifact; release is
+	// therefore already complete and must remain idempotent.
+	if !prepared && !claimed {
+		return response{Status: "released"}, nil
+	}
+	crossed, err := gitLockCrossed(destination, receipt, input)
+	if err != nil {
+		return response{}, err
+	}
+	if !crossed {
+		return response{Status: "pending", Reason: "operation has no Git metadata crossing receipt"}, nil
+	}
+	if err := cleanupGitReceipt(receipt, input); err != nil {
+		return response{}, err
+	}
+	return response{Status: "released"}, nil
+}
+
+func rollbackExtracted(
+	opened *openedParent,
+	scratchFD int,
+	scratch string,
+	input request,
+	reason string,
+) (response, error) {
+	if err := linkEntry(scratchFD, "source", opened.parentFD, opened.base); err != nil {
+		if errors.Is(err, unix.EEXIST) {
+			return response{Status: "pending", Reason: reason + "; a newer destination also exists"}, nil
+		}
+		return response{}, fmt.Errorf("restore extracted source: %w", err)
+	}
+	if err := unix.Fsync(opened.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync restored source: %w", err)
+	}
+	if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+		return response{}, err
+	}
+	return response{Status: "changed", Reason: reason}, nil
+}
+
+func restoreSourceOverTarget(
+	opened *openedParent,
+	scratchFD int,
+	scratch string,
+	input request,
+	reason string,
+) (response, error) {
+	current, err := identityAt(opened.parentFD, opened.base)
+	if err != nil {
+		return response{}, err
+	}
+	targetIdentity, err := requestedTargetIdentity(input.Target)
+	if err != nil {
+		return response{}, err
+	}
+	if current != nil {
+		if !identitiesEqual(current, targetIdentity) {
+			return response{Status: "pending", Reason: reason + "; a newer destination also exists"}, nil
+		}
+		if err := unix.Renameat(opened.parentFD, opened.base, scratchFD, "current"); err != nil {
+			return response{}, fmt.Errorf("retain installed target during rollback: %w", err)
+		}
+	}
+	if err := linkEntry(scratchFD, "source", opened.parentFD, opened.base); err != nil {
+		if current != nil {
+			_ = unix.Renameat(scratchFD, "current", opened.parentFD, opened.base)
+		}
+		return response{}, fmt.Errorf("restore source over target: %w", err)
+	}
+	if err := unix.Fsync(opened.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync source rollback: %w", err)
+	}
+	if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+		return response{}, err
+	}
+	return response{Status: "changed", Reason: reason}, nil
+}
+
+func recoverTransaction(input request) (response, error) {
+	opened, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{Status: "pending", Reason: "recorded parent is not safely reachable"}, nil
+	}
+	defer opened.close()
+	if err := verifyRootIdentity(opened, input); err != nil {
+		return response{Status: "pending", Reason: err.Error()}, nil
+	}
+	scratch := scratchName(input.ID)
+	scratchFD, err := unix.Openat(
+		opened.parentFD,
+		scratch,
+		unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0,
+	)
+	if errors.Is(err, unix.ENOENT) {
+		return classifyWithoutScratch(opened, input)
+	}
+	if err != nil {
+		return response{}, fmt.Errorf("open retained transaction scratch: %w", err)
+	}
+	defer unix.Close(scratchFD)
+
+	crossed, err := transactionCrossed(scratchFD, input)
+	if err != nil {
+		return response{}, err
+	}
+	if crossed {
+		return response{Status: "applied"}, nil
+	}
+
+	source, err := identityAt(scratchFD, "source")
+	if err != nil {
+		return response{}, err
+	}
+	current, err := identityAt(opened.parentFD, opened.base)
+	if err != nil {
+		return response{}, err
+	}
+	targetIdentity, err := requestedTargetIdentity(input.Target)
+	if err != nil {
+		return response{}, err
+	}
+
+	if source != nil {
+		writable, err := hasWritableOpen(
+			scratchFD,
+			"source",
+			filepath.Join(opened.parentAbs, scratch, "source"),
+		)
+		if err != nil {
+			return response{}, err
+		}
+		sourceIsExpected := identitiesEqual(source, input.Expected)
+		if writable || !sourceIsExpected {
+			if current == nil {
+				return rollbackExtracted(
+					opened,
+					scratchFD,
+					scratch,
+					input,
+					"retained source is local or still writable",
+				)
+			}
+			if identitiesEqual(current, targetIdentity) {
+				return restoreSourceOverTarget(
+					opened,
+					scratchFD,
+					scratch,
+					input,
+					"retained source is local or still writable",
+				)
+			}
+			if !writable {
+				sourceTime, sourceTimeErr := entryChangedAt(scratchFD, "source")
+				if sourceTimeErr != nil {
+					return response{}, sourceTimeErr
+				}
+				currentTime, currentTimeErr := entryChangedAt(opened.parentFD, opened.base)
+				if currentTimeErr != nil {
+					return response{}, currentTimeErr
+				}
+				if sourceTime > currentTime {
+					return replaceCurrentWithSource(
+						opened,
+						scratchFD,
+						scratch,
+						"retained source is the later local write",
+					)
+				}
+				if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+					return response{}, err
+				}
+				return response{
+					Status: "changed",
+					Reason: "visible destination is the later local write",
+				}, nil
+			}
+			return response{
+				Status: "pending",
+				Reason: "retained source and visible destination are both local",
+			}, nil
+		}
+		if identitiesEqual(current, targetIdentity) || (input.Target == nil && current == nil) {
+			if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+				return response{}, err
+			}
+			return response{Status: "applied"}, nil
+		}
+		if current == nil {
+			return rollbackExtracted(
+				opened,
+				scratchFD,
+				scratch,
+				input,
+				"apply stopped before target installation",
+			)
+		}
+		if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+			return response{}, err
+		}
+		return response{Status: "changed", Reason: "newer visible destination won interrupted apply"}, nil
+	}
+
+	if identitiesEqual(current, targetIdentity) || (input.Target == nil && current == nil) {
+		if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+			return response{}, err
+		}
+		return response{Status: "applied"}, nil
+	}
+	if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+		return response{}, err
+	}
+	return response{Status: "changed", Reason: "visible destination superseded interrupted apply"}, nil
+}
+
+func readReceipt(input request) (response, error) {
+	opened, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		return response{Status: "not-crossed"}, nil
+	}
+	defer opened.close()
+	if err := verifyRootIdentity(opened, input); err != nil {
+		return response{Status: "not-crossed"}, nil
+	}
+	scratchFD, err := unix.Openat(
+		opened.parentFD,
+		scratchName(input.ID),
+		unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0,
+	)
+	if errors.Is(err, unix.ENOENT) {
+		return response{Status: "not-crossed"}, nil
+	}
+	if err != nil {
+		return response{}, fmt.Errorf("open receipt artifact: %w", err)
+	}
+	defer unix.Close(scratchFD)
+	crossed, err := transactionCrossed(scratchFD, input)
+	if err != nil {
+		return response{}, err
+	}
+	if crossed {
+		return response{Status: "crossed"}, nil
+	}
+	return response{Status: "not-crossed"}, nil
+}
+
+func releaseReceipt(input request) (response, error) {
+	opened, err := openParent(input.Root, input.Path, false)
+	if err != nil {
+		// A missing locator does not prove the operation-owned receipt is
+		// absent. The physical parent may merely have moved and will be rebound
+		// by the durable document plan. Keep that plan until the exact parent
+		// can be reopened and the receipt is inspected.
+		return response{
+			Status: "pending",
+			Reason: fmt.Sprintf("recorded receipt parent is unavailable: %v", err),
+		}, nil
+	}
+	defer opened.close()
+	if err := verifyRootIdentity(opened, input); err != nil {
+		return response{}, err
+	}
+	scratch := scratchName(input.ID)
+	scratchFD, err := unix.Openat(
+		opened.parentFD,
+		scratch,
+		unix.O_RDONLY|unix.O_DIRECTORY|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0,
+	)
+	if errors.Is(err, unix.ENOENT) {
+		return response{Status: "released"}, nil
+	}
+	if err != nil {
+		return response{}, fmt.Errorf("open receipt artifact: %w", err)
+	}
+	defer unix.Close(scratchFD)
+	crossed, err := transactionCrossed(scratchFD, input)
+	if err != nil {
+		return response{}, err
+	}
+	if !crossed {
+		return response{Status: "pending", Reason: "operation has no crossing receipt"}, nil
+	}
+	if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+		return response{}, err
+	}
+	return response{Status: "released"}, nil
+}
+
+func transactionCrossed(scratchFD int, input request) (bool, error) {
+	if input.Target == nil {
+		deleted, err := existsAt(scratchFD, deletedMarker)
+		if err != nil {
+			return false, err
+		}
+		source, err := existsAt(scratchFD, "source")
+		if err != nil {
+			return false, err
+		}
+		return deleted && source, nil
+	}
+	prepared, err := existsAt(scratchFD, preparedMarker)
+	if err != nil {
+		return false, err
+	}
+	target, err := existsAt(scratchFD, "target")
+	if err != nil {
+		return false, err
+	}
+	return prepared && !target, nil
+}
+
+func replaceCurrentWithSource(
+	opened *openedParent,
+	scratchFD int,
+	scratch string,
+	reason string,
+) (response, error) {
+	if err := unix.Renameat(opened.parentFD, opened.base, scratchFD, "current"); err != nil {
+		return response{}, fmt.Errorf("retain older visible destination: %w", err)
+	}
+	if err := linkEntry(scratchFD, "source", opened.parentFD, opened.base); err != nil {
+		_ = unix.Renameat(scratchFD, "current", opened.parentFD, opened.base)
+		return response{}, fmt.Errorf("restore later retained source: %w", err)
+	}
+	if err := unix.Fsync(opened.parentFD); err != nil {
+		return response{}, fmt.Errorf("sync later retained source: %w", err)
+	}
+	if err := cleanupScratch(opened.parentFD, scratchFD, scratch); err != nil {
+		return response{}, err
+	}
+	return response{Status: "changed", Reason: reason}, nil
+}
+
+func classifyWithoutScratch(opened *openedParent, input request) (response, error) {
+	return response{
+		Status: "changed",
+		Reason: "transaction has no operation-owned crossing receipt",
+	}, nil
+}
+
+func requestedTargetIdentity(value *target) (*identity, error) {
+	if value == nil {
+		return nil, nil
+	}
+	return &identity{
+		Kind:   value.Kind,
+		Exec:   value.Kind == "file" && value.Exec,
+		Bytes:  value.Bytes,
+		SHA256: value.SHA256,
+	}, nil
+}
+
+func prepareTarget(scratchFD int, value target) error {
+	if value.Content == nil {
+		return errors.New("apply target content is missing")
+	}
+	content, err := base64.StdEncoding.DecodeString(*value.Content)
+	if err != nil {
+		return err
+	}
+	if value.Kind == "symlink" {
+		if bytes.IndexByte(content, 0) >= 0 {
+			return errors.New("symlink target contains NUL")
+		}
+		if err := unix.Symlinkat(string(content), scratchFD, "target"); err != nil {
+			return fmt.Errorf("prepare target symlink: %w", err)
+		}
+		return unix.Fsync(scratchFD)
+	}
+	mode := uint32(0o644)
+	if value.Exec {
+		mode = 0o755
+	}
+	fd, err := unix.Openat(
+		scratchFD,
+		"target",
+		unix.O_WRONLY|unix.O_CREAT|unix.O_EXCL|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		mode,
+	)
+	if err != nil {
+		return fmt.Errorf("prepare target file: %w", err)
+	}
+	file := os.NewFile(uintptr(fd), "target")
+	if _, err := file.Write(content); err != nil {
+		_ = file.Close()
+		return fmt.Errorf("write target: %w", err)
+	}
+	if err := unix.Fchmod(fd, mode); err != nil {
+		_ = file.Close()
+		return fmt.Errorf("chmod target: %w", err)
+	}
+	if err := unix.Fsync(fd); err != nil {
+		_ = file.Close()
+		return fmt.Errorf("sync target: %w", err)
+	}
+	if err := file.Close(); err != nil {
+		return fmt.Errorf("close target: %w", err)
+	}
+	return unix.Fsync(scratchFD)
+}
+
+func writeMarker(scratchFD int, name string) error {
+	fd, err := unix.Openat(
+		scratchFD,
+		name,
+		unix.O_WRONLY|unix.O_CREAT|unix.O_EXCL|unix.O_NOFOLLOW|unix.O_CLOEXEC,
+		0o600,
+	)
+	if err != nil {
+		return err
+	}
+	if err := unix.Fsync(fd); err != nil {
+		_ = unix.Close(fd)
+		return err
+	}
+	if err := unix.Close(fd); err != nil {
+		return err
+	}
+	return unix.Fsync(scratchFD)
+}
+
+func existsAt(dirFD int, name string) (bool, error) {
+	var stat unix.Stat_t
+	if err := unix.Fstatat(dirFD, name, &stat, unix.AT_SYMLINK_NOFOLLOW); err != nil {
+		if errors.Is(err, unix.ENOENT) {
+			return false, nil
+		}
+		return false, err
+	}
+	return true, nil
+}
+
+func identityAt(dirFD int, name string) (*identity, error) {
+	var stat unix.Stat_t
+	if err := unix.Fstatat(dirFD, name, &stat, unix.AT_SYMLINK_NOFOLLOW); err != nil {
+		if errors.Is(err, unix.ENOENT) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("stat %q: %w", name, err)
+	}
+	switch uint32(stat.Mode) & unix.S_IFMT {
+	case unix.S_IFDIR:
+		return &identity{
+			Kind: "directory",
+			Dev:  strconv.FormatUint(uint64(stat.Dev), 10),
+			Ino:  strconv.FormatUint(uint64(stat.Ino), 10),
+		}, nil
+	case unix.S_IFLNK:
+		content, err := readlinkAt(dirFD, name)
+		if err != nil {
+			return nil, err
+		}
+		sum := sha256.Sum256(content)
+		return &identity{
+			Kind:   "symlink",
+			Bytes:  int64(len(content)),
+			SHA256: hex.EncodeToString(sum[:]),
+			Dev:    strconv.FormatUint(uint64(stat.Dev), 10),
+			Ino:    strconv.FormatUint(uint64(stat.Ino), 10),
+		}, nil
+	case unix.S_IFREG:
+		fd, err := unix.Openat(dirFD, name, unix.O_RDONLY|unix.O_NOFOLLOW|unix.O_CLOEXEC, 0)
+		if err != nil {
+			return nil, fmt.Errorf("open %q for identity: %w", name, err)
+		}
+		file := os.NewFile(uintptr(fd), name)
+		hash := sha256.New()
+		bytesRead, readErr := io.Copy(hash, file)
+		closeErr := file.Close()
+		if readErr != nil {
+			return nil, fmt.Errorf("hash %q: %w", name, readErr)
+		}
+		if closeErr != nil {
+			return nil, fmt.Errorf("close %q: %w", name, closeErr)
+		}
+		return &identity{
+			Kind:   "file",
+			Exec:   uint32(stat.Mode)&0o100 != 0,
+			Bytes:  bytesRead,
+			SHA256: hex.EncodeToString(hash.Sum(nil)),
+			Dev:    strconv.FormatUint(uint64(stat.Dev), 10),
+			Ino:    strconv.FormatUint(uint64(stat.Ino), 10),
+		}, nil
+	default:
+		return nil, fmt.Errorf("%q is not a regular file or symlink", name)
+	}
+}
+
+func entryChangedAt(dirFD int, name string) (int64, error) {
+	var stat unix.Stat_t
+	if err := unix.Fstatat(dirFD, name, &stat, unix.AT_SYMLINK_NOFOLLOW); err != nil {
+		return 0, fmt.Errorf("stat %q change time: %w", name, err)
+	}
+	return statChangedAt(stat), nil
+}
+
+func statChangedAt(stat unix.Stat_t) int64 {
+	mtime := stat.Mtim.Sec*1_000_000_000 + stat.Mtim.Nsec
+	ctime := stat.Ctim.Sec*1_000_000_000 + stat.Ctim.Nsec
+	if ctime > mtime {
+		return ctime
+	}
+	return mtime
+}
+
+func readlinkAt(dirFD int, name string) ([]byte, error) {
+	size := 256
+	for size <= 1024*1024 {
+		buffer := make([]byte, size)
+		count, err := unix.Readlinkat(dirFD, name, buffer)
+		if err != nil {
+			return nil, fmt.Errorf("read symlink %q: %w", name, err)
+		}
+		if count < len(buffer) {
+			return buffer[:count], nil
+		}
+		size *= 2
+	}
+	return nil, errors.New("symlink target exceeds one MiB")
+}
+
+func identitiesEqual(left, right *identity) bool {
+	if left == nil || right == nil {
+		return left == nil && right == nil
+	}
+	return left.Kind == right.Kind &&
+		left.Exec == right.Exec &&
+		left.Bytes == right.Bytes &&
+		left.SHA256 == right.SHA256 &&
+		(left.Dev == "" || right.Dev == "" || left.Dev == right.Dev) &&
+		(left.Ino == "" || right.Ino == "" || left.Ino == right.Ino)
+}
+
+func linkEntry(sourceFD int, source string, destinationFD int, destination string) error {
+	return unix.Linkat(sourceFD, source, destinationFD, destination, 0)
+}
+
+func removeAt(dirFD int, name string, flags int) error {
+	err := unix.Unlinkat(dirFD, name, flags)
+	if errors.Is(err, unix.ENOENT) {
+		return nil
+	}
+	return err
+}
+
+func cleanupScratch(parentFD, scratchFD int, scratch string) error {
+	for _, name := range []string{
+		"source",
+		"target",
+		"current",
+		preparedMarker,
+		deletedMarker,
+	} {
+		if err := removeAt(scratchFD, name, 0); err != nil {
+			return fmt.Errorf("remove retained %s: %w", name, err)
+		}
+	}
+	if err := unix.Fsync(scratchFD); err != nil {
+		return fmt.Errorf("sync emptied scratch: %w", err)
+	}
+	if err := removeAt(parentFD, scratch, unix.AT_REMOVEDIR); err != nil {
+		return fmt.Errorf("remove transaction scratch: %w", err)
+	}
+	if err := unix.Fsync(parentFD); err != nil {
+		return fmt.Errorf("sync scratch removal: %w", err)
+	}
+	return nil
+}
+
+func syncBoth(first, second int) error {
+	if err := unix.Fsync(first); err != nil {
+		return fmt.Errorf("sync destination parent: %w", err)
+	}
+	if err := unix.Fsync(second); err != nil {
+		return fmt.Errorf("sync transaction scratch: %w", err)
+	}
+	return nil
+}
+
+func parseFD(value string) (int, bool) {
+	fd, err := strconv.Atoi(value)
+	return fd, err == nil
+}