# 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.