Pin SAM3DBody and MHR assets

[EHxuban11]

• Pin SAM 3D Body mirror snapshots and the MHR v1.0.1 asset to reviewed revisions, sizes, and SHA-256 identities.
• Add exact online/offline acquisition, legacy-cache migration, link rejection, and create-only publication checks.
• Download online snapshots into private revision staging and bound cleanup/recovery so multi-gigabyte copies cannot silently accumulate.
• Add the supported libreyolo[hf] install guidance for automatic acquisition.
• Verified: 204 relevant tests passed, 5 platform/data skips, 9 deselected; cached MHR CPU contract and D3 offline migration passed; Ruff, format, diff-check, and Greptile 5/5 passed.
• Not verified locally: the full xdist unit matrix, live upstream SAM inference, H checkpoint load, GPU inference, or live Linux/macOS publication. CI is authoritative for the full matrix.

Code provenance

• New implementation, tests, and documentation are original LibreYOLO code.
• MHR asset metadata and its parameter contract reference facebookresearch/MHR commit 4998cec385b1aaa07abdefba71bfba2f83c7db32 (Apache-2.0); no upstream code is copied.
• SAM 3D Body repository metadata and byte-identical weights reference facebookresearch/sam-3d-body commit b5c765a0d89d789985e186d396315e7590887b94 under the custom SAM License. No SAM 3D Body implementation code is copied, adapted, or ported.

Greptile Summary

The PR pins the SAM 3D Body and MHR assets to reviewed revisions and byte identities, then adds strict acquisition, migration, staging, publication, and loading checks.

• Adds shared filesystem and byte-integrity helpers for model assets.
• Introduces revision-keyed SAM snapshot acquisition with online, offline, and legacy-cache paths.
• Pins and validates the MHR release archive, extracted model, and license.
• Updates dependency metadata, tests, licensing notices, and the mesh-task contract.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
libreyolo/models/sam3dbody/_assets.py	Adds descriptor-based hashing, link rejection, private staging, guarded cleanup, and create-only atomic publication primitives.
libreyolo/models/sam3dbody/snapshot.py	Implements pinned SAM snapshot acquisition, offline loading, legacy migration, exact inventory validation, and recovery handling.
libreyolo/models/sam3dbody/mhr_body.py	Pins the MHR release and validates the archive, model member, cache publication, and TorchScript loading boundary.
libreyolo/models/sam3dbody/model.py	Integrates verified snapshot and MHR identities around the upstream path-only constructor and adds actionable optional-dependency guidance.
pyproject.toml	Raises the Hugging Face optional dependency floor to the version required for dry-run byte metadata.
tests/unit/test_sam3dbody_assets.py	Adds focused coverage for integrity checks, acquisition modes, migration, link rejection, recovery, and dependency errors.
docs/adr/0013-mesh-task-contract.md	Documents the pinned transport, cache lifecycle, gate behavior, and trusted-filesystem boundary.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Start[Initialize SAM 3D Body] --> Cache{Pinned private snapshot exists?}
  Cache -->|Yes| Verify[Verify inventory, sizes, and SHA-256]
  Cache -->|No| Legacy{Verified legacy cache available?}
  Legacy -->|Yes| Stage[Copy into private revision-keyed stage]
  Legacy -->|No| Mode{Offline mode?}
  Mode -->|Yes| HubCache[Read reviewed runtime objects from Hub cache]
  Mode -->|No| Preflight[Verify gate, revision, tree, and declared sizes]
  Preflight --> Download[Download reviewed files]
  HubCache --> Stage
  Download --> Stage
  Stage --> Publish[Create-only atomic publication]
  Publish --> Verify
  Verify --> Load[Pass verified paths to upstream loader]
  Load --> Recheck[Rehash checkpoint, config, license, and MHR]

Loading

_{Reviews (2): Last reviewed commit: "Bound SAM3DBody asset staging" | Re-trigger Greptile}

Context used:

• Knowledge Base — Model zoo, architectures, and inference backends
• Knowledge Base — Specialist inference tasks: embeddings and body meshes