feat(durable): define dead-letter authority record

[seonghobae]

Objective

Advance issue #312 with a path-disjoint durable dead-letter primitive. Terminal retry exhaustion needs bounded, privacy-safe evidence that binds one dead-letter outcome to the exact job generation and attempt without persisting arbitrary exception text as durable authority.

Test-first state

Protected main was directly resolved at 55d7ae8647208e301f282350f076eeddaba61d11. This Draft starts intentionally RED at exact test-only head 445f1afbab188f1c8ec0d175c084735063613c84. ConversionDeadLetterRecordTest requires exact dead-letter/job/generation/attempt authority, a controlled low-cardinality reason code, and fail-closed missing or impossible identities. The production type does not exist at this head, so Maven test compilation is expected to fail at that exact boundary.

Scope

New durable-domain dead-letter record plus focused tests only. This does not persist the record, alter the current conversion worker, expose raw exception text, implement retry scheduling, worker leases, cancellation, telemetry export, or HTTP admission behavior. It is deliberately path-disjoint from the active issue-#312 idempotency/admission/outbox/lease/retry/cancellation/attempt/audit/delivery-receipt/capacity and restart-recovery slices.

Acceptance

Observe exact-head RED -> smallest immutable production implementation -> exact-head mvn -B --no-transfer-progress verify with zero failures/errors/skips, exact owned-production coverage and strict public Javadocs -> CI/Security Scan/SAST/fuzz -> current reviews/threads/live-base refetch. Keep Draft until the unchanged exact implementation head is GREEN. Independent non-author approval remains a separate protected-merge gate.

Summary by CodeRabbit

• 새 기능

  • 변환 실패 작업의 식별자, 작업 정보, 시도 횟수, 실패 시각 및 사유를 안전하게 기록합니다.
  • 작업 ID, 세대 및 시도 횟수가 모두 일치하는지 확인할 수 있습니다.
  • 필수 정보와 사유 코드 형식, 숫자 범위를 자동으로 검증합니다.

• 테스트

  • 기록된 값 보존, 권한 일치 여부 및 입력값 검증 동작을 확인하는 테스트를 추가했습니다.

[coderabbitai]

Warning

Review limit reached

@seonghobae, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ea44f048-4707-48ae-9dc6-9d45df5b2034

📥 Commits

Reviewing files that changed from the base of the PR and between fcbce0c and d2edf5c.

📒 Files selected for processing (2)

• src/main/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecord.java
• src/test/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecordTest.java

📝 Walkthrough

Walkthrough

변환 실패 정보를 보존하는 불변 ConversionDeadLetterRecord를 추가했습니다. 생성 시 필수 값, generation, attempt, reason code를 검증합니다. 작업 ID, generation, attempt가 모두 일치하는 경우에만 권한을 승인합니다. 관련 동작을 JUnit 테스트로 검증합니다.

Changes

변환 dead-letter 레코드

Layer / File(s)	Summary
레코드 계약 및 생성 검증 src/main/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecord.java, src/test/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecordTest.java	dead-letter 식별자, 작업 ID, generation, attempt, 실패 시각 및 reason code를 불변 상태로 저장합니다. 필수 값과 양수 조건을 검증합니다. reason code의 형식과 길이를 제한합니다. 접근자와 생성 검증 테스트를 추가합니다.
작업 권한 일치 검사 src/main/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecord.java, src/test/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecordTest.java	authorizes가 작업 ID, generation, attempt의 완전한 일치 여부를 반환합니다. 일치 및 불일치 입력을 테스트합니다.

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

Possibly related PRs

• ContextualWisdomLab/clearfolio#369: generation과 attempt 검증 및 권한 확인을 포함하는 다른 불변 변환 lifecycle 레코드를 추가합니다.
• ContextualWisdomLab/clearfolio#371: generation과 attempt 기반의 불변 변환 레코드 및 일치 검사를 추가합니다.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 durable dead-letter authority record 추가라는 PR의 주요 변경을 정확하고 간결하게 설명합니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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 feat/conversion-dead-letter-record-main-20260812

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecord.java`:
- Around line 72-74: Restrict reasonCode validation in
ConversionDeadLetterRecord to a fixed enum or registered allowlist instead of
accepting any value matching the regex, while preserving the existing format
checks. Add a test in ConversionDeadLetterRecordTest covering a format-valid but
unregistered code such as TENANT_12345 and assert that it is rejected.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 660b1a9b-1082-4921-b96c-6ca3467ad9fa

📥 Commits

Reviewing files that changed from the base of the PR and between 55d7ae8 and fcbce0c.

📒 Files selected for processing (2)

• src/main/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecord.java
• src/test/java/com/clearfolio/viewer/durable/ConversionDeadLetterRecordTest.java