v0.3.1-pre.001-fix-002

ROADMAP.md

@@ -80,34 +80,49 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U
 
 ## Architecture de données — progression canonique
 
-La chaîne durable cible est :
+La progression durable cible est :
 
 ```text
-RAW -> CORE -> DECODE -> SPECIALIZED
+RAW -> STRUCTURAL -> DECODED -> DOMAIN
 ```
 
-- **RAW** et **CORE** ne nécessitent aucun décodage Program.
-- À la fin de chaque couche horizontale RAW/CORE, ajouter les jobs/workers/apps nécessaires pour la rendre réellement exploitable avant d'ouvrir la couche suivante.
-- À partir de **DECODE**, avancer verticalement groupe par groupe : wire -> decode -> matérialisation -> projection spécialisée si utile -> préparation d'exécution -> policy -> execution -> scénarios Devnet.
+- **RAW** et **STRUCTURAL** ne nécessitent aucun décodage Program.
+- La progression n'est pas une chaîne obligatoire pour chaque famille : une donnée event-only peut s'arrêter en N1, et un état de compte pourra aller directement vers un futur decoder si aucune décomposition STRUCTURAL utile n'existe.
+- À la fin des couches horizontales RAW/STRUCTURAL réellement persistées, ajouter les jobs/workers/apps nécessaires avant d'ouvrir la couche suivante.
+- À partir de **DECODED**, avancer verticalement groupe par groupe ; **DOMAIN** désigne les projections métier et la matérialisation est le processus qui les produit.
 
 ## 0.3.x — RAW / acquisition persistée
 
-- [/] `0.3.1` — Introduire `ksp-store-api` uniquement avec le **modèle objet commun et les contrats N1 RAW/observations** : transactions et logs dans la première surface, provenance, identités, outcomes, queries/pagination et contrats backend, sans persistence concrète ni configuration backend.
+- [/] `0.3.1` — Introduire `ksp-store-api` uniquement avec le **modèle objet commun et les contrats N1 RAW/observations** : `RawTransaction` + observations en premier, inventaire/admission cross-source des futurs account/status models, séparation explicite des events realtime non persistés, lifecycle logique de rétention/tombstone, outcomes, queries/pagination et contrats backend, sans persistence concrète ni configuration backend.
 - [ ] `0.3.2` — Introduire ensemble `ksp-store-lib` et `ksp-store-postgres-lib` : façade/runtime Store commune, feature `postgres` activée par défaut, implémentation PostgreSQL de référence via `tokio-postgres`, Config `std.store`/secrets et migrations privées au backend. Un backend connu demandé par Config mais absent des features compilées est rejeté explicitement.
-- [ ] `0.3.3` — Étendre `ksp-interface-lib` avec les wires génériques nécessaires aux acquisitions et à la future normalisation de la couche suivant RAW.
+- [ ] `0.3.3` — Étendre `ksp-interface-lib` avec les modèles passifs/wires réellement partagés par acquisition/workers, notamment les events realtime non persistés retenus par l'audit `0.3.1`, sans dupliquer les modèles persistants de `ksp-store-api`.
 - [ ] `0.3.4` — Introduire `ksp-job-api` et un job de backfill historique concret consommant uniquement `ksp-store-lib` côté Store.
 - [ ] `0.3.5` — Introduire une application spécialisée de backfill/inspection RAW.
 - [ ] Compléter ensuite la couche RAW avec le worker/service live, son contrôle et les outils d'exploitation réellement nécessaires avant de passer à la couche de normalisation générique suivante.
 
-## Série CORE suivante
+### TODO/IDEAS — taxonomie N1, processing et rétention
 
-- [ ] Définir la persistence CORE canonique Solana générique.
-- [ ] Implémenter `RAW -> CORE` sans decoder Program : blocs, slots, signatures, transactions/messages, comptes, instructions/CPI brutes, logs/meta et relations structurelles.
-- [ ] Ajouter replay/backfill RAW -> CORE.
-- [ ] Ajouter worker/service CORE.
-- [ ] Ajouter l'application de contrôle/inspection CORE utile.
+- [ ] **TODO** — maintenir une matrice d'admission HTTP/WS/gRPC/provider pour chaque modèle N1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte.
+- [ ] **TODO** — `RawAccountState` + observation : auditer les shapes HTTP/WS/Yellowstone, conserver les bytes canoniques et documenter les limites de backfill historique avant de figer la capability de persistence.
+- [ ] **TODO** — `TransactionStatusObservation` : auditer `signatureSubscribe`, `getSignatureStatuses`, Yellowstone TransactionStatus et extensions provider ; distinguer persistence éventuelle et déclenchement d'event.
+- [ ] **TODO** — logs realtime : conserver `logMessages` dans `RawTransaction` jusqu'à la décomposition STRUCTURAL ; traiter `logsSubscribe` comme event-only candidat et décider son contrat passif dans `ksp-interface-lib`, sans table Store par défaut. Le format canonique d'un wake-up « donnée persistée disponible » reste distinct et appartient à `ksp-store-api` conformément à `KSP-NOTIFY-*`, tandis que sa publication appartient au worker/runtime.
+- [ ] **TODO** — slot/root/slotsUpdates et vote : ne créer un modèle passif commun que si un consumer realtime réel et une sémantique cross-ledger/provider justifient le contrat ; aucune persistence Store par défaut.
+- [ ] **IDEA** — `RawBlock` : ne rouvrir que si une information block-level non reconstructible devient nécessaire ; `getBlock` doit d'abord être traité comme source de `RawTransaction`, pas comme invitation à recopier le ledger en blocs.
+- [ ] **REJET ACTUEL** — Yellowstone `Entry` : trop bas niveau et aucune destination replay/decomposition/event métier justifiant un modèle KSP n'est identifiée.
+- [ ] **TODO** — processing ledger : reprendre l'idée kbot2/kbot3 `stage + processor identity/version + input identity/hash + terminal status`, sans faire d'un `processed: bool` la preuve durable unique ; prévoir force replay/version upgrades.
+- [ ] **TODO** — lifecycle RAW : prévoir `Full -> Compacted -> Archived -> Purged`, policy d'éligibilité hors Store, compression/archive backend futures et tombstone minimal empêchant un backfill normal après purge ; une réhydratation doit être explicitement forcée.
+- [ ] **TODO** — frontière `ksp-interface-lib` / `ksp-store-api` : documenter chaque type partagé afin que les events passifs non persistés vivent dans Interface et que les modèles persistants/replayables vivent dans Store API, sans doublons quasi équivalents.
+- [ ] **IDEA** — réauditer la structure de processing/decode/materialization historique kbot2/kbot3 lors de l'ouverture de N2/N3 ; conserver l'isolation instruction/CPI et les statuts terminal/versionnés, sans reprendre automatiquement le schéma SQL historique.
 
-## Séries DECODE/SPECIALIZED/EXECUTION — progression verticale
+## Série STRUCTURAL suivante
+
+- [ ] Définir la persistence STRUCTURAL canonique Solana générique pour les familles réellement décomposables.
+- [ ] Implémenter en priorité `RawTransaction -> STRUCTURAL` sans decoder Program : transaction/message, comptes/références, instructions top-level, CPI/inner instructions, logs/meta/balances/return data et relations structurelles.
+- [ ] Vérifier avant extension si d'autres familles N1 possèdent une vraie décomposition STRUCTURAL utile ; ne pas créer de niveau vide par convention.
+- [ ] Ajouter replay/backfill RAW -> STRUCTURAL avec processing versionné.
+- [ ] Ajouter worker/service STRUCTURAL et l'application de contrôle/inspection utile.
+
+## Séries DECODED/DOMAIN/EXECUTION — progression verticale
 
 ### Priorité 1 — Solana Core Programs
 
@@ -120,7 +135,7 @@ RAW -> CORE -> DECODE -> SPECIALIZED
 - [ ] SPL Token.
 - [ ] Associated Token Account.
 - [ ] Token-2022 et extensions pertinentes.
-- [ ] Pour chaque famille : decode -> materialize -> specialized -> prepare -> policy -> execute -> scenarios.
+- [ ] Pour chaque famille : decode -> materialize -> domain projection -> prepare -> policy -> execute -> scenarios.
 
 ### Priorité 3 — Metadata token
 
@@ -144,7 +159,7 @@ RAW -> CORE -> DECODE -> SPECIALIZED
 
 - [ ] Après les premiers groupes Meteora/Raydium/Pump/Orca, introduire une petite `ksp-app-market-desk` spécialisée.
 - [ ] Visualiser tokens, pools/markets, liquidité, swaps/trades, prix, volumes, OHLC/candles et activité live/récente lorsque disponible.
-- [ ] Lire les projections SPECIALIZED KSP ; ne pas reconstruire la logique protocolaire dans l'UI.
+- [ ] Lire les projections DOMAIN KSP ; ne pas reconstruire la logique protocolaire dans l'UI.
 
 ### Routing