216 lines
15 KiB
Markdown
216 lines
15 KiB
Markdown
<!-- file: docs/validation/016-V0_2_13_INTERFACE.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# Validation `0.2.13` — Interface / wire foundation
|
|
|
|
## 1. Objet
|
|
|
|
Cette matrice est ouverte par `0.2.13-pre.001`. Elle suit la première surface de `ksp-interface-lib` et enregistre les critères de fermeture sans transformer Interface en Program API ou en modèle RAW/CORE générique.
|
|
|
|
Scope retenu :
|
|
|
|
```text
|
|
ProgramAccountMeta
|
|
ProgramInstruction
|
|
Pubkey via ksp-core-lib
|
|
bornes comptes/data
|
|
aucun codec générique
|
|
aucun comportement Program
|
|
```
|
|
|
|
## 2. Baseline stable
|
|
|
|
| Contrat | Attendu | Statut `pre.001` |
|
|
|----------------------------|------------------------------------------------|------------------------------------------|
|
|
| archive | `khadhroony-solana-project-v0.2.12.zip` stable | PASS marqueurs internes |
|
|
| workspace version entrée | `0.2.12` | PASS |
|
|
| `deltas/0.2.12/rel.001.md` | présent | PASS |
|
|
| prompt 018 | présent | PASS |
|
|
| `.git` | optionnel archive | ABSENT — tag non revérifiable localement |
|
|
| `ksp-interface-lib` entrée | absent | PASS |
|
|
| `ksp-program-api` entrée | absent | PASS |
|
|
| gate Cargo stable | fmt/check/clippy/test | PASS preuve opérateur |
|
|
| audits Python base | Rust + Markdown | PASS sandbox |
|
|
|
|
## 3. Lecture et ownership internes
|
|
|
|
| Famille | Constat | Décision |
|
|
|-----------------------------------|-----------------------------------------------------|-------------------------------------|
|
|
| Core `Pubkey` | public crate-root, `solana-pubkey ^4.3` | réutiliser; aucun wrapper Interface |
|
|
| Core Program IDs | 18 identités fondamentales + registry | laisser Core |
|
|
| Core Error/Result | contrat commun workspace | réutiliser pour Interface |
|
|
| HTTP transaction/block DTOs | projections JSON-RPC Transport | laisser Transport |
|
|
| Yellowstone instruction/meta DTOs | projections protobuf/Geyser | laisser Transport |
|
|
| Architecture 006 | Interface wire passive; Program comportement séparé | scope conforme |
|
|
| Roadmap 0.3.2 | wires génériques acquisition/CORE reportés | ne pas anticiper |
|
|
|
|
## 4. Héritage kbot3
|
|
|
|
| Concept | Verdict | Preuve attendue dans KSP |
|
|
|-----------------------------------------|--------------------|--------------------------------------------|
|
|
| ordered account meta | REPRENDRE | `ProgramAccountMeta` sans naming execution |
|
|
| passive `{program_id, accounts, data}` | REPRENDRE | `ProgramInstruction` borné |
|
|
| string Pubkey/ProgramId wrappers | REDESSINER | Core `Pubkey` directement |
|
|
| unbounded payload | REDESSINER | borne + Debug résumé |
|
|
| decoder traits/recognition/proofs | REPORTER 0.2.14 | absents d'Interface |
|
|
| instruction path/CPI/replay context | REPORTER 0.3.2+ | absents de 0.2.13 |
|
|
| canonical transaction/replay JSON model | REPORTER/redéfinir | aucun portage |
|
|
| prepared execution policy/signers | REPORTER | absents d'Interface |
|
|
| monolithic `ks-lib` organization | REJETER | crate ownership séparé |
|
|
|
|
## 5. Audit externe courant
|
|
|
|
| Référence | État observé 2026-08-27 | Décision de validation |
|
|
|------------------------------|------------------------------------------------------------------|--------------------------------------------------------------|
|
|
| `solana-instruction` | 3.5.0; `Pubkey ^4.3.0`; codecs optionnels | parité conceptuelle requise, dépendance non requise |
|
|
| Solana `Instruction` | program_id + ordered AccountMeta + opaque bytes | forme cible exacte |
|
|
| Solana syscall bounds | 255 account metas CPI; data 10 KiB; 128 unique account infos CPI | 255/10 KiB = admission Interface; 128 non appliqué aux metas |
|
|
| `solana-loader-v3-interface` | 8.1.1; compatible générations observées | hors scope, réaudit au vertical réel |
|
|
| licence Anza SDK | Apache-2.0 | compatible si future dépendance réellement retenue |
|
|
|
|
## 6. Matrice de frontière de release
|
|
|
|
| Surface | Owner | 0.2.13 | 0.2.14 | 0.3.2+ | Statut |
|
|
|-----------------------------------|----------------|-----------|-----------------|----------------|---------|
|
|
| Pubkey / Program IDs fondamentaux | Core | reuse | reuse | reuse | FIXÉ |
|
|
| Program account meta | Interface | IMPLEMENT | consume | reuse | FIXÉ |
|
|
| Program instruction passive | Interface | IMPLEMENT | consume | reuse | FIXÉ |
|
|
| Program-specific codec/layout | Interface | OUT | si besoin réel | selon vertical | REPORTÉ |
|
|
| decoder/preparer traits | Program API | OUT | AUDIT/IMPLEMENT | consume | REPORTÉ |
|
|
| Transport provider DTOs | Transport | UNCHANGED | UNCHANGED | adapter future | FIXÉ |
|
|
| generic acquisition/replay wire | Interface/CORE | OUT | OUT | IMPLEMENT | REPORTÉ |
|
|
| RAW persistence | Store | OUT | OUT | `0.3.1`+ | REPORTÉ |
|
|
|
|
## 7. API publique cible
|
|
|
|
| Contrat | Attendu final `0.2.13` | Statut |
|
|
|----------------------|--------------------------------------------------------|------------------|
|
|
| crate | `ksp-interface-lib` membre workspace | PASS pre.002 |
|
|
| façade | exports explicites crate-root; aucun `pub mod` | PASS pre.002 |
|
|
| Pubkey | réexport/usage contrôlé de Core; pas de type parallèle | PASS pre.002 |
|
|
| `ProgramAccountMeta` | private fields + writable/readonly + accessors | TODO pre.003 |
|
|
| `ProgramInstruction` | private fields + `try_new` + accessors | TODO pre.004 |
|
|
| account bound | `<= 255` | TODO pre.003/004 |
|
|
| data bound | `<= 10_240` | TODO pre.004 |
|
|
| serde | absent | FIXÉ pre.001 |
|
|
| generic codec | absent | FIXÉ pre.001 |
|
|
| Debug instruction | résumé borné, pas payload complet | TODO pre.004 |
|
|
| Error/Result | Core commun + codes Interface sûrs | TODO pre.003 |
|
|
|
|
## 8. Robustness/adversarial
|
|
|
|
| Cas | Attendu | Gate |
|
|
|------------------------------|--------------------------|-------------------------|
|
|
| 0 account | accepté | unit |
|
|
| 255 accounts | accepté | unit |
|
|
| 256 accounts | refus avant état valide | unit |
|
|
| 0 data | accepté | unit |
|
|
| 10_240 bytes | accepté | unit |
|
|
| 10_241 bytes | refus | unit |
|
|
| duplicate accounts | ordre/doublons conservés | unit + public API |
|
|
| unknown Program Pubkey | accepté | unit |
|
|
| hostile data marker in Debug | absent du rendu | unit |
|
|
| hostile data marker in Error | absent du rendu/context | unit |
|
|
| unchecked narrowing cast | absent | source audit/Clippy |
|
|
| malformed binary wire | N/A sans codec | ne pas inventer un test |
|
|
| unknown discriminant | N/A sans enum wire | réouvrir au vertical |
|
|
| serde hostile allocation | N/A serde absent | dependency canary |
|
|
|
|
## 9. Dependency firewall
|
|
|
|
| Dépendance depuis Interface | Attendu final | Preuve |
|
|
|-------------------------------------|----------------------------------------|------------------------|
|
|
| `ksp-core-lib` | AUTORISÉ / requis | manifest + cargo tree |
|
|
| `ksp-program-api` / Program Lib | INTERDIT | manifest/source canary |
|
|
| On-chain / Off-chain Transport | INTERDIT | manifest/source canary |
|
|
| Config / Wallet / Store / Tauri | INTERDIT | manifest/source canary |
|
|
| reqwest / tonic / tokio / websocket | INTERDIT | cargo tree + manifest |
|
|
| serde / serde_json | ABSENT en foundation | manifest + cargo tree |
|
|
| borsh / bincode / wincode | ABSENT en foundation | manifest + cargo tree |
|
|
| `solana-instruction` | ABSENT tant qu'interop réel non requis | manifest + cargo tree |
|
|
|
|
Graphes attendus :
|
|
|
|
```bash
|
|
cargo tree -p ksp-interface-lib --edges normal
|
|
cargo tree --duplicates
|
|
```
|
|
|
|
Si une nouvelle dépendance externe apparaît après `pre.001`, la présente matrice doit être rouverte avant acceptation.
|
|
|
|
## 10. Tests de release
|
|
|
|
| Famille | Attendu | Statut |
|
|
|--------------------------|------------------------------------------------|--------------|
|
|
| unit tests privés | constructeurs/bornes/order/debug/errors | TODO |
|
|
| `tests/public_api.rs` | consommation crate-root uniquement | PASS pre.002 |
|
|
| external consumer canary | surface utilisable hors modules privés | TODO |
|
|
| dependency boundary | firewall exact | PASS pre.002 |
|
|
| release completeness | inventaire exact, aucun domaine supplémentaire | TODO |
|
|
| round-trip codec | aucun tant qu'aucun codec | N/A |
|
|
| network smoke | aucun pour crate wire pure | N/A |
|
|
|
|
## 11. Gate technique final attendu
|
|
|
|
Avant réconciliation documentaire :
|
|
|
|
```text
|
|
cargo fmt --all PASS attendu
|
|
python3 scripts/audit_rust_workspace_rules.py PASS attendu
|
|
python3 scripts/audit_markdown_tables.py ... PASS attendu
|
|
cargo check --workspace PASS attendu
|
|
cargo clippy --workspace --all-targets PASS attendu
|
|
cargo test --workspace PASS attendu
|
|
cargo tree -p ksp-interface-lib --edges normal inspecté
|
|
cargo tree --duplicates inspecté
|
|
```
|
|
|
|
Aucun smoke réseau/live n'est exigé par défaut.
|
|
|
|
## 12. État `pre.001`
|
|
|
|
| Critère de sortie prompt | Statut |
|
|
|-------------------------------------------|-----------------------------------|
|
|
| sources internes obligatoires relues | PASS |
|
|
| base stable confirmée | PASS marqueurs + preuve opérateur |
|
|
| Core/Transport inventoriés | PASS |
|
|
| architecture 006 confrontée à la base | PASS |
|
|
| archive kbot3 auditée | PASS |
|
|
| matrice héritage | PASS |
|
|
| frontière 0.2.13 / 0.2.14 / 0.3.2 | PASS |
|
|
| premier lot exact décidé | PASS |
|
|
| ownership types | PASS |
|
|
| dépendances candidates auditables/bornées | PASS |
|
|
| threat model | PASS |
|
|
| test strategy | PASS |
|
|
| dependency graph cible | PASS |
|
|
| plan + validation | PASS |
|
|
| forecast/sizing | PASS |
|
|
| implémentation Program lourde | ABSENTE |
|
|
|
|
Le passage à `pre.002` est autorisé après application du delta et validation opérateur. Le statut des items d'implémentation reste volontairement `TODO` jusqu'aux tranches correspondantes.
|
|
|
|
## 13. État préparé `pre.002`
|
|
|
|
Le scaffold matérialisé conserve volontairement une surface minimale :
|
|
|
|
```text
|
|
workspace member PASS structurel
|
|
normal dependency ksp-core-lib uniquement
|
|
Pubkey réexport Core au crate-root
|
|
public modules aucun
|
|
ProgramAccountMeta absent par contrat pre.002
|
|
ProgramInstruction absent par contrat pre.002
|
|
serde / borsh / bincode / wincode absents
|
|
network/runtime dependencies absentes
|
|
ksp-logging-lib absent
|
|
constants.rs / TRACING_TARGET absents
|
|
README / USAGE initiaux
|
|
public API canary présent
|
|
dependency firewall canary présent
|
|
```
|
|
|
|
Le logging reste volontairement absent : la foundation `0.2.13` est passive et n'émet aucun événement/span runtime. Si une future surface comportementale démontre un besoin réel de logging, `ksp-logging-lib`, `src/constants.rs` et `TRACING_TARGET` devront être introduits ensemble conformément à `DEP-LOG-004` et `DEP-LOG-010`.
|
|
|
|
Le passage à `pre.003` reste conditionné au gate opérateur complet sur l'overlay `pre.002`.
|