Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e39cf656b20dd906209e9d4daef73c052e729ca4
khadhroony-solana-project/prompts/018-V0_2_13_START_PROMPT.md

39 KiB
Raw Blame History

Prompt de démarrage 0.2.13 — Interface / wire foundation

1. Identité de la release et base exacte requise

La base attendue est exclusivement la release stable :

v0.2.12

Ne pas ouvrir 0.2.13 depuis :

0.2.12-pre.*
0.2.12-pre.*-fix.*
0.2.12-rel.* non encore validé stable
une archive intermédiaire de travail
l'ancien dépôt khadhroony-bot3
un souvenir de session

Si une archive opérateur de v0.2.12 est fournie au démarrage, cette archive réelle est la première autorité devant les snippets, anciennes archives, anciens prompts et mémoire de conversation. Une divergence entre la base réelle et ce prompt déclenche un audit explicite ; elle ne se résout jamais par supposition.

La release à ouvrir est :

0.2.13 — Interface / wire foundation

La première tranche est :

0.2.13-pre.001

pre.001 est obligatoirement une tranche lecture + audit interne + audit d'héritage kbot3 + audit externe ciblé + brainstorming + frontières + dependency graph + threat/robustness model + sizing + planification.

Aucune API wire lourde, aucun trait Program et aucun portage de code kbot3 ne doit commencer avant la sortie cohérente de ce gate.

À l'ouverture, vérifier au minimum :

git describe / tag stable si metadata Git disponible
workspace.package.version = 0.2.12
deltas/0.2.12/rel.001.md présent
prompts/018-V0_2_13_START_PROMPT.md présent
ksp-interface-lib absent au démarrage sauf contradiction de la base réelle
ksp-program-api absent au démarrage sauf contradiction de la base réelle

2. Mission et résultat attendu

La mission de 0.2.13 est d'introduire la première surface de ksp-interface-lib, conformément à l'architecture KSP actuelle :

façade wire officielle KSP
API publique wire réutilisable
contrats passifs / codecs / validation locale
pas de comportement Program
pas de runtime réseau
pas de persistence

La release doit préparer proprement :

0.2.14 — ksp-program-api foundation

sans implémenter cette release par anticipation.

Résultat attendu à la clôture, sous réserve du scope exact décidé en pre.001 :

ksp-interface-lib existe comme crate membre du workspace
façade publique explicite via crate root
surface wire minimale réellement justifiée par le futur Program API
ownership Core / Interface / Program clairement séparé
codec(s) wire seulement si un contrat réel l'exige
validation/bornes déterministes des données exposées
aucune logique decode/reconnaissance/exécution/materialisation
aucune dépendance reverse vers Transport/Store/Wallet/App
aucune dépendance protocolaire opportuniste non auditée
canari consumer externe/public API
canaris de dependency firewall
round-trips/adversarial tests si sérialisation retenue
README/USAGE durables réconciliés avant publication
plan/validation de release complets
prompt 0.2.14 préparé dans le couloir final dédié

Le résultat n'est pas de recréer un modèle universel de transaction/replay ni de remplir Interface par symétrie avec l'ancien ks-lib.

La question centrale de la release est :

quel est le minimum wire public KSP-owned qu'il faut stabiliser maintenant pour que ksp-program-api puisse être conçu proprement en 0.2.14, sans anticiper les wires génériques RAW/CORE réservés aux séries suivantes ?

3. Sources de vérité internes obligatoires — ordre de lecture

3.1 Règles globales

Lire d'abord, dans cet ordre :

RULES.md
docs/000-README.md

docs/rules/RULES_GENERAL.md
docs/rules/RULES_KSP.md
docs/rules/RULES_RUST.md
docs/rules/RULES_DEPENDENCIES.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/PROMPT_STRUCTURE.md

Le présent prompt est un contrat opératoire autonome, mais ne remplace aucune règle normative.

Rappels qui conditionnent directement cette release :

Rust 2024
unsafe / unwrap / expect / panic interdits selon les règles KSP
? interdit en production selon les lints KSP
#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]

pas de pub mod comme raccourci de façade
surface publique réexportée explicitement depuis crate root
unit tests sous unit_tests/ autant que possible
tests/ réservé aux tests d'intégration consommant l'API publique
Error/Result communs possédés par ksp-core-lib
Program IDs fondamentaux possédés par ksp-core-lib
Pubkey consommé via ksp-core-lib lorsque la frontière KSP l'exige

Règles wire/dependency à relire particulièrement :

KSP-WIRE-001..003
DEP-WIRE-001..007
DEP-PROGRAM-001..004
DEP-KSP-001..005
DEP-CARGO-001..007

Après toute modification Rust :

cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets

Pour tout Markdown touché :

python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.13

Une commande non exécutée n'est jamais déclarée PASS.

3.2 Architecture durable à préserver

Lire ensuite, dans cet ordre :

docs/architecture/000-README.md
docs/architecture/001-PROJECT_OBJECTIVES.md
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
docs/architecture/003-COMPONENT_CONTRACTS.md
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/architecture/006-WIRE_AND_PROGRAM.md
docs/architecture/007-EXECUTION_AND_POLICY.md
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md

docs/architecture/006-WIRE_AND_PROGRAM.md est la référence architecturale centrale de cette release.

Points acquis à préserver :

ksp-interface-lib = façade wire officielle + API wire publique
pas de ksp-interface-api séparée actuellement
Program IDs fondamentaux restent dans Core
Interface peut posséder codecs/layouts/discriminants/seeds/constructeurs wire lorsqu'ils appartiennent réellement au contrat
Interface ne possède pas interprétation métier/decode Program/policy/exécution réseau
ksp-program-api est ouvert/extensible et vient ensuite
ksp-program-lib porte plus tard les implémentations officielles
une extension externe peut consommer les wires officiels sans dépendre de ksp-program-lib
RAW -> CORE reste générique et ne dépend pas de Program
CORE -> DECODE est la première frontière qui peut utiliser Program API

Ne pas remplacer ces décisions par la structure de kbot3.

3.3 Plans, roadmap et clôture 0.2.12

Relire :

ROADMAP.md
CHANGELOG.md

docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md
docs/validation/015-V0_2_12_SOL_PRICES_DESK.md

deltas/0.2.12/rel.001.md

Le but n'est pas de rouvrir 0.2.12, mais de confirmer la base stable et la séquence retenue :

0.2.13 interface/wire foundation
0.2.14 program-api foundation
0.3.1 Store RAW
0.3.2 extension Interface pour wires génériques acquisition/CORE

Cette séquence est une contrainte importante : 0.2.13 ne doit pas absorber prématurément 0.3.2.

3.4 Code réel à inventorier avant design

Inventorier au minimum :

Cargo.toml
crates/ksp-core-lib/Cargo.toml
crates/ksp-core-lib/src/lib.rs
crates/ksp-core-lib/src/program_ids.rs

crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/src/lib.rs
crates/ksp-onchain-transport-lib/src/rpc_common.rs
crates/ksp-onchain-transport-lib/src/rpc_accounts.rs
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
crates/ksp-onchain-transport-lib/src/rpc_blocks.rs
crates/ksp-onchain-transport-lib/src/ws_*.rs selon types réellement pertinents
crates/ksp-onchain-transport-lib/src/grpc_*.rs selon types réellement pertinents

L'inventaire doit distinguer :

type fondamental déjà possédé par Core
wire/provider DTO privé de Transport
type générique potentiellement partageable mais actuellement transport-owned
contrat nouveau réellement nécessaire à Interface
type qui appartient seulement à RAW/CORE plus tard

Ne pas déplacer un DTO Transport vers Interface uniquement pour réduire une duplication apparente. Ownership et stabilité priment.

4. Sources externes normatives à réauditer en pre.001

La release ne doit pas figer un wire Solana ou choisir un codec depuis des souvenirs historiques.

Selon le scope candidat retenu pendant l'audit, consulter en priorité les sources officielles et actuelles suivantes :

Documentation officielle Solana / Anza correspondant aux structures wire réellement ciblées
sources Agave / crates officielles actuelles lorsque leur comportement wire fait autorité
crates officielles d'interface Solana/Anza candidates à un réexport contrôlé
API actuelle de solana-pubkey déjà utilisée par Core
sources primaires des codecs candidats : borsh, wincode ou équivalent seulement si un besoin réel existe

Pour toute crate candidate :

vérifier version stable réellement courante
vérifier ownership/source officielle ou normative
vérifier MSRV/edition/features utiles si pertinents
vérifier default-features et features réellement nécessaires
inspecter dépendances transitives fondamentales
cargo tree -d
cargo tree -i <codec-ou-primitive> si ajouté

L'exemple historique solana-loader-v3-interface dans l'architecture doit être réaudité s'il devient pertinent ; il n'est pas une dépendance obligatoire. De même, le rejet historique de mpl-token-metadata illustre une politique de contrôle du wire, pas une règle imposant son implémentation dans 0.2.13.

Aucun résultat externe ancien n'est considéré frais par défaut.

5. État validé à préserver depuis v0.2.12

5.1 Workspace et Core

État attendu :

workspace Rust 2024 stable
ksp-core-lib possède Error / ErrorCode / ErrorContext / Result
ksp-core-lib réexporte la Pubkey KSP
ksp-core-lib possède le registry des Program IDs fondamentaux
18 Program IDs fondamentaux couverts par les canaris actuels
ksp-interface-lib absent
ksp-program-api absent

0.2.13 ne doit pas déplacer les Program IDs fondamentaux hors de Core.

5.2 Transport

Les transports on-chain sont déjà fonctionnels et séparés :

HTTP typed complet
WebSocket standard
Helius LaserStream WebSocket
Yellowstone gRPC standard/provider-neutral

Ils restent propriétaires de leurs DTOs réseau/provider et ne doivent pas acquérir une dépendance vers Interface/Program par commodité.

Frontière durable :

Transport -X-> ksp-interface-lib sauf besoin architectural explicitement décidé plus tard
Transport -X-> ksp-program-api
Transport -X-> ksp-program-lib

0.2.13 n'est pas une refactorisation générale de Transport.

5.3 Off-chain, Wallet et Desks

Les surfaces stabilisées jusqu'à 0.2.12 restent hors chantier :

ksp-offchain-transport-lib
ksp-wallet-lib
ksp-app-config-desk
ksp-app-wallet-desk
ksp-app-solprices-desk

Ne pas les modifier pour démontrer Interface, sauf si un gate de dépendance global révèle une violation préexistante directement bloquante et que le workflow impose une tranche dédiée.

5.4 Pipeline durable

Préserver :

RAW -> CORE -> DECODE -> SPECIALIZED

Avec :

RAW -> CORE -X-> Program API
RAW -> CORE -X-> Program Lib
CORE -> DECODE peut utiliser Program API plus tard

Les modèles d'acquisition/replay/store ne sont pas la mission de 0.2.13.

6. Décisions acquises — ne pas redébattre sans contradiction réelle

Les décisions suivantes sont considérées acquises :

  1. la crate cible s'appelle ksp-interface-lib ;
  2. aucune crate ksp-interface-api séparée n'est créée par symétrie ;
  3. ksp-interface-lib expose une API wire publique réutilisable par les implémentations officielles et externes ;
  4. ksp-interface-lib ne dépend pas de ksp-program-api ni de ksp-program-lib ;
  5. ksp-program-api est réservé à 0.2.14 ;
  6. ksp-program-lib et les implémentations officielles concrètes sont reportés à des vertical slices ultérieures ;
  7. Program IDs fondamentaux et Pubkey KSP restent possédés par Core ;
  8. les codecs wire officiels utilisés directement par KSP appartiennent normalement à Interface ;
  9. une crate protocolaire externe incompatible peut être remplacée par une implémentation KSP bornée ;
  10. une extension Program externe peut temporairement posséder son propre wire lorsqu'Interface ne le possède pas encore ;
  11. l'ancien khadhroony-bot3 est une source d'idées, jamais une autorité architecturale ;
  12. aucun monolithe équivalent à l'ancien ks-lib n'est recréé ;
  13. la compatibilité automatique avec les anciens types kbot3 n'est pas un objectif ;
  14. 0.3.2 reste propriétaire de l'extension Interface nécessaire aux acquisitions et à la normalisation CORE ;
  15. une release concrète doit rester clôturable dans une seule session et être réduite si le sizing est négatif.

Une contradiction avec la base stable réelle se traite par audit et décision documentée, pas par réécriture silencieuse de ces acquis.

7. Questions réellement ouvertes à trancher pendant pre.001

7.1 Premier périmètre wire concret

Décider ce qui constitue réellement la première surface de ksp-interface-lib :

scaffold + primitives publiques uniquement
wire Program générique minimal
autre lot officiel minimal démontré par l'architecture

Ne pas forcer une famille de types parce qu'elle existait dans kbot3.

7.2 Frontière Program-facing vs acquisition-facing

Pour chaque candidat — instruction identity, CPI path, account meta, logs, return data, transaction failure, balance deltas, contexte de replay — décider explicitement :

nécessaire à Program API dès 0.2.14
utile mais acquisition/CORE -> reporter 0.3.2+
spécifique à un transport -> rester Transport
spécifique à un Program concret -> vertical slice ultérieure

7.3 Réutilisation Core vs nouveau wrapper

Déterminer :

quand utiliser directement ksp_core_lib::Pubkey
quand créer un newtype KSP-owned
quand un simple alias serait insuffisant
quels identifiants ont déjà un owner canonique

Aucun wrapper ne doit être créé uniquement pour renommer un type stable déjà possédé par Core.

7.4 Représentation des bytes et bornes

Si la surface contient des données binaires :

Vec<u8> borné ?
newtype borné ?
encodage texte seulement à la frontière serde ?
limites maximales exactes ou conservatrices ?
validation avant allocation pathologique ?
Debug complet, résumé ou redacted/bounded ?

La décision doit être justifiée par le wire réel et les usages publics.

7.5 Sérialisation et codecs

Décider si serde, borsh, wincode ou autre est réellement requis dans 0.2.13.

Questions :

le contrat public a-t-il besoin d'un round-trip stable dès maintenant ?
le codec appartient-il au wire du protocole ou seulement à un stockage futur ?
une crate officielle actuelle peut-elle être réexportée/wrappée proprement ?
une réimplémentation KSP est-elle préférable à un graphe incompatible ?

Ne pas ajouter plusieurs codecs « pour préparer la suite ».

7.6 Versionnement du contrat wire

Ne pas introduire format_version, contract_version ou enum V1/V2 par réflexe.

Si une version explicite est retenue, documenter :

ce qui est versionné
pourquoi l'évolution incompatible est plausible
qui choisit/interprète la version
comment unknown/future est traité

7.7 Error model et validation locale

Décider quelles erreurs sont :

construction invalide
borne dépassée
wire malformed
unsupported local
invariant structurel

Utiliser l'Error KSP commun lorsque cela correspond au contrat actuel. Ne pas inventer une hiérarchie d'erreurs Program avant ksp-program-api.

7.8 Surface d'extension externe

Définir le canari minimum prouvant qu'une crate externe peut :

dépendre de ksp-interface-lib
importer uniquement les exports crate-root
construire/lire les types publics retenus
sérialiser/désérialiser si cette capacité fait partie du contrat
ne pas dépendre de modules privés ni de ksp-program-lib

7.9 Héritage kbot3

Pour les concepts historiques pertinents, produire une matrice :

REPRENDRE
REDESSINER
REPORTER
REJETER

Chaque ligne doit expliquer pourquoi, et vers quelle couche/version un report est effectué.

7.10 Sizing

Confirmer que le scope retenu tient dans une release/session.

Si le premier wire officiel complet est trop large :

réduire 0.2.13 au socle public réellement nécessaire
reporter les familles additionnelles
ne pas ouvrir plusieurs protocoles en parallèle

8. Héritage khadhroony-bot3 — audit historique contrôlé

L'archive historique fournie avant la publication de v0.2.12 est :

khadhroony-bot3_v0.5.3-pre.005-fix010.zip

Elle peut être redonnée dans la nouvelle session pour inspection complète.

La reconnaissance préalable a identifié dans l'ancien ks-lib plusieurs familles d'idées :

identités et modèles wire
instruction path / contexte CPI
accounts résolus / instruction accounts
payload brut / return data / logs
état d'échec transaction
version de contrat

contrats decoder historiques
identity / surfaces / coverage
recognize / outcome
diagnostics / proof
external decoder canaries

contrats execution/materialization historiques
prepared execution plans
required signers / policy
materializer contracts

Deux leçons négatives sont déjà acquises :

ancien ks-lib = monolithe de plusieurs centaines de fichiers
plusieurs générations de Decoder API y coexistent

Donc :

  • ne copier aucun dossier/module entier ;
  • ne conserver aucun nom historique uniquement pour compatibilité ;
  • ne créer aucun trait Decoder/Executor/Materializer dans 0.2.13 ;
  • ne considérer un type historique que si son concept répond à un besoin KSP actuel démontré ;
  • comparer l'idée à l'architecture KSP avant de comparer le code ligne par ligne.

Si l'archive n'est pas disponible au démarrage, ne pas inventer ses détails. Utiliser seulement le seed ci-dessus et signaler les points nécessitant une nouvelle inspection opérateur.

9. Objectifs et livrables de 0.2.13

Le scope exact est recalibré par pre.001, mais la release doit viser les livrables suivants.

9.1 Crate et façade

crates/ksp-interface-lib/
Cargo.toml
src/lib.rs
README.md
USAGE.md
unit_tests/
tests/

La crate respecte les conventions workspace et n'expose pas ses modules privés comme API.

9.2 Surface wire publique

Le lot retenu doit posséder :

rustdoc public
constructeurs/validation explicites si nécessaires
invariants et bornes définis
ordre sémantique préservé
états optionnels fidèles au wire réel
Debug maîtrisé
serde/codec seulement si décidé

9.3 Dependency firewall

Prouver au minimum :

Interface -> Core autorisé
Interface -X-> Program API
Interface -X-> Program Lib
Interface -X-> Config
Interface -X-> Transport
Interface -X-> Store
Interface -X-> Wallet
Interface -X-> Tauri
Interface -X-> reqwest / tonic / runtime réseau

Une dépendance logging n'est ajoutée que si un comportement runtime réel à instrumenter existe ; une crate wire déclarative ne doit pas ajouter Logging par réflexe.

9.4 Consumer externe

Créer un canari integration/downstream-style démontrant que la surface voulue est consommable uniquement via l'API publique.

9.5 Documentation et validation

pre.001 doit créer :

docs/plans/020-V0_2_13_INTERFACE_PLAN.md
docs/validation/016-V0_2_13_INTERFACE.md

Ces noms sont la suite documentaire attendue si la base stable ne contient pas déjà ces numéros. En cas de contradiction réelle, conserver la nomenclature effective de la base et documenter l'écart.

10. Hors périmètre explicite

Ne pas implémenter dans 0.2.13 :

ksp-program-api
ksp-program-lib
ProgramInstructionDecoder
ProgramAccountDecoder
ProgramEventDecoder
ProgramReturnDataDecoder
registry comportemental Program
recognition / coverage / decoder outcome définitifs
ProgramExecutionPreparer
PreparedProgramExecution définitif
materializer
execution policy
execution orchestration
System/SPL/Token-2022/Metadata/Anchor/DEX decoder concret
IDL parser/generator
Store/persistence RAW ou CORE
replay ledger / claims / jobs / workers
application Tauri
provider réseau
plugin dynamique / ABI C / WASM sandbox
compatibilité automatique avec ks-lib
migration des anciens modèles kbot3

Ne pas implémenter non plus un modèle complet :

RawBlock
CoreTransactionReplayInput
CoreInstructionReplayInput
pipeline acquisition universel

uniquement parce que ces structures pourront être utiles plus tard. Les wires génériques d'acquisition/CORE restent notamment attendus en 0.3.2.

11. Contraintes sécurité, API et architecture spécifiques

11.1 Robustesse des données

Toute donnée de taille variable doit avoir une politique explicite :

limite
moment de validation
allocation
conversion
Debug
serde

Rejeter avant allocation/copie pathologique lorsque techniquement possible.

11.2 Fidélité wire

Ne pas confondre :

absent
null / None lorsque le wire le permet
empty
zero
unknown/future

Ne pas normaliser une distinction wire utile pour simplifier l'API.

11.3 Ordre

Préserver l'ordre lorsque Solana lui donne une sémantique :

account metas
instruction accounts
instruction order
CPI path si retenu

Ne pas remplacer une séquence ordonnée par une map/set sans justification.

11.4 Numeric safety

Aucune vérité canonique lossless ne passe par f32/f64.

Les slots, indexes, offsets, lengths et counts utilisent des types/bornes compatibles avec le wire réel et les conversions sont vérifiées.

11.5 API évolutive

Pour les enums publics susceptibles d'acquérir de nouvelles variantes externes, évaluer #[non_exhaustive] explicitement.

Ne pas appliquer #[non_exhaustive] mécaniquement à chaque enum ; documenter le choix lorsqu'il affecte l'extensibilité downstream.

11.6 Debug et données volumineuses

Une structure contenant des bytes ou collections potentiellement importantes ne doit pas produire accidentellement un Debug gigantesque.

Choisir selon le contrat :

Debug dérivé sûr et borné par construction
Debug custom résumant length/hash/metadata non sensible
pas de Debug public si inutile

11.7 Pas de comportement Program prématuré

Une méthode passive de validation/codec/constructeur wire est autorisée lorsqu'elle appartient au contrat de données.

Une méthode qui choisit :

quel decoder
si une instruction est reconnue
quelle sémantique canonique produire
comment matérialiser
comment exécuter

appartient aux couches Program/Materializer/Execution ultérieures.

12. Première mission 0.2.13-pre.001 — gate obligatoire

12.1 Baseline stable

Avant toute modification lourde :

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 --workspace

Pour une base stable intacte, cargo fmt --all ne doit pas servir à introduire des modifications opportunistes. Si une commande modifie ou échoue sur la base stable, documenter le constat avant d'avancer.

12.2 Audit interne complet

Produire un inventaire concret :

Core public API utile
Program IDs / Pubkey ownership
DTOs Transport potentiellement ressemblants
règles wire/dependency
architecture 006
roadmap 0.2.13 / 0.2.14 / 0.3.2
workspace dependencies actuelles

Pour chaque type candidat déjà existant :

owner actuel
visibilité
consumer actuel
sémantique
raison éventuelle de réutiliser / laisser en place / redessiner

12.3 Audit kbot3

Si l'archive est disponible :

  1. inventorier uniquement les familles pertinentes ;
  2. identifier les concepts, pas seulement les noms de fichiers ;
  3. produire la matrice REPRENDRE / REDESSINER / REPORTER / REJETER ;
  4. distinguer clairement les idées Interface des idées Program API/Program Lib/Materializer/Execution ;
  5. noter les anti-patterns historiques à ne pas reproduire.

Ne pas porter de code pendant cette étape.

12.4 Audit externe actuel

Pour chaque dépendance/wire externe réellement candidat :

source primaire
version stable courante
contrat wire actuel
features requises
dépendances transitives
compatibilité avec solana-pubkey/Core actuel
codec generations
licence si nouvelle dépendance

Ne pas auditer vingt crates spéculatives : seulement les candidates du scope retenu.

12.5 Matrice de frontières

Produire une matrice explicite, au minimum :

concept/type
owner cible
0.2.13 ?
0.2.14 ?
0.3.2+ ?
source d'autorité
raison

Cette matrice doit empêcher la fuite entre :

Core
Interface
Transport
Program API
Program Lib
RAW/CORE
Store

12.6 Surface API proposée

Avant implémentation, écrire conceptuellement la façade visée :

exports crate-root
principaux types publics
constructeurs
validation
serde/codec éventuel
erreurs
bornes

Les noms restent modifiables pendant pre.001; le but est de vérifier la cohérence, pas de figer prématurément tous les détails.

12.7 Threat / robustness model

Auditer :

oversized byte payload
oversized collection
integer overflow / index conversion
malformed wire
unknown enum/discriminant
nested structures pathologiques
Debug volumineux
allocation/copie excessive
serde hostile
panic/unwrap/expect

Pour chaque risque retenu, indiquer le test/canari prévu.

12.8 Dependency graph cible

Établir la cible réelle, par exemple :

ksp-interface-lib
    -> ksp-core-lib
    -> serde ?
    -> codec(s) réellement retenu(s) ?
    -> interface officielle compatible ?

et prouver explicitement les interdictions.

Si une nouvelle dépendance externe est proposée, prévoir les cargo tree de validation.

12.9 Stratégie de tests

Décider avant le développement :

unit tests privés
integration public API
external consumer compile canary
round-trip fixtures
malformed fixtures
oversized/adversarial
compile-fail si utile
cargo tree/firewall

Aucun smoke réseau n'est requis par défaut pour une crate wire pure.

12.10 Sizing

Estimer chaque tranche intermédiaire avec le budget KSP d'environ 15–20 minutes de travail effectif comme outil de découpage, jamais comme promesse.

Si une tranche est manifestement trop grosse, la scinder avant implémentation.

Si la release entière paraît impossible à clôturer raisonnablement dans la session, réduire le scope fonctionnel de 0.2.13 avant de coder.

12.11 Documents de sortie

Créer ou mettre à jour au minimum :

docs/plans/020-V0_2_13_INTERFACE_PLAN.md
docs/validation/016-V0_2_13_INTERFACE.md
deltas/0.2.13/pre.001.md

Le plan doit contenir la prévision souple recalibrée sous forme de headings ### pre.NNN, avec statuts et éventuels fixes imbriqués conformément aux conventions KSP utilisées dans les releases récentes.

Critères de sortie de pre.001

pre.001 n'est fermé que si :

sources internes obligatoires réellement relues
base stable confirmée
surface Core/Transport pertinente inventoriée
architecture 006 confrontée à la base réelle
archive kbot3 auditée si disponible ou absence explicitement notée
matrice REPRENDRE/REDESSINER/REPORTER/REJETER produite
frontière 0.2.13 / 0.2.14 / 0.3.2 explicite
premier lot wire exact décidé ou réduit
ownership des types décidé
dépendances candidates auditables et bornées
threat/robustness model écrit
strategy de tests définie
dependency graph cible défini
plan + validation créés
forecast recalibré
sizing compatible avec une release/session
aucune implémentation Program lourde commencée

Si l'une de ces sorties reste ambiguë, pre.001 continue ou reçoit un fix ; pre.002 ne commence pas par défaut.

13. Prévision souple initiale des prereleases

Cette trajectoire est un forecast de départ. pre.001 doit la fusionner, scinder, supprimer ou prolonger selon le scope réellement démontré.

pre.001 — Audit actuel + héritage kbot3 + frontières + sizing

Statut : prévu

Lectures obligatoires, baseline, audit Core/Transport, audit kbot3, audit externe ciblé, matrice d'ownership, threat model, dependency graph, plan/validation et sizing. Aucun développement fonctionnel lourd.

pre.002 — Scaffold ksp-interface-lib + façade + firewall

Statut : prévu

Créer la crate, l'ajouter au workspace, poser la façade publique minimale, README/USAGE initiaux et canaris de dépendances. Ne pas introduire encore une grande famille wire si le scaffold suffit pour fermer la tranche.

pre.003 — Primitives publiques retenues

Statut : prévu

Introduire uniquement les wrappers/identités/bornes réellement confirmés par pre.001, en réutilisant Core lorsque possible. Aucun modèle d'acquisition général par anticipation.

pre.004 — Premier lot wire officiel retenu

Statut : prévu

Matérialiser le premier lot fonctionnel réellement justifié : layouts/types/codec/constructeurs wire selon le plan final. Aucun decode sémantique.

pre.005 — Second lot wire uniquement si démontré

Statut : optionnel

Ajouter une seconde famille uniquement si pre.001 a démontré qu'elle appartient réellement à la foundation 0.2.13. Supprimer cette tranche si le minimum est déjà complet.

pre.006 — Sérialisation / bornes / adversarial

Statut : prévu

Durcir round-trips, malformed/unknown, tailles hostiles, integer conversions, Debug, ordre et options. Si aucun codec n'est retenu, convertir cette tranche en hardening structurel pertinent plutôt que d'inventer de la sérialisation.

pre.007 — Consumer externe + API/dependency hardening

Statut : prévu

Prouver la consommation via crate-root, stabilité de la façade, firewall interne/externe, docs publiques et graphes Cargo. Aucun nouveau domaine wire opportuniste.

pre.008 — Gate technique final

Statut : prévu

Gate workspace complet, canaris public API/dependencies, cargo tree pertinents et audit de complétude de la surface retenue. Aucun README/USAGE final ni préparation de publication dans cette tranche.

pre.009 — Réconciliation documentaire finale

Statut : prévu

Réconcilier plan, validation, README/USAGE et architectures/références durables réellement affectées. Ne pas finaliser CHANGELOG.md, ROADMAP.md ni le prompt suivant.

pre.010 — Préparation de publication minimale

Statut : prévu

Modifier fonctionnellement uniquement :

prompts/019-V0_2_14_START_PROMPT.md
CHANGELOG.md
ROADMAP.md

plus Cargo.toml et le delta mécanique requis. Aucun code, test, README, USAGE, plan, validation, règle ou architecture n'est rouvert.

rel.001 — Publication stable

Statut : prévu

Passer la version Cargo à 0.2.13, exécuter le gate de publication requis, créer le commit de livraison puis le tag stable v0.2.13 conformément au workflow KSP.

Les responsabilités de fermeture restent donc séparées :

gate technique final
réconciliation documentaire
préparation de publication minimale
rel.001

Un fix reste strictement local à la responsabilité de sa tranche.

14. Versionnement, deltas, commits, archives et tags

Version Cargo des prereleases :

0.2.13-pre.1
0.2.13-pre.2
...
0.2.13-pre.N.fix.M

Deltas :

deltas/0.2.13/pre.001.md
deltas/0.2.13/pre.002.md
...
deltas/0.2.13/pre.NNN-fix.MMM.md
deltas/0.2.13/rel.001.md

Commits de livraison :

v0.2.13-pre.001
v0.2.13-pre.002
v0.2.13-pre.NNN-fix.MMM
v0.2.13-rel.001

Aucun tag Git pour prerelease/fix/rel.

Seule la release stable reçoit :

v0.2.13

Archives :

ksp-general-<delivery-id>.zip
ksp-doc-<delivery-id>.zip lorsque le payload est strictement documentaire/prompts

Chaque archive contient uniquement les fichiers ajoutés/modifiés du delta plus son fichier delta. Les suppressions sont listées explicitement.

Une prerelease non-fix synchronise workspace.package.version même si elle est documentaire. Un fix purement documentaire ne force pas de bump Cargo ; un fix code/build/runtime/config suit l'identifiant SemVer technique prévu par VERSION_WORKFLOW.md.

Chaque delta est commité à partir de 0.1.x; un fix ne réécrit jamais silencieusement le delta d'origine.

15. Validation opérateur et procédure d'application

Le mode opératoire reste celui des releases KSP récentes :

  1. l'assistant travaille à partir de la base opérateur réellement validée ;
  2. il produit un delta ZIP minimal ;
  3. l'opérateur applique l'archive dans son checkout ;
  4. l'opérateur exécute les gates ;
  5. les logs réels font autorité pour fermer la tranche ou produire un fix ;
  6. un fix reste dans le scope exact de la tranche défectueuse.

Gate Rust standard après modification :

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

Puis tests ciblés de la crate :

cargo test -p ksp-interface-lib

Aux gates globaux :

cargo test --workspace

Lorsque le graphe change ou qu'une dépendance wire est ajoutée :

cargo tree -p ksp-interface-lib --edges normal
cargo tree --duplicates
cargo tree -i <dependency-fondamentale> si pertinent

Ne jamais déclarer PASS :

cargo fmt
rust audit
cargo check
clippy
tests
cargo tree

si la commande correspondante n'a pas réellement été exécutée.

Il n'y a aucun gate Tauri par défaut pour 0.2.13, car la release ne doit modifier aucune application.

Il n'y a aucun smoke réseau par défaut pour une crate wire pure. Si pre.001 découvre un besoin réellement justifié, le gate doit être défini explicitement avant implémentation et ne doit pas transformer Interface en consumer réseau.

16. Tests et canaris attendus

Le plan final doit couvrir, selon la surface retenue :

16.1 Public API

exports crate-root complets
aucun pub mod opportuniste
rustdoc public
consumer externe compile
aucun import de module privé nécessaire

16.2 Dependency firewall

Interface -> Core seulement selon besoins réels
Interface -X-> Program API / Program Lib
Interface -X-> Config
Interface -X-> Transport
Interface -X-> Store
Interface -X-> Wallet
Interface -X-> Tauri
Interface -X-> reqwest / tonic / provider SDK
codec/direct protocol deps uniquement si possédés par le wire retenu

16.3 Wire fidelity

Selon le contrat :

round-trip exact
fixtures officielles/externes lorsque disponibles
ordre préservé
unknown/malformed géré
absent/empty/value distingués
integer conversions vérifiées
no f64 canonical truth

16.4 Adversarial

oversized bytes
oversized collections
invalid discriminant
truncated input
trailing data si interdit par le wire
path/index overflow
nested/pathological input
Debug borné

16.5 Architecture

Canaris empêchant l'introduction prématurée de :

Decoder trait
Program registry comportemental
Materializer trait
Execution preparer
Store DTO
Transport dependency

16.6 External consumer

Le canari doit simuler une crate externe qui ne dépend pas de l'implémentation officielle Program et n'accède qu'à l'API publique Interface.

17. Critères de clôture de 0.2.13

La release peut devenir stable seulement si :

ksp-interface-lib existe dans le workspace
scope public final correspond au plan recalibré de pre.001
aucun trait Program n'a fuité dans Interface
aucun modèle RAW/CORE prématuré n'a été imposé
Program IDs fondamentaux restent dans Core
ownership de chaque type public est documenté
surface publique est consommable depuis crate externe
bornes/adversarial canaris verts
codec/serde éventuels sont justifiés et testés
dependency firewall vert
cargo tree pertinent inspecté si graphe modifié
cargo fmt + audit Rust + check + clippy verts
cargo test -p ksp-interface-lib vert
cargo test --workspace vert
aucun smoke réseau inventé sans besoin
README/USAGE finaux réconciliés dans la tranche documentaire dédiée
plan/validation/architecture durable réconciliés dans cette même tranche documentaire
prompt 0.2.14 finalisé seulement dans la dernière prerelease
CHANGELOG/ROADMAP finalisés seulement dans la dernière prerelease
aucun rattrapage code/doc dans rel.001

Le numéro de prerelease prévu n'est jamais un critère de clôture.

18. Release/session suivante envisagée

La release suivante est :

0.2.14 — Program API foundation

Elle doit ouvrir ksp-program-api comme contrat ouvert et extensible pour les comportements Program réellement démontrés.

Inputs historiques utiles à réauditer alors, notamment depuis kbot3 :

identity / descriptor
surfaces / capabilities
recognition
instruction/account decoder families
outcomes / diagnostics / proof
prepared execution boundary
external implementation canaries

Mais 0.2.13 ne doit pas figer leur forme trait avant cet audit.

Après 0.2.14, les implémentations officielles ksp-program-lib arrivent avec les vertical slices qui en ont réellement besoin, et non comme une grande couche monolithique préalable.

La trajectoire RAW/CORE reste séparée :

0.3.1  Store RAW
0.3.2  extension Interface pour wires génériques acquisition/CORE

19. Instruction d'ouverture

Au début de la session 0.2.13 :

  1. confirmer la base stable v0.2.12 ou l'archive stable opérateur autoritaire ;
  2. vérifier workspace.package.version = 0.2.12 et deltas/0.2.12/rel.001.md ;
  3. lire les règles de la section 3.1 dans l'ordre ;
  4. lire l'architecture de la section 3.2, en particulier 006-WIRE_AND_PROGRAM.md ;
  5. relire la séquence fonctionnelle et la clôture 0.2.12 ;
  6. exécuter la baseline complète avant développement lourd ;
  7. inventorier la surface publique réelle Core et les DTOs Transport pertinents ;
  8. réinspecter l'archive kbot3 si elle est disponible ;
  9. produire la matrice REPRENDRE / REDESSINER / REPORTER / REJETER ;
  10. auditer uniquement les sources externes réellement candidates et leurs versions actuelles ;
  11. décider le premier minimum wire de ksp-interface-lib ;
  12. produire la matrice d'ownership Core / Interface / Transport / Program API / 0.3.2+ ;
  13. décider bytes/bornes/serde/codec/versionnement/error model ;
  14. produire la façade publique conceptuelle et le dependency graph cible ;
  15. produire le threat/robustness model et la stratégie de tests ;
  16. dimensionner la release et chaque tranche ;
  17. créer le plan 020, la validation 016 et deltas/0.2.13/pre.001.md ;
  18. ne pas commencer les traits Program, les decoders, les materializers, l'execution ou un modèle RAW/CORE complet avant la fermeture de ce gate.

La première réponse de travail de la nouvelle session doit donc être un audit/sizing 0.2.13-pre.001 complet, avec matrice d'héritage kbot3, frontières, surface wire proposée, dépendances, risques, tests et forecast recalibré — pas un scaffold déjà figé ni un portage de ks-lib.

Reference in New Issue View Git Blame Copy Permalink