9.0 KiB
Delta 0.3.1-pre.001 — audit Store API, N1 RAW et split PostgreSQL
1. Base requise
Base directe attendue :
v0.2.14
workspace.package.version = 0.2.14
Sources obligatoires réellement disponibles à l'ouverture :
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 :
v0.3.1-pre.001
Archive overlay attendue :
ksp-general-0.3.1-pre.001.zip
2. Objectif
Ouvrir 0.3.1 uniquement par le gate prévu :
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é :
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 :
RawTransaction
RawTransactionObservation
RawLog
RawLogObservation
RawPayload/provenance/reference/outcome/page communs
Familles prévues mais reportées :
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 :
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 :
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é :
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 :
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 :
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 :
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
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
Cargo.toml
12. Fichiers supprimés
aucun
13. Version Cargo
La prerelease non-fix synchronise :
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 :
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 :
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
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 :
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 :
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 :
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.