194 lines
11 KiB
Markdown
194 lines
11 KiB
Markdown
<!-- file: docs/validation/017-V0_2_14_PROGRAM_API.md -->
|
|
<!-- version: 3 -->
|
|
|
|
# Validation `0.2.14` — Program API foundation
|
|
|
|
## 1. Objet
|
|
|
|
Cette matrice est ouverte par `0.2.14-pre.001`. Elle distingue les preuves déjà acquises par le gate d'audit des validations futures qui ne doivent pas être déclarées PASS avant exécution.
|
|
|
|
Le scope validé par `pre.001` est une foundation instruction-only avec output associé à l'implémentation. Registry runtime, payload canonique D3 et `ProgramExecutionPreparer` sont explicitement reportés.
|
|
|
|
## 2. Gate `pre.001`
|
|
|
|
| Critère | Statut | Preuve |
|
|
|----------------------------|---------|--------------------------------------------------------------------------------|
|
|
| base stable `0.2.13` | PASS | Cargo `0.2.13`, `rel.001` et prompt 019 présents |
|
|
| metadata Git/tag | N/A | archive opérateur sans metadata Git exploitable |
|
|
| `ksp-interface-lib` stable | PASS | surface et canaris `0.2.13` relus |
|
|
| `ksp-program-api` absent | PASS | aucun répertoire de crate sur la base |
|
|
| `ksp-program-lib` absent | PASS | aucun répertoire de crate sur la base |
|
|
| archive kbot3 disponible | PASS | archive historique réellement extraite et auditée |
|
|
| règles Program/API relues | PASS | règles KSP/Dependencies/Workflow prescrites relues |
|
|
| architecture durable relue | PASS | `002` à `010`, avec `006-WIRE_AND_PROGRAM.md` central |
|
|
| audit Core + Interface | PASS | input `ProgramInstruction` jugé suffisant pour instruction-only |
|
|
| matrice héritage kbot3 | PASS | `REPRENDRE / REDESSINER / REPORTER / REJETER` dans le plan 021 |
|
|
| ownership matrix | PASS | Core/Interface/Program/CORE/Execution séparés dans le plan 021 |
|
|
| API candidate | PASS | recognition + generic outcome + associated-output decoder |
|
|
| payload canonique | REPORTÉ | aucune représentation D3 inventée en `0.2.14` |
|
|
| registry runtime | REPORTÉ | aucune composition dyn hétérogène dans la release |
|
|
| execution preparer | REPORTÉ | attend un intent technique réel de vertical slice |
|
|
| dependency graph | PASS | cible Core + Interface uniquement |
|
|
| threat/API model | PASS | payload, Debug, open-world, externe hostile, exactness et scope creep couverts |
|
|
| stratégie de tests | PASS | unit/public/external/firewall/completeness, aucun live smoke |
|
|
| sizing | PASS | release réduite à decoder instruction-only et couloirs de fermeture séparés |
|
|
|
|
## 3. Décisions API à prouver par le code
|
|
|
|
| Contrat | Décision `pre.001` | Gate futur |
|
|
|--------------------------------------------|---------------------------------------------------------|--------------------------------|
|
|
| `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` |
|
|
| registry dyn | absent | completeness `pre.005` |
|
|
| identity/version/coverage | absents | completeness `pre.005` |
|
|
| Program Account/Event/ReturnData decoder | absents | completeness `pre.005` |
|
|
| ProgramExecutionPreparer | absent | completeness `pre.005` |
|
|
| serde/JSON/codec | absents | firewall `pre.002` / `pre.005` |
|
|
| runtime/logging | absents | firewall `pre.002` / `pre.005` |
|
|
|
|
## 4. External implementation canary
|
|
|
|
La preuve finale doit utiliser une crate consommatrice séparée et vérifier :
|
|
|
|
```text
|
|
implementation de ProgramInstructionDecoder
|
|
associated output défini hors KSP
|
|
Program Pubkey absent du registry Core
|
|
construction de ProgramInstruction via la facade publique retenue
|
|
recognition ProgramMatch ou ExactMatch déterministe
|
|
decode vers Decoded(external value)
|
|
aucun ksp-program-lib
|
|
aucun module privé
|
|
```
|
|
|
|
Ce canari remplace toute affirmation documentaire non exécutable d'extensibilité.
|
|
|
|
## 5. Dependency firewall cible
|
|
|
|
Graphe normal attendu :
|
|
|
|
```text
|
|
ksp-program-api
|
|
├── ksp-core-lib
|
|
│ └── solana-pubkey
|
|
└── ksp-interface-lib
|
|
└── ksp-core-lib
|
|
```
|
|
|
|
Interdits :
|
|
|
|
```text
|
|
Transport
|
|
Store
|
|
Wallet
|
|
Materializer
|
|
Config
|
|
Tauri
|
|
ksp-program-lib
|
|
ksp-logging-lib
|
|
serde / serde_json
|
|
borsh / wincode / bincode
|
|
solana-instruction
|
|
reqwest / tokio / tonic
|
|
tracing
|
|
```
|
|
|
|
## 6. Threat/API gates futurs
|
|
|
|
| Gate | Attendu | Statut initial |
|
|
|---------------------------|--------------------------------------------------------------------------|----------------|
|
|
| unknown Program Pubkey | utilisable sans registry Core | PENDING |
|
|
| 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 |
|
|
|
|
## 7. Gates de fermeture
|
|
|
|
### Gate technique final
|
|
|
|
À exécuter dans la prerelease dédiée :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.14
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-program-api
|
|
cargo test --workspace
|
|
cargo tree -p ksp-program-api --edges normal
|
|
cargo tree --duplicates
|
|
```
|
|
|
|
### Réconciliation documentaire
|
|
|
|
Doit fermer :
|
|
|
|
```text
|
|
ksp-program-api README/USAGE
|
|
plan 021
|
|
validation 017
|
|
indexes/références durables concernées
|
|
```
|
|
|
|
Sans `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant.
|
|
|
|
### Préparation de publication
|
|
|
|
Doit rester limitée à :
|
|
|
|
```text
|
|
Cargo.toml
|
|
CHANGELOG.md
|
|
ROADMAP.md
|
|
prompt de démarrage 0.3.1
|
|
delta de la prerelease
|
|
```
|
|
|
|
## 8. Gate opérateur `pre.002`
|
|
|
|
Le gate fourni le 28 août 2026 est intégralement vert :
|
|
|
|
```text
|
|
cargo fmt --all PASS
|
|
audit Rust général / exports / workspace PASS
|
|
audit Markdown PASS — 170 tables / 119 fichiers
|
|
cargo check --workspace PASS
|
|
cargo clippy --workspace --all-targets PASS
|
|
cargo test -p ksp-program-api PASS — 4 tests d'intégration
|
|
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.003`.
|
|
|
|
## 9. État préparé `pre.003`
|
|
|
|
| Critère | Statut | Preuve |
|
|
|--------------------------------------|--------|----------------------------------------------------------------------|
|
|
| `ProgramInstructionRecognition` | PASS | enum non exhaustif `NoMatch / ProgramMatch / ExactMatch` |
|
|
| `ProgramInstructionDecodeOutcome<T>` | PASS | enum non exhaustif `Decoded(T) / Unsupported` |
|
|
| absence de `Failed` / `Ignored` | PASS | échec réservé au futur `Result`; aucun statut parallèle |
|
|
| Debug recognition | PASS | enum sans payload; Debug dérivé |
|
|
| Debug outcome | PASS | implémentation manuelle sans `T: Debug`, valeur `Decoded` non rendue |
|
|
| dépendances normales | PASS | manifest inchangé : `ksp-core-lib` + `ksp-interface-lib` |
|
|
| module public | PASS | aucun `pub mod`; exports crate-root uniquement |
|
|
| `ProgramInstructionDecoder` | ABSENT | réservé à `pre.004` |
|
|
| 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.
|