Aller au contenu

P1.5E — Capacity Benchmark Harness

Status: CLOSED_PASS / GIT-OFF-LIVE

Objet

P1.5E fournit le harness reproductible utilisé par les phases suivantes pour mesurer la capacité réelle de CMonChoix Platform.

Cette certification prouve le mécanisme de benchmark. Elle ne certifie encore ni la capacité du VPS, ni une baseline production, ni des seuils CPU/RAM/DB, ni un SLO de production. Ces preuves appartiennent à P1.5F, P1.5G et P1.5H.

Autorités

Contrat machine-readable :

benchmarks/capacity/harness-contract.json

Runner :

scripts/capacity-benchmark-harness.sh

Résultats par défaut hors du dépôt :

/mnt/data/cmonchoix-benchmarks/p1-5

Un benchmark ne doit pas salir le worktree Git ni transformer le dépôt en stockage de séries temporelles.

Mode par défaut

Le harness est fail-closed :

default = --plan

Un plan valide scénario et métadonnées, impose au minimum 1 warm-up et 3 runs mesurés, ne lance aucun workload, ne contacte pas Docker et ne crée aucun résultat.

Exemple :

bash scripts/capacity-benchmark-harness.sh \
  --plan \
  --scenario S0 \
  --dataset-id baseline-production-v1 \
  --dataset-sha256 <64-hex> \
  --offers 100000 \
  --products 25000 \
  --merchants 10 \
  --change-percent 0 \
  --workers 1

Exécution explicite

Une exécution exige :

--execute
--expected-git-sha <SHA exact>
--workload-script <fichier exécutable>
--verifier-script <fichier exécutable>
--recovery-script <fichier exécutable>   # obligatoire pour S1..S6
--scenario-config <json tracké>           # obligatoire pour S1 uniquement

Le worktree doit être propre et le SHA courant doit correspondre exactement à la révision annoncée.

Le harness n'accepte aucune chaîne de commande dynamique. Il n'utilise ni eval, ni bash -c.

Le harness certifié est désormais p1.5e-v3. Les scripts workload, verifier et, pour S1–S6, recovery doivent être Git-trackés sur la révision exacte et restent fingerprintés par SHA-256 dans le manifest. S1 exige en plus un --scenario-config JSON Git-tracké et fingerprinté ; ce JSON n'est jamais sourcé ni évalué comme du shell.

S0 reste strictement read-only et refuse un --recovery-script. À l'inverse, S1–S6 refusent l'exécution si le recovery script est absent ou non exécutable.

Séparation workload / correctness

Chaque répétition suit :

capacity before
    ↓
workload
    ↓
business verifier
    ↓
capacity after
    ↓
window max + avg
    ↓
recovery / rollback
    ↓
runtime recovered state

La recovery est volontairement exécutée après les captures capacity-after et capacity-window. Elle ne pollue donc pas la fenêtre mesurée du scénario.

Un workload non nul est FAIL. Un verifier non nul est FAIL. Pour S1–S6, un recovery non nul est également FAIL. Un benchmark plus rapide avec un résultat métier différent ou une restauration incomplète ne peut donc pas être déclaré PASS.

Répétitions

Minimum obligatoire :

1 warm-up
3 measured runs

Le résumé conserve notamment :

median_duration_ms
worst_duration_ms
business_correctness=PASS

Manifest reproductible

Le manifest fige notamment :

git_sha
worker_image_reference
worker_image_id
config hashes
dataset_id
dataset_sha256
offers
products
merchant_count
change_percent
worker_count
scenario_id
benchmark_harness_version
started_at
finished_at
workload_script + sha256
verifier_script + sha256
recovery_script + sha256
scenario_config + sha256

Les configs critiques hashées comprennent Compose, Alloy, Prometheus, recording rules, contrat capacité et dashboard.

Métriques

Le harness lit les 19 séries contractuelles ccx_capacity_* définies par P1.5D. Le contrat JSON doit rester exactement aligné sur monitoring/capacity-metrics.json.

La lecture passe par l'autorité Prometheus live :

docker exec ccx_prometheus
promtool query instant

Pour chaque run sont conservés :

capacity-before.txt
capacity-after.txt
capacity-window.txt

La fenêtre post-run contient max_over_time et avg_over_time sur l'intervalle du run augmenté d'une marge de scrape.

Scénarios

ID Phase Intention
S0 P1.5F baseline production read-only
S1 P1.5G large feed
S2 P1.5G high churn prix/stock
S3 P1.5G marchands concurrents
S4 P1.5G comparaison 1/2/4 workers si le Runtime l'autorise
S5 P1.5G projection rebuild
S6 P1.5G frontend pendant sync lourde

S4 refuse toute valeur autre que 1, 2 ou 4 workers. Cela n'autorise pas automatiquement la concurrence : le contrat Runtime CURRENT reste prioritaire.

Autorité de mutation

Le harness lui-même ne doit jamais exécuter :

systemctl start|stop|restart|enable|disable
docker compose up|down|restart

Toute mutation contrôlée de P1.5G appartient au workload versionné fourni explicitement au harness et doit posséder sa propre procédure de recovery.

Avec le harness v3, cette règle reste fail-closed : S1–S6 exigent --recovery-script, fingerprintent son SHA-256 et exécutent la recovery après la collecte des preuves du run. Le harness lui-même ne reçoit toujours aucune autorité systemctl ou docker compose up/down/restart.

Artefacts

Chaque répétition conserve les logs workload/verifier/recovery, les trois captures capacité, l'état Runtime avant/après workload, l'état après recovery et result.env.

Le répertoire racine conserve :

manifest.env
config-hashes.sha256
environment.env
runs.tsv
summary.env

CI

P1.5E est gardé par :

tests/Architecture/CapacityBenchmarkHarnessBoundaryTest.php
tests/Operations/capacity-benchmark-harness-smoke.sh

Les guards vérifient la parité des 19 séries, les sept scénarios, les répétitions minimales, le mode plan, le SHA exact, l'absence de shell dynamique et l'absence d'autorité de gestion des services.

État après P1.5E

P1.5A  measurement contract             CLOSED
P1.5B  runtime instrumentation          CLOSED
P1.5C  source materialization Git       CLOSED
P1.5D  dashboard + recording rules Git  CLOSED
P1.5E  benchmark harness Git            CLOSED

P1.5F  production read-only baseline    PREPARED / LIVE EXECUTION REQUIRED
P1.5G  controlled live benchmark        FUTURE
P1.5H  capacity certificate              FUTURE

Voir aussi

  • Capacity Measurement Contract
  • Performance et capacité
  • Certification Overview