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

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

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 :

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	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	PASS
Debug outcome	contenu Decoded non rendu automatiquement	PASS
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 :

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 :

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

Les canaris unitaires et publics de pre.003 doivent passer avant d'ouvrir pre.004. La preuve d'implémentation externe, le Program Pubkey open-world et l'associated output complet restent réservés au trait decoder de la tranche suivante.