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

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

1. Base

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

0.3.1-pre.1

8. Fichiers modifiés

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

9. Fichier ajouté

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

10. Fichiers supprimés

aucun

11. Validations exécutées

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

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 :

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 :

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.