fix(durable): bound provider lifecycle fields

[seonghobae]

RED phase for #127

Protected main cd873be84361cceca81e961d757b373a7c4ea95b now enforces durable progress invariants, but durable lifecycle normalization still accepts arbitrary nonempty provider status and endpoint text. That allows unsupported/high-cardinality lifecycle state to become persistence input and leaves terminal semantics dependent on an unvalidated string.

This Draft starts from that exact protected head and is intentionally test-only RED. The regression requires unsupported/missing/control-bearing status or endpoint evidence to fail before PostgreSQL acquisition, without copying the rejected provider value into the package-owned error, while preserving the currently documented OpenAI Batch status set and endpoint set.

Current OpenAI Batch API reference evidence (checked 2026-08-13) documents the supported batch endpoints /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, and /v1/moderations, and lifecycle examples/fields cover validating, failed, in_progress, finalizing, completed, expired, cancelling, and cancelled. Provider-specific extensions remain outside first-party verified compatibility unless independently reviewed.

After the expected RED is observed, the narrow GREEN will change only the durable normalization boundary and focused assurance/doctoring needed for that contract. No schema migration, credential authority, provider transport, scheduler, model, or release authority is intended.

Refs #127.

Summary by CodeRabbit

• 개선 사항

  • 원격 배치의 상태와 엔드포인트 값을 저장 전에 검증합니다.
  • 지원되지 않는 값은 데이터베이스에 연결하기 전에 안전하게 거부합니다.
  • 상태와 엔드포인트가 비어 있으면 기존 기본값을 유지합니다.
  • 공식 상태 및 엔드포인트 값을 일관된 형식으로 저장합니다.

• 문서

  • 배치 생명주기 상태, 종료 상태 및 허용 값에 대한 계약 문서를 추가했습니다.

• 테스트

  • 잘못된 값, NUL 문자 포함 값, 오류 메시지의 입력값 노출 여부를 검증하는 회귀 테스트를 추가했습니다.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 042864ec-1853-45ea-9f38-e6b155ff4017

📥 Commits

Reviewing files that changed from the base of the PR and between cd873be and 29cf2a3.

📒 Files selected for processing (4)

• docs/doctoring/durable-lifecycle-field-contract.md
• pg_llm_batch/db.py
• tests/test_durable_lifecycle_field_contract.py
• tests/test_remote_batch_state_contracts.py

---

📝 Walkthrough

Walkthrough

원격 provider lifecycle의 batch_status와 batch_endpoint 허용값 계약을 추가했다. 저장 전에 값을 검증하고 정규화한다. 빈 값은 기존 기본값을 유지한다. 지원되지 않는 값은 데이터베이스 접근 전에 ValueError로 거부한다. 회귀 테스트와 운영 문서를 추가했다.

Changes

Provider lifecycle contract

Layer / File(s)	Summary
검증 계약과 정규화 pg_llm_batch/db.py, docs/doctoring/durable-lifecycle-field-contract.md	지원되는 상태와 endpoint 집합을 추가했다. 빈 값은 unknown 또는 None으로 정규화한다. 지원되지 않는 값은 ValueError로 거부한다. terminal 상태와 복구 절차를 문서화했다.
스냅샷 영속화 연결 pg_llm_batch/db.py	원격 배치 스냅샷이 검증된 batch_status와 batch_endpoint 값을 저장하도록 변경했다.
계약 회귀 테스트 tests/test_durable_lifecycle_field_contract.py, tests/test_remote_batch_state_contracts.py	지원되지 않는 값이 PostgreSQL 접근 전에 거부되는지 검증한다. 오류 메시지의 입력값 비노출과 기존 기본값, 공식 OpenAI 값, terminal 시각 처리를 검증한다. NUL 입력 테스트를 새 계약에 맞게 변경했다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• [Data Integrity] Validate durable provider lifecycle status and endpoint fields #127 — batch_status와 batch_endpoint의 내구성 검증을 직접 구현하고 테스트와 문서로 보강한다.

Possibly related PRs

• ContextualWisdomLab/pg-llm-batch#50 — 기존 durable lifecycle 영속화에 상태와 endpoint 검증을 추가한다.
• ContextualWisdomLab/pg-llm-batch#93 — provider lifecycle 영속화 및 관측 계약과 직접 연결된다.
• ContextualWisdomLab/pg-llm-batch#141 — 동일한 원격 batch lifecycle 영속화 경로를 수정하며, 이번 변경은 해당 경로에 값 검증을 추가한다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/durable-lifecycle-field-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}