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

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

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

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

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?: ...,
    ...
}

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

La surface visée reste conceptuellement :

SlotLifecycleEvent { slot, stage }

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

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

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 exécutées dans l'environnement d'assemblage

Exécutables sans Cargo :

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

Le résultat réel est enregistré dans deltas/0.3.5/pre.001.md après exécution.

13. Validations opérateur requises

À appliquer sur le repository v0.3.4 après extraction de l'overlay :

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

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.

14. Exit gate pre.001

pre.001 est prêt à livrer lorsque :

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