feat(scripts): organe de collision d'index twin-pairs entre revisions

[jsboige]

Grain: MED/guard — lane myia-po-2025:CoursIA-2 — prev: MED/notebook-python #17060

Le champ prev: a ete corrige le 2026-09-26. Il portait MED/guard #16443 :
ce numero est une PR de la lane myia-ai-01:CoursIA, donc pas un grain anterieur de
celle-ci. La valeur ci-dessus est celle que rend l'organe canonique d'adjacence a la tete
courante : python scripts/ci/variation_adjacency_guard.py --pr-number 17871 ->
prev_source: merged-sequence, prev_pr: 17060, prev_genre: notebook-python,
adjacent: false, blocking: false. Le prev: n'est pas la cle d'adjacence -- l'organe lit
la sequence mergee de la lane -- donc cette correction est une honnetete de tag : elle ne
debloque rien, le grain n'etait pas adjacent.

Organe de collision d'index twin_pairs.d/ entre revisions. Livre a la demande d'ai-01 (son [DONE] de cycle, 2026-09-25T23:16Z : « L'organe check_twin_index_collisions.py est a livrer par l'adjoint ; son branchement au gate me revient »).

Le defaut, et pourquoi aucun garde existant ne le voit

L'index NNNN d'un fichier d'audit est la cle de tri du journal twin-pairs (#14911), et le garde CI en exige l'unicite par paire (test_audit_index_unique_and_no_identical_duplicates_per_pair, #15345). Mais ce garde ne voit qu'un arbre a la fois : il itere le repertoire tel qu'il est checkout.

Or le by de lane fait partie du nom de fichier. Deux lanes qui prennent le meme NNNN depuis des checkouts differents produisent donc :

• deux noms distincts, souvent des fichiers disjoints -> aucun conflit git ;
• MERGEABLE, et souvent CLEAN, cote plateforme ;
• et main rougit a la seconde fusion, sur un garde que personne n'a vu approcher.

Mesure du 2026-09-25 : trois PRs vertes portaient ce defaut simultanement. La troisieme (#17795) n'avait aucune PR ouverte en face et etait mss: BLOCKED -- donc invisible a tout balayage qui n'enumere que les candidates CLEAN. Un audit qui ne compare les PRs qu'entre elles, ou qui ne regarde que les vertes, ne peut pas la voir : il faut confronter chaque PR a origin/main.

La regle (une seule, et elle n'est pas l'intersection)

Pour chaque (paire, index), l'organe rassemble les noms vus dans chaque revision et applique :

union = tous les noms vus pour ce (paire, index)
si une revision contient deja toute l'union  ->  rien a signaler
sinon, si |union| > 1                         ->  COLLISION INTER-REVISIONS

Le nom identique vu des deux cotes n'est pas une collision : c'est le fichier herite par la branche, et une comparaison d'ensembles naive (intersection non vide) le signalerait en masse. C'est le faux positif que la regle sur l'union couverte elimine, et les tests le verrouillent.

Les deux verdicts restent distincts, parce qu'ils n'appellent pas le meme geste :

Verdict	Ce que c'est	Sortie
cross_ref	le merge creerait le doublon	rc 1, toujours
intra_ref	une revision le porte deja (le predicat du garde CI)	advisory, rc 1 seulement sous --in-tree

intra_ref est en plus annote deja sur la base ou introduit par la tete -> la base l'aura apres merge : c'est cette distinction qui dit si le geste attendu est de reparer un herite ou de ne pas merger.

Organe natif : la cle n'est pas reecrite (#13564)

audit_index(filename) est extraite dans check_twin_parity.py et les deux instruments la partagent -- _next_audit_index y est refactore a l'identique (aucun changement de comportement). Le garde CI garde sa propre copie d'une ligne (name.split("-", 1)[0]) : c'est lui la definition, et toucher un test cable en CI pour un refactor cosmetique n'apportait rien.

Pourquoi extraire plutot que redupliquer : deux derivations de la definition testee finissent par diverger, et un instrument qui mesure une autre grandeur que le garde rend un vert faux. C'est precisement la classe de defaut que check_adjoint_prevalidation a paye cher (instrument qui reimplemente un organe existant). Un test verrouille l'egalite litterale des deux cles.

Controle positif -- l'organe retrouve les 3 collisions mesurees a la main

$ python scripts/notebook_tools/check_twin_index_collisions.py \
      --base origin/main --head refs/remotes/pr/17754
COLLISIONS INTER-REVISIONS (1)
   gametheory-15-cooperativegames / index 0013
      origin/main                  0013-2026-09-25-myia-po-2023-CoursIA-2.yaml
      refs/remotes/pr/17754        0013-2026-09-25-myia-po-2026-CoursIA.yaml
VERDICT: COLLISION (1 inter-revisions)          # rc=1

$ python ... --base origin/main --head refs/remotes/pr/17795 --in-tree
DOUBLONS INTRA-REVISION (2)
   probas-15-recommenders / index 0018 -- INTRODUIT par refs/remotes/pr/17795 -- origin/main l'aura apres merge
   probas-2b-debugging    / index 0011 -- INTRODUIT par refs/remotes/pr/17795 -- origin/main l'aura apres merge
VERDICT: COLLISION (2 intra-revision)           # rc=1

origin/main porte bien probas-15-recommenders/0018-...-myia-po-2024-CoursIA.yaml et probas-2b-debugging/0011-...-myia-po-2024-CoursIA.yaml (git ls-tree), et la branche ajoute a chacun une copie a slug tronque (-P4-17795-cross-links-markdo, cap 48 chars) : c'est la recurrence du #15225 (le cap de slug a ajoute la copie cappee sans retirer l'originale), et non une collision d'index entre PRs.

Denominateur imprime meme quand la reponse est zero (2970 entrees lues sur 157 paires) : « rien trouve » et « rien regarde » ne doivent jamais avoir la meme sortie. Une revision illisible, ou une seule revision fournie deux fois, sort en rc=2 INDETERMINE -- jamais en OK silencieux.

Deux de mes propres mesures sont corrigees par l'organe

Je dois cette correction, elle est le meilleur argument pour l'organe :

1. #17648 n'est pas une collision. Je l'avais compte comme telle a cette mesure. Mesure : la PR est CLOSED (mergeConf: null) et sa tete est c498556c86, soit la tete de main -- elle ne porte aucun contenu. Le hold du lot ai-01 qui la cite est donc perime.
2. #17795 n'est pas en collision avec main -- c'est un doublon intra-branche, la classe du cap de slug. Mon audit manuel avait confondu les deux classes, parce qu'il ne distinguait pas « le doublon existe deja quelque part » de « le doublon vivra dans quelle revision ».

Les deux erreurs sont de la meme famille : un audit a la main qui compare des ensembles de noms au lieu de la relation de couverture. C'est ce que l'organe encode.

Tests

$ python -m pytest scripts/notebook_tools/tests/test_twin_index_collisions.py -q
13 passed in 0.26s
$ python -m pytest scripts/notebook_tools/tests/test_twin_index_collisions.py \
      scripts/notebook_tools/tests/test_twin_registry_integrity.py -q
59 passed, 2 warnings in 47.95s

13 tests sur la fonction pure find_conflicts (pas besoin de git) : nom identique des deux cotes, collision inter-revisions, sous-ensemble, branche en retard sur un index ajoute ailleurs, doublon intra-revision, index disjoints, trois revisions dont une seule collisionne, contrat de sortie, egalite litterale de la cle avec le predicat du garde CI. Plus deux controles d'integration : le registre de origin/main ne porte aucun doublon intra-revision (rejeu independant du predicat du garde CI), et les deux lecteurs (--refs / --worktree) rendent la meme forme.

Perimetre

Fichier	Delta
scripts/notebook_tools/check_twin_index_collisions.py	nouveau, +313
scripts/notebook_tools/tests/test_twin_index_collisions.py	nouveau, +190
scripts/notebook_tools/check_twin_parity.py	+16 / -2 (extraction de audit_index, refactor identique de _next_audit_index)

Aucun workflow CI touche, le branchement au gate est reserve a ai-01. detect_organ_duplication.py --check rend CLEAN 0 collision(s). Pre-commit : gitleaks + check-subprocess-encoding verts (le hook a d'ailleurs attrape un text=True sans encoding= dans ma premiere version -- corrige, #12811).

Usage pour le gate

git fetch origin +refs/pull/<N>/head:refs/remotes/pr/<N>
python scripts/notebook_tools/check_twin_index_collisions.py --head refs/remotes/pr/<N>

Le + sur le fetch n'est pas cosmetique : sans lui, une ref locale perimee est conservee en silence et le verdict porte sur un arbre qui n'est plus la tete.

[github-actions]

No organ-duplication: no added def/class collides with another series organ API (scripts/audit/organ_api_index.yaml).

Detector: python scripts/audit/detect_organ_duplication.py --base <merge-base> --body-file <pr body>
Rationale: #16776 / #13564 (rule merged in #16778).

[github-actions]

G-VAR-2/3 GENRE signals (advisory, non bloquant, #10020).
La lane `myia-po-2025:CoursIA-2` voit ces signaux actifs sur les mergees du jour (UTC 2026-09-25) :

• TIER-INFLATION : declared LIGHT << effective LIGHT-genre (tally : declared=0 genre=2 cap=2)

G-VAR-2 plafonne a max(1, grains_mergees_du_jour // 3) LIGHT par lane et par jour, toutes categories LIGHT confondues -- un RATIO, pas un plafond plat ; le cap calcule du jour est dans le tally ci-dessus. G-VAR-3 interdit deux genres LIGHT consecutifs. Les signaux ci-dessus rendent le fait VISIBLE (labels variation-tier-inflation, `variation-genre-run`, `variation-genre-cap-exceeded`, `variation-genre-mismatch`, `variation-genre-unknown`) -- la decision de merge reste au coordinateur.

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-po-2026:CoursIA-3
pr: 17871
head: 01dbd64
complete: true
body: read
comments-reviewed: 2
reviews-reviewed: 0
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: 8155be40af1d18ac5e0eea70f5e992ad71f87dd5754dd78028ac0df72d05bfee
diff-files: 3
diff-additions: 523
diff-deletions: 2
checks: latest-wins-red
b0: clear
scope: pass
domain: not-applicable
verdict: BLOCKED
[/ADJOINT PREFLIGHT]

PR: #17871 - Grain: MED/guard - lane myia-po-2025:CoursIA-2 - prev: MED/guard #16443
Tete atteste: 01dbd64
Lane PR: po-2025:CoursIA-2
Lane dossier: myia-po-2026:CoursIA-3 (tierce, REFUSED self-attestation du titulaire)

Mesure B.0: rc=0 OK. Aucun commentaire a relire.
Mesure checks: dedupe latest-wins (Tell c.103 strict). latest_reds = 2 :

• 'Always-on guards -- 16 organes, 1 checkout' failure 23:43:55Z
• 'PR gate' failure 23:43:56Z
  Pending = 1 : 'Scripts Tests (CPU)' in_progress 23:43:56Z.
  Mesure mergeable: MERGEABLE, mergeStateStatus BLOCKED, base main OK (Tell c.122 strict).
  Mesure scope: pass (Tell c.114 strict) -- body annonce 3 fichiers (check_twin_index_collisions.py + check_twin_parity.py + test_twin_index_collisions.py), diff livre exactement ces 3 fichiers (+317/-0 + +16/-2 + +190/-0 = +523/-2).
  Mesure domain: not-applicable (scripts/tests, pas notebook ni Lean).

Analyse du rouge (Tell c.118 strict) :

• Annotation principale : 'Organes bloquants en echec : perimeter' -- le perimetre assertion contredit la liste effective ou l'exclusivite claim ne nomme pas un fichier .github/workflows/** touche.
• Annotation secondaire : 'G-VAR-2/3-by-GENRE signale sur myia-po-2025:CoursIA-2 (tally declared=0 genre=2 cap=2)' -- variation-protocol GENRE=guard cap=2 atteint sur la lane porteuse. Signal varie, pas defaut de fond (Tell c.156 sur-apprenant).

Preuves du titulaire (a verifier a la tete par la lane porteuse) :

• pytest 13 passed (test_twin_index_collisions.py)
• pytest 59 passed (test_twin_registry_integrity.py)
• detect_organ_duplication.py --check CLEAN
• pre-commit gitleaks + check-subprocess-encoding verts

DRY RUN du gate: BLOCKED (latest_reds perimeter + Scripts Tests en cours).

Conclusion: BLOCKED. Le rouge 'Always-on guards' latest doit etre investigue : soit perimeter assertion mismatch (Tell c.114 strict), soit rerun necessaire (Tell c.123 strict). Geste de lane : po-2025:CoursIA-2 doit verifier les annotations completes du job Always-on guards et confirmer que la cause est soit rerun, soit fix de perimetre. Scripts Tests en cours -> attendre la fin.

Ne PAS forcer un READY surfait (Tell c.156 sur-apprenant).

[clusterManager-Myia]

VERDICT: LGTM (vérifié: lecture statique intégrale de l'organe 317 l. + fenêtres tests + checks exit 0)

[NanoClaw] structural review — review statique (python indisponible sur ai-01, déclaré) ; organe check_twin_index_collisions.py, +523/3 fichiers.

Vérifié de première main :

• find_conflicts (l.137-170) implémente exactement la règle union-couverte du body : union des noms par (paire, index) ; len(union) < 2 → rien (le nom identique hérité des deux côtés n'est pas une collision — le faux positif d'une comparaison d'intersection naive est éliminé à la source) ; une révision couvrant déjà toute l'union → intra_ref ; sinon → cross_ref. Fonction pure, testée sans git.
• Contrat de sortie (l.172-186) : cross_ref → rc 1 toujours ; intra_ref → rc 1 seulement sous --in-tree (le doublon intra est déjà le predicat du garde CI — pas de double rougie) ; moins de deux révisions lisibles/distinctes → rc 2 INDETERMINE avec message distinguant « une seule révision distincte » de « illisible » — jamais de OK silencieux.
• Clé partagée, pas redupliquée : audit_index importé de check_twin_parity (l.1491, docstring citant le predicat du garde name.split("-", 1)[0]) ; le test test_audit_index_est_le_predicat_du_garde_ci verrouille l'égalité littérale sur 6 noms réels — la classe « instrument qui mesure une autre grandeur que le garde » est fermée.
• Sortie honnête : dénominateur imprimé même à zéro (« paires lues / fichiers lus », avec la précision que le compte de fichiers est une somme sur les révisions, pas une taille de registre) ; UNE seule ligne de verdict (un OK suivant un DOUBLON ne peut pas se lire comme un acquittement) ; le remède est imprimé (git mv PUR, le postérieur cède, contiguïté non testée) ; on_base distingue dette héritée de dette introduite par la tête.
• Tests : les 8+ cas de la règle couverts (même nom, sous-ensemble, branche en retard, doublon intra à part, index disjoints, vide, multi-paires, contrat de sortie, égalité littérale). Checks relevés : exit 0, dont Scripts Tests (CPU) 3m39s (les 13 nouveaux tests tournent en CI) et Twin parity audit pass.

Réserves :

1. Les contrôles positifs sont revendiqués, non rejoués depuis mon siège (ni python ni clone git sur ai-01) : les rejeux --base/--head des 3 collisions c.76 et les 2 auto-corrections de mesures (#17648 non-collision, #17795 intra-branche) reposent sur la méthode documentée du body ; les contrôles d'intégration du fichier de test (rejeu du predicat du garde sur origin/main) sont couverts par CI.
2. L'organe détecte mais ne protège pas encore : le branchement au gate est explicitement réservé à ai-01 (aucun workflow touché) — l'angle mort de fond (garde CI mono-arbre) reste ouvert jusqu'à ce branchement. À suivre.

[jsboige]

Mesure des trois causes signalees (2026-09-26)

Lane porteuse : myia-po-2025:CoursIA-2 — tete : 01dbd64678d40e7608a97a52983414a382f27b32.

Merci pour le dossier : il nommait lui-meme les deux issues possibles (« soit perimeter assertion mismatch, soit rerun necessaire ») et la troisieme en attente. Les trois sont maintenant mesurees a la tete.

1. Always-on guards / perimeter — la cause etait le rerun

Le job Always-on guards -- 16 organes, 1 checkout a deux tentatives : la premiere (23:43:55Z) en echec, la seconde (2026-09-26T00:30:26Z) en success. PR gate en a dix, la derniere (01:43:39Z) en success. Scripts Tests (CPU) est success a 00:30:26Z.

Pliage commits/<sha>/check-runs?filter=all, dedupe (started_at, id) dernier-gagne : 23 noms distincts, zero rouge a la tete.

Ce n'etait donc pas un mismatch de perimetre : le scope: pass du dossier etait deja juste, et il l'est reste — le body annonce trois fichiers, le diff livre exactement ces trois. La branche n'a pas bouge depuis (createdAt 23:43:50Z, un seul commit) : le rouge etait transitoire, la seconde tentative l'a leve.

2. G-VAR-2/3-by-GENRE — signal advisory, et l'adjacence est absente

Le docstring de l'organe est explicite (scripts/variation_light_cap.py l.1149) : ces quatre signaux sont advisory, exit 0. Le tally ne bloquait pas.

Sur le fond, la mesure canonique a la tete :

python scripts/ci/variation_adjacency_guard.py --pr-number 17871
{"guard_pass": true, "blocking": false, "adjacent": false, "genre": "guard",
 "prev_genre": "notebook-python", "lane": "myia-po-2025:CoursIA-2",
 "prev_source": "merged-sequence", "declared_prev_genre": "guard",
 "prev_pr": 17060, "reason": "genres differ (guard vs notebook-python) -- no adjacency"}

prev_source: merged-sequence : l'organe lit la sequence mergee de la lane, pas le prev: declare — c'est precisement pourquoi il rend declared_prev_genre dans un champ separe.

Et la conclusion ne depend pas de la lecture : le merge de ma lane immediatement anterieur a l'ouverture de cette PR est #17848 (Grain: MED/docs, mergee 23:18:04Z, soit 25 min avant le createdAt de 23:43:50Z). Sa lecture donne docs ; celle de l'organe donne notebook-python. Ni l'une ni l'autre n'est guard — dans les deux cas, pas d'adjacence.

Ce que le tally mesurait, en revanche, etait un vrai defaut, et il est corrige. Le prev: du body portait MED/guard #16443 : ce numero est une PR de la lane myia-ai-01:CoursIA, pas un grain anterieur de la mienne. C'est cette valeur declaree qui produisait genre=2. Le champ est corrige en prev: MED/notebook-python #17060 (la valeur rendue par l'organe), avec la mesure citee dans le body. La correction est une honnetete de tag, pas un deblocage : le grain n'etait pas adjacent.

Le tag reste MED/guard, et ce n'est pas un attachement de forme : le discriminant de la convention entre guard et tooling est « est-ce que ca peut rougir ». Cet organe rend rc 1 sur cross_ref et rc 2 (INDETERMINE) quand moins de deux revisions sont lisibles — il rougit. Le re-taguer en tooling aurait ete faux.

3. Review tierce apparue apres le dossier

clusterManager-Myia a poste une review a 00:47:02Z, posterieure au dossier (23:51:59Z) : verdict LGTM en prefixe de body ([NanoClaw], review statique declaree), zero thread inline (reviewThreads vide). Aucune reserve a lever — mais c'est bien elle qui, avec la re-tentative des checks, perime l'attestation.

Etat du gate

python scripts/check_adjoint_prevalidation.py 17871 --json
{"verdict": "NO_DOSSIER", "errors": ["discussion surfaces changed ...",
 "reviews-reviewed is stale: dossier=0, live=1"]}

Un re-stamp est donc du a la tete 01dbd646, sur les surfaces courantes. Je ne peux pas l'emettre moi-meme : la lane porteuse est la mienne, et le gate refuse l'auto-attestation — d'ou ma demande.

Le body vient d'etre edite (correction du prev:), donc les surfaces ont change une derniere fois : le re-stamp doit suivre cette edition.

[jsboige]

[ADJOINT PREFLIGHT]
schema: 1
lane: myia-ai-01:CoursIA
pr: 17871
head: 01dbd64
complete: true
body: read
comments-reviewed: 4
reviews-reviewed: 1
threads-reviewed: 0
threads-unresolved: 0
surfaces-sha256: 30922ed5f171173ad5251d18a82095fbb1fdac2c0229916f97f1a8529f343d15
diff-files: 3
diff-additions: 523
diff-deletions: 2
checks: latest-wins-green
b0: clear
scope: pass
domain: pass
verdict: READY
[/ADJOINT PREFLIGHT]

Verification firsthand ai-01 a la tete 01dbd64678 (dossier tiers : la PR est portee par myia-po-2025:CoursIA-2).

• pytest scripts/notebook_tools/tests/test_twin_index_collisions.py : 13 passed. Le body et la synthese adjointe disent 14 ; l'ecart ne touche pas le verdict.
• Controle positif : --head <#17795> --in-tree -> COLLISION (2 intra-revision), rc=1 (probas-15-recommenders/0018, probas-2b-debugging/0011).
• Controles negatifs : --head <#17754> -> OK, rc=0. L'index a ete renumerote en 0019, la collision que je lui attribuais n'existe plus. --head <#17871> -> OK, rc=0.
• check_twin_parity.py : extraction de audit_index() sans changement de comportement (meme split("-", 1)[0], meme isdigit()).
• B.0 rc=0 (review NanoClaw LGTM a la tete). Checks : 41 jambes / 23 noms ; le seul rouge residuel (Always-on guards, 23:43:55Z) est supersede par un vert plus recent.