From 5e5ed6d1ab343d12c9aafaa51c9e93e867b68d29 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Fri, 28 Aug 2026 10:50:43 +0200 Subject: [PATCH] v0.2.14-pre.001 --- Cargo.toml | 4 +- deltas/0.2.14/pre.001.md | 201 +++++++ docs/plans/000-README.md | 3 +- docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md | 625 +++++++++++++++++++++ docs/validation/000-README.md | 3 +- docs/validation/017-V0_2_14_PROGRAM_API.md | 162 ++++++ 6 files changed, 994 insertions(+), 4 deletions(-) create mode 100644 deltas/0.2.14/pre.001.md create mode 100644 docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md create mode 100644 docs/validation/017-V0_2_14_PROGRAM_API.md diff --git a/Cargo.toml b/Cargo.toml index c0e3305..3d65070 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 312 +# version: 313 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.2.13" +version = "0.2.14-pre.1" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.2.14/pre.001.md b/deltas/0.2.14/pre.001.md new file mode 100644 index 0000000..3827a85 --- /dev/null +++ b/deltas/0.2.14/pre.001.md @@ -0,0 +1,201 @@ + + + +# Delta `0.2.14-pre.001` — audit Program API, héritage kbot3 et sizing + +## 1. Base requise + +Base directe attendue : + +```text +v0.2.13 +workspace.package.version = 0.2.13 +``` + +Sources obligatoires réellement disponibles à l'ouverture : + +```text +archive opérateur khadhroony-solana-project-v0.2.13.zip +archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +La metadata Git n'est pas incluse dans l'archive opérateur; le tag `v0.2.13` ne peut donc pas être interrogé localement. La version Cargo, `deltas/0.2.13/rel.001.md`, le prompt 019 et la surface Interface publiée concordent avec la base stable attendue. + +Commit attendu : + +```text +v0.2.14-pre.001 +``` + +## 2. Objectif + +Ouvrir `0.2.14 — Program API foundation` uniquement par le gate prévu : + +```text +lecture règles + architecture +audit Core + Interface stables +audit historique kbot3 réel +matrice d'héritage +ownership +API candidate +threat/API model +dependency graph +stratégie de tests +sizing et prévision souple recalibrée +``` + +Aucun scaffold `ksp-program-api`, decoder concret, registry runtime ou execution preparer n'est ajouté dans cette livraison. + +## 3. Décisions principales + +Le scope est réduit à une foundation instruction-only : + +```text +ProgramInstructionRecognition +ProgramInstructionDecodeOutcome +ProgramInstructionDecoder avec associated output +``` + +Le candidat trait utilise : + +```text +&ProgramInstruction +&[Pubkey] +ksp_core_lib::Result +Send + Sync +``` + +L'output concret appartient à l'implémentation externe ou au futur `ksp-program-lib`. + +Sont explicitement reportés : + +```text +payload canonique D3 +registry runtime hétérogène +identity/version/coverage génériques +diagnostics/proofs Program dédiés +ProgramAccountDecoder / Event / ReturnData +ProgramExecutionPreparer +``` + +Le design n'ajoute aucune dépendance externe et ne requiert donc aucun audit web/Solana supplémentaire en `pre.001`. + +## 4. Héritage kbot3 + +L'archive historique a été réellement extraite et les contrats prioritaires ont été relus. + +Conclusions : + +```text +REPRENDRE séparation recognition/decode, trait instruction, Send+Sync, préparation pure conceptuelle +REDESSINER recognition, outcomes, execution capability/prepared plan +REPORTER identity/version, coverage, diagnostics, proofs, replay context, decoded event, registry, preparer +REJETER Program IDs/Pubkeys String, generic JSON payload, generic protocol monolith, executor, policy dans Program, ks-lib monolithique +``` + +Les decoders Solana Core, SPL Token et SPL Token-2022 confirment que l'ancien trait contextualisé dépendait réellement de signature/slot/path/transaction status/hash et JSON. Ces champs appartiennent aux futures couches CORE/DECODE et ne sont pas reconstruits dans Program API. + +## 5. Sizing recalibré + +Prévision active : + +```text +pre.001 audit/design/sizing +pre.002 scaffold + facade + dependency firewall +pre.003 recognition + outcome +pre.004 decoder trait + external implementation +pre.005 adversarial/API hardening + completeness +pre.006 gate technique final +pre.007 réconciliation documentaire +pre.008 préparation de publication minimale +rel.001 publication stable +``` + +Registry, canonical payload et execution preparation ne sont plus des tranches de `0.2.14`. + +## 6. Fichiers ajoutés + +```text +docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md +docs/validation/017-V0_2_14_PROGRAM_API.md +deltas/0.2.14/pre.001.md +``` + +## 7. Fichiers modifiés + +```text +Cargo.toml +docs/plans/000-README.md +docs/validation/000-README.md +``` + +## 8. Fichiers supprimés + +```text +aucun +``` + +## 9. Version Cargo + +La prerelease non-fix synchronise : + +```text +workspace.package.version = 0.2.14-pre.1 +``` + +Aucune crate Program n'existe encore; le changement Cargo sert uniquement à identifier la tranche `pre.001` conformément au workflow. + +## 10. Validations exécutées pendant la préparation + +Le journal opérateur fourni à l'ouverture sur la base stable `v0.2.13` montre un baseline complet vert avant application de ce delta, notamment audits Rust/Markdown, `cargo check --workspace`, Clippy, tests ciblés des crates et `cargo test --workspace`. Cette preuve de base ne remplace pas le gate après application. + +Dans l'environnement de génération du présent overlay, les contrôles statiques suivants ont été réellement exécutés après modification : + +```text +python3 scripts/audit_rust_workspace_rules.py + General Rust rule audit: clean + Rust export completeness audit: 0 candidate(s) + KSP workspace Rust rule audit: clean + +python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.14 + Markdown table audit: clean (170 tables, 116 files) +``` + +`cargo` n'est pas installé dans l'environnement de génération utilisé pour préparer l'archive. Les commandes Cargo de validation après application n'ont donc pas été rejouées ici et ne sont pas déclarées PASS. + +## 11. Validations non requises dans cette tranche + +```text +cargo test -p ksp-program-api crate encore absente +cargo tree -p ksp-program-api crate encore absente +smokes réseau/live hors scope d'une API déclarative +``` + +## 12. Questions ouvertes + +Aucune question ne bloque le passage à `pre.002`. + +Les sujets suivants restent ouverts volontairement pour des releases ultérieures, pas pour compléter `0.2.14` : + +```text +canonical DECODE/D3 payload +runtime registry / conflict policy / erased composition +processor identity/version durable +coverage descriptors +contextual proofs/diagnostics +ProgramExecutionPreparer exact +``` + +## 13. Application et validation opérateur + +Après application de l'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 +``` + +Aucun développement fonctionnel Program ne doit être ajouté à ce delta. diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index 4ff4372..bd79034 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -29,6 +29,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) — plan historique clôturé de `0.2.11 — Off-chain price transport`; SOL/USD V1, huit providers REST sans SDK, registry/availability/rate limits Off-chain et Config `std.offchain_transport`. - [`019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](019-V0_2_12_SOL_PRICES_DESK_PLAN.md) — plan historique clôturé de `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk`; il conserve le gabarit 1434/1435, le composite Config, les DTO/commands provider-neutral, l’intégration Wallet minimale et les gates live/build finaux. - [`020-V0_2_13_INTERFACE_PLAN.md`](020-V0_2_13_INTERFACE_PLAN.md) — plan candidat réconcilié de `0.2.13 — Interface / wire foundation`; il fixe la surface finale `ProgramAccountMeta` + `ProgramInstruction`, les bornes `255` / `10_240`, le firewall Interface -> Core, les canaris de complétude/consumer externe et la frontière avec Program API/RAW/CORE. +- [`021-V0_2_14_PROGRAM_API_PLAN.md`](021-V0_2_14_PROGRAM_API_PLAN.md) — plan actif de `0.2.14 — Program API foundation`, ouvert par `pre.001`; il fixe une foundation instruction-only ouverte, un output typé par associated type, le report du payload canonique D3, du registry runtime et de `ProgramExecutionPreparer`, ainsi que le canari d’implémentation externe. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md b/docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md new file mode 100644 index 0000000..7f7e8cd --- /dev/null +++ b/docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md @@ -0,0 +1,625 @@ + + + +# 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), + 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>; +} +``` + +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>` 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` 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. diff --git a/docs/validation/000-README.md b/docs/validation/000-README.md index 4469fad..ce05b5d 100644 --- a/docs/validation/000-README.md +++ b/docs/validation/000-README.md @@ -1,5 +1,5 @@ - + # Validations KSP @@ -25,3 +25,4 @@ Documents : - [`014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) — matrice historique clôturée de `0.2.11` : SOL/USD multi-provider, numeric safety, rate limiting/availability, Config capability-aware et smoke keyless final `7/7`. - [`015-V0_2_12_SOL_PRICES_DESK.md`](015-V0_2_12_SOL_PRICES_DESK.md) — matrice historique clôturée de `0.2.12` : screen/features, DTO/commands, Config/composite, frontières provider-neutral, sécurité, Wallet integration, packaging Tauri et gates live/build. - [`016-V0_2_13_INTERFACE.md`](016-V0_2_13_INTERFACE.md) — matrice candidate finale de `0.2.13` : ownership Interface/Core/Transport/Program, surface passive, bornes/adversarial, façade publique exacte, consumer externe, release completeness, dependency firewall et gate technique `pre.006` intégralement vert. +- [`017-V0_2_14_PROGRAM_API.md`](017-V0_2_14_PROGRAM_API.md) — matrice active de `0.2.14 — Program API foundation`; elle suit le gate d’audit `pre.001`, l’open-world external implementation canary, le firewall Core/Interface et les gates techniques/documentaires futurs. diff --git a/docs/validation/017-V0_2_14_PROGRAM_API.md b/docs/validation/017-V0_2_14_PROGRAM_API.md new file mode 100644 index 0000000..f2c7634 --- /dev/null +++ b/docs/validation/017-V0_2_14_PROGRAM_API.md @@ -0,0 +1,162 @@ + + + +# Validation `0.2.14` — Program API foundation + +## 1. Objet + +Cette matrice est ouverte par `0.2.14-pre.001`. Elle distingue les preuves déjà acquises par le gate d'audit des validations futures qui ne doivent pas être déclarées PASS avant exécution. + +Le scope validé par `pre.001` est une foundation instruction-only avec output associé à l'implémentation. Registry runtime, payload canonique D3 et `ProgramExecutionPreparer` sont explicitement reportés. + +## 2. Gate `pre.001` + +| Critère | Statut | Preuve | +|----------------------------|---------|--------------------------------------------------------------------------------| +| base stable `0.2.13` | PASS | Cargo `0.2.13`, `rel.001` et prompt 019 présents | +| metadata Git/tag | N/A | archive opérateur sans metadata Git exploitable | +| `ksp-interface-lib` stable | PASS | surface et canaris `0.2.13` relus | +| `ksp-program-api` absent | PASS | aucun répertoire de crate sur la base | +| `ksp-program-lib` absent | PASS | aucun répertoire de crate sur la base | +| archive kbot3 disponible | PASS | archive historique réellement extraite et auditée | +| règles Program/API relues | PASS | règles KSP/Dependencies/Workflow prescrites relues | +| architecture durable relue | PASS | `002` à `010`, avec `006-WIRE_AND_PROGRAM.md` central | +| audit Core + Interface | PASS | input `ProgramInstruction` jugé suffisant pour instruction-only | +| matrice héritage kbot3 | PASS | `REPRENDRE / REDESSINER / REPORTER / REJETER` dans le plan 021 | +| ownership matrix | PASS | Core/Interface/Program/CORE/Execution séparés dans le plan 021 | +| API candidate | PASS | recognition + generic outcome + associated-output decoder | +| payload canonique | REPORTÉ | aucune représentation D3 inventée en `0.2.14` | +| registry runtime | REPORTÉ | aucune composition dyn hétérogène dans la release | +| execution preparer | REPORTÉ | attend un intent technique réel de vertical slice | +| dependency graph | PASS | cible Core + Interface uniquement | +| threat/API model | PASS | payload, Debug, open-world, externe hostile, exactness et scope creep couverts | +| stratégie de tests | PASS | unit/public/external/firewall/completeness, aucun live smoke | +| sizing | PASS | release réduite à decoder instruction-only et couloirs de fermeture séparés | + +## 3. Décisions API à prouver par le code + +| Contrat | Décision `pre.001` | Gate futur | +|--------------------------------------------|---------------------------------------------------------|--------------------------------| +| `ProgramInstructionRecognition` | `NoMatch / ProgramMatch / ExactMatch`, non exhaustif | `pre.003` | +| `ProgramInstructionDecodeOutcome` | `Decoded(Decoded) / Unsupported`, non exhaustif | `pre.003` | +| decoder failure | `ksp_core_lib::Result`, aucun statut `Failed` parallèle | `pre.003` / `pre.004` | +| `ProgramInstructionDecoder` | `Send + Sync`, associated `Decoded` | `pre.004` | +| input | `&ProgramInstruction` | `pre.004` | +| Program IDs déclarés | `&[Pubkey]`, opaque et open-world | `pre.004` | +| output | type concret de l'implémentation | `pre.004` | +| registry dyn | absent | completeness `pre.005` | +| identity/version/coverage | absents | completeness `pre.005` | +| Program Account/Event/ReturnData decoder | absents | completeness `pre.005` | +| ProgramExecutionPreparer | absent | completeness `pre.005` | +| serde/JSON/codec | absents | firewall `pre.002` / `pre.005` | +| runtime/logging | absents | firewall `pre.002` / `pre.005` | + +## 4. External implementation canary + +La preuve finale doit utiliser une crate consommatrice séparée et vérifier : + +```text +implementation de ProgramInstructionDecoder +associated output défini hors KSP +Program Pubkey absent du registry Core +construction de ProgramInstruction via la facade publique retenue +recognition ProgramMatch ou ExactMatch déterministe +decode vers Decoded(external value) +aucun ksp-program-lib +aucun module privé +``` + +Ce canari remplace toute affirmation documentaire non exécutable d'extensibilité. + +## 5. Dependency firewall cible + +Graphe normal attendu : + +```text +ksp-program-api +├── ksp-core-lib +│ └── solana-pubkey +└── ksp-interface-lib + └── ksp-core-lib +``` + +Interdits : + +```text +Transport +Store +Wallet +Materializer +Config +Tauri +ksp-program-lib +ksp-logging-lib +serde / serde_json +borsh / wincode / bincode +solana-instruction +reqwest / tokio / tonic +tracing +``` + +## 6. Threat/API gates futurs + +| Gate | Attendu | Statut initial | +|---------------------------|--------------------------------------------------------------------------|----------------| +| unknown Program Pubkey | utilisable sans registry Core | PENDING | +| max Interface input | decoder consomme l'input déjà borné sans nouvelle allocation obligatoire | PENDING | +| malformed program payload | `Err` ou `Unsupported` selon contrat, sans payload dans l'erreur | PENDING | +| Debug recognition | aucun payload | PENDING | +| Debug outcome | contenu `Decoded` non rendu automatiquement | PENDING | +| default methods | aucun default method susceptible de masquer panic/policy | PENDING | +| closed-world enum | aucun inventaire central de Program kinds | PENDING | +| serde accidental | aucune dependency/derive | PENDING | +| runtime creep | aucun réseau, wallet, store, logging ou UI | PENDING | +| external output | type tiers accepté sans `Any`/JSON central | PENDING | +| dyn claim | aucune assertion d'object-safety hétérogène dans cette release | PENDING | + +## 7. Gates de fermeture + +### Gate technique final + +À exécuter dans la prerelease dédiée : + +```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 +cargo test -p ksp-program-api +cargo test --workspace +cargo tree -p ksp-program-api --edges normal +cargo tree --duplicates +``` + +### Réconciliation documentaire + +Doit fermer : + +```text +ksp-program-api README/USAGE +plan 021 +validation 017 +indexes/références durables concernées +``` + +Sans `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant. + +### Préparation de publication + +Doit rester limitée à : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompt de démarrage 0.3.1 +delta de la prerelease +``` + +## 8. Statut courant + +`0.2.14-pre.001` ne matérialise aucune crate Program et n'exécute aucun decoder. Le gate de design est considéré cohérent lorsque les validations statiques de l'overlay passent; toutes les preuves fonctionnelles restent `PENDING` jusqu'aux tranches correspondantes.