# DiscoveryTaskResult — Design Document

**Status:** DESIGN-FROZEN in v0.31a; **RUNTIME IMPLEMENTED in v0.31b1** for `target_convention="pde_library"`; **WeakPDELibrary diagnostic wrapper RUNTIME IMPLEMENTED in v0.31b2 as a SEPARATE summary type (`pdelie_weak_pde_library_diagnostic`)**, not as a `discovery_task_result` variant.

This document defines the composed `TaskResult` artifact returned by the `pdelie.tasks.discovery` submodule when a caller runs a PySINDy-backed PDE discovery task over a canonical scalar 1D PDELie input. It is normative for v0.31 proper.

## Motivation

The existing downstream-discovery surface consists of three narrow, disconnected pieces:

- `pdelie.discovery.to_pysindy_trajectories` — flattens a periodic scalar 1D `FieldBatch` into PySINDy-shape trajectories (`src/pdelie/discovery/pysindy_bridge.py`)
- `pdelie.discovery.fit_pysindy_discovery(config=None)` — runs a *default* PySINDy fit over the bridge output and refuses non-default configs (`src/pdelie/discovery/pysindy_adapter.py:196-204`)
- `pdelie.discovery.summarize_discovery_result` — normalizes a backend-native discovery-result dict into a JSON-compatible summary (`src/pdelie/discovery/contracts.py:305-409`)

A user who wants to run a `PDELibrary`-backed PDE discovery over their canonical data currently has to build the bridge, hand-configure PySINDy, run the fit outside PDELie, and then re-enter the reporting layer through `summarize_discovery_result`. The task bridge composes these three pieces into one call and produces a single stable JSON-compatible artifact that carries backend provenance, recovery metrics, and residuals side-by-side.

### Why a new schema

`summarize_discovery_result` is a stable v0.22 surface. It is intentionally *backend-native*: it wraps any dict shaped like PySINDy's output. It does not carry backend versions, does not carry input-layout provenance, does not carry a `weak_contract` block, and does not enforce strict-JSON (`allow_nan=False`). The task-bridge output needs all four of these, and it needs to compose cleanly with `summarize_discovery_result` as a sibling embedded payload rather than replacing it.

## Proposed schema

`TaskResult` is the return type of the (design-only) `pdelie.tasks.discovery.run_pysindy_pde_task(...)` runtime API. Its stable serialized form is:

```
{
    "summary_schema_version": "0.1",
    "summary_type": "discovery_task_result",
    "task_name": str,
    "backend_name": Literal["pysindy"],
    "backend_version": dict[str, str],
    "target_convention": Literal["pde_library", "weak_pde_library"],
    "derivative_backend": str,
    "input_layout": Literal["scalar_1d_uniform"],
    "library_feature_names": list[str],
    "selected_terms": dict[str, dict[str, float]],
    "coefficients": dict | None,
    "support_precision": float,
    "support_recall": float,
    "support_f1": float,
    "exact_support": bool,
    "coefficient_relative_l2": float,
    "train_residual": dict | None,
    "heldout_residual": dict | None,
    "weak_contract": dict | None,
    "warnings": list[str],
    "pysindy_bridge_variant": Literal["periodic_only_v1"],
    "underlying_discovery_result": dict,
}
```

### Field semantics

- `summary_schema_version` — literal `"0.1"`.
- `summary_type` — literal `"discovery_task_result"`.
- `task_name` — caller-supplied non-empty string identifying the task instance for provenance and logging.
- `backend_name` — `Literal["pysindy"]` in v0.31. Expansion of the Literal set (e.g. to `"pysr"`) is a `v0.32+` concern.
- `backend_version` — dict with required keys `pysindy`, `sklearn`, and `pdelie`. Values are version strings (`importlib.metadata.version(...)`).
- `target_convention` — `Literal["pde_library", "weak_pde_library"]`. Selects between the strong PySINDy `PDELibrary` bridge and the `WeakPDELibrary` diagnostic wrapper.
- `derivative_backend` — string promoted from `fit_config["pysindy_model"]["differentiation_method"]`. This is the PySINDy-side identifier (e.g. `"FiniteDifference"`, `"SmoothedFiniteDifference"`, or `"SpectralDerivative"`). The v0.30c PDELie-side `spectral_fd` / `finite_difference` dispatch continues to govern PDELie-native derivative computation; this field records which method PySINDy used, not which PDELie backend was invoked.
- `input_layout` — `Literal["scalar_1d_uniform"]`. Reserved enum for `v0.34+` multi-channel/2D expansion. The field is first-class *now* so that `v0.34a-c` do not retrofit the schema; only `"scalar_1d_uniform"` is accepted at runtime.
- `library_feature_names` — list of non-empty strings, unique. Renamed from `library_terms` for continuity with `summarize_discovery_result` (`src/pdelie/discovery/contracts.py:395`, which reports `library_feature_names` from `result_mapping["library_feature_names"]`).
- `selected_terms` — dict keyed by PySINDy target-feature name; values are `dict[str, float]` mapping candidate-term string to fitted coefficient. Verbatim from the `equation_terms` block of the embedded `discovery_result` (`src/pdelie/discovery/contracts.py:396`).
- `coefficients` — optional dict carrying the raw coefficient matrix in a JSON-compatible form (e.g. `{"shape": [num_features, num_terms], "values": list[list[float]], "epsilon": support_epsilon}`). Opt-in shape; consumers must tolerate `None`.
- `support_precision`, `support_recall`, `support_f1` — configured recovery metrics; produced via the existing `pdelie.discovery.evaluate_discovery_recovery` machinery.
- `exact_support` — bool; `True` iff `support_precision == 1.0 and support_recall == 1.0`.
- `coefficient_relative_l2` — float; `||fit - target||_2 / max(||target||_2, epsilon)`.
- `train_residual`, `heldout_residual` — optional strict-numeric dicts of the shape `{"size": int, "l2_norm": float, "rms": float, "max_abs": float}`, matching `_residual_summary_or_none` at `src/pdelie/discovery/contracts.py:198-214`.
- `weak_contract` — optional dict. **Non-null iff `target_convention == "weak_pde_library"`**. Its structure is documented under "WeakPDELibrary wrapper" below.
- `warnings` — list of non-empty strings drawn from a controlled vocabulary (`"heldout_residual_missing"`, `"support_epsilon_defaulted"`, `"weak_contract_diagnostic_only"`, `"differentiation_method_defaulted"`; extended per implementation review).
- `pysindy_bridge_variant` — `Literal["periodic_only_v1"]`. Provenance identifier for the PySINDy discovery bridge variant that produced this `TaskResult`. `"periodic_only_v1"` is the sole accepted value in v0.31 and encodes the periodic-only-x contract enforced at runtime by the `pdelie.tasks.discovery` entry point (see "Runtime boundary-condition guard" below). Future FD-nonperiodic variants (v0.32.5 target) will add distinct string values (e.g. `"nonperiodic_x_finite_difference_v1"`) so consumers reading a saved `TaskResult` can determine which bridge produced it without inferring from `derivative_backend` or the embedded field metadata. This is a first-class field so extension does not require a schema-version bump.
- `underlying_discovery_result` — the payload returned by `summarize_discovery_result(...)`. TaskResult composes with the existing summarizer as a sibling wrapper, not as a parent that swallows the child.

## Runtime boundary-condition guard

The v0.31a periodic-only fence is enforced at **two** places in v0.31b runtime:

1. **The `pdelie.tasks.discovery` task-runner entry point** — before assembling PySINDy trajectories, the runner calls `is_x_periodic(field)` from `pdelie._boundary`. If the field is not periodic, the runner raises `PySINDyDiscoveryUnsupportedBoundaryError` (a new dedicated exception in `pdelie.tasks.discovery`, subclass of `ScopeValidationError`) with a message pointing to `pysindy_bridge_variant == "periodic_only_v1"`.
2. The existing `to_pysindy_trajectories` gate at `src/pdelie/discovery/pysindy_bridge.py:27-28` continues to reject nonperiodic fields.

**Both are required.** Relying on the `to_pysindy_trajectories` gate alone leaves a hole: `fit_pysindy_discovery` accepts raw trajectory arrays and does not consult boundary metadata, so a caller who assembles trajectories directly bypasses the bridge gate. The task-runner-level guard closes that hole for v0.31.

The `pysindy_bridge_variant` field records which enforcement path was in effect at task time. When v0.32.5 lands FD-nonperiodic discovery, it will emit a distinct variant string; consumers reading old `TaskResult` payloads can filter by the periodic-only variant explicitly.

### `weak_contract` trigger predicate

`weak_contract` is:

- `None` when `target_convention == "pde_library"`
- a non-null dict when `target_convention == "weak_pde_library"`

There is no third state. The runtime rejects (`SchemaValidationError`) any TaskResult where `target_convention == "weak_pde_library"` and `weak_contract is None`, or where `target_convention == "pde_library"` and `weak_contract is not None`.

## NaN-safety contract

The composed payload MUST pass:

```python
assert json.loads(json.dumps(payload, allow_nan=False)) == payload
```

before return. The runtime accomplishes this by routing the final payload through the existing helper `_validate_strict_json_compatible(payload, name="discovery_task_result summary")` at `src/pdelie/reporting/summaries.py:196-202`, mirroring the two existing strict-JSON summaries (`summarize_xarray_dataset_readiness` at `summaries.py:1311` and `summarize_weak_form_supportability` at `summaries.py:1954`).

This is required BECAUSE only 2 of 14 current `summarize_*` functions enforce `allow_nan=False`; the other 12 route through the permissive `_summary_payload` funnel (`summaries.py:255-261` calling `_validate_json_compatible` at `:187-193`, which catches only `TypeError` and permits NaN/Inf). TaskResult **must not** inherit that assumption because:

- the embedded `underlying_discovery_result` can, in principle, carry NaN residual entries under the permissive summarizer path
- `train_residual` and `heldout_residual` are numeric-valued and an NaN in either would silently pass the permissive validator
- downstream consumers (dashboards, notebook checks, discovery-workflow reporting) treat TaskResult as a canonical artifact and would break on `NaN` deserialization in strict JSON parsers

The runtime uses `_validate_strict_json_compatible` at the *composition boundary* — after all sub-payloads are assembled, immediately before return. The check catches any NaN or Inf that leaked in through an embedded sub-summary.

## WeakPDELibrary wrapper

When `target_convention == "weak_pde_library"`, the task bridge additionally composes a diagnostic report from PySINDy's `WeakPDELibrary` output. This wrapper carries its own top-level payload with:

```
{
    "summary_schema_version": "0.1",
    "summary_type": "pdelie_weak_pde_library_diagnostic",
    "method_family": "pysindy_weak_pde_library_polynomial_gauss_v1",
    "test_function_family": "pysindy_weak_pde_library_polynomial_bump_v1",
    "quadrature_rule": "pysindy_weak_pde_library_composite_gauss_v1",
    "diagnostic_only": true,
    ...
}
```

and its condensed form is stored inside the TaskResult's `weak_contract` field:

```
{
    "method_family": "pysindy_weak_pde_library_polynomial_gauss_v1",
    "test_function_family": "pysindy_weak_pde_library_polynomial_bump_v1",
    "quadrature_rule": "pysindy_weak_pde_library_composite_gauss_v1",
    "diagnostic_only": true,
}
```

### Why these identifier strings

The three identifier strings above are **distinct** from the pdelie-native `weak_1d` identifiers:

- `method_family`: pdelie-native is `"local_separable_quartic_bump_trapezoid_v1"` (`src/pdelie/residuals/weak_1d.py:20`)
- `test_function` / `test_function_family`: pdelie-native is `"separable_quartic_bump_beta"` (`src/pdelie/residuals/weak_1d.py:22`)
- `quadrature` / `quadrature_rule`: pdelie-native is `"composite_tensor_product_trapezoidal_native_window"` (`src/pdelie/residuals/weak_1d.py:21`)

The wrapper's strings deliberately use the `pysindy_weak_pde_library_*` prefix so downstream consumers (`summarize_weak_residual_report`, `summarize_split_leakage_provenance`, any future `summarize_weak_form_supportability` extension) can disambiguate provenance. There is no enum or allowlist gating these strings today — they are free-form string constants — so nothing at the schema layer prevents accidental collision. The scope freeze **documents** the wrapper's chosen strings explicitly as the disambiguation mechanism.

### The `diagnostic_only: true` marker

The wrapper payload always carries `"diagnostic_only": true`. This marker exists so that no downstream summarizer can mistake a WeakPDELibrary wrapper report for a public weak-form supportability claim. In particular:

- `summarize_weak_form_supportability` continues to treat the pdelie-native `weak_1d` slice as `supported_existing_slice` (Heat/Burgers); the wrapper report **cannot** promote a PDE to `supported_existing_slice`.
- The wrapper contributes to `supportability_label = "diagnostic_only"` at most.

## Supportability policy update

The supportability-policy dict gains one new key and one re-scoping note:

- new key: `"supports_pysindy_weak_library_diagnostic": True` — records that the wrapper is available as a diagnostic-only surface
- existing key `"supports_weak_derivative_backend"` is re-scoped to *public strong-derivative-only pdelie-native path*, with an explicit inline note that the WeakPDELibrary wrapper is a diagnostic-scope weak derivative backend

Both changes are additive; no existing field is removed and no existing value is silently flipped.

## Legacy compatibility

- `summarize_discovery_result` is unchanged. TaskResult **composes with it** — it does not replace it. A caller who wants only the discovery-result summary continues to call `summarize_discovery_result` directly.
- `fit_pysindy_discovery(config=None)` continues to work at its existing default; the loosening in v0.31 accepts `config={"pysindy_model": <configured_SINDy>}` as an additional shape.
- The existing periodic-only guard in `to_pysindy_trajectories` (`src/pdelie/discovery/pysindy_bridge.py:18-28`) is unchanged; **PySINDy PDELibrary bridge is periodic-only in v0.31; FD-nonperiodic extension is explicitly deferred**.

## Retention window for `weak_1d`

`weak_1d` is retained through v0.32 close. Its removal is contingent on:

1. the v0.31 PySINDy `PDELibrary` bridge shipping a documented replacement path, AND
2. the `WeakPDELibrary` diagnostic wrapper landing a validated parity harness with a documented `O((dx)^p)` tolerance

Neither condition is expected to hold at the v0.31 close; the wrapper's `diagnostic_only: true` marker makes this explicit.

## Out of scope for v0.31

The following are deliberately deferred to later releases:

- root `pdelie` exports for any TaskResult, WeakPDELibrary wrapper, or discovery-task API
- WSINDy design-matrix / SR3 weak sparse recovery
- weak-form nonperiodic surface
- multi-channel or 2D FieldBatch dispatch (`v0.34`)
- SymmetryCandidate contract (`v0.30.1`)
- LieGG / trained-model extraction (`v0.35a`)
- benchmark policy or clean/noisy gating
- PDEBench / The Well support claims (`v0.32` external-data readiness cookbooks)
- promotion of the v0.30e advisory `lint` / `typecheck` / `coverage` CI jobs to blocking

## Validation requirements (for v0.31 proper, not v0.31a)

When the TaskResult runtime lands (v0.31b+):

- `run_pysindy_pde_task(...)` must call `_validate_strict_json_compatible(payload, name="discovery_task_result summary")` on the composed payload before return
- `summary_schema_version == "0.1"` and `summary_type == "discovery_task_result"` are literal-string invariants
- `backend_name in {"pysindy"}` and `target_convention in {"pde_library", "weak_pde_library"}` are literal-set invariants
- `input_layout == "scalar_1d_uniform"` is a literal invariant (widened only under a scope freeze)
- `weak_contract` non-null iff `target_convention == "weak_pde_library"`
- `underlying_discovery_result["summary_type"] == "discovery_result"`
- backend versions are strings from `importlib.metadata.version(...)` for `pysindy`, `sklearn`, `pdelie`

## Implementation pointer (for v0.31 proper)

The most surgical implementation places a new submodule `src/pdelie/tasks/discovery.py` with:

- `run_pysindy_pde_task(field, *, config, target_convention, task_name, target_terms=None, ...)` composing the existing `to_pysindy_trajectories` + `fit_pysindy_discovery` + `summarize_discovery_result` + `evaluate_discovery_recovery` machinery
- a strict-JSON helper import from `pdelie.reporting.summaries` — reuse `_validate_strict_json_compatible` without duplicating logic
- a `WeakPDELibraryDiagnostic` dataclass (submodule-only) with an `as_dict()` that produces the wrapper-payload shape above
- **no** new root `pdelie` export; **no** modification of `pdelie.residuals.weak_1d`

The existing summarizer strict-JSON helper (`_validate_strict_json_compatible` at `src/pdelie/reporting/summaries.py:196-202`) handles the serialization enforcement without modification.

## v0.31b2 — WeakPDELibrary diagnostic as a SEPARATE summary type

**Status update:** In v0.31b1, `target_convention="weak_pde_library"` was DEFERRED. In v0.31b2, it is RUNTIME IMPLEMENTED — but the runtime lands on a **separate** top-level summary type (`pdelie_weak_pde_library_diagnostic`), not as a variant of `discovery_task_result`. The v0.31b1 `discovery_task_result` schema is not extended and its 22-key top-level shape is preserved.

### Why a separate summary type

The peer-review of the v0.31b arc flagged that embedding a full diagnostic-only WeakPDELibrary report inside `discovery_task_result` would either:

1. inflate `discovery_task_result` from 22 keys to a variable-shape payload whose key set depends on `target_convention`, or
2. force downstream consumers of the v0.31b1 discovery-task-result schema to disambiguate two very different payload shapes at read time.

Both outcomes are avoided by giving the WeakPDELibrary diagnostic its own strict-JSON top-level summary type. The condensed `weak_contract` dict (already frozen at 4 keys in v0.31a) remains embedded inside `discovery_task_result` when `target_convention == "weak_pde_library"`, so the composition boundary between the two summary types is *only* the condensed 4-key `weak_contract` block. The full WeakPDELibrary diagnostic payload is *not* embedded into `discovery_task_result` and does not change the 22-key `discovery_task_result` top-level shape.

### `pdelie_weak_pde_library_diagnostic` top-level key set

The v0.31b2 wrapper's public JSON payload has exactly the following top-level keys:

```
summary_schema_version
summary_type
diagnostic_only
method_family
backend_name
backend_version
input_layout
boundary_policy
target_convention
library_configuration
test_function_family
quadrature_rule
spatiotemporal_grid_shape
input_field_shape
weak_feature_names
weak_matrix_shape
weak_target_shape
retained_weak_rows
skipped_weak_rows
skipped_row_reasons
finite_value_status
column_norms
matrix_rank
matrix_condition_number
warnings
compatibility_notes
provenance
```

Frozen literal values:

- `summary_schema_version = "0.1"`
- `summary_type = "pdelie_weak_pde_library_diagnostic"`
- `diagnostic_only = True`
- `method_family = "pysindy_weak_pde_library_polynomial_gauss_v1"`
- `input_layout = "scalar_1d_uniform"`

The three identifier strings frozen in v0.31a (`method_family`, `test_function_family`, `quadrature_rule`) continue to carry their `pysindy_weak_pde_library_*` prefix so the pdelie-native `weak_1d` provenance strings (`local_separable_quartic_bump_trapezoid_v1`, `separable_quartic_bump_beta`, `composite_tensor_product_trapezoidal_native_window`) remain unambiguously disambiguated.

### `diagnostic_only=True` does NOT change `discovery_task_result`

The `diagnostic_only: true` marker is a top-level field on `pdelie_weak_pde_library_diagnostic` only. It is **not** promoted to a top-level key on `discovery_task_result`. The v0.31b1 22-key top-level shape of `discovery_task_result` is preserved verbatim in v0.31b2:

- no new top-level key is added to `discovery_task_result`;
- the embedded 4-key `weak_contract` dict (with its own inner `diagnostic_only: true`) is unchanged from v0.31a;
- `discovery_task_result` remains a 22-key top-level shape.

Callers who want the full diagnostic report call the wrapper (via `pdelie.tasks.weak_pde_library`) directly; callers who want a discovery-task record with the condensed weak-contract provenance continue to use `pdelie.tasks.discovery.run_pysindy_pde_task` unchanged. The two entry points are siblings, not parent/child.

### Public surface (v0.31b2)

Three new submodule-only names, none of which is re-exported at the `pdelie` root:

- `pdelie.tasks.weak_pde_library.WeakPDELibraryDiagnostic` — dataclass carrying the wrapper payload; has an `as_dict()` producing the strict-JSON top-level shape above.
- `pdelie.tasks.weak_pde_library.summarize_pysindy_weak_pde_library_diagnostic` — takes a `WeakPDELibraryDiagnostic` instance (or the raw PySINDy assemblage produced by `inspect_pysindy_weak_pde_library`) and returns the strict-JSON-validated summary dict.
- `pdelie.tasks.weak_pde_library.inspect_pysindy_weak_pde_library` — the inspector that runs PySINDy's `WeakPDELibrary` under a periodic scalar 1D `FieldBatch` and returns a `WeakPDELibraryDiagnostic`.

All three names are also available from the `pdelie.tasks` package as re-exports; they are **not** exported at the `pdelie` root. No `pdelie.residuals`, `pdelie.reporting`, or `pdelie.discovery` symbol carries any of these names. The strict-JSON boundary is enforced by routing the final payload through `_validate_strict_json_compatible` at `src/pdelie/reporting/summaries.py:196-202` exactly once, immediately before return.

### Exception reuse

`PySINDyDiscoveryUnsupportedBoundaryError` (defined in `pdelie.tasks.discovery` since v0.31b1, subclass of `ScopeValidationError`) is the correct raise for nonperiodic-x inputs to `inspect_pysindy_weak_pde_library`. No new exception is introduced. General schema violations raise `SchemaValidationError` per the existing v0.22 convention.

### Non-goals (v0.31b2)

- no `pdelie` root export for the three new names
- no promotion of any PDE to `supported_existing_slice` via the wrapper (the marker `diagnostic_only=True` is load-bearing)
- no WSINDy design matrix; no SR3-style weak sparse recovery; no noise-robustness certification; no clean/noisy gate
- no validated `O((dx)^p)` parity harness with the pdelie-native `weak_1d` output (contingent on `weak_1d` removal beyond v0.32 close and explicitly deferred)
- no PDEBench / The Well benchmark claim
- no widening of the periodic-only-x guard; the two-layer runtime BC guard from v0.31b1 (task-entry `is_x_periodic` + `to_pysindy_trajectories` bridge gate) covers the wrapper path as well
- no removal of `weak_1d`; retention is guaranteed through v0.32 close
- no change to `discovery_task_result`'s 22-key top-level shape, and no new top-level `diagnostic_only` key on `discovery_task_result`