# 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.
