v0.3.13-pre.001
This commit is contained in:
494
docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
Normal file
494
docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
Normal file
@@ -0,0 +1,494 @@
|
||||
<!-- file: docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Validation v0.3.13 — WS standard / Helius / HTTP live + convergence multi-source
|
||||
|
||||
## 1. Rôle
|
||||
|
||||
Ce document enregistre les preuves réellement exécutées et les non-claims de `0.3.13`. `pre.001` est exclusivement un gate d'archive, règles, audit, brainstorming, sizing et planification ; aucune nouvelle source live productive n'est codée dans cette tranche.
|
||||
|
||||
## 2. Archive stable contrôlée
|
||||
|
||||
```text
|
||||
archive : khadhroony-solana-project-v0.3.12.zip
|
||||
SHA-256 : 85c41eb9f8575ee58edd9863445cbc37b79ef59c4a7cf882679ff24dc8991bf5
|
||||
bytes : 8260528
|
||||
entries : 1981
|
||||
files : 1788
|
||||
directories : 193
|
||||
absolute entries : 0
|
||||
parent traversal entries : 0
|
||||
duplicate entries : 0
|
||||
symlink entries : 0
|
||||
workspace members : 21
|
||||
crate manifests : 21
|
||||
workspace.package.version : 0.3.12
|
||||
edition : 2024
|
||||
stable delta : deltas/0.3.12/rel.001.md
|
||||
```
|
||||
|
||||
Résultat structurel : PASS.
|
||||
|
||||
Artefacts interdits recherchés :
|
||||
|
||||
```text
|
||||
Cargo.lock : absent
|
||||
rust-toolchain.toml : absent
|
||||
rust-toolchain : absent
|
||||
package-lock.json : absent
|
||||
pnpm-lock.yaml : absent
|
||||
yarn.lock : absent
|
||||
.env : absent
|
||||
```
|
||||
|
||||
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/0.3.12
|
||||
Markdown table audit: clean (306 table(s), 199 file(s))
|
||||
```
|
||||
|
||||
Résultat : PASS.
|
||||
|
||||
## 4. Preuve opérateur stable fournie
|
||||
|
||||
Le journal opérateur fourni avec l'ouverture `0.3.13` montre sur `0.3.12` :
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check : terminé sans erreur visible
|
||||
audit Rust : clean, export completeness 0
|
||||
audit Markdown ciblé stable : clean (306 tables, 199 fichiers)
|
||||
cargo check --workspace : terminé avec succès
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings : terminé avec succès
|
||||
cargo test -p ksp-worker-raw-transaction-ingest-lib : vert
|
||||
cargo tree Worker --edges normal : produit
|
||||
cargo tree Worker -e features : produit
|
||||
```
|
||||
|
||||
Suites Worker affichées :
|
||||
|
||||
```text
|
||||
unit : 66 pass
|
||||
cross_layer_completeness : 4 pass
|
||||
dependency_boundary : 9 pass
|
||||
hardening : 16 pass
|
||||
public_api : 9 pass
|
||||
release_completeness : 4 pass
|
||||
doc-tests : 0
|
||||
```
|
||||
|
||||
Cette preuve concerne la stable d'entrée. Elle n'est pas présentée comme une exécution locale post-modification de `pre.001`.
|
||||
|
||||
## 5. Cargo local dans l'environnement d'assemblage
|
||||
|
||||
`cargo` et `rustfmt` ne sont pas installés dans l'environnement d'assemblage courant.
|
||||
|
||||
Non exécuté localement avant ou après modification :
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check
|
||||
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
|
||||
cargo tree --duplicates
|
||||
```
|
||||
|
||||
Aucune de ces commandes n'est déclarée PASS localement.
|
||||
|
||||
## 6. Audit des règles
|
||||
|
||||
Documents normatifs audités :
|
||||
|
||||
```text
|
||||
RULES.md
|
||||
docs/rules/RULES_GENERAL.md
|
||||
docs/rules/RULES_RUST.md
|
||||
docs/rules/RULES_KSP.md
|
||||
docs/rules/RULES_DEPENDENCIES.md
|
||||
docs/rules/RULES_DOCUMENTATION.md
|
||||
docs/rules/PROMPT_STRUCTURE.md
|
||||
docs/rules/FILE_CONTRACTS.md
|
||||
docs/rules/VERSION_WORKFLOW.md
|
||||
docs/rules/SCENARIO_CONVENTION.md
|
||||
```
|
||||
|
||||
Scan supplémentaire des identifiants normatifs :
|
||||
|
||||
```text
|
||||
fichiers de règles : 10
|
||||
rule ids détectés : 489
|
||||
rule ids uniques : 488
|
||||
collision : KSP-CONFIG-018 x2
|
||||
```
|
||||
|
||||
Le dépôt stable ne contenait pas de contradiction de contenu entre ces deux règles, mais l'identifiant normatif n'était pas unique.
|
||||
|
||||
Preuve historique : `deltas/0.1.3/pre.014.md` définit explicitement l'inventaire `.env.example` comme `KSP-CONFIG-018`. La règle desktop est donc renumérotée `KSP-CONFIG-019` dans `pre.001` ; aucun texte de règle n'est affaibli ni supprimé.
|
||||
|
||||
## 7. Audit dépendances et frontières
|
||||
|
||||
Contrôlé statiquement :
|
||||
|
||||
```text
|
||||
21 crates = 21 workspace members
|
||||
aucune version package explicite hors workspace inheritance
|
||||
aucune edition crate divergente
|
||||
ksp-worker-raw-transaction-ingest-lib dépend de ksp-onchain-transport-lib
|
||||
Worker ne dépend pas de ksp-config-lib
|
||||
Worker ne dépend pas de ksp-job-backfill-lib
|
||||
Worker ne dépend pas de ksp-store-postgres-lib
|
||||
Worker ne dépend pas directement de reqwest/tonic/yellowstone-grpc-proto
|
||||
Store physique absent du Worker
|
||||
```
|
||||
|
||||
La primitive `solana-keypair` présente dans `ksp-wallet-lib` est autorisée explicitement par `DEP-SOL-004` et n'est pas une violation.
|
||||
|
||||
Résultat : aucune violation de dépendance stable identifiée par cet audit.
|
||||
|
||||
## 8. Handoff 0.3.12 vérifié
|
||||
|
||||
Sources lues :
|
||||
|
||||
```text
|
||||
docs/plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md
|
||||
docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.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/
|
||||
```
|
||||
|
||||
Contrats stables confirmés :
|
||||
|
||||
```text
|
||||
une source Yellowstone caller-composed
|
||||
hydratation getTransaction observed
|
||||
coalescence network/signature/commitment
|
||||
source_key opaque 32 bytes
|
||||
observation key = domain + network + signature + source_key
|
||||
admission centrale bounded mpsc
|
||||
canonicalisation Common RAW avant Store
|
||||
persistence atomique transaction + observation
|
||||
processing frontier run-local
|
||||
reconnect/replay/gap sans repair
|
||||
```
|
||||
|
||||
## 9. Common RAW et Store vérifiés
|
||||
|
||||
`ksp-raw-transaction-lib` expose :
|
||||
|
||||
```text
|
||||
RawTransactionMaterial
|
||||
canonicalize_raw_transaction
|
||||
assemble_raw_transaction_acquisition
|
||||
wire Legacy/V0/V1
|
||||
```
|
||||
|
||||
`ksp-store-api` / `ksp-store-lib` exposent déjà deux capabilities distinctes utiles à la convergence :
|
||||
|
||||
```text
|
||||
persist_raw_transaction_acquisition(transaction, observation, Normal)
|
||||
record_raw_transaction_observation(observation)
|
||||
```
|
||||
|
||||
La seconde est explicitement conçue pour une observation supplémentaire d'une transaction déjà persistée sans resoumettre le payload canonique.
|
||||
|
||||
Conclusion : aucun changement Store API n'est requis par le design `pre.001`.
|
||||
|
||||
## 10. Transport WS/HTTP vérifié
|
||||
|
||||
Surface standard :
|
||||
|
||||
```text
|
||||
SolanaStandardWsSession::connect
|
||||
logs_subscribe
|
||||
block_subscribe
|
||||
shared WsSession actor
|
||||
reconnect/resubscribe Transport-owned
|
||||
```
|
||||
|
||||
Surface Helius :
|
||||
|
||||
```text
|
||||
HeliusLaserStreamWsSession::connect
|
||||
transaction_subscribe
|
||||
shared WsSession actor
|
||||
pas d'escape hatch générique
|
||||
blockSubscribe volontairement non exposé sur Helius facade
|
||||
```
|
||||
|
||||
Surface HTTP :
|
||||
|
||||
```text
|
||||
get_transaction_observed
|
||||
get_block_observed
|
||||
get_slot
|
||||
get_blocks
|
||||
get_blocks_with_limit
|
||||
```
|
||||
|
||||
Conclusion : aucun nouveau client HTTP/WS ni nouvelle dépendance réseau n'est requis dans Worker.
|
||||
|
||||
## 11. Config/secrets vérifiés
|
||||
|
||||
`config/std.transport.json` contient les profils committed standard/public actuels. `config/examples/std.transport.example.json` démontre déjà les formes Helius LaserStream Mainnet/Devnet.
|
||||
|
||||
`KSP_SECRET_HELIUS_API_KEY` existe déjà dans l'inventaire `.env.example` et dans les contrats Config/tests concernés.
|
||||
|
||||
Conclusion pre.001 :
|
||||
|
||||
```text
|
||||
aucune nouvelle variable secret
|
||||
aucun profil Config ajouté dans cette tranche
|
||||
Config reste hors Worker
|
||||
pre.005 décidera un profil committed seulement si un consumer/smoke concret le justifie
|
||||
```
|
||||
|
||||
## 12. Audit externe courant
|
||||
|
||||
Consulté le 10 septembre 2026.
|
||||
|
||||
### 12.1 logsSubscribe
|
||||
|
||||
Solana confirme `all`, `allWithVotes` et `mentions` avec un seul pubkey par appel. La notification contient contexte/slot, signature, erreur et logs mais pas le RAW complet.
|
||||
|
||||
Décision : hydration obligatoire.
|
||||
|
||||
### 12.2 blockSubscribe
|
||||
|
||||
Solana maintient la méthode comme instable et conditionnée à l'activation validator. Commitment `confirmed`/`finalized` seulement.
|
||||
|
||||
Le guide Transaction V1 courant impose la préparation `maxSupportedTransactionVersion = 1`; sinon V1 peut provoquer `-32015` en HTTP et `block:null`/stagnation côté blockSubscribe.
|
||||
|
||||
Décision : toutes les nouvelles requêtes transaction/block de `0.3.13` utilisent `1` lorsque la surface le permet. La qualification RAW-direct V1 reste test-gated en `pre.004`.
|
||||
|
||||
### 12.3 Helius
|
||||
|
||||
La référence Helius courante liste `transactionSubscribe` comme extension supportée et `blockSubscribe` parmi les méthodes instables non supportées sur LaserStream WSS.
|
||||
|
||||
Le pricing courant place `transactionSubscribe` à partir de Developer, pas sur Free.
|
||||
|
||||
Décision : aucun tier n'est codé ; smoke live conditionnel.
|
||||
|
||||
Sources :
|
||||
|
||||
```text
|
||||
https://solana.com/docs/rpc/websocket/logssubscribe
|
||||
https://solana.com/docs/rpc/websocket/blocksubscribe
|
||||
https://solana.com/docs/core/transactions/versioned-transactions
|
||||
https://www.helius.dev/docs/api-reference/rpc/websocket-methods
|
||||
https://www.helius.dev/pricing
|
||||
```
|
||||
|
||||
## 13. Contrats de source fermés par pre.001
|
||||
|
||||
### 13.1 Yellowstone
|
||||
|
||||
```text
|
||||
input : channel/request + HTTP pool/role
|
||||
output : reference signal + continuity
|
||||
bound : Transport + global Worker queue
|
||||
retry/reconnect : Transport
|
||||
proof : non-regression 0.3.12
|
||||
```
|
||||
|
||||
### 13.2 Standard logs
|
||||
|
||||
```text
|
||||
input : standard WS endpoint/filter/confirmed-or-finalized + HTTP pool/role
|
||||
output : signature/slot reference signal
|
||||
bound : WS notification queue + global Worker queue
|
||||
retry/reconnect : Transport WS
|
||||
hydration retry : Transport HTTP
|
||||
proof : deterministic notification -> one observed getTransaction -> RAW golden
|
||||
```
|
||||
|
||||
### 13.3 Standard block
|
||||
|
||||
```text
|
||||
input : standard WS + full/base64 + confirmed/finalized + maxVersion=1
|
||||
output : complete material for qualified versions
|
||||
bound : WS queue + global Worker queue
|
||||
retry/reconnect : Transport WS
|
||||
proof : RAW parity Legacy/V0, V1 dedicated fixture, block:null canary
|
||||
```
|
||||
|
||||
### 13.4 Helius transaction
|
||||
|
||||
```text
|
||||
input : Helius WS + full/base64 + maxVersion=1 + HTTP pool/role
|
||||
output : reference signal then hydration
|
||||
bound : Transport Helius filters/queue + global Worker queue
|
||||
retry/reconnect : Transport WS
|
||||
hydration retry : Transport HTTP
|
||||
proof : deterministic Helius notification -> RAW golden; live conditional
|
||||
```
|
||||
|
||||
### 13.5 HTTP live polling
|
||||
|
||||
```text
|
||||
input : HTTP pool/roles + confirmed/finalized + polling settings
|
||||
run bound : getSlot at source start; never scan lower slot
|
||||
output : getBlock observed transactions
|
||||
source timer owner : Worker
|
||||
HTTP retry/rate-limit : Transport
|
||||
proof : deterministic tip/skipped/null/stop tests
|
||||
```
|
||||
|
||||
## 14. Bornes fermées
|
||||
|
||||
```text
|
||||
live sources : 1..32
|
||||
source signal queue : settings.admission_queue_capacity()
|
||||
pending signals global : <= settings.admission_queue_capacity()
|
||||
hydration in-flight : <= settings.persistence_concurrency()
|
||||
no provider-private unbounded Worker queue
|
||||
HTTP poll interval : 100 ms .. 30 s, default 1 s
|
||||
HTTP poll max blocks/cycle : 1 .. 1024, default 128
|
||||
```
|
||||
|
||||
Ces bornes sont des décisions de plan à matérialiser/tester dans les prereleases techniques correspondantes ; elles ne sont pas encore une API de `pre.001`.
|
||||
|
||||
## 15. Convergence et observations
|
||||
|
||||
Décision : coalescence avant hydration par `(network, signature, commitment)` pour toutes les sources reference-only.
|
||||
|
||||
Une hydration peut servir plusieurs observation seeds. Après canonicalisation :
|
||||
|
||||
```text
|
||||
première observation : persistence atomique entity + observation
|
||||
suivantes : record_raw_transaction_observation
|
||||
```
|
||||
|
||||
Même identité/content identique : idempotent.
|
||||
|
||||
Même identité/content divergent : content conflict explicite et terminal.
|
||||
|
||||
## 16. Health/terminalité
|
||||
|
||||
L'inventaire de sources reste interne et borné. La projection publique future est source-neutral et agrège des counts d'états sans provider material.
|
||||
|
||||
Décision conservative : un `Failed` terminal d'une source configurée reste terminal pour le Worker en `0.3.13`, car aucune preuve de coverage équivalent n'existe encore. Failover/degraded non-terminal appartient au gap-repair/coverage `0.3.14`.
|
||||
|
||||
## 17. Sizing
|
||||
|
||||
Release maintenue avec :
|
||||
|
||||
```text
|
||||
pre.002 resources multi-source
|
||||
pre.003 logs + hydration
|
||||
pre.004 blockSubscribe
|
||||
pre.005 Helius
|
||||
pre.006 HTTP polling
|
||||
pre.007 supervisor/inventory
|
||||
pre.008 convergence/observations
|
||||
pre.009 conflict/backpressure/fairness
|
||||
pre.010 snapshot/health
|
||||
pre.011 races/shutdown
|
||||
pre.012 completeness/security
|
||||
pre.013 gate technique/live
|
||||
pre.014 documentation
|
||||
pre.015 publication prep
|
||||
rel.001 stable
|
||||
```
|
||||
|
||||
Aucune responsabilité de fermeture n'est fusionnée.
|
||||
|
||||
## 18. Non-claims pre.001
|
||||
|
||||
`pre.001` ne prétend pas :
|
||||
|
||||
```text
|
||||
avoir ajouté une source productive
|
||||
avoir modifié le runtime Worker multi-source
|
||||
avoir exécuté un smoke Helius
|
||||
avoir prouvé blockSubscribe V1 en live
|
||||
avoir exécuté cargo dans l'environnement d'assemblage
|
||||
avoir implémenté gap repair/failover
|
||||
avoir ajouté un profil Config Helius committed
|
||||
```
|
||||
|
||||
## 19. Validation post-modification pre.001
|
||||
|
||||
Exécuté :
|
||||
|
||||
```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), 828 file(s))
|
||||
```
|
||||
|
||||
Résultat : PASS.
|
||||
|
||||
Exécuté :
|
||||
|
||||
```text
|
||||
supplemental normative rule-id scan
|
||||
489 ids, 489 uniques, 0 duplicate
|
||||
```
|
||||
|
||||
Résultat : PASS.
|
||||
|
||||
Comparaison exhaustive du working tree avec l'archive stable après suppression du cache Python généré par l'audit :
|
||||
|
||||
```text
|
||||
added : 3
|
||||
deltas/0.3.13/pre.001.md
|
||||
docs/plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md
|
||||
docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
|
||||
modified : 2
|
||||
Cargo.toml
|
||||
docs/rules/RULES_KSP.md
|
||||
deleted : 0
|
||||
extra/unexpected : 0
|
||||
```
|
||||
|
||||
Résultat : PASS.
|
||||
|
||||
Cargo post-modification reste `NON EXÉCUTÉ LOCAL` parce que le toolchain n'est pas disponible.
|
||||
|
||||
## 20. Gate opérateur requis avant pre.002
|
||||
|
||||
Après application du delta :
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
`pre.002` ne doit pas commencer si cette livraison révèle une anomalie de règles/version/archive non corrigée.
|
||||
Reference in New Issue
Block a user