Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.3-pre.003-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-30 10:21:48 +02:00
parent 61bf7ba468
commit c17e78c6a8
64 changed files with 2890 additions and 424 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Plan `0.3.3` — Store/PostgreSQL RawTransaction vertical slice
@@ -159,15 +159,17 @@ SHA-256 = d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
Le SQL crée uniquement `ksp_store_schema_migrations`. Le moteur stable considère toute migration appliquée `> 0` comme `SchemaNewer`; il doit donc être généralisé avant V001.
Convention figée pour la nouvelle ressource :
Convention initialement retenue en `pre.001`, puis corrigée par `pre.003-fix.001` avant toute tranche repository : V001 reste une migration logique unique (`version = 1`, `name = raw_transaction`) mais ses ressources physiques sont séparées et ordonnées sous :
```text
crates/ksp-store-postgres-lib/migrations/V001__raw_transaction.sql
version = 1
name = raw_transaction
checksum SHA-256 calculé sur les bytes embedded exacts
crates/ksp-store-postgres-lib/migrations/v001_raw_transaction/
tables/
constraints/
indexes/
```
Le checksum logique V001 est calculé de manière déterministe sur l'identifiant relatif et les bytes exacts de chaque ressource embedded dans l'ordre du registre. Cette correction ne transforme pas chaque table/contrainte/index en version de migration autonome.
### 5.3 Config `std.store` final
`config/std.store.json` est `format_version = 1`, profil par défaut `devnet` et contient exactement :
@@ -1040,17 +1042,36 @@ Statut matérialisé en `pre.002` :
- tests de checksum/inventory/bounds ;
- matérialiser `store.postgres_retention_compaction_unsupported`, sans modifier les contrats stables sauf preuve nouvelle d'un blocage réel.
Statut matérialisé en `pre.003` :
Statut du commit `pre.003` avant correctif :
- registre réel `[V000, V001]`, version courante `1` ;
- V000 reste byte-identique avec son checksum historique ;
- V001 est embarquée sous `migrations/V001__raw_transaction.sql` avec checksum SHA-256 `6fe57ed0313d2ed295280dd6e49f6d86695d4e4effee2724a25e36db1ea17761` ;
- V001 crée exactement `ksp_store_identity`, `ksp_raw_transactions`, `ksp_raw_transaction_observations`, `ksp_raw_transaction_archive_payloads` et l'index partiel `(slot, signature)` hors `purged` ;
- `slot` reste `NUMERIC(20,0)` et toutes les bornes physiques suivent les invariants `ksp-store-api` sans narrowing ;
- le hook V001 crée puis valide l'identité en `AppliedNow`, et valide seulement en `Existing` ; absence, forme invalide ou réseau différent deviennent un `MigrationMismatch` sûr sans rendre la valeur persistée ;
- `store.postgres_retention_compaction_unsupported` est réservé par valeur dans le backend et la façade, sans reverse dependency ;
- V000 byte-identique avec son checksum historique ;
- V001 monolithique possédait le checksum `6fe57ed0313d2ed295280dd6e49f6d86695d4e4effee2724a25e36db1ea17761` ;
- les quatre tables, contraintes et l'index partiel étaient créés, mais l'historique de migration ne prouvait pas à lui seul la compatibilité physique des objets réellement présents ;
- le hook V001 créait/validait déjà l'identité réseau sans rebind silencieuse ;
- aucune capability/repository `RawTransaction*` n'était encore implémentée.
### `0.3.3-pre.003-fix.001` — correction du contrat physique
Le correctif s'applique au commit `pre.003` et remplace la matérialisation SQL sans changer le numéro logique V001 :
- V000 est déplacée sous `migrations/v000_bootstrap/tables/001_ksp_store_schema_migrations.sql` **byte-identique** ; son checksum historique reste `d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450` ;
- V001 est éclatée en 40 ressources embedded : 4 tables, 35 contraintes, 1 index ;
- le checksum logique V001 devient `31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51`, calculé sur les identifiants relatifs et bytes ordonnés des ressources ;
- chaque ressource sait comment être créée de façon additive, mais `IF NOT EXISTS` n'est jamais considéré comme preuve de compatibilité ;
- le backend introspecte les catalogues PostgreSQL et classe chaque ressource `Compatible`, `Missing` ou `Incompatible` ;
- tables, colonnes obligatoires, nullabilité/types, précision `NUMERIC(20,0)`, PK/FK/CHECK, index partiel, RLS, triggers, rules et contraintes externes susceptibles de modifier les writes sont vérifiés ;
- les CHECK sont comparés à la définition canonique dérivée de leur propre ressource SQL, et non à une liste permissive de fragments ;
- une colonne externe est acceptée uniquement lorsque sa présence est prouvée non bloquante pour les writes KSP ; les indexes externes non uniques sont tolérés ; les extensions ambiguës ou write-constraining bloquent `Ready` ;
- `schema_autocreate` contrôle l'initialisation/adoption d'une base sans metadata KSP ; `schema_autoupdate` contrôle les migrations pending et les réparations additives sûres d'un schéma KSP existant ;
- aucune réparation destructive ou ambiguë n'est exécutée automatiquement : le backend bloque avec une erreur/log sûrs pour intervention manuelle ;
- une identité V001 absente sur une migration déjà appliquée n'est jamais recréée automatiquement ;
- Config `std.store` passe au format V2 pour séparer les deux politiques, tout en conservant la lecture V1 où `auto_migrate` mappe les deux valeurs ;
- les fichiers monolithiques `migrations/V000__bootstrap.sql` et `migrations/V001__raw_transaction.sql` sont supprimés explicitement par le delta ;
- aucune capability/repository `RawTransaction*` n'est encore implémentée.
Une base PostgreSQL sur laquelle le commit `pre.003` aurait déjà enregistré l'ancien checksum V001 n'est **pas** réécrite silencieusement : elle doit être réinitialisée si elle est jetable, ou réconciliée manuellement. Le correctif préserve ainsi la règle d'immutabilité de l'historique au lieu de masquer une divergence de prerelease.
### `0.3.3-pre.004` — mapping et lectures
- codecs SQL privés ;

62
docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Validation `0.3.3` — Store/PostgreSQL RawTransaction vertical slice
@@ -11,7 +11,7 @@ Cette validation accompagne :
0.3.3 — Store/PostgreSQL RawTransaction vertical slice
```
Elle démarre en `0.3.3-pre.001` comme matrice de preuve. Les gates opérateur de `pre.001` et `pre.002` sont verts. Les lignes non encore implémentées restent explicitement `À FAIRE`; elles ne sont pas présentées comme acquises.
Elle démarre en `0.3.3-pre.001` comme matrice de preuve. Les gates opérateur de `pre.001` et `pre.002` sont verts. `pre.003` a été commité avant son gate opérateur ; `pre.003-fix.001` corrige donc sa matérialisation physique par-dessus ce commit. Les lignes non encore implémentées restent explicitement `À FAIRE`; elles ne sont pas présentées comme acquises.
## 2. Baseline stable
@@ -206,14 +206,14 @@ Critère : aucune branche ne doit utiliser `as i64`, `as i32`, clamp ou saturati
### 7.1 Bootstrap
| Cas | Résultat attendu |
|-------------------------------------------|------------------------------------------------------------------------|
| V001 appliquée pour la première fois | identity créée avec le réseau runtime dans la transaction de bootstrap |
| réouverture même réseau | succès idempotent |
| réouverture autre réseau | erreur terminale sûre |
| V001 présente mais identity absente | mismatch/corruption, jamais rebind silencieuse |
| identity malformée | erreur terminale sûre |
| migration pending + auto_migrate disabled | backend non prêt, aucune persistence métier |
| Cas | Résultat attendu |
|-----------------------------------------------|------------------------------------------------------------------------|
| V001 appliquée pour la première fois | identity créée avec le réseau runtime dans la transaction de bootstrap |
| réouverture même réseau | succès idempotent |
| réouverture autre réseau | erreur terminale sûre |
| V001 présente mais identity absente | mismatch/corruption, jamais rebind silencieuse |
| identity malformée | erreur terminale sûre |
| migration pending + `schema_autoupdate=false` | backend non prêt, aucune persistence métier |
### 7.2 Pré-I/O capability
@@ -446,17 +446,25 @@ Preuves acquises en `pre.002` avant création réelle de V001 :
- les migrations pending sont appliquées dans l'ordre sous la transaction et l'advisory lock déjà acquis ;
- chaque migration vérifie encore la forme de la metadata avant d'insérer sa ligne d'historique.
Preuves matérialisées en `pre.003` avec la vraie V001 :
Le commit `pre.003` a matérialisé la vraie V001 et son binding réseau, mais son fichier SQL monolithique et le seul contrôle de l'historique ne suffisaient pas à prouver la compatibilité structurelle de la base. Son checksum V001 historique de prerelease était `6fe57ed0313d2ed295280dd6e49f6d86695d4e4effee2724a25e36db1ea17761`.
- registre réel `[V000, V001]` et version courante dérivée `1` ;
- historique V000 seul reconnu comme préfixe exact avec V001 pending ;
- historique V000+V001 exact reconnu comme complet ;
- checksum V001 figé à `6fe57ed0313d2ed295280dd6e49f6d86695d4e4effee2724a25e36db1ea17761` ;
- binding réseau réel branché dans le hook `StoreIdentity` ;
- inventaire physique exact : identity, canonical, observations, archive, index partiel ;
- bornes SQL statiquement alignées sur `u64`, `u32`, `RawTimestamp`, payload 16 MiB et source payload 64 MiB.
Preuves statiques ajoutées par `pre.003-fix.001` :
L'application V000 -> V001, le rollback réel du hook, la réouverture même/autre réseau et la divergence de checksum sur PostgreSQL réel restent à prouver dans le gate live dédié `pre.009`; ils ne sont pas déclarés PASS dans cette tranche.
- V000 déplacée byte-identique, checksum toujours `d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450` ;
- V001 logique unique composée de 40 ressources ordonnées : 4 tables, 35 contraintes et 1 index ;
- checksum V001 multi-ressources `31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51` ;
- anciens fichiers monolithiques absents après application du delta ;
- `CREATE ... IF NOT EXISTS`/guards servent uniquement à la création additive, jamais à déclarer un objet compatible ;
- inspection catalogue indépendante de l'historique avec états `Compatible`, `Missing`, `Incompatible` ;
- contraintes attendues comparées exactement à une définition canonique issue de la ressource SQL correspondante ;
- colonne externe nullable sans default/identity/generated acceptée comme extension non bloquante ;
- index externe non unique accepté ;
- mauvais type/nullabilité sur colonne obligatoire, extra colonne write-blocking, contrainte externe non équivalente, unique index autonome, trigger actif, rule ou RLS bloquent `Ready` ;
- ressource obligatoire manquante réparable seulement lorsque la politique le permet et que la réparation est additive/sûre ;
- identité V001 manquante sur un historique déjà appliqué reste terminale et n'est jamais auto-recréée ;
- `std.store` V2 sépare `schema_autocreate` et `schema_autoupdate`, avec lecture V1 conservée et mapping de `auto_migrate` vers les deux valeurs.
L'application V000 -> V001, les réparations réelles, le rollback du hook, la réouverture même/autre réseau et la matrice de drift sur PostgreSQL réel restent à prouver dans le gate live dédié `pre.009`; elles ne sont pas déclarées PASS par le correctif statique. Une base ayant déjà enregistré l'ancien checksum V001 de `pre.003` doit être réinitialisée ou réconciliée manuellement ; le moteur ne réécrit pas son historique silencieusement.
### 17.2 Binding réseau atomique
@@ -522,11 +530,21 @@ cap 500/1000 dans Store pagination
### `pre.003`
- V001 + tables/constraints/indexes : PASS statique ;
- V001 + tables/constraints/indexes : matérialisé puis corrigé par `pre.003-fix.001` ;
- binding réseau hook `AppliedNow`/`Existing` : PASS statique ;
- checksum/inventory/bounds tests : PASS statique ;
- code `postgres_retention_compaction_unsupported` backend + façade : PASS ;
- preuve PostgreSQL réelle V001 : différée à `pre.009`.
- gate opérateur `pre.003` : NON FOURNI avant le correctif.
### `pre.003-fix.001`
- arborescence versionnée et 40 ressources V001 : PASS statique ;
- V000 byte-identique/checksum historique : PASS statique ;
- checksum/inventory/order V001 multi-ressources : PASS statique ;
- contrat catalogue `Compatible/Missing/Incompatible` : PASS statique ;
- politiques `schema_autocreate` / `schema_autoupdate` + compatibilité Config V1 : PASS statique ;
- extensions externes non bloquantes tolérées, extensions write-blocking refusées : PASS statique ;
- preuve PostgreSQL réelle V001/drift/réparation : différée à `pre.009` ;
- gate Cargo opérateur : À EXÉCUTER.
### `pre.004`