44 KiB
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 :
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 :
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 :
0.3.8
La première tranche est obligatoirement :
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 :
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 :
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 :
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 :
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 :
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 :
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
Pour tout Markdown touché :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
khadhroony-bot3_v0.5.3-pre.005-fix010-thelatest1.zip
ou l'archive équivalente explicitement fournie par l'opérateur.
Inspecter au minimum :
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 :
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 :
REPRENDRE FONCTIONNELLEMENT
REDESSINER POUR LES CONTRATS KSP
REPORTER
REJETER
Interdictions :
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 :
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 :
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 :
Store::open
Store::runtime_snapshot
Store::health
Store::close
Une instance Store représente :
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 :
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 :
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 :
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 :
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 :
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 :
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
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
RawTransaction.payload complet
RawAccountState.data complet
Décider une vue détail à la demande :
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 :
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 :
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 :
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 :
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 :
package = ksp-app-store-desk
lib = ksp_app_store_desk_lib
bin = ksp-app-store-desk
Attendus :
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 :
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 :
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 :
StoreRuntimeSnapshot
StoreHealthSnapshot
Exemples sûrs :
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 :
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 :
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 :
slot range optionnelle
pubkey filter optionnel
direction
page size
cursor navigation
liste des références
détail state à la demande
Colonnes candidates :
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 :
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 :
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 :
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 :
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 :
payload RAW
account bytes
URI Store
credentials
cursor opaque
contenu de recherche utilisateur sensible
10. Hors périmètre explicite
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 :
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 :
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 :
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 :
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 :
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 :
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 :
IPC massif involontaire
freeze frontend
DOM énorme
log du contenu
copie multiple en mémoire
11.6 Frontend sandbox
Le frontend ne réalise :
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 :
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 :
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 :
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 :
élément
Config Desk
Wallet Desk
Backfill Desk
Solprices Desk
choix Store Desk
Auditer :
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 :
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à :
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 :
fonction historique
fichier kbot3 observé
valeur UX
équivalent KSP actuel
classification REPRENDRE/REDESSINER/REPORTER/REJETER
Inclure au minimum :
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 :
méthode
input
output
network semantics
pagination
payload size
safety
utilité UI
Inclure :
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 :
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 :
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 :
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 :
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 :
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 :
request DTO
response DTO
Store capability consommée
state mutation éventuelle
secret/large-payload review
error mapping
12.11 Threat model
Auditer au minimum :
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 :
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 :
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 :
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 :
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 :
gate technique/live
réconciliation documentaire
préparation publication minimale
14. Versionnement, deltas, commits, archives et tags
Version Cargo :
0.3.8-pre.1
0.3.8-pre.2
...
0.3.8-pre.N.fix.M
Deltas :
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 :
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 :
v0.3.8
Archive de livraison :
ksp-general-<delivery-id>.zip
Règles :
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 :
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 :
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 :
(cd crates/ksp-app-store-desk && cargo tauri dev)
Ne jamais lancer directement :
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 :
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 :
(cd crates/ksp-app-store-desk && cargo tauri build)
16. Tests attendus
16.1 Package / desktop contract
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
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
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
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
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é :
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
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
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
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 :
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 :
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 :
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 :
0.3.9 — ksp-worker-api
Mission prévue :
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 :
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 :
- confirmer la base stable
v0.3.7ou l'archive stable autoritaire ; - vérifier
workspace.package.version = 0.3.7etdeltas/0.3.7/rel.001.md; - lire les règles dans l'ordre de la section 3 ;
- relire architecture Store + Apps ;
- relire la clôture Store
0.3.1–0.3.4et Backfill Desk0.3.7; - exécuter la baseline avant modification lourde ;
- auditer les quatre Desk KSP et identifier le gabarit réellement courant ;
- inventorier leurs dépendances npm et confirmer la base KSP ;
- auditer DataTables depuis Config/Wallet Desk KSP ;
- extraire kbot3 séparément et l'auditer uniquement comme référence fonctionnelle/UX ;
- produire la matrice kbot3 REPRENDRE/REDESSINER/REPORTER/REJETER ;
- inventorier toutes les read capabilities Store actuelles ;
- produire la gap map observations/diagnostics/summaries ;
- produire le screen map ;
- produire le table/column map ;
- produire le pagination map Store vs DataTables ;
- produire le DTO/command map ;
- décider cursor ownership/IPC ;
- décider payload/detail policy ;
- produire le threat model ;
- recalibrer la prévision de prereleases au budget KSP ;
- créer plan, validation et
pre.001; - 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.