v0.3.4-pre.004
This commit is contained in:
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# 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, toujours sans repository account ni dispatch façade ; `pre.003-fix.001` corrige ensuite uniquement l'ordre alphabétique du bloc `const` de `migration.rs` révélé par `RUST-FMT-104`.
|
||||
`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 maintenant le mapping PostgreSQL privé et les deux lectures `get` account, sans write, pagination ni implémentation de capability.
|
||||
|
||||
Base canonique auditée :
|
||||
|
||||
@@ -17,8 +17,8 @@ workspace.package.version = 0.3.3
|
||||
Version de travail de cette prerelease :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.4-pre.3.fix.1
|
||||
label = 0.3.4-pre.003-fix.001
|
||||
workspace.package.version = 0.3.4-pre.4
|
||||
label = 0.3.4-pre.004
|
||||
```
|
||||
|
||||
Décision de scope : `ksp-store-api` reste inchangée. L'audit n'a révélé aucun gap backend-agnostic bloquant ; la difficulté restante est exclusivement l'implémentation physique PostgreSQL et son dispatch par la façade.
|
||||
@@ -585,7 +585,7 @@ Aucune ressource SQL, migration, table, contrainte, index, surface runtime ou ca
|
||||
|
||||
### `pre.003` — Contraintes, index et schema compatibility V002
|
||||
|
||||
**Statut : réalisé ; corrigé par `pre.003-fix.001`, gate opérateur complet du fix à rejouer.**
|
||||
**Statut : réalisé ; corrigé par `pre.003-fix.001`, gate opérateur complet PASS.**
|
||||
|
||||
Budget cible : **15-20 min**. V002 est complétée à **32 resources** : deux tables, 29 contraintes (PK/FK incluses) et un index non unique `(slot, pubkey, state_hash)` sans prédicat. Les contraintes matérialisent les bornes backend-agnostic existantes : fixed-width 32/64 bytes, domaines `u64` via `NUMERIC(20,0)`, data `<= 16 MiB`, codes de provenance 1..128 octets/alphabet sûr, timestamps bornés, ordre `observed_at <= received_at` et source payload `<= 64 MiB`.
|
||||
|
||||
@@ -597,7 +597,7 @@ Gate de base `pre.002-fix.001` fourni le 2026-08-30 : audits Rust/Markdown, `car
|
||||
|
||||
#### `pre.003-fix.001` — ordre alphabétique du bloc `const` migration
|
||||
|
||||
**Statut : réalisé ; gate opérateur complet du fix à rejouer.**
|
||||
**Statut : réalisé ; gate opérateur complet PASS.**
|
||||
|
||||
Le gate opérateur de `pre.003` confirme `cargo check --workspace`, Clippy all-targets, `ksp-store-api`, `ksp-store-lib`, `ksp-store-postgres-lib` (45 tests), `ksp-config-lib` et `ksp-store-lib --no-default-features`, mais l'audit Rust détecte une unique violation `RUST-FMT-104` dans `src/migration.rs`. Le correctif déplace seulement `HISTORY_LOAD_SQL` avant `HISTORY_UPDATE_CHECKSUM_SQL` afin de restaurer l'ordre alphabétique du bloc homogène de constantes.
|
||||
|
||||
@@ -605,9 +605,15 @@ Aucune valeur de constante, requête SQL, ressource V002, checksum, logique de m
|
||||
|
||||
### `pre.004` — Mapping privé et lectures `get`
|
||||
|
||||
**Statut : planifié.**
|
||||
**Statut : réalisé ; gate opérateur complet à rejouer.**
|
||||
|
||||
Budget cible : **15-20 min**. Implémenter le mapping privé state/observation, les lectures `get` et les hostile-row guards. Aucun write account dans cette tranche.
|
||||
Budget cible : **15-20 min**. Le module privé `src/raw_account.rs` possède désormais les deux SELECT de lecture et les codecs physiques de `RawAccountState` / `RawAccountObservation`. `PostgresBackend` expose uniquement `get_raw_account_state` et `get_raw_account_observation` avec des modèles `ksp-store-api` ; aucun `tokio_postgres::Row`, SQL ou type physique ne traverse le bridge.
|
||||
|
||||
Le mapping revalide les invariants même si PostgreSQL devait contenir une ligne hostile : `pubkey`/owner/hash/key en largeur exacte, signature optionnelle à 64 bytes, `slot`/`lamports`/`rent_epoch`/`write_version` via `NUMERIC(20,0)::text -> u64`, timestamps et source payload size bornés, provenance reconstruite via les constructeurs API et ordre `observed_at <= received_at`. Les bytes account sont admis via `RawAccountState::try_new`, donc data vide reste valide et `> 16 MiB` devient `DataInvalid`.
|
||||
|
||||
Le `RawAccountStateReference` reçu par `get` est vérifié contre le réseau mono-backend **avant `pool.get()`**. `RawObservationKey` ne porte pas de réseau ; le réseau de la référence account reconstruite provient exclusivement du backend déjà lié par `ksp_store_identity`.
|
||||
|
||||
La tranche reste strictement read-only : aucun `INSERT`, `UPDATE`, `DELETE`, `ON CONFLICT`, `FOR UPDATE`, cursor ou `list_raw_account_states`. Les quatre `impl RawAccount* for PostgresBackend` restent interdits jusqu'à `pre.008`; `pre.005` et `pre.006` possèdent encore les écritures.
|
||||
|
||||
### `pre.005` — Acquisition atomique et idempotence
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Validation `0.3.4` — Store/PostgreSQL `RawAccountState` + complétude RAW
|
||||
|
||||
## 1. Portée
|
||||
|
||||
Cette matrice est ouverte par `0.3.4-pre.001`. `0.3.4-pre.002` matérialise la fondation V002 minimale et `pre.002-fix.001` corrige deux canaris sans modifier le SQL ; son gate opérateur complet est PASS. `0.3.4-pre.003` complète les contraintes de domaine, l'index de navigation, la compatibilité externe et le checksum V002 final ; `pre.003-fix.001` corrige uniquement l'ordre alphabétique du bloc `const` de migration. Les repositories et les quatre capabilities account restent volontairement pending.
|
||||
Cette matrice est ouverte par `0.3.4-pre.001`. `0.3.4-pre.002` matérialise la fondation V002 minimale et `pre.002-fix.001` corrige deux canaris sans modifier le SQL ; son gate opérateur complet est PASS. `0.3.4-pre.003` complète les contraintes de domaine, l'index de navigation, la compatibilité externe et le checksum V002 final ; `pre.003-fix.001` corrige uniquement l'ordre alphabétique du bloc `const` et son gate opérateur complet est PASS. `pre.004` matérialise le mapping privé et les deux lectures `get` account. Les writes, la pagination, le dispatch Store et les quatre implémentations de capabilities account restent volontairement pending.
|
||||
|
||||
Base :
|
||||
|
||||
@@ -143,12 +143,12 @@ observation_key family-local unique
|
||||
| PK state | `(pubkey,slot,state_hash)` | PASS pre.002 |
|
||||
| PK observation | `(observation_key)` | PASS pre.002 |
|
||||
| FK observation -> state | `(account_pubkey,account_slot,account_state_hash)` -> state composite PK | PASS pre.002 |
|
||||
| contraintes domaine/fixed-width | non encore ajoutées | PENDING pre.003 |
|
||||
| index métier | `(slot,pubkey,state_hash)` non encore ajouté | PENDING pre.003 |
|
||||
| contraintes domaine/fixed-width | 26 CHECK + PK/FK, bornes API exactes | PASS pre.003 |
|
||||
| index métier | `(slot,pubkey,state_hash)` non unique / non filtré | PASS pre.003 |
|
||||
| index owner/provider/time/status | aucun prévu | PASS negative scope |
|
||||
| archive/tombstone account | aucune | PASS negative scope |
|
||||
| V002 checksum intermédiaire | `30ac8749…26311f55` sur les 5 resources pre.002 | PROVISIONAL |
|
||||
| V002 checksum final | après contraintes/index de pre.003 | PENDING pre.003 |
|
||||
| V002 checksum final | `ff21605e…bdb550e` sur 32 resources | PASS pre.003 |
|
||||
|
||||
## 8. Idempotence et concurrence
|
||||
|
||||
@@ -273,8 +273,8 @@ Le test live account devra être opt-in/ignored, URI stdin, sans environnement n
|
||||
|---------|-------------------------------------------------------------------|---------|
|
||||
| pre.001 | audit, kbot3, threat model, V002 design, sizing, plan/validation | DONE |
|
||||
| pre.002 | V002 registry + deux tables + PK/FK de base, sans repository | PASS |
|
||||
| pre.003 | contraintes complètes, index, schema compatibility, checksum V002 | FIXED |
|
||||
| pre.004 | mapping privé state/observation + get reads + hostile rows | PLANNED |
|
||||
| pre.003 | contraintes complètes, index, schema compatibility, checksum V002 | PASS |
|
||||
| pre.004 | mapping privé state/observation + get reads + hostile rows | READY |
|
||||
| pre.005 | acquisition atomique state+observation + idempotence/conflict | PLANNED |
|
||||
| pre.006 | observation supplémentaire + races/cancellation unitaires | PLANNED |
|
||||
| pre.007 | list RawAccountStateQuery + keyset cursor V1 account | PLANNED |
|
||||
@@ -333,7 +333,7 @@ Gate opérateur du 2026-08-30 : audits Rust/Markdown, `cargo check --workspace`,
|
||||
|
||||
Ces deux défauts appartiennent strictement au couloir `pre.002` et sont corrigés par `pre.002-fix.001`. Ils ne remettent en cause ni les cinq resources V002 ni leur checksum.
|
||||
|
||||
Contraintes complètes/index/schema compatibility/checksum final : **PENDING `pre.003`**. Repository et capabilities account : **PENDING `pre.004+`**.
|
||||
Contraintes complètes/index/schema compatibility/checksum final : **PASS `pre.003`**. Mapping/lectures account : **PENDING `pre.004`** à ce verdict historique ; writes/pagination/capabilities restent `pre.005+`.
|
||||
|
||||
## 18. Correctif `pre.002-fix.001`
|
||||
|
||||
@@ -395,4 +395,42 @@ Invariants du fix :
|
||||
- aucune modification de schéma, repository, dispatch ou capability ;
|
||||
- `workspace.package.version = 0.3.4-pre.3.fix.1` conformément à `VER-ID-007/010`.
|
||||
|
||||
L'audit Rust du fix doit être **PASS** avant `pre.004`. Le gate Cargo complet du fix reste à rejouer par l'opérateur.
|
||||
Gate opérateur de `pre.003-fix.001` du 2026-08-30 : **PASS complet** — audits Rust/Markdown, `cargo check --workspace`, Clippy all-targets, Store API, Store façade, backend PostgreSQL (45 tests), Config et `--no-default-features` sont verts.
|
||||
|
||||
## 21. Verdict `pre.004`
|
||||
|
||||
Mapping PostgreSQL privé account : **PASS statique ; gate Cargo opérateur à rejouer**.
|
||||
|
||||
Surface matérialisée :
|
||||
|
||||
```text
|
||||
src/raw_account.rs privé
|
||||
PostgresBackend::get_raw_account_state public bridge backend
|
||||
PostgresBackend::get_raw_account_observation public bridge backend
|
||||
RawAccount* trait impl 0/4 — volontairement fermé
|
||||
write SQL account absent
|
||||
pagination/cursor account absent
|
||||
migrations V000/V001/V002 inchangées
|
||||
```
|
||||
|
||||
Le mapping state couvre `slot`, `lamports` et `rent_epoch` sur tout le domaine `u64` via les projections `::text`, les largeurs exactes 32 bytes de pubkey/owner/state hash, le booléen `executable` et les bytes account complets. `RawAccountState::try_new` fournit la dernière admission backend-agnostic et transforme un payload > 16 MiB en `DataInvalid`; les comptes à data vide restent valides.
|
||||
|
||||
Le mapping observation reconstruit l'identité account, toute la provenance commune et les metadata optionnelles `is_startup`, `transaction_signature` et `write_version`. `write_version` conserve tout le domaine `u64` via `NUMERIC(20,0)::text`; une signature présente doit faire exactement 64 bytes. L'absence de metadata optionnelle reste `None`, sans valeur inventée.
|
||||
|
||||
Hostile-row guards déterministes couvrent notamment : largeur pubkey/hash/signature invalide, décimal négatif ou > `u64::MAX`, provenance/origin invalide, ordre temporel impossible et data oversized. Les erreurs restent `DataInvalid`/`ReadFailed`/`WrongNetwork` avec phases statiques et sans écho de valeur hostile.
|
||||
|
||||
Le garde réseau de `get_raw_account_state` est exécuté avant acquisition d'une connexion. `get_raw_account_observation` reçoit seulement un `RawObservationKey`; la référence reconstruite utilise donc le réseau mono-backend déjà validé à l'ouverture, comme prévu par le contrat.
|
||||
|
||||
Les canaris de scope prouvent encore l'absence de :
|
||||
|
||||
```text
|
||||
INSERT / UPDATE / DELETE account
|
||||
ON CONFLICT / FOR UPDATE account
|
||||
list_raw_account_states / cursor KSPA
|
||||
impl RawAccountStateRead/Write for PostgresBackend
|
||||
impl RawAccountObservationRead/Write for PostgresBackend
|
||||
Store dispatch account
|
||||
```
|
||||
|
||||
Validations exécutées dans l'environnement d'assemblage : audit Rust général/export/workspace **PASS**. Le gate opérateur complet doit rejouer `cargo fmt`, audits, check, Clippy et suites ciblées après application du delta.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user