v0.3.9-pre.009
This commit is contained in:
16
CHANGELOG.md
16
CHANGELOG.md
@@ -1,8 +1,22 @@
|
||||
<!-- file: CHANGELOG.md -->
|
||||
<!-- version: 28 -->
|
||||
<!-- version: 29 -->
|
||||
|
||||
# Changelog KSP
|
||||
|
||||
## 0.3.9 — Worker API générique + audit exhaustif d'acquisition RawTransaction — 2026-09-05
|
||||
|
||||
`0.3.9` introduit `ksp-worker-api` comme façade générique, courte et runtime-neutral pour services continus. La surface stable reste Core-only et expose `WorkerId`, `WorkerKindCode`, `WorkerState`, `WorkerHealth`, `WorkerActivity`, `WorkerLifecycle`, `WorkerStopToken`, `WorkerSnapshotSequence`, `WorkerSnapshot`, `WorkerSnapshotFuture` et `WorkerSnapshotSource`. Les identités sont bornées et redacted, le lifecycle possède des transitions explicites avec terminaux immuables, le stop token est partagé/idempotent, la séquence ne wrappe pas et le snapshot source latest-value reste object-safe, `Send + Sync` et implémentable depuis l'extérieur. L'API ne possède aucun runtime `start/stop` universel, aucune sémantique Job/checkpoint, aucun domaine Solana et aucune dépendance Transport/Store/Config/Tauri.
|
||||
|
||||
Après freeze de cette API, la seconde moitié de la release réalise puis consolide l'audit exhaustif des voies d'acquisition `RawTransaction`. Le document durable `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md` est réécrit comme une synthèse unique Store-centrique : `RawTransaction` est le cœur RAW durable, tandis que `RawTransactionObservation` conserve les provenances multiples. L'audit distingue systématiquement possibilité protocolaire/provider, support architectural KSP, support implémenté et preuve live ; il couvre HTTP, WebSocket standard, Helius `transactionSubscribe`, Yellowstone gRPC, acquisition par blocs/slots, discovery + hydration, replay/gap repair, archives et sources EARLY/pre-execution. Les matrices recensent aussi les principaux providers/réseaux/tier/coûts connus sans réduire l'architecture aux seuls comptes gratuits actuellement disponibles.
|
||||
|
||||
La séparation des producteurs RAW est figée. `ksp-job-backfill-lib` reste un producteur historique **paramétré, borné et terminable** ; le futur `ksp-worker-raw-transaction-ingest-lib` sera un producteur live **continu start/stop sans requête métier historique**. Ils ne s'appellent pas, ne se supervisent pas et ne collaborent pas : chacun alimente indépendamment le même Store. HTTP, WS, gRPC, replay et archive sont des capabilities orthogonales à ces rôles ; un Worker peut utiliser HTTP pour hydration ou réparation de sa propre continuité live, tandis qu'un Job pourra utiliser gRPC/replay si une campagne historique bornée le justifie. Le handoff `0.3.10` retient `ksp-raw-transaction-lib` comme lower-layer source-neutral commune afin d'extraire la canonicalisation RAW v1 aujourd'hui locale au Backfill sans duplication ni edge Job ↔ Worker ; les golden bytes/hash RAW v1 doivent rester inchangés.
|
||||
|
||||
La release normalise aussi l'identité réseau KSP : `mainnet` devient l'identité canonique dans Config/Store/Transport/tests et `mainnet-beta` reste seulement un alias legacy/externe lorsque la frontière provider l'exige. Les données Mainnet N1 encore utilisées comme données de test ne dictent aucune compatibilité durable et aucune migration SQL n'est introduite pour préserver l'ancien libellé. Pendant le gate final, les baselines workspace sont également relevées à `jsonschema ^0.53` et `yellowstone-grpc-proto ^12.7`; Yellowstone 12.7 ajoute le RPC serveur `SubscribeGossip`, ce qui nécessite uniquement l'adaptation des fixtures `Geyser` avec une réponse `UNIMPLEMENTED` et n'ouvre aucune capability Gossip de production.
|
||||
|
||||
Le gate technique final passe les audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, 385/385 tests unitaires `ksp-onchain-transport-lib`, 43/43 canaries `release_completeness`, `cargo test --workspace --all-targets --all-features`, le bundle complet `ksp-worker-api` et les graphes Cargo jusqu'à `cargo tree --duplicates`; seuls les smokes/probes explicitement opt-in restent ignorés. La réconciliation documentaire `pre.008` réaligne ensuite README/USAGE/indexes/architecture/plan/validation et son gate opérateur repasse audits Rust/Markdown plus `cargo check --workspace` en `0.3.9-pre.8`.
|
||||
|
||||
`prompts/029-V0_3_10_START_PROMPT.md` ouvre `0.3.10` exclusivement depuis le tag stable `v0.3.9`. La prochaine release doit d'abord matérialiser `ksp-raw-transaction-lib`, migrer le Backfill vers cette canonicalisation commune sans changement fonctionnel, puis construire `ksp-worker-raw-transaction-ingest-lib` multi-source dès V1. Son `pre.001` est obligatoirement un gate d'audit/sizing : inventaire exact des gaps Transport/Config, runtime Worker, capabilities live, continuité, preuves provider et dépendances avant toute implémentation lourde.
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 487
|
||||
# version: 488
|
||||
|
||||
[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", "crates/ksp-worker-api"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.3.9-pre.8"
|
||||
version = "0.3.9-pre.9"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
10
ROADMAP.md
10
ROADMAP.md
@@ -101,8 +101,8 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
- [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é.
|
||||
- [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, la canonicalisation logique `mainnet` étant déjà matérialisée en `0.3.9-pre.006-fix.003`, `0.3.10` ne doit ajouter qu'un éventuel alias de frontière si une source externe l'exige réellement. Aucun decode Program ni dépendance backend/provider directe dans le worker.
|
||||
- [X] `0.3.9` — `ksp-worker-api` stable comme API générique et volontairement courte pour services continus : identité/kind bornés, lifecycle explicite, health/activity sûrs, stop token partagé, séquence/snapshot latest-value et `WorkerSnapshotSource` object-safe, avec dépendance Core-only et sans runtime/start-stop universel, Solana, Transport, Store, Config ou Tauri. Après freeze Worker API, l'audit `RawTransaction` a été consolidé dans une synthèse Store-centrique exhaustive séparant possibilités/support/preuve et classant HTTP, WS standard/provider, Yellowstone gRPC, blocs/slots, discovery + hydration, replay de continuité, archives et sources EARLY. Le Job Backfill historique paramétré et le Worker Ingest live start/stop sont deux producteurs indépendants du même Store ; `mainnet` est désormais l'identité KSP canonique et `mainnet-beta` un alias legacy/externe. Le handoff retient `ksp-raw-transaction-lib` comme lower-layer commune de canonicalisation RAW v1 pour `0.3.10`, sans edge Job ↔ Worker.
|
||||
- [ ] `0.3.10` — Introduire `ksp-raw-transaction-lib` puis `ksp-worker-raw-transaction-ingest-lib` **multi-source dès V1**. La lower-layer commune extrait de `ksp-job-backfill-lib` la canonicalisation RAW v1 sans changer ses golden bytes/hash ni ses campagnes historiques. Le worker continu est démarré/arrêté sans paramètres métier de campagne, ouvre les sources/rôles activés par la composition Config, acquiert depuis son démarrage, persiste `RawTransaction + RawTransactionObservation`, publie ses snapshots/notifications indépendamment de leurs lecteurs et répare uniquement ses propres gaps de continuité live. HTTP, WS, Yellowstone gRPC et extensions provider sont des capabilities orthogonales : HTTP peut servir au live/hydration et gRPC/WS ne deviennent jamais synonymes de Worker. La release porte seulement les adaptations Transport/Config/common réellement justifiées par l'audit (`get_block_observed`, projections full source-neutral, provenance sûre, replay `from_slot`, profils/capabilities nécessaires), avec support architectural conservé même lorsque certains smokes provider restent bloqués par tier. Aucun nouveau backfill multi-stratégie, decode Program, backend physique direct ni dépendance Worker ↔ Job.
|
||||
- [ ] `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.
|
||||
|
||||
@@ -114,9 +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.
|
||||
- [X] **TODO réseau** — audit fermé en `0.3.9` : `mainnet` est l'identité logique canonique KSP ; `mainnet-beta` reste un alias legacy/externe. `pre.006-fix.003` normalise Config/Store/Transport/tests pendant N1 RAW sans migration des données expérimentales, qui peuvent être droppées/recréées.
|
||||
- [X] **TODO `0.3.9`** — matrice RAW Transaction unique produite et consolidée dans `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`, avec séparation possibilités/support/preuve, capabilities orthogonales aux producteurs, provenance/déduplication/continuité et handoffs indépendants `0.3.10` Worker live / `0.3.12` Backfill historique.
|
||||
- [ ] **TODO Helius `0.3.10`** — ajouter uniquement les profils/capabilities Helius réellement nécessaires au Worker live après revalidation des surfaces/tier courants ; réutiliser exclusivement `KSP_SECRET_HELIUS_API_KEY` via Config et la surface `transactionSubscribe` déjà Transport-owned, sans SDK provider ni second client parallèle.
|
||||
- [X] **TODO réseau** — identité KSP canonique fixée à `mainnet` dans Config/Store/Transport/tests ; `mainnet-beta` reste uniquement un alias legacy/externe lorsque la frontière provider l'exige. Les données N1 RAW antérieures restent non autoritaires pendant cette phase et aucune compatibilité de base de test n'impose l'ancien libellé.
|
||||
- [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-*`.
|
||||
|
||||
36
deltas/0.3.9/pre.009.md
Normal file
36
deltas/0.3.9/pre.009.md
Normal file
@@ -0,0 +1,36 @@
|
||||
<!-- file: deltas/0.3.9/pre.009.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.3.9-pre.009 — préparation de publication
|
||||
|
||||
## Objet
|
||||
|
||||
Préparer la publication stable de `0.3.9` après fermeture technique `pre.007-fix.002` et réconciliation documentaire `pre.008`, sans aucun rattrapage fonctionnel ou documentaire hors couloir de publication.
|
||||
|
||||
## Version
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.9-pre.9
|
||||
```
|
||||
|
||||
## Modifications
|
||||
|
||||
- `prompts/029-V0_3_10_START_PROMPT.md` : contrat opératoire autonome pour `0.3.10`, centré sur `ksp-raw-transaction-lib` puis `ksp-worker-raw-transaction-ingest-lib` live multi-source, avec `pre.001` audit/sizing obligatoire avant codage lourd ;
|
||||
- `CHANGELOG.md` : synthèse finale de `0.3.9`, Worker API, audit RAW, séparation Worker/Backfill, canonicalisation `mainnet`, upgrades `jsonschema`/Yellowstone et gates opérateur ;
|
||||
- `ROADMAP.md` : `0.3.9` fermé, handoff `0.3.10` aligné sur la lower-layer RAW commune et le rôle strictement live du Worker, TODO audit RAW/réseau clôturés ;
|
||||
- `Cargo.toml` : synchronisation mécanique de prerelease vers `0.3.9-pre.9`.
|
||||
|
||||
## Hors périmètre
|
||||
|
||||
Aucun README, USAGE, architecture, plan, validation, code Rust/TypeScript, test, schema, Config, endpoint, dépendance, runtime ou backend n'est modifié dans cette tranche.
|
||||
|
||||
## Validation attendue
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Si ce gate est vert, la candidate est prête pour `rel.001`, qui doit rester une publication mécanique stable sans rattrapage.
|
||||
839
prompts/029-V0_3_10_START_PROMPT.md
Normal file
839
prompts/029-V0_3_10_START_PROMPT.md
Normal file
@@ -0,0 +1,839 @@
|
||||
<!-- file: prompts/029-V0_3_10_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Prompt de démarrage `0.3.10` — normalisation RAW commune + Worker `RawTransaction` live multi-source
|
||||
|
||||
## 1. Identité de la release et base exacte
|
||||
|
||||
Ouvrir **uniquement** `0.3.10` depuis la release stable/taggée :
|
||||
|
||||
```text
|
||||
v0.3.9
|
||||
```
|
||||
|
||||
La base de travail fournie par l'opérateur est autoritaire sur les souvenirs de session, snippets, anciens deltas ou copies intermédiaires. Avant toute modification, vérifier qu'elle correspond bien à `v0.3.9` et lire les règles/documents obligatoires listés ci-dessous.
|
||||
|
||||
La mission de `0.3.10` est double mais cohérente :
|
||||
|
||||
```text
|
||||
1. matérialiser la lower-layer commune ksp-raw-transaction-lib
|
||||
2. introduire ksp-worker-raw-transaction-ingest-lib comme worker live multi-source V1
|
||||
```
|
||||
|
||||
Ces deux crates servent le même cœur durable `Store / RawTransaction`, mais **ne créent aucune relation fonctionnelle entre Job Backfill et Worker Ingest**.
|
||||
|
||||
## 2. Mission et résultat attendu
|
||||
|
||||
### 2.1 Centre du modèle
|
||||
|
||||
Le résultat durable recherché reste :
|
||||
|
||||
```text
|
||||
sources d'acquisition
|
||||
|
|
||||
v
|
||||
normalisation RAW v1
|
||||
|
|
||||
v
|
||||
ksp-store-lib
|
||||
|
|
||||
v
|
||||
RawTransaction + RawTransactionObservation
|
||||
```
|
||||
|
||||
`RawTransaction` est la vérité RAW persistée. Les observations/provenances décrivent les acquisitions multiples possibles d'une même transaction.
|
||||
|
||||
Identité canonique :
|
||||
|
||||
```text
|
||||
RawTransaction identity = (network, signature)
|
||||
network canonique Mainnet KSP = mainnet
|
||||
mainnet-beta = alias legacy/externe seulement
|
||||
```
|
||||
|
||||
Un même RAW peut être observé depuis plusieurs providers/protocoles. L'idempotence doit converger vers une seule entité canonique et plusieurs observations ; une divergence de contenu canonique reste un conflit explicite.
|
||||
|
||||
### 2.2 `ksp-raw-transaction-lib`
|
||||
|
||||
La canonicalisation RAW v1 aujourd'hui prouvée dans `ksp-job-backfill-lib` doit être extraite vers une lower-layer source-neutral commune au Job existant et au nouveau Worker, sans duplication et sans edge Job ↔ Worker.
|
||||
|
||||
Responsabilités cibles à confirmer pendant `pre.001` :
|
||||
|
||||
```text
|
||||
format id/version RAW
|
||||
matériau source-neutral de transaction complète
|
||||
canonical payload bytes
|
||||
content hash
|
||||
construction RawTransaction
|
||||
construction/projection RawTransactionObservation
|
||||
validation réseau/signature/slot/meta/version/index
|
||||
```
|
||||
|
||||
Responsabilités interdites :
|
||||
|
||||
```text
|
||||
runtime
|
||||
HTTP / WS / gRPC
|
||||
Config/env/secrets
|
||||
scheduler
|
||||
Job lifecycle/checkpoint/campagne
|
||||
Worker lifecycle/source loop
|
||||
backend Store physique
|
||||
```
|
||||
|
||||
La migration du Job existant doit préserver **byte-for-byte** les golden bytes/hash RAW v1 déjà validés. Aucun RAW v2 n'est justifié par cette extraction.
|
||||
|
||||
### 2.3 `ksp-worker-raw-transaction-ingest-lib`
|
||||
|
||||
Le Worker est un service continu. Son contrat fonctionnel cible est :
|
||||
|
||||
```text
|
||||
start
|
||||
-> ouvre les sources techniques activées par la composition
|
||||
-> acquiert à partir de son démarrage
|
||||
-> normalise/persiste continuellement
|
||||
-> publie snapshots/notifications concrètes indépendamment de leurs lecteurs
|
||||
-> répare uniquement ses propres pertes de continuité live
|
||||
stop
|
||||
-> arrêt coopératif/borné
|
||||
```
|
||||
|
||||
Le démarrage **ne reçoit pas** de requête métier historique telle que :
|
||||
|
||||
```text
|
||||
signature
|
||||
program_id
|
||||
address
|
||||
slot range
|
||||
before/after
|
||||
historical limit
|
||||
```
|
||||
|
||||
Ces entrées appartiennent au Job Backfill. Le Worker ne lance, n'appelle, n'attend ni ne supervise `ksp-job-backfill-lib`.
|
||||
|
||||
Le Worker peut néanmoins utiliser HTTP, replay Yellowstone ou une autre primitive lorsqu'elle sert **son acquisition live ou la réparation de son propre frontier live**. La frontière Worker/Job est définie par l'intention et le lifecycle, jamais par le protocole.
|
||||
|
||||
## 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.10
|
||||
```
|
||||
|
||||
Une commande non exécutée n'est jamais déclarée PASS.
|
||||
|
||||
### 3.2 Architecture acquisition autoritaire
|
||||
|
||||
Lire intégralement, dans cet ordre :
|
||||
|
||||
```text
|
||||
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.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/008-DATA_MATERIALIZATION_AND_STORE.md
|
||||
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
|
||||
```
|
||||
|
||||
`011-RAW_TRANSACTION_ACQUISITION.md` est le handoff fonctionnel principal de `0.3.9`. Ne pas revenir à la juxtaposition des anciens audits A/B et ne pas réduire sa matrice aux seules sources actuellement testables.
|
||||
|
||||
Décisions déjà fermées :
|
||||
|
||||
```text
|
||||
centre = Store / RawTransaction
|
||||
Job Backfill = historique paramétré, borné, terminable
|
||||
Worker Ingest = acquisition continue start/stop sans requête métier historique
|
||||
Job et Worker = producteurs indépendants
|
||||
HTTP / WS / gRPC / archive = capabilities, pas rôles
|
||||
Worker repair = seulement continuité de son run live
|
||||
support architectural != preuve live
|
||||
provider model = ouvert/capability-driven
|
||||
mainnet = identité KSP canonique
|
||||
mainnet-beta = alias legacy/externe
|
||||
canonicalisation RAW = lower-layer commune
|
||||
```
|
||||
|
||||
### 3.3 Worker API figée en `0.3.9`
|
||||
|
||||
Lire :
|
||||
|
||||
```text
|
||||
crates/ksp-worker-api/Cargo.toml
|
||||
crates/ksp-worker-api/README.md
|
||||
crates/ksp-worker-api/USAGE.md
|
||||
crates/ksp-worker-api/src/
|
||||
crates/ksp-worker-api/tests/
|
||||
|
||||
docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
|
||||
docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md
|
||||
```
|
||||
|
||||
Surface générique acquise :
|
||||
|
||||
```text
|
||||
WorkerId
|
||||
WorkerKindCode
|
||||
WorkerState
|
||||
WorkerHealth
|
||||
WorkerActivity
|
||||
WorkerLifecycle
|
||||
WorkerStopToken
|
||||
WorkerSnapshotSequence
|
||||
WorkerSnapshot
|
||||
WorkerSnapshotFuture
|
||||
WorkerSnapshotSource
|
||||
```
|
||||
|
||||
`ksp-worker-api` est **runtime-neutral**. Il ne fournit pas de `start()/stop()` universel et ne doit pas être élargi pour les besoins Solana du premier worker concret sauf défaut réellement générique démontré.
|
||||
|
||||
### 3.4 Backfill et canonicalisation RAW v1 existante
|
||||
|
||||
Lire intégralement :
|
||||
|
||||
```text
|
||||
crates/ksp-job-backfill-lib/Cargo.toml
|
||||
crates/ksp-job-backfill-lib/README.md
|
||||
crates/ksp-job-backfill-lib/USAGE.md
|
||||
crates/ksp-job-backfill-lib/src/conversion.rs
|
||||
crates/ksp-job-backfill-lib/src/
|
||||
crates/ksp-job-backfill-lib/unit_tests/
|
||||
crates/ksp-job-backfill-lib/tests/
|
||||
|
||||
docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md
|
||||
docs/validation/023-V0_3_6_JOB_API_BACKFILL.md
|
||||
```
|
||||
|
||||
Inventorier avant extraction :
|
||||
|
||||
```text
|
||||
RAW_TRANSACTION_FORMAT_ID/version
|
||||
canonical bytes exacts
|
||||
digest/hash exact
|
||||
mapping getTransaction -> RawTransaction
|
||||
mapping provenance/observation
|
||||
golden vectors
|
||||
network/signature/slot/block_time guards
|
||||
error codes/Debug/redaction
|
||||
```
|
||||
|
||||
Le changement autorisé dans Backfill en `0.3.10` est la **migration vers la lower-layer commune** avec comportement inchangé. L'ajout de nouvelles stratégies historiques reste `0.3.12`.
|
||||
|
||||
### 3.5 Store
|
||||
|
||||
Lire :
|
||||
|
||||
```text
|
||||
crates/ksp-store-api/README.md
|
||||
crates/ksp-store-api/USAGE.md
|
||||
crates/ksp-store-api/src/
|
||||
crates/ksp-store-lib/README.md
|
||||
crates/ksp-store-lib/USAGE.md
|
||||
crates/ksp-store-lib/src/
|
||||
```
|
||||
|
||||
Préserver :
|
||||
|
||||
```text
|
||||
RawTransaction identity = network + signature
|
||||
RawTransactionObservation séparée de l'entité canonique
|
||||
persistance acquisition atomique/idempotente
|
||||
conflit de contenu explicite
|
||||
rétention/tombstone existants
|
||||
Store façade uniquement pour les consumers ordinaires
|
||||
aucun backend PostgreSQL direct dans Worker/Common RAW
|
||||
```
|
||||
|
||||
La lower-layer commune doit utiliser la façade/les reexports Store approuvés par l'architecture actuelle et ne doit pas introduire arbitrairement une nouvelle dépendance directe à `ksp-store-api` sans audit de frontière.
|
||||
|
||||
### 3.6 Transport
|
||||
|
||||
Lire les surfaces actuelles de `ksp-onchain-transport-lib`, notamment :
|
||||
|
||||
```text
|
||||
HTTP observed getTransaction
|
||||
getBlock / getBlocks / getBlocksWithLimit
|
||||
WS logsSubscribe
|
||||
WS signatureSubscribe
|
||||
WS blockSubscribe
|
||||
Helius transactionSubscribe
|
||||
Yellowstone transactions
|
||||
Yellowstone transaction_status
|
||||
Yellowstone blocks
|
||||
Yellowstone blocks_meta / slots
|
||||
Yellowstone from_slot / replay info / reconnect snapshots
|
||||
```
|
||||
|
||||
Réauditer explicitement les gaps `011` :
|
||||
|
||||
```text
|
||||
TR-B = get_block_observed
|
||||
TR-C = projection source-neutral des transactions full WS/Yellowstone
|
||||
TR-D = métadonnées sûres d'acquisition live pour observation uniforme
|
||||
TR-E = exploitation du from_slot/replay existant sans second moteur Yellowstone
|
||||
TR-F = adapters EARLY seulement lorsque le protocole est réellement implémenté
|
||||
```
|
||||
|
||||
Ne pas ajouter un second client Yellowstone ou Helius si la surface existante suffit.
|
||||
|
||||
### 3.7 Config et composition
|
||||
|
||||
Lire :
|
||||
|
||||
```text
|
||||
crates/ksp-config-lib/README.md
|
||||
crates/ksp-config-lib/USAGE.md
|
||||
crates/ksp-config-lib/src/transport.rs
|
||||
config/std.transport.json
|
||||
config/schemas/std.transport.schema.json
|
||||
config/examples/std.transport.example.json
|
||||
.env.example
|
||||
```
|
||||
|
||||
Config reste propriétaire des endpoints, credentials et secrets. Le Worker ne lit jamais directement l'environnement.
|
||||
|
||||
Cible conceptuelle à auditer :
|
||||
|
||||
```text
|
||||
source id
|
||||
network
|
||||
endpoint ref
|
||||
capabilities
|
||||
priority
|
||||
enabled
|
||||
settings techniques
|
||||
```
|
||||
|
||||
Une composition peut activer plusieurs sources simultanément. Les paramètres de campagne historique ne doivent pas entrer dans cette configuration Worker.
|
||||
|
||||
Le graphe cible actuel de `009` ne suppose pas une dépendance directe Worker -> Config : la composition/adapter supérieur résout la Config en settings source-neutral. Toute divergence doit être argumentée pendant `pre.001` avant codage.
|
||||
|
||||
## 4. Sources externes à réauditer pour fraîcheur
|
||||
|
||||
La matrice `0.3.9` est une photographie documentée au 4 septembre 2026. `0.3.10-pre.001` doit revalider uniquement ce qui peut avoir changé et qui affecte l'implémentation réelle :
|
||||
|
||||
```text
|
||||
Solana JSON-RPC / PubSub actuels
|
||||
Yellowstone gRPC upstream/proto actuel
|
||||
Helius standard WSS / transactionSubscribe / LaserStream
|
||||
PublicNode Yellowstone
|
||||
OrbitFlare Yellowstone
|
||||
providers/tier réellement utilisés dans les smokes
|
||||
QuickNode / Alchemy / Shyft / Triton / dRPC lorsque leur capability influence le modèle
|
||||
DoubleZero/feeds EARLY seulement si une intégration réelle est envisagée
|
||||
```
|
||||
|
||||
Utiliser les sources primaires. Distinguer systématiquement :
|
||||
|
||||
```text
|
||||
capability protocolaire
|
||||
capability documentée provider
|
||||
support implémenté KSP
|
||||
preuve live KSP
|
||||
```
|
||||
|
||||
Une branche connue mais inaccessible sur le compte opérateur reste admissible et doit être testable par fixtures/mocks lorsque cela a du sens.
|
||||
|
||||
Le workspace stable `v0.3.9` utilise notamment `yellowstone-grpc-proto ^12.7`; vérifier la version réellement courante au début de la tranche avant toute nouvelle dépendance ou adaptation protobuf. Ne pas confondre mise à jour de dépendance et objectif fonctionnel de la release.
|
||||
|
||||
## 5. État validé à préserver
|
||||
|
||||
`v0.3.9` ferme notamment :
|
||||
|
||||
```text
|
||||
Worker API Core-only/générique
|
||||
RawTransaction Store backend-neutral + PostgreSQL
|
||||
RawTransactionObservation/provenance
|
||||
Backfill HTTP historique existant
|
||||
Transport HTTP/WS/Helius/Yellowstone existant
|
||||
Config Transport V3 et profils publics actuels
|
||||
mainnet canonique
|
||||
jsonschema ^0.53
|
||||
yellowstone-grpc-proto ^12.7
|
||||
```
|
||||
|
||||
Les gates `0.3.9` ont validé le workspace complet `--all-targets --all-features`, les 385 tests unitaires Transport, 43 canaries de release Transport, Worker API complet et les arbres Cargo. Ne pas affaiblir ces canaris pour faire passer le nouveau code.
|
||||
|
||||
## 6. Architecture cible et dépendances
|
||||
|
||||
### 6.1 Lower-layer commune
|
||||
|
||||
Cible à confirmer :
|
||||
|
||||
```text
|
||||
ksp-raw-transaction-lib
|
||||
-> ksp-core-lib # seulement si nécessaire directement
|
||||
-> ksp-store-lib # façade ; default-features=false
|
||||
-> serde_json / sha2 # seulement si RAW v1 les requiert encore
|
||||
```
|
||||
|
||||
Pas de Transport, Config, Job API, Worker API, runtime async ou backend physique.
|
||||
|
||||
### 6.2 Worker concret
|
||||
|
||||
Cible à confirmer :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-transaction-ingest-lib
|
||||
-> ksp-worker-api
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-raw-transaction-lib
|
||||
-> ksp-store-lib # façade ; default-features=false
|
||||
-> ksp-logging-lib
|
||||
```
|
||||
|
||||
`ksp-interface-lib` n'est ajouté que si un fait passif réellement partagé apporte une valeur démontrée ; ne pas créer une dépendance par anticipation.
|
||||
|
||||
Interdits :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-transaction-ingest-lib -> ksp-job-api
|
||||
ksp-worker-raw-transaction-ingest-lib -> ksp-job-backfill-lib
|
||||
ksp-worker-raw-transaction-ingest-lib -> ksp-store-postgres-lib
|
||||
ksp-worker-raw-transaction-ingest-lib -> provider SDK
|
||||
lower layer -> Worker/Job
|
||||
```
|
||||
|
||||
### 6.3 Job existant
|
||||
|
||||
Après extraction :
|
||||
|
||||
```text
|
||||
ksp-job-backfill-lib
|
||||
-> ksp-raw-transaction-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-lib
|
||||
-> ses dépendances Job/runtime existantes
|
||||
```
|
||||
|
||||
Le Job conserve seul scopes, limites, campagnes, frontier historique, checkpoint et reprise.
|
||||
|
||||
## 7. Sources/capabilities Worker V1
|
||||
|
||||
Le modèle V1 doit pouvoir représenter au minimum les voies admises par `011`, même lorsque certaines ne peuvent pas être prouvées live immédiatement :
|
||||
|
||||
```text
|
||||
Yellowstone transactions full
|
||||
Yellowstone blocks full
|
||||
Yellowstone transaction_status + hydration
|
||||
WS logsSubscribe + HTTP getTransaction
|
||||
WS blockSubscribe full
|
||||
Helius transactionSubscribe full
|
||||
HTTP live block polling
|
||||
HTTP transaction hydration
|
||||
Yellowstone replay/from_slot pour continuité du run
|
||||
source EARLY via adapter extensible
|
||||
```
|
||||
|
||||
Ne pas coder la sélection sous forme d'un enum fermé de providers. La composition se fait par capabilities et settings techniques.
|
||||
|
||||
Une source peut être :
|
||||
|
||||
```text
|
||||
alternative
|
||||
complémentaire
|
||||
redondante
|
||||
spécialisée
|
||||
```
|
||||
|
||||
Plusieurs sources peuvent être actives simultanément.
|
||||
|
||||
## 8. Continuité, déduplication et persistence
|
||||
|
||||
Le Worker doit distinguer :
|
||||
|
||||
```text
|
||||
reconnect physique
|
||||
resubscribe
|
||||
replay adressable
|
||||
hydration
|
||||
scan blocs live
|
||||
repair du frontier live
|
||||
```
|
||||
|
||||
Un reconnect WS ne vaut pas replay.
|
||||
|
||||
Le Worker ne cherche pas l'historique arbitraire antérieur à son run. Lorsqu'un gap apparaît pendant son activité, il peut réparer la zone perdue jusqu'à son frontier live avec les capabilities disponibles.
|
||||
|
||||
Ordre conceptuel de repair, à auditer/sizer :
|
||||
|
||||
```text
|
||||
replay natif qualifié
|
||||
source live redondante
|
||||
scan HTTP blocs
|
||||
hydration signatures découvertes
|
||||
fail/degraded explicite si la continuité ne peut pas être prouvée
|
||||
```
|
||||
|
||||
Ne jamais déclarer lossless sans preuve suffisante.
|
||||
|
||||
La persistence doit utiliser l'idempotence Store existante. Les duplicates multi-source sont attendus ; une observation supplémentaire n'est pas une seconde entité RAW.
|
||||
|
||||
## 9. Notifications et supervision
|
||||
|
||||
Le Worker concret doit exposer un état observable compatible avec `ksp-worker-api` :
|
||||
|
||||
```text
|
||||
identity/kind
|
||||
state
|
||||
health
|
||||
activity
|
||||
sequence
|
||||
snapshot latest-value
|
||||
stop request partagé
|
||||
```
|
||||
|
||||
Les notifications/snapshots sont produits indépendamment de la présence de lecteurs. Un consumer lent ou absent ne doit pas devenir propriétaire du lifecycle du Worker.
|
||||
|
||||
`pre.001` doit décider le minimum de projection concrète nécessaire pour rates/source health/gap state/compteurs sans élargir `ksp-worker-api` ni inventer un event bus global.
|
||||
|
||||
## 10. Hors périmètre `0.3.10`
|
||||
|
||||
Ne pas implémenter :
|
||||
|
||||
```text
|
||||
ksp-app-raw-transaction-ingest-desk # 0.3.11
|
||||
nouvelles stratégies Job Backfill # 0.3.12
|
||||
campagnes historiques dans le Worker
|
||||
checkpoint Backfill dans le Worker
|
||||
Program decode / DEX / materialization
|
||||
RawAccountState ingest worker
|
||||
backend PostgreSQL direct dans le Worker
|
||||
provider SDK
|
||||
control plane global
|
||||
nouveau format RAW v2 sans nécessité démontrée
|
||||
```
|
||||
|
||||
Les adaptations du Job autorisées sont limitées à la migration vers la canonicalisation commune et aux tests de non-régression correspondants.
|
||||
|
||||
## 11. Première mission `pre.001` — audit, brainstorming et sizing
|
||||
|
||||
**Ne pas commencer l'implémentation lourde du Worker en arrivant dans la session.**
|
||||
|
||||
`pre.001` doit d'abord produire un plan détaillé de `0.3.10` à partir de la base réelle.
|
||||
|
||||
### 11.1 Vérification de base
|
||||
|
||||
- vérifier la base/tag/archive `v0.3.9` ;
|
||||
- lire les règles et sources obligatoires ;
|
||||
- inventorier les crates/manifests/features réellement présents ;
|
||||
- exécuter les audits statiques disponibles ;
|
||||
- ne déclarer aucun gate Cargo PASS sans l'avoir réellement exécuté.
|
||||
|
||||
### 11.2 Audit de l'extraction RAW commune
|
||||
|
||||
Comparer précisément le code actuel Backfill avec la cible `ksp-raw-transaction-lib` :
|
||||
|
||||
```text
|
||||
items à déplacer
|
||||
items à laisser Job-owned
|
||||
dépendances exactes nécessaires
|
||||
golden bytes/hash à préserver
|
||||
public API minimale de la common crate
|
||||
erreurs/validation/redaction
|
||||
absence de cycle de dépendances
|
||||
```
|
||||
|
||||
Décider le découpage avant de déplacer du code.
|
||||
|
||||
### 11.3 Audit Transport/Config pour chaque capability live
|
||||
|
||||
Construire une matrice implementation-ready avec au moins :
|
||||
|
||||
```text
|
||||
capability
|
||||
méthode/protocole
|
||||
surface KSP existante
|
||||
gap exact
|
||||
donnée complète ou hydration requise
|
||||
provenance disponible
|
||||
continuity/replay semantics
|
||||
network/provider testable aujourd'hui
|
||||
adaptation Transport nécessaire
|
||||
adaptation Config nécessaire
|
||||
fixture test
|
||||
live smoke possible
|
||||
```
|
||||
|
||||
Réutiliser les IDs `TR-B` à `TR-F` de `011` ou les superséder explicitement si l'audit montre une meilleure découpe.
|
||||
|
||||
### 11.4 Audit du runtime Worker
|
||||
|
||||
Décider avant codage :
|
||||
|
||||
```text
|
||||
ownership du runtime/task
|
||||
start/stop concret
|
||||
source supervisor
|
||||
multi-source concurrency
|
||||
bounded channels/backpressure
|
||||
source health
|
||||
latest-value status
|
||||
admission/dedup/persistence flow
|
||||
gap detection + repair
|
||||
shutdown order
|
||||
terminal fault policy
|
||||
```
|
||||
|
||||
Aucun paramètre métier historique ne doit apparaître dans le contrat start.
|
||||
|
||||
### 11.5 Audit des preuves
|
||||
|
||||
Séparer :
|
||||
|
||||
```text
|
||||
unit/fixture deterministic
|
||||
integration local
|
||||
provider live gratuit
|
||||
provider live bloqué par tier
|
||||
preuve de replay
|
||||
preuve de continuity repair
|
||||
Store persistence proof
|
||||
```
|
||||
|
||||
Les tests live restent opt-in/ignored si secrets, endpoint externe, tier ou coût sont requis.
|
||||
|
||||
### 11.6 Sizing et planification
|
||||
|
||||
Produire un plan dédié `0.3.10` et une validation dédiée avant implémentation lourde.
|
||||
|
||||
Chaque prerelease intermédiaire visée à plus d'environ 15-20 minutes de travail effectif doit être scindée. Réserver explicitement les couloirs finaux :
|
||||
|
||||
```text
|
||||
gate technique/live
|
||||
réconciliation documentaire
|
||||
préparation de publication
|
||||
rel.001
|
||||
```
|
||||
|
||||
### 11.7 Critères de sortie de `pre.001`
|
||||
|
||||
Le gate `pre.001` est fermé seulement si les points suivants sont explicites :
|
||||
|
||||
```text
|
||||
boundary exacte ksp-raw-transaction-lib
|
||||
migration Backfill sans changement RAW v1
|
||||
surface publique minimale du Worker concret
|
||||
runtime/source supervision décidés
|
||||
capability matrix Worker implementation-ready
|
||||
TR-B..TR-F réévalués
|
||||
Config/source settings décidés sans secret leak
|
||||
continuité/gap repair bornés
|
||||
notification/snapshot contract concret
|
||||
multi-source dedup/provenance/persistence décidés
|
||||
provider/access/proof matrix revalidée
|
||||
liste de tests/smokes
|
||||
dependency graph cible
|
||||
prévision souple détaillée et dimensionnée
|
||||
aucune implémentation lourde commencée avant cohérence du plan
|
||||
```
|
||||
|
||||
## 12. Prévision souple initiale des prereleases
|
||||
|
||||
Cette prévision est un point de départ à recalibrer par `pre.001`, pas un calendrier rigide.
|
||||
|
||||
### `pre.001` — audit/sizing/plan
|
||||
|
||||
Lecture complète, audit lower-layer/Transport/Config/Worker runtime, fraîcheur providers, dependency graph, threat model, tests et plan détaillé.
|
||||
|
||||
### `pre.002` — `ksp-raw-transaction-lib` foundation
|
||||
|
||||
Créer la common crate, déplacer la canonicalisation RAW v1 sans changer les golden bytes/hash, migrer Backfill vers elle et verrouiller les frontières de dépendances.
|
||||
|
||||
### `pre.003` — Worker foundation/runtime
|
||||
|
||||
Créer `ksp-worker-raw-transaction-ingest-lib`, lifecycle concret, start/stop, source supervision abstraite, snapshots/latest-value, persistence pipeline minimal et shutdown borné sans source live complexe.
|
||||
|
||||
### `pre.004` — Transport/Common acquisition gaps P0
|
||||
|
||||
Matérialiser les adaptations source-neutral indispensables : `get_block_observed`, transaction material/provenance commune et autres gaps réellement confirmés par `pre.001`.
|
||||
|
||||
### `pre.005` — Yellowstone live
|
||||
|
||||
Brancher transactions/blocks/status+hydration, multi-source admission, continuity metadata et replay `from_slot` uniquement pour le frontier live du Worker.
|
||||
|
||||
### `pre.006` — WS/HTTP live
|
||||
|
||||
Brancher logs+hydration, blockSubscribe, HTTP live block polling/hydration et Helius `transactionSubscribe` existant selon Config/capabilities.
|
||||
|
||||
### `pre.007` — multi-source hardening
|
||||
|
||||
Déduplication, observations multiples, backpressure, source health, failure isolation, continuity/gap repair et adversarial tests.
|
||||
|
||||
### `pre.008` — providers/config/smokes accessibles
|
||||
|
||||
Compléter les profils/capabilities réellement nécessaires, exécuter les smokes gratuits disponibles Mainnet/Devnet/Testnet et conserver les branches payantes derrière fixtures/opt-in.
|
||||
|
||||
### `pre.009` — extensions EARLY réellement accessibles ou tranche de consolidation
|
||||
|
||||
N'implémenter une source EARLY vendor-specific que si son protocole, son accès et son rôle sont suffisamment prouvés. Sinon utiliser cette tranche pour consolidation/hardening plutôt que créer un faux support.
|
||||
|
||||
### `pre.010` — gate technique/live final
|
||||
|
||||
Workspace complet, graphes de dépendances, tests live pertinents, continuité/recovery et preuves Store.
|
||||
|
||||
### `pre.011` — réconciliation documentaire finale
|
||||
|
||||
README/USAGE/architecture/plan/validation uniquement.
|
||||
|
||||
### `pre.012` — préparation de publication
|
||||
|
||||
Prompt `0.3.11`, CHANGELOG, ROADMAP uniquement, plus fichiers mécaniques de version/delta.
|
||||
|
||||
### `rel.001` — publication mécanique stable
|
||||
|
||||
Publication `v0.3.10` sans rattrapage fonctionnel ou documentaire.
|
||||
|
||||
`pre.001` peut scinder, fusionner ou insérer des tranches/fixes selon le résultat réel de l'audit. Il doit préserver l'ordre des responsabilités de fermeture.
|
||||
|
||||
## 13. Sécurité et hardening spécifiques
|
||||
|
||||
Préserver au minimum :
|
||||
|
||||
```text
|
||||
aucun secret/URL/header/token dans Debug ou erreurs publiques
|
||||
aucun raw transaction payload dans tracing par défaut
|
||||
bornes explicites sur queues/buffers/filter sets
|
||||
pas de panic/unwrap/expect/unsafe
|
||||
pas de provider body/message copié dans ErrorContext
|
||||
aucune rétention d'un endpoint secret dans snapshot
|
||||
source failure isolée lorsque possible
|
||||
shutdown/reconnect bornés
|
||||
conflit de contenu canonique terminal/explicite selon policy décidée
|
||||
no-loss claim interdit sans preuve
|
||||
```
|
||||
|
||||
Les diagnostics Worker doivent être utiles sans exposer signatures/payloads lorsque leur exposition n'est pas nécessaire.
|
||||
|
||||
## 14. Validation Rust et dépendances
|
||||
|
||||
Pendant les tranches 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/0.3.10
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Puis tests ciblés des crates touchées.
|
||||
|
||||
Pour les gates techniques :
|
||||
|
||||
```bash
|
||||
cargo test --workspace --all-targets --all-features
|
||||
cargo tree -p ksp-raw-transaction-lib --edges normal
|
||||
cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal
|
||||
cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features
|
||||
cargo tree --duplicates
|
||||
```
|
||||
|
||||
Adapter les graphes si le plan `pre.001` modifie réellement les noms/edges, sans supprimer le contrôle de dépendances.
|
||||
|
||||
Les smokes live doivent être explicitement opt-in lorsqu'ils nécessitent réseau externe, secrets ou accès payant.
|
||||
|
||||
## 15. Versionnement, deltas et publication
|
||||
|
||||
- chaque nouvelle prerelease non-fix synchronise `workspace.package.version` selon `VER-ID-009` ;
|
||||
- `0.3.10-pre.001` correspond à Cargo `0.3.10-pre.1` ;
|
||||
- les correctifs utilisent la forme Cargo `0.3.10-pre.N.fix.M` ;
|
||||
- chaque livraison a son delta minimal sous `deltas/0.3.10/` ;
|
||||
- les archives d'échange suivent `VER-ARCHIVE-*` ;
|
||||
- aucun lockfile/cache/secret/build output dans les deltas ;
|
||||
- chaque delta est commité selon les règles Git KSP ;
|
||||
- seul le stable final reçoit le tag `v0.3.10`.
|
||||
|
||||
Ne jamais réécrire un delta déjà publié pour masquer un défaut ; ouvrir un fix ou une tranche appropriée.
|
||||
|
||||
## 16. Critères de clôture de `0.3.10`
|
||||
|
||||
La release peut fermer lorsque :
|
||||
|
||||
```text
|
||||
ksp-raw-transaction-lib possède une canonicalisation RAW v1 unique et prouvée
|
||||
Backfill utilise cette common crate sans changement fonctionnel de campagne
|
||||
Worker live démarre/s'arrête sans paramètres métier historiques
|
||||
plusieurs sources peuvent être actives simultanément
|
||||
les voies P0 Yellowstone + WS/HTTP admises sont représentées/implémentées selon plan
|
||||
les adaptations Transport/Config sont capability-driven et minimales
|
||||
RawTransaction + observations convergent correctement dans Store
|
||||
multi-source duplicates et conflits sont traités explicitement
|
||||
repair ne dépasse pas la continuité du run live
|
||||
snapshots/notifications sont receiver-independent et sûrs
|
||||
les branches non testables live restent testées déterministiquement quand possible
|
||||
aucun edge Job <-> Worker
|
||||
aucun backend physique/provider SDK dans le Worker
|
||||
gate technique/live final vert
|
||||
réconciliation documentaire séparée
|
||||
prompt 0.3.11/CHANGELOG/ROADMAP préparés séparément
|
||||
```
|
||||
|
||||
## 17. Release suivante envisagée
|
||||
|
||||
`0.3.11` introduira `ksp-app-raw-transaction-ingest-desk` pour sélectionner et superviser une ou plusieurs sources/méthodes offertes par le Worker `0.3.10`, sans recopier discovery, hydration, dedup, persistence ou recovery.
|
||||
|
||||
`0.3.12` reviendra ensuite sur `ksp-job-backfill-lib`/Desk pour les stratégies historiques multi-source/multi-protocole. Ne pas anticiper ce travail dans `0.3.10`.
|
||||
|
||||
## 18. Instruction d'ouverture
|
||||
|
||||
Au début de la prochaine session :
|
||||
|
||||
1. vérifier que la base fournie correspond exactement à `v0.3.9` ;
|
||||
2. lire les règles, `009`, `011`, Worker API, Backfill conversion, Store, Transport et Config dans l'ordre prescrit ;
|
||||
3. réauditer les dépendances/provider capabilities dont la fraîcheur affecte réellement l'implémentation ;
|
||||
4. produire **`pre.001` comme audit/sizing/plan**, avec dependency graph, capability matrix, threat model et stratégie de tests ;
|
||||
5. **ne pas commencer l'implémentation lourde de `ksp-raw-transaction-lib` ou du Worker avant fermeture cohérente de ce gate**.
|
||||
|
||||
L'objectif n'est pas de coder le chemin le plus facile avec les comptes gratuits actuels. L'objectif est de construire un socle live multi-source maximal, capability-driven et extensible, tout en distinguant clairement support architectural, support implémenté et preuve live disponible.
|
||||
Reference in New Issue
Block a user