<!-- file: docs/guides/REPLAY_CORE_EXTRACTION_AND_MATERIALIZATION.md -->
<!-- version: 1 -->

# Guide extraction Core, replay et matérialisation

## Chaîne de traitement

```text
acquisition canonique
        ↓
extraction Core
        ↓
entrées de replay instruction-level
        ↓
reconnaissance et décodage
        ↓
observations et diagnostics
        ↓
matérialisation optionnelle
```

## Extraction Core

L’extraction transforme une transaction canonique persistée en entités Core normalisées. Elle doit conserver les index, comptes, Program IDs, succès ou échec de transaction et contexte nécessaire aux instructions internes.

```rust
let summary = match kb_pipeline::execute_core_extraction(
    request,
    observer,
).await {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
```

## Decode replay

Le replay sélectionne des instructions Core, applique une politique de dispatch et invoque les décodeurs compatibles.

- une reconnaissance incompatible ne produit pas d’observation ;
- une transaction échouée peut produire une intention non committée ;
- les diagnostics doivent rester distincts des observations ;
- la même entrée et la même version de pipeline doivent produire un résultat déterministe.

## Matérialisation

La matérialisation est optionnelle et idempotente. Elle transforme les événements décodés en projections métier sans inventer un état confirmé.

Une tâche de matérialisation doit préciser :

- la provenance de l’événement ;
- le statut committé ou non committé ;
- les clés d’idempotence ;
- les invariants de mise à jour ;
- le traitement des événements obsolètes ou contradictoires.

## Reprise

La progression persistée ne doit avancer qu’après clôture cohérente du candidat. Les erreurs partielles restent rejouables.

## Tests de référence

- extraction Core legacy et v0 ;
- instructions outer et inner ;
- transactions échouées ;
- dispatch vers le décodeur exact ;
- matérialisation optionnelle ;
- replay forcé et idempotence ;
- corrélations stateful Token-2022.

## Références

- `docs/architecture/PIPELINE_ARCHITECTURE.md` ;
- `docs/architecture/STORAGE_ARCHITECTURE.md` ;
- `kb-pipeline/USAGE.md` ;
- `kb-lib/USAGE.md` ;
- `kb-store/USAGE.md`.