v0.3.9-pre.001

docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md

@@ -0,0 +1,204 @@
+<!-- file: docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md -->
+<!-- version: 1 -->
+
+# Validation v0.3.9 — Worker API + audit RAW Transaction
+
+## 1. Objet
+
+Cette matrice suit les preuves de `0.3.9` sans remplacer les deltas. `pre.001` ferme seulement le cadrage architectural ; les preuves Rust et l’audit externe RAW restent ouverts jusqu’à leurs tranches dédiées.
+
+## 2. Gate d’ouverture `pre.001`
+
+- [X] Archive KSP fournie explicitement comme stable `v0.3.8`.
+- [X] SHA-256 KSP : `b3a34a3dfd56fac1eef3d23f13631ff001338b612834488038cf259112c63624`.
+- [X] `unzip -t` KSP intégral propre.
+- [X] 1 809 entrées KSP contrôlées sans traversal/absolu/symlink/artefact interdit.
+- [X] `workspace.package.version = 0.3.8`.
+- [X] `deltas/0.3.8/rel.001.md` présent.
+- [X] 18 membres workspace inventoriés ; Store Desk, Job, Transport, Config et Store requis présents.
+- [X] Archive kbot3 SHA-256 `ee47643b9f8b582ee8db97b2381ec107e45aef8c009fee44757531514615d318` et `unzip -t` propre.
+- [X] kbot3 **non inspecté fonctionnellement** pendant la conception Worker API ; usage réservé à l’audit RAW après freeze.
+- [X] Règles normatives et architectures obligatoires du prompt lues avant décision.
+- [X] Headers/version des documents obligatoires confirmés.
+- [X] `ksp-job-api` manifest/src/tests et plan/validation `0.3.6` audités comme référence de propriétés.
+- [X] `ksp-job-backfill-lib` et Backfill Desk audités comme contraste API générique / consumer concret.
+- [X] Audit Rust Python baseline : clean, export completeness 0, KSP workspace clean.
+- [X] Audit Markdown baseline : clean, 316 tables / 725 fichiers.
+- [ ] `cargo fmt --all -- --check` local : non exécuté, `cargo` absent.
+- [ ] `cargo check --workspace` local : non exécuté, `cargo` absent.
+- [ ] `cargo clippy --workspace --all-targets` local : non exécuté, `cargo` absent.
+- [ ] `cargo tree -p ksp-job-api --edges normal` local : non exécuté, `cargo` absent ; manifest statique Core-only confirmé séparément.
+
+### Audit post-documentation `pre.001`
+
+- [X] Audit Rust post-modification : General clean, export completeness 0, KSP workspace clean.
+- [X] Audit Markdown post-modification : clean, 321 tables / 728 fichiers.
+- [X] Diff byte-level contre le ZIP stable : trois ajouts, zéro modification, zéro suppression après retrait des artefacts ignorés.
+- [X] `Cargo.toml` reste byte-identique à la base et `workspace.package.version = 0.3.8`.
+
+Le ZIP ne contient pas `.git`; l’existence du tag n’est pas inspectée directement. Le `rel.001` stable décrit l’opération `tag v0.3.8` et le prompt autorise l’archive stable explicitement fournie comme base.
+
+## 3. Architecture Worker API décidée en `pre.001`
+
+- [X] Job et Worker restent deux lifecycle APIs sémantiquement distinctes.
+- [X] Aucun edge `ksp-worker-api -> ksp-job-api`.
+- [X] Dependency cible exacte : `ksp-worker-api -> ksp-core-lib` uniquement.
+- [X] `WorkerId` et `WorkerKindCode` propres, 128 octets max, alphabet sûr.
+- [X] States retenus : Created, Starting, Running, Stopping, Stopped, Faulted(ErrorCode).
+- [X] Stopped et Faulted terminaux/immutables.
+- [X] Health distinct : Unknown, Healthy, Degraded, Unhealthy.
+- [X] Activity générique minimale : Unknown, Idle, Active.
+- [X] Aucun progress `current/total`, pourcentage, ETA ou métrique métier dans l’API commune.
+- [X] Snapshot commun fixe, non générique, sans payload arbitraire.
+- [X] Snapshot fields limités à identity/kind/sequence/state/health/activity.
+- [X] Latest-value retenu : current + wait_for_change + coalescing + resync.
+- [X] Sequence monotone checked, exhaustion explicite.
+- [X] `WorkerSnapshotSource` prévu `Send + Sync` et object-safe sans Tokio.
+- [X] `WorkerStopToken` coopératif, partagé, idempotent, non bloquant.
+- [X] Stop token ne possède ni timeout, ni join, ni runtime.
+- [X] Fault public ne conserve qu’un `ErrorCode` statique.
+- [X] Restart/retry/factory/control plane explicitement caller-owned et différés.
+- [X] Ancien lifecycle/source terminal jamais rebinding vers une nouvelle instance.
+- [X] Aucun WorkerHandle générique imposé en V1.
+- [X] Aucun type transaction/slot/provider/endpoint/Store/replay/backfill/checkpoint dans la surface prévue.
+
+## 4. Surface et hardening à matérialiser
+
+### `pre.002`
+
+- [ ] `crates/ksp-worker-api` créée dans le workspace.
+- [ ] Manifest sans feature/dev/build dependency et avec Core uniquement.
+- [ ] `identity.rs`, `error.rs`, `lifecycle.rs`, `snapshot.rs`, `stop.rs`, `lib.rs` matérialisés.
+- [ ] Façade crate-root uniquement, aucun `pub mod`.
+- [ ] Quatre error codes stables `worker_api` matérialisés.
+- [ ] Bounds exacts identity testés.
+- [ ] Lifecycle transition matrix exacte testée.
+- [ ] Transition invalide conserve l’état source.
+- [ ] Stop token idempotent/shared testée.
+- [ ] Snapshot sequence/exhaustion testée.
+- [ ] Public API consumer depuis crate root testée.
+- [ ] Dependency firewall initial testée.
+
+### `pre.003`
+
+- [ ] Stop-vs-fault ordres adversariaux couverts.
+- [ ] Tous mutateurs refusent Stopped/Faulted.
+- [ ] Debug hostile identity redacted.
+- [ ] Snapshot ne contient aucun payload/string libre.
+- [ ] Stop token `Send + Sync` prouvé cross-thread.
+- [ ] `WorkerSnapshotSource: Send + Sync` prouvé.
+- [ ] `WorkerSnapshotSource` object-safe prouvé avec trait object.
+- [ ] Implémentation externe std-only compilée/testée.
+- [ ] Listeners lents indépendants resynchronisés vers latest value.
+- [ ] Late listener `current()` + séquence validés.
+- [ ] Snapshot terminal reste lisible.
+- [ ] Exact module inventory prouvé.
+- [ ] Exact crate-root export inventory prouvé.
+- [ ] Production sources sans Job/Config/Interface/Transport/Store/Tokio/futures/serde/Tauri/Solana.
+- [ ] Worker API déclarée fonctionnellement frozen avant tout audit RAW détaillé.
+
+## 5. Threat model à fermer
+
+- [X] Queue non bornée évitée architecturalement par latest-value.
+- [X] Slow-listener blocking évité architecturalement par coalescing/resync.
+- [X] Stale snapshot couvert par sequence monotone.
+- [X] Sequence wrap prévu comme erreur explicite.
+- [X] Stop répété couvert par token first-wins.
+- [X] Stop/fault terminal défini par first valid terminal transition.
+- [X] Old-handle/restart fermé par immutabilité + no rebind.
+- [X] Identity/log leakage réduit par bornes + Debug redaction.
+- [X] Arbitrary payload dans snapshot commun interdit par forme fixe.
+- [X] External error payload dans état interdit ; ErrorCode only.
+- [X] Health/lifecycle séparés.
+- [X] Fausse notion de completion/progress Worker interdite.
+- [X] Runtime ownership reste hors API.
+- [ ] Canaries Rust correspondantes exécutées après matérialisation.
+
+## 6. Audit RAW Transaction post-freeze
+
+Aucun item ci-dessous n’est déclaré exécuté en `pre.001`.
+
+### `pre.004` — Solana standard + KSP
+
+- [ ] Réaudit Solana JSON-RPC HTTP primaire.
+- [ ] Réaudit Solana WebSocket primaire.
+- [ ] Capabilities KSP Transport réellement publiques inventoriées.
+- [ ] Store RAW identity/content/provenance réconfirmés.
+- [ ] Config/secrets/network descriptors inventoriés pour handoff uniquement.
+- [ ] HTTP discovery/hydration roles classifiés.
+- [ ] WS logs/signature/block roles classifiés.
+- [ ] Live/catch-up/gap-repair/history applicability documentée.
+- [ ] `mainnet` / `mainnet-beta` audit interne commencé sans migration.
+
+### `pre.005` — providers + kbot3 historique
+
+- [ ] Helius HTTP standard Mainnet/Devnet réaudité sur sources officielles courantes.
+- [ ] Helius WS standard Mainnet/Devnet réaudité.
+- [ ] Helius transactionSubscribe/extensions réaudités séparément avec tier courant.
+- [ ] Yellowstone upstream transactions/transaction_status/blocks/block_meta réaudité.
+- [ ] Replay/from_slot réellement supporté classifié provider par provider.
+- [ ] Quotas/filter/subscription/reconnect limits sourcés.
+- [ ] Providers supplémentaires pertinents réaudités uniquement sur docs officielles.
+- [ ] kbot3 réaudité fonctionnellement : acquisition/live/history/recovery/fallback/provenance.
+- [ ] Aucun code/DTO/URL/Config/dependency kbot3 repris.
+
+### `pre.006` — synthèse et handoff
+
+- [ ] Matrice complète des dimensions imposées par le prompt 028.
+- [ ] Alternatives/complements/redundancy/specialization classifiés.
+- [ ] Discovery + hydration distingués des streams full transaction.
+- [ ] Dedup content vs observations de provenance explicitée.
+- [ ] Stratégie multi-source V1 `0.3.10` proposée sans enum protocole simpliste.
+- [ ] Gaps Transport `0.3.10` listés, non implémentés en `0.3.9`.
+- [ ] Gaps Config `0.3.10` listés, aucun nouvel endpoint ajouté en `0.3.9`.
+- [ ] Réutilisation unique `KSP_SECRET_HELIUS_API_KEY` confirmée.
+- [ ] Stratégie compatible `mainnet` / `mainnet-beta` conclue.
+- [ ] Applicability `0.3.12` Backfill indiquée par source/méthode.
+- [ ] `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md` créé comme owner de l’audit.
+
+## 7. Couloirs de fermeture
+
+### `pre.007` — gate technique final
+
+- [ ] `cargo fmt --all -- --check`.
+- [ ] audits Rust/Markdown complets.
+- [ ] `cargo check --workspace`.
+- [ ] `cargo clippy --workspace --all-targets --all-features -- -D warnings`.
+- [ ] `cargo test --workspace --all-targets --all-features`.
+- [ ] `cargo test -p ksp-worker-api`.
+- [ ] `cargo tree -p ksp-worker-api --edges normal`.
+- [ ] `cargo tree -p ksp-worker-api -e features`.
+- [ ] `cargo tree --duplicates`.
+
+### `pre.008` — réconciliation documentaire
+
+- [ ] Worker API README version-neutral de surface/responsabilités.
+- [ ] Worker API USAGE version-neutral avec exemples réutilisables.
+- [ ] Plan/validation réconciliés sur preuves réelles.
+- [ ] Architectures/index docs réconciliés.
+- [ ] Audit RAW final relu comme handoff 0.3.10/0.3.12.
+- [ ] Aucun CHANGELOG/ROADMAP/prompt suivant finalisé ici.
+
+### `pre.009` — publication
+
+- [ ] Prompt `0.3.10` produit depuis l’audit final.
+- [ ] CHANGELOG synchronisé.
+- [ ] ROADMAP synchronisé.
+- [ ] Cargo version mécanique synchronisée selon workflow.
+- [ ] Delta publication préparatoire minimal.
+
+### `rel.001`
+
+- [ ] Version stable `0.3.9` mécanique.
+- [ ] Aucun rattrapage fonctionnel/documentaire.
+- [ ] Commit/tag stable selon workflow.
+
+## 8. Versioning courant
+
+`pre.001` est doc-only et conserve :
+
+```text
+workspace.package.version = 0.3.8
+```
+
+Aucun code/build/runtime/config n’est modifié. Le premier changement Rust de la release est réservé à `pre.002`.