docs: align repaired 4-knob environment docs

docs/FUSION_DELIVERABLES_MAP.md

@@ -13,7 +13,7 @@ Use this map to sequence execution, not to reopen already-locked task choices.
 - [x] baseline comparison has been rerun on the real verifier path
 - [x] Northflank smoke workflow and note are committed
 - [x] Northflank smoke test has passed on the team H100
-- [x] current 3-knob family has been verified as blocked on P1 triangularity
+- [x] historical upstream 3-knob family has been verified as blocked on P1 triangularity
 - [x] repaired low-dimensional boundary builder is implemented
 - [x] explicit VMEC failure semantics are implemented
 - [x] low-fi `run` truth vs high-fi `submit` truth is labeled clearly

docs/FUSION_DESIGN_LAB_PLAN_V2.md

@@ -14,7 +14,7 @@
 - [x] baseline comparison has been rerun on the real verifier path
 - [x] Northflank smoke workflow and note are committed
 - [x] Northflank smoke test has passed on the team H100
-- [x] current 3-knob family has been checked against the real low-fidelity verifier
+- [x] historical upstream 3-knob family has been checked against the real low-fidelity verifier
 - [x] parameterization repair is implemented so triangularity is controllable
 - [x] explicit VMEC failure semantics are implemented
 - [x] low-fi `run` truth vs high-fi `submit` truth is labeled clearly in the environment surface
@@ -181,7 +181,7 @@ Allowed reuse:
 
 Implementation handoff:
 
-- the remaining work is now parameterization repair, then fixture coverage, manual playtesting, heuristic refresh, smoke validation, and deployment
+- the remaining work is now fixture coverage, manual playtesting, heuristic refresh, smoke validation, and deployment
 - do not treat supporting decision notes as a new planning backlog
 
 ## 8.1 Compute Surfaces
@@ -221,11 +221,11 @@ Auth stance:
 
 The environment contract must be frozen before meaningful evaluation.
 
-Current verified blocker:
+Historical blocker that drove the repair:
 
-- the current upstream 3-knob `generate_rotating_ellipse(aspect_ratio, elongation, rotational_transform, n_field_periods)` family does not expose triangularity control
+- the upstream 3-knob `generate_rotating_ellipse(aspect_ratio, elongation, rotational_transform, n_field_periods)` family does not expose triangularity control
 - on the real low-fidelity verifier path, sampled points stayed at roughly `average_triangularity=+0.004975` and `p1_feasibility=1.00995`
-- so the next contract revision must repair parameterization before reward iteration becomes meaningful
+- that blocker is why the repo now uses a repaired 4-knob low-dimensional family with explicit `triangularity_scale`
 
 ### Observation
 
@@ -235,20 +235,27 @@ The observation should expose:
 - current aspect ratio
 - current average triangularity
 - current edge rotational transform over field periods
-- current feasibility score or normalized violation summary
-- best-so-far feasible score
-- best-so-far least-violating design summary
-- step number
-- budget remaining
-- concise textual summary of the last action outcome
+- current `p1_score`
+- current `p1_feasibility`
+- current `constraints_satisfied`
+- current `vacuum_well`
+- `evaluation_fidelity`
+- `evaluation_failed`
+- `failure_reason`
+- `step_number`
+- `budget_remaining`
+- `best_score`
+- `best_feasibility`
+- `target_spec`
+- concise textual summary of the last action outcome in `diagnostics_text`
 
 The observation must be interpretable by a human without additional hidden state.
 
 ### Action Space
 
-The action space stays intentionally small and discrete, but the current 3-knob version is no longer enough. The next contract revision should keep low-dimensional actions while adding an explicit control that can move triangularity.
+The live action space stays intentionally small and discrete while exposing the repaired 4-knob low-dimensional family.
 
-Near-term target:
+Current contract:
 
 - `run`
 - `submit`
@@ -260,11 +267,11 @@ For `run`, the controllable fields are:
   - `aspect_ratio`
   - `elongation`
   - `rotational_transform`
-  - `triangularity_scale` or equivalent low-dimensional triangularity control
+  - `triangularity_scale`
 - direction: increase or decrease
 - magnitude: small, medium, large
 
-This is not trying to expose the full Fourier-boundary space. The goal is a legible environment, not maximal realism. The verifier should stay official; the custom logic belongs in the low-dimensional boundary builder, not in reward semantics.
+This is not trying to expose the full Fourier-boundary space. The goal is a legible environment, not maximal realism. The verifier stays official; the custom logic belongs in the low-dimensional boundary builder, not in reward semantics.
 
 ### Episode Flow
 
@@ -530,7 +537,7 @@ The repo should make the environment easy to understand:
 
 - notebook starts on the team H100
 - persistent storage mount is usable
-- smoke test artifact is written successfully
+- smoke test artifact is written successfully from the rotating-ellipse-derived low-dimensional boundary path
 - latest artifact example: `/home/jovyan/fusion-design-lab/smoke/northflank_smoke_20260308T023646Z.json`
 
 ### Gate 1: Environment Contract Locked

docs/FUSION_NEXT_12_HOURS_CHECKLIST.md

@@ -16,7 +16,7 @@ Do not expand scope beyond one stable task. Training is supporting evidence, not
 - [x] re-run baselines on the real verifier path
 - [x] commit the Northflank smoke workflow and note
 - [x] pass the Northflank smoke test on the team H100
-- [x] verify that the current 3-knob family is blocked on P1 triangularity under the real verifier path
+- [x] verify that the historical upstream 3-knob family is blocked on P1 triangularity under the real verifier path
 - [x] repair the low-dimensional parameterization
 - [x] add explicit VMEC failure semantics
 - [x] label low-fi `run` truth vs high-fi `submit` truth in the task surface
@@ -50,7 +50,7 @@ Carry these rules through the whole checklist:
 2. Attach persistent storage before relying on saved models, caches, or fixture downloads.
 3. Preserve the concrete smoke-test evidence:
    - import `constellaration`
-   - generate one rotating-ellipse boundary
+   - generate one rotating-ellipse-derived low-dimensional boundary
    - run one low-fidelity verifier call
    - keep one artifact in persistent storage
    - current artifact: `/home/jovyan/fusion-design-lab/smoke/northflank_smoke_20260308T023646Z.json`

docs/P1_ENV_CONTRACT_V1.md

@@ -15,16 +15,18 @@ This file captures the technical contract that should drive the next code change
 
 The central change is now explicit:
 
-- the current upstream 3-knob rotating-ellipse family is blocked on P1 triangularity under the real verifier path
-- the next environment contract must repair parameterization before more reward iteration or heuristic work
+- the historical upstream 3-knob rotating-ellipse family is blocked on P1 triangularity under the real verifier path
+- that blocker drove the repair to the current 4-knob low-dimensional runtime
 - the runtime now exposes the repaired 4-knob target, but measured sweep validation and fixture calibration are still pending
 
-## Verified Blocker
+## Historical Blocker
+
+This section records the resolved upstream blocker that motivated the current repair. It is not the live runtime state.
 
 Current verified facts:
 
 - upstream `generate_rotating_ellipse(aspect_ratio, elongation, rotational_transform, n_field_periods)` has no triangularity control
-- the current 3-knob environment directly exposes only:
+- the historical 3-knob environment directly exposed only:
   - `aspect_ratio`
   - `elongation`
   - `rotational_transform`
@@ -35,8 +37,8 @@ Current verified facts:
 
 Conclusion:
 
-- the current 3-knob family is not a meaningful playtest or baseline environment for `P1`
-- reward work is secondary until the boundary family can actually approach the official triangularity constraint
+- the historical 3-knob family was not a meaningful playtest or baseline environment for `P1`
+- the live runtime therefore moved to a repaired boundary family before further reward iteration
 
 ## Design Split
 
@@ -66,12 +68,16 @@ Current repo state:
 - explicit failure results are returned when VMEC evaluation fails
 - measured sweep validation is still pending
 
-Target functions:
+Current live functions:
 
-- `build_initial_boundary(...) -> SurfaceRZFourier`
-- `apply_low_dim_perturbation(...) -> SurfaceRZFourier`
+- `build_boundary_from_params(...) -> SurfaceRZFourier`
 - `evaluate_boundary(boundary, fidelity) -> EvaluationMetrics`
 
+Current layering note:
+
+- discrete perturbation application lives in `server/environment.py`
+- there is no separate `apply_low_dim_perturbation(...)` helper in the live code
+
 The verifier layer should own:
 
 - low-fidelity step-time evaluation
@@ -147,9 +153,16 @@ Keep:
 - `edge_iota_over_nfp`
 - `p1_feasibility`
 - `p1_score`
+- `constraints_satisfied`
+- `vacuum_well`
+- `evaluation_fidelity`
+- `evaluation_failed`
+- `failure_reason`
+- `step_number`
 - `budget_remaining`
 - `best_score`
 - `best_feasibility`
+- `target_spec`
 - `diagnostics_text`
 
 Add clarity about fidelity:

docs/PIVOT_P1_ROTATING_ELLIPSE.md

@@ -9,17 +9,17 @@ Use this file as rationale for the pivot, not as a fresh planning queue. Once th
 ## Current Branch Status
 
 - [x] pivot accepted
-- [x] 3-knob rotating-ellipse `P1` contract is implemented
+- [x] historical upstream 3-knob rotating-ellipse `P1` contract was implemented and evaluated
 - [x] `constellaration` verifier path is wired
-- [x] current 3-knob family is verified as blocked on P1 triangularity
-- [ ] repaired low-dimensional family with explicit triangularity control is implemented
+- [x] historical upstream 3-knob family is verified as blocked on P1 triangularity
+- [x] repaired low-dimensional family with explicit triangularity control is implemented
 - [ ] tracked fixtures are added
 - [ ] manual playtest evidence is recorded
 - [ ] heuristic baseline is refreshed for the real verifier path
 
 Current caution:
 
-- the current upstream rotating-ellipse family is useful as a seed generator, but not sufficient as the full environment action family because it does not move triangularity under the real verifier path
+- the upstream rotating-ellipse family remains useful as a seed generator, but the live environment action family is the repaired rotating-ellipse-derived 4-knob contract
 
 ## Decision
 
@@ -52,7 +52,7 @@ This borrows the strongest low-dimensional entry point from the proven winning a
 
 ### Single Task
 
-Improve a stellarator boundary's P1 score using the rotating-ellipse parameterization under the official ConStellaration P1 constraints.
+Improve a stellarator boundary's P1 score using a rotating-ellipse-derived low-dimensional parameterization under the official ConStellaration P1 constraints.
 
 ### P1 Constraints (from `GeometricalProblem`)
 
@@ -68,7 +68,7 @@ Feasibility tolerance: normalized constraint violations <= 1% (0.01).
 
 ### Parameter Space
 
-The upstream rotating-ellipse generator takes 3 continuous parameters + 1 discrete:
+Historical upstream seed generator:
 
 | Parameter | Role | Typical range |
 |---|---|---|
@@ -79,36 +79,43 @@ The upstream rotating-ellipse generator takes 3 continuous parameters + 1 discre
 
 These map to `constellaration.initial_guess.generate_rotating_ellipse(aspect_ratio, elongation, rotational_transform, n_field_periods)` which returns a `SurfaceRZFourier` boundary in ~4ms.
 
-Verified blocker:
+Historical blocker:
 
 - on the real low-fidelity verifier path, sampled 3-knob points kept `average_triangularity` at roughly `+0.004975`
 - sampled `p1_feasibility` stayed at roughly `1.00995`
 - no sampled point was feasible
 
-So the hackathon environment now needs a custom low-dimensional boundary family on top of the rotating-ellipse seed, with an explicit triangularity control knob or equivalent mechanism.
+Current live environment family:
+
+| Parameter | Role | Current implementation range |
+|---|---|---|
+| `aspect_ratio` | Width-to-height ratio of the repaired boundary | 3.2 - 3.8 |
+| `elongation` | Vertical stretching of cross-section | 1.2 - 1.8 |
+| `rotational_transform` | Magnetic field line winding | 1.2 - 1.9 |
+| `triangularity_scale` | Explicit triangularity control | 0.4 - 0.7 |
+| `n_field_periods` | Fixed at 3 (not an action) | 3 |
+
+These ranges describe the live implementation in `server/environment.py`. They are still subject to measured sweep and playtest refinement.
 
 ### Action Space
 
-Original 3-knob action space:
+Current action space:
 
 ```
 intent: "run" | "submit" | "restore_best"
-operator: "aspect_ratio" | "elongation" | "rotational_transform"
+parameter: "aspect_ratio" | "elongation" | "rotational_transform" | "triangularity_scale"
 direction: "increase" | "decrease"
 magnitude: "small" | "medium" | "large"
 ```
 
-This is no longer sufficient on its own. The next contract revision should keep the same discrete structure while adding:
-
-- `triangularity_scale` or equivalent low-dimensional control
-
-Magnitude deltas (to be tuned by playtest):
+Current implementation deltas:
 
 | Parameter | small | medium | large |
 |---|---|---|---|
-| aspect_ratio | 0.1 | 0.3 | 0.8 |
-| elongation | 0.1 | 0.3 | 0.8 |
-| rotational_transform | 0.02 | 0.05 | 0.15 |
+| aspect_ratio | 0.05 | 0.10 | 0.20 |
+| elongation | 0.05 | 0.10 | 0.20 |
+| rotational_transform | 0.05 | 0.10 | 0.20 |
+| triangularity_scale | 0.02 | 0.05 | 0.10 |
 
 ### Episode Flow
 
@@ -135,15 +142,19 @@ p1_score: float                # current step-time score
 p1_feasibility: float          # current step-time max normalized constraint violation
 constraints_satisfied: bool    # feasibility <= 0.01
 vacuum_well: float             # stability indicator
+evaluation_fidelity: "low" | "high"
+evaluation_failed: bool
+failure_reason: str
 step_number: int
 budget_remaining: int
 best_score: float
+best_feasibility: float
 target_spec: str
 ```
 
-Follow-up requirement from the verified blocker:
+Current requirement:
 
-- once submit stays high-fidelity, the observation or diagnostics text should make the low-fi vs high-fi distinction explicit
+- the observation and diagnostics text should make the low-fi vs high-fi distinction explicit
 
 ### Reward V0
 
@@ -170,10 +181,10 @@ submit penalty (if infeasible or no improvement):
 
 This puts feasibility first. An agent that achieves feasibility then minimizes elongation gets rewarded. An agent that never reaches feasibility gets penalized.
 
-Execution note after the verified blocker:
+Current execution note:
 
 - keep reward mostly scalar and verifier-driven
-- repair parameterization before further reward tuning
+- keep parameterization repair and reward semantics separate
 - do not add mode- or constraint-specific reward hacks to compensate for a blocked action family
 
 ### State
@@ -192,7 +203,7 @@ history: list[str]
 
 | | Rotating-ellipse env | Curated-seed Fourier-repair env |
 |---|---|---|
-| Action space | 3 parameters (AR, elongation, iota) | N Fourier modes |
+| Action space | 4 parameters (AR, elongation, rotational transform, triangularity scale) | N Fourier modes |
 | Starting point | Generated from parameters | Frozen from HF dataset |
 | Interpretability | High — parameters map to physical shape | Lower — mode perturbations are abstract |
 | Dataset dependency | None at runtime | Requires offline curation |
@@ -230,7 +241,7 @@ Update `fusion_lab/models.py` for new schemas.
 
 Status: open.
 
-Validate hypothesis: "6 actions is enough" only after parameterization repair.
+Validate hypothesis: "6 actions is enough" on the repaired low-dimensional family.
 - Play 5-10 episodes manually
 - Log: can a human reach feasibility? Improve elongation?
 - Tune magnitude deltas if needed
@@ -264,11 +275,12 @@ If full high-fidelity `constellaration` deployment fails (Docker build, HF Space
 
 ## Known-Good Fixtures
 
-Start with 1-2 rotating-ellipse configurations for sanity checks and expand only if the implementation needs more coverage:
+Start with the frozen repaired-family reset seeds in `server/contract.py` and expand only if the implementation needs more coverage:
 
-1. **Current default baseline reference:** aspect_ratio=3.5, elongation=1.5, rotational_transform=0.4 — currently deeply infeasible on the real verifier path; keep as a negative reference only until parameterization repair lands
-2. **Infeasible reference:** aspect_ratio=5.0, elongation=3.0, rotational_transform=0.2 — expected to violate constraints
-3. **Near-boundary anchor:** still needs to be found after parameterization repair and real verifier probing before manual playtesting
+1. **Reset seed:** aspect_ratio=3.6, elongation=1.4, rotational_transform=1.5, triangularity_scale=0.55
+2. **Reset seed:** aspect_ratio=3.4, elongation=1.4, rotational_transform=1.6, triangularity_scale=0.55
+3. **Reset seed:** aspect_ratio=3.8, elongation=1.4, rotational_transform=1.5, triangularity_scale=0.55
+4. **Deliberately bad reference:** keep a clearly infeasible boundary only as a negative verifier/reward sanity check
 
 These are for verifier/reward sanity, not a prerequisite seed-mining project.