khadhroony-solana-project/deltas/0.2.14/pre.002.md

<!-- file: deltas/0.2.14/pre.002.md -->
<!-- version: 1 -->

# Delta `0.2.14-pre.002` — scaffold `ksp-program-api` + façade + firewall

## 1. Base requise

Cette tranche s'applique exclusivement sur :

```text
v0.2.13
+ 0.2.14-pre.001
```

Le gate opérateur fourni pour `pre.001` est vert :

```text
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 :

```text
0.2.14-pre.1
```

à :

```text
0.2.14-pre.2
```

Commit attendu :

```text
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 :

```text
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 :

```text
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 :

```text
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 :

```text
[dependencies]
ksp-core-lib
ksp-interface-lib
```

Le canari `tests/dependency_boundary.rs` verrouille notamment l'absence de :

```text
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 :

```text
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 :

```text
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

```text
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

```text
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

```text
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 :

```bash
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 :

```text
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 :

```text
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`.