Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.0-pre.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-17 13:33:37 +02:00
parent 7d40de3249
commit 259bff6707
23 changed files with 2999 additions and 3301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

393
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,344 +1,153 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 10 -->
<!-- version: 6 -->
# 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`](006-WIRE_AND_PROGRAM.md), `pre.005` Execution/Policy, `pre.006` les niveaux durables/Materialization/Store, `pre.007` l'exploitation workers/jobs/pipelines, `pre.008` Apps/Services/Scenarios/Control, puis `pre.009` le séquencement des premières releases fonctionnelles. La séquence détaillée est dans `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`. Les détails de types Rust restent révisables avec les premières implémentations.
Ce document maintient l'inventaire synthétique des composants retenus ou pressentis. Les numéros de release précis restent soumis au sizing de chaque session.
## 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.
- `Stable` — implémenté et publié ;
- `Retenu` — composant/contrat décidé ;
- `Pressenti` — direction décidée mais périmètre exact à confirmer ;
- `À la demande` — créé seulement au premier besoin réel ;
- `Non retenu` — explicitement écarté pour l'instant.
## 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.1` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.3` par défaut | documents de configuration, profils, résolution, modifications autorisées |
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.2` | façade unique `tracing`/appender/subscriber, initialisation et logging structuré KSP ; peut dépendre de core pour Error/Result |
| Config desktop | `ksp-app-config-desk` | app | N4 | Retenu | `0.1.4` par défaut | app spécialisée Tauri validant chargement, profils, édition, sauvegarde, validation et diagnostics Config |
| 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 |
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|-------------------------|------------------------------------------|--------------------|--------------|---------------------------------|----------------------------------------------------------|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.1` | JSON-RPC HTTP complet, settings, pools, rôles |
| Wallet | `ksp-wallet-lib` | lib | Retenu | `0.2.2` | `.kspwallet`, secrets, signature, import/export |
| Wallet Desk | `ksp-app-wallet-desk` | app | Retenu | `0.2.3` | Wallet + Config composite + HTTP/balance |
| Standard WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.4` | WebSocket Solana complet, sessions/subscriptions |
| Helius WS | `ksp-onchain-transport-lib` | lib | Retenu | `0.2.5` | LaserStream WebSocket comme extension du moteur standard |
| Yellowstone | `ksp-onchain-transport-lib` | lib | Pressenti | `0.2.6` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Retenu | `0.2.7` | première abstraction/provider de prix SOL/USD, SOL/EUR |
| Price Desk | nom à fixer | app | Retenu | `0.2.8` | visualisation/validation des prix |
| Wire | `ksp-interface-lib` | lib | Retenu | `0.2.9` | façade wire officielle + API publique wire |
| Program API | `ksp-program-api` | API | Retenu | `0.2.10` | contrats extensibles Program |
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |
| Store API | `ksp-store-api` | API | Retenu | `0.3.1` | contrats persistence backend-agnostic, RAW d'abord |
| Store PostgreSQL | `ksp-store-lib` | lib | Retenu | `0.3.1` | backend PostgreSQL officiel, RAW d'abord |
| Job lifecycle | `ksp-job-api` | API | Retenu | `0.3.3` | lifecycle des jobs terminables |
| Backfill | `ksp-job-backfill` | job/lib à préciser | Retenu | `0.3.3` | acquisition historique vers RAW |
| Backfill Desk | nom à fixer | app | Retenu | `0.3.4` | contrôle/inspection du backfill RAW |
| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus |
| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW |
| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE |
| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
| Trading Intelligence | noms à définir | libs/jobs | Futur | après données stables | features/signaux/anomalies/ML |
## APIs séparées retenues
Les couples suivants ont une justification d'extensibilité suffisante :
## Contrats séparés retenus
```text
ksp-program-api -> ksp-program-lib
ksp-materializer-api -> ksp-materializer-lib
ksp-store-api -> ksp-store-lib
ksp-program-api
ksp-materializer-api
ksp-store-api
ksp-worker-api
ksp-job-api
ksp-execution-policy-api
```
Les APIs lifecycle sont également séparées :
Pas de crates séparées actuellement pour :
```text
ksp-worker-api -> workers continus
ksp-job-api -> jobs terminables
ksp-interface-api
ksp-wallet-api
ksp-onchain-transport-api
ksp-offchain-transport-api
ksp-scenario-api
ksp-job-control-lib
ksp-data-api
```
Aucune API commune worker+job n'est prévue.
## Transport
## Execution policy et orchestration
`ksp-onchain-transport-lib` doit couvrir l'intégralité des opérations documentées de la surface ciblée par chaque release. Les statuts deprecated/obsolete encore fonctionnels et unstable/experimental restent exposés avec warning runtime KSP.
La frontière détaillée est définie dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md).
La Config standard Transport appartient à `ksp-config-lib`, qui adapte vers les settings publics du transport ; le transport ne dépend jamais de Config.
Principes retenus :
Les WebSockets supportent plusieurs sessions pour un même endpoint URL, mais un pool/scheduler automatique n'est créé qu'après besoin démontré.
```text
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`.
Les principes de cette frontière sont désormais fixés : transport et Store restent indépendants, et la conversion explicite transport -> D1 appartient au pipeline/composant de composition. Les DTO exacts seront définis avec les premières implémentations Transport/Store.
## 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.
Les providers Yellowstone spécifiques restent des extensions futures ; le contrat standard est provider-neutral.
## Wallet
Aucune crate `ksp-wallet-api` n'est prévue.
Le format natif est `.kspwallet`.
`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 anciens temporary wallets JSON ne sont pas migrés.
Les applications futures utilisant ce wallet restent des consommateurs de `ksp-wallet-lib`, pas des implémentations alternatives du contrat wallet.
`WalletPolicy` est exclu du Wallet et relève de l'execution policy.
## Workers
Import/export reste extensible ; les formats supplémentaires sont suivis dans `docs/IDEAS.md`.
### `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 éventuel orchestrateur commun si un besoin opérationnel concret le justifie ;
- 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 :
## Data plane
```text
library target
-> logique/runtime service réutilisable
binary target
-> bootstrap autonome mince
RAW -> CORE -> DECODE -> SPECIALIZED
```
Cette direction permet de tester/réutiliser la logique sans perdre la propriété « service indépendant ».
- RAW : acquisition replayable ;
- CORE : normalisation blockchain générique sans decoder Program ;
- DECODE : interpretation Program + matérialisation générique/journal ;
- SPECIALIZED : projections queryables de domaine.
Le binaire autonome n'est pas une seconde implémentation du worker.
## Progression des processors
### Workers de processing
RAW et CORE sont complétés couche par couche avec jobs/workers/apps utiles.
Le modèle initial d'un unique W2 est remplacé par une chaîne de responsabilités plus étroites :
À partir de DECODE, progression verticale par groupe :
```text
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
wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario
```
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 :
Groupes prioritaires :
```text
worker live -----\
job backfill -----+--> même notification de donnée
import -----------/
Solana Core Programs
SPL token/trading
token metadata
Anchor
Meteora
Raydium
Pump
Orca
Market Desk V1
Jupiter/OKX routing
Market Desk V2
trading-adjacent
general decoding
```
`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.
Meteora vaults, Pump fees et autres satellites nécessaires restent dans leur groupe.
Le transport de notification reste distinct du contrat de donnée.
## Applications spécialisées
## Scénarios et demos
Les applications servent de validations/exploitations réelles sans absorber la logique des bibliothèques.
Aucune crate monolithique de scénarios n'est prévue.
Market Desk est progressive : V1 après les DEX prioritaires, puis enrichissement routing après Jupiter/OKX.
Les scénarios vivent dans des crates spécialisées :
## Questions restantes
```text
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 :
```text
ksp-app-scenario-<domain>-<environment>-desk-demo
```
Exemples :
```text
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 :
```text
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 :
```text
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 restantes après la fondation
- types Rust exacts des contrats ouverts de `ksp-program-api` ;
- DTO exacts des modèles transport et D1/D2/D3/D4 avec les premières implémentations concernées ;
- schémas SQL, indexes, claims/leases et pagination du Store PostgreSQL ;
- première implémentation manager/service : mécanisme IPC et proxy distant Worker ;
- contexte requis par les projectors stateful ;
- futur : orchestrateur commun seulement si un besoin opérationnel concret le justifie ; l'application globale reste un produit futur après validation des apps spécialisées.
- noms exacts de Price Desk et Backfill Desk ;
- surface exacte Yellowstone après audit normatif de `0.2.6-pre.001` ;
- nécessité future d'un pool automatique WS ;
- types exacts `ksp-program-api`/`ksp-materializer-api`/`ksp-store-api` ;
- nom/packaging précis du premier RAW worker et du CORE normalizer ;
- granularité des workers DECODE/SPECIALIZED par groupe.