0.3.17-pre.001
This commit is contained in:
287
deltas/0.3.17/pre.001.md
Normal file
287
deltas/0.3.17/pre.001.md
Normal file
@@ -0,0 +1,287 @@
|
||||
<!-- 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
|
||||
```
|
||||
Reference in New Issue
Block a user