# 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 |