khadhroony-solana-project/deltas/0.0.3/pre.006.md

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 :

0.0.3-pre.5

à :

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.

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 :

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 :

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 :

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.