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

0.3.16-pre.009

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-22 08:59:09 +02:00
parent f2227dce21
commit 40add02ac2
16 changed files with 498 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
crates/ksp-job-backfill-lib/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-job-backfill-lib/README.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# ksp-job-backfill-lib
@@ -56,7 +56,7 @@ ksp-job-backfill-lib
-X-> backend imposé par le job
```
Le chemin d'écriture est l'acquisition atomique `RawTransaction + RawTransactionObservation` en mode normal. La crate distingue insertion, déjà présent, tombstone purgé, observation nouvelle/existante, missing et conflit. Un conflit de contenu n'est jamais converti en succès idempotent.
Le chemin d'écriture est l'acquisition atomique `RawTransaction + RawTransactionObservation` en mode normal. La crate distingue insertion, déjà présent, tombstone purgé, observation nouvelle/existante, missing et conflit. Depuis `0.3.16`, un outcome Store `QuarantinedConflict` est projeté en `BackfillEntityPersistence::Conflict` tout en conservant l'outcome réel de l'observation (`Inserted` ou `AlreadyPresent`) ; il n'est jamais aplati en simple succès idempotent. Le code d'erreur legacy `ERROR_CODE_RAW_CONFLICT` reste pris en charge pour compatibilité.
## Concurrence et checkpoint
@@ -112,7 +112,7 @@ La crate ne possède pas :
- Worker API / worker live ;
- retry, pacing ou sélection d'endpoint Transport ;
- backend Store concret ;
- decoding Program ou matérialisation CORE/DECODE/SPECIALIZED ;
- decoding Program ou matérialisation STRUCTURAL/DECODED/DOMAIN ;
- table dédiée de checkpoint ;
- control plane Job générique.

6
crates/ksp-job-backfill-lib/USAGE.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-job-backfill-lib/USAGE.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Utilisation de ksp-job-backfill-lib
@@ -191,7 +191,7 @@ entity: Inserted | AlreadyPresent | SkippedPurged | Conflict
observation: Inserted | AlreadyPresent | NotRecorded | NotApplicable
```
`Missing` ne provoque aucune écriture Store. Un conflit de contenu reste observable comme conflit et ne doit pas être traité comme une relance idempotente réussie.
`Missing` ne provoque aucune écriture Store. Un `QuarantinedConflict` durable reste observable comme `Conflict`, mais l'outcome de l'observation Store est conservé : une réobservation peut donc produire `Conflict + AlreadyPresent`. Ce cas ne doit jamais être aplati en simple relance idempotente réussie. Un backend legacy qui renvoie encore le code Store de conflit est également projeté comme conflit de compatibilité.
## Frontières à respecter
@@ -203,4 +203,4 @@ Le caller ne doit pas :
- utiliser provider/endpoint comme identité transactionnelle ;
- inventer une provenance pour `getTransaction = null` ;
- interpréter un checkpoint caller-owned comme une garantie de persistence crash-safe automatique ;
- utiliser le job RAW comme decoder Program ou processor CORE.
- utiliser le job RAW comme decoder Program ou processor STRUCTURAL.

16
crates/ksp-store-lib/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-store-lib/README.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# ksp-store-lib
@@ -19,7 +19,7 @@ Elle expose aux consumers une surface backend-neutral, réexporte les contrats R
- `Store::health().await` pour la readiness portable et bornée ;
- `Store::close(self).await` pour la fermeture explicite bornée ;
- le mapping des erreurs backend vers des codes Store stables sans exposer les erreurs physiques ;
- les dix capabilities RAW de `ksp-store-api` dispatchées vers le backend compilé : six `RawTransaction*` et quatre `RawAccount*` ;
- les quatorze capabilities RAW de `ksp-store-api` dispatchées vers le backend compilé, dont les quatre capabilities d'inspection entity/observation ;
- une validation réseau backend-neutral avant dispatch pour toutes les opérations qui portent explicitement un réseau ;
- les réexports crate-root de `ksp-store-api` nécessaires aux consumers ordinaires.
@@ -65,7 +65,7 @@ Store ne lit ni `.env`, ni variables `KSP_*` / `KSPB_*`, ni variables/fichiers i
## Surface RAW
`Store` implémente exactement dix capabilities RAW backend-neutral :
`Store` implémente exactement quatorze capabilities RAW backend-neutral :
```text
RawTransactionRead
@@ -74,13 +74,17 @@ RawTransactionObservationRead
RawTransactionObservationWrite
RawTransactionRetentionRead
RawTransactionRetentionWrite
RawTransactionInspectionRead
RawTransactionObservationInspectionRead
RawAccountStateRead
RawAccountStateWrite
RawAccountObservationRead
RawAccountObservationWrite
RawAccountStateInspectionRead
RawAccountObservationInspectionRead
```
Pour `RawTransaction`, la façade fournit la lecture canonique et des observations, l'acquisition atomique transaction+observation, l'ajout idempotent d'observations, la pagination keyset et les transitions de rétention demandées par le caller.
Pour `RawTransaction`, la façade fournit la lecture canonique et des observations, l'acquisition atomique transaction+observation, l'ajout idempotent d'observations, les inspections random-access, la pagination keyset et les transitions de rétention demandées par le caller. Depuis `0.3.16`, l'outcome d'acquisition peut aussi exposer la classification de variante (`InsertedCanonical`, `ObservedExact`, `ObservedCompatibleLessComplete`, `PromotedCompatibleMoreComplete`, `QuarantinedConflict`, `Rehydrated`, `SkippedPurged`). `QuarantinedConflict` est un succès durable : la façade ne le transforme pas en erreur terminale.
Pour `RawAccountState`, elle fournit :
@@ -112,4 +116,6 @@ Sont volontairement hors de cette surface :
- [`../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md`](../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md) — plan `RawTransaction` ;
- [`../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md`](../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) — validation `RawTransaction` ;
- [`../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md`](../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md) — design `RawAccountState` et complétude RAW ;
- [`../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — validation `RawAccountState` et conformance 10/10.
- [`../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — validation `RawAccountState` ;
- [`../../docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md`](../../docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md) — variantes, sélecteur canonique et conflit durable ;
- [`../../docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md`](../../docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md) — validation `0.3.16` et preuve PostgreSQL live.

6
crates/ksp-store-lib/USAGE.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-store-lib/USAGE.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Utilisation de ksp-store-lib
@@ -195,7 +195,7 @@ async fn persist_acquisition(
Le mode `Normal` respecte un tombstone `Purged`. `ForceRehydrate` doit être choisi explicitement lorsqu'un caller veut restaurer un payload purgé et que l'identité retenue est compatible.
Un contenu divergent sous la même identité produit `ERROR_CODE_RAW_CONFLICT`; Store ne remplace jamais silencieusement le contenu gagnant.
Depuis `0.3.16`, le caller doit inspecter `RawAcquisitionWriteOutcome::transaction_variant()` pour une acquisition `RawTransaction`. Un contenu divergent conservable ne produit plus une erreur terminale : il retourne `QuarantinedConflict`, la variante reçue est durable et le canonique reste inchangé. `ObservedCompatibleLessComplete` conserve le canonique courant ; `PromotedCompatibleMoreComplete` signale une promotion atomique. `ERROR_CODE_RAW_CONFLICT` reste pertinent pour des chemins legacy/directs qui ne disposent pas de cette quarantaine durable.
## 8. Lire et ajouter une observation
@@ -379,6 +379,6 @@ Les conflits et queries invalides utilisent les codes backend-neutral `store_api
## 15. Limites de la façade
La façade ne fournit pas d'accès public au SQL, au pool, aux clients ou transactions PostgreSQL. Elle dispatch les dix capabilities RAW de l'API commune, mais ne fournit aucune capability de rétention, archivage, purge, delete ou compaction account.
La façade ne fournit pas d'accès public au SQL, au pool, aux clients ou transactions PostgreSQL. Elle dispatch les quatorze capabilities RAW de l'API commune, dont quatre capabilities d'inspection, mais ne fournit aucune capability de rétention, archivage, purge, delete ou compaction account.
La taille de page est une primitive de navigation. Les décisions de batch, priorité, backlog et scheduling appartiennent aux workers/jobs, pas à Store.

23
crates/ksp-store-postgres-lib/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-store-postgres-lib/README.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# ksp-store-postgres-lib
@@ -63,7 +63,18 @@ VerifyFull
Le moteur de migrations embarqué vérifie version logique, nom et checksum SHA-256, sérialise les runners par advisory transaction lock et refuse une history divergente ou plus récente que le runtime.
Le bootstrap metadata est conservé comme migration V000. La migration logique V001 matérialise le schéma `RawTransaction` et V002 le schéma `RawAccountState`, chacune en ressources séparées `tables/`, `constraints/` et `indexes/` afin que le backend puisse vérifier leur compatibilité effective sans transformer les fichiers SQL en parser généraliste.
Le bootstrap metadata est conservé comme migration V000. La migration logique V001 matérialise le schéma `RawTransaction`, V002 le schéma `RawAccountState` et V003 ajoute le sidecar multi-variantes `RawTransaction`. V000/V001/V002 restent byte/checksum-identiques. Les migrations sont découpées en ressources `tables/`, `constraints/` et `indexes/` afin que le backend puisse vérifier leur compatibilité effective sans transformer les fichiers SQL en parser généraliste.
V003 ajoute exactement les quatre tables métier suivantes :
```text
ksp_raw_transaction_variants
ksp_raw_transaction_canonical_selectors
ksp_raw_transaction_observation_variants
ksp_raw_transaction_conflicts
```
Le conflict case V003 de `0.3.16` est volontairement minimal (`Open`/réouverture idempotente, relation/reason/revision). Le lifecycle complet de résolution/historique est reporté à `0.3.17`.
La base est liée à un seul `RawNetworkId` via `ksp_store_identity`. Une migration enregistrée mais physiquement divergente est un mismatch ; les réparations additives sûres dépendent de `schema_autoupdate`.
@@ -108,9 +119,9 @@ persist_raw_transaction_acquisition
record_raw_transaction_observation
```
L'acquisition canonique et son observation initiale sont commises dans une seule transaction PostgreSQL. Les clés uniques physiques fournissent l'admission idempotente ; après un conflit unique, le backend verrouille la ligne gagnante et compare le contenu réel avant de conclure `AlreadyPresent` ou `Conflict`.
L'acquisition et son observation sont commises dans une seule transaction PostgreSQL. Après collision d'identité, le backend verrouille la ligne V001 avec `FOR UPDATE`, compare le contenu via le comparateur partagé puis persiste/réutilise la variante reçue. `Exact` et `CompatibleLessComplete` conservent le canonique, `CompatibleMoreComplete` met à jour atomiquement selector V003 et projection V001, tandis que `Conflict`/`Incomparable` ouvrent ou mettent à jour un conflict case durable sans modifier le canonique. La nouvelle observation est rattachée à la variante réellement reçue avant `COMMIT`.
Un tombstone `Purged` compatible produit `SkippedPurged/NotRecorded` en mode normal. `ForceRehydrate` restaure explicitement le payload `Full` et l'observation dans la même transaction.
Un tombstone `Purged` compatible produit `SkippedPurged/NotRecorded` en mode normal. `ForceRehydrate` restaure explicitement le payload `Full` et l'observation dans la même transaction. `content_hash` n'est qu'un préfiltre : les bytes disponibles restent l'autorité d'égalité.
## Pagination RAW transaction
@@ -181,4 +192,6 @@ La crate ne contient :
- [`../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md`](../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md) — design `RawTransaction` ;
- [`../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md`](../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) — validation `RawTransaction` ;
- [`../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md`](../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md) — design `RawAccountState` et complétude RAW ;
- [`../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — validation `RawAccountState` et conformance RAW.
- [`../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — validation `RawAccountState` et conformance RAW ;
- [`../../docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md`](../../docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md) — V003, convergence et conflit durable ;
- [`../../docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md`](../../docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md) — validation `0.3.16`, concurrence/rollback et live PostgreSQL 17.

6
crates/ksp-store-postgres-lib/USAGE.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-store-postgres-lib/USAGE.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Utilisation de ksp-store-postgres-lib
@@ -155,7 +155,7 @@ async fn persist_acquisition(
}
```
L'opération est atomique : le canonique et son observation initiale sont tous deux durables ou aucun ne l'est. Une identité déjà présente avec un contenu identique est idempotente ; un contenu divergent retourne `PostgresBackendErrorKind::Conflict` sans overwrite silencieux.
L'opération est atomique : variante reçue, observation, mapping observation->variante, selector/projection éventuels et conflict case sont tous durables ou aucun ne l'est. Une identité déjà présente avec un contenu exact est idempotente. Une divergence conservable retourne un succès `RawAcquisitionWriteOutcome` dont `transaction_variant()` vaut `QuarantinedConflict`; le canonique n'est pas écrasé. Une représentation strictement plus complète selon la seule preuve `logMessages` admise peut retourner `PromotedCompatibleMoreComplete` et promouvoir atomiquement le selector/projection. Les conflits d'observation directe et autres contrats legacy peuvent encore produire `PostgresBackendErrorKind::Conflict`.
Pour un tombstone purgé compatible, le mode `Normal` ne restaure pas le payload. `ForceRehydrate` doit être demandé explicitement pour rétablir un payload `Full`.
@@ -289,4 +289,4 @@ fn classify(error: &ksp_store_postgres_lib::PostgresBackendError) {
Le backend ne lit aucune variable d'environnement et ne possède aucune sélection de target Config. Les applications, jobs et workers doivent normalement passer par `ksp-store-lib`.
Les dix capabilities RAW communes sont implémentées par ce backend. Les décisions de batch, priorité, backlog, scheduling et policy de rétention restent hors de sa responsabilité ; aucune rétention/archivage/purge account n'est fournie.
Les quatorze capabilities RAW communes sont implémentées par ce backend, dont les quatre capabilities d'inspection entity/observation. Les décisions de batch, priorité, backlog, scheduling et policy de rétention restent hors de sa responsabilité ; aucune rétention/archivage/purge account n'est fournie.

4
crates/ksp-worker-raw-transaction-ingest-lib/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-worker-raw-transaction-ingest-lib/README.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# ksp-worker-raw-transaction-ingest-lib
@@ -289,7 +289,7 @@ variant quarantined conflict
store failure
```
En `0.3.16-pre.007`, un conflit de contenu classifié par le Store n'est plus une faute terminale : la variante entrante est conservée, le conflict case durable est ouvert ou mis à jour idempotemment et l'outcome `QuarantinedConflict` maintient le Worker `Running` avec une health `Degraded`. Un ancien backend qui renvoie encore `ERROR_CODE_RAW_CONFLICT` reste traité comme erreur terminale de compatibilité. La résolution explicite du conflict case n'appartient pas à cette tranche.
Depuis `0.3.16`, un conflit de contenu classifié par le Store n'est plus une faute terminale : la variante entrante est conservée, le conflict case durable est ouvert ou mis à jour idempotemment et l'outcome `QuarantinedConflict` maintient le Worker `Running` avec une health `Degraded`. Le hardening final prouve qu'une identité suivante continue d'atteindre le Store après cette quarantaine. Un ancien backend qui renvoie encore `ERROR_CODE_RAW_CONFLICT` reste traité comme erreur terminale de compatibilité. La résolution explicite du conflict case et le retry Store complet appartiennent à `0.3.17`.
## Snapshots et erreurs

4
crates/ksp-worker-raw-transaction-ingest-lib/USAGE.md
View File

@@ -1,5 +1,5 @@
<!-- file: crates/ksp-worker-raw-transaction-ingest-lib/USAGE.md -->
<!-- version: 16 -->
<!-- version: 17 -->
# Utilisation de ksp-worker-raw-transaction-ingest-lib
@@ -266,7 +266,7 @@ somme de leurs tâches d'hydration actives <= persistence_concurrency
Ces contraintes garantissent au moins une part à chaque source reference-bearing sans introduire de scheduler pondéré. Si les settings ne permettent pas cette répartition, le démarrage échoue avant spawn avec `runtime_invalid`; le caller doit augmenter la capacité concernée ou réduire le nombre de sources nécessitant une hydration.
Pour une même identité `(network, signature)`, le Worker ne choisit ni majorité ni provider préféré et n'écrase pas un contenu divergent ; le Store reste l'autorité durable finale. La cache run-local ne fait que sérialiser cette identité et chaque acquisition atteint le Store. Un entrant prouvé moins complet reste une observation compatible, un entrant prouvé plus complet peut devenir canonique atomiquement, et une divergence conflictuelle/incomparable est conservée comme variante avec un conflict case durable. L'outcome `QuarantinedConflict` n'arrête pas le Worker : il reste `Running` et sa health devient `Degraded`.
Pour une même identité `(network, signature)`, le Worker ne choisit ni majorité ni provider préféré et n'écrase pas un contenu divergent ; le Store reste l'autorité durable finale. Le cache run-local ne fait que sérialiser cette identité et chaque acquisition atteint le Store. Un entrant prouvé moins complet reste une observation compatible, un entrant prouvé plus complet peut devenir canonique atomiquement, et une divergence conflictuelle/incomparable est conservée comme variante avec un conflict case durable. L'outcome `QuarantinedConflict` n'arrête pas le Worker : il reste `Running`, sa health devient `Degraded` et les identités suivantes continuent à être persistées. Le retry Store/backoff configurable n'est pas encore fourni par `0.3.16`.
## Observer le snapshot concret