From b2ce0f8bf6303250402f4dc707c33cec42044afd Mon Sep 17 00:00:00 2001
From: Ed Morley <501702+edmorley@users.noreply.github.com>
Date: Tue, 16 Jun 2026 14:17:48 +0100
Subject: [PATCH] Clarify the uv layer's use of arch in comments

The uv download URL uses the buildpack's compile-time arch (Rust's
`std::env::consts::ARCH`, e.g. `x86_64`) since that's how Astral names their
archives, whereas the cache metadata uses the CNB target arch (e.g. `amd64`).
Add comments explaining this, and also why the layer isn't invalidated on
distro or Python version changes.

Making this change to reduce both human and LLM confusion when
reviewing the codebase.

GUS-W-23022354.
---
 src/layers/uv.rs | 5 +++++
 tests/mod.rs     | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/layers/uv.rs b/src/layers/uv.rs
index 00789ae..eb9c09a 100644
--- a/src/layers/uv.rs
+++ b/src/layers/uv.rs
@@ -86,6 +86,9 @@ pub(crate) fn install_uv(
             // There's also a statically compiled musl uv binary archive, but:
             // 1. It's currently slower than the glibc variant: https://github.com/astral-sh/uv/issues/10610
             // 2. At the moment this buildpack only supports Ubuntu anyway (we only compile Python runtimes for Ubuntu).
+            //
+            // Note: We use `ARCH` instead of `context.target.arch` since we need the uname-style arch (e.g. `x86_64`)
+            // rather than the Go-style arch (e.g. `amd64`) used by the OCI/CNB specification and APIs.
             let archive_url = format!(
                 "https://releases.astral.sh/github/uv/releases/download/{UV_VERSION}/uv-{ARCH}-unknown-linux-gnu.tar.gz"
             );
@@ -105,6 +108,8 @@ pub(crate) fn install_uv(
     Ok(())
 }
 
+// uv is a standalone prebuilt binary (rather than a Python package like pip or Poetry), so unlike the
+// other tool layers the uv layer doesn't need invalidating on distro or Python version changes.
 #[derive(Deserialize, PartialEq, Serialize)]
 #[serde(deny_unknown_fields)]
 struct UvLayerMetadata {
diff --git a/tests/mod.rs b/tests/mod.rs
index 7103068..9b02830 100644
--- a/tests/mod.rs
+++ b/tests/mod.rs
@@ -23,7 +23,7 @@ fn default_build_config(fixture_path: impl AsRef<Path>) -> BuildConfig {
     let mut config = BuildConfig::new(&builder, fixture_path);
 
     // TODO: Once Pack build supports `--platform` and libcnb-test is adjusted accordingly, change
-    // this to allow configuring the target arch independently of the builder name (eg via env var).
+    // this to allow configuring the target arch independently of the builder name (e.g. via env var).
     let target_triple = match builder.as_str() {
         // Compile the buildpack for ARM64 iff the builder supports multi-arch and the host is ARM64.
         "heroku/builder:24" | "heroku/builder:26" if cfg!(target_arch = "aarch64") => {