0.1.0

2026-07-23 16:37:12 +02:00
parent 99c345f2f2
commit 0da75c1311
2159 changed files with 230833 additions and 0 deletions
--- a/docs/RAW_STORAGE_LIFECYCLE.md
+++ b/docs/RAW_STORAGE_LIFECYCLE.md
@@ -0,0 +1,115 @@
+<!-- file: docs/RAW_STORAGE_LIFECYCLE.md -->
+<!-- version: 4 -->
+
+# Cycle de vie du stockage transactionnel Solana
+
+## Principe général
+
+Le stockage rejouable repose désormais sur une transaction Solana canonique unique par signature. Les formats d’origine JSON-RPC, WebSocket Helius ou Yellowstone Protobuf sont des formats de transport, pas des modèles de stockage métier.
+
+Le cycle est :
+
+```text
+acquisition
+  -> normalisation canonique
+    -> persistance raw canonique
+      -> extraction core
+        -> décodage
+          -> matérialisation
+            -> compaction / archivage / purge éventuelle
+```
+
+## Transaction canonique
+
+`kb_sol_raw_transactions` conserve suffisamment d’information pour :
+
+- auditer une transaction ;
+- reconstruire les tables `core` ;
+- rejouer de nouvelles versions de décodeurs ;
+- rejouer de nouvelles versions de matérialiseurs ;
+- comparer plusieurs sources sans dépendre de leur format.
+
+La ligne est unique par signature. `canonical_format_version` permet de faire évoluer le contrat sans ambiguïté.
+
+## Observations d’acquisition
+
+`kb_sol_obs_transaction_observations` conserve les preuves techniques d’acquisition :
+
+- fournisseur et endpoint ;
+- protocole et méthode ;
+- origine live/backfill/replay/réparation ;
+- commitment ;
+- session et filtre ;
+- timestamps de détection, réception, normalisation et persistance ;
+- taille du message ;
+- statut et erreur éventuelle.
+
+Cette table ne conserve pas le payload complet. Elle peut contenir plusieurs lignes pour une même signature.
+
+## Ancienne table WebSocket
+
+`kb_sol_raw_ws_notifications` est une table historique de `0.2.3`, supprimée pendant la transition validée `0.3.1`. Elle n’existe plus dans la baseline SQL active.
+
+Les nouvelles notifications WebSocket ne doivent pas être stockées intégralement par défaut. Une notification de logs peut rester temporairement dans une queue mémoire jusqu’à l’hydratation de la transaction.
+
+## États de rétention
+
+Les états de rétention de `kb_sol_raw_transactions` sont :
+
+```text
+full
+compacted
+archived
+purged
+```
+
+### `full`
+
+Le document canonique complet est présent dans PostgreSQL.
+
+### `compacted`
+
+Une représentation réduite ou un stockage externe permet encore l’audit minimal, mais le payload canonique complet n’est plus dans la ligne chaude.
+
+### `archived`
+
+Le payload a été déplacé vers un stockage d’archive durable.
+
+### `purged`
+
+Le payload n’est plus disponible. Le hash canonique, la signature, le slot et les données dérivées doivent rester suffisants pour les diagnostics autorisés.
+
+## États de traitement
+
+```text
+received
+core_extracted
+decoded
+materialized
+failed
+```
+
+L’état décrit la progression de la transaction canonique, pas celle de chaque observation de source.
+
+## Conditions avant compaction ou purge
+
+Aucune purge destructive ne doit être activée avant validation de :
+
+- l’extraction core idempotente ;
+- la couverture des décodeurs prioritaires ;
+- la reconstruction depuis archive ;
+- la stabilité du hash canonique ;
+- la conservation du ledger de traitement ;
+- la stratégie de sauvegarde PostgreSQL.
+
+## Payloads fournisseur de diagnostic
+
+Les payloads complets spécifiques à un fournisseur peuvent être exportés temporairement pour une session de test. Ils ne doivent pas devenir une dépendance du replay métier.
+
+Un export de diagnostic doit être :
+
+- opt-in ;
+- borné en durée et en taille ;
+- associé à une session ;
+- supprimable indépendamment de PostgreSQL.
+