etm-powersync-energy-plugin-etm/docs/DESIGN_10.md

DESIGN — §10 : éco / confort, et le délestage dans le même lot

Statut : conception, à valider avant tout code (AGENTS.md, workflow obligatoire). Entrée : specs/spec_loadmodel.md §10 (LM-1000 → LM-1009) et §12. Écrit après relecture de rulebasedscheduler.cpp (getPlan, buildSetpointAction, buildSgReadyStateAction), smartchargingmanager.cpp (verifyOverloadProtection), et des deux notes qui contraignent la forme : LM-1006-1 (le plafond de soutirage) et LM-1009 (les deux régimes d'échéance).

Ce document ne demande pas si le §10 doit se faire. Il dit sous quelle forme, et nomme les cinq points qui demandent une décision — §8. Trois d'entre eux ne sont pas techniques.

---

1. Pourquoi le délestage part AVEC, et pas après

C'est la précondition écrite en §13 de la spec, et elle tient pour une raison arithmétique simple : la passe éco n'est pas bornée par le surplus (LM-1005). Elle est bornée par une autorisation de soutirage. Or aujourd'hui, la seule borne de soutirage qui existe dans le moteur — phasePowerLimit — ne déleste que les bornes de recharge (verifyOverloadProtection, boucle sur m_evChargers).

Livrer les planchers éco sans le délestage général donnerait donc : un matin sans soleil, chaque charge se sert au réseau pour tenir son obligation, personne ne les additionne, et l'installation disjoncte. Ce n'est pas une dégradation de confort — c'est une coupure, chez un client.

Conséquence de conception, pas de calendrier : la passe éco a besoin d'un objet « plafond » qui n'existe pas encore. Le §10 doit donc le créer. C'est le §2.

---

2. Le plafond de soutirage devient un OBJET (LM-1006-1)

2.1 Ce qu'il remplace

Aujourd'hui, la limite de raccordement est consultée à deux endroits, sous deux formes, sans jamais être nommée :

• RootMeter::calculateAllowanceAmpere(phases, phasePowerLimit) — la place libre par phase, interrogée par le proxy puis, depuis 3g-2, par EnergyArbitrator::evPhaseAllowanceW() ;
• verifyOverloadProtection() — la réaction temps réel, qui déleste les bornes.

Aucun des deux ne se demande d'où vient le plafond, parce qu'il n'y en a qu'un. Le §14a en ajoutera un second, le §10 lui-même un troisième.

2.2 La forme proposée

/*! Un plafond de soutirage, et ce qui l'a produit. */
struct DrawCap {
    enum Source { Connection, GridOperator, EcoSelfImposed };

    Source  source      = Connection;
    double  totalW      = -1;   //!< Plafond au POINT DE LIVRAISON. < 0 = pas de plafond total.
    QList<double> perPhaseA;    //!< Plafond PAR PHASE. Vide = pas de plafond par phase.
    QDateTime until;            //!< Fin de validité ; invalide = permanent.
};

/*! Le plafond EFFECTIF du cycle, et celui qui a mordu. */
struct DrawBudget {
    QList<DrawCap> declared;    //!< Tous les plafonds actifs, quelle que soit leur source.
    double  effectiveW   = -1;  //!< Le plus contraignant, ramené en watts.
    DrawCap::Source binding = DrawCap::Connection;  //!< QUI a mordu — publié, pas déduit.
    bool    perPhaseBound = false;  //!< Vrai si c'est une phase qui borne, pas le total.
};

binding est le champ qui justifie tout l'objet. Sans lui, un client bridé lit « protection de surcharge » là où la cause est le gestionnaire de réseau — deux causes, deux gestes (LM-1006-1, propriété 1).

2.3 Le piège : par phase, ou au total ?

Les trois sources ne parlent pas la même langue, et c'est le seul vrai problème technique du §2.

Source	Forme naturelle	Peut-on la convertir ?
Disjoncteur de branchement	par phase (A)	pas en un total : 3 × 32 A ne vaut pas 22 kW répartissables
§14a EnWG	total (W au point de livraison)	pas en par-phase : le gestionnaire ne dit rien de la répartition
Plancher éco (§10)	total (W qu'on s'autorise)	idem

Un plafond total ne protège pas d'une surcharge monophasée : 4 kW tirés entièrement sur L1 passent un plafond total de 6 kW et font disjoncter un 16 A. Et un plafond par phase ne sait pas exprimer le §14a.

Décision de conception proposée : DrawBudget porte les deux, les évalue toutes les deux, et binding dit laquelle a mordu la première. Aucune conversion, jamais — c'est la conversion qui perdrait l'information. effectiveW n'est qu'une commodité d'affichage, dérivée, et perPhaseBound dit s'il faut la lire avec précaution.

2.4 Où il se calcule

Une fois par cycle, dans buildContext(), à côté de ctx.meter et ctx.battery — c'est déjà l'endroit qui lit le compteur et connaît phasePowerLimit. Il devient un champ de SurplusContext :

struct SurplusContext {
    // … existant …
    DrawBudget drawCap;   //!< [§10] Plafond de soutirage du cycle, toutes sources confondues.
};

Publié en télémétrie au même titre que budget — c'est la contrepartie de binding : un client qui ne voit pas le plafond ne peut pas expliquer ce qu'il affiche.

---

3. Les deux passes, et ce qui borne chacune

LM-1002 fixe la structure : deux passes sur la même liste, triée une seule fois par rang. Ce qui change entre elles n'est pas l'ordre, c'est la borne.

                    ┌────────────── passe 1 : ÉCO ──────────────┐
liste triée par     │ borne : DrawBudget (autorisation de       │
rang (une seule)    │         SOUTIRAGE — pas le surplus)       │
   rang 1 ─────────▶│ sert : le plancher `needs` non atteint    │
   rang 2 ─────────▶│ produit : une CIBLE, pas une commande     │
   rang 3 ─────────▶└───────────────────────────────────────────┘
        │
        │           ┌──────────── passe 2 : CONFORT ────────────┐
        └──────────▶│ borne : le RELIQUAT de surplus            │
   (même ordre)     │ sert : la cible de confort si demandeuse  │
                    │ produit : une CIBLE, pas une commande     │
                    └───────────────────────────────────────────┘
                                        │
                            somme par charge, arrondie UNE fois
                                        │
                                   UNE commande

Ce que la passe 1 dépense n'est pas ce que la passe 2 dépense. C'est le point que le code actuel ne sait pas exprimer : getPlan() n'a qu'un compteur, remainingSurplusW, et buildSetpointAction() le décrémente et émet l'action dans le même geste (rulebasedscheduler.cpp:207-212). Le §10 doit séparer les deux — voir §4.

Deux comptabilités, donc, et elles ne se mélangent pas :

struct PlanBudget {          // existant, inchangé dans sa sémantique
    double surplusW, evReservedW, allocatedW, recreditedW, remainingW;
};
struct PlanDraw {            // [§10] ce que la passe 1 a décidé d'ACHETER
    double authorisedW = 0;  //!< Ce que le DrawBudget laissait prendre.
    double committedW  = 0;  //!< Ce que la passe 1 a réellement engagé au réseau.
    double remainingW  = 0;  //!< Reliquat d'autorisation, non dépensé.
};

Pourquoi deux structures et pas un champ de plus : PlanBudget répond « d'où vient l'énergie servie » ; PlanDraw répond « combien a-t-on décidé d'acheter ». Les fondre rendrait l'invariant publié de PlanBudget (surplus + recrédit − alloué == restant) faux ou incompréhensible, et c'est lui qui rend la charge utile vérifiable par un client.

---

4. Une seule commande par charge et par cycle (LM-1003)

C'est la contrainte qui impose la refonte structurelle, et elle est petite à énoncer : les passes calculent, elles ne commandent pas.

Découpage proposé de getPlan() :

// 1. contexte, budget de surplus, plafond de soutirage  (inchangé + DrawBudget)
// 2. tri UNE fois                                        (inchangé)
QHash<QString, LoadTarget> cibles;   // loadId → { ecoW, confortW, motifs… }

// 3. passe 1 — éco, bornée par ctx.drawCap
for (const LoadContext &lc : chargesTriees)
    cibles[lc.id].eco = planifierEco(lc, drawRestant, planDraw);

// 4. passe 2 — confort, bornée par le reliquat de surplus
for (const LoadContext &lc : chargesTriees)
    cibles[lc.id].confort = planifierConfort(lc, surplusRestant, planBudget);

// 5. UNE émission par charge : somme, arrondi au mécanisme, motif
for (const LoadContext &lc : chargesTriees)
    slot.actions.append(emettre(lc, cibles.value(lc.id)));

L'arrondi au mécanisme se fait à l'étape 5, une seule fois. C'est ce qui empêche le défaut que LM-1003 nomme : un relais commuté en passe 1 puis recommuté en passe 2, soit du court-cycling fabriqué par l'arbitre lui-même.

Le recrédit s'attribue à la première passe où la charge apparaît (LM-1004) — donc dans planifierEco() si elle a un plancher, dans planifierConfort() sinon. Un champ recreditAttribue dans LoadTarget le rend vérifiable plutôt que discipliné.

Ce que cette refonte casse, et qu'il faut prévoir : buildSetpointAction() et buildSgReadyStateAction() mélangent aujourd'hui décision, écrêtage de verrou, comptabilité et motif. Ils doivent se scinder en « décider une cible » et « émettre ». C'est le gros du travail du lot, et c'est du remaniement, pas de l'ajout. Les tests de motif existants (testDecisionReasonRendering, testEcsBudgetUnderLock, testEcsSurplusPV) sont le filet : ils portent sur le TEXTE publié, donc ils survivront au remaniement ou le condamneront.

---

5. Le délestage : ce qu'il coupe, et dans quel ordre

Le plafond borne le PLAN, il ne le corrige pas après coup. C'est la leçon de 3g-2 : un plafond appliqué après l'allocation laisse le waterfall croire qu'il a servi.

• En passe 1, chaque charge servie décrémente planDraw.remainingW. Quand l'autorisation est épuisée, les charges suivantes reçoivent 0 et le motif nomme la source (§6).
• L'ordre de délestage est l'inverse de l'ordre de service : le rang décide qui est servi en premier, donc qui est coupé en dernier. Aucun second classement — c'est LM-1002 appliqué à l'envers, et c'est la seule lecture qui ne surprendra pas l'installateur.
• L4 ne bouge pas. verifyOverloadProtection() garde le dernier mot en temps réel, sur la mesure, après le dispatch. Le §10 lui ajoute des charges à délester ; il ne lui retire pas son rôle et ne s'y substitue pas. Sa position dans update() reste INTOUCHABLE (AGENTS, modèle de sécurité).

---

6. Les motifs — ce que le §10 ajoute au catalogue

Le catalogue est fermé et testé sur le texte ; toute clé ajoutée demande une ligne de rendu et une entrée de clôture (testDecisionReasonRendering).

Code	params	Quand
DRAW_CAP	capW, source, requiredW, o:phase	Le plafond de soutirage refuse, et source dit lequel : raccordement, gestionnaire de réseau, ou auto-imposé. phase présent si c'est une phase qui borne.
ECO_FLOOR_GRID	deliveredWh, targetWh, gridW	Une obligation éco servie au réseau. gridW chiffre l'achat, comme EV_GRID_START le fait déjà.
ECO_FLOOR_MET	deliveredWh, targetWh	L'obligation est atteinte — et elle ne peut se dire atteinte que sur le régime ÉNERGIE (LM-1009).
COMFORT_SKIPPED	o:sensorValue, o:setpoint	La charge n'est plus demandeuse de son bonus (comparateur de LM-1008). Distinct de « pas de budget ».

Et un champ, pas un code : le régime de l'avancement (mesuré / estimé / non mesurable), publié sur chaque charge portant une obligation. C'est la condition C2 de LM-1009, et elle ne peut pas vivre dans un code : les trois régimes coexistent dans le même cycle, sur des charges différentes.

---

7. Ce que LM-1009 impose à l'obligation éco

Trois décisions déjà prises, rappelées ici parce qu'elles ferment des choix de conception :

• D1 — l'avancement se mesure et s'affiche en énergie livrée. La passe 1 compare donc des Wh à des Wh, jamais un pourcentage.
• D2 — obligation par SESSION d'abord. Pour une borne, la session est le branchement, et la source est sessionEnergy. Pour une charge thermique, la « session » est le cycle quotidien — et c'est là que l'analogie s'arrête : minEnergyWhPerDay reste hors de ce lot, faute d'accumulation inter-sessions (§11).
• C1 — une charge dont l'énergie livrée n'est pas mesurable dégrade visiblement. Le cas est réel dès demain : la V2C Trydan ne publie pas sessionEnergy (docs/PREPA_BANC_20260828.md §2.2). Le §10 doit donc prévoir ce régime dès l'écriture, pas comme un cas dégradé ajouté après.

Conséquence directe : une obligation éco sur une charge non mesurable est déclarative, pas vérifiable. Elle peut être servie ; elle ne peut jamais être annoncée tenue. C'est la même frontière que LM-1009 trace pour l'échéance VE.

---

8. LES CINQ POINTS À TRANCHER

8.1 — La réserve batterie annule-t-elle aussi la passe ÉCO ? (le plus important)

LM-1203-b dit : sous la réserve, le budget est annulé. Mais ce budget est un budget de surplus, et la passe 1 ne dépense pas de surplus — elle dépense une autorisation de soutirage.

• Si la réserve annule aussi la passe 1 : une installation dont la batterie est basse n'atteindra jamais son plancher éco. Un ballon qui n'a pas vu 50 °C ne les verra pas, parce que la batterie de la maison est à 15 %.
• Si elle ne l'annule pas : la maison achète au réseau pour un chauffe-eau pendant que sa batterie est basse — ce qui peut être exactement ce qu'on veut (l'obligation prime) ou une absurdité (on achète pendant qu'on manque).

Ma recommandation : la réserve N'annule PAS la passe 1. La réserve protège le surplus ; une obligation d'énergie sur échéance est d'une autre nature, et si elle cède à la réserve, elle cesse d'être une obligation. Mais c'est une décision d'exploitation, pas de code.

8.2 — Le plafond §14a est-il par phase, au total, ou les deux ? Le §2.3 propose de porter les deux sans jamais convertir. Reste à confirmer que c'est bien ainsi que le gestionnaire de réseau l'exprimera — et le transport du §14a n'existe pas encore, donc la réponse peut attendre à condition que la forme ne se ferme pas maintenant.

8.3 — Le repli L2 doit-il TENIR le plafond ? LM-1006-1, propriété 2 : le plafond survit à la panne du HEMS, et ce sera une obligation légale pour le §14a. Or le repli L2 actuel est conçu pour ne rien initier (SAFETY.md §L2), pas pour continuer à faire respecter une borne imposée par un tiers. Les deux ne sont pas la même chose. Ma recommandation : en mode dégradé, le plan cesse, mais une allocation statique respectant le dernier plafond connu est maintenue. C'est un changement de nature du repli, et il mérite d'être décidé, pas déduit.

8.4 — La cible de confort : comparateur seul, ou dosage ? LM-1008 tranche déjà : comparateur (sonde < consigne → demandeuse), le dosage attend le modèle thermique du §11. À confirmer que ça reste vrai pour ce lot, parce que c'est ce qui le rend faisable sans historique.

8.5 — Que fait l'app des deux passes ? LM-1006, couplage 2 : un plancher éco de rang 4 passe devant un confort de rang 1, et c'est contre-intuitif pour l'installateur qui vient de poser son ordre. Sans écran qui montre les deux passes, le premier retour terrain sera « l'ordre n'est pas respecté ». Ce n'est pas du travail moteur, mais c'est une condition de livraison du lot.

---

9. Ce qui n'est PAS dans ce lot

• minEnergyWhPerDay — obligation quotidienne, exige l'accumulation inter-sessions (§11). Le lot livre l'obligation par session.
• Le transport du §14a — aucun canal n'existe. Le lot livre la forme du plafond, pas sa source externe.
• Le prix, l'heure, le signal tarifaire (LM-1005) — le rule-based franchit la frontière de l'achat grossièrement : « plancher non atteint à 22 h → chauffer ». Une règle d'horloge. L'optimisation appartient au MILP, donc à l'optimiseur socket, donc à 3d.
• Le dosage en Wh du confort — voir 8.4.
• La conversion degrés → Wh — couche domaine, jamais l'arbitre (LM-1008).

---

10. Ordre de travail proposé

Étape	Contenu	Éprouvable
10-a	DrawCap / DrawBudget, calculés dans buildContext(), publiés, sans effet sur les décisions	oui — télémétrie, aucun changement de comportement
10-b	Délestage : le plafond borne le plan ; motif DRAW_CAP avec sa source ; l'ordre de coupe est l'inverse du rang	oui — simulation + banc
10-c	Refonte décider/émettre (§4) : deux passes, une commande, recrédit unique — à comportement CONSTANT, passe 1 vide	oui — les 16 scénarios run doivent rester identiques au bit près
10-d	Passe 1 réellement servie : obligation par session, régimes de LM-1009, motifs éco	oui — banc
10-e	Passe 2 confort : comparateur de sonde	oui — banc, avec la sonde du §11

10-a et 10-c sont les deux étapes qui ne changent rien, et ce sont les plus importantes : elles rendent le reste petit. 10-c en particulier doit être prouvée par l'invariance des scénarios enregistrés — si la refonte décider/émettre change un seul point de contrôle, c'est qu'elle a changé une décision, et il faut savoir laquelle avant d'aller plus loin.