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

v0.3.1-pre.009

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-29 11:22:29 +02:00
parent 55325ffd32
commit 2f0eb316f5
13 changed files with 412 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/plans/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/000-README.md -->
<!-- version: 67 -->
<!-- version: 68 -->
# Plans KSP
@@ -28,8 +28,9 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
- [`017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) — plan historique clôturé de la release stable `0.2.10 — OrbitFlare Yellowstone gRPC`; il conserve le Devnet gRPC gratuit, N1/N2 immuables, la License Key `x-token` et le smoke final `Slot + Ping`.
- [`018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) — plan historique clôturé de `0.2.11 — Off-chain price transport`; SOL/USD V1, huit providers REST sans SDK, registry/availability/rate limits Off-chain et Config `std.offchain_transport`.
- [`019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](019-V0_2_12_SOL_PRICES_DESK_PLAN.md) — plan historique clôturé de `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk`; il conserve le gabarit 1434/1435, le composite Config, les DTO/commands provider-neutral, l’intégration Wallet minimale et les gates live/build finaux.
- [`020-V0_2_13_INTERFACE_PLAN.md`](020-V0_2_13_INTERFACE_PLAN.md) — plan candidat réconcilié de `0.2.13 — Interface / wire foundation`; il fixe la surface finale `ProgramAccountMeta` + `ProgramInstruction`, les bornes `255` / `10_240`, le firewall Interface -> Core, les canaris de complétude/consumer externe et la frontière avec Program API/RAW/CORE.
- [`021-V0_2_14_PROGRAM_API_PLAN.md`](021-V0_2_14_PROGRAM_API_PLAN.md) — plan candidat réconcilié de `0.2.14 — Program API foundation`; il fixe la façade instruction-only ouverte, les enums Recognition/Outcome, `ProgramInstructionDecoder`, l'output associé possédé par l'implémentation, le canari externe avec Program Pubkey non enregistré, le firewall Core/Interface et le report du payload canonique D3, du registry runtime et de `ProgramExecutionPreparer`.
- [`020-V0_2_13_INTERFACE_PLAN.md`](020-V0_2_13_INTERFACE_PLAN.md) — plan historique clôturé de la release stable `0.2.13 — Interface / wire foundation`; il fixe la surface finale `ProgramAccountMeta` + `ProgramInstruction`, les bornes `255` / `10_240`, le firewall Interface -> Core, les canaris de complétude/consumer externe et la frontière avec Program API/RAW/CORE.
- [`021-V0_2_14_PROGRAM_API_PLAN.md`](021-V0_2_14_PROGRAM_API_PLAN.md) — plan historique clôturé de la release stable `0.2.14 — Program API foundation`; il fixe la façade instruction-only ouverte, les enums Recognition/Outcome, `ProgramInstructionDecoder`, l'output associé possédé par l'implémentation, le canari externe avec Program Pubkey non enregistré, le firewall Core/Interface et le report du payload canonique D3, du registry runtime et de `ProgramExecutionPreparer`.
- [`022-V0_3_1_STORE_RAW_PLAN.md`](022-V0_3_1_STORE_RAW_PLAN.md) — plan candidat réconcilié de `0.3.1 — Store API RAW foundation`; il fixe `ksp-store-api` seul, les modèles transaction/account + observations, queries/outcomes/capabilities, rétention/tombstone, la frontière event-only/Interface et le report de `ksp-store-lib` + PostgreSQL à `0.3.2`.
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.

90
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: 8 -->
<!-- version: 9 -->
# Plan `0.3.1` — Store API RAW foundation
@@ -76,12 +76,12 @@ observations d'acquisition persistantes lorsque leur conservation est utile
références durables
outcomes d'écriture/idempotence
queries cursorisées sans plafond métier arbitraire
health/readiness communs utiles
contrats/capabilities backend extensibles
référence/format canonique de wake-up pour une donnée déjà persistée, conformément aux règles KSP-NOTIFY
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.
La release doit aussi auditer les autres données on-chain réellement utiles afin de distinguer explicitement :
```text
@@ -941,7 +941,7 @@ Les autres références sont ajoutées uniquement avec leur modèle réel.
Le Store runtime persiste et lit. Il ne possède ni scheduler, ni event bus, ni mécanisme de publication et ne doit pas s'appuyer sur une notification native de base de données pour piloter le pipeline.
Les règles `KSP-NOTIFY-001..006` restent applicables : `ksp-store-api` peut posséder **le format canonique** d'un wake-up signifiant qu'une donnée déjà commitée est disponible, sous forme de référence durable compacte. Cela ne signifie pas que la base ou `ksp-store-lib` publie elle-même le signal.
Les règles `KSP-NOTIFY-001..006` restent applicables, mais `0.3.1` n'ajoute **aucun type de notification dédié**. Les références durables déjà exposées par `ksp-store-api` fournissent l'identité compacte nécessaire à un futur contrat de wake-up si un publisher/consumer réel le justifie. La base et `ksp-store-lib` ne publient pas eux-mêmes le signal.
Le futur ordre d'orchestration est :
@@ -1036,20 +1036,13 @@ La policy est **spécifique à chaque famille**. `RawAccountState`, qui pourrait
`0.3.1` doit préparer les contrats logiques de rétention/tombstone sans implémenter compression, stockage d'archive, cron/worker de purge ou maintenance PostgreSQL.
## 13. Health et diagnostics
## 13. Health et diagnostics — reportés au runtime Store
La façade peut exposer un health commun minimal :
`0.3.1` n'expose aucun `StoreHealth` dans `ksp-store-api`. Le health/readiness est un état runtime de la façade et des backends, pas une propriété nécessaire des modèles RAW persistants.
```text
Unknown
Healthy
Degraded
Unhealthy
```
`0.3.2` devra cadrer dans `ksp-store-lib` une projection portable uniquement si les consumers runtime en ont réellement besoin ; les backends pourront fournir leurs diagnostics privés derrière cette projection.
avec un backend code sûr et un code diagnostic borné si nécessaire.
Ne pas exposer dans l'API commune :
Ne jamais exposer dans l'API commune :
```text
migration SQL state
@@ -1060,7 +1053,7 @@ DSN
SQLSTATE arbitraire présenté comme contrat portable
```
Les diagnostics spécifiques à PostgreSQL appartiennent à `ksp-store-postgres-lib`. `ksp-store-lib` ne projette vers le contrat commun que les états réellement portables et sanitised.
Les diagnostics spécifiques à PostgreSQL appartiennent à `ksp-store-postgres-lib`. Si `ksp-store-lib` expose un health commun en `0.3.2`, il ne projette que les états réellement portables et sanitised.
## 14. Dependency graph `0.3.1`
@@ -1121,12 +1114,12 @@ L'archive contient aussi les documents kbot2 historiques. Ils avaient déjà for
|------------------------------------------|-------------------------------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------|
| 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` |
| `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 | REPRENDRE | health minimal portable dans `ksp-store-api` |
| 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` |
| 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 |
| logs transactionnels | conservés puis extraits dans la couche Core historique | REDESSINER | restent dans `RawTransaction`, puis deviennent des unités N2 STRUCTURAL ; pas de `RawLog` persistant séparé |
| account observations/states | N1 account observation + N2 account state existaient | REDESSINER | prévoir `RawAccountState`/observation ; N2 seulement si une décomposition réellement utile est démontrée |
| account observations/states | N1 account observation + N2 account state existaient | REDESSINER | `RawAccountState`/observation stabilisés en N1 ; N2 seulement si une décomposition réellement utile est démontrée |
| repository traits | capabilities async séparées | REPRENDRE | capabilities read/write fines, aucune obligation de supporter toutes les familles |
| pagination | cursor opaque historique | REDESSINER | limite caller > 0 sans plafond métier KSP ; cursor hostile borné uniquement |
| replay contracts | sélection + force replay version-aware | REPRENDRE | futur replay piloté par processor/version/input hash, jamais par simple bool |
@@ -1341,30 +1334,30 @@ Aucun PostgreSQL live test n'appartient à `0.3.1` puisque le backend PostgreSQL
## 21. Ownership
| Concept | Owner candidat/fixé | Visibilité | Introduction | Raison |
|--------------------------------------|-------------------------------|-----------------------------|---------------------------------------|-----------------------------------------------------|
| `RawTransaction` | `ksp-store-api` | public | `0.3.1` | modèle persistant/replayable commun |
| `RawTransactionObservation` | `ksp-store-api` | public | `0.3.1` | acquisition durable distincte du RAW |
| transaction log messages RAW | dans `RawTransaction` | public via modèle RAW | `0.3.1` | font partie de la transaction avant décomposition |
| structural transaction log lines | future couche N2 | hors `0.3.1` | série STRUCTURAL | unités extraites après décomposition |
| `RawAccountState` | `ksp-store-api` | public si audit PASS | prévu `0.3.1`, capability progressive | état canonique commun HTTP/WS/gRPC à confirmer |
| `RawAccountObservation` | `ksp-store-api` | public si audit PASS | prévu `0.3.1`, capability progressive | provenance/account acquisition |
| `TransactionStatusObservation` | à confirmer `ksp-store-api` | public si persistence utile | exploration `0.3.1` | petit état durable/event potentiel |
| log/status/slot/vote event-only | préférer `ksp-interface-lib` | public passif | future tranche Interface si retenue | échange inter-composants sans persistence Store |
| `RawRetentionState` / tombstone | `ksp-store-api` | public logique | à stabiliser en `0.3.1` | cycle de vie RAW backend-agnostic |
| processing ledger versionné | future contrat Store commun | hors surface initiale RAW | avec jobs/N2/N3 | preuve durable stage/version/input, pas bool |
| RAW references | `ksp-store-api` | public | `0.3.1` | reads/replay/lineage |
| write outcomes | `ksp-store-api` | public | `0.3.1` | sémantique idempotente commune |
| query/page | `ksp-store-api` | public | `0.3.1` | navigation/replay backend-agnostic |
| health portable | `ksp-store-api` | public | `0.3.1` | consumer commun |
| 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 |
| 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 |
| retention policy/maintenance worker | job/worker/opérateur futur | hors Store API décisionnel | ultérieur | décide l'éligibilité ; Store applique la transition |
| Concept | Owner candidat/fixé | Visibilité | Introduction | Raison |
|--------------------------------------|-------------------------------|----------------------------|-------------------------------------|------------------------------------------------------------------|
| `RawTransaction` | `ksp-store-api` | public | `0.3.1` | modèle persistant/replayable commun |
| `RawTransactionObservation` | `ksp-store-api` | public | `0.3.1` | acquisition durable distincte du RAW |
| transaction log messages RAW | dans `RawTransaction` | public via modèle RAW | `0.3.1` | font partie de la transaction avant décomposition |
| structural transaction log lines | future couche N2 | hors `0.3.1` | série STRUCTURAL | unités extraites après décomposition |
| `RawAccountState` | `ksp-store-api` | public | `0.3.1` | état canonique commun HTTP/WS/gRPC sous admission stricte |
| `RawAccountObservation` | `ksp-store-api` | public | `0.3.1` | provenance/acquisition de l'état compte |
| `TransactionStatusObservation` | non fixé | absent | reporté | HTTP snapshot, WS transition et Yellowstone update non fusionnés |
| log/status/slot/vote event-only | préférer `ksp-interface-lib` | public passif | future tranche Interface si retenue | échange inter-composants sans persistence Store |
| `RawRetentionState` / tombstone | `ksp-store-api` | public logique | `0.3.1` | cycle de vie RAW backend-agnostic stabilisé |
| processing ledger versionné | future contrat Store commun | hors surface initiale RAW | avec jobs/N2/N3 | preuve durable stage/version/input, pas bool |
| RAW references | `ksp-store-api` | public | `0.3.1` | reads/replay/lineage |
| write outcomes | `ksp-store-api` | public | `0.3.1` | sémantique idempotente commune |
| query/page | `ksp-store-api` | public | `0.3.1` | navigation/replay backend-agnostic |
| health runtime | `ksp-store-lib` | hors `0.3.1` | `0.3.2` à cadrer | état runtime, non requis par les modèles RAW |
| 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 |
| 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 |
| retention policy/maintenance worker | job/worker/opérateur futur | hors Store API décisionnel | ultérieur | décide l'éligibilité ; Store applique la transition |
## 22. Hors scope strict `0.3.1`
@@ -1430,15 +1423,17 @@ La tranche matérialise aussi le résultat distinct `ExpectedStateMismatch` pour
### `pre.008` — Gate technique final
**Statut : préparé par `0.3.1-pre.008`, à fermer par le gate opérateur complet.**
**Statut : PASS opérateur.**
La tranche reste un gate pur : aucun nouveau modèle, capability, test métier, backend, codec, event-only type ou comportement runtime. Elle synchronise uniquement la version workspace et les preuves documentaires du gate final.
Le gate opérateur doit couvrir le workspace complet, les tests Store API, l'ownership Logging et les graphes Cargo. Aucun développement fonctionnel nouveau.
Le gate opérateur a été exécuté après `cargo clean` : audits Rust/Markdown, `cargo check --workspace`, Clippy, tests ciblés de toutes les crates présentes, `cargo test --workspace`, builds Tauri des trois Desk et graphes Cargo sont verts. La commande ciblée initiale `cargo test -p ksp-program-lib` était un nom de package erroné ; `cargo test -p ksp-program-api` a ensuite été exécuté séparément et passe intégralement.
### `pre.009` — Réconciliation documentaire finale
README/USAGE, plan, validation et références durables réellement concernées. Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant.
**Statut : matérialisé par `0.3.1-pre.009`.**
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
@@ -1486,7 +1481,7 @@ ksp-store-api existe seule dans le domaine Store
RawTransaction + observations stables
aucune source partielle ne fabrique un RawTransaction incomplet
logs transactionnels restent dans RawTransaction jusqu'à N2 STRUCTURAL
RawAccountState/observation audités et modèle prévu si compatibilité cross-source prouvée
RawAccountState/observation audités, modèles et capabilities stabilisés sous admission cross-source stricte
TransactionStatusObservation classé explicitement
logsSubscribe/slot/vote classés event-only/Interface, reportés ou rejetés explicitement
RawBlock reste IDEA sans persistence tant qu'un besoin block-level n'est pas démontré
@@ -1496,7 +1491,7 @@ models et capabilities séparés
contrats backend communs stables
backend externe implémentable sans ksp-store-lib
aucun type backend/SQL public
queries/pagination cursorisée sans plafond métier KSPs
queries/pagination cursorisée sans plafond métier KSP
idempotence/conflict semantics explicites
atomic acquisition contract explicite
références durables stables
@@ -1504,6 +1499,7 @@ RawRetentionState/tombstone empêchent le rebackfill normal après purge
force rehydrate reste explicitement distinct
aucun simple processed bool n'est présenté comme preuve suffisante de traitement
future preuve processing versionnée stage/processor/input reste possible
health/readiness runtime et type de wake-up dédié restent explicitement hors `ksp-store-api` `0.3.1`
aucune dépendance PostgreSQL
aucune surface N2 STRUCTURAL/N3 DECODED/N4 DOMAIN implémentée
workspace et graphes entièrement verts