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

v0.3.1-pre.010

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-29 11:39:50 +02:00
parent 2f0eb316f5
commit 78e015413b
6 changed files with 247 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/022-V0_3_1_STORE_RAW_PLAN.md -->
<!-- version: 9 -->
<!-- version: 10 -->
# Plan `0.3.1` — Store API RAW foundation
@@ -32,15 +32,20 @@ Après application de `pre.001`, la version Cargo cible est :
Le brainstorming de `pre.001` a séparé la création de l'API Store de son implémentation PostgreSQL.
La trajectoire devient :
La trajectoire devient d'abord :
```text
0.3.1 = ksp-store-api uniquement
0.3.2 = ksp-store-lib + ksp-store-postgres-lib
0.3.2 = ouverture conjointe ksp-store-lib + ksp-store-postgres-lib
fondation runtime/backend PostgreSQL uniquement
feature postgres par défaut
PostgreSQL de référence via tokio-postgres
0.3.3 = même paire de crates / persistence PostgreSQL RawTransaction complète
0.3.4 = même paire de crates / RawAccountState + complétude Store RAW
```
Le redécoupage `pre.010` conserve donc les deux crates Store/PostgreSQL **ensemble à chaque release**, mais sépare la charge en trois slices. Il évite de cumuler dans une seule session création de façade, Config, connexions/migrations, persistence transaction, rétention et persistence account.
Cette décision remplace pour `0.3.1` la mission combinée `ksp-store-api + ksp-store-lib` décrite dans le prompt de démarrage. `pre.001-fix.001` réconcilie immédiatement le `ROADMAP.md` afin que la trajectoire globale ne conserve pas une séquence désormais fausse.
Conséquences immédiates :
@@ -56,9 +61,9 @@ aucun std.store
aucun ksp-store-lib
```
`0.3.1` doit stabiliser le contrat logique suffisamment pour que `0.3.2` puisse ensuite demander :
`0.3.1` doit stabiliser le contrat logique suffisamment pour que la série `0.3.2`–`0.3.4` puisse ensuite demander :
> quelle représentation PostgreSQL satisfait le mieux ce contrat ?
> quelle représentation PostgreSQL satisfait le mieux ce contrat, puis comment l'implémenter famille par famille sans réduire le contrat API ?
et non :
@@ -80,7 +85,7 @@ contrats/capabilities backend extensibles
cycle de rétention logique du RAW et tombstones anti-rebackfill
```
Le health/readiness runtime et un éventuel type canonique dédié de wake-up ne sont finalement pas matérialisés dans `0.3.1`. Les références durables de l'API suffisent pour la foundation RAW ; le health appartient à la façade runtime `ksp-store-lib` de `0.3.2`, tandis qu'un contrat de notification dédié ne sera ajouté que lorsqu'un consumer/publisher réel en aura besoin conformément aux règles KSP-NOTIFY.
Le health/readiness runtime et un éventuel type canonique dédié de wake-up ne sont finalement pas matérialisés dans `0.3.1`. Les références durables de l'API suffisent pour la foundation RAW ; le health appartient à la façade runtime `ksp-store-lib` et peut être cadré dès la fondation `0.3.2`, tandis qu'un contrat de notification dédié ne sera ajouté que lorsqu'un consumer/publisher réel en aura besoin conformément aux règles KSP-NOTIFY.
La release doit aussi auditer les autres données on-chain réellement utiles afin de distinguer explicitement :
@@ -91,7 +96,7 @@ modèle event-only non persisté
DTO Transport seulement
```
La façade runtime concrète `Store`, la sélection d'un backend compilé et l'orchestration commune appartiendront à `ksp-store-lib` en `0.3.2`. Les consumers ordinaires jobs/workers/apps dépendront alors uniquement de `ksp-store-lib`, qui réexportera la surface commune nécessaire de `ksp-store-api`.
La façade runtime concrète `Store`, la sélection d'un backend compilé et l'orchestration commune appartiendront à `ksp-store-lib` à partir de `0.3.2`. Les consumers ordinaires jobs/workers/apps dépendront alors uniquement de `ksp-store-lib`, qui réexportera la surface commune nécessaire de `ksp-store-api`. `0.3.3` et `0.3.4` complèteront cette même façade et le même backend PostgreSQL sans introduire une seconde architecture.
`ksp-store-api` ne devient pas propriétaire de tous les messages inter-crates. Un modèle passif partagé qui ne représente aucune donnée persistée/rejouable et sert uniquement à transporter un événement entre acquisition et traitement relève préférentiellement de `ksp-interface-lib`. La frontière exacte doit être documentée avant création d'un tel type afin d'éviter deux structs concurrentes représentant le même fait.
@@ -154,7 +159,7 @@ backend alternatif -X-> ksp-store-lib
### 4.2 Features de `ksp-store-lib`
`0.3.2` introduira au minimum :
La fondation `0.3.2` introduira au minimum :
```text
default = [postgres]
@@ -189,7 +194,7 @@ backend compilé sélectionné
crate backend privée
```
Règles fixées pour `0.3.2` et les futurs backends :
Règles fixées pour `0.3.2` puis conservées par `0.3.3`, `0.3.4` et les futurs backends :
- utiliser une URI/DSN lorsque le moteur possède une forme URI naturelle (`postgresql://...`, futur `mysql://...`, etc.) ;
- permettre des options typées backend-specific uniquement lorsqu'elles sont réellement nécessaires et sans `serde_json::Value` opaque comme contrat runtime ;
@@ -200,7 +205,7 @@ Règles fixées pour `0.3.2` et les futurs backends :
- distinguer `backend inconnu` de `backend KSP connu mais non compilé` avant tentative de connexion ;
- éviter tout fallback implicite vers `PG*`, `.pgpass` ou autre source d'environnement lue directement par le driver/backend lorsque Config a déjà fourni les settings effectifs.
La forme exacte de `StoreSettings` et du document `std.store` appartient au design de `0.3.2`; `0.3.1` fixe seulement ces responsabilités et invariants.
La forme exacte de `StoreSettings` et du document `std.store` appartient au design de fondation `0.3.2`; `0.3.1` fixe seulement ces responsabilités et invariants.
### 4.4 Surface consumer
@@ -792,7 +797,7 @@ Aucune promesse exactly-once distribuée n'est faite.
`ksp-store-api` définit le modèle persistant et les opérations backend-agnostic qu'une implémentation doit satisfaire. `0.3.1` ne construit pas de backend, ne sélectionne aucun moteur et n'introduit pas encore la façade runtime concrète `Store`.
Le backend concret implémente des contrats publics d'extension, mais son modèle interne reste privé. En `0.3.2`, `ksp-store-lib::Store` enveloppera ces contrats et deviendra la seule façade de consommation normale des jobs/workers/apps.
Le backend concret implémente des contrats publics d'extension, mais son modèle interne reste privé. À partir de `0.3.2`, `ksp-store-lib::Store` enveloppera progressivement ces contrats et deviendra la seule façade de consommation normale des jobs/workers/apps. La conformance PostgreSQL des familles RAW est ensuite matérialisée par slices en `0.3.3` puis `0.3.4`.
### 11.2 Object-safety et async
@@ -864,7 +869,7 @@ get_raw_account_observation(observation_key)
record_raw_account_observation(observation)
```
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 `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 dans la slice `RawTransaction` `0.3.3`, puis avec le même invariant pour `RawAccountState` en `0.3.4`; 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.
@@ -1112,9 +1117,9 @@ L'archive contient aussi les documents kbot2 historiques. Ils avaient déjà for
| Concept historique | Observation kbot2/kbot3 | Décision | Application KSP |
|------------------------------------------|-------------------------------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------|
| séparation façade Store / PostgreSQL | PostgreSQL et driver privés | REPRENDRE | API commune séparée ; façade + backend PostgreSQL reportés à `0.3.2` |
| séparation façade Store / PostgreSQL | PostgreSQL et driver privés | REPRENDRE | API commune séparée ; paire façade/backend ouverte en `0.3.2` puis complétée par slices `0.3.3`/`0.3.4` |
| `StoreOpenOptions` / backend selection | backend + options historiques partiellement opaques | REDESSINER | Config produit les settings ; `ksp-store-lib` sélectionne un backend compilé |
| health/readiness | contrat backend-neutral présent | REPORTER | health runtime portable à cadrer dans `ksp-store-lib` `0.3.2`; aucun `StoreHealth` dans `ksp-store-api` `0.3.1` |
| health/readiness | contrat backend-neutral présent | REPORTER | health runtime portable à cadrer dans la fondation `ksp-store-lib` `0.3.2`; aucun `StoreHealth` dans Store API |
| transaction canonique source-independent | HTTP/WS/gRPC convergent vers une transaction canonique | REPRENDRE | `RawTransaction` commun seulement si la source satisfait le contrat complet |
| acquisition observations | transaction + account observations séparées du RAW | REPRENDRE | concept N1 central ; transaction d'abord, account prévu après matrice de compatibilité |
| ancienne raw WS notification | kbot2 l'a supprimée de la baseline persistante | REPRENDRE | `logsSubscribe`/events restent event-only par défaut ; pas de table de notification brute |
@@ -1353,7 +1358,7 @@ Aucun PostgreSQL live test n'appartient à `0.3.1` puisque le backend PostgreSQL
| backend capabilities | `ksp-store-api` | public | `0.3.1` | implémentations externes |
| `Store` facade | `ksp-store-lib` | public | `0.3.2` | point de consommation commun |
| backend dispatch/settings | `ksp-store-lib` | public/privé selon contrat | `0.3.2` | features disponibles + sélection Config |
| PostgreSQL rows/pool/SQL/migrations | `ksp-store-postgres-lib` | privé/opérateur | `0.3.2` | détails physiques |
| PostgreSQL rows/pool/SQL/migrations | `ksp-store-postgres-lib` | privé/opérateur | `0.3.2` puis `0.3.3`/`0.3.4` | fondation puis schémas RAW par slice |
| transport -> RAW conversion | composition/pipeline futur | privé/réutilisable | release acquisition | conversion explicite, jamais dépendance inverse |
| RAW -> STRUCTURAL | future pipeline générique | hors `0.3.1` | série suivante | aucune dépendance Program |
| event runtime / scheduler / analyzer | worker/analyser/runtime futur | hors Store | ultérieur | Store ne notifie pas lui-même |
@@ -1435,7 +1440,15 @@ Le gate opérateur a été exécuté après `cargo clean` : audits Rust/Markdown
Le plan, la validation, l'inventaire/graphe d'architecture, les dépendances des futurs consumers Store et `IDEAS.md` sont réconciliés avec la surface réellement livrée. `README.md` ne porte pas d'inventaire Store détaillé et aucun USAGE Store n'existe encore : aucune modification artificielle n'y est ajoutée. Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant n'est touché.
### `pre.010` — Préparation de publication minimale
### `pre.010` — Redécoupage documentaire des futures slices Store/PostgreSQL
**Statut : matérialisé par `0.3.1-pre.010`.**
Cette tranche rouvre uniquement la responsabilité documentaire de trajectoire après décision opérateur postérieure à `pre.009`. Elle découpe l'ancien `0.3.2` surdimensionné en trois releases où `ksp-store-lib` et `ksp-store-postgres-lib` progressent toujours ensemble : fondation runtime/backend, `RawTransaction`, puis `RawAccountState` + complétude.
Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant n'est touché dans cette tranche afin de respecter la séparation des couloirs de fermeture.
### `pre.011` — Préparation de publication minimale
Uniquement :
@@ -1444,10 +1457,10 @@ Cargo.toml
CHANGELOG.md
ROADMAP.md
prompts/021-V0_3_2_START_PROMPT.md
delta pre.010
delta pre.011
```
Le prompt `0.3.2` ouvre ensemble `ksp-store-lib` et `ksp-store-postgres-lib`, avec feature `postgres` par défaut et `tokio-postgres` strictement dans la crate backend.
Le prompt `0.3.2` ouvre ensemble `ksp-store-lib` et `ksp-store-postgres-lib`, mais **uniquement pour la fondation runtime/backend PostgreSQL**. Les surfaces `RawTransaction` et `RawAccountState` restent réservées respectivement à `0.3.3` et `0.3.4`.
### `rel.001` — Publication stable
@@ -1461,16 +1474,18 @@ La prévision durable devient, sous réserve des gates de chaque release :
```text
0.3.1 ksp-store-api / N1 RAW + observations + lifecycle logique
0.3.2 ksp-store-lib + ksp-store-postgres-lib / PostgreSQL reference via tokio-postgres
0.3.3 ksp-interface-lib additions nécessaires aux événements/acquisitions partagés
0.3.4 ksp-job-api + premier backfill RAW concret
0.3.5 application backfill/inspection RAW
0.3.2 Store/PostgreSQL foundation / runtime, Config, connexion, migrations, health
0.3.3 Store/PostgreSQL RawTransaction / persistence + observations + query + retention
0.3.4 Store/PostgreSQL RawAccountState + complétude/conformance RAW cross-family
0.3.5 ksp-interface-lib additions nécessaires aux événements/acquisitions partagés
0.3.6 ksp-job-api + premier backfill RAW concret
0.3.7 application backfill/inspection RAW
ensuite worker/service live RAW avant ouverture N2 STRUCTURAL
```
Les événements realtime non persistés et les modèles Interface peuvent être avancés ou retardés selon le premier consumer réel ; ils ne doivent pas être artificiellement absorbés par Store.
La renumérotation `0.3.1..0.3.5` issue de `pre.001-fix.001` reste valide.
Le redécoupage `pre.010` remplace la renumérotation précédente `0.3.2..0.3.5`. Les deux crates `ksp-store-lib` et `ksp-store-postgres-lib` restent développées de pair dans les trois slices `0.3.2`–`0.3.4`; seule la responsabilité fonctionnelle de chaque release est réduite.
## 25. Critères de fermeture de `0.3.1`
@@ -1503,5 +1518,5 @@ health/readiness runtime et type de wake-up dédié restent explicitement hors `
aucune dépendance PostgreSQL
aucune surface N2 STRUCTURAL/N3 DECODED/N4 DOMAIN implémentée
workspace et graphes entièrement verts
prompt 0.3.2 cohérent avec ksp-store-lib + ksp-store-postgres-lib + tokio-postgres
prompt 0.3.2 cohérent avec la fondation conjointe ksp-store-lib + ksp-store-postgres-lib + tokio-postgres, sans absorber RawTransaction/RawAccountState
```