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

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 |