etm-powersync-energy-plugin-etm/specs/spec_loadmodel.md

SPEC — Modèle de charges (domaine × mécanisme)

Version : 0.1.3 Dépôt : etm-powersync-energy-plugin-etm Statut : intention de conception figée. §3 (schéma persisté) est en cours d'implémentation depuis le 2026-08-09 : relay-router, etmvariableload et sg-ready sont trois charges utiles discriminées par adapter. Le reste du document reste une intention.

0.1.3 — LM-200 ajouté (§2) : toutes les cases de la matrice ne se valent pas. Certaines sont non prévues, d'autres sont interdites par la physique — le cas de la PAC, qui ne se pilote qu'en SgReady ou en communicant. Précise LM-101, qui était trop permissif lu seul. Aucune décision de conception renversée ; une contrainte qui existait dans le matériel et pas dans le document.

0.1.2 — LM-104 ajouté (§1) : « supposer conservateur pour annoncer, tenter systématiquement pour agir ». Principe dégagé des tests d'ECS-411 et ECS-414, inscrit ici parce qu'il vaut pour tout mécanisme et non pour l'ECS seul. §3 : le mécanisme sg-ready a sa charge utile et cesse d'être une intention.

0.1.1 — passe de vérification contre le code. Quatre précisions : préséance des verrous (LM-303), portée de l'union discriminée (LM-302), citation de règle (LM-102), EvAdapter inscrit au renommage (LM-601). Aucune décision de conception modifiée.

Ce document ne déclenche aucun travail. L'ordre de specs/spec_ecs.md §2 reste seul en vigueur, et l'étape 1 reste bloquée par ses arbitrages §13-1 et §13-2. Une seule chose ici est urgente : la forme du schéma persisté (§3), parce que c'est la seule partie coûteuse à rattraper une fois que le banc et la beta auront écrit des données. Le reste s'implémente au fil des besoins.

---

§1 — Deux couches

LM-100 — Le modèle de charges se découpe en deux couches indépendantes :

• Couche domaine — Ecs, Hvac, Ev, SmartHome. Détient le modèle de la charge (état thermique, échéance de départ, cycle), en déduit la demande et available. Ne parle à aucun matériel.
• Couche mécanisme — Relay, Variable, SgReady, ModbusSetpoint. Traduit une enveloppe en watts vers le matériel et tient les verrous. Écrite une seule fois, partagée par tous les domaines.

LM-101 — Une charge configurée choisit un domaine et un mécanisme. Le domaine ne détermine pas le mécanisme et réciproquement — mais il en exclut certains, cf. LM-200. L'indépendance des deux couches porte sur le couplage de conception, pas sur la liberté de combiner : elle dit qu'aucune des deux n'a besoin de connaître l'autre pour être écrite, jamais que toute paire est réalisable.

LM-102 — Aucune des deux couches ne répartit de budget. La couche domaine se retire de l'allocation via available ; elle ne la négocie pas. Règles absolues 1 et 2 d'AGENTS.md inchangées.

LM-104 — Supposer conservateur pour annoncer, tenter systématiquement pour agir. Un adaptateur qui ne peut pas LIRE l'état d'un organe DOIT le supposer dans l'état le plus consommateur (contact fermé, palier engagé) quand il annonce — dans telemetry(), toLoadContext() ou la déduction de son état courant au démarrage. Le même adaptateur DOIT néanmoins émettre l'écriture vers cet organe quand il agit, sans jamais la court-circuiter au motif que l'état supposé coïncide déjà avec la cible.

Les deux moitiés sont indissociables, et c'est l'omission de la seconde qui est piégeuse : supposer « fermé » puis en déduire « donc rien à écrire » transforme une hypothèse de prudence en masquage de panne — l'organe reste dans son état réel, inconnu, et aucun verdict d'échec ne se déclenche. La prudence porte sur ce qu'on DIT de l'installation, jamais sur ce qu'on lui ENVOIE.

Portée : tout mécanisme, présent et futur. Relay (déduction de palier au démarrage), SgReady (relevé du motif de contacts réellement fermés), et par construction ModbusSetpoint dès qu'un registre devient illisible. Origine : deux défauts symétriques trouvés par les tests d'ECS-411 puis d'ECS-414 — d'abord l'hypothèse inverse (« injoignable donc ouvert »), puis son corollaire (« supposé fermé donc jamais écrit »).

Justification. Un nommage par domaine seul (EcsAdapter, HvacAdapter) obligerait à écrire l'encodage SG-Ready deux fois (ECS et HVAC), la combinatoire de relais deux fois (ECS et EV en prise commandée), et le transport Modbus deux fois (HVAC et EV). Un nommage par mécanisme seul perdrait les comportements propres au domaine, qui sont réels : stockage différable pour l'ECS, confort immédiat pour le HVAC, échéance de départ pour l'EV, cycle non modulable pour le SmartHome.

---

§2 — Matrice

Domaine	Mécanismes attendus
Ecs	Relay (résistance à paliers) · SgReady (ballon thermodynamique) · Variable (triac)
Hvac	SgReady (PAC) · ModbusSetpoint (PAC, clim, VMC)
Ev	Relay (prise commandée : GreenUp, Witty) · ModbusSetpoint (borne)
SmartHome	Relay — voir §7, sémantique différente

LM-200 — Une case vide se lit de deux façons, et il faut les distinguer. La plupart sont non prévues : rien ne les interdit, elles n'ont simplement pas d'usage identifié. D'autres sont impossibles, parce que le mécanisme ne sait pas commander cet organe-là. Les confondre revient à traiter une contrainte physique comme une lacune de feuille de route.

Le cas dur, et le seul identifié à ce jour : la PAC. Une pompe à chaleur se pilote de deux façons, et de deux seulement :

Voie	Mécanisme	Ce qui circule
SG-Ready	SgReady	deux contacts secs vers l'entrée de signalisation — 4 états normés
Communicante	mécanisme communicant, via un plugin nymea	mode, consignes, limite de puissance — le modèle propre de la machine

Ni Relay, ni Variable. Ce ne sont pas des cases à remplir plus tard :

• Relay couperait l'ALIMENTATION du compresseur. Un RelayRouter étage de la puissance réelle ; appliqué à une PAC, il lui retire son autorité sur son propre cycle — dégivrage, retour d'huile, temporisation de redémarrage — et transforme chaque décision d'arbitrage en court-cycling. Le verrou minOn/minOff limite la casse, il ne rend pas le geste légitime.
• Variable suppose un cadran en watts. Un triac module une résistance ; un compresseur n'est pas gradable. Une PAC communicante peut certes accepter une limite de puissance, mais elle l'interprète selon son propre modèle et ne s'engage sur aucune valeur instantanée — ce n'est pas la sémantique d'enveloppe que Variable promet à l'optimiseur, et cette promesse alimente le budget.

⚠️ Le piège de lecture : « ma PAC est pilotée par deux relais, donc Relay ». Non. Les contacts SG-Ready sont des relais, et au banc .75 ce sont bien deux things power (K1/K2). Mais ils signalent, ils ne portent pas la charge. C'est exactement ce qui sépare les deux mécanismes : Relay commute de la puissance, SgReady commute du sens. Voir des relais dans une configuration ne dit donc rien du mécanisme qui convient.

Ce que ça implique pour le mécanisme communicant, qui n'existe pas encore. Il est appelé ModbusSetpoint dans ce document : le nom est trop étroit. Ce qui le définit n'est pas Modbus — c'est qu'un thing nymea porte le modèle de la machine et que le moteur lui parle dans ce modèle-là. Le transport (Modbus RTU/TCP, IP propriétaire, passerelle cloud) est une affaire de plugin d'intégration, invisible d'ici. À renommer quand il sera implémenté ; à ne pas confondre avec Variable d'ici là, malgré la ressemblance de surface d'une « consigne » à écrire.

Rien n'empêche aujourd'hui d'exprimer une case interdite. domain est une métadonnée d'intention, optionnelle, que l'arbitre ne lit pas : une charge domain: "hvac" + adapter: "relay-router" est acceptée par isValid(), et l'omission du domaine contournerait de toute façon tout contrôle qui s'y appuierait. Faire du domaine un discriminant de validation est une décision de contrat, pas un correctif — elle est portée en §8.

---

§3 — Schéma de configuration (à figer)

LM-300 — LoadConfig est une union discriminée par le mécanisme :

LoadConfig {
    id, nom, enabled
    domaine        : Ecs | Hvac | Ev | SmartHome
    typeAppareil   : affine le domaine (résistif | thermodynamique | …)
    groupe, prioritéGroupe, prioritéMembre
    mécanisme      : Relay | Variable | SgReady | ModbusSetpoint   ← discriminant
    chargeUtile    : LoadConfigRelay | LoadConfigVariable | …
    verrous        : minOnS, minOffS
    facettes[]     : voir §4
}

État d'implémentation (2026-08-09). Trois charges utiles existent, discriminées par le champ adapter du schéma persisté — relay-router, etmvariableload, sg-ready. Le domaine, le groupe et les facettes ne sont pas encore portés : ce qui est figé, c'est la forme, celle qui coûte cher à rattraper.

adapter = "sg-ready"  →  sgReady {
    states[] { state : 1..4, relays[] : thingId, estimatedPowerW }
    minStateHoldS
}

estimatedPowerW porte volontairement ce nom : c'est une estimation, jamais un engagement — une PAC ne consomme pas la même chose à −5 °C et à +12 °C. Le champ sert à ordonner et à budgéter, la mesure reste la source de vérité (ECS-500). L'état 2 est obligatoire : c'est le plancher de repli du mode dégradé L2 et de la désactivation (ECS-413/414). Une configuration qui ne peut pas l'exprimer est refusée, pas construite.

LM-301 — Ajouter un mécanisme DOIT se limiter à un type de charge utile et une branche de fabrique. Rien d'autre ne bouge. Vérifié à l'usage : l'ajout de sg-ready a touché exactement une charge utile, une branche de isValid(), une branche de fabrique dans rebuildLoadAdapters(), et un champ optionnel au schéma RPC. Aucun code d'arbitrage n'a bougé.

LM-301-b — La limite de LM-301, trouvée au lot B-bis (2026-08-25). « Une charge utile, une branche de fabrique » vaut pour construire un mécanisme, pas pour l'alimenter en actions. Quand sg-ready a rejoint la table commune des charges arbitrées, un code d'arbitrage a bel et bien dû bouger : le repli du mode dégradé L2 fabriquait un Setpoint(0) pour toute la table, en présumant du kind. Une PAC de configuration recevait donc une action que SgReadyAdapter rejette d'entrée — et rien d'autre : elle restait en état 4 (forcé) sous compteur muet, quand SAFETY.md §L2 exige l'état 2. Le défaut ne se voyait pas dans la télémétrie, où le motif DEGRADED_L2 s'affichait correctement ; seule l'écriture manquait.

Règle qui en sort : tout code qui fabrique une action pour une charge quelconque DOIT lire descriptor().supportedKinds et se refuser explicitement s'il n'y trouve rien de connu — jamais présumer du kind à partir de la table où la charge se trouve. C'est le pendant, côté actions, de ce que LM-302-b dit côté validation : ce qui est vrai « pour toutes les charges » n'appartient à aucune charge utile.

LM-302-b — Ce qu'une charge utile ne peut pas valider. L'exclusivité d'un Thing est une propriété de l'ensemble des charges, pas d'une charge : aucune charge utile ne peut la vérifier, quelle que soit sa rigueur. Elle vit donc au niveau du store (validateSet()), et tout mécanisme futur DOIT déclarer les Things qu'il revendique via LoadConfig::claimedThingIds() — c'est le seul point à étendre, et l'oublier rend le mécanisme invisible à la vérification. Voir ECS-110-b.

LM-302 — Charges utiles auto-validantes, et portée de l'« inexprimable ». Chaque charge utile valide la sienne. Les états invalides doivent être inexprimables dans les types C++ et le schéma persisté ; à la frontière JSON-RPC, la validation est à l'exécution, par contrainte nymea.

Corollaire vérifié à l'usage (2026-08-09). GetLoadConfig sérialise via le méta-objet, donc toutes les propriétés déclarées apparaissent dans la sortie — y compris la charge utile vide d'un autre mécanisme. Un schéma qui exige une clé interne dès que la charge utile est présente rend donc impossible l'aller-retour lire-puis-réécrire, c'est-à-dire le geste ordinaire de l'application, et le rejet survient avant le handler.

Règle. Toutes les clés internes d'une charge utile optionnelle DOIVENT être déclarées optionnelles (o:) au schéma RPC. L'exigence réelle vit dans isValid(), jamais dans le schéma. Les clés internes d'une charge utile optionnelle contraignent les charges des autres mécanismes — c'est le côté par lequel le mur se touche.

Obligation permanente. Tout mécanisme ajouté DOIT être accompagné d'un test d'aller-retour GetLoadConfig → SetLoadConfig inchangé, vérifié échouant sans le correctif. Sans cette obligation, le prochain mécanisme rejouera la scène.

LM-303 — Verrous. typeAppareil fournit des défauts (résistif ≈ 60 s, thermodynamique ≈ 300 s), l'installateur peut les modifier, et c'est la valeur stockée qui fait foi. Jamais de temporisation codée en dur.

Préséance. Les verrous déclarés au niveau de la charge s'appliquent par défaut. Une charge utile PEUT en porter de plus fins — par relais, par registre — et ceux-là priment sur le défaut de charge, pour le seul actionneur qu'ils désignent.

Cette règle laisse spec_ecs.md §13-3 (ECS-307, grain des temporisations par relais) entièrement ouvert : ajouter plus tard un champ optionnel dans une charge utile est rétro-compatible, quelle que soit la réponse. Le schéma persisté n'a donc pas à être « rendu tolérant » — c'est la préséance qui devait être écrite, et elle l'est ici.

---

§4 — Facettes : une machine, plusieurs fonctions

LM-400 — Une machine physique est une seule charge : un rang, un jeu de verrous, une ligne de budget. Une PAC assurant chauffage et ECS n'est jamais déclarée deux fois.

Justification. Deux déclarations produiraient une double allocation du surplus pour une seule consommation, deux rangs pour un seul comportement, et deux jeux de verrous sur un seul compresseur — la protection anti court-cycling tomberait précisément là où elle coûte le plus cher.

LM-401 — Une charge PEUT porter plusieurs facettes au-dessus d'un actionnement unique. Une PAC mixte porte une facette ECS (consigne, température ballon) et une facette chauffage, avec un seul mécanisme.

LM-402 — Les facettes servent à la lecture, au suivi et au calcul d'available. Elles ne portent pas de rang. Une charge à deux facettes ne peut pas être classée « après les chauffe-eau mais avant la clim » : si cette granularité est nécessaire, il faut deux machines, pas deux entrées.

LM-403 — Le mode est une sortie, pas une entrée. SG-Ready applique un niveau d'encouragement à la machine entière ; le choix de la fonction appartient au régulateur interne. Le HEMS observe le mode courant, il ne le sélectionne pas. Aucune conception ne DOIT supposer un aiguillage.

Ce que le mode apporte : available devient honnête. Machine en mode chauffage → la facette ECS n'absorbera rien quoi qu'on encourage → le waterfall passe au suivant au lieu de le deviner.

LM-404 — Biais par consigne : option avancée, hors périmètre pour l'instant. Monter hotWaterSetpointTemperature place le ballon sous consigne et la machine bascule d'elle-même. C'est indirect, lent, et surtout persistant : une consigne écrite le reste après un plantage ou un redémarrage, et elle écrase un réglage d'installateur. Toute implémentation future DOIT comporter des bornes dures, une politique de restauration et un chien de garde. À ne rouvrir que si le terrain le justifie.

LM-405 — Décomposition côté ems, pas côté plugin. Le découpage en facettes DOIT se faire dans l'ems au-dessus des états plats du thing, et non en forkant les plugins constructeurs. Chaque constructeur expose une structure différente ; l'abstraction doit vivre là où elle est indépendante du constructeur, sous peine de la refaire N fois et de gérer deux formes du même concept.

LM-406 — Si l'installation n'a pas de chauffe-eau distinct, il n'y a pas de charge ECS : la facette ECS s'accroche à la charge PAC.

---

§5 — Groupes et double rang

LM-500 — Un groupe est une clé de tri, jamais un détenteur de budget. Le waterfall trie sur le couple (prioritéGroupe, prioritéMembre) et reste inchangé. Un groupe qui reçoit une allocation puis la redistribue est un second décideur (règle absolue 1).

LM-501 — Classer un ECS, une PAC et une clim les uns par rapport aux autres fonctionne déjà avec la liste plate triée par priority. Les groupes ne sont nécessaires qu'à l'échelle : plusieurs chauffe-eau, plusieurs bornes, plusieurs zones, quand on veut déplacer une famille entière sans renuméroter.

LM-502 — Plafond de groupe : optionnel. Justifié quand les membres partagent une limite électrique réelle (bornes sur un même câble ou un même abonnement). Sans objet pour un groupe thermique, dont les membres sont sur des circuits distincts. C'est le seul point où la boucle du waterfall change vraiment : elle doit suivre l'engagement cumulé du groupe.

LM-503 — Deux notions à ne pas confondre avec un rang :

• Exclusion mutuelle (clim et PAC en opposition dans une même zone) : une contrainte entre appareils.
• Équité interne (trois chauffe-eau à rang égal, dont le troisième resterait froid tout l'été) : une politique de rotation dans le tri.

LM-504 — « HVAC » couvre chauffage, ventilation et climatisation ; y ranger l'eau chaude sanitaire est un abus. Libellé recommandé côté installateur : « Thermique » ou « Chauffage & eau chaude ».

---

§6 — Nommage

LM-600 — Les classes d'actionnement portent le nom du mécanisme, jamais du domaine.

LM-601 — Un renommage de cohérence est souhaitable. Trois classes sont concernées, avec des échéances distinctes :

Classe	Défaut	Débloqué après
RelayRouter	Ne suit pas la convention *Adapter de ses voisins	étape 3 de spec_ecs.md
EtmVariableLoadAdapter	Préfixe Etm redondant dans un dépôt ETM	étape 3 de spec_ecs.md
EvAdapter	Nommé d'après un domaine (§2 range Ev en domaine)	3g

EvAdapter n'est pas une classe de domaine égarée dans la couche mécanisme : c'est un adaptateur de mécanisme mal nommé. Il parle à l'interface evcharger de nymea — un mécanisme au même titre que SgReady. Le correctif est un renom, pas un redécoupage.

Aucun de ces renommages ne se fait avant son échéance. Pour RelayRouter, renommer juste avant la restructuration de m_relayMapping double le bruit dans l'historique ; pour EvAdapter, le câblage lui-même change en 3g (l'adaptateur n'est aujourd'hui pas dispatché), et renommer une classe dont le branchement va bouger produit le même bruit pour rien.

BatteryAdapter n'entre pas dans ce tableau : LM-700 le traite hors moule.

---

§7 — Cas hors moule

LM-700 — Batterie. Une batterie n'est pas une charge avec un rang : elle est aussi une source, capable de financer les autres charges (grid-funding, 3f). Elle intervient à un autre moment de la cascade et ne se modélise pas comme un consommateur classé. Onduleur hybride et AC-coupling sont bien deux mécanismes.

LM-701 — SmartHome. Un cycle de lave-vaisselle ne se descend pas à 0 W en cours de route : c'est un engagement pris au démarrage, pas un verrou minOn. La sémantique d'action n'est pas une enveloppe en watts mais un décalage temporel — démarrer maintenant ou plus tard. À traiter comme un type d'action distinct, pas comme une variante.

---

§8 — Points ouverts

1. typeAppareil — quelle énumération exacte, et jusqu'où elle affine le domaine.

2. Représentation persistée des facettes (§4) : imbriquées dans la charge, ou table séparée référençant la charge.

3. Sémantique d'action du SmartHome (LM-701) : à spécifier avant toute implémentation, elle ne se déduit pas du reste.

4. Rotation d'équité (LM-503) : politique à définir si le besoin se confirme.

5. Le domaine doit-il devenir un discriminant de validation (LM-200) ? Aujourd'hui domain est une métadonnée optionnelle que l'arbitre ne lit pas ; rien ne refuse domain: "hvac" + adapter: "relay-router". Trois façons de traiter la case interdite, par coût croissant :

   • la documenter seulement — l'app guide le choix, le moteur ne juge pas. C'est l'état actuel, désormais écrit ;
   • refuser dans isValid() — cohérent avec « les états invalides doivent être inexprimables » (LM-302), mais domain cesse d'être une métadonnée : ce serait un changement de contrat, à annoncer à l'app. Et le contrôle reste contournable par omission, puisque le domaine est facultatif — un refus qu'on esquive en effaçant un champ protège mal ;
   • avertir sans refuser — une ligne de journal à la construction de l'adaptateur. Ne bloque pas une installation atypique, laisse une trace lisible au banc.

   Le troisième est le seul qui ne mente ni sur le statut de domain, ni sur la force réelle du contrôle. À trancher, pas par moi.

---

§9 — Ce que ce document ne change pas

• L'ordre de specs/spec_ecs.md §2 et ses arbitrages bloquants.
• Les règles absolues 1 à 10 d'AGENTS.md.
• Le découpage en vigueur : le scheduler alloue, RelayRouter traduit.
• Rien dans le code aujourd'hui.