khadhroony-solana-project/deltas/0.0.3/pre.004.md

Delta 0.0.3-pre.004

Base requise

v0.0.3-pre.003.

Objectif

Détailler la frontière Wire/Program sans ouvrir encore la totalité de l'orchestration Execution/Policy.

La tranche formalise :

• ksp-interface-lib et la propriété des codecs wire ;
• la politique de sélection/réimplémentation des crates d'interface externes ;
• ksp-program-api ouvert/extensible ;
• les familles de decoders ;
• ProgramExecutionPreparer ;
• le lifecycle machine-readable des opérations anciennes/abandonnées ;
• le registry officiel + externe ;
• l'organisation future de ksp-program-lib ;
• le workflow d'une extension Program développée indépendamment.

Version Cargo

workspace.package.version passe de :

0.0.3-pre.3

à :

0.0.3-pre.4

Le header de Cargo.toml passe de version 9 à 10.

Fichiers ajoutés

• docs/architecture/006-WIRE_AND_PROGRAM.md
• deltas/0.0.3/pre.004.md

Fichiers modifiés

• Cargo.toml
• docs/architecture/000-README.md
• docs/architecture/003-COMPONENT_CONTRACTS.md
• docs/architecture/004-COMPONENT_INVENTORY.md
• docs/architecture/005-DEPENDENCY_GRAPH.md
• docs/rules/RULES_DEPENDENCIES.md
• docs/rules/RULES_KSP.md
• docs/IDEAS.md
• docs/plans/001-V0_0_3_PLAN.md
• prompts/001-V0_1_X_START_PROMPT.md

Fichiers supprimés

Aucun.

Décisions principales

Codecs wire

ksp-interface-lib est le propriétaire normal des dépendances wire telles que borsh, wincode et équivalents pour les interfaces officielles KSP.

ksp-program-lib ne redécode pas directement une surface officielle avec une autre génération de codec.

Sélection des interfaces externes

Une interface externe est retenue selon :

• caractère officiel/normatif ;
• stabilité/utilité de l'API ;
• compatibilité avec le stack actuel ;
• absence de dette de générations anciennes évitable.

Une crate protocolaire qui impose une ancienne génération incompatible d'un codec fondamental peut être remplacée par une réimplémentation KSP bornée aux contrats wire nécessaires.

Le workspace devra auditer les doublons de dépendances fondamentales (cargo tree -d, cargo tree -i ...) lorsque les dépendances fonctionnelles seront introduites.

Program API ouverte

Aucun enum central fermé de Program IDs n'est prévu.

Le résultat décodé doit pouvoir être auto-identifié, extensible et persistable.

Any ne peut pas constituer à lui seul le contrat de résultat.

Decoders

Les capacités sont séparables, avec notamment :

ProgramInstructionDecoder
ProgramAccountDecoder

et ajout de surfaces Event/ReturnData seulement lorsqu'un besoin réel le justifie.

Préparation d'exécution

Le terme ProgramExecutor est remplacé conceptuellement par :

ProgramExecutionPreparer

Il prépare l'opération protocolaire mais ne signe, simule, envoie ou confirme pas la transaction.

Lifecycle / deprecated

Le statut d'une opération est machine-readable.

Une opération simplement ancienne n'est pas automatiquement deprecated.

Une opération réellement abandonnée peut rester techniquement préparée avec warning et être ensuite autorisée/refusée par la policy supérieure.

#[deprecated] n'est pas obligatoire.

Le decoder continue de décoder les surfaces historiques distinguables.

Registry et extensions

Le registry doit composer implémentations officielles, externes et expérimentales.

Une extension s'appelle conceptuellement :

ksp-program-<name>-lib

et implémente ksp-program-api.

Elle peut exister/tester indépendamment de ksp-program-lib.

Si son interface wire n'est pas encore officiellement intégrée à KSP, elle peut temporairement posséder ses propres définitions compatibles.

Lors de l'intégration officielle, le wire migre vers ksp-interface-lib et l'implémentation Program vers ksp-program-lib sans modifier le contrat commun uniquement pour ce nouveau Program ID.

Organisation de ksp-program-lib

Principe retenu :

domain -> program/protocol -> capability

avec une direction de travail de type :

<domain>/<program>/dec/*
<domain>/<program>/exec_prep/*

Les noms exacts de répertoires restent à valider avec la première implémentation.

Plan ajusté

La tranche Execution/Policy est déplacée vers pre.005.

Les tranches suivantes sont décalées :

• pre.005 — Execution/Policy ;
• pre.006 — Data/Store/Acquisition ;
• pre.007 — Apps/Workers/Jobs/Scenarios ;
• pre.008 — plan des premières releases fonctionnelles ;
• pre.009 — clôture fondatrice.

Questions reportées

• représentation exacte du payload décodé ouvert/persistable ;
• descripteurs/registry exacts ;
• conflits entre plusieurs implémentations d'un même Program ID ;
• formes Rust exactes des traits ;
• noms définitifs dec / exec_prep.

Ces points seront fixés avec les premières implémentations lorsqu'un cas réel permet de tester la qualité du contrat.

Validations

• headers file: / version: vérifiés ;
• Cargo.toml parsé et version 0.0.3-pre.4 vérifiée ;
• liens vers 006-WIRE_AND_PROGRAM.md vérifiés ;
• plan pre.005 à pre.009 vérifié ;
• aucune commande Cargo de build/test exécutée : ce delta reste documentaire et n'ajoute aucun code Rust fonctionnel.