# Reproducibility Protocol for Hardened Labels v0.1 — UNNS-H Mode Project

## 1. Purpose

This document explains how to independently reproduce the conservative hardened-label file used in the UNNS-H Mode physical-window hardening stage.

It belongs here:

```text
unns_hmode_project/
  docs/
    31A_REPRODUCIBILITY_PROTOCOL_HARDENED_LABELS.md
```

It accompanies:

```text
components/
  reproduce_hardened_v0_1_from_review.py
```

The goal is reproducibility of the **label-hardening artifact**, not proof of H-mode.

---

## 2. What is being reproduced

The reproducible output is:

```text
outputs/reports/
  tokamark_physical_window_labels_HARDENED_v0_1.csv
```

from this input:

```text
outputs/reports/
  tokamark_physical_window_labels_HARDENING_REVIEW.csv
```

The output is generated by a deterministic conservative rule.

---

## 3. What is not being reproduced

This protocol does not reproduce an independent physical validation of H-mode.

It does not replace expert plasma-physics review.

It does not prove that the accepted windows are final regime labels.

It only reproduces the conservative hardening decision that was applied to the review CSV.

Independent physical reproduction requires a separate reviewer to inspect the diagnostic traces and assign labels without using the UNNS audit columns.

---

## 4. Required files

From project root, the following input must exist:

```text
outputs/reports/
  tokamark_physical_window_labels_HARDENING_REVIEW.csv
```

The script must be placed here:

```text
components/
  reproduce_hardened_v0_1_from_review.py
```

Optional but useful for audit:

```text
outputs/reports/
  tokamark_physical_window_labels_HARDENING_REVIEW.md
  tokamark_physical_window_labels_HARDENING_REVIEW_summary.json
```

---

## 5. Deterministic conservative rule

Apply the following rule to every row in the hardening review CSV.

### 5.1 Accept only L-mode and L-H transition rows already marked ACCEPT

A row is validation-eligible only if:

```text
original_label_type ∈ {L_MODE, LH_TRANSITION}
review_decision = ACCEPT
```

For those rows:

```text
hardened_label_type = original_label_type
label_type = original_label_type
review_decision = ACCEPT
excluded_from_validation = False
```

For `LH_TRANSITION`, assign:

```text
hardening_level = 1_PLAUSIBLE
```

For `L_MODE`, preserve `1_PLAUSIBLE` if already present; otherwise keep:

```text
hardening_level = 0_PROVISIONAL
```

### 5.2 Keep H-mode-stable rows excluded

For every row where:

```text
original_label_type = H_MODE_STABLE
```

set:

```text
hardened_label_type = H_MODE_STABLE
label_type = H_MODE_STABLE
hardening_level = 0_PROVISIONAL
review_decision = NEEDS_EXTERNAL_REFERENCE
excluded_from_validation = True
```

and use this exclusion reason:

```text
H_MODE_STABLE not hardened: requires independent confirmation from D-alpha/profile/soft-X or external timing; not accepted from post-transition quiet interval alone
```

### 5.3 Keep ambiguous rows excluded

For every row where:

```text
original_label_type = AMBIGUOUS
```

or:

```text
review_decision = KEEP_AMBIGUOUS
```

set:

```text
hardened_label_type = AMBIGUOUS
label_type = AMBIGUOUS
hardening_level = 0_PROVISIONAL
review_decision = KEEP_AMBIGUOUS
excluded_from_validation = True
```

### 5.4 Keep unlabelable rows excluded

For every row where:

```text
original_label_type = UNLABELABLE
```

or:

```text
review_decision = KEEP_UNLABELABLE
```

set:

```text
hardened_label_type = UNLABELABLE
label_type = UNLABELABLE
hardening_level = 0_PROVISIONAL
review_decision = KEEP_UNLABELABLE
excluded_from_validation = True
```

### 5.5 Fail closed

Any unexpected row is excluded from validation.

This prevents accidental strengthening of the result through unknown labels or malformed review decisions.

---

## 6. Strict non-circularity rule

The following columns must not be used to accept or reject a physical label:

```text
m_edge_conf_median_AUDIT_ONLY
conf_positive_fraction_AUDIT_ONLY
conf_negative_fraction_AUDIT_ONLY
```

These fields are preserved only so the hardened labels can later be compared against the UNNS margin.

The hardening rule must be based on:

```text
original_label_type
review_decision
hardening_level
independent diagnostic evidence fields
exclusion status
```

not on UNNS performance.

---

## 7. Reproduction command

From project root, run:

```powershell
python components\reproduce_hardened_v0_1_from_review.py ^
  --review outputs\reports\tokamark_physical_window_labels_HARDENING_REVIEW.csv ^
  --out-dir outputs\reports
```

Expected outputs:

```text
outputs/reports/
  tokamark_physical_window_labels_HARDENED_v0_1.csv
  tokamark_physical_window_labels_HARDENED_v0_1_summary.json
  tokamark_physical_window_labels_HARDENED_v0_1_SUMMARY.md
```

The script also prints SHA256 hashes for the input and output CSV files.

---

## 8. Expected counts

For the current hardening review file, the expected output counts are:

```text
rows: 89
shots: 8
eligible rows: 12
```

Expected label counts:

```text
AMBIGUOUS:      54
UNLABELABLE:    18
L_MODE:          6
LH_TRANSITION:   6
H_MODE_STABLE:   5
```

Expected validation-eligible label counts:

```text
L_MODE:        6
LH_TRANSITION: 6
```

Expected excluded rows:

```text
77
```

Expected included rows:

```text
12
```

---

## 9. How to verify reproduction

After running the script, verify:

```text
outputs/reports/tokamark_physical_window_labels_HARDENED_v0_1_summary.json
```

contains:

```text
eligible_rows = 12
eligible_label_counts = {'L_MODE': 6, 'LH_TRANSITION': 6}
```

Then run the analyzer:

```powershell
python components\tokamark_physical_window_label_analyzer.py ^
  --labels outputs\reports\tokamark_physical_window_labels_HARDENED_v0_1.csv ^
  --out-dir outputs\reports ^
  --prefix tokamark_physical_window_label_analysis_HARDENED_v0_1
```

This should produce:

```text
outputs/reports/
  tokamark_physical_window_label_analysis_HARDENED_v0_1.csv
  tokamark_physical_window_label_analysis_HARDENED_v0_1_by_label.csv
  tokamark_physical_window_label_analysis_HARDENED_v0_1_transition_pairs.csv
  tokamark_physical_window_label_analysis_HARDENED_v0_1.json
  tokamark_physical_window_label_analysis_HARDENED_v0_1.md
```

---

## 10. Expected scientific consequence

Because the conservative rule keeps all `H_MODE_STABLE` rows excluded, the hardened analyzer run should not reproduce the earlier first-gate result:

```text
H_MODE_STABLE > L_MODE
```

That is expected.

The hardening pass intentionally says:

```text
we do not yet have enough independent support to keep H_MODE_STABLE as validation evidence
```

Therefore, if the hardened analysis weakens or fails the physical-window alignment gate, that is an honest and reproducible result, not a pipeline failure.

---

## 11. Independent physical reproduction

A stronger independent reproduction would require a separate reviewer to:

```text
1. Start from the raw TokaMark shot data.
2. Generate the same diagnostic preview files.
3. Inspect D-alpha, profile-gradient, soft-X, power, and density evidence.
4. Assign physical labels without looking at m_edge_conf.
5. Save their own hardened labels.
6. Run the analyzer.
7. Compare whether their independently hardened labels align with m_edge_conf.
```

This protocol does not complete that external review. It only makes the present conservative hardening decision reproducible.

---

## 12. Next report

After reproducing the hardened file and running the hardened analyzer, write:

```text
docs/
  31_PHYSICAL_WINDOW_LABEL_HARDENING_RESULTS.md
```

That report should distinguish between:

```text
artifact reproducibility
```

and:

```text
independent physical validation
```

The current script supports the first. The second requires external/manual physical review.
