khadhroony-solana-project/deltas/0.3.1/pre.001-fix.002.md

Delta 0.3.1-pre.001-fix.002 — taxonomie N1, STRUCTURAL et lifecycle RAW

1. Base

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 :

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 :

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 :

RAW -> CORE -> DECODE -> SPECIALIZED

est remplacée comme vocabulaire cible par :

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 :

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 :

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 :

0.3.1-pre.1

9. Fichiers modifiés

ROADMAP.md
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
docs/validation/018-V0_3_1_STORE_RAW.md

10. Fichier ajouté

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

11. Fichiers supprimés

aucun

12. Validations exécutées

Dans l'environnement de génération du fix :

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 :

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 :

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