# Release Bundle 형식 — 배포 담당자용

- bundle 생성은 개발 측에서 Git의 정확한 commit을 사용합니다. 현장 설치에는 Git이 필요 없습니다.
- `.git`, AGENTS, docs/profiles, deployment-review, 개인 기록은 고객 bundle에서 제외합니다.
- checksum은 훼손 검사입니다. 배포자 신뢰는 별도 승인 SHA256 전달로 확보합니다.
- 실제 image/model bytes와 제3자 라이선스/배포 권한은 담당자가 확인합니다.

## 1. 형식

```text
release.tar.gz
  manifest.json        첫 파일, schema1
  SHA256SUMS           파일별 SHA256
  deployctl
  deployment_kit/
  source/              허용된 운영 source/Compose/template
  docs/deployment/     현장 문서만
  images/              필요한 image tar
  models/              필요한 asset
```

manifest: `release_id`, CONFIG/APP/FULL `kind`, `source_sha`, `compatibility_id`, 선택 `parent_release`,
`requirements`, `images`, `build_contract`, `files`를 가집니다.
각 image는 service/reference/immutable `id`와 선택 archive 경로입니다. 64자리 hash는 실제값을 사용합니다.
사양 예시는 `source/deploy/configs` 아래가 아니라 **개발 repo의 `deploy/configs/*.example`**에서 확인할 수 있습니다.
검증된 bundle에서는 그 파일들이 `source/deploy/configs/`로 배치됩니다.

## 2. 생성

```bash
./deployctl bundle create --repo /absolute/reviewed-repo --spec /safe/release-spec.json --output /safe/contextra-v1.tar.gz
./deployctl bundle verify /safe/contextra-v1.tar.gz
```

spec에 이미지 등 assets를 넣을 때는 source HOST 절대경로/destination `images/` 또는 `models/`/sha256를 명시합니다.
Git tracked 파일이라도 작업공간 bytes가 source_sha와 다르면 중단합니다. untracked 파일은 자동 배포하지 않습니다.
링크/특수파일/경로 탈출/중복/누락/파일·디렉터리 충돌을 거부합니다.

## 3. 작은 패치의 기준

CONFIG는 app/sidecar bytes와 image가 그대로여야 합니다. APP은 Analytics 앱만 재빌드합니다.
FULL도 compatibility_id가 다르면 자동 데이터 migration하지 않습니다. 이 ID는 엔지니어가 검토한 계약이지 자동 호환성 증명이 아닙니다.
SDK/native 변경 때 full image는 별도 승인된 개발 빌드로 준비합니다. bundle source가 전체 개발 build context를 대체하지는 않습니다.

## 4. 보관

최소 현재와 직전 두 release, 해당 image/model/manifest를 보관합니다. 도구는 자동 prune하지 않습니다.
배포물에는 secret을 넣지 않습니다. customer image 안에 개발 기록이 baked-in되어 있지 않은지도 image 제작자가 별도 검사합니다.