khadhroony-solana-project/docs/validation/017-V0_2_14_PROGRAM_API.md

Validation 0.2.14 — Program API foundation

1. Objet

Cette matrice, ouverte par 0.2.14-pre.001, est réconciliée par pre.007 après fermeture intégralement verte du gate technique pre.006. Elle conserve l'historique des preuves par tranche et la surface candidate finale.

Le scope final reste 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	PASS pre.003
ProgramInstructionDecodeOutcome<Decoded>	Decoded(Decoded) / Unsupported, non exhaustif	PASS pre.003
decoder failure	ksp_core_lib::Result, aucun statut Failed parallèle	pre.003 / pre.004
ProgramInstructionDecoder	Send + Sync, associated Decoded	PASS pre.004
input	&ProgramInstruction	PASS pre.004
Program IDs déclarés	&[Pubkey], opaque et open-world	PASS pre.004
output	type concret de l'implémentation	PASS 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 matérialisée en pre.004 utilise une crate d'intégration consommatrice séparée et vérifie :

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é. Son gate opérateur pre.004 est confirmé intégralement vert.

5. Dependency firewall cible

Graphe normal attendu :

ksp-program-api
├── ksp-core-lib
│   └── solana-pubkey
└── ksp-interface-lib
    └── ksp-core-lib

Interdits :

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	PASS pre.004
max Interface input	decoder consomme l'input déjà borné sans nouvelle allocation obligatoire	PASS pre.005
malformed program payload	Err ou Unsupported; aucun echo n'est ajouté par le contrat	PASS pre.005
Debug recognition	aucun payload	PASS
Debug outcome	contenu Decoded non rendu automatiquement	PASS
default methods	aucun default method susceptible de masquer panic/policy	PASS pre.004
closed-world enum	aucun inventaire central de Program kinds	PASS pre.004
serde accidental	aucune dependency/derive	PASS pre.004
runtime creep	aucun réseau, wallet, store, logging ou UI	PASS pre.004
external output	type tiers accepté sans Any/JSON central	PASS pre.004
dyn claim	aucune assertion d'object-safety hétérogène dans cette release	PASS pre.004

7. Gates de fermeture

Gate technique final

Le gate technique dédié pre.006 est fermé intégralement vert. Les commandes de référence étaient :

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 -p ksp-logging-lib --test ownership
cargo test --workspace
cargo tree -p ksp-program-api --edges normal
cargo tree --duplicates

Réconciliation documentaire

pre.007 ferme :

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 à :

Cargo.toml
CHANGELOG.md
ROADMAP.md
prompt de démarrage 0.3.1
delta de la prerelease

8. Gate opérateur pre.002

Le gate fourni le 28 août 2026 est intégralement vert :

cargo fmt --all                                      PASS
audit Rust général / exports / workspace             PASS
audit Markdown                                       PASS — 170 tables / 119 fichiers
cargo check --workspace                              PASS
cargo clippy --workspace --all-targets               PASS
cargo test -p ksp-program-api                        PASS — 4 tests d'intégration
cargo test --workspace                               PASS
cargo tree -p ksp-program-api --edges normal         PASS — Core + Interface uniquement
cargo tree --duplicates                              exécuté, inventaire workspace observé

Ce gate autorise l'ouverture de pre.003.

9. État préparé pre.003

Critère	Statut	Preuve
ProgramInstructionRecognition	PASS	enum non exhaustif NoMatch / ProgramMatch / ExactMatch
ProgramInstructionDecodeOutcome<T>	PASS	enum non exhaustif Decoded(T) / Unsupported
absence de Failed / Ignored	PASS	échec réservé au futur Result; aucun statut parallèle
Debug recognition	PASS	enum sans payload; Debug dérivé
Debug outcome	PASS	implémentation manuelle sans T: Debug, valeur Decoded non rendue
dépendances normales	PASS	manifest inchangé : ksp-core-lib + ksp-interface-lib
module public	PASS	aucun pub mod; exports crate-root uniquement
ProgramInstructionDecoder	ABSENT	réservé à pre.004
registry / descriptor / payload D3	ABSENT	hors scope maintenu
serde / codec / logging / runtime	ABSENT	dependency firewall maintenu

Le gate opérateur pre.003 est confirmé intégralement vert : audits Rust/Markdown, check, Clippy, tests ciblés, workspace complet et graphes Cargo passent.

10. Gate opérateur pre.003

cargo fmt --all                                      PASS
audit Rust général / exports / workspace             PASS
audit Markdown                                       PASS — 171 tables / 120 fichiers
cargo check --workspace                              PASS
cargo clippy --workspace --all-targets               PASS
cargo test -p ksp-program-api                        PASS — 8 tests Rust
cargo test --workspace                               PASS
cargo tree -p ksp-program-api --edges normal         PASS — Core + Interface uniquement
cargo tree --duplicates                              exécuté, inventaire workspace observé

Ce gate autorise l'ouverture de pre.004.

11. État préparé pre.004

Critère	Statut	Preuve
ProgramInstructionDecoder	PASS	trait public Send + Sync
associated Decoded	PASS	type sans bound imposé, possédé par l'implémentation
program_ids	PASS	&[Pubkey], aucune validation registry dans l'API
recognize	PASS	input &ProgramInstruction, outcome ProgramInstructionRecognition
decode	PASS	Result<ProgramInstructionDecodeOutcome<Self::Decoded>>
default methods	ABSENT	toutes les méthodes sont obligatoires
external implementation canary	PASS	test d'intégration downstream-style séparé
Program Pubkey non enregistré	PASS	assertion ksp_core_lib::find_program_pubkey(...) == None
output externe concret	PASS	ExternalDecodedInstruction défini dans le consumer canary
ksp-program-lib	ABSENT	aucune dépendance ni implémentation officielle
registry / descriptor / payload D3	ABSENT	hors scope maintenu
serde / codec / logging / runtime	ABSENT	dependency firewall inchangé

Le canari d'implémentation consomme la façade ksp_program_api pour le trait, les types et les outcomes. Le registry Core n'est utilisé que par l'assertion de test négative et n'est pas réexporté par Program API. Le gate opérateur de pre.004 est confirmé intégralement vert et autorise pre.005.

12. Gate opérateur pre.004

Le gate fourni le 28 août 2026 est intégralement vert :

cargo fmt --all                                      PASS
audit Rust général / exports / workspace             PASS
audit Markdown                                       PASS — 172 tables / 121 fichiers
cargo check --workspace                              PASS
cargo clippy --workspace --all-targets               PASS
cargo test -p ksp-program-api                        PASS — 11 tests Rust
cargo test --workspace                               PASS
cargo tree -p ksp-program-api --edges normal         PASS — Core + Interface uniquement
cargo tree --duplicates                              exécuté, inventaire workspace observé

Ce gate autorise l'ouverture de pre.005.

13. État préparé pre.005

Critère	Statut	Preuve
exact crate-root export inventory	PASS	test release_completeness sur les 10 réexports
exact production module inventory	PASS	lib.rs, decode vocabulary et decoder trait uniquement
public enum inventory	PASS	Recognition + DecodeOutcome uniquement
closed-world Program enum	ABSENT	aucun ProgramKind/inventaire public central
registry / descriptors	ABSENT	aucune collection/runtime selection/identity-version-coverage
ProgramExecutionPreparer	ABSENT	scope négatif maintenu
serde / JSON / Any / codecs	ABSENT	manifest + source canaries
logging / runtime / IO	ABSENT	aucune dépendance ou primitive runtime/FS/env/network
max Interface input	PASS	255 accounts + 10 240 bytes traversent le trait par référence
malformed hostile payload	PASS	Result::Err Core reste sûr sans echo automatique du payload
Debug outcome	PASS	valeur décodée jamais formatée
associated Decoded implicit bounds	ABSENT	canari avec output Rc<Cell<_>>, donc non-Send/non-Sync accepté
dyn heterogeneous claim	ABSENT	aucun dyn ProgramInstructionDecoder/registry
dépendances normales	PASS	ksp-core-lib + ksp-interface-lib uniquement

La sécurité des messages/contextes produits volontairement par une implémentation tierce reste sa responsabilité ; ksp-program-api garantit seulement qu'il n'ajoute aucun canal parallèle ni copie automatique du payload hostile.

Le gate opérateur de pre.005 a révélé uniquement le faux positif cross-crate logging corrigé par pre.005-fix.001. Le gate du fix est désormais intégralement vert et autorise le gate technique final pre.006.

14. Gate opérateur pre.005-fix.001

Le gate fourni le 28 août 2026 est intégralement vert :

cargo fmt --all                                      PASS
audit Rust général / exports / workspace             PASS
audit Markdown                                       PASS — 173 tables / 123 fichiers
cargo check --workspace                              PASS
cargo clippy --workspace --all-targets               PASS
cargo test -p ksp-program-api                        PASS — 18 tests Rust
cargo test -p ksp-logging-lib --test ownership       PASS — 2/2
cargo test --workspace                               PASS
cargo tree -p ksp-program-api --edges normal         PASS — Core + Interface uniquement
cargo tree --duplicates                              inspecté

Le faux positif tracing du canari release_completeness.rs est fermé sans ajout de dépendance, sans modification de production et sans affaiblissement du scanner logging workspace.

15. Gate technique final préparé pre.006

pre.006 ne modifie aucun fichier de production ni de test. Le gate final doit confirmer la candidate suivante sans élargissement :

Critère	Attendu pre.006
API Program	exactement la surface fermée en pre.005
tests ksp-program-api	18 tests Rust PASS
ownership Logging	2 tests PASS
workspace	PASS
graphe normal ksp-program-api	Core + Interface uniquement
registry / preparer / payload D3	ABSENTS
serde / codec / logging runtime / IO	ABSENTS
README / USAGE	non réconciliés ici
CHANGELOG / ROADMAP / prompt suivant	non modifiés

Aucun smoke réseau/live n'est requis : ksp-program-api reste une API déclarative instruction-only sans I/O.

16. Gate technique final pre.006

Le gate opérateur fourni le 28 août 2026 confirme la candidate technique complète :

cargo fmt --all                                      PASS
audits Rust / export completeness / workspace        PASS
audit Markdown                                       PASS — 174 tables / 124 fichiers
cargo check --workspace                              PASS
cargo clippy --workspace --all-targets               PASS
cargo test -p ksp-program-api                        PASS — 18 tests Rust
cargo test -p ksp-logging-lib --test ownership       PASS — 2/2
cargo test --workspace                               PASS
cargo tree -p ksp-program-api --edges normal         PASS — Core + Interface uniquement
cargo tree --duplicates                              inspecté

Les duplicates observés sont ceux du workspace global et ne proviennent d'aucune dépendance ajoutée par Program API. Aucun smoke live n'est applicable à cette foundation déclarative sans I/O.

La validation technique de la release candidate est fermée.

17. Réconciliation documentaire pre.007

La documentation finale candidate est alignée sur les preuves techniques :

Référence durable	Statut pre.007	Contrat réconcilié
crates/ksp-program-api/README.md	PASS structurel	ownership, surface exacte, semantics, hardening, firewall et frontières
crates/ksp-program-api/USAGE.md	PASS structurel	usage crate-root, implémentation externe, sélection, outcome et Debug sûr
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md	PASS structurel	contenu réel 0.2.14 + reports runtime/D3/preparer
docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md	PASS structurel	gate pre.006 fermé + lane documentaire finale
docs/validation/017-V0_2_14_PROGRAM_API.md	PASS structurel	statuts finaux et preuves opérateur
index docs/000, plans et validation	PASS structurel	candidate réconciliée sans publication stable prématurée

La tranche ne modifie aucun code/test/manifest de crate/dépendance et ne touche ni CHANGELOG.md, ni ROADMAP.md, ni le prompt 0.3.1. Ces surfaces restent réservées à la préparation minimale de publication pre.008.

Le gate opérateur de pre.007 doit rester déterministe : audits, check, Clippy, tests ciblés Program/Logging et workspace suffisent ; aucun smoke live ni nouveau cargo tree n'est requis si l'overlay documentaire est appliqué exactement.