321 lines
9.9 KiB
Markdown
321 lines
9.9 KiB
Markdown
<!-- file: deltas/0.3.14/pre.005.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.14-pre.005` — preuve conservative de coverage redondante
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
0.3.14-pre.004
|
|
workspace.package.version = 0.3.14-pre.4
|
|
deltas/0.3.14/pre.004.md présent
|
|
```
|
|
|
|
## Gate de la base
|
|
|
|
Le gate opérateur de `0.3.14-pre.004` est validé avant ouverture de cette tranche :
|
|
|
|
```text
|
|
cargo fmt --all : PASS
|
|
cargo fmt --all -- --check : PASS
|
|
audit Rust workspace rules : PASS
|
|
audit Markdown tables : PASS
|
|
cargo check --workspace : PASS
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings : PASS
|
|
cargo test -p ksp-onchain-transport-lib --all-targets --all-features : PASS
|
|
cargo test -p ksp-worker-raw-transaction-ingest-lib --all-targets --all-features : PASS
|
|
```
|
|
|
|
Le gate Transport comprend notamment :
|
|
|
|
```text
|
|
391 unit tests : PASS
|
|
public_api : 53 PASS
|
|
release_completeness : 46 PASS
|
|
smokes live : ignorés par défaut conformément au contrat existant
|
|
```
|
|
|
|
Le gate Worker comprend notamment :
|
|
|
|
```text
|
|
120 unit tests : PASS
|
|
cross_layer_completeness : 8 PASS
|
|
dependency_boundary : 19 PASS
|
|
hardening : 29 PASS
|
|
public_api : 20 PASS
|
|
release_completeness : 6 PASS
|
|
```
|
|
|
|
## Objectif
|
|
|
|
Implémenter strictement la tranche `pre.005` du plan `035` :
|
|
|
|
```text
|
|
matérialiser les relations conservative Exact / Superset
|
|
matérialiser des epochs et ranges de coverage run-local bornés
|
|
n'autoriser une preuve redondante que depuis une source distincte
|
|
exiger un commitment strictement identique
|
|
exiger que l'epoch couvre intégralement la plage du gap
|
|
interdire toute équivalence opportuniste entre familles exactes différentes
|
|
conserver KnownReferences impropre à TargetCoverage
|
|
ne modifier encore aucune décision runtime de supervisor
|
|
ne déclencher aucun repair HTTP et aucun replay supplémentaire
|
|
```
|
|
|
|
## Relations de coverage
|
|
|
|
`RawTransactionIngestCoverageScope` possède maintenant une relation privée et directionnelle :
|
|
|
|
```text
|
|
FullLedgerTransactions -> FullLedgerTransactions : Exact
|
|
FullLedgerTransactions -> ExactSourceScope(...) : Superset
|
|
ExactSourceScope(family, fingerprint)
|
|
-> ExactSourceScope(même family, même fingerprint) : Exact
|
|
autres combinaisons : aucune relation prouvée
|
|
```
|
|
|
|
Cette relation est volontairement conservative.
|
|
|
|
Deux scopes exacts qui partagent le même fingerprint mais pas le même `family_code` ne sont jamais considérés équivalents. Ainsi, par exemple, aucune correspondance `standard_logs <-> helius_transaction` ou `standard_block <-> yellowstone` n'est inventée à partir d'une similarité de sélecteur.
|
|
|
|
La relation est également indépendante de l'identité provider/endpoint : cette indépendance vient uniquement du scope sémantique déjà normalisé, tandis que l'obligation de redondance exige une `source_key` différente.
|
|
|
|
## Commitments
|
|
|
|
La redondance requiert un commitment strictement identique :
|
|
|
|
```text
|
|
Confirmed couvre seulement Confirmed
|
|
Finalized couvre seulement Finalized
|
|
```
|
|
|
|
Aucune hiérarchie `Confirmed <-> Finalized` n'est inférée dans cette tranche.
|
|
|
|
## TargetCoverage
|
|
|
|
La construction de `RawTransactionIngestTargetCoverage` réutilise désormais la relation conservative plutôt qu'une comparaison ad hoc :
|
|
|
|
```text
|
|
un FullLedgerTransactions au même commitment subsume les requirements exacts
|
|
un requirement exact identique est dédupliqué
|
|
un scope exact cross-family reste distinct
|
|
un commitment différent reste distinct
|
|
KnownReferences reste interdit comme target scope
|
|
```
|
|
|
|
Aucune broadening cross-family n'est introduite.
|
|
|
|
## Epochs et ranges de coverage
|
|
|
|
La tranche matérialise des contrats privés :
|
|
|
|
```text
|
|
RawTransactionIngestCoverageRange
|
|
RawTransactionIngestCoverageEpoch
|
|
RawTransactionIngestCoverageEpochLedger
|
|
RawTransactionIngestCoverageRelation
|
|
```
|
|
|
|
Un `CoverageRange` est inclusif et rejette uniquement une plage inversée. Contrairement au `GapRange`, il n'est pas limité artificiellement à `MAX_RAW_TRANSACTION_INGEST_REPAIR_RANGE_SLOTS`, car un epoch de continuité saine peut être plus long qu'une seule obligation de repair.
|
|
|
|
Un epoch conserve :
|
|
|
|
```text
|
|
epoch_id
|
|
source_key
|
|
commitment
|
|
scope
|
|
range inclusif
|
|
```
|
|
|
|
Le ledger est run-local et borné à :
|
|
|
|
```text
|
|
MAX_RAW_TRANSACTION_INGEST_COVERAGE_EPOCHS = 256
|
|
```
|
|
|
|
Il vérifie :
|
|
|
|
```text
|
|
IDs non nuls et uniques
|
|
next_epoch_id strictement monotone
|
|
borne de cardinalité
|
|
range valide
|
|
scope admissible comme configured target scope
|
|
source_key présente dans l'inventaire exact des capabilities
|
|
commitment et scope strictement identiques à la capability de cette source
|
|
```
|
|
|
|
Le ledger est initialisé vide avec les autres continuity contracts. Aucune coverage n'est pré-déclarée à partir de la simple configuration d'une source.
|
|
|
|
## Preuve de redondance
|
|
|
|
Un epoch peut prouver une obligation uniquement si toutes les conditions suivantes sont vraies :
|
|
|
|
```text
|
|
source de preuve != source cible
|
|
commitment de preuve == commitment requis
|
|
range de preuve contient intégralement le GapRange inclusif
|
|
scope de preuve relation Exact ou Superset avec le scope requis
|
|
```
|
|
|
|
Un epoch partiel, une source identique, un commitment différent, un filtre différent ou une famille différente ne ferment donc aucune obligation.
|
|
|
|
`FullLedgerTransactions` peut fournir une preuve `Superset` d'un scope exact au même commitment, parce qu'il représente toutes les transactions de tous les blocs produits. L'inverse est interdit.
|
|
|
|
## Activation runtime
|
|
|
|
Cette tranche ne change pas encore la politique de source-loss/reconciliation :
|
|
|
|
```text
|
|
aucun gap n'est fermé automatiquement
|
|
aucune source n'est maintenue en vie grâce à cette preuve
|
|
aucune terminalité fail-closed de pre.003/pre.004 n'est encore remplacée
|
|
```
|
|
|
|
`pre.008` restera responsable de l'intégration de ces preuves dans le supervisor et le gap ledger. `pre.005` fournit uniquement le modèle conservative nécessaire.
|
|
|
|
## Tests ajoutés
|
|
|
|
Les unit tests Worker couvrent :
|
|
|
|
```text
|
|
Exact pour même famille + même fingerprint
|
|
Superset uniquement FullLedger -> exact
|
|
absence de relation exact -> FullLedger
|
|
absence de relation pour filtre exact différent
|
|
absence de relation cross-family malgré fingerprint identique
|
|
source distincte obligatoire
|
|
commitment strictement identique
|
|
range complet obligatoire
|
|
ledger borné à 256 epochs
|
|
next_epoch_id monotone
|
|
capability source/scope/commitment obligatoire
|
|
```
|
|
|
|
Les canaris `hardening` et `release_completeness` garantissent en plus :
|
|
|
|
```text
|
|
présence des contrats Exact/Superset/epoch
|
|
absence d'équivalence cross-family codée en dur
|
|
absence de hiérarchie opportuniste de commitment
|
|
absence d'exposition publique des nouveaux types de preuve
|
|
```
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
deltas/0.3.14/pre.005.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/continuity.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/hardening.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/release_completeness.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/continuity.rs
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
```text
|
|
aucun
|
|
```
|
|
|
|
## Version Cargo
|
|
|
|
Conformément à `VER-ID-009`, cette nouvelle prerelease synchronise la version workspace :
|
|
|
|
```text
|
|
header Cargo.toml : 571 -> 572
|
|
workspace.package.version : 0.3.14-pre.4 -> 0.3.14-pre.5
|
|
```
|
|
|
|
Versions des fichiers modifiés :
|
|
|
|
```text
|
|
ksp-worker-raw-transaction-ingest-lib/src/continuity.rs : 4 -> 5
|
|
ksp-worker-raw-transaction-ingest-lib/tests/hardening.rs : 28 -> 29
|
|
ksp-worker-raw-transaction-ingest-lib/tests/release_completeness.rs : 23 -> 24
|
|
ksp-worker-raw-transaction-ingest-lib/unit_tests/continuity.rs : 3 -> 4
|
|
```
|
|
|
|
## Frontières préservées
|
|
|
|
```text
|
|
aucun changement Transport
|
|
aucun changement Config
|
|
aucun changement Store
|
|
aucun changement Job Backfill
|
|
aucune nouvelle dépendance
|
|
aucune nouvelle feature
|
|
aucun repair HTTP
|
|
aucun replay Worker
|
|
aucun nouveau socket/actor/retry
|
|
aucun set_from_slot dans Worker
|
|
aucune nouvelle surface publique Worker
|
|
aucune équivalence cross-family opportuniste
|
|
aucune hiérarchie implicite de commitment
|
|
```
|
|
|
|
## 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
|
|
scan des frontières et de la surface crate-root Worker
|
|
comparaison exacte 0.3.14-pre.004 -> 0.3.14-pre.005
|
|
contrôle des versions de fichiers modifiés
|
|
contrôle du contenu de l'archive delta
|
|
unzip -t de l'archive delta
|
|
réapplication de l'archive sur la base puis comparaison byte-exacte
|
|
```
|
|
|
|
## Validations non exécutées dans le sandbox de préparation
|
|
|
|
Le sandbox ne fournit pas le toolchain Cargo/Rust. Les gates suivants restent à exécuter côté opérateur :
|
|
|
|
```text
|
|
cargo fmt --all
|
|
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
|
|
```
|
|
|
|
## Décisions prises
|
|
|
|
```text
|
|
coverage relationnelle directionnelle, jamais symétrisée implicitement
|
|
FullLedger est un superset d'un exact scope au même commitment
|
|
un exact scope n'est équivalent qu'à même family + même fingerprint
|
|
une redondance doit provenir d'une source_key distincte
|
|
un epoch doit contenir toute la plage du gap
|
|
aucune coverage initiale n'est créée depuis la configuration seule
|
|
pre.005 ne modifie pas encore la terminalité runtime
|
|
```
|
|
|
|
## Questions ouvertes
|
|
|
|
```text
|
|
aucune pour pre.005
|
|
```
|
|
|
|
## Tranche suivante
|
|
|
|
`pre.006` reste dédiée au scan HTTP de réparation : détection des capabilities run-wide réellement disponibles, fenêtres bornées, découverte `getBlocks`/`getBlocksWithLimit` conservative et récupération `getBlock observed`, sans broadening de scope.
|
|
|
|
## Gate opérateur après application
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
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 --all-targets --all-features
|
|
```
|