diff --git a/Cargo.toml b/Cargo.toml index 4babf5c..56c71b8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 93 +# version: 94 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-logging-lib"] [workspace.package] -version = "0.2.0-pre.2" +version = "0.2.0-pre.3" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index aa215cf..7db22ab 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -41,7 +41,8 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U - [/] `0.2.0` — Auditer bot3, fixer l'ordre de `0.2.x`, actualiser l'architecture et préparer `0.2.1`. - [X] `0.2.0-pre.001` — Méthode d'audit, cartographie initiale et matrice provisoire. -- [/] `0.2.0-pre.002` — Fixer l'ordre fonctionnel, la discipline de sizing, le pipeline RAW/CORE/DECODE/SPECIALIZED et préparer le prompt `0.2.1`. +- [X] `0.2.0-pre.002` — Fixer l'ordre fonctionnel, la discipline de sizing, le pipeline RAW/CORE/DECODE/SPECIALIZED et préparer le prompt `0.2.1`. +- [/] `0.2.0-pre.003` — Audit de cohérence final : corriger les règles résiduelles supersédées, compléter les fiches `0.2.1+`, préserver les TODO bot3 utiles et finaliser le prompt `0.2.1`. ### Releases fonctionnelles décidées/pressenties diff --git a/crates/ksp-app-config-desk/README.md b/crates/ksp-app-config-desk/README.md index 5a51801..217533f 100644 --- a/crates/ksp-app-config-desk/README.md +++ b/crates/ksp-app-config-desk/README.md @@ -1,5 +1,5 @@ - + # `ksp-app-config-desk` @@ -89,7 +89,7 @@ Deux audits d'intégration applicatifs complètent les audits Config/Logging exi Les artefacts frontend construits ne sont pas versionnés. `tauri.conf.json` fixe : ```text -../../builds/khadhroony-solana-project/ksp-app-config-desk/dist +../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist ``` `vite.config.ts` résout cette même destination depuis la racine de la crate, ce qui maintient `dist` hors du workspace source et l'aligne avec la stratégie `.cargo/config.toml` pour les artefacts Rust. diff --git a/crates/ksp-app-config-desk/USAGE.md b/crates/ksp-app-config-desk/USAGE.md index 9de9e2e..831ded5 100644 --- a/crates/ksp-app-config-desk/USAGE.md +++ b/crates/ksp-app-config-desk/USAGE.md @@ -1,5 +1,5 @@ - + # Utilisation de `ksp-app-config-desk` @@ -66,7 +66,7 @@ npm run build Vite construit les pages `main.html` et `splash.html` vers : ```text -../../builds/khadhroony-solana-project/ksp-app-config-desk/dist +../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist ``` Cette destination est résolue depuis la racine de la crate dans `vite.config.ts` et correspond au `frontendDist` de `tauri.conf.json`. diff --git a/crates/ksp-app-config-desk/tauri.conf.json b/crates/ksp-app-config-desk/tauri.conf.json index e103725..d35bb54 100644 --- a/crates/ksp-app-config-desk/tauri.conf.json +++ b/crates/ksp-app-config-desk/tauri.conf.json @@ -7,7 +7,7 @@ "beforeDevCommand": "npm run dev", "devUrl": "http://localhost:1430", "beforeBuildCommand": "npm run build", - "frontendDist": "../../builds/khadhroony-solana-project/ksp-app-config-desk/dist" + "frontendDist": "../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist" }, "app": { "windows": [ diff --git a/crates/ksp-app-config-desk/vite.config.ts b/crates/ksp-app-config-desk/vite.config.ts index 5a17686..e1ef4a5 100644 --- a/crates/ksp-app-config-desk/vite.config.ts +++ b/crates/ksp-app-config-desk/vite.config.ts @@ -8,7 +8,7 @@ import { defineConfig, normalizePath } from "vite"; const appRoot = fileURLToPath(new URL(".", import.meta.url)); const frontendRoot = normalizePath(resolve(appRoot, "frontend")); -const frontendDist = normalizePath(resolve(appRoot, "../../builds/khadhroony-solana-project/ksp-app-config-desk/dist")); +const frontendDist = normalizePath(resolve(appRoot, "../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist")); const devHost = process.env.TAURI_DEV_HOST; export default defineConfig({ diff --git a/deltas/0.1.4/pre.004.md b/deltas/0.1.4/pre.004.md index 69adb74..e89c7f5 100644 --- a/deltas/0.1.4/pre.004.md +++ b/deltas/0.1.4/pre.004.md @@ -1,5 +1,5 @@ - + # Delta 0.1.4-pre.004 — squelette Rust/Tauri de `ksp-app-config-desk` @@ -134,7 +134,7 @@ Le plugin tracing n'est volontairement pas déclaré dans cette tranche ; son co La destination de build est fixée dès maintenant à : ```text -../../builds/khadhroony-solana-project/ksp-app-config-desk/dist +../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist ``` `tauri.conf.json` l'utilise comme `build.frontendDist`. `vite.config.ts` utilisera la même valeur comme `build.outDir` à partir de `pre.005`. @@ -255,5 +255,5 @@ Si cette tranche est validée et commitée, `pre.005` introduira le gabarit fron - Bootstrap, Font Awesome, SimpleBar et `resize-observer-polyfill` ; - `tauri-plugin-tracing` + `@fltsci/tauri-plugin-tracing` ; - Vite strict `1430`, HMR `1431` ; -- output `../../builds/khadhroony-solana-project/ksp-app-config-desk/dist` ; +- output `../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist` ; - premier `cargo tauri dev` du shell minimal. diff --git a/deltas/0.1.4/pre.005.md b/deltas/0.1.4/pre.005.md index 5b9cbb4..3ebfc9a 100644 --- a/deltas/0.1.4/pre.005.md +++ b/deltas/0.1.4/pre.005.md @@ -1,5 +1,5 @@ - + # Delta 0.1.4-pre.005 — gabarit frontend Vite/TypeScript/SCSS et tracing Tauri @@ -167,13 +167,13 @@ Le serveur est configuré ainsi : `tauri.conf.json` possédait déjà : ```text -../../builds/khadhroony-solana-project/ksp-app-config-desk/dist +../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist ``` `vite.config.ts` part maintenant de la racine de la crate puis résout **le même chemin contractuel** : ```text -../../builds/khadhroony-solana-project/ksp-app-config-desk/dist +../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist ``` Le `root` Vite reste `frontend/`, mais l'utilisation d'un path absolu résolu depuis la crate évite que `build.outDir` ne soit accidentellement interprété relativement à `frontend/`. diff --git a/deltas/0.1.4/pre.016-fix.002.md b/deltas/0.1.4/pre.016-fix.002.md index 5d48884..32666d4 100644 --- a/deltas/0.1.4/pre.016-fix.002.md +++ b/deltas/0.1.4/pre.016-fix.002.md @@ -1,3 +1,6 @@ + + + # 0.1.4-pre.016-fix.002 ## Objet diff --git a/deltas/0.2.0/pre.003.md b/deltas/0.2.0/pre.003.md new file mode 100644 index 0000000..f1a40ed --- /dev/null +++ b/deltas/0.2.0/pre.003.md @@ -0,0 +1,210 @@ + + + +# Delta `0.2.0-pre.003` + +## Identité + +```text +release : 0.2.0 +prerelease : pre.003 +identifiant de commit attendu : v0.2.0-pre.003 +workspace.package.version : 0.2.0-pre.3 +base : 0.2.0-pre.002 +``` + +`pre.003` est la **dernière prerelease planifiée** de la release de cadrage `0.2.0`. Elle ne développe aucune capacité N2 runtime ; elle réalise l'audit de cohérence final demandé par le plan `007` avant `rel.001`. + +## Mission + +Auditer la base Git complète `0.2.0-pre.002`, éliminer les contradictions normatives/documentaires résiduelles, vérifier que les décisions bot3 utiles n'ont pas été perdues, compléter les fiches de releases `0.2.1+`, finaliser le prompt `0.2.1` et fournir une matrice de clôture durable. + +## Écarts détectés et corrigés + +### Collisions d'identifiants normatifs + +`docs/rules/RULES_KSP.md` utilisait deux fois : + +```text +KSP-TRANSPORT-001 +KSP-DATA-001 +KSP-DATA-002 +``` + +Correction : + +```text +KSP-TRANSPORT-001 reste : pas de ksp-onchain-transport-api séparée +KSP-TRANSPORT-006 devient : couverture documentaire exhaustive + warnings de statut +KSP-DATA-001/002 restent : contrats de notifications de données +KSP-FLOW-001/002 deviennent : progression RAW/CORE/DECODE/SPECIALIZED + satellites de protocole +``` + +Un audit automatique des IDs normatifs ne trouve plus de doublon après correction. + +### Replay jobs historiques encore figés + +`KSP-JOB-009` imposait encore : + +```text +ksp-job-replay-core +ksp-job-replay-generic-materialization +ksp-job-replay-domain-projection +``` + +Cette règle contredisait la progression verticale fixée par `pre.002`. + +La nouvelle règle ne fige plus de jobs DECODE/SPECIALIZED globaux. Un replay Core pourra être introduit avec CORE ; à partir de DECODE, les jobs de replay émergent avec les groupes/capacités réels et réutilisent la même logique que le processing live correspondant. + +Les entrées `IDEAS.md` basées sur `generic-materialization`, `domain-projection` et un type global `DomainProjector` sont requalifiées en conséquence. + +### Diagramme global W1–W4 encore actif + +`docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md` conservait encore : + +```text +W1 -> D1 -> W2 -> D2 -> W3 -> D3 -> W4 -> D4 +``` + +Ce schéma pouvait contredire la décision de `pre.002` en suggérant quatre workers globaux imposés. Il est remplacé par les frontières durables `D1 RAW -> D2 CORE -> D3 DECODE -> D4 SPECIALIZED`, avec workers RAW/CORE horizontaux et workers/processors DECODE/SPECIALIZED introduits need-driven par groupe vertical. + +### TODO Wallet bot3 incomplets dans KSP + +L'audit du TODO/matrice Wallet bot3 montre que KSP avait conservé Solana CLI/Base58/Phantom/Solflare mais avait trop résumé plusieurs reports utiles. + +`IDEAS.md` conserve maintenant explicitement : + +- Solflare Keystore, seulement avec format suffisamment stable/testable ; +- Backpack, après caractérisation exacte du wire Solana `Private key` ; +- Trust Wallet, après caractérisation du wire Solana exact ; +- Base app / ex-Coinbase Wallet, sans synthèse de recovery phrase ; +- distinction entre Base app et Coinbase Developer Platform. + +Ces entrées restent des idées/TODO, pas des dépendances ni engagements de `0.2.2`. + +### Fiches de release manquantes + +Le prompt d'ouverture `0.2.0` exigeait pour chaque release `0.2.1+` : + +```text +mission +périmètre +hors-périmètre +dépendances +critères de clôture +estimation souple des prereleases +``` + +`pre.002` avait fixé la séquence mais n'avait pas regroupé ces six dimensions pour chaque release. + +`docs/plans/007-V0_2_0_SERIES_PLANNING.md` contient maintenant une fiche pour `0.2.1` à `0.2.10`. + +## Spot-check HTTP Solana + +Un contrôle externe daté du **2026-08-17** a été effectué uniquement pour valider le sizing et la qualité du prompt `0.2.1` : + +- l'index officiel HTTP Solana observé contient 52 méthodes courantes ; +- la section officielle `Deprecated Methods` expose séparément 14 noms ; +- l'inventaire bot3 `ks-onchain-transport/src/standard_methods.rs` contient les 52 noms courants observés ; +- bot3 ne couvre pas ces 14 anciennes méthodes deprecated comme surface standard ; +- l'égalité des noms courants ne garantit pas un contrat équivalent, bot3 distinguant notamment typed adapters et appels raw JSON. + +Ces nombres ne deviennent pas une règle durable. `0.2.1-pre.001` doit refaire l'inventaire depuis la documentation officielle du jour et vérifier la disponibilité runtime des méthodes deprecated/obsolete avant de promettre leur support. + +## Prompt `0.2.1` + +`prompts/006-V0_2_1_START_PROMPT.md` passe en version 2 et est considéré **finalisé côté contenu** pour l'ouverture de `0.2.1` après `v0.2.0` stable. + +Il impose maintenant explicitement : + +- index HTTP courant ; +- section officielle `Deprecated Methods` séparée ; +- toute surface HTTP unstable/experimental officiellement documentée ; +- vérification de disponibilité runtime des méthodes deprecated/obsolete ; +- comparaison nom par nom avec bot3 ; +- distinction du niveau de contrat bot3 `typed` vs raw/generic ; +- gate de sizing avant implémentation lourde. + +## Matrice de clôture ajoutée + +Nouveau document : + +```text +docs/validation/002-V0_2_0_SERIES_PLANNING.md +``` + +Il trace les critères du prompt `0.2.0`, les preuves documentaires, les écarts trouvés par `pre.003`, le spot-check HTTP et les conditions permettant de passer à `rel.001`. + +## Fichiers modifiés + +```text +Cargo.toml +ROADMAP.md +docs/000-README.md +docs/IDEAS.md +docs/architecture/000-README.md +docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +docs/plans/000-README.md +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/plans/007-V0_2_0_SERIES_PLANNING.md +docs/rules/RULES_KSP.md +docs/validation/000-README.md +prompts/000-README.md +prompts/006-V0_2_1_START_PROMPT.md +``` + +## Fichiers ajoutés + +```text +docs/validation/002-V0_2_0_SERIES_PLANNING.md +deltas/0.2.0/pre.003.md +``` + +## Validation statique réalisée dans l'environnement d'échange + +- parsing TOML de `Cargo.toml` ; +- `workspace.package.version = 0.2.0-pre.3` ; +- audit d'unicité des IDs normatifs sous `docs/rules/` ; +- contrôle des en-têtes `` / versions des fichiers modifiés ; +- contrôle des fences Markdown équilibrées ; +- contrôle des liens Markdown locaux, en ignorant les exemples littéraux de syntaxe Markdown ; +- scan global des headers Markdown : un ancien delta livré `deltas/0.1.4/pre.016-fix.002.md` ne possède pas le header moderne ; il est volontairement laissé intact afin de ne pas réécrire silencieusement l'historique `0.1.4` ; +- recherche des anciennes décisions actives `replay-generic-materialization` / `replay-domain-projection` / `DomainProjector` ; +- recherche des diagrammes/contrats pouvant encore imposer mécaniquement un worker global par niveau D1–D4 ; +- comparaison ciblée avec les TODO Wallet et l'inventaire HTTP de bot3 ; +- spot-check de la documentation officielle Solana actuelle pour HTTP et Deprecated Methods. + +## Validations non exécutables dans cet environnement + +Le conteneur d'échange ne fournit ni `cargo` ni `rustc`. + +Avant commit de `pre.003`, exécuter sur le dépôt canonique : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test --workspace +``` + +Aucun build Tauri n'est requis par cette tranche documentaire : aucune application/frontend/runtime Tauri n'est modifié. + +## Commit attendu + +Après application et validations : + +```text +v0.2.0-pre.003 +``` + +Aucun tag Git stable n'est créé pour cette prerelease. + +## Suite + +Si les validations de `pre.003` sont propres, la prochaine livraison doit être : + +```text +0.2.0-rel.001 +``` + +`rel.001` doit rester minimal : version stable `0.2.0`, statuts documentaires, entrée `CHANGELOG`, delta final, validations globales, commit de release puis tag `v0.2.0`. diff --git a/docs/000-README.md b/docs/000-README.md index 6ea785d..eea6b79 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation KSP @@ -42,7 +42,8 @@ docs/ │ └── 007-V0_2_0_SERIES_PLANNING.md ├── validation/ │ ├── 000-README.md -│ └── 001-V0_1_4_CONFIG_DESKTOP.md +│ ├── 001-V0_1_4_CONFIG_DESKTOP.md +│ └── 002-V0_2_0_SERIES_PLANNING.md └── rules/ ├── FILE_CONTRACTS.md ├── PROMPT_STRUCTURE.md @@ -59,7 +60,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é ## Documents de planification -Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La session active est `0.2.0`, ouverte par [`../prompts/005-V0_2_0_START_PROMPT.md`](../prompts/005-V0_2_0_START_PROMPT.md). Son plan directeur d'audit et de découpage de série est [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), créé par `0.2.0-pre.001` puis restructuré par `0.2.0-pre.002` autour de la séquence Transport HTTP -> Wallet -> transports live -> off-chain -> Interface/Program et de l'architecture RAW -> CORE -> DECODE -> SPECIALIZED. Le prompt préparatoire de la première release fonctionnelle est [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). +Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La session active est `0.2.0`, ouverte par [`../prompts/005-V0_2_0_START_PROMPT.md`](../prompts/005-V0_2_0_START_PROMPT.md). Son plan directeur d'audit et de découpage de série est [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), créé par `0.2.0-pre.001`, restructuré par `0.2.0-pre.002` puis audité/finalisé par `0.2.0-pre.003` autour de la séquence Transport HTTP -> Wallet -> transports live -> off-chain -> Interface/Program et de l'architecture RAW -> CORE -> DECODE -> SPECIALIZED. Sa matrice de clôture est [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). Le prompt préparatoire de la première release fonctionnelle est [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). `IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales. diff --git a/docs/IDEAS.md b/docs/IDEAS.md index 1b32183..1767874 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -1,5 +1,5 @@ - + # Idées à explorer @@ -190,8 +190,12 @@ Formats/cibles à inventorier et prioriser selon usage réel : - Solana CLI keypair JSON ; - keypair Base58 complet lorsque pertinent ; -- Phantom ; -- Solflare ; +- Phantom, en privilégiant le wire Solana générique réellement documenté plutôt qu'un codec de marque inutile ; +- Solflare, y compris réévaluation du keystore protégé seulement si son format public devient suffisamment stable pour un round-trip testé ; +- Backpack : caractériser le wire Solana exact de l'import `Private key` avant tout codec/alias dédié ; +- Trust Wallet : caractériser le wire Solana exact d'import/export avant implémentation ; +- Base app / ex-Coinbase Wallet : ne jamais synthétiser une recovery phrase depuis une keypair arbitraire ; réévaluer uniquement si un import direct de keypair Solana est officiellement spécifié ; +- distinguer Coinbase Developer Platform d'un wallet utilisateur Base/Coinbase si son API d'import/export est étudiée ; - autres wallets logiciels Solana ; - hardware wallets / standards de dérivation si un besoin apparaît ; - migrations depuis formats historiques KSP/bot uniquement si utiles aux utilisateurs réels. @@ -287,9 +291,9 @@ Les processing outcomes par processor/version/capability constituent la vérité ### Jobs de replay -**Status :** Transférée vers une décision/règle +**Status :** Requalifiée par `0.2.0-pre.003` -Trois jobs distincts sont retenus : `ksp-job-replay-core`, `ksp-job-replay-generic-materialization` et `ksp-job-replay-domain-projection`. Ils réutilisent les pipelines spécialisés correspondants. +L'ancienne liste figée `ksp-job-replay-core` / `ksp-job-replay-generic-materialization` / `ksp-job-replay-domain-projection` n'est plus une décision KSP. La frontière `RAW -> CORE` pourra introduire un replay Core lorsque CORE sera ouverte. À partir de DECODE, les jobs de replay doivent émerger avec les groupes/capacités verticaux réels et réutiliser la même logique que le processing live correspondant, sans imposer un materializer/projector global à tout Solana. ### Notification backend de référence @@ -311,11 +315,11 @@ Définir le schéma SQL, la durée/renouvellement de lease et la technique Postg Fixer les noms/types exacts et distinguer Produced, NoOutput, NotApplicable, Unsupported et failure déterministe sans transformer des situations normales en erreurs. -### Contexte stateful des projectors +### Contexte stateful des projections SPECIALIZED **Status :** À explorer avec la première projection nécessitant un état existant -Le Store est interrogé par le pipeline/worker puis le contexte est injecté au `DomainProjector`. Définir comment le projector décrit les données de contexte nécessaires sans dépendre du backend. +Le Store est interrogé par la couche de composition/pipeline/worker puis le contexte est injecté dans l'implémentation de projection/materialization spécialisée concernée. Définir comment cette capacité décrit les données de contexte nécessaires sans dépendre du backend, sans imposer un type global `DomainProjector`. ### Job pause/resume diff --git a/docs/architecture/000-README.md b/docs/architecture/000-README.md index 1abc940..f2ea09f 100644 --- a/docs/architecture/000-README.md +++ b/docs/architecture/000-README.md @@ -1,5 +1,5 @@ - + # Architecture KSP @@ -26,6 +26,6 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas. 7. [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md) — policy multi-checkpoints, orchestration transactionnelle, wallet/transport, retry, approval externe et résultat d'exécution ; 8. [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) — niveaux durables D1–D4, Materialization, Store PostgreSQL de référence, provenance, idempotence, replay et notifications de données persistées ; 9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — pipelines spécialisés, workers live, jobs de backfill/replay, backlog, claim/lease, reprise, concurrence et mécanisme de notification de référence ; -10. [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md) — apps spécialisées, workers autonomes, control plane, scenarios réutilisables, demos desktop et frontières IPC/orchestration. +10. [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md) — apps spécialisées, workers autonomes et need-driven, control plane, scenarios réutilisables, demos desktop et frontières IPC/orchestration. `004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires. diff --git a/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md b/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md index c721f91..ab3d654 100644 --- a/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +++ b/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md @@ -1,5 +1,5 @@ - + # Applications, services, scenarios et control plane @@ -196,21 +196,26 @@ core-processor -X-> generic-materializer generic-materializer -X-> domain-projector ``` -Le data plane reste : +Le data plane durable reste : ```text -W1 -> D1 - | - v - W2 -> D2 - | - v - W3 -> D3 - | - v - W4 -> D4 +transport / acquisition + | + v + D1 RAW + | + v + D2 CORE + | + v + D3 DECODE + | + v + D4 SPECIALIZED ``` +Ce schéma décrit les **frontières de données**, pas quatre workers globaux imposés. RAW et CORE peuvent disposer de workers horizontaux propres à leur couche. À partir de DECODE, la granularité des workers/processors émerge des groupes fonctionnels verticaux réellement introduits ; plusieurs groupes peuvent donc posséder des lifecycle hosts distincts sans qu'un `W3` ou `W4` universel existe. + Les notifications accélèrent le réveil mais ne créent pas une connexion fonctionnelle worker-to-worker. Cette indépendance permet arrêt, restart ou mise à jour d'un worker sans arrêter volontairement les autres. diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index 9f2aab4..756f251 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -15,7 +15,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](004-V0_1_2_LOGGING_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.2`, établi par `0.1.2-pre.001` puis consolidé jusqu'à `0.1.2-rel.001`. - [`005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.3 — Configuration foundation`, établi par `0.1.3-pre.001`, exécuté jusqu'à `pre.015` puis publié par `0.1.3-rel.001`. - [`006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](006-V0_1_4_CONFIG_DESKTOP_PLAN.md) — plan historique clôturé de la release stable `0.1.4 — ksp-app-config-desk`, établi par `0.1.4-pre.001` puis consolidé jusqu'à `0.1.4-rel.001`. -- [`007-V0_2_0_SERIES_PLANNING.md`](007-V0_2_0_SERIES_PLANNING.md) — plan actif de `0.2.0`, ouvert par `pre.001` puis consolidé par `pre.002` avec l'ordre `0.2.1+`, la stratégie RAW/CORE/DECODE/SPECIALIZED, les vertical slices Program et le prompt préparatoire `0.2.1`. +- [`007-V0_2_0_SERIES_PLANNING.md`](007-V0_2_0_SERIES_PLANNING.md) — plan actif de `0.2.0`, ouvert par `pre.001`, consolidé par `pre.002` puis finalisé/audité par `pre.003` avec l'ordre `0.2.1+`, la stratégie RAW/CORE/DECODE/SPECIALIZED, les vertical slices Program, les fiches de release et le prompt finalisé `0.2.1`. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md index 3e25c5b..720855a 100644 --- a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +++ b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md @@ -1,5 +1,5 @@ - + # Séquence des releases fonctionnelles KSP @@ -351,7 +351,7 @@ Par défaut : # Série `0.2.x` — accès Solana, Wallet et contrats initiaux -`0.2.0` reste la release de cadrage. `0.2.0-pre.002` fixe maintenant le début de la séquence fonctionnelle suivante : +`0.2.0` reste la release de cadrage. `0.2.0-pre.002` a fixé le début de la séquence fonctionnelle suivante et `0.2.0-pre.003` en réalise l'audit final de cohérence avant publication stable : ```text 0.2.1 on-chain transport HTTP foundation @@ -546,10 +546,10 @@ Les releases `0.1.1` à `0.1.4` sont stables et leurs plans/prompts restent hist prompts/005-V0_2_0_START_PROMPT.md ``` -`0.2.0-pre.001` a construit la première cartographie. `0.2.0-pre.002` fixe la trajectoire ci-dessus et prépare : +`0.2.0-pre.001` a construit la première cartographie. `0.2.0-pre.002` a fixé la trajectoire ci-dessus. `0.2.0-pre.003` corrige les décisions résiduelles supersédées, complète les fiches de release et finalise : ```text prompts/006-V0_2_1_START_PROMPT.md ``` -Le prompt `0.2.1` reste un brouillon vivant jusqu'à la publication stable de `v0.2.0`. +Le prompt `0.2.1` est finalisé côté contenu par `0.2.0-pre.003`; il ne devient applicable qu'après publication stable de `v0.2.0`. diff --git a/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md b/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md index 4c4b5e3..69c371f 100644 --- a/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md +++ b/docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md @@ -1,5 +1,5 @@ - + # Plan `0.1.4` — `ksp-app-config-desk` @@ -228,7 +228,7 @@ Le layout frontend reprend la convention éprouvée de bot3 : les sources web so Les artefacts frontend construits doivent être séparés des sources. Pour `ksp-app-config-desk`, la destination contractuelle est fixée à : ```text -../../builds/khadhroony-solana-project/ksp-app-config-desk/dist +../../../builds/khadhroony-solana-project/ksp-app-config-desk/dist ``` Cette valeur est utilisée par `build.frontendDist` dans `tauri.conf.json`. `vite.config.ts` utilise la même destination comme `build.outDir` depuis son introduction en `pre.005`. Elle remplace le `../dist`/`../../dist` historique du gabarit bot3. diff --git a/docs/plans/007-V0_2_0_SERIES_PLANNING.md b/docs/plans/007-V0_2_0_SERIES_PLANNING.md index 158c1c9..e6bbc74 100644 --- a/docs/plans/007-V0_2_0_SERIES_PLANNING.md +++ b/docs/plans/007-V0_2_0_SERIES_PLANNING.md @@ -1,5 +1,5 @@ - + # Plan `0.2.0` — audit bot3 et planification de la série `0.2.x` @@ -58,7 +58,7 @@ Les statuts de décision sont : `reprendre` ne signifie jamais « copier mécaniquement le code ». -## 4. Décisions de `0.2.0-pre.002` +## 4. Décisions stabilisées par `0.2.0-pre.002` / `pre.003` ### 4.1 Ordre fonctionnel initial de la série @@ -198,6 +198,113 @@ Le `pre.001` de `0.2.6` devra inventorier la surface normative Yellowstone réel Les adaptations/provider profiles plus avancés sont reportés après les fondations prioritaires. +### 4.8 Fiches de releases `0.2.1+` + +Ces fiches complètent la simple séquence numérique. Elles sont **souples** : le `pre.001` de chaque release refait le sizing sur les dépendances et documentations réellement actuelles. Une estimation ne justifie jamais d'ouvrir une release dont la clôture dans la même session paraît incertaine. + +#### `0.2.1` — HTTP Solana foundation + +- **Mission :** créer `ksp-onchain-transport-lib` avec JSON-RPC HTTP Solana complet, settings publics, pool logique d'endpoints, rôles/capabilities/limites et adapter Config -> Transport. +- **Périmètre :** index HTTP officiel courant, méthodes deprecated/obsolete encore réellement utilisables, éventuelles méthodes HTTP unstable/experimental documentées, read/write technique, timeouts, retry/backoff, health et observabilité. +- **Hors périmètre :** Wallet, WebSocket, LaserStream, gRPC, Store, Program, orchestration d'exécution. +- **Dépendances :** fondations `0.1.x`; `ksp-config-lib` peut dépendre des contrats Transport pour l'adapter, jamais l'inverse. +- **Clôture :** matrice documentaire exhaustive et testée, ownership propre, warnings de statut, pools/rôles validés, README/USAGE et prompt `0.2.2`. +- **Estimation souple :** environ 8–12 prereleases courtes **si** le gate `pre.001` confirme qu'elles restent clôturables dans une seule session ; sinon scinder avant implémentation lourde. + +#### `0.2.2` — Wallet foundation + +- **Mission :** créer `ksp-wallet-lib` et le format natif `.kspwallet`. +- **Périmètre :** création/ouverture, protection du secret, identité/pubkey, signature, changement de mot de passe, atomicité/no-clobber, import/export extensible et premiers formats réellement validés. +- **Hors périmètre :** `WalletPolicy`, wallet JSON temporaire bot2/bot3, UI Tauri, lecture de solde réseau. +- **Dépendances :** Core/Logging et primitives crypto/signature nécessaires ; aucun besoin de dépendre de Transport pour le cœur Wallet. +- **Clôture :** format documenté/testé, secret non exposé, import/export round-trip retenu, README/USAGE et prompt Wallet Desk. +- **Estimation souple :** environ 5–8 prereleases. + +#### `0.2.3` — `ksp-app-wallet-desk` + +- **Mission :** valider en Tauri Config composite + Wallet + HTTP. +- **Périmètre :** sélection/ouverture de wallet, identité/pubkey, affichage du solde réel via `getBalance`, opérations Wallet utiles à la première UI, instrumentation Logging et modèle Tauri Config Desk. +- **Hors périmètre :** WebSocket, trading, execution policy, duplication de cryptographie ou JSON-RPC dans l'app. +- **Dépendances :** `0.2.1`, `0.2.2`, Config Desk/Tauri conventions. +- **Clôture :** flux opérateur bout en bout sur un endpoint réel configurable, secrets protégés, build Tauri final exécuté en dernière opération de validation. +- **Estimation souple :** environ 5–8 prereleases. + +#### `0.2.4` — WebSocket Solana standard + +- **Mission :** ajouter la surface WebSocket Solana standard complète au transport. +- **Périmètre :** sessions persistantes, subscriptions/unsubscriptions/notifications documentées, reconnexion bornée, plusieurs sessions possibles sur une même URL, plusieurs subscriptions par session. +- **Hors périmètre :** scheduler/pool automatique complexe de sessions, Helius-specific, Yellowstone. +- **Dépendances :** `0.2.1` et contrats Transport déjà stabilisés. +- **Clôture :** matrice WS exhaustive, lifecycle/reconnect/tests réseau opt-in et warnings pour toute surface unstable/deprecated concernée. +- **Estimation souple :** environ 5–8 prereleases. + +#### `0.2.5` — Helius LaserStream WebSocket + +- **Mission :** étendre le moteur WS standard avec la surface Helius ciblée sans dupliquer le client. +- **Périmètre :** opérations/filtres/notifications/capabilities Helius documentés et réellement disponibles au moment de la release. +- **Hors périmètre :** gRPC LaserStream, autres providers, shred delivery. +- **Dépendances :** `0.2.4`. +- **Clôture :** extensions isolées du moteur commun, matrice Helius, tests opt-in selon credentials disponibles, absence de secret dans les logs. +- **Estimation souple :** environ 3–5 prereleases. + +#### `0.2.6` — Yellowstone gRPC standard foundation + +- **Mission :** introduire un client/backend Yellowstone standard et provider-neutral. +- **Périmètre :** surface normative retenue à `pre.001`, connexion/auth metadata générique, stream/subscription, filtres et lifecycle nécessaires. +- **Hors périmètre :** profils commerciaux spécifiques Helius/Triton/ERPC/Chainstack/Shyft, shred/deshred et optimisations provider-only. +- **Dépendances :** transport foundation ; aucun provider ne devient propriétaire du contrat. +- **Clôture :** matrice protocolaire, test contre au moins un endpoint réellement accessible lorsque possible, comportement provider-neutral documenté. +- **Estimation souple :** environ 4–7 prereleases, avec gate de découpage obligatoire si la surface normative courante dépasse ce qui est raisonnablement clôturable dans la session. + +#### `0.2.7` — Off-chain price transport + +- **Mission :** créer `ksp-offchain-transport-lib` sur un premier besoin réel de prix. +- **Périmètre :** abstraction de lecture de prix, premier provider, au minimum SOL/USD et SOL/EUR, erreurs/timeouts/observabilité et settings publics nécessaires. +- **Hors périmètre :** metadata HTTP/IPFS/Arweave, quotes/routing, agrégation multi-provider complexe. +- **Dépendances :** fondations Core/Logging ; indépendante du transport on-chain sauf composition applicative. +- **Clôture :** provider interchangeable derrière le contrat retenu, prix typés/testés, README/USAGE. +- **Estimation souple :** environ 3–5 prereleases. + +#### `0.2.8` — Price Desk + +- **Mission :** valider le transport off-chain dans une petite application Tauri. +- **Périmètre :** Config, sélection/refresh des paires supportées, affichage des prix et provenance/état utiles. +- **Hors périmètre :** Market Desk DEX/OHLC, trading et metadata. +- **Dépendances :** `0.2.7` + conventions Tauri stabilisées. +- **Clôture :** UI mince fonctionnelle, refresh observable, erreurs sûres et build Tauri final. +- **Estimation souple :** environ 3–5 prereleases. + +#### `0.2.9` — `ksp-interface-lib` foundation + +- **Mission :** ouvrir la façade wire officielle KSP et son API publique utilisable aussi par des crates externes. +- **Périmètre :** organisation wire, règles réexport/wrapper/réimplémentation compatible, premiers types/interfaces Solana réellement nécessaires et canaries de compatibilité. +- **Hors périmètre :** inventaire exhaustif de tous les protocoles Solana/SPL/Metaplex, Program implementations complètes. +- **Dépendances :** Core et dépendances wire externes explicitement retenues/centralisées au workspace. +- **Clôture :** API publique cohérente avec les implémentations internes, aucune dépendance métier externe inutile dans les couches supérieures, README/USAGE. +- **Estimation souple :** environ 4–7 prereleases. + +#### `0.2.10` — `ksp-program-api` foundation + +- **Mission :** introduire le contrat extensible Program avant les vertical slices réels. +- **Périmètre :** identité/capabilities, contrats de décodage et préparation d'exécution nécessaires à une implémentation externe, support/deprecation machine-readable et extension ouverte. +- **Hors périmètre :** `ksp-program-lib` exhaustif, materializers, execution engine, scénarios. +- **Dépendances :** Core + `ksp-interface-lib` lorsque les contrats wire le nécessitent. +- **Clôture :** une implémentation externe fictive/test démontre que l'API n'impose pas `ksp-program-lib`; contrats documentés et prompt de la série suivante préparé. +- **Estimation souple :** environ 3–5 prereleases. + +### 4.9 Audit final `0.2.0-pre.003` + +L'audit final de la base Git `0.2.0-pre.002` a relevé et corrige les écarts suivants avant release stable : + +- collisions d'identifiants normatifs dans `RULES_KSP.md` (`KSP-TRANSPORT-001`, `KSP-DATA-001`, `KSP-DATA-002`) ; +- ancienne règle `KSP-JOB-009` imposant encore trois jobs de replay globaux incompatibles avec la progression verticale décidée ; +- ancien diagramme `W1 -> D1 -> W2 -> D2 -> W3 -> D3 -> W4 -> D4` dans `010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`, encore susceptible d'être lu comme quatre workers globaux imposés ; il est remplacé par les frontières durables D1–D4 et une granularité worker need-driven ; +- entrées `IDEAS.md` encore formulées autour de `generic-materialization` / `domain-projection` et d'un type global `DomainProjector` ; +- TODO Wallet bot3 utiles non encore reportés explicitement : Backpack, Trust Wallet, Solflare keystore, Base app/ex-Coinbase Wallet et distinction Coinbase Developer Platform ; +- absence dans le plan directeur des fiches mission/périmètre/hors-périmètre/dépendances/clôture/estimation demandées pour chaque release `0.2.1+`. + +Un spot-check externe effectué le **2026-08-17** sur la documentation officielle Solana observe 52 méthodes dans l'index HTTP courant et 14 noms dans la section officielle Deprecated Methods. L'inventaire bot3 contient les 52 noms de l'index courant, mais pas la surface deprecated séparée. Cette observation confirme l'intérêt de réutiliser l'inventaire fonctionnel bot3 tout en imposant à `0.2.1-pre.001` un nouvel audit officiel complet ; **les nombres observés ici ne deviennent pas un contrat durable**. + ## 5. Wallet ### 5.1 `0.2.2` — format natif `.kspwallet` @@ -581,31 +688,27 @@ Il est volontairement prématuré de figer maintenant chaque numéro jusqu'aux D | Backfill | bot3 pipelines/jobs historiques | refondre | `ksp-job-api` + job concret | `0.3.3` | | Market Desk | absent comme app KSP dédiée | ajouter | app spécialisée | après DEX prioritaires | -## 17. Prévision souple des prereleases restantes de `0.2.0` +## 17. Clôture de `0.2.0` `pre.001` a ouvert la méthode et la cartographie. -`pre.002` fixe la direction fonctionnelle principale de `0.2.x`, la stratégie RAW/CORE/DECODE/SPECIALIZED, la progression verticale Program, le dimensionnement de session et prépare le prompt `0.2.1`. +`pre.002` a fixé la direction fonctionnelle principale de `0.2.x`, la stratégie RAW/CORE/DECODE/SPECIALIZED, la progression verticale Program, le dimensionnement de session et le premier prompt `0.2.1`. -La suite de `0.2.0` doit rester courte : +`pre.003` est la **dernière prerelease planifiée de `0.2.0`**. Elle réalise l'audit de cohérence final, corrige les règles résiduelles supersédées, complète les fiches de release demandées par le prompt d'ouverture, préserve les TODO bot3 utiles et finalise le prompt `0.2.1`. -### `pre.003` candidate — audit de cohérence finale +Aucune `pre.004` n'est prévue. Elle ne serait créée que si la validation de `pre.003` révélait un nouveau défaut ou une omission substantielle qui ne peut pas être honnêtement corrigée dans `rel.001`. -- relire le découpage complet `0.2.1 -> 0.3.x` ; -- vérifier qu'aucune capacité bot3 pertinente au transport/wallet/interface/program n'est perdue ; -- vérifier les dépendances et hors-périmètre ; -- corriger les incohérences documentaires restantes ; -- confirmer que `0.2.1` est suffisamment bornée. +Après validation de `pre.003`, `0.2.0-rel.001` doit rester une publication de cadrage : -### dernière prerelease candidate +- passer `workspace.package.version` à `0.2.0` ; +- marquer `0.2.0` stable dans ROADMAP/indices/plans ; +- ajouter l'entrée stable `0.2.0` au `CHANGELOG.md` ; +- créer `deltas/0.2.0/rel.001.md` ; +- exécuter les validations globales de clôture disponibles ; +- commit `v0.2.0-rel.001`, puis tag stable Git `v0.2.0` ; +- ne modifier le prompt `0.2.1` que si une validation de clôture révèle un écart réel. -- validations documentaires finales ; -- nettoyage/archivage ; -- mise à jour finale du changelog si prévue par le workflow ; -- finalisation du prompt `0.2.1` ; -- préparation de `0.2.0-rel.001`. - -Le nombre exact reste souple : ne pas créer artificiellement une prerelease vide si `pre.003` suffit pour clôturer. +La matrice de clôture durable est `docs/validation/002-V0_2_0_SERIES_PLANNING.md`. ## 18. Première release fonctionnelle décidée : `0.2.1` @@ -617,10 +720,10 @@ La première release fonctionnelle de la série est désormais : Sa mission est de fournir la première frontière réseau Solana KSP réellement exploitable par Wallet, applications futures, acquisition RAW et execution technique ultérieure. -Le prompt préparatoire est : +Le prompt finalisé est : ```text prompts/006-V0_2_1_START_PROMPT.md ``` -Il reste un brouillon vivant jusqu'à la publication stable de `0.2.0`, puis devient le prompt de reprise de `0.2.1`. +Son contenu est finalisé par `0.2.0-pre.003`. Il devient le prompt de reprise applicable dès publication/tag stable de `v0.2.0`. diff --git a/docs/rules/RULES_KSP.md b/docs/rules/RULES_KSP.md index 39976fe..25bc747 100644 --- a/docs/rules/RULES_KSP.md +++ b/docs/rules/RULES_KSP.md @@ -1,5 +1,5 @@ - + # Règles spécifiques à KSP @@ -156,7 +156,7 @@ - **KSP-JOB-006** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie. - **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie. - **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers. -- **KSP-JOB-009** — Les jobs de replay retenus sont `ksp-job-replay-core`, `ksp-job-replay-generic-materialization` et `ksp-job-replay-domain-projection`. +- **KSP-JOB-009** — Aucun inventaire global de jobs de replay DECODE/SPECIALIZED n'est figé à l'avance. `RAW -> CORE` peut introduire un job de replay Core lorsque la couche CORE est ouverte ; à partir de DECODE, les jobs de replay sont introduits avec les groupes/capacités verticaux qui en ont réellement besoin, sans imposer des jobs génériques `generic-materialization` / `domain-projection` pour tout Solana. - **KSP-JOB-010** — Les jobs de replay réutilisent exactement le pipeline spécialisé de la frontière correspondante. - **KSP-JOB-011** — Le backfill conserve un checkpoint de progression dans la source historique en plus des outcomes de persistence D1. - **KSP-JOB-012** — Replay normal/reprise et force replay sont deux intentions distinctes ; un force replay conserve provenance/historique et ne supprime pas silencieusement le résultat courant. @@ -254,6 +254,6 @@ - **KSP-REL-014** — Toute application/binaire Tauri KSP considéré comme complété possède un `USAGE.md` durable décrivant ses fenêtres, leurs objectifs, leurs flux principaux et leur utilisation opérateur. - **KSP-REL-015** — Une application Tauri complétée ne crée `PRESENTATION.md` que si elle possède réellement une vue de présentation embarquée ; dans ce cas le fichier est finalisé comme contenu UI sans liens navigables et reste distinct du `README.md` et du `USAGE.md`. - **KSP-REL-016** — Une prerelease vise environ 15 à 20 minutes de travail effectif. Le `pre.001` dimensionne aussi la release concrète entière : une release doit pouvoir être ouverte, développée, validée et clôturée dans une seule session de chat. Si cette clôture paraît incertaine, la release est scindée avant l'implémentation fonctionnelle lourde ; une version volontairement répartie sur plusieurs sessions est interdite. -- **KSP-TRANSPORT-001** — Pour une surface de transport explicitement ciblée, KSP inventorie et implémente toutes les méthodes/opérations exposées par la documentation normative retenue, sauf impossibilité technique explicitement documentée. Les opérations `deprecated`/`obsolete` encore fonctionnelles et `unstable`/`experimental` restent utilisables mais émettent un `warn` via `ksp-logging-lib` à chaque utilisation concernée ; leur statut est décrit par une metadata centralisée et non par des warnings dispersés. -- **KSP-DATA-001** — La progression durable canonique est `RAW -> CORE -> DECODE -> SPECIALIZED`. RAW et CORE ne nécessitent aucun decoder Program ; le passage RAW -> CORE reste une normalisation générique de la blockchain Solana. À partir de DECODE, KSP progresse verticalement par groupe fonctionnel à travers wire, décodage, matérialisation, projection spécialisée si utile, préparation d'exécution, policy, exécution et scénarios de validation. -- **KSP-DATA-002** — Un programme ou composant satellite nécessaire à la compréhension, la matérialisation ou l'exécution correcte d'un protocole appartient au groupe de ce protocole. Il n'est pas reporté artificiellement dans une catégorie `trading-adjacent`. +- **KSP-TRANSPORT-006** — Pour une surface de transport explicitement ciblée, KSP inventorie et implémente toutes les méthodes/opérations exposées par la documentation normative retenue, sauf impossibilité technique explicitement documentée. L'inventaire couvre aussi les sections officielles séparées `deprecated`/`obsolete` et `unstable`/`experimental` lorsqu'elles existent. Les opérations deprecated/obsolete encore réellement fonctionnelles et unstable/experimental restent utilisables mais émettent un `warn` via `ksp-logging-lib` à chaque utilisation concernée ; leur statut est décrit par une metadata centralisée et non par des warnings dispersés. +- **KSP-FLOW-001** — La progression durable canonique est `RAW -> CORE -> DECODE -> SPECIALIZED`. RAW et CORE ne nécessitent aucun decoder Program ; le passage RAW -> CORE reste une normalisation générique de la blockchain Solana. À partir de DECODE, KSP progresse verticalement par groupe fonctionnel à travers wire, décodage, matérialisation, projection spécialisée si utile, préparation d'exécution, policy, exécution et scénarios de validation. +- **KSP-FLOW-002** — Un programme ou composant satellite nécessaire à la compréhension, la matérialisation ou l'exécution correcte d'un protocole appartient au groupe de ce protocole. Il n'est pas reporté artificiellement dans une catégorie `trading-adjacent`. diff --git a/docs/validation/000-README.md b/docs/validation/000-README.md index 74725b8..db35015 100644 --- a/docs/validation/000-README.md +++ b/docs/validation/000-README.md @@ -1,5 +1,5 @@ - + # Validations KSP @@ -10,3 +10,4 @@ Les deltas restent l’historique autoritatif des livraisons ; une matrice de va Documents : - [`001-V0_1_4_CONFIG_DESKTOP.md`](001-V0_1_4_CONFIG_DESKTOP.md) — matrice finale de `0.1.4 — ksp-app-config-desk`. +- [`002-V0_2_0_SERIES_PLANNING.md`](002-V0_2_0_SERIES_PLANNING.md) — audit final de cohérence et matrice de clôture documentaire de `0.2.0`. diff --git a/docs/validation/002-V0_2_0_SERIES_PLANNING.md b/docs/validation/002-V0_2_0_SERIES_PLANNING.md new file mode 100644 index 0000000..4114815 --- /dev/null +++ b/docs/validation/002-V0_2_0_SERIES_PLANNING.md @@ -0,0 +1,173 @@ + + + +# Validation `0.2.0` — audit bot3 et planification de la série `0.2.x` + +## Objet + +Cette matrice synthétise l'audit final de `0.2.0` et vérifie que le cadrage demandé par `prompts/005-V0_2_0_START_PROMPT.md` est suffisamment complet avant publication stable. + +Elle ne remplace ni `docs/plans/007-V0_2_0_SERIES_PLANNING.md` ni les deltas `0.2.0`. + +## Base auditée + +```text +KSP : khadhroony-solana-project_v0.2.0-pre.002-full-from-git.zip +bot3 : khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +Audit final réalisé le : + +```text +2026-08-17 +``` + +## Matrice de clôture + +| Critère | Statut après `pre.003` | Preuve / décision | +|-------------------------------------------------------------------------------------------------|------------------------|----------------------------------------------------------------------------------------------------------------------| +| Méthode d'audit bot3 définie | OK | `007`, sections 1–3 | +| Cartographie Wallet / Transport / Interface / Program / scenarios | OK | `007`, matrice section 16 + architecture KSP | +| Distinction fonctionnalité / implémentation / contrat / dépendance / convention | OK | `007`, section 3 | +| Matrice reprendre / adapter / refondre / abandonner / ajouter | OK | `007`, section 16 | +| Config reste propriétaire exclusif de Config/env | OK | Transport ne dépend pas de Config ; adapter Config -> Transport | +| Logging reste façade runtime | OK | warnings Transport imposés via `ksp-logging-lib` | +| Wallet temporaire bot2/bot3 abandonné | OK | `.kspwallet` devient le format natif ; scenarios futurs utilisent de vrais wallets | +| `WalletPolicy` sortie du Wallet | OK | future `ksp-execution-policy-api` / policy contextuelle | +| TODO import/export bot3 utiles préservés | OK | `IDEAS.md` inclut Solana CLI/Base58, Phantom, Solflare/keystore, Backpack, Trust Wallet, Base app et distinction CDP | +| Ordre `0.2.1+` justifié par dépendances | OK | HTTP précède Wallet/Wallet Desk ; transports live puis off-chain puis Interface/Program | +| Chaque release `0.2.1+` possède mission/périmètre/hors-périmètre/dépendances/clôture/estimation | OK | `007`, section 4.8 | +| Discipline ~15–20 min/prerelease | OK | règles release/prompt | +| Une release concrète = une seule session de chat | OK | gate de sizing obligatoire à `pre.001` | +| Transport couvre toute documentation normative ciblée | OK | règle `KSP-TRANSPORT-006` | +| Deprecated/obsolete encore fonctionnel => `warn` | OK | règle `KSP-TRANSPORT-006` | +| Unstable/experimental => `warn` | OK | règle `KSP-TRANSPORT-006` | +| RAW -> CORE indépendant de Program decoding | OK | règles/architecture corrigées depuis `pre.002` | +| Pipeline durable RAW -> CORE -> DECODE -> SPECIALIZED | OK | architecture 008/009, plans 002/007 | +| RAW et CORE progressent horizontalement | OK | workers/jobs/apps ajoutés à la fin de chaque couche selon besoin | +| DECODE+ progresse verticalement groupe par groupe | OK | `KSP-FLOW-001` | +| Satellites protocole restent dans leur groupe | OK | `KSP-FLOW-002` | +| Ancienne chaîne globale materializer/projector supprimée comme décision active | OK | `KSP-WORKER-008`, `KSP-JOB-009` corrigé, IDEAS requalifié | +| Ordre Program orienté trading défini | OK | Core -> SPL token -> metadata -> Anchor -> Meteora/Raydium/Pump/Orca -> routing -> trading-adjacent -> généraliste | +| Market Desk progressive prévue | OK | V1 après DEX prioritaires, enrichissement après routing | +| Première release fonctionnelle décidée | OK | `0.2.1 — ksp-onchain-transport-lib / HTTP Solana foundation` | +| Prompt `0.2.1` finalisé | OK | `prompts/006-V0_2_1_START_PROMPT.md` version 2 | +| Collisions d'identifiants normatifs | CORRIGÉ | `KSP-TRANSPORT-006`, `KSP-FLOW-001/002`; les IDs notification existants restent inchangés | +| Jobs de replay globaux historiques | CORRIGÉ | aucune liste DECODE/SPECIALIZED globale figée ; replay introduit par frontière/groupe réel | + +## Spot-check Transport HTTP avant `0.2.1` + +Ce contrôle n'est **pas** la matrice normative de `0.2.1`; il sert uniquement à vérifier que le sizing du prompt est crédible et que bot3 ne constitue pas la source de vérité. + +### Documentation Solana observée le 2026-08-17 + +Index HTTP officiel : + +```text +https://solana.com/docs/rpc/http +``` + +Le spot-check recense **52 méthodes dans l'index HTTP courant**. + +La documentation Solana possède aussi une section `Deprecated Methods` séparée. Le spot-check observe **14 noms deprecated** dans cette section. Une page deprecated peut indiquer une suppression attendue dans une ancienne génération de `solana-core`; `0.2.1-pre.001` doit donc vérifier la disponibilité runtime actuelle avant de conclure qu'elle reste supportable. + +Exemple de source officielle : + +```text +https://solana.com/docs/rpc/deprecated/getrecentblockhash +``` + +### Comparaison bot3 + +`ks-onchain-transport/src/standard_methods.rs` contient les **52 noms de l'index HTTP courant** observé lors de ce spot-check, mais ne contient pas les 14 anciennes méthodes deprecated séparées. + +Cette égalité de noms ne signifie pas égalité de contrat : bot3 distingue notamment des méthodes avec typed adapter et des méthodes seulement enregistrées/raw JSON. KSP doit auditer request/response/status/tests méthode par méthode. + +Conclusion : + +- l'existant bot3 est une bonne source d'inventaire et de comportements historiques ; +- il n'est pas la norme ; +- `0.2.1-pre.001` doit refaire la matrice depuis la documentation officielle du jour ; +- la section deprecated séparée doit être inspectée explicitement ; +- si le nombre réel de méthodes + niveau de typage + pools/config rendent `0.2.1` trop risquée pour une seule session, la release est redécoupée **avant** l'implémentation lourde. + +## Écarts trouvés dans `pre.002` et corrigés par `pre.003` + +### IDs normatifs dupliqués + +`RULES_KSP.md` réutilisait : + +```text +KSP-TRANSPORT-001 +KSP-DATA-001 +KSP-DATA-002 +``` + +pour deux décisions différentes chacune. + +Correction : + +```text +KSP-TRANSPORT-001 conserve la décision de ne pas créer ksp-onchain-transport-api +KSP-TRANSPORT-006 porte la couverture documentaire exhaustive +KSP-DATA-001/002 restent les règles historiques de notification de données +KSP-FLOW-001/002 portent la progression durable et les satellites de protocole +``` + +### Replay jobs supersédés + +`KSP-JOB-009` imposait encore : + +```text +ksp-job-replay-core +ksp-job-replay-generic-materialization +ksp-job-replay-domain-projection +``` + +La règle est remplacée par une introduction need-driven des replays : CORE lorsqu'il existe, puis groupes/capacités verticaux à partir de DECODE. + +### Diagramme workers encore trop figé + +`docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md` conservait encore un schéma `W1 -> D1 -> W2 -> D2 -> W3 -> D3 -> W4 -> D4`. Même sans noms concrets, il pouvait réintroduire l'idée de quatre workers globaux correspondant mécaniquement aux quatre niveaux durables. `pre.003` le remplace par un diagramme des **frontières de données D1–D4** et précise que RAW/CORE peuvent avoir leurs workers horizontaux tandis que DECODE/SPECIALIZED utilisent des workers/processors need-driven par groupe vertical. + +### IDEAS Wallet incomplet + +Le TODO bot3 conservait plusieurs cibles étudiées mais non implémentées. Elles sont maintenant explicitement reportées dans KSP sans en faire des engagements prématurés : Backpack, Trust Wallet, Solflare Keystore, Base app/ex-Coinbase Wallet et distinction Coinbase Developer Platform. + +### Plan directeur incomplet sur les releases + +Le prompt `0.2.0` demandait pour chaque release `0.2.1+` : mission, périmètre, hors-périmètre, dépendances, critères de clôture et estimation souple des prereleases. `pre.002` n'avait pas encore regroupé ces six dimensions pour toutes les releases. `pre.003` ajoute les fiches correspondantes dans `007`. + +## Anomalie historique non bloquante + +Le scan global des headers Markdown détecte un ancien delta déjà livré : + +```text +deltas/0.1.4/pre.016-fix.002.md +``` + +qui ne possède pas les deux commentaires d'en-tête `file/version` utilisés par la convention actuelle. Ce fichier appartient à l'historique publié `0.1.4` et n'est **pas réécrit silencieusement** dans `0.2.0-pre.003`, conformément à la règle d'immutabilité pratique des deltas livrés. Cette anomalie ne modifie aucune règle/architecture active et ne bloque pas `0.2.0`. + +## Statut de clôture + +Après application et validation de `0.2.0-pre.003`, aucun développement N2 n'est attendu dans `0.2.0`. + +La publication `0.2.0-rel.001` peut être préparée si les validations locales ne révèlent pas d'écart supplémentaire. + +Le `rel.001` doit essentiellement : + +```text +workspace.package.version -> 0.2.0 +ROADMAP / plans / indices -> 0.2.0 stable +CHANGELOG.md -> entrée stable 0.2.0 +deltas/0.2.0/rel.001.md +validations globales finales +commit v0.2.0-rel.001 +tag Git v0.2.0 +``` + +Le prompt à utiliser ensuite est : + +```text +prompts/006-V0_2_1_START_PROMPT.md +``` diff --git a/prompts/000-README.md b/prompts/000-README.md index b35b85d..5f09626 100644 --- a/prompts/000-README.md +++ b/prompts/000-README.md @@ -1,5 +1,5 @@ - + # Prompts KSP @@ -27,4 +27,4 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par - [`004-V0_1_4_START_PROMPT.md`](004-V0_1_4_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.4 — ksp-app-config-desk` après publication stable de `0.1.3`. - [`005-V0_2_0_START_PROMPT.md`](005-V0_2_0_START_PROMPT.md) — prompt de reprise préparé à la clôture de `0.1.4`; il ouvre `0.2.0-pre.001`, release intermédiaire d'audit de `khadhroony-bot3`, de comparaison avec KSP et de planification/découpage du reste de `0.2.x`. -- [`006-V0_2_1_START_PROMPT.md`](006-V0_2_1_START_PROMPT.md) — prompt préparatoire destiné à ouvrir `0.2.1 — ksp-onchain-transport-lib / HTTP Solana foundation` après publication stable de `0.2.0`; il impose l'audit exhaustif de la documentation HTTP Solana, la séparation Config/Transport, les pools/rôles et le gate de sizing « une release = une session ». +- [`006-V0_2_1_START_PROMPT.md`](006-V0_2_1_START_PROMPT.md) — prompt finalisé par `0.2.0-pre.003`, destiné à ouvrir `0.2.1 — ksp-onchain-transport-lib / HTTP Solana foundation` après publication stable de `0.2.0`; il impose l'audit exhaustif des surfaces HTTP courantes et deprecated/unstable officiellement documentées, la séparation Config/Transport, les pools/rôles et le gate de sizing « une release = une session ». diff --git a/prompts/006-V0_2_1_START_PROMPT.md b/prompts/006-V0_2_1_START_PROMPT.md index 2f35305..2c011ea 100644 --- a/prompts/006-V0_2_1_START_PROMPT.md +++ b/prompts/006-V0_2_1_START_PROMPT.md @@ -1,8 +1,10 @@ - + # Prompt de démarrage `0.2.1` — `ksp-onchain-transport-lib` HTTP Solana foundation +> **Statut : finalisé par `0.2.0-pre.003`.** Utiliser ce prompt uniquement après publication stable/tag `v0.2.0`; toute information externe temporelle doit être revérifiée à l'ouverture de `0.2.1-pre.001`. + ## 1. Contexte de reprise La base attendue est la release stable `v0.2.0` de `khadhroony-solana-project`. @@ -148,6 +150,15 @@ Reprendre les besoins/invariants utiles ; ne pas reproduire : Au début de `pre.001`, consulter la documentation **officielle et actuelle** de Solana pour JSON-RPC HTTP et identifier précisément la surface normative de la release. +L'inventaire doit couvrir explicitement : + +- l'index HTTP courant ; +- la section officielle `Deprecated Methods` même lorsqu'elle est séparée de l'index courant ; +- toute surface HTTP `unstable` / `experimental` officiellement documentée ; +- la disponibilité runtime réelle d'une méthode deprecated/obsolete avant de décider qu'elle reste supportable. + +Le spot-check documentaire de clôture de `0.2.0` a observé 52 méthodes dans l'index HTTP courant du 2026-08-17 et 14 noms dans la section officielle Deprecated Methods. **Ces nombres ne sont pas un contrat** : `0.2.1-pre.001` doit refaire l'inventaire depuis les sources officielles du jour. + Ne pas utiliser une liste mémorisée ou la liste bot3 comme vérité. Pour chaque méthode HTTP documentée, relever au minimum : @@ -503,24 +514,25 @@ Il doit contenir au minimum : 1. audit exact de la base stable `v0.2.0` ; 2. audit détaillé de `ks-onchain-transport` bot3 ; -3. inventaire **exhaustif** des méthodes HTTP Solana documentées actuellement ; -4. statut `stable/deprecated/unstable` de chaque méthode ; -5. matrice méthode -> module/API KSP -> request -> response -> tests -> prerelease candidate ; -6. inventaire des contrats bot3 utiles à reprendre/adapter/refondre/abandonner ; -7. décision exacte sur les settings publics Transport ; -8. décision exacte pools/rôles/capabilities/priority/rate-limit/concurrence ; -9. stratégie retry/backoff/timeout ; -10. stratégie d'erreurs ; -11. ownership des modèles de réponse difficiles ; -12. dépendances externes retenues après vérification de versions/features ; -13. design du document `std.transport` et de l'adapter Config -> Transport ; -14. nouvelles variables `.env.example` réellement nécessaires, sans secret concret ; -15. architecture de tests/fixtures/smoke tests ; -16. canaries de dépendances/ownership ; -17. hors-périmètre confirmés ; -18. critères de clôture ; -19. prévision souple des prereleases ; -20. **gate de sizing de la release entière**. +3. inventaire **exhaustif** des méthodes HTTP Solana documentées actuellement, y compris les index current/deprecated/unstable séparés ; +4. comparaison nom par nom avec l'inventaire bot3 afin d'identifier ajouts, suppressions, méthodes historiques non reprises et niveau de contrat réel (`typed` vs raw/generic) ; +5. statut `stable/deprecated/unstable` de chaque méthode ; +6. matrice méthode -> module/API KSP -> request -> response -> tests -> prerelease candidate ; +7. inventaire des contrats bot3 utiles à reprendre/adapter/refondre/abandonner ; +8. décision exacte sur les settings publics Transport ; +9. décision exacte pools/rôles/capabilities/priority/rate-limit/concurrence ; +10. stratégie retry/backoff/timeout ; +11. stratégie d'erreurs ; +12. ownership des modèles de réponse difficiles ; +13. dépendances externes retenues après vérification de versions/features ; +14. design du document `std.transport` et de l'adapter Config -> Transport ; +15. nouvelles variables `.env.example` réellement nécessaires, sans secret concret ; +16. architecture de tests/fixtures/smoke tests ; +17. canaries de dépendances/ownership ; +18. hors-périmètre confirmés ; +19. critères de clôture ; +20. prévision souple des prereleases ; +21. **gate de sizing de la release entière**. ### Gate de sizing obligatoire