v0.2.14-pre.001
This commit is contained in:
625
docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md
Normal file
625
docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md
Normal file
@@ -0,0 +1,625 @@
|
||||
<!-- file: docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Plan `0.2.14` — Program API foundation
|
||||
|
||||
## 1. Statut et base
|
||||
|
||||
Ce plan est établi par `0.2.14-pre.001` à partir de la release stable `v0.2.13` et de l'archive historique obligatoire `khadhroony-bot3_v0.5.3-pre.005-fix010.zip`.
|
||||
|
||||
La base KSP vérifiée à l'ouverture est :
|
||||
|
||||
```text
|
||||
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
|
||||
ksp-program-api absent
|
||||
ksp-program-lib absent
|
||||
```
|
||||
|
||||
L'archive opérateur ne contient pas de metadata Git exploitable ; le tag `v0.2.13` ne peut donc pas être revérifié localement. L'identité stable est établie par la version Cargo, le delta `rel.001`, le prompt suivant et la surface Interface publiée. Aucun écart bloquant n'a été trouvé entre la base réelle et le prompt.
|
||||
|
||||
Après application de `pre.001`, la version Cargo cible est :
|
||||
|
||||
```text
|
||||
0.2.14-pre.1
|
||||
```
|
||||
|
||||
## 2. Mission recalibrée
|
||||
|
||||
`0.2.14` introduit `ksp-program-api` comme première crate publique extensible du domaine Program.
|
||||
|
||||
Le scope est volontairement réduit à une **foundation de décodage d'instruction typée** :
|
||||
|
||||
```text
|
||||
Core
|
||||
-> Pubkey + Error/Result
|
||||
|
||||
Interface
|
||||
-> ProgramAccountMeta + ProgramInstruction
|
||||
|
||||
Program API
|
||||
-> reconnaissance instruction-local
|
||||
-> outcome de décodage minimal
|
||||
-> trait ProgramInstructionDecoder ouvert
|
||||
-> output associé possédé par l'implémentation
|
||||
```
|
||||
|
||||
La release ne crée pas :
|
||||
|
||||
```text
|
||||
payload canonique D3
|
||||
registry runtime hétérogène
|
||||
identity/version runtime de decoder
|
||||
coverage matrix générique
|
||||
ProgramAccountDecoder
|
||||
ProgramEventDecoder
|
||||
ProgramReturnDataDecoder
|
||||
ProgramExecutionPreparer
|
||||
ksp-program-lib
|
||||
```
|
||||
|
||||
Ce réduction évite de figer des contrats appartenant aux futures couches CORE, DECODE, Materializer, Store ou Execution.
|
||||
|
||||
## 3. Sources KSP relues
|
||||
|
||||
Le gate `pre.001` a relu les sources prescrites par le prompt :
|
||||
|
||||
```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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Les règles structurantes sont notamment `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` et `DEP-CARGO-001..007`.
|
||||
|
||||
Le résultat normatif est sans ambiguïté : `ksp-program-api` porte des contrats ouverts, reste principalement déclaratif, doit être implémentable depuis une crate externe, utilise les types KSP existants et ne dépend pas des couches runtime supérieures.
|
||||
|
||||
## 4. Inventaire KSP actuel
|
||||
|
||||
### 4.1 Core
|
||||
|
||||
`ksp-core-lib` fournit déjà :
|
||||
|
||||
```text
|
||||
Error
|
||||
ErrorCode
|
||||
ErrorContext
|
||||
Result
|
||||
Pubkey
|
||||
registry KSP des Program IDs fondamentaux
|
||||
```
|
||||
|
||||
Le registry Core est un inventaire KSP de Program IDs fondamentaux. Il n'est pas un registry d'implémentations Program et ne doit pas devenir un closed-world gate : un decoder externe peut viser un `Pubkey` absent de ce registry.
|
||||
|
||||
### 4.2 Interface
|
||||
|
||||
La surface stable `0.2.13` fournit exactement :
|
||||
|
||||
```text
|
||||
Pubkey
|
||||
ProgramAccountMeta
|
||||
ProgramInstruction
|
||||
MAX_PROGRAM_INSTRUCTION_ACCOUNTS = 255
|
||||
MAX_PROGRAM_INSTRUCTION_DATA_LEN = 10_240
|
||||
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED
|
||||
```
|
||||
|
||||
`ProgramInstruction` apporte déjà l'input minimal nécessaire au premier decoder :
|
||||
|
||||
```text
|
||||
program_id: Pubkey
|
||||
accounts: ordered bounded ProgramAccountMeta slice
|
||||
data: bounded opaque byte slice
|
||||
```
|
||||
|
||||
Les comptes conservent ordre et doublons. Les Program IDs sont opaques. Le `Debug` de l'instruction ne copie ni accounts ni bytes. Il n'existe donc aucune lacune Interface à combler pour le scope instruction-only.
|
||||
|
||||
### 4.3 Pipeline futur
|
||||
|
||||
La frontière durable reste :
|
||||
|
||||
```text
|
||||
RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
```
|
||||
|
||||
`RAW -> CORE` ne dépend pas de Program. Le futur `CORE -> DECODE` pourra fournir une instruction Interface accompagnée d'un contexte CORE séparé lorsque ce contexte existera. `0.2.14` ne crée pas ce contexte par anticipation.
|
||||
|
||||
## 5. Audit historique kbot3
|
||||
|
||||
### 5.1 Fichiers audités
|
||||
|
||||
Les contrats et usages historiques ont été relus dans :
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Les trois decoders concrets montrent que l'ancien `DcApiInstructionDecoder` était réellement utilisé pour `identity`, `surfaces`, `coverage`, `recognize` puis `decode`, mais contre un input contextualisé contenant signature, slot, instruction path, transaction failure, hashes, logs, balance changes et JSON. Ces dépendances contextuelles ne sont pas présentes dans la foundation KSP actuelle.
|
||||
|
||||
`ks-lib` regroupait en outre modèles, decoders, executors et materializers avec un graphe comprenant codecs, serde/JSON, interfaces Solana et tracing. Cette ownership monolithique est incompatible avec les frontières KSP actuelles.
|
||||
|
||||
### 5.2 Matrice d'héritage
|
||||
|
||||
| Concept historique | Observation réelle kbot3 | Décision | Application KSP `0.2.14` |
|
||||
|-----------------------------------|----------------------------------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------|
|
||||
| `DcApiDecoderIdentity` | nom et version alloués en `String` | REPORTER | aucune identity runtime tant qu'aucun registry ou replay persistant ne la consomme |
|
||||
| `DcApiDecoderSurface` | Program ID textuel, surface code et priorité | REDESSINER | Program IDs typés; surface code et priorité reportés avec le registry |
|
||||
| `DcApiDecoderCoverageDeclaration` | matrice sérialisable instruction/event/discriminator | REPORTER | couverture machine-readable reportée au premier besoin d'inventaire/runtime |
|
||||
| `DcApiDecoderRecognition` | compatible, exact, priority et codes textuels | REPRENDRE | reconnaissance conservée mais réduite à trois niveaux sans priorité ni strings |
|
||||
| `DcApiDecoderOutcomeStatus` | `Decoded`, `Ignored`, `Unsupported`, `Failed` | REDESSINER | `Decoded(T)` ou `Unsupported`; `Failed` devient `Err`, `Ignored` n'est pas justifié pour un decoder d'instruction |
|
||||
| `DcApiDecoderDiagnostic` | code, message et retriable sérialisables | REPORTER | `ksp_core_lib::Error/Result` suffit à la foundation; diagnostic Program dédié reporté |
|
||||
| `DcApiDecoderProof` | preuve et confidence, dont logs/balances/heuristique | REPORTER | aucun proof sans contexte CORE réel; l'exactitude de recognition reste une assertion du decoder |
|
||||
| `DcApiInstructionDecoder` | trait `Send + Sync` avec identity, coverage, recognize, decode | REPRENDRE | trait instruction-only conservé, input remplacé par `ProgramInstruction`, output devient associated type |
|
||||
| `DcApiProtocolDecoder` | trait générique parallèle avec support `No/Maybe/Yes` | REJETER | pas de second trait monolithique; les capabilities restent séparées par trait |
|
||||
| `MdCoreInstructionReplayInput` | input JSON riche de transaction/CPI/logs/balances | REPORTER | futur CORE; aucune reconstruction en `0.2.14` |
|
||||
| `MdDecodedProtocolEvent` | identité événement liée à signature, slot, path et strings protocole | REPORTER | futur contrat DECODE/Materializer; absent de la foundation |
|
||||
| `MdProgramId` / `MdPubkey` | wrappers `String` | REJETER | `ksp_core_lib::Pubkey` reste canonique |
|
||||
| `MdInstructionPath` | path CPI textuel | REPORTER | futur CORE; absent de `ProgramInstruction` |
|
||||
| `ExApiExecutionRequest` | operation code + `payload_json` générique | REJETER | ne pas créer de JSON générique pour masquer un contrat d'intent non conçu |
|
||||
| `ExApiExecutionCapability` | supported/unsupported avec strings | REDESSINER | concept utile pour un futur preparer, mais aucun contrat execution en `0.2.14` |
|
||||
| `ExApiPreparedExecutionPlan` | instructions, signers, policy, spend et metadata | REDESSINER | séparer plus tard préparation technique et policy; réutiliser `ProgramInstruction` pour le wire |
|
||||
| `ExApiInstructionExecutor` | support + plan générique JSON | REJETER | concept `ProgramExecutor` abandonné |
|
||||
| `ExApiTypedInstructionExecutor` | associated `Intent` et build pur d'un plan | REPRENDRE | idée de préparation pure conservée conceptuellement pour futur `ProgramExecutionPreparer` |
|
||||
| policy intégrée au plan | cluster, simulation, spend, blockhash, post-validation | REJETER | owner futur `ksp-execution-policy-api` / `ksp-execution-lib` |
|
||||
| `ks-lib` monolithique | decoder + executor + materializer + model + codecs | REJETER | frontières `Interface`, `Program API`, futurs `Program Lib`, `Materializer`, `Execution` séparées |
|
||||
|
||||
## 6. Matrice d'ownership
|
||||
|
||||
| Concept | Owner | Décision `0.2.14` |
|
||||
|------------------------------------|----------------------------------------------|--------------------------------------------|
|
||||
| `Pubkey` | `ksp-core-lib` | réutilisé; jamais dupliqué |
|
||||
| Program IDs fondamentaux KSP | `ksp-core-lib` | inchangés; non exhaustifs du monde externe |
|
||||
| `ProgramAccountMeta` | `ksp-interface-lib` | réutilisé |
|
||||
| `ProgramInstruction` | `ksp-interface-lib` | input du premier decoder |
|
||||
| bornes wire instruction | `ksp-interface-lib` | inchangées |
|
||||
| recognition instruction-local | `ksp-program-api` | introduite |
|
||||
| capability decoder instruction | `ksp-program-api` | introduite |
|
||||
| output décodé protocolaire concret | extension externe ou futur `ksp-program-lib` | associated type de l'implémentation |
|
||||
| payload canonique DECODE/D3 | future frontière DECODE/Materializer/Store | reporté |
|
||||
| decoder officiel | futur `ksp-program-lib` | hors scope |
|
||||
| contexte transaction/CPI/logs | future couche CORE | reporté |
|
||||
| registry runtime d'implémentations | future composition Program/DECODE | reporté |
|
||||
| wire codec officiel | `ksp-interface-lib` | hors Program API |
|
||||
| execution preparation | `ksp-program-api` futur | reporté de cette release |
|
||||
| execution policy | futur `ksp-execution-policy-api` | hors scope |
|
||||
| signature/simulation/send/confirm | futur `ksp-execution-lib` + Wallet/Transport | hors scope |
|
||||
| persistence/materialization | futurs Store/Materializer | hors scope |
|
||||
|
||||
## 7. API candidate retenue
|
||||
|
||||
Le design cible à matérialiser dans les tranches suivantes est volontairement petit.
|
||||
|
||||
### 7.1 Façade héritée
|
||||
|
||||
`ksp-program-api` dépendra de Core et Interface et pourra réexporter explicitement depuis son crate root les types nécessaires à une implémentation externe sans module privé :
|
||||
|
||||
```rust
|
||||
pub use ksp_core_lib::{Error, ErrorCode, ErrorContext, Pubkey, Result};
|
||||
pub use ksp_interface_lib::{ProgramAccountMeta, ProgramInstruction};
|
||||
```
|
||||
|
||||
Ces réexports ne changent pas l'ownership : Error/Pubkey restent Core-owned et les structures wire restent Interface-owned.
|
||||
|
||||
Les constantes d'admission Interface ne sont pas réexportées par défaut : l'input reçu a déjà franchi ces bornes et Program API ne les possède pas.
|
||||
|
||||
### 7.2 Recognition
|
||||
|
||||
Candidat retenu :
|
||||
|
||||
```rust
|
||||
#[non_exhaustive]
|
||||
pub enum ProgramInstructionRecognition {
|
||||
NoMatch,
|
||||
ProgramMatch,
|
||||
ExactMatch,
|
||||
}
|
||||
```
|
||||
|
||||
Sémantique :
|
||||
|
||||
```text
|
||||
NoMatch l'implémentation ne revendique pas cette instruction
|
||||
ProgramMatch le Program ID ou la famille est reconnue, mais l'entrée n'est pas prouvée exacte
|
||||
ExactMatch l'implémentation affirme une reconnaissance instruction-locale exacte
|
||||
```
|
||||
|
||||
Aucun score flottant, confidence, priority, surface code ou discriminator textuel n'entre dans la foundation.
|
||||
|
||||
Alternatives rejetées :
|
||||
|
||||
```text
|
||||
bool trop pauvre pour distinguer Program-only et exact
|
||||
No / Maybe / Yes sémantique moins explicite et héritée du generic protocol decoder
|
||||
priority inutile sans registry conflict policy
|
||||
entry code String crée un contrat textuel non consommé
|
||||
proof enum dépend en partie du futur contexte CORE
|
||||
```
|
||||
|
||||
### 7.3 Outcome
|
||||
|
||||
Candidat retenu :
|
||||
|
||||
```rust
|
||||
#[non_exhaustive]
|
||||
pub enum ProgramInstructionDecodeOutcome<Decoded> {
|
||||
Decoded(Decoded),
|
||||
Unsupported,
|
||||
}
|
||||
```
|
||||
|
||||
`decode` retourne un `ksp_core_lib::Result`. Un échec de validation/décodage est donc `Err`, pas un doublon `Failed` dans l'outcome.
|
||||
|
||||
`Ignored` n'est pas retenu : pour une capability qui décode une instruction en une valeur typée, une entrée connue doit soit produire la valeur, soit être unsupported, soit échouer. Une politique de filtrage ou de matérialisation n'appartient pas à ce contrat.
|
||||
|
||||
Le `Debug` de cet outcome, s'il est exposé, devra être borné et ne pas rendre automatiquement le contenu `Decoded`.
|
||||
|
||||
### 7.4 Decoder instruction
|
||||
|
||||
Candidat retenu :
|
||||
|
||||
```rust
|
||||
pub trait ProgramInstructionDecoder: Send + Sync {
|
||||
type Decoded;
|
||||
|
||||
fn program_ids(&self) -> &[Pubkey];
|
||||
|
||||
fn recognize(
|
||||
&self,
|
||||
instruction: &ProgramInstruction,
|
||||
) -> ProgramInstructionRecognition;
|
||||
|
||||
fn decode(
|
||||
&self,
|
||||
instruction: &ProgramInstruction,
|
||||
) -> Result<ProgramInstructionDecodeOutcome<Self::Decoded>>;
|
||||
}
|
||||
```
|
||||
|
||||
Propriétés recherchées :
|
||||
|
||||
```text
|
||||
input entièrement KSP-owned et déjà borné
|
||||
Program IDs typés
|
||||
aucun serde/JSON/codec
|
||||
aucun contexte transactionnel inventé
|
||||
aucun I/O
|
||||
aucun default method
|
||||
Send + Sync sur l'implémentation
|
||||
output concret possédé par la crate externe
|
||||
```
|
||||
|
||||
Le `program_ids()` peut contenir un `Pubkey` absent du registry Core. Il sert uniquement à déclarer la portée Program de l'implémentation; il n'introduit aucun enum central.
|
||||
|
||||
### 7.5 Associated output et composition
|
||||
|
||||
L'associated type est retenu précisément parce que `0.2.14` ne possède pas encore le payload canonique D3.
|
||||
|
||||
Une extension peut définir :
|
||||
|
||||
```text
|
||||
ExternalDecodedInstruction
|
||||
```
|
||||
|
||||
sans forcer KSP à utiliser `Any`, JSON ou une enum centrale.
|
||||
|
||||
Conséquence assumée : le trait n'est **pas** une promesse de registry hétérogène `dyn ProgramInstructionDecoder` sans fixer `Decoded`. `0.2.14` ne crée donc aucun registry runtime et n'annonce aucun object-safe erased decoder.
|
||||
|
||||
Quand la frontière DECODE/D3 réelle existera, KSP pourra introduire un contrat séparé de composition/erasure ou un envelope canonique réellement justifié, sans transformer cette foundation typée en faux format persistant.
|
||||
|
||||
## 8. Décisions sur les questions ouvertes du prompt
|
||||
|
||||
### Capability initiale
|
||||
|
||||
Retenu :
|
||||
|
||||
```text
|
||||
instruction decoder uniquement
|
||||
```
|
||||
|
||||
`ProgramAccountDecoder` est reporté : aucun input account Program-facing stable n'existe encore dans Interface/CORE.
|
||||
|
||||
### Input
|
||||
|
||||
Retenu :
|
||||
|
||||
```text
|
||||
&ProgramInstruction
|
||||
```
|
||||
|
||||
Aucun signature, slot, CPI path, logs, return data, balance delta ou transaction error n'est ajouté.
|
||||
|
||||
### Identity / descriptors / coverage
|
||||
|
||||
Reportés. Le trait lui-même représente la capability; `program_ids()` suffit au besoin immédiat. Nom/version d'implémentation et coverage matrix ne sont pas consommés par la foundation.
|
||||
|
||||
### Payload ouvert
|
||||
|
||||
Retenu : output associé à l'implémentation. Aucun payload canonique commun n'est créé.
|
||||
|
||||
### Proof / confidence
|
||||
|
||||
Reportés. `ExactMatch` est une assertion instruction-locale du decoder, pas une preuve persistée. Logs, balance deltas et audit contextuel appartiennent à CORE/DECODE ultérieur.
|
||||
|
||||
### Diagnostics
|
||||
|
||||
Aucun diagnostic Program dédié. `Error/Result` Core suffit à la foundation. Les erreurs d'une extension doivent rester bornées et ne pas recopier le payload hostile.
|
||||
|
||||
### Registry
|
||||
|
||||
Reporté. `0.2.14` prouve l'extension par une crate externe, pas par un `Vec<Box<dyn ...>>` runtime.
|
||||
|
||||
### Object safety
|
||||
|
||||
Aucun gate object-safety n'est requis pour la surface retenue puisque le registry hétérogène est explicitement hors scope. Le trait reste `Send + Sync`, mais son associated output est intentionnellement typé.
|
||||
|
||||
### `ProgramExecutionPreparer`
|
||||
|
||||
Reporté au premier vertical slice qui possède un intent technique réel. L'ancien bot démontre qu'un preparer pur est utile, mais son ancien plan mélangeait encore policy, wallet/signers, blockhash, simulation et post-replay.
|
||||
|
||||
### Logging
|
||||
|
||||
Aucun `ksp-logging-lib`, `tracing`, `constants.rs` ou `TRACING_TARGET` dans l'API déclarative.
|
||||
|
||||
### Sérialisation
|
||||
|
||||
Aucun `serde` ou `serde_json`.
|
||||
|
||||
## 9. Dependency graph cible
|
||||
|
||||
Le graphe normal final visé est :
|
||||
|
||||
```text
|
||||
ksp-program-api
|
||||
├── ksp-core-lib
|
||||
│ └── solana-pubkey
|
||||
└── ksp-interface-lib
|
||||
└── ksp-core-lib
|
||||
```
|
||||
|
||||
Dépendances de production interdites pour cette release :
|
||||
|
||||
```text
|
||||
ksp-program-lib
|
||||
ksp-onchain-transport-lib
|
||||
ksp-offchain-transport-lib
|
||||
ksp-config-lib
|
||||
ksp-wallet-lib
|
||||
ksp-store-api
|
||||
ksp-store-lib
|
||||
ksp-materializer-api
|
||||
ksp-materializer-lib
|
||||
ksp-logging-lib
|
||||
serde
|
||||
serde_json
|
||||
borsh
|
||||
wincode
|
||||
bincode
|
||||
solana-instruction
|
||||
reqwest
|
||||
tokio
|
||||
tonic
|
||||
tauri
|
||||
tracing
|
||||
```
|
||||
|
||||
Aucune nouvelle dépendance externe n'est nécessaire. L'audit externe ciblé de `pre.001` est donc `N/A` : le design ne dépend d'aucune nouvelle sémantique Solana, crate protocolaire ou registry dyn actuel.
|
||||
|
||||
## 10. Threat / API model
|
||||
|
||||
| Risque | Traitement de la foundation |
|
||||
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------|
|
||||
| payload hostile | input data déjà borné par Interface à `10_240` bytes; aucun Debug Program ne doit recopier ces bytes |
|
||||
| account vector hostile | input déjà borné à `255` metas; ordre et doublons restent visibles au decoder |
|
||||
| Program Pubkey inconnu | accepté; aucun lookup Core obligatoire |
|
||||
| closed-world enum | interdit; aucun `ProgramKind` central |
|
||||
| implémentation externe incorrecte | trait in-process non sandboxé; KSP ne prétend pas contenir un code tiers arbitraire |
|
||||
| panic externe | aucun default method Program; un panic d'une implémentation tierce reste un défaut de cette implémentation |
|
||||
| false `ExactMatch` | assertion du decoder; pas de proof contextuel inventé; futures compositions peuvent auditer les conflits |
|
||||
| strings non bornées | aucun nouveau String dans l'API candidate |
|
||||
| Debug leak | Recognition sans payload; outcome ne doit pas rendre automatiquement `Decoded`; input Interface a déjà un Debug borné |
|
||||
| status incohérent | `Failed` supprimé au profit de `Err`; outcome minimal réduit les combinaisons invalides |
|
||||
| priority ambiguity | aucun priority sans registry; les conflits sont reportés au contrat de composition futur |
|
||||
| registry conflicts | registry absent de la release |
|
||||
| object-safety impossible | aucune promesse de dyn hétérogène; associated output assumé |
|
||||
| accidental serialization | aucune dépendance/derive serde |
|
||||
| network/policy creep | aucune dépendance runtime et aucun client/wallet/context réseau dans les signatures |
|
||||
|
||||
## 11. Stratégie de tests
|
||||
|
||||
### Unit tests
|
||||
|
||||
Prévoir :
|
||||
|
||||
```text
|
||||
Recognition variants distincts
|
||||
outcome Decoded / Unsupported
|
||||
Debug outcome borné si implémenté
|
||||
unknown Program Pubkey
|
||||
empty/max-boundary ProgramInstruction déjà garanti par Interface et réutilisé sans recopie
|
||||
```
|
||||
|
||||
### Public API
|
||||
|
||||
Le canari `tests/public_api.rs` devra utiliser uniquement les exports crate-root de `ksp-program-api`.
|
||||
|
||||
### External implementation
|
||||
|
||||
Un test d'intégration doit construire une crate consommatrice séparée qui :
|
||||
|
||||
```text
|
||||
dépend uniquement de ksp-program-api pour le contrat Program
|
||||
implémente ProgramInstructionDecoder
|
||||
définit son propre type ExternalDecodedInstruction
|
||||
utilise un Pubkey opaque absent du registry Core
|
||||
reconnaît et décode une instruction
|
||||
n'accède à aucun module privé
|
||||
ne dépend pas de ksp-program-lib
|
||||
```
|
||||
|
||||
La technique exacte de crate fixture temporaire sera choisie lors de la tranche d'implémentation, sans ajouter de dépendance runtime.
|
||||
|
||||
### Dependency firewall
|
||||
|
||||
Canaris manifest/source pour interdire les dépendances listées en section 9.
|
||||
|
||||
### Release completeness
|
||||
|
||||
Verrouiller la surface décidée, l'absence de registry/preparer/payload canonique et l'absence de `pub mod`.
|
||||
|
||||
### Aucun smoke réseau
|
||||
|
||||
Aucun HTTP/WS/gRPC/live smoke n'est pertinent pour une API in-memory déclarative.
|
||||
|
||||
## 12. Sizing
|
||||
|
||||
Le scope initial du prompt contenait decoder, descriptors, registry, payload ouvert et possiblement execution preparation. L'audit montre que stabiliser ces surfaces ensemble obligerait à anticiper D3 et Execution.
|
||||
|
||||
Le gate réduit donc la release à :
|
||||
|
||||
```text
|
||||
crate + facade + firewall
|
||||
recognition + outcome minimal
|
||||
decoder instruction avec associated output
|
||||
external implementation canary
|
||||
hardening/completeness
|
||||
gate technique
|
||||
documentation
|
||||
publication
|
||||
```
|
||||
|
||||
Ce périmètre reste compatible avec une release clôturable dans une session et avec des tranches intermédiaires bornées.
|
||||
|
||||
## 13. Prévision souple recalibrée
|
||||
|
||||
### `pre.001` — Audit KSP + kbot3 + API model + sizing
|
||||
|
||||
Présente tranche : baseline, règles/architecture, héritage, ownership, API candidate, dependency graph, threat model, tests et scope réduit. Aucun code Program.
|
||||
|
||||
### `pre.002` — Scaffold `ksp-program-api` + façade + firewall
|
||||
|
||||
Créer la crate, l'ajouter au workspace, poser les réexports Core/Interface retenus, README/USAGE initiaux minimaux et canaris de dépendances/public facade. Aucun trait decoder encore.
|
||||
|
||||
### `pre.003` — Recognition + outcome minimal
|
||||
|
||||
Introduire `ProgramInstructionRecognition` et `ProgramInstructionDecodeOutcome<Decoded>` avec invariants et Debug sûr. Aucun descriptor/registry.
|
||||
|
||||
### `pre.004` — `ProgramInstructionDecoder` + external implementation
|
||||
|
||||
Introduire le trait `Send + Sync` avec associated output, `program_ids`, `recognize`, `decode`, puis prouver une implémentation depuis une crate externe avec Program Pubkey non enregistré.
|
||||
|
||||
### `pre.005` — Adversarial/API hardening + completeness
|
||||
|
||||
Verrouiller bounds/Debug/error safety, exact export inventory, absence de closed-world enum, absence de serde/codec/logging/runtime et scope négatif registry/preparer/payload canonique.
|
||||
|
||||
### `pre.006` — Gate technique final
|
||||
|
||||
Aucun développement fonctionnel. Audits Rust/Markdown, check, Clippy, `cargo test -p ksp-program-api`, workspace complet et graphes Cargo.
|
||||
|
||||
### `pre.007` — Réconciliation documentaire finale
|
||||
|
||||
README/USAGE, plan, validation, index et références durables réellement concernées. Aucun `CHANGELOG.md`, `ROADMAP.md` ou prompt suivant.
|
||||
|
||||
### `pre.008` — Préparation de publication minimale
|
||||
|
||||
Uniquement `Cargo.toml`, `CHANGELOG.md`, `ROADMAP.md`, prompt `0.3.1` et delta `pre.008`.
|
||||
|
||||
### `rel.001` — Publication stable
|
||||
|
||||
Mécanique de publication uniquement.
|
||||
|
||||
La numérotation reste souple : une anomalie peut insérer une tranche dédiée, mais les couloirs `gate technique -> réconciliation documentaire -> publication minimale` restent séparés.
|
||||
|
||||
## 14. Hors périmètre confirmé
|
||||
|
||||
```text
|
||||
ksp-program-lib
|
||||
decoder officiel Solana/SPL
|
||||
ProgramAccountDecoder / Event / ReturnData
|
||||
registry runtime
|
||||
priority/conflict policy
|
||||
descriptor identity/version/coverage
|
||||
payload canonique D3
|
||||
serde/JSON/Any
|
||||
proof/confidence contextuels
|
||||
CORE replay input
|
||||
Materializer / Store
|
||||
ProgramExecutionPreparer
|
||||
ExecutionPolicy / Execution
|
||||
Wallet / Transport / Config / Tauri
|
||||
IDL runtime / Anchor generic decoder
|
||||
```
|
||||
|
||||
## 15. Critères de clôture
|
||||
|
||||
La release pourra être publiée lorsque :
|
||||
|
||||
```text
|
||||
ksp-program-api existe
|
||||
le trait instruction-only est public et documenté
|
||||
une extension externe l'implémente avec un Pubkey non enregistré
|
||||
aucun enum central Program n'est requis
|
||||
aucun payload canonique prématuré n'est figé
|
||||
aucun registry/preparer n'est anticipé
|
||||
Core/Interface sont les seules dépendances KSP normales
|
||||
aucun runtime/codec/logging/serde n'est tiré
|
||||
public API / external implementation / dependency firewall / completeness passent
|
||||
cargo test -p ksp-program-api passe
|
||||
cargo test --workspace passe
|
||||
graphes Cargo inspectés
|
||||
documentation finale réconciliée
|
||||
```
|
||||
|
||||
## 16. Suite
|
||||
|
||||
Après `0.2.14`, la séquence active reste :
|
||||
|
||||
```text
|
||||
0.3.1 ksp-store-api + ksp-store-lib, RAW only
|
||||
0.3.2 ksp-interface-lib, wires génériques acquisition/CORE
|
||||
0.3.3 ksp-job-api + backfill
|
||||
0.3.4 application backfill/RAW
|
||||
```
|
||||
|
||||
Le payload DECODE, les materializers et la préparation d'exécution ne sont pas déplacés dans `0.3.1`; ils attendent les vertical slices qui démontreront leurs contrats réels.
|
||||
Reference in New Issue
Block a user