[verified] Clarify Issue body provider-derived revision readback contract

2026-10-12 22:10:55 +00:00
parent c1f0034300
commit 33b0e44421
4 changed files with 31 additions and 0 deletions
@@ -40,6 +40,15 @@
 - 성공 response만으로 완료를 주장하지 않는다. Exact target을 fresh readback하고 author stable account ID, payload, timestamp, commit/ref와 collection cardinality를 baseline과 비교한다.
 - Timeout, malformed response 또는 connection loss 뒤에는 같은 mutation을 재호출하기 전에 complete collection을 한 번 읽어 결과를 reconciliation한다. 결과가 없거나 여러 개이거나 경쟁 mutation과 구분할 수 없으면 uncertain/partial로 중단한다.

+### Issue body update의 provider-derived readback
+
+- 이 계약은 승인된 Issue body update에만 적용한다. 현재 origin의 실제 server version·endpoint/update 경로와 독립적으로 확인한 matching provider contract를 기존 snapshot/근거에 연결한다. 보관 소스나 snapshot 자체의 version 주장만으로 현재 서버 계약을 확정하지 않는다. Revision 필드의 API 노출 여부도 확인하며, 내부 모델 필드가 transport에 항상 노출된다고 추정하지 않는다.
+- Write 직전 fresh snapshot은 target identity와 body, `updated_at`, comment baseline 및 보호 필드(title·state·labels·assignees·milestone 등)를 승인 baseline과 비교한다. 노출된 revision도 비교하여 pre-write drift를 차단한다. Provider 파생 변경 허용은 write 이후에만 적용하며 drift gate나 기존 조건부 update를 완화하지 않는다.
+- Readback의 body는 실제 전송 artifact의 exact bytes와 같아야 한다. 보호 필드와 해당 workflow의 complete comment baseline 계약은 그대로 검증한다. `content_version`이 해당 authenticated transport의 baseline과 readback에 제공되고 matching contract가 이 단일 body update에서 정확히 1 증가를 보장하면, 두 값이 boolean이 아닌 비음수 정수인지 확인하고 after == before + 1을 검증한다. 같은 body의 no-op에는 증가를 요구하지 않는다.
+- Revision이 누락·malformed이거나 증가가 0 또는 2 이상이거나 계약이 미확인이면 one-step 검증 성공으로 추정하지 않는다. Provider가 필드를 노출하지 않는 확인된 계약이면 비노출·검증 한계를 기록하고 workflow의 나머지 필수 검증을 적용한다. 필수 revision 근거가 부족하거나 경쟁 mutation과 구분할 수 없으면 uncertain/partial로 중단한다. `updated_at` 등 다른 필드도 같은 operation의 확인된 인과·타입·변경 규칙으로 각각 대조하며 일괄 비교 제외하지 않는다. Timestamp만으로 경쟁 변경이 없다고 주장하지 않는다.
+- 정상 파생 증가와 무관한 mutation을 구분하여 fresh readback으로 reconciliation한다. Body가 일치해도 다른 필수 검증이 실패하면 completed가 아니다. Timeout·오류·불일치 뒤에는 자동 재write하지 않는다. 보존된 baseline·payload·현재 결과로 판정하고 불확실하면 uncertain/partial로 보고한다. 별도 승인된 재개에서도 fresh identity·lease·snapshot·drift gate를 다시 통과한다.
+- 이는 기존 adapter를 사용하는 main의 비교 절차이며 새 runtime checker·publisher·projection framework 또는 자동 retry를 추가하지 않는다. 문서 계약 테스트 통과는 실제 adapter 준수나 live 서버 동작을 검증한 것이 아니다.
+
 ## Credential 안전

 - Credential 값은 role profile의 secret store에만 저장하고 repository, harness 문서와 workflow artifact에는 저장하지 않는다.