docs: organize project guidance and module contracts

2026-09-29 00:34:57 +09:00
parent 73db138566
commit a3502c9b97
50 changed files with 1748 additions and 414 deletions
@@ -0,0 +1,15 @@
+# 공개 C++ interface
+
+이 영역은 외부 consumer와 solver 내부 계층이 공유하는 선언·값·실패·수명 계약을 소유한다.
+구현 파일의 세부 구조나 vendor handle은 공개 API에 포함하지 않는다.
+
+- Header는 단독 include로 사용할 수 있어야 한다. Repository 경로 기반 include guard와
+  직접 필요한 include를 사용하고 src의 private header를 역으로 include하지 않는다.
+- MKL·TBB·HDF5·Win32 타입은 공개하지 않는다. Concrete adapter class 선언이 있더라도
+  resource는 private implementation에 격리한다.
+- Source identity, entity index와 equation index를 구분한다. 반환한 record의 단위·좌표·
+  location과 non-owning 인자의 수명을 production Doxygen에 기록한다.
+- Status/Result로 표현하는 expected failure와 exception 경계를 보존한다. Future용
+  optional state·virtual method를 공통 base에 추가하지 않는다.
+- Interface 변경은 consumer compile, 소유권·수명, invalid combination과 현재 결과의
+  보존을 검증한다. 선언만 추가하고 parser나 CLI 지원까지 완료됐다고 보고하지 않는다.