7.0 KiB
Delta 0.3.9-pre.002 — noyau ksp-worker-api
Base requise
0.3.9-pre.001-fix.002
workspace.package.version = 0.3.9-pre.1.fix.2
Le gate opérateur de la base a exécuté cargo clean, format, audits Rust/Markdown, cargo check --workspace, Clippy workspace --all-targets --all-features -- -D warnings, tests workspace --all-targets --all-features, les cinq builds Tauri deb,rpm et cargo tree --duplicates. Les commandes Cargo ont terminé sans échec signalé ; les tests live/smoke explicitement opt-in sont restés ignored comme prévu.
Objectif
Créer uniquement le noyau passif et runtime-neutral de ksp-worker-api décidé en pre.001, sans commencer le worker RAW Transaction ni anticiper le hardening de pre.003.
Version
Cette tranche est une nouvelle prerelease non-fix :
workspace.package.version = 0.3.9-pre.2
Le Cargo.toml racine passe du header 476 au header 477 et ajoute crates/ksp-worker-api aux membres du workspace.
Surface ajoutée
WorkerId
WorkerKindCode
MAX_WORKER_ID_BYTES = 128
MAX_WORKER_KIND_CODE_BYTES = 128
WorkerState
WorkerHealth
WorkerActivity
WorkerLifecycle
WorkerStopToken
WorkerSnapshotSequence
WorkerSnapshot
WorkerSnapshotFuture<'a>
WorkerSnapshotSource
ERROR_CODE_WORKER_ID_INVALID
ERROR_CODE_WORKER_KIND_INVALID
ERROR_CODE_WORKER_TRANSITION_INVALID
ERROR_CODE_WORKER_SNAPSHOT_SEQUENCE_EXHAUSTED
Error / ErrorCode / ErrorContext / Result
Tous les exports sont accessibles depuis le crate-root ; les modules restent privés.
Lifecycle matérialisé
Created -> Starting
Created -> Stopped
Starting -> Running
Starting -> Stopping
Starting -> Faulted(code)
Running -> Stopping
Running -> Faulted(code)
Stopping -> Stopped
Stopping -> Faulted(code)
Stopped et Faulted(ErrorCode) sont terminaux. Faulted conserve uniquement un ErrorCode KSP statique. Une transition invalide retourne ERROR_CODE_WORKER_TRANSITION_INVALID avec les seuls codes source/cible et laisse l'état inchangé.
WorkerHealth (Unknown, Healthy, Degraded, Unhealthy) et WorkerActivity (Unknown, Idle, Active) restent orthogonaux au lifecycle ; aucune completion, progression, ETA, slot, provider ou métrique métier n'entre dans cette API.
Snapshot et stop
WorkerSnapshot est fixe et contient exactement les dimensions communes décidées : identité, kind, séquence, lifecycle, health et activity. Aucun payload arbitraire ou champ diagnostique libre n'est admis.
WorkerSnapshotSequence part de zéro, avance par checked_add(1), expose is_after et retourne une erreur explicite en cas d'épuisement.
WorkerSnapshotSource expose current() et wait_for_change(...) via un future std boxed ; il n'impose aucun runtime concret. Les preuves object-safety, implémentation externe et listeners lents restent dans pre.003.
WorkerStopToken partage une intention atomique cloneable ; seule la première demande retourne true. Le token ne modifie pas directement le lifecycle et ne possède ni join, ni timeout, ni thread/task.
Firewalls
Dépendance normale exacte :
ksp-worker-api -> ksp-core-lib
Absents du manifest et des sources de production :
features / dev-dependencies / build-dependencies
ksp-job-api
ksp-interface-lib
ksp-config-lib
ksp-logging-lib
ksp-onchain-transport-lib
ksp-store-api / ksp-store-lib
tokio / futures / serde / tracing / Tauri
Solana / provider / RawTransaction / backfill / checkpoint
Tests ajoutés
Treize tests unitaires :
- identité : admission aux bornes, rejets hostiles, alphabet exact ;
- lifecycle : chemins terminaux, arrêt/fault depuis Stopping, conservation sur transition invalide, matrice exacte, codes state/health/activity ;
- stop : partage/idempotence et état par défaut ;
- snapshot : séquence monotone, exhaustion explicite et projection exacte des six dimensions communes.
Quatre canaries d'intégration :
- deux canaries dependency boundary : manifest Core-only et absence de chemins runtime/domain interdits dans les sources de production ;
- deux canaries public API : consommation crate-root du lifecycle/stop/snapshot et stabilité des bornes/error codes.
Le hardening adversarial complet, l'object-safety, l'implémentation externe std-only, les listeners lents/indépendants, le late-listener et les inventaires exacts restent réservés à pre.003.
Fichiers ajoutés
crates/ksp-worker-api/Cargo.toml
crates/ksp-worker-api/src/error.rs
crates/ksp-worker-api/src/identity.rs
crates/ksp-worker-api/src/lib.rs
crates/ksp-worker-api/src/lifecycle.rs
crates/ksp-worker-api/src/snapshot.rs
crates/ksp-worker-api/src/stop.rs
crates/ksp-worker-api/unit_tests/identity.rs
crates/ksp-worker-api/unit_tests/lifecycle.rs
crates/ksp-worker-api/unit_tests/snapshot.rs
crates/ksp-worker-api/unit_tests/stop.rs
crates/ksp-worker-api/tests/dependency_boundary.rs
crates/ksp-worker-api/tests/public_api.rs
deltas/0.3.9/pre.002.md
Fichiers modifiés
Cargo.toml
docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md
Fichiers supprimés
Aucun.
Documentation volontairement différée
crates/ksp-worker-api/README.md et USAGE.md ne sont pas créés dans cette tranche de code. Le plan réserve leur réconciliation version-neutral à pre.008, après freeze fonctionnelle et hardening de la surface publique.
Validations exécutées dans l'environnement d'assemblage
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 (320 table(s), 731 file(s))
Contrôles statiques complémentaires :
workspace member ksp-worker-api présent
workspace.package.version = 0.3.9-pre.2
manifest Worker API = Core-only, aucune feature/dev/build dependency
6 sources de production prévues présentes
4 fichiers unit_tests présents
2 suites d'intégration présentes
aucun pub mod dans src/lib.rs
aucun runtime concret ajouté
L'environnement d'assemblage ne fournit ni cargo, ni rustc, ni rustfmt. Aucun gate Cargo de pre.002 n'est donc déclaré PASS localement.
Gate opérateur demandé
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-api
cargo tree -p ksp-worker-api --edges normal
cargo tree -p ksp-worker-api -e features
Questions ouvertes
Aucune question ne bloque pre.003 après un gate opérateur vert. Les questions volontairement différées (WorkerHandle, registry/factory, restart generation, remote protocol, serialization, metrics communes) restent hors scope conformément au plan pre.001.