khadhroony-solana-project/deltas/0.0.3/pre.007.md

Delta 0.0.3-pre.007

Base requise

v0.0.3-pre.006.

Objectif

Formaliser le modèle opérationnel des acquisitions et traitements continus/ponctuels au-dessus des niveaux durables D1–D4, sans encore ouvrir les apps/managers/IPC.

Version Cargo

workspace.package.version passe de :

0.0.3-pre.6

à :

0.0.3-pre.7

Le header de Cargo.toml passe de version 12 à 13.

Fichiers ajoutés

• docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
• deltas/0.0.3/pre.007.md

Fichiers modifiés

• Cargo.toml
• ROADMAP.md
• docs/architecture/000-README.md
• docs/architecture/003-COMPONENT_CONTRACTS.md
• docs/architecture/004-COMPONENT_INVENTORY.md
• docs/architecture/005-DEPENDENCY_GRAPH.md
• docs/rules/RULES_DEPENDENCIES.md
• docs/rules/RULES_KSP.md
• docs/IDEAS.md
• docs/plans/001-V0_0_3_PLAN.md
• prompts/001-V0_1_X_START_PROMPT.md

Fichiers supprimés

Aucun.

Décisions principales

Pipelines spécialisés

Le besoin concret de mutualiser exactement la même frontière entre worker live et job justifie quatre crates :

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

Aucun ksp-pipeline-lib monolithique n'est introduit.

Les pipelines dépendent des APIs nécessaires, pas des implémentations officielles lorsqu'une injection est possible :

raw ingestion        -> onchain transport models + store-api
core processing      -> program-api + store-api
generic materialize  -> materializer-api + store-api
domain projection    -> materializer-api + store-api

Workers/jobs composent ensuite ksp-store-lib, ksp-program-lib, ksp-materializer-lib ou des implémentations externes compatibles.

Workers

Workers retenus :

ksp-worker-raw-retriever
ksp-worker-core-processor
ksp-worker-generic-materializer
ksp-worker-domain-projector

ksp-worker-api reste une lifecycle API continue.

Le raw retriever supporte la hot reconfiguration et distingue configuration desired/effective.

Jobs

Jobs de données retenus :

ksp-job-backfill
ksp-job-replay-core
ksp-job-replay-generic-materialization
ksp-job-replay-domain-projection

ksp-job-api reste séparé de Worker et aucune ksp-job-control-lib n'est créée.

Backlog et outcomes

L'absence d'output ne signifie pas qu'un input est pending.

Le backlog est relatif à :

input
processor identity
processor version
capability/materializer/projector

Chaque traitement possède un outcome durable, y compris pour NoOutput/NotApplicable/Unsupported selon les types finaux.

Une nouvelle version de processor peut créer un nouveau travail pour un input déjà terminal sous l'ancienne version.

Claim / lease

La concurrence multi-instance utilise une ownership temporaire par claim/lease.

Une lease expirée après crash rend l'input de nouveau claimable.

Le détail SQL est reporté à l'implémentation PostgreSQL.

At-least-once

Sémantique retenue :

at-least-once processing
+
idempotent durable persistence
+
durable processing outcomes

Aucune promesse exactly-once distribuée n'est recherchée.

Atomicité

Outputs obligatoires et processing outcome d'une même unité logique doivent être cohérents/atomiques du point de vue durable.

Reprise

Après restart, worker/job recharge configuration/scope, laisse expirer/récupère les claims, requête le backlog Store et reprend.

Un cursor est une optimisation, pas la preuve de completion.

Replay

Replay normal/reprise et force replay sont distincts.

Un force replay conserve provenance/historique et ne supprime pas silencieusement le résultat courant.

Notifications

PostgreSQL LISTEN/NOTIFY est retenu comme mécanisme initial de référence de wake-up, sans garantie de backlog.

Chaque consumer combine :

notification wake-up
+
periodic polling

Le Store reste la source de vérité.

Batching / backpressure

Batch size, concurrence, poll interval, retry/backoff et lease duration sont des paramètres spécialisés, pas nécessairement des propriétés universelles de Worker/Job API.

Un backlog downstream croissant est observable mais ne ralentit pas automatiquement l'acquisition D1.

Plan

• pre.008 — apps/managers/scenarios/processus/IPC/orchestration ;
• pre.009 — releases fonctionnelles concrètes ;
• pre.010 — clôture fondatrice.

Questions reportées

• schéma SQL de claim/lease ;
• durée/renouvellement de lease ;
• types exacts des processing outcomes ;
• contexte stateful des projectors ;
• graceful shutdown d'un batch ;
• pause/resume générique ou capability de job ;
• télémétrie/metrics au-delà des logs et health.

Validations

• headers file: / version: vérifiés ;
• Cargo.toml parsé et version 0.0.3-pre.7 vérifiée ;
• référence vers 009-ACQUISITION_WORKERS_AND_JOBS.md vérifiée ;
• quatre pipelines spécialisés présents dans inventaire/règles ;
• quatre workers et quatre jobs de données présents dans l'architecture ;
• aucune dépendance pipeline vers ksp-store-lib, ksp-program-lib ou ksp-materializer-lib dans le graphe de pipeline ;
• plan conservé jusqu'à pre.010 ;
• aucune commande Cargo build/test exécutée : ce delta reste documentaire.