# 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.