# 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : 1. vérifier que la base est exactement `v0.3.16` ; 2. lire toutes les sources internes de la section 4 ; 3. réauditer les sources externes pertinentes de la section 5 ; 4. inventorier les contrats publics actuels Store/Worker/Transport/Config ; 5. produire le modèle conceptuel complet conflict case / participants / history / resolution / reopen ; 6. produire la stratégie de revision/CAS et la matrice des races ; 7. produire la politique de rétention/pins/rollback/ForceRehydrate ; 8. produire la classification `Transient / Terminal` et son ownership ; 9. produire la politique Worker de retry/backpressure/Blocked/cancellation ; 10. produire la politique Transport reconnect/config sans confondre coverage ; 11. auditer la compatibilité du Job Backfill existant ; 12. dimensionner les migrations/tests/live proofs ; 13. créer ou réviser le plan `0.3.17` avec prereleases bornées ; 14. publier seulement ensuite `0.3.17-pre.001`. Critères de sortie `pre.001` : ```text 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. ```text 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 : ```text 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 : ```text ksp-general-0.3.17-pre.NNN.zip ksp-general-0.3.17-pre.NNN-fix.NNN.zip ``` Après toute modification Rust : ```bash 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é : ```bash 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 : ```text 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 : ```text 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 ```