v0.3.9-pre.002
This commit is contained in:
202
deltas/0.3.9/pre.002.md
Normal file
202
deltas/0.3.9/pre.002.md
Normal file
@@ -0,0 +1,202 @@
|
||||
<!-- file: deltas/0.3.9/pre.002.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.9-pre.002` — noyau `ksp-worker-api`
|
||||
|
||||
## Base requise
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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é
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
ksp-worker-api -> ksp-core-lib
|
||||
```
|
||||
|
||||
Absents du manifest et des sources de production :
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```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 (320 table(s), 731 file(s))
|
||||
```
|
||||
|
||||
Contrôles statiques complémentaires :
|
||||
|
||||
```text
|
||||
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é
|
||||
|
||||
```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-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`.
|
||||
Reference in New Issue
Block a user