From 153014be9d3e0a24762345b00e7a1a7dfddf8039 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sat, 29 Aug 2026 16:48:16 +0200 Subject: [PATCH] v0.3.2-pre.002 --- Cargo.toml | 6 +- crates/ksp-store-lib/Cargo.toml | 19 ++ crates/ksp-store-lib/src/constants.rs | 7 + crates/ksp-store-lib/src/lib.rs | 21 ++ .../tests/dependency_boundary.rs | 52 ++++ crates/ksp-store-postgres-lib/Cargo.toml | 14 + .../ksp-store-postgres-lib/src/constants.rs | 7 + crates/ksp-store-postgres-lib/src/lib.rs | 21 ++ .../tests/dependency_boundary.rs | 35 +++ deltas/0.3.2/pre.002.md | 244 ++++++++++++++++++ ...3-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md | 15 +- .../019-V0_3_2_STORE_POSTGRES_FOUNDATION.md | 20 +- 12 files changed, 452 insertions(+), 9 deletions(-) create mode 100644 crates/ksp-store-lib/Cargo.toml create mode 100644 crates/ksp-store-lib/src/constants.rs create mode 100644 crates/ksp-store-lib/src/lib.rs create mode 100644 crates/ksp-store-lib/tests/dependency_boundary.rs create mode 100644 crates/ksp-store-postgres-lib/Cargo.toml create mode 100644 crates/ksp-store-postgres-lib/src/constants.rs create mode 100644 crates/ksp-store-postgres-lib/src/lib.rs create mode 100644 crates/ksp-store-postgres-lib/tests/dependency_boundary.rs create mode 100644 deltas/0.3.2/pre.002.md diff --git a/Cargo.toml b/Cargo.toml index 1f48f4c..41bba61 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 331 +# version: 332 [workspace] resolver = "3" -members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-wallet-lib"] +members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.3.2-pre.1" +version = "0.3.2-pre.2" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/crates/ksp-store-lib/Cargo.toml b/crates/ksp-store-lib/Cargo.toml new file mode 100644 index 0000000..5ee26aa --- /dev/null +++ b/crates/ksp-store-lib/Cargo.toml @@ -0,0 +1,19 @@ +# file: crates/ksp-store-lib/Cargo.toml +# version: 1 + +[package] +name = "ksp-store-lib" +version.workspace = true +edition.workspace = true +repository.workspace = true + +[features] +default = ["postgres"] +postgres = ["dep:ksp-store-postgres-lib"] + +[dependencies] +ksp-store-api = { path = "../ksp-store-api" } +ksp-store-postgres-lib = { path = "../ksp-store-postgres-lib", optional = true } + +[lints] +workspace = true diff --git a/crates/ksp-store-lib/src/constants.rs b/crates/ksp-store-lib/src/constants.rs new file mode 100644 index 0000000..de4a4af --- /dev/null +++ b/crates/ksp-store-lib/src/constants.rs @@ -0,0 +1,7 @@ +// file: crates/ksp-store-lib/src/constants.rs +// version: 1 + +//! Store facade-owned constants. + +/// Owning tracing target reserved for events emitted by the common Store runtime facade. +pub(crate) const TRACING_TARGET: &str = "ksp-store-lib"; diff --git a/crates/ksp-store-lib/src/lib.rs b/crates/ksp-store-lib/src/lib.rs new file mode 100644 index 0000000..643d636 --- /dev/null +++ b/crates/ksp-store-lib/src/lib.rs @@ -0,0 +1,21 @@ +// file: crates/ksp-store-lib/src/lib.rs +// version: 1 + +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +//! Common backend-neutral Store runtime facade for KSP. +//! +//! `0.3.2-pre.002` establishes only the crate and Cargo feature graph. Runtime +//! settings, backend selection, lifecycle, error mapping and API reexports are +//! introduced by later prereleases of `0.3.2`. +//! +//! The default `postgres` feature compiles the official PostgreSQL backend as +//! an optional implementation dependency. No backend implementation type is +//! part of this crate's public surface. + +mod constants; + +/// Crate-owned tracing target reserved for later Store runtime behavior. +pub(crate) use self::constants::TRACING_TARGET; diff --git a/crates/ksp-store-lib/tests/dependency_boundary.rs b/crates/ksp-store-lib/tests/dependency_boundary.rs new file mode 100644 index 0000000..4eecf24 --- /dev/null +++ b/crates/ksp-store-lib/tests/dependency_boundary.rs @@ -0,0 +1,52 @@ +// file: crates/ksp-store-lib/tests/dependency_boundary.rs +// version: 1 + +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +//! Cargo-feature and dependency-boundary canaries for the common Store runtime scaffold. + +#[test] +fn pre_002_manifest_owns_default_postgres_feature_and_optional_backend_edge() { + let manifest = include_str!("../Cargo.toml"); + assert!(manifest.contains("default = [\"postgres\"]")); + assert!(manifest.contains("postgres = [\"dep:ksp-store-postgres-lib\"]")); + assert!(manifest.contains("ksp-store-api = { path = \"../ksp-store-api\" }")); + assert!(manifest.contains("ksp-store-postgres-lib = { path = \"../ksp-store-postgres-lib\", optional = true }")); + for forbidden in [ + "ksp-config-lib", + "ksp-materializer", + "ksp-program", + "ksp-onchain-transport-lib", + "ksp-offchain-transport-lib", + "tokio-postgres", + "deadpool-postgres", + "rustls", + ] { + assert!(!manifest.contains(forbidden), "forbidden pre.002 Store facade dependency detected: {forbidden}"); + } + return; +} + +#[test] +fn pre_002_scaffold_keeps_backend_types_and_future_runtime_surface_private() { + let crate_root = include_str!("../src/lib.rs"); + assert!(crate_root.contains("mod constants;")); + assert!(crate_root.contains("pub(crate) use self::constants::TRACING_TARGET;")); + for forbidden in [ + "pub mod ", + "pub use ksp_store_postgres_lib", + "StoreSettings", + "StoreBackendSettings", + "PostgresStoreSettings", + "pub struct Store", + "tokio_postgres", + "deadpool_postgres", + ] { + assert!(!crate_root.contains(forbidden), "forbidden pre.002 Store facade surface detected: {forbidden}"); + } + let constants = include_str!("../src/constants.rs"); + assert!(constants.contains("pub(crate) const TRACING_TARGET: &str = \"ksp-store-lib\";")); + return; +} diff --git a/crates/ksp-store-postgres-lib/Cargo.toml b/crates/ksp-store-postgres-lib/Cargo.toml new file mode 100644 index 0000000..1122639 --- /dev/null +++ b/crates/ksp-store-postgres-lib/Cargo.toml @@ -0,0 +1,14 @@ +# file: crates/ksp-store-postgres-lib/Cargo.toml +# version: 1 + +[package] +name = "ksp-store-postgres-lib" +version.workspace = true +edition.workspace = true +repository.workspace = true + +[dependencies] +ksp-store-api = { path = "../ksp-store-api" } + +[lints] +workspace = true diff --git a/crates/ksp-store-postgres-lib/src/constants.rs b/crates/ksp-store-postgres-lib/src/constants.rs new file mode 100644 index 0000000..63ad06c --- /dev/null +++ b/crates/ksp-store-postgres-lib/src/constants.rs @@ -0,0 +1,7 @@ +// file: crates/ksp-store-postgres-lib/src/constants.rs +// version: 1 + +//! PostgreSQL Store backend-owned constants. + +/// Owning tracing target reserved for events emitted by the PostgreSQL Store backend. +pub(crate) const TRACING_TARGET: &str = "ksp-store-postgres-lib"; diff --git a/crates/ksp-store-postgres-lib/src/lib.rs b/crates/ksp-store-postgres-lib/src/lib.rs new file mode 100644 index 0000000..ec93df5 --- /dev/null +++ b/crates/ksp-store-postgres-lib/src/lib.rs @@ -0,0 +1,21 @@ +// file: crates/ksp-store-postgres-lib/src/lib.rs +// version: 1 + +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +//! Official PostgreSQL backend implementation scaffold for KSP Store. +//! +//! `0.3.2-pre.002` establishes only the backend crate boundary. PostgreSQL +//! driver, pooling, TLS, SQL, migrations and health behavior are intentionally +//! absent until their dedicated prereleases. +//! +//! This crate depends on `ksp-store-api` and never on `ksp-store-lib`, which +//! keeps backend implementation ownership acyclic and reusable behind the +//! common facade. + +mod constants; + +/// Crate-owned tracing target reserved for later PostgreSQL backend behavior. +pub(crate) use self::constants::TRACING_TARGET; diff --git a/crates/ksp-store-postgres-lib/tests/dependency_boundary.rs b/crates/ksp-store-postgres-lib/tests/dependency_boundary.rs new file mode 100644 index 0000000..3f18d77 --- /dev/null +++ b/crates/ksp-store-postgres-lib/tests/dependency_boundary.rs @@ -0,0 +1,35 @@ +// file: crates/ksp-store-postgres-lib/tests/dependency_boundary.rs +// version: 1 + +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +//! Dependency-boundary canaries for the PostgreSQL Store backend scaffold. + +#[test] +fn pre_002_backend_depends_on_store_api_without_reverse_facade_edge() { + let manifest = include_str!("../Cargo.toml"); + assert!(manifest.contains("ksp-store-api = { path = \"../ksp-store-api\" }")); + for forbidden in ["ksp-store-lib", "ksp-config-lib", "ksp-materializer", "ksp-program", "ksp-onchain-transport-lib", "ksp-offchain-transport-lib"] { + assert!(!manifest.contains(forbidden), "forbidden PostgreSQL backend dependency detected: {forbidden}"); + } + return; +} + +#[test] +fn pre_002_backend_does_not_advance_connection_pool_tls_or_migrations() { + let manifest = include_str!("../Cargo.toml"); + for forbidden in ["tokio", "tokio-postgres", "deadpool-postgres", "tokio-postgres-rustls", "rustls", "sha2"] { + assert!(!manifest.contains(forbidden), "premature PostgreSQL runtime dependency detected: {forbidden}"); + } + let crate_root = include_str!("../src/lib.rs"); + assert!(crate_root.contains("mod constants;")); + assert!(crate_root.contains("pub(crate) use self::constants::TRACING_TARGET;")); + for forbidden in ["pub mod ", "pub struct", "pub enum", "pub trait", "tokio_postgres", "deadpool_postgres", "mod migration", "SELECT ", "CREATE TABLE"] { + assert!(!crate_root.contains(forbidden), "premature PostgreSQL backend surface detected: {forbidden}"); + } + let constants = include_str!("../src/constants.rs"); + assert!(constants.contains("pub(crate) const TRACING_TARGET: &str = \"ksp-store-postgres-lib\";")); + return; +} diff --git a/deltas/0.3.2/pre.002.md b/deltas/0.3.2/pre.002.md new file mode 100644 index 0000000..d59ec5e --- /dev/null +++ b/deltas/0.3.2/pre.002.md @@ -0,0 +1,244 @@ + + + +# Delta `0.3.2-pre.002` — scaffold Store runtime/PostgreSQL et feature graph + +## 1. Base requise + +```text +0.3.2-pre.001 +``` + +Le gate opérateur de `pre.001` est fourni vert : + +```text +cargo fmt --all PASS +audit Rust général / exports / workspace PASS +audit Markdown PASS — 186 tables / 124 files +cargo check --workspace PASS +cargo clippy --workspace --all-targets PASS +``` + +## 2. Objectif + +Créer uniquement les deux crates runtime prévues par le plan `0.3.2` et matérialiser le feature graph PostgreSQL sans avancer les settings, la Config Store, la connexion, le pool, TLS, les migrations ou les vertical slices RAW. + +Crates créées : + +```text +ksp-store-lib +ksp-store-postgres-lib +``` + +## 3. Version + +Le workspace passe à : + +```text +0.3.2-pre.2 +``` + +Les deux crates sont ajoutées aux membres du workspace. + +## 4. Graphe matérialisé + +```text +ksp-store-lib +├── ksp-store-api +└── [default feature postgres] + └── ksp-store-postgres-lib + └── ksp-store-api +``` + +Invariants : + +```text +ksp-store-postgres-lib -X-> ksp-store-lib +ksp-store-lib -X-> Config/Transport/Program/Materializer +ksp-store-postgres-lib -X-> Config/Transport/Program/Materializer +``` + +Feature exacte : + +```toml +[features] +default = ["postgres"] +postgres = ["dep:ksp-store-postgres-lib"] +``` + +`ksp-store-postgres-lib` reste une optional dependency de la façade afin que : + +```text +cargo check -p ksp-store-lib --no-default-features +``` + +puisse compiler sans backend PostgreSQL. + +## 5. Dépendances volontairement différées + +`pre.002` n'ajoute pas encore : + +```text +ksp-logging-lib +tokio +tokio-postgres +deadpool-postgres +tokio-postgres-rustls +rustls +sha2 +``` + +Ce n'est pas une remise en cause du graphe cible du plan 023. Aucun comportement de production ne consomme encore ces crates dans le scaffold ; les ajouter maintenant violerait le contrat selon lequel une dépendance de package correspond à un usage réel. + +Le séquencement reste : + +```text +ksp-logging-lib façade lors du premier comportement Store réel +ksp-logging-lib backend lors du premier comportement PostgreSQL réel +tokio/driver/pool/TLS pre.005 +sha2 pre.006 +``` + +Les deux crates possèdent cependant dès maintenant leur `src/constants.rs` et le `TRACING_TARGET` crate-owned attendu, sans émission de log artificielle. + +## 6. Surface Rust + +`ksp-store-lib` reste un scaffold sans API runtime publique. Il ne matérialise pas encore : + +```text +Store +StoreSettings +StoreBackendSettings +PostgresStoreSettings +StoreBackendKind +errors Store runtime +reexports ksp-store-api +``` + +Ces éléments restent réservés à `pre.003`. + +`ksp-store-postgres-lib` n'expose encore aucun type backend public et ne contient aucun driver, pool, SQL, migration ou health runtime. + +Aucun `pub mod` n'est introduit. + +## 7. Canaris ajoutés + +### `ksp-store-lib` + +`tests/dependency_boundary.rs` vérifie : + +```text +default feature postgres exact +optional backend dependency exacte +façade -> ksp-store-api +absence Config/Transport/Program/Materializer +absence driver/pool/TLS prématurés +absence de settings/Store/backend types publics en pre.002 +TRACING_TARGET possédé par constants.rs +``` + +### `ksp-store-postgres-lib` + +`tests/dependency_boundary.rs` vérifie : + +```text +backend -> ksp-store-api +absence backend -> ksp-store-lib +absence Config/Transport/Program/Materializer +absence Tokio/tokio-postgres/Deadpool/Rustls/SHA-256 +absence SQL/migration/runtime surface prématurée +TRACING_TARGET possédé par constants.rs +``` + +## 8. Documentation mise à jour + +```text +docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md +docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md +``` + +Le plan marque le scaffold comme matérialisé et précise le staging des dépendances runtime. La validation conserve les critères Cargo en `TODO` tant que le gate opérateur de cette tranche n'a pas été fourni. + +## 9. Fichiers ajoutés + +```text +crates/ksp-store-lib/Cargo.toml +crates/ksp-store-lib/src/constants.rs +crates/ksp-store-lib/src/lib.rs +crates/ksp-store-lib/tests/dependency_boundary.rs +crates/ksp-store-postgres-lib/Cargo.toml +crates/ksp-store-postgres-lib/src/constants.rs +crates/ksp-store-postgres-lib/src/lib.rs +crates/ksp-store-postgres-lib/tests/dependency_boundary.rs +deltas/0.3.2/pre.002.md +``` + +## 10. Fichiers modifiés + +```text +Cargo.toml +docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md +docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md +``` + +## 11. Fichiers supprimés + +```text +aucun +``` + +## 12. Validations exécutées dans l'environnement de génération + +```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, 125 files) +``` + +Une validation statique complémentaire des manifests/features confirme également le graphe exact attendu et les deux canaris de frontière ont été rejoués par équivalent textuel dans l’environnement sans Cargo. + +## 13. Validations opérateur requises + +`cargo`, `rustc` et `rustfmt` ne sont pas disponibles dans l'environnement de génération. Après application : + +```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 +cargo test -p ksp-store-api +cargo test -p ksp-store-lib +cargo test -p ksp-store-postgres-lib +cargo check -p ksp-store-lib --no-default-features +cargo tree -p ksp-store-lib --edges normal +cargo tree -p ksp-store-lib -e features +cargo tree -p ksp-store-postgres-lib --edges normal +``` + +Une commande non exécutée n'est pas déclarée PASS. + +## 14. Hors scope confirmé + +```text +StoreSettings / backend selection runtime +STORE_BACKEND_NOT_COMPILED +Config std.store +URI/secrets Store +connexion PostgreSQL +pool Deadpool +TLS Rustls +migrations/bootstrap +health/readiness runtime +SQL métier +RawTransaction PostgreSQL +RawAccountState PostgreSQL +``` + +## 15. Suite + +`0.3.2-pre.003` matérialise les settings backend-neutral, l'identité/sélection de backend, les erreurs stables de façade et le lifecycle contract `Store` sans encore ouvrir la connexion PostgreSQL lourde. diff --git a/docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md b/docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md index a327c07..c982cfa 100644 --- a/docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md +++ b/docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md @@ -1,5 +1,5 @@ - + # Plan `0.3.2` — Store/PostgreSQL runtime foundation @@ -882,6 +882,19 @@ Livrer le présent plan, la matrice validation, l'audit externe/kbot3, les déci Créer les crates, manifests, modules minimaux, `postgres` default, `--no-default-features`, constants/logging targets et canaris de dépendances. Ajouter seulement les dépendances nécessaires au scaffold retenu. +**Statut : matérialisé par `0.3.2-pre.002`, gate Cargo opérateur à exécuter.** + +La tranche matérialise exactement : + +```text +ksp-store-lib -> ksp-store-api +ksp-store-lib[postgres] -> ksp-store-postgres-lib +ksp-store-postgres-lib -> ksp-store-api +ksp-store-postgres-lib -X-> ksp-store-lib +``` + +Les deux crates possèdent déjà leur `src/constants.rs` et leur futur `TRACING_TARGET`, mais `ksp-logging-lib` n'est pas encore ajouté : aucun comportement de production n'émet de log dans le scaffold. De même, Tokio, tokio-postgres, Deadpool, Rustls et SHA-256 restent absents tant que leurs tranches d'usage réel ne sont pas ouvertes. Cette matérialisation respecte la règle selon laquelle une dépendance de package doit correspondre à un usage réel plutôt qu'à une anticipation du graphe final. + ### `pre.003` — Settings + backend selection + lifecycle contracts Matérialiser `StoreSettings`, `StoreBackendSettings`, `PostgresStoreSettings`, erreurs stable, façade `Store` sans connexion lourde et réexports API. Tester la feature mismatch. diff --git a/docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md b/docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md index 5e04a54..2ed7a25 100644 --- a/docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md +++ b/docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md @@ -1,5 +1,5 @@ - + # Validation `0.3.2` — Store/PostgreSQL runtime foundation @@ -66,6 +66,8 @@ sha2 0.11.0 refinery 0.9.2 audité/rejeté ``` +Le gate opérateur après application de `pre.001`, fourni le 29 août 2026, est vert : audits Rust/Markdown, `cargo check --workspace` et `cargo clippy --workspace --all-targets` passent sur `0.3.2-pre.1`. + ## 3. Frontières Cargo ### V32-DEP-001 — Façade -> API @@ -74,7 +76,9 @@ refinery 0.9.2 audité/rejeté ksp-store-lib -> ksp-store-api ``` -Statut : `TODO pre.002`. +Matérialisé par `0.3.2-pre.002` dans le manifest de `ksp-store-lib`. + +Statut : `TODO gate opérateur pre.002` jusqu'au test ciblé et au `cargo tree`. ### V32-DEP-002 — Backend -> API @@ -82,7 +86,9 @@ Statut : `TODO pre.002`. ksp-store-postgres-lib -> ksp-store-api ``` -Statut : `TODO pre.002`. +Matérialisé par `0.3.2-pre.002` dans le manifest de `ksp-store-postgres-lib`. + +Statut : `TODO gate opérateur pre.002` jusqu'au test ciblé et au `cargo tree`. ### V32-DEP-003 — Pas de cycle backend @@ -92,7 +98,9 @@ ksp-store-postgres-lib -X-> ksp-store-lib Preuves : manifest scanner + cargo tree. -Statut : `TODO pre.002/pre.009`. +Le canari source de `pre.002` interdit explicitement la dépendance inverse ; la preuve Cargo reste à exécuter puis sera durcie à nouveau en `pre.009`. + +Statut : `TODO gate opérateur pre.002/pre.009`. ### V32-DEP-004 — Feature PostgreSQL @@ -104,7 +112,9 @@ ksp-store-postgres-lib est optional dependency cargo check -p ksp-store-lib --no-default-features passe ``` -Statut : `TODO pre.002`. +Le manifest de `ksp-store-lib` matérialise `default = ["postgres"]` et l'optional dependency `ksp-store-postgres-lib`. La compilation sans default feature est une preuve opérateur obligatoire. + +Statut : `TODO gate opérateur pre.002`. ### V32-DEP-005 — Firewall domaines