v0.3.8-pre.013

crates/ksp-app-store-desk/README.md

@@ -0,0 +1,106 @@
+<!-- file: crates/ksp-app-store-desk/README.md -->
+<!-- version: 1 -->
+
+# `ksp-app-store-desk`
+
+`ksp-app-store-desk` est l’application desktop spécialisée d’inspection read-only du Store KSP.
+
+Elle reste une couche de composition Tauri : Config sélectionne le profil Store et Logging, `ksp-store-lib` possède la façade backend-neutral et les contrats d’inspection, et le backend physique reste entièrement masqué à l’application comme au frontend.
+
+## Package
+
+```text
+package : ksp-app-store-desk
+lib     : ksp_app_store_desk_lib
+bin     : ksp-app-store-desk
+```
+
+Le binaire est un launcher mince. La bibliothèque applicative possède le bootstrap, le lifecycle Store, les DTOs Tauri, les commands, les projections de détail bornées et le bridge de tracing frontend.
+
+## Composition
+
+```text
+ksp-config-lib        -> composite, profils, secrets et runtime packagé
+ksp-core-lib          -> erreurs et primitives communes
+ksp-store-lib         -> façade Store backend-neutral et contrats RAW/inspection
+ksp-logging-lib       -> logging/tracing applicatif
+ksp-app-store-desk    -> orchestration Tauri + projections sûres read-only
+```
+
+L’application ne dépend pas directement de `ksp-store-api`, `ksp-store-postgres-lib`, `tokio-postgres` ou d’un autre backend physique. Elle ne possède aucun SQL.
+
+## Vues
+
+La surface utilisateur comprend :
+
+- **Overview** : état du runtime Store, health portable, réseau, backend logique, migration et compteurs de pool sûrs ;
+- **RAW Transactions** : inspection DataTables server-side, filtres de slot et direction, état de rétention et détail explicite ;
+- **RAW Accounts** : inspection DataTables server-side, filtre pubkey exact, plage de slots, direction et détail explicite ;
+- **Diagnostics** : projection sûre du shell, de Config et du runtime Store.
+
+Les détails Transaction et Account contiennent également leurs observations dans des DataTables server-side dédiées lorsque ces observations existent.
+
+## Pagination et inspection
+
+Store Desk utilise la surface d’inspection random-access de `ksp-store-lib` : `offset + limit` avec counts exacts. DataTables est l’unique propriétaire de la pagination visible et les tailles admises sont `25`, `50` et `100`.
+
+Cette voie d’inspection humaine ne remplace pas la pagination cursor/keyset du Store. Les workers, jobs et autres consumers machine peuvent continuer à utiliser `RawPageCursor` / `RawPageRequest`; Store Desk ne consomme pas ces cursors.
+
+Le frontend conserve `draw` localement et ne transmet ni search globale DataTables, ni ordre de colonnes arbitraire, ni cursor, ni réseau physique au Store.
+
+## Rows, détails et observations
+
+Les rows de table ne transportent jamais les bytes RAW complets :
+
+- Transaction : identité, slot, format, hash, taille éventuelle et état de rétention ;
+- Account : pubkey, slot, state hash, owner, lamports, executable, rent epoch et longueur de data ;
+- Observation : provenance d’acquisition sûre et metadata bornées, sans source payload bytes.
+
+Un détail est chargé explicitement pour une seule entité. Les previews payload Transaction et data Account sont limitées à **512 bytes**, rendues en hexadécimal et accompagnées de la taille exacte et d’un indicateur de troncature.
+
+Pour une Transaction, les états `Full`, `Archived` et `Purged` restent distincts. Un état `Purged` est représenté via son tombstone ; Store Desk n’offre aucune action d’archive, purge ou force-rehydrate.
+
+## Valeurs longues et copie
+
+Les signatures, hashes, pubkeys, owners et autres identifiants longs sont tronqués visuellement au centre tout en restant disponibles via tooltip et bouton de copie. La copie n’ajoute aucune capability Tauri : elle utilise le WebView et le tracing ne transporte que l’identifiant logique du champ, jamais la valeur copiée.
+
+## Config et réseaux
+
+Le composite dédié est :
+
+```text
+cfg.composite.ksp-app-store-desk
+```
+
+Les profils committed couvrent `mainnet`, `devnet` et `testnet`. Mainnet est le profil par défaut. Le composite contient uniquement Logging + Store ; aucun Transport n’est ouvert par l’application.
+
+Le frontend ne reçoit jamais URI Store, credential, secret Config, SQL, handle pool ou type backend physique.
+
+## Sécurité et ownership
+
+Store Desk est read-only par contrat applicatif : aucun command Tauri d’écriture Store n’est exposé. Les capabilities guest restent limitées à `core:default` et `tracing:default`.
+
+Le frontend ne possède ni accès réseau navigateur direct, ni persistence navigateur des données RAW, ni accès filesystem, ni dialogue natif pour contourner les façades KSP.
+
+Les comptes et counts `u64` susceptibles d’excéder le domaine entier sûr JavaScript traversent IPC sous forme décimale et sont vérifiés avant conversion côté TypeScript.
+
+## Ports et développement
+
+```text
+Vite HTTP : 1438
+Vite WS   : 1439
+```
+
+Lancement :
+
+```bash
+(cd crates/ksp-app-store-desk && cargo tauri dev)
+```
+
+Build production :
+
+```bash
+(cd crates/ksp-app-store-desk && cargo tauri build)
+```
+
+Voir également [`USAGE.md`](USAGE.md), [`../ksp-store-lib/README.md`](../ksp-store-lib/README.md), [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) et [`../../docs/validation/025-V0_3_8_STORE_DESK.md`](../../docs/validation/025-V0_3_8_STORE_DESK.md).

crates/ksp-app-store-desk/USAGE.md

@@ -0,0 +1,149 @@
+<!-- file: crates/ksp-app-store-desk/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de `ksp-app-store-desk`
+
+## 1. Lancement
+
+Depuis la racine du workspace :
+
+```bash
+(cd crates/ksp-app-store-desk && cargo tauri dev)
+```
+
+Le runtime charge le composite Store Desk via `ksp-config-lib`, initialise Logging puis ouvre le Store sélectionné via `ksp-store-lib`.
+
+## 2. Profil et readiness
+
+Le composite `cfg.composite.ksp-app-store-desk` sélectionne un profil Logging et un profil Store. Mainnet est le profil par défaut ; Devnet et Testnet sont également définis dans la configuration committed.
+
+La vue **Overview** expose notamment :
+
+```text
+Store open
+health state
+profile
+network
+backend kind
+migration version / pending migrations
+pool size / capacity / available / waiting
+```
+
+Ces informations sont des projections portables. Elles ne contiennent jamais URI PostgreSQL, credential, secret ou handle physique.
+
+## 3. RAW Transactions
+
+La vue **RAW Transactions** charge les données côté serveur via la façade d’inspection Store.
+
+Filtres disponibles :
+
+```text
+slot minimum
+slot maximum
+direction ascending / descending
+```
+
+La table affiche des summaries sans payload RAW complet. Les signatures et hashes longs restent copiables sans que leur valeur soit journalisée.
+
+Le bouton de détail recharge explicitement une seule Transaction. Le modal affiche les metadata canoniques, l’état de rétention et, lorsqu’un payload est encore retenu, un preview hexadécimal limité à 512 bytes avec taille exacte et indicateur de troncature.
+
+Un état `Purged` est présenté à partir du tombstone disponible. Aucune opération d’archive, purge ou force-rehydrate n’est proposée par l’application.
+
+## 4. RAW Accounts
+
+La vue **RAW Accounts** utilise le même modèle d’inspection server-side.
+
+Filtres disponibles :
+
+```text
+pubkey exacte
+slot minimum
+slot maximum
+direction ascending / descending
+```
+
+La table ne transporte pas les bytes Account. Elle expose seulement les metadata utiles : pubkey, slot, state hash, owner, lamports, executable, rent epoch et longueur de data.
+
+Le détail recharge exactement l’identité `(pubkey, slot, state_hash)` puis affiche un preview hexadécimal de data limité à 512 bytes, la longueur exacte et l’indicateur de troncature.
+
+## 5. Observations
+
+Les modals Transaction et Account contiennent une table **Observations** associée à l’entité actuellement ouverte.
+
+La table est server-side et expose uniquement de la provenance sûre : provider logique, protocole, méthode/origine d’acquisition, timestamps, endpoint/session/filter/commitment lorsqu’ils existent, hash/taille de source et metadata Account optionnelles admises.
+
+Les bytes du payload source ne traversent jamais IPC.
+
+## 6. Pagination DataTables
+
+Les tables Transactions, Accounts et Observations utilisent DataTables comme unique pager visible.
+
+Tailles disponibles :
+
+```text
+25
+50
+100
+```
+
+Le frontend mappe `start` vers l’offset Store et `length` vers la limite. Les counts exacts restent des chaînes décimales jusqu’à vérification du domaine `Number.MAX_SAFE_INTEGER`.
+
+La pagination d’inspection est distincte de la pagination cursor/keyset utilisée par les consumers machine du Store. Store Desk n’accepte ni cursor, ni search globale DataTables, ni tri arbitraire de colonnes.
+
+## 7. Rafraîchissement et filtres
+
+**Refresh** redessine la table concernée avec ses filtres Store explicites. Un changement de filtre repart de la première page.
+
+Les valeurs de filtre sont validées côté Rust : slots décimaux, pubkey canonique et direction autorisée. Elles ne sont pas injectées dans les logs frontend.
+
+## 8. Valeurs longues et copie
+
+Les valeurs longues sont affichées sous forme tronquée au centre. Le survol permet de consulter la valeur complète et le bouton de copie copie la valeur actuellement affichée par le frontend.
+
+Les événements de tracing de copie transportent uniquement un `fieldId` logique. Ils ne contiennent jamais signature, pubkey, owner, hash ou preview hex.
+
+## 9. Read-only et frontières
+
+Store Desk est un outil d’inspection. Il ne fournit aucune commande pour :
+
+```text
+écrire une entité RAW
+ajouter une observation
+archiver
+purger
+force-rehydrate
+démarrer un backfill
+démarrer un worker
+modifier la configuration Store
+```
+
+Ces responsabilités appartiennent aux composants KSP propriétaires.
+
+Le frontend ne reçoit jamais :
+
+```text
+URI Store
+credentials/secrets
+SQL
+handles backend/pool
+payload RAW complet
+data Account complète
+source payload bytes
+contexte d’erreur arbitraire
+```
+
+## 10. Fermeture
+
+La fermeture de la fenêtre principale bloque les nouvelles admissions puis ferme le Store de manière bornée avant de terminer le process.
+
+Le shutdown applicatif n’effectue aucune mutation métier de rétention ou de données.
+
+## 11. Build production
+
+Depuis la racine du workspace :
+
+```bash
+(cd crates/ksp-app-store-desk && cargo tauri build)
+```
+
+Le build frontend passe par TypeScript puis Vite avant le build Tauri. Les resources Config enregistrées sont packagées selon le contrat commun des applications Desk KSP.