# Domain Model Foundation Implementation Plan

## Metadata
- feature_id: domain-model-foundation
- source_requirement: AGENTS.md; docs/ARCHITECTURE.md; docs/ADR.md
- source_research: N/A for this architecture foundation slice
- source_formulation: N/A for this architecture foundation slice
- source_numerical_review: N/A for this architecture foundation slice
- source_io_definition: docs/ARCHITECTURE.md input-model ownership rules
- source_reference_models: N/A for this architecture foundation slice
- status: ready-for-implementation
- owner_agent: implementation-planning-agent
- date: 2026-06-08

## Readiness Check

| input | required_status | observed_status | decision |
| --- | --- | --- | --- |
| architecture | Domain, AnalysisModel, AnalysisState, DofManager boundaries documented | documented in docs/ARCHITECTURE.md and docs/ADR.md | proceed |
| requirements | Domain ownership rules documented | documented in AGENTS.md and docs/ARCHITECTURE.md | proceed |
| formulation | not required for model-container storage | N/A | proceed |
| numerical_review | not required for model-container storage | N/A | proceed |
| io_definition | parser contract not required; semantic storage boundary documented | sufficient for Domain foundation | proceed |
| reference_models | not required because this slice produces no solver result | N/A | proceed |

## Implementation Scope

- included_behavior: C++17 core model-definition storage for nodes, element definitions, material definitions, shell property definitions, sets, boundary conditions, nodal loads, and linear static step definitions.
- included_behavior: CMake/CTest bootstrap for MSVC x64 Debug validation.
- included_behavior: deterministic id validation and const retrieval APIs for stored model definitions.
- excluded_behavior: MITC4 stiffness, shape functions, Jacobian checks, assembly, solver, reaction recovery, HDF5 output, Abaqus parser, MKL, TBB, and reference comparison.
- non_goals: numerical correctness claims, release readiness, Abaqus/Nastran execution, and stored reference artifact generation.

## Domain Contract

`Domain` owns parsed model definitions only. It preserves the model that an input parser or factory layer creates and should be treated as immutable by analysis code after parsing/building is complete.

Included model definitions:

- nodes
- element definitions
- material definitions
- shell property definitions
- node sets
- element sets
- boundary conditions
- nodal loads
- analysis step definitions

Excluded state:

- equation ids
- sparse matrix structure or values
- reduced or full displacement vectors
- residual vectors
- reaction vectors
- current time
- increment counters
- nonlinear iteration counters
- element integration point state
- MKL, TBB, or HDF5 handles

Boundary responsibilities:

- `DofManager` owns active DOF discovery, constrained/free DOF mapping, equation numbering, sparse pattern connectivity, and full-vector reconstruction.
- `AnalysisModel` owns the step-local execution view over active domain objects. It references `Domain` objects by id or stable reference and does not copy the whole domain.
- `AnalysisState` owns mutable solution, residual, load vector, time/increment, and future element state.

Common data rules:

- All ids use signed 64-bit storage.
- Node DOF order is `U1, U2, U3, UR1, UR2, UR3`.
- Coordinates and scalar physical values use `double`.
- Units are user-consistent and are not enforced or converted by `Domain`.
- Duplicate ids fail with `std::invalid_argument`.
- Insertions that reference missing required objects fail with `std::invalid_argument`.
- Direct lookup of a missing object fails with `std::out_of_range`.
- Optional `find*` lookup APIs return `nullptr` for missing objects.
- Retrieval APIs return const references or const pointers.

## Work Breakdown

| task_id | order | purpose | upstream_trace | depends_on | expected_test_first |
| --- | --- | --- | --- | --- | --- |
| TASK-001 | 1 | Bootstrap CMake, core target, and CTest for Domain tests | ADR-002 | none | TEST-001 |
| TASK-002 | 2 | Define signed 64-bit id aliases and six-DOF ordering constants | ADR-014; AGENTS.md MITC4 scope | TASK-001 | TEST-002 |
| TASK-003 | 3 | Add `Node` and node storage/retrieval in `Domain` | ADR-010; docs/ARCHITECTURE.md Domain section | TASK-002 | TEST-003 |
| TASK-004 | 4 | Add MITC4 element definition storage without element computation | ADR-004; docs/ARCHITECTURE.md Core Runtime Objects | TASK-003 | TEST-004 |
| TASK-005 | 5 | Add material, shell property, node set, and element set storage | docs/ARCHITECTURE.md Domain included data | TASK-004 | TEST-005 |
| TASK-006 | 6 | Add boundary condition, nodal load, and linear static step definition storage | ADR-012; docs/ARCHITECTURE.md Domain included data | TASK-005 | TEST-006 |
| TASK-007 | 7 | Lock down Domain invariants and failed-insert stability | ADR-010; docs/AGENT_RULES.md boundaries | TASK-006 | TEST-007 |
| TASK-008 | 8 | Record build/test evidence and handoff status | docs/build-test-reports/README.md | TASK-007 | TEST-008 |

## TDD Test Plan

| test_id | order | test_type | red_condition | green_condition | linked_task | command |
| --- | --- | --- | --- | --- | --- | --- |
| TEST-001 | 1 | CTest bootstrap | `domain.bootstrap` is not registered or cannot run | `domain.bootstrap` passes under MSVC Debug | TASK-001 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain.bootstrap` |
| TEST-002 | 2 | unit | `fesa/core/ModelTypes.hpp` is missing | id aliases are 64-bit and DOF ordinals are 0..5 | TASK-002 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| TEST-003 | 3 | unit | `Node` and `Domain` node APIs are missing | add/find/direct lookup/duplicate node tests pass | TASK-003 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| TEST-004 | 4 | unit | element definition APIs are missing | element add/find/direct lookup/connectivity/missing-node tests pass | TASK-004 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| TEST-005 | 5 | unit | material, property, and set APIs are missing | material/property/set validation tests pass | TASK-005 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| TEST-006 | 6 | unit | boundary, load, and step APIs are missing | BC/load/step storage tests pass | TASK-006 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| TEST-007 | 7 | unit | failed insertion mutates Domain or mutable access leaks | invariant and failed-insert stability tests pass | TASK-007 | `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain` |
| TEST-008 | 8 | validation | build/test evidence is missing | build/test report records passing validation or classified failure | TASK-008 | `python scripts/validate_workspace.py` |

## CMake/CTest Plan

- target_candidates: `fesa_core`, `fesa_domain_tests`
- add_test_needs: `domain.bootstrap` initially, then Domain behavior tests under the same `domain` CTest filter.
- labels: `domain`, `core`
- msvc_config: Debug
- expected_feature_command: `ctest --test-dir build/msvc-debug --output-on-failure -C Debug -R domain`
- workspace_validation: `python scripts/validate_workspace.py`

## Candidate Files and Ownership

| file_candidate | purpose | owner_boundary | notes |
| --- | --- | --- | --- |
| `CMakeLists.txt` | root CMake project, core library, CTest registration | build/test bootstrap | MSVC x64 Debug baseline |
| `include/fesa/core/ModelTypes.hpp` | id aliases and DOF constants | core model definitions | no solver state |
| `include/fesa/core/Node.hpp` | node id and coordinate definition | core model definitions | no displacement storage |
| `include/fesa/core/ElementDefinition.hpp` | element id, type, connectivity, property reference | core model definitions | no stiffness behavior |
| `include/fesa/core/MaterialDefinition.hpp` | linear elastic material input definition | core model definitions | no constitutive matrix |
| `include/fesa/core/PropertyDefinition.hpp` | shell property input definition | core model definitions | no section stiffness |
| `include/fesa/core/BoundaryCondition.hpp` | prescribed DOF value definition | core model definitions | no matrix application |
| `include/fesa/core/LoadDefinition.hpp` | nodal load definition | core model definitions | no global vector assembly |
| `include/fesa/core/StepDefinition.hpp` | linear static step definition | core model definitions | no analysis driver |
| `include/fesa/core/Domain.hpp` | Domain public storage/retrieval API | core model definitions | const retrieval only |
| `src/core/Domain.cpp` | Domain validation and storage implementation | core model definitions | no external dependencies |
| `tests/core/domain_bootstrap_test.cpp` | CTest bootstrap executable | test | created before production code |
| `tests/core/model_types_test.cpp` | id and DOF tests | test | optional separate executable |
| `tests/core/domain_storage_test.cpp` | Domain behavior tests | test | required before production changes |

## Data Flow Contract

1. A future Abaqus parser and factory/registry layer creates semantic model definitions.
2. `Domain` stores those definitions and validates duplicate ids and missing required references.
3. A future `AnalysisModel` builds a step-local execution view from `Domain` ids or stable references.
4. A future `DofManager` derives active DOFs and equation ids outside `Domain`.
5. A future `AnalysisState` stores solution and iteration state outside `Domain`.

## Acceptance Traceability Matrix

| requirement_id | task_id | test_id | reference_model_id | acceptance_criterion | status |
| --- | --- | --- | --- | --- | --- |
| DOM-REQ-001 Domain owns parsed model definitions | TASK-003 to TASK-006 | TEST-003 to TEST-006 | N/A | storage and const retrieval tests pass | draft |
| DOM-REQ-002 Domain excludes solver state | TASK-007 | TEST-007 | N/A | invariant tests and member review pass | draft |
| DOM-REQ-003 ids use signed 64-bit storage | TASK-002 | TEST-002 | N/A | `sizeof(Id) == 8` test passes | draft |
| DOM-REQ-004 node DOF order is fixed | TASK-002 | TEST-002 | N/A | DOF ordinal test passes | draft |
| DOM-REQ-005 duplicate ids are rejected | TASK-003 to TASK-006 | TEST-003 to TEST-006 | N/A | duplicate tests throw `std::invalid_argument` | draft |
| DOM-REQ-006 missing required references are rejected | TASK-004 to TASK-006 | TEST-004 to TEST-006 | N/A | missing-reference tests throw `std::invalid_argument` | draft |
| DOM-REQ-007 direct missing lookup is deterministic | TASK-003 to TASK-007 | TEST-003 to TEST-007 | N/A | direct missing lookup throws `std::out_of_range` | draft |
| DOM-REQ-008 validation uses MSVC CMake/CTest | TASK-001; TASK-008 | TEST-001; TEST-008 | N/A | configure/build/CTest evidence recorded | 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
```

## Risks and Downstream Handoff

### Implementation Agent

- Keep each storage layer separate and test-first.
- Do not add numerical behavior while implementing model definitions.
- Preserve `Domain` as a model container, not a solver-state object.

### Build/Test Executor Agent

- Use Visual Studio 17 2022, x64, Debug, and `build/msvc-debug`.
- After `CMakeLists.txt` exists, `python scripts/validate_workspace.py` must configure, build, and run CTest instead of taking the no-CMake path.

### Correction Agent

- Implementation-owned failures are expected to be compile or unit-test failures in `fesa_core` or `fesa_domain_tests`.
- Upstream-contract failures include requests to store equation ids, displacements, reaction vectors, or integration point state inside `Domain`.

### Reference Verification Agent

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

## Open Issues

- The full MITC4 requirements, formulation, I/O definition, and reference model artifacts are still separate upstream stages.
- The parser-to-Domain factory API is intentionally deferred until the Abaqus input subset phase.