FESADev/docs/ARCHITECTURE.md

# FESA 구조해석 솔버 아키텍처

## 목적과 적용 범위

FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한다. 이 문서는
[PRD](PRD.md)의 제품 목표를 공통 책임, 의존성, 데이터와 수명 경계로 연결한다.
특정 요소·재료·하중의 정식화, 해석 알고리즘, 코드 목록 또는 구현 완료 현황은 다루지 않는다.

구체적인 API, 수식, 실행 순서와 결과 schema는 `docs/<feature-id>/`의 승인된
정식화·I/O·구현 계약에서 정의한다. 아래의 책임 모델은 아직 없는 클래스, 공통 base,
state field 또는 디렉토리를 미리 만들라는 지시가 아니다. 기존 구현의 승인된 의미를
일반적인 설명에 맞추어 변경하지 않는다.

설계 결정과 변경 근거는 [ADR](ADR.md), 코드 규약은 [CODINGSTYLE](CODINGSTYLE.md)을
따른다. 현재 프로젝트의 기술 선택은 [AGENTS.md](../AGENTS.md)와 실행 가능한
build/configuration에서 확인한다.

## 아키텍처 원칙

- 물리·수치 의미는 외부 파일 형식과 vendor API보다 독립적인 계약으로 유지한다.
- 모델 정의, 현재 실행 view, equation 구성, mutable state와 결과의 소유권을 구분한다.
- Local physics 계산과 global topology, assembly, constraint, solve 책임을 분리한다.
- Identity, units, coordinates, ordering과 failure 의미를 경계마다 명시한다.
- Candidate를 완성·검증한 뒤 계약된 state나 authoritative output에 반영한다.
- 병렬화와 최적화에서도 결정적인 ordering과 failure preservation을 유지한다.
- 실제 승인된 사용 사례에 필요한 최소 확장만 도입한다.

## Solver runtime과 개발 운영 영역

```text
Solver runtime
입력 adapter → semantic model → analysis procedure → recovery/results → 출력 adapter
                                    │
                                    ├─ DOF / equation / sparse pattern
                                    ├─ element / material / load contribution
                                    ├─ assembly / constraint policy
                                    └─ numerical backend

개발 운영 영역
사용자 요구 → Coordinator → 담당 specialist → 산출물과 evidence → gate 판정
                               │
                               └─ 할당된 계획 / Harness / 코드·테스트·문서 변경
```

첫 흐름은 해석 데이터의 전달을, 두 번째는 개발 작업과 검증의 흐름을 나타낸다.
Agent, prompt, phase 파일과 Harness는 solver runtime API나 물리 모델의 일부가 아니다.
개발 운영 영역은 저장소의 변경과 검증을 통제하며 solver가 실행 중 이를 호출하지 않는다.

## 공통 책임과 의존성

아래 명칭은 책임 경계이며 반드시 각각 하나의 클래스나 독립 library를 뜻하지 않는다.
실제 타입과 파일 배치는 승인된 Feature와 현재 코드 구조에서 결정한다.

| 경계 | 소유하는 책임 | 소유하지 않는 책임 |
| --- | --- | --- |
| Core identity/diagnostic | Source identity, 공통 상태와 진단의 의미 | 파일 문법, 물리 정식화, vendor resource |
| Input adapter | 외부 syntax와 지원 semantics의 검증·mapping | 해석 알고리즘과 acceptance 변경 |
| Model definition | Topology, 재료·property·하중·제약·step 정의와 stable identity | Equation 번호, 해석 중 mutable solution |
| Active model view | 현재 procedure/step에 필요한 모델의 non-owning 참조 | 원본 모델 복사나 수명 소유 |
| Element/material | 승인된 local ordering의 물리 응답과 recovery 계약 | Global equation numbering, 직접 sparse write, 파일 저장 |
| Load definition/evaluation | Target·magnitude·configuration 의미와 ordered contribution | Global vector의 공유 누적 |
| DOF/equation | 활성 DOF, full/free/constrained mapping, numbering, scatter와 sparse pattern | 요소 정식화, 수치 factorization |
| Assembly | Local contribution을 지정된 global structure에 결정적으로 누적 | Physics 재해석, equation 번호의 분산 생성 |
| Constraint policy | 승인된 제약의 equation 적용과 해 복구 의미 | Input syntax나 별도 물리 모델의 임의 도입 |
| Analysis procedure | 필요한 state·해법·반복/종료·commit·recovery lifecycle | Vendor handle이나 concrete storage API의 공개 |
| Numerical backend | 행렬·벡터 연산, 해법 resource와 backend failure translation | Source label의 물리 의미, 입력 모델 해석 |
| Results/recovery | 계산 결과의 물리량·위치·identity와 state 반영 | 저장 파일 layout이나 reference 데이터 보정 |
| Output adapter | 승인 schema로의 serialization, self-check와 finalization | 물리량 정의와 acceptance 판정 변경 |

의존성은 consumer가 명시된 contract를 사용하는 방향으로 둔다. Input/output과 vendor
adapter가 core 계약에 의존하며, public core가 concrete adapter나 vendor/OS 타입에
의존하지 않는다. Interface와 implementation의 의존성 방향을 역전하지 않는다.

Numerical consumer가 요소 종류별 concrete storage를 직접 분기하지 않도록 승인된
evaluation/contribution contract를 사용한다. Definition과 runtime object의 호환성은
지정된 생성 경계에서 검사한다. 이를 위해 speculative registry, 공유 소유권 또는
사용하지 않는 polymorphic capability를 추가하지 않는다.

## 데이터 계약

### Identity

다음 개념을 같은 정수나 row 위치라는 이유로 서로 대체하지 않는다.

- Source identity: 외부 입력에서 의미가 있는 label과 instance/scope
- Internal identity/index: 검증된 모델 내부의 안정된 식별 또는 위치
- DOF identity: Entity의 물리 자유도와 component
- Equation index: 특정 procedure의 equation ordering
- Result identity: Entity, quantity, location, component, step/frame과 coordinate 의미

Renumbering, filtering, 병렬 scheduling과 serialization 뒤에도 필요한 대응 관계를
보존한다. Reference matching은 row 순서가 아니라 계약된 source identity와 component를
사용한다. 특정 typed wrapper나 result-key 클래스를 이 문서만으로 새로 만들지 않는다.

### Units, coordinates와 result meaning

입력 값의 단위계를 임의로 추론하거나 결과에 맞춰 변환하지 않는다. 필요한 dimension,
좌표계, component 순서, 변환과 부호는 정식화 및 I/O 계약으로 고정한다.
서로 다른 위치나 정의의 recovery quantity를 같은 결과로 취급하지 않는다.
Averaging, extrapolation 또는 station 변환은 별도 승인된 의미가 있을 때만 수행한다.

### 모델, view와 state의 수명

- `Domain`은 전체 모델 정의를 소유하며 검증 이후 가능한 한 불변으로 취급한다.
- `AnalysisModel`은 Domain을 복사하지 않는 non-owning 실행 view다. Domain은 모든
  view와 그에 의존하는 계산보다 오래 살아야 한다.
- `DofManager`는 DOF/equation mapping과 sparse pattern을 전담한다. Node나 Element에
  equation 번호를 분산 저장하지 않는다.
- Analysis owner는 해당 procedure가 실제로 사용하는 mutable state와 workspace만 소유한다.
  재사용·재시도·해제 시 dependent object를 남기지 않는다.
- Trial/committed 구분이 필요한 procedure는 update 실패와 commit 시점을 별도 계약으로
  정의한다. 모든 procedure나 material에 이 state를 일괄 추가하지 않는다.
- Recovery와 output은 유효한 candidate를 검증한 뒤 반영한다. 기존 state와 최종 파일의
  보존 범위는 성공 경로뿐 아니라 실패 경로에서도 검증한다.

## 해석 실행 흐름

공통적으로 외부 입력의 의미를 검증하고 실행 모델을 구성한 뒤, 선택된 procedure가
equation과 state를 관리하여 결과를 복구·저장한다. 이것은 책임 수준의 설명이며 모든
procedure에 동일한 반복문이나 고정된 단계 목록을 강제하는 Template Method가 아니다.

각 procedure 계약은 다음을 명시한다.

1. 입력 준비와 procedure 선택의 경계, 원본 모델의 owner와 lifetime
2. 필요한 DOF, state, equation, workspace와 초기화 조건
3. Contribution, constraint, factorization/solve와 update의 순서
4. 해당하는 경우 increment, iteration, convergence와 종료 조건
5. 성공 candidate의 commit, recovery와 결과 frame의 의미
6. 실패 category, rollback·재사용 조건과 final output의 보존 범위

정적·동적, 선형·비선형, eigen 또는 contact 계열은 실제 요구와 승인된 계약으로
정의한다. 이 구분을 명시하는 것은 해당 기능이 이미 지원된다는 뜻이 아니다.
기존 절차에 조건문으로 새 physics를 끼워 넣거나, 간결한 공통 그림을 근거로 승인된
연산 순서·reaction·residual·commit 의미를 바꾸지 않는다.

현재 개별 procedure의 구체적인 실행 계약은 해당 Feature의 formulation·I/O·구현 문서를
확인한다. 기존 프로젝트 문서의 실행 순서와 객체 배치는
[개정 전 아키텍처](archive/pre-generalization/ARCHITECTURE.md)에 이력으로 보존한다.

## Local 계산, assembly와 constraint

Local kernel은 승인된 geometry, material/property, DOF/state와 요청된 계산 범위를 받아
local ordering이 명시된 contribution 또는 recovery 값을 만든다. Global numbering,
공유 matrix 갱신, 파일 lookup, 전체 convergence 판정이나 최종 저장을 수행하지 않는다.

DOF owner가 지정한 pattern과 scatter를 assembly가 사용한다. Contribution 생성과
누적 순서를 명시하고 병렬 worker는 소유한 buffer에만 기록한다. Join 이후 reduction과
diagnostic 선택은 결정적으로 수행한다. Hash iteration이나 실행 scheduling을
authoritative ordering으로 사용하지 않는다.

Constraint 방식, full/reduced space, prescribed value, residual과 reaction의 정의는
선택된 procedure의 수학 계약에 포함한다. 서로 다른 enforcement 방식의 결과 의미를
같다고 가정하지 않는다. 특수 차원·빈 시스템·singularity의 처리는 계약에 따라 검증하며
임의의 regularization, zero clamp 또는 fallback으로 실패를 숨기지 않는다.

## Numerical backend와 실행 환경

Math storage, index convention, matrix capability, resource lifetime과 오류 변환은
backend-neutral 계약으로 노출한다. Vendor header, handle과 OS 타입은 private adapter에
격리한다. Dense와 sparse의 의미가 다르면 하나의 storage hierarchy로 억지로 합치지 않는다.

Build dependency는 프로젝트가 소유한 target 경계에서 정규화하고, 새로운 dynamic
dependency는 link뿐 아니라 실제 실행에 필요한 runtime closure까지 확인한다.
개인 설치 절대 경로를 소스 계약으로 고정하지 않는다. Thread와 workspace 정책은
실제 workload와 재현성 evidence에 근거하여 관리한다.

현재 target graph와 dependency 선택은 [CMakeLists.txt](../CMakeLists.txt),
[dependency 설정](../cmake/FesaDependencies.cmake),
[solver target](../src/fesa/CMakeLists.txt), [test target](../tests/CMakeLists.txt)과
[CMakePresets.json](../CMakePresets.json)을 확인한다. 이 참조는 다른 toolchain이나
backend를 자동 승인하지 않으며 FESA의 현재 검증 baseline은 프로젝트 지침을 따른다.

## 입력, 결과와 진단

Input adapter는 지원되는 외부 syntax, scope, default와 model/history 의미를
검증된 semantic model로 mapping한다. 의미상 무해하다고 계약된 항목만 warning/no-op으로
처리할 수 있으며 나머지 미지원 semantics는 fail-closed로 진단한다.

Results/recovery가 물리량의 의미를, output adapter가 저장 layout을 소유한다.
Authoritative output과 diagnostic log, debug view, reference artifact를 구분한다.
공식 형식, 파일명, schema version, mandatory dataset과 backward compatibility는
현재 프로젝트·Feature I/O 계약을 따른다. 일반화 때문에 기존의 필수 결과를 optional로
바꾸거나 다른 파일 형식으로 대체하지 않는다.

Output은 계약된 임시 candidate에 기록하고 검증·close를 완료한 뒤 최종 결과로 반영한다.
실패 frame이나 불완전한 파일을 정상 결과처럼 공개하지 않는다. 내부 state의 commit과
외부 파일의 finalization은 서로 다른 경계이므로 각각의 failure contract를 정의한다.

Diagnostic은 실패 단계, 안정된 code와 메시지, 가능한 source location/entity를 제공한다.
정확한 category, field와 CLI exit code는 I/O 계약을 따른다. Backend 오류를 그대로
누출하거나 내부 failure classification을 새 public exit code로 임의 승격하지 않는다.

## 검증과 reference 경계

검증 coverage와 비교량의 논리적 정의는 Numerical Review, 물리량의 저장·외부 대응은
I/O, 실행 evidence는 Implementation, 독립 물리 판단은 Physics Evaluation이 소유한다.
각 단계는 상위 계약을 결과에 맞춰 수정하지 않는다.

- Source identity, location과 component 일치 여부를 수치 tolerance보다 먼저 확인한다.
- Missing, extra, duplicate와 nonfinite required value를 숨기지 않는다.
- 외부 reference 판정은 [TOLERANCE](TOLERANCE.md)의 공통 정책을 적용한다. 물리 평형,
  정식화와 수렴의 검증 기준은 각자의 계약을 따른다.
- Reference artifact의 naming이나 보조 metadata를 맞추기 위해 파일을 변경하지 않는다.
- 공개 입력 의미나 관찰 가능한 결과 비교를 외부 solver의 내부 동작 동등성으로 해석하지 않는다.

구현 존재, 특정 revision의 검증 통과와 현재 release readiness는 별도로 확인한다.
Architecture 문서의 그림이나 모듈명이 기능의 완료 증거를 대신하지 않는다.

## 개발 운영 인프라

공통 agent 상태 전이는 [SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill의 역할은
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실제 실행 절차는
[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 agent/skill profile을 읽는다.

| Owner | 책임 |
| --- | --- |
| Coordinator | Feature 문서 목록·상태, dispatch, evidence gate, revision·retry budget과 closure |
| Specialist | 할당된 stage의 전문 판단, 기본·상세 산출물과 공통 handoff |
| Planning Agent | 할당된 implementation plan과 phase/index/step 계획 파일 |
| Executor | 현재 step 선택, branch, transport attempt, timestamp, path-scoped commit과 phase 진행 |
| Implementation Agent | 선택된 step의 코드·테스트·보고서와 result payload |
| Hook | 도구 호출 전 guardrail과 설정된 종료 검증; TDD 관찰이나 완전한 sandbox의 대체가 아님 |

Coordinator만 workflow를 전이한다. Specialist의 outcome은 전이 요청이고, Harness의
step 상태는 별개의 실행 상태다. Executor transport attempt는 최대 2회이며 동일
`retry_key`의 correction 1회와 뒤따르는 Implementation rerun은 Coordinator가 관리한다.
두 budget을 혼용하거나 실패 문구만 바꿔 반복하지 않는다.

승인된 scope와 할당된 작업 안의 일반 계획·문서·local 실행에는 반복 승인 gate를
추가하지 않는다. 계획 요청만으로 실행을 시작하지 않으며 외부 solver, 원격·파괴 작업과
sandbox 권한 확대에는 해당 명시적 권한이 필요하다.

Project config, preset과 실행 command는 검토해야 하는 실행 입력이다. Hook 통과나
구조화된 argument list만으로 그 side effect가 격리되었다고 간주하지 않는다.
Executor는 시작 전 선택된 phase 제어 파일 밖의 변경을 거부하며 모든 pending Step의
Planning 소유 `owned_paths`를 검증한다. 매 시도 후와 stage/commit 경계에서 신뢰된 목록과
변경·staged 경로를 대조하고 구현 변경과 phase metadata를 분리한다. 범위 밖 변경은
보존하고 재시도·커밋·다음 Step을 중단한다. 이 검사는 동시 writer의 원자적 격리나 여러
커밋의 단일 transaction을 보장하지 않는다. 실행 중 동시 편집을 피한다.
종료 코드와 Step 보고 상태를 함께 판정하며 명시적 실패를 transport 재시도로 덮어쓰지
않는다. 실제 wrapper timeout이고 결과 미보고일 때만 최초 포함 최대 두 번 시도한다.
환경·실패 진단과 원래 보고는 Executor 소유 `attempt_history`에 남기고 재개 때 보존한다.
등록된 Hook을 수동 실행하여 검증 evidence를 대신하지 않는다.

문서 전용 Stop 생략은 기록된 동일 session/turn의 허용된 편집 대상이 모두 저장소 내부
Markdown인 조건에 한정된다. 기록이 없거나 불완전한 읽기 전용 작업과 shell 쓰기까지
안전하게 분류한다고 가정하지 않는다. 생략은 build/test 통과가 아니다.
사용자가 실행을 제외한 문서 작업은 정적 검토와 미실행 항목을 보고한다.

## 문서와 아키텍처의 변경

프로젝트 공통 원칙의 변경은 공통 ADR로, 구현 항목별 선택은 해당 Feature ADR로
기록한다. Feature PRD는 범위와 acceptance 요약을, requirements·formulation·I/O는
전문 계약의 원본을 소유한다. 관리 문서와 기본·상세 산출물은
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)의 소유권과 링크 규칙을 따른다.

Public dependency, identity, 수명, result meaning이나 lifecycle 변경은 영향받는
계약과 evidence를 함께 검토한다. 상위 계약 변경으로 영향받는 evidence는 stale 처리하며,
문서 정리만으로 기존 기능의 재검증이나 release 승인을 완료한 것으로 표시하지 않는다.

개정 전 구현 설명은 [보존본](archive/pre-generalization/ARCHITECTURE.md)에 남긴다.
해당 설명을 Feature 문서로 이관할 때 원래 범위와 승인 revision을 확인한다.
현재 문서는 과거 구현 상세를 삭제하여 계약을 없애거나 미래 API를 선결정하지 않는다.