khadhroony-solana-project/deltas/0.3.1/pre.004.md

<!-- file: deltas/0.3.1/pre.004.md -->
<!-- version: 1 -->

# Delta `0.3.1-pre.004` — admission cross-source + account state N1

## Base requise

```text
0.3.1-pre.3-fix.1
```

Le gate opérateur de `pre.003-fix.001` est fourni vert : `cargo fmt --all`, audits Rust/Markdown, `cargo check --workspace`, Clippy workspace et `cargo test -p ksp-store-api` passent.

## Objectif

Auditer les formes HTTP/WS/gRPC déjà possédées par `ksp-onchain-transport-lib` avant d'ajouter une nouvelle famille N1, puis matérialiser uniquement le modèle dont la sémantique commune est démontrée.

La tranche :

- admet `RawAccountState`/`RawAccountObservation` avec bytes complets + slot durable ;
- sépare les enrichissements Yellowstone de l'état canonique commun ;
- refuse conceptuellement les réponses account partielles/parsées comme états persistants ;
- diffère `TransactionStatusObservation` parce que snapshot HTTP, transition WS et update Yellowstone ne représentent pas encore le même fait ;
- ferme la classification logs/slot/vote/block/Entry sans créer de modèles Store prématurés.

## Version

Le workspace passe à :

```text
0.3.1-pre.4
```

## Audit account cross-source

Surfaces KSP relues :

```text
HTTP
  getAccountInfo
  getMultipleAccounts
  getProgramAccounts

WebSocket
  accountSubscribe
  programSubscribe
  Helius standard account/program reuse

Yellowstone gRPC
  Account / AccountInfo
```

Champs communs retenus pour un état complet :

```text
network
pubkey
slot
lamports
owner
executable
rent_epoch
complete account data bytes
canonical state hash
```

Règles d'admission :

```text
getAccountInfo/getMultipleAccounts
    -> admissibles avec account non-null + bytes complets

getProgramAccounts/programSubscribe
    -> slot/context obligatoire

accountSubscribe
    -> admissible avec bytes complets

Yellowstone Account
    -> admissible seulement sans accounts_data_slice tronquant les bytes

jsonParsed/dataSlice/bare program notification
    -X-> RawAccountState persistant
```

`space` n'est pas une vérité stockée séparément lorsque les bytes complets sont présents : `data.len()` est déterministe.

## Modèles ajoutés

```text
RawAccountStateReference
    network
    pubkey
    slot
    state_hash

RawAccountState
    reference
    lamports
    owner
    executable
    rent_epoch
    complete data bytes

RawAccountObservation
    observation_key
    account reference
    provenance
    optional write_version
    optional transaction_signature
    optional is_startup
```

La référence inclut `state_hash` parce que plusieurs écritures d'une account peuvent survenir dans le même slot alors que HTTP/WS standards ne possèdent pas le `write_version` Yellowstone. Plusieurs sources observant le même état complet peuvent donc converger sans faire de l'ordinal Yellowstone un identifiant commun.

Le calcul du digest reste producer/converter-owned. `ksp-store-api` n'ajoute aucun codec ni algorithme de hash.

## Borne account data

Nouvelle admission guard Store-owned :

```text
MAX_RAW_ACCOUNT_DATA_BYTES = 16 MiB
```

Les bytes vides restent valides pour une account vide. La borne n'est pas présentée comme une limite protocolaire Solana.

`RawAccountState` n'implémente pas `Clone` et son `Debug` ne rend jamais les bytes.

## Observation account

Les informations présentes uniquement sur certaines sources restent observation-only :

```text
Yellowstone write_version
Yellowstone transaction signature
Yellowstone is_startup
```

HTTP/WS utilisent le même `RawAccountObservation` sans inventer ces valeurs.

Provider/protocol/method/endpoint/commitment/timing restent dans `RawAcquisitionProvenance` conformément à `pre.003`.

## Transaction status différé

Surfaces auditées :

```text
getSignatureStatuses
    = snapshot interrogé avec confirmations/confirmationStatus

signatureSubscribe
    = event one-shot de réception/commitment demandé

Yellowstone TransactionStatus
    = update avec slot/signature/is_vote/index/error, sans commitment commun
```

La tranche n'introduit donc aucun `TransactionStatusObservation` générique rempli d'options. La future conception devra distinguer snapshot durable et event realtime et auditer l'ownership `ksp-interface-lib` des événements passifs.

## Classification fermée

```text
logsSubscribe
    -> event-only candidat ; pas de RawLog Store

transaction logMessages
    -> restent dans RawTransaction jusqu'à N2 STRUCTURAL

slot/root/slotsUpdates
    -> event-only candidat

vote
    -> event-only candidat après compatibilité utile

getBlock/Yellowstone Block
    -> conteneur d'acquisition RawTransaction ; RawBlock reste IDEA

Yellowstone Entry
    -> explicitement non retenu
```

Le Store runtime ne publie aucune notification ; workers/analyzers/runtime possèdent les futurs déclenchements.

## Tests ajoutés/mis à jour

Unitaires account :

- état complet et champs communs ;
- account data vide accepté ;
- account data oversized rejeté ;
- `Debug` sans bytes ;
- metadata Yellowstone optionnelle sur observation.

Canaris d'intégration :

- surface crate-root `RawAccountState*`/`RawAccountObservation` ;
- dépendance runtime toujours exactement Core-only ;
- absence de Transport/backend/runtime/codec ;
- absence de `TransactionStatusObservation`, `RawLogNotification`, `RawSlotEvent`, `RawVoteEvent`, `RawBlock` et `YellowstoneEntry` publics.

## Documentation mise à jour

```text
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
docs/validation/018-V0_3_1_STORE_RAW.md
```

La matrice cross-source est désormais explicite et `pre.004` ne prétend pas que toutes les réponses on-chain constituent des modèles Store.

## Validations exécutées dans l'environnement de génération

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

## Validations non exécutées dans l'environnement de génération

`cargo`, `rustc` et `rustfmt` ne sont pas installés dans l'environnement de génération. L'opérateur doit donc exécuter :

```text
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-store-api
```

Une commande non exécutée n'est pas déclarée PASS.

## Hors scope confirmé

```text
source converter HTTP/WS/gRPC concret
TransactionStatus model commun
logs/slot/vote event model
RawBlock persistence
Yellowstone Entry persistence
capabilities read/write
queries/outcomes
retention/tombstone concret
ksp-store-lib
ksp-store-postgres-lib
PostgreSQL/tokio-postgres
Config std.store
N2 STRUCTURAL
N3/N4
```

## Suite

`0.3.1-pre.005` introduit les capabilities backend extensibles et object-safe pour les modèles persistants réellement matérialisés, sans façade runtime `Store`, sans backend PostgreSQL et sans obliger un backend à supporter toutes les familles N1.