v0.0.3-pre.003

docs/rules/RULES_DEPENDENCIES.md

@@ -1,36 +1,74 @@
 <!-- file: docs/rules/RULES_DEPENDENCIES.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Règles des dépendances KSP
 
 ## Portée
 
-Les règles `DEP-*` définissent quelles dépendances externes peuvent traverser les frontières KSP et quelles couches en sont propriétaires.
+Les règles `DEP-*` définissent quelles dépendances externes et internes peuvent traverser les frontières KSP et quelles couches en sont propriétaires.
 
-Elles complètent les règles Rust générales. Elles sont particulièrement strictes pour les crates liées à Solana et aux protocoles on-chain.
+Elles complètent les règles Rust générales et le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md`.
 
 ## Firewall des exécutables
 
-- **DEP-EXEC-001** — Les applications, demos et workers KSP ne dépendent directement d'aucune crate externe relative à Solana ou à un protocole Solana. Ils consomment exclusivement les bibliothèques KSP propriétaires de ces contrats.
-- **DEP-EXEC-002** — Une application peut dépendre directement de bibliothèques générales non-Solana nécessaires à son interface ou à son runtime, par exemple UI, sérialisation, Base64 ou Base58, à condition que ces dépendances ne portent pas une opération métier/protocolaire appartenant à KSP.
-- **DEP-EXEC-003** — Si un exécutable a besoin d'un type, d'une fonction ou d'un contrat Solana, la bibliothèque KSP propriétaire doit l'exposer ou fournir le wrapper/contrat approprié ; l'exécutable ne contourne pas cette frontière en ajoutant lui-même la crate Solana.
+- **DEP-EXEC-001** — Les applications, demos, workers et jobs KSP ne dépendent directement d'aucune crate externe relative à Solana ou à un protocole Solana. Ils consomment exclusivement les composants KSP propriétaires de ces contrats.
+- **DEP-EXEC-002** — Un exécutable peut dépendre directement de bibliothèques générales non-Solana nécessaires à son interface ou à son runtime, à condition qu'elles ne portent pas une opération métier/protocolaire appartenant à KSP.
+- **DEP-EXEC-003** — Si un exécutable a besoin d'un type, d'une fonction ou d'un contrat Solana, le composant KSP propriétaire doit l'exposer ou fournir le wrapper/contrat approprié.
+
+## Direction des dépendances internes
+
+- **DEP-KSP-001** — Une crate `ksp-<domain>-api` ne dépend jamais de l'implémentation officielle `ksp-<domain>-lib`.
+- **DEP-KSP-002** — Une bibliothèque basse de transformation/sémantique ne dépend pas d'un worker, job, application ou orchestrateur qui la consomme.
+- **DEP-KSP-003** — Les conversions entre modèles de transport, processing et persistence sont réalisées par les composants de composition appropriés plutôt que par des dépendances croisées entre domaines.
+- **DEP-KSP-004** — Aucun `ksp-data-api` global n'est introduit uniquement pour éviter des conversions explicites entre modèles appartenant à des responsabilités différentes.
+- **DEP-KSP-005** — Une dépendance autorisée par le graphe n'est ajoutée au manifeste que lorsqu'un usage réel la justifie.
+
+## Program / Execution
+
+- **DEP-PROGRAM-001** — `ksp-program-api` peut dépendre de `ksp-core-lib` et `ksp-interface-lib`.
+- **DEP-PROGRAM-002** — `ksp-program-lib` dépend de `ksp-program-api` et peut dépendre de `ksp-interface-lib`/`ksp-core-lib`.
+- **DEP-PROGRAM-003** — `ksp-program-api` et `ksp-program-lib` ne dépendent pas du wallet, du transport, du store ou des materializers.
+- **DEP-EXECUTION-001** — `ksp-execution-policy-api` dépend du contrat public Program, pas de l'implémentation `ksp-program-lib`.
+- **DEP-EXECUTION-002** — `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-execution-policy-api`, `ksp-wallet-lib` et `ksp-onchain-transport-lib`; il ne dépend pas de `ksp-program-lib`.
+- **DEP-EXECUTION-003** — Une implémentation de policy reste située dans une crate de scénario/domaine/produit appropriée et ne devient pas une responsabilité de `ksp-program-lib`.
+
+## Materializer / Store
+
+- **DEP-MAT-001** — `ksp-materializer-api` peut dépendre de `ksp-program-api` lorsque les contrats de matérialisation consomment des sorties canoniques de processing.
+- **DEP-MAT-002** — `ksp-materializer-api` et `ksp-materializer-lib` ne dépendent pas de `ksp-store-api` ou `ksp-store-lib`.
+- **DEP-STORE-001** — `ksp-store-api` ne dépend pas de Program, Materializer ou Transport.
+- **DEP-STORE-002** — `ksp-store-lib` dépend de `ksp-store-api` et contient l'implémentation PostgreSQL de référence ; il ne dépend pas des implémentations Program/Materializer/Transport.
+- **DEP-STORE-003** — Les workers/jobs spécialisés sont propriétaires des conversions entre modèles runtime et DTO persistants.
+
+## Transport
+
+- **DEP-TRANSPORT-001** — `ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api` ou `ksp-store-lib`.
+- **DEP-TRANSPORT-002** — Les providers on-chain normalisent leurs réponses dans des modèles KSP homogènes par catégorie de données avant exposition aux consommateurs.
+- **DEP-TRANSPORT-003** — Les modèles de transport ne réalisent pas de décodage métier/protocolaire et doivent rester facilement convertibles en DTO raw persistants.
+- **DEP-TRANSPORT-004** — Aucun `ksp-onchain-transport-api` ou `ksp-offchain-transport-api` global n'est créé dans l'architecture actuelle.
+
+## Worker / Job lifecycle
+
+- **DEP-WORKER-001** — `ksp-worker-control-lib` dépend de `ksp-worker-api` et ne dépend pas de `ksp-job-api`.
+- **DEP-JOB-001** — `ksp-job-api` ne dépend ni de `ksp-worker-api` ni de `ksp-worker-control-lib`.
+- **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun.
 
 ## Propriété des dépendances Solana
 
-- **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir une bibliothèque KSP propriétaire précise. Elle n'est pas ajoutée dans plusieurs couches uniquement parce qu'elle est pratique à utiliser.
+- **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir un composant KSP propriétaire précis.
 - **DEP-SOL-002** — Les bibliothèques KSP de haut niveau qui n'ont pas besoin d'un contrat externe bas niveau ne dépendent pas directement de ce contrat.
 - **DEP-SOL-003** — Les primitives Solana/Anza suffisamment fondamentales et stables peuvent être utilisées dans les bibliothèques KSP de bas niveau qui en sont propriétaires.
 - **DEP-SOL-004** — La liste initialement acceptée de primitives fondamentales comprend `solana-pubkey`, `solana-keypair`, `solana-signer`, `solana-hash` et `solana-nonce`.
-- **DEP-SOL-005** — L'ajout d'une autre crate Solana/Anza est décidé à partir d'un besoin concret et de sa stabilité/API ; l'appartenance au dépôt Solana/Anza ne constitue pas à elle seule une autorisation automatique.
-- **DEP-SOL-006** — Une bibliothèque KSP peut exposer ou réexporter une primitive externe fondamentale lorsque cette primitive fait intentionnellement partie du contrat KSP ; l'exécutable consommateur dépend alors de KSP, pas directement de la crate externe.
+- **DEP-SOL-005** — L'ajout d'une autre crate Solana/Anza est décidé à partir d'un besoin concret et de sa stabilité/API.
+- **DEP-SOL-006** — Une bibliothèque KSP peut exposer ou réexporter une primitive externe fondamentale lorsque cette primitive fait intentionnellement partie du contrat KSP.
 
 ## Crates de protocoles et interfaces wire
 
 - **DEP-PROTO-001** — Les crates d'interface/protocole externes telles que `mpl-token-metadata` ou `spl-elgamal-registry-interface` sont interdites par défaut comme dépendances runtime KSP.
 - **DEP-PROTO-002** — KSP préfère posséder ses représentations compatibles nécessaires : Program IDs, discriminants, layouts, enums, structures wire, règles de PDA, sérialisation/désérialisation et autres contrats effectivement requis.
 - **DEP-PROTO-003** — Une réimplémentation KSP vise le contrat nécessaire et ne consiste pas à copier mécaniquement l'architecture ou l'intégralité d'une crate externe.
-- **DEP-PROTO-004** — La méthode de vérification de compatibilité wire, l'usage éventuel de dépendances externes uniquement en tests de conformité et les contraintes de licence/source de vérité restent à définir avant la première implémentation de protocole concernée.
-- **DEP-PROTO-005** — Une dépendance protocolaire externe exceptionnellement nécessaire doit être explicitement justifiée, confinée à la bibliothèque propriétaire la plus basse possible et documentée avec sa version, sa raison et sa condition de suppression ou réévaluation.
+- **DEP-PROTO-004** — La méthode de vérification de compatibilité wire et l'usage éventuel de dépendances externes uniquement en tests de conformité doivent être définis avant la première implémentation concernée.
+- **DEP-PROTO-005** — Une dépendance protocolaire externe exceptionnellement nécessaire doit être explicitement justifiée et confinée au composant propriétaire le plus bas possible.
 
 ## Versions
 

docs/rules/RULES_KSP.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_KSP.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Règles spécifiques à KSP
 
@@ -33,9 +33,9 @@
 - **KSP-PROGRAM-004** — Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable.
 - **KSP-PROGRAM-005** — Une opération devenue obsolète mais toujours identifiable/exécutable peut rester implémentée dans l'executor et être marquée `deprecated`.
 - **KSP-PROGRAM-006** — `ksp-program-lib` ne contient pas la politique de sécurité de production.
-- **KSP-EXEC-001** — La direction retenue est une API de policy d'exécution séparée, candidate `ksp-execution-policy-api`, afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`.
+- **KSP-EXEC-001** — `ksp-execution-policy-api` est retenu comme API publique de policy d'exécution afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`.
 - **KSP-EXEC-002** — Une application UI sélectionne/injecte une implémentation de policy réutilisable ; elle ne doit pas enfouir une politique d'exécution complexe dans sa couche d'interface.
-- **KSP-EXEC-003** — `ksp-execution-lib` est un candidat fort d'orchestration spécialisée entre programme, policy, wallet et transport. Son graphe exact est reporté à l'étude des dépendances.
+- **KSP-EXEC-003** — `ksp-execution-lib` est retenu comme orchestration spécialisée entre programme, policy, wallet et transport. Il dépend de `ksp-program-api` et non de `ksp-program-lib`.
 
 ## Transports
 
@@ -71,11 +71,18 @@
 - **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie.
 - **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers.
 
+## Matérialisation et persistence
+
+- **KSP-MAT-001** — `ksp-materializer-api` peut dépendre de `ksp-program-api` ; `ksp-materializer-lib` dépend de son API mais ne dépend pas du store.
+- **KSP-MAT-002** — `ksp-materializer-api` / `ksp-materializer-lib` ne réalisent pas eux-mêmes la persistance ; les workers/jobs/pipelines spécialisés composent matérialisation et store.
+- **KSP-STORE-001** — `ksp-store-api` reste indépendant des APIs Program/Materializer/Transport et possède les contrats persistants.
+- **KSP-STORE-002** — Les conversions entre modèles runtime et DTO persistants sont explicites aux frontières de composition ; aucun `ksp-data-api` global n'est introduit actuellement.
+
 ## Notifications de données
 
 - **KSP-DATA-001** — Une notification de donnée décrit la donnée disponible et non le worker/job qui l'a produite.
 - **KSP-DATA-002** — Le même type de donnée utilise le même contrat de notification quelle que soit son origine : worker, job, import ou autre source.
-- **KSP-DATA-003** — `ksp-store-api` est le propriétaire candidat des références/notifications canoniques de données persistées lorsque ces contrats appartiennent naturellement à la frontière store.
+- **KSP-DATA-003** — `ksp-store-api` est le propriétaire retenu des références/notifications canoniques lorsqu'elles signifient qu'une donnée persistée est disponible.
 - **KSP-DATA-004** — Le contrat de notification est séparé de son mécanisme de transport concret.
 
 ## Pipelines et scénarios