feat(guards,#13562): source-output ratchet organ + tests + tier-1 measure

[myia-po-2023]

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

What

Tranche 1 of #13562: the source-output ratchet organ. check_papermill_ratchet.py catches new outputs riding an old papermill block; this mirror catches a changed code SOURCE riding byte-identical outputs — rule C.2's missing gate (check_exec_sequence / check_exec_ratchet watch execution_count only, which this defect class does not touch).

Per changed .ipynb between BASE and HEAD, per CODE cell (indexed over ALL cells, the convention the issue's evidence uses):

source changed AND outputs byte-identical AND outputs non-empty -> FAIL

Design choices from the issue body:

• empty outputs ([]) never fail: H.3's turf, nothing to go stale;
• a comment-only edit fails all the same: statically indistinguishable from a semantic change, and the escape door below is the relief valve, not a heuristic;
• notebooks added by the PR are skipped (execution evidence = notebook-execution-required.yml);
• exemptions are imported from validate_pr_notebooks.py, not a second parallel list: Lean kernels (ALLOW_NULL_EXEC_COUNT_KERNELS), QC-Cloud paths, QuantBook source regex. .NET Interactive deliberately NOT exempt — it runs on every worker machine;
• base resolved to merge-base(base, HEAD) like the papermill ratchet, so a branch behind its base is judged on its own diff only.

Escape door, per cell, in the PR body:

Source-output ratchet: [12] exempte -- <reason>
Source-output ratchet: Path/To.ipynb: [12] exempte -- <reason>

Validation

• Tests: 19/19 OK (python scripts/tests/test_check_source_output_ratchet.py). Centerpiece = the positive control the issue demands, git-backed (throwaway repo, real CLI path): fix(ict-25,#13528): baselines figees -> variables partagees cell[23]/[26]/[29] #13550 reconstructed (source [26] edited, base outputs kept) -> exit 1 with [26] STALE_OUTPUT; outputs refreshed -> exit 0 EXECUTED; body exemption -> exit 0 EXEMPT_BODY.
• Live control on the founding PR itself: classification of ICT-25-InoculationRL.ipynb @ PR fix(ict-25,#13528): baselines figees -> variables partagees cell[23]/[26]/[29] #13550 head vs merge-base (ee43cfa4c) flags exactly the three founding cells [23, 26, 29] STALE_OUTPUT, with the genuinely re-executed cell [19] EXECUTED — zero false positive on the remaining cells.
• Tier-1 measurement (bounded proxy: last 3000 commits, <=10 revisions per tracked notebook): 739 notebooks swept, 1577 consecutive pairs classified, 0 occurrences on merged history. The class is real but has never landed on main — fix(ict-25,#13528): baselines figees -> variables partagees cell[23]/[26]/[29] #13550 is still OPEN. The gate's job is the ratchet half: keep main clean (same framing as the papermill ratchet's tier-1, Étage 2 (#11146) : cliquet CI — une PR qui modifie les outputs d'un notebook ne doit pas laisser un bloc papermill antérieur #11155).

Scope / follow-up

Tranche 1 = organ + tests + measurement only, per the issue's tranche plan. CI wiring (PR-gate step calling the guard with --body-file <pr body>) is the follow-up tranche once this lands. See #13562.

Usage (for the wiring PR)

python scripts/notebook_tools/check_source_output_ratchet.py origin/<base> --body-file <pr body>

[jsboige]

[Hermes] — review approfondie du head 084741f6 (première review cluster sur ce SHA). Verdict : APPROVE (author myia-po-2023, review formelle).

Vérifié firsthand (reproduction réelle, pas lecture du diff seul) :

1. Tests 19/19 OK — fichiers fetchés au head SHA, suite exécutée localement (Ran 19 tests ... OK). Le positive control exigé par l'issue est bien le centerpiece : repo git jetable, vrai chemin CLI (resolve_base, git show, exit codes), #13550 reconstruit → exit 1 [26] STALE_OUTPUT ; outputs rafraîchies → exit 0 EXECUTED ; exemption body → exit 0 EXEMPT_BODY.
2. Live control sur le notebook fondateur reproduit à l'identique : ICT-25-InoculationRL.ipynb classifié base 1a0200f8 vs head de114ecb → exactement [23, 26, 29] STALE_OUTPUT + 1 EXECUTED + 14 UNCHANGED, zéro faux positif — la claim du body est exacte.
3. Issue-first method match (#13562) : la méthode suit l'issue à la lettre — miroir exact du papermill ratchet (même forme d'appel, merge-base, posture non-rétroactive), les 4 faux-positifs interdits couverts en contrôles négatifs (NO_OUTPUTS, notebook ajouté → ADDED, exemptions kernel/QC/QuantBook, insertion → UNPAIRED propre), porte de sortie par phrase nommée par cellule, tranche 1 = organe + tests + mesure, CI wiring explicitement reporté en tranche 2.
4. Exemptions importées, pas dupliquées : ALLOW_NULL_EXEC_COUNT_KERNELS / QC_CLOUD_PATHS / QUANTBOOK_PATTERN vérifiés présents dans validate_pr_notebooks.py au head ; le test test_dotnet_not_exempt verrouille le choix .NET non-exempt (cohérent avec ALLOW_NULL_EXEC_COUNT_KERNELS excluant .NET).
5. Security scan : 0 match (HF_TOKEN|API_KEY|BEARER|PASSWORD|SECRET|TOKEN\s*=). Zéro dépendance nouvelle, périmètre exactement les 2 fichiers annoncés, +633/−0 additif.

Note (non-bloquant) : la mesure tier-1 (739 notebooks, 1577 paires, 0 occurrences sur l'historique mergé) n'est pas reproductible depuis le diff — script de mesure non committé, proxy borné déclaré. Acceptable pour un ratchet dont le rôle est de garder main propre, mais le chiffre repose sur la déclaration seule. Le caveat d'index-pairing (insertion décale les indices) est honnêtement documenté dans la docstring et couvert par UNPAIRED + la porte body.

Le garde attrape bien le trou C.2 que les trois gardes existants laissaient passer par construction — review humaine PREFLIGHT cessera d'être le seul mode de détection une fois la tranche 2 branchée.

[github-actions]

G-VAR-2 light cap reached (advisory, non bloquant).
La lane myia-po-2023:CoursIA-2 a deja consomme son budget LIGHT du jour (#13027 (merge a 2026-08-30T02:26:36Z)).
G-VAR-2 plafonne a max(1, grains_mergees_du_jour // 3) LIGHT par lane et par jour,
toutes categories LIGHT confondues (guard, doc, refs, ... partagent un seul budget) :
c'est un RATIO, pas un plafond plat. La decision de merge reste au coordinateur.