khadhroony-solana-project/prompts/024-V0_3_5_START_PROMPT.md

<!-- file: prompts/024-V0_3_5_START_PROMPT.md -->
<!-- version: 1 -->

# 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`**.