diff --git a/CHANGELOG.md b/CHANGELOG.md index e78d864..aafb82e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,26 @@ - + # Changelog KSP +## 0.3.7 — Backfill Desk : contrôle, monitoring, Cancel/Resume et autocomplete — 2026-09-03 + +`0.3.7` introduit `ksp-app-backfill-desk`, première application Tauri KSP spécialisée dans le contrôle d'un `ksp-job-backfill-lib` historique `RawTransaction`. L'application reste une couche de composition : `ksp-config-lib` possède les profils/composites/secrets, `ksp-onchain-transport-lib` le pool HTTP et les politiques provider/retry/rate-limit, `ksp-store-lib` la persistence backend-neutral, `ksp-job-backfill-lib` la découverte/hydratation/frontier/checkpoint/runtime et `ksp-job-api` le lifecycle commun. La Desk ne dépend ni d'un backend Store physique, ni de SQL, ni d'un SDK provider. + +Le package reprend le gabarit Tauri KSP courant avec cible lib + bin, launcher mince, splash commun, bridge `tracing`, frontend sous `frontend/`, bindings TS-RS applicatifs, ports stricts `1436/1437` et packaging Config/Schemas distribué. Le composite `cfg.composite.ksp-app-backfill-desk` couvre `mainnet`, `devnet` et `testnet`; Mainnet est le profil par défaut et la cohérence réseau Transport/Store est vérifiée avant ouverture d'une campagne. Les profils Store committed ont été réconciliés sur TLS PostgreSQL `disabled` pour l'environnement local de validation, sans retirer le support `verify_full` du Store/schema. + +Le formulaire Backfill couvre `LatestAddress`, `BeforeAddress`, `AfterAddress` et `ExplicitSignatures`, les commitments `finalized`/`confirmed`, la sélection d'un rôle HTTP logique, `min_context_slot` lorsque le scope l'autorise, ainsi que les bornes publiques de page/candidats/concurrence. Le frontend ne choisit ni réseau physique, ni endpoint/provider, ni JobId; le réseau dérive de la composition Store et les validations finales restent déléguées à `BackfillRequest`. + +Le Start réel conserve un seul run actif, génère le JobId côté backend et installe le handle de contrôle avant le spawn asynchrone. Le monitoring est latest-value : `BackfillSnapshotSource` est projeté via l'événement `ksp-backfill-status`, avec commande de resynchronisation explicite et rétention du dernier terminal. La projection expose lifecycle, phase, scope, boundary, compteurs de candidats/entités/observations, missing/conflicts/holes, concurrence maximale, frontier contiguë, présence de checkpoint et codes d'échec sûrs, sans adresse/signatures de campagne, payload RAW, URL, credential, contexte d'erreur arbitraire ni cursor/checkpoint concret. + +Le Cancel est coopératif, ciblé par le JobId backend et idempotent : un Cancel IPC retardé ne peut pas annuler le run suivant, un terminal gagné reste autoritaire et la fermeture de l'application bloque d'abord les nouveaux Starts puis demande best-effort l'annulation avant le shutdown Store. Le Resume est limité à la session courante : la Desk conserve en mémoire Rust la requête terminale et le checkpoint opaque, `ksp-job-backfill-lib` valide puis réémet le checkpoint pour un nouveau JobId sans changer le scope fingerprint/frontier, et aucun checkpoint durable n'est promis après redémarrage. + +Le polish final ajoute une saisie d'adresse libre avec autocomplete HTML `datalist` dérivé exclusivement de `ksp-core-lib::entries()`/`ProgramIdEntry`; aucune liste de Program IDs n'est hardcodée côté frontend et la sélection n'est jamais une allow-list. Les canaris de hardening figent ensuite l'inventaire des dépendances, modules, commandes Tauri, contrôles frontend, profils Config, frontières Store/provider, sécurité IPC et discipline crate-root des DTO partagés. + +Le gate final passe `cargo fmt --all -- --check`, audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, `cargo test --workspace --all-targets --all-features`, arbres Cargo ciblés, `cargo tree --duplicates` et `cargo tauri build`. Le run workspace enregistre 1 494 tests passés, 0 échec et 15 tests ignorés explicitement opt-in/operator-only; le build produit les bundles Linux `.deb`, `.rpm` et `.AppImage`. + +`prompts/027-V0_3_8_START_PROMPT.md` ouvre `0.3.8` sur `ksp-app-store-desk` V1. Le gabarit, le visuel, la structure Tauri et les dépendances npm de base viennent exclusivement des Desk KSP actuelles; DataTables reprend le pattern déjà utilisé par Config/Wallet Desk. L'archive kbot3 reste obligatoire uniquement comme référence fonctionnelle/UX des anciens diagnostics et tableaux RAW : aucune source, DTO, commande, SQL, gabarit ou version npm kbot3 n'est reprise. La première tranche doit auditer les capabilities Store existantes et les gaps éventuels de listing/diagnostic avant d'ouvrir des tableaux `RawTransaction`, `RawAccountState`, observations et rétention/tombstones via la seule façade `ksp-store-lib`. + ## 0.3.6 — Job API + backfill RAW historique observable — 2026-09-01 `0.3.6` introduit `ksp-job-api` comme contrat passif et runtime-neutral pour les traitements bornés/terminables : identité `JobId`/`JobKindCode`, lifecycle explicite, annulation coopérative partagée, snapshots typés et notifications latest-value consommables par plusieurs listeners sans transformer l'API en scheduler, runtime Tokio ou bus d'événements. La surface reste Core-only et sert immédiatement au premier consumer concret `ksp-job-backfill-lib`. diff --git a/Cargo.toml b/Cargo.toml index c21ac71..4b9eef7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 442 +# version: 443 [workspace] resolver = "3" members = ["crates/ksp-app-backfill-desk", "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-job-api", "crates/ksp-job-backfill-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-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.3.7-pre.16" +version = "0.3.7-pre.17" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 3fbf0a0..ddd136e 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -99,8 +99,8 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN - [X] `0.3.4` — Vertical slice PostgreSQL `RawAccountState` complète sur `ksp-store-lib` + `ksp-store-postgres-lib` : quatre capabilities account ajoutées aux six transaction pour une conformance RAW 10/10, V002 additive de 32 ressources au-dessus de V000/V001 immuables, state+observation atomiques, idempotence/conflit exacts, metadata Yellowstone observation-only, get/list keyset `(slot,pubkey,state_hash)` avec cursor KSPA anti-replay, hardening cross-family et live validé sur PostgreSQL 17 sans rétention destructive account. - [X] `0.3.5` — `ksp-interface-lib` étendu avec deux familles passives réellement partagées : `SlotLifecycleEvent` (`Processed`, `FirstShredReceived`, `Completed`, `CreatedBank`, `Dead`, `OptimisticallyConfirmed`, `Rooted`) et `TransactionExecutionEvent` (`slot + TransactionSignature[64] + Succeeded/Failed`). Interface reste Core-only, provider-neutral, sans serde/codec/runtime/event bus et sans duplication de `RawTransaction`/`RawAccountState`; les DTOs riches restent Transport-owned et les candidats non convergents restent différés. - [X] `0.3.6` — `ksp-job-api` + `ksp-job-backfill-lib` stables pour la première verticale historique `RawTransaction` : lifecycle/cancellation/latest-value runtime-neutral, scopes `Latest`/`Before`/`After`/signatures explicites, découverte/hydratation Transport observée, RAW v1 canonique, persistance Store atomique/idempotente, concurrence bornée, frontier contiguë, checkpoint/reprise caller-owned, snapshots sûrs et hardening externe sans dépendance backend/provider directe. -- [ ] `0.3.7` — Introduire `ksp-app-backfill-desk`, application Tauri spécialisée de contrôle et monitoring de `ksp-job-backfill-lib`, composée via Config : sélection de composition/profil, lancement/annulation, scopes/anchors, limites, progression latest-value, compteurs, frontier/checkpoint/reprise et outcome terminal. Elle ne devient ni navigateur Store généraliste, ni scheduler, ni propriétaire des retries/providers/backends. -- [ ] `0.3.8` — Introduire `ksp-app-store-desk` V1, application Tauri backend-agnostique de diagnostic, consultation et requêtage du Store via `ksp-store-lib` + Config : health/capabilities, `RawTransaction`, `RawAccountState`, observations, rétention/tombstones et pagination sûre. Cette application évoluera ensuite avec les couches STRUCTURAL, DECODED, processing/materialization et DOMAIN réellement ajoutées au Store, sans SQL ni backend physique dans l'UI. +- [X] `0.3.7` — `ksp-app-backfill-desk` livrée comme Desk Tauri KSP spécialisée : composition Config Mainnet/Devnet/Testnet, quatre scopes HTTP, validation/start single-run, monitoring latest-value `ksp-backfill-status`, Cancel ciblé/idempotent, Resume in-session par checkpoint Rust-only réémis pour un nouveau JobId, autocomplete libre depuis `ksp-core-lib`, hardening IPC/dependency boundaries et build Linux `.deb`/`.rpm`/`.AppImage`. Aucun SQL/backend/provider physique ni checkpoint durable n’est exposé. +- [ ] `0.3.8` — Introduire `ksp-app-store-desk` V1 sur le **gabarit KSP courant** (shell/splash/styles/assets/logging et dépendances npm de base des Desk KSP), avec DataTables selon le pattern déjà utilisé par Config/Wallet Desk. La V1 reste backend-agnostique et consulte le Store uniquement via `ksp-store-lib` + Config : health/runtime sûr, tableaux `RawTransaction` et `RawAccountState`, observations lorsque la surface de listing backend-neutral est disponible/ajoutée proprement, rétention/tombstones en lecture et pagination Store opaque distincte du filtrage/paging local DataTables. kbot3 sert uniquement de référence fonctionnelle/UX des anciens tableaux RAW, jamais de gabarit, source de code, SQL, DTO, commandes ou versions npm. L’application évoluera ensuite avec STRUCTURAL, DECODED, processing/materialization et DOMAIN réellement persistés. - [ ] `0.3.9` — Introduire `ksp-worker-api` comme API générique de lifecycle/health/progression pour services continus, en reprenant le pattern latest-value stabilisé par Job tout en gardant les sémantiques Worker distinctes des jobs terminables et des wake-ups Store post-commit. - [ ] `0.3.10` — Introduire `ksp-worker-raw-transaction-ingest-lib` pour l'acquisition continue de `RawTransaction` via les surfaces live de `ksp-onchain-transport-lib`, persistance atomique par `ksp-store-lib`, reprise/backpressure/idempotence et notifications `ksp-worker-api`, sans decode Program ni dépendance backend/provider directe. - [ ] `0.3.11` — Introduire `ksp-app-raw-transaction-ingest-desk`, application Tauri spécialisée de contrôle et monitoring du worker live : lifecycle, health, rates, backpressure, reconnect/recovery et compteurs sûrs ; la consultation détaillée des données persistées reste la responsabilité de `ksp-app-store-desk`. diff --git a/deltas/0.3.7/pre.017.md b/deltas/0.3.7/pre.017.md new file mode 100644 index 0000000..8e4d78f --- /dev/null +++ b/deltas/0.3.7/pre.017.md @@ -0,0 +1,91 @@ + + + +# Delta `0.3.7-pre.017` — préparation de publication et prompt `0.3.8` + +## 1. Base requise + +```text +0.3.7-pre.016 +``` + +Le gate documentaire opérateur de `pre.016` est propre : audits Rust/Markdown sans erreur. Le gate technique `pre.015` reste l'autorité de clôture technique et n'est pas rejoué dans cette lane de publication minimale. + +## 2. Objectif + +Fermer exclusivement le couloir de préparation de publication : + +```text +CHANGELOG.md +ROADMAP.md +prompts/027-V0_3_8_START_PROMPT.md +``` + +Les seuls fichiers mécaniques supplémentaires sont `Cargo.toml` pour la version prerelease et le présent delta. + +Aucun README, USAGE, plan, validation, architecture, code, test, Config ou manifest de crate n'est rouvert. + +## 3. Version + +```text +workspace.package.version = 0.3.7-pre.17 +``` + +## 4. CHANGELOG + +Ajout de l'entrée `0.3.7` récapitulant : + +```text +Backfill Desk Tauri KSP +Config/Transport/Store/Job boundaries +Start single-run +monitoring latest-value +Cancel ciblé/idempotent +Resume in-session +Program ID autocomplete depuis ksp-core-lib +hardening/completeness +réconciliation TLS Store committed +1 494 tests passés au gate final +3 bundles Linux Tauri +``` + +## 5. ROADMAP + +- `0.3.7` passe à `[X]` avec la surface effectivement livrée ; +- `0.3.8` reste la prochaine release et précise le gabarit KSP, DataTables KSP, tableaux RAW backend-neutral et le rôle strictement fonctionnel/UX de kbot3. + +## 6. Prompt `0.3.8` + +Le prompt `027-V0_3_8_START_PROMPT.md` respecte `PROMPT_STRUCTURE.md` et ouvre `ksp-app-store-desk` V1. + +Décision structurante : + +```text +gabarit/visuel/structure/npm de base = Desk KSP +DataTables = pattern déjà éprouvé dans Config/Wallet Desk KSP +kbot3 = référence fonctionnelle/UX uniquement +code/DTO/commandes/SQL/gabarit/versions npm kbot3 = interdits comme source +``` + +`pre.001` doit auditer les capabilities Store réelles et produire une gap map avant toute table lourde. Une query manquante nécessaire à la V1 doit être ajoutée proprement dans les couches Store backend-neutral ou entraîner un redécoupage ; elle ne peut pas être contournée par SQL dans l'application. + +## 7. Hors scope + +```text +code/runtime Backfill +Store runtime/migrations +Config +README/USAGE +plan/validation +architecture +nouveau test +nouvelle dépendance +publication stable +``` + +## 8. Suite + +```text +0.3.7-rel.001 — publication stable v0.3.7 +0.3.8-pre.001 — audit/sizing Store Desk selon prompt 027 +``` diff --git a/prompts/027-V0_3_8_START_PROMPT.md b/prompts/027-V0_3_8_START_PROMPT.md new file mode 100644 index 0000000..295751b --- /dev/null +++ b/prompts/027-V0_3_8_START_PROMPT.md @@ -0,0 +1,1840 @@ + + + +# Prompt de démarrage `0.3.8` — `ksp-app-store-desk` V1 RAW + +## 1. Identité de la release et base exacte requise + +Ouvrir cette session uniquement après publication et tag validés de : + +```text +v0.3.7 +``` + +La base autoritaire est le dépôt stable `v0.3.7` ou, si l'opérateur fournit une archive stable explicitement désignée comme base, cette archive exacte. + +Vérifier avant tout travail : + +```text +workspace.package.version = 0.3.7 +deltas/0.3.7/rel.001.md présent +ksp-app-backfill-desk présent et stable +ksp-store-api / ksp-store-lib / ksp-store-postgres-lib présents +``` + +Ne pas partir d'un ZIP de prerelease `0.3.7-pre.*` si une archive stable `v0.3.7` est fournie. + +La release concrète est : + +```text +0.3.8 +``` + +La première tranche est obligatoirement : + +```text +0.3.8-pre.001 +``` + +`pre.001` est un gate de **lecture + audit Store + audit gabarit KSP + audit kbot3 fonctionnel + brainstorming + sizing + planification**. + +Il est interdit de commencer la session en copiant une application Tauri, en écrivant directement les tables DataTables ou en ajoutant du SQL pour obtenir les données manquantes. + +--- + +## 2. Mission et résultat attendu + +Créer : + +```text +crates/ksp-app-store-desk +``` + +comme première application Tauri KSP spécialisée dans **l'inspection backend-agnostique du Store et l'exploration tabulaire de la couche RAW réellement persistée**. + +La V1 doit permettre à un opérateur/développeur de voir l'état du Store, de parcourir les familles RAW présentes et d'inspecter leurs métadonnées/détails utiles sans connaître PostgreSQL, SQL, les migrations physiques ou les clients backend. + +Chaîne d'ownership attendue : + +```text +Config composite/profile + | + +--> Logging settings + +--> Store settings + | + v + Store + | + +--> health/runtime snapshot + +--> RAW read/query capabilities + +--> opaque Store pagination + | + v + DTO applicatifs bornés + | + v + UI Tauri / DataTables +``` + +Résultat V1 visé à la clôture : + +```text +ksp-app-store-desk existe comme package Tauri Rust lib + bin +ports Vite/HMR dédiés 1438/1439 +shell/splash/styles/assets/logging conformes au gabarit KSP stable +package.json part du socle npm KSP stable, pas de kbot3 +DataTables suit le pattern KSP Config/Wallet Desk lorsque retenu +Config compose Logging + Store pour le Desk +Store est ouvert exclusivement via ksp-store-lib +health/runtime sûrs sont visibles +RawTransaction est navigable sous forme de tableau +RawAccountState est navigable sous forme de tableau +les observations RAW sont consultables si la surface backend-neutral requise existe ou est ajoutée proprement +l'état de rétention/tombstone RawTransaction est visible en lecture +les filtres Store utilisent uniquement les query contracts KSP disponibles +la pagination Store opaque reste distincte du paging/filtering local DataTables +les grands payloads/bytes ne sont pas dupliqués dans toutes les rows IPC +une vue détail explicite permet d'inspecter une entité sans fuite backend +aucun SQL, row PostgreSQL, URI, pool/client, migration interne ou backend physique n'est piloté par le frontend +aucun accès direct ksp-store-api ou ksp-store-postgres-lib depuis l'application +aucune action destructive de rétention n'est requise pour la V1 +aucune logique Worker/Backfill/Decode/Materialization n'est réimplémentée +README/USAGE/plan/validation finalisés dans le couloir documentaire +build Tauri final vert +``` + +La notion de « tableaux correspondant au RAW » signifie **des vues des contrats logiques KSP** (`RawTransaction`, `RawAccountState`, observations, rétention/tombstone) et non une copie 1:1 des tables SQL PostgreSQL. + +--- + +## 3. Sources de vérité internes obligatoires — ordre de lecture + +### 3.1 Gouvernance générale + +Lire d'abord : + +```text +RULES.md +ROADMAP.md +CHANGELOG.md +docs/000-README.md + +docs/rules/RULES_GENERAL.md +docs/rules/RULES_KSP.md +docs/rules/RULES_RUST.md +docs/rules/RULES_DEPENDENCIES.md +docs/rules/RULES_DOCUMENTATION.md +docs/rules/FILE_CONTRACTS.md +docs/rules/VERSION_WORKFLOW.md +docs/rules/PROMPT_STRUCTURE.md +``` + +Le prompt complète ces règles ; il ne les remplace pas. + +Rappels directement bloquants : + +```text +Rust 2024 +unsafe / unwrap / expect / panic interdits selon les règles KSP +? interdit en production +retours explicites ; clippy::implicit_return deny +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +pas de pub mod +pub/pub(crate) partagés consommés via crate::Item +item seulement module-local => private +unit tests sous unit_tests/ +integration tests sous tests/ + +ksp-config-lib possède Config/env/secrets +ksp-store-lib est l'unique façade Store des consumers ordinaires +ksp-store-api possède les contrats persistants mais n'est pas une dépendance app +ksp-store-postgres-lib possède SQL/driver/pool/migrations physiques +ksp-logging-lib possède le runtime/policy tracing KSP +application = composition + DTO/commands + UX +``` + +Après toute modification Rust : + +```bash +cargo fmt --all +python3 scripts/audit_rust_workspace_rules.py +cargo check --workspace +cargo clippy --workspace --all-targets +``` + +Pour tout Markdown touché : + +```bash +python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.8 +``` + +Une commande non exécutée n'est jamais déclarée PASS. + +### 3.2 Architecture Store et applications + +Lire ensuite : + +```text +docs/architecture/000-README.md +docs/architecture/002-LAYERS_AND_DEPENDENCIES.md +docs/architecture/003-COMPONENT_CONTRACTS.md +docs/architecture/004-COMPONENT_INVENTORY.md +docs/architecture/005-DEPENDENCY_GRAPH.md +docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md +docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +``` + +Frontières acquises : + +```text +Store API = contrats persistants backend-neutral +Store lib = façade runtime/query des consumers +backend PostgreSQL = implémentation physique privée +Config = sélection target/network/backend/settings/secrets +Store Desk = inspection/composition, jamais backend +``` + +Le Desk n'obtient pas le droit de contourner une capability manquante par une requête SQL « temporaire ». + +### 3.3 Fondations Store `0.3.1` à `0.3.4` + +Lire intégralement : + +```text +crates/ksp-store-lib/README.md +crates/ksp-store-lib/USAGE.md +crates/ksp-store-postgres-lib/README.md +crates/ksp-store-postgres-lib/USAGE.md + +docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md +docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md +docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md +docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md +docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md +docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md +``` + +Puis inventorier le code réel : + +```text +crates/ksp-store-api/src/lib.rs +crates/ksp-store-api/src/capability/raw_transaction.rs +crates/ksp-store-api/src/capability/raw_account.rs +crates/ksp-store-api/src/capability/raw_retention.rs +crates/ksp-store-api/src/model/raw_transaction.rs +crates/ksp-store-api/src/model/raw_account.rs +crates/ksp-store-api/src/model/raw_pagination.rs +crates/ksp-store-api/src/model/raw_retention.rs +crates/ksp-store-api/src/model/raw_primitives.rs + +crates/ksp-store-lib/src/lib.rs +crates/ksp-store-lib/src/store.rs +crates/ksp-store-lib/src/health.rs +crates/ksp-store-lib/src/settings.rs + +crates/ksp-store-postgres-lib/src/ +crates/ksp-store-postgres-lib/migrations/ +crates/ksp-store-postgres-lib/tests/ +``` + +Le backend PostgreSQL est lu pour **auditer la conformance et les gaps**, jamais pour créer une dépendance applicative ni recopier son SQL. + +### 3.4 État `0.3.7` à préserver + +Lire : + +```text +crates/ksp-app-backfill-desk/README.md +crates/ksp-app-backfill-desk/USAGE.md +docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md +docs/validation/024-V0_3_7_BACKFILL_DESK.md +deltas/0.3.7/rel.001.md +``` + +Pourquoi : + +```text +réutiliser les conventions KSP desktop finalisées +ne pas régresser la composition Config/Store +réutiliser les patterns d'erreur/DTO/instrumentation sûrs +ne pas confondre inspection Store et contrôle Backfill +``` + +### 3.5 Config et targets Store + +Auditer : + +```text +crates/ksp-config-lib/src/lib.rs +crates/ksp-config-lib/src/composite.rs +crates/ksp-config-lib/src/registry.rs +crates/ksp-config-lib/src/packaging.rs +crates/ksp-config-lib/src/store.rs + +config/std.logging.json +config/std.store.json +config/schemas/std.logging.schema.json +config/schemas/std.store.schema.json +config/schemas/composite.schema.json +config/composite.ksp-app-backfill-desk.json +``` + +`pre.001` doit décider le composite exact de Store Desk, attendu a priori : + +```text +config/composite.ksp-app-store-desk.json +``` + +La configuration sélectionne un target Store ; l'application ne lit jamais URI/env/libpq elle-même. + +### 3.6 Gabarit desktop KSP — source exclusive du shell et des dépendances de base + +Le **gabarit de Store Desk est KSP, pas kbot3**. + +Lire au minimum : + +```text +crates/ksp-app-config-desk/Cargo.toml +crates/ksp-app-config-desk/package.json +crates/ksp-app-config-desk/tauri.conf.json +crates/ksp-app-config-desk/vite.config.ts +crates/ksp-app-config-desk/src/ +crates/ksp-app-config-desk/frontend/ +crates/ksp-app-config-desk/tests/ + +crates/ksp-app-wallet-desk/Cargo.toml +crates/ksp-app-wallet-desk/package.json +crates/ksp-app-wallet-desk/tauri.conf.json +crates/ksp-app-wallet-desk/vite.config.ts +crates/ksp-app-wallet-desk/src/ +crates/ksp-app-wallet-desk/frontend/ +crates/ksp-app-wallet-desk/tests/ + +crates/ksp-app-backfill-desk/Cargo.toml +crates/ksp-app-backfill-desk/package.json +crates/ksp-app-backfill-desk/tauri.conf.json +crates/ksp-app-backfill-desk/vite.config.ts +crates/ksp-app-backfill-desk/src/ +crates/ksp-app-backfill-desk/frontend/ +crates/ksp-app-backfill-desk/tests/ + +crates/ksp-app-solprices-desk/package.json +crates/ksp-app-solprices-desk/frontend/ +``` + +`KSP-APP-008` reste normatif : `ksp-app-config-desk` est la référence du gabarit, les Desk plus récentes servent à vérifier les raffinements réellement stabilisés depuis. + +Le socle npm observé dans la base `0.3.7` est attendu autour de : + +```text +dependencies + @fltsci/tauri-plugin-tracing + @fortawesome/fontawesome-free + @tauri-apps/api + bootstrap + resize-observer-polyfill + simplebar + +devDependencies + @tauri-apps/cli + @types/bootstrap + @types/node + sass-embedded + typescript + vite +``` + +Les Desk KSP Config/Wallet utilisent déjà en plus : + +```text +datatables.net-bs5 +datatables.net-select-bs5 +``` + +Ces packages constituent la référence KSP pour la V1 Store Desk si les besoins de table/selection le justifient. + +**Interdiction explicite :** ne pas prendre `package.json`, les versions npm, le shell HTML, les SASS, les assets ou la structure Tauri de kbot3 comme source pour Store Desk. + +Ports réservés pour Store Desk : + +```text +Vite HTTP 1438 +Vite HMR 1439 +``` + +Ils sont stricts conformément à `KSP-APP-024`. + +--- + +## 4. Référence historique kbot3 obligatoire — fonctionnelle/UX uniquement + +L'archive kbot3 fournie par l'opérateur doit être réauditée en `pre.001` comme **référence fonctionnelle et UX des vues Store historiques**, jamais comme source de code ou de gabarit. + +Archive attendue : + +```text +khadhroony-bot3_v0.5.3-pre.005-fix010-thelatest1.zip +``` + +ou l'archive équivalente explicitement fournie par l'opérateur. + +Inspecter au minimum : + +```text +kb-app-demo-desktop/src/demo_store_common.rs +kb-app-demo-desktop/src/demo_store_diag.rs +kb-app-demo-desktop/src/demo_store_raw.rs +kb-app-demo-desktop/src/demo_store_replay_candidates.rs + +kb-app-demo-desktop/frontend/demo_store_diag.html +kb-app-demo-desktop/frontend/demo_store_raw.html +kb-app-demo-desktop/frontend/demo_store_replay_candidates.html + +kb-app-demo-desktop/frontend/ts/demo_store_diag.ts +kb-app-demo-desktop/frontend/ts/demo_store_raw.ts +kb-app-demo-desktop/frontend/ts/demo_store_tables.ts +kb-app-demo-desktop/frontend/ts/demo_store_block_pagination.ts +kb-app-demo-desktop/frontend/ts/demo_store_replay_candidates.ts +``` + +Fonctionnalités historiques à inventorier : + +```text +statut/health Store lisible +refresh manuel +tables responsives horizontales +DataTables avec filtre local +page length locale +copyable identifiers lorsque pertinent +sélection de ligne lorsque réellement utile +badges/états lisibles +navigation backend par blocs distincte de DataTables +résumé de ressource / compteurs / slot min-max +vue détail / JSON de diagnostic +feedback busy/error +instrumentation frontend +``` + +La matrice `pre.001` classe chaque idée : + +```text +REPRENDRE FONCTIONNELLEMENT +REDESSINER POUR LES CONTRATS KSP +REPORTER +REJETER +``` + +Interdictions : + +```text +aucune copie de code Rust/TS/HTML/SASS kbot3 +aucune reprise de DTO/commande kbot3 comme contrat +aucun SQL/repository kbot3 comme chemin applicatif +aucune reprise de package.json ou versions npm kbot3 +aucun accès direct au backend historique ks-store +``` + +La forme visuelle et technique finale suit les Desk **KSP** ; seule l'idée fonctionnelle des vues/tableaux peut être reprise de kbot3. + +--- + +## 5. Sources externes à réauditer en `pre.001` + +Une dependency externe réellement ajoutée ou mise à jour doit être auditée sur sa source primaire. + +Pour DataTables, vérifier si nécessaire : + +```text +DataTables / datatables.net-bs5 +Select / datatables.net-select-bs5 +compatibilité Bootstrap 5 +API ESM/TypeScript réellement utilisée par les Desk KSP +``` + +Mais la priorité est la cohérence workspace : si Config/Wallet Desk utilisent déjà des ranges compatibles et suffisants, Store Desk les réutilise au lieu d'introduire une version divergente par application. + +Pour Tauri/TypeScript/Vite/Bootstrap, ne pas déclencher une mise à niveau opportuniste de tout le workspace dans `0.3.8` sauf nécessité explicitement démontrée par `pre.001`. + +Documenter : + +```text +version/range KSP existant +version stable externe courante si auditée +raison de conserver ou modifier +features/plugins réellement nécessaires +``` + +--- + +## 6. État Store validé à préserver depuis `v0.3.7` + +### 6.1 Façade Store + +`ksp-store-lib` possède : + +```text +Store::open +Store::runtime_snapshot +Store::health +Store::close +``` + +Une instance Store représente : + +```text +1 réseau logique + 1 backend sélectionné +``` + +L'UI ne multiplexe pas elle-même plusieurs connexions physiques. + +### 6.2 RAW capabilities existantes + +La façade implémente exactement dix capabilities RAW : + +```text +RawTransactionRead +RawTransactionWrite +RawTransactionObservationRead +RawTransactionObservationWrite +RawTransactionRetentionRead +RawTransactionRetentionWrite +RawAccountStateRead +RawAccountStateWrite +RawAccountObservationRead +RawAccountObservationWrite +``` + +Store Desk V1 consomme d'abord les **read capabilities**. Les write capabilities ne deviennent pas automatiquement des boutons UI. + +### 6.3 Queries/pagination existantes + +La base stable possède : + +```text +RawTransactionQuery +RawAccountStateQuery +RawPageRequest +RawPageLimit +RawPageCursor +RawSlotRange +RawSortDirection +``` + +`list_raw_transactions` retourne des `RawTransactionReference`. + +`list_raw_account_states` retourne des `RawAccountStateReference`. + +Les cursors sont backend-owned et opaques. + +Important : + +```text +Store API n'impose pas un plafond métier arbitraire de page +le Desk doit néanmoins choisir un default UX borné +ce default applicatif n'est pas une policy Store/Worker +``` + +### 6.4 Gaps connus à confirmer en `pre.001` + +Dans `v0.3.7`, il n'existe pas a priori de listing backend-neutral générique pour : + +```text +RawTransactionObservation +RawAccountObservation +``` + +Les observations sont lisibles par `RawObservationKey`, mais pas énumérables via une query publique existante. + +Il n'existe pas non plus de contrat Store public garantissant des diagnostics physiques de type : + +```text +nombre de lignes SQL par table +nom de table +schema PostgreSQL +index physiques +``` + +Ces gaps sont **à auditer**, pas à contourner. + +### 6.5 Retention transactionnelle + +Pour `RawTransaction`, les read contracts permettent : + +```text +retention state +tombstone minimal lorsque purgé +``` + +La V1 peut afficher ces informations. + +Les transitions `Full -> Archived -> Purged` et `ForceRehydrate` restent des décisions de policy/maintenance. Elles ne deviennent pas des actions UI V1 par simple disponibilité du trait write. + +`RawAccountState` ne possède pas de lifecycle destructif de rétention. + +--- + +## 7. Décisions acquises — ne pas redébattre sans contradiction réelle + +```text +nom : ksp-app-store-desk +release : 0.3.8 +ports : 1438/1439 +gabarit : KSP uniquement +référence gabarit normative : ksp-app-config-desk + raffinements Desk KSP stables +npm de base : KSP uniquement +DataTables : pattern KSP Config/Wallet Desk si retenu +kbot3 : référence fonctionnelle/UX uniquement +Store access : ksp-store-lib uniquement +Config access : ksp-config-lib +SQL/backend physique : interdit dans app/frontend +V1 : inspection/query RAW, non maintenance destructive +future layers : même Store Desk évoluera avec STRUCTURAL/DECODED/materialization/DOMAIN +``` + +La release ne crée pas une seconde façade Store UI-specific. + +Une extension Store nécessaire au browsing doit être : + +```text +backend-neutral +réutilisable hors Tauri +possédée par ksp-store-api / ksp-store-lib +implémentée par les backends concernés +couverte par tests de frontière/conformance +``` + +et non une commande app qui sait que PostgreSQL possède telle table. + +--- + +## 8. Questions réellement ouvertes à trancher pendant `pre.001` + +### 8.1 Screen map + +Décider la structure réelle, par exemple : + +```text +Overview / Health +RAW Transactions +RAW Accounts +Transaction Observations +Account Observations +``` + +ou une navigation plus compacte si les observations sont intégrées au détail d'une entité. + +Le nombre de vues doit rester lisible selon `KSP-APP-028`. + +### 8.2 Table map et colonnes + +Produire avant code une matrice : + +```text +vue/table UI +contrat KSP source +getter/champ source +DTO app-owned +format frontend +filtrable localement ? +filtrable côté Store ? +chargé dans la row ou à la demande ? +``` + +Pour les entiers `u64` susceptibles de dépasser la précision JS (`slot`, `lamports`, `rent_epoch`, timestamps, counts), décider une projection **texte décimal** côté IPC plutôt qu'une coercition `number` dangereuse. + +### 8.3 Capability gap matrix + +Pour chaque vue voulue : + +```text +capability existe +capability existe mais ne liste que les références +capability manque +extension Store minimale possible +extension trop grosse -> split release avant implémentation lourde +``` + +Les observations sont le premier gap connu à analyser. + +### 8.4 Row summary vs N+1 detail fetch + +Le listage actuel retourne des références. Décider si une page de 25/50/100 références peut être enrichie par lectures bornées parallèles ou si une nouvelle query backend-neutral de summary est préférable. + +Interdictions : + +```text +N+1 non borné +concurrence non bornée +SQL JOIN app-owned +DTO Store API conçu uniquement pour DataTables +``` + +### 8.5 Pagination Store vs DataTables + +Décider explicitement : + +```text +page/cursor Store = navigation durable backend +paging/search/order DataTables = opération locale sur le bloc chargé +``` + +Le frontend ne doit jamais faire croire qu'un tri local réordonne toute la base. + +Si DataTables conserve son propre paging, le libellé/UX doit distinguer clairement : + +```text +bloc Store chargé +page locale DataTables +``` + +Une alternative valide est de désactiver le paging DataTables et de ne garder que filtre/tri local. + +### 8.6 Cursor ownership / IPC + +Le cursor Store est opaque. + +Choisir entre : + +```text +cursor conservé côté Rust avec session/query state +ou token app-owned opaque borné traversant IPC sans jamais être interprété côté TS +``` + +Ne jamais décoder la sémantique PostgreSQL du cursor dans le frontend. + +Prévoir la navigation arrière : stack de cursors/session state si utile ; ne pas inventer `OFFSET`. + +### 8.7 Payload/detail policy + +Les rows de table ne doivent pas contenir systématiquement : + +```text +RawTransaction.payload complet +RawAccountState.data complet +``` + +Décider une vue détail à la demande : + +```text +metadata/hash/format/size dans la table +contenu chargé explicitement pour une seule entité +preview bornée si nécessaire +aucun payload dans les logs +aucune persistence browser +``` + +Si un export exact de gros bytes est nécessaire, il doit être conçu explicitement côté Rust et ne pas transformer le frontend en filesystem client. + +### 8.8 Observations + +Décider si V1 doit fournir : + +```text +tables d'observations dédiées +observations d'une entité dans le détail +ou les deux +``` + +Si un listing manque, définir la query Store backend-neutral minimale et ses clés de pagination/filtering. + +### 8.9 Retention/tombstones + +Décider comment afficher : + +```text +Full +Archived +Purged +tombstone présent +payload indisponible +``` + +La V1 ne doit pas ajouter par défaut de boutons archive/purge/force-rehydrate. + +### 8.10 Profil/network UX + +Décider si la V1 : + +```text +utilise le profil composite choisi au démarrage +ou permet un changement contrôlé de target qui implique fermeture/reouverture Store +``` + +Ne jamais garder deux Stores physiques ouverts implicitement pour masquer le choix de target. + +### 8.11 Gate live + +Déterminer si un smoke PostgreSQL réel read-only est disponible et sûr : + +```text +Config -> Store -> health -> query page -> detail +``` + +Il ne doit jamais modifier/purger les données de l'opérateur pour prouver le Desk V1. + +--- + +## 9. Objectifs et livrables de `0.3.8` + +### 9.1 Package application + +Créer le package mixte : + +```text +package = ksp-app-store-desk +lib = ksp_app_store_desk_lib +bin = ksp-app-store-desk +``` + +Attendus : + +```text +launcher main.rs mince +run public depuis la lib +tauri.rs centralise #[tauri::command] +modules tw_* pour fenêtres si besoin +splash KSP commun +frontend/ + frontend/ts/ + frontend/sass/ +bindings TS-RS non versionnés +capabilities minimales +ports 1438/1439 stricts +``` + +### 9.2 Gabarit et npm + +Le scaffold doit dériver du **gabarit KSP stable**. + +Le package frontend reprend le socle KSP stable et ajoute DataTables uniquement sur la base du pattern KSP Config/Wallet. + +Ne pas importer : + +```text +package-lock.json +npm lockfiles +versions kbot3 +plugins kbot3 non présents dans KSP +markdown-it si aucune vue Markdown n'existe +``` + +### 9.3 Config composite + +Créer le composite Store Desk seulement si le gate le confirme : + +```text +Logging +Store +``` + +Transport n'est pas une dépendance de la consultation Store V1. + +Le target Store doit rester Config-owned. + +### 9.4 Overview / health + +Projeter uniquement les données sûres de : + +```text +StoreRuntimeSnapshot +StoreHealthSnapshot +``` + +Exemples sûrs : + +```text +network +backend kind logique +health state +migration version +pending migration count +pool capacity/size/available/waiting +last stable error code +``` + +Ne pas afficher URI, credentials, hostname complet ou détails driver. + +### 9.5 Table RawTransaction + +La V1 doit au minimum permettre : + +```text +query par network Store courant +slot range optionnelle +direction ascending/descending +page size UX bornée +navigation cursor sûre +liste de signatures/références +détail transaction à la demande +retention state/tombstone en lecture +``` + +Colonnes candidates à auditer : + +```text +signature +slot +block_time +payload format id/version +payload size +content hash +retention state +``` + +Ne pas figer les colonnes sans les relier aux getters KSP réels pendant `pre.001`. + +### 9.6 Table RawAccountState + +La V1 doit au minimum permettre : + +```text +slot range optionnelle +pubkey filter optionnel +direction +page size +cursor navigation +liste des références +détail state à la demande +``` + +Colonnes candidates : + +```text +pubkey +slot +state hash +owner +lamports +executable +rent epoch +data length +``` + +Les bytes account complets sont detail-only, jamais répétés dans toutes les rows. + +### 9.7 Observations RAW + +Objectif fonctionnel : rendre consultables les observations d'acquisition transaction/account avec leur provenance sûre. + +Champs candidats : + +```text +observation key +reference entity +provider code +protocol code +acquisition method +origin +received_at +observed_at +commitment +logical endpoint id +capture/filter ids +source payload hash/size +account-only write_version/is_startup/transaction_signature lorsque présents +``` + +Si la base stable ne permet pas leur listing, `pre.001` doit cadrer l'extension Store minimale avant implémentation. + +### 9.8 Detail views + +Prévoir un détail de ligne app-owned permettant de lire les champs non adaptés au tableau. + +Le détail reste : + +```text +read-only +borné +sans SQL/backend leak +sans persistence browser +instrumenté sans payload +``` + +### 9.9 DataTables UX + +Fonctions candidates issues du pattern KSP + audit kbot3 fonctionnel : + +```text +scroll horizontal +filtre local +page length locale si non ambiguë +tri local clairement identifié +sélection seulement si une action réelle la justifie +badges de statut +copy UX d'identifiants si sûre +redraw propre lors d'un nouveau bloc Store +responsive Bootstrap KSP +``` + +Ne pas utiliser DataTables pour inventer la pagination backend. + +### 9.10 Instrumentation frontend + +Conformément à `KSP-APP-027` : + +```text +load/refresh/query start/end +changement de filtre Store +navigation first/next/previous +ouverture/fermeture détail +changement tab/vue +DataTable redraw significatif en trace +``` + +Ne jamais logger : + +```text +payload RAW +account bytes +URI Store +credentials +cursor opaque +contenu de recherche utilisateur sensible +``` + +--- + +## 10. Hors périmètre explicite + +```text +SQL ou query builder dans l'application +ksp-store-postgres-lib comme dépendance app +tokio-postgres/deadpool/rustls dans l'app +accès direct ksp-store-api uniquement pour contourner ksp-store-lib +édition/destruction de RAW +archive/purge/force-rehydrate UI +policy de rétention +backfill/job control +worker lifecycle +transport RPC +live ingest +STRUCTURAL/CORE/DECODED/DOMAIN non persistés +materialization/replay pipeline +scheduler +application globale/control desk +analytics métier/trading +``` + +Les tables physiques : + +```text +ksp_raw_transactions +ksp_raw_transaction_observations +ksp_raw_transaction_archive_payloads +ksp_raw_account_states +ksp_raw_account_observations +``` + +peuvent être auditées côté backend pour comprendre la conformance, mais elles ne deviennent pas le contrat UI. + +--- + +## 11. Contraintes sécurité, API et architecture spécifiques + +### 11.1 Dependency firewall + +Dépendances KSP attendues côté application, à confirmer par `pre.001` : + +```text +ksp-config-lib +ksp-logging-lib +ksp-store-lib +``` + +Ajouter `ksp-core-lib` uniquement si une responsabilité applicative réelle le nécessite et qu'elle ne peut pas être consommée proprement via les réexports Store/KSP déjà présents. + +Interdits comme dépendances normales de Store Desk : + +```text +ksp-store-api +ksp-store-postgres-lib +tokio-postgres +deadpool-postgres +reqwest +tonic +yellowstone-grpc-* +crates Solana/protocole externes +``` + +### 11.2 DTO / IPC + +Les DTO Tauri sont app-owned. + +Ils n'exposent jamais : + +```text +SQL +row backend +statement +transaction DB +URI/credential +pool/client physique +migration resource SQL +cursor décodé +``` + +Les grands entiers utilisent un format JS-safe décidé explicitement. + +Les erreurs exposent domaine/code/message borné si le pattern app courant le prévoit ; jamais `Debug` backend ou contexte arbitraire. + +### 11.3 Store cursor + +Le cursor est une capability de navigation, pas un batch scheduler. + +Le frontend : + +```text +ne l'interprète pas +ne le transforme pas en OFFSET +ne construit pas de SQL-like ordering +``` + +### 11.4 DataTables + +DataTables est un composant de rendu/interaction local. + +Il ne possède pas : + +```text +source de vérité de la pagination Store +network scope +slot range durable +cursor backend +policy de query +``` + +### 11.5 Gros payloads + +`MAX_RAW_PAYLOAD_BYTES` et `MAX_RAW_ACCOUNT_DATA_BYTES` atteignent des tailles incompatibles avec une duplication naïve par row. + +Le design doit prévenir : + +```text +IPC massif involontaire +freeze frontend +DOM énorme +log du contenu +copie multiple en mémoire +``` + +### 11.6 Frontend sandbox + +Le frontend ne réalise : + +```text +aucun fetch réseau direct +aucun filesystem direct +aucune persistence localStorage/sessionStorage/IndexedDB de RAW +aucun dialog navigateur bloquant +``` + +Les capabilities Tauri restent minimales. + +### 11.7 Read-only V1 + +La disponibilité d'une capability write Store n'autorise pas automatiquement son exposition UI. + +La V1 est un Desk d'inspection et de query. + +Toute action destructive future devra posséder : + +```text +policy claire +confirmation Bootstrap +contrat backend dédié +threat model +canaris +release/tranche explicite +``` + +--- + +## 12. Première mission `0.3.8-pre.001` — gate obligatoire + +### 12.1 Vérification de la base + +Avant toute modification : + +```text +valider l'archive/base v0.3.7 +vérifier workspace.package.version +vérifier deltas/0.3.7/rel.001.md +vérifier l'absence de modifications inattendues +``` + +Exécuter la baseline pertinente : + +```bash +cargo fmt --all -- --check +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 +cargo check --workspace +cargo clippy --workspace --all-targets +``` + +Puis tests ciblés Store/Config avant changement si raisonnable. + +### 12.2 Audit du gabarit KSP + +Produire une matrice exacte : + +```text +élément +Config Desk +Wallet Desk +Backfill Desk +Solprices Desk +choix Store Desk +``` + +Auditer : + +```text +Cargo package lib/bin +main.rs / lib.rs / tauri.rs +splash/main lifecycle +assets/logo/font/favicon +SASS/SCSS +header/footer/navigation +frontend logging bridge +Tauri capabilities +package.json dependencies/devDependencies +vite/tsconfig/build hooks +bundle.resources Config +``` + +Le résultat doit dire explicitement : + +```text +GABARIT STORE DESK = KSP +``` + +### 12.3 Audit npm / DataTables + +Inventorier les versions réellement présentes dans `v0.3.7`. + +Vérifier que Config/Wallet Desk utilisent déjà : + +```text +datatables.net-bs5 +datatables.net-select-bs5 +``` + +Décider les modules strictement nécessaires à Store Desk. + +Ne pas ajouter `Select` si aucune sélection n'a de fonction réelle. + +### 12.4 Audit kbot3 fonctionnel + +Extraire l'archive dans un arbre isolé et produire la matrice : + +```text +fonction historique +fichier kbot3 observé +valeur UX +équivalent KSP actuel +classification REPRENDRE/REDESSINER/REPORTER/REJETER +``` + +Inclure au minimum : + +```text +store diag +raw diagnostics +DataTables helper +block pagination +replay-candidate tables +``` + +Aucun fichier kbot3 n'entre dans le payload KSP. + +### 12.5 Capability map Store + +Pour chaque read capability publique : + +```text +méthode +input +output +network semantics +pagination +payload size +safety +utilité UI +``` + +Inclure : + +```text +Store::runtime_snapshot +Store::health +list/get RawTransaction +get RawTransactionObservation +get retention/tombstone +list/get RawAccountState +get RawAccountObservation +``` + +### 12.6 Gap map + +Produire une liste séparée : + +```text +besoin UI +capability manquante +raison réelle +contrat backend-neutral candidat +backends à implémenter +tests requis +coût/sizing +``` + +Aucun gap n'est comblé dans l'app par SQL. + +### 12.7 Screen map + +Dessiner les vues/tabs/cartes et interactions principales. + +Inclure : + +```text +Overview +Transactions +Accounts +Observations ou détails observations +Detail +``` + +si justifié par le capability map. + +### 12.8 Table/column map + +Pour chaque table candidate, figer : + +```text +colonnes +format IPC +source KSP +backend filter vs local filter +sortable localement ? +copyable ? +detail-only ? +``` + +Ne pas écrire les DataTables avant cette map. + +### 12.9 Pagination map + +Décrire séparément : + +```text +Store first page +Store next cursor +Store previous/history +DataTables local page +DataTables local search +DataTables local sort +``` + +La distinction doit être visible jusque dans les labels UX. + +### 12.10 DTO/command map + +Lister les commands candidates, par exemple : + +```text +get_runtime_status +store_options +store_refresh_health +store_query_raw_transactions +store_get_raw_transaction_detail +store_query_raw_accounts +store_get_raw_account_detail +store_query_*_observations si support ajouté +``` + +Les noms sont candidats ; `pre.001` doit les recalibrer selon l'architecture finale. + +Pour chaque command : + +```text +request DTO +response DTO +Store capability consommée +state mutation éventuelle +secret/large-payload review +error mapping +``` + +### 12.11 Threat model + +Auditer au minimum : + +```text +hostile page sizes +hostile cursor/token +slot ranges inversés +pubkey invalide +payload 16 MiB +account data 16 MiB +u64 > JS safe integer +rapid refresh +query race / stale response +DataTable redraw race +Store close while query active +browser persistence +logging payload leak +backend/URI leak +``` + +### 12.12 Sizing + +Estimer chaque tranche au budget KSP 15–20 minutes. + +Si l'extension observation-listing ou une nouvelle surface de summary Store rend `0.3.8` trop grosse pour une session, **scinder la release avant le scaffold lourd**. + +### 12.13 Livrables obligatoires de `pre.001` + +Créer : + +```text +docs/plans/029-V0_3_8_STORE_DESK_PLAN.md +docs/validation/025-V0_3_8_STORE_DESK.md +deltas/0.3.8/pre.001.md +``` + +Le plan doit contenir : + +```text +base/gates +dependency map +gabarit KSP map +npm/DataTables map +kbot3 functional matrix +Store capability map +gap map +screen map +table/column map +pagination map +DTO/command map +threat model +prévision souple recalibrée +``` + +### 12.14 Critères de sortie de `pre.001` + +`pre.001` n'est fermé que si : + +```text +base exacte confirmée +règles/prompt lus +gabarit KSP identifié +npm base identifié depuis KSP +kbot3 classé fonctionnellement sans code repris +RAW capabilities exactes inventoriées +gaps observation/diagnostics explicités +tables/colonnes décidées ou questions bloquantes signalées +pagination Store/DataTables séparée +DTO/commands sketchés +threat model présent +sizing <= une session crédible +aucune implémentation lourde commencée +``` + +--- + +## 13. Prévision souple initiale des prereleases + +Point de départ à recalibrer obligatoirement par `pre.001` : + +```text +pre.001 audit/sizing + KSP template/npm + kbot3 matrix + Store capability/gap/table/pagination maps +pre.002 scaffold ksp-app-store-desk KSP + ports 1438/1439 + shell/splash/tracing + DataTables retenu +pre.003 Config composite + Store lifecycle + Overview/health/runtime safe +pre.004 RawTransaction query/page/detail + retention/tombstone read projection +pre.005 RawAccountState query/page/detail + pubkey/slot filters +pre.006 Store API/listing extensions observations ou summaries si pre.001 les justifie, avec backend conformance +pre.007 observations transaction/account UI + provenance safe + intégration des extensions retenues +pre.008 pagination/cursor UX + DataTables local filtering/sorting + responsive/detail polish +pre.009 security/dependency/composition/hardening + release completeness +pre.010 gate technique final + workspace + cargo tree + cargo tauri build + smoke Store read-only opt-in +pre.011 réconciliation documentaire finale +pre.012 prompt suivant + CHANGELOG + ROADMAP uniquement +rel.001 publication stable v0.3.8 +``` + +Cette trajectoire est **souple**. + +Si aucune extension Store n'est requise, `pre.006` est réaffectée/supprimée et les numéros se tassent. + +Si une extension Store backend-neutral est plus large qu'une tranche bornée, scinder la release avant de transformer `0.3.8` en refonte Store cachée. + +Les trois responsabilités finales restent séparées : + +```text +gate technique/live +réconciliation documentaire +préparation publication minimale +``` + +--- + +## 14. Versionnement, deltas, commits, archives et tags + +Version Cargo : + +```text +0.3.8-pre.1 +0.3.8-pre.2 +... +0.3.8-pre.N.fix.M +``` + +Deltas : + +```text +deltas/0.3.8/pre.001.md +deltas/0.3.8/pre.002.md +... +deltas/0.3.8/pre.NNN-fix.MMM.md +deltas/0.3.8/rel.001.md +``` + +Commits : + +```text +v0.3.8-pre.001 +v0.3.8-pre.002 +v0.3.8-pre.NNN-fix.MMM +v0.3.8-rel.001 +``` + +Ces chaînes sont des **messages/identités de commit**, pas des tags prerelease. + +Aucun tag prerelease. + +Publication stable uniquement : + +```text +v0.3.8 +``` + +Archive de livraison : + +```text +ksp-general-.zip +``` + +Règles : + +```text +delta minimal +seuls fichiers ajoutés/modifiés + delta +header version incrémenté uniquement si fichier réellement changé +code/build/runtime/config/test-code -> workspace version synchronisée +fix doc-only -> ne pas bumper workspace version artificiellement +fix reste dans la lane de la prerelease d'origine +``` + +Chaque prerelease/fix est commité conformément aux règles KSP. + +--- + +## 15. Procédure d'application et validation opérateur + +Après chaque tranche Rust : + +```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.8 +cargo check --workspace +cargo clippy --workspace --all-targets +``` + +Puis tests ciblés des crates touchées. + +Si `ksp-store-api`, `ksp-store-lib` ou `ksp-store-postgres-lib` sont étendus : + +```bash +cargo test -p ksp-store-api +cargo test -p ksp-store-lib +cargo test -p ksp-store-postgres-lib +cargo check -p ksp-store-lib --no-default-features +``` + +Application : + +```bash +(cd crates/ksp-app-store-desk && cargo tauri dev) +``` + +Ne jamais lancer directement : + +```bash +npm run dev +npm run build +``` + +pour le cycle applicatif normal ; `KSP-APP-034` impose Tauri crate-local. + +`npm` direct sert seulement à installer/mettre à jour les dépendances déclarées. + +Les `cargo tree` sont exécutés lorsque le graphe change et au gate final : + +```bash +cargo tree -p ksp-app-store-desk --edges normal +cargo tree -p ksp-app-store-desk -e features +cargo tree -p ksp-store-lib --edges normal +cargo tree -p ksp-store-lib -e features +cargo tree --duplicates +``` + +Gate final Tauri, en dernière opération : + +```bash +(cd crates/ksp-app-store-desk && cargo tauri build) +``` + +--- + +## 16. Tests attendus + +### 16.1 Package / desktop contract + +```text +package lib + bin +run public +ports 1438/1439 stricts +beforeDevCommand/beforeBuildCommand crate-local +splash/main lifecycle KSP +assets/styles/fonts conformes au gabarit KSP +capabilities minimales +tracing bridge +bundle.resources Config +``` + +### 16.2 Dependency boundary + +```text +app -> ksp-config-lib / ksp-logging-lib / ksp-store-lib seulement selon map retenue +pas de ksp-store-api direct +pas de backend PostgreSQL +pas de SQL +pas de transport/provider +pas de crates Solana externes +``` + +### 16.3 Config / Store lifecycle + +```text +composite Store Desk valide +target Store sélectionné +network projeté sûrement +Store open/health/close +wrong/invalid Config safe +shutdown borné +``` + +### 16.4 RawTransaction + +```text +first page +next page +ascending/descending +slot range +invalid/reversed range +page limit hostile +reference projection +one detail load +payload metadata exact +retention Full/Archived/Purged +tombstone present/absent +large payload not duplicated in rows +``` + +### 16.5 RawAccountState + +```text +first/next page +ascending/descending +pubkey filter +slot range +reference identity exact +owner/lamports/executable/rent_epoch/data_len +u64 JS-safe projection +large data detail-only +``` + +### 16.6 Observations + +Si listing ajouté : + +```text +transaction observations page/query +account observations page/query +stable keyset/cursor semantics +entity filter +provenance projection +optional account metadata +no source payload bytes +``` + +Si aucune extension n'est ajoutée, les tests doivent prouver la UX réellement retenue pour accéder aux observations sans prétendre à un listing inexistant. + +### 16.7 Pagination/DataTables + +```text +Store cursor opaque +next navigation correct +previous/history semantics correctes si présentes +DataTables filter local uniquement +local sort n'altère pas query Store +redraw ne duplique pas rows/listeners +table destroy/recreate propre si utilisé +``` + +### 16.8 Frontend/security + +```text +no fetch +no filesystem +no localStorage/sessionStorage/IndexedDB RAW +no SQL/URI/credential +no cursor parsing +no payload logging +no browser native dialogs +safe error projection +safe instrumentation +``` + +### 16.9 Hardening + +```text +module inventory +command inventory +DTO inventory +npm dependency inventory +KSP template canaries +backend firewall +large-value/bounds adversarial tests +release completeness +``` + +### 16.10 Build / live + +Gate final : + +```bash +cargo test --workspace --all-targets --all-features +(cd crates/ksp-app-store-desk && cargo tauri build) +``` + +Un smoke PostgreSQL réel est opt-in si un target sûr est disponible : + +```text +open Store +health ready +load one transaction page +load one account page +open one detail +close cleanly +``` + +Il doit être **read-only** et ne doit ni purge, ni archive, ni mutate les données de l'opérateur. + +--- + +## 17. Critères de clôture de `0.3.8` + +La release devient stable seulement si : + +```text +ksp-app-store-desk suit le gabarit KSP +ports 1438/1439 corrects +npm de base dérivé de KSP, pas de kbot3 +DataTables intégré selon le pattern KSP retenu +Config + Store lifecycle corrects +health/runtime sûrs visibles +RawTransaction table navigable +RawAccountState table navigable +observations consultables selon le contrat décidé en pre.001 +retention/tombstones transaction visibles en lecture +Store pagination opaque correcte +DataTables local clairement séparé de la pagination Store +grands payloads non dupliqués dans les rows +aucun SQL/backend physique/provider dans app/frontend +aucun direct ksp-store-api pour contourner la façade +aucune action destructive V1 non cadrée +security/dependency/completeness verts +workspace gate vert +cargo tree pertinent audité +cargo tauri build vert +smoke read-only exécuté ou explicitement non requis selon décision pre.001 +README/USAGE/plan/validation réconciliés dans la tranche documentaire +prompt 0.3.9 + CHANGELOG + ROADMAP uniquement dans la dernière prerelease +aucun rattrapage dans rel.001 +``` + +Si une surface d'observation nécessaire ne peut pas être ajoutée proprement dans le budget/session, la release doit être redécoupée **avant** de fermer une V1 qui contourne les contrats Store. + +--- + +## 18. Release/session suivante envisagée + +La release suivante reste : + +```text +0.3.9 — ksp-worker-api +``` + +Mission prévue : + +```text +API générique lifecycle/health/progression des services continus +latest-value inspiré du pattern Job validé +sémantique Worker distincte des jobs terminables +pas de fusion avec Store notifications post-commit +``` + +Puis : + +```text +0.3.10 ksp-worker-raw-transaction-ingest-lib +0.3.11 ksp-app-raw-transaction-ingest-desk +``` + +`ksp-app-store-desk` restera l'outil de consultation détaillée des données persistées et évoluera avec les nouvelles couches Store au lieu d'être remplacé par une seconde application de browsing. + +--- + +## 19. Instruction d'ouverture + +Au début de la session `0.3.8` : + +1. confirmer la base stable `v0.3.7` ou l'archive stable autoritaire ; +2. vérifier `workspace.package.version = 0.3.7` et `deltas/0.3.7/rel.001.md` ; +3. lire les règles dans l'ordre de la section 3 ; +4. relire architecture Store + Apps ; +5. relire la clôture Store `0.3.1`–`0.3.4` et Backfill Desk `0.3.7` ; +6. exécuter la baseline avant modification lourde ; +7. auditer les quatre Desk KSP et identifier le gabarit réellement courant ; +8. inventorier leurs dépendances npm et confirmer la base KSP ; +9. auditer DataTables depuis Config/Wallet Desk KSP ; +10. extraire kbot3 séparément et l'auditer **uniquement** comme référence fonctionnelle/UX ; +11. produire la matrice kbot3 REPRENDRE/REDESSINER/REPORTER/REJETER ; +12. inventorier toutes les read capabilities Store actuelles ; +13. produire la gap map observations/diagnostics/summaries ; +14. produire le screen map ; +15. produire le table/column map ; +16. produire le pagination map Store vs DataTables ; +17. produire le DTO/command map ; +18. décider cursor ownership/IPC ; +19. décider payload/detail policy ; +20. produire le threat model ; +21. recalibrer la prévision de prereleases au budget KSP ; +22. créer plan, validation et `pre.001` ; +23. **ne pas commencer le scaffold lourd, ne pas copier kbot3 et ne pas écrire de SQL/app query avant la fermeture cohérente de ce gate**. + +La première réponse de travail de la nouvelle session doit être un **audit/sizing `0.3.8-pre.001` complet** : gabarit KSP, npm/DataTables KSP, matrice kbot3 fonctionnelle, Store capability/gap map, screen/table/pagination maps, DTO/commands, threat model et forecast recalibré — pas une Store Desk déjà implémentée.