# Prompt de démarrage `0.3.9` — `ksp-worker-api` générique + audit RAW Transaction préparatoire ## 1. Identité de la release et base exacte requise Ouvrir cette session uniquement après publication et tag validés de : ```text v0.3.8 ``` La base autoritaire est le dépôt stable `v0.3.8` ou, si l'opérateur fournit une archive stable explicitement désignée comme base, cette archive exacte. Vérifier avant tout travail : ```text workspace.package.version = 0.3.8 deltas/0.3.8/rel.001.md présent ksp-app-store-desk présent et stable ksp-job-api / ksp-job-backfill-lib présents et stables ksp-onchain-transport-lib / ksp-config-lib / ksp-store-lib présents et stables ``` Release ouverte : ```text 0.3.9 ``` Première livraison attendue : ```text 0.3.9-pre.001 ``` `pre.001` est un gate d'audit/brainstorming/sizing/planification. Il ne doit pas commencer l'implémentation lourde de `ksp-worker-api` et ne doit surtout pas commencer le worker RAW Transaction. --- ## 2. Mission et résultat attendu ### 2.1 Mission principale Introduire : ```text crates/ksp-worker-api ``` comme API KSP **générique** pour des services continus pouvant rester actifs indéfiniment. Le contrat doit couvrir uniquement les primitives réellement transversales nécessaires à des workers KSP, par exemple selon l'audit `pre.001` : ```text identity lifecycle/state health progress/activity sûre snapshot latest-value notification/resynchronisation cancellation/stop borné erreur terminale/fault sûre handle/supervision si réellement générique ``` Les noms, états exacts et transitions sont des questions de `pre.001`; ils ne sont pas imposés par cette liste. ### 2.2 Distinction Worker / Job obligatoire `ksp-worker-api` ne doit pas devenir un alias de `ksp-job-api`. Sémantique cible : ```text Job = traitement borné/terminable avec outcome et fin normale attendue Worker = service continu dont l'état Running peut être durable/indéfini ``` Le pattern latest-value stabilisé dans `ksp-job-api` peut être réutilisé **conceptuellement** lorsque ses propriétés sont génériques, mais : ```text aucune dépendance ksp-worker-api -> ksp-job-api n'est supposée aucune sémantique de checkpoint/backfill n'entre dans Worker API aucun JobId/JobKindCode n'est réutilisé par simple commodité aucun worker concret ne dicte les états de l'API générique ``` ### 2.3 Deuxième résultat obligatoire de `0.3.9` Une fois `ksp-worker-api` **fonctionnellement fermée et hardenée**, la fin de `0.3.9` doit produire un audit fonctionnel exhaustif des sources/méthodes d'acquisition `RawTransaction`. Cet audit est un **handoff architectural pour `0.3.10`**. Il ne constitue pas l'implémentation du worker concret et ne doit pas déformer `ksp-worker-api` pour un besoin Solana-specific. Résultat attendu à la fermeture : ```text ksp-worker-api stable et générique + matrice exhaustive RawTransaction documentée + décisions/gaps préparatoires explicites pour 0.3.10 ``` --- ## 3. Sources de vérité internes obligatoires — ordre de lecture ### 3.1 Gouvernance générale Lire d'abord : ```text RULES.md ROADMAP.md CHANGELOG.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 prompt complète ces règles ; il ne les remplace pas. Rappels directement bloquants : ```text Rust 2024 unsafe / unwrap / expect / panic interdits selon les règles KSP ? interdit en production retours explicites ; clippy::implicit_return deny #![warn(missing_docs)] #![deny(unreachable_pub)] #![forbid(unsafe_code)] pas de pub mod pub/pub(crate) partagés consommés via crate::Item item seulement module-local => private unit tests sous unit_tests/ integration tests sous tests/ ``` Après toute modification Rust : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Pour tout Markdown touché : ```bash python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.9 ``` Une commande non exécutée n'est jamais déclarée PASS. ### 3.2 Architecture acquisition / workers / jobs Lire intégralement : ```text docs/architecture/000-README.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/009-ACQUISITION_WORKERS_AND_JOBS.md docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md ``` Ces documents possèdent les décisions durables acquises avant l'ouverture de `0.3.9`, notamment : ```text ksp-worker-api reste générique ksp-worker-raw-transaction-ingest-lib est le premier worker concret retenu le worker RAW est multi-source dès V1 l'audit des sources RAW a lieu en fin de 0.3.9 après fermeture Worker API 0.3.11 appartient à la Desk d'ingestion 0.3.12 étend le backfill vers les autres sources/stratégies ``` Une divergence entre ces documents et la base réelle déclenche un audit explicite ; ne pas improviser une nouvelle trajectoire. ### 3.3 `ksp-job-api` — référence de propriétés, pas parent de Worker Lire : ```text crates/ksp-job-api/Cargo.toml crates/ksp-job-api/README.md crates/ksp-job-api/USAGE.md crates/ksp-job-api/src/lib.rs crates/ksp-job-api/src/ crates/ksp-job-api/tests/ docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md docs/validation/023-V0_3_6_JOB_API_BACKFILL.md ``` Inventorier précisément les propriétés déjà prouvées : ```text identity bornée lifecycle explicite cancellation partagée/idempotente latest-value notification/source sequence/resynchronisation terminal immuable Debug/redaction Send/Sync API Core-only ``` Puis décider en `pre.001` lesquelles sont réellement génériques à Worker et lesquelles restent Job-specific. Interdiction : copier mécaniquement les types/états Job ou ajouter `ksp-job-api` comme dépendance pour éviter quelques lignes de code. ### 3.4 Premier backfill concret — référence de contraste Lire : ```text crates/ksp-job-backfill-lib/README.md crates/ksp-job-backfill-lib/USAGE.md crates/ksp-job-backfill-lib/src/ crates/ksp-job-backfill-lib/tests/ crates/ksp-app-backfill-desk/README.md crates/ksp-app-backfill-desk/USAGE.md docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md docs/validation/024-V0_3_7_BACKFILL_DESK.md ``` Objectif de cette lecture : ```text comprendre la séparation API générique / consumer concret identifier ce qui est Job/backfill-specific et ne doit jamais remonter dans Worker API constater que le backfill 0.3.6/0.3.7 est une première stratégie HTTP ne pas en déduire que tout backfill ou tout ingest doit être HTTP ``` Le scope historique actuel : ```text getSignaturesForAddress -> getTransaction observé -> RawTransaction + RawTransactionObservation -> ksp-store-lib ``` reste valide mais n'est pas la définition générale de l'acquisition RAW Transaction. ### 3.5 Store RAW — convergence multi-source à préserver Lire : ```text crates/ksp-store-api/README.md crates/ksp-store-api/src/lib.rs crates/ksp-store-api/src/model/raw_transaction.rs crates/ksp-store-api/src/model/raw_primitives.rs crates/ksp-store-api/src/model/raw_retention.rs crates/ksp-store-api/src/capability/raw_transaction.rs crates/ksp-store-lib/README.md crates/ksp-store-lib/USAGE.md crates/ksp-store-lib/src/lib.rs crates/ksp-store-lib/src/store.rs crates/ksp-store-postgres-lib/README.md crates/ksp-store-postgres-lib/tests/ ``` Invariants à préserver dans l'audit futur : ```text identité canonique RawTransaction = réseau + signature contenu canonique indépendant du provider/source acquisition/provenance séparée dans RawTransactionObservation même identité + même contenu => idempotence même identité + contenu incompatible => conflit explicite jamais d'écrasement silencieux Store consommé par les workers uniquement via ksp-store-lib ``` ### 3.6 Transport on-chain réel Lire avant l'audit RAW final : ```text crates/ksp-onchain-transport-lib/README.md crates/ksp-onchain-transport-lib/USAGE.md crates/ksp-onchain-transport-lib/src/lib.rs crates/ksp-onchain-transport-lib/src/rpc_method.rs crates/ksp-onchain-transport-lib/src/rpc_transactions.rs crates/ksp-onchain-transport-lib/src/ws_*.rs crates/ksp-onchain-transport-lib/src/grpc_*.rs crates/ksp-onchain-transport-lib/tests/release_completeness.rs crates/ksp-onchain-transport-lib/tests/public_api.rs ``` Ne pas se contenter des noms de modules : inventorier les capabilities publiques réellement utilisables, leurs garanties, leurs limites et les metadata de provenance disponibles. ### 3.7 Config / secrets / réseaux Lire avant le handoff `0.3.10` : ```text crates/ksp-config-lib/README.md crates/ksp-config-lib/USAGE.md crates/ksp-config-lib/src/environment.rs crates/ksp-config-lib/src/transport.rs crates/ksp-config-lib/tests/ config/std.transport.json config/schemas/std.transport.schema.json .env.example ``` Acquis : ```text Config est l'unique owner de env/secrets KSP_SECRET_HELIUS_API_KEY existe déjà dans le namespace Config KSP les URLs/credentials ne doivent jamais être dupliqués dans Worker API 0.3.9 n'ajoute aucun endpoint/profil Helius pour le worker futur ``` L'audit peut identifier les adaptations nécessaires pour `0.3.10`; il ne les implémente pas dans la phase générique `0.3.9`. --- ## 4. Référence historique kbot3 — fonctionnelle uniquement Pour la construction de `ksp-worker-api`, kbot3 n'est pas nécessaire comme source d'API. Pour **l'audit RAW Transaction de fin de `0.3.9`**, l'archive kbot3 fournie par l'opérateur doit être réauditée comme référence fonctionnelle historique. Règle absolue : ```text kbot3 = référence fonctionnelle kbot3 != source de code kbot3 != source de DTO kbot3 != source de Config/URL kbot3 != source de dépendances/versions kbot3 != contrat KSP ``` Inventorier les fonctions historiques pertinentes : ```text sources d'acquisition utilisées rôles live/history/backfill HTTP discovery/hydration WS/provider streaming sélection provider/source reconnect/recovery multi-source ou fallback éventuel provenance conservée limites/quotas connus historiquement ``` Une capability historique n'est jamais déclarée encore disponible sans réaudit de la source primaire actuelle. --- ## 5. Sources externes normatives à réauditer lorsque la fraîcheur importe L'audit RAW Transaction est freshness-sensitive. Utiliser les sources primaires courantes au moment de la tranche, notamment : ```text documentation Solana officielle des clusters Solana JSON-RPC HTTP officiel Solana WebSocket officiel Helius documentation/pricing/capability matrix officielle Yellowstone gRPC / proto upstream officiel provider docs officielles pour replay/from_slot/quota lorsque pertinentes ``` Ne pas figer dans le code une observation historique du prompt. À vérifier explicitement : ```text terminologie actuelle Mainnet et compatibilité mainnet-beta méthodes WS réellement stables/instables et provider support Helius HTTP standard Mainnet/Devnet Helius WS standard Mainnet/Devnet Helius transactionSubscribe et autres extensions : disponibilité/tier courant Yellowstone transaction / transaction_status / block / block_meta mécanismes replay/from_slot réellement supportés par chaque provider quotas, filtre limits, subscription limits, reconnect semantics ``` Les offres provider peuvent évoluer entre le présent prompt et l'exécution de `0.3.9`; toujours réauditer avant décision. --- ## 6. État validé `v0.3.8` à préserver ### 6.1 Frontières fondamentales ```text ksp-core-lib -> types/erreur/program registry fondamentaux ksp-logging-lib -> logging/tracing policy/runtime ksp-config-lib -> Config/env/secrets/composites ksp-onchain-transport-lib -> HTTP/WS/Yellowstone transport ksp-store-api -> contrats persistants backend-neutral ksp-store-lib -> façade Store consumer ksp-store-postgres-lib -> backend physique privé ksp-job-api -> API traitements bornés/terminables ksp-job-backfill-lib -> premier job historique concret ksp-worker-api -> nouvelle API continue générique, à créer en 0.3.9 ``` ### 6.2 Store Desk n'est pas rouvert `0.3.8` a stabilisé : ```text inspection random-access backend-neutral RawTransaction / RawAccountState / observations DataTables server-side pagination machine cursor/keyset conservée Store Desk read-only ``` `0.3.9` ne transforme pas Store Desk en écran Worker et ne modifie pas Store API pour préparer artificiellement le worker futur. ### 6.3 Interface events `ksp-interface-lib` conserve les événements passifs partagés existants (`SlotLifecycleEvent`, `TransactionExecutionEvent`) sans devenir l'API Worker ou une seconde couche RAW. --- ## 7. Décisions acquises et questions réellement ouvertes ### 7.1 Décisions acquises — non négociables sans contradiction prouvée de la base ```text ksp-worker-api et ksp-worker-raw-transaction-ingest-lib restent deux crates distinctes 0.3.9 livre ksp-worker-api 0.3.10 livre le premier worker RawTransaction concret 0.3.11 livre la Desk d'ingestion 0.3.12 étend Backfill aux autres sources/méthodes Worker API reste générique et non Solana Worker API est fonctionnellement fermée avant l'audit détaillé RawTransaction l'audit RawTransaction est placé en fin de 0.3.9 pour ne pas saturer 0.3.10 le futur worker est multi-source dès V1 aucune source HTTP/WS/gRPC unique n'est supposée a priori Config reste l'unique owner des secrets KSP_SECRET_HELIUS_API_KEY doit être réutilisée dans le futur au lieu de créer un second secret aucune URL/endpoints Helius n'est ajoutée pendant 0.3.9 mainnet/mainnet-beta n'est pas renommé sans audit de compatibilité kbot3 reste fonctionnel-only ``` ### 7.2 Questions ouvertes pour `ksp-worker-api` `pre.001` doit répondre sans projeter les besoins RawTransaction : ```text WorkerId propre ou autre identité générique ? états lifecycle exacts ? Created/Starting/Running/Stopping/Stopped/Faulted nécessaires ? health est-il distinct de lifecycle ? quel snapshot générique minimal ? quelle notion générique de progression/activity existe réellement pour un service continu ? latest-value source/sequence doit-elle être directement dans Worker API ? stop/cancellation : primitive séparée ou intégrée au handle ? restart/restartability appartient-elle à l'API ou au caller ? quelle immutabilité après fault/stop ? quels contrats Send/Sync/object-safe ? external implementation sans runtime KSP possible ? Core-only est-il suffisant comme dépendance exacte ? ``` Aucun type spécifique à transaction, slot, provider, endpoint, Store, replay ou backfill ne doit apparaître pour « faciliter » le premier consumer. ### 7.3 Questions ouvertes pour l'audit RAW de fin de release L'audit doit déterminer, sans implémenter le worker : ```text quelles sources sont admissibles en continuous ingest ? quelles sources fournissent une transaction complète directement ? quelles sources font seulement discovery et nécessitent hydration ? quelles sources sont utiles pour gap repair/catch-up ? quelles sources peuvent aussi servir au backfill historique ? quelles combinaisons multi-source apportent redondance ou complémentarité réelle ? quels gaps Transport/Config doivent être comblés en 0.3.10 ? ``` --- ## 8. Objectifs/livrables `0.3.9` Livrables attendus : ```text crates/ksp-worker-api/ Cargo.toml src/ tests/ README.md USAGE.md docs/plans/ docs/validation/ document/matrice d'audit RawTransaction de fin de release handoff explicite vers 0.3.10 deltas/0.3.9/pre.NNN.md / fix / rel.001 prompt 0.3.10 dans la tranche de publication finale ``` Le document d'audit RAW peut être intégré au plan/architecture/référence la plus appropriée après décision de `pre.001`; ne pas créer un fichier arbitraire si un owner documentaire existe déjà. --- ## 9. Hors périmètre `0.3.9` Interdit dans cette release sauf correction indispensable d'une contradiction découverte et explicitement rescopée : ```text ksp-worker-raw-transaction-ingest-lib worker RawTransaction fonctionnel persistance live RawTransaction depuis un nouveau worker ksp-app-raw-transaction-ingest-desk modification multi-source de ksp-job-backfill-lib modification multi-source de ksp-app-backfill-desk nouveaux endpoints/profils Helius runtime nouvelles URLs Helius Config nouveau secret Helius decode Program / STRUCTURAL / DECODED / DOMAIN nouveau backend Store SQL/schema/migration pour le worker scheduler global / control plane / remote worker protocol Tauri/IPC Worker ``` `0.3.9` **peut documenter** les adaptations Transport/Config requises par `0.3.10`; elle ne doit pas les implémenter par anticipation pendant l'audit. --- ## 10. Contraintes sécurité/API/architecture spécifiques ### 10.1 Dépendances `ksp-worker-api` Cible initiale à challenger en `pre.001` : ```text ksp-worker-api -> ksp-core-lib uniquement ``` Ne pas ajouter sans preuve : ```text ksp-job-api ksp-interface-lib ksp-config-lib ksp-logging-lib ksp-onchain-transport-lib ksp-store-api ksp-store-lib tokio futures serde Tauri provider SDK ``` Une API passive ne doit pas devenir runtime-owned par commodité. ### 10.2 Debug / sécurité Les surfaces génériques doivent : ```text bornes explicites pour identities/codes Debug sûr et borné aucun payload/secret arbitraire dans errors/snapshots aucun Box externe conservé dans état public codes d'erreur KSP statiques aucune queue non bornée aucun listener lent autorisé à bloquer le producteur ``` ### 10.3 Runtime ownership `ksp-worker-api` décrit des contrats ; elle ne crée pas automatiquement un runtime Tokio, thread, scheduler ou process. Le futur `ksp-worker-raw-transaction-ingest-lib` de `0.3.10` possédera la logique runtime concrète correspondante. --- ## 11. Première mission `pre.001` — audit, brainstorming, sizing et planification **Ne pas commencer l'implémentation lourde avant la sortie de ce gate.** ### 11.1 Vérifier la base - archive/tag stable `v0.3.8` ; - `workspace.package.version` ; - `rel.001` ; - membres workspace ; - versions/file headers ; - audits Rust/Markdown baseline ; - `cargo tree` actuel de `ksp-job-api` et dépendances voisines. ### 11.2 Auditer `ksp-job-api` Construire une matrice : ```text concept Job propriété réellement générique ? pertinent pour Worker ? réutilisation conceptuelle ? duplication justifiée ? interdit dans Worker ? ``` Ne pas résoudre par héritage nominal ou dépendance de crate avant cette matrice. ### 11.3 Brainstorm Worker API Définir : ```text identity state machine health model snapshot minimal notification/latest-value semantics stop/cancellation fault semantics restart ownership thread-safety/object-safety public API surface error codes Debug/redaction external implementation test ``` Chaque élément doit être justifié par un worker générique, pas uniquement par RAW Transaction. ### 11.4 Dependency/threat map Documenter : ```text allowed dependency graph forbidden reverse edges runtime ownership unbounded queue risks slow listener risks stale snapshot/race risks stop-vs-fault race restart/old-handle race identity/logging leakage ``` ### 11.5 Sizing Recalibrer la release pour rester courte. Objectif : seulement quelques tranches de code Worker API, puis audit RAW et couloirs de fermeture. Si l'API nécessite beaucoup plus de code que prévu, identifier pourquoi avant de l'ouvrir davantage. ### 11.6 Sortie obligatoire de `pre.001` Le gate est fermé seulement avec : ```text architecture Worker API décidée state/health/snapshot/stop semantics décidées surface publique prévue exact dependency map questions différées explicitement listées threat map plan de tests prévision souple recalibrée audit RAW positionné après freeze fonctionnel de l'API aucun code RawTransaction worker commencé ``` --- ## 12. Prévision souple initiale — release volontairement courte La numérotation est prévisionnelle. Les fixes ou splits nécessaires sont autorisés ; ne jamais forcer la fermeture pour respecter un numéro. ### pre.001 — audit / architecture / sizing Worker API Lecture complète, comparaison Job/Worker, state/health/snapshot/cancellation design, dependencies, threat map, tests et sizing. Pas de worker concret. ### pre.002 — contrats `ksp-worker-api` Créer la crate et matérialiser le noyau générique décidé : identities/states/health/snapshot/latest-value/stop uniquement selon le plan validé. Tests unit/public/dependency dès la même tranche. #### pre.002-fix.NNN — correctifs éventuels du noyau API Uniquement si le contrat générique de `pre.002` présente un défaut réel. ### pre.003 — hardening / external implementation / freeze fonctionnel Fermer lifecycle races, Send/Sync, object-safety si requise, external consumer/implementation, Debug/redaction, exact export/module inventories et dependency firewall. **À la fin de cette tranche, Worker API doit être considérée fonctionnellement fermée avant l'audit RAW Transaction.** ### pre.004 — audit fonctionnel exhaustif des sources `RawTransaction` + handoff `0.3.10` Tranche principalement documentaire/research, placée volontairement après la freeze Worker API. Elle ne modifie ni Worker API pour des besoins Solana-specific, ni Transport/Config/endpoints par anticipation. ### pre.005 — gate technique final ```text fmt/audits/check/clippy/tests workspace ksp-worker-api ciblé graphes Cargo / duplicates pertinents ``` Aucun smoke réseau n'est requis pour Worker API elle-même. Un éventuel probe externe de l'audit source reste diagnostic et ne transforme pas `0.3.9` en implémentation Transport. ### pre.006 — réconciliation documentaire finale README/USAGE Worker API, plan/validation, architecture/référence et document d'audit RAW final. `USAGE.md` reste version-neutral. ### pre.007 — préparation de publication Uniquement : ```text prompt 0.3.10 CHANGELOG.md ROADMAP.md Cargo.toml mécanique delta ``` ### rel.001 — publication stable Publication mécanique `v0.3.9`, aucun rattrapage fonctionnel/documentaire. Le nombre de tranches de **code** est volontairement faible. Si `pre.001` conclut que `pre.002` + `pre.003` peuvent être fusionnées sans dépasser les budgets/risques, la prévision peut être raccourcie ; les couloirs audit RAW, gate technique, réconciliation documentaire et publication restent séparés selon leurs responsabilités. --- ## 13. Audit RAW Transaction obligatoire de fin `0.3.9` ### 13.1 Principe Ne jamais commencer par : ```text "le worker sera HTTP" "le worker sera WebSocket" "le worker sera gRPC" ``` Commencer par les **capabilities d'acquisition** et les rôles qu'elles remplissent. ### 13.2 Familles/méthodes minimales à examiner Au minimum : ```text HTTP getSignaturesForAddress + getTransaction HTTP slots / getBlocks / getBlock WS logsSubscribe + éventuelle hydration HTTP WS signatureSubscribe + éventuelle hydration WS blockSubscribe lorsque réellement disponible extensions transactionnelles provider-specific dont Helius transactionSubscribe Yellowstone transactions Yellowstone transaction_status Yellowstone blocks Yellowstone block_meta replay / from_slot / catch-up lorsque le provider le supporte multi-provider / multi-transport ``` Ajouter toute autre voie courante découverte dans les sources primaires. ### 13.3 Matrice obligatoire par source/méthode Pour chaque voie : | Dimension | Question obligatoire | |---------------------|----------------------------------------------------------------------------| | transport/protocole | HTTP, WS, Yellowstone gRPC, provider-specific ? | | provider | standard Solana, Helius, PublicNode, OrbitFlare, autre réellement audité ? | | réseau | Mainnet, Devnet, Testnet selon disponibilité réelle ? | | disponibilité | free, payant, provider/tier-dependent au moment de l'audit ? | | temporalité | live, catch-up, gap-repair, historique ? | | discovery | comment la transaction est-elle découverte ? | | contenu | transaction complète directe, référence, logs, statut, block ? | | hydration | `getTransaction` ou autre lecture complémentaire nécessaire ? | | filtres | compte/programme/signature/slot/success/failure/vote/etc. ? | | ordering | ordre garanti, seulement observé, ou aucun ? | | duplication | quelles duplications/replays attendre ? | | reconnect | comportement sur coupure et resubscribe ? | | replay | slot/checkpoint/from_slot réellement supporté ? profondeur ? | | gap repair | comment détecter/réparer une coupure ? | | backpressure | comportement si KSP consomme plus lentement ? | | commitment/finality | quelles informations et garanties ? | | provenance | metadata sûre à conserver dans `RawTransactionObservation` ? | | quotas/limits | RPS, subscriptions, account filters, response limits, tier ? | | gap Transport KSP | capability déjà présente ou adaptation `0.3.10` ? | | gap Config KSP | profil/secret/capability descriptor à ajouter en `0.3.10` ? | | applicability | continuous ingest, catch-up/gap repair, historical backfill ? | La table finale doit respecter le formateur/audit Markdown KSP. ### 13.4 Relations entre sources Classer explicitement les combinaisons utiles : ```text alternative = A ou B pour le même rôle complémentaire = discovery A + hydration B redondante = A + B en parallèle pour résilience/coverage spécialisée = source dédiée live, catch-up, gap-repair ou historique ``` Le futur worker peut combiner plusieurs catégories. Éviter un modèle trop pauvre comme : ```rust // À ne pas adopter comme architecture par défaut. enum Source { Http, WebSocket, Grpc, } ``` Les rôles/capabilities importent davantage que le protocole nominal. ### 13.5 Pipeline de convergence à préparer Le handoff `0.3.10` doit aboutir conceptuellement à : ```text source(s) / discovery / direct stream / hydration | v normalisation source-independent RawTransaction | +--> RawTransactionObservation par acquisition | v ksp-store-lib ``` La déduplication ne doit pas effacer les observations de provenance légitimes. ### 13.6 Helius L'audit doit : ```text réauditer la documentation/pricing/capabilities Helius courants examiner HTTP standard Mainnet + Devnet examiner WS standard Mainnet + Devnet examiner séparément les extensions enhanced/advanced telles que transactionSubscribe ne jamais supposer qu'un endpoint Helius donne accès à toutes les capabilities réutiliser KSP_SECRET_HELIUS_API_KEY via Config dans la future 0.3.10 ne créer aucun second secret ne pas ajouter les URLs/endpoints Helius dans 0.3.9 ``` Aucune URL historique kbot3 n'est transférée comme vérité KSP. ### 13.7 `mainnet` / `mainnet-beta` Auditer avant toute décision d'implémentation : ```text RawNetworkId / Store persisté Config profiles/targets Transport network descriptors provider naming Backfill scope fingerprints/checkpoints CLI/external aliases ``` Objectif : > un même cluster de production ne doit jamais devenir deux identités KSP indépendantes. Ne pas renommer/migrer dans `0.3.9`. Le handoff `0.3.10` doit proposer une stratégie compatible ou conclure explicitement qu'aucun changement n'est nécessaire. ### 13.8 Réutilisation future par Backfill La matrice n'est pas seulement « live worker ». Elle doit indiquer pour chaque source : ```text continuous ingest ? gap repair / catch-up ? historical backfill ? ``` Cette même matrice devient l'entrée de `0.3.12` pour étendre `ksp-job-backfill-lib` et `ksp-app-backfill-desk` sans refaire l'erreur d'une hypothèse mono-source. --- ## 14. Règles de versionnement, deltas, commits et tags Conserver le workflow KSP : ```text 0.3.9-pre.1 / pre.2 / ... dans workspace.package.version pour changements code/build/runtime/config fix code/test/build => version Cargo fix correspondante fix strictement documentaire => pas de bump workspace.package.version deltas/0.3.9/pre.NNN.md deltas/0.3.9/pre.NNN-fix.MMM.md deltas/0.3.9/rel.001.md ``` Le premier delta `pre.001` peut rester doc-only et conserver `workspace.package.version = 0.3.8` si aucun code/build/runtime/config n'est modifié, conformément aux règles de versioning KSP. Le premier changement Rust porte alors le bump technique de prerelease. Archives d'échange minimales selon leur scope : ```text ksp-doc-.zip ksp-general-.zip ``` Ne jamais livrer une copie complète du dépôt comme « delta ». Tags : ```text seul le stable final v0.3.9 est taggé selon le workflow courant ``` --- ## 15. Validation opérateur ### 15.1 Baseline / chaque tranche Rust ```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 cargo check --workspace cargo clippy --workspace --all-targets ``` Puis tests ciblés : ```bash cargo test -p ksp-worker-api ``` et, selon les changements : ```bash cargo test -p ksp-job-api cargo test -p ksp-core-lib cargo tree -p ksp-worker-api --edges normal cargo tree -p ksp-worker-api -e features ``` ### 15.2 Gate final Le gate technique final inclut au minimum : ```bash cargo fmt --all -- --check 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 cargo check --workspace cargo clippy --workspace --all-targets --all-features -- -D warnings cargo test --workspace --all-targets --all-features cargo tree -p ksp-worker-api --edges normal cargo tree -p ksp-worker-api -e features cargo tree --duplicates ``` Le shell opérateur peut continuer après une commande rouge ; lire chaque résultat. Une commande ultérieure verte n'annule jamais un échec antérieur. --- ## 16. Tests attendus pour `ksp-worker-api` Le plan `pre.001` doit au minimum prévoir des preuves sur : ```text exact lifecycle transition matrix invalid transition leaves state unchanged stop/cancel idempotence stop-vs-fault/terminal races snapshot latest-value observable par listeners lents indépendants sequence monotone / exhaustion explicite si sequence utilisée late listener resync Debug/redaction hostile values identity exact bounds Send/Sync external consumer / external implementation crate-root public surface exact dependency firewall exact module/export inventories aucun Transport/Store/Config/Tauri/Job-specific type ``` Les tests ne doivent pas inventer un runtime concret si l'API est passive. --- ## 17. Critères de clôture `0.3.9` La release n'est publiable que lorsque : ```text ksp-worker-api est stable, documentée et générique Worker/Job semantics restent distinctes aucun type Solana/Transport/Store/provider n'a contaminé Worker API public/dependency/security/race gates sont verts README/USAGE version-neutral sont réconciliés audit RawTransaction exhaustif terminé après freeze Worker API matrice sources/méthodes couvre live/catch-up/gap-repair/history multi-source alternatives/complements/redundancy/specialization documenté gaps Transport/Config 0.3.10 explicités Helius future use réauditée sans endpoint ajouté en 0.3.9 mainnet/mainnet-beta strategy auditée sans migration prématurée applicability future Backfill 0.3.12 documentée workspace final green prompt 0.3.10 cohérent avec l'audit final CHANGELOG/ROADMAP finalisés dans le couloir de publication rel.001 mécanique uniquement ``` --- ## 18. Release/session suivante envisagée — `0.3.10` Objectif prévu : ```text ksp-worker-raw-transaction-ingest-lib ``` Cette release doit **consommer l'audit produit par `0.3.9`**, pas repartir d'une hypothèse de protocole unique. Elle pourra inclure : ```text adaptations ksp-onchain-transport-lib réellement nécessaires adaptations ksp-config-lib réellement nécessaires profils Helius HTTP/WS nécessaires Mainnet/Devnet réutilisation KSP_SECRET_HELIUS_API_KEY multi-source / multi-provider discovery + hydration lorsque nécessaire direct full-transaction streaming lorsque disponible gap repair / reconnect / recovery normalisation canonique RawTransaction RawTransactionObservation par acquisition persistance atomique/idempotente via ksp-store-lib supervision via ksp-worker-api ``` Elle ne doit pas : ```text copier kbot3 hardcoder une source unique sans justification d'audit confondre provider/tier avec capability générique renommer mainnet-beta de manière destructive ouvrir Decode/STRUCTURAL/DOMAIN ``` `0.3.11` sera la Desk de choix/supervision des sources ; `0.3.12` réutilisera la matrice pour étendre Backfill. --- ## 19. Instruction d'ouverture Au début de la prochaine session : 1. vérifier la base stable exacte `v0.3.8` et `deltas/0.3.8/rel.001.md` ; 2. lire les règles et architectures obligatoires dans l'ordre du présent prompt ; 3. auditer `ksp-job-api` comme référence de propriétés génériques **sans supposer une dépendance Worker -> Job** ; 4. inventorier la surface exacte attendue de `ksp-worker-api`, les risques et les dépendances ; 5. produire `pre.001` avec brainstorming, sizing, plan/tests/gates et prévision souple recalibrée ; 6. **ne pas commencer `ksp-worker-raw-transaction-ingest-lib`, ne pas ajouter d'endpoint Helius et ne pas modifier Transport/Config pour l'ingestion avant fermeture du gate Worker API prévu** ; 7. réserver l'audit exhaustif RawTransaction à la fin de `0.3.9`, après freeze fonctionnel de Worker API, puis utiliser ce document comme handoff autoritaire vers `0.3.10`. Ne pas répondre à une incertitude par une hypothèse : auditer la base, les sources primaires et les règles KSP, puis documenter la décision.