Architecture Decision Records

이 문서는 구조해석 FEM solver framework의 현재 architecture decision을 한 곳에서 관리한다. 모든 항목은 별도 표기가 없으면 Accepted다. 결정을 바꿀 때 기존 항목을 삭제하거나 의미를 바꾸지 않고 새 ADR에서 Supersedes 관계를 기록한다.

ADR-001: Solver core와 adapter의 계층 분리

상태: Accepted
결정: Semantic model, element/material, analysis와 results를 core에 두고 input, persistence, sparse/vendor backend는 adapter로 둔다. 의존성은 adapter에서 core로 향한다.
근거: Physics와 numerical contract가 file format 또는 vendor API 수명에 종속되는 것을 방지한다.
결과: 작은 feature에서도 mapping layer가 필요하다. 대신 parser, storage와 backend를 독립적으로 교체·시험할 수 있다.

ADR-002: C++17과 MSVC x64를 초기 검증 baseline으로 사용

상태: Accepted
결정: Solver production code의 최소 언어 수준은 C++17이며 Windows baseline은 MSVC x64다. CMake/CTest 또는 명시된 Visual Studio solution은 .harness/config.json에서 선택한다.
근거: 현재 Harness가 검증 가능한 현실적 baseline을 제공하면서 vendor extension을 public contract로 만들지 않기 위함이다.
결과: 다른 compiler/platform 지원은 별도 evidence가 생기기 전까지 보장하지 않는다. Toolchain upgrade는 compatibility 및 numerical regression 검토가 필요하다.

ADR-003: Feature contract와 TDD를 구현 선행 조건으로 사용

상태: Accepted
결정: Requirement, formulation, numerical/verification와 I/O contract가 준비된 뒤 production 구현을 시작한다. 구현은 실패 test 관찰 후 최소 변경으로 통과시킨다.
근거: 수식이나 output meaning이 불명확한 상태에서 코드가 사실상의 계약이 되는 것을 방지한다.
결과: 작은 변경에도 직접 test와 evidence가 필요하다. 명백한 상위 계약 결함은 implementation에서 우회하지 않고 owner에게 반환한다.

ADR-004: Abaqus는 공개 reference convention이며 solver identity가 아님

상태: Accepted
결정: 공식 Abaqus 문서의 입력 의미, analysis procedure, output definition과 verification 사례를 observable behavior 기준으로 사용한다. 선택된 .inp subset은 adapter contract로 구현한다.
근거: 익숙하고 문서화된 CAE convention을 활용하면서 비공개 구현 복제나 과도한 호환성 주장을 피한다.
결과: 지원 subset과 차이를 명시해야 한다. 내부 알고리즘 동등성, 전체 호환성과 bitwise result 일치를 주장하지 않는다. 다른 interchange adapter도 core를 변경하지 않고 추가할 수 있다.

ADR-005: Stable typed identity를 배열 위치와 분리

상태: Accepted
결정: Source label, internal entity, DOF, equation과 result key를 서로 다른 identity로 표현한다. 외부 result/reference 매칭은 row order 대신 semantic key를 사용한다.
근거: Renumbering, filtering, parallel processing과 storage ordering이 physical identity를 훼손하지 않게 한다.
결과: Explicit mapping 비용이 생기지만 duplicate/missing/extra entity를 deterministic하게 검출할 수 있다.

ADR-006: Immutable model과 transactional analysis state

상태: Accepted
결정: 검증된 model definition은 analysis 동안 immutable하다. Iteration의 trial state와 마지막 converged committed state를 분리하고 성공한 increment만 commit한다.
근거: Nonlinear/material update 실패가 다음 retry와 published result를 오염시키지 않게 한다.
결과: State copy, checkpoint 또는 rollback protocol이 필요하다. 성능 최적화는 동일한 failure atomicity를 보존해야 한다.

ADR-007: Local element kernel과 global assembly를 분리

상태: Accepted
결정: Element는 명시적 local ordering으로 residual/tangent와 recovery data를 반환한다. DOF numbering, sparsity, scatter, constraint와 global reduction은 별도 module이 소유한다.
근거: Element formulation을 작은 test로 검증하고 여러 assembly/backend에서 재사용하기 위함이다.
결과: Evaluation context와 local contribution contract가 필요하다. Element가 global matrix나 source parser에 직접 접근하는 편의는 허용하지 않는다.

ADR-008: Deterministic ordering과 reduction을 correctness로 취급

상태: Accepted
결정: Numbering, contribution ordering, floating-point reduction tree와 output ordering을 명시적으로 관리한다. 병렬화는 동일 identity와 허용된 numerical envelope를 검증한다.
근거: 회귀 비교, 문제 재현과 물리 검토가 실행 scheduling에 좌우되지 않게 한다.
결과: 일부 빠른 비결정적 알고리즘을 사용할 수 없거나 별도 opt-in contract가 필요할 수 있다.

ADR-009: Structured diagnostic과 fail-closed semantic validation

상태: Accepted
결정: Input/model/formulation/assembly/solver/convergence/recovery/storage/environment 실패를 stable category와 code로 반환한다. 지원하지 않는 의미는 기본적으로 오류다.
근거: Silent fallback이나 warning-only 처리가 잘못된 해석을 정상 결과처럼 보이게 하는 위험이 크다.
결과: Parser와 adapter가 더 엄격할 수 있다. 결과에 영향이 없다고 명시된 construct만 warning으로 낮출 수 있다.

ADR-010: Backend-neutral results와 versioned persistence

상태: Accepted
결정: Physical result identity를 in-memory results model이 소유하고 CSV, HDF5 또는 다른 저장 형식은 versioned adapter가 projection한다. Validated candidate만 atomic publish한다.
근거: 저장 layout 변경이 solver physics와 public quantity 의미를 바꾸지 않게 한다.
결과: Schema version, units, coordinates, location, step/frame와 provenance metadata가 필요하다. 특정 저장 형식은 feature/project 설정으로 선택한다.

ADR-011: 다중 방법 verification과 immutable reference artifact

상태: Accepted
결정: Unit/patch/analytical/manufactured/convergence/invariant/reference comparison 중 feature에 적합한 둘 이상의 독립 방법을 사용한다. 승인된 reference input, expected result와 tolerance는 implementation이 수정할 수 없다.
근거: 같은 가정을 공유하는 한 가지 비교만으로는 formulation, mapping과 implementation 오류를 구분하기 어렵다.
결과: Evidence 준비 비용이 증가한다. Artifact가 없거나 상충하면 구현을 억지로 맞추지 않고 numerical/reference owner에게 반환한다.

ADR-012: Coordinator-owned workflow와 critical-only human gate

상태: Accepted
결정: Coordinator가 공통 handoff envelope를 검증하고 다음 owner와 state transition을 결정한다. Agent는 승인 범위의 repository-local 작업을 자율 수행하며 제품 의미, 공개 호환성, acceptance, authoritative artifact, 보안·법률 위험 수용 또는 외부 권한을 바꾸는 결정만 사용자에게 요청한다.
근거: 모든 단계의 반복 승인 병목을 제거하면서 되돌리기 어렵거나 제품 정의를 바꾸는 선택은 사람이 통제하게 한다.
결과: 상태 schema, evidence digest, retry signature와 허용 transition을 기계적으로 검증해야 한다. 같은 signature의 correction은 한 번만 허용한다.

ADR-013: Project configuration은 실행 가능한 신뢰 경계

상태: Accepted
결정: Build preset, solution과 test command를 포함하는 .harness/config.json은 code와 같은 review 대상이다. Harness는 repository-relative path와 구조화된 command만 허용하고 unrelated working-tree content를 stage하지 않는다.
근거: shell=False만으로 executable 또는 preset의 side effect를 격리할 수 없기 때문이다.
결과: 임의 PATH executable과 repository 밖 command는 거부한다. danger-full-access, remote push와 파괴 작업에는 명시적 권한 및 격리 조건이 필요하다.

ADR 추가 기준

다음 변경은 새 ADR이 필요하다.

Core dependency 방향 또는 public module 경계 변경
Identity, units, coordinates, state ownership 또는 result meaning 변경
Analysis lifecycle, constraint 방식 또는 convergence contract의 공통 정책 변경
지원 toolchain/platform baseline 또는 persistence compatibility 변경
Agent 권한, human gate 또는 authoritative evidence precedence 변경

단순 구현 세부사항, 한 feature에만 적용되는 formulation과 되돌릴 수 있는 내부 refactoring은 해당 feature 문서나 implementation plan에 기록한다.

8.9 KiB Raw Blame History