docs(traces): INTERFACE.md (réglage, RPC, format, fichiers, plafond), protocole annexe D (brief 4 T6)

Annexe D : défaut désactivé, nom des fichiers, rotation locale, plafond, appariement
requête → réponse (la ligne N attend la réponse à la requête N), no-response, jamais le token ;
le rejeu est fait par tools/etm-powersync-trace-replay (et non plus « hems-sim »).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Patrick Schurig 2026-10-17 12:12:25 +02:00
parent 64a864bfaa
commit 6c44a4e091

View File

@ -568,10 +568,14 @@ Pas de poids, pas de pourcentages : un ordre, des besoins, des exceptions expliq
But : comparer des optimiseurs **sur les mêmes entrées** et rejouer un incident.
- Option plugin `optimizerTrace` (défaut : désactivée en production, activée sur banc).
- Fichiers NDJSON locaux, rotation par jour, rétention configurable (défaut 14 jours), sous
le répertoire de stockage du moteur (`NymeaSettings::storagePath()`).
- Une ligne par cycle :
- Option plugin `optimizerTrace` (défaut : **désactivée** ; à activer sur banc), réglée par
`NymeaEnergy.SetOptimizerTrace` (`INTERFACE.md`, « Traces de décision »).
- Fichiers NDJSON locaux `etm-powersync-optimizer-trace-AAAA-MM-JJ.ndjson`, rotation à minuit
heure locale, rétention configurable (défaut 14 jours), plafond par fichier journalier
(défaut 64 Mio), sous le répertoire de stockage du moteur (`NymeaSettings::storagePath()`).
Écriture asynchrone : une trace en échec ne bloque rien et ne change aucune décision.
- Une ligne par cycle, **y compris sous le rule-based** (sa réponse est alors le plan du
rule-based, `strategy: "rules"`) et en mode dégradé L2 (`strategy: "none"`, sans requête) :
```json
{"t":"2026-10-12T13:42:00+02:00","request":{ "...GetPlan params..." },
@ -579,8 +583,15 @@ But : comparer des optimiseurs **sur les mêmes entrées** et rejouer un inciden
"powerW":1200,"clamped":false}],"strategy":"optimizer","latencyMs":12}
```
- **Rejeu** : hems-sim relit `request`, l'envoie à un optimiseur candidat, compare
`response` + `diagnostics`.
- `request` : les params `GetPlan` envoyés (ou qui l'auraient été) ; `response` : ce qui a
répondu à **cette** requête — `result` brut, ou `error.code` (`no-response` si elle a été
remplacée sans réponse) ; `executed` : actions appliquées au cycle ; `latencyMs` : optimiseur
seulement. La réponse à la requête N sert au cycle N+1 : la ligne N l'attend.
- Jamais le token (il ne voyage que dans le handshake ; recopié par une réponse, il est masqué).
- **Rejeu** : `tools/etm-powersync-trace-replay` relit `request`, l'envoie à un optimiseur
candidat (`unix://` par défaut, `tcp://` accepté), écrit les réponses à côté de la trace et
résume : taux d'abstention, `computeMs` médian et max, cycles dont les actions du créneau
courant diffèrent du plan enregistré.
- Les traces restent sur le site. Export manuel par l'installateur uniquement.
## Annexe E — Optimiseur de référence