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

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