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

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.

Codecs wire et cohérence des versions

• DEP-WIRE-001 — Pour les surfaces wire officielles KSP, les dépendances directes vers borsh, wincode ou codecs équivalents appartiennent normalement à ksp-interface-lib.
• DEP-WIRE-002 — ksp-program-lib ne redécode pas directement une surface possédée par ksp-interface-lib avec sa propre dépendance codec.
• DEP-WIRE-003 — Une crate d'interface externe est retenue seulement si sa source/API et son graphe de dépendances sont suffisamment compatibles avec le stack KSP actuel.
• DEP-WIRE-004 — Une crate protocolaire externe qui impose une génération ancienne/incompatible d'une dépendance fondamentale peut être remplacée par une réimplémentation KSP bornée aux contrats wire nécessaires.
• DEP-WIRE-005 — Les doublons de générations de dépendances fondamentales sont audités et les doublons évitables doivent être éliminés ; un doublon inévitable requiert une justification.
• DEP-WIRE-006 — KSP cherche des versions récentes compatibles et ne fixe pas arbitrairement une ancienne version uniquement pour conserver une crate protocolaire remplaçable.
• DEP-WIRE-007 — Une extension Program externe peut posséder temporairement son propre wire lorsqu'aucune interface officielle KSP correspondante n'existe encore.

Logging

• DEP-LOG-001 — ksp-logging-lib est le propriétaire KSP direct de tracing, tracing-appender, tracing-subscriber et de l'initialisation/configuration logging.
• DEP-LOG-002 — ksp-logging-lib peut dépendre de ksp-core-lib pour le contrat commun Error / Result.
• DEP-LOG-003 — ksp-core-lib ne dépend pas de ksp-logging-lib dans l'architecture actuelle.
• DEP-LOG-004 — Les crates KSP comportant du runtime peuvent dépendre directement de ksp-logging-lib et ne dépendent normalement pas directement de tracing.
• DEP-LOG-005 — Les crates *-api purement déclaratives n'ajoutent pas une dépendance logging sans comportement réel à instrumenter.
• DEP-LOG-006 — Une application/framework peut exceptionnellement intégrer directement un plugin/dépendance tracing imposé par son framework, notamment Tauri, sans créer une seconde politique de logging parallèle à ksp-logging-lib.

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-PROGRAM-004 — Une implémentation externe ksp-program-<name>-lib peut dépendre directement de ksp-program-api sans dépendre de ksp-program-lib.
• DEP-EXECUTION-001 — ksp-execution-policy-api dépend du contrat public Program et de Core, pas de ksp-program-lib, wallet, transport, store ou UI.
• DEP-EXECUTION-002 — ksp-execution-lib dépend de ksp-program-api, ksp-execution-policy-api, ksp-wallet-lib, ksp-onchain-transport-lib, ksp-logging-lib et Core ; 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.
• DEP-EXECUTION-004 — Une exécution réelle reçoit explicitement une policy ; aucun fallback permissif implicite n'est prévu.
• DEP-EXECUTION-005 — La policy décide/refuse/contraint mais ne réalise pas la simulation, la signature, le transport réseau ou l'interaction UI.
• DEP-EXECUTION-006 — Wallet/signers et provider/transport sont fournis/sélectionnés par la composition supérieure ; ksp-execution-lib les orchestre sans définir leur policy de sélection.
• DEP-EXECUTION-007 — Le retry réseau d'un appel identique appartient au transport ; un retry modifiant le lifecycle d'exécution appartient à ksp-execution-lib.
• DEP-EXECUTION-008 — ksp-execution-lib ne dépend ni de ksp-store-api ni de ksp-store-lib; la persistence d'un résultat appartient à une composition supérieure.

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-MAT-003 — Une matérialisation générique doit pouvoir produire un output compatible avec le journal D3 sans imposer une table PostgreSQL spécialisée par materializer.
• 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.
• DEP-STORE-004 — Les niveaux durables sont D1 Raw, D2 Core canonique, D3 journal de matérialisation générique et D4 projections spécialisées.
• DEP-STORE-005 — Les replays D1 -> D2, D2 -> D3 et D3 -> D4 doivent pouvoir être exécutés indépendamment.
• DEP-STORE-006 — Une notification de donnée persistée ne constitue jamais la source de vérité du backlog ; les queries Store et marqueurs durables d'idempotence/version de processor font autorité.
• DEP-STORE-007 — Une notification de donnée est publiée seulement après persistence/commit réussis.
• DEP-STORE-008 — D4 est organisé par faits canoniques quand les invariants le permettent, et non par familles de tables propres aux protocoles.

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.

Pipelines spécialisés

• DEP-PIPE-001 — KSP ne crée pas de ksp-pipeline-lib monolithique.
• DEP-PIPE-002 — Les pipelines spécialisés retenus pour les frontières durables sont ksp-pipeline-raw-ingestion-lib, ksp-pipeline-core-processing-lib, ksp-pipeline-generic-materialization-lib et ksp-pipeline-domain-projection-lib.
• DEP-PIPE-003 — Un pipeline de processing dépend des APIs nécessaires à sa frontière et non des implémentations officielles correspondantes lorsque l'API permet l'injection/composition.
• DEP-PIPE-004 — Les pipelines spécialisés ne dépendent pas de ksp-worker-api ou ksp-job-api; worker et job possèdent le lifecycle.
• DEP-PIPE-005 — Worker live et job de replay/backfill réutilisent le même pipeline pour une même frontière durable afin d'éviter la duplication de logique.
• DEP-PIPE-006 — Le pipeline raw ingestion peut dépendre des modèles homogènes de ksp-onchain-transport-lib et de ksp-store-api, mais pas de ksp-store-lib.
• DEP-PIPE-007 — Le pipeline Core processing dépend de ksp-program-api et non de ksp-program-lib.
• DEP-PIPE-008 — Les pipelines de matérialisation/projection dépendent de ksp-materializer-api et non de ksp-materializer-lib.

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-WORKER-002 — Les workers de processing reconstruisent leur backlog depuis ksp-store-api/Store ; une notification ne suffit pas à prouver qu'un input a été traité.
• DEP-WORKER-003 — Les workers concrets peuvent dépendre de ksp-store-lib et des implémentations officielles Program/Materializer nécessaires à la composition.
• 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.
• DEP-JOB-003 — Les jobs de replay réutilisent les pipelines des workers correspondants au lieu de dupliquer la logique D1 -> D2, D2 -> D3 ou D3 -> D4.

Services, applications et control plane

• DEP-SERVICE-001 — Chaque worker concret doit pouvoir fonctionner comme service/processus indépendant.
• DEP-SERVICE-002 — La direction de packaging préférée est un package ksp-worker-<role> contenant une cible bibliothèque réutilisable et une cible binaire autonome mince.
• DEP-SERVICE-003 — Un worker concret ne dépend pas d'un autre worker concret ; les données transitent par les niveaux durables Store.
• DEP-SERVICE-004 — Le binaire worker compose/initialise le service mais ne duplique pas le pipeline ou la logique métier de sa cible bibliothèque.
• DEP-CONTROL-001 — ksp-worker-api définit la sémantique de lifecycle indépendamment du transport local/IPC.
• DEP-CONTROL-002 — ksp-worker-control-lib dépend de ksp-worker-api et peut plus tard adapter des handles locaux ou proxies distants.
• DEP-CONTROL-003 — Le control plane ne transporte pas les payloads D1/D2/D3/D4 entre workers.
• DEP-CONTROL-004 — Aucun ksp-ipc-api générique n'est introduit avant le premier besoin concret de transport de control.
• DEP-APP-001 — Les applications spécialisées sont privilégiées avant une future application globale.
• DEP-APP-002 — Une app manager worker pilote le service via les contrats de control et ne modifie pas directement son état interne de processing dans PostgreSQL.
• DEP-SCENARIO-001 — Une app scenario dépend de ksp-scenario-<domain>-lib ; le workflow du scenario ne réside pas dans l'application.
• DEP-SCENARIO-002 — Une crate scenario ne dépend pas de Tauri et doit pouvoir être appelée depuis d'autres interfaces/tests.

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.