# ADR-0043: EU ESDAC Soil Quality Contract

**Status**: Accepted
**Date**: 2026-08-19
**Review Date**: 2026-08-19
**Review Owner**: EU soil maintainer
**Ratification**: User review confirmed; accepted for Phase 3 implementation

## Context

The Phase 0 pilot sampled 1,000 valid ESDAC raster cells. Phase 1 replay
captured a valid control, a degraded land-use metadata case, zero-valued STU
data, non-increasing horizon depths, missing depth classes, missing Ksat
coverage, and categorical lookup/provider exceptions. The current builder can
write a `.sol` file for some invalid profiles or fail with an unstructured
exception for others.

The work package needs an explicit quality result before Phase 3 adds a
validation boundary. The contract must distinguish optional metadata loss from
mandatory physical or structural invalidity and must not introduce a silent
generic-soil fallback.

## Decision

Adopt the following Phase 3 contract:

1. Return `valid` when all source, derived, horizon, Ksat, and serialization
   invariants pass.
2. Return `degraded` when optional land-use metadata is unavailable, or when a
   partially missing Ksat profile remains finite and model-representable. The
   warning must include field, location, raw state, and reason code.
3. Return `rejected` for provider exceptions, unsupported required categorical
   values, unreadable depth classes, all-zero mandatory STU profiles, invalid
   texture balance, nonpositive density, non-finite derived values,
   non-increasing horizons, all-missing Ksat, or nonrepresentable output.
4. Require clay/sand/silt percentages to be finite, bounded in `[0, 100]`, and
   within one percentage point of a 100-percent texture sum. This tolerance is
   for integer source quantization, not a calibration or replacement rule.
5. Allow individual zero texture components and zero gravel; reject an
   all-zero mandatory texture triad. Do not introduce an empirical density
   cutoff or an organic-matter minimum in this phase.
6. Require serialized water contents to satisfy the already accepted contract
   `0 <= wilting_point <= field_capacity <= 1` from ADR-0012.

No production code changes are included in this ADR's Phase 2 commit. Phase 3
defines and tests the pure validation/result boundary and its location-aware
diagnostics. Phase 4 wires that accepted contract into the ESDAC builder and
worker aggregation without changing the quality policy.

## Decision Provenance

- **Decision venue**: EU disturbed-soil hardening work-package execution
  session, 2026-08-19, America/Los_Angeles.
- **Participants present**: User and Codex, 2026-08-19.
- **Decision owner(s)**: EU soil maintainer.
- **Implementer(s)**: Codex, subject to the accepted contract.
- **Ratification**: User reviewed ADR-0043 and confirmed that it is
  reasonable to ratify for Phase 3 implementation, 2026-08-19.

## Change Summary

Current behavior has no structured valid/degraded/rejected result and can
silently write decreasing horizon depths or represent an all-missing Ksat
profile with `0.001`.

Accepted behavior adds a field-qualified quality contract. It does not yet
change runtime behavior, generated files, defaults, transfer functions, or
fallback execution.

## Rationale

Structural failures are unambiguous model-input defects: a second horizon
cannot end before the first, and an all-zero mandatory STU profile cannot
produce a physically meaningful layer. Optional land-use metadata does not
invalidate the physical profile by itself, so it is observable degradation.
The one-percentage texture tolerance preserves integer percentage source data
without accepting materially incomplete texture profiles.

The contract rejects missing mandatory evidence instead of manufacturing a
generic replacement soil. This keeps the failure actionable and preserves the
distinction between upstream data quality and approved scientific fallback.

## Alternatives Considered

1. Treat every zero as invalid — rejected because zero gravel and individual
   zero texture components can be valid physical states.
2. Treat every source gap as a generic fallback — rejected because it masks
   source/version/provider defects and changes model parameterization.
3. Keep the current `0.001` all-missing Ksat representation — rejected because
   it converts missing evidence into a plausible-looking model value.
4. Reject every missing optional metadata field — rejected because the Phase 1
   control matrix shows a physically valid profile can exist with missing
   land-use metadata.
5. Add empirical density or organic-matter cutoffs now — rejected because the
   pilot does not establish calibrated domain limits and no such thresholds
   are needed to catch the confirmed failures.

## Evidence

- Work package: `docs/work-packages/20260819_eu_disturbed_soil_hardening/`.
- Phase 1 fixture:
  `tests/eu/soils/fixtures/eu_disturbed_soil_phase1.json`.
- Replay tests:
  `tests/eu/soils/test_esdac_quality_fixture.py`.
- Pilot result: 641 suspicious locations, 596 completed suspicious builds,
  35 builder exceptions, 59 horizon-order findings, and 10 controls.
- Related water-content contract: ADR-0012.

## Consequences

Phase 3 will need a structured result/error carrier and a validation boundary
before `.sol` serialization. Existing callers that expect only a soil key may
need an additive diagnostic path. Locations currently producing invalid files
will become rejected or degraded with visible reasons rather than silently
accepted.

The one-percentage tolerance and Ksat policy are scientific/workflow
parameterization decisions. If the EU soil maintainer changes them, this ADR
must be amended before implementation.

## Risk and Rollback Notes

Risk: legitimate edge profiles may be rejected if their source encoding falls
outside the accepted contract. Phase 3 must retain the Phase 1 valid control,
add a valid-zero matrix, and report rejection counts as a guardrail. Rollback
is to revert the Phase 3 validation boundary while preserving the fixture and
diagnostic tests; do not restore silent fallback without a revised ADR.

## Amendment — 2026-11-06

[ADR-0139](ADR-0139-esdac-missing-metadata.md) defines required data by the
physical materials actually emitted, allows missing descriptive metadata with
warnings, and handles shallow profiles using existing mapped depths. Consult
the [current source sufficiency contract](../schemas/esdac-soil-source-contract.md)
for field policy and deterministic batch identity/retry behavior.
