docs: organize project guidance and module contracts
This commit is contained in:
KOKO\Mimi
+102
-231
@@ -1,260 +1,131 @@
|
||||
# FESA 구조해석 솔버 아키텍처
|
||||
# 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과 개발 운영 영역
|
||||
FESA는 로컬 모델 파일을 읽어 해석하고 HDF5 결과를 저장하는 C++ 솔버다. 현재 공개
|
||||
실행 경로는 하나의 CLI이며, 내부 정적 library와 테스트 target이 같은 core를 사용한다.
|
||||
개발용 Python 실행기는 솔버 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
|
||||
|
||||
개발 운영 영역
|
||||
사용자 요구 → 메인 assistant → 필요한 전문 작업·구현 → 검증·결과 확인
|
||||
│
|
||||
└─ 명시적 Harness / 코드·테스트·문서 변경
|
||||
fesa_cli
|
||||
└─ app: 경로·출력 쓰기 소유권·실행 조합
|
||||
├─ io/abaqus: 입력 읽기 → syntax → semantic mapping
|
||||
│ └─ model: Domain·source identity·재료/단면/step 정의
|
||||
└─ analysis: 준비된 모델 → procedure별 실행 → 완료 candidate
|
||||
├─ AnalysisModel: Domain의 non-owning view
|
||||
├─ fem / constraints: DOF·equation·partition
|
||||
├─ elements / materials / properties / loads: local 계산
|
||||
├─ assembly: 결정적인 global 누적
|
||||
├─ math / solvers: storage·PARDISO·FEAST
|
||||
└─ results: 물리 결과 복구·state 반영
|
||||
└─ io/hdf5: candidate 파일 → self-check·close → 최종 교체
|
||||
```
|
||||
|
||||
첫 흐름은 해석 데이터의 전달을, 두 번째는 개발 작업과 검증의 흐름을 나타낸다.
|
||||
Agent, skill과 Harness는 solver runtime API나 물리 모델의 일부가 아니다.
|
||||
개발 운영 영역은 저장소의 변경과 검증을 통제하며 solver가 실행 중 이를 호출하지 않는다.
|
||||
Consumer는 backend-neutral contract를 통해 값을 주고받는다. MKL·TBB·HDF5·Win32
|
||||
header와 handle은 private implementation에 머문다. 새 물리나 backend를 추가할 때
|
||||
core가 외부 adapter를 참조하는 방향으로 의존성을 뒤집지 않는다.
|
||||
|
||||
## 공통 책임과 의존성
|
||||
## 모듈 경계
|
||||
|
||||
아래 명칭은 책임 경계이며 반드시 각각 하나의 클래스나 독립 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 판정 변경 |
|
||||
| `include/fesa` | 공개 선언, 값·실패·수명 계약 | Vendor handle, 실행별 equation 저장 |
|
||||
| `app` | CLI 경로, output lease, 객체 조합과 외부 종료 | 요소 정식화, 수렴 기준 결정 |
|
||||
| `core` | Source identity, ASCII 처리, Status·Diagnostic | 입력 procedure 허용 범위 |
|
||||
| `io/abaqus` | 문법·scope·semantic mapping, Domain 생성 | 해법, 결과 복구 |
|
||||
| `model` | 전체 정의, target 해석, 초기 shell geometry | Mutable solution, global equation 번호 |
|
||||
| `properties` | 재료 연결과 beam/shell 단면 정의 | 물성 평가식, state 수명 |
|
||||
| `materials` | 구성 관계와 필요한 물성 capability | Element topology, analysis state |
|
||||
| `elements` | Local 행렬·힘·관성·회복에 필요한 응답 | Global CSR 갱신, 파일 접근 |
|
||||
| `loads` | 하중 의미·configuration·local contribution | Global 공유 누적, 입력 target 이름 해석 |
|
||||
| `fem` | DOF, scatter, full/free/constrained mapping, pattern | 선형계 factorization |
|
||||
| `constraints` | 지정값 적용, partition·대입 정책 | 물리 결과 재해석 |
|
||||
| `assembly` | Sparse·하중·압력 contribution의 ordered reduction | Equation 번호 발급, 수렴 판정 |
|
||||
| `analysis` | Procedure별 초기화·증분·반복·종료·state lifecycle | Concrete 저장 형식, vendor resource 공개 |
|
||||
| `math` | Vector·Matrix·SparseMatrix, private BLAS adapter | 모델 의미, source target lookup |
|
||||
| `solvers/linear` | PARDISO factorization·solve, resource와 실패 변환 | 경계조건 변경, 모델 수정 |
|
||||
| `solvers/eigen` | FEAST 실행과 수치 제어의 backend 경계 | Source EIGENSOLVER의 재해석, 외부 비교 판정 |
|
||||
| `results` | Location·부호·좌표가 명확한 복구와 candidate commit | HDF5 layout, reference 보정 |
|
||||
| `io/hdf5` | Schema serialization·readback·최종 파일 교체 | 물리량 정의, acceptance 완화 |
|
||||
|
||||
의존성은 consumer가 명시된 contract를 사용하는 방향으로 둔다. Input/output과 vendor
|
||||
adapter가 core 계약에 의존하며, public core가 concrete adapter나 vendor/OS 타입에
|
||||
의존하지 않는다. Interface와 implementation의 의존성 방향을 역전하지 않는다.
|
||||
같은 module의 public 선언은 `include/fesa/<module>`, implementation은
|
||||
`src/fesa/<module>`에 나뉜다. 이 물리적 분리가 interface와 implementation의 소유권을
|
||||
둘로 나누지는 않는다. Parser가 concrete numerical storage를 생성·조작하는 대신
|
||||
semantic 정의와 검증된 생성 경계로 연결한다.
|
||||
|
||||
Numerical consumer가 요소 종류별 concrete storage를 직접 분기하지 않도록 승인된
|
||||
evaluation/contribution contract를 사용한다. Definition과 runtime object의 호환성은
|
||||
지정된 생성 경계에서 검사한다. 이를 위해 speculative registry, 공유 소유권 또는
|
||||
사용하지 않는 polymorphic capability를 추가하지 않는다.
|
||||
## 대표 실행 흐름
|
||||
|
||||
## 데이터 계약
|
||||
1. App이 단일 입력 경로에서 lexical sibling 결과·로그 경로를 만들고 output lease를
|
||||
획득한다. Lease를 얻기 전에 공개 파일을 truncate하지 않는다.
|
||||
2. 입력을 한 번 읽고 source 위치·raw 표기와 함께 syntax를 해석한다. Mapper가 target,
|
||||
element/section/material 및 procedure 조합을 검증해 Domain을 만든다.
|
||||
3. 준비 단계가 static, nonlinear static, frequency 또는 HHT executor로 분기한다.
|
||||
Domain을 복사해 별도 모델을 만들지 않는다.
|
||||
4. 선택된 procedure가 active view, equation과 workspace를 구성하고 local 계산,
|
||||
ordered assembly, constraint, solve 및 필요한 반복을 수행한다.
|
||||
5. 해와 recovery를 검증해 procedure 전용 state에 반영한다. 비선형·동적 trial은
|
||||
이전 committed state/history와 독립적이며 실패한 trial은 공개하지 않는다.
|
||||
6. 완료 outcome을 얻은 뒤 로그 close를 확인하고 해당 writer를 호출한다. Writer는
|
||||
임시 파일에 기록·검사·close를 마친 뒤 최종 HDF5를 교체한다.
|
||||
|
||||
### Identity
|
||||
State commit과 파일 교체는 별개의 실패 경계다. 일부 frame을 내부에서 accept했더라도
|
||||
전체 해석이 실패했다면 미완성 이력을 새로운 정상 결과 파일로 공개하지 않는다.
|
||||
반면 실행 로그는 실패를 설명하기 위해 남을 수 있어 최종 결과와 보존 범위가 다르다.
|
||||
|
||||
다음 개념을 같은 정수나 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 의미
|
||||
Domain이 모델 정의를 소유한다. AnalysisModel, DOF 구성에 사용되는 참조와 실행 객체가
|
||||
Domain보다 오래 살아서는 안 된다. DofManager는 topology에서 물리 DOF와 equation
|
||||
순서를 구성하며 node/element 내부에 equation 번호를 배포하지 않는다.
|
||||
|
||||
Renumbering, filtering, 병렬 scheduling과 serialization 뒤에도 필요한 대응 관계를
|
||||
보존한다. Reference matching은 row 순서가 아니라 계약된 source identity와 component를
|
||||
사용한다. 특정 typed wrapper나 result-key 클래스를 이 문서만으로 새로 만들지 않는다.
|
||||
현재 procedure마다 static, nonlinear, eigen, dynamic state를 구별한다. 공통된다는
|
||||
이유로 사용하지 않는 가속도·plastic state·thermal field를 일괄 추가하지 않는다.
|
||||
새 procedure는 필요한 lifecycle을 정의한 뒤 준비 단계에서 연결한다. 기존 static
|
||||
반복문에 조건문으로 물리를 누적하지 않는다.
|
||||
|
||||
### Units, coordinates와 result meaning
|
||||
Source identity, internal entity index, DOF component, equation index와 결과 위치는
|
||||
서로 다른 경계의 식별자다. Assembly와 serialization 사이에서 row 순서를 바꾸더라도
|
||||
source와 결과의 대응은 명시적으로 유지한다.
|
||||
|
||||
입력 값의 단위계를 임의로 추론하거나 결과에 맞춰 변환하지 않는다. 필요한 dimension,
|
||||
좌표계, component 순서, 변환과 부호는 정식화 및 I/O 계약으로 고정한다.
|
||||
서로 다른 위치나 정의의 recovery quantity를 같은 결과로 취급하지 않는다.
|
||||
Averaging, extrapolation 또는 station 변환은 별도 승인된 의미가 있을 때만 수행한다.
|
||||
## 계산과 병렬화
|
||||
|
||||
### 모델, view와 state의 수명
|
||||
Element/local load 계산은 index-owned buffer에 기록한다. TBB 작업을 join한 뒤
|
||||
stable COO ordering과 고정된 reduction으로 sparse matrix와 global vector를 만든다.
|
||||
Global storage를 여러 worker가 직접 수정하지 않으므로 thread scheduling이 합산 순서를
|
||||
정하지 않는다. 진단 선택과 결과 row의 순서도 같은 원칙으로 관리한다.
|
||||
|
||||
- `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은 프로젝트 지침을 따른다.
|
||||
MKL은 private dense 연산과 PARDISO·FEAST backend에서 사용한다. Linear solver와
|
||||
tangent solver의 matrix 성질을 구별하고, eigen finite-space reduction은 해석 모델의
|
||||
책임으로 유지한다. Backend 선택이 물성·경계조건·질량을 바꾸는 fallback이 되지 않는다.
|
||||
|
||||
## 입력, 결과와 진단
|
||||
|
||||
Input adapter는 지원되는 외부 syntax, scope, default와 model/history 의미를
|
||||
검증된 semantic model로 mapping한다. 의미상 무해하다고 계약된 항목만 warning/no-op으로
|
||||
처리할 수 있으며 나머지 미지원 semantics는 fail-closed로 진단한다.
|
||||
입력 adapter는 syntax뿐 아니라 procedure별 허용 의미까지 검사한다. Source 이름·
|
||||
label·raw spelling은 보존하고 내부 정렬과 결과 schema의 고정 storage 이름을 분리한다.
|
||||
무시 가능한 출력 요청은 허용된 조합에만 적용한다.
|
||||
|
||||
Results/recovery가 물리량의 의미를, output adapter가 저장 layout을 소유한다.
|
||||
Authoritative output과 diagnostic log, debug view, reference artifact를 구분한다.
|
||||
공식 형식, 파일명, schema version, mandatory dataset과 backward compatibility는
|
||||
현재 프로젝트·Feature I/O 계약을 따른다. 일반화 때문에 기존의 필수 결과를 optional로
|
||||
바꾸거나 다른 파일 형식으로 대체하지 않는다.
|
||||
Recovery는 물리량의 위치·좌표·단위·부호를 결정하고 writer는 이를 저장한다.
|
||||
Final output은 입력의 lexical sibling인 `<stem>_results.h5`다. Log와 debug CSV는
|
||||
다른 역할이며 공식 HDF5를 대신하지 않는다. HDF5 self-check와 solver의 물리 검증은
|
||||
서로 다른 책임이다.
|
||||
|
||||
Output은 계약된 임시 candidate에 기록하고 검증·close를 완료한 뒤 최종 결과로 반영한다.
|
||||
실패 frame이나 불완전한 파일을 정상 결과처럼 공개하지 않는다. 내부 state의 commit과
|
||||
외부 파일의 finalization은 서로 다른 경계이므로 각각의 failure contract를 정의한다.
|
||||
Expected failure는 Status/Result로 이동하며 source location과 entity를 포함한
|
||||
Diagnostic으로 변환한다. App이 공개 오류 출력과 종료값을 결정한다. Vendor 코드가
|
||||
public exit code나 사용자 입력의 의미를 직접 결정하지 않는다.
|
||||
|
||||
Diagnostic은 실패 단계, 안정된 code와 메시지, 가능한 source location/entity를 제공한다.
|
||||
정확한 category, field와 CLI exit code는 I/O 계약을 따른다. Backend 오류를 그대로
|
||||
누출하거나 내부 failure classification을 새 public exit code로 임의 승격하지 않는다.
|
||||
## 빌드와 개발 실행 영역
|
||||
|
||||
## 검증과 reference 경계
|
||||
CMake는 `fesa_solver` static library, `fesa_cli` 실행 파일과 C++ 테스트를 구성한다.
|
||||
Project-owned dependency target이 MKL·TBB·HDF5의 package target 차이를 감싼다.
|
||||
GoogleTest는 승인된 로컬 source checkout을 사용한다. Windows 실행 target 옆에
|
||||
필요한 MKL·OpenMP·TBB·HDF5 및 관련 runtime을 준비하며 link 성공만으로 실행 환경이
|
||||
완성되었다고 판단하지 않는다.
|
||||
|
||||
검증 coverage와 비교량의 논리적 정의는 Numerical Review, 물리량의 저장·외부 대응은
|
||||
I/O, 실행 evidence는 구현 담당자, 독립 물리 판단은 Physics Evaluation의 전문 책임이다.
|
||||
메인은 작업에 필요한 전문 판단만 배정하며 고정 stage 순회를 요구하지 않는다. 수식·요소·
|
||||
재료·적분·상태 갱신 변경에는 독립 수치 검토와 해당 analytical/invariant 검증을 수행한다.
|
||||
각 담당자는 상위 계약을 결과에 맞춰 수정하지 않는다.
|
||||
Python 실행 경로는 `execute.py → config/discovery/toolchain → adapter → process`다.
|
||||
Adapter는 CMake/CTest 또는 MSBuild 명령 계획을 만들고 process는 argv·cwd·timeout과
|
||||
결과 검사를 수행한다. FESA 제품의 검증 baseline은 CMake/MSVC x64 Debug/CTest다.
|
||||
Python 실행기 회귀는 별도 suite이며 CTest가 이를 자동 실행하지 않는다.
|
||||
|
||||
- Source identity, location과 component 일치 여부를 수치 tolerance보다 먼저 확인한다.
|
||||
- Missing, extra, duplicate와 nonfinite required value를 숨기지 않는다.
|
||||
- 외부 reference 판정은 [TOLERANCE](TOLERANCE.md)의 공통 정책을 적용한다. 물리 평형,
|
||||
정식화와 수렴의 검증 기준은 각자의 계약을 따른다.
|
||||
- Reference artifact의 naming이나 보조 metadata를 맞추기 위해 파일을 변경하지 않는다.
|
||||
- 공개 입력 의미나 관찰 가능한 결과 비교를 외부 solver의 내부 동작 동등성으로 해석하지 않는다.
|
||||
|
||||
구현 존재, 특정 revision의 검증 통과와 현재 release readiness는 별도로 확인한다.
|
||||
Architecture 문서의 그림이나 모듈명이 기능의 완료 증거를 대신하지 않는다.
|
||||
|
||||
## 개발 운영 인프라
|
||||
|
||||
현행 운영은 [ADR-028](ADR.md#adr-028), 역할·인계는
|
||||
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill 적용은
|
||||
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실행 동작은
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 source·config에 대조한다.
|
||||
|
||||
| Owner | 책임 |
|
||||
| --- | --- |
|
||||
| 메인 assistant | 범위·작업 분해, 필요한 전문 작업 배정, 직접 계획·구현·수정, Feature context와 완료 evidence 확인 |
|
||||
| Specialist | 할당된 전문 판단·파일과 간결한 결과; 상위 계약 문제를 owner와 메인에 전달 |
|
||||
| 구현 담당자 | 메인 또는 implementation-agent로서 코드·테스트·관련 검증과 필요한 reference evidence 작성 |
|
||||
| Harness runner | 명시 호출 시 config·project·toolchain 선택, adapter 계획 실행과 결과 반환 |
|
||||
| Backend adapter/process | CMake/CTest 또는 MSBuild 명령 구성, argv/cwd·timeout·실패·결과 검사 |
|
||||
|
||||
구성된 solver build/test와 Harness 구현의 Python 회귀 검증은 별도 범위다.
|
||||
현재 CMake adapter와 CTest 등록은 Harness Python suite를 실행하지 않는다.
|
||||
Harness 동작 변경의 Python 검사는 구현 담당자가 변경 영향에 맞게 별도로 수행하며,
|
||||
Runner 성공을 미실행한 Python 검사나 reference 비교의 통과로 확장하지 않는다.
|
||||
|
||||
Runner는 내부 LLM, phase 상태기계, 자동 Git·retry, 파일명 TDD gate나 대화 종료 hook을
|
||||
사용하지 않는다. 과거 phase/coordination 기록은 이력으로 보존한다. 일반 실패는 현재
|
||||
구현 owner가 수정하며 새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.
|
||||
|
||||
Project config·preset·command는 검토해야 할 실행 입력이다. Repository 경로 검사,
|
||||
`shell=False`와 timeout이 실행 파일의 side effect를 모두 격리하는 sandbox는 아니다.
|
||||
사용자 변경을 보존하고 실제 도구 권한과 외부 solver·원격·파괴 작업의 명시적 승인을 따른다.
|
||||
승인된 일반 작업에 반복 승인을 추가하지 않으며 계획 요청만으로 실행을 시작하지 않는다.
|
||||
|
||||
변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 계약상 필수
|
||||
reference 비교를 한 번 수행한다. 요청이나 넓은 영향으로 전체 검증이 필요한 경우에도
|
||||
실행하고 이후 변경·실패가 없으면 반복하지 않는다. 문서 작업은 정적 검토로 확인한다.
|
||||
명령·exit code·판정값과 미실행 항목을 필요한 보고서에 기록하며 Harness 성공만으로
|
||||
물리·수치 correctness나 외부 release readiness를 선언하지 않는다.
|
||||
|
||||
## 문서와 아키텍처의 변경
|
||||
|
||||
프로젝트 공통 원칙의 변경은 공통 ADR로, 구현 항목별 선택은 해당 Feature ADR로
|
||||
기록한다. Feature PRD는 범위·작은 요구사항·acceptance와 현재 checklist의 원본이다.
|
||||
복잡한 requirements·formulation·I/O는 필요한 경우에만 전문 문서로 분리하고 PRD에서
|
||||
참조하여 원본을 중복하지 않는다. 메인이 관리하는 핵심 문서 3개와 선택적 상세 산출물은
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)의 소유권과 링크 규칙을 따른다.
|
||||
|
||||
Public dependency, identity, 수명, result meaning이나 lifecycle 변경은 영향받는
|
||||
계약과 evidence를 함께 검토한다. 상위 계약 변경으로 영향받는 evidence는 stale 처리하며,
|
||||
문서 정리만으로 기존 기능의 재검증이나 release 승인을 완료한 것으로 표시하지 않는다.
|
||||
|
||||
개정 전 구현 설명은 [보존본](archive/pre-generalization/ARCHITECTURE.md)에 남긴다.
|
||||
해당 설명을 Feature 문서로 이관할 때 원래 범위와 승인 revision을 확인한다.
|
||||
현재 문서는 과거 구현 상세를 삭제하여 계약을 없애거나 미래 API를 선결정하지 않는다.
|
||||
개발 작업을 조정하는 메인과 전문 agent는 파일·검증 evidence를 다루지만 솔버가 이들을
|
||||
호출하지 않는다. 실행기는 내부 LLM·phase 상태기계·자동 Git·자동 retry·대화 종료 hook을
|
||||
소유하지 않는다. 과거 운영 기록은 실행 가능한 현재 pipeline으로 해석하지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user