# Classification

*The intelligence layer over the wings you already build by hand.*

You already build a minimum wing and a max block. You already put the psychopath behind steel and the
teenage pickpocket behind a wooden door. Classification does not replace those walls, cells and locks —
it answers the question vanilla never does: **who belongs where.** It reads the one shared
`CriminalRecord` every module writes to and turns it into a single verdict, so the crime system, the
search, the escape and the classifier all agree on how dangerous a pawn is, because they read the same
number.

Grade drives everything downstream: search frequency, privileges, escape risk, and — critically —
parole eligibility ([Parole](Parole.md) gates on grade).

> The isolation *toll* of a max/solitary placement is Prisoner Realism's (good) sim. Justice only
> decides the placement.

---

## The tiers

`SecurityGrade` is four bands, low to high — the tiers players already build, named:

| Grade | Risk score | Reading |
|---|---|---|
| **Minimum** | `< 0.35` | Barely a disposition, clean record. Open dorm, light watch. |
| **Medium** | `0.35 – 0.79` | A real record or a real nature. Proper cell, routine search. The parole ceiling. |
| **Maximum** | `0.80 – 1.49` | Repeat offender or proven flight risk. Steel, solitary door, frequent search. |
| **Supermax** | `≥ 1.5` | The headline cases. Escapes plus crimes plus a dark nature. Never let them near a wall. |

Note the ceiling at **Medium**: [Parole](Parole.md) will only consider a pawn graded Medium or below.
Grade is therefore not just a placement hint — it is the gate a pawn has to fall back through before
they can be released.

---

## The risk score

Risk is a `0..~3` number: baseline disposition plus everything on the record, minus reform earned.

```
risk = Nature(pawn) * 0.5              // who they are, before they have done anything
     + escapeAttempts * 0.35          // a proven flight risk is the headline
     + crimesCommitted * 0.20
     + timesCaught     * 0.15
     + contrabandMade  * 0.10
     - max(0, reform)  * 0.4          // genuine reform earns a downgrade
risk = max(0, risk)                   // never negative
```

| Term | Weight | Why this weight |
|---|---|---|
| `Nature` (0..1) | `× 0.5` | Disposition alone can carry a pawn to Medium (Nature 0.7+), but never past it on its own. Character is a suspicion, not a conviction. |
| `escapeAttempts` | `× 0.35` | The heaviest per-event term. A pawn who *runs* is the one who ends up armed in your base. One attempt is worth nearly two crimes. |
| `crimesCommitted` | `× 0.20` | The staple. Steady, cumulative. |
| `timesCaught` | `× 0.15` | Caught contraband is worse than merely suspected. |
| `contrabandMade` | `× 0.10` | The lightest term — making a shiv is common; escaping with one is not. |
| `reform` (if > 0) | `− 0.4` | The only term that can *lower* the grade. At most −0.4 (reform capped at 1.0). |

Two facts fall out of the numbers, and both matter for how you play:

- **`timesSearched` is not in the formula.** Searching a pawn does not make them more dangerous —
  only *finding* something (`timesCaught`) does. Search freely; it costs the prisoner no grade.
- **Reform can shift at most 0.4 of risk.** At `reform = 1.0`, the downgrade is `−0.4`. So a pawn
  whose record *without reform* already totals `≥ 1.2` can never fall to Medium (`< 0.8`) no matter
  how thoroughly they reform — and therefore can **never be paroled**. A prolific offender is a
  life sentence. You will hold them, work them, or execute them; you will not release them. This is a
  deliberate property of the weights, not an accident.

---

## Worked example — grading a record

**Bram**, an Abrasive raider. Nature = `0.05 + 0.15 = 0.20`. He has three crimes, one escape attempt,
was caught twice, made two shivs, and has not been reformed (`reform = 0`).

```
risk = 0.20 * 0.5   = 0.100   (nature)
     + 1    * 0.35  = 0.350   (escape — the headline)
     + 3    * 0.20  = 0.600   (crimes)
     + 2    * 0.15  = 0.300   (caught)
     + 2    * 0.10  = 0.200   (contraband)
     - 0    * 0.4   = 0.000   (no reform)
                    ─────────
              total = 1.550   →  ≥ 1.5  →  SUPERMAX
```

Now treat him. Say patient handling and good conduct lift him to `reform = 0.40`:

```
risk = 1.550 - (0.40 * 0.4) = 1.550 - 0.160 = 1.390   →  MAXIMUM
```

He drops a band. But notice: his reform-less risk is `1.55`, well above `1.2`. Even at perfect
`reform = 1.0` he lands at `1.55 − 0.40 = 1.15` — still Maximum. **Bram is beyond parole for the rest
of his life.** His record decided that, not his disposition.

Contrast **Cass**, a Kind pickpocket. Nature = `clamp01(0.05 − 0.30) = 0`. One crime, caught once, no
escape, no contraband, `reform = 0`.

```
risk = 0 + 0 + (1*0.20) + (1*0.15) + 0 - 0 = 0.350   →  MEDIUM  (exactly on the line)
```

Give Cass the standard treatment to `reform = 0.30`:

```
risk = 0.350 - (0.30 * 0.4) = 0.350 - 0.120 = 0.230   →  MINIMUM
```

Cass is now Minimum, and — being Medium-or-below with `reform ≥ 0.30` — **paroleable**. Same
institution, two futures, and the record told you which was which before you had to guess.

---

## How to play with grades

- **Segregate by grade, not by vibe.** Sort your cells to the four bands and put a pawn where their
  score, not your hunch, says. The whole suite reads the record; you can too.
- **Escapes are the alarm.** One escape attempt (`+0.35`) will jump a middling pawn a band. If a pawn
  crosses into Maximum after a break attempt, believe it — treat them as the flight risk the number
  says they are.
- **A clean nature is not a clean record.** A Kind pawn who has escaped twice still grades Maximum;
  disposition is only half the score.
- **Watch the parole ceiling.** If you intend to release someone, keep their reform-less risk under
  `1.2` — mostly that means limiting how deep their record gets *before* you start treating them. A
  pawn you let rack up escapes and catches has sentenced themselves.
- **Reform is the only lever that lowers a grade.** See [Discipline & Reform](Discipline-and-Reform.md)
  for how to move it, and [Parole](Parole.md) for where the grade gate lands.

---

## For modders

```csharp
SecurityGrade grade = Classification.Grade(pawn);   // the verdict
float score         = Classification.Risk(pawn);    // the raw 0..~3 number
```

Both are pure reads — `Risk` uses `GameComponent_CriminalRecords.PeekFor` and never creates a record.
`SecurityGrade` is an ordered enum (`Minimum < Medium < Maximum < Supermax`), so `grade <= Medium`
comparisons work as written. The type lives in the `Contraband` namespace (Justice was extracted from
Institution: Contraband and kept the shared namespace).

---

*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Justice · Gangs. Developed
with substantial assistance from Claude (Anthropic).*