failureModes에 soft-resolve 모드 추가 — reject 아닌 '다른 shape로 resolve' 실패 7건 (프로비저닝 의존)

[DaveDev42]

문제

failureModes 다이얼(#777)은 현재 reject만 한다 — buildNativeError로 네이티브 오류 envelope을 만들어 throw/onError한다. 그런데 실기기(env3) capture는 다이얼로 재현해야 할 실패의 상당수가 reject가 아니라 다른 shape로 resolve하는 soft-resolve임을 보인다. reject 전용 다이얼로는 이걸 못 만든다.

sdk-example env1↔env3 capture diff(현재 동치 59/70)의 남은 불일치 11건 중 7건이 이 soft-resolve 부류다:

API :: scenario	env3 (실기기) 관측	mock 현재 기본값	상태
grantPromotionReward / grantPromotionRewardForGame (3 시나리오)	resolved { errorCode, message }	{ key }	shape 확정 — #785가 담당
IAP.getSubscriptionInfo :: happy-varied-orderId	resolved {} (valueKeys=[])	{ subscription: {...} }	shape 확정
checkoutPayment :: I2-result-success-examined	resolved ["false","reason"] 키	{ success }	키셋 확정(sdk-example task #31), 값 수준 미확정(#303, 폰 필요)
requestTossPayPaysBilling (2 시나리오)	resolved ["false","reason"] 키	{ success }	위와 같음

전부 프로비저닝·시나리오 의존이다 — 31146에 등록된 promotion이 없고, 조회한 orderId에 활성 구독이 없고, 테스트가 실 결제를 완료할 수 없다. 그래서 실기기는 "성공했지만 내용이 빈/오류 본문" shape로 resolve한다.

설계 규칙 (왜 mock 기본값을 못 바꾸나)

이건 이미 코드 주석과 #785·#786에 명문화된 규칙이다: 프로비저닝·시나리오 의존 관측은 mock의 무조건적 기본값이 되면 안 된다. 기본값을 이 soft-resolve로 굳히면 —

• SDK가 선언한 성공 분기({ key }, { subscription }, { success: true })가 mock에서 영구히 도달 불가능해진다. 정상 프로비저닝된 앱을 개발하는 일반 사용자의 dev 경험이 깨진다.
• mock 동치 갭 해소 — 반환-shape 소수정 + 실패-모드 다이얼 (env1이 env3 실 계약을 재현) #770 자신의 acceptance("다이얼 미사용 시 zero behavior change")도 깨진다.

그래서 기본값은 선언 타입대로 성공으로 두고, 재현은 다이얼에 붙인다. 문제는 현 다이얼이 reject만 한다는 것 — 이 부류를 담을 다이얼 모드가 없다.

할 일 (설계 + 구현)

1. failureModes에 soft-resolve 모드를 추가한다. reject(현행)와 별개로, 지정한 API가 다이얼을 켰을 때만 대체 shape로 resolve하게 한다. shape는 API별로 고정(실측값):

• grantPromotionReward/grantPromotionRewardForGame → { errorCode, message } (#785와 통합 — #785를 이 모드의 첫 소비자로)
• IAP.getSubscriptionInfo → {} (빈 객체)
• checkoutPayment / requestTossPayPaysBilling → 결제 실패 soft-resolve shape

2. 값 수준 미확정 gate. promotion({errorCode,message})·IAP({})는 키셋·값이 정합해 지금 배선 가능하다. 그러나 결제 2 API의 ["false","reason"] 키셋은 sdk-example#303(폰 필요)에서 값 수준 확증이 안 끝났다 — 키 이름이 특이해(문자열 "false") 하네스 아티팩트가 아님은 확인됐지만(task #31) 실제 값 구조는 미확정이다. 결제 2 API 배선은 #303 확증 후에 착수한다(미확정 shape로 다이얼을 굳히면 계기가 또 거짓말한다). promotion·IAP만 이 이슈에서 배선하고, 결제는 #303-gated로 남긴다.

3. Acceptance

• 다이얼 미설정 시 각 API가 선언 타입 성공 shape 유지(zero behavior change)
• 다이얼 설정 시 실측과 동치인 soft-resolve shape로 resolve
• 두 상태를 각각 단언하는 테스트 (특히 valueKeys = 실측 키셋)
• sdk-example에서 다이얼 켠 상태로 env1↔env3 capture diff가 해당 키들을 동치로 접는지 확인 (promotion 3 + IAP 1 = 4건 → 동치 59/70에서 63/70 기대; 결제 3건은 feat: unify MCP error messages with 4-state differentiation (#285) #303-gated)

관련

• grantPromotionReward soft-failure shape를 failureModes 다이얼에 배선 #785 (promotion soft-failure 배선 — 이 모드의 첫 소비자로 통합)
• mock 동치 갭 해소 — 반환-shape 소수정 + 실패-모드 다이얼 (env1이 env3 실 계약을 재현) #770 (env1↔env3 동치 / failureModes 도입), feat(mock): 실패-모드 다이얼 — env1이 env3 프로비저닝-의존 reject 재현 #777 (다이얼), IAP.getSubscriptionInfo·TossPay 반환-shape가 프로비저닝 의존 capture를 무조건 기본값으로 굳힘 (#778 잔여) #786 (IAP/TossPay 되돌림 정정)
• sdk-example#303 (결제 값 수준 확증, 폰 필요), sdk-example#317 (계기가 이 갭을 볼 수 있게 한 errorKeys 비교)

커뮤니티 오픈소스 프로젝트입니다.

[DaveDev42]

설계 확정 (env3 run11 2.x/iOS 실측 대조 후)

.ait-run/.ait-capture/(env3 run11) 실측으로 세 shape를 못 박았다:

API :: scenario	env3 실측	성격
grantPromotionReward / grantPromotionRewardForGame (5 레코드)	resolved · valueKeys=['errorCode','message'] · booleanValues=null	값-독립, 완전 실측
IAP.getSubscriptionInfo :: happy-varied-orderId (3)	resolved · valueKeys=[] (빈 객체) · booleanValues=null	값-독립, 완전 실측
checkoutPayment / requestTossPayPaysBilling (payment)	resolved · valueKeys=['false','reason'] · booleanValues=null	키셋 실측(task#31 "하네스 버그 아님, 실기기 shape 확정"), 값 수준 재확인 폰-gated (#303)

다이얼 API — Option A (reject 축에 겹치지 않는 명시적 softResolve 서브맵)

reject 전용 failureModes(per-API NativeErrorCode)와 의미가 다르다 — reject는 던지고, soft-resolve는 다른 shape로 resolve한다. 그래서 NativeErrorCode 값을 재사용(암묵)하지 않고 별도 boolean 서브맵으로 분리한다:

export interface FailureModes {
  sdkLine: '2.x' | '3.x';
  // ... 기존 reject 키 (appLogin, loadAdMob, ...) 변경 없음 ...
  /**
   * soft-resolve 다이얼 — reject가 아니라 "다른 shape로 resolve"하는 env3
   * 프로비저닝-의존 실패를 재현. 켠 API만 실측 대체 shape로 resolve, 미설정
   * API는 선언 타입대로 성공 유지(다이얼 미사용 시 zero behavior change).
   * shape는 API별 고정(env3 run11 2.x/iOS 실측, valueKeys만 실측이고 문자열
   * 내용은 예시):
   *   grantPromotionReward/grantPromotionRewardForGame → { errorCode, message }
   *   getSubscriptionInfo → {}
   */
  softResolve?: {
    grantPromotionReward?: boolean;
    grantPromotionRewardForGame?: boolean;
    getSubscriptionInfo?: boolean;
  };
}

payment(checkoutPayment/requestTossPayPaysBilling)는 shape는 실측됐으나 값 수준 재확인이 폰-gated(#303)라 이 배선에서 제외 — 마찬가지 성격이라 확정 시 한 줄로 추가되게 서브맵을 확장 가능하게 둔다.

off-contract cast

grantPromotionReward의 선언 반환은 Promise<GrantPromotionRewardResponse>(= { key })인데 soft-resolve shape는 { errorCode, message }라 타입이 안 맞는다 — 이건 SDK 타입이 실기기보다 낙관적이라는 사실 그 자체다. 국소 as unknown as GrantPromotionRewardResponse cast + 주석으로 처리(__typecheck.ts 반환 타입은 불변이라 두 라인 typecheck는 통과). getSubscriptionInfo도 동일({} as unknown as { subscription: IapSubscriptionInfoResult }).

이 배선이 닫는 것 / 남는 것 (동치 산술)

• devtools 측(이 이슈): 메커니즘 + promotion(grantPromotionReward soft-failure shape를 failureModes 다이얼에 배선 #785 close) + IAP 배선.
• sdk-example 측(후속, publish 후): provisioningMirror.ts에 softResolve surface 추가 + game/iap *.ait.test.ts beforeAll 배선 → 측정 시 4건 동치.
• 폰 없는 env1↔env3 천장 = 66/70 (94.3%): 현 59 + errorKeys 3건(fix(mock): 결정적 입력-계약 reject 3건 native envelope shape 수정 #790, 머지됨) + soft-resolve 4건(promotion 3 + IAP 1). 남는 4건은 전부 폰-gated(payment 값 확인 3 + getCurrentLocation timeout flake 1).

#785는 이 모드의 첫 소비자로 통합돼 이 PR에서 닫힌다. #789는 payment 잔여로 열어둔다.