v0.3.1-pre.005

docs/plans/022-V0_3_1_STORE_RAW_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/022-V0_3_1_STORE_RAW_PLAN.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->
 
 # Plan `0.3.1` — Store API RAW foundation
 
@@ -803,7 +803,7 @@ La stratégie candidate est :
 ```text
 capabilities Send + Sync
 méthodes object-safe
-futures boxed KSP-owned via un alias StoreFuture<'a, T>
+futures boxed KSP-owned via un alias StoreApiFuture<'a, T>
 future ksp-store-lib::Store compose les capabilities disponibles
 ```
 
@@ -813,21 +813,36 @@ Cette stratégie évite une dépendance `async-trait` uniquement pour masquer la
 
 Éviter un trait monolithique exigeant tous les types de données à chaque backend.
 
-La candidate est une composition fine :
+`pre.005` matérialise une composition fine par famille et par direction :
 
 ```text
-StoreHealth
 RawTransactionRead
 RawTransactionWrite
 RawTransactionObservationRead
 RawTransactionObservationWrite
 
-future RawAccountStateRead
-future RawAccountStateWrite
-future TransactionStatus* si persistence réellement retenue
+RawAccountStateRead
+RawAccountStateWrite
+RawAccountObservationRead
+RawAccountObservationWrite
 ```
 
-Un modèle event-only ne crée aucune capability Store par défaut.
+Les capabilities d'écriture distinguent deux usages :
+
+```text
+persist_raw_*_acquisition(raw, observation)
+    = création/admission atomique du RAW + observation
+
+record_raw_*_observation(observation)
+    = acquisition supplémentaire d'un RAW déjà persistant
+    = ne retransmet pas le payload volumineux
+```
+
+Les traits sont `Send + Sync`, dyn-compatible et retournent `StoreApiFuture<'a, T>`, alias KSP basé uniquement sur `Pin<Box<dyn Future + Send>>`. Un backend externe peut donc les implémenter sans `async-trait`, `tokio`, `ksp-store-lib` ou crate backend officielle.
+
+`StoreHealth`, les listes/queries et les outcomes détaillés ne sont pas artificiellement introduits dans cette tranche. `pre.006` finalise les résultats d'écriture et le lifecycle logique avant fermeture de l'API.
+
+Un modèle event-only ne crée aucune capability Store par défaut. Aucun trait monolithique `StoreBackend` n'est introduit : un backend peut implémenter uniquement les familles réellement supportées.
 
 La future façade `ksp-store-lib::Store` peut exposer seulement les capabilities réellement compilées/supportées et produire une erreur stable lorsqu'une opération demandée n'est pas disponible.
 
@@ -835,22 +850,25 @@ La future façade `ksp-store-lib::Store` peut exposer seulement les capabilities
 
 Aucun handle de transaction SQL/public n'est exposé.
 
-Les invariants multi-écritures sont exprimés par des opérations logiques communes. Candidate initiale :
+La surface matérialisée par `pre.005` commence par les opérations unitaires nécessaires :
 
 ```text
-persist_transaction_acquisition(transaction, observation)
-record_transaction_observation(observation)
 get_raw_transaction(reference)
-list_raw_transactions(query, page)
-list_transaction_observations(query, page)
+persist_raw_transaction_acquisition(transaction, observation)
+get_raw_transaction_observation(observation_key)
+record_raw_transaction_observation(observation)
 
-future persist_account_acquisition(state, observation)
-future account reads/queries
-
-health()
+get_raw_account_state(reference)
+persist_raw_account_acquisition(state, observation)
+get_raw_account_observation(observation_key)
+record_raw_account_observation(observation)
 ```
 
-`persist_transaction_acquisition` signifie au contrat que le RAW et son observation réussissent atomiquement ou échouent ensemble. PostgreSQL réalisera cela avec une transaction privée en `0.3.2`; un autre backend utilisera son mécanisme natif.
+Les opérations `persist_raw_*_acquisition` signifient au contrat que le RAW et son observation réussissent atomiquement ou échouent ensemble. PostgreSQL réalisera cela avec une transaction privée en `0.3.2`; un autre backend utilisera son mécanisme natif.
+
+Les opérations `record_raw_*_observation` supposent que la référence RAW ciblée existe déjà et permettent de retenir une acquisition supplémentaire sans retransmettre la donnée RAW complète.
+
+Les listes, queries, backlog, health commun et outcomes détaillés restent à finaliser dans `pre.006`; aucune transaction backend publique n'est nécessaire pour les exprimer.
 
 ### 11.5 Outcomes
 
@@ -1375,7 +1393,7 @@ Audit HTTP/WS/gRPC matérialisé. `RawAccountState`/observation sont admis avec
 
 ### `pre.005` — Capabilities backend extensibles
 
-Implémenter les contracts read/write object-safe et l'external backend canary, sans façade runtime `Store` et sans runtime DB. Un modèle prévu n'oblige pas chaque backend à implémenter sa capability.
+Matérialiser les contracts read/write object-safe pour transaction/account et leurs observations, l'alias `StoreApiFuture`, ainsi qu'un canari backend externe. Les écritures d'acquisition imposent RAW + observation atomiques et les observations supplémentaires peuvent être enregistrées sans retransmettre le RAW. Aucune façade runtime `Store`, aucun trait monolithique backend et aucun runtime DB.
 
 ### `pre.006` — Queries, outcomes et lifecycle RAW