<!-- 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
```