diff --git a/CHANGELOG.md b/CHANGELOG.md index aafb82e..56b4803 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,26 @@ - + # Changelog KSP +## 0.3.8 — Store Desk V1 RAW, inspection backend-neutral et trajectoire Worker multi-source — 2026-09-04 + +`0.3.8` introduit `ksp-app-store-desk`, application Tauri KSP read-only dédiée à l'inspection du Store. Le package reprend le gabarit Desk commun (splash/shell/assets/styles/tracing), compose `ksp-config-lib`, `ksp-logging-lib` et la seule façade `ksp-store-lib`, et interdit à l'application tout accès direct à `ksp-store-api`, `ksp-store-postgres-lib`, SQL, driver/pool PostgreSQL, Transport on-chain ou ressource physique. Le bootstrap ouvre un Store lié au profil/réseau composite, expose health/runtime backend-neutral et effectue un shutdown borné à la fermeture de la fenêtre principale. + +Pour éviter de détourner la pagination machine existante, Store API ajoute une primitive d'inspection backend-neutral distincte : `RawInspectionPageRequest`/`RawInspectionPage`, summaries `RawTransaction`/`RawAccountState` sans gros bytes et quatre capabilities d'inspection couvrant entités et observations. Le backend PostgreSQL implémente les vues d'inspection par `COUNT` exact + `OFFSET/LIMIT` contrôlé, tandis que les queries historiques `RawPage` restent keyset/cursor, sans `OFFSET`, pour workers, backfills et replays. La façade `ksp-store-lib` conserve ainsi le même ensemble de 14 capabilities RAW que le backend sans exposer de détail physique. + +La Desk projette `RawTransaction` et `RawAccountState` via DataTables `serverSide` avec **un seul pager visible**, filtres Store explicites, tailles de page bornées et counts vérifiés avant conversion JavaScript. Les détails sont chargés à la demande avec preview RAW bornée à 512 octets ; les rows ne transportent pas le payload transactionnel ni les bytes account. Les observations Transaction/Account sont elles aussi paginées côté serveur dans les détails et n'exposent que la provenance sûre déjà normalisée par Store API : provider/protocol/method/origin, timestamps, endpoint/session/filter/commitment optionnels, hash/taille de payload source et metadata Yellowstone account lorsqu'elle existe, jamais les bytes source. Les identifiants longs utilisent affichage tronqué, tooltip et copie explicite ; le tracing frontend reste metadata-only et ne journalise aucune valeur métier copiée. + +Le hardening final fige les inventaires Cargo/npm/modules/commands/capabilities Tauri, la composition Config, l'absence de réseau/browser-storage/SQL/backend physique dans le frontend, les DTO IPC sans curseur machine et la coexistence exacte entre navigation keyset et inspection random-access. Le correctif `pre.012-fix.001` réaligne aussi `tsconfig.json` Store Desk byte-for-byte sur le gabarit TypeScript commun des autres Desk, ce qui rétablit le build `tsc && vite build` des imports CSS DataTables et ajoute un canari de non-divergence. + +Le gate technique autoritaire passe `cargo fmt --all -- --check`, audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, `cargo test --workspace --all-targets --all-features`, `ksp-store-lib --no-default-features`, graphes Cargo et build Tauri Store Desk ; il comptabilise 1 592 tests passés, 0 échec et 15 tests opt-in/operator-only ignorés. Après la réconciliation documentaire, un rerun propre depuis `cargo clean` confirme encore les audits/check/Clippy/tests et reconstruit avec succès les cinq Desk KSP Config, SOL Prices, Wallet, Backfill et Store en bundles Linux `.deb` + `.rpm`, sans rouvrir le runtime. + +La trajectoire suivante est explicitement redécoupée pour éviter de répéter l'hypothèse HTTP du premier backfill. `0.3.9` introduira d'abord `ksp-worker-api` comme abstraction générique de service continu, puis seulement **après fermeture fonctionnelle de cette API** produira un audit exhaustif des sources/méthodes `RawTransaction`. Cet audit couvrira HTTP, WS standard, extensions provider, Yellowstone gRPC, block/slot, discovery + hydration, replay/gap-repair et multi-provider, et classera les sources comme alternatives, complémentaires, redondantes ou spécialisées. Il servira d'entrée architecturale à `0.3.10`, qui introduira `ksp-worker-raw-transaction-ingest-lib` multi-source dès V1 et ne modifiera Transport/Config que pour les adaptations réellement justifiées par l'audit. Les futures sources Helius HTTP/WS Mainnet/Devnet devront réutiliser `KSP_SECRET_HELIUS_API_KEY` via Config ; aucune URL Helius n'est ajoutée par `0.3.8`. La terminologie `mainnet`/`mainnet-beta` sera auditée avant tout changement afin de préserver une identité KSP unique pour le même cluster. + +`0.3.11` ouvrira ensuite `ksp-app-raw-transaction-ingest-desk`, capable de choisir/superviser une ou plusieurs sources/méthodes sans dupliquer la logique du worker. `0.3.12` reviendra sur `ksp-job-backfill-lib` et `ksp-app-backfill-desk` pour ajouter les autres stratégies historiques/catch-up pertinentes issues du même audit ; la verticale `getSignaturesForAddress + getTransaction` de `0.3.6`/`0.3.7` reste une première stratégie HTTP valide, pas la définition générale du backfill KSP. kbot3 reste uniquement une référence fonctionnelle pour ces audits, jamais une source de code, DTO, Config, URL ou dépendance. + +`prompts/028-V0_3_9_START_PROMPT.md` ouvre `0.3.9` sur cette base : Worker API doit rester Core-only/générique et être stabilisée avant l'audit RAW Transaction, lequel prépare `0.3.10` sans ajouter de worker concret ni d'endpoints provider pendant `0.3.9`. + ## 0.3.7 — Backfill Desk : contrôle, monitoring, Cancel/Resume et autocomplete — 2026-09-03 `0.3.7` introduit `ksp-app-backfill-desk`, première application Tauri KSP spécialisée dans le contrôle d'un `ksp-job-backfill-lib` historique `RawTransaction`. L'application reste une couche de composition : `ksp-config-lib` possède les profils/composites/secrets, `ksp-onchain-transport-lib` le pool HTTP et les politiques provider/retry/rate-limit, `ksp-store-lib` la persistence backend-neutral, `ksp-job-backfill-lib` la découverte/hydratation/frontier/checkpoint/runtime et `ksp-job-api` le lifecycle commun. La Desk ne dépend ni d'un backend Store physique, ni de SQL, ni d'un SDK provider. diff --git a/Cargo.toml b/Cargo.toml index 3647a5e..62fc8c1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 473 +# version: 474 [workspace] resolver = "3" members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.3.8-pre.13" +version = "0.3.8-pre.14" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index ddd136e..8979ddd 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -100,10 +100,11 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN - [X] `0.3.5` — `ksp-interface-lib` étendu avec deux familles passives réellement partagées : `SlotLifecycleEvent` (`Processed`, `FirstShredReceived`, `Completed`, `CreatedBank`, `Dead`, `OptimisticallyConfirmed`, `Rooted`) et `TransactionExecutionEvent` (`slot + TransactionSignature[64] + Succeeded/Failed`). Interface reste Core-only, provider-neutral, sans serde/codec/runtime/event bus et sans duplication de `RawTransaction`/`RawAccountState`; les DTOs riches restent Transport-owned et les candidats non convergents restent différés. - [X] `0.3.6` — `ksp-job-api` + `ksp-job-backfill-lib` stables pour la première verticale historique `RawTransaction` : lifecycle/cancellation/latest-value runtime-neutral, scopes `Latest`/`Before`/`After`/signatures explicites, découverte/hydratation Transport observée, RAW v1 canonique, persistance Store atomique/idempotente, concurrence bornée, frontier contiguë, checkpoint/reprise caller-owned, snapshots sûrs et hardening externe sans dépendance backend/provider directe. - [X] `0.3.7` — `ksp-app-backfill-desk` livrée comme Desk Tauri KSP spécialisée : composition Config Mainnet/Devnet/Testnet, quatre scopes HTTP, validation/start single-run, monitoring latest-value `ksp-backfill-status`, Cancel ciblé/idempotent, Resume in-session par checkpoint Rust-only réémis pour un nouveau JobId, autocomplete libre depuis `ksp-core-lib`, hardening IPC/dependency boundaries et build Linux `.deb`/`.rpm`/`.AppImage`. Aucun SQL/backend/provider physique ni checkpoint durable n’est exposé. -- [ ] `0.3.8` — Introduire `ksp-app-store-desk` V1 sur le **gabarit KSP courant** (shell/splash/styles/assets/logging et dépendances npm de base des Desk KSP), avec DataTables selon le pattern déjà utilisé par Config/Wallet Desk. La V1 reste backend-agnostique et consulte le Store uniquement via `ksp-store-lib` + Config : health/runtime sûr, tableaux `RawTransaction` et `RawAccountState`, observations lorsque la surface de listing backend-neutral est disponible/ajoutée proprement, rétention/tombstones en lecture et pagination Store opaque distincte du filtrage/paging local DataTables. kbot3 sert uniquement de référence fonctionnelle/UX des anciens tableaux RAW, jamais de gabarit, source de code, SQL, DTO, commandes ou versions npm. L’application évoluera ensuite avec STRUCTURAL, DECODED, processing/materialization et DOMAIN réellement persistés. -- [ ] `0.3.9` — Introduire `ksp-worker-api` comme API générique de lifecycle/health/progression pour services continus, en reprenant le pattern latest-value stabilisé par Job tout en gardant les sémantiques Worker distinctes des jobs terminables et des wake-ups Store post-commit. -- [ ] `0.3.10` — Introduire `ksp-worker-raw-transaction-ingest-lib` pour l'acquisition continue de `RawTransaction` via les surfaces live de `ksp-onchain-transport-lib`, persistance atomique par `ksp-store-lib`, reprise/backpressure/idempotence et notifications `ksp-worker-api`, sans decode Program ni dépendance backend/provider directe. -- [ ] `0.3.11` — Introduire `ksp-app-raw-transaction-ingest-desk`, application Tauri spécialisée de contrôle et monitoring du worker live : lifecycle, health, rates, backpressure, reconnect/recovery et compteurs sûrs ; la consultation détaillée des données persistées reste la responsabilité de `ksp-app-store-desk`. +- [X] `0.3.8` — `ksp-app-store-desk` V1 RAW livrée sur le gabarit KSP courant comme application Tauri read-only backend-neutral. La Desk compose Config + Logging + `ksp-store-lib`, expose health/runtime sûrs, DataTables `serverSide` pour `RawTransaction`, `RawAccountState` et leurs observations, détails bornés, provenance sûre et états de rétention/tombstone, sans SQL/backend physique/Transport dans l'application. La nouvelle inspection random-access `offset + limit + counts exacts` reste distincte de la pagination machine cursor/keyset conservée pour workers/backfills/replays. Le gate final et les builds Linux `.deb`/`.rpm` sont verts. +- [ ] `0.3.9` — Introduire `ksp-worker-api` comme API **générique et volontairement courte** de lifecycle/health/progression/snapshot pour services continus, distincte de `ksp-job-api` et sans dépendance Solana/Transport/Store/Tauri. Une fois l'API Worker fonctionnellement fermée, terminer la release par un audit fonctionnel exhaustif des sources/méthodes d'acquisition `RawTransaction` : HTTP, WS standard, extensions provider, Yellowstone gRPC, blocks/slots, discovery + hydration, replay/gap-repair et combinaisons multi-provider. Cet audit prépare `0.3.10` sans ajouter d'endpoint ni de Config provider dans `0.3.9`. +- [ ] `0.3.10` — Introduire `ksp-worker-raw-transaction-ingest-lib` **multi-source dès V1**. Le worker compose les stratégies retenues par l'audit `0.3.9` comme sources alternatives, complémentaires, redondantes ou spécialisées live/catch-up/gap-repair, converge vers `RawTransaction + RawTransactionObservation`, persiste par `ksp-store-lib` et utilise `ksp-worker-api` pour supervision/cancellation. Cette release porte aussi, et seulement si l'audit les justifie, les adaptations nécessaires de `ksp-onchain-transport-lib`/`ksp-config-lib` : futures sources Helius HTTP/WS Mainnet/Devnet avec réutilisation de `KSP_SECRET_HELIUS_API_KEY`, capabilities/tier réaudités au moment du travail, et éventuelle canonicalisation `mainnet`/`mainnet-beta` uniquement avec stratégie de compatibilité sûre. Aucun decode Program ni dépendance backend/provider directe dans le worker. +- [ ] `0.3.11` — Introduire `ksp-app-raw-transaction-ingest-desk`, Desk Tauri KSP spécialisée qui choisit et supervise **une ou plusieurs sources/méthodes** réellement admises par `0.3.10` : lifecycle, health, rates, backpressure, reconnect/recovery, gap state et compteurs sûrs. La Desk ne réimplémente ni discovery, hydration, déduplication, reprise ni persistence ; l'inspection détaillée des RAW persistés reste la responsabilité de `ksp-app-store-desk`. +- [ ] `0.3.12` — Étendre `ksp-job-backfill-lib` et `ksp-app-backfill-desk` au **backfill multi-source/multi-stratégie** à partir de la même matrice d'acquisition auditée en `0.3.9`. Conserver la stratégie actuelle `getSignaturesForAddress + getTransaction` comme première voie HTTP valide, puis ajouter seulement les voies historiques/catch-up/gap-repair réellement pertinentes et sûres (par exemple block/slot, replay provider lorsqu'il existe), sans supposer qu'une source live WS constitue un historique universel. ### TODO/IDEAS — applications spécialisées et control plane @@ -113,6 +114,9 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN ### TODO/IDEAS — taxonomie N1, processing et rétention - [ ] **TODO** — maintenir la matrice d’admission HTTP/WS/gRPC/provider lors de toute nouvelle famille N1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte. +- [ ] **TODO `0.3.9`** — produire après fermeture de `ksp-worker-api` une matrice RAW Transaction unique et réutilisable par `0.3.10` puis `0.3.12`, couvrant discovery, hydration/direct payload, filtres, ordering/duplicates, reconnect/replay, gap repair, backpressure, commitment, provenance, quotas, gaps Transport/Config et applicability continuous-ingest/catch-up/backfill. +- [ ] **TODO Helius futur** — ne pas ajouter d'URL/endpoints Helius en `0.3.8` ni pendant la construction générique de Worker API. L'audit `0.3.9` réévalue les capabilities/tier courants ; `0.3.10` peut ensuite ajouter les profils HTTP/WS réellement nécessaires en réutilisant exclusivement `KSP_SECRET_HELIUS_API_KEY` via Config. +- [ ] **TODO réseau** — auditer `mainnet` vs `mainnet-beta` avant tout renommage : Store persisté, Config, Transport, checkpoints/fingerprints et aliases externes doivent converger vers une identité KSP unique pour le même cluster ; aucune migration/canonicalisation n'est supposée avant cette preuve. - [X] `RawAccountState` + observation — contrat commun stabilisé en `0.3.1` avec bytes complets + slot, provenance séparée et enrichissements source-specific optionnels ; la persistence PostgreSQL physique est complétée en `0.3.4` avec les quatre capabilities account et la conformance RAW 10/10. - [ ] **TODO** — statut/commitment transactionnel restant : `0.3.5` couvre uniquement le fait passif d’exécution `slot + signature + outcome`; réauditer séparément `signatureSubscribe` et `getSignatureStatuses` lorsqu’un consumer de commitment/snapshot réel apparaît, sans fusionner snapshot, transition et execution update dans un modèle Option-soup. - [ ] **IDEA** — logs realtime enrichis : `logsSubscribe` alimente déjà la projection minimale `TransactionExecutionEvent`, mais un éventuel `TransactionLogEvent` portant les lignes de log reste différé dans `docs/IDEAS.md` jusqu’à démonstration d’un consumer et de bornes explicites. `logMessages` reste dans `RawTransaction` jusqu’à STRUCTURAL ; le wake-up post-commit reste distinct et Store API-owned conformément à `KSP-NOTIFY-*`. diff --git a/deltas/0.3.8/pre.014.md b/deltas/0.3.8/pre.014.md new file mode 100644 index 0000000..8877613 --- /dev/null +++ b/deltas/0.3.8/pre.014.md @@ -0,0 +1,150 @@ + + + +# Delta `0.3.8-pre.014` — préparation de publication et ouverture `0.3.9` + +## 1. Base requise + +```text +0.3.8-pre.013-fix.001 +workspace.package.version = 0.3.8-pre.13 +``` + +`pre.013-fix.001` est une correction strictement documentaire de la réconciliation `pre.013`; elle n'a donc pas modifié la version Cargo. + +## 2. Objectif + +Exécuter exclusivement le couloir final de préparation de publication autorisé par `PROMPT_STRUCTURE.md` : + +```text +CHANGELOG.md +ROADMAP.md +prompt de démarrage 0.3.9 +Cargo.toml mécanique de prerelease +delta courant +``` + +Aucune correction d'architecture durable n'est absorbée ici : la trajectoire Worker/RAW multi-source a été documentée séparément dans `pre.013-fix.001` avant cette tranche. + +## 3. Version + +```text +workspace.package.version = 0.3.8-pre.14 +Cargo.toml file header = 474 +``` + +Aucun manifest de crate, dépendance, feature, code, test ou Config ne change. + +## 4. ROADMAP + +`0.3.8` est marqué terminé sur sa surface réellement livrée. + +La trajectoire `0.3.9` à `0.3.12` devient : + +```text +0.3.9 ksp-worker-api générique, puis audit exhaustif RawTransaction en fin de release +0.3.10 ksp-worker-raw-transaction-ingest-lib multi-source dès V1 + adaptations Transport/Config justifiées +0.3.11 ksp-app-raw-transaction-ingest-desk avec choix/supervision d'une ou plusieurs sources/méthodes +0.3.12 extension multi-source de ksp-job-backfill-lib + ksp-app-backfill-desk +``` + +Les TODOs rappellent également : + +```text +matrice acquisition unique réutilisée live + backfill +aucune URL/endpoints Helius ajoutés en 0.3.8/pendant la construction générique Worker API +réutilisation future de KSP_SECRET_HELIUS_API_KEY via Config +réaudit provider/tier au moment de 0.3.9/0.3.10 +mainnet/mainnet-beta audité avant toute canonicalisation/migration +``` + +## 5. CHANGELOG + +Ajoute l'entrée finale `0.3.8` : + +- Store Desk V1 RAW read-only ; +- inspection backend-neutral random-access distincte du cursor/keyset machine ; +- tables Transaction/Account/observations DataTables server-side ; +- détails bornés et provenance sûre ; +- security/dependency completeness ; +- correction du `tsconfig.json` commun ; +- gates techniques/builds finaux ; +- trajectoire Worker/API/ingest/backfill multi-source acquise. + +## 6. Prompt `0.3.9` + +Ajout : + +```text +prompts/028-V0_3_9_START_PROMPT.md +``` + +Le prompt est autoportant et impose : + +```text +pre.001 audit/brainstorm/sizing avant code lourd +ksp-worker-api générique et courte +freeze fonctionnelle Worker API avant audit RawTransaction +audit exhaustif HTTP/WS/provider/Yellowstone/block-slot/replay/multi-provider +aucun endpoint Helius ajouté en 0.3.9 +réutilisation future KSP_SECRET_HELIUS_API_KEY +mainnet/mainnet-beta audit préalable +handoff autoritaire vers ksp-worker-raw-transaction-ingest-lib 0.3.10 multi-source +réutilisation de la matrice pour Backfill 0.3.12 +kbot3 fonctionnel-only +``` + +## 7. Fichiers modifiés + +```text +Cargo.toml +ROADMAP.md +CHANGELOG.md +``` + +## 8. Fichiers ajoutés + +```text +prompts/028-V0_3_9_START_PROMPT.md +deltas/0.3.8/pre.014.md +``` + +## 9. Fichiers supprimés + +Aucun. + +## 10. Hors scope + +```text +README / USAGE +plans / validations / architecture +src/** +tests/** +frontend/** +Config / schemas / .env +ksp-worker-api code +ksp-worker-raw-transaction-ingest-lib +ksp-onchain-transport-lib runtime +endpoints/URLs Helius +Store/schema/migrations +``` + +## 11. Validation + +Cette tranche est publication-only hors bump mécanique Cargo. Après overlay : + +```bash +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 +``` + +Le gate technique complet et les builds ont été exécutés avant la réconciliation documentaire et confirmés par le rerun opérateur `pre.013`; aucun code/build/runtime/config n'est rouvert ici. + +## 12. Suite + +Si les audits documentaires sont verts : + +```text +0.3.8-rel.001 — publication stable mécanique +puis ouverture 0.3.9 exclusivement depuis v0.3.8 avec prompts/028-V0_3_9_START_PROMPT.md +``` diff --git a/prompts/028-V0_3_9_START_PROMPT.md b/prompts/028-V0_3_9_START_PROMPT.md new file mode 100644 index 0000000..ac8d900 --- /dev/null +++ b/prompts/028-V0_3_9_START_PROMPT.md @@ -0,0 +1,1112 @@ + + + +# 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.