algo/docs/collatz_features_and_fixes.md

Documentation consolidée — Collatz, corrections et livre enfant

Auteur : Équipe 4NK

Document unique regroupant les informations importantes des fichiers docs/features/ et docs/fixKnowledge/.

---

1. Collatz — Vérifications déterministes

1.1 C2 (réduction projective)

Objectif : Vérification déterministe des assertions du lemme C2 (complétion par frères, projection projective sur B_{12}).

Script : collatz_verify_c2_projective.py

Artefacts : docs/artefacts/collatz/c2_projective/verification_c2_projective.{json,md}

python3 applications/collatz/collatz_k_scripts/collatz_verify_c2_projective.py \
  --repo-root /home/ncantu/code/algo \
  --output-dir docs/artefacts/collatz/c2_projective

1.2 C3 (clôture locale)

Objectif : Artefact déterministe vérifiant une instance de C3 sur L=\mathrm{Lift}_{12\to m}(B_{12}) (témoins F et D8).

Script : collatz_verify_c3_local_descent.py

Artefacts : docs/artefacts/collatz/c3_local_descent/verification_c3_local_descent.{json,md}

python3 applications/collatz/collatz_k_scripts/collatz_verify_c3_local_descent.py \
  --local-h6-root docs/artefacts/collatz \
  --output-dir docs/artefacts/collatz/c3_local_descent \
  --palier 15

1.3 Clauses universelles (Option A)

Objectif : Conversion témoin local → clause universelle candidate (H4/H5), domaine L=\mathrm{Lift}_{12\to 13}(B_{12}).

Scripts : collatz_extract_universal_clauses.py, collatz_verify_universal_clauses.py

Artefacts : docs/artefacts/collatz/universal_clauses/clauses_universelles.{json,md}, verification_universal_clauses.{json,md}

Entrée : docs/artefacts/collatz/c3_local_descent/verification_c3_local_descent.json

1.4 Register K modular (couverture finie)

Objectif : Construire \mathcal{K}_M (clauses décidables à palier 2^M) et audit de couverture sur L.

Script : collatz_build_register_K_modular.py

Artefacts : docs/artefacts/collatz/register_K/palier2pM/register_K_mod2pM.{json,md}, audit_register_K_mod2pM.{json,md}, non_eligible_clauses_mod2pM.{json,md}, manifest_register_K_mod2pM.{json,md}

python3 applications/collatz/collatz_k_scripts/collatz_build_register_K_modular.py \
  --palier 15 --horizon-k 5 --repo-root /home/ncantu/code/algo

1.5 Certificat de raffinement

Objectif : Chemin de raffinement déterministe depuis n \bmod 2^M vers le résidu terminal stable.

Scripts : collatz_build_refinement_certificate_modular.py, collatz_build_refinement_certificate_over_Sm.py, collatz_build_refinement_certificate_over_Sm_multilevel.py, collatz_build_refinement_bundle_over_Sm_multilevel.py

Artefacts : docs/artefacts/collatz/refinement_K/palier2pM/refinement_certificate_mod2pM.{json,md}, variantes Sm, Sm_multilevel

---

2. Collatz — Extensions de grammaire

2.1 Clauses D_minor (descente minorée)

Objectif : Feuilles terminales D_{\underline{}} pour fermer des classes où une borne inférieure suffit à conclure.

Scripts : collatz_generate_minorated_descent_clauses_over_Sm.py, collatz_verify_minorated_descent_clauses_over_Sm.py, collatz_derive_brother_minorated_clauses_from_terminal_over_Sm.py

Artefacts : docs/artefacts/collatz/minorated_clauses_over_Sm/palier2p<M>/clauses_D_minor_over_Sm_mod2p<M>.{json,md}

python3 applications/collatz/collatz_k_scripts/collatz_generate_minorated_descent_clauses_over_Sm.py \
  --repo-root /home/ncantu/code/algo --palier 15 --k 8 --underlineA 13

2.2 Chaîne Hensel décalée (Phase 3)

Objectif : Fermer des racines en démarrant la chaîne Hensel à m=19 pour les résidus dont le frère à m=19 est fermable.

Script : collatz_build_hensel_chain_leaves_shifted.py

Paramètres : --start-m 19|20|21, --leaf-json

Résultat : 1373 résidus fermés à m=19 ; open_roots 1349→1101 (−248).

2.3 Plan d’extensions de grammaire (cas no/no)

Phases : Phase 1 (extension mécanique m=19..21), Phase 2 (multi-modulus, conclue négative), Phase 3 (chaîne Hensel décalée), Phase 4 (clause D partielle, recherche).

Rapports : docs/artefacts/collatz/refinement_K/palier2p15/phase1_grammar_extensions_report.md, option_a_extension_m24_report.md, option_b_hensel_m20_m21_report.md

2.4 Feuilles ciblées et diagnostic

Diagnostic : Sur les racines extrêmes, les deux enfants à m=16 n’ont pas de clause terminale décidable (cas no/no). lb_root typiquement dans [50, 136].

Script : collatz_diagnose_targeted_leaves_failure.py

Artefact : docs/artefacts/collatz/refinement_K/palier2p15/targeted_leaves/diagnostic_targeted_leaves_failure_mod2p15.md

---

3. Collatz — Rapports et artefacts

3.1 Générateur de rapports d’exécution

Objectif : Rapport standard (commande, artefacts, sha256, compteurs) sans transcript dans les documents mathématiques.

Script : collatz_generate_run_report.py

Profils : extend_finale, validation_section7, pipeline_d16_d17, fusion_palier2p25, local_H6_E1, local_H6, c2_projective, c3_local_descent, c3_local_descent_palier, universal_clauses, universal_clauses_palier

Format : docs/collatz_run_report_format.md

3.2 Artefacts H6 locaux et index

Objectif : Paquet d’artefacts par état E de B_{12} pour vérifier la couverture.

Script : collatz_generate_local_h6_artefacts.py

Artefacts : docs/artefacts/collatz/local_E{id}_palier2p{m}/, docs/artefacts/collatz/local_H6_index.md

3.3 Rationalisation conjoncture

Objectif : Un seul tronc canonique dans conjoncture_collatz.md, blocs annexes déplacés.

Scripts : collatz_conjoncture_rationalize.py, collatz_conjoncture_audit.py

Annexe : applications/collatz/conjoncture_collatz_annexes.md

Artefacts : docs/artefacts/collatz/conjoncture_rationalisation/audit_conjoncture.{json,md}

---

4. Collatz — Optimisation mémoire

Contexte : Plantages OOM pour m≥22 (clauses terminales).

Optimisations :

• Itérateur au lieu de liste ; mode streaming (JSONL temporaire) si total_roots > 500_000
• json.dump() vers fichier au lieu de json.dumps()
• Chargement prioritaire .residues.json (streaming ijson) pour paliers ≥20
• ResidueBitset pour leaves_by_m et closed (≈1 Mo)
• Chunked stream load pour noyau_post_D20.json (1.7 GB) ; run_update_noyau et run_single_palier en stream

Scripts concernés : collatz_generate_terminal_clauses_over_Sm.py, collatz_generate_minorated_descent_clauses_over_Sm.py, collatz_build_refinement_certificate_over_Sm_multilevel.py, collatz_build_hensel_chain_leaves_shifted.py

---

5. Corrections (fixKnowledge)

5.1 Docs status et transcript cleanup

Problème : Transcript terminal mélangé au texte mathématique ; conclusions affirmant une couverture totale alors que le résidu n’est pas vide.

Correctifs :

• Supprimer le transcript de conjoncture_collatz.md
• Requalifier la conclusion : fermeture globale conditionnelle à H_{\mathrm{ext}}(M): R_M=\varnothing
• Mettre à jour démonstration collatz.md : option hybride

Références : diagnostic_run_D18_D21_et_statut_preuve.md, errata_demonstration_collatz.md, plan_lemmes_manquants_et_programme_de_preuve.md

5.2 Scission : inférence palier et répertoires de sortie

Problème : palier inféré incorrectement (max valeur des classes si colonne générique) ; FileNotFoundError si répertoire parent absent.

Correctifs :

• Colonne palier ou m/modulus_power explicite ; fallback depuis le chemin palier2p<m>
• Créer out_json_path.parent avant écriture
• Ne pas ajouter de résidu 0 pour chaînes vides

Script : collatz_scission.py

5.3 Crash OOM paliers finale F16

Problème : 08-paliers-finale.sh et Cursor tués par OOM killer pendant F16 (chargement noyau_post_D20.json ~1.7 GB).

Correctifs :

• Exécuter le pipeline hors Cursor (terminal séparé, nohup)
• Stream load avec --modulo ; chunked processing pour build_fusion_clauses
• run_update_noyau et run_single_palier en stream pour fichiers >500 MB

Reprise : RESUME_FROM=D20 ./scripts/08-paliers-finale.sh

---

6. Livre enfant

Fichier : pour enfants/livre_enfant.md

Corrections v0.21 : Gérondifs sans sujet corrigés ; suppression introspection (E3) ; variation répétitions (N2) ; fusion phrases courtes (N5) ; formulations qualité littéraire.

Règles : .cursor/rules/redaction-pour-enfant.mdc

---

7. Index des scripts Collatz

Script	Rôle
collatz_verify_c2_projective.py	Vérification C2
collatz_verify_c3_local_descent.py	Vérification C3
collatz_extract_universal_clauses.py	Extraction clauses universelles
collatz_verify_universal_clauses.py	Vérification clauses universelles
collatz_build_register_K_modular.py	Register K et audit couverture
collatz_build_refinement_certificate_modular.py	Certificat raffinement (domaine L)
collatz_build_refinement_certificate_over_Sm_multilevel.py	Fermeture multiniveaux
collatz_build_refinement_bundle_over_Sm_multilevel.py	Pipeline bundle
collatz_generate_minorated_descent_clauses_over_Sm.py	Génération D_minor
collatz_verify_minorated_descent_clauses_over_Sm.py	Vérification D_minor
collatz_build_hensel_chain_leaves_shifted.py	Chaîne Hensel décalée
collatz_generate_run_report.py	Génération rapports
collatz_generate_local_h6_artefacts.py	Artefacts H6 locaux
collatz_conjoncture_rationalize.py	Rationalisation conjoncture
collatz_conjoncture_audit.py	Audit conjoncture
collatz_diagnose_targeted_leaves_failure.py	Diagnostic feuilles ciblées
collatz_scission.py	Scission (certificats)

---

8. Index des chemins d’artefacts

Chemin	Contenu
docs/artefacts/collatz/c2_projective/	Vérification C2
docs/artefacts/collatz/c3_local_descent/	Vérification C3
docs/artefacts/collatz/universal_clauses/	Clauses universelles
docs/artefacts/collatz/register_K/	Register K
docs/artefacts/collatz/refinement_K/	Certificats raffinement
docs/artefacts/collatz/minorated_clauses_over_Sm/	Clauses D_minor
docs/artefacts/collatz/local_E*_palier2p*/	Artefacts H6 par état
docs/artefacts/collatz/local_H6_index.md	Index agrégé H6
docs/artefacts/collatz/conjoncture_rationalisation/	Audit conjoncture