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.