Skip to content

lean(knot,#2874): refondre Conway.lean en sous-fichiers progressifs avec commentaires de digestion #18397

Description

@jsboige

Constat first-hand

MyIA.AI.Notebooks/SymbolicAI/Lean/knot_lean/Knots/Conway.lean est aujourd'hui un mur de 3 736 lignes dans un seul namespace Knots, avec 112 déclarations enchainées sans coupure par fichier. Mesure :

  • wc -l : 3 736 lignes (sibling EN Conway_en.lean de taille comparable, convention i18n i18n(lean): harmoniser les fichiers .lean en francais + traduction anglaise — inventaire, convention, PR pilote #4980 doublonne la lecture).
  • grep -cE "^(theorem|lemma|def|structure|inductive|namespace|end )" : 112 déclarations.
  • grep -cE "^/-!|^/--|^-- " : ~33 commentaires/docstrings de section. Le ratio signal/bruit reste honorable intra-fichier, mais la navigation est impossible : on ne saute pas un mur de 3 736 lignes pour chercher où est définie KT_trivial_alexander.
  • Un seul namespace Knots (ligne 33) → end Knots (ligne 3736). Aucun section Lean intermédiaire.

Sections thématiques déjà présentes en docstrings mais non séparées en sous-fichiers (relevé manuel sur le source) :

Bornes (lignes) Thème Mentions
35–244 Mutation de Conway (KleinRot, mutateWindow, AreMutants, contrôle négatif trèfle) /-! ## 1. Mutation de Conway l.35, contrôles l.195–244
244–319 Codes PD Conway / KT + contrôles wf contrôles conway_wf l.265, kinoshitaTerasaka_wf l.306
319–1544 arcPartition + lemmes de préservation (mergePair_symm, sameClass_*, foldl, etc.) — brique majeure du PR #16650 ~1 200 lignes, soit ~32 % du fichier
(muettes dans le source mais visibles aux en-têtes /-!) Polynômes d'Alexander (Conway t⁰, KT t⁵), preuves par déterminant Dehn conway_trivial_alexander et KT_trivial_alexander (l.2889) — preuves set_option maxRecDepth 8000 in qui s'étendent sur 200+ lignes
3635–3656 Nœuds slice (IsSmoothlySlice, IsTopologicallySlice) squelette def ... := sorry
3656–3736 Théorème de Piccirillo (conway_not_smoothly_slice) énoncé seul, 4 sorry permanents

Les 4 exact sorry (l.3677, 3707, 3718) et les 2 def ... := sorry (l.3644, 3652) sont explicitement marqués permanents dans les commentaires (« This sorry is effectively permanent », « Mathlib prerequisites missing »). Ce ne sont pas des dettes à lever, ce sont des limites connues : théorie des 4-variétés lisses, s-invariant de Rasmussen, homologie de Khovanov — toute la machinerie est hors Mathlib.

Pourquoi c'est un problème

  1. Navigation impossible : un lecteur qui cherche mergePair_symm (l.361) doit grep -n dans un fichier monolithique. Aucune table des matières en tête, aucun section Lean, aucun point d'entrée par sous-thème.
  2. Progression pédagogique invisible : la séquence « mutation → contrôle négatif trèfle → contrôle positif Conway/KT → arcPartition → Alexander → slice → Piccirillo » est didactique (chaque étape pose un objet utilisé par la suivante), mais elle n'est lisible qu'en lisant tout le fichier.
  3. Commentaires de digestion absents : la convention i18n FR/EN i18n(lean): harmoniser les fichiers .lean en francais + traduction anglaise — inventaire, convention, PR pilote #4980 a ses /-! de section, mais le corps des preuves (by induction ... ; simp_all ; ring) n'a aucun commentaire expliquant pourquoi cette tactique, quelle est l'intuition, où la preuve réutilise un lemme antérieur. C'est particulièrement vrai pour les preuves par déterminant Dehn (lignes 1000–2900) où le Matrix.of ![...] puis Matrix.det_of_upperTriangular ne disent rien au lecteur non-averti.
  4. Le sibling EN duplique le mur : Conway_en.lean reproduit la même structure monolithique (convention sibling pair i18n(lean): harmoniser les fichiers .lean en francais + traduction anglaise — inventaire, convention, PR pilote #4980 : byte-identique hors docstrings). Un split du FR impose un split du EN, sinon l'organe check_i18n_siblings.py ne valide plus le corps byte-identity.
  5. Cible lake build non scopée : un lake build Knots.Conway recompile 3 736 lignes à chaque modification. Un split par sous-thème permettrait un cache plus granulaire et un cycle PR/review plus court.

Cause racine

Conway.lean a grandi par accretion (cf. git log --oneline -- Knots/Conway.lean — 16 commits visibles) :

À chaque PR, le diff s'ajoute au fichier maître. Personne n'a séparé en sous-fichiers parce que la doctrine de gradation (« un sujet = un fichier ») n'a pas été appliquée rétroactivement au moment où le sujet a cessé d'être un.

Portée proposée (à arbitrer coordinateur)

Option A — Split par section thématique (préférée) :

Fichier Contenu Bornes actuelles
Knots/Mutation.lean + _en.lean KleinRot, mutateWindow, AreMutants, contrôle négatif trèfle l.35–244 (~210 lignes)
Knots/ConwayPD.lean + _en.lean Codes PD Conway / KT + contrôles wf + mutants concrets l.244–319 (~75 lignes)
Knots/ArcPartition.lean + _en.lean mergePair, arcPartition, lemmes de préservation l.319–1544 (~1 225 lignes)
Knots/AlexanderTrivial.lean + _en.lean conway_trivial_alexander (t⁰), KT_trivial_alexander (t⁵), preuves Dehn ~1 200 lignes
Knots/Slice.lean + _en.lean IsSmoothlySlice, IsTopologicallySlice, théorème de Piccirillo l.3635–3736 (~100 lignes)
Knots/Conway.lean + _en.lean Stub aggregator : importe les 5 sous-fichiers + namespace Knots ouvert-fermé (~30 lignes)

Avantages :

  • Chaque sous-fichier devient un point d'entrée digestible (~75–1 225 lignes, la borne haute reste l'ArcPartition qu'on peut re-splitter en ArcPartition/Basic.lean + ArcPartition/Invariance.lean).
  • lake build Knots.Mutation compile ~210 lignes au lieu de 3 736.
  • La convention i18n sibling pair reste byte-identique par sous-fichier, ce qui est même plus précis qu'aujourd'hui (toute la docstring FR diffère du EN, on pourra auditer fichier par fichier).
  • La progression pédagogique devient structurelle : lire dans l'ordre Mutation → ConwayPD → ArcPartition → AlexanderTrivial → Slice raconte le cours.

Option B — Split minimal : séparer seulement la section Slice (l.3635–3736, 100 lignes, 4 sorry permanents + Piccirillo) en Knots/Slice.lean. Le reste reste monolithique. Plus rapide (1 PR) mais ne résout pas la navigation ni les commentaires de digestion.

Commentaires de digestion : à intégrer dans la PR de split, dans les deux siblings (convention FR/EN : seules les docstrings diffèrent, mais les commentaires -- ... sur les lignes de tactique sont aussi à dupliquer). Trois niveaux :

  1. En-tête de section (déjà partiellement présent en /-!) : expliciter le pourquoi de la section, pas le quoi.
  2. Au-dessus de chaque preuve (ligne vide puis -- ...) : dire ce que la preuve établit en une phrase.
  3. Au-dessus de chaque set_option ou simp non-trivial : expliquer pourquoi cette option est nécessaire (ex. maxRecDepth 8000 l.2882 : la récursion sur les mineurs de Gauss explose la borne par défaut, on borne O(10²)).

Garde anti-régression

python scripts/lean/count_code_sorry.py --json : avant/après. Le compte distinct_code_sorry doit rester à 8 pour knot_lean (les 4 sorry permanents sont doublonnés FR/EN par la convention #4980). Si le split change ce compte, c'est une régression (anti-regression.md).

scripts/lean/check_i18n_siblings.py --all : pour chaque nouveau sous-fichier FR, vérifier que le _en sibling reste byte-identity hors docstrings/commentaires.

lake build Knots.Conway + lake build Knots.Mutation + lake build Knots.ArcPartition + lake build Knots.AlexanderTrivial + lake build Knots.Slice doivent tous passer.

Liens

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions