v0.3.11-pre.001
This commit is contained in:
@@ -0,0 +1,444 @@
|
||||
<!-- file: docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Validation v0.3.11 — fondation runtime du Worker RawTransaction ingest
|
||||
|
||||
## 1. Rôle du document
|
||||
|
||||
Ce document suit les preuves de `0.3.11` pour `ksp-worker-raw-transaction-ingest-lib`.
|
||||
|
||||
Il distingue explicitement :
|
||||
|
||||
```text
|
||||
preuve exécutée dans l'environnement d'assemblage
|
||||
preuve opérateur fournie sur la stable de base
|
||||
preuve planifiée pour une tranche future
|
||||
preuve non applicable au scope 0.3.11
|
||||
```
|
||||
|
||||
Aucune commande Cargo non exécutée localement n'est déclarée PASS.
|
||||
|
||||
## 2. Gate `pre.001` — audit/sizing/plan
|
||||
|
||||
État : **fermé pour la planification**. Le gate statique/Markdown final du delta complet est PASS dans l’environnement d’assemblage ; les gates Cargo restent non exécutables localement.
|
||||
|
||||
### 2.1 Archive stable contrôlée
|
||||
|
||||
```text
|
||||
archive : khadhroony-solana-project-v0.3.10.zip
|
||||
SHA-256 : befafea61304aaea15c94db7c8b3525c58b7c1622bf880a9110373bcc0ae6ac0
|
||||
bytes : 7993096
|
||||
entries : 1901
|
||||
unzip -t : PASS
|
||||
racine unique : khadhroony-solana-project
|
||||
workspace.package.version : 0.3.10
|
||||
workspace members : 20
|
||||
stable delta : deltas/0.3.10/rel.001.md
|
||||
```
|
||||
|
||||
Sécurité/forme :
|
||||
|
||||
```text
|
||||
absolute entries : 0
|
||||
path traversal entries : 0
|
||||
symlinks : 0
|
||||
.git/ : 0
|
||||
target/ : 0
|
||||
node_modules/ : 0
|
||||
Cargo.lock : 0
|
||||
.env : 0
|
||||
workspace member manifest missing : 0
|
||||
```
|
||||
|
||||
Préconditions fonctionnelles :
|
||||
|
||||
```text
|
||||
ksp-raw-transaction-lib : présent + README/USAGE/src/tests/unit_tests
|
||||
ksp-worker-api : présent
|
||||
ksp-job-backfill-lib : présent
|
||||
Backfill -> ksp-raw-transaction-lib : présent
|
||||
ksp-worker-raw-transaction-ingest-lib : absent
|
||||
```
|
||||
|
||||
### 2.2 Baseline statique exécutée avant modification
|
||||
|
||||
```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), 772 file(s))
|
||||
```
|
||||
|
||||
Les audits automatiques sont verts mais ne détectent pas toutes les contradictions sémantiques entre règles ; la lecture humaine reste obligatoire.
|
||||
|
||||
### 2.3 Cargo local
|
||||
|
||||
```text
|
||||
cargo : indisponible dans l'environnement d'assemblage
|
||||
```
|
||||
|
||||
Donc, pour `pre.001` local :
|
||||
|
||||
```text
|
||||
cargo fmt : NON EXÉCUTÉ
|
||||
cargo check : NON EXÉCUTÉ
|
||||
cargo clippy: NON EXÉCUTÉ
|
||||
cargo test : NON EXÉCUTÉ
|
||||
cargo tree : NON EXÉCUTÉ
|
||||
```
|
||||
|
||||
### 2.4 Preuve opérateur de la stable `0.3.10`
|
||||
|
||||
Le journal opérateur fourni le 8 septembre 2026 montre sur la base stable `0.3.10` :
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check : terminé sans erreur
|
||||
Rust rule audit : clean
|
||||
Markdown audit : clean dans l'environnement opérateur
|
||||
cargo check --workspace : terminé sans erreur
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings : terminé sans erreur
|
||||
```
|
||||
|
||||
Suites ciblées communiquées :
|
||||
|
||||
```text
|
||||
ksp-raw-transaction-lib : 26 tests verts au total
|
||||
ksp-job-backfill-lib : 77 tests verts au total
|
||||
```
|
||||
|
||||
Les arbres normaux des deux crates ont également été fournis. Cette preuve confirme la qualité de la stable opérateur ; elle ne remplace pas les futurs gates Cargo de `0.3.11-pre.*`.
|
||||
|
||||
## 3. Audit humain des règles
|
||||
|
||||
### 3.1 Divergence D2
|
||||
|
||||
Défaut trouvé dans la stable :
|
||||
|
||||
```text
|
||||
RULES_KSP / KSP-DURABLE-002 : D2 encore nommé Core canonique
|
||||
RULES_KSP / KSP-DURABLE-006 : instructions encore appelées faits Core
|
||||
RULES_DEPENDENCIES / DEP-STORE-004 : D2 encore nommé Core canonique
|
||||
```
|
||||
|
||||
Ces formulations contredisent les règles actives plus récentes et `docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md` :
|
||||
|
||||
```text
|
||||
RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
Correction `pre.001` : règles actives normalisées vers D1 `RAW`, D2 `STRUCTURAL`, D3 `DECODED`, D4 `DOMAIN`. Les traces historiques ne sont pas réécrites.
|
||||
|
||||
### 3.2 Ancien nom Worker
|
||||
|
||||
Défaut trouvé dans :
|
||||
|
||||
```text
|
||||
KSP-WORKER-005
|
||||
KSP-WORKER-006
|
||||
KSP-WORKER-007
|
||||
KSP-WORKER-010
|
||||
```
|
||||
|
||||
Ancien nom :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-retriever
|
||||
```
|
||||
|
||||
Nom durable confirmé par architecture/ROADMAP/CHANGELOG/handoff/prompt :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-transaction-ingest-lib
|
||||
```
|
||||
|
||||
Correction `pre.001` : normalisation du nom uniquement, sans changement de responsabilité des règles.
|
||||
|
||||
### 3.3 Tension Store API/façade Worker auditée
|
||||
|
||||
`DEP-WORKER-003` privilégie l'injection d'APIs pour la logique réutilisable ; `DEP-STORE-010`, l'architecture `011` et le prompt `030` autorisent/ordonnent la façade `ksp-store-lib` pour le producer runtime concret.
|
||||
|
||||
Décision : pas de nouvelle règle nécessaire. La crate concrète dépend de `ksp-store-lib default-features=false`, tandis que la logique de persistence reste derrière un port privé testable. Aucun backend physique n'entre dans la crate.
|
||||
|
||||
## 4. Inventaire des surfaces de référence
|
||||
|
||||
### 4.1 Worker API
|
||||
|
||||
Surface crate-root constatée :
|
||||
|
||||
```text
|
||||
WorkerId
|
||||
WorkerKindCode
|
||||
WorkerState
|
||||
WorkerHealth
|
||||
WorkerActivity
|
||||
WorkerLifecycle
|
||||
WorkerStopToken
|
||||
WorkerSnapshotSequence
|
||||
WorkerSnapshot
|
||||
WorkerSnapshotFuture
|
||||
WorkerSnapshotSource
|
||||
```
|
||||
|
||||
Aucun runtime Tokio, Store, Transport, Config ou type Solana n'est présent.
|
||||
|
||||
### 4.2 Common RAW
|
||||
|
||||
Surface pertinente constatée :
|
||||
|
||||
```text
|
||||
RawTransactionMaterial
|
||||
RawTransactionWireField
|
||||
RawTransactionVersion
|
||||
canonicalize_raw_transaction
|
||||
RawTransactionAcquisition
|
||||
assemble_raw_transaction_acquisition
|
||||
signature/wire helpers
|
||||
```
|
||||
|
||||
La crate dépend de `ksp-store-api` pour les modèles persistables mais reste sans runtime/Transport/Worker/Job/backend.
|
||||
|
||||
### 4.3 Store
|
||||
|
||||
Contrat atomique pertinent :
|
||||
|
||||
```text
|
||||
RawTransactionWrite::persist_raw_transaction_acquisition
|
||||
RawTransactionAcquisitionMode::Normal
|
||||
RawAcquisitionWriteOutcome
|
||||
RawEntityWriteOutcome
|
||||
RawObservationWriteOutcome
|
||||
ERROR_CODE_RAW_CONFLICT
|
||||
```
|
||||
|
||||
`Store` est non-Clone et possède son propre close ; le Worker recevra donc `Arc<Store>` et ne prendra pas la responsabilité de le fermer.
|
||||
|
||||
### 4.4 Backfill
|
||||
|
||||
Patterns vérifiés :
|
||||
|
||||
```text
|
||||
RawTransactionPersistencePort privé
|
||||
Store network check avant write
|
||||
mapping explicite conflict vs idempotence
|
||||
watch/latest-value runtime
|
||||
cancellation et terminal
|
||||
security hardening tests
|
||||
```
|
||||
|
||||
Aucun scope/checkpoint Job n'est transféré au Worker.
|
||||
|
||||
## 5. Fraîcheur des dépendances
|
||||
|
||||
Vérifié le 8 septembre 2026 sur les documentations courantes :
|
||||
|
||||
```text
|
||||
tokio 1.53.1
|
||||
futures-util 0.3.34
|
||||
sha2 0.11.0
|
||||
```
|
||||
|
||||
Constats :
|
||||
|
||||
```text
|
||||
Tokio spawn/JoinHandle -> feature rt
|
||||
Tokio mpsc/watch -> feature sync
|
||||
Tokio select! -> feature macros
|
||||
Tokio timeout/time -> feature time
|
||||
bounded mpsc applique du backpressure
|
||||
watch ne retient que la dernière valeur
|
||||
JoinHandle droppé détache la tâche -> handles privés doivent rester possédés/joints
|
||||
```
|
||||
|
||||
Décision : aucun bump workspace. Le futur manifest Worker prévoit Tokio direct avec `macros,rt,sync,time`, `sha2` pour la key domain-separated, et aucun `futures-util` ni Transport tant qu'un usage réel n'est pas matérialisé.
|
||||
|
||||
## 6. Questions `pre.001` fermées
|
||||
|
||||
### 6.1 Settings
|
||||
|
||||
Surface minimale retenue :
|
||||
|
||||
```text
|
||||
network
|
||||
worker_id
|
||||
admission_queue_capacity
|
||||
persistence_concurrency
|
||||
shutdown_drain_timeout
|
||||
```
|
||||
|
||||
Bornes retenues :
|
||||
|
||||
```text
|
||||
queue : 1..=65_536, default 256
|
||||
persistence concurrency : 1..=64, default 8
|
||||
drain : 100 ms..=30 s, default 5 s
|
||||
```
|
||||
|
||||
### 6.2 Source types
|
||||
|
||||
Décision : `SourceId`, capability, role, continuity et settings provider restent privés/absents en `0.3.11`. Ils ne seront publics qu'avec une première source productive en `0.3.12+`.
|
||||
|
||||
### 6.3 Start/handle
|
||||
|
||||
Décision :
|
||||
|
||||
```text
|
||||
RawTransactionIngestWorker::start(settings, Arc<Store>) -> Result<Handle>
|
||||
request_stop idempotent
|
||||
snapshot_source concret
|
||||
projection WorkerSnapshot commune
|
||||
wait_terminal async boxed sans JoinHandle public
|
||||
```
|
||||
|
||||
### 6.4 Supervisor/tasks
|
||||
|
||||
Décision : supervisor unique privé, `JoinSet`/JoinHandle privés, ownership intégral jusqu'au terminal.
|
||||
|
||||
### 6.5 Channels
|
||||
|
||||
Décision :
|
||||
|
||||
```text
|
||||
1 mpsc borné pour admission
|
||||
1 watch latest-value pour snapshot concret
|
||||
1 watch privé pour réveil stop
|
||||
aucun unbounded channel
|
||||
```
|
||||
|
||||
### 6.6 Timestamps/frontiers
|
||||
|
||||
Décision : aucun frontier/timestamp runtime public dans la fondation. `received_at` reste propriété de l'entrée/provenance source ; run frontier/continuity attendent une source réelle.
|
||||
|
||||
### 6.7 Persistence/conflict
|
||||
|
||||
Décision : Store mode `Normal`, vérité de correction dans Store, aucune cache-based correctness, conflict terminal sans overwrite ni source gagnante.
|
||||
|
||||
### 6.8 Fault
|
||||
|
||||
Décision : erreurs statiques Worker pour settings/runtime/source/store/conflict/drain/counter. Le texte d'erreur distant ou le matériau de transaction n'entre jamais dans snapshot/Debug public.
|
||||
|
||||
## 7. Harness déterministe prévu
|
||||
|
||||
Le harness privé doit pouvoir injecter des matériaux RAW complets et metadata sûre sans réseau et contrôler les ordres de terminaison.
|
||||
|
||||
Preuves minimales :
|
||||
|
||||
```text
|
||||
start/stop normal
|
||||
stop idempotent
|
||||
queue pleine/backpressure
|
||||
concurrency Store bornée
|
||||
new/idempotent/new observation
|
||||
content conflict
|
||||
Store error
|
||||
source failure
|
||||
stop pendant admission/persistence
|
||||
drain timeout
|
||||
no orphan task
|
||||
slow/no snapshot listener
|
||||
latest-value concrete/common
|
||||
redaction
|
||||
```
|
||||
|
||||
Le harness ne devient pas une API publique d'injection.
|
||||
|
||||
## 8. Questions reportées sans blocage
|
||||
|
||||
```text
|
||||
source IDs/capabilities/roles publics
|
||||
required/optional source policy
|
||||
retry/reconnect policy
|
||||
Yellowstone/WS/Helius/HTTP productive adapters
|
||||
run frontier
|
||||
continuity/gap repair
|
||||
hydration live
|
||||
multi-source coalescence optimization
|
||||
hot reconfiguration desired/effective
|
||||
provider smokes
|
||||
```
|
||||
|
||||
Ces sujets appartiennent aux releases `0.3.12+` ou à une tranche ultérieure explicitement ouverte si la base réelle l'impose.
|
||||
|
||||
## 9. Sizing et décision release
|
||||
|
||||
Le forecast initial du prompt est scindé afin de ne pas concentrer crate/settings/runtime/supervision/persistence/snapshots dans les mêmes tranches.
|
||||
|
||||
Prévision retenue :
|
||||
|
||||
```text
|
||||
pre.001 audit/rules/plan
|
||||
pre.002 crate + dependency firewall
|
||||
pre.003 identity/settings
|
||||
pre.004 lifecycle/start/handle/terminal
|
||||
pre.005 supervisor/task ownership + harness
|
||||
pre.006 bounded admission + common RAW
|
||||
pre.007 Store persistence/idempotence/conflict
|
||||
pre.008 snapshots + Worker API projection
|
||||
pre.009 shutdown/backpressure/fault hardening
|
||||
pre.010 public/release/security hardening
|
||||
pre.011 technical final gate
|
||||
pre.012 documentation reconciliation
|
||||
pre.013 publication preparation
|
||||
rel.001
|
||||
```
|
||||
|
||||
Décision `pre.001` : **0.3.11 reste clôturable dans une seule session** si aucune source live, modification Transport/Config, migration Store ou continuity/gap-repair n'entre dans le scope.
|
||||
|
||||
## 10. Gates futurs
|
||||
|
||||
À partir de `pre.002`, chaque tranche Rust rejoue au minimum :
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Les suites et graphes s'ajoutent selon la responsabilité de la tranche. `pre.011` exécute le gate workspace final, y compris :
|
||||
|
||||
```bash
|
||||
cargo test --workspace --all-targets --all-features
|
||||
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
|
||||
```
|
||||
|
||||
## 11. Non-claims `0.3.11`
|
||||
|
||||
Même après fermeture de cette release, ne pas revendiquer :
|
||||
|
||||
```text
|
||||
Yellowstone support
|
||||
WS standard support
|
||||
Helius support
|
||||
HTTP live ingestion
|
||||
lossless provider continuity
|
||||
replay/gap repair
|
||||
multi-provider live convergence
|
||||
hot source reconfiguration
|
||||
Desk ingestion
|
||||
```
|
||||
|
||||
`0.3.11` prouve uniquement que le host runtime Worker est sûr, borné, déterministe et prêt à recevoir ces sources dans les releases suivantes.
|
||||
|
||||
## 12. Gate final `pre.001` dans l’environnement d’assemblage
|
||||
|
||||
Après matérialisation du 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), 775 file(s))
|
||||
|
||||
scan sémantique des règles actives : 0 formulation obsolète ciblée restante
|
||||
comparaison byte-à-byte avec la stable : 3 fichiers ajoutés, 3 modifiés, 0 supprimé
|
||||
```
|
||||
Reference in New Issue
Block a user