v0.0.3-pre.006

deltas/0.0.3/pre.006.md

@@ -0,0 +1,194 @@
+<!-- file: deltas/0.0.3/pre.006.md -->
+<!-- version: 1 -->
+
+# Delta 0.0.3-pre.006
+
+## Base requise
+
+`v0.0.3-pre.005`.
+
+## Objectif
+
+Formaliser les niveaux durables de données, la séparation Materializer/Store et les garanties nécessaires à la reconstruction/replay avant de détailler les workers/jobs.
+
+## Version Cargo
+
+`workspace.package.version` passe de :
+
+```text
+0.0.3-pre.5
+```
+
+à :
+
+```text
+0.0.3-pre.6
+```
+
+Le header de `Cargo.toml` passe de version 11 à 12.
+
+## Fichiers ajoutés
+
+- `docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`
+- `deltas/0.0.3/pre.006.md`
+
+## Fichiers modifiés
+
+- `Cargo.toml`
+- `ROADMAP.md`
+- `docs/architecture/000-README.md`
+- `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md`
+- `docs/architecture/003-COMPONENT_CONTRACTS.md`
+- `docs/architecture/004-COMPONENT_INVENTORY.md`
+- `docs/architecture/005-DEPENDENCY_GRAPH.md`
+- `docs/rules/RULES_DEPENDENCIES.md`
+- `docs/rules/RULES_KSP.md`
+- `docs/IDEAS.md`
+- `docs/plans/001-V0_0_3_PLAN.md`
+- `prompts/001-V0_1_X_START_PROMPT.md`
+
+## Fichiers supprimés
+
+Aucun.
+
+## Décisions principales
+
+### Niveaux durables
+
+La persistence n'utilise pas N1/N2/N3/N4, réservés aux couches architecturales.
+
+```text
+D1 Raw
+D2 Core canonique
+D3 journal de matérialisation générique
+D4 projections spécialisées/queryables
+```
+
+D1/D2/D3 sont destinés à être fortement stabilisés ; D4 reste plus évolutif.
+
+### D1
+
+D1 conserve suffisamment d'information raw/provenance pour rejouer le processing sans réacquérir la blockchain lorsque les données nécessaires ont déjà été capturées.
+
+`ksp-worker-raw-retriever` et `ksp-job-backfill` produisent le même contrat D1 pour la même catégorie de donnée.
+
+### D2
+
+D2 contient les faits Core canoniques Solana.
+
+Top-level et CPI restent des faits distincts lorsque leurs invariants/requêtes diffèrent.
+
+### D3
+
+D3 est un journal durable obligatoire, équivalent conceptuel du rôle historique de `k_sol_mat_outputs`.
+
+Une extension externe de materializer doit pouvoir produire un output D3 générique sans imposer de table PostgreSQL spécialisée.
+
+### D4
+
+D4 contient les projections spécialisées/queryables.
+
+Les projections sont modélisées par faits canoniques lorsque les invariants le permettent, et non par familles de tables propres à Meteora/Raydium/Orca/etc.
+
+Les metadata d'assets/tokens peuvent normaliser Metaplex Token Metadata + Token-2022 Metadata ; SPM reste distinct.
+
+### Materializer
+
+Une seule API publique est prévue :
+
+```text
+ksp-materializer-api
+```
+
+avec des capacités conceptuelles D2 -> D3 et D3 -> D4.
+
+`ksp-materializer-lib` transforme mais ne persiste pas et ne dépend pas du Store.
+
+### Store
+
+`ksp-store-api` possède les contrats persistants D1/D2/D3/D4 et reste indépendant de Program/Materializer/Transport.
+
+`ksp-store-lib` contient PostgreSQL comme implémentation de référence.
+
+Une nouvelle projection relationnelle D4 implique explicitement un contrat Store/migration/backend.
+
+### Provenance et temporalités
+
+Chaque niveau dérivé doit pouvoir remonter à son input durable et à l'identité/version du processor.
+
+Les temporalités blockchain et locales restent distinctes. `block_time` reste optionnel et n'est jamais inventé.
+
+### Idempotence
+
+Le résultat durable est identifié conceptuellement par l'input logique, l'identité/version du processor et l'identité logique de l'output.
+
+Une nouvelle version peut produire un résultat distinct/supersédant sans dupliquer incohéremment une même version.
+
+### Replay
+
+Les replays sont indépendants :
+
+```text
+D1 -> D2
+D2 -> D3
+D3 -> D4
+```
+
+Ils seront exécutés sous forme de jobs bornés, pas comme modes cachés des workers live.
+
+### Notifications
+
+`ksp-store-api` possède le format canonique des notifications de données persistées.
+
+Une notification est seulement un wake-up et peut être perdue/dupliquée.
+
+Le Store et les marqueurs durables de backlog/idempotence font autorité.
+
+Ordre obligatoire :
+
+```text
+persist
+commit
+notify
+```
+
+Le mécanisme de diffusion reste séparé du contrat.
+
+## Plan ajusté
+
+La partie workers/jobs est déplacée vers une tranche dédiée :
+
+- `pre.007` — acquisition/workers/jobs/replay/backlog ;
+- `pre.008` — apps/managers/scenarios/orchestration ;
+- `pre.009` — plan des premières releases fonctionnelles ;
+- `pre.010` — clôture fondatrice.
+
+## Questions reportées
+
+### `pre.007`
+
+- lifecycle des quatre workers ;
+- jobs de replay ;
+- backlog/cursors/checkpoints ;
+- batching/concurrence ;
+- hot reconfiguration ;
+- mécanisme de notification de référence ;
+- reprise après crash/process restart.
+
+### Première release Store réelle
+
+- noms exacts de tables/DTO/repositories ;
+- contraintes/idempotence SQL ;
+- index/pagination ;
+- représentation des hashes/provenances/états ;
+- migrations ;
+- conversion des entiers Solana/PostgreSQL.
+
+## Validations
+
+- headers `file:` / `version:` vérifiés ;
+- `Cargo.toml` parsé et version `0.0.3-pre.6` vérifiée ;
+- référence vers `008-DATA_MATERIALIZATION_AND_STORE.md` vérifiée ;
+- nomenclature D1–D4 présente dans les documents structurants ;
+- plan recalé jusqu'à `pre.010` ;
+- aucune commande Cargo build/test exécutée : ce delta reste documentaire et n'ajoute aucun code Rust fonctionnel.