Règles spécifiques à KSP

Nomenclature

KSP-NAME-001 — Une bibliothèque Rust d'implémentation réutilisable se nomme ksp-<role>-lib, sauf famille explicitement définie par une règle plus spécifique.
KSP-NAME-002 — Une crate publique de contrats extensibles se nomme ksp-<domain>-api. Elle est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe -lib.
KSP-NAME-003 — Une crate ksp-<domain>-api expose principalement les types/traits/contrats nécessaires aux implémentations ; elle n'est pas une implémentation fonctionnelle directement destinée aux exécutables.
KSP-NAME-004 — Une application se nomme ksp-app-<role>-<interface> lorsque l'interface doit être indiquée.
KSP-NAME-005 — Un worker continu se nomme ksp-worker-<role>.
KSP-NAME-006 — Un job ponctuel/historique/terminable se nomme ksp-job-<role>.
KSP-NAME-007 — Une démonstration se termine par -demo.
KSP-NAME-008 — Les crates Rust sont placées directement sous crates/.

KSP-API-001 — Un domaine extensible peut séparer ksp-<domain>-api et ksp-<domain>-lib.
KSP-API-002 — Les premiers couples retenus sont ksp-program-api / ksp-program-lib, ksp-materializer-api / ksp-materializer-lib et ksp-store-api / ksp-store-lib.
KSP-API-003 — KSP ne crée pas de ksp-api-lib monolithique regroupant les contrats de domaines indépendants.
KSP-API-004 — Un contrat public extensible doit pouvoir être implémenté depuis une crate séparée du workspace principal lorsque cela est techniquement pertinent.
KSP-API-005 — Les signatures des contrats publics utilisent en priorité des types publics KSP et les primitives externes explicitement admises ; elles ne doivent pas imposer des détails internes instables.
KSP-API-006 — ksp-store-lib contient PostgreSQL comme implémentation officielle de référence derrière ksp-store-api.

KSP-PROGRAM-001 — Les contrats decoder/executor appartiennent à ksp-program-api; les implémentations officielles intégrées appartiennent à ksp-program-lib.
KSP-PROGRAM-002 — Le decoder vise toute surface techniquement décodable dont la définition est connue, y compris les formats anciens, obsolètes ou expérimentaux encore distinguables.
KSP-PROGRAM-003 — Le statut deprecated concerne la capacité d'exécution, pas la capacité de décodage.
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-WORKER-001 — Un worker représente un service continu/live ; il est distinct d'un job.
KSP-WORKER-002 — Les contrats communs des workers appartiennent à ksp-worker-api et ne contiennent aucun contrat propre aux jobs.
KSP-WORKER-003 — ksp-worker-control-lib est le candidat d'implémentation commune de gouvernance/contrôle des workers lorsque plusieurs consommateurs le justifient.
KSP-WORKER-004 — W1 est un worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
KSP-WORKER-005 — W1 persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
KSP-WORKER-006 — W1 doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.

KSP-JOB-001 — Un job représente un travail déclenché à la demande, suivable et terminable ; il est distinct d'un worker continu.
KSP-JOB-002 — Les contrats communs des jobs appartiennent à ksp-job-api et ne contiennent aucun contrat propre aux workers.
KSP-JOB-003 — Les implémentations concrètes utilisent le préfixe ksp-job-.
KSP-JOB-004 — ksp-job-backfill est le candidat retenu pour le backfill historique ; il ne doit pas être implémenté comme un mode W1.
KSP-JOB-005 — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
KSP-JOB-006 — Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers.

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-004 — Le contrat de notification est séparé de son mécanisme de transport concret.

KSP-PIPE-001 — KSP ne crée pas de ksp-pipeline-lib monolithique. Les pipelines sont introduits séparément à la demande selon leur responsabilité réelle.
KSP-DEMO-001 — Il n'existe pas de crate monolithique ksp-scenarios-lib.
KSP-DEMO-002 — Les scénarios sont séparés en crates ksp-scenario-<domain>-lib par responsabilité fonctionnelle cohérente.
KSP-DEMO-003 — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés.
KSP-DEMO-004 — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé.
KSP-DEMO-005 — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow.

KSP-APP-001 — Une application KSP est une interface et une couche de composition. Elle ne réimplémente pas une opération appartenant conceptuellement à un composant KSP réutilisable inférieur.
KSP-APP-002 — Les applications/demos ne dépendent pas directement de crates Solana/protocoles externes.
KSP-APP-003 — Les applications/demos peuvent réaliser les opérations strictement liées à l'interface, mais pas la logique métier/protocolaire réutilisable.