Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
84ef8bb1f1441dcc9fd08786191421ebd7a93792
khadhroony-solana-project/docs/validation/017-V0_2_14_PROGRAM_API.md
SinuS Von SifriduS 2cf00e9426 v0.2.14-pre.007
2026-08-28 16:16:15 +02:00

347 lines
22 KiB
Markdown
Raw Blame History

<!-- file: docs/validation/017-V0_2_14_PROGRAM_API.md -->
<!-- version: 7 -->
# Validation `0.2.14` — Program API foundation
## 1. Objet
Cette matrice, ouverte par `0.2.14-pre.001`, est réconciliée par `pre.007` après fermeture intégralement verte du gate technique `pre.006`. Elle conserve l'historique des preuves par tranche et la surface candidate finale.
Le scope final reste 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
Le gate technique dédié `pre.006` est fermé intégralement vert. Les commandes de référence étaient :
```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 -p ksp-logging-lib --test ownership
cargo test --workspace
cargo tree -p ksp-program-api --edges normal
cargo tree --duplicates
```
### Réconciliation documentaire
`pre.007` ferme :
```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.
## 16. Gate technique final `pre.006`
Le gate opérateur fourni le 28 août 2026 confirme la candidate technique complète :
```text
cargo fmt --all PASS
audits Rust / export completeness / workspace PASS
audit Markdown PASS — 174 tables / 124 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é
```
Les duplicates observés sont ceux du workspace global et ne proviennent d'aucune dépendance ajoutée par Program API. Aucun smoke live n'est applicable à cette foundation déclarative sans I/O.
La validation technique de la release candidate est fermée.
## 17. Réconciliation documentaire `pre.007`
La documentation finale candidate est alignée sur les preuves techniques :
| Référence durable | Statut `pre.007` | Contrat réconcilié |
|-------------------------------------------------|------------------|---------------------------------------------------------------------------|
| `crates/ksp-program-api/README.md` | PASS structurel | ownership, surface exacte, semantics, hardening, firewall et frontières |
| `crates/ksp-program-api/USAGE.md` | PASS structurel | usage crate-root, implémentation externe, sélection, outcome et Debug sûr |
| `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` | PASS structurel | contenu réel `0.2.14` + reports runtime/D3/preparer |
| `docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md` | PASS structurel | gate `pre.006` fermé + lane documentaire finale |
| `docs/validation/017-V0_2_14_PROGRAM_API.md` | PASS structurel | statuts finaux et preuves opérateur |
| index `docs/000`, plans et validation | PASS structurel | candidate réconciliée sans publication stable prématurée |
La tranche ne modifie aucun code/test/manifest de crate/dépendance et ne touche ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt `0.3.1`. Ces surfaces restent réservées à la préparation minimale de publication `pre.008`.
Le gate opérateur de `pre.007` doit rester déterministe : audits, check, Clippy, tests ciblés Program/Logging et workspace suffisent ; aucun smoke live ni nouveau `cargo tree` n'est requis si l'overlay documentaire est appliqué exactement.
Reference in New Issue View Git Blame Copy Permalink