297 lines
9.0 KiB
Markdown
297 lines
9.0 KiB
Markdown
<!-- file: deltas/0.3.1/pre.001.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# 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.
|