# Prompt de démarrage `0.3.5` — Interface passive acquisition events ## 1. Identité de la release et base exacte requise La release à ouvrir est : ```text 0.3.5 — ksp-interface-lib : modèles passifs/event-only réellement partagés ``` La base autoritaire attendue est exclusivement la release stable : ```text v0.3.4 workspace.package.version = 0.3.4 ``` L'archive/repository `v0.3.4` fourni par l'opérateur prévaut sur toute mémoire, snippet, ancien artefact ou hypothèse de cette session. La première tranche est : ```text 0.3.5-pre.001 ``` Elle est obligatoirement une tranche de **lecture + inventaire des consumers/producers + audit sémantique multi-transport + brainstorming + threat model + sizing + planification**. Ne pas créer immédiatement une grande enum `Event`, des wrappers de DTO Transport ou des modèles persistants parallèles avant la sortie cohérente de ce gate. --- ## 2. Mission et résultat attendu `0.3.5` intervient après la fermeture de la persistence RAW PostgreSQL : ```text 0.3.1 ksp-store-api : contrats RAW backend-agnostic 0.3.2 Store/PostgreSQL foundation 0.3.3 RawTransaction PostgreSQL 0.3.4 RawAccountState PostgreSQL + RAW 10/10 0.3.5 Interface : événements passifs réellement partagés ``` La mission est d'étendre **`ksp-interface-lib` uniquement lorsque la sémantique d'un événement est réellement commune**, afin que les couches de composition/acquisition futures puissent consommer un contrat KSP passif sans dépendre des DTOs HTTP/WS/gRPC/provider. Le résultat attendu n'est **pas** un catalogue exhaustif de tout ce que les transports savent notifier. Le résultat attendu est : ```text inventaire actuel des surfaces event-like matrice de convergence sémantique par candidat ownership Interface/Transport/Store/consumer explicitement décidé un sous-ensemble minimal de contrats passifs KSP-owned réellement justifiés aucune duplication des modèles persistants/replayables de ksp-store-api aucune dépendance Interface -> Transport ou Interface -> Store aucun event bus, scheduler, worker, job ou persistence aucun provider DTO promu en contrat transversal API crate-root stable, bornée et consommable depuis une crate externe ``` Une famille candidate **reste reportée** si le gate ne démontre pas simultanément une sémantique commune suffisamment précise et un usage consumer concret/proche qui justifie une API publique durable. La release suivante reste : ```text 0.3.6 — ksp-job-api + premier backfill historique RAW concret ``` --- ## 3. Sources de vérité internes obligatoires — ordre de lecture ### 3.1 Règles globales Lire d'abord : ```text RULES.md docs/000-README.md docs/rules/RULES_GENERAL.md docs/rules/RULES_KSP.md docs/rules/RULES_RUST.md docs/rules/RULES_DEPENDENCIES.md docs/rules/RULES_DOCUMENTATION.md docs/rules/FILE_CONTRACTS.md docs/rules/VERSION_WORKFLOW.md docs/rules/PROMPT_STRUCTURE.md ``` Relire particulièrement les familles applicables : ```text KSP-API-* KSP-TRANSPORT-* KSP-STORE-* KSP-NOTIFY-* KSP-PROC-* KSP-REL-* DEP-KSP-* DEP-LOG-* DEP-STORE-* DEP-WORKER-* DEP-JOB-* ``` Rappels structurants : ```text ksp-interface-lib -> ksp-core-lib ksp-interface-lib -X-> ksp-program-api ksp-interface-lib -X-> ksp-program-lib ksp-interface-lib -X-> ksp-onchain-transport-lib ksp-interface-lib -X-> ksp-store-api ksp-interface-lib -X-> ksp-store-lib ksp-interface-lib -X-> Config/Wallet ksp-onchain-transport-lib possède ses DTOs/runtime HTTP/WS/gRPC ksp-store-api possède les modèles persistants/replayables RAW composition supérieure convertit entre contrats lorsque nécessaire ``` Un fix strictement documentaire ne modifie pas `workspace.package.version`. Une prerelease non-fix, y compris la tranche de publication, synchronise la version Cargo conformément à `VER-ID-009`. ### 3.2 Architecture durable Lire ensuite : ```text docs/architecture/000-README.md docs/architecture/001-PROJECT_OBJECTIVES.md docs/architecture/002-LAYERS_AND_DEPENDENCIES.md docs/architecture/003-COMPONENT_CONTRACTS.md docs/architecture/004-COMPONENT_INVENTORY.md docs/architecture/005-DEPENDENCY_GRAPH.md docs/architecture/006-WIRE_AND_PROGRAM.md docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md ``` Préserver notamment : ```text Interface = contrat passif/wire partagé, pas runtime réseau Transport = protocoles, sessions, provider DTOs, backpressure/reconnect Store API = persistence/replay/cursors/outcomes RAW Store = source de vérité durable du backlog notification after commit = wake-up non durable, distinct d'un event réseau worker/job = policy, range, batch, progression, retries opérationnels ``` ### 3.3 Fondation Interface stable `0.2.13` Lire intégralement : ```text docs/plans/020-V0_2_13_INTERFACE_PLAN.md docs/validation/016-V0_2_13_INTERFACE.md crates/ksp-interface-lib/Cargo.toml crates/ksp-interface-lib/README.md crates/ksp-interface-lib/USAGE.md crates/ksp-interface-lib/src/** crates/ksp-interface-lib/tests/** ``` La base stable possède une petite surface passive Program-facing : ```text Pubkey ProgramAccountMeta ProgramInstruction MAX_PROGRAM_INSTRUCTION_ACCOUNTS MAX_PROGRAM_INSTRUCTION_DATA_LEN ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED ``` Le graphe normal attendu reste actuellement : ```text ksp-interface-lib └── ksp-core-lib ``` `0.3.5` peut élargir la responsabilité documentaire de la crate aux événements passifs d'acquisition retenus, mais ne doit pas transformer Interface en transport, en façade Store ou en runtime. ### 3.4 Contrats RAW/ownership stabilisés `0.3.1` Lire : ```text docs/plans/022-V0_3_1_STORE_RAW_PLAN.md docs/validation/018-V0_3_1_STORE_RAW.md crates/ksp-store-api/Cargo.toml crates/ksp-store-api/src/** crates/ksp-store-api/tests/** ``` Relire particulièrement les décisions : ```text persistent/replayable -> ksp-store-api event-only partagé -> ksp-interface-lib préférentiel RawTransaction + RawTransactionObservation restent Store API RawAccountState + RawAccountObservation restent Store API logsSubscribe n'a pas créé RawLog persistant TransactionStatusObservation a été reporté faute de convergence slot/root/slotsUpdates/vote sont des candidats event-only à réauditer wake-up « persisted data available » est distinct des events réseau ``` Ne pas déplacer ni recopier les types Store pour rendre Interface plus pratique. ### 3.5 Store/PostgreSQL stable `0.3.2`–`0.3.4` Lire au minimum : ```text docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md crates/ksp-store-lib/README.md crates/ksp-store-lib/USAGE.md crates/ksp-store-postgres-lib/README.md crates/ksp-store-postgres-lib/USAGE.md ``` L'objectif n'est pas d'auditer de nouveau SQL/migrations, mais de préserver la frontière désormais stable : ```text 10 capabilities RAW persistantes 6 RawTransaction* 4 RawAccount* aucune capability de rétention account aucun event réseau persistant ajouté par défaut ``` ### 3.6 Surfaces Transport à auditer Lire les contrats publics et les tests associés de `ksp-onchain-transport-lib`, en particulier : ```text crates/ksp-onchain-transport-lib/src/ws_transactions.rs crates/ksp-onchain-transport-lib/src/ws_cluster.rs crates/ksp-onchain-transport-lib/src/ws_accounts.rs crates/ksp-onchain-transport-lib/src/ws_blocks.rs crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs crates/ksp-onchain-transport-lib/src/grpc_subscribe.rs crates/ksp-onchain-transport-lib/src/grpc_stream.rs crates/ksp-onchain-transport-lib/src/rpc_transactions.rs crates/ksp-onchain-transport-lib/src/rpc_blocks.rs crates/ksp-onchain-transport-lib/tests/** ``` Inventorier au minimum : ```text standard WS signatureNotification standard WS logsNotification standard WS slotNotification standard WS rootNotification standard WS slotsUpdatesNotification standard WS voteNotification standard WS account/program notifications standard WS blockNotification Helius transaction notifications Yellowstone Account Yellowstone Slot Yellowstone Transaction Yellowstone TransactionStatus Yellowstone Block / BlockMeta Yellowstone Entry HTTP getSignatureStatuses / getTransaction / getBlock surfaces pertinentes ``` Les DTOs ci-dessus sont **Transport-owned**. Ils sont des inputs d'audit, pas des types à réexporter depuis Interface. Lire enfin : ```text CHANGELOG.md ROADMAP.md ``` Créer en `pre.001` : ```text docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md ``` --- ## 4. Archive historique kbot3 L'archive historique kbot3 **n'est pas requise** pour `0.3.5`. Raison : la décision à prendre dépend des sémantiques **actuelles** déjà matérialisées dans KSP et des contrats officiels actuels HTTP/WS/Yellowstone. Une ancienne hiérarchie d'events ne doit pas devenir une autorité par inertie. Donc : ```text ne pas bloquer pre.001 sur khadhroony-bot3_v0.5.3-pre.005-fix010.zip ne pas inventer un audit historique obligatoire ne pas recopier une ancienne Event enum si elle est retrouvée ``` Si l'opérateur fournit volontairement une archive historique, elle peut être consultée **après** l'inventaire KSP actuel comme source comparative non normative, sans modifier les critères d'admission. --- ## 5. Sources externes normatives à réauditer lorsque la fraîcheur importe Cette release dépend davantage de la **sémantique** des notifications que de nouvelles dépendances Cargo. Lorsque `pre.001` compare des surfaces, vérifier les sources primaires réellement actuelles pour les opérations concernées : ```text Solana JSON-RPC HTTP Solana WebSocket subscriptions Yellowstone gRPC / geyser proto actuel utilisé par KSP Helius LaserStream WebSocket seulement pour ses extensions déjà implémentées ``` Comparer la documentation externe avec les types/tests effectivement présents dans `ksp-onchain-transport-lib`. Si une différence apparaît : ```text ne pas modifier Transport dans 0.3.5 par réflexe identifier d'abord s'il s'agit d'un bug Transport bloquant ou d'une évolution externe si correction Transport nécessaire, la traiter dans une tranche/release propriétaire adaptée ne pas masquer la divergence en élargissant le modèle Interface ``` Aucun SDK provider n'est ajouté pour cette release. Aucun codec wire (`borsh`, `wincode`, etc.) n'est ajouté uniquement pour représenter un événement passif. `bincode` reste interdit pour les codecs wire KSP. --- ## 6. Ownership à figer avant tout nouveau type Pour chaque candidat, `pre.001` doit choisir exactement une catégorie principale. ### 6.1 Store API Un fait appartient à `ksp-store-api` lorsqu'il est : ```text persistant replayable durablement queryable partie du backlog ou de l'identité RAW ``` Exemples déjà acquis : ```text RawTransaction RawTransactionObservation RawAccountState RawAccountObservation RawPageCursor / queries / outcomes ``` `0.3.5` ne duplique pas ces modèles sous un nom `Event`. ### 6.2 Transport Un fait reste Transport lorsqu'il dépend encore : ```text d'une méthode HTTP/WS/gRPC spécifique d'un lifecycle de subscription/session d'un filter echo provider d'un format d'erreur provider d'un payload raw/serde_json forward-compatible d'un détail Yellowstone/Helius non transversal ``` Un type `SolanaLogsNotification`, `YellowstoneSlotUpdate` ou `HeliusTransactionNotification` ne devient pas Interface simplement parce qu'il est public. ### 6.3 Interface Un événement est candidat Interface lorsque : ```text il est passif il n'est pas destiné à devenir une seconde persistence RAW sa sémantique peut être exprimée sans nom/méthode/provider de transport au moins deux producteurs/converters ou consumers peuvent raisonnablement partager exactement ce contrat la conversion ne perd pas une distinction sémantique importante les champs communs ne sont pas un Option-soup construit par union artificielle ``` ### 6.4 Composition/pipeline futur Une transformation qui nécessite : ```text state de session provenance endpoint/provider agrégation de plusieurs messages lookup HTTP supplémentaire conversion vers RawTransaction/RawAccountState policy de retry/batch/range ``` appartient à une couche de composition/pipeline/worker/job future, pas à la structure passive Interface. --- ## 7. Matrice de candidats obligatoire `pre.001` doit produire une matrice par **nature de fait**, pas par nom de méthode. ### 7.1 Slot / root / lifecycle Comparer au minimum : ```text WS slotNotification WS rootNotification WS slotsUpdatesNotification Yellowstone Slot update ``` Auditer : ```text slot parent root status/lifecycle processed/confirmed/finalized first shred/completed/created bank/dead server timestamp unknown variants dead error ``` Ne pas supposer que `root == finalized`, que `slotNotification` et `slotsUpdates` sont équivalents, ni que tous les statuts Yellowstone possèdent un équivalent WebSocket. Une abstraction peut être plus petite que l'union des surfaces si cette petite sémantique est réellement utile et lossless pour le consumer visé. ### 7.2 Logs realtime Comparer : ```text WS logsNotification transaction logMessages présents dans les transactions complètes Yellowstone Transaction meta/log messages lorsque disponibles ``` Préserver la décision déjà acquise : ```text logMessages d'une transaction persistée restent dans RawTransaction/STRUCTURAL futur logsSubscribe peut être un event-only séparé aucune table RawLog par défaut ``` Décider si un event passif de logs possède un vrai consumer distinct du pipeline de transaction complète. Ne pas faire entrer `serde_json::Value` provider comme erreur canonique Interface sans justification forte. ### 7.3 Transaction status Comparer : ```text HTTP getSignatureStatuses snapshot WS signatureNotification one-shot/transition Yellowstone TransactionStatus update Helius transaction status/notification si réellement applicable ``` La décision `0.3.1` est **REPORTÉ** faute de convergence. `0.3.5` ne l'annule que si l'audit démontre une nature de fait commune sans perte. Ne pas créer : ```text TransactionStatusEvent avec une dizaine d'Option pour couvrir toutes les sources champ status qui mélange received/processed/confirmed/finalized arbitrairement opaque provider error promue telle quelle ``` ### 7.4 Vote Comparer : ```text WS voteNotification Yellowstone transactions de vote / filtres is_vote autres surfaces réellement disponibles ``` Une transaction marquée `is_vote=true` n'est pas automatiquement équivalente au contenu sémantique d'un `voteNotification` gossip. ### 7.5 Account / program Les notifications account/program peuvent alimenter `RawAccountState`, mais `0.3.5` ne doit pas créer un doublon Interface de : ```text RawAccountState RawAccountStateReference RawAccountObservation ``` Un contrat event-only distinct n'est recevable que si un consumer a besoin d'une sémantique non persistante réellement différente. ### 7.6 Transaction complète / block Les notifications transaction/block servent déjà d'acquisition potentielle de `RawTransaction`. Ne pas créer par réflexe : ```text InterfaceRawTransaction TransactionEvent contenant une copie de RawTransaction RawBlock parallèle ``` `RawBlock` reste conditionnel selon le roadmap. ### 7.7 Yellowstone Entry La décision actuelle reste : ```text REJET ACTUEL ``` Ne rouvrir que si `pre.001` identifie un consumer réel et une destination sémantique claire. La simple disponibilité du proto n'est pas un besoin KSP. ### 7.8 Notification after commit Le wake-up : ```text persist commit notify ``` est **distinct** des événements réseau. Son format canonique appartient conceptuellement au domaine Store/API selon `KSP-NOTIFY-*`, mais ne doit pas être matérialisé dans `0.3.5` sans publisher + consumer réel. Ne pas l'ajouter à Interface pour « avoir un event générique ». --- ## 8. Contrat de design des types Interface retenus Pour chaque type admis par `pre.001` : ### 8.1 KSP-owned et provider-neutral Le nom/type public ne doit pas contenir : ```text Yellowstone Helius Rpc WebSocket Grpc provider name subscription id endpoint id ``` sauf si le type décrit explicitement un wire protocolaire possédé par Interface, ce qui n'est pas l'objectif par défaut de cette release. ### 8.2 Champs privés et API explicite Préférer : ```text private fields constructeur(s) validants si admission nécessaire accessors explicites #[must_use] approprié ``` Les enums publiques évolutives sont `#[non_exhaustive]` lorsque l'ajout de variantes futures est un scénario normal. ### 8.3 Pas d'Option-soup Si deux producers partagent seulement une petite intersection utile, modéliser cette intersection ou deux faits distincts. Ne pas créer une structure unique avec des champs optionnels simplement parce que « certains transports les ont ». ### 8.4 Bornes Toute donnée variable hostile doit être bornée si elle entre dans le contrat Interface : ```text Vec String opaque bytes liste de slots/logs error text éventuel ``` Les bornes sont des **admission guards Interface**, pas des affirmations de maxima protocolaire. ### 8.5 Debug et erreurs Le `Debug` public ne doit pas dumper : ```text logs arbitraires complets opaque error payloads raw JSON payloads provider listes pathologiques ``` Les erreurs utilisent les types Core et des codes/contexte sûrs. Ne jamais recopier le payload hostile dans `message` ou `context`. ### 8.6 Clone/Copy Ne dériver `Copy` que pour les petits contrats réellement copiables. Ne pas dériver `Clone` sur un événement volumineux simplement par habitude si cela encourage des duplications de payloads importants. ### 8.7 Sérialisation/codecs Par défaut : ```text serde absent serde_json absent borsh absent wincode absent bincode interdit ``` N'ajouter un codec/serde que si un **consumer concret de cette release** exige un format public et que l'ownership Interface est démontré. ### 8.8 Logging Des modèles passifs n'ont pas besoin de logging runtime. Donc, par défaut : ```text ksp-logging-lib absent constants.rs absent TRACING_TARGET absent ``` Si un comportement runtime est introduit, réauditer d'abord l'ownership : il est probablement hors scope Interface. --- ## 9. Dépendances et frontières interdites La cible préférée reste : ```text ksp-interface-lib └── ksp-core-lib ``` Toute nouvelle dépendance normale doit être justifiée par `pre.001`. Interdictions de release : ```text ksp-interface-lib -> ksp-onchain-transport-lib ksp-interface-lib -> ksp-store-api ksp-interface-lib -> ksp-store-lib ksp-interface-lib -> ksp-config-lib ksp-interface-lib -> ksp-program-api ksp-interface-lib -> ksp-wallet-lib ksp-interface-lib -> Tauri ``` `ksp-onchain-transport-lib` n'est pas modifié uniquement pour adopter les nouveaux types. Les conversions vers Interface appartiendront au consumer/composition owner lorsque celui-ci est matérialisé, sauf décision architecturale explicitement réauditée dans une release propriétaire. Aucune `ksp-interface-api` séparée n'est créée sans contrainte de graphe réelle. --- ## 10. Décisions acquises et questions réellement ouvertes ### 10.1 Acquis ```text Interface possède les contrats passifs/wire réellement partagés Store API possède les modèles persistants/replayables Transport possède ses DTOs protocol/provider et lifecycle réseau pas de RawLog Store par défaut TransactionStatusObservation reste différé tant que les sémantiques divergent slot/root/slotsUpdates/vote restent candidats, pas engagements wake-up post-commit != event réseau pas de codec générique par anticipation pas de bincode wire pas de runtime logging dans un modèle passif ``` ### 10.2 À décider dans `pre.001` Décider explicitement : ```text quels consumers concrets justifient 0.3.5 quelles natures de fait ont >= 2 surfaces réellement convergentes quels candidats restent Transport-only quels candidats restent reportés quels types exacts Interface créer noms exacts sans provider/protocol leakage champs exacts et optionality bornes d'admission Debug/error policy Clone/Copy policy besoin réel ou absence de serde/codec inventaire crate-root final si README Interface doit élargir sa description Program-only si une architecture durable contient une formulation devenue fausse ``` Si aucun candidat ne franchit le gate, ne pas fabriquer une API vide ou artificielle pour respecter le numéro de release : documenter le résultat, recalibrer la release et préserver la trajectoire. --- ## 11. Threat model obligatoire Couvrir au minimum : ```text union artificielle de sémantiques différentes perte d'un état important lors d'une conversion Option-soup rendant une source indiscernable provider/protocol leakage dans une API transversale duplication de RawTransaction/RawAccountState promotion d'un snapshot HTTP en event de transition confusion root/finalized/confirmed/processed confusion vote gossip / transaction de vote raw JSON ou error text hostile dans Interface log/event non borné Debug volumineux ou sensible derive Clone pathologique sur gros payload unknown future variant traité comme sémantique connue ajout d'un codec sans consumer nouvelle dépendance Transport/Store inverse création d'un event bus ou scheduler dans Interface wake-up post-commit confondu avec event réseau API fermée impossible à faire évoluer ``` --- ## 12. Première mission `pre.001` ### 12.1 Vérifier la base Avant toute modification fonctionnelle : 1. vérifier `v0.3.4` stable et `workspace.package.version = 0.3.4` ; 2. lire les règles/architectures listées ci-dessus ; 3. confirmer la surface publique et le graphe actuel de `ksp-interface-lib` ; 4. confirmer la surface RAW Store stable 10/10 ; 5. inventorier toutes les surfaces event-like Transport actuelles ; 6. identifier les consumers actuels et les consumers RAW imminents déjà prévus par l'architecture ; 7. ne pas attendre une archive kbot3. ### 12.2 Matrice producer -> nature de fait Pour chaque surface : ```text producer/protocol méthode/update nature du fait champs obligatoires champs optionnels ordre/lifecycle timestamp semantics error semantics filter/session/provider metadata payload volumineux éventuel persistant/replayable ou event-only ``` ### 12.3 Matrice de convergence Pour chaque nature de fait candidate : ```text sources comparées intersection sémantique exacte différences non représentables conversion lossless possible ? consumer concret owner retenu Interface candidate / Transport-only / Store / Reporté / Rejeté ``` ### 12.4 Matrice anti-duplication Store Comparer tout type candidat avec : ```text RawTransaction* RawAccount* RawAcquisitionProvenance RawTimestamp RawContentHash RawObservationKey ``` Démontrer qu'un nouveau contrat Interface ne crée pas une deuxième vérité persistante. ### 12.5 API sketch Pour chaque candidat admis, proposer avant code : ```text nom public struct/enum champs privés constructeur/accessors bounds Debug Clone/Copy non_exhaustive error code éventuel ``` ### 12.6 Graphe Produire le graphe normal visé de `ksp-interface-lib` et justifier toute différence avec Core-only. ### 12.7 Threat model Produire la matrice de la section 11 avec mitigation/gate associé. ### 12.8 Sizing Chaque tranche prévue au-delà d'environ **15 à 20 minutes de travail effectif** doit être scindée. Si plusieurs familles d'events sont admises, les séparer par responsabilité au lieu de créer une grosse tranche « events ». Ne jamais aspirer `0.3.6` Job API/backfill dans `0.3.5`. ### 12.9 Documents de gate Créer : ```text docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md ``` ### 12.10 Critères de sortie de `pre.001` `pre.001` est terminé seulement si : ```text base v0.3.4 vérifiée règles/architecture relues surface Interface actuelle inventoriée surface Store 10/10 confirmée et protégée surfaces HTTP/WS/Yellowstone/Helius pertinentes inventoriées consumers concrets/imminents identifiés matrice producer -> nature de fait produite matrice de convergence produite ownership de chaque candidat décidé candidats reportés/rejetés explicités anti-duplication Store démontrée API sketch des seuls types retenus produit bounds/Debug/Clone/non_exhaustive décidés graphe cible décidé threat model complet plan 026 créé validation 022 créée prévision souple recalibrée aucune grosse Event enum ni dépendance runtime ajoutée prématurément ``` --- ## 13. Prévision souple initiale des prereleases Cette prévision est volontairement conditionnelle au nombre réel de familles admises par `pre.001`. ### `pre.001` — Audit consumers, sémantiques et ownership Lectures, inventaire Transport/Store/Interface, matrice de convergence, threat model, API sketch, sizing, plan/validation. ### `pre.002` — Première famille passive retenue Implémenter la première nature de fait réellement admise, avec types KSP-owned, bounds, `Debug`, tests unitaires et crate-root minimal. Si aucun candidat n'est admis, recalibrer au lieu d'inventer ce lot. ### `pre.003` — Famille passive supplémentaire si justifiée Ajouter uniquement une seconde famille dont la convergence et le consumer sont déjà prouvés. Si plusieurs familles dépassent le budget, insérer autant de tranches bornées que nécessaire. Si aucune seconde famille n'est justifiée, cette responsabilité est omise/décalée sans remplissage artificiel. ### `pre.004` — Surface publique, consumer externe et anti-duplication Verrouiller exports/modules, consumabilité depuis une crate externe, enums évolutives, absence de Store/Transport leakage et canaris contre la duplication des modèles persistants. ### `pre.005` — Hardening/completeness Interface Hostile inputs/bounds/Debug, dépendances exactes, absence de serde/codec/logging/runtime non justifiés, inventaire des candidats reportés et non-régression Program instruction foundation. ### `pre.006` — Gate technique final ```text cargo fmt/audits cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-interface-lib cargo test --workspace cargo tree -p ksp-interface-lib --edges normal cargo tree -p ksp-interface-lib -e features cargo tree --duplicates ``` Aucun smoke réseau n'est requis par défaut puisque `0.3.5` ne modifie pas le moteur Transport. Si `pre.001` démontre qu'un live est indispensable pour établir une sémantique, créer un gate technique séparé avant la réconciliation documentaire. ### `pre.007` — Réconciliation documentaire finale README/USAGE Interface, plan `026`, validation `022` et architecture/références réellement devenues fausses. `USAGE.md` reste version-neutre. Ne pas toucher `CHANGELOG.md`, `ROADMAP.md` ni au prompt suivant. ### `pre.008` — Préparation de publication minimale Uniquement : ```text Cargo.toml CHANGELOG.md ROADMAP.md prompts/025-V0_3_6_START_PROMPT.md deltas/0.3.5/pre.008.md ``` Le numéro réel peut dériver si `pre.001` insère/retire des lots ; les responsabilités de fermeture restent dans cet ordre. ### `rel.001` — Publication stable Version finale + delta uniquement. --- ## 14. Versionnement, deltas, commits et tags Respecter `docs/rules/VERSION_WORKFLOW.md`. Rappels : ```text workspace.package.version prerelease : 0.3.5-pre.N livraison : 0.3.5-pre.NNN fix code/runtime/config : Cargo 0.3.5-pre.N.fix.M fix strictement documentaire : Cargo inchangé prerelease non-fix documentaire/publication : Cargo synchronisé chaque delta commité tag stable final : v0.3.5 ``` Chaque delta contient au minimum : ```text base requise objectif fichiers ajoutés fichiers modifiés fichiers supprimés validations exécutées validations non exécutées décisions questions ouvertes ``` Une commande non exécutée n'est jamais déclarée PASS. --- ## 15. Procédure d'application et validation opérateur Après chaque overlay : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.5 cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-interface-lib ``` Lorsque la surface publique change : ```bash cargo test -p ksp-program-api ``` pour vérifier la non-régression du consumer Program existant, sans obliger Program API à utiliser les nouveaux events. Au gate technique final : ```bash cargo test --workspace cargo tree -p ksp-interface-lib --edges normal cargo tree -p ksp-interface-lib -e features cargo tree --duplicates ``` Ne pas ajouter de build Tauri ou de smoke réseau sans changement correspondant réellement à leur responsabilité. --- ## 16. Critères de clôture de `0.3.5` La release stable est prête seulement si : ```text les types ajoutés correspondent à des faits réellement partagés chaque candidat refusé/reporté reste documenté aucun modèle persistent/replayable Store n'est dupliqué aucun DTO provider/Transport n'est réexporté ksp-interface-lib ne dépend ni de Transport ni de Store le graphe de dépendances reste minimal et justifié aucun event bus/scheduler/runtime n'est introduit aucun codec/serde/logging n'est ajouté sans consumer réel les types variables sont bornés Debug/errors restent sûrs et bornés les enums publiques évolutives sont ouvertes de manière appropriée la foundation ProgramInstruction reste non régressée une crate externe peut consommer les nouveaux contrats depuis le crate-root workspace/Clippy/tests/graphes sont verts README/USAGE/plan/validation sont réconciliés selon leur rôle prompt 0.3.6 est prêt ``` Il n'existe **aucun quota minimal d'events à créer**. La qualité de la frontière prime sur le nombre de types. --- ## 17. Hors périmètre explicite Ne pas ouvrir dans `0.3.5` : ```text modification fonctionnelle de ksp-onchain-transport-lib nouvelle persistence Store nouvelle migration PostgreSQL RawLog table RawBlock sans besoin démontré RawTransaction / RawAccountState bis dans Interface notification bus/runtime PostgreSQL LISTEN/NOTIFY Redis/Kafka/NATS ksp-worker-api worker RAW live ksp-job-api backfill 0.3.6 Store Desk / app backfill 0.3.7 STRUCTURAL persistence Program decoder/materializer execution provider SDK codec wire générique ``` --- ## 18. Release suivante et instruction d'ouverture La release suivante envisagée est : ```text 0.3.6 — Job API + premier backfill historique RAW ``` ### Instruction d'ouverture À réception de la base stable `v0.3.4` : 1. vérifier la base exacte et le graphe actuel de `ksp-interface-lib` ; 2. lire règles, architecture, foundation Interface et décisions Store RAW `0.3.1`–`0.3.4` ; 3. inventorier les surfaces event-like actuelles de `ksp-onchain-transport-lib` ; 4. réauditer les docs officielles HTTP/WS/Yellowstone uniquement pour les candidats réellement comparés ; 5. identifier les consumers et produire les matrices producer/nature de fait/convergence/ownership ; 6. préserver `RawTransaction`/`RawAccountState` comme vérité persistante Store API ; 7. figer seulement les types passifs Interface dont la sémantique et l'usage sont démontrés ; 8. produire threat model, sizing, plan `026` et validation `022` ; 9. **ne pas attendre l'archive kbot3 : elle n'est pas requise pour cette release** ; 10. **ne pas commencer Job API/backfill, worker live, Store notifications ou modifications Transport avant la clôture cohérente de `0.3.5-pre.001`**.