311 lines
8.6 KiB
Markdown
311 lines
8.6 KiB
Markdown
<!-- file: deltas/0.3.14/pre.011.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.14-pre.011` — snapshots / observabilité gap et récupération
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
0.3.14-pre.010-fix.001
|
|
workspace.package.version = 0.3.14-pre.10.fix.1
|
|
deltas/0.3.14/pre.010-fix.001.md présent
|
|
```
|
|
|
|
## Gate de la base
|
|
|
|
Le gate opérateur de `0.3.14-pre.010-fix.001` 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-worker-raw-transaction-ingest-lib --all-targets --all-features : PASS
|
|
```
|
|
|
|
Le gate Worker comprend notamment :
|
|
|
|
```text
|
|
147 unit tests : PASS
|
|
cross_layer_completeness : 8 PASS
|
|
dependency_boundary : 19 PASS
|
|
hardening : 35 PASS
|
|
public_api : 20 PASS
|
|
release_completeness : 12 PASS
|
|
```
|
|
|
|
## Objectif
|
|
|
|
Implémenter strictement la tranche `pre.011` du plan `035` :
|
|
|
|
```text
|
|
stabiliser une projection publique source-neutral des gaps run-local
|
|
exposer gap_id, plage inclusive, état, raison et dernière méthode éventuelle
|
|
exposer les agrégats open/repairing/repaired/unresolved et méthodes de récupération
|
|
conserver les compteurs checked
|
|
borner la liste détaillée publiée
|
|
ne jamais exposer source key, provider, endpoint, signature, payload ou erreur distante arbitraire
|
|
ne modifier ni ownership Transport ni pipeline Common RAW/Store
|
|
```
|
|
|
|
## Types publics stabilisés
|
|
|
|
La surface `snapshot` ajoute :
|
|
|
|
```text
|
|
RawTransactionIngestGapId
|
|
RawTransactionIngestGapState
|
|
RawTransactionIngestGapReason
|
|
RawTransactionIngestRepairMethod
|
|
RawTransactionIngestGapSnapshot
|
|
```
|
|
|
|
`RawTransactionIngestGapSnapshot` expose uniquement :
|
|
|
|
```text
|
|
gap_id
|
|
start_slot
|
|
end_slot
|
|
state
|
|
reason
|
|
last_method éventuel
|
|
```
|
|
|
|
Aucune identité logique de source et aucune donnée provider n'est transportée.
|
|
|
|
## Raisons et états
|
|
|
|
Les raisons publiques reflètent le catalogue privé déjà validé :
|
|
|
|
```text
|
|
HttpProducedBlockUnavailable
|
|
KnownReferenceMissing
|
|
SourceFailure
|
|
TransportOverflow
|
|
WebSocketReconnect
|
|
YellowstoneRetention
|
|
```
|
|
|
|
Les états publics sont :
|
|
|
|
```text
|
|
Pending
|
|
Repairing
|
|
Repaired
|
|
Unresolved
|
|
```
|
|
|
|
Un gap `Unresolved` reste terminalement visible et n'est plus reclassé `Repaired` par l'arrivée tardive d'un coverage epoch.
|
|
|
|
## Méthodes source-neutral
|
|
|
|
Le catalogue public de méthode est :
|
|
|
|
```text
|
|
Replay
|
|
RedundantCoverage
|
|
HttpScan
|
|
BlockFetch
|
|
TransactionHydration
|
|
```
|
|
|
|
Dans le comportement productif actuellement fermé, la réconciliation par coverage epoch distincte enregistre explicitement :
|
|
|
|
```text
|
|
last_method = RedundantCoverage
|
|
```
|
|
|
|
Les autres méthodes restent à zéro tant qu'aucun mécanisme productif ne fournit une preuve correspondante ; la snapshot ne fabrique jamais une méthode depuis une simple configuration.
|
|
|
|
## Projection détaillée bornée
|
|
|
|
La liste publique `RawTransactionIngestSnapshot::gaps()` reste bornée par :
|
|
|
|
```text
|
|
MAX_RAW_TRANSACTION_INGEST_OPEN_REPAIR_GAPS = 64
|
|
```
|
|
|
|
La projection conserve toujours tous les gaps ouverts, puis utilise uniquement la capacité restante pour les gaps `Repaired` les plus récents. Les entrées sont triées par `gap_id` avant publication.
|
|
|
|
L'historique complet n'est donc jamais dupliqué dans la latest-value snapshot.
|
|
|
|
## Agrégats publics
|
|
|
|
`RawTransactionIngestSnapshot` expose désormais :
|
|
|
|
```text
|
|
open_gap_count
|
|
repairing_gap_count
|
|
repaired_gap_total
|
|
unresolved_gap_total
|
|
replay_repair_total
|
|
redundant_coverage_repair_total
|
|
http_scan_repair_total
|
|
repair_block_fetch_total
|
|
repair_transaction_hydration_total
|
|
oldest_open_gap_start_slot
|
|
```
|
|
|
|
Les comptes sont calculés avec `checked_add`. Un overflow devient une erreur Worker `counter_exhausted` ; aucune saturation silencieuse n'est introduite.
|
|
|
|
## Pont continuity -> snapshot
|
|
|
|
La projection privée `RawTransactionIngestContinuitySnapshotProjection` reste interne à la crate.
|
|
|
|
Le chemin de publication est :
|
|
|
|
```text
|
|
RawTransactionIngestGapLedger
|
|
-> RawTransactionIngestContinuityContracts::observability_projection
|
|
-> source_inventory_health_projection
|
|
-> RawTransactionIngestProcessingFrontierProjection
|
|
-> RawTransactionIngestSnapshotPublisher
|
|
-> RawTransactionIngestSnapshot
|
|
```
|
|
|
|
Le même `watch` latest-value existant est réutilisé. Aucun second canal public ou pipeline de persistence n'est créé.
|
|
|
|
## Non-Copy de la projection interne
|
|
|
|
La projection processing interne transporte maintenant un `Vec` borné de snapshots de gaps ; elle devient donc `Clone` mais n'est plus `Copy`.
|
|
|
|
Les points qui lisaient auparavant une valeur `watch` par déréférencement utilisent désormais `clone()` explicitement. Cela ne change ni les frontières d'ownership ni la sémantique latest-value.
|
|
|
|
## Tests ajoutés ou étendus
|
|
|
|
Les unit tests couvrent :
|
|
|
|
```text
|
|
gap Pending visible avec plage/raison exactes
|
|
gap réconcilié visible comme Repaired avec RedundantCoverage
|
|
gap Unresolved conservé et oldest_open_gap_start_slot exact
|
|
agrégats repaired/unresolved/méthodes exacts
|
|
propagation continuity -> inventory aggregate -> concrete snapshot
|
|
surface publique complète des getters gap/agrégats
|
|
borne détaillée <= 64
|
|
```
|
|
|
|
Les canaris `hardening`, `public_api` et `release_completeness` vérifient en plus :
|
|
|
|
```text
|
|
catalogue public exact attendu
|
|
compteurs checked
|
|
projection détaillée bornée
|
|
absence de source_key/endpoint/signature/payload dans snapshot.rs
|
|
absence de source_key dans la crate root
|
|
aucune croissance du graphe de dépendances ou du pipeline
|
|
```
|
|
|
|
## Hors périmètre inchangé
|
|
|
|
```text
|
|
aucun nouveau mécanisme de replay/reconnect Worker
|
|
aucun nouveau scan HTTP ou retry réseau
|
|
aucun changement de health policy pre.009
|
|
aucun changement de fairness pre.010
|
|
aucun respawn de source
|
|
aucun EARLY/shred
|
|
aucun Job Backfill depuis Worker
|
|
aucun backend Store physique
|
|
aucune nouvelle dépendance
|
|
shutdown/races réservés à pre.012
|
|
```
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
deltas/0.3.14/pre.011.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/continuity.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/runtime.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/runtime_resources.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/snapshot.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/hardening.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/public_api.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/release_completeness.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/continuity.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/runtime_resources.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/snapshot.rs
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
```text
|
|
aucun
|
|
```
|
|
|
|
## Version Cargo
|
|
|
|
Conformément à `VER-ID-009` :
|
|
|
|
```text
|
|
header Cargo.toml : 583 -> 584
|
|
workspace.package.version : 0.3.14-pre.10.fix.1 -> 0.3.14-pre.11
|
|
```
|
|
|
|
Versions des fichiers Rust modifiés :
|
|
|
|
```text
|
|
src/continuity.rs : 10
|
|
src/lib.rs : 33
|
|
src/runtime.rs : 18
|
|
src/runtime_resources.rs : 41
|
|
src/snapshot.rs : 9
|
|
unit_tests/continuity.rs : 8
|
|
unit_tests/runtime_resources.rs : 33
|
|
unit_tests/snapshot.rs : 7
|
|
tests/hardening.rs : 35
|
|
tests/public_api.rs : 23
|
|
tests/release_completeness.rs : 30
|
|
```
|
|
|
|
## Validation exécutée dans l'environnement de préparation
|
|
|
|
```text
|
|
python3 scripts/audit_rust_workspace_rules.py : PASS
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas : PASS
|
|
scan des frontières Worker/Transport/Backfill/Store : PASS
|
|
scan de redaction de la surface snapshot : PASS
|
|
contrôle de l'inventaire public attendu : PASS
|
|
comparaison exacte pre.010-fix.001 -> pre.011 : PASS
|
|
```
|
|
|
|
Les gates Cargo ne sont pas déclarés PASS dans l'environnement de préparation lorsqu'ils ne peuvent pas y être exécutés. Ils restent obligatoires côté opérateur avant `pre.012`.
|
|
|
|
## Décisions prises
|
|
|
|
```text
|
|
surface détaillée bornée à 64 entrées
|
|
priorité de projection à tous les gaps ouverts
|
|
historique réparé représenté par compteurs + capacité détaillée restante
|
|
Unresolved reste visible et non réconciliable tardivement
|
|
aucune identité de source publique
|
|
aucun nouveau canal latest-value
|
|
```
|
|
|
|
## Questions ouvertes
|
|
|
|
```text
|
|
aucune pour cette tranche
|
|
```
|
|
|
|
## 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
|
|
```
|