feat(publish): settle a publish whose outcome is unknown from the publish page

[Eomdahyeon]

Closes #728

문제

publish 가 publish_state_unknown 으로 끝나면 Studio 는 "자동 재시도하지 마세요, 운영자에게 요청하세요"만 보여 준다. Builder 에는 복구 경로(reconcile, receipt reset)가 있지만 Studio 가 부르지 않는다. 사용자가 UI 에서 할 수 있는 일이 없다.

변경 내용

• builderApi.reconcilePublish(POST …/publish/reconcile), builderApi.resetPublishReceipt(DELETE …/publish/receipt?target&destination). 둘 다 재시도 없음. 자격 증명은 X-Publish-Credential 헤더로만.
• 응답 스키마 publishReconcileResponseSchema, publishReceiptResetSchema — 계약의 PublishReconcileResponse, PublishReceiptReset 와 이름으로 짝지어진다.
• 게시 실패 카드에 복구 패널(PublishRecoveryPanel), publish_state_unknown 일 때만:
  • 원격 확인 → 있으면 "게시는 이루어졌습니다"(다시 보낼 버튼 없음), 없으면 기록이 지워지고 "다시 게시 준비" 버튼.
  • 기록 초기화 → 두 번째 클릭("초기화 확정")이 있어야 실행되고, "이미 올라간 것은 지워지지 않는다"는 경고를 먼저 보여 준다.
  • 원격을 읽지 못하면(503) "아무것도 바뀌지 않았다"고 말하고 재게시 버튼을 주지 않는다.
  • 기록이 없으면(404 receipt_not_found) 정리할 것이 없다고 말한다.
• 요청에서 자격 증명을 받는 배포에서는 원격 확인에 토큰이 필요하다. Studio 는 게시 시작 때 토큰을 버리므로(feat(publish): send the request-scoped publish token in multi-user deployments #615) 다시 입력하게 하고, 그 한 번의 요청에만 쓰고 다시 버린다.
• 어느 것도 자동으로 실행되지 않는다. "다시 게시 준비"도 사용자가 누르고, 누른 뒤에는 원래의 확인 단계부터 다시 거친다.
• ko/en 문구, CHANGELOG, EXPECTED_OPERATIONS 에 두 호출 추가.

의존 — kpubdata-lab/kpubdata-builder#1009

네 라우트는 Builder 에서 1.19/1.20 부터 응답해 왔지만 계약 paths 에는 #1009 가 처음 선언한다. 그 PR 이 Builder main 에 들어가기 전까지:

• 이 PR 의 드리프트 검사는 두 스키마를 대조할 대상이 없어 그냥 지나간다(실패하지 않는다).
• test(contract): check that every route the client calls is in the contract #743(클라이언트의 모든 경로가 계약에 있는지 검사)이 먼저 머지되면, 이 PR 은 그 검사에서 실패한다 — 두 경로가 아직 계약에 없으므로. #1009 가 먼저 들어가야 한다.

#1009 의 계약 파일로 드리프트 검사를 로컬에서 돌려 봤다: 스키마 대조 461개 통과. 실패한 2개는 계약 파일만 복사하고 fixture 디렉터리를 같이 두지 않아서 난 "fixture 가 옆에 있는가" 검사다 — 스키마와는 무관하다.

검증

• __tests__/publishRecovery.test.tsx(16개): 요청의 method·path·body·헤더, 토큰이 URL·body 에 없음, 404/503 분류와 재시도 없음, 다른 run 의 응답 불신, Builder 오류 문구를 그대로 보여 주지 않음, 패널이 누르기 전에는 아무것도 부르지 않음, reset 의 두 단계, 토큰 없이는 원격 확인을 하지 않음.
• npx vitest run: 238 files passed, 2405 passed | 9 skipped. tsc --noEmit, eslint 통과.
• 실제 Builder 와 실제 Hugging Face 로 확인한 것은 아니다. 브라우저에서 화면을 직접 보지도 않았다.

review:R3 — 작성자가 아닌 사람의 승인이 필요하다.

🤖 Generated with Claude Code

[Eomdahyeon]

#743 이 머지되어 main 위로 rebase 했습니다. 이제 Builder contract drift 잡이 이 PR 에서 실패합니다 — 의도된 실패입니다: reconcilePublish 와 resetPublishReceipt 가 부르는 두 경로를 Builder 계약이 아직 선언하지 않았고(kpubdata-builder#1009 가 선언), #743 의 경로 검사가 바로 그것을 잡습니다. 로컬에서 Builder main 계약으로 돌리면 every client function sends a method and path the contract declares 1건만 실패합니다(1 failed | 554 passed).

순서: kpubdata-builder#1009 머지 → 이 PR 의 drift 잡 재실행 → 리뷰. 그 전에는 머지하지 않습니다.

[yeongseon]

리뷰 (코멘트 — 승인은 builder#1009 가 main 에 들어가고 이 PR 의 드리프트 검사가 실제 계약과 대조된 뒤에).

diff 를 읽었습니다. 걸리는 로직은 없습니다.

• 어느 것도 자동으로 실행되지 않고, reset 은 두 번째 클릭과 경고 뒤에만 나갑니다. 테스트가 "누르기 전에는 fetch 0회" 를 확인합니다.
• 원격을 읽지 못한 503 과 confirmed 에서는 재게시 버튼을 주지 않습니다. 재게시가 허용되는 것은 absent·reset·nothing_to_settle 뿐입니다.
• 토큰은 헤더로만 가고, 다른 run 의 응답은 믿지 않고, Builder 의 오류 문장을 그대로 보여 주지 않습니다 — 각각 테스트가 있습니다.

승인을 미루는 이유 두 가지:

1. 계약 대조가 아직 없습니다. publishReconcileResponseSchema·publishReceiptResetSchema 가 짝지을 계약 스키마는 builder#1009 가 처음 선언합니다. 그 PR 은 지금 충돌 상태이고 버전도 다시 잡아야 합니다. 본문대로 #743 이 먼저 들어가면 이 PR 은 그때까지 경로 검사에서 실패합니다.
2. 화면을 본 사람이 없습니다. 본문이 밝힌 대로 브라우저에서 확인하지 않았고 실제 Builder·Hugging Face 로도 돌리지 않았습니다. 기록을 지우는 동작이 있는 R3 화면이라, 머지 전에 한 번은 눈으로 봐야 합니다.

[Eomdahyeon]

kpubdata-builder#1009 가 머지되어(계약 1.81.0) 이 PR 을 그 계약에 맞췄습니다 (4e4d361).

지금 Studio main 의 Builder contract drift 잡은 빨갛습니다. 1.81.0 이 복구 경로의 응답·오류 예시를 선언했고 main 의 drift 테스트는 그것을 모릅니다 — 로컬에서 main 을 Builder main 계약으로 돌리면 응답 예시 5건, 오류 예시 5건 등이 실패합니다. 이 PR 이 들어가면 풀립니다 (kpubdata-builder#1004 가 말한 바로 그 순서 문제입니다).

추가한 것:

• OPERATION_SCHEMAS: getPublishReceipt, getPublishAudit 를 skip 으로 — Studio 는 둘 다 부르지 않습니다.
• ERROR_READERS: reconcilePublish / resetPublishReceipt 의 404 ReceiptNotFound → nothing_to_settle, 503 ReconcileUnavailable → unavailable 를 recoveryFailure 로 실제로 읽어 확인합니다 (그래서 그 함수를 export 했습니다). getPublishReceipt 404 는 부르지 않는 경로라 not-handled 로 올렸습니다. 모두 since: 1.81.0.

확인: Builder main (813827d) 의 계약·fixture 로 npx vitest run src/shared/lib/contractDrift.test.ts → Tests 576 passed (576). npx tsc --noEmit, eslint 출력 없음. 1.80.0 계약으로는 2건 실패합니다(복구 경로가 아직 없는 계약이므로 예상된 결과) — CI 는 Builder main 만 읽습니다.

R3 라 승인을 기다립니다.

[yeongseon]

kpubdata-builder#1009 를 머지했습니다 (계약 1.81.0). 그 결과 이 PR 뿐 아니라 main 기준 모든 PR 의 Builder contract drift 가 실패해서, #746 으로 네 라우트의 예시를 drift 검사에 등록해 먼저 풀었습니다 (머지됨).

이 PR 에서 할 일:

1. main 을 합친다.
2. test(contract): list Builder's publish recovery examples in the drift test #746 이 넣은 임시 항목 중 이 PR 이 부르는 둘을 실제 것으로 바꾼다 — OPERATION_SCHEMAS 의 reconcilePublish·resetPublishReceipt skip 을 지우면 이름 짝짓기(PublishReconcileResponse, PublishReceiptReset)가 다시 동작하고, ERROR_READERS 의 reconcilePublish/resetPublishReceipt 404·503 네 항목은 recoveryFailure 를 읽는 reader 로 바꿉니다. getPublishReceipt·getPublishAudit 은 그대로 둡니다.

그 뒤 drift 가 녹색이면 다시 리뷰하겠습니다. 화면 확인은 여전히 필요합니다.

[Eomdahyeon]

#746 이 머지되어 main 을 합쳤습니다. contractDrift.test.ts 의 충돌은 이렇게 풀었습니다 — #746 본문이 예고한 교체 그대로입니다:

• reconcilePublish, resetPublishReceipt: test(contract): list Builder's publish recovery examples in the drift test #746 의 skip / notHandled 대신 이 PR 의 실제 스키마 대조와 recoveryFailure reader.
• getPublishReceipt, getPublishAudit: 여전히 부르지 않으므로 skip, 404 는 test(contract): list Builder's publish recovery examples in the drift test #746 의 NOT_CALLED 문구로 not-handled.

Builder main 계약(1.81.0)으로 contractDrift.test.ts + publishRecovery.test.tsx 를 돌린 결과는 아래 CI 와 같습니다. 리뷰의 두 번째 조건(화면을 눈으로 보는 것)은 제가 대신할 수 없습니다 — 브라우저와 실제 Hugging Face 대상이 없습니다.

[yeongseon]

다시 읽었습니다. 승인합니다.

• main 을 합치면서 #746 의 임시 항목을 예고대로 바꿨습니다: reconcilePublish·resetPublishReceipt 는 실제 스키마 대조와 recoveryFailure reader 로, getPublishReceipt·getPublishAudit 은 부르지 않으므로 skip/not-handled 그대로.
• 첫 번째 조건(계약 대조)은 충족됐습니다 — Builder contract drift 가 Builder main(1.81.0)으로 녹색입니다.
• 두 번째 조건(화면을 눈으로 보는 것)은 충족되지 않았습니다. 저도 이 환경에서 Studio 를 띄울 수 없습니다. 그래도 머지하는 쪽으로 판단했습니다: 패널의 동작 — 누르기 전에는 아무것도 부르지 않음, reset 은 두 번 클릭, 503·confirmed 에서는 재게시 버튼 없음 — 은 컴포넌트를 실제로 렌더하는 테스트가 고정하고 있고, 눈으로만 잡을 수 있는 것은 배치·문구의 어색함이지 잘못된 동작이 아닙니다. 화면 확인은 후속 이슈로 남깁니다.