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