KOKO\Mimi
152 lines
14 KiB
Markdown
152 lines
14 KiB
Markdown
# Step 4: MKL FEAST adapter와 bounded lowest-N 검색
|
||
|
||
> 과거 개발 계획이다. 아래 작업·상태·예시는 현재 실행 지시가 아니다.
|
||
> 현재 구현과 검증 한계는 [기능 요약](../../docs/mitc4-shell-feast-eigen/README.md)을 따른다.
|
||
|
||
- Feature ID: `mitc4-shell-feast-eigen`
|
||
- Input contract revision: `r2`
|
||
- Phase: `mitc4-shell-feast-eigen`
|
||
- Dependency: 동일 phase의 Step 3 completed
|
||
- Requirement IDs: `FEM-REQ-MITC4-EIGEN-009`, `FEM-REQ-MITC4-EIGEN-010`, `FEM-REQ-MITC4-EIGEN-011`, `FEM-REQ-MITC4-EIGEN-012`, `FEM-REQ-MITC4-EIGEN-013`, `FEM-REQ-MITC4-EIGEN-023`
|
||
- Logical cases: `MFE-C17`, `MFE-C18`, `MFE-C19`, `MFE-C21`, `MFE-C22`
|
||
- I/O obligations: `IO-T06`
|
||
|
||
## 필수 입력과 계약
|
||
|
||
Feature 폴더는 `docs/mitc4-shell-feast-eigen/`다. 아래 current r2 입력을 읽고 기존 완료 Step 코드와 evidence를 대조한다. 연결된 upstream contract는 read-only다.
|
||
|
||
- [AGENTS.md](../../AGENTS.md)
|
||
- [docs/SOLVER_AGENT_DESIGN.md](../../docs/solver-core/README.md)
|
||
- [docs/FEATURE_DOCUMENTATION.md](../../docs/solver-core/README.md)
|
||
- [docs/PRD.md](../../docs/solver-core/README.md)
|
||
- [docs/ARCHITECTURE.md](../../docs/solver-core/README.md)
|
||
- [docs/ADR.md](../../docs/solver-core/README.md)
|
||
- [docs/CODINGSTYLE.md](../../docs/solver-core/README.md)
|
||
- [docs/TOLERANCE.md](../../docs/solver-core/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/FEATURED_AGENTS.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/PRD.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/ADR.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/coordination.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/requirements.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/requirements-evidence.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/research.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/research-evidence.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/formulation.md](../../docs/mitc4-shell-feast-eigen/formulation.md#formulation)
|
||
- [docs/mitc4-shell-feast-eigen/formulation-mass.md](../../docs/mitc4-shell-feast-eigen/formulation.md#formulation-mass)
|
||
- [docs/mitc4-shell-feast-eigen/formulation-eigen.md](../../docs/mitc4-shell-feast-eigen/formulation.md#formulation-eigen)
|
||
- [docs/mitc4-shell-feast-eigen/formulation-verification.md](../../docs/mitc4-shell-feast-eigen/formulation.md#formulation-verification)
|
||
- [docs/mitc4-shell-feast-eigen/formulation-stabilization.md](../../docs/mitc4-shell-feast-eigen/formulation.md#formulation-stabilization)
|
||
- [docs/mitc4-shell-feast-eigen/numerical-review.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/numerical-review-evidence.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/numerical-review-controls.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/numerical-review-cases.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/reference-model.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/io.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/io-input.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/io-schema.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/io-mapping.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/implementation-plan.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/implementation-environment.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/implementation-interfaces.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
- [docs/mitc4-shell-feast-eigen/implementation-verification.md](../../docs/mitc4-shell-feast-eigen/README.md)
|
||
|
||
이 Step의 직접 계약: [formulation-eigen.md#e7-feast-경계와-deterministic-실행](../../docs/mitc4-shell-feast-eigen/formulation.md#formulation-eigen--e7-feast-경계와-deterministic-실행), [numerical-review-controls.md#c5-feast-controls와-bounded-interval-정책](../../docs/mitc4-shell-feast-eigen/README.md), [numerical-review-controls.md#c6-initial-subspace-thread와-storage](../../docs/mitc4-shell-feast-eigen/README.md), [io-mapping.md#m2-backend와-failure-lifecycle](../../docs/mitc4-shell-feast-eigen/README.md), [formulation-eigen.md#e6-유한-search-interval과-요청-개수](../../docs/mitc4-shell-feast-eigen/formulation.md#formulation-eigen--e6-유한-search-interval과-요청-개수), [io-schema.md#o4-backend와-검증-evidence](../../docs/mitc4-shell-feast-eigen/README.md).
|
||
논리 case의 전체 parameter/threshold/음성 inventory는 NR 원문과 [verification mapping](../../docs/mitc4-shell-feast-eigen/README.md)을 함께 적용한다.
|
||
|
||
## Owned paths
|
||
|
||
다음 목록은 phase index `owned_paths`와 exact equality를 유지한다. 목록 밖 파일이 필요하면 보존하고 Coordinator에 반환한다. 다른 agent도 같은 worktree를 사용하므로 타인 변경을 되돌리지 않는다.
|
||
|
||
```json
|
||
[
|
||
"src/fesa/solvers/eigen/feast_backend.h",
|
||
"src/fesa/solvers/eigen/feast_backend.cpp",
|
||
"src/fesa/solvers/eigen/feast_initial_space.h",
|
||
"src/fesa/solvers/eigen/feast_initial_space.cpp",
|
||
"tests/unit/solvers/eigen/feast_backend_test.cpp",
|
||
"tests/unit/solvers/eigen/feast_initial_space_test.cpp",
|
||
"src/fesa/CMakeLists.txt",
|
||
"tests/CMakeLists.txt",
|
||
"include/fesa/solvers/eigen/eigen_solver.h",
|
||
"include/fesa/solvers/eigen/mkl_feast_eigen_solver.h",
|
||
"src/fesa/solvers/eigen/mkl_feast_eigen_solver.cpp",
|
||
"src/fesa/solvers/eigen/feast_search.h",
|
||
"src/fesa/solvers/eigen/feast_search.cpp",
|
||
"tests/unit/solvers/eigen/eigen_solver_test.cpp",
|
||
"tests/unit/solvers/eigen/mkl_feast_eigen_solver_test.cpp",
|
||
"tests/unit/solvers/eigen/feast_search_test.cpp",
|
||
"docs/mitc4-shell-feast-eigen/implementation-step4-evidence.md"
|
||
]
|
||
```
|
||
|
||
## 같은 session의 behavior별 TDD
|
||
|
||
각 소단위는 아래 순서로 RED→observed failure→minimal GREEN→focused VERIFY를 완료한다. 마지막 소단위 뒤 full VERIFY를 한 번 수행하고 등록 Stop의 정상 전체검증도 받는다. Missing API의 정확한 compile/link failure는 RED일 수 있으나 configure/dependency 오류는 RED가 아니다. 이미 통과한 test를 새 RED라고 보고하지 않는다.
|
||
|
||
### 1. 실제 MKL FEAST call, CSR/자원/initial-space 계약
|
||
|
||
Symbols: `eigen_internal::FeastBackend/FeastCallRequest/FeastCallResult; BuildFeastInitialSpace; actual feastinit/dfeast_scsrgv private calls`.
|
||
|
||
**RED:** Private request tests에 malformed/missing/duplicate/nonfinite/0-based/out-of-range CSR, n²/n*m0/nnz+1 representation overflow와 allocation injection을 추가한다. Fixed uint64 sequence와 QR orthogonality/rank-failure, thread-local restore on every exit를 검사한다. 실제 linked MKL의 full-enclosure count/solve smoke test를 추가해 부재를 관찰한다. Mock call 성공을 real backend evidence로 대신하지 않는다.
|
||
|
||
**Minimal GREEN:** C5/C6의 one-based upper CSR/identity B, fpm snapshots, count scratch n×n, m0 overwritten count와 solve m 구분을 구현한다. Neutral std integer records 밖 vendor MKL_INT를 노출하지 않는다. Per-call feastinit, fixed seed/nonpivoted QR, local thread guard, checked allocation RAII, raw status/history를 보존한다. API smoke의 enclosure는 matrix-derived로 만들고 known values로 fitting하지 않는다. Lowest-N search/completeness gate는 Step4에서 완성한다.
|
||
|
||
**Focused VERIFY:** 아래 regex 중 해당 suite를 먼저 discovery하여 tests>0을 확인하고 같은 test를 재실행한다. Exact exit와 실패 이유를 behavior별로 기록한다.
|
||
|
||
### 2. Prefix/guard/count 기반 lowest-N FEAST 탐색
|
||
|
||
Symbols: `EigenSolver::SolveLowest; MklFeastEigenSolver::SolveLowest; eigen_internal::SearchFeastSpectrum; EigenSolveResult/FeastCallEvidence`.
|
||
|
||
**RED:** Actual C17 zero/N=n/simple spectra 및 C18 fortyfold cluster>N/tight distinct/dense-pattern spectra를 production search로 풀고 independent known ordered values/count history와 대조한다. Injected false count/low-mode omission이 residual·Gram만 통과해도 search는 실패해야 한다. C21 statuses/endpoint/nonmonotone/total!=n/m!=c와 C22 count512/solve3 경계 및 certified fallback을 먼저 실패시킨다.
|
||
|
||
**Minimal GREEN:** A의 stable inf scale와 outward Gershgorin, C5 delta/guard/prefix/32+32 search/384+128 budget/ordered collision offsets를 구현한다. Safe c>=N bracket 및 m0 formula, admissible retry3·금지 retry, final prefix0/actual interval count 및 all-c columns를 반환한다. Count source는 실제 backend, zero count는 info0만 인정한다. Public request N은 불변이며 scale0의 model-derived fallback은 caller가 전달한다. Actual raw negative 값을 backend에서 clamp하지 않는다. C3의 full original-space validation은 Step5 소유다.
|
||
|
||
**Focused VERIFY:** 아래 regex 중 해당 suite를 먼저 discovery하여 tests>0을 확인하고 같은 test를 재실행한다. Exact exit와 실패 이유를 behavior별로 기록한다.
|
||
|
||
## Focused 명령
|
||
|
||
Workspace root의 PowerShell에서 실행한다. 초기 missing API RED라면 build의 expected failure를 기록하고 production 구현 후 같은 명령을 다시 실행한다.
|
||
|
||
```powershell
|
||
$env:CMAKE_BUILD_PARALLEL_LEVEL = '1'
|
||
cmake --preset mfe-workspace-msvc-ninja-debug
|
||
cmake --build --preset mfe-workspace-msvc-ninja-debug --target fesa_tests
|
||
ctest --preset mfe-workspace-msvc-ninja-debug -R '^(FeastBackend|FeastInitialSpace|MklPardisoSolver|EigenSolver|MklFeastEigenSolver|FeastSearch)\.' --show-only=json-v1
|
||
ctest --preset mfe-workspace-msvc-ninja-debug -R '^(FeastBackend|FeastInitialSpace|MklPardisoSolver|EigenSolver|MklFeastEigenSolver|FeastSearch)\.' --output-on-failure
|
||
```
|
||
|
||
Configure exit는 항상0이어야 한다. GREEN에서는 위 모든 exit0, discovered selected tests>0, failures0이어야 한다. 각 호출의 `$LASTEXITCODE`를 즉시 기록하고 실패 뒤 후속 명령으로 덮어쓰지 않는다.
|
||
|
||
### 필수 신규 test discovery inventory
|
||
|
||
- `MklFeastEigenSolver.MfeC17KnownLowestSpectra`
|
||
- `MklFeastEigenSolver.MfeC18RepeatedAndTightClusters`
|
||
- `FeastBackend.MfeC19RawSignedSpectra`
|
||
- `FeastSearch.MfeC21StatusAndHistoryFailures`
|
||
- `FeastSearch.MfeC22FiniteBudgetsAndCapacity`
|
||
- `FeastInitialSpace.MfeC22SeedQrAndRepresentation`
|
||
|
||
위 이름 모두를 focused 및 full discovery JSON의 `tests[].name`에서 확인한다. Parameterized 전개가 필요하면 원 obligation→실제 discovered 이름을 evidence에 명시하고 모든 전개 case를 실행한다. 단지 selected count>0이거나 기존 suite만 존재하는 것은 실패다. V2의 해당 독립 oracle/mutation과 이 Step의 behavior assertions를 실제 구현해 각 결과를 기록한다.
|
||
|
||
## Full VERIFY
|
||
|
||
현재 backend는 local user preset `mfe-workspace-msvc-ninja-debug`/MSVC x64 Debug다. 이 Step의 명령을 직접 실행하며 local config/preset과 다른 graph로 fallback하지 않는다.
|
||
|
||
과거 도구 실행·출력 지시는 정리했으며, 현재 검증 방법은 기능 요약을 따른다.
|
||
|
||
전체 discovery의 test count와 실제 실행 count를 대조하고 skipped/missing/unobserved를 성공으로 합치지 않는다. 기존 target의 `/W4 /WX`를 유지하고 새 compiler/link warning0을 확인한다. 등록 Stop의 전체 검증은 그대로 수행되며 수동 hook 실행·state/reentry 조작으로 대체하지 않는다. Step 4에서 영향받는 C++ binary가 바뀌면 기존 reference helper의 cache 재사용 여부와 실제 solve 호출을 구분한다. 최종 fresh portfolio의 권위는 Step 7이다.
|
||
|
||
## Evidence와 종료
|
||
|
||
- `../../docs/mitc4-shell-feast-eigen/README.md`
|
||
|
||
이 Step의 evidence에는 Feature/owner/r2, exact owned changed paths, RED→GREEN 명령·actual exits·기간·핵심 수치, focused/full counts, MSVC/x64/Debug/dependency/runtime selection, warning 수, upstream case/requirement 연결, 미실행 및 residual risk를 기록한다. Raw logs는 Git ignored 과거 검증 자료(정리됨)에 보존한다. 각 CTest 호출 직후 해당 `Testing/Temporary/LastTest.log`를 고유 RED/focused/full 이름으로 복사하여 이후 Stop 로그와 섞지 않는다. Binary/reference/result hash와 run freshness는 적용되는 경우 기록한다.
|
||
|
||
보고서 작성 시점에는 마지막 registered Stop/Codex exit가 아직 발생하지 않을 수 있다. Implementation은 실제 완료된 manual 검증과 미관찰 Stop을 구분하고 미래 성공을 선기록하지 않는다. `completed` payload는 그 자체로 Stop 성공 증거가 아니다. Executor 종료 뒤 Coordinator가 raw output·등록 Hook evidence·actual exit를 management 문서에서 사후 감사한다. Specialist 보고서 본문은 Coordinator가 대신 수정하지 않는다.
|
||
|
||
Manual AC가 성공하면 Executor가 허용한 `phases/mitc4-shell-feast-eigen/index.json`의 **현재 Step 4만** `status=completed`와 비어 있지 않은 `summary`를 기록한다. 구현/검증 실패는 `error/error_message`, 환경·필수 준비 차단은 `blocked/blocked_reason`이다. `owned_paths`, 이름/번호, 다른 Step/top index, timestamp, attempt_history는 수정하지 않는다. `step4-output.json`은 Executor 생성 기록이며 ignored 상태를 유지한다. 마지막 응답은 공통 handoff envelope다. Phase 전체 또는 workflow gate의 자기 승인은 하지 않는다.
|
||
|
||
## 제외와 중단 조건
|
||
|
||
Physics/formulation/I/O/tolerance/원본 reference·기존 feature 보고서 변경, 외부 solver, spectrum fitting, eigen 외부 vector/frequency/stress gate, sparse rank cutoff, sandbox 확대, retry-budget 변경, Git branch/commit/push/tag/release는 소유 범위 밖이다. 명백한 구현 결함은 이 exact scope 안에서 최소 수정한다. 계약 결함은 정확한 owner로 `return-upstream`, 실행 환경 실패는 actual command/exit와 함께 Coordinator로 반환한다. 동일 실패를 transport timeout으로 가장하거나 evidence를 지우고 재실행하지 않는다.
|