[Chain-Frost]

Final review corrections (2026-10-17)

Published repair: 8b386d8. Maximums preserves text identifiers (including leading zeros), and both wrappers reject output aliases of primary/attribute inputs, even with --overwrite. Physical identity checks include hard links; non-overwrite writes use exclusive creation. Wrapper revisions are 2026-10-17.1.

Focused regression checks: 68 passed, 2 skipped (Windows symlink privileges). Ruff, strict Pyright, compilation, help, documentation and retained-wheel verification pass. All 34 review threads are resolved. The user explicitly authorized fixing and manually merging PR #100 after all five final-head hosted checks pass. Deferred engineering follow-ups #102/#103 retain their existing scope; run-hy8#6 is not included in this authorization.

---

Merge scope and deferred verification (2026-10-17)

Current head: 97fe390. CI and package integration are repaired. All five hosted jobs passed at this head (Python CI, Fast PR checks). The complete local suite recorded 1,226 passed / 12 skipped, Ruff and strict Pyright passed, and wheel 26.10.17.1 was rebuilt and isolated-smoke-tested.

Completed engineering evidence: A genuine Maximums workbook was produced from the supplied Module 03 tutorial EOF outputs. All four Maximums evaluation scenarios ran through both the native solver and installed Windows HY-8. Observed maximum differences were 0.18138% discharge, 0.00367773 m headwater and 0.16326% outlet velocity. Inlet/material selections for this fixture were explicit test assumptions, not confirmed source physical metadata. These results are evidence of a tested workflow, not general HY-8 numerical parity or universal TUFLOW model correctness.

Explicitly deferred follow-ups — not blockers for merging this migration:

• Validate migrated TUFLOW culvert engines against actual HY-8 on Windows #102: Finish full mixed 1d_nwk/pit/rectangular/ignored-feature tests on real network data, remaining material/inlet/loss variations, retained workspace tests and formally agreed numerical acceptance tolerances on representative data. The supplied 162 GeoPackages / 950 layers contain no suitable 1d_nwk source. Keep issue open.
• Verify TUFLOW blockage handling in Maximums/EOF culvert integration #103: Verify the source blockage method, EOF nominal/effective dimensions, event/category blockage and risk of double application against real source model/blockage-matrix evidence. No such source was supplied. Keep issue open as future engineering-validation work.

Limits until the follow-ups are completed: The migrated wrappers use explicit physical material/inlet configuration and reject unsupported or unresolved mapping scenarios. The reduced-area blockage assumption is not automatically validated for arbitrary TUFLOW models; independently confirm model-specific blockage/dimension provenance before engineering reliance. Defer any claim of general numerical equivalence. Do not weaken fail-closed behaviour merely to pass a workflow.

Remaining PR steps: Final review of the published head and any required code/documentation corrections, then an explicitly authorised manual merge. Green CI alone is not merge permission. Follow-up Chain-Frost/run-hy8#6 merges only after this PR.

Validation record: migration handoff.

---

Closes #99.

Summary

• migrates the two TUFLOW-specific culvert computation demos out of run-hy8;

• adds a shared engine-neutral circular culvert definition with explicit physical shape/material/inlet configuration and separate TUFLOW loss parameters;

• adds explicit --engine hy8|ryan-culverts selection;

• delegates native hydraulics to public culvert_solver APIs;

• delegates HY-8 hydraulics to public run_hy8 APIs;

• preserves the original Maximums forward/inverse scenarios and 1d_nwk HW:D checks;

• removes project-specific hard-coded source paths;

• emits engine-labelled long-form CSV while retaining failed rows/scenarios;

• catalogues both maintained wrappers for MCP discovery;

• documents repository ownership and the lack of assumed numerical parity.

Scope note

The migrated workflows remain circular-only because the source demos do not provide enough information to reconstruct rectangular culverts faithfully. TUFLOW Type = C establishes circular shape only; material and inlet treatment are explicit physical inputs and are never inferred from Manning roughness or loss coefficients.

Mixed networks can supply per-crossing Material and Inlet Configuration through the optional attribute source. The shared typed definition carries CircularCulvertConfiguration separately from TuflowLossParameters. Unsupported or unresolved combinations fail closed rather than borrowing another material/inlet assumption.

Review fixes

Automated review findings were addressed for:

• canonical Maximums Num_barrels handling;

• fail-closed Flags checking so box rows are not treated as circular;

• preserving the complete governing Maximums row instead of synthesising columns across rows;

• preserving valid zero invert elevations;

• modelling HY-8 constant tailwater with the actual downstream invert rather than the water-surface elevation;

• skipping TUFLOW 1d_nwk features marked ignored;

• resolving negative Len_or_ANA from the digitised feature geometry;

• refusing result CSV replacement unless --overwrite is supplied;

• using unique retained HY-8 workspaces per crossing/AEP/scenario and requiring explicit overwrite before reuse;

• exposing the native wrappers in the packaged MCP workflow catalogue with focused registry coverage and safety metadata;

• applying numeric TUFLOW pBlockage to circular 1d_nwk geometry and failing closed for unresolved category blockage;

• rejecting unresolved TUFLOW -99999 invert sentinels before hydraulic evaluation;

• treating canonical Number_of = 0 as TUFLOW's documented one-barrel default;

• protecting retained 1d_nwk HY-8 workspaces from implicit reuse;

• splitting external HY-8 catalogue discovery into privileged, explicit-approval workflow entries.

• applying Maximums pBlockage consistently with the 1d_nwk circular mapping;

• using deterministic filesystem-safe internal HY-8 crossing/project/barrel names while preserving original TUFLOW IDs in normalized output;

• making retained HY-8 workspace keys collision-resistant after sanitization in both migrated wrappers.

• allowing adverse-slope culverts through the engine-neutral model and failing closed only for the native engine that does not support them;

• adding wrapper/library identity banners to both maintained wrappers;

• avoiding HY-8 workspace-root creation for native Maximums runs.

• preserving Maximums base-run identity (trim_runcode, with internalName fallback) when selecting governing rows and exporting results;

• retaining nominal diameter separately from blockage-adjusted hydraulic diameter so HW/D targets and reported HW/D remain TUFLOW-consistent in both wrappers.

• rejecting malformed/non-finite barrel-count values instead of silently defaulting them to one barrel while preserving documented missing/blank defaults;

• replacing roughness-based material inference with explicit typed physical configuration (shape, material and inlet treatment);

• supporting per-crossing inlet configuration alongside material in CSV/vector attribute sources and CLI overrides;

• keeping TUFLOW loss coefficients separate from physical inlet selection;

• preserving Maximums Entry Loss, Exit Loss and Fixed Loss evidence: native EntryC is attached as a barrel loss override while unsupported loss terms fail closed, and HY-8 rejects incompatible arbitrary loss overrides;

• correcting wrapper-side attribute lookup and isolating workspace tests from unrelated native mixed-flow convergence.

Regression tests cover these mappings, blockage/default/sentinel semantics, overwrite/workspace safeguards, native and privileged MCP discovery, native forward/inverse dispatch, and the HY-8 adapter boundary.

Intentionally retained ancillary changes

This branch also intentionally retains:

• the ASC_to_ASC parity-test conventional executable default and its documentation;

• the minor uncertainty-test Ruff formatting change;

• the vendor/ryan_culverts pointer advance currently present on the branch.

These are intentionally retained rather than removed from this PR.

Validation

See the current validation and merge blockers above. Earlier green runs do not establish final-head readiness.

Dependency / merge order

1. Merge this PR manually.

2. Then merge Remove TUFLOW-specific demo ownership run-hy8#6, which removes the obsolete upstream TUFLOW demo copies and closes Review ownership of TUFLOW/domain-specific demo scripts run-hy8#4.

No ryan-culverts implementation PR is required for this migration because the required public solver APIs already exist.

Do not merge automatically.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T02:25:34.384453Z	cbbdfab	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 75892bf316

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Chain-Frost]

Scope decision (17 October 2026): #103 remains open as future, source-model-specific blockage verification. The outstanding real mixed-1d_nwk, expanded physical configuration/loss, workspace, and acceptance-tolerance checks in #102 are also deferred, not PR #100 merge blockers. The verified Maximums/Windows HY-8 tests and passing final-head CI stand as the current evidence; no claim is made of universal parity, verified model-specific blockage, or completed #102/#103. The PR and both issue descriptions have been updated accordingly. Keep fail-closed safeguards and clear user-facing limitations. No automatic merge; final review and explicit manual authorisation still required.