khadhroony-solana-project/docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md

Validation 0.3.5 — Interface passive acquisition events

1. Portée

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 :

v0.3.4
workspace.package.version = 0.3.4

Version de travail :

0.3.5-pre.1

2. Gate d'entrée v0.3.4

Le log opérateur fourni avec l'archive indique un gate stable v0.3.4 propre : audits Rust/Markdown, cargo check, Clippy, tests ciblés des crates, cargo test --workspace, ksp-store-lib --no-default-features et graphes Store ont été exécutés sans échec visible ; les smokes réseau restent explicitement ignorés/opt-in.

Cette preuve est l'entrée de 0.3.5. Elle n'est pas réétiquetée comme validation exécutée dans l'environnement d'assemblage de pre.001.

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	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	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
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

Les modèles suivants sont explicitement non admis par le gate :

TransactionStatusObservation {
    confirmations?: ...,
    confirmation_status?: ...,
    received?: ...,
    is_vote?: ...,
    transaction_index?: ...,
    logs?: ...,
    ...
}

SlotLifecycleEvent {
    parent?: ...,
    root?: ...,
    timestamp?: ...,
    dead_error?: ...,
    provider?: ...,
    ...
}

La surface admise reste conceptuellement :

SlotLifecycleEvent { slot, stage }

Le candidat séparé, non encore admis, reste :

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
RawAccountObservation	inchangé	observation persistante
pagination/cursors RAW	inchangés	contrats de navigation Store
retention/tombstone transaction	inchangés	lifecycle de persistence Store
notification after commit	non implémentée ici	ownership Store API réservé par KSP-NOTIFY-*

Canari conceptuel : aucun futur fichier source Interface de 0.3.5 ne doit importer ksp_store_api, ksp_store_lib ou copier leurs modèles.

8. Validation dependency/ownership

État de l'archive stable inspecté :

crates/ksp-interface-lib/Cargo.toml
    runtime dependency = ksp-core-lib seulement

Cible 0.3.5 :

ksp-interface-lib -> ksp-core-lib
ksp-interface-lib -X-> ksp-onchain-transport-lib
ksp-interface-lib -X-> ksp-store-api
ksp-interface-lib -X-> ksp-store-lib
ksp-interface-lib -X-> ksp-program-api
ksp-interface-lib -X-> serde/tracing/tokio/channel runtime additions

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

Consumer proche documenté par l'architecture : futur worker RAW live / composition d'acquisition.

Usage possible sans dépendance protocol-specific :

Solana standard WS -----------+
                              +-> converter composition -> SlotLifecycleEvent -> réaction lifecycle du consumer
Yellowstone gRPC -------------+

0.3.6 backfill n'est pas forcé d'utiliser ce type ; il reste une composition historique Transport + Store.

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 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

Ajoutés :

docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md
docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md
deltas/0.3.5/pre.001.md

Modifié :

Cargo.toml

Aucun autre fichier ne doit changer dans cet overlay.

12. Validations statiques de l'overlay initial

L'overlay pre.001 avait exécuté les audits disponibles dans l'environnement d'assemblage :

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))

13. Gate opérateur pre.001 reçu avant fix.001

L'opérateur a rejoué depuis un cargo clean :

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.3.5
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-interface-lib

Résultat : PASS intégral.

Preuves synthétiques :

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 :

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