v0.1.0-pre.064-065
This commit is contained in:
222
olddocs/archivekbot2/kb_store_core/README.md
Normal file
222
olddocs/archivekbot2/kb_store_core/README.md
Normal file
@@ -0,0 +1,222 @@
|
||||
<!-- file: kb_store_core/README.md -->
|
||||
<!-- version: 12 -->
|
||||
|
||||
# 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
|
||||
|
||||
```text
|
||||
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. |
|
||||
| `CoreInstructionReplayInput` | 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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
kb_sol_<domain>_<name>
|
||||
```
|
||||
|
||||
Exemples :
|
||||
|
||||
```text
|
||||
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 `CoreInstructionReplayInput`, 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 `CoreInstructionReplayInput` 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 :
|
||||
|
||||
```text
|
||||
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`, `CoreInstructionReplayInput` 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.
|
||||
Reference in New Issue
Block a user