diff --git a/Cargo.toml b/Cargo.toml index caaf28d..d248ade 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 506 +# version: 507 [workspace] resolver = "3" -members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api"] +members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api", "crates/ksp-worker-raw-transaction-ingest-lib"] [workspace.package] -version = "0.3.11-pre.1" +version = "0.3.11-pre.2" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml b/crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml new file mode 100644 index 0000000..429df37 --- /dev/null +++ b/crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml @@ -0,0 +1,20 @@ +# file: crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml +# version: 1 + +[package] +name = "ksp-worker-raw-transaction-ingest-lib" +version.workspace = true +edition.workspace = true +repository.workspace = true + +[dependencies] +ksp-core-lib = { path = "../ksp-core-lib" } +ksp-logging-lib = { path = "../ksp-logging-lib" } +ksp-raw-transaction-lib = { path = "../ksp-raw-transaction-lib" } +ksp-store-lib = { path = "../ksp-store-lib", default-features = false } +ksp-worker-api = { path = "../ksp-worker-api" } +sha2 = { workspace = true } +tokio = { workspace = true, features = ["macros", "rt", "sync", "time"] } + +[lints] +workspace = true diff --git a/crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs b/crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs new file mode 100644 index 0000000..29bf7bf --- /dev/null +++ b/crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs @@ -0,0 +1,12 @@ +// file: crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs +// version: 1 + +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +//! Source-neutral runtime foundation for continuous KSP RAW transaction ingestion. +//! +//! The crate is intentionally limited to its dependency skeleton in this tranche. +//! Worker identity, settings, lifecycle, tasks, admission, persistence and snapshots +//! are introduced only by their dedicated prereleases. diff --git a/crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs b/crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs new file mode 100644 index 0000000..e057818 --- /dev/null +++ b/crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs @@ -0,0 +1,109 @@ +// file: crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs +// version: 1 + +//! Dependency firewall canaries for the RAW transaction ingest Worker skeleton. + +#[test] +fn pre_002_manifest_dependency_surface_is_exact() { + let manifest = include_str!("../Cargo.toml"); + let dependencies = dependency_section(manifest); + let names = manifest_dependency_names(dependencies); + assert_eq!(names, vec!["ksp-core-lib", "ksp-logging-lib", "ksp-raw-transaction-lib", "ksp-store-lib", "ksp-worker-api", "sha2", "tokio",],); + for required in [ + "ksp-core-lib = { path = \"../ksp-core-lib\" }", + "ksp-logging-lib = { path = \"../ksp-logging-lib\" }", + "ksp-raw-transaction-lib = { path = \"../ksp-raw-transaction-lib\" }", + "ksp-store-lib = { path = \"../ksp-store-lib\", default-features = false }", + "ksp-worker-api = { path = \"../ksp-worker-api\" }", + "sha2 = { workspace = true }", + "tokio = { workspace = true, features = [\"macros\", \"rt\", \"sync\", \"time\"] }", + ] { + assert!(dependencies.contains(required), "required Worker dependency missing: {required}"); + } + return; +} + +#[test] +fn pre_002_manifest_keeps_forbidden_layers_and_live_sources_out() { + let manifest = include_str!("../Cargo.toml"); + let dependencies = dependency_section(manifest); + for forbidden in [ + "futures-util", + "ksp-config-lib", + "ksp-interface-lib", + "ksp-job-api", + "ksp-job-backfill-lib", + "ksp-onchain-transport-lib", + "ksp-program-api", + "ksp-store-api", + "ksp-store-postgres-lib", + "ksp-wallet-lib", + "reqwest", + "solana-", + "tokio-tungstenite", + "tonic", + "yellowstone-grpc-proto", + ] { + assert!(!dependencies.contains(forbidden), "forbidden Worker dependency present: {forbidden}"); + } + assert!(!manifest.contains("[dev-dependencies]"), "pre.002 requires no test-only dependency"); + assert!(!manifest.contains("[build-dependencies]"), "pre.002 requires no build dependency"); + return; +} + +#[test] +fn pre_002_crate_root_contains_no_runtime_behavior_or_public_contract_yet() { + let root = include_str!("../src/lib.rs"); + for forbidden in [ + "pub mod ", + "pub struct ", + "pub enum ", + "pub trait ", + "pub fn ", + "tokio::", + "ksp_store_lib::", + "ksp_raw_transaction_lib::", + "ksp_worker_api::", + "start(", + "spawn(", + ] { + assert!(!root.contains(forbidden), "pre.002 crate root opened behavior too early: {forbidden}"); + } + return; +} + +fn dependency_section(manifest: &str) -> &str { + let after_header = match manifest.split_once("[dependencies]") { + std::option::Option::Some((_, section)) => section, + std::option::Option::None => { + return ""; + }, + }; + let end = match after_header.find("\n[") { + std::option::Option::Some(index) => index, + std::option::Option::None => after_header.len(), + }; + return &after_header[..end]; +} + +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/deltas/0.3.11/pre.002.md b/deltas/0.3.11/pre.002.md new file mode 100644 index 0000000..58b82f6 --- /dev/null +++ b/deltas/0.3.11/pre.002.md @@ -0,0 +1,164 @@ + + + +# Delta `0.3.11-pre.002` — squelette Worker RAW + dependency firewall + +## Base requise + +```text +0.3.11-pre.001 +workspace.package.version = 0.3.11-pre.1 +``` + +Le gate opérateur communiqué pour `pre.001` est vert sur `cargo fmt --all`, les audits Rust/Markdown, `cargo check --workspace` et Clippy workspace strict `--all-targets --all-features -- -D warnings`. Aucun `cargo test` supplémentaire n'a été communiqué pour ce gate et aucun n'est inventé. + +## Objectif + +Créer uniquement le squelette de `ksp-worker-raw-transaction-ingest-lib`, l'inscrire au workspace et verrouiller son graphe de dépendances. Aucun settings, identity, `start`, task, channel, Store write, canonicalisation ou snapshot runtime n'est matérialisé dans cette tranche. + +## Version + +Cette tranche est une prerelease non-fix : + +```text +workspace.package.version = 0.3.11-pre.2 +``` + +Le `Cargo.toml` racine passe du header `506` au header `507` et le workspace passe de 20 à 21 membres. + +## Graphe de production exact + +```text +ksp-worker-raw-transaction-ingest-lib + -> ksp-core-lib + -> ksp-logging-lib + -> ksp-raw-transaction-lib + -> ksp-store-lib default-features=false + -> ksp-worker-api + -> sha2 + -> tokio features=macros,rt,sync,time +``` + +Ces edges matérialisent uniquement la frontière décidée en `pre.001`. Le code runtime qui les consommera reste réservé à ses tranches dédiées. + +## Firewall explicite + +Absents du manifest de production : + +```text +futures-util +ksp-config-lib +ksp-interface-lib +ksp-job-api +ksp-job-backfill-lib +ksp-onchain-transport-lib +ksp-program-api +ksp-store-api direct +ksp-store-postgres-lib +ksp-wallet-lib +reqwest +Solana protocol SDK direct +tokio-tungstenite +tonic +yellowstone-grpc-proto +``` + +Il n'existe ni `[dev-dependencies]`, ni `[build-dependencies]` dans cette tranche. + +## Crate-root volontairement vide de comportement + +`src/lib.rs` contient uniquement les lints workspace et la rustdoc de responsabilité. Il n'expose encore : + +```text +aucun pub mod +aucun type public +aucune fonction publique +aucun start/spawn +aucun appel Tokio +aucun appel Store/common RAW/Worker API +``` + +Le test externe `dependency_boundary.rs` verrouille le manifest exact, les edges interdits et l'absence de comportement runtime prématuré au crate-root. + +## Documentation volontairement différée + +`README.md` et `USAGE.md` ne sont pas créés à ce stade car la crate ne possède encore aucune API consommable. Leur réconciliation version-neutral reste réservée à `pre.012`, après freeze de la fondation runtime. + +## Fichiers ajoutés + +```text +crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml +crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs +crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs +deltas/0.3.11/pre.002.md +``` + +## Fichiers modifiés + +```text +Cargo.toml +docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md +docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md +``` + +## Fichiers supprimés + +Aucun. + +## Validations exécutées dans l'environnement d'assemblage + +```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 +Markdown table audit: clean (340 table(s), 776 file(s)) + +contrôle TOML/statique : workspace 0.3.11-pre.2, 21 membres, manifest Worker exact, Store sans default features, Tokio macros/rt/sync/time +comparaison byte-à-byte avec pre.001 : 4 fichiers ajoutés, 3 modifiés, 0 supprimé +``` + +L'environnement d'assemblage ne fournit ni `cargo`, ni `rustc`, ni `rustfmt`. Aucun gate Cargo n'est déclaré PASS localement. + +## Gate opérateur demandé + +```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 +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test -p ksp-worker-raw-transaction-ingest-lib +cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal +cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features +``` + +## Validations non exécutées localement + +```text +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test -p ksp-worker-raw-transaction-ingest-lib +cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal +cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features +``` + +## Décisions conservées + +```text +aucune source live dans 0.3.11 +aucun Transport productif avant 0.3.12 +Store uniquement via ksp-store-lib default-features=false +aucun backend Store direct +aucun Job/Backfill/Config dans le Worker +futures-util absent tant qu'un usage réel n'est pas démontré +Tokio direct parce que le Worker concret possédera ses tâches runtime +aucune API publique avant la tranche qui en possède le contrat +``` + +## Suite + +Après gate opérateur vert, `pre.003` introduit uniquement l'identité Worker concrète et `RawTransactionIngestSettings` avec defaults, bornes et validation. Aucun spawn n'y est autorisé. diff --git a/docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md b/docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md index 065aef0..5afe823 100644 --- a/docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md +++ b/docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md @@ -1,5 +1,5 @@ - + # Plan v0.3.11 — fondation runtime du Worker RawTransaction ingest @@ -699,6 +699,8 @@ Budget cible : **10–15 min**. Vérifier la stable, corriger les deux divergenc Budget cible : **10–15 min**. Créer la crate minimale, l'ajouter au workspace, installer uniquement les edges décidés et les tests de manifest/dependency boundary. Pas de runtime comportemental. +État après matérialisation : **implémenté, gate opérateur requis**. Le manifest porte exactement les sept edges décidés (`core`, `logging`, common RAW, façade Store sans backend par défaut, Worker API, `sha2`, Tokio `macros/rt/sync/time`) ; la crate-root reste sans API ni comportement runtime et un test externe verrouille le firewall. + ### `pre.003` — identity + settings foundation Budget cible : **10–15 min**. Kind code, settings, defaults/bounds, validation network/worker identity et erreurs correspondantes. Aucun spawn. diff --git a/docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md b/docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md index 93f3579..e161dee 100644 --- a/docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md +++ b/docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md @@ -1,5 +1,5 @@ - + # Validation v0.3.11 — fondation runtime du Worker RawTransaction ingest @@ -442,3 +442,93 @@ Markdown table audit: clean (340 table(s), 775 file(s)) scan sémantique des règles actives : 0 formulation obsolète ciblée restante comparaison byte-à-byte avec la stable : 3 fichiers ajoutés, 3 modifiés, 0 supprimé ``` + +## 13. Fermeture opérateur `pre.001` et matérialisation `pre.002` + +### 13.1 Fermeture opérateur de `pre.001` + +Le journal opérateur communiqué le 8 septembre 2026 ferme le gate demandé sur `0.3.11-pre.1` : + +```text +cargo fmt --all : terminé sans erreur +python3 scripts/audit_rust_workspace_rules.py : clean, export completeness 0 +python3 scripts/audit_markdown_tables.py ... : clean (340 tables, 775 files) +cargo check --workspace : terminé sans erreur +cargo clippy --workspace --all-targets --all-features -- -D warnings : terminé sans erreur +``` + +La sortie Cargo confirme toutes les crates existantes en `0.3.11-pre.1`. Aucun `cargo test` n'a été communiqué dans ce gate et aucun test supplémentaire n'est donc déclaré exécuté. `pre.002` peut être ouverte. + +### 13.2 Scope matérialisé dans `pre.002` + +La tranche crée uniquement : + +```text +crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml +crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs +crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs +``` + +Le manifest de production est limité à : + +```text +ksp-core-lib +ksp-logging-lib +ksp-raw-transaction-lib +ksp-store-lib default-features=false +ksp-worker-api +sha2 +tokio features = macros,rt,sync,time +``` + +Sont explicitement absents : + +```text +futures-util +ksp-config-lib +ksp-job-api +ksp-job-backfill-lib +ksp-onchain-transport-lib +ksp-store-api direct +ksp-store-postgres-lib +provider SDK / reqwest / tonic / Yellowstone / WebSocket client +dev-dependencies +build-dependencies +``` + +La crate-root n'expose encore aucun type, fonction, module public ou runtime. Settings/identity commencent en `pre.003`; start/lifecycle en `pre.004`. + +### 13.3 Preuves locales d'assemblage `pre.002` + +Exécuté dans l'environnement d'assemblage : + +```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 +Markdown table audit: clean (340 table(s), 776 file(s)) + +contrôle TOML/statique : workspace 0.3.11-pre.2, 21 membres, Worker présent, 7 dépendances exactes, Store default-features=false, Tokio macros/rt/sync/time +comparaison byte-à-byte avec pre.001 : 4 fichiers ajoutés, 3 modifiés, 0 supprimé +``` + +L'environnement d'assemblage ne fournit ni `cargo`, ni `rustc`, ni `rustfmt`. Aucun gate Cargo de `pre.002` n'est déclaré PASS localement. + +### 13.4 Gate opérateur demandé pour `pre.002` + +```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 +cargo check --workspace +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo test -p ksp-worker-raw-transaction-ingest-lib +cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal +cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features +``` + +Critère de passage : le firewall exact reste vert et aucun backend Store, Job, Config, Transport/provider ou runtime comportemental prématuré n'apparaît. +