195 lines
5.2 KiB
Markdown
195 lines
5.2 KiB
Markdown
<!-- 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.
|