---
id: "req-0002"
status: approved
discovery: "dcy-0002"
criteria:
  create:
    - "ac-0006"
    - "ac-0007"
    - "ac-0008"
    - "ac-0009"
    - "ac-0010"
    - "ac-0011"
    - "ac-0012"
  update: []
  retire: []
  satisfy: []
---

# Requester-versioned GHCR 이미지 게시 계약

## Objective

`portfolio-hub`가 requester가 명시적으로 선택한 strict `vX.Y.Z` tag의 exact source에서 검증된 OCI image를 한 번만 build하고, 설치 payload·HTTP·PostgreSQL migration/readiness·비밀 제외·artifact identity를 검증한 동일 artifact만 GHCR에 게시할 수 있는 fail-closed capability를 제공한다.

## Scope

- Alembic 설정과 모든 migration을 installable package data로 포함하고 source, wheel 및 image inventory의 non-empty exact parity를 유지한다.
- Python 3.11과 repository-owned `uv.lock`을 verification 및 runtime dependency 설치에 사용하며 non-root runtime과 deny-by-default build context를 제공한다.
- 일반 branch/main은 registry write 권한 없이 full regression과 release/container contract를 검증하고, strict `vX.Y.Z` tag push만 publication authority와 `packages: write`를 가진다.
- verify 단계가 exact tagged commit에서 image를 한 번 build하고 installed payload, DB-disabled HTTP liveness, isolated PostgreSQL migration·DB ping·DB-enabled liveness 및 cleanup을 검증한다.
- tested image ID, archive SHA-256, OCI revision과 secret canary를 fail-closed로 검사하고, publish 단계는 같은 archive를 checksum 검증 후 load하여 rebuild 없이 source selector와 requester version selector에 게시하며 same digest를 확인한다.
- 운영자에게 immutable digest, 명시적 pre-start `pfhub migrate-db`, runtime secret/read-only/writable mount 및 image rollback과 DB rollback의 분리 경계를 문서화한다.

## Constraints

- automatic version bump, malformed/prerelease tag publication, moving `latest`, branch/main registry write를 허용하지 않는다.
- 실제 credential, production DB, production migration 및 bootstrap-user side effect를 smoke에 사용하지 않는다.
- image build·검증·publication capability는 운영 deployment 기능·설정·실행과 분리한다.
- registry login/push 전 검증 실패는 external registry write 전에 fail-closed여야 한다. push 이후에만 얻는 digest가 없거나 malformed이면 workflow는 nonzero로 실패하고 성공 summary를 내지 않지만 이미 발생한 registry write를 없었다고 주장하지 않는다.
- 이 승인된 사양은 로컬 구현 커밋 `96260b6302e050c6e564f3eca4e723558f26246f`의 의도를 기술하지만, 사후 ProofLine 문서화 자체가 정식 implementation chronology, delivery closure, push, publication, release 또는 deployment 완료를 소급 생성하지 않는다.

## Non-Goals

- 이 Requirement에서 version 선택, Git tag 생성·push, 기능 브랜치 push, PR, GHCR publication 또는 package visibility 변경을 실행하지 않는다.
- GitHub Release, 운영 서버/Dockge/Compose 배포·재시작, production credential·DB·migration·downgrade·repair·reset·backup을 수행하지 않는다.
- deployment orchestrator, multi-architecture build, signing, SBOM, attestation을 추가하지 않는다.
- application API/domain behavior, sibling repository 또는 unrelated repository-wide lint debt를 변경하지 않는다.
- ProofLine 정식 시퀀스로 구현됐다는 소급 주장을 만들지 않는다.