# Network Permeability

## Purpose

This document defines the operator-facing backdrop for interference and reachability.

It is not a decorative map.

It exists to answer:

- which user-network slices can still reach DAMM ingress
- where interference is accumulating
- which failures are provider-specific versus zone-specific
- where the next ingress or egress node should be added

## Core Idea

The permeability model is the bridge between raw observations and fleet decisions.

The pipeline should be:

1. collect path observations
2. normalize incidents
3. derive permeability scores
4. rank placement and routing recommendations
5. publish the result into operator surfaces

## Data Model

### Network Zone

A network zone is the slice from which we evaluate reachability.

It may be keyed by:

- country
- region
- ASN
- carrier
- named user cohort

Required fields:

- `id`
- `label`
- `country`
- `networkType`
- `notes`

### Path Observation

A path observation is a direct measurement from one network zone to one ingress option.

Required fields:

- `zoneId`
- `provider`
- `ingressRegion`
- `gatewayId`
- `frontdoorId`
- `observedAt`
- `handshakeSuccessRate`
- `medianRttMs`
- `p95RttMs`
- `packetLossPct`
- `sampleCount`

Optional fields:

- `dnsTamperingObserved`
- `resetObserved`
- `notes`

### Interference Incident

An incident is the normalized operator-facing record of disruption.

Required fields:

- `id`
- `zoneId`
- `severity`
- `class`
- `summary`
- `firstSeenAt`
- `lastSeenAt`
- `confidence`
- `affectedProviders`
- `affectedFrontdoors`

Suggested `class` values:

- `dns_tampering`
- `packet_loss`
- `selective_ingress_blocking`
- `provider_outage`
- `mobile_only_disruption`
- `regional_blackhole`

### Permeability Score

Permeability is the current judgment for a zone-to-ingress slice.

Required fields:

- `zoneId`
- `provider`
- `ingressRegion`
- `permeabilityScore`
- `stabilityScore`
- `replaceabilityScore`
- `status`
- `recommendedAction`

Suggested `status` values:

- `open`
- `degraded`
- `intermittent`
- `selectively_interfered`
- `effectively_blocked`

### Placement Recommendation

Placement recommendations turn the permeability model into action.

Required fields:

- `type`
- `target`
- `reason`
- `priority`
- `backingZoneIds`

Suggested `type` values:

- `add_ingress`
- `add_egress`
- `reweight`
- `withdraw_frontdoor`
- `hold`
- `investigate`

## How DAMM Should Use It

### Control Plane

The control plane should consume permeability summaries as an input to:

- placement guidance
- frontdoor publication weighting
- degraded-mode reporting

The control plane should not silently rewrite trust boundaries based on this data.

Permeability affects ranking and operator judgment, not signature policy.

### Operator Report

The operator report should surface:

- weakest current user-network slices
- highest-severity incidents
- where diversity is too thin
- the next node recommendation and why it exists

### Orchestrator

The orchestrator should eventually use permeability-backed recommendations to:

- add ingress capacity in the right provider-region pair
- add egress where exit demand and interference both justify it
- avoid overreacting to short-lived or low-confidence incidents

## Design Constraints

- evidence should age out
- low-confidence incidents should not dominate placement
- provider failure and state interference should not be conflated
- the first UI should privilege ranked tables over maps
- any world map should remain secondary to the action list

## MVP Contract

The current MVP should provide:

- a JSON artifact with sample or collected permeability data
- a generated operator page
- a link from the VPN report
- a documented schema and interpretation

The current MVP does not yet provide:

- live probes from all user cohorts
- automated route ranking in the client
- automatic provider provisioning from incidents alone