khadhroony-solana-project/deltas/0.3.3/pre.007.md

Delta 0.3.3-pre.007 — rétention atomique RawTransaction

1. Base et gate d'entrée

Base opérateur obligatoire :

0.3.3-pre.6.fix.1

Le gate opérateur fourni le 2026-08-30 est entièrement vert :

cargo fmt --all                                      PASS
scripts/audit_rust_workspace_rules.py               PASS
scripts/audit_markdown_tables.py                    PASS
cargo check --workspace                             PASS
cargo clippy --workspace --all-targets              PASS
cargo test -p ksp-store-api                         PASS
cargo test -p ksp-store-lib                         PASS
cargo test -p ksp-store-postgres-lib                PASS (34 unit backend, live foundation ignoré)
cargo test -p ksp-config-lib                        PASS (128 unit + ownership/public API)
cargo check -p ksp-store-lib --no-default-features  PASS

La pagination/cursor pre.006 est donc acquise et la tranche peut ouvrir la rétention mutante.

2. Version

workspace.package.version = 0.3.3-pre.7

3. Scope exact

Cette tranche ajoute uniquement le bridge backend PostgreSQL de transition :

PostgresBackend::transition_raw_transaction_retention
Full -> Archived
Archived -> Purged
compare-and-transition
Compacted unsupported

Ne sont pas encore ouverts :

implémentations complètes des six traits RawTransaction*
dispatch ksp-store-lib
RawAccountState
worker/job policy

4. Pré-I/O

Avant pool.get() :

• le réseau de transition.reference() doit égaler le binding backend ;
• si expected ou target vaut Compacted, le backend retourne RetentionCompactionUnsupported ;
• le code KSP stable reste store.postgres_retention_compaction_unsupported.

Aucune ligne retention_state = 'compacted' n'est créée et aucune dépendance de compression n'est ajoutée.

5. Compare-and-transition

Sous transaction PostgreSQL, le canonical est lu avec FOR UPDATE. Sa forme physique est validée avant de retourner un outcome ou de muter :

current == target   -> AlreadyAtTarget
current != expected -> ExpectedStateMismatch
Full + expected Full + target Archived       -> archive
Archived + expected Archived + target Purged -> purge

Une référence absente est ReferenceNotFound. Aucun succès n'est rendu avant commit.

6. Full -> Archived

La transition :

1. exige un payload hot non vide et borné ;
2. exige l'absence d'une archive résiduelle ;
3. insère les octets exacts dans ksp_raw_transaction_archive_payloads ;
4. met payload = NULL et retention_state = 'archived' sur le canonical ;
5. commit les deux opérations ensemble.

Aucun état Archived sans payload archive n'est committé par KSP.

7. Archived -> Purged

La transition :

1. exige l'absence de payload hot et la présence d'un payload archive valide ;
2. supprime la ligne archive ;
3. met block_time_unix_millis = NULL, payload = NULL et retention_state = 'purged' ;
4. conserve signature, slot, format id/version et content hash ;
5. commit atomiquement.

Le tombstone reste donc limité aux cinq champs du contrat API.

8. Races croisées

Les acquisitions/idempotence/ForceRehydrate de pre.005 et les transitions de cette tranche verrouillent la même ligne canonical avant mutation. Les races archive/purge/rehydrate sont donc sérialisées ; la preuve concurrente PostgreSQL réelle reste réservée à pre.009.

9. Erreurs

La classification backend ajoute :

RetentionCompactionUnsupported

Les autres classifications réutilisées sont :

WrongNetwork
ReferenceNotFound
DataInvalid
WriteFailed

Aucun texte serveur, SQLSTATE, query ou bind n'est retenu.

10. Migrations

Aucune ressource V000/V001 n'est modifiée. Les checksums attendus restent :

V000 d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
V001 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51

11. Gate opérateur demandé

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

Le test PostgreSQL live reste #[ignore]; la preuve métier rétention/concurrence est réservée à pre.009.

12. Suite si gate vert

0.3.3-pre.008 — six implémentations de capabilities + dispatch ksp-store-lib