v0.3.15-pre.018
This commit is contained in:
798
prompts/035-V0_3_16_START_PROMPT.md
Normal file
798
prompts/035-V0_3_16_START_PROMPT.md
Normal file
@@ -0,0 +1,798 @@
|
||||
<!-- file: prompts/035-V0_3_16_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Prompt de démarrage `0.3.16` — RAW resilience, variantes, conflits et récupération
|
||||
|
||||
## 1. Identité de la release et base exacte requise
|
||||
|
||||
Ouvrir **uniquement** `0.3.16` depuis la release stable/taggée :
|
||||
|
||||
```text
|
||||
v0.3.15
|
||||
```
|
||||
|
||||
Ne pas démarrer depuis une prerelease intermédiaire `0.3.15-pre.*` ou depuis une archive de travail non taggée.
|
||||
|
||||
La première livraison attendue est :
|
||||
|
||||
```text
|
||||
0.3.16-pre.001
|
||||
```
|
||||
|
||||
`pre.001` est obligatoirement un gate de **lecture + audit Store/Worker/Transport/Config/Store Desk + audit des sémantiques RPC de complétude + brainstorming + sizing + planification**. Il est interdit de commencer directement par une migration PostgreSQL, par de nouvelles tables de conflit ou par l'UI Store Desk avant fermeture de ce gate.
|
||||
|
||||
## 2. Mission et résultat attendu
|
||||
|
||||
Faire évoluer KSP afin qu'une divergence RAW ou une indisponibilité locale récupérable ne soit plus confondue avec une panne irréversible d'acquisition.
|
||||
|
||||
Le résultat cible doit permettre :
|
||||
|
||||
```text
|
||||
plusieurs producteurs/routes observent la même identité RAW
|
||||
-> Store compare les représentations
|
||||
-> Exact
|
||||
ou CompatibleLessComplete
|
||||
ou CompatibleMoreComplete
|
||||
ou Conflict
|
||||
|
||||
Exact
|
||||
-> idempotence / observation supplémentaire
|
||||
|
||||
CompatibleLessComplete
|
||||
-> canonique plus complet conservé
|
||||
-> observation conservée
|
||||
-> acquisition continue
|
||||
|
||||
CompatibleMoreComplete
|
||||
-> promotion atomique vers la variante plus complète
|
||||
-> ancienne variante conservée
|
||||
-> historique réversible
|
||||
-> acquisition continue
|
||||
|
||||
Conflict
|
||||
-> canonique courant conservé
|
||||
-> variante entrante conservée intégralement
|
||||
-> dossier de conflit durable ouvert/complété
|
||||
-> Worker continue en état dégradé plutôt que Faulted
|
||||
```
|
||||
|
||||
La release doit également introduire une politique explicite et bornée pour :
|
||||
|
||||
```text
|
||||
Store temporairement indisponible
|
||||
Transport temporairement indisponible / reconnexion
|
||||
```
|
||||
|
||||
et étendre `ksp-app-store-desk` avec les vues et actions nécessaires à l'inspection/résolution/restauration des conflits RAW.
|
||||
|
||||
## 3. Principe directeur acquis
|
||||
|
||||
La règle centrale est :
|
||||
|
||||
```text
|
||||
une divergence de données != une panne d'acquisition
|
||||
```
|
||||
|
||||
Une provenance provider n'est jamais une autorité canonique en soi.
|
||||
|
||||
La décision canonique porte sur une **qualité de représentation prouvée**, indépendamment :
|
||||
|
||||
```text
|
||||
de l'ordre d'arrivée
|
||||
du provider
|
||||
de la route productrice
|
||||
du fait qu'une représentation est arrivée en premier
|
||||
```
|
||||
|
||||
Aucune règle `first-provider-wins`, majorité provider, liste de providers prioritaires ou « Solana public a toujours raison » n'est admise.
|
||||
|
||||
## 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.15`
|
||||
|
||||
Lire intégralement :
|
||||
|
||||
```text
|
||||
prompts/034-V0_3_15_START_PROMPT.md
|
||||
docs/plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md
|
||||
docs/validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md
|
||||
docs/plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md
|
||||
|
||||
deltas/0.3.15/pre.014.md
|
||||
deltas/0.3.15/pre.014-fix.001.md
|
||||
deltas/0.3.15/pre.015.md
|
||||
deltas/0.3.15/pre.015-fix.001.md
|
||||
deltas/0.3.15/pre.016.md
|
||||
deltas/0.3.15/pre.017.md
|
||||
deltas/0.3.15/pre.018.md
|
||||
deltas/0.3.15/rel.001.md
|
||||
```
|
||||
|
||||
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.15` et utiliser le commit/tag comme autorité.
|
||||
|
||||
### 4.3 Store RAW
|
||||
|
||||
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/
|
||||
|
||||
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/
|
||||
```
|
||||
|
||||
Auditer en particulier :
|
||||
|
||||
```text
|
||||
RawTransaction / RawTransactionObservation
|
||||
identité (network, signature)
|
||||
content_hash et payload canonique
|
||||
atomic insert canonical + observation
|
||||
additional observation
|
||||
content_conflict actuel
|
||||
rétention Full / Archived / Purged / ForceRehydrate
|
||||
inspection random-access Store Desk
|
||||
migration registry V000/V001/V002 et règles de checksum
|
||||
verrous / transactions / concurrence / cancellation
|
||||
projection des erreurs backend vers store-lib/store-api
|
||||
```
|
||||
|
||||
Ne pas casser les checksums des migrations stables existantes. Toute évolution physique est additive via une nouvelle migration/resource versionnée.
|
||||
|
||||
### 4.4 Common RAW et sémantique 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 RAW v1 canonique et ses golden bytes/hash restent des contrats acquis. `0.3.16` ne doit pas redéfinir arbitrairement la canonicalisation pour faire disparaître les conflits.
|
||||
|
||||
Le moteur de qualité doit comparer des représentations réelles et conserver leurs variantes. Il ne doit pas masquer une contradiction en normalisant deux payloads réellement distincts vers une valeur artificielle.
|
||||
|
||||
### 4.5 Worker live et acquisition
|
||||
|
||||
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/
|
||||
|
||||
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
|
||||
```
|
||||
|
||||
Préserver les cinq familles live et le pipeline unique :
|
||||
|
||||
```text
|
||||
Yellowstone hydrated
|
||||
Standard Logs hydrated
|
||||
Standard Block direct
|
||||
Helius Transaction hydrated
|
||||
HTTP Block Polling direct
|
||||
|
||||
Transport
|
||||
-> Worker
|
||||
-> ksp-raw-transaction-lib
|
||||
-> ksp-store-lib
|
||||
```
|
||||
|
||||
Le Worker et le Job Backfill restent des producteurs indépendants. `0.3.16` ne crée aucun edge `Worker -> Job` ni `Job -> Worker`.
|
||||
|
||||
### 4.6 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/
|
||||
config/std.transport.json
|
||||
config/examples/std.transport.example.json
|
||||
config/schemas/std.transport.schema.json
|
||||
```
|
||||
|
||||
Auditer les politiques de retry/reconnect déjà existantes avant d'ajouter de nouveaux réglages. Ne pas introduire une seconde politique concurrente si un contrat Transport peut être étendu proprement.
|
||||
|
||||
### 4.7 Store Desk
|
||||
|
||||
Lire :
|
||||
|
||||
```text
|
||||
crates/ksp-app-store-desk/README.md
|
||||
crates/ksp-app-store-desk/USAGE.md
|
||||
crates/ksp-app-store-desk/src/
|
||||
crates/ksp-app-store-desk/src/frontend/
|
||||
crates/ksp-app-store-desk/tests/
|
||||
crates/ksp-app-store-desk/package.json
|
||||
```
|
||||
|
||||
Préserver les règles du gabarit Desk KSP :
|
||||
|
||||
```text
|
||||
même architecture lib.rs exports-only / tauri.rs bridge / modules spécialisés
|
||||
frontend Vite + TypeScript
|
||||
tracing frontend des actions sans valeurs sensibles
|
||||
DataTables serverSide lorsque pertinent
|
||||
aucun SQL / backend PostgreSQL / endpoint / secret dans l'application
|
||||
ksp-store-lib = seule façade Store consommée par la Desk
|
||||
pas de npm run build comme gate manuel ; utiliser le workflow Tauri/Vite du projet
|
||||
```
|
||||
|
||||
## 5. Sources externes normatives à réauditer en `pre.001`
|
||||
|
||||
La fraîcheur et la sémantique exacte importent. Réauditer les sources officielles actuelles avant de généraliser les règles de complétude :
|
||||
|
||||
```text
|
||||
Solana / Agave RPC getTransaction et getBlock
|
||||
TransactionStatusMeta / UiTransactionStatusMeta
|
||||
sémantique de logMessages et du marqueur Log truncated
|
||||
innerInstructions
|
||||
loadedAddresses
|
||||
returnData
|
||||
computeUnitsConsumed
|
||||
costUnits
|
||||
preTokenBalances / postTokenBalances
|
||||
rewards
|
||||
champ absent vs null vs liste vide vs valeur présente
|
||||
maxSupportedTransactionVersion
|
||||
```
|
||||
|
||||
Lorsque nécessaire, vérifier aussi la source Agave/runtime responsable de la troncature des logs afin de prouver la relation exacte au lieu de déduire une règle à partir d'un seul provider.
|
||||
|
||||
Pour PostgreSQL, réauditer la documentation officielle des mécanismes réellement retenus pour :
|
||||
|
||||
```text
|
||||
transactions
|
||||
SELECT ... FOR UPDATE
|
||||
UPSERT / ON CONFLICT
|
||||
contraintes d'unicité
|
||||
indexation
|
||||
isolation / concurrence
|
||||
DDL/migrations additives
|
||||
```
|
||||
|
||||
Toute conclusion externe doit être traduite en canari KSP et documentée. Une hypothèse non prouvée reste fail-closed.
|
||||
|
||||
## 6. État validé de `0.3.15` à préserver
|
||||
|
||||
`0.3.15` fournit déjà :
|
||||
|
||||
```text
|
||||
Raw Transaction Ingest Desk multi-route
|
||||
1 Worker indépendant par route sélectionnée
|
||||
Store partagé par plusieurs routes du même réseau
|
||||
inventaire capability-driven
|
||||
Start/Stop ciblé
|
||||
monitoring lifecycle/health/activity/backpressure/reconnect/replay/gaps/repair
|
||||
cinq familles live
|
||||
```
|
||||
|
||||
Le live Mainnet de référence a validé Yellowstone + HTTP Block Polling environ dix-neuf minutes en parallèle, sans `grpc_backpressure_overflow`, sans route `Faulted`, puis avec Stop propre `Stopped/Healthy` pour les deux routes.
|
||||
|
||||
Yellowstone Block final :
|
||||
|
||||
```text
|
||||
gRPC Block = trigger
|
||||
include_transactions = false
|
||||
HTTP getBlock = Full/Base64
|
||||
maxSupportedTransactionVersion = 1
|
||||
rewards = false
|
||||
```
|
||||
|
||||
La saturation de la queue d'updates Yellowstone applique une backpressure bornée/asynchrone vers le stream au lieu d'un overflow local terminal. Un `Status` reçu après half-close local pendant un Stop explicite est traité comme fermeture coopérative ; le même `grpc_status` observé pendant une session active reste une vraie faute/reconnexion.
|
||||
|
||||
Store sait déjà accepter le cas étroit :
|
||||
|
||||
```text
|
||||
canonique complet déjà stocké
|
||||
+
|
||||
incoming dont seule la liste logMessages est explicitement tronquée
|
||||
+
|
||||
relation de troncature strictement prouvée
|
||||
=> observation acceptée
|
||||
=> canonique inchangé
|
||||
=> pas de content_conflict terminal
|
||||
```
|
||||
|
||||
Le sens inverse n'est pas encore implémenté.
|
||||
|
||||
## 7. Décisions acquises pour les variantes RAW
|
||||
|
||||
Le modèle conceptuel cible est :
|
||||
|
||||
```text
|
||||
RawTransaction identity (network, signature)
|
||||
|
|
||||
+-- Variant A <- canonical current
|
||||
| +-- observations/provenances
|
||||
|
|
||||
+-- Variant B
|
||||
| +-- observations/provenances
|
||||
|
|
||||
+-- Variant C
|
||||
+-- observations/provenances
|
||||
|
||||
Conflict case
|
||||
+-- status
|
||||
+-- canonical variant
|
||||
+-- classification
|
||||
+-- resolution history
|
||||
```
|
||||
|
||||
Les noms physiques exacts sont à décider après audit `pre.001`, pas avant.
|
||||
|
||||
Une variante doit représenter une représentation effectivement reçue ou une variante synthétique explicitement marquée comme telle. Une promotion ne détruit jamais la variante précédemment canonique.
|
||||
|
||||
Exemple :
|
||||
|
||||
```text
|
||||
A canonical
|
||||
B alternate
|
||||
|
||||
promote B
|
||||
=> A conservé
|
||||
=> B devient canonical
|
||||
=> historique A -> B
|
||||
|
||||
restore A plus tard
|
||||
=> historique B -> A
|
||||
=> aucune reconstruction externe nécessaire
|
||||
```
|
||||
|
||||
## 8. Classification de convergence cible
|
||||
|
||||
Le comparateur partagé vise au minimum :
|
||||
|
||||
```text
|
||||
Exact
|
||||
CompatibleLessComplete
|
||||
CompatibleMoreComplete
|
||||
Conflict
|
||||
```
|
||||
|
||||
Règles :
|
||||
|
||||
```text
|
||||
Exact
|
||||
-> contenu équivalent
|
||||
-> observation idempotente ou supplémentaire
|
||||
|
||||
CompatibleLessComplete
|
||||
-> incoming prouvé moins complet
|
||||
-> canonique conservé
|
||||
-> incoming/observation conservés selon le modèle retenu
|
||||
|
||||
CompatibleMoreComplete
|
||||
-> incoming domine le canonique sans contradiction
|
||||
-> promotion atomique
|
||||
-> ancien canonique conservé comme variante
|
||||
|
||||
Conflict
|
||||
-> aucun ordre de qualité sûr
|
||||
-> canonique courant conservé
|
||||
-> incoming conservé comme variante
|
||||
-> dossier conflict durable
|
||||
```
|
||||
|
||||
La qualité est une **relation partielle**, pas nécessairement un ordre total.
|
||||
|
||||
Si une représentation est plus complète sur un champ mais moins complète sur un autre, elle peut être `Incomparable` conceptuellement et doit rester fail-closed tant qu'aucune règle de fusion sûre n'existe.
|
||||
|
||||
Il est interdit de fabriquer automatiquement une représentation « best-of-fields » qui n'a été retournée par aucune source, sauf mécanisme de fusion explicitement défini, audité et marqué comme synthétique.
|
||||
|
||||
## 9. Politique champ par champ — prudence obligatoire
|
||||
|
||||
`logMessages` est le seul premier cas déjà démontré en live.
|
||||
|
||||
Pour tout autre champ, `pre.001` doit distinguer :
|
||||
|
||||
```text
|
||||
absence informationnelle
|
||||
absence structurelle / mode de sérialisation
|
||||
null métier
|
||||
liste vide métier
|
||||
champ non disponible historiquement
|
||||
champ dépendant de la version transaction/node
|
||||
contradiction réelle
|
||||
```
|
||||
|
||||
Ne jamais considérer automatiquement :
|
||||
|
||||
```text
|
||||
absent == null
|
||||
null == []
|
||||
[] == valeur tronquée
|
||||
valeur la plus longue == meilleure
|
||||
provider X == vérité
|
||||
```
|
||||
|
||||
Les scalaires présents avec deux valeurs différentes restent `Conflict` sauf contrat normatif contraire explicitement prouvé.
|
||||
|
||||
Les listes différentes restent `Conflict` sans relation formelle de préfixe/troncature/complétude propre à ce champ.
|
||||
|
||||
## 10. Conflits durables et santé Worker
|
||||
|
||||
Un conflit durablement stocké ne doit plus arrêter le Worker :
|
||||
|
||||
```text
|
||||
content conflict
|
||||
-> variant persisted
|
||||
-> conflict case unresolved
|
||||
-> acquisition continue
|
||||
-> Worker Running
|
||||
-> health Degraded
|
||||
```
|
||||
|
||||
Le health model et les snapshots doivent rester source-neutral et redacted. Évaluer au minimum les compteurs conceptuels :
|
||||
|
||||
```text
|
||||
unresolved_content_conflict_count
|
||||
auto_resolved_conflict_count
|
||||
canonical_promotion_count
|
||||
```
|
||||
|
||||
Le nom final de chaque compteur appartient à l'audit/API design `pre.001`.
|
||||
|
||||
La complétude doit pouvoir distinguer :
|
||||
|
||||
```text
|
||||
acquisition_complete
|
||||
= les données attendues ont été durablement capturées, variantes comprises
|
||||
|
||||
canonical_complete
|
||||
= aucune obligation de réconciliation canonique n'est ouverte
|
||||
```
|
||||
|
||||
Un conflit sur une identité ne doit pas bloquer l'acquisition des autres identités.
|
||||
|
||||
Le futur RAW -> STRUCTURAL décidera séparément si une identité `canonical_complete=false` peut être matérialisée ; ne pas implémenter STRUCTURAL dans `0.3.16`.
|
||||
|
||||
## 11. Store retry et backpressure
|
||||
|
||||
Un Store indisponible n'est pas équivalent à un content conflict.
|
||||
|
||||
Le Worker ne doit jamais :
|
||||
|
||||
```text
|
||||
continuer à consommer indéfiniment sans durabilité
|
||||
jeter silencieusement les RAW
|
||||
présenter une persistence échouée comme acquisition réussie
|
||||
```
|
||||
|
||||
Auditer puis définir une politique Store bornée :
|
||||
|
||||
```text
|
||||
classification transient / terminale
|
||||
pause ou backpressure admission
|
||||
retry borné ou illimité seulement si explicitement configuré
|
||||
délai initial
|
||||
backoff
|
||||
max delay
|
||||
budget/tentatives
|
||||
reset après stabilité si pertinent
|
||||
observabilité Degraded / Blocked
|
||||
terminal uniquement sur politique épuisée ou erreur structurelle
|
||||
```
|
||||
|
||||
La propriété essentielle est :
|
||||
|
||||
```text
|
||||
pas de perte silencieuse
|
||||
```
|
||||
|
||||
Si le Store bloque suffisamment longtemps pour saturer l'acquisition, la pression doit remonter de manière bornée/cohérente au lieu de créer une queue non bornée.
|
||||
|
||||
## 12. Reconnexion Transport configurable
|
||||
|
||||
La politique Transport est distincte de la politique Store.
|
||||
|
||||
Auditer les réglages existants pour HTTP, WebSocket et Yellowstone avant d'ajouter une surface commune ou spécialisée.
|
||||
|
||||
Paramètres conceptuels à étudier :
|
||||
|
||||
```text
|
||||
initial_delay
|
||||
max_delay
|
||||
backoff_multiplier
|
||||
max_attempts
|
||||
reset_after_stable_duration
|
||||
jitter borné
|
||||
```
|
||||
|
||||
Une perte de connexion ne doit pas rendre le Worker terminal immédiatement tant que la politique de reconnexion autorise une reprise.
|
||||
|
||||
Inversement, une reconnexion n'est jamais une preuve de coverage : les gaps/replay/repair `0.3.14` restent responsables de la continuité.
|
||||
|
||||
## 13. `ksp-app-store-desk` — conflits et historique
|
||||
|
||||
Étendre Store Desk via `ksp-store-lib` uniquement.
|
||||
|
||||
Prévoir au minimum des surfaces autour de :
|
||||
|
||||
```text
|
||||
RAW Conflicts
|
||||
RAW Conflict History / Resolution History
|
||||
```
|
||||
|
||||
Pour une identité conflictuelle, l'UI doit pouvoir présenter de manière bornée :
|
||||
|
||||
```text
|
||||
variante canonique actuelle
|
||||
variantes alternatives
|
||||
différences structurées
|
||||
provenances/observations
|
||||
statut du conflit
|
||||
historique des promotions/résolutions
|
||||
origine native ou synthétique d'une variante
|
||||
```
|
||||
|
||||
Actions visées, après audit des contrats :
|
||||
|
||||
```text
|
||||
Promote variant
|
||||
Keep current canonical + Resolve
|
||||
Restore previous canonical
|
||||
Reopen conflict
|
||||
Assisted merge pour champs explicitement compatibles
|
||||
```
|
||||
|
||||
Une fusion manuelle doit créer une nouvelle variante explicitement `manual/synthetic` avec ses parents. Elle ne modifie pas silencieusement une variante provider existante et ne prétend pas être une observation provider native.
|
||||
|
||||
Éviter un éditeur JSON libre comme mécanisme principal de résolution. Les actions doivent être structurées et typées autant que possible.
|
||||
|
||||
## 14. Frontières de crates et sécurité
|
||||
|
||||
Responsabilités cibles :
|
||||
|
||||
```text
|
||||
ksp-store-api
|
||||
DTO/contrats backend-neutral variantes, conflits, résolution, inspection
|
||||
|
||||
ksp-store-lib
|
||||
façade unique consommée par Worker/Job/Desk
|
||||
moteur de convergence backend-neutral seulement si cela respecte l'ownership audité
|
||||
|
||||
ksp-store-postgres-lib
|
||||
schema/migrations/SQL/transactions/verrous/indexes
|
||||
atomicité physique variantes/promotions/résolutions
|
||||
|
||||
ksp-worker-raw-transaction-ingest-lib
|
||||
pipeline live
|
||||
ne fault plus sur conflit durable correctement persisté
|
||||
health/compteurs/retry orchestration selon ownership réel
|
||||
|
||||
ksp-onchain-transport-lib
|
||||
reconnexion réseau et backpressure Transport
|
||||
|
||||
ksp-config-lib
|
||||
configuration typée des politiques retenues
|
||||
|
||||
ksp-app-store-desk
|
||||
inspection/résolution via ksp-store-lib uniquement
|
||||
```
|
||||
|
||||
Interdictions :
|
||||
|
||||
```text
|
||||
aucun SQL dans Worker/Desk
|
||||
aucun backend PostgreSQL direct dans Worker/Job/Desk
|
||||
aucune dépendance Job <-> Worker
|
||||
aucun endpoint/token/signature/payload dans logs sûrs
|
||||
aucune queue non bornée
|
||||
aucun overwrite destructif d'une ancienne variante
|
||||
aucune décision canonique par nom de provider
|
||||
aucune baisse de qualité canonique automatique
|
||||
```
|
||||
|
||||
Les opérations manuelles doivent être auditables. Une résolution doit conserver l'identité de l'action et son résultat sans exiger d'exposer de secret ou de payload arbitraire dans les logs.
|
||||
|
||||
## 15. Première mission `pre.001` — audit, brainstorming et sizing
|
||||
|
||||
Avant toute implémentation :
|
||||
|
||||
1. reconstruire/auditer la base stable `v0.3.15` et confirmer les gates de fermeture ;
|
||||
2. inventorier exactement les APIs Store RawTransaction actuelles et les outcomes d'écriture ;
|
||||
3. inventorier les tables/migrations PostgreSQL actuelles, clés, FK, index, contraintes, rétention et transactions ;
|
||||
4. tracer le chemin actuel `Worker -> Store` lorsqu'un `content_conflict` survient ;
|
||||
5. tracer les chemins d'erreur Store temporaire/terminal et la façon dont ils affectent admission/drain/health ;
|
||||
6. inventorier toutes les politiques retry/reconnect Transport existantes et leurs propriétaires ;
|
||||
7. inventorier les DTOs/queries Store Desk disponibles pour ajouter conflits/variantes sans bypass ;
|
||||
8. réauditer les sémantiques officielles des champs `TransactionStatusMeta` avant toute règle de complétude hors `logMessages` ;
|
||||
9. proposer au moins deux modèles physiques raisonnables pour variantes/conflits/résolutions, avec analyse atomicité/rétention/concurrence ;
|
||||
10. décider si l'identité physique d'une variante repose sur `content_hash`, un id surrogate, ou une combinaison, sans confondre hash et preuve d'égalité ;
|
||||
11. décider comment les observations se rattachent à la variante réellement reçue ;
|
||||
12. décider comment `Full/Archived/Purged/ForceRehydrate` interagit avec les variantes et conflits ;
|
||||
13. définir la machine d'état d'un conflict case et l'historique de résolution ;
|
||||
14. définir le modèle de dominance/qualité et les cas `Exact/Less/More/Conflict/Incomparable` internes nécessaires ;
|
||||
15. définir les métriques/health source-neutral ;
|
||||
16. définir la politique Store retry et la politique Transport reconnect sans les mélanger ;
|
||||
17. découper la release en prereleases réellement tenables dans le budget KSP ;
|
||||
18. créer/réviser un plan dédié `0.3.16` et un document de validation avant l'implémentation lourde.
|
||||
|
||||
Le gate `pre.001` ne doit pas créer une migration finale « pour avancer ». Il peut créer des documents, tests de caractérisation et POC strictement nécessaires au choix architectural, conformément aux règles de la base.
|
||||
|
||||
Critères de sortie `pre.001` :
|
||||
|
||||
```text
|
||||
modèle conceptuel validé
|
||||
frontières de crates validées
|
||||
migration strategy validée sans casser V000/V001/V002
|
||||
sémantique de qualité logMessages prouvée
|
||||
politique pour les autres champs explicitement conservative
|
||||
Store retry ownership décidé
|
||||
Transport reconnect ownership décidé
|
||||
Store Desk scope décidé
|
||||
risques/races/rétention identifiés
|
||||
prévision souple des prereleases publiée
|
||||
hors-périmètre explicite
|
||||
```
|
||||
|
||||
## 16. Prévision souple initiale des prereleases
|
||||
|
||||
Cette prévision est un point de départ, à recalibrer en `pre.001`. Ne jamais fusionner artificiellement des tranches pour respecter ces numéros.
|
||||
|
||||
```text
|
||||
pre.001 audit complet, sémantiques externes, modèles physiques, sizing et plan
|
||||
pre.002 contrats Store API backend-neutral pour variantes/conflits/résolutions
|
||||
pre.003 migration PostgreSQL additive + mapping backend des variantes/conflits
|
||||
pre.004 moteur de comparaison/dominance, logMessages bidirectionnel et atomicité promotion
|
||||
pre.005 persistence Conflict : quarantine durable, observations par variante, races/concurrence
|
||||
pre.006 inspection Store API/lib des variants/conflicts/history + rétention/rehydration hardening
|
||||
pre.007 Worker : conflit durable non terminal, health Degraded et compteurs source-neutral
|
||||
pre.008 Store transient failure : retry/backpressure/blocked health sans perte silencieuse
|
||||
pre.009 Transport reconnect configurable et Config associée, sans inventer de coverage
|
||||
pre.010 Store Desk backend : queries/actions de conflits et résolutions
|
||||
pre.011 Store Desk frontend : vues conflicts/history, promote/keep/restore/reopen
|
||||
pre.012 fusion assistée/synthétique strictement bornée si les règles prouvées la permettent
|
||||
pre.013 hardening cross-layer : concurrence, cancellation, retention, rollback, security/redaction
|
||||
pre.014 preuves live PostgreSQL/Store + routes Worker sous conflits/retry/reconnect réellement testables
|
||||
pre.015 gate technique/live final : workspace, graphes, bundles/smokes pertinents
|
||||
pre.016 réconciliation documentaire finale
|
||||
pre.017 préparation de publication : CHANGELOG + ROADMAP + prompt 0.3.17
|
||||
rel.001 publication stable mécanique
|
||||
```
|
||||
|
||||
Si `pre.001` démontre qu'une tranche intermédiaire dépasse le budget d'environ 15–20 minutes de travail effectif, elle doit être scindée et les numéros suivants décalés. Les trois responsabilités finales restent dans l'ordre : technique/live -> documentation -> publication.
|
||||
|
||||
## 17. Hors périmètre de `0.3.16`
|
||||
|
||||
Ne pas inclure :
|
||||
|
||||
```text
|
||||
0.3.17 : transformation de ksp-job-backfill-lib en moteur multi-route/multi-stratégie
|
||||
0.3.18 : adaptation de ksp-app-backfill-desk au Backfill multi-route
|
||||
RAW -> STRUCTURAL / persistence STRUCTURAL
|
||||
DECODED / DOMAIN
|
||||
majority voting provider
|
||||
priorité canonique codée par provider
|
||||
fusion libre de JSON arbitraire
|
||||
reconstruction d'une variante perdue depuis Internet comme mécanisme normal de rollback
|
||||
nouveau second pipeline d'acquisition
|
||||
nouvelle dépendance Worker <-> Backfill
|
||||
```
|
||||
|
||||
Le Job Backfill continue cependant à utiliser les contrats Store communs existants. Si la migration de schéma `0.3.16` exige une compatibilité mécanique pour que le Job actuel continue de fonctionner, cette compatibilité appartient naturellement à `0.3.16`; elle ne doit pas être confondue avec le multi-route `0.3.17`.
|
||||
|
||||
## 18. Versionnement, deltas, validation et instruction d'ouverture
|
||||
|
||||
Respecter strictement `docs/rules/VERSION_WORKFLOW.md`.
|
||||
|
||||
Chaque changement code/build/runtime/config bump la version workspace. Les deltas sont livrés comme archives minimales :
|
||||
|
||||
```text
|
||||
ksp-general-0.3.16-pre.NNN.zip
|
||||
ksp-general-0.3.16-pre.NNN-fix.NNN.zip
|
||||
```
|
||||
|
||||
Les commandes de validation doivent être choisies selon la tranche et enregistrées dans son delta. 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 doivent être préférés pendant le développement ; le workspace complet appartient aux gates appropriés. Les smokes/live PostgreSQL/provider sont uniquement revendiqués lorsqu'ils sont réellement exécutés avec les ressources correspondantes.
|
||||
|
||||
Pour les applications Desk, ne pas utiliser `npm run build` comme gate manuel. Le workflow Tauri/Vite du projet reste l'autorité, par exemple :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-store-desk && cargo tauri dev)
|
||||
(cd crates/ksp-app-store-desk && cargo tauri build)
|
||||
```
|
||||
|
||||
Une commande non exécutée n'est jamais déclarée PASS.
|
||||
|
||||
### Instruction d'ouverture de la prochaine session
|
||||
|
||||
Commencer par :
|
||||
|
||||
```text
|
||||
1. vérifier que la base est exactement le tag stable v0.3.15 ;
|
||||
2. lire toutes les sources internes de la section 4 dans l'ordre ;
|
||||
3. réauditer les sources externes de la section 5 ;
|
||||
4. exécuter la mission pre.001 de la section 15 ;
|
||||
5. publier le plan/sizing avant toute migration ou développement lourd.
|
||||
```
|
||||
|
||||
Ne pas commencer par créer les tables `conflicts/variants`, modifier le Worker ou dessiner l'UI Store Desk avant d'avoir fermé le gate `pre.001`.
|
||||
|
||||
La release suivante envisagée après fermeture stable de `0.3.16` est :
|
||||
|
||||
```text
|
||||
0.3.17 — ksp-job-backfill-lib multi-route / multi-stratégie
|
||||
```
|
||||
Reference in New Issue
Block a user