# Step 14: Runtime Element and Factory

## 담당 역할과 필수 스킬

- 담당 역할: `implementation-agent`
- 필수 스킬: `harness`, `fesa-cpp-msvc-tdd`
- 이 Step만 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`로 수행한다.

## 읽어야 할 파일

- `/AGENTS.md`
- `/docs/CODINGSTYLE.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- `/docs/linear-static-3d-euler-beam/formulation.md`
- `/docs/linear-static-mitc4-shell/formulation.md`
- `/docs/cpp-object-oriented-modular-refactoring/implementation-plan.md`
- Step 12 material/property hierarchy files
- Step 13 element definition and Domain files
- `/include/fesa/elements/euler_beam_3d.h`, `/src/fesa/elements/euler_beam_3d.cpp`
- `/include/fesa/elements/mitc4_shell.h`, `/src/fesa/elements/mitc4_shell.cpp`
- element/model/result record tests
- `/src/fesa/CMakeLists.txt`, `/tests/CMakeLists.txt`
- `/phases/cpp-object-oriented-modular-refactoring/index.json`
- `/phases/cpp-object-oriented-modular-refactoring/step14.md`

## 작업

Requirement `R-ELEMENT-001`의 numerical runtime boundary를 구현한다.

1. `/tests/unit/elements/element_factory_test.cpp`를 먼저 추가한다. `C-ELEMENT-001` covers
   base-pointer virtual destruction, B33 and MITC4 factory success, stable DOF layout, stiffness
   and recovery through base, unknown/mismatched property/material/null rejection.
2. Missing `element.h` and `element_factory.h` cause RED compile failure.
3. Create `/include/fesa/elements/element.h`,
   `/include/fesa/elements/element_factory.h`, and
   `/src/fesa/elements/element_factory.cpp`; register the source and factory test in CMake.
4. Candidate interfaces:

```cpp
struct ElementDofLayout {
  SourceEntityId source_id;
  std::vector<EntityIndex> node_indices;
  std::vector<DofComponent> components_per_node;
};

struct ElementStiffnessContribution {
  ElementDofLayout layout;
  Matrix values;
};

struct BeamElementResultRows {
  std::vector<EndpointResultRow> endpoint_rows;
  std::vector<GaussResultRow> gauss_rows;
  std::vector<StressS11Row> stress_rows;
};

struct ShellElementResultRows {
  std::vector<ShellResultRow> rows;
  double physical_strain_energy;
};

using ElementResultPayload =
    std::variant<BeamElementResultRows, ShellElementResultRows>;

struct ElementResultBundle {
  SourceEntityId source_id;
  ElementResultPayload payload;
};

class Element {
 public:
  virtual ~Element() = default;
  virtual const ElementDofLayout& DofLayout() const noexcept = 0;
  virtual Result<ElementStiffnessContribution> ComputeStiffness() const = 0;
  virtual Result<ElementResultBundle> Recover(
      const Vector& full_displacement) const = 0;
};

using ElementView = std::vector<std::reference_wrapper<const Element>>;

class ElementFactory {
 public:
  Result<std::unique_ptr<Element>> Create(
      const ElementDefinition& definition,
      const Domain& domain) const;
};
```

5. The linear-static candidate owns `std::vector<std::unique_ptr<Element>>` and builds an
   `ElementView` whose lifetime is bounded by that owner. Carrier type locations may be adjusted
   to avoid circular public dependencies, but semantics and names must stay consistent for
   Steps 15–17.
6. Factory centralizes explicit definition/property/material kind compatibility, bounds checks,
   and structured diagnostic. It may use a checked kind discriminator and concrete access after
   validation; downstream consumers must not downcast.
7. Existing B33/MITC4 numerical kernels implement `Element` without changing formulation or adding
   fields meaningless to the other element.

## Acceptance Criteria

```powershell
cmake --build .harness/build --config Debug --target fesa_unit_tests
ctest --test-dir .harness/build -C Debug `
  -R "ElementFactory|EulerBeam3D|Mitc4Shell" --output-on-failure
rg -n "dynamic_cast" src/fesa include/fesa
& "C:/Program Files/LLVM/bin/clang-format.exe" --dry-run --Werror `
  include/fesa/elements/element.h include/fesa/elements/element_factory.h `
  src/fesa/elements/element_factory.cpp tests/unit/elements/element_factory_test.cpp
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```

The downcast scan must show no newly scattered consumer downcasts. If the centralized factory uses
a checked cast, document the preceding kind validation and keep it in the factory only.

## 검증 및 상태 갱신

- RED, success/rejection cases, base stiffness/recovery, downcast scan and full CTest를 summary에 기록한다.
- Formulation or result identity changes are `error`.
- 성공 시 현재 Step만 `completed`로 갱신한다.
- timestamp, retry, commit, advancement는 Executor 소유다.

## 금지사항

- Semantic definition and runtime kernel을 one class로 합치지 마라.
- Future element registry/global static registration을 추가하지 마라.
- Giant common result record with meaningless optional fields를 만들지 마라.
- 직접 commit하거나 hook script를 수동 실행하지 마라.