# V0.15 Scope Freeze

## Summary

`v0.15` is the materialized uniform translation orbit batch release.

Stable release theme:

> promote the first conservative user-facing data utility for materializing finite uniform translation orbits from canonical `FieldBatch` inputs.

Stable path:

`canonical scalar 1D periodic FieldBatch + finite uniform x-shifts -> materialized orbit FieldBatch + JSON-compatible provenance report`

This release turns the `v0.13` and `v0.14` diagnostic evidence into one narrow data utility.
It remains paper-agnostic and does not add train/test policy, split management, time translation, new PDEs, KS promotion, weak KS, broad adapters, operator APIs, or root exports.

---

## Stable Scope

`v0.15` adds one runtime public API and one runtime-only structured return under `pdelie.invariants`:

```python
pdelie.invariants.build_uniform_translation_orbit_batch(
    field,
    *,
    shifts,
    keep_source_index=True,
    keep_shift_index=True,
    source_field_id=None,
    copy=True,
) -> OrbitBatchResult

pdelie.invariants.OrbitBatchResult(
    field: FieldBatch,
    report: dict[str, Any],
)
```

`OrbitBatchResult` is not a canonical object.
It has no schema migration policy and no `.to_dict()` / `.from_dict()` contract.

The helper:

- supports canonical scalar 1D uniform periodic `FieldBatch` inputs only
- uses existing `InvariantApplier` uniform `x` translation
- returns a materialized `FieldBatch` plus a JSON-compatible provenance report
- mutates no inputs
- has no root `pdelie` export

---

## Materialization Semantics

Shift semantics:

- `shifts` must be a non-empty sequence of finite floats
- raw shift order is preserved
- duplicate shifts are preserved
- normalized shifts are recorded modulo the inferred periodic domain length

Batch semantics:

- materialization appends along the `batch` dimension
- output ordering is `shift_major`
- for each raw shift in input order, all source batch rows appear in original source-batch order
- output batch size is `source_batch_size * len(shifts)`

Provenance semantics:

- optional `source_field_id` is JSON-compatible provenance metadata only
- `source_field_id` is not a canonical identity system
- source batch indices are included when `keep_source_index=True`
- shift indices are included when `keep_shift_index=True`
- duplicate shifts remain traceable through shift indices and batch records
- output metadata records an `orbit_materialization` entry
- output preprocess log appends one aggregate `materialize_uniform_translation_orbit_batch` entry

Mask and copy semantics:

- `mask=None` remains `None`
- non-`None` masks are taken from transformed fields and concatenated along batch
- transformed values are always newly computed through `InvariantApplier`
- `copy=True` is the conservative default
- `copy=False` may avoid extra coordinate or mask copies where safe, but the helper still mutates no inputs

---

## Non-goals

`v0.15` explicitly does not include:

- train/test policy
- train/heldout split management
- heldout-leakage detection
- sparse-discovery branch policy
- private-paper augmentation recipes
- time-translation APIs
- no time-translation APIs are included in this release
- `axis="time"` support in `InvariantApplier`
- new PDE support
- stable KS generator promotion
- stable KS residual evaluator promotion
- weak KS
- broad dataset adapters
- PDEBench or The Well support
- multidimensional grids
- nonuniform grids
- multivariable systems
- operator-facing symmetry APIs
- root `pdelie` export expansion

---

## Milestones

### Milestone 0 - Scope Freeze

Freeze `v0.15` as materialized uniform translation orbit batches.

### Milestone 1 - API Semantics Freeze

Freeze API name, `OrbitBatchResult` status, batch ordering, provenance fields, mask behavior, metadata/preprocess composition, and copy semantics.

### Milestone 2 - Orbit Batch Implementation

Implement `pdelie.invariants.build_uniform_translation_orbit_batch(...)` and `pdelie.invariants.OrbitBatchResult`.
Document both in `API_STABILITY.md`.

### Milestone 3 - Compatibility And Diagnostics

Verify materialized Heat and KdV orbit batches remain valid `FieldBatch` objects and remain compatible with derivatives, residual evaluators, and reporting helpers.

### Milestone 4 - Example

Add `python -m pdelie.examples.translation_orbit_batch` and `pdelie.examples.run_translation_orbit_batch_example(...)`.

### Milestone 5 - API / Public-surface Audit

Confirm the new API remains submodule-only and no train/test policy, time translation, KS runtime, weak KS, broad adapter, or operator API landed.

### Milestone 6 - Release Gate and Readiness

Add `tests/test_v0_15_release_gate.py`, update CI, bump package metadata to `0.15.0`, and align release-facing docs.

---

## Release-gate Expectations

Expected gate coverage:

- `build_uniform_translation_orbit_batch(...)` is documented and submodule-only
- `OrbitBatchResult` is documented and submodule-only
- representative Heat and KdV orbit batches validate as `FieldBatch` objects
- output batch shape follows shift-major ordering
- duplicate shifts are preserved
- source/shift provenance is traceable
- residual diagnostics remain finite on representative materialized batches
- root `pdelie` remains unchanged
- no train/test policy, time translation, KS runtime, weak KS, broad adapter, or operator API lands
- current CI uses `v0_15-release-gate` plus full editable tests and package smoke

---

## Status

- Milestone 0: COMPLETE
- Milestone 1: COMPLETE
- Milestone 2: COMPLETE
- Milestone 3: COMPLETE
- Milestone 4: COMPLETE
- Milestone 5: COMPLETE
- Milestone 6: COMPLETE