# ADR-0046: Config Builder Model and Landuse-Modification Defaults

Status: Accepted
Date: 2026-08-27

## Decision Provenance

- **Decision Venue**: active Codex development sessions, 2026-08-27 04:00 UTC
  and 2026-08-27 06:00 UTC.
- **Participants Present**: project operator and Codex.
- **Decision Owner**: project operator.
- **Implementer**: Codex.

## Context

The initial Config Builder inherited TOPAZ and `wepp_dcc52a6` from shared
defaults and exposed only Single OFE. Adding an explicit delineation and WEPP
binary selection requires deterministic defaults; relying on component sort
order would make a scientifically material choice accidental.

## Change Summary

Previously, new Builder configs inherited TOPAZ and `wepp_dcc52a6` and had no
explicit binary selection. After this decision, new Builder configs explicitly
default to WhiteboxTools and `wepp_260803`; Single OFE remains the default
representation, while Multiple OFE is available only with that backend/binary
pair. Builder configs previously inherited
`landuse.enable_landuse_change = false` from shared defaults; new Builder
configs now explicitly set it to `true` through the selected landuse component.

## Decision

New Config Builder projects default to WhiteboxTools (`wbt`), Single OFE, and
`wepp_260803`. Binary choices are the complete list returned by the canonical
runtime provider `wepp_runner.wepp_runner.get_linux_wepp_bin_opts()`. Multiple
OFE is a conservative Builder V1 option available only with WhiteboxTools and
`wepp_260803`. Existing projects and shared Interfaces presets are not migrated
or changed.

Every Config Builder project is classified Preview. This maturity label
communicates that the expanded model-input matrix has not completed production
promotion.

New Config Builder projects also enable landuse modification. The selected
landuse component owns and writes this Builder-scoped value. Existing projects,
shared defaults, and Interfaces presets are not migrated or changed.

## Rationale

The operator selected the deployed WhiteboxTools and `wepp_260803` path as the
default for new Builder work. Explicit registered defaults make the choice
reviewable and persist it in `config.cfg` and `config-manifest.json`. Binary
availability intentionally follows the canonical runtime provider, while the
default never follows provider or lexical ordering.

The Builder is intended to expose its configured landuse workflow, including
post-delineation landuse edits. Writing the capability in the registered
landuse component makes that behavior explicit in generated configuration and
component provenance without broadening the shared default.

## Alternatives Considered

Keeping TOPAZ and `wepp_dcc52a6` as defaults was rejected because it does not
match the operator-selected path for new Builder projects. A separate
hard-coded Builder binary allowlist was initially selected, then superseded by
the operator's requirement that Builder use the complete canonical provider
list. Inferring a compatible binary after submission remains rejected because
silent model-selection substitution would obscure provenance.

Keeping landuse modification disabled was rejected because it unnecessarily
hides the Builder run-page editing workflow. Changing shared `_defaults.cfg`
was rejected because it would alter unrelated legacy and Interfaces configs.

## Evidence

- Contract checkpoint:
  `docs/work-packages/20260826_project_config_builder_model_options/artifacts/20260827_contract_decision.md`.
- Canonical availability provider:
  `wepp_runner.wepp_runner.get_linux_wepp_bin_opts()`.
- Required acceptance evidence: direct role resolution and representative
  execution for every provider-exposed binary, a Forest WBT Multiple OFE
  preparation/run with `wepp_260803`, and a Forest Single OFE run with each
  exposed binary before registry exposure.

## Risk and Rollback Notes

Different WEPP binaries can produce different scientific outputs. WhiteboxTools
and TOPAZ can also delineate different watershed geometry. Preview maturity,
explicit review text, manifest provenance, and the Forest execution matrix make
that difference observable. The provider's `latest` entry is intentionally a
mutable alias: its resolved target is recorded at creation, but future runs may
resolve a newer target. Users requiring immutable-release reproducibility must
select a concrete binary value.

Rollback removes the new registry defaults and choices for future Builder
creation. It does not rewrite flattened configs already created with
`wepp_260803`; changing existing projects requires separately authorized
remediation. Failure of executable, preparation, or representative-run evidence
blocks exposure and retains the previous Builder implementation.

Landuse modification changes only the availability of an explicit user action;
it does not rewrite landuse automatically. Rollback changes the registered
landuse component value back to false for future Builder projects and does not
rewrite existing flattened configs.

## Consequences

New Builder projects intentionally differ from the former inherited defaults.
Tests must assert the defaults directly and must not derive them from registry
ordering. They also expose the Modify Landuse control. Existing runs and
Interfaces presets preserve their recorded behavior.
