llm-wiki/raw/branch-notes/feature-outbox-dispatch-mode-contract.md

---
title: branch / feature-outbox-dispatch-mode-contract
source_type: branch-note
status: raw
branch: feature-outbox-dispatch-mode-contract
parent_branch:
related_projects: [ca-skeleton]
governing_docs: [raw/project-notes/ca-skeleton-operational-contract]
tags: [branch, ca-skeleton, outbox, cdc, debezium, dispatch-mode]
created: 2026-07-28
target_merge:
status_label: in-progress
id: BR-CA-SKELETON-OPERATIONAL-CONTRACT-072
kind: project-work-item
project: ca-skeleton-operational-contract
work_item: WI-CA-SKELETON-OPERATIONAL-CONTRACT-072
inherits: [DEC-CA-SKELETON-OPERATIONAL-CONTRACT-OUTBOX-DISPATCH-001@1, DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1]
refines: []
overrides: []
depends_on: [WI-CA-SKELETON-OPERATIONAL-CONTRACT-063]
imports: []
delegates: []
accepts_delegations: []
contract_packet: 1
---

# branch: feature-outbox-dispatch-mode-contract

> Layer: `raw/branch-notes/` — 단일 브랜치의 **TODO·결정·진행 기록**. 머지/종료 후 verified 결과는 `/ingest`로 `wiki/projects/`에 추출. 원본은 raw에 영구 보관.
> `status_label`: `in-progress` | `review` | `merged` | `abandoned`
> **스캐폴딩 상태** — 결정(D-row)·구현 가이드는 비어 있다. `/branch-spec feature-outbox-dispatch-mode-contract` 로 채운다.

<!-- section-id: branch-parent -->
## 부모 (필수)

- **Parent project (canonical SSOT)**: [[raw/project-notes/ca-skeleton-operational-contract]]

> 분해 근거: `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` §4.2 — 능력 계약 (Tier C). 본 branch 는 project §8.0 `WI-CA-SKELETON-OPERATIONAL-CONTRACT-072` 의 실행 단위다.

형제 branch (같은 부모의 다른 자식 — 인접 영역):

- [[raw/branch-notes/feature-domain-event-outbox-contract]]
- [[raw/branch-notes/feature-background-job-async-contract]]
- [[raw/branch-notes/feature-kafka-producer-runtime-contract]]

<!-- section-id: branch-contract-packet -->
## 브랜치 계약 패킷

> project Work Item 에서 내려온 실행 계약의 snapshot. 여기에는 **pinned pointer + 1줄 요약 + branch 적용점**만 쓰고 상세를 복제하지 않는다.

- **생성 시 프로젝트 개정**: `1`
- **패킷 스키마**: `contract_packet: 1`
- **완료 조건**: event/delivery 분리·모드 배타·CDC 라우팅·파티션 정리 조건 test 가 통과한다

<!-- section-id: inherited-project-decisions -->
### 상속한 프로젝트 결정

| Decision Ref | Project Summary | Branch Application | Source |
|---|---|---|---|
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-OUTBOX-DISPATCH-001@1` | outbox는 불변 event 행과 polling 전용 delivery 행을 분리하고 dispatch 모드는 polling과 cdc가 배타이며 append는 업무 write와 같은 트랜잭션에 남는다 | `/branch-spec` 에서 적용 경계 작성 | [[raw/project-notes/ca-skeleton-operational-contract]] |
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1` | end-to-end 메시징 보증은 at-least-once 전달과 멱등 consumer·inbox로 표현하고 DB와 broker를 걸친 exactly-once를 주장하지 않는다 | `/branch-spec` 에서 적용 경계 작성 | [[raw/project-notes/ca-skeleton-operational-contract]] |

<!-- section-id: branch-local-decisions -->
### 브랜치 지역 결정

> `/branch-spec` 단계에서 작성한다. 근거 없이 추측해 채우지 않는다.

| Decision ID | Decision | Relation | Supporting Claims | Status |
|---|---|---|---|---|

<!-- section-id: declared-overrides -->
### 선언한 예외

| Override ID | Overrides | Reason | Approval | Status |
|---|---|---|---|---|

<!-- GENERATED: project-contract-imports:start -->
## 가져온 프로젝트 계약

| Ref | Owner | 요약 | Branch 적용 |
|---|---|---|---|
<!-- GENERATED: project-contract-imports:end -->

<!-- section-id: branch-goal -->
## 목표

- `WI-CA-SKELETON-OPERATIONAL-CONTRACT-072` 의 완료 조건을 구현한다: event/delivery 분리·모드 배타·CDC 라우팅·파티션 정리 조건 test 가 통과한다
- **주도권 이전 수신** — H6 (`feature-domain-event-outbox-contract` 의 행 상태 머신 D-row). 이전 절차는 `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` §5.2 6단계를 따른다. 기존 branch 의 D-row 는 `/branch-spec` 으로 본 branch 결정이 확정된 뒤 포인터로 치환한다.
- 이슈:
- PR:

<!-- section-id: branch-scope -->
## 범위

### 포함 범위

- `outbox_event`(불변 envelope) 와 `outbox_delivery`(polling 전용 상태) 분리
- `dispatch-mode: disabled | polling | cdc` 배타성과 전환 runbook
- append 는 업무 write 와 같은 트랜잭션 유지 (Redis·Kafka 이동 금지)
- polling — claim owner token, aggregate sequence 순서, broker ack 기한, 통합 재시도 예산, replay/requeue/skip 도구
- CDC — Debezium Outbox Event Router 매핑, connector predicate·offset·snapshot·WAL/slot 운영, lag 감시
- `outbox_event` 파티션 보존과 정리 가능 조건 (consumed 증명 + replay 보존 경과)

### 제외 범위

> 의도적으로 제외한 것. 면접 등에서 "이건 범위에 없었습니다"라고 답할 근거.

- Kafka producer 설정 — #063 소유
- scheduler 실행 기반 — `feature-background-job-async-contract` 소유
- 심층 명세 — 본 노트는 스캐폴딩. D-row 와 §구현 가이드는 `/branch-spec` 이 채운다.
- project decision registry 변경 — owner 는 project-note

## 근거 (필수, 최소 1개+)

> 외부 근거 미등록. `/branch-spec feature-outbox-dispatch-mode-contract` 단계에서 verbatim 인용과 함께 `raw/official-docs/` 로 수집한 뒤 여기서 링크한다.

| Source | 정당화하는 결정 |
|---|---|
| (미등록) | 1차 수집 대상: Debezium 공식 — Outbox Event Router · ca-tmpl platform 설계 §11.1·§11.2 |

**프로젝트 내부 설계 참조 (등급 `internal-design-doc` — 공식 문서 아님, best practice 로 격상 금지):**

- ca-tmpl `docs/superpowers/specs/2026-07-26-production-capability-platform-design.md`
- llm-wiki `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md`

## TODO

각 항목 옆에 증거 등급 표기: `actually-implemented` | `locally-verified` | `prod-verified` | `documented-only` | `planned` | `needs-confirmation`

- [ ] `/branch-spec feature-outbox-dispatch-mode-contract` 로 D-row·§구현 가이드 작성 — 등급: `planned`
- [ ] event/delivery 분리·모드 배타·CDC 라우팅·파티션 정리 조건 test 가 통과한다 — 등급: `planned`

## 진행 중 메모

아직 없음.

## 결정 사항

project 결정 외 branch-local 결정은 아직 없음. `/branch-spec` 단계에서 기록한다.

<!-- section-id: decision-evidence -->
## 결정-근거 매핑

> `/branch-spec` 단계에서 작성한다.

| Decision ID | Decision | 선택 조건 (언제 이 결정 / 언제 대안) | Supporting Claims | Evidence Strength | Open Risk |
|---|---|---|---|---|---|

<!-- section-id: implementation -->
## 구현 가이드

`/branch-spec` 단계에서 source claim 기반으로 작성한다. 3-rule meta principle(R1 Reference 필수 / R2 UNSUPPORTED_IMPL_DECISION 명시 / R3 OUT_OF_BRANCH_SCOPE 정제) 적용.

<!-- section-id: edge-failure-dependency -->
## 엣지·실패·의존

- **실패·엣지 경로**: `/branch-spec` 단계에서 구체화한다.
- **다른 계약 의존**: `WI-CA-SKELETON-OPERATIONAL-CONTRACT-063`([[raw/branch-notes/feature-kafka-producer-runtime-contract]]) 의 계약에 의존

<!-- section-id: claims-to-verify -->
## 검증해야 할 주장

| Claim | Why uncertain | How to verify | Status |
|---|---|---|---|
| 본 branch 가 소유할 관심사가 sibling branch 결정과 겹치지 않는다 | 스캐폴딩 시점에는 D-row 가 없어 경계가 문장으로만 존재 | `/branch-spec` 후 `/sync` 실행 — owner 중복 검출 | `needs-confirmation` |

## 관심사 커버리지 (coverage-auditor 자동 생성 — 있을 때)

`/coverage` 실행 전.

## 마주친 문제

아직 없음.

## 묶음 (이 branch에서 파생된 자료)

<!-- GENERATED: branches:start -->
<!-- GENERATED: branches:end -->

## 관련 일일 노트

해당 없음.

## 완료 후 정리

- PR 링크:
- 리뷰 메모:
- 머지 결과 / 배포 환경:
- **wiki 추출 대상** (verified만, `wiki/projects/`로만 추출):
- **추출하지 않을 항목** (planned / documented-only / abandoned):