Loki/docs/superpowers/specs/2026-10-15-rust-migration-lot8-modeles-design.md

# Lot 8 — routes des modèles tenues par la façade

## Contexte

Les modèles `.gguf` vivaient dans le Go :

- la liste du sélecteur (`handleModels`, `backend_models_refs.go`) ;
- les dossiers de modèles (`backend_model_dirs.go`) ;
- la suppression (`deleteModelFile`) ;
- les téléchargements (`backend_models.go`, `backend_models_shards.go`) ;
- le catalogue Hugging Face (`backend_hf.go`, `web_hf.go`, `backend_catalog.go`).

Lot 8 : la façade tient tout cela quand `LOKI_MODELS=rust` (expérimental ;
sans la variable rien ne change, tout part au Go).

## Ce que sert la façade

| Route | Module | Rôle |
|---|---|---|
| `GET /api/models` | `models.rs` | `.gguf` des dossiers déclarés (tranches 2..N exclues), taille de la famille, tranches manquantes, qui les référence (presets, configuration en service) |
| `POST /api/models/delete` | `models.rs` | refus si en service ; 409 avec la liste des presets sans `force` ; le modèle part avec toutes ses tranches, octets libérés rendus |
| `GET\|POST /api/models/dirs` | `models.rs` | dossiers de modèles, nombre de modèles, espace libre ; ajout (dossier existant) et retrait |
| `POST /api/models/download/probe` | `downloads.rs` | taille du modèle (toutes ses tranches), espace libre, « ça tient ? », ou « déjà là » avec la valeur de `MODEL=` |
| `POST /api/models/download` | `downloads.rs` | lance en arrière-plan ; 409 si déjà en cours ; « déjà là » si toutes les tranches sont présentes |
| `GET /api/models/download/status` | `downloads.rs` | état de chaque téléchargement de ce lancement |
| `POST /api/models/download/cancel` | `downloads.rs` | annule ; ce que le téléchargement a écrit est effacé |
| `GET /api/hf/search` | `hf.rs` | dépôts GGUF, matériel local joint |
| `GET /api/hf/files` | `hf.rs` | modèles, projecteurs et poids MTP d'un dépôt, verdict mémoire de chaque modèle (contexte du preset actif, projecteur du dépôt) |
| `GET\|POST /api/hf/token` | `hf.rs` | jeton vérifié auprès de Hugging Face avant d'être enregistré, jamais rendu en clair |

Mêmes contrats (corps, codes, messages) et même mécanique que le Go, entre
autres :

- téléchargement :
  - lien de page Hugging Face (`/blob/`) converti en lien direct ;
  - modèle en tranches rapatrié en entier ;
  - place disque vérifiée sur le total, avec 256 Mio de marge ; jamais de
    refus sur FUSE, overlayfs, NFS, SMB, Ceph ou GlusterFS ;
  - plages d'octets en parallèle (`LOKI_DL_CONNS`) et reprise d'une
    connexion coupée ;
  - jeton envoyé aux seuls hôtes Hugging Face ;
- catalogue : réponses mises en cache (60 s pour une recherche, 10 min pour un
  dépôt), cache vidé à l'enregistrement d'un jeton ;
- `.part` orphelins vidés au démarrage — par la façade : le Go ne le fait
  plus, il effacerait un téléchargement qu'elle mène.

## Côté Go (`facade_models.go`)

Le tunnel du relais et la redistribution E2E arrivent au Go sans passer par
la façade : `withFacadeChat` lui remet ces routes, authentifiées par le
jeton interne, comme celles du chat. Façade injoignable : 502 « modèles
indisponibles : … ».

La façade transmet `LOKI_MODELS=rust` et son adresse au Go qu'elle lance.

## Écarts assumés

- Une source qui ignore les plages n'est plus lue en entier pendant la sonde.
- Erreurs de transport (réseau, TLS) au format de reqwest.
- Message d'un corps JSON illisible : celui de serde (l'interface n'en envoie
  jamais).
- Hôte d'un lien collé en majuscules converti comme les autres.
- Espace libre et mémoire vive inconnus hors Unix/Linux (la façade n'est
  livrée que pour Linux).
- `/api/models/download/status` trié par date de début.
- Nombres flottants du matériel écrits `24.0` (le Go écrit `24`) : même
  valeur JSON.

## Parité

Journaux tirés du Go et rejoués en Rust (`LOKI_PARITY_UPDATE=1` pour
régénérer) :

- `internal/loki/parity_dl_test.go` → `tests/parity_models/download.json` →
  `tests/downloads.rs` : lien normalisé, famille de tranches,
  `Content-Range`, messages de refus, hôtes et dépôts Hugging Face, dossier
  de destination ;
- `internal/loki/parity_models_test.go` → `tests/parity_models/models.json` →
  `tests/models.rs` : quantification déduite du nom, découpage
  d'`EXTRA_ARGS`, jeton masqué, `gated`, classement d'un dépôt, choix du
  projecteur, verdicts mémoire, puis un scénario sur disque de 20 appels
  (liste, dossiers, suppressions avec et sans `force`, modèle en service,
  tranches, chemins refusés) rejoué à l'identique, fichiers restants et
  dossiers enregistrés compris.

Deux mutations (`replacen` → `replace` sur `/blob/`, `--mmproj` ignoré)
font échouer les rejeux.

De bout en bout :

- téléchargements contre un faux Hugging Face : trois connexions sur des
  plages disjointes, source sans plages, tranches dont une présente, dépôt
  verrouillé, panne pendant la deuxième tranche, annulation et 409 ;
- catalogue contre un faux Hugging Face : recherche, cache, taille LFS,
  dépôt verrouillé ou absent, jeton refusé ou accepté ;
- toutes les routes par la façade (clé de pilotage, remise du Go, base du Go
  écrite), et laissées au Go sans la variable.

## Reste

- Essai réel sur une installation avant d'en faire le défaut.