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