366 lines
9.3 KiB
Markdown
366 lines
9.3 KiB
Markdown
<!-- file: deltas/0.3.2/pre.001.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.3.2-pre.001` — audit Store/PostgreSQL, runtime foundation et réconciliation du graphe
|
||
|
||
## 1. Base requise
|
||
|
||
Base directe attendue :
|
||
|
||
```text
|
||
v0.3.1
|
||
workspace.package.version = 0.3.1
|
||
```
|
||
|
||
Sources obligatoires réellement disponibles :
|
||
|
||
```text
|
||
khadhroony-solana-project-v0.3.1.zip
|
||
khadhroony-bot3_v0.5.3-pre.005-fix010.zip
|
||
```
|
||
|
||
La metadata Git n'est pas incluse dans l'archive KSP ; le tag `v0.3.1` ne peut donc pas être interrogé localement. La version Cargo, `deltas/0.3.1/rel.001.md`, le prompt 021, la présence de `ksp-store-api` et l'absence des deux crates runtime concordent avec la base stable requise.
|
||
|
||
Commit attendu :
|
||
|
||
```text
|
||
v0.3.2-pre.001
|
||
```
|
||
|
||
Archive overlay attendue :
|
||
|
||
```text
|
||
ksp-general-0.3.2-pre.001.zip
|
||
```
|
||
|
||
## 2. Objectif
|
||
|
||
Ouvrir `0.3.2` uniquement par le gate prévu :
|
||
|
||
```text
|
||
lecture règles + architecture + 0.3.1
|
||
réaudit kbot3 physique ciblé
|
||
réaudit PostgreSQL/tokio-postgres/pool/TLS/migrations
|
||
brainstorming runtime/backend
|
||
threat model
|
||
dependency graph exact
|
||
Config std.store candidate
|
||
integration test strategy
|
||
sizing + prévision souple
|
||
réconciliation des règles Store contradictoires découvertes
|
||
```
|
||
|
||
Aucune crate runtime, connexion, pool, TLS, migration ou Config Store n'est implémenté dans ce delta.
|
||
|
||
## 3. Divergence stable découverte
|
||
|
||
La base stable avait déjà adopté le backend séparé dans le plan `0.3.1` et les architectures 003/004/005, mais conservait l'ancien modèle dans :
|
||
|
||
```text
|
||
KSP-API-006
|
||
DEP-STORE-002
|
||
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
|
||
```
|
||
|
||
Le prompt 021 demande en plus de relire `DEP-STORE-001..010`, alors que la base ne définissait que `001..008`.
|
||
|
||
La réconciliation livrée fixe :
|
||
|
||
```text
|
||
ksp-store-lib = façade/runtime commune
|
||
ksp-store-postgres-lib = backend physique officiel
|
||
backend -> ksp-store-api
|
||
backend -X-> ksp-store-lib
|
||
consumers ordinaires -> ksp-store-lib
|
||
```
|
||
|
||
`DEP-STORE-009` et `DEP-STORE-010` sont ajoutées pour rendre la frontière normative explicite.
|
||
|
||
## 4. Décisions du gate
|
||
|
||
### PostgreSQL/driver
|
||
|
||
```text
|
||
PostgreSQL minimal supporté : 15
|
||
PostgreSQL de référence : 18.6
|
||
driver : tokio-postgres 0.7.18
|
||
```
|
||
|
||
### Pool
|
||
|
||
```text
|
||
retenu : deadpool-postgres 0.14.x
|
||
rejeté : pool KSP maison sans besoin démontré
|
||
rejeté : bb8-postgres pour cette fondation, ownership de connection task moins adapté au close KSP
|
||
```
|
||
|
||
### TLS
|
||
|
||
```text
|
||
tokio-postgres-rustls 0.14.x
|
||
rustls 0.23
|
||
aws-lc-rs
|
||
native system roots
|
||
modes KSP : Disabled / VerifyFull uniquement
|
||
```
|
||
|
||
### Migrations
|
||
|
||
```text
|
||
moteur KSP privé
|
||
SQL embarqué
|
||
history table ksp_store_schema_migrations
|
||
sentinel version 0
|
||
SHA-256
|
||
advisory transaction lock borné
|
||
run transactionnel
|
||
aucun down automatique
|
||
aucune table RAW métier
|
||
```
|
||
|
||
`refinery 0.9.2` a été audité mais n'est pas retenu.
|
||
|
||
### Config
|
||
|
||
```text
|
||
std.store V1 possédé par ksp-config-lib
|
||
KSP_SECRET_STORE_POSTGRES_URI
|
||
settings typés
|
||
aucun serde_json::Value backend_options
|
||
aucun env/PG*/.pgpass lu par Store/backend
|
||
```
|
||
|
||
### Health
|
||
|
||
Un health/readiness portable minimal est retenu pour distinguer Store construit, prêt et fermé sans exposer pool/URI/SQL.
|
||
|
||
## 5. Graphe cible
|
||
|
||
```text
|
||
ksp-store-lib
|
||
├── ksp-store-api
|
||
├── ksp-logging-lib
|
||
└── [postgres] ksp-store-postgres-lib
|
||
|
||
ksp-store-postgres-lib
|
||
├── ksp-store-api
|
||
├── ksp-logging-lib
|
||
├── tokio
|
||
├── tokio-postgres
|
||
├── deadpool-postgres
|
||
├── tokio-postgres-rustls
|
||
├── rustls
|
||
└── sha2
|
||
```
|
||
|
||
Feature :
|
||
|
||
```text
|
||
default = postgres
|
||
--no-default-features doit compiler
|
||
Postgres connu sans feature -> STORE_BACKEND_NOT_COMPILED avant I/O
|
||
```
|
||
|
||
## 6. Héritage kbot3 ciblé
|
||
|
||
Surfaces relues : ancien `ks-store`, PostgreSQL, migration resources, health, Config et docs Store.
|
||
|
||
Résumé :
|
||
|
||
```text
|
||
REPRENDRE façade intentionnelle, pool/timeout bornés, advisory lock, health, SQL privé
|
||
REDESSINER crates séparées, tokio-postgres, settings typés, TLS, checksum/history, close, errors
|
||
REPORTER 16 tables N1-N3, 240 SQL métier, 79 index, repositories/replay/ledgers
|
||
REJETER SQLx, monolithe façade/backend, backend_options JSON, env direct, erreurs backend brutes
|
||
```
|
||
|
||
Le détail est dans le plan 023.
|
||
|
||
## 7. Threat model
|
||
|
||
Le plan couvre explicitement :
|
||
|
||
```text
|
||
credential leak URI/Debug/error/log
|
||
PG*/.pgpass bypass Config
|
||
connection string hostile
|
||
connection storm/unbounded pool
|
||
hung connect/migration/shutdown
|
||
concurrent migration runners
|
||
modified migration/checksum
|
||
partial migration
|
||
SQL/dynamic identifier injection
|
||
feature/config mismatch
|
||
connection task leaked/dropped
|
||
schema history newer than runtime
|
||
server error echo
|
||
```
|
||
|
||
## 8. PostgreSQL integration strategy
|
||
|
||
Le test `#[ignore]` de `pre.008` lira une URI dédiée depuis stdin, refusera une metadata table préexistante, ne créera aucune table métier et ne détruira ni base ni schema.
|
||
|
||
Il prouvera :
|
||
|
||
```text
|
||
connect >= PostgreSQL 15
|
||
bootstrap initial
|
||
idempotence
|
||
concurrence
|
||
checksum mismatch
|
||
rollback d'un échec injecté
|
||
health ready
|
||
close borné
|
||
cleanup metadata créée par le test
|
||
```
|
||
|
||
La cible de gate est PostgreSQL 18.6.
|
||
|
||
## 9. Sizing recalibré
|
||
|
||
La prévision reste :
|
||
|
||
```text
|
||
pre.001 audit/design/réconciliation normative
|
||
pre.002 scaffold + feature graph
|
||
pre.003 settings + selection/lifecycle contracts
|
||
pre.004 Config std.store
|
||
pre.005 connection + deadpool + Rustls
|
||
pre.006 migration/bootstrap
|
||
pre.007 composition + health/close
|
||
pre.008 PostgreSQL integration réelle
|
||
pre.009 hardening/completeness/dependency matrix
|
||
pre.010 gate technique final
|
||
pre.011 réconciliation documentaire finale
|
||
pre.012 préparation publication minimale
|
||
rel.001 publication stable
|
||
```
|
||
|
||
La release reste clôturable sans absorber `RawTransaction` ou `RawAccountState`.
|
||
|
||
## 10. Fichiers ajoutés
|
||
|
||
```text
|
||
docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md
|
||
docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md
|
||
deltas/0.3.2/pre.001.md
|
||
```
|
||
|
||
## 11. Fichiers modifiés
|
||
|
||
```text
|
||
Cargo.toml
|
||
docs/rules/RULES_KSP.md
|
||
docs/rules/RULES_DEPENDENCIES.md
|
||
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
|
||
```
|
||
|
||
## 12. Fichiers supprimés
|
||
|
||
```text
|
||
aucun
|
||
```
|
||
|
||
## 13. Version Cargo
|
||
|
||
La prerelease non-fix synchronise :
|
||
|
||
```text
|
||
workspace.package.version = 0.3.2-pre.1
|
||
```
|
||
|
||
Aucune crate runtime n'est encore ajoutée ; le changement versionne le gate `pre.001`.
|
||
|
||
## 14. Baseline opérateur `v0.3.1`
|
||
|
||
Le journal opérateur fourni à l'ouverture montre notamment :
|
||
|
||
```text
|
||
cargo fmt --all PASS
|
||
audit Rust général / exports / workspace PASS
|
||
audit Markdown PASS — 186 tables / 138 fichiers
|
||
cargo check --workspace PASS
|
||
cargo clippy --workspace --all-targets PASS
|
||
tests ciblés dont ksp-store-api PASS
|
||
cargo test --workspace PASS
|
||
builds Tauri SOL Prices/Wallet/Config Desk PASS
|
||
cargo tree -p ksp-store-api --edges normal ksp-store-api -> ksp-core-lib
|
||
cargo tree --duplicates exécuté
|
||
```
|
||
|
||
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 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.2
|
||
Markdown table audit: clean (186 tables, 124 files)
|
||
```
|
||
|
||
`cargo` n’est pas installé dans l’environnement de génération. Les commandes suivantes n’ont donc pas été rejouées ici et ne sont pas déclarées PASS :
|
||
|
||
```text
|
||
cargo fmt --all
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets
|
||
```
|
||
|
||
Aucun code Rust n’est modifié par `pre.001`; le seul changement Cargo est `workspace.package.version`. Le baseline opérateur `v0.3.1` 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-lib crate encore absente
|
||
cargo test -p ksp-store-postgres-lib crate encore absente
|
||
PostgreSQL live réservé à pre.008
|
||
pool/TLS connection tests réservés à pre.005+
|
||
migration runtime tests réservés à pre.006+
|
||
```
|
||
|
||
## 17. Questions ouvertes
|
||
|
||
Aucune question architecturale ne bloque `pre.002`.
|
||
|
||
Les détails d'implémentation volontairement réservés aux tranches dédiées sont :
|
||
|
||
```text
|
||
noms Rust exacts des settings/errors
|
||
mapping deadpool exact des timeouts
|
||
construction rustls root store exacte
|
||
DDL final de history metadata
|
||
forme finale health snapshots
|
||
```
|
||
|
||
Ils ne rouvrent pas :
|
||
|
||
```text
|
||
tokio-postgres
|
||
deadpool-postgres
|
||
Rustls VerifyFull/Disabled
|
||
migrations KSP-owned
|
||
backend crate séparée
|
||
Config ownership
|
||
absence de RAW métier en 0.3.2
|
||
```
|
||
|
||
## 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.2
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets
|
||
```
|
||
|
||
Aucun scaffold Store, SQL, migration runtime ou Config `std.store` ne doit être ajouté à ce delta.
|