v0.3.1-pre.011
This commit is contained in:
10
CHANGELOG.md
10
CHANGELOG.md
@@ -1,8 +1,16 @@
|
||||
<!-- file: CHANGELOG.md -->
|
||||
<!-- version: 18 -->
|
||||
<!-- version: 19 -->
|
||||
|
||||
# Changelog KSP
|
||||
|
||||
## 0.3.1 — Store API RAW foundation — 2026-08-29
|
||||
|
||||
`0.3.1` introduit `ksp-store-api` comme contrat backend-agnostic de persistence N1 RAW, sans runtime Store ni backend physique. La release stabilise deux familles réellement convergentes : `RawTransaction` avec payload canonique opaque/versionné, identité réseau+signature et observations d’acquisition séparées, puis `RawAccountState` avec bytes complets, identité réseau+pubkey+slot+hash et observations pouvant conserver les enrichissements Yellowstone sans les confondre avec l’état canonique. `TransactionStatusObservation` reste reporté faute de convergence sémantique suffisante entre snapshot HTTP, transition WebSocket et update Yellowstone ; `logsSubscribe`, slot/root/slotsUpdates et vote restent event-only candidats, `RawBlock` reste une idée conditionnelle et Yellowstone `Entry` reste rejeté de la taxonomie active.
|
||||
|
||||
La façade publique conserve un modèle objet sans SQL ni rows backend, des primitives de provenance/hash/timestamps bornées, des queries cursorisées sans plafond métier KSP arbitraire, des outcomes d’idempotence/conflit, dix capabilities fines object-safe et un lifecycle logique de rétention transactionnelle `Full -> Compacted -> Archived -> Purged`. Le tombstone minimal empêche le rebackfill normal après purge tandis que `ForceRehydrate` reste une intention distincte ; une course de compare-and-transition est représentée par `ExpectedStateMismatch` plutôt que par un overwrite silencieux. Le backlog, le batch-size, la priorité, la policy de processing, la compression/archive physique, les notifications runtime et les couches STRUCTURAL/DECODED/DOMAIN restent hors Store API. Le graphe normal final de `ksp-store-api` reste strictement limité à `ksp-core-lib`; aucun PostgreSQL, Tokio, serde, Config, Transport, Program, Logging ou backend concret n’entre dans la crate.
|
||||
|
||||
Les canaris de clôture verrouillent 60 exports crate-root, 10 capabilities, l’inventaire exact des modules RAW, l’implémentabilité par un backend externe, les bornes adversariales, la redaction des `Debug`, la frontière Interface/Store et l’absence de surface N2/N3/N4. Le gate technique de référence a été exécuté après `cargo clean` et passe audits Rust/Markdown, `cargo check --workspace`, Clippy, tests ciblés des crates, `cargo test --workspace`, builds Tauri des trois Desk et graphes Cargo ; les gates documentaires suivants restent également verts. Le redécoupage final prépare trois releases Store/PostgreSQL où `ksp-store-lib` et `ksp-store-postgres-lib` avancent toujours ensemble : `0.3.2` pour la fondation runtime/backend, `0.3.3` pour la vertical slice `RawTransaction`, puis `0.3.4` pour `RawAccountState` et la complétude RAW. `prompts/021-V0_3_2_START_PROMPT.md` ouvre donc uniquement la fondation conjointe Store/PostgreSQL, avec `tokio-postgres` comme driver retenu mais pooling, TLS, migrations et Config à réauditer avant implémentation lourde.
|
||||
|
||||
## 0.2.14 — Program API foundation — 2026-08-28
|
||||
|
||||
`0.2.14` introduit `ksp-program-api` comme première API publique extensible du domaine Program, volontairement limitée au décodage d’instructions et indépendante des runtimes supérieurs. La façade réexporte les contrats Core/Interface nécessaires puis possède `ProgramInstructionRecognition` (`NoMatch`, `ProgramMatch`, `ExactMatch`), `ProgramInstructionDecodeOutcome<Decoded>` (`Decoded`, `Unsupported`) et le trait `ProgramInstructionDecoder: Send + Sync`. L’output `Decoded` reste possédé par l’implémentation et ne reçoit aucun bound implicite `Debug`, `Clone`, `Send` ou `Sync`; les erreurs réelles restent dans le `Result` Core. Les Program IDs sont des `Pubkey` opaques : une implémentation externe peut prendre en charge un programme absent du registry Core sans enum centrale fermée, `Any`, JSON, descriptor global ni registry runtime.
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 330
|
||||
# version: 331
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-wallet-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.3.1-pre.10"
|
||||
version = "0.3.1-pre.11"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
37
ROADMAP.md
37
ROADMAP.md
@@ -1,5 +1,5 @@
|
||||
<!-- file: ROADMAP.md -->
|
||||
<!-- version: 93 -->
|
||||
<!-- version: 94 -->
|
||||
|
||||
# Roadmap KSP
|
||||
|
||||
@@ -93,26 +93,29 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
|
||||
## 0.3.x — RAW / acquisition persistée
|
||||
|
||||
- [/] `0.3.1` — Introduire `ksp-store-api` uniquement avec le **modèle objet commun et les contrats N1 RAW/observations** : `RawTransaction` + observations en premier, inventaire/admission cross-source des futurs account/status models, séparation explicite des events realtime non persistés, lifecycle logique de rétention/tombstone, outcomes, queries/pagination et contrats backend, sans persistence concrète ni configuration backend.
|
||||
- [ ] `0.3.2` — Introduire ensemble `ksp-store-lib` et `ksp-store-postgres-lib` : façade/runtime Store commune, feature `postgres` activée par défaut, implémentation PostgreSQL de référence via `tokio-postgres`, Config `std.store`/secrets et migrations privées au backend. Un backend connu demandé par Config mais absent des features compilées est rejeté explicitement.
|
||||
- [ ] `0.3.3` — Étendre `ksp-interface-lib` avec les modèles passifs/wires réellement partagés par acquisition/workers, notamment les events realtime non persistés retenus par l'audit `0.3.1`, sans dupliquer les modèles persistants de `ksp-store-api`.
|
||||
- [ ] `0.3.4` — Introduire `ksp-job-api` et un job de backfill historique concret consommant uniquement `ksp-store-lib` côté Store.
|
||||
- [ ] `0.3.5` — Introduire une application spécialisée de backfill/inspection RAW.
|
||||
- [ ] Compléter ensuite la couche RAW avec le worker/service live, son contrôle et les outils d'exploitation réellement nécessaires avant de passer à la couche de normalisation générique suivante.
|
||||
- [X] `0.3.1` — `ksp-store-api` stable : modèles N1 RAW backend-agnostic `RawTransaction` et `RawAccountState` avec observations, provenance, payload/hash/timestamps bornés, 10 capabilities object-safe, queries cursorisées sans plafond métier arbitraire, outcomes idempotence/conflit et lifecycle logique rétention/tombstone/force-rehydrate ; aucun backend physique, Config, runtime Store, notification dédiée ni surface STRUCTURAL/DECODED/DOMAIN.
|
||||
- [ ] `0.3.2` — Introduire ensemble `ksp-store-lib` et `ksp-store-postgres-lib` pour la **fondation runtime/backend PostgreSQL uniquement** : façade Store, feature `postgres` par défaut, dispatch des backends compilés, Config `std.store`/secrets, connexion/pool/TLS à réauditer, bootstrap/migrations privés et health/readiness seulement si un contrat portable est réellement justifié. Aucun schéma `RawTransaction`/`RawAccountState` n’est ajouté dans cette slice.
|
||||
- [ ] `0.3.3` — Étendre le même couple `ksp-store-lib` + `ksp-store-postgres-lib` avec la vertical slice PostgreSQL `RawTransaction` complète : persistence/observation atomiques, get/list cursorisé, idempotence/conflit, rétention/tombstone/force-rehydrate, concurrence et rollback validés sur PostgreSQL réel.
|
||||
- [ ] `0.3.4` — Étendre le même couple avec `RawAccountState` + observation, puis fermer la complétude/conformance RAW cross-family, les indexes/migrations physiques nécessaires et le hardening PostgreSQL final.
|
||||
- [ ] `0.3.5` — Étendre `ksp-interface-lib` uniquement avec les modèles passifs/events réellement partagés par les premiers consumers d’acquisition, sans dupliquer les modèles persistants de `ksp-store-api`.
|
||||
- [ ] `0.3.6` — Introduire `ksp-job-api` et un premier job de backfill historique concret consommant `ksp-store-lib`, avec policy/batch-size/progression possédés par le job et non par Store.
|
||||
- [ ] `0.3.7` — Introduire une application spécialisée de backfill/inspection RAW.
|
||||
- [ ] Compléter ensuite la couche RAW avec le worker/service live, son contrôle et les outils d’exploitation réellement nécessaires avant de passer à la couche de normalisation générique suivante.
|
||||
|
||||
### TODO/IDEAS — taxonomie N1, processing et rétention
|
||||
|
||||
- [ ] **TODO** — maintenir une matrice d'admission HTTP/WS/gRPC/provider pour chaque modèle N1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte.
|
||||
- [ ] **TODO** — `RawAccountState` + observation : auditer les shapes HTTP/WS/Yellowstone, conserver les bytes canoniques et documenter les limites de backfill historique avant de figer la capability de persistence.
|
||||
- [ ] **TODO** — `TransactionStatusObservation` : auditer `signatureSubscribe`, `getSignatureStatuses`, Yellowstone TransactionStatus et extensions provider ; distinguer persistence éventuelle et déclenchement d'event.
|
||||
- [ ] **TODO** — logs realtime : conserver `logMessages` dans `RawTransaction` jusqu'à la décomposition STRUCTURAL ; traiter `logsSubscribe` comme event-only candidat et décider son contrat passif dans `ksp-interface-lib`, sans table Store par défaut. Le format canonique d'un wake-up « donnée persistée disponible » reste distinct et appartient à `ksp-store-api` conformément à `KSP-NOTIFY-*`, tandis que sa publication appartient au worker/runtime.
|
||||
- [ ] **TODO** — maintenir la matrice d’admission HTTP/WS/gRPC/provider lors de toute nouvelle famille N1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte.
|
||||
- [X] `RawAccountState` + observation — contrat commun stabilisé en `0.3.1` avec bytes complets + slot, provenance séparée et enrichissements source-specific optionnels ; la persistence PostgreSQL physique reste réservée à `0.3.4`.
|
||||
- [ ] **TODO** — `TransactionStatusObservation` : réauditer `signatureSubscribe`, `getSignatureStatuses`, Yellowstone TransactionStatus et extensions provider lorsqu’un consumer réel apparaît ; ne pas fusionner snapshot, transition et update dans un modèle Option-soup.
|
||||
- [ ] **TODO** — logs realtime : conserver `logMessages` dans `RawTransaction` jusqu’à la décomposition STRUCTURAL ; traiter `logsSubscribe` comme event-only candidat et décider son contrat passif dans `ksp-interface-lib`, sans table Store par défaut. Le format canonique d’un wake-up « donnée persistée disponible » reste distinct et appartient à `ksp-store-api` conformément à `KSP-NOTIFY-*`, mais ne sera matérialisé qu’avec un publisher/consumer réel.
|
||||
- [ ] **TODO** — slot/root/slotsUpdates et vote : ne créer un modèle passif commun que si un consumer realtime réel et une sémantique cross-ledger/provider justifient le contrat ; aucune persistence Store par défaut.
|
||||
- [ ] **IDEA** — `RawBlock` : ne rouvrir que si une information block-level non reconstructible devient nécessaire ; `getBlock` doit d'abord être traité comme source de `RawTransaction`, pas comme invitation à recopier le ledger en blocs.
|
||||
- [ ] **REJET ACTUEL** — Yellowstone `Entry` : trop bas niveau et aucune destination replay/decomposition/event métier justifiant un modèle KSP n'est identifiée.
|
||||
- [ ] **TODO** — processing ledger : reprendre l'idée kbot2/kbot3 `stage + processor identity/version + input identity/hash + terminal status`, sans faire d'un `processed: bool` la preuve durable unique ; prévoir force replay/version upgrades.
|
||||
- [ ] **TODO** — lifecycle RAW : prévoir `Full -> Compacted -> Archived -> Purged`, policy d'éligibilité hors Store, compression/archive backend futures et tombstone minimal empêchant un backfill normal après purge ; une réhydratation doit être explicitement forcée.
|
||||
- [ ] **TODO** — frontière `ksp-interface-lib` / `ksp-store-api` : documenter chaque type partagé afin que les events passifs non persistés vivent dans Interface et que les modèles persistants/replayables vivent dans Store API, sans doublons quasi équivalents.
|
||||
- [ ] **IDEA** — réauditer la structure de processing/decode/materialization historique kbot2/kbot3 lors de l'ouverture de N2/N3 ; conserver l'isolation instruction/CPI et les statuts terminal/versionnés, sans reprendre automatiquement le schéma SQL historique.
|
||||
- [ ] **IDEA** — `RawBlock` : ne rouvrir que si une information block-level non reconstructible devient nécessaire ; `getBlock` doit d’abord être traité comme source de `RawTransaction`, pas comme invitation à recopier le ledger en blocs.
|
||||
- [ ] **REJET ACTUEL** — Yellowstone `Entry` : trop bas niveau et aucune destination replay/decomposition/event métier justifiant un modèle KSP n’est identifiée.
|
||||
- [ ] **TODO** — processing ledger : reprendre l’idée kbot2/kbot3 `stage + processor identity/version + input identity/hash + terminal status`, sans faire d’un `processed: bool` la preuve durable unique ; prévoir force replay/version upgrades lorsque les processors seront ouverts.
|
||||
- [X] lifecycle RAW logique — `RawRetentionState`, tombstone minimal, normal-skip et force-rehydrate sont stabilisés en `0.3.1` pour `RawTransaction`.
|
||||
- [ ] **TODO** — rétention physique : définir plus tard compression/archive backend, critères d’éligibilité fondés sur les preuves de processing et maintenance worker/job ; Store applique une transition demandée mais ne décide pas seul qu’un RAW peut être purgé.
|
||||
- [X] frontière `ksp-interface-lib` / `ksp-store-api` — ownership documenté et canaris de non-duplication stabilisés en `0.3.1`; les events passifs non persistés restent Interface, les modèles persistants/replayables restent Store API.
|
||||
- [ ] **IDEA** — réauditer la structure de processing/decode/materialization historique kbot2/kbot3 lors de l’ouverture de N2/N3 ; conserver l’isolation instruction/CPI et les statuts terminal/versionnés, sans reprendre automatiquement le schéma SQL historique.
|
||||
|
||||
## Série STRUCTURAL suivante
|
||||
|
||||
|
||||
270
deltas/0.3.1/pre.011.md
Normal file
270
deltas/0.3.1/pre.011.md
Normal file
@@ -0,0 +1,270 @@
|
||||
<!-- file: deltas/0.3.1/pre.011.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.1-pre.011` — préparation de publication et prompt `0.3.2`
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
```text
|
||||
0.3.1-pre.010
|
||||
workspace.package.version = 0.3.1-pre.10
|
||||
```
|
||||
|
||||
Le gate opérateur de `pre.010`, exécuté le **29 août 2026**, est propre :
|
||||
|
||||
```text
|
||||
cargo fmt --all PASS
|
||||
python3 scripts/audit_rust_workspace_rules.py PASS / clean
|
||||
python3 scripts/audit_markdown_tables.py PASS / clean — 186 tables / 135 fichiers
|
||||
cargo check --workspace PASS
|
||||
cargo clippy --workspace --all-targets PASS
|
||||
cargo test -p ksp-store-api PASS
|
||||
unit 15/15
|
||||
dependency_boundary 2/2
|
||||
external_backend 1/1
|
||||
public_api 7/7
|
||||
release_completeness 5/5
|
||||
security_hardening 4/4
|
||||
```
|
||||
|
||||
Le gate technique lourd de référence de `pre.008`, exécuté après `cargo clean`, a également validé le workspace complet, les tests ciblés, `cargo test --workspace`, les trois builds Tauri et les graphes Cargo. Le seul nom de package erroné utilisé dans la première séquence (`ksp-program-lib`) a été immédiatement remplacé par `cargo test -p ksp-program-api`, qui passe intégralement.
|
||||
|
||||
## 2. Objectif
|
||||
|
||||
Dernière prerelease avant `rel.001`, strictement limitée à la préparation de publication :
|
||||
|
||||
```text
|
||||
bump workspace vers 0.3.1-pre.11
|
||||
ajout de l'entrée stable candidate 0.3.1 dans CHANGELOG.md
|
||||
fermeture 0.3.1 et trajectoire 0.3.2..0.3.7 dans ROADMAP.md
|
||||
création du prompt 0.3.2
|
||||
delta pre.011
|
||||
```
|
||||
|
||||
Aucun code, test, manifest de crate, README/USAGE, plan, validation, architecture ou règle normative n'est rouvert.
|
||||
|
||||
## 3. Version Cargo
|
||||
|
||||
```text
|
||||
0.3.1-pre.10
|
||||
-> 0.3.1-pre.11
|
||||
```
|
||||
|
||||
## 4. Changelog `0.3.1`
|
||||
|
||||
`CHANGELOG.md` enregistre la surface stable candidate réellement livrée :
|
||||
|
||||
```text
|
||||
ksp-store-api uniquement
|
||||
RawTransaction + observation
|
||||
RawAccountState + observation
|
||||
primitives RAW/provenance/hash/timestamp
|
||||
queries cursorisées sans plafond métier KSP
|
||||
10 capabilities object-safe
|
||||
idempotence/conflit
|
||||
rétention/tombstone/force-rehydrate
|
||||
ExpectedStateMismatch
|
||||
60 exports crate-root
|
||||
backend externe canari
|
||||
aucun PostgreSQL/runtime Config/Transport/Program/Logging
|
||||
aucune surface STRUCTURAL/DECODED/DOMAIN
|
||||
```
|
||||
|
||||
Il enregistre aussi le gate de référence après `cargo clean` et le redécoupage final :
|
||||
|
||||
```text
|
||||
0.3.2 fondation Store/PostgreSQL
|
||||
0.3.3 RawTransaction PostgreSQL
|
||||
0.3.4 RawAccountState + complétude RAW
|
||||
```
|
||||
|
||||
## 5. Roadmap
|
||||
|
||||
`ROADMAP.md` :
|
||||
|
||||
```text
|
||||
passe 0.3.1 à [X]
|
||||
réduit explicitement 0.3.2 à la fondation runtime/backend
|
||||
ajoute 0.3.3 RawTransaction
|
||||
ajoute 0.3.4 RawAccountState + complétude
|
||||
renumérote Interface / Job / application en 0.3.5 / 0.3.6 / 0.3.7
|
||||
reclasse les TODO déjà matérialisés par 0.3.1
|
||||
```
|
||||
|
||||
La règle de pagination reste visible : Store navigue/cursorise ; batch-size, priorité et policy appartiennent aux futurs workers/jobs/executors.
|
||||
|
||||
## 6. Prompt `0.3.2`
|
||||
|
||||
Le nouveau prompt est confronté à :
|
||||
|
||||
```text
|
||||
docs/rules/PROMPT_STRUCTURE.md
|
||||
docs/rules/VERSION_WORKFLOW.md
|
||||
docs/rules/FILE_CONTRACTS.md
|
||||
docs/rules/RULES_KSP.md
|
||||
docs/rules/RULES_DEPENDENCIES.md
|
||||
|
||||
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||||
docs/architecture/004-COMPONENT_INVENTORY.md
|
||||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
|
||||
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
|
||||
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
|
||||
docs/validation/018-V0_3_1_STORE_RAW.md
|
||||
```
|
||||
|
||||
L'archive historique reste requise :
|
||||
|
||||
```text
|
||||
khadhroony-bot3_v0.5.3-pre.005-fix010.zip
|
||||
```
|
||||
|
||||
mais seulement pour réauditer les éléments physiques Store/PostgreSQL pertinents : runtime, pool, Config, migrations, schema/versioning et health. Elle n'est jamais une base de code.
|
||||
|
||||
Références externes vérifiées lors de la préparation du prompt, le **29 août 2026** :
|
||||
|
||||
```text
|
||||
PostgreSQL stable : 18.6
|
||||
tokio-postgres : 0.7.18
|
||||
```
|
||||
|
||||
Le prompt impose de réauditer ces versions à l'ouverture réelle de `0.3.2`.
|
||||
|
||||
## 7. Scope strict du prompt suivant
|
||||
|
||||
`0.3.2` ouvre ensemble :
|
||||
|
||||
```text
|
||||
ksp-store-lib
|
||||
ksp-store-postgres-lib
|
||||
```
|
||||
|
||||
pour :
|
||||
|
||||
```text
|
||||
features/backend dispatch
|
||||
Store settings/lifecycle
|
||||
Config std.store
|
||||
connexion/pool/TLS PostgreSQL
|
||||
migrations/bootstrap privés
|
||||
health/readiness seulement si justifié
|
||||
PostgreSQL integration réelle
|
||||
```
|
||||
|
||||
Sont explicitement réservés :
|
||||
|
||||
```text
|
||||
0.3.3 -> RawTransaction PostgreSQL complet
|
||||
0.3.4 -> RawAccountState PostgreSQL + complétude RAW
|
||||
```
|
||||
|
||||
Aucune table RAW métier n'est demandée à `0.3.2`.
|
||||
|
||||
## 8. Prévision souple intégrée au prompt
|
||||
|
||||
Le prompt réserve :
|
||||
|
||||
```text
|
||||
pre.001 audit/threat model/dependencies/sizing
|
||||
pre.002 scaffold deux crates + feature graph
|
||||
pre.003 settings/backend selection/lifecycle
|
||||
pre.004 Config std.store
|
||||
pre.005 connexion/pool/TLS
|
||||
pre.006 migrations/bootstrap
|
||||
pre.007 composition facade/backend + diagnostics
|
||||
pre.008 PostgreSQL integration réelle
|
||||
pre.009 hardening/completeness/feature matrix
|
||||
pre.010 gate technique final
|
||||
pre.011 réconciliation documentaire
|
||||
pre.012 préparation de publication
|
||||
rel.001 publication stable
|
||||
```
|
||||
|
||||
La prévision reste souple et doit être recalibrée par `0.3.2-pre.001`.
|
||||
|
||||
## 9. Fichiers ajoutés
|
||||
|
||||
```text
|
||||
prompts/021-V0_3_2_START_PROMPT.md
|
||||
deltas/0.3.1/pre.011.md
|
||||
```
|
||||
|
||||
## 10. Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
```
|
||||
|
||||
## 11. Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## 12. Surfaces explicitement non rouvertes
|
||||
|
||||
```text
|
||||
README.md
|
||||
RULES.md
|
||||
.env.example
|
||||
config/**
|
||||
crates/**
|
||||
docs/**
|
||||
prompts/001..020
|
||||
```
|
||||
|
||||
En particulier :
|
||||
|
||||
```text
|
||||
crates/ksp-store-api/**
|
||||
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
|
||||
docs/validation/018-V0_3_1_STORE_RAW.md
|
||||
docs/architecture/**
|
||||
```
|
||||
|
||||
## 13. Validations de préparation
|
||||
|
||||
À exécuter sur l'arbre reconstruit :
|
||||
|
||||
```text
|
||||
audit Rust workspace
|
||||
audit Markdown
|
||||
contrôle exact du payload overlay
|
||||
contrôle versions/file headers
|
||||
contrôle qu'aucun fichier hors lane n'est modifié
|
||||
```
|
||||
|
||||
Aucun résultat Cargo nouveau n'est revendiqué par la génération de cette tranche.
|
||||
|
||||
## 14. Gate opérateur
|
||||
|
||||
La lane est documentaire/de publication ; un gate ciblé suffit :
|
||||
|
||||
```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
|
||||
cargo test -p ksp-store-api
|
||||
```
|
||||
|
||||
Le gate lourd workspace/Tauri a déjà été exécuté sur `pre.008` et aucune surface code/runtime/dependency n'est rouverte depuis.
|
||||
|
||||
## 15. Étape suivante
|
||||
|
||||
Si le gate reste vert :
|
||||
|
||||
```text
|
||||
0.3.1-rel.001
|
||||
```
|
||||
|
||||
La publication stable doit être strictement mécanique :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.1
|
||||
deltas/0.3.1/rel.001.md
|
||||
```
|
||||
|
||||
`rel.001` ne doit rouvrir ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt `0.3.2`.
|
||||
932
prompts/021-V0_3_2_START_PROMPT.md
Normal file
932
prompts/021-V0_3_2_START_PROMPT.md
Normal file
@@ -0,0 +1,932 @@
|
||||
<!-- file: prompts/021-V0_3_2_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Prompt de démarrage `0.3.2` — Store/PostgreSQL runtime foundation
|
||||
|
||||
## 1. Identité de la release et bases exactes requises
|
||||
|
||||
La base KSP attendue est **exclusivement** la release stable :
|
||||
|
||||
```text
|
||||
v0.3.1
|
||||
```
|
||||
|
||||
La release à ouvrir est :
|
||||
|
||||
```text
|
||||
0.3.2 — Store/PostgreSQL runtime foundation
|
||||
```
|
||||
|
||||
La première tranche est :
|
||||
|
||||
```text
|
||||
0.3.2-pre.001
|
||||
```
|
||||
|
||||
Deux archives sont requises au démarrage :
|
||||
|
||||
```text
|
||||
1. archive opérateur correspondant exactement à KSP v0.3.1
|
||||
2. archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip
|
||||
```
|
||||
|
||||
Ordre d'autorité :
|
||||
|
||||
```text
|
||||
v0.3.1 réelle / archive opérateur autorité KSP actuelle
|
||||
règles + architecture de v0.3.1 autorité normative et architecturale
|
||||
plan + validation 0.3.1 autorité sur les contrats Store API acquis
|
||||
PostgreSQL/tokio-postgres actuels autorité externe sur les comportements présents
|
||||
khadhroony-bot3 historique source d'audit/héritage uniquement
|
||||
anciens prompts / snippets / mémoire auxiliaires seulement
|
||||
```
|
||||
|
||||
L'archive kbot3 reste obligatoire pour `pre.001`, mais l'audit n'a pas à répéter mécaniquement tout `0.3.1`. Il doit rouvrir les parties physiques pertinentes : ancien runtime Store, configuration, connexion PostgreSQL, migrations, schema/versioning, health/readiness, erreurs, pool et stratégie d'intégration.
|
||||
|
||||
Si l'archive historique n'est pas disponible :
|
||||
|
||||
```text
|
||||
ne pas inventer son contenu depuis la mémoire
|
||||
ne pas déclarer l'audit d'héritage physique terminé
|
||||
ne pas figer le mécanisme final de migrations/bootstrap
|
||||
```
|
||||
|
||||
Ne pas ouvrir `0.3.2` depuis :
|
||||
|
||||
```text
|
||||
0.3.1-pre.*
|
||||
0.3.1-pre.*-fix.*
|
||||
0.3.1-rel.* non encore validé stable
|
||||
une archive intermédiaire de travail
|
||||
khadhroony-bot3 comme base de code
|
||||
un souvenir de session
|
||||
```
|
||||
|
||||
À l'ouverture, vérifier au minimum :
|
||||
|
||||
```text
|
||||
tag Git v0.3.1 si metadata Git disponible
|
||||
workspace.package.version = 0.3.1
|
||||
deltas/0.3.1/rel.001.md présent
|
||||
prompts/021-V0_3_2_START_PROMPT.md présent
|
||||
ksp-store-api présent
|
||||
ksp-store-lib absent sauf contradiction de la base réelle
|
||||
ksp-store-postgres-lib absent sauf contradiction de la base réelle
|
||||
archive khadhroony-bot3_v0.5.3-pre.005-fix010.zip disponible
|
||||
```
|
||||
|
||||
Si une divergence existe entre ce prompt et la base stable réelle, **la base stable réelle gagne** et la divergence devient une sortie explicite de `pre.001`.
|
||||
|
||||
`pre.001` est obligatoirement une tranche de **lecture + audit + brainstorming + threat model + dependency graph + sizing + planification**. Aucune implémentation lourde de connexion, pool, TLS, migration ou Config Store ne commence avant la sortie cohérente de ce gate.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mission et résultat attendu
|
||||
|
||||
`0.3.2` introduit ensemble :
|
||||
|
||||
```text
|
||||
ksp-store-lib
|
||||
ksp-store-postgres-lib
|
||||
```
|
||||
|
||||
mais **uniquement comme fondation runtime/backend PostgreSQL**.
|
||||
|
||||
La séparation durable est :
|
||||
|
||||
```text
|
||||
ksp-store-api
|
||||
contrats backend-agnostic persistants
|
||||
|
||||
ksp-store-lib
|
||||
façade/runtime Store commune
|
||||
sélectionne uniquement les backends compilés
|
||||
feature postgres activée par défaut
|
||||
|
||||
ksp-store-postgres-lib
|
||||
backend PostgreSQL officiel de référence
|
||||
dépend de ksp-store-api
|
||||
ne dépend jamais de ksp-store-lib
|
||||
possède seul driver / pool / TLS / SQL / migrations physiques
|
||||
```
|
||||
|
||||
Le résultat attendu à la clôture est une fondation réelle capable de :
|
||||
|
||||
```text
|
||||
construire des Store settings indépendants de Config
|
||||
sélectionner explicitement un backend compilé
|
||||
ouvrir et fermer proprement le runtime Store
|
||||
ouvrir une connexion/pool PostgreSQL réellement fonctionnel
|
||||
initialiser et vérifier la fondation de migrations/schema sans tables RAW métier
|
||||
rejeter proprement un backend connu mais non compilé
|
||||
recevoir la Config effective uniquement depuis ksp-config-lib
|
||||
ne lire directement aucun .env / KSP_* / KSPB_* / PG* / .pgpass dans Store/backend
|
||||
fournir des erreurs et diagnostics sans URI/credential/SQL parameter sensible
|
||||
prouver la fondation sur un PostgreSQL réel dans un test opt-in isolé et non destructif
|
||||
```
|
||||
|
||||
`0.3.2` **ne doit pas** implémenter les vertical slices persistence de :
|
||||
|
||||
```text
|
||||
RawTransaction réservé à 0.3.3
|
||||
RawAccountState réservé à 0.3.4
|
||||
```
|
||||
|
||||
La release peut créer les structures privées nécessaires au runtime et au moteur de migrations, mais aucun schéma/table/index métier `RawTransaction` ou `RawAccountState` n'est ajouté uniquement pour « tester » PostgreSQL.
|
||||
|
||||
---
|
||||
|
||||
## 3. Sources de vérité internes obligatoires — ordre de lecture
|
||||
|
||||
### 3.1 Règles globales
|
||||
|
||||
Lire d'abord :
|
||||
|
||||
```text
|
||||
RULES.md
|
||||
docs/000-README.md
|
||||
|
||||
docs/rules/RULES_GENERAL.md
|
||||
docs/rules/RULES_KSP.md
|
||||
docs/rules/RULES_RUST.md
|
||||
docs/rules/RULES_DEPENDENCIES.md
|
||||
docs/rules/RULES_DOCUMENTATION.md
|
||||
docs/rules/FILE_CONTRACTS.md
|
||||
docs/rules/VERSION_WORKFLOW.md
|
||||
docs/rules/PROMPT_STRUCTURE.md
|
||||
```
|
||||
|
||||
Relire particulièrement :
|
||||
|
||||
```text
|
||||
KSP-API-001..007
|
||||
KSP-CONFIG-001..018
|
||||
KSP-STORE-001..002
|
||||
KSP-NOTIFY-001..006
|
||||
KSP-PROC-001..008
|
||||
KSP-REL-001..016
|
||||
|
||||
DEP-KSP-001..005
|
||||
DEP-CARGO-001..007
|
||||
DEP-LOG-001..012
|
||||
DEP-STORE-001..010
|
||||
DEP-WORKER-001..003
|
||||
DEP-JOB-001..003
|
||||
```
|
||||
|
||||
Rappels directement structurants :
|
||||
|
||||
```text
|
||||
ksp-store-lib -> ksp-store-api
|
||||
ksp-store-lib[postgres] -> ksp-store-postgres-lib
|
||||
ksp-store-postgres-lib -> ksp-store-api
|
||||
ksp-store-postgres-lib -X-> ksp-store-lib
|
||||
Config -> Store autorisé
|
||||
Store -X-> Config
|
||||
Transport -X-> Store
|
||||
Program/Materializer -X-> Store
|
||||
workers/jobs/apps futurs -> ksp-store-lib
|
||||
workers/jobs/apps futurs -X-> ksp-store-postgres-lib
|
||||
```
|
||||
|
||||
### 3.2 Architecture durable
|
||||
|
||||
Lire ensuite :
|
||||
|
||||
```text
|
||||
docs/architecture/000-README.md
|
||||
docs/architecture/001-PROJECT_OBJECTIVES.md
|
||||
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
|
||||
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||||
docs/architecture/004-COMPONENT_INVENTORY.md
|
||||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||
docs/architecture/007-EXECUTION_AND_POLICY.md
|
||||
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
|
||||
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
|
||||
```
|
||||
|
||||
Références centrales de cette release :
|
||||
|
||||
```text
|
||||
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
|
||||
```
|
||||
|
||||
Préserver notamment :
|
||||
|
||||
```text
|
||||
Store persiste et sert des contrats ; il ne possède pas les policies d'exécution
|
||||
la pagination/cursorisation Store n'impose aucun plafond métier global arbitraire
|
||||
batch-size/priorité/stratégie appartiennent aux futurs workers/jobs/executors
|
||||
Config possède documents/placeholders/.env/secrets
|
||||
backend PostgreSQL possède son driver et ses objets physiques
|
||||
aucun type SQL/backend ne traverse la façade publique
|
||||
```
|
||||
|
||||
### 3.3 État `0.3.1` à relire intégralement
|
||||
|
||||
Lire :
|
||||
|
||||
```text
|
||||
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
|
||||
docs/validation/018-V0_3_1_STORE_RAW.md
|
||||
crates/ksp-store-api/Cargo.toml
|
||||
crates/ksp-store-api/src/**
|
||||
crates/ksp-store-api/tests/**
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
```
|
||||
|
||||
Créer en `pre.001` :
|
||||
|
||||
```text
|
||||
docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md
|
||||
docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md
|
||||
```
|
||||
|
||||
Le plan doit contenir la prévision souple recalibrée de la release et rester la référence détaillée des prereleases.
|
||||
|
||||
---
|
||||
|
||||
## 4. Sources externes normatives à réauditer
|
||||
|
||||
La fraîcheur importe pour cette release.
|
||||
|
||||
Réauditer au début de `pre.001` avec les sources primaires actuelles :
|
||||
|
||||
```text
|
||||
PostgreSQL documentation/release notes courantes
|
||||
tokio-postgres docs.rs / crates.io / repository upstream
|
||||
runtime Tokio réellement requis par tokio-postgres
|
||||
connecteurs TLS réellement compatibles et maintenus
|
||||
solutions de pooling candidates si un pool externe est retenu
|
||||
```
|
||||
|
||||
Référence connue lors de la préparation de ce prompt, le **29 août 2026** :
|
||||
|
||||
```text
|
||||
PostgreSQL stable courant : 18.6
|
||||
tokio-postgres courant : 0.7.18
|
||||
```
|
||||
|
||||
Ces versions sont des **points de départ d'audit**, pas des pins automatiques. `pre.001` doit vérifier qu'elles sont toujours les versions stables pertinentes au moment réel de l'implémentation.
|
||||
|
||||
Décision déjà acquise :
|
||||
|
||||
```text
|
||||
driver PostgreSQL KSP = tokio-postgres
|
||||
```
|
||||
|
||||
Ne pas rouvrir SQLx comme choix principal sauf contradiction technique nouvelle et documentée.
|
||||
|
||||
Questions externes encore ouvertes à auditer :
|
||||
|
||||
```text
|
||||
pooling : pool externe maintenu vs abstraction KSP minimale
|
||||
TLS : connecteur exact, root store, modes supportés, absence de fuite de secrets
|
||||
PostgreSQL major minimal supporté/testé
|
||||
migrations : mécanisme KSP privé vs crate externe réellement justifiée
|
||||
checksums/versioning/locking de migrations
|
||||
timeouts et shutdown propre
|
||||
```
|
||||
|
||||
Aucune dépendance additionnelle n'est ajoutée seulement parce qu'elle est habituelle dans l'écosystème.
|
||||
|
||||
---
|
||||
|
||||
## 5. État validé de `0.3.1` à préserver
|
||||
|
||||
`ksp-store-api` est une fondation stable candidate et ne doit pas être redessinée pour simplifier PostgreSQL.
|
||||
|
||||
Surface acquise :
|
||||
|
||||
```text
|
||||
60 exports crate-root
|
||||
10 capabilities fines object-safe
|
||||
RawTransaction + RawTransactionObservation
|
||||
RawAccountState + RawAccountObservation
|
||||
RawPayload / RawContentHash / RawObservationKey
|
||||
provenance/timestamps/codes bornés
|
||||
queries cursorisées
|
||||
outcomes idempotence/conflit
|
||||
RawRetentionState / tombstone / force-rehydrate
|
||||
ExpectedStateMismatch pour race de rétention
|
||||
```
|
||||
|
||||
Propriétés acquises :
|
||||
|
||||
```text
|
||||
ksp-store-api -> ksp-core-lib uniquement
|
||||
aucun pub mod public
|
||||
aucun SQL / row / pool / runtime DB
|
||||
aucun serde/tokio/config/transport/program/logging
|
||||
aucun modèle event-only
|
||||
aucune surface STRUCTURAL / DECODED / DOMAIN
|
||||
backend externe implémentable sans ksp-store-lib
|
||||
```
|
||||
|
||||
`0.3.2` ne modifie `ksp-store-api` que si un **gap backend-agnostic concret et bloquant** est démontré par l'implémentation de fondation. Une préférence PostgreSQL, un type de pool ou un besoin SQL n'est jamais une raison suffisante.
|
||||
|
||||
---
|
||||
|
||||
## 6. Décisions acquises et questions réellement ouvertes
|
||||
|
||||
### 6.1 Décisions acquises
|
||||
|
||||
```text
|
||||
ksp-store-lib et ksp-store-postgres-lib sont ouvertes ensemble
|
||||
postgres est la feature backend par défaut de ksp-store-lib
|
||||
tokio-postgres est le driver PostgreSQL retenu
|
||||
ksp-store-postgres-lib dépend de ksp-store-api, jamais de ksp-store-lib
|
||||
ksp-store-lib ne contient aucun SQL/backend physique
|
||||
Config sélectionne le backend parmi ceux compilés
|
||||
backend connu mais non compilé -> erreur explicite, aucun fallback silencieux
|
||||
Config possède URI/secrets/.env ; Store/backend ne lisent aucun environnement directement
|
||||
RawTransaction PostgreSQL est hors 0.3.2
|
||||
RawAccountState PostgreSQL est hors 0.3.2
|
||||
pagination Store != policy de batch executor
|
||||
```
|
||||
|
||||
### 6.2 Questions ouvertes à fermer par `pre.001`
|
||||
|
||||
```text
|
||||
forme exacte de StoreSettings et StoreBackendKind
|
||||
forme exacte du lifecycle Store open/close
|
||||
reexports API nécessaires depuis ksp-store-lib
|
||||
pool : bibliothèque externe ou implémentation KSP minimale
|
||||
TLS : connecteur/features/modes réellement retenus
|
||||
support PostgreSQL major minimal
|
||||
mécanisme de migration/version/checksum
|
||||
verrouillage concurrent du bootstrap/migrations
|
||||
schema/namespace privé de migration
|
||||
stratégie de rollback après migration échouée
|
||||
health/readiness portable : nécessaire maintenant ou reporté
|
||||
stratégie de test PostgreSQL réel isolé/non destructif
|
||||
forme exacte de std.store et de ses profils/secrets
|
||||
impacts de packaging Config/Tauri lorsque le registre Config gagne std.store
|
||||
```
|
||||
|
||||
Une question ouverte ne doit pas être résolue par imitation de kbot3 ou par habitude ecosystem sans audit.
|
||||
|
||||
---
|
||||
|
||||
## 7. Objectifs et livrables de `0.3.2`
|
||||
|
||||
### 7.1 `ksp-store-lib`
|
||||
|
||||
À la clôture, la crate doit au minimum :
|
||||
|
||||
```text
|
||||
exister comme bibliothèque Rust 2024
|
||||
avoir ksp-store-api comme dépendance normale
|
||||
avoir la feature postgres activée par défaut
|
||||
lier ksp-store-postgres-lib uniquement sous feature postgres
|
||||
rester compilable --no-default-features
|
||||
exposer une façade Store/runtime commune
|
||||
accepter des settings déjà résolus
|
||||
sélectionner un backend compilé explicitement
|
||||
rejeter un backend connu non compilé avec erreur stable
|
||||
ne jamais exposer un handle/type PostgreSQL public
|
||||
réexporter uniquement la surface ksp-store-api réellement utile aux consumers
|
||||
posséder README.md + USAGE.md durables avant fermeture
|
||||
```
|
||||
|
||||
### 7.2 `ksp-store-postgres-lib`
|
||||
|
||||
À la clôture, la crate doit au minimum :
|
||||
|
||||
```text
|
||||
exister comme backend officiel
|
||||
avoir ksp-store-api comme dépendance KSP
|
||||
ne jamais dépendre de ksp-store-lib
|
||||
posséder tokio-postgres en interne
|
||||
posséder connexion/pool/TLS retenus
|
||||
posséder bootstrap/migrations privés
|
||||
ouvrir/fermer proprement ses ressources
|
||||
sanitiser erreurs/Debug/logs
|
||||
ne lire aucun Config/env directement
|
||||
ne créer aucune table RAW métier de 0.3.3/0.3.4
|
||||
posséder README.md + USAGE.md durables avant fermeture
|
||||
```
|
||||
|
||||
Une table/namespace interne de suivi des migrations peut être créée si elle est réellement nécessaire au moteur de migration ; elle reste une primitive d'infrastructure, pas une première table RAW métier.
|
||||
|
||||
### 7.3 Config `std.store`
|
||||
|
||||
La release doit ajouter une Config Store seulement après design `pre.001` :
|
||||
|
||||
```text
|
||||
config/std.store.json
|
||||
config/examples/std.store.example.json
|
||||
config/schemas/std.store.schema.json
|
||||
registry Config + file IDs
|
||||
adapter typed ksp-config-lib -> StoreSettings
|
||||
provenance/sensibilité/redaction conformes aux règles Config
|
||||
```
|
||||
|
||||
Les secrets PostgreSQL passent par Config. Ne jamais introduire dans Store/backend :
|
||||
|
||||
```text
|
||||
std::env
|
||||
.env parsing
|
||||
KSP_* / KSPB_* lookup
|
||||
PGHOST / PGPORT / PGUSER / PGPASSWORD / PGDATABASE
|
||||
.pgpass implicite
|
||||
```
|
||||
|
||||
Auditer les bundles/resources Tauri existants : ne modifier les apps que si leur contrat de packaging Config exige réellement la nouvelle ressource. Aucun nouvel écran Store n'est ajouté.
|
||||
|
||||
### 7.4 Migrations et bootstrap
|
||||
|
||||
Le mécanisme retenu doit au minimum couvrir :
|
||||
|
||||
```text
|
||||
ordre déterministe
|
||||
identité/version de migration
|
||||
checksum ou preuve équivalente contre modification silencieuse
|
||||
application transactionnelle lorsque PostgreSQL le permet
|
||||
verrouillage/concurrence de bootstrap
|
||||
reprise sûre après échec
|
||||
mismatch explicite
|
||||
aucun SQL dynamique construit depuis input non fiable
|
||||
introspection/version observable sans exposer les SQL internes publiquement
|
||||
```
|
||||
|
||||
Les migrations sont privées à `ksp-store-postgres-lib`.
|
||||
|
||||
Aucune migration `RawTransaction` ou `RawAccountState` n'est créée dans cette release.
|
||||
|
||||
---
|
||||
|
||||
## 8. Hors périmètre strict
|
||||
|
||||
Ne pas ouvrir dans `0.3.2` :
|
||||
|
||||
```text
|
||||
persistence PostgreSQL RawTransaction
|
||||
persistence PostgreSQL RawTransactionObservation
|
||||
queries RawTransaction PostgreSQL
|
||||
retention/tombstone RawTransaction PostgreSQL
|
||||
persistence PostgreSQL RawAccountState
|
||||
persistence PostgreSQL RawAccountObservation
|
||||
queries RawAccountState PostgreSQL
|
||||
processing ledger
|
||||
claims/leases de processing
|
||||
compression/archive RAW physique
|
||||
worker/job/backfill
|
||||
application Store/inspection
|
||||
notification event bus
|
||||
LISTEN/NOTIFY comme mécanisme requis
|
||||
N2 STRUCTURAL
|
||||
N3 DECODED
|
||||
N4 DOMAIN
|
||||
Program/Materializer/Execution
|
||||
backend MySQL/SQLite/Oracle/RocksDB/ClickHouse
|
||||
```
|
||||
|
||||
Ne pas créer un faux repository CRUD « exemple » sur une table générique seulement pour démontrer le driver.
|
||||
|
||||
La preuve PostgreSQL de `0.3.2` porte sur la **fondation runtime/migrations**, pas sur une pseudo-entité temporaire qui deviendrait de la dette.
|
||||
|
||||
---
|
||||
|
||||
## 9. Contraintes sécurité/API/architecture spécifiques
|
||||
|
||||
### 9.1 Secrets et diagnostics
|
||||
|
||||
Aucune surface `Debug`, erreur publique, log ou snapshot ne doit révéler :
|
||||
|
||||
```text
|
||||
URI PostgreSQL complète
|
||||
password
|
||||
userinfo
|
||||
secret placeholder résolu
|
||||
TLS private material
|
||||
SQL parameter sensible
|
||||
contenu brut d'une erreur distante pouvant reproduire une valeur secrète
|
||||
```
|
||||
|
||||
Les erreurs KSP utilisent le contrat Core et un contexte sûr, stable et borné.
|
||||
|
||||
### 9.2 SQL et migrations
|
||||
|
||||
```text
|
||||
requêtes statiques ou paramètres bindés
|
||||
aucune interpolation de valeurs métier dans SQL
|
||||
identifiants physiques non contrôlés par un input utilisateur
|
||||
migrations embarquées/possédées par le backend
|
||||
concurrence de migration sérialisée explicitement
|
||||
checksum mismatch = erreur, jamais réécriture silencieuse
|
||||
```
|
||||
|
||||
### 9.3 Runtime async
|
||||
|
||||
```text
|
||||
async-first
|
||||
aucun runtime global Store imposé
|
||||
aucun spawn orphelin
|
||||
shutdown borné
|
||||
connection-driving futures correctement possédées
|
||||
aucun mutex sync gardé à travers await
|
||||
```
|
||||
|
||||
### 9.4 Logging
|
||||
|
||||
Si `ksp-store-lib` ou `ksp-store-postgres-lib` émettent des événements/spans runtime :
|
||||
|
||||
```text
|
||||
utiliser ksp-logging-lib
|
||||
pas de tracing direct hors façade KSP
|
||||
ajouter constants.rs avec TRACING_TARGET selon les règles KSP
|
||||
aucun credential/URI/SQL parameter dans les champs
|
||||
```
|
||||
|
||||
Une crate qui n'émet aucun log n'ajoute pas Logging artificiellement.
|
||||
|
||||
### 9.5 Backend features
|
||||
|
||||
Le minimum à valider est :
|
||||
|
||||
```text
|
||||
cargo check -p ksp-store-lib
|
||||
cargo check -p ksp-store-lib --no-default-features
|
||||
cargo tree -p ksp-store-lib --edges normal
|
||||
cargo tree -p ksp-store-lib -e features
|
||||
cargo tree -p ksp-store-postgres-lib --edges normal
|
||||
```
|
||||
|
||||
`--no-default-features` doit produire un runtime Store sans backend disponible mais compilable ; tenter d'ouvrir `postgres` dans cet état doit produire l'erreur explicite retenue, pas un panic ni un fallback.
|
||||
|
||||
---
|
||||
|
||||
## 10. Première mission `0.3.2-pre.001`
|
||||
|
||||
`pre.001` ne code pas le runtime lourd. Il doit produire un dossier de décision exploitable.
|
||||
|
||||
### 10.1 Vérifier la base réelle
|
||||
|
||||
Inventorier :
|
||||
|
||||
```text
|
||||
workspace members
|
||||
workspace dependencies
|
||||
ksp-store-api exact
|
||||
ksp-config-lib registry/adapters
|
||||
Config Desk/resource packaging
|
||||
Logging ownership
|
||||
architecture Store
|
||||
roadmap 0.3.2/0.3.3/0.3.4
|
||||
```
|
||||
|
||||
### 10.2 Réauditer l'héritage kbot3 ciblé
|
||||
|
||||
Relire au minimum dans l'archive historique :
|
||||
|
||||
```text
|
||||
ks-store/Cargo.toml
|
||||
ks-store/src/store.rs
|
||||
ks-store/src/postgres/**
|
||||
ks-store/migrations/postgres/**
|
||||
config/store.config.json
|
||||
config/schemas/store.config.schema.json
|
||||
ks-config/src/store.rs
|
||||
docs/architecture/STORAGE_ARCHITECTURE.md
|
||||
docs/guides/POSTGRES_STORAGE.md
|
||||
```
|
||||
|
||||
Classer sous :
|
||||
|
||||
```text
|
||||
REPRENDRE
|
||||
REDESSINER
|
||||
REPORTER
|
||||
REJETER
|
||||
```
|
||||
|
||||
Porter l'attention sur :
|
||||
|
||||
```text
|
||||
open options
|
||||
pool/lifecycle
|
||||
TLS
|
||||
migrations/schema version/checksum
|
||||
locking
|
||||
health/readiness
|
||||
redaction/error mapping
|
||||
Config ownership
|
||||
maintenance
|
||||
SQL naming
|
||||
```
|
||||
|
||||
### 10.3 Réauditer PostgreSQL et dependencies actuelles
|
||||
|
||||
Vérifier :
|
||||
|
||||
```text
|
||||
PostgreSQL stable/current support policy
|
||||
tokio-postgres version/features/MSRV
|
||||
Tokio features réellement nécessaires
|
||||
pool candidates
|
||||
TLS connector candidates
|
||||
migration helper candidates si utile
|
||||
licences
|
||||
versions transitives/doublons
|
||||
```
|
||||
|
||||
Ne pas décider un pool ou TLS connector uniquement parce qu'il est populaire.
|
||||
|
||||
### 10.4 Produire le design de fondation
|
||||
|
||||
Le gate doit proposer puis figer :
|
||||
|
||||
```text
|
||||
graphe Cargo exact
|
||||
features exactes de ksp-store-lib
|
||||
StoreSettings / backend identity
|
||||
Store open/close lifecycle
|
||||
backend dispatch
|
||||
known-but-not-compiled error
|
||||
Postgres backend construction
|
||||
pool/lifecycle
|
||||
TLS policy
|
||||
migration/bootstrap architecture
|
||||
Config std.store shape
|
||||
redaction/error codes
|
||||
real PostgreSQL test strategy
|
||||
```
|
||||
|
||||
### 10.5 Threat model
|
||||
|
||||
Couvrir au minimum :
|
||||
|
||||
```text
|
||||
credential leak URI/Debug/error/log
|
||||
implicit PG* / .pgpass bypassing Config
|
||||
malicious/invalid connection string
|
||||
connection storm / unbounded pool
|
||||
hung connect / migration / shutdown
|
||||
concurrent migration runners
|
||||
modified historical migration
|
||||
partial migration
|
||||
SQL injection / dynamic identifier injection
|
||||
backend feature/config mismatch
|
||||
connection task dropped/leaked
|
||||
schema incompatible/newer than runtime
|
||||
PostgreSQL server error echoing values
|
||||
```
|
||||
|
||||
### 10.6 Sizing
|
||||
|
||||
Le gate doit vérifier que `0.3.2` reste clôturable dans une session avec **fondation uniquement**.
|
||||
|
||||
Si pooling + TLS + Config + migrations + integration réelle dépassent encore la capacité raisonnable d'une session, redécouper **avant** l'implémentation lourde. Ne jamais absorber `RawTransaction` pour « rentabiliser » la release.
|
||||
|
||||
### 10.7 Critères de sortie de `pre.001`
|
||||
|
||||
`pre.001` est terminé seulement si :
|
||||
|
||||
```text
|
||||
sources obligatoires lues
|
||||
base stable vérifiée
|
||||
audit kbot3 ciblé documenté
|
||||
audit PostgreSQL/tokio-postgres actuel documenté
|
||||
pool/TLS/migrations questions tranchées ou explicitement réservées à une tranche précise
|
||||
graphe Cargo exact proposé
|
||||
Config shape candidate bornée
|
||||
threat model complet
|
||||
stratégie de PostgreSQL integration test définie
|
||||
plan 023 créé
|
||||
validation 019 créée
|
||||
prévision souple recalibrée
|
||||
aucun RawTransaction/RawAccountState PostgreSQL tiré dans 0.3.2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Prévision souple initiale des prereleases
|
||||
|
||||
Cette prévision est volontairement fine. `pre.001` peut la scinder/réordonner si l'audit le justifie.
|
||||
|
||||
### `pre.001` — Audit, threat model, dependencies et sizing
|
||||
|
||||
Lecture complète, audit kbot3 ciblé, audit PostgreSQL/tokio-postgres/pool/TLS/migrations, design Config/runtime/backend, graphe exact, tests et plan.
|
||||
|
||||
### `pre.002` — Scaffold des deux crates + feature graph
|
||||
|
||||
Créer `ksp-store-lib` et `ksp-store-postgres-lib`, manifests, modules privés minimaux, dépendances retenues, feature `postgres` par défaut, compilation `--no-default-features`, canaris de direction de dépendances. Pas encore de connexion réelle lourde.
|
||||
|
||||
### `pre.003` — Store settings + backend selection/lifecycle contract
|
||||
|
||||
Matérialiser les settings backend-neutral, identité backend, erreurs stable known/not-compiled, façade `Store` minimale et reexports API utiles. Aucun SQL métier.
|
||||
|
||||
### `pre.004` — Config `std.store`
|
||||
|
||||
Ajouter document/schema/example/registry/adaptor Config, secrets/provenance/redaction et impacts de packaging strictement nécessaires. Store/backend restent incapables de lire l'environnement.
|
||||
|
||||
### `pre.005` — PostgreSQL connection + pool + TLS
|
||||
|
||||
Implémenter la construction backend PostgreSQL, connect/open/close, pool retenu, timeouts et TLS retenu, avec tests déterministes sans table RAW métier.
|
||||
|
||||
### `pre.006` — Migration/bootstrap foundation
|
||||
|
||||
Implémenter ownership des migrations, version/checksum, serialization/locking, transaction/recovery et introspection minimale. Une table/namespace interne de migration est autorisée ; aucune table `RawTransaction`/`RawAccountState`.
|
||||
|
||||
### `pre.007` — Composition façade/backend + diagnostics/health si retenu
|
||||
|
||||
Fermer l'ouverture end-to-end `StoreSettings -> Store -> backend`, shutdown, error mapping, snapshots/health portable seulement si le gate `pre.001` l'a justifié, et feature mismatch.
|
||||
|
||||
### `pre.008` — PostgreSQL integration réelle
|
||||
|
||||
Test opt-in non destructif sur PostgreSQL réel : connexion, bootstrap initial, re-run idempotent, concurrence migration, mismatch/checksum/recovery selon stratégie retenue, close propre. Aucun test ne doit exiger une table RAW métier.
|
||||
|
||||
### `pre.009` — Hardening, completeness et dependency matrix
|
||||
|
||||
Inputs hostiles, redaction, no-env, no-SQL-leak, exact exports/modules, `--no-default-features`, external backend compatibility, graphes/features Cargo et non-régression de `ksp-store-api`.
|
||||
|
||||
### `pre.010` — Gate technique final
|
||||
|
||||
Workspace, tests ciblés, ownership Logging, PostgreSQL integration gate retenu et graphes Cargo. Aucun développement fonctionnel nouveau.
|
||||
|
||||
### `pre.011` — Réconciliation documentaire finale
|
||||
|
||||
README/USAGE des deux crates, plan, validation, architecture/indexes réellement impactés. Ne pas toucher `CHANGELOG.md`, `ROADMAP.md` ni au prompt suivant.
|
||||
|
||||
### `pre.012` — Préparation de publication minimale
|
||||
|
||||
Uniquement :
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
prompts/022-V0_3_3_START_PROMPT.md
|
||||
delta pre.012
|
||||
```
|
||||
|
||||
### `rel.001` — Publication stable
|
||||
|
||||
Version finale + delta uniquement.
|
||||
|
||||
---
|
||||
|
||||
## 12. Versionnement, deltas, commits et tags
|
||||
|
||||
Respecter `docs/rules/VERSION_WORKFLOW.md`.
|
||||
|
||||
Rappels :
|
||||
|
||||
```text
|
||||
workspace.package.version prérelease : 0.3.2-pre.N
|
||||
livraison : 0.3.2-pre.NNN
|
||||
fix de code/runtime : Cargo 0.3.2-pre.N.fix.M
|
||||
fix doc-only : version Cargo inchangée
|
||||
chaque delta commité à partir de 0.1.x
|
||||
aucun tag prerelease requis
|
||||
tag stable final : v0.3.2
|
||||
```
|
||||
|
||||
Chaque delta contient :
|
||||
|
||||
```text
|
||||
base requise
|
||||
objectif
|
||||
fichiers ajoutés/modifiés/supprimés
|
||||
validations exécutées
|
||||
validations non exécutées
|
||||
décisions
|
||||
questions ouvertes
|
||||
```
|
||||
|
||||
Une commande non exécutée n'est jamais déclarée PASS.
|
||||
|
||||
---
|
||||
|
||||
## 13. Procédure d'application et validation opérateur
|
||||
|
||||
Après chaque overlay :
|
||||
|
||||
```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.2
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Puis tests ciblés selon la tranche, typiquement :
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Lorsque le graphe/features change :
|
||||
|
||||
```bash
|
||||
cargo check -p ksp-store-lib --no-default-features
|
||||
cargo tree -p ksp-store-lib --edges normal
|
||||
cargo tree -p ksp-store-lib -e features
|
||||
cargo tree -p ksp-store-postgres-lib --edges normal
|
||||
cargo tree --duplicates
|
||||
```
|
||||
|
||||
Le gate technique final inclut `cargo test --workspace`.
|
||||
|
||||
Ne pas refaire systématiquement les builds Tauri à chaque tranche. Les exécuter uniquement si les resources/configs desktop ou le packaging réellement touché le justifient, et lors d'un gate final où cette preuve est pertinente.
|
||||
|
||||
---
|
||||
|
||||
## 14. Validations PostgreSQL spécifiques
|
||||
|
||||
La release doit disposer avant fermeture d'un test PostgreSQL réel, opt-in et sûr.
|
||||
|
||||
Le design exact appartient à `pre.001`, mais les invariants sont :
|
||||
|
||||
```text
|
||||
aucun credential commité
|
||||
aucune lecture directe env par Store/backend
|
||||
input opérateur explicite ou fixture locale dédiée
|
||||
aucune destruction d'une base/schema non créé par le test
|
||||
cleanup best-effort borné
|
||||
bootstrap initial prouvé
|
||||
second bootstrap idempotent prouvé
|
||||
concurrence de bootstrap/migration prouvée
|
||||
failure/mismatch safe selon stratégie retenue
|
||||
close/shutdown prouvé
|
||||
```
|
||||
|
||||
Si le test utilise stdin comme les smokes credentials KSP existants, ne jamais afficher la valeur fournie.
|
||||
|
||||
Aucune connexion live n'est exigée pour les prereleases purement documentaires.
|
||||
|
||||
---
|
||||
|
||||
## 15. Critères de clôture de `0.3.2`
|
||||
|
||||
La release stable est prête seulement si :
|
||||
|
||||
```text
|
||||
ksp-store-lib existe et dépend de ksp-store-api
|
||||
ksp-store-postgres-lib existe et dépend de ksp-store-api
|
||||
ksp-store-postgres-lib ne dépend pas de ksp-store-lib
|
||||
feature postgres de ksp-store-lib activée par défaut
|
||||
--no-default-features compile
|
||||
backend postgres connu mais non compilé est rejeté explicitement
|
||||
StoreSettings ne dépend pas de Config
|
||||
ksp-config-lib possède std.store + schema/example/adaptor retenus
|
||||
Store/backend ne lisent aucun env/.env/PG*/.pgpass
|
||||
connexion/pool/TLS PostgreSQL sont bornés et redacted
|
||||
migrations/bootstrap privés sont versionnés et concurrency-safe
|
||||
aucune table RAW métier n'est ajoutée
|
||||
aucune capability RawTransaction n'est implémentée par PostgreSQL
|
||||
aucune capability RawAccountState n'est implémentée par PostgreSQL
|
||||
aucune policy batch/backlog n'entre dans Store
|
||||
aucun type PostgreSQL/SQL/pool ne fuit dans la façade publique
|
||||
ksp-store-api reste compatible et sans dépendance backend
|
||||
README/USAGE des deux crates sont durables
|
||||
PostgreSQL integration réelle est verte
|
||||
workspace/clippy/tests/graphes sont verts
|
||||
prompt 0.3.3 réserve clairement la vertical slice RawTransaction
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 16. Release suivante et instruction d'ouverture
|
||||
|
||||
La release suivante envisagée est :
|
||||
|
||||
```text
|
||||
0.3.3 — Store/PostgreSQL RawTransaction vertical slice
|
||||
```
|
||||
|
||||
Elle doit réutiliser les **mêmes** :
|
||||
|
||||
```text
|
||||
ksp-store-lib
|
||||
ksp-store-postgres-lib
|
||||
Store settings
|
||||
backend dispatch
|
||||
pool/TLS
|
||||
migration engine
|
||||
```
|
||||
|
||||
et ajouter seulement la conformance PostgreSQL `RawTransaction`/observation/query/rétention définie par `ksp-store-api`.
|
||||
|
||||
`0.3.4` restera propriétaire de `RawAccountState` + complétude RAW.
|
||||
|
||||
### Instruction d'ouverture
|
||||
|
||||
À réception de la base stable `v0.3.1` et de l'archive historique requise :
|
||||
|
||||
1. vérifier la base exacte ;
|
||||
2. lire les règles/architecture/plan/validation dans l'ordre indiqué ;
|
||||
3. réauditer les versions et sources PostgreSQL/tokio-postgres actuelles ;
|
||||
4. réauditer kbot3 uniquement sur la fondation physique pertinente ;
|
||||
5. produire brainstorming, threat model, graphe Cargo, décisions pool/TLS/migrations/Config et sizing ;
|
||||
6. créer le plan `023` et la validation `019` ;
|
||||
7. **ne pas commencer l'implémentation lourde avant validation cohérente du gate `pre.001`** ;
|
||||
8. **ne pas implémenter RawTransaction ou RawAccountState PostgreSQL dans `0.3.2`**.
|
||||
Reference in New Issue
Block a user