22 KiB
Prompt de démarrage 0.3.17 — résilience opérationnelle et cycle de vie des variantes RAW
1. Identité de la release et base exacte requise
Ouvrir uniquement 0.3.17 depuis la release stable/taggée :
v0.3.16
Ne pas démarrer depuis 0.3.16-pre.*, depuis une archive intermédiaire ou depuis un état de travail non taggé.
La première livraison attendue est :
0.3.17-pre.001
pre.001 est obligatoirement un gate de lecture + audit Store API/Store/PostgreSQL/Worker/Transport/Config + audit du cycle de vie durable des variantes/conflits + audit des erreurs transient/terminal + brainstorming + sizing + planification.
Il est interdit de commencer directement par une UI Store Desk, un moteur de retry générique, une migration opportuniste ou une boucle de reconnexion parallèle avant fermeture de ce gate.
2. Mission et résultat attendu
0.3.16 a livré les fondations multi-variantes : comparaison fail-closed, sélecteur canonique, promotion strictement prouvée, conservation des variantes et quarantaine durable minimale sans arrêt du Worker.
0.3.17 doit transformer cette fondation en mécanisme opérable et résilient côté backend/runtime, sans ouvrir encore l'UI Store Desk.
Le résultat cible est :
plusieurs représentations RAW durables
-> inspection backend-neutral
-> conflict case complet et revisionné
-> participants/historique durable
-> résolution explicite et concurrent-safe
-> restore/reopen possibles selon contrat
-> rétention/pins empêchant la perte d'une variante encore nécessaire
Store temporairement indisponible
-> classification Transient / Terminal
-> retry borné avec backpressure explicite
-> aucun drop silencieux
-> health/activity cohérentes
-> cancellation/drain pendant backoff
Transport live temporairement indisponible
-> mécanisme de reconnexion propriétaire réutilisé
-> configuration bornée
-> aucune confusion entre reconnexion, replay delivery et preuve de coverage
La release doit fournir les contrats nécessaires à 0.3.18, où ksp-app-store-desk exposera ensuite l'inspection et les actions opérateur.
3. Principes directeurs acquis
Les principes suivants sont déjà décidés et ne doivent pas être redébattus sans preuve nouvelle :
une divergence de données != une panne d'acquisition
Store est l'autorité de convergence durable
une provenance/provider n'est jamais une priorité canonique en soi
content_hash seul n'est jamais une preuve d'égalité lorsque les bytes sont disponibles
la dominance reste fail-closed
seule une complétude explicitement prouvée autorise une promotion automatique
un conflit non résolu conserve toutes les variantes nécessaires
reconnexion != coverage
retry != duplication silencieuse
Le Worker ne doit pas réintroduire un arbitre run-local plus fort que le Store.
4. Sources de vérité internes obligatoires — ordre de lecture
4.1 Gouvernance générale
Lire intégralement, dans cet ordre :
RULES.md
ROADMAP.md
CHANGELOG.md
docs/000-README.md
docs/rules/RULES_GENERAL.md
docs/rules/RULES_KSP.md
docs/rules/RULES_RUST.md
docs/rules/RULES_DEPENDENCIES.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/PROMPT_STRUCTURE.md
Le présent prompt complète ces règles ; il ne les remplace pas.
Rappels bloquants :
Rust 2024
unsafe interdit
unwrap / expect / panic interdits selon les règles KSP
retours explicites ; clippy::implicit_return deny
#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]
pas de pub mod
pub/pub(crate) partagés reexportés via crate root
accès partagés via crate::Item, y compris intra-crate
unit tests sous unit_tests/
integration tests sous tests/
4.2 Handoff stable 0.3.16
Lire intégralement :
prompts/035-V0_3_16_START_PROMPT.md
docs/plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md
docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md
docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md
deltas/0.3.16/pre.001.md
...
deltas/0.3.16/pre.010.md
deltas/0.3.16/rel.001.md
Les pre.*-fix.* réellement présents doivent également être lus lorsqu'ils corrigent une tranche citée.
Lorsque rel.001.md n'est pas encore présent dans l'archive fournie à l'ouverture de la session, ne pas l'inventer : vérifier d'abord que la base est bien le tag stable v0.3.16 et utiliser le commit/tag comme autorité.
4.3 Store API et façade
Lire et auditer réellement :
crates/ksp-store-api/README.md
crates/ksp-store-api/USAGE.md
crates/ksp-store-api/src/
crates/ksp-store-api/tests/
crates/ksp-store-lib/README.md
crates/ksp-store-lib/USAGE.md
crates/ksp-store-lib/src/
crates/ksp-store-lib/tests/
Auditer en particulier :
RawTransactionVariant*
RawTransactionVariantComparison
RawTransactionVariantWriteOutcome
RawAcquisitionWriteOutcome
capabilities RawTransaction existantes
surface d'inspection actuelle
codes d'erreur Store et backend-neutralité
object safety et stabilité des traits publics
rétention RawTransaction existante
0.3.17-pre.001 doit décider les DTOs/capabilities backend-neutral nécessaires pour :
lister/inspecter variantes
lister/inspecter conflict cases
lire l'historique de résolution
résoudre/promouvoir/conserver/restaurer/réouvrir avec revision attendue
classifier les erreurs Store Transient / Terminal sans exposer le backend physique
Aucune API publique ne doit exposer tokio-postgres, SQL, row handles ou détails provider.
4.4 Backend PostgreSQL et migration V003
Lire :
crates/ksp-store-postgres-lib/README.md
crates/ksp-store-postgres-lib/USAGE.md
crates/ksp-store-postgres-lib/src/
crates/ksp-store-postgres-lib/tests/
crates/ksp-store-postgres-lib/unit_tests/
crates/ksp-store-postgres-lib/resources/
État acquis à préserver :
V000/V001/V002 figés
V003 additive
ksp_raw_transaction_variants
ksp_raw_transaction_canonical_selectors
ksp_raw_transaction_observation_variants
ksp_raw_transaction_conflicts
Le sélecteur canonique et la projection V001 doivent rester atomiquement cohérents.
Toute extension physique de 0.3.17 doit être additive, migrationnée et justifiée par un contrat métier réel. Ne pas modifier rétroactivement les ressources/checksums stables.
Auditer avant conception :
FOR UPDATE / ordre des locks
revision compare-and-set
participants d'un conflict case
historique append-only
reopen après résolution
races ingestion <-> résolution
races résolution <-> rétention
rollback transactionnel
idempotence des actions opérateur
4.5 Common RAW et règles de comparaison
Lire :
crates/ksp-raw-transaction-lib/README.md
crates/ksp-raw-transaction-lib/USAGE.md
crates/ksp-raw-transaction-lib/src/
crates/ksp-raw-transaction-lib/tests/
Le comparateur 0.3.16 reste l'autorité de classification automatique. Ne pas élargir la dominance pour faciliter l'UI ou réduire artificiellement le nombre de conflits.
État acquis :
Exact
CompatibleLessComplete
CompatibleMoreComplete
Conflict
Incomparable
La seule dominance actuellement prouvée concerne les formes strictes de troncature logMessages documentées. Les autres différences restent fail-closed tant qu'une preuve spécifique n'existe pas.
4.6 Worker live
Lire :
crates/ksp-worker-api/
crates/ksp-worker-raw-transaction-ingest-lib/README.md
crates/ksp-worker-raw-transaction-ingest-lib/USAGE.md
crates/ksp-worker-raw-transaction-ingest-lib/src/
crates/ksp-worker-raw-transaction-ingest-lib/tests/
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/
État acquis :
chaque acquisition atteint le Store
convergence run-local = sérialisation seulement
QuarantinedConflict = succès durable non terminal
Worker reste Running
health devient Degraded
legacy ERROR_CODE_RAW_CONFLICT reste terminal uniquement comme compatibilité backend ancien
0.3.17 doit ajouter le comportement Store transient sans perdre cet invariant.
La politique de retry doit expliciter :
quels codes/classes sont Transient
quels codes/classes sont Terminal
borne de tentatives ou budget temporel
backoff borné
jitter éventuel et ownership
backpressure amont
état Blocked/Degraded/Unhealthy attendu
cancellation pendant sleep/backoff
shutdown/drain avec tentative en vol
absence de double persistence après résultat durable
4.7 Transport et Config
Lire :
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/
crates/ksp-onchain-transport-lib/tests/
crates/ksp-config-lib/README.md
crates/ksp-config-lib/USAGE.md
crates/ksp-config-lib/src/
crates/ksp-config-lib/tests/
Réutiliser les mécanismes propriétaires actuels HTTP/WebSocket/Yellowstone. Ne pas créer une seconde pile réseau dans le Worker.
La reconnexion configurable doit conserver la séparation :
reconnect attempt
session resume / from_slot / ReplayInfo lorsque disponible
replay delivery
coverage proof
Aucun de ces éléments ne vaut automatiquement un autre.
4.8 Job Backfill existant
Lire au minimum :
crates/ksp-job-backfill-lib/README.md
crates/ksp-job-backfill-lib/USAGE.md
crates/ksp-job-backfill-lib/src/persistence.rs
crates/ksp-job-backfill-lib/unit_tests/persistence.rs
Le Job Backfill reste un producteur indépendant et doit continuer de fonctionner avec les évolutions Store. 0.3.17 n'est pas la release du Backfill multi-route/multi-stratégie.
4.9 Architecture et références durables
Lire :
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md
Ces documents décrivent l'état réconcilié à la fermeture de 0.3.16 et doivent servir de baseline, pas les anciens objectifs devenus obsolètes du prompt 035.
5. Sources externes normatives à réauditer en pre.001
Réauditer uniquement les sources officielles ou upstream réellement nécessaires :
PostgreSQL : transactions, row locking, deadlocks, serialization failures et SQLSTATE
Tokio PostgreSQL : erreurs de connexion/IO/DB et possibilités de classification sûres
Solana JSON-RPC/WebSocket : comportement de session/subscription/reconnect applicable
Yellowstone gRPC upstream : lifecycle de stream, fermeture, reprise/from_slot/ReplayInfo applicable
Tokio/Tonic/Tungstenite utilisés par les crates actuelles : cancellation/reconnect lorsque pertinent
La réaudition doit distinguer :
fait documenté upstream
comportement observé par KSP
politique KSP choisie
Ne jamais transformer un message d'erreur provider arbitraire en contrat public KSP.
6. État validé de 0.3.16 à préserver
À l'ouverture de 0.3.17, considérer comme acquis uniquement ce qui est présent dans le tag v0.3.16 et confirmé par ses deltas/validation.
La baseline attendue comprend :
Store API comparator backend-neutral
V003 additive et historique V000/V001/V002 intact
variants durables
canonical selector revisionné
observation -> variant mapping
conflict case minimal durable
promotion CompatibleMoreComplete atomique
ancien canonique conservé comme variante
Conflict/Incomparable quarantinés sans mutation canonique
Worker Running/Degraded après QuarantinedConflict
Backfill projection Conflict compatible
PostgreSQL live proof exécutée sur PostgreSQL 17
Le gate final de 0.3.16 doit être lu dans docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md et dans les deltas de fermeture ; ne pas inventer un résultat non enregistré.
7. Cycle de vie complet des conflict cases
Le modèle minimal 0.3.16 ne suffit pas à une résolution opérateur complète.
pre.001 doit cadrer précisément :
identité stable du conflict case
participants/variantes concernées
status Open / Resolved et éventuels états supplémentaires réellement nécessaires
reason/relation conservées
revision monotone
resolved canonical variant
actor/reason opérateur si un contrat KSP sûr le justifie
journal append-only de transitions
reopen quand une nouvelle divergence survient
idempotence d'une résolution répétée
stale revision explicite
Une résolution ne doit jamais détruire immédiatement la variante perdante si elle reste nécessaire à l'historique, au rollback ou à un conflict case ouvert.
8. Actions et concurrence
Les actions opérateur futures de 0.3.18 doivent être rendues sûres par les contrats backend de 0.3.17.
Auditer et définir au minimum :
promote candidate
keep current canonical
restore previous variant
resolve conflict
reopen conflict
Chaque action mutable doit avoir une sémantique de revision attendue ou équivalent compare-and-set. Une action stale doit échouer explicitement sans écraser une décision concurrente.
Les races à couvrir incluent :
ingestion -> nouvelle variante pendant résolution
promotion automatique -> résolution manuelle concurrente
résolution A -> résolution B concurrente
réouverture -> résolution précédente
rétention/purge -> variante encore référencée
force rehydrate -> identité existante avec bytes exacts/différents
9. Rétention, pins et rollback
La rétention doit être définie avant tout purge de variante.
Principe :
une variante nécessaire à un selector, conflict case ouvert, historique de résolution ou rollback autorisé ne peut pas disparaître silencieusement
pre.001 doit décider :
quels objets pin une variante
quand un pin peut être relâché
archive vs purge
interaction avec RawRetentionState V001
interaction avec ForceRehydrate
restore depuis variante locale conservée
comportement si une ancienne variante est déjà physiquement absente
Le réseau n'est pas un mécanisme normal de rollback d'une variante précédemment connue.
10. Classification Store Transient / Terminal
La classification doit être backend-neutral à la frontière publique tout en restant suffisamment précise pour le runtime.
Ne pas classifier par texte libre d'erreur.
pre.001 doit produire une matrice au moins pour :
connexion indisponible / reset
pool temporairement indisponible
timeout/cancellation locale
deadlock/serialization retryable si applicable
constraint/data-invalid
migration/schema mismatch
network mismatch KSP
stale revision
retention conflict
secret/config invalid
La classe publique doit être stable et sûre ; le backend conserve les détails physiques privés.
11. Retry Store, backpressure et état Blocked
Le retry appartient au Worker/runtime consumer, pas au backend PostgreSQL sous forme de boucle cachée illimitée.
Le Store backend peut classifier et retourner ; le Worker décide une politique bornée selon les contrats KSP.
Le design doit éviter :
queue mémoire non bornée
retry storm
sleep non cancellable
perte silencieuse après exhaustion
health Healthy pendant une impossibilité persistante de commit
double écriture après succès ambigu sans idempotence
La relation avec les limites actuelles in_flight/admission doit être explicitement testée.
12. Reconnexion Transport configurable
0.3.17 étend les mécanismes existants ; il ne crée pas une abstraction universelle inventée au-dessus de toutes les routes.
La configuration doit être bornée et cohérente avec les contrats Config existants :
attempt/backoff limits
connect/session deadlines
stop preemption
source supervision
replay/from_slot lorsque réellement supporté
Une reconnexion réussie ne ferme aucun gap à elle seule. Les contrats 0.3.14 de coverage/gap repair restent autoritaires.
13. Frontières de crates et hors UI
Frontières cibles :
ksp-store-api
DTOs/capabilities backend-neutral
ksp-store-postgres-lib
SQL, locks, transactions, migrations, classification physique
ksp-store-lib
façade et dispatch backend-neutral
ksp-worker-raw-transaction-ingest-lib
politique retry/backpressure/health/cancellation
ksp-onchain-transport-lib
sessions/reconnect/replay transport-owned
ksp-config-lib
configuration bornée des mécanismes existants
ksp-app-store-desk n'est pas à développer dans 0.3.17. Seuls les contrats nécessaires à sa future utilisation doivent être stabilisés.
14. Sécurité et redaction
Ne jamais exposer dans erreurs/logs/snapshots publics :
URI PostgreSQL
password/token/API key
endpoint complet lorsque sa publication n'est pas nécessaire
payload RAW
signature brute si les règles de surface l'interdisent
server error arbitraire
SQL complet
row/backend handle
Les diagnostics de conflits existants restent bornés et structurels.
Toute nouvelle action de résolution doit journaliser seulement les identifiants/codes sûrs nécessaires à l'audit.
15. Première mission pre.001 — audit, brainstorming et sizing
Avant toute implémentation lourde :
- vérifier que la base est exactement
v0.3.16; - lire toutes les sources internes de la section 4 ;
- réauditer les sources externes pertinentes de la section 5 ;
- inventorier les contrats publics actuels Store/Worker/Transport/Config ;
- produire le modèle conceptuel complet conflict case / participants / history / resolution / reopen ;
- produire la stratégie de revision/CAS et la matrice des races ;
- produire la politique de rétention/pins/rollback/ForceRehydrate ;
- produire la classification
Transient / Terminalet son ownership ; - produire la politique Worker de retry/backpressure/Blocked/cancellation ;
- produire la politique Transport reconnect/config sans confondre coverage ;
- auditer la compatibilité du Job Backfill existant ;
- dimensionner les migrations/tests/live proofs ;
- créer ou réviser le plan
0.3.17avec prereleases bornées ; - publier seulement ensuite
0.3.17-pre.001.
Critères de sortie pre.001 :
contrats Store API proposés et bornés
modèle conflict lifecycle validé
revision/race semantics validées
rétention/pins validés
classification Transient/Terminal validée
retry ownership et bornes validés
reconnect ownership et bornes validés
compatibilité Backfill explicitée
migration strategy validée
preuves live nécessaires identifiées
prévision souple des prereleases publiée
hors-périmètre explicite
16. Prévision souple initiale des prereleases
Cette trajectoire provient du plan réconcilié 0.3.16. Elle doit être réauditée en pre.001 et peut être subdivisée si le sizing l'exige.
pre.001 audit + contrats Store API inspection/résolution + classification Transient/Terminal + plan
pre.002 conflict cases complets : participants, résolution, reopen, historique append-only, races
pre.003 rétention des variantes : archive, pins, purge guards, rollback local, ForceRehydrate
pre.004 ksp-store-lib : inspection/historique/actions backend-neutral + compatibilité Backfill
pre.005 Worker : Store retry/backpressure/Blocked, exhaustion, cancellation et drain pendant backoff
pre.006 Transport/Config : reconnect WebSocket/Yellowstone configurable sur mécanismes existants
pre.007 hardening cross-layer + preuves live ciblées Store outage/recovery, retry, reconnect, concurrence
pre.008 réconciliation documentaire finale
pre.009 préparation de publication : CHANGELOG + ROADMAP + prompt 0.3.18
rel.001 publication stable mécanique
Ne jamais fusionner artificiellement les couloirs de fermeture. Les règles VER-LIFECYCLE-* restent autoritaires si le nombre de tranches évolue.
17. Hors périmètre de 0.3.17
Ne pas inclure :
frontend/backend Tauri Store Desk de résolution -> 0.3.18
backfill multi-route/multi-stratégie -> 0.3.19
adaptation Backfill Desk -> 0.3.20
RAW -> STRUCTURAL
persistence STRUCTURAL
DECODED / DOMAIN
majority voting provider
priorité provider
fusion heuristique de JSON arbitraire
retry illimité caché dans le backend Store
nouvelle pile réseau Worker parallèle à Transport
nouvelle dépendance Worker <-> Backfill
18. Versionnement, deltas, validation et instruction d'ouverture
Respecter strictement docs/rules/VERSION_WORKFLOW.md.
Les deltas de 0.3.17 utilisent :
ksp-general-0.3.17-pre.NNN.zip
ksp-general-0.3.17-pre.NNN-fix.NNN.zip
Après toute modification Rust :
cargo fmt --all
cargo fmt --all -- --check
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
Pour tout Markdown touché :
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
Les tests ciblés sont préférés pendant le développement ; les gates complets et live proofs sont réservés aux tranches prévues et ne sont déclarés PASS que lorsqu'ils ont réellement été exécutés.
Les tests PostgreSQL live qui lisent une URI dédiée sur stdin doivent continuer à ne jamais l'échoer ni la conserver dans les logs/deltas.
Pour les applications Desk, ne pas utiliser npm run build comme gate manuel. 0.3.17 ne développe normalement pas la Store Desk ; si un smoke Tauri devenait nécessaire pour une compatibilité mécanique, utiliser le workflow Tauri/Vite KSP prévu par les règles.
Instruction d'ouverture de la prochaine session
Commencer par :
1. vérifier que la base est exactement le tag stable v0.3.16 ;
2. lire toutes les sources internes de la section 4 dans l'ordre ;
3. réauditer les sources externes pertinentes de la section 5 ;
4. exécuter la mission pre.001 de la section 15 ;
5. produire le plan/sizing avant toute migration ou développement lourd.
Ne pas commencer par l'UI Store Desk, par une boucle de retry ou par une migration avant d'avoir fermé le gate pre.001.
La trajectoire suivante est :
0.3.17 résilience opérationnelle + cycle de vie des variantes
0.3.18 Store Desk inspection/résolution des variantes et conflits
0.3.19 Backfill multi-route/multi-stratégie
0.3.20 Backfill Desk correspondant