FESADev/docs/implementation-plans/domain-model-foundation-implementation-plan.md

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

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.