@rscc/common-core 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,10 @@
 # @rscc/common-core
 
-RSCC 공통 코어 — `CommonResponse` 봉투 타입, API 클라이언트 팩토리(traceId 발신/에코), SSE 프레임 파서, JWT 디코더, 시크릿 마스킹 유틸. **프레임워크 무관, 런타임 의존성 0.**
+RSCC 공통 코어 — `CommonResponse` 봉투 타입과 API 클라이언트(traceId·재시도·멱등성 키), SSE 파서,
+회복탄력성 유틸(retry·서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시), 보안 유틸(마스킹·로그 리댁션·
+웹훅 서명·JWT 디코드), 와이어 계약 헬퍼(날짜·목록 쿼리·벌크·업로드·피처 플래그), 한국 도메인 유틸.
+**프레임워크 무관, 런타임 의존성 0.** 같은 라이브러리의 Java·Python 구현과 동일한 와이어 계약·공유
+테스트 벡터로 시맨틱을 맞춘다.
 
 ## 설치
 
@@ -8,43 +12,107 @@ RSCC 공통 코어 — `CommonResponse` 봉투 타입, API 클라이언트 팩
 npm i @rscc/common-core
 ```
 
-- **Node >= 18** (전역 `fetch` / `Headers` / `ReadableStream` 전제)
+- **Node >= 18** 또는 모던 브라우저 (전역 `fetch` / `Headers` / `ReadableStream` / `crypto.subtle` 전제)
 - ESM + CJS 듀얼 빌드, 타입 선언(`.d.ts` / `.d.cts`) 동봉, `sideEffects: false`
+- 메인 엔트리 `@rscc/common-core` 는 브라우저 안전. Node 전용 기능은 서브패스 `@rscc/common-core/crypto` 로만 제공
 
-## 공개 API
+## 모듈 한눈에
 
 | 모듈 | 공개 API | 설명 |
 |---|---|---|
-| types | `CommonResponse<T>` · `PageResponse<T>` · `ResultCode` | 응답 봉투·페이지네이션(page 0 시작)·결과 코드(값은 문자열) |
-| apiClient | `createApiClient(config)` · `ApiError` · `ApiClient` · `ApiClientConfig` · `ApiResult<T>` | 봉투 언랩 · 401 콜백 · `X-Trace-Id` 발신/에코 |
-| sse | `parseSseFrame` · `readSseStream` · `SseFrameEvent` · `SseSource` · `SseCallbacks` | SSE 프레임 파싱 — 청크/멀티바이트 경계 안전, 모르는 키는 skip |
+| types | `CommonResponse<T>` · `PageResponse<T>` · `ResultCode` · `FieldErrorDetail` · `ValidationErrorData` · `isValidationErrorData` | 응답 봉투 · 페이지(page 0 시작) · 결과 코드(값은 문자열) · 검증 오류 봉투 타입 가드 |
+| apiClient | `createApiClient` · `ApiError` · `ApiClient` · `ApiClientConfig` · `ApiClientRetryOptions` · `ApiResult<T>` · `ApiRequestInfo` / `ApiResponseInfo` / `ApiErrorInfo` | 봉투 언랩 · 401 콜백 · `X-Trace-Id` 발신/에코 · opt-in 재시도/멱등성 키/`strictJson`/관측 훅 |
+| sse | `parseSseFrame` · `readSseStream` · `SseFrameEvent` · `SseSource` · `SseCallbacks` | SSE 프레임 파싱 — 청크·멀티바이트 경계 안전, 모르는 키는 skip |
 | jwt | `decodeJwtPayload` · `getTokenExpiry` · `isTokenExpired` | base64url 디코드만 — **서명 미검증**, 만료 판단은 fail-closed |
-| masking | `maskSecret` | 앞4+뒤4 노출, 8자 이하 전량 마스킹 (java `MaskingUtils` 와 동일 규칙) |
+| masking | `maskSecret` · `maskName` · `maskPhone` · `maskEmail` · `maskCardNumber` | 시크릿(앞4+뒤4)·이름·휴대폰·이메일·카드번호 마스킹 |
+| datetime | `toWireDateTime` · `toWireDate` · `parseWireDateTime` · `stripZone` | 오프셋 없는 LocalDateTime 와이어 형식 — `toISOString()`(Z) 의 9시간 스큐 차단 |
+| chosung | `toChosung` · `isChosungQuery` | 한글 초성 변환·초성 질의 판별 (자동완성) |
+| retry | `retry` · `isRetryableStatus` · `parseRetryAfterMs` · `RetryOptions` | 지수 백오프 + full jitter, 시간 예산, `Retry-After` 파싱 |
+| cache | `createTtlCache` · `TtlCache<K,V>` · `TtlCacheOptions` | TTL 캐시 + single-flight(동일 키 로더 1회 공유), lazy expiry |
+| circuitBreaker | `createCircuitBreaker` · `CircuitOpenError` · `CircuitBreaker` · `CircuitBreakerOptions` · `CircuitState` | 연속 실패 서킷 브레이커 — `execute(fn)` 권장, 취소는 무집계(`onIgnore`) |
+| tokenBucket | `createTokenBucket` · `TokenBucket` · `TokenBucketOptions` | 토큰버킷 레이트리미터 (연속 리필, 대기 없이 즉시 판정) |
+| bulkhead | `createBulkhead` · `BulkheadFullError` · `Bulkhead` · `BulkheadOptions` | 동시 실행 + 대기 슬롯 격벽, 만석 즉시 거부 |
+| logSanitize | `sanitizeLogValue` | 로그 인젝션 방지 — 제어 문자 공백 치환 + 길이 절단 |
+| bizno | `normalizeBusinessNumber` · `isValidBusinessNumber` · `isValidCorporateNumber` | 사업자(10)·법인(13)번호 체크섬 검증 |
+| idempotency | `generateIdempotencyKey` | 멱등성 키 생성 (apiClient `idempotency` 옵션으로 자동 부착 가능) |
+| webhook | `signWebhook` · `verifyWebhook` · `WEBHOOK_SIGNATURE_HEADER` | HMAC-SHA256 웹훅 서명/검증 (WebCrypto — async), 시크릿 로테이션 |
+| bulk | `isBulkResult` · `bulkFailures` · `createBulkResultBuilder` · `BulkResult` · `BulkResultItem` · `BulkResultBuilder` | 벌크/부분 실패 봉투 판별·생성 |
+| upload | `sniffFile` · `kindsForExtension` · `validateUpload` · `FileKind` · `UploadValidationResult` | 업로드 프리검증 — 크기·확장자·매직바이트 대조 |
+| query | `buildListQuery` · `ListQueryOptions` · `SortParam` | 목록 조회 쿼리(page/size/sort/필터) 빌더 |
+| featureFlags | `parseFlag` · `createFeatureFlags` · `FeatureFlagReader` | 피처 플래그 파싱 (참 집합 `true`/`1`/`on`/`yes`) |
+| rrn | `normalizeRrn` · `isValidRrn` · `isForeignerRrn` · `rrnChecksumOkLegacy` · `rrnBirthDate` | 주민등록번호 형식·생년월일 검증 (기본 검증은 **체크섬 미포함**) |
+| josa | `pickJosa` · `attachJosa` · `JosaPair` | 은/는·이/가 등 조사 자동 선택 |
+| age | `ageMan` · `ageByYear` · `ageInsurance` | 만 나이·연 나이·보험 나이 (입력 `"YYYY-MM-DD"` 문자열) |
+| phone | `normalizePhoneNumber` · `classifyPhoneNumber` · `formatPhoneNumber` · `toE164` · `PhoneType` | 전화번호 정규화·분류·포맷·E.164 변환 |
+| money | `toKoreanWords` · `toFormalNotation` · `abbreviateAmount` | 금액 한글 수사 · 공문서 표기(`금…원整`) · UI 약식(`1.2억`) |
+| businessDays | `createBusinessDays` · `BusinessDays` · `BusinessDaysOptions` | 영업일 계산 (공휴일 주입형 — 내장 공휴일 없음) |
+| jamo | `decomposeHangul` · `composeHangul` · `matchesHangul` | 두벌식 자모 분해·조합·혼합 질의 매칭 |
+| **crypto (서브패스)** | `encryptAesGcm` · `decryptAesGcm` · `CryptoError` — `@rscc/common-core/crypto` | AES-256/GCM (Java/Python 와이어 호환). **Node 전용** (`node:crypto`) |
 
 ## 사용 예시
 
 ### createApiClient — CommonResponse 언랩 + traceId
 
 ```ts
-import { createApiClient, ApiError } from "@rscc/common-core";
+import { createApiClient, ApiError, isValidationErrorData } from "@rscc/common-core";
 
 const api = createApiClient({
-  baseUrl: "https://api.example.com",              // 끝 슬래시 없이
-  getToken: () => localStorage.getItem("token"),  // 선택 — Authorization: Bearer 부착
+  baseUrl: "https://api.example.com",             // 끝 슬래시 유무 무관 — 경계 슬래시 자동 단일화
+  getToken: () => sessionStorage.getItem("token"), // 선택 — Authorization: Bearer 부착
   onUnauthorized: () => { /* 로그아웃/리다이렉트 정책은 소비자가 결정 */ },
+  // 선택: retry: { retries: 3 }, idempotency: {}, strictJson: true, onRequest/onResponse/onError
 });
 
-// 성공 봉투 → data 언랩
+// 성공 봉투 → data 언랩 (비봉투 JSON 은 그대로)
 const user = await api.request<UserInfo>("/api/v1/users/me");
 
-// 실패 봉투/HTTP 에러 → ApiError { code, message, status, traceId }
+// 문자열 body → Content-Type: application/json 자동 부착
+await api.request("/api/v1/items", { method: "POST", body: JSON.stringify(item) });
+
+// 실패 봉투/HTTP 에러 → ApiError { code, message, status, traceId, data, retryAfterMs }
 try {
   await api.request("/api/v1/things/999");
 } catch (e) {
-  if (e instanceof ApiError) console.error(`[${e.traceId}] ${e.code}: ${e.message}`);
+  if (e instanceof ApiError) {
+    console.error(`[${e.traceId}] ${e.code}: ${e.message}`);
+    if (isValidationErrorData(e.data)) { /* e.data.errors — 필드별 검증 오류 */ }
+  }
 }
+
+// traceId·status·원본 Response 가 필요하면
+const { data, traceId, response } = await api.requestWithMeta<UserInfo>("/api/v1/users/me");
+```
+
+- **Content-Type**: 호출자가 지정하지 않았고 body 가 **문자열**일 때만 `application/json` 을 붙인다.
+  body 없는 요청(GET 등)엔 붙이지 않으므로 교차 출처 GET 이 CORS preflight 를 유발하지 않는다.
+  `URLSearchParams`/`Blob`/`FormData`/`ArrayBuffer`/`ReadableStream` 은 fetch 기본값을 따른다.
+- **traceId**: 논리 호출당 1회 생성해 `X-Trace-Id` 로 부착(재시도 전 시도 동일), 응답 에코를 우선 노출.
+- **retry** (opt-in): 멱등 메서드(GET/HEAD/OPTIONS/PUT/DELETE)만 기본 재시도, 408/429/5xx 일부·네트워크
+  오류 대상, `Retry-After` 를 대기 하한으로 존중. POST/PATCH 는 `methods` 로 명시 옵트인.
+- **idempotency** (opt-in): POST/PATCH 에 `Idempotency-Key` 를 논리 호출당 1회 생성해 부착(호출자 헤더 우선).
+- **strictJson** (opt-in): 2xx 의 비-JSON 본문을 null 대신 `INVALID_JSON` ApiError 로 실패(`rawText` 앞 2048자
+  보존). 빈 본문(204 등)은 계속 null.
+- `requestWithMeta` 의 `response` 는 **본문 미소비 원본** — 파싱은 `clone()` 사본으로 하므로 `text()`/`json()`
+  재호출이 가능하다.
+
+### 서킷 브레이커 — execute 권장
+
+```ts
+import { createCircuitBreaker, CircuitOpenError, retry } from "@rscc/common-core";
+
+const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
+
+// 게이트 → 실행 → 결과 보고를 정확히 1회 보장. OPEN 이면 fn 미호출 + CircuitOpenError
+await retry(() => cb.execute(() => api.request("/api/v1/downstream")), {
+  shouldRetry: (e) => !(e instanceof CircuitOpenError), // OPEN 차단은 즉시 실패
+});
 ```
 
+- resolve → 성공, `name === "AbortError"` → 무집계(`onIgnore`), 그 외 throw → 실패로 집계 후 **같은 오류를 그대로** rethrow.
+- 수동 게이트(`allowRequest()` + `onSuccess`/`onFailure`/`onIgnore` 중 정확히 1회)도 지원한다.
+- 보고가 끝내 오지 않은 그랜트는 OPEN 진입 후 `2 × openDurationMs` 에 유실로 용서되어 OPEN 영구 고착을 막는다.
+  HALF_OPEN 프로브도 `openDurationMs` 동안 미보고면 유실로 간주해 새 프로브를 넘긴다(HALF_OPEN 고착 방지).
+
 ### SSE 스트림 소비
 
 ```ts
@@ -52,24 +120,38 @@ import { readSseStream } from "@rscc/common-core";
 
 const res = await fetch(streamUrl, { method: "POST", body, signal });
 await readSseStream(res, {
-  onDelta: (chunk) => { /* 텍스트 증분 */ },
+  onConversationId: (id) => { /* 첫 프레임 */ },
   onSources: (sources) => { /* RAG 근거 */ },
+  onDelta: (chunk) => { /* 텍스트 증분 */ },
   onError: (message) => { /* in-band 오류 */ },
   onDone: () => { /* data: [DONE] */ },
 });
 ```
 
+### AES-256/GCM — Node 전용 서브패스
+
+```ts
+import { encryptAesGcm, decryptAesGcm, CryptoError } from "@rscc/common-core/crypto";
+
+const enc = encryptAesGcm("민감값", key); // Base64(IV(12B)∥암호문∥태그(16B)) — 매번 다름
+const dec = decryptAesGcm(enc, key);      // 키 상이·변조 시 CryptoError
+```
+
 ## 알려진 제약
 
-- SSE 파서는 프레임 구분자 **LF(`\n\n`) 고정** — CRLF 로 정규화하는 프록시 뒤에서는 프레임이 분리되지 않는다.
-- `baseUrl` 은 **끝 슬래시 없이** 지정할 것 — path 와 단순 연결하며 정규화하지 않는다.
-- `requestWithMeta` 의 `ApiResult.response` 는 body 가 이미 소비된 상태 — headers/status 조회용.
-- 2xx 응답인데 본문이 JSON 이 아니면 `data` 는 조용히 null 이 된다.
+- **SSE 파서는 프레임 구분자 LF(`\n\n`) 고정** — 개행을 CRLF 로 정규화하는 프록시 뒤에서는 프레임이 분리되지 않는다.
+- 2xx 응답인데 본문이 JSON 이 아니면 `data` 는 기본적으로 조용히 null 이 된다 — 명시 실패가 필요하면 `strictJson: true`.
+- 문자열 body 는 `application/json` 으로 간주된다 — JSON 이 아닌 문자열 본문은 Content-Type 을 직접 지정할 것.
+- 교차 출처에서 traceId 에코를 읽으려면 서버가 `Access-Control-Expose-Headers: X-Trace-Id` 를 내려야 한다
+  (못 읽으면 발신 값을 노출 — 서버가 수신 traceId 를 재사용하므로 동일 값).
+- 1회성 body(`ReadableStream`/`FormData`)는 재전송이 불가해 `retry` 를 지정해도 1회만 실행된다.
 - JWT 디코더는 **서명을 검증하지 않는다** — 표시·만료 판단 전용. 인가 판단은 반드시 서버에서.
+- `isValidRrn` 은 체크섬을 포함하지 않는다(2020-10 이후 발급분은 체크섬 불성립) — `rrnChecksumOkLegacy` 는 레거시 정합 검사 전용.
+- `signWebhook`/`verifyWebhook` 은 WebCrypto 기반이라 **async** 다 (Java/Python 은 동기).
+- 서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시는 **인스턴스(프로세스) 로컬** 상태다 — 분산 공유되지 않는다.
+- `@rscc/common-core/crypto` 는 `node:crypto` 를 쓰는 **Node 전용** 서브패스 — 브라우저 번들에 포함하지 말 것.
 
-## 문서 / 저장소
+## 관련 패키지
 
-- 상세 문서: [js/README.md](https://github.com/Jeonghyeon-Ryu/r-common/blob/master/js/README.md)
-- 와이어 계약(단일 소스): [contracts/](https://github.com/Jeonghyeon-Ryu/r-common/tree/master/contracts)
-- React 훅: [@rscc/common-react](https://www.npmjs.com/package/@rscc/common-react)
-- 저장소: [Jeonghyeon-Ryu/r-common](https://github.com/Jeonghyeon-Ryu/r-common) · MIT
+- React 훅(`useDebounce`, `useSse`): [@rscc/common-react](https://www.npmjs.com/package/@rscc/common-react)
+- 라이선스: MIT

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   ApiError: () => ApiError,
   BulkheadFullError: () => BulkheadFullError,
+  CircuitOpenError: () => CircuitOpenError,
   ResultCode: () => ResultCode,
   WEBHOOK_SIGNATURE_HEADER: () => WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount: () => abbreviateAmount,
@@ -262,8 +263,7 @@ function createApiClient(config) {
       if (idempotencyKey !== null && !headers.has(idempotencyHeader)) {
         headers.set(idempotencyHeader, idempotencyKey);
       }
-      const isFormData = typeof FormData !== "undefined" && init.body instanceof FormData;
-      if (!headers.has("Content-Type") && !isFormData) {
+      if (!headers.has("Content-Type") && typeof init.body === "string") {
         headers.set("Content-Type", "application/json");
       }
       if (config.getToken && !headers.has("Authorization")) {
@@ -685,6 +685,12 @@ function createTtlCache(options) {
 }
 
 // src/circuitBreaker.ts
+var CircuitOpenError = class extends Error {
+  constructor(message = "\uC11C\uD0B7 OPEN \u2014 \uC694\uCCAD \uCC28\uB2E8") {
+    super(message);
+    this.name = "CircuitOpenError";
+  }
+};
 function createCircuitBreaker(options) {
   const { failureThreshold, openDurationMs, now = Date.now } = options;
   if (!Number.isInteger(failureThreshold) || failureThreshold <= 0) {
@@ -697,6 +703,7 @@ function createCircuitBreaker(options) {
   let consecutiveFailures = 0;
   let openedAtMs = 0;
   let probeInFlight = false;
+  let probeStartedAtMs = 0;
   let inFlightGrants = 0;
   function allowRequest() {
     if (state === "CLOSED") {
@@ -704,18 +711,24 @@ function createCircuitBreaker(options) {
       return true;
     }
     if (state === "OPEN") {
-      if (now() - openedAtMs >= openDurationMs) {
-        if (inFlightGrants > 0) {
+      const nowMs2 = now();
+      const elapsedMs = nowMs2 - openedAtMs;
+      if (elapsedMs < openDurationMs) return false;
+      if (inFlightGrants > 0) {
+        if (elapsedMs < 2 * openDurationMs) {
           return false;
         }
-        state = "HALF_OPEN";
-        probeInFlight = true;
-        return true;
+        inFlightGrants = 0;
       }
-      return false;
+      state = "HALF_OPEN";
+      probeInFlight = true;
+      probeStartedAtMs = nowMs2;
+      return true;
     }
-    if (probeInFlight) return false;
+    const nowMs = now();
+    if (probeInFlight && nowMs - probeStartedAtMs < openDurationMs) return false;
     probeInFlight = true;
+    probeStartedAtMs = nowMs;
     return true;
   }
   function onSuccess() {
@@ -750,13 +763,40 @@ function createCircuitBreaker(options) {
     }
     inFlightGrants = Math.max(0, inFlightGrants - 1);
   }
+  function onIgnore() {
+    if (state === "HALF_OPEN") {
+      probeInFlight = false;
+      return;
+    }
+    inFlightGrants = Math.max(0, inFlightGrants - 1);
+  }
+  async function execute(fn) {
+    if (!allowRequest()) {
+      throw new CircuitOpenError();
+    }
+    let result;
+    try {
+      result = await fn();
+    } catch (error) {
+      if (isAbortError(error)) onIgnore();
+      else onFailure();
+      throw error;
+    }
+    onSuccess();
+    return result;
+  }
   return {
     allowRequest,
     onSuccess,
     onFailure,
+    onIgnore,
+    execute,
     state: () => state
   };
 }
+function isAbortError(error) {
+  return typeof error === "object" && error !== null && error.name === "AbortError";
+}
 
 // src/tokenBucket.ts
 function createTokenBucket(options) {
@@ -1738,6 +1778,7 @@ function matchesHangul(query, target) {
 0 && (module.exports = {
   ApiError,
   BulkheadFullError,
+  CircuitOpenError,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,

package/dist/index.d.cts

@@ -315,6 +315,11 @@ interface ApiClient {
  *
  * 동작 (contracts/common-response.schema.json, trace.md):
  * - 매 요청에 traceId 를 생성해 traceIdHeader(기본 X-Trace-Id)로 부착한다.
+ * - `Content-Type: application/json` 은 호출자가 Content-Type 을 지정하지 않았고 body 가
+ *   **문자열**일 때만 기본 부착한다 (JSON.stringify 관용). body 없는 요청(GET 등)엔 붙이지
+ *   않아 교차 출처 GET 의 CORS preflight 를 유발하지 않으며, URLSearchParams/Blob/FormData/
+ *   ArrayBuffer/ReadableStream 등은 fetch 기본값에 맡긴다. 문자열이지만 JSON 이 아닌 본문은
+ *   Content-Type 을 직접 지정할 것.
  * - 응답이 CommonResponse 봉투면 success 검사 후 data 를 언랩한다
  *   (data 부재 시 undefined). 비봉투 JSON 은 그대로 반환.
  * - 실패 봉투 / HTTP 에러는 code·message·traceId 를 담은 ApiError 를 throw.
@@ -575,9 +580,13 @@ declare function createTtlCache<K, V>(options: TtlCacheOptions): TtlCache<K, V>;
  * 경량 서킷 브레이커. 런타임 의존성 0 (native 만).
  *
  * Java `com.rscc.common.util.CircuitBreaker` / Python `rscc_common.circuit_breaker` 와
- * 시맨틱 동일 (3언어 공유 벡터 CB-01~09 — 각 언어 테스트에 수동 동기화. Python 은
+ * 시맨틱 동일 (3언어 공유 벡터 CB-01~13 — 각 언어 테스트에 수동 동기화. Python 은
  * 시간 단위가 초 — `초 × 1000 == ms`).
  *
+ * - **권장 사용법 — `execute(fn)`**: 게이트(allowRequest) → 실행 → 결과 보고를 한 번에
+ *   처리해 보고를 **정확히 1회** 보장한다. 차단 시 {@link CircuitOpenError} 로 reject
+ *   (fn 미호출), 취소(`name === "AbortError"`)는 성공·실패 어느 쪽에도 집계하지 않는다
+ *   (onIgnore — CB-12). 수동 게이트(allowRequest + 보고)는 execute 로 감쌀 수 없는 경우에만.
  * - **연속(consecutive) 실패 카운트**: `onFailure()` 가 failureThreshold 에 도달(`>=`)하면
  *   OPEN. `onSuccess()` 는 카운터를 0 으로 리셋한다 (슬라이딩 윈도 비채택 — 단순성).
  * - **lazy 전이**: OPEN → HALF_OPEN 전이는 `allowRequest()` 호출 시점에 판정한다
@@ -586,38 +595,51 @@ declare function createTtlCache<K, V>(options: TtlCacheOptions): TtlCache<K, V>;
  * - **HALF_OPEN 프로브 1개**: 프로브가 진행 중이면 나머지 `allowRequest()` 는 false.
  *   프로브 성공 → CLOSED(카운터 0), 프로브 실패 → OPEN 재진입(openedAt 갱신 —
  *   전체 openDurationMs 재대기).
- * - **결과 보고 규율**: `allowRequest()==true` 를 받은 호출만 `onSuccess()`/`onFailure()`
- *   를 **정확히 1회** 호출한다 (try/finally 로 보고 보장 권장 — 보고 누락은 아래 프로브
- *   보류를 무기한 지속시킨다). OPEN 대기 중 늦게 도착한 보고는 상태·openedAt·카운터를
- *   바꾸지 않고(no-op — CB-08) 미보고 그랜트 잔량만 소진한다.
+ * - **결과 보고 규율**: `allowRequest()==true` 를 받은 호출만 `onSuccess()`/`onFailure()`/
+ *   `onIgnore()` 중 하나를 **정확히 1회** 호출한다 (수동 게이트라면 try/catch 로 보고 보장 —
+ *   성공·실패로 판정할 수 없는 취소 등은 `onIgnore()` 로 그랜트만 반납). OPEN 대기 중 늦게
+ *   도착한 보고는 상태·openedAt·카운터를 바꾸지 않고(no-op — CB-08) 미보고 그랜트 잔량만
+ *   소진한다.
  * - **스테일 그랜트 격리**: CLOSED 시절 그랜트가 아직 보고되지 않은 동안에는
  *   openDurationMs 가 경과해도 HALF_OPEN 전이(프로브)가 보류된다 — 스테일 보고가 프로브
- *   결과로 오인되는 것을 막아 HALF_OPEN 중 도착하는 보고는 항상 프로브의 것이다 (CB-09).
+ *   결과로 오인되는 것을 막아 HALF_OPEN 중 도착하는 보고는 (아래 용서 이후의 매우 늦은
+ *   보고를 제외하면) 항상 프로브의 것이다 (CB-09).
+ * - **유실 그랜트 용서 (2× 규칙)**: 보고가 끝내 오지 않는 그랜트(보고 누락·유실)가 위 보류를
+ *   무기한 지속시켜 서킷이 OPEN 에 영구 고착되는 것을 막는다 — OPEN 진입 후
+ *   `2 × openDurationMs` 경과 시점에도 미보고 그랜트가 남아 있으면 이를 유실로 간주해 0 으로
+ *   용서하고 정상 HALF_OPEN 전이 + 프로브 획득을 수행한다 (CB-10). 용서 뒤 매우 늦은 스테일
+ *   보고가 HALF_OPEN 중 도착하면 프로브 결과로 취급되지만 무해하다 — 스테일 성공은 하류가
+ *   실제로 응답했다는 증거이고, 스테일 실패는 보수적인 OPEN 재진입일 뿐이다 (스테일
+ *   onIgnore 는 프로브 슬롯을 조기 해제해 프로브가 1개 더 허가될 뿐 — 최초 보고가 판정).
+ * - **유실 프로브 용서**: HALF_OPEN 프로브가 openDurationMs(`>=`) 동안 보고되지 않으면 유실로
+ *   간주해 다음 allowRequest() 에 새 프로브를 넘긴다 — 보고 누락 프로브 1개로 HALF_OPEN 에 영구
+ *   고착되는 것을 막는다 (CB-13). 옛 프로브의 늦은 보고는 새 프로브 결과로 취급되며 위와 같은
+ *   이유로 무해하다.
+ *
+ * @example 권장 — execute 로 게이트·보고를 위임한다.
+ * ```ts
+ * const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
+ * const user = await cb.execute(() => api.request<User>("/users/1")); // OPEN 이면 CircuitOpenError
+ * ```
  *
- * @example 서킷 + 재시도 조합 — 시도 직전 allowRequest 게이트, 결과를 브레이커에 보고.
- * OPEN 차단 오류는 shouldRetry 에서 비재시도로 걸러 즉시 실패시킨다(빠른 실패 유지).
+ * @example 서킷 + 재시도 조합 — 시도마다 execute 로 게이트·보고. OPEN 차단
+ * ({@link CircuitOpenError})은 shouldRetry 에서 비재시도로 걸러 즉시 실패시킨다(빠른 실패 유지).
  * ```ts
  * const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
- * const circuitOpen = new Error("서킷 OPEN — 요청 차단");
- * await retry(
- *   async () => {
- *     if (!cb.allowRequest()) throw circuitOpen;
- *     try {
- *       const r = await call();
- *       cb.onSuccess();
- *       return r;
- *     } catch (error) {
- *       cb.onFailure();
- *       throw error;
- *     }
- *   },
- *   {
- *     shouldRetry: (error) => error !== circuitOpen, // OPEN 차단은 즉시 실패
- *     onRetry: (error, attempt, delayMs) => console.warn(`재시도 ${attempt} (${delayMs}ms)`),
- *   }
- * );
+ * await retry(() => cb.execute(() => call()), {
+ *   shouldRetry: (error) => !(error instanceof CircuitOpenError), // OPEN 차단은 즉시 실패
+ *   onRetry: (error, attempt, delayMs) => console.warn(`재시도 ${attempt} (${delayMs}ms)`),
+ * });
  * ```
  */
+/**
+ * 서킷 차단 거부 오류 — `execute()` 가 allowRequest()==false(OPEN 대기·프로브 보류·HALF_OPEN
+ * 프로브 경합)일 때 reject 하며, 이때 작업 함수는 **호출되지 않는다** (CB-12).
+ * Java `CircuitOpenException` / Python `CircuitOpenError` 패리티. 재시도 조합에서 비재시도 신호로 쓴다.
+ */
+declare class CircuitOpenError extends Error {
+    constructor(message?: string);
+}
 type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
 interface CircuitBreakerOptions {
     /** OPEN 전이 임계 — 연속 실패가 이 값에 도달(`>=`)하면 OPEN. 필수 양의 정수 (아니면 RangeError). */
@@ -631,14 +653,32 @@ interface CircuitBreaker {
     /**
      * 요청 통과 여부 — CLOSED 는 true, OPEN 대기 중 false, openDurationMs 경과 시
      * HALF_OPEN 전이 + 프로브 슬롯 획득(true) — 단 CLOSED 시절 미보고 그랜트가 남아 있으면
-     * 전이를 보류하고 false (CB-09). HALF_OPEN 프로브 경합 시 나머지 false.
-     * true 를 받은 호출만 결과를 onSuccess()/onFailure() 로 보고해야 한다.
+     * 전이를 보류하고 false (CB-09), 보류는 OPEN 진입 후 `2 × openDurationMs` 까지만 —
+     * 그 시점엔 미보고 그랜트를 유실로 용서하고 전이 + 프로브 획득(true) (CB-10).
+     * HALF_OPEN 프로브 경합 시 나머지 false — 단 프로브가 openDurationMs 경과(`>=`)까지
+     * 미보고면 유실로 간주해 이 호출에 새 프로브를 넘긴다(true) (CB-13).
+     * true 를 받은 호출만 결과를 onSuccess()/onFailure()/onIgnore() 중 하나로 보고해야 한다.
      */
     allowRequest(): boolean;
     /** 성공 보고 — CLOSED 카운터 리셋, HALF_OPEN 프로브 성공 시 CLOSED 복귀. OPEN 중엔 무시. */
     onSuccess(): void;
     /** 실패 보고 — CLOSED 연속 카운트 증가(임계 도달 시 OPEN), HALF_OPEN 프로브 실패 시 OPEN 재진입. OPEN 중엔 무시. */
     onFailure(): void;
+    /**
+     * 결과 없는 그랜트 반납 — 취소(abort) 등 성공·실패로 판정할 수 없는 호출이 보고 대신
+     * 호출한다 (CB-11). CLOSED: 미보고 그랜트만 반납(연속 실패 카운터 무변화). HALF_OPEN:
+     * 프로브 슬롯 해제 — HALF_OPEN 유지, 다음 allowRequest() 가 새 프로브를 획득한다.
+     * OPEN: 미보고 그랜트 잔량만 소진(그 외 무변화).
+     */
+    onIgnore(): void;
+    /**
+     * fn 래핑 (권장 사용법) — allowRequest() 게이트 → 실행 → 결과 보고를 **정확히 1회** 보장한다.
+     * 거부는 reject(CircuitOpenError) — 동기 throw 아님, 거부 시 fn 은 호출되지 않는다.
+     * resolve → onSuccess() 후 값 반환. throw/reject 는 `name === "AbortError"` 면 onIgnore(),
+     * 그 외(TimeoutError 포함)는 onFailure() 후 **같은 값을 래핑 없이** 다시 throw 한다 (CB-12).
+     * fn 의 동기 throw 도 동일하게 처리된다.
+     */
+    execute<T>(fn: () => T | PromiseLike<T>): Promise<T>;
     /** 현재 상태 조회 — lazy 전이 특성상 openDurationMs 경과 후에도 allowRequest() 전엔 OPEN 으로 보고된다. */
     state(): CircuitState;
 }
@@ -1307,4 +1347,4 @@ declare function composeHangul(s: string): string;
  */
 declare function matchesHangul(query: string, target: string): boolean;
 
-export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };

package/dist/index.d.ts

@@ -315,6 +315,11 @@ interface ApiClient {
  *
  * 동작 (contracts/common-response.schema.json, trace.md):
  * - 매 요청에 traceId 를 생성해 traceIdHeader(기본 X-Trace-Id)로 부착한다.
+ * - `Content-Type: application/json` 은 호출자가 Content-Type 을 지정하지 않았고 body 가
+ *   **문자열**일 때만 기본 부착한다 (JSON.stringify 관용). body 없는 요청(GET 등)엔 붙이지
+ *   않아 교차 출처 GET 의 CORS preflight 를 유발하지 않으며, URLSearchParams/Blob/FormData/
+ *   ArrayBuffer/ReadableStream 등은 fetch 기본값에 맡긴다. 문자열이지만 JSON 이 아닌 본문은
+ *   Content-Type 을 직접 지정할 것.
  * - 응답이 CommonResponse 봉투면 success 검사 후 data 를 언랩한다
  *   (data 부재 시 undefined). 비봉투 JSON 은 그대로 반환.
  * - 실패 봉투 / HTTP 에러는 code·message·traceId 를 담은 ApiError 를 throw.
@@ -575,9 +580,13 @@ declare function createTtlCache<K, V>(options: TtlCacheOptions): TtlCache<K, V>;
  * 경량 서킷 브레이커. 런타임 의존성 0 (native 만).
  *
  * Java `com.rscc.common.util.CircuitBreaker` / Python `rscc_common.circuit_breaker` 와
- * 시맨틱 동일 (3언어 공유 벡터 CB-01~09 — 각 언어 테스트에 수동 동기화. Python 은
+ * 시맨틱 동일 (3언어 공유 벡터 CB-01~13 — 각 언어 테스트에 수동 동기화. Python 은
  * 시간 단위가 초 — `초 × 1000 == ms`).
  *
+ * - **권장 사용법 — `execute(fn)`**: 게이트(allowRequest) → 실행 → 결과 보고를 한 번에
+ *   처리해 보고를 **정확히 1회** 보장한다. 차단 시 {@link CircuitOpenError} 로 reject
+ *   (fn 미호출), 취소(`name === "AbortError"`)는 성공·실패 어느 쪽에도 집계하지 않는다
+ *   (onIgnore — CB-12). 수동 게이트(allowRequest + 보고)는 execute 로 감쌀 수 없는 경우에만.
  * - **연속(consecutive) 실패 카운트**: `onFailure()` 가 failureThreshold 에 도달(`>=`)하면
  *   OPEN. `onSuccess()` 는 카운터를 0 으로 리셋한다 (슬라이딩 윈도 비채택 — 단순성).
  * - **lazy 전이**: OPEN → HALF_OPEN 전이는 `allowRequest()` 호출 시점에 판정한다
@@ -586,38 +595,51 @@ declare function createTtlCache<K, V>(options: TtlCacheOptions): TtlCache<K, V>;
  * - **HALF_OPEN 프로브 1개**: 프로브가 진행 중이면 나머지 `allowRequest()` 는 false.
  *   프로브 성공 → CLOSED(카운터 0), 프로브 실패 → OPEN 재진입(openedAt 갱신 —
  *   전체 openDurationMs 재대기).
- * - **결과 보고 규율**: `allowRequest()==true` 를 받은 호출만 `onSuccess()`/`onFailure()`
- *   를 **정확히 1회** 호출한다 (try/finally 로 보고 보장 권장 — 보고 누락은 아래 프로브
- *   보류를 무기한 지속시킨다). OPEN 대기 중 늦게 도착한 보고는 상태·openedAt·카운터를
- *   바꾸지 않고(no-op — CB-08) 미보고 그랜트 잔량만 소진한다.
+ * - **결과 보고 규율**: `allowRequest()==true` 를 받은 호출만 `onSuccess()`/`onFailure()`/
+ *   `onIgnore()` 중 하나를 **정확히 1회** 호출한다 (수동 게이트라면 try/catch 로 보고 보장 —
+ *   성공·실패로 판정할 수 없는 취소 등은 `onIgnore()` 로 그랜트만 반납). OPEN 대기 중 늦게
+ *   도착한 보고는 상태·openedAt·카운터를 바꾸지 않고(no-op — CB-08) 미보고 그랜트 잔량만
+ *   소진한다.
  * - **스테일 그랜트 격리**: CLOSED 시절 그랜트가 아직 보고되지 않은 동안에는
  *   openDurationMs 가 경과해도 HALF_OPEN 전이(프로브)가 보류된다 — 스테일 보고가 프로브
- *   결과로 오인되는 것을 막아 HALF_OPEN 중 도착하는 보고는 항상 프로브의 것이다 (CB-09).
+ *   결과로 오인되는 것을 막아 HALF_OPEN 중 도착하는 보고는 (아래 용서 이후의 매우 늦은
+ *   보고를 제외하면) 항상 프로브의 것이다 (CB-09).
+ * - **유실 그랜트 용서 (2× 규칙)**: 보고가 끝내 오지 않는 그랜트(보고 누락·유실)가 위 보류를
+ *   무기한 지속시켜 서킷이 OPEN 에 영구 고착되는 것을 막는다 — OPEN 진입 후
+ *   `2 × openDurationMs` 경과 시점에도 미보고 그랜트가 남아 있으면 이를 유실로 간주해 0 으로
+ *   용서하고 정상 HALF_OPEN 전이 + 프로브 획득을 수행한다 (CB-10). 용서 뒤 매우 늦은 스테일
+ *   보고가 HALF_OPEN 중 도착하면 프로브 결과로 취급되지만 무해하다 — 스테일 성공은 하류가
+ *   실제로 응답했다는 증거이고, 스테일 실패는 보수적인 OPEN 재진입일 뿐이다 (스테일
+ *   onIgnore 는 프로브 슬롯을 조기 해제해 프로브가 1개 더 허가될 뿐 — 최초 보고가 판정).
+ * - **유실 프로브 용서**: HALF_OPEN 프로브가 openDurationMs(`>=`) 동안 보고되지 않으면 유실로
+ *   간주해 다음 allowRequest() 에 새 프로브를 넘긴다 — 보고 누락 프로브 1개로 HALF_OPEN 에 영구
+ *   고착되는 것을 막는다 (CB-13). 옛 프로브의 늦은 보고는 새 프로브 결과로 취급되며 위와 같은
+ *   이유로 무해하다.
+ *
+ * @example 권장 — execute 로 게이트·보고를 위임한다.
+ * ```ts
+ * const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
+ * const user = await cb.execute(() => api.request<User>("/users/1")); // OPEN 이면 CircuitOpenError
+ * ```
  *
- * @example 서킷 + 재시도 조합 — 시도 직전 allowRequest 게이트, 결과를 브레이커에 보고.
- * OPEN 차단 오류는 shouldRetry 에서 비재시도로 걸러 즉시 실패시킨다(빠른 실패 유지).
+ * @example 서킷 + 재시도 조합 — 시도마다 execute 로 게이트·보고. OPEN 차단
+ * ({@link CircuitOpenError})은 shouldRetry 에서 비재시도로 걸러 즉시 실패시킨다(빠른 실패 유지).
  * ```ts
  * const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
- * const circuitOpen = new Error("서킷 OPEN — 요청 차단");
- * await retry(
- *   async () => {
- *     if (!cb.allowRequest()) throw circuitOpen;
- *     try {
- *       const r = await call();
- *       cb.onSuccess();
- *       return r;
- *     } catch (error) {
- *       cb.onFailure();
- *       throw error;
- *     }
- *   },
- *   {
- *     shouldRetry: (error) => error !== circuitOpen, // OPEN 차단은 즉시 실패
- *     onRetry: (error, attempt, delayMs) => console.warn(`재시도 ${attempt} (${delayMs}ms)`),
- *   }
- * );
+ * await retry(() => cb.execute(() => call()), {
+ *   shouldRetry: (error) => !(error instanceof CircuitOpenError), // OPEN 차단은 즉시 실패
+ *   onRetry: (error, attempt, delayMs) => console.warn(`재시도 ${attempt} (${delayMs}ms)`),
+ * });
  * ```
  */
+/**
+ * 서킷 차단 거부 오류 — `execute()` 가 allowRequest()==false(OPEN 대기·프로브 보류·HALF_OPEN
+ * 프로브 경합)일 때 reject 하며, 이때 작업 함수는 **호출되지 않는다** (CB-12).
+ * Java `CircuitOpenException` / Python `CircuitOpenError` 패리티. 재시도 조합에서 비재시도 신호로 쓴다.
+ */
+declare class CircuitOpenError extends Error {
+    constructor(message?: string);
+}
 type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
 interface CircuitBreakerOptions {
     /** OPEN 전이 임계 — 연속 실패가 이 값에 도달(`>=`)하면 OPEN. 필수 양의 정수 (아니면 RangeError). */
@@ -631,14 +653,32 @@ interface CircuitBreaker {
     /**
      * 요청 통과 여부 — CLOSED 는 true, OPEN 대기 중 false, openDurationMs 경과 시
      * HALF_OPEN 전이 + 프로브 슬롯 획득(true) — 단 CLOSED 시절 미보고 그랜트가 남아 있으면
-     * 전이를 보류하고 false (CB-09). HALF_OPEN 프로브 경합 시 나머지 false.
-     * true 를 받은 호출만 결과를 onSuccess()/onFailure() 로 보고해야 한다.
+     * 전이를 보류하고 false (CB-09), 보류는 OPEN 진입 후 `2 × openDurationMs` 까지만 —
+     * 그 시점엔 미보고 그랜트를 유실로 용서하고 전이 + 프로브 획득(true) (CB-10).
+     * HALF_OPEN 프로브 경합 시 나머지 false — 단 프로브가 openDurationMs 경과(`>=`)까지
+     * 미보고면 유실로 간주해 이 호출에 새 프로브를 넘긴다(true) (CB-13).
+     * true 를 받은 호출만 결과를 onSuccess()/onFailure()/onIgnore() 중 하나로 보고해야 한다.
      */
     allowRequest(): boolean;
     /** 성공 보고 — CLOSED 카운터 리셋, HALF_OPEN 프로브 성공 시 CLOSED 복귀. OPEN 중엔 무시. */
     onSuccess(): void;
     /** 실패 보고 — CLOSED 연속 카운트 증가(임계 도달 시 OPEN), HALF_OPEN 프로브 실패 시 OPEN 재진입. OPEN 중엔 무시. */
     onFailure(): void;
+    /**
+     * 결과 없는 그랜트 반납 — 취소(abort) 등 성공·실패로 판정할 수 없는 호출이 보고 대신
+     * 호출한다 (CB-11). CLOSED: 미보고 그랜트만 반납(연속 실패 카운터 무변화). HALF_OPEN:
+     * 프로브 슬롯 해제 — HALF_OPEN 유지, 다음 allowRequest() 가 새 프로브를 획득한다.
+     * OPEN: 미보고 그랜트 잔량만 소진(그 외 무변화).
+     */
+    onIgnore(): void;
+    /**
+     * fn 래핑 (권장 사용법) — allowRequest() 게이트 → 실행 → 결과 보고를 **정확히 1회** 보장한다.
+     * 거부는 reject(CircuitOpenError) — 동기 throw 아님, 거부 시 fn 은 호출되지 않는다.
+     * resolve → onSuccess() 후 값 반환. throw/reject 는 `name === "AbortError"` 면 onIgnore(),
+     * 그 외(TimeoutError 포함)는 onFailure() 후 **같은 값을 래핑 없이** 다시 throw 한다 (CB-12).
+     * fn 의 동기 throw 도 동일하게 처리된다.
+     */
+    execute<T>(fn: () => T | PromiseLike<T>): Promise<T>;
     /** 현재 상태 조회 — lazy 전이 특성상 openDurationMs 경과 후에도 allowRequest() 전엔 OPEN 으로 보고된다. */
     state(): CircuitState;
 }
@@ -1307,4 +1347,4 @@ declare function composeHangul(s: string): string;
  */
 declare function matchesHangul(query: string, target: string): boolean;
 
-export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };

package/dist/index.js

@@ -171,8 +171,7 @@ function createApiClient(config) {
       if (idempotencyKey !== null && !headers.has(idempotencyHeader)) {
         headers.set(idempotencyHeader, idempotencyKey);
       }
-      const isFormData = typeof FormData !== "undefined" && init.body instanceof FormData;
-      if (!headers.has("Content-Type") && !isFormData) {
+      if (!headers.has("Content-Type") && typeof init.body === "string") {
         headers.set("Content-Type", "application/json");
       }
       if (config.getToken && !headers.has("Authorization")) {
@@ -594,6 +593,12 @@ function createTtlCache(options) {
 }
 
 // src/circuitBreaker.ts
+var CircuitOpenError = class extends Error {
+  constructor(message = "\uC11C\uD0B7 OPEN \u2014 \uC694\uCCAD \uCC28\uB2E8") {
+    super(message);
+    this.name = "CircuitOpenError";
+  }
+};
 function createCircuitBreaker(options) {
   const { failureThreshold, openDurationMs, now = Date.now } = options;
   if (!Number.isInteger(failureThreshold) || failureThreshold <= 0) {
@@ -606,6 +611,7 @@ function createCircuitBreaker(options) {
   let consecutiveFailures = 0;
   let openedAtMs = 0;
   let probeInFlight = false;
+  let probeStartedAtMs = 0;
   let inFlightGrants = 0;
   function allowRequest() {
     if (state === "CLOSED") {
@@ -613,18 +619,24 @@ function createCircuitBreaker(options) {
       return true;
     }
     if (state === "OPEN") {
-      if (now() - openedAtMs >= openDurationMs) {
-        if (inFlightGrants > 0) {
+      const nowMs2 = now();
+      const elapsedMs = nowMs2 - openedAtMs;
+      if (elapsedMs < openDurationMs) return false;
+      if (inFlightGrants > 0) {
+        if (elapsedMs < 2 * openDurationMs) {
           return false;
         }
-        state = "HALF_OPEN";
-        probeInFlight = true;
-        return true;
+        inFlightGrants = 0;
       }
-      return false;
+      state = "HALF_OPEN";
+      probeInFlight = true;
+      probeStartedAtMs = nowMs2;
+      return true;
     }
-    if (probeInFlight) return false;
+    const nowMs = now();
+    if (probeInFlight && nowMs - probeStartedAtMs < openDurationMs) return false;
     probeInFlight = true;
+    probeStartedAtMs = nowMs;
     return true;
   }
   function onSuccess() {
@@ -659,13 +671,40 @@ function createCircuitBreaker(options) {
     }
     inFlightGrants = Math.max(0, inFlightGrants - 1);
   }
+  function onIgnore() {
+    if (state === "HALF_OPEN") {
+      probeInFlight = false;
+      return;
+    }
+    inFlightGrants = Math.max(0, inFlightGrants - 1);
+  }
+  async function execute(fn) {
+    if (!allowRequest()) {
+      throw new CircuitOpenError();
+    }
+    let result;
+    try {
+      result = await fn();
+    } catch (error) {
+      if (isAbortError(error)) onIgnore();
+      else onFailure();
+      throw error;
+    }
+    onSuccess();
+    return result;
+  }
   return {
     allowRequest,
     onSuccess,
     onFailure,
+    onIgnore,
+    execute,
     state: () => state
   };
 }
+function isAbortError(error) {
+  return typeof error === "object" && error !== null && error.name === "AbortError";
+}
 
 // src/tokenBucket.ts
 function createTokenBucket(options) {
@@ -1646,6 +1685,7 @@ function matchesHangul(query, target) {
 export {
   ApiError,
   BulkheadFullError,
+  CircuitOpenError,
   ResultCode,
   WEBHOOK_SIGNATURE_HEADER,
   abbreviateAmount,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rscc/common-core",
-  "version": "0.2.0",
-  "description": "RSCC 공통 코어 — CommonResponse 타입, apiClient 팩토리(traceId 발신/에코), SSE 프레임 파서, JWT 디코더, 마스킹 유틸. 프레임워크 무관, 런타임 의존성 0.",
+  "version": "0.3.0",
+  "description": "RSCC 공통 코어 — CommonResponse 타입·apiClient(traceId·재시도·멱등성 키), SSE 파서, 회복탄력성(retry·서킷 브레이커·토큰버킷·Bulkhead·TTL 캐시), 보안(마스킹·로그 리댁션·웹훅 서명·JWT 디코드·AES-GCM 서브패스), 와이어 계약 헬퍼, 한국 도메인 유틸. 프레임워크 무관, 런타임 의존성 0.",
   "keywords": [
     "rscc",
     "common-response",