182 lines
9.6 KiB
Markdown
182 lines
9.6 KiB
Markdown
<!-- file: docs/validation/017-V0_2_14_PROGRAM_API.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# 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 | `pre.003` |
|
|
| `ProgramInstructionDecodeOutcome<Decoded>` | `Decoded(Decoded) / Unsupported`, non exhaustif | `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 | PENDING |
|
|
| Debug outcome | contenu `Decoded` non rendu automatiquement | PENDING |
|
|
| 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. État préparé `pre.002`
|
|
|
|
Le scaffold matérialisé est :
|
|
|
|
```text
|
|
workspace member PASS structurel
|
|
normal dependencies ksp-core-lib + ksp-interface-lib uniquement
|
|
crate-root facade Error/ErrorCode/ErrorContext/Result/Pubkey + Interface instruction types
|
|
public modules aucun
|
|
README / USAGE présents
|
|
public API canary présent
|
|
dependency firewall canary présent
|
|
ProgramInstructionRecognition absent par contrat pre.002
|
|
ProgramInstructionDecodeOutcome absent par contrat pre.002
|
|
ProgramInstructionDecoder absent par contrat pre.002
|
|
registry / canonical payload / preparer absents
|
|
serde / codecs / runtime logging absents
|
|
```
|
|
|
|
Le gate opérateur `pre.001` fourni le 28 août 2026 est vert pour `cargo fmt --all`, audits Rust/Markdown, `cargo check --workspace` et Clippy workspace.
|
|
|
|
Le passage à `pre.003` reste conditionné au gate opérateur de cet overlay. Les preuves recognition/outcome restent `PENDING` jusqu'à leur tranche dédiée.
|