v0.3.3-pre.004
This commit is contained in:
323
deltas/0.3.3/pre.004.md
Normal file
323
deltas/0.3.3/pre.004.md
Normal file
@@ -0,0 +1,323 @@
|
||||
<!-- file: deltas/0.3.3/pre.004.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.3-pre.004` — mapping PostgreSQL privé et lectures RawTransaction
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
```text
|
||||
0.3.3-pre.3.fix.3
|
||||
```
|
||||
|
||||
Le gate opérateur fourni pour `pre.003-fix.003` est entièrement vert :
|
||||
|
||||
```text
|
||||
cargo fmt --all PASS
|
||||
audit Rust général / exports / workspace PASS
|
||||
audit Markdown PASS — 214 tables / 136 files
|
||||
cargo check --workspace PASS
|
||||
cargo clippy --workspace --all-targets PASS
|
||||
cargo test -p ksp-store-api PASS
|
||||
cargo test -p ksp-store-lib PASS
|
||||
cargo test -p ksp-store-postgres-lib PASS — 19 unit tests + canaris, live ignored
|
||||
cargo test -p ksp-config-lib PASS — 128 unit tests + ownership/public API
|
||||
cargo check -p ksp-store-lib --no-default-features PASS
|
||||
```
|
||||
|
||||
La V001 split, son contrat catalogue et les politiques `schema_autocreate/schema_autoupdate` sont donc considérés acquis.
|
||||
|
||||
## 2. Objectif
|
||||
|
||||
Implémenter la tranche lecture de la vertical slice PostgreSQL `RawTransaction` sans ouvrir encore les écritures ni la pagination :
|
||||
|
||||
```text
|
||||
mapping SQL privé
|
||||
get_raw_transaction
|
||||
get_raw_transaction_observation
|
||||
get_raw_transaction_retention_state
|
||||
get_raw_transaction_tombstone
|
||||
```
|
||||
|
||||
Les méthodes du backend retournent uniquement des modèles `ksp-store-api`. Aucun `tokio_postgres::Row`, SQL, SQLSTATE ou bind ne traverse le bridge public.
|
||||
|
||||
## 3. Version
|
||||
|
||||
Le workspace passe à :
|
||||
|
||||
```text
|
||||
0.3.3-pre.4
|
||||
```
|
||||
|
||||
## 4. Module physique privé
|
||||
|
||||
Nouveau module :
|
||||
|
||||
```text
|
||||
crates/ksp-store-postgres-lib/src/raw_transaction.rs
|
||||
```
|
||||
|
||||
Il possède les SELECT et les codecs physiques de cette tranche. `runtime.rs` ne contient aucun SQL métier et délègue les quatre lectures au module privé.
|
||||
|
||||
La tranche reste strictement read-only :
|
||||
|
||||
```text
|
||||
INSERT INTO absent
|
||||
UPDATE absent
|
||||
DELETE FROM absent
|
||||
```
|
||||
|
||||
Les écritures canonique/observation restent `pre.005`; `list_raw_transactions` et le cursor restent `pre.006`.
|
||||
|
||||
## 5. Conversion physique exacte
|
||||
|
||||
Le mapping respecte les contrats `ksp-store-api` sans narrowing :
|
||||
|
||||
```text
|
||||
slot NUMERIC(20,0) -> PostgreSQL ::text -> parse u64
|
||||
format_version BIGINT -> u32::try_from
|
||||
block/observed/received BIGINT -> u64::try_from -> RawTimestamp
|
||||
source payload size BIGINT -> u64::try_from + borne API
|
||||
signature -> BYTEA exactement 64 bytes
|
||||
hash/key -> BYTEA exactement 32 bytes
|
||||
format/provenance codes -> constructeurs API fallibles
|
||||
```
|
||||
|
||||
Le chemin `slot` couvre explicitement :
|
||||
|
||||
```text
|
||||
0
|
||||
i64::MAX
|
||||
i64::MAX + 1
|
||||
u64::MAX
|
||||
```
|
||||
|
||||
Aucune dépendance décimale supplémentaire n'est introduite.
|
||||
|
||||
## 6. `get_raw_transaction`
|
||||
|
||||
La requête lit la ligne canonique avec `LEFT JOIN` du payload archive.
|
||||
|
||||
Décodage :
|
||||
|
||||
```text
|
||||
Full
|
||||
payload chaud obligatoire
|
||||
payload archive interdit
|
||||
-> Some(RawTransaction)
|
||||
|
||||
Archived
|
||||
payload chaud absent
|
||||
payload archive obligatoire
|
||||
-> Some(RawTransaction)
|
||||
|
||||
Purged
|
||||
payload chaud absent
|
||||
payload archive absent
|
||||
block_time absent
|
||||
-> None
|
||||
```
|
||||
|
||||
Toute incohérence de forme, entier hors domaine, code invalide, signature/hash mal dimensionné ou payload incompatible produit `DataInvalid` sans conserver la valeur hostile.
|
||||
|
||||
## 7. Observation
|
||||
|
||||
`get_raw_transaction_observation` reconstruit :
|
||||
|
||||
```text
|
||||
observation_key
|
||||
transaction signature
|
||||
provider
|
||||
protocol
|
||||
acquisition_method
|
||||
origin
|
||||
received_at
|
||||
capture_session_id optionnel
|
||||
commitment optionnel
|
||||
endpoint_id optionnel
|
||||
filter_id optionnel
|
||||
observed_at optionnel
|
||||
source_payload_hash optionnel
|
||||
source_payload_size_bytes optionnel
|
||||
```
|
||||
|
||||
`RawObservationKey` ne porte pas de réseau ; le `RawTransactionReference` reconstruit utilise donc exclusivement le réseau mono-backend déjà vérifié à l'ouverture.
|
||||
|
||||
L'ordre temporel `observed_at <= received_at` est revalidé par le constructeur API.
|
||||
|
||||
## 8. Rétention et tombstone
|
||||
|
||||
`get_raw_transaction_retention_state` mappe uniquement les états physiques supportés par V001 :
|
||||
|
||||
```text
|
||||
full
|
||||
archived
|
||||
purged
|
||||
```
|
||||
|
||||
Une valeur inconnue ou `compacted` stockée physiquement est une corruption `DataInvalid`; `Compacted` n'a toujours aucune représentation PostgreSQL prétendue.
|
||||
|
||||
`get_raw_transaction_tombstone` retourne `Some` uniquement pour `Purged`, vérifie également que `block_time` est absent, puis reconstruit exactement :
|
||||
|
||||
```text
|
||||
network + signature
|
||||
slot
|
||||
format_id
|
||||
format_version
|
||||
content_hash
|
||||
```
|
||||
|
||||
Pour `Full` ou `Archived`, le résultat est `None`.
|
||||
|
||||
## 9. Réseau pré-I/O
|
||||
|
||||
Les trois lectures portant un `RawTransactionReference` passent par un garde privé commun avant `pool.get()` :
|
||||
|
||||
```text
|
||||
reference.network == backend.network -> continuer
|
||||
sinon -> WrongNetwork
|
||||
```
|
||||
|
||||
Le mauvais réseau ne consomme donc aucune connexion PostgreSQL et ne dépend d'aucun SQL.
|
||||
|
||||
## 10. Erreurs backend
|
||||
|
||||
`PostgresBackendErrorKind` ajoute :
|
||||
|
||||
```text
|
||||
DataInvalid
|
||||
ReadFailed
|
||||
WrongNetwork
|
||||
```
|
||||
|
||||
Classification :
|
||||
|
||||
```text
|
||||
pool wait/connect -> kinds existants PoolTimeout/ConnectFailed
|
||||
SELECT/driver read -> ReadFailed
|
||||
row/cardinality/model -> DataInvalid
|
||||
reference mauvais réseau -> WrongNetwork
|
||||
```
|
||||
|
||||
`PostgresBackendError` reste composé uniquement de :
|
||||
|
||||
```text
|
||||
kind
|
||||
phase &'static str
|
||||
```
|
||||
|
||||
Aucune erreur externe n'est retenue ni rendue.
|
||||
|
||||
## 11. Surface backend
|
||||
|
||||
`PostgresBackend` expose désormais :
|
||||
|
||||
```text
|
||||
get_raw_transaction
|
||||
get_raw_transaction_observation
|
||||
get_raw_transaction_retention_state
|
||||
get_raw_transaction_tombstone
|
||||
```
|
||||
|
||||
Ces méthodes ne constituent pas encore les implémentations finales des traits `RawTransaction*` : `RawTransactionRead` exige également `list_raw_transactions`, réservé à `pre.006`. Les six traits seront complets avant leur dispatch par `ksp-store-lib` en `pre.008`.
|
||||
|
||||
## 12. Tests déterministes
|
||||
|
||||
Le nouveau miroir `unit_tests/raw_transaction.rs` couvre notamment :
|
||||
|
||||
```text
|
||||
Full u64::MAX
|
||||
Archived u64::MAX
|
||||
Purged -> None
|
||||
résidu payload/block_time sur Purged -> DataInvalid
|
||||
provenance complète/optionnelle
|
||||
source payload max
|
||||
slot > u64::MAX -> DataInvalid
|
||||
hash mal dimensionné -> DataInvalid
|
||||
origin hostile -> DataInvalid sans écho
|
||||
états Full/Archived/Purged
|
||||
Compacted physique -> DataInvalid
|
||||
tombstone u64::MAX/u32::MAX
|
||||
wrong-network pré-I/O
|
||||
```
|
||||
|
||||
Les canaris d'intégration figent également :
|
||||
|
||||
```text
|
||||
module SQL privé
|
||||
aucun write SQL en pre.004
|
||||
aucune dépendance nouvelle
|
||||
surface publique sans types PostgreSQL
|
||||
nouveaux error kinds sûrs
|
||||
```
|
||||
|
||||
## 13. Migrations
|
||||
|
||||
Aucune ressource de migration n'est modifiée.
|
||||
|
||||
Les checksums restent :
|
||||
|
||||
```text
|
||||
V000 d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
|
||||
V001 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51
|
||||
```
|
||||
|
||||
## 14. Fichiers ajoutés
|
||||
|
||||
```text
|
||||
crates/ksp-store-postgres-lib/src/raw_transaction.rs
|
||||
crates/ksp-store-postgres-lib/unit_tests/raw_transaction.rs
|
||||
deltas/0.3.3/pre.004.md
|
||||
```
|
||||
|
||||
## 15. Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-store-postgres-lib/README.md
|
||||
crates/ksp-store-postgres-lib/USAGE.md
|
||||
crates/ksp-store-postgres-lib/src/error.rs
|
||||
crates/ksp-store-postgres-lib/src/lib.rs
|
||||
crates/ksp-store-postgres-lib/src/runtime.rs
|
||||
crates/ksp-store-postgres-lib/tests/dependency_boundary.rs
|
||||
crates/ksp-store-postgres-lib/tests/hardening_completeness.rs
|
||||
crates/ksp-store-postgres-lib/tests/public_api.rs
|
||||
docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md
|
||||
docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md
|
||||
```
|
||||
|
||||
## 16. Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## 17. Hors scope confirmé
|
||||
|
||||
Aucun changement n'est apporté à :
|
||||
|
||||
```text
|
||||
ksp-store-api contrats
|
||||
ksp-store-lib dispatch métier
|
||||
écriture RawTransaction
|
||||
écriture observation
|
||||
pagination/cursor
|
||||
transition rétention
|
||||
RawAccountState
|
||||
worker/job/app
|
||||
migration SQL V000/V001
|
||||
```
|
||||
|
||||
## 18. Gate opérateur
|
||||
|
||||
```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.3
|
||||
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
|
||||
```
|
||||
|
||||
La tranche n'est validée qu'après gate opérateur entièrement vert.
|
||||
Reference in New Issue
Block a user