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	pre.003
ProgramInstructionDecodeOutcome<Decoded>	Decoded(Decoded) / Unsupported, non exhaustif	pre.003
decoder failure	ksp_core_lib::Result, aucun statut Failed parallèle	pre.003 / pre.004
ProgramInstructionDecoder	Send + Sync, associated Decoded	pre.004
input	&ProgramInstruction	pre.004
Program IDs déclarés	&[Pubkey], opaque et open-world	pre.004
output	type concret de l'implémentation	pre.004
registry dyn	absent	completeness pre.005
identity/version/coverage	absents	completeness pre.005
Program Account/Event/ReturnData decoder	absents	completeness pre.005
ProgramExecutionPreparer	absent	completeness pre.005
serde/JSON/codec	absents	firewall pre.002 / pre.005
runtime/logging	absents	firewall pre.002 / pre.005

4. External implementation canary

La preuve finale doit utiliser une crate consommatrice séparée et vérifier :

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	PENDING
Debug outcome	contenu Decoded non rendu automatiquement	PENDING
default methods	aucun default method susceptible de masquer panic/policy	PENDING
closed-world enum	aucun inventaire central de Program kinds	PENDING
serde accidental	aucune dependency/derive	PENDING
runtime creep	aucun réseau, wallet, store, logging ou UI	PENDING
external output	type tiers accepté sans Any/JSON central	PENDING
dyn claim	aucune assertion d'object-safety hétérogène dans cette release	PENDING

7. Gates de fermeture

Gate technique final

À exécuter dans la prerelease dédiée :

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. État préparé pre.002

Le scaffold matérialisé est :

workspace member                         PASS structurel
normal dependencies                      ksp-core-lib + ksp-interface-lib uniquement
crate-root facade                        Error/ErrorCode/ErrorContext/Result/Pubkey + Interface instruction types
public modules                           aucun
README / USAGE                           présents
public API canary                        présent
dependency firewall canary               présent
ProgramInstructionRecognition            absent par contrat pre.002
ProgramInstructionDecodeOutcome          absent par contrat pre.002
ProgramInstructionDecoder                absent par contrat pre.002
registry / canonical payload / preparer  absents
serde / codecs / runtime logging         absents

Le gate opérateur pre.001 fourni le 28 août 2026 est vert pour cargo fmt --all, audits Rust/Markdown, cargo check --workspace et Clippy workspace.

Le passage à pre.003 reste conditionné au gate opérateur de cet overlay. Les preuves recognition/outcome restent PENDING jusqu'à leur tranche dédiée.