docs(contract): declare the publish recovery routes

[yeongseon]

Refs #994 — 이 PR 은 그 이슈의 일부다 (publish 라우트 4개). 남는 것은 아래 "이 PR 에 없는 것".

문제

GET·DELETE /builds/{run_id}/publish/receipt, POST …/publish/reconcile, GET …/publish/audit 는 계약 1.19.0 / 1.20.0 부터 응답해 왔지만 contract/builder-api.yaml 에는 info.description 의 산문으로만 있었다. paths 에 없으니 클라이언트가 대조할 스키마가 없고, _DISPATCH_ROUTES 에도 없어서 라우트 테스트가 이 넷을 몰랐다. Studio 가 publish_state_unknown 복구 UI 를 붙이려면 (kpubdata-lab/kpubdata-studio#728) 이 선언이 먼저다.

변경 내용

• contract/builder-api.yaml 1.76.0 → 1.77.0 (additive): 네 operation (getPublishReceipt, resetPublishReceipt, reconcilePublish, getPublishAudit) 과 스키마 PublishReceipt, PublishReconcileRequest, PublishReconcileResponse, PublishReceiptReset, PublishAuditLog, PublishAuditEntry. 형태는 service/publish_api.py 와 service/routes/publish.py 가 실제로 돌려주는 것을 읽어 적었다. wire 는 바뀌지 않는다.
• service/app.py: API_CONTRACT_VERSION = "1.77.0".
• contract/fixtures/responses.json: 생성기로 다시 만들었다 (2xx 54 → 59, error 37 → 42).
• tests/unit/test_service_contract.py: _DISPATCH_ROUTES, _REQUIRED_OPERATIONS, _IMPLEMENTED_OPERATIONS, _OPERATION_STATUS_CODES 에 넷을 추가.
• tests/unit/test_service_publish.py::TestPublishRecoveryConformance: 실제 요청의 응답을 선언한 스키마와 대조한다 — unknown receipt, succeeded receipt(result 포함), receipt_not_found 404 (세 라우트), 쿼리 누락 400, reconcile 세 갈래(원격 있음 / 없음 / 읽을 수 없음 503), 모르는 필드 400, reset 과 그 뒤의 audit. 마지막 테스트는 부정 테스트다: 선언에 없는 state 값이 검사를 실패시키는지.

이 PR 에 없는 것 (#994 에 남는다)

• X-Provider-Key 를 header 파라미터로 선언
• 429 auth_throttled, 과부하 503, X-Request-ID 응답 헤더
• _DISPATCH_ROUTES 를 라우트 어댑터에서 생성 — 라우트가 if 연쇄라 표로 바꾸는 리팩터링이 먼저 필요하다

검증

로컬에서 pytest 를 실행하지 못했다. 이 환경에서 files.pythonhosted.org 에 연결되지 않아 uv sync 가 실패한다 (pypi.org 는 200). 새 테스트는 이 PR 의 CI 가 첫 실행이다. 의존성 없이 돌릴 수 있는 것은 돌렸다:

$ python3 scripts/check_contract_compat.py --base origin/main
contract compatible with origin/main: 1.76.0 -> 1.77.0
$ python3 scripts/generate_response_fixtures.py --check
contract/fixtures/responses.json matches the contract
$ python3 scripts/check_version_consistency.py
버전 일치: pyproject 0.4.0 == CHANGELOG
$ python3 scripts/check_english_comments.py
checked 443 files: no Korean comments or docstrings
$ ruff check tests/unit/test_service_publish.py tests/unit/test_service_contract.py src/kpubdata_builder/service/app.py
All checks passed!

계약 YAML 은 yaml.safe_load 로 읽어 operation 68개 (이전 64개) 를 확인했다.

🤖 Generated with Claude Code

[yeongseon]

리뷰 메모 — 리베이스 때 고쳐야 할 것.

계약 버전이 겹칩니다. 이 PR 은 1.76.0 → 1.77.0 으로 올리는데 main 의 API_CONTRACT_VERSION 이 이미 1.77.0 입니다 (#903 의 profile range trim 이 가져갔습니다). 리베이스하면서 1.78.0 으로 올리고 contract/fixtures/responses.json 을 다시 생성해야 합니다. CHANGELOG 항목의 버전도 같이.

스키마 본문(약 400줄)은 publish_api.py 와 줄 단위로 대조하지 못했습니다 — 설명과 파일 구성, 테스트 목록까지만 봤습니다.

[Eomdahyeon]

이 PR 이 main 과 충돌 상태가 된 것은 내가 #1010 을 머지했기 때문이다 — main 의 계약이 1.77.0 이 됐고 이 PR 도 1.77.0 을 쓴다. 미안하다.

#994 의 나머지 중 둘(X-Provider-Key 파라미터, 429 auth_throttled·과부하 503·X-Request-ID)은 #1024 로 올렸다. 그 PR 은 #1022(#996) → #1023(#1000) 위에 쌓여 1.78.0 ~ 1.80.0 을 쓴다. 이 PR 과 그 스택 중 어느 쪽을 먼저 넣을지 정해 주면 내 쪽 버전 줄을 맞추겠다. 원하면 이 브랜치를 main 위로 리베이스하는 것도 내가 할 수 있다 — 남의 브랜치라 요청 없이는 건드리지 않았다.

[yeongseon]

순서 메모: #1022 → #1023 → #1024 스택이 계약 1.78.0 ~ 1.80.0 을 씁니다. 그 스택을 먼저 넣기로 했으니, 이 PR 은 리베이스할 때 1.81.0 으로 올리고 fixture 를 다시 생성해야 합니다 (앞선 코멘트의 1.78.0 은 더 이상 맞지 않습니다). studio#744 가 이 PR 의 선언을 기다립니다.

[yeongseon]

main 을 합쳤습니다. 충돌은 네 파일(CHANGELOG.md, contract/builder-api.yaml, contract/fixtures/responses.json, service/app.py)이었고, 계약 버전을 1.81.0 으로 올렸습니다 — main 이 1.77.0 ~ 1.80.0 을 가져갔기 때문입니다. 본문의 "1.76.0 → 1.77.0" 은 이제 "1.80.0 → 1.81.0" 으로 읽어야 합니다.

의존성 없이 돌릴 수 있는 것만 로컬에서 확인했습니다:

$ python3 scripts/generate_response_fixtures.py --check
contract/fixtures/responses.json matches the contract
$ python3 scripts/check_contract_compat.py --base origin/main
contract compatible with origin/main: 1.80.0 -> 1.81.0
$ python3 scripts/check_version_consistency.py
버전 일치: pyproject 0.4.0 == CHANGELOG
$ python3 scripts/check_english_comments.py src tests scripts
checked 450 files: no Korean comments or docstrings

계약은 operation 68개로 읽힙니다. pytest·mypy 는 로컬에서 돌리지 못했습니다 (files.pythonhosted.org 연결 실패로 uv sync 불가) — 이 푸시의 CI 가 첫 실행입니다. 이 PR 이 main 에 들어가면 studio#744 의 Builder contract drift 를 다시 돌릴 수 있습니다.