fix(telemetry): measure response bytes and retrieval work (W0-1) - #468

Symptôme

W0-1 / ⚪2 : les opérations instrumentées écrivaient bytes_out=0, tandis que
query_methodology, session_start et auto_recall étaient absents du journal.
Le chemin de récupération et le travail effectif du reranker n'étaient pas mesurés.

Cause racine

Contrat de mesure incomplet : _telemetry_wrap n'envoyait pas la réponse au
compteur. Les erreurs et validations de sortie sont converties par le SDK après
le handler ; les compter dans le handler seul laisse encore des zéros faux.
Les hooks ne possédaient pas de frontière de mesure, et le chemin du journal
ignorait CORTEX_CLAUDE_DIR.

Changement

• Mesurer le texte UTF-8 effectivement rendu par le SDK, succès comme erreur,
  dans un middleware de composition ; publier chaque échantillon une seule fois.
  Les appels directs aux handlers mesurent leur résultat sérialisé.
• Enregistrer les opérations manquantes. Les hooks comptent les octets après
  encodage et conversion des fins de ligne, sans reconstruire l'encodeur stdout.
• Transporter tier et reranked_count dans un contexte propre à l'opération,
  restauré après les appels imbriqués. Le compteur ne croît qu'après une inférence
  réussie ; il vaut zéro si le modèle est sauté ou échoue.
• Respecter CORTEX_CLAUDE_DIR pour le journal et signaler ses échecs d'écriture.
  Documenter la frontière de mesure et la signification des champs dans PRIVACY.md.

Les poids de récupération, les décisions du reranker et les réponses ne changent
pas. tier=pg nomme le pipeline actuellement exécuté, y compris avec son store
SQLite ; les anciennes routes conservent simple / mixed / deep. tier=null
signifie qu'aucune route instrumentée n'a été exécutée. Un hook silencieux et un
handler direct qui lève sans réponse gardent légitimement bytes_out=0.

Preuve

Base : 10a0f38152d15625b58b4027ea86eb7705377ae7.
Commit testé : 24f7a398abd3371d983421ae94ff177e2ecfb5c9 ; aucun rebase.
Checkout propre : /private/tmp/cortex-green-w0-1-validation, macOS arm64,
Python 3.12.11, versions installées depuis uv.lock.

Conditions relevées avant validation : getconf NPROCESSORS_ONLN → 10 ;
uptime → load averages: 5.66 6.04 4.93 ; df -h / → 68Gi disponibles.
Avant la suite complète : charge 5.65 5.44 5.19 ; 67Gi disponibles après
préparation du checkout. Un seul travail lourd local à la fois.
Après validation : charge 6.84 6.33 5.62, espace disponible 67Gi.

Avant correction, le test du wrapper sur les handlers publics recall({}) et
remember({}) échouait sur la première assertion de volume : bytes_out=0
malgré une réponse non vide (1 failed, 1 passed). Après correction, les tests
comparent le volume à la sérialisation du SDK et au stdout effectivement écrit.

Signaux d'acceptation W0-1 présents dans les tests :

• test_real_store_round_trip_records_nonempty_response_sizes : vrai store
  SQLite jetable, rappel suivi d'une écriture, exactement les deux échantillons,
  bytes_out>0, tier et reranked_count présents.
• test_isolated_session_records_all_context_operations : session avec sources
  simulées, journal jetable contenant exactement query_methodology,
  session_start, auto_recall ; tailles du banner et de l'injection exactes.
• test_sdk_text_response_is_counted_exactly_once : vrai client/serveur SDK en
  mémoire, succès, exception et rejet du schéma de sortie ; volume, statut et
  compteurs concordent avec le résultat reçu.
• Tests de CRLF, UTF-8, remplacement des caractères invalides, exceptions,
  restauration de stdout, scopes concurrents/imbriqués et worker tardif.

Gates exécutées dans cet ordre :

uv sync --no-default-groups --extra dev --extra sqlite --group lint --locked
.venv/bin/ruff check && .venv/bin/ruff format --check
# All checks passed! ; 1403 files already formatted
.venv/bin/python scripts/check_craftsmanship.py
# Craftsmanship gate: OK
uv sync --no-default-groups --extra dev --extra postgresql --extra sqlite \
  --extra codebase --extra otel --group typecheck --group lint --locked
.venv/bin/python -m pyright mcp_server/
# 0 errors, 0 warnings, 0 informations

Environnement des commandes pytest ci-dessous :

export CORTEX_TEST_DATABASE_URL=postgresql://localhost:1/cortex_green_isolated
export CORTEX_MEMORY_STORE_BACKEND=sqlite DATABASE_URL=
export HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 CORTEX_RERANKER_OFFLINE=1
.venv/bin/python -m pytest tests_py/core/ tests_py/shared/ tests_py/handlers/ \
  tests_py/hooks/ tests_py/test_telemetry_middleware.py -q --tb=short
# 5566 passed, 67 skipped, 3 warnings in 110.32s
.venv/bin/python -m pytest -q --tb=short
# 7490 passed, 221 skipped, 3 warnings, 123 subtests passed in 143.13s

PostgreSQL est volontairement inaccessible : les tests qui le requièrent sont
signalés comme sautés, pas comme validés. La suite redirige tous ses chemins de
données vers des arbres jetables. Aucun score de qualité de rappel ni gain
énergétique n'est revendiqué par cette PR d'instrumentation.

Conformité

• §1.1 : PASS — branche dédiée fix/green-telemetry, commit conventionnel, une PR W0-1 ;
  fusion laissée au propriétaire.
• §1.2 : PASS — gates locales ci-dessus ; baseline diminuée de la seule entrée
  method-size: record, rendue inutile par l'extraction des étapes de publication.
• §1.3 : PASS — nouveaux modules sous les caps, nouveaux imports conformes aux couches ;
  les sources de la sérialisation et des conversions sont nommées dans le code.
  La dette historique conservée est détaillée ci-dessous.
• §1.4 : PASS — échecs de journalisation observables, aucun cache de modèle sous /tmp,
  aucun shim ni mécanisme retiré.
• §1.5 : PASS — données exclusivement jetables ; pas de changement d'algorithme de
  lecture/écriture ni de revendication de floors. L'acceptation spécifique W0-1
  est démontrée par les tests ci-dessus.
• §1.6 : PASS — charge vérifiée avant les travaux lourds ; exécutions locales sérialisées.
• §1.7 : PASS — aucune opération sur les données de production.
• §1.8 : PASS — aucune issue ouverte ; dette rencontrée listée ci-dessous.
• §1.9 : PASS — nombres issus des sorties des commandes ou de l'identifiant ⚪2 du contrat.
• §1.10 : PASS — porte binaire de confiance du reranker inchangée.

Candidats issues

• core/telemetry.py conserve ses imports historiques os et pathlib, déjà
  présents dans la baseline de la base. Cette PR corrige la résolution du chemin
  existant sans introduire de nouvel import de couche ; extraire tout le sink
  demanderait une tâche distincte.
• Les fichiers historiques query_methodology.py, session_start.py,
  auto_recall.py et certaines fonctions de récupération dépassent déjà les caps.
  Le diff ajoute leurs points d'observation sans absorber leur refonte générale.
• Le harnais local non suivi benchmarks/energy/ présente des erreurs Ruff
  préexistantes ; il n'entre pas dans W0-1. La décision du propriétaire pour W0-2
  reste nécessaire. Le checkout isolé vérifie l'intégralité des fichiers de la PR.
• La protection GitHub de main liste encore des jobs individuels, contrairement
  au check agrégé décrit par CONTRIBUTING.md ; traitement prévu par W1-2.

Runbook

Aucune migration, purge ou opération de maintenance sur la production.
Après fusion, redémarrer l'hôte MCP pour charger l'instrumentation.