Mode Diátaxis : référence. Faits exacts à consulter — la table d'invariants, l'état du câblage des upgrades, la commande d'audit. Le pourquoi (doctrine du résidu de facteur d'émission) est dans Stratégie du résidu FE — (b)+(c).
La contrainte directrice du pipeline GES est le déterminisme : un re-run redonne le même total carbone au centime près. Trois invariants tiennent de bout en bout, y compris quand un LLM intervient sur le 4ᵉ niveau de résolution des facteurs d'émission (FE).
| Id | Invariant |
|---|---|
| I1 | La chaîne FE déterministe (client → bibliothèque nationale → IPCC Tier 1) est intouchée. Le consensus / la récupération agentique n'agit que sur le 4ᵉ niveau (escalade LLM), déjà non déterministe. |
| I2 | Tout appel LLM est figé puis rejoué. Le résidu (consensus C1 + juge C3 + récupérateur D′) écrit ses échantillons bruts dans le calc-dir ; un re-run les rejoue depuis le cache, sans réseau. Reproductible bit-à-bit une fois le cache constitué. |
| I3 | Le LLM ne produit jamais un chiffre carbone « de niveau déterministe ». Une confidence de consensus vaut llm-consensus(N=…), jamais tier1 / client. Le juge C3 ne classe que des objets subjectifs, jamais un FE. Une proposition de résidu n'entre dans aucun total tant que verified_by_human n'est pas posé. |
Statut des upgrades issus des deux notes d'architecture
(rapports/transposition-robin-bfev/, transposition-coscientist-bfev/) une
fois branchés dans le pipeline du skill data-processing. Plan d'implémentation :
rapports/plan-upgrades-skill-pipeline-2026-05-31.md.
| Phase | Upgrade | Module | Effet |
|---|---|---|---|
| A | Filet de non-régression « golden » | tests/golden_skill_calc.py (dépôt) |
Rejoue un calc-dir 100 % déterministe et diffe aggregates.json à tolérance 0. Garde-fou de toute phase ultérieure. |
| B1 | Émetteur meta.yaml |
bfev.meta.write_meta_yaml |
calculate écrit period_months / tdr_period_months / gwp_vintage (AR6 par défaut) — les racines de l'arbre d'hypothèses que lisent les contrôles V1. |
| B2/B3 | Adaptateur d'audit (V1/V2/V3 + contrôle C2) | bfev.skill_audit.audit_calc_dir |
Adapte le calc-dir plat du skill à bfev.audit.run, écrit consistency-audit.json + run_state.json. Active les contrôles période / annualisation / millésime GWP, le registre d'erreurs récurrentes, la décision d'état terminal. |
| C | Classement des leviers (BTL) | bfev.lever_ranking.rank_levers |
Tournoi BTL par paires avec cache de juge rejouable (ranking_cache.json) ; refuse les objets en forme de FE (I3). Pour les leviers de décarbonation / questions EGCC — jamais un FE. |
| D | Consensus FE (cache/replay) | bfev.fe_consensus.CachedConsensusResolver |
Résolution déterministe d'abord (I1) ; consensus seulement sur EFResolutionError, mis en cache dans consensus_cache.json (I2), confidence jamais promue (I3). consensus_factor_row adapte le résultat au schéma FE du skill. |
| D′ | Escalade FE sourcée (récupération + garde humaine) | bfev.fe_escalation, bfev.agentic_retriever, bfev.validation_sheet |
Récupère un FE résiduel auprès d'un domaine autoritatif (ADEME/DEFRA/IPCC/EXIOBASE), vérifie valeur+unité dans l'unité native citée, convertit de façon déterministe hors LLM, archive la citation, gate la proposition (hors total jusqu'à validation expert). Voir la doctrine. |
| E1 | Manifeste de citations (C2) | bfev.manifest.build via bfev.skill_audit.emit_manifest |
allowed_citations.json liste les sources FE / GWP + acteurs réellement résolus. report ne peut citer que celles-ci — anti-hallucination par construction, pas a posteriori. |
calculate.py. Le mécanisme (fe_consensus) est complet
et testé, mais le hook d'une ligne sur la branche « aucun FE trouvé » est
différé : il est inerte sans sampler LLM, et l'adaptateur Completion de
claude-agent-sdk derrière bfev.sampler n'est pas connecté dans le skill.
Le brancher maintenant ajouterait du code mort et invérifiable dans le template
FE critique. Prérequis : connecter l'adaptateur sampler (SDK + auth)._gwp_vintage_check reste vacant tant que calculate n'enregistre pas un
gwp_source par ligne ; aujourd'hui il n'interdit qu'une chaîne AR5 explicite.PYTHONPATH=bfev/src python -m bfev.skill_audit <calc_dir>
# émet allowed_citations.json (si absent), consistency-audit.json, run_state.json
bfev est importé via PYTHONPATH=bfev/src — pip est absent des venvs du
projet, donc pas de pip install -e. L'audit est en lecture seule sur les
artefacts calculés du calc-dir ; il ne recalcule jamais un chiffre.
Les caches de replay (consensus_cache.json, ranking_cache.json) sont
octet-stables (sort_keys). Un re-run frozen=True interdit tout cache miss :
une re-livraison ne fait zéro appel réseau et reproduit les totaux à
l'identique. C'est ce qui autorise un LLM à toucher le pipeline sans compromettre
l'auditabilité.