v0.3.4-pre.012
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 379
|
||||
# version: 380
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.3.4-pre.11"
|
||||
version = "0.3.4-pre.12"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: crates/ksp-store-lib/README.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# 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 six capabilities `RawTransaction*` dispatchées vers le backend compilé ;
|
||||
- les dix capabilities RAW de `ksp-store-api` dispatchées vers le backend compilé : six `RawTransaction*` et quatre `RawAccount*` ;
|
||||
- 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.
|
||||
|
||||
@@ -63,9 +63,9 @@ Store ne lit ni `.env`, ni variables `KSP_*` / `KSPB_*`, ni variables/fichiers i
|
||||
|
||||
`ksp-config-lib` possède `std.store`, la résolution des secrets et la sélection du target. Il construit ensuite un `StoreSettings` backend-neutral. L'URI PostgreSQL reste nécessaire au runtime mais n'a aucun getter public dans `ksp-store-lib` et son `Debug` est redacted.
|
||||
|
||||
## Surface RawTransaction
|
||||
## Surface RAW
|
||||
|
||||
`Store` implémente les six capabilities transactionnelles acquises dans `ksp-store-api` :
|
||||
`Store` implémente exactement dix capabilities RAW backend-neutral :
|
||||
|
||||
```text
|
||||
RawTransactionRead
|
||||
@@ -74,24 +74,29 @@ RawTransactionObservationRead
|
||||
RawTransactionObservationWrite
|
||||
RawTransactionRetentionRead
|
||||
RawTransactionRetentionWrite
|
||||
RawAccountStateRead
|
||||
RawAccountStateWrite
|
||||
RawAccountObservationRead
|
||||
RawAccountObservationWrite
|
||||
```
|
||||
|
||||
Le consumer manipule uniquement les modèles et outcomes backend-neutral. Les erreurs physiques PostgreSQL sont projetées vers des codes Store stables sans exposer le backend.
|
||||
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.
|
||||
|
||||
La façade fournit ainsi :
|
||||
Pour `RawAccountState`, elle fournit :
|
||||
|
||||
- lecture d'une transaction canonique, de ses observations et de sa rétention ;
|
||||
- écriture atomique transaction + observation ;
|
||||
- ajout idempotent d'observations ;
|
||||
- pagination keyset déterministe par cursor opaque ;
|
||||
- application de transitions de rétention demandées par le caller ;
|
||||
- validation réseau avant dispatch lorsqu'un input porte explicitement son réseau.
|
||||
- lecture d'un état complet par référence durable `(network, pubkey, slot, state_hash)` ;
|
||||
- pagination keyset des références dans l'ordre total `(slot, pubkey, state_hash)`, avec filtre pubkey optionnel ;
|
||||
- écriture atomique état+observation avec idempotence exacte et conflit sur contenu divergent ;
|
||||
- lecture et ajout d'observations account ;
|
||||
- validation réseau avant dispatch pour les opérations dont l'input porte explicitement un réseau.
|
||||
|
||||
Les cursors restent opaques et propres à leur famille. Store ne leur attribue aucune sémantique de batch, priorité ou scheduling.
|
||||
|
||||
## Hors périmètre
|
||||
|
||||
Sont volontairement hors de cette surface :
|
||||
|
||||
- persistence/query/rétention PostgreSQL de `RawAccountState` ;
|
||||
- rétention, archivage, purge, delete ou compaction de `RawAccountState` ;
|
||||
- batch-size, priorité, backlog ou policy de worker/job ;
|
||||
- transport d'acquisition, Program decoding et materialization ;
|
||||
- exposition publique de SQL, pool, client, row, statement ou transaction PostgreSQL.
|
||||
@@ -105,4 +110,6 @@ Sont volontairement hors de cette surface :
|
||||
- [`../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) — plan de fondation ;
|
||||
- [`../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md) — validation de fondation ;
|
||||
- [`../../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/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.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: crates/ksp-store-lib/USAGE.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Utilisation de ksp-store-lib
|
||||
|
||||
@@ -268,7 +268,98 @@ async fn archive_transaction(
|
||||
|
||||
Le backend PostgreSQL supporte physiquement `Full -> Archived -> Purged`. Une transition impliquant `Compacted` est rejetée par ce backend tant qu'aucune représentation compactée réelle n'est implémentée.
|
||||
|
||||
## 11. Diagnostics et erreurs
|
||||
## 11. Lire et paginer les états account RAW
|
||||
|
||||
Importer `RawAccountStateRead` donne accès à la lecture par référence et à la navigation déterministe.
|
||||
|
||||
```rust
|
||||
use ksp_store_lib::RawAccountStateRead;
|
||||
|
||||
async fn read_account_state(
|
||||
store: &ksp_store_lib::Store,
|
||||
reference: &ksp_store_lib::RawAccountStateReference,
|
||||
) -> ksp_store_lib::Result<std::option::Option<ksp_store_lib::RawAccountState>> {
|
||||
return store.get_raw_account_state(reference).await;
|
||||
}
|
||||
```
|
||||
|
||||
Pour une première page :
|
||||
|
||||
```rust
|
||||
use ksp_store_lib::RawAccountStateRead;
|
||||
|
||||
async fn first_account_page(
|
||||
store: &ksp_store_lib::Store,
|
||||
network: ksp_store_lib::RawNetworkId,
|
||||
pubkey: std::option::Option<ksp_store_lib::Pubkey>,
|
||||
) -> ksp_store_lib::Result<ksp_store_lib::RawPage<ksp_store_lib::RawAccountStateReference>> {
|
||||
let limit = ksp_store_lib::RawPageLimit::new(100);
|
||||
let limit = match limit {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
|
||||
let slots = ksp_store_lib::RawSlotRange::new(std::option::Option::None, std::option::Option::None);
|
||||
let slots = match slots {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
|
||||
let query = ksp_store_lib::RawAccountStateQuery::new(
|
||||
network,
|
||||
pubkey,
|
||||
slots,
|
||||
ksp_store_lib::RawSortDirection::Ascending,
|
||||
ksp_store_lib::RawPageRequest::first(limit),
|
||||
);
|
||||
|
||||
return store.list_raw_account_states(&query).await;
|
||||
}
|
||||
```
|
||||
|
||||
La continuation utilise uniquement `RawPage::next_cursor()` puis `RawPageRequest::after`. Le cursor account est opaque et lié au réseau, au filtre pubkey, à la direction et aux bornes de slots de la query qui l'a produit.
|
||||
|
||||
## 12. Persister une acquisition account
|
||||
|
||||
L'état canonique et son observation initiale sont une seule opération atomique.
|
||||
|
||||
```rust
|
||||
use ksp_store_lib::RawAccountStateWrite;
|
||||
|
||||
async fn persist_account_acquisition(
|
||||
store: &ksp_store_lib::Store,
|
||||
state: ksp_store_lib::RawAccountState,
|
||||
observation: ksp_store_lib::RawAccountObservation,
|
||||
) -> ksp_store_lib::Result<ksp_store_lib::RawAcquisitionWriteOutcome> {
|
||||
return store.persist_raw_account_acquisition(state, observation).await;
|
||||
}
|
||||
```
|
||||
|
||||
`state.reference()` et `observation.account()` doivent désigner exactement le même état et le réseau du `Store`. Une répétition byte-identique est idempotente ; un contenu divergent sous la même identité retourne `ERROR_CODE_RAW_CONFLICT`.
|
||||
|
||||
## 13. Lire et ajouter une observation account
|
||||
|
||||
```rust
|
||||
use ksp_store_lib::RawAccountObservationRead;
|
||||
use ksp_store_lib::RawAccountObservationWrite;
|
||||
|
||||
async fn use_account_observation(
|
||||
store: &ksp_store_lib::Store,
|
||||
key: &ksp_store_lib::RawObservationKey,
|
||||
observation: ksp_store_lib::RawAccountObservation,
|
||||
) -> ksp_store_lib::Result<ksp_store_lib::RawObservationWriteOutcome> {
|
||||
let existing = store.get_raw_account_observation(key).await;
|
||||
if let std::result::Result::Err(error) = existing {
|
||||
return std::result::Result::Err(error);
|
||||
}
|
||||
|
||||
return store.record_raw_account_observation(observation).await;
|
||||
}
|
||||
```
|
||||
|
||||
`record_raw_account_observation` ne crée jamais implicitement l'état canonique ; une référence absente retourne `ERROR_CODE_RAW_REFERENCE_NOT_FOUND`. `RawObservationKey` ne contient pas de réseau : la lecture par clé reste liée au backend mono-réseau déjà ouvert.
|
||||
|
||||
## 14. Diagnostics et erreurs
|
||||
|
||||
Les snapshots et erreurs de façade n'exposent ni URI, host, user, database, SQL, handle backend, valeur de bind ni texte d'erreur PostgreSQL.
|
||||
|
||||
@@ -286,8 +377,8 @@ store.postgres_retention_compaction_unsupported
|
||||
|
||||
Les conflits et queries invalides utilisent les codes backend-neutral `store_api.raw_conflict` et `store_api.raw_query_invalid`.
|
||||
|
||||
## 12. Limites de la façade
|
||||
## 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. Les capabilities `RawAccount*` réexportées par l'API commune ne sont pas encore dispatchées par `Store`.
|
||||
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 taille de page est une primitive de navigation. Les décisions de batch, priorité, backlog et scheduling appartiennent aux workers/jobs, pas à Store.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: crates/ksp-store-postgres-lib/README.md -->
|
||||
<!-- version: 10 -->
|
||||
<!-- version: 11 -->
|
||||
|
||||
# ksp-store-postgres-lib
|
||||
|
||||
@@ -18,7 +18,7 @@ La crate possède seule pour PostgreSQL :
|
||||
- le bootstrap et le moteur de migrations privé KSP ;
|
||||
- la table metadata `ksp_store_schema_migrations` ;
|
||||
- l'advisory transaction lock borné des migrations ;
|
||||
- le schéma physique et les statements privés `RawTransaction` ;
|
||||
- les schémas physiques et statements privés `RawTransaction` et `RawAccountState` ;
|
||||
- les snapshots runtime/health sûrs destinés au bridge de façade ;
|
||||
- la fermeture explicite du pool et son fallback `Drop` best-effort ;
|
||||
- la classification d'erreurs backend sans conserver le texte d'erreur PostgreSQL.
|
||||
@@ -63,7 +63,7 @@ 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` 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` 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.
|
||||
|
||||
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`.
|
||||
|
||||
@@ -130,11 +130,43 @@ Le backend verrouille la ligne canonique avec `FOR UPDATE`, compare l'état cour
|
||||
|
||||
Toute transition impliquant `Compacted` est rejetée avec `RetentionCompactionUnsupported` tant qu'aucune représentation compactée réelle n'est implémentée.
|
||||
|
||||
## Lectures RAW account
|
||||
|
||||
Le backend expose :
|
||||
|
||||
```text
|
||||
get_raw_account_state
|
||||
get_raw_account_observation
|
||||
```
|
||||
|
||||
`get_raw_account_state` reconstruit l'état complet à partir de `(pubkey, slot, state_hash)` sans narrowing du domaine `u64`. Les bytes `pubkey`, `owner` et `state_hash` sont revalidés à leur largeur exacte et `data` reste un `BYTEA` complet, vide autorisé, borné par le contrat Store API.
|
||||
|
||||
`get_raw_account_observation` reconstruit la provenance commune et les métadonnées account optionnelles, notamment `is_startup`, `transaction_signature` et `write_version`. La signature est une metadata fixed-width et ne crée aucune FK vers la famille transaction.
|
||||
|
||||
## Écritures RAW account
|
||||
|
||||
Le backend expose :
|
||||
|
||||
```text
|
||||
persist_raw_account_acquisition
|
||||
record_raw_account_observation
|
||||
```
|
||||
|
||||
L'acquisition état+observation est transactionnelle. Les inserts utilisent `ON CONFLICT ... DO NOTHING`, puis verrouillent et comparent le contenu gagnant avant de conclure `AlreadyPresent` ou `Conflict`; aucun `DO UPDATE` n'est utilisé. Une collision divergente d'observation fait échouer toute l'acquisition et rollback un éventuel nouvel état.
|
||||
|
||||
L'ajout d'une observation vérifie que l'état référencé existe déjà et ne crée jamais implicitement cet état.
|
||||
|
||||
## Pagination RAW account
|
||||
|
||||
`list_raw_account_states` parcourt les références selon l'ordre total `(slot, pubkey, state_hash)`, en ASC ou DESC, avec filtre pubkey optionnel. La continuation est keyset, sans `OFFSET`.
|
||||
|
||||
Le cursor `KSPA` est opaque et lié au réseau, au filtre pubkey, à la direction, aux bornes de slots et à la dernière clé complète. Il est distinct du cursor transaction `KSPT`.
|
||||
|
||||
## Hors périmètre
|
||||
|
||||
La crate ne contient :
|
||||
|
||||
- aucune implémentation PostgreSQL des capabilities `RawAccount*` ;
|
||||
- aucune rétention, archive, purge, suppression ou compaction account ;
|
||||
- aucune orchestration worker/job ;
|
||||
- aucun transport d'acquisition ou decoder Program ;
|
||||
- aucune policy autonome de batch, priorité ou rétention.
|
||||
@@ -147,4 +179,6 @@ La crate ne contient :
|
||||
- [`../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) — décisions pool/TLS/migrations ;
|
||||
- [`../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md) — validation de fondation ;
|
||||
- [`../../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/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.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: crates/ksp-store-postgres-lib/USAGE.md -->
|
||||
<!-- version: 10 -->
|
||||
<!-- version: 11 -->
|
||||
|
||||
# Utilisation de ksp-store-postgres-lib
|
||||
|
||||
@@ -202,7 +202,58 @@ Le backend applique la transition choisie par le caller ; il ne décide pas de l
|
||||
|
||||
Une transition impliquant `Compacted` est refusée avec `PostgresBackendErrorKind::RetentionCompactionUnsupported` tant qu'aucune représentation compactée réelle n'est disponible.
|
||||
|
||||
## 11. Classifier les erreurs sans fuite
|
||||
## 11. Lire et paginer les états account
|
||||
|
||||
```rust
|
||||
async fn read_account_state(
|
||||
backend: &ksp_store_postgres_lib::PostgresBackend,
|
||||
reference: &ksp_store_api::RawAccountStateReference,
|
||||
) -> std::result::Result<std::option::Option<ksp_store_api::RawAccountState>, ksp_store_postgres_lib::PostgresBackendError> {
|
||||
return backend.get_raw_account_state(reference).await;
|
||||
}
|
||||
```
|
||||
|
||||
Pour la navigation, construire un `RawAccountStateQuery` puis appeler :
|
||||
|
||||
```rust
|
||||
async fn list_account_states(
|
||||
backend: &ksp_store_postgres_lib::PostgresBackend,
|
||||
query: &ksp_store_api::RawAccountStateQuery,
|
||||
) -> std::result::Result<ksp_store_api::RawPage<ksp_store_api::RawAccountStateReference>, ksp_store_postgres_lib::PostgresBackendError> {
|
||||
return backend.list_raw_account_states(query).await;
|
||||
}
|
||||
```
|
||||
|
||||
La pagination est keyset sur `(slot, pubkey, state_hash)` avec filtre pubkey optionnel. Le cursor `KSPA` est opaque, lié au contexte de query et distinct du cursor transaction.
|
||||
|
||||
## 12. Persister une acquisition account
|
||||
|
||||
```rust
|
||||
async fn persist_account_acquisition(
|
||||
backend: &ksp_store_postgres_lib::PostgresBackend,
|
||||
state: ksp_store_api::RawAccountState,
|
||||
observation: ksp_store_api::RawAccountObservation,
|
||||
) -> std::result::Result<ksp_store_api::RawAcquisitionWriteOutcome, ksp_store_postgres_lib::PostgresBackendError> {
|
||||
return backend.persist_raw_account_acquisition(state, observation).await;
|
||||
}
|
||||
```
|
||||
|
||||
Le backend exige le même réseau et la même référence complète entre l'état et l'observation avant l'I/O métier. L'opération est atomique et idempotente par comparaison exacte du contenu persistant ; un contenu divergent produit `PostgresBackendErrorKind::Conflict` sans overwrite silencieux.
|
||||
|
||||
## 13. Lire et ajouter une observation account
|
||||
|
||||
```rust
|
||||
async fn record_account_observation(
|
||||
backend: &ksp_store_postgres_lib::PostgresBackend,
|
||||
observation: ksp_store_api::RawAccountObservation,
|
||||
) -> std::result::Result<ksp_store_api::RawObservationWriteOutcome, ksp_store_postgres_lib::PostgresBackendError> {
|
||||
return backend.record_raw_account_observation(observation).await;
|
||||
}
|
||||
```
|
||||
|
||||
La lecture correspondante utilise `get_raw_account_observation`. L'ajout exige un état déjà durable et retourne `ReferenceNotFound` lorsqu'il manque. Les métadonnées Yellowstone optionnelles sont conservées sans créer de couplage physique vers `RawTransaction`.
|
||||
|
||||
## 14. Classifier les erreurs sans fuite
|
||||
|
||||
```rust
|
||||
fn classify(error: &ksp_store_postgres_lib::PostgresBackendError) {
|
||||
@@ -234,8 +285,8 @@ fn classify(error: &ksp_store_postgres_lib::PostgresBackendError) {
|
||||
|
||||
`PostgresBackendError` conserve uniquement une classification KSP et une phase statique. Ne pas reconstruire de diagnostic utilisateur à partir d'une erreur brute PostgreSQL.
|
||||
|
||||
## 12. Limites du backend direct
|
||||
## 15. Limites du backend direct
|
||||
|
||||
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 capabilities `RawAccount*` ne sont pas implémentées par ce backend. Les décisions de batch, priorité, backlog, scheduling et policy de rétention restent hors de sa responsabilité.
|
||||
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.
|
||||
|
||||
185
deltas/0.3.4/pre.012.md
Normal file
185
deltas/0.3.4/pre.012.md
Normal file
@@ -0,0 +1,185 @@
|
||||
<!-- file: deltas/0.3.4/pre.012.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.4-pre.012` — réconciliation documentaire finale Store/PostgreSQL RAW
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
Base directe attendue :
|
||||
|
||||
```text
|
||||
0.3.4-pre.011
|
||||
```
|
||||
|
||||
Le couloir technique est fermé. Le replay de `pre.011` confirme les tests façade sans backend, le workspace complet, les graphes Cargo et le live `RawAccountState` sur PostgreSQL 17.
|
||||
|
||||
## 2. Objectif
|
||||
|
||||
Réconcilier exclusivement les documents durables avec la surface Store/PostgreSQL effectivement validée.
|
||||
|
||||
Cette tranche ne rouvre aucun comportement Rust, test fonctionnel, Config, schema, migration, dépendance ou feature et ne prépare pas encore la publication.
|
||||
|
||||
## 3. Version
|
||||
|
||||
Conformément à `VER-ID-009`, cette prerelease non-fix synchronise :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.4-pre.12
|
||||
```
|
||||
|
||||
Aucune autre propriété Cargo n'est modifiée.
|
||||
|
||||
## 4. Résultat technique hérité
|
||||
|
||||
```text
|
||||
Store/Postgres RAW capabilities 10/10
|
||||
RawTransaction capabilities 6
|
||||
RawAccount capabilities 4
|
||||
ksp-store-lib --no-default-features PASS
|
||||
cargo test --workspace PASS
|
||||
Cargo graphs façade/backend/features/duplicates exécutés
|
||||
postgres_raw_account_live PASS — PostgreSQL 17
|
||||
V002 resources 32
|
||||
V002 checksum ff21605ed45f7ab4c0f92bbb692700b4118a9488b04d50a31d259ac59bdb550e
|
||||
```
|
||||
|
||||
Les doublons Cargo du workspace sont transverses et ne révèlent aucune duplication propre au Store nécessitant une correction.
|
||||
|
||||
## 5. Réconciliation `ksp-store-lib`
|
||||
|
||||
Le README et le USAGE décrivent désormais durablement :
|
||||
|
||||
```text
|
||||
exactement 10 capabilities RAW
|
||||
6 RawTransaction* + 4 RawAccount*
|
||||
lecture RawAccountState par référence
|
||||
pagination keyset (slot,pubkey,state_hash), filtre pubkey optionnel
|
||||
acquisition account atomique et idempotence exacte
|
||||
lecture/ajout d'observation account
|
||||
cursors opaques family-local
|
||||
aucune rétention/archive/purge/delete/compaction account
|
||||
aucune policy batch/priorité/scheduling dans Store
|
||||
```
|
||||
|
||||
Les anciennes affirmations indiquant que les capabilities `RawAccount*` n'étaient pas dispatchées sont supprimées.
|
||||
|
||||
## 6. Réconciliation `ksp-store-postgres-lib`
|
||||
|
||||
Le README et le USAGE décrivent désormais :
|
||||
|
||||
```text
|
||||
V001 = schéma RawTransaction
|
||||
V002 = schéma RawAccountState
|
||||
lectures state/observation account
|
||||
acquisition state+observation atomique
|
||||
observation supplémentaire reference-guarded
|
||||
pagination keyset account et cursor KSPA
|
||||
aucun ON CONFLICT DO UPDATE
|
||||
aucune FK account transaction_signature -> RawTransaction
|
||||
aucune rétention destructive account
|
||||
```
|
||||
|
||||
La crate reste un backend physique derrière `ksp-store-lib`, jamais une seconde façade applicative.
|
||||
|
||||
## 7. Documents de release
|
||||
|
||||
Le plan `025` enregistre le PASS technique de `pre.011`, synchronise la version de travail sur `pre.012` et marque la réconciliation documentaire comme matérialisée.
|
||||
|
||||
La validation `021` ferme le verdict `pre.011` et ouvre le verdict documentaire `pre.012`.
|
||||
|
||||
`README.md` racine et les architectures Store ont été relus ; aucune affirmation devenue fausse n'y justifie une modification artificielle. `ksp-store-api` n'acquiert pas un README/USAGE uniquement pour cette tranche.
|
||||
|
||||
## 8. Hors scope préservé
|
||||
|
||||
```text
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
prompt 0.3.5
|
||||
src/**
|
||||
tests/**
|
||||
config/**
|
||||
migrations/**
|
||||
account retention/archive/purge/delete/compaction
|
||||
workers/jobs/backfills
|
||||
batch/priorité/backlog policy
|
||||
nouveau backend
|
||||
Store Desk
|
||||
```
|
||||
|
||||
La préparation minimale `CHANGELOG`/`ROADMAP`/prompt reste réservée à `pre.013`.
|
||||
|
||||
## 9. Fichiers ajoutés
|
||||
|
||||
```text
|
||||
deltas/0.3.4/pre.012.md
|
||||
```
|
||||
|
||||
## 10. Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-store-lib/README.md
|
||||
crates/ksp-store-lib/USAGE.md
|
||||
crates/ksp-store-postgres-lib/README.md
|
||||
crates/ksp-store-postgres-lib/USAGE.md
|
||||
docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md
|
||||
docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md
|
||||
```
|
||||
|
||||
## 11. Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## 12. Migrations
|
||||
|
||||
Aucune migration n'est modifiée.
|
||||
|
||||
```text
|
||||
V000 d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
|
||||
V001 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51
|
||||
V002 ff21605ed45f7ab4c0f92bbb692700b4118a9488b04d50a31d259ac59bdb550e
|
||||
```
|
||||
|
||||
## 13. Validations de génération
|
||||
|
||||
Les validations statiques applicables ont été rejouées après matérialisation de l'overlay :
|
||||
|
||||
```text
|
||||
General Rust rule audit: clean
|
||||
Rust export completeness audit: 0 candidate(s)
|
||||
KSP workspace Rust rule audit: clean
|
||||
Markdown table audit: clean (240 table(s), 151 file(s))
|
||||
protected src/tests/config/migrations byte-identical à pre.011: PASS
|
||||
```
|
||||
|
||||
Les exécutables Cargo/Rust ne sont pas disponibles dans l'environnement de génération ; aucun résultat Cargo post-overlay n'est revendiqué ici.
|
||||
|
||||
## 14. Gate opérateur après application
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.4
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-store-api
|
||||
cargo test -p ksp-store-lib
|
||||
cargo test -p ksp-store-postgres-lib
|
||||
cargo test -p ksp-config-lib
|
||||
cargo check -p ksp-store-lib --no-default-features
|
||||
```
|
||||
|
||||
Aucun nouveau live PostgreSQL, `cargo test --workspace` ou graphe Cargo n'est requis par cette tranche documentaire ; ces preuves sont déjà fermées par `pre.011`.
|
||||
|
||||
## 15. Questions ouvertes
|
||||
|
||||
Aucune pour le périmètre `0.3.4`.
|
||||
|
||||
## 16. Suite
|
||||
|
||||
Après gate documentaire vert :
|
||||
|
||||
```text
|
||||
0.3.4-pre.013 — préparation publication minimale + prompt 0.3.5
|
||||
0.3.4-rel.001 — stabilisation/tag v0.3.4
|
||||
```
|
||||
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md -->
|
||||
<!-- version: 17 -->
|
||||
<!-- version: 18 -->
|
||||
|
||||
# Plan `0.3.4` — Store/PostgreSQL `RawAccountState` + complétude RAW
|
||||
|
||||
## 1. Statut de la release
|
||||
|
||||
`0.3.4-pre.001` a figé le design. `0.3.4-pre.002` a matérialisé la fondation physique V002 minimale puis `pre.002-fix.001` a corrigé deux canaris sans toucher au SQL. `0.3.4-pre.003` complète V002 avec les contraintes de domaine, l'index de navigation, la compatibilité de schéma et le checksum final ; `pre.003-fix.001` corrige uniquement l'ordre alphabétique du bloc `const` de `migration.rs` et son gate opérateur complet est PASS. `0.3.4-pre.004` ouvre le mapping PostgreSQL privé et les deux lectures `get` account ; `pre.004-fix.001` corrige uniquement leur conformité au profil Clippy KSP et un canari inutilisé. `pre.005` ajoute l'acquisition atomique, `pre.006` l'observation supplémentaire, `pre.007` la pagination/cursor account et `pre.007-fix.001` réconcilie ses canaris ; le gate opérateur complet du fix est PASS. `pre.008` ouvre les quatre capabilities account sur `PostgresBackend` puis leur dispatch dans `Store`, pour porter l'inventaire RAW à 10/10 sans nouveau SQL ; `pre.008-fix.001` corrige son unique canari mal réconcilié et son gate opérateur complet est PASS. `pre.009` ajoute la preuve PostgreSQL live account et réconcilie l'isolation du live RawTransaction avec le schéma V002 complet ; son gate standard et son live account sur PostgreSQL 17 sont PASS. `pre.010` ferme le hardening et la complétude cross-family sans modifier le runtime ou les migrations ; son gate opérateur complet est PASS. `pre.011` ouvre exclusivement le gate technique final, le replay live ciblé et les graphes Cargo avant toute réconciliation documentaire.
|
||||
`0.3.4-pre.001` a figé le design. `0.3.4-pre.002` a matérialisé la fondation physique V002 minimale puis `pre.002-fix.001` a corrigé deux canaris sans toucher au SQL. `0.3.4-pre.003` complète V002 avec les contraintes de domaine, l'index de navigation, la compatibilité de schéma et le checksum final ; `pre.003-fix.001` corrige uniquement l'ordre alphabétique du bloc `const` de `migration.rs` et son gate opérateur complet est PASS. `0.3.4-pre.004` ouvre le mapping PostgreSQL privé et les deux lectures `get` account ; `pre.004-fix.001` corrige uniquement leur conformité au profil Clippy KSP et un canari inutilisé. `pre.005` ajoute l'acquisition atomique, `pre.006` l'observation supplémentaire, `pre.007` la pagination/cursor account et `pre.007-fix.001` réconcilie ses canaris ; le gate opérateur complet du fix est PASS. `pre.008` ouvre les quatre capabilities account sur `PostgresBackend` puis leur dispatch dans `Store`, pour porter l'inventaire RAW à 10/10 sans nouveau SQL ; `pre.008-fix.001` corrige son unique canari mal réconcilié et son gate opérateur complet est PASS. `pre.009` ajoute la preuve PostgreSQL live account et réconcilie l'isolation du live RawTransaction avec le schéma V002 complet ; son gate standard et son live account sur PostgreSQL 17 sont PASS. `pre.010` ferme le hardening et la complétude cross-family sans modifier le runtime ou les migrations ; son gate opérateur complet est PASS. `pre.011` ouvre exclusivement le gate technique final, le replay live ciblé et les graphes Cargo avant toute réconciliation documentaire ; ses tests `--no-default-features`, le workspace complet, les graphes Cargo et le replay live account sur PostgreSQL 17 sont PASS. `pre.012` ouvre exclusivement la réconciliation documentaire finale sans rouvrir le code fonctionnel.
|
||||
|
||||
Base canonique auditée :
|
||||
|
||||
@@ -17,11 +17,11 @@ workspace.package.version = 0.3.3
|
||||
Version de travail de cette prerelease :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.4-pre.10
|
||||
label = 0.3.4-pre.010
|
||||
workspace.package.version = 0.3.4-pre.12
|
||||
label = 0.3.4-pre.012
|
||||
```
|
||||
|
||||
Décision de scope : `ksp-store-api` reste inchangée. L'inventaire backend/façade est désormais 10/10 ; les tranches restantes portent uniquement sur la preuve PostgreSQL réelle, le hardening cross-family, le gate final et la réconciliation documentaire.
|
||||
Décision de scope : `ksp-store-api` reste inchangée. L'inventaire backend/façade est désormais 10/10 et le couloir technique est fermé ; il ne reste que la réconciliation documentaire courante, puis la préparation de publication et la stabilisation.
|
||||
|
||||
## 2. Invariants hérités et frontières
|
||||
|
||||
@@ -709,17 +709,17 @@ Les canaris façade comparent directement les noms des dix traits RAW implément
|
||||
|
||||
### `pre.011` — Gate technique final
|
||||
|
||||
**Statut : matérialisé ; gate opérateur final à exécuter.**
|
||||
**Statut : réalisé ; gate technique final PASS.**
|
||||
|
||||
Budget cible : **15-20 min**. La tranche n'ajoute aucun code, test fonctionnel, SQL, migration, capability, dépendance runtime, README/USAGE, CHANGELOG/ROADMAP ou prompt suivant. Elle synchronise uniquement la version de prerelease, le plan, la validation et son delta afin de rejouer le gate technique final sur la surface candidate déjà durcie.
|
||||
|
||||
Le gate comprend le workspace complet, `ksp-store-lib` sans feature PostgreSQL, les graphes Cargo façade/backend/features et le replay `postgres_raw_account_live` avec URI dédiée via stdin. Le live account suffit comme preuve finale ciblée : il traverse bootstrap/reopen V002, concurrence/cancellation et coexistence réelle avec `RawTransaction`; les lives foundation et RawTransaction séparés ne sont pas requis par cette tranche.
|
||||
Le replay de clôture confirme `cargo test -p ksp-store-lib --no-default-features`, `cargo test --workspace`, les graphes Cargo façade/backend/features/duplicates et `postgres_raw_account_live` avec URI dédiée via stdin. Le live account passe sur PostgreSQL 17 et traverse bootstrap/reopen V002, concurrence/cancellation et coexistence réelle avec `RawTransaction`; les lives foundation et RawTransaction séparés ne sont pas requis par cette tranche.
|
||||
|
||||
### `pre.012` — Réconciliation documentaire finale
|
||||
|
||||
**Statut : planifié.**
|
||||
**Statut : matérialisé ; gate documentaire opérateur à exécuter.**
|
||||
|
||||
Budget cible : **10-15 min**. Réconcilier les documents durables requis avec la surface effectivement validée, sans rouvrir le code fonctionnel ni préparer la publication.
|
||||
Budget cible : **10-15 min**. Réconcilier les documents durables requis avec la surface effectivement validée, sans rouvrir le code fonctionnel ni préparer la publication. Les README/USAGE de `ksp-store-lib` et `ksp-store-postgres-lib` décrivent désormais la surface RAW 10/10 et les opérations `RawAccountState` ; le plan et la validation enregistrent le PASS technique de `pre.011`. `CHANGELOG.md`, `ROADMAP.md` et le prompt `0.3.5` restent réservés à `pre.013`.
|
||||
|
||||
### `pre.013` — Préparation de publication minimale
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md -->
|
||||
<!-- version: 16 -->
|
||||
<!-- version: 17 -->
|
||||
|
||||
# Validation `0.3.4` — Store/PostgreSQL `RawAccountState` + complétude RAW
|
||||
|
||||
@@ -681,7 +681,7 @@ Le gate opérateur du 2026-08-30 est PASS : audits Rust/Markdown, workspace chec
|
||||
|
||||
## 30. Verdict `pre.011`
|
||||
|
||||
Gate technique final : **matérialisé ; exécution opérateur requise avant `pre.012`**.
|
||||
Gate technique final : **PASS**.
|
||||
|
||||
Cette tranche ne modifie aucun code de production, test fonctionnel, SQL, migration, Config runtime, manifest de crate, dépendance runtime, README/USAGE, CHANGELOG/ROADMAP ou prompt suivant. Elle synchronise uniquement la version workspace et documente le gate final.
|
||||
|
||||
@@ -720,5 +720,47 @@ unset KSP_PG_TEST_URI
|
||||
|
||||
Le live account est la preuve finale ciblée : il couvre bootstrap/reopen V002, bornes u64/data, idempotence/conflits, pagination/cursors, concurrence/cancellation et coexistence `RawTransaction`. Les lives foundation et RawTransaction séparés ne sont pas requis par `pre.011`.
|
||||
|
||||
Tout défaut découvert par ce gate ouvre `pre.011-fix.NNN` avant la réconciliation documentaire finale.
|
||||
Le replay opérateur de clôture confirme :
|
||||
|
||||
```text
|
||||
cargo test -p ksp-store-lib --no-default-features PASS
|
||||
cargo test --workspace PASS
|
||||
cargo tree façade/backend/features/duplicates exécutés
|
||||
postgres_raw_account_live PASS — PostgreSQL 17, 3.00 s
|
||||
```
|
||||
|
||||
Les graphes ne révèlent pas de reverse edge Store ni de dépendance PostgreSQL lorsque la feature façade correspondante est désactivée. Les doublons Cargo observés appartiennent au workspace transverse et ne matérialisent aucune duplication propre à la verticale Store nécessitant un correctif. Le live final lit l'URI dédiée depuis stdin sans l'écho.
|
||||
|
||||
Le couloir technique est donc fermé ; aucun `pre.011-fix.NNN` n'est requis.
|
||||
|
||||
## 31. Verdict `pre.012`
|
||||
|
||||
Réconciliation documentaire finale : **matérialisée ; gate documentaire opérateur à exécuter**.
|
||||
|
||||
Documents durables réconciliés :
|
||||
|
||||
```text
|
||||
crates/ksp-store-lib/README.md
|
||||
crates/ksp-store-lib/USAGE.md
|
||||
crates/ksp-store-postgres-lib/README.md
|
||||
crates/ksp-store-postgres-lib/USAGE.md
|
||||
docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md
|
||||
docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md
|
||||
```
|
||||
|
||||
La documentation décrit maintenant la surface réellement validée : dix capabilities RAW exactes, quatre capabilities `RawAccount*`, acquisition account atomique/idempotente, observation supplémentaire reference-guarded, pagination keyset `(slot,pubkey,state_hash)` avec cursor `KSPA`, séparation stricte avec `RawTransaction` et absence de rétention/destruction account.
|
||||
|
||||
Relus et volontairement inchangés :
|
||||
|
||||
```text
|
||||
README.md racine
|
||||
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||||
docs/architecture/004-COMPONENT_INVENTORY.md
|
||||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
|
||||
ksp-config-lib README/USAGE
|
||||
ksp-store-api — aucun README/USAGE à créer artificiellement
|
||||
```
|
||||
|
||||
`CHANGELOG.md`, `ROADMAP.md` et le prompt de démarrage `0.3.5` restent hors de cette tranche et appartiennent à `pre.013`. Aucun `src/**`, test, Config, schema, migration ou dépendance n'est modifié.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user