GeezerVison

Fixes #726
Refs #887 (the delete-through is fixed; the vendor --check half is not, see Deferred)

Problem

The architecture audit found that symlink and write containment is decided in several places, each with its own rule:

• B08 / Vendored mode still writes and deletes through a symlinked .socket dir: the #664 guard checks .socket/vendor and below only, so rollback in one yarn berry project wipes another project's vendored tarball and ledger #887: the .socket link guard covered only deletes, and it started below .socket. In socket_dir.rs the walk was take_while(*a != stop_dir), and vendor_dir_symlink started at .socket/vendor. If two projects share one .socket through a link, a vendored write or revert in one project writes to, or deletes, the other project's units and state.json, and still exits 0.
• B24 / get writes a patch view's blobs under their claimed hash without checking the content, overwriting already-verified blobs in place #726 (C42): get and agent-mode scan wrote inline blobContent with an in-place tokio::fs::write. The bytes were never hash-checked, and a committed .socket/blobs or .socket/blobs/<hash> symlink sent them outside the project.
• B23: a new-file entry (empty beforeHash) silently overwrote an existing file with different content, even under --strict. CLI_CONTRACT's mismatch policy says it should not.
• B25: the agent-mode guard against writing through links was a denylist of three known stores. A Composer path repository (vendor/<ns>/<name> symlinked to first-party source), a flit --symlink package, or any directory linked out of the package was patched in place.

Change

• One containment helper, socket_patch_core::utils::containment:
  • linked_level / ensure_unlinked lstat every level below a root, the leaf included.
  • try_linked_level is the fallible version. It returns lstat errors other than NotFound instead of treating them as "not a link".
  • is_link is the only lstat link predicate. utils::fs::is_symlink and fs::first_symlink now delegate to it.
  • nearest_socket_dir / socket_project_root.
  • resolves_within checks canonical containment.
• Vendored mode still writes and deletes through a symlinked .socket dir: the #664 guard checks .socket/vendor and below only, so rollback in one yarn berry project wipes another project's vendored tarball and ledger #887. The guard now starts at the project root, so .socket itself is checked:
  • vendor_dir_symlink reports a linked .socket, so every vendored write and revert refuses with vendor_dir_symlink_unsupported.
  • remove_tree_and_prune, remove_file_and_prune and write_json_ledger refuse before they write or delete. write_json_ledger covers the vendored ledger and the pre-v5 hosted redirect ledger.
  • Agent-mode state (manifest.json, blobs/) under a linked .socket keeps working. A shared agent manifest is coherent, and refusing it at lock time would need a maintainer decision.
• get writes a patch view's blobs under their claimed hash without checking the content, overwriting already-verified blobs in place #726 / B24. New function blob_fetcher::store_verified_blob:
  • It refuses a linked level and verifies the git-sha256 against the blob's name before writing anything.
  • It leaves an existing entry untouched if it already verifies.
  • It writes to a stage file and renames it into place.
  • get.rs::write_blob_entry now calls it. The streaming download writer (stream_cache_entry_atomic) applies the same link guard and the same hash rule. These are still two writers: one stages from bytes in memory, the other streams a response body. They share the guard, the hash check and the stage prefix, but each keeps its own stage-and-rename code.
  • The hand-rolled base64 decoder is deleted in favour of the base64 crate. The pinned "Invalid base64 character" message is kept.
• B23. The apply engine treats a new-file collision as a HashMismatch with an empty expected_hash:
  • --strict refuses it.
  • The default policy overwrites it and emits content_mismatch_overwritten.
  • Verbose apply prints expected: (new file) for it.
• B25. shared_store now checks containment, not only the known store markers:
  • Every directory a patch writes into must resolve inside the package directory.
  • A Composer package (identified by <vendor-dir>/composer/installed.json) must resolve inside its vendor dir.
  • Anything else is refused as OutsideInstallTree by apply and by rollback. The rollback refusal has its own remedy ("restore that source from version control") instead of "patch that source directly".
• Recovery stays fail-closed. group_commit::recover uses try_linked_level. A journaled path whose level cannot be probed (EACCES, ENOTDIR) keeps the journal and errors, as the deleted crosses_symlink did.

Duplicates deleted

The "is any level below the root a link" cursor walk had 9 hand-rolled copies before this PR:

• socket_dir::linked_level
• the loop in vendor::path::vendor_dir_symlink
• group_commit::crosses_symlink
• group_commit::is_symlink
• 2 loops in vendor::redownload
• vendor::pypi_hatch's wheel-pin walk
• 2 loops in vendor::reuse
• vendor::bun_binary's workspace-tarball walk

After this PR, 8 of them route through containment::linked_level / try_linked_level. The one left is bun_binary.rs, which belongs to the bun session's files (#1009); see Deferred.

The lstat link predicate had 3 implementations (fs::is_symlink, group_commit::is_symlink, and the inline check in first_symlink) and now has 1, containment::is_link.

Also deleted: socket_dir's private nearest_socket_dir (it now lives only in containment) and the hand-rolled base64 decoder.

Behavior changes

• Linked .socket: a project whose .socket is a symlink can no longer vendor, revert vendored units, or write the vendored ledger or the pre-v5 hosted redirect ledger. It gets vendor_dir_symlink_unsupported or a refusal. Agent mode is unchanged.
• Blob and diff downloads: a linked .socket/blobs or .socket/diffs, or a linked .socket/blobs/<hash> entry, is refused. This affects agent-mode get, apply, repair and rollback. The blob is reported failed, and nothing is written at the link target. A user who pointed .socket/blobs at a shared cache must replace the link with a real directory.
• Inline blobs in get: an inline blob whose bytes do not hash to its name fails the patch with content hash mismatch before anything is written.
• New-file collision: reported as a mismatch overwrite by default, and refused under --strict.
• Out-of-tree packages: agent-mode apply and rollback refuse a Composer path-repo package, a directory linked out of the package, and a package a package manager links into site-packages from its own prefix (Homebrew's Cellar, the Nix store). A file that an older socket-patch patched in place there can no longer be rolled back by socket-patch. The refusal says to restore it from version control.

All of these are documented in the new CLI_CONTRACT section "Links under .socket/ and write containment" and in docs/ecosystems.md.

Testing

All runs were local on macOS (rustc 1.93.1), through the shared heavy-job limiter with CARGO_INCREMENTAL=0 -j4.

• Clippy: cargo clippy --workspace --all-features -- -D warnings -A unused_variables is clean. The -A is needed because python_crawler.rs:2734 has an unused variable that only fires on macOS and already fails on main; CI's Linux clippy does not hit it. --all-targets reports nothing in the lines this PR changed; its remaining errors are in test code and already fail on main.
• Core lib: cargo test -p socket-patch-core --lib: 5586 passed, 1 failed. The failure is utils::digest::tests::production_digests_go_through_the_helpers, a stale PENDING_INLINE_DIGESTS list on this branch's base that Fix main CI red on stale digest pending-list entries #1016 has since fixed on main. It is unrelated to this PR.
• CLI: cargo test -p socket-patch-cli --no-fail-fast, every target including --lib: 199 of 202 targets pass, and the --lib target passes 865/865. After the tests/get/ fixture fix, --test get passes 81/81 and --test in_process_get_corrupt_manifest passes. The other two failures are not caused by this PR:
  • e2e_vendor_cargo_build::cargo_vendored_manifest_patch_builds_on_old_toolchains cannot run here: the x86_64 rustup 1.41 toolchain gives "Bad CPU type in executable" on this arm64 machine without Rosetta.
  • mode_migration_npm::berry_vendored_then_hosted_takeover_leaves_pure_hosted fails the same way at this branch's merge-base (db83f01) with none of this PR's changes. I checked that in a separate worktree.
• Regression tests (failing first):
  • containment::*, including try_linked_level_propagates_unprobeable_levels
  • group_commit::recovery_fails_closed_when_a_level_cannot_be_probed
  • blob_fetcher::download_refuses_a_linked_blobs_dir_or_entry: the download path, with a linked .socket/blobs and a dangling .socket/blobs/<hash>
  • socket_dir::a_linked_socket_dir_is_never_written_or_deleted_through (Vendored mode still writes and deletes through a symlinked .socket dir: the #664 guard checks .socket/vendor and below only, so rollback in one yarn berry project wipes another project's vendored tarball and ledger #887)
  • vendor_dir_symlink_finds_the_outermost_linked_level
  • write_blob_entry_verifies_content_against_its_hash and write_blob_entry_refuses_a_linked_blob_or_blobs_dir (get writes a patch view's blobs under their claimed hash without checking the content, overwriting already-verified blobs in place #726)
  • write_all_patch_blobs_unwinds_its_own_blobs_on_a_later_failure and write_all_patch_blobs_unwind_spares_preexisting_blobs, which now use real hashes so the unwind is actually exercised
  • test_apply_package_patch_new_file_collision_refused_under_strict (B23)
  • expected_hash_label_names_a_new_file_collision
  • composer_path_repository_is_outside_the_install_tree, which also checks the rollback remedy text, and written_dir_linked_out_of_the_package_is_refused (B25)
• Fixtures: every CLI fixture that named an inline blob with a fake hash (1111…, 0000…) now uses the real git-sha256. This covers the top-level in_process_* and covgap files, tests/get/, and in_process_get_corrupt_manifest. I checked the Linux-only docker_e2e_* and e2e_* mock servers by reading them: they already compute git_sha256 of their content.
• Left to CI: the Linux, Windows and Docker suites. On Windows, junction handling depends on FileType::is_symlink, which the old guards also relied on.

Deferred

• Vendored mode still writes and deletes through a symlinked .socket dir: the #664 guard checks .socket/vendor and below only, so rollback in one yarn berry project wipes another project's vendored tarball and ledger #887, vendor --check: it still exits 0 (discovered: 0) when the shared ledger is gone but the lock is still wired to a missing artifact. Vendored mode still writes and deletes through a symlinked .socket dir: the #664 guard checks .socket/vendor and below only, so rollback in one yarn berry project wipes another project's vendored tarball and ledger #887 stays open for that half.
• A linked .socket itself: it still redirects agent-mode blob and manifest writes, because the cache guard's root is .socket. Refusing it for every command at lock time, as audit B08 recommended, would break a shared agent manifest. That needs a maintainer decision; I did not make it. CLI_CONTRACT states the gap.
• Two blob writers: store_verified_blob and stream_cache_entry_atomic still each have their own stage-and-rename code. Merging them into one commit helper is possible but was left out of this PR.
• vendor::bun_binary's workspace-tarball walk: the last hand-rolled link walk. It is in the bun session's files (Fix open bun issues (#992, #861, #784, #764, #735, #635, #599, #578, #497, #443, #371) #1009), so I did not edit it there. It can call containment::try_linked_level once Fix open bun issues (#992, #861, #784, #764, #735, #635, #599, #578, #497, #443, #371) #1009 lands.
• B23, second half: a pre-image store. Rolling back an added file still deletes it, and the content it replaced is not kept. This needs a manifest field (roadmap item 17, C24/Decide: make --download-mode file the default and retire the diff download path #792).
• With Bun's globalStore (Bun ≥ 1.3.14), agent mode patches and rolls back every other project sharing the store, and vex attests unpatched transitive copies as not_affected #635 (Bun globalStore): the bun session has claimed it.
• Composer crawler: resolve_install_path still checks containment lexically. The write guard covers it at apply time.

🤖 Generated with Claude Code

Generated by Claude Code