31 KiB
Prompt de démarrage 0.3.5 — Interface passive acquisition events
1. Identité de la release et base exacte requise
La release à ouvrir est :
0.3.5 — ksp-interface-lib : modèles passifs/event-only réellement partagés
La base autoritaire attendue est exclusivement la release stable :
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 :
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 :
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 :
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 :
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 :
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 :
KSP-API-*
KSP-TRANSPORT-*
KSP-STORE-*
KSP-NOTIFY-*
KSP-PROC-*
KSP-REL-*
DEP-KSP-*
DEP-LOG-*
DEP-STORE-*
DEP-WORKER-*
DEP-JOB-*
Rappels structurants :
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 :
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 :
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 :
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 :
Pubkey
ProgramAccountMeta
ProgramInstruction
MAX_PROGRAM_INSTRUCTION_ACCOUNTS
MAX_PROGRAM_INSTRUCTION_DATA_LEN
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED
Le graphe normal attendu reste actuellement :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
CHANGELOG.md
ROADMAP.md
Créer en pre.001 :
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 :
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 :
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 :
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 :
persistant
replayable
durablement queryable
partie du backlog ou de l'identité RAW
Exemples déjà acquis :
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 :
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 :
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 :
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 :
WS slotNotification
WS rootNotification
WS slotsUpdatesNotification
Yellowstone Slot update
Auditer :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
ksp-interface-lib
└── ksp-core-lib
Toute nouvelle dépendance normale doit être justifiée par pre.001.
Interdictions de release :
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
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 :
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 :
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 :
- vérifier
v0.3.4stable etworkspace.package.version = 0.3.4; - lire les règles/architectures listées ci-dessus ;
- confirmer la surface publique et le graphe actuel de
ksp-interface-lib; - confirmer la surface RAW Store stable 10/10 ;
- inventorier toutes les surfaces event-like Transport actuelles ;
- identifier les consumers actuels et les consumers RAW imminents déjà prévus par l'architecture ;
- ne pas attendre une archive kbot3.
12.2 Matrice producer -> nature de fait
Pour chaque surface :
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 :
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 :
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 :
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 :
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 :
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
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
0.3.6 — Job API + premier backfill historique RAW
Instruction d'ouverture
À réception de la base stable v0.3.4 :
- vérifier la base exacte et le graphe actuel de
ksp-interface-lib; - lire règles, architecture, foundation Interface et décisions Store RAW
0.3.1–0.3.4; - inventorier les surfaces event-like actuelles de
ksp-onchain-transport-lib; - réauditer les docs officielles HTTP/WS/Yellowstone uniquement pour les candidats réellement comparés ;
- identifier les consumers et produire les matrices producer/nature de fait/convergence/ownership ;
- préserver
RawTransaction/RawAccountStatecomme vérité persistante Store API ; - figer seulement les types passifs Interface dont la sémantique et l'usage sont démontrés ;
- produire threat model, sizing, plan
026et validation022; - ne pas attendre l'archive kbot3 : elle n'est pas requise pour cette release ;
- 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.