@simplysm/sd-claude 14.0.89 → 14.0.90

package/claude/references/sd-simplysm14/apis/orm-node/db-conn.md

@@ -1,6 +1,6 @@
 # @simplysm/orm-node — 저수준 DB 연결
 
-`createOrm` 추상화를 거치지 않고 raw SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 직접 다루거나, dialect별 접속 설정 타입을 작성하거나, `DbContext` 의 executor 를 직접 구성할 때 같이 읽히는 묶음. 연결 인스턴스 생성·연결 인터페이스·접속 설정·executor·dialect 헬퍼·상수로 구성.
+`createOrm` 추상화를 거치지 않고 raw SQL·파라미터 쿼리·bulk insert·수동 트랜잭션을 직접 다루거나, dialect별 접속 설정 타입을 작성하거나, `DbContext` 의 executor 를 손수 구성할 때 함께 읽히는 묶음. 연결 인스턴스 생성·연결 인터페이스·접속 설정·executor·dialect 헬퍼·상수로 구성.
 
 ## createDbConn
 
@@ -17,19 +17,25 @@ await conn.connect();
 
 ## DbConn
 
-저수준 연결 인터페이스. `EventEmitter<{ close: void }>` 를 상속하며 연결 종료 시 `close` 이벤트를 발생시킨다. 구현체 `MssqlDbConn`/`MysqlDbConn`/`PostgresqlDbConn` 는 직접 export 되지 않고 `createDbConn` 으로만 획득(타입 import 만 가능).
+저수준 연결 인터페이스. `EventEmitter<{ close: void }>` 를 상속하며 연결 종료 시 `close` 이벤트를 발생시킨다. 구현체 `MssqlDbConn`/`MysqlDbConn`/`PostgresqlDbConn` 은 직접 export 되지 않고 `createDbConn` 으로만 획득(타입 `DbConn` 만 import 가능).
 
-- `config: DbConnConfig` — 이 연결의 접속 설정(읽기 전용).
-- `isConnected: boolean` — 현재 연결 여부. `connect` 성공 시 `true`, `close`/종료(`end`) 이벤트 시 `false`. 상태 확인·재연결 판단에 사용.
-- `isInTransaction: boolean` — 트랜잭션 진행 여부. `beginTransaction` 후 `true`, 커밋·롤백 후 `false`.
-- `connect(): Promise<void>` — 연결 수립. 이미 연결돼 있으면 `DB_CONN_ERRORS.ALREADY_CONNECTED` throw.
-- `close(): Promise<void>` — 연결 종료. 미연결 상태면 아무 동작 없이 반환(throw 안 함).
-- `beginTransaction(isolationLevel?: IsolationLevel): Promise<void>` — 트랜잭션 시작. `isolationLevel` 미지정 시 `config.defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED` 로 시작. 테스트로 확인된 허용 값: `"READ_UNCOMMITTED"|"READ_COMMITTED"|"REPEATABLE_READ"|"SERIALIZABLE"`.
-- `commitTransaction(): Promise<void>` — 커밋.
-- `rollbackTransaction(): Promise<void>` — 롤백.
-- `execute(queries: string[]): Promise<Record<string, unknown>[][]>` — 원시 SQL 문자열 배열을 순차 실행. 빈/공백 문자열은 건너뜀. 각 쿼리의 결과셋들을 평탄화해 하나의 배열로 묶어 반환. DDL·다건 SQL 일괄 실행에 사용.
-- `executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>` — 파라미터 바인딩 쿼리 실행. SQL 인젝션 회피·값 재바인딩 시. 반환은 결과셋 배열(MySQL 멀티스테이트먼트는 statement별로 분리되며 INSERT/UPDATE/DELETE 자리는 빈 배열, PostgreSQL 은 단일 결과셋). `params` 미지정 시 MSSQL 은 배치(`execSqlBatch`) 경로로 실행.
-- `bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>` — 네이티브 bulk API 로 대량 삽입. `tableName` 은 `database.table` 또는 `database.schema.table`(dialect별 인용 부호 포함된 완전 수식명). `columnMetas` 는 컬럼명 → `ColumnMeta`(`dataType`·`nullable`) 매핑이며 **키 순서가 컬럼 순서를 결정**, `records` 의 각 객체는 이 키들로 값 추출. `records` 가 빈 배열이면 아무 동작 없이 반환. dialect별 경로: MSSQL tedious `BulkLoad`, MySQL `LOAD DATA LOCAL INFILE`(임시 CSV 파일 생성·삭제, UUID/binary 는 `UNHEX`), PostgreSQL `COPY FROM STDIN`(CSV 스트림). `DateTime`/`DateOnly`/`Time`/`Uuid`/`Uint8Array` 값은 dialect별로 적절히 변환됨.
+- config: DbConnConfig — 이 연결의 접속 설정(읽기 전용). 어떤 dialect·DB 로 연결됐는지 확인용.
+- isConnected: boolean — 현재 연결 여부. `connect` 성공 시 `true`, `close`/종료(`end`) 이벤트 시 `false`. 재연결 판단·정리 분기에 사용.
+- isInTransaction: boolean — 트랜잭션 진행 여부. `beginTransaction` 후 `true`, 커밋·롤백 후 `false`. 중첩 방지·상태 확인에 사용.
+- connect(): Promise\<void\> — 연결 수립. 이미 연결돼 있으면 `DB_CONN_ERRORS.ALREADY_CONNECTED` throw.
+- close(): Promise\<void\> — 연결 종료. 미연결 상태면 아무 동작 없이 반환(throw 안 함). 재호출 안전.
+- beginTransaction(isolationLevel?: IsolationLevel): Promise\<void\> — 트랜잭션 시작. `isolationLevel` 미지정 시 `config.defaultIsolationLevel`, 그것도 없으면 `READ_UNCOMMITTED` 로 시작. 테스트로 확인된 값: `"READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE"`. 더티 리드 차단이 필요하면 `READ_COMMITTED` 이상.
+- commitTransaction(): Promise\<void\> — 진행 중 트랜잭션 커밋, `isInTransaction` 을 `false` 로.
+- rollbackTransaction(): Promise\<void\> — 진행 중 트랜잭션 롤백, `isInTransaction` 을 `false` 로.
+- execute(queries: string[]): Promise\<Record\<string, unknown\>[][]\> — 원시 SQL 문자열 배열을 순차 실행. 빈/공백 문자열은 건너뜀. 각 쿼리의 결과셋들을 평탄화해 하나의 배열로 묶어 반환. DDL·다건 SQL 일괄 실행에 사용.
+- executeParametrized(query: string, params?: unknown[]): Promise\<Record\<string, unknown\>[][]\> — 파라미터 바인딩 쿼리 1건 실행. SQL 인젝션 회피·값 재바인딩 시. 반환은 결과셋 배열(MySQL 멀티스테이트먼트는 statement별로 분리되며 INSERT/UPDATE/DELETE 자리는 빈 배열, PostgreSQL 은 단일 결과셋). `params` 미지정 시 MSSQL 은 배치(`execSqlBatch`) 경로, 지정 시 `execSql` 파라미터 경로로 실행.
+- bulkInsert(tableName: string, columnMetas: Record\<string, ColumnMeta\>, records: Record\<string, unknown\>[]): Promise\<void\> — 네이티브 bulk API 로 대량 삽입. `tableName` 은 `database.table` 또는 `database.schema.table`(dialect별 인용 부호 포함된 완전 수식명). `columnMetas` 는 컬럼명 → `ColumnMeta`(`dataType`·`nullable`) 매핑이며 **키 순서가 컬럼 순서를 결정**, `records` 의 각 객체는 이 키들로 값 추출. `records` 가 빈 배열이면 아무 동작 없이 반환. `DateTime`/`DateOnly`/`Time`/`Uuid`/`Uint8Array`/`null` 값은 dialect별로 적절히 변환됨.
+
+dialect별 bulk insert 경로(서버 측 권한·설정에 의존):
+
+- MSSQL — tedious `BulkLoad`. `ColumnMeta.dataType` 을 tedious 타입으로 매핑.
+- MySQL — `LOAD DATA LOCAL INFILE`. 임시 CSV 파일을 생성·실행 후 삭제하며, UUID/binary 컬럼은 `UNHEX()` 로 복원.
+- PostgreSQL — `COPY FROM STDIN`(CSV 스트림). binary 는 bytea hex 형식으로 인코딩.
 
 ```typescript
 await conn.beginTransaction("READ_COMMITTED");
@@ -43,19 +49,23 @@ await conn.commitTransaction();
 
 공통 필드:
 
-- `dialect` — `"mysql"` | `"mssql"` | `"mssql-azure"` | `"postgresql"`. DBMS 선택. `"mssql-azure"` 는 Azure SQL 용으로 드라이버는 mssql 과 동일하되 연결 시 `encrypt` 활성화. 쿼리 빌더용 dialect 로는 `getDialectFromConfig` 가 `"mssql"` 로 정규화.
-- `host: string` — 접속 호스트.
-- `port?: number` — 포트. 미지정 시 드라이버 기본값(PostgreSQL 은 미지정 시 5432 로 보정).
-- `username: string` — 인증 사용자.
-- `password: string` — 인증 비밀번호.
-- `database?: string` — 접속 기본 DB 이름.
-- `defaultIsolationLevel?: IsolationLevel` — `beginTransaction` 의 `isolationLevel` 미지정 시 적용할 기본 격리 수준.
+- dialect — `"mysql" | "mssql" | "mssql-azure" | "postgresql"`. DBMS 선택. `"mssql-azure"` 는 Azure SQL 용으로 드라이버는 mssql 과 동일하되 연결 시 `encrypt` 가 활성화됨. 쿼리 빌더용 dialect 로는 `getDialectFromConfig` 가 `"mssql"` 로 정규화.
+- host: string — 접속 호스트.
+- port?: number — 포트. 미지정 시 드라이버 기본값(PostgreSQL 은 미지정 시 5432 로 보정).
+- username: string — 인증 사용자.
+- password: string — 인증 비밀번호.
+- database?: string — 접속 기본 DB 이름.
+- defaultIsolationLevel?: IsolationLevel — `beginTransaction` 의 `isolationLevel` 미지정 시 적용할 기본 격리 수준. 연결 단위로 기본 격리를 고정하고 싶을 때.
 
 dialect별 추가 필드:
 
-- `MysqlDbConnConfig` — `dialect: "mysql"`. 공통 필드만(스키마 개념 없음).
-- `MssqlDbConnConfig` — `dialect: "mssql" | "mssql-azure"`. `schema?: string`(예 `dbo`) 추가.
-- `PostgresqlDbConnConfig` — `dialect: "postgresql"`. `schema?: string`(예 `public`) 추가.
+- MysqlDbConnConfig — `dialect: "mysql"`. 공통 필드만(스키마 개념 없음).
+- MssqlDbConnConfig — `dialect: "mssql" | "mssql-azure"`. `schema?: string`(예 `dbo`) 추가.
+- PostgresqlDbConnConfig — `dialect: "postgresql"`. `schema?: string`(예 `public`) 추가.
+
+```typescript
+const cfg: MssqlDbConnConfig = { dialect: "mssql", host: "localhost", port: 21433, username: "sa", password: "...", database: "TestDb", schema: "dbo" };
+```
 
 ## getDialectFromConfig
 
@@ -63,7 +73,7 @@ dialect별 추가 필드:
 function getDialectFromConfig(config: DbConnConfig): Dialect
 ```
 
-`config.dialect` 를 `@simplysm/orm-common` 의 `Dialect` 로 변환. `"mssql-azure"` → `"mssql"` 로 정규화하고 나머지는 그대로 반환. 쿼리 빌더의 dialect 결정에 사용. Azure 여부와 무관하게 같은 SQL 방언을 써야 할 때.
+`config.dialect` 를 `@simplysm/orm-common` 의 `Dialect` 로 변환. `"mssql-azure"` → `"mssql"` 로 정규화하고 나머지는 그대로 반환. 쿼리 빌더의 dialect 결정에 사용 — Azure 여부와 무관하게 같은 SQL 방언을 써야 할 때.
 
 ## NodeDbContextExecutor
 
@@ -73,19 +83,20 @@ new NodeDbContextExecutor(config: DbConnConfig)
 
 `@simplysm/orm-common` 의 `DbContextExecutor` 를 Node 환경에서 구현한 클래스. `createOrm` 이 내부에서 자동 주입하므로 보통 직접 쓸 일은 없고, `DbContext` 를 `createOrm` 없이 수동 인스턴스화할 때만 사용. 생성자는 `DbConnConfig` 만 받고, 실제 연결은 `connect()` 시점에 `createDbConn` 으로 지연 생성한다.
 
-- `connect(): Promise<void>` — `createDbConn(config)` 로 연결 생성 후 수립.
-- `close(): Promise<void>` — 연결 종료 후 내부 참조 해제.
-- `beginTransaction(isolationLevel?: IsolationLevel)` / `commitTransaction()` / `rollbackTransaction()` — 내부 `DbConn` 에 트랜잭션 위임.
-- `executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>` — 파라미터 쿼리 위임.
-- `bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]): Promise<void>` — bulk insert 위임.
-- `executeDefs<T>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>` — `QueryDef` 배열을 dialect 쿼리 빌더로 SQL 변환해 실행. `resultMetas` 가 전부 `null`/미지정이면(결과 불필요) 모든 def 를 하나의 SQL 로 합쳐 단일 요청으로 보내고 def 수만큼 빈 배열 반환(쓰기 전용 최적화). 그 외엔 def 마다 개별 실행 후, 해당 위치에 `resultMeta` 가 있으면 `parseQueryResult` 로 타입 변환해 반환, 없으면 raw 결과셋 그대로 반환.
+- constructor(config: DbConnConfig) — `getDialectFromConfig` 로 dialect 를 결정해 보관. 이 시점엔 연결을 열지 않음.
+- connect(): Promise\<void\> — `createDbConn(config)` 로 연결 생성 후 수립.
+- close(): Promise\<void\> — 연결 종료 후 내부 참조 해제.
+- beginTransaction(isolationLevel?: IsolationLevel) / commitTransaction() / rollbackTransaction() — 내부 `DbConn` 에 트랜잭션 제어 위임. `isolationLevel?` 의미는 위 `DbConn.beginTransaction` 과 동일.
+- executeParametrized(query: string, params?: unknown[]): Promise\<Record\<string, unknown\>[][]\> — 파라미터 쿼리 위임.
+- bulkInsert(tableName: string, columnMetas: Record\<string, ColumnMeta\>, records: DataRecord[]): Promise\<void\> — bulk insert 위임.
+- executeDefs\<T\>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise\<T[][]\> — `QueryDef` 배열을 dialect 쿼리 빌더로 SQL 변환해 실행. `resultMetas` 가 전부 `null`/미지정이면(결과 불필요) 모든 def 를 하나의 SQL 로 합쳐 단일 요청으로 보내고 def 수만큼 빈 배열 반환(쓰기 전용 최적화, 인터페이스 계약 유지). 그 외엔 def 마다 개별 실행 후, 해당 위치에 `resultMeta` 가 있으면 `parseQueryResult` 로 타입 변환해 반환, 없으면 raw 결과셋 그대로 반환.
 - 모든 실행 메서드는 미연결 상태에서 호출 시 `SdError(DB_CONN_ERRORS.NOT_CONNECTED)` throw.
 
 ## 상수
 
-- `DB_CONN_CONNECT_TIMEOUT` — 연결 수립 타임아웃. `10 * 1000`(10초). 연결 드라이버의 connect 타임아웃으로 전달.
-- `DB_CONN_DEFAULT_TIMEOUT` — 쿼리 기본 타임아웃. `10 * 60 * 1000`(10분). 마지막 활동 후 이 값의 2배가 지나면 연결을 자동 종료(idle 타임아웃)하는 데도 사용.
-- `DB_CONN_ERRORS` — 오류 메시지 상수 객체(`as const`). `NOT_CONNECTED`(미연결 상태에서 실행 시), `ALREADY_CONNECTED`(이미 연결된 상태에서 재연결 시). `expect(...).rejects.toThrow(DB_CONN_ERRORS.NOT_CONNECTED)` 처럼 throw 비교·메시지 매칭에 사용.
+- DB_CONN_CONNECT_TIMEOUT — 연결 수립 타임아웃 `10 * 1000`(10초). 드라이버의 connect 타임아웃으로 전달.
+- DB_CONN_DEFAULT_TIMEOUT — 쿼리 기본 타임아웃 `10 * 60 * 1000`(10분). 마지막 활동 후 이 값의 2배가 지나면 연결을 자동 종료(idle 타임아웃)하는 데도 사용.
+- DB_CONN_ERRORS — 오류 메시지 상수 객체(`as const`). `NOT_CONNECTED`(미연결 상태에서 실행 시), `ALREADY_CONNECTED`(이미 연결된 상태에서 재연결 시). `expect(...).rejects.toThrow(DB_CONN_ERRORS.NOT_CONNECTED)` 처럼 throw 비교·메시지 매칭에 사용.
 
 ## 주의사항
 

package/claude/references/sd-simplysm14/apis/sd-cli/README.md

@@ -1,26 +1,27 @@
 # @simplysm/sd-cli
 
-simplysm 빌드/배포 오케스트레이터 CLI. entry 에서 공개되는 것은 CLI 실행 코드가 아니라 ① `sd.config.ts` 작성용 설정 타입, ② 내부 TypeScript/Angular 컴파일러(`SdTsCompiler`), ③ Vitest 전용 Angular Vite 플러그인(`sdAngularPlugin`) 세 가지뿐이다.
+simplysm 모노레포의 빌드/배포 오케스트레이터 CLI. entry(`src/index.ts`)가 외부로 노출하는 것은 CLI 실행 코드가 아니라 세 가지뿐: ① `sd.config.ts` 작성용 설정 타입군, ② 패키지 단위 TypeScript/Angular AOT 증분 컴파일러(`SdTsCompiler`)와 그 옵션·결과 타입, ③ Vitest 전용 Angular Vite 플러그인(`sdAngularPlugin`).
 
 ## 사용 트리거 인덱스
 
-- **sd.config.ts 설정 타입** — 프로젝트 루트 `sd.config.ts` 를 작성·수정하며 패키지 빌드 타겟·배포·Capacitor/Electron/PWA·서버 옵션을 지정할 때. 자세히: [sd-config-types.md](./sd-config-types.md)
-- **SdTsCompiler / ISdTsCompilerOptions / ISdTsCompilerResult** — sd-cli 외부에서 패키지 단위 TS(또는 Angular AOT) 증분 컴파일을 직접 구동하거나 그 결과(emit·진단·lint·SCSS)를 다룰 때. 자세히: [SdTsCompiler.md](./SdTsCompiler.md)
-- **sdAngularPlugin / SdAngularPluginOptions** — Vitest 의 Angular project 에서 `.ts` 를 AOT 컴파일해 주입하는 Vite 플러그인을 설정할 때. (인라인, 아래 참조)
+- **sd.config.ts 설정 타입** — 프로젝트 루트 `sd.config.ts` 를 작성·수정하며 어떤 패키지를 어떤 타겟(`node`/`browser`/`neutral`/`client`/`server`/`scripts`)으로 빌드할지, 배포(npm/로컬/FTP)·Capacitor/Electron/PWA·서버 옵션을 지정할 때. `SdConfigFn` 으로 default export 함수 타입을 잡고 각 패키지를 타겟별 인터페이스로 채움. 자세히: [sd-config-types.md](./sd-config-types.md)
+- **SdTsCompiler / ISdTsCompilerOptions / ISdTsCompilerResult / ISdTsCompilerEmitOptions** — sd-cli 외부에서 패키지 단위 TS(또는 Angular AOT) 증분 컴파일을 직접 구동하거나 그 결과(emit·진단·lint·SCSS)를 다룰 때. 자세히: [SdTsCompiler.md](./SdTsCompiler.md)
+- **sdAngularPlugin / SdAngularPluginOptions** — Vitest 에서 Angular 패키지의 `.ts` 를 AOT 컴파일해 주입하는 Vite 플러그인을 설정할 때. 아래 인라인 섹션 참조.
 
 ## sdAngularPlugin
 
-```ts
-function sdAngularPlugin(options: SdAngularPluginOptions): Plugin   // vite Plugin 반환
-interface SdAngularPluginOptions { pkg: string }
+```typescript
+function sdAngularPlugin(options: SdAngularPluginOptions): Plugin; // vite Plugin 반환
+interface SdAngularPluginOptions { pkg: string; }
 ```
 
-Angular AOT 컴파일을 수행하는 Vite 플러그인. **Vitest 전용**(`vitest.config.ts` 의 `angular` project plugins 에 등록). 내부적으로 `SdTsCompiler` 로 대상 패키지의 `.ts`(tests 포함, `includeTests: true`)를 AOT 컴파일하고, Vite `transform` 훅에서 컴파일된 JS 를 반환한다. `enforce: "pre"` 로 다른 transform 보다 먼저 동작하며, 컴파일러가 만든 인라인 base64 소스맵을 분리해 Vite 호환 형태(`{ code, map }`)로 넘긴다. `buildEnd` 마다 내부 컴파일러를 폐기해 다음 watch 재빌드 때 재생성하고, watch 변경 파일은 `buildStart` 의 캐시 무효화에 사용한다.
+Angular AOT 컴파일을 수행하는 **Vitest 전용** Vite 플러그인(`vitest.config.ts` 의 `angular` project plugins 에 등록). 내부에서 `SdTsCompiler` 로 대상 패키지의 `.ts`(tests 포함, `includeTests: true`, `output: { js: true, dts: false }`)를 AOT 컴파일하고, Vite `transform` 훅에서 컴파일된 JS 를 반환한다. `enforce: "pre"` 로 다른 transform 보다 먼저 동작하며, 컴파일러가 만든 인라인 base64 소스맵을 분리해 Vite 호환 형태(`{ code, map }`)로 넘긴다. `compilerOptionsTransformer` 로 `noEmit:false`·`declaration:false`·`inlineSourceMap:true`·`rootDir = cwd` 를 강제하고, `buildEnd` 마다 내부 컴파일러를 폐기해 다음 watch 재빌드 때 재생성하며, watch 변경 파일을 모아 `buildStart` 의 캐시 무효화에 쓴다.
 
 - pkg: string — 컴파일 대상 패키지 디렉토리명. `sd.config.ts` 의 `packages` 키와 동일(`@simplysm/` 접두사 제외한 짧은 이름, 예: `"angular"`). 플러그인은 `process.cwd()/packages/<pkg>` 를 컴파일 루트로 잡으므로, 테스트하려는 Angular 패키지명을 그대로 넣는다.
 
-```ts
+```typescript
 // vitest.config.ts
 import { sdAngularPlugin } from "@simplysm/sd-cli";
-plugins: [sdAngularPlugin({ pkg: "angular" })]
+
+plugins: [sdAngularPlugin({ pkg: "angular" })];
 ```

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

@@ -1,36 +1,39 @@
 # @simplysm/service-client
 
-WebSocket 기반 서비스 서버(`@simplysm/service-server`)에 접속해 서비스 메서드 호출·서버 이벤트 구독·파일 업/다운로드·ORM 원격 실행을 수행하는 클라이언트. 브라우저(DOM Worker)와 Node.js(글로벌 `WebSocket` 없으면 `ws` polyfill, `worker_threads`) 양쪽에서 동작.
+WebSocket 으로 서비스 서버(`@simplysm/service-server`)에 접속해 서비스 메서드 RPC 호출·서버 푸시 이벤트 구독/발행·파일 업/다운로드·서버측 ORM 원격 실행을 수행하는 클라이언트. 브라우저(DOM Worker)와 Node.js(글로벌 `WebSocket` 없으면 `ws` 로 polyfill, `worker_threads`) 양쪽에서 동작.
 
 ## 사용 트리거 인덱스
 
-- **createServiceClient / ServiceClient** — 서버 접속, 서비스 메서드 호출, 인증, 연결 상태 추적이 필요할 때. 이 패키지의 주 진입점. (아래 인라인 섹션)
+- **createServiceClient / ServiceClient** — 서버 접속, 서비스 호출, 인증, 연결 상태 추적이 필요할 때. 이 패키지의 주 진입점. (아래 인라인 섹션)
 - **ServiceConnectionOptions** — 클라이언트 생성 시 접속 대상(host/port/ssl)·재연결 정책을 정할 때. (아래 인라인 섹션)
 - **getService / ServiceProxy** — 서버 서비스 인터페이스를 타입 안전 프록시로 호출할 때. (아래 인라인 섹션)
-- **이벤트 구독 (addListener / getEvent / emitEvent / ClientEventProxy / EventClient)** — 서버 푸시 이벤트를 구독·발행할 때. (아래 인라인 섹션)
-- **파일 업/다운로드 (uploadFile / downloadFileBuffer / FileClient)** — 인증된 파일 업로드 또는 서버 상대경로 파일 다운로드 시. (아래 인라인 섹션)
+- **이벤트 구독·발행 (addListener / removeListener / emitEvent / getEvent / ClientEventProxy / EventClient)** — 서버 푸시 이벤트를 구독·발행할 때. (아래 인라인 섹션)
+- **파일 업/다운로드 (uploadFile / downloadFileBuffer / FileClient)** — 인증된 파일 업로드, 서버 상대경로 파일 다운로드 시. (아래 인라인 섹션)
 - **진행률 (ServiceProgress / ServiceProgressState)** — 대용량 요청·응답의 청크 전송 진행률을 추적할 때. (아래 인라인 섹션)
-- **환경 호환 타입·헬퍼 (BlobInput / FileCollection / BrowserWorker / isWorkerSupported 등)** — Node/browser 공용 코드에서 DOM 전용 타입 회피, Worker 지원 여부 분기 시. (아래 인라인 섹션)
+- **환경 호환 타입·헬퍼 (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)
+- **저수준 전송 계층 (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 패턴을 따른다.
 
 ## 메인 클라이언트 (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. 이벤트 등록 가능 여부 판단에 사용.
-- `hostUrl: string` (getter) — `http(s)://host:port` 형태의 HTTP 베이스 URL. `ssl` 이 true 면 https. 파일 클라이언트가 이 URL 을 사용.
-- `connect(): Promise<void>` — 서버에 WebSocket 연결. 초기 연결 실패 시 throw.
-- `close(): Promise<void>` — 연결 수동 종료(이후 재연결하지 않음) 및 프로토콜 워커 자원 해제. 종료 후 재사용 금지.
-- `send(serviceName, methodName, params, progress?): Promise<unknown>` — 저수준 서비스 호출. `serviceName.methodName` 메시지를 전송하고 응답 반환. 보통 `getService` 프록시를 통해 간접 사용. `progress` 를 안 줘도 client 의 `request/response/server-progress` 이벤트는 항상 발생.
-- `auth(token): Promise<void>` — 인증 토큰 전송 후 내부에 보관. 보관 토큰은 재연결 시 자동 재인증·파일 업로드 Bearer 인증에 재사용.
+- 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 — 아래 각 섹션 참조.
 
 ```ts
 const client = createServiceClient("my-app", { host: "localhost", port: 50080, ssl: false });
@@ -40,10 +43,10 @@ await client.auth(jwtToken);
 
 **ServiceClientEvents** (EventEmitter 이벤트):
 
-- `"request-progress": ServiceProgressState` — 요청(업로드) 청크 진행률. 요청 본문이 분할(청크 2개 이상) 전송될 때만 발생.
-- `"response-progress": ServiceProgressState` — 응답(다운로드) 청크 진행률.
-- `"server-progress": ServiceProgressState` — 서버가 처리 중 직접 보고하는 진행률(서버측 `progress` 메시지).
-- `"state": "connected" | "closed" | "reconnecting"` — 연결 상태 변화. `"connected"` = 연결/재연결 성공, `"closed"` = 정상 종료 또는 재연결 한도 초과, `"reconnecting"` = 재연결 시도 중. `"connected"` 전이 시 보관 토큰으로 자동 재인증 및 이벤트 리스너 자동 복구 수행.
+- "request-progress": ServiceProgressState — 요청(업로드) 청크 진행률. 요청 본문이 청크 2개 이상으로 분할될 때만 발생.
+- "response-progress": ServiceProgressState — 응답(다운로드) 청크 수신 진행률. 분할 응답 완료 시 100% 한 번 더 보고.
+- "server-progress": ServiceProgressState — 서버가 처리 중 직접 보고하는 진행률(서버측 `progress` 메시지 수신 시).
+- "state": "connected" | "closed" | "reconnecting" — 연결 상태 변화. "connected" = 연결/재연결 성공(이 전이 시 보관 토큰으로 자동 재인증 + 이벤트 리스너 자동 복구), "closed" = 정상 종료 또는 재연결 한도 초과, "reconnecting" = 재연결 시도 중. 오프라인 배너 토글 등에 사용.
 
 ```ts
 client.on("state", (s) => { if (s === "reconnecting") showOfflineBanner(); });
@@ -55,62 +58,63 @@ client.on("state", (s) => { if (s === "reconnecting") showOfflineBanner(); });
 
 - port: number — 서버 포트. 필수.
 - host: string — 서버 호스트. 필수.
-- ssl?: boolean — TLS 사용 여부. true 면 `wss`/`https`, false·미지정이면 `ws`/`http`. TLS 서버에 붙을 때 true.
-- maxReconnectCount?: number — 연결 끊김 시 최대 재연결 시도 횟수. 미지정 시 10. **0 이면 재연결 비활성화**(끊기면 즉시 포기). 테스트·단발성 연결이면 0.
+- ssl?: boolean — TLS 사용 여부. true 면 `wss`/`https`, false·미지정이면 `ws`/`http`. TLS 서버에 붙을 때만 true.
+- maxReconnectCount?: number — 연결 끊김 시 최대 재연결 시도 횟수. 미지정 시 10. 0 이면 재연결 비활성화(끊기면 즉시 포기). 테스트·단발성 연결이면 0.
 
 ## getService / ServiceProxy
 
 서버 서비스 인터페이스의 각 메서드를 `Promise` 반환 함수로 노출하는 타입 안전 프록시.
 
-`getService<TService>(serviceName): ServiceProxy<TService>` — `serviceName` 으로 등록된 서버 서비스의 프록시 반환. 프록시 메서드 호출 = `client.send(serviceName, 메서드명, 인자배열)`.
+`getService<TService>(serviceName): ServiceProxy<TService>` — `serviceName` 으로 등록된 서버 서비스의 프록시 반환. 프록시 메서드 호출은 내부적으로 `client.send(serviceName, 메서드명, 인자배열)` 로 위임.
 
-- TService — 서버 서비스 메서드 인터페이스 타입. 컴파일 타임 시그니처 검증용(런타임 검증 아님).
-- `ServiceProxy<TService>` — TService 의 각 함수 멤버를 `(...args) => Promise<Awaited<R>>` 로 매핑. 함수 아닌 속성은 `never` 로 제외.
+- TService — 서버 서비스 메서드 인터페이스 타입. 컴파일 타임 시그니처 검증용(런타임 검증 아님). 앱에선 server 패키지가 export 한 `ServiceMethods<typeof XxxService>` 사용.
+- serviceName: string — 서버의 `defineService("XxxName", ...)` 이름과 일치해야 함.
+- ServiceProxy\<TService\> — TService 의 각 함수 멤버를 `(...args) => Promise<Awaited<R>>` 로 매핑. 함수 아닌 속성은 `never` 로 제외.
 
 ```ts
-const svc = client.getService<MyServiceMethods>("MyService");
-const result = await svc.echo("hi"); // 서버의 MyService.echo("hi") 호출, Promise<string>
+const svc = client.getService<TestServiceMethods>("TestService");
+const result = await svc.echo("hi"); // 서버 TestService.echo("hi") 호출, Promise<string>
 ```
 
-## 이벤트 구독 (addListener / getEvent / emitEvent)
+## 이벤트 구독·발행 (addListener / removeListener / emitEvent / getEvent)
 
-서버 푸시 이벤트는 `@simplysm/service-common` 의 `defineEvent` 산출물(`ServiceEventDef`. `$info` = 구독 필터 정보 타입, `$data` = 페이로드 타입) 단위로 구독. 등록한 리스너는 재연결 시 자동 복구됨.
+서버 푸시 이벤트는 `@simplysm/service-common` 의 `defineEvent` 산출물(`ServiceEventDef`. `$info` = 구독 필터 정보 타입, `$data` = 페이로드 타입) 단위로 다룬다. 등록한 리스너는 재연결 시 자동 복구됨.
 
-`addListener<TEventDef>(eventDef, info, cb): Promise<string>` — 리스너 등록. **연결되지 않은 상태면 throw**. 반환 key 로 나중에 제거.
+`addListener<TEventDef>(eventDef, info, cb): Promise<string>` — 리스너 등록. 미연결(`connected === false`)이면 throw. 반환 key 로 나중에 제거.
 
-- eventDef: TEventDef — 이벤트 정의(`defineEvent` 결과). `$info`/`$data` 타입 출처.
-- info: TEventDef["$info"] — 이 구독을 식별·필터링할 정보(서버가 emit 대상 선별에 사용).
-- cb: (data) => PromiseLike<void> — 이벤트 수신 콜백. 콜백 내 예외는 로깅만 되고 전파되지 않음.
+- eventDef: TEventDef — 이벤트 정의(`defineEvent` 결과). `$info`/`$data` 타입의 출처.
+- info: TEventDef["$info"] — 이 구독을 식별·필터링할 정보. 서버가 emit 대상 선별에 사용.
+- cb: (data: $data) => PromiseLike\<void\> — 이벤트 수신 콜백. 콜백 내 예외는 로깅만 되고 호출부로 전파되지 않음.
 
-`removeListener(key): Promise<void>` — 등록 key 로 리스너 제거. 서버 전송 실패(연결 끊김 등) 시 무시(서버가 끊김 시 자동 정리).
+`removeListener(key): Promise<void>` — 등록 key 로 리스너 제거. 서버 전송 실패(연결 끊김 등)는 무시(서버가 끊김 시 리스너를 자동 정리하므로 안전).
 
 `emitEvent<TEventDef>(eventDef, infoSelector, data): Promise<void>` — 이벤트 발행. 서버에서 동일 이벤트 구독자 목록을 조회한 뒤 `infoSelector(info)` 가 true 인 대상에게만 data 전송.
 
-- infoSelector: (item: $info) => boolean — 발행 대상 구독자를 info 기준으로 필터.
+- infoSelector: (item: $info) => boolean — 발행 대상 구독자를 info 기준으로 필터. true 반환 구독자에게만 전달.
 - data: TEventDef["$data"] — 전송 페이로드.
 
-`getEvent<TEventDef>(eventDef): ClientEventProxy<TEventDef>` — 특정 eventDef 에 바인딩된 프록시 반환(eventDef 반복 전달 생략용).
+`getEvent<TEventDef>(eventDef): ClientEventProxy<TEventDef>` — 특정 eventDef 에 바인딩된 프록시 반환. eventDef 를 매번 넘기지 않고 짧게 쓰려 할 때(앱의 `AppServiceProvider.xxxEvent` getter 패턴).
 
 `ClientEventProxy<TEventDef>` 멤버: `addListener(info, cb)`, `removeListener(key)`, `emit(infoSelector, data)` — 위 client 메서드의 eventDef 고정판.
 
 ```ts
-const evt = defineEvent<{ channel: string }, string>("Chat");
-const key = await client.addListener(evt, { channel: "room1" }, async (msg) => render(msg));
-await client.emitEvent(evt, (info) => info.channel === "room1", "hello");
+const chatEvent = defineEvent<{ channel: string }, string>("Chat");
+const key = await client.addListener(chatEvent, { channel: "room1" }, async (msg) => render(msg));
+await client.emitEvent(chatEvent, (info) => info.channel === "room1", "hello");
 await client.removeListener(key);
 ```
 
-`EventClient` / `createEventClient(transport)` 는 `ServiceClient` 가 내부 조립에 쓰는 저수준 구현. 위 4개 메서드에 더해 `resubscribeAll(): Promise<void>`(보관된 모든 리스너를 서버에 재등록, 재연결 복구용)을 가짐. 일반 사용에선 직접 만들지 않음.
+`EventClient` / `createEventClient(transport)` 는 `ServiceClient` 가 내부 조립에 쓰는 저수준 구현. 위 메서드에 더해 `resubscribeAll(): Promise<void>`(보관된 모든 리스너를 서버에 재등록, 재연결 복구용)를 가짐. 일반 사용에선 직접 만들지 않음.
 
 ## 파일 업/다운로드 (uploadFile / downloadFileBuffer)
 
-`uploadFile(files): Promise<ServiceUploadResult[]>` — `POST <hostUrl>/upload` (multipart) 로 파일 업로드. 보관 토큰을 `Authorization: Bearer` 로 전송하므로 **사전 `auth()` 필수**(미인증 시 throw).
+`uploadFile(files): Promise<ServiceUploadResult[]>` — `POST <hostUrl>/upload` (multipart/form-data) 로 파일 업로드. 보관 토큰을 `Authorization: Bearer` 헤더로 전송하므로 사전 `auth()` 필수(미인증 시 throw). 응답 비정상 시 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);
@@ -124,9 +128,9 @@ const bytes = await client.downloadFileBuffer("/files/a.txt");
 
 대용량 요청/응답이 청크로 분할될 때 진행 상황을 보고하는 콜백·상태 타입.
 
-`ServiceProgress` — `send(..., progress)` 에 넘기는 콜백 집합(메서드별 추적용, 전역 이벤트와 별개). 각 콜백 `(s: ServiceProgressState) => void`:
+`ServiceProgress` — `send(..., progress)` 에 넘기는 콜백 집합(해당 호출 단건 추적용, 전역 이벤트와 별개). 각 콜백은 `(s: ServiceProgressState) => void`:
 
-- request? — 요청 청크 업로드 진행 시 호출(요청 청크 2개 이상일 때만).
+- request? — 요청 청크 업로드 진행 시 호출. 요청 청크가 2개 이상일 때만 발생.
 - response? — 응답 청크 수신 진행 시 호출. 분할 응답이었으면 완료 시 100%(`completedSize === totalSize`)를 한 번 더 보고.
 - server? — 서버가 처리 중 보고한 진행률 수신 시 호출(`name: "progress"` 메시지).
 
@@ -136,15 +140,15 @@ const bytes = await client.downloadFileBuffer("/files/a.txt");
 - totalSize: number — 전체 바이트 수.
 - completedSize: number — 완료 바이트 수. `completedSize === totalSize` 면 완료.
 
-`send` 호출 시 위 콜백과 무관하게 ServiceClient 의 `request/response/server-progress` 이벤트도 항상 발생하므로, 전역 추적이면 콜백 대신 `client.on("response-progress", ...)` 를 써도 됨.
+전역 추적이면 콜백 대신 ServiceClient 의 `request/response/server-progress` 이벤트(`client.on("response-progress", ...)`)를 써도 됨 — `send` 는 progress 인자 유무와 무관하게 이 이벤트들을 항상 발생시킴.
 
 ## 환경 호환 타입·헬퍼 (browser-compat)
 
 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. 프로토콜 인코딩 오프로딩 가능 여부 판단(미지원 시 메인 스레드 폴백).
+- 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. 프로토콜 인코딩/파싱 오프로딩 가능 여부 판단(미지원 시 메인 스레드 폴백).

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

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

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

@@ -1,36 +1,38 @@
 # @simplysm/service-client — 저수준 전송 계층
 
-`ServiceClient` 가 생성자에서 내부적으로 조립하는 저수준 모듈들. WebSocket 연결·하트비트·재연결(SocketProvider), 요청/응답 매칭과 메시지 디스패치(ServiceTransport), 인코딩/디코딩의 Worker 오프로딩(ClientProtocolWrapper). 일반 사용에서는 `ServiceClient` 만 쓰면 되고, 이 계층은 직접 다룰 일이 드물다.
+`ServiceClient` 가 생성자에서 내부적으로 조립하는 저수준 모듈들. WebSocket 연결·하트비트·재연결(SocketProvider), 요청/응답 매칭과 메시지 디스패치(ServiceTransport), 인코딩/디코딩의 Worker 오프로딩(ClientProtocolWrapper). 일반 사용에서는 `ServiceClient` 만 쓰면 되며, 이 계층은 소켓·청크·하트비트 동작을 이해해야 할 때만 읽는다.
 
 ## SocketProvider / createSocketProvider
 
-WebSocket 1개의 연결·하트비트·자동 재연결을 담당.
+WebSocket 1개의 연결·하트비트·자동 재연결 담당.
 
-`createSocketProvider(url, clientName, maxReconnectCount): SocketProvider` — 프로바이더 생성.
+`createSocketProvider(url, clientName, maxReconnectCount): SocketProvider` — 프로바이더 생성. Node 환경에서 글로벌 `WebSocket` 이 없으면 모듈 로드 시 `ws` 패키지로 polyfill.
 
 - url: string — `ws(s)://host:port/ws`. 접속 시 `ver=2`, 생성된 `clientId`(UUID), `clientName` 쿼리를 붙임.
 - clientName: string — 접속 쿼리에 실리는 식별명.
-- maxReconnectCount: number — 최대 재연결 시도. 0 이면 재연결 안 함.
+- maxReconnectCount: number — 최대 재연결 시도 횟수. 0 이면 재연결 안 함.
 
 내부 상수: 하트비트 ping 5초 간격, 30초 무수신 시 타임아웃, 재연결 3초 간격. 1바이트 `0x01` ping 전송, `0x02` pong 수신은 무시(타임스탬프만 갱신).
 
-- `clientName: string` (readonly) — 생성 시 받은 식별명.
-- `connected: boolean` (getter) — 소켓이 OPEN 인지.
-- `connect(): Promise<void>` — 접속 시작. 실패 시 throw, 성공 시 재연결 카운트 리셋하고 `state: "connected"` emit.
-- `close(): Promise<void>` — 수동 종료. 이후 자동 재연결 안 함. `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"` = 재연결 시도 중.
+- state: "connected" | "closed" | "reconnecting" — 연결 상태 변화. "connected" = 연결/재연결 성공, "closed" = 수동 종료 또는 재연결 한도 초과, "reconnecting" = 재연결 시도 중.
 
-하트비트 타임아웃 감지 시 소켓을 강제 정리하고(늦은 onclose 로 인한 중복 재연결 방지로 핸들러 해제) 수동 종료가 아니면 재연결을 시도. 최대 시도 초과 시 `state: "closed"` emit.
+하트비트 타임아웃 감지 시 소켓을 강제 정리하고(늦은 onclose 로 인한 중복 재연결 방지를 위해 핸들러 해제) 수동 종료가 아니면 재연결을 시도. 최대 시도 초과 시 `state: "closed"` emit.
 
 ## ServiceTransport / createServiceTransport
 
-요청별 uuid 매칭, 응답/에러/진행률/서버이벤트 디스패치를 담당.
+요청별 uuid 매칭, 응답/에러/진행률/서버이벤트 디스패치 담당.
 
 `createServiceTransport(socket, protocol): ServiceTransport` — 트랜스포트 생성. 소켓 `message` 를 받아 decode 후 종류별 분기. 소켓이 `closed`/`reconnecting` 되면 대기 중인 모든 요청을 reject(메모리 해제).
 
@@ -39,21 +41,21 @@ WebSocket 1개의 연결·하트비트·자동 재연결을 담당.
 
 멤버:
 
-- `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 에 매칭되는 로컬 리스너로 디스패치.
 
-decode 실패 시에도 헤더 16바이트에서 uuid 를 선추출해 해당 요청만 reject. 분할 응답이면 완료 시 `progress.response` 로 100% 를 한 번 더 보고.
+decode 실패 시에도 헤더 16바이트에서 uuid 를 선추출해 해당 요청만 reject. 분할 응답이면 완료 시 `progress.response` 로 100% 를 한 번 더 보고. 서버측 진행 메시지(`name: "progress"`)는 `progress.server` 로 전달.
 
 ## ClientProtocolWrapper / createClientProtocolWrapper
 
-인코드/디코드를 크기 기준으로 Worker 에 오프로딩하는 래퍼. `@simplysm/service-common` 의 `ServiceProtocol` 을 감쌈.
+인코드/디코드를 크기 기준으로 Worker 에 오프로딩하는 래퍼. `@simplysm/service-common` 의 `ServiceProtocol` 을 감쌈. Worker 미가용·임계값(30KB) 이하면 메인 스레드 처리로 폴백.
 
-`createClientProtocolWrapper(protocol): ClientProtocolWrapper` — 래퍼 생성. 임계값 30KB. Worker 미가용·임계값 이하면 메인 스레드 처리로 폴백.
+`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()` 에서 호출.
+- 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()` 에서 호출.