v0.3.11-pre.004
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Plan v0.3.11 — fondation runtime du Worker RawTransaction ingest
|
||||
|
||||
@@ -705,15 +705,19 @@ Budget cible : **10–15 min**. Créer la crate minimale, l'ajouter au workspace
|
||||
|
||||
Budget cible : **10–15 min**. Kind code, settings, defaults/bounds, validation network/worker identity et erreurs correspondantes. Aucun spawn.
|
||||
|
||||
État après matérialisation : **implémenté, gate opérateur requis**. Le kind stable vaut `raw_transaction_ingest`; les settings portent uniquement `network`, `worker_id`, queue, concurrence de persistence et drain timeout. Les identités restent validées par leurs types propriétaires, tandis que les trois bornes techniques sont verrouillées par un code d'erreur Worker stable et des tests unitaires/externes. Aucun `start`, spawn, channel, supervisor ou appel Store n'est introduit.
|
||||
État après matérialisation : **implémenté et gate opérateur validé après `pre.003-fix.001`**. Le kind stable vaut `raw_transaction_ingest`; les settings portent uniquement `network`, `worker_id`, queue, concurrence de persistence et drain timeout. Les identités restent validées par leurs types propriétaires, tandis que les trois bornes techniques sont verrouillées par un code d'erreur Worker stable et des tests unitaires/externes. Le fix `pre.003-fix.001` remplace les deux propagations `?` interdites par un contrôle de flux explicite ; le gate communiqué le 8 septembre 2026 est ensuite vert sur `fmt`, audits, `check`, Clippy strict et les dix tests de la crate.
|
||||
|
||||
### `pre.004` — start/handle/lifecycle/terminal
|
||||
|
||||
Budget cible : **15–20 min**. Start sur runtime caller-owned, handle public, stop idempotent, lifecycle générique, terminal future sans JoinHandle public. Harness runtime minimal.
|
||||
|
||||
État après matérialisation : **implémenté, gate opérateur requis**. `RawTransactionIngestWorker::start(settings, Arc<Store>)` vérifie le runtime Tokio courant puis le réseau Store avant spawn. Le handle clonable expose uniquement `request_stop()` et `wait_terminal()` ; un `watch<bool>` privé sert au wake-up de stop et un `watch<WorkerState>` privé au terminal de fondation. Le task racine ne possède encore aucun task enfant, aucune admission/persistence et aucun snapshot concret ; la disparition de tous les handles ferme le sender de stop et fait terminer proprement ce task. `wait_terminal()` attend le terminal puis la fermeture du sender d'état, sans exposer de `JoinHandle`.
|
||||
|
||||
Les méthodes `snapshot_source()` et `worker_snapshot_source()` prévues par la surface finale restent volontairement différées à `pre.008`, où leur contrat latest-value concret sera effectivement prouvé.
|
||||
|
||||
### `pre.005` — supervisor privé + ownership des tâches
|
||||
|
||||
Budget cible : **15–20 min**. Supervisor, JoinSet/joins privés, stop wake-up, test source seam et preuve qu'aucune tâche ne survit au terminal. Pas encore de persistence réelle.
|
||||
Budget cible : **15–20 min**. Introduire le supervisor, les JoinSet/joins privés, intégrer le wake-up de stop déjà matérialisé à l'ownership des tâches enfants, ajouter le test source seam et prouver qu'aucune tâche enfant ne survit au terminal. Pas encore de persistence réelle.
|
||||
|
||||
### `pre.006` — admission bornée + canonicalisation common
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Validation v0.3.11 — fondation runtime du Worker RawTransaction ingest
|
||||
|
||||
@@ -634,3 +634,109 @@ cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features
|
||||
```
|
||||
|
||||
Critère de passage : defaults/bornes/erreurs/identités sont verts, le dependency firewall reste inchangé et aucun comportement runtime de `pre.004` n'apparaît.
|
||||
|
||||
## 15. Fermeture opérateur `pre.003-fix.001` et matérialisation `pre.004`
|
||||
|
||||
### 15.1 Fermeture opérateur de `pre.003-fix.001`
|
||||
|
||||
Le journal opérateur communiqué le 8 septembre 2026 ferme le correctif technique `0.3.11-pre.003-fix.001` (`workspace.package.version = 0.3.11-pre.3.fix.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, 778 files)
|
||||
cargo check --workspace : terminé sans erreur
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings : terminé sans erreur
|
||||
cargo test -p ksp-worker-raw-transaction-ingest-lib : 4 unit + 3 dependency-boundary + 3 public API PASS, 0 échec
|
||||
doc-tests : PASS
|
||||
```
|
||||
|
||||
Le défaut `clippy::question_mark_used` de `pre.003` est donc clos. `pre.004` peut être ouverte.
|
||||
|
||||
### 15.2 Scope matérialisé dans `pre.004`
|
||||
|
||||
La tranche ajoute :
|
||||
|
||||
```text
|
||||
ERROR_CODE_RAW_TRANSACTION_INGEST_RUNTIME_INVALID
|
||||
RawTransactionIngestWorker
|
||||
RawTransactionIngestHandle
|
||||
RawTransactionIngestTerminalFuture
|
||||
RawTransactionIngestWorker::start(settings, Arc<Store>)
|
||||
RawTransactionIngestHandle::request_stop()
|
||||
RawTransactionIngestHandle::wait_terminal()
|
||||
```
|
||||
|
||||
`start` reste synchrone et ne crée aucun runtime. Il exige un `tokio::runtime::Handle::try_current()` valide avant le spawn, puis compare `settings.network()` au réseau sûr exposé par `Store::runtime_snapshot()`. Une incompatibilité retourne uniquement le code stable `worker_raw_transaction_ingest.runtime_invalid` avec un contexte statique ; aucun identifiant de Worker ou valeur réseau n'est recopié dans l'erreur.
|
||||
|
||||
Le `Store` est reçu sous `Arc<Store>` et seulement retenu par le task racine de fondation ; aucune opération Store n'est encore appelée et le Worker ne ferme jamais la façade.
|
||||
|
||||
### 15.3 Lifecycle et terminal
|
||||
|
||||
La state machine concrète réutilise exclusivement `ksp-worker-api::WorkerLifecycle` :
|
||||
|
||||
```text
|
||||
Created -> Starting -> Running -> Stopping -> Stopped
|
||||
Created -> Starting -> Stopping -> Stopped (stop immédiat)
|
||||
```
|
||||
|
||||
Tout invariant de transition impossible est projeté vers `Faulted(ERROR_CODE_RAW_TRANSACTION_INGEST_RUNTIME_INVALID)` sans texte externe.
|
||||
|
||||
Le handle partage `WorkerStopToken` pour l'idempotence. Le premier `request_stop()` accepté réveille le task racine via un `tokio::sync::watch<bool>` privé ; les appels suivants retournent `false`. La fermeture de tous les senders de stop, notamment lorsque tous les handles sont droppés sans appel explicite, est interprétée comme une terminaison coopérative afin de ne pas laisser le task racine attendre indéfiniment.
|
||||
|
||||
Le terminal de fondation est porté par un `watch<WorkerState>` privé. `wait_terminal()` retourne une future boxed `Send` appartenant à la crate concrète et attend à la fois un état terminal puis la fermeture du sender par le task racine. Aucun `tokio::task::JoinHandle` ni `JoinSet` n'est exposé publiquement.
|
||||
|
||||
### 15.4 Frontière volontaire de `pre.004`
|
||||
|
||||
La tranche n'introduit encore aucun :
|
||||
|
||||
```text
|
||||
JoinSet / ownership de tâches enfants
|
||||
mpsc d'admission
|
||||
PrivateRawTransactionIngress
|
||||
canonicalisation common RAW
|
||||
observation key
|
||||
appel Store de persistence
|
||||
RawTransactionIngestSnapshot
|
||||
WorkerSnapshotSource concret
|
||||
source live
|
||||
Transport
|
||||
Config
|
||||
```
|
||||
|
||||
Le `watch<bool>` de stop est le wake-up minimal nécessaire au contrat start/stop. `pre.005` l'intègre au supervisor et à l'ownership des futures tâches enfants ; `pre.008` ouvre seulement alors les deux sources de snapshot prévues par la surface finale.
|
||||
|
||||
### 15.5 Preuves locales d'assemblage `pre.004`
|
||||
|
||||
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), 779 file(s))
|
||||
|
||||
scan statique : aucun ?, unwrap, expect ou panic de production dans la crate Worker
|
||||
scan statique : aucun JoinSet, mpsc, persistence, canonicalisation ou Transport dans runtime.rs
|
||||
```
|
||||
|
||||
L'environnement d'assemblage ne fournit ni `cargo`, ni `rustc`, ni `rustfmt`. Aucun gate Cargo `pre.004` n'est déclaré PASS localement.
|
||||
|
||||
### 15.6 Gate opérateur demandé pour `pre.004`
|
||||
|
||||
```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 start caller-owned, le contrôle de réseau, les transitions generic Worker API, le stop idempotent et le terminal boxed sont verts ; aucun `JoinHandle` public, supervisor enfant, admission, Store write, snapshot concret ou source live n'apparaît.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user