diff --git a/Cargo.toml b/Cargo.toml index b0d564d..f330ce8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 323 +# version: 324 [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-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-wallet-lib"] [workspace.package] -version = "0.3.1-pre.1" +version = "0.3.1-pre.2" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/crates/ksp-store-api/Cargo.toml b/crates/ksp-store-api/Cargo.toml new file mode 100644 index 0000000..44ca8d3 --- /dev/null +++ b/crates/ksp-store-api/Cargo.toml @@ -0,0 +1,14 @@ +# file: crates/ksp-store-api/Cargo.toml +# version: 1 + +[package] +name = "ksp-store-api" +version.workspace = true +edition.workspace = true +repository.workspace = true + +[dependencies] +ksp-core-lib = { path = "../ksp-core-lib" } + +[lints] +workspace = true diff --git a/crates/ksp-store-api/src/capability.rs b/crates/ksp-store-api/src/capability.rs new file mode 100644 index 0000000..4f6e562 --- /dev/null +++ b/crates/ksp-store-api/src/capability.rs @@ -0,0 +1,8 @@ +// file: crates/ksp-store-api/src/capability.rs +// version: 1 + +//! Private home for backend-agnostic Store capability contracts. +//! +//! `0.3.1-pre.002` establishes the ownership boundary only. Concrete read and +//! write capabilities are introduced after the RAW models they operate on are +//! defined; no backend/runtime contract belongs here. diff --git a/crates/ksp-store-api/src/lib.rs b/crates/ksp-store-api/src/lib.rs new file mode 100644 index 0000000..03f2a2f --- /dev/null +++ b/crates/ksp-store-api/src/lib.rs @@ -0,0 +1,31 @@ +// file: crates/ksp-store-api/src/lib.rs +// version: 1 + +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +//! Backend-agnostic persistence contracts for KSP Store implementations. +//! +//! `ksp-store-api` owns persistent models plus the contracts that operate on +//! them. The `0.3.1` release is limited to N1 RAW/acquisition data. N2 +//! STRUCTURAL is a later, distinct layer and no Program decode belongs to this +//! crate. +//! +//! Models and capabilities deliberately have separate private module homes. +//! Backend implementations, SQL, migrations, Config, Transport and runtime +//! dispatch remain outside this crate. + +mod capability; +mod model; + +/// Common KSP error type used by Store-facing contracts. +pub use ksp_core_lib::Error; +/// Stable structured code identifying a KSP error category and condition. +pub use ksp_core_lib::ErrorCode; +/// Structured contextual field attached to a KSP error. +pub use ksp_core_lib::ErrorContext; +/// Canonical Solana account address primitive shared by persistent models. +pub use ksp_core_lib::Pubkey; +/// Common KSP result alias using [`Error`]. +pub use ksp_core_lib::Result; diff --git a/crates/ksp-store-api/src/model.rs b/crates/ksp-store-api/src/model.rs new file mode 100644 index 0000000..038c4c8 --- /dev/null +++ b/crates/ksp-store-api/src/model.rs @@ -0,0 +1,9 @@ +// file: crates/ksp-store-api/src/model.rs +// version: 1 + +//! Private home for persistent Store models. +//! +//! The current release is N1 RAW-only. Future N2 STRUCTURAL models are a +//! separate data layer and are not introduced by this scaffold. Persistent +//! models and backend capabilities remain separate even when one capability +//! operates on one or more models. diff --git a/crates/ksp-store-api/tests/dependency_boundary.rs b/crates/ksp-store-api/tests/dependency_boundary.rs new file mode 100644 index 0000000..eccc892 --- /dev/null +++ b/crates/ksp-store-api/tests/dependency_boundary.rs @@ -0,0 +1,95 @@ +// file: crates/ksp-store-api/tests/dependency_boundary.rs +// version: 1 + +//! Dependency canaries for the Store API scaffold. + +#[test] +fn pre_002_manifest_has_exact_core_only_runtime_dependency() { + let manifest = include_str!("../Cargo.toml"); + let dependencies_tail = manifest.split("[dependencies]").nth(1); + assert!(dependencies_tail.is_some(), "Store API dependencies section must exist"); + let dependencies_tail = match dependencies_tail { + std::option::Option::Some(value) => value, + std::option::Option::None => return, + }; + let dependencies = match dependencies_tail.split("[lints]").next() { + std::option::Option::Some(value) => value, + std::option::Option::None => return, + }; + assert_eq!(manifest_dependency_names(dependencies), std::vec!["ksp-core-lib"]); + for forbidden in [ + "ksp-config-lib", + "ksp-interface-lib", + "ksp-logging-lib", + "ksp-materializer-api", + "ksp-offchain-transport-lib", + "ksp-onchain-transport-lib", + "ksp-program-api", + "ksp-program-lib", + "ksp-store-lib", + "ksp-store-postgres-lib", + "ksp-wallet-lib", + "async-trait", + "bincode", + "chrono", + "postgres", + "serde", + "serde_json", + "sqlx", + "tauri", + "tokio", + "tokio-postgres", + "tonic", + "tracing", + "wincode", + ] { + assert!(!dependencies.contains(forbidden), "forbidden Store API dependency detected: {forbidden}"); + } + return; +} + +#[test] +fn pre_002_source_boundary_separates_models_capabilities_and_backend_runtime() { + let crate_root = include_str!("../src/lib.rs"); + assert!(crate_root.contains("mod capability;")); + assert!(crate_root.contains("mod model;")); + assert!(!crate_root.contains("pub mod ")); + for forbidden in [ + "ksp_store_lib", + "ksp_store_postgres_lib", + "ksp_onchain_transport_lib", + "ksp_program_api", + "serde::", + "sqlx::", + "tokio::", + "tokio_postgres::", + "std::env::", + "std::fs::", + "std::net::", + ] { + assert!(!crate_root.contains(forbidden), "forbidden Store API crate-root dependency/surface detected: {forbidden}"); + } + return; +} + +fn manifest_dependency_names(section: &str) -> std::vec::Vec<&str> { + let mut names = std::vec::Vec::new(); + for line in section.lines() { + let content = match line.split('#').next() { + std::option::Option::Some(value) => value.trim(), + std::option::Option::None => continue, + }; + if content.is_empty() { + continue; + } + let name = match content.split('=').next() { + std::option::Option::Some(value) => value.trim().trim_end_matches(".workspace"), + std::option::Option::None => continue, + }; + if !name.is_empty() { + names.push(name); + } + } + names.sort_unstable(); + return names; +} diff --git a/crates/ksp-store-api/tests/public_api.rs b/crates/ksp-store-api/tests/public_api.rs new file mode 100644 index 0000000..64b3dfa --- /dev/null +++ b/crates/ksp-store-api/tests/public_api.rs @@ -0,0 +1,32 @@ +// file: crates/ksp-store-api/tests/public_api.rs +// version: 1 + +//! Integration canaries for the public `ksp-store-api` scaffold. + +fn consume_result(value: ksp_store_api::Result) -> ksp_store_api::Result { + return value; +} + +#[test] +fn public_pre_002_core_facade_is_available_from_crate_root() { + let pubkey = ksp_store_api::Pubkey::new_from_array([0x31_u8; 32]); + let forwarded = consume_result(std::result::Result::Ok(pubkey)); + assert!(forwarded.is_ok()); + let error_code_type: std::option::Option = std::option::Option::None; + let error_context_type: std::option::Option = std::option::Option::None; + let error_type: std::option::Option = std::option::Option::None; + assert!(error_code_type.is_none()); + assert!(error_context_type.is_none()); + assert!(error_type.is_none()); + return; +} + +#[test] +fn public_pre_002_scaffold_exposes_no_private_module_paths_or_backend_types() { + let source = include_str!("../src/lib.rs"); + assert!(!source.contains("pub mod ")); + for forbidden in ["Postgres", "Sql", "Migration", "ProgramInstruction", "RawTransaction"] { + assert!(!source.contains(forbidden), "forbidden pre.002 Store API public concept detected: {forbidden}"); + } + return; +} diff --git a/deltas/0.3.1/pre.002.md b/deltas/0.3.1/pre.002.md new file mode 100644 index 0000000..b3f8deb --- /dev/null +++ b/deltas/0.3.1/pre.002.md @@ -0,0 +1,105 @@ + + + +# Delta `0.3.1-pre.002` + +## Base requise + +```text +0.3.1-pre.001-fix.003 +``` + +## Objectif + +Créer uniquement le scaffold de `ksp-store-api` et matérialiser la frontière de dépendances validée par `pre.001`, sans introduire encore les primitives RAW de `pre.003` ni aucun backend/runtime Store. + +## Fichiers ajoutés + +```text +crates/ksp-store-api/Cargo.toml +crates/ksp-store-api/src/capability.rs +crates/ksp-store-api/src/lib.rs +crates/ksp-store-api/src/model.rs +crates/ksp-store-api/tests/dependency_boundary.rs +crates/ksp-store-api/tests/public_api.rs +deltas/0.3.1/pre.002.md +``` + +## Fichiers modifiés + +```text +Cargo.toml +``` + +Le workspace passe à : + +```text +0.3.1-pre.2 +``` + +et enregistre `crates/ksp-store-api` comme membre. + +## Décisions matérialisées + +- `ksp-store-api` dépend uniquement de `ksp-core-lib`. +- les modules `model` et `capability` sont privés et distincts ; aucune arborescence de module interne n'est une API publique. +- la façade crate-root réexporte seulement les primitives Core réellement communes nécessaires aux futurs contrats Store : `Error`, `ErrorCode`, `ErrorContext`, `Pubkey` et `Result`. +- `0.3.1` reste N1 RAW-only ; STRUCTURAL reste une couche ultérieure distincte et aucun type N2 n'est créé dans cette tranche. +- aucune dépendance Interface, Transport, Program, Materializer, Config, Logging, async runtime, serde, codec ou backend n'est introduite. +- aucun marker trait ou enum Store artificiel n'est créé avant qu'une opération/modèle réel ne le justifie. +- `RawTransaction`, provenance, payload, observation et idempotence restent réservés à `pre.003`. + +## Tests ajoutés + +`dependency_boundary.rs` vérifie : + +- la dépendance runtime exacte Core-only ; +- l'absence des crates backend/runtime/transport/program/config ; +- l'absence de chemins SQL/PostgreSQL/async/env/filesystem dans la façade. + +`public_api.rs` vérifie : + +- la consommation externe des réexports Core depuis le crate-root ; +- l'absence de `pub mod` ; +- l'absence de concepts backend et de modèles RAW introduits prématurément. + +## Validations exécutées dans l'environnement de génération + +```text +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 +``` + +## Validations non exécutées dans l'environnement de génération + +`cargo`/`rustfmt` ne sont pas disponibles dans l'environnement de génération. L'opérateur doit donc exécuter : + +```text +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-store-api +``` + +Une commande non exécutée n'est pas déclarée PASS. + +## Hors scope confirmé + +```text +RawTransaction concret +RawAccountState +TransactionStatusObservation +capabilities read/write +queries/outcomes +retention/tombstone concret +ksp-store-lib +ksp-store-postgres-lib +PostgreSQL/tokio-postgres +Config std.store +N2 STRUCTURAL +N3/N4 +``` + +## Suite + +`0.3.1-pre.003` introduit les primitives RAW communes puis `RawTransaction` et son observation, sans faire sortir les logs inclus de la transaction vers un modèle `RawLog` distinct.