WEPPcloud

← Back to help

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)/(rhow+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. 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.