# model-artifact
Model artifact resolution over a pluggable repository interface.
`model-artifact` turns a parsed model coordinate into a concrete primary model
file, artifact file set, and provenance record. It also owns GGUF artifact
metadata scanning used for context planning and MoE/stage packaging. It knows
artifact-selection policy and file metadata formats, but it does not know how
any particular registry downloads files.
## Architecture Role
Repository adapters implement `ModelRepository`. This crate asks the adapter for
the resolved revision and file listing, then applies shared selection rules for
GGUF and safetensors artifacts.
```mermaid
flowchart LR
R["ModelRef<br/>repo, revision, selector"] --> A["model-artifact"]
Repo["ModelRepository<br/>resolve revision<br/>list files"] --> A
A --> P["primary_file"]
A --> F["artifact file set<br/>single file or split shards"]
A --> I["ModelIdentity<br/>canonical_ref<br/>distribution_id"]
P --> S["skippy-model-package<br/>write-package"]
F --> S
I --> T["mesh status<br/>runtime + OpenAI metadata"]
```
## Selection Rules
- With a selector, prefer exact file and basename matches before quant-like GGUF
matches.
- Without a selector, prefer `model.safetensors`, then split safetensors, then
GGUF first shards, then single GGUF files.
- Split GGUF shards are grouped by matching shard prefix and total count.
- Known GGUF sidecars are ignored during default selection.
## Main Types
- `ModelRepository` abstracts revision resolution and file listing.
- `ResolvedModelArtifact` records source repo, source revision, selected files,
primary file, canonical ref, format, and distribution id.
- `ModelIdentity` is the portable identity shape used by higher-level crates.
- `ModelArtifactFile` carries path plus optional size and checksum metadata.
- `gguf::GgufCompactMeta`, `gguf::GgufKvCacheQuant`, and
`gguf::scan_gguf_compact_meta()` expose GGUF header metadata without making
host or client crates own a GGUF parser.
Concrete Hugging Face behavior lives in `model-hf`; tests and other callers can
provide small in-memory repository implementations.
Callers should carry `ModelIdentity` forward instead of falling back to local
filenames. For direct local GGUF serving, mesh synthesizes a package identity
around the file while keeping the artifact path separate from the public model
ref.