khadhroony-solana-project/deltas/0.3.17/pre.001.md

<!-- file: deltas/0.3.17/pre.001.md -->
<!-- version: 1 -->

# Delta `0.3.17-pre.001` — gate d'audit, architecture et sizing

## Base requise

```text
v0.3.16
workspace.package.version = 0.3.16
```

Ne pas appliquer sur une `0.3.16-pre.*` ou sur un état intermédiaire.

## Objet

Exécuter le gate obligatoire de lecture, audit, brainstorming et sizing défini par `prompts/036-V0_3_17_START_PROMPT.md` avant toute implémentation du cycle de vie complet des conflict cases, du retry Store ou du hardening reconnect.

Cette tranche :

- vérifie l'archive stable reçue et son handoff `0.3.16` ;
- réaudite intégralement les règles KSP demandées ;
- inventorie les contrats Store API/Store/PostgreSQL/Worker/Transport/Config/Backfill ;
- réaudite les sources upstream nécessaires ;
- fixe le modèle conflict case/participants/history/resolution/reopen ;
- fixe la double revision conflict/selector et l'ordre de locks ;
- fixe les semantics de rétention/restore/purge guards ;
- fixe la classification Store `Transient/Terminal` ;
- fixe le retry Worker, la backpressure et `WorkerActivity::Blocked` ;
- confirme que les reconnects existants doivent être durcis et non réimplémentés ;
- recalibre les prereleases `0.3.17` ;
- ne modifie aucun Rust, SQL, migration ou UI.

## Version workspace

`Cargo.toml` :

```text
header version : 651 -> 652
workspace      : 0.3.16 -> 0.3.17-pre.1
```

Aucune autre modification sémantique du `Cargo.toml` racine n'est prévue.

## Fichiers ajoutés

```text
docs/plans/039-V0_3_17_RAW_OPERATIONAL_RESILIENCE_PLAN.md
docs/validation/034-V0_3_17_RAW_OPERATIONAL_RESILIENCE.md
deltas/0.3.17/pre.001.md
```

## Fichiers modifiés

```text
Cargo.toml
```

## Fichiers supprimés

```text
aucun
```

## Audit baseline réellement exécuté

```text
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
Markdown table audit: clean (352 table(s), 962 file(s))
```

Contrôle complémentaire :

```text
workspace version stable       0.3.16
workspace members              22
deltas 0.3.16 présents         21
handoff prompt/plan/validation complet
lockfiles/target/node_modules  absents
manifest inheritance           cohérente
root lint contract             cohérent
```

Le toolchain Cargo n'est pas installé dans l'environnement d'assemblage ; aucun PASS Cargo post-bump n'est inventé.

## Décisions principales

### Conflict case

Identité backend-neutral : `RawTransactionReference` encapsulée par une référence de conflict case.

Etats :

```text
Open
Resolved
```

Aucun état supplémentaire n'est justifié.

Chaque mutation réelle incrémente une revision `u64` monotone ; une réobservation identique est idempotente.

### Participants et historique

V004 doit ajouter un participant ledger monotone et un journal append-only. Le bootstrap depuis V003 ne reconstruit jamais un historique non prouvé.

Le journal n'enregistre que références, enums/codes KSP et timestamps bornés ; aucun payload RAW, texte DB ou acteur libre.

### Actions

Les contrats futurs couvrent :

```text
keep current canonical
promote variant
restore variant
resolve
reopen
```

Toute action mutable compare à la fois :

```text
expected_conflict_revision
expected_canonical_revision
```

Une action déjà exactement appliquée est idempotente `AlreadyAtTarget`; une action concurrente incompatible est `StaleRevision`.

### Rétention

Les rows de variantes référencées restent durables comme identités.

Purge payload interdite pour :

```text
canonical selector courant
participants d'un conflict case Open
mutation en cours
```

L'historique conserve l'identité mais ne pin pas éternellement les bytes. Un restore utilise uniquement des bytes locaux Full/Archived ; après purge explicite, il échoue clairement sans fetch réseau.

### Store error class

Type public backend-neutral retenu :

```text
Transient
Terminal
```

La classification est un contrat Store, pas une liste PostgreSQL codée dans le Worker. Un code inconnu est `Terminal`.

SQLSTATE retryables initiaux :

```text
40001 serialization_failure
40P01 deadlock_detected
57P01 admin_shutdown
57P02 crash_shutdown
57P03 cannot_connect_now
```

Pool timeout/connection loss sont Transient après configuration valide. Config, migration/schema mismatch, wrong network, data invalid, stale revision et retention conflicts sont Terminal.

### Worker retry

Le Worker possède le retry :

```text
default retries       5
maximum retries       20
initial backoff       250 ms
max backoff default   5 s
absolute backoff max  30 s
jitter                 none in first implementation
```

Aucune retry queue : un item conserve son persistence slot jusqu'au résultat/exhaustion. L'admission queue existante fournit la backpressure.

Pendant retry :

```text
state    Running
activity Blocked
health   Degraded
```

Après exhaustion/Terminal : `Faulted/Unhealthy`.

### Transport reconnect

Les acteurs Transport existants restent propriétaires. Le principal gap statique identifié est l'absence de borne maximale KSP explicite sur `WsReconnectSettings::max_retries`, alors que Yellowstone possède `MAX_GRPC_RECONNECT_RETRIES = 100`.

Reconnect, resubscribe/from_slot, replay delivery et coverage restent des concepts distincts.

### Backfill

Aucune dépendance Worker <-> Backfill. Les nouveaux contrats sont ajoutés comme traits séparés afin de ne pas casser `RawTransactionWrite` et les producteurs actuels.

## Migration

Une V004 additive est justifiée après les contrats `pre.002`.

V000/V001/V002/V003 restent byte/checksum-identiques.

V004 doit au minimum matérialiser :

```text
participants
history append-only
projection de résolution
support physique de rétention de variante réellement nécessaire
```

## Découpage recalibré

```text
pre.001  audit + architecture + sizing + plan
pre.002  Store API variants/conflicts/history/actions + StoreErrorClass
pre.003  PostgreSQL V004 additive + bootstrap legacy
pre.004  PostgreSQL lifecycle/actions/CAS/races/history
pre.005  variant retention/archive/purge guards/restore
pre.006  Store facade + physical error classification + Backfill compatibility
pre.007  Worker Store retry/backpressure/Blocked/cancellation
pre.008  Transport/Config reconnect bounds/hardening
pre.009  technical/live final gate
pre.010  documentation reconciliation
pre.011  publication preparation
rel.001  stable mechanical publication
```

## Hors périmètre

```text
Store Desk -> 0.3.18
Backfill multi-route -> 0.3.19
Backfill Desk -> 0.3.20
RAW -> STRUCTURAL
STRUCTURAL persistence
DECODED / DOMAIN
provider majority/priority
heuristic merge
unbounded/hidden Store retry
Worker network stack
Worker <-> Backfill dependency
network rollback
invented operator authentication
```

## Validations exécutées après assemblage

Après création de cette tranche :

```text
General Rust rule audit                 clean
Rust export completeness audit          0 candidate(s)
KSP workspace Rust rule audit           clean
Markdown table audit                    clean (352 table(s), 965 file(s))
workspace.package.version               0.3.17-pre.1
byte-diff contre archive source         PASS
  fichiers ajoutés                      exactement 3
  fichiers modifiés                     exactement Cargo.toml
  fichiers supprimés                    0
Cargo gates                             NOT RUN (toolchain absent)
```

## Gate demandé 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
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
```

Aucun test PostgreSQL live n'est requis pour `pre.001`.

La tranche suivante, seulement après gate propre, est :

```text
0.3.17-pre.002
```