0.2.0-0-pre.2

docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md

@@ -0,0 +1,174 @@
+<!-- file: docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md -->
+<!-- version: 1 -->
+
+# Étude des dépendances et de la composition
+
+## Statut
+
+Étude non normative pour `0.2.0-0-pre.2`.
+
+## Objectif
+
+Permettre qu'un produit choisisse uniquement ce dont il a besoin, sans duplication des jeux et sans couplage aux providers/platformes.
+
+## Dépendances proposées
+
+Direction générale :
+
+```text
+game-specific
+    ↓
+game-systems
+    ↓
+technical capability APIs
+    ↓
+engine kernel contracts
+```
+
+Les implémentations sont injectées/composées par le produit :
+
+```text
+app/product
+ ├─ game
+ ├─ adapters
+ ├─ providers
+ └─ runtime/backend
+```
+
+Le jeu ne choisit pas lui-même son provider AdMob, son adapter Android ou son transport concret.
+
+## Dépendances interdites candidates
+
+- kernel → game ;
+- kernel → provider ;
+- game-system → application plateforme ;
+- game → SDK publicitaire ;
+- game → Java Android ;
+- game → Tauri ;
+- provider → game-specific ;
+- serveur générique → crate d'application client.
+
+Des exceptions ne doivent être introduites qu'après justification explicite.
+
+## Composition statique
+
+La direction proposée reste la composition Rust statique.
+
+Exemple conceptuel :
+
+```text
+game-snake-android
+  ├─ game-snake
+  ├─ engine-v1-...
+  ├─ input-touch adapter
+  ├─ render-sdl adapter
+  ├─ logging-android
+  └─ ads-admob provider [si activé]
+```
+
+Un autre produit :
+
+```text
+game-snake-desktop
+  ├─ game-snake
+  ├─ engine-v1-...
+  ├─ input-keyboard adapter
+  ├─ render-sdl adapter
+  └─ no ads provider
+```
+
+Le gameplay reste le même.
+
+## Cargo features
+
+Les features Cargo restent utiles pour :
+
+- capacités locales d'une crate ;
+- optional dependencies ;
+- sélection technique bornée.
+
+Elles ne doivent pas devenir le langage global de composition du produit, car leur unification à travers le graphe peut rendre les variantes difficiles à raisonner.
+
+## Manifest produit/jeu
+
+Un manifest dédié pourra décrire plus tard :
+
+- engine generation ;
+- plateformes ;
+- capabilities requises ;
+- capabilities optionnelles ;
+- providers ;
+- online policy ;
+- input profiles ;
+- asset packs ;
+- logging profile.
+
+Exemple purement illustratif :
+
+```toml
+[product]
+game = "snake"
+engine = "v1"
+
+[capabilities]
+score = "required"
+auth = "optional"
+ads = "disabled"
+online = "optional"
+
+[platforms]
+desktop = true
+android = true
+web = true
+```
+
+Ce format n'est pas encore retenu.
+
+## Crates : création à la demande
+
+Un concept réservé n'entraîne pas automatiquement une crate.
+
+Créer une crate devient justifié notamment si :
+
+- plusieurs consommateurs réels existent ;
+- une dépendance lourde doit être isolée ;
+- plusieurs providers/adapters sont nécessaires ;
+- une frontière platform-specific est requise ;
+- un contrat stable mérite une API séparée.
+
+## Structure workspace candidate
+
+La structure pourrait évoluer vers des familles comme :
+
+```text
+crates/
+  engines/
+  capabilities/
+  game-systems/
+  providers/
+  networking/
+  games/
+  apps/
+  servers/
+  common/
+  tools/
+```
+
+Cette arborescence est une hypothèse d'étude. Elle n'est pas encore un contrat de fichiers.
+
+## Online/offline
+
+La composition doit pouvoir exprimer :
+
+- offline-only ;
+- online-optional ;
+- online-required ;
+- online-required pour une capability particulière.
+
+Un jeu online-optional ne doit pas avoir à compiler tout un stack realtime s'il n'en a pas besoin.
+
+## Étape suivante après validation de l'étude
+
+Après revue de `0-pre.2`, les décisions retenues pourront être promues progressivement vers `docs/architecture/`.
+
+Ce n'est qu'après cette promotion qu'il sera pertinent de planifier les POC techniques, notamment Tauri Android, Web/WASM et les variantes natives, pour tester les hypothèses de plateforme.