ksp-program-api
ksp-program-api est la façade publique ouverte du domaine Program KSP. Elle porte uniquement les contrats communs nécessaires aux implémentations Program officielles futures comme aux crates externes ; elle ne possède aucun decoder concret, registry runtime, payload canonique DECODE ni logique d'exécution.
La surface candidate de 0.2.14 est volontairement instruction-only et reste indépendante des couches runtime supérieures.
Ownership
Le graphe normal est limité à :
ksp-program-api
├── ksp-core-lib
└── ksp-interface-lib
└── ksp-core-lib
Core reste propriétaire de :
Error
ErrorCode
ErrorContext
Result
Pubkey
Interface reste propriétaire de :
ProgramAccountMeta
ProgramInstruction
Program API possède :
ProgramInstructionRecognition
ProgramInstructionDecodeOutcome<Decoded>
ProgramInstructionDecoder
ksp-program-api réexporte toute sa surface consommable depuis son crate-root. Aucun module interne n'est public.
Surface publique candidate
L'inventaire crate-root de 0.2.14 contient exactement :
Error
ErrorCode
ErrorContext
Result
Pubkey
ProgramAccountMeta
ProgramInstruction
ProgramInstructionRecognition
ProgramInstructionDecodeOutcome<Decoded>
ProgramInstructionDecoder
Les canaris de release completeness verrouillent cet inventaire ainsi que les trois fichiers/modules Rust de production de la crate.
Recognition
ProgramInstructionRecognition est #[non_exhaustive] :
NoMatch l'implémentation ne revendique pas l'instruction
ProgramMatch le Program correspond, sans reconnaissance instruction-local exacte
ExactMatch l'implémentation affirme un match instruction-local exact
La reconnaissance ne porte aucun score, priorité, proof, confidence, discriminator textuel ni inventaire central de Programs. ExactMatch reste une affirmation de l'implémentation, pas une preuve indépendante produite par KSP.
Decode outcome
ProgramInstructionDecodeOutcome<Decoded> est #[non_exhaustive] :
Decoded(Decoded) valeur typée possédée par l'implémentation
Unsupported instruction reconnue mais non supportée par cette capability
Les échecs réels utilisent le Result Core. Il n'existe aucune variante parallèle Failed ou Ignored.
Le Debug de l'outcome n'impose pas Decoded: Debug et n'affiche jamais la valeur Decoded.
Decoder instruction-only
ProgramInstructionDecoder est un trait ouvert Send + Sync :
type Decoded
program_ids(&self) -> &[Pubkey]
recognize(&self, &ProgramInstruction) -> ProgramInstructionRecognition
decode(&self, &ProgramInstruction) -> Result<ProgramInstructionDecodeOutcome<Self::Decoded>>
Decoded ne reçoit aucun bound implicite supplémentaire : une implémentation reste propriétaire de son type de sortie concret. Le trait ne fournit aucun default method et ne promet pas de composition dyn hétérogène.
program_ids() expose des Pubkey opaques ; une implémentation externe peut prendre en charge un Program ID absent du registry Core. Aucun enum central, Any, JSON ou descriptor global n'est nécessaire.
program_ids et recognize servent à la sélection explicite. decode consomme par référence une ProgramInstruction déjà admise/bornée par Interface et déjà sélectionnée pour le decoder.
Hardening validé
La candidate verrouille notamment :
Program Pubkey non enregistré accepté
input Interface maximal 255 accounts + 10_240 bytes accepté à la frontière decoder
payload hostile aucun echo automatique ajouté par Program API
Debug outcome valeur Decoded jamais rendue
associated Decoded aucun Debug/Clone/Send/Sync imposé
closed-world Program enum absent
registry / descriptors / priority absents
ProgramExecutionPreparer absent
serde / JSON / Any / codecs absents
logging / runtime / filesystem / environment / I/O absents
Une implémentation tierce reste responsable du contenu des erreurs qu'elle construit explicitement. ksp-program-api garantit seulement qu'il n'ajoute aucun canal parallèle ni copie automatique du payload d'entrée.
Frontières
La foundation 0.2.14 ne contient pas :
ksp-program-lib
registry runtime
identity/version/coverage de decoder
payload canonique D3
ProgramAccountDecoder
ProgramEventDecoder
ProgramReturnDataDecoder
ProgramExecutionPreparer
serde / serde_json
borsh / wincode / bincode
solana-instruction
network / async runtime
logging / tracing
Wallet / Transport / Store / Materializer / Config / Tauri
Ces surfaces restent reportées jusqu'aux vertical slices qui démontreront leurs contrats réels. En particulier, les codecs wire officiels restent possédés par ksp-interface-lib et ne sont introduits qu'en présence d'un protocole réel.