v0.3.12-pre.001
This commit is contained in:
1081
docs/plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md
Normal file
1081
docs/plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md
Normal file
File diff suppressed because it is too large
Load Diff
533
docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md
Normal file
533
docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md
Normal file
@@ -0,0 +1,533 @@
|
||||
<!-- file: docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Validation v0.3.12 — Yellowstone + hydration HTTP + continuité de run du Worker RawTransaction
|
||||
|
||||
## 1. Rôle du document
|
||||
|
||||
Ce document enregistre les preuves réellement exécutées, les non-claims et les gates progressifs de `0.3.12`. Une commande non exécutée n'est jamais déclarée PASS.
|
||||
|
||||
`pre.001` est un gate de lecture/audit/sizing. Il ne contient aucun code Worker réseau productif.
|
||||
|
||||
## 2. Gate `pre.001` — base stable
|
||||
|
||||
### 2.1 Archive contrôlée
|
||||
|
||||
```text
|
||||
archive : khadhroony-solana-project-v0.3.11.zip
|
||||
SHA-256 : a6bb59935650a7f48630d12ef80fbd1a44a84819dd129b085ff7f467369535fc
|
||||
bytes : 8125100
|
||||
entries : 1950
|
||||
unzip -t : PASS
|
||||
root unique : PASS
|
||||
absolute entries : 0
|
||||
path traversal : 0
|
||||
symlinks : 0
|
||||
.git/ : 0
|
||||
target/ : 0
|
||||
node_modules/ : 0
|
||||
Cargo.lock : 0
|
||||
.env : 0
|
||||
workspace members : 21
|
||||
workspace.package.version : 0.3.11
|
||||
```
|
||||
|
||||
`deltas/0.3.11/rel.001.md` est présent.
|
||||
|
||||
### 2.2 Préconditions fonctionnelles
|
||||
|
||||
Contrôlé dans la stable :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-transaction-ingest-lib présent
|
||||
README/USAGE présents
|
||||
aucun edge Worker -> Transport
|
||||
aucune source réseau productive dans src/
|
||||
ksp-raw-transaction-lib présent
|
||||
ksp-onchain-transport-lib présent avec Yellowstone gRPC générique
|
||||
ksp-store-lib présent
|
||||
ksp-job-backfill-lib ne dépend pas du Worker
|
||||
```
|
||||
|
||||
Résultat : PASS.
|
||||
|
||||
## 3. Baseline statique locale avant modification
|
||||
|
||||
Exécuté dans l'archive extraite :
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Résultat : PASS.
|
||||
|
||||
Exécuté :
|
||||
|
||||
```text
|
||||
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), 798 file(s))
|
||||
```
|
||||
|
||||
Résultat : PASS.
|
||||
|
||||
## 4. Cargo local dans l'environnement d'assemblage
|
||||
|
||||
`cargo` n'est pas installé dans l'environnement d'assemblage utilisé pour `pre.001`.
|
||||
|
||||
Non exécuté localement :
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
cargo test --workspace --all-targets --all-features
|
||||
cargo tree --duplicates
|
||||
```
|
||||
|
||||
Ces commandes ne sont pas déclarées PASS localement.
|
||||
|
||||
## 5. Preuve opérateur de la stable `0.3.11`
|
||||
|
||||
Le journal fourni avec la demande d'ouverture montre sur la stable :
|
||||
|
||||
```text
|
||||
cargo clean : exécuté
|
||||
cargo fmt --all -- --check : sans erreur visible
|
||||
audit Rust : clean
|
||||
audit Markdown : clean (340 tables, 798 fichiers)
|
||||
cargo check --workspace : terminé sans erreur
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings : terminé sans erreur
|
||||
cargo test --workspace : suites affichées vertes ; tests live opt-in ignorés conformément à leur contrat
|
||||
cargo tree Worker normal/features : demandé dans le journal opérateur
|
||||
```
|
||||
|
||||
Cette preuve opérateur concerne l'état stable d'entrée. Elle n'est pas réétiquetée comme exécution locale de `0.3.12-pre.001`.
|
||||
|
||||
## 6. Audit humain des règles
|
||||
|
||||
Sources lues pour le gate :
|
||||
|
||||
```text
|
||||
RULES.md
|
||||
ROADMAP.md
|
||||
CHANGELOG.md
|
||||
docs/000-README.md
|
||||
docs/rules/RULES_GENERAL.md
|
||||
docs/rules/RULES_KSP.md
|
||||
docs/rules/RULES_RUST.md
|
||||
docs/rules/RULES_DEPENDENCIES.md
|
||||
docs/rules/RULES_DOCUMENTATION.md
|
||||
docs/rules/FILE_CONTRACTS.md
|
||||
docs/rules/VERSION_WORKFLOW.md
|
||||
docs/rules/PROMPT_STRUCTURE.md
|
||||
```
|
||||
|
||||
Résultat : aucune divergence normative active nécessitant une correction de règle en `pre.001`.
|
||||
|
||||
Vérifications clés :
|
||||
|
||||
```text
|
||||
D2 reste STRUCTURAL
|
||||
nom Worker canonique = ksp-worker-raw-transaction-ingest-lib
|
||||
Worker/Job restent séparés
|
||||
Config reste propriétaire de l'environnement et des secrets
|
||||
Store backend direct reste interdit au Worker
|
||||
VER-ID-009 impose 0.3.12-pre.1 pour cette prerelease non-fix
|
||||
```
|
||||
|
||||
## 7. Sources internes de handoff auditées
|
||||
|
||||
Lecture/inventaire réalisés sur :
|
||||
|
||||
```text
|
||||
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
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/README.md
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/USAGE.md
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/src/
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/tests/
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/
|
||||
|
||||
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
|
||||
docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
|
||||
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
|
||||
crates/ksp-raw-transaction-lib/README.md
|
||||
crates/ksp-raw-transaction-lib/USAGE.md
|
||||
crates/ksp-raw-transaction-lib/src/
|
||||
crates/ksp-raw-transaction-lib/tests/
|
||||
|
||||
crates/ksp-onchain-transport-lib/Cargo.toml
|
||||
crates/ksp-onchain-transport-lib/README.md
|
||||
crates/ksp-onchain-transport-lib/USAGE.md
|
||||
crates/ksp-onchain-transport-lib/src/grpc_*.rs
|
||||
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
|
||||
crates/ksp-onchain-transport-lib/src/rpc_blocks.rs
|
||||
crates/ksp-onchain-transport-lib/tests/
|
||||
|
||||
crates/ksp-store-lib/README.md
|
||||
crates/ksp-store-lib/USAGE.md
|
||||
crates/ksp-store-lib/src/
|
||||
crates/ksp-worker-api/README.md
|
||||
crates/ksp-worker-api/USAGE.md
|
||||
crates/ksp-worker-api/src/
|
||||
crates/ksp-config-lib/README.md
|
||||
crates/ksp-config-lib/USAGE.md
|
||||
crates/ksp-config-lib/src/
|
||||
```
|
||||
|
||||
Le résultat d'inventaire est détaillé dans le plan `033`.
|
||||
|
||||
## 8. Preuve Worker stable
|
||||
|
||||
Le Worker stable possède exactement huit fichiers de production sous `src/` :
|
||||
|
||||
```text
|
||||
admission.rs
|
||||
error.rs
|
||||
identity.rs
|
||||
lib.rs
|
||||
persistence.rs
|
||||
runtime.rs
|
||||
settings.rs
|
||||
snapshot.rs
|
||||
```
|
||||
|
||||
Le manifest normal ne contient pas `ksp-onchain-transport-lib`, `ksp-config-lib`, `ksp-job-backfill-lib`, backend physique, Tonic, Reqwest ni Yellowstone proto.
|
||||
|
||||
Un scan source `grpc|yellowstone|http|ws|transport` ne révèle qu'une documentation signalant l'absence de source live ; aucun adapter réseau productif n'est présent.
|
||||
|
||||
Résultat : PASS pour la précondition `0.3.11`.
|
||||
|
||||
## 9. Preuve Transport actuelle
|
||||
|
||||
Contrats existants confirmés :
|
||||
|
||||
```text
|
||||
YellowstoneGrpcChannel::open_standard_subscribe
|
||||
SolanaYellowstoneGrpcSubscribeSession::next_update
|
||||
SolanaYellowstoneGrpcSubscribeSession::snapshot
|
||||
YellowstoneSubscribeRequest::set_from_slot
|
||||
YellowstoneReplayInfo::first_available
|
||||
HttpTransportPool::get_transaction_observed
|
||||
HttpTransportPool::get_block_observed
|
||||
HttpObservedValue::{value, endpoint_name, provider}
|
||||
```
|
||||
|
||||
Le snapshot Yellowstone indique explicitement :
|
||||
|
||||
```text
|
||||
continuity_gap_count : seulement gap prouvé par borne ReplayInfo
|
||||
replay_attempt_count : tentative, pas preuve de couverture
|
||||
duplicate_update_count : observabilité, duplicates toujours livrés
|
||||
last_requested_from_slot
|
||||
last_observed_slot
|
||||
```
|
||||
|
||||
Résultat : PASS pour la réutilisation du moteur existant.
|
||||
|
||||
## 10. Audit externe de fraîcheur
|
||||
|
||||
### 10.1 Yellowstone versions
|
||||
|
||||
Source docs.rs courante :
|
||||
|
||||
```text
|
||||
yellowstone-grpc-proto latest : 12.7.0
|
||||
publication : 2026-08-29
|
||||
workspace KSP : ^12.7
|
||||
```
|
||||
|
||||
Résultat : aucune mise à jour de dépendance nécessaire en `pre.001`.
|
||||
|
||||
### 10.2 Replay upstream
|
||||
|
||||
Le changelog upstream du 22 juillet 2026 documente la correction `yellowstone-grpc-geyser 14.2.1` pour un cas où `from_slot` + `blocks` était accepté mais aucun Block replay n'était livré avant reprise live.
|
||||
|
||||
Impact de validation :
|
||||
|
||||
```text
|
||||
subscribe accepted != replay proven
|
||||
from_slot sent != replay proven
|
||||
first_available compatible != replay proven
|
||||
```
|
||||
|
||||
Cette menace doit posséder un canari KSP et, si un provider live est disponible, un smoke dédié.
|
||||
|
||||
### 10.3 Solana HTTP
|
||||
|
||||
La documentation officielle courante confirme que `getTransaction` à `confirmed/finalized`, en Base64, fournit les champs nécessaires à la conversion Common RAW déjà qualifiée : `blockTime`, `meta`, `slot`, `transaction`, `version`.
|
||||
|
||||
Résultat : hydration `getTransaction` maintenue comme référence P0.
|
||||
|
||||
### 10.4 Providers
|
||||
|
||||
OrbitFlare documente encore Devnet gRPC et un free tier Devnet-only. Helius LaserStream documente Yellowstone wire compatibility et un replay provider-specific d'environ 216 000 slots / 24 heures. Ces valeurs ne sont pas transposées dans les constantes KSP.
|
||||
|
||||
PublicNode reste operator-only dans KSP ; aucune nouvelle assertion provider n'est ajoutée faute de source primaire indexée suffisamment précise pendant ce gate.
|
||||
|
||||
## 11. Gate de matrice Yellowstone fermé
|
||||
|
||||
### 11.1 Transaction
|
||||
|
||||
Preuve interne : `YellowstoneTransactionUpdate` contient slot, filter names, created_at et `YellowstoneTransactionInfo`; ce dernier contient signature, transaction, meta, index.
|
||||
|
||||
Conclusion : candidat hydration ; RAW-direct non prouvé.
|
||||
|
||||
### 11.2 TransactionStatus
|
||||
|
||||
Preuve interne : slot, signature, index, is_vote, error optionnelle.
|
||||
|
||||
Conclusion : discovery/hydration seulement.
|
||||
|
||||
### 11.3 Block
|
||||
|
||||
Preuve interne : slot, block_time, transactions avec transaction/meta/signature/index, compteurs et metadata block.
|
||||
|
||||
Conclusion : chaque transaction peut devenir candidat hydration ; aucun pipeline block RAW parallèle.
|
||||
|
||||
### 11.4 BlockMeta
|
||||
|
||||
Conclusion : continuity/health only ; aucune signature donc aucune hydration transaction autonome.
|
||||
|
||||
### 11.5 Slot
|
||||
|
||||
Conclusion : continuity/health only ; aucune admission RAW.
|
||||
|
||||
### 11.6 from_slot
|
||||
|
||||
Conclusion : mécanisme Transport de replay au reconnect, pas checkpoint historique Worker.
|
||||
|
||||
### 11.7 ReplayInfo
|
||||
|
||||
Conclusion : `first_available` prouve seulement une limite de rétention. Un gap est prouvé quand la demande est antérieure à cette borne ; le cas inverse ne prouve pas que toutes les updates filtrées ont été livrées.
|
||||
|
||||
## 12. Gate architecture d'injection fermé
|
||||
|
||||
Décision :
|
||||
|
||||
```text
|
||||
nouvel edge autorisé : Worker -> ksp-onchain-transport-lib
|
||||
Worker -> Config : interdit
|
||||
Worker -> Job : interdit
|
||||
Worker -> backend : interdit
|
||||
Worker -> Tonic/Reqwest/yellowstone-grpc-proto direct : non retenu
|
||||
```
|
||||
|
||||
La composition supérieure construit `YellowstoneGrpcChannel`, `YellowstoneSubscribeRequest`, `HttpTransportPool` et `HttpRoleName`. `pre.002` matérialise exactement :
|
||||
|
||||
```text
|
||||
RawTransactionIngestYellowstoneSource::new(...)
|
||||
RawTransactionIngestRuntimeResources::new(yellowstone_source)
|
||||
RawTransactionIngestWorker::start_with_runtime_resources(settings, Arc<Store>, resources)
|
||||
```
|
||||
|
||||
Les champs restent privés. `RawTransactionIngestWorker::start(settings, Arc<Store>)` reste disponible comme foundation source-neutral. Aucune API publique `enqueue` n'est ouverte.
|
||||
|
||||
## 13. Gate hydration/provenance fermé
|
||||
|
||||
Hydration P0 :
|
||||
|
||||
```text
|
||||
get_transaction_observed
|
||||
Base64
|
||||
confirmed/finalized uniquement
|
||||
maxSupportedTransactionVersion = 0
|
||||
```
|
||||
|
||||
Provenance : route composite encodée dans les champs `RawAcquisitionProvenance` existants, avec provider/endpoint réels du winner HTTP et identité sûre Yellowstone, sous `MAX_RAW_CODE_BYTES`. Aucune migration Store.
|
||||
|
||||
Un code composite impossible à représenter est rejeté ; aucune troncature silencieuse.
|
||||
|
||||
## 14. Gate continuité fermé
|
||||
|
||||
Décisions :
|
||||
|
||||
```text
|
||||
Transport high-watermark != Worker processing frontier
|
||||
processing frontier != blockchain completeness
|
||||
reconnect != replay
|
||||
replay != repair
|
||||
continuity gap prouvé => fault Worker sûr
|
||||
aucun Backfill automatique
|
||||
aucun checkpoint persistant inter-process
|
||||
pending hydration peut survivre au reconnect source dans le même run
|
||||
```
|
||||
|
||||
Le split `pre.007`/`pre.008` évite de coder frontier et replay semantics dans une seule tranche.
|
||||
|
||||
## 15. Threat model à transformer en tests
|
||||
|
||||
Canaris obligatoires :
|
||||
|
||||
```text
|
||||
secret/URL/header redaction
|
||||
remote status/error text not copied
|
||||
bounded signal/hydration queues
|
||||
bounded coalescence
|
||||
no duplicate HTTP in-flight for same key
|
||||
no double retry storm
|
||||
stop during connect/reconnect/hydration/replay
|
||||
no admission after stop frontier
|
||||
no orphan task after terminal
|
||||
counter checked arithmetic
|
||||
stale frontier never labelled complete
|
||||
continuity gap terminal and safe
|
||||
```
|
||||
|
||||
## 16. Smokes live
|
||||
|
||||
### 16.1 Disponibilité démontrée par le dépôt
|
||||
|
||||
Présents et ignored :
|
||||
|
||||
```text
|
||||
yellowstone_orbitflare_smoke
|
||||
yellowstone_publicnode_smoke
|
||||
```
|
||||
|
||||
Ils exigent des tokens fournis de manière operator-only.
|
||||
|
||||
### 16.2 Disponibilité opérateur pour `pre.001`
|
||||
|
||||
Aucun secret live n'est fourni dans l'archive. Le journal stable montre ces tests comme ignorés par défaut.
|
||||
|
||||
Résultat :
|
||||
|
||||
```text
|
||||
Worker live smoke : NON EXÉCUTÉ en pre.001
|
||||
raison : pipeline productif pas encore implémenté + secret/provider live non fourni au gate
|
||||
```
|
||||
|
||||
Aucun faux PASS live n'est enregistré.
|
||||
|
||||
## 17. Graphe Cargo cible vérifiable à partir de `pre.002`
|
||||
|
||||
Attendu :
|
||||
|
||||
```text
|
||||
Worker -> core
|
||||
Worker -> logging
|
||||
Worker -> onchain-transport
|
||||
Worker -> raw-transaction
|
||||
Worker -> store facade default-features=false
|
||||
Worker -> worker-api
|
||||
Worker -> sha2
|
||||
Worker -> tokio
|
||||
```
|
||||
|
||||
Toujours absent :
|
||||
|
||||
```text
|
||||
Config
|
||||
Job Backfill
|
||||
Store backend
|
||||
Tauri
|
||||
provider SDK
|
||||
Tonic direct
|
||||
Reqwest direct
|
||||
Yellowstone proto direct
|
||||
```
|
||||
|
||||
## 18. Sizing et décision release
|
||||
|
||||
Forecast retenu :
|
||||
|
||||
```text
|
||||
pre.001 audit/sizing/plan
|
||||
pre.002 Transport resource/source contract
|
||||
pre.003 Transaction + TransactionStatus signal adapters
|
||||
pre.004 HTTP hydration + provenance composite
|
||||
pre.005 Block + BlockMeta + Slot adapters
|
||||
pre.006 productive source task + supervisor/coalescence
|
||||
pre.007 processing frontier
|
||||
pre.008 reconnect/from_slot/ReplayInfo
|
||||
pre.009 races/retry/backpressure hardening
|
||||
pre.010 cross-layer completeness/security
|
||||
pre.011 technical/live gate
|
||||
pre.012 documentation reconciliation
|
||||
pre.013 publication preparation
|
||||
rel.001
|
||||
```
|
||||
|
||||
Décision : `0.3.12` reste ouverte et n'est pas rescindée. Toute tranche dépassant réellement 15–20 minutes est scindée avant exécution.
|
||||
|
||||
## 19. Validation après modification de `pre.001`
|
||||
|
||||
Exécuté sur le delta complet :
|
||||
|
||||
```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), 801 file(s))
|
||||
```
|
||||
|
||||
Résultat : PASS pour les audits statiques locaux.
|
||||
|
||||
Cargo reste NON EXÉCUTÉ localement car l'outil n'est pas installé.
|
||||
|
||||
Le gate opérateur demandé après application du delta est :
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
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
|
||||
```
|
||||
|
||||
`pre.001` n'ajoutant aucun Rust, les tests ciblés Worker restent une preuve de non-régression facultative mais recommandée :
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
## 20. Non-claims `pre.001`
|
||||
|
||||
`pre.001` ne prétend pas avoir :
|
||||
|
||||
```text
|
||||
ajouté l'edge Worker -> Transport dans Cargo
|
||||
ouvert une session Yellowstone dans le Worker
|
||||
hydraté une transaction live
|
||||
persisté un RAW live Yellowstone
|
||||
prouvé un RAW-direct Yellowstone
|
||||
prouvé un replay provider complet
|
||||
implémenté une frontier
|
||||
implémenté un repair
|
||||
enrichi les snapshots runtime
|
||||
exécuté un smoke live Worker
|
||||
exécuté Cargo dans l'environnement d'assemblage
|
||||
```
|
||||
|
||||
## 21. Critère de sortie `pre.001`
|
||||
|
||||
Le gate est fermé si :
|
||||
|
||||
```text
|
||||
base stable prouvée
|
||||
règles auditées
|
||||
surfaces internes inventoriées
|
||||
fraîcheur externe auditée
|
||||
matrice Yellowstone fermée
|
||||
injection runtime décidée
|
||||
hydration/provenance décidées
|
||||
frontier/replay/repair distingués
|
||||
threat model défini
|
||||
smokes classifiés
|
||||
Cargo graph cible défini
|
||||
forecast <20 min par tranche
|
||||
maintien/split décidé
|
||||
plan + validation + delta créés
|
||||
audits statiques post-modification verts
|
||||
```
|
||||
Reference in New Issue
Block a user