v0.0.3-pre.002

docs/rules/PROMPT_STRUCTURE.md

@@ -1,203 +1,70 @@
 <!-- file: docs/rules/PROMPT_STRUCTURE.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Structure des prompts KSP
 
 ## Portée
 
-Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des sessions/prereleases qu'ils préparent.
+Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des releases/sessions qu'ils préparent.
 
-Les prompts eux-mêmes sont conservés sous `prompts/`.
+## Série, release concrète et session
 
-## Objectif
+Une notation de série telle que `0.1.x` regroupe des fonctionnalités apparentées. Elle n'est pas une unité de session et n'a pas à être réalisable en une seule session.
 
-Un prompt doit permettre de reprendre le travail sans reconstituer manuellement :
+Exemple : `0.1.x` peut regrouper plusieurs releases concrètes comme `0.1.1`, `0.1.2`, `0.1.3`, chacune avec son propre cycle de prereleases et, en principe, sa propre session de travail principale.
 
-- la mission de la phase ;
-- la base Git/version ;
-- l'état validé à préserver ;
-- les règles applicables ;
-- l'architecture déjà décidée ;
-- les questions encore ouvertes ;
-- les sources externes normatives lorsqu'elles existent ;
-- le plan souple ;
-- le mode de livraison ;
-- les validations et critères de sortie.
+Le contrôle de charge s'applique donc d'abord à **la release concrète préparée** et à ses prereleases, pas à toute la série fonctionnelle.
 
-Le prompt ne remplace jamais les sources de vérité du dépôt.
-
-## Cycle de vie
-
-Un prompt de prochaine grande phase est créé dès que sa direction devient suffisamment claire.
-
-Il passe par trois états conceptuels :
-
-1. **Brouillon** — créé tôt et volontairement incomplet ;
-2. **Quasi-final** — mis à jour lorsque les frontières, crates, dépendances et objectifs sont suffisamment stabilisés ;
-3. **Final** — vérifié pendant la phase documentaire de clôture et prêt à être utilisé comme point de départ de la session/version suivante.
-
-Le prompt de la phase suivante doit être maintenu pendant la phase courante lorsque de nouvelles décisions changent matériellement son futur démarrage.
-
-## Première et dernière prerelease d'une version
+## Cycle d'une release concrète
 
 Sauf raison explicitement documentée :
 
-- la première prerelease (`pre.001`) est consacrée au brainstorming, à l'audit lorsque nécessaire, à la planification, aux décisions de périmètre et au découpage souple des prereleases suivantes ;
-- la dernière prerelease est consacrée à la validation finale, à la documentation, au nettoyage/archivage nécessaire, à la synchronisation des documents de release et à la finalisation du prompt de la session/version suivante.
-
-Le développement fonctionnel significatif ne doit pas précéder le cadrage suffisant de `pre.001`.
+- `pre.001` = brainstorming/audit si nécessaire + planification + découpage de la release ;
+- les prereleases intermédiaires = tranches bornées de développement/validation ;
+- la dernière prerelease = validation finale + documentation + nettoyage/archivage + préparation du prompt/release suivante.
 
 ## Dimensionnement des prereleases
 
-Pendant l'élaboration du plan de `pre.001`, les prereleases de travail situées après `pre.001` et avant la prerelease finale de clôture doivent être conçues comme des tranches bornées.
+Lors de `pre.001`, une prerelease intermédiaire estimée à plus d'environ **15 à 20 minutes de travail effectif de session** doit être scindée.
 
-Lors de la planification, une tranche dont la charge estimée paraît dépasser approximativement **15 à 20 minutes de travail effectif de session** doit être scindée en plusieurs prereleases ou sous-objectifs livrables séparément.
+Cette durée est un budget de planification et non une promesse d'exécution.
 
-Cette durée est un budget de planification, pas une promesse de temps d'exécution. Elle sert à empêcher les tranches trop larges, difficiles à valider ou à corriger.
+Si la complexité réelle augmente, la tranche est redécoupée plutôt que surchargée.
 
-Si la complexité réelle découverte en cours de travail dépasse l'estimation, la tranche doit être redécoupée plutôt que surchargée.
+## Dimensionnement d'une release/session
 
-## Dimensionnement d'une session ou d'une version
+Avant de finaliser le prompt d'une release concrète, vérifier que son plan complet est compatible avec une session de qualité.
 
-Avant de finaliser le prompt de la session suivante, il faut évaluer la charge totale produite par le plan prévu.
+Si une release concrète paraît trop lourde, la scinder en plusieurs releases de la même série lorsque les fonctions restent du même groupe, ou changer de série si une frontière fonctionnelle différente le justifie.
 
-Si un prompt risque de générer trop de prereleases, trop de fichiers, trop de décisions ou un contexte trop lourd pour une seule session de qualité, le périmètre doit être découpé :
+Exemple : si `0.1.1` devient trop large, créer `0.1.2` plutôt que forcer tout `0.1.x` dans une seule session.
 
-- en plusieurs sessions conservant éventuellement la même série/version lorsque la continuité fonctionnelle le justifie ;
-- et/ou en plusieurs versions lorsque la séparation correspond à une frontière fonctionnelle plus propre.
-
-Exemple : si une version prévue pour introduire decoder + executor devient manifestement trop lourde après planification, la continuité du roadmap est conservée mais le travail peut être réparti sur plusieurs sessions ou versions.
-
-La qualité du contexte, la testabilité et la cohérence architecturale priment sur le maintien artificiel d'un découpage de versions imaginé plus tôt.
+Une série complète peut naturellement s'étendre sur de nombreuses sessions.
 
 ## Structure recommandée d'un prompt
 
-### 1. Identité de la phase
-
-Indiquer :
-
-- version ou série visée ;
-- titre court ;
-- nature de la session : brainstorming, planification, développement, audit, validation, clôture, etc.
-
-### 2. Mission
-
-Décrire l'état concret à atteindre pendant la phase.
-
-La mission ne doit pas être une simple liste de fichiers à modifier.
-
-### 3. Base requise
-
-Indiquer :
-
-- version/tag/commit de départ ;
-- état attendu du workspace ;
-- fichiers/documents fondamentaux déjà présents.
-
-### 4. État validé à préserver
-
-Lister les éléments déjà validés qui ne doivent pas régresser pendant la nouvelle phase, par exemple :
-
-- APIs déjà stabilisées ;
-- comportements fonctionnels validés ;
-- tests/scénarios connus comme passants ;
-- décisions gelées ou fortement contraintes ;
-- problèmes explicitement reportés qui ne doivent pas être rouverts sans raison.
-
-Cette section est distincte de la simple base Git/version.
-
-### 5. Sources de vérité internes à relire
-
-Lister explicitement les documents nécessaires, en priorité :
-
-- `RULES.md` et règles spécialisées pertinentes ;
-- `ROADMAP.md` ;
-- plan de version actif ;
-- architecture concernée ;
-- `docs/IDEAS.md` lorsqu'une question ouverte est pertinente ;
-- dernier delta/release utile.
-
-Le prompt doit renvoyer aux sources de vérité au lieu de les recopier intégralement.
-
-### 6. Sources externes normatives
-
-Lorsqu'une phase concerne un protocole, programme, standard ou API externe, lister les sources qui font autorité :
-
-- dépôt upstream officiel ;
-- documentation officielle ;
-- IDL/schema officiel ;
-- Program ID ;
-- format wire ;
-- spécification normative ;
-- autre source externe explicitement retenue.
-
-Une copie historique locale ne doit pas être traitée comme source de vérité actuelle lorsque la phase exige une vérification upstream.
-
-### 7. Décisions acquises
-
-Résumer uniquement les décisions indispensables pour éviter une mauvaise direction au démarrage.
-
-### 8. Objectifs et livrables
-
-Lister les objectifs principaux et les artefacts attendus.
-
-### 9. Hors périmètre
-
-Indiquer ce qui ne doit explicitement pas être ouvert pendant la phase.
-
-### 10. Méthode de travail
-
-Rappeler la séquence KSP applicable :
-
-1. brainstorming ;
-2. planification ;
-3. développement lorsque la phase est fonctionnelle ;
-4. tests/validations ;
-5. documentation finale ;
-6. mise à jour/préparation du prompt suivant.
-
-Une phase fondatrice/documentaire adapte la partie développement à son objet.
-
-### 11. Versionnement et deltas
-
-Rappeler :
-
-- version Cargo attendue ;
-- format du delta ;
-- règle des fixes techniques/documentaires ;
-- politique de commits de la phase ;
-- règle de découpage des livraisons trop volumineuses.
-
-### 12. Contraintes techniques spécifiques
-
-Lister uniquement les contraintes importantes pour cette phase : dépendances, environnements, sécurité, API publique, stockage, transport, etc.
-
-### 13. Plan initial souple
-
-Pour un `pre.001`, fournir la prévision souple des prereleases ou étapes principales.
-
-Chaque tranche intermédiaire doit respecter le budget de complexité défini plus haut et être redécoupée si nécessaire.
-
-### 14. Validations attendues
-
-Indiquer les commandes/tests/audits pertinents et interdire de déclarer une validation non exécutée.
-
-### 15. Critères de sortie
-
-Décrire les conditions nécessaires pour considérer la phase terminée.
-
-### 16. Préparation de la suite
-
-Indiquer quel document/prompt doit être produit ou mis à jour avant la clôture.
-
-Avant finalisation de ce prompt suivant, appliquer obligatoirement le contrôle de dimensionnement de session/version.
+1. Identité de la série et de la release concrète visée ;
+2. Mission ;
+3. Base requise ;
+4. État validé à préserver ;
+5. Sources de vérité internes ;
+6. Sources externes normatives ;
+7. Décisions acquises ;
+8. Objectifs et livrables ;
+9. Hors périmètre ;
+10. Méthode de travail ;
+11. Versionnement/deltas/commits ;
+12. Contraintes techniques spécifiques ;
+13. Plan initial souple et prereleases bornées ;
+14. Validations attendues ;
+15. Critères de sortie ;
+16. Préparation de la release/session suivante.
 
 ## Règles de rédaction
 
-- Le prompt est précis mais évite de dupliquer plusieurs pages déjà présentes dans les documents canoniques.
-- Une règle normative appartient d'abord à `docs/rules/`, pas seulement au prompt.
-- Une décision architecturale durable appartient à `docs/architecture/`, pas seulement au prompt.
+- Le prompt référence les sources canoniques au lieu de recopier inutilement leur contenu.
+- Une règle normative appartient à `docs/rules/`.
+- Une décision durable appartient à `docs/architecture/`.
 - Une idée non décidée appartient à `docs/IDEAS.md`.
-- Le prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
-- Les chemins et versions mentionnés doivent être cohérents avec le dépôt au moment de la finalisation.
-- Un prompt final ne doit pas préparer une session manifestement surdimensionnée.
+- Un prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
+- Une release concrète manifestement surdimensionnée doit être redécoupée avant ouverture de sa session principale.

docs/rules/RULES_KSP.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_KSP.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->
 
 # Règles spécifiques à KSP
 
@@ -13,6 +13,7 @@
 - **KSP-NAME-006** — Un job ponctuel/historique/terminable se nomme `ksp-job-<role>`.
 - **KSP-NAME-007** — Une démonstration se termine par `-demo`.
 - **KSP-NAME-008** — Les crates Rust sont placées directement sous `crates/`.
+- **KSP-NAME-009** — Une application desktop de scénario spécialisée suit la forme `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.
 
 ## Architecture et APIs
 
@@ -22,8 +23,9 @@
 - **KSP-API-004** — Un contrat public extensible doit pouvoir être implémenté depuis une crate séparée du workspace principal lorsque cela est techniquement pertinent.
 - **KSP-API-005** — Les signatures des contrats publics utilisent en priorité des types publics KSP et les primitives externes explicitement admises ; elles ne doivent pas imposer des détails internes instables.
 - **KSP-API-006** — `ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence derrière `ksp-store-api`.
+- **KSP-API-007** — Une crate `*-api` n'est créée que lorsqu'un vrai besoin d'extension, backend ou lifecycle le justifie ; la symétrie de nommage n'est jamais une justification suffisante.
 
-## Programmes
+## Programmes et exécution
 
 - **KSP-PROGRAM-001** — Les contrats decoder/executor appartiennent à `ksp-program-api`; les implémentations officielles intégrées appartiennent à `ksp-program-lib`.
 - **KSP-PROGRAM-002** — Le decoder vise toute surface techniquement décodable dont la définition est connue, y compris les formats anciens, obsolètes ou expérimentaux encore distinguables.
@@ -31,24 +33,43 @@
 - **KSP-PROGRAM-004** — Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable.
 - **KSP-PROGRAM-005** — Une opération devenue obsolète mais toujours identifiable/exécutable peut rester implémentée dans l'executor et être marquée `deprecated`.
 - **KSP-PROGRAM-006** — `ksp-program-lib` ne contient pas la politique de sécurité de production.
+- **KSP-EXEC-001** — La direction retenue est une API de policy d'exécution séparée, candidate `ksp-execution-policy-api`, afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`.
+- **KSP-EXEC-002** — Une application UI sélectionne/injecte une implémentation de policy réutilisable ; elle ne doit pas enfouir une politique d'exécution complexe dans sa couche d'interface.
+- **KSP-EXEC-003** — `ksp-execution-lib` est un candidat fort d'orchestration spécialisée entre programme, policy, wallet et transport. Son graphe exact est reporté à l'étude des dépendances.
+
+## Transports
+
+- **KSP-TRANSPORT-001** — KSP ne crée pas de `ksp-onchain-transport-api` séparée dans l'architecture actuelle.
+- **KSP-TRANSPORT-002** — `ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api`.
+- **KSP-TRANSPORT-003** — Les providers on-chain normalisent leurs sorties dans des modèles de transport homogènes par catégorie de données avant exposition aux consommateurs.
+- **KSP-TRANSPORT-004** — Les modèles de transport restent sans décodage métier/protocolaire et doivent être explicitement/facilement convertibles vers les modèles raw persistants de `ksp-store-api` par la couche d'acquisition.
+- **KSP-TRANSPORT-005** — KSP ne crée pas de `ksp-offchain-transport-api` globale ni de trait universel artificiel pour des domaines off-chain hétérogènes.
+
+## Wallet
+
+- **KSP-WALLET-001** — KSP ne crée pas de `ksp-wallet-api` dans l'architecture actuelle ; `ksp-wallet-lib` possède le format wallet KSP et ses capacités de lecture/protection/import/export/pubkey/secret/signature.
 
 ## Workers
 
 - **KSP-WORKER-001** — Un worker représente un service continu/live ; il est distinct d'un job.
 - **KSP-WORKER-002** — Les contrats communs des workers appartiennent à `ksp-worker-api` et ne contiennent aucun contrat propre aux jobs.
-- **KSP-WORKER-003** — `ksp-worker-control-lib` est le candidat d'implémentation commune de gouvernance/contrôle des workers lorsque plusieurs consommateurs le justifient.
-- **KSP-WORKER-004** — W1 est un worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
-- **KSP-WORKER-005** — W1 persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
-- **KSP-WORKER-006** — W1 doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
+- **KSP-WORKER-003** — `ksp-worker-api` est principalement une lifecycle API de services continus : identité, état, health, démarrage/arrêt et événements communs ; les capacités optionnelles ne deviennent universelles que si plusieurs workers les partagent réellement.
+- **KSP-WORKER-004** — `ksp-worker-control-lib` est une implémentation commune de gouvernance/contrôle réutilisable par managers desktop, future application globale et orchestrateur ; les apps ne réimplémentent pas cette gouvernance.
+- **KSP-WORKER-005** — `ksp-worker-raw-retriever` est le worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
+- **KSP-WORKER-006** — `ksp-worker-raw-retriever` persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
+- **KSP-WORKER-007** — `ksp-worker-raw-retriever` doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
+- **KSP-WORKER-008** — Les workers de processing actuellement retenus sont `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector`; le dernier nom reste provisoire.
 
 ## Jobs
 
 - **KSP-JOB-001** — Un job représente un travail déclenché à la demande, suivable et terminable ; il est distinct d'un worker continu.
 - **KSP-JOB-002** — Les contrats communs des jobs appartiennent à `ksp-job-api` et ne contiennent aucun contrat propre aux workers.
-- **KSP-JOB-003** — Les implémentations concrètes utilisent le préfixe `ksp-job-`.
-- **KSP-JOB-004** — `ksp-job-backfill` est le candidat retenu pour le backfill historique ; il ne doit pas être implémenté comme un mode W1.
-- **KSP-JOB-005** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
-- **KSP-JOB-006** — Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers.
+- **KSP-JOB-003** — `ksp-job-api` est principalement une lifecycle API de travaux terminables : identité, état, progression, annulation, résultat et capacités de reprise lorsqu'elles sont pertinentes.
+- **KSP-JOB-004** — Les implémentations concrètes utilisent le préfixe `ksp-job-`.
+- **KSP-JOB-005** — `ksp-job-backfill` est retenu pour le backfill historique ; il ne doit pas être implémenté comme un mode du worker raw.
+- **KSP-JOB-006** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
+- **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie.
+- **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers.
 
 ## Notifications de données
 
@@ -60,14 +81,16 @@
 ## Pipelines et scénarios
 
 - **KSP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique. Les pipelines sont introduits séparément à la demande selon leur responsabilité réelle.
-- **KSP-DEMO-001** — Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
-- **KSP-DEMO-002** — Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib` par responsabilité fonctionnelle cohérente.
-- **KSP-DEMO-003** — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés.
-- **KSP-DEMO-004** — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé.
-- **KSP-DEMO-005** — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow.
+- **KSP-SCENARIO-001** — Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
+- **KSP-SCENARIO-002** — Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib` par responsabilité fonctionnelle cohérente.
+- **KSP-SCENARIO-003** — `ksp-scenario-api` n'est pas retenu actuellement ; KSP privilégie d'abord une norme documentaire/structurelle commune qui ne limite pas les contrats spécifiques des scénarios.
+- **KSP-SCENARIO-004** — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés.
+- **KSP-SCENARIO-005** — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé.
+- **KSP-SCENARIO-006** — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow.
 
 ## Applications
 
 - **KSP-APP-001** — Une application KSP est une interface et une couche de composition. Elle ne réimplémente pas une opération appartenant conceptuellement à un composant KSP réutilisable inférieur.
 - **KSP-APP-002** — Les applications/demos ne dépendent pas directement de crates Solana/protocoles externes.
 - **KSP-APP-003** — Les applications/demos peuvent réaliser les opérations strictement liées à l'interface, mais pas la logique métier/protocolaire réutilisable.
+- **KSP-APP-004** — Une demo scenario desktop consomme la crate `ksp-scenario-<domain>-lib` correspondante ; elle suit la convention `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.