khadhroony-solana-project/deltas/0.2.13/pre.003.md

Delta 0.2.13-pre.003 — ProgramAccountMeta + borne accounts

1. Base requise

Cette tranche s'applique exclusivement sur :

v0.2.12
+ 0.2.13-pre.001
+ 0.2.13-pre.002

Le gate opérateur fourni pour pre.002 est intégralement vert :

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 test --workspace                               PASS
cargo tree -p ksp-interface-lib --edges normal       inspecté
cargo tree --duplicates                              inspecté

Le graphe ciblé confirme :

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

Aucune dépendance codec/runtime n'est introduite par Interface et les doublons workspace observés sont préexistants à cette crate.

La version workspace passe de :

0.2.13-pre.2

à :

0.2.13-pre.3

2. Objectif

Matérialiser uniquement la primitive passive représentant un account meta d'instruction Program, figer la borne publique du nombre d'account metas et introduire le code d'erreur Interface minimal nécessaire à la future admission de ProgramInstruction.

La tranche ajoute :

ProgramAccountMeta
MAX_PROGRAM_INSTRUCTION_ACCOUNTS = 255
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED
unit tests de la primitive
public API canaries correspondants

Elle n'ajoute pas encore :

ProgramInstruction
MAX_PROGRAM_INSTRUCTION_DATA_LEN
enforcement de collection 255/256
data payload
Debug résumé d'instruction
serde / serde_json
borsh / bincode / wincode
solana-instruction
logging/runtime
Program behavior

3. ProgramAccountMeta

La primitive possède trois champs privés :

Pubkey
is_signer
is_writable

Les constructeurs publics sont :

ProgramAccountMeta::readonly(pubkey, is_signer)
ProgramAccountMeta::writable(pubkey, is_signer)

Les accessors publics sont :

pubkey()
is_signer()
is_writable()

Le type reste strictement passif :

• aucune validation de registry Program n'est appliquée au Pubkey ;
• aucune policy signer/writable n'est inventée ;
• aucune sérialisation ou conversion vers solana-instruction::AccountMeta n'est ajoutée ;
• les champs privés empêchent une dérive future de représentation sans passer par l'API possédée par Interface.

4. Borne accounts

La façade expose :

pub const MAX_PROGRAM_INSTRUCTION_ACCOUNTS: usize = 255;

Cette constante fixe le plafond d'admission retenu par le plan 0.2.13.

pre.003 ne crée volontairement aucune collection artificielle autour de ProgramAccountMeta uniquement pour tester 255/256. L'enforcement concret sera réalisé dans ProgramInstruction::try_new à pre.004, lorsque la collection existera réellement.

La borne data 10_240 reste également réservée à pre.004 avec le payload qu'elle protège.

5. Modèle d'erreur minimal

Interface continue d'utiliser ksp_core_lib::Error, ErrorCode et Result; aucun second type d'erreur n'est introduit.

La seule catégorie matérialisée est :

interface.program_instruction_limit_exceeded

via :

ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED

Le code invalid_program_instruction n'est pas ajouté : aucun invariant de forme distinct des bornes n'existe encore dans la foundation. Le créer uniquement par symétrie serait prématuré.

À pre.004, les erreurs de borne devront limiter leur contexte aux longueurs et plafonds sûrs ; aucun payload ni compte arbitraire ne devra être copié dans les diagnostics.

6. Logging

La décision de pre.002 reste inchangée. Interface est toujours une crate de contrats passifs et n'émet aucun événement/span runtime.

Restent donc absents :

ksp-logging-lib
src/constants.rs
TRACING_TARGET
tracing direct

7. Tests

Les unit tests de ProgramAccountMeta couvrent :

readonly -> identité/signature conservées, writable=false
writable -> identité/signature conservées, writable=true
Pubkey opaque/non registry accepté
MAX_PROGRAM_INSTRUCTION_ACCOUNTS == 255

tests/public_api.rs prouve depuis le crate-root :

construction readonly/writable
accessors publics
borne accounts publique
code d'erreur stable et typé par ksp_core_lib::ErrorCode

tests/dependency_boundary.rs conserve le firewall pre.002 et vérifie désormais que :

ProgramAccountMeta est présent
MAX_PROGRAM_INSTRUCTION_ACCOUNTS est présent
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED est présent
ProgramInstruction reste absent
logging/runtime restent absents

8. Fichiers ajoutés

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
deltas/0.2.13/pre.003.md

9. 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

10. 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
docs/architecture/**
docs/rules/**
crates/ksp-core-lib/**
crates/ksp-logging-lib/**
crates/ksp-onchain-transport-lib/**
crates/ksp-offchain-transport-lib/**
crates/ksp-config-lib/**
crates/ksp-wallet-lib/**
crates/ksp-app-*/**
prompts/**

README/USAGE restent dans leur lane de réconciliation finale pre.007; aucune documentation durable hors plan/validation n'est rouverte pour cette petite tranche fonctionnelle.

11. Validations de génération

Les audits Python sont rejoués sur l'arbre matérialisé avant livraison. Le sandbox de génération ne fournit pas cargo, rustc ou rustfmt; aucun nouveau PASS Cargo n'est donc revendiqué localement.

12. Gate opérateur attendu

Après application :

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

Une correction découverte par ce gate reste un 0.2.13-pre.003-fix.NNN et n'avance pas pre.004.

13. Suite

Après gate vert, pre.004 pourra matérialiser uniquement :

ProgramInstruction { program_id, accounts, data }
MAX_PROGRAM_INSTRUCTION_DATA_LEN = 10_240
try_new borné
accessors
Debug résumé sans payload
acceptation 0/255 accounts et 0/10_240 data
rejet 256 accounts et 10_241 data
ordre et doublons conservés
contextes d'erreur sûrs

Aucun serde/codec ou comportement Program ne doit être ajouté dans cette tranche suivante.