Files
obikmer/prompts/merge_mmap_refactor.md
T
Eric Coissac 1f199c69db feat: implement in-memory column builders and refactor merge partitioning
Introduce `MemBitVecBuilder` and `MemCompactIntVecBuilder` to construct columns in RAM before writing, reducing the number of open file descriptors during merge operations. Refactor `partition_merge.rs` to use these new builders via `add_mem_col`, decoupling live memory mappings from source counts to prevent `SIGBUS` errors.

- Add `mem_builder` module with `MemBitVecBuilder` and `MemCompactIntVecBuilder` structs for in-memory column construction and PCIV file writing.
- Extend `MatrixBuilder` with `add_mem_col` and `n_cols` methods, updating `ColBuilder` enum to support `MemBit` and `MemInt` variants.
- Refactor `partition_merge.rs` to use `add_mem_col` instead of `add_col`, introducing `run_pass2` for batch processing and optimizing destination layer handling.
- Update `format.rs` with `pciv_index_layout`, `write_pciv_header`, and `write_pciv_tail` functions to manage PCIV index layout and header/tail sections.
- Modify `mmap_file.rs` to use `write_std_header` and introduce `write_built` for standardized file writing and flushing logic.
- Make `MAGIC` constant public in `bitvec.rs` and update documentation for memory mapping alignment and structure.
- Add test modules `tests/matrix_builder.rs` and `tests/mem_builder.rs` to verify column counts and byte-identical output of new builders against persistent versions.
- Update `mkdocs.yml` navigation to include "Merge mmap audit (2026-11)" documentation entry.
- Add implementation audit documentation in `DevDocMD/implementation/merge_mmap_audit.md` detailing memory mapping failures and refactoring plans.
- Add merge testing scripts `scripts/smoke_test_merge.sh` and `scripts/bench_merge_oracle.sh` for validation and benchmarking.
- Bump `obikmer` package version from 1.4.2 to 1.4.3 in `Cargo.toml`.
2026-11-17 15:16:41 +01:00

15 KiB

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 :

    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.