From f4331cf48af07e1858ade378ffef1ed076696670 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sat, 1 Aug 2026 11:28:43 +0200 Subject: [PATCH] v0.1.0-pre.075 --- KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md | 480 +++--------------- docs/README.md | 3 +- docs/audits/PRE_0_4_6_STATIC_CODE_AUDIT.md | 57 +++ docs/guides/DEVNET_0_4_6_OPERATOR_GUIDE.md | 99 ++++ ...WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md | 116 +++++ kb-app-demo-desktop/CHANGELOG.md | 7 +- kb-app-demo-desktop/TODO.md | 5 +- kb-config/CHANGELOG.md | 6 +- kb-pipeline-demo-scenarios/CHANGELOG.md | 6 +- scripts/audit_pre_0_4_6_static_contracts.py | 113 +++++ scripts/audit_rust_workspace_rules.py | 5 +- 11 files changed, 484 insertions(+), 413 deletions(-) create mode 100644 docs/audits/PRE_0_4_6_STATIC_CODE_AUDIT.md create mode 100644 docs/guides/DEVNET_0_4_6_OPERATOR_GUIDE.md create mode 100644 docs/validation/WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md create mode 100644 scripts/audit_pre_0_4_6_static_contracts.py mode change 100755 => 100644 scripts/audit_rust_workspace_rules.py diff --git a/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md b/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md index f376dfb..3b3984b 100644 --- a/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md +++ b/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md @@ -1,396 +1,96 @@ - + -# Clôture de la migration `khadhroony-bot3` +# Clôture de la migration vers `0.4.6` -Ce fichier est temporaire. Il doit disparaître lorsque la migration est close, que la documentation active décrit uniquement `khadhroony-bot3`, et que la version du workspace est alignée sur `0.4.7`. +Ce document temporaire contient uniquement les tâches encore nécessaires pour aligner officiellement `khadhroony-bot3` sur le périmètre fonctionnel de `khadhroony-bot2 0.4.6`. -## Principes de clôture +Les travaux Metaplex Token Metadata sont reportés entre `0.4.6` et `0.4.7`. Anchor, le wallet complet, le split de configuration, les protocoles applicatifs et les transports avancés restent dans leurs versions ROADMAP respectives. -- Une case n’est cochée qu’après preuve par recherche, compilation, test, audit, requête SQL ou validation runtime. -- Les noms, modules et documents actifs doivent décrire Bot3 comme le produit courant, sans récit permanent de migration depuis Bot2. -- Les protocoles applicatifs Pump.fun, Raydium, Meteora, Jupiter, autres AMM et launchpads restent hors périmètre tant que Solana Core, SPL, Metaplex Token Metadata et Anchor ne sont pas clôturés. -- Les rappels d’amélioration non bloquants doivent être déplacés vers `docs/IDEA_REMINDERS.md`, pas conservés dans cette checklist. -- La documentation finale décrit l’état courant. Elle ne doit pas accumuler un journal de changements par version dans les README. +## 1. Preuves déjà acquises -## État validé de `0.1.0-pre.061` +- [x] Onze crates consolidées et documentées. +- [x] Solana Core, SPL Memo, SPL Token classique, ATA et Token-2022 migrés jusqu’au périmètre historique `0.4.6`. +- [x] System Transfer et Memo v4 validés de bout en bout sur Devnet. +- [x] ATA classique, ATA Token-2022, SPL Token classique et huit opérations Token-2022 déclarés validés dans le rapport `pre.062`. +- [x] Registre ElGamal conservé comme exception documentée, sans validation réseau déclarée. +- [x] Seul `kb-config` dépend directement de `dotenvy`. +- [x] Tous les appels frontend `invoke(...)` détectés correspondent à une commande Tauri enregistrée. +- [x] La session WebSocket est stockée dans `AppState` et la fermeture de la fenêtre `demo_ws` ne déclenche pas statiquement de déconnexion. +- [x] La fermeture de la fenêtre principale déclenche la déconnexion globale de la session WebSocket. -- [x] Suite ciblée complète : toutes les crates principales réussissent leurs tests. -- [x] `kb-app-demo-desktop` : 116 tests réussis. -- [x] `kb-config` : 45 tests réussis. -- [x] `kb-core` : 2 tests réussis. -- [x] `kb-lib` : 625 tests réussis. -- [x] `kb-onchain-transport` : 113 tests réussis. -- [x] `kb-pipeline` : 89 tests réussis. -- [x] `kb-pipeline-demo-scenarios` : 35 tests réussis. -- [x] `kb-store` : 84 tests réussis. -- [x] `cargo check --workspace` réussi. -- [x] Audit général Rust propre. -- [x] Audit des exports Rust propre. -- [x] Audit spécifique Khadhroony propre. -- [x] `cargo clippy --all-targets` propre. -- [x] Démarrage Tauri, splash, PostgreSQL et fenêtres principales validés. -- [x] Extraction Core complète de 4 574 transactions raw : 4 574 extraites, 0 échec. -- [x] Replay complet de 11 880 instructions exécuté. -- [x] Les 6 faux échecs Metaplex ont été corrigés et rejoués avec succès. -- [x] Les 76 tentatives Loader malformées de transactions échouées sont désormais décodées comme observations non engagées. -- [x] Les 4 tags Loader v4 inconnus restent correctement classés `Unsupported`. -- [x] Aucune erreur de matérialisation observée pendant la campagne propre. -- [x] Les trois erreurs supplémentaires du replay ont été identifiées comme timeouts transitoires du pool PostgreSQL, distincts des échecs fonctionnels de décodage. -- [x] Revalider les suites après les correctifs `pre.061-delta-fix-004` et `pre.061-delta-fix-005` : 116 tests desktop, 625 tests `kb-lib`, suites consolidées et replay propre. +## 2. Nomenclature et données persistées -# 0. `0.1.0-pre.062` — validation Devnet +- [ ] Exécuter l’audit statique `scripts/audit_pre_0_4_6_static_contracts.py` dans le workspace réel. +- [ ] Vérifier l’absence de réintroduction des anciennes crates, anciens targets et anciennes identités persistées. +- [ ] Confirmer que les matrices actives et les registres compilés utilisent les identités canoniques. +- [ ] Rejouer System Transfer et Memo v4 après purge ou reconstruction des données dérivées si cette preuve n’a pas déjà été conservée après la migration de nomenclature. +- [ ] Documenter la preuve ou fermer explicitement ce replay si les rapports existants suffisent. -- [x] Séparer les DSN PostgreSQL Mainnet, Devnet et tests par variables d’environnement. -- [x] Résoudre les profils Devnet sans dépendre du nom historique `local_devnet`. -- [x] Autoriser une sélection explicite par l’interface ou `KB_DEVNET_PROFILE` pour les scénarios CLI/tests. -- [x] À l’ouverture des fenêtres Exécution Solana Core et Exécution SPL, connecter la base du profil sélectionné. -- [x] Créer les tables manquantes uniquement lorsque `auto_initialize_schema` l’autorise. -- [x] Refuser l’activation des commandes Devnet lorsque PostgreSQL est désactivé, non PostgreSQL ou incomplet. -- [x] Valider visuellement la préparation de la base Devnet dans les deux fenêtres : seul le profil `local_devnet` est proposé et les 13 tables PostgreSQL sont créées ou détectées. -- [ ] Exécuter les scénarios Devnet selon `docs/DEVNET_EXECUTION_GUIDE.md`. - - [x] Préparer le terminal Bash de contrôle et stocker les preuves sous `/tmp/devnet-validation/pre.062`. - - [x] Vérifier les CLI Solana/Agave et le genesis hash Devnet. - - [x] Financer le wallet persistant `local_devnet` via faucet Web. - - [x] Valider le transfert System de bout en bout : simulation, envoi, confirmation, balances, backfill, Core extraction et Decode replay sans erreur. - - [x] Valider SPL Memo v4 : simulation, confirmation finalisée, backfill, Core extraction, Decode replay, matérialisation et idempotence validés. - - [ ] Valider ATA et SPL Token classique. - - [ ] Valider ATA et scénarios Token-2022. - - [ ] Valider registre ElGamal selon les prérequis disponibles. +## 3. Desktop, Tauri et frontend +- [ ] Réduire `kb-app-demo-desktop/src/tauri.rs` à une couche mince de commandes et d’adaptation. +- [ ] Déplacer l’orchestration Decode replay, PostgreSQL et exécution encore substantielle vers les modules fonctionnels appropriés. +- [ ] Vérifier que les tests unitaires associés suivent les fonctions déplacées. +- [ ] Valider visuellement une dernière fois menus, séparateurs et absence de contrôles morts ou dupliqués. +- [ ] Vérifier les viewers et sorties de Decode replay, Exécution Solana Core et Exécution SPL. +- [ ] Vérifier le timeout HTTP et le comportement d’arrêt global. -# 1. Nettoyage structurel et nomenclature +## 4. Cycle de vie WebSocket -## 1.0 Convention globale des identités persistées +Exécuter le scénario [`docs/validation/WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md`](docs/validation/WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md). -- [x] Arrêter la notation hiérarchique par points pour les identités runtime et les codes persistés. -- [x] Ajouter la documentation normative `docs/OPERATION_NAMING_CONVENTION.md`. -- [x] Ajouter la matrice machine-readable `test-fixtures/contract-matrices/OPERATION_NAMING_MATRIX.json`. -- [x] Migrer les constantes et attentes actives de Solana Core, SPL Memo, SPL Token, Token-2022, ATA, registre ElGamal et Metaplex vers la notation canonique. -- [x] Ajouter une règle courte renvoyant vers la documentation et la matrice. -- [ ] Purger ou recréer la base `solana_devnet`, puis rejouer les preuves System Transfer et Memo v4 avec les nouveaux codes. -- [ ] Ajouter un audit final empêchant la réintroduction des anciennes valeurs contractuelles. -- [x] Corriger la frontière entre codes de registre `lower_snake_case` et identités persistées en notation par points. -- [x] Corriger le test de matrice pour rester propre sous Clippy sans assertion constante fausse. -- [x] Corriger la référence IDL Metaplex vers le nom canonique local. -- [x] Documenter quelles surfaces actives disposent réellement d’une IDL officielle et lesquelles reposent sur des crates d’interface. +- [ ] Souscrire à des logs mentionnant un Program ID actif. +- [ ] Fermer `demo_ws` sans unsubscribe ni disconnect. +- [ ] Confirmer dans les logs que la session et la subscription restent actives. +- [ ] Rouvrir `demo_ws` et confirmer la restauration du statut et de la subscription. +- [ ] Désinscrire explicitement la subscription. +- [ ] Souscrire de nouveau puis déconnecter explicitement la socket. +- [ ] Refaire un abonnement puis fermer l’application principale et confirmer la déconnexion globale. +- [ ] Archiver les logs et captures de preuve. +## 5. Configuration, secrets et logging -## 1.1 Règles +- [ ] Exécuter les tests `kb-config` et `kb-logging` dans le workspace réel. +- [ ] Confirmer la priorité `KB_ENV_FILE`, `.env`, variables d’environnement et fallbacks. +- [ ] Confirmer la résolution de `HELIUS_API_KEY` sans fuite dans les logs ou payloads frontend. +- [ ] Vérifier les routes console et fichiers des profils Devnet et Mainnet. +- [ ] Vérifier les targets consolidées `kb-lib.decoder.*`, `kb-lib.executor.*` et `kb-lib.materializer.*`. +- [ ] Confirmer l’absence de répertoires de logs dédiés aux anciennes crates supprimées. -- [x] Reprendre dans les règles Bot3 toutes les règles Bot2 encore applicables. -- [x] Remplacer les anciens fichiers de règles par `docs/rules/RULES_GENERAL.md`, `docs/rules/RULES_RUST.md`, `docs/rules/RULES_SPECIFIC_KHADHROONY.md` et un index `RULES.md`. -- [x] Adapter le workflow des deltas à Bot3. -- [ ] Effectuer une dernière lecture croisée des règles portant sur imports, réexports, façades, Tauri, TS-RS, logging, versionnement et archives. -- [ ] Supprimer de cette checklist toute demande de justification historique sans valeur normative. +## 6. PostgreSQL et pipeline -## 1.2 Anciennes crates, imports et chemins +- [ ] Exécuter les tests `kb-store` et `kb-pipeline`. +- [ ] Exécuter un healthcheck PostgreSQL sur le profil Devnet. +- [ ] Vérifier les migrations et les diagnostics des tables raw, Core et decode/materialization. +- [ ] Exécuter une campagne complète raw → Core → Decode replay → Materialize. +- [ ] Vérifier l’idempotence d’un second replay. +- [ ] Contrôler les index et contraintes avec les diagnostics existants. +- [ ] Documenter le dimensionnement actuel du pool et les trois timeouts transitoires historiques. +- [ ] Décider si le retry PostgreSQL borné est requis avant `0.4.6` ou reporté à la refonte `0.5.x`. -- [x] Confirmer l’absence d’import, réexport ou dépendance active vers les anciennes crates `kb_executor_*`. -- [x] Confirmer l’absence d’import, réexport ou dépendance active vers les anciennes crates `kb_decoder_*`. -- [x] Confirmer l’absence d’import, réexport ou dépendance active vers les anciennes crates `kb_materializer_*`. -- [x] Confirmer l’absence d’import, réexport ou dépendance active vers l’ancienne crate `kb_model`. -- [x] Confirmer l’absence de dépendance ou de crate `kb_store_pg`. -- [x] Confirmer l’absence de dépendance ou de crate `kb_store_core`. -- [x] Confirmer qu’aucune ancienne crate supprimée n’a été recréée sous un autre chemin. -- [x] Auditer `kb-app-demo-desktop/**/*.rs` pour les anciens chemins structurels actifs. -- [x] Vérifier les bindings TS-RS générés : aucun ancien chemin de crate actif n’est exporté. -- [x] Classer les anciennes chaînes runtime et les remplacer par les identités consolidées `kb-lib.decoder.*`, `kb-lib.executor.*` et `kb-lib.materializer.*`. -- [ ] Réécrire lors de la refonte documentaire finale les commentaires et documents qui racontent encore la consolidation depuis les anciennes crates. +## 7. Validation desktop des surfaces `0.4.6` -Contrôles exécutés : aucune correspondance structurelle `ancienne_crate::`, aucune dépendance Cargo correspondante et aucun répertoire de crate supprimée. +- [ ] Valider HTTP, WebSocket, Backfill, Core extraction, Decode replay et diagnostics SQL. +- [ ] Valider Exécution Solana Core sur Devnet. +- [ ] Valider Memo v4, ATA classique, ATA Token-2022, SPL Token classique et Token-2022 dans le desktop. +- [ ] Vérifier simulation, confirmation opérateur, envoi, progression, résumé et diagnostics. +- [ ] Vérifier backfill, Core extraction, replay et matérialisation post-exécution. +- [ ] Confirmer que toutes les options frontend correspondent à une capacité backend réelle. -## 1.3 Convention Token-2022 +## 8. Documentation opérateur minimale -Convention arrêtée : +- [x] Ajouter [`docs/guides/DEVNET_0_4_6_OPERATOR_GUIDE.md`](docs/guides/DEVNET_0_4_6_OPERATOR_GUIDE.md). +- [ ] Relire le guide pendant la campagne runtime et corriger les champs ou commandes inexacts. +- [ ] Ajouter les preuves finales au rapport d’alignement. -- symboles, modules, fichiers, fonctions et variables internes : `token_2022` / `TOKEN_2022` ; -- types et variantes Rust en PascalCase : `Token2022` ; -- valeurs JSON/TS explicitement concernées : `token_2022` avec attributs Serde et TS-RS ; -- codes persistés : `spl.token_2022` et opérations sous `spl.token_2022.*` ; -- noms officiels externes : conserver leur orthographe publiée ; -- exceptions contractuelles Metaplex conservées : `token2022EmbeddedMetadata` et `token2022_embedded_metadata`. +## 9. Report explicite vers `0.4.7` -- [x] Inventorier les occurrences actives `token2022`, `TOKEN2022`, `token_2022`, `TOKEN_2022`. -- [x] Classer les occurrences entre symboles internes, contrats externes, valeurs persistées, API, tests, IDL et documentation historique. -- [x] Renommer les symboles et modules internes vers `token_2022` / `TOKEN_2022`. -- [x] Conserver `Token2022` pour les types et variantes Rust. -- [x] Aligner Serde et TS-RS sur `token_2022` lorsque cette valeur appartient au contrat applicatif. -- [x] Renommer les identités persistées et runtime vers `spl.token_2022` et `kb-lib.*.token_2022`. -- [x] Purger les données dérivées puis reconstruire Core, Decode et Materialize depuis les 4 574 raws. -- [x] Valider 55 instructions Token-2022 décodées, 0 échec fonctionnel. -- [x] Vérifier les matrices actives ; corriger la dernière commande historique dans `SPL_TOKEN_2022_MATRIX.json`. -- [x] Découpler les assertions structurelles des matrices des compteurs globaux et volatils de `cargo test`. -- [ ] Réauditer progressivement chaque matrice active lors de la reprise de sa surface ; les preuves opérateur restent informatives et les invariants doivent être dérivés des lignes de matrice et des registres compilés. -- [ ] Refaire l’audit Python de nomenclature lors de la stabilisation finale des helpers de migration. +- [x] Conserver le décodeur Metaplex Token Metadata déjà migré. +- [x] Reporter la vérification de la matérialisation, l’exécuteur, le pipeline, les scénarios et le desktop vers `0.4.7`. +- [ ] Après publication de `0.4.6`, créer la première prerelease de planification de `0.4.7` selon `docs/rules/VERSION_DEVELOPMENT_LIFECYCLE.md`. -# 2. Frontend et application desktop - -## 2.1 Menu, contrôles et HTML - -- [x] Ordre principal du menu corrigé : Configuration, Transport et collecte, Pipeline, SQL, Exécution. -- [ ] Vérifier une dernière fois les séparateurs du menu. -- [ ] Supprimer les entrées de menu, boutons, onglets et liens sans backend accessible. -- [ ] Vérifier qu’une sortie ne possède qu’une seule paire de contrôles Copier/Effacer. -- [x] Vérifier toutes les balises HTML après les derniers remaniements ; les quatre conteneurs finaux manquants ont été refermés et le parseur HTML local ne signale plus de déséquilibre. -- [ ] Vérifier que chaque option HTML correspond à une commande Tauri et à un scénario backend réellement accessible. - -## 2.2 Viewers et journaux - -- [x] HTTP utilise un composant texte borné pour le résultat brut. -- [x] WebSocket utilise un composant texte/log borné et persistant pendant la session. -- [x] Extraction Core place paramètres, journaux et résultats dans une structure cohérente. -- [x] Réserver les viewers JSON au JSON structuré nécessitant exploration ou formatage ; HTTP endpoints/résultat et WebSocket statut/endpoints utilisent désormais `@andypf/json-viewer`. -- [x] Utiliser des textareas pour texte brut, logs et diagnostics concaténés ; les messages WebSocket restent textuels avec Copier/Effacer. -- [ ] Vérifier ce contrat dans Decode replay, Exécution Solana Core et Exécution SPL. -- [x] Convertir Statut et Endpoints WebSocket en viewers JSON structurés après contrôle runtime. - -## 2.3 Fenêtres SQL - -- [x] Replay Candidates accepte temporairement jusqu’à 100 000 résultats. -- [x] Les CSV sont écrits dans `/data/exports_csv`. -- [x] Export `replay_transactions.csv` validé. -- [ ] Mettre les autres fenêtres SQL sur une seule colonne pleine largeur lorsque ce n’est pas déjà le cas. -- [x] Rendre le journal des annotations responsive avec DataTables, pagination, recherche et scroll horizontal borné au wrapper. -- [ ] Limiter le scroll horizontal au wrapper de table. - -## 2.4 Rappels non bloquants - -- [x] Déplacer les autocomplétions futures, la pagination SQL/IPC et la résolution configurable du chemin `kb-store` vers `docs/IDEA_REMINDERS.md`. - -# 3. Configuration, environnement et secrets - -Préparation engagée avant la campagne Devnet `0.1.0-pre.062`; la validation runtime complète reste à effectuer pendant cette campagne. - -- [x] Conserver `HELIUS_API_KEY` comme variable Helius canonique déjà utilisée par la configuration. -- [x] Séparer les bases runtime avec `KB_POSTGRES_MAINNET_URL` et `KB_POSTGRES_DEVNET_URL`. -- [x] Conserver `KB_POSTGRES_TEST_URL` comme contrat existant des tests d’intégration PostgreSQL. -- [x] Faire de `.env.example` l’unique modèle dotenv versionné et ignorer tous les `.env*` réels. -- [x] Faire pointer `local_devnet` vers la variable Devnet et les deux profils Mainnet vers la variable Mainnet. - -- [ ] Confirmer que seul `kb-config` charge `.env`. -- [ ] Confirmer l’ordre de priorité des variables du processus, de `KB_ENV_FILE`, du `.env` racine et des valeurs de configuration. -- [ ] Confirmer le comportement de `${VAR}`. -- [ ] Confirmer le comportement de `${VAR:-fallback}`. -- [ ] Confirmer que l’absence de secrets pour les services optionnels reste non fatale. -- [ ] Vérifier que les diagnostics et logs ne révèlent aucun secret. -- [ ] Confirmer que `kb-pipeline-demo-scenarios` ne dépend pas directement de `dotenvy`. -- [ ] Valider réellement la résolution de `HELIUS_API_KEY` depuis `.env`. - -# 4. Logging - -- [x] Console runtime observée sur le profil `mainnet_research`. -- [ ] Confirmer la console active pour `local_devnet`. -- [ ] Confirmer la console active pour `mainnet`. -- [ ] Vérifier l’absence de routes Bot2 réellement obsolètes. -- [ ] Vérifier les targets `kb-lib.decoder.*`. -- [ ] Vérifier les targets `kb-lib.executor.*`. -- [ ] Vérifier les targets `kb-lib.materializer.*`. -- [ ] Vérifier qu’aucun ancien répertoire de logs correspondant à une crate supprimée n’est recréé. - -# 5. Tauri et séparation des responsabilités - -- [x] Les principales commandes Tauri ont été déplacées vers leurs modules fonctionnels. -- [ ] Auditer `tauri.rs` et vérifier qu’il ne conserve que l’enregistrement et des wrappers minces. -- [ ] Déplacer toute logique Decode replay, Backfill, SQL replay ou Exécution encore substantielle hors de `tauri.rs`. -- [ ] Vérifier les wrappers restants après ce dernier déplacement. -- [ ] Garantir que les tests unitaires résident dans les modules fonctionnels, pas dans les wrappers Tauri. -- [x] Fermeture explicite et Clippy propres sur l’état `pre.061`. -- [ ] Revalider timeout HTTP et arrêt global de l’application lors de la campagne finale runtime. - -# 6. PostgreSQL et reconstruction - -- [x] Tables raw et dérivées classées. -- [x] Script `reset_derived_store_keep_raw.sql` corrigé avec `TRUNCATE ... RESTART IDENTITY`. -- [x] `kb_sol_raw_transactions` conservée. -- [x] `kb_sol_obs_transaction_observations` classée comme acquisition à conserver lors des futurs resets. -- [x] La perte des anciennes observations de la base de démonstration actuelle est acceptée ; aucune restauration n’est requise. -- [x] Extraction Core complète des 4 574 raws validée. -- [x] Replay complet des décodeurs enregistrés validé. -- [x] Matérialisation sans erreur de ledger validée. -- [x] Compteurs et anomalies du replay analysés. -- [ ] Créer `kb-store/maintenance/README.md`. -- [ ] Documenter précisément les tables conservées, les tables dérivées et l’ordre de reconstruction. -- [ ] Documenter le contrôle des index et contraintes après recréation du schéma. -- [ ] Documenter la future transition vers une nouvelle base alimentée en temps réel par worker, complétée par backfills ciblés ou automatisés. - -# 7. Parité fonctionnelle avant Metaplex Executor - -L’objectif n’est pas de produire un rapport historique Bot2 permanent. Il faut confirmer que le périmètre requis est présent et utilisable dans Bot3. - -## 7.1 Décodage et matérialisation - -- [x] Solana Core : replay réel validé sur la base de démonstration. -- [x] SPL Memo : replay réel validé. -- [x] SPL Token classique : replay réel validé. -- [x] SPL ATA : replay réel validé. -- [x] SPL Token-2022 : replay réel validé. -- [ ] ElGamal Registry : obtenir une fixture ou campagne réelle de décodage d’instruction et d’état. -- [x] Extraction Core : campagne complète validée. -- [x] Replay : campagne complète validée. -- [x] Matérialisation : aucune erreur de matérialiseur observée. -- [x] PostgreSQL : reconstruction et persistance validées. -- [x] Identifier les 3 erreurs de campagne résiduelles comme timeouts transitoires du pool PostgreSQL, sans échec final de décodeur persisté. -- [x] Séparer dans le résumé `failedInputs` des erreurs d’orchestration ou de stockage via `processingErrorInputs`. -- [ ] Dimensionner le pool et ajouter un retry borné pour les timeouts transitoires avant la campagne finale. - -## 7.2 Transport et infrastructure - -- [x] Backfill HTTP validé en runtime. -- [x] HTTP JSON-RPC validé en runtime. -- [x] WebSocket validé en runtime. -- [x] Logging validé sur `mainnet_research`. -- [x] Configuration principale chargée et utilisée en runtime. -- [ ] Valider les profils `local_devnet` et `mainnet` lors de la campagne finale. - -### 7.2.1 Stabilisation frontend avant `0.1.0-pre.062` - -- [x] Corriger les quatre conteneurs HTML finaux signalés par RustRover. -- [x] Remplacer les favicons absentes par `imgs/logo.png`. -- [x] Valider visuellement les fenêtres Config, HTTP, WebSocket, Backfill, Core extraction, Decode replay et SQL. -- [x] Séparer les JSON viewers des sorties textuelles et conserver Copier/Effacer sur les sorties sans viewer selon leur volatilité. -- [x] Rendre le journal des annotations responsive et paginé avec DataTables. -- [x] Étendre DataTables aux tableaux de diagnostic SQL. -- [x] Corriger les avertissements frontend connus : API Rollup `names`, exception locale, initialiseur redondant et sélecteur de custom element. -- [ ] Revalider le frontend en runtime après application du dernier correctif. - -# 7.3 Exécution - -- [ ] Vérifier Exécution Solana Core via la fenêtre desktop et les scénarios Devnet. -- [ ] Vérifier Exécution SPL via la fenêtre desktop et les scénarios Devnet. -- [ ] Comparer les options de `demo_execution_spl.html` aux scénarios réellement supportés. -- [ ] Supprimer les options mortes. -- [ ] Raccorder ou documenter `execute_devnet_spl_token_lifecycle` s’il reste non exposé par l’application. -- [ ] Vérifier simulation, envoi, progression, résumé et diagnostics. -- [ ] Vérifier replay post-exécution et matérialisation pour chaque famille supportée. - -# 8. Guide Devnet des exécuteurs - -Créer une documentation dédiée, distincte des README généraux : - -- [x] Créer la première version de `docs/DEVNET_EXECUTION_GUIDE.md` avant les tests ; la compléter et la corriger pendant les campagnes Devnet. -- [ ] Documenter la création en ligne de commande d’un wallet de démonstration. -- [ ] Documenter la récupération de la pubkey. -- [x] Imposer l’utilisation d’un faucet Web pour financer le wallet Devnet ; ne pas dépendre de `solana airdrop`, non fonctionnel dans l’environnement de validation. -- [ ] Documenter les champs à saisir dans l’interface desktop. -- [ ] Documenter chaque scénario Solana Core étape par étape. -- [ ] Documenter chaque scénario SPL étape par étape. -- [ ] Documenter les préconditions, comptes, signers, frais estimés et résultats attendus. -- [ ] Documenter le replay et les projections à vérifier après chaque exécution. -- [ ] Ajouter ensuite les scénarios Metaplex Token Metadata. - -# 8.1 Convention et admission des IDL - -- [x] Documenter la convention `..[.].json` dans `idls/001.README.md`. -- [x] Renommer l’IDL active Metaplex Token Metadata avec le segment `metadata`. -- [x] Conserver le contenu JSON des IDL strictement inchangé. -- [x] Décider que la classification et le renommage des autres IDL seront effectués au moment où leur décodeur ou exécuteur devient actif. -- [ ] Maintenir progressivement un inventaire des sources, versions ou commits des IDL actives. - -# 8.1 Ordre metadata après validation des exécuteurs existants - -- [ ] Créer le pipeline metadata général et la fenêtre desktop spécialisée `demo_execution_metadata`. -- [ ] Traiter d’abord SPL Token Metadata incorporé à Token-2022. -- [ ] Traiter ensuite le programme Metaplex Token Metadata et son exécuteur. -- [ ] Décider ensuite de la création de `kb-offchain-transport` comme transport off-chain général : metadata HTTP(S)/IPFS/Arweave, prix et taux, APIs Jupiter et autres fournisseurs ; évaluer séparément les opérations off-chain mutables. - -# 9. Metaplex Token Metadata — décodeur - -- [x] IDL JSON local présent et renommé selon `...json`. -- [x] Six erreurs réelles isolées : 5 `create_metadata_account_v3`, 1 `transfer`. -- [x] Cause des faux échecs identifiée : comparaison stricte incorrecte des privilèges globaux avec les metas CPI. -- [x] Validation corrigée pour exiger les privilèges nécessaires sans refuser les privilèges supplémentaires. -- [x] Replay ciblé : 6 décodées, 0 échec. -- [x] Loader : transactions échouées, payloads tronqués et variantes inconnues distingués. -- [ ] Comparer systématiquement runtime, IDL local, builders et interface officielle pour les variantes couvertes. -- [ ] Vérifier les comptes optionnels et variantes legacy. -- [ ] Ajouter des fixtures issues des six transactions réelles sans dépendre de la base runtime. -- [ ] Étendre le replay Metaplex à un corpus plus large que les six signatures de correction. -- [ ] Vérifier les comptes Metaplex et leurs rôles sur instructions externes et CPI. -- [ ] Fermer explicitement la matrice du décodeur Metaplex avant de commencer son exécuteur. - -# 10. Metaplex Token Metadata — exécuteur et Devnet - -Étape fonctionnelle suivante. - -- [ ] Définir les opérations exécutables et celles restant decode-only. -- [ ] Compléter les intents typés. -- [ ] Compléter les builders. -- [ ] Comparer chaque builder aux builders officiels. -- [ ] Valider l’ordre exact des comptes. -- [ ] Valider signer et writable flags. -- [ ] Gérer les comptes optionnels et variantes supportées. -- [ ] Ajouter les politiques de sécurité. -- [ ] Imposer simulation-first. -- [ ] Interdire l’envoi mainnet par défaut. -- [ ] Ajouter limites de coût, estimation des frais et plafond de dépense. -- [ ] Ajouter validation post-exécution. -- [ ] Ajouter tests unitaires et matrice de couverture. -- [ ] Ajouter scénarios Devnet explicites dans `kb-pipeline-demo-scenarios`. -- [ ] Exposer les scénarios supportés dans l’application desktop. -- [ ] Afficher plan, signers, simulation, envoi et résultat. -- [ ] Effectuer le replay post-exécution. -- [ ] Vérifier décodage et matérialisation. -- [ ] Afficher des diagnostics bornés. - -# 11. Anchor - -À traiter après clôture complète de Metaplex Token Metadata et avant les protocoles applicatifs. - -- [ ] Définir la stratégie d’exploitation des IDL Anchor locaux. -- [ ] Définir les contrats génériques de discriminants, comptes et événements. -- [ ] Définir les limites entre décodage générique Anchor et décodeurs spécialisés par protocole. -- [ ] Ajouter tests et documentation avant intégration de Pump.fun, Raydium, Meteora, Jupiter ou autres protocoles Anchor. - -# 12. Documentation finale - -Cette section ne commence qu’après validation des exécuteurs actuels et clôture fonctionnelle Metaplex. - -## 12.1 README - -- [ ] Réécrire le README racine pour décrire uniquement Bot3 et son architecture actuelle. -- [ ] Réécrire le README de chaque crate pour expliquer son rôle, ses responsabilités et ses limites. -- [ ] Ajouter des liens vers les documents spécialisés pertinents. -- [ ] Retirer le récit de migration Bot2 → Bot3 des documents actifs. -- [ ] Retirer les listes d’évolution par version des README. -- [ ] Lorsqu’une fonctionnalité évolue, modifier le paragraphe fonctionnel correspondant au lieu d’ajouter une entrée chronologique. - -## 12.2 Usage des APIs et binaires - -- [ ] Créer un `USAGE.md` dans chaque crate publique ou binaire pertinent. -- [ ] Lister les APIs publiques réellement destinées aux consommateurs. -- [ ] Fournir des exemples Rust compilables ou quasi compilables. -- [ ] Documenter les types, traits, fonctions, builders, erreurs, invariants et limites. -- [ ] Documenter les commandes et options des binaires. -- [ ] Documenter les workflows d’intégration entre crates. -- [ ] Éviter de recopier mécaniquement toute l’API interne. - -## 12.3 Documentation issue de Bot2 - -- [ ] Inventorier les documents Bot2 encore fonctionnellement pertinents. -- [ ] Réécrire leur contenu pour l’architecture, les noms et les règles Bot3. -- [ ] Ne conserver aucune formulation laissant penser que Bot3 dépend conceptuellement de Bot2. -- [ ] Supprimer les documents de migration devenus inutiles, dont cette checklist. - -## 12.4 IDL - -L’ancien bloc `docs/IDL_SOURCES.md` n’est pas un prérequis autonome puisque les IDL sont déjà stockés localement. - -- [ ] Ajouter dans la documentation technique existante un inventaire léger des IDL réellement présents sous `idls/`. -- [ ] Pour chaque IDL utilisé, indiquer protocole, Program ID, source, version/commit connu, chemin local et usage. -- [ ] Ne pas inventer de source ou de version absente. - -# 13. Versionnement final - -- [ ] Clôturer toutes les tâches fonctionnelles de cette checklist. -- [ ] Terminer la documentation finale. -- [ ] Vérifier qu’aucun document actif ne présente Bot2 comme dépendance historique nécessaire. -- [ ] Aligner les versions du workspace Bot3 sur `0.4.7`. -- [ ] Mettre à jour `CHANGELOG.md` avec l’état fonctionnel final, sans dupliquer les README. -- [ ] Produire l’archive finale selon `docs/DELTA_WORKFLOW.md`. -- [ ] Supprimer `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md` après validation explicite de la clôture. - -# 14. Validation finale +## 10. Validation finale et changement de version - [ ] `cargo fmt --all`. - [ ] `cargo test --workspace`. @@ -398,39 +98,9 @@ L’ancien bloc `docs/IDL_SOURCES.md` n’est pas un prérequis autonome puisque - [ ] `cargo clippy --all-targets`. - [ ] `python3 scripts/audit_rust_workspace_rules.py`. - [ ] Vérifier les bindings TS-RS régénérés. -- [ ] Vérifier l’absence de secrets dans l’archive. -- [ ] Vérifier l’absence de `target`, `node_modules`, `dist`, logs, bases, `.env`, `Cargo.lock`, `package-lock.json` et bindings générés exclus par les règles de livraison. -- [ ] Valider toutes les fenêtres desktop. -- [ ] Valider HTTP, WebSocket, Backfill, Core extraction, Decode replay et SQL. -- [ ] Valider Exécution Solana Core et Exécution SPL sur Devnet. -- [ ] Valider Metaplex Executor et replay post-exécution sur Devnet. -- [ ] Valider configuration, logging et PostgreSQL sur les profils requis. -- [ ] Vérifier que les protocoles applicatifs différés sont documentés hors de cette checklist. - -# 15. Critères de clôture - -- [ ] Aucun import ou chemin d’ancienne crate ne subsiste. -- [ ] Convention Token-2022 définitivement appliquée et, si nécessaire, données dérivées migrées ou rejouées. -- [ ] Tauri ne contient plus de logique métier substantielle. -- [ ] UI sans contrôle mort ou dupliqué. -- [ ] Configuration et secrets validés. -- [ ] Logging propre sur tous les profils requis. -- [ ] Reconstruction PostgreSQL documentée et reproductible. -- [ ] Solana Core, SPL, Metaplex Token Metadata et Anchor au niveau requis avant protocoles applicatifs. -- [ ] Exécuteurs supportés validés sur Devnet. -- [ ] Documentation active entièrement réécrite pour Bot3. -- [ ] `USAGE.md` disponibles pour les surfaces publiques et binaires. -- [ ] Workspace aligné sur `0.4.7`. -- [ ] Cette checklist est supprimée. - -### 0.1.0-pre.062 — séparation du socle Devnet commun - -- [x] Garder `kb-app-demo-desktop/src/tauri.rs` comme couche mince de wrappers `#[tauri::command]`. -- [x] Déplacer `DemoExecutionDevnetStoreReadinessPayload`, `bounded_u32` et `prepare_devnet_profile_store` dans `kb-app-demo-desktop/src/demo_devnet_common.rs`. -- [x] Revalider `cargo fmt --all`, `cargo test -p kb-app-demo-desktop -p kb-pipeline-demo-scenarios`, `cargo check --workspace` et `cargo clippy --all-targets` : 117 tests desktop et 37 tests scénarios réussis. -- [x] Renommer l’en-tête du menu desktop `Exécution` en `Exécution Devnet`. -- [x] Déplacer l’idée de profils de logging indépendants vers `docs/IDEA_REMINDERS.md` sans ouvrir de développement dans `pre.062`. -- [x] Corriger l’audit d’ordre des exports pour le cas lexical Token-2022 sans imposer un réordonnancement contraire à rustfmt. -- [x] Aligner les tests `kb-store` sur `materializer.transaction.annotations`. -- [x] Réorganiser `docs/DEVNET_EXECUTION_GUIDE.md` autour de commandes communes référencées et de scénarios Devnet séparés. - +- [ ] Vérifier l’absence de secrets et artefacts exclus dans l’archive. +- [ ] Mettre à jour `docs/audits/V0_4_6_ALIGNMENT_AUDIT.md` vers `READY_WITH_DOCUMENTED_EXCEPTIONS` ou `READY_FOR_0_4_6`. +- [ ] Mettre les versions Cargo à `0.4.6`. +- [ ] Ajouter la section fonctionnelle `0.4.6` au changelog général. +- [ ] Mettre à jour les changelogs des crates affectées. +- [ ] Archiver puis supprimer cette checklist après validation explicite. diff --git a/docs/README.md b/docs/README.md index 1220098..5134d06 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,5 @@ - + # Documentation active de Khadhroony Bot3 @@ -39,6 +39,7 @@ Modèles documentaires non génératifs : ## 4. Audits et décisions actifs - [`audits/V0_4_6_ALIGNMENT_AUDIT.md`](audits/V0_4_6_ALIGNMENT_AUDIT.md) ; +- [`audits/PRE_0_4_6_STATIC_CODE_AUDIT.md`](audits/PRE_0_4_6_STATIC_CODE_AUDIT.md) ; - [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ; - [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md). diff --git a/docs/audits/PRE_0_4_6_STATIC_CODE_AUDIT.md b/docs/audits/PRE_0_4_6_STATIC_CODE_AUDIT.md new file mode 100644 index 0000000..fc4e101 --- /dev/null +++ b/docs/audits/PRE_0_4_6_STATIC_CODE_AUDIT.md @@ -0,0 +1,57 @@ + + + +# Audit statique préalable à `0.4.6` + +## Résumé + +L’audit statique a été exécuté sur l’archive complète `v0.1.0-pre.074-fix001`. + +## Résultats propres + +- seul `kb-config` dépend directement de `dotenvy` ; +- 50 commandes littérales appelées par le frontend ont été détectées ; +- les 50 sont présentes dans `tauri::generate_handler!` ; +- les huit commandes enregistrées non appelées directement depuis TypeScript correspondent aux ouvertures de fenêtres déclenchées depuis le menu Rust ; +- `AppState` possède la session WebSocket persistante ; +- la destruction de `demo_ws` ne contient pas de déconnexion statique ; +- la destruction de la fenêtre principale appelle la déconnexion globale ; +- aucune ancienne crate consolidée n’est redevenue une dépendance Cargo active ; +- les onze crates possèdent les quatre documents obligatoires. + +## Écart démontré : `tauri.rs` reste trop substantiel + +`kb-app-demo-desktop/src/tauri.rs` contient encore environ 1 900 lignes et appelle directement : + +- `kb_pipeline::execute_decode_replay` ; +- `kb_pipeline::execute_http_backfill` ; +- `kb_store::PostgresStore::connect` et des repositories ; +- les scénarios Devnet Solana Core, Memo, SPL Token, ATA et Token-2022 ; +- la construction de listes de matérialisateurs et de filtres de diagnostics. + +Le fichier n’est donc pas encore uniquement une couche mince de wrappers `#[tauri::command]`. + +### Décision + +Avant `0.4.6`, déplacer l’orchestration vers les modules fonctionnels déjà présents : + +- `demo_backfill.rs` ; +- `demo_core_extraction.rs` ; +- `demo_decode_replay.rs` ; +- `demo_execution_solana_core.rs` ; +- `demo_execution_spl.rs` et ses sous-modules ; +- modules SQL concernés. + +`tauri.rs` doit conserver l’assemblage Tauri, les wrappers de commandes, l’ouverture des fenêtres et les adaptations minimales d’erreur ou d’état. + +## Vérifications runtime encore nécessaires + +L’audit statique ne prouve pas : + +- la persistance réelle de la socket après fermeture de la fenêtre ; +- la restauration visuelle du statut à la réouverture ; +- les timeouts réseau ; +- le comportement des profils et routes de logging ; +- la campagne PostgreSQL et Devnet complète. + +Ces points doivent être validés avec les scénarios dédiés et leurs logs. diff --git a/docs/guides/DEVNET_0_4_6_OPERATOR_GUIDE.md b/docs/guides/DEVNET_0_4_6_OPERATOR_GUIDE.md new file mode 100644 index 0000000..020c4ec --- /dev/null +++ b/docs/guides/DEVNET_0_4_6_OPERATOR_GUIDE.md @@ -0,0 +1,99 @@ + + + +# Guide opérateur Devnet pour l’alignement `0.4.6` + +## 1. Objectif + +Ce guide regroupe les opérations minimales à valider avant le passage officiel de bot3 à `0.4.6`. + +## 2. Préparer le profil + +- sélectionner un profil Devnet valide ; +- vérifier le RPC HTTP, le WebSocket et PostgreSQL ; +- vérifier que `auto_initialize_schema` correspond à l’intention de la campagne ; +- utiliser un wallet de démonstration persistant et financé par faucet Web. + +La clé privée ne doit jamais être copiée dans les logs ou l’interface. + +## 3. Vérifier PostgreSQL + +Depuis les fenêtres SQL : + +1. charger le diagnostic général ; +2. vérifier les tables raw ; +3. vérifier les tables Core ; +4. vérifier les tables decode/materialization ; +5. noter la version de migration et les anomalies d’index ou contraintes. + +## 4. Campagne raw → Core → Decode → Materialize + +1. Exécuter un backfill borné sur un Program ID ou une adresse connue. +2. Vérifier l’insertion raw et les observations. +3. Exécuter Core extraction sur les nouvelles lignes. +4. Exécuter Decode replay avec les décodeurs adaptés. +5. Activer la matérialisation. +6. Vérifier les diagnostics et projections. +7. Rejouer la même sélection. +8. Confirmer l’idempotence et l’absence de duplications. + +## 5. Exécution Solana Core + +Pour System Transfer : + +- vérifier le wallet et la balance ; +- générer ou saisir un destinataire ; +- utiliser un montant minimal ; +- exécuter d’abord la simulation ; +- confirmer explicitement l’envoi ; +- vérifier la signature finalisée ; +- effectuer backfill, Core extraction et replay ; +- vérifier les observations et projections attendues. + +## 6. Exécution SPL + +Valider séparément : + +- Memo v4 ; +- ATA classique ; +- ATA Token-2022 ; +- SPL Token classique `TransferChecked` ; +- opérations Token-2022 documentées comme supportées. + +Pour chaque scénario : + +1. vérifier les préconditions et comptes ; +2. vérifier les signers ; +3. simuler ; +4. confirmer l’envoi ; +5. vérifier la confirmation réseau ; +6. effectuer le backfill ; +7. effectuer Core extraction ; +8. effectuer Decode replay et matérialisation ; +9. rejouer pour l’idempotence ; +10. vérifier l’état final via CLI ou RPC lorsque pertinent. + +## 7. WebSocket + +Exécuter intégralement [`WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md`](../validation/WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md). + +## 8. Résultats à consigner + +Pour chaque campagne, conserver : + +- profil et cluster ; +- opération ; +- comptes publics concernés ; +- signature ; +- résultat simulation ; +- résultat envoi et confirmation ; +- nombres raw/Core/decode/materialize ; +- diagnostics ; +- résultat du second replay ; +- commande CLI ou RPC de vérification finale. + +## 9. Hors périmètre + +Metaplex Token Metadata complet n’est pas un critère de `0.4.6`. Il sera planifié et terminé dans `0.4.7`. + +Le registre ElGamal reste conditionnel tant que son déploiement réseau et les preuves nécessaires ne sont pas confirmés. diff --git a/docs/validation/WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md b/docs/validation/WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md new file mode 100644 index 0000000..8828264 --- /dev/null +++ b/docs/validation/WEBSOCKET_LIFECYCLE_VALIDATION_SCENARIO.md @@ -0,0 +1,116 @@ + + + +# Validation du cycle de vie WebSocket desktop + +## Objectif + +Prouver qu’une session WebSocket appartient à l’application et non à la fenêtre `demo_ws`. + +## Préparation + +1. Configurer un endpoint WebSocket Devnet dans le profil utilisé. +2. Activer une route de logs contenant au minimum `kb-app-demo-desktop` et `kb-onchain-transport` au niveau `debug`. +3. Lancer : + +```bash +cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json 2>&1 | tee /tmp/kbot3-pre075-ws.log +``` + +4. Ouvrir la fenêtre **WebSocket standard**. +5. Rafraîchir les endpoints et vérifier qu’un rôle compatible est disponible. + +## Souscription principale recommandée + +Utiliser `logsSubscribe`, car elle permet de filtrer les transactions mentionnant un Program ID. + +| Champ | Valeur | +|-------------|----------------------------------------------------------------| +| Rôle | rôle WebSocket standard Devnet disponible | +| Méthode | `logsSubscribe` | +| Target | vide | +| Filter JSON | `{"mentions":["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]}` | +| Config JSON | `{"commitment":"confirmed"}` | + +Le Program ID choisi est SPL Token classique. Il peut être remplacé par Token-2022 : + +```text +TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb +``` + +## Scénario A — fermeture et réouverture de la fenêtre + +1. Cliquer **Souscrire**. +2. Noter l’identifiant de subscription et vérifier : + - statut connecté ; + - `subscriptionCount = 1` ; + - méthode `logsSubscribe`. +3. Attendre au moins une notification ou, à défaut, conserver la réponse de subscription. +4. Fermer uniquement la fenêtre `demo_ws` avec le bouton de la fenêtre. +5. Ne pas cliquer sur **Unsubscribe** ni **Déconnecter socket**. +6. Attendre 15 à 30 secondes. +7. Rouvrir **WebSocket standard** depuis le menu principal. +8. Vérifier immédiatement : + - statut connecté ; + - même endpoint ; + - subscription toujours présente ; + - même identifiant distant ou identifiant remappé explicitement après reconnexion ; + - nouveaux messages reçus si le réseau en produit. + +### Critère de réussite + +La fenêtre restaurée affiche l’état réel de la session persistante. Aucun événement `Disconnected` ne doit être provoqué par la fermeture de `demo_ws`. + +## Scénario B — unsubscribe explicite + +1. Sélectionner la subscription active. +2. Cliquer **Unsubscribe sélectionnée**. +3. Vérifier : + - `subscriptionCount = 0` ; + - socket encore connectée ; + - message de désinscription ; + - absence de nouvelles notifications pour cette subscription. + +## Scénario C — nouvelle subscription puis déconnexion explicite + +1. Souscrire de nouveau avec le même filtre. +2. Vérifier `subscriptionCount = 1`. +3. Cliquer **Déconnecter socket**. +4. Vérifier : + - statut déconnecté ; + - aucune subscription active ; + - événement ou diagnostic de déconnexion dans les logs. + +## Scénario D — arrêt global de l’application + +1. Souscrire de nouveau. +2. Fermer la fenêtre `demo_ws`. +3. Fermer ensuite la fenêtre principale de l’application. +4. Vérifier dans `/tmp/kbot3-pre075-ws.log` que la déconnexion globale est exécutée. +5. Vérifier que le processus Tauri se termine sans rester en arrière-plan. + +## Scénario optionnel — `programSubscribe` + +Pour observer les changements de comptes appartenant à Token-2022 : + +| Champ | Valeur | +|-------------|--------------------------------------------------| +| Méthode | `programSubscribe` | +| Target | `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` | +| Filter JSON | vide | +| Config JSON | `{"commitment":"confirmed","encoding":"base64"}` | + +Cette souscription peut être très active. Les limites de débit et de taille de l’interface doivent rester fonctionnelles. + +## Preuves à archiver + +Fournir une archive contenant : + +- `/tmp/kbot3-pre075-ws.log` ; +- copie du statut avant fermeture ; +- copie du statut après réouverture ; +- identifiants de subscription ; +- résultat unsubscribe ; +- résultat disconnect ; +- heure approximative de chaque étape ; +- anomalie éventuelle et reproduction minimale. diff --git a/kb-app-demo-desktop/CHANGELOG.md b/kb-app-demo-desktop/CHANGELOG.md index 60f1b42..c5eb0c4 100644 --- a/kb-app-demo-desktop/CHANGELOG.md +++ b/kb-app-demo-desktop/CHANGELOG.md @@ -1,8 +1,13 @@ - + # CHANGELOG — kb-app-demo-desktop +## 0.1.0-pre.075 + +- ajout de l’audit statique Tauri/frontend et du scénario de validation du cycle de vie WebSocket ; +- identification de l’orchestration encore substantielle dans `tauri.rs` comme blocant avant `0.4.6` ; + ## 0.1.0-pre.072 - reclassement du TODO selon les blocants avant `0.4.6`, les travaux `0.4.7`, les versions ultérieures et les dépendances conditionnelles. diff --git a/kb-app-demo-desktop/TODO.md b/kb-app-demo-desktop/TODO.md index 7ccba74..3be26c4 100644 --- a/kb-app-demo-desktop/TODO.md +++ b/kb-app-demo-desktop/TODO.md @@ -1,10 +1,13 @@ - + # TODO — kb-app-demo-desktop ## Bloquants avant alignement `0.4.6` +- [ ] Architecture - déplacer hors de `tauri.rs` l’orchestration pipeline, stockage et exécution encore substantielle. +- [ ] Architecture - conserver dans `tauri.rs` uniquement les wrappers Tauri, l’assemblage runtime et les adaptations minimales. + - [ ] Validation - vérifier intégralement la synchronisation des adaptateurs Tauri et des payloads TS-RS avec les APIs réutilisables. - [ ] Validation - couvrir explicitement les cycles d’ouverture, fermeture et réouverture des fenêtres concernées. - [ ] WebSocket - valider que la fermeture de `demo_ws` ne ferme pas une session WebSocket active. diff --git a/kb-config/CHANGELOG.md b/kb-config/CHANGELOG.md index ee03174..e10d887 100644 --- a/kb-config/CHANGELOG.md +++ b/kb-config/CHANGELOG.md @@ -1,8 +1,12 @@ - + # CHANGELOG — kb-config +## 0.1.0-pre.075 + +- validation statique que `kb-config` reste l’unique propriétaire direct de `dotenvy` ; + ## 0.1.0-pre.073 - ajout du guide transversal [`docs/guides/CONFIGURATION.md`](../docs/guides/CONFIGURATION.md) ; diff --git a/kb-pipeline-demo-scenarios/CHANGELOG.md b/kb-pipeline-demo-scenarios/CHANGELOG.md index 8d7f4c1..c91399d 100644 --- a/kb-pipeline-demo-scenarios/CHANGELOG.md +++ b/kb-pipeline-demo-scenarios/CHANGELOG.md @@ -1,8 +1,12 @@ - + # CHANGELOG — kb-pipeline-demo-scenarios +## 0.1.0-pre.075 + +- ajout du guide opérateur Devnet `0.4.6` distinguant les scénarios de validation des composants réutilisables ; + ## 0.1.0-pre.073 - ajout du guide transversal [`docs/guides/DEVNET_VALIDATION.md`](../docs/guides/DEVNET_VALIDATION.md) ; diff --git a/scripts/audit_pre_0_4_6_static_contracts.py b/scripts/audit_pre_0_4_6_static_contracts.py new file mode 100644 index 0000000..45a963c --- /dev/null +++ b/scripts/audit_pre_0_4_6_static_contracts.py @@ -0,0 +1,113 @@ +#!/usr/bin/env python3 +# file: scripts/audit_pre_0_4_6_static_contracts.py +# version: 1 + +"""Audit static contracts that must remain true before the 0.4.6 alignment.""" + +from __future__ import annotations + +import argparse +import pathlib +import re +import sys +import tomllib + +def fail(code: str, message: str) -> None: + """Print one violation.""" + + print(f"{code}: {message}") + +def frontend_invokes(root: pathlib.Path) -> set[str]: + """Return literal Tauri commands invoked by the frontend.""" + + commands: set[str] = set() + pattern = re.compile(r"invoke(?:<[^>]+>)?\(\s*[\"']([A-Za-z0-9_]+)[\"']") + for suffix in ("*.ts", "*.html"): + for path in (root / "kb-app-demo-desktop" / "frontend").rglob(suffix): + commands.update(pattern.findall(path.read_text(encoding="utf-8"))) + return commands + +def registered_commands(root: pathlib.Path) -> set[str]: + """Return commands registered in generate_handler.""" + + path = root / "kb-app-demo-desktop" / "src" / "tauri.rs" + text = path.read_text(encoding="utf-8") + match = re.search(r"generate_handler!\[(.*?)\]\);", text, re.DOTALL) + if match is None: + return set() + return set(re.findall(r"^[ \t]*([A-Za-z_][A-Za-z0-9_]*)[ \t]*,", match.group(1), re.MULTILINE)) + +def main() -> int: + """Run the pre-0.4.6 static audit.""" + + parser = argparse.ArgumentParser() + parser.add_argument("--root", default=".") + parser.add_argument("--report-only", action="store_true") + arguments = parser.parse_args() + root = pathlib.Path(arguments.root).resolve() + violations = 0 + + dotenv_crates: list[str] = [] + for cargo in sorted(root.glob("*/Cargo.toml")): + data = tomllib.loads(cargo.read_text(encoding="utf-8")) + dependencies = data.get("dependencies", {}) + if "dotenvy" in dependencies: + dotenv_crates.append(cargo.parent.name) + if dotenv_crates != ["kb-config"]: + fail("ALIGN001", f"dotenvy must be owned only by kb-config, found {dotenv_crates}") + violations += 1 + + missing = sorted(frontend_invokes(root) - registered_commands(root)) + if missing: + fail("ALIGN002", f"frontend commands missing from Tauri registration: {missing}") + violations += 1 + + tauri_text = (root / "kb-app-demo-desktop" / "src" / "tauri.rs").read_text(encoding="utf-8") + if 'window.label() != "main"' not in tauri_text or "disconnect_demo_ws_app_state" not in tauri_text: + fail("ALIGN003", "global WebSocket shutdown must be tied to main-window destruction") + violations += 1 + if re.search(r'window\.label\(\)\s*==\s*"demo_ws".*disconnect_demo_ws', tauri_text, re.DOTALL): + fail("ALIGN004", "demo_ws window destruction must not disconnect the application session") + violations += 1 + + app_state = (root / "kb-app-demo-desktop" / "src" / "app_state.rs").read_text(encoding="utf-8") + if "demo_ws_session" not in app_state: + fail("ALIGN005", "AppState must own the persistent demo WebSocket session") + violations += 1 + + forbidden_crates = ( + "kb_decoder_", + "kb_executor_", + "kb_materializer_", + "kb_store_core", + "kb_store_pg", + ) + for path in sorted(root.rglob("*.rs")): + if any(part in {"olddocs", "target"} for part in path.parts): + continue + text = path.read_text(encoding="utf-8") + for name in forbidden_crates: + if name in text: + fail("ALIGN006", f"legacy crate identity {name!r} found in {path.relative_to(root)}") + violations += 1 + + required_docs = ("README.md", "TODO.md", "USAGE.md", "CHANGELOG.md") + for cargo in sorted(root.glob("*/Cargo.toml")): + for document in required_docs: + if not (cargo.parent / document).is_file(): + fail("ALIGN007", f"missing {document} in {cargo.parent.name}") + violations += 1 + + matrix = root / "test-fixtures" / "contract-matrices" / "OPERATION_NAMING_MATRIX.json" + if not matrix.is_file(): + fail("ALIGN008", "operation naming matrix is missing") + violations += 1 + + if violations == 0: + print("Pre-0.4.6 static contract audit: clean") + return 0 + print(f"Pre-0.4.6 static contract audit: {violations} violation(s)") + return 0 if arguments.report_only else 1 + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/audit_rust_workspace_rules.py b/scripts/audit_rust_workspace_rules.py old mode 100755 new mode 100644 index 007a3e0..ec55fdd --- a/scripts/audit_rust_workspace_rules.py +++ b/scripts/audit_rust_workspace_rules.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # file: scripts/audit_rust_workspace_rules.py -# version: 3 +# version: 4 """Run the general, export-completeness and khadhroony workspace audits.""" @@ -10,7 +10,6 @@ import argparse import pathlib import subprocess - def main() -> int: """Run all independent audit scripts.""" @@ -23,12 +22,12 @@ def main() -> int: ["python3", str(script_dir / "audit_rust_general_rules.py"), "--root", arguments.root], ["python3", str(script_dir / "audit_rust_export_completeness.py"), "--root", arguments.root], ["python3", str(script_dir / "audit_khadhroony_workspace_rules.py"), "--root", arguments.root], + ["python3", str(script_dir / "audit_pre_0_4_6_static_contracts.py"), "--root", arguments.root], ] if arguments.report_only: for command in commands: command.append("--report-only") return max(subprocess.run(command, check=False).returncode for command in commands) - if __name__ == "__main__": raise SystemExit(main())