khadhroony-solana-project/deltas/0.3.14/pre.002.md

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