docs(uv): fix stale uv.hub references and clean up extension docstrings/comments

[xangcastle]

Docstrings and documentation were still mentioning the pre-rename uv.hub API in its docstring example and prose, and the inline comments were a mix of redundant narration, dead code, and one note that directly contradicted the deliberate non-validation of hub uniqueness. Replace every stale uv.hub reference with uv.declare_hub, drop the low-value comments.

---

Changes are visible to end-users: yes/no

• Searched for relevant documentation and updated as needed: yes/no
• Breaking change (forces users to change their own code or config): yes/no
• Suggested release notes appear below: yes/no

Test plan

• Covered by existing test cases
• New test cases added
• Manual testing; please provide instructions so we can reproduce:

[aspect-workflows]

✨ Aspect Workflows Tasks

📅 Fri Jul 10 19:54:58 UTC 2026

✅ 36 successful tasks

• ✅ buildifier · ⏱ 18.3s · 🐙 GitHub Actions · ☑️ Check
  💬 Format complete (clean)
• ✅ gazelle · ⏱ 19.3s · 🐙 GitHub Actions · ☑️ Check
  💬 Gazelle complete (clean)
• ✅ test-e2e-bazel-8 [test] · ⏱ 3m 54s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (195/195 passed)
• ✅ test-e2e-bazel-9 [test] · ⏱ 3m 43s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (189/189 passed)
• ✅ test-e2e-interpreter-input-validation-bazel-8 [test] · ⏱ 26.8s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-e2e-interpreter-input-validation-bazel-9 [test] · ⏱ 34.5s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-e2e-interpreter-runtime-metadata-bazel-8 [test] · ⏱ 26.4s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (2/2 passed)
• ✅ test-e2e-interpreter-runtime-metadata-bazel-9 [test] · ⏱ 1m 3s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (2/2 passed)
• ✅ test-e2e-interpreter-toolchain-settings-bazel-8 [test] · ⏱ 19.2s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-e2e-interpreter-toolchain-settings-bazel-9 [test] · ⏱ 1m 23s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-e2e-rules-proto-grpc-python-bazel-8 [test] · ⏱ 1m 51s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-e2e-rules-proto-grpc-python-bazel-9 [test] · ⏱ 2m 31s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-debugger-bazel-8 [test] · ⏱ 28s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-debugger-bazel-9 [test] · ⏱ 1m 4s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-dev_deps-bazel-8 [test] · ⏱ 26.4s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-dev_deps-bazel-9 [test] · ⏱ 50.3s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-django-bazel-8 [test] · ⏱ 24s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-django-bazel-9 [test] · ⏱ 1m · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-multi_version-bazel-8 [test] · ⏱ 28.7s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (2/2 passed)
• ✅ test-examples-multi_version-bazel-9 [test] · ⏱ 47.9s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (2/2 passed)
• ✅ test-examples-protobuf-bazel-8 [test] · ⏱ 1m 38s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-protobuf-bazel-9 [test] · ⏱ 2m 1s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-py_binary-bazel-8 [test] · ⏱ 20.4s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-py_binary-bazel-9 [test] · ⏱ 1m 16s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-py_pex_binary-bazel-8 [test] · ⏱ 21.4s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-py_pex_binary-bazel-9 [test] · ⏱ 1m 40s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-py_venv-bazel-8 [test] · ⏱ 20.8s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (3/3 passed)
• ✅ test-examples-py_venv-bazel-9 [test] · ⏱ 27.5s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (3/3 passed)
• ✅ test-examples-pytest-bazel-8 [test] · ⏱ 50s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (9/9 passed)
• ✅ test-examples-pytest-bazel-9 [test] · ⏱ 1m 9s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (9/9 passed)
• ✅ test-examples-uv_pip_compile-bazel-8 [test] · ⏱ 22.9s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-uv_pip_compile-bazel-9 [test] · ⏱ 55.7s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-virtual_deps-bazel-8 [test] · ⏱ 20.7s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-examples-virtual_deps-bazel-9 [test] · ⏱ 42.2s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (1/1 passed)
• ✅ test-root-bazel-8 [test] · ⏱ 3m 3s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (235/235 passed)
• ✅ test-root-bazel-9 [test] · ⏱ 3m 48s · 🐙 GitHub Actions · ☑️ Check
  💬 Bazel test complete (234/234 passed)

---

_{⏱ Last updated Fri Jul 10 20:00:19 UTC 2026 · 📊 GitHub API quota 1,253/15,000 (8% used, resets in 10m)
🚀 Powered by Aspect CLI (v2026.28.2)  |  Aspect Build · X · LinkedIn · YouTube}

[github-actions]

py_binary startup benchmark

Version	Mean (ms)	Median (ms)	± stddev	vs BCR	vs main	Build (s)
BCR 1.11.7 (baseline)	188.768	188.085	±4.228	—	—	43.62
HEAD main	60.229	59.762	±2.248	-68.1%	—	9.58
This PR	60.716	60.413	±2.259	-67.8%	+0.8%	7.03

Measured with hyperfine --warmup 5 --runs 50 on Linux
Gate: PR vs HEAD main (threshold: 10%). BCR is shown only as a historical baseline.
Build time: cold bazel build //:bench with isolated output base, no disk cache.

sys.path quality

Version	sys.path entries	distinct site-packages roots	duplicate realpaths
BCR 1.11.7 (baseline)	6	1	0
HEAD main	7	2	0
This PR	7	2	0

sys.path quality measured by bench_syspath inside the assembled venv. Duplicate realpaths indicate symlink redundancy; many distinct site-packages roots suggest an inefficient venv layout.

Bazel analysis benchmark

Version	Mean (ms)	Median (ms)	± stddev	vs BCR	vs main	Packages	Targets
BCR 2.0.0-alpha.4 (baseline)	11280.882	11258.400	±148.570	—	—	101	301
HEAD main	10147.749	10168.737	±170.121	-10.0%	—	101	301
This PR	10288.457	10319.462	±177.859	-8.8%	+1.4%	101	301

Measured with hyperfine --warmup 1 --runs 10 on Linux
Gate: PR vs HEAD main (threshold: 10%). BCR is shown only as a historical baseline.
Command: cold bazel build --nobuild //workspace/... with isolated output base, no disk cache.

Auxiliary metrics

Version	Loaded packages	Configured targets
BCR 2.0.0-alpha.4 (baseline)	101	301
HEAD main	101	301
This PR	101	301