207 lines
6.5 KiB
Markdown
207 lines
6.5 KiB
Markdown
<!-- file: deltas/0.3.4/pre.001.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.4-pre.001` — audit et physical design `RawAccountState` PostgreSQL
|
|
|
|
## 1. Objet
|
|
|
|
Ouverture de :
|
|
|
|
```text
|
|
0.3.4 — Store/PostgreSQL RawAccountState + complétude/conformance RAW
|
|
```
|
|
|
|
Cette tranche reste volontairement un gate de lecture/audit/design/sizing. Aucun SQL V002, aucune table account, aucun repository account et aucune impl capability account ne sont ajoutés.
|
|
|
|
## 2. Base
|
|
|
|
Base canonique :
|
|
|
|
```text
|
|
v0.3.3
|
|
workspace.package.version = 0.3.3
|
|
```
|
|
|
|
Le gate opérateur fourni avec la reprise est propre sur audits Rust/Markdown, checks, Clippy et suites ciblées/workspace de la release stable ; les live tests restent opt-in/ignored.
|
|
|
|
## 3. Version
|
|
|
|
Version workspace après overlay :
|
|
|
|
```text
|
|
0.3.4-pre.1
|
|
```
|
|
|
|
Label de livraison :
|
|
|
|
```text
|
|
0.3.4-pre.001
|
|
```
|
|
|
|
## 4. Fichiers ajoutés
|
|
|
|
```text
|
|
docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md
|
|
docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md
|
|
deltas/0.3.4/pre.001.md
|
|
```
|
|
|
|
## 5. Fichier modifié
|
|
|
|
```text
|
|
Cargo.toml
|
|
```
|
|
|
|
Modifications :
|
|
|
|
```text
|
|
workspace.package.version : 0.3.3 -> 0.3.4-pre.1
|
|
file header version : 363 -> 364
|
|
```
|
|
|
|
## 6. Fichiers supprimés
|
|
|
|
Aucun.
|
|
|
|
## 7. Audit effectué
|
|
|
|
Ont été relus avant design : règles globales/KSP/Rust/dépendances/docs/versioning ; architectures Store/data/execution/workers ; plans/validations `0.3.1`, `0.3.2`, `0.3.3` ; source/tests Store API/façade/backend ; Config `std.store` ; migrations V000/V001 ; archive kbot3 ciblée account.
|
|
|
|
Inventaire confirmé :
|
|
|
|
```text
|
|
10 capabilities RAW contractuelles
|
|
6 RawTransaction implémentées physiquement dans PostgresBackend + Store
|
|
4 RawAccount encore non implémentées et explicitement fermées par canaries 0.3.3
|
|
```
|
|
|
|
Checksums recalculés :
|
|
|
|
```text
|
|
V000 = d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
|
|
V001 = 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51
|
|
```
|
|
|
|
## 8. Décisions majeures
|
|
|
|
### 8.1 V002
|
|
|
|
V002 sera additive, sous `migrations/v002_raw_account_state/`, avec seulement :
|
|
|
|
```text
|
|
ksp_raw_account_states
|
|
ksp_raw_account_observations
|
|
```
|
|
|
|
V000/V001 restent byte-immutables.
|
|
|
|
### 8.2 Identité state
|
|
|
|
```text
|
|
network API + (pubkey, slot, state_hash)
|
|
```
|
|
|
|
Le réseau est le binding DB existant. PK physique `(pubkey, slot, state_hash)`. Pubkey/owner/hash en BYTEA fixed-width ; slot/lamports/rent_epoch en NUMERIC(20,0). Data account en BYTEA complet, vide autorisé, maximum 16 MiB.
|
|
|
|
### 8.3 Observation
|
|
|
|
L'observation référence le state par FK composite et conserve provenance + `is_startup` + `transaction_signature` + `write_version`. Ces metadata restent observation-only. Aucune FK transaction n'est ajoutée.
|
|
|
|
### 8.4 Atomicité/idempotence
|
|
|
|
Pattern retenu : transaction PostgreSQL, `INSERT ... ON CONFLICT DO NOTHING RETURNING`, puis `SELECT ... FOR UPDATE` et comparaison exacte sur collision. Aucun `ON CONFLICT DO UPDATE`, aucun `has_*`, aucun overwrite silencieux.
|
|
|
|
`record_raw_account_observation` vérifie le state préexistant et ne le crée jamais implicitement.
|
|
|
|
### 8.5 Pagination
|
|
|
|
Ordre total :
|
|
|
|
```text
|
|
(slot, pubkey, state_hash)
|
|
```
|
|
|
|
Cursor V1 account fixe 109 bytes, magic `KSPA`, domaine `KSP/raw-account-state-cursor/v1`, digest lié au réseau, filtre pubkey, range, direction et dernière clé. Le cursor transaction `KSPT` est donc non rejouable.
|
|
|
|
Index métier additionnel unique :
|
|
|
|
```text
|
|
(slot, pubkey, state_hash)
|
|
```
|
|
|
|
Aucun index owner/provider/time/status.
|
|
|
|
## 9. Audit kbot3
|
|
|
|
Classification :
|
|
|
|
- **REPRENDRE** : invariants unicité/FK et principe d'index account+slot ; NUMERIC pour valeurs monétaires ;
|
|
- **REDESSINER** : identité durable, BYTEA fixed-width, bytes complets, u64 exact, observation séparée, atomicité/conflict/cursor ;
|
|
- **REPORTER** : normalisation CORE, processing ledger, batch 1000, indexes owner/provider/time/status ;
|
|
- **REJETER** : sqlx/monolithe, BIGSERIAL comme identité publique, base64 physique, BIGINT narrowing, status/error RAW, maintenance destructive comme comportement normal.
|
|
|
|
Aucun code historique n'est copié.
|
|
|
|
## 10. Threat model
|
|
|
|
Le plan couvre mauvaise DB/réseau, fixed-width hostile, overflow u64, 16 MiB, observation orpheline, rollback partiel, même pubkey+slot multi-state, conflits exacts, collisions observation, races, cursor hostile/cross-query/cross-family, ordre pagination, metadata Yellowstone, fuite SQL/server text, cancellation et migration mismatch.
|
|
|
|
## 11. Sizing recalibré
|
|
|
|
Le forecast est étendu à `pre.013` afin de séparer V002 registry/tables de ses contraintes/schema compatibility, puis acquisition write de la concurrence/observation supplémentaire. Le gate technique final reste suivi d'une lane documentaire et d'une lane publication distinctes.
|
|
|
|
## 12. Hors scope conservé
|
|
|
|
```text
|
|
ksp-store-api redesign
|
|
account retention/archive/purge
|
|
STRUCTURAL/CORE/DECODED/DOMAIN persistence
|
|
Interface events
|
|
workers/jobs/backfills
|
|
batch/priorité/backlog policy
|
|
nouveaux indexes sans query
|
|
nouveaux backends/apps
|
|
```
|
|
|
|
## 13. Questions ouvertes
|
|
|
|
Aucune question de contrat bloquante après `pre.001`. Les numéros exacts de ressources SQL et le découpage de helpers privés sont laissés à `pre.002/pre.003` sans pouvoir modifier les invariants figés.
|
|
|
|
## 14. Validations exécutées
|
|
|
|
```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 (240 table(s), 134 file(s))
|
|
|
|
assertions structurelles locales
|
|
workspace.package.version = 0.3.4-pre.1
|
|
Cargo.toml header version = 364
|
|
plan 025 / validation 021 / delta pre.001 présents
|
|
aucun répertoire migrations/v002_raw_account_state
|
|
aucun module backend raw_account créé
|
|
```
|
|
|
|
## 15. Validations non exécutées dans le conteneur d'assemblage
|
|
|
|
L'exécutable `cargo` n'est pas disponible dans cet environnement. L'appel `cargo fmt --all` s'arrête donc immédiatement avec `cargo: command not found`; aucune commande Cargo post-overlay n'est déclarée PASS.
|
|
|
|
À exécuter côté opérateur :
|
|
|
|
```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
|
|
```
|
|
|
|
Le gate opérateur de la base `v0.3.3` fourni avec la reprise était intégralement vert avant cet overlay. Cet historique ne remplace pas le gate post-overlay ci-dessus.
|