8.6 KiB
Delta 0.3.14-pre.011 — snapshots / observabilité gap et récupération
Base requise
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 :
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 :
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 :
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 :
RawTransactionIngestGapId
RawTransactionIngestGapState
RawTransactionIngestGapReason
RawTransactionIngestRepairMethod
RawTransactionIngestGapSnapshot
RawTransactionIngestGapSnapshot expose uniquement :
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é :
HttpProducedBlockUnavailable
KnownReferenceMissing
SourceFailure
TransportOverflow
WebSocketReconnect
YellowstoneRetention
Les états publics sont :
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 :
Replay
RedundantCoverage
HttpScan
BlockFetch
TransactionHydration
Dans le comportement productif actuellement fermé, la réconciliation par coverage epoch distincte enregistre explicitement :
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 :
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 :
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 :
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 :
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 :
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é
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
deltas/0.3.14/pre.011.md
Fichiers modifiés
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
aucun
Version Cargo
Conformément à VER-ID-009 :
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 :
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
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
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
aucune pour cette tranche
Gate opérateur après application
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