feat: 공식 문서 근거자료, 브랜치 기능 문서 작성
This commit is contained in:
DongHyeonka
@@ -429,8 +429,8 @@ Out of scope:
|
||||
| `FE-D024` | dependency lock, secret scan, vulnerability scan, license inventory, dependency review를 merge/release gate로 분리 (lock 은 `FE-GATE-001`, 나머지 4개는 `FE-GATE-013`) | `accepted-documented-only` | `feature-frontend-build-bundle-supply-chain-contract` | `FE-OC-018`, `FE-OC-019`, `FE-OC-020` | supply-chain scope 최소값 | organization security policy가 더 강한 gate 지정 | — |
|
||||
| `FE-D025` | sample slice는 제거 가능한 contract fixture이며 product import를 금지 | `accepted-documented-only` | `feature-sample-feature-slice-contract-fixture` | `FE-OC-024` | backend skeleton의 sample-fixture 운영 원칙을 frontend에 적용 | fixture 없이 동일 gate coverage를 증명 | — |
|
||||
| `FE-D026` | 신규 runtime capability 6종은 `FE-REG-CAPABILITY` flag로 default OFF이며 활성화는 owner·gate·runbook을 동반한다 | `conditional-default` | `feature-frontend-env-runtime-config-contract` | `FE-OC-004`, `FE-OC-022`, `FE-OC-027`, `FE-OC-028`, `FE-OC-029`, `FE-OC-030`, `FE-OC-031`, `FE-OC-032` | project-local default, 외부 source claim 아님 | 특정 capability가 제품 필수가 되어 상시 활성이 요구됨 | — |
|
||||
| `FE-D027` | 로컬 바이너리 backend는 IndexedDB를 default로 하고 OPFS는 대용량 순차 write에 opt-in, Cache Storage는 service worker 호스팅 response cache 전용이다 | `conditional-default` | `feature-frontend-binary-file-io-store-contract` | `FE-OC-013`, `FE-OC-027` | project-local default, 외부 source claim 아님 | OPFS 브라우저 지원 또는 quota 정책이 바뀜 | — |
|
||||
| `FE-D028` | 탭 간 무효화는 BroadcastChannel 우선에 `storage` event fallback을 쓰고 leader election 없이 무효화 key만 전파한다 | `conditional-default` | `feature-frontend-cache-tier-cross-tab-invalidation-contract` | `FE-OC-012`, `FE-OC-028` | project-local default, 외부 source claim 아님; 값 전파는 PII·stale 표면을 넓힘 | 다중 탭 실시간 협업이 제품 요구가 됨 | — |
|
||||
| `FE-D027` | 로컬 바이너리 backend는 IndexedDB를 default로 하고 OPFS는 대용량 순차 write에 opt-in, Cache Storage는 정책상 service worker 호스팅 response cache 전용으로 제한한다 | `conditional-default` | `feature-frontend-binary-file-io-store-contract` | `FE-OC-013`, `FE-OC-027` | backend 선택은 project-local default. Cache Storage 제한은 플랫폼 제약이 아니라 release 단위 파티션 일관성을 위한 정책이다 — [[raw/official-docs/mdn-object-url-cache-storage]] `#C3` | OPFS 브라우저 지원 또는 quota 정책이 바뀜 | — |
|
||||
| `FE-D028` | 탭 간 무효화는 BroadcastChannel만 쓰고 별도 fallback 경로를 두지 않으며 leader election 없이 무효화 key만 전파한다. 채널을 쓸 수 없으면 탭 내 무효화만 수행한다 | `conditional-default` | `feature-frontend-cache-tier-cross-tab-invalidation-contract` | `FE-OC-012`, `FE-OC-028` | BroadcastChannel은 2022년 3월부터 모든 주요 브라우저에서 동작한다 — [[raw/official-docs/mdn-broadcastchannel-storage-event]] `#C4`. 값 전파 금지는 PII·stale 표면을 넓히지 않기 위한 project decision | 지원 대상에 BroadcastChannel 미동작 브라우저가 실제로 포함되거나, 다중 탭 실시간 협업이 제품 요구가 됨 | — |
|
||||
| `FE-D029` | presigned URL 획득은 shared client를 경유하고 실제 byte 전송은 session credential을 첨부하지 않는 transfer adapter가 수행한다 | `accepted-documented-only` | `feature-frontend-large-object-transfer-contract` | `FE-OC-006`, `FE-OC-019`, `FE-OC-029` | credential 유출 방지 invariant, project decision | 스토리지가 same-origin proxy만 제공 | — |
|
||||
| `FE-D030` | 재개 가능 전송은 part size·병렬도·part 재시도 상한을 registry로 고정하고 part 상태를 `BlobStorePort`에 보존한다 | `conditional-default` | `feature-frontend-large-object-transfer-contract` | `FE-OC-029` | project-local default, 외부 source claim 아님 | 스토리지 제공자가 다른 multipart 제약을 요구 | — |
|
||||
| `FE-D031` | transport default는 REST이고 GraphQL·gRPC-Web·Connect-Web은 `FE-REG-API`의 protocol 필드로 opt-in하며 미지원 환경은 REST gateway로 fallback한다 | `conditional-default` | `feature-frontend-multi-protocol-api-transport-contract` | `FE-OC-006`, `FE-OC-007`, `FE-OC-030` | project-local default, 외부 source claim 아님 | backend가 단일 비-REST protocol만 제공 | — |
|
||||
@@ -440,7 +440,7 @@ Out of scope:
|
||||
| `FE-D035` | background sync 재생은 `idempotency: keyed` operation만 허용한다 (`FE-D016` 상속) | `accepted-documented-only` | `feature-frontend-background-execution-worker-contract` | `FE-OC-009`, `FE-OC-032` | mutation 자동 retry 결정의 중복 write 방지 invariant를 지연 재생에 확장 | mutation이 naturally idempotent임이 schema로 증명됨 | — |
|
||||
| `FE-D036` | Web Worker 작업은 structured-clone 또는 Transferable로만 통신하고 timeout과 terminate를 계약하며 worker 안에서 application port를 재구현하지 않는다 | `accepted-documented-only` | `feature-frontend-background-execution-worker-contract` | `FE-OC-002`, `FE-OC-032` | worker 안 로직 중복이 layer 경계를 우회하는 것을 차단, project decision | SharedArrayBuffer 기반 병렬 처리가 요구됨 | — |
|
||||
|
||||
`FE-D026`~`FE-D036`의 `Evidence / rationale`에 적힌 `project-local default, 외부 source claim 아님`은 `FE-D001`이 쓰는 표기와 같다. 대응 raw 근거 문서가 아직 없다는 사실을 감추지 않고 명시하는 장치이며, 수집 계획은 `FE-Q-011`이 소유한다.
|
||||
`FE-D026`~`FE-D036` 중 아직 raw 근거가 없는 행의 `Evidence / rationale`에 적힌 `project-local default, 외부 source claim 아님`은 `FE-D001`이 쓰는 표기와 같다. 대응 raw 근거 문서가 아직 없다는 사실을 감추지 않고 명시하는 장치이며, 수집 계획은 `FE-Q-011`이 소유한다. `FE-D027`은 2026-07-28 조사로 근거 일부를 확보해 이 표기에서 빠졌다 — 경위는 §6.1 개정 기록.
|
||||
|
||||
### 3.3 Decision change protocol
|
||||
|
||||
@@ -486,8 +486,8 @@ Out of scope:
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SUPPLY-CHAIN-001` | 1 | `supply-chain` | dependency lock, secret scan, vulnerability scan, license inventory, dependency review를 merge/release gate로 분리한다 | `accepted-documented-only` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D024` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SAMPLE-FIXTURE-001` | 1 | `sample-fixture` | sample slice는 제거 가능한 contract fixture이며 product import를 금지한다 | `accepted-documented-only` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D025` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001` | 1 | `capability` | 신규 runtime capability 6종은 FE-REG-CAPABILITY flag로 default OFF이며 활성화는 owner·gate·runbook을 동반한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D026` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-BINARY-STORE-001` | 1 | `binary-store` | 로컬 바이너리 backend는 IndexedDB를 default로 하고 OPFS는 대용량 순차 write에 opt-in, Cache Storage는 service worker 호스팅 response cache 전용이다 | `conditional-default` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D027` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CROSS-TAB-001` | 1 | `cross-tab` | 탭 간 무효화는 BroadcastChannel 우선에 storage event fallback을 쓰고 leader election 없이 무효화 key만 전파한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D028` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-BINARY-STORE-001` | 1 | `binary-store` | 로컬 바이너리 backend는 IndexedDB를 default로 하고 OPFS는 대용량 순차 write에 opt-in, Cache Storage는 정책상 service worker 호스팅 response cache 전용으로 제한한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D027`; [[raw/official-docs/mdn-object-url-cache-storage]] `#C3` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CROSS-TAB-001` | 2 | `cross-tab` | 탭 간 무효화는 BroadcastChannel만 쓰고 별도 fallback 경로를 두지 않으며 leader election 없이 무효화 key만 전파한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D028`; [[raw/official-docs/mdn-broadcastchannel-storage-event]] `#C4` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-TRANSFER-CREDENTIAL-001` | 1 | `transfer-credential` | presigned URL 획득은 shared client를 경유하고 실제 byte 전송은 session credential을 첨부하지 않는 transfer adapter가 수행한다 | `accepted-documented-only` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D029` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-RESUMABLE-TRANSFER-001` | 1 | `resumable-transfer` | 재개 가능 전송은 part size·병렬도·part 재시도 상한을 registry로 고정하고 part 상태를 BlobStorePort에 보존한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D030` |
|
||||
| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-PROTOCOL-001` | 1 | `protocol` | transport default는 REST이고 GraphQL·gRPC-Web·Connect-Web은 FE-REG-API의 protocol 필드로 opt-in하며 미지원 환경은 REST gateway로 fallback한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | §3.2 `FE-D031` |
|
||||
@@ -502,6 +502,9 @@ Out of scope:
|
||||
> - 2026-07-21 · `DEC-...-SUPPLY-CHAIN-001` · `compatibility_impact: additive` · revision 유지(1). Decision Summary 에 `dependency review` 를 추가했다. 이는 새 결정이 아니라 **불완전한 요약의 정정**이다 — `FE-OC-018` 과 §13.1 이 처음부터 dependency review 를 요구했고 §3.2 `FE-D024` 도 이를 포함하는데 이 registry 행만 4개 control 로 적혀 있었다. 기존 4개 control 의 동작은 바뀌지 않고, gate 정의(§15.1 `FE-GATE-013`)도 이미 dependency-review fixture 를 포함한 채 revision 1 이므로 같은 판정을 적용한다.
|
||||
> - 2026-07-28 · `DEC-...-OFFLINE-CACHE-001` · `compatibility_impact: behavior-change` · revision 1→2. `FE-D034` 가 `FE-D019` 를 supersede 하면서 service worker 를 "전면 off" 에서 "precaching off + 역할별 capability opt-in" 으로 바꿨다. WebPush·Background Sync·Cache Storage 가 service worker 없이는 동작하지 않기 때문이다. behavior-change 이므로 §3.3 4단계에 따라 `FE-GATE-032`(SW update UX + rollback 시 SW 되돌림)와 `FE-RB-007` 이 migration·rollback evidence 를 담당한다. 이 결정을 pin 한 [[raw/branch-notes/feature-frontend-release-cache-rollback-contract]] 는 `@2` 로 갱신했다.
|
||||
> - 2026-07-28 · `DEC-...-REGISTRY-001` · `compatibility_impact: additive` · revision 유지(1). 9번째 registry `FE-REG-CAPABILITY` 를 추가했다. 기존 8개 registry 의 owner·schema·동작은 바뀌지 않으므로 `DEC-...-SUPPLY-CHAIN-001` 선례와 같은 판정을 적용한다. 다만 Summary 문자열이 바뀌므로 이를 복사해 둔 소비 branch 4곳([[raw/branch-notes/feature-frontend-storage-registry-contract]]·[[raw/branch-notes/feature-frontend-observability-logging-trace-contract]]·[[raw/branch-notes/feature-frontend-contract-registry-governance]]·[[raw/branch-notes/feature-frontend-contract-compatibility-governance]])의 상속 표를 함께 갱신했다.
|
||||
> - 2026-07-28 · `DEC-...-CROSS-TAB-001` · `compatibility_impact: behavior-change` · revision 1→2. `storage` event fallback 경로를 **삭제**했다. 삭제 근거는 두 가지다. (1) [[raw/official-docs/mdn-broadcastchannel-storage-event]] `#C4` 가 BroadcastChannel 을 2022년 3월부터 Baseline Widely available 로 기록하는데, fallback 이 필요한 브라우저가 지원 대상에 실제로 있다는 근거는 조사에서 나오지 않았다. (2) `#C10` 대로 `sessionStorage` 의 `storage` event 는 다른 탭에 도달하지 않아 원래 서술("`storage` event fallback")이 동작하지 않는 구현을 허용하고 있었다. 쓰이지 않는 경로를 남기면 저장 공간 예산·자기 수신 제외·연속 동일값 문제를 위한 장치를 계속 유지해야 하고, 평소 실행되지 않아 테스트로도 검증되지 않는다. 필요해지는 시점(지원 대상에 미동작 브라우저가 들어올 때)에 다시 넣는다. behavior-change 이므로 `FE-GATE-028` 의 fixture 목록에서 fallback 항목을 제거하고 `CROSS_TAB_CHANNEL_UNAVAILABLE` 의 진입 조건을 좁혔다. 이 결정을 pin 한 [[raw/branch-notes/feature-frontend-cache-tier-cross-tab-invalidation-contract]] 는 `@2` 로 갱신했다.
|
||||
> - 2026-07-28 · `DEC-...-BINARY-STORE-001` · `compatibility_impact: none` · revision 유지(1). Summary 의 "Cache Storage는 service worker 호스팅 response cache 전용이다" 를 "정책상 ... 전용으로 제한한다" 로 바꿨다. 이는 새 결정도 완화도 아니라 **틀린 근거의 정정**이다 — 원문은 플랫폼 제약을 서술하는 것처럼 읽혔으나 [[raw/official-docs/mdn-object-url-cache-storage]] `#C3` 이 "you're not limited to only using it with service workers" 이고 `Window.caches` 로 window scope 에서도 접근 가능하다고 적는다. 제한 자체는 유지되므로 어떤 adapter 의 허용 동작도 바뀌지 않고, 바뀐 것은 그 제한이 **우리가 고른 것**임을 드러낸 점이다. Summary 문자열이 바뀌므로 이를 pin 한 [[raw/branch-notes/feature-frontend-binary-file-io-store-contract]] 의 상속 표를 함께 갱신했다. 발견 경위는 같은 노트 §Audit & Findings `CACHE_STORAGE_CONSTRAINT_DRIFT`.
|
||||
> - 2026-07-28 · §5.5 `FE-REG-STORAGE.evictionOrder` 필드 Rule · `compatibility_impact: none` · 대응 registry 결정 `DEC-...-REGISTRY-001` revision 유지(1). 필드 설명에 **주체**(애플리케이션 주도)와 **비적용 범위**(브라우저 eviction)를 명시했다. 어떤 행의 `evictionOrder` 값도 바뀌지 않았고 §8.2 `BLOB_STORE_QUOTA_EXCEEDED` 복구 경로도 그대로다. 정정 근거는 [[raw/official-docs/mdn-storage-quotas-eviction-persistence]] `#C1`(origin 전량 삭제)·`#C3`(LRU 는 origin 단위)이며, 원문은 브라우저가 이 순서를 존중한다는 오독을 허용했다. Decision Summary 를 건드리지 않으므로 소비 branch 상속 표 전파는 불필요하다. 발견 경위는 [[raw/branch-notes/feature-frontend-binary-file-io-store-contract]] §Audit & Findings `EVICTION_SCOPE_DRIFT`.
|
||||
> - 2026-07-28 · `DEC-...-CAPABILITY-001` 외 10건 신규 등록. 근거 raw 문서가 아직 없으므로 §3.2 대응 행의 `Evidence / rationale` 에 `project-local default, 외부 source claim 아님` 을 명시했고, 수집 계획은 `FE-Q-011` 이 소유한다.
|
||||
> - Summary 셀은 소비 branch 의 상속 표와 **문자열이 정확히 일치해야 한다**(`wiki_consistency_check.py` 의 `CONFLICTS_WITH_PROJECT_DECISION`). 분류·근거 같은 메타는 이 기록에 적고 Summary 에 섞지 않는다. 조사 앞에 공백을 넣지 않는다 — `…release token을 8개 registry로` 형태가 기준이다.
|
||||
|
||||
@@ -533,7 +536,7 @@ Out of scope:
|
||||
| `adapters/file` | 파일 선택·저장 dialog, object URL 생성/해제 | application port, File System Access / input element | 파일 내용 해석, 도메인 검증 | `planned` |
|
||||
| `adapters/blob-store` | IndexedDB·OPFS·Cache Storage 백엔드, quota 매핑, eviction | application port, browser storage API | 저장 대상의 의미, 도메인 정책 | `planned` |
|
||||
| `adapters/cache-persistence` | 캐시 직렬화, version partition, 복원 거부 | application port, 자체 영속 백엔드 | 캐시 정책 결정(`QueryCachePort` 소유) | `planned` |
|
||||
| `adapters/cross-tab` | BroadcastChannel·`storage` event 전송, 메시지 봉투 | application port, browser globals | 무효화 대상 결정 | `planned` |
|
||||
| `adapters/cross-tab` | BroadcastChannel 전송, 메시지 봉투 | application port, browser globals | 무효화 대상 결정 | `planned` |
|
||||
| `adapters/transfer` | part 분할·병렬·재시도·무결성·진행 보고, credential-less 전송 | application port, fetch, Streams | presign 발급, 업로드 대상 도메인 규칙 | `planned` |
|
||||
| `adapters/protocol` | GraphQL·gRPC-Web·Connect-Web codec 과 status 정규화 | application output port, fetch | operation 정의, use-case policy | `planned` |
|
||||
| `adapters/realtime` | 연결 수명주기, 재연결 backoff, resume cursor, 프레임 디코드, 구독 해제 | application port, EventSource·WebSocket·fetch | 이벤트의 도메인 의미, 상태 병합 정책 | `planned` |
|
||||
@@ -842,7 +845,7 @@ capability flag 6개의 기본값이 전부 `false`인 것은 `FE-D026`의 defau
|
||||
| `migration` | conditional | previous version을 읽으면 migration 또는 discard |
|
||||
| `quotaFallback` | yes | memory/no-persist/feature-disable 중 하나. correctness에 영향을 주는 값은 `없음`으로 선언 |
|
||||
| `payloadClass` | yes | `structured`(기본) 또는 `binary`. `binary`는 `sensitive-forbidden` classification과 조합할 수 없음 |
|
||||
| `evictionOrder` | yes | quota 압박 시 제거 순서(정수, 낮을수록 먼저). 제거 불가 값은 `null` |
|
||||
| `evictionOrder` | yes | **애플리케이션 주도** 정리 순서(정수, 낮을수록 먼저). 제거 불가 값은 `null`. 브라우저 eviction 에는 적용되지 않는다 |
|
||||
|
||||
Initial planned rows:
|
||||
|
||||
@@ -859,6 +862,8 @@ Initial planned rows:
|
||||
|
||||
`UPLOAD_PART_STATE`의 `quotaFallback`이 `없음`이고 `evictionOrder`가 `null`인 것은 §9.4의 "correctness에 영향을 주는 값은 storage fallback을 임의 적용하지 않는다"를 이 행에 적용한 것이다. part 상태가 조용히 memory로 넘어가면 새로고침 한 번에 이어받기가 불가능해지고, 사용자는 그 사실을 전송이 실패한 뒤에야 알게 된다.
|
||||
|
||||
`evictionOrder`가 지배하는 범위는 **애플리케이션이 quota 압박을 감지하고 스스로 정리할 때의 순서**뿐이다. 브라우저가 주도하는 eviction은 이 순서를 보지 않는다 — [[raw/official-docs/mdn-storage-quotas-eviction-persistence]] `#C1`은 "When an origin's data is evicted by the browser, all of its data, not parts of it, is deleted at the same time"라고 적고 `#C3`은 LRU가 origin 단위로 동작한다고 적는다. 즉 이 필드는 §8.2의 `BLOB_STORE_QUOTA_EXCEEDED` 복구 경로에 주는 입력일 뿐이고, `evictionOrder`가 높다고 해서 어떤 행도 브라우저 eviction 에서 보호받지 못한다. 브라우저 eviction 에 대한 유일한 방어는 `navigator.storage.persist()` 허가이며(`#C4`), 그 허가는 브라우저 재량이라 요청이 성공한다고 가정할 수 없다(`#C5`). Safari는 cross-site tracking prevention이 켜져 있으면 7일간 사용자 상호작용이 없는 origin의 script 생성 데이터를 삭제한다(`#C7`).
|
||||
|
||||
### 5.6 Error registry minimum schema
|
||||
|
||||
| Field | Required | Rule |
|
||||
@@ -1394,7 +1399,7 @@ Raw response body, token, authorization header, full URL/query, stack, storage v
|
||||
| IndexedDB/OPFS/Cache Storage 접근 불가 또는 security error | `BLOB_STORE_UNAVAILABLE` | no | registry `quotaFallback`; `없음`이면 terminal | 기능 저하 고지, 무음 처리 금지 | backend type + reason enum |
|
||||
| 로컬 바이너리 quota 초과 | `BLOB_STORE_QUOTA_EXCEEDED` | no | `evictionOrder` 순 제거 후 재시도, `null` 행은 제거 금지 | 저장 실패 고지 + 정리 action | quota bucket, 값 금지 |
|
||||
| 캐시 직렬화·영속·복원 실패 | `CACHE_PERSISTENCE_FAILURE` | no | 메모리 캐시만 사용 | 무음, 필요 시 stale 표시 | phase + tier only |
|
||||
| BroadcastChannel과 `storage` event가 모두 불가 | `CROSS_TAB_CHANNEL_UNAVAILABLE` | no | 탭 내 무효화만 수행 | 무음, 다중 탭 stale 가능성 고지 가능 | reason enum only |
|
||||
| BroadcastChannel 사용 불가 | `CROSS_TAB_CHANNEL_UNAVAILABLE` | no | 탭 내 무효화만 수행 | 무음, 다중 탭 stale 가능성 고지 가능 | reason enum only |
|
||||
| presigned URL 만료/거부 | `PRESIGN_EXPIRED` | presign 재획득 후 1회 | 재획득 성공 시 같은 위치에서 재개 | 자동 재개, 재획득도 실패하면 retry action | operation ID only, URL 금지 |
|
||||
| upload part 재시도 상한 소진 | `UPLOAD_PART_FAILED` | no (part 내부 재시도는 최대 2회) | part 상태 보존 후 일시정지 | 재개 action, 진행률 유지 | part index bucket + attempts |
|
||||
| 체크섬 또는 크기 불일치 | `TRANSFER_INTEGRITY_MISMATCH` | no | 해당 part 폐기 후 재전송 1회, 재실패면 terminal | 무결성 실패 고지 + 처음부터 다시 action | size bucket only |
|
||||
@@ -1897,7 +1902,7 @@ Script 이름을 바꾸는 것은 허용되지만 acceptance gate와 artifact ma
|
||||
| `FE-GATE-025` | `FE-RB-005` drill | production promotion | `FE-OC-025` | — | blocking release defect | rollback decision, escalation, recovery assertions pass | `FE-RB-005` record | `FAIL_UNVERIFIED` |
|
||||
| `FE-GATE-026` | lab performance | release | `FE-OC-021` | `FE-NFR-003`, `FE-NFR-004`, `FE-NFR-005` | recorded runner/throttling/cache context + named interactions | every lab threshold passes and report contains reproducibility metadata | lab performance report | `FAIL_UNVERIFIED` |
|
||||
| `FE-GATE-027` | binary I-O & local store | merge | `FE-OC-013`, `FE-OC-027` | — | picker 취소·거부, quota 초과 fallback, OPFS 순차 write, Cache Storage 버전 파티션, object URL 해제 | 모든 fixture가 기대 kind로 처리되고 object URL 누수 0 | binary I-O report | `FAIL_UNVERIFIED` |
|
||||
| `FE-GATE-028` | cache tier & cross-tab | merge | `FE-OC-012`, `FE-OC-028` | — | 영속 캐시 version 파티션, 탭 A mutation → 탭 B 무효화, BroadcastChannel 부재 fallback | 불일치 version 캐시는 복원되지 않고 탭 간 무효화가 도달 | cache tier report | `FAIL_UNVERIFIED` |
|
||||
| `FE-GATE-028` | cache tier & cross-tab | merge | `FE-OC-012`, `FE-OC-028` | — | 영속 캐시 version 파티션, 탭 A mutation → 탭 B 무효화, BroadcastChannel 부재 시 탭 내 무효화만 | 불일치 version 캐시는 복원되지 않고 탭 간 무효화가 도달 | cache tier report | `FAIL_UNVERIFIED` |
|
||||
| `FE-GATE-029` | large object transfer | merge + release | `FE-OC-019`, `FE-OC-029` | `FE-NFR-018` | presign 만료, part 재시도 상한, stream 중단 후 재개, 무결성 불일치, credential 첨부 negative | 모든 fixture 통과 + 전송 요청에 session credential 0건 | transfer report | `FAIL_UNVERIFIED` |
|
||||
| `FE-GATE-030` | multi-protocol transport | merge | `FE-OC-006`, `FE-OC-007`, `FE-OC-030` | — | GraphQL `200 + errors[]`, gRPC status ↔ HTTP status, codec decode 실패, gateway fallback | 모든 protocol 실패가 기대 kind로 정규화 | protocol mapping report | `FAIL_UNVERIFIED` |
|
||||
| `FE-GATE-031` | realtime lifecycle | merge + release | `FE-OC-011`, `FE-OC-031` | `FE-NFR-016`, `FE-NFR-017` | 결정론 fake clock backoff, resume gap 감지, unmount 후 열린 연결(`SUBSCRIPTION_LEAKED` fixture), 이벤트 스키마 거부, `FE-RB-006` drill | backoff가 cap을 넘지 않고 unmount 후 열린 연결 0, 미검증 이벤트 0건 도달 | realtime lifecycle report | `FAIL_UNVERIFIED` |
|
||||
@@ -2511,7 +2516,7 @@ Repository identity와 implementation/test/CI/deploy evidence 또는 blocking ga
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-026` | `feature-frontend-operational-runbook-contract` | 5개 drill의 trigger·window·escalation·evidence assertion이 검증된다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-DEPLOYMENT-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-TELEMETRY-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-024`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-005`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-012`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-004` | `planned` |
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-027` | `feature-frontend-ci-quality-gates-contract` | blocking gate가 분리되고 dependency graph와 artifact retention이 검증된다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-TEST-STACK-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SUPPLY-CHAIN-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-DEPLOYMENT-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-017`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-020`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-024`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-025`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-026` | `planned` |
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-028` | `feature-frontend-binary-file-io-store-contract` | picker·다운로드·object URL 해제·quota·OPFS·Cache Storage fixture가 통과하고 binary I-O report가 생성된다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-BINARY-STORE-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-REGISTRY-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-002`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-011` | `planned` |
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-029` | `feature-frontend-cache-tier-cross-tab-invalidation-contract` | version 파티션·탭 간 무효화·채널 부재 fallback fixture가 통과한다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CROSS-TAB-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SERVER-STATE-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-010`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-011` | `planned` |
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-029` | `feature-frontend-cache-tier-cross-tab-invalidation-contract` | version 파티션·탭 간 무효화·채널 부재 시 탭 내 무효화 fixture가 통과한다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CROSS-TAB-001@2`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SERVER-STATE-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-010`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-011` | `planned` |
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-030` | `feature-frontend-large-object-transfer-contract` | presign 만료·part 재시도·무결성·credential 경계 fixture가 통과한다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-TRANSFER-CREDENTIAL-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-RESUMABLE-TRANSFER-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-005`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-028` | `planned` |
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-031` | `feature-frontend-multi-protocol-api-transport-contract` | protocol별 성공/실패 정규화와 gateway fallback fixture가 통과한다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-PROTOCOL-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-VALIDATION-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-005`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-006`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-007` | `planned` |
|
||||
| `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-032` | `feature-frontend-realtime-subscription-lifecycle-contract` | backoff·resume·구독 해제·이벤트 검증 fixture와 `FE-RB-006` drill이 통과한다 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-REALTIME-TRANSPORT-001@1`, `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-REALTIME-LIFECYCLE-001@1` | `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-006`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-007`, `WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-013` | `planned` |
|
||||
@@ -2553,7 +2558,7 @@ Branch는 project-wide contract를 상세 implementation-ready spec으로 내린
|
||||
| `feature-frontend-operational-runbook-contract` | `FE-OC-025` | `FE-OC-004`, `FE-OC-006`, `FE-OC-014`, `FE-OC-016`, `FE-OC-017` | five drills with trigger/window/escalation/evidence assertions | P3 | `feature-frontend-release-cache-rollback-contract`, `feature-api-client-response-envelope-contract`, `feature-frontend-observability-logging-trace-contract`, `feature-frontend-env-runtime-config-contract` |
|
||||
| `feature-frontend-ci-quality-gates-contract` | — | `FE-OC-020`, `FE-OC-021`, `FE-OC-022`, `FE-OC-023`, `FE-OC-024`, `FE-OC-025` | separate blocking gates, dependency graph, artifact retention | P3 | `feature-frontend-test-taxonomy-contract`, `feature-frontend-build-bundle-supply-chain-contract`, `feature-frontend-release-cache-rollback-contract`, `feature-web-vitals-performance-budget-contract`, `feature-frontend-operational-runbook-contract` |
|
||||
| `feature-frontend-binary-file-io-store-contract` | `FE-OC-027` | `FE-OC-013`, `FE-OC-022`, `FE-OC-029` | picker/다운로드/object URL 해제/quota/OPFS/Cache Storage fixtures + binary I-O report | P4 | `feature-frontend-storage-registry-contract`, `feature-frontend-clean-architecture-layering-contract` |
|
||||
| `feature-frontend-cache-tier-cross-tab-invalidation-contract` | `FE-OC-028` | `FE-OC-012`, `FE-OC-013`, `FE-OC-023` | version 파티션 + 탭 간 무효화 + 채널 부재 fallback fixtures | P4 | `feature-server-state-caching-contract`, `feature-frontend-storage-registry-contract` |
|
||||
| `feature-frontend-cache-tier-cross-tab-invalidation-contract` | `FE-OC-028` | `FE-OC-012`, `FE-OC-013`, `FE-OC-023` | version 파티션 + 탭 간 무효화 + 채널 부재 시 탭 내 무효화 fixtures | P4 | `feature-server-state-caching-contract`, `feature-frontend-storage-registry-contract` |
|
||||
| `feature-frontend-large-object-transfer-contract` | `FE-OC-029` | `FE-OC-006`, `FE-OC-019`, `FE-OC-027` | presign 만료/part 재시도/무결성/credential 경계 fixtures | P4 | `feature-api-client-response-envelope-contract`, `feature-frontend-binary-file-io-store-contract` |
|
||||
| `feature-frontend-multi-protocol-api-transport-contract` | `FE-OC-030` | `FE-OC-006`, `FE-OC-007`, `FE-OC-008` | protocol별 성공/실패 정규화 + gateway fallback fixtures | P4 | `feature-api-client-response-envelope-contract`, `feature-runtime-schema-validation-contract`, `feature-frontend-error-classification-boundary-contract` |
|
||||
| `feature-frontend-realtime-subscription-lifecycle-contract` | `FE-OC-031` | `FE-OC-007`, `FE-OC-008`, `FE-OC-011`, `FE-OC-025` | backoff/resume/구독 해제/이벤트 검증 fixtures + `FE-RB-006` drill | P4 | `feature-runtime-schema-validation-contract`, `feature-frontend-error-classification-boundary-contract`, `feature-async-ui-state-contract` |
|
||||
|
||||
@@ -42,13 +42,35 @@ semantic_surface_exclusions:
|
||||
|
||||
도메인/비즈니스 로직은 제거합니다. 대신 운영 실패 분류, 경계 validation, mapper, structured response, structured logging, distributed tracing, env-driven configuration, repository access permission, adapter failure contract, API schema, transaction/concurrency, runtime lifecycle, sample domain fixture, domain onboarding, use case/port contract, domain modeling guardrails, business rule validation, domain event/outbox, metrics/alerting, secret/config source, management endpoint security, tenant policy, file/resource handling, cache consistency, background job/async, API compatibility, CI quality gate, build/release supply chain, container runtime, operational runbook, data retention/privacy, developer experience 기준을 기본 제공해야 합니다.
|
||||
|
||||
### 1.1 Production Capability Platform (2026-07-28 추가)
|
||||
|
||||
위 목표에 **운영 능력(capability)의 개방** 을 더합니다. 계약만 있고 seam 만 있는 adapter 는 실제 운영에서 쓸 수 없습니다. 그렇다고 모든 기술을 core 에 탑재하면 안 쓰는 프로젝트가 의존성·기동시간·보안 표면을 떠안습니다.
|
||||
|
||||
```text
|
||||
available by default, inactive by default
|
||||
```
|
||||
|
||||
- 개발자가 capability 와 provider 를 **typed 설정으로 선택**하고, composition root 가 선택된 토폴로지와 보증을 **startup 에 검증**한다.
|
||||
- application 코드는 framework-free semantic port 에만 의존한다.
|
||||
- 선택된 adapter 는 실제 client·안전한 기본값·health·metric·실패 의미·재사용 가능한 contract test 를 **함께** 제공한다.
|
||||
- **선택되지 않은 capability 는 연결·백그라운드 워커·스키마·암묵적 런타임 동작을 만들지 않는다.**
|
||||
- 하나의 전략이 모든 도메인에 맞다고 가정하지 않는다. rate limit 알고리즘, cache 전략, outbox dispatch 모드, lock 보증 등급은 **교체 가능한 축**으로 둔다.
|
||||
- 자주 쓰는 연산은 기본 제공하되, **그 연산이 만드는 함정(비원자 check-then-act 등)을 문서와 test 가 함께 드러낸다.** 상세는 §36 capability card 의 "unsafe recipe ↔ 안전한 대체" 항목.
|
||||
|
||||
이 확장의 분해 설계(신규 branch 18개 · 주도권 이전 8건 · 기존 owner 개정 3건)는 `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` 가 SSOT 입니다.
|
||||
|
||||
<!-- section-id: implementation-boundaries -->
|
||||
## 2. 하지 않는 것
|
||||
|
||||
- `ProblemDetail` 사용 안 함. 자체 structured envelope 응답을 사용.
|
||||
- 특정 비즈니스 도메인 예외를 기본 제공하지 않음.
|
||||
- 단, skeleton 계약 검증을 위한 sample domain fixture는 둠. 이 sample은 비즈니스 기능이 아니라 contract 검증 도구임.
|
||||
- Kafka/Redis/Slack/Google Email을 기본 dependency로 무겁게 탑재하지 않음.
|
||||
- Kafka/Redis/MongoDB/Slack/Google Email을 **core 기본 dependency로 탑재하지 않음**. optional adapter 모듈로 제공하고 기본 비활성(§1.1). **2026-07-28 개정** — 이전 표기 "무겁게 탑재하지 않음" 은 "구현하지 않는다" 로 읽혀 seam 수준 정체의 근거가 되었다. 모듈 내부는 운영 등급으로 완결하되 선택되지 않으면 런타임에 존재하지 않는다.
|
||||
- **R0 seam 을 R2 provider 로 표기하지 않음.** 문서·startup 진단·capability card 모두에 적용(§36).
|
||||
- capability 의 **use case·domain model·business rule 을 제공하지 않음.** port 와 adapter 계약까지만 정의하고 그 port 를 호출하는 use case 는 적용 프로젝트가 작성.
|
||||
- capability 의 **성능 수치·개선 서사를 만들지 않음.** capacity 입력(키 크기·연산율·보존기간·재시도 증폭)만 계약.
|
||||
- DB 와 broker 를 걸친 **exactly-once**, Redis lock 의 **strong correctness** 를 코드·문서 어디에도 주장하지 않음.
|
||||
- 특정 vendor(관리형 Redis/Kafka/Mongo 제공자, CDN, push 서비스, KMS)를 선택하지 않음.
|
||||
- raw exception, SQL, token, request/response body를 클라이언트 응답이나 기본 로그에 노출하지 않음.
|
||||
- `wiki/interview/`, `wiki/portfolio/`, `wiki/blog/`로 직접 파생하지 않음. 먼저 `wiki/projects/` canonical 문서로 승급.
|
||||
|
||||
@@ -210,7 +232,7 @@ retryable 기본값:
|
||||
- read timeout
|
||||
- DNS temporary failure
|
||||
- message publish temporary failure
|
||||
- cache unavailable when degradation is allowed
|
||||
- cache unavailable when degradation is allowed — **단, 이 행은 §11 실패 정책 매트릭스가 세분화한다**: backend 실패만 retryable/degradable 이고 codec·프로그래밍 결함은 non-retryable(해당 연산 fail closed)
|
||||
|
||||
non-retryable 기본값:
|
||||
|
||||
@@ -372,11 +394,27 @@ use case capability:
|
||||
- missing token, malformed token, expired token, invalid signature, issuer mismatch, audience mismatch, claim mapping failure 분리.
|
||||
- token/PII 로그 금지.
|
||||
|
||||
### Optional Adapters
|
||||
### Capability 별 실패 정책 매트릭스
|
||||
|
||||
- Kafka: publish/consume/deserialization/retry/DLQ/idempotency/correlationId 기준.
|
||||
- Redis: cache miss는 장애 아님. unavailable은 degrade 가능 여부로 분류.
|
||||
- Slack/Email: notification failure가 core use case를 막을지 명시.
|
||||
> **2026-07-28 개정** — 이전 `### Optional Adapters` 3줄(Kafka / Redis / Slack·Email)을 대체한다. 전역 fail-open 도 전역 fail-closed 도 없다. 실패 정책은 **capability 단위**이며, 같은 client 를 공유해도 정책은 분리된다(예: cache Redis 와 coordination Redis).
|
||||
> owner: [[raw/branch-notes/feature-capability-provider-selection-contract]] · 근거: `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` §9
|
||||
|
||||
| Capability | 기본 실패 정책 | 근거 |
|
||||
|---|---|---|
|
||||
| optional cache (backend 실패) | fail open — source 로 fallback, degraded 결과와 metric 노출 | 캐시 부재는 정확성 손실이 아니다 |
|
||||
| cache codec·프로그래밍 결함 | fail closed (해당 연산) — 손상 항목 축출/격리, miss 로 위장 금지 | 결함을 miss 로 숨기면 영구 오염 |
|
||||
| security session store | fail closed — 인증 상태를 지어내지 않는다 | 인증은 추측 대상이 아니다 |
|
||||
| keyed mutation idempotency | fail closed | 중복 write 방지가 목적 |
|
||||
| strict rate limit (남용·비용 경계) | fail closed 또는 의도적으로 제한된 local emergency limiter | 무제한 통과는 경계의 부재 |
|
||||
| availability 지향 rate limit | 명시적 local emergency fallback, 조용한 무제한 통과 금지 | 저하는 허용, 은폐는 불가 |
|
||||
| efficiency lock | 선언된 use case 정책에 따라 실패 또는 계속 | 중복 *작업* 방지가 목적 |
|
||||
| fenced correctness lock | 획득·lease 상실 시 보호 작업 중단 | 중복 *결과* 차단이 목적 |
|
||||
| outbox append | 업무 트랜잭션 롤백 | append 는 업무 write 와 원자 |
|
||||
| outbox dispatcher 장애 | write 는 계속 축적, lag·backlog 알림 | 전달 지연은 업무 차단 사유가 아니다 |
|
||||
| best-effort notification·message | 명시적 fail open | 이름과 계약에 best-effort 명시 |
|
||||
| durable notification·message | outbox/inbox + 재시도 + 종단 실패 경로 | 유실 불가 경로 |
|
||||
|
||||
Kafka 의 publish/consume/deserialization/retry/DLQ/idempotency/correlationId 기준은 [[raw/branch-notes/feature-kafka-producer-runtime-contract]] 와 [[raw/branch-notes/feature-kafka-consumer-inbox-contract]] 가 소유한다.
|
||||
|
||||
## 12. Test Contract
|
||||
|
||||
@@ -1032,6 +1070,36 @@ promotion failure:
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-057` | `feature-sample-portfolio-public-access` | sample public endpoint allowlist와 authenticated endpoint negative test가 명시된다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-MODULE-LAYOUT-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-FRAMEWORK-001@2`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-TEST-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-048`, `WI-CA-SKELETON-OPERATIONAL-CONTRACT-021` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-058` | `feature-startup-failure-log-suppression` | suppressible startup failure 조건과 retained actionable error test가 명시된다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-BOOTSTRAP-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-ERROR-ENVELOPE-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-001`, `WI-CA-SKELETON-OPERATIONAL-CONTRACT-017` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-059` | `feature-static-analysis-quality-contract` | static analysis 도구·threshold·CI failure mapping과 fixture가 명시된다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-BUILD-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-TEST-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-028`, `WI-CA-SKELETON-OPERATIONAL-CONTRACT-029`, `WI-CA-SKELETON-OPERATIONAL-CONTRACT-018` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `feature-capability-provider-selection-contract` | capability descriptor·provider 선택·readiness 등급 검증 test가 통과하고 bean 이름 기반 판정이 제거된다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-SELECTION-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001@1` | - | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-061` | `feature-redis-runtime-role-isolation-contract` | 3-role 연결·키·코덱·health 계약 test와 incompatible co-location 거부 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-REDIS-ROLE-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-OPTIONAL-ADAPTER-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-062` | `feature-redis-atomic-program-catalog-contract` | program descriptor·golden vector·NOSCRIPT 재적재 test와 unsafe recipe 경합 재현 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-REDIS-PROGRAM-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-061` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-063` | `feature-kafka-producer-runtime-contract` | acknowledgement·delivery timeout·순서·보안 설정 계약 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-EVENT-BROKER-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-064` | `feature-kafka-consumer-inbox-contract` | inbound leaf 등록·manual ack·rebalance·DLT·inbox 멱등 계약 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-IDEMPOTENCY-OWNERSHIP-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-063`, `WI-CA-SKELETON-OPERATIONAL-CONTRACT-070` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-065` | `feature-mongo-runtime-baseline-contract` | concern·index manifest·replica-set 트랜잭션·change stream checkpoint test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-MONGO-BASELINE-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-OPTIONAL-ADAPTER-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-066` | `feature-objectstorage-streaming-lifecycle-contract` | streaming·multipart·presigned·checksum·orphan 회수 계약 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-MODULE-LAYOUT-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-067` | `feature-cache-strategy-registry-contract` | 전략 registry·TTL 4종·single-flight·실패 등급 분리 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CACHE-STRATEGY-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CACHE-FAILURE-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-061` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-068` | `feature-edge-rate-limit-policy-registry-contract` | 알고리즘 6종 교체·policy registry·decision 기반 Retry-After·fallback test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-RATE-LIMIT-ALGORITHM-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-RATE-LIMIT-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-062` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-069` | `feature-session-auth-mode-contract` | 배타 인증 모드·CSRF·쿠키·회전·다중 파드 세션 계약 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-SESSION-MODE-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-061` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-070` | `feature-idempotency-ownership-protocol-contract` | owner token 프로토콜·lease 분리·보증 등급별 provider 공통 계약 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-IDEMPOTENCY-OWNERSHIP-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-IDEMPOTENCY-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-071` | `feature-fenced-lock-coordination-contract` | fencing token 단조성·high watermark 거부·lease-lost 신호 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-LOCK-FENCING-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-SCHEDULER-LOCK-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-072` | `feature-outbox-dispatch-mode-contract` | event/delivery 분리·모드 배타·CDC 라우팅·파티션 정리 조건 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-OUTBOX-DISPATCH-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-063` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-073` | `feature-graphql-production-baseline-contract` | 깊이·복잡도·persisted query·field authorization·스키마 gate test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-API-VERSIONING-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-074` | `feature-grpc-production-baseline-contract` | proto 호환·TLS/mTLS·deadline·크기 한계·drain test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-OPTIONAL-ADAPTER-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-075` | `feature-websocket-cluster-delivery-contract` | handshake 인증·destination authorization·bounded queue·cluster 전달 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060`, `WI-CA-SKELETON-OPERATIONAL-CONTRACT-063` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-076` | `feature-read-consistency-query-contract` | ReadConsistency·cursor·replica 라우팅·projection lag 계약 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-READ-CONSISTENCY-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-TRANSACTION-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-060` | `planned` |
|
||||
| `WI-CA-SKELETON-OPERATIONAL-CONTRACT-077` | `feature-notification-durable-delivery-contract` | durable/best-effort 분리·template 버전·receipt·dedupe 계약 test가 통과한다 | `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-RESILIENCE-001@1` | `WI-CA-SKELETON-OPERATIONAL-CONTRACT-072` | `planned` |
|
||||
|
||||
> **주도권 이전 (2026-07-28)** — 아래 기존 Work Item 은 관심사 일부 또는 전부를 신규 branch 로 이전했다. 이전 절차와 대상 D-row 는 `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` §5 가 SSOT.
|
||||
>
|
||||
> | 기존 WI | branch | 이전한 관심사 | 신규 owner |
|
||||
> |---|---|---|---|
|
||||
> | `WI-…-016` | `feature-rate-limit-idempotency-contract` | idempotency 저장소·프로토콜(H1), rate limit 키·분산·알고리즘(H2) | `WI-…-070`, `WI-…-068` |
|
||||
> | `WI-…-024` | `feature-cache-consistency-contract` | cache 전략 — stampede·TTL·직렬화·negative·cluster(H3) | `WI-…-067` |
|
||||
> | `WI-…-049` | `feature-cachestore-multi-backend-router` | cache 실패 등급 — fail-open 경계(H4) | `WI-…-067`, `WI-…-061` |
|
||||
> | `WI-…-052` | `feature-distributed-lock-contract` | correctness lock·fencing(H5). efficiency mutex 는 유지 | `WI-…-071` |
|
||||
> | `WI-…-038` | `feature-domain-event-outbox-contract` | outbox 행 모델·dispatch 전략(H6) | `WI-…-072` |
|
||||
> | `WI-…-008` | `feature-security-operational-baseline` | session·인증 모드(H7). JWT 검증은 유지 | `WI-…-069` |
|
||||
> | `WI-…-004` | `feature-env-driven-runtime-configuration` | multi-instance 활성화 **판정 메커니즘**(H8) — [[raw/branch-notes/feature-env-driven-runtime-configuration]] D8 의 bean presence 검사 부분. flag·env registry row 는 계속 env-driven 소유 | `WI-…-060` |
|
||||
|
||||
## 24. Branch 실행 계획
|
||||
|
||||
@@ -1107,6 +1175,38 @@ TODO는 작업 목록이 아니라 미완성 계약입니다. 각 TODO는 branch
|
||||
- [[raw/branch-notes/feature-streaming-response-contract]] (SSE / WebSocket / long-polling / chunked 지원 여부 1차 결정)
|
||||
- [[raw/branch-notes/feature-resource-identifier-contract]] (D1~D19 결정 박힘 — ULID 26-char Crockford base32 + PostgreSQL `uuid` native + sample-portfolio `WorkLogId = "01ARZ3NDEKTSV4RRFFQ69G5FAV"` fixture, project §34 Stack Commitment 정합)
|
||||
|
||||
**Production Capability 확장 (2026-07-28 신설 — `WI-…-060`~`077`).** 착수 순서는 Tier 의존을 따른다: 1차 플랫폼 → 2차 기술 런타임 → 3차 능력 계약 → 4차 전송·조회. 1차 완료 전 2차 착수 금지(설계 §12).
|
||||
|
||||
1차 — 플랫폼:
|
||||
|
||||
- [[raw/branch-notes/feature-capability-provider-selection-contract]]
|
||||
|
||||
2차 — 기술 런타임:
|
||||
|
||||
- [[raw/branch-notes/feature-redis-runtime-role-isolation-contract]]
|
||||
- [[raw/branch-notes/feature-redis-atomic-program-catalog-contract]] (`redis-runtime-role-isolation` 선행 필수)
|
||||
- [[raw/branch-notes/feature-kafka-producer-runtime-contract]]
|
||||
- [[raw/branch-notes/feature-kafka-consumer-inbox-contract]]
|
||||
- [[raw/branch-notes/feature-mongo-runtime-baseline-contract]]
|
||||
- [[raw/branch-notes/feature-objectstorage-streaming-lifecycle-contract]]
|
||||
|
||||
3차 — 능력 계약 (착수 시 설계 §5.2 주도권 이전 6단계 동반):
|
||||
|
||||
- [[raw/branch-notes/feature-cache-strategy-registry-contract]]
|
||||
- [[raw/branch-notes/feature-edge-rate-limit-policy-registry-contract]]
|
||||
- [[raw/branch-notes/feature-session-auth-mode-contract]]
|
||||
- [[raw/branch-notes/feature-idempotency-ownership-protocol-contract]]
|
||||
- [[raw/branch-notes/feature-fenced-lock-coordination-contract]]
|
||||
- [[raw/branch-notes/feature-outbox-dispatch-mode-contract]]
|
||||
|
||||
4차 — 전송·조회:
|
||||
|
||||
- [[raw/branch-notes/feature-graphql-production-baseline-contract]]
|
||||
- [[raw/branch-notes/feature-grpc-production-baseline-contract]]
|
||||
- [[raw/branch-notes/feature-websocket-cluster-delivery-contract]]
|
||||
- [[raw/branch-notes/feature-read-consistency-query-contract]]
|
||||
- [[raw/branch-notes/feature-notification-durable-delivery-contract]]
|
||||
|
||||
## 25. Default Decisions
|
||||
|
||||
> **Legacy reference (v1).** 아래 default와 owner map은 세부 rationale·branch-local owner 설명을 보존한다. project-wide 결정의 현재 owner와 상속 기준은 `## 6.1 Project Decision Registry / 안정 결정 레지스트리`다. branch-owned D-row는 project registry로 복제하지 않는다.
|
||||
@@ -1134,6 +1234,7 @@ TODO는 작업 목록이 아니라 미완성 계약입니다. 각 TODO는 branch
|
||||
| rate-limit key | authenticated는 principal 기준, unauthenticated는 IP + normalized route 기준. tenant 활성화 시 tenant를 prefix로 추가 | `feature-rate-limit-idempotency-contract` | tenant/user/API key/IP 기준이 branch마다 다름 |
|
||||
| bootstrap command | `./gradlew bootstrap` 기본. 없는 경우 `./gradlew test` + `docker compose up` wrapper로 제공 | `feature-developer-experience-contract` | 신규 팀이 첫 실행 명령을 문서에서 판정할 수 없음 |
|
||||
| Testcontainers policy | persistence/outbound integration test부터 강제, unit/architecture/contract test는 Testcontainers 금지 | `feature-test-taxonomy-fixture-contract` | contract test가 컨테이너 의존으로 느려지거나 CI 실패 원인을 흐림 |
|
||||
| capability 활성화 | production capability는 모듈로 제공하되 기본 비활성. 활성화는 typed descriptor 기반 provider 선택으로만 (`provider: disabled\|<id>` / `dispatch-mode` / leaf `enabled`) | `feature-capability-provider-selection-contract` | classpath 존재·`matchIfMissing`·local provider 기본값으로 capability가 활성화되거나, bean 이름 존재만으로 보증을 주장 |
|
||||
|
||||
### SSOT Owner Map
|
||||
|
||||
@@ -1157,6 +1258,32 @@ TODO는 작업 목록이 아니라 미완성 계약입니다. 각 TODO는 branch
|
||||
| **HTTP method 지원/실패 분류** (D12 405/Allow, D13 HEAD/OPTIONS) | [[raw/branch-notes/feature-api-contract-baseline]] D12/D13 | (no counterpart — leaf) | 405 응답 + `Allow` MUST, HEAD MUST 자동 mirror |
|
||||
| **PATCH content type + mapper** | [[raw/branch-notes/feature-boundary-validation-mapping-contract]] B2 (ArchUnit `no_merge_patch_json_media_type_string` enforced) | api-contract-baseline D14 (정정 — content type 정책만 consume) | RFC 7396 (merge-patch+json) / RFC 6902 (json-patch+json) 모두 *미채택* — `application/json` only · absent/null/value 3-상태 wrapper |
|
||||
| **Conditional request** (ETag / If-Match / If-None-Match / 304 / 412) | [[raw/branch-notes/feature-api-contract-baseline]] D15 | sample-portfolio fixture (WorkLogVersion 이 ETag derivation source) | DB optimistic lock 과 HTTP 412 가 동일 conflict 의 두 표현 |
|
||||
|
||||
#### Production Capability 영역 (2026-07-28 신설 — 설계 §4.2 / §5)
|
||||
|
||||
> **주도권 이전 표기**: `이전 ← <기존 branch>` 는 그 관심사의 owner 가 신규 branch 로 **이동했음**을 뜻한다. 기존 branch 는 consumer 로 남고, 해당 D-row 는 `/branch-spec` 으로 신규 결정이 확정된 뒤 포인터로 치환된다(설계 §5.2).
|
||||
|
||||
| contract area | single SSOT owner | consumers/producers | rule |
|
||||
| --- | --- | --- | --- |
|
||||
| capability 활성화 · provider 선택 · readiness 등급 | `feature-capability-provider-selection-contract` | 모든 capability branch, env-runtime-config, runtime-health, integration-adapter-templates | 활성화 판정은 typed descriptor 로만. bean 이름·classpath 존재는 근거가 아님. **이전 ← [[raw/branch-notes/feature-env-driven-runtime-configuration]] 의 판정 메커니즘(H8)** — flag 자체와 env registry row 는 env-driven 유지 |
|
||||
| Redis role·연결·키·코덱 | `feature-redis-runtime-role-isolation-contract` | cache-strategy, rate-limit, session, idempotency, fenced-lock | 물리 형식은 여기서만 결정. 능력 branch 는 의미만 소유 |
|
||||
| Redis atomic program (Lua/Function) 카탈로그 | `feature-redis-atomic-program-catalog-contract` | rate-limit, idempotency, fenced-lock, cache-strategy | 다단계 read-decide-write 는 program 경유. unsafe recipe ↔ 대체 쌍 문서화 의무 |
|
||||
| cache 전략·TTL·stampede | `feature-cache-strategy-registry-contract` | cache-consistency, cachestore-router, redis-runtime | **이전 ← [[raw/branch-notes/feature-cache-consistency-contract]] D3~D9 (H3)** |
|
||||
| cache 실패 등급 (fail-open 경계) | `feature-cache-strategy-registry-contract` | cachestore-router, redis-runtime | **이전 ← [[raw/branch-notes/feature-cachestore-multi-backend-router]] D1~D3 (H4)** — codec 결함을 miss 로 위장 금지 |
|
||||
| rate limit 알고리즘·policy registry·키 차원 | `feature-edge-rate-limit-policy-registry-contract` | rate-limit-idempotency, api-contract-baseline, web adapter | **이전 ← [[raw/branch-notes/feature-rate-limit-idempotency-contract]] D4·D5 (H2)** |
|
||||
| idempotency 저장소·owner token 프로토콜 | `feature-idempotency-ownership-protocol-contract` | rate-limit-idempotency, transaction-concurrency, kafka-consumer-inbox | **이전 ← [[raw/branch-notes/feature-rate-limit-idempotency-contract]] D2·D3·D6·D7·D8·D9 (H1)** |
|
||||
| correctness lock · fencing token | `feature-fenced-lock-coordination-contract` | distributed-lock, background-job-async | **이전 ← [[raw/branch-notes/feature-distributed-lock-contract]] (H5 — 대상 D-row 는 §25 Owner Map 참조)**. efficiency mutex 는 distributed-lock 이 계속 소유 |
|
||||
| outbox 행 모델 · dispatch 모드 (polling/cdc) | `feature-outbox-dispatch-mode-contract` | domain-event-outbox, background-job-async, kafka-producer | **이전 ← `feature-domain-event-outbox-contract` 행 상태 머신 D-row (H6)** |
|
||||
| session · 인증 모드 (jwt/redis-session) | `feature-session-auth-mode-contract` | security-operational-baseline, authn-authz, redis-runtime | **이전 ← `feature-security-operational-baseline` session D-row (H7)**. JWT 검증 자체는 security baseline 유지 |
|
||||
| Kafka producer 전달 계약 | `feature-kafka-producer-runtime-contract` | messaging-multibroker-router, outbox-dispatch | broker ack·순서·보안은 여기서만 |
|
||||
| Kafka consumer · inbox | `feature-kafka-consumer-inbox-contract` | background-job-async, idempotency-ownership | 신규 inbound leaf 소유. 모듈 registry migration 동반 |
|
||||
| MongoDB 런타임 baseline | `feature-mongo-runtime-baseline-contract` | persistence-failure-baseline, read-consistency-query | PostgreSQL 계약과 분리 |
|
||||
| object storage 스트리밍·수명주기 | `feature-objectstorage-streaming-lifecycle-contract` | file-resource-handling, data-retention-privacy | `byte[]` 전용 API 대체 |
|
||||
| GraphQL 운영 baseline | `feature-graphql-production-baseline-contract` | api-contract-baseline, application-query-bypass | subscription 전송은 websocket branch 위임 |
|
||||
| gRPC 운영 baseline | `feature-grpc-production-baseline-contract` | streaming-response, security-operational-baseline | proto 호환·deadline·크기 한계 |
|
||||
| WebSocket cluster 전달 | `feature-websocket-cluster-delivery-contract` | streaming-response, graphql, kafka-producer | in-process simple broker 는 R1 고정 |
|
||||
| 조회 일관성 · replica 라우팅 | `feature-read-consistency-query-contract` | application-query-bypass, database-connection-pool, mongo-runtime | 범용 QueryPort 도입 금지 |
|
||||
| notification durable 전달 | `feature-notification-durable-delivery-contract` | notification-provider-spi, outbox-dispatch, webhook-outbound | provider SPI·라우팅 골격은 notification-provider-spi 유지 |
|
||||
| **Response cache policy + Vary header** | [[raw/branch-notes/feature-api-contract-baseline]] D16 (HTTP header 정책) | `feature-cache-consistency-contract` (cache layer 구현 SSOT) | default `Cache-Control: no-store`, Vary 의무 |
|
||||
| **Long-running operation (LRO)** | [[raw/branch-notes/feature-api-contract-baseline]] D17 (polling-only) | webhook callback 패턴은 별도 `feature-webhook-outbound-contract` | 202 + `Location: /v1/operations/{id}` + polling endpoint |
|
||||
| **Pagination index base + size cap** | [[raw/branch-notes/feature-api-contract-baseline]] D18 | (no counterpart — leaf) | `page` 0-indexed, `size` default 20 / max 100 |
|
||||
@@ -1228,6 +1355,21 @@ TODO는 작업 목록이 아니라 미완성 계약입니다. 각 TODO는 branch
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-TEST-001` | 1 | `stack-test` | test framework는 JUnit 5다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | §34 Stack Matrix `Test framework` |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-ARCHTEST-001` | 1 | `stack-archtest` | architecture test는 archunit-junit5 1.3.0을 사용한다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | §34 Stack Matrix `Architecture test` |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-RANDOM-001` | 1 | `stack-random` | ULID·idempotency key·token 생성의 random source는 SecureRandom이다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | §34 Stack Matrix `Random source` |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-SELECTION-001` | 1 | `capability-selection` | production capability는 available by default이고 inactive by default이며 활성화는 typed descriptor 기반 provider 선택으로만 이뤄진다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | §36 Capability Readiness Model + `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` §6 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001` | 1 | `capability-readiness` | 모든 capability는 R0~R3 readiness 등급과 capability card를 가지며 R0 seam을 R2 provider로 표기하지 않는다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | §36 Capability Readiness Model |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-REDIS-ROLE-001` | 1 | `redis-role` | Redis는 cache·coordination·session 3개 role로 분리하고 key prefix나 DB number를 격리 수단으로 쓰지 않는다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #2 · ca-tmpl redis 심층 설계 §10 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-REDIS-PROGRAM-001` | 1 | `redis-program` | 다단계 read-decide-write는 버전 있는 atomic program으로만 제공하고 각 helper는 unsafe recipe와 안전한 대체를 쌍으로 문서화하며 경합 test로 증명한다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #3 · ca-tmpl redis 심층 설계 §13·§14 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CACHE-STRATEGY-001` | 1 | `cache-strategy` | cache 기본 전략은 cache-aside와 after-commit 무효화이고 SWR·refresh-ahead·L1L2·분산 stampede 억제는 opt-in이며 maxmemory-policy는 배포 설정이 소유한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #8 · ca-tmpl platform 설계 §8.4 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CACHE-FAILURE-001` | 1 | `cache-failure` | optional cache의 backend 실패는 fail open이고 codec·프로그래밍 결함은 해당 연산을 fail closed로 처리하며 cache miss로 위장하지 않는다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | §11 실패 정책 매트릭스 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-RATE-LIMIT-ALGORITHM-001` | 1 | `rate-limit-algorithm` | rate limit은 policyId 단위로 알고리즘을 선택하고 fixed window·sliding counter·token bucket을 기본 제공하며 sliding log·GCRA·leaky bucket은 opt-in이다 | `conditional-default` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #9 · ca-tmpl platform 설계 §8.5 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-SESSION-MODE-001` | 1 | `session-mode` | 인증 모드는 jwt와 redis-session이 배타이고 jwt가 default이며 redis-session은 전용 session role과 CSRF·쿠키·회전·다중 파드 계약을 동반한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #10 · ca-tmpl platform 설계 §8.6 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-IDEMPOTENCY-OWNERSHIP-001` | 1 | `idempotency-ownership` | idempotency는 owner token 기반 claim·renew·complete·release 프로토콜을 쓰고 실행 lease와 replay TTL을 분리하며 보증 등급을 명시한다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #11 · ca-tmpl platform 설계 §9 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-LOCK-FENCING-001` | 1 | `lock-fencing` | DistributedLockPort는 efficiency mutex로 고정하고 correctness가 필요한 경로는 별도 FencedLockPort와 보호 자원의 high watermark 거부로만 보장한다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #12 · ca-tmpl platform 설계 §10 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-OUTBOX-DISPATCH-001` | 1 | `outbox-dispatch` | outbox는 불변 event 행과 polling 전용 delivery 행을 분리하고 dispatch 모드는 polling과 cdc가 배타이며 append는 업무 write와 같은 트랜잭션에 남는다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #13 · ca-tmpl platform 설계 §11.1·§11.2 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-DELIVERY-SEMANTICS-001` | 1 | `delivery-semantics` | end-to-end 메시징 보증은 at-least-once 전달과 멱등 consumer·inbox로 표현하고 DB와 broker를 걸친 exactly-once를 주장하지 않는다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | ca-tmpl platform 설계 §11.4 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-MONGO-BASELINE-001` | 1 | `mongo-baseline` | MongoDB는 read preference·read concern·write concern을 명시하고 트랜잭션과 change stream은 replica-set 요건 검증을 통과할 때만 활성화한다 | `conditional-default` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #6 · ca-tmpl platform 설계 §12.3 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-READ-CONSISTENCY-001` | 1 | `read-consistency` | 조회는 ReadConsistency를 명시하고 replica 라우팅은 그 정책과 요청 문맥으로 결정하며 TransactionPort.inRead는 replica 사용을 뜻하지 않는다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | 설계 §4.2 #17 · ca-tmpl platform 설계 §12.1 |
|
||||
| `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-OPTIONAL-ADAPTER-001` | 1 | `stack-optional-adapter` | optional adapter stack은 축마다 구현체 하나를 고정하고 core stack과 분리된 matrix로 관리한다 | `active` | [[raw/project-notes/ca-skeleton-operational-contract]] | §34 Optional Adapter Stack Matrix |
|
||||
|
||||
| area | single-instance default | multi-instance activation requirement |
|
||||
| --- | --- | --- |
|
||||
@@ -1539,6 +1681,22 @@ Release-blocking 5 category에 대한 runbook stub 5종 작성.
|
||||
|
||||
본 contract의 6개 핵심 결정에 대해 외부 source(공식 문서·RFC·대기업 기술블로그·GitHub repo)를 조사하여 `raw/official-docs/`와 `raw/company-tech-blogs/`에 raw **54개 파일**로 저장. 각 raw 파일은 owning branch-note와 양방향 wikilink로 연결됨. 비교 분석은 추후 `wiki/concepts/` 합성 단계(Phase E)에서 6개 concept 문서로 정리.
|
||||
|
||||
### 29.0 프로젝트 내부 설계 참조 (2026-07-28 추가 — 등급 `internal-design-doc`)
|
||||
|
||||
> **공식 문서가 아니다.** ca-tmpl repo 가 소유한 프로젝트 내부 설계이며, 인용 시 "ca-tmpl 프로젝트 설계 결정" 으로 표기한다. 외부 best practice 로 격상하거나 면접·블로그에서 표준으로 인용하지 않는다(CLAUDE.md §5·§11).
|
||||
> 각 문서의 **외부 공식 근거는 아직 `raw/` 로 수집되지 않았다**. Production Capability branch 의 `/branch-spec` 단계에서 verbatim 인용과 함께 수집한다.
|
||||
|
||||
| 문서 (ca-tmpl `docs/superpowers/specs/`) | 줄 수 | 대응 llm-wiki branch |
|
||||
|---|---:|---|
|
||||
| `2026-07-26-production-capability-platform-design.md` | 1,346 | `feature-capability-provider-selection-contract` 외 17개 전체 |
|
||||
| `2026-07-26-redis-production-capability-design.md` | 6,771 | `feature-redis-runtime-role-isolation-contract`, `feature-redis-atomic-program-catalog-contract` + Redis 를 provider 로 쓰는 능력 branch 5개 |
|
||||
| `2026-07-27-httpclient-production-capability-design.md` | 7,030 | `feature-outbound-http-client-baseline` (개정) |
|
||||
| `2026-07-26-fileserver-production-capability-design.md` | 2,467 | `feature-file-resource-handling-contract` (개정) |
|
||||
|
||||
llm-wiki 측 분해 설계: `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` — 신규 branch 18개·주도권 이전 8건·hub 델타의 SSOT.
|
||||
|
||||
**`/branch-spec` 단계 1차 수집 대상 (외부 공식 문서):** Redis(eval-intro·key eviction·distributed locks·rate-limiter) / Spring Data Redis scripting / Spring Session Redis / Debezium Outbox Event Router / Kafka(design·producer configs) / MongoDB(read·write concern·change streams) / Amazon S3 object integrity / GraphQL Java limits / gRPC(deadlines·retry) / Spring WebSocket broker relay.
|
||||
|
||||
### Topic 1 — Architecture Layout
|
||||
|
||||
- **ca-tmpl 결정**: Gradle multi-module Clean Architecture / Hexagonal boundary (`domain-core`, `application-core`, `adapter-*`, `shared-contract`, `app-bootstrap`, `sample-portfolio`)
|
||||
@@ -2425,7 +2583,9 @@ sequenceDiagram
|
||||
- [[raw/branch-notes/feature-build-release-supply-chain-contract]]
|
||||
- [[raw/branch-notes/feature-business-rule-validation-contract]]
|
||||
- [[raw/branch-notes/feature-cache-consistency-contract]]
|
||||
- [[raw/branch-notes/feature-cache-strategy-registry-contract]]
|
||||
- [[raw/branch-notes/feature-cachestore-multi-backend-router]]
|
||||
- [[raw/branch-notes/feature-capability-provider-selection-contract]]
|
||||
- [[raw/branch-notes/feature-ci-quality-gates-contract]]
|
||||
- [[raw/branch-notes/feature-container-runtime-contract]]
|
||||
- [[raw/branch-notes/feature-contract-registry-governance]]
|
||||
@@ -2439,22 +2599,36 @@ sequenceDiagram
|
||||
- [[raw/branch-notes/feature-domain-event-outbox-contract]]
|
||||
- [[raw/branch-notes/feature-domain-feature-onboarding-contract]]
|
||||
- [[raw/branch-notes/feature-domain-modeling-guardrails]]
|
||||
- [[raw/branch-notes/feature-edge-rate-limit-policy-registry-contract]]
|
||||
- [[raw/branch-notes/feature-env-driven-runtime-configuration]]
|
||||
- [[raw/branch-notes/feature-fenced-lock-coordination-contract]]
|
||||
- [[raw/branch-notes/feature-file-resource-handling-contract]]
|
||||
- [[raw/branch-notes/feature-graphql-production-baseline-contract]]
|
||||
- [[raw/branch-notes/feature-grpc-production-baseline-contract]]
|
||||
- [[raw/branch-notes/feature-idempotency-ownership-protocol-contract]]
|
||||
- [[raw/branch-notes/feature-implementation-readiness-scorecard]]
|
||||
- [[raw/branch-notes/feature-integration-adapter-templates]]
|
||||
- [[raw/branch-notes/feature-kafka-consumer-inbox-contract]]
|
||||
- [[raw/branch-notes/feature-kafka-producer-runtime-contract]]
|
||||
- [[raw/branch-notes/feature-log-management-contract]]
|
||||
- [[raw/branch-notes/feature-management-actuator-security-contract]]
|
||||
- [[raw/branch-notes/feature-messaging-multibroker-router]]
|
||||
- [[raw/branch-notes/feature-metrics-alerting-contract]]
|
||||
- [[raw/branch-notes/feature-migration-startup-contract]]
|
||||
- [[raw/branch-notes/feature-mongo-runtime-baseline-contract]]
|
||||
- [[raw/branch-notes/feature-notification-durable-delivery-contract]]
|
||||
- [[raw/branch-notes/feature-notification-provider-spi]]
|
||||
- [[raw/branch-notes/feature-objectstorage-streaming-lifecycle-contract]]
|
||||
- [[raw/branch-notes/feature-operational-error-observability-foundation]]
|
||||
- [[raw/branch-notes/feature-operational-runbook-contract]]
|
||||
- [[raw/branch-notes/feature-outbound-http-client-baseline]]
|
||||
- [[raw/branch-notes/feature-outbox-dispatch-mode-contract]]
|
||||
- [[raw/branch-notes/feature-persistence-auditing-contract]]
|
||||
- [[raw/branch-notes/feature-persistence-failure-baseline]]
|
||||
- [[raw/branch-notes/feature-rate-limit-idempotency-contract]]
|
||||
- [[raw/branch-notes/feature-read-consistency-query-contract]]
|
||||
- [[raw/branch-notes/feature-redis-atomic-program-catalog-contract]]
|
||||
- [[raw/branch-notes/feature-redis-runtime-role-isolation-contract]]
|
||||
- [[raw/branch-notes/feature-repository-access-permission-contract]]
|
||||
- [[raw/branch-notes/feature-resource-identifier-contract]]
|
||||
- [[raw/branch-notes/feature-runtime-context-propagation-contract]]
|
||||
@@ -2465,6 +2639,7 @@ sequenceDiagram
|
||||
- [[raw/branch-notes/feature-schema-serialization-contract]]
|
||||
- [[raw/branch-notes/feature-secrets-config-source-contract]]
|
||||
- [[raw/branch-notes/feature-security-operational-baseline]]
|
||||
- [[raw/branch-notes/feature-session-auth-mode-contract]]
|
||||
- [[raw/branch-notes/feature-skeleton-package-blueprint-contract]]
|
||||
- [[raw/branch-notes/feature-startup-failure-log-suppression]]
|
||||
- [[raw/branch-notes/feature-static-analysis-quality-contract]]
|
||||
@@ -2473,6 +2648,7 @@ sequenceDiagram
|
||||
- [[raw/branch-notes/feature-test-taxonomy-fixture-contract]]
|
||||
- [[raw/branch-notes/feature-transaction-concurrency-contract]]
|
||||
- [[raw/branch-notes/feature-webhook-outbound-contract]]
|
||||
- [[raw/branch-notes/feature-websocket-cluster-delivery-contract]]
|
||||
<!-- GENERATED: branches:end -->
|
||||
|
||||
> generated reverse view는 child branch의 v2 contract migration 후 채운다. 아래 수기 목록은 그 전까지 legacy navigation으로 보존한다.
|
||||
@@ -2526,7 +2702,28 @@ sequenceDiagram
|
||||
- [[raw/branch-notes/feature-implementation-readiness-scorecard]] — 15-area binary gate
|
||||
- [[raw/branch-notes/feature-distributed-lock-contract]] — `distributedLockProvider` bean 계약 (JdbcLockRegistry default + tx commit 정합)
|
||||
|
||||
(총 44개 — `raw/branch-notes/feature-*.md` glob 으로 확인 가능)
|
||||
**Production Capability 확장 (2026-07-28 신설 — 설계 §4.2)**
|
||||
|
||||
- [[raw/branch-notes/feature-capability-provider-selection-contract]] — capability descriptor + provider 선택 SSOT + readiness R0~R3
|
||||
- [[raw/branch-notes/feature-redis-runtime-role-isolation-contract]] — Redis cache/coordination/session 3-role + 키·코덱
|
||||
- [[raw/branch-notes/feature-redis-atomic-program-catalog-contract]] — Lua/Function 카탈로그 + unsafe recipe ↔ atomic 대체
|
||||
- [[raw/branch-notes/feature-kafka-producer-runtime-contract]] — acks=all + idempotent producer + delivery timeout
|
||||
- [[raw/branch-notes/feature-kafka-consumer-inbox-contract]] — inbound leaf + manual ack + DLT + InboxStorePort
|
||||
- [[raw/branch-notes/feature-mongo-runtime-baseline-contract]] — read/write concern + index manifest + change stream
|
||||
- [[raw/branch-notes/feature-objectstorage-streaming-lifecycle-contract]] — streaming/multipart/presigned + staged finalization
|
||||
- [[raw/branch-notes/feature-cache-strategy-registry-contract]] — 전략 registry + TTL 4종 + 실패 등급 분리
|
||||
- [[raw/branch-notes/feature-edge-rate-limit-policy-registry-contract]] — policyId registry + 알고리즘 6종 교체
|
||||
- [[raw/branch-notes/feature-session-auth-mode-contract]] — jwt | redis-session 배타 프로파일 + 다중 파드
|
||||
- [[raw/branch-notes/feature-idempotency-ownership-protocol-contract]] — owner token claim/renew/complete/release
|
||||
- [[raw/branch-notes/feature-fenced-lock-coordination-contract]] — FencedLockPort + fencing high watermark
|
||||
- [[raw/branch-notes/feature-outbox-dispatch-mode-contract]] — 불변 event + delivery 분리 + polling|cdc 배타
|
||||
- [[raw/branch-notes/feature-graphql-production-baseline-contract]] — depth/complexity + persisted query + DataLoader
|
||||
- [[raw/branch-notes/feature-grpc-production-baseline-contract]] — proto 호환 + mTLS + deadline + backpressure
|
||||
- [[raw/branch-notes/feature-websocket-cluster-delivery-contract]] — handshake 인증 + bounded queue + broker relay
|
||||
- [[raw/branch-notes/feature-read-consistency-query-contract]] — ReadConsistency + cursor + replica 라우팅
|
||||
- [[raw/branch-notes/feature-notification-durable-delivery-contract]] — durable/best-effort 분리 + template 버전 + receipt
|
||||
|
||||
(수기 목록 총 62개 — 기존 44 + Production Capability 18. 위 GENERATED 목록은 77개이며 `raw/branch-notes/feature-*.md` glob 으로 확인 가능)
|
||||
|
||||
### 31.2 근거 자료
|
||||
|
||||
@@ -2673,7 +2870,7 @@ sequenceDiagram
|
||||
- `[ ]` Webhook outbound (signature / replay / retry / observability) — `feature-webhook-outbound-contract` (D=0, scaffolding)
|
||||
- `[ ]` Streaming response (SSE / WebSocket / long-poll / chunked — 1차 결정: 지원 여부) — `feature-streaming-response-contract` (D=0, scaffolding)
|
||||
- `[~]` API versioning + Sunset / Deprecation (`/v1` URI prefix → 향후 `/v2`) — `feature-api-compatibility-deprecation-contract` (D=8, sl=in-progress)
|
||||
- `[~]` Outbound HTTP resilience (Resilience4j circuit breaker / retry / timeout) — `feature-outbound-http-client-baseline` (D=11, sl=in-progress)
|
||||
- `[*]` Outbound HTTP resilience (Resilience4j circuit breaker / retry / timeout) — `feature-outbound-http-client-baseline` (D=11, sl=in-progress). **2026-07-28 상태 정정**: `[~]`→`[*]` — ca-tmpl `adapter/outbound/httpclient` 38개 파일(test 15) 존재. 단 `globalCallTimeout` 이 실행 중 호출을 취소하지 않고 decorator 순서가 문서와 다름 → **본 branch 개정 대상**(설계 §5.3)
|
||||
- `[~]` Error envelope + 코드 registry (`error-codes.yaml` SSOT) — `feature-operational-error-observability-foundation` (D=12, sl=in-progress)
|
||||
- `[~]` Idempotency-Key + Rate limit (HTTP header / TTL / fingerprint) — `feature-rate-limit-idempotency-contract` (D=10, sl=in-progress)
|
||||
- `[~]` Contract verification test suite (OpenAPI drift detection) — `feature-contract-verification-test-suite` (D=9, sl=in-progress)
|
||||
@@ -2689,9 +2886,9 @@ sequenceDiagram
|
||||
- `[~]` Migration runner readiness gate (Flyway startup) — `feature-migration-startup-contract` (D=8, sl=in-progress)
|
||||
- `[~]` Multi-tenancy isolation (tenant context + DB scope) — `feature-tenant-context-policy` (D=10, sl=in-progress)
|
||||
- `[~]` Data retention / Privacy / GDPR (DSR / PII / 감사 log) — `feature-data-retention-privacy-contract` (D=12, sl=in-progress)
|
||||
- `[~]` File / Resource handling (upload / download / S3) — `feature-file-resource-handling-contract` (D=12, sl=in-progress)
|
||||
- `[*]` File / Resource handling (upload / download / S3) — `feature-file-resource-handling-contract` (D=12, sl=in-progress). **2026-07-28 상태 정정**: `[~]`→`[*]` — ca-tmpl `adapter/outbound/fileserver` 16개 파일(test 5) 존재. 전체 파일 버퍼링·비원자 덮어쓰기는 **본 branch 개정 대상**(설계 §5.3). object storage 스트리밍은 [[raw/branch-notes/feature-objectstorage-streaming-lifecycle-contract]] 로 분리
|
||||
- `[~]` Domain event + Transactional Outbox — `feature-domain-event-outbox-contract` (D=10, sl=in-progress)
|
||||
- `[~]` Cache consistency (Redis adapter + invalidation) — `feature-cache-consistency-contract` (D=9, sl=in-progress)
|
||||
- `[*]` Cache consistency (Redis adapter + invalidation) — `feature-cache-consistency-contract` (D=9, sl=in-progress). **2026-07-28 상태 정정**: `[~]`→`[*]` — ca-tmpl `adapter/outbound/cache-redis` 43개 파일(test 13) 존재. 전략·실패 등급 주도권은 [[raw/branch-notes/feature-cache-strategy-registry-contract]] 로 이전(H3)
|
||||
- `(없음)` Persistence auditing (CreatedBy / UpdatedBy 도메인 오염 차단) — **신규 branch 권고: `feature-persistence-auditing-contract`**
|
||||
- `(없음)` DB connection pool 운영 안정성 (HikariCP pool size / timeout / leak detection / slow query) — **신규 branch 권고 (priority #4): `feature-database-connection-pool-contract`**
|
||||
- `(없음)` Backup / restore / DR (PITR / schema rollback policy / restore drill) — F 미래 후보 (사용자 항목 #6)
|
||||
@@ -2735,6 +2932,40 @@ sequenceDiagram
|
||||
- `(없음)` Template instantiation contract (group / artifact / basePackage / root package rename / README 치환 / sample-off 적용 검증) — **신규 branch 권고 (priority #1): `feature-template-instantiation-contract`** — developer-experience + sample-removal-adoption 와 인접하나 *clone 후 검증 절차* 가 독립 row 로 약함
|
||||
- `(없음)` AuthN / AuthZ product API baseline (JWT / OAuth2 resource server / RBAC / ABAC / permission matrix / endpoint authorization annotation) — **신규 branch 권고 (priority #5): `feature-authentication-authorization-contract`** — `feature-security-operational-baseline` 와 별개 (그 branch 는 CORS / SecureRandom / header suppression 중심, 본 branch 는 *product API 인증/인가*)
|
||||
|
||||
### F-CAP. Production Capability 영역 (2026-07-28 신설 — 18 branch)
|
||||
|
||||
> 설계 SSOT: `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md`. 착수 순서는 §24 의 4차수를 따른다. 각 row 는 `WI-…-060`~`077` 과 1:1.
|
||||
|
||||
**Tier P — 플랫폼 (나머지 17개의 선행)**
|
||||
|
||||
- `[ ]` Capability descriptor · provider 선택 · readiness R0~R3 · capability card — `feature-capability-provider-selection-contract` (D=0, scaffolding). **선행 필수** — bean 이름 기반 multi-instance 판정(`StartupSafetyValidator`) 교체 포함
|
||||
|
||||
**Tier T — 기술 런타임**
|
||||
|
||||
- `[*]` Redis role isolation · 연결 · key model · codec — `feature-redis-runtime-role-isolation-contract` (D=0, scaffolding). 코드 일부 존재: key builder/namespace/digest, envelope codec, Lettuce runtime 골격
|
||||
- `[*]` Redis atomic program 카탈로그 (Lua/Function) — `feature-redis-atomic-program-catalog-contract` (D=0, scaffolding). 코드 일부 존재: `RedisLuaProgramExecutor`·`RedisProgramCatalog`·`RedisProgramDescriptor`·`RedisAtomicPrimitives`
|
||||
- `[ ]` Kafka producer 런타임 (acks=all · idempotent · delivery timeout) — `feature-kafka-producer-runtime-contract` (D=0, scaffolding)
|
||||
- `[ ]` Kafka consumer + inbox (신규 inbound leaf · DLT · backpressure) — `feature-kafka-consumer-inbox-contract` (D=0, scaffolding). **모듈 19→20 registry migration 동반**
|
||||
- `[ ]` MongoDB 런타임 baseline (concern · index manifest · change stream) — `feature-mongo-runtime-baseline-contract` (D=0, scaffolding). hub 최초 등록 (기존 row 자체가 부재했음)
|
||||
- `[ ]` Object storage 스트리밍·수명주기 (multipart · presigned · checksum) — `feature-objectstorage-streaming-lifecycle-contract` (D=0, scaffolding). `byte[]` 전용 `ObjectStoragePort` 대체
|
||||
|
||||
**Tier C — 능력 계약 (착수 시 주도권 이전 동반)**
|
||||
|
||||
- `[ ]` Cache 전략 registry (TTL 4종 · single-flight · SWR/stampede) — `feature-cache-strategy-registry-contract` (D=0, scaffolding). 이전 ← cache-consistency(H3) · cachestore-router(H4)
|
||||
- `[ ]` Edge rate limit policy registry (알고리즘 6종 교체) — `feature-edge-rate-limit-policy-registry-contract` (D=0, scaffolding). 이전 ← rate-limit-idempotency(H2). 현재 코드는 `FIXED_WINDOW` 단일 · in-process
|
||||
- `[ ]` Session · 인증 모드 (`jwt | redis-session`) — `feature-session-auth-mode-contract` (D=0, scaffolding). 이전 ← security-operational-baseline(H7). hub 최초 등록 (기존 row 자체가 부재했음)
|
||||
- `[ ]` Idempotency owner token 프로토콜 — `feature-idempotency-ownership-protocol-contract` (D=0, scaffolding). 이전 ← rate-limit-idempotency(H1). 현재 port 에 owner token 없음
|
||||
- `[ ]` Fenced lock · coordination primitive — `feature-fenced-lock-coordination-contract` (D=0, scaffolding). 이전 ← [[raw/branch-notes/feature-distributed-lock-contract]] (H5 — 대상 D-row 는 §25 Owner Map 참조)
|
||||
- `[ ]` Outbox dispatch mode (불변 event + polling|cdc) — `feature-outbox-dispatch-mode-contract` (D=0, scaffolding). 이전 ← domain-event-outbox(H6). 현재 가변 status row 는 Debezium Outbox Router 와 비호환
|
||||
|
||||
**Tier X — 전송·조회**
|
||||
|
||||
- `[ ]` GraphQL 운영 baseline (depth/complexity · persisted · DataLoader) — `feature-graphql-production-baseline-contract` (D=0, scaffolding). hub 최초 등록 (기존 row 자체가 부재했음)
|
||||
- `[ ]` gRPC 운영 baseline (proto 호환 · mTLS · deadline · backpressure) — `feature-grpc-production-baseline-contract` (D=0, scaffolding). hub 최초 등록 (기존 row 자체가 부재했음)
|
||||
- `[ ]` WebSocket cluster 전달 (handshake 인증 · bounded queue · broker relay) — `feature-websocket-cluster-delivery-contract` (D=0, scaffolding). hub 최초 등록 (기존 row 자체가 부재했음). in-process simple broker 는 R1 고정
|
||||
- `[ ]` 조회 일관성 · replica 라우팅 (`ReadConsistency` · cursor · lag) — `feature-read-consistency-query-contract` (D=0, scaffolding)
|
||||
- `[ ]` Notification durable 전달 (template 버전 · receipt · dedupe) — `feature-notification-durable-delivery-contract` (D=0, scaffolding)
|
||||
|
||||
### E. 신규 branch 권고 (우선순위 9개)
|
||||
|
||||
사용자 18항 + 9 보강 분석 결과의 통합 우선순위. 박을 시점은 본 branch 가 *현재 결정에 영향* 을 주거나 *코드 작성 중 막힐* 때.
|
||||
@@ -2778,12 +3009,12 @@ sequenceDiagram
|
||||
|
||||
### 현재 우선순위 (진행 가능 순서)
|
||||
|
||||
**현재 분포 요약** (46 ca-skeleton branches + 9 신규 권고 + 11 미래 후보):
|
||||
**현재 분포 요약** (2026-07-28 갱신 — **64** ca-skeleton branches = 기존 46 + Production Capability 18 · + 8 신규 권고 · + 11 미래 후보):
|
||||
|
||||
- `[x]` 3개 (locally-verified 이상): `feature-skeleton-package-blueprint-contract`, `feature-architecture-enforcement-rules`, `feature-application-port-usecase-contract`
|
||||
- `[*]` 4개 (partial implementation): `feature-boundary-validation-mapping-contract`, `feature-domain-feature-onboarding-contract`, `feature-sample-removal-adoption-contract`, `feature-implementation-readiness-scorecard`
|
||||
- `[~]` 37개 (결정 박힘, 코드 없음): 대부분 — D-row 평균 9~12개
|
||||
- `[ ]` 2개 (scaffolding only): `feature-webhook-outbound-contract`, `feature-streaming-response-contract`
|
||||
- `[*]` 9개 (partial implementation): `feature-boundary-validation-mapping-contract`, `feature-domain-feature-onboarding-contract`, `feature-sample-removal-adoption-contract`, `feature-implementation-readiness-scorecard`, **+ 2026-07-28 상태 정정 3개** `feature-cache-consistency-contract`·`feature-outbound-http-client-baseline`·`feature-file-resource-handling-contract`, **+ 신규 2개** `feature-redis-runtime-role-isolation-contract`·`feature-redis-atomic-program-catalog-contract`
|
||||
- `[~]` 34개 (결정 박힘, 코드 없음): D-row 평균 9~12개 (이전 37개 중 3개가 `[*]` 로 승급)
|
||||
- `[ ]` 18개 (scaffolding only): `feature-webhook-outbound-contract`, `feature-streaming-response-contract` + **Production Capability 16개** (§F-CAP 중 Redis foundation 2개 제외 전부)
|
||||
- `(없음)` 8개 (신규 branch 권고, E 영역): template-instantiation / static-analysis / dependency-vulnerability / database-connection-pool / authn-authz / runtime-context / persistence-auditing / distributed-lock — (query-bypass 는 2026-06-05 scaffold+구현 완료로 제외, `[x]` locally-verified 로 승급)
|
||||
- `(없음)` 11개 (미래 후보, F 영역): backup-restore / performance-load / docs-publishing / local-dev-data / clock-injection / i18n / money-decimal / search / notification / saga / soft-delete
|
||||
|
||||
@@ -2854,6 +3085,34 @@ ca-skeleton 은 *단일 stack 커밋* 을 채택합니다. 다중 DB / 다중
|
||||
| Architecture test | archunit-junit5 | 1.3.0 | D17 ArchUnit rule suite (resource-identifier branch + boundary branch) |
|
||||
| Random source | `java.security.SecureRandom` | Java 21 | ULID generator + idempotency key + token generation 의 의무 random source |
|
||||
|
||||
### Optional Adapter Stack Matrix (2026-07-28 신설)
|
||||
|
||||
> owner 결정: `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-STACK-OPTIONAL-ADAPTER-001@1`. **core Stack Matrix 는 그대로다** — 아래는 §1.1 capability 가 활성화됐을 때만 classpath 와 런타임에 등장하는 축이다. "축마다 구현체 하나" 라는 위 단일 stack 정신을 optional 축에도 동일 적용한다.
|
||||
>
|
||||
> `상태` 열: **존재** = 이미 의존성이 pin 되어 있음 / `도입 예정` = capability branch 착수 시 추가 / `opt-in 설정만` = 설정 골격만 있고 운영 계약 없음.
|
||||
|
||||
| Capability 축 | 선택 | 버전 | 상태 | 비고 |
|
||||
|---|---|---|---|---|
|
||||
| Redis client | Lettuce (Spring Data Redis) | Spring Boot BOM transitive | 도입 예정 | `LettuceRedisRuntime` 골격은 존재하나 SDK 의존성 추가는 후속. owner `feature-redis-runtime-role-isolation-contract` |
|
||||
| Session store | Spring Session Data Redis | Spring Boot BOM transitive | 도입 예정 | `redis-session` 모드 활성 시에만. owner `feature-session-auth-mode-contract` |
|
||||
| Kafka client | spring-kafka | Spring Boot BOM transitive | 도입 예정 | producer 먼저, consumer 는 신규 inbound leaf |
|
||||
| CDC | Debezium + Kafka Connect | 배포 자산 | 도입 예정 | **애플리케이션 의존성 아님.** connector 는 외부 배포·통합 test 자산 |
|
||||
| MongoDB | Spring Data MongoDB | Spring Boot BOM transitive | opt-in 설정만 | replica-set 요건 검증 필요 |
|
||||
| Object storage | AWS SDK v2 | `2.30.0` (`ext.awsSdkVersion`) | **존재** | Boot BOM 미관리 → 모듈 scope BOM import |
|
||||
| gRPC | io.grpc + protobuf | `1.68.1` (`ext.grpcVersion`) | **존재** | Boot BOM 미관리 → 모듈 scope BOM import |
|
||||
| GraphQL | Spring for GraphQL | Spring Boot BOM transitive | 최소 구현 존재 | production gate(depth/complexity/persisted) 미도입 |
|
||||
| Resilience | Resilience4j | — | **존재** | core 결정 `RESILIENCE-001` 유지 |
|
||||
| 통합 test | Testcontainers (+ Toxiproxy) | test scope | 부분 존재 | `TESTCONTAINERS-001` 정책 상속 |
|
||||
|
||||
**Out of Stack (optional 축) — 명시적 거부:**
|
||||
|
||||
- **lock/coordination**: Redisson 을 lock provider *기본* 으로 삼지 않는다. Spring Integration `LockRegistry` 계열(JDBC/Redis)이 기본이며 Redisson 은 대안. ZooKeeper / etcd / Consul 은 범위 밖.
|
||||
- **messaging**: RabbitMQ / Pulsar / ActiveMQ 는 범위 밖. Redis Streams 는 Kafka 대체재가 아니라 후속 소규모 provider 후보.
|
||||
- **cache**: Ehcache / Hazelcast / Infinispan 은 범위 밖. L1 local cache 는 Caffeine.
|
||||
- **search**: Elasticsearch / OpenSearch 는 범위 밖 (§35 F 영역 유지).
|
||||
|
||||
optional 축의 변경도 아래 "Stack 변경 절차" 4단계를 그대로 따른다.
|
||||
|
||||
### Cross-Branch 상속 패턴
|
||||
|
||||
각 branch 의 §결정 사항 / §Decision Evidence Map / §구현 가이드 가 stack 관련 결정 시 본 § 를 *reference* 만 하고 *재선언하지 않음*. 예시:
|
||||
@@ -2888,3 +3147,63 @@ ca-skeleton 은 *단일 stack 커밋* 을 채택합니다. 다중 DB / 다중
|
||||
- **Test framework**: TestNG / Spock — JUnit 5 단일
|
||||
|
||||
도메인이 위 alternative 를 요구할 경우 본 § 를 갱신 (cascade) 또는 별도 project-fork.
|
||||
|
||||
## 36. Capability Readiness Model (2026-07-28 신설)
|
||||
|
||||
> owner: [[raw/branch-notes/feature-capability-provider-selection-contract]] · 결정: `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-READINESS-001@1`, `DEC-CA-SKELETON-OPERATIONAL-CONTRACT-CAPABILITY-SELECTION-001@1`
|
||||
> 설계 SSOT: `docs/superpowers/specs/2026-07-28-ca-skeleton-production-capability-feature-decomposition-design.md` §6
|
||||
> 절 번호는 §35 뒤에 **덧붙였다** — 중간 삽입은 기존 문서·branch-note 의 절 참조를 어긋나게 한다.
|
||||
|
||||
### 36.1 Readiness 4단계
|
||||
|
||||
§1.1 의 "available by default, inactive by default" 를 판정 가능한 등급으로 만든다. seam 이 있다는 사실은 capability 가 운영 가능하다는 뜻이 아니다.
|
||||
|
||||
| 등급 | 의미 | 필요한 증거 | CLAUDE.md §6 등급 대응 |
|
||||
|---|---|---|---|
|
||||
| `R0` Contract | 타입·seam·placeholder 만 존재 | unit test + architecture boundary test | `planned` 또는 `documented-only` |
|
||||
| `R1` Local | 단일 로컬 프로세스/로컬 서비스에서 동작 | 집중 통합 test + 한계 문서화 | `actually-implemented` (partial) |
|
||||
| `R2` Production baseline | 실제 provider, 안전한 설정, 실패 의미, health, metric, 보안, graceful lifecycle | provider 계약 test + 실서비스 통합 + 동시성/실패 test + runbook | `locally-verified` |
|
||||
| `R3` Scale/HA | cluster·failover·rolling upgrade 검증 | topology test + 호환 매트릭스 + 복구/용량 runbook | `prod-verified` |
|
||||
|
||||
**금지 (§2 에 등록):** R0 seam 을 R2 provider 로 표기하는 것. 문서·startup 진단·capability card 모두에 적용된다.
|
||||
|
||||
### 36.2 Capability card 필수 항목
|
||||
|
||||
R2 이상을 주장하는 capability 는 owner branch-note 에 아래를 갖춘 card 를 보유한다.
|
||||
|
||||
```text
|
||||
owner 모듈 · semantic port
|
||||
provider ID 와 readiness 등급
|
||||
보증(guarantee)과 명시적 비보증(non-guarantee)
|
||||
기본 실패 정책과 허용되는 override (§11 실패 정책 매트릭스와 일치)
|
||||
필요한 토폴로지 · 영속/축출 정책
|
||||
설정 키와 secret
|
||||
liveness/readiness 영향
|
||||
bounded cardinality metric 과 trace span
|
||||
적합/부적합 지침 · 비용 모델 · 자원 한계
|
||||
흔한 unsafe recipe · 그것이 만드는 경합/실패 · 안전한 대체
|
||||
집중/통합/실패 test 명령
|
||||
rolling upgrade · 복구 노트
|
||||
runbook 링크
|
||||
```
|
||||
|
||||
**"흔한 unsafe recipe ↔ 안전한 대체" 항목이 §1.1 의 교육적 요구를 계약으로 고정하는 장치다.** 예: `GET → 판단 → INCR → EXPIRE` 는 개별 명령이 직렬화되더라도 클라이언트 사이 인터리빙이 가능하므로 원자적이지 않다 — card 는 이 recipe 와 그 대체(단일 atomic program)를 쌍으로 제시하고, provider 는 그 경합을 재현하는 test 를 통과해야 card 에 보증을 쓸 수 있다.
|
||||
|
||||
승급 게이트: §26 Universal Acceptance Gate 10문항 + §23 promotion contract 6필드에 더해, capability branch 는 (1) 보증과 비보증이 **둘 다** 작성되어 있을 것, (2) 주장하는 동시성·실패 의미를 증명하는 **경합 test 이름**이 명시되어 있을 것.
|
||||
|
||||
### 36.3 활성화 SSOT
|
||||
|
||||
```text
|
||||
provider: disabled | <provider-id> # 선택 가능한 capability
|
||||
dispatch-mode: disabled | polling | cdc # 모드 축이 있는 capability (outbox)
|
||||
enabled: true | false # provider·mode 축이 없는 leaf 에만
|
||||
```
|
||||
|
||||
규범:
|
||||
|
||||
- `matchIfMissing=true`, classpath 존재, local provider 기본값이 production capability 를 활성화해서는 **안 된다**.
|
||||
- 미사용 capability 는 연결·백그라운드 워커·스키마·암묵적 런타임 동작을 만들지 **않는다**.
|
||||
- legacy flag 를 한시적으로 유지하는 경우, SSOT 와의 불일치는 **startup 오류**다.
|
||||
- 활성화·안전 판정은 **bean 이름이 아니라 typed descriptor** 로 한다. 현재 ca-tmpl `StartupSafetyValidator` 는 bean 이름 문자열 목록(`distributedLockProvider`·`cacheStampedeProtection`·`outboxLeaderElection`·`distributedRateLimiter`·`migrationStartupRunner` 5개)으로 multi-instance 안전을 판정하므로, 그 이름의 아무 bean 이나 존재하면 안전으로 보고된다 — `feature-capability-provider-selection-contract` 의 교체 대상.
|
||||
|
||||
capability descriptor 최소 필드: `capabilityId`, `providerId`, readiness 등급, guarantee class, failure mode, multi-instance 지원, 필요한 backing role, readiness 영향, 구현 버전.
|
||||
|
||||
Reference in New Issue
Block a user