# Soil–groundwater feedback: bounded diagnosis, not a corrected simulation Measured by `.venv/bin/python scripts/diagnose_domain_seepage_soil_feedback.py`. Reproduction is read-only for the source model and writes only this diagnostic folder. The exact source receipts, daily heads, transfer matrix and profile inputs are bound in `receipt.json`. ## Finding The original G2 soil-recharge stream continues supplying cells where the previous day's upper groundwater head is already at or above the estimated soil bottom. This identifies an important interaction to implement and test; it does **not** prove that all this drainage should cease. Saturated soil can transmit downward water if the hydraulic gradient permits it. A shallow head alone cannot determine the correct flux. The measured April exposure is material, whereas September exposure is very small. The generated `contact_summary.csv` contains both (a) previous head above mean ground and (b) previous head above soil bottom, using the actual HRU soil-profile depths. These are tests on the earlier inspection cells and original G2 heads, not the entire domain or the new whole-domain candidate. First replay days are excluded so every screen uses a genuinely preceding saved day. `hru_withholding.csv` identifies the contributing HRUs. `signed_withholding_ledger.csv` demonstrates, for a deliberately extreme accounting envelope, that any withheld recharge must have an equal positive counterpart. Its positive account is explicitly **unallocated water**. It has no physical storage capacity or release process and must never be presented as soil storage, surface flooding, or an executable production correction. Original heads are not recomputed. This diagnostic measures exposure and tests bookkeeping, not feedback effectiveness. The soil-bottom test assumes the HRU soil depth can be subtracted from its receiving cell's mean terrain. Terrain within the cell and actual soil pressure are unresolved. This geometry is useful for screening but is insufficient for calibrating a flux law. ## Existing hook and what remains missing Read: `docs/records/model-domain-review-2026-09-23/production_adoption/coupling/soil_feedback_hook_readiness.json`, keys `native_hook.live_state`, `input_and_ledger_contract`, and `available_head_state`. An existing disabled-by-default native hook can credit live layer soil water, cap the addition at live saturation capacity, and emit an equal groundwater debit. It consumes supplied requests; it does not calculate those requests from heads. It acts before soil percolation. Therefore it is **groundwater-to-soil supply**, not a direct limiter on downward soil drainage. Measured: the present script rechecks the retained finite-credit and over-cap native test ledgers. Both close their request/applied/rejected and signed debit identities; recorded soil storage changes agree with applied credits within the native single-precision tolerance. These are recomputed historical fixtures, not newly executed native simulations. Their values and hashes are in `receipt.json`. Read: `src/chu_swatplus/swat_live.py:135` exposes completed HRU recharge events; `src/chu_swatplus/live_groundwater_coupler.py:163` assembles the groundwater solve; `src/chu_swatplus/mf6_live.py:216` conserves volume when converting recharge to depth and returns heads from the solved groundwater state. That conservation switch is **not** a saturation response. `src/chu_swatplus/funded_recharge.py` conserves externally funded additions; it does not impose a soil hydraulic boundary. These newer daily-engine files were inspected only; they were neither modified nor treated as the G2 source generation. The source G2 arrays contain recharge fluxes, not the contemporaneous layer water content/pressure needed to calculate a pressure-dependent downward flux. Static soil depths and hydraulic parameters are available in its source deck, but those alone do not supply the missing live state. No physically qualified limiter or head-to-credit rule was found in the inspected interfaces. ## Concrete conservative implementation route 1. Add a disabled-by-default interface at the **live soil process**, before its percolation water is exported. Expose each layer's current storage, saturation limit, geometry and hydraulic parameters alongside the mapped previous groundwater head. Use a declared lag and test timestep sensitivity. Do not reconstruct live storage from exported recharge. 2. Treat two directions separately. Downward recharge needs a soil-bottom pressure/gradient response; upward groundwater supply needs its own finite transfer law and explicit groundwater debit. The existing capped credit hook is a reusable component for the latter, not a replacement for the former. 3. If downward export is reduced, retain that water in the actual soil calculation. Let native capacity and surface processes route any resulting excess to surface storage/runoff; do not append an unlimited account after SWAT has completed the day. Book the groundwater recharge decrease and soil/surface increase against the same original transfer so it is not counted twice. 4. For upward supply, request a physically bounded transfer, credit only what the live soil accepts, and debit exactly that accepted amount from groundwater. Keep rejected requests unfunded. Use an explicit exchange entry; do not hide a groundwater extraction inside negative recharge or classify it as pumping. 5. Recompute groundwater evaporation from the same land response to avoid counting the same atmospheric loss twice. Run identity/no-contact, wet-bottom, reversed-gradient and over-capacity tests before a whole-domain comparison. Retain cell/HRU signed ledgers and actual final stores, and demonstrate finite exchange and timestep stability. These are implementation requirements, not proof that a specific pressure law has been calibrated. Step 3 of the investigation is completed here as an exposure/conservation diagnosis and existing-hook recheck; a coupled physical feedback experiment remains unimplemented. Drainage experiments alone cannot resolve this interface gap.