From d33911f925d50c7163c5eb7e056e51a56e21473a Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Fri, 14 Aug 2026 09:51:30 +0200 Subject: [PATCH] v0.0.3-pre.004 --- Cargo.toml | 4 +- deltas/0.0.3/pre.004.md | 189 +++++++++ docs/IDEAS.md | 34 +- docs/architecture/000-README.md | 5 +- docs/architecture/003-COMPONENT_CONTRACTS.md | 4 +- docs/architecture/004-COMPONENT_INVENTORY.md | 73 ++-- docs/architecture/005-DEPENDENCY_GRAPH.md | 39 +- docs/architecture/006-WIRE_AND_PROGRAM.md | 418 +++++++++++++++++++ docs/plans/001-V0_0_3_PLAN.md | 44 +- docs/rules/RULES_DEPENDENCIES.md | 13 +- docs/rules/RULES_KSP.md | 15 +- prompts/001-V0_1_X_START_PROMPT.md | 5 +- 12 files changed, 776 insertions(+), 67 deletions(-) create mode 100644 deltas/0.0.3/pre.004.md create mode 100644 docs/architecture/006-WIRE_AND_PROGRAM.md diff --git a/Cargo.toml b/Cargo.toml index 3255600..5bf810f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 9 +# version: 10 [workspace] resolver = "3" members = ["crates/ksp-core-lib"] [workspace.package] -version = "0.0.3-pre.3" +version = "0.0.3-pre.4" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.0.3/pre.004.md b/deltas/0.0.3/pre.004.md new file mode 100644 index 0000000..6e7e53b --- /dev/null +++ b/deltas/0.0.3/pre.004.md @@ -0,0 +1,189 @@ + + + +# Delta 0.0.3-pre.004 + +## Base requise + +`v0.0.3-pre.003`. + +## Objectif + +Détailler la frontière Wire/Program sans ouvrir encore la totalité de l'orchestration Execution/Policy. + +La tranche formalise : + +- `ksp-interface-lib` et la propriété des codecs wire ; +- la politique de sélection/réimplémentation des crates d'interface externes ; +- `ksp-program-api` ouvert/extensible ; +- les familles de decoders ; +- `ProgramExecutionPreparer` ; +- le lifecycle machine-readable des opérations anciennes/abandonnées ; +- le registry officiel + externe ; +- l'organisation future de `ksp-program-lib` ; +- le workflow d'une extension Program développée indépendamment. + +## Version Cargo + +`workspace.package.version` passe de : + +```text +0.0.3-pre.3 +``` + +à : + +```text +0.0.3-pre.4 +``` + +Le header de `Cargo.toml` passe de version 9 à 10. + +## Fichiers ajoutés + +- `docs/architecture/006-WIRE_AND_PROGRAM.md` +- `deltas/0.0.3/pre.004.md` + +## Fichiers modifiés + +- `Cargo.toml` +- `docs/architecture/000-README.md` +- `docs/architecture/003-COMPONENT_CONTRACTS.md` +- `docs/architecture/004-COMPONENT_INVENTORY.md` +- `docs/architecture/005-DEPENDENCY_GRAPH.md` +- `docs/rules/RULES_DEPENDENCIES.md` +- `docs/rules/RULES_KSP.md` +- `docs/IDEAS.md` +- `docs/plans/001-V0_0_3_PLAN.md` +- `prompts/001-V0_1_X_START_PROMPT.md` + +## Fichiers supprimés + +Aucun. + +## Décisions principales + +### Codecs wire + +`ksp-interface-lib` est le propriétaire normal des dépendances wire telles que `borsh`, `wincode` et équivalents pour les interfaces officielles KSP. + +`ksp-program-lib` ne redécode pas directement une surface officielle avec une autre génération de codec. + +### Sélection des interfaces externes + +Une interface externe est retenue selon : + +- caractère officiel/normatif ; +- stabilité/utilité de l'API ; +- compatibilité avec le stack actuel ; +- absence de dette de générations anciennes évitable. + +Une crate protocolaire qui impose une ancienne génération incompatible d'un codec fondamental peut être remplacée par une réimplémentation KSP bornée aux contrats wire nécessaires. + +Le workspace devra auditer les doublons de dépendances fondamentales (`cargo tree -d`, `cargo tree -i ...`) lorsque les dépendances fonctionnelles seront introduites. + +### Program API ouverte + +Aucun enum central fermé de Program IDs n'est prévu. + +Le résultat décodé doit pouvoir être auto-identifié, extensible et persistable. + +`Any` ne peut pas constituer à lui seul le contrat de résultat. + +### Decoders + +Les capacités sont séparables, avec notamment : + +```text +ProgramInstructionDecoder +ProgramAccountDecoder +``` + +et ajout de surfaces Event/ReturnData seulement lorsqu'un besoin réel le justifie. + +### Préparation d'exécution + +Le terme `ProgramExecutor` est remplacé conceptuellement par : + +```text +ProgramExecutionPreparer +``` + +Il prépare l'opération protocolaire mais ne signe, simule, envoie ou confirme pas la transaction. + +### Lifecycle / deprecated + +Le statut d'une opération est machine-readable. + +Une opération simplement ancienne n'est pas automatiquement deprecated. + +Une opération réellement abandonnée peut rester techniquement préparée avec warning et être ensuite autorisée/refusée par la policy supérieure. + +`#[deprecated]` n'est pas obligatoire. + +Le decoder continue de décoder les surfaces historiques distinguables. + +### Registry et extensions + +Le registry doit composer implémentations officielles, externes et expérimentales. + +Une extension s'appelle conceptuellement : + +```text +ksp-program--lib +``` + +et implémente `ksp-program-api`. + +Elle peut exister/tester indépendamment de `ksp-program-lib`. + +Si son interface wire n'est pas encore officiellement intégrée à KSP, elle peut temporairement posséder ses propres définitions compatibles. + +Lors de l'intégration officielle, le wire migre vers `ksp-interface-lib` et l'implémentation Program vers `ksp-program-lib` sans modifier le contrat commun uniquement pour ce nouveau Program ID. + +### Organisation de `ksp-program-lib` + +Principe retenu : + +```text +domain -> program/protocol -> capability +``` + +avec une direction de travail de type : + +```text +//dec/* +//exec_prep/* +``` + +Les noms exacts de répertoires restent à valider avec la première implémentation. + +## Plan ajusté + +La tranche Execution/Policy est déplacée vers `pre.005`. + +Les tranches suivantes sont décalées : + +- `pre.005` — Execution/Policy ; +- `pre.006` — Data/Store/Acquisition ; +- `pre.007` — Apps/Workers/Jobs/Scenarios ; +- `pre.008` — plan des premières releases fonctionnelles ; +- `pre.009` — clôture fondatrice. + +## Questions reportées + +- représentation exacte du payload décodé ouvert/persistable ; +- descripteurs/registry exacts ; +- conflits entre plusieurs implémentations d'un même Program ID ; +- formes Rust exactes des traits ; +- noms définitifs `dec` / `exec_prep`. + +Ces points seront fixés avec les premières implémentations lorsqu'un cas réel permet de tester la qualité du contrat. + +## Validations + +- headers `file:` / `version:` vérifiés ; +- `Cargo.toml` parsé et version `0.0.3-pre.4` vérifiée ; +- liens vers `006-WIRE_AND_PROGRAM.md` vérifiés ; +- plan `pre.005` à `pre.009` vérifié ; +- aucune commande Cargo de build/test exécutée : ce delta reste documentaire et n'ajoute aucun code Rust fonctionnel. diff --git a/docs/IDEAS.md b/docs/IDEAS.md index e52b4a7..9559ae4 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -1,5 +1,5 @@ - + # Idées à explorer @@ -160,3 +160,35 @@ Ne pas créer de `ksp-pipeline-lib`. Les pipelines sont introduits séparément **Status :** Retenue Construire d'abord statistiques, features, signaux, risque, backtests, détection de patterns/anomalies et intégrations ML telles que XGBoost. La couche/application de trading opérationnelle est construite ensuite. + +## Program API — questions d'implémentation + +### Payload décodé ouvert et persistable + +**Status :** À explorer lors de la première implémentation + +`ksp-program-api` ne doit utiliser ni enum central fermé de Program IDs ni `Any` comme seule représentation. + +À décider à partir des besoins réels : + +- value tree typé KSP ; +- schema/version + payload binaire ; +- structure sérialisable ouverte ; +- autre contrat garantissant identification, persistence et extensibilité. + +### Conflits de registry + +**Status :** À explorer + +Définir la politique lorsqu'un registry reçoit plusieurs implémentations capables de traiter le même Program ID/surface/version : + +- priorité explicite ; +- refus du conflit ; +- sélection par version/capability ; +- autre mécanisme documenté. + +### Convention interne `dec` / `exec_prep` + +**Status :** À explorer avec les premiers modules + +Le principe `domain/program/capability` est retenu. Les noms exacts des dossiers courts (`dec`, `exec_prep`) seront validés avec la première vraie arborescence. diff --git a/docs/architecture/000-README.md b/docs/architecture/000-README.md index 35b5d5c..1ccc445 100644 --- a/docs/architecture/000-README.md +++ b/docs/architecture/000-README.md @@ -1,5 +1,5 @@ - + # Architecture KSP @@ -21,6 +21,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas. 2. [`002-LAYERS_AND_DEPENDENCIES.md`](002-LAYERS_AND_DEPENDENCIES.md) — couches conceptuelles, sens des dépendances et responsabilités des exécutables ; 3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants et contrats déjà acquis ; 4. [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) — inventaire courant des domaines, APIs, bibliothèques, workers, jobs, scénarios et applications candidates ; -5. [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) — graphe de dépendances retenu, dépendances interdites et frontières de conversion/composition. +5. [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) — graphe de dépendances retenu, dépendances interdites et frontières de conversion/composition ; +6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe. `004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires. diff --git a/docs/architecture/003-COMPONENT_CONTRACTS.md b/docs/architecture/003-COMPONENT_CONTRACTS.md index 533233b..b369f80 100644 --- a/docs/architecture/003-COMPONENT_CONTRACTS.md +++ b/docs/architecture/003-COMPONENT_CONTRACTS.md @@ -1,5 +1,5 @@ - + # Contrats initiaux des composants KSP @@ -9,7 +9,7 @@ Ce document enregistre les frontières déjà suffisamment claires pour guider l Le principe commun est de définir tôt les contrats nécessaires entre composants, puis d'enrichir les implémentations lorsque le besoin réel apparaît. -L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) et le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). +L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) et les contrats Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md). ## Convention API / implémentation diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index 5e635de..28d1cb0 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -9,7 +9,7 @@ Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`. Il répond principalement à la question : **quel composant possède quelle responsabilité ?** -Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a corrigé à partir du graphe formalisé dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). Les détails internes des APIs restent toutefois révisables dans les prereleases spécialisées suivantes. +Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md). Les détails de types Rust restent révisables avec les premières implémentations. ## Statuts @@ -21,40 +21,41 @@ Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a co ## Inventaire synthétique -| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale | -|-------------------------|---------------------------------------------|---------------|-------------------|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux | -| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées | -| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun | -| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles | -| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics decoder/executor et types associés | -| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés | -| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution | -| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` | -| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store | -| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain | -| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature | -| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation | -| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP | -| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées | -| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries | -| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus | -| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur | -| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data | -| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique | -| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core | -| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine | -| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables | -| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise | -| Other jobs | `ksp-job-` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques | -| Scenarios | `ksp-scenario--lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine | -| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant | -| Scenario demo apps | `ksp-app-scenario---desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante | -| Specialized pipelines | `ksp-pipeline--lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale | -| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML | -| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte | -| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana | -| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX | +| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale | +|-------------------------|---------------------------------------------|-------------------------|-------------------|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux | +| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées | +| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun | +| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles | +| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry | +| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders et `ProgramExecutionPreparer` officiels organisés par domaine/programme/capacité | +| Program extension | `ksp-program--lib` | lib externe/optionnelle | N2 | À la demande | dès besoin | implémentation externe de `ksp-program-api` pour un Program ID non encore intégré officiellement | +| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution | +| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` | +| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store | +| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain | +| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature | +| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation | +| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP | +| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées | +| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries | +| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus | +| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur | +| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data | +| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique | +| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core | +| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine | +| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables | +| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise | +| Other jobs | `ksp-job-` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques | +| Scenarios | `ksp-scenario--lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine | +| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant | +| Scenario demo apps | `ksp-app-scenario---desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante | +| Specialized pipelines | `ksp-pipeline--lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale | +| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML | +| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte | +| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana | +| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX | ## APIs séparées retenues diff --git a/docs/architecture/005-DEPENDENCY_GRAPH.md b/docs/architecture/005-DEPENDENCY_GRAPH.md index 9b61242..49342ad 100644 --- a/docs/architecture/005-DEPENDENCY_GRAPH.md +++ b/docs/architecture/005-DEPENDENCY_GRAPH.md @@ -1,5 +1,5 @@ - + # Graphe de dépendances KSP @@ -87,6 +87,23 @@ ksp-interface-lib -> ksp-core-lib --- +# Propriété des codecs wire + +Pour les surfaces wire officielles KSP : + +```text +ksp-interface-lib + -> codecs wire nécessaires (borsh/wincode/...) +``` + +`ksp-program-lib` n'ajoute pas directement une autre génération de codec pour les mêmes surfaces. + +Une extension Program externe peut temporairement posséder son wire lorsqu'il n'est pas encore officiellement intégré à `ksp-interface-lib`. + +Le critère d'adoption d'une crate d'interface externe inclut la compatibilité de son graphe de dépendances avec le stack KSP actuel. + +--- + # Graphe Program ```text @@ -102,7 +119,7 @@ ksp-program-lib ## Frontière de `ksp-program-api` -`ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/executor. +`ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/execution preparation. Il est également le propriétaire candidat du **contrat d'opération préparée** produit par la sémantique programme et consommé par la couche d'exécution. @@ -131,10 +148,26 @@ ksp-program-lib -X-> ksp-materializer-lib ksp-program-lib -X-> ksp-execution-lib ``` -Le decoder/executor de programme reste donc testable sans réseau, wallet ou base de données. +Le decoder/execution preparation de programme reste donc testable sans réseau, wallet ou base de données. --- + +## Implémentations Program externes + +Une implémentation externe peut dépendre de : + +```text +ksp-program--lib + -> ksp-program-api + -> ksp-core-lib + -> ksp-interface-lib # lorsque le wire officiel nécessaire existe +``` + +Elle ne dépend pas obligatoirement de `ksp-program-lib`. + +Le runtime peut composer registry officiel + registry/implémentations externes derrière `ksp-program-api`. + # Graphe Execution / Policy `ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants. diff --git a/docs/architecture/006-WIRE_AND_PROGRAM.md b/docs/architecture/006-WIRE_AND_PROGRAM.md new file mode 100644 index 0000000..f38ac8b --- /dev/null +++ b/docs/architecture/006-WIRE_AND_PROGRAM.md @@ -0,0 +1,418 @@ + + + +# Wire, Program API et implémentations Program + +## Objet + +Ce document constitue la sortie principale de `0.0.3-pre.004`. + +Il précise : + +- le rôle de `ksp-interface-lib` ; +- la propriété des codecs wire ; +- la politique de sélection/réimplémentation des crates d'interface externes ; +- la forme générale et ouverte de `ksp-program-api` ; +- la séparation decoder / préparation d'exécution ; +- le registry extensible ; +- l'organisation interne prévue de `ksp-program-lib` ; +- le workflow d'une implémentation de programme développée hors de l'implémentation officielle. + +Les types Rust exacts restent volontairement à définir lors de la première implémentation réelle. + +## `ksp-interface-lib` + +`ksp-interface-lib` est la façade wire officielle KSP pour les programmes Solana supportés officiellement. + +Elle possède ou réexporte de manière contrôlée les contrats nécessaires tels que : + +- discriminants ; +- layouts d'instructions ; +- layouts de comptes ; +- enums/structures wire ; +- sérialisation/désérialisation wire ; +- règles et seeds de PDA lorsque ces règles appartiennent au contrat protocolaire ; +- constructeurs d'instructions lorsque ceux-ci représentent directement le contrat wire. + +Les Program IDs fondamentaux restent possédés par `ksp-core-lib`. + +`ksp-interface-lib` ne possède pas : + +- RPC/WS/provider ; +- wallet/signature ; +- persistence ; +- matérialisation ; +- interprétation canonique/métier d'une instruction ; +- policy/safety ; +- lifecycle d'exécution réseau. + +## Propriété des codecs wire + +Pour le code KSP officiel, les dépendances directement utilisées pour encoder/décoder les formats wire, notamment `borsh`, `wincode` ou codecs équivalents, appartiennent normalement à `ksp-interface-lib`. + +La règle n'interdit pas qu'une autre crate KSP utilise un codec pour une raison indépendante du wire Solana, mais une telle dépendance directe doit avoir une justification distincte. + +En particulier : + +```text +ksp-interface-lib + -> borsh / wincode / codecs wire nécessaires + +ksp-program-lib + -X-> borsh / wincode pour redécoder directement le wire protocolaire +``` + +`ksp-program-lib` reçoit des contrats typés/wire exposés par la façade officielle au lieu de recréer la sérialisation protocolaire. + +## Politique de sélection des interfaces externes + +Une crate externe d'interface Solana/Anza peut être utilisée directement lorsque : + +1. elle appartient à une source officielle ou suffisamment normative pour le contrat concerné ; +2. sa surface est suffisamment stable et finale pour l'usage KSP ; +3. son graphe de dépendances est compatible avec le stack de dépendances KSP actuel ; +4. elle n'introduit pas sans nécessité une génération ancienne/incompatible d'un codec ou d'une primitive fondamentale ; +5. son usage évite une réimplémentation KSP sans réduire le contrôle du contrat public. + +Une crate protocolaire externe peut être rejetée même si son API fonctionne lorsqu'elle impose un stack ancien ou incompatible avec le reste du workspace. + +### Exemples observés pendant la planification + +`solana-loader-v3-interface` illustre une interface officielle actuelle qui peut raisonnablement être conservée plutôt que réécrite lorsque sa version et son graphe restent compatibles avec KSP. + +`mpl-token-metadata` illustre le cas inverse : KSP ne prévoit pas de l'intégrer comme dépendance runtime. Les contrats wire Metaplex Token Metadata nécessaires seront réimplémentés/possédés par `ksp-interface-lib`. + +Ces exemples sont des applications de la règle, pas des exceptions codées en dur : l'état des dépendances doit être revérifié au moment de chaque implémentation. + +## Politique anti-doublons de générations + +KSP ne cherche pas à figer arbitrairement une version précise des dépendances. Le projet cherche au contraire à rester sur des générations récentes et compatibles. + +Les doublons de versions/générations de dépendances fondamentales doivent être inspectés régulièrement, notamment pour : + +- codecs wire ; +- primitives Solana ; +- sérialisation ; +- bibliothèques cryptographiques fondamentales. + +Un doublon réellement imposé et inévitable par une dépendance retenue peut être temporairement accepté avec justification. + +Un doublon évitable provoqué par une crate protocolaire remplaçable doit être éliminé plutôt que normalisé comme dette permanente. + +Outils d'audit attendus lorsque le workspace fonctionnel le permettra : + +```bash +cargo tree -d +cargo tree -i borsh +cargo tree -i wincode +``` + +La liste sera complétée selon les dépendances réellement utilisées. + +## `ksp-program-api` + +`ksp-program-api` porte des contrats publics **ouverts**. + +Une implémentation externe doit pouvoir prendre en charge un Program ID encore inconnu de `ksp-program-lib` sans modifier une enum centrale KSP. + +### Pas d'enum fermée de programmes + +Une structure de la forme suivante est explicitement évitée : + +```text +enum DecodedProgram { + Token(...), + Token2022(...), + Meteora(...), + ... +} +``` + +car chaque nouveau protocole exigerait une modification de l'API centrale. + +De même, un `Any` runtime non persistable ne peut pas constituer l'unique représentation d'un résultat décodé. + +Le résultat doit rester : + +- auto-identifiable ; +- extensible ; +- sérialisable/persistable lorsque la frontière Core l'exige ; +- exploitable par une implémentation externe de materializer ; +- compatible avec l'ajout de Program IDs sans modification de l'API commune. + +La représentation exacte du payload ouvert sera définie avec les contrats Core/Store/Materializer réels, sans introduire prématurément une enum fermée. + +## Familles de decoders + +Plutôt qu'un unique trait possédant toutes les surfaces possibles, `ksp-program-api` doit pouvoir distinguer les capacités de décodage. + +Familles initiales candidates : + +```text +ProgramInstructionDecoder +ProgramAccountDecoder +ProgramEventDecoder +ProgramReturnDataDecoder +``` + +Les deux premières sont considérées comme besoins fondamentaux probables. + +Les autres ne sont ajoutées que lorsqu'une première surface réelle le justifie. + +Une implémentation de programme n'est pas obligée de fournir toutes les capacités. + +Des descripteurs communs doivent permettre d'identifier les capacités effectivement supportées. + +## Politique de décodage historique + +Le decoder vise toute surface techniquement décodable dont la définition est connue : + +- actuelle ; +- ancienne ; +- legacy ; +- abandonnée ; +- expérimentale/test lorsque le wire est connu ; +- historique distinguable. + +Le statut de lifecycle d'une opération n'empêche jamais son décodage historique. + +Si une définition a réellement été écrasée sous une identité indistinguable et que l'ancienne forme ne peut plus être reconnue de manière fiable, la définition applicable la plus récente est utilisée. + +Le concept `deprecated` n'est donc pas un filtre de decoder. + +## Préparation d'exécution Program + +Le terme `ProgramExecutor` est abandonné dans le cadrage KSP parce qu'il suggère une exécution transactionnelle complète. + +Le contrat prévu est nommé conceptuellement : + +```text +ProgramExecutionPreparer +``` + +Sa responsabilité : + +```text +ProgramExecutionRequest + | + v +ProgramExecutionPreparer + | + v +PreparedProgramExecution +``` + +Noms exacts des types à confirmer lors de l'implémentation. + +Le preparer peut notamment : + +- valider les paramètres protocolaires ; +- déterminer les comptes requis ; +- dériver les PDA nécessaires ; +- construire une ou plusieurs instructions ; +- indiquer les autorités/signers requis ; +- exposer les contraintes techniques propres à l'opération. + +Il ne réalise pas : + +- sélection du wallet réel ; +- accès aux secrets ; +- récupération du recent blockhash ; +- signature transactionnelle ; +- simulation RPC ; +- envoi réseau ; +- confirmation ; +- retry réseau ; +- policy/safety de produit. + +Ces responsabilités appartiennent aux couches d'exécution supérieures. + +## `PreparedProgramExecution` + +Le contrat préparé entre Program et Execution doit pouvoir transporter conceptuellement : + +- identité du programme/opération ; +- instructions ; +- comptes/authorities/signers requis ; +- contraintes techniques ; +- informations nécessaires à une policy supérieure ; +- metadata de préparation utiles à l'exécution. + +Il ne contient pas de secret wallet et ne fixe pas un endpoint réseau concret. + +Il doit être consommable par `ksp-execution-lib` indépendamment du fait que l'implémentation Program provienne de `ksp-program-lib` ou d'une crate externe. + +## Lifecycle des opérations préparables + +Le lifecycle d'une opération d'exécution doit être machine-readable. + +Il faut distinguer au minimum conceptuellement : + +- opération actuelle/supportée ; +- opération legacy/ancienne mais pas nécessairement déconseillée ; +- opération réellement abandonnée/déconseillée. + +Les noms exacts des statuts seront définis plus tard. + +Le statut « deprecated » est réservé à une surface clairement abandonnée/remplacée, pas simplement ancienne. + +KSP ne rend pas obligatoire l'annotation Rust `#[deprecated]`. + +Une opération techniquement encore préparée mais marquée comme abandonnée peut : + +1. produire un warning explicite ; +2. transmettre son statut à `ksp-execution-policy-api` ; +3. être autorisée ou rejetée par la policy supérieure selon le contexte. + +Le decoder continue de la reconnaître indépendamment de ce statut. + +## Registry extensible + +Le registry Program doit pouvoir combiner : + +- implémentations officielles KSP ; +- implémentations externes ; +- implémentations expérimentales. + +Les descripteurs doivent permettre d'identifier au minimum conceptuellement : + +- Program ID ; +- identité/version de l'implémentation ; +- capacités de décodage ; +- opérations préparables ; +- statut/lifecycle des opérations ; +- autres capacités nécessaires au dispatch. + +Le contrat exact du registry sera défini lors de l'implémentation. + +Le registry ne doit pas nécessiter une modification de `ksp-program-api` pour enregistrer un nouveau Program ID. + +## Implémentations externes + +Une extension externe de programme est une **implémentation** de `ksp-program-api`, pas une nouvelle API commune. + +Nomenclature recommandée lorsque l'extension suit les conventions KSP : + +```text +ksp-program--lib +``` + +Exemple conceptuel : + +```text +ksp-program-fluxbeam-lib +``` + +et non : + +```text +ksp-program-fluxbeam-api +``` + +Cette crate peut dépendre de : + +```text +ksp-program-api +ksp-core-lib +ksp-interface-lib +``` + +selon les besoins. + +Elle peut être développée, testée et utilisée par un runtime KSP sans être intégrée à `ksp-program-lib`. + +## Wire d'une extension encore non officielle + +`ksp-interface-lib` est la façade wire **officielle KSP**, mais `ksp-program-api` ne doit pas empêcher une extension externe de fournir temporairement ses propres définitions wire. + +Deux cas sont possibles : + +```text +interface officielle déjà dans KSP + -> extension utilise ksp-interface-lib + +interface pas encore intégrée + -> extension possède sa définition wire compatible + -> extension implémente ksp-program-api +``` + +Lors de l'intégration officielle : + +1. les définitions wire sont revues/vérifiées ; +2. les contrats wire nécessaires migrent vers `ksp-interface-lib` ; +3. decoder/preparer migrent vers `ksp-program-lib` ; +4. le contrat `ksp-program-api` ne change pas pour cette seule raison. + +## Organisation interne de `ksp-program-lib` + +`ksp-program-lib` doit être organisé d'abord par domaine puis par programme/protocole, et seulement ensuite par capacité. + +Direction retenue : + +```text +/ + / + dec/ + ... + exec_prep/ + ... +``` + +Exemples conceptuels : + +```text +spl/ + token_2022/ + dec/ + exec_prep/ + +metadata/ + token/ + mpl/ + dec/ + exec_prep/ + +dex/ + meteora/ + dlmm/ + dec/ + exec_prep/ +``` + +Les noms courts `dec` / `exec_prep` restent une convention candidate ; les noms précis seront décidés avec les premières vraies arborescences Rust. + +Le principe durable est : + +```text +domain -> program/protocol -> capability +``` + +et non un répertoire racine géant `decoder/` ou `executor/` contenant tous les protocoles. + +## Conformité wire + +Pour chaque contrat wire réimplémenté, la documentation/tests doivent permettre d'identifier la source normative utilisée. + +Les validations peuvent combiner selon le cas : + +- documentation/source officielle ; +- fixtures officielles ; +- transactions/comptes réels connus ; +- golden vectors ; +- comparaison avec une implémentation de référence lorsqu'elle peut être utilisée sans polluer durablement le graphe KSP. + +Une crate externe provoquant volontairement une génération incompatible de dépendances fondamentales ne doit pas être ajoutée au workspace simplement pour faciliter un test si des fixtures/vecteurs indépendants permettent la même vérification. + +## Questions laissées ouvertes + +La première implémentation Program devra encore fixer précisément : + +- formes Rust des traits decoder ; +- représentation du payload décodé ouvert/persistable ; +- forme exacte des descriptors ; +- types exacts `ProgramExecutionRequest` / `PreparedProgramExecution` ; +- forme du registry et règles de conflit entre plusieurs implémentations d'un même Program ID ; +- stratégie précise de warning/log pour opérations abandonnées ; +- convention finale `dec` / `exec_prep`. + +La tranche suivante doit traiter `ksp-execution-policy-api` et `ksp-execution-lib` sans rouvrir les responsabilités Program définies ici. diff --git a/docs/plans/001-V0_0_3_PLAN.md b/docs/plans/001-V0_0_3_PLAN.md index 5e9fd13..8ad1831 100644 --- a/docs/plans/001-V0_0_3_PLAN.md +++ b/docs/plans/001-V0_0_3_PLAN.md @@ -1,5 +1,5 @@ - + # Plan KSP 0.0.3 @@ -13,7 +13,7 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su - `pre.002` — inventaire initial des composants ; - `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition. -La prochaine tranche prévue est `pre.004`, consacrée à Program/Wire/Execution. +La tranche `pre.004` est consacrée à Wire/Program. Execution/Policy est volontairement déplacé vers `pre.005` afin de garder des prereleases de planification bornées. ## Décisions structurantes actuelles @@ -51,20 +51,32 @@ Livré : - correction de `004-COMPONENT_INVENTORY.md` ; - suppression des décisions négatives présentées à tort comme tâches du roadmap. -### `pre.004` — Programmes, wire et exécution +### `pre.004` — Wire et Program -Objectifs prévus : +Livré : -- détailler `ksp-interface-lib` ; -- détailler `ksp-program-api` et `ksp-program-lib` ; -- définir précisément decoder API et executor API ; -- définir le contrat d'opération préparée ; -- définir `ksp-execution-policy-api` ; -- détailler le cycle de `ksp-execution-lib` : préparation, policy, simulation, signature, envoi, confirmation ; -- cadrer conformité wire, historique/deprecated et policy supérieure ; -- vérifier que la tranche reste dans le budget de complexité, sinon la scinder. +- propriété et rôle de `ksp-interface-lib` ; +- propriété des codecs wire ; +- politique anti-doublons de générations et sélection/réimplémentation des interfaces externes ; +- API Program ouverte ; +- familles de decoders par capacité ; +- `ProgramExecutionPreparer` à la place d'un executor transactionnel ambigu ; +- statut lifecycle machine-readable pour les opérations anciennes/abandonnées ; +- registry extensible official + external ; +- organisation `domain -> program/protocol -> capability` ; +- workflow d'une implémentation externe avant intégration officielle. -### `pre.005` — Données, store et acquisitions +### `pre.005` — Execution et Policy + +- détailler `ksp-execution-policy-api` ; +- détailler `ksp-execution-lib` ; +- consommer `PreparedProgramExecution` sans dépendre de `ksp-program-lib` ; +- définir les étapes policy, simulation, wallet/signature, transport/envoi, confirmation ; +- déterminer les policies de scenario Devnet vs produit général ; +- traiter erreurs/retry/confirmation et limites de responsabilité ; +- scinder à nouveau si la tranche devient trop dense. + +### `pre.006` — Données, store et acquisitions - détailler `ksp-materializer-api` / `ksp-materializer-lib` ; - détailler `ksp-store-api` / `ksp-store-lib` ; @@ -74,7 +86,7 @@ Objectifs prévus : - cadrer les workers de processing ; - revisiter niveaux durables, replay, provenance et idempotence. -### `pre.006` — Applications, workers, jobs, scenarios et pipelines spécialisés +### `pre.007` — Applications, workers, jobs, scenarios et pipelines spécialisés - formaliser les apps spécialisées ; - détailler `ksp-worker-control-lib` ; @@ -83,14 +95,14 @@ Objectifs prévus : - cadrer l'orchestrateur futur ; - inventorier les pipelines spécialisés réellement nécessaires. -### `pre.007` — Plan des premières releases fonctionnelles +### `pre.008` — Plan des premières releases fonctionnelles - transformer les séries `0.1.x+` en premières releases concrètes ; - dimensionner chaque release concrète ; - choisir la première release `0.1.N` ; - transformer le brouillon de prompt en prompt quasi-final de cette release concrète. -### `pre.008` — Clôture fondatrice +### `pre.009` — Clôture fondatrice - validations finales de cohérence ; - documentation/nettoyage/archivage ; diff --git a/docs/rules/RULES_DEPENDENCIES.md b/docs/rules/RULES_DEPENDENCIES.md index dfe5de1..5de7dd3 100644 --- a/docs/rules/RULES_DEPENDENCIES.md +++ b/docs/rules/RULES_DEPENDENCIES.md @@ -1,5 +1,5 @@ - + # Règles des dépendances KSP @@ -23,11 +23,22 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur - **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. + ## 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--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, 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`. diff --git a/docs/rules/RULES_KSP.md b/docs/rules/RULES_KSP.md index 9edf0a1..45f3f68 100644 --- a/docs/rules/RULES_KSP.md +++ b/docs/rules/RULES_KSP.md @@ -1,5 +1,5 @@ - + # Règles spécifiques à KSP @@ -27,7 +27,7 @@ ## Programmes et exécution -- **KSP-PROGRAM-001** — Les contrats decoder/executor appartiennent à `ksp-program-api`; les implémentations officielles intégrées appartiennent à `ksp-program-lib`. +- **KSP-PROGRAM-001** — Les contrats de décodage et de préparation d'exécution 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. @@ -49,6 +49,17 @@ - **KSP-WALLET-001** — KSP ne crée pas de `ksp-wallet-api` dans l'architecture actuelle ; `ksp-wallet-lib` possède le format wallet KSP et ses capacités de lecture/protection/import/export/pubkey/secret/signature. +- **KSP-PROGRAM-007** — Le contrat de préparation d'exécution est nommé conceptuellement `ProgramExecutionPreparer`; il ne signe, ne simule, n'envoie et ne confirme pas une transaction. +- **KSP-PROGRAM-008** — `ksp-program-api` reste ouvert : aucun enum central fermé ne doit imposer une modification de l'API pour ajouter un Program ID externe. +- **KSP-PROGRAM-009** — Le résultat décodé doit pouvoir être auto-identifié et devenir persistable ; `Any` ne constitue pas à lui seul un contrat de résultat acceptable. +- **KSP-PROGRAM-010** — Une extension de programme est une implémentation `ksp-program--lib`, pas une nouvelle crate `*-api`. +- **KSP-PROGRAM-011** — `ksp-program-lib` est organisé selon `domain -> program/protocol -> capability`; les dossiers globaux regroupant tous les decoders de tous les protocoles sont évités. +- **KSP-PROGRAM-012** — Le statut legacy/deprecated d'une opération est machine-readable et indépendant du décodage historique. +- **KSP-PROGRAM-013** — `#[deprecated]` n'est pas imposé pour les opérations historiques ; un warning runtime et la policy supérieure peuvent porter la décision d'usage. +- **KSP-WIRE-001** — `ksp-interface-lib` est le propriétaire normal des codecs wire pour les interfaces officielles KSP. +- **KSP-WIRE-002** — Les interfaces externes sont sélectionnées aussi selon la modernité/cohérence de leur graphe de dépendances, pas uniquement selon la commodité de leur API. +- **KSP-WIRE-003** — Les contrats wire d'une crate protocolaire rejetée sont réimplémentés de manière bornée dans `ksp-interface-lib` lorsque KSP en a besoin. + ## Workers - **KSP-WORKER-001** — Un worker représente un service continu/live ; il est distinct d'un job. diff --git a/prompts/001-V0_1_X_START_PROMPT.md b/prompts/001-V0_1_X_START_PROMPT.md index f729c1d..2ab20d8 100644 --- a/prompts/001-V0_1_X_START_PROMPT.md +++ b/prompts/001-V0_1_X_START_PROMPT.md @@ -1,5 +1,5 @@ - + # Prompt de démarrage KSP 0.1.x @@ -33,7 +33,7 @@ Ces objectifs pourront être répartis entre plusieurs releases `0.1.N`. ## 5. Sources de vérité -Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `005`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. +Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `006`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. ## 6. Décisions acquises pertinentes @@ -47,6 +47,7 @@ Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PR - Les exécutables ne dépendent pas directement de crates Solana/protocoles externes. - `ksp-core-lib` doit posséder les Program IDs fondamentaux et le type d'erreur commun. - Les dépendances basses suivent le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md` ; N1 ne doit pas dépendre de ses consommateurs supérieurs. +- KSP évite les générations anciennes/dupliquées évitables de dépendances fondamentales ; toute contrainte de version non actuelle doit être motivée par un besoin réel. - Les règles fines de naming/arborescence/API publique seront définies à partir des premières APIs réelles. ## 7. Hors périmètre de la série N1