1841 lines
44 KiB
Markdown
1841 lines
44 KiB
Markdown
<!-- file: prompts/027-V0_3_8_START_PROMPT.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# 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-<delivery-id>.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.
|