372 lines
25 KiB
Markdown
372 lines
25 KiB
Markdown
<!-- file: docs/validation/016-V0_2_13_INTERFACE.md -->
|
|
<!-- version: 8 -->
|
|
|
|
# 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 | PASS pre.003 |
|
|
| `ProgramInstruction` | private fields + `try_new` + accessors | PASS pre.006 |
|
|
| account bound | constante publique `<= 255`; enforcement constructeur | PASS pre.006 |
|
|
| data bound | `<= 10_240` | PASS pre.006 |
|
|
| serde | absent | FIXÉ pre.001 |
|
|
| generic codec | absent | FIXÉ pre.001 |
|
|
| Debug instruction | résumé borné, pas payload complet | PASS pre.006 |
|
|
| Error/Result | Core commun + code Interface sûr minimal | PASS 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 | account meta/borne puis instruction/adversarial | PASS pre.006 |
|
|
| `tests/public_api.rs` | consommation crate-root uniquement | PASS pre.006 |
|
|
| external consumer canary | surface utilisable hors modules privés | PASS pre.006 |
|
|
| dependency boundary | firewall exact | PASS pre.006 |
|
|
| release completeness | inventaire exact, aucun domaine supplémentaire | PASS pre.006 |
|
|
| round-trip codec | aucun tant qu'aucun codec | N/A |
|
|
| network smoke | aucun pour crate wire pure | N/A |
|
|
|
|
## 11. Gate technique final validé
|
|
|
|
Le gate opérateur `0.2.13-pre.006` du **28 août 2026** ferme la lane technique :
|
|
|
|
```text
|
|
cargo fmt --all PASS
|
|
python3 scripts/audit_rust_workspace_rules.py PASS
|
|
python3 scripts/audit_markdown_tables.py ... PASS — 162 tables / 119 fichiers
|
|
cargo check --workspace PASS
|
|
cargo clippy --workspace --all-targets PASS
|
|
cargo test -p ksp-interface-lib PASS
|
|
cargo test -p ksp-logging-lib --test ownership PASS
|
|
cargo test --workspace PASS
|
|
cargo tree -p ksp-interface-lib --edges normal Core-only confirmé
|
|
cargo tree --duplicates inspecté
|
|
```
|
|
|
|
Aucun smoke réseau/live n'est exigé : la crate reste une foundation wire pure sans I/O.
|
|
|
|
## 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`.
|
|
|
|
## 14. État préparé `pre.003`
|
|
|
|
| Critère | Statut |
|
|
|-----------------------------------------------------|---------------------------------------------|
|
|
| `ProgramAccountMeta` crate-root | PASS structurel |
|
|
| champs privés | PASS |
|
|
| constructeurs `readonly` / `writable` | PASS |
|
|
| accessors identité/signer/writable | PASS |
|
|
| Pubkey opaque non registry | PASS unit |
|
|
| `MAX_PROGRAM_INSTRUCTION_ACCOUNTS == 255` | PASS unit + public API |
|
|
| enforcement collection `255/256` | PENDING `pre.004` avec `ProgramInstruction` |
|
|
| code `interface.program_instruction_limit_exceeded` | PASS public API |
|
|
| type d'erreur propre Interface | ABSENT, Core commun conservé |
|
|
| `ProgramInstruction` | ABSENT par contrat |
|
|
| data bound | PENDING `pre.004` |
|
|
| serde/codecs | ABSENTS |
|
|
| logging/runtime | ABSENTS |
|
|
| dépendance normale | `ksp-core-lib` uniquement |
|
|
|
|
Le statut `PASS/PENDING` de la borne accounts signifie que la valeur publique est désormais figée à `255`, tandis que le rejet concret de `256` comptes sera testé lorsque la collection existera dans `ProgramInstruction`. Aucun faux wrapper de collection n'est créé dans `pre.003`.
|
|
|
|
## 15. État préparé `pre.004`
|
|
|
|
| Critère | Statut |
|
|
|------------------------------------------------------|----------------------------------------------|
|
|
| `ProgramInstruction` crate-root | PASS structurel |
|
|
| champs privés | PASS |
|
|
| constructeur `try_new` | PASS |
|
|
| accessors `program_id/accounts/data` | PASS |
|
|
| `MAX_PROGRAM_INSTRUCTION_DATA_LEN == 10_240` | PASS unit + public API |
|
|
| accounts `255` accepté / `256` refusé | PASS unit |
|
|
| data `10_240` accepté / `10_241` refusé | PASS unit |
|
|
| accounts/data vides | PASS unit |
|
|
| ordre + doublons accounts | PASS unit |
|
|
| Program Pubkey opaque/non registry | PASS unit |
|
|
| erreur borne Core commune | PASS |
|
|
| contexte erreur limité aux longueurs/plafonds sûrs | PASS unit |
|
|
| Debug résumé sans accounts/payload | PASS unit |
|
|
| serde/codecs | ABSENTS |
|
|
| `solana-instruction` | ABSENT |
|
|
| logging/runtime | ABSENTS |
|
|
| dépendance normale | `ksp-core-lib` uniquement |
|
|
| `cargo test --workspace` sur preuve entrée `pre.003` | NON FOURNI — à rejouer au gate opérateur 004 |
|
|
|
|
La tranche ferme ainsi le premier lot générique `{ program_id, accounts, data }` sans ajouter de codec ni de comportement Program. Le hardening `pre.005` doit porter sur l'usage externe, les cas adversariaux et le firewall, pas sur une nouvelle famille wire.
|
|
|
|
## 16. État préparé `pre.005`
|
|
|
|
Le gate opérateur `pre.004` est complet : fmt, audits Rust/Markdown, `cargo check --workspace`, Clippy, `cargo test -p ksp-interface-lib`, `cargo test --workspace` et graphes Cargo sont verts/inspectés.
|
|
|
|
La tranche `pre.005` ajoute uniquement des canaris de hardening :
|
|
|
|
```text
|
|
external consumer crate présent via tests/external_consumer.rs
|
|
release completeness présent via tests/release_completeness.rs
|
|
crate-root exports exacts vérifiés par source canary
|
|
production module inventory exact vérifié par filesystem canary
|
|
source dependency firewall étendu à tous les src production
|
|
narrowing cast / encode/decode caché interdits par source canary
|
|
Vec accounts/data sans réallocation vérifié par identité de pointeur
|
|
payload hostile dans Error/Debug absent attendu
|
|
account material arbitraire dans Error absent attendu
|
|
nouveau type wire aucun
|
|
nouvelle dépendance aucune
|
|
codec/logging/runtime toujours absents
|
|
```
|
|
|
|
Les nouveaux tests sont **présents mais non déclarés PASS dans le sandbox**, qui ne dispose pas de Cargo. Leur statut final dépend du gate opérateur `pre.005`.
|
|
|
|
Le consumer externe est un test d'intégration Rust, donc compilé par Cargo dans un crate distinct de `ksp-interface-lib`. Sa source ne consomme que les exports du crate-root ; les modules privés ne sont pas utilisés.
|
|
|
|
Le canari de complétude impose exactement les exports publics retenus et exactement quatre modules/fichiers de production : `error.rs`, `lib.rs`, `program_account_meta.rs`, `program_instruction.rs`. Cette contrainte ferme explicitement le risque d'ajout opportuniste d'une seconde famille wire avant la release stable.
|
|
|
|
## 17. Gate `pre.005` et correctif `pre.005-fix.001`
|
|
|
|
Le gate ciblé Interface est intégralement vert :
|
|
|
|
```text
|
|
unit tests Interface 10/10 PASS
|
|
manifest/source firewall 4/4 PASS
|
|
external consumer 1/1 PASS
|
|
public API 5/5 PASS
|
|
release completeness 3/3 PASS
|
|
doctests 0 échec
|
|
```
|
|
|
|
Le workspace échoue ensuite dans le canari transversal Logging :
|
|
|
|
```text
|
|
ksp-logging-lib/tests/ownership.rs
|
|
workspace_crates_do_not_bypass_ksp_logging_facade
|
|
```
|
|
|
|
Diagnostic confirmé : `tests/dependency_boundary.rs` contient le littéral `tracing::` uniquement comme pattern interdit. Le scanner Logging travaille sur le texte brut des `.rs` et interprète donc ce pattern de test comme un bypass réel. Le graphe Cargo Interface reste pourtant :
|
|
|
|
```text
|
|
ksp-interface-lib
|
|
└── ksp-core-lib
|
|
└── solana-pubkey 4.3.0
|
|
```
|
|
|
|
`pre.005-fix.001` remplace uniquement ce littéral source par une construction compile-time équivalente `concat!("tracing", "::")`. La propriété testée reste identique ; seule l'interaction entre deux scanners est corrigée.
|
|
|
|
Statut final du fix après gate opérateur :
|
|
|
|
```text
|
|
production src inchangé
|
|
API publique inchangée
|
|
dépendances inchangées
|
|
logging runtime Interface toujours absent
|
|
codec toujours absent
|
|
version technique 0.2.13-pre.5.fix.1
|
|
cargo test -p ksp-interface-lib PASS
|
|
cargo test -p ksp-logging-lib --test ownership PASS
|
|
cargo test --workspace PASS
|
|
cargo tree Interface Core-only confirmé
|
|
```
|
|
|
|
## 18. Gate technique final `pre.006`
|
|
|
|
Le gate final a confirmé la surface complète sans nouvelle modification technique :
|
|
|
|
```text
|
|
unit Interface 10/10 PASS
|
|
dependency boundary 4/4 PASS
|
|
external consumer 1/1 PASS
|
|
public API 5/5 PASS
|
|
release completeness 3/3 PASS
|
|
ownership Logging 2/2 PASS
|
|
workspace PASS
|
|
Cargo graph Interface ksp-core-lib uniquement
|
|
```
|
|
|
|
Les duplicates observés dans le workspace sont extérieurs au graphe normal d'Interface et ne proviennent d'aucune dépendance ajoutée par `0.2.13`.
|
|
|
|
La validation technique de la release candidate est fermée.
|
|
|
|
## 19. 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-interface-lib/README.md` | PASS structurel | ownership, surface finale, bornes, firewall, frontières |
|
|
| `crates/ksp-interface-lib/USAGE.md` | PASS structurel | usage crate-root, construction metas/instruction, erreurs et limites |
|
|
| `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` | PASS structurel | contenu réel `0.2.13` + reports `0.2.14` / `0.3.2+` |
|
|
| `docs/plans/020-V0_2_13_INTERFACE_PLAN.md` | PASS structurel | gate `pre.006` fermé + lane documentaire finale |
|
|
| `docs/validation/016-V0_2_13_INTERFACE.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 n'ajoute aucun code/test/codec/dépendance et ne modifie ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt `0.2.14`. Ces trois surfaces restent réservées à `pre.008`.
|
|
|
|
Le gate opérateur de `pre.007` doit rester déterministe : audits, check, Clippy et workspace tests suffisent ; aucun smoke live ni nouveau `cargo tree` n'est requis si l'overlay documentaire est appliqué exactement.
|