v0.1.0-pre.064-065

olddocs/archivekbot2/kb_materializer_transaction_annotations/README.md

@@ -0,0 +1,47 @@
+<!-- file: kb_materializer_transaction_annotations/README.md -->
+<!-- version: 4 -->
+
+# kb_materializer_transaction_annotations
+
+Ce crate fournit une projection réutilisable d’annotations de transaction. La première surface active est SPL Memo v1, v3 et v4 ; le domaine n’est volontairement pas fusionné avec metadata, admin, lifecycle ou compliance audit.
+
+## Projection Memo
+
+Le matérialiseur accepte uniquement les observations `spl_memo` dont le Program ID, la surface et l’entrée correspondent exactement. `add_memo`, `memo_intent` et `invalid_memo_attempt` sont reconnus afin que la politique commune puisse enregistrer un refus explicite, mais seule une observation `add_memo` réussie et commitée produit une sortie.
+
+La sortie `TransactionAnnotation` conserve :
+
+- signature, slot et chemin d’instruction outer/inner ;
+- génération et Program ID exacts ;
+- texte UTF‑8 complet dans la borne de 4 096 octets ;
+- longueur et SHA-256 du payload ;
+- signataires exigés, observés et réellement vérifiés par la génération ;
+- état committed, version de projection et provenance du matérialiseur ;
+- clé d’idempotence déterministe fondée sur signature, chemin, Program ID et hash.
+
+Pour v1, les comptes signers restent observables mais la liste `verified` est vide, car le runtime historique ne les vérifie pas. Pour v3/v4, une projection commitée exige l’égalité ordonnée entre signataires requis et observés, doublons compris.
+
+## Persistance et replay
+
+La sortie utilise le store commun `kb_sol_mat_events` avec la famille `transaction_annotation`. Aucune migration SQL supplémentaire n’est nécessaire et les événements decode/core ne sont pas dupliqués. Le ledger commun assure :
+
+- replay identique et même version : skip ;
+- force replay : remplacement atomique des sorties appartenant à la version ciblée ;
+- changement de version : identité de processor distincte et déterministe.
+
+Les transactions échouées, observations non commitées, UTF‑8 invalides et validations de signataires invalides restent uniquement dans `kb_sol_decode_events`. Les comptes complets, flags writable, préfixes diagnostics, erreurs UTF‑8 et preuves détaillées restent également dans l’événement décodé ; la projection ne conserve que les champs utiles à la consultation d’annotations.
+
+## Consultation
+
+La fenêtre `demo_decode_replay` affiche les sorties comme un journal d’annotations, et non comme une série OHLC : slot, signature, instruction path, génération, texte, longueur, signataires vérifiés, hash et provenance. La lecture passe par le contrat borné `DecodePipelineStore::list_materialized_events`, filtré exactement sur le processor `transaction_annotations` et la famille `transaction_annotation` ; aucun SQL libre ni payload JSON arbitraire ne traverse l’UI.
+
+La démo d’exécution Memo v4 réutilise ce même contrat de lecture pour vérifier la projection après confirmation. Trois transactions Devnet réelles ont chacune produit exactement une annotation ; le second replay a été `skipped` sans sortie supplémentaire ni refus. Cette projection reste un journal consultable et corrélable, pas une agrégation temporelle de type OHLC.
+
+Le parcours Mainnet du 14 juillet 2026 a acquis puis extrait 300 transactions réelles, 100 par Program ID. Le replay a décodé 102 instructions v1, 439 v3 et 100 v4 sans unmatched ni échec de décodage. La projection a produit respectivement 69, 422 et 100 annotations ; les 33 refus v1 et 17 refus v3 correspondaient aux intentions issues de transactions échouées. Un second replay v3 non forcé a sélectionné zéro entrée, validant le skip idempotent du ledger. Les campagnes forcées v3/v4 ont également reproduit les mêmes nombres de sorties.
+
+## Règles locales
+
+- `SuccessfulCommittedOnly` est appliqué avant toute sortie.
+- Un payload décodé incohérent échoue fermé avec un diagnostic stable.
+- Le target tracing canonique est `kb_materializer_transaction_annotations`.
+- Aucun log ne contient de clé privée ni de texte Memo complet.