Contrat MAESTRO V5

P73C : les schémas ci-dessous sont rendus en SVG inline, visibles hors ligne sans moteur Mermaid ni CDN.

Source normative

AGENTS.md est le contrat d'architecture suprême. Les documents de DOC/10_CONCEPTS sont des références conceptuelles non normatives : ils guident le développement, mais ne remplacent jamais AGENTS.md.

Règle centrale : Kernel garant du framework

Le Kernel est le garant du framework et du bus SYS.

Le boot est séquentiel pour valider les moteurs, les espaces publics et les dépendances officielles étape par étape. Une fois un moteur/module/composant chargé par son propriétaire officiel, le script consomme SYS comme acquis.

Contrat attendu : capture locale des dépendances au point d'entrée officiel, puis usage direct. Pas de revalidation permanente du bus.

Pattern attendu

local SYS_REF = nil
local LOGGER = nil
local UI = nil

function Unit.Init(SYS)
    SYS_REF = SYS
    LOGGER = SYS.LOGGER
    UI = SYS.UI

    return Unit
end

Interdit après la frontière officielle

if type(SYS) ~= "table" then ... end
if type(SYS.UI) ~= "table" then ... end
if type(SYS.LOGGER.Exec) ~= "function" then ... end
local UI = SYS.UI or {}
local Utils = GetUtils()

Schémas contractuels P73B

Usage : les schémas suivants sont des contraintes de code. Ils doivent être relus avant toute nouvelle étape pour éviter les loaders parallèles, les fallbacks, le bruit défensif SYS et le mélange moteur/module/composant. Page complète : MAESTRO_ARCHITECTURE_DIAGRAMS_P73B.html.

Couches runtime

Source Mermaid initiale

flowchart TD
  K[Kernel garantit SYS] --> F[FSM décide]
  F --> D[Dispatcher exécute]
  D --> E[Engines exposent SYS.NAME]
  E --> U[UI Factory expose SYS.UI]
  U --> C[CPNT_* scannés]
  D --> M[MOD_* orchestration métier]
  M --> UI[Composants publics + Excel ranges]
  M -. interdit .-> G[gfx / ParseExcel / ApplyFont]
  U -. interdit .-> B[Logique métier / POP loader]

Module = orchestration. Composant = dessin. Factory = scan dynamique.

Cycle moteur

Source Mermaid initiale

stateDiagram-v2
  [*] --> Load
  Load --> Ping
  Ping --> Init
  Init --> Expose
  Expose --> StepNext
  Load --> FailFast
  Ping --> FailFast
  Init --> FailFast
  Expose --> FailFast

Un moteur réel = un STEP_NEXT. Pas de fallback.

Règles absolues

Type fort et respect strict de la casse.
SYS est le bus runtime officiel unique.
SYS.Services est supprimé du contrat runtime public.
_G est interdit comme espace runtime public.
0 fallback silencieux et 0 fallback fonctionnel.
Exception unique : marqueur visuel mauve si une couleur CSS manque ou est invalide.
Marqueur i18n visible autorisé : [* key *].
Fail-fast explicite : une ressource critique absente doit produire une erreur lisible.
0 bidouille : corriger la cause racine, pas masquer le symptôme.
Pas de dofile composant dans les modules.
Pas d'accès _G pour résoudre un service ou un composant.
Pas de reaper.ShowConsoleMsg sauf demande explicite de debug.

Couches métier

Couche	Responsabilité	Interdit
Kernel	Garantir le framework, construire `SYS`, preboot minimal, main loop.	Reprendre la FSM après activation, masquer un contrat cassé.
FSM	Décider la transition à partir des données officielles.	Charger des fichiers ou agir comme loader.
Dispatcher	Exécuter l'action demandée : load, ping, init, expose, STEP_NEXT.	Décider l'état suivant ou créer une FSM cachée.
Engines	Services runtime officiels exposés dans `SYS.NAME`.	Sortir de leur périmètre ou refaire le rôle d'un autre moteur.
Factory	Grille, rendu, input distribué, scan dynamique `COMPONENTS/CPNT_*.lua`, exposition `SYS.UI`.	Logique métier, loader `POP_*`, chargement module, Project Guard.
Components	Dessin et interaction UI réutilisable exposés dans `SYS.UI`.	Logique métier, DB métier, API métier, chargement de fichiers.
Modules	Orchestration métier et UI par composants publics.	Dessin bas niveau, `gfx`, `ParseExcel`, `ApplyFont`, chargement composant.

Périmètre strict des moteurs

Le détail complet est dans Engines V5 et dans DOC/10_CONCEPTS/MAESTRO_ENGINE_PERIMETER_CONTRACT_P73.md.

Moteur	Exposition	Périmètre strict
MO_KERNEL	`SYS`	Garant framework, preboot, main loop, handoff vers FSM.
MO_MANIFEST	`SYS.MANIFEST`, `SYS.PATHS`	Chemins officiels et scan strict du projet.
MO_LOGGER_ENGINE	`SYS.LOGGER`	Journal runtime officiel uniquement.
MO_PANIC_HANDLER	`SYS.PANIC`	Affichage fatal minimal pre-Factory.
MO_BOOT_CONSOLE_ENGINE	`SYS.BOOT_CONSOLE`	Console temporaire de boot et miroir logger.
MO_SQL_ENGINE	`SYS.SQL`	SQL RAM/persistant, transactions et introspection.
MO_ACTION_DISPATCHER	`SYS.DISPATCHER`	Exécuter les actions FSM officielles.
MO_FSM_ENGINE	`SYS.FSM`	Automate et sélection de transition.
MO_LOADER	`SYS.LOADER`	Parseurs de configuration et dumps boot obligatoires.
MO_CORE_UTILS	`SYS.UTILS`, `SYS.CACHE`	Helpers purs, signatures et métadonnées.
MO_CSS_ENGINE	`SYS.CSS`	Styles, palette, résolution CSS.
MO_I18N_ENGINE	`SYS.I18N`, `SYS.T`	Dictionnaires et traduction.
MO_SYSTEM_MONITOR	`SYS.MONITOR`	Mesure runtime et performance.
MO_TASK_SCHEDULER	`SYS.SCHEDULER`	File de tâches non bloquantes.
MO_RESOURCES_MANAGER	`SYS.RESOURCES`	Ressources graphiques officielles.
MO_UI_FACTORY	`SYS.UI`	Rendu UI, input et composants scannés dynamiquement.
MO_NOTIFIER_ENGINE	`SYS.NOTIFIER`	Notifications runtime génériques.
MO_MIDI_ENGINE	`SYS.MIDI`	Pont REAPER pour MIDI/projet/RPP.
MO_REST_ENGINE	`SYS.REST`	HTTP/curl officiel asynchrone.
MO_AI_ENGINE	`SYS.AI`	Assistance AI optionnelle via REST/Scheduler.

Factory et composants

Les composants CPNT_* sont des extensions directes de la UI Factory. La Factory les scanne dynamiquement pendant Init(SYS), valide leurs exports et expose l'API publique dans SYS.UI.

Un module consomme uniquement les composants publics : SYS.UI.BUTTON, SYS.UI.CONSOLE, SYS.UI.SIDEPANEL, SYS.UI.TINYNOTEPAD, etc. Il ne charge jamais un composant par chemin.

Popup / Project Guard — décision courante

Pas de POP_*.lua tant qu'AGENTS.md ne définit pas cette famille.
Pas de loader POP_* dans MO_UI_FACTORY.
Aucun MO_PROJECT_GUARD_ENGINE dans le palier courant, donc aucune transition FSM dédiée.
Working Directory / Working RPP : utiliser SYS.UTILS pour les helpers purs et SYS.MIDI pour le pont REAPER, aux endroits requis.
Les modules/popup métier travaillent avec des Excel ranges fixes et des composants publics uniquement.

Langue et i18n

Interface visible en français par défaut.
Ton orienté musicien/compositeur.
Jargon technique limité et expliqué quand il est utile.
Utiliser T("key") quand le service est disponible.
Commentaires dans les scripts en français.

AI

AI optionnelle, contextuelle et non intrusive.
Aucun appel API automatique au boot.
Appels AI uniquement sur action utilisateur ou tâche explicitement planifiée.
Appels AI via Scheduler/REST, sans blocage UI.
Jamais de clé API dans Git, les logs ou les scripts ; utiliser OPENAI_API_KEY.