v0.3.3-pre.001
This commit is contained in:
283
deltas/0.3.3/pre.001.md
Normal file
283
deltas/0.3.3/pre.001.md
Normal file
@@ -0,0 +1,283 @@
|
||||
<!-- file: deltas/0.3.3/pre.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.3-pre.001` — audit et physical design RawTransaction PostgreSQL
|
||||
|
||||
## 1. Objet
|
||||
|
||||
Ouverture de :
|
||||
|
||||
```text
|
||||
0.3.3 — Store/PostgreSQL RawTransaction vertical slice
|
||||
```
|
||||
|
||||
Cette tranche reste volontairement documentaire/conception : elle fixe l'audit, le threat model, le design physique V001 et le séquencement avant toute migration ou persistence métier.
|
||||
|
||||
## 2. Base
|
||||
|
||||
Base canonique :
|
||||
|
||||
```text
|
||||
v0.3.2
|
||||
```
|
||||
|
||||
Le gate opérateur fourni pour `0.3.2` est propre : audits Rust/Markdown, workspace check, Clippy, tests Store/API/PostgreSQL foundation/Config et `ksp-store-lib --no-default-features` passent ; les tests live restent opt-in/ignored conformément à la fondation.
|
||||
|
||||
## 3. Version
|
||||
|
||||
Version workspace après overlay :
|
||||
|
||||
```text
|
||||
0.3.3-pre.1
|
||||
```
|
||||
|
||||
Label de livraison :
|
||||
|
||||
```text
|
||||
0.3.3-pre.001
|
||||
```
|
||||
|
||||
## 4. Fichiers ajoutés
|
||||
|
||||
```text
|
||||
docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md
|
||||
docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md
|
||||
deltas/0.3.3/pre.001.md
|
||||
```
|
||||
|
||||
## 5. Fichier modifié
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
```
|
||||
|
||||
Modifications :
|
||||
|
||||
```text
|
||||
workspace.package.version : 0.3.2 -> 0.3.3-pre.1
|
||||
file header version : 347 -> 348
|
||||
```
|
||||
|
||||
## 6. Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## 7. Audit effectué
|
||||
|
||||
Ont été relus avant design :
|
||||
|
||||
- règles générales/KSP/Rust/dépendances/docs/file contracts/version workflow/prompt structure ;
|
||||
- architectures Layers/Dependencies/Store/API/Config concernées ;
|
||||
- plan/validation `0.3.1` ;
|
||||
- source/tests complets `ksp-store-api` ;
|
||||
- plan/validation `0.3.2` ;
|
||||
- source/tests complets `ksp-store-lib` et `ksp-store-postgres-lib` ;
|
||||
- surface Config `std.store` ;
|
||||
- archive historique kbot3 ciblée demandée par le prompt ;
|
||||
- documentation PostgreSQL/tokio-postgres nécessaire aux choix numériques et de concurrence.
|
||||
|
||||
## 8. Décisions majeures
|
||||
|
||||
### 8.1 `slot: u64`
|
||||
|
||||
`BIGINT` est rejeté pour `slot` car il narrowe le domaine API. V001 utilisera :
|
||||
|
||||
```text
|
||||
NUMERIC(20,0)
|
||||
```
|
||||
|
||||
avec conversion décimale fallible et tests jusqu'à `u64::MAX`.
|
||||
|
||||
### 8.2 Réseau physique
|
||||
|
||||
V001 introduira :
|
||||
|
||||
```text
|
||||
ksp_store_identity
|
||||
```
|
||||
|
||||
Une base V001 est mono-réseau. Le binding est créé/validé sous le bootstrap lock afin qu'une URI pointant vers un autre réseau échoue avant exposition d'un backend prêt.
|
||||
|
||||
### 8.3 Schéma RAW minimal
|
||||
|
||||
Tables décidées :
|
||||
|
||||
```text
|
||||
ksp_store_identity
|
||||
ksp_raw_transactions
|
||||
ksp_raw_transaction_observations
|
||||
ksp_raw_transaction_archive_payloads
|
||||
```
|
||||
|
||||
Index métier additionnel unique :
|
||||
|
||||
```text
|
||||
(slot, signature) WHERE retention_state <> 'purged'
|
||||
```
|
||||
|
||||
Aucun index provider/status/created_at/hash n'est ajouté sans requête correspondante.
|
||||
|
||||
### 8.4 Atomicité/idempotence
|
||||
|
||||
Le repository n'utilisera aucun `has_*` préalable. La stratégie est :
|
||||
|
||||
```text
|
||||
INSERT ... ON CONFLICT DO NOTHING RETURNING
|
||||
-> si conflit : SELECT ... FOR UPDATE
|
||||
-> comparaison exacte du contenu
|
||||
-> AlreadyPresent ou ERROR_CODE_RAW_CONFLICT
|
||||
```
|
||||
|
||||
Le canonique et son observation d'acquisition sont dans la même transaction PostgreSQL.
|
||||
|
||||
### 8.5 Pagination
|
||||
|
||||
Ordre total :
|
||||
|
||||
```text
|
||||
(slot, signature)
|
||||
```
|
||||
|
||||
Cursor backend-private V1 fixe 109 octets, lié par SHA-256 au réseau, à la direction, au slot range et à la dernière clé. Aucun cap métier arbitraire n'est ajouté.
|
||||
|
||||
### 8.6 Rétention
|
||||
|
||||
`Full`, `Archived` et `Purged` sont représentables honnêtement par le backend `0.3.3` avec une relation archive séparée du hot path.
|
||||
|
||||
`Compacted` n'est pas assimilé au TOAST PostgreSQL et n'est pas simulé. Le plan `0.3.1` le qualifiait déjà d'optionnel ; aucun changement `ksp-store-api` n'est donc justifié. Les transitions qui l'impliquent seront rejetées avant I/O par `store.postgres_retention_compaction_unsupported`.
|
||||
|
||||
## 9. Audit kbot3
|
||||
|
||||
Classification effectuée :
|
||||
|
||||
- **REPRENDRE** : unicités, FK, keyset/index slot conceptuels ;
|
||||
- **REDESSINER** : fixed bytes, payload opaque, u64 exact, atomicité, conflit réel, réseau, retention compare-and-transition ;
|
||||
- **REPORTER** : indexes provider/status/time, processing/replay, batches, apps, AccountState ;
|
||||
- **REJETER** : sqlx, `has_*`, JSONB canonique, narrowing i64/i32, FK `SET NULL`, error text SQL, caps 500/1000, processing_state RAW.
|
||||
|
||||
Aucun code historique n'est copié.
|
||||
|
||||
## 10. Threat model couvert
|
||||
|
||||
Le plan couvre explicitement :
|
||||
|
||||
- mauvaise URI/réseau ;
|
||||
- DB bytes malformés ;
|
||||
- overflow u64 ;
|
||||
- observation orpheline ;
|
||||
- inserts identiques/divergents concurrents ;
|
||||
- collision observation ;
|
||||
- cursor hostile/replay ;
|
||||
- ambiguïté pagination ;
|
||||
- retention race ;
|
||||
- purge/read/write race ;
|
||||
- ForceRehydrate race ;
|
||||
- fuite SQL/server text ;
|
||||
- cancellation/rollback ;
|
||||
- migration mismatch.
|
||||
|
||||
## 11. Séquencement recalibré
|
||||
|
||||
Le forecast initial est étendu à `pre.013` afin de séparer proprement :
|
||||
|
||||
1. généralisation du moteur de migration ;
|
||||
2. V001/binding réseau ;
|
||||
3. mapping/read ;
|
||||
4. write/observation atomiques ;
|
||||
5. pagination ;
|
||||
6. rétention ;
|
||||
7. façade ;
|
||||
8. live PostgreSQL ;
|
||||
9. hardening ;
|
||||
10. gate ;
|
||||
11. docs ;
|
||||
12. publication.
|
||||
|
||||
## 12. Hors scope conservé
|
||||
|
||||
Aucun changement fonctionnel n'est apporté à :
|
||||
|
||||
```text
|
||||
RawAccountState
|
||||
N2
|
||||
workers/jobs/backfills
|
||||
apps
|
||||
transport
|
||||
codecs wire
|
||||
event bus
|
||||
compression/archive worker global
|
||||
autres backends
|
||||
```
|
||||
|
||||
## 13. Validations exécutées
|
||||
|
||||
Audit statique de la base et de l'overlay :
|
||||
|
||||
```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.3
|
||||
Markdown table audit: clean (214 table(s), 131 file(s))
|
||||
|
||||
assertions structurelles locales
|
||||
workspace.package.version = 0.3.3-pre.1
|
||||
headers/version des trois nouveaux Markdown corrects
|
||||
aucune référence résiduelle au faux code API RAW_RETENTION_UNSUPPORTED
|
||||
```
|
||||
|
||||
L'audit de base couvre aussi manifests/features, modules/exports, V000 et checksum, Config `std.store`, plans/validations `0.3.1`/`0.3.2`, tests hardening/completeness et preuve live documentée.
|
||||
|
||||
## 14. Validations non exécutées
|
||||
|
||||
Le conteneur d'assemblage ne fournit pas l'exécutable `cargo`. Les commandes suivantes sont donc **NON EXÉCUTÉES**, jamais déclarées PASS :
|
||||
|
||||
```text
|
||||
cargo fmt --all
|
||||
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 tests PostgreSQL live ne sont pas exécutés non plus. `pre.001` ne modifie aucun SQL/runtime métier, la preuve foundation réelle `0.3.2` est déjà acquise et le futur test RawTransaction n'existe pas encore.
|
||||
|
||||
## 15. Questions ouvertes
|
||||
|
||||
Aucune question de design bloquante n'est laissée ouverte par `pre.001`.
|
||||
|
||||
Les valeurs runtime retenues sont déjà fixées :
|
||||
|
||||
```text
|
||||
store.postgres_retention_compaction_unsupported
|
||||
store.wrong_network
|
||||
store.raw_reference_not_found
|
||||
store.postgres_read_failed
|
||||
store.postgres_write_failed
|
||||
store.postgres_data_invalid
|
||||
store.postgres_page_limit_unsupported
|
||||
```
|
||||
|
||||
Le checksum V001 n'est pas une question de design : il sera calculé sur les bytes exacts lorsque `V001__raw_transaction.sql` sera créé en `pre.003`.
|
||||
|
||||
## 16. Gate demandé
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Aucun test PostgreSQL live n'est requis dans cette tranche documentaire.
|
||||
Reference in New Issue
Block a user