v0.0.3-pre.004

deltas/0.0.3/pre.004.md

@@ -0,0 +1,189 @@
+<!-- file: deltas/0.0.3/pre.004.md -->
+<!-- version: 1 -->
+
+# 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 :
+
+```text
+0.0.3-pre.3
+```
+
+à :
+
+```text
+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 :
+
+```text
+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 :
+
+```text
+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 :
+
+```text
+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 :
+
+```text
+domain -> program/protocol -> capability
+```
+
+avec une direction de travail de type :
+
+```text
+<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.