Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.10-pre.008

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-08 06:43:02 +02:00
parent ab87fd23cd
commit 510adcb49b
21 changed files with 790 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/IDEAS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/IDEAS.md -->
<!-- version: 27 -->
<!-- version: 28 -->
# Idées à explorer
@@ -159,9 +159,9 @@ Conserver comme pistes séparées les offres pré-exécution/shred/deshred (Heli
**Status :** Retenue, granularité révisée
RAW et CORE peuvent disposer de workers dédiés à la fin de leur couche respective.
RAW et STRUCTURAL peuvent disposer de workers dédiés à la fin de leur couche respective.
À partir de DECODE, ne pas figer à l'avance une chaîne globale `generic-materializer -> domain-projector` pour tout Solana : la granularité des workers/processors doit émerger des vertical slices Program réels et réutiliser les mêmes transformations que les jobs de replay correspondants.
À partir de DECODED, ne pas figer à l'avance une chaîne globale `generic-materializer -> domain-projector` pour tout Solana : la granularité des workers/processors doit émerger des vertical slices Program réels et réutiliser les mêmes transformations que les jobs de replay correspondants.
### Worker control
@@ -322,7 +322,7 @@ Les futurs processing outcomes versionnés constituent la preuve durable de trai
**Status :** Requalifiée par `0.2.0-pre.003`
L'ancienne liste figée `ksp-job-replay-core` / `ksp-job-replay-generic-materialization` / `ksp-job-replay-domain-projection` n'est plus une décision KSP. La frontière `RAW -> CORE` pourra introduire un replay Core lorsque CORE sera ouverte. À partir de DECODE, les jobs de replay doivent émerger avec les groupes/capacités verticaux réels et réutiliser la même logique que le processing live correspondant, sans imposer un materializer/projector global à tout Solana.
L'ancienne liste figée `ksp-job-replay-core` / `ksp-job-replay-generic-materialization` / `ksp-job-replay-domain-projection` n'est plus une décision KSP. La frontière `RAW -> STRUCTURAL` pourra introduire un replay STRUCTURAL lorsque STRUCTURAL sera ouverte. À partir de DECODED, les jobs de replay doivent émerger avec les groupes/capacités verticaux réels et réutiliser la même logique que le processing live correspondant, sans imposer un materializer/projector global à tout Solana.
### Notification backend de référence
@@ -344,7 +344,7 @@ Définir le schéma SQL, la durée/renouvellement de lease et la technique Postg
Fixer les noms/types exacts et distinguer Produced, NoOutput, NotApplicable, Unsupported et failure déterministe sans transformer des situations normales en erreurs.
### Contexte stateful des projections SPECIALIZED
### Contexte stateful des projections DOMAIN
**Status :** À explorer avec la première projection nécessitant un état existant
@@ -426,4 +426,4 @@ Si cette capacité devient utile, l’intégration doit être conçue dans la pi
`0.2.0-pre.002` avait fixé le premier séquencement concret. `0.2.1-pre.001-fix.001` le recalibre désormais sur `0.2.1 -> 0.2.13`, sous réserve du gate de dimensionnement de chaque `pre.001` et avec possibilité d'enchaîner plusieurs releases complètement clôturées dans une même session lorsque le sizing le permet.
Les séries après RAW/CORE ne sont volontairement pas numérotées programme par programme à ce stade : la règle est de redécouper chaque vertical slice selon sa taille réelle et de ne jamais ouvrir une release qui ne peut pas être clôturée dans sa session.
Les séries après RAW/STRUCTURAL ne sont volontairement pas numérotées programme par programme à ce stade : la règle est de redécouper chaque vertical slice selon sa taille réelle et de ne jamais ouvrir une release qui ne peut pas être clôturée dans sa session.

28
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Couches et dépendances KSP
@@ -26,7 +26,7 @@ Les niveaux architecturaux N1–N4 décrivent les familles de composants du proj
### N3 — Données, jobs, workers et processing
- `ksp-store-api` / `ksp-store-lib` ;
- `ksp-materializer-api` / implementations lorsque DECODE s'ouvre ;
- `ksp-materializer-api` / implementations lorsque DECODED s'ouvre ;
- `ksp-job-api`, `ksp-job-backfill-lib` puis les jobs concrets introduits par les couches ;
- `ksp-worker-api` et workers ;
- processors/pipelines spécialisés réellement réutilisés.
@@ -45,32 +45,32 @@ La chaîne de données canonique est :
```text
D1 RAW
-> D2 CORE
-> D3 DECODE
-> D4 SPECIALIZED
-> D2 STRUCTURAL
-> D3 DECODED
-> D4 DOMAIN
```
Aliases fonctionnels :
```text
RAW -> CORE -> DECODE -> SPECIALIZED
RAW -> STRUCTURAL -> DECODED -> DOMAIN
```
RAW et CORE sont indépendants du décodage Program.
RAW et STRUCTURAL sont indépendants du décodage Program.
CORE est une normalisation générique de Solana : structure des blocs, transactions, messages, comptes, instructions/CPI brutes, logs/meta et relations fondamentales.
STRUCTURAL est une normalisation générique de Solana : structure des blocs, transactions, messages, comptes, instructions/CPI brutes, logs/meta et relations fondamentales.
Le premier decoder Program intervient seulement à `CORE -> DECODE`.
Le premier decoder Program intervient seulement à `STRUCTURAL -> DECODED`.
## Progression par couche
### RAW et CORE
### RAW et STRUCTURAL
Ces deux couches sont construites horizontalement.
À la fin de chaque couche, KSP ajoute les composants d'exploitation nécessaires : persistence, replay/backfill, worker/service et application de contrôle lorsque utiles.
### DECODE et SPECIALIZED
### DECODED et DOMAIN
À partir du décodage, KSP progresse verticalement par groupe fonctionnel :
@@ -134,7 +134,7 @@ Les applications Tauri restent minces :
- instrumentation frontend ;
- aucun déplacement de logique de transport, Wallet, Config, Program, Store ou Materializer dans Tauri.
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, `ksp-app-backfill-desk`, `ksp-app-store-desk`, CORE tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites. `ksp-app-backfill-desk` compose Config, Transport HTTP, Store et `ksp-job-backfill-lib` sans absorber découverte, retry/rate-limit, persistance ou checkpoint ; son frontend ne reçoit que des DTOs sûrs et le checkpoint de reprise reste Rust-only. `ksp-app-store-desk` compose Config, Logging et `ksp-store-lib` pour une inspection RAW read-only : il n'accède ni au backend physique ni au SQL et sépare la pagination random-access de l'interface de la pagination cursor/keyset réservée aux consumers machine.
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, `ksp-app-backfill-desk`, `ksp-app-store-desk`, STRUCTURAL tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites. `ksp-app-backfill-desk` compose Config, Transport HTTP, Store et `ksp-job-backfill-lib` sans absorber découverte, retry/rate-limit, persistance ou checkpoint ; son frontend ne reçoit que des DTOs sûrs et le checkpoint de reprise reste Rust-only. `ksp-app-store-desk` compose Config, Logging et `ksp-store-lib` pour une inspection RAW read-only : il n'accède ni au backend physique ni au SQL et sépare la pagination random-access de l'interface de la pagination cursor/keyset réservée aux consumers machine.
## Workers et jobs
@@ -171,7 +171,7 @@ ksp-execution-policy-api
## Groupes Program prioritaires
Après RAW/CORE :
Après RAW/STRUCTURAL :
```text
Solana Core Programs
@@ -198,4 +198,4 @@ Un satellite nécessaire à un protocole reste dans son groupe : Pump fee avec P
- split éventuel d'une API Interface séparée uniquement si un vrai besoin apparaît ;
- contrats Rust exacts de Program/Materializer/Store ;
- mécanisme IPC du premier manager de worker autonome ;
- granularité future des workers DECODE/SPECIALIZED par groupe.
- granularité future des workers DECODED/DOMAIN par groupe.

26
docs/architecture/003-COMPONENT_CONTRACTS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
<!-- version: 15 -->
<!-- version: 16 -->
# Contrats initiaux des composants KSP
@@ -137,24 +137,24 @@ La chaîne durable est :
```text
D1 RAW
-> D2 CORE
-> D3 DECODE
-> D4 SPECIALIZED
-> D2 STRUCTURAL
-> D3 DECODED
-> D4 DOMAIN
```
### RAW
Acquisition replayable + provenance, sans décodage Program.
### CORE
### STRUCTURAL
Normalisation générique Solana, sans décodage Program.
### DECODE
### DECODED
Interprétation Program/protocole puis matérialisation générique/journal durable.
### SPECIALIZED
### DOMAIN
Projections queryables de domaine : token, metadata, pools, trades, OHLC, routes, etc.
@@ -166,7 +166,7 @@ La première Store release est RAW-only ; les couches suivantes sont ajoutées q
## Materializer
`ksp-materializer-api`/`ksp-materializer-lib` sont introduits avec le premier besoin DECODE réel, pas avant.
`ksp-materializer-api`/`ksp-materializer-lib` sont introduits avec le premier besoin DECODED réel, pas avant.
Program et Materializer restent indépendants du backend Store ; les composants de composition convertissent leurs outputs vers les DTO persistants.
@@ -174,9 +174,9 @@ Program et Materializer restent indépendants du backend Store ; les composants
`ksp-worker-api` est la lifecycle API des services continus.
RAW et CORE peuvent recevoir leurs workers à la fin de leur couche respective.
RAW et STRUCTURAL peuvent recevoir leurs workers à la fin de leur couche respective.
Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program réels, afin de ne pas créer une orchestration générique vide avant les processors.
Les workers DECODED/DOMAIN sont introduits avec les groupes Program réels, afin de ne pas créer une orchestration générique vide avant les processors.
## Jobs
@@ -184,7 +184,7 @@ Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program réels,
Le premier job concret est `ksp-job-backfill-lib`. Il couvre un backfill historique `RawTransaction` : quatre scopes bornés, découverte/hydratation Transport observée, conversion RAW v1, persistance atomique par `ksp-store-lib`, concurrence bornée, frontier/checkpoint contigus caller-owned, annulation coopérative et snapshots complets sûrs. Il ne dépend ni de Config, ni d'un backend Store concret, ni d'un Worker.
Les jobs de replay suivants pourront suivre les frontières durables ouvertes : RAW -> CORE, CORE -> DECODE, DECODE -> SPECIALIZED. Ils ne sont pas forcés d'adopter le contrat métier du backfill RAW ; seuls les contrats vraiment communs appartiennent à `ksp-job-api`.
Les jobs de replay suivants pourront suivre les frontières durables ouvertes : RAW -> STRUCTURAL, STRUCTURAL -> DECODED, DECODED -> DOMAIN. Ils ne sont pas forcés d'adopter le contrat métier du backfill RAW ; seuls les contrats vraiment communs appartiennent à `ksp-job-api`.
Aucune `ksp-job-control-lib` n'est créée sans duplication concrète.
@@ -206,7 +206,7 @@ ksp-app-wallet-desk
ksp-app-solprices-desk
ksp-app-backfill-desk
ksp-app-store-desk
CORE tooling
STRUCTURAL tooling
ksp-app-market-desk
```
@@ -218,7 +218,7 @@ Une application globale reste future.
## Progression verticale Program
À partir de DECODE :
À partir de DECODED :
```text
wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario

26
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 36 -->
<!-- version: 37 -->
# Inventaire initial des composants KSP
@@ -48,10 +48,10 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
| Worker lifecycle | `ksp-worker-api` | API | Retenu | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Retenu | `0.3.11`–`0.3.14` | ingestion continue `RawTransaction` multi-source, déduplication/provenance/recovery |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Retenu | `0.3.15` | choix/supervision d’une ou plusieurs sources/méthodes sans réimplémenter le worker |
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE bornée/rejouable |
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche CORE | backlog RAW -> CORE continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes |
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche STRUCTURAL | normalisation Solana générique RAW -> STRUCTURAL bornée/rejouable |
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche STRUCTURAL | backlog RAW -> STRUCTURAL continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODED | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODED | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
@@ -107,19 +107,19 @@ Import/export reste extensible ; les formats supplémentaires sont suivis dans `
## Data plane
```text
RAW -> CORE -> DECODE -> SPECIALIZED
RAW -> STRUCTURAL -> DECODED -> DOMAIN
```
- RAW : acquisition replayable ;
- CORE : normalisation blockchain générique sans decoder Program ;
- DECODE : interpretation Program + matérialisation générique/journal ;
- SPECIALIZED : projections queryables de domaine.
- STRUCTURAL : normalisation blockchain générique sans decoder Program ;
- DECODED : interpretation Program + matérialisation générique/journal ;
- DOMAIN : projections queryables de domaine.
## Progression structurelle
RAW et CORE sont complétés couche par couche avec jobs/workers/apps utiles.
RAW et STRUCTURAL sont complétés couche par couche avec jobs/workers/apps utiles.
À partir de DECODE, progression verticale par groupe :
À partir de DECODED, progression verticale par groupe :
```text
wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario
@@ -154,6 +154,6 @@ Market Desk est progressive : V1 après les DEX prioritaires, puis enrichissemen
## Questions restantes
- nécessité future d'un pool automatique WS ;
- types exacts `ksp-materializer-api` lors de l'ouverture DECODE ;
- types exacts `ksp-materializer-api` lors de l'ouverture DECODED ;
- nom/packaging précis des futurs STRUCTURAL job et STRUCTURAL worker ;
- granularité des workers DECODE/SPECIALIZED par groupe.
- granularité des workers DECODED/DOMAIN par groupe.

40
docs/architecture/005-DEPENDENCY_GRAPH.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 25 -->
<!-- version: 26 -->
# Graphe de dépendances KSP
@@ -244,9 +244,9 @@ Une petite policy spécifique peut vivre dans une crate scenario/orchestrateur.
```text
D1 RAW
-> D2 CORE
-> D3 DECODE
-> D4 SPECIALIZED
-> D2 STRUCTURAL
-> D3 DECODED
-> D4 DOMAIN
```
### RAW
@@ -292,7 +292,7 @@ ksp-store-lib
Le Job Backfill et le Worker RAW peuvent donc partager exactement la canonicalisation et le wire sans que la common crate possède le runtime, le Transport ou le backend.
### CORE
### STRUCTURAL
```text
D1 RAW
@@ -301,23 +301,23 @@ D1 RAW
Solana generic normalizer
|
v
D2 CORE
D2 STRUCTURAL
```
Le normalizer CORE peut utiliser `ksp-interface-lib` pour des wires Solana génériques.
Le normalizer STRUCTURAL peut utiliser `ksp-interface-lib` pour des wires Solana génériques.
Interdictions :
```text
RAW -> CORE -X-> ksp-program-api
RAW -> CORE -X-> ksp-program-lib
RAW -> CORE -X-> ksp-materializer-api
RAW -> STRUCTURAL -X-> ksp-program-api
RAW -> STRUCTURAL -X-> ksp-program-lib
RAW -> STRUCTURAL -X-> ksp-materializer-api
```
### DECODE
### DECODED
```text
D2 CORE
D2 STRUCTURAL
|
v
ksp-program-api implementation
@@ -329,19 +329,19 @@ decoded facts
ksp-materializer-api implementation
|
v
D3 DECODE / generic journal
D3 DECODED / generic journal
```
### SPECIALIZED
### DOMAIN
```text
D3 DECODE
D3 DECODED
|
v
specialized projector/materializer
|
v
D4 SPECIALIZED
D4 DOMAIN
```
## Materialization
@@ -386,7 +386,7 @@ ksp-store-postgres-lib -X-> ksp-store-lib
worker/job -X-> ksp-store-postgres-lib
```
La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches. Les consumers runtime ordinaires (jobs, workers, apps) utilisent `ksp-store-lib`; ils ne sélectionnent ni n'importent directement `ksp-store-postgres-lib` ou un autre backend.
La première release Store (`0.3.1`) est RAW-only ; les contrats STRUCTURAL/DECODED/DOMAIN sont ajoutés avec leurs couches. Les consumers runtime ordinaires (jobs, workers, apps) utilisent `ksp-store-lib`; ils ne sélectionnent ni n'importent directement `ksp-store-postgres-lib` ou un autre backend.
## Jobs
@@ -436,7 +436,7 @@ ksp-worker-control-lib
Le worker RAW Transaction n'est pas défini comme « un worker WebSocket » ou « un worker gRPC ». Il reçoit une ou plusieurs stratégies d'acquisition construites au-dessus des façades KSP réellement disponibles ; celles-ci peuvent être alternatives, complémentaires (discovery + hydration), redondantes entre providers ou spécialisées live/catch-up/gap-repair. La transaction canonique reste identifiée indépendamment de la source et chaque acquisition utile conserve sa propre observation/provenance Store.
RAW worker puis STRUCTURAL worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Le traitement RAW -> CORE borné est porté par un STRUCTURAL job distinct du service continu. Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
RAW worker puis STRUCTURAL worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Le traitement RAW -> STRUCTURAL borné est porté par un STRUCTURAL job distinct du service continu. Les workers DECODED/DOMAIN sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
## Apps
@@ -515,7 +515,7 @@ ksp-app-market-desk
-> KSP domain/query contracts
```
Elle consomme les projections SPECIALIZED normalisées ; elle ne dépend pas directement des bibliothèques protocole externes.
Elle consomme les projections DOMAIN normalisées ; elle ne dépend pas directement des bibliothèques protocole externes.
## Scenarios
@@ -536,7 +536,7 @@ L'app demo correspondante reste un adapter UI mince.
## Progression verticale Program
À partir de DECODE :
À partir de DECODED :
```text
wire

4
docs/architecture/006-WIRE_AND_PROGRAM.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/006-WIRE_AND_PROGRAM.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Wire, Program API et implémentations Program
@@ -442,7 +442,7 @@ Une crate externe provoquant volontairement une génération incompatible de dé
## Progression verticale par groupe
Après les couches RAW/CORE, les Program implementations ne sont pas développées horizontalement comme une longue liste de decoders isolés. Chaque groupe prioritaire avance successivement :
Après les couches RAW/STRUCTURAL, les Program implementations ne sont pas développées horizontalement comme une longue liste de decoders isolés. Chaque groupe prioritaire avance successivement :
```text
wire -> decode -> materialize -> specialized -> execution preparation -> policy -> execution -> scenario

82
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md -->
<!-- version: 6 -->
<!-- version: 7 -->
# Data, Materialization et Store
@@ -10,19 +10,21 @@ Ce document définit la chaîne durable KSP, la responsabilité du Store et les
La nomenclature canonique est désormais :
```text
RAW -> CORE -> DECODE -> SPECIALIZED
RAW -> STRUCTURAL -> DECODED -> DOMAIN
```
Les aliases D1–D4 restent utilisés pour les niveaux persistés :
```text
D1 = RAW
D2 = CORE
D3 = DECODE / matérialisation générique décodée
D4 = SPECIALIZED
D2 = STRUCTURAL
D3 = DECODED / matérialisation générique décodée
D4 = DOMAIN
```
Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait déjà dépendre de `ksp-program-api`. **RAW et CORE sont indépendants de tout decoder Program.**
Le nom de couche historique `CORE` est abandonné pour D2 parce qu'il confondait la fondation commune `ksp-core-lib` avec une opération de décomposition structurelle du Store. `Core` reste inchangé lorsqu'il désigne la crate fondamentale ou un nom propre comme « Solana Core Programs ».
Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait déjà dépendre de `ksp-program-api`. **RAW et STRUCTURAL sont indépendants de tout decoder Program.**
## Principes structurants
@@ -36,7 +38,7 @@ Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait dé
### Mission
RAW conserve l'acquisition suffisamment fidèlement pour reconstruire CORE sans redemander la donnée au provider lorsqu'elle a déjà été capturée.
RAW conserve l'acquisition suffisamment fidèlement pour reconstruire STRUCTURAL sans redemander la donnée au provider lorsqu'elle a déjà été capturée.
Le transport peut normaliser plusieurs providers vers un modèle KSP homogène, mais D1 doit rester lossless pour les besoins de replay couverts.
@@ -77,15 +79,15 @@ Selon la catégorie, D1 doit pouvoir conserver notamment :
- identité/hash d'idempotence ;
- cursor/page/range/checkpoint lorsque pertinent.
## D2 — CORE
## D2 — STRUCTURAL
### Mission
CORE est une **normalisation canonique générique de la blockchain Solana**.
STRUCTURAL est une **normalisation canonique générique de la blockchain Solana**.
Cette couche doit fonctionner même si `ksp-program-api` et `ksp-program-lib` ne sont pas encore capables de décoder le moindre programme métier.
Exemples de faits CORE candidats :
Exemples de faits STRUCTURAL candidats :
- slots ;
- blocks et block metadata ;
@@ -102,9 +104,9 @@ Exemples de faits CORE candidats :
- return data brute ;
- relations structurelles transaction/message/instruction/account.
Un fait CORE peut contenir un `program_id`, des bytes et des indexes sans savoir que l'instruction représente un `Transfer`, un `Swap` ou une mutation Metadata.
Un fait STRUCTURAL peut contenir un `program_id`, des bytes et des indexes sans savoir que l'instruction représente un `Transfer`, un `Swap` ou une mutation Metadata.
### Frontière RAW -> CORE
### Frontière RAW -> STRUCTURAL
```text
D1 RAW
@@ -113,39 +115,39 @@ D1 RAW
normalisation Solana générique
|
v
D2 CORE
D2 STRUCTURAL
```
Interdictions :
```text
RAW -> CORE -X-> ksp-program-api
RAW -> CORE -X-> ksp-program-lib
RAW -> CORE -X-> ksp-materializer-api
RAW -> STRUCTURAL -X-> ksp-program-api
RAW -> STRUCTURAL -X-> ksp-program-lib
RAW -> STRUCTURAL -X-> ksp-materializer-api
```
Les codecs/wires génériques nécessaires à la structure Solana peuvent provenir de `ksp-interface-lib` lorsqu'ils appartiennent à la façade wire officielle, sans transformer cette étape en décodage Program.
### Provenance CORE
### Provenance STRUCTURAL
D2 doit pouvoir relier chaque résultat à :
- son input D1 ;
- l'identité/version du normalizer CORE ;
- l'identité/version du normalizer STRUCTURAL ;
- un hash logique d'input ;
- l'instant de processing/persistence ;
- son état de processing durable lorsque nécessaire.
## D3 — DECODE / matérialisation générique
## D3 — DECODED / matérialisation générique
### Mission
DECODE commence lorsque KSP interprète un `program_id`, un layout d'instruction, un compte ou un événement selon un contrat Program/protocole.
DECODED commence lorsque KSP interprète un `program_id`, un layout d'instruction, un compte ou un événement selon un contrat Program/protocole.
La progression logique d'un groupe est :
```text
CORE
STRUCTURAL
|
v
decoder Program
@@ -157,7 +159,7 @@ decoded facts
materialisation générique / journal durable
|
v
D3 DECODE
D3 DECODED
```
D3 conserve l'équivalent conceptuel obligatoire du journal générique de matérialisation de bot3 (`k_sol_mat_outputs`), sans imposer son ancien schéma ou son nom physique.
@@ -165,7 +167,7 @@ D3 conserve l'équivalent conceptuel obligatoire du journal générique de maté
Le journal doit pouvoir répondre au minimum :
```text
quel input CORE ?
quel input STRUCTURAL ?
quel program/decoder ?
quelle version ?
quel materializer ?
@@ -179,10 +181,10 @@ quel état/superseded/failed/replay ?
Les types exacts de decoded facts et du journal sont décidés lorsque les premiers vertical slices Program existent.
### Frontière CORE -> DECODE
### Frontière STRUCTURAL -> DECODED
```text
D2 CORE
D2 STRUCTURAL
|
v
ksp-program-api implementation
@@ -201,11 +203,11 @@ Les implémentations officielles pourront provenir de `ksp-program-lib` et `ksp-
Program et Materializer ne dépendent pas du backend Store.
## D4 — SPECIALIZED
## D4 — DOMAIN
### Mission
SPECIALIZED expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
DOMAIN expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
Exemples :
@@ -258,15 +260,15 @@ La direction reste :
### OHLC
Les candles sont des projections SPECIALIZED calculées à partir des trades/price observations persistés.
Les candles sont des projections DOMAIN calculées à partir des trades/price observations persistés.
Une application marché lit les OHLC matérialisés ; elle ne reparcourt pas toutes les transactions pour reconstruire les candles à chaque affichage.
## Vertical slices Program
RAW et CORE sont développés horizontalement.
RAW et STRUCTURAL sont développés horizontalement.
À partir de DECODE, la progression est verticale par groupe :
À partir de DECODED, la progression est verticale par groupe :
```text
wire
@@ -289,7 +291,7 @@ Les composants satellites nécessaires à un protocole appartiennent à son grou
La première implementation `0.3.1` est volontairement **RAW-only** : elle ne crée pas prématurément les contrats physiques D2/D3/D4.
Les surfaces CORE/DECODE/SPECIALIZED sont ajoutées quand leurs couches sont réellement ouvertes.
Les surfaces STRUCTURAL/DECODED/DOMAIN sont ajoutées quand leurs couches sont réellement ouvertes.
## `ksp-store-lib` et backends physiques
@@ -342,7 +344,7 @@ La voie `RawInspectionPageRequest` est backend-neutral mais conçue pour une ins
## `ksp-materializer-api` et `ksp-materializer-lib`
Ils sont introduits seulement lorsque le premier groupe DECODE démontre le contrat réel.
Ils sont introduits seulement lorsque le premier groupe DECODED démontre le contrat réel.
`ksp-materializer-api` porte les contrats extensibles ; `ksp-materializer-lib` contient les implementations officielles communes.
@@ -353,9 +355,9 @@ Une projection très locale/spécifique peut rester dans son groupe si la créat
Les frontières durables restent replayables indépendamment :
```text
RAW -> CORE
CORE -> DECODE
DECODE -> SPECIALIZED
RAW -> STRUCTURAL
STRUCTURAL -> DECODED
DECODED -> DOMAIN
```
Un replay d'une couche dérivée ne doit pas refaire arbitrairement les couches précédentes.
@@ -393,16 +395,16 @@ Ils ne dupliquent pas le contrat durable.
La stabilité cible est différente selon la couche :
- RAW : fortement stable après mise en production ;
- CORE : fortement stable après validation de la normalisation Solana générique ;
- DECODE : extensible par nouveaux Program/versions ;
- SPECIALIZED : plus évolutif selon les besoins de query, trading et analytics.
- STRUCTURAL : fortement stable après validation de la normalisation Solana générique ;
- DECODED : extensible par nouveaux Program/versions ;
- DOMAIN : plus évolutif selon les besoins de query, trading et analytics.
## Questions laissées ouvertes
- schémas SQL exacts RAW puis CORE ;
- schémas SQL exacts RAW puis STRUCTURAL ;
- représentation persistable exacte d'un decoded output ;
- contrat exact du journal D3 ;
- granularité des projectors SPECIALIZED ;
- granularité des projectors DOMAIN ;
- politique de supersession/versioning des outputs ;
- fenêtres OHLC initiales ;
- mécanisme de contexte pour les projections stateful.

44
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 16 -->
<!-- version: 17 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -8,7 +8,7 @@
Ce document définit le lifecycle opérationnel autour des couches :
```text
RAW -> CORE -> DECODE -> SPECIALIZED
RAW -> STRUCTURAL -> DECODED -> DOMAIN
```
Il conserve la séparation stricte entre :
@@ -20,7 +20,7 @@ Il conserve la séparation stricte entre :
## Règle de progression
RAW et CORE sont les deux premières couches horizontales. Elles ne nécessitent aucun decoder Program.
RAW et STRUCTURAL sont les deux premières couches horizontales. Elles ne nécessitent aucun decoder Program.
Pour chacune, KSP peut terminer successivement :
@@ -31,7 +31,7 @@ persistence
-> application de contrôle/inspection si utile
```
À partir de DECODE, les processors/jobs/workers/scenarios sont introduits **avec le groupe Program concerné**, en vertical slice, au lieu de créer à l'avance une grande flotte générique de workers de décodage/materialisation sans programme réel.
À partir de DECODED, les processors/jobs/workers/scenarios sont introduits **avec le groupe Program concerné**, en vertical slice, au lieu de créer à l'avance une grande flotte générique de workers de décodage/materialisation sans programme réel.
## RAW
@@ -86,7 +86,7 @@ Le job :
- limite les hydrations concurrentes, avance seulement une frontier contiguë durable et retourne un checkpoint opaque caller-owned ;
- arrête coopérativement les nouvelles admissions lors d'une annulation et draine une persistence Store déjà soumise ;
- publie des snapshots latest-value sûrs sans payload RAW ni secrets/URLs Transport ;
- n'effectue aucun décodage Program et n'écrit aucun fait CORE/DECODE/SPECIALIZED.
- n'effectue aucun décodage Program et n'écrit aucun fait STRUCTURAL/DECODED/DOMAIN.
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
@@ -204,7 +204,7 @@ L'archive kbot3 doit être relue uniquement comme **référence fonctionnelle**
L'audit `0.3.9` a conclu que `mainnet` est l'identité logique canonique KSP du réseau de production Solana. `mainnet-beta` reste un alias legacy/externe ou un libellé provider lorsqu'une API externe l'emploie réellement ; il ne constitue plus l'identité persistée cible de Store/RAW/Config.
Depuis `0.3.9-pre.006-fix.003`, les profils Mainnet engagés dans Config/Store/Transport utilisent `mainnet`, de même que les tests et exemples runtime associés. KSP ne crée donc pas deux identités persistées pour le même cluster. Les anciennes données N1 RAW portant `mainnet-beta` sont considérées comme expérimentales et peuvent être droppées/recréées ; aucune migration destructive n'est imposée avant finalisation des Jobs/Workers RAW.
Depuis `0.3.9-pre.006-fix.003`, les profils Mainnet engagés dans Config/Store/Transport utilisent `mainnet`, de même que les tests et exemples runtime associés. KSP ne crée donc pas deux identités persistées pour le même cluster. Les anciennes données D1 RAW portant `mainnet-beta` sont considérées comme expérimentales et peuvent être droppées/recréées ; aucune migration destructive n'est imposée avant finalisation des Jobs/Workers RAW.
Les frontières externes restent libres de documenter ou d'accepter un nom provider legacy lorsque nécessaire, sans recopier ce nom dans `RawNetworkId` canonique.
@@ -237,11 +237,11 @@ une stratégie live + gap repair
Le détail des RAW persistés reste la responsabilité de Store Desk.
## CORE
## STRUCTURAL
### Pipeline RAW -> CORE
### Pipeline RAW -> STRUCTURAL
La normalisation CORE est générique Solana :
La normalisation STRUCTURAL est générique Solana :
```text
D1 RAW
@@ -250,15 +250,15 @@ D1 RAW
Solana generic normalizer
|
v
D2 CORE
D2 STRUCTURAL
```
Dépendances interdites :
```text
CORE normalizer -X-> ksp-program-api
CORE normalizer -X-> ksp-program-lib
CORE normalizer -X-> ksp-materializer-api
STRUCTURAL normalizer -X-> ksp-program-api
STRUCTURAL normalizer -X-> ksp-program-lib
STRUCTURAL normalizer -X-> ksp-materializer-api
```
`ksp-interface-lib` peut fournir les wires Solana génériques nécessaires à la structure blockchain.
@@ -271,21 +271,21 @@ Un job borné peut rejouer :
RAW persisted range
|
v
CORE normalizer
STRUCTURAL normalizer
|
v
D2 CORE
D2 STRUCTURAL
```
sans redemander les données au réseau.
### STRUCTURAL worker
Le STRUCTURAL worker continu peut consommer le backlog RAW nouvellement persisté et produire CORE.
Le STRUCTURAL worker continu peut consommer le backlog RAW nouvellement persisté et produire STRUCTURAL.
Le Store reste source de vérité du backlog ; les notifications ne sont qu'un wake-up.
## DECODE et SPECIALIZED
## DECODED et DOMAIN
### Introduction par groupe fonctionnel
@@ -294,7 +294,7 @@ KSP ne crée pas d'abord un unique « worker decoder de tout Solana » puis tous
Chaque groupe prioritaire introduit les capacités nécessaires :
```text
CORE inputs du groupe
STRUCTURAL inputs du groupe
|
v
Program decoder
@@ -303,10 +303,10 @@ Program decoder
decoded facts
|
v
generic materialization / DECODE persistence
generic materialization / DECODED persistence
|
v
SPECIALIZED projection si utile
DOMAIN projection si utile
```
Puis le même groupe avance vers préparation d'exécution, policy, execution et scénarios Devnet.
@@ -511,7 +511,7 @@ STRUCTURAL job / STRUCTURAL worker
Pas de Program API.
### Groupes DECODE/SPECIALIZED
### Groupes DECODED/DOMAIN
Le composant de composition du groupe peut utiliser :
@@ -530,5 +530,5 @@ selon les capacités réellement introduites.
- politique d'alias externe `mainnet-beta` à matérialiser uniquement aux frontières qui en ont réellement besoin, sans créer une seconde identité Store ;
- modèle de claim/lease PostgreSQL pour les futurs processors continus ;
- taille de batch et stratégie backpressure des workers de processing ;
- découpage des workers DECODE/SPECIALIZED par groupe lorsque les premiers groupes existent ;
- découpage des workers DECODED/DOMAIN par groupe lorsque les premiers groupes existent ;
- mécanisme IPC des applications de contrôle futures.

24
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# Applications, services, scenarios et control plane
@@ -49,7 +49,7 @@ Elle ne doit pas réimplémenter :
## Applications de validation par couche
KSP peut ajouter une petite application spécialisée à la fin d'une couche RAW ou CORE lorsque cela permet de valider et exploiter réellement la couche avant de passer à la suivante. Ces applications lisent les contrats KSP et ne recopient pas les processors dans Tauri.
KSP peut ajouter une petite application spécialisée à la fin d'une couche RAW ou STRUCTURAL lorsque cela permet de valider et exploiter réellement la couche avant de passer à la suivante. Ces applications lisent les contrats KSP et ne recopient pas les processors dans Tauri.
À partir des vertical slices Program, les applications restent attachées aux besoins réels : demos de scenarios pour l'exécution et Market Desk pour les projections de marché.
@@ -198,12 +198,12 @@ Exemples conceptuels :
ksp-worker-raw-transaction-ingest-lib # premier runtime worker réutilisable retenu
future autonomous raw-ingest binary # seulement si un besoin de service séparé le justifie
future STRUCTURAL worker
future group-specific DECODE/SPECIALIZED workers when justified
future group-specific DECODED/DOMAIN workers when justified
```
Le premier worker RAW est volontairement prévu comme bibliothèque réutilisable afin qu'une Desk ou un futur host puisse le construire sans dupliquer sa logique. Un binaire autonome n'est pas créé par convention seule ; s'il apparaît, il reste un host mince au-dessus de la même bibliothèque et de `ksp-worker-api`.
RAW reçoit son worker d’ingestion à la fin de sa couche ; CORE reçoit ensuite son STRUCTURAL worker lorsque sa persistence/backlog sont disponibles. Les workers DECODE/SPECIALIZED ne sont plus tous anticipés comme une chaîne globale fixe : leur granularité doit émerger des premiers vertical slices Program.
RAW reçoit son worker d’ingestion à la fin de sa couche ; STRUCTURAL reçoit ensuite son STRUCTURAL worker lorsque sa persistence/backlog sont disponibles. Les workers DECODED/DOMAIN ne sont plus tous anticipés comme une chaîne globale fixe : leur granularité doit émerger des premiers vertical slices Program.
Le binaire, lorsqu'il existe, doit rester mince.
@@ -247,16 +247,16 @@ transport / acquisition
D1 RAW
|
v
D2 CORE
D2 STRUCTURAL
|
v
D3 DECODE
D3 DECODED
|
v
D4 SPECIALIZED
D4 DOMAIN
```
Ce schéma décrit les **frontières de données**, pas quatre workers globaux imposés. RAW et CORE peuvent disposer de workers horizontaux propres à leur couche. À partir de DECODE, la granularité des workers/processors émerge des groupes fonctionnels verticaux réellement introduits ; plusieurs groupes peuvent donc posséder des lifecycle hosts distincts sans qu'un `W3` ou `W4` universel existe.
Ce schéma décrit les **frontières de données**, pas quatre workers globaux imposés. RAW et STRUCTURAL peuvent disposer de workers horizontaux propres à leur couche. À partir de DECODED, la granularité des workers/processors émerge des groupes fonctionnels verticaux réellement introduits ; plusieurs groupes peuvent donc posséder des lifecycle hosts distincts sans qu'un `W3` ou `W4` universel existe.
Les notifications accélèrent le réveil mais ne créent pas une connexion fonctionnelle worker-to-worker.
@@ -286,7 +286,7 @@ Le data plane transporte/persiste les données Solana et les résultats de proce
ksp-onchain-transport-lib
|
v
RAW -> CORE -> DECODE -> SPECIALIZED
RAW -> STRUCTURAL -> DECODED -> DOMAIN
```
avec notifications de données persistées comme wake-up.
@@ -516,11 +516,11 @@ Une app spécialisée peut éditer une configuration puis demander son applicati
Après les groupes Meteora/Raydium/Pump/Orca, KSP prévoit une première application spécialisée candidate `ksp-app-market-desk`.
V1 peut afficher tokens, pools/markets, liquidité, trades/swaps, prix, volumes, OHLC et activité live/récente à partir des projections SPECIALIZED et des contrats KSP. Elle ne dépend pas directement des SDK/protocoles DEX pour reconstruire leurs modèles dans l'UI.
V1 peut afficher tokens, pools/markets, liquidité, trades/swaps, prix, volumes, OHLC et activité live/récente à partir des projections DOMAIN et des contrats KSP. Elle ne dépend pas directement des SDK/protocoles DEX pour reconstruire leurs modèles dans l'UI.
Après Jupiter/OKX, la même application est enrichie avec routes, legs, DEX impliqués, fees/slippage et comparaison quote/execution lorsqu'elle existe.
Les OHLC sont matérialisés dans SPECIALIZED et consommés par l'application; ils ne sont pas recalculés à partir de tout l'historique lors de chaque rendu.
Les OHLC sont matérialisés dans DOMAIN et consommés par l'application; ils ne sont pas recalculés à partir de tout l'historique lors de chaque rendu.
## Future orchestrator
@@ -575,7 +575,7 @@ control/application adapters
Data plane séparé :
```text
transport -> RAW -> CORE -> DECODE -> SPECIALIZED
transport -> RAW -> STRUCTURAL -> DECODED -> DOMAIN
```
Aucun payload de processing n'a besoin de transiter via l'UI/control plane.

4
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
<!-- version: 10 -->
<!-- version: 11 -->
# Acquisition et alimentation `RawTransaction`
@@ -610,7 +610,7 @@ priorités/composition
Les prix/tiers d'audit ne doivent pas devenir une politique runtime.
`mainnet` est l'identité réseau durable KSP. `mainnet-beta` reste uniquement un alias de compatibilité/historique ou un libellé externe lorsqu'un provider/API l'emploie. Depuis `0.3.9-pre.006-fix.003`, les profils Config/Store/Transport Mainnet engagés utilisent `mainnet` comme identité logique, et les exemples/tests associés ont été normalisés. Les endpoints publics Solana engagés suivent également la nomenclature Mainnet courante (`https://api.mainnet.solana.com` et `wss://api.mainnet.solana.com`). Aucune migration de données N1 n'est exigée : les données RAW Mainnet encore expérimentales peuvent être droppées/recréées si elles portent l'ancienne identité.
`mainnet` est l'identité réseau durable KSP. `mainnet-beta` reste uniquement un alias de compatibilité/historique ou un libellé externe lorsqu'un provider/API l'emploie. Depuis `0.3.9-pre.006-fix.003`, les profils Config/Store/Transport Mainnet engagés utilisent `mainnet` comme identité logique, et les exemples/tests associés ont été normalisés. Les endpoints publics Solana engagés suivent également la nomenclature Mainnet courante (`https://api.mainnet.solana.com` et `wss://api.mainnet.solana.com`). Aucune migration de données D1 n'est exigée : les données RAW Mainnet encore expérimentales peuvent être droppées/recréées si elles portent l'ancienne identité.
## 13. Normalisation RAW commune sans couplage Job/Worker

60
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
<!-- version: 96 -->
<!-- version: 97 -->
# Séquence des releases fonctionnelles KSP
@@ -524,7 +524,7 @@ Metadata HTTP/IPFS/Arweave viendra au premier besoin Metadata réel. SOL/EUR et
La dependency direction reste strictement `Interface -> Core`; aucun serde/codec générique, `solana-instruction`, runtime réseau ou logging n'est introduit. La façade crate-root est verrouillée par canaris public API, consumer externe, release completeness et dependency firewall. [`../../crates/ksp-interface-lib/README.md`](../../crates/ksp-interface-lib/README.md) et [`../../crates/ksp-interface-lib/USAGE.md`](../../crates/ksp-interface-lib/USAGE.md) deviennent les références durables de cette foundation. Le gate technique final `pre.006` est vert avant réconciliation documentaire.
Aucune `ksp-interface-api` séparée n'est retenue pour l'instant. Les codecs/layouts spécifiques restent conditionnés à un vertical réel, tandis que les wires génériques d'acquisition/CORE restent reportés à `0.3.2+`.
Aucune `ksp-interface-api` séparée n'est retenue pour l'instant. Les codecs/layouts spécifiques restent conditionnés à un vertical réel. La décomposition STRUCTURAL générique reste reportée à la série STRUCTURAL ouverte seulement après fermeture de la couche RAW ; elle n'est plus associée à un ancien numéro `0.3.2+` devenu obsolète.
### `0.2.14` — Program API foundation
@@ -552,50 +552,62 @@ Le hardening final verrouille l'inventaire crate-root exact, le passage d'une `P
Restent explicitement reportés : `ksp-program-lib`, payload canonique D3, registry runtime, identity/version/coverage génériques, autres familles de decoder et `ProgramExecutionPreparer`. Ils seront introduits uniquement par les vertical slices qui démontreront leurs contrats réels.
## Architecture durable : RAW -> CORE -> DECODE -> SPECIALIZED
## Architecture durable : RAW -> STRUCTURAL -> DECODED -> DOMAIN
La chaîne de données est :
```text
D1 RAW
-> D2 CORE
-> D3 DECODE
-> D4 SPECIALIZED
-> D2 STRUCTURAL
-> D3 DECODED
-> D4 DOMAIN
```
RAW et CORE ne nécessitent aucun decoder Program.
RAW et STRUCTURAL ne nécessitent aucun decoder Program.
`RAW -> CORE` est une normalisation générique Solana ; le premier decoder intervient à `CORE -> DECODE`.
`RAW -> STRUCTURAL` est une normalisation générique Solana ; le premier decoder intervient à `STRUCTURAL -> DECODED`.
## Série `0.3.x` — RAW / acquisition persistée
Début décidé :
La séquence effective a évolué par sizing et validation réels. La référence détaillée reste `ROADMAP.md`; cette synthèse conserve uniquement les frontières fonctionnelles :
```text
0.3.1 ksp-store-api + ksp-store-lib, RAW only
0.3.2 ksp-interface-lib, wires génériques acquisition/CORE
0.3.3 ksp-job-api + backfill
0.3.4 application backfill/RAW
0.3.1 ksp-store-api RAW
0.3.2 Store runtime + backend PostgreSQL foundation
0.3.3 persistence RawTransaction
0.3.4 persistence RawAccountState
0.3.5 Interface acquisition events
0.3.6 ksp-job-api + RawTransaction Backfill
0.3.7 ksp-app-backfill-desk
0.3.8 ksp-app-store-desk RAW
0.3.9 ksp-worker-api + audit acquisition RawTransaction
0.3.10 common ksp-raw-transaction-lib + preuves cross-source
0.3.11-0.3.14 Worker RAW ingest découpé par responsabilité
0.3.15 ksp-app-raw-transaction-ingest-desk
0.3.16 Backfill multi-source / multi-stratégie
```
La suite de la série termine la couche RAW avec worker/service live et outils d'exploitation utiles avant l'ouverture de CORE.
Cette série ferme la couche RAW et ses outils d'exploitation avant l'ouverture fonctionnelle de STRUCTURAL. Le Worker live RAW reste distinct des jobs historiques et ne constitue pas encore une transformation RAW -> STRUCTURAL.
`0.3.1` ne doit pas créer par anticipation les modèles/tables DECODE/SPECIALIZED.
Aucune release RAW ne crée par anticipation la persistence DECODED/DOMAIN.
## Série CORE suivante
## Série STRUCTURAL suivante
Objectif : rendre CORE exploitable sans aucun decoder Program :
Objectif : rendre la couche STRUCTURAL exploitable sans aucun decoder Program. Elle décompose les entrées RAW réellement décomposables en unités Solana génériques plus fines destinées au décodage ultérieur :
```text
RAW persisted
-> Solana generic normalization
-> CORE persistence
-> RAW->CORE replay/backfill
-> STRUCTURAL worker/service
-> CORE inspection/control app
-> Solana generic structural decomposition
-> STRUCTURAL persistence
-> RAW -> STRUCTURAL replay/backfill
-> STRUCTURAL job borné/rejouable
-> STRUCTURAL worker/service continu
-> STRUCTURAL inspection/control dans ksp-app-store-desk lorsque pertinent
```
## Séries DECODE/SPECIALIZED/EXECUTION suivantes
Le nom de couche historique `CORE` est abandonné. `Core` reste réservé à `ksp-core-lib`, à son domaine fondamental et aux noms propres tels que « Solana Core Programs ».
## Séries DECODED/DOMAIN/EXECUTION suivantes
À partir du décodage, KSP progresse par vertical slices complets et non par grandes couches de crates isolées :
@@ -638,7 +650,7 @@ Après les DEX prioritaires, introduire une petite `ksp-app-market-desk` consomm
Après Jupiter/OKX, enrichir la même app avec routes, legs, DEX impliqués, fees/slippage et quote/execution lorsque disponible.
L'app ne réimplémente pas les SDK/protocoles DEX ; elle consomme les faits SPECIALIZED normalisés.
L'app ne réimplémente pas les SDK/protocoles DEX ; elle consomme les faits DOMAIN normalisés.
## Discipline de sizing

8
docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# Plan v0.3.10 — RAW Transaction commune + qualification cross-source
@@ -1044,7 +1044,7 @@ Statut : réalisés, avec fixes déjà tracés et `pre.006-fix.001` requis pour
### `pre.007` — gate technique final `0.3.10`
Statut : **ouvert sur `0.3.10-pre.7`** après gate opérateur entièrement vert de `pre.006-fix.002`.
Statut : **fermé**. Le gate opérateur sur `0.3.10-pre.7` est entièrement vert, y compris workspace tests, Clippy strict, suites ciblées et graphes demandés.
Budget cible : **15–20 min**. Rejouer le workspace complet, Clippy strict, suites common/Transport/Backfill, arbres normal/dev/features pertinents et duplicate tree. Aucun nouveau scope fonctionnel ; tout défaut découvert appartient à une tranche corrective dédiée avant de poursuivre la fermeture.
@@ -1052,7 +1052,9 @@ Le gate exact de cette tranche ne référence plus `ksp-worker-raw-transaction-i
### `pre.008` — réconciliation documentaire `0.3.10`
Budget cible : **10–15 min**. Réconcilier plan, validation, README/USAGE de la common si nécessaire et architecture durable avec le périmètre effectivement livré. Aucun runtime Worker, smoke nouveau, CHANGELOG, ROADMAP ou prompt suivant.
Statut : **ouvert sur `0.3.10-pre.8`** après fermeture technique de `pre.007`.
Budget cible : **10–15 min**. Réconcilier plan, validation, séquence fonctionnelle active, règles/architecture durables et README/USAGE de la common avec le périmètre effectivement livré. Normaliser la couche Store D2 (appelée N2 dans certains plans Store historiques) sous le nom `STRUCTURAL` et éliminer les références actives à l'ancien nom de couche `CORE`, sans renommer `ksp-core-lib`, le domaine Core fondamental ou les traces historiques clôturées. `ksp-raw-transaction-lib` doit recevoir `README.md` et `USAGE.md` puisqu'elle devient une bibliothèque complétée. Aucun runtime Worker, smoke nouveau, CHANGELOG ou prompt suivant. `ROADMAP.md` peut être corrigé uniquement pour la nomenclature durable des couches ; ses statuts de publication restent réservés à `pre.009`.
### `pre.009` — préparation de publication `0.3.10`

10
docs/rules/RULES_DEPENDENCIES.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/RULES_DEPENDENCIES.md -->
<!-- version: 17 -->
<!-- version: 18 -->
# Règles des dépendances KSP
@@ -100,13 +100,13 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
## Pipelines spécialisés
- **DEP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique.
- **DEP-PIPE-002** — Les frontières canoniques de processing sont `RAW -> CORE -> DECODE -> SPECIALIZED`. Une crate pipeline dédiée n'est créée que lorsqu'une logique doit réellement être réutilisée entre plusieurs lifecycle hosts (worker/job/app/test) ; aucune liste globale de quatre crates pipeline n'est imposée par symétrie.
- **DEP-PIPE-002** — Les frontières canoniques de processing sont `RAW -> STRUCTURAL -> DECODED -> DOMAIN`. Une crate pipeline dédiée n'est créée que lorsqu'une logique doit réellement être réutilisée entre plusieurs lifecycle hosts (worker/job/app/test) ; aucune liste globale de quatre crates pipeline n'est imposée par symétrie.
- **DEP-PIPE-003** — Un pipeline de processing dépend des APIs nécessaires à sa frontière et non des implémentations officielles correspondantes lorsque l'API permet l'injection/composition.
- **DEP-PIPE-004** — Les pipelines spécialisés ne dépendent pas de `ksp-worker-api` ou `ksp-job-api`; worker et job possèdent le lifecycle.
- **DEP-PIPE-005** — Worker live et job de replay/backfill réutilisent le même pipeline pour une même frontière durable afin d'éviter la duplication de logique.
- **DEP-PIPE-006** — Le pipeline raw ingestion peut dépendre des modèles homogènes de `ksp-onchain-transport-lib` et de `ksp-store-api`, mais pas de `ksp-store-lib`.
- **DEP-PIPE-007** — La transformation `RAW -> CORE` est Solana-générique et ne dépend ni de `ksp-program-api`, ni de `ksp-program-lib`, ni de `ksp-materializer-api`; les premiers contrats Program interviennent seulement à partir de `CORE -> DECODE`.
- **DEP-PIPE-008** — À partir de `CORE -> DECODE`, les pipelines/processors verticaux peuvent dépendre de `ksp-program-api` et de `ksp-materializer-api` selon leur rôle, sans dépendre par défaut des implémentations officielles correspondantes lorsque l'injection/composition suffit. `DECODE -> SPECIALIZED` utilise de même les contrats de matérialisation/projection nécessaires sans imposer une implémentation globale unique.
- **DEP-PIPE-007** — La transformation `RAW -> STRUCTURAL` est Solana-générique et ne dépend ni de `ksp-program-api`, ni de `ksp-program-lib`, ni de `ksp-materializer-api`; les premiers contrats Program interviennent seulement à partir de `STRUCTURAL -> DECODED`.
- **DEP-PIPE-008** — À partir de `STRUCTURAL -> DECODED`, les pipelines/processors verticaux peuvent dépendre de `ksp-program-api` et de `ksp-materializer-api` selon leur rôle, sans dépendre par défaut des implémentations officielles correspondantes lorsque l'injection/composition suffit. `DECODED -> DOMAIN` utilise de même les contrats de matérialisation/projection nécessaires sans imposer une implémentation globale unique.
## Worker / Job lifecycle
@@ -115,7 +115,7 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
- **DEP-WORKER-003** — La logique réutilisable d'un worker/job dépend en priorité des APIs KSP (`ksp-store-api`, `ksp-program-api`, `ksp-materializer-api`, etc.) et reçoit les implémentations par composition. Le binaire/service mince peut câbler `ksp-store-lib` ou les implémentations officielles nécessaires sans transférer cet ownership à la logique du worker/job.
- **DEP-JOB-001** — `ksp-job-api` ne dépend ni de `ksp-worker-api` ni de `ksp-worker-control-lib`.
- **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun.
- **DEP-JOB-003** — Lorsqu'une même transformation existe en live et en replay, jobs et workers réutilisent la même logique de transformation au lieu de dupliquer `RAW -> CORE`, `CORE -> DECODE` ou `DECODE -> SPECIALIZED`.
- **DEP-JOB-003** — Lorsqu'une même transformation existe en live et en replay, jobs et workers réutilisent la même logique de transformation au lieu de dupliquer `RAW -> STRUCTURAL`, `STRUCTURAL -> DECODED` ou `DECODED -> DOMAIN`.
## Services, applications et control plane

10
docs/rules/RULES_KSP.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/RULES_KSP.md -->
<!-- version: 39 -->
<!-- version: 40 -->
# Règles spécifiques à KSP
@@ -141,7 +141,7 @@
- **KSP-WORKER-005** — `ksp-worker-raw-retriever` est le worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
- **KSP-WORKER-006** — `ksp-worker-raw-retriever` persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
- **KSP-WORKER-007** — `ksp-worker-raw-retriever` doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
- **KSP-WORKER-008** — Les workers de processing ne sont pas figés à l'avance sous une chaîne globale `core -> generic materializer -> domain projector`. RAW et CORE peuvent disposer de workers horizontaux propres à leur couche ; à partir de DECODE, les workers/processors sont introduits au besoin avec chaque groupe fonctionnel vertical afin que décodage, matérialisation, projection spécialisée et validation d'exécution évoluent ensemble.
- **KSP-WORKER-008** — Les workers de processing ne sont pas figés à l'avance sous une chaîne globale `structural -> generic materializer -> domain projector`. RAW et STRUCTURAL peuvent disposer de workers horizontaux propres à leur couche ; à partir de DECODED, les workers/processors sont introduits au besoin avec chaque groupe fonctionnel vertical afin que décodage, matérialisation, projection spécialisée et validation d'exécution évoluent ensemble.
- **KSP-WORKER-009** — Les workers de processing utilisent notification comme wake-up mais reconstruisent leur backlog depuis le Store.
- **KSP-WORKER-010** — `ksp-worker-raw-retriever` distingue une configuration desired et une configuration effective lors des reconfigurations à chaud.
- **KSP-WORKER-011** — Un cursor de scan est une optimisation ; les processing outcomes durables constituent la preuve qu'un input a été traité pour un processor/version/capability.
@@ -161,7 +161,7 @@
- **KSP-JOB-006** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
- **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie.
- **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers.
- **KSP-JOB-009** — Aucun inventaire global de jobs de replay DECODE/SPECIALIZED n'est figé à l'avance. `RAW -> CORE` peut introduire un job de replay Core lorsque la couche CORE est ouverte ; à partir de DECODE, les jobs de replay sont introduits avec les groupes/capacités verticaux qui en ont réellement besoin, sans imposer des jobs génériques `generic-materialization` / `domain-projection` pour tout Solana.
- **KSP-JOB-009** — Aucun inventaire global de jobs de replay DECODED/DOMAIN n'est figé à l'avance. `RAW -> STRUCTURAL` peut introduire un job de replay STRUCTURAL lorsque la couche STRUCTURAL est ouverte ; à partir de DECODED, les jobs de replay sont introduits avec les groupes/capacités verticaux qui en ont réellement besoin, sans imposer des jobs génériques `generic-materialization` / `domain-projection` pour tout Solana.
- **KSP-JOB-010** — Les jobs de replay réutilisent exactement le pipeline spécialisé de la frontière correspondante.
- **KSP-JOB-011** — Le backfill conserve un checkpoint de progression dans la source historique en plus des outcomes de persistence D1.
- **KSP-JOB-012** — Replay normal/reprise et force replay sont deux intentions distinctes ; un force replay conserve provenance/historique et ne supprime pas silencieusement le résultat courant.
@@ -181,7 +181,7 @@
## Pipelines et scénarios
- **KSP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique.
- **KSP-PIPE-002** — Les frontières canoniques de données/processing sont `RAW -> CORE -> DECODE -> SPECIALIZED`. Les pipelines RAW et CORE peuvent être développés horizontalement jusqu'à leur acquisition/persistence/replay/worker/app ; à partir de DECODE, KSP progresse par groupes fonctionnels verticaux et ne pré-déclare pas une chaîne globale de crates pipeline pour tous les protocoles.
- **KSP-PIPE-002** — Les frontières canoniques de données/processing sont `RAW -> STRUCTURAL -> DECODED -> DOMAIN`. Les pipelines RAW et STRUCTURAL peuvent être développés horizontalement jusqu'à leur acquisition/persistence/replay/worker/app ; à partir de DECODED, KSP progresse par groupes fonctionnels verticaux et ne pré-déclare pas une chaîne globale de crates pipeline pour tous les protocoles.
- **KSP-PIPE-003** — Un pipeline spécialisé contient la logique réutilisable d'une frontière mais aucun lifecycle worker/job.
- **KSP-PIPE-004** — Les pipelines utilisent les APIs Program/Materializer/Store lorsque ces frontières doivent être injectables ; les implémentations officielles sont composées par workers/jobs.
- **KSP-PIPE-005** — Le traitement est at-least-once avec persistence idempotente et outcomes durables, plutôt qu'une promesse exactly-once distribuée.
@@ -262,5 +262,5 @@
- **KSP-REL-016** — Une prerelease vise environ 15 à 20 minutes de travail effectif. Le `pre.001` dimensionne aussi la release concrète entière : une release doit pouvoir être ouverte, développée, validée et clôturée dans une seule session de chat. Si cette clôture paraît incertaine, la release est scindée avant l'implémentation fonctionnelle lourde ; une version volontairement répartie sur plusieurs sessions est interdite.
- **KSP-TRANSPORT-006** — Pour une surface de transport explicitement ciblée, KSP inventorie et implémente toutes les méthodes/opérations exposées par la documentation normative retenue, sauf impossibilité technique explicitement documentée. L'inventaire couvre aussi les sections officielles séparées `deprecated`/`obsolete` et `unstable`/`experimental` lorsqu'elles existent. Les opérations deprecated/obsolete encore réellement fonctionnelles et unstable/experimental restent utilisables mais émettent un `warn` via `ksp-logging-lib` à chaque utilisation concernée ; leur statut est décrit par une metadata centralisée et non par des warnings dispersés.
- **KSP-TRANSPORT-007** — La complétude d'un wrapper de transport standard couvre toute la surface sémantique de requête auditée : paramètres, options de configuration, variantes/overloads courants, formes legacy encore supportées et contraintes déterministes connues. Les formes de réponse pertinentes sont conservées losslessly, y compris les variantes, `null` et omissions significatives. KSP peut canonicaliser des syntaxes strictement équivalentes et conserver des sous-arbres wire riches via `serde_json::Value` tant qu'aucune information n'est perdue ; toute limitation volontaire d'une possibilité normative/runtime supportée doit être explicitement justifiée et documentée.
- **KSP-FLOW-001** — La progression durable canonique est `RAW -> CORE -> DECODE -> SPECIALIZED`. RAW et CORE ne nécessitent aucun decoder Program ; le passage RAW -> CORE reste une normalisation générique de la blockchain Solana. À partir de DECODE, KSP progresse verticalement par groupe fonctionnel à travers wire, décodage, matérialisation, projection spécialisée si utile, préparation d'exécution, policy, exécution et scénarios de validation.
- **KSP-FLOW-001** — La progression durable canonique est `RAW -> STRUCTURAL -> DECODED -> DOMAIN`. RAW et STRUCTURAL ne nécessitent aucun decoder Program ; le passage RAW -> STRUCTURAL reste une décomposition/normalisation structurelle générique de la blockchain Solana. Le nom de couche historique `CORE` est abandonné pour D2 et ne doit pas être réintroduit ; cette règle ne renomme ni `ksp-core-lib`, ni le domaine Core fondamental, ni les noms propres tels que « Solana Core Programs ». À partir de DECODED, KSP progresse verticalement par groupe fonctionnel à travers wire, décodage, matérialisation, projection spécialisée si utile, préparation d'exécution, policy, exécution et scénarios de validation.
- **KSP-FLOW-002** — Un programme ou composant satellite nécessaire à la compréhension, la matérialisation ou l'exécution correcte d'un protocole appartient au groupe de ce protocole. Il n'est pas reporté artificiellement dans une catégorie `trading-adjacent`.

23
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# Validation v0.3.10 — RAW Transaction commune + qualification cross-source
@@ -1018,7 +1018,7 @@ Le même correctif réconcilie aussi l'architecture durable avec l'extraction co
```text
ksp-raw-transaction-lib est inventoriée explicitement ;
son graphe lower-layer est documenté ;
CORE processor / CORE worker deviennent STRUCTURAL job / STRUCTURAL worker ;
les anciens libellés `CORE processor` / `CORE worker` sont requalifiés en `STRUCTURAL job` / `STRUCTURAL worker` ;
le plan conserve une note de génération séquentielle des prompts 0.3.12 -> 0.3.15.
```
@@ -1042,3 +1042,22 @@ Les smokes réseau opt-in de Transport restent `ignored` conformément à leur p
Tout défaut découvert ouvre `pre.007-fix.NNN`. Tant que le gate `pre.007` n'est pas entièrement vert, `pre.008` de réconciliation documentaire ne doit pas commencer.
### 13.13 Gate opérateur `pre.007` et ouverture de `pre.008`
Le rejeu opérateur communiqué le 8 septembre 2026 sur `0.3.10-pre.7` ferme le gate technique final : audits Rust/Markdown, `cargo check --workspace`, Clippy workspace strict, `cargo test --workspace --all-targets --all-features`, suites ciblées common/Transport/Backfill et graphes Cargo demandés sont exécutés sans échec. Les smokes live opt-in restent `ignored` par conception et ne sont pas requalifiés en preuves réseau.
`pre.008` est exclusivement documentaire. La nomenclature durable des couches de données Store est réconciliée avec la décision prise lors de l'ouverture Store :
```text
D1 = RAW
D2 = STRUCTURAL
D3 = DECODED
D4 = DOMAIN
```
Les plans Store historiques qui parlent de N1–N4 data sont interprétés selon cette correspondance, mais la documentation durable réserve désormais `D1–D4` aux couches de données afin de ne pas entrer en collision avec les niveaux architecturaux N1–N4 de `002-LAYERS_AND_DEPENDENCIES.md`.
Le terme historique `CORE` n'est plus un nom de couche D2 Store. Il reste valide lorsqu'il désigne `ksp-core-lib`, le domaine Core fondamental ou un nom propre comme « Solana Core Programs ». Les anciens plans/deltas clôturés restent des traces historiques et ne sont pas réécrits en masse.
La réconciliation vérifie également la documentation durable de `ksp-raw-transaction-lib` : la crate étant désormais une lower-layer complétée de `0.3.10`, elle doit posséder son `README.md` descriptif et son `USAGE.md` version-neutre conformément aux règles de clôture des bibliothèques KSP.