0.1.0-0-pre.4

docs/000-README.md

@@ -1,5 +1,5 @@
 <!-- file: docs/000-README.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Documentation games.sasedev
 
@@ -44,3 +44,8 @@ Voir [`../RULES.md`](../RULES.md), notamment [`rules/RULES_COMMANDS.md`](rules/R
 - [`validation/001-VALIDATION_GATES.md`](validation/001-VALIDATION_GATES.md) — gates manuelles du workspace.
 
 - [`development/002-DESKTOP_DISTRIBUTIONS.md`](development/002-DESKTOP_DISTRIBUTIONS.md) — distributions Desktop natives et variante Tauri optionnelle.
+## Tests et diagnostics
+
+- [`testing/001-TEST_ARCHITECTURE.md`](testing/001-TEST_ARCHITECTURE.md) — séparation `unit_tests/` / `tests/`, tests ciblés et tracing de test.
+- [`development/003-TRACING_AND_DIAGNOSTICS.md`](development/003-TRACING_AND_DIAGNOSTICS.md) — socle `tracing`, subscriber et appender communs.
+

docs/development/003-TRACING_AND_DIAGNOSTICS.md

@@ -0,0 +1,23 @@
+<!-- file: docs/development/003-TRACING_AND_DIAGNOSTICS.md -->
+<!-- version: 1 -->
+
+# Tracing et diagnostics
+
+## Objectif
+
+Le projet utilise `tracing` comme façade structurée commune pour les événements de diagnostic Rust. Les applications choisissent le subscriber adapté à leur distribution ; les librairies émettent des événements sans imposer une destination globale.
+
+## Socle initial
+
+`crates/common/game-logging-lib` regroupe l’initialisation réutilisable. La première implémentation fournit :
+
+- un subscriber console formaté ;
+- une écriture non bloquante via `tracing-appender` ;
+- un guard dont la durée de vie protège le flush des événements ;
+- un subscriber local destiné aux tests.
+
+Les runners Desktop initialisent ce socle. Les futures intégrations Android pourront adapter la destination aux contraintes Logcat/plateforme sans modifier les crates jeu.
+
+## Évolution
+
+Les filtres par target/niveau, fichiers rotatifs, configuration utilisateur, traces Android et éventuelle télémétrie distante seront ajoutés uniquement lorsqu’un besoin concret les justifie.

docs/rules/FILE_CONTRACTS.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/FILE_CONTRACTS.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Contrats des fichiers principaux
 
@@ -16,6 +16,8 @@
 - `docs/monetization/` décrit les modèles de monétisation indépendamment des fournisseurs.
 - `docs/services/` décrit leaderboards, backend, partage, anti-cheat et services communautaires.
 - `docs/development/` décrit les workflows de développement non normatifs complémentaires aux règles.
+- `docs/testing/` décrit l’architecture des tests, leur placement et les stratégies de sélection.
+- `crates/common/` contient les bibliothèques transverses indépendantes d’une génération spécifique du moteur, notamment le socle de logging.
 - `deltas/` contient un document par livraison ou correctif versionné.
 - `prompts/` peut contenir les prompts de reprise de session lorsqu'ils deviennent utiles.
 - `scripts/` contient des audits en lecture seule et des outils du dépôt.

docs/rules/RULES_COMMANDS.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_COMMANDS.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Règles d'exécution des commandes
 
@@ -9,7 +9,7 @@
 - **CMD-GEN-002** — Une commande mutante n'est pas utilisée lorsqu'une commande de contrôle en lecture seule suffit.
 - **CMD-GEN-003** — Les commandes destructives ou de nettoyage global ne sont jamais exécutées par habitude.
 - **CMD-GEN-004** — Une gate n'est déclarée réussie que si la commande exacte a été exécutée sur l'état livré.
-- **CMD-GEN-005** — Les commandes ciblées sont préférées pendant le développement ; les commandes workspace complètes sont utilisées aux gates de livraison.
+- **CMD-GEN-005** — Les commandes ciblées sont préférées dès que leur portée est connue ; les gates workspace complètes ne sont imposées que lorsque leur coût est justifié par la portée du changement ou la phase de validation.
 - **CMD-GEN-006** — Les scripts `audit_*` sont des contrôles en lecture seule et ne corrigent jamais automatiquement les fichiers.
 - **CMD-GEN-007** — Sauf demande explicite contraire, les commandes Cargo de validation finale sont exécutées par l'utilisateur sur son workspace local et non déclarées réussies par le générateur.
 - **CMD-GEN-008** — Chaque fichier delta indique les commandes de validation que l'utilisateur doit exécuter et le statut connu de la validation du delta précédent.
@@ -18,17 +18,18 @@
 
 ## Rust et Cargo
 
-- **CMD-RUST-001** — `cargo fmt --all` peut être utilisé après une tranche cohérente pour appliquer le formatage ; il ne sert pas de diagnostic.
-- **CMD-RUST-002** — `cargo fmt --all -- --check` est la gate canonique de formatage et doit être exécutée avant livraison.
+- **CMD-RUST-001** — Lorsqu’un delta a modifié au moins un fichier Rust, l’utilisateur exécute `cargo fmt --all` au début de la validation afin d’appliquer le formatage canonique; les changements purement produits par rustfmt constituent l’unique exception à l’incrément obligatoire de l’en-tête de version du fichier.
+- **CMD-RUST-002** — `cargo fmt --all -- --check` suit immédiatement le formatage et constitue la gate canonique de conformité rustfmt.
 - **CMD-RUST-003** — `cargo check --workspace` est la première gate de compilation globale après les audits statiques.
 - **CMD-RUST-004** — `cargo clippy --workspace --all-targets --all-features -- -D warnings` est exécuté après un `cargo check --workspace` propre pour la gate complète.
-- **CMD-RUST-005** — `cargo test --workspace --all-targets --all-features` est la gate de tests globale ; des tests `-p <crate>` peuvent être utilisés plus tôt pendant le développement.
-- **CMD-RUST-006** — `cargo run -p <desktop-runner>` sert aux smokes manuels Desktop et n'est pas substitué aux tests automatisés.
-- **CMD-RUST-007** — `cargo build` est utilisé lorsqu'un artefact exécutable ou une bibliothèque est réellement nécessaire ; il n'est pas lancé systématiquement en plus de `cargo check`.
-- **CMD-RUST-008** — `cargo tree` et ses variantes sont des commandes de diagnostic de dépendances, pas des gates obligatoires de chaque delta.
-- **CMD-RUST-009** — `cargo update` n'est jamais exécuté opportunistement. Toute mise à jour de dépendance doit appartenir à une tranche explicitement consacrée aux dépendances ou être nécessaire à la fonctionnalité en cours.
-- **CMD-RUST-010** — `cargo clean` n'est pas une gate et n'est pas utilisé en routine. Il n'est autorisé qu'en cas de diagnostic de build corrompu, de contrainte disque explicite ou de demande ciblée, avec justification.
-- **CMD-RUST-011** — La suppression manuelle de `target/` ne remplace pas `cargo clean` et suit les mêmes restrictions.
+- **CMD-RUST-005** — Les tests ciblés `cargo test -p <crate> --all-targets --all-features` sont la stratégie normale d’un delta et doivent couvrir toutes les crates directement ou transitivement affectées lorsque cela est raisonnablement déterminable.
+- **CMD-RUST-006** — `cargo test --workspace --all-targets --all-features` est une gate lourde réservée au démarrage d’une nouvelle version `X.Y.Z`, à la fin d’une phase/version, aux changements transverses importants ou lorsqu’il existe un doute raisonnable sur la portée des tests ciblés.
+- **CMD-RUST-007** — `cargo run -p <desktop-runner>` sert aux smokes manuels Desktop et n'est pas substitué aux tests automatisés.
+- **CMD-RUST-008** — `cargo build` est utilisé lorsqu'un artefact exécutable ou une bibliothèque est réellement nécessaire ; il n'est pas lancé systématiquement en plus de `cargo check`.
+- **CMD-RUST-009** — `cargo tree` et ses variantes sont des commandes de diagnostic de dépendances, pas des gates obligatoires de chaque delta.
+- **CMD-RUST-010** — `cargo update` n'est jamais exécuté opportunistement. Toute mise à jour de dépendance doit appartenir à une tranche explicitement consacrée aux dépendances ou être nécessaire à la fonctionnalité en cours.
+- **CMD-RUST-011** — `cargo clean` n'est pas une gate et n'est pas utilisé en routine. Il n'est autorisé qu'en cas de diagnostic de build corrompu, de contrainte disque explicite ou de demande ciblée, avec justification.
+- **CMD-RUST-012** — La suppression manuelle de `target/` ne remplace pas `cargo clean` et suit les mêmes restrictions.
 
 ## Runners Desktop
 

docs/rules/RULES_PROJECT.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_PROJECT.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Règles spécifiques games.sasedev
 
@@ -7,7 +7,7 @@
 
 - **GAME-WS-001** — Un seul workspace Cargo racine contient les crates Rust du dépôt.
 - **GAME-WS-002** — Toutes les crates Rust résident sous `crates/`.
-- **GAME-WS-003** — Les crates moteur résident sous `crates/engines/`, les crates jeu sous `crates/games/` et les exécutables/launchers réutilisant ces libs sous `crates/apps/`.
+- **GAME-WS-003** — Les crates moteur résident sous `crates/engines/`, les crates jeu sous `crates/games/`, les bibliothèques transverses indépendantes d’une génération de moteur sous `crates/common/` et les exécutables/launchers réutilisant ces libs sous `crates/apps/`.
 - **GAME-WS-004** — Une crate hérite par défaut de `workspace.package.version`.
 - **GAME-WS-005** — Une crate arrivée à maturité peut porter sa propre version SemVer lorsqu'une décision documentée rend son cycle autonome nécessaire.
 - **GAME-WS-006** — Les dépendances tierces communes sont centralisées sous `[workspace.dependencies]` et consommées avec `workspace = true` lorsqu'elles sont partagées.
@@ -54,3 +54,10 @@
 
 - **GAME-POC-001** — Les premiers POC servent à valider l'architecture et doivent rester volontairement petits.
 - **GAME-POC-002** — Un POC ne justifie pas l'introduction prématurée d'un ECS, moteur physique ou backend complet s'il n'en a pas besoin.
+
+## Diagnostics structurés
+
+- **GAME-TRACE-001** — `tracing` est le mécanisme Rust canonique pour les diagnostics structurés.
+- **GAME-TRACE-002** — `tracing-subscriber` compose les subscribers applicatifs et de test ; une librairie métier ne configure pas silencieusement le subscriber global.
+- **GAME-TRACE-003** — `tracing-appender` est utilisé lorsque l’écriture non bloquante ou les fichiers de logs deviennent nécessaires ; le guard associé reste vivant pendant toute la durée utile.
+- **GAME-TRACE-004** — La configuration de logging commune réside dans une crate transverse et ne doit pas être dupliquée par jeu.

docs/rules/RULES_RUST.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_RUST.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Règles Rust générales
 
@@ -35,8 +35,9 @@
 ## Formatage
 
 - **RUST-FMT-001** — `rustfmt.toml` racine est canonique.
-- **RUST-FMT-002** — `cargo fmt --all -- --check` fait partie des gates.
-- **RUST-FMT-003** — La largeur maximale canonique est 160 caractères.
+- **RUST-FMT-002** — Lorsqu’un delta modifie du code Rust, `cargo fmt --all` est exécuté avant la gate afin d’appliquer `rustfmt.toml`; les seules modifications produites par cette commande ne nécessitent pas d’incrémenter l’en-tête `// version: N` des fichiers concernés.
+- **RUST-FMT-003** — `cargo fmt --all -- --check` vérifie ensuite que l’état livré est conforme au formatage canonique.
+- **RUST-FMT-004** — La largeur maximale canonique est 160 caractères.
 
 ## Tests
 

docs/testing/001-TEST_ARCHITECTURE.md

@@ -0,0 +1,28 @@
+<!-- file: docs/testing/001-TEST_ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# Architecture des tests
+
+## Séparation physique
+
+Le code de production sous `src/` ne contient aucun corps de test. Les tests unitaires résident dans `unit_tests/` à la racine de la crate et sont rattachés explicitement au module testé :
+
+```rust
+#[cfg(test)]
+#[path = "../unit_tests/example.rs"]
+mod tests;
+```
+
+Les tests d’intégration, d’environnement et les smokes automatisés résident sous `tests/`, selon le mécanisme Cargo standard.
+
+Cette séparation reprend le modèle utilisé dans KSP : elle garde `src/` exclusivement consacré au code de production tout en permettant aux unit tests d’accéder au contexte privé du module auquel ils sont rattachés.
+
+## Tests ciblés
+
+Un delta ne relance pas automatiquement tous les tests du workspace. Les crates affectées sont testées explicitement avec `cargo test -p ... --all-targets --all-features`.
+
+La suite globale est conservée comme gate lourde pour les frontières de version, la stabilisation et les changements transverses dont l’impact ne peut pas être borné avec confiance.
+
+## Tracing dans les tests
+
+`game-logging-lib::with_test_tracing` installe un subscriber local au thread pour la durée du corps de test. Il évite les conflits liés à plusieurs initialisations globales et permet aux tests d’émettre des événements `tracing` consultables avec les mécanismes habituels du test runner.

docs/validation/001-VALIDATION_GATES.md

@@ -1,5 +1,5 @@
 <!-- file: docs/validation/001-VALIDATION_GATES.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Gates de validation
 
@@ -9,19 +9,34 @@ Les audits Python peuvent être exécutés pendant la préparation d'un delta. S
 
 Le générateur ne marque jamais une commande Cargo comme propre s'il ne dispose que du résultat d'un delta antérieur.
 
-## Gate canonique Rust et documentation
+## Gate normale d’un delta Rust
 
-À exécuter par l'utilisateur pour valider chaque delta contenant du code, du build, des manifests ou des règles affectant le workspace :
+Lorsqu’un delta modifie du code Rust, la validation commence par un formatage mutatif volontaire :
 
 ```bash
+cargo fmt --all
 cargo fmt --all -- --check
+```
+
+Les modifications exclusivement produites par `cargo fmt --all` n’imposent pas d’incrémenter `// version: N`, car elles font partie de la préparation du même état avant commit.
+
+Les audits et gates de compilation restent ensuite :
+
+```bash
 python3 scripts/audit_rust_workspace_rules.py
 python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates Android deltas
 cargo check --workspace
 cargo clippy --workspace --all-targets --all-features -- -D warnings
-cargo test --workspace --all-targets --all-features
 ```
 
+Les tests sont ciblés par défaut :
+
+```bash
+cargo test -p <crate-affectée> --all-targets --all-features
+```
+
+Le fichier delta énumère les crates à tester. `cargo test --workspace --all-targets --all-features` n’est demandé systématiquement qu’au démarrage d’une nouvelle version `X.Y.Z`, vers la fin d’une phase/version, après un changement transversal important ou lorsque l’impact réel ne permet pas de sélectionner avec confiance les tests ciblés.
+
 ## Smokes Desktop
 
 Lorsqu'un delta modifie la boucle exécutable, le runtime ou le comportement visible des runners Desktop, exécuter également :