00.01 — Cartographie de l’écosystème#

L’écosystème Ocarina est constitué de six dépôts publics sur le compte GitHub mojo-molotov. Ils s’organisent en cinq rôles distincts qui se composent :

Rôle	Dépôt	Forme
Framework	`ocarina`	Bibliothèque Python publiée sur PyPI
Application sous test (SUT) publique	`igoristan`	SPA React + Vike déployée sur GitHub Pages
Backend de coordination	`tests-workers`	API Vercel Edge + Upstash Redis
Suite d’exemples	`ocarina-example` (canonique), `ocarina-with-ai-example` (IA)	Projets Python e2e tournés vers l’Igoristan / CURA
Documentation publique	`ocarina-holy-book`	Site VitePress FR + EN, PDF, skills IA

Schéma d’ensemble (big picture)#

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              OCARINA (BIG PICTURE)                              │
└─────────────────────────────────────────────────────────────────────────────────┘

   ┌──────────────────────────────┐         ┌──────────────────────────────────┐
   │  [PACKAGE]  ocarina          │ ──────► │  [PACKAGE]  ocarina-example      │
   │  Framework Python 3.14+      │   pip   │  Suite e2e contre l'Igoristan    │
   │  ROP / DSL / orchestration   │ install │  (Selenium + Firefox + Redis)    │
   └──────────────────────────────┘         └──────────────────────────────────┘
            │  │                                       │  ▲   │
            │  │                                       │  │  utilise
            │  │ pip install ocarina                   │  │  IGOR_API_KEY
            │  ▼                                       ▼  │   │
            │  ┌────────────────────────────────────┐  pilote │
            │  │ [PACKAGE]  ocarina-with-ai-example │  ┌──────┴──────────────────┐
            │  │ Suite e2e CURA Healthcare          │  │ [WEBSITE]  igoristan    │
            │  │ Claude Code, 99% machine           │  │ React 19 + Vike         │
            │  └────────────────────────────────────┘  │ GitHub Pages            │
            │              │                           └──────┬──────────────────┘
            │              │ pilote                           │ fetch OTP
            │              ▼                                  ▼
            │   ┌──────────────────────────────┐    ┌──────────────────────────────┐
            │   │ [WEBSITE]  CURA Healthcare   │    │ [BACKEND]  tests-workers     │
            │   │ Heroku, PHP open source      │    │ Vercel Edge Functions        │
            │   └──────────────────────────────┘    │ + Upstash Redis              │
            │                                       │ /api/otp, /otp-history,      │
            │                                       │ /api/corsicadex              │
            │                                       └──────────────────────────────┘
            │                                                 ▲
            │                                                 │ x-api-key
            │                                                 │ (IGOR_API_KEY ≡ API_SECRET)
            │                                                 │
            ▼
   ┌──────────────────────────────┐
   │  [DOCS]  ocarina-holy-book   │
   │  VitePress FR + EN + RU      │
   │  Skills IA, PDF, llms.txt    │
   │  GitHub Pages                │
   └──────────────────────────────┘

ocarina → suites d’exemples : dépendance Python classique (pip install ocarina).
Suites d’exemples → SUT (Igoristan / CURA) : pilotage navigateur via Selenium.
Suite Igoristan ↔ tests-workers : appels HTTP (OTP, Corsicadex) ; le secret partagé IGOR_API_KEY (côté client) ≡ API_SECRET (côté serveur).

Responsabilités#

Rôle	Contrat	Besoin
Framework	Donner le DSL, l’orchestration, la pool de drivers, les reporters	Doit être petit, auditable, sans dépendances cachées
SUT public	Offrir un terrain de jeu volontairement chaotique (random errors, OTP, formulaires capricieux)	Hébergé en permanence sur GitHub Pages, sans backend lourd
Backend de coordination	Coordonner les workers sur l’OTP, fournir des données pour les tests parallèles	Stateless côté code, l’état vit dans Redis (Upstash)
Exemples	Démontrer comment on utilise réellement Ocarina, à la fois sans IA (canonique) et avec IA (CURA)	Doivent être publics, exécutables, complets, suivis en CI
Documentation	Transmettre le pourquoi, le comment, et l’usage IA	Doit exister en EN + FR + RU (tradition corso-russe), exposer des fichiers adaptés aux LLMs comme `llms.txt`, générer des PDF

Trois licences#

Licence	Dépôts concernés	Pourquoi
MIT	`ocarina`, `ocarina-example`, `ocarina-with-ai-example`, `ocarina-holy-book`	Tout ce qui est code Python ou doc, transmissible « tel quel », souverain — voir `../11-independence/`.
ISC	`tests-workers`	Choix par défaut du scaffold Vercel Edge, conservé.
(aucune licence)	`igoristan`	Application démo publique, hébergée par l’auteur (à considérer comme WTFPL).

Points de friction volontaires entre dépôts#

Le design est volontairement asymétrique sur certains axes ; ces frictions sont des outils de test :

L’Igoristan a un useAuth faux : Math.random() < 0.9 peut faire échouer le login même avec le bon mot de passe, ce qui force la stratégie de rejeu côté Ocarina. Voir ../05-igoristan/03-use-auth.md
tests-workers ampute volontairement les millisecondes du timestamp OTP (.000Z) pour forcer la coordination avec du delta timing. Voir ../06-tests-workers/07-otp-coordination-flow.md
CURA Healthcare contient des gaps connus documentés dans IDENTIFIED_GAPS.md : les tests qui leur sont associés sont intentionnellement en échec dans cette version de la suite IA. Voir ../08-ai-example/05-security-gaps.md
Le compteur Math.random() < 0.3 côté donkey-sausage-eater-detector exerce match_page (branchement sur états aléatoires). Voir ../05-igoristan/02-routes.md
La page random-error de l’Igoristan exerce les transient_errors (retry d’Ocarina) en levant des erreurs aléatoires. La chaotic form balance des erreurs au hasard sans impacter directement les tests, pour exercer les watchers. Des temps de chargement aléatoires permettent enfin de vérifier les flots de test face aux race conditions.

Ces frictions volontaires sont la raison d’être du SUT : un site qui marche tout le temps ne sert à rien pour démontrer un framework de test résilient.