khadhroony-solana-project/deltas/0.3.1/pre.001-fix.001.md

<!-- file: deltas/0.3.1/pre.001-fix.001.md -->
<!-- version: 1 -->

# Delta `0.3.1-pre.001-fix.001` — split façade Store / backend PostgreSQL et roadmap

## 1. Base

```text
livraison : 0.3.1-pre.001
Cargo     : 0.3.1-pre.1
```

Ce correctif reste dans le couloir de conception/audit de `pre.001`. Il ne crée aucune crate Store, aucun code runtime, aucune Config exécutable, aucune migration et aucune dependency PostgreSQL.

## 2. Motif opérateur

Le brainstorming postérieur à `pre.001` affine le split Store :

```text
0.3.1
    ksp-store-api uniquement

0.3.2
    ksp-store-lib
    ksp-store-postgres-lib
```

`ksp-store-api` reste propriétaire du modèle objet/struct commun RAW/observations et des contrats/capabilities backend. `ksp-store-lib` devient la façade/runtime commune consommée par les jobs/workers/apps. Les backends sont des crates séparées importées optionnellement par `ksp-store-lib` selon les features compilées.

## 3. Graphe corrigé

Cible durable :

```text
ksp-store-api
    ^                 ^
    |                 |
ksp-store-lib   ksp-store-postgres-lib
    |                 ^
    | feature postgres|
    +-----------------+

futur ksp-store-mysql-lib -> ksp-store-api
ksp-store-lib[mysql]       -> futur ksp-store-mysql-lib
```

Règles :

```text
ksp-store-postgres-lib -X-> ksp-store-lib
backend alternatif     -X-> ksp-store-lib
consumer métier        -X-> crate backend directe
consumer métier         -> ksp-store-lib uniquement côté Store
```

`ksp-store-lib` réexportera la surface commune de `ksp-store-api` nécessaire aux consumers afin qu'un worker/job n'ait pas à dépendre séparément de l'API et du backend.

## 4. Features et sélection runtime

`0.3.2` introduira :

```text
default = [postgres]
postgres -> dep:ksp-store-postgres-lib
```

Les futures features backend pourront être compilées simultanément. La feature contrôle la **disponibilité dans le binaire** ; Config contrôle le **backend actif**.

Un appel avec une Config demandant un backend KSP connu mais non présent dans les features compilées doit être rejeté explicitement, avec un code stable de type :

```text
STORE_BACKEND_NOT_COMPILED
```

Aucun fallback silencieux vers PostgreSQL n'est permis.

## 5. Config, URI, secrets et `.env`

La responsabilité reste conforme aux règles Config KSP :

```text
ksp-config-lib
    = documents + schemas + placeholders + .env + provenance/sensitivity

ksp-store-lib
    = settings runtime + backend dispatch

ksp-store-*-lib
    = connexion/persistence backend
```

Pour un backend disposant d'une URI/DSN naturelle, la Config utilisera une URI plutôt qu'une décomposition artificielle, sauf besoin backend réellement justifié. Des options backend-specific peuvent être ajoutées sous forme typée lorsque nécessaire.

Invariants :

- une URI pouvant contenir user/password/token est `Secret` dans son ensemble ;
- les credentials proviennent de placeholders `KSP_SECRET_*` résolus par `ksp-config-lib` ;
- toute nouvelle variable apparaît commentée dans `.env.example` lors de sa première utilisation réelle ;
- le vrai `.env` et les vrais URI/credentials ne sont jamais versionnés ;
- Store et backend ne lisent jamais directement `.env` ni les variables KSP/KSPB ;
- URI/DSN/password/token restent absents des `Debug`, logs, erreurs et health ;
- l'absence de feature backend est détectée avant toute connexion ou fallback driver implicite.

La forme exacte de `std.store`, du nom des variables et des settings runtime est reportée à `0.3.2`.

## 6. ROADMAP corrigé

La séquence devient :

```text
0.3.1  ksp-store-api RAW/observations
0.3.2  ksp-store-lib + ksp-store-postgres-lib
0.3.3  wires Interface nécessaires aux acquisitions/normalisation future
0.3.4  ksp-job-api + premier backfill historique
0.3.5  application backfill/inspection RAW
```

La ligne `0.3.1` passe en cours et n'annonce plus de persistence PostgreSQL dans cette release.

## 7. Version Cargo

Ce correctif est strictement documentaire. Conformément à `VER-ID-008`, `workspace.package.version` reste :

```text
0.3.1-pre.1
```

## 8. Fichiers modifiés

```text
ROADMAP.md
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
docs/validation/018-V0_3_1_STORE_RAW.md
```

## 9. Fichier ajouté

```text
deltas/0.3.1/pre.001-fix.001.md
```

## 10. Fichiers supprimés

```text
aucun
```

## 11. Validations exécutées

Dans l'environnement de génération du fix :

```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.1
  Markdown table audit: clean (184 table(s), 122 file(s))
```

`cargo` n'est pas disponible dans cet environnement. Comme le fix ne modifie aucun fichier de code/build/runtime/config exécutable, aucune version Cargo n'est changée ; le gate opérateur reste néanmoins :

```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.1
cargo check --workspace
cargo clippy --workspace --all-targets
```

Aucun test Store ciblé n'existe encore et aucun gate PostgreSQL n'est requis dans ce fix documentaire.

## 12. Questions ouvertes

Aucune question ne bloque `0.3.1-pre.002`.

Restent volontairement reportés à `0.3.2` :

```text
forme exacte de StoreSettings
shape du document std.store
nom exact des variables KSP_SECRET_* Store
URI/DSN PostgreSQL exact accepté
pool/TLS/timeouts
migrations/schema/indexes
mapping PostgreSQL des modèles API
```

Ces détails ne changent pas les frontières déjà fixées par le présent correctif.