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

v0.3.1-pre.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-28 21:31:08 +02:00
parent 3d307be645
commit 29a888d1dc
4 changed files with 1581 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Cargo.toml
View File

@@ -1,12 +1,12 @@
# file: Cargo.toml
# version: 322
# version: 323
[workspace]
resolver = "3"
members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-wallet-lib"]
[workspace.package]
version = "0.2.14"
version = "0.3.1-pre.1"
edition = "2024"
license = "MIT"
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

296
deltas/0.3.1/pre.001.md Normal file
View File

@@ -0,0 +1,296 @@
<!-- file: deltas/0.3.1/pre.001.md -->
<!-- version: 1 -->
# Delta `0.3.1-pre.001` — audit Store API, N1 RAW et split PostgreSQL
## 1. Base requise
Base directe attendue :
```text
v0.2.14
workspace.package.version = 0.2.14
```
Sources obligatoires réellement disponibles à l'ouverture :
```text
archive opérateur khadhroony-solana-project-v0.2.14.zip
archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip
```
La metadata Git n'est pas incluse dans l'archive opérateur ; le tag `v0.2.14` ne peut donc pas être interrogé localement. La version Cargo, `deltas/0.2.14/rel.001.md`, le prompt 020 et la surface Program API publiée concordent avec la base stable attendue.
Commit attendu :
```text
v0.3.1-pre.001
```
Archive overlay attendue :
```text
ksp-general-0.3.1-pre.001.zip
```
## 2. Objectif
Ouvrir `0.3.1` uniquement par le gate prévu :
```text
lecture règles + architecture
audit base KSP stable
audit historique kbot3
audit PostgreSQL/driver actuel
brainstorming N1 RAW
split ksp-store-api / ksp-store-lib
ownership
API candidate
backend extension model
threat model
stratégie de tests
sizing et prévision souple recalibrée
```
Aucune crate Store fonctionnelle n'est ajoutée dans cette livraison.
## 3. Décision de scope majeure
Le scope du prompt initial est volontairement réduit et scindé :
```text
0.3.1 = ksp-store-api uniquement
0.3.2 = ksp-store-lib PostgreSQL via tokio-postgres
```
`ksp-store-api` possédera le modèle objet/struct commun et les opérations backend-agnostic. Les représentations internes, rows, requêtes, migrations, pools et transactions SQL seront invisibles aux consumers.
Une future implémentation alternative, par exemple `ksp-store-mysql-lib`, dépendra directement de `ksp-store-api` et non de `ksp-store-lib`.
La composition/configuration choisira l'implémentation liée au host puis fournira la même façade `Store` aux consumers.
Le `ROADMAP.md` stable contient encore l'ancienne prévision combinée. Il n'est pas modifié dans cette tranche et sera réconcilié dans la lane de préparation de publication conformément au workflow KSP.
## 4. N1 RAW retenu
Le niveau N1/D1 est défini comme acquisition persistée/replayable.
Surface initiale `0.3.1` :
```text
RawTransaction
RawTransactionObservation
RawLog
RawLogObservation
RawPayload/provenance/reference/outcome/page communs
```
Familles prévues mais reportées :
```text
RawAccount
RawBlock
RawSlot/updates si besoin durable distinct
autres acquisitions justifiées ultérieurement
```
HTTP, WebSocket et gRPC sont des moyens d'acquisition/provenance, pas des familles RAW séparées.
Le RAW transaction devra pouvoir être transformé ultérieurement en normalisation Solana générique (actuellement nommée CORE/D2), puis décomposé en instructions top-level et CPI indépendantes afin qu'un decoder absent/Unsupported n'empêche pas le traitement du reste.
## 5. API/backend model
Décisions candidates :
```text
Store = façade consumer commune
StoreBackend = contrat d'implémentation externe object-safe
capabilities = StoreHealth + RawTransactionStore + RawLogStore
async = StoreFuture<'a, T> boxed KSP-owned par défaut
atomicité = opérations métier persist_*_acquisition
transaction SQL handle public = interdit
page = 100 défaut / 500 max / cursor opaque borné
```
Sémantique d'idempotence :
```text
nouvelle clé -> Inserted
même clé + même contenu -> AlreadyPresent
même clé + contenu divergent -> Error Conflict
```
Aucun `has_*` n'est requis avant write.
## 6. Héritage kbot3
L'archive historique a été extraite et les surfaces Store prioritaires réellement relues.
Le Store historique comporte 16 tables N1-N3, 240 ressources SQL atomiques et 79 index attendus. La séparation façade/PostgreSQL, les observations, la pagination bornée et l'idempotence sont réutilisables conceptuellement, mais les contrats N2/N3 et la représentation physique ne sont pas repris.
Résumé :
```text
REPRENDRE séparation façade/backend, health portable, repository capabilities, pagination bornée, observations, idempotence
REDESSINER StoreOpenOptions, raw DTO/entities, write semantics, diagnostics, Config Store
REPORTER schema/migrations/indexes, raw table physique, replay processing, CORE, DECODE, materialization, processing ledger
REJETER maintenance destructive publique, JSON backend options opaque, PK SQL comme identité API, monolithe N1/N2/N3
```
La matrice détaillée est dans `docs/plans/022-V0_3_1_STORE_RAW_PLAN.md`.
## 7. Audit externe
Audit actuel au 28 août 2026 :
```text
PostgreSQL 18.6 — stable courant, 13 août 2026
tokio-postgres 0.7.18 — stable courant, 12 juin 2026
Rust 2024, MSRV 1.85
prepared statements / transactions / COPY / async pipelined supportés
```
Décision opérateur : `tokio-postgres` sera le driver interne du backend PostgreSQL de référence dans `0.3.2`.
Aucune dependency PostgreSQL n'est ajoutée dans `0.3.1`.
## 8. Dependency graph `0.3.1`
Cible :
```text
ksp-store-api
└── ksp-core-lib
```
`ksp-interface-lib`, serde, chrono, tokio et toute crate DB restent absents tant qu'un usage public réel ne les justifie pas.
## 9. Sizing recalibré
Prévision active :
```text
pre.001 audit/design/split
pre.002 scaffold ksp-store-api
pre.003 primitives RAW + transaction
pre.004 raw logs + extensibilité N1
pre.005 backend contract + Store facade + external canary
pre.006 queries/pagination/outcomes/notification reference
pre.007 adversarial/API hardening + completeness
pre.008 gate technique final
pre.009 réconciliation documentaire
pre.010 préparation de publication minimale
rel.001 publication stable
```
Le futur `0.3.2` ouvre `ksp-store-lib` PostgreSQL/`tokio-postgres`.
## 10. Fichiers ajoutés
```text
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
docs/validation/018-V0_3_1_STORE_RAW.md
deltas/0.3.1/pre.001.md
```
## 11. Fichiers modifiés
```text
Cargo.toml
```
## 12. Fichiers supprimés
```text
aucun
```
## 13. Version Cargo
La prerelease non-fix synchronise :
```text
workspace.package.version = 0.3.1-pre.1
```
Aucune crate Store n'existe encore ; le changement Cargo identifie uniquement le gate `pre.001` conformément au workflow.
## 14. Validations de baseline
Le journal opérateur fourni à l'ouverture sur `v0.2.14` montre :
```text
cargo fmt --all PASS
audit Rust général / exports / workspace PASS
audit Markdown PASS — 175 tables / 128 fichiers
cargo check --workspace PASS
cargo clippy --workspace --all-targets PASS
cargo test --workspace PASS
```
Les smokes live opt-in restent ignorés comme prévu par leurs contrats.
Cette preuve de base ne remplace pas le gate après application de `pre.001`.
## 15. Validations après application
Dans l'environnement de génération du présent overlay, les contrôles statiques suivants ont été réellement exécutés après modification :
```text
python3 scripts/audit_rust_workspace_rules.py
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
Markdown table audit: clean (184 tables, 121 files)
```
`cargo` n'est pas installé dans l'environnement de génération utilisé pour préparer l'archive. `cargo fmt --all`, `cargo check --workspace` et `cargo clippy --workspace --all-targets` n'ont donc pas été rejoués ici et ne sont pas déclarés PASS. Le baseline opérateur `v0.2.14` fourni reste vert, mais ne remplace pas le gate opérateur après application.
## 16. Validations non requises dans cette tranche
```text
cargo test -p ksp-store-api crate encore absente
cargo tree -p ksp-store-api crate encore absente
PostgreSQL live backend reporté à 0.3.2
migration/schema tests backend reporté à 0.3.2
```
## 17. Questions ouvertes
Aucune question architecturale ne bloque `pre.002`.
Restent volontairement à stabiliser par les tranches de code :
```text
nom exact des wrappers d'identité RAW
format_id/version concret du premier RawPayload transaction
bornes finales payload/provenance
identité déterministe exacte d'un RawLog
forme finale StoreFuture/backend traits
référence notification introduite en pre.006 ou reportée si insuffisamment stable
```
Ces questions ne remettent pas en cause :
```text
Store API seule en 0.3.1
PostgreSQL/tokio-postgres en 0.3.2
modèle public commun backend-agnostic
transaction + logs comme premières familles N1
```
## 18. Application et validation opérateur
Après application de l'overlay :
```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
cargo check --workspace
cargo clippy --workspace --all-targets
```
Aucun scaffold Store, SQL, migration ou changement Config ne doit être ajouté à ce delta.

1015
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md Normal file
View File

File diff suppressed because it is too large Load Diff

268
docs/validation/018-V0_3_1_STORE_RAW.md Normal file
View File

@@ -0,0 +1,268 @@
<!-- file: docs/validation/018-V0_3_1_STORE_RAW.md -->
<!-- version: 1 -->
# Validation `0.3.1` — Store API RAW foundation
## 1. Objet
Cette matrice est ouverte par `0.3.1-pre.001`. Elle valide désormais **`ksp-store-api` uniquement** ; l'implémentation PostgreSQL `ksp-store-lib` a été déplacée vers `0.3.2` par décision opérateur pendant le gate de brainstorming.
Le scope concret N1 initial est :
```text
RawTransaction + observation
RawLog + observation
provenance/références/outcomes/queries communs
façade Store + contrat backend externe
```
Les autres familles RAW restent extensibles et reportées jusqu'à audit réel de leur besoin.
## 2. Gate `pre.001`
| Critère | Statut | Preuve |
|----------------------------|---------|-------------------------------------------------------------------------------|
| base stable `0.2.14` | PASS | Cargo `0.2.14`, `rel.001` et prompt 020 présents |
| metadata Git/tag | N/A | archive opérateur sans metadata Git exploitable |
| baseline opérateur | PASS | audits, check, Clippy et workspace tests fournis verts sur `v0.2.14` |
| `ksp-program-api` stable | PASS | façade instruction-only relue |
| `ksp-store-api` absent | PASS | aucun répertoire Store API sur la base |
| `ksp-store-lib` absent | PASS | aucun répertoire Store lib sur la base |
| archive kbot3 disponible | PASS | archive historique extraite et auditée |
| règles Store/API relues | PASS | règles KSP/Dependencies/Workflow prescrites relues |
| architecture durable relue | PASS | graph/store/acquisition relus, D1/D2 séparés |
| matrice héritage kbot3 | PASS | `REPRENDRE / REDESSINER / REPORTER / REJETER` dans le plan 022 |
| audit externe PostgreSQL | PASS | PostgreSQL 18.6 courant au 28 août 2026 |
| audit driver futur | PASS | `tokio-postgres 0.7.18`, Rust 2024/MSRV 1.85, async/transactions/COPY audités |
| split version | PASS | `0.3.1 = Store API`, `0.3.2 = Store lib PostgreSQL` |
| dependency graph `0.3.1` | PASS | cible Core-only |
| modèle backend commun | PASS | API object/struct commune, rows backend privées |
| inventaire RAW initial | PASS | transaction + logs + observations |
| autres RAW | REPORTÉ | account/block/slot ajoutés seulement sur besoin audité |
| provenance | PASS | provider/protocol/origin/timing sûrs, aucun secret |
| idempotence | PASS | atomic put, `Inserted/AlreadyPresent`, divergence = conflict |
| API candidate | PASS | façade Store + capabilities object-safe + external backend |
| public SQL transaction | ABSENT | invariants atomiques exprimés par opérations métier |
| pagination | PASS | 100 par défaut / 500 max / cursor opaque borné |
| notification ownership | PASS | référence RAW KSP-owned, mécanisme hors scope |
| D2/CORE persistence | ABSENT | explicitement hors `0.3.1` |
| DECODE/SPECIALIZED | ABSENT | explicitement hors `0.3.1` |
| schema PostgreSQL candidat | REPORTÉ | déplacé intégralement à `0.3.2` par split API/backend |
| migration policy | REPORTÉ | responsabilité `ksp-store-lib` `0.3.2` |
| PostgreSQL live gate | REPORTÉ | aucun backend DB dans `0.3.1`; gate obligatoire à définir en `0.3.2` |
| threat model | PASS | modèle hostile/API/backend couvert dans plan 022 |
| stratégie de tests | PASS | unit/public/external/firewall/completeness, aucun PostgreSQL live |
| sizing | PASS | dix prereleases courtes + lanes fermeture séparées |
## 3. Décisions structurelles à prouver par le code
| Contrat | Décision `pre.001` | Gate futur |
|-----------------------------|-------------------------------------------------------------------|-------------------------------|
| crate `ksp-store-api` | seule crate Store créée en `0.3.1` | `pre.002` |
| dépendance normale | `ksp-core-lib` uniquement par défaut | `pre.002` |
| backend PostgreSQL | absent de `0.3.1` | completeness `pre.007` |
| `RawPayload` | KSP-owned, source-independent, versionné, borné, Debug sans bytes | `pre.003` |
| transaction identity | réseau + signature logique, jamais PK SQL | `pre.003` |
| `RawTransaction` | objet persistant commun replayable | `pre.003` |
| `RawTransactionObservation` | acquisition/provenance séparée du RAW | `pre.003` |
| `RawLog` | famille N1 distincte avec ordering préservé | `pre.004` |
| `RawLogObservation` | provenance séparée du log canonique | `pre.004` |
| future RAW families | extensibles sans JSON universel | `pre.004` / `pre.007` |
| `StoreFuture<'a, T>` | future object-safe KSP-owned, sans `async-trait` par défaut | `pre.005` |
| backend trait | implémentable hors workspace, `Send + Sync` | `pre.005` |
| façade `Store` | même consumer surface quel que soit backend injecté | `pre.005` |
| transaction handle | aucun handle SQL/backend public | `pre.005` |
| atomic acquisition | méthode métier RAW + observation all-or-nothing | `pre.005` / `pre.006` |
| write outcome | `Inserted / AlreadyPresent`; divergence = `Err Conflict` | `pre.006` |
| `PageRequest` | borné, default 100, max 500 | `pre.006` |
| cursor | opaque, borné, aucun SQL/backend contract visible | `pre.006` |
| notification reference | compacte, durable, payload non dupliqué | `pre.006` ou report explicite |
| health | portable et sanitisé | `pre.005` / `pre.006` |
## 4. Dependency firewall final attendu
Le graphe final `0.3.1` doit rester :
```text
ksp-store-api
└── ksp-core-lib
└── solana-pubkey
```
Interdits par défaut dans Store API :
```text
ksp-store-lib
ksp-onchain-transport-lib
ksp-offchain-transport-lib
ksp-interface-lib sans usage de type réel
ksp-program-api
ksp-program-lib
ksp-materializer-api
ksp-config-lib
ksp-logging-lib
ksp-wallet-lib
tokio-postgres
sqlx
serde / serde_json
chrono
tokio
async-trait
Tauri
```
Toute divergence exige un usage public réel et une révision du plan.
## 5. Matrice N1 initiale
| Famille | `0.3.1` | Identité logique candidate | Replay couvert | Provenance |
|-------------|---------|-----------------------------------------------------------|---------------------------------------------------------------------------|-------------------------------|
| transaction | IN | network + signature | future décomposition générique Solana complète couverte par le format RAW | observations séparées |
| logs | IN | identité transaction/slot + clé déterministe à stabiliser | ordre et contenu log nécessaires à replay/inspection | observations séparées |
| account | REPORTÉ | pubkey + context/slot/version à auditer | futur compte RAW replayable | prévu par primitives communes |
| block | REPORTÉ | network + slot/block identity | futur backfill/block replay | prévu par primitives communes |
| slot/update | REPORTÉ | sémantique exacte à auditer | seulement si un fait durable distinct est utile | prévu par primitives communes |
## 6. Frontière N1 -> D2
`0.3.1` doit préserver sans implémenter :
```text
RawTransaction
-> generic Solana normalization
-> transaction/message
-> account keys
-> top-level instructions
-> CPI/inner instructions
-> logs/meta/balances/return data
-> traitement individuel ultérieur
```
Canari négatif durable :
```text
ksp-store-api -X-> ksp-program-api
```
Le terme `CORE` reste le nom architectural actuel de D2 mais peut être renommé avant ouverture de cette couche sans modifier la séparation fonctionnelle.
## 7. Extensibilité backend
Le canari externe doit démontrer :
```text
crate/test consumer externe
-> dépend de ksp-store-api
-> définit son propre backend mémoire
-> implémente le contrat public
-> construit la façade Store
-> écrit et relit transaction/log via les mêmes fonctions
-X-> ksp-store-lib
-X-> PostgreSQL
```
L'implémentation PostgreSQL officielle de `0.3.2` devra satisfaire la même suite de conformance.
## 8. Threat/API gates futurs
| Gate | Attendu | Statut initial |
|---------------------------------|-----------------------------------------------------|-----------------------|
| oversized RAW payload | rejet avant stockage/copied allocation pathologique | `pre.003` |
| payload Debug | aucun bytes brut | `pre.003` |
| hostile provenance text | borné/trim/control policy explicite | `pre.003` |
| duplicate same content | outcome `AlreadyPresent` | `pre.006` |
| duplicate divergent content | erreur Conflict stable | `pre.006` |
| check-then-insert | absent de l'API publique | `pre.005` |
| partial transaction+observation | interdit par atomic acquisition contract | `pre.005` |
| page limit 0/>500 | rejet | `pre.006` |
| cursor oversize | rejet | `pre.006` |
| SQL/backend cursor leak | absent | `pre.006` / `pre.007` |
| provider secret leak | absent du modèle public | `pre.003` / `pre.007` |
| backend row/public type | absent | `pre.007` |
| async runtime dependency | aucune dependency Tokio dans API par défaut | `pre.005` / `pre.007` |
| external backend | compile et fonctionne sans Store lib | `pre.005` |
| closed RAW enum | future family ajoutable | `pre.004` / `pre.007` |
| D2/D3/D4 creep | aucune surface | `pre.007` |
## 9. Gates de fermeture prévus
### Gate technique final `pre.008`
Commandes de référence :
```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-store-api
cargo test -p ksp-logging-lib --test ownership
cargo test --workspace
cargo tree -p ksp-store-api --edges normal
cargo tree --duplicates
```
### Réconciliation documentaire `pre.009`
Doit fermer :
```text
crates/ksp-store-api/README.md
crates/ksp-store-api/USAGE.md
plan 022
validation 018
indexes/références durables concernées
```
Sans `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant.
### Préparation de publication `pre.010`
Doit rester limitée à :
```text
Cargo.toml
CHANGELOG.md
ROADMAP.md
prompts/021-V0_3_2_START_PROMPT.md
delta pre.010
```
Le `ROADMAP.md` y réconcilie la nouvelle séquence `0.3.1 API -> 0.3.2 PostgreSQL`.
## 10. PostgreSQL reporté à `0.3.2`
Aucun gate PostgreSQL live n'est demandé à `0.3.1`.
Le prochain prompt devra transformer les invariants API en backend de référence et prévoir :
```text
tokio-postgres
settings programmatiques issus de Config/composition
pool/TLS audités
migrations KSP-owned
schema conformance
write/read round-trip des modèles API
idempotence/race
atomic rollback
pagination
error/DSN redaction
PostgreSQL réel opt-in puis gate final obligatoire
```
## 11. État initial des tranches
| Tranche | Objet | État |
|-----------|---------------------------------|-----------------------|
| `pre.001` | audit/design/split API/backend | PRÊT après gate local |
| `pre.002` | scaffold Store API | À FAIRE |
| `pre.003` | primitives + RawTransaction | À FAIRE |
| `pre.004` | RawLog + extensibilité N1 | À FAIRE |
| `pre.005` | backend contract + façade Store | À FAIRE |
| `pre.006` | queries/outcomes/notification | À FAIRE |
| `pre.007` | adversarial/completeness | À FAIRE |
| `pre.008` | gate technique final | À FAIRE |
| `pre.009` | réconciliation documentaire | À FAIRE |
| `pre.010` | préparation publication | À FAIRE |
| `rel.001` | stable | À FAIRE |