khadhroony-solana-project/docs/rules/RULES_DEPENDENCIES.md

<!-- file: docs/rules/RULES_DEPENDENCIES.md -->
<!-- version: 2 -->

# Règles des dépendances KSP

## Portée

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 et le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md`.

## Firewall des exécutables

- **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 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.
- **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 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

- **DEP-VER-001** — KSP privilégie les versions récentes compatibles des dépendances.
- **DEP-VER-002** — Une version volontairement ancienne, bornée ou incompatible avec la politique générale est documentée avec la raison, le propriétaire et la condition permettant de lever la contrainte.
- **DEP-VER-003** — Les lockfiles ne servent pas à figer silencieusement une version de dépendance ; les contraintes nécessaires appartiennent aux manifests et à la documentation.