Skip to content

Attachment migration — overlap, switch, hysteresis #68

@TickTockBent

Description

@TickTockBent

Phase 3 — Discovery Protocol v2

Context

When attachment selection (#67) identifies a better substrate node for a transient node, it needs to migrate without losing gossip.

With the substrate/transient model, migration is simpler than tree rebalancing — it's a single connection swap. Open new WebSocket, confirm gossip flowing, close old WebSocket. No subtree restructuring, no cascading effects. The main complexity is hysteresis to prevent flapping.

Migration only applies to transient nodes — they're the ones with substrate attachments. Substrate nodes stay in their flat mesh and never migrate.

Task

Migration flow:

  1. Transient node opens WebSocket to new substrate node candidate
  2. Sends hello, receives welcome
  3. New substrate node begins forwarding gossip
  4. Brief overlap: node receives gossip from both old and new attachment (dedup handles duplicates)
  5. Node closes connection to old substrate node
  6. Attachment reference updated

Hysteresis (anti-flap):

  • New attachment must be measurably better: >25% latency improvement OR same-enclave vs cross-enclave
  • Improvement must persist across two consecutive evaluation cycles before migration triggers
  • Cooldown: one full evaluation cycle after migration before next migration is allowed
  • These thresholds are starting points — tune based on real network behavior

Failure during migration:

  • If new substrate attachment fails (handshake timeout, WS error): cancel migration, keep old attachment
  • If old substrate node dies during overlap: migration accelerates, new attachment becomes primary
  • No data loss in either case — dedup handles duplicates during overlap, and missed data was ephemeral anyway

Acceptance Criteria

  • Migration with overlap — no gossip gap
  • Hysteresis: requires sustained improvement across 2 cycles
  • Cooldown after migration
  • Failed migration keeps old attachment
  • Old substrate node death during migration handled gracefully
  • Only transient nodes migrate — substrate nodes never run this code

Depends on #67.
Part of Discovery Protocol v2 — see docs/internal/REPRAM-Discovery-Protocol-v2.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    discovery-v2Discovery Protocol v2 — tree topology and NAT traversalenhancementNew feature or requestjavascriptPull requests that update javascript code

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions