fix(ledger): dcy-015 outbox 영속 오류 분류 + 백오프/dead-letter (BAT-019)

portfolio-hub 404(미등록 포트폴리오)가 retryable 로 분류되어 백오프·상한 없이
초당 영구 재시도되던 버그(issue #13, 실측 930회) 정정.

거버넌스: 전부 change-req (신규 REQ 없음, dcy-015 OQ-3; 백오프 env 는 REQ-019 흡수).
- REQ-017: 404/400/422 → LedgerPermanentError 분류 (409 conflict / 408·429·5xx·
  network retryable 불변). LedgerPort 에 permanent 타입 추가
- REQ-019: 영속 → 터미널 delivery_failed 즉시(재시도 0). retryable 지수 백오프
  +jitter+next_retry_at, max_attempts 초과 시 dead-letter delivery_failed.
  list_pending 이 백오프 행 스킵(head-of-line 보호). 마이그레이션 007(status enum
  +next_retry_at). 백오프 env(base/cap/max-attempts)
- REQ-018: 터미널/dead-letter WARN + WriterStats.delivery_failed 카운터 가시화
- REQ-020: runtime-flows/data-model/interface-contract 정합

단일 터미널 delivery_failed(permanent/dead-letter, last_outcome 로 사유 구분) —
conflict_blocked 패턴과 동형. dead-letter 는 운영자 재처리 가능 상태.

검증: 단위 311 passed/34 skipped, 인프라 게이트(PG+RabbitMQ) 345 passed, ruff clean.
신규 test_ledger_outbox_backoff + adapter/PG 테스트, 기존 retryable 백오프 정합.
BAT-019 release-candidate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/srs/Integration/req-017_ledger-port-and-portfolio-hub-adapter.md

@@ -189,3 +189,42 @@
 - AC-2: tests/adapters/ledger/test_portfolio_hub_ledger.py::test_post_contract_includes_execution_id_and_path_uses_portfolio_id (path `/v1/portfolios/PF-77/ledger/trades` + body `quantity`/`fee_amount`/`tax_amount` 단언, `qty`/`fee`/`tax` 부재 단언).
 - AC-1/AC-3/AC-4: 기존 테스트 회귀(16 passed) 유지.
 - 실 e2e: 매수 intent → 체결 → ledger POST 201 + outbox completed.
+
+### CHG-20260608-01
+
+- Date: 2026-06-08
+- Author: Justin Ko
+
+#### Change Summary
+
+- (change-req, dcy-015/issue #13) portfolio-hub 어댑터 오류 분류 분리: **404/400/422 → `LedgerPermanentError`**(신규, 재시도로 해소 불가), 409→conflict(불변), 408/429/5xx/network→retryable(불변). LedgerPort 에 `LedgerPermanentError` 타입 추가 + 어댑터 계약 헤더 갱신. BAT-019 재구현·재검증 완료 → Implemented 유지.
+
+#### Intent
+
+- 미등록 포트폴리오 404 가 retryable 로 오분류되어 영구 재시도되던 근본 원인 제거 — 영속(클라이언트) 오류를 명시 타입으로 분리해 outbox 가 터미널 처리하게 한다.
+
+#### Acceptance Criteria Delta
+
+- Added:
+  - 어댑터가 404/400/422 를 `LedgerPermanentError` 로 매핑. LedgerPort 에 permanent 오류 타입.
+
+#### Impacted Area Delta
+
+- Modules: `trex_core/application/ledger_port.py`(LedgerPermanentError), `trex_core/adapters/ledger/portfolio_hub.py`(분류), `trex_core/adapters/ledger/in_memory.py`(permanent_executions 주입)
+- Tests: tests/adapters/ledger/test_portfolio_hub_ledger.py(404/400/422 permanent, 429 retryable)
+
+#### Delivery Trace Delta
+
+- Batches: BAT-019
+- Releases: none
+
+#### Revalidation Impact
+
+- Reverification Needed: yes (BAT-019 에서 완료)
+- Existing Implementation Invalidated: yes (404 등을 retryable 로 분류하던 경로)
+- Status Recommendation: Implemented (change-req → BAT-019 재검증)
+- Follow-up Action: confirm-req-implemented(BAT-019).
+
+#### Validation Plan
+
+- BAT-019: 404/400/422→LedgerPermanentError, 429/5xx→retryable, 409→conflict 단위.

docs/srs/Integration/req-018_fill-to-ledger-recording.md

@@ -228,3 +228,42 @@
 #### Validation Plan
 
 - BAT-017: 부분 취소 시 sell 원장 1건(qty=체결분, price=체결가) 단위.
+
+### CHG-20260608-03
+
+- Date: 2026-06-08
+- Author: Justin Ko
+
+#### Change Summary
+
+- (change-req, dcy-015/issue #13) ledger 터미널 실패 가시화 확장: `delivery_failed`(permanent/dead-letter)를 `WriterStats.delivery_failed` 카운터 + WARN 로그 + 구분 status 로 노출(dcy-011 `ledger_skipped` 가시화 패턴 정합). dead-letter 는 운영자 재처리 가능 상태이며 `find_ledger_gap_slots`(REQ-055)·skip 가시화와 연계. BAT-019 재구현·재검증 완료 → Implemented 유지.
+
+#### Intent
+
+- ledger 가 끝내 기록되지 않는 실패(404 영속·dead-letter)가 무성 pending 으로 남지 않고 운영자에게 노출되도록(NFR-2 가시성).
+
+#### Acceptance Criteria Delta
+
+- Updated:
+  - 원장 미기록(터미널 delivery_failed) 시 WARN 로그 + 카운터 + 구분 status 가시화.
+
+#### Impacted Area Delta
+
+- Modules: `trex_core/application/ledger_outbox.py`(WARN + WriterStats.delivery_failed)
+- Tests: tests/application/test_ledger_outbox_backoff.py::test_permanent_failure_emits_warning
+
+#### Delivery Trace Delta
+
+- Batches: BAT-019
+- Releases: none
+
+#### Revalidation Impact
+
+- Reverification Needed: yes (BAT-019 에서 완료)
+- Existing Implementation Invalidated: no (관측만 추가)
+- Status Recommendation: Implemented (change-req → BAT-019 재검증)
+- Follow-up Action: confirm-req-implemented(BAT-019).
+
+#### Validation Plan
+
+- BAT-019: delivery_failed WARN 로그(caplog) + 카운터 단위.