Aller au contenu

Runtime

Status

Status: CURRENT Last consolidated by: BC-068D This document describes the current runtime boundary. For the live operational posture, see ../operations/runtime-current-state.md.

Mission

Le Runtime exécute les traitements techniques de la Platform.

Il orchestre techniquement les jobs, batchs, locks, métriques et reprises d'erreur sans contenir la logique métier profonde.

Pourquoi ce composant existe

La Platform doit pouvoir exécuter des traitements longs, fiables et contrôlés sans mélanger :

  • logique métier
  • orchestration technique
  • persistance
  • monitoring
  • interfaces utilisateur

Le Runtime existe pour rendre l'exécution fiable, observable et reprise en cas d'échec.

Responsabilités

Le Runtime est responsable de :

  • orchestration technique
  • queue
  • batch planning
  • batch execution
  • locks
  • retries
  • métriques d'exécution
  • logs runtime
  • reprise après erreur
  • contrôle d'état d'exécution

Le Runtime n'est pas la source de vérité métier et n'est pas le propriétaire des règles frontend, catalogues, projections publiques ou décisions de gouvernance.

La chaîne dormant Projection / Realtime n'est plus un runtime actif. L'état courant certifié est :

  • aucune activation runtime de cette chaîne ;
  • aucun worker/queue/event path live ;
  • noyau de référence synchrone final seulement :
CatalogRankingEngine
→ CatalogIntelligenceRebuildService
→ CatalogIntelligenceEngine
→ CatalogRepositoryInterface

Ce qui lui appartient

Appartiennent au Runtime :

  • Queue Runner
  • Batch Planner
  • Batch Executor
  • Lock Manager
  • Metrics Logger
  • Run Repository
  • Feed Reader runtime
  • Settings runtime
  • Retry policy
  • Error handling technique
  • adapters techniques de state/transient/lock
  • adapters techniques cron/rewrite
  • adapters techniques schema/install/migration

Ce qui lui est interdit

Le Runtime ne doit jamais contenir :

  • règles métier profondes
  • logique d'identité produit
  • scoring vertical
  • rendu frontend
  • HTML
  • règles de navigation
  • décisions humaines
  • patchs marchands
  • corrections SQL opportunistes

Dépendances autorisées

Le Runtime peut dépendre de :

  • Pipeline
  • Infrastructure
  • Settings techniques
  • repositories runtime
  • logs
  • locks
  • métriques
  • stores techniques WordPress pour l'état runtime non métier
  • adapters WordPress Cron / Rewrite pour la maintenance technique
  • adapters WordPress Schema pour les probes/installations techniques explicites

Dépendances interdites

Le Runtime ne doit pas dépendre de :

  • Frontend
  • templates
  • pages admin
  • règles verticales directes
  • Domain Core direct si le Pipeline doit servir d'intermédiaire
  • décisions humaines de gouvernance
  • endpoints HTTP de présentation

Dans l'état transitoire validé par BC-051 :

  • le bootstrap runtime commun ne charge plus directement les hooks HTTP ;
  • le frontend public est bootstrapé séparément ;
  • les fonctions legacy Product Models de includes/application/ ne sont plus chargées depuis ccx-feeds.php mais via un loader ciblé frontend/CLI ;
  • includes/feeds-pipeline.php n'est plus chargé par includes/bootstrap/runtime.php et passe par un loader ciblé includes/bootstrap/pipeline.php dans les contextes qui exécutent réellement le Pipeline.

Dans l'état transitoire validé par BC-052 :

  • includes/feeds-mapping.php et la famille includes/mapping/* ne sont plus chargés par includes/bootstrap/runtime.php ;
  • le mapping technique passe par includes/bootstrap/mapping.php et n'est chargé qu'avec le Pipeline ;
  • includes/quality/* ne sont plus chargés par includes/bootstrap/runtime.php ;
  • includes/bootstrap/quality.php charge Quality uniquement dans les contextes read-only de health/audit explicitement visés ;
  • includes/strict/* ne sont plus chargés par includes/bootstrap/runtime.php ;
  • includes/bootstrap/strict.php expose la capacité Strict (registry + règles) sans installer de schéma ;
  • includes/bootstrap/strict-schema.php ajoute uniquement les déclarations de schéma Strict nécessaires aux points d'entrée de schéma explicites ;
  • includes/bootstrap/verticals.php charge le registry vertical commun sans charger les modules métier ;
  • includes/bootstrap/verticals.php expose aussi un detection registry léger pour le scoring vertical ;
  • ccx_v5_choose_vertical() charge uniquement les détecteurs légers verticals/*/detect.php pendant la résolution ;
  • les verticals/*/module.php sont maintenant chargés à la demande via ccx_bootstrap_vertical_module() ;
  • le Runtime commun ne charge plus les modules verticaux "au cas où".

Dans l'état transitoire validé par BC-063E2 :

  • les writes techniques WordPress hors métier passent par un adapter explicite includes/infrastructure/technical-state.php ;
  • CCX_WordPressTechnicalStateStore confine les options techniques ;
  • CCX_WordPressTransientStore confine les transients techniques ;
  • CCX_TechnicalLockService confine les named locks MySQL ;
  • les wrappers legacy publics restent inchangés et conservent les mêmes clés, TTL et timeouts.

Dans l'état transitoire validé par BC-063E3 :

  • CCX_CronScheduleService et CCX_WordPressCronAdapter confinent le scheduling technique WordPress ;
  • CCX_RewriteMaintenanceService et CCX_WordPressRewriteAdapter confinent la maintenance technique des rewrites ;
  • le fingerprint des routes Product Models reste stocké via le store technique WordPress ;
  • aucun flush rewrite n'est autorisé sur le frontend public ;
  • le cron passif n'acquiert aucun scheduling additionnel au chargement.

Dans l'état transitoire validé par BC-063E4 :

  • les installations de schéma, migrations structurelles et tables temporaires actives passent par des services explicites ;
  • WP_CLI passif et admin read-only ne doivent plus suffire à déclencher un install/migrate implicite ;
  • le versioning de schéma reste technique et passe par le store WordPress technique ;
  • le SQL legacy de schéma reste inchangé mais n'est plus l'entrypoint public.

Entrées

Le Runtime peut recevoir :

  • job
  • feed à traiter
  • configuration technique
  • contexte d'exécution
  • batch plan
  • run_id
  • priorité
  • état précédent

Les contrôleurs WordPress admin-post n'orchestrent pas directement le Runtime. Ils délèguent à une façade applicative dédiée qui charge le minimum technique requis puis traduit un résultat explicite vers HTTP.

Le même principe s'applique progressivement à WP-CLI : les reads ccx sync passent désormais par une façade dédiée, et l'adapter CLI ne charge plus Quality au chargement du fichier. Le bootstrap Pipeline reste réservé aux sous-commandes qui exécutent réellement une action runtime.

Depuis BC-062B4C, les writes/orchestrations ccx sync passent aussi par un noyau d'actions commun :

  • le point d'entrée WordPress/CLI ne décide plus de l'exécution runtime ;
  • sync-runtime-actions.php charge le Pipeline uniquement pour les actions qui en ont besoin ;
  • cancel, cleanup-stage, cleanup-spool et snapshots prune restent hors Pipeline ;
  • la dette restante concerne surtout le bootstrap CLI global, pas l'adapter sync-runtime.php lui-même.

Depuis BC-062B4D, la CLI Taxonomy suit à son tour cette séparation :

  • l'adapter taxonomy-v2.php ne pilote plus directement schéma, SQL, transactions ni temp tables ;
  • taxonomy-v2-actions.php rend explicites les effets techniques de chaque commande ;
  • audit et dry-run restent classés comme diagnostics à effets techniques potentiels, et non comme lectures pures.

Depuis BC-062B4E, la frontière CLI est considérée certifiée :

  • les commandes Sync read passent par cli-sync-runtime-read.php ;
  • les commandes Sync action et diagnostic passent par cli-sync-runtime-actions.php et sync-runtime-actions.php ;
  • profile rejoint aussi cette façade et ne reste plus une exception runner-direct ;
  • la dette qui subsiste concerne le chargement CLI global autour de includes/bootstrap/cli.php / includes/runtime/bootstrap.php, non la logique des adapters.

Depuis BC-062C, cette dette de chargement CLI global est réduite :

  • includes/bootstrap/cli.php passe par includes/bootstrap/runtime-cli.php au lieu du bootstrap runtime générique ;
  • runtime-cli.php charge les repositories/runtime classes, sync-runner.php, sync-health.php, rebuild-chain.php, taxonomy-v2/core.php et les manifestes CLI, mais pas queue-runner.php ;
  • le CLI simple ne rend plus disponibles ccx_bootstrap_pipeline(), ccx_bootstrap_quality() ni ccx_health_admin_context() ;
  • le chargement du Pipeline reste déclenché à l'exécution par sync-runtime-actions.php pour start, resume, batch, retry_failed, tick, maintain, doctor, profile, replay et rebuild_chain.

Depuis BC-062C3, les contextes admin/HTTP sont réduits à leur tour :

  • includes/bootstrap/admin.php passe par includes/bootstrap/runtime-admin.php au lieu du bootstrap runtime générique ;
  • runtime-admin.php charge les classes runtime requises pour les façades admin sans queue-runner.php ni bootstrap Pipeline ;
  • includes/bootstrap/http.php délègue uniquement à l'adapter HTTP ;
  • l'adapter HTTP charge runtime-http.php et le Pipeline uniquement dans la branche worker autorisée ;
  • les façades http-admin-post-actions.php distinguent désormais :
  • runtime léger pour enqueue_all, sync_health, rebuild_chain ;
  • runtime + Pipeline pour worker_group seulement ;
  • http-health.php charge ccx-health-reconcile.php à la demande, après validation de la route et de la clé.

Depuis BC-062C4, le fichier principal du plugin est à son tour réduit :

  • ccx-feeds.php se limite au garde d'accès, aux constantes techniques, au chargement éventuel de la config locale, à bootstrap/platform.php puis à bootstrap/plugin.php ;
  • le contrat de routes Product Models et la maintenance de rewrites ne sont plus connus du point d'entrée ;
  • ces responsabilités passent par includes/bootstrap/route-maintenance.php, donc par un bootstrap technique interne plutôt que par le file-scope du plugin principal.

Depuis BC-062C5, cette frontière bootstrap WordPress est considérée certifiée :

  • ccx-feeds.php connaît seulement le bootstrap Platform puis le bootstrap plugin ;
  • plugin.php distribue les contextes sans retour arrière :
  • route-maintenance
  • worker
  • http
  • admin
  • cli
  • frontend
  • admin dépend de runtime-admin.php ;
  • http dépend de l'adapter HTTP puis de runtime-http.php uniquement dans les branches autorisées ;
  • cli dépend de runtime-cli.php ;
  • worker dépend du runtime commun ;
  • le frontend public reste projection-first et n'embarque ni bootstrap admin, ni bootstrap HTTP, ni runtime worker.

Invariants certifiés :

  • aucun bootstrap croisé frontend/admin/HTTP/CLI/worker ;
  • aucun Pipeline prématuré en frontend, HTTP forbidden, admin read-only ou CLI simple ;
  • le Pipeline n'est autorisé qu'au moment d'une action explicite qui l'exige ;
  • la maintenance de routes reste technique, séparée du rendu frontend public.

Depuis BC-063C3, un premier rebuild de projection métier sort aussi des orchestrateurs applicatifs directs :

  • ccx_product_models_rebuild() ne porte plus le SQL write de ccx_product_models_v1 ;
  • le remplacement destructif scoped par vertical_id passe par CCX_ProductModelProjectionWriteService ;
  • le SQL legacy reste confiné dans un writer technique dédié ;
  • aucune transaction globale supplémentaire n'est ajoutée par cette frontière.

Depuis BC-063C4, les rebuilds d'enrichissement Product Models suivent le même principe :

  • ccx_product_model_variants_rebuild() ne porte plus le SQL write de ccx_product_model_variants_v1 ;
  • ccx_product_specs_rebuild() ne porte plus le SQL write de ccx_product_specs_v1 ;
  • ccx_product_gallery_rebuild() ne porte plus le SQL write de ccx_product_gallery_v1 ;
  • chacun délègue un replace destructif scoped par vertical_id à un write service dédié ;
  • aucune transaction globale supplémentaire n'est ajoutée.

Depuis BC-062D5, la certification de contexte WordPress complète ajoute :

  • aucun adapter WordPress ne dépend d'un autre adapter WordPress ;
  • les services partagés restent transport-neutral ;
  • les globals transport restent confinés à leurs adapters ;
  • le worker / cron ne dépend ni du frontend, ni de l'admin, ni du CLI ;
  • le cron passif et la queue vide n'amorcent pas le Pipeline ;
  • le Pipeline runtime worker n'est chargé qu'après détection d'un run reprenable.

Depuis BC-062E, cette frontière est aussi certifiée globalement au niveau Adapter :

  • l'entry point WordPress ne connaît ni runtime direct, ni pipeline direct, ni logique métier ;
  • les bootstraps restent des sélecteurs/chargeurs, pas des couches d'orchestration métier ;
  • les writes legacy encore présents derrière des façades ou dans l'infrastructure/runtime ne doivent pas remonter dans les adapters.

Le même principe s'applique à l'endpoint WordPress de health : le hook init garde seulement la détection de route, l'authentification, le mapping de requête et la traduction HTTP, tandis que la façade applicative renvoie un résultat explicite contenant le payload JSON et les flags d'encodage attendus.

La surface admin WordPress Sync Runtime obéit au même principe :

  • contrôleur admin pour hooks, capability, nonce, mapping et redirects ;
  • façade de lecture pour le view model ;
  • façade d'actions pour l'orchestration runtime et les writes ;
  • renderer dédié pour l'HTML.

Le rendu read-only de la page admin ne doit pas charger le pipeline ni déclencher d'effet runtime. Le pipeline n'est autorisé qu'au moment des actions explicites qui en ont besoin (tick, maintain, start, resume).

Sorties

Le Runtime peut produire :

  • statut d'exécution
  • logs
  • métriques
  • erreurs contrôlées
  • événements techniques
  • état de queue
  • résultat de batch
  • information de reprise

Contrats utilisés

Le Runtime peut utiliser :

  • contrats de Pipeline
  • contrats de persistance technique
  • contrats de logging
  • contrats de lock
  • contrats de métriques

Il ne doit pas contourner les contrats métier.

BC-063E5 — writes techniques certifiés

Les writes techniques WordPress utilisés par le Runtime sont désormais attendus uniquement via frontières explicites :

  • état technique / transients / locks ;
  • scheduling cron ;
  • maintenance rewrite ;
  • installation / migration / schéma temporaire.

Les helpers legacy encore présents dans le Runtime ne doivent plus déclencher de write technique au simple chargement. Les nettoyages ou installations résiduels doivent rester attachés à un contexte d'exécution explicite.

Composants internes

Organisation cible :

runtime/

queue/
  queue-runner
  job-repository

batch/
  batch-planner
  batch-executor
  batch-persister

locks/
  lock-manager

metrics/
  metrics-logger

runs/
  run-repository

errors/
  retry-policy
  failure-handler