Establish native micro runtime checkpoint

1 files changed, 139 insertions, 0 deletions

diff --git a/docs/research/005-foundation-contract.md b/docs/research/005-foundation-contract.md
new file mode 100644
index 0000000..842b732
--- /dev/null
+++ b/docs/research/005-foundation-contract.md
@@ -0,0 +1,139 @@
+# Pure 연구 보고서 005: 연산·수명·모듈 경계
+
+작성일: 2026-09-22
+상태: **설계 초안과 데이터 레이아웃의 제한된 컴파일 검사 완료**.
+버퍼 런타임·모듈 로더·포맷 지원·새 컴파일러가 구현됐다는 뜻은 아니다.
+
+## 이번에 정한 것
+
+사용자는 현재 문법이 매력적이고 기본 사용에 걸림돌이 없었다고 평가했다.
+동시에 현재 결과는 평범한 작은 DSL로 보이며 실제 서비스·앱·CLI 개발을 통해 가치를 확인해야 한다고 했다.
+이 피드백을 특정 사용자의 현재 경험으로 기록한다. 대규모 개발 생산성이나 독창성 검증으로 확대하지 않는다.
+
+그다음 합의는 **연산 의미 → 데이터 수명·소유권 → 모듈 계약**을 먼저 명세하는 것이다.
+커널 우회는 실제 입출력 병목이 확인될 때 별도 백엔드로 검토한다.
+압축·암호화·문서·미디어·OS를 다루려는 장기 목표도 기록했다.
+각 분야를 실제 지원하거나 새로운 알고리즘을 만드는 일은 별도의 구현·검증 범위를 갖는다.
+
+이번 산출물:
+
+| 문서 | 정한 경계 |
+|---|---|
+| [연산 의미](../design/001-operation-semantics.md) | 숫자 계산, 관리 상태 확정, 버퍼 변환, 외부 효과의 실패 범위 |
+| [메모리·수명](../design/002-memory-lifetime.md) | 예산, 버퍼 소유자·대여, 비동기 완료·취소·반납 |
+| [모듈 계약](../design/003-module-contract.md) | 프로파일·버전·진행 결과, 네이티브 호출과 영속 형식의 구분 |
+| [C17 레코드 초안](../design/abi-v0.h) | 핸들·구간·스트림 결과·한도 정보의 필드 폭과 크기 |
+
+제작 화면의 문법·동작은 이번 작업에서 바꾸지 않았다. 새 데모를 조작해 평가할 과제도 없다.
+현재 사용성 피드백을 유지하면서 다음 실제 앱이 요구할 기반을 명확히 하는 단계다.
+
+## 가장 중요한 세 가지 결정
+
+**첫째, 취소 요청과 버퍼 반납은 다르다.**
+파일·네트워크·장치 작업은 취소 요청 뒤에도 접근이 남을 수 있다.
+접수된 작업의 대여는 최종 완료를 회수할 때까지 유지한다. 동기 백엔드도 같은 요청 계약을 사용한다.
+libuv 역시 요청 관련 메모리를 완료 콜백 전에 해제하지 않도록 요구한다.
+이 자료를 일반적인 수명 계약의 근거로 사용했고 libuv를 실제 의존성으로 추가하지는 않았다.
+[libuv 요청 계약](https://docs.libuv.org/en/v1.x/request.html#c.uv_cancel)
+
+**둘째, 입력 소비·유효 출력·스트림 종료를 따로 센다.**
+압축 해제는 입력을 다 읽은 뒤에도 출력과 종료 처리가 남을 수 있다.
+첫 바이트 프로파일은 `consumed`, `produced`, `status`를 따로 반환한다.
+코덱의 내부 윈도·문맥도 예산에 포함해야 하므로 외부 버퍼 크기만으로 전체 메모리를 판단하지 않는다.
+근거로 읽은 Zstd 매뉴얼은 1.5.1이며 최신 라이브러리 버전 추천은 아니다.
+[Zstandard 매뉴얼](https://facebook.github.io/zstd/zstd_manual.html)
+
+**셋째, 물리적으로 쓴 바이트와 사용 가능한 데이터는 다르다.**
+첫 출력 프로파일은 유효 길이 0인 별도 버퍼에 쓰고, 완료 회수 시 검증된 접두부만 공개한다.
+인증 복호화는 해당 인증 단위가 성공한 뒤에만 평문을 유효 출력으로 전달한다.
+이것은 검증된 암호 라이브러리의 계약을 보존할 조건이며 자체 암호 알고리즘 제안이 아니다.
+[libsodium 인증 암호화](https://doc.libsodium.org/secret-key_cryptography/secretbox)
+
+## 현재 구현과의 차이
+
+현재 Workbench의 숫자 오류 복구는 32개 `f64` 배열을 임시 복사한 뒤 함께 확정하는 구조다.
+외부 출력이나 제자리 버퍼 쓰기까지 되돌리는 기능은 없다.
+그래서 새 초안은 **자원 예약 → 관리 상태·작업 목록 확정 → 실제 백엔드 제출 → 완료 처리**를 구분한다.
+확정 전 자원 부족은 기존 상태를 보존하며, 확정 후 백엔드 실패는 이미 발급한 티켓의 완료로 보고한다.
+
+현재 `revision`은 적용 횟수이며 ABI 버전이 아니다. 내부 Zig 구조체의 `@sizeOf`도
+포맷·모듈 파일의 직렬화 규칙이 아니다. 64 KiB는 Wasm 선형 메모리이며 전체 컴파일러·앱의 상한이 아니다.
+이 세 수치를 미래 계약의 보장으로 잘못 재사용하지 않는다.
+
+## 작게 만들기 위해 선택한 제약
+
+- 첫 모듈은 바이트 스트림 프로파일로 제한한다. 파일·GPU·다중 평면 미디어의 결과는 별도 프로파일이 필요하다.
+- 한 스트림 문맥에는 진행 요청 하나만 허용한다. 첫 제어 흐름은 실행 영역별 직렬 처리다.
+- 입력과 출력 버퍼를 분리하고 버퍼 전체 단위로 읽기 공유 또는 쓰기 독점을 적용한다.
+- 요청·완료·대여·버퍼 슬롯을 함께 예산에 넣는다. 느린 소비자로 포화되면 역압력을 반환한다.
+- 진행 작업·대여·열린 문맥이 남아 있으면 교체를 거절한다. 첫 계약은 무중단 모듈 교체를 약속하지 않는다.
+- 모듈마다 새 문법·전역 타입 분석·무제한 특수화를 컴파일러에 추가하지 않는다.
+- 작은 핵심 계약과 검증된 외부 라이브러리의 연결을 먼저 시험한다. 내부 알고리즘 재구현은 독립적인 비교 근거가 필요하다.
+
+제약은 비용을 줄이기 위한 가설이지 성능 측정 결과가 아니다.
+고정 풀도 미사용 예약 공간을 낭비할 수 있고, 공통 코드도 직접 특수화한 코드보다 느릴 수 있다.
+어느 쪽이 유리한지는 실제 작업과 전체 비용으로 비교한다.
+
+## 장기 분야가 요구하는 검증
+
+| 분야 | 공통 계약에 요구하는 것 | 해당 분야의 별도 책임 |
+|---|---|---|
+| 압축 | 부분 소비·생성, 종료 처리, 내부 메모리 상한 | 포맷 호환, 압축률·속도·입력 분포, 사전·윈도 |
+| 암호화 | 출력 공개 시점, 키·임시 버퍼 수명 | 검증된 구현, 키·nonce·인증 단위·프로토콜의 올바른 사용 |
+| 문서 | 범위가 명시된 읽기, 점진 처리, 오류 위치 | 구조·인코딩·참조·랜덤 접근·각 포맷의 의미 |
+| 미디어 | 버퍼 대여, 비동기 완료, 시간·역압력 | 프레임·평면·코덱·GPU 동기화·실제 시간 제약 |
+| OS·장치 | 외부 효과·핸들·완료·어댑터 경계 | 플랫폼 API·권한·드라이버·커널 경로, 자체 OS의 별도 설계 |
+
+이 표는 모든 분야를 하나의 바이트 함수로 표현할 수 있다는 주장이 아니다.
+공통으로 보존해야 할 수명·진행·비용 규칙을 정하고, 의미가 다른 부분은 각 모듈이 책임지게 한다.
+지원할 실제 포맷·버전·플랫폼의 목록이나 전체 OS 개발 일정은 아직 정하지 않았다.
+
+## 검증한 범위와 증거
+
+코드·문서 검토에서 다음 모순을 찾아 초안에서 해결했다.
+
+- 런타임 접수 전 거절과 관리 상태 확정 뒤 백엔드 제출 실패의 혼동.
+- 출력 오프셋이 임의일 때 단일 유효 길이로 초기화되지 않은 구간까지 공개할 수 있는 모호함.
+- 취소 중 공유 입력 읽기를 허용하는 규칙과 모든 읽기를 금지하는 검사 항목의 충돌.
+- 동기 백엔드 반환과 런타임의 완료 회수 중 어느 시점에 대여가 끝나는지의 충돌.
+
+그 결과 v0 출력은 빈 버퍼·오프셋 0으로 제한하고, 모든 접수 요청의 대여는 완료 회수까지 유지한다.
+입력의 공유 읽기는 허용하지만 충돌하는 쓰기·재사용은 거절한다.
+
+Zig 0.15.2의 C 컴파일러로 **AArch64 Linux, AArch64 macOS, wasm32**를 대상으로
+레코드 크기·오프셋의 `_Static_assert` 8개씩을 컴파일했다. 세 타깃 모두 성공했다.
+이는 헤더의 제한된 데이터 배치 검사다. M3 실행·함수 호출 ABI·버퍼 수명·성능 검증이 아니다.
+[컴파일 기록과 해시](../design/validation/2026-09-22-record-layout.json)를 보관했다.
+
+```sh
+python3 docs/design/check-abi-layout.py --zig /path/to/zig --output /tmp/pure-abi-new.json
+```
+
+출력 파일은 덮어쓰지 않는다. native ABI의 다음 검증은 독립 C 생산자와 Zig 소비자 사이의
+실제 호출, 버전 거절, 수명·예산 처리다. 현재 헤더에는 함수 테이블이나 동적 로더 구현이 없다.
+
+## 다음 구현의 합격 기준
+
+2026-09-22 후속 결정: [006의 문제 조사](006-problem-landscape.md)에 따라,
+아래 구현에 앞서 기존의 잘 구성한 구현에서 실제 비용과 남은 개선 여지를 확인한다.
+이 계약은 후보 설계이며, 조사·비교 결과에 따라 변경한다.
+
+먼저 작은 고정 버퍼 풀과 요청 슬롯에서 제출·완료·반납을 실행하고,
+포화·부분 출력·취소 경합·늦은 완료·오래된 핸들·교체 거절을 재현한다.
+이는 수명 계약 검사이며 실제 앱 사용성 평가로 대신하지 않는다.
+
+그다음 실제 파일 스트림과 검증된 변환 라이브러리를 연결해
+풀의 총 용량보다 큰 파일, 느린 출력, 잘린 입력, 출력 실패를 다룬다.
+직접 라이브러리를 호출하는 일반 구현과 결과·오류 의미를 맞춘 뒤 다음을 비교한다.
+
+| 측정 축 | 기록할 대상 |
+|---|---|
+| 컴파일러 | 소스·토큰·AST·IR 용량, 최대 작업 메모리, 컴파일 시간, 산출물 크기 |
+| 실행 메모리 | 확보·사용·유지 바이트, 내부 문맥·완료 큐·계측 공간, 전체 RSS |
+| 복사 | 계측한 경로별 바이트, 원본 버퍼 유지 시간, 측정하지 못한 경로 |
+| 처리 | 입출력 총량·정확성·처리량·큐 대기 포함 지연·완료/거절/취소 수 |
+| 제작 | 실제 앱에서 새 기능을 위해 계약 밖 코드나 실행기 변경이 필요했던 지점 |
+
+새 API가 모듈 내부 메모리를 숨기거나, 풀·완료 큐·이전 문맥을 포함하면 이득이 사라지거나,
+부분 실패에서 데이터를 잃으면 해당 설계를 수정한다. 기존 구현에 없던 제약을 붙여 이긴 경우에도
+같은 조건의 비교로 별도 보고한다. 이번 초안에서 새로운 원리·성능 우월성을 입증하지 않았다.