Runtime Architecture Overview¶

Status: CURRENT

Objet¶

Le Runtime est la couche d’orchestration opérationnelle de CMonChoix Platform.

Il décide quand et comment exécuter les capacités du Pipeline, du Domain Core et des projections, sans devenir propriétaire de la vérité métier.

Entrées externes
      ↓
Adapters
      ↓
Runtime
      ↓
Application / Pipeline / Projection
      ↓
Persistence et observabilité

Le Runtime orchestre. Il ne normalise pas, ne résout pas une identité et ne construit pas lui-même une projection.

Entrypoints WordPress¶

Le graphe de bootstrap courant est :

ccx-feeds.php
    ↓
includes/bootstrap/platform.php
    ↓
includes/bootstrap/plugin.php
    ├── route-maintenance.php
    ├── worker.php
    ├── http.php
    ├── admin.php
    ├── cli.php
    └── frontend.php

Chaque adapter charge un runtime minimal adapté à son contexte :

runtime.php pour le worker et le cron ;
runtime-http.php pour les requêtes HTTP authentifiées ;
runtime-admin.php pour l’administration ;
runtime-cli.php pour WP-CLI.

Le Pipeline, le Mapping, Quality, Strict et les verticales sont chargés à la demande par leurs bootstraps dédiés. Ils ne doivent pas être chargés sur une requête qui n’en a pas besoin.

Matrice de chargement¶

Contexte	Pipeline	Mapping	Quality	Frontend	Worker	Admin
frontend public	non	non	non	oui	non	non
admin lecture seule	non	non	non	non	non	oui
action admin	ciblé	selon action	selon action	non	non	oui
HTTP health / interdit	non	non	non	non	non	non
HTTP worker autorisé	oui	via Pipeline	selon besoin	non	non	non
CLI simple	non	non	non	non	non	non
CLI sync / taxonomy	ciblé	selon action	selon action	non	non	non
worker / cron	selon job	via Pipeline	selon job	non	oui	non

Cette matrice est une contrainte d’architecture. Tout chargement plus large doit être justifié par un besoin runtime réel.

Responsabilités¶

Le Runtime est responsable de :

lancer et reprendre les synchronisations ;
ordonnancer les étapes d’une exécution ;
gérer les batches, offsets et compteurs ;
propager les paramètres d’exécution ;
produire un résultat explicite de succès ou d’échec ;
exposer des informations de diagnostic et de progression ;
empêcher qu’un adapter transporte de la logique métier.

Les commandes CLI et les endpoints HTTP restent des adapters minces : parsing, validation, délégation, formatage.

Frontières strictes¶

Le Runtime ne doit jamais :

normaliser une ligne marchande ;
résoudre une identité produit ;
choisir un candidat métier ;
calculer une règle de qualité verticale ;
modifier la vérité du Product Domain ;
construire directement une vue catalogue ;
dépendre du rendu HTML, des headers HTTP ou de WP_CLI dans ses services applicatifs partagés.

Ces responsabilités appartiennent respectivement au Pipeline, au Domain Core, aux Vertical Modules, au Quality Scorer et au Projection Engine.

Exécution d’une synchronisation¶

Le cycle opérationnel général est :

Création ou reprise du run
        ↓
Acquisition du feed
        ↓
Stage
        ↓
Normalisation / classification / qualité
        ↓
Projection vers offers_norm
        ↓
Contrôles post-projection
        ↓
Finalisation du run

Une étape peut être exécutée par batch. La reprise doit utiliser l’état persistant du run plutôt qu’une supposition fondée sur le processus PHP courant.

Worker et cron¶

Le worker est le seul contexte chargé pour exécuter automatiquement les jobs reprenables.

Les invariants suivants s’appliquent :

cron_schedules et ccx_runtime_tick sont enregistrés dans includes/runtime/queue-runner.php ;
le Pipeline reste lazy lors d’un cron passif ;
il n’est chargé que lorsqu’un job exécutable ou reprenable a été identifié ;
le worker n’expose aucun renderer, endpoint ou transport utilisateur.

Runtime CLI¶

WP-CLI utilise includes/bootstrap/cli.php puis runtime-cli.php.

Les commandes doivent déléguer aux façades applicatives, notamment aux composants de lecture et d’action du runtime de synchronisation. Une commande ne doit pas contenir de SQL métier, de migration implicite ou d’algorithme de normalisation.

Les déclarations de schéma et migrations restent réservées aux commandes ou points d’installation explicitement conçus pour cela.

Projection et Media Quality¶

Le Runtime peut déclencher une projection ou un audit Media Quality, mais il ne porte pas leurs règles.

La chaîne de responsabilité reste :

Runtime
   ↓
Application service
   ↓
Projection Writer
   ↓
Offers Norm
   ↓
Media Quality audit

Media Quality fonctionne par défaut en mode audit-first. Une exécution runtime ne doit jamais activer une mutation destructive implicite ni effacer une image principale en l’absence de remplacement fiable.

Résultats et observabilité¶

Chaque exécution doit exposer au minimum :

un identifiant de run ;
son état courant et final ;
les dates de début et de fin ;
le nombre de lignes lues, traitées, rejetées et projetées ;
les erreurs structurées ;
les métriques de qualité utiles au diagnostic ;
les informations nécessaires à une reprise sûre.

Les logs complètent l’état persistant, mais ne le remplacent pas.

Isolation et idempotence¶

Une erreur sur un feed ou un batch ne doit pas corrompre les autres exécutions.

Les opérations reprenables doivent être idempotentes ou protégées par une clé stable. Relancer un batch déjà validé ne doit pas créer de doublons ni réappliquer une mutation destructive.

Invariants¶

Adapter mince¶

Les adapters HTTP, Admin, CLI, Frontend et Worker ne s’incluent pas entre eux et ne contiennent pas de logique métier.

Chargement minimal¶

Une requête ne charge que les capacités nécessaires à son contexte.

Orchestration uniquement¶

Le Runtime déclenche les traitements ; les composants métier les réalisent.

Traçabilité¶

Toute exécution importante est identifiable, mesurable et explicable.

Reprise sûre¶

Les runs interrompus peuvent reprendre à partir d’un état persistant cohérent.

Absence de mutation implicite¶

Aucun audit, diagnostic ou commande de lecture ne modifie silencieusement les données.

Tests d’architecture attendus¶

Les tests doivent vérifier au minimum :

l’absence d’inclusion entre adapters ;
l’absence de transport dans les services applicatifs partagés ;
le chargement lazy du Pipeline ;
la stabilité de la matrice de bootstrap ;
l’absence de schéma implicite dans un runtime de lecture ;
l’idempotence des opérations reprenables ;
le caractère non destructif des audits par défaut.

Voir aussi¶

../operations/runtime-current-state.md
../pipeline/normalisation.md
../business-domains/catalog/projection-engine.md
../architecture/media-quality-engine.md
../contracts/quality-scorer.md
../../plugins/ccx-feeds-industrial/README.md