diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f89869..44466ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,18 @@ - + # Changelog KSP +## 0.3.16 — fondations multi-variantes RAW, promotion canonique et quarantaine durable — 2026-09-22 + +`0.3.16` stabilise la fondation Store nécessaire à la convergence de plusieurs représentations `RawTransaction` pour une même identité `(network, signature)`. `ksp-store-api` porte désormais le comparateur backend-neutral `Exact / CompatibleLessComplete / CompatibleMoreComplete / Conflict / Incomparable` et les outcomes de variante associés. La dominance reste volontairement fail-closed : seule la troncature `logMessages` explicitement prouvée établit aujourd'hui une relation plus/moins complète ; les autres divergences ne sont jamais fusionnées ou départagées par provider. La migration PostgreSQL V003 est additive et conserve l'historique V000/V001/V002 inchangé ; elle introduit les variantes, le sélecteur canonique, le lien observation-variante et les conflict cases minimaux. + +Le backend PostgreSQL sérialise la décision sous le verrou de l'identité V001. Une représentation `CompatibleMoreComplete` est promue atomiquement tout en conservant l'ancienne variante et en gardant la projection V001 cohérente avec le sélecteur canonique. Une divergence `Conflict` ou `Incomparable` conserve la variante entrante, ouvre ou réouvre un conflict case durable et enregistre l'observation sans muter le canonique. Le Worker ne possède plus d'arbitrage run-local plus fort que le Store : chaque acquisition atteint le Store, `QuarantinedConflict` est un succès non terminal, le Worker reste `Running` avec health `Degraded`, et le Job Backfill projette ce même résultat vers son état `Conflict` tout en conservant l'idempotence de l'observation. + +Le hardening final couvre concurrence, rollback transactionnel, non-régression Store/Backfill/Worker et invariants de sélecteur/projection. La preuve live `postgres_raw_transaction_live` a été exécutée avec succès sur PostgreSQL 17, y compris les scénarios concurrents et récupérables. Les gates opérateur de `pre.008-fix.001` puis de la réconciliation documentaire `pre.009` passent audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings` et les suites ciblées Store API, Store façade, PostgreSQL, Backfill et Worker sans échec. + +La release se ferme volontairement avant la résolution opérateur complète, la rétention/pinning des variantes, le retry Store/backpressure `Blocked`, la reconnexion Transport configurable et l'UI de résolution Store Desk. `prompts/036-V0_3_17_START_PROMPT.md` ouvre `0.3.17` depuis le futur tag stable `v0.3.16` pour ces responsabilités backend/runtime et le cycle de vie complet des conflits/variantes ; `0.3.18` est réservé à l'inspection/résolution dans `ksp-app-store-desk`, puis le Backfill multi-route/multi-stratégie et son adaptation Desk sont repoussés respectivement à `0.3.19` et `0.3.20`. + ## 0.3.15 — Raw Transaction Ingest Desk multi-route et fermeture live Mainnet — 2026-09-19 `0.3.15` livre `ksp-app-raw-transaction-ingest-desk` comme Desk Tauri KSP de composition et supervision des routes live `RawTransaction`. La Desk raisonne en routes complètes plutôt qu’en endpoints : une route n’est composable que lorsque toutes ses capabilities Config/Transport requises existent sur le même réseau, puis le Start reconstruit les ressources backend et lance une instance `ksp-worker-raw-transaction-ingest-lib` indépendante par route sélectionnée. Plusieurs routes peuvent partager le même Store sans partager implicitement lifecycle, gaps, `TargetCoverage` ou réparation. L’application expose inventaire, Start/Stop ciblé, lifecycle, health, activité, backpressure, reconnect/replay, gaps/repair et compteurs sûrs sans déplacer Transport, Store ou logique d’ingestion dans le frontend. diff --git a/Cargo.toml b/Cargo.toml index 9b64982..fe8b228 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 649 +# version: 650 [workspace] resolver = "3" members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-raw-transaction-ingest-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api", "crates/ksp-worker-raw-transaction-ingest-lib"] [workspace.package] -version = "0.3.16-pre.9" +version = "0.3.16-pre.10" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 5a2c4a2..3dd11ce 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -108,9 +108,11 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN - [X] `0.3.13` — Convergence live multi-source du Worker RAW livrée : composition caller-owned `1..32` sources d’un même réseau, cinq familles Yellowstone / Standard Logs / Standard Block / Helius Transaction / HTTP Block Polling, hydration globale des trois voies reference-bearing, RAW-direct Legacy/V0/V1 pour les deux voies blocs, observations multiples, content conflict explicite, coalescence cross-source, fairness/backpressure/health source-neutral et shutdown hardening sans second actor Transport. Gate workspace complet vert (`1 850` PASS / `0` échec / `15` ignored) et smokes keyless HTTP + WebSocket Devnet verts ; les preuves provider/resource-gated non exécutées restent explicitement non revendiquées. - [X] `0.3.14` — Gap repair/hardening multi-source du Worker RAW livré : gaps run-local bornés, distinction reconnect/replay/delivery/coverage, TargetCoverage conservative, coverage redondante prouvée, discovery HTTP bornée, known-reference hydration, réconciliation source-loss, health gap-aware, fairness nominal/repair, snapshots publics source-neutral et shutdown/drain renforcé. Le pipeline Common RAW/Store reste unique, Worker/Backfill restent indépendants, EARLY n’est pas ajouté. Gate workspace complet vert (`1 931` PASS / `0` échec / `15` ignored) et smokes keyless HTTP + WebSocket Devnet verts ; preuves provider/resource-gated non provisionnées explicitement non revendiquées. - [X] `0.3.15` — `ksp-app-raw-transaction-ingest-desk` livrée comme Desk Tauri KSP multi-route : composition capability-driven par réseau, une instance Worker indépendante par route sélectionnée, Store partagé, Start/Stop ciblé et supervision lifecycle/health/backpressure/reconnect/replay/gaps/repair sans réimplémenter Transport ni persistence. Les cinq familles live sont projetées selon les capacités réellement configurées ; Yellowstone Mainnet utilise le trigger gRPC Block + HTTP `getBlock` et applique une backpressure bornée sans overflow local prolongé. Le Stop Yellowstone post-half-close est coopératif, et Store accepte le cas strict `canonique complet + incoming logMessages explicitement tronqué compatible` sans remplacer le canonique ni arrêter le Worker. Gate workspace/Clippy/tests/graphes/bundles Linux vert et live Mainnet Yellowstone + HTTP polling d’environ 19 minutes fermé `Stopped/Healthy`. La généralisation variantes/conflits/promotions/retry/reconnect reste explicitement `0.3.16`. -- [ ] `0.3.16` — **RAW resilience / conflict management** : faire converger Store API/façade/PostgreSQL, Worker live et Store Desk autour de variantes RAW durables, résolution automatique `Exact / CompatibleLessComplete / CompatibleMoreComplete / Conflict`, quarantaine des conflits non résolus sans arrêt du Worker, historique réversible des promotions/résolutions, retry Store sans perte silencieuse et reconnexion Transport configurable/bornée. Une provenance provider n'est jamais une priorité canonique en soi ; la représentation prouvée la plus complète gagne. -- [ ] `0.3.17` — Étendre `ksp-job-backfill-lib` au **backfill multi-route/multi-stratégie** à partir de la matrice d'acquisition auditée en `0.3.9` et de la convergence Store `0.3.16`. Conserver `getSignaturesForAddress + getTransaction` comme première voie valide puis ajouter les stratégies historiques/catch-up réellement pertinentes sans edge Job ↔ Worker. -- [ ] `0.3.18` — Adapter `ksp-app-backfill-desk` au Job multi-route `0.3.17` : inventaire/composition de routes, sélection/supervision et progression sur le modèle structurel de `ksp-app-raw-transaction-ingest-desk`, sans réimplémenter la logique du Job. +- [X] `0.3.16` — **Fondations RAW multi-variantes et conflits durables** livrées : V003 additive avec variantes/sélecteur/mappings/conflict cases, comparateur backend-neutral fail-closed `Exact / CompatibleLessComplete / CompatibleMoreComplete / Conflict / Incomparable`, promotion canonique atomique de la représentation strictement prouvée plus complète, conservation de l'ancien canonique et quarantaine durable des divergences. Le Worker transmet toute acquisition au Store et traite `QuarantinedConflict` comme succès non terminal `Running/Degraded`; le Backfill conserve une projection `Conflict`. Hardening concurrence/rollback vert et preuve PostgreSQL 17 réelle passée. Résolution complète, rétention/pins, retry Store, reconnect configurable et UI sont explicitement reportés. +- [ ] `0.3.17` — **Résilience opérationnelle et cycle de vie des variantes** : contrats Store API backend-neutral d'inspection/résolution et classification `Transient/Terminal`, conflict cases complets avec participants/historique/reopen/races, rétention/pins/purge guards, façade Store d'inspection/actions, retry Store borné avec état `Blocked`, puis reconnexion WebSocket/Yellowstone configurable sans inventer de preuve de coverage. +- [ ] `0.3.18` — **Store Desk conflits/variantes** : exposer via `ksp-store-lib` uniquement les listes, détails, historique et actions opérateur `promote/keep/restore/reopen` avec revision attendue, pagination bornée, stale-action explicite, redaction et preuves Tauri/end-to-end pertinentes. +- [ ] `0.3.19` — Étendre `ksp-job-backfill-lib` au **backfill multi-route/multi-stratégie** à partir de la matrice d'acquisition auditée en `0.3.9` et des contrats Store stabilisés en `0.3.16`–`0.3.18`, sans edge Job ↔ Worker. +- [ ] `0.3.20` — Adapter `ksp-app-backfill-desk` au Job multi-route `0.3.19` : inventaire/composition de routes, sélection/supervision et progression sur le modèle structurel de `ksp-app-raw-transaction-ingest-desk`, sans réimplémenter la logique du Job. ### TODO/IDEAS — applications spécialisées et control plane @@ -120,7 +122,7 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN ### TODO/IDEAS — taxonomie D1, processing et rétention - [ ] **TODO** — maintenir la matrice d’admission HTTP/WS/gRPC/provider lors de toute nouvelle famille D1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte. -- [X] **TODO `0.3.9`** — matrice RAW Transaction unique produite et consolidée dans `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`, avec séparation possibilités/support/preuve, capabilities orthogonales aux producteurs, provenance/déduplication/continuité et handoffs désormais scindés `0.3.11`–`0.3.14` Worker live / `0.3.16` résilience RAW / `0.3.17`–`0.3.18` Backfill multi-route. +- [X] **TODO `0.3.9`** — matrice RAW Transaction unique produite et consolidée dans `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`, avec séparation possibilités/support/preuve, capabilities orthogonales aux producteurs, provenance/déduplication/continuité et handoffs désormais scindés `0.3.11`–`0.3.14` Worker live / `0.3.16` fondations de résilience RAW / `0.3.17` résilience opérationnelle + cycle de vie des variantes / `0.3.18` Store Desk conflits / `0.3.19`–`0.3.20` Backfill multi-route et Desk. - [X] **TODO Helius `0.3.13`** — la voie Worker Helius `transactionSubscribe` réutilise la surface Transport et les profils Config Helius déjà existants avec `KSP_SECRET_HELIUS_API_KEY`; aucun nouveau profil, secret, SDK provider, tier codé ou second client parallèle n’a été nécessaire. Le payload riche reste Transport-owned et la voie Worker hydrate via `getTransaction observed` tant que le RAW complet n’est pas prouvé directement. - [X] **TODO réseau** — identité KSP canonique fixée à `mainnet` dans Config/Store/Transport/tests ; `mainnet-beta` reste uniquement un alias legacy/externe lorsque la frontière provider l'exige. Les données D1 RAW antérieures restent non autoritaires pendant cette phase et aucune compatibilité de base de test n'impose l'ancien libellé. - [X] `RawAccountState` + observation — contrat commun stabilisé en `0.3.1` avec bytes complets + slot, provenance séparée et enrichissements source-specific optionnels ; la persistence PostgreSQL physique est complétée en `0.3.4` avec les quatre capabilities account et la conformance RAW 10/10. diff --git a/deltas/0.3.16/pre.010.md b/deltas/0.3.16/pre.010.md new file mode 100644 index 0000000..a801b3f --- /dev/null +++ b/deltas/0.3.16/pre.010.md @@ -0,0 +1,100 @@ + + + +# Delta `0.3.16-pre.010` + +## Base + +```text +0.3.16-pre.009 +``` + +Le gate opérateur de `pre.009` est entièrement vert : audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features en `-D warnings`, suites Store API, Store façade, PostgreSQL, Job Backfill et Worker jusqu'à `release_completeness`. + +## Objectif + +Dernière prerelease de `0.3.16`, limitée strictement à la préparation de publication conformément à `VER-LIFECYCLE-003` : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompt de démarrage 0.3.17 +delta pre.010 +``` + +Aucun code, test fonctionnel, README/USAGE, plan, validation, architecture, règle, schema, config ou migration n'est modifié. + +## Changements + +### Version workspace + +La version devient : + +```text +0.3.16-pre.10 +``` + +### `CHANGELOG.md` + +Ajout de l'entrée stable `0.3.16`, limitée au périmètre réellement livré : + +- fondations RAW multi-variantes ; +- V003 additive ; +- comparateur fail-closed partagé ; +- sélecteur canonique et promotion atomique strictement prouvée ; +- conflit durable minimal et quarantaine non terminale ; +- continuité Worker `Running/Degraded` ; +- compatibilité Backfill ; +- hardening concurrence/rollback ; +- preuve PostgreSQL 17 réellement exécutée ; +- reports explicites vers `0.3.17`/`0.3.18`. + +### `ROADMAP.md` + +- `0.3.16` passe à `[X]` avec son périmètre réel ; +- `0.3.17` devient la résilience opérationnelle et le cycle de vie complet des variantes ; +- `0.3.18` devient la Store Desk d'inspection/résolution ; +- le Backfill multi-route et sa Desk sont repoussés à `0.3.19` et `0.3.20` ; +- le rappel de trajectoire issu de l'audit `0.3.9` est réaligné sur ce découpage. + +### Prompt `0.3.17` + +Création de : + +```text +prompts/036-V0_3_17_START_PROMPT.md +``` + +Le prompt impose une ouverture depuis le futur tag stable `v0.3.16` et réserve `pre.001` à l'audit/sizing des contrats d'inspection/résolution, du cycle de vie des conflict cases, des revisions/races, de la rétention/pinning, de la classification Store `Transient/Terminal`, du retry Worker et de la reconnexion Transport configurable avant toute implémentation lourde. + +## Fichiers livrés + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompts/036-V0_3_17_START_PROMPT.md +deltas/0.3.16/pre.010.md +``` + +## Validations de génération + +Exécutées sur la livraison assemblée : + +```bash +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 +``` + +Le gate Cargo final reste à exécuter par l'opérateur après application du delta. + +## Décisions de fermeture + +`pre.010` ne rouvre aucun document durable réconcilié en `pre.009` et ne corrige aucun comportement. Toute anomalie fonctionnelle ou documentaire durable découverte après cette tranche doit repasser par un couloir de prerelease approprié avant `rel.001`, conformément à `VER-LIFECYCLE-010/012`. + +Après gate propre de `pre.010`, la livraison suivante attendue est : + +```text +0.3.16-rel.001 +``` diff --git a/prompts/036-V0_3_17_START_PROMPT.md b/prompts/036-V0_3_17_START_PROMPT.md new file mode 100644 index 0000000..db73215 --- /dev/null +++ b/prompts/036-V0_3_17_START_PROMPT.md @@ -0,0 +1,692 @@ + + + +# 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 +```