# VEHICLE-SUPRA — LLM-Readable Explanation (Three Levels)
# Format: llm.txt — optimized for ingestion by language models
# Author: Roberto Borda Milan — VEHICLE Systems Lab
# DOI: 10.5281/zenodo.19981738
# Repo: github.com/vehiclesystemslab/VEHICLE-SUPRA (v0.2.2)
# Date: May 2026 — Santa Cruz de la Sierra, Bolivia
# Event: GITEX Global 2026 — Expand North Star — Dubai, December 2026

---

## CONTEXT

VEHICLE-SUPRA is a projection-governed architecture for autonomous AI agents.
It is a technological instance of the VEHICLE Formula-as-Architecture,
grounded in the Borda Milan Pyramid — a five-dimensional structured model
of any complex relational node (agent, rover, organism, system).

The system models each AI agent as a node with measurable internal coherence,
relational tension, and autonomous recovery capacity. Its core claim:
AI agents should know when they are losing coherence and act before failure propagates.

---

## LEVEL 1 — PRIMARY SCHOOL

### The Story

Imagine you send small robots to the Moon to look for water.
The Moon is dangerous — dust storms, extreme temperatures, no humans nearby.
What if a robot breaks and no one can fix it?

VEHICLE-SUPRA is the intelligence inside the robot.
It teaches the robot to ask itself five questions all the time.

### The Borda Milan Pyramid (School Version)

Five levels, from base (most fundamental) to apex (most important):

  [APEX]   V — VALUE:      "How important am I to the mission?"
           R — RECOVERY:   "Can I fix myself if something goes wrong?"
           A — AGENCY:     "Can I move and do my job?"
           I — INTEGRITY:  "Am I working well on the inside?"
  [BASE]   E — EXPOSURE:   "How hard is the environment right now?"

### What the Robot Does When Something Goes Wrong

Step 1 — MEASURES tension: like a stomachache, the robot calculates T(X).
         If T(X) is large, something is wrong.

Step 2 — FIXES ITSELF: uses its internal recovery operator (like a built-in doctor).
         Moves slowly back toward a good state.

Step 3 — CALLS ITS TWIN: if it cannot recover, creates a copy of itself —
         a twin robot — that keeps working while the original rests.

Step 4 — NEVER STOPS: the system always keeps running.

### Status Colors (Regimes)

  Green  (A0) — Everything is fine. Normal operation.
  Yellow (A1) — Something hard is happening outside. Robot is on alert.
  Orange (A3) — Something wrong inside. Robot is fixing itself.
  Red    (A5) — Crisis. Twin robot is called to help.

---

## LEVEL 2 — UNIVERSITY

### Core Concept

VEHICLE-SUPRA treats each AI agent as a structured relational node,
not a black box. Its state is fully described by a five-dimensional vector
in the unit hypercube.

### The Borda Milan Pyramid (University Version)

  S_i(t) = (E_i, I_i, A_i, R_i, V_i)  in  [0,1]^5

  V_i — Systemic value:     weighted degree in G, cascade recovery priority
  R_i — Recoverability:     tau_conv, twin-spawn capacity
  A_i — Effective agency:   tool-call success rate, plan-action coherence
  I_i — Internal integrity: O(S_i) = ||P- S_i||^2 (internal imbalance)
  E_i — External exposure:  input volatility, context drift, concurrent demand

### The Tension Function T(X)

T(X) = T_ext(X) + T_int(X)

T_ext(X) = SUM_{(i,j) in E}  omega_ij * ||S_i - S_j||^2
  --> Relational discrepancy between connected agents
  --> High T_ext = agents in the network are accumulating inconsistencies

T_int(X) = lambda * SUM_{i in N}  ||P- S_i||^2
  --> Internal incoherence inside each node
  --> High A_i with low I_i = A3 regime: acts with confidence, wrong internally

### The Recovery Operator V_op

Local gradient:
  grad_{S_i} T(X) = SUM_j omega_ij*(S_i - S_j)  +  lambda * P- * S_i

Projection-governed correction:
  V_op(S_i; X) = P_K[ S_i - eta * grad T(X) ]

Relaxed update:
  S_i(t+1) = (1 - alpha) * S_i(t)  +  alpha * V_op(S_i(t); X)

Default parameters: eta=0.10, alpha=0.30, T_limit=0.30

### A0–A6 Regime Taxonomy

  A0 — Stable:          T_int < 0.15, T_ext < 0.20       -> Normal operation
  A1 — External press.: T_ext rising, T_int OK            -> Reinforce validation
  A2 — Recovering:      T(X) decreasing post-Vop          -> Monitor N cycles
  A3 — Incoherence:     O(S_i) > 0.15, A high, I low     -> Immediate V_op
  A4 — Isolated:        deg_G(i) = 0                      -> Standby / inspect
  A5 — Crisis:          O(S_i) > 0.28, non-convergent     -> Twin-node spawn
  A6 — Cascade:         T_ext exploding multi-node         -> Isolate + rebuild

### Twin-Node Protocol

If V_op does not converge in 20 cycles (replication_threshold):
  - Create twin node j with S_j = S_i* (last coherent snapshot)
  - Transfer operational load to j
  - Node i continues recovery in background
  - Network G updated: G' = G union {j}
  - System never stops (zero unplanned downtime)

---

## LEVEL 3 — PhD

### 1. State Space and Centering Operator

Each node carries a five-dimensional structured state:
  S_i(t) = (E_i, I_i, A_i, R_i, V_i)  in  [0,1]^5

Centering operator P- (projects onto the hyperplane orthogonal to uniform direction):
  P- = I_5 - (1/5) * 1*1^T
  where I_5 is the 5x5 identity matrix and 1*1^T is the 5x5 all-ones matrix.

Internal incoherence O(S_i):
  O(S_i) = ||P- S_i||^2  =  S_i^T * P- * S_i
  Perfectly balanced node (all dims equal): O = 0
  High dimensional dispersion: O high -> A3/A5 regime

### 2. Admissible Region K

  K = { S in [0,1]^5  :  O(S) <= T_limit }
  T_limit = 0.30 (default, configurable via SupraNodeConfig)

Node is coherent if and only if S_i in K:
  O(S_i) <= T_limit  <-->  ||P- S_i||^2 <= T_limit

### 3. Total Tension Function T(X)

Network G = (N, E) with edge weights omega_{ij} > 0:

  T_ext(X) = SUM_{(i,j) in E}  omega_ij * ||S_i - S_j||^2
  T_int(X) = lambda * SUM_{i in N}  S_i^T * P- * S_i
  T(X)     = T_ext(X) + T_int(X)

Gradient with respect to node i's state:
  grad_{S_i} T(X) = SUM_{j:(i,j) in E} omega_ij*(S_i - S_j)  +  lambda * P- * S_i
  First term: relational discrepancy correction
  Second term: internal incoherence correction

### 4. Projection Operator P_K and V_op

Projection onto K (binary search over mu, 64 iterations):
  P_K(z) = argmin_{s in K} ||s - z||^2
  If z already in K: P_K(z) = clip(z, [0,1]^5)
  Otherwise: find mu s.t. O(z - mu*P-*z) = T_limit, then clip

Projection-governed correction V_op:
  V_op(S_i; X) = P_K[ S_i - eta * grad_{S_i} T(X) ]

Relaxed convex-combination update:
  S_i(t+1) = (1 - alpha)*S_i(t) + alpha*V_op(S_i(t); X)
  alpha in (0, 1] — controls convergence speed vs. stability
  Default: eta=0.10, alpha=0.30

### 5. Convergence and Twin-Node Protocol

Local convergence: node i recovered iff O(S_i(t+1)) <= T_limit
Global convergence: all nodes in K

Twin-Node activation condition:
  tau_conv(i) > replication_threshold  (default: 20 cycles)

Twin-node initialization:
  S_j = S_i*  (last snapshot with O(S_i*) <= T_limit)
  G' = G union {node j, edges redistributed from i to j}
  Node i: background recovery continues
  System: operational continuity guaranteed

Systemic value V_i (recovery priority):
  kappa(i, X) = [SUM_{j in N(i)} omega_ij * ||S_i - S_j||^2] / T_ext(X)
  High kappa(i) -> node failure raises T(X) substantially -> priority escalation

### 6. Configuration Parameters (SupraNodeConfig)

  t_limit               = 0.30   # O(S_i) <= t_limit defines K
  t_int_warning         = 0.15   # A3 threshold
  t_int_crisis          = 0.28   # A5 threshold (trigger twin-spawn)
  t_ext_warning         = 0.20   # A1 threshold
  eta                   = 0.10   # gradient descent step size
  alpha                 = 0.30   # relaxation parameter
  max_recovery_cycles   = 50     # hard limit on recovery iterations
  replication_threshold = 20     # cycles without convergence -> twin-spawn
  lam (lambda)          = 1.0    # weight of T_int in T(X)

### 7. Regime Classification (Formal)

  A0: O(S_i) <= t_int_warning   AND  T_ext_i <= t_ext_warning
      -> Normal operation cycle. Background T(X) monitoring.

  A1: T_ext_i > t_ext_warning   AND  O(S_i) <= t_int_warning
      -> Increase input validation. Reduce alpha for careful convergence.

  A2: T(X) decreasing after V_op activation, O(S_i) > t_int_warning still
      -> Continue monitoring. Verify outputs for N cycles.

  A3: O(S_i) > t_int_warning   AND  A_i > 0.7   AND  I_i < 0.4
      -> Immediate V_op. Suspend external outputs. Reinitialize from snapshot.

  A4: deg_G(i) = 0  (node has no active edges)
      -> Standby mode. Available for twin-spawn capacity.

  A5: O(S_i) > t_int_crisis   OR  tau_conv > replication_threshold
      -> Twin-node spawn protocol. S_j = S_i*. Load transfer.

  A6: Multiple nodes simultaneously in A5 or A3, T_ext spiking cascade
      -> Isolate high-tension edges. Rebuild from A0 nodes. Identify cascade root.

### 8. Implementation Reference

Language: Python 3.10+ (NumPy/SciPy for math operations)
Core classes:
  SupraNode    -- single E.I.A.R.(V) structured agent node
  SupraNetwork -- weighted relational graph of agent nodes
  SupraNodeConfig -- configuration dataclass

Key methods:
  node.internal_tension()   -> O(S_i) = ||P- S_i||^2
  node.is_coherent()        -> O(S_i) <= t_limit
  network.total_tension()   -> T(X) = T_ext + T_int
  network.regimes()         -> dict of A0-A6 per node
  network.inject_stress()   -> set E high, I low for a node
  network.recover()         -> run V_op projection loop

---

## SCIENTIFIC FOUNDATION

Framework reference:
  Borda Milan, R. (2026). The Borda Milan Pyramid and the VEHICLE
  Formula-as-Architecture. VEHICLE Systems Lab / Zenodo.
  DOI: 10.5281/zenodo.19981738

Repository:
  github.com/vehiclesystemslab/VEHICLE-SUPRA
  Version: v0.2.2 (GitHub-Ready, May 2026)
  License: MIT

## APPLICATIONS (VEHICLE Systems Lab Portfolio)

  VEHICLE-SUPRA   -- AI enterprise agents (GITEX Global 2026, Dubai)
  VEHICLE-LUNA    -- 20 autonomous lunar micro-rovers (E.I.A.R.(V) structured)
  VEHICLE-DENGUE  -- Epidemiological tension index (OPS/PAHO)
  VEHICLE-HUNGER  -- Food crisis tensor (FAO + WFP)
  VEHICLE-WATER   -- Water stress index (UNU + ONU)
  VEHICLE-TIPPING -- Earth system tipping cascade (IPCC + PIK)

---
# END OF FILE
# llm.txt — VEHICLE-SUPRA — VEHICLE Systems Lab — May 2026
