v0.2.13-pre.007
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 309
|
||||
# version: 310
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-wallet-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.2.13-pre.6"
|
||||
version = "0.2.13-pre.7"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
@@ -1,19 +1,109 @@
|
||||
<!-- file: crates/ksp-interface-lib/README.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# ksp-interface-lib
|
||||
|
||||
`ksp-interface-lib` est la façade KSP destinée aux contrats wire passifs des programmes Solana. Elle est conçue pour être consommée par les implémentations Program officielles ou externes sans absorber Transport, Wallet, Store, Config ni le comportement métier Program.
|
||||
`ksp-interface-lib` est la façade wire officielle KSP destinée aux contrats passifs partagés par les implémentations Program Solana officielles ou externes. La crate expose uniquement des structures de représentation/admission ; elle ne possède ni transport, ni exécution, ni persistence, ni comportement métier Program.
|
||||
|
||||
## Ownership
|
||||
|
||||
La crate réutilise les primitives fondamentales déjà possédées par `ksp-core-lib`, notamment `Pubkey`. Les Program IDs fondamentaux restent également dans Core. Interface possédera progressivement les layouts, discriminants, codecs et constructeurs wire uniquement lorsqu'un protocole réel les exige.
|
||||
La crate réutilise les primitives fondamentales déjà possédées par `ksp-core-lib` :
|
||||
|
||||
La foundation ne dépend pas de runtime réseau ou applicatif. Elle n'ajoute donc pas de logging runtime, de scheduler, de persistence ou de configuration.
|
||||
```text
|
||||
Pubkey
|
||||
Error / ErrorCode / Result
|
||||
Program IDs fondamentaux
|
||||
```
|
||||
|
||||
## Surface initiale
|
||||
`Pubkey` est réexporté depuis le crate-root Interface afin qu'un consumer wire n'introduise aucun wrapper d'identité parallèle. Les Program IDs restent possédés et répertoriés par Core.
|
||||
|
||||
La façade crate-root expose actuellement le `Pubkey` canonique de Core. Les contrats passifs d'instruction et d'account meta sont introduits séparément afin de fermer leurs bornes et leur surface publique avant les premières APIs Program.
|
||||
La dependency direction candidate `0.2.13` reste strictement :
|
||||
|
||||
```text
|
||||
ksp-interface-lib
|
||||
└── ksp-core-lib
|
||||
└── solana-pubkey
|
||||
```
|
||||
|
||||
## Surface publique `0.2.13`
|
||||
|
||||
La façade crate-root expose exactement :
|
||||
|
||||
```text
|
||||
Pubkey
|
||||
ProgramAccountMeta
|
||||
MAX_PROGRAM_INSTRUCTION_ACCOUNTS
|
||||
ProgramInstruction
|
||||
MAX_PROGRAM_INSTRUCTION_DATA_LEN
|
||||
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED
|
||||
```
|
||||
|
||||
Aucun module interne n'est public.
|
||||
|
||||
### `ProgramAccountMeta`
|
||||
|
||||
`ProgramAccountMeta` représente un compte ordonné d'une instruction avec :
|
||||
|
||||
```text
|
||||
pubkey
|
||||
is_signer
|
||||
is_writable
|
||||
```
|
||||
|
||||
Les champs restent privés. Les constructeurs publics sont `readonly(pubkey, is_signer)` et `writable(pubkey, is_signer)`, complétés par les accessors `pubkey()`, `is_signer()` et `is_writable()`.
|
||||
|
||||
La structure n'applique aucune sémantique spécifique à un programme et n'exige pas que la `Pubkey` appartienne au registry des Program IDs Core.
|
||||
|
||||
### `ProgramInstruction`
|
||||
|
||||
`ProgramInstruction` représente un contrat passif borné :
|
||||
|
||||
```text
|
||||
program_id
|
||||
accounts: Vec<ProgramAccountMeta>
|
||||
data: Vec<u8>
|
||||
```
|
||||
|
||||
`ProgramInstruction::try_new` consomme directement les deux `Vec`, conserve l'ordre et les doublons des accounts et préserve les octets opaques de `data` sans décodage.
|
||||
|
||||
Les cas vides sont valides et une `program_id` inconnue du registry KSP reste admissible.
|
||||
|
||||
## Bornes d'admission
|
||||
|
||||
Interface applique deux limites locales :
|
||||
|
||||
| Limite | Valeur |
|
||||
|------------------------------------|----------|
|
||||
| `MAX_PROGRAM_INSTRUCTION_ACCOUNTS` | `255` |
|
||||
| `MAX_PROGRAM_INSTRUCTION_DATA_LEN` | `10_240` |
|
||||
|
||||
Ces valeurs sont des **bornes d'admission Interface**. Elles ne constituent pas une garantie qu'une instruction donnée tient dans toutes les contraintes d'une transaction Solana top-level. La limite CPI de comptes uniques n'est notamment pas transformée en règle artificielle sur la liste d'account metas.
|
||||
|
||||
Un dépassement utilise le code commun :
|
||||
|
||||
```text
|
||||
interface.program_instruction_limit_exceeded
|
||||
```
|
||||
|
||||
Le contexte d'erreur est limité aux métadonnées sûres `field`, `actual_len` et `maximum_len`. Aucun payload arbitraire ni account meta hostile n'est recopié dans l'erreur.
|
||||
|
||||
Le `Debug` de `ProgramInstruction` est volontairement borné : il affiche `program_id`, `account_count` et `data_len`, jamais les accounts complets ni les octets du payload.
|
||||
|
||||
## Codecs et runtime
|
||||
|
||||
La foundation `0.2.13` n'ajoute aucun codec par réflexe :
|
||||
|
||||
```text
|
||||
serde / serde_json absents
|
||||
borsh absent
|
||||
wincode absent
|
||||
bincode absent
|
||||
solana-instruction absent
|
||||
```
|
||||
|
||||
Des codecs/layouts/discriminants spécifiques pourront être ajoutés ultérieurement uniquement lorsqu'un vertical Program réel en démontre le besoin et que leur ownership wire appartient bien à Interface.
|
||||
|
||||
La crate ne produit aucun événement runtime. Elle ne dépend donc pas de `ksp-logging-lib` et ne possède ni `constants.rs` ni `TRACING_TARGET`. Si un futur comportement Interface exige réellement du logging, le runtime devra passer par la façade Logging KSP plutôt que par une dépendance directe à Tracing.
|
||||
|
||||
## Frontières
|
||||
|
||||
@@ -21,12 +111,21 @@ La façade crate-root expose actuellement le `Pubkey` canonique de Core. Les con
|
||||
|
||||
```text
|
||||
RPC / WebSocket / gRPC
|
||||
provider DTOs Transport
|
||||
wallet / signature
|
||||
persistence / Store
|
||||
Config / environnement
|
||||
interprétation métier Program
|
||||
execution policy
|
||||
persistence / Store
|
||||
Program decoding / recognition / proofs
|
||||
execution policy / signers
|
||||
transaction replay / CPI path / runtime logs
|
||||
lifecycle réseau
|
||||
```
|
||||
|
||||
La conception détaillée de la foundation est suivie dans [`../../docs/plans/020-V0_2_13_INTERFACE_PLAN.md`](../../docs/plans/020-V0_2_13_INTERFACE_PLAN.md) et sa validation dans [`../../docs/validation/016-V0_2_13_INTERFACE.md`](../../docs/validation/016-V0_2_13_INTERFACE.md).
|
||||
La foundation Program API est reportée à `0.2.14`. Les wires génériques d'acquisition/CORE restent reportés à `0.3.2+`.
|
||||
|
||||
## Références
|
||||
|
||||
- [Usage public](USAGE.md)
|
||||
- [Plan `0.2.13`](../../docs/plans/020-V0_2_13_INTERFACE_PLAN.md)
|
||||
- [Validation `0.2.13`](../../docs/validation/016-V0_2_13_INTERFACE.md)
|
||||
- [Architecture Wire + Program](../../docs/architecture/006-WIRE_AND_PROGRAM.md)
|
||||
|
||||
@@ -1,24 +1,122 @@
|
||||
<!-- file: crates/ksp-interface-lib/USAGE.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Usage de ksp-interface-lib
|
||||
|
||||
Cette page décrit la surface publique actuellement matérialisée par la foundation Interface. Les APIs d'instruction sont ajoutées progressivement sans exposer les modules internes.
|
||||
Cette page décrit la façade publique matérialisée par `0.2.13`. Les modules internes ne font pas partie du contrat consommable : utiliser uniquement les exports du crate-root.
|
||||
|
||||
## Utiliser le Pubkey canonique
|
||||
|
||||
Interface réexporte le `Pubkey` possédé par Core afin que les futurs contrats wire puissent partager la même primitive sans wrapper parallèle :
|
||||
## Construire des account metas
|
||||
|
||||
```rust
|
||||
let program_id = ksp_interface_lib::Pubkey::default();
|
||||
let bytes = program_id.to_bytes();
|
||||
assert_eq!(bytes.len(), 32);
|
||||
let readonly_account = ksp_interface_lib::Pubkey::new_from_array([1_u8; 32]);
|
||||
let writable_account = ksp_interface_lib::Pubkey::new_from_array([2_u8; 32]);
|
||||
|
||||
let readonly = ksp_interface_lib::ProgramAccountMeta::readonly(readonly_account, true);
|
||||
let writable = ksp_interface_lib::ProgramAccountMeta::writable(writable_account, false);
|
||||
|
||||
assert_eq!(readonly.pubkey(), &readonly_account);
|
||||
assert!(readonly.is_signer());
|
||||
assert!(!readonly.is_writable());
|
||||
|
||||
assert_eq!(writable.pubkey(), &writable_account);
|
||||
assert!(!writable.is_signer());
|
||||
assert!(writable.is_writable());
|
||||
```
|
||||
|
||||
Un consumer ne doit pas reconstruire une identité Program textuelle propre à Interface. Les Program IDs fondamentaux restent possédés et répertoriés par `ksp-core-lib`.
|
||||
`readonly`/`writable` décrivent uniquement les flags wire de l'account meta. Interface ne valide pas l'identité du compte contre un registry Program.
|
||||
|
||||
## Surface volontairement absente
|
||||
## Construire une instruction passive
|
||||
|
||||
La foundation initiale n'expose encore aucun constructeur d'instruction fonctionnel. Elle ne fournit pas non plus de codec générique Borsh/Wincode, de sérialisation Serde, de transport ou de comportement Program. Ces surfaces sont ajoutées uniquement lorsque leur contrat réel est matérialisé et borné.
|
||||
```rust
|
||||
let program_id = ksp_interface_lib::Pubkey::new_from_array([3_u8; 32]);
|
||||
let account_id = ksp_interface_lib::Pubkey::new_from_array([4_u8; 32]);
|
||||
|
||||
Aucun runtime logging n'est nécessaire pour les contrats passifs actuels ; une future instrumentation comportementale devrait passer par `ksp-logging-lib` selon les règles KSP au lieu d'introduire `tracing` directement.
|
||||
let account = ksp_interface_lib::ProgramAccountMeta::writable(account_id, true);
|
||||
let result = ksp_interface_lib::ProgramInstruction::try_new(
|
||||
program_id,
|
||||
std::vec![account, account],
|
||||
std::vec![7_u8, 8, 9],
|
||||
);
|
||||
|
||||
match result {
|
||||
std::result::Result::Ok(instruction) => {
|
||||
assert_eq!(instruction.program_id(), &program_id);
|
||||
assert_eq!(instruction.accounts(), &[account, account]);
|
||||
assert_eq!(instruction.data(), &[7_u8, 8, 9]);
|
||||
}
|
||||
std::result::Result::Err(error) => {
|
||||
eprintln!("{error}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
L'ordre et les doublons des accounts sont conservés. Les octets `data` restent opaques : `ProgramInstruction` ne les sérialise, désérialise ni interprète.
|
||||
|
||||
Les `Vec` fournis à `try_new` sont consommés par la structure après validation des bornes ; aucun clone ou reformatage interne n'est requis par le contrat actuel.
|
||||
|
||||
## Bornes
|
||||
|
||||
Les limites publiques sont :
|
||||
|
||||
```rust
|
||||
assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_ACCOUNTS, 255);
|
||||
assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_DATA_LEN, 10_240);
|
||||
```
|
||||
|
||||
`255` account metas et `10_240` bytes de data sont admis. `256` account metas ou `10_241` bytes sont refusés par `try_new` avant création d'un `ProgramInstruction` valide.
|
||||
|
||||
Ces limites sont des bornes locales Interface et ne promettent pas qu'une instruction admise respecte à elle seule toutes les contraintes de taille/account-set d'une transaction Solana complète.
|
||||
|
||||
## Observer une erreur de limite
|
||||
|
||||
Le code public est :
|
||||
|
||||
```rust
|
||||
assert_eq!(
|
||||
ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.domain(),
|
||||
"interface",
|
||||
);
|
||||
assert_eq!(
|
||||
ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.code(),
|
||||
"program_instruction_limit_exceeded",
|
||||
);
|
||||
```
|
||||
|
||||
Une erreur de dépassement expose uniquement un contexte structurel sûr :
|
||||
|
||||
```text
|
||||
field
|
||||
actual_len
|
||||
maximum_len
|
||||
```
|
||||
|
||||
Le contenu du payload et les account metas arbitraires ne sont pas projetés dans le diagnostic.
|
||||
|
||||
## Debug borné
|
||||
|
||||
Le `Debug` de `ProgramInstruction` contient uniquement :
|
||||
|
||||
```text
|
||||
program_id
|
||||
account_count
|
||||
data_len
|
||||
```
|
||||
|
||||
Il ne faut donc pas attendre de ce rendu une sérialisation wire ou un dump du payload.
|
||||
|
||||
## Dépendances à ne pas ajouter côté consumer
|
||||
|
||||
Un consumer de la façade Interface n'a pas besoin d'ajouter un SDK Program Solana uniquement pour reconstruire `ProgramInstruction`. La crate utilise le `Pubkey` canonique partagé avec Core et conserve son propre contrat passif.
|
||||
|
||||
La foundation ne fournit volontairement pas :
|
||||
|
||||
```text
|
||||
serde générique
|
||||
Borsh / Wincode générique
|
||||
solana-instruction interop automatique
|
||||
transport réseau
|
||||
Program decoder/preparer
|
||||
signing/execution
|
||||
```
|
||||
|
||||
Ces surfaces doivent être introduites dans leur owner respectif lorsqu'un cas réel le justifie, pas comme dépendances implicites d'un consumer Interface.
|
||||
|
||||
192
deltas/0.2.13/pre.007.md
Normal file
192
deltas/0.2.13/pre.007.md
Normal file
@@ -0,0 +1,192 @@
|
||||
<!-- file: deltas/0.2.13/pre.007.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.2.13-pre.007` — réconciliation documentaire finale Interface
|
||||
|
||||
## 1. Base
|
||||
|
||||
```text
|
||||
0.2.13-pre.006
|
||||
```
|
||||
|
||||
Le gate opérateur de `pre.006`, exécuté le **28 août 2026**, est intégralement vert :
|
||||
|
||||
```text
|
||||
cargo fmt --all PASS
|
||||
audits Rust / export completeness / workspace PASS
|
||||
audit Markdown 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é
|
||||
```
|
||||
|
||||
La lane technique est donc fermée avant cette tranche.
|
||||
|
||||
## 2. Objectif
|
||||
|
||||
`pre.007` est exclusivement le couloir de réconciliation documentaire finale de `0.2.13`. Aucun fichier Rust, test, manifest de crate, dépendance, codec ou comportement n'est modifié.
|
||||
|
||||
La tranche transforme les README/USAGE initiaux d'Interface en références durables et aligne plan, validation, séquence fonctionnelle et index documentaires sur la surface réellement validée.
|
||||
|
||||
## 3. Version technique
|
||||
|
||||
```text
|
||||
0.2.13-pre.6
|
||||
->
|
||||
0.2.13-pre.7
|
||||
```
|
||||
|
||||
Le bump est mécanique pour une prerelease non-fix. Aucun autre manifest/version applicative n'est synchronisé artificiellement.
|
||||
|
||||
## 4. Surface finale candidate documentée
|
||||
|
||||
```text
|
||||
Pubkey réexport Core
|
||||
ProgramAccountMeta passif, champs privés
|
||||
ProgramInstruction passif, champs privés
|
||||
MAX_PROGRAM_INSTRUCTION_ACCOUNTS 255
|
||||
MAX_PROGRAM_INSTRUCTION_DATA_LEN 10_240
|
||||
ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED interface.program_instruction_limit_exceeded
|
||||
```
|
||||
|
||||
Les propriétés réconciliées sont :
|
||||
|
||||
```text
|
||||
accounts ordonnés préservés
|
||||
doublons accounts préservés
|
||||
accounts/data vides acceptés
|
||||
Program Pubkey hors registry accepté
|
||||
Vec accounts/data consommés sans reformatage interne
|
||||
Debug ProgramInstruction program_id/account_count/data_len uniquement
|
||||
erreur de borne field/actual_len/maximum_len uniquement
|
||||
```
|
||||
|
||||
Les limites `255` et `10_240` restent explicitement des bornes d'admission Interface et non une garantie complète de fit transaction Solana top-level.
|
||||
|
||||
## 5. Dependency firewall final
|
||||
|
||||
Le graphe normal confirmé par l'opérateur reste :
|
||||
|
||||
```text
|
||||
ksp-interface-lib
|
||||
└── ksp-core-lib
|
||||
└── solana-pubkey
|
||||
```
|
||||
|
||||
La foundation ne dépend pas de :
|
||||
|
||||
```text
|
||||
serde / serde_json
|
||||
borsh / wincode / bincode
|
||||
solana-instruction
|
||||
Transport / Config / Store / Wallet / Program
|
||||
reqwest / tonic / tokio / Tauri
|
||||
ksp-logging-lib / tracing runtime
|
||||
```
|
||||
|
||||
L'absence de runtime logging est volontaire : la surface actuelle est purement passive.
|
||||
|
||||
## 6. Références durables réconciliées
|
||||
|
||||
```text
|
||||
crates/ksp-interface-lib/README.md
|
||||
crates/ksp-interface-lib/USAGE.md
|
||||
docs/000-README.md
|
||||
docs/plans/000-README.md
|
||||
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
docs/plans/020-V0_2_13_INTERFACE_PLAN.md
|
||||
docs/validation/000-README.md
|
||||
docs/validation/016-V0_2_13_INTERFACE.md
|
||||
```
|
||||
|
||||
Le README Interface fixe l'ownership, la surface publique, les bornes, le modèle d'erreur, le Debug borné, le graphe et les frontières de responsabilité.
|
||||
|
||||
`USAGE.md` documente l'usage crate-root de `ProgramAccountMeta` et `ProgramInstruction`, les accessors, les limites et l'observation des erreurs sans accès aux modules privés.
|
||||
|
||||
La séquence fonctionnelle enregistre le contenu effectivement livré par `0.2.13`, tout en maintenant :
|
||||
|
||||
```text
|
||||
0.2.14 Program API foundation
|
||||
0.3.2+ wires génériques acquisition/CORE
|
||||
```
|
||||
|
||||
## 7. Fichiers ajoutés/modifiés
|
||||
|
||||
Ajouté :
|
||||
|
||||
```text
|
||||
deltas/0.2.13/pre.007.md
|
||||
```
|
||||
|
||||
Modifiés :
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-interface-lib/README.md
|
||||
crates/ksp-interface-lib/USAGE.md
|
||||
docs/000-README.md
|
||||
docs/plans/000-README.md
|
||||
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
docs/plans/020-V0_2_13_INTERFACE_PLAN.md
|
||||
docs/validation/000-README.md
|
||||
docs/validation/016-V0_2_13_INTERFACE.md
|
||||
```
|
||||
|
||||
Aucun fichier supprimé.
|
||||
|
||||
## 8. Surfaces volontairement inchangées
|
||||
|
||||
Cette tranche ne touche pas :
|
||||
|
||||
```text
|
||||
crates/ksp-interface-lib/src/**
|
||||
crates/ksp-interface-lib/tests/**
|
||||
crates/ksp-interface-lib/unit_tests/**
|
||||
crates/ksp-interface-lib/Cargo.toml
|
||||
docs/architecture/**
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
prompts/**
|
||||
```
|
||||
|
||||
Les architectures existantes sont déjà compatibles avec la foundation réellement livrée et ne nécessitent aucune réécriture de clôture.
|
||||
|
||||
## 9. Gate opérateur
|
||||
|
||||
La tranche étant documentaire hors bump workspace, le gate demandé reste déterministe :
|
||||
|
||||
```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.13
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-interface-lib
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Aucun smoke réseau/live ni nouveau `cargo tree` n'est requis si l'overlay est appliqué exactement : ces preuves appartiennent à la lane technique fermée par `pre.006`.
|
||||
|
||||
## 10. Suite
|
||||
|
||||
Si le gate est vert :
|
||||
|
||||
```text
|
||||
0.2.13-pre.008 — préparation minimale de publication
|
||||
```
|
||||
|
||||
`pre.008` reste limitée à :
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
prompts/019-V0_2_14_START_PROMPT.md
|
||||
deltas/0.2.13/pre.008.md
|
||||
```
|
||||
|
||||
Aucun code, test, README/USAGE, plan, validation ou architecture ne doit être rouvert dans cette lane de publication minimale sauf défaut réel découvert au gate.
|
||||
File diff suppressed because one or more lines are too long
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 64 -->
|
||||
<!-- version: 65 -->
|
||||
|
||||
# Plans KSP
|
||||
|
||||
@@ -28,7 +28,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
|
||||
- [`017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) — plan historique clôturé de la release stable `0.2.10 — OrbitFlare Yellowstone gRPC`; il conserve le Devnet gRPC gratuit, N1/N2 immuables, la License Key `x-token` et le smoke final `Slot + Ping`.
|
||||
- [`018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) — plan historique clôturé de `0.2.11 — Off-chain price transport`; SOL/USD V1, huit providers REST sans SDK, registry/availability/rate limits Off-chain et Config `std.offchain_transport`.
|
||||
- [`019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](019-V0_2_12_SOL_PRICES_DESK_PLAN.md) — plan historique clôturé de `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk`; il conserve le gabarit 1434/1435, le composite Config, les DTO/commands provider-neutral, l’intégration Wallet minimale et les gates live/build finaux.
|
||||
- [`020-V0_2_13_INTERFACE_PLAN.md`](020-V0_2_13_INTERFACE_PLAN.md) — plan actif de `0.2.13 — Interface / wire foundation`; il fixe le premier lot passif `ProgramAccountMeta` + `ProgramInstruction`, les bornes, le firewall Interface -> Core, l’héritage kbot3 retenu/rejeté et la frontière avec Program API/RAW/CORE.
|
||||
- [`020-V0_2_13_INTERFACE_PLAN.md`](020-V0_2_13_INTERFACE_PLAN.md) — plan candidat réconcilié de `0.2.13 — Interface / wire foundation`; il fixe la surface finale `ProgramAccountMeta` + `ProgramInstruction`, les bornes `255` / `10_240`, le firewall Interface -> Core, les canaris de complétude/consumer externe et la frontière avec Program API/RAW/CORE.
|
||||
|
||||
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
||||
<!-- version: 93 -->
|
||||
<!-- version: 94 -->
|
||||
|
||||
# Séquence des releases fonctionnelles KSP
|
||||
|
||||
@@ -520,9 +520,11 @@ Metadata HTTP/IPFS/Arweave viendra au premier besoin Metadata réel. SOL/EUR et
|
||||
|
||||
### `0.2.13` — Interface foundation
|
||||
|
||||
`ksp-interface-lib` devient la façade wire officielle et expose une API publique wire utilisable par les implementations officielles et externes.
|
||||
`ksp-interface-lib` matérialise la première façade wire officielle KSP, volontairement passive et Program-facing. La surface candidate stable réexporte le `Pubkey` canonique de Core et expose `ProgramAccountMeta` ainsi que `ProgramInstruction` avec champs privés, accessors explicites et admission bornée à `255` account metas et `10_240` bytes de data. L'ordre et les doublons sont conservés, les Program Pubkeys opaques restent acceptés et les diagnostics ne recopient ni payload ni account material arbitraire.
|
||||
|
||||
Aucune `ksp-interface-api` séparée n'est retenue pour l'instant.
|
||||
La dependency direction reste strictement `Interface -> Core`; aucun serde/codec générique, `solana-instruction`, runtime réseau ou logging n'est introduit. La façade crate-root est verrouillée par canaris public API, consumer externe, release completeness et dependency firewall. [`../../crates/ksp-interface-lib/README.md`](../../crates/ksp-interface-lib/README.md) et [`../../crates/ksp-interface-lib/USAGE.md`](../../crates/ksp-interface-lib/USAGE.md) deviennent les références durables de cette foundation. Le gate technique final `pre.006` est vert avant réconciliation documentaire.
|
||||
|
||||
Aucune `ksp-interface-api` séparée n'est retenue pour l'instant. Les codecs/layouts spécifiques restent conditionnés à un vertical réel, tandis que les wires génériques d'acquisition/CORE restent reportés à `0.3.2+`.
|
||||
|
||||
### `0.2.14` — Program API foundation
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/020-V0_2_13_INTERFACE_PLAN.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Plan `0.2.13` — Interface / wire foundation
|
||||
|
||||
@@ -407,15 +407,15 @@ Fermer les cas limites, surface crate-root, consumer externe, firewall source/ma
|
||||
|
||||
### pre.006 — gate technique final
|
||||
|
||||
**Statut : préparé ; gate opérateur à confirmer.**
|
||||
**Statut : réalisé ; gate opérateur intégralement PASS.**
|
||||
|
||||
Exécuter workspace complet, canaris de complétude/public API/dependencies, `cargo tree` et audit final du scope exact. Aucun README/USAGE final ni préparation de publication.
|
||||
Workspace complet, canaris de complétude/public API/dependencies, ownership Logging, `cargo tree` et audit final du scope exact sont validés. Aucun README/USAGE final ni préparation de publication n'a été mélangé à cette tranche.
|
||||
|
||||
### pre.007 — réconciliation documentaire finale
|
||||
|
||||
**Statut : prévu**
|
||||
**Statut : réalisé ; gate opérateur documentaire à confirmer.**
|
||||
|
||||
Finaliser README/USAGE de la crate, plan, validation et références durables réellement affectées. Ne pas modifier `CHANGELOG.md`, `ROADMAP.md` ni le prompt suivant.
|
||||
README/USAGE Interface, plan, validation, séquence fonctionnelle et index documentaires réellement affectés sont réconciliés. `CHANGELOG.md`, `ROADMAP.md` et le prompt suivant restent réservés à `pre.008`.
|
||||
|
||||
### pre.008 — préparation de publication minimale
|
||||
|
||||
@@ -571,7 +571,7 @@ Pubkey
|
||||
|
||||
Il verrouille également l'absence de `pub mod` et l'inventaire exact des quatre fichiers Rust de production. Ajouter une seconde famille wire dans `0.2.13` ferait ainsi échouer explicitement le canari de complétude au lieu d'élargir silencieusement la release.
|
||||
|
||||
Le hardening unitaire vérifie enfin que les allocations des `Vec` admis sont transférées telles quelles dans `ProgramInstruction` et que les erreurs de dépassement n'échoient ni marqueur hostile de payload ni représentation arbitraire d'account meta. Ces tests renforcent le contrat de construction sans changer l'API publique.
|
||||
Le hardening unitaire vérifie enfin que les allocations des `Vec` admis sont transférées telles quelles dans `ProgramInstruction` et que les erreurs de dépassement ne recopient ni marqueur hostile de payload ni représentation arbitraire d'account meta. Ces tests renforcent le contrat de construction sans changer l'API publique.
|
||||
|
||||
Après validation opérateur de `pre.005`, `pre.006` doit rester un gate technique pur sans nouveau développement fonctionnel.
|
||||
|
||||
@@ -605,11 +605,24 @@ Aucun fichier `src/` de production, aucune dépendance, aucune API publique, auc
|
||||
|
||||
Le gate opérateur du fix est désormais intégralement vert : fmt, audits Rust/Markdown, `cargo check --workspace`, Clippy, tests Interface, canari Logging ciblé, `cargo test --workspace` et graphes Cargo sont tous validés/inspectés. Le faux positif est donc fermé sans élargissement du scope.
|
||||
|
||||
## 21. Gate technique final préparé `pre.006`
|
||||
## 21. Gate technique final validé `pre.006`
|
||||
|
||||
`pre.006` n'ajoute aucun code, aucun test et aucune dépendance. Les canaris existants couvrent déjà la surface publique, le consumer externe, les bornes, le Debug borné, les erreurs sûres, l'inventaire exact et le firewall de dépendances.
|
||||
`pre.006` n'a ajouté aucun code, aucun test et aucune dépendance. Le gate opérateur du **28 août 2026** ferme la lane technique avec les preuves suivantes :
|
||||
|
||||
La tranche se limite à figer l'état technique suivant avant réconciliation documentaire :
|
||||
```text
|
||||
cargo fmt --all PASS
|
||||
audits Rust / export completeness / workspace PASS
|
||||
audit Markdown 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é
|
||||
```
|
||||
|
||||
La surface technique finale avant documentation reste donc :
|
||||
|
||||
```text
|
||||
workspace.package.version 0.2.13-pre.6
|
||||
@@ -623,20 +636,37 @@ ksp-logging-lib / tracing runtime Interface absents
|
||||
network/live smoke N/A pour foundation wire pure
|
||||
```
|
||||
|
||||
Le gate opérateur final à rejouer est :
|
||||
Le gate `pre.006` autorise la réconciliation documentaire finale sans réouverture technique.
|
||||
|
||||
```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.13
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-interface-lib
|
||||
cargo test -p ksp-logging-lib --test ownership
|
||||
cargo test --workspace
|
||||
cargo tree -p ksp-interface-lib --edges normal
|
||||
cargo tree --duplicates
|
||||
## 22. Réconciliation documentaire finale `pre.007`
|
||||
|
||||
`pre.007` ne modifie aucun fichier Rust, test, manifest de crate, dépendance ou comportement. La version workspace avance mécaniquement à `0.2.13-pre.7` conformément au workflow de prerelease non-fix.
|
||||
|
||||
Les références durables sont réconciliées autour du contrat réellement livré :
|
||||
|
||||
```text
|
||||
crates/ksp-interface-lib/README.md
|
||||
crates/ksp-interface-lib/USAGE.md
|
||||
docs/000-README.md
|
||||
docs/plans/000-README.md
|
||||
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
docs/plans/020-V0_2_13_INTERFACE_PLAN.md
|
||||
docs/validation/000-README.md
|
||||
docs/validation/016-V0_2_13_INTERFACE.md
|
||||
```
|
||||
|
||||
Après gate vert, `pre.007` est autorisé et devient exclusivement la réconciliation documentaire finale.
|
||||
Le README Interface fixe l'ownership, la surface crate-root exacte, les deux bornes d'admission, le modèle d'erreur sûr, le Debug borné, le graphe `Interface -> Core`, l'absence de codecs/logging/runtime et les frontières avec Program API/Transport/Store. `USAGE.md` documente les constructeurs `readonly`/`writable`, `ProgramInstruction::try_new`, les accessors, les bornes et l'observation des erreurs sans dépendre des modules privés.
|
||||
|
||||
La séquence fonctionnelle précise désormais le contenu réellement livré par `0.2.13` et maintient les reports : Program API en `0.2.14`, wires génériques acquisition/CORE en `0.3.2+`. Les index plan/validation passent du statut actif au statut candidat réconcilié sans annoncer prématurément la release stable.
|
||||
|
||||
La tranche ne touche explicitement pas :
|
||||
|
||||
```text
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
prompts/019-V0_2_14_START_PROMPT.md
|
||||
architecture
|
||||
code/tests/manifests de crate
|
||||
```
|
||||
|
||||
Ces surfaces appartiennent à `pre.008` pour la préparation minimale de publication, sauf découverte d'un défaut réel imposant une nouvelle tranche corrective.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/000-README.md -->
|
||||
<!-- version: 28 -->
|
||||
<!-- version: 29 -->
|
||||
|
||||
# Validations KSP
|
||||
|
||||
@@ -24,4 +24,4 @@ Documents :
|
||||
- [`013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) — matrice finale de la release stable `0.2.10` : Free Devnet, auth `x-token`, endpoint security, heartbeat standard, Config V3, smoke live `Slot + Ping` et invariant N1/N2 immuable.
|
||||
- [`014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) — matrice historique clôturée de `0.2.11` : SOL/USD multi-provider, numeric safety, rate limiting/availability, Config capability-aware et smoke keyless final `7/7`.
|
||||
- [`015-V0_2_12_SOL_PRICES_DESK.md`](015-V0_2_12_SOL_PRICES_DESK.md) — matrice historique clôturée de `0.2.12` : screen/features, DTO/commands, Config/composite, frontières provider-neutral, sécurité, Wallet integration, packaging Tauri et gates live/build.
|
||||
- [`016-V0_2_13_INTERFACE.md`](016-V0_2_13_INTERFACE.md) — matrice active ouverte par `0.2.13-pre.001` : ownership Interface/Core/Transport/Program, héritage kbot3, surface instruction passive, bornes/adversarial, façade publique et dependency firewall.
|
||||
- [`016-V0_2_13_INTERFACE.md`](016-V0_2_13_INTERFACE.md) — matrice candidate finale de `0.2.13` : ownership Interface/Core/Transport/Program, surface passive, bornes/adversarial, façade publique exacte, consumer externe, release completeness, dependency firewall et gate technique `pre.006` intégralement vert.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/016-V0_2_13_INTERFACE.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Validation `0.2.13` — Interface / wire foundation
|
||||
|
||||
@@ -89,12 +89,12 @@ aucun comportement Program
|
||||
| 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 | TODO pre.004 |
|
||||
| account bound | constante publique `<= 255`; enforcement constructeur | PASS/PENDING |
|
||||
| data bound | `<= 10_240` | TODO pre.004 |
|
||||
| `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 | TODO pre.004 |
|
||||
| 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
|
||||
@@ -142,30 +142,32 @@ Si une nouvelle dépendance externe apparaît après `pre.001`, la présente mat
|
||||
|
||||
| Famille | Attendu | Statut |
|
||||
|--------------------------|-------------------------------------------------|--------------|
|
||||
| unit tests privés | account meta/borne puis instruction/adversarial | PASS pre.004 |
|
||||
| `tests/public_api.rs` | consommation crate-root uniquement | PASS pre.004 |
|
||||
| external consumer canary | surface utilisable hors modules privés | PASS pre.005 |
|
||||
| dependency boundary | firewall exact | PASS pre.004 |
|
||||
| release completeness | inventaire exact, aucun domaine supplémentaire | PASS pre.005 |
|
||||
| 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 attendu
|
||||
## 11. Gate technique final validé
|
||||
|
||||
Avant réconciliation documentaire :
|
||||
Le gate opérateur `0.2.13-pre.006` du **28 août 2026** ferme la lane technique :
|
||||
|
||||
```text
|
||||
cargo fmt --all PASS attendu
|
||||
python3 scripts/audit_rust_workspace_rules.py PASS attendu
|
||||
python3 scripts/audit_markdown_tables.py ... PASS attendu
|
||||
cargo check --workspace PASS attendu
|
||||
cargo clippy --workspace --all-targets PASS attendu
|
||||
cargo test --workspace PASS attendu
|
||||
cargo tree -p ksp-interface-lib --edges normal inspecté
|
||||
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é par défaut.
|
||||
Aucun smoke réseau/live n'est exigé : la crate reste une foundation wire pure sans I/O.
|
||||
|
||||
## 12. État `pre.001`
|
||||
|
||||
@@ -332,24 +334,38 @@ cargo test --workspace PASS
|
||||
cargo tree Interface Core-only confirmé
|
||||
```
|
||||
|
||||
## 18. Gate technique final préparé `pre.006`
|
||||
## 18. Gate technique final `pre.006`
|
||||
|
||||
Aucun nouveau canari n'est nécessaire : le gate `pre.005-fix.001` a déjà exécuté avec succès tous les tests ciblés et workspace sur la surface complète. `pre.006` change uniquement la version technique et la traçabilité du gate final.
|
||||
|
||||
État à confirmer par l'opérateur :
|
||||
Le gate final a confirmé la surface complète sans nouvelle modification technique :
|
||||
|
||||
```text
|
||||
cargo fmt --all PASS attendu
|
||||
audits Rust / export completeness / workspace PASS attendus
|
||||
audit Markdown PASS attendu
|
||||
cargo check --workspace PASS attendu
|
||||
cargo clippy --workspace --all-targets PASS attendu
|
||||
cargo test -p ksp-interface-lib PASS attendu
|
||||
cargo test -p ksp-logging-lib --test ownership PASS attendu
|
||||
cargo test --workspace PASS attendu
|
||||
cargo tree -p ksp-interface-lib --edges normal Core-only attendu
|
||||
cargo tree --duplicates inspecté attendu
|
||||
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
|
||||
```
|
||||
|
||||
La validation technique sera considérée fermée uniquement après ce gate. Aucun smoke réseau n'est requis pour cette foundation wire pure.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user