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