khadhroony-solana-project/deltas/0.3.8/pre.003.md

Delta 0.3.8-pre.003 — contrats Store d’inspection et tracing Store Desk

Base requise

Base directe attendue :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 à :

RawPageCursor
RawPageRequest
RawPage<T>
RawTransactionQuery
RawAccountStateQuery
list_raw_transactions
list_raw_account_states

La frontière reste :

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 :

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

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

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

aucun

Validations exécutées dans l’environnement d’assemblage

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 :

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 :

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.