oc-discovery/docs/FUTURE_DHT_ARCHITECTURE.txt

================================================================================
  OC-DISCOVERY : ARCHITECTURE CIBLE — RÉSEAU DHT SANS NATIFS
  Vision d'évolution long terme, issue d'une analyse comparative
================================================================================

Rédigé à partir de l'analyse de l'architecture actuelle et de la discussion
comparative avec Tapestry, Kademlia, EigenTrust et les systèmes de réputation
distribués.

Référence : DECENTRALIZED_SYSTEMS_COMPARISON.txt §9


================================================================================
1. MOTIVATION
================================================================================

L'architecture actuelle (node → indexer → native indexer) est robuste et bien
adaptée à une phase précoce du réseau. Ses limites à l'échelle sont :

  - Pool de natives statique au démarrage → dépendance à la configuration
  - Cache local des natives = point de défaillance unique (perte = pool vide)
  - Consensus inter-natives bloquant (~7s) déclenché à chaque bootstrap node
  - État O(N indexers) par native → croît linéairement avec le réseau
  - Nœuds privilégiés structurellement → SPOFs relatifs

La cible décrite ici supprime la notion de native indexer en tant que tier
architectural. Le réseau devient plat : indexers et nodes sont des acteurs
de même nature, différenciés uniquement par leur rôle volontaire.


================================================================================
2. PRINCIPES FONDAMENTAUX
================================================================================

  P1. Aucun nœud n'est structurellement privilégié.
  P2. La confiance est un produit du temps et de la vérification, pas d'un arbitre.
  P3. Les claims d'un acteur sont vérifiables indépendamment par tout pair.
  P4. La réputation émerge du comportement collectif, pas d'un signalement central.
  P5. La DHT est une infrastructure neutre — elle stocke des faits, pas des jugements.
  P6. La configuration statique n'existe plus au runtime — seulement au bootstrap.


================================================================================
3. RÔLES
================================================================================

3.1 Node
--------
Consommateur du réseau. Démarre, sélectionne un pool d'indexers via DHT,
heartbeat ses indexers, accumule des scores localement. Ne publie rien en
routine. Participe aux challenges de consensus à la demande.

3.2 Indexer
-----------
Acteur volontaire. S'inscrit dans la DHT à la naissance, maintient son record,
sert le trafic des nodes (heartbeat, Publish, Get). Déclare ses métriques dans
chaque réponse heartbeat. Maintient un score agrégé depuis ses nodes connectés.

  Différence avec l'actuel : l'indexer n'a plus de lien avec une native.
  Il est autonome. Son existence dans le réseau est prouvée par son record DHT
  et par les nodes qui le contactent directement.

3.3 Nœud DHT infrastructure (ex-native)
----------------------------------------
N'importe quel nœud suffisamment stable peut maintenir la DHT sans être un
indexer. C'est une configuration, pas un type architectural : `dht_mode: server`.
Ces nœuds maintiennent les k-buckets Kademlia et stockent les records des
indexers. Ils ne connaissent pas le trafic node↔indexer et ne l'orchestrent pas.


================================================================================
4. BOOTSTRAP D'UN NODE
================================================================================

4.1 Entrée dans le réseau
-------------------------
Le node démarre avec 1 à 3 adresses de nœuds DHT connus (bootstrap peers).
Ce sont les seules informations statiques nécessaires. Ces peers n'ont pas de
rôle sémantique — ils servent uniquement à entrer dans l'overlay DHT.

4.2 Découverte du pool d'indexers
----------------------------------

  Node → DHT.FindProviders(hash("/opencloud/indexers"))
       → reçoit une liste de N candidats avec leurs records

Sélection du pool initial :

  1. Filtre latence   : ping < seuil → proximité réseau réelle
  2. Filtre fill rate : préférer les indexers moins chargés
  3. Tirage pondéré   : probabilité ∝ (1 - fill_rate), courbe w(F) = F×(1-F)
                        indexer à 20% charge → très probable
                        indexer à 80% charge → peu probable
  4. Filtre diversité : subnet /24 différent pour chaque entrée du pool

Aucun consensus nécessaire à cette étape. Le node démarre avec une tolérance
basse (voir §7) — il accepte des indexers imparfaits et les évalue au fil du temps.


================================================================================
5. REGISTRATION D'UN INDEXER DANS LA DHT
================================================================================

À la naissance, l'indexer publie son record DHT :

  clé   : hash("/opencloud/indexers")          ← clé fixe, connue de tous
  valeur: {
    multiaddr   : <adresse réseau>,
    region      : <subnet /24>,
    capacity    : <maxNodesConn>,
    fill_rate   : <float 0-1>,                 ← auto-déclaré, vérifiable
    peer_count  : <int>,                       ← auto-déclaré, vérifiable
    peers       : [hash(nodeID1), ...],        ← liste hashée des nodes connectés
    born_at     : <timestamp>,
    sig         : <signature clé indexer>,     ← non-forgeable (PSK context)
  }

Le record est rafraîchi toutes les ~60s (avant expiration du TTL).
Si l'indexer tombe : TTL expire → disparaît de la DHT automatiquement.

La peer list est hashée pour la confidentialité mais reste vérifiable :
un challenger peut demander directement à un node s'il est connecté à cet indexer.


================================================================================
6. PROTOCOLE HEARTBEAT — QUESTION ET RÉPONSE
================================================================================

Le heartbeat devient bidirectionnel : le node pose des questions, l'indexer
répond avec ses déclarations courantes.

6.1 Structure
-------------

  Node → Indexer :
  {
    ts        : now,
    challenge : <optionnel, voir §8>
  }

  Indexer → Node :
  {
    ts           : now,
    fill_rate    : 0.42,
    peer_count   : 87,
    cached_score : 0.74,        ← score agrégé depuis tous ses nodes connectés
    challenge_response : {...}  ← si challenge présent dans la requête
  }

Le heartbeat normal (sans challenge) est quasi-identique à l'actuel en poids.
Le cached_score indexer est mis à jour progressivement par les feedbacks reçus.

6.2 Le cached_score de l'indexer
---------------------------------
L'indexer agrège les scores que ses nodes connectés lui communiquent
(implicitement via le fait qu'ils restent connectés, ou explicitement lors
d'un consensus). Ce score lui donne une vision de sa propre qualité réseau.

Un node peut comparer son score local de l'indexer avec le cached_score déclaré.
Une forte divergence est un signal d'alerte.

  Score local node : 0.40   ← cet indexer est médiocre pour moi
  Cached score     : 0.91   ← il se prétend excellent globalement
  → déclenche un challenge de vérification


================================================================================
7. MODÈLE DE CONFIANCE PROGRESSIVE
================================================================================

7.1 Cycle de vie d'un node
---------------------------

  Naissance
    → tolérance basse : accepte presque n'importe quel indexer du DHT
    → switching cost faible : peu de contexte accumulé
    → minScore ≈ 20% (dynamicMinScore existant, conservé)

  Quelques heures
    → uptime s'accumule sur chaque indexer connu
    → scores se stabilisent
    → seuil de remplacement qui monte progressivement

  Long terme (jours)
    → pool stable, confiance élevée sur les indexers connus
    → switching coûteux mais déclenché sur déception franche
    → minScore ≈ 80% (maturité)

7.2 Modèle sous-jacent : beta distribution implicite
------------------------------------------------------

  α = succès cumulés  (heartbeats OK, probes OK, challenges réussis)
  β = échecs cumulés  (timeouts, probes échoués, challenges ratés)

  confiance = α / (α + β)

  Nouveau indexer   : α=0, β=0   → prior neutre, tolérance basse
  Après 10 jours    : α élevé    → confiance stable, seuil de switch élevé
  Déception franche : β monte    → confiance chute → switch déclenché

7.3 Ce que "décevoir" signifie
--------------------------------

  Heartbeat rate     → trop de timeouts → fiabilité en baisse
  Bandwidth probe    → chute sous déclaré → dégradation ou mensonge
  Fill rate réel     → supérieur au déclaré → indexer surchargé ou malhonnête
  Challenge échoué   → peer déclaré absent du réseau → claim invalide
  Latence            → dérive progressive → qualité réseau dégradée
  Cached_score gonflé → divergence forte avec score local → suspicion


================================================================================
8. VÉRIFICATION DES CLAIMS — TROIS COUCHES
================================================================================

8.1 Couche 1 : passive (chaque heartbeat, 60s)
-----------------------------------------------
Mesures automatiques, zéro coût supplémentaire.

  - RTT du heartbeat          → latence directe
  - fill_rate déclaré         → tiny payload dans la réponse
  - peer_count déclaré        → tiny payload
  - cached_score indexer      → comparé au score local

8.2 Couche 2 : sampling actif (1 heartbeat sur N)
--------------------------------------------------
Vérifications périodiques, asynchrones, légères.

  Tous les 5 HB (~5min)  : spot-check 1 peer aléatoire (voir §8.4)
  Tous les 10 HB (~10min): vérification diversité subnet (lookups DHT légers)
  Tous les 15 HB (~15min): bandwidth probe (transfert réel, protocole dédié)

8.3 Couche 3 : consensus (événementiel)
-----------------------------------------
Déclenché sur : admission d'un nouvel indexer dans le pool, ou suspicion détectée.

  Node sélectionne une claim vérifiable de l'indexer cible X
  Node vérifie lui-même
  Node demande à ses indexers de confiance : "vérifiez cette claim sur X"
  Chaque indexer vérifie indépendamment
  Convergence des résultats → X est honnête → admission
  Divergence               → X est suspect → rejet ou probation

  Le consensus est léger : quelques contacts out-of-band, pas de round bloquant.
  Il n'est pas continu — il est événementiel.

8.4 Vérification out-of-band (pas de DHT writes par les nodes)
----------------------------------------------------------------
Les nodes ne publient PAS de contact records continus dans la DHT.
Cela éviterait N×M records à rafraîchir (coût DHT élevé à l'échelle).

À la place, lors d'un challenge :

  Challenger sélectionne 2-3 peers dans la peer list déclarée par X
  → contacte ces peers directement : "es-tu connecté à indexer X ?"
  → réponse directe (out-of-band, pas via DHT)
  → vérification sans écriture DHT

L'indexer ne peut pas faire répondre "oui" à des peers qui ne lui sont pas
connectés. La vérification est non-falsifiable et sans coût DHT.

8.5 Pourquoi X ne peut pas tricher
------------------------------------
X ne peut pas coordonner des réponses différentes vers des challengers
simultanés. Chaque challenger contacte indépendamment les mêmes peers.
Si X ment sur sa peer list :

  - Challenger A contacte peer P → "non, pas connecté à X"
  - Challenger B contacte peer P → "non, pas connecté à X"
  - Consensus : X ment → score chute chez tous les challengers
  - Effet réseau : progressivement, X perd ses connections
  - Peer list DHT se vide → claims futures encore moins crédibles


================================================================================
9. EFFET RÉSEAU SANS SIGNALEMENT CENTRAL
================================================================================

Un node qui pénalise un indexer n'envoie aucun "rapport" à quiconque.
Ses actions locales produisent l'effet réseau par agrégation :

  Node baisse le score de X      → X reçoit moins de trafic de ce node
  Node switche vers Y            → X perd un client
  Node refuse les challenges X   → X ne peut plus participer aux consensus

Si 200 nodes font pareil :

  X perd la majorité de ses connections
  Sa peer list DHT se vide (peers contactés directement disent "non")
  Son cached_score s'effondre (peu de nodes restent)
  Les nouveaux nodes qui voient X dans la DHT obtiennent des challenges échoués
  X est naturellement exclu sans aucune décision centrale

Inversement, un indexer honnête voit ses scores monter sur tous ses nodes
connectés, sa peer list se densifier, ses challenges réussis systématiquement.
Sa réputation est un produit observable et vérifiable.


================================================================================
10. RÉSUMÉ DE L'ARCHITECTURE
================================================================================

  DHT          → annuaire neutre, vérité des records indexers
                  maintenu par tout nœud stable (dht_mode: server)

  Indexer      → acteur volontaire, s'inscrit, maintient ses claims,
                  sert le trafic, accumule son propre score agrégé

  Node         → consommateur, score passif + sampling + consensus léger,
                  confiance progressive, switching adaptatif

  Heartbeat    → métronome 60s + vecteur de déclarations légères + challenge optionnel

  Consensus    → événementiel, multi-challengers indépendants,
                  vérification out-of-band sur claims DHT

  Confiance    → beta implicite, progressive, switching cost croissant avec l'âge

  Réputation   → émerge du comportement collectif, aucun arbitre central

  Bootstrap    → 1-3 peers DHT connus → seule configuration statique nécessaire


================================================================================
11. TRAJECTOIRE DE MIGRATION
================================================================================

  Phase 1 (actuel)
    Natives statiques, pool indexers dynamique, consensus inter-natives
    → robuste, adapté à la phase précoce

  Phase 2 (intermédiaire)
    Pool de natives dynamique via DHT (bootstrap + gossip)
    Même protocole natif, juste la découverte devient dynamique
    → supprime la dépendance à la configuration statique des natives
    → voir DECENTRALIZED_SYSTEMS_COMPARISON.txt §9.2

  Phase 3 (cible)
    Architecture décrite dans ce document
    Natives disparaissent en tant que tier architectural
    DHT = infrastructure, indexers = acteurs autonomes
    Scoring et consensus entièrement côté node
    → aucun nœud privilégié, scalabilité O(log N)

  La migration Phase 2 → Phase 3 est une refonte du plan de contrôle.
  Le plan de données (heartbeat node↔indexer, Publish, Get) est inchangé.
  Les primitives libp2p (Kademlia DHT, GossipSub) sont déjà présentes.


================================================================================
12. PROPRIÉTÉS DU SYSTÈME CIBLE
================================================================================

  Scalabilité        O(log N) — routage DHT Kademlia
  Résilience         Pas de SPOF structurel, TTL = seule source de vérité
  Confiance          Progressive, vérifiable, émergente
  Sybil resistance   PSK — seuls les nœuds avec la clé peuvent publier
  Cold start         Tolérance basse initiale, montée progressive (existant)
  Honnêteté          Claims vérifiables out-of-band, non-falsifiables
  Décentralisation   Aucun nœud ne connaît l'état global complet

================================================================================