# 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 ```