AbaqusSubroutineDev/docs/corrections/uel-3d-euler-beam-uel-abi-correction.md

# 3D Euler-Bernoulli Beam UEL ABI Correction Report

## Metadata
- feature_id: uel-3d-euler-beam
- source_failure_report: `docs/abaqus-uel-subroutines-research.md`
- source_implementation_report: `docs/build-test-reports/uel-3d-euler-beam-green.md`
- source_implementation_plan: N/A; correction follows the post-review research findings
- status: corrected-for-build-test
- owner_agent: correction-agent
- date: 2026-06-12

## Failure Triage
- classification: upstream-contract plus implementation defect
- first_failed_command: `python -m unittest scripts.test_uel_3d_euler_beam_uel`; `python scripts/validate_fortran.py`
- failed_target_or_test: missing Abaqus `UEL` wrapper; adapter rejected `NSVARS=1`
- evidence_tail: wrapper source-smoke failed because `src/fortran/uel_3d_euler_beam_uel.for` was missing; Fortran ABI test failed with `actual=6 expected=0` for a valid `NSVARS=1` static call
- triage_decision: implementation-owned correction allowed after research clarified the Abaqus manual ABI

## Root Cause Summary
- root_cause_type: implementation boundary defect and stale interface policy
- summary: the step 7 code implemented a testable kernel and no-Abaqus adapter, but did not expose the top-level Abaqus `SUBROUTINE UEL(...)`. The adapter also kept the pre-research `NSVARS=0` policy, conflicting with the documented `*USER ELEMENT, VARIABLES` requirement for a positive allocation.
- why_minimal_fix_is_allowed: the correction preserves the existing kernel formulation and only fixes the Abaqus-facing call boundary, state-variable allocation check, and static-procedure `LFLAGS` validation.

## Correction Scope

| file | change_type | reason | in_scope |
| --- | --- | --- | --- |
| `src/fortran/uel_3d_euler_beam_uel.for` | source | add fixed-form Abaqus `UEL` wrapper with manual signature, `ABA_PARAM.INC`, manual dimensions, adapter call, and fatal `XIT` path | true |
| `src/fortran/uel_3d_euler_beam_abi_adapter.f90` | source | accept `NSVARS>=1`, use explicit/manual-style array bounds, and validate `LFLAGS(1)` / `LFLAGS(4)` | true |
| `src/fortran/uel_3d_euler_beam_kernel.f90` | source | add status ids for unsupported `LFLAGS(1)` and `LFLAGS(4)` | true |
| `scripts/test_uel_3d_euler_beam_uel.py` | test | verify wrapper signature, include, dimensions, adapter call, and fatal path without requiring Abaqus include files | true |
| `tests/test_uel_3d_euler_beam_uel.py` | test | expose a related test path for the production-source TDD guard | true |
| `tests/fortran/uel_3d_euler_beam/test_abi_static.f90` | test | update valid adapter calls to `NSVARS=1` and explicit static `LFLAGS` values | true |
| `tests/fortran/uel_3d_euler_beam/test_invalid_inputs.f90` | test | add `NSVARS<1`, `LFLAGS(1)`, and `LFLAGS(4)` diagnostics | true |
| `tests/fortran/test_uel_3d_euler_beam_abi_adapter.f90` | test | update source-smoke adapter call to the corrected policy | true |
| `docs/io-definitions/uel-3d-euler-beam.md` | documentation | align current interface contract with the implemented Abaqus-facing policy | true |
| `docs/reference-models/uel-3d-euler-beam.md` | documentation | align test model and input-deck requirements with `VARIABLES=1` and wrapper source-smoke | true |

Excluded files:
- reference artifacts: unchanged
- tolerances: unchanged
- formulation matrix/residual equations: unchanged

## Verification Evidence

| order | command | exit_code | result | evidence |
| --- | --- | --- | --- | --- |
| 1 | `python -m unittest scripts.test_uel_3d_euler_beam_uel` before implementation | 1 | RED | failed because `src/fortran/uel_3d_euler_beam_uel.for` did not exist |
| 2 | `python scripts/validate_fortran.py` before implementation | 1 | RED | `uel_3d_euler_beam_abi_static` failed because `NSVARS=1` returned `UEL3DEB_E006_NSVARS` |
| 3 | `python -m unittest scripts.test_uel_3d_euler_beam_uel` after implementation | 0 | pass | wrapper source-smoke passed |
| 4 | `python scripts/validate_fortran.py` after implementation | 0 | pass | all six no-Abaqus Fortran manifest executables compiled and passed with Intel `ifx` |
| 5 | `python -m unittest discover -s scripts -p "test_*.py"` | 0 | pass | 60 Python harness/source-smoke tests passed |
| 6 | `python scripts/validate_workspace.py` | 0 | pass | reference artifact metadata validation and Fortran validation succeeded |
| 7 | `git diff --check` | 0 | pass | no whitespace errors; line-ending warnings only |

## Traceability

| requirement_or_finding | corrected_file | acceptance_criterion |
| --- | --- | --- |
| C-UEL-001 / C-UEL-002 | `src/fortran/uel_3d_euler_beam_uel.for` | top-level external `SUBROUTINE UEL(...)` exists with manual ABI arguments |
| C-UEL-003 | `src/fortran/uel_3d_euler_beam_uel.for`, `src/fortran/uel_3d_euler_beam_abi_adapter.f90` | Abaqus-facing boundary uses manual dimensions; adapter remains testable |
| C-UEL-004 | `src/fortran/uel_3d_euler_beam_abi_adapter.f90`, `docs/io-definitions/uel-3d-euler-beam.md` | valid static adapter calls use `NSVARS=1`; `NSVARS<1` returns `UEL3DEB_E006_NSVARS` |
| C-UEL-005 | `src/fortran/uel_3d_euler_beam_abi_adapter.f90` | unsupported `LFLAGS(1)` and `LFLAGS(4)` return dedicated diagnostics |

## Handoff Recommendation

| target_agent | reason | required_input |
| --- | --- | --- |
| Build/Test Executor Agent | run full workspace validation after correction | this report and command evidence |
| Reference Verification Agent | update external model expectations to `VARIABLES=1` before user-generated Abaqus artifacts are prepared | corrected I/O and reference-model documents |
| Physics Evaluation Agent | no formulation behavior changed; external CSV physics checks remain pending | future user-provided reference bundles |

## Stop Condition
- repeated_failure: false
- upstream_ambiguity: false
- reference_artifact_gap: true
- environment_blocker: false
- next_required_decision: user must still provide external Abaqus artifacts before solver-result validation can complete