307 lines
19 KiB
Markdown
307 lines
19 KiB
Markdown
<!-- file: docs/validation/017-V0_2_14_PROGRAM_API.md -->
|
|
<!-- version: 6 -->
|
|
|
|
# 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` | 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` |
|
|
| 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 matérialisée en `pre.004` utilise une crate d'intégration consommatrice séparée et vérifie :
|
|
|
|
```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é. Son gate opérateur `pre.004` est confirmé intégralement vert.
|
|
|
|
## 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 | PASS `pre.004` |
|
|
| max Interface input | decoder consomme l'input déjà borné sans nouvelle allocation obligatoire | PASS `pre.005` |
|
|
| malformed program payload | `Err` ou `Unsupported`; aucun echo n'est ajouté par le contrat | PASS `pre.005` |
|
|
| Debug recognition | aucun payload | PASS |
|
|
| Debug outcome | contenu `Decoded` non rendu automatiquement | PASS |
|
|
| 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
|
|
|
|
### 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 |
|
|
|
|
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 `pre.004` est confirmé intégralement vert et autorise `pre.005`.
|
|
|
|
## 12. Gate opérateur `pre.004`
|
|
|
|
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 — 172 tables / 121 fichiers
|
|
cargo check --workspace PASS
|
|
cargo clippy --workspace --all-targets PASS
|
|
cargo test -p ksp-program-api PASS — 11 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.005`.
|
|
|
|
## 13. État préparé `pre.005`
|
|
|
|
| Critère | Statut | Preuve |
|
|
|--------------------------------------|--------|----------------------------------------------------------------------|
|
|
| exact crate-root export inventory | PASS | test `release_completeness` sur les 10 réexports |
|
|
| exact production module inventory | PASS | `lib.rs`, decode vocabulary et decoder trait uniquement |
|
|
| public enum inventory | PASS | Recognition + DecodeOutcome uniquement |
|
|
| closed-world Program enum | ABSENT | aucun `ProgramKind`/inventaire public central |
|
|
| registry / descriptors | ABSENT | aucune collection/runtime selection/identity-version-coverage |
|
|
| `ProgramExecutionPreparer` | ABSENT | scope négatif maintenu |
|
|
| serde / JSON / Any / codecs | ABSENT | manifest + source canaries |
|
|
| logging / runtime / IO | ABSENT | aucune dépendance ou primitive runtime/FS/env/network |
|
|
| max Interface input | PASS | 255 accounts + 10 240 bytes traversent le trait par référence |
|
|
| malformed hostile payload | PASS | `Result::Err` Core reste sûr sans echo automatique du payload |
|
|
| Debug outcome | PASS | valeur décodée jamais formatée |
|
|
| associated `Decoded` implicit bounds | ABSENT | canari avec output `Rc<Cell<_>>`, donc non-`Send`/non-`Sync` accepté |
|
|
| dyn heterogeneous claim | ABSENT | aucun `dyn ProgramInstructionDecoder`/registry |
|
|
| dépendances normales | PASS | `ksp-core-lib` + `ksp-interface-lib` uniquement |
|
|
|
|
La sécurité des messages/contextes produits volontairement par une implémentation tierce reste sa responsabilité ; `ksp-program-api` garantit seulement qu'il n'ajoute aucun canal parallèle ni copie automatique du payload hostile.
|
|
|
|
Le gate opérateur de `pre.005` a révélé uniquement le faux positif cross-crate logging corrigé par `pre.005-fix.001`. Le gate du fix est désormais intégralement vert et autorise le gate technique final `pre.006`.
|
|
|
|
## 14. Gate opérateur `pre.005-fix.001`
|
|
|
|
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 — 173 tables / 123 fichiers
|
|
cargo check --workspace PASS
|
|
cargo clippy --workspace --all-targets PASS
|
|
cargo test -p ksp-program-api PASS — 18 tests Rust
|
|
cargo test -p ksp-logging-lib --test ownership PASS — 2/2
|
|
cargo test --workspace PASS
|
|
cargo tree -p ksp-program-api --edges normal PASS — Core + Interface uniquement
|
|
cargo tree --duplicates inspecté
|
|
```
|
|
|
|
Le faux positif `tracing` du canari `release_completeness.rs` est fermé sans ajout de dépendance, sans modification de production et sans affaiblissement du scanner logging workspace.
|
|
|
|
## 15. Gate technique final préparé `pre.006`
|
|
|
|
`pre.006` ne modifie aucun fichier de production ni de test. Le gate final doit confirmer la candidate suivante sans élargissement :
|
|
|
|
| Critère | Attendu `pre.006` |
|
|
|--------------------------------------|-------------------------------------------|
|
|
| API Program | exactement la surface fermée en `pre.005` |
|
|
| tests `ksp-program-api` | 18 tests Rust PASS |
|
|
| ownership Logging | 2 tests PASS |
|
|
| workspace | PASS |
|
|
| graphe normal `ksp-program-api` | Core + Interface uniquement |
|
|
| registry / preparer / payload D3 | ABSENTS |
|
|
| serde / codec / logging runtime / IO | ABSENTS |
|
|
| README / USAGE | non réconciliés ici |
|
|
| CHANGELOG / ROADMAP / prompt suivant | non modifiés |
|
|
|
|
Aucun smoke réseau/live n'est requis : `ksp-program-api` reste une API déclarative instruction-only sans I/O.
|