190 lines
5.3 KiB
Markdown
190 lines
5.3 KiB
Markdown
<!-- 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.
|