195 lines
6.1 KiB
Markdown
195 lines
6.1 KiB
Markdown
<!-- 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
|
|
```
|