# ADR-0132: optional SSURGO retention builder

Date: 2026-11-02

Status: accepted bounded opt-in contract and canonical local implementation, 2026-11-02; broad regression passes. General release and package closure remain HOLD for the confirmed native FC/HK ownership defect; no deployment.

## Decision provenance

Venue: user-authorized rock/water development program, agent workspace, 2026-11-02 America/Los_Angeles. Participants: user and Codex implementation/review agents; no external institutional endorsement. Decision authority: user-authorized program; parent agent recorded the bounded admission and optional API decision on 2026-11-02. Implementer: Codex surface_scope. Independent implementation, science and security integration outcome reviews have passed; the dated evidence below bounds this acceptance.

## Decision

Expose an explicit optional SSURGO builder policy after unchanged full component and horizon selection. Preserve the default capped mass-complement branch and every unrelated source family. Require a source acquisition receipt SHA256 and complete requested profile success. Carry source-to-emitted row identity through actual treatment, MOFE and staging consumers using mandatory marked, hash-bound companions. No UI, persisted policy, default migration or native engine selection is added.

For both final source-derived FC/WP branches, original finite positive ordered source fractions, original density 0<rho<2.65 and prepared mass fraction 0<=w<=0.85, use c=2.65*(1-w)/(rho*w+2.65*(1-w)). Set FC and WP to original source fractions/c only if 0<WP/c<FC/c<1-rho/2.65. Zero rock remains numerically unchanged. Missing/fallback, prior selection exclusions, native-cap conflicts and density/porosity conflicts remain unchanged with reasons. The default remains source fractions/(1-min(w,0.5)). This reproduces ADR-0127; it introduces no new scientific assumption or threshold.

## Rationale and alternatives

The optional policy makes the bounded retained experiment reproducible without changing global Horizon arithmetic. Reject universal source-family adoption, density-changing treatment, metadata-only guards disconnected from consumers and a new NoDb setting. Native behavior must be admitted independently. Normal installed spawn imports must load the integrated writers; research import finders and executor injections are excluded.

## Evidence and gates

P04 actual baseline v4 and candidate v6 each cover 66 soils/193 OFEs and match P02 numeric contracts. The v6 root receipt is 9a73068af0f0e0f8bbe083acc61c6c5a0c98cb98b0a76be0af218f53aef58df6. Earlier failures retained evidence for blank density parsing, module resource completeness and spawned worker identity. Security controls cover parent confinement, relocation, missing companions, foreign identities, stale reuse and exclusive output races. P03 completed 142 histories on native source d2e14d96af5942409c9a315dc8594fcc164a702a. Independent science and implementation reviews accept bounded consumer behavior for this six-source project, unchanged-density treatments and actual hourly engine, with internal observations on H11/H28/H40 and nonvacuous H40 accepted-root withdrawal. This is not universal physical validation, thermal closure, full-system water-budget closure or field calibration.

The API retains its generic mathematical eligibility without a case-specific whitelist or new tuning. That rule does not certify every eligible profile physically; callers must retain independent acquisition/cache/source association evidence. Other source families and density-changing treatments remain outside admission.

Exact retained decisions:

- Science: `P03-terminal-science-admission-v1.json`, SHA256 `505710d3c5c2460944d8a4c4981aa04325ee0e63f98bad7717c47212f17184c3`.
- Implementation: `P03-terminal-implementation-outcome-v1.json`, SHA256 `cbb54e05bd744691bd3ff50cdd7a902e5fa10e6060d7295186f15cb0a62cc56e`.
- Parent: `out/rock-water-development-20261101/P03-parent-admission-v1/decision.json`, SHA256 `b32e16c4ca31c02f2271dc99954a70daeae4d8bac36fc2c30ec875ac8467801d`.
- Actual P03 receipt: `out/rock-water-development-20261101/P03-final-continuation-v2/execution-result.json`, SHA256 `19cf9032023aff47dd3af9a32870cc5bbf9486cd0a41815cc6cbee62d598e28e`.

At the contract decision checkpoint, installed-controller and integration outcomes
were pending. The following dated admission supersedes that pending status while
preserving the original P03/P04 scope and unchanged formulas.

### Canonical local integration admission, 2026-11-02

Parent decision `out/rock-water-development-20261101/P04-parent-integration-disposition-v1/decision.json`
(SHA256 `5b426af69fe64e6c7ced5adbe0edbe22e38598ef80ba094028498543075cb855`)
accepts the canonical local explicit opt-in implementation and installed-controller
artifact gate. Actual receipt `e44238519b8e9f8cbe76c13deba7cd43ec02b114afd0a982128eb27ac4ef19dc`
binds exact reproduction of all 66 soils and companions through ordinary installed
modules. Independent science, implementation and security outcomes pass. Canonical
validation `a22256d2a08140d78e936d1a8b9f5a882a635eaedbe97c91220c1b07a710c694`
records 84 focused tests, 346 affected tests, two stub modules and test-stub checks
passing. Exact unchanged inputs permit reuse of bounded P03 evidence without a
new native campaign. At that integration checkpoint, broad repository validation
and final documentation, archive, public selection and release signoff remained
open. Broad-v2 subsequently passes 12,729 tests with 423 skips and unchanged bound
code/binaries; parent `c72571780b7552e3840d5c5cfc90cddda623343054a4679e986f593974c504d9`
accepts the terminal regression evidence. This does not resolve the native
ownership HOLD described below. No default adoption, deployment,
universal physical validation or relaxation of acquisition association follows.


## Risk, rejection and rollback

S01 subsequently confirms wrong-OFE dynamic FC/HK consumption under both the
default and optional policies on heterogeneous native inputs. Unrestricted
heterogeneous-use readiness is HOLD; the existing API's mathematical eligibility
does not certify physical validity. Preserve the current default and explicit
optional implementation, but do not infer a general safe-use class or close the
native correctness finding through documentation. The defect's pre-revision5
source history is not evidence of harmlessness or unchanged output consequences.
See the [known native ownership limit](../schemas/whole-soil-water-capacity-contract.md#known-native-coefficient-ownership-defect).
The supplementary investigation authorizes observation and disposition, not a
native repair. Prior P03/P04 evidence remains bounded to its measured scope.

Companion loss, unsupported density changes or stale artifacts must fail closed. Do not remove markers or relax checks to resume a failed build. If integration gates fail, retain the private packet and failed artifacts; do not enable the optional capability or reinterpret failure as default admission. After optional integration, rollback removes the optional entrypoint only after preserving existing opt-in artifacts and their validator; do not silently reinterpret those artifacts as legacy soils. No automatic rebuild or default migration is authorized.


## Acquisition association boundary

`retention_source_receipt` is a caller-supplied SHA256 identifier. The API checks its syntax and internal source/decision/emitted-row/parent consistency; it does not open or independently verify the acquisition receipt, raw source snapshot or cache. A matching hash is not external source authority, institutional attestation or proof that the metadata describes an actual acquisition.

The authorized acquisition/build caller must independently bind the actual receipt to the complete consistent source snapshot, production cache schema/ordered rows/missingness, selected components/horizons and builder input fields. Retain that association evidence with the build. P04 supplies this separate evidence through its frozen P01 tables and finalized-cache/source-record audit; generic companion validation alone does not reproduce that verification. This boundary remains mandatory for every later opted-in build.
