v0.3.1-pre.001-fix-002

deltas/0.3.1/pre.001-fix.002.md

@@ -0,0 +1,194 @@
+<!-- file: deltas/0.3.1/pre.001-fix.002.md -->
+<!-- version: 1 -->
+
+# Delta `0.3.1-pre.001-fix.002` — taxonomie N1, STRUCTURAL et lifecycle RAW
+
+## 1. Base
+
+```text
+livraison : 0.3.1-pre.001-fix.001
+Cargo     : 0.3.1-pre.1
+```
+
+Le gate opérateur post-`fix.001` fourni est vert pour `cargo fmt --all`, audits Rust/Markdown, `cargo check --workspace` et `cargo clippy --workspace --all-targets`. L'opérateur indique également que la validation des tests est OK.
+
+Ce correctif reste strictement documentaire : aucune crate, API Rust, Config, dependency, migration ou runtime Store n'est créé.
+
+## 2. Motif
+
+Le brainstorming avant `pre.002` révèle que la taxonomie précédente était encore trop proche d'un pipeline linéaire et traitait à tort les logs transactionnels et `logsSubscribe` comme une même famille persistante.
+
+Le correctif doit aussi préserver deux besoins futurs avant qu'une API publique ne les rende difficiles à ajouter :
+
+```text
+frontière claire ksp-interface-lib / ksp-store-api
+processing versionné + retention/compaction/archive/purge du RAW
+```
+
+## 3. Taxonomie N1 corrigée
+
+Règle d'admission : deux réponses HTTP/WS/gRPC/provider convergent vers le même modèle N1 seulement si elles satisfont intégralement la même sémantique KSP sans perte.
+
+Classification courante :
+
+```text
+RawTransaction + observation
+    = N1 persistant certain
+
+transaction logMessages
+    = partie de RawTransaction ; extraction future en N2 STRUCTURAL
+
+RawAccountState + observation
+    = modèle N1 à prévoir après matrice de compatibilité
+
+TransactionStatusObservation
+    = modèle/observation à explorer et prévoir si la sémantique converge
+
+logsSubscribe / slot / vote
+    = event-only candidats ; pas de persistence Store par défaut
+
+RawBlock
+    = IDEA seulement ; getBlock sert d'abord de conteneur d'acquisition de transactions
+
+Yellowstone Entry
+    = examiné et non retenu actuellement
+```
+
+## 4. N2 renommé STRUCTURAL
+
+La chaîne historique :
+
+```text
+RAW -> CORE -> DECODE -> SPECIALIZED
+```
+
+est remplacée comme vocabulaire cible par :
+
+```text
+RAW -> STRUCTURAL -> DECODED -> DOMAIN
+```
+
+N2 décrit une décomposition structurelle, pas un « Core » métier. Le premier cas certain est `RawTransaction -> STRUCTURAL` avec transaction/message, account refs, instructions top-level, CPI/inner instructions, logs/meta/balances/return data.
+
+Toutes les familles N1 ne sont pas obligées de passer par N2.
+
+## 5. Frontière Interface / Store
+
+La règle fixée est :
+
+```text
+persistant / replayable / queryable
+    -> ksp-store-api
+
+observation durable d'un fait Store
+    -> ksp-store-api
+
+event-only passif inter-composants
+    -> ksp-interface-lib de préférence
+
+format canonique « donnée persistée disponible »
+    -> ksp-store-api, publication par worker/runtime après commit
+
+shape HTTP/WS/gRPC/provider
+    -> Transport seulement
+```
+
+Un modèle event-only n'implique jamais automatiquement une capability Store. Les conversions restent explicites lorsque les sémantiques diffèrent.
+
+## 6. Processing et lifecycle RAW
+
+L'audit des documents kbot2 embarqués dans l'archive kbot3 retrouve :
+
+```text
+full -> compacted -> archived -> purged
+```
+
+et un replay piloté par une identité de processing incluant stage, processor/version et input hash.
+
+KSP reprend les concepts en les redessinant :
+
+- aucun `processed: bool` ne constitue la preuve durable unique ;
+- le futur processing ledger doit être version-aware et input-hash-aware ;
+- la policy d'éligibilité à la rétention appartient à un worker/job/maintenance layer, pas au Store ;
+- le Store applique uniquement une transition logique/atomique demandée ;
+- un tombstone minimal reste après purge afin qu'un backfill normal n'acquière pas de nouveau la même transaction ;
+- une réhydratation après purge exige un mode explicitement forcé ;
+- les policies de rétention peuvent différer selon la famille RAW.
+
+Le payload RAW n'a donc pas vocation à rester éternellement en stockage chaud lorsque les couches dérivées et la policy active permettent sa compaction/archive/purge.
+
+## 7. ROADMAP
+
+`ROADMAP.md` est corrigé pour :
+
+- remplacer CORE par STRUCTURAL dans la progression future ;
+- rappeler que les niveaux ne sont pas obligatoires pour toutes les familles ;
+- préciser `0.3.1` avec admission cross-source, events non persistés et lifecycle/tombstone ;
+- ajouter un bloc TODO/IDEAS N1/processing/rétention ;
+- conserver `0.3.2 = ksp-store-lib + ksp-store-postgres-lib` inchangé.
+
+## 8. Version Cargo
+
+Fix documentaire uniquement. Conformément au workflow, `workspace.package.version` reste :
+
+```text
+0.3.1-pre.1
+```
+
+## 9. Fichiers modifiés
+
+```text
+ROADMAP.md
+docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
+docs/validation/018-V0_3_1_STORE_RAW.md
+```
+
+## 10. Fichier ajouté
+
+```text
+deltas/0.3.1/pre.001-fix.002.md
+```
+
+## 11. Fichiers supprimés
+
+```text
+aucun
+```
+
+## 12. Validations exécutées
+
+Dans l'environnement de génération du fix :
+
+```text
+python3 scripts/audit_rust_workspace_rules.py
+  General Rust rule audit: clean
+  Rust export completeness audit: 0 candidate(s)
+  KSP workspace Rust rule audit: clean
+
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
+  Markdown table audit: clean (184 table(s), 123 file(s))
+```
+
+`cargo` n'est pas disponible dans cet environnement. Le fix est strictement documentaire et la base opérateur post-`fix.001` a déjà passé `cargo fmt`, `cargo check` et Clippy. Après application du présent fix, le gate opérateur reste :
+
+```bash
+cargo fmt --all
+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/0.3.1
+cargo check --workspace
+cargo clippy --workspace --all-targets
+```
+
+Aucun code n'est modifié et aucun test Store ciblé n'existe encore.
+
+## 13. Suite
+
+`pre.002` peut ensuite créer le scaffold `ksp-store-api` avec une taxonomie désormais suffisamment contrainte pour éviter de figer :
+
+```text
+un faux RawLog persistant
+un pipeline N1->N2 obligatoire
+un processed bool irréversible
+une retention éternelle du RAW
+une dépendance implicite entre event runtime et Store
+```