# V0.9 Scope Freeze

## Summary

`v0.9` is the stable normalized periodic KdV strong-path release for `pdelie`.

Its purpose is:

> promote the existing tests-first KdV feasibility slice into a narrow stable runtime path for normalized, periodic, short-horizon KdV data.

Stable release definition:

`canonical scalar 1D uniform periodic FieldBatch -> spectral_fd with u_xxx -> normalized KdV residual evaluator -> translation fit/verification`

`v0.9` is not general KdV support.
It is a controlled strong-form path for the existing scalar 1D periodic regime.

---

## Stable Scope

Stable `v0.9` scope is limited to:

- `compute_spectral_fd_derivatives(..., max_spatial_order=...)` through spatial order 3
- `pdelie.data.generate_kdv_1d_field_batch(...)`
- `pdelie.residuals.KdVResidualEvaluator`
- canonical scalar 1D uniform periodic `FieldBatch` inputs
- normalized periodic KdV only
- short-horizon synthetic KdV generation under the frozen default regime
- translation fitting and held-out verification through the existing polynomial translation stack

Stable `v0.9` does not add root exports.
The new runtime APIs live under their existing submodules.

---

## Exact Public API Contracts

### Derivatives

Planned stable derivative API:

```python
compute_spectral_fd_derivatives(
    field: FieldBatch,
    *,
    max_spatial_order: int = 2,
) -> DerivativeBatch
```

Frozen order behavior:

- `max_spatial_order=1` emits derivative keys `u_t` and `u_x`
- `max_spatial_order=2` emits exactly the existing default derivative keys `u_t`, `u_x`, and `u_xx`
- `max_spatial_order=3` emits `u_t`, `u_x`, `u_xx`, and `u_xxx`
- unsupported orders raise `ScopeValidationError`

Backward-compatibility rule:

- default `max_spatial_order=2` preserves the `v0.8` derivative arrays and stable behavior
- default config and diagnostics should remain unchanged unless implementation requires a documented versioned addition

### KdV Data

Planned stable generator API:

```python
generate_kdv_1d_field_batch(
    *,
    batch_size: int = 2,
    num_times: int = 17,
    num_points: int = 64,
    max_time: float = 0.03,
    num_modes: int = 3,
    amplitude: float = 0.08,
    seed: int = 0,
    num_substeps: int = 8,
    domain_length: float = 2 * pi,
) -> FieldBatch
```

Frozen generator policy:

- no `dtype` parameter in `v0.9`
- no custom initial conditions in `v0.9`
- generated data uses dims `("batch", "time", "x", "var")`
- generated data uses `var_names = ["u"]`
- generated metadata includes `parameter_tags = {"equation": "kdv_normalized"}`
- generated metadata keeps periodic `x`, cartesian coordinates, rectilinear grid type, and uniform grid regularity

### KdV Residual

Planned stable residual evaluator API:

```python
KdVResidualEvaluator().evaluate(
    field: FieldBatch,
    derivatives: DerivativeBatch | None = None,
) -> ResidualBatch
```

Frozen residual contract:

- equation: `u_t + 6*u*u_x + u_xxx = 0`
- residual form: `u_t + 6*u*u_x + u_xxx`
- if derivatives are omitted, the evaluator computes `compute_spectral_fd_derivatives(field, max_spatial_order=3)`
- if derivatives are supplied, the evaluator requires `u_t`, `u_x`, and `u_xxx`
- output uses `ResidualBatch(definition_type="analytic", normalization="none")`
- diagnostics include `equation`, `backend`, `max_abs_residual`, and `rms_residual`

The `definition_type="analytic"` label means formula-defined strong-form residual using numerical derivatives, matching the existing Heat/Burgers residual convention.
It does not mean an exact closed-form solution residual.

---

## KdV Equation and Numerical Regime

Frozen KdV equation:

```text
u_t + 6*u*u_x + u_xxx = 0
```

Frozen stable regime:

- normalized coefficient form only
- scalar `u` only
- one spatial dimension `x`
- uniform periodic rectilinear grid
- short time horizon
- synthetic Fourier-mode initial conditions generated by the runtime generator
- spectral spatial derivatives
- finite-difference time derivative

The stable numerical guarantee covers the frozen default short-horizon regime and the release-gate fixtures.
Accepted parameters outside the release-guaranteed regime may produce valid `FieldBatch` objects, but they are not promised to satisfy release-gate numerical thresholds.

---

## Generator Parameter Validation

The KdV generator must reject invalid parameters with typed validation errors.

Frozen validation rules:

- `batch_size` must be a positive integer
- `num_times` must be an integer with `num_times >= 3`
- `num_points` must be an integer with `num_points >= 16`
- `max_time` must be finite and positive
- `num_modes` must be an integer with `num_modes >= 1`
- `num_modes <= floor(num_points / 3)`
- `amplitude` must be finite and nonnegative
- `seed` must be an integer
- `num_substeps` must be a positive integer
- `domain_length` must be finite and positive

Frozen release-guaranteed regime:

- default generator parameters
- `max_time <= 0.03`
- `amplitude <= 0.08`
- `num_modes <= 3`
- `num_substeps >= 8`
- `num_points >= 64`
- `num_times >= 17`

The function may accept parameters outside the release-guaranteed regime if they pass validation.
Those accepted-outside-guarantee parameters are user-risk in `v0.9`.

---

## Release Fixtures and Thresholds

Frozen KdV vertical-slice fixture:

- generator seed: `9001`
- `batch_size = 5`
- `train_size = 2`
- train/heldout split seed: `9002`
- all other generator settings use the frozen defaults

Frozen release-gate thresholds:

- KdV residual max absolute value `< 1e-2`
- KdV residual RMS value `< 2e-3`
- translation span distance `<= 5e-2`
- first-epsilon held-out verification error `< 1e-4`
- held-out verification classification is not `failed`
- mass drift `<= 1e-8`
- relative L2 drift `<= 5e-3`

These thresholds gate the stable release fixture.
They are not general mathematical guarantees for arbitrary accepted KdV generator parameters.

---

## Scope Limits

Stable `v0.9` scope is limited to:

- canonical `FieldBatch` only
- dims exactly `("batch", "time", "x", "var")`
- scalar `var` only
- finite unmasked values only
- uniform time only
- uniform periodic rectilinear `x` only
- normalized periodic KdV only
- synthetic short-horizon KdV data only
- polynomial translation generator fitting and verification only

---

## Explicit Non-goals

Out of stable `v0.9` scope:

- no weak KdV API
- no weak derivative API expansion
- no KdV weak residual reports
- no root `pdelie` exports for KdV APIs
- no custom KdV initial-condition API
- no variable-coefficient KdV
- no broad KdV stability guarantee outside the frozen release fixtures
- no multidimensional grids
- no multivariable systems
- no nonuniform-grid support
- no PDEBench or The Well adapters
- no broad dataset adapter expansion
- no operator-method expansion
- no new canonical object

---

## Milestones

Planned `v0.9` sequence:

- Milestone 0 - KdV strong-path scope freeze
- Milestone 1 - spectral `u_xxx`
- Milestone 2 - KdV generator
- Milestone 3 - KdV residual evaluator
- Milestone 4 - KdV vertical slice
- Milestone 5 - imported parity and non-goal guards
- Milestone 6 - release gate and release readiness

`API_STABILITY.md` is updated as public APIs land:

- Milestone 1 updates it for the derivative API change
- Milestone 2 updates it for the KdV generator
- Milestone 3 updates it for the KdV residual evaluator
- Milestone 6 only aligns final release-facing docs