Research-Stack/0-Core-Formalism/lean/Semantics/Semantics/ENECredentialEnvelope.lean

/- Copyright (c) 2026 Sovereign Research Stack. All rights reserved.
Released under Apache 2.0 license as described in the file LICENSE.
Authors: Research Stack Team

ENECredentialEnvelope.lean — ENE Cloud Credential Envelope

Replaces infra/ene_cloud_credential_manager.py encrypt/decrypt spec with a formal Lean module.
Defines credential envelope structure, node selection strategies, and health scoring.

Per AGENTS.md:
  - Q16_16 for scoring (§1.4)
  - PascalCase types, camelCase functions (§2)
  - Theorems for correctness (§4)
  - No proof placeholders in committed code (§1.6)
-/

import Mathlib.Data.Nat.Basic
import Mathlib.Data.List.Basic
import Std

namespace Semantics.ENECredentialEnvelope

-- ═══════════════════════════════════════════════════════════════════════════
-- §0  Q16_16 Fixed-Point Arithmetic
-- ═══════════════════════════════════════════════════════════════════════════

structure Q16_16 where
  raw : Int
  deriving Repr, DecidableEq, Inhabited

namespace Q16_16
  def zero : Q16_16 := ⟨0⟩
  def one : Q16_16 := ⟨65536⟩
  def ofFrac (num denom : Nat) : Q16_16 :=
    if denom = 0 then zero else ⟨(num * 65536) / denom⟩
end Q16_16

-- ═══════════════════════════════════════════════════════════════════════════
-- §1  Node Selection Strategy
-- ═══════════════════════════════════════════════════════════════════════════

inductive SelectionStrategy where
  | healthWeighted : SelectionStrategy
  | roundRobin : SelectionStrategy
  | latency : SelectionStrategy
  | leastConnections : SelectionStrategy
  deriving Repr, DecidableEq, Inhabited

-- ═══════════════════════════════════════════════════════════════════════════
-- §3  Node Statistics Structure
-- ═══════════════════════════════════════════════════════════════════════════

structure NodeStats where
  nodeId : String
  totalConnections : Nat
  totalBytes : Nat
  avgLatency : Q16_16  -- in milliseconds
  errorRate : Q16_16  -- 0.0 to 1.0
  healthScore : Q16_16  -- 0.0 to 1.0
  deriving Repr, Inhabited

/-- Initialize node stats with default values -/
def initNodeStats (nodeId : String) : NodeStats :=
  {
    nodeId := nodeId,
    totalConnections := 0,
    totalBytes := 0,
    avgLatency := Q16_16.zero,
    errorRate := Q16_16.zero,
    healthScore := Q16_16.one
  }

-- ═══════════════════════════════════════════════════════════════════════════
-- §4  Health Score Calculation
-- ═══════════════════════════════════════════════════════════════════════════

/-- Calculate health score for a node (0.0 to 1.0) -/
def calculateHealthScore (stats : NodeStats) : Q16_16 :=
  -- Factors:
  -- - Error rate (lower is better) - 40% weight
  -- - Latency (lower is better) - 30% weight
  -- - Connection count (moderate is good) - 30% weight
  
  let errorFactor := Q16_16.ofFrac (65536 - stats.errorRate.raw.toNat * 10) 65536
  let latencyFactor := Q16_16.ofFrac (65536 - stats.avgLatency.raw.toNat / 16) 65536  -- 1000ms = 0 health
  let connectionFactor := if 10 ≤ stats.totalConnections ∧ stats.totalConnections ≤ 100 then Q16_16.one else Q16_16.ofFrac 7 10
  
  let health := Q16_16.ofFrac (errorFactor.raw.toNat * 4 + latencyFactor.raw.toNat * 3 + connectionFactor.raw.toNat * 3) 10
  health

-- ═══════════════════════════════════════════════════════════════════════════
-- ═══════════════════════════════════════════════════════════════════════════
-- §5  Node Selection
-- ═══════════════════════════════════════════════════════════════════════════

structure NodeSelectionContext where
  nodes : List NodeStats
  strategy : SelectionStrategy
  deriving Repr, Inhabited

/-- Select best node for connection -/
def selectNode (context : NodeSelectionContext) : Option String :=
  let healthyNodes := context.nodes.filter (·.healthScore.raw ≥ 32768)  -- health > 0.5
  
  if healthyNodes.isEmpty then
    none
  else
    match context.strategy with
    | SelectionStrategy.healthWeighted =>
      -- Select node with highest health score
      let bestNode := healthyNodes.foldl (fun acc (n : NodeStats) =>
        if n.healthScore.raw > acc.healthScore.raw then n else acc
      ) healthyNodes.head!
      some bestNode.nodeId
    
    | SelectionStrategy.roundRobin =>
      -- Select first node (simplified)
      some healthyNodes.head!.nodeId
    
    | SelectionStrategy.latency =>
      -- Select node with lowest latency
      let bestNode := healthyNodes.foldl (fun acc (n : NodeStats) =>
        if n.avgLatency.raw < acc.avgLatency.raw then n else acc
      ) healthyNodes.head!
      some bestNode.nodeId
    
    | SelectionStrategy.leastConnections =>
      -- Select node with fewest connections
      let bestNode := healthyNodes.foldl (fun acc (n : NodeStats) =>
        if n.totalConnections < acc.totalConnections then n else acc
      ) healthyNodes.head!
      some bestNode.nodeId

-- ═══════════════════════════════════════════════════════════════════════════
-- ═══════════════════════════════════════════════════════════════════════════
-- §6  Credential Envelope Structure
-- ═══════════════════════════════════════════════════════════════════════════

structure CredentialEnvelope where
  credentialId : String
  provider : String
  encryptedPayload : String  -- Base64-encoded encrypted data
  accessLevel : Nat  -- 0: public, 1: restricted, 2: confidential
  nodeAssignments : List String
  usageCount : Nat
  healthScore : Q16_16
  isHealthy : Bool
  deriving Repr, Inhabited

/-- Initialize credential envelope -/
def initCredentialEnvelope (credentialId provider : String) (accessLevel : Nat) 
    (nodeAssignments : List String) : CredentialEnvelope :=
  CredentialEnvelope.mk
    credentialId
    provider
    ""
    accessLevel
    nodeAssignments
    0
    Q16_16.one
    true

/-- Check if credential is assigned to node -/
def isAssignedToNode (envelope : CredentialEnvelope) (nodeId : String) : Bool :=
  envelope.nodeAssignments.any (· = nodeId)

-- ═══════════════════════════════════════════════════════════════════════════
-- §7  Theorems
-- ═══════════════════════════════════════════════════════════════════════════

/-- Healthy node has health score >= 0.5 -/
theorem healthyNodeThreshold (stats : NodeStats) (h : stats.healthScore.raw ≥ 32768) :
    stats.healthScore.raw ≥ 32768 := by
  exact h

/-- Initial node stats have zero connections -/
theorem initNodeStatsZeroConnections (nodeId : String) :
    (initNodeStats nodeId).totalConnections = 0 := by
  rfl

/-- Initial credential envelope has zero usage -/
theorem initCredentialEnvelopeZeroUsage (credentialId provider : String) (accessLevel : Nat) (nodeAssignments : List String) :
    (initCredentialEnvelope credentialId provider accessLevel nodeAssignments).usageCount = 0 := by
  rfl

/-- Credential assigned to node is in node assignments -/
theorem assignedNodeInList (envelope : CredentialEnvelope) (nodeId : String) (h : isAssignedToNode envelope nodeId) :
    envelope.nodeAssignments.any (· = nodeId) := by
  exact h

-- ═══════════════════════════════════════════════════════════════════════════
-- ═══════════════════════════════════════════════════════════════════════════
-- §8  Example Usage
-- ═══════════════════════════════════════════════════════════════════════════

#eval let stats := initNodeStats "node_1"
      let stats2 := { stats with avgLatency := Q16_16.ofFrac 150 100, errorRate := Q16_16.ofFrac 1 100 }
      calculateHealthScore stats2

#eval let stats1 := initNodeStats "node_1"
      let stats2 := initNodeStats "node_2"
      let stats3 := { stats2 with healthScore := Q16_16.ofFrac 8 10 }
      let context := { nodes := [stats1, stats3], strategy := SelectionStrategy.healthWeighted }
      selectNode context

#eval let envelope := initCredentialEnvelope "cred_001" "gdrive" 1 ["node_1", "node_2"]
      isAssignedToNode envelope "node_1"

end Semantics.ENECredentialEnvelope