diff --git a/deltas/0.3.5/pre.001-fix.001.md b/deltas/0.3.5/pre.001-fix.001.md new file mode 100644 index 0000000..3b570f9 --- /dev/null +++ b/deltas/0.3.5/pre.001-fix.001.md @@ -0,0 +1,191 @@ + + + +# Delta `0.3.5-pre.001-fix.001` — correction du gate Interface acquisition events + +## Base requise + +```text +0.3.5-pre.001 +workspace.package.version = 0.3.5-pre.1 +``` + +Ce fix est strictement documentaire. Conformément au workflow KSP, il ne modifie pas `workspace.package.version` et ne touche aucun fichier Cargo/Rust/runtime/config. + +## Motif du fix + +Le brainstorming post-gate a identifié deux décisions trop conservatrices dans `pre.001` : + +1. `OptimisticConfirmation <-> Yellowstone Confirmed` et `Root <-> Yellowstone Finalized` représentent bien les mêmes faits de lifecycle lorsqu'ils sont normalisés avec des noms KSP qui conservent la sémantique source ; +2. la catégorie générique « transaction status » mélangeait snapshot, commitment et exécution, masquant un candidat event-only transversal possible. + +## Corrections de conception + +### Slot lifecycle + +L'intersection admise devient : + +```text +SlotLifecycleStage + + Processed + + FirstShredReceived + + Completed + + CreatedBank + + Dead + + OptimisticallyConfirmed + + Rooted +``` + +Mappings corrigés : + +```text +Solana slotsUpdates::OptimisticConfirmation + -> SlotLifecycleStage::OptimisticallyConfirmed + <- Yellowstone SlotStatus::Confirmed + +Solana rootSubscribe / slotsUpdates::Root + -> SlotLifecycleStage::Rooted + <- Yellowstone SlotStatus::Finalized +``` + +Les noms `OptimisticallyConfirmed` et `Rooted` évitent de promouvoir les labels Yellowstone `Confirmed`/`Finalized` en terminologie KSP universelle. `Frozen` reste hors intersection. + +### Transaction execution + +`TransactionExecutionEvent` est rouvert comme **candidat actif de `0.3.5`**, conceptuellement : + +```text +TransactionExecutionEvent { + slot, + signature, + outcome = Succeeded | Failed, +} +``` + +Producers candidats : + +```text +Solana logsSubscribe +Yellowstone TransactionStatus +Helius transactionSubscribe +``` + +Le type n'est pas encore admis. `pre.003` doit d'abord auditer la représentation KSP de signature, les mappings exacts, l'anti-duplication Store et le consumer concret. Aucun type partiel ne doit être créé si ce gate échoue. + +### Logs et commitment + +Les familles sont désormais explicitement séparées : + +```text +TransactionLogEvent + -> idée différée ; bornes/consumer/multi-producer à démontrer + +getSignatureStatuses + -> snapshot Transport + +signatureSubscribe + -> transition one-shot de commitment Transport + +TransactionCommitmentEvent + -> non admis ; ne jamais fusionner avec TransactionExecutionEvent par Option soup +``` + +### Extensions provider/protocol + +La règle d'ownership est clarifiée : + +```text +DTO provider/protocol spécifique + -> Transport + +fait passif provider-neutral réellement commun + -> Interface après gate sémantique +``` + +Ainsi `Helius transactionSubscribe` et Yellowstone `Entry` restent Transport-owned comme DTOs. Leur caractère non standard n'interdit pas qu'un futur fait commun qu'ils permettent d'observer soit Interface-owned. + +## Traçabilité TODO/IDEAS + +Le fix ne crée pas artificiellement une entrée durable séparée pendant que le gate `0.3.5` est encore actif : + +```text +TransactionExecutionEvent -> suivi actif dans plan/validation 0.3.5 +TransactionLogEvent -> idée différée explicitement tracée dans plan/validation +``` + +Si `TransactionLogEvent` reste hors scope à la réconciliation documentaire finale, il devra être transféré dans le TODO/IDEAS durable approprié. + +## Plan de prereleases corrigé + +```text +pre.002 implémentation SlotLifecycleEvent/Stage à 7 stages +pre.003 gate TransactionExecutionEvent + implémentation seulement si gate complet +pre.004 canaris externes + complétude API +pre.005 hardening final +pre.006 gate technique final +pre.007 réconciliation documentaire finale +pre.008 préparation de publication +rel.001 stable 0.3.5 +``` + +## Gate opérateur reçu pour `pre.001` + +Avant ce fix, l'opérateur a rejoué : + +```text +cargo clean +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/0.3.5 +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-interface-lib +``` + +Résultat fourni : + +```text +General Rust rule audit: clean +Rust export completeness audit: 0 candidate(s) +KSP workspace Rust rule audit: clean +Markdown table audit: clean (251 table(s), 137 file(s)) +cargo check --workspace: PASS +cargo clippy --workspace --all-targets: PASS +cargo test -p ksp-interface-lib: PASS +``` + +Les tests Interface détaillés fournis sont tous propres : 10 unitaires, 4 dependency-boundary, 1 external-consumer, 5 public-api, 3 release-completeness, aucun échec de doc-test. + +## Fichiers modifiés + +```text +docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md +docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md +``` + +## Fichiers ajoutés + +```text +deltas/0.3.5/pre.001-fix.001.md +``` + +## Fichiers explicitement inchangés + +```text +Cargo.toml +crates/** +README.md +ROADMAP.md +CHANGELOG.md +``` + +## Gate demandé après application du fix + +Le fix ne change que Markdown. Rejouer : + +```text +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/0.3.5 +``` + +Aucun rerun Cargo n'est requis par le contenu du fix lui-même. diff --git a/docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md b/docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md index 2a55833..2ddb958 100644 --- a/docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md +++ b/docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md @@ -1,5 +1,5 @@ - + # Plan `0.3.5` — Interface passive acquisition events @@ -21,7 +21,7 @@ label = 0.3.5-pre.001 `0.3.5-pre.001` est un gate de lecture, inventaire, convergence sémantique, threat model, sizing et planification. Il ne modifie aucun contrat public Rust, aucun DTO Transport, aucun modèle Store, aucun runtime et aucune persistence. -Le résultat du gate est volontairement étroit : **une seule famille satisfait actuellement les critères d'admission Interface**, le lifecycle de slot sur une intersection minimale de statuts réellement commune entre les surfaces Solana WebSocket et Yellowstone. Toutes les autres familles restent Transport, Store ou reportées. +Le résultat du gate reste volontairement étroit, mais `pre.001-fix.001` corrige deux conclusions trop conservatrices : le lifecycle de slot possède une intersection de **sept** stages communs après normalisation sémantique explicite, et `TransactionExecutionEvent` est rouvert comme candidat actif de `0.3.5` sans être encore admis. Les payloads riches, les logs complets, les snapshots/commitments de signature et les DTOs provider/protocol restent Transport ou Store selon leur ownership. ## 2. Mission @@ -224,7 +224,7 @@ Une égalité de noms ne suffit pas. Une proximité de commitment ne suffit pas. ## 6. Inventaire producer -> nature de fait | Producer / surface | Nature du fait | Champs structurants obligatoires | Optionalité utile | Ordre / lifecycle | Timestamp semantics | Error semantics | Metadata session/provider | Volume potentiel | Persistent/replayable ? | -|----------------------------------------|-------------------------------------|-------------------------------------------------------|-----------------------------------|---------------------------------------------------|-------------------------------------------|----------------------------------------|----------------------------------------|-----------------------|-----------------------------------------| +| -------------------------------------- | ----------------------------------- | ----------------------------------------------------- | --------------------------------- | ------------------------------------------------- | ----------------------------------------- | -------------------------------------- | -------------------------------------- | --------------------- | --------------------------------------- | | Solana WS `slotSubscribe` | progression de slot | slot, parent, root | aucune | event répété à chaque slot traité | aucun | aucune | subscription id hors DTO métier | minime | non | | Solana WS `rootSubscribe` | progression de root | root slot | aucune | event répété lors du changement de root | aucun | aucune | subscription id | minime | non | | Solana WS `slotsUpdatesSubscribe` | lifecycle interne slot | slot, type, timestamp | parent/stats/error selon variante | multi-event par slot ; méthode instable | Unix update timestamp en ms | texte seulement pour `dead` | subscription id | faible à modéré | non | @@ -248,7 +248,7 @@ Une égalité de noms ne suffit pas. Une proximité de commitment ne suffit pas. ### 6.1 Consumers actuels et imminents | Consumer | Besoin actuel / prévu | Dépendance à Interface event | Décision `pre.001` | -|-------------------------------------------|-----------------------------------------------------------|------------------------------|---------------------------------------------------------------------------| +| ----------------------------------------- | --------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------- | | `ksp-program-api` | ProgramInstruction / ProgramAccountMeta | non | préserver la surface Program existante ; aucun re-export acquisition | | `0.3.6` premier backfill RAW | range historique -> Transport -> RAW ingestion -> Store | non | ne pas forcer SlotLifecycle dans le backfill | | futur worker RAW live | subscriptions/fetch live multi-transport -> RAW ingestion | oui, candidat concret | consumer proche justifiant une projection slot lifecycle provider-neutral | @@ -257,54 +257,90 @@ Une égalité de noms ne suffit pas. Une proximité de commitment ne suffit pas. ## 7. Matrice de convergence sémantique -| Nature candidate | Sources comparées | Intersection exacte retenue | Différences non représentables sans perte | Projection commune lossless pour le fait ciblé ? | Consumer concret | Owner | Décision | -|-----------------------------|---------------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------|--------------------------------------------------|-----------------------------------|-----------------|-----------------| -| lifecycle slot | slotSubscribe + slotsUpdates + Yellowstone Slot | Processed, FirstShredReceived, Completed, CreatedBank, Dead | parent/root/timestamps/diagnostics ; Frozen/Optimistic/Root vs Confirmed/Finalized | oui, pour l'occurrence `slot + stage` | futur worker RAW live | Interface | ADMIS | -| root/finality | rootSubscribe + slotsUpdates Root + Yellowstone Finalized | aucune | root et finalized ne sont pas déclarés équivalents par une norme commune | non | aucun besoin exact démontré | Transport | REPORTÉ | -| logs realtime | logsSubscribe + transaction meta logs + Yellowstone tx | signature/logs seulement au prix de perdre la nature de la source | event logs vs matière d'une transaction complète | non pour un fait unique | hydratation possible, non requise | Transport | REPORTÉ | -| transaction status | getSignatureStatuses + signatureSubscribe + Yellowstone TransactionStatus | aucune | snapshot vs transition commitment vs execution update | non | aucun contrat unique démontré | Transport | REPORTÉ | -| vote | voteSubscribe + Yellowstone transaction `is_vote` | qualificatif « vote » seulement | gossip pré-consensus vs transaction exécutée | non | aucun besoin commun démontré | Transport | REPORTÉ | -| account/program | WS account/program + Yellowstone Account | état account complet possible | persistance/replay déjà possédés par RawAccountState/Observation | non comme event distinct | RAW ingestion | Store/Transport | REJET Interface | -| transaction complète | HTTP/WS/Helius/Yellowstone transaction | transaction complète selon source | format/commitment/provider metadata ; RawTransaction déjà canonique Store | non comme second type | RAW ingestion | Store/Transport | REJET Interface | -| block | getBlock/blockSubscribe/Yellowstone Block | slot + block container | payloads/options/reconstruction ; pas de consumer passif minimal prouvé | non | extraction RAW transaction | Transport | REJET Interface | -| Yellowstone Entry | Yellowstone uniquement | aucune multi-source | mono-producer et protocole-specific | non | aucun | Transport | REJET Interface | -| persisted-data available | Store after commit | référence durable compacte conceptuelle | event réseau sans relation ; owner déjà normé par KSP-NOTIFY | oui mais hors owner Interface | processors futurs | Store API | REJET Interface | -| Helius Enhanced transaction | Helius uniquement | aucune multi-source indépendante | filtres/options/provider behavior | non | Transport consumer | Transport | REJET Interface | +| Nature candidate | Sources comparées | Intersection exacte retenue | Différences non représentables sans perte | Projection commune lossless pour le fait ciblé ? | Consumer concret | Owner | Décision | +| ----------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------- | ------------------------------ | ------------------- | +| lifecycle slot | slotSubscribe + slotsUpdates + rootSubscribe + Yellowstone Slot | Processed, FirstShredReceived, Completed, CreatedBank, Dead, OptimisticallyConfirmed, Rooted | Frozen ; parent/timestamps/diagnostics ; noms wire Confirmed/Finalized côté Yellowstone | oui, pour l'occurrence `slot + stage` | futur worker RAW live | Interface | ADMIS | +| transaction execution | logsSubscribe + Yellowstone TransactionStatus + Helius transactionSubscribe | candidat `slot + signature + outcome` | signature primitive KSP à définir ; metadata/provider/detail modes ; delivery semantics | à confirmer par gate dédié avant création du type | futur worker RAW live | Interface si gate passe | CANDIDAT ACTIF | +| logs realtime | logsSubscribe + transaction/meta Yellowstone/Helius | logs associés à une transaction | volume/bornes, richesse de source, disponibilité selon détail | non admis dans cette release sans consumer/bornes | hydratation possible | Interface si futur gate | IDÉE DIFFÉRÉE | +| signature commitment/snapshot | getSignatureStatuses + signatureSubscribe | identité de signature seulement | snapshot HTTP vs transition one-shot commitment | non comme event d'exécution | aucun contrat unique démontré | Transport | REPORTÉ | +| vote | voteSubscribe + Yellowstone transaction `is_vote` | qualificatif « vote » seulement | gossip pré-consensus vs transaction exécutée | non | aucun besoin commun démontré | Transport | REPORTÉ | +| account/program | WS account/program + Yellowstone Account | état account complet possible | persistance/replay déjà possédés par RawAccountState/Observation | non comme event distinct | RAW ingestion | Store/Transport | REJET Interface | +| transaction complète | HTTP/WS/Helius/Yellowstone transaction | transaction complète selon source | format/commitment/provider metadata ; RawTransaction déjà canonique Store | non comme second type | RAW ingestion | Store/Transport | REJET Interface | +| block | getBlock/blockSubscribe/Yellowstone Block | slot + block container | payloads/options/reconstruction ; pas de consumer passif minimal prouvé | non | extraction RAW transaction | Transport | REJET Interface | +| Yellowstone Entry | Yellowstone aujourd'hui | aucune multi-source démontrée | mono-producer et protocole-specific aujourd'hui | non aujourd'hui ; futur fait transversal -> Interface | aucun actuel | Transport DTO | REPORTÉ | +| persisted-data available | Store after commit | référence durable compacte conceptuelle | event réseau sans relation ; owner déjà normé par KSP-NOTIFY | oui mais hors owner Interface | processors futurs | Store API | REJET Interface | +| Helius Enhanced transaction | Helius transactionSubscribe | peut contribuer au candidat TransactionExecutionEvent | filtres/options/provider behavior et DTO riche | DTO non ; projection sémantique possible via converter | futur worker RAW live | Transport DTO / Interface fact | PRODUCTEUR CANDIDAT | ### 7.1 Lifecycle de slot — ADMIS sous intersection stricte -| Fait commun | Solana standard | Yellowstone | Décision Interface | Metadata volontairement non commune | -|--------------------------|-----------------------------------------|----------------------|--------------------|--------------------------------------------------------------------------------| -| slot traité | `slotSubscribe` | `Processed` | ADMIS | parent/root courant côté WS ; filters/created_at/parent côté Yellowstone | -| premier shred reçu | `FirstShredReceived` | `FirstShredReceived` | ADMIS | timestamp WS ; created_at/filters côté Yellowstone | -| ingestion slot complétée | `Completed` | `Completed` | ADMIS | timestamp WS ; created_at/filters côté Yellowstone | -| bank créé | `CreatedBank` | `CreatedBank` | ADMIS | parent requis WS, optionnel Yellowstone ; il reste dans le DTO Transport riche | -| slot mort | `Dead` | `Dead` | ADMIS | diagnostics source-specific et horodatages restent Transport | -| frozen | `Frozen` | aucun statut exact | REJETÉ | pas d'intersection | -| optimistic confirmation | `OptimisticConfirmation` | `Confirmed` | REJETÉ | aucune équivalence normative exacte retenue | -| root | `rootSubscribe` / `slotsUpdates` `Root` | `Finalized` | REJETÉ | aucune équivalence normative exacte retenue | -| confirmed | aucun événement exact retenu | `Confirmed` | REJETÉ | pas de producer standard exact | -| finalized | aucun événement exact retenu | `Finalized` | REJETÉ | root n'est pas promu artificiellement en finalized | +| Fait commun | Solana standard | Yellowstone | Stage KSP | Décision Interface | Metadata volontairement non commune | +| ------------------------ | --------------------------------------- | -------------------- | ------------------------- | ------------------ | ------------------------------------------------------------------------------ | +| slot traité | `slotSubscribe` | `Processed` | `Processed` | ADMIS | parent/root courant côté WS ; filters/created_at/parent côté Yellowstone | +| premier shred reçu | `FirstShredReceived` | `FirstShredReceived` | `FirstShredReceived` | ADMIS | timestamp WS ; created_at/filters côté Yellowstone | +| ingestion slot complétée | `Completed` | `Completed` | `Completed` | ADMIS | timestamp WS ; created_at/filters côté Yellowstone | +| bank créé | `CreatedBank` | `CreatedBank` | `CreatedBank` | ADMIS | parent requis WS, optionnel Yellowstone ; il reste dans le DTO Transport riche | +| slot mort | `Dead` | `Dead` | `Dead` | ADMIS | diagnostics source-specific et horodatages restent Transport | +| confirmation optimiste | `OptimisticConfirmation` | `Confirmed` | `OptimisticallyConfirmed` | ADMIS | le nom KSP conserve la sémantique Solana ; delivery reste Transport | +| root atteint | `rootSubscribe` / `slotsUpdates` `Root` | `Finalized` | `Rooted` | ADMIS | le nom KSP évite de généraliser `Finalized` au-delà du mapping audité | +| frozen | `Frozen` | aucun statut exact | — | REJETÉ | pas d'intersection | Le fait commun est volontairement plus petit que chaque DTO producteur. La conversion **n'efface pas** le DTO Transport : elle ajoute une projection passive `slot + stage` pour les consumers qui n'ont besoin que de l'occurrence de l'étape commune. Le timestamp n'entre pas dans le contrat commun : `slotsUpdatesSubscribe.timestamp` décrit l'horodatage Unix de l'update côté validator alors que `YellowstoneUpdateTimestamp` est une metadata de création serveur. Les réunir sous un seul champ produirait une fausse équivalence. -Le `parent`, le root courant et `dead_error` restent également source-owned ; un consumer qui en a besoin doit conserver le DTO Transport ou définir un contrat supérieur spécifique. +Le `parent`, le root courant exposé comme metadata de certaines notifications, `dead_error` et les détails de delivery restent source-owned ; un consumer qui en a besoin doit conserver le DTO Transport ou définir un contrat supérieur spécifique. Les mappings `OptimisticConfirmation -> OptimisticallyConfirmed <- Yellowstone Confirmed` et `Root -> Rooted <- Yellowstone Finalized` sont des normalisations sémantiques documentées, pas des renommages universels des commitments Solana. -### 7.2 Logs realtime — REPORTÉ +### 7.2 Transaction execution — CANDIDAT ACTIF -Le payload standard `logsSubscribe` est compact et event-only, mais le gate ne démontre pas une deuxième surface sémantiquement indépendante qui produise exactement le même fait : +`pre.001-fix.001` sépare désormais l'**exécution observée d'une transaction** des snapshots/commitments de signature. Trois producers peuvent exposer le même fait minimal : -- Helius standard réutilise le wire standard Solana et n'ajoute donc pas un nouveau contrat ; -- Yellowstone expose des logs dans la transaction/meta complète, pas une notification `logsSubscribe` équivalente ; -- la signature + logs peut déclencher une hydratation, mais ce besoin pourra être porté directement par le DTO Transport tant qu'un consumer multi-transport concret n'exige pas une projection commune. +```text +Solana logsSubscribe + -> context slot + signature + err -Aucun `RawLog`, `TransactionLogEvent` ou équivalent public n'est donc créé en `0.3.5` sauf réouverture explicite du gate avec un nouveau producer/consumer. +Yellowstone TransactionStatus + -> slot + signature + err + metadata Yellowstone -### 7.3 Transaction status — REPORTÉ +Helius transactionSubscribe + -> slot + signature/transaction + résultat d'exécution selon le detail mode +``` -Les trois familles restent distinctes : +Le contrat candidat est conceptuellement : + +```text +TransactionExecutionEvent { + slot, + signature, + outcome = Succeeded | Failed, +} +``` + +Il n'est **pas encore admis** dans `pre.001-fix.001`. Un gate dédié doit encore démontrer : + +- une représentation KSP-owned de la signature compatible avec le dependency firewall actuel ; +- que le mapping Helius retenu reste valide pour les detail modes réellement supportés sans dépendre d'un payload complet ; +- que `err == null` / `err != null` suffit bien à définir le fait `Succeeded` / `Failed` sans copier l'erreur source ; +- que le consumer proche justifie cette projection sans concurrencer `RawTransaction`/`RawTransactionObservation`. + +Les DTOs `logsSubscribe`, Yellowstone `TransactionStatus` et Helius `transactionSubscribe` restent intégralement Transport-owned. Seule une éventuelle projection passive commune appartiendrait à Interface. + +### 7.3 Logs realtime et signature commitment — DIFFÉRENCIÉS + +Les logs ne sont plus utilisés comme argument pour rejeter l'exécution commune : `logsSubscribe` peut produire un `TransactionExecutionEvent` sans que les lignes de logs entrent dans le contrat partagé. + +Une éventuelle famille distincte reste une **idée différée** : + +```text +TransactionLogEvent { + slot, + signature, + logs, +} +``` + +Elle n'est pas admise en `0.3.5` tant que les bornes, la disponibilité multi-producer et un consumer concret ne sont pas démontrés. Aucun `RawLog` n'est créé. + +Les surfaces de commitment/snapshot restent séparées de l'exécution : ```text HTTP getSignatureStatuses @@ -312,12 +348,9 @@ HTTP getSignatureStatuses WS signatureSubscribe = transition one-shot vers le commitment demandé, éventuellement précédée de ReceivedSignature - -Yellowstone transaction_status - = update execution/status avec signature, slot, is_vote, index et error ``` -Une struct avec de nombreux `Option` perdrait les distinctions entre snapshot, observation de réception, transition de commitment et update d'exécution. La décision de `0.3.1` est donc confirmée. +Aucun `TransactionCommitmentEvent` n'est admis. Une future famille de commitment devra être auditée indépendamment et ne pourra pas être fusionnée avec `TransactionExecutionEvent` par une struct à nombreux `Option`. ### 7.4 Vote — REPORTÉ @@ -346,9 +379,9 @@ La conversion Transport -> Store API reste à la composition. `RawTransaction` et `RawTransactionObservation` sont déjà Store-owned. Les blocs servent de conteneurs d'acquisition ou de payloads Transport riches. Aucun `RawBlock`, `TransactionEvent` ou `BlockEvent` transversal n'est ajouté. -### 7.7 Yellowstone Entry — REJET Interface +### 7.7 Yellowstone Entry — Transport aujourd'hui, ownership sémantique réservé -`Entry` n'a qu'un producer/protocole démontré et ne possède aucun consumer transversal proche. Il reste strictement Transport. +`SubscribeUpdateEntry` reste un DTO Yellowstone strictement Transport-owned : un seul producer/protocole est démontré aujourd'hui et aucun consumer transversal proche ne justifie un type partagé. Cette décision ne réserve toutefois pas le **fait** à Transport : si une future seconde source permet de reconstruire un même `LedgerEntryEvent` provider-neutral, ce nouveau fait passif devra être audité pour ownership Interface, sans déplacer le DTO Yellowstone lui-même. ### 7.8 Notification after commit — REJET Interface @@ -366,6 +399,8 @@ pub enum SlotLifecycleStage { Completed, CreatedBank, Dead, + OptimisticallyConfirmed, + Rooted, } pub struct SlotLifecycleEvent { @@ -405,7 +440,7 @@ Contraintes : - aucune conversion `From` dans Interface, car cela créerait une dépendance interdite ; - les converters appartiennent au futur consumer/composition ou, si un usage concret le justifie plus tard, à une crate de composition dédiée. -Le nom final peut être ajusté pendant `pre.002` seulement si les canaris montrent une ambiguïté réelle. Le sens `slot + stage commun` ne doit pas être élargi. +Le nom final peut être ajusté pendant `pre.002` seulement si les canaris montrent une ambiguïté réelle. Le sens `slot + stage commun` ne doit pas être élargi. `OptimisticallyConfirmed` et `Rooted` sont volontairement préférés à `Confirmed` et `Finalized` afin de conserver la sémantique KSP du fait normalisé sans transformer les labels Yellowstone en terminologie universelle. ## 9. Consumer proche et usage concret @@ -425,7 +460,7 @@ Cette API ne devient pas un prérequis de `0.3.6` : le premier backfill historiq ## 10. Anti-duplication Store | Contrat Store comparé | Chevauchement avec `SlotLifecycleEvent` | Pourquoi il n'y a pas de seconde vérité | -|-----------------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------| +| --------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- | | `RawTransaction` | slot possible seulement | aucun payload/signature/format/hash ; l'event ne peut reconstruire une transaction | | `RawTransactionObservation` | slot indirect possible | aucune provenance acquisition, observation key ou timestamp durable | | `RawAccountState` | slot possible seulement | aucune pubkey/state hash/lamports/owner/data ; aucun état account | @@ -476,22 +511,22 @@ future acquisition composition / RAW live worker ## 12. Threat model -| Risque | Menace | Garde planifiée | -|--------------------------------|------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------| -| mega enum | Interface devient catalogue de tous les transports | une seule famille étroite ; aucun `Event` générique | -| Option soup | sémantiques différentes fusionnées par champs optionnels | `slot + stage` seulement ; status/log/vote non convergents reportés | -| persistence creep | event-only devient second Store | aucun RAW/payload/cursor/retention ; `KSP-NOTIFY-*` reste Store API | -| transport wrapper | copie des DTOs WS/gRPC/provider | aucune metadata protocol/provider dans le type Interface | -| faux timestamp commun | horodatages WS et Yellowstone confondus | aucun timestamp partagé | -| root/finality confusion | `root` normalisé artificiellement en `Finalized` | aucun stage Root/Finalized tant qu'une équivalence normative exacte n'est pas démontrée | -| optimistic/confirmed confusion | `OptimisticConfirmation` fusionné à `Confirmed` | deux états exclus de l'intersection | -| dead diagnostic leak | texte provider/validator traverse une API partagée durable | stage `Dead` sans diagnostic ; détail reste Transport | -| cross-network confusion | event sans réseau mélangé entre sessions | conversion autorisée seulement dans une composition déjà liée à un contexte réseau ; pas de network id dupliqué | -| unbounded payload | logs/JSON/bytes entrent dans Interface | aucun payload variable dans la famille admise | -| public enum breakage | ajout futur casse les matches externes | `SlotLifecycleStage` non-exhaustive | -| logging/runtime creep | crate passive acquiert tracing/Tokio/channel | aucune dependency/runtime/logging ajoutée | -| Helius semantic promotion | extension provider devient norme KSP | Enhanced `transactionSubscribe` reste Transport | -| Yellowstone protocol promotion | `Entry`/filters/created_at deviennent Interface | types Yellowstone restent Transport | +| Risque | Menace | Garde planifiée | +| ------------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| mega enum | Interface devient catalogue de tous les transports | familles admises séparées et étroites ; aucun `Event` générique | +| Option soup | sémantiques différentes fusionnées par champs optionnels | familles séparées : SlotLifecycle ; candidat TransactionExecution ; logs/commitment restent distincts | +| persistence creep | event-only devient second Store | aucun RAW/payload/cursor/retention ; `KSP-NOTIFY-*` reste Store API | +| transport wrapper | copie des DTOs WS/gRPC/provider | aucune metadata protocol/provider dans le type Interface | +| faux timestamp commun | horodatages WS et Yellowstone confondus | aucun timestamp partagé | +| root/finality confusion | label Yellowstone `Finalized` promu comme vérité universelle | stage KSP `Rooted` ; mapping source explicite `Root <-> Yellowstone Finalized` sans renommer le fait KSP | +| optimistic/confirmed confusion | label Yellowstone `Confirmed` promu comme commitment générique | stage KSP `OptimisticallyConfirmed` ; mapping source explicite avec l'optimistic confirmation Solana | +| dead diagnostic leak | texte provider/validator traverse une API partagée durable | stage `Dead` sans diagnostic ; détail reste Transport | +| cross-network confusion | event sans réseau mélangé entre sessions | conversion autorisée seulement dans une composition déjà liée à un contexte réseau ; pas de network id dupliqué | +| unbounded payload | logs/JSON/bytes entrent dans Interface | aucun payload variable dans la famille admise | +| public enum breakage | ajout futur casse les matches externes | `SlotLifecycleStage` non-exhaustive | +| logging/runtime creep | crate passive acquiert tracing/Tokio/channel | aucune dependency/runtime/logging ajoutée | +| Helius semantic promotion | DTO/provider extension devient norme KSP | `transactionSubscribe` reste Transport ; seule une projection sémantique commune peut devenir Interface | +| Yellowstone protocol promotion | DTO `Entry`/filters/created_at deviennent Interface | types Yellowstone restent Transport ; un futur fait transversal est réaudité séparément | ## 13. Stratégie de tests @@ -523,14 +558,22 @@ SolanaSlotUpdate::FirstShredReceived -> FirstShredReceived SolanaSlotUpdate::Completed -> Completed SolanaSlotUpdate::CreatedBank -> CreatedBank SolanaSlotUpdate::Dead -> Dead -YellowstoneSlotStatus équivalents -> mêmes stages +SolanaSlotUpdate::OptimisticConfirmation -> OptimisticallyConfirmed +SolanaRoot / SolanaSlotUpdate::Root -> Rooted +YellowstoneSlotStatus::Confirmed -> OptimisticallyConfirmed +YellowstoneSlotStatus::Finalized -> Rooted +YellowstoneSlotStatus autres équivalents -> mêmes stages ``` -Et devra explicitement refuser de convertir les variantes hors intersection en un faux stage commun. +Et devra explicitement refuser `Frozen` ou toute variante future sans mapping audité au lieu d'inventer un faux stage commun. + +## 13.3 Traçabilité des candidats différés + +`TransactionExecutionEvent` reste un candidat actif de cette release et est donc suivi dans le présent plan/validation plutôt que déplacé dans un TODO durable avant son gate. `TransactionLogEvent` est explicitement une idée différée. Si cette idée reste hors scope à la réconciliation documentaire finale, elle doit être reportée dans la surface TODO/IDEAS durable appropriée au lieu d'être perdue avec le plan de release. ## 14. Prévision souple des prereleases -La release est dimensionnée pour rester dans une seule session et ne possède qu'une famille fonctionnelle retenue. +La release reste dimensionnée pour une seule session. `SlotLifecycleEvent` est la seule famille admise immédiatement ; `TransactionExecutionEvent` devient un second candidat actif qui doit passer un gate dédié avant toute implémentation. ### `0.3.5-pre.001` — audit + plan @@ -549,16 +592,22 @@ La release est dimensionnée pour rester dans une seule session et ne possède q - tests unitaires et public API ciblés ; - préserver le graphe Core-only. -### `0.3.5-pre.003` — canaris externes + complétude API +### `0.3.5-pre.003` — gate `TransactionExecutionEvent` -- external consumer ; +- auditer la représentation de signature compatible avec les règles de dépendances ; +- prouver les mappings exacts Solana `logsSubscribe` / Yellowstone `TransactionStatus` / Helius `transactionSubscribe` ; +- vérifier anti-duplication Store et consumer concret ; +- si et seulement si le gate est complet, implémenter la famille minimale `slot + signature + outcome` ; +- sinon enregistrer explicitement le rejet/report sans type partiel. + +### `0.3.5-pre.004` — canaris externes + complétude API + +- external consumer pour toutes les familles effectivement admises ; - inventaire exact des modules/exports ; - canaris négatifs contre Transport/Store/runtime/serde/logging ; - non-exhaustive et stabilité de la surface. -Cette tranche ne crée aucune deuxième famille d'event sauf réouverture documentée du gate avec preuve nouvelle. Le défaut est de conserver logs/status/vote/root reportés. - -### `0.3.5-pre.004` — hardening final +### `0.3.5-pre.005` — hardening final - adversarial/API hardening ; - absence de payload/source metadata ; @@ -566,20 +615,20 @@ Cette tranche ne crée aucune deuxième famille d'event sauf réouverture docume - validation du graphe et des dépendances ; - aucun élargissement fonctionnel opportuniste. -### `0.3.5-pre.005` — gate technique final +### `0.3.5-pre.006` — gate technique final - gates Rust/workspace complets ; - `cargo tree` Interface normal/features/duplicates ; -- aucun smoke live requis : le contrat est passif et ne possède aucun réseau. +- aucun smoke live requis : les contrats Interface restent passifs et ne possèdent aucun réseau. -### `0.3.5-pre.006` — réconciliation documentaire finale +### `0.3.5-pre.007` — réconciliation documentaire finale - plan + validation ; - README/USAGE Interface durables et version-neutral ; - architecture durable uniquement si le rôle Interface doit être explicité ; - aucun CHANGELOG/ROADMAP/prompt suivant dans cette tranche. -### `0.3.5-pre.007` — préparation de publication +### `0.3.5-pre.008` — préparation de publication Lane minimale : @@ -588,7 +637,7 @@ Cargo.toml CHANGELOG.md ROADMAP.md prompts/025-V0_3_6_START_PROMPT.md -deltas/0.3.5/pre.007.md +deltas/0.3.5/pre.008.md ``` Aucun code, README/USAGE, plan ou validation ne doit être rouvert ici. @@ -642,11 +691,13 @@ persistence ou migration Store nouvelle capability Store RawLog / RawBlock TransactionStatusObservation fusionné +TransactionCommitmentEvent fusionné avec execution +TransactionLogEvent sans nouveau gate de bornes/consumer VoteEvent partagé -Root == Finalized -OptimisticConfirmation == Confirmed +label KSP `Finalized` utilisé comme alias universel de root +label KSP `Confirmed` utilisé comme alias universel d'optimistic confirmation Helius Enhanced DTO dans Interface -Yellowstone Entry dans Interface +Yellowstone Entry DTO dans Interface serde/wincode/borsh ajouté sans protocole réel logging/runtime dans Interface conversion Transport -> Interface possédée par Interface @@ -658,8 +709,9 @@ La release peut fermer si et seulement si : ```text une famille minimale SlotLifecycle est publique et bornée -intersection = Processed + FirstShredReceived + Completed + CreatedBank + Dead -aucune variante hors intersection n'est normalisée artificiellement +intersection = Processed + FirstShredReceived + Completed + CreatedBank + Dead + OptimisticallyConfirmed + Rooted +Frozen et toute variante future sans mapping audité ne sont pas normalisées artificiellement +TransactionExecutionEvent est soit admis après son gate dédié, soit explicitement reporté sans type partiel aucun payload/diagnostic/timestamp/provider metadata n'entre dans Interface Interface reste Core-only Store RAW 10/10 reste inchangé diff --git a/docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md b/docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md index 2ecb533..8770350 100644 --- a/docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md +++ b/docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md @@ -1,11 +1,11 @@ - + # Validation `0.3.5` — Interface passive acquisition events ## 1. Portée -Ce document est ouvert par `0.3.5-pre.001`. Il enregistre uniquement des constats d'audit et des décisions de gate réellement effectués ; aucun test Cargo de `0.3.5` n'est déclaré PASS dans cette tranche tant qu'il n'a pas été rejoué par l'opérateur. +Ce document est ouvert par `0.3.5-pre.001` et corrigé par `0.3.5-pre.001-fix.001`. Le fix enregistre les corrections sémantiques du gate ainsi que le gate Cargo réellement rejoué par l'opérateur sur `0.3.5-pre.1`. Base : @@ -28,52 +28,49 @@ Cette preuve est l'entrée de `0.3.5`. Elle n'est pas réétiquetée comme valid ## 3. Gate de lecture `pre.001` -| Contrôle | Résultat | Preuve / décision | -|---------------------------------------|----------|--------------------------------------------------------------------------------------------------------| -| règles globales relues | PASS | familles KSP-API/TRANSPORT/STORE/NOTIFY/PROC/REL et DEP applicables relues | -| architecture durable relue | PASS | Interface passif, Transport protocol/runtime, Store persistant, composition owner des conversions | -| fondation Interface stable relue | PASS | surface Program petite ; dépendance normale Core-only | -| Store API RAW relu | PASS | `RawTransaction*` + `RawAccount*` restent Store-owned | -| Store/PostgreSQL `0.3.2`–`0.3.4` relu | PASS | RAW physique 10/10 fermé ; aucune rétention account | -| surfaces HTTP/WS/gRPC/Helius relues | PASS | status/log/slot/vote/account/transaction/block/Entry inventoriés | -| documentation Solana courante auditée | PASS | `slotSubscribe`, `slotsUpdatesSubscribe`, status/log/vote/account/program, getTransaction/getBlock | -| Yellowstone upstream courant audité | PASS | `SlotStatus` et familles SubscribeUpdate courantes | -| Helius courant audité | PASS | standard WSS préserve wire Solana ; Enhanced `transactionSubscribe` reste extension provider | -| producer/consumer inventory | PASS | une intersection lifecycle slot justifiée ; autres familles non admises | -| threat model | PASS | mega enum, Option soup, Store duplication, timestamp/finality confusion et provider promotion couverts | -| sizing release | PASS | 7 prereleases prévues avant `rel.001`, une seule famille fonctionnelle | +| Contrôle | Résultat | Preuve / décision | +| ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | +| règles globales relues | PASS | familles KSP-API/TRANSPORT/STORE/NOTIFY/PROC/REL et DEP applicables relues | +| architecture durable relue | PASS | Interface passif, Transport protocol/runtime, Store persistant, composition owner des conversions | +| fondation Interface stable relue | PASS | surface Program petite ; dépendance normale Core-only | +| Store API RAW relu | PASS | `RawTransaction*` + `RawAccount*` restent Store-owned | +| Store/PostgreSQL `0.3.2`–`0.3.4` relu | PASS | RAW physique 10/10 fermé ; aucune rétention account | +| surfaces HTTP/WS/gRPC/Helius relues | PASS | status/log/slot/vote/account/transaction/block/Entry inventoriés | +| documentation Solana courante auditée | PASS | `slotSubscribe`, `slotsUpdatesSubscribe`, status/log/vote/account/program, getTransaction/getBlock | +| Yellowstone upstream courant audité | PASS | `SlotStatus` et familles SubscribeUpdate courantes | +| Helius courant audité | PASS | standard WSS préserve wire Solana ; Enhanced `transactionSubscribe` reste extension provider | +| producer/consumer inventory | PASS | lifecycle slot 7 stages admis ; TransactionExecutionEvent rouvert comme candidat actif | +| threat model | PASS | mega enum, Option soup, Store duplication, mapping lifecycle explicite et provider promotion couverts | +| sizing release | PASS | 8 prereleases prévues avant `rel.001` ; second candidat soumis à gate dédié | ## 4. Matrice de décision par famille -| Famille | Décision | Owner | Motif déterminant | -|---------------------------------------|-----------------|-----------------|---------------------------------------------------------------------------------------------| -| slot lifecycle intersection | ADMIS | Interface | faits compacts exacts produits par Solana WS et Yellowstone ; pas de persistence | -| root/finality | REPORTÉ | Transport | aucune équivalence normative exacte `root` <-> `Finalized` retenue | -| optimistic/confirmed | REPORTÉ | Transport | aucune équivalence normative exacte retenue | -| logs realtime | REPORTÉ | Transport | pas de seconde surface indépendante équivalente ; Yellowstone logs restent transaction/meta | -| transaction status | REPORTÉ | Transport | HTTP snapshot != WS one-shot commitment != Yellowstone execution update | -| vote | REPORTÉ | Transport | gossip pré-consensus != transaction qualifiée `is_vote` | -| account/program | REJET Interface | Store/Transport | risque de doublon `RawAccountState`/observation ou wrapper Transport | -| transaction | REJET Interface | Store/Transport | `RawTransaction`/observation déjà persistants | -| block | REJET Interface | Transport | conteneur/payload d'acquisition ; aucun besoin passif transversal démontré | -| Yellowstone Entry | REJET Interface | Transport | surface protocolaire mono-producer | -| persisted-data available notification | REJET Interface | Store API | ownership normatif `KSP-NOTIFY-001..006` | -| Helius Enhanced transaction | REJET Interface | Transport | extension provider-specific | +| Famille | Décision | Owner | Motif déterminant | +| ------------------------------------- | ------------------- | ------------------------------ | ---------------------------------------------------------------------------------------- | +| slot lifecycle intersection | ADMIS | Interface | 7 faits compacts normalisés ; détails protocol/provider restent Transport | +| transaction execution | CANDIDAT ACTIF | Interface si gate passe | intersection candidate `slot + signature + outcome` sur Solana/Yellowstone/Helius | +| logs realtime | IDÉE DIFFÉRÉE | Interface si futur gate | payload variable/bornes/consumer non démontrés ; ne pas mélanger avec execution | +| signature commitment/snapshot | REPORTÉ | Transport | HTTP snapshot != WS one-shot commitment ; distinct de l'exécution | +| vote | REPORTÉ | Transport | gossip pré-consensus != transaction qualifiée `is_vote` | +| account/program | REJET Interface | Store/Transport | risque de doublon `RawAccountState`/observation ou wrapper Transport | +| transaction | REJET Interface | Store/Transport | `RawTransaction`/observation déjà persistants | +| block | REJET Interface | Transport | conteneur/payload d'acquisition ; aucun besoin passif transversal démontré | +| Yellowstone Entry | REPORTÉ | Transport DTO | mono-producer aujourd'hui ; un futur fait transversal KSP serait réaudité pour Interface | +| persisted-data available notification | REJET Interface | Store API | ownership normatif `KSP-NOTIFY-001..006` | +| Helius Enhanced transaction | PRODUCTEUR CANDIDAT | Transport DTO / Interface fact | DTO provider-specific ; projection possible seulement vers un fait commun admis | ## 5. Intersection lifecycle retenue -| Stage Interface prévu | Producer Solana standard | Producer Yellowstone | Verdict | Détails exclus du contrat commun | -|--------------------------|----------------------------------------|----------------------|---------|-------------------------------------------------------------------------| -| `Processed` | `slotSubscribe` | `Processed` | PASS | WS parent/root ; Yellowstone filters/created_at/parent | -| `FirstShredReceived` | `slotsUpdates::FirstShredReceived` | `FirstShredReceived` | PASS | timestamps/metadata source | -| `Completed` | `slotsUpdates::Completed` | `Completed` | PASS | timestamps/metadata source | -| `CreatedBank` | `slotsUpdates::CreatedBank` | `CreatedBank` | PASS | parent reste dans le DTO Transport riche | -| `Dead` | `slotsUpdates::Dead` | `Dead` | PASS | diagnostic `err`/`dead_error` et timestamp restent Transport | -| `Frozen` | `slotsUpdates::Frozen` | — | FAIL | pas d'intersection | -| `OptimisticConfirmation` | `slotsUpdates::OptimisticConfirmation` | `Confirmed` | FAIL | noms/semantiques proches insuffisants sans équivalence normative exacte | -| `Root` | `rootSubscribe` / `slotsUpdates::Root` | `Finalized` | FAIL | aucune normalisation root/finalized inventée | -| `Confirmed` | — | `Confirmed` | FAIL | producer standard exact absent | -| `Finalized` | — | `Finalized` | FAIL | producer standard exact absent | +| Stage Interface prévu | Producer Solana standard | Producer Yellowstone | Verdict | Détails exclus du contrat commun | +| ------------------------- | -------------------------------------- | -------------------- | ------- | -------------------------------------------------------------------------------- | +| `Processed` | `slotSubscribe` | `Processed` | PASS | WS parent/root ; Yellowstone filters/created_at/parent | +| `FirstShredReceived` | `slotsUpdates::FirstShredReceived` | `FirstShredReceived` | PASS | timestamps/metadata source | +| `Completed` | `slotsUpdates::Completed` | `Completed` | PASS | timestamps/metadata source | +| `CreatedBank` | `slotsUpdates::CreatedBank` | `CreatedBank` | PASS | parent reste dans le DTO Transport riche | +| `Dead` | `slotsUpdates::Dead` | `Dead` | PASS | diagnostic `err`/`dead_error` et timestamp restent Transport | +| `OptimisticallyConfirmed` | `slotsUpdates::OptimisticConfirmation` | `Confirmed` | PASS | nom KSP conserve l'optimistic confirmation ; delivery/metadata restent Transport | +| `Rooted` | `rootSubscribe` / `slotsUpdates::Root` | `Finalized` | PASS | nom KSP conserve le fait root ; `Finalized` reste un label Yellowstone source | +| — | `slotsUpdates::Frozen` | — | FAIL | pas d'intersection | ## 6. Validation anti-Option-soup @@ -86,6 +83,7 @@ TransactionStatusObservation { received?: ..., is_vote?: ..., transaction_index?: ..., + logs?: ..., ... } @@ -99,16 +97,22 @@ SlotLifecycleEvent { } ``` -La surface visée reste conceptuellement : +La surface admise reste conceptuellement : ```text SlotLifecycleEvent { slot, stage } ``` +Le candidat séparé, non encore admis, reste : + +```text +TransactionExecutionEvent { slot, signature, outcome } +``` + ## 7. Validation anti-duplication Store | Modèle Store stable | Action `0.3.5` | Justification | -|---------------------------------|---------------------|------------------------------------------------| +| ------------------------------- | ------------------- | ---------------------------------------------- | | `RawTransaction` | inchangé | payload durable/replayable | | `RawTransactionObservation` | inchangé | provenance persistante | | `RawAccountState` | inchangé | état account durable | @@ -139,7 +143,7 @@ ksp-interface-lib -X-> ksp-program-api ksp-interface-lib -X-> serde/tracing/tokio/channel runtime additions ``` -Le `cargo tree` ne peut pas être exécuté dans l'environnement d'assemblage actuel, où `cargo` est absent. Le gate opérateur est donc obligatoire sur l'overlay. +Le gate opérateur de `pre.001` confirme `cargo check --workspace`, Clippy et les tests `ksp-interface-lib`. Les graphes `cargo tree` restent réservés au gate technique final de la release. ## 9. Consumer concret retenu @@ -157,22 +161,22 @@ Yellowstone gRPC -------------+ ## 10. Threat gates -| Gate | Attendu `0.3.5` | Statut `pre.001` | -|----------------------------------|-----------------------------------------------|------------------| -| mega enum | absent | PLAN PASS | -| protocol/provider enum leakage | absent | PLAN PASS | -| timestamp semantics conflated | absent | PLAN PASS | -| root/finalized conflated | absent | PLAN PASS | -| optimistic/confirmed conflated | absent | PLAN PASS | -| dead diagnostic in shared API | absent | PLAN PASS | -| RAW Store duplication | absent | PLAN PASS | -| event persistence | absent | PLAN PASS | -| event bus/runtime | absent | PLAN PASS | -| network id duplicated from Store | absent | PLAN PASS | -| cross-network use | composition doit conserver son scope réseau | À CANARIER | -| public enum evolution | `SlotLifecycleStage` doit être non-exhaustive | À IMPLÉMENTER | -| Core-only graph | aucune dependency nouvelle | À REJOUER | -| external consumer | type consommable depuis crate externe | À IMPLÉMENTER | +| Gate | Attendu `0.3.5` | Statut `pre.001` | +| ------------------------------------ | ------------------------------------------------- | ---------------- | +| mega enum | absent | PLAN PASS | +| protocol/provider enum leakage | absent | PLAN PASS | +| timestamp semantics conflated | absent | PLAN PASS | +| root/finalized label confusion | évitée par le stage KSP `Rooted` | PLAN PASS | +| optimistic/confirmed label confusion | évitée par le stage KSP `OptimisticallyConfirmed` | PLAN PASS | +| dead diagnostic in shared API | absent | PLAN PASS | +| RAW Store duplication | absent | PLAN PASS | +| event persistence | absent | PLAN PASS | +| event bus/runtime | absent | PLAN PASS | +| network id duplicated from Store | absent | PLAN PASS | +| cross-network use | composition doit conserver son scope réseau | À CANARIER | +| public enum evolution | `SlotLifecycleStage` doit être non-exhaustive | À IMPLÉMENTER | +| Core-only graph | aucune dependency nouvelle | PASS opérateur | +| external consumer | type consommable depuis crate externe | À IMPLÉMENTER | ## 11. Fichiers de `pre.001` @@ -192,20 +196,23 @@ Cargo.toml Aucun autre fichier ne doit changer dans cet overlay. -## 12. Validations exécutées dans l'environnement d'assemblage +## 12. Validations statiques de l'overlay initial -Exécutables sans Cargo : +L'overlay `pre.001` avait exécuté les audits disponibles 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/0.3.5 +-> Markdown table audit: clean (251 table(s), 137 file(s)) ``` -Le résultat réel est enregistré dans `deltas/0.3.5/pre.001.md` après exécution. +## 13. Gate opérateur `pre.001` reçu avant `fix.001` -## 13. Validations opérateur requises - -À appliquer sur le repository `v0.3.4` après extraction de l'overlay : +L'opérateur a rejoué depuis un `cargo clean` : ```text cargo fmt --all @@ -216,19 +223,40 @@ cargo clippy --workspace --all-targets cargo test -p ksp-interface-lib ``` -Aucun `cargo test -p ksp-program-api` n'est requis par le contenu de `pre.001`, car aucun contrat public Interface n'est encore modifié. Il devient requis à partir de la première tranche qui change réellement la surface publique concernée. +Résultat : **PASS intégral**. -## 14. Exit gate `pre.001` - -`pre.001` est prêt à livrer lorsque : +Preuves synthétiques : ```text -plan + validation + delta existent -workspace.package.version = 0.3.5-pre.1 -une seule famille est admise : SlotLifecycle -stages admis = Processed / FirstShredReceived / Completed / CreatedBank / Dead -logs/status/vote/root/account/transaction/block/Entry/post-commit sont classés explicitement -aucun fichier Rust/Transport/Store n'est modifié -les audits statiques disponibles sont propres -les gates Cargo non exécutables sont explicitement laissés à l'opérateur +General Rust rule audit: clean +Rust export completeness audit: 0 candidate(s) +KSP workspace Rust rule audit: clean +Markdown table audit: clean (251 table(s), 137 file(s)) +cargo check --workspace -> PASS +cargo clippy --workspace --all-targets -> PASS +ksp-interface-lib unit tests -> 10 passed +ksp-interface-lib dependency_boundary -> 4 passed +ksp-interface-lib external_consumer -> 1 passed +ksp-interface-lib public_api -> 5 passed +ksp-interface-lib release_completeness -> 3 passed +doc-tests -> 0 failed +``` + +`pre.001-fix.001` est documentation-only ; il ne modifie ni Cargo ni Rust. L'opérateur doit néanmoins rejouer les deux audits Markdown/Rust après application du fix pour confirmer l'overlay final. + +## 14. Exit gate `pre.001-fix.001` + +Le gate corrigé impose désormais : + +```text +workspace.package.version = 0.3.5-pre.1 inchangée +SlotLifecycle admis avec 7 stages +stages = Processed / FirstShredReceived / Completed / CreatedBank / Dead / OptimisticallyConfirmed / Rooted +Frozen reste hors intersection +TransactionExecutionEvent = candidat actif mais non encore admis +TransactionLogEvent = idée différée, distincte de l'exécution +getSignatureStatuses/signatureSubscribe = snapshot/commitment Transport, non fusionnés avec execution +Helius transactionSubscribe et Yellowstone Entry restent des DTOs Transport +un futur fait provider-neutral produit par une extension provider peut appartenir à Interface après gate +aucun fichier Rust/Transport/Store/Cargo n'est modifié par le fix ```