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

v0.2.14-pre.004

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-28 14:21:21 +02:00
parent 27d4cb1f36
commit bcf2f16c05
11 changed files with 649 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Plan `0.2.14` — Program API foundation
@@ -549,13 +549,15 @@ Aucun trait decoder, recognition, outcome, registry, codec, runtime logging ou e
### `pre.003` — Recognition + outcome minimal
**Statut : matérialisé ; gate opérateur à confirmer.**
**Statut : réalisé ; gate opérateur intégralement PASS.**
`ProgramInstructionRecognition` et `ProgramInstructionDecodeOutcome<Decoded>` sont ajoutés dans un module privé puis réexportés depuis le crate-root. Les deux enums sont `#[non_exhaustive]`. Le `Debug` de l'outcome est manuel, ne requiert pas `Decoded: Debug` et n'affiche jamais la valeur décodée. Aucun descriptor, registry ou trait decoder n'est avancé.
### `pre.004` — `ProgramInstructionDecoder` + external implementation
Introduire le trait `Send + Sync` avec associated output, `program_ids`, `recognize`, `decode`, puis prouver une implémentation depuis une crate externe avec Program Pubkey non enregistré.
**Statut : matérialisé ; gate opérateur à confirmer.**
Le trait `ProgramInstructionDecoder: Send + Sync` expose l'associated type `Decoded`, `program_ids`, `recognize` et `decode`. Un test d'intégration downstream-style l'implémente avec un type décodé tiers et un `Pubkey` explicitement absent du registry Core. L'implémentation ne requiert ni `ksp-program-lib`, ni enum centrale, ni `Any`, JSON ou codec.
### `pre.005` — Adversarial/API hardening + completeness
@@ -620,7 +622,32 @@ registry / canonical payload / preparer absents
normal dependencies inchangées : Core + Interface
```
Les tests unitaires vérifient notamment qu'un type décodé externe dépourvu de `Debug` peut être contenu et formaté via l'outcome sans exposer sa valeur. Le passage à `pre.004` reste conditionné au gate opérateur de cet overlay.
Les tests unitaires vérifient notamment qu'un type décodé externe dépourvu de `Debug` peut être contenu et formaté via l'outcome sans exposer sa valeur. Le gate opérateur `pre.003` fourni le 28 août 2026 est intégralement vert et autorise `pre.004`.
## 13.3 État préparé après `pre.004`
La tranche matérialise exactement :
```text
ProgramInstructionDecoder public depuis le crate-root
supertraits Send + Sync
associated output type Decoded possédé par l'implémentation
program_ids &[Pubkey] opaque/open-world
recognize &ProgramInstruction -> Recognition
decode &ProgramInstruction -> Result<Outcome<Self::Decoded>>
default methods aucun
external implementation canary présent comme crate d'intégration séparée
external decoded type défini hors code de production KSP
external Program Pubkey explicitement absent du registry Core
central Program enum / Any / JSON absents
registry dyn / descriptor / D3 payload absents
ProgramExecutionPreparer absent
normal dependencies inchangées : Core + Interface
```
Le canari externe utilise uniquement la façade `ksp_program_api::*` pour l'implémentation du trait ; l'accès direct à `ksp_core_lib::find_program_pubkey` est limité à l'assertion de test prouvant que le Program choisi n'est pas enregistré. Aucune API de registry n'est réexportée par Program API.
`pre.005` reste une tranche de hardening/completeness : elle ne doit pas élargir le contrat fonctionnel.
## 14. Hors périmètre confirmé

65
docs/validation/017-V0_2_14_PROGRAM_API.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/017-V0_2_14_PROGRAM_API.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Validation `0.2.14` — Program API foundation
@@ -40,10 +40,10 @@ Le scope validé par `pre.001` est une foundation instruction-only avec output a
| `ProgramInstructionRecognition` | `NoMatch / ProgramMatch / ExactMatch`, non exhaustif | PASS `pre.003` |
| `ProgramInstructionDecodeOutcome<Decoded>` | `Decoded(Decoded) / Unsupported`, non exhaustif | PASS `pre.003` |
| decoder failure | `ksp_core_lib::Result`, aucun statut `Failed` parallèle | `pre.003` / `pre.004` |
| `ProgramInstructionDecoder` | `Send + Sync`, associated `Decoded` | `pre.004` |
| input | `&ProgramInstruction` | `pre.004` |
| Program IDs déclarés | `&[Pubkey]`, opaque et open-world | `pre.004` |
| output | type concret de l'implémentation | `pre.004` |
| `ProgramInstructionDecoder` | `Send + Sync`, associated `Decoded` | PASS `pre.004` |
| input | `&ProgramInstruction` | PASS `pre.004` |
| Program IDs déclarés | `&[Pubkey]`, opaque et open-world | PASS `pre.004` |
| output | type concret de l'implémentation | PASS `pre.004` |
| registry dyn | absent | completeness `pre.005` |
| identity/version/coverage | absents | completeness `pre.005` |
| Program Account/Event/ReturnData decoder | absents | completeness `pre.005` |
@@ -53,7 +53,7 @@ Le scope validé par `pre.001` est une foundation instruction-only avec output a
## 4. External implementation canary
La preuve finale doit utiliser une crate consommatrice séparée et vérifier :
La preuve matérialisée en `pre.004` utilise une crate d'intégration consommatrice séparée et vérifie :
```text
implementation de ProgramInstructionDecoder
@@ -66,7 +66,7 @@ aucun ksp-program-lib
aucun module privé
```
Ce canari remplace toute affirmation documentaire non exécutable d'extensibilité.
Ce canari remplace toute affirmation documentaire non exécutable d'extensibilité. Son gate opérateur reste à confirmer avant de déclarer la tranche close.
## 5. Dependency firewall cible
@@ -102,17 +102,17 @@ tracing
| Gate | Attendu | Statut initial |
|---------------------------|--------------------------------------------------------------------------|----------------|
| unknown Program Pubkey | utilisable sans registry Core | PENDING |
| unknown Program Pubkey | utilisable sans registry Core | PASS `pre.004` |
| max Interface input | decoder consomme l'input déjà borné sans nouvelle allocation obligatoire | PENDING |
| malformed program payload | `Err` ou `Unsupported` selon contrat, sans payload dans l'erreur | PENDING |
| Debug recognition | aucun payload | PASS |
| Debug outcome | contenu `Decoded` non rendu automatiquement | PASS |
| default methods | aucun default method susceptible de masquer panic/policy | PENDING |
| closed-world enum | aucun inventaire central de Program kinds | PENDING |
| serde accidental | aucune dependency/derive | PENDING |
| runtime creep | aucun réseau, wallet, store, logging ou UI | PENDING |
| external output | type tiers accepté sans `Any`/JSON central | PENDING |
| dyn claim | aucune assertion d'object-safety hétérogène dans cette release | PENDING |
| default methods | aucun default method susceptible de masquer panic/policy | PASS `pre.004` |
| closed-world enum | aucun inventaire central de Program kinds | PASS `pre.004` |
| serde accidental | aucune dependency/derive | PASS `pre.004` |
| runtime creep | aucun réseau, wallet, store, logging ou UI | PASS `pre.004` |
| external output | type tiers accepté sans `Any`/JSON central | PASS `pre.004` |
| dyn claim | aucune assertion d'object-safety hétérogène dans cette release | PASS `pre.004` |
## 7. Gates de fermeture
@@ -190,4 +190,39 @@ Ce gate autorise l'ouverture de `pre.003`.
| registry / descriptor / payload D3 | ABSENT | hors scope maintenu |
| serde / codec / logging / runtime | ABSENT | dependency firewall maintenu |
Les canaris unitaires et publics de `pre.003` doivent passer avant d'ouvrir `pre.004`. La preuve d'implémentation externe, le Program Pubkey open-world et l'associated output complet restent réservés au trait decoder de la tranche suivante.
Le gate opérateur `pre.003` est confirmé intégralement vert : audits Rust/Markdown, check, Clippy, tests ciblés, workspace complet et graphes Cargo passent.
## 10. Gate opérateur `pre.003`
```text
cargo fmt --all PASS
audit Rust général / exports / workspace PASS
audit Markdown PASS — 171 tables / 120 fichiers
cargo check --workspace PASS
cargo clippy --workspace --all-targets PASS
cargo test -p ksp-program-api PASS — 8 tests Rust
cargo test --workspace PASS
cargo tree -p ksp-program-api --edges normal PASS — Core + Interface uniquement
cargo tree --duplicates exécuté, inventaire workspace observé
```
Ce gate autorise l'ouverture de `pre.004`.
## 11. État préparé `pre.004`
| Critère | Statut | Preuve |
|------------------------------------|--------|----------------------------------------------------------------------|
| `ProgramInstructionDecoder` | PASS | trait public `Send + Sync` |
| associated `Decoded` | PASS | type sans bound imposé, possédé par l'implémentation |
| `program_ids` | PASS | `&[Pubkey]`, aucune validation registry dans l'API |
| `recognize` | PASS | input `&ProgramInstruction`, outcome `ProgramInstructionRecognition` |
| `decode` | PASS | `Result<ProgramInstructionDecodeOutcome<Self::Decoded>>` |
| default methods | ABSENT | toutes les méthodes sont obligatoires |
| external implementation canary | PASS | test d'intégration downstream-style séparé |
| Program Pubkey non enregistré | PASS | assertion `ksp_core_lib::find_program_pubkey(...) == None` |
| output externe concret | PASS | `ExternalDecodedInstruction` défini dans le consumer canary |
| `ksp-program-lib` | ABSENT | aucune dépendance ni implémentation officielle |
| registry / descriptor / payload D3 | ABSENT | hors scope maintenu |
| serde / codec / logging / runtime | ABSENT | dependency firewall inchangé |
Le canari d'implémentation consomme la façade `ksp_program_api` pour le trait, les types et les outcomes. Le registry Core n'est utilisé que par l'assertion de test négative et n'est pas réexporté par Program API. Le gate opérateur de cet overlay reste requis avant `pre.005`.