khadhroony-solana-project/docs/architecture/004-COMPONENT_INVENTORY.md

Inventaire initial des composants KSP

Objet

Ce document constitue le premier inventaire architectural de 0.0.3-pre.002.

Il répond principalement à la question : quel composant possède quelle responsabilité ?

Le premier inventaire a été produit en 0.0.3-pre.002. pre.003 l'a corrigé à partir du graphe, puis pre.004 a détaillé Wire/Program dans 006-WIRE_AND_PROGRAM.md, pre.005 Execution/Policy, pre.006 les niveaux durables/Materialization/Store, pre.007 l'exploitation workers/jobs/pipelines, puis pre.008 Apps/Services/Scenarios/Control dans 010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md. Les détails de types Rust restent révisables avec les premières implémentations.

Statuts

• Retenu — composant ou responsabilité considérée nécessaire dans la trajectoire actuelle ;
• Candidat fort — composant très probable mais dont la frontière exacte doit encore être validée ;
• Futur retenu — responsabilité acquise mais implémentation différée ;
• À la demande — ne doit être créé que lorsqu'un premier besoin concret le justifie ;
• Non retenu actuellement — idée volontairement non créée ; elle peut être réévaluée si l'usage réel change.

Inventaire synthétique

Domaine	Composant	Nature	Niveau provisoire	Statut	Première série envisagée	Responsabilité principale
Core	ksp-core-lib	lib	N1	Retenu	0.1.x	Error commun, Program IDs, primitives/contrats réellement transversaux
Configuration	ksp-config-lib	lib	N1	Retenu	0.1.x	documents de configuration, profils, résolution, modifications autorisées
Logging	ksp-logging-lib	lib	N1	Retenu	0.1.x	façade unique tracing/appender/subscriber, initialisation et logging structuré KSP ; peut dépendre de core pour Error/Result
Wire Solana	ksp-interface-lib	lib	N1	Retenu	0.2.x	façade wire on-chain, réexports contrôlés et réimplémentations compatibles
Program API	ksp-program-api	API	N2 contrat	Retenu	0.2.x	contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry
Program impl.	ksp-program-lib	lib	N2	Retenu	0.2.x+	decoders et ProgramExecutionPreparer officiels organisés par domaine/programme/capacité
Program extension	ksp-program-<name>-lib	lib externe/optionnelle	N2	À la demande	dès besoin	implémentation externe de ksp-program-api pour un Program ID non encore intégré officiellement
Execution policy	ksp-execution-policy-api	API	N3 contrat	Retenu	premier besoin d'exécution réelle	policy obligatoire, multi-checkpoints, décision/requirements sans wallet/réseau/UI
Execution orchestration	ksp-execution-lib	lib	N3	Retenu	premier besoin d'exécution réelle	consomme PreparedProgramExecution; orchestre policy/simulation/signature/submission/confirmation/retry sans dépendre de ksp-program-lib ou du store
Transport on-chain	ksp-onchain-transport-lib	lib	N2	Retenu	0.2.x	RPC/WS/providers et modèles de transport homogènes, sans dépendance store
Transport off-chain	ksp-offchain-transport-lib	lib	N2	Retenu, implémentation différable	premier besoin réel	accès metadata, prix, quotes, routage et autres ressources hors blockchain
Wallet	ksp-wallet-lib	lib	N2	Retenu	0.2.x	format wallet KSP, lecture/protection/import/export, pubkey, secret/signature
Materializer API	ksp-materializer-api	API	N3 contrat	Retenu	0.3.x	contrats publics/extensibles de matérialisation
Materializer impl.	ksp-materializer-lib	lib	N3	Retenu	0.3.x+	materializers officiels KSP
Store API	ksp-store-api	API	N3 contrat	Retenu	0.3.x	contrats backend-agnostic, modèles persistants et notifications de données persistées
Store impl.	ksp-store-lib	lib	N3	Retenu	0.3.x	PostgreSQL de référence, migrations, repositories, queries, backlog/replay et notification backend
Worker lifecycle	ksp-worker-api	API	N3 contrat	Retenu	0.3.x	lifecycle commun des services continus
Worker control	ksp-worker-control-lib	lib	N3	Retenu	0.3.x+	gouvernance réutilisable de services workers autonomes pour apps spécialisées puis futurs managers/orchestrateurs
Live raw acquisition	ksp-worker-raw-retriever	worker	N4	Retenu	0.3.x	acquisition live/quasi-live -> raw persisté -> notification data
Raw -> Core	ksp-worker-core-processor	worker	N4	Futur retenu	0.6.x	transformer le raw persisté en Core canonique
Core -> generic mat.	ksp-worker-generic-materializer	worker	N4	Futur retenu	0.6.x	produire la matérialisation/journal générique depuis le Core
Domain projection	ksp-worker-domain-projector	worker	N4	Futur retenu, nom provisoire	0.6.x	matérialiser/classer/stocker les projections spécialisées par domaine
Job lifecycle	ksp-job-api	API	N3 contrat	Retenu	0.3.x	lifecycle/progression commun des travaux déclenchés et terminables
Historical backfill	ksp-job-backfill	job	N4	Retenu	0.3.x	acquisition historique avec pagination, progression, checkpoint/reprise
Core replay	ksp-job-replay-core	job	N4	Retenu	0.3.x/0.6.x	replay borné D1 -> D2 via le pipeline Core
Generic materialization replay	ksp-job-replay-generic-materialization	job	N4	Retenu	0.3.x/0.6.x	replay borné D2 -> D3 via le pipeline générique
Domain projection replay	ksp-job-replay-domain-projection	job	N4	Retenu	0.3.x/0.6.x	replay borné D3 -> D4 via le pipeline de projection
Other jobs	ksp-job-<role>	job	N4	À la demande	0.4.x+	metadata, quotes et autres travaux ponctuels/historiques
Scenarios	ksp-scenario-<domain>-lib	lib	N3	Retenu	0.4.x+	scénarios de validation spécialisés par domaine
Scenario common API	ksp-scenario-api	API	—	Non retenu actuellement	—	préférer une norme de scénario souple plutôt qu'un trait commun contraignant
Scenario demo apps	ksp-app-scenario-<domain>-<env>-desk-demo	app	N4	Retenu	0.4.x+	interface desktop appelant la crate scénario correspondante
Raw ingestion pipeline	ksp-pipeline-raw-ingestion-lib	lib	N3	Retenu	0.3.x	conversion/persistence transport model -> D1 partagée par worker live et backfill
Core processing pipeline	ksp-pipeline-core-processing-lib	lib	N3	Retenu	0.3.x/0.6.x	logique D1 -> D2 partagée par worker et replay, basée sur ksp-program-api
Generic materialization pipeline	ksp-pipeline-generic-materialization-lib	lib	N3	Retenu	0.3.x/0.6.x	logique D2 -> D3 partagée par worker et replay, basée sur ksp-materializer-api
Domain projection pipeline	ksp-pipeline-domain-projection-lib	lib	N3	Retenu	0.3.x/0.6.x	logique D3 -> D4 partagée par worker et replay, basée sur ksp-materializer-api
Trading Intelligence	noms à définir	API/libs/jobs	N3+	Futur retenu	0.7.x	statistiques, features, signaux, anomalies, backtests, ML
Trading operation/app	noms à définir	libs/apps	N3/N4	Futur retenu	après Trading Intelligence	politique/automatisation de trading et application monoposte
Solana explorer	noms à définir	libs/apps	N3/N4	Futur retenu	futur	exploration générale Solana
DEX explorer	noms à définir	libs/apps	N3/N4	Futur retenu	futur	exploration/analyse DEX

APIs séparées retenues

Les couples suivants ont une justification d'extensibilité suffisante :

ksp-program-api        -> ksp-program-lib
ksp-materializer-api   -> ksp-materializer-lib
ksp-store-api          -> ksp-store-lib

Les APIs lifecycle sont également séparées :

ksp-worker-api         -> workers continus
ksp-job-api            -> jobs terminables

Aucune API commune worker+job n'est prévue.

Execution policy et orchestration

La frontière détaillée est définie dans 007-EXECUTION_AND_POLICY.md.

Principes retenus :

PreparedProgramExecution
        |
        v
ksp-execution-lib
   |       |       |
 policy  wallet  onchain transport

• ksp-execution-lib dépend de ksp-program-api, pas de ksp-program-lib ;
• une policy est explicitement fournie pour toute exécution réelle ;
• la policy peut être évaluée à plusieurs checkpoints ;
• une policy décide/contraint mais n'exécute pas de réseau/signature/UI ;
• Program constraints, options caller et policy constraints restent trois sources distinctes ;
• wallet/signers et transport/provider sont fournis par la composition supérieure ;
• simulation/submission/status sont des primitives transport orchestrées par execution ;
• signature est une capacité wallet orchestrée par execution ;
• retry réseau identique et retry de lifecycle d'exécution restent distincts ;
• une approbation externe peut suspendre/reprendre l'exécution sans faire dépendre la policy de l'UI ;
• aucun accès Store depuis ksp-execution-lib.

ksp-logging-lib est consommé transversalement par les crates runtime qui doivent logger, sans imposer une dépendance aux crates *-api déclaratives ni à ksp-core-lib.

Transport on-chain

Aucune crate ksp-onchain-transport-api n'est prévue.

ksp-onchain-transport-lib peut contenir plusieurs familles hétérogènes :

• HTTP RPC ;
• WebSocket RPC ;
• Helius avancé ;
• Yellowstone ;
• autres providers/transports futurs.

Les adapters providers doivent toutefois faire sortir de la crate des modèles de transport homogènes par catégorie de donnée, afin que les consommateurs n'aient pas à comprendre chaque réponse propriétaire.

Ces modèles :

• restent indépendants de ksp-store-api ;
• conservent les informations raw/provenance nécessaires ;
• ne réalisent aucun décodage métier/protocolaire ;
• doivent être facilement et explicitement convertibles par ksp-worker-raw-retriever vers les modèles raw persistants de ksp-store-api.

Le détail de cette frontière de conversion est reporté à pre.003/pre.005.

Transport off-chain

Aucune crate ksp-offchain-transport-api ni trait global OffchainTransport n'est prévu.

ksp-offchain-transport-lib regroupe volontairement des accès hétérogènes afin d'éviter une explosion de petites crates. Metadata externes, quotes, prix hors blockchain ou routage peuvent conserver des APIs/modules spécialisés à l'intérieur de cette crate sans prétendre partager une abstraction métier commune.

Wallet

Aucune crate ksp-wallet-api n'est prévue.

ksp-wallet-lib est propriétaire du format wallet KSP, des opérations de protection/import/export et de l'accès contrôlé aux capacités pubkey/secret/signature nécessaires aux couches supérieures.

Les applications futures utilisant ce wallet restent des consommateurs de ksp-wallet-lib, pas des implémentations alternatives du contrat wallet.

Workers

ksp-worker-api

ksp-worker-api est une lifecycle API de services continus.

Elle pourra porter des contrats communs comme identité, état, health, start/stop/shutdown et événements de lifecycle. Une capacité optionnelle comme la reconfiguration à chaud ne doit devenir universelle que si plusieurs workers la partagent réellement.

Elle ne contient aucun concept de progression/checkpoint terminal propre aux jobs.

ksp-worker-control-lib

ksp-worker-control-lib est une implémentation réutilisable de gouvernance au-dessus de ksp-worker-api.

Elle doit pouvoir être consommée par :

• une application desktop manager spécialisée ;
• une future application globale ;
• un futur orchestrateur ;
• des tools/tests lorsque pertinent.

Les applications restent des interfaces et ne réimplémentent pas elles-mêmes registre, dispatch start/stop, agrégation d'état ou reconfiguration générique.

Packaging des workers

Chaque package ksp-worker-<role> doit pouvoir fournir :

library target
    -> logique/runtime service réutilisable

binary target
    -> bootstrap autonome mince

Cette direction permet de tester/réutiliser la logique sans perdre la propriété « service indépendant ».

Le binaire autonome n'est pas une seconde implémentation du worker.

Workers de processing

Le modèle initial d'un unique W2 est remplacé par une chaîne de responsabilités plus étroites :

raw persisted
    |
    v
ksp-worker-core-processor
    |
    v
canonical Core
    |
    v
ksp-worker-generic-materializer
    |
    v
generic materialization/journal
    |
    v
ksp-worker-domain-projector
    |
    v
domain projections

Le nom ksp-worker-domain-projector est explicitement provisoire jusqu'à ce que les contrats de matérialisation spécialisée soient définis.

Jobs

ksp-job-api est une lifecycle API de travaux déclenchés et terminables.

Elle peut porter identité, état, progression, cancel, résultat et, lorsque pertinent, pause/resume/checkpoint.

Aucune ksp-job-control-lib n'est prévue actuellement. Le fait que plusieurs jobs implémentent ksp-job-api suffit tant qu'aucune duplication concrète de gouvernance ne justifie une bibliothèque commune.

Notifications de données

Les notifications de données restent indépendantes du lifecycle des workers et des jobs.

Le même type de donnée persistée doit produire le même contrat de notification quelle que soit son origine :

worker live -----\
job backfill -----+--> même notification de donnée
import -----------/

ksp-store-api reste le propriétaire candidat de ces références/notifications lorsqu'elles signifient qu'une donnée persistée est disponible.

Le transport de notification reste distinct du contrat de donnée.

Scénarios et demos

Aucune crate monolithique de scénarios n'est prévue.

Les scénarios vivent dans des crates spécialisées :

ksp-scenario-memo-lib
ksp-scenario-token-lib
ksp-scenario-ata-lib
ksp-scenario-token-2022-lib
ksp-scenario-metadata-lib
ksp-scenario-spm-lib
...

ksp-scenario-api n'est pas retenu actuellement. La norme commune est documentée dans docs/rules/SCENARIO_CONVENTION.md et peut évoluer avec les premières implémentations.

Les applications de démonstration correspondantes suivent la forme :

ksp-app-scenario-<domain>-<environment>-desk-demo

Exemples :

ksp-app-scenario-memo-devnet-desk-demo
ksp-app-scenario-token-2022-devnet-desk-demo
ksp-app-scenario-metadata-devnet-desk-demo

Chaque application appelle la crate ksp-scenario-<domain>-lib correspondante et ne duplique pas son scénario. La crate scenario doit également pouvoir être appelée hors desktop.

Applications spécialisées et control plane

Les applications spécialisées sont prioritaires sur une future application globale.

Une app worker spécialisée passe par ksp-worker-control-lib / ksp-worker-api et ne manipule pas directement l'état interne du worker dans le Store.

Le data plane est D1–D4. Le control plane porte start/stop/status/health/reconfigure et reste séparé des payloads de processing.

Les workers doivent être exploitables comme services autonomes. Le mécanisme IPC exact reste à définir à la première implémentation manager/service ; aucun ksp-ipc-api générique n'est créé maintenant.

Une future application globale est conservée dans docs/IDEAS.md seulement.

Pipelines

ksp-pipeline-lib reste rejeté.

Le premier besoin concret de réutilisation est maintenant identifié : worker live et job de replay/backfill doivent partager la même logique d'une frontière durable.

Pipelines retenus :

ksp-pipeline-raw-ingestion-lib
ksp-pipeline-core-processing-lib
ksp-pipeline-generic-materialization-lib
ksp-pipeline-domain-projection-lib

Les pipelines sont backend/implementation agnostic autant que possible : ils dépendent des APIs (ksp-store-api, ksp-program-api, ksp-materializer-api) et reçoivent les implémentations concrètes par composition depuis worker/job.

Modèle opérationnel workers/jobs

Le backlog de processing est défini par les inputs applicables moins les processing outcomes terminaux du processor/version/capability cible.

L'absence d'output n'est pas une preuve d'absence de traitement.

KSP retient :

notification wake-up + periodic polling
Store backlog = source de vérité
claim/lease = ownership temporaire
at-least-once + idempotence = sémantique de traitement

Le raw retriever expose une hot reconfiguration avec distinction desired/effective configuration.

Les jobs de replay restent distincts des workers continus et réutilisent les mêmes pipelines.

Corrections issues de pre.003

Le graphe confirme les principes suivants :

• Program et Materializer restent indépendants du store et des I/O réseau ;
• ksp-execution-policy-api et ksp-execution-lib sont retenus ;
• ksp-execution-lib consomme ksp-program-api, pas l'implémentation officielle ksp-program-lib ;
• ksp-materializer-api peut dépendre de ksp-program-api, mais ni Materializer API/lib ni Store API/lib ne se dépendent mutuellement ;
• les workers/jobs spécialisés réalisent les conversions explicites entre modèles de transport, processing et persistence ;
• aucun ksp-data-api global n'est introduit ;
• ksp-worker-control-lib est retenu comme gouvernance workers réutilisable ; aucune ksp-job-control-lib n'est retenue.

Questions reportées aux prereleases suivantes

• pre.004 : forme exacte du contrat entre program preparation, execution policy, wallet et transport ;
• pre.004 : types publics précis de ksp-program-api et policy ;
• pre.005 : types publics de transport on-chain et conversion vers les DTO raw de ksp-store-api ;
• pre.005 : modèles materializer/store, notifications, replay et provenance ;
• première implémentation manager/service : mécanisme IPC et proxy distant Worker ;
• futur : orchestrateur/application globale seulement lorsqu'un besoin opérationnel concret le justifie.