6.9 KiB
Delta 0.2.13-pre.004 — ProgramInstruction passif borné
1. Base requise
Cette tranche s'applique exclusivement sur :
v0.2.12
+ 0.2.13-pre.001
+ 0.2.13-pre.002
+ 0.2.13-pre.003
La preuve opérateur fournie pour pre.003 confirme :
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 -p ksp-interface-lib PASS
cargo tree -p ksp-interface-lib --edges normal inspecté
cargo tree --duplicates inspecté
cargo test --workspace n'apparaît pas dans cette preuve opérateur. La présente préparation n'en invente donc pas le résultat ; ce test devra être rejoué avec le gate de pre.004 avant de déclarer la continuité workspace complète.
Le graphe ciblé reste strictement :
ksp-interface-lib
└── ksp-core-lib
└── solana-pubkey 4.3.0
La version workspace passe de :
0.2.13-pre.3
à :
0.2.13-pre.4
2. Objectif
Matérialiser le second type du premier lot wire générique décidé en pre.001 : une instruction Program passive { program_id, accounts, data }, bornée à l'admission et sans comportement Program.
La tranche ajoute :
ProgramInstruction
MAX_PROGRAM_INSTRUCTION_DATA_LEN = 10_240
ProgramInstruction::try_new(...)
accessors program_id/accounts/data
Debug résumé
unit/public canaries de limites, ordre et doublons
Elle n'ajoute pas :
serde / serde_json
borsh / bincode / wincode
solana-instruction
codec ou discriminant Program spécifique
Program API / Program behavior
Transport / Store / Config / Wallet
ksp-logging-lib / constants.rs / TRACING_TARGET
runtime réseau
3. ProgramInstruction
Le type possède trois champs privés :
program_id : Pubkey
accounts : Vec<ProgramAccountMeta>
data : Vec<u8>
Le constructeur public est :
ProgramInstruction::try_new(program_id, accounts, data)
-> ksp_core_lib::Result<ProgramInstruction>
Les accessors publics sont :
program_id() -> &Pubkey
accounts() -> &[ProgramAccountMeta]
data() -> &[u8]
La construction consomme directement les Vec fournis. Aucun clone interne, conversion vers solana-instruction ou sérialisation n'est ajouté.
4. Bornes d'admission
Les deux plafonds sont désormais matérialisés :
MAX_PROGRAM_INSTRUCTION_ACCOUNTS = 255
MAX_PROGRAM_INSTRUCTION_DATA_LEN = 10_240
try_new vérifie en usize :
accounts.len() <= 255
data.len() <= 10_240
Canaris exacts :
255 accounts accepté
256 accounts refusé
10_240 octets data accepté
10_241 octets data refusé
Ces valeurs restent des bornes d'admission Interface fondées sur les plafonds Solana CPI audités en pre.001. Elles ne garantissent pas qu'une instruction rentre dans une transaction top-level complète.
5. Sémantique passive
Restent valides :
accounts vides
data vide
Program Pubkey inconnu du registry Core
doublons d'accounts
ordre arbitraire des account metas
payload opaque quelconque sous la borne
Interface n'ajoute aucune politique signer/writable, aucun lookup de Program ID, aucune déduplication et aucune interprétation du payload.
6. Erreurs
Les deux violations de borne réutilisent :
interface.program_instruction_limit_exceeded
via ksp_core_lib::Error/Result.
Le contexte d'erreur est limité à :
field
actual_len
maximum_len
Aucun octet data, aucun account arbitraire et aucun payload externe n'est copié dans l'erreur.
Le code conceptuel invalid_program_instruction reste absent : la foundation ne possède toujours aucun invariant de forme distinct des deux limites.
7. Debug borné
ProgramInstruction n'utilise pas un derive(Debug) qui imprimerait les deux Vec.
Son Debug manuel expose uniquement :
program_id
account_count
data_len
Les account metas et le payload sont volontairement absents du rendu.
8. Logging
La décision de pre.002 reste inchangée : cette crate est passive.
Restent absents :
ksp-logging-lib
src/constants.rs
TRACING_TARGET
tracing direct
Une erreur de validation de borne est une valeur retournée au caller, pas un événement runtime à logger depuis Interface.
9. Tests
Les unit tests de ProgramInstruction couvrent :
accounts/data vides acceptés
Program Pubkey opaque accepté
ordre et doublons préservés
payload opaque préservé
255 / 256 accounts
10_240 / 10_241 octets data
code/message/contexte d'erreur sûr
Debug résumé sans payload ni account flags
tests/public_api.rs ajoute un canari de consommation crate-root de ProgramInstruction et de MAX_PROGRAM_INSTRUCTION_DATA_LEN.
tests/dependency_boundary.rs est avancé à pre.004 et confirme toujours :
ksp-core-lib seule dépendance normale
aucun serde/borsh/bincode/wincode
aucun solana-instruction
aucun logging/runtime
ProgramInstruction présent via façade explicite
10. Fichiers ajoutés
crates/ksp-interface-lib/src/program_instruction.rs
crates/ksp-interface-lib/unit_tests/program_instruction.rs
deltas/0.2.13/pre.004.md
11. Fichiers modifiés
Cargo.toml
crates/ksp-interface-lib/src/lib.rs
crates/ksp-interface-lib/tests/dependency_boundary.rs
crates/ksp-interface-lib/tests/public_api.rs
docs/plans/020-V0_2_13_INTERFACE_PLAN.md
docs/validation/016-V0_2_13_INTERFACE.md
12. Fichiers volontairement inchangés
README.md
ROADMAP.md
CHANGELOG.md
.env.example
crates/ksp-interface-lib/Cargo.toml
crates/ksp-interface-lib/README.md
crates/ksp-interface-lib/USAGE.md
crates/ksp-interface-lib/src/error.rs
crates/ksp-interface-lib/src/program_account_meta.rs
crates/ksp-interface-lib/unit_tests/program_account_meta.rs
docs/architecture/**
prompts/**
config/**
13. Gate attendu
Après application de l'overlay :
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 -p ksp-interface-lib
cargo test --workspace
cargo tree -p ksp-interface-lib --edges normal
cargo tree --duplicates
Le cargo test --workspace est particulièrement requis ici puisqu'il n'était pas présent dans la preuve opérateur fournie pour pre.003.
14. Suite autorisée
Après gate vert, pre.005 doit rester une tranche de hardening :
cas adversariaux complémentaires
consumer externe
surface crate-root
firewall source/manifest
graphes Cargo
canari de complétude du premier lot
Aucun second domaine wire, codec générique ou comportement Program ne doit être ajouté opportunément.