# 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}`

```bash
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}`

```bash
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}`

```bash
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}`

```bash
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 |