Files
obikmer/prompts/merge_mmap_refactor.md
T

150 lines
15 KiB
Markdown
Raw Normal View History

# Prompt — refonte mmap de `obikmerge` (plans A puis C)
> À coller tel quel au début d'une nouvelle session Claude Code ouverte à la racine du dépôt obikmer.
> Conçu pour être suivi par **Sonnet** : toutes les décisions d'architecture sont fixées ci-dessous. Le plan B de l'audit (ouverture « slots only » dans `obikindex`) est **hors périmètre** de cette session (voir étape 5).
---
## Contexte
Lis d'abord `DevDocMD/implementation/merge_mmap_audit.md`. C'est le diagnostic complet, et ce prompt en implémente le plan.
En résumé : `obikmerge::partition_merge::merge_partition` ouvre, pour **chaque** partition, **toutes** les couches de **toutes** les sources (4 mmaps chacune). Elle crée aussi **toutes** les colonnes destination d'avance, en fichiers creux mappés en écriture (`set_len` + `MmapMut`). Avec 186 sources, ça fait environ 1 100 mappings par partition, ce qui épuise `vm.max_map_count` en production (pas d'accès root pour le relever). L'écriture via `MmapMut` dans des fichiers creux transforme aussi tout refus d'allocation disque en SIGBUS.
Objectif : le nombre de mappings vivants par partition ne doit plus dépendre du nombre de sources, et l'écriture des colonnes du merge ne doit plus passer par `MmapMut`. **Le résultat sur disque doit rester strictement identique.**
## Règles (non négociables)
- Appelle `mcp__serena__initial_instructions` avant tout travail de code. Utilise Serena (`find_symbol`, `get_symbols_overview`, `find_referencing_symbols`, `replace_symbol_body`, `replace_content`) pour naviguer et éditer le Rust.
- **Aucune commande VCS mutante** (git/jj : commit, add, mv, rm, describe, push…). Lecture seule autorisée.
- **Aucune nouvelle dépendance**, ni changement de version.
- `obikindex` fait autorité : cette session n'y modifie et n'y ajoute rien.
- Pas de fonctions libres ad hoc dans `obikmerge` pour combler un manque d'API. Si une opération générique manque sur un type de `obicompactvec`, ajoute-la comme méthode sur ce type.
- Fichiers source sous ~500 lignes. `partition_merge.rs` en fait déjà 605 : il **doit** être découpé (étape 6).
- **Ne jamais `.collect()` un flux de k-mers ou de unitigs** pour satisfaire une contrainte de trait.
- Échanges en **français**, documentation en **anglais**.
- **Point d'arrêt obligatoire** à la fin de chaque étape. Résume ce qui a été fait et les résultats de tests (sortie réelle), puis **attends mon feu vert** avant l'étape suivante.
- Si un test ou l'oracle échoue et que tu ne trouves pas la cause en une tentative, **arrête-toi et expose le problème**, sans contournement.
## Étape 1 — Oracle de non-régression (avant toute modification de code)
### 1a. Oracle synthétique (rapide, couvre comptage et merge en deux temps)
1. Lis `scripts/smoke_test_index.sh` (modèle de style, options de `obikmer index`) et les `--help` de `obikmer index`, `merge` et `dump`.
2. Écris `scripts/smoke_test_merge.sh`, sur le même modèle :
- génère 4 FASTA aléatoires déterministes A, B, C, D, petits, avec **des fragments partagés** entre eux. Le merge doit à la fois retrouver des k-mers déjà présents dans la destination (chemin « couche existante ») et en créer de nouveaux (chemin « nouvelle couche ») ;
- indexe chacun deux fois : présence (défaut) et comptage (`--with-counts`). Plusieurs partitions (`-p 4`) ;
- scénario 1 : `merge A B C D` (présence), puis la même chose en comptage ;
- scénario 2 : `merge A B` → AB, puis `merge AB C D`. Ce scénario couvre une source multi-génome et une destination à plusieurs couches ;
- scénario 3 : comme le scénario 1, avec `--dense` ;
- pour chaque sortie : `obikmer dump` → `sort` → un fichier texte ;
- deux modes : `--record DIR` écrit les sorties triées dans `DIR`, `--check DIR` les régénère et fait un `diff` avec `DIR`. Affiche PASS/FAIL clairement, avec un code de sortie cohérent.
3. Lance `--record benchmark/run/merge_oracle/synthetic` **avec le code actuel, non modifié**. Vérifie que les fichiers ne sont pas vides et que les colonnes de génomes ont du sens.
4. Lance aussitôt `--check` sur le même code pour vérifier que le script est déterministe.
### 1b. Oracle sur données réelles : `benchmark/`
`benchmark/run/specimen_index_presence/` contient 20 index présence construits à partir de vrais génomes (bactéries + une levure, lectures simulées). Lis `benchmark/README.md` et `benchmark/merge_presence.sh` (le merge de référence y utilise `--force --force-presence`).
État constaté au 2026-11-17, à revérifier :
- `specimen_index_count/` est **vide** : pas de piste comptage sans relancer `gmake index_count` (GNU make ≥ 4.3 : `gmake` sur macOS). **Demande-moi** avant de le lancer, car ça prend du temps ;
- `reference_index/` (`.npz`) est **absent** : `verify_merge_*.py` est inutilisable, ne t'appuie pas dessus ;
- `global_index_presence/` a été produit par un binaire antérieur au code actuel (release du 2026-10-22) : **ce n'est pas la référence**.
Procédure :
1. Recompile le binaire release à partir du **code actuel non modifié** (`cargo build --release` dans `src/`). Ne touche pas aux artefacts existants de `benchmark/run/`.
2. Lance le merge des 20 index avec les mêmes options que `merge_presence.sh`, mais vers un répertoire **dédié**, par exemple `benchmark/run/merge_oracle/bench/merged`, jamais `benchmark/run/global_index_presence`. Garde le log stderr : le rapport de stages (wall et RSS de `merge_partitions`) sert de référence de performance.
3. `obikmer dump` du résultat → `sort` → compresse (`zstd`) + `sha256sum`, dans `benchmark/run/merge_oracle/bench/`. La sortie peut être volumineuse : compare d'abord les hash, et ne fais un `diff` que s'ils diffèrent.
4. Contrôle croisé informatif : fais la même chose (dump trié + hash) sur `benchmark/run/global_index_presence`. Si les hash diffèrent, **signale-le sans conclure** : l'écart peut venir d'évolutions légitimes du code depuis octobre.
5. Écris ces étapes dans un script `scripts/bench_merge_oracle.sh` avec deux modes : `--record DIR` et `--check DIR`. En mode `--check`, il affiche aussi le temps de `merge_partitions` avant/après.
Après chaque étape de code (3, 4, 6), les **deux** oracles doivent passer : `smoke_test_merge.sh --check` et `bench_merge_oracle.sh --check`. Si `merge_partitions` est plus de 20 % plus lent qu'avant sur le benchmark, signale-le au point d'arrêt.
**Point d'arrêt.**
## Étape 2 — `MatrixBuilder::n_cols` (petit prérequis, `obicompactvec`)
Ajoute `pub fn n_cols(&self) -> usize` à `obicompactvec::MatrixBuilder` (`src/obicompactvec/src/matrix_builder.rs`), en déléguant au builder Bit ou Int. Si `PersistentCompactIntMatrixBuilder` n'expose pas `n_cols()`, ajoute-le sur ce type. Ajoute un test unitaire. `cargo test -p obicompactvec`.
Pas de point d'arrêt séparé : enchaîne sur l'étape 3.
## Étape 3 — Plan A : passe 2 par groupes de sources (`obikmerge`)
Fichier : `src/obikmerge/src/partition_merge.rs`, fonction `merge_partition`.
### 3a. Passe 1 sans ouvrir les couches sources
Construis la liste des chemins `unitigs.bin` sans `open()`. Pour chaque source et chaque `l in 0..partition.n_layers()`, prends `KmerLayer::new(&partition, l).unitigs_path()` (ce chemin est valide sur la variante `Empty`). Garde le filtre `exists()`. Ne touche pas au reste de la passe 1 (`build_graph`, `materialize_layer`, ouverture de `new_mphf`).
### 3b. Nouvelle couche : matrice initialisée seule
Si `any_new`, crée la matrice de la nouvelle couche avec `MatrixBuilder::new(presence, n_new, data_dir)`, ajoute les `n_dst_genomes` colonnes absentes, puis **ferme**. Les colonnes sources seront ajoutées par `resume`, groupe par groupe.
### 3c. Boucle sur les groupes
- `const SRC_GROUP: usize = 2;` (aligné sur `max_open`), avec un commentaire qui explique pourquoi.
- Itère sur `sources.chunks(SRC_GROUP)`, **dans l'ordre**, en tenant un `col_base` = nombre de colonnes sources déjà ajoutées avant ce groupe.
- Pour chaque groupe :
1. ouvre les couches de ses sources pour cette partition (`partition.layer(l)?.open()` puis `Arc::new`), comme aujourd'hui mais **seulement pour ce groupe** ;
2. `group_n` = somme des `src_n` du groupe ;
3. pour chaque couche dst existante, puis pour la nouvelle couche si `any_new` : `MatrixBuilder::resume`, vérifie `n_cols() == n_dst_genomes + col_base`, puis `add_col()` × `group_n` ;
4. construis les `pass2_items` du groupe. Le `col_offset` est **local au groupe** (0..group_n) ;
5. lance le pipeline de passe 2 existant, inchangé dans sa logique (Flat → Transform → Sink), sur ces items et ces builders. Les vecteurs `exist_sink`/`new_sink` ne contiennent que les colonnes du groupe ;
6. vérifie l'erreur de passe 2, ferme toutes les `ColBuilder` puis tous les `MatrixBuilder` du groupe ;
7. **drop** les couches du groupe avant de passer au suivant ;
8. `col_base += group_n`.
- L'initialisation `init_presence_matrix` (premier merge en présence) reste **avant** la boucle, inchangée.
- `dst_layers` (ouverts une seule fois) et `new_mphf` restent partagés par tous les groupes.
Invariant à documenter dans un commentaire : les colonnes sont ajoutées dans l'ordre des sources, donc la colonne absolue `n_dst_genomes + col_base + offset_local + g` est la même qu'avant la refonte.
### 3d. Vérification
`cargo test -p obikmerge`, `cargo clippy -p obikmerge`, puis `scripts/smoke_test_merge.sh --check benchmark/run/merge_oracle/synthetic` et `scripts/bench_merge_oracle.sh --check benchmark/run/merge_oracle/bench` (recompile le release avant). Les deux **doivent** passer sans aucun diff.
**Point d'arrêt.**
## Étape 4 — Plan C : colonnes construites en mémoire (`obicompactvec`)
But : plus aucun `MmapMut` ni fichier creux pour les colonnes **remplies** par le merge.
1. Lis `PersistentBitVecBuilder` (`bitvec.rs` : `new`, `set`, `close`), `PersistentCompactIntVecBuilder` (`builder.rs` : `new`, `set`, `close`), `format.rs` (`finalize_pciv`, `HEADER_SIZE`) et `mmap_file.rs` (`building_path`, `publish_built`). Note **exactement** les octets écrits à la fermeture : en-tête, données, overflow, `.building` puis `rename`.
2. Ajoute deux types :
- `MemBitVecBuilder` (dans `bitvec.rs`, ou un nouveau `mem_builder.rs` si `bitvec.rs` dépasse 500 lignes) : `words: Vec<u64>`, `n`, `path` ; `new(n, path)`, `set(slot, bool)`, `close() -> io::Result<()>` ;
- `MemCompactIntVecBuilder` : `primary: Vec<u8>`, `overflow: HashMap<usize, u32>`, `n`, `path` ; `new`, `set(slot, u32)` (même sémantique sentinelle 255 que le builder persistant), `close()`.
`close()` écrit avec un `BufWriter` dans `building_path(path)`, produit le **même fichier, octet pour octet**, que le builder persistant, fait `flush` + `sync_all`, puis `publish_built(path)`. Réutilise les fonctions de format existantes plutôt que de dupliquer la mise en page de l'en-tête. S'il faut factoriser l'écriture de l'en-tête ou de l'overflow pour la partager, fais-le dans `format.rs` / `mmap_file.rs`.
3. Dans `matrix_builder.rs` : ajoute les variantes `ColBuilder::MemBit(MemBitVecBuilder)` et `ColBuilder::MemInt(MemCompactIntVecBuilder)` (`set_val` et `close` les gèrent), plus `MatrixBuilder::add_mem_col() -> io::Result<ColBuilder>`. Ce dernier incrémente `n_cols` exactement comme `add_col`. Si les builders de matrice sous-jacents n'exposent ni le chemin de la prochaine colonne ni l'incrément, ajoute-leur une méthode `add_mem_col` symétrique de `add_col`. Le nommage des colonnes reste privé à la crate.
4. Tests unitaires (`src/obicompactvec/src/tests/`) : pour n ∈ {0, 1, 63, 64, 65, 10 000} et des valeurs pseudo-aléatoires (incluant des comptes ≥ 255), comparer **octet par octet** le fichier produit par le builder mémoire et celui du builder persistant. Vérifier aussi qu'une matrice construite avec `add_mem_col` se relit via `PersistentBitMatrix::open` / `PersistentIntMatrix::open`.
5. Dans `merge_partition`, remplace `add_col()` par `add_mem_col()` pour les colonnes sources (couches existantes et nouvelle couche). `add_absent_col` reste tel quel : on n'écrit jamais dans son mapping, donc aucun risque de SIGBUS.
6. Ajoute un commentaire sur le coût mémoire : `SRC_GROUP × src_n × (L_dst + 1) × (n/8 ou n)` octets au plus par partition.
7. `cargo test -p obicompactvec -p obikmerge`, clippy, puis `smoke_test_merge.sh --check` et `bench_merge_oracle.sh --check` (release recompilé).
`obikselect` et `obikfilter` ne sont **pas** migrés dans cette session.
**Point d'arrêt.**
## Étape 5 — Plan B : hors périmètre
**Ne pas implémenter.** Le plan B (ouverture « slots only » des couches dans `obikindex`) a été tranché par le développeur : ce sera un chantier séparé (forme retenue : composition, voir la section « Plan B » de `merge_mmap_audit.md`). Après l'étape 3, son gain en mmaps pour le merge est négligeable (~8 → ~2 par partition). Il touche en revanche le chemin de requête d'`obikindex` et concerne trois crates.
Les couches sources de la passe 2 continuent donc d'être ouvertes par `partition.layer(l)?.open()`, mais seulement groupe par groupe (étape 3). Ne crée aucun type ni méthode « lookup only » dans `obikindex` ou `obikmerge`.
## Étape 6 — Découpage, doc, finition
1. Découpe `partition_merge.rs` en module `partition_merge/` (par exemple `mod.rs` pour l'orchestration, `pass1.rs`, `pass2.rs`, `tests.rs`), chaque fichier sous 500 lignes, sans changement de comportement.
2. Supprime tout code devenu mort : `find_referencing_symbols` sur ce que la refonte a remplacé. Signale tout ce qui est devenu injustifié plutôt que de le garder par inertie.
3. `cargo test --workspace`, `cargo clippy --workspace`, `cargo check --workspace --features numa` si la feature existe, `scripts/smoke_test_index.sh`, `scripts/smoke_test_merge.sh --check` et `scripts/bench_merge_oracle.sh --check` (release recompilé ; reporte le temps de `merge_partitions` avant/après).
4. Documentation :
- `DevDocMD/implementation/merge_mmap_audit.md` : passe le statut à « implemented », en indiquant ce qui a été fait et les écarts éventuels au plan ;
- `DevDocMD/implementation/merge.md`, section « Algorithm » : décris le traitement par groupes de sources et les colonnes en mémoire ;
- vérifie si `UserDocMD/` décrit le comportement mémoire du merge, et le cas échéant mets-le à jour, en prose, sans code Rust ;
- mets à jour la `nav:` des `mkdocs*.yml` si un fichier a été ajouté, puis lance `qmd embed`.
5. Rapport final : liste des fichiers modifiés, résultats de tests, et estimation du nombre de mmaps par partition avant/après (calculée, marquée comme estimée). Termine par la commande de mesure à lancer en production, qui ne demande pas root :
```bash
PID=$(pgrep -f 'obikmer merge'); while sleep 60; do
echo "$(date +%T) maps=$(wc -l < /proc/$PID/maps) threads=$(ls /proc/$PID/task | wc -l)"; done
```
Ne commite rien : c'est moi qui le ferai.