@ax-hub/admin-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,324 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] — 2026-05-29
+
+First stable major. `@ax-hub/sdk` ↔ backend `main` 정렬 (110→177 routes, 36→42 error codes) + 단일 패키지에서 npm workspaces 모노레포로 전환. 거버넌스(admin) surface 36 op 을 신규 공개 패키지 **`@ax-hub/admin-sdk`** 로 분리. SDK 1차 사용자(코딩 에이전트 + member/PAT 앱)는 admin 메서드로 항상 403 을 받았으므로 main SDK 표면에서 제거하는 것이 정상화다. 마이그레이션 매핑은 [`docs/MIGRATION-1.0.md`](docs/MIGRATION-1.0.md) 참조 (ADR-0042 / ADR-0043 / ADR-0044).
+
+### BREAKING
+
+- **admin 거버넌스 36 op 이동 — `@ax-hub/sdk` 에서 제거, 신규 `@ax-hub/admin-sdk` 로 이동.** 접근은 `new AdminClient({ token, tokenType })` (from `@ax-hub/admin-sdk`) 로. 매핑:
+  - `sdk.audit.*` (events `list`/`get`, `integrityCheck`, `anonymize`) → `adminSdk.audit.*`
+  - `sdk.authz.{tags,subjects,grants}` → `adminSdk.authz.*`
+  - `sdk.authz.evaluator` / `decide` **제거-only** — backend 공식 route 부재. backend 노출 시 후속 admin-sdk 에서 재도입.
+  - `sdk.tenants.{create,list,update,delete}` + members / invitations / email-domains / icon → `adminSdk.tenants.*`. **`sdk.tenants.get` 은 main 유지.**
+  - `sdk.identity.idp` (`IdentityProviderClient`) → `adminSdk.identityProviders.*`
+  - `sdk.apps.categories.{create,update,delete}` → `adminSdk.categories.*`. **`sdk.apps.categories.list`/`get` 은 main 유지.**
+- **`sdk.apps.create()` 는 이제 tenant UUID(`defaultTenantId`) 를 요구**하고 미설정 시 `TenantIdRequiredError` 를 throw. 구 `POST /api/v1/apps` 404-fallback 경로 제거. `apps.list()` 는 `defaultTenantId` 설정 시 tenant-scoped, 미설정 시 live alias 호출 (US1).
+
+### Added
+
+- **신규 capability ~25 (US3, non-breaking):** apps `suspend`/`resume`, app invitations `create`/`delete`, `members.list`, `discover`(global + tenant), `me/apps` (owned + received), `check-availability` + icon pre-create, tables `check-availability`/`column-types`/`browse-rows`, deploy `logs`/`app-bootstraps`/github accounts+repos, `gateway.engines`, identity github oauth `start`/`callback`, `config.public` (tokenless), reviewer review-requests history.
+- **MCP + OAuth (US4):** `registerMcpClient` (Dynamic Client Registration, unauthenticated), RFC 8707 `resource`/audience binding on authorize + token, oauth-client `allowedResources`, 9 typed OAuth errors incl. 전용 `InvalidTargetError`.
+- **입력/필드 drift (US5):** `CreateAppInput`/`UpdateAppInput` 신규 필드 (`authMode`, `dataScopes`, `deployMethod`, `resourceTier`, `subdomain`, `clearSubdomain`, `iconDarkUrl`), oauth-client 신규 필드, env-var `stage`, table `description`, app-list `filter`/`sort`/`page` 파라미터.
+
+### Changed
+
+- backend contract pin 을 spec-278 → backend `main` 으로 전진 (110→177 routes, 36→42 error codes). error catalog 6 코드 추가 (`codes.go.snapshot` 갱신, `extract-codes` 재생성).
+- OAuth 9 코드 매핑에 `invalid_target` 전용 구분 추가 (US5).
+
+### Infrastructure
+
+- 단일 패키지 `@ax-hub/sdk` → **npm workspaces 모노레포** (`packages/*`). 공유 infra(http/auth/error/pagination/retry/redaction/branded-id/resource helpers)를 private **`@ax-hub/core`** (`private:true`, **미발행**) 로 추출, tsup `noExternal` 로 `@ax-hub/sdk` + `@ax-hub/admin-sdk` dist 에 inline. publish `.d.ts` 에 private core import 0 (SC-009, `check:dts-no-private-core` gate).
+- 신규 공개 패키지 **`@ax-hub/admin-sdk`** (governance surface, `AdminClient`).
+- public packages(sdk/admin-sdk) semver major 1.0.0 동반, private core 버전 동기화. release CI 가 두 공개 패키지를 발행 (core 는 비발행).
+- ADR 신규: ADR-0042 (monorepo workspaces), ADR-0043 (BC relocation → admin-sdk), ADR-0044 (public API whitelist 재정의).
+
+## [0.3.0] — 2026-05-26
+
+gateway 거버넌스 surface(`engines`/`connectors`/`resources`, `@adminOnly`)를 SDK 에서 제거하고 member-facing surface(`query` + `catalog`)만 유지 (ADR-0041). SDK 1차 사용자(코딩 에이전트 + member-token 앱)는 거버넌스 메서드로 항상 403 을 받았고, connector/engine 관리는 콘솔 관리자 작업이다.
+
+### BREAKING
+
+- `gateway.{engines,connectors,resources}` 제거. member token 은 이들에 항상 `ForbiddenError`(403)였음. connector 목록·이름→UUID 는 `gateway.catalog.listConnectors()` 사용 — `CatalogConnector.id` 는 동일 connector UUID 라 `query.run({ connectorId })` 에 그대로 사용.
+- 공개 타입 `GatewayEngine`/`GatewayConnector`/`GatewayResource` 제거.
+- `TenantGatewayClient` 는 `query` + `catalog` props 만 노출. `GatewayClient`/`TenantGatewayClient`/`GatewayCatalogClient`, `query`/`catalog`, 모든 `Catalog*`·`GatewayQuery*` 타입·응답 헬퍼는 유지.
+
+## [0.2.0] — 2026-05-26
+
+나머지 6개 BC(identity·tenants·audit·apps·deploy·schema)를 backend golden routes + handler shape 와 전수 대조해 발견한 drift 일괄 수정 (ADR-0040). 라이브 PAT smoke 로 fixed read + 회귀 검증 (`discover.search`/`listMine`/`integrityCheck` 동작, authz/gateway/audit 무손상).
+
+### BREAKING
+
+- `tenants.members.{update,deactivate,reactivate}` 반환 `TenantMember` → `void`. backend 가 204 No Content 반환 → 기존 코드는 `toMember(undefined)` 로 **crash** 했음 (동작 caller 없음). 갱신된 row 가 필요하면 `members.list()` 재조회.
+- `identity.systemOAuthClients.{create,delete}` 제거. global `POST/DELETE /oauth-clients` 라우트 없음 — app-scoped 생성은 `apps.oauthClients.create(appId, …)` 사용. `get()` 은 유지.
+- `deployments.{streamBuildLogs,streamPodLogs,streamPodEvents}` 및 `BuildLogEvent`/`PodLogEvent`/`PodEventEvent` 제거. backend 에 해당 SSE 라우트 부재 (gateway query.stream ADR-0037 과 동일 phantom).
+- `DeploymentResponse` shape 변경: `url`/`errorMessage`/`createdAt`/`updatedAt` 제거(wire 부재), `commitSha`/`currentStage`/`imageUri`/`failureReason` 추가. `DeploymentStatus` enum 변경 (`queued`/`rolled_back` 제거 → `pending`/`pushing` 추가).
+- `CreateDeploymentInput.ref` 제거 → `commitSha?`/`forceRebuild?` (backend `commit_sha`/`force_rebuild`). 기존 `ref` 는 backend 가 무시(항상 default-branch HEAD 배포)했으므로 실동작 변화 없음.
+- `IntegrityCheckResult.brokenAt?: string` → `firstBadSeq?: number` (+ `reason?`). backend 는 `first_bad_seq` 반환 — 기존 `brokenAt` 은 항상 undefined 였음.
+
+### Fixed
+
+- `apps.discover.search` 경로 `GET /api/v1/apps` → `GET /api/v1/apps/search`. 기존엔 list alias 를 호출해 `q`/`category`/`sort` 필터가 무시됐음 (라이브: items=4 반환 확인).
+- `apps.listMine` 경로 `/api/v1/users/me/apps` → `/api/v1/me/apps/workspace`. 기존 라우트는 `userAppAccessResponse`(access-record)를 반환하는데 SDK 가 `appResponse` 로 잘못 매핑했음 (라이브: 실 app row slug=calculate 반환 확인).
+- `tenants.invitations.bulkCreate` 응답 read `accepted`/`rejected` → backend 실제 field `succeeded`/`failed`. 기존엔 항상 빈 결과를 반환했음. backend 의 `message`(한국어 사용자 문구)를 `rejected[].message` 로 추가 노출.
+- `deployments.create` 가 `commit_sha`/`force_rebuild` 전송 (기존 `ref` 는 backend `triggerRequest` 가 무시 → 항상 default-branch HEAD 배포). `{ commitSha }` 로 특정 commit 배포 가능.
+- `audit.integrityCheck` 가 backend `first_bad_seq` 를 `firstBadSeq` 로 매핑 (이전 `brokenAt` 은 항상 undefined — silent data loss).
+- `audit.anonymize` body 에서 `anonymized_id` 가 `reason` 으로 fallback 하지 않음. `reason` 은 UUID 가 아니라 400 을 유발했음.
+- `apps.tables.{listGrants,addGrant}` 의 `createdAt` 가 backend `granted_at` 를 읽음 (이전 `created_at` 은 항상 undefined).
+
+### Known follow-ups (ADR-0040)
+
+- works-via-fallback (미수정, 동작): `data.discover` slug-inspect probe, `data.insertMany` `/_bulk` probe, `apps.publication.unpublish` `/unpublish` probe, signIcon field alias.
+- 미확인: `deploy.create` request body(`ref` vs `commit_sha`), `deploy.list` cursor vs offset, `apps.env-vars` `secret`/`stage` drop, tenant-scoped BC 의 slug→UUID 자동 resolve 여부.
+- `audit.server.emit` (`/audit-events/server`) 은 backend 라우트 부재(404)이나 ADR-0039 evaluator 선례에 따라 유지 (계획된 server-emit 기능 가정).
+- missing-method 커버리지 (backend 라우트 존재, SDK 미구현)는 ADR-0040 참조 — 이번 scope 밖.
+
+## [0.1.2] — 2026-05-26
+
+전 BC 라이브 smoke (PAT, 실 백엔드 20개 호출) 로 발견한 authz 경로·응답 drift 수정 (ADR-0039). 나머지 BC(identity·tenants·apps·audit·gateway)는 라이브에서 정상 확인.
+
+### BREAKING
+
+- `authz.{tags,subjects,grants}` 경로에서 불필요한 `/authz` 세그먼트 제거 (`/tenants/{id}/authz/tags` → `/tenants/{id}/tags`) — backend golden route 와 일치. 이전엔 전부 404 였음 (라이브 검증: tags 5 / subjects 1 / grants 24 반환).
+- `authz.{tags,subjects,grants}.list()` 반환 `PaginatedList<T>` → `T[]` — backend 가 bare array 반환 (gateway ADR-0036 와 동일). 이전엔 404 라 동작 caller 없었음. Migration: `(await authz.tags.list()).items` → `await authz.tags.list()`.
+
+### Known follow-ups (ADR-0039)
+
+- `authz.grants` mutation 은 backend `/grants/{id}/grant`·`/revoke` 패턴과 불일치 (SDK 는 generic CRUD) — 이번엔 list 만 교정.
+- `authz.evaluator.decide/decideMany` 는 backend 라우트 미존재 (404) — 백엔드 구현 또는 제거 결정 필요.
+
+## [0.1.1] — 2026-05-26
+
+라이브 백엔드 smoke (0.1.0 gateway 전 기능 18개) 로 발견한 `isSqlFormatError` 오분류 수정.
+
+### Fixed
+
+- `isSqlFormatError` 가 라이브 deny 형식 `"SQL 형식 오류: safesql: ...only SELECT or WITH allowed (got \"delete\")"` 를 정상 인식. 이전엔 `safesql:` prefix 만 `startsWith` 매칭해, 백엔드가 한국어 prefix 로 감싼 실제 응답을 놓치고 SQL 형식 오류를 policy deny 로 오분류했음. 이제 `startsWith('SQL 형식 오류:') || includes('safesql:')` 로 양쪽 매칭 (ADR-0038 정정 — spec 의 `"SQL 형식 오류:"` prefix 가 옳았음). 나머지 gateway 표면(catalog list/get/invoke/hasAccess/helpers·query.run·governance)은 라이브에서 정상 확인.
+
+## [0.1.0] — 2026-05-25
+
+backend SPEC 307 (catalog + invoke) 를 SDK 에 반영 (ADR-0038). member-facing 데이터 카탈로그 표면 신규. 기존 governance API signature 불변 (additive minor).
+
+### Added
+
+- `gateway.catalog` (`GatewayCatalogClient`) — member-facing: `listKinds()` / `listConnectors()` / `listResources(filter?)` / `getResource(connector, path)` / `invoke(connector, path, {sql, params, rowLimit})` + `hasAccess()` / `listResourcesWithDetail()`. governance (connectors/resources/engines/query) 와 분리.
+- `gateway.catalog.getResource` 는 권한 없는/존재 안 하는 path 에 `NotFoundError` throw (strict zero-trust — 권한 없음과 부재 구별 안 함). boolean 확인은 `hasAccess`.
+- `gateway.catalog.invoke` 의 policy deny 는 throw 아닌 `{ allowed: false, denyReason }` response (HTTP 200).
+- 응답/경로 helper: `isAllowed` · `isPolicyDeny` · `isSqlFormatError` · `getAccessibleColumns` · `getMaskHint` · `tableFromPath`.
+- 타입: `CatalogKind` · `CatalogKindAction` · `CatalogConnector` · `CatalogResourceView` · `CatalogResourceDetail` · `CatalogPermissionsReadList` · `CatalogPermissionsReadDetail` · `CatalogAncestor` · `CatalogTag` · `CatalogResourceFilter` · `InvokeInput` · `InvokeResult`.
+
+### Changed (docs only — signature 불변)
+
+- `authz.{tags,subjects,grants}.list` + `gateway.{connectors,resources}` (governance) 에 `@adminOnly` JSDoc — v0.1 backend 에서 member → `ForbiddenError` (자동 retry 무의미). member 는 `gateway.catalog` 사용.
+- `query.run` JSDoc: catalog `allowedColumns` 외 column 참조 시 외부 DB column-not-found 가 500 `InternalServerError` 로 전달 (no auto-retry); deny 의미 (generic policy vs `safesql:` SQL-format) 명시.
+
+### Notes
+
+- spec 의 `isSqlFormatError` 제안 리터럴 `"SQL 형식 오류:"` 는 backend 실제 prefix `"safesql:"` 로 교정 (ADR-0038). string-prefix 매칭은 brittle — helper JSDoc 경고.
+- spec §3.2 의 `query` `@deprecated` 제안은 backend `/gateway/query` 제거 계획이 없어 보류 (`@see catalog.invoke` soft note).
+- PAT (`identity.pat`, spec §5.3) 는 이 SDK 에 미노출 → out of scope.
+
+## [0.0.6] — 2026-05-25
+
+ADR-0036 이 남긴 gateway drift follow-up 정리 (ADR-0037). 0.0.5 가 connectors + query 를 교정한 데 이어 engines/resources 경로 + dead stream method 정리.
+
+### BREAKING
+
+- `gateway.query.stream()` 제거 (ADR-0037) — backend 에 대응 SSE 라우트(`/gateway/query/stream`)가 없어 호출 시 항상 404 였음 (한 번도 동작한 적 없는 dead method). Migration: 단발 조회는 `gateway.query.run()` 사용. 스트리밍 조회는 backend 미지원.
+
+### Fixed
+
+- `gateway.resources.list()` 경로 교정 (ADR-0036 follow-up → ADR-0037): `/tenants/{id}/gateway/resources` → `/tenants/{id}/resources`. 기존 경로는 backend 404. connectors 와 동일한 tenant-root 패턴 (대칭 회복). 호출 코드 변경 없음 (SDK 내부 경로).
+- `gateway.engines.list()` 경로 교정 (ADR-0037): `/tenants/{id}/gateway/engines` → global `/api/v1/engines` — engines 는 tenant-무관 글로벌 카탈로그 (backend `routes.go`). 접근자(`tenant(t).gateway.engines`)는 BC 위해 유지, URL 만 global. 호출 코드 변경 없음.
+
+### Added
+
+- `TenantGatewayClient` export (ADR-0037) — `sdk.tenant(id).gateway` 의 반환 타입. helper 의 반환 타입 주석에 사용 가능 (이전엔 미export 라 추론에만 의존).
+
+## [0.0.5] — 2026-05-25
+
+### BREAKING
+
+- `gateway.connectors.list()` / `gateway.resources.list()` 반환 `PaginatedList<T>` → `T[]` — backend gateway list 엔드포인트가 pagination 봉투 없이 bare array 반환 (ADR-0036). Migration: `const { items } = await tenant.gateway.connectors.list()` → `const items = await tenant.gateway.connectors.list()` (cursor/total 처리 제거).
+- `gateway.connectors` 경로가 tenant root 로 이동 (`/tenants/{id}/gateway/connectors` → `/tenants/{id}/connectors`) — 기존 경로는 backend 에서 404 였음 (ADR-0036). 호출 코드 변경 없음 (SDK 내부 경로).
+- `GatewayQueryResult` 모양 변경 (ADR-0036): `{ rows, rowCount, auditEventId }` → `{ allowed, denyReason?, columns, rows, rowCount, matchedPolicies? }`. `auditEventId` 제거 (backend query 응답에 없어 항상 undefined 였음). `query.run` 이 backend 의 positional `rows: [][]any` + `columns` 를 객체 배열로 zip — 이전엔 `rows` 가 `Row[]` 로 타입됐지만 실제론 매핑 안 된 배열이었음. Migration: `res.rows[i].colName` 이 이제 실제 동작; `res.auditEventId` 사용처 제거; policy deny 는 `res.allowed === false` + `res.denyReason` 로 확인.
+
+### Internal
+
+- **harness revamp (2026-05-22)** — agent-first SDK 유지보수 인프라 신규 구축. 회사 인계 + 신규 maintainer 대비.
+  - `AGENTS.md` rewrite: 8 BC + 16 invariants + BC-specific rules summary + verification matrix + workflow + anti-patterns. LLM-agnostic (Claude/Codex/Cursor 모두 root에서 자동 인식).
+  - `CLAUDE.md`에 `<!-- sdk-rules:start -->...<!-- sdk-rules:end -->` managed block 추가. GitNexus block과 분리.
+  - per-domain `CLAUDE.md` × 7: `src/resources/`, `src/resources/apps/`, `src/resources/data/`, `src/errors/`, `codegen/`, `tests/`, `scripts/`. Claude Code 작업 디렉토리 자동 컨텍스트.
+  - `docs/decisions/` ADR catalog (MADR format) × 35: `.plan/` 31+ 결정을 영구 보존. `README.md` 인덱스.
+  - `docs/MAINTAINING.md`: 회사 인수자 onboarding (week 1 / month 3 / month 12 milestones + first PR walkthrough + common pitfalls).
+  - `lefthook.yml` pre-commit: priority 1 `build:raw` 후 priority 2 `typecheck`/`test:unit`/`extract-codes`/`route-inventory-diff`/`check:size:fast`/`check:dist-wire:fast` parallel. race-free.
+  - `package.json` `prepare: lefthook install` — `npm install` 시 hook 자동 설치. `lefthook` devDep 추가.
+  - `check:size:fast` + `check:dist-wire:fast` script variants — pre-commit용 (build 호출 안 함, dist/ exists guard 추가).
+  - `tests/lefthook-smoke/` × 6 fixture + `run.sh` + `.github/workflows/lefthook-smoke.yml`: invariant 위반 패턴 (한국어 substring, mock parity, cursor v2 bypass, BC boundary, redaction leak, prototype pollution)이 실제 차단되는지 PR마다 검증.
+  - `.github/PULL_REQUEST_TEMPLATE.md`: 16 invariant checklist + ADR link field + verification checklist.
+  - `.plan/` 삭제 — rationale은 `docs/decisions/` ADR로 영구 이관.
+  - `TODOS.md` deferred to v1.1+: sdk-onboard skill, harness-fidelity eval, extract-decisions automation, AGENTS↔ADR sync script, ADR index 자동 생성.
+
+## [0.0.4] — 2026-05-22
+
+PR #12 종합 리뷰 (8 ce reviewers) 결과 반영 — D36 scope freeze 명시적 override (2026-05-22). 75 finding → 25 distinct → 8 stories.
+
+### BREAKING
+
+- `list()` `nextCursor` wire format — `orderBy`/`after`/`before` 또는 v2 cursor 입력 시 `v2:<base64-url>` 키셋 토큰 반환. 기존 순수 정수 cursor 는 plain page 호환을 위해 계속 수용되지만 `v1:` 접두사 토큰은 이제 `LegacyCursorError` throw.
+- `list()` 진입부 `cursor` 검증 강화 — v2/v1 접두사 아닌 cursor 가 정수가 아니면 `InvalidCursorError` throw (silent NaN 폴백 차단).
+- `v2:` cursor 토큰에 `contextFingerprint` (tenant+app+table SHA8) 가 SDK 측에서 주입되며 디코드 시 mismatch 면 `InvalidCursorError` throw — 다른 테이블의 cursor 재생 차단.
+- `v2:` cursor 토큰 size 상한 `MAX_CURSOR_TOKEN_LENGTH=4096` — 초과 시 `InvalidCursorError` (base64 DoS 가드).
+- mock `get/update/delete` 가 `NotFoundError` throw — 실 백엔드 404 동작과 일치 (이전: `get` = null cast, `delete` = silent). drop-in parity 의 핵심 누락 해소.
+- mock `insert` 가 중복 id 시 `ConflictError` (code=`duplicate_key`, httpStatus=409) throw — 이전: 일반 `Error`. `instanceof AxHubError` 분기를 가진 호출자가 mock/real 일관 처리 가능.
+- `defineSchema().validate` 타입이 `unknown` → `ZodSchemaLike` 로 좁혀짐 — 잘못된 입력 컴파일 단계 차단.
+
+### Added
+
+- `ScanLimitExceededError` (`InternalServerError` 계열, code=`scan_limit_exceeded`) — `count({where})` 가 100K 행 스캔 한도 초과 시, `discover()` app-id fallback 이 10 페이지 한도 초과 시 throw.
+- `MAX_CURSOR_TOKEN_LENGTH` 상수 export.
+- `assertCursorMatchesContext` 함수 — SDK 자체에서 cursor scope 검증.
+- `KeysetCursor.contextFingerprint` 옵션 필드, `CursorBuildOptions.contextFingerprint` 옵션.
+- `PaginatedList.totalIsExact?: boolean` — `where` 적용 + 백엔드 미푸시다운 시 `false` 마킹, caller 가 page-당 partial count 임을 인지 가능.
+- `assertSafeLikePattern()` + `MAX_LIKE_PATTERN_LENGTH`/`MAX_CONSECUTIVE_WILDCARDS`/`MAX_LIKE_ALTERNATION_SEGMENTS` 상수 — `like.raw()` 진입부에서 ReDoS 패턴 거부.
+
+### Changed
+
+- `assertMockModeAllowed()` — `NODE_ENV` 대소문자/공백 정규화 (`'Production '` / `'PRODUCTION'` 인식), `AX_HUB_ALLOW_MOCK_IN_PROD` 가 `'1'/'true'/'yes'/'on'` (대소문자/공백 무시) truthy 파싱.
+- `SchemaCache` 5xx 응답 시 30 초 negative TTL 로 이전 stale 엔트리 보존 (stale-while-error) → degraded backend 동안 thundering herd 방지. `negativeTtlMs` 옵션으로 조정 가능 (default `DEFAULT_SCHEMA_CACHE_NEGATIVE_TTL_MS = 30000`).
+- `SchemaCache.getOrSet` 가 monotonic write token 으로 stale-write race 차단 — `fresh:true` 추월이 stale `set` 으로 overwrite 못 함.
+- `SchemaCache.getOrSet` 가 loader rejection 시 즉시 inflight 키 evict (다음 콜러 retry 가능). transient 5xx 만 stale entry 복원.
+- `count({where})` 가 page 크기 100 → 1000 + 최대 100 페이지 (10만 행) 스캔 상한 + 매 iteration `signal.aborted` 검사.
+- `discover()` app-id 폴백 (`resolveAppId`) 가 5 초 총 budget + `signal` per-page threading + 빈 첫 페이지 즉시 `TableNotFoundError` + 페이지 한도 초과 시 `ScanLimitExceededError`.
+- `inferSchemaFromRows` UUID 정규식 RFC4122 정확 (`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`) — 이전 `[0-9a-f-]{27,}` false-positive 제거.
+- `src/mock/index.ts` wildcard `export *` 제거 → `createMockStore`/`assertMockModeAllowed`/`MockClientOptions`/`MockStore`/`MockFixtures`/`MockSchemas`/`MockRow` 만 named export. DSL evaluator/CRUD 핸들러/페이지네이션/projection internal 화.
+- `src/mock/projection.ts` 단일 라인 re-export 파일 삭제 (consumer 들이 `src/resources/data/projection.js` 직접 import).
+- `schemaFromInspectResult` 가 `__proto__`/`constructor`/`prototype` 등 위험 컬럼명 거부 + identifier-shape regex 검증 (defense-in-depth, prototype pollution 시나리오 봉쇄).
+- mock `paginateRows` 가 cursor tiebreaker row 가 삭제된 경우 page1 silent 재출력 대신 `InvalidCursorError` throw.
+- mock pagination 의 plain cursor 가 정수 아니면 `InvalidCursorError` throw.
+
+### Fixed
+
+- DSL 평가 single truth — `src/resources/data/index.ts` 의 `matchesWhere`/`compare`/`likeToRegExp`/`escapeRegExp` 4 함수 삭제. live + mock 양쪽이 `src/mock/dsl-evaluator.ts` 의 `evaluateWhere` 만 사용 (D32a). `eq null` 등 PG NULL trinary 가 양쪽 일관.
+- mock `evaluateWhere` 의 `gt/gte/lt/lte` 가 null 측 명시적 false 분기 — 이전 `compare` NaN 의존 → 명시적 PG trinary 매핑.
+- `PaginatedList.hasPrev` 가 v2 cursor 폴백 경로 (`opts.cursor && isV2Cursor`) 포함 — 이전: `after`/`before` 직접 입력 시만 true.
+- `PaginatedList.total` 이 `where` 모드 시 잘못된 `items.length` (페이지 당 매치 카운트) 가 아닌 백엔드 `raw.total` (unfiltered) + `totalIsExact:false` 마킹 — caller 가 자체 inference 가능.
+- mock `count` / `list` 응답에 `totalIsExact: true` 마킹 (전수 in-memory 평가).
+
+### Verification
+
+- `npm run typecheck`
+- `npm run test`
+- `npm run build`
+- `npm run check:size`
+- `npm run check:dist-wire`
+- `npm run readme:doctest`
+
+## [1.0.0-rc.1] — 2026-05-21
+
+SDK master-plan implementation across foundation, identity/tenants, authz/audit/gateway, data DSL, codegen, webhook/idempotency, and DevEx gates.
+
+### Breaking
+
+- Build output is now minified to keep the ESM main bundle under the 100KB budget.
+
+### Migration
+
+```ts
+// Before (0.x aliases, kept for compatibility until RC cleanup)
+await sdk.identity.issuePersonalAccessToken({ name: 'ci' })
+
+// Preferred
+await sdk.identity.pat.issue({ name: 'ci' })
+```
+
+Run `node --experimental-strip-types codemods/0.x-to-1.0.ts <files...>` for textual alias migration.
+
+### Added
+
+- `sdk.tenant(slug)` / `sdk.tenant(slug).app(appSlug)` scoped clients.
+- `sdk.tenants` members, invitations, email domains, icon upload.
+- `sdk.identity.pat`, `oauth`, `oidc`, `deviceCode`, `idp`, and `systemOAuthClients` sub-namespaces.
+- `sdk.authz`, `sdk.audit`, `sdk.gateway`, and `sdk.data` bounded-context clients.
+- Type-safe data DSL: `defineSchema`, `where`, `and/or/not`, `raw`, `escapeLike`.
+- Dynamic data advanced track: `data.discover()` runtime introspection with per-client schema cache; optional Zod-compatible `defineSchema(..., { validate })`; `select` projection with `Pick<>` narrowing; v2 keyset cursor helpers (`after`/`before`, `firstCursor`, `hasNext`/`hasPrev`); and `mode: "mock"` fixture-backed data clients with 55-scenario parity coverage.
+- Webhook HMAC verification with timestamp tolerance and replay cache.
+- Codegen outputs under `codegen/generated/` plus route inventory drift checks.
+- DevEx utilities: `bench:tthw`, `check:size`, minimal `ax-hub-sdk doctor`, opt-in E2E smoke test, README-ko, examples.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run test`
+- `npm run build`
+- `npm run generate`
+- `npm run extract-codes`
+- `npm run route-inventory-diff`
+- `npm run check:size`
+
+## [0.2.0] — 2026-05-15
+
+apps SDK expansion. Phase 1 aha demo (`apps.create` + `deployments` + auth) extends to publication workflow, social loop (likes/comments/access), schema admin (tables/grants), oauth-clients, git connection, icon upload, and admin review namespace. 28 / 28 apps backend context endpoints covered.
+
+### Added
+
+- **Publication workflow**: `sdk.apps.publication.submit/list/unpublish` (owner) + `sdk.publicationRequests.get/approve/reject/listPending` (reviewer/admin) — full state machine for `draft → pending_review → approved → public`.
+- **Social loop**: `sdk.apps.likes.like/unlike/me` (idempotent — backend returns `inserted` / `deleted` booleans), `sdk.apps.comments.add/list/listAll/delete` (1-500 char client-side validation, paginated iterator), `sdk.apps.access.grant/revoke/me` (self-grant; `me()` returns `null` for 404).
+- **Schema admin**: `sdk.apps.tables.list/create/delete/addColumn/dropColumn/listGrants/addGrant/revokeGrant`. Table name regex `^[a-z][a-z0-9_]{0,62}$` validated client-side via `validateTableName`.
+- **OAuth clients**: `sdk.apps.oauthClients.create/delete`. `create` returns `clientSecret` raw — **surfaced exactly once**, store immediately (PAT pattern).
+- **Git connection**: `sdk.apps.git.connect/installStart` — GitHub App install flow + repo binding.
+- **App lifecycle additions**: `sdk.apps.permanent` (hard-purge soft-deleted app), `sdk.apps.signIconUploadURL`/`signIconDarkUploadURL` (presigned PUT), `sdk.apps.listMine` (apps caller has access to, distinct from tenant-scoped `list`).
+- **Error subclasses** (19 new): `AlreadyRevokedError`, `AlreadySettledError`, `AlreadyActiveError`, `AlreadyInactiveError`, `AlreadyAccessedError`, `NotDeletedError`, `LastAdminError`, `PendingExistsError`, `InvalidStateTransitionError`, `SchemaNameTakenError`, `DomainTakenError`, `DuplicateError`, `NotMemberError`, `NotAllowedError`, `InvalidValueError`, `RequiredError`, `EmptyError`, `BadRequestError`, `AppUnavailableError`. All mapped from backend `codes.go` (b7d2e6a).
+- **`validateTableName`** helper in `src/utils/slug.ts`.
+- **`examples/social-app-demo.ts`** — end-to-end publication workflow + social loop demo.
+
+### Coverage
+
+- 28 / 28 apps backend context endpoints (100%).
+- 9 new integration test files: publication, access, likes, comments, tables, oauth-clients, git, publication-requests, plus apps-flow extensions.
+- Test count: 73 → 130+ tests.
+
+### NOT in this release
+
+- **Data API** (`/data/{tenantSlug}/{appSlug}/{table}/*`) — runtime CRUD against tables you created via `tables.*`. Backend dispatcher Phase 2 dependency. Workaround in v0.2: use `sdk.http.request` directly for raw fetch. Tracked for v0.2.2.
+- **Tenants context** (`sdk.tenants.*`, `categories`) — next PR.
+- **Identity OAuth admin** — Identity BC namespace, separate PR.
+- MCP server bundle (v1.1), browser bundle (v1.2).
+
+### Backend dependencies
+
+- Pinned against backend `main` HEAD `b7d2e6a` (apps dispatcher on spec 278 신형식). `schema` BC dispatcher legacy — `tables.*` relies on HTTP-status fallback for category dispatch; specific subclass mapping may miss until backend completes Phase 2 dispatcher migration.
+
+---
+
+## [0.1.0] — 2026-05-14
+
+Initial Phase 1 development. v0.1.0 release.
+
+### Added
+
+- `AxHubClient` with PAT and JWT auth modes (+ JWT refresh dedupe)
+- Backend wrapped envelope error dispatch (spec 278 land): 9 category base classes (`ValidationError`, `UnauthenticatedError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `PreconditionFailedError`, `RateLimitedError`, `InternalServerError`, `UnavailableError`) + 10 specific code subclasses (`SlugTakenError`, `TokenExpiredError`, `NotAdminError`, `PermanentlyDeletedError`, …)
+- OAuth RFC 6749 separate dispatch path (`OAuthError` + specific codes for Device Flow)
+- SSE async iterator with client-side dedupe + gap detection (Phase 0 finding: backend hub.go ignores `Last-Event-ID`)
+- Pagination `listAll` async iterator with drift event emission
+- Rate limit handling — `Retry-After` honor, `'sleep' | 'throw'` strategies
+- `X-Request-Id` (ULID) auto-injection per request, surfaced on every `AxHubError.requestId`
+- Tenant scoping — `defaultTenantSlug`, `withTenant`, `TenantSlugRequiredError`
+- Resources: `sdk.apps.*` (CRUD + env-vars, directory split), `sdk.deployments.*` (lifecycle + 3 SSE streams), `sdk.identity.*` (PAT issuance, me)
+- Injectable logger interface + Authorization/X-Api-Key/Cookie redaction
+- Dual ESM/CJS build via tsup, strict TypeScript, vitest test runner
+
+### Coverage
+
+- 73 tests (60 unit + 13 integration)
+- 18 / 77 backend endpoints (aha demo path). Phase 2 fills out remaining 59.
+
+### Known limitations
+
+- Backend `Last-Event-ID` on SSE not honored; SDK dedupes + emits `GapDetectedEvent`. Backend follow-up issue tbd.
+- Backend `Idempotency-Key` not supported; SDK does not auto-inject and refuses to retry POST/PATCH/DELETE.
+- MCP server bundle (v1.1), browser bundle (v1.2), CLI tool, OpenTelemetry native: deferred.
+- `codegen/extract-codes.ts` was still unwired — `src/errors/code-map.ts` was a hand-written stub mirroring backend `codes.go` registry.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 jocoding-ax-partners
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.