[dennis-upbound]

Description of your changes

Fixes #530.

A ModelCache downloads every file in a HuggingFace repository. Many repositories publish the same weights more than once, as a consolidated checkpoint beside the sharded safetensors or one copy per format. mistralai/Mistral-Small-3.2-24B-Instruct-2506 holds about 90 GiB, and vLLM can serve it from the 45 GiB in Mistral's format, which leaves the cache with twice the storage and download time it needs (#457). The docs also don't say how to start a cached model's engine when HuggingFace isn't reachable (#530).

This builds on #574 and should merge after it. It's based on main, so GitHub shows #574's commits here too until #574 merges.

spec.huggingFace gets optional include and exclude lists of glob patterns. The hydration Job passes each to hf download as --include or --exclude, quoted for the shell. The Job now quotes repo and revision too. A repo ID or revision made of letters, digits, dots, dashes and slashes comes out unchanged, so an existing cache's Job doesn't change.

spec:
  source: HuggingFace
  huggingFace:
    repo: mistralai/Mistral-Small-3.2-24B-Instruct-2506
    include: ["consolidated.safetensors", "params.json", "tekken.json"]
    sizeGiB: 50

Deleting a cache before its download finished left the hydration Job on the cluster, because the Job is composed without the Delete management policy so that its own TTL can clean up its completed pod. A cache created again under the same name gets a claim of the same name, and the old Job downloaded into it. In a live run, a cache whose filters left out the weights went Ready with every weight file of the repository staged. This happens on main too, without filters: a cache recreated with another revision gets the old revision. A hydrating Job now has every management policy, so deleting the cache deletes it. Once the cluster is Ready the Job is composed without Delete until its Object reflects that, then dropped. The TTL cleanup works as before.

This is a breaking change: repo, revision, include and exclude can't change once the cache exists. The cache downloads once. An edit afterwards did nothing, and an edit during the download failed on the Job's immutable template. CEL transition rules on spec.huggingFace now reject the edit with "Create a new ModelCache to change spec.huggingFace.." I checked the rules with kubectl replace --dry-run=server against a 1.34 kube-apiserver. Changing, adding or removing any of the four is rejected. The same spec, a sizeGiB or authSecret change, a metadata update and a status update are accepted.

The docs show the filters and say to size the cache to the files it downloads. To start an engine without contacting HuggingFace, they say to set HF_HUB_OFFLINE=1 in the engine's env and to make sure the cache contains every file the engine reads. Modelplane still doesn't set the variable itself, because it breaks engines that fetch a second repository. I checked the documented setup with the hydration Job's exact command. With no network, a staged model loads by repo ID with HF_HUB_OFFLINE=1. Without it, the load retries huggingface.co for 93 seconds first.

Decisions. The source is immutable because it can't change in place without downloading again and restarting every engine that reads the cache. Creating a new cache under a new name is explicit, and makes the swap a deliberate rollout. The engines keep the old cache until the new one is ready, then restart onto it once. The docs say not to recreate a cache under its old name while engines mount it, because the new cache gets the old claim's name and can't stage until those engines stop. sizeGiB stays required, so this is towards #457, not a fix.

Towards #457.

compose-model-cache has new unit tests for the filters, the quoting, and the two steps that drop a finished Job. The end-to-end test from #574 now filters its repository and checks that the cache staged none of the weights the filters leave out. It passed on kind, and so did a manual check that the API server rejects an edit to the source. The Job deletion change has unit tests but hasn't run live yet.

An include that matches no file still marks the cache Ready with an empty snapshot. That's a follow-up.

I have:

• Read and followed Modelplane's contribution process.
• Run nix flake check (or ./nix.sh flake check) and made sure it passes.
• Added or updated tests covering any composition function changes.
• Signed off every commit with git commit -s.

🤖 Generated with Claude Code

[github-actions]

Docs preview: https://modelplane-docs-pr-578.vercel.app (ready once the site's Content workflow finishes)