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