khadhroony-solana-project/docs/validation/016-V0_2_13_INTERFACE.md

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 :

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	PASS pre.002
façade	exports explicites crate-root; aucun pub mod	PASS pre.002
Pubkey	réexport/usage contrôlé de Core; pas de type parallèle	PASS pre.002
ProgramAccountMeta	private fields + writable/readonly + accessors	PASS pre.003
ProgramInstruction	private fields + try_new + accessors	PASS pre.006
account bound	constante publique <= 255; enforcement constructeur	PASS pre.006
data bound	<= 10_240	PASS pre.006
serde	absent	FIXÉ pre.001
generic codec	absent	FIXÉ pre.001
Debug instruction	résumé borné, pas payload complet	PASS pre.006
Error/Result	Core commun + code Interface sûr minimal	PASS 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 :

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	account meta/borne puis instruction/adversarial	PASS pre.006
tests/public_api.rs	consommation crate-root uniquement	PASS pre.006
external consumer canary	surface utilisable hors modules privés	PASS pre.006
dependency boundary	firewall exact	PASS pre.006
release completeness	inventaire exact, aucun domaine supplémentaire	PASS pre.006
round-trip codec	aucun tant qu'aucun codec	N/A
network smoke	aucun pour crate wire pure	N/A

11. Gate technique final validé

Le gate opérateur 0.2.13-pre.006 du 28 août 2026 ferme la lane technique :

cargo fmt --all                                      PASS
python3 scripts/audit_rust_workspace_rules.py        PASS
python3 scripts/audit_markdown_tables.py ...         PASS — 162 tables / 119 fichiers
cargo check --workspace                              PASS
cargo clippy --workspace --all-targets               PASS
cargo test -p ksp-interface-lib                      PASS
cargo test -p ksp-logging-lib --test ownership       PASS
cargo test --workspace                               PASS
cargo tree -p ksp-interface-lib --edges normal       Core-only confirmé
cargo tree --duplicates                              inspecté

Aucun smoke réseau/live n'est exigé : la crate reste une foundation wire pure sans I/O.

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.

13. État préparé pre.002

Le scaffold matérialisé conserve volontairement une surface minimale :

workspace member                     PASS structurel
normal dependency                    ksp-core-lib uniquement
Pubkey                               réexport Core au crate-root
public modules                       aucun
ProgramAccountMeta                   absent par contrat pre.002
ProgramInstruction                   absent par contrat pre.002
serde / borsh / bincode / wincode    absents
network/runtime dependencies          absentes
ksp-logging-lib                      absent
constants.rs / TRACING_TARGET        absents
README / USAGE                       initiaux
public API canary                    présent
dependency firewall canary           présent

Le logging reste volontairement absent : la foundation 0.2.13 est passive et n'émet aucun événement/span runtime. Si une future surface comportementale démontre un besoin réel de logging, ksp-logging-lib, src/constants.rs et TRACING_TARGET devront être introduits ensemble conformément à DEP-LOG-004 et DEP-LOG-010.

Le passage à pre.003 reste conditionné au gate opérateur complet sur l'overlay pre.002.

14. État préparé pre.003

Critère	Statut
ProgramAccountMeta crate-root	PASS structurel
champs privés	PASS
constructeurs readonly / writable	PASS
accessors identité/signer/writable	PASS
Pubkey opaque non registry	PASS unit
MAX_PROGRAM_INSTRUCTION_ACCOUNTS == 255	PASS unit + public API
enforcement collection 255/256	PENDING pre.004 avec ProgramInstruction
code interface.program_instruction_limit_exceeded	PASS public API
type d'erreur propre Interface	ABSENT, Core commun conservé
ProgramInstruction	ABSENT par contrat
data bound	PENDING pre.004
serde/codecs	ABSENTS
logging/runtime	ABSENTS
dépendance normale	ksp-core-lib uniquement

Le statut PASS/PENDING de la borne accounts signifie que la valeur publique est désormais figée à 255, tandis que le rejet concret de 256 comptes sera testé lorsque la collection existera dans ProgramInstruction. Aucun faux wrapper de collection n'est créé dans pre.003.

15. État préparé pre.004

Critère	Statut
ProgramInstruction crate-root	PASS structurel
champs privés	PASS
constructeur try_new	PASS
accessors program_id/accounts/data	PASS
MAX_PROGRAM_INSTRUCTION_DATA_LEN == 10_240	PASS unit + public API
accounts 255 accepté / 256 refusé	PASS unit
data 10_240 accepté / 10_241 refusé	PASS unit
accounts/data vides	PASS unit
ordre + doublons accounts	PASS unit
Program Pubkey opaque/non registry	PASS unit
erreur borne Core commune	PASS
contexte erreur limité aux longueurs/plafonds sûrs	PASS unit
Debug résumé sans accounts/payload	PASS unit
serde/codecs	ABSENTS
solana-instruction	ABSENT
logging/runtime	ABSENTS
dépendance normale	ksp-core-lib uniquement
cargo test --workspace sur preuve entrée pre.003	NON FOURNI — à rejouer au gate opérateur 004

La tranche ferme ainsi le premier lot générique { program_id, accounts, data } sans ajouter de codec ni de comportement Program. Le hardening pre.005 doit porter sur l'usage externe, les cas adversariaux et le firewall, pas sur une nouvelle famille wire.

16. État préparé pre.005

Le gate opérateur pre.004 est complet : fmt, audits Rust/Markdown, cargo check --workspace, Clippy, cargo test -p ksp-interface-lib, cargo test --workspace et graphes Cargo sont verts/inspectés.

La tranche pre.005 ajoute uniquement des canaris de hardening :

external consumer crate                 présent via tests/external_consumer.rs
release completeness                    présent via tests/release_completeness.rs
crate-root exports exacts               vérifiés par source canary
production module inventory exact       vérifié par filesystem canary
source dependency firewall              étendu à tous les src production
narrowing cast / encode/decode caché     interdits par source canary
Vec accounts/data sans réallocation      vérifié par identité de pointeur
payload hostile dans Error/Debug         absent attendu
account material arbitraire dans Error   absent attendu
nouveau type wire                         aucun
nouvelle dépendance                       aucune
codec/logging/runtime                     toujours absents

Les nouveaux tests sont présents mais non déclarés PASS dans le sandbox, qui ne dispose pas de Cargo. Leur statut final dépend du gate opérateur pre.005.

Le consumer externe est un test d'intégration Rust, donc compilé par Cargo dans un crate distinct de ksp-interface-lib. Sa source ne consomme que les exports du crate-root ; les modules privés ne sont pas utilisés.

Le canari de complétude impose exactement les exports publics retenus et exactement quatre modules/fichiers de production : error.rs, lib.rs, program_account_meta.rs, program_instruction.rs. Cette contrainte ferme explicitement le risque d'ajout opportuniste d'une seconde famille wire avant la release stable.

17. Gate pre.005 et correctif pre.005-fix.001

Le gate ciblé Interface est intégralement vert :

unit tests Interface                10/10 PASS
manifest/source firewall            4/4 PASS
external consumer                   1/1 PASS
public API                           5/5 PASS
release completeness                3/3 PASS
doctests                            0 échec

Le workspace échoue ensuite dans le canari transversal Logging :

ksp-logging-lib/tests/ownership.rs
workspace_crates_do_not_bypass_ksp_logging_facade

Diagnostic confirmé : tests/dependency_boundary.rs contient le littéral tracing:: uniquement comme pattern interdit. Le scanner Logging travaille sur le texte brut des .rs et interprète donc ce pattern de test comme un bypass réel. Le graphe Cargo Interface reste pourtant :

ksp-interface-lib
└── ksp-core-lib
    └── solana-pubkey 4.3.0

pre.005-fix.001 remplace uniquement ce littéral source par une construction compile-time équivalente concat!("tracing", "::"). La propriété testée reste identique ; seule l'interaction entre deux scanners est corrigée.

Statut final du fix après gate opérateur :

production src                            inchangé
API publique                              inchangée
dépendances                               inchangées
logging runtime Interface                 toujours absent
codec                                     toujours absent
version technique                         0.2.13-pre.5.fix.1
cargo test -p ksp-interface-lib           PASS
cargo test -p ksp-logging-lib --test ownership PASS
cargo test --workspace                    PASS
cargo tree Interface                      Core-only confirmé

18. Gate technique final pre.006

Le gate final a confirmé la surface complète sans nouvelle modification technique :

unit Interface                                      10/10 PASS
dependency boundary                                 4/4 PASS
external consumer                                   1/1 PASS
public API                                           5/5 PASS
release completeness                                3/3 PASS
ownership Logging                                   2/2 PASS
workspace                                           PASS
Cargo graph Interface                               ksp-core-lib uniquement

Les duplicates observés dans le workspace sont extérieurs au graphe normal d'Interface et ne proviennent d'aucune dépendance ajoutée par 0.2.13.

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

19. 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-interface-lib/README.md	PASS structurel	ownership, surface finale, bornes, firewall, frontières
crates/ksp-interface-lib/USAGE.md	PASS structurel	usage crate-root, construction metas/instruction, erreurs et limites
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md	PASS structurel	contenu réel 0.2.13 + reports 0.2.14 / 0.3.2+
docs/plans/020-V0_2_13_INTERFACE_PLAN.md	PASS structurel	gate pre.006 fermé + lane documentaire finale
docs/validation/016-V0_2_13_INTERFACE.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 n'ajoute aucun code/test/codec/dépendance et ne modifie ni CHANGELOG.md, ni ROADMAP.md, ni le prompt 0.2.14. Ces trois surfaces restent réservées à pre.008.

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