<!-- file: deltas/0.2.8/pre.006.md -->
<!-- version: 1 -->

# Delta `0.2.8-pre.006` — Helius transactionNotification + lifecycle actor

## 1. Base et objet

Base appliquée :

```text
0.2.8-pre.5.fix.2
```

Le checkpoint opérateur de cette base est intégralement vert et sans warning : `cargo fmt`, audit Rust, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, tests Transport et `cargo test --workspace` passent. Transport compte alors `322` tests unitaires, `39` tests public API, `27` tests release-completeness et `4` doctests compile-fail.

Cette tranche transforme le contrat de requête Helius préparé en `pre.005` en une souscription live complète, sans créer de second moteur WebSocket :

```text
transactionSubscribe
  -> registry actor existant
  -> WsSubscription<HeliusTransactionNotification>
  -> transactionNotification
  -> reconnect/resubscribe/remap remote ID
  -> transactionUnsubscribe
```

## 2. Version technique

```text
workspace.package.version = 0.2.8-pre.6
commit attendu            = v0.2.8-pre.006
Git tag                    = aucun tag prerelease
```

Le header root `Cargo.toml` passe en version `226`.

## 3. Subscription kind provider

`WsSubscriptionKind` gagne :

```text
HeliusTransaction
```

avec le triplet exact :

```text
as_str              helius_transaction
subscribe_method     transactionSubscribe
unsubscribe_method   transactionUnsubscribe
notification_method  transactionNotification
```

Cette extension ne modifie pas la partition standard Solana de neuf familles et reste hors des trois familles standard classées unstable (`Block`, `SlotsUpdates`, `Vote`).

Le generic actor existant reste l'unique propriétaire :

- du socket physique ;
- du pending map JSON-RPC ;
- des local IDs ;
- des remote IDs ;
- du registry de subscriptions ;
- du reconnect/resubscribe ;
- des queues de notifications ;
- du cleanup unsubscribe ;
- du shutdown.

## 4. Handle live Helius

`HeliusLaserStreamWsSession` expose maintenant :

```rust
transaction_subscribe(
    &self,
    request: &HeliusTransactionSubscribeRequest,
) -> Result<WsSubscription<HeliusTransactionNotification>>
```

La validation déterministe et la sérialisation de `pre.005` restent exécutées avant l'enregistrement actor. Le helper de sérialisation et ses sous-helpers redeviennent du code de production uniquement parce qu'ils ont désormais un consommateur réel ; ils restent strictement privés au module.

Aucune visibilité n'est élargie pour les tests. Les canaris du sous-module accèdent aux helpers privés avec `super::Item`; les contrats publics sont consommés via `crate::Item`.

## 5. Notification typed

Trois formes publiques sont exposées au crate-root.

### 5.1 Full/accounts

`HeliusFullTransactionNotification` conserve :

```text
transaction       serde_json::Value
signature         String
slot              u64
transactionIndex  u64
```

Le nested `transaction` reste lossless en JSON, car sa forme dépend de `encoding` et `transactionDetails`; Transport ne décode pas les Programs.

### 5.2 Signatures

`HeliusTransactionSignatureNotification` conserve :

```text
signature           String
slot                u64
transactionIndex    u64
err                  Omitted | Null | Value(JSON)
memo                 Omitted | Null | Value(String)
blockTime            Omitted | Null | Value(i64)
confirmationStatus   Omitted | Null | Value(String)
```

Les champs optionnels réutilisent `SolanaWireField` afin de ne pas confondre omission et `null`.

### 5.3 Union publique

```text
HeliusTransactionNotification::Full(...)
HeliusTransactionNotification::Signature(...)
HeliusTransactionNotification::Unknown(JSON)
```

`Unknown` conserve uniquement le `params.result` provider. L'enveloppe JSON-RPC complète et `params.subscription` ne franchissent pas le boundary public. Cette forme couvre notamment un `transactionDetails=none` ou une évolution provider non encore typée sans tuer arbitrairement la logical subscription.

## 6. Reconnect, unsubscribe tardif et backpressure

Le support Helius s'appuie directement sur les garanties du moteur `0.2.7` :

- les params `transactionSubscribe` originaux sont conservés par le registry ;
- après reconnect, un nouvel ID remote remplace l'ancien ;
- le `WsSubscriptionId` local reste stable ;
- le remote ID n'est jamais public ;
- au début d'un unsubscribe, le mapping remote -> local est retiré avant l'émission de `transactionUnsubscribe` ;
- une notification provider déjà en vol après cancellation est donc ignorée ;
- un overflow de queue échoue seulement la logical subscription lente ;
- le cleanup best-effort utilise automatiquement `transactionUnsubscribe` grâce au nouveau `WsSubscriptionKind`.

Cette sémantique correspond au contrat Helius actuel qui précise que quelques messages en vol peuvent encore arriver brièvement après `transactionUnsubscribe`.

## 7. Canaris ajoutés/actualisés

Les tests Helius transaction couvrent maintenant :

```text
notification Full / Signature / Unknown
live transactionSubscribe exact via façade publique
transactionNotification routée vers WsSubscription
transactionUnsubscribe exact via handle public
reconnect : remote ID 41 -> 99
resubscribe : params identiques
stable local WsSubscriptionId
late transactionNotification après demande unsubscribe ignorée
overflow transaction : handle lent Failed + ERROR_CODE_WS_BACKPRESSURE_OVERFLOW
cleanup overflow : transactionUnsubscribe [remote_id]
Helius root sain reste Active et reçoit encore sa notification
```

Un canari lifecycle verrouille aussi le triplet exact du nouveau `WsSubscriptionKind::HeliusTransaction`.

Les public/release canaries gagnent :

- le symbole public `HeliusLaserStreamWsSession::transaction_subscribe` ;
- les trois types publics de notification ;
- la présence du kind provider ;
- l'absence de second `connect_async`/actor dans le module Helius ;
- la conservation des compile-fail Helius block/slotsUpdates/vote/escape-hatch.

Comptages attendus :

```text
Transport unit             325
Transport public API        40
release completeness        28
doctests compile-fail        4
```

## 8. Documentation

Le plan `015` :

- ferme `pre.005`, `fix.001` et `fix.002` après preuve opérateur sans warning ;
- marque `pre.006` PREPARED ;
- documente l'union notification, le remap remote/local et les nouveaux canaris lifecycle.

La validation `011` :

- enregistre le checkpoint final `pre.005` ;
- ouvre la gate `pre.006` ;
- conserve heartbeat, adversarial élargi et smoke live dans leurs tranches prévues.

## 9. Hors scope

Restent explicitement hors de `pre.006` :

```text
heartbeat / idle timer               pre.007
provider adversarial/security élargi pre.008
compliance finale                    pre.009
smoke Helius live opt-in             pre.010
LaserStream gRPC                     future transport séparé
```

Aucune nouvelle dépendance n'est ajoutée.

## 10. Fichiers modifiés

```text
Cargo.toml
crates/ksp-onchain-transport-lib/src/lib.rs
crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs
crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
crates/ksp-onchain-transport-lib/src/ws_subscription.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_helius_transactions.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_lifecycle.rs
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
deltas/0.2.8/pre.006.md
```

## 11. Gate opérateur

```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-onchain-transport-lib
cargo test --workspace
```

Critère de fermeture : aucune erreur, aucun warning nouveau, audit Rust clean et tous les nouveaux canaris lifecycle Helius verts.