188 lines
7.2 KiB
Markdown
188 lines
7.2 KiB
Markdown
<!-- file: deltas/0.3.4/pre.003.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.4-pre.003` — contraintes, index et compatibilité V002
|
|
|
|
## 1. Base
|
|
|
|
Base appliquée :
|
|
|
|
```text
|
|
0.3.4-pre.002-fix.001
|
|
workspace.package.version = 0.3.4-pre.2.fix.1
|
|
```
|
|
|
|
Le gate opérateur fourni le 2026-08-30 est intégralement vert : audits Rust/Markdown, `cargo check --workspace`, Clippy all-targets, suites `ksp-store-api`, `ksp-store-lib`, `ksp-store-postgres-lib`, `ksp-config-lib` et `cargo check -p ksp-store-lib --no-default-features` passent. Le backend PostgreSQL exécute notamment 43 tests unitaires sans échec après `pre.002-fix.001`.
|
|
|
|
## 2. Version
|
|
|
|
Cette tranche contient des changements Rust/SQL fonctionnels :
|
|
|
|
```text
|
|
workspace.package.version = 0.3.4-pre.3
|
|
label = 0.3.4-pre.003
|
|
```
|
|
|
|
## 3. Scope exécuté
|
|
|
|
`pre.003` ferme uniquement le schéma physique V002 et sa compatibilité de migration. Aucun repository account ni dispatch façade n'est ouvert.
|
|
|
|
Inventaire V002 final :
|
|
|
|
```text
|
|
2 tables
|
|
29 contraintes = 2 PK + 1 FK + 26 CHECK
|
|
1 index non unique
|
|
32 resources au total
|
|
```
|
|
|
|
Les 26 `CHECK` ajoutés matérialisent les invariants déjà possédés par `ksp-store-api` :
|
|
|
|
- pubkeys, state hashes, observation keys et source hashes aux largeurs fixes attendues ;
|
|
- transaction signature optionnelle à 64 bytes ;
|
|
- `slot`, `lamports`, `rent_epoch`, `account_slot` et `write_version` dans le domaine `u64` exact, avec stockage `NUMERIC(20,0)` lorsque nécessaire ;
|
|
- `data` account bornée à 16 MiB, vide autorisé ;
|
|
- provenance logique obligatoire/optionnelle bornée à 1..128 octets avec l'alphabet sûr KSP ;
|
|
- origin limité à `backfill`, `import`, `live`, `repair`, `replay` ;
|
|
- timestamps bornés à `MAX_RAW_UNIX_MILLIS` et ordre `observed_at <= received_at` ;
|
|
- source payload size optionnelle bornée à 64 MiB.
|
|
|
|
`is_startup` reste un `BOOLEAN NULL` sans contrainte artificielle supplémentaire.
|
|
|
|
## 4. Index de navigation
|
|
|
|
Un seul index métier est ajouté :
|
|
|
|
```text
|
|
ix_ksp_raw_account_states_slot_pubkey_state_hash
|
|
(slot, pubkey, state_hash)
|
|
```
|
|
|
|
Il est non unique et sans prédicat. Aucun index owner/provider/method/time/status n'est introduit sans query publique qui le justifie.
|
|
|
|
## 5. Checksum V002 final et transition de prerelease
|
|
|
|
Checksum V002 intermédiaire écrit par `pre.002` :
|
|
|
|
```text
|
|
30ac87496f1bb3805d816660891d7eab2127c599a636eb40c17ade5926311f55
|
|
```
|
|
|
|
Checksum V002 final calculé sur les 32 resources ordonnées :
|
|
|
|
```text
|
|
ff21605ed45f7ab4c0f92bbb692700b4118a9488b04d50a31d259ac59bdb550e
|
|
```
|
|
|
|
V000 et V001 restent byte-inchangées et conservent leurs checksums :
|
|
|
|
```text
|
|
V000 = d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
|
|
V001 = 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51
|
|
```
|
|
|
|
Le moteur accepte le checksum V002 intermédiaire **uniquement** avec `schema_update=update_if_needed`. Dans ce cas, sous la transaction de migration existante :
|
|
|
|
1. l'historique reconnaît uniquement le checksum provisoire explicitement connu ;
|
|
2. les resources V002 manquantes sont matérialisées et réinspectées ;
|
|
3. la compatibilité externe V002 est vérifiée ;
|
|
4. l'entrée V002 de `ksp_store_schema_migrations` est remplacée par le checksum final avec un `UPDATE` conditionné par version, nom et ancien checksum ;
|
|
5. le commit publie ensemble schéma et historique final.
|
|
|
|
Avec `schema_update=disabled`, le checksum provisoire reste un `MigrationMismatch`. Tout checksum V002 inconnu reste rejeté même avec update activé.
|
|
|
|
## 6. Schema compatibility V002
|
|
|
|
La vérification externe générique couvre désormais V001 et V002 avec leurs inventaires propres. Pour les deux tables account, elle conserve les mêmes principes que V001 :
|
|
|
|
- colonnes attendues et types physiques compatibles ;
|
|
- contraintes KSP attendues reconnues par nom/définition ;
|
|
- extension externe bloquante rejetée ;
|
|
- unique index externe non adossé à une contrainte rejeté ;
|
|
- triggers/rules externes rejetés.
|
|
|
|
Le probe d'adoption inclut désormais les deux tables V002 afin qu'un schéma KSP account existant sans metadata de migration ne soit pas considéré comme vide.
|
|
|
|
Le contrat d'index interne supporte explicitement les deux formes possédées : V001 avec prédicat `retention_state <> 'purged'`, V002 sans prédicat.
|
|
|
|
## 7. Canaries et tests modifiés
|
|
|
|
Les canaries backend prouvent désormais :
|
|
|
|
- 32 resources V002, ordonnées par tables/constraints/index ;
|
|
- inventaire exact 2/29/1 ;
|
|
- checksum final exact et checksums V000/V001 stables ;
|
|
- acceptation conditionnelle du checksum provisoire et rejet des historiques arbitraires ;
|
|
- bornes physiques majeures et absence de narrowing `u64` ;
|
|
- index unique de navigation non filtré/non unique ;
|
|
- compatibilité externe V002 ;
|
|
- absence persistante de `src/raw_account.rs`, d'implémentation `RawAccount*` et de dispatch runtime account.
|
|
|
|
## 8. Scope négatif préservé
|
|
|
|
Cette tranche n'ajoute pas :
|
|
|
|
```text
|
|
ksp-store-api change
|
|
raw_account repository module
|
|
RawAccount* implementation on PostgresBackend
|
|
RawAccount* implementation on Store
|
|
Store account dispatch
|
|
account retention/archive/purge
|
|
owner/provider/time/status indexes
|
|
worker/job/backfill policy
|
|
Transport -> Store coupling
|
|
new backend
|
|
```
|
|
|
|
## 9. Documentation
|
|
|
|
`docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md` conserve le forecast souple sous forme de sous-paragraphes `### pre.NNN` / `#### pre.NNN-fix.MMM`. `pre.002-fix.001` y passe au statut gate opérateur complet PASS et `pre.003` au statut réalisé / gate opérateur à rejouer.
|
|
|
|
`docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md` enregistre le gate vert de la base, l'inventaire V002 final, les checksums et la stratégie de transition de prerelease.
|
|
|
|
## 10. Validation exécutée dans l'environnement d'assemblage
|
|
|
|
```text
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
=> General Rust rule audit: clean
|
|
=> Rust export completeness audit: 0 candidate(s)
|
|
=> KSP workspace Rust rule audit: clean
|
|
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.4
|
|
=> Markdown table audit: clean (239 table(s), 138 file(s))
|
|
```
|
|
|
|
Le calcul indépendant de checksum sur les bytes des resources V002 donne :
|
|
|
|
```text
|
|
ff21605ed45f7ab4c0f92bbb692700b4118a9488b04d50a31d259ac59bdb550e
|
|
```
|
|
|
|
`cargo`, `clippy` et les tests Rust ne sont pas disponibles dans l'environnement d'assemblage. Aucun résultat Cargo de `pre.003` n'est donc revendiqué ici.
|
|
|
|
## 11. Gate opérateur demandé
|
|
|
|
```text
|
|
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
|
|
```
|
|
|
|
Les preuves PostgreSQL live account restent hors de cette tranche et sont prévues plus tard dans le forecast.
|
|
|
|
## 12. Fichiers
|
|
|
|
Le delta contient uniquement `Cargo.toml`, les fichiers Rust/tests/schema réellement modifiés, les nouvelles resources V002, les deux documents de suivi modifiés et ce fichier `pre.003.md`. Aucun snapshot complet, aucune archive historique et aucun artefact de build ne sont inclus.
|
|
|
|
## 13. Verdict
|
|
|
|
`0.3.4-pre.003` : **READY FOR OPERATOR GATE**.
|