DETERMINISTIC_EXECUTION_GATE.md

Deterministic execution-integrity gate

This revision prevents invalid hydraulic arrays from being presented as successful SWMR results.

Changes

1. Dynamic-wave preflight recognizes explicit zero values for MAX_TRIALS, HEAD_TOLERANCE, and MIN_SURFAREA as legacy/default sentinels. It creates an immutable derivative execution copy using unit-aware effective defaults, while preserving and hashing the original upload. Negative and non-numeric values remain blocking errors. Omitted values remain untouched.
2. Post-run integrity classification records valid, limited, or invalid using routing convergence and flow-routing continuity evidence.
3. A run is invalid when every routing step fails, at least 5% of routing steps fail, or the routing continuity error is at least 10%.
4. Invalid hydraulic arrays remain available in the audit database, but node, link, storage, control, capacity, spill, and depth-velocity conclusions are set to Not assessed - hydraulic routing solution invalid.
5. The executive summary and model identity disclose the execution gate.
6. Calgary screening returns no pass/fail hydraulic results for an invalid run.
7. Regression tests cover the Kincora zero-value failure and the corrected usable-run metadata.

Kincora failure reproduced

The legacy input explicitly contained:

MAX_TRIALS       0
HEAD_TOLERANCE   0

The EPA SWMM 5.2 desktop interface resolves these values to effective defaults. For SI models the derivative uses MAX_TRIALS=8, HEAD_TOLERANCE=0.0015 m, and MIN_SURFAREA=1.167 m2. Every substitution, both hashes, and both INP files are retained in the audit package. This is a disclosed compatibility action, not a mutation of the uploaded engineering model.

Validation

• Python compilation passed for all packaged modules.
• 35 deterministic unit checks passed.
• Preflight integration requires the Space dependencies and isolated OpenSWMM worker environment described in the existing README.