FESADev/docs/requirements/linear-static-3d-euler-beam.md

# Linear Static 3D Euler Beam Requirements

## Metadata

- feature_id: `linear-static-3d-euler-beam`
- title: `Linear Static 3D Euler Beam`
- status: `approved`
- owner_agent: `requirement-agent`
- date: `2026-08-09`
- approved_design: `docs/superpowers/specs/2026-08-08-linear-static-3d-euler-beam-design.md`
- approval_basis: design `status: approved`, user approval on `2026-08-08`, and amendment on `2026-08-09`
- source_formulation: `docs/formulations/3d-isoparametric-euler-beam-formulation.md`
- reference_baseline: `reference/cantilever beam/` at source commit `2b34d0b`

## Purpose

이 baseline은 승인된 Abaqus `.inp` subset을 입력으로 받아 2절점 3차원
Euler–Bernoulli beam의 단일 선형 정적 step을 해석하고, 검증 가능한 변위, 반력,
요소 결과와 축응력을 authoritative `results.h5`에 기록하는 FESA V0 기능을 정의한다.
이 문서는 승인 설계를 검증 가능한 `shall` 요구조건으로 전사하며 Abaqus full
compatibility, 새로운 수학 계약 또는 새로운 구현 정책을 추가하지 않는다.

## In Scope

- 입력 파일당 하나의 `*STEP, *STATIC` 선형 정적 해석
- small displacement, small rotation, 균질 선형 등방 탄성
- 2절점 직선 prismatic 3D Euler–Bernoulli beam과 Abaqus `TYPE=B33`
- 절점당 전역 자유도 `[UX, UY, UZ, URX, URY, URZ]`
- 축 변형, 두 방향 굽힘, Saint-Venant 비틀림
- nodal concentrated load와 zero/nonzero prescribed displacement
- formulation 검증용 constant local line-load equivalent nodal vector kernel
- identity `*PART/*ASSEMBLY/*INSTANCE` wrapper와 stable source identity
- deterministic COO-to-CSR assembly, element-local oneTBB 계산, MKL PARDISO factorization/substitution
- HDF5 displacement, reaction, equilibrium end action, section resultant, generalized strain/resultant, axial `S11`
- 승인된 `reference/cantilever beam/` legacy B33 bundle의 displacement, reaction, section resultant comparison

## Out Of Scope

- Abaqus full compatibility와 Abaqus `TYPE=B31` Timoshenko beam
- 다중 analysis step과 step 간 load/BC propagation
- instance translation/rotation, nested assembly, dependent/independent mesh semantics
- `I12 != 0`, taper, offset, release, curved beam, warping
- Abaqus `*DLOAD` 입력과 Domain distributed-load object
- 기하·재료비선형, dynamics, contact, thermal effects
- transverse shear stress와 torsional shear stress recovery
- beam stress에 대한 Abaqus reference comparison
- Abaqus, Nastran 또는 다른 reference solver 실행과 reference artifact 생성·수정·복원

## Analysis Definition

- analysis_type: single-step linear static
- kinematics: small displacement and small rotation
- element: two-node straight prismatic 3D Euler–Bernoulli beam, Abaqus `TYPE=B33`
- nodal_dofs: global `[UX, UY, UZ, URX, URY, URZ]`
- deformation_modes: axial, local-y/local-z bending, Saint-Venant torsion
- material_model: homogeneous isotropic linear elasticity from `E` and `nu`
- boundary_conditions: DOF 1 through 6, including nonzero prescribed displacement
- loads: nodal concentrated load; formulation-only constant local line-load kernel
- local_coordinate_system: `t -> local x`, Abaqus first section axis `n1 -> local y`, `t x n1 -> local z`, right-handed
- units: input uses a user-consistent unit system; the approved cantilever reference bundle is SI
- authoritative_output: HDF5 `results.h5`


## Input Requirements

- **FESA-REQ-LS3DEB-001** — The FESA solver shall accept exactly one `*STEP` containing `*STATIC` per input file and shall reject a second analysis step with a structured unsupported diagnostic.
- **FESA-REQ-LS3DEB-002** — The FESA solver shall analyze only straight, prismatic, two-node 3D Euler–Bernoulli beams under small-displacement, small-rotation, linear-static assumptions.
- **FESA-REQ-LS3DEB-003** — The FESA solver shall assign each beam node the six global DOFs `[UX, UY, UZ, URX, URY, URZ]` in that order.
- **FESA-REQ-LS3DEB-004** — The FESA solver shall support axial deformation, bending about both local section axes, Saint-Venant torsion, and homogeneous isotropic linear elasticity.
- **FESA-REQ-LS3DEB-005** — The FESA solver shall map only `*ELEMENT, TYPE=B33` to the V0 Euler–Bernoulli beam formulation.
- **FESA-REQ-LS3DEB-006** — The FESA solver shall reject `*ELEMENT, TYPE=B31` with `unsupported-element-formulation` and shall not reinterpret B31 as B33.
- **FESA-REQ-LS3DEB-007** — The FESA solver shall support nodal `*CLOAD` and `*BOUNDARY` data for DOFs 1 through 6, including nonzero prescribed displacement.
- **FESA-REQ-LS3DEB-008** — The element verification contract shall include a constant local line-load equivalent nodal vector kernel, while the V0 parser and CLI shall not support `*DLOAD` or create a Domain distributed-load object.
- **FESA-REQ-LS3DEB-009** — The parser shall support exactly `*HEADING`; `*PART`, `*END PART`; `*NODE`; `*ELEMENT, TYPE=B33`; `*NSET`, `*ELSET`, including `GENERATE`; `*MATERIAL`, `*ELASTIC`; `*BEAM GENERAL SECTION, SECTION=GENERAL`; `*SECTION POINTS`; `*ASSEMBLY`, `*END ASSEMBLY`; `*INSTANCE`, `*END INSTANCE`; `*BOUNDARY`; `*CLOAD`; `*STEP`, `*STATIC`, and `*END STEP` as model/procedure keywords.
- **FESA-REQ-LS3DEB-010** — The parser shall interpret keyword and parameter names case-insensitively, recognize `**` comment lines, and preserve source label text for external identity.
- **FESA-REQ-LS3DEB-011** — The parser shall accept `*BOUNDARY` rows only as `target, first_dof, last_dof[, value]`, default an omitted value to zero, and accept `*CLOAD` rows only as `target, dof, magnitude`; targets shall resolve by source node label or node set, including assembly-level sets with `INSTANCE`.
- **FESA-REQ-LS3DEB-012** — The semantic mapping shall read general-section data as `A, I11, I12, I22, J`, require `I12=0`, map `Iy=I11` and `Iz=I22`, and construct local axes as `n1 -> y` and `t x n1 -> z`.
- **FESA-REQ-LS3DEB-013** — A general beam section shall reference a material whose isotropic `*ELASTIC` data provides exactly `E, nu`; the solver shall compute `G=E/(2(1+nu))` and require positive `E`, `G`, `A`, `Iy`, `Iz`, and `J`.
- **FESA-REQ-LS3DEB-014** — Before element calculation, the solver shall require `L > 1e-12 * max(1, norm(X1), norm(X2))` and `norm(a_perp) > 1e-12 * max(1, norm(a))`; zero/near-zero length, a zero guide vector, and a tangent-parallel guide vector shall produce structured model-validation diagnostics.
- **FESA-REQ-LS3DEB-015** — `*PART/*ASSEMBLY/*INSTANCE` mapping shall preserve `SourceEntityId { instance_name, source_label }` for nodes, elements, and sets and shall map it deterministically to a separate stable Domain internal index.
- **FESA-REQ-LS3DEB-016** — The semantic model shall allow multiple identity instances of the same part without merging their source identities.
- **FESA-REQ-LS3DEB-017** — An instance containing translation or rotation data shall be rejected with `unsupported-instance-transform`.
- **FESA-REQ-LS3DEB-018** — Nested assembly and dependent/independent mesh semantics shall be rejected as unsupported rather than silently approximated.
- **FESA-REQ-LS3DEB-019** — The parser shall issue structured warnings and no-op the exact allowlist `*PREPRINT`, `*RESTART`, `*TRANSVERSE SHEAR STIFFNESS`, `*OUTPUT, FIELD`, `*OUTPUT, HISTORY`, `*NODE OUTPUT`, `*ELEMENT OUTPUT`, `*CONTACT OUTPUT`, and unsupported variable data belonging to those output requests.
- **FESA-REQ-LS3DEB-020** — Unsupported model-affecting keywords outside the no-op allowlist shall be errors, and accepted Abaqus output requests shall not change or suppress FESA's mandatory HDF5 results.

## Architecture and Execution Requirements

- **FESA-REQ-LS3DEB-021** — `Domain` shall own the complete parsed model and remain effectively immutable after mapping; `AnalysisModel` shall expose references or IDs for the single active step without copying Domain objects.
- **FESA-REQ-LS3DEB-022** — `DofManager` alone shall own node DOF definitions, full/free equation numbering, constrained/free mappings, element scatter maps, sparse patterns, and full/reduced vector reconstruction; Node and Element shall not store equation IDs.
- **FESA-REQ-LS3DEB-023** — V0 `AnalysisState` shall own full displacement, external/internal force, residual, constrained reaction, step/frame identity, and element recovery rows and shall not allocate velocity, acceleration, temperature, iteration history, or nonlinear element state.
- **FESA-REQ-LS3DEB-024** — Element-local stiffness work shall use the `ParallelFor`/oneTBB boundary, and global assembly shall deterministically reduce element contributions in stable element order from COO triplets into a 0-based CSR matrix.
- **FESA-REQ-LS3DEB-025** — MKL, TBB, and HDF5 API/types shall remain behind the `LinearSolver`, `ParallelFor`, dense/sparse math, and `ResultsWriter` adapter boundaries; `Vector` shall use contiguous doubles, `Matrix` row-major contiguous doubles, and `SparseMatrix` a separate 0-based CSR representation.
- **FESA-REQ-LS3DEB-026** — The linear-static lifecycle shall assemble and partition stiffness, call `Kff` factorization, and only then assemble the full load vector, form the effective RHS, and perform substitution; factorization and substitution shall remain observably separate.
- **FESA-REQ-LS3DEB-027** — For prescribed displacement `dc`, the solver shall form `rhs=Ff-Kfc*dc`, reconstruct the full displacement after substitution, and recover constrained reaction from `K*d-F`, equivalently `Rc=Kcf*df+Kcc*dc-Fc`, rather than a separate end-force sum.

## Output Requirements

- **FESA-REQ-LS3DEB-028** — The sole authoritative solver output shall be HDF5 `results.h5`; the writer shall complete a temporary file before replacing the final path and shall leave no incomplete final file after a writer failure.
- **FESA-REQ-LS3DEB-029** — HDF5 schema v0 shall contain `/metadata`, `/model/nodes`, `/model/elements`, `/steps/<step-name>/frames/0/nodal/displacement`, `/steps/<step-name>/frames/0/nodal/reaction`, `/steps/<step-name>/frames/0/element/end_force_local`, `/steps/<step-name>/frames/0/element/section_resultant`, `/steps/<step-name>/frames/0/element/generalized_strain`, `/steps/<step-name>/frames/0/element/stress_s11`, and `/diagnostics`.
- **FESA-REQ-LS3DEB-030** — HDF5 metadata/model identity shall record schema version, solver version, source input identity, unit-system label, coordinate convention, element formulation, stable internal IDs, and instance/source-label mappings; ordinary input shall use `user-consistent-unspecified`, while the approved cantilever comparison shall apply its external SI contract without inferring SI from `.inp` alone.
- **FESA-REQ-LS3DEB-031** — Output shall include every node's global displacement/reaction in `[UX, UY, UZ, URX, URY, URZ]`, local endpoint equilibrium end actions in `[FX,FY,FZ,MX,MY,MZ]`, endpoint section resultants in `[N,T,My,Mz]`, and generalized strain/resultant values at the two Gauss points, independent of Abaqus output requests.
- **FESA-REQ-LS3DEB-032** — The solver shall output axial `S11` at both Gauss points and each input section point, or at centroid `(0,0)` with `source=fesa-default` when section points are absent; transverse/torsional shear stress shall not be recovered, and Abaqus beam-stress reference comparison shall remain explicit N/A while analytical/unit and HDF5 schema tests remain mandatory.
- **FESA-REQ-LS3DEB-033** — The CLI shall support `fesa.exe <model.inp> --output <results.h5>`, default output to the current directory's `results.h5`, use exit codes `0=success`, `2=usage`, `3=input`, `4=model`, `5=solver`, `6=HDF5`, and emit `severity`, `code`, `file`, `line`, `keyword`, `entity_identity`, and `message` diagnostics to stderr in deterministic order.

## Verification Requirements

- **FESA-REQ-LS3DEB-034** — Every production C++ behavior shall be developed in one step as GoogleTest `RED -> GREEN -> VERIFY`, with a related C++ test file, focused CTest evidence, full MSVC x64 Debug build/CTest evidence, at least one discovered test, and no new warning under the FESA target's `/W4 /WX` policy.
- **FESA-REQ-LS3DEB-035** — Numerical tests shall satisfy normalized `1e-12` for stiffness symmetry and two-point-Gauss/closed-form agreement, normalized `1e-10` for rigid-mode and linear-system residual, and relative `1e-9` for analytical solutions, while checking six rigid modes, rank 6, positive deformation energy, transformation orthogonality/energy invariance, prescribed-displacement recovery, and axial/torsion/two-plane bending benchmarks.

## Verification Quantities

- nodal_displacement: required, global six components, HDF5-to-Abaqus CSV comparison
- reaction: required, global six components plus global force/moment equilibrium
- equilibrium_end_action: required, local endpoint six components; unit/analytical and physics tests
- section_resultant: required, endpoint `[N,T,My,Mz]`, node-station-normalized reference comparison
- generalized_strain_and_resultant: required at two Gauss points; formulation and schema tests
- stress: axial `S11` required; Abaqus reference comparison N/A
- residual: required, free-DOF and normalized global equilibrium checks
- energy_and_modes: required for symmetry, rank, rigid modes, and transform invariance


## Tolerance Policy

- **FESA-REQ-LS3DEB-036** — The approved B33 reference comparison shall group rows by the same model, step/frame, quantity, and component, compute `reference_scale` only from read-only Abaqus values, and apply `absolute_floor + 1e-6 * reference_scale` to every matched row.
- **FESA-REQ-LS3DEB-037** — For the approved SI bundle, displacement and rotation shall use `absolute_floor=1e-9`, force and moment shall use `absolute_floor=1e-3`, and a zero component scale shall use the applicable absolute floor alone.
- **FESA-REQ-LS3DEB-038** — Reference values shall not be zero-clamped and rows shall not be dropped; missing, extra, duplicate, nonfinite, schema-mismatched, or identity-mismatched rows shall fail before tolerance evaluation.
- **FESA-REQ-LS3DEB-039** — The verification report shall record every row decision and maximum absolute error, component-scale normalized error, RMS error, norm error, and worst row/component for each compared quantity.

## Reference Artifact Requirements

The approved logical model is `cantilever-beam-b33`, schema is
`abaqus-cae-report-csv-v0`, source commit is `2b34d0b`, generator is
`Abaqus/CAE Learning Edition 2024`, and the coordinate/output contract is global Cartesian
nodal output plus beam-local section-force output at `Step-1`, increment 1, step time 1.0.

- **FESA-REQ-LS3DEB-040** — The V0 reference baseline shall use the exact read-only files `reference/cantilever beam/cantilever beam.inp`, `reference/cantilever beam/cantilever beam displacements.csv`, `reference/cantilever beam/cantilever beam reactions.csv`, and `reference/cantilever beam/cantilever beam elemental forces.csv` without rename, rewrite, correction, or restoration; absent `metadata.json` is allowed by project-wide policy and `README.md` is N/A for this approved legacy bundle.
- **FESA-REQ-LS3DEB-041** — Before comparison, artifact validation shall confirm all four files, `TYPE=B33`, expected CAE report headers, unique row keys, and finite values; failure shall be classified as `needs-reference-artifacts` or `schema-mismatch` and comparison shall not start.
- **FESA-REQ-LS3DEB-042** — Reference verification shall compare displacement by source-node identity (`U1/U2/U3/UR1/UR2/UR3`), reaction by source-node identity (`RF1/RF2/RF3/RM1/RM2/RM3`), and node-station-normalized section resultant by `SF1->N`, `SM1->My`, `SM2->Mz`, `SM3->T`; adjacent interior endpoints shall first agree within approved tolerance and shall not be averaged to hide a mismatch.
- **FESA-REQ-LS3DEB-043** — Reference comparison shall run only after build/test passes; physics sanity shall run only after reference comparison passes and shall check global force/moment equilibrium, reaction sign, displacement direction, symmetry, element section-force consistency, and normalized residual; release readiness shall require all prior gate evidence and known limitations.
- **FESA-REQ-LS3DEB-044** — FESA agents and Harness shall not execute Abaqus, Nastran, or another reference solver and shall not create, modify, rename, or restore reference artifacts; release documentation shall not claim support for any Out Of Scope behavior.


## Requirement Verification Matrix

| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| FESA-REQ-LS3DEB-001 | The FESA solver shall accept exactly one `*STEP` containing `*STATIC` per input file and shall reject a second analysis step with a structured unsupported diagnostic. | analysis | Preserve the approved V0 single-step boundary. | Approved design §§2, 6.1; PRD FESA-PRD-011 | must | Parser/semantic unit test; CLI integration test | One static step runs; a second step fails with a structured unsupported diagnostic. | N/A | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-002 | The FESA solver shall analyze only straight, prismatic, two-node 3D Euler–Bernoulli beams under small-displacement, small-rotation, linear-static assumptions. | analysis | Bound the formulation and validation domain. | Approved design §2; formulation §2 | must | Model validation test; formulation review | Accepted models satisfy every listed assumption and excluded procedures are not represented as supported. | N/A | research-agent; formulation-agent; numerical-review-agent | approved |
| FESA-REQ-LS3DEB-003 | The FESA solver shall assign each beam node the six global DOFs `[UX, UY, UZ, URX, URY, URZ]` in that order. | analysis | Keep assembly and result components deterministic. | Approved design §§2, 4.3 | must | DofManager unit test; HDF5 schema test | DOF mapping and nodal result columns use the exact approved order. | Exact ordering | formulation-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-004 | The FESA solver shall support axial deformation, bending about both local section axes, Saint-Venant torsion, and homogeneous isotropic linear elasticity. | analysis | Define the complete V0 beam physics. | Approved design §2; formulation §§2, 10 | must | Element unit tests; analytical benchmarks | Axial, torsion, local-y bending, and local-z bending cases recover the approved analytical quantities. | Relative `1e-9` analytical | research-agent; formulation-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-005 | The FESA solver shall map only `*ELEMENT, TYPE=B33` to the V0 Euler–Bernoulli beam formulation. | input | Preserve Abaqus element-family meaning. | Approved design §6.3; PRD FESA-PRD-011 | must | Parser/semantic unit test | B33 creates the approved beam semantic object and reaches model validation. | N/A | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-006 | The FESA solver shall reject `*ELEMENT, TYPE=B31` with `unsupported-element-formulation` and shall not reinterpret B31 as B33. | input | B31 includes transverse shear deformation. | Approved design §§2.2, 6.3; ADR-013 | must | Parser diagnostic test | B31 fails with the exact approved diagnostic code and creates no Euler beam. | Exact diagnostic code | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-007 | The FESA solver shall support nodal `*CLOAD` and `*BOUNDARY` data for DOFs 1 through 6, including nonzero prescribed displacement. | input | Exercise constrained partition and RHS correction. | Approved design §§2.1, 6.1, 7 | must | Parser test; constraint/load integration test | DOFs 1..6 map correctly and nonzero `dc` contributes to effective RHS and reaction. | Residual normalized `1e-10` | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-008 | The element verification contract shall include a constant local line-load equivalent nodal vector kernel, while the V0 parser and CLI shall not support `*DLOAD` or create a Domain distributed-load object. | scope | Verify the formulation without widening CLI input. | Approved design §§2.1, 2.2, 4.5 | must | Element unit test; parser negative test | The closed-form equivalent vector passes and `*DLOAD` is rejected without a Domain distributed-load object. | Normalized `1e-12` kernel comparison | formulation-agent; io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-009 | The parser shall support exactly `*HEADING`; `*PART`, `*END PART`; `*NODE`; `*ELEMENT, TYPE=B33`; `*NSET`, `*ELSET`, including `GENERATE`; `*MATERIAL`, `*ELASTIC`; `*BEAM GENERAL SECTION, SECTION=GENERAL`; `*SECTION POINTS`; `*ASSEMBLY`, `*END ASSEMBLY`; `*INSTANCE`, `*END INSTANCE`; `*BOUNDARY`; `*CLOAD`; `*STEP`, `*STATIC`, and `*END STEP` as model/procedure keywords. | input | Avoid a full-compatibility claim. | Approved design §6.1; ADR-003 | must | Keyword inventory review; parser tests | Every listed keyword has positive coverage and no unlisted keyword is documented as supported. | Exact keyword inventory | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-010 | The parser shall interpret keyword and parameter names case-insensitively, recognize `**` comment lines, and preserve source label text for external identity. | input | Match approved syntax and identity behavior. | Approved design §6.1 | must | Lexer/parser unit tests | Case variants parse equally, comments are ignored, and original label text survives mapping. | Exact source-label identity | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-011 | The parser shall accept `*BOUNDARY` rows only as `target, first_dof, last_dof[, value]`, default an omitted value to zero, and accept `*CLOAD` rows only as `target, dof, magnitude`; targets shall resolve by source node label or node set, including assembly-level sets with `INSTANCE`. | input | Prevent ambiguous semantic mapping. | Approved design §6.1 | must | Parser positive/negative tests | Only approved row arities and DOFs 1..6 pass, and all approved target forms resolve deterministically. | N/A | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-012 | The semantic mapping shall read general-section data as `A, I11, I12, I22, J`, require `I12=0`, map `Iy=I11` and `Iz=I22`, and construct local axes as `n1 -> y` and `t x n1 -> z`. | input | Preserve stiffness directions and signs. | Approved design §6.2; PRD FESA-PRD-019 | must | Section-mapping test; rotated-element test | Every property and right-handed local-axis mapping matches the approved contract. | Exact mapping; transform normalized `1e-12` | formulation-agent; io-definition-agent; numerical-review-agent | approved |
| FESA-REQ-LS3DEB-013 | A general beam section shall reference a material whose isotropic `*ELASTIC` data provides exactly `E, nu`; the solver shall compute `G=E/(2(1+nu))` and require positive `E`, `G`, `A`, `Iy`, `Iz`, and `J`. | input | Prevent nonphysical or indefinite stiffness. | Approved design §6.2; formulation §10 | must | Semantic/model validation tests | Complete valid data passes; malformed elasticity data or any nonpositive required property fails. | Input-consistent units; normalized `1e-12` for computed `G` | formulation-agent; io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-014 | Before element calculation, the solver shall require `L > 1e-12 * max(1, norm(X1), norm(X2))` and `norm(a_perp) > 1e-12 * max(1, norm(a))`; zero/near-zero length, a zero guide vector, and a tangent-parallel guide vector shall produce structured model-validation diagnostics. | input | Prevent singular geometry and undefined local axes. | Approved design §6.2; formulation §§3.1, 19 | must | Geometry validation tests | Values at or below either approved threshold fail and valid values produce a right-handed orthonormal frame. | Both thresholds use coefficient `1e-12` | numerical-review-agent; io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-015 | `*PART/*ASSEMBLY/*INSTANCE` mapping shall preserve `SourceEntityId { instance_name, source_label }` for nodes, elements, and sets and shall map it deterministically to a separate stable Domain internal index. | model | Make row mapping and diagnostics traceable. | Approved design §§4.1, 6.4 | must | Semantic mapping and determinism tests | Instance/source labels round-trip and map to stable unique internal IDs. | Exact identity | io-definition-agent; reference-model-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-016 | The semantic model shall allow multiple identity instances of the same part without merging their source identities. | model | Support approved wrapper reuse without transforms. | Approved design §§2.1, 6.4; ADR-013 | must | Multi-instance semantic integration test | Nodes, elements, and sets for each identity instance remain distinct and deterministic. | Exact identity | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-017 | An instance containing translation or rotation data shall be rejected with `unsupported-instance-transform`. | model | V0 has no transform semantics. | Approved design §§2.2, 6.4 | must | Parser/semantic negative tests | Any translation or rotation data fails with the exact approved diagnostic code. | Exact diagnostic code | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-018 | Nested assembly and dependent/independent mesh semantics shall be rejected as unsupported rather than silently approximated. | model | Prevent silent topology changes. | Approved design §§2.2, 6.4 | must | Semantic negative tests | Each excluded construct produces a structured unsupported diagnostic and no Domain model. | N/A | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-019 | The parser shall issue structured warnings and no-op the exact allowlist `*PREPRINT`, `*RESTART`, `*TRANSVERSE SHEAR STIFFNESS`, `*OUTPUT, FIELD`, `*OUTPUT, HISTORY`, `*NODE OUTPUT`, `*ELEMENT OUTPUT`, `*CONTACT OUTPUT`, and unsupported variable data belonging to those output requests. | input | Accept the legacy input without changing analysis meaning. | Approved design §6.5; PRD FESA-PRD-013 | must | Parser diagnostic test | Every allowlisted keyword/data form yields deterministic warnings, no semantic effect, and no error. | Exact allowlist | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-020 | Unsupported model-affecting keywords outside the no-op allowlist shall be errors, and accepted Abaqus output requests shall not change or suppress FESA's mandatory HDF5 results. | input/output | Keep the supported subset explicit. | Approved design §6.5; ADR-003 | must | Parser negative test; HDF5 integration test | An unlisted model keyword fails and mandatory datasets exist with or without allowed output requests. | Exact dataset inventory | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-021 | `Domain` shall own the complete parsed model and remain effectively immutable after mapping; `AnalysisModel` shall expose references or IDs for the single active step without copying Domain objects. | architecture | Preserve approved ownership and activation boundaries. | Approved design §§4.1, 4.2; ADR-004 | must | Unit test; architecture review | Active-step view construction neither copies nor mutates Domain objects. | N/A | implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-022 | `DofManager` alone shall own node DOF definitions, full/free equation numbering, constrained/free mappings, element scatter maps, sparse patterns, and full/reduced vector reconstruction; Node and Element shall not store equation IDs. | architecture | Prevent distributed numbering state. | Approved design §4.3; ADR-004 | must | DofManager tests; dependency/code review | All maps reconstruct correctly and no Node or Element stores equation IDs. | Exact mapping | implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-023 | V0 `AnalysisState` shall own full displacement, external/internal force, residual, constrained reaction, step/frame identity, and element recovery rows and shall not allocate velocity, acceleration, temperature, iteration history, or nonlinear element state. | architecture | Keep V0 state minimal and traceable. | Approved design §4.4; PRD FESA-PRD-005 | must | State unit/integration tests | All required state is connected to output and every excluded state remains unallocated. | N/A | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-024 | Element-local stiffness work shall use the `ParallelFor`/oneTBB boundary, and global assembly shall deterministically reduce element contributions in stable element order from COO triplets into a 0-based CSR matrix. | architecture | Ensure repeatable sparse assembly and reference rows. | Approved design §§2.1, 7; ADR-008, ADR-009 | must | Repeated assembly tests; CSR structure tests | Repeated and thread-count-varied runs produce identical CSR ordering and numerically identical values. | Stable ordering; normalized numeric `1e-12` | numerical-review-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-025 | MKL, TBB, and HDF5 API/types shall remain behind the `LinearSolver`, `ParallelFor`, dense/sparse math, and `ResultsWriter` adapter boundaries; `Vector` shall use contiguous doubles, `Matrix` row-major contiguous doubles, and `SparseMatrix` a separate 0-based CSR representation. | architecture | Isolate external backends from solver core. | Approved design §5; ADR-006 | must | Dependency review; math/backend unit tests | No public core API exposes backend types and every storage layout matches the approved contract. | N/A | implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-026 | The linear-static lifecycle shall assemble and partition stiffness, call `Kff` factorization, and only then assemble the full load vector, form the effective RHS, and perform substitution; factorization and substitution shall remain observably separate. | execution | Preserve reusable factorization and failure classification. | Approved design §§1, 7; ADR-007 | must | Orchestration test; solver-adapter test | The event trace is stiffness, partition, factorize, load, RHS, solve and no opaque solve hides factorization. | Exact event order | implementation-planning-agent; build-test-executor-agent | approved |
| FESA-REQ-LS3DEB-027 | For prescribed displacement `dc`, the solver shall form `rhs=Ff-Kfc*dc`, reconstruct the full displacement after substitution, and recover constrained reaction from `K*d-F`, equivalently `Rc=Kcf*df+Kcc*dc-Fc`, rather than a separate end-force sum. | execution | Correctly handle nonzero constraints and equilibrium. | Approved design §7; formulation §§15, 16.5 | must | Constraint/load integration and residual tests | RHS, full displacement, and constrained reactions match the approved partition equations. | Residual normalized `1e-10` | formulation-agent; numerical-review-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-028 | The sole authoritative solver output shall be HDF5 `results.h5`; the writer shall complete a temporary file before replacing the final path and shall leave no incomplete final file after a writer failure. | output | Prevent ambiguous or partial results. | Approved design §9; ADR-005 | must | HDF5 integration/atomicity tests | Success produces the final file and injected failure leaves no incomplete final `results.h5`. | N/A | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-029 | HDF5 schema v0 shall contain `/metadata`, `/model/nodes`, `/model/elements`, `/steps/<step-name>/frames/0/nodal/displacement`, `/steps/<step-name>/frames/0/nodal/reaction`, `/steps/<step-name>/frames/0/element/end_force_local`, `/steps/<step-name>/frames/0/element/section_resultant`, `/steps/<step-name>/frames/0/element/generalized_strain`, `/steps/<step-name>/frames/0/element/stress_s11`, and `/diagnostics`. | output | Give downstream comparison a stable schema root. | Approved design §9 | must | HDF5 schema test | Every named path exists at frame 0 with documented identity and rank/component contracts. | Exact paths | io-definition-agent; reference-verification-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-030 | HDF5 metadata/model identity shall record schema version, solver version, source input identity, unit-system label, coordinate convention, element formulation, stable internal IDs, and instance/source-label mappings; ordinary input shall use `user-consistent-unspecified`, while the approved cantilever comparison shall apply its external SI contract without inferring SI from `.inp` alone. | output | Make results auditable without guessing units or identity. | Approved design §9; ADR-005 | must | Metadata/schema test; reference contract review | Every field is present, ordinary runs use the exact label, and legacy comparison records external SI provenance. | Exact labels and identity | io-definition-agent; reference-model-agent; reference-verification-agent | approved |
| FESA-REQ-LS3DEB-031 | Output shall include every node's global displacement/reaction in `[UX, UY, UZ, URX, URY, URZ]`, local endpoint equilibrium end actions in `[FX,FY,FZ,MX,MY,MZ]`, endpoint section resultants in `[N,T,My,Mz]`, and generalized strain/resultant values at the two Gauss points, independent of Abaqus output requests. | output | Separate equilibrium, section, and generalized results. | Approved design §§8, 9 | must | Recovery unit tests; HDF5 schema test | Every component order and endpoint/Gauss location matches the contract in runs with and without output requests. | Analytical `1e-9`; reference policy where applicable | formulation-agent; io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-032 | The solver shall output axial `S11` at both Gauss points and each input section point, or at centroid `(0,0)` with `source=fesa-default` when section points are absent; transverse/torsional shear stress shall not be recovered, and Abaqus beam-stress reference comparison shall remain explicit N/A while analytical/unit and HDF5 schema tests remain mandatory. | output | Retain useful stress recovery without inventing a reference baseline. | Approved design §§2.2, 8.3, 12 | must | Stress unit/analytical test; HDF5 schema test; report review | Correct stress rows and fallback label exist, no shear stress is emitted, and reference report marks stress N/A. | Analytical relative `1e-9`; Abaqus reference N/A | formulation-agent; io-definition-agent; reference-verification-agent | approved |
| FESA-REQ-LS3DEB-033 | The CLI shall support `fesa.exe <model.inp> --output <results.h5>`, default output to the current directory's `results.h5`, use exit codes `0=success`, `2=usage`, `3=input`, `4=model`, `5=solver`, `6=HDF5`, and emit `severity`, `code`, `file`, `line`, `keyword`, `entity_identity`, and `message` diagnostics to stderr in deterministic order. | output | Stabilize automation and failure classification. | Approved design §10 | must | CLI integration and diagnostic ordering tests | Default/explicit output works and every failure class returns its exact code and complete ordered fields. | Exact codes, fields, and order | io-definition-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-034 | Every production C++ behavior shall be developed in one step as GoogleTest `RED -> GREEN -> VERIFY`, with a related C++ test file, focused CTest evidence, full MSVC x64 Debug build/CTest evidence, at least one discovered test, and no new warning under the FESA target's `/W4 /WX` policy. | verification | Enforce project TDD and warning policy. | Approved design §§11.1, 11.4; ADR-012 | must | Implementation report; build/CTest logs | The related test fails first, then focused/full tests pass, discovery finds tests, and FESA emits no warning. | Zero test failures and new warnings | implementation-planning-agent; implementation-agent; build-test-executor-agent | approved |
| FESA-REQ-LS3DEB-035 | Numerical tests shall satisfy normalized `1e-12` for stiffness symmetry and two-point-Gauss/closed-form agreement, normalized `1e-10` for rigid-mode and linear-system residual, and relative `1e-9` for analytical solutions, while checking six rigid modes, rank 6, positive deformation energy, transformation orthogonality/energy invariance, prescribed-displacement recovery, and axial/torsion/two-plane bending benchmarks. | verification | Detect sign, integration, rank, and transform defects. | Approved design §§11.2, 11.3; formulation §18 | must | Unit, analytical, and orchestration tests | Every listed invariant and analytical case passes at its stated threshold. | `1e-12` matrix; `1e-10` residual; `1e-9` analytical | formulation-agent; numerical-review-agent; implementation-planning-agent | approved |
| FESA-REQ-LS3DEB-036 | The approved B33 reference comparison shall group rows by the same model, step/frame, quantity, and component, compute `reference_scale` only from read-only Abaqus values, and apply `absolute_floor + 1e-6 * reference_scale` to every matched row. | tolerance | Give zero and nonzero rows one deterministic rule. | Approved design §11.3; ADR-014 | must | Comparison unit/integration test; report review | Every group uses the Abaqus-only maximum absolute scale and every matched row uses the exact formula. | Relative coefficient `1e-6` | reference-model-agent; reference-verification-agent | approved |
| FESA-REQ-LS3DEB-037 | For the approved SI bundle, displacement and rotation shall use `absolute_floor=1e-9`, force and moment shall use `absolute_floor=1e-3`, and a zero component scale shall use the applicable absolute floor alone. | tolerance | Preserve dimensional meaning near zero. | Approved design §11.3; ADR-014 | must | Comparison tests with zero/near-zero rows | Each quantity uses its exact SI floor and zero-scale groups use no relative contribution. | SI `1e-9` displacement/rotation; `1e-3` force/moment | reference-model-agent; reference-verification-agent | approved |
| FESA-REQ-LS3DEB-038 | Reference values shall not be zero-clamped and rows shall not be dropped; missing, extra, duplicate, nonfinite, schema-mismatched, or identity-mismatched rows shall fail before tolerance evaluation. | tolerance | Prevent false passes through omission or clamping. | Approved design §§11.3, 12; ADR-014 | must | Negative comparison tests | Every listed invalid case fails before numeric comparison and zero values remain unchanged. | No ignored invalid rows | reference-verification-agent | approved |
| FESA-REQ-LS3DEB-039 | The verification report shall record every row decision and maximum absolute error, component-scale normalized error, RMS error, norm error, and worst row/component for each compared quantity. | tolerance | Make the pass/fail decision auditable. | Approved design §11.3; ADR-014 | must | Verification report schema/review | Per-row decisions and all required aggregate/worst metrics are present for every quantity. | Report completeness | reference-verification-agent; release-agent | approved |
| FESA-REQ-LS3DEB-040 | The V0 reference baseline shall use the exact read-only files `reference/cantilever beam/cantilever beam.inp`, `reference/cantilever beam/cantilever beam displacements.csv`, `reference/cantilever beam/cantilever beam reactions.csv`, and `reference/cantilever beam/cantilever beam elemental forces.csv` without rename, rewrite, correction, or restoration; absent `metadata.json` is allowed by project-wide policy and `README.md` is N/A for this approved legacy bundle. | reference | Protect the approved correctness baseline. | Approved design §12; ADR-010, ADR-014 | must | Artifact inventory; Git diff review | Exact filenames exist and no reference file is added, removed, renamed, or content-modified. | Exact path/content identity | reference-model-agent; reference-verification-agent; release-agent | approved |
| FESA-REQ-LS3DEB-041 | Before comparison, artifact validation shall confirm all four files, `TYPE=B33`, expected CAE report headers, unique row keys, and finite values; failure shall be classified as `needs-reference-artifacts` or `schema-mismatch` and comparison shall not start. | reference | Detect stale B31 or malformed evidence. | Approved design §§6.3, 12 | must | Artifact-check integration test | All checks pass before comparison and every failure uses an approved classification. | Exact inventory and schema | reference-model-agent; reference-verification-agent | approved |
| FESA-REQ-LS3DEB-042 | Reference verification shall compare displacement by source-node identity (`U1/U2/U3/UR1/UR2/UR3`), reaction by source-node identity (`RF1/RF2/RF3/RM1/RM2/RM3`), and node-station-normalized section resultant by `SF1->N`, `SM1->My`, `SM2->Mz`, `SM3->T`; adjacent interior endpoints shall first agree within approved tolerance and shall not be averaged to hide a mismatch. | reference | Compare equivalent quantities despite legacy station rows. | Approved design §§8.2, 12 | must | Reference comparison test/report | All components match by source identity and interior endpoints pass before deterministic representative selection. | Requirements 036 and 037 policy | io-definition-agent; reference-model-agent; reference-verification-agent | approved |
| FESA-REQ-LS3DEB-043 | Reference comparison shall run only after build/test passes; physics sanity shall run only after reference comparison passes and shall check global force/moment equilibrium, reaction sign, displacement direction, symmetry, element section-force consistency, and normalized residual; release readiness shall require all prior gate evidence and known limitations. | governance | Keep numerical similarity distinct from physical/release approval. | Approved design §§11, 12, 13 | must | Gate evidence audit | Each downstream report cites the preceding pass and physics evidence covers all six checks before release review. | Relevant upstream tolerances | coordinator-agent; physics-evaluation-agent; release-agent | approved |
| FESA-REQ-LS3DEB-044 | FESA agents and Harness shall not execute Abaqus, Nastran, or another reference solver and shall not create, modify, rename, or restore reference artifacts; release documentation shall not claim support for any Out Of Scope behavior. | governance | Prevent baseline contamination and scope inflation. | Approved design §§2.2, 12; ADR-010 | must | Process audit; Git diff; release documentation review | No reference execution or artifact mutation occurs and every exclusion is recorded without a support claim. | N/A | coordinator-agent; reference-model-agent; release-agent | approved |

## Open Questions

- 이 approved requirements baseline 안에는 사용자 결정을 기다리는 항목이 없다.
- source formulation의 `needs-research` 상태와 그 문서에 남은 evidence/open-issue 항목은 후속 Research, Formulation Alignment, Numerical Review gate에서 이 승인 baseline에 맞춰 해결해야 하며, 이 Step에서 새 정책으로 해소하지 않는다.
- 이 baseline의 수치, 단위, schema, keyword, reference 경로를 바꾸려면 요구조건 변경 승인과 downstream traceability 갱신이 필요하다.

## Downstream Handoff

### Research Agent

- B33/Euler–Bernoulli 의미, slender-beam 적용 한계, 두 방향 굽힘·비틀림 benchmark와 source reliability를 조사하되 승인 범위나 tolerance를 바꾸지 않는다.
- 확인된 사실과 추론을 분리하고 unresolved evidence gap을 명시한다.

### Formulation Agent

- source formulation의 feature/status를 이 baseline과 정렬하고 DOF 순서, local-axis, `theta_y=-dw/dx`, 2점 Gauss, stiffness/recovery 부호를 추적한다.
- 요구조건을 충족하는 수학 계약만 정리하고 C++ API나 input/output schema를 설계하지 않는다.

### I/O Definition Agent

- 요구조건 009~020과 028~033을 exact parser/model/HDF5 row schema와 diagnostic 계약으로 구체화한다.
- 최소 HDF5 path, stable source identity, ordinary-run unit label, legacy SI comparison provenance를 보존한다.

### Reference Model Agent

- 요구조건 036~044에 따라 read-only legacy inventory, provenance, row keys, component mapping, artifact precheck, tolerance coverage를 계약화한다.
- `reference/cantilever beam/`의 네 파일은 어떤 방식으로도 변경하지 않는다.

### Implementation Planning Agent

- 모든 `must` row를 테스트에 추적하고 C++ production 작업마다 같은 Step 안에서 RED/GREEN/VERIFY를 증명하는 계획을 작성한다.
- factorization-before-load orchestration, nonzero prescribed displacement, deterministic assembly, atomic HDF5, CLI diagnostics, reference precheck를 독립적으로 검증 가능하게 분해한다.