34 KiB
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 :
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 :
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 :
0.3.9
Première livraison attendue :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
Pour tout Markdown touché :
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.9
Une commande non exécutée n'est jamais déclarée PASS.
3.2 Architecture acquisition / workers / jobs
Lire intégralement :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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
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é :
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
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 :
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 :
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 :
crates/ksp-worker-api/
Cargo.toml
src/
tests/
README.md
USAGE.md
docs/plans/<nouveau plan 0.3.9>
docs/validation/<nouvelle validation 0.3.9>
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 :
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 :
ksp-worker-api -> ksp-core-lib uniquement
Ne pas ajouter sans preuve :
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 :
bornes explicites pour identities/codes
Debug sûr et borné
aucun payload/secret arbitraire dans errors/snapshots
aucun Box<dyn Error> 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 treeactuel deksp-job-apiet dépendances voisines.
11.2 Auditer ksp-job-api
Construire une matrice :
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 :
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 :
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 :
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
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 :
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 :
"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 :
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 :
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 :
// À 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 à :
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 :
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 :
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 :
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 :
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 :
ksp-doc-<delivery-id>.zip
ksp-general-<delivery-id>.zip
Ne jamais livrer une copie complète du dépôt comme « delta ».
Tags :
seul le stable final v0.3.9 est taggé selon le workflow courant
15. Validation opérateur
15.1 Baseline / chaque tranche Rust
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 :
cargo test -p ksp-worker-api
et, selon les changements :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
- vérifier la base stable exacte
v0.3.8etdeltas/0.3.8/rel.001.md; - lire les règles et architectures obligatoires dans l'ordre du présent prompt ;
- auditer
ksp-job-apicomme référence de propriétés génériques sans supposer une dépendance Worker -> Job ; - inventorier la surface exacte attendue de
ksp-worker-api, les risques et les dépendances ; - produire
pre.001avec brainstorming, sizing, plan/tests/gates et prévision souple recalibrée ; - 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 ; - 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 vers0.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.