From 9148920f42d09610f7257037193a6ad894e6fb53 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Thu, 27 Aug 2026 23:33:01 +0200 Subject: [PATCH] v0.2.13-pre.001 --- Cargo.toml | 4 +- deltas/0.2.13/pre.001.md | 276 +++++++++++++ docs/000-README.md | 10 +- docs/plans/000-README.md | 5 +- docs/plans/020-V0_2_13_INTERFACE_PLAN.md | 479 +++++++++++++++++++++++ docs/validation/000-README.md | 5 +- docs/validation/016-V0_2_13_INTERFACE.md | 191 +++++++++ 7 files changed, 960 insertions(+), 10 deletions(-) create mode 100644 deltas/0.2.13/pre.001.md create mode 100644 docs/plans/020-V0_2_13_INTERFACE_PLAN.md create mode 100644 docs/validation/016-V0_2_13_INTERFACE.md diff --git a/Cargo.toml b/Cargo.toml index f280947..4d893e9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 302 +# version: 303 [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-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.2.12" +version = "0.2.13-pre.1" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.2.13/pre.001.md b/deltas/0.2.13/pre.001.md new file mode 100644 index 0000000..1e0e2e4 --- /dev/null +++ b/deltas/0.2.13/pre.001.md @@ -0,0 +1,276 @@ + + + +# Delta `0.2.13-pre.001` — audit/sizing Interface / wire foundation + +## 1. Base requise + +```text +v0.2.12 +``` + +Archive opérateur utilisée : `khadhroony-solana-project-v0.2.12.zip`, annoncée comme issue du tag Gitea stable. + +Vérifications d'identité : + +```text +workspace.package.version = 0.2.12 PASS à l'entrée +deltas/0.2.12/rel.001.md présent +prompts/018-V0_2_13_START_PROMPT.md présent +crates/ksp-interface-lib absent +crates/ksp-program-api absent +.git absent de l'archive +``` + +Le tag stable n'est donc pas revérifiable localement par Git. L'archive opérateur, le delta stable et la preuve opérateur fournie constituent l'autorité de reprise. + +## 2. Objectif + +Exécuter le gate obligatoire `pre.001` sans ouvrir encore la crate : relire règles/architecture, auditer Core/Transport, auditer l'héritage kbot3, vérifier les candidates externes actuelles, décider le premier lot wire, fixer ownership/bornes/threat model/dependency graph/tests, produire plan/validation et recalibrer la release. + +## 3. Décisions prises + +```text +crate cible ksp-interface-lib +premier lot ProgramAccountMeta + ProgramInstruction +orientation Program-facing passive +Pubkey ksp-core-lib::Pubkey, aucun wrapper parallèle +Program IDs fondamentaux restent ksp-core-lib +account metas ordre + doublons préservés +borne account metas 255 +borne instruction data 10_240 octets +fields privés pour préserver les invariants +serde OUT pour la foundation +borsh/bincode/wincode OUT sans protocole concret +solana-instruction référence normative, pas dépendance runtime +solana-loader-v3-interface reporté au vertical loader-v3 réel +Transport DTO refactor OUT +Program traits/decode/recognition 0.2.14, OUT de Interface +replay/CPI/logs/return-data/Core 0.3.2+, OUT de 0.2.13 +nouvelle dépendance externe aucune +network/logging runtime aucun +``` + +Les plafonds 255/10 KiB sont des bornes d'admission Interface dérivées des limites runtime Solana actuelles. Ils ne garantissent pas qu'une instruction donnée rentre dans une transaction top-level complète ; l'assembly transactionnel reste hors scope. + +## 4. Héritage kbot3 + +Archive auditée : `khadhroony-bot3_v0.5.3-pre.005-fix010.zip`. + +Verdict synthétique : + +```text +REPRENDRE ordered account meta; instruction program_id/accounts/data +REDESSINER wrappers String Pubkey/ProgramId; payload non borné +REPORTER decoder traits; recognition/proofs; replay/CPI/logs/return data; + canonical transaction; prepared execution/signers/policies +REJETER monolithe ks-lib; JSON/version/hash génériques par réflexe; + operation_code dans le contrat d'instruction passive +``` + +Aucun code kbot3 n'est porté par ce delta. + +## 5. Audit externe ciblé + +État observé le 27 août 2026 : + +```text +solana-instruction 3.5.0 + Instruction = program_id: Pubkey + Vec + Vec + solana-pubkey ^4.3.0 + serde/borsh/bincode/wincode optionnels + licence Anza SDK Apache-2.0 + +solana-program 4.1.0 + MAX_CPI_INSTRUCTION_ACCOUNTS = 255 + MAX_CPI_INSTRUCTION_DATA_LEN = 10 * 1024 + MAX_CPI_ACCOUNT_INFOS = 128 (unique account infos; non appliqué aux metas) + +solana-loader-v3-interface 8.1.1 + compatible avec solana-instruction ^3.5.0 / solana-pubkey ^4.3.0 observés + hors premier lot +``` + +Aucune nouvelle dépendance n'est justifiée par `pre.001`. + +## 6. Fichiers ajoutés + +```text +docs/plans/020-V0_2_13_INTERFACE_PLAN.md +docs/validation/016-V0_2_13_INTERFACE.md +deltas/0.2.13/pre.001.md +``` + +## 7. Fichiers modifiés + +```text +Cargo.toml +docs/000-README.md +docs/plans/000-README.md +docs/validation/000-README.md +``` + +`workspace.package.version` passe à `0.2.13-pre.1` conformément au workflow des prereleases non-fix. + +## 8. Fichiers supprimés + +```text +aucun +``` + +## 9. Fichiers volontairement inchangés + +```text +ROADMAP.md +CHANGELOG.md +prompts/018-V0_2_13_START_PROMPT.md +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/architecture/** +crates/** +config/** +.env.example +``` + +La roadmap/séquence/architecture possèdent déjà les frontières `0.2.13` / `0.2.14` / `0.3.2`. `pre.001` les confronte à la base réelle dans le nouveau plan sans les réécrire par duplication. `ROADMAP.md` et `CHANGELOG.md` restent hors du couloir de cette tranche. + +## 10. Audit interne exécuté + +Points confirmés : + +```text +Core réexporte Pubkey et possède les Program IDs fondamentaux +Core possède Error/Result communs +Transport possède encore les projections HTTP/WS/Yellowstone concrètes +aucun besoin de déplacer ces DTOs vers Interface en 0.2.13 +Interface ne doit pas dépendre de Program/Transport/Store/Wallet/Config +Program API pourra dépendre de Core + Interface en 0.2.14 +wires d'acquisition/CORE génériques restent réservés à 0.3.2+ +workspace n'a pas solana-instruction/borsh/wincode comme besoin Interface actuel +``` + +## 11. Threat model et tests décidés + +```text +accounts 255 accepté +accounts 256 refusé +data 10_240 accepté +data 10_241 refusé +empty accounts/data accepté +ordre + doublons préservés +unknown Program Pubkey accepté +Debug instruction résumé borné +payload hostile dans Debug/Error absent +serde hostile éliminé par absence de serde +malformed/discriminant N/A tant qu'aucun codec n'est retenu +panic/unwrap/expect/? audits/lints KSP +network smoke non requis +public API / external consumer requis +cargo tree / dependency firewall requis dès scaffold +``` + +## 12. Validations exécutées dans le sandbox + +Avant modification, sur l'archive stable extraite : + +```text +python3 scripts/audit_rust_workspace_rules.py PASS +python3 scripts/audit_markdown_tables.py ... deltas/0.2.13 PASS +``` + +La preuve opérateur fournie sur le checkout stable `0.2.12` établit : + +```text +cargo fmt --all PASS +Rust rules audit PASS +Markdown table audit PASS +cargo check --workspace PASS +cargo clippy --workspace --all-targets PASS +cargo test --workspace PASS +``` + +Après génération du présent overlay : + +```text +python3 scripts/audit_rust_workspace_rules.py PASS + General Rust rule audit clean + Rust export completeness audit 0 candidate(s) + KSP workspace Rust rule audit clean +python3 scripts/audit_markdown_tables.py ... deltas/0.2.13 PASS + tables / files 160 / 111 +``` + +## 13. Validations non exécutées dans ce sandbox + +```text +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test --workspace +cargo tree -p ksp-interface-lib --edges normal +cargo tree --duplicates +``` + +Cause : executable `cargo` absent du sandbox de préparation. `ksp-interface-lib` n'existe pas encore par contrat de `pre.001`, donc les graphes propres à la crate commenceront avec `pre.002`. + +Aucune commande non exécutée localement n'est déclarée PASS. + +## 14. Forecast souple recalibré + +### pre.001 — audit + héritage + frontières + sizing + +**Statut : livré par le présent delta.** + +### pre.002 — scaffold `ksp-interface-lib` + façade + firewall + +**Statut : prévu.** + +### pre.003 — `ProgramAccountMeta` + bornes communes + +**Statut : prévu.** + +### pre.004 — `ProgramInstruction` passif borné + +**Statut : prévu.** + +### pre.005 — adversarial + consumer externe + API/dependency hardening + +**Statut : prévu.** + +### pre.006 — gate technique final + +**Statut : prévu.** + +### pre.007 — réconciliation documentaire finale + +**Statut : prévu.** + +### pre.008 — préparation de publication minimale + +**Statut : prévu.** + +### rel.001 — publication stable + +**Statut : prévu.** + +Le second lot wire optionnel du forecast initial est supprimé : aucun second domaine ne justifie une tranche dans cette foundation. Le scope reste compatible avec une release/session. + +## 15. Questions ouvertes + +Aucune question bloquante pour `pre.002`. + +Les noms exacts des codes d'erreur et le détail final des accessors peuvent encore être ajustés dans `pre.003`/`pre.004` sans rouvrir l'ownership, les bornes ou le scope de release. + +## 16. Validation opérateur après application + +Exécuter : + +```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.13 +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test --workspace +``` + +`pre.002` ne commence qu'après retour du gate appliqué. diff --git a/docs/000-README.md b/docs/000-README.md index 7ef67e2..485b049 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation KSP @@ -55,7 +55,8 @@ docs/ │ ├── 016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md │ ├── 017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md │ ├── 018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md -│ └── 019-V0_2_12_SOL_PRICES_DESK_PLAN.md +│ ├── 019-V0_2_12_SOL_PRICES_DESK_PLAN.md +│ └── 020-V0_2_13_INTERFACE_PLAN.md ├── validation/ │ ├── 000-README.md │ ├── 001-V0_1_4_CONFIG_DESKTOP.md @@ -72,7 +73,8 @@ docs/ │ ├── 012-V0_2_9_YELLOWSTONE_GRPC.md │ ├── 013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md │ ├── 014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md -│ └── 015-V0_2_12_SOL_PRICES_DESK.md +│ ├── 015-V0_2_12_SOL_PRICES_DESK.md +│ └── 016-V0_2_13_INTERFACE.md └── rules/ ├── FILE_CONTRACTS.md ├── PROMPT_STRUCTURE.md @@ -89,7 +91,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é ## Documents de planification -Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert la release stable `0.2.2 — HTTP Accounts + Tokens + Cluster`. Son plan clôturé [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) conserve l'audit et l'implémentation des 22 wrappers typés, tandis que [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) enregistre les validations déterministes, les graphes Cargo et les deux smokes Devnet passés avant publication. Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) a ouvert la release stable `0.2.3 — HTTP Transactions`. Son plan clôturé [`plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) conserve l'audit et l'implémentation des 11 wrappers ; le réaudit [`validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`](validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md) confirme la complétude des 37 wrappers HTTP typés et [`validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](validation/006-V0_2_3_HTTP_TRANSACTIONS.md) enregistre les validations finales, graphes Cargo et deux smokes Devnet passés avant publication. Le prompt [`../prompts/009-V0_2_4_START_PROMPT.md`](../prompts/009-V0_2_4_START_PROMPT.md) a ouvert la release stable `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale`. Son plan clôturé [`plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md) conserve l’implémentation des 15 wrappers et la compliance `52/52 + 14/14`; la matrice finale [`validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md`](validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md) enregistre le réaudit SIMD/inventaire, les canaries globales et les preuves opérateur avant publication. Le prompt [`../prompts/010-V0_2_5_START_PROMPT.md`](../prompts/010-V0_2_5_START_PROMPT.md), finalisé par `0.2.4-pre.009-fix.001`, ouvre `0.2.5 — Wallet foundation` sur la base stable `v0.2.4`. Son plan historique clôturé [`plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md`](plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md) part du gate `pre.001` (héritage, threat model offline, VIEW/OWNER indépendants et niveau B read-only), puis matérialise la crate en `pre.002`, le wire/transcript en `pre.003`, les primitives Argon2id/XChaCha20-Poly1305 en `pre.004`, les payloads/create/open en `pre.005`, la persistence en `pre.006`, l'administration/signature en `pre.007` et les adapters transfer en `pre.008`. `pre.009` ferme l'audit adversarial/interoperability/compliance dans [`validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md`](validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md) avant la documentation finale `pre.010` ; `pre.010` finalise [`../crates/ksp-wallet-lib/README.md`](../crates/ksp-wallet-lib/README.md), [`../crates/ksp-wallet-lib/USAGE.md`](../crates/ksp-wallet-lib/USAGE.md), la spec, les graphes et la matrice ; `pre.010-fix.001`–`fix.003` ferment ensuite la mise à niveau Dalek et la normalisation Rust/audit structurel. `0.2.5-rel.001` publie la release stable et [`../prompts/011-V0_2_6_START_PROMPT.md`](../prompts/011-V0_2_6_START_PROMPT.md) ouvre `0.2.6 — Wallet Desk`. Le gate `0.2.6-pre.001` est conservé dans [`plans/013-V0_2_6_WALLET_DESK_PLAN.md`](plans/013-V0_2_6_WALLET_DESK_PLAN.md) : il réaudite Config Desk et les APIs finales, retient le gabarit desktop, fixe `std.wallet`, la composition Config/Wallet/HTTP/Logging, les secrets `KSP_SECRET_WALLET_PASS_*`, les frontières VIEW/OWNER et la trajectoire de validation. `pre.002`–`pre.014` matérialisent ensuite le shell Tauri, Config Wallet/composite, inventory, create/open, balance HTTP, import/export, metadata, rotations, révocation VIEW forte, compliance et polish desktop. `pre.015` fige le wire binaire `.kspwallet` V2, `pre.016` matérialise les APIs génériques/versionnées et le runtime V2, puis `pre.017` ajoute la migration explicite OWNER-authentifiée V1 -> V2. `pre.018` ferme le runtime Tauri packagé Config/resources et la documentation candidate ; `pre.018-fix.001` corrige le canari d'ownership Config, après quoi le gate workspace et le build final Linux sont verts. `pre.018-fix.002` renforce uniquement le contrat de reprise `0.2.7`. `0.2.6-rel.001` publie cette surface stable et [`../prompts/012-V0_2_7_START_PROMPT.md`](../prompts/012-V0_2_7_START_PROMPT.md) devient le prochain point d'entrée. Le gate `0.2.7-pre.001` ouvre la release WebSocket standard dans [`plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md`](plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md) ; la matrice normative puis finale est conservée dans [`validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md`](validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md). `0.2.7-pre.014` ferme la candidate technique/documentaire après validation 18/18, smoke WebSocket Devnet et audit du graphe Cargo ; `pre.014-fix.001` renforce uniquement le prompt suivant. `0.2.7-rel.001` publie `0.2.7 — WebSocket Solana standard` stable et [`../prompts/013-V0_2_8_START_PROMPT.md`](../prompts/013-V0_2_8_START_PROMPT.md) ouvre `0.2.8 — Helius LaserStream WebSocket`. Le plan historique clôturé [`plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md`](plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md) et la matrice finale [`validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md`](validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md) conservent la release stable `0.2.8 — Helius LaserStream WebSocket` publiée par `rel.001` : protocol `helius_laserstream`, sept familles standard Helius (`account/logs/program/root/signature/slot/slotsUpdates`), extension `transactionSubscribe`/`transactionUnsubscribe`, `block/vote` absents, heartbeat Ping 60 s, Config/secrets redacted, lifecycle adversarial et graphes Cargo finaux validés. [`../prompts/014-V0_2_9_START_PROMPT.md`](../prompts/014-V0_2_9_START_PROMPT.md) devient le contrat actif pour ouvrir Yellowstone gRPC standard/provider-neutral depuis le tag stable `v0.2.8`. La release stable `0.2.9` est conservée dans [`plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) et [`validation/012-V0_2_9_YELLOWSTONE_GRPC.md`](validation/012-V0_2_9_YELLOWSTONE_GRPC.md) : stratégie proto Apache + client KSP/Tonic, moteur N1, standard N2, Config V3, profils PublicNode Mainnet/Testnet authentifiés par `x-token` secret et smoke live `Subscribe` validé sur les deux réseaux. La candidate `0.2.10 — OrbitFlare Yellowstone gRPC` est réconciliée dans [`plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) et [`validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) : Devnet `http://devnet.rpc.orbitflare.com:10000`, License Key `ORBIT-*` injectée comme metadata secrète `x-token`, Config Transport V3 inchangée, live `Subscribe -> Slot + Ping` passé, aucun overlay provider et aucun heartbeat supplémentaire. La candidate `0.2.11 — Off-chain price transport` est réconciliée dans [`plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) et [`validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) : SOL/USD V1, huit adapters REST sans SDK provider, décimal exact, registry/availability/rate limits possédés par Off-chain Transport, Config `std.offchain_transport`, refresh individuel/multiple provider-neutral et smoke live keyless final `7/7` après correction CoinMarketCap V2. [`../crates/ksp-offchain-transport-lib/README.md`](../crates/ksp-offchain-transport-lib/README.md) et [`../crates/ksp-offchain-transport-lib/USAGE.md`](../crates/ksp-offchain-transport-lib/USAGE.md) deviennent les références durables ; la future `ksp-app-solprices-desk` reste une HID sans logique provider. La candidate `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk` est réconciliée dans [`plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md) et [`validation/015-V0_2_12_SOL_PRICES_DESK.md`](validation/015-V0_2_12_SOL_PRICES_DESK.md) : `ksp-app-solprices-desk` fournit le refresh manuel row/selected/all provider-neutral, états/timestamps exacts et diagnostics sûrs sur ports 1434/1435 ; Wallet Desk réutilise `MarketPriceService::refresh_all` pendant le refresh balance pour afficher une moyenne SOL/USD consumer-owned et l'équivalent USD exact, sans provider concret ni fallback Off-chain. Les gates finaux workspace/live et les trois builds Tauri Linux sont verts avant réconciliation documentaire. +Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert la release stable `0.2.2 — HTTP Accounts + Tokens + Cluster`. Son plan clôturé [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) conserve l'audit et l'implémentation des 22 wrappers typés, tandis que [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) enregistre les validations déterministes, les graphes Cargo et les deux smokes Devnet passés avant publication. Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) a ouvert la release stable `0.2.3 — HTTP Transactions`. Son plan clôturé [`plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) conserve l'audit et l'implémentation des 11 wrappers ; le réaudit [`validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`](validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md) confirme la complétude des 37 wrappers HTTP typés et [`validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](validation/006-V0_2_3_HTTP_TRANSACTIONS.md) enregistre les validations finales, graphes Cargo et deux smokes Devnet passés avant publication. Le prompt [`../prompts/009-V0_2_4_START_PROMPT.md`](../prompts/009-V0_2_4_START_PROMPT.md) a ouvert la release stable `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale`. Son plan clôturé [`plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md) conserve l’implémentation des 15 wrappers et la compliance `52/52 + 14/14`; la matrice finale [`validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md`](validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md) enregistre le réaudit SIMD/inventaire, les canaries globales et les preuves opérateur avant publication. Le prompt [`../prompts/010-V0_2_5_START_PROMPT.md`](../prompts/010-V0_2_5_START_PROMPT.md), finalisé par `0.2.4-pre.009-fix.001`, ouvre `0.2.5 — Wallet foundation` sur la base stable `v0.2.4`. Son plan historique clôturé [`plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md`](plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md) part du gate `pre.001` (héritage, threat model offline, VIEW/OWNER indépendants et niveau B read-only), puis matérialise la crate en `pre.002`, le wire/transcript en `pre.003`, les primitives Argon2id/XChaCha20-Poly1305 en `pre.004`, les payloads/create/open en `pre.005`, la persistence en `pre.006`, l'administration/signature en `pre.007` et les adapters transfer en `pre.008`. `pre.009` ferme l'audit adversarial/interoperability/compliance dans [`validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md`](validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md) avant la documentation finale `pre.010` ; `pre.010` finalise [`../crates/ksp-wallet-lib/README.md`](../crates/ksp-wallet-lib/README.md), [`../crates/ksp-wallet-lib/USAGE.md`](../crates/ksp-wallet-lib/USAGE.md), la spec, les graphes et la matrice ; `pre.010-fix.001`–`fix.003` ferment ensuite la mise à niveau Dalek et la normalisation Rust/audit structurel. `0.2.5-rel.001` publie la release stable et [`../prompts/011-V0_2_6_START_PROMPT.md`](../prompts/011-V0_2_6_START_PROMPT.md) ouvre `0.2.6 — Wallet Desk`. Le gate `0.2.6-pre.001` est conservé dans [`plans/013-V0_2_6_WALLET_DESK_PLAN.md`](plans/013-V0_2_6_WALLET_DESK_PLAN.md) : il réaudite Config Desk et les APIs finales, retient le gabarit desktop, fixe `std.wallet`, la composition Config/Wallet/HTTP/Logging, les secrets `KSP_SECRET_WALLET_PASS_*`, les frontières VIEW/OWNER et la trajectoire de validation. `pre.002`–`pre.014` matérialisent ensuite le shell Tauri, Config Wallet/composite, inventory, create/open, balance HTTP, import/export, metadata, rotations, révocation VIEW forte, compliance et polish desktop. `pre.015` fige le wire binaire `.kspwallet` V2, `pre.016` matérialise les APIs génériques/versionnées et le runtime V2, puis `pre.017` ajoute la migration explicite OWNER-authentifiée V1 -> V2. `pre.018` ferme le runtime Tauri packagé Config/resources et la documentation candidate ; `pre.018-fix.001` corrige le canari d'ownership Config, après quoi le gate workspace et le build final Linux sont verts. `pre.018-fix.002` renforce uniquement le contrat de reprise `0.2.7`. `0.2.6-rel.001` publie cette surface stable et [`../prompts/012-V0_2_7_START_PROMPT.md`](../prompts/012-V0_2_7_START_PROMPT.md) devient le prochain point d'entrée. Le gate `0.2.7-pre.001` ouvre la release WebSocket standard dans [`plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md`](plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md) ; la matrice normative puis finale est conservée dans [`validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md`](validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md). `0.2.7-pre.014` ferme la candidate technique/documentaire après validation 18/18, smoke WebSocket Devnet et audit du graphe Cargo ; `pre.014-fix.001` renforce uniquement le prompt suivant. `0.2.7-rel.001` publie `0.2.7 — WebSocket Solana standard` stable et [`../prompts/013-V0_2_8_START_PROMPT.md`](../prompts/013-V0_2_8_START_PROMPT.md) ouvre `0.2.8 — Helius LaserStream WebSocket`. Le plan historique clôturé [`plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md`](plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md) et la matrice finale [`validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md`](validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md) conservent la release stable `0.2.8 — Helius LaserStream WebSocket` publiée par `rel.001` : protocol `helius_laserstream`, sept familles standard Helius (`account/logs/program/root/signature/slot/slotsUpdates`), extension `transactionSubscribe`/`transactionUnsubscribe`, `block/vote` absents, heartbeat Ping 60 s, Config/secrets redacted, lifecycle adversarial et graphes Cargo finaux validés. [`../prompts/014-V0_2_9_START_PROMPT.md`](../prompts/014-V0_2_9_START_PROMPT.md) devient le contrat actif pour ouvrir Yellowstone gRPC standard/provider-neutral depuis le tag stable `v0.2.8`. La release stable `0.2.9` est conservée dans [`plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) et [`validation/012-V0_2_9_YELLOWSTONE_GRPC.md`](validation/012-V0_2_9_YELLOWSTONE_GRPC.md) : stratégie proto Apache + client KSP/Tonic, moteur N1, standard N2, Config V3, profils PublicNode Mainnet/Testnet authentifiés par `x-token` secret et smoke live `Subscribe` validé sur les deux réseaux. La candidate `0.2.10 — OrbitFlare Yellowstone gRPC` est réconciliée dans [`plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) et [`validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) : Devnet `http://devnet.rpc.orbitflare.com:10000`, License Key `ORBIT-*` injectée comme metadata secrète `x-token`, Config Transport V3 inchangée, live `Subscribe -> Slot + Ping` passé, aucun overlay provider et aucun heartbeat supplémentaire. La candidate `0.2.11 — Off-chain price transport` est réconciliée dans [`plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) et [`validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) : SOL/USD V1, huit adapters REST sans SDK provider, décimal exact, registry/availability/rate limits possédés par Off-chain Transport, Config `std.offchain_transport`, refresh individuel/multiple provider-neutral et smoke live keyless final `7/7` après correction CoinMarketCap V2. [`../crates/ksp-offchain-transport-lib/README.md`](../crates/ksp-offchain-transport-lib/README.md) et [`../crates/ksp-offchain-transport-lib/USAGE.md`](../crates/ksp-offchain-transport-lib/USAGE.md) deviennent les références durables ; la future `ksp-app-solprices-desk` reste une HID sans logique provider. La release stable `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk` est conservée dans [`plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md) et [`validation/015-V0_2_12_SOL_PRICES_DESK.md`](validation/015-V0_2_12_SOL_PRICES_DESK.md) : `ksp-app-solprices-desk` fournit le refresh manuel row/selected/all provider-neutral, états/timestamps exacts et diagnostics sûrs sur ports 1434/1435 ; Wallet Desk réutilise `MarketPriceService::refresh_all` pendant le refresh balance pour afficher une moyenne SOL/USD consumer-owned et l'équivalent USD exact, sans provider concret ni fallback Off-chain. Les gates finaux workspace/live et les trois builds Tauri Linux sont verts avant publication. `0.2.13 — Interface / wire foundation` est ouvert par [`../prompts/018-V0_2_13_START_PROMPT.md`](../prompts/018-V0_2_13_START_PROMPT.md) ; son gate de cadrage est conservé dans [`plans/020-V0_2_13_INTERFACE_PLAN.md`](plans/020-V0_2_13_INTERFACE_PLAN.md) avec la matrice [`validation/016-V0_2_13_INTERFACE.md`](validation/016-V0_2_13_INTERFACE.md). ## Spécifications de formats diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index f240737..61cbd5d 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -27,7 +27,8 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) — plan historique clôturé de la release stable `0.2.9 — Yellowstone gRPC standard/provider-neutral`, publiée par `rel.001`; il fixe le moteur N1, le standard N2, Config V3, le replay prudent et la validation PublicNode Mainnet/Testnet. - [`017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) — plan historique clôturé de la release stable `0.2.10 — OrbitFlare Yellowstone gRPC`; il conserve le Devnet gRPC gratuit, N1/N2 immuables, la License Key `x-token` et le smoke final `Slot + Ping`. - [`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 actif de `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk`; il fixe le gabarit 1434/1435, le composite Config, les DTO/commands provider-neutral, le threat model et la trajectoire d’intégration Wallet. +- [`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 actif de `0.2.13 — Interface / wire foundation`; il fixe le premier lot passif `ProgramAccountMeta` + `ProgramInstruction`, les bornes, le firewall Interface -> Core, l’héritage kbot3 retenu/rejeté et la frontière avec Program API/RAW/CORE. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/020-V0_2_13_INTERFACE_PLAN.md b/docs/plans/020-V0_2_13_INTERFACE_PLAN.md new file mode 100644 index 0000000..7367aaa --- /dev/null +++ b/docs/plans/020-V0_2_13_INTERFACE_PLAN.md @@ -0,0 +1,479 @@ + + + +# Plan `0.2.13` — Interface / wire foundation + +## 1. Base, autorité et nature de `pre.001` + +La release est ouverte exclusivement depuis l'archive opérateur `khadhroony-solana-project-v0.2.12.zip`, annoncée comme issue du tag stable `v0.2.12`. L'archive fournie ne contient pas de metadata `.git`; `git describe` n'est donc pas vérifiable dans le sandbox. Les marqueurs internes sont cohérents : + +```text +workspace.package.version = 0.2.12 +prompts/018-V0_2_13_START_PROMPT.md présent +deltas/0.2.12/rel.001.md présent +crates/ksp-interface-lib absent +crates/ksp-program-api absent +``` + +Le log opérateur joint à la reprise établit sur la base stable : + +```text +cargo fmt --all PASS +python3 scripts/audit_rust_workspace_rules.py PASS +python3 scripts/audit_markdown_tables.py ... PASS +cargo check --workspace PASS +cargo clippy --workspace --all-targets PASS +cargo test --workspace PASS +``` + +Dans le sandbox de préparation, `cargo` n'est pas installé. Les audits Python de la base ont été rejoués et sont propres ; aucune commande Cargo non exécutée localement n'est déclarée PASS. + +`0.2.13-pre.001` reste un gate de lecture/audit/sizing. Il ne crée pas encore `ksp-interface-lib` et ne porte aucun code de l'ancien dépôt. + +## 2. Décision de scope + +Le minimum retenu pour `0.2.13` est une foundation **Program-facing passive** : + +```text +ProgramAccountMeta +ProgramInstruction +bornes locales explicites sur account metas et data +façade crate-root explicite +Error/Result communs via ksp-core-lib +aucun serde/codec générique ajouté sans protocole réel +aucun comportement Program +``` + +Cette surface correspond à la forme fondamentale d'une invocation Solana : identité du programme, comptes ordonnés avec flags signer/writable, puis octets opaques. Elle prépare directement la future construction d'instructions de `ksp-program-api` sans absorber le modèle d'acquisition/replay qui appartient à `0.3.2+`. + +Le scope est volontairement réduit par rapport au forecast initial : `0.2.13` ne crée ni modèle canonique de transaction, ni replay input, ni logs/return-data génériques, ni CPI path, ni discriminant spécifique d'un programme tant qu'aucun vertical slice officiel ne le justifie. + +## 3. Règles et architecture confrontées à la base réelle + +Sources internes relues avant décision : + +```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 +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +ROADMAP.md +``` + +Les contraintes structurantes sont confirmées : + +```text +Core possède Pubkey, Error/Result et les Program IDs fondamentaux +Interface possède/reexporte de manière contrôlée les contrats wire officiels +Program API pourra dépendre de Core + Interface, jamais l'inverse +Transport reste propriétaire des DTOs RPC/WS/gRPC et ne dépend pas d'Interface +RAW/CORE n'exige aucun decoder Program +0.3.2 étendra Interface pour les wires génériques d'acquisition/CORE +pas de pub mod ; exports explicites depuis crate root +pas de dépendance externe sans usage réel +``` + +## 4. Inventaire interne stable pertinent + +### 4.1 Core + +| Surface stable | Owner actuel | Visibilité/consumer | Décision `0.2.13` | +|----------------------------------|----------------|-----------------------------------------------|---------------------------------------------------------------------| +| `Pubkey` | `ksp-core-lib` | public crate-root; consommé dans le workspace | réutiliser directement; aucun wrapper Interface | +| `Error` / `ErrorCode` / `Result` | `ksp-core-lib` | public crate-root; contrat commun | réutiliser pour les erreurs de bornes Interface | +| 18 Program IDs + registry/filter | `ksp-core-lib` | public crate-root | laisser Core; Interface ne duplique pas les identités fondamentales | + +Les anciens wrappers textuels `MdProgramId` / `MdPubkey` de kbot3 n'apportent donc aucune valeur à la frontière KSP actuelle : un `Pubkey` typé existe déjà et doit rester l'identité fondamentale. + +### 4.2 Transport + +| Type/famille observée | Owner actuel | Sémantique réelle | Décision | +|----------------------------------------------------------|-------------------------|--------------------------------------------------------|-------------------| +| `SolanaEncodedTransaction` | On-chain Transport HTTP | projection JSON-RPC encodée | laisser Transport | +| `SolanaConfirmedTransaction` / `SolanaBlockTransaction` | On-chain Transport HTTP | réponse RPC avec états wire/metadata provider | laisser Transport | +| `SolanaWireField` | On-chain Transport HTTP | distinction omitted/null/value propre aux réponses RPC | laisser Transport | +| `YellowstoneCompiledInstruction` | On-chain Transport gRPC | projection protobuf Yellowstone | laisser Transport | +| `YellowstoneInnerInstructions` / `YellowstoneReturnData` | On-chain Transport gRPC | metadata d'update Geyser | laisser Transport | +| `YellowstoneTransactionError` / `...Meta` | On-chain Transport gRPC | sémantique provider/protobuf | laisser Transport | + +Ces DTOs peuvent ressembler à de futurs objets génériques, mais ils représentent aujourd'hui des formes de transport concrètes. `0.2.13` ne les déplace pas et ne force aucune dépendance `Transport -> Interface`. + +### 4.3 Dépendances workspace + +La base possède déjà notamment : + +```text +solana-pubkey = ^4.3, default-features = false +serde = ^1.0 +serde_json = ^1.0 +``` + +Aucun `solana-instruction`, `borsh`, `wincode` ou crate d'interface Program n'est actuellement nécessaire au nouveau lot. Le graphe cible initial reste donc `Interface -> Core` uniquement. + +## 5. Audit d'héritage `khadhroony-bot3` + +Archive auditée : `khadhroony-bot3_v0.5.3-pre.005-fix010.zip`. + +Familles inspectées : + +```text +ks-lib/src/model/solana.rs +ks-lib/src/model/canonical_transaction.rs +ks-lib/src/model/replay.rs +ks-lib/src/decoder/api/contracts.rs +ks-lib/src/executor/api/execution.rs +familles decoder/* wire pertinentes comme points de comparaison uniquement +``` + +La matrice suivante porte sur les **concepts**, pas sur un portage de code : + +| Concept kbot3 | Verdict | Cible KSP | Raison | +|--------------------------------------------------------------|------------|----------------------------------|--------------------------------------------------------------------------------| +| account `{ pubkey, is_signer, is_writable }` ordonné | REPRENDRE | Interface `0.2.13` | forme passive fondamentale d'une instruction; retirer le naming execution | +| instruction `{ program_id, accounts, data }` | REPRENDRE | Interface `0.2.13` | forme officielle minimale; retirer `operation_code` et toute policy | +| `MdPubkey` / `MdProgramId` en `String` | REDESSINER | Core | remplacer par `ksp_core_lib::Pubkey` déjà possédé par Core | +| payload `Vec` non borné | REDESSINER | Interface `0.2.13` | ajouter admission bornée et Debug résumé | +| `DcApiInstructionDecoder` + recognition/outcomes/proofs | REPORTER | Program API `0.2.14` | comportement de reconnaissance/decode, interdit dans Interface | +| `MdInstructionPath` / parent / stack height | REPORTER | Interface/CORE `0.3.2+` | contexte d'acquisition/replay, pas nécessaire au builder Program minimal | +| logs / return data / tx failure / balance changes génériques | REPORTER | Interface/CORE `0.3.2+` | faits d'exécution/acquisition; ne pas préfigurer CORE | +| `MdCanonicalTransaction` + canonical JSON/hash | REPORTER | CORE series après `0.3.2` | modèle source-neutral large à redéfinir avec Store/CORE réels | +| `MdCoreInstructionReplayInput` | REPORTER | CORE/replay après RAW | contrat transversal trop large, dépend de données encore non possédées | +| Prepared plan, signers, fee payer, policies | REPORTER | Program API/Execution ultérieurs | responsabilité d'orchestration/exécution, pas wire passif | +| monolithe `ks-lib` + générations d'API coexistantes | REJETER | aucune | ownership flou et couplage vertical/horizontal à ne pas reproduire | +| version/hash/JSON génériques par réflexe | REJETER | aucune dans `0.2.13` | aucun contrat sérialisé ne justifie une enveloppe/version générique maintenant | + +Anti-patterns à ne pas reproduire : + +```text +wrappers Pubkey/ProgramId textuels alors qu'une primitive typée existe +serde dérivé sur tous les contrats sans frontière de sérialisation réelle +JSON Value comme échappatoire pour des formes structurelles futures +contrat replay géant utilisé comme point de rencontre de toutes les couches +operation_code/policy/signers mêlés à l'instruction passive +traits decoder dans la même crate que les wires +``` + +## 6. Audit externe actuel — 27 août 2026 + +L'audit externe est limité aux candidates réellement proches du lot retenu. + +| Candidate | Version actuelle observée | Contrat / graphe | Décision | +|------------------------------|---------------------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| +| `solana-instruction` | 3.5.0 | `Instruction { program_id: Pubkey, accounts: Vec, data: Vec }`; `solana-pubkey ^4.3.0`; codecs optionnels | référence normative; pas de dépendance runtime `0.2.13` | +| `solana-program` syscalls | 4.1.0 | `MAX_CPI_INSTRUCTION_ACCOUNTS = 255`; data `10 KiB`; account infos uniques `128` | source normative des plafonds d'admission initiaux; pas de dépendance | +| `solana-loader-v3-interface` | 8.1.1 | interface officielle; dépend `solana-instruction ^3.5.0` + `solana-pubkey ^4.3.0`; wincode optionnel | compatible en apparence mais hors premier lot; réauditer au vertical loader-v3 | + +Sources primaires/current utilisées : + +```text +https://docs.rs/solana-instruction/3.5.0/solana_instruction/struct.Instruction.html +https://docs.rs/solana-program/4.1.0/solana_program/syscalls/index.html +https://docs.rs/solana-loader-v3-interface/8.1.1/solana_loader_v3_interface/ +https://github.com/anza-xyz/solana-sdk +``` + +`solana-instruction` 3.5.0 est Apache-2.0 via le workspace Anza. Ses features `serde`, `borsh`, `bincode` et `wincode` sont optionnelles. La génération `solana-pubkey ^4.3.0` est cohérente avec la base KSP. + +La dépendance directe n'est néanmoins pas retenue maintenant : ses champs `Vec` publics ne permettent pas à KSP de garantir les bornes d'admission sur sa propre API, et aucun interop runtime ne requiert encore de convertir vers ce type. `DEP-KSP-005` impose de ne pas ajouter une dépendance seulement pour refléter une forme triviale que KSP doit de toute façon borner. + +## 7. Matrice de frontières + +| Concept/type | Owner cible | 0.2.13 ? | 0.2.14 ? | 0.3.2+ ? | Autorité / raison | +|-------------------------------------------------------------|----------------|----------|------------------|------------------------|-----------------------------------------------| +| `Pubkey` | Core | reuse | reuse | reuse | primitive fondamentale KSP déjà stable | +| Program IDs fondamentaux | Core | reuse | reuse | reuse | registry Core déjà stable | +| account meta d'instruction | Interface | OUI | consume | reuse | forme Solana officielle passive | +| instruction Program passive | Interface | OUI | consume | reuse | minimum nécessaire au futur preparer | +| codec/discriminant Program spécifique | Interface | NON | si vertical réel | selon besoin | aucun protocole concret dans foundation | +| instruction path / CPI ancestry | Interface/CORE | NON | NON requis | OUI | fait structurel d'acquisition/normalisation | +| logs / return data / tx failure / balance deltas génériques | Interface/CORE | NON | NON requis | OUI | surface RAW/CORE future | +| DTOs RPC/WS/Yellowstone existants | Transport | laisser | laisser | adapter plus tard | projection transport concrète | +| decoder identity/recognition/decode | Program API | NON | OUI audit | consume CORE plus tard | comportement extensible Program | +| implémentations officielles de programmes | Program Lib | NON | NON | plus tard | vertical slices distincts | +| RAW persistence | Store | NON | NON | `0.3.1` | architecture RAW | +| transaction/replay canonique générique | CORE | NON | NON | après `0.3.2` | doit être défini avec acquisition/Store réels | + +## 8. Surface API proposée + +Les noms restent ajustables jusqu'à implémentation, mais le contrat conceptuel est fermé : + +```rust +pub use ksp_core_lib::Pubkey; + +pub const MAX_PROGRAM_INSTRUCTION_ACCOUNTS: usize = 255; +pub const MAX_PROGRAM_INSTRUCTION_DATA_LEN: usize = 10 * 1024; + +pub struct ProgramAccountMeta { /* private */ } +pub struct ProgramInstruction { /* private */ } +``` + +Façade visée : + +```text +ProgramAccountMeta::writable(pubkey, is_signer) +ProgramAccountMeta::readonly(pubkey, is_signer) +ProgramAccountMeta::{pubkey,is_signer,is_writable} + +ProgramInstruction::try_new(program_id, accounts, data) -> ksp_core_lib::Result +ProgramInstruction::{program_id,accounts,data} +``` + +Décisions de contrat : + +- `Pubkey` est consommé via Core ; aucun `ProgramId` wrapper supplémentaire ; +- les comptes gardent exactement leur ordre et les doublons restent permis ; +- comptes vides et data vide restent valides ; +- aucune validation sémantique de Program ID, signer ou writable au-delà de la forme passive ; +- les champs restent privés afin d'empêcher la construction d'un état hors bornes ; +- la construction valide les longueurs sans cloner les vecteurs fournis ; +- `Debug` de `ProgramInstruction` doit résumer `program_id`, `account_count` et `data_len`, sans imprimer tout le payload ; +- pas de `serde::{Serialize, Deserialize}` dans la foundation : aucune persistence/IPC/wire sérialisée générique ne l'exige, et une dérive `Deserialize` naïve affaiblirait le gate de taille avant allocation ; +- aucun `borsh`, `bincode` ou `wincode` générique : les codecs arrivent avec un vrai protocole Program dans Interface ; +- pas de `format_version` artificiel tant qu'aucun format sérialisé KSP n'est défini. + +### 8.1 Bornes + +Les bornes initiales suivent les plafonds runtime Solana actuels : + +```text +account metas d'une instruction <= 255 +data d'une instruction <= 10_240 octets +``` + +Elles sont des **bornes d'admission Interface**, pas la promesse qu'une instruction seule rentrera dans toute transaction top-level. Les contraintes de message/transaction, comptes uniques, fee payer, blockhash et assembly appartiennent aux couches d'exécution ultérieures. + +### 8.2 Erreurs + +Le crate n'introduit pas un second type d'erreur. Les violations de borne utilisent `ksp_core_lib::Error/Result` avec codes Interface stables et contexte sûr limité aux longueurs/plafonds. Aucun octet du payload, compte arbitraire ou valeur externe n'est copié dans les diagnostics. + +Les codes exacts seront matérialisés avec la première primitive ; deux catégories suffisent conceptuellement : + +```text +invalid_program_instruction +program_instruction_limit_exceeded +``` + +Si la première implémentation démontre qu'une seule catégorie bornée suffit, ne pas créer la seconde par symétrie. + +## 9. Threat / robustness model + +| Risque | Décision | Canari prévu | +|-------------------------------------|------------------------------------------------------|------------------------------------------------------| +| data surdimensionnée | refus avant stockage/copie supplémentaire | `10_240` accepté; `10_241` refusé | +| collection accounts surdimensionnée | refus déterministe | `255` accepté; `256` refusé | +| conversion/index overflow | aucun cast étroit en foundation; comparer en `usize` | borne 255 + absence de casts unchecked | +| ordre/doublons accounts | préserver exactement; ne pas dédupliquer | ordre et doublon round-trip structurel via accessors | +| wire malformé | N/A : aucun decoder/codec dans le lot | aucun faux test; réouvrir au premier codec réel | +| enum/discriminant inconnu | N/A : aucun discriminant dans le lot | réouvrir au vertical Program | +| structures imbriquées pathologiques | N/A au-delà des deux Vec plates | bornes accounts/data suffisent pour ce lot | +| Debug volumineux | Debug résumé | payload sentinelle absent du rendu Debug | +| allocation/copie excessive | `try_new` consomme les Vec; pas de clone interne | canari structure/API + revue source | +| serde hostile | serde absent | dependency/public API canary | +| panic/unwrap/expect/? | interdits par règles/lints | audit Rust + Clippy workspace | +| Program ID inconnu | accepté : Pubkey opaque typé | canari avec Pubkey non registry | + +## 10. Dependency graph cible et firewall + +Cible de `0.2.13` : + +```text +ksp-interface-lib + -> ksp-core-lib + -> solana-pubkey ^4.3 +``` + +Interdictions : + +```text +ksp-interface-lib -X-> ksp-program-api +ksp-interface-lib -X-> ksp-program-lib +ksp-interface-lib -X-> ksp-onchain-transport-lib +ksp-interface-lib -X-> ksp-offchain-transport-lib +ksp-interface-lib -X-> ksp-config-lib +ksp-interface-lib -X-> ksp-store-* +ksp-interface-lib -X-> ksp-wallet-lib +ksp-interface-lib -X-> Tauri +ksp-interface-lib -X-> reqwest/tonic/tokio/network +``` + +Aucun logging runtime n'est attendu dans une crate de contrats passifs. `ksp-logging-lib` reste absent sauf comportement futur démontré. + +Validation Cargo prévue dès le scaffold : + +```bash +cargo tree -p ksp-interface-lib --edges normal +cargo tree --duplicates +``` + +Comme aucune nouvelle dépendance externe n'est retenue au gate, aucun doublon codec/Solana ne doit être créé par `pre.002`. + +## 11. Stratégie de tests + +### Tests unitaires privés + +Sous `unit_tests/` rattachés aux modules privés : + +```text +constructeurs account meta writable/readonly +bornes comptes 255/256 +bornes data 10_240/10_241 +empty accounts/data acceptés +ordre et doublons préservés +Pubkey inconnu accepté +Debug borné et payload absent +erreurs sans bytes ni valeur hostile +``` + +### Tests d'intégration `tests/` + +```text +public_api.rs consommation uniquement via crate-root +external_consumer.rs petit consumer/crate canary si le pattern workspace le permet +dependency_boundary.rs manifest/source firewall et absence de serde/codecs/network +release_completeness.rs inventaire exact de la surface 0.2.13 retenue +``` + +Aucun smoke réseau n'est requis. Aucun round-trip binaire/JSON n'est inventé sans codec réel. + +## 12. Hors scope explicite + +```text +ksp-program-api et tout trait decoder/preparer +ksp-program-lib +codec Program spécifique sans vertical réel +system/token/loader/metaplex instruction families +PDA seeds sans protocole concret +transaction/message/compiled instruction génériques d'acquisition +replay input / instruction path / CPI tree +logs / return data / transaction errors / balances génériques +Store/persistence +Transport refactor ou dépendance vers Interface +Wallet/Tauri/Config +serde/JSON canonical/hash +execution policy, signer selection, blockhash, simulation, send +``` + +## 13. Prévision souple recalibrée + +Le scope réduit permet de supprimer le second lot wire optionnel du forecast initial et de garder des tranches compatibles avec le budget KSP de 15–20 minutes de travail effectif. + +### pre.001 — audit + héritage + frontières + sizing + +**Statut : EN COURS / sortie du présent delta** + +Relire les règles/architectures, auditer Core/Transport, classer kbot3, auditer les candidates externes, retenir la surface instruction passive, fixer bornes/firewall/threat model/tests et créer plan/validation. + +### pre.002 — scaffold `ksp-interface-lib` + façade + firewall + +**Statut : prévu** + +Créer la crate, l'ajouter au workspace, poser `lib.rs` avec exports explicites, lints, README/USAGE initiaux et canaris manifest/firewall. Dépendance normale unique : `ksp-core-lib`. + +### pre.003 — `ProgramAccountMeta` + bornes communes + +**Statut : prévu** + +Matérialiser la primitive de compte ordonné, les constantes de borne, le modèle d'erreur Interface minimal et les unit/public canaries associés. Ne pas avancer `ProgramInstruction` si la tranche dépasse le budget. + +### pre.004 — `ProgramInstruction` passif borné + +**Statut : prévu** + +Ajouter l'instruction `{ program_id, accounts, data }`, constructeur validé, accessors, Debug résumé et canaris d'ordre/doublons/limites. Aucun serde/codec ou comportement Program. + +### pre.005 — adversarial + consumer externe + API/dependency hardening + +**Statut : prévu** + +Fermer les cas limites, surface crate-root, consumer externe, firewall source/manifest et graphes Cargo. Ne pas ajouter un second domaine wire opportuniste. + +### pre.006 — gate technique final + +**Statut : prévu** + +Exécuter workspace complet, canaris de complétude/public API/dependencies, `cargo tree` et audit final du scope exact. Aucun README/USAGE final ni préparation de publication. + +### pre.007 — réconciliation documentaire finale + +**Statut : prévu** + +Finaliser README/USAGE de la crate, plan, validation et références durables réellement affectées. Ne pas modifier `CHANGELOG.md`, `ROADMAP.md` ni le prompt suivant. + +### pre.008 — préparation de publication minimale + +**Statut : prévu** + +Préparer uniquement `prompts/019-V0_2_14_START_PROMPT.md`, `CHANGELOG.md`, `ROADMAP.md`, le bump prerelease mécanique et le delta. Aucun code/test/README/USAGE/plan/validation/architecture ne doit être rouvert. + +### rel.001 — publication stable + +**Statut : prévu** + +Passer `workspace.package.version` à `0.2.13`, rejouer le gate stable requis, publier le commit `v0.2.13-rel.001` puis le tag stable `v0.2.13`. + +## 14. Sizing et critère session + +| Tranche | Charge relative | Motif du découpage | +|---------|------------------|----------------------------------| +| pre.002 | petite | scaffold + firewall uniquement | +| pre.003 | petite | une primitive + bornes/erreurs | +| pre.004 | petite à moyenne | instruction + hardening local | +| pre.005 | moyenne | consumer + adversarial + graphes | +| pre.006 | gate | aucun développement fonctionnel | +| pre.007 | documentation | réconciliation séparée | +| pre.008 | publication prep | payload minimal séparé | + +Le scope paraît clôturable dans une release/session sans sacrifier les lanes de sortie. Si `pre.003` ou `pre.004` révèle qu'une dépendance/codec spécifique est indispensable, le gate doit être rouvert avant d'étendre le scope ; il ne faut pas réactiver automatiquement `pre.005` comme second lot wire. + +## 15. Gate `0.2.13-pre.001` + +À la sortie préparée : + +```text +base stable / prompt / rel confirmé +règles et architecture obligatoires relues +Core / Transport inventoriés +archive kbot3 auditée +matrice REPRENDRE/REDESSINER/REPORTER/REJETER produite +0.2.13 / 0.2.14 / 0.3.2 séparés +premier lot ProgramAccountMeta + ProgramInstruction +nouvelle dépendance externe aucune +threat model / tests / dependency graph définis +plan + validation créés +implementation Program absente +``` + +## 16. Gate attendu pour `pre.002` + +`pre.002` peut commencer si le présent delta est appliqué et le gate opérateur est vert. Il doit rester un scaffold strict : + +```text +nouvelle crate membre ksp-interface-lib +Cargo dépend uniquement de ksp-core-lib +lints workspace hérités +crate root explicite sans pub mod +README/USAGE initiaux +canari public API minimal +canari dependency firewall +aucun ProgramAccountMeta/ProgramInstruction fonctionnel si le scaffold suffit à la tranche +``` + +Aucune question ouverte ne bloque `pre.002`. diff --git a/docs/validation/000-README.md b/docs/validation/000-README.md index 1da1ef5..18b98e2 100644 --- a/docs/validation/000-README.md +++ b/docs/validation/000-README.md @@ -1,5 +1,5 @@ - + # Validations KSP @@ -23,4 +23,5 @@ Documents : - [`012-V0_2_9_YELLOWSTONE_GRPC.md`](012-V0_2_9_YELLOWSTONE_GRPC.md) — matrice finale de la release stable `0.2.9` : service Geyser courant, `Subscribe` standard, 7 unary, filtres/updates, dépendances/licence, replay/backpressure, Config V3 et smoke PublicNode Mainnet/Testnet. - [`013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) — matrice finale de la release stable `0.2.10` : Free Devnet, auth `x-token`, endpoint security, heartbeat standard, Config V3, smoke live `Slot + Ping` et invariant N1/N2 immuable. - [`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 active ouverte par `0.2.12-pre.001` : screen/features, DTO/commands, Config/composite, frontières provider-neutral, sécurité, Wallet integration, packaging Tauri et gates live/build. +- [`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 active ouverte par `0.2.13-pre.001` : ownership Interface/Core/Transport/Program, héritage kbot3, surface instruction passive, bornes/adversarial, façade publique et dependency firewall. diff --git a/docs/validation/016-V0_2_13_INTERFACE.md b/docs/validation/016-V0_2_13_INTERFACE.md new file mode 100644 index 0000000..c5583d0 --- /dev/null +++ b/docs/validation/016-V0_2_13_INTERFACE.md @@ -0,0 +1,191 @@ + + + +# Validation `0.2.13` — Interface / wire foundation + +## 1. Objet + +Cette matrice est ouverte par `0.2.13-pre.001`. Elle suit la première surface de `ksp-interface-lib` et enregistre les critères de fermeture sans transformer Interface en Program API ou en modèle RAW/CORE générique. + +Scope retenu : + +```text +ProgramAccountMeta +ProgramInstruction +Pubkey via ksp-core-lib +bornes comptes/data +aucun codec générique +aucun comportement Program +``` + +## 2. Baseline stable + +| Contrat | Attendu | Statut `pre.001` | +|----------------------------|------------------------------------------------|------------------------------------------| +| archive | `khadhroony-solana-project-v0.2.12.zip` stable | PASS marqueurs internes | +| workspace version entrée | `0.2.12` | PASS | +| `deltas/0.2.12/rel.001.md` | présent | PASS | +| prompt 018 | présent | PASS | +| `.git` | optionnel archive | ABSENT — tag non revérifiable localement | +| `ksp-interface-lib` entrée | absent | PASS | +| `ksp-program-api` entrée | absent | PASS | +| gate Cargo stable | fmt/check/clippy/test | PASS preuve opérateur | +| audits Python base | Rust + Markdown | PASS sandbox | + +## 3. Lecture et ownership internes + +| Famille | Constat | Décision | +|-----------------------------------|-----------------------------------------------------|-------------------------------------| +| Core `Pubkey` | public crate-root, `solana-pubkey ^4.3` | réutiliser; aucun wrapper Interface | +| Core Program IDs | 18 identités fondamentales + registry | laisser Core | +| Core Error/Result | contrat commun workspace | réutiliser pour Interface | +| HTTP transaction/block DTOs | projections JSON-RPC Transport | laisser Transport | +| Yellowstone instruction/meta DTOs | projections protobuf/Geyser | laisser Transport | +| Architecture 006 | Interface wire passive; Program comportement séparé | scope conforme | +| Roadmap 0.3.2 | wires génériques acquisition/CORE reportés | ne pas anticiper | + +## 4. Héritage kbot3 + +| Concept | Verdict | Preuve attendue dans KSP | +|-----------------------------------------|--------------------|--------------------------------------------| +| ordered account meta | REPRENDRE | `ProgramAccountMeta` sans naming execution | +| passive `{program_id, accounts, data}` | REPRENDRE | `ProgramInstruction` borné | +| string Pubkey/ProgramId wrappers | REDESSINER | Core `Pubkey` directement | +| unbounded payload | REDESSINER | borne + Debug résumé | +| decoder traits/recognition/proofs | REPORTER 0.2.14 | absents d'Interface | +| instruction path/CPI/replay context | REPORTER 0.3.2+ | absents de 0.2.13 | +| canonical transaction/replay JSON model | REPORTER/redéfinir | aucun portage | +| prepared execution policy/signers | REPORTER | absents d'Interface | +| monolithic `ks-lib` organization | REJETER | crate ownership séparé | + +## 5. Audit externe courant + +| Référence | État observé 2026-08-27 | Décision de validation | +|------------------------------|------------------------------------------------------------------|--------------------------------------------------------------| +| `solana-instruction` | 3.5.0; `Pubkey ^4.3.0`; codecs optionnels | parité conceptuelle requise, dépendance non requise | +| Solana `Instruction` | program_id + ordered AccountMeta + opaque bytes | forme cible exacte | +| Solana syscall bounds | 255 account metas CPI; data 10 KiB; 128 unique account infos CPI | 255/10 KiB = admission Interface; 128 non appliqué aux metas | +| `solana-loader-v3-interface` | 8.1.1; compatible générations observées | hors scope, réaudit au vertical réel | +| licence Anza SDK | Apache-2.0 | compatible si future dépendance réellement retenue | + +## 6. Matrice de frontière de release + +| Surface | Owner | 0.2.13 | 0.2.14 | 0.3.2+ | Statut | +|-----------------------------------|----------------|-----------|-----------------|----------------|---------| +| Pubkey / Program IDs fondamentaux | Core | reuse | reuse | reuse | FIXÉ | +| Program account meta | Interface | IMPLEMENT | consume | reuse | FIXÉ | +| Program instruction passive | Interface | IMPLEMENT | consume | reuse | FIXÉ | +| Program-specific codec/layout | Interface | OUT | si besoin réel | selon vertical | REPORTÉ | +| decoder/preparer traits | Program API | OUT | AUDIT/IMPLEMENT | consume | REPORTÉ | +| Transport provider DTOs | Transport | UNCHANGED | UNCHANGED | adapter future | FIXÉ | +| generic acquisition/replay wire | Interface/CORE | OUT | OUT | IMPLEMENT | REPORTÉ | +| RAW persistence | Store | OUT | OUT | `0.3.1`+ | REPORTÉ | + +## 7. API publique cible + +| Contrat | Attendu final `0.2.13` | Statut | +|----------------------|--------------------------------------------------------|------------------| +| crate | `ksp-interface-lib` membre workspace | TODO pre.002 | +| façade | exports explicites crate-root; aucun `pub mod` | TODO pre.002+ | +| Pubkey | réexport/usage contrôlé de Core; pas de type parallèle | TODO pre.002/003 | +| `ProgramAccountMeta` | private fields + writable/readonly + accessors | TODO pre.003 | +| `ProgramInstruction` | private fields + `try_new` + accessors | TODO pre.004 | +| account bound | `<= 255` | TODO pre.003/004 | +| data bound | `<= 10_240` | TODO pre.004 | +| serde | absent | FIXÉ pre.001 | +| generic codec | absent | FIXÉ pre.001 | +| Debug instruction | résumé borné, pas payload complet | TODO pre.004 | +| Error/Result | Core commun + codes Interface sûrs | TODO pre.003 | + +## 8. Robustness/adversarial + +| Cas | Attendu | Gate | +|------------------------------|--------------------------|-------------------------| +| 0 account | accepté | unit | +| 255 accounts | accepté | unit | +| 256 accounts | refus avant état valide | unit | +| 0 data | accepté | unit | +| 10_240 bytes | accepté | unit | +| 10_241 bytes | refus | unit | +| duplicate accounts | ordre/doublons conservés | unit + public API | +| unknown Program Pubkey | accepté | unit | +| hostile data marker in Debug | absent du rendu | unit | +| hostile data marker in Error | absent du rendu/context | unit | +| unchecked narrowing cast | absent | source audit/Clippy | +| malformed binary wire | N/A sans codec | ne pas inventer un test | +| unknown discriminant | N/A sans enum wire | réouvrir au vertical | +| serde hostile allocation | N/A serde absent | dependency canary | + +## 9. Dependency firewall + +| Dépendance depuis Interface | Attendu final | Preuve | +|-------------------------------------|----------------------------------------|------------------------| +| `ksp-core-lib` | AUTORISÉ / requis | manifest + cargo tree | +| `ksp-program-api` / Program Lib | INTERDIT | manifest/source canary | +| On-chain / Off-chain Transport | INTERDIT | manifest/source canary | +| Config / Wallet / Store / Tauri | INTERDIT | manifest/source canary | +| reqwest / tonic / tokio / websocket | INTERDIT | cargo tree + manifest | +| serde / serde_json | ABSENT en foundation | manifest + cargo tree | +| borsh / bincode / wincode | ABSENT en foundation | manifest + cargo tree | +| `solana-instruction` | ABSENT tant qu'interop réel non requis | manifest + cargo tree | + +Graphes attendus : + +```bash +cargo tree -p ksp-interface-lib --edges normal +cargo tree --duplicates +``` + +Si une nouvelle dépendance externe apparaît après `pre.001`, la présente matrice doit être rouverte avant acceptation. + +## 10. Tests de release + +| Famille | Attendu | Statut | +|--------------------------|------------------------------------------------|--------| +| unit tests privés | constructeurs/bornes/order/debug/errors | TODO | +| `tests/public_api.rs` | consommation crate-root uniquement | TODO | +| external consumer canary | surface utilisable hors modules privés | TODO | +| dependency boundary | firewall exact | TODO | +| release completeness | inventaire exact, aucun domaine supplémentaire | TODO | +| round-trip codec | aucun tant qu'aucun codec | N/A | +| network smoke | aucun pour crate wire pure | N/A | + +## 11. Gate technique final attendu + +Avant réconciliation documentaire : + +```text +cargo fmt --all PASS attendu +python3 scripts/audit_rust_workspace_rules.py PASS attendu +python3 scripts/audit_markdown_tables.py ... PASS attendu +cargo check --workspace PASS attendu +cargo clippy --workspace --all-targets PASS attendu +cargo test --workspace PASS attendu +cargo tree -p ksp-interface-lib --edges normal inspecté +cargo tree --duplicates inspecté +``` + +Aucun smoke réseau/live n'est exigé par défaut. + +## 12. État `pre.001` + +| Critère de sortie prompt | Statut | +|-------------------------------------------|-----------------------------------| +| sources internes obligatoires relues | PASS | +| base stable confirmée | PASS marqueurs + preuve opérateur | +| Core/Transport inventoriés | PASS | +| architecture 006 confrontée à la base | PASS | +| archive kbot3 auditée | PASS | +| matrice héritage | PASS | +| frontière 0.2.13 / 0.2.14 / 0.3.2 | PASS | +| premier lot exact décidé | PASS | +| ownership types | PASS | +| dépendances candidates auditables/bornées | PASS | +| threat model | PASS | +| test strategy | PASS | +| dependency graph cible | PASS | +| plan + validation | PASS | +| forecast/sizing | PASS | +| implémentation Program lourde | ABSENTE | + +Le passage à `pre.002` est autorisé après application du delta et validation opérateur. Le statut des items d'implémentation reste volontairement `TODO` jusqu'aux tranches correspondantes.