Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.0.3-pre.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-14 00:03:57 +02:00
parent 4032298589
commit 5a86808376
23 changed files with 1845 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/rules/FILE_CONTRACTS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/FILE_CONTRACTS.md -->
<!-- version: 6 -->
<!-- version: 8 -->
# Contrats des fichiers
@@ -23,15 +23,25 @@ Les règles `FILE-*` définissent la responsabilité et le mode de modification
## Répertoire `docs/`
| Fichier/famille | Responsabilité | Règle de modification |
|---------------------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `docs/000-README.md` | Indexer et expliquer la documentation tout en restant en tête des listings et arbres de fichiers. | Modifier lorsque l'organisation durable de `docs/` change ; `000-README.md` reste prioritaire lorsqu'un ordre numérique existe. |
| `docs/rules/*.md` | Définir les règles normatives par portée. | Modifier uniquement pour une décision normative ; incrémenter la version du fichier à chaque enregistrement modifiant son contenu. |
| `docs/IDEAS.md` | Conserver les idées, pistes, questions et alternatives à explorer qui ne sont pas encore des engagements du roadmap. | Ajouter une idée dès qu'elle mérite d'être conservée ; mettre à jour son statut lorsqu'elle est explorée, retenue, rejetée ou transférée vers un plan, le roadmap, une règle ou une décision. |
| futurs documents d'architecture | Décrire l'architecture courante décidée. | Ne pas utiliser comme journal de livraison ; reporter les décisions depuis les deltas/plans. |
| futurs documents de référence | Définir vocabulaire, identifiants et références canoniques. | Mettre à jour quand la référence canonique évolue. |
| futurs plans | Organiser une phase ou version complexe. | Ils peuvent évoluer pendant la phase ; leur statut normatif doit être explicite. |
| futures validations | Conserver des résultats réellement exécutés. | Ne jamais enregistrer une validation supposée comme réussie. |
| Fichier/famille | Responsabilité | Règle de modification |
|-----------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `docs/000-README.md` | Indexer et expliquer la documentation tout en restant en tête des listings et arbres de fichiers. | Modifier lorsque l'organisation durable de `docs/` change ; `000-README.md` reste prioritaire lorsqu'un ordre numérique existe. |
| `docs/rules/*.md` | Définir les règles normatives par portée. | Modifier uniquement pour une décision normative ; incrémenter la version du fichier à chaque enregistrement modifiant son contenu. |
| `docs/rules/PROMPT_STRUCTURE.md` | Définir la structure, le cycle de vie et le dimensionnement des prompts/sessions KSP. | Modifier lorsque le contrat des prompts ou les règles de découpage de sessions/prereleases changent. |
| `docs/architecture/000-README.md` | Indexer les documents décrivant l'architecture KSP décidée ou en cours de cadrage explicite. | Modifier lorsque la structure documentaire d'architecture change. |
| `docs/architecture/*.md` | Décrire les objectifs, frontières, responsabilités et architecture courante ou explicitement proposée. | Ne pas utiliser comme journal de livraison ; distinguer clairement les décisions validées des hypothèses encore ouvertes. |
| `docs/plans/000-README.md` | Indexer les plans de versions/phases. | Modifier lorsque l'organisation des plans change. |
| `docs/plans/*.md` | Organiser une version ou phase complexe et, pour `pre.001`, détailler la prévision souple de ses prereleases. | Faire évoluer le plan lorsque la planification change ; prévoir des tranches intermédiaires bornées et redécouper toute tranche estimée trop lourde. |
| `docs/IDEAS.md` | Conserver les idées, pistes, questions et alternatives à explorer qui ne sont pas encore des engagements du roadmap. | Ajouter une idée dès qu'elle mérite d'être conservée ; mettre à jour son statut lorsqu'elle est explorée, retenue, rejetée ou transférée. |
| futurs documents de référence | Définir vocabulaire, identifiants et références canoniques. | Mettre à jour quand la référence canonique évolue. |
| futures validations | Conserver des résultats réellement exécutés. | Ne jamais enregistrer une validation supposée comme réussie. |
## Répertoire `prompts/`
| Fichier/famille | Responsabilité | Règle de modification |
|-----------------------------|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `prompts/000-README.md` | Point d'entrée des prompts et de leur cycle de vie. | Modifier lorsque l'organisation pratique des prompts change ; les règles normatives restent sous `docs/rules/PROMPT_STRUCTURE.md`. |
| `prompts/*START_PROMPT*.md` | Conserver un prompt de reprise versionné et réutilisable pour ouvrir une phase/version de travail. | Le créer tôt sous forme de brouillon lorsque la trajectoire devient assez claire, le mettre à jour au fil des décisions, puis le finaliser pendant la phase documentaire de clôture avant son utilisation. |
## Répertoire `deltas/`
@@ -54,4 +64,4 @@ Les règles `FILE-*` définissent la responsabilité et le mode de modification
- **FILE-GEN-001** — Un fichier généré n'est jamais modifié manuellement lorsque sa source de vérité est un générateur.
- **FILE-GEN-002** — Le choix de versionner ou ignorer une famille générée est décidé explicitement lorsqu'elle apparaît.
- **FILE-GEN-003** — Les futurs artefacts Tauri `bindings/` et `gen/` ne sont pas encore une convention KSP en `0.0.2-pre.001-fix.001`.
- **FILE-GEN-003** — Les futurs artefacts Tauri `bindings/` et `gen/` ne sont pas encore une convention KSP ; ils seront traités lorsqu'ils apparaîtront.

203
docs/rules/PROMPT_STRUCTURE.md Normal file
View File

@@ -0,0 +1,203 @@
<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
<!-- version: 2 -->
# Structure des prompts KSP
## Portée
Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des sessions/prereleases qu'ils préparent.
Les prompts eux-mêmes sont conservés sous `prompts/`.
## Objectif
Un prompt doit permettre de reprendre le travail sans reconstituer manuellement :
- la mission de la phase ;
- la base Git/version ;
- l'état validé à préserver ;
- les règles applicables ;
- l'architecture déjà décidée ;
- les questions encore ouvertes ;
- les sources externes normatives lorsqu'elles existent ;
- le plan souple ;
- le mode de livraison ;
- les validations et critères de sortie.
Le prompt ne remplace jamais les sources de vérité du dépôt.
## Cycle de vie
Un prompt de prochaine grande phase est créé dès que sa direction devient suffisamment claire.
Il passe par trois états conceptuels :
1. **Brouillon** — créé tôt et volontairement incomplet ;
2. **Quasi-final** — mis à jour lorsque les frontières, crates, dépendances et objectifs sont suffisamment stabilisés ;
3. **Final** — vérifié pendant la phase documentaire de clôture et prêt à être utilisé comme point de départ de la session/version suivante.
Le prompt de la phase suivante doit être maintenu pendant la phase courante lorsque de nouvelles décisions changent matériellement son futur démarrage.
## Première et dernière prerelease d'une version
Sauf raison explicitement documentée :
- la première prerelease (`pre.001`) est consacrée au brainstorming, à l'audit lorsque nécessaire, à la planification, aux décisions de périmètre et au découpage souple des prereleases suivantes ;
- la dernière prerelease est consacrée à la validation finale, à la documentation, au nettoyage/archivage nécessaire, à la synchronisation des documents de release et à la finalisation du prompt de la session/version suivante.
Le développement fonctionnel significatif ne doit pas précéder le cadrage suffisant de `pre.001`.
## Dimensionnement des prereleases
Pendant l'élaboration du plan de `pre.001`, les prereleases de travail situées après `pre.001` et avant la prerelease finale de clôture doivent être conçues comme des tranches bornées.
Lors de la planification, une tranche dont la charge estimée paraît dépasser approximativement **15 à 20 minutes de travail effectif de session** doit être scindée en plusieurs prereleases ou sous-objectifs livrables séparément.
Cette durée est un budget de planification, pas une promesse de temps d'exécution. Elle sert à empêcher les tranches trop larges, difficiles à valider ou à corriger.
Si la complexité réelle découverte en cours de travail dépasse l'estimation, la tranche doit être redécoupée plutôt que surchargée.
## Dimensionnement d'une session ou d'une version
Avant de finaliser le prompt de la session suivante, il faut évaluer la charge totale produite par le plan prévu.
Si un prompt risque de générer trop de prereleases, trop de fichiers, trop de décisions ou un contexte trop lourd pour une seule session de qualité, le périmètre doit être découpé :
- en plusieurs sessions conservant éventuellement la même série/version lorsque la continuité fonctionnelle le justifie ;
- et/ou en plusieurs versions lorsque la séparation correspond à une frontière fonctionnelle plus propre.
Exemple : si une version prévue pour introduire decoder + executor devient manifestement trop lourde après planification, la continuité du roadmap est conservée mais le travail peut être réparti sur plusieurs sessions ou versions.
La qualité du contexte, la testabilité et la cohérence architecturale priment sur le maintien artificiel d'un découpage de versions imaginé plus tôt.
## Structure recommandée d'un prompt
### 1. Identité de la phase
Indiquer :
- version ou série visée ;
- titre court ;
- nature de la session : brainstorming, planification, développement, audit, validation, clôture, etc.
### 2. Mission
Décrire l'état concret à atteindre pendant la phase.
La mission ne doit pas être une simple liste de fichiers à modifier.
### 3. Base requise
Indiquer :
- version/tag/commit de départ ;
- état attendu du workspace ;
- fichiers/documents fondamentaux déjà présents.
### 4. État validé à préserver
Lister les éléments déjà validés qui ne doivent pas régresser pendant la nouvelle phase, par exemple :
- APIs déjà stabilisées ;
- comportements fonctionnels validés ;
- tests/scénarios connus comme passants ;
- décisions gelées ou fortement contraintes ;
- problèmes explicitement reportés qui ne doivent pas être rouverts sans raison.
Cette section est distincte de la simple base Git/version.
### 5. Sources de vérité internes à relire
Lister explicitement les documents nécessaires, en priorité :
- `RULES.md` et règles spécialisées pertinentes ;
- `ROADMAP.md` ;
- plan de version actif ;
- architecture concernée ;
- `docs/IDEAS.md` lorsqu'une question ouverte est pertinente ;
- dernier delta/release utile.
Le prompt doit renvoyer aux sources de vérité au lieu de les recopier intégralement.
### 6. Sources externes normatives
Lorsqu'une phase concerne un protocole, programme, standard ou API externe, lister les sources qui font autorité :
- dépôt upstream officiel ;
- documentation officielle ;
- IDL/schema officiel ;
- Program ID ;
- format wire ;
- spécification normative ;
- autre source externe explicitement retenue.
Une copie historique locale ne doit pas être traitée comme source de vérité actuelle lorsque la phase exige une vérification upstream.
### 7. Décisions acquises
Résumer uniquement les décisions indispensables pour éviter une mauvaise direction au démarrage.
### 8. Objectifs et livrables
Lister les objectifs principaux et les artefacts attendus.
### 9. Hors périmètre
Indiquer ce qui ne doit explicitement pas être ouvert pendant la phase.
### 10. Méthode de travail
Rappeler la séquence KSP applicable :
1. brainstorming ;
2. planification ;
3. développement lorsque la phase est fonctionnelle ;
4. tests/validations ;
5. documentation finale ;
6. mise à jour/préparation du prompt suivant.
Une phase fondatrice/documentaire adapte la partie développement à son objet.
### 11. Versionnement et deltas
Rappeler :
- version Cargo attendue ;
- format du delta ;
- règle des fixes techniques/documentaires ;
- politique de commits de la phase ;
- règle de découpage des livraisons trop volumineuses.
### 12. Contraintes techniques spécifiques
Lister uniquement les contraintes importantes pour cette phase : dépendances, environnements, sécurité, API publique, stockage, transport, etc.
### 13. Plan initial souple
Pour un `pre.001`, fournir la prévision souple des prereleases ou étapes principales.
Chaque tranche intermédiaire doit respecter le budget de complexité défini plus haut et être redécoupée si nécessaire.
### 14. Validations attendues
Indiquer les commandes/tests/audits pertinents et interdire de déclarer une validation non exécutée.
### 15. Critères de sortie
Décrire les conditions nécessaires pour considérer la phase terminée.
### 16. Préparation de la suite
Indiquer quel document/prompt doit être produit ou mis à jour avant la clôture.
Avant finalisation de ce prompt suivant, appliquer obligatoirement le contrôle de dimensionnement de session/version.
## Règles de rédaction
- Le prompt est précis mais évite de dupliquer plusieurs pages déjà présentes dans les documents canoniques.
- Une règle normative appartient d'abord à `docs/rules/`, pas seulement au prompt.
- Une décision architecturale durable appartient à `docs/architecture/`, pas seulement au prompt.
- Une idée non décidée appartient à `docs/IDEAS.md`.
- Le prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
- Les chemins et versions mentionnés doivent être cohérents avec le dépôt au moment de la finalisation.
- Un prompt final ne doit pas préparer une session manifestement surdimensionnée.

39
docs/rules/RULES_DEPENDENCIES.md Normal file
View File

@@ -0,0 +1,39 @@
<!-- file: docs/rules/RULES_DEPENDENCIES.md -->
<!-- version: 1 -->
# 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.
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.
## 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.
## 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-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.
## 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.
## 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.

90
docs/rules/RULES_KSP.md
View File

@@ -1,47 +1,73 @@
<!-- file: docs/rules/RULES_KSP.md -->
<!-- version: 1 -->
<!-- version: 5 -->
# Règles spécifiques à KSP
## Portée
## Nomenclature
Les règles `KSP-*` s'appliquent à l'architecture, la nomenclature et l'organisation propres à `khadhroony-solana-project`.
- **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/`.
## Succession des projets précédents
## Architecture et APIs
- **KSP-LINEAGE-001** — KSP succède aux projets Khadhroony Solana précédents mais ne les duplique pas mécaniquement.
- **KSP-LINEAGE-002** — Une reprise de code, structure, dépendance ou documentation historique doit être justifiée par un besoin KSP actuel.
- **KSP-LINEAGE-003** — Une architecture historique n'est jamais considérée comme normative uniquement parce qu'elle a fonctionné dans `khadhroony-bot3` ou un prédécesseur.
- **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`.
## Nomenclature des crates et exécutables
## Programmes
- **KSP-NAME-001** — Une bibliothèque Rust réutilisable se nomme `ksp-<role>-lib`.
- **KSP-NAME-002** — Une application se nomme `ksp-app-<role>-<interface>` lorsque l'interface doit être indiquée.
- **KSP-NAME-003** — Un worker se nomme `ksp-worker-<role>`.
- **KSP-NAME-004** — Une démonstration se termine par `-demo`.
- **KSP-NAME-005** — Les interfaces d'application utilisent des tokens courts et stables, notamment `cli` pour une interface en ligne de commande et `desk` pour une application desktop.
- **KSP-NAME-006** — Les crates Rust sont placées directement sous `crates/` ; aucun sous-répertoire de catégories n'est utilisé pour les regrouper.
- **KSP-NAME-007** — Les applications sont placées sous `apps/` lorsqu'elles sont introduites.
- **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.
## Environnements des démonstrations
## Workers
- **KSP-DEMO-001** — Une demo limitée à un environnement encode explicitement cet environnement dans son nom avant le token d'interface et avant `-demo`.
- **KSP-DEMO-002** — Les tokens d'environnement initiaux sont `mainnet`, `devnet`, `testnet`, `local-validator` et `synthetic`.
- **KSP-DEMO-003** — Une demo sans token d'environnement est conçue pour permettre le choix de l'environnement parmi ceux qu'elle supporte ; l'absence de token ne signifie pas implicitement `mainnet`.
- **KSP-DEMO-004** — Exemples de forme : `ksp-app-<role>-devnet-cli-demo`, `ksp-app-<role>-local-validator-desk-demo`, `ksp-app-<role>-synthetic-cli-demo` et `ksp-app-<role>-desk-demo` pour une demo à environnement sélectionnable.
- **KSP-DEMO-005** — Une demo ne doit pas agréger plusieurs responsabilités indépendantes uniquement pour constituer une application de démonstration universelle.
- **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.
## Frontières architecturales déjà décidées
## Jobs
- **KSP-ARCH-001** — `ksp-core-lib` regroupe les fondations réellement transversales, y compris la responsabilité autrefois séparée des identifiants de programmes ; il ne doit pas devenir un conteneur générique de tout code partagé.
- **KSP-ARCH-002** — Une bibliothèque commune dédiée aux interfaces/wire on-chain doit exister ; son nom de travail est `ksp-interface-lib` jusqu'à validation définitive.
- **KSP-ARCH-003** — La matérialisation constitue une responsabilité distincte des interfaces/wire et du traitement des programmes.
- **KSP-ARCH-004** — Le regroupement ou la séparation définitive du decoder, de la construction d'instructions et de l'exécution réseau reste une décision d'architecture ouverte ; aucune structure historique ne doit être recopiée avant cette décision.
- **KSP-ARCH-005** — Une bibliothèque comme le wallet reste indépendante de son interface utilisateur ; les applications et demos qui la manipulent consomment la bibliothèque au lieu d'y être intégrées.
- **KSP-ARCH-006** — La configuration doit disposer d'une bibliothèque propriétaire de ses contrats et pourra disposer d'une application dédiée à l'inspection et la modification des profils et valeurs autorisées.
- **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.
## Dépendances et outils
## Notifications de données
- **KSP-TOOL-001** — Aucun `rust-toolchain.toml` n'est utilisé dans KSP.
- **KSP-TOOL-002** — Les lockfiles de dépendances sont ignorés et non livrés.
- **KSP-TOOL-003** — Les répertoires et fichiers générés ne sont ajoutés au `.gitignore` qu'après apparition d'un besoin réel et décision explicite ; les futurs `bindings/` et `gen/` Tauri seront traités à ce moment.
- **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.
## Pipelines et scénarios
- **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.
## Applications
- **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.