khadhroony-solana-project/docs/validation/018-V0_3_1_STORE_RAW.md

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 :

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 :

ksp-store-api
└── ksp-core-lib
    └── solana-pubkey

Interdits par défaut dans Store API :

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 :

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 :

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 :

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 :

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 :

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 à :

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 :

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