<!-- file: docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md -->
<!-- version: 1 -->

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

```text
v0.3.4
workspace.package.version = 0.3.4
```

Version de travail :

```text
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 :

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

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

La surface visée reste conceptuellement :

```text
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é :

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

Cible `0.3.5` :

```text
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 :

```text
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 :

```text
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é :

```text
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 :

```text
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 :

```text
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 :

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