269 lines
15 KiB
Markdown
269 lines
15 KiB
Markdown
<!-- 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 |
|