diff --git a/Cargo.toml b/Cargo.toml index 7bdd54a..b2df8f9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 329 +# version: 330 [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.9" +version = "0.3.1-pre.10" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.3.1/pre.010.md b/deltas/0.3.1/pre.010.md new file mode 100644 index 0000000..25f2220 --- /dev/null +++ b/deltas/0.3.1/pre.010.md @@ -0,0 +1,135 @@ + + + +# Delta `0.3.1-pre.010` — Redécoupage documentaire des slices Store/PostgreSQL + +## Base requise + +```text +0.3.1-pre.009 +``` + +Le gate opérateur ciblé de `pre.009` est propre : audits Rust/Markdown, `cargo check --workspace`, Clippy et `cargo test -p ksp-store-api` passent. Le gate lourd `pre.008`, reconstruit après `cargo clean`, reste la preuve technique de référence pour le workspace et les bundles Tauri. + +## Objectif + +Réduire avant publication le scope de la future implémentation Store/PostgreSQL afin que chaque release concrète reste clôturable dans une session sans sacrifier migrations, concurrence, atomicité, idempotence ou validation PostgreSQL réelle. + +La décision opérateur est : + +```text +ksp-store-lib et ksp-store-postgres-lib restent développées ensemble +mais l'ancien scope unique 0.3.2 est découpé en trois releases +``` + +Nouvelle trajectoire : + +```text +0.3.2 fondation runtime/backend PostgreSQL +0.3.3 vertical slice PostgreSQL RawTransaction complète +0.3.4 vertical slice PostgreSQL RawAccountState + complétude Store RAW +0.3.5 Interface events/acquisitions partagés si consumer réel +0.3.6 ksp-job-api + premier backfill RAW +0.3.7 application backfill/inspection RAW +``` + +## Fichiers ajoutés + +```text +deltas/0.3.1/pre.010.md +``` + +## Fichiers modifiés + +```text +Cargo.toml +docs/architecture/004-COMPONENT_INVENTORY.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 +``` + +## Fichiers supprimés + +Aucun. + +## Décisions figées + +- `workspace.package.version` passe à `0.3.1-pre.10` : nouvelle prerelease non-fix, même si la tranche est documentaire. +- `ksp-store-lib` et `ksp-store-postgres-lib` ne sont **jamais** séparées en deux releases où l'une existerait sans l'autre ; elles avancent de pair sur `0.3.2`, `0.3.3` et `0.3.4`. +- `0.3.2` est limité à la fondation runtime/backend : crates, features, Config `std.store`, sélection backend, erreur backend connu non compilé, connexion/TLS/pooling à auditer, migrations/bootstrap privés, health/readiness portable si le gate `pre.001` le confirme. +- `0.3.2` n'implémente pas artificiellement les capabilities `RawTransaction` ou `RawAccountState` uniquement pour augmenter le scope. +- `0.3.3` implémente la conformance PostgreSQL complète de `RawTransaction` : observation, get/list cursorisé, atomicité RAW + observation, idempotence/conflit, rétention/tombstone/force-rehydrate et races/rollback réels. +- `0.3.4` implémente `RawAccountState` + observation, puis la complétude/conformance cross-family, les migrations/indexes finaux et le gate PostgreSQL réel final de la couche RAW. +- La pagination Store reste une primitive de navigation/cursorisation ; batch-size, priorité et policy appartiennent aux workers/jobs/executors. Une limitation physique backend peut être reflétée sans devenir un plafond métier global imposé par Store. +- Les anciennes étapes Interface/backfill/app sont renumérotées `0.3.5`, `0.3.6`, `0.3.7`. +- La préparation de publication minimale est décalée de `pre.010` à `pre.011` afin de ne pas mélanger cette correction de trajectoire avec `CHANGELOG.md`, `ROADMAP.md` et le prompt `0.3.2`. +- `ROADMAP.md`, `CHANGELOG.md` et `prompts/021-V0_3_2_START_PROMPT.md` restent donc inchangés dans `pre.010`; ils seront réconciliés uniquement dans `pre.011` conformément à `PROMPT_STRUCTURE.md`. + +## Pourquoi trois slices + +L'ancien `0.3.2` cumulait au minimum : + +```text +création de deux crates +feature/backend dispatch +Config et secrets +connexion/pool/TLS PostgreSQL +migrations/bootstrap +RawTransaction +RawAccountState +queries/pagination +atomicité/idempotence/races +rétention/tombstones/rehydration +health/readiness +validation PostgreSQL réelle +``` + +Deux slices auraient encore concentré la fondation runtime/backend et une famille RAW lourde dans la même session. Trois slices réduisent le risque de saturation tout en conservant une progression architecturale cohérente et testable. + +## Validations exécutées pendant la génération + +```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 (186 table(s), 136 file(s)) +``` + +Les tableaux touchés ont été réalignés selon le format RustRover attendu par l'audit Markdown. + +## Validations non exécutées pendant la génération + +L'environnement de génération ne dispose pas de la toolchain Cargo/Rust utilisée par l'opérateur ; aucun `cargo check`, Clippy ou test Cargo n'est revendiqué pour cette archive. + +Aucun code Rust, manifest de crate, schema Config, migration ou runtime n'est modifié dans cette tranche. + +## Gate opérateur 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.1 +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-store-api +``` + +Le gate lourd workspace/Tauri n'a pas besoin d'être rejoué pour cette tranche documentaire si ce gate ciblé reste vert. + +## Suite + +Si `pre.010` est propre, `pre.011` est la préparation de publication minimale : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompts/021-V0_3_2_START_PROMPT.md +deltas/0.3.1/pre.011.md +``` + +Le prompt `0.3.2` devra être strictement dimensionné sur la **fondation runtime/backend PostgreSQL** et annoncer explicitement `0.3.3`/`0.3.4` comme slices suivantes, sans commencer leur implémentation. diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index 8780a44..7082b05 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -37,11 +37,11 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse | Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles | | Program extension | `ksp-program--lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` | | Store API | `ksp-store-api` | API | Retenu | `0.3.1` | RAW transaction/account, observations, queries, outcomes, rétention et capabilities backend | -| Store runtime | `ksp-store-lib` | lib | Retenu | `0.3.2` | façade Store commune, dispatch par features/config | -| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Retenu | `0.3.2` | backend PostgreSQL officiel par défaut, privé derrière Store | -| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.4` | lifecycle des jobs terminables | -| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.4` | acquisition historique vers RAW via `ksp-store-lib` | -| Backfill Desk | nom à fixer | app | Retenu | `0.3.5` | contrôle/inspection du backfill RAW | +| Store runtime | `ksp-store-lib` | lib | Retenu | `0.3.2`–`0.3.4` | fondation puis conformance RAW par slices, dispatch features/config | +| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Retenu | `0.3.2`–`0.3.4` | fondation, RawTransaction puis RawAccountState/complétude | +| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.6` | lifecycle des jobs terminables | +| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.6` | acquisition historique vers RAW via `ksp-store-lib` | +| Backfill Desk | nom à fixer | app | Retenu | `0.3.7` | contrôle/inspection du backfill RAW | | Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus | | RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW | | CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE | diff --git a/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md b/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md index b176aa9..469345a 100644 --- a/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md +++ b/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md @@ -1,5 +1,5 @@ - + # Acquisition, workers, jobs et pipelines spécialisés @@ -262,7 +262,7 @@ status progress ``` -Les types exacts sont décidés à `0.3.4` avec le premier vrai backfill. +Les types exacts sont décidés à `0.3.6` avec le premier vrai backfill, après clôture des trois slices Store/PostgreSQL `0.3.2`–`0.3.4` et de la tranche Interface `0.3.5`. Aucune `ksp-job-control-lib` n'est créée sans duplication concrète. diff --git a/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md b/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md index 78c1c01..5e3ef6f 100644 --- a/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md +++ b/docs/plans/022-V0_3_1_STORE_RAW_PLAN.md @@ -1,5 +1,5 @@ - + # Plan `0.3.1` — Store API RAW foundation @@ -32,15 +32,20 @@ Après application de `pre.001`, la version Cargo cible est : Le brainstorming de `pre.001` a séparé la création de l'API Store de son implémentation PostgreSQL. -La trajectoire devient : +La trajectoire devient d'abord : ```text 0.3.1 = ksp-store-api uniquement -0.3.2 = ksp-store-lib + ksp-store-postgres-lib +0.3.2 = ouverture conjointe ksp-store-lib + ksp-store-postgres-lib + fondation runtime/backend PostgreSQL uniquement feature postgres par défaut PostgreSQL de référence via tokio-postgres +0.3.3 = même paire de crates / persistence PostgreSQL RawTransaction complète +0.3.4 = même paire de crates / RawAccountState + complétude Store RAW ``` +Le redécoupage `pre.010` conserve donc les deux crates Store/PostgreSQL **ensemble à chaque release**, mais sépare la charge en trois slices. Il évite de cumuler dans une seule session création de façade, Config, connexions/migrations, persistence transaction, rétention et persistence account. + Cette décision remplace pour `0.3.1` la mission combinée `ksp-store-api + ksp-store-lib` décrite dans le prompt de démarrage. `pre.001-fix.001` réconcilie immédiatement le `ROADMAP.md` afin que la trajectoire globale ne conserve pas une séquence désormais fausse. Conséquences immédiates : @@ -56,9 +61,9 @@ aucun std.store aucun ksp-store-lib ``` -`0.3.1` doit stabiliser le contrat logique suffisamment pour que `0.3.2` puisse ensuite demander : +`0.3.1` doit stabiliser le contrat logique suffisamment pour que la série `0.3.2`–`0.3.4` puisse ensuite demander : -> quelle représentation PostgreSQL satisfait le mieux ce contrat ? +> quelle représentation PostgreSQL satisfait le mieux ce contrat, puis comment l'implémenter famille par famille sans réduire le contrat API ? et non : @@ -80,7 +85,7 @@ contrats/capabilities backend extensibles cycle de rétention logique du RAW et tombstones anti-rebackfill ``` -Le health/readiness runtime et un éventuel type canonique dédié de wake-up ne sont finalement pas matérialisés dans `0.3.1`. Les références durables de l'API suffisent pour la foundation RAW ; le health appartient à la façade runtime `ksp-store-lib` de `0.3.2`, tandis qu'un contrat de notification dédié ne sera ajouté que lorsqu'un consumer/publisher réel en aura besoin conformément aux règles KSP-NOTIFY. +Le health/readiness runtime et un éventuel type canonique dédié de wake-up ne sont finalement pas matérialisés dans `0.3.1`. Les références durables de l'API suffisent pour la foundation RAW ; le health appartient à la façade runtime `ksp-store-lib` et peut être cadré dès la fondation `0.3.2`, tandis qu'un contrat de notification dédié ne sera ajouté que lorsqu'un consumer/publisher réel en aura besoin conformément aux règles KSP-NOTIFY. La release doit aussi auditer les autres données on-chain réellement utiles afin de distinguer explicitement : @@ -91,7 +96,7 @@ modèle event-only non persisté DTO Transport seulement ``` -La façade runtime concrète `Store`, la sélection d'un backend compilé et l'orchestration commune appartiendront à `ksp-store-lib` en `0.3.2`. Les consumers ordinaires jobs/workers/apps dépendront alors uniquement de `ksp-store-lib`, qui réexportera la surface commune nécessaire de `ksp-store-api`. +La façade runtime concrète `Store`, la sélection d'un backend compilé et l'orchestration commune appartiendront à `ksp-store-lib` à partir de `0.3.2`. Les consumers ordinaires jobs/workers/apps dépendront alors uniquement de `ksp-store-lib`, qui réexportera la surface commune nécessaire de `ksp-store-api`. `0.3.3` et `0.3.4` complèteront cette même façade et le même backend PostgreSQL sans introduire une seconde architecture. `ksp-store-api` ne devient pas propriétaire de tous les messages inter-crates. Un modèle passif partagé qui ne représente aucune donnée persistée/rejouable et sert uniquement à transporter un événement entre acquisition et traitement relève préférentiellement de `ksp-interface-lib`. La frontière exacte doit être documentée avant création d'un tel type afin d'éviter deux structs concurrentes représentant le même fait. @@ -154,7 +159,7 @@ backend alternatif -X-> ksp-store-lib ### 4.2 Features de `ksp-store-lib` -`0.3.2` introduira au minimum : +La fondation `0.3.2` introduira au minimum : ```text default = [postgres] @@ -189,7 +194,7 @@ backend compilé sélectionné crate backend privée ``` -Règles fixées pour `0.3.2` et les futurs backends : +Règles fixées pour `0.3.2` puis conservées par `0.3.3`, `0.3.4` et les futurs backends : - utiliser une URI/DSN lorsque le moteur possède une forme URI naturelle (`postgresql://...`, futur `mysql://...`, etc.) ; - permettre des options typées backend-specific uniquement lorsqu'elles sont réellement nécessaires et sans `serde_json::Value` opaque comme contrat runtime ; @@ -200,7 +205,7 @@ Règles fixées pour `0.3.2` et les futurs backends : - distinguer `backend inconnu` de `backend KSP connu mais non compilé` avant tentative de connexion ; - éviter tout fallback implicite vers `PG*`, `.pgpass` ou autre source d'environnement lue directement par le driver/backend lorsque Config a déjà fourni les settings effectifs. -La forme exacte de `StoreSettings` et du document `std.store` appartient au design de `0.3.2`; `0.3.1` fixe seulement ces responsabilités et invariants. +La forme exacte de `StoreSettings` et du document `std.store` appartient au design de fondation `0.3.2`; `0.3.1` fixe seulement ces responsabilités et invariants. ### 4.4 Surface consumer @@ -792,7 +797,7 @@ Aucune promesse exactly-once distribuée n'est faite. `ksp-store-api` définit le modèle persistant et les opérations backend-agnostic qu'une implémentation doit satisfaire. `0.3.1` ne construit pas de backend, ne sélectionne aucun moteur et n'introduit pas encore la façade runtime concrète `Store`. -Le backend concret implémente des contrats publics d'extension, mais son modèle interne reste privé. En `0.3.2`, `ksp-store-lib::Store` enveloppera ces contrats et deviendra la seule façade de consommation normale des jobs/workers/apps. +Le backend concret implémente des contrats publics d'extension, mais son modèle interne reste privé. À partir de `0.3.2`, `ksp-store-lib::Store` enveloppera progressivement ces contrats et deviendra la seule façade de consommation normale des jobs/workers/apps. La conformance PostgreSQL des familles RAW est ensuite matérialisée par slices en `0.3.3` puis `0.3.4`. ### 11.2 Object-safety et async @@ -864,7 +869,7 @@ get_raw_account_observation(observation_key) record_raw_account_observation(observation) ``` -Les opérations `persist_raw_*_acquisition` signifient au contrat que le RAW et son observation réussissent atomiquement ou échouent ensemble. PostgreSQL réalisera cela avec une transaction privée en `0.3.2`; un autre backend utilisera son mécanisme natif. +Les opérations `persist_raw_*_acquisition` signifient au contrat que le RAW et son observation réussissent atomiquement ou échouent ensemble. PostgreSQL réalisera cela avec une transaction privée dans la slice `RawTransaction` `0.3.3`, puis avec le même invariant pour `RawAccountState` en `0.3.4`; un autre backend utilisera son mécanisme natif. Les opérations `record_raw_*_observation` supposent que la référence RAW ciblée existe déjà et permettent de retenir une acquisition supplémentaire sans retransmettre la donnée RAW complète. @@ -1112,9 +1117,9 @@ L'archive contient aussi les documents kbot2 historiques. Ils avaient déjà for | Concept historique | Observation kbot2/kbot3 | Décision | Application KSP | |------------------------------------------|-------------------------------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------| -| séparation façade Store / PostgreSQL | PostgreSQL et driver privés | REPRENDRE | API commune séparée ; façade + backend PostgreSQL reportés à `0.3.2` | +| séparation façade Store / PostgreSQL | PostgreSQL et driver privés | REPRENDRE | API commune séparée ; paire façade/backend ouverte en `0.3.2` puis complétée par slices `0.3.3`/`0.3.4` | | `StoreOpenOptions` / backend selection | backend + options historiques partiellement opaques | REDESSINER | Config produit les settings ; `ksp-store-lib` sélectionne un backend compilé | -| health/readiness | contrat backend-neutral présent | REPORTER | health runtime portable à cadrer dans `ksp-store-lib` `0.3.2`; aucun `StoreHealth` dans `ksp-store-api` `0.3.1` | +| health/readiness | contrat backend-neutral présent | REPORTER | health runtime portable à cadrer dans la fondation `ksp-store-lib` `0.3.2`; aucun `StoreHealth` dans Store API | | transaction canonique source-independent | HTTP/WS/gRPC convergent vers une transaction canonique | REPRENDRE | `RawTransaction` commun seulement si la source satisfait le contrat complet | | acquisition observations | transaction + account observations séparées du RAW | REPRENDRE | concept N1 central ; transaction d'abord, account prévu après matrice de compatibilité | | ancienne raw WS notification | kbot2 l'a supprimée de la baseline persistante | REPRENDRE | `logsSubscribe`/events restent event-only par défaut ; pas de table de notification brute | @@ -1353,7 +1358,7 @@ Aucun PostgreSQL live test n'appartient à `0.3.1` puisque le backend PostgreSQL | backend capabilities | `ksp-store-api` | public | `0.3.1` | implémentations externes | | `Store` facade | `ksp-store-lib` | public | `0.3.2` | point de consommation commun | | backend dispatch/settings | `ksp-store-lib` | public/privé selon contrat | `0.3.2` | features disponibles + sélection Config | -| PostgreSQL rows/pool/SQL/migrations | `ksp-store-postgres-lib` | privé/opérateur | `0.3.2` | détails physiques | +| PostgreSQL rows/pool/SQL/migrations | `ksp-store-postgres-lib` | privé/opérateur | `0.3.2` puis `0.3.3`/`0.3.4` | fondation puis schémas RAW par slice | | transport -> RAW conversion | composition/pipeline futur | privé/réutilisable | release acquisition | conversion explicite, jamais dépendance inverse | | RAW -> STRUCTURAL | future pipeline générique | hors `0.3.1` | série suivante | aucune dépendance Program | | event runtime / scheduler / analyzer | worker/analyser/runtime futur | hors Store | ultérieur | Store ne notifie pas lui-même | @@ -1435,7 +1440,15 @@ Le gate opérateur a été exécuté après `cargo clean` : audits Rust/Markdown Le plan, la validation, l'inventaire/graphe d'architecture, les dépendances des futurs consumers Store et `IDEAS.md` sont réconciliés avec la surface réellement livrée. `README.md` ne porte pas d'inventaire Store détaillé et aucun USAGE Store n'existe encore : aucune modification artificielle n'y est ajoutée. Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant n'est touché. -### `pre.010` — Préparation de publication minimale +### `pre.010` — Redécoupage documentaire des futures slices Store/PostgreSQL + +**Statut : matérialisé par `0.3.1-pre.010`.** + +Cette tranche rouvre uniquement la responsabilité documentaire de trajectoire après décision opérateur postérieure à `pre.009`. Elle découpe l'ancien `0.3.2` surdimensionné en trois releases où `ksp-store-lib` et `ksp-store-postgres-lib` progressent toujours ensemble : fondation runtime/backend, `RawTransaction`, puis `RawAccountState` + complétude. + +Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant n'est touché dans cette tranche afin de respecter la séparation des couloirs de fermeture. + +### `pre.011` — Préparation de publication minimale Uniquement : @@ -1444,10 +1457,10 @@ Cargo.toml CHANGELOG.md ROADMAP.md prompts/021-V0_3_2_START_PROMPT.md -delta pre.010 +delta pre.011 ``` -Le prompt `0.3.2` ouvre ensemble `ksp-store-lib` et `ksp-store-postgres-lib`, avec feature `postgres` par défaut et `tokio-postgres` strictement dans la crate backend. +Le prompt `0.3.2` ouvre ensemble `ksp-store-lib` et `ksp-store-postgres-lib`, mais **uniquement pour la fondation runtime/backend PostgreSQL**. Les surfaces `RawTransaction` et `RawAccountState` restent réservées respectivement à `0.3.3` et `0.3.4`. ### `rel.001` — Publication stable @@ -1461,16 +1474,18 @@ La prévision durable devient, sous réserve des gates de chaque release : ```text 0.3.1 ksp-store-api / N1 RAW + observations + lifecycle logique -0.3.2 ksp-store-lib + ksp-store-postgres-lib / PostgreSQL reference via tokio-postgres -0.3.3 ksp-interface-lib additions nécessaires aux événements/acquisitions partagés -0.3.4 ksp-job-api + premier backfill RAW concret -0.3.5 application backfill/inspection RAW +0.3.2 Store/PostgreSQL foundation / runtime, Config, connexion, migrations, health +0.3.3 Store/PostgreSQL RawTransaction / persistence + observations + query + retention +0.3.4 Store/PostgreSQL RawAccountState + complétude/conformance RAW cross-family +0.3.5 ksp-interface-lib additions nécessaires aux événements/acquisitions partagés +0.3.6 ksp-job-api + premier backfill RAW concret +0.3.7 application backfill/inspection RAW ensuite worker/service live RAW avant ouverture N2 STRUCTURAL ``` Les événements realtime non persistés et les modèles Interface peuvent être avancés ou retardés selon le premier consumer réel ; ils ne doivent pas être artificiellement absorbés par Store. -La renumérotation `0.3.1..0.3.5` issue de `pre.001-fix.001` reste valide. +Le redécoupage `pre.010` remplace la renumérotation précédente `0.3.2..0.3.5`. Les deux crates `ksp-store-lib` et `ksp-store-postgres-lib` restent développées de pair dans les trois slices `0.3.2`–`0.3.4`; seule la responsabilité fonctionnelle de chaque release est réduite. ## 25. Critères de fermeture de `0.3.1` @@ -1503,5 +1518,5 @@ health/readiness runtime et type de wake-up dédié restent explicitement hors ` aucune dépendance PostgreSQL aucune surface N2 STRUCTURAL/N3 DECODED/N4 DOMAIN implémentée workspace et graphes entièrement verts -prompt 0.3.2 cohérent avec ksp-store-lib + ksp-store-postgres-lib + tokio-postgres +prompt 0.3.2 cohérent avec la fondation conjointe ksp-store-lib + ksp-store-postgres-lib + tokio-postgres, sans absorber RawTransaction/RawAccountState ``` diff --git a/docs/validation/018-V0_3_1_STORE_RAW.md b/docs/validation/018-V0_3_1_STORE_RAW.md index 711a775..835bf1f 100644 --- a/docs/validation/018-V0_3_1_STORE_RAW.md +++ b/docs/validation/018-V0_3_1_STORE_RAW.md @@ -1,11 +1,11 @@ - + # Validation `0.3.1` — Store API RAW foundation ## 1. Objet -Cette matrice est ouverte par `0.3.1-pre.001`, corrigée par `pre.001-fix.001` puis recalibrée par `pre.001-fix.002`. Elle valide **`ksp-store-api` uniquement**. La façade/runtime commune `ksp-store-lib` et l'implémentation PostgreSQL séparée `ksp-store-postgres-lib` sont réunies dans `0.3.2`. +Cette matrice est ouverte par `0.3.1-pre.001`, corrigée par `pre.001-fix.001` puis recalibrée par `pre.001-fix.002`. Elle valide **`ksp-store-api` uniquement**. La façade/runtime commune `ksp-store-lib` et l'implémentation PostgreSQL séparée `ksp-store-postgres-lib` seront développées de pair sur trois slices : fondation `0.3.2`, `RawTransaction` `0.3.3`, puis `RawAccountState` + complétude `0.3.4`. Le scope concret N1 certain est : @@ -27,7 +27,7 @@ cycle de rétention logique + tombstone | baseline opérateur | PASS | audits/check/Clippy fournis verts ; validation tests déclarée OK | | archive kbot3 + kbot2 historique | PASS | kbot3 extraite ; `olddocs/archivekbot2` audité pour lifecycle/replay | | règles Store/API relues | PASS | règles KSP/Dependencies/Workflow prescrites relues | -| split version | PASS | `0.3.1 = Store API`, `0.3.2 = Store lib + PostgreSQL lib` | +| split version | PASS | `0.3.1 = Store API`, `0.3.2..0.3.4 = Store lib + PostgreSQL lib par slices` | | dependency graph `0.3.1` | PASS | cible Core-only | | modèle backend commun | PASS | API object/struct commune, rows backend privées | | admission multi-source | PASS | même modèle seulement si HTTP/WS/gRPC satisfont intégralement la même sémantique | @@ -46,7 +46,7 @@ cycle de rétention logique + tombstone | retention lifecycle | PASS | `Full/Compacted/Archived/Purged` redessiné backend-agnostic | | tombstone anti-rebackfill | PASS | identité/hash/slot minimal conservé après purge ; backfill forcé distinct | | notification ownership runtime | PASS | Store ne possède aucun event bus/scheduler/DB notify | -| schema/migrations PostgreSQL | REPORTÉ | responsabilité `ksp-store-postgres-lib` `0.3.2` | +| schema/migrations PostgreSQL | REPORTÉ | fondation `0.3.2`, schémas RAW complétés en `0.3.3`/`0.3.4` | | D2/N3/N4 persistence | ABSENT | hors `0.3.1` | | threat model | PASS | source mismatch, purge prématurée, stale processing, backend/event leaks couverts | | sizing | PASS | dix prereleases courtes + lanes fermeture séparées | @@ -77,7 +77,7 @@ cycle de rétention logique + tombstone | backfill normal après purge | skip distinct | `pre.006` | | force rehydrate | chemin explicite distinct, jamais fallback automatique | `pre.006` | | processing evidence | futur ledger version-aware, jamais un bool unique | boundary `pre.006/007` | -| façade runtime `Store` | reportée à `ksp-store-lib`, hors `0.3.1` | `0.3.2` | +| façade runtime `Store` | reportée à `ksp-store-lib`, hors `0.3.1` | fondation `0.3.2` | ## 4. Dependency firewall final attendu @@ -166,7 +166,7 @@ crate/test backend externe -X-> PostgreSQL ``` -`0.3.2` ajoutera ensuite la façade de consommation `ksp-store-lib`. Le backend officiel `ksp-store-postgres-lib` devra satisfaire la même suite de conformance API. +`0.3.2` ajoutera ensuite la façade de consommation `ksp-store-lib` et la fondation `ksp-store-postgres-lib`. La conformance API du backend officiel sera matérialisée par famille : `RawTransaction` en `0.3.3`, puis `RawAccountState` et la complétude cross-family en `0.3.4`. ## 8. Threat/API gates futurs @@ -397,6 +397,8 @@ Le graphe normal Store API reste strictement `ksp-store-api -> ksp-core-lib` et ### 8.7 Réconciliation `pre.009` +**PASS opérateur ciblé.** Après application de `0.3.1-pre.009`, audits Rust/Markdown, `cargo check --workspace`, Clippy et `cargo test -p ksp-store-api` passent. Aucun re-gate Tauri/workspace complet n'était requis après le gate lourd propre de `pre.008`. + La surface finale réellement retenue pour `0.3.1` est : ```text @@ -433,56 +435,88 @@ N2 STRUCTURAL / N3 DECODED / N4 DOMAIN ### Réconciliation documentaire `pre.009` -**PRÊT après audits documentaires.** Voir §8.7. Le plan, la validation, les architectures Store réellement concernées et `IDEAS.md` sont réconciliés. Aucun README/USAGE Store n'existe à maintenir actuellement ; `CHANGELOG.md`, `ROADMAP.md` et le prompt suivant restent réservés à `pre.010`. +**PASS opérateur ciblé.** Voir §8.7. Le plan, la validation, les architectures Store réellement concernées et `IDEAS.md` sont réconciliés. Aucun README/USAGE Store n'existe à maintenir actuellement. -### Préparation de publication `pre.010` +### Redécoupage documentaire `pre.010` -Doit rester limitée à : +La décision opérateur postérieure à `pre.009` sépare l'ancien scope PostgreSQL unique en trois releases afin de préserver la qualité et la clôture par session, sans séparer `ksp-store-lib` de `ksp-store-postgres-lib`. Cette responsabilité documentaire doit être fermée avant la lane de publication. + +### Préparation de publication `pre.011` + +La préparation de publication finale est décalée à `pre.011` après le redécoupage documentaire `pre.010`. Elle doit rester limitée à : ```text Cargo.toml CHANGELOG.md ROADMAP.md prompts/021-V0_3_2_START_PROMPT.md -delta pre.010 +delta pre.011 ``` -Le `ROADMAP.md` est réconcilié par `pre.001-fix.001` puis `pre.001-fix.002`; `pre.010` ne doit plus avoir à réparer la taxonomie N1/N2 ni le split backend. +`pre.011` ne doit plus réparer la taxonomie N1/N2 ni le découpage Store/PostgreSQL : ces décisions appartiennent aux tranches documentaires antérieures. -## 10. PostgreSQL reporté à `0.3.2` +## 10. PostgreSQL reporté aux slices `0.3.2`–`0.3.4` -Aucun gate PostgreSQL live n'est demandé à `0.3.1`. +Aucun gate PostgreSQL live n'est demandé à `0.3.1`. Le développement de `ksp-store-lib` et `ksp-store-postgres-lib` reste conjoint, mais l'ancien scope unique `0.3.2` est redécoupé pour préserver la qualité et la clôture par session. -Le prochain prompt devra transformer les invariants API en façade commune + backend de référence et prévoir : +### `0.3.2` — fondation runtime/backend PostgreSQL ```text ksp-store-lib - -> façade Store commune + -> façade Store commune minimale -> réexports utiles de ksp-store-api -> feature postgres par défaut -> dispatch backend selon Config -> erreur backend connu mais non compilé + -> health/readiness runtime si justifié par le gate pre.001 ksp-store-postgres-lib -> tokio-postgres - -> pool/TLS audités - -> migrations KSP-owned - -> schema conformance - -> write/read round-trip des modèles API - -> idempotence/race - -> atomic rollback - -> pagination + -> connexion/pool/TLS audités + -> bootstrap migrations KSP-owned + -> transaction primitive privée si nécessaire à la suite Config -> std.store -> URI/DSN backend lorsque naturel -> secrets ${KSP_SECRET_*} / .env owned par ksp-config-lib -> aucun vrai secret versionné +``` -sécurité - -> URI/DSN/credentials redacted - -> aucune lecture directe env/.env par Store ou backend - -> PostgreSQL réel opt-in puis gate final obligatoire +Aucune capability `RawTransaction` ou `RawAccountState` n'est implémentée artificiellement dans cette fondation uniquement pour gonfler le scope. + +### `0.3.3` — vertical slice PostgreSQL `RawTransaction` + +```text +RawTransaction + observation +write/read/get/list cursorisé +atomic RAW + observation +idempotence / AlreadyPresent / conflict +retention / tombstone / force rehydrate +rollback et races réelles +conformance ksp-store-api +``` + +### `0.3.4` — vertical slice PostgreSQL `RawAccountState` + complétude + +```text +RawAccountState + observation +write/read/get/list cursorisé +idempotence / conflict / atomic observation +conformance cross-family +migration/index hardening +backend dispatch/health final +gate PostgreSQL réel final +``` + +Règles communes aux trois slices : + +```text +URI/DSN/credentials redacted +aucune lecture directe env/.env par Store ou backend +aucun plafond métier arbitraire de pagination imposé par Store +limitations physiques backend exposées sans devenir policy executor +PostgreSQL réel opt-in pendant développement puis gate final de la slice concernée ``` ## 11. État des tranches @@ -497,6 +531,7 @@ sécurité | `pre.006` | queries/outcomes/retention/tombstone | PASS après `fix.001` | | `pre.007` | boundary/adversarial/completeness | PASS après `fix.001` | | `pre.008` | gate technique final | PASS opérateur complet | -| `pre.009` | réconciliation documentaire | PRÊT après audits documentaires | -| `pre.010` | préparation publication | À FAIRE | +| `pre.009` | réconciliation documentaire | PASS opérateur ciblé | +| `pre.010` | redécoupage documentaire futures slices | PRÊT après audits documentaires | +| `pre.011` | préparation publication | À FAIRE | | `rel.001` | stable | À FAIRE |