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`.
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_instructionsavant 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.
obikindexfait autorité : cette session n'y modifie et n'y ajoute rien.- Pas de fonctions libres ad hoc dans
obikmergepour combler un manque d'API. Si une opération générique manque sur un type deobicompactvec, ajoute-la comme méthode sur ce type. - Fichiers source sous ~500 lignes.
partition_merge.rsen 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)
- Lis
scripts/smoke_test_index.sh(modèle de style, options deobikmer index) et les--helpdeobikmer index,mergeetdump. - É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, puismerge 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 dansDIR,--check DIRles régénère et fait undiffavecDIR. Affiche PASS/FAIL clairement, avec un code de sortie cohérent.
- Lance
--record benchmark/run/merge_oracle/syntheticavec le code actuel, non modifié. Vérifie que les fichiers ne sont pas vides et que les colonnes de génomes ont du sens. - Lance aussitôt
--checksur 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 relancergmake index_count(GNU make ≥ 4.3 :gmakesur macOS). Demande-moi avant de le lancer, car ça prend du temps ;reference_index/(.npz) est absent :verify_merge_*.pyest 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 :
- Recompile le binaire release à partir du code actuel non modifié (
cargo build --releasedanssrc/). Ne touche pas aux artefacts existants debenchmark/run/. - Lance le merge des 20 index avec les mêmes options que
merge_presence.sh, mais vers un répertoire dédié, par exemplebenchmark/run/merge_oracle/bench/merged, jamaisbenchmark/run/global_index_presence. Garde le log stderr : le rapport de stages (wall et RSS demerge_partitions) sert de référence de performance. obikmer dumpdu résultat →sort→ compresse (zstd) +sha256sum, dansbenchmark/run/merge_oracle/bench/. La sortie peut être volumineuse : compare d'abord les hash, et ne fais undiffque s'ils diffèrent.- 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. - Écris ces étapes dans un script
scripts/bench_merge_oracle.shavec deux modes :--record DIRet--check DIR. En mode--check, il affiche aussi le temps demerge_partitionsavant/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é surmax_open), avec un commentaire qui explique pourquoi.- Itère sur
sources.chunks(SRC_GROUP), dans l'ordre, en tenant uncol_base= nombre de colonnes sources déjà ajoutées avant ce groupe. - Pour chaque groupe :
- ouvre les couches de ses sources pour cette partition (
partition.layer(l)?.open()puisArc::new), comme aujourd'hui mais seulement pour ce groupe ; group_n= somme dessrc_ndu groupe ;- pour chaque couche dst existante, puis pour la nouvelle couche si
any_new:MatrixBuilder::resume, vérifien_cols() == n_dst_genomes + col_base, puisadd_col()×group_n; - construis les
pass2_itemsdu groupe. Lecol_offsetest local au groupe (0..group_n) ; - 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_sinkne contiennent que les colonnes du groupe ; - vérifie l'erreur de passe 2, ferme toutes les
ColBuilderpuis tous lesMatrixBuilderdu groupe ; - drop les couches du groupe avant de passer au suivant ;
col_base += group_n.
- ouvre les couches de ses sources pour cette partition (
- L'initialisation
init_presence_matrix(premier merge en présence) reste avant la boucle, inchangée. dst_layers(ouverts une seule fois) etnew_mphfrestent 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.
-
Lis
PersistentBitVecBuilder(bitvec.rs:new,set,close),PersistentCompactIntVecBuilder(builder.rs:new,set,close),format.rs(finalize_pciv,HEADER_SIZE) etmmap_file.rs(building_path,publish_built). Note exactement les octets écrits à la fermeture : en-tête, données, overflow,.buildingpuisrename. -
Ajoute deux types :
MemBitVecBuilder(dansbitvec.rs, ou un nouveaumem_builder.rssibitvec.rsdé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 unBufWriterdansbuilding_path(path), produit le même fichier, octet pour octet, que le builder persistant, faitflush+sync_all, puispublish_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 dansformat.rs/mmap_file.rs. -
Dans
matrix_builder.rs: ajoute les variantesColBuilder::MemBit(MemBitVecBuilder)etColBuilder::MemInt(MemCompactIntVecBuilder)(set_valetcloseles gèrent), plusMatrixBuilder::add_mem_col() -> io::Result<ColBuilder>. Ce dernier incrémenten_colsexactement commeadd_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éthodeadd_mem_colsymétrique deadd_col. Le nommage des colonnes reste privé à la crate. -
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 avecadd_mem_colse relit viaPersistentBitMatrix::open/PersistentIntMatrix::open. -
Dans
merge_partition, remplaceadd_col()paradd_mem_col()pour les colonnes sources (couches existantes et nouvelle couche).add_absent_colreste tel quel : on n'écrit jamais dans son mapping, donc aucun risque de SIGBUS. -
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. -
cargo test -p obicompactvec -p obikmerge, clippy, puissmoke_test_merge.sh --checketbench_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
-
Découpe
partition_merge.rsen modulepartition_merge/(par exemplemod.rspour l'orchestration,pass1.rs,pass2.rs,tests.rs), chaque fichier sous 500 lignes, sans changement de comportement. -
Supprime tout code devenu mort :
find_referencing_symbolssur ce que la refonte a remplacé. Signale tout ce qui est devenu injustifié plutôt que de le garder par inertie. -
cargo test --workspace,cargo clippy --workspace,cargo check --workspace --features numasi la feature existe,scripts/smoke_test_index.sh,scripts/smoke_test_merge.sh --checketscripts/bench_merge_oracle.sh --check(release recompilé ; reporte le temps demerge_partitionsavant/après). -
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:desmkdocs*.ymlsi un fichier a été ajouté, puis lanceqmd embed.
-
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.