5.6 KiB
Delta 0.2.14-pre.002 — scaffold ksp-program-api + façade + firewall
1. Base requise
Cette tranche s'applique exclusivement sur :
v0.2.13
+ 0.2.14-pre.001
Le gate opérateur fourni pour pre.001 est vert :
cargo fmt --all PASS
python3 scripts/audit_rust_workspace_rules.py PASS
python3 scripts/audit_markdown_tables.py ... PASS — 170 tables / 116 fichiers
cargo check --workspace PASS
cargo clippy --workspace --all-targets PASS sans warning
La version workspace passe de :
0.2.14-pre.1
à :
0.2.14-pre.2
Commit attendu :
v0.2.14-pre.002
2. Objectif
Matérialiser uniquement le scaffold de ksp-program-api et verrouiller sa façade/dependency firewall avant toute capability de décodage.
La tranche ajoute :
nouveau membre workspace ksp-program-api
manifest Core + Interface uniquement
façade crate-root explicite
réexports Core retenus
réexports Interface retenus
README/USAGE initiaux
canari public API
canari dependency firewall
Elle n'ajoute pas :
ProgramInstructionRecognition
ProgramInstructionDecodeOutcome
ProgramInstructionDecoder
ProgramExecutionPreparer
registry runtime
identity/version/coverage
payload canonique D3
serde / JSON / Any
codec
runtime logging
network / async runtime
3. Façade publique de scaffold
Le crate-root réexporte explicitement :
ksp-core-lib
Error
ErrorCode
ErrorContext
Result
Pubkey
ksp-interface-lib
ProgramAccountMeta
ProgramInstruction
Ces réexports ne changent pas l'ownership des types. Ils fournissent la façade retenue par le plan afin qu'une future implémentation externe puisse dépendre du contrat Program sans reconstruire les types Core/Interface ni accéder à leurs modules privés.
Aucun pub mod n'est exposé.
4. Dependency firewall
Le manifest membre possède exactement :
[dependencies]
ksp-core-lib
ksp-interface-lib
Le canari tests/dependency_boundary.rs verrouille notamment l'absence de :
ksp-program-lib
ksp-logging-lib
Transport / Config / Wallet / Store / Materializer
serde / serde_json
borsh / bincode / wincode
solana-instruction
reqwest / tokio / tonic / tauri / tracing
Il verrouille aussi l'absence de src/constants.rs, TRACING_TARGET, recognition/outcome/decoder/preparer et de module public pendant pre.002.
5. Logging
La crate reste une API déclarative sans comportement runtime. Aucun span/event n'est émis et aucun logging n'est nécessaire.
Restent donc volontairement absents :
ksp-logging-lib
src/constants.rs
TRACING_TARGET
tracing direct
Si une future surface Program comportementale nécessite réellement une instrumentation, elle devra respecter les règles Logging KSP dans la crate qui possède ce comportement. Le scaffold API ne doit pas tirer un runtime logging par anticipation.
6. Tests ajoutés
tests/public_api.rs vérifie que la façade crate-root permet de construire Pubkey, ProgramAccountMeta et ProgramInstruction, et que les types d'erreur Core sont adressables sans module privé.
tests/dependency_boundary.rs vérifie :
dépendances normales exactes = Core + Interface
absence des dépendances interdites
absence de pub mod
absence des contrats réservés à pre.003/pre.004
absence de logging/runtime/codec
Aucun unit test métier n'est ajouté : la crate ne possède encore aucun comportement propre.
7. Fichiers ajoutés
crates/ksp-program-api/Cargo.toml
crates/ksp-program-api/README.md
crates/ksp-program-api/USAGE.md
crates/ksp-program-api/src/lib.rs
crates/ksp-program-api/tests/dependency_boundary.rs
crates/ksp-program-api/tests/public_api.rs
deltas/0.2.14/pre.002.md
8. Fichiers modifiés
Cargo.toml
docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md
docs/validation/017-V0_2_14_PROGRAM_API.md
9. Fichiers volontairement inchangés
README.md
RULES.md
ROADMAP.md
CHANGELOG.md
docs/architecture/**
docs/rules/**
crates/ksp-core-lib/**
crates/ksp-interface-lib/**
crates/ksp-logging-lib/**
crates/ksp-*-transport-lib/**
crates/ksp-config-lib/**
crates/ksp-wallet-lib/**
crates/ksp-app-*/**
prompts/**
Aucune architecture durable n'est rouverte : la direction Program API -> Core + Interface est déjà normative.
10. Validations de génération
Les audits Python sont rejoués sur l'arbre matérialisé avant livraison. L'environnement de génération ne fournit pas cargo, rustc ou rustfmt; aucun PASS Cargo nouveau n'est revendiqué localement.
11. 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.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
Le graphe normal doit confirmer :
ksp-program-api
├── ksp-core-lib
└── ksp-interface-lib
└── ksp-core-lib
Une correction découverte par ce gate reste un 0.2.14-pre.002-fix.NNN et n'avance pas pre.003.
12. Suite
Après gate vert, pre.003 pourra matérialiser uniquement :
ProgramInstructionRecognition
ProgramInstructionDecodeOutcome<Decoded>
invariants / Debug sûr associés
unit/public canaries correspondants
ProgramInstructionDecoder et l'implémentation externe restent réservés à pre.004.