{
  "openrpc": "1.3.2",
  "info": {
    "title": "etm-powersync — protocole moteur ↔ optimiseur",
    "version": "1.8",
    "license": {
      "name": "GPL-3.0-or-later",
      "url": "https://www.gnu.org/licenses/gpl-3.0.html"
    },
    "description": "Contrat MACHINE du protocole entre le moteur d'énergie etm-powersync-energy-plugin-etm (client) et un optimiseur externe (serveur) — docs/OPTIMIZER_PROTOCOL.md en est la prose. Ce document est la source de la forme des messages ; il est servi par le moteur qui tourne (NymeaEnergy.GetOptimizerProtocol) et les deux côtés sont testés contre lui.\n\nCe qu'OpenRPC ne dit pas, et où cela se trouve :\n- TRANSPORT : unix:// (défaut, socket local 0660) ou tcp:// (LAN), JSON-RPC 2.0, un message par ligne (NDJSON), UTF-8 — x-etm-transport ;\n- SENS : le moteur est le CLIENT, il se connecte et envoie Handshake puis GetPlan ; la box n'ouvre aucun port. UpdateLearned va dans l'autre sens (x-etm-direction) ;\n- ERREURS de l'optimiseur (1.2) : par méthode dans methods[].errors, et pour un message qu'il ne peut pas traiter (ligne illisible, lot, ligne trop longue, méthode inconnue) dans x-etm-message-errors ; forme de error.data d'une erreur, quand elle est normée (1.3) : x-etm-data-schema de l'erreur, exigée à partir de x-etm-data-required-from ; jamais la valeur reçue dans error.message (1.4) : x-etm-error-message ;\n- HEARTBEAT IMPLICITE et machine de repli §7 — x-etm-fallback-machine ;\n- VALIDATION SÉMANTIQUE du plan : le JSON Schema dit la forme ; ce que le validateur du moteur refuse en plus (charge inconnue, créneau courant incomplet…) est listé, règle par règle, dans x-etm-semantic-rules avec son fallbackCode ;\n- listes fermées : régénérées DEPUIS LE CODE (x-etm-generated), jamais recopiées à la main.\n\nForme côté moteur (requêtes) : STRICTE — additionalProperties: false ; un champ ajouté au sérialiseur sans le schéma fait échouer les tests. Cette fermeture juge ce qu'émet le MOTEUR contre la version qu'il annonce : un optimiseur d'une mineure antérieure ne s'en sert pas pour refuser un contexte, il ignore les champs qu'il ne connaît pas (§7, §9). Forme côté optimiseur (réponses) : ouverte — un champ inconnu est ignoré (§9) ; le schéma dit ce qu'un optimiseur CONFORME envoie, x-etm-tolerances ce que le moteur accepte en plus."
  },
  "servers": [
    {
      "name": "unix",
      "url": "unix:///run/powersync/optimizer.sock",
      "summary": "Défaut : optimiseur local, socket possédé par root:powersync, mode 0660. Le répertoire /run/powersync appartient au paquet de l'optimiseur (x-etm-transport.runtimeDirectory)."
    },
    {
      "name": "tcp",
      "url": "tcp://{host}:{port}",
      "summary": "Optimiseur sur le LAN. Token recommandé ; il circule en clair sans TLS (E16).",
      "variables": {
        "host": {
          "default": "192.0.2.10"
        },
        "port": {
          "default": "7400"
        }
      }
    }
  ],
  "methods": [
    {
      "name": "Handshake",
      "summary": "Ouverture de session, à chaque (re)connexion (§3).",
      "description": "Envoyé par le moteur (client) dès la connexion. Délai : 5 s depuis le DÉBUT de la tentative ; au-delà, repli et nouvelle tentative au backoff. Le message porte le secret : il n'est jamais journalisé. Refus (1.2) : token absent ou différent → -32001 ; majeure incompatible → -32602 ; les deux fautes dans le même handshake → -32001, le token est jugé AVANT la majeure (1.3) ; l'optimiseur ferme après avoir envoyé l'erreur, le moteur à sa réception. Un token envoyé alors que l'optimiseur n'en exige pas est accepté, sans erreur.",
      "paramStructure": "by-name",
      "params": [
        {
          "name": "protocolVersion",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/ProtocolVersion"
          },
          "description": "Version du moteur ; seule la majeure est comparée, des deux côtés (une autre majeure : l'optimiseur répond -32602 et ferme — -32001 si le token est faux aussi, 1.3)."
        },
        {
          "name": "engine",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^etm-powersync-energy-plugin-etm/"
          },
          "description": "Moteur et sa version."
        },
        {
          "name": "token",
          "required": false,
          "schema": {
            "$ref": "#/components/schemas/HandshakeToken"
          }
        }
      ],
      "result": {
        "name": "handshake",
        "schema": {
          "$ref": "#/components/schemas/HandshakeResult"
        }
      },
      "errors": [
        {
          "code": -32001,
          "message": "token refusé",
          "data": "Token configuré côté optimiseur, et absent ou différent dans le Handshake — jugé AVANT la majeure (1.3) : token faux et autre majeure dans le même Handshake → -32001. Un token envoyé alors que l'optimiseur n'en exige pas est ACCEPTÉ.",
          "x-etm-connection": "fermée"
        },
        {
          "code": -32602,
          "message": "majeure incompatible",
          "data": "Majeure de params.protocolVersion différente de celle de l'optimiseur (1.2), le token étant accepté ou non exigé (1.3 : le token est jugé d'abord).",
          "x-etm-connection": "fermée"
        }
      ],
      "x-etm-direction": "engine→optimizer",
      "x-etm-timeout-s": 5,
      "x-etm-errors-engine": "Toute réponse error au Handshake, quel que soit son code : handshake-refused, le moteur ferme, nouvelle tentative au backoff."
    },
    {
      "name": "GetPlan",
      "summary": "Demande d'un plan pour le contexte courant (§4-§6).",
      "description": "À chaque cycle (~1/min) et sur événement (trigger). Une requête en vol au plus : une plus récente remplace l'attente de la précédente (sa réponse est ignorée par id, ce n'est pas un échec). Délai : 10 s par requête. La réponse à la requête N sert au cycle N+1 (modèle cache). Le JSON Schema dit la FORME ; x-etm-semantic-rules dit ce que le validateur refuse en plus.",
      "paramStructure": "by-name",
      "params": [
        {
          "name": "timestamp",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          },
          "description": "Instant du cycle — le « maintenant » du validateur."
        },
        {
          "name": "trigger",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Trigger"
          }
        },
        {
          "name": "site",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Site"
          }
        },
        {
          "name": "meter",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Meter"
          }
        },
        {
          "name": "pv",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Pv"
          }
        },
        {
          "name": "battery",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Battery"
          }
        },
        {
          "name": "loads",
          "required": true,
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Load"
            }
          },
          "description": "Charges arbitrées, ⊆ GetLoadConfig."
        },
        {
          "name": "forecast",
          "required": true,
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Forecast"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": "null sans instantané de prévision."
        },
        {
          "name": "tariff",
          "required": true,
          "schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Tariff"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      ],
      "result": {
        "name": "plan",
        "schema": {
          "$ref": "#/components/schemas/GetPlanResult"
        }
      },
      "errors": [
        {
          "code": -32600,
          "message": "handshake requis",
          "data": "GetPlan reçu avant un Handshake réussi sur cette connexion (1.2). Le moteur n'en envoie jamais : il attend d'être prêt.",
          "x-etm-connection": "conservée"
        },
        {
          "code": -32602,
          "message": "contexte invalide",
          "data": "Contexte GetPlan non conforme au contrat (1.2). error.data liste les problèmes : pour chacun, le chemin du champ fautif et la nature du problème, JAMAIS la valeur reçue. Forme normée en 1.3 : InvalidContextData. Une erreur et non une abstention : un contexte invalide est un défaut du moteur, une abstention le cacherait.",
          "x-etm-data-schema": {
            "$ref": "#/components/schemas/InvalidContextData"
          },
          "x-etm-data-required-from": "1.3",
          "x-etm-connection": "conservée"
        },
        {
          "code": -32603,
          "message": "erreur interne",
          "data": "Code JSON-RPC 2.0 standard pour toute autre panne de l'optimiseur.",
          "x-etm-connection": "conservée"
        }
      ],
      "x-etm-direction": "engine→optimizer",
      "x-etm-timeout-s": 10,
      "x-etm-errors-engine": "Toute réponse error à GetPlan, quel que soit son code : échec de la requête (rpc-error), compté par la règle des échecs consécutifs (§7). error.data n'est PAS lu : ni décision, ni journal (le code seul), ni trace (le code de l'échec seul, rpc-error)."
    },
    {
      "name": "UpdateLearned",
      "summary": "Estimations apprises de l'optimiseur (§8) — notification, sans id.",
      "description": "Envoyée par l'OPTIMISEUR, et seulement par lui (1.2) : sens inverse des deux autres, sans id, sans réponse. Reçue PAR UN OPTIMISEUR : notification ignorée ; requête avec id → -32601 (x-etm-message-errors). État du moteur : reçue, journalisée une fois, IGNORÉE — rien n'est persisté, le contenu n'est pas lu. Forme NON NORMÉE (1.2 à 1.4) : elle sera fixée avec la première stratégie qui apprend.",
      "paramStructure": "by-name",
      "params": [
        {
          "name": "loads",
          "required": false,
          "schema": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "description": "Non normé (1.2 à 1.4) : intention §8 (learned + confidence par charge)."
        }
      ],
      "x-etm-direction": "optimizer→engine",
      "x-etm-notification": true
    }
  ],
  "components": {
    "schemas": {
      "ProtocolVersion": {
        "description": "Version du protocole parlée par le moteur (GEN : OptimizerProtocol::ProtocolVersion).",
        "const": "1.8"
      },
      "Trigger": {
        "description": "Cause de la requête (§5.1). GEN : SocketScheduler::knownTriggers() — du moins au plus significatif.",
        "type": "string",
        "enum": [
          "cycle",
          "forecast",
          "config",
          "load-change",
          "intent"
        ]
      },
      "Domain": {
        "description": "Intention déclarée par l'installateur, jamais déduite du mécanisme, non lue par l'arbitre (§5.3). GEN : LoadConfig::knownDomains().",
        "type": "string",
        "enum": [
          "ecs",
          "ev",
          "heating",
          "hvac",
          "battery"
        ]
      },
      "ActionKind": {
        "description": "Type d'action (§6). GEN : OptimizerPlan::kinds(). `constraint` est RÉSERVÉ (annexe F) : reconnu par le validateur, toujours refusé (règle kind-mismatch) faute de mécanisme porteur.",
        "type": "string",
        "enum": [
          "setpoint",
          "state",
          "constraint"
        ]
      },
      "ReasonCode": {
        "description": "Codes de motif qu'un optimiseur peut émettre (§6, liste blanche). GEN : DecisionCode::optimizerEmittableCodes(). Clés de paramètres admises par code : x-etm-reason-params.",
        "type": "string",
        "enum": [
          "SURPLUS_SETPOINT",
          "SURPLUS_INSUFFICIENT",
          "BELOW_MIN_POWER",
          "EV_DEADLINE",
          "SG_FORCED",
          "SG_RECOMMENDED",
          "SG_NORMAL",
          "ECO_FLOOR_GRID",
          "PRICE_SLOT",
          "OPTIMIZER_DECISION",
          "TARGET_NOT_MET"
        ]
      },
      "PriceInclude": {
        "description": "Composante incluse dans le prix (§5.2). GEN : TariffConfig::includes().",
        "type": "string",
        "enum": [
          "energy",
          "grid",
          "taxes"
        ]
      },
      "FallbackCode": {
        "description": "Côté app (NymeaEnergy.GetPlan.fallbackCode) : pourquoi l'optimiseur n'a pas commandé le cycle. Hors fil. GEN : SocketScheduler::knownFallbackCodes().",
        "type": "string",
        "enum": [
          "no-plan",
          "abstain",
          "empty-plan",
          "no-current-slot",
          "expired",
          "malformed-plan",
          "bad-time",
          "slots-unordered",
          "malformed-action",
          "unknown-load",
          "unknown-kind",
          "kind-mismatch",
          "kind-not-announced",
          "missing-reason",
          "bad-value",
          "duplicate-load",
          "incomplete-slot",
          "no-shadow-slot"
        ]
      },
      "LastErrorCode": {
        "description": "Côté app (NymeaEnergy.GetOptimizerStatus.lastErrorCode) : dernier code d'erreur vu (connexion, requête, plan). Hors fil. GEN : SocketScheduler::knownLastErrorCodes().",
        "type": "string",
        "enum": [
          "invalid-endpoint",
          "token-too-short",
          "connect-failed",
          "closed-during-handshake",
          "connection-lost",
          "handshake-timeout",
          "handshake-refused",
          "invalid-handshake",
          "major-mismatch",
          "line-too-long",
          "invalid-json",
          "missing-id",
          "unknown-id",
          "timeout",
          "rpc-error",
          "invalid-response",
          "disconnected",
          "request-too-long",
          "malformed-plan",
          "bad-time",
          "slots-unordered",
          "malformed-action",
          "unknown-load",
          "unknown-kind",
          "kind-mismatch",
          "kind-not-announced",
          "missing-reason",
          "bad-value",
          "duplicate-load",
          "incomplete-slot"
        ]
      },
      "HandshakeToken": {
        "description": "Secret partagé (§3, E-T2-8) : 16 caractères au moins, 4 096 octets au plus (borne en octets non exprimable ici : contrôlée par le moteur), imprimable, sans blanc ni caractère de contrôle, UTF-8 admis. Envoyé seulement s'il est configuré ; jamais journalisé.",
        "type": "string",
        "minLength": 16,
        "pattern": "^[^\\s\\x00-\\x1f\\x7f]+$"
      },
      "Capabilities": {
        "description": "Capacités annoncées (§3, 1.1, optionnel). Affichées en mode installateur, réduites aux clés et valeurs connues (capacitesPubliees) ; un champ inconnu est ignoré (§9).",
        "type": "object",
        "properties": {
          "maxHorizonH": {
            "description": "Horizon maximal planifié, en heures.",
            "type": "number",
            "minimum": 0
          },
          "resolutionS": {
            "description": "Pas des créneaux, en secondes.",
            "type": "number",
            "minimum": 0
          },
          "kinds": {
            "description": "PRÉSENT, il restreint les kinds acceptés (règle kind-not-announced).",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActionKind"
            }
          },
          "usesForecast": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "pv",
                "baseload",
                "price",
                "temperature"
              ]
            }
          },
          "reasonCodes": {
            "description": "L'optimiseur émet des reasonCode du catalogue.",
            "type": "boolean"
          }
        },
        "required": [],
        "additionalProperties": true
      },
      "HandshakeResult": {
        "type": "object",
        "properties": {
          "protocolVersion": {
            "description": "Version semver de l'optimiseur ; même MAJEURE que le moteur exigée (règle major-mismatch).",
            "type": "string",
            "minLength": 1,
            "pattern": "^[0-9]+(\\.[0-9]+)*$"
          },
          "name": {
            "description": "Nom affiché (mode installateur), non contrôlé par le moteur (E-T7-3).",
            "type": "string"
          },
          "planning": {
            "description": "Vrai si l'optimiseur produit des plans multi-créneaux. Informatif.",
            "type": "boolean"
          },
          "capabilities": {
            "$ref": "#/components/schemas/Capabilities"
          }
        },
        "required": [
          "protocolVersion"
        ],
        "additionalProperties": true
      },
      "Site": {
        "type": "object",
        "properties": {
          "contractedPowerW": {
            "description": "Puissance souscrite (W) ; null si inconnue (E1), jamais 0.",
            "type": [
              "number",
              "null"
            ]
          },
          "gridCapW": {
            "description": "RÉSERVÉ (signaux réseau type §14a EnWG) : toujours null en 1.1.",
            "type": "null"
          },
          "phaseLimitA": {
            "description": "SEUIL par phase (A) que le moteur fait respecter au COMPTEUR RACINE — le courant total de la phase, maison comprise, pas la part des charges pilotées : la limite du branchement moins la marge de sécurité (phaseSafetyMarginPercent), pas la limite elle-même ; un plan bâti sur la limite serait écrêté à chaque cycle. Ce qu'une charge peut encore prendre = seuil − courant mesuré de la phase (meter.perPhaseA) + ce qu'elle tire déjà. null sans limite réglée.",
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "number"
            }
          },
          "timeZone": {
            "description": "1.8 — fuseau IANA de la box (« Europe/Paris ») : celui des heures murales du contexte (needs.dailyDeadline, départ quotidien d'une voiture, heures du tarif). Absent pour un optimiseur 1.7 ou antérieur, et si la box n'en connaît pas.",
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "contractedPowerW",
          "gridCapW",
          "phaseLimitA"
        ],
        "additionalProperties": false
      },
      "Meter": {
        "type": "object",
        "properties": {
          "source": {
            "description": "ThingId du compteur racine désigné ; null si inconnu.",
            "type": [
              "string",
              "null"
            ]
          },
          "importW": {
            "description": "Puissance importée (W).",
            "type": "number",
            "minimum": 0
          },
          "exportW": {
            "description": "Exported power (W), RAW measurement (rule 8 of the project's coding rules) — never the net after control.",
            "type": "number",
            "minimum": 0
          },
          "perPhaseA": {
            "description": "Courant par phase (A).",
            "type": "array",
            "items": {
              "type": "number"
            }
          }
        },
        "required": [
          "source",
          "importW",
          "exportW",
          "perPhaseA"
        ],
        "additionalProperties": false
      },
      "Pv": {
        "type": "object",
        "properties": {
          "currentW": {
            "description": "Production instantanée (W), positive ; null sans producteur (jamais 0).",
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          }
        },
        "required": [
          "currentW"
        ],
        "additionalProperties": false
      },
      "BatteryAbsent": {
        "description": "Aucun stockage déclaré : rien d'autre n'est émis.",
        "type": "object",
        "properties": {
          "present": {
            "const": false
          }
        },
        "required": [
          "present"
        ],
        "additionalProperties": false
      },
      "BatteryPresent": {
        "type": "object",
        "properties": {
          "present": {
            "const": true
          },
          "socPercent": {
            "type": "number"
          },
          "powerW": {
            "description": "Positif = charge, négatif = décharge.",
            "type": "number"
          },
          "capacityWh": {
            "description": "null si inconnue.",
            "type": [
              "number",
              "null"
            ]
          },
          "maxChargeW": {
            "description": "null si inconnue.",
            "type": [
              "number",
              "null"
            ]
          },
          "maxDischargeW": {
            "description": "null si inconnue.",
            "type": [
              "number",
              "null"
            ]
          },
          "reserveSocPercent": {
            "description": "Réserve de secours (%) ; null si inconnue.",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "present",
          "socPercent",
          "powerW",
          "capacityWh",
          "maxChargeW",
          "maxDischargeW",
          "reserveSocPercent"
        ],
        "additionalProperties": false
      },
      "Battery": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BatteryAbsent"
          },
          {
            "$ref": "#/components/schemas/BatteryPresent"
          }
        ]
      },
      "TariffEntry": {
        "description": "Zone tarifaire en vigueur à timestamp (1.4).",
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Libellé saisi par l'installateur, ou code de période publié par un appareil fournisseur de tarif (donnée, jamais une phrase du moteur)."
          },
          "priceCtkWh": {
            "type": "number",
            "description": "Prix complet payé de la zone, c€/kWh."
          },
          "offPeak": {
            "description": "La zone est CREUSE au jugement du moteur (1.4) : au prix le plus bas d'un tarif dont les zones n'ont pas toutes le même prix — plusieurs zones à ce prix sont toutes creuses ; le libellé n'y entre pas. Tarif unique ou prix tous égaux : false. Tarif lu sur un appareil fournisseur : le créneau au NOMINAL (0-100) le plus bas parmi les créneaux connus, même règle (TariffConfig::niveauxCreux()). Même lecture que les décisions du rule-based.",
            "type": "boolean"
          },
          "nominal": {
            "description": "1.6 — prix NORMALISÉ du créneau, 0-100 : 0 = la période la moins chère du CONTRAT, 100 = la plus chère, les autres au prorata de leur prix, arrondi à l'entier ; contrat à prix unique (base, prix tous égaux) : 0. Tarif lu sur un appareil fournisseur : le nominal qu'il publie ; tarif saisi : calculé de même sur les zones saisies. Relatif au contrat, jamais à la journée. null : le prix du créneau n'est pas confirmé (publié présumé — priceKnown faux chez le fournisseur, couleur Tempo pas encore annoncée). C'est la grandeur que l'optimiseur place ; il ne lit pas le contrat.",
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "expensive": {
            "description": "1.6 — le créneau est au PRIX FORT au jugement du moteur : prix ≥ facteur (2 par défaut, réglable de 1,5 à 4) × le prix le plus bas du contrat (pointe EJP, rouge Tempo HP ; jamais HC/HP, base, Tempo bleu ou blanc). Le moteur n'y prend rien du réseau sans l'accord de l'usager, quel que soit le plan (§1). Même règle que ses décisions ; appliquée au prix publié, confirmé ou non.",
            "type": "boolean"
          }
        },
        "required": [
          "label",
          "priceCtkWh",
          "offPeak",
          "nominal",
          "expensive"
        ],
        "additionalProperties": false
      },
      "TariffNextEntry": {
        "description": "Un changement de zone (1.4) : la zone qui commence à from et court jusqu'au from suivant.",
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "priceCtkWh": {
            "type": "number"
          },
          "from": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Début de la zone : instant ISO 8601 AVEC son décalage (Z ou ±hh:mm), tiré de la plage murale minute par minute absolue — une heure murale nue est refusée. Jamais null en 1.4."
          },
          "offPeak": {
            "description": "La zone est CREUSE au jugement du moteur (1.4) : au prix le plus bas d'un tarif dont les zones n'ont pas toutes le même prix — plusieurs zones à ce prix sont toutes creuses ; le libellé n'y entre pas. Tarif unique ou prix tous égaux : false. Tarif lu sur un appareil fournisseur : le créneau au NOMINAL (0-100) le plus bas parmi les créneaux connus, même règle (TariffConfig::niveauxCreux()). Même lecture que les décisions du rule-based.",
            "type": "boolean"
          },
          "nominal": {
            "description": "1.6 — prix NORMALISÉ du créneau, 0-100 : 0 = la période la moins chère du CONTRAT, 100 = la plus chère, les autres au prorata de leur prix, arrondi à l'entier ; contrat à prix unique (base, prix tous égaux) : 0. Tarif lu sur un appareil fournisseur : le nominal qu'il publie ; tarif saisi : calculé de même sur les zones saisies. Relatif au contrat, jamais à la journée. null : le prix du créneau n'est pas confirmé (publié présumé — priceKnown faux chez le fournisseur, couleur Tempo pas encore annoncée). C'est la grandeur que l'optimiseur place ; il ne lit pas le contrat.",
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 100
          },
          "expensive": {
            "description": "1.6 — le créneau est au PRIX FORT au jugement du moteur : prix ≥ facteur (2 par défaut, réglable de 1,5 à 4) × le prix le plus bas du contrat (pointe EJP, rouge Tempo HP ; jamais HC/HP, base, Tempo bleu ou blanc). Le moteur n'y prend rien du réseau sans l'accord de l'usager, quel que soit le plan (§1). Même règle que ses décisions ; appliquée au prix publié, confirmé ou non.",
            "type": "boolean"
          }
        },
        "required": [
          "label",
          "priceCtkWh",
          "from",
          "offPeak",
          "nominal",
          "expensive"
        ],
        "additionalProperties": false
      },
      "Tariff": {
        "description": "Le tarif EN VIGUEUR, rempli depuis 1.4 : le tarif SAISI (NymeaEnergy.SetTariff), ou celui d'un appareil fournisseur de tarif choisi par NymeaEnergy.SetTariffSource (ses créneaux connus) — null sans tarif. current : la zone en vigueur à timestamp ; next : chaque changement de zone après timestamp, dans l'ordre, jusqu'à la fin du lendemain dans le fuseau de la box (l'horizon de forecast). offPeak sur chaque entrée : le jugement « heures creuses » du moteur. Le prix sur la grille de la prévision se lit dans forecast.price (1.1), du même tarif. 1.6 : chaque entrée porte nominal (0-100, null si le prix n'est pas confirmé) et expensive (le prix fort du moteur). Rien n'est émis au-delà du connu : la fin du connu est forecast.price.knownUntil.",
        "type": "object",
        "properties": {
          "provider": {
            "type": [
              "string",
              "null"
            ],
            "description": "null : un tarif saisi n'a pas de fournisseur. Tarif lu sur un appareil fournisseur : le nom de son plugin (« edf »)."
          },
          "current": {
            "$ref": "#/components/schemas/TariffEntry"
          },
          "next": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TariffNextEntry"
            }
          }
        },
        "required": [
          "provider",
          "current",
          "next"
        ],
        "additionalProperties": false
      },
      "Correction": {
        "type": "string",
        "enum": [
          "temperature",
          "ac-limit"
        ]
      },
      "PvField": {
        "type": "object",
        "properties": {
          "id": {
            "description": "ThingId du plan.",
            "type": "string"
          },
          "corrections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Correction"
            }
          }
        },
        "required": [
          "id",
          "corrections"
        ],
        "additionalProperties": false
      },
      "PvForecast": {
        "type": "object",
        "properties": {
          "p50W": {
            "description": "Puissance AC moyenne sur [t, t+pas), sommée sur les plans puis plafonnée à acLimitW ; null = case inconnue. Un plafond, pas une espérance (§5.2).",
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "conversion": {
            "description": "Seule valeur émise par le moteur GPL ; un consommateur ignore une valeur inconnue.",
            "type": "string",
            "enum": [
              "physics"
            ]
          },
          "corrections": {
            "description": "[] = conversion brute.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Correction"
            }
          },
          "weatherModel": {
            "description": "Modèle qui a RÉPONDU ; null si inconnu.",
            "type": [
              "string",
              "null"
            ]
          },
          "issuedAt": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          },
          "contentChangedAt": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          },
          "acLimitW": {
            "description": "Plafond AC du site (W), s'il est configuré.",
            "type": "integer"
          },
          "perField": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PvField"
            }
          }
        },
        "required": [
          "p50W",
          "conversion",
          "corrections",
          "weatherModel",
          "issuedAt",
          "contentChangedAt"
        ],
        "additionalProperties": false
      },
      "BaseloadLoadQuality": {
        "type": "object",
        "properties": {
          "loadId": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "meter",
              "device",
              "none"
            ]
          },
          "minutesBySource": {
            "type": "object",
            "propertyNames": {
              "enum": [
                "meter",
                "device",
                "none"
              ]
            },
            "additionalProperties": {
              "type": "integer"
            }
          },
          "constantMeasurement": {
            "type": "boolean"
          }
        },
        "required": [
          "loadId",
          "source",
          "minutesBySource"
        ],
        "additionalProperties": false
      },
      "BaseloadQuality": {
        "type": "object",
        "properties": {
          "windowDays": {
            "type": "integer"
          },
          "minDays": {
            "type": "integer"
          },
          "resolutionS": {
            "type": "integer"
          },
          "daysCovered": {
            "type": "object",
            "properties": {
              "workday": {
                "type": "integer"
              },
              "weekend": {
                "type": "integer"
              }
            },
            "required": [
              "workday",
              "weekend"
            ],
            "additionalProperties": false
          },
          "minutes": {
            "type": "integer"
          },
          "commandedMinutes": {
            "type": "integer"
          },
          "negativeMinutes": {
            "type": "integer"
          },
          "incompleteMinutes": {
            "type": "integer"
          },
          "computedAt": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          },
          "loads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BaseloadLoadQuality"
            }
          }
        },
        "required": [
          "windowDays",
          "minDays",
          "resolutionS",
          "daysCovered",
          "minutes",
          "commandedMinutes",
          "negativeMinutes",
          "incompleteMinutes",
          "loads"
        ],
        "additionalProperties": false
      },
      "Baseload": {
        "type": "object",
        "properties": {
          "model": {
            "description": "Le moteur GPL émet profile ou none (learned n'est pas émis).",
            "type": "string",
            "enum": [
              "profile",
              "none"
            ]
          },
          "p50W": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "quality": {
            "$ref": "#/components/schemas/BaseloadQuality"
          }
        },
        "required": [
          "model",
          "p50W"
        ],
        "additionalProperties": false
      },
      "Price": {
        "type": "object",
        "properties": {
          "currency": {
            "const": "EUR"
          },
          "importCtkWh": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "exportCtkWh": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "includes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceInclude"
            }
          },
          "source": {
            "description": "Une zone (fixed) ou des zones horaires (tou). Créneaux d'un appareil fournisseur : tou dès que leurs prix diffèrent, fixed sinon ; une case de la grille non couverte par les créneaux connus vaut null, et knownUntil est la fin du connu. tempo et day-ahead ne sont pas émis en 1.1.",
            "type": "string",
            "enum": [
              "fixed",
              "tou"
            ]
          },
          "knownUntil": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          }
        },
        "required": [
          "currency",
          "importCtkWh",
          "exportCtkWh",
          "includes",
          "source",
          "knownUntil"
        ],
        "additionalProperties": false
      },
      "Forecast": {
        "description": "Prévisions sur UNE grille (§5.2) ; tableaux alignés index par index.",
        "type": "object",
        "properties": {
          "start": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          },
          "resolutionS": {
            "description": "Pas de la grille (s) — fait foi, jamais supposé.",
            "type": "integer",
            "minimum": 1
          },
          "steps": {
            "description": "Nombre de cases ; toutes les séries ont cette longueur.",
            "type": "integer",
            "minimum": 0
          },
          "pv": {
            "description": "null sans courbe (site non désigné, charge utile refusée, canal muet).",
            "anyOf": [
              {
                "$ref": "#/components/schemas/PvForecast"
              },
              {
                "type": "null"
              }
            ]
          },
          "baseload": {
            "$ref": "#/components/schemas/Baseload"
          },
          "weather": {
            "description": "Aucune source de température en 1.1 : toujours null.",
            "type": "null"
          },
          "price": {
            "description": "null sans tarif (ni saisi, ni lu sur un appareil fournisseur).",
            "anyOf": [
              {
                "$ref": "#/components/schemas/Price"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "start",
          "resolutionS",
          "steps",
          "pv",
          "baseload",
          "weather",
          "price"
        ],
        "additionalProperties": false
      },
      "Measurement": {
        "oneOf": [
          {
            "description": "Rien ne mesure : état positif, pas une erreur.",
            "type": "object",
            "properties": {
              "source": {
                "const": "none"
              }
            },
            "required": [
              "source"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "meter",
                  "device"
                ]
              },
              "powerW": {
                "type": "number"
              }
            },
            "required": [
              "source",
              "powerW"
            ],
            "additionalProperties": false
          }
        ],
        "description": "Mesure par charge (§5.3, LM-1105/1106) : décider sur source, jamais sur adapter."
      },
      "EnergyTarget": {
        "type": "object",
        "properties": {
          "by": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          },
          "minWh": {
            "description": "Énergie minimale à avoir délivrée à l'échéance.",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "source": {
            "description": "installer : obligation quotidienne (1.1). user-intent : dérogation à cible d'énergie (1.1), ou SoC visé d'une voiture converti en Wh — énergie qui RESTE à charger d'ici le départ, batterie seule (1.5). learned n'est pas émis.",
            "type": "string",
            "enum": [
              "installer",
              "user-intent"
            ]
          }
        },
        "required": [
          "by",
          "minWh",
          "source"
        ],
        "additionalProperties": false
      },
      "LoadNeeds": {
        "description": "Besoins (§5.3). Champs 1.0 émis tels quels quand ils sont déclarés ; un optimiseur 1.1 préfère energyTargets.",
        "type": "object",
        "properties": {
          "dailyDeadline": {
            "description": "Heure murale locale HH:MM (1.0).",
            "type": "string",
            "pattern": "^[0-9]{2}:[0-9]{2}$"
          },
          "minEnergyWhPerDay": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "targetSocPercent": {
            "description": "SoC visé (%). 1.5 — pour une borne : le SoC VISÉ de la voiture assignée, réglé par l'usager (NymeaEnergy.SetCarChargingSettings) ; le moteur ne le planifie pas.",
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 100
          },
          "deadline": {
            "description": "Échéance absolue. 1.5 — pour une borne : le PROCHAIN départ de la voiture assignée (le départ ponctuel tant qu'il est à venir, sinon la prochaine heure quotidienne). Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.",
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "energyTargets": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/EnergyTarget"
            }
          },
          "offPeakShift": {
            "description": "1.4 — true, ou absent : le besoin RÉSEAU de cette charge se reporte en heures creuses (borne en « Éco avec minimum » ou à échéance). Le rule-based la sert à pleine puissance dans les zones offPeak de tariff, au surplus seulement en dehors ; sans heure creuse, sans effet.",
            "type": "boolean",
            "const": true
          },
          "minSocPercent": {
            "description": "1.5 — SoC MINIMUM de la voiture assignée (%), une sécurité : le moteur le sert lui-même, à pleine puissance permise, et impose son action comme PLANCHER sur le plan (progress.minSocStatus: below). À planifier autour, jamais à retirer. ABSENT, comme minSocStatus, quand la voiture est sous son minimum pendant la période chère du tarif sans confirmation de l'usager : le moteur ne le sert pas alors, et n'impose aucun plancher.",
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 90
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "LoadLearned": {
        "description": "Absent tant qu'aucun profil n'a été reçu (E12).",
        "type": "object",
        "properties": {
          "dailyEnergyWh": {
            "type": "number"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "required": [
          "dailyEnergyWh",
          "confidence"
        ],
        "additionalProperties": false
      },
      "Vehicle": {
        "description": "1.5 — la voiture ASSIGNÉE à la borne, lue sur ses états génériques (jamais une marque). Absente sans voiture assignée.",
        "type": "object",
        "properties": {
          "carId": {
            "description": "Identifiant de la voiture (ThingId) — stable d'une borne à l'autre.",
            "type": "string",
            "minLength": 1
          },
          "source": {
            "description": "vehicle : SoC lu sur la voiture (état en lecture seule) ; estimate : SoC saisi par l'usager et avancé par l'estimation du moteur.",
            "type": "string",
            "enum": [
              "vehicle",
              "estimate"
            ]
          },
          "known": {
            "description": "Un SoC est lu. Faux : socPercent absent (jamais 0).",
            "type": "boolean"
          },
          "socPercent": {
            "description": "SoC lu (%). Présent si known.",
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "socAt": {
            "description": "Instant du SoC, quand la voiture l'horodate ; absent sinon (son âge est alors inconnu). Le moteur juge un SoC de plus de 12 h trop ancien pour servir le minimum. Instant ISO 8601 AVEC son décalage.",
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "capacityWh": {
            "description": "Capacité de la batterie (Wh) ; absente si inconnue.",
            "type": "number",
            "exclusiveMinimum": 0
          },
          "sessionMinEnergyWh": {
            "description": "1.8 — kWh minimum PAR BRANCHEMENT réglés pour cette voiture (Wh), avant son départ (needs.deadline). Servis par le moteur quand le SoC n'est pas utilisable (inconnu, périmé, ou aucun visé) : energyTargets en porte alors le reste (source user-intent) et progress l'avancement, compté sur l'énergie de CETTE borne depuis le branchement, remis à zéro au débranchement. Une borne qui ne mesure ni l'énergie de sa séance ni sa puissance (progress.energyRegime estimated, estimé sur la puissance commandée) : le reste compte en plus 10 % de ces kWh (supplément exigé avant de les dire livrés, energyTargetWh reste la valeur réglée). Absent si non réglé.",
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "departureMarginS": {
            "description": "1.8 — marge de départ de la voiture (s, 0 à 7 200, défaut 1 800), présente dès qu'un départ est connu (needs.deadline). Les kWh (energyTargets, source user-intent) et le SoC visé sont à livrer AVANT deadline − marge — et avant le début d'un prix fort connu plus tôt ; de deadline − marge à deadline, la borne reste ouverte au plancher (6 A sur les phases tenues) pour que la voiture prenne son préconditionnement sur le secteur, jamais au prix fort sans accord de l'usager. 0 = finir à l'heure du départ, sans fenêtre de préconditionnement. Le moteur seul (rule-based) applique cette règle aux kWh par branchement.",
            "type": "integer",
            "minimum": 0,
            "maximum": 7200
          }
        },
        "required": [
          "carId",
          "source",
          "known"
        ],
        "additionalProperties": false
      },
      "LoadProgress": {
        "description": "1.5 — AVANCEMENT des obligations de la charge, forme plate ; chaque champ est présent seulement s'il a un objet. Pour qu'un optimiseur planifie la journée entière sans rien laisser au rule-based.",
        "type": "object",
        "properties": {
          "chargingMode": {
            "description": "Borne : le mode choisi par l'usager (normal = Manuel, eco = Auto).",
            "type": "string",
            "enum": [
              "normal",
              "eco",
              "ecoWithMinCurrent",
              "ecoWithTargetTime",
              "ecoMinWithTargetTime"
            ]
          },
          "manualEnabled": {
            "description": "Borne en mode normal dont l'interrupteur Manuel a été posé : activé (pleine puissance) ou désactivé (arrêt).",
            "type": "boolean"
          },
          "energyTargetWh": {
            "description": "Obligation quotidienne en énergie (Wh) — needs.minEnergyWhPerDay.",
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "energyDeliveredWh": {
            "description": "Énergie livrée sur la période d'obligation en cours (Wh) ; ABSENTE si elle ne se mesure pas (energyRegime: unmeasurable), jamais 0.",
            "type": "integer",
            "minimum": 0
          },
          "energyRegime": {
            "description": "D'où vient energyDeliveredWh.",
            "type": "string",
            "enum": [
              "measured",
              "estimated",
              "unmeasurable"
            ]
          },
          "energyBy": {
            "description": "Échéance de l'obligation quotidienne en cours. Instant ISO 8601 AVEC son décalage.",
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "derogationEndsAt": {
            "description": "Fin du filet de la dérogation qui court. Instant ISO 8601 AVEC son décalage.",
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "derogationTargetWh": {
            "description": "Cible en énergie de la dérogation (Wh), depuis sa pose.",
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "derogationDeliveredWh": {
            "description": "Énergie livrée depuis la pose de la dérogation (Wh).",
            "type": "integer",
            "minimum": 0
          },
          "minSocStatus": {
            "description": "SoC minimum de la voiture assignée : below — sous le minimum, le moteur le sert CE cycle et impose son action comme plancher (l'action de l'optimiseur pour cette borne est ignorée) ; met — atteint ; unknown / stale — non servi, SoC inconnu ou trop ancien. Absent sans minimum réglé, et quand la voiture est sous son minimum pendant la période chère du tarif sans confirmation de l'usager (non servi, aucun plancher).",
            "type": "string",
            "enum": [
              "below",
              "met",
              "unknown",
              "stale"
            ]
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "LoadReadback": {
        "description": "1.5 — RELECTURE du cycle PRÉCÉDENT : ce que le moteur a fait de la consigne de cette charge, qu'elle vienne du plan ou du rule-based (abstention, repli). Absente si la charge n'était pas au plan de ce cycle, ou si aucun cycle n'a été planifié (premier cycle, mode dégradé).",
        "type": "object",
        "properties": {
          "cycleAt": {
            "description": "Instant du cycle relu. Instant ISO 8601 AVEC son décalage.",
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "origin": {
            "description": "Qui a décidé : optimizer (la charge était nommée par le plan) ou rules (rule-based : sans plan, abstention, repli, charge indisponible).",
            "type": "string",
            "enum": [
              "optimizer",
              "rules"
            ]
          },
          "planId": {
            "description": "planId du plan appliqué, si origin = optimizer et qu'il en avait un.",
            "type": "string"
          },
          "decidedW": {
            "description": "Puissance DÉCIDÉE (W) : celle que demandait le plan, ou que le rule-based avait allouée — avant toute garde.",
            "type": "number",
            "minimum": 0
          },
          "decidedState": {
            "description": "État SG-Ready décidé.",
            "type": "integer",
            "minimum": 1,
            "maximum": 4
          },
          "appliedW": {
            "description": "Puissance APPLIQUÉE (W) : ce que l'adaptateur a posé, ou ce que la protection a laissé.",
            "type": "number",
            "minimum": 0
          },
          "appliedState": {
            "description": "État SG-Ready appliqué.",
            "type": "integer",
            "minimum": 0,
            "maximum": 4
          },
          "appliedA": {
            "description": "Borne : courant appliqué (A), 0 à l'arrêt.",
            "type": "number",
            "minimum": 0
          },
          "appliedPhases": {
            "description": "Borne : phases appliquées.",
            "type": "integer",
            "minimum": 1,
            "maximum": 3
          },
          "bounded": {
            "description": "Vrai si une garde du moteur a modifié la consigne décidée.",
            "type": "boolean"
          },
          "boundBy": {
            "description": "Quelle garde : overload (protection de surcharge), minSoc (plancher du SoC minimum, à la place de la demande du plan), drawCap (autorisation de soutirage), phaseLimit (limite de phase du branchement), lock (verrou de la charge), loadCeiling (plafond de cycle de la charge), adapter (arrondi ou bornes du mécanisme), blockLimit (durée maximale de blocage d'une PAC atteinte : rendue à l'état 2), peakBlockOff (blocage au prix fort refusé : l'interrupteur de la PAC est décoché, rendue à l'état 2). Absent si bounded est faux.",
            "type": "string",
            "enum": [
              "overload",
              "minSoc",
              "drawCap",
              "phaseLimit",
              "lock",
              "loadCeiling",
              "adapter",
              "blockLimit",
              "peakBlockOff"
            ]
          },
          "reasonCode": {
            "description": "Motif FINAL publié pour la charge (catalogue du moteur) — le code, jamais une phrase.",
            "type": "string"
          },
          "measurementSource": {
            "description": "Source de la mesure publiée (§5.3) ; none = rien ne mesure.",
            "type": "string",
            "enum": [
              "meter",
              "device",
              "none"
            ]
          },
          "measuredW": {
            "description": "Puissance MESURÉE (W) ; absente sous none.",
            "type": "number"
          },
          "divergent": {
            "description": "Le moteur juge que la mesure ne suit pas la commande (au-delà de sa tolérance et de la latence du mécanisme). Absent quand rien n'est commandé.",
            "type": "boolean"
          }
        },
        "required": [
          "cycleAt",
          "origin",
          "decidedW",
          "appliedW",
          "bounded",
          "measurementSource"
        ],
        "additionalProperties": false
      },
      "LoadWatts": {
        "description": "Charge pilotée en watts : combinaison de relais (relay-router) ou consigne continue (etmvariableload).",
        "type": "object",
        "properties": {
          "id": {
            "description": "Identifiant de la charge — clé des actions.",
            "type": "string",
            "minLength": 1
          },
          "label": {
            "description": "Nom lisible.",
            "type": "string"
          },
          "priority": {
            "description": "Rang effectif (1 = premier servi).",
            "type": "integer"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "learned": {
            "$ref": "#/components/schemas/LoadLearned"
          },
          "needs": {
            "$ref": "#/components/schemas/LoadNeeds"
          },
          "progress": {
            "$ref": "#/components/schemas/LoadProgress"
          },
          "readback": {
            "$ref": "#/components/schemas/LoadReadback"
          },
          "adapter": {
            "type": "string",
            "enum": [
              "relay-router",
              "etmvariableload"
            ]
          },
          "declared": {
            "type": "object",
            "properties": {
              "minPowerW": {
                "description": "0 = aucun plancher.",
                "type": "number"
              },
              "maxPowerW": {
                "type": "number"
              },
              "phase": {
                "description": "1.7 — phase du réseau sur laquelle la charge MONOPHASÉE est câblée, saisie par l'installateur. Absente = inconnue : garder le pire cas (toutes les monophasées sur la même phase).",
                "enum": [
                  "L1",
                  "L2",
                  "L3"
                ]
              },
              "powerRanges": {
                "description": "1.8 — les puissances atteignables (PowerRange). Absent si rien n'est déclaré (borne sans appareil). Toujours une liste de niveaux pour un relay-router et une PAC, deux plages (mono, tri) qui peuvent se chevaucher pour une borne commutable.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PowerRange"
                }
              }
            },
            "required": [
              "minPowerW",
              "maxPowerW"
            ],
            "additionalProperties": false
          },
          "telemetry": {
            "type": "object",
            "properties": {
              "currentPowerW": {
                "description": "Puissance courante (W) telle que l'adaptateur la publie.",
                "type": "number"
              },
              "available": {
                "description": "Gouverne l'ALLOCATION, pas la COMPTABILITÉ (§5.3).",
                "type": "boolean"
              },
              "measurement": {
                "$ref": "#/components/schemas/Measurement"
              },
              "lockMinPowerW": {
                "description": "Plancher imposé MAINTENANT par un verrou.",
                "type": "number"
              },
              "lockMaxPowerW": {
                "description": "Plafond imposé maintenant ; négatif = aucun plafond.",
                "type": "number"
              },
              "tank": {
                "description": "1.8 — le BALLON servi par ce chauffe-eau (LoadConfig.tank) : volume (L), température visée (°C) et mesurée par sa sonde (absente si la sonde ne mesure pas ce cycle). Avec la température, le besoin est la température visée avant needs.dailyDeadline : energyTargets en porte l'énergie (volume × 1,163 Wh/(L·K) × écart, source installer) à la place des kWh par jour. Absent sans ballon déclaré.",
                "type": "object",
                "properties": {
                  "volumeL": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "targetC": {
                    "type": "number"
                  },
                  "tempC": {
                    "type": "number"
                  }
                },
                "required": [
                  "volumeL",
                  "targetC"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "currentPowerW",
              "available",
              "lockMinPowerW",
              "lockMaxPowerW"
            ],
            "additionalProperties": false
          },
          "limits": {
            "type": "object",
            "properties": {
              "minOnS": {
                "type": "integer"
              },
              "minOffS": {
                "type": "integer"
              }
            },
            "required": [
              "minOnS",
              "minOffS"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "adapter",
          "label",
          "priority",
          "declared",
          "telemetry",
          "limits"
        ],
        "additionalProperties": false
      },
      "LoadEvCharger": {
        "description": "Borne. Une borne CONFIGURÉE dont l'appareil manque n'a ni declared, ni limits, ni pluggedIn/charging : ses zéros diraient « inconnu ».",
        "type": "object",
        "properties": {
          "id": {
            "description": "Identifiant de la charge — clé des actions.",
            "type": "string",
            "minLength": 1
          },
          "label": {
            "description": "Nom lisible.",
            "type": "string"
          },
          "priority": {
            "description": "Rang effectif (1 = premier servi).",
            "type": "integer"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "learned": {
            "$ref": "#/components/schemas/LoadLearned"
          },
          "needs": {
            "$ref": "#/components/schemas/LoadNeeds"
          },
          "progress": {
            "$ref": "#/components/schemas/LoadProgress"
          },
          "readback": {
            "$ref": "#/components/schemas/LoadReadback"
          },
          "adapter": {
            "const": "evcharger"
          },
          "declared": {
            "type": "object",
            "properties": {
              "minA": {
                "type": "number"
              },
              "maxA": {
                "type": "number"
              },
              "phases": {
                "description": "Phases que le moteur VISE ce cycle (règle de bascule, voiture), pas la plaque — sens gardé pour un optimiseur 1.0 à 1.6. La plaque : wiredPhases (1.7).",
                "type": "integer"
              },
              "wiredPhases": {
                "description": "1.7 — phases CÂBLÉES de la borne (plaque, installation), indépendamment de la voiture et de la règle. Absent si inconnu.",
                "enum": [
                  1,
                  3
                ]
              },
              "phaseSwitch": {
                "description": "1.7 — le matériel bascule 1 ↔ 3 (absent sinon). Ce que la séquence impose : arrêt de la charge tenu stopHoldS avant d'écrire les phases, puis settleS sans nouvelle bascule. Ce que ce cycle permet : telemetry.allowedPhases.",
                "type": "object",
                "properties": {
                  "phases": {
                    "description": "Phases que le matériel accepte.",
                    "type": "array",
                    "items": {
                      "enum": [
                        1,
                        3
                      ]
                    }
                  },
                  "stopHoldS": {
                    "description": "Arrêt vu par toutes les sources, tenu ce temps avant d'écrire les phases (s).",
                    "type": "integer",
                    "minimum": 0
                  },
                  "settleS": {
                    "description": "Après une bascule : aucune autre bascule, la commande n'est pas jugée (s).",
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "required": [
                  "phases",
                  "stopHoldS",
                  "settleS"
                ],
                "additionalProperties": false
              },
              "phase": {
                "description": "1.7 — phase du réseau d'une borne câblée en MONOPHASÉ (wiredPhases 1), saisie par l'installateur. Absente = inconnue (pire cas), et toujours absente d'une borne triphasée.",
                "enum": [
                  "L1",
                  "L2",
                  "L3"
                ]
              },
              "powerRanges": {
                "description": "1.8 — les puissances atteignables (PowerRange). Absent si rien n'est déclaré (borne sans appareil). Toujours une liste de niveaux pour un relay-router et une PAC, deux plages (mono, tri) qui peuvent se chevaucher pour une borne commutable.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PowerRange"
                }
              }
            },
            "required": [
              "minA",
              "maxA",
              "phases"
            ],
            "additionalProperties": false
          },
          "telemetry": {
            "type": "object",
            "properties": {
              "currentPowerW": {
                "description": "Puissance courante (W) telle que l'adaptateur la publie.",
                "type": "number"
              },
              "available": {
                "description": "Gouverne l'ALLOCATION, pas la COMPTABILITÉ (§5.3).",
                "type": "boolean"
              },
              "measurement": {
                "$ref": "#/components/schemas/Measurement"
              },
              "pluggedIn": {
                "type": "boolean"
              },
              "charging": {
                "type": "boolean"
              },
              "heldPhases": {
                "description": "1.7 — phases que la borne tient maintenant (relues pour une borne à bascule, comptées par le moteur sinon).",
                "enum": [
                  1,
                  3
                ]
              },
              "allowedPhases": {
                "description": "1.7 — les valeurs de phases qu'une action peut porter CE cycle : [1, 3] pour une borne qui bascule avec cette voiture hors séquence, fenêtre qui suit une bascule et espacement (sans 3 si la règle interdit le triphasé : délestage, limite de phase) ; sinon [heldPhases]. Une autre valeur est servie sur heldPhases (readback.boundBy : adapter).",
                "type": "array",
                "items": {
                  "enum": [
                    1,
                    3
                  ]
                },
                "minItems": 1
              },
              "carPhases": {
                "description": "1.7 — phases de la voiture, connues (publiées par la voiture assignée, ou mesurées par la borne) ; absent si inconnues.",
                "enum": [
                  1,
                  3
                ]
              },
              "sessionWh": {
                "description": "Absent si la borne ne compte pas sa session (LM-1009 C1).",
                "type": "number"
              },
              "vehicle": {
                "$ref": "#/components/schemas/Vehicle"
              }
            },
            "required": [
              "currentPowerW",
              "available"
            ],
            "additionalProperties": false
          },
          "limits": {
            "type": "object",
            "properties": {
              "chargingEnabledLockS": {
                "type": "integer"
              },
              "currentChangeLockS": {
                "type": "integer"
              }
            },
            "required": [
              "chargingEnabledLockS",
              "currentChangeLockS"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "adapter",
          "label",
          "priority",
          "telemetry"
        ],
        "additionalProperties": false
      },
      "LoadSgReady": {
        "description": "PAC SG-Ready : 4 états normés, kind state.",
        "type": "object",
        "properties": {
          "id": {
            "description": "Identifiant de la charge — clé des actions.",
            "type": "string",
            "minLength": 1
          },
          "label": {
            "description": "Nom lisible.",
            "type": "string"
          },
          "priority": {
            "description": "Rang effectif (1 = premier servi).",
            "type": "integer"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "learned": {
            "$ref": "#/components/schemas/LoadLearned"
          },
          "needs": {
            "$ref": "#/components/schemas/LoadNeeds"
          },
          "progress": {
            "$ref": "#/components/schemas/LoadProgress"
          },
          "readback": {
            "$ref": "#/components/schemas/LoadReadback"
          },
          "adapter": {
            "const": "sg-ready"
          },
          "declared": {
            "type": "object",
            "properties": {
              "states": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 4
                }
              },
              "estimatedPowerW": {
                "type": "object",
                "propertyNames": {
                  "pattern": "^[1-4]$"
                },
                "additionalProperties": {
                  "type": "number"
                }
              },
              "powerRanges": {
                "description": "1.8 — les puissances atteignables (PowerRange). Absent si rien n'est déclaré (borne sans appareil). Toujours une liste de niveaux pour un relay-router et une PAC, deux plages (mono, tri) qui peuvent se chevaucher pour une borne commutable.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PowerRange"
                }
              },
              "modes": {
                "description": "1.8 — la puissance de chaque état (mode) : apprise au compteur de la PAC (source learned, moyenne mesurée dans ce mode hors transitoire), sinon saisie (source declared). Jamais exacte : un mode est commandé, sa puissance en est l'effet. Classer les modes par powerW, jamais par leur numéro.",
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 4
                    },
                    "powerW": {
                      "type": "number",
                      "minimum": 0
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "learned",
                        "declared"
                      ]
                    },
                    "exact": {
                      "type": "boolean",
                      "const": false
                    }
                  },
                  "required": [
                    "state",
                    "powerW",
                    "source",
                    "exact"
                  ],
                  "additionalProperties": false
                }
              },
              "compressorBlock": {
                "description": "1.8 — vrai : l'état 1 (bloquée) est servi par le contact du COMPRESSEUR seul (régulation et circulateur tournent), les contacts SG restant sur l'état 2. Absent : l'état 1 est l'état SG 1 (toute la PAC).",
                "type": "boolean",
                "const": true
              }
            },
            "required": [
              "states",
              "estimatedPowerW"
            ],
            "additionalProperties": false
          },
          "telemetry": {
            "type": "object",
            "properties": {
              "currentPowerW": {
                "description": "Puissance courante (W) telle que l'adaptateur la publie.",
                "type": "number"
              },
              "available": {
                "description": "Gouverne l'ALLOCATION, pas la COMPTABILITÉ (§5.3).",
                "type": "boolean"
              },
              "measurement": {
                "$ref": "#/components/schemas/Measurement"
              },
              "state": {
                "description": "État commandé (1-4) ; 0 = non applicable.",
                "type": "integer",
                "minimum": 0,
                "maximum": 4
              },
              "minState": {
                "description": "Fenêtre d'états autorisée MAINTENANT par minStateHold.",
                "type": "integer"
              },
              "maxState": {
                "type": "integer"
              },
              "blockedS": {
                "description": "1.8 — durée déjà bloquée dans la période en cours (s) ; absente si la PAC n'a pas été bloquée.",
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "currentPowerW",
              "available",
              "state",
              "minState",
              "maxState"
            ],
            "additionalProperties": false
          },
          "limits": {
            "type": "object",
            "properties": {
              "minStateHoldS": {
                "type": "integer"
              },
              "maxBlockS": {
                "description": "1.8 — durée MAXIMALE de blocage (état 1) par période chère (s) : au-delà, le moteur rend la main (état 2, HEAT_PUMP_BLOCK_LIMIT, readback.boundBy : blockLimit), même si le plan redemande le blocage. Hors prix fort, le compte repart après autant de temps libre.",
                "type": "integer",
                "minimum": 0
              },
              "blockAtExpensivePrice": {
                "description": "1.8 — l'interrupteur « bloquer au prix fort » de la PAC (défaut vrai). Vrai : le moteur seul bloque la PAC au prix fort (HEAT_PUMP_PEAK_BLOCK), au plus maxBlockS ; un plan peut le faire aussi. Faux : un état 1 demandé AU PRIX FORT est refusé par la garde du moteur (état 2, HEAT_PUMP_PEAK_BLOCK_REFUSED, readback.boundBy : peakBlockOff) ; hors prix fort, rien ne change.",
                "type": "boolean"
              }
            },
            "required": [
              "minStateHoldS"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "adapter",
          "label",
          "priority",
          "declared",
          "telemetry",
          "limits"
        ],
        "additionalProperties": false
      },
      "Load": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/LoadWatts"
          },
          {
            "$ref": "#/components/schemas/LoadEvCharger"
          },
          {
            "$ref": "#/components/schemas/LoadSgReady"
          }
        ],
        "description": "Une charge arbitrée (§5.3) — la forme dépend du mécanisme (adapter)."
      },
      "ReasonParams": {
        "description": "Paramètres du motif : valeurs nombre, booléen ou code [A-Za-z]+ ; clés admises par code : x-etm-reason-params. Toute autre clé est SUPPRIMÉE avant l'app (filtrée, pas refusée). gridW (ECO_FLOOR_GRID, PRICE_SLOT, EV_DEADLINE — 1.7 pour les deux derniers) : la part RÉSEAU de l'action (W), telle que l'optimiseur la planifie ; le moteur la valide (nombre, 0 ≤ gridW ≤ puissance de l'action) et la republie, il ne la calcule jamais — hors bornes, elle est supprimée.",
        "type": [
          "object",
          "null"
        ],
        "additionalProperties": {
          "type": [
            "number",
            "boolean",
            "string"
          ],
          "pattern": "^[A-Za-z]+$"
        }
      },
      "SetpointAction": {
        "type": "object",
        "properties": {
          "loadId": {
            "description": "Charge visée : connue du contexte (règle unknown-load), une fois par créneau (duplicate-load).",
            "type": "string",
            "minLength": 1
          },
          "reason": {
            "description": "Texte français, OBLIGATOIRE et non vide (règle missing-reason). Traces et journal seulement, jamais vers l'app.",
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "reasonCode": {
            "$ref": "#/components/schemas/ReasonCode"
          },
          "reasonParams": {
            "$ref": "#/components/schemas/ReasonParams"
          },
          "force": {
            "description": "INTERDIT sur le fil (§6) : ignoré, signalé une fois."
          },
          "kind": {
            "const": "setpoint"
          },
          "powerW": {
            "description": "Consigne en watts (relay-router, etmvariableload ; ou borne).",
            "type": "number",
            "minimum": 0
          },
          "currentA": {
            "description": "Borne : courant (0 = suspendre).",
            "type": "number",
            "minimum": 0
          },
          "phases": {
            "description": "Borne : phases visées ; absent = inchangé.",
            "enum": [
              1,
              3
            ]
          }
        },
        "required": [
          "loadId",
          "kind",
          "reason"
        ],
        "additionalProperties": true,
        "anyOf": [
          {
            "required": [
              "powerW"
            ]
          },
          {
            "required": [
              "currentA"
            ]
          }
        ]
      },
      "StateAction": {
        "type": "object",
        "properties": {
          "loadId": {
            "description": "Charge visée : connue du contexte (règle unknown-load), une fois par créneau (duplicate-load).",
            "type": "string",
            "minLength": 1
          },
          "reason": {
            "description": "Texte français, OBLIGATOIRE et non vide (règle missing-reason). Traces et journal seulement, jamais vers l'app.",
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "reasonCode": {
            "$ref": "#/components/schemas/ReasonCode"
          },
          "reasonParams": {
            "$ref": "#/components/schemas/ReasonParams"
          },
          "force": {
            "description": "INTERDIT sur le fil (§6) : ignoré, signalé une fois."
          },
          "kind": {
            "const": "state"
          },
          "state": {
            "description": "1 = verrouillage, 2 = normal, 3 = recommandation, 4 = forcé.",
            "type": "integer",
            "minimum": 1,
            "maximum": 4
          }
        },
        "required": [
          "loadId",
          "kind",
          "reason",
          "state"
        ],
        "additionalProperties": true
      },
      "ConstraintAction": {
        "description": "RÉSERVÉ (annexe F) : forme décrite, toujours refusée (kind-mismatch).",
        "type": "object",
        "properties": {
          "loadId": {
            "description": "Charge visée : connue du contexte (règle unknown-load), une fois par créneau (duplicate-load).",
            "type": "string",
            "minLength": 1
          },
          "reason": {
            "description": "Texte français, OBLIGATOIRE et non vide (règle missing-reason). Traces et journal seulement, jamais vers l'app.",
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "reasonCode": {
            "$ref": "#/components/schemas/ReasonCode"
          },
          "reasonParams": {
            "$ref": "#/components/schemas/ReasonParams"
          },
          "force": {
            "description": "INTERDIT sur le fil (§6) : ignoré, signalé une fois."
          },
          "kind": {
            "const": "constraint"
          },
          "charge": {
            "enum": [
              "allow",
              "forbid"
            ]
          },
          "discharge": {
            "enum": [
              "allow",
              "forbid"
            ]
          }
        },
        "required": [
          "loadId",
          "kind",
          "reason"
        ],
        "additionalProperties": true
      },
      "Action": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/SetpointAction"
          },
          {
            "$ref": "#/components/schemas/StateAction"
          },
          {
            "$ref": "#/components/schemas/ConstraintAction"
          }
        ]
      },
      "Expected": {
        "description": "Trajectoire prévue : affichage et mesure d'écart, JAMAIS pour commander.",
        "type": "object",
        "properties": {
          "gridImportW": {
            "type": "number"
          },
          "gridExportW": {
            "type": "number"
          },
          "batterySocPercent": {
            "description": "RÉSERVÉ (annexe F) : ignoré."
          }
        },
        "required": [],
        "additionalProperties": true
      },
      "Slot": {
        "type": "object",
        "properties": {
          "from": {
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.",
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "to": {
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.",
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "actions": {
            "description": "Absent ou null = aucune action.",
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Action"
            }
          },
          "expected": {
            "$ref": "#/components/schemas/Expected"
          }
        },
        "required": [
          "from",
          "to"
        ],
        "additionalProperties": true
      },
      "Diagnostics": {
        "description": "Informatif : mode installateur et traces.",
        "type": "object",
        "properties": {
          "solver": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "optimal",
              "feasible",
              "best-so-far",
              "infeasible-relaxed"
            ]
          },
          "gapPercent": {
            "type": "number"
          },
          "computeMs": {
            "type": "number",
            "minimum": 0
          },
          "inputsUsed": {
            "type": "object",
            "properties": {
              "pv": {
                "type": "string",
                "enum": [
                  "physics",
                  "hybrid",
                  "none"
                ]
              }
            },
            "required": [],
            "additionalProperties": true
          }
        },
        "required": [],
        "additionalProperties": true
      },
      "Plan": {
        "description": "Plan par créneaux (§6).",
        "type": "object",
        "properties": {
          "abstain": {
            "const": false
          },
          "planId": {
            "type": "string"
          },
          "strategy": {
            "description": "Chaîne libre, informative.",
            "type": "string"
          },
          "computedAt": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$",
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée."
          },
          "validUntil": {
            "description": "Instant ISO 8601 AVEC son décalage (Z ou ±hh:mm) — une heure murale nue est refusée.",
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2}(\\.[0-9]+)?)?(Z|[+-][0-9]{2}:[0-9]{2})$"
          },
          "slots": {
            "description": "[] = abstention (empty-plan). Seul le créneau couvrant maintenant est exécuté.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Slot"
            }
          },
          "diagnostics": {
            "$ref": "#/components/schemas/Diagnostics"
          }
        },
        "required": [
          "slots"
        ],
        "additionalProperties": true
      },
      "Abstention": {
        "description": "« Pas de plan maintenant » (§7) : repli pour ce cycle, pas un échec.",
        "type": "object",
        "properties": {
          "abstain": {
            "const": true
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "abstain"
        ],
        "additionalProperties": true
      },
      "GetPlanResult": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/Abstention"
          },
          {
            "$ref": "#/components/schemas/Plan"
          }
        ]
      },
      "InvalidContextData": {
        "description": "error.data de la réponse -32602 à GetPlan (§7, 1.3). Exigé d'un optimiseur qui s'annonce 1.3 ou plus ; un optimiseur 1.2 peut répondre un autre data, le moteur ne le lit pas. Aucune valeur reçue n'y figure, dans aucun champ : la forme est fermée, le chemin suit un motif, la nature est un code d'une liste fermée.",
        "type": "object",
        "properties": {
          "problems": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/ContextProblem"
            },
            "description": "Les problèmes trouvés, de 1 à 50 ; s'il y en a davantage, les 50 premiers, et truncated."
          },
          "truncated": {
            "const": true,
            "description": "Présent, et vrai, seulement si des problèmes ont été omis (problems en compte alors 50) ; absent sinon."
          }
        },
        "required": [
          "problems"
        ],
        "additionalProperties": false,
        "x-etm-closed-why": "forme de l'optimiseur fermée à dessein : aucune valeur reçue ne doit pouvoir s'y glisser"
      },
      "ContextProblem": {
        "description": "Un problème du contexte GetPlan (1.3) : où, et de quelle nature — jamais la valeur reçue.",
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "pattern": "^params(\\.[A-Za-z0-9_]+|\\[[0-9]+\\])*$",
            "description": "Chemin du champ fautif depuis params : noms séparés par des points, indices de liste entre crochets (params.forecast.pv[3].from). Champ absent : son chemin attendu."
          },
          "problem": {
            "$ref": "#/components/schemas/ContextProblemCode"
          }
        },
        "required": [
          "path",
          "problem"
        ],
        "additionalProperties": false,
        "x-etm-closed-why": "forme de l'optimiseur fermée à dessein : aucune valeur reçue ne doit pouvoir s'y glisser"
      },
      "ContextProblemCode": {
        "description": "Nature d'un problème du contexte (1.3), liste fermée : missing (obligatoire absent), type (type faux), range (hors bornes), format (chaîne mal formée : instant, durée…), enum (valeur hors liste), constraint (règle entre champs, ordre des créneaux…). Un code inconnu est ignoré par le moteur (§9).",
        "type": "string",
        "enum": [
          "missing",
          "type",
          "range",
          "format",
          "enum",
          "constraint"
        ]
      },
      "PowerRange": {
        "description": "1.8 — une plage de puissances ATTEIGNABLES, déduite par le moteur de la configuration (relais et combinaisons, paliers, plancher et plafond, courants publiés et phases de la borne, puissance d'un mode de PAC) : une liste de niveaux OU un continu. 0 W (arrêt) est toujours permis en plus, sauf verrou du moment (telemetry). Les verrous du cycle, la limite de phase et les phases permises ce cycle (allowedPhases) n'y sont PAS appliqués. Une consigne hors plage est servie au niveau atteignable INFÉRIEUR, jamais au-dessus (readback.boundBy : adapter).",
        "oneOf": [
          {
            "description": "Paliers : relais (combinaisons ou un seul à la fois), etmvariableload fixed, modes d'une PAC.",
            "type": "object",
            "properties": {
              "kind": {
                "description": "setpoint : la charge tire la valeur demandée ; cap : elle tire AU PLUS la valeur (réservé : entrée 0-10 V d'une PAC) — jamais comptée comme une consommation sûre.",
                "type": "string",
                "enum": [
                  "setpoint",
                  "cap"
                ]
              },
              "exact": {
                "description": "Vrai pour un relais ou une borne ; faux pour une puissance estimée ou apprise (mode de PAC).",
                "type": "boolean"
              },
              "phases": {
                "description": "Phases tirées : 1 ou 3. Absent si inconnu (charge en watts sans phase saisie). La phase d'une charge monophasée : declared.phase.",
                "enum": [
                  1,
                  3
                ]
              },
              "levelsW": {
                "description": "Niveaux atteignables (W), croissants, sans 0.",
                "type": "array",
                "items": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "minItems": 1
              }
            },
            "required": [
              "kind",
              "exact",
              "levelsW"
            ],
            "additionalProperties": false
          },
          {
            "description": "Continu : gradateur (etmvariableload dynamic), borne (au pas d'un ampère).",
            "type": "object",
            "properties": {
              "kind": {
                "description": "setpoint : la charge tire la valeur demandée ; cap : elle tire AU PLUS la valeur (réservé : entrée 0-10 V d'une PAC) — jamais comptée comme une consommation sûre.",
                "type": "string",
                "enum": [
                  "setpoint",
                  "cap"
                ]
              },
              "exact": {
                "description": "Vrai pour un relais ou une borne ; faux pour une puissance estimée ou apprise (mode de PAC).",
                "type": "boolean"
              },
              "phases": {
                "description": "Phases tirées : 1 ou 3. Absent si inconnu (charge en watts sans phase saisie). La phase d'une charge monophasée : declared.phase.",
                "enum": [
                  1,
                  3
                ]
              },
              "minW": {
                "description": "Plus petite puissance non nulle (W) ; 0 = aucun plancher.",
                "type": "number",
                "minimum": 0
              },
              "maxW": {
                "description": "Plus grande puissance (W).",
                "type": "number",
                "exclusiveMinimum": 0
              },
              "stepW": {
                "description": "Pas (W) — 230 W (mono) ou 690 W (tri) pour une borne, un ampère par phase. Absent : au watt près.",
                "type": "number",
                "exclusiveMinimum": 0
              }
            },
            "required": [
              "kind",
              "exact",
              "minW",
              "maxW"
            ],
            "additionalProperties": false
          }
        ]
      }
    }
  },
  "x-etm-transport": {
    "description": "Ce qu'OpenRPC ne dit pas du fil (§2-§4).",
    "schemes": [
      "unix",
      "tcp"
    ],
    "defaultEndpoint": "unix:///run/powersync/optimizer.sock",
    "jsonrpc": "2.0",
    "framing": "ndjson",
    "encoding": "utf-8",
    "roles": {
      "client": "engine",
      "server": "optimizer"
    },
    "maxLineBytes": 1048576,
    "maxLineBytesScope": "les deux sens (1.2) : octets de la ligne, '\\n' non compté. Reçue trop longue : côté optimiseur -32600 (id null), connexion conservée ; côté moteur, ligne écartée (line-too-long), connexion conservée. Émise : le moteur n'émet jamais de ligne de plus de maxLineBytes ; une requête trop longue n'est pas envoyée et compte comme un échec (request-too-long, §7), connexion conservée.",
    "batches": "interdits dans les deux sens (1.2) : un message JSON-RPC, un objet, par ligne. Un lot reçu : côté optimiseur -32600 (id null), aucun de ses messages traité ; côté moteur, ligne écartée (invalid-json), connexion conservée.",
    "handshakeTimeoutS": 5,
    "requestTimeoutS": 10,
    "backoffS": {
      "initial": 1,
      "max": 60,
      "factor": 2
    },
    "requestsInFlight": 1,
    "ids": "entiers croissants sur toute la vie du client, à travers les reconnexions",
    "lineErrors": "ligne non JSON, sans id, id jamais émis, ligne > maxLineBytes : comptée, connexion CONSERVÉE (côté moteur ; côté optimiseur : x-etm-message-errors)",
    "tokenMasking": "toute occurrence du token dans un message reçu est remplacée par « [token masqué] » dès l'analyse",
    "runtimeDirectory": "/run/powersync appartient au paquet de l'OPTIMISEUR (RuntimeDirectory=powersync de son unité, groupe powersync) (1.2). Le moteur ne le crée ni ne le suppose : sans optimiseur, il n'en a pas besoin."
  },
  "x-etm-message-errors": {
    "description": "Ce que l'OPTIMISEUR répond à un message qu'il ne peut pas traiter, quelle que soit la méthode (1.2). Connexion conservée dans tous les cas. Le moteur n'émet que des objets, un par ligne, des méthodes Handshake et GetPlan : il n'en provoque aucune — pas même la ligne trop longue, qu'il n'émet jamais (§2). Reçue par le moteur, une réponse error à id null est une ligne écartée (missing-id), connexion conservée. Toute autre erreur : un code JSON-RPC 2.0 standard.",
    "items": [
      {
        "code": -32700,
        "message": "erreur d'analyse",
        "data": "Ligne qui n'est pas du JSON (ou pas de l'UTF-8). Réponse à id null. Code standard JSON-RPC 2.0.",
        "x-etm-connection": "conservée"
      },
      {
        "code": -32600,
        "message": "lot interdit",
        "data": "Ligne qui est un lot JSON-RPC ([…]) (1.2). Une seule réponse, à id null ; aucun message du lot n'est traité.",
        "x-etm-connection": "conservée"
      },
      {
        "code": -32600,
        "message": "ligne trop longue",
        "data": "Ligne de plus de maxLineBytes octets, '\\n' non compté (1.2). Jetée sans être analysée ni gardée en mémoire ; réponse à id null.",
        "x-etm-connection": "conservée"
      },
      {
        "code": -32601,
        "message": "méthode inconnue",
        "data": "Requête (avec id) d'une méthode que l'optimiseur ne sert pas — dont UpdateLearned, qui ne va que de l'optimiseur au moteur (1.2). Une notification (sans id) : ignorée, sans réponse.",
        "x-etm-connection": "conservée"
      }
    ]
  },
  "x-etm-error-message": {
    "description": "error.message d'une réponse error de l'optimiseur, toute méthode, tout code (1.4, décision du 2026-10-23) : un texte FIXE — le message de methods[].errors ou de x-etm-message-errors —, JAMAIS composé avec une valeur reçue (comme error.data depuis 1.2). Exigé d'un optimiseur qui s'annonce noEchoRequiredFrom ou plus ; averti en deçà. Le moteur ne lit pas le message : il journalise le code seul.",
    "noEchoRequiredFrom": "1.4"
  },
  "x-etm-fallback-machine": {
    "description": "Machine de repli §7 (OptimizerStatus) : heartbeat implicite — une réponse valide à GetPlan = optimiseur vivant. Les échecs se comptent PAR REQUÊTE.",
    "failuresBeforeDead": 2,
    "rows": [
      {
        "situation": "réponse plan valide",
        "optimizerAlive": "true",
        "activeStrategy": "optimizer"
      },
      {
        "situation": "abstain, plan vide, aucun créneau courant",
        "optimizerAlive": "inchangé",
        "activeStrategy": "rules (ce cycle)"
      },
      {
        "situation": "plan expiré (validUntil dépassé)",
        "optimizerAlive": "inchangé",
        "activeStrategy": "rules jusqu'au prochain plan valide"
      },
      {
        "situation": "timeout / erreur / plan invalide sur deux requêtes consécutives",
        "optimizerAlive": "false",
        "activeStrategy": "rules"
      },
      {
        "situation": "socket absent / fermé / handshake refusé",
        "optimizerAlive": "false",
        "activeStrategy": "rules"
      },
      {
        "situation": "aucun endpoint configuré",
        "optimizerAlive": "false",
        "activeStrategy": "rules"
      },
      {
        "situation": "mode dégradé L2 (compteur muet > 90 s)",
        "optimizerAlive": "inchangé",
        "activeStrategy": "none"
      }
    ]
  },
  "x-etm-semantic-rules": {
    "description": "Ce que le moteur refuse EN PLUS de la forme, dans l'ordre de ses contrôles (OptimizerPlan::valider, OptimizerClient::handleHandshakeReply). name = code du verdict. issue : abstention (repli ce cycle, pas un échec), expired, invalid (plan refusé en entier, compté comme échec), connection-refused (handshake). needs : ce qu'il faut connaître en plus de la réponse (la requête, le handshake).",
    "rules": [
      {
        "name": "abstain",
        "method": "GetPlan",
        "issue": "abstention",
        "fallbackCode": "abstain",
        "countsAsFailure": false,
        "needs": [],
        "schemaAlsoCatches": false,
        "description": "result.abstain vaut true."
      },
      {
        "name": "malformed-plan",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "malformed-plan",
        "countsAsFailure": true,
        "needs": [],
        "schemaAlsoCatches": true,
        "description": "slots absent ou non liste ; un créneau qui n'est pas un objet ; actions non liste.",
        "lastErrorCode": "malformed-plan"
      },
      {
        "name": "empty-plan",
        "method": "GetPlan",
        "issue": "abstention",
        "fallbackCode": "empty-plan",
        "countsAsFailure": false,
        "needs": [],
        "schemaAlsoCatches": false,
        "description": "slots est une liste vide."
      },
      {
        "name": "bad-time",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "bad-time",
        "countsAsFailure": true,
        "needs": [],
        "schemaAlsoCatches": true,
        "description": "from/to illisibles ou sans décalage, ou from ≥ to ; validUntil illisible ou sans décalage.",
        "lastErrorCode": "bad-time"
      },
      {
        "name": "slots-unordered",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "slots-unordered",
        "countsAsFailure": true,
        "needs": [],
        "schemaAlsoCatches": false,
        "description": "un créneau commence avant la fin du précédent.",
        "lastErrorCode": "slots-unordered"
      },
      {
        "name": "malformed-action",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "malformed-action",
        "countsAsFailure": true,
        "needs": [],
        "schemaAlsoCatches": true,
        "description": "action qui n'est pas un objet, ou sans loadId (chaîne non vide).",
        "lastErrorCode": "malformed-action"
      },
      {
        "name": "unknown-load",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "unknown-load",
        "countsAsFailure": true,
        "needs": [
          "request"
        ],
        "schemaAlsoCatches": false,
        "description": "loadId absent des loads[] de la requête.",
        "lastErrorCode": "unknown-load"
      },
      {
        "name": "unknown-kind",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "unknown-kind",
        "countsAsFailure": true,
        "needs": [],
        "schemaAlsoCatches": true,
        "description": "kind hors ActionKind.",
        "lastErrorCode": "unknown-kind"
      },
      {
        "name": "kind-mismatch",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "kind-mismatch",
        "countsAsFailure": true,
        "needs": [
          "request"
        ],
        "schemaAlsoCatches": false,
        "description": "kind différent de celui du mécanisme de la charge (setpoint : evcharger, relay-router, etmvariableload ; state : sg-ready ; constraint : aucun).",
        "lastErrorCode": "kind-mismatch"
      },
      {
        "name": "kind-not-announced",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "kind-not-announced",
        "countsAsFailure": true,
        "needs": [
          "handshake"
        ],
        "schemaAlsoCatches": false,
        "description": "capabilities.kinds annoncé au handshake et kind absent de la liste.",
        "lastErrorCode": "kind-not-announced"
      },
      {
        "name": "missing-reason",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "missing-reason",
        "countsAsFailure": true,
        "needs": [],
        "schemaAlsoCatches": true,
        "description": "reason absent, non textuel, ou vide une fois les caractères de contrôle retirés.",
        "lastErrorCode": "missing-reason"
      },
      {
        "name": "bad-value",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "bad-value",
        "countsAsFailure": true,
        "needs": [
          "request"
        ],
        "schemaAlsoCatches": true,
        "description": "state absent ou hors 1-4 ; borne : currentA/powerW absents ou négatifs, phases hors {1, 3} ; charge en watts : powerW absent ou négatif.",
        "lastErrorCode": "bad-value"
      },
      {
        "name": "duplicate-load",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "duplicate-load",
        "countsAsFailure": true,
        "needs": [],
        "schemaAlsoCatches": false,
        "description": "deux actions pour la même charge dans un créneau.",
        "lastErrorCode": "duplicate-load"
      },
      {
        "name": "expired",
        "method": "GetPlan",
        "issue": "expired",
        "fallbackCode": "expired",
        "countsAsFailure": false,
        "needs": [
          "request"
        ],
        "schemaAlsoCatches": false,
        "description": "validUntil ≤ timestamp de la requête."
      },
      {
        "name": "no-current-slot",
        "method": "GetPlan",
        "issue": "abstention",
        "fallbackCode": "no-current-slot",
        "countsAsFailure": false,
        "needs": [
          "request"
        ],
        "schemaAlsoCatches": false,
        "description": "aucun créneau ne couvre le timestamp de la requête."
      },
      {
        "name": "incomplete-slot",
        "method": "GetPlan",
        "issue": "invalid",
        "fallbackCode": "incomplete-slot",
        "countsAsFailure": true,
        "needs": [
          "request"
        ],
        "schemaAlsoCatches": false,
        "description": "une charge available de la requête n'a pas d'action dans le créneau courant (décision Q1).",
        "lastErrorCode": "incomplete-slot"
      },
      {
        "name": "handshake-refused",
        "method": "Handshake",
        "issue": "connection-refused",
        "fallbackCode": "no-plan",
        "lastErrorCode": "handshake-refused",
        "countsAsFailure": false,
        "needs": [],
        "schemaAlsoCatches": false,
        "description": "réponse error, quel que soit son code (token refusé : -32001, jugé d'abord ; majeure incompatible : -32602, Handshake.errors) → le moteur ferme, nouvelle tentative au backoff."
      },
      {
        "name": "invalid-handshake",
        "method": "Handshake",
        "issue": "connection-refused",
        "fallbackCode": "no-plan",
        "lastErrorCode": "invalid-handshake",
        "countsAsFailure": false,
        "needs": [],
        "schemaAlsoCatches": true,
        "description": "result non objet, protocolVersion absent ou vide, capabilities présent et non objet."
      },
      {
        "name": "major-mismatch",
        "method": "Handshake",
        "issue": "connection-refused",
        "fallbackCode": "no-plan",
        "lastErrorCode": "major-mismatch",
        "countsAsFailure": false,
        "needs": [],
        "schemaAlsoCatches": false,
        "description": "MAJEURE de protocolVersion (ce qui précède le premier point) différente de celle du moteur."
      }
    ]
  },
  "x-etm-tolerances": {
    "description": "Ce que le moteur ACCEPTE au-delà du schéma — un optimiseur conforme ne s'en sert pas.",
    "items": [
      "reasonCode absent ou hors ReasonCode : action acceptée, motif transmis sous OPTIMIZER_DECISION sans paramètres.",
      "reasonParams : clé non admise pour le code (x-etm-reason-params) ou valeur refusée : clé supprimée, action acceptée.",
      "planId, strategy : lus comme chaînes quel que soit leur type ; computedAt illisible : ignoré.",
      "diagnostics, expected : non objets ignorés ; valeurs inconnues filtrées avant l'app.",
      "abstain : toute valeur « vraie » au sens de QVariant::toBool (true, chaîne non vide autre que « false »/« 0 », nombre non nul).",
      "champs inconnus (params et result) : ignorés (§9) ; force et champs réservés (annexe F) : ignorés et signalés une fois.",
      "state : 3.0 accepté comme 3 (entier au sens JSON Schema).",
      "error.data d'une réponse error (1.3) : jamais lu — un code problem inconnu, un data d'une autre forme (optimiseur 1.2) ou absent ne changent rien : l'erreur reste un échec rpc-error.",
      "error.message (1.4) : jamais lu ni journalisé par le moteur (le code seul) — un message qui recopierait une valeur reçue ne change rien côté moteur ; c'est un écart de l'optimiseur, jugé par le validateur et la conformité."
    ]
  },
  "x-etm-reason-params": {
    "BELOW_MIN_POWER": [
      "budgetW",
      "minPowerW",
      "state"
    ],
    "ECO_FLOOR_GRID": [
      "gridW",
      "atMaximum",
      "remainingWh",
      "targetWh",
      "remainingS",
      "regime",
      "minAlwaysW",
      "boundBy"
    ],
    "EV_DEADLINE": [
      "gridW"
    ],
    "OPTIMIZER_DECISION": [],
    "PRICE_SLOT": [
      "priceCtkWh",
      "setpointW",
      "gridW"
    ],
    "SG_FORCED": [
      "budgetW",
      "estimatedW"
    ],
    "SG_NORMAL": [
      "budgetW"
    ],
    "SG_RECOMMENDED": [
      "budgetW",
      "estimatedW"
    ],
    "SURPLUS_INSUFFICIENT": [
      "budgetW"
    ],
    "SURPLUS_SETPOINT": [
      "budgetW",
      "setpointW",
      "stepped"
    ],
    "TARGET_NOT_MET": [
      "missingWh",
      "socAtDeparturePercent"
    ]
  },
  "x-etm-generated": {
    "description": "Listes fermées RÉGÉNÉRÉES depuis le code (tools/etm-powersync-gen-protocol-doc --enums-from) ; la suite etm-powersync-protocolschema échoue si le code et le schéma divergent.",
    "items": [
      {
        "pointer": "/info/version",
        "from": "OptimizerProtocol::ProtocolVersion"
      },
      {
        "pointer": "/components/schemas/ProtocolVersion/const",
        "from": "OptimizerProtocol::ProtocolVersion"
      },
      {
        "pointer": "/components/schemas/Trigger/enum",
        "from": "SocketScheduler::knownTriggers()"
      },
      {
        "pointer": "/components/schemas/Domain/enum",
        "from": "LoadConfig::knownDomains()"
      },
      {
        "pointer": "/components/schemas/ActionKind/enum",
        "from": "OptimizerPlan::kinds()"
      },
      {
        "pointer": "/components/schemas/ReasonCode/enum",
        "from": "DecisionCode::optimizerEmittableCodes()"
      },
      {
        "pointer": "/x-etm-reason-params",
        "from": "DecisionCode::optimizerParamKeys()"
      },
      {
        "pointer": "/components/schemas/PriceInclude/enum",
        "from": "TariffConfig::includes()"
      },
      {
        "pointer": "/components/schemas/FallbackCode/enum",
        "from": "SocketScheduler::knownFallbackCodes()"
      },
      {
        "pointer": "/components/schemas/LastErrorCode/enum",
        "from": "SocketScheduler::knownLastErrorCodes()"
      }
    ]
  }
}
