# 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가 모듈 내부 메모리를 숨기거나, 풀·완료 큐·이전 문맥을 포함하면 이득이 사라지거나,
부분 실패에서 데이터를 잃으면 해당 설계를 수정한다. 기존 구현에 없던 제약을 붙여 이긴 경우에도
같은 조건의 비교로 별도 보고한다. 이번 초안에서 새로운 원리·성능 우월성을 입증하지 않았다.