v0.3.1-pre.002

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"

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

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.

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;

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.

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;
+}

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::Pubkey>) -> ksp_store_api::Result<ksp_store_api::Pubkey> {
+    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<ksp_store_api::ErrorCode> = std::option::Option::None;
+    let error_context_type: std::option::Option<ksp_store_api::ErrorContext> = std::option::Option::None;
+    let error_type: std::option::Option<ksp_store_api::Error> = 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;
+}

deltas/0.3.1/pre.002.md

@@ -0,0 +1,105 @@
+<!-- file: deltas/0.3.1/pre.002.md -->
+<!-- version: 1 -->
+
+# 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.