Sasedev/khadhroony-solana-project

Fork 0

Files

SinuS Von SifriduS 8c8b7ee986 v0.2.13-pre.008

2026-08-28 08:50:19 +02:00

40 KiB

Raw Blame History

Prompt de démarrage `0.2.14` — Program API foundation

1. Identité de la release et bases exactes requises

La base KSP attendue est exclusivement la release stable :

v0.2.13

La release à ouvrir est :

0.2.14 — Program API foundation

La première tranche est :

0.2.14-pre.001

Deux archives sont requises au démarrage de la session :

1. archive opérateur correspondant exactement à KSP v0.2.13
2. archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip

Ordre d'autorité :

v0.2.13 réelle / archive opérateur   autorité KSP actuelle
règles + architecture de v0.2.13     autorité normative et architecturale
khadhroony-bot3 historique            source d'audit/héritage uniquement
anciens prompts / snippets / mémoire  auxiliaires seulement

L'archive kbot3 n'est pas facultative pour le gate pre.001 : cette release porte précisément le premier contrat Program extensible de KSP et doit confronter l'architecture actuelle aux anciens contrats de decoder/executor avant de figer une nouvelle API. Si l'archive historique n'est pas disponible, ne pas inventer son contenu depuis la mémoire et ne pas déclarer l'audit d'héritage terminé.

Ne pas ouvrir 0.2.14 depuis :

0.2.13-pre.*
0.2.13-pre.*-fix.*
0.2.13-rel.* non encore validé stable
une archive de travail intermédiaire
l'ancien dépôt khadhroony-bot3 comme base de code
un souvenir de session

Si une divergence existe entre le prompt et la base stable réelle, la base réelle gagne et la divergence devient une sortie explicite de l'audit pre.001.

À l'ouverture, vérifier au minimum :

tag Git v0.2.13 si metadata Git disponible
workspace.package.version = 0.2.13
deltas/0.2.13/rel.001.md présent
prompts/019-V0_2_14_START_PROMPT.md présent
ksp-interface-lib présent et conforme à la surface stable 0.2.13
ksp-program-api absent sauf contradiction de la base réelle
ksp-program-lib absent sauf contradiction de la base réelle
archive khadhroony-bot3_v0.5.3-pre.005-fix010.zip disponible pour l'audit historique

pre.001 est obligatoirement une tranche lecture + audit KSP actuel + audit kbot3 + brainstorming + frontières + threat/API model + dependency graph + stratégie d'extension externe + sizing + planification.

Aucun trait Program définitif, registry runtime, decoder concret ni execution preparer concret ne doit être implémenté avant la sortie cohérente de ce gate.

2. Mission et résultat attendu

La mission de 0.2.14 est d'introduire ksp-program-api comme premier contrat public extensible du domaine Program.

La crate est une crate *-api au sens KSP :

contrats publics
traits/capabilities/descriptors
surface implémentable depuis une crate externe
pas d'implémentation officielle de protocoles
pas de runtime réseau
pas de persistence
pas de policy produit

La release doit réaliser la frontière :

ksp-interface-lib
    = wire passif officiel

ksp-program-api
    = comportement Program ouvert / extensible

ksp-program-lib
    = implémentations officielles futures, hors 0.2.14

Le résultat attendu à la clôture, sous réserve du sizing et des décisions de pre.001, est une foundation suffisamment petite pour être stable et suffisamment réelle pour qu'une crate externe puisse démontrer une implémentation Program sans modifier une enum centrale KSP.

Les contrats candidats à auditer sont notamment :

identité d'implémentation Program
capabilities déclarées
reconnaissance déterministe d'une instruction
contrat de decoder instruction
statuts/outcomes/diagnostics minimaux
descriptor de couverture ou surface supportée
registry/composition extensible si une API commune est réellement nécessaire
ProgramExecutionPreparer et PreparedProgramExecution uniquement si le sizing démontre que leur foundation appartient déjà à 0.2.14

La release ne doit pas résoudre artificiellement les contrats qui appartiennent à des couches encore absentes, notamment le replay CORE complet, la persistence D3, les materializers, la policy d'exécution ou l'orchestration transactionnelle.

La question centrale de 0.2.14 est :

quel est le plus petit contrat Program public, ouvert et objectivement réutilisable qui permet de séparer reconnaissance/décodage/préparation du wire Interface, sans recréer les modèles CORE/Store/Execution avant leurs releases ?

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 :

KSP-NAME-002..003
KSP-API-001..007
KSP-PROGRAM-001..006
DEP-LOG-005
DEP-PROGRAM-001..004
DEP-WIRE-001..007
DEP-PIPE-007..008
DEP-SOL-001..006
DEP-PROTO-001..005
DEP-CARGO-001..007

Rappels directement structurants :

ksp-program-api porte volontairement le suffixe -api et non -lib
une crate *-api est principalement déclarative
une API publique extensible doit être implémentable depuis une crate séparée
les signatures publiques utilisent des types KSP publics stables
pas de pub mod comme raccourci de façade
surface publique réexportée explicitement depuis crate root
Error/Result communs restent possédés par ksp-core-lib
les crates *-api purement déclaratives n'ajoutent pas de logging sans comportement réel

Pour tout Rust modifié :

cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets

Pour tout Markdown touché :

python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.14

Une commande non exécutée n'est jamais déclarée PASS.

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/007-EXECUTION_AND_POLICY.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

docs/architecture/006-WIRE_AND_PROGRAM.md est la référence centrale de la release.

Préserver notamment :

ksp-interface-lib = wire officiel, passif
ksp-program-api = contrats publics ouverts
ksp-program-lib = implémentations officielles ultérieures
extension externe ksp-program-<name>-lib possible sans dépendre de ksp-program-lib
pas d'enum fermée de tous les programmes
pas de Any runtime comme unique représentation de résultat
familles de decoder séparables par capability
ProgramInstructionDecoder / ProgramAccountDecoder = besoins fondamentaux probables, pas obligation de les matérialiser tous sans input réel
ProgramEventDecoder / ProgramReturnDataDecoder = seulement au premier besoin réel
ProgramExecutionPreparer = préparation technique, jamais exécution transactionnelle complète
RAW -> CORE -X-> Program
CORE -> DECODE = première frontière Program future

3.3 Clôture stable `0.2.13`

Relire :

CHANGELOG.md
ROADMAP.md

docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/020-V0_2_13_INTERFACE_PLAN.md
docs/validation/016-V0_2_13_INTERFACE.md

crates/ksp-interface-lib/README.md
crates/ksp-interface-lib/USAGE.md

deltas/0.2.13/rel.001.md

La surface Interface acquise est une contrainte d'entrée de 0.2.14 et ne doit pas être redessinée par commodité.

3.4 Code KSP réel à inventorier avant design

Inventorier au minimum :

Cargo.toml
crates/ksp-core-lib/Cargo.toml
crates/ksp-core-lib/src/lib.rs
crates/ksp-core-lib/src/error.rs
crates/ksp-core-lib/src/program_ids.rs

crates/ksp-interface-lib/Cargo.toml
crates/ksp-interface-lib/src/lib.rs
crates/ksp-interface-lib/src/error.rs
crates/ksp-interface-lib/src/program_account_meta.rs
crates/ksp-interface-lib/src/program_instruction.rs
crates/ksp-interface-lib/tests/public_api.rs
crates/ksp-interface-lib/tests/dependency_boundary.rs
crates/ksp-interface-lib/tests/external_consumer.rs
crates/ksp-interface-lib/tests/release_completeness.rs

Ne pas supposer qu'un type de l'ancien bot doit être reconstruit s'il n'existe aucune frontière KSP actuelle qui le consomme.

4. Archive historique `khadhroony-bot3` — audit obligatoire

L'archive attendue est :

khadhroony-bot3_v0.5.3-pre.005-fix010.zip

Elle est une source historique contrôlée, jamais une base à extraire par-dessus KSP.

4.1 Fichiers kbot3 prioritaires

Auditer au minimum lorsqu'ils sont présents :

ks-lib/src/decoder/api/contracts.rs
ks-lib/src/decoder/api/decoder.rs
ks-lib/src/decoder/api.rs

ks-lib/src/model/decoded.rs
ks-lib/src/model/replay.rs
ks-lib/src/model/solana.rs

ks-lib/src/executor/api/execution.rs
ks-lib/src/executor/api/executor.rs
ks-lib/src/executor/api.rs

ks-lib/src/decoder/solana/core/decoder.rs
ks-lib/src/decoder/spl/token/decoder.rs
ks-lib/src/decoder/spl/token_2022/decoder.rs

ks-lib/src/lib.rs
ks-lib/Cargo.toml
ks-lib/README.md
ks-lib/USAGE.md

docs/OPERATION_NAMING_CONVENTION.md
docs/IDL_AUDIT.md
docs/IDL_TO_KB_LIB_NOMENCLATURE.md
docs/architecture/ARCHITECTURE.md
docs/architecture/CRATE_MAP.md
docs/architecture/PIPELINE_ARCHITECTURE.md

Le but n'est pas de tout lire uniformément : commencer par les contrats API/model, puis utiliser quelques decoders concrets uniquement pour comprendre comment ces contrats étaient réellement consommés.

4.2 Matrice d'héritage obligatoire

Toute idée significative issue de kbot3 doit être classée :

REPRENDRE
REDESSINER
REPORTER
REJETER

Exemples à confronter explicitement :

DcApiDecoderIdentity
DcApiDecoderSurface
DcApiDecoderCoverageDeclaration
DcApiDecoderRecognition
DcApiDecoderOutcomeStatus
DcApiDecoderDiagnostic
DcApiDecoderProof / ProofKind
DcApiInstructionDecoder
DcApiProtocolDecoder / support No-Maybe-Yes

ExApiExecutionRequest
ExApiExecutionCapability
ExApiPreparedExecutionPlan
ExApiInstructionExecutor

MdDecodedProtocolEvent
MdCoreInstructionReplayInput
MdProgramId / MdPubkey / MdInstructionPath

4.3 Héritage pressenti à vérifier, pas à appliquer aveuglément

Les idées suivantes peuvent être conservées conceptuellement si l'audit les confirme :

séparer identité, capability, reconnaissance et decode
résultat terminal explicite plutôt qu'une convention implicite
diagnostics structurés plutôt qu'une erreur tierce brute
capabilities déclarées par l'implémentation
support d'implémentations externes
reconnaissance indépendante d'une enum centrale de programmes
séparation decode / préparation d'exécution

Les éléments suivants doivent au minimum être redessinés avant toute reprise :

Program IDs / Pubkeys en String       -> types Core/Interface typés
serde/JSON par défaut                 -> seulement si une frontière actuelle l'exige
payload_json générique                -> ne pas figer sans modèle réel
executor                              -> ProgramExecutionPreparer si cette capability entre réellement dans 0.2.14
policy d'exécution mélangée au plan   -> couche ExecutionPolicy future
noms/version en String possédés partout -> contrats bornés et justifiés

Les éléments suivants sont présumés reportés tant qu'une frontière réelle ne les réclame pas :

signature transaction
slot/block_time comme input générique de decoder
instruction_path / parent CPI / stack_height
logs runtime
return data runtime
transaction_failed / transaction error
balance deltas
hash JSON déterministe du replay input
canonical transaction/replay model
payload persistable D3 complet
materialization
post-execution replay validation

Ils appartiennent aux futures couches acquisition/CORE/DECODE/Store/Materializer, pas à la foundation Program API isolée.

Les éléments suivants sont présumés rejetés :

monolithe ks-lib regroupant decoder/executor/materializer/model
répertoire racine géant decoder/ ou executor/ comme architecture officielle future
enum centrale fermée de programmes/protocoles
Any runtime comme seul output ouvert
generic JSON comme substitut à un contrat non conçu
Program ID textuel parallèle au Pubkey Core
dépendance Program API vers Transport/Store/Wallet/Tauri
policy/safety de produit dans Program API

Toute divergence à ces présomptions doit être justifiée dans le plan pre.001.

5. Sources externes à réauditer en `pre.001`

ksp-program-api est principalement un contrat KSP-owned ; aucune dépendance externe n'est requise par principe.

Toutefois, si le design proposé dépend d'un comportement Solana, d'une primitive, d'une crate officielle ou d'une contrainte Rust actuelle, vérifier les sources primaires au moment du gate.

À auditer seulement si pertinent :

documentation/source officielle Solana/Anza pour les semantics d'instruction réellement invoquées
API courante de solana-pubkey déjà possédée par Core
crate/interface officielle uniquement si elle est réellement nécessaire au contrat public
object safety / dyn compatibility Rust si un registry de trait objects est retenu

Pour toute nouvelle dépendance candidate :

version stable réellement courante
source/ownership
features réellement nécessaires
default-features
MSRV/edition si pertinent
graphe transitif
raison pour laquelle Core + Interface ne suffisent pas

Ne pas ajouter serde, serde_json, borsh, wincode, solana-instruction ou une crate protocolaire uniquement parce qu'ils existaient dans kbot3.

6. État validé à préserver depuis `v0.2.13`

6.1 Core

Error / ErrorCode / ErrorContext / Result possédés par ksp-core-lib
Pubkey canonique possédé/réexporté par Core
registry des Program IDs fondamentaux possédé par Core

Aucun wrapper ProgramId(String) parallèle ne doit être introduit dans Program API.

6.2 Interface

Surface stable attendue :

Pubkey
ProgramAccountMeta
ProgramInstruction
MAX_PROGRAM_INSTRUCTION_ACCOUNTS = 255
MAX_PROGRAM_INSTRUCTION_DATA_LEN = 10_240
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED

Propriétés :

ProgramInstruction passif
accounts ordonnés et doublons préservés
Program Pubkey opaque accepté
Debug borné
Error Core-owned
aucun serde/codec générique
aucun solana-instruction
aucun logging runtime

Graphe stable :

ksp-interface-lib
    -> ksp-core-lib
        -> solana-pubkey

0.2.14 ne doit pas modifier Interface uniquement pour faciliter un premier trait. Si une lacune Wire réelle est découverte, la traiter comme décision explicite et re-sizer la release ; ne pas absorber silencieusement une extension Interface importante dans Program API.

6.3 Autres crates

Les crates suivantes restent hors chantier :

ksp-onchain-transport-lib
ksp-offchain-transport-lib
ksp-wallet-lib
ksp-config-lib
ksp-app-*-desk

Frontières :

Program API -X-> Transport
Program API -X-> Store
Program API -X-> Wallet
Program API -X-> Materializer
Program API -X-> Tauri

6.4 Pipeline durable

RAW -> CORE -> DECODE -> SPECIALIZED

Avec :

RAW -> CORE -X-> ksp-program-api
CORE -> DECODE peut utiliser ksp-program-api plus tard

La foundation Program API peut préparer ce futur usage, mais ne crée pas le modèle CORE manquant.

7. Décisions acquises — ne pas redébattre sans contradiction réelle

la crate cible se nomme ksp-program-api ;
le suffixe -api est volontaire et conforme à KSP-NAME-002 ;
ksp-program-api contient les contrats, pas les implémentations officielles ;
ksp-program-lib reste hors de 0.2.14 ;
une implémentation externe doit pouvoir dépendre directement de ksp-program-api ;
un nouveau Program ID externe ne doit pas nécessiter la modification d'une enum centrale KSP ;
ksp-program-api peut dépendre de Core et d'Interface si leurs types sont réellement utilisés ;
ksp-program-api ne dépend pas de Transport/Store/Wallet/Materializer ;
les Program IDs fondamentaux et Pubkey restent Core-owned ;
le wire reste Interface-owned ;
les codecs wire restent hors Program API ;
le decoder vise aussi les surfaces historiques distinguables ;
deprecated concerne la capability d'exécution, pas la capacité de décodage ;
ProgramExecutor est abandonné au profit du concept ProgramExecutionPreparer pour la préparation pure ;
la policy/safety, signature, blockhash, simulation, envoi, confirmation et retry réseau ne sont pas Program API ;
les modèles acquisition/replay/CORE complets ne sont pas créés dans 0.2.14 ;
kbot3 est une source historique, jamais une autorité architecturale ;
une crate *-api purement déclarative n'ajoute pas de logging sans comportement réel ;
aucun ksp-api-lib ou ksp-interface-api n'est créé par symétrie ;
la release doit rester clôturable dans une seule session et être réduite si le sizing l'exige.

8. Questions réellement ouvertes à trancher pendant `pre.001`

8.1 Capability initiale minimale

Décider si la foundation stable contient :

instruction decoder seulement
instruction decoder + descriptors/capabilities
instruction + account decoder si un input account public réel est démontré
instruction decoder + execution preparation foundation
autre combinaison plus petite justifiée par l'architecture

Ne pas créer ProgramAccountDecoder si aucune forme d'input account stable n'existe encore et que sa définition imposerait d'anticiper CORE.

8.2 Input de decoder instruction

Le candidat naturel est le contrat Interface existant :

&ksp_interface_lib::ProgramInstruction

Auditer s'il suffit à la première capability.

Ne pas ajouter automatiquement :

signature
slot
instruction path
CPI ancestry
logs
return data
balance deltas
transaction error

Ces données ne font pas partie de ProgramInstruction et appartiennent à un futur contexte CORE/acquisition.

8.3 Reconnaissance

Déterminer la forme minimale et déterministe :

bool
No / Maybe / Yes
compatible + exact
priority
recognized entry code/discriminant

Éviter un modèle plus riche que les besoins réels du dispatch futur.

8.4 Identité et descriptors

Décider :

identité d'implémentation statique ou value object
version d'implémentation nécessaire maintenant ou reportée
Program IDs déclarés via Pubkey typé
capabilities déclarées
surface/coverage machine-readable réellement utile
priorité/conflit entre implémentations nécessaire maintenant ou reporté

Aucun String non borné n'est ajouté par réflexe.

8.5 Outcome de decode

Auditer les statuts historiques kbot3 :

Decoded
Ignored
Unsupported
Failed

Décider lesquels ont un sens dans une API sans payload canonique D3 encore stabilisé.

Ne pas confondre :

recognition = ce decoder peut-il identifier cette entrée ?
decode outcome = que s'est-il passé après sélection ?
KSP Error = défaut de contrat/validation de l'appel

8.6 Payload décodé ouvert

C'est une question critique.

L'architecture exige à terme un résultat :

auto-identifiable
extensible
persistable lorsque la frontière Core/Store l'exige
consommable par materializers externes

Mais 0.2.14 ne doit pas inventer D3 avant Store/Materializer.

Comparer explicitement :

enum centrale fermée                         REJET présumé
Any uniquement                               REJET présumé
serde_json::Value générique                  REJET par défaut
trait avec associated output                 à auditer pour composition hétérogène
payload bytes + media/schema identity        à auditer sans anticiper persistence
pas de payload canonique dans la foundation  option valide si le contrat decoder peut rester utile autrement

Si aucune représentation satisfaisante n'est justifiable maintenant, reporter la sortie canonique complète plutôt que figer un mauvais contrat public.

8.7 Proof / confidence

L'ancien bot mélangeait :

ExactDiscriminator
ExactLayout
Idl
Manual
LogCorrelation
BalanceDelta
Heuristic
Audit

Distinguer :

preuves purement instruction-locales
preuves dépendant de logs/balance/CPI/context CORE
metadata d'audit humaine
confidence heuristic

Les preuves contextuelles ne doivent pas entrer dans 0.2.14 sans input contextuel réel.

8.8 Diagnostics et erreurs

Décider si un diagnostic Program API dédié apporte déjà une valeur réelle ou si ksp_core_lib::Error/Result suffit à la foundation.

Contraintes :

aucun payload hostile dans Error/Debug
pas d'erreur tierce brute publique
pas de duplication du Core Error model
codes machine-readable seulement s'ils représentent un état Program réel

8.9 `Send + Sync`, object safety et dyn dispatch

Si le registry futur doit composer plusieurs implémentations inconnues à compile-time, auditer explicitement :

Send + Sync
object safety / dyn compatibility
associated types éventuels
lifetime des descriptors statiques
coût/complexité de box/arc

Ne pas imposer dyn si une autre composition publique plus simple suffit ; ne pas définir des traits impossibles à enregistrer si le registry extensible est un besoin de la release.

8.10 Registry

Distinguer :

contrat/descripteur d'enregistrement dans Program API
registry runtime concret dans une implémentation/composition future

ksp-program-api ne doit pas devenir une bibliothèque runtime générale uniquement pour stocker des Vec<Box<dyn ...>> si ce comportement appartient à ksp-program-lib ou à un pipeline futur.

8.11 ProgramExecutionPreparer

L'architecture place ce contrat dans Program API, mais le sizing de 0.2.14 doit décider s'il entre dans la même release foundation.

Si retenu, il doit rester strictement :

input technique Program
validation protocolaire
comptes/PDA requis
construction de ProgramInstruction
signers/authorities publics requis
contraintes techniques

Et exclure :

wallet concret
secrets
recent blockhash
transaction assembly complète si elle appartient à Execution
simulation RPC
send/confirm
retry réseau
policy mainnet/spend
post-execution storage/replay

8.12 Logging

Présomption :

ksp-program-api purement déclaratif -> pas de ksp-logging-lib
pas de constants.rs / TRACING_TARGET
pas de tracing direct

Si un comportement runtime réel est ajouté malgré le scope, re-sizer la release avant d'introduire logging.

8.13 Sérialisation

Ne pas ajouter serde par anticipation.

Une API in-memory n'a pas besoin de sérialisation uniquement parce qu'un futur Store pourrait en avoir besoin.

8.14 Sizing

Évaluer chaque capability candidate selon :

nécessité immédiate
nombre de types publics
risque de figer une mauvaise API
besoin d'Interface supplémentaire
besoin d'une future couche CORE/Store/Materializer
possibilité de test external-consumer
budget 15-20 min par tranche
clôturabilité dans une session

Réduire le scope avant l'implémentation lourde si nécessaire.

9. Objectifs et livrables de `0.2.14`

9.1 Crate et façade

Créer, après validation pre.001 :

crates/ksp-program-api/

Avec :

Cargo.toml
README.md
USAGE.md
src/lib.rs
modules privés
réexports crate-root explicites
unit_tests/ pour unit tests
tests/ pour consumer/public/dependency canaries

9.2 Contrats publics minimaux

La surface finale doit être issue du plan pre.001, pas de cette liste comme checklist forcée.

Elle doit néanmoins démontrer au minimum :

un vrai point d'extension Program
un input public stable provenant de Core/Interface
une implémentation externe possible
aucune enum centrale de protocoles
aucune dépendance sur l'implémentation officielle future

9.3 Dependency firewall

Cible pressentie :

ksp-program-api
    -> ksp-core-lib
    -> ksp-interface-lib   seulement si surface publique réellement utilisée

Interdits par défaut :

ksp-program-lib
ksp-onchain-transport-lib
ksp-offchain-transport-lib
ksp-config-lib
ksp-store-api / ksp-store-lib
ksp-materializer-api / ksp-materializer-lib
ksp-wallet-lib
Tauri
reqwest / tonic / tokio
borsh / wincode / bincode
serde / serde_json sans frontière prouvée
solana-instruction
tracing direct
ksp-logging-lib si API purement déclarative

Ne pas ajouter ksp-interface-lib uniquement pour respecter un graphe dessiné : si aucun type Interface n'est utilisé, DEP-KSP-005/minimalité l'emporte.

9.4 External implementation canary

Le gate de release doit prouver qu'une crate consommatrice séparée peut :

implémenter le ou les traits publics retenus
utiliser un Program Pubkey non enregistré dans Core
consommer uniquement les exports crate-root
ne dépendre ni de ksp-program-lib ni d'un module privé

9.5 Documentation

Créer un plan/validation dédiés :

docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md
docs/validation/017-V0_2_14_PROGRAM_API.md

Mettre à jour les index correspondants lorsque ces fichiers sont créés.

README/USAGE de ksp-program-api sont réconciliés dans le couloir documentaire final, pas au milieu des tranches fonctionnelles sauf scaffold initial minimal.

10. Hors périmètre explicite

Sont hors de 0.2.14, sauf re-scope documenté après découverte bloquante :

ksp-program-lib complet
premier decoder Solana Core officiel
premier decoder SPL officiel
vertical slice protocolaire réel
materializers
Store D1/D2/D3/D4
modèles RAW/CORE complets
instruction path/CPI tree générique
logs/return data/balance deltas normalisés
canonical transaction/replay
ksp-execution-policy-api
ksp-execution-lib
wallet/signature
simulation/send/confirmation
RPC/WS/gRPC
Config
Tauri/apps
IDLs runtime
Anchor decoder générique
registry global de tous les programmes KSP
serde/JSON comme format canonique de decode

La release ne doit pas devenir une mini-version de toutes les couches futures sous prétexte de « rendre l'API complète ».

11. Contraintes sécurité, API et architecture spécifiques

11.1 Surface ouverte

Un nouveau programme externe doit pouvoir être supporté sans modifier une enum ProgramKind centrale.

11.2 Types fondamentaux

Utiliser ksp_core_lib::Pubkey / réexports KSP, pas des IDs textuels parallèles.

11.3 Entrées hostiles

Tout contrat acceptant strings/bytes/vectors doit posséder des bornes déterministes si la taille est attacker-controlled.

11.4 Debug

Aucun Debug public ne doit recopier arbitrairement des payloads instruction ou diagnostics externes volumineux.

11.5 Pas de narrowing implicite

Les conversions numériques sont explicites et validées.

11.6 Pas de sérialisation accidentelle

Ne pas dériver Serialize/Deserialize sur toute l'API uniquement pour faciliter les tests.

11.7 Pas de comportement réseau

Une méthode de trait Program ne reçoit pas un client RPC, une URL provider ou un wallet.

11.8 Pas de policy cachée

Un decoder reconnaît/décode ; un preparer prépare. Ils ne décident pas d'une autorisation produit ou mainnet.

11.9 Extensibilité testable

L'extensibilité doit être prouvée par un consumer externe concret, pas seulement affirmée par documentation.

11.10 API minimale

Chaque type public doit justifier :

qui le produit
qui le consomme
pourquoi Core/Interface ne suffit pas
pourquoi il appartient déjà à 0.2.14

12. Première mission `0.2.14-pre.001` — gate obligatoire

12.1 Baseline stable

Vérifier :

v0.2.13 réel
version Cargo stable
rel.001 présent
Interface stable
absence de Program API/Lib
workspace vert au point de départ ou anomalies documentées

12.2 Audit interne complet

Produire l'inventaire actuel de :

Core types utilisables
Interface exports utilisables
frontières dependencies
règles API/Program
architecture Program/Execution
séquence 0.3.x future

12.3 Audit kbot3

Avec l'archive khadhroony-bot3_v0.5.3-pre.005-fix010.zip, produire une matrice réelle au minimum sur :

decoder identity/surface/coverage
recognition/support semantics
decode outcomes/diagnostics/proofs
decoder traits
replay/context input
open decoded event model
execution request/capability/prepared plan
ancien executor trait
monolithic ownership

Classer chaque concept REPRENDRE / REDESSINER / REPORTER / REJETER.

12.4 Audit externe ciblé

Seulement selon les candidats retenus :

semantics Solana officielles réellement invoquées
Rust dyn/object-safety actuelle si registry dyn retenu
nouvelles dépendances éventuelles

Aucune recherche externe n'est nécessaire pour justifier une dépendance qui n'est finalement pas ajoutée.

12.5 Matrice d'ownership

Produire une matrice comparable à :

concept                              owner attendu
Pubkey                               Core
Program IDs fondamentaux             Core
ProgramAccountMeta                   Interface
ProgramInstruction                   Interface
recognition contract                 Program API
decoder capability                   Program API
decoder implementation               external / future Program Lib
wire codec                            Interface
transaction context CORE             future CORE
materialized decoded fact            future Materializer/D3
execution policy                     future ExecutionPolicy
network execution                    future Execution Lib

12.6 API candidate

Avant tout code, proposer les signatures publiques candidates :

traits
descriptors
enums/statuts éventuels
input/output types
error/result
ownership des strings/bytes
Send/Sync/object safety

Pour chaque élément, indiquer les alternatives rejetées.

12.7 Dependency graph cible

Proposer puis vérifier un graphe minimal.

Candidat :

ksp-program-api
├── ksp-core-lib
└── ksp-interface-lib   si utilisé

Toute autre dépendance doit être justifiée individuellement.

12.8 Threat/API model

Couvrir au minimum :

payload hostile
Program Pubkey inconnu
implémentation externe hostile ou incorrecte
panics dans des méthodes default
Debug leak
strings non bornées
registry conflicts si registry retenu
priority ambiguity
false exact recognition
status incohérent avec résultat
dyn/object-safety impossible
closed-world enum accidentelle

12.9 Stratégie de tests

Prévoir :

unit tests des value objects retenus
public API crate-root
external consumer/implementation
dependency firewall
release completeness
unknown Program Pubkey
object safety si nécessaire
adversarial bounds/Debug
aucun network smoke

12.10 Sizing et prévision souple recalibrée

Comparer le scope réel à la prévision initiale de la section 13.

Chaque tranche intermédiaire vise environ 15-20 minutes de travail effectif maximum comme budget de planning.

Si decoder + preparer + registry + open payload ne peuvent pas être stabilisés proprement dans la même session, réduire 0.2.14 avant de coder.

12.11 Documents de sortie `pre.001`

Créer/mettre à jour au minimum :

Cargo.toml
docs/plans/000-README.md
docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md
docs/validation/000-README.md
docs/validation/017-V0_2_14_PROGRAM_API.md
deltas/0.2.14/pre.001.md

Ne pas créer le scaffold lourd de ksp-program-api tant que la matrice d'API et le sizing ne sont pas cohérents.

Critères de sortie de `pre.001`

Le gate est réussi seulement si :

base v0.2.13 vérifiée
archive kbot3 réellement auditée
matrice REPRENDRE/REDESSINER/REPORTER/REJETER documentée
ownership Core/Interface/Program/CORE/Execution explicite
surface API candidate écrite
questions payload/registry/preparer tranchées ou explicitement reportées
dependency graph cible minimal
threat/API model établi
stratégie de tests établie
scope clôturable dans une session
prévision souple recalibrée
aucun développement fonctionnel lourd commencé prématurément

13. Prévision souple initiale des prereleases

Cette trajectoire est volontairement souple. pre.001 peut scinder, fusionner ou supprimer des tranches fonctionnelles, mais doit préserver la séparation finale gate technique / réconciliation documentaire / préparation de publication.

`pre.001` — Audit KSP + kbot3 + frontières + API model + sizing

Lectures obligatoires, inventaire stable, audit historique, ownership, threat model, dependency graph, signatures candidates, stratégie de tests et plan détaillé.

`pre.002` — Scaffold `ksp-program-api` + façade + dependency firewall

Créer la crate minimale, l'intégrer au workspace, réexports crate-root, README/USAGE initiaux minimaux, public API canary et exact dependency boundary. Aucun decoder concret.

`pre.003` — Identité / capability / reconnaissance minimales

Introduire uniquement les value objects/statuts réellement retenus en pre.001, avec Pubkey typé et invariants bornés. Ne pas encore inventer le payload canonique si celui-ci est reporté.

`pre.004` — Premier contrat decoder public

Matérialiser la capability decoder prioritaire, probablement instruction si le sizing le confirme, contre les types Interface existants. Prouver l'implémentation depuis une crate d'intégration séparée.

`pre.005` — Outcome / descriptor / registry contract ou seconde capability réellement retenue

Cette tranche ne doit exister que pour les éléments explicitement justifiés par pre.001. Elle peut servir au descriptor/coverage, à une seconde capability ou au contrat de composition, mais ne remplit pas l'API par symétrie.

`pre.006` — Execution preparation foundation uniquement si retenue

Si ProgramExecutionPreparer appartient au scope recalibré, introduire son contrat sans wallet, policy, transport, simulation ou send. Sinon cette tranche est supprimée ou réaffectée à un hardening réel.

`pre.007` — External implementation + adversarial/API hardening

Prouver extensibilité depuis un consumer séparé, Program ID inconnu, object safety/dyn si nécessaire, Debug/bounds/errors, exact export inventory et dependency firewall final.

`pre.008` — Gate technique final

Aucun nouveau développement fonctionnel. Audits Rust, check, Clippy, tests ciblés, workspace complet et graphes Cargo.

`pre.009` — Réconciliation documentaire finale

README/USAGE, plan, validation, séquence/index/références durables réellement touchés. Aucun CHANGELOG/ROADMAP/prompt suivant.

`pre.010` — Préparation de publication minimale

Uniquement :

Cargo.toml
CHANGELOG.md
ROADMAP.md
prompt de démarrage de la release suivante
delta pre.010

Aucun code/test/README/USAGE/plan/validation/architecture.

`rel.001` — Publication stable

Mécanique de publication uniquement ; aucun rattrapage fonctionnel ou documentaire.

14. Versionnement, deltas, commits, archives et tags

Appliquer docs/rules/VERSION_WORKFLOW.md.

Rappels :

workspace.package.version 0.2.14-pre.N pour une prerelease non-fix
identifiant de livraison X.Y.Z-pre.NNN
delta deltas/0.2.14/pre.NNN.md
fix local à sa responsabilité : pre.NNN-fix.MMM
version Cargo d'un fix code/runtime : 0.2.14-pre.N.fix.M

À partir de 0.1.x, chaque delta est commité.

Commit attendu :

v0.2.14-pre.NNN

Les prereleases/fixes ne nécessitent pas de tag Git.

La release stable reçoit :

commit v0.2.14-rel.001
tag v0.2.14
workspace.package.version = 0.2.14

Archives overlay :

ksp-general-0.2.14-pre.NNN.zip

Elles contiennent uniquement les fichiers ajoutés/modifiés + delta correspondant.

Ne jamais remplacer silencieusement une archive publiée sous le même identifiant.

15. Validation opérateur et procédure d'application

Après application d'un 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.2.14
cargo check --workspace
cargo clippy --workspace --all-targets

Puis les tests ciblés de ksp-program-api dès que la crate existe :

cargo test -p ksp-program-api

Aux gates techniques/final :

cargo test --workspace
cargo tree -p ksp-program-api --edges normal
cargo tree --duplicates

Si une nouvelle dépendance externe est introduite :

cargo tree -i <dependency>

selon le besoin.

Aucun smoke réseau/live n'est attendu pour une API purement déclarative.

Ne pas déclarer un gate vert si une commande demandée n'a pas été réellement exécutée.

16. Tests et canaris attendus

16.1 Public API

Le consumer doit utiliser exclusivement les exports crate-root.

16.2 External implementation

Une crate de test séparée doit implémenter la capability publique retenue pour un Program Pubkey opaque/non enregistré.

16.3 Dependency firewall

Le manifest Program API doit rester limité aux dépendances nécessaires et ne tirer aucun runtime réseau/storage/UI.

16.4 Open-world

Aucune enum centrale de Program IDs/protocoles ne doit être nécessaire pour enregistrer ou utiliser l'implémentation externe canari.

16.5 Recognition/decode invariants

Selon le contrat retenu :

unknown input
recognized but unsupported
exact/partial recognition
status incohérent
malformed payload
empty payload
max boundary
one-above boundary

16.6 Debug/error safety

Aucun payload hostile ou valeur externe arbitraire n'est copié dans Error/Debug sans borne.

16.7 Object safety

Si le design exige dyn Trait, ajouter un canari de compilation/usage réel. Sinon ne pas imposer ce gate artificiellement.

16.8 Release completeness

Verrouiller la surface réellement décidée sans rendre impossible son extension future.

17. Critères de clôture de `0.2.14`

La release peut être publiée seulement si :

ksp-program-api existe et respecte les règles *-api
surface publique minimale documentée
au moins une capability Program réellement implémentable depuis une crate externe
aucune enum centrale fermée de programmes
aucun ksp-program-lib anticipé
aucune dépendance Transport/Store/Wallet/Materializer/Tauri
aucun codec wire direct Program API
aucun logging runtime inutile
aucun replay/CORE context artificiellement inventé
external implementation canary PASS
public API canary PASS
dependency firewall PASS
adversarial/API hardening PASS
cargo test -p ksp-program-api PASS
cargo test --workspace PASS
graphe Cargo inspecté
documentation durable réconciliée
CHANGELOG/ROADMAP/prompt suivant préparés dans la dernière prerelease dédiée

Si ProgramExecutionPreparer a été reporté par pre.001, son absence n'est pas un échec de release : le plan doit simplement indiquer explicitement son prochain owner/release.

18. Release/session suivante envisagée

Après 0.2.14, la séquence active prévoit :

0.3.1 — ksp-store-api + ksp-store-lib, RAW only

Puis :

0.3.2 — extension ksp-interface-lib pour wires génériques acquisition/CORE
0.3.3 — ksp-job-api + backfill
0.3.4 — application backfill/RAW

0.2.14 ne doit pas aspirer ces contrats pour rendre Program API artificiellement « complet ».

Le prompt suivant préparé en fin de release sera donc consacré à 0.3.1, sauf décision de roadmap explicitement modifiée avant la clôture.

19. Instruction d'ouverture

À l'ouverture de la session 0.2.14 :

vérifier que la base est exactement v0.2.13 ;
vérifier que l'archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip est disponible ;
lire les règles et architectures listées dans les sections 3.1 et 3.2 ;
inventorier la surface réelle Core + Interface de v0.2.13 ;
auditer les contrats kbot3 listés en section 4 ;
produire la matrice REPRENDRE / REDESSINER / REPORTER / REJETER ;
proposer ownership, API candidate, dependency graph, threat/API model et stratégie de tests ;
recalibrer la prévision souple et le sizing ;
créer seulement ensuite le delta/documentation 0.2.14-pre.001 ;
ne pas commencer le scaffold fonctionnel ksp-program-api avant que le gate pre.001 soit cohérent.

Le premier message de travail doit commencer par l'audit de la base réelle et des deux sources KSP/kbot3, pas par une proposition de code fondée sur la mémoire.

40 KiB Raw Blame History

Prompt de démarrage 0.2.14 — Program API foundation