Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.5-pre.001-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-31 10:21:47 +02:00
parent c24e4c48f8
commit 75e8030b07
3 changed files with 430 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md
View File

@@ -1,11 +1,11 @@
<!-- file: docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Validation `0.3.5` — Interface passive acquisition events
## 1. Portée
Ce document est ouvert par `0.3.5-pre.001`. Il enregistre uniquement des constats d'audit et des décisions de gate réellement effectués ; aucun test Cargo de `0.3.5` n'est déclaré PASS dans cette tranche tant qu'il n'a pas été rejoué par l'opérateur.
Ce document est ouvert par `0.3.5-pre.001` et corrigé par `0.3.5-pre.001-fix.001`. Le fix enregistre les corrections sémantiques du gate ainsi que le gate Cargo réellement rejoué par l'opérateur sur `0.3.5-pre.1`.
Base :
@@ -28,52 +28,49 @@ Cette preuve est l'entrée de `0.3.5`. Elle n'est pas réétiquetée comme valid
## 3. Gate de lecture `pre.001`
| Contrôle | Résultat | Preuve / décision |
|---------------------------------------|----------|--------------------------------------------------------------------------------------------------------|
| règles globales relues | PASS | familles KSP-API/TRANSPORT/STORE/NOTIFY/PROC/REL et DEP applicables relues |
| architecture durable relue | PASS | Interface passif, Transport protocol/runtime, Store persistant, composition owner des conversions |
| fondation Interface stable relue | PASS | surface Program petite ; dépendance normale Core-only |
| Store API RAW relu | PASS | `RawTransaction*` + `RawAccount*` restent Store-owned |
| Store/PostgreSQL `0.3.2`–`0.3.4` relu | PASS | RAW physique 10/10 fermé ; aucune rétention account |
| surfaces HTTP/WS/gRPC/Helius relues | PASS | status/log/slot/vote/account/transaction/block/Entry inventoriés |
| documentation Solana courante auditée | PASS | `slotSubscribe`, `slotsUpdatesSubscribe`, status/log/vote/account/program, getTransaction/getBlock |
| Yellowstone upstream courant audité | PASS | `SlotStatus` et familles SubscribeUpdate courantes |
| Helius courant audité | PASS | standard WSS préserve wire Solana ; Enhanced `transactionSubscribe` reste extension provider |
| producer/consumer inventory | PASS | une intersection lifecycle slot justifiée ; autres familles non admises |
| threat model | PASS | mega enum, Option soup, Store duplication, timestamp/finality confusion et provider promotion couverts |
| sizing release | PASS | 7 prereleases prévues avant `rel.001`, une seule famille fonctionnelle |
| Contrôle | Résultat | Preuve / décision |
| ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| règles globales relues | PASS | familles KSP-API/TRANSPORT/STORE/NOTIFY/PROC/REL et DEP applicables relues |
| architecture durable relue | PASS | Interface passif, Transport protocol/runtime, Store persistant, composition owner des conversions |
| fondation Interface stable relue | PASS | surface Program petite ; dépendance normale Core-only |
| Store API RAW relu | PASS | `RawTransaction*` + `RawAccount*` restent Store-owned |
| Store/PostgreSQL `0.3.2`–`0.3.4` relu | PASS | RAW physique 10/10 fermé ; aucune rétention account |
| surfaces HTTP/WS/gRPC/Helius relues | PASS | status/log/slot/vote/account/transaction/block/Entry inventoriés |
| documentation Solana courante auditée | PASS | `slotSubscribe`, `slotsUpdatesSubscribe`, status/log/vote/account/program, getTransaction/getBlock |
| Yellowstone upstream courant audité | PASS | `SlotStatus` et familles SubscribeUpdate courantes |
| Helius courant audité | PASS | standard WSS préserve wire Solana ; Enhanced `transactionSubscribe` reste extension provider |
| producer/consumer inventory | PASS | lifecycle slot 7 stages admis ; TransactionExecutionEvent rouvert comme candidat actif |
| threat model | PASS | mega enum, Option soup, Store duplication, mapping lifecycle explicite et provider promotion couverts |
| sizing release | PASS | 8 prereleases prévues avant `rel.001` ; second candidat soumis à gate dédié |
## 4. Matrice de décision par famille
| Famille | Décision | Owner | Motif déterminant |
|---------------------------------------|-----------------|-----------------|---------------------------------------------------------------------------------------------|
| slot lifecycle intersection | ADMIS | Interface | faits compacts exacts produits par Solana WS et Yellowstone ; pas de persistence |
| root/finality | REPORTÉ | Transport | aucune équivalence normative exacte `root` <-> `Finalized` retenue |
| optimistic/confirmed | REPORTÉ | Transport | aucune équivalence normative exacte retenue |
| logs realtime | REPORTÉ | Transport | pas de seconde surface indépendante équivalente ; Yellowstone logs restent transaction/meta |
| transaction status | REPORTÉ | Transport | HTTP snapshot != WS one-shot commitment != Yellowstone execution update |
| vote | REPORTÉ | Transport | gossip pré-consensus != transaction qualifiée `is_vote` |
| account/program | REJET Interface | Store/Transport | risque de doublon `RawAccountState`/observation ou wrapper Transport |
| transaction | REJET Interface | Store/Transport | `RawTransaction`/observation déjà persistants |
| block | REJET Interface | Transport | conteneur/payload d'acquisition ; aucun besoin passif transversal démontré |
| Yellowstone Entry | REJET Interface | Transport | surface protocolaire mono-producer |
| persisted-data available notification | REJET Interface | Store API | ownership normatif `KSP-NOTIFY-001..006` |
| Helius Enhanced transaction | REJET Interface | Transport | extension provider-specific |
| Famille | Décision | Owner | Motif déterminant |
| ------------------------------------- | ------------------- | ------------------------------ | ---------------------------------------------------------------------------------------- |
| slot lifecycle intersection | ADMIS | Interface | 7 faits compacts normalisés ; détails protocol/provider restent Transport |
| transaction execution | CANDIDAT ACTIF | Interface si gate passe | intersection candidate `slot + signature + outcome` sur Solana/Yellowstone/Helius |
| logs realtime | IDÉE DIFFÉRÉE | Interface si futur gate | payload variable/bornes/consumer non démontrés ; ne pas mélanger avec execution |
| signature commitment/snapshot | REPORTÉ | Transport | HTTP snapshot != WS one-shot commitment ; distinct de l'exécution |
| vote | REPORTÉ | Transport | gossip pré-consensus != transaction qualifiée `is_vote` |
| account/program | REJET Interface | Store/Transport | risque de doublon `RawAccountState`/observation ou wrapper Transport |
| transaction | REJET Interface | Store/Transport | `RawTransaction`/observation déjà persistants |
| block | REJET Interface | Transport | conteneur/payload d'acquisition ; aucun besoin passif transversal démontré |
| Yellowstone Entry | REPORTÉ | Transport DTO | mono-producer aujourd'hui ; un futur fait transversal KSP serait réaudité pour Interface |
| persisted-data available notification | REJET Interface | Store API | ownership normatif `KSP-NOTIFY-001..006` |
| Helius Enhanced transaction | PRODUCTEUR CANDIDAT | Transport DTO / Interface fact | DTO provider-specific ; projection possible seulement vers un fait commun admis |
## 5. Intersection lifecycle retenue
| Stage Interface prévu | Producer Solana standard | Producer Yellowstone | Verdict | Détails exclus du contrat commun |
|--------------------------|----------------------------------------|----------------------|---------|-------------------------------------------------------------------------|
| `Processed` | `slotSubscribe` | `Processed` | PASS | WS parent/root ; Yellowstone filters/created_at/parent |
| `FirstShredReceived` | `slotsUpdates::FirstShredReceived` | `FirstShredReceived` | PASS | timestamps/metadata source |
| `Completed` | `slotsUpdates::Completed` | `Completed` | PASS | timestamps/metadata source |
| `CreatedBank` | `slotsUpdates::CreatedBank` | `CreatedBank` | PASS | parent reste dans le DTO Transport riche |
| `Dead` | `slotsUpdates::Dead` | `Dead` | PASS | diagnostic `err`/`dead_error` et timestamp restent Transport |
| `Frozen` | `slotsUpdates::Frozen` | — | FAIL | pas d'intersection |
| `OptimisticConfirmation` | `slotsUpdates::OptimisticConfirmation` | `Confirmed` | FAIL | noms/semantiques proches insuffisants sans équivalence normative exacte |
| `Root` | `rootSubscribe` / `slotsUpdates::Root` | `Finalized` | FAIL | aucune normalisation root/finalized inventée |
| `Confirmed` | — | `Confirmed` | FAIL | producer standard exact absent |
| `Finalized` | — | `Finalized` | FAIL | producer standard exact absent |
| Stage Interface prévu | Producer Solana standard | Producer Yellowstone | Verdict | Détails exclus du contrat commun |
| ------------------------- | -------------------------------------- | -------------------- | ------- | -------------------------------------------------------------------------------- |
| `Processed` | `slotSubscribe` | `Processed` | PASS | WS parent/root ; Yellowstone filters/created_at/parent |
| `FirstShredReceived` | `slotsUpdates::FirstShredReceived` | `FirstShredReceived` | PASS | timestamps/metadata source |
| `Completed` | `slotsUpdates::Completed` | `Completed` | PASS | timestamps/metadata source |
| `CreatedBank` | `slotsUpdates::CreatedBank` | `CreatedBank` | PASS | parent reste dans le DTO Transport riche |
| `Dead` | `slotsUpdates::Dead` | `Dead` | PASS | diagnostic `err`/`dead_error` et timestamp restent Transport |
| `OptimisticallyConfirmed` | `slotsUpdates::OptimisticConfirmation` | `Confirmed` | PASS | nom KSP conserve l'optimistic confirmation ; delivery/metadata restent Transport |
| `Rooted` | `rootSubscribe` / `slotsUpdates::Root` | `Finalized` | PASS | nom KSP conserve le fait root ; `Finalized` reste un label Yellowstone source |
| — | `slotsUpdates::Frozen` | — | FAIL | pas d'intersection |
## 6. Validation anti-Option-soup
@@ -86,6 +83,7 @@ TransactionStatusObservation {
received?: ...,
is_vote?: ...,
transaction_index?: ...,
logs?: ...,
...
}
@@ -99,16 +97,22 @@ SlotLifecycleEvent {
}
```
La surface visée reste conceptuellement :
La surface admise reste conceptuellement :
```text
SlotLifecycleEvent { slot, stage }
```
Le candidat séparé, non encore admis, reste :
```text
TransactionExecutionEvent { slot, signature, outcome }
```
## 7. Validation anti-duplication Store
| Modèle Store stable | Action `0.3.5` | Justification |
|---------------------------------|---------------------|------------------------------------------------|
| ------------------------------- | ------------------- | ---------------------------------------------- |
| `RawTransaction` | inchangé | payload durable/replayable |
| `RawTransactionObservation` | inchangé | provenance persistante |
| `RawAccountState` | inchangé | état account durable |
@@ -139,7 +143,7 @@ ksp-interface-lib -X-> ksp-program-api
ksp-interface-lib -X-> serde/tracing/tokio/channel runtime additions
```
Le `cargo tree` ne peut pas être exécuté dans l'environnement d'assemblage actuel, où `cargo` est absent. Le gate opérateur est donc obligatoire sur l'overlay.
Le gate opérateur de `pre.001` confirme `cargo check --workspace`, Clippy et les tests `ksp-interface-lib`. Les graphes `cargo tree` restent réservés au gate technique final de la release.
## 9. Consumer concret retenu
@@ -157,22 +161,22 @@ Yellowstone gRPC -------------+
## 10. Threat gates
| Gate | Attendu `0.3.5` | Statut `pre.001` |
|----------------------------------|-----------------------------------------------|------------------|
| mega enum | absent | PLAN PASS |
| protocol/provider enum leakage | absent | PLAN PASS |
| timestamp semantics conflated | absent | PLAN PASS |
| root/finalized conflated | absent | PLAN PASS |
| optimistic/confirmed conflated | absent | PLAN PASS |
| dead diagnostic in shared API | absent | PLAN PASS |
| RAW Store duplication | absent | PLAN PASS |
| event persistence | absent | PLAN PASS |
| event bus/runtime | absent | PLAN PASS |
| network id duplicated from Store | absent | PLAN PASS |
| cross-network use | composition doit conserver son scope réseau | À CANARIER |
| public enum evolution | `SlotLifecycleStage` doit être non-exhaustive | À IMPLÉMENTER |
| Core-only graph | aucune dependency nouvelle | À REJOUER |
| external consumer | type consommable depuis crate externe | À IMPLÉMENTER |
| Gate | Attendu `0.3.5` | Statut `pre.001` |
| ------------------------------------ | ------------------------------------------------- | ---------------- |
| mega enum | absent | PLAN PASS |
| protocol/provider enum leakage | absent | PLAN PASS |
| timestamp semantics conflated | absent | PLAN PASS |
| root/finalized label confusion | évitée par le stage KSP `Rooted` | PLAN PASS |
| optimistic/confirmed label confusion | évitée par le stage KSP `OptimisticallyConfirmed` | PLAN PASS |
| dead diagnostic in shared API | absent | PLAN PASS |
| RAW Store duplication | absent | PLAN PASS |
| event persistence | absent | PLAN PASS |
| event bus/runtime | absent | PLAN PASS |
| network id duplicated from Store | absent | PLAN PASS |
| cross-network use | composition doit conserver son scope réseau | À CANARIER |
| public enum evolution | `SlotLifecycleStage` doit être non-exhaustive | À IMPLÉMENTER |
| Core-only graph | aucune dependency nouvelle | PASS opérateur |
| external consumer | type consommable depuis crate externe | À IMPLÉMENTER |
## 11. Fichiers de `pre.001`
@@ -192,20 +196,23 @@ Cargo.toml
Aucun autre fichier ne doit changer dans cet overlay.
## 12. Validations exécutées dans l'environnement d'assemblage
## 12. Validations statiques de l'overlay initial
Exécutables sans Cargo :
L'overlay `pre.001` avait exécuté les audits disponibles dans l'environnement d'assemblage :
```text
python3 scripts/audit_rust_workspace_rules.py
-> General Rust rule audit: clean
-> Rust export completeness audit: 0 candidate(s)
-> KSP workspace Rust rule audit: clean
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.5
-> Markdown table audit: clean (251 table(s), 137 file(s))
```
Le résultat réel est enregistré dans `deltas/0.3.5/pre.001.md` après exécution.
## 13. Gate opérateur `pre.001` reçu avant `fix.001`
## 13. Validations opérateur requises
À appliquer sur le repository `v0.3.4` après extraction de l'overlay :
L'opérateur a rejoué depuis un `cargo clean` :
```text
cargo fmt --all
@@ -216,19 +223,40 @@ cargo clippy --workspace --all-targets
cargo test -p ksp-interface-lib
```
Aucun `cargo test -p ksp-program-api` n'est requis par le contenu de `pre.001`, car aucun contrat public Interface n'est encore modifié. Il devient requis à partir de la première tranche qui change réellement la surface publique concernée.
Résultat : **PASS intégral**.
## 14. Exit gate `pre.001`
`pre.001` est prêt à livrer lorsque :
Preuves synthétiques :
```text
plan + validation + delta existent
workspace.package.version = 0.3.5-pre.1
une seule famille est admise : SlotLifecycle
stages admis = Processed / FirstShredReceived / Completed / CreatedBank / Dead
logs/status/vote/root/account/transaction/block/Entry/post-commit sont classés explicitement
aucun fichier Rust/Transport/Store n'est modifié
les audits statiques disponibles sont propres
les gates Cargo non exécutables sont explicitement laissés à l'opérateur
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
Markdown table audit: clean (251 table(s), 137 file(s))
cargo check --workspace -> PASS
cargo clippy --workspace --all-targets -> PASS
ksp-interface-lib unit tests -> 10 passed
ksp-interface-lib dependency_boundary -> 4 passed
ksp-interface-lib external_consumer -> 1 passed
ksp-interface-lib public_api -> 5 passed
ksp-interface-lib release_completeness -> 3 passed
doc-tests -> 0 failed
```
`pre.001-fix.001` est documentation-only ; il ne modifie ni Cargo ni Rust. L'opérateur doit néanmoins rejouer les deux audits Markdown/Rust après application du fix pour confirmer l'overlay final.
## 14. Exit gate `pre.001-fix.001`
Le gate corrigé impose désormais :
```text
workspace.package.version = 0.3.5-pre.1 inchangée
SlotLifecycle admis avec 7 stages
stages = Processed / FirstShredReceived / Completed / CreatedBank / Dead / OptimisticallyConfirmed / Rooted
Frozen reste hors intersection
TransactionExecutionEvent = candidat actif mais non encore admis
TransactionLogEvent = idée différée, distincte de l'exécution
getSignatureStatuses/signatureSubscribe = snapshot/commitment Transport, non fusionnés avec execution
Helius transactionSubscribe et Yellowstone Entry restent des DTOs Transport
un futur fait provider-neutral produit par une extension provider peut appartenir à Interface après gate
aucun fichier Rust/Transport/Store/Cargo n'est modifié par le fix
```