# Analysis Model Objects Implementation Plan

## Metadata
- feature_id: analysis-model-objects
- source_requirement: AGENTS.md; docs/ARCHITECTURE.md; docs/ADR.md
- source_research: N/A for this architecture/model-object slice
- source_formulation: N/A for this architecture/model-object slice
- source_numerical_review: N/A for this architecture/model-object slice
- source_io_definition: docs/ARCHITECTURE.md Domain and factory/registry ownership rules
- source_reference_models: N/A for this architecture/model-object slice
- status: ready-for-implementation
- owner_agent: implementation-planning-agent
- date: 2026-06-09

## Readiness Check

| input | required_status | observed_status | decision |
| --- | --- | --- | --- |
| architecture | model object boundaries documented | documented in docs/ARCHITECTURE.md and ADR-004/010/011 | proceed |
| domain foundation | base Domain storage available | implemented in `domain-model-foundation` | proceed |
| formulation | not required for identity-only model object skeletons | N/A | proceed |
| numerical_review | not required for identity-only model object skeletons | N/A | proceed |
| io_definition | parser DTO compatibility sufficient | existing `*Definition` objects remain input DTOs | proceed |
| reference_models | not required because this slice produces no solver result | N/A | proceed |

## Implementation Scope

- included_behavior: C++17 model object classes for nodes, elements, materials, shell properties, loads, and boundary conditions.
- included_behavior: abstract base classes for element, material, load, and boundary condition model objects.
- included_behavior: MITC4 element model skeleton with id, connectivity, property id, 4-node count, and 24-DOF count.
- included_behavior: Domain RAII ownership for polymorphic model objects through `std::unique_ptr`.
- included_behavior: compatibility with existing `*Definition` value objects and tests.
- excluded_behavior: MITC4 stiffness, Jacobian, MITC shear interpolation, constitutive matrices, global force assembly, boundary-condition elimination, equation numbering, solver vectors, reaction recovery, HDF5 output, parser/factory implementation, and reference comparison.
- non_goals: numerical correctness claims, release readiness, reference-solver execution, and reference artifact generation.

## Model Object Contract

`Domain` remains the owner of parsed model definition. This phase adds runtime model objects that can later be used by `AnalysisModel`, factories, and element/material implementations without storing analysis state in `Domain`.

Model object responsibilities:

- `Node`: id and reference coordinates only; fixed six-DOF count from project convention.
- `Element`: identity, element type, connectivity, property reference, and node count only.
- `Mitc4Element`: MITC4 model skeleton with four node ids and 24 element DOFs only.
- `Material`: material identity only.
- `LinearElasticMaterial`: id, Young's modulus, and Poisson ratio only.
- `ShellProperty`: property id, material id, and thickness only.
- `Load`: load kind only.
- `NodalLoad`: node id, DOF, and scalar value only.
- `BoundaryCondition`: boundary kind only.
- `SinglePointConstraint`: node id, DOF, and prescribed scalar value only.

Excluded from all model objects:

- equation ids
- sparse matrix data
- displacement, residual, reaction, velocity, acceleration, or temperature vectors
- current time, increment, or iteration counters
- element integration point state
- MKL, TBB, HDF5, or reference-comparison handles

Existing `*Definition` value objects remain parser/factory DTOs for now. This phase must not delete them. Later parser/factory work may either map DTOs into model objects or retire DTOs with an explicit migration plan.

Compatibility decision:

- Existing `ElementDefinition`, `LinearElasticMaterialDefinition`, `ShellPropertyDefinition`, `BoundaryCondition`, `NodalLoadDefinition`, and `LinearStaticStepDefinition` classes remain under `include/fesa/core/` as value-style input DTOs.
- New runtime model objects live under ownership namespaces: `fesa::element`, `fesa::material`, `fesa::property`, `fesa::load`, and `fesa::boundary`.
- `Domain` supports both existing DTO storage APIs and new polymorphic model-object ownership APIs during the transition.
- Parser/factory work must make an explicit choice to map DTOs to model objects or replace DTOs in a separate phase. This phase does not decide parser behavior.

## Work Breakdown

| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
| --- | --- | --- | --- | --- | --- |
| AMO-001 | 1 | refine `Node` model class contract | ADR-010; docs/ARCHITECTURE.md Node | none | AMO-TEST-001 |
| AMO-002 | 2 | add abstract `Element` base interface | ADR-004; docs/ARCHITECTURE.md Element | AMO-001 | AMO-TEST-002 |
| AMO-003 | 3 | add MITC4 element model skeleton | AGENTS.md MITC4 scope | AMO-002 | AMO-TEST-003 |
| AMO-004 | 4 | add material base and linear elastic material object | docs/ARCHITECTURE.md Material | AMO-002 | AMO-TEST-004 |
| AMO-005 | 5 | add shell property model object | docs/ARCHITECTURE.md Property | AMO-004 | AMO-TEST-005 |
| AMO-006 | 6 | add load base and nodal load object | docs/ARCHITECTURE.md loads | AMO-002 | AMO-TEST-006 |
| AMO-007 | 7 | add boundary base and single-point constraint object | ADR-012 | AMO-002 | AMO-TEST-007 |
| AMO-008 | 8 | extend Domain with polymorphic object ownership | ADR-010; ADR-011 | AMO-003 to AMO-007 | AMO-TEST-008 |
| AMO-009 | 9 | preserve `*Definition` compatibility | domain-model-foundation plan | AMO-008 | AMO-TEST-009 |
| AMO-010 | 10 | record build/test evidence and handoff | docs/build-test-reports/README.md | AMO-009 | AMO-TEST-010 |

## TDD Test Plan

| test_id | order | test_type | red_condition | green_condition | linked_task | command |
| --- | --- | --- | --- | --- | --- | --- |
| AMO-TEST-001 | 1 | unit | `Node::dofCount()` missing | Node model tests pass | AMO-001 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| AMO-TEST-002 | 2 | unit | `fesa/element/Element.hpp` missing | Element base polymorphism tests pass | AMO-002 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object` |
| AMO-TEST-003 | 3 | unit | `Mitc4Element` missing | MITC4 model skeleton tests pass | AMO-003 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object` |
| AMO-TEST-004 | 4 | unit | material model headers missing | material base and linear elastic tests pass | AMO-004 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object` |
| AMO-TEST-005 | 5 | unit | shell property model missing | shell property tests pass | AMO-005 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object` |
| AMO-TEST-006 | 6 | unit | load model headers missing | load base and nodal load tests pass | AMO-006 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object` |
| AMO-TEST-007 | 7 | unit | boundary model headers missing | boundary base and SPC tests pass | AMO-007 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R model-object` |
| AMO-TEST-008 | 8 | unit | Domain polymorphic APIs missing | Domain owns and retrieves model objects by base interface | AMO-008 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "domain|model-object"` |
| AMO-TEST-009 | 9 | regression | existing definition tests fail | existing Domain definition tests remain passing | AMO-009 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| AMO-TEST-010 | 10 | validation | report evidence missing | validation report records passing commands or classified failure | AMO-010 | `python scripts/validate_workspace.py` |

## CMake/CTest Plan

- target_candidates: `fesa_core`, `fesa_domain_tests`, `fesa_model_object_tests`
- labels: `domain`, `core`, `model-object`, `element`, `material`, `property`, `load`, `boundary`
- msvc_config: Debug
- expected_feature_command: `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "domain|model-object"`
- workspace_validation: `python scripts/validate_workspace.py`

## Candidate Files and Ownership

| file_candidate | purpose | owner_boundary | notes |
| --- | --- | --- | --- |
| `include/fesa/core/Node.hpp` | existing node model object | core model definition | no solver state |
| `include/fesa/element/Element.hpp` | abstract element model base | element model identity | no stiffness API |
| `include/fesa/element/Mitc4Element.hpp` | MITC4 element model skeleton | element model identity | no formulation implementation |
| `src/element/Mitc4Element.cpp` | MITC4 model accessors | element model identity | no numerical behavior |
| `include/fesa/material/Material.hpp` | abstract material model base | material identity | no constitutive matrix |
| `include/fesa/material/LinearElasticMaterial.hpp` | linear elastic material model | material input values | no stress update |
| `src/material/LinearElasticMaterial.cpp` | linear elastic material accessors | material input values | no numerical behavior |
| `include/fesa/property/ShellProperty.hpp` | shell property model | property input values | no section stiffness |
| `src/property/ShellProperty.cpp` | shell property validation/accessors | property input values | thickness validation only |
| `include/fesa/load/Load.hpp` | abstract load model base | load identity | no assembly |
| `include/fesa/load/NodalLoad.hpp` | nodal load model | load input values | no global vector behavior |
| `src/load/NodalLoad.cpp` | nodal load accessors | load input values | no assembly |
| `include/fesa/boundary/BoundaryCondition.hpp` | abstract boundary model base | boundary identity | no matrix application |
| `include/fesa/boundary/SinglePointConstraint.hpp` | SPC boundary model | boundary input values | no reaction recovery |
| `src/boundary/SinglePointConstraint.cpp` | SPC accessors | boundary input values | no matrix application |
| `include/fesa/core/Domain.hpp` | Domain ownership extension | core ownership | preserve existing APIs |
| `src/core/Domain.cpp` | Domain ownership implementation | core ownership | no solver state |
| `tests/**` | TDD coverage | tests | write before production changes |

## Acceptance Traceability Matrix

| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
| --- | --- | --- | --- | --- | --- |
| AMO-REQ-001 Node is model data only | AMO-001 | AMO-TEST-001 | N/A | Node tests pass and no solver state added | draft |
| AMO-REQ-002 Element base is identity-only | AMO-002 | AMO-TEST-002 | N/A | Element base tests pass | draft |
| AMO-REQ-003 MITC4 model skeleton has 4 nodes and 24 DOFs | AMO-003 | AMO-TEST-003 | N/A | MITC4 model tests pass | draft |
| AMO-REQ-004 Material model stores input values only | AMO-004 | AMO-TEST-004 | N/A | material tests pass | draft |
| AMO-REQ-005 Shell property validates thickness only | AMO-005 | AMO-TEST-005 | N/A | shell property tests pass | draft |
| AMO-REQ-006 Load and boundary models do not assemble/apply | AMO-006; AMO-007 | AMO-TEST-006; AMO-TEST-007 | N/A | load/boundary tests pass and APIs remain value accessors | draft |
| AMO-REQ-007 Domain owns polymorphic model objects via RAII | AMO-008 | AMO-TEST-008 | N/A | Domain ownership tests pass | draft |
| AMO-REQ-008 Existing definition APIs remain compatible | AMO-009 | AMO-TEST-009 | N/A | existing domain tests pass | draft |

## Validation Commands

```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R "domain|model-object"
```

## Risks and Downstream Handoff

### Implementation Agent

- Keep model objects identity-only until formulation and solver stages define numerical APIs.
    - Preserve existing `*Definition` tests.
- Prefer RAII ownership through `std::unique_ptr` and const retrieval.

### Build/Test Executor Agent

- Use Visual Studio 17 2022, x64, Debug, and `build/msvc-debug`.
- Use `python scripts/validate_workspace.py` as canonical validation.

### Correction Agent

- Implementation-owned failures are expected to be compile or unit-test failures in model object headers, model object sources, CMake registration, or Domain ownership methods.
- Upstream-contract failures include requests to add numerical MITC4 behavior or solver state in this phase.

### Reference Verification Agent

- No reference verification is required for this phase.
- This phase produces no HDF5 result and consumes no reference artifacts.

## Open Issues

- Parser/factory mapping from `*Definition` DTOs to model objects remains deferred.
- MITC4 formulation, material constitutive behavior, shell section stiffness, assembly, solver, and HDF5 output remain separate future phases.