1431 lines
40 KiB
Markdown
1431 lines
40 KiB
Markdown
<!-- file: prompts/019-V0_2_14_START_PROMPT.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# 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 :
|
|
|
|
```text
|
|
v0.2.13
|
|
```
|
|
|
|
La release à ouvrir est :
|
|
|
|
```text
|
|
0.2.14 — Program API foundation
|
|
```
|
|
|
|
La première tranche est :
|
|
|
|
```text
|
|
0.2.14-pre.001
|
|
```
|
|
|
|
Deux archives sont requises au démarrage de la session :
|
|
|
|
```text
|
|
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é :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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é :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
```
|
|
|
|
Pour tout Markdown touché :
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
REPRENDRE
|
|
REDESSINER
|
|
REPORTER
|
|
REJETER
|
|
```
|
|
|
|
Exemples à confronter explicitement :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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** :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
Pubkey
|
|
ProgramAccountMeta
|
|
ProgramInstruction
|
|
MAX_PROGRAM_INSTRUCTION_ACCOUNTS = 255
|
|
MAX_PROGRAM_INSTRUCTION_DATA_LEN = 10_240
|
|
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED
|
|
```
|
|
|
|
Propriétés :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
ksp-onchain-transport-lib
|
|
ksp-offchain-transport-lib
|
|
ksp-wallet-lib
|
|
ksp-config-lib
|
|
ksp-app-*-desk
|
|
```
|
|
|
|
Frontières :
|
|
|
|
```text
|
|
Program API -X-> Transport
|
|
Program API -X-> Store
|
|
Program API -X-> Wallet
|
|
Program API -X-> Materializer
|
|
Program API -X-> Tauri
|
|
```
|
|
|
|
### 6.4 Pipeline durable
|
|
|
|
```text
|
|
RAW -> CORE -> DECODE -> SPECIALIZED
|
|
```
|
|
|
|
Avec :
|
|
|
|
```text
|
|
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
|
|
|
|
1. la crate cible se nomme `ksp-program-api` ;
|
|
2. le suffixe `-api` est volontaire et conforme à `KSP-NAME-002` ;
|
|
3. `ksp-program-api` contient les **contrats**, pas les implémentations officielles ;
|
|
4. `ksp-program-lib` reste hors de `0.2.14` ;
|
|
5. une implémentation externe doit pouvoir dépendre directement de `ksp-program-api` ;
|
|
6. un nouveau Program ID externe ne doit pas nécessiter la modification d'une enum centrale KSP ;
|
|
7. `ksp-program-api` peut dépendre de Core et d'Interface si leurs types sont réellement utilisés ;
|
|
8. `ksp-program-api` ne dépend pas de Transport/Store/Wallet/Materializer ;
|
|
9. les Program IDs fondamentaux et `Pubkey` restent Core-owned ;
|
|
10. le wire reste Interface-owned ;
|
|
11. les codecs wire restent hors Program API ;
|
|
12. le decoder vise aussi les surfaces historiques distinguables ;
|
|
13. `deprecated` concerne la capability d'exécution, pas la capacité de décodage ;
|
|
14. `ProgramExecutor` est abandonné au profit du concept `ProgramExecutionPreparer` pour la préparation pure ;
|
|
15. la policy/safety, signature, blockhash, simulation, envoi, confirmation et retry réseau ne sont pas Program API ;
|
|
16. les modèles acquisition/replay/CORE complets ne sont pas créés dans `0.2.14` ;
|
|
17. kbot3 est une source historique, jamais une autorité architecturale ;
|
|
18. une crate `*-api` purement déclarative n'ajoute pas de logging sans comportement réel ;
|
|
19. aucun `ksp-api-lib` ou `ksp-interface-api` n'est créé par symétrie ;
|
|
20. 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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
&ksp_interface_lib::ProgramInstruction
|
|
```
|
|
|
|
Auditer s'il suffit à la première capability.
|
|
|
|
Ne pas ajouter automatiquement :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
Decoded
|
|
Ignored
|
|
Unsupported
|
|
Failed
|
|
```
|
|
|
|
Décider lesquels ont un sens dans une API sans payload canonique D3 encore stabilisé.
|
|
|
|
Ne pas confondre :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
ExactDiscriminator
|
|
ExactLayout
|
|
Idl
|
|
Manual
|
|
LogCorrelation
|
|
BalanceDelta
|
|
Heuristic
|
|
Audit
|
|
```
|
|
|
|
Distinguer :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
input technique Program
|
|
validation protocolaire
|
|
comptes/PDA requis
|
|
construction de ProgramInstruction
|
|
signers/authorities publics requis
|
|
contraintes techniques
|
|
```
|
|
|
|
Et exclure :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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` :
|
|
|
|
```text
|
|
crates/ksp-program-api/
|
|
```
|
|
|
|
Avec :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
ksp-program-api
|
|
-> ksp-core-lib
|
|
-> ksp-interface-lib seulement si surface publique réellement utilisée
|
|
```
|
|
|
|
Interdits par défaut :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 à :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
v0.2.14-pre.NNN
|
|
```
|
|
|
|
Les prereleases/fixes ne nécessitent pas de tag Git.
|
|
|
|
La release stable reçoit :
|
|
|
|
```text
|
|
commit v0.2.14-rel.001
|
|
tag v0.2.14
|
|
workspace.package.version = 0.2.14
|
|
```
|
|
|
|
Archives overlay :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```bash
|
|
cargo test -p ksp-program-api
|
|
```
|
|
|
|
Aux gates techniques/final :
|
|
|
|
```bash
|
|
cargo test --workspace
|
|
cargo tree -p ksp-program-api --edges normal
|
|
cargo tree --duplicates
|
|
```
|
|
|
|
Si une nouvelle dépendance externe est introduite :
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
0.3.1 — ksp-store-api + ksp-store-lib, RAW only
|
|
```
|
|
|
|
Puis :
|
|
|
|
```text
|
|
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` :
|
|
|
|
1. vérifier que la base est exactement `v0.2.13` ;
|
|
2. vérifier que l'archive historique `khadhroony-bot3_v0.5.3-pre.005-fix010.zip` est disponible ;
|
|
3. lire les règles et architectures listées dans les sections 3.1 et 3.2 ;
|
|
4. inventorier la surface réelle Core + Interface de `v0.2.13` ;
|
|
5. auditer les contrats kbot3 listés en section 4 ;
|
|
6. produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` ;
|
|
7. proposer ownership, API candidate, dependency graph, threat/API model et stratégie de tests ;
|
|
8. recalibrer la prévision souple et le sizing ;
|
|
9. créer seulement ensuite le delta/documentation `0.2.14-pre.001` ;
|
|
10. **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.
|