From f8333f42f6c12251cbb317fb60345de589e4b2d6 Mon Sep 17 00:00:00 2001 From: Patrick Schurig Date: Sat, 17 Oct 2026 13:28:34 +0200 Subject: [PATCH] =?UTF-8?q?docs(optimiseur):=20annexe=20E=20=E2=80=94=20ch?= =?UTF-8?q?emin,=20p=C3=A9rim=C3=A8tre=20et=20codes=20de=20l'optimiseur=20?= =?UTF-8?q?de=20r=C3=A9f=C3=A9rence=20(brief=204=20T7)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit tools/ref-optimizer → tools/etm-powersync-ref-optimizer ; ce qu'il reproduit (passe confort) et ce que le contexte 1.1 ne lui permet pas de reproduire ; codes émissibles seulement. tools/README.md : renvoi vers son README, règle de comparaison d'une action state. Co-Authored-By: Claude Opus 5.5 --- docs/OPTIMIZER_PROTOCOL.md | 18 +++++++++++++++--- tools/README.md | 7 ++++++- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/OPTIMIZER_PROTOCOL.md b/docs/OPTIMIZER_PROTOCOL.md index 230d98c..cf15fc0 100644 --- a/docs/OPTIMIZER_PROTOCOL.md +++ b/docs/OPTIMIZER_PROTOCOL.md @@ -596,9 +596,21 @@ But : comparer des optimiseurs **sur les mêmes entrées** et rejouer un inciden ## Annexe E — Optimiseur de référence -`tools/ref-optimizer/` : serveur Python minimal (bibliothèque standard seule) conforme 1.1, -répondant un plan à un créneau qui reproduit le waterfall rule-based. Usages : test de bout -en bout du `SocketScheduler` ; point de comparaison du banc ; exemple communautaire. +`tools/etm-powersync-ref-optimizer/` : serveur Python minimal (bibliothèque standard seule) +conforme 1.1, `unix:///run/powersync/optimizer.sock` par défaut, `tcp://` accepté ; répondant un +plan à un créneau qui reproduit le waterfall rule-based. Usages : test de bout en bout du +`SocketScheduler` (suite `etm-powersync-refoptimizer`) ; point de comparaison du banc ; exemple +communautaire. Mode d'emploi et modes d'injection de défauts : son `README.md`. + +- Il ne lit **que** le contexte `GetPlan` (aucune connexion sortante, aucun fichier hors le token). +- Il reproduit la **passe confort** : tri (rang, identifiant), surplus net signé, recrédit de la + consommation courante, réserve de stockage, plancher, plafond, verrous, mapping SG-Ready avec + hystérésis. Il ne reproduit pas ce que le contexte 1.1 ne porte pas : passe éco (avancement + livré), dérogations, autorisation de soutirage, paliers d'un `relay-router`, refus de commande, + proxy VE. +- Il n'émet que les codes `reasonCode` qu'un optimiseur peut émettre, avec leurs seules clés + documentées ; un code du rule-based hors de cette liste (verrou, réserve…) part en + `OPTIMIZER_DECISION`, le mécanisme nommé dans `reason`. ## Annexe F — Champs réservés (non normatifs) diff --git a/tools/README.md b/tools/README.md index 0a0d6d3..4cd7140 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,7 +1,9 @@ # tools/ Outils de développement et d'exploitation du plugin. Ce fichier ne décrit que -`etm-powersync-trace-replay` ; les autres scripts portent leur mode d'emploi en en-tête. +`etm-powersync-trace-replay` ; l'optimiseur de référence a le sien +(`etm-powersync-ref-optimizer/README.md`), les autres scripts portent leur mode d'emploi en +en-tête. ## `etm-powersync-trace-replay` — rejouer des traces de décision @@ -28,6 +30,9 @@ plan enregistré. - **Sorties** : `.replay-.ndjson` (une ligne par requête rejouée : réponse, latence, écarts) et `….summary.txt`, à côté de la trace. Jamais d'écrasement (`--out` vers un fichier existant est refusé). +- **Comparaison** : charge, kind, puissance d'une consigne (`setpoint`, à `--tolerance-w` près), + état d'une action `state` — la puissance d'une action `state` n'est pas comparée (le §6 ne la + définit pas, et le plan du rule-based tracé la porte). - **Résumé** : requêtes rejouées, taux d'abstention, `computeMs` médian et max (s'il est fourni dans `diagnostics`), cycles non comparables (réponse enregistrée en erreur), cycles dont les actions du créneau courant diffèrent du plan enregistré, avec la liste.