khadhroony-bot3/migration/khadhroony-bot2-reference/kb_store_core

kb_store_core

kb_store_core déclare les contrats de stockage indépendants du backend concret.

Ce crate ne dépend pas de PostgreSQL, SQLite, Tauri ou du RPC. Il sert de frontière commune entre le pipeline, les applications, les workers et les implémentations de stockage.

Rôle exact

kb_store_core contient :

• les traits repository backend-agnostiques ;
• les DTOs applicatifs ou repository ;
• les entities proches des lignes SQL, sans dépendance vers PostgreSQL ;
• les types communs de pagination, tri et limites ;
• les contrats de healthcheck et de statut migrations ;
• les helpers d'erreur storage basés sur kb_core::Error et kb_core::Result.

kb_store_core ne contient pas :

• de pool PostgreSQL ;
• de SQL ;
• de migrations ;
• de logique Tauri ;
• de client RPC ;
• de dépendance vers kb_store_pg.

Layout obligatoire

src/
  lib.rs
  pagination.rs
  health.rs
  db_error.rs
  dtos.rs
  entities.rs
  repositories.rs
  dtos/
  entities/
  repositories/

Les fichiers dtos.rs, entities.rs et repositories.rs servent uniquement de façade de modules. Ils évitent mod.rs et conservent les sous-dossiers spécialisés.

Conventions de dossiers

Dossier	Rôle
entities/	Représentations proches des lignes SQL.
dtos/	Contrats applicatifs, Tauri ou repository.
repositories/	Traits repository backend-agnostiques.

Les structures Rust ne doivent pas être placées dans des modules de requêtes SQL.

Contrats actifs 0.3.4

Les premiers contrats stabilisés sont volontairement minimaux :

Type	Rôle
RawTransactionInsert	Entrée d’écriture pour une transaction canonique dans kb_sol_raw_transactions; from_canonical calcule le JSON et le hash déterministes.
TransactionObservationInsert	Entrée d’écriture légère pour kb_sol_obs_transaction_observations, sans payload source complet.
TransactionObservationOrigin	Origine Live, Backfill, Replay, Repair ou Migration.
TransactionObservationStatus	État technique de détection, réception, normalisation, persistance, échec ou absence temporaire.
CoreTransactionInsert	Transaction normalisée liée à la ligne canonical raw.
CoreAccountKeyInsert	Compte résolu statique ou ALT avec flags signer/writable.
CoreInstructionInsert	Instruction top-level résolue avec chemin et hash de payload.
CoreInnerInstructionInsert	Instruction CPI résolue avec parent, chemin et hash de payload.
CoreLogInsert	Log ordonné avec rattachement prudent et hash de texte.
CoreBalanceChangeInsert	Delta SOL ou token exact, déterministe et lié au compte résolu.
MdCoreInstructionReplayInput	Instruction avec contexte extrait, dont les instructions outer ordonnées depuis le contrat 2, pour les décodeurs.
CoreInstructionReplayFilter	Filtre de sélection des instructions à traiter ou rejouer.
CoreInstructionLifecycleMark	Marquage d'état pour une instruction normalisée.
CoreInstructionProcessingState	État opérationnel d'une instruction pour replay partiel.
DecodedEventInsert	Entrée d'écriture future pour kb_sol_decode_decoded_events.
MaterializedEventInsert	Entrée d'écriture future pour kb_sol_mat_*.
ProcessingLedgerMark	Contrat de marquage pour kb_sol_ops_processing_ledger.
CoreExtractionSelectionFilter	Sélection bornée par signatures, slots, état raw ou programme déjà indexé.
ProcessingLedgerIdentity	Identité stable stage/processor/version/input/hash.
CoreExtractionBundle	Graphe complet à persister atomiquement pour une signature.
CoreExtractionFailure	Échec rejouable avec code et message explicites.
RawPayloadLifecycleMark	Marquage d'état de rétention et de traitement raw.
InsertOutcome	Résultat commun d'insert, upsert ou skip.
PageRequest	Contrat de pagination borné.
SortDirection	Contrat de tri générique.
StoreBackendDescriptor	Diagnostic backend sans exposer le DSN complet.
StoreMigrationSnapshot	Diagnostic de version migrations sans imposer une stratégie SQL.

Traits repository

Les traits publics de 0.2.1 sont async et sans implémentation SQL :

StoreHealthStore
RawTransactionStore
CoreTransactionStore
CoreExtractionStore
ProgramObservationStore
DecodedEventStore
MaterializedEventStore
ProcessingLedgerStore

Ils définissent les frontières utilisées par kb_store_pg, kb_store_sqlite, le pipeline et les futures fenêtres de diagnostic.

Convention Entity

Une Entity représente une ligne logique stockée. Elle reste proche de la DB, mais ne doit pas imposer PostgreSQL dans kb_store_core.

Exemples actuels :

RawTransactionRow
TransactionObservationRow
CoreTransactionRow
CoreAccountKeyRow
CoreInstructionRow
CoreInnerInstructionRow
CoreLogRow
CoreBalanceChangeRow
DecodedEventRow
MaterializedEventRow
ProcessingLedgerRow

Convention Dto

Un Dto représente un contrat d'entrée, de sortie ou de diagnostic.

Exemples actuels :

RawTransactionInsert
TransactionObservationInsert
CoreTransactionInsert
CoreAccountKeyInsert
CoreInstructionInsert
CoreInnerInstructionInsert
CoreLogInsert
CoreBalanceChangeInsert
CoreInstructionReplayInput
StoreBackendDescriptor
StoreMigrationSnapshot

Tables Solana référencées

Les traits et DTOs doivent référencer les tables Solana par convention logique, mais sans SQL concret. Le nom physique PostgreSQL suit :

kb_sol_<domain>_<name>

Exemples :

kb_sol_raw_transactions
kb_sol_obs_transaction_observations
kb_sol_core_transactions
kb_sol_core_account_keys
kb_sol_core_instructions
kb_sol_core_inner_instructions
kb_sol_core_logs
kb_sol_core_balance_changes
kb_sol_obs_program_observations
kb_sol_ops_processing_ledger

Règles locales

• Les commentaires de code restent en anglais.
• La documentation Markdown reste en français.
• Les exports publics sont contrôlés depuis lib.rs.
• Les erreurs passent par kb_core::Error et kb_core::Result.
• Le crate doit rester testable offline.

Replay instruction-level

Le replay opérationnel doit pouvoir cibler CoreInstructionRow, pas seulement CoreTransactionRow. Cela permet à un décodeur de demander uniquement les instructions Pending, Failed ou ReplayRequested, filtrées par program_id et plage de slots.

Le décodage réel doit ensuite recevoir MdCoreInstructionReplayInput, c'est-à-dire une instruction avec son contexte extrait : comptes résolus, inner instructions, logs, balances et erreur de transaction. Cette décision prépare les futures tables kb_sol_core_instructions, kb_sol_core_logs, kb_sol_core_balance_changes et kb_sol_ops_processing_ledger sans figer encore leur SQL exact.

Extension 0.2.4

0.2.4 rend les contrats core effectivement utilisés par kb_store_pg. Le replay reste planifié depuis CoreInstructionRow, mais les décodeurs reçoivent MdCoreInstructionReplayInput avec account keys, inner instructions, logs et balance changes.

Le champ balance_change_index est ajouté au contrat CoreBalanceChangeInsert afin de dédupliquer les balance changes par ordre d'extraction dans une transaction.

Migration corrective 0.3.1

Les noms historiques RawRpcTransaction*, RawWsNotification*, kb_sol_raw_rpc_transactions et kb_sol_raw_ws_notifications restent uniquement dans les migrations et la documentation historique 0.2.x.

Le contrat actif utilise :

RawTransaction*
TransactionObservation*
kb_sol_raw_transactions
kb_sol_obs_transaction_observations

La transaction canonique contient le document rejouable source-indépendant et sa version. L’observation conserve uniquement la provenance, la méthode, les timestamps, les tailles, les hashes et les statuts techniques.

Contrat atomique 0.3.4

CoreExtractionStore sépare la logique de transformation de l’implémentation SQL. Le pipeline peut sélectionner les lignes raw, vérifier le ledger, persister un CoreExtractionBundle ou enregistrer un CoreExtractionFailure sans dépendre de PostgreSQL.

Contrats decode et matérialisation 0.4.0

DecodePipelineStore regroupe les opérations backend-agnostiques de sélection, skip, couverture, persistance atomique decode, échec et matérialisation. Les DTOs DecodePersistenceBundle et MaterializationPersistenceBundle imposent la cohérence entre processor, version, input key/hash, signature, instruction path, sorties et ledger.

La couverture machine-readable est portée par DecodeCoverageDeclarationInsert, DecodeCoverageObservationInsert et DecodeCoverageSummaryRow.

Contrat contextualisé 2

Depuis 0.4.1-pre.014, MdCoreInstructionReplayInput transporte outer_instructions_json, obligatoirement un tableau JSON. Chaque entrée représente une instruction outer avec instructionIndex, instructionPath, programId, payloadJson et payloadHash. La liste inclut l’instruction cible et conserve l’ordre numérique du message. Ce champ participe à la sérialisation déterministe et donc au hash de replay.

Ce changement est purement contractuel : il ne requiert aucune migration SQL et ne modifie pas les garanties d’idempotence ou de rollback des stores.