7.7 KiB
Delta 0.3.17-pre.001 — gate d'audit, architecture et sizing
Base requise
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 :
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
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
Cargo.toml
Fichiers supprimés
aucun
Audit baseline réellement exécuté
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 :
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 :
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 :
keep current canonical
promote variant
restore variant
resolve
reopen
Toute action mutable compare à la fois :
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 :
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 :
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 :
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 :
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 :
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 :
participants
history append-only
projection de résolution
support physique de rétention de variante réellement nécessaire
Découpage recalibré
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
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 :
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
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 :
0.3.17-pre.002