---
title: "Maritime Cyber-Range Simulation Guide"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Maritime Cyber-Range Simulation Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(MarineChain)
```

<h2 style="font-size:160%; font-weight:bold;"> Introduction </h2>
The Maritime PoAH Cyber-Range package is a simulation platform designed to evaluate and test maritime communication architectures under active threat vectors. Utilizing the Proof of Authority with Hunt (PoAH) lightweight consensus framework, the package models real-time kinematic mobility, high-altitude platform station (HAPS) stratospheric routing, and zero-trust regional geofencing.

This guide details the core architectural state machines, boundary mechanics, and how to operate the decoupled simulation dashboard.

<h2 style="font-size:160%; font-weight:bold;"> Architectural Engine Mechanics </h2>
The architecture maintains an automated, zero-trust stance by enforcing strict state transitions across all traveling fleet assets.

1. Finite State Machine (FSM)
Each vessel spawned within the range is evaluated at each clock tick against an operational state array:

- EnRoute (Orange): The vessel is traveling safely toward its designated terminal hub. It continually generates performance logs and transmits telemetry.

- Arrived (Green): The vessel has successfully matched its target port destination coordinates. Kinematics stop, and the vessel remains safely anchored.

- Locked (Red): The vessel has tripped a security boundary or is being actively targeted by a cyber-attack vector.

2. Autonomous Isolation Protocol (The "Active" Rule)When a threat is intercepted, the control station changes the vessel state to Locked. The system enforces containment immediately:$$\text{Velocity} = 0$$$$\text{Network Transmissions} = \emptyset$$The dashboard label changes to SECURITY LOCKOUT ACTIVE, confirming that data streams are severed and the vehicle is physically quarantined on the range canvas.

<h2 style="font-size:160%; font-weight:bold;"> Zero-Trust Geofencing </h2>
Instead of using the HAPS transceiver purely to calculate network delay penalties, the system converts its communication coverage radius into a hard boundary line.

Distance is monitored using the Haversine Formula, tracking physical displacement over the curvature of the Earth:

$$d = 2R \arcsin\left(\sqrt{\sin^2\left(\frac{\Delta \phi}{2}\right) + \cos(\phi_1)\cos(\phi_2)\sin^2\left(\frac{\Delta \lambda}{2}\right)}\right)$$
Where:

- $\phi_1, \phi_2$ are the latitudes of the vessel and HAPS center in radians.

- $\Delta \phi, \Delta \lambda$ are the geographic differences.

- $R$ is the Earth's mean radius ($6,371,000\text{ meters}$).

If $d > \text{Geofence Shield Radius}$, an automated boundary breach event fires. The vessel instantly switches to a Locked state, halts, and changes its map marker to a localized red containment pin.

<h2 style="font-size:160%; font-weight:bold;"> Operating the Cyber-Range Dashboard </h2>
To launch the self-contained dashboard workspace, run the application entrypoint command:

```{r run_app, eval = FALSE}
library(MarineChain)
run_app()
```
<h2 style="font-size:160%; font-weight:bold;"> Configuration Pipeline Steps </h2>

1. Configure Core Geometry: Adjust the slider to set the total fleet vessel volume. Provide target coordinates for your Control Station Base and your floating stratospheric HAPS node.

2. Define Port Networks: Modify the Fleet Port Destinations Network Matrix text area. Input custom target locations using plain text line arrays formatted as Latitude, Longitude.

3. Execute: Click "Start Simulation". The application will ingest the configurations, parse the matrices without hard-coded constants, build the regional geofence, and begin movement loops.

4. Inject Cyber Vulnerabilities: Navigate to the threat inspector panel. Select an attack vector (Modification or Impersonation) and pick a target vessel to test the immediate lockout and containment features offline.

<h2 style="font-size:160%; font-weight:bold;"> Conclusion and Next Steps </h2>
This package (MarineChain) provides a fully decoupled, visual, and reactive sandbox simulation layer. With robust state machine tracking and offline containment capabilities in place, the workspace is ready for the next package (Formal Symbolic Protocol Verification), where we will mathematically prove the safety of these communication paths under adversarial conditions.
