---
baseline: N0021@r0000
created: 2026-04-13T04:44:36.429019+00:00
---

## Delta

# Proposal 004: 첨부 파일 지원 및 무결성 검증 (Attachment Support & Integrity Validation)

## 개요
현재 `entries/NXXXX/attachments/` 폴더는 존재하지만, 이를 관리하는 CLI 명령어나 파일의 무결성을 보장하는 장치가 없습니다. 
지식 베이스에 이미지, 로그, PDF 등 바이너리 파일을 안전하게 첨부하고, 파일이 변조되거나 유실되지 않았는지 검증하는 기능을 제안합니다.

## 배경 및 문제점
1. **관리 도구 부재**: 사용자가 수동으로 폴더에 파일을 넣어야 하며, 어떤 파일이 첨부되었는지 `manifest`에 기록되지 않습니다.
2. **무결성 보장 불가**: 외부 요인으로 첨부 파일이 손상되거나 변경되었을 때, `elf validate` 명령어가 이를 감지하지 못합니다.
3. **이동성(Portability) 저하**: 다른 환경으로 Vault를 복사했을 때, 일부 첨부 파일이 누락되어도 알 수 있는 방법이 없습니다.

## 제안하는 변경 스펙

### 1. 명령어 도입
- `elf entry attach <ID> <FILE_PATH>`: 파일을 `attachments/` 폴더로 복사하고 `manifest.toml`에 등록합니다.
- `elf entry detach <ID> <FILE_NAME>`: 파일을 폴더에서 삭제하고 `manifest.toml`에서 제거합니다.

### 2. 무결성 보장 메커니즘 (Hash-based Validation)
- `manifest.toml`에 `[[attachments]]` 섹션을 추가하고, 각 파일의 **SHA-256 해시값**과 파일 크기, 원본 파일명을 기록합니다.
- **`elf validate` 확장**: 기존 인덱스/노트 검사 외에도, `attachments/` 내 파일들의 해시를 재계산하여 `manifest`와 일치하는지 대조합니다.

### 3. 데이터 동기화
- `sync.jsonl`에 첨부 파일 추가/삭제 이벤트를 기록하여, 분산 환경에서의 동기화 무결성을 확보합니다.

## 고려 사항 및 안건 (Discussion)
- **파일 크기 제한**: Vault 자체의 경량성을 유지하기 위해 첨부 가능한 파일의 최대 크기(예: 50MB) 설정 필요 여부.
- **중복 방지**: 동일한 해시를 가진 파일이 여러 Entry에 첨부될 경우, 스토리지 절약을 위해 공유 저장소(Content-Addressable Storage) 방식을 채택할지 여부.
- **버전 관리**: 첨부 파일 자체도 리비전(Revision)에 따라 버전 관리를 할 것인가? (초기 단계에서는 현재 버전만 유지하는 것을 권장).

## 기대 효과
1. **신뢰할 수 있는 지식 베이스**: 텍스트 데이터뿐만 아니라 증거 자료(바이너리)까지 무결성이 보장된 상태로 보존할 수 있습니다.
2. **자동화 도구 연동**: AI 에이전트가 작업 결과물(이미지, 로그)을 자동으로 엔트리에 첨부하고 검증할 수 있는 안정적인 API를 제공합니다.
