# Contrats initiaux des composants KSP ## Convention API / implémentation Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP sépare : ```text ksp--api ksp--lib ``` La crate `ksp--api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`. Elle expose principalement des traits, types, enums et contrats publics ; elle peut être consommée par plusieurs implémentations et n'est pas, à elle seule, une implémentation fonctionnelle destinée aux exécutables. La crate `ksp--lib` contient l'implémentation officielle KSP correspondante lorsqu'une telle implémentation existe. Cette séparation n'est pas automatique pour tous les domaines. Elle est utilisée lorsqu'une vraie frontière d'extension ou de backend justifie une API indépendante. Premiers couples retenus : - `ksp-program-api` + `ksp-program-lib` ; - `ksp-materializer-api` + `ksp-materializer-lib` ; - `ksp-store-api` + `ksp-store-lib`. Un unique `ksp-api-lib` monolithique est rejeté. ## `ksp-program-api` / `ksp-program-lib` `ksp-program-api` possède les contrats publics communs de décodage/exécution. Une crate séparée doit pouvoir implémenter et tester ces contrats sans dépendre de `ksp-program-lib`. `ksp-program-lib` contient les implémentations officielles intégrées des Program IDs supportés. Le decoder vise toute surface techniquement décodable dont la définition est connue. Le statut `deprecated` concerne l'exécution, pas le décodage. 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. L'executor expose les opérations techniquement exécutables connues ; une opération obsolète mais encore identifiable/exécutable peut rester implémentée et être marquée `deprecated`. La politique de sécurité appartient à une couche supérieure. ## `ksp-materializer-api` / `ksp-materializer-lib` `ksp-materializer-api` possède les contrats publics/extensibles de matérialisation. Une crate externe doit pouvoir implémenter un materializer contre cette API sans dépendre de `ksp-materializer-lib`. `ksp-materializer-lib` contient les materializers officiels intégrés KSP. ## `ksp-store-api` / `ksp-store-lib` `ksp-store-api` possède les contrats backend-agnostic de persistance et d'accès aux données KSP. `ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence : configuration/connexion, migrations, repositories, queries et mécanismes backend nécessaires. Les applications, workers, jobs et materializers consomment les contrats KSP et ne contournent pas le store pour accéder directement au backend. ## Notifications de données Une notification de donnée décrit la donnée disponible, pas son producteur. Le même type de donnée doit utiliser le même contrat de notification qu'elle provienne : - de W1 ; - d'un job de backfill ; - d'un import ; - d'une autre source future. `ksp-store-api` est le propriétaire candidat des références/événements canoniques indiquant qu'une donnée persistée est disponible, par exemple conceptuellement `RawDataRef` / `RawDataAvailable`. Le contrat de notification reste distinct du mécanisme de transport concret : channel in-process, PostgreSQL LISTEN/NOTIFY, IPC, broker ou autre mécanisme futur. ## Workers Les workers sont des services continus/live. Leurs contrats communs appartiennent à : ```text ksp-worker-api ``` Cette API ne contient aucun contrat de job. Une future implémentation commune de gouvernance/contrôle des workers peut vivre dans : ```text ksp-worker-control-lib ``` W1 reste un worker d'acquisition raw live/quasi-live : configuration, transport, persistance raw, reconfiguration à chaud et notification de disponibilité. Il ne décode pas, ne matérialise pas et ne réalise aucun replay/backfill historique. ## Jobs Les jobs sont des travaux déclenchés à la demande, suivables et terminables. Leurs contrats communs appartiennent à : ```text ksp-job-api ``` Cette API ne contient aucun contrat de worker. Les implémentations concrètes utilisent le préfixe `ksp-job-`. Premier candidat retenu : ```text ksp-job-backfill ``` D'autres jobs pourront être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel existe. Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers, même si certaines opérations semblent similaires. ## Pipelines KSP ne prévoit pas de `ksp-pipeline-lib` monolithique. Lorsqu'un pipeline réutilisable devient nécessaire, il est introduit séparément avec un périmètre concret et borné. ## Demos et scénarios Il n'existe pas de crate monolithique `ksp-scenarios-lib`. Les scénarios sont organisés en crates spécialisées par domaine cohérent, par exemple : ```text ksp-scenario-memo-lib ksp-scenario-token-lib ksp-scenario-ata-lib ksp-scenario-token-2022-lib ksp-scenario-metadata-lib ksp-scenario-spm-lib ``` Les metadata d'assets/tokens peuvent regrouper Metaplex Token Metadata et Token-2022 Metadata. Solana Program Metadata reste séparé.