274 lines
8.7 KiB
Markdown
274 lines
8.7 KiB
Markdown
<!-- file: deltas/0.3.8/pre.003.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Delta `0.3.8-pre.003` — contrats Store d’inspection et tracing Store Desk
|
||
|
||
## Base requise
|
||
|
||
Base directe attendue :
|
||
|
||
```text
|
||
0.3.8-pre.002-fix.001
|
||
workspace.package.version = 0.3.8-pre.2.fix.1
|
||
```
|
||
|
||
Le gate opérateur fourni pour cette base est vert : audits Rust/Markdown, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, suite `ksp-app-store-desk` et arbres Cargo ont tous été exécutés sans échec après le fix Vite/Clippy.
|
||
|
||
La livraison est :
|
||
|
||
```text
|
||
0.3.8-pre.003
|
||
workspace.package.version = 0.3.8-pre.3
|
||
commit = v0.3.8-pre.003
|
||
tag = aucun
|
||
```
|
||
|
||
## Objectif
|
||
|
||
Matérialiser la primitive backend-neutral d’inspection RAW décidée en `pre.001`, sans modifier le chemin cursor/keyset canonique et sans ouvrir PostgreSQL dans cette tranche.
|
||
|
||
Le delta ferme également deux invariants Store Desk explicitement demandés après `pre.002-fix.001` :
|
||
|
||
```text
|
||
tracing développement Store Desk = supertrace
|
||
interaction frontend significative = événement KSP tracé
|
||
```
|
||
|
||
Aucun Store runtime n’est ouvert par l’application et aucun SQL n’est ajouté.
|
||
|
||
## Contrats Store d’inspection
|
||
|
||
`ksp-store-api` ajoute un modèle séparé de la pagination cursor :
|
||
|
||
```text
|
||
RawInspectionPageRequest
|
||
offset: u64
|
||
limit: RawPageLimit
|
||
|
||
RawInspectionPage<T>
|
||
items
|
||
total_items
|
||
filtered_items
|
||
```
|
||
|
||
La sémantique des counts est exacte :
|
||
|
||
- `total_items` = nombre d’entités dans le scope obligatoire de la query avant filtres optionnels ;
|
||
- `filtered_items` = nombre d’entités après filtres optionnels ;
|
||
- `items` = uniquement la fenêtre random-access demandée.
|
||
|
||
Les incohérences `filtered_items > total_items` ou `items.len() > filtered_items` sont rejetées par le modèle.
|
||
|
||
Les queries ajoutées sont :
|
||
|
||
```text
|
||
RawTransactionInspectionQuery
|
||
network
|
||
slots
|
||
direction
|
||
RawInspectionPageRequest
|
||
|
||
RawAccountStateInspectionQuery
|
||
network
|
||
pubkey?
|
||
slots
|
||
direction
|
||
RawInspectionPageRequest
|
||
```
|
||
|
||
Le `u64` offset ne reçoit aucun plafond politique artificiel dans `ksp-store-api`. La conversion vers une limite physique backend et le rejet pré-I/O des offsets non représentables appartiennent aux vertical slices PostgreSQL `pre.004` / `pre.005`.
|
||
|
||
## Summaries sans gros bytes
|
||
|
||
`RawTransactionSummary` expose uniquement :
|
||
|
||
```text
|
||
reference
|
||
slot
|
||
block_time
|
||
format_id
|
||
format_version
|
||
content_hash
|
||
payload_size_bytes?
|
||
retention_state
|
||
```
|
||
|
||
Le payload canonique n’est jamais contenu dans le summary. La taille est `None` pour `Purged`; un état qui conserve logiquement le payload exige une taille valide, non nulle et bornée par `MAX_RAW_PAYLOAD_BYTES`.
|
||
|
||
`RawAccountStateSummary` expose uniquement :
|
||
|
||
```text
|
||
reference
|
||
lamports
|
||
owner
|
||
executable
|
||
rent_epoch
|
||
data_length_bytes
|
||
```
|
||
|
||
Les bytes account data ne sont jamais contenus dans le summary et `data_length_bytes` reste borné par `MAX_RAW_ACCOUNT_DATA_BYTES`.
|
||
|
||
## Capabilities
|
||
|
||
Deux traits read object-safe sont ajoutés sans modifier les traits RAW historiques :
|
||
|
||
```text
|
||
RawTransactionInspectionRead::inspect_raw_transactions
|
||
RawAccountStateInspectionRead::inspect_raw_account_states
|
||
```
|
||
|
||
Ils retournent `RawInspectionPage<...Summary>`.
|
||
|
||
`ksp-store-lib` réexporte les nouveaux types et traits afin que les consommateurs futurs restent dépendants de la façade commune. En revanche :
|
||
|
||
```text
|
||
Store n’implémente pas encore les deux traits d’inspection
|
||
PostgresBackend n’implémente pas encore les deux traits d’inspection
|
||
```
|
||
|
||
L’inventaire canonique existant reste donc exactement à dix implementations RAW sur la façade et dix sur le backend PostgreSQL. Les implementations d’inspection sont réservées à `pre.004` et `pre.005`.
|
||
|
||
## Pagination canonique préservée
|
||
|
||
Aucune modification n’est apportée à :
|
||
|
||
```text
|
||
RawPageCursor
|
||
RawPageRequest
|
||
RawPage<T>
|
||
RawTransactionQuery
|
||
RawAccountStateQuery
|
||
list_raw_transactions
|
||
list_raw_account_states
|
||
```
|
||
|
||
La frontière reste :
|
||
|
||
```text
|
||
cursor/keyset = workers/backfill/replay/navigation durable
|
||
inspection offset/count = operator/admin random-access
|
||
DataTables = futur unique pager visuel de Store Desk
|
||
```
|
||
|
||
Aucun terme ou DTO DataTables (`draw`, `recordsTotal`, `recordsFiltered`) n’entre dans `ksp-store-api`.
|
||
|
||
## Tracing Store Desk
|
||
|
||
Le scaffold Store Desk demandait auparavant le profil par défaut de `std.logging` (`local_dev`). Il sélectionne maintenant explicitement :
|
||
|
||
```text
|
||
DEVELOPMENT_LOGGING_PROFILE = supertrace
|
||
```
|
||
|
||
Le fallback local reste `LogFilterLevel::Trace` si la Config managed n’est pas disponible.
|
||
|
||
Le frontend conserve les événements spécifiques existants pour navigation et Refresh et renforce le logging générique :
|
||
|
||
- clics des boutons non spécialisés via un listener délégué au `document`, ce qui couvre aussi les boutons dynamiques créés ultérieurement par DataTables ;
|
||
- clic d’un contrôle tab ;
|
||
- activation effective d’un tab Bootstrap ;
|
||
- changement d’un `input`, `select` ou `textarea` ;
|
||
- IPC requested/completed/failed via le bridge existant.
|
||
|
||
Les valeurs de filtres, payloads, URI et secrets ne sont pas ajoutés aux logs. Les tranches DataTables métier devront instrumenter explicitement page, page-length, redraw/query et actions détail sans logguer les données RAW.
|
||
|
||
## Fichiers ajoutés
|
||
|
||
```text
|
||
crates/ksp-store-api/src/model/raw_inspection.rs
|
||
crates/ksp-store-api/unit_tests/model/raw_inspection.rs
|
||
deltas/0.3.8/pre.003.md
|
||
```
|
||
|
||
## Fichiers modifiés
|
||
|
||
```text
|
||
Cargo.toml
|
||
crates/ksp-app-store-desk/frontend/ts/main.ts
|
||
crates/ksp-app-store-desk/src/bootstrap.rs
|
||
crates/ksp-app-store-desk/src/constants.rs
|
||
crates/ksp-app-store-desk/src/lib.rs
|
||
crates/ksp-app-store-desk/tests/desktop_security.rs
|
||
crates/ksp-store-api/src/capability/raw_account.rs
|
||
crates/ksp-store-api/src/capability/raw_transaction.rs
|
||
crates/ksp-store-api/src/lib.rs
|
||
crates/ksp-store-api/src/model.rs
|
||
crates/ksp-store-api/tests/dependency_boundary.rs
|
||
crates/ksp-store-api/tests/external_backend.rs
|
||
crates/ksp-store-api/tests/public_api.rs
|
||
crates/ksp-store-api/tests/release_completeness.rs
|
||
crates/ksp-store-api/tests/security_hardening.rs
|
||
crates/ksp-store-lib/src/lib.rs
|
||
crates/ksp-store-lib/tests/public_api.rs
|
||
docs/plans/029-V0_3_8_STORE_DESK_PLAN.md
|
||
docs/validation/025-V0_3_8_STORE_DESK.md
|
||
```
|
||
|
||
## Fichiers supprimés
|
||
|
||
```text
|
||
aucun
|
||
```
|
||
|
||
## Validations exécutées dans l’environnement d’assemblage
|
||
|
||
```text
|
||
python3 scripts/audit_rust_workspace_rules.py
|
||
-> General Rust rule audit: clean
|
||
-> Rust export completeness audit: 0 candidate(s)
|
||
-> KSP workspace Rust rule audit: clean
|
||
|
||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
|
||
-> Markdown table audit: clean
|
||
```
|
||
|
||
Contrôles ciblés supplémentaires :
|
||
|
||
```text
|
||
Store API exact root export inventory: clean
|
||
Store API production module inventory: raw_inspection ajouté, aucun module physique
|
||
Store API UI/SQL boundary: clean
|
||
External backend object-safety canary: source complete pour 12 traits
|
||
ksp-store-lib inspection reexports: clean
|
||
Store facade canonical RAW implementations: 10 inchangées
|
||
PostgreSQL backend canonical RAW implementations: 10 inchangées
|
||
Store/PostgreSQL inspection implementations: absentes comme prévu
|
||
Store Desk supertrace selection: clean
|
||
Store Desk delegated button/tab/control tracing: clean
|
||
TypeScript syntax audit: clean (5 fichiers, TS 5.8.3)
|
||
Manifest parse: clean
|
||
```
|
||
|
||
## Validations non exécutées dans l’environnement d’assemblage
|
||
|
||
`cargo` et `rustfmt` ne sont pas disponibles dans le sandbox d’assemblage. Le gate opérateur requis est :
|
||
|
||
```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
|
||
cargo check --workspace
|
||
cargo clippy --workspace --all-targets
|
||
cargo test -p ksp-store-api
|
||
cargo test -p ksp-store-lib
|
||
cargo check -p ksp-store-lib --no-default-features
|
||
cargo test -p ksp-app-store-desk
|
||
cargo tree -p ksp-store-api --edges normal
|
||
cargo tree -p ksp-store-lib --edges normal
|
||
```
|
||
|
||
## Invariants de fermeture
|
||
|
||
- aucune reprise de code kbot3 ;
|
||
- aucun SQL ou type PostgreSQL dans `ksp-store-api`, `ksp-store-lib` ou Store Desk ;
|
||
- aucun remplacement du cursor/keyset RAW ;
|
||
- aucune implementation backend/facade des nouveaux traits dans cette tranche ;
|
||
- aucun `Store::open` supplémentaire dans Store Desk ;
|
||
- aucune dépendance Store directe ajoutée à Store Desk ;
|
||
- un seul pager DataTables restera visible quand l’UI métier sera branchée ;
|
||
- `supertrace` et le tracing des interactions frontend sont désormais des invariants explicites de la phase de développement.
|
||
|
||
## Suite prévue
|
||
|
||
Après gate opérateur vert, `pre.004` implémente **uniquement le vertical slice PostgreSQL + façade `RawTransactionInspectionRead`** : summary query, counts exacts, offset/limit checked et maintien intégral du listage keyset existant.
|