@simplysm/sd-claude 14.0.98 → 14.0.100

package/claude/references/sd-simplysm14/apis/service-client/README.md

@@ -1,39 +1,39 @@
 # @simplysm/service-client
 
-WebSocket 으로 서비스 서버에 접속해 서비스 RPC 호출·서버 푸시 이벤트 구독/발행·파일 업/다운로드·서버측 ORM 원격 실행을 수행하는 클라이언트. 브라우저와 Node.js 양쪽에서 동작(Node 에서 글로벌 `WebSocket` 이 없으면 모듈 로드 시 `ws` 로 polyfill).
+WebSocket 으로 서비스 서버에 붙어 서비스 메서드 RPC 호출·서버 푸시 이벤트 구독/발행·파일 업/다운로드·서버측 ORM 원격 실행을 수행하는 클라이언트. 브라우저·Node.js 양쪽에서 동작하며, Node 에서 글로벌 `WebSocket` 이 없으면 소켓 모듈 로드 시점에 `ws` 패키지로 polyfill 한다.
 
 ## 사용 트리거 인덱스
 
-- **createServiceClient / ServiceClient** — 서버 접속, 서비스 호출, 인증, 연결 상태 추적이 필요할 때. 이 패키지의 주 진입점. (아래 인라인 섹션)
-- **ServiceConnectionOptions** — 클라이언트 생성 시 접속 대상(host/port/ssl)·재연결 정책을 정할 때. (아래 인라인 섹션)
-- **getService / ServiceProxy** — 서버 서비스 인터페이스를 타입 안전 프록시로 호출할 때. (아래 인라인 섹션)
-- **이벤트 구독·발행 (addListener / removeListener / emitEvent / getEvent / ClientEventProxy / EventClient)** — 서버 푸시 이벤트를 구독·발행할 때. (아래 인라인 섹션)
-- **파일 업/다운로드 (uploadFile / downloadFileBuffer / FileClient)** — 인증된 파일 업로드, 서버 상대경로 파일 다운로드 시. (아래 인라인 섹션)
-- **진행률 (ServiceProgress / ServiceProgressState)** — 대용량 요청·응답의 청크 전송 진행률을 추적할 때. (아래 인라인 섹션)
-- **환경 호환 타입·헬퍼 (BlobInput / FileCollection / BrowserWorker / isWorkerSupported 등)** — Node/browser 공용 코드에서 DOM 전용 타입 회피, Worker 지원 분기 시. (아래 인라인 섹션)
-- **ORM 원격 실행 (createOrmClientConnector / OrmClientConnector / OrmConnectOptions / OrmClientDbContextExecutor)** — 서버측 ORM DbContext 를 클라이언트에서 트랜잭션 단위로 실행할 때. 자세히: [orm.md](./orm.md)
-- **저수준 전송 계층 (SocketProvider / ServiceTransport / ClientProtocolWrapper 및 create\*)** — 일반적으로 직접 쓰지 않음. `ServiceClient` 가 내부에서 조립. 소켓·하트비트·프로토콜·청크 동작을 이해해야 할 때. 자세히: [transport.md](./transport.md)
+- **createServiceClient / ServiceClient** — 서버 접속·서비스 호출·인증·연결 상태 추적의 주 진입점. (아래 인라인)
+- **ServiceConnectionOptions** — 접속 대상(host/port/ssl)·재연결 정책 지정. (아래 인라인)
+- **getService / ServiceProxy** — 서버 서비스를 타입 안전 프록시로 호출. (아래 인라인)
+- **이벤트 구독·발행 (getEvent / addListener / removeListener / emitEvent / ClientEventProxy / EventClient)** — 서버 푸시 이벤트 구독·발행. (아래 인라인)
+- **파일 업/다운로드 (uploadFile / downloadFileBuffer / FileClient)** — 인증 업로드, 서버 상대경로 다운로드. (아래 인라인)
+- **진행률 (ServiceProgress / ServiceProgressState)** — 청크 분할되는 대용량 요청/응답의 진행 추적. (아래 인라인)
+- **환경 호환 타입·헬퍼 (BlobInput / FileCollection / BrowserWorker / isBrowserWorkerSupported / isNodeWorkerSupported / isWorkerSupported)** — Node/browser 공용 코드의 DOM 타입 회피·Worker 분기. (아래 인라인)
+- **ORM 원격 실행 (createOrmClientConnector / OrmClientConnector / OrmConnectOptions / OrmClientDbContextExecutor)** — 서버 DbContext 를 클라이언트에서 트랜잭션 단위로 실행. 자세히: [orm.md](./orm.md)
+- **저수준 전송 계층 (SocketProvider / ServiceTransport / ClientProtocolWrapper 및 create\*)** — `ServiceClient` 가 내부에서 조립하는 소켓·하트비트·프로토콜·청크 모듈. 직접 쓰지 않음. 자세히: [transport.md](./transport.md)
 
-> 앱(Angular) 레이어에서는 `ServiceClient` 를 화면에서 직접 만들지 않고 `AppServiceProvider`(root provider) 의 `client` getter 를 경유해 서비스·이벤트·ORM 진입점을 모은다. 아래 예시는 client 직접 호출 형태로 보여주지만, 실제 앱 코드는 manuals/client-service.md·client-orm.md 의 provider 패턴을 따른다.
+> 앱(Angular)에서는 화면이 `ServiceClient` 를 직접 만들지 않고 `AppServiceProvider`(root provider)의 `client` getter 를 경유해 서비스·이벤트·ORM 진입점을 모은다. 아래 예시는 client 직접 호출 형태지만, 실제 앱 코드는 manuals/client-service.md·client-orm.md·event.md 의 provider 패턴을 따른다.
 
 ## 메인 클라이언트 (createServiceClient / ServiceClient)
 
 `createServiceClient(name, options): ServiceClient` — 클라이언트 인스턴스 생성. `new ServiceClient(name, options)` 와 동일.
 
-- name: string — 클라이언트 식별 이름. WebSocket 접속 쿼리의 `clientName`·파일 업로드 헤더 `x-sd-client-name` 으로 서버에 전달. 서버 로그·연결 구분에 사용.
-- options: ServiceConnectionOptions — 접속 대상·재연결 정책 (아래 섹션).
+- `name: string` — 클라이언트 식별 이름. WebSocket 접속 쿼리의 `clientName`·파일 업로드 헤더 `x-sd-client-name` 으로 서버에 전달. 서버측 연결 구분·로깅용.
+- `options: ServiceConnectionOptions` — 접속 대상·재연결 정책 (아래 섹션).
 
 `ServiceClient` 는 `EventEmitter<ServiceClientEvents>` 를 상속하며 다음을 노출:
 
-- name: string (readonly) — 생성 시 받은 클라이언트 이름.
-- options: ServiceConnectionOptions (readonly) — 생성 시 받은 접속 옵션.
-- connected: boolean (getter) — 현재 WebSocket 이 OPEN 상태인지. 재연결 중·종료 시 false. 이벤트 등록 가능 여부 판단에 사용 (`addListener` 는 false 면 throw).
-- hostUrl: string (getter) — `http(s)://host:port` 형태의 HTTP 베이스 URL. `ssl` 이 true 면 https. 파일 업/다운로드가 이 URL 을 베이스로 사용.
-- connect(): Promise\<void\> — 서버에 WebSocket 연결. 초기 연결 실패 시 throw. 통신(서비스 호출·이벤트 등록) 전에 반드시 1회 호출.
-- close(): Promise\<void\> — 연결 수동 종료(이후 자동 재연결 안 함) 및 프로토콜 워커 자원 해제. 종료한 인스턴스는 재사용하지 말 것.
-- send(serviceName, methodName, params, progress?): Promise\<unknown\> — 저수준 서비스 호출. `serviceName.methodName` 메시지를 보내고 응답 반환. 보통 `getService` 프록시로 간접 호출. progress 인자를 주지 않아도 client 의 `request/response/server-progress` 이벤트는 항상 발생.
-- auth(token): Promise\<void\> — 인증 토큰 전송 후 내부 보관. 보관 토큰은 재연결 시 자동 재인증·파일 업로드 Bearer 인증에 재사용. 파일 업로드 전에는 반드시 선행.
-- getService / getEvent / addListener / removeListener / emitEvent / uploadFile / downloadFileBuffer — 아래 각 섹션 참조.
+- `name: string` (readonly) — 생성 시 받은 이름.
+- `options: ServiceConnectionOptions` (readonly) — 생성 시 받은 접속 옵션.
+- `connected: boolean` (getter) — 소켓이 OPEN 상태인지. 재연결 중·종료 시 false. `addListener` 는 false 면 throw 하므로 등록 가능 여부 판단에 사용.
+- `hostUrl: string` (getter) — `ssl` 이면 `https://`, 아니면 `http://` 로 시작하는 `프로토콜://host:port` HTTP 베이스 URL. 파일 업/다운로드가 이 URL 을 베이스로 사용.
+- `connect(): Promise<void>` — 서버에 WebSocket 연결. 초기 연결 실패 시 throw. 모든 통신(서비스 호출·이벤트 등록) 전에 1회 호출.
+- `close(): Promise<void>` — 연결 수동 종료(이후 자동 재연결 안 함) 후 프로토콜 워커 자원 해제(`protocolWrapper.dispose()`). 종료한 인스턴스는 재사용하지 않음.
+- `send(serviceName, methodName, params, progress?): Promise<unknown>` — 저수준 서비스 호출. `serviceName.methodName` 메시지를 보내고 응답 반환. 보통 `getService` 프록시로 간접 호출. progress 인자를 주지 않아도 client 의 `request/response/server-progress` 이벤트는 항상 발생.
+- `auth(token): Promise<void>` — 인증 토큰을 서버에 전송하고 내부 보관. 보관 토큰은 재연결 시 자동 재인증·파일 업로드 Bearer 인증에 재사용됨. 파일 업로드 전 선행 필수.
+- `getService / getEvent / addListener / removeListener / emitEvent / uploadFile / downloadFileBuffer` — 아래 각 섹션.
 
 ```ts
 const client = createServiceClient("my-app", { host: "localhost", port: 50080, ssl: false });
@@ -43,10 +43,10 @@ await client.auth(jwtToken);
 
 **ServiceClientEvents** (EventEmitter 이벤트):
 
-- "request-progress": ServiceProgressState — 요청(업로드) 청크 진행률. 요청 본문이 청크 2개 이상으로 분할될 때만 발생.
-- "response-progress": ServiceProgressState — 응답(다운로드) 청크 수신 진행률. 분할 응답 완료 시 100% 한 번 더 보고.
-- "server-progress": ServiceProgressState — 서버가 처리 중 직접 보고하는 진행률(서버측 `progress` 메시지 수신 시).
-- "state": "connected" | "closed" | "reconnecting" — 연결 상태 변화. "connected" = 연결/재연결 성공(이 전이 시 보관 토큰으로 자동 재인증 + 이벤트 리스너 자동 복구), "closed" = 정상 종료 또는 재연결 한도 초과, "reconnecting" = 재연결 시도 중. 오프라인 배너 토글 등에 사용.
+- `"request-progress": ServiceProgressState` — 요청(업로드) 청크 진행률. 요청 본문이 청크 2개 이상으로 분할될 때만 발생.
+- `"response-progress": ServiceProgressState` — 응답(다운로드) 청크 수신 진행률. 분할 응답이면 완료 시 100% 를 한 번 더 보고.
+- `"server-progress": ServiceProgressState` — 서버가 처리 중 보고하는 진행률(서버측 `name: "progress"` 메시지 수신 시).
+- `"state": "connected" | "closed" | "reconnecting"` — 연결 상태 전이. `"connected"` = 연결/재연결 성공(이 전이 시 보관 토큰으로 자동 재인증 + 등록 리스너 자동 복구), `"closed"` = 정상 종료 또는 재연결 한도 초과, `"reconnecting"` = 재연결 시도 중. 오프라인 배너 토글 등에 사용.
 
 ```ts
 client.on("state", (s) => { if (s === "reconnecting") showOfflineBanner(); });
@@ -56,50 +56,50 @@ client.on("state", (s) => { if (s === "reconnecting") showOfflineBanner(); });
 
 `createServiceClient` 의 두 번째 인자.
 
-- port: number — 서버 포트. 필수.
-- host: string — 서버 호스트. 필수.
-- ssl?: boolean — TLS 사용 여부. true 면 `wss`/`https`, false·미지정이면 `ws`/`http`. TLS 서버에 붙을 때만 true.
-- maxReconnectCount?: number — 연결 끊김 시 최대 재연결 시도 횟수. 미지정 시 10. 0 이면 재연결 비활성화(끊기면 즉시 포기). 테스트·단발성 연결이면 0.
+- `port: number` — 서버 포트. 필수.
+- `host: string` — 서버 호스트. 필수.
+- `ssl?: boolean` — TLS 사용 여부. true 면 `wss`/`https`, false·미지정이면 `ws`/`http`. TLS 서버에 붙을 때만 true.
+- `maxReconnectCount?: number` — 연결 끊김 시 최대 재연결 시도 횟수. 미지정 시 10. 0 이면 재연결을 비활성화하고 끊기면 즉시 포기. 테스트·단발성 연결이면 0.
 
 ## getService / ServiceProxy
 
-서버 서비스 인터페이스의 각 메서드를 `Promise` 반환 함수로 노출하는 타입 안전 프록시.
+서버 서비스의 각 메서드를 `Promise` 반환 함수로 노출하는 타입 안전 프록시.
 
-`getService<TService>(serviceName): ServiceProxy<TService>` — `serviceName` 으로 등록된 서버 서비스의 프록시 반환. 프록시 메서드 호출은 내부적으로 `client.send(serviceName, 메서드명, 인자배열)` 로 위임.
+`getService<TService>(serviceName): ServiceProxy<TService>` — `serviceName` 으로 등록된 서버 서비스의 프록시 반환. 프록시 메서드 호출은 내부적으로 `client.send(serviceName, 메서드명, 인자배열)` 로 위임(`Proxy` 기반, 모든 속성 접근을 비동기 RPC 함수로 변환).
 
-- TService — 서버 서비스 메서드 인터페이스 타입. 컴파일 타임 시그니처 검증용(런타임 검증 아님). 앱에선 server 패키지가 export 한 `ServiceMethods<typeof XxxService>` 사용.
-- serviceName: string — 서버의 `defineService("XxxName", ...)` 이름과 일치해야 함.
-- ServiceProxy\<TService\> — TService 의 각 함수 멤버를 `(...args) => Promise<Awaited<R>>` 로 매핑하는 타입 변환기. 원본이 동기 반환이어도 Promise 로 래핑됨. 함수 아닌 속성은 `never` 로 제외.
+- `TService` — 서버 서비스 메서드 인터페이스 타입. 컴파일 타임 시그니처 검증 전용(런타임 검증 아님). 앱에선 server 패키지가 export 한 `ServiceMethods<typeof XxxService>` 사용.
+- `serviceName: string` — 서버의 `defineService("XxxName", ...)` 이름과 일치해야 함.
+- `ServiceProxy<TService>` — `TService` 의 각 함수 멤버를 `(...args) => Promise<Awaited<R>>` 로 매핑하는 타입 변환기. 원본이 동기 반환이어도 Promise 로 래핑. 함수 아닌 속성은 `never` 로 제외.
 
 ```ts
 const svc = client.getService<TestServiceMethods>("TestService");
-const result = await svc.echo("hi"); // 서버 TestService.echo("hi") 호출, Promise<string>
+const result = await svc.echo("hi"); // 서버 TestService.echo("hi") 호출 → Promise<string>
 ```
 
-## 이벤트 구독·발행 (addListener / removeListener / emitEvent / getEvent)
+## 이벤트 구독·발행 (getEvent / addListener / removeListener / emitEvent)
 
-서버 푸시 이벤트는 `@simplysm/service-common` 의 `defineEvent` 산출물(`ServiceEventDef`. `$info` = 구독 필터 정보 타입, `$data` = 페이로드 타입) 단위로 다룬다. 등록한 리스너는 재연결 시 자동 복구됨.
+서버 푸시 이벤트는 `@simplysm/service-common` 의 `defineEvent` 산출물(`ServiceEventDef`. `$info` = 구독 필터 정보 타입, `$data` = 페이로드 타입) 단위로 다룬다. 등록한 리스너는 재연결 시 자동 재구독된다.
 
 `addListener<TEventDef>(eventDef, info, cb): Promise<string>` — 리스너 등록. 미연결(`connected === false`)이면 throw("서버에 연결되지 않았습니다."). 반환 key 로 나중에 제거.
 
-- eventDef: TEventDef — 이벤트 정의(`defineEvent` 결과). `$info`/`$data` 타입의 출처.
-- info: TEventDef["$info"] — 이 구독을 식별·필터링할 정보. 발행측 selector 가 이 값을 보고 전달 여부 결정.
-- cb: (data: $data) => PromiseLike\<void\> — 이벤트 수신 콜백. 콜백 내 예외는 로깅만 되고 호출부로 전파되지 않음.
+- `eventDef: TEventDef` — 이벤트 정의(`defineEvent` 결과). `$info`/`$data` 타입의 출처이자 라우팅 키(`eventName`).
+- `info: TEventDef["$info"]` — 이 구독을 식별·필터링할 정보. 발행측 selector 가 이 값을 보고 전달 여부 결정.
+- `cb: (data: $data) => PromiseLike<void>` — 이벤트 수신 콜백. 콜백 내 예외는 로깅만 되고 호출부로 전파되지 않음.
 
-`removeListener(key): Promise<void>` — 등록 key 로 리스너 제거. 서버 전송 실패(연결 끊김 등)는 무시(서버가 끊김 시 리스너를 자동 정리하므로 안전).
+`removeListener(key): Promise<void>` — 등록 key 로 리스너 제거(로컬 맵 삭제 + 서버 `evt:remove` 전송). 서버 전송 실패(연결 끊김 등)는 무시 — 서버가 끊김 시 리스너를 자동 정리하므로 안전.
 
 `emitEvent<TEventDef>(eventDef, infoSelector, data): Promise<void>` — 이벤트 발행. 서버에서 동일 이벤트 구독자 목록을 조회한 뒤 `infoSelector(info)` 가 true 인 대상에게만 data 전송. 매칭 대상이 0개면 전송 자체를 생략.
 
-- infoSelector: (item: $info) => boolean — 발행 대상 구독자를 info 기준으로 필터. true 반환 구독자에게만 전달. 전체 전송이면 `() => true`.
-- data: TEventDef["$data"] — 전송 페이로드.
+- `infoSelector: (item: $info) => boolean` — 발행 대상 구독자를 info 기준으로 필터. true 반환 구독자에게만 전달. 전체 전송이면 `() => true`.
+- `data: TEventDef["$data"]` — 전송 페이로드.
 
 `getEvent<TEventDef>(eventDef): ClientEventProxy<TEventDef>` — 특정 eventDef 에 바인딩된 프록시 반환. eventDef 를 매번 넘기지 않고 짧게 쓰려 할 때(앱의 `AppServiceProvider.xxxEvent` getter 패턴).
 
 `ClientEventProxy<TEventDef>` 멤버(위 client 메서드의 eventDef 고정판):
 
-- addListener(info, cb): Promise\<string\> — 리스너 등록.
-- removeListener(key): Promise\<void\> — 리스너 제거.
-- emit(infoSelector, data): Promise\<void\> — 이벤트 발행.
+- `addListener(info, cb): Promise<string>` — 리스너 등록.
+- `removeListener(key): Promise<void>` — 리스너 제거.
+- `emit(infoSelector, data): Promise<void>` — 이벤트 발행.
 
 ```ts
 const chatEvent = defineEvent<{ channel: string }, string>("Chat");
@@ -108,17 +108,17 @@ await client.emitEvent(chatEvent, (info) => info.channel === "room1", "hello");
 await client.removeListener(key);
 ```
 
-`EventClient` / `createEventClient(transport)` 는 `ServiceClient` 가 내부 조립에 쓰는 저수준 구현. 위 메서드(getEvent/addListener/removeListener/emit)에 더해 `resubscribeAll(): Promise<void>`(보관된 모든 리스너를 서버에 재등록, 재연결 복구용)를 가짐. 일반 사용에선 직접 만들지 않음.
+`EventClient` / `createEventClient(transport)` 는 `ServiceClient` 가 내부 조립에 쓰는 저수준 구현. 위 메서드(getEvent/addListener/removeListener/emit)에 더해 `resubscribeAll(): Promise<void>`(보관된 모든 리스너를 서버에 재등록, 재연결 복구용. 항목별 실패는 로깅 후 계속)를 가짐. 일반 사용에선 직접 만들지 않음.
 
 ## 파일 업/다운로드 (uploadFile / downloadFileBuffer)
 
-`uploadFile(files): Promise<ServiceUploadResult[]>` — `POST <hostUrl>/upload` (multipart/form-data) 로 파일 업로드. 보관 토큰을 `Authorization: Bearer` 헤더로 전송하므로 사전 `auth()` 필수(미인증 시 throw). 응답 비정상 시 throw.
+`uploadFile(files): Promise<ServiceUploadResult[]>` — `POST <hostUrl>/upload` (multipart/form-data) 로 파일 업로드. 보관 토큰을 `Authorization: Bearer` 헤더로 전송하므로 사전 `auth()` 필수(보관 토큰 없으면 throw). 응답 비정상(`!res.ok`) 시 throw.
 
-- files: `File[] | FileCollection | { name: string; data: BlobInput }[]` — 업로드 대상. 브라우저 `File` 배열, `FileCollection`(FileList 호환), 또는 `{ name, data }` 커스텀 객체 배열. 커스텀 객체의 data 가 `Blob` 이 아니면 `new Blob([data])` 로 감싸 전송.
+- `files: File[] | FileCollection | { name: string; data: BlobInput }[]` — 업로드 대상. 브라우저 `File` 배열, `FileCollection`(FileList 호환), 또는 `{ name, data }` 커스텀 객체 배열. 커스텀 객체의 data 가 `Blob` 이 아니면 `new Blob([data])` 로 감싸 전송.
 
 `downloadFileBuffer(relPath): Promise<Bytes>` — `<hostUrl>/<relPath>` 를 GET 해 `Uint8Array` 반환. 응답 비정상(`!res.ok`) 시 throw.
 
-- relPath: string — 서버 기준 상대경로. 선행 `/` 유무 모두 허용(없으면 자동으로 `/` 추가).
+- `relPath: string` — 서버 기준 상대경로. 선행 `/` 유무 모두 허용(없으면 자동으로 `/` 보정).
 
 ```ts
 await client.auth(token);
@@ -134,15 +134,15 @@ const bytes = await client.downloadFileBuffer("/files/a.txt");
 
 `ServiceProgress` — `send(..., progress)` 에 넘기는 콜백 집합(해당 호출 단건 추적용, 전역 이벤트와 별개). 각 콜백은 `(s: ServiceProgressState) => void`:
 
-- request? — 요청 청크 업로드 진행 시 호출. 요청 청크가 2개 이상일 때만 발생.
-- response? — 응답 청크 수신 진행 시 호출. 분할 응답이었으면 완료 시 100%(`completedSize === totalSize`)를 한 번 더 보고.
-- server? — 서버가 처리 중 보고한 진행률 수신 시 호출(`name: "progress"` 메시지).
+- `request?` — 요청 청크 업로드 진행 시 호출. 요청 청크가 2개 이상일 때만 발생.
+- `response?` — 응답 청크 수신 진행 시 호출. 분할 응답이었으면 완료 시 100%(`completedSize === totalSize`)를 한 번 더 보고.
+- `server?` — 서버가 처리 중 보고한 진행률 수신 시 호출(서버측 `name: "progress"` 메시지).
 
 `ServiceProgressState` — 진행률 스냅샷.
 
-- uuid: string — 해당 요청/응답 식별자. 동시 요청 구분용.
-- totalSize: number — 전체 바이트 수.
-- completedSize: number — 완료 바이트 수. `completedSize === totalSize` 면 완료.
+- `uuid: string` — 해당 요청/응답 식별자. 동시 요청 구분용.
+- `totalSize: number` — 전체 바이트 수.
+- `completedSize: number` — 완료 바이트 수. `completedSize === totalSize` 면 완료.
 
 전역 추적이면 콜백 대신 ServiceClient 의 `request/response/server-progress` 이벤트(`client.on("response-progress", ...)`)를 써도 됨 — `send` 는 progress 인자 유무와 무관하게 이 이벤트들을 항상 발생시킴.
 
@@ -154,9 +154,9 @@ client.on("response-progress", (s) => updateBar(s.completedSize / s.totalSize));
 
 Node/browser 공용 코드에서 DOM 전용 타입을 피하고 Worker 지원 여부를 분기하기 위한 타입·함수. 프로토콜 인코딩/파싱 Worker 오프로딩 판단 시 내부에서 사용.
 
-- BlobInput = `Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string` — `Blob` 생성자가 받는 데이터 타입(DOM `BlobPart` 대체). `uploadFile` 의 커스텀 객체 data 타입.
-- FileCollection (interface) — DOM `FileList` 대체. `length`, `item(index): File | null`, 인덱스 접근, `[Symbol.iterator]` 보유. 브라우저 `FileList` 와 구조적 호환.
-- BrowserWorker (interface) — DOM `Worker` 최소 인터페이스(`onmessage`/`onerror` 핸들러, `postMessage(message, transfer?)`, `terminate()`). DOM lib 없이 타입체크 통과용.
-- isBrowserWorkerSupported(): boolean — `globalThis` 에 `Worker` 존재 여부 반환. 브라우저 DOM Worker 가용 판단.
-- isNodeWorkerSupported(): boolean — `process.versions.node` 존재 여부 반환. Node `worker_threads` 가용 판단.
-- isWorkerSupported(): boolean — 위 둘 중 하나라도 true 면 true. 프로토콜 인코딩/파싱 오프로딩 가능 여부 판단(미지원 시 메인 스레드 폴백).
+- `BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string` — `Blob` 생성자가 받는 데이터 타입(DOM `BlobPart` 대체). `uploadFile` 커스텀 객체의 data 타입.
+- `FileCollection` (interface) — DOM `FileList` 대체. `length`, `item(index): File | null`, 인덱스 접근, `[Symbol.iterator]` 보유. 브라우저 `FileList` 와 구조적 호환.
+- `BrowserWorker` (interface) — DOM `Worker` 최소 인터페이스(`onmessage`/`onerror` 핸들러, `postMessage(message, transfer?)`, `terminate()`). DOM lib 없이 타입체크 통과용.
+- `isBrowserWorkerSupported(): boolean` — `globalThis` 에 `Worker` 존재 여부 반환. 브라우저 DOM Worker 가용 판단.
+- `isNodeWorkerSupported(): boolean` — `process.versions.node` 존재 여부 반환. Node `worker_threads` 가용 판단.
+- `isWorkerSupported(): boolean` — 위 둘 중 하나라도 true 면 true. 프로토콜 인코딩/파싱 오프로딩 가능 여부 판단(미지원 시 메인 스레드 폴백).

package/claude/references/sd-simplysm14/apis/service-client/orm.md

@@ -1,8 +1,8 @@
 # @simplysm/service-client — ORM 원격 실행
 
-서버측 ORM DbContext 를 클라이언트에서 원격으로 실행하는 묶음. 쿼리 자체는 서버 `Orm` 서비스가 DB 에 대해 수행하고, 클라이언트는 커넥션·트랜잭션·쿼리 정의(`QueryDef`)만 RPC 로 전송한다. 쿼리는 `connect`/`connectWithoutTransaction` 콜백 내부에서만 가능. ORM 작업을 트랜잭션 경계로 묶어 실행할 때 함께 읽힌다.
+서버측 ORM DbContext 를 클라이언트에서 원격 실행하는 묶음. 쿼리 자체는 서버 `Orm` 서비스가 DB 에 대해 수행하고, 클라이언트는 커넥션·트랜잭션·쿼리 정의(`QueryDef`)만 RPC 로 전송한다. 쿼리는 `connect`/`connectWithoutTransaction` 콜백 내부에서만 가능. ORM 작업을 트랜잭션 경계로 묶어 실행할 때 함께 읽힌다.
 
-> 앱(Angular)에서는 `OrmConnectOptions`(DbClass·connOpt·dbContextOpt)를 화면에 흩뿌리지 않고 `AppOrmProvider`(root provider) 한 곳에 고정한 뒤 `connectAsync`/`connectWithoutTransAsync` 만 호출한다. 쿼리 작성법은 apis/orm-common 참조. 아래 예시는 connector 직접 호출 형태지만 실제 앱은 manuals/client-orm.md 의 provider 패턴을 따른다.
+> 앱(Angular)에서는 `OrmConnectOptions`(DbClass·connOpt·dbContextOpt)를 화면에 흩뿌리지 않고 `AppOrmProvider`(root provider) 한 곳에 고정한 뒤 `connectAsync` 만 호출한다. 쿼리 작성법은 apis/orm-common·manuals/orm.md 참조. 아래 예시는 connector 직접 호출 형태지만 실제 앱은 manuals/client-orm.md 의 provider 패턴을 따른다.
 
 ## createOrmClientConnector / OrmClientConnector
 
@@ -10,13 +10,13 @@
 
 `OrmClientConnector` 메서드:
 
-- connect<T, R>(config, callback): Promise\<R\> — 트랜잭션 안에서 callback 실행. DbContext 생성 → `db.connect(...)`(connect + beginTransaction + callback + commit/rollback) 수행. callback 정상 반환 시 커밋(반환값이 그대로 반환됨), throw 시 롤백되어 콜백 내 다건 작업이 원자 처리됨. callback 에서 발생한 에러 중 외래키 제약 위반 메시지(MySQL `a parent row: a foreign key constraint` / MSSQL `conflicted with the REFERENCE` / PostgreSQL `violates foreign key constraint`)는 "경고! 연관된 작업으로 인해 작업이 거부되었습니다. 후속 작업을 확인해 주세요." 로 감싸 `SdError` 로 throw(원본은 cause 에 보존), 그 외 에러는 그대로 throw.
-- connectWithoutTransaction<T, R>(config, callback): Promise\<R\> — 트랜잭션 없이 callback 실행(`db.connectWithoutTransaction`). 트랜잭션 안에서 동작하지 않는 작업(예: DB initialize)·조회 전용 작업에 사용. callback 반환값이 그대로 반환됨. 외래키 메시지 래핑 없음.
+- `connect<T, R>(config, callback): Promise<R>` — 트랜잭션 안에서 callback 실행. DbContext 생성 → `db.connect(...)`(connect + beginTransaction + callback + commit/rollback) 수행. callback 정상 반환 시 커밋(반환값이 그대로 메서드 반환값), throw 시 롤백되어 콜백 내 다건 작업이 원자 처리됨. callback 에서 발생한 에러 중 외래키 제약 위반 메시지(MySQL `a parent row: a foreign key constraint` / MSSQL `conflicted with the REFERENCE` / PostgreSQL `violates foreign key constraint`)는 "경고! 연관된 작업으로 인해 작업이 거부되었습니다. 후속 작업을 확인해 주세요." 로 감싼 `SdError` 로 throw(원본은 cause 에 보존), 그 외 에러는 그대로 throw.
+- `connectWithoutTransaction<T, R>(config, callback): Promise<R>` — 트랜잭션 없이 callback 실행(`db.connectWithoutTransaction`). 트랜잭션 안에서 동작하지 않는 작업(예: DB initialize)·조회 전용 작업에 사용. callback 반환값이 그대로 반환됨. 외래키 메시지 래핑 없음.
 
 공통 인자:
 
-- config: OrmConnectOptions\<T\> — 아래 섹션. DbContext 클래스·서버 ORM 설정·DB명/스키마.
-- callback: (db: T) => Promise\<R\> | R — 생성·연결된 DbContext 를 받아 쿼리하는 콜백. 동기/비동기 반환 모두 허용.
+- `config: OrmConnectOptions<T>` — 아래 섹션. DbContext 클래스·서버 ORM 설정·DB명/스키마.
+- `callback: (db: T) => Promise<R> | R` — 생성·연결된 DbContext 를 받아 쿼리하는 콜백. 동기/비동기 반환 모두 허용.
 
 ```ts
 const connector = createOrmClientConnector(client);
@@ -30,24 +30,24 @@ const rows = await connector.connect(
 
 `connect`/`connectWithoutTransaction` 의 첫 인자. DbContext 1회 실행에 필요한 설정.
 
-- DbClass: `new (executor, opt) => T` — 실행할 DbContext 클래스 생성자. `executor`(아래 `OrmClientDbContextExecutor`)와 `{ database, schema? }` 를 받아 인스턴스화됨. 앱별 DbContext(예: `MainDbContext`)를 그대로 전달.
-- connOpt: `DbConnOptions & { configName: string }` — 서버측 ORM 연결 설정. `configName` 은 서버에 등록된 ORM 설정 이름(서버가 이 이름으로 실제 DB 접속 정보를 찾음). 나머지 필드는 `@simplysm/service-common` 의 `DbConnOptions`.
-- dbContextOpt?: `{ database: string; schema?: string }` — DbContext 에 적용할 DB명·스키마. 생략 시 서버 `getInfo()` 가 돌려준 `database`/`schema` 를 사용. database 가 옵션·서버 양쪽 모두 비어 있으면 throw("database는 필수입니다." — 결측을 임의 보정하지 않음).
-  - database: string — 대상 데이터베이스명.
-  - schema?: string — 대상 스키마명. 미지정 시 서버 `getInfo()` 의 schema 를 사용.
+- `DbClass: new (executor, opt) => T` — 실행할 DbContext 클래스 생성자. `executor`(아래 `OrmClientDbContextExecutor`)와 `{ database, schema? }` 를 받아 인스턴스화됨. 앱별 DbContext(예: `MainDbContext`)를 그대로 전달.
+- `connOpt: DbConnOptions & { configName: string }` — 서버측 ORM 연결 설정. `configName` 은 서버에 등록된 ORM 설정 이름(서버가 이 이름으로 실제 DB 접속 정보를 찾음). 나머지 필드는 `@simplysm/service-common` 의 `DbConnOptions`.
+- `dbContextOpt?: { database: string; schema?: string }` — DbContext 에 적용할 DB명·스키마. 생략 시 서버 `getInfo()` 가 돌려준 `database`/`schema` 를 사용. database 가 옵션·서버 양쪽 모두 비어 있으면 throw("database는 필수입니다." — 결측을 임의 보정하지 않음).
+  - `database: string` — 대상 데이터베이스명.
+  - `schema?: string` — 대상 스키마명. 미지정 시 서버 `getInfo()` 의 schema 를 사용.
 
 ## OrmClientDbContextExecutor
 
 `DbContextExecutor`(`@simplysm/orm-common`) 구현체. 모든 메서드를 `client.getService<OrmService>("Orm")` RPC 로 위임. 커넥터가 내부에서 DbContext 에 주입하므로 직접 생성·호출은 보통 불필요.
 
-`new OrmClientDbContextExecutor(client, opt)` — 생성. opt = `DbConnOptions & { configName: string }`. 생성 시 `Orm` 서비스 프록시 확보. 아래 connect 이외의 실행 메서드는 connId 가 없으면(미연결) throw("데이터베이스에 연결되지 않았습니다.").
-
-- getInfo(): `Promise<{ dialect; database?; schema? }>` — 서버 ORM 설정 정보(방언·기본 DB명·스키마) 조회. 커넥터가 dbContextOpt 미지정 시 fallback 으로 사용.
-- connect(): Promise\<void\> — 서버에 커넥션 생성, 반환된 connId 를 내부 보관. 이후 트랜잭션·쿼리 호출의 핸들.
-- beginTransaction(isolationLevel?): Promise\<void\> — 트랜잭션 시작. isolationLevel(orm-common `IsolationLevel`) 미지정 시 서버 기본값.
-- commitTransaction(): Promise\<void\> — 트랜잭션 커밋.
-- rollbackTransaction(): Promise\<void\> — 트랜잭션 롤백.
-- close(): Promise\<void\> — 커넥션 종료 후 보관 connId 해제.
-- executeDefs\<T\>(defs, options?): Promise\<T[][]\> — 쿼리 정의 배열(`QueryDef[]`)을 서버에서 실행. options 는 정의별 결과 매핑 메타(`(ResultMeta | undefined)[]`, 항목별 nullable)로 행 역직렬화 방식 지정. 정의 1개당 결과 배열 1개를 가진 2차원 배열 반환.
-- executeParametrized(query, params?): Promise\<unknown[][]\> — 파라미터 바인딩 raw SQL 실행. query = SQL 문자열, params = 바인딩 값 배열.
-- bulkInsert(tableName, columnDefs, records): Promise\<void\> — 대량 삽입. tableName = 대상 테이블명, columnDefs(`Record<string, ColumnMeta>`)로 컬럼별 메타를, records(`Record<string, unknown>[]`)로 삽입할 행 객체 배열을 전달.
+`new OrmClientDbContextExecutor(client, opt)` — 생성. `opt = DbConnOptions & { configName: string }`. 생성 시 `Orm` 서비스 프록시 확보. 아래 `getInfo`/`connect` 이외의 실행 메서드는 connId 가 없으면(미연결) throw("데이터베이스에 연결되지 않았습니다.").
+
+- `getInfo(): Promise<{ dialect; database?; schema? }>` — 서버 ORM 설정 정보(방언·기본 DB명·스키마) 조회. 커넥터가 dbContextOpt 미지정 시 fallback 으로 사용.
+- `connect(): Promise<void>` — 서버에 커넥션 생성, 반환된 connId 를 내부 보관. 이후 트랜잭션·쿼리 호출의 핸들.
+- `beginTransaction(isolationLevel?): Promise<void>` — 트랜잭션 시작. `isolationLevel`(orm-common `IsolationLevel`) 미지정 시 서버 기본값.
+- `commitTransaction(): Promise<void>` — 트랜잭션 커밋.
+- `rollbackTransaction(): Promise<void>` — 트랜잭션 롤백.
+- `close(): Promise<void>` — 커넥션 종료 후 보관 connId 해제.
+- `executeDefs<T>(defs, options?): Promise<T[][]>` — 쿼리 정의 배열(`QueryDef[]`)을 서버에서 실행. `options` 는 정의별 결과 매핑 메타(`(ResultMeta | undefined)[]`, 항목별 nullable)로 행 역직렬화 방식 지정. 정의 1개당 결과 배열 1개를 가진 2차원 배열 반환.
+- `executeParametrized(query, params?): Promise<unknown[][]>` — 파라미터 바인딩 raw SQL 실행. `query` = SQL 문자열, `params` = 바인딩 값 배열.
+- `bulkInsert(tableName, columnDefs, records): Promise<void>` — 대량 삽입. `tableName` = 대상 테이블명, `columnDefs`(`Record<string, ColumnMeta>`)로 컬럼별 메타, `records`(`Record<string, unknown>[]`)로 삽입할 행 객체 배열을 전달.

package/claude/references/sd-simplysm14/apis/service-client/transport.md

@@ -1,52 +1,52 @@
 # @simplysm/service-client — 저수준 전송 계층
 
-`ServiceClient` 가 생성자에서 내부적으로 조립하는 저수준 모듈들. WebSocket 연결·하트비트·재연결(SocketProvider), 요청/응답 매칭과 메시지 디스패치(ServiceTransport), 인코딩/디코딩의 Worker 오프로딩(ClientProtocolWrapper). 일반 사용에서는 `ServiceClient` 만 쓰면 되며, 이 계층은 소켓·청크·하트비트 동작을 이해해야 할 때만 읽는다.
+`ServiceClient` 가 생성자에서 내부적으로 조립하는 저수준 모듈들. WebSocket 연결·하트비트·자동 재연결(SocketProvider), 요청/응답 uuid 매칭과 메시지 디스패치(ServiceTransport), 인코딩/디코딩의 Worker 오프로딩(ClientProtocolWrapper). 일반 사용에서는 `ServiceClient` 만 쓰면 되며, 이 계층은 소켓·청크·하트비트 동작을 이해해야 할 때만 읽는다.
 
 ## SocketProvider / createSocketProvider
 
 WebSocket 1개의 연결·하트비트·자동 재연결 담당.
 
-`createSocketProvider(url, clientName, maxReconnectCount): SocketProvider` — 프로바이더 생성. Node 환경에서 글로벌 `WebSocket` 이 없으면 모듈 로드 시 `ws` 패키지로 polyfill.
+`createSocketProvider(url, clientName, maxReconnectCount): SocketProvider` — 프로바이더 생성. 이 모듈은 import 시점에 글로벌 `WebSocket` 이 없으면 `ws` 패키지로 polyfill 한다(Node 환경).
 
-- url: string — `ws(s)://host:port/ws`. 접속 시 `ver=2`, 생성된 `clientId`(UUID), `clientName` 쿼리를 붙임.
-- clientName: string — 접속 쿼리에 실리는 식별명.
-- maxReconnectCount: number — 최대 재연결 시도 횟수. 0 이면 재연결 안 함.
+- `url: string` — `ws(s)://host:port/ws`. 접속 시 `ver=2`, 생성된 `clientId`(UUID), `clientName` 쿼리를 붙임.
+- `clientName: string` — 접속 쿼리에 실리는 식별명.
+- `maxReconnectCount: number` — 최대 재연결 시도 횟수. 0 이면 재연결 안 함.
 
-내부 상수: 하트비트 ping 5초 간격, 30초 무수신 시 타임아웃, 재연결 3초 간격. 1바이트 `0x01` ping 전송, `0x02` pong 수신은 무시(타임스탬프만 갱신).
+내부 상수: ping 5초 간격 전송, 30초 무수신 시 타임아웃, 재연결 3초 간격. 1바이트 `0x01` ping 전송, 수신한 1바이트 `0x02` pong 은 무시(하트비트 타임스탬프만 갱신).
 
-멤버:
+`SocketProvider` 멤버:
 
-- clientName: string (readonly) — 생성 시 받은 식별명.
-- connected: boolean (getter) — 소켓이 OPEN 상태인지.
-- connect(): Promise\<void\> — 접속 시작. 실패 시 throw, 성공 시 재연결 카운트 리셋하고 `state: "connected"` emit.
-- close(): Promise\<void\> — 수동 종료. 이후 자동 재연결 안 함. 소켓 CLOSED 까지 대기 후 `state: "closed"` emit.
-- send(data: Bytes): Promise\<void\> — 바이트 전송. 일정 시간 내 미연결이면 throw("서버에 연결되지 않았습니다. 인터넷 연결을 확인해 주세요.").
-- on(type, listener) / off(type, listener) — 이벤트 구독/해제.
+- `clientName: string` (readonly) — 생성 시 받은 식별명.
+- `connected: boolean` (getter) — 소켓이 OPEN 상태인지.
+- `connect(): Promise<void>` — 접속 시작. 실패 시 throw, 성공 시 재연결 카운트 리셋 후 `state: "connected"` emit.
+- `close(): Promise<void>` — 수동 종료. 이후 자동 재연결 안 함. 소켓 CLOSED 까지 대기 후 `state: "closed"` emit.
+- `send(data: Bytes): Promise<void>` — 바이트 전송. 일정 시간 내 미연결이면 throw("서버에 연결되지 않았습니다. 인터넷 연결을 확인해 주세요.").
+- `on(type, listener)` / `off(type, listener)` — 이벤트 구독/해제.
 
 `SocketProviderEvents`:
 
-- message: Bytes — 수신 바이트(ping/pong 1바이트 제어 프레임 제외).
-- state: "connected" | "closed" | "reconnecting" — 연결 상태 변화. "connected" = 연결/재연결 성공, "closed" = 수동 종료 또는 재연결 한도 초과, "reconnecting" = 재연결 시도 중.
+- `message: Bytes` — 수신 바이트(1바이트 ping/pong 제어 프레임 제외).
+- `state: "connected" | "closed" | "reconnecting"` — 연결 상태 전이. `"connected"` = 연결/재연결 성공, `"closed"` = 수동 종료 또는 재연결 한도 초과, `"reconnecting"` = 재연결 시도 중.
 
-하트비트 타임아웃 감지 시 소켓을 강제 정리하고(늦은 onclose 로 인한 중복 재연결 방지를 위해 핸들러 해제) 수동 종료가 아니면 재연결을 시도. 최대 시도 초과 시 `state: "closed"` emit.
+하트비트 타임아웃 감지 시 소켓을 강제 정리하고(늦은 `onclose` 로 인한 중복 재연결 방지를 위해 핸들러 해제) 수동 종료가 아니면 재연결을 시도. 재연결은 재귀 대신 루프로 수행하며 최대 시도 초과 시 `state: "closed"` emit.
 
 ## ServiceTransport / createServiceTransport
 
 요청별 uuid 매칭, 응답/에러/진행률/서버이벤트 디스패치 담당.
 
-`createServiceTransport(socket, protocol): ServiceTransport` — 트랜스포트 생성. 소켓 `message` 를 받아 decode 후 종류별 분기. 소켓이 `closed`/`reconnecting` 되면 대기 중인 모든 요청을 reject(메모리 해제).
+`createServiceTransport(socket, protocol): ServiceTransport` — 트랜스포트 생성. 소켓 `message` 를 받아 decode 후 종류별 분기. 소켓이 `closed`/`reconnecting` 되면 대기 중인 모든 요청을 reject("요청 취소됨: ...") 하여 메모리 해제.
 
-- socket: SocketProvider — 하위 소켓.
-- protocol: ClientProtocolWrapper — 인코드/디코드 래퍼.
+- `socket: SocketProvider` — 하위 소켓.
+- `protocol: ClientProtocolWrapper` — 인코드/디코드 래퍼.
 
-멤버:
+`ServiceTransport` 멤버:
 
-- send(message, progress?): Promise\<unknown\> — 요청 1건 전송 후 응답 Promise 반환. uuid 생성 → 리스너 등록 → encode → 청크 순차 전송. 응답(`response`) 수신 시 resolve, 에러(`error`) 수신 시 서버 에러 필드를 머지한 `Error` 로 reject. message = `ServiceClientMessage`, progress = `ServiceProgress`(선택).
-- on(type, listener) / off(type, listener) — 이벤트 구독/해제.
+- `send(message, progress?): Promise<unknown>` — 요청 1건 전송 후 응답 Promise 반환. uuid 생성 → 리스너 선등록 → encode → 청크 순차 전송. 응답(`response`) 수신 시 resolve, 에러(`error`) 수신 시 서버 에러 필드를 머지한 `Error` 로 reject. `message = ServiceClientMessage`, `progress = ServiceProgress`(선택).
+- `on(type, listener)` / `off(type, listener)` — 이벤트 구독/해제.
 
 `ServiceTransportEvents`:
 
-- event: `{ keys: string[]; data: unknown }` — 서버가 푸시한 `evt:on` 메시지. `EventClient` 가 이걸 구독해 keys 에 매칭되는 로컬 리스너로 디스패치.
+- `event: { keys: string[]; data: unknown }` — 서버가 푸시한 `evt:on` 메시지. `EventClient` 가 이걸 구독해 keys 에 매칭되는 로컬 리스너로 디스패치.
 
 decode 실패 시에도 헤더 16바이트에서 uuid 를 선추출해 해당 요청만 reject. 분할 응답이면 완료 시 `progress.response` 로 100% 를 한 번 더 보고. 서버측 진행 메시지(`name: "progress"`)는 `progress.server` 로 전달.
 
@@ -56,6 +56,10 @@ decode 실패 시에도 헤더 16바이트에서 uuid 를 선추출해 해당
 
 `createClientProtocolWrapper(protocol): ClientProtocolWrapper` — 래퍼 생성.
 
-- encode(uuid, message): Promise\<{ chunks: Bytes[]; totalSize: number }\> — 메시지를 청크 배열로 인코드. body 가 Uint8Array, 30KB 초과 문자열, 길이 100 초과 배열, 또는 첫 항목이 Uint8Array 인 배열이면 Worker 사용. message = `ServiceMessage`.
-- decode(bytes): Promise\<ServiceMessageDecodeResult\<ServiceMessage\>\> — 수신 바이트 디코드. 청크 재조립(stateful)은 한 메시지의 청크가 흩어지지 않도록 항상 메인 스레드 단일 누적기에서 수행하고(#35), 재조립 완료 후 30KB 초과 JSON 파싱(stateless)만 Worker 에 위임. 미완료(progress) 상태면 그대로 반환.
-- dispose(): void — 프로토콜과 Worker 리졸버 정리. `ServiceClient.close()` 에서 호출.
+`ClientProtocolWrapper` 멤버:
+
+- `encode(uuid, message): Promise<{ chunks: Bytes[]; totalSize: number }>` — 메시지를 청크 배열로 인코드. body 가 `Uint8Array`, 30KB 초과 문자열, 길이 100 초과 배열, 또는 첫 항목이 `Uint8Array` 인 배열이면 Worker 사용(그 외·Worker 미가용 시 메인 스레드). `message = ServiceMessage`.
+- `decode(bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>` — 수신 바이트 디코드. 청크 재조립(stateful)은 한 메시지의 청크가 서로 다른 누적기로 흩어지지 않도록 항상 메인 스레드 단일 누적기에서 수행하고(#35), 재조립 완료 후 30KB 초과 JSON 파싱(stateless)만 Worker 에 위임. 미완료(progress) 상태면 그대로 반환.
+- `dispose(): void` — 프로토콜과 Worker 리졸버 정리. `ServiceClient.close()` 에서 호출.
+
+Worker 는 browser DOM Worker 또는 Node `worker_threads` 중 가용한 쪽을 lazy 초기화하며, Worker 작업이 60초 내 응답하지 않으면 해당 작업을 시간 초과로 reject 한다.

package/claude/references/sd-simplysm14/apis/service-common/README.md

@@ -1,6 +1,6 @@
 # @simplysm/service-common
 
-서버·클라이언트가 공유하는 서비스 통신 계약. 이벤트 정의(`defineEvent`), 내장 RPC 서비스 인터페이스 시그니처, 앱 메뉴·권한·모듈 구조(`AppStructure`), WebSocket 바이너리 프로토콜·메시지 타입을 한곳에 둔다. 발생측·구독측 또는 서버·클라이언트가 같은 정의 객체·타입을 import 해 쓰는 게 핵심.
+서버·클라이언트가 공유하는 서비스 통신 계약. 실시간 이벤트 정의(`defineEvent`), 내장 RPC 서비스 인터페이스 시그니처, 앱 메뉴·권한·모듈 구조(`AppStructure`), WebSocket 바이너리 프로토콜·메시지 타입을 한곳에 둔다. 발생측·구독측 또는 서버·클라이언트가 같은 정의 객체·타입을 import 해 쓰는 게 핵심.
 
 ## 사용 트리거 인덱스
 
@@ -21,9 +21,9 @@
 function defineEvent<TInfo = unknown, TData = unknown>(eventName: string): ServiceEventDef<TInfo, TData>
 ```
 
-- `TInfo` (제네릭) — 구독자가 "무엇을 구독하는지" 식별하는 메타데이터 타입. 발생측 selector 가 이 값을 보고 전달 대상을 골라냄. 미지정 시 `unknown`. 예: `{ warehouseId: number }`.
-- `TData` (제네릭) — 이벤트가 실어 나르는 페이로드 타입. 구독 콜백이 받는 인자 타입. 미지정 시 `unknown`. 예: `{ orderId: number; status: string }`.
-- `eventName` (인자) — 라우팅 키 문자열. 같은 이름이면 같은 이벤트로 취급되므로 앱 내에서 고유해야 함.
+- `TInfo` (제네릭) — 구독자가 "무엇을 구독하는지" 식별하는 메타데이터 타입. 발생측 selector 가 이 값을 보고 전달 대상을 골라냄. 미지정 시 `unknown`.
+- `TData` (제네릭) — 이벤트가 실어 나르는 페이로드 타입. 구독 콜백이 받는 인자 타입. 미지정 시 `unknown`.
+- `eventName` (인자) — 라우팅 키 문자열. `ServiceEventDef.eventName` 에 그대로 들어가며 런타임에 실제로 쓰이는 유일한 값. 같은 이름이면 같은 이벤트로 취급되므로 앱 내에서 고유해야 함.
 - 반환된 `ServiceEventDef` 를 그대로 발생·구독 API 의 첫 인자로 넘기면 이름·타입이 추론됨.
 
 ```ts
@@ -49,8 +49,8 @@ interface ServiceEventDef<TInfo = unknown, TData = unknown> {
 ```
 
 - `eventName: string` — 라우팅 키. `defineEvent` 인자가 그대로 들어가며 런타임에 실제로 쓰이는 유일한 값.
-- `$info: TInfo` (readonly) — `TInfo` 타입 추출 전용 phantom 마커. 런타임 값은 `undefined`(사용되지 않음). 발생·구독 API 가 이 마커로 `TInfo` 를 끌어다 씀.
-- `$data: TData` (readonly) — `TData` 타입 추출 전용 phantom 마커. 런타임 값은 `undefined`(사용되지 않음). 직접 읽지 말 것.
+- `$info: TInfo` (readonly) — `TInfo` 타입 추출 전용 마커. 런타임 값은 `undefined`(사용되지 않음). 발생·구독 API 가 이 마커로 `TInfo` 를 끌어다 씀. 직접 읽지 말 것.
+- `$data: TData` (readonly) — `TData` 타입 추출 전용 마커. 런타임 값은 `undefined`(사용되지 않음). 직접 읽지 말 것.
 
 ## 내장 RPC 서비스 시그니처 (OrmService / AutoUpdateService)
 
@@ -82,7 +82,7 @@ interface OrmService {
 - `rollbackTransaction(connId)` — 트랜잭션 취소.
 - `executeParametrized(connId, query, params?)` — 파라미터 바인딩 raw SQL 직접 실행. `params` 는 플레이스홀더에 순서대로 바인딩(없으면 바인딩 없는 쿼리). 결과는 결과셋별 행 배열(`unknown[][]`).
 - `executeDefs(connId, defs, options?)` — ORM 코어가 만든 `QueryDef` 배열을 일괄 실행. `options[i]` 는 `defs[i]` 결과셋의 컬럼 파싱 메타(`ResultMeta`)로, 메타 불필요한 def 자리는 `undefined`.
-- `bulkInsert(connId, tableName, columnDefs, records)` — 다건 레코드 대량 삽입. `columnDefs` 는 컬럼명→`ColumnMeta`(타입·인코딩) 매핑, `records` 는 삽입할 행 배열.
+- `bulkInsert(connId, tableName, columnDefs, records)` — 다건 레코드 대량 삽입. `columnDefs` 는 컬럼명→`ColumnMeta` 매핑, `records` 는 삽입할 행 배열.
 
 `Dialect`/`IsolationLevel`/`QueryDef`/`ColumnMeta`/`ResultMeta` 는 `@simplysm/orm-common` 타입.
 
@@ -92,7 +92,7 @@ interface OrmService {
 type DbConnOptions = { configName?: string; config?: Record<string, unknown> }
 ```
 
-- `configName?: string` — 서버에 등록된 DB 연결 설정의 이름. 이 이름으로 서버가 접속 정보를 찾음. (`getInfo`/`connect` 는 `configName` 을 필수로 교차해 받음.)
+- `configName?: string` — 서버에 등록된 DB 연결 설정의 이름. 이 이름으로 서버가 접속 정보를 찾음. `getInfo`/`connect` 는 이 필드를 필수로 교차해(`& { configName: string }`) 받음.
 - `config?: Record<string, unknown>` — 등록 설정 대신 직접 넘기는 즉석 접속 설정 객체. `configName` 으로 가리킬 수 없을 때 사용.
 
 ### AutoUpdateService

package/claude/references/sd-simplysm14/apis/service-common/app-structure.md

@@ -51,7 +51,7 @@ interface AppStructureLeafItem<TModule> {
 ```
 
 - `code` / `title` / `modules` / `requiredModules` / `icon` — 그룹과 동일 의미.
-- `perms?: ("use" | "edit")[]` — 이 화면에 부여 가능한 권한 종류. `"use"` = 조회 권한, `"edit"` = 편집 권한. 지정한 화면만 권한 페이지·권한 체크 대상이 됨. 생략하면 제약 없는 화면(항상 모든 권한 활성).
+- `perms?: ("use" | "edit")[]` — 이 화면에 부여 가능한 권한 종류. `"use"` = 조회 권한, `"edit"` = 편집 권한. 지정한 화면만 권한 페이지·권한 체크 대상이 됨. 생략하면 제약 없는 화면.
 - `subPerms?: AppStructureSubPermission<TModule>[]` — 한 화면 안의 세부 기능 권한 목록.
 - `url?: string` — 외부 링크 등 이동 경로. 일반 화면 라우팅 대신 외부로 보낼 때.
 - `isNotMenu?: boolean` — 메뉴 노출 토글. `true` 면 사이드 메뉴에서 숨김(라우팅 대상 화면 자체는 유지). 홈·내정보 등 직접 진입 화면에 사용. 미지정/`false` 면 메뉴에 노출.
@@ -88,9 +88,9 @@ interface FlatPermission<TModule = unknown> {
 }
 ```
 
-- `titleChain: string[]` — 루트부터 이 권한까지의 표시명 경로. 권한 페이지에서 계층 라벨로 사용.
+- `titleChain: string[]` — 루트부터 이 권한까지의 표시명(`title`) 경로. 권한 페이지에서 계층 라벨로 사용.
 - `codeChain: string[]` — 루트부터의 코드 경로 + 마지막에 권한 종류(`"use"`/`"edit"`)·세부코드가 붙은 전체 키. 권한 식별자.
-- `modulesChain: TModule[][]` — 경로상 각 레벨이 가진 `modules` 배열들의 모음. 이 권한이 어떤 모듈 조건에 묶였는지 표현.
+- `modulesChain: TModule[][]` — 경로상 `modules` 를 가진 각 레벨의 `modules` 배열들의 모음. 이 권한이 어떤 모듈 조건에 묶였는지 표현.
 
 ## isUsableModules
 
@@ -102,9 +102,16 @@ function isUsableModules<TModule>(modules: TModule[] | undefined, requiredModule
 
 - `modules` — OR 조건. 나열 중 하나라도 `usableModules` 에 있으면 통과. `undefined`/빈 배열이면 무조건 통과.
 - `requiredModules` — AND 조건. 나열 전부가 `usableModules` 에 있어야 통과. `undefined`/빈 배열이면 통과로 간주.
-- `usableModules` — 현재 앱에서 활성인 모듈 목록.
+- `usableModules` — 현재 앱에서 활성인 모듈 목록. `undefined` 이면 `modules` 를 가진 항목은 매칭 실패(통과 불가).
 - 반환: requiredModules(AND)와 modules(OR)를 모두 만족하면 `true`.
 
+```ts
+import { isUsableModules } from "@simplysm/service-common";
+
+isUsableModules(["A", "B"], undefined, ["A"]); // true — OR
+isUsableModules(undefined, ["A", "B"], ["A"]); // false — AND 미충족
+```
+
 ## isUsableModulesChain
 
 ```ts
@@ -116,7 +123,7 @@ function isUsableModulesChain<TModule>(modulesChain: TModule[][], requiredModule
 - `modulesChain` — 각 레벨의 `modules` 배열들. 모든 레벨이 OR 조건을 통과해야 함.
 - `requiredModulesChain` — 각 레벨의 `requiredModules` 배열들. 모든 레벨이 AND 조건을 통과해야 함.
 - `usableModules` — 현재 활성 모듈 목록.
-- 반환: 한 레벨이라도 막히면 `false`. 자식 표시 여부 판정에 사용.
+- 반환: 빈 체인이면 `true`, 한 레벨이라도 막히면 `false`. 자식 표시 여부 판정에 사용.
 
 ## getFlatPermissions
 
@@ -128,7 +135,7 @@ function getFlatPermissions<TModule>(items: AppStructureItem<TModule>[], usableM
 
 - `items` — 앱 구조 배열(루트).
 - `usableModules` — 현재 활성 모듈. 모듈 조건을 통과하지 못한 가지(그 자식·권한 포함)는 결과에서 빠짐.
-- 동작: leaf 의 `perms` 각각, 그리고 `subPerms` 의 각 `perm` 을 한 줄(`FlatPermission`)로 펼침. `subPerms` 는 자체 모듈 조건도 추가로 검사.
+- 동작: leaf 의 `perms` 각각, 그리고 `subPerms` 의 각 `perm` 을 한 줄(`FlatPermission`)로 펼침. `subPerms` 는 자체 모듈 조건도 추가로 검사. 빈 `items` 면 빈 배열.
 - 반환: 표시 가능한 권한들의 평탄 배열. 권한 관리 화면(`<sd-permission-table>` 입력)·권한 매칭의 기반.
 
 ```ts

package/claude/references/sd-simplysm14/apis/service-common/protocol.md

@@ -37,7 +37,7 @@ interface ServiceProtocol {
 ```
 
 - `encode(uuid, message)` — 메시지를 와이어 바이트로 인코딩. 3MB 초과 시 자동으로 여러 청크로 분할. 반환 `chunks` 는 전송할 패킷 배열, `totalSize` 는 본문 총 바이트. 같은 메시지의 모든 청크는 동일 `uuid` 를 공유. `MAX_TOTAL_SIZE` 초과 시 throw.
-- `accumulate(bytes)` — 수신 청크 패킷을 누적(stateful). 같은 uuid 의 청크를 한 누적기에 모음. 미완성이면 `progress`, 전부 도착하면 재조립된 raw 바이트를 담은 `complete` 반환. JSON 파싱은 안 함. 헤더(28바이트) 미만이거나 크기 위반 시 throw. 중복 패킷은 무시(인덱스 기준 1회만 반영).
+- `accumulate(bytes)` — 수신 청크 패킷을 누적(stateful). 같은 uuid 의 청크를 한 누적기에 모음. 미완성이면 `progress`, 전부 도착하면 재조립된 raw 바이트를 담은 `complete` 반환. JSON 파싱은 안 함. 헤더(28바이트) 미만이거나 크기 위반 시 throw. 중복 패킷은 인덱스 기준 1회만 반영(중복은 무시). 누적분이 `totalSize` 를 초과하면 무결성 위반으로 throw.
 - `parseMessage(resultBytes)` — 재조립된 raw 바이트를 `ServiceMessage` 로 파싱(stateless). 누적기 상태에 의존하지 않아 worker 등 다른 컨텍스트에 위임 가능. 파싱 실패 시 throw.
 - `decode(bytes)` — `accumulate` 후 완료 시 `parseMessage` 까지 수행하는 통합 경로. 단일 컨텍스트에서 한 번에 디코딩할 때.
 - `dispose()` — 내부 청크 누적기의 GC 타이머 해제·메모리 반환. 인스턴스를 더 안 쓸 때 반드시 호출.