[architecture][RFC] Provider Adapter v1 behind the capability registry

[lidge-jun]

배경

Provider Capability Registry는 완성됐습니다. 8개 lane(oauth, api, grok,
grok-api, agy, gemini-api, atlascloud, minimax)의 메타데이터가
중앙화됐고, parity 테스트가 routes/edit.ts / config.ts / Responses adapter /
MCP 제한 / runtime timeout을 실제로 읽어 일치를 검증합니다.

하지만 Registry는 control plane이지 플러그인 인터페이스가 아닙니다.

Registry가 답하는 것:

누가 존재하는가 / 무슨 모델을 갖는가 / 무슨 인증을 쓰는가 / 어떤 제한이 있는가

아직 하나의 인터페이스로 고정되지 않은 것: 실제 런타임 동작. 그래서 신규
provider는 여전히 core adapter, route, UI, 오류 처리, 테스트, package release를
횡단으로 건드립니다.

제안: Registry 뒤에 Adapter v1

interface ProviderAdapter {
  validateAuth(): Promise<AuthResult>;
  listModels(): Promise<Model[]>;
  generateImage(input: ImageRequest): Promise<JobHandle>;
  editImage(input: EditRequest): Promise<JobHandle>;
  generateVideo?(input: VideoRequest): Promise<JobHandle>;
  getJob?(id: string): Promise<JobSnapshot>;
  cancelJob?(id: string): Promise<void>;
  normalizeError(error: unknown): ProviderError;
}

첫 단계에서 npm package로 쪼갤 필요는 없습니다. 폴더 경계와 인터페이스를 먼저
고정합니다.

packages/
  core/
  provider-sdk/
  providers/{openai,grok,gemini,minimax}/

수용 조건

• 신규 provider 구현 시 core 변경 5개 파일 이하
• UI에 provider별 switch 문이 없음
• Registry에서 모델·기능·제한 자동 생성
• 공통 contract suite가 모든 adapter에 자동 적용
• adapter가 자신의 오류 정규화를 소유
• adapter 하나를 core 밖 실험 패키지로 로딩 성공

이것이 끝나기 전에 하지 말 것

새 provider를 추가하지 않는 것이 맞습니다. Adapter v1 없이 provider를 더
넣으면 Registry가 있어도 횡단 수정이 다시 늘어납니다.

근거: 2026-08-14 성숙도 재평가 (64/80) Phase 2-1. 아키텍처 점수를 58→69로 올린
것이 Registry였고, 다음 상승은 그 뒤의 adapter 계층에서 나옵니다.

[lidge-jun]

이번 릴리스에서는 adapter 구현에 착수하지 않겠습니다. 이 이슈는 열어 둡니다.

의존 순서는 #151 canonical job envelope → #150 provider adapter가 맞습니다.
여기서 제안한 generateImage(): Promise<JobHandle>과
editImage(): Promise<JobHandle>은 JobHandle의 phase, sequence, terminal,
cancel/retry/resume 의미가 먼저 고정돼야 합니다. 지금 ProviderAdapterV1 타입만
추가하면 runtime이 그 계약을 어겨도 공통 테스트가 잡지 못합니다.

현재 코드에서 확인한 경계는 다음과 같습니다.

• lib/inflight.ts:184 — setJobPhase(..., phase: string)이라 canonical phase
  union이 없습니다.
• lib/inflight.ts:52 — terminal snapshot은 프로세스 메모리 Map에만 남아
  재시작 뒤 복구되지 않습니다.
• lib/eventBus.ts:17 — seq는 프로세스 전역 replay cursor이며 job별 sequence가
  아닙니다.
• lib/grokImageCore.ts:199-203 — idempotency key가 없어 과금 POST를 재시도하지
  않는다고 코드가 명시합니다.

최근 MiniMax 추가 범위도 기준으로 남깁니다. provider 관련 네 커밋의 파일 union은
54개였습니다. 초기 구현, key/model 보강, UI 등록, fail-open 수정까지 합친 보수적
실측값입니다. #150의 “신규 provider 구현 시 core 변경 5개 이하”와 아직 큰 차이가
있습니다.

다음 착수 때는 #151의 envelope를 SSE/CLI/MCP/UI 소비 경로에 먼저 배선하고 contract
suite로 고정하겠습니다. 그 다음 현재 Registry 뒤에 adapter lookup을 놓고 OpenAI
계열 한 lane을 기준 adapter로 옮긴 뒤, core 밖 실험 adapter 로딩과 5-file budget을
실제 diff로 검증하겠습니다. 신규 provider 추가는 그 검증 뒤가 맞습니다.

정리 제안: 기존 priority: p1은 유지하고 dependencies, area: typescript를
추가합니다. 별도 milestone은 현재 열려 있지 않으므로 만들지 않고, #151의 구현
범위와 release target이 확정될 때 두 이슈를 같은 architecture milestone에 묶는 편이
정확합니다.

[lidge-jun]

이번 사이클에서도 adapter 구현에는 착수하지 않았습니다. 이슈는 열어 둡니다.

의존 순서가 #151 → #150이라고 했었는데, 그 #151의 1단계가 이번에
들어갔습니다(32de69e3, ddf56f9e). 다만 adapter가 필요로 하는 부분은
아직 아닙니다.

지금 상태

JobEnvelopeV1이 생겼고 SSE 페이로드에 실립니다. 그런데 #150의
generateImage(): Promise<JobHandle>이 전제하는 것은 envelope 타입이
아니라 cancel / retry / resume 계약입니다. 그게 #151에서 아직 미착수라,
지금 adapter 인터페이스를 고정하면 그 계약이 정해질 때 다시 고쳐야 합니다.

이번에 확인한 경계

계획 단계에서 실독하며 확인한 것들을 남깁니다.

• lib/providers/types.ts:28 — 모델 타입은 CoreProviderModel입니다.
  ProviderModel이라는 타입은 없습니다.
• lib/minimaxImageAdapter.ts:192-199 — generateViaMinimax(prompt, ctx, options)가
  ctx.minimaxApiKey에서 키를 읽습니다. process.env가 아닙니다.
  routes/keys.ts:302-305가 런타임에 이 값을 갱신하므로, env만 보는
  validateAuth()는 오탐을 냅니다. adapter는 RuntimeContext를 묶는
  팩토리여야 합니다.
• routes/models.ts:171-177 — minimaxLane(ctx)이 첫 소비자 후보입니다.
  DTO 투영(lane(...), entries(...), video: [])은 route에 남고
  auth/모델 조회만 adapter 뒤로 갑니다.
• 회귀를 잡는 건 tests/models-endpoint-contract.test.ts:103-128입니다.
  다만 minimax에 대해서는 status와 모델 id만 보고 reason,
  defaults.image, video: [], 키가 있을 때의 ready 상태는 확인하지
  않습니다. adapter로 옮기려면 이 테스트부터 보강해야 합니다.

다음 착수 조건

#151의 cancel/retry/resume 계약이 고정되면, minimax lane 하나를 기준
adapter로 옮기고 공통 contract suite를 붙이겠습니다. 그 다음에 5-file
budget을 실제 diff로 측정합니다. 신규 provider 추가는 그 뒤가 맞습니다.

[lidge-jun]

1단계를 구현했습니다. 커밋 a00812e1. 이슈는 열어 둡니다 — 수용 조건 6개 중 2개 충족, 4개 미충족입니다.

수용 조건 대조

조건	상태
신규 provider 구현 시 core 변경 5개 파일 이하	미충족 — adapter 2개째가 생겨야 측정 가능
UI에 provider별 switch 문이 없음	미충족 — UI 미변경
Registry에서 모델·기능·제한 자동 생성	부분 — minimax lane 한정
공통 contract suite가 모든 adapter에 자동 적용	충족
adapter가 자신의 오류 정규화를 소유	부분 — minimax 한정
adapter 하나를 core 밖 실험 패키지로 로딩	미충족 — 폴더 경계만

무엇을 만들었나

lib/providers/adapters/ 아래 세 파일입니다.

types.ts — ProviderAdapterV1. lane이 이미 소유하고 있는 것부터 인터페이스로 고정했습니다: 인증 상태, 모델 목록, 오류 어휘.

interface ProviderAdapterV1 {
  readonly laneId: CoreProviderId;
  validateAuth(): AuthResult;
  listModels(): readonly CoreProviderModel[];
  normalizeError(error: unknown): ProviderError;
  generateImage?(input: unknown): Promise<JobHandle>;
  editImage?(input: unknown): Promise<JobHandle>;
}

generateImage/editImage를 선택 멤버로 둔 이유가 있습니다. 이슈 본문 제안대로 Promise<JobHandle>을 반환하려면 JobHandle의 phase, sequence, terminal, cancel/retry/resume 의미가 먼저 고정돼야 합니다. #151 1단계에서 JobEnvelopeV1과 JobHandle 타입은 만들었지만 cancel/retry/resume 계약은 아직입니다. 지금 필수로 박으면 그 계약이 정해질 때 두 번 고칩니다.

minimax.ts — 기준 adapter. minimax를 고른 이유는 8개 lane 중 런타임 표면이 가장 작기 때문입니다(키 1개, 이미지 모델 2개, 비디오 없음, 참조 1장). 인터페이스 모양이 맞는지 확인하는 데 가장 싼 자리입니다. 기존 lib/minimaxImageAdapter.ts는 그대로 두고 감싸기만 합니다.

index.ts — getProviderAdapter(ctx, laneId). 등록되지 않은 7개 lane은 null을 돌려주고 기존 경로가 그대로 돕니다.

프로덕션 소비자를 붙였습니다

routes/models.ts의 minimaxLane이 이제 adapter를 거칩니다. lookup만 만들고 아무도 안 쓰면 죽은 코드라서, 실제 요청 경로에 놓는 것이 1단계의 조건이라고 봤습니다.

DTO 투영은 route에 남겼습니다. /api/models 응답 형태를 바꾸지 않기 위해서입니다. 그리고 그게 정말 안 바뀌었는지 확인하는 테스트를 추가했습니다.

✔ the MiniMax lane keeps its exact DTO when no key is configured
✔ the MiniMax lane reports ready once the runtime context holds a key

status, reason, defaults.image, models.image 항목 전체 형태, video 빈 배열을 키 있음/없음 두 상태에서 단언합니다.

팩토리인 이유

createMinimaxAdapter(ctx)가 RuntimeContext를 클로저로 잡습니다. 모듈 수준 싱글턴이 아닙니다.

routes/keys.ts:302-305가 서버 실행 중에 ctx.minimaxApiKey를 갱신합니다. process.env를 읽으면 사용자가 방금 키를 설정했는데도 lane이 미인증으로 나옵니다.

contract suite

tests/provider-adapter-v1-contract.test.ts 9건입니다. provider 이름을 나열하지 않고 listProviderAdapters()를 순회하므로, adapter가 하나 더 등록되면 아무도 이 파일을 고치지 않아도 모든 단언을 물려받습니다. 그게 수용 조건 중 "공통 contract suite 자동 적용"입니다.

✔ at least one adapter is registered
✔ every adapter implements the required members
✔ every adapter lane exists in the capability registry
✔ listModels comes from the registry, not a hand-written list
✔ no adapter source hard-codes a model id
✔ validateAuth reflects live credentials from the runtime context
✔ normalizeError owns the lane's error vocabulary
✔ an existing provider-specific code is preserved, not double-prefixed
✔ an unregistered lane returns null so its current path is untouched

"no adapter source hard-codes a model id"는 정적 검사입니다. adapter 소스에 registry 모델 id 문자열이 리터럴로 나타나면 실패합니다 — registry가 없애려던 drift가 adapter에서 되살아나는 걸 막습니다.

검증

npm run typecheck        exit 0
npm run typecheck:tests  exit 0
npm run test:inventory   exit 0
npm test                 tests 2268 / pass 2266 / fail 0 / skipped 2

기존 provider-registry-parity, minimax-provider-contract 등 provider 테스트 무회귀입니다.

다음 단계

순서는 이렇게 봅니다.

1. #151의 cancel/retry/resume 계약 확정 → generateImage/editImage 시그니처 고정
2. adapter 2개째(atlascloud가 다음으로 표면이 작습니다) → 그때 "core 변경 5개 파일 이하"를 실제 diff로 측정
3. generate/edit 런타임 디스패치를 adapter로 이전
4. UI의 provider별 분기 제거
5. core 밖 실험 패키지 로딩

신규 provider 추가는 여전히 그 뒤입니다. 이슈 본문의 경고가 그대로 유효합니다 — adapter 계층이 완성되기 전에 provider를 더 넣으면 횡단 수정이 다시 늘어납니다.

[lidge-jun]

2번째 adapter를 구현했습니다. 커밋 cb6d8629. 수용 조건의 핵심 실측인 "core 변경 5개 파일 이하"를 측정했습니다.

core diff 실측

git diff --stat (docs 제외)
 lib/providers/adapters/atlascloud.ts        [NEW]  88줄
 lib/providers/adapters/index.ts             [MOD]  +10 -5
 routes/models.ts                            [MOD]  +19 -8
 tests/provider-adapter-v1-contract.test.ts  [MOD]  +44 -27
 tests/models-endpoint-contract.test.ts      [MOD]  +43 -2

core(비테스트) 3개, 전체 5개. 수용 조건 충족. minimax 전례(3 lib + 1 route)와 같은 형태이고, generate/edit 디스패치는 interface상 optional이라 이동 대상이 아니었습니다 — 그 signature는 #151의 cancel/retry/resume 계약에 묶여 있습니다.

atlascloud를 고른 이유 (표면 크기가 아니라 계약 적합성)

lane	탈락 사유
gemini-api	API key + Vertex SA 이중 credential — AuthResult 다중 credential 설계 선행 필요
agy	async binary 탐지라 sync validateAuth() 부적합
grok-api	errorPrefix GROK_를 grok과 공유 — normalizeError 소유 모호
oauth/api	errorPrefix null — contract suite의 오류 어휘 검증이 전부 skip

atlascloud만 단일 API key + 고유 prefix + image 전용 + sync 판독이 전부 성립합니다.

contract suite가 실제로 자동 적용됨을 확인

9건 중 6건이 listProviderAdapters 자동 순회라 atlascloud가 등록만으로 상속했습니다 (required members, registry 일치, 모델 id 하드코딩 금지, 오류 어휘: 401 비재시도 / 429·502 재시도 / prefix 강제).

감사가 지적한 공허함도 고쳤습니다: auth two-state 단언이 minimax 하드코딩이라 fixture만 넓히면 atlascloud의 ok===true가 검증 없이 통과할 뻔했습니다. auth 단언을 lane 순회형으로 일반화하고 lane별 기대 reason 테이블(EXPECTED_AUTH_REASON)을 두어, 새 adapter가 테이블에 행을 추가하지 않으면 테스트가 실패합니다.

수용 조건 현황

조건	상태
신규 provider 구현 시 core 변경 5개 파일 이하	실측 충족 (core 3)
공통 contract suite가 모든 adapter에 자동 적용	충족 (6건 자동 상속 + auth 실단언)
adapter가 자신의 오류 정규화를 소유	충족 (ATLASCLOUD_ prefix, retryable 세트)
Registry에서 모델·기능·제한 자동 생성	충족 (listModels = registry 파생)
UI에 provider별 switch 문이 없음	미착수 — generate/edit 디스패치가 adapter 뒤로 가야 성립
adapter 하나를 core 밖 실험 패키지로 로딩	미착수

알려진 한계 (기록)

ATLASCLOUD_UNKNOWN은 PROVIDER_ERROR_MAP에 키가 없어 providerErrorClass()가 undefined를 반환합니다. MINIMAX_UNKNOWN도 같은 기존 구멍이며, 이번 단계는 minimax 패리티를 유지했습니다.

검증

npm test    2301 중 2299 pass, 0 fail
typecheck / typecheck:tests / test:inventory 통과

이슈는 계속 열어 둡니다 — 남은 두 조건(UI switch 제거, 외부 패키지 로딩)은 generate/edit 디스패치 전환이 선행돼야 하고, 그 signature는 envelope 기반 JobHandle(#151 완료로 이제 고정됨) 위에서 다음 단계로 설계할 일입니다. 다음 순서: adapter에 generateImage/editImage를 채우고 파이프라인 디스패치를 adapter 경유로 전환.

계획·감사 기록: devlog/_plan/260818_platform_contracts_closeout/020_wp2_atlascloud_adapter.md (독립 리뷰어 2명, 감사 2라운드, 결함 4건 반영)

[lidge-jun]

수용 조건을 하나씩 실제 코드로 확인했습니다. 아직 안 끝났습니다. 열어둡니다.

0/0 을 만들려고 닫는 건 정직하지 않다고 판단했습니다.

수용 조건	상태	근거
신규 provider 시 core 변경 5파일 이하	❌	이번 주 comfy video 하나 붙이는 데 routes/video.ts, routes/models.ts, lib/providerOptions.ts, lib/comfyImageAdapter.ts, lib/comfyGraphBind.ts, lib/comfyWorkflowStore.ts, UI store 3개, CLI 2개를 건드렸습니다
UI 에 provider별 switch 없음	❌	GenProviderModelSelect.tsx 6곳, storeSettingsImpl.ts 11곳
Registry 에서 모델·기능·제한 자동 생성	✅	deriveProviderIds, deriveCliImageModelSet, 이번에 추가한 deriveVideoProviderIds
공통 contract suite 가 모든 adapter 에 적용	🟡	tests/provider-adapter-v1-contract.test.ts 는 있는데 어댑터가 10 lane 중 4개(minimax, atlascloud, nai, comfy)뿐
adapter 가 자기 오류 정규화를 소유	✅	normalizeError 가 ProviderAdapterV1 에 있고 4개 다 구현
core 밖 실험 패키지로 adapter 로딩	❌	packages/ 없음. 전부 lib/providers/adapters/

핵심 격차

ProviderAdapterV1 의 generateImage / editImage 가 optional 인데 아무 어댑터도 구현하지 않았습니다. 실제 생성은 여전히 lib/generatePipeline.ts 와 routes/* 가 lane 별로 분기해서 합니다. 즉 지금 어댑터는 "auth + model list + error shape" 까지고, RFC 가 말한 런타임 동작 인터페이스는 아직입니다.

Registry 가 control plane 이라는 이 이슈의 진단이 여전히 정확하고, 그 다음 층이 안 올라온 상태입니다.

참고: "끝나기 전에 새 provider 추가하지 말 것"

이 조언은 지켜지지 못했습니다. 그 사이 nai 와 comfy 가 들어왔고, comfy video 작업에서 예상대로 횡단 수정이 발생했습니다. 이건 이 이슈의 논거를 약화시키는 게 아니라 강화하는 실측 사례라고 봅니다.

남은 작업이 실재하므로 열어둡니다.