# APOSTOLUS 16-2 · 16-3 · 치매 비약물치료·진단 묶음의 가상 검증 하네스

설계 명세 두 건의 판정 장치를 표준 라이브러리 Python으로 실행하는 참조 구현이다. 입력은 고정 픽스처 두 개이고 모든 자료는 코드가 만든 합성 코호트다. ADNI, OASIS-3, DementiaBank의 원자료와 요약 통계는 읽지 않고 담지도 않는다. 아래 수치는 합성 가정 위의 가상 지표이며 실제 코호트 성능이 아니다.

| 과제 | 설계 명세 | 내부 연구 목표 | 1차 가상 지표 |
| --- | --- | --- | --- |
| 16-2 | 적응형 인지훈련 난이도 제어 엔진 | 난이도 수렴률 95% 이상 | 962/1000 (96.2%), 단측 95% 하한 0.9505 |
| 16-3 | 다기관 MRI·음성 융합 위험도 층화 | 외부 코호트 AUROC 0.90 이상 | 합성 외부 AUROC 0.932 (하한 0.909), 0.926 (하한 0.905) |

## 읽을 때 함께 봐야 하는 것

- **16-2의 여유는 작다.** 반복 실행 2회 중 하한 게이트를 넘은 것은 1회다. 세 실행을 합치면 2890/3000 (96.3%, 하한 0.9572)다.
- **16-2의 수렴률은 판정 정의에 따라 달라진다.** 같은 궤적에 정의만 바꾸면 81.1%에서 97.2%까지 움직인다.
- **16-2의 분포 이동 14개 중** 점추정 95%를 넘은 것은 5개, 하한까지 넘은 것은 3개다. 가장 낮은 것은 `SH_ACUTE_DROP` (36.0%)다. 급변 검출 변형은 이 시나리오를 58.6%로 올리지만 기본 코호트를 95.6%로 낮춰 1차 정책에는 넣지 않았다.
- **16-2의 정책 모형과 응답 생성기는 같은 함수형을 쓴다.** 함수형이 다른 생성기에서는 측정하지 않았다.
- **16-3에서 0.90에 못 미친 조건**: `ZERO_ADAPTATION_B_TO_A`, `SPEECH_UNSEEN_UNIT`, `EFFECT_SCALE_0.5`, `EFFECT_SCALE_0.75`. 시드를 바꾼 10회 평가에서 점추정 통과 9회, 하한 통과 7회, 최솟값 0.881.
- **16-3의 동시 보유(영상+음성) 평가는 합성 쌍에서만 했다.** 공개 자료에는 같은 대상의 MRI·음성 쌍이 없다.

## 실행

프로젝트 루트에서 Python 3.10 이상으로 실행한다. 외부 패키지는 필요 없다.

```sh
python3 -B -m cog16.orchestrate --output evidence/cog16-run.json
python3 -B -m cog16.audit --run evidence/cog16-run.json --output evidence/cog16-audit.json
python3 -B -m unittest discover -s tests -p 'test_cog16_*.py' -v
```

실행기는 16-2의 코호트 몬테카를로(1,000명 × 2,304시행 × 24개 실행) 때문에 작업자 11개로 약 5–6분 걸린다. 감사기는 약 1초, 단위 시험 61건은 약 15초다(다른 작업이 함께 도는 부하에서 잰 값). 작업자 수는 결과에 영향을 주지 않는다. `python3 -B -m cog16.orchestrate --check evidence/cog16-run.json`은 다시 실행해 바이트 단위로 비교한다. 감사가 실패하면 첫 실패 관문과 사유를 JSON에 적고 종료 코드 1을 돌려준다. 감사 문서의 `humanAuditorSignature`는 항상 비어 있고 `researchStatus`는 `external_cohort_not_run`이다.

| 파일 | 역할 |
| --- | --- |
| `_contract.py` | 정규화·해시, 픽스처 잠금, 식별자 형식 문자열 검사(`free_text_paths`), 원자적 쓰기 |
| `_stats.py` | 재현 가능한 난수열, 이항 꼬리와 Clopper–Pearson 구간, 정규분포 도우미, 소형 선형대수 |
| `t162.py` | 다차원 문항반응 가상 환자(학습·피로·일중·피로 붕괴·지연시간), 확장 칼만 필터와 레짐 필터, 안전 제약형 밴딧, 실패 안전 상태 기계, 독립 감시기, 수렴 판정, 분포 이동·결함 주입·프로토콜 사례 |
| `t163.py` | 합성 다기관 코호트, ComBat 경험적 베이즈와 미관측 단위 보정, 명부 감사, 결측 모달리티 융합망과 수작업 역전파, 온도 보정과 evidential 출력, fast DeLong, ECE, 매칭·순열·누출 통제, 라우터 |
| `orchestrate.py` | 두 과제 블록을 한 증거 문서로 묶는 실행기 |
| `audit.py` | 풀이 모듈을 import하지 않고 다른 구현으로 다시 계산하는 감사기 |

## 실행기와 감사기의 분리

감사기는 `t162`·`t163`을 불러오지 않는다. 같이 쓰는 것은 `_contract.py`의 직렬화·해시 도우미와 고정 픽스처뿐이다. 주장이 실린 수치는 다른 방법으로 다시 계산한다.

| 대상 | 실행기 | 감사기 |
| --- | --- | --- |
| 16-2 1차 실행의 성공 수·층별 수·조건별 수·정착 시간 분위수 | 환자별 판정에서 집계 | 증거 문서의 환자별 정수 행 1,000개에서 다시 집계 |
| Clopper–Pearson 하한·상한 254개 | 로그 감마 부동소수 합과 이분법 | 보고된 한계를 정수 산술 이항 꼬리 방정식에 대입 |
| 16-2 수렴 판정(정착 시간, 밴드 내 비율, RMS, 좌절 사건) | 부동소수 이동 합 | 프로토콜 사례 5건의 궤적에서 정수 누적합으로 다시 유도 |
| 16-2 게이트 표지·합산·분포 이동 통과 목록 | 실행 중 계산 | 보고된 수에서 다시 계산 |
| 16-3 AUROC와 DeLong 구간 21개(1차 2, 무적응 2, 음성·융합 3, 효과 배율 4, 시드 반복 10) | 중간순위 알고리즘 | 증거 문서의 사례별 점수에서 전수 비교 정의와 유리수 분산 |
| 16-3 1차 평가의 보정 오차(ECE, Brier) | 구간별 합의 차 | 구간별 평균의 차(교과서 정의) |
| 16-3 게이트 문자열·시드 반복 집계·효과 배율 판정 | 실행 중 계산 | 감사기가 다시 계산한 AUROC와 하한에서 유도. `benchmark`의 16-3 수치도 감사기 계산값 |

두 프로그램은 같은 파일 권한으로 돈다. 정답을 숨긴 독립 블라인드 환경이 아니며, 별도 호스트·컨테이너 실행과 감사자 서명은 하지 않았다. 16-2의 코호트 시뮬레이션 자체(가상 환자 응답 생성)와 16-3의 모형 적합은 감사기가 다시 돌리지 않는다. 감사기가 확인하는 것은 증거 문서에 실린 행·궤적·점수에서 주장이 따라 나오는지다. 16-2의 반복·분포 이동·기준 정책 실행은 환자별 행을 싣지 않으므로, 그 성공 수는 실행기 집계값이고 감사기는 그 수의 구간과 게이트만 다시 계산한다. 관문 하나가 실패하면 감사는 거기서 멈추고 `auditStatus`는 `fail`, 뒤 관문은 `not_run`으로 남는다.

## 네 관문

| 관문 | 확인하는 것 |
| --- | --- |
| G1 동결 입력과 제출 구조 | 픽스처 2개의 잠금 해시, 제출 본문 해시, 문서의 모든 문자열이 식별자 형식인지 |
| G2 판정 정의·통제 완전성과 구조 규칙 | 16-2 판정 정의가 픽스처와 같은지, 층·시나리오·기준 정책이 빠짐없는지, 감시기 위반 0건, 프로토콜 사례 5건. 16-3 명부 감사 위반 0건, 누출 결함 전부 검출, 순열 통제, 기지 정답 검사 |
| G3 독립 재계산 | 위 표의 재계산이 제출값과 일치하는지 |
| G4 가상 지표 판정과 결과 해시 | 두 과제의 1차 가상 지표가 사전 정의 기준에 드는지. 실행 문서 해시를 감사 문서에 기록 |

현재 기록: 실행 문서 해시 `7a8639328bb25ec9…`, 감사 문서 해시 `c2b0a655e2652113…`, 관문 4개 통과.

## 하지 않은 것

- 실제 ADNI·OASIS-3·DementiaBank 자료에서의 측정. 반입 절차는 각 명세서의 11장에 있다.
- PyTorch 모듈 실행(이 환경에 torch가 없다)과 16-3 도메인 적대 학습. 인터페이스와 수식만 있다.
- 참고 문헌의 원문 대조.