v0.3.14-pre.002
This commit is contained in:
257
deltas/0.3.14/pre.002.md
Normal file
257
deltas/0.3.14/pre.002.md
Normal file
@@ -0,0 +1,257 @@
|
||||
<!-- file: deltas/0.3.14/pre.002.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.14-pre.002` — contrats run-local gap / range / coverage
|
||||
|
||||
## Base requise
|
||||
|
||||
```text
|
||||
0.3.14-pre.001
|
||||
workspace.package.version = 0.3.14-pre.1
|
||||
deltas/0.3.14/pre.001.md présent
|
||||
```
|
||||
|
||||
Gate opérateur communiqué sur `0.3.14-pre.1` :
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check : PASS
|
||||
General Rust rule audit : clean
|
||||
Rust export completeness audit : 0 candidate(s)
|
||||
KSP workspace Rust rule audit : clean
|
||||
Markdown table audit : clean (306 tables / 181 files sur le périmètre demandé)
|
||||
cargo check --workspace : PASS
|
||||
```
|
||||
|
||||
## Objectif
|
||||
|
||||
Matérialiser uniquement la tranche `pre.002` du plan `035` :
|
||||
|
||||
```text
|
||||
contrats run-local de gap et plage inclusive
|
||||
TargetCoverage conservative par commitment et scope
|
||||
FullLedgerTransactions / ExactSourceScope / KnownReferences
|
||||
inventaire privé des capabilities de repair déjà composées
|
||||
ledger run-local borné et invariants de coalescence
|
||||
bornes de future discovery / fetch / active repair
|
||||
raccord pur aux RuntimeResources avant spawn des sources
|
||||
```
|
||||
|
||||
Cette tranche ne réalise aucun repair, replay, scan HTTP, hydration de gap ou I/O Store supplémentaire.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
```text
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/src/continuity.rs
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/continuity.rs
|
||||
deltas/0.3.14/pre.002.md
|
||||
```
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/src/runtime_resources.rs
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/tests/hardening.rs
|
||||
crates/ksp-worker-raw-transaction-ingest-lib/tests/release_completeness.rs
|
||||
```
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
```text
|
||||
aucun
|
||||
```
|
||||
|
||||
## Contrats introduits
|
||||
|
||||
Bornes run-local :
|
||||
|
||||
```text
|
||||
MAX_RAW_TRANSACTION_INGEST_OPEN_REPAIR_GAPS = 64
|
||||
MAX_RAW_TRANSACTION_INGEST_REPAIR_RANGE_SLOTS = 4096
|
||||
MAX_RAW_TRANSACTION_INGEST_REPAIR_DISCOVERY_WINDOW_SLOTS = 512
|
||||
MAX_RAW_TRANSACTION_INGEST_REPAIR_BLOCK_FETCH_IN_FLIGHT = 4
|
||||
MAX_RAW_TRANSACTION_INGEST_REPAIR_ACTIVE_GAPS = 1
|
||||
```
|
||||
|
||||
Le scope de coverage distingue explicitement :
|
||||
|
||||
```text
|
||||
FullLedgerTransactions
|
||||
ExactSourceScope(family, semantic_fingerprint)
|
||||
KnownReferences(fingerprint)
|
||||
```
|
||||
|
||||
`KnownReferences` est admis comme notion de capability mais rejeté comme `TargetCoverage` configurée : connaître des signatures à hydrater ne prouve jamais qu'aucune transaction n'a été perdue.
|
||||
|
||||
Les plages de gap sont inclusives, bornées, validées avec arithmétique checked et coalescibles seulement lorsqu'elles se chevauchent ou sont adjacentes sans dépasser la borne maximale.
|
||||
|
||||
Le ledger impose notamment :
|
||||
|
||||
```text
|
||||
réseau unique du run
|
||||
GapId non nul, unique et monotone
|
||||
maximum 64 gaps ouverts
|
||||
maximum 1 gap en Repairing
|
||||
pas de ranges ouverts coalescibles du même source/scope/commitment/reason
|
||||
aucun wrap implicite des compteurs ou bornes
|
||||
```
|
||||
|
||||
## Capabilities source
|
||||
|
||||
L'inventaire est dérivé des `RuntimeResources` déjà validées, sans I/O :
|
||||
|
||||
```text
|
||||
HTTP Block Polling All -> FullLedgerTransactions
|
||||
Standard Block All -> FullLedgerTransactions
|
||||
Standard Block filtered -> ExactSourceScope
|
||||
Standard Logs -> ExactSourceScope
|
||||
Helius transactionSubscribe -> ExactSourceScope
|
||||
Yellowstone -> ExactSourceScope provider-neutral
|
||||
```
|
||||
|
||||
La capability de scan HTTP n'est pas inférée de la simple présence d'un `HttpTransportPool`. Elle est déclarée seulement lorsque le rôle fourni expose réellement, sur le réseau attendu :
|
||||
|
||||
```text
|
||||
getBlock
|
||||
getSlot
|
||||
et au moins getBlocks ou getBlocksWithLimit
|
||||
```
|
||||
|
||||
La disponibilité de `getTransaction` est détectée séparément pour la future hydration de références.
|
||||
|
||||
Pour Yellowstone, le fingerprint de coverage retire du calcul les éléments de transport/continuité qui ne définissent pas le scope métier :
|
||||
|
||||
```text
|
||||
commitment
|
||||
from_slot
|
||||
ping
|
||||
```
|
||||
|
||||
Le scope reste volontairement conservatif : aucune équivalence cross-family ou provider n'est inventée.
|
||||
|
||||
## Intégration runtime
|
||||
|
||||
Avant le spawn des sources live, `RawTransactionIngestRuntimeResources` :
|
||||
|
||||
```text
|
||||
construit exactement un descriptor par source
|
||||
valide réseau / source keys / TargetCoverage / bornes
|
||||
construit un ledger vide run-local
|
||||
conserve ces contrats pendant la durée du supervisor
|
||||
revalide les invariants à la fermeture
|
||||
```
|
||||
|
||||
Aucune nouvelle tâche, socket, retry, requête HTTP/gRPC/WS, lecture Config ou opération Store n'est ajoutée par cette tranche.
|
||||
|
||||
## Tests ajoutés / renforcés
|
||||
|
||||
Les tests couvrent :
|
||||
|
||||
```text
|
||||
valeurs exactes des cinq bornes
|
||||
plages inclusives / reversed / maximum / overflow
|
||||
chevauchement et adjacency
|
||||
merge borné
|
||||
TargetCoverage exact dédupliquée
|
||||
absence de broadening entre commitments
|
||||
subsomption FullLedger seulement au même commitment
|
||||
rejet de KnownReferences comme target
|
||||
limites open/active gaps
|
||||
monotonicité GapId
|
||||
module production continuity privé
|
||||
absence d'I/O et de nouvelles frontières dans continuity.rs
|
||||
inventaire de modules de production mis à jour
|
||||
```
|
||||
|
||||
La surface publique du crate reste inchangée ; les nouveaux contrats sont `pub(crate)` et réexportés uniquement par la façade crate-root pour usage interne conforme aux règles KSP.
|
||||
|
||||
## Dépendances / features
|
||||
|
||||
```text
|
||||
aucune nouvelle dépendance
|
||||
aucune nouvelle feature
|
||||
aucun SDK provider
|
||||
aucun accès Config depuis le Worker
|
||||
aucun accès Job Backfill depuis le Worker
|
||||
aucun backend Store physique depuis le Worker
|
||||
```
|
||||
|
||||
## Version Cargo
|
||||
|
||||
```text
|
||||
header Cargo.toml : 566 -> 567
|
||||
workspace.package.version : 0.3.14-pre.1 -> 0.3.14-pre.2
|
||||
```
|
||||
|
||||
## Validations exécutées
|
||||
|
||||
Dans le sandbox de préparation :
|
||||
|
||||
```text
|
||||
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/0.3.14
|
||||
scan statique frontières / I/O continuity
|
||||
comparaison exacte avec la base pre.001
|
||||
contrôle contenu archive delta
|
||||
unzip -t archive delta
|
||||
```
|
||||
|
||||
Résultats :
|
||||
|
||||
```text
|
||||
General Rust rule audit : clean
|
||||
Rust export completeness audit : 0 candidate(s)
|
||||
KSP workspace Rust rule audit : clean
|
||||
Markdown table audit : clean (306 tables / 182 files)
|
||||
scan continuity I/O / frontières : PASS
|
||||
scan surface publique continuity : PASS
|
||||
comparaison pre.001 -> pre.002 : 3 ajouts / 5 modifications / 0 suppression
|
||||
```
|
||||
|
||||
Le contrôle ZIP est exécuté après construction de l'archive de livraison ; toute archive qui échoue ce contrôle est rejetée et n'est pas livrée.
|
||||
|
||||
## Validations non exécutées
|
||||
|
||||
Le sandbox de préparation ne fournit pas le toolchain Cargo/Rust ; les gates suivants ne peuvent donc pas constituer une preuve locale :
|
||||
|
||||
```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 --all-targets --all-features
|
||||
```
|
||||
|
||||
Ils doivent être exécutés côté opérateur après application du delta.
|
||||
|
||||
## Décisions prises
|
||||
|
||||
```text
|
||||
pre.002 reste sans repair I/O
|
||||
TargetCoverage est conservative et commitment-sensitive
|
||||
FullLedger ne broaden jamais un commitment différent
|
||||
KnownReferences ne prouve jamais la complétude
|
||||
HTTP repair capability est détectée par méthodes réellement routables
|
||||
Yellowstone coverage identity exclut cursor replay et identité provider/endpoint
|
||||
les contrats restent privés au Worker
|
||||
aucune nouvelle dépendance ou frontière architecturale
|
||||
```
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
```text
|
||||
aucune pour pre.002
|
||||
```
|
||||
|
||||
La tranche suivante reste `pre.003` : observabilité latest-value de continuité WebSocket, sans encore déclencher le repair.
|
||||
|
||||
## Gate opérateur après application
|
||||
|
||||
```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/0.3.14
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
cargo test -p ksp-worker-raw-transaction-ingest-lib --all-targets --all-features
|
||||
```
|
||||
Reference in New Issue
Block a user