mega-framework 0.1.11 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {

package/sample/crud/docs/guide/03-service-model-db.md

@@ -802,12 +802,68 @@ export class User extends MegaModel {
 
 - **옵트인**이다 — `static schema` 가 없는 모델(레거시 raw SQL 운용)은 그냥 무시된다.
 - 같은 `static schema` 선언은 **공통 CRUD([§2-1](#2-1-공통-crud-static-schema-opt-in-adr-212))도 함께 켠다**(SQL 어댑터) — "스키마 1선언 = 마이그레이션 + CRUD".
-- 타입: `serial/bigSerial/integer/bigInteger/smallInteger/real/doublePrecision/decimal(p,s)/varchar(n)/
-  text/char(n)/boolean/timestamp/timestamptz/date/time/uuid/json/jsonb/enum(values)/bytea`.
-- 체인: `.primary() .notNull() .unique({name?}) .default(v | {raw}) .defaultNow() .check(expr,{name?})
-  .references(model, col, {onDelete?, onUpdate?, name?}) .comment(text)`. 복합 PK 는 `t.primary(['a','b'])`.
-- FK 대상은 **모델 이름**(file-scan 범위 안에 있어야 함 — 없으면 fail-fast). 관계는 FK 까지만 —
-  조인 헬퍼/lazy load 같은 ORM 기능은 없다(ADR-009).
+
+#### 컬럼 타입 — `t.<type>()`
+
+각 타입 메서드는 `ColumnBuilder` 를 반환하므로 아래 **수식어를 체인**할 수 있다(`src/core/migration/schema-builder.js`).
+
+| 분류 | 메서드 | 비고 |
+| --- | --- | --- |
+| 정수 | `t.serial()` · `t.bigSerial()` | 자동증가(postgres SERIAL / BIGSERIAL) |
+| 정수 | `t.integer()` · `t.bigInteger()` · `t.smallInteger()` | |
+| 실수 | `t.real()` · `t.doublePrecision()` | |
+| 정밀수 | `t.decimal(precision, scale)` | NUMERIC(p,s) |
+| 문자열 | `t.varchar(maxLength)` · `t.char(length)` · `t.text()` | |
+| 논리 | `t.boolean()` | |
+| 시간 | `t.timestamp()` · `t.timestamptz()` · `t.date()` · `t.time()` | |
+| 기타 | `t.uuid()` · `t.json()` · `t.jsonb()` · `t.bytea()` | |
+| 열거 | `t.enum(values, { name? })` | postgres 는 `TEXT + CHECK (col IN (...))` 로 렌더(native enum 미사용 — 값 추가/삭제가 제약 교체로 단순) |
+| **mongo 전용** | `t.objectId()` · `t.object(shape?)` · `t.array(items?, { uniqueItems? })` | SQL dialect 는 렌더 시 거부. `object`/`array` 의 중첩 필드는 타입·길이·enum·notNull(→required)만 — unique/primary/references/check 는 **최상위 전용** |
+
+#### 컬럼 수식어 (체인) — `ColumnBuilder`
+
+| 메서드 | 뜻 |
+| --- | --- |
+| `.primary()` | 단일 컬럼 PRIMARY KEY. 복합 PK 는 `t.primary(['a','b'])`(아래) |
+| `.notNull()` | NOT NULL |
+| `.nullable()` | 명시 null 허용. SQL 은 기본 nullable 이라 선언적 표시(no-op), mongo 는 `['type','null']` 유니온. `.notNull()` 과 **동시 사용 불가** |
+| `.unique({ name? })` | UNIQUE 제약. 이름 미지정 시 `uniq_<table>_<col>` |
+| `.default(value)` | DEFAULT. literal(string/number/boolean/null) 또는 `{ raw: 'expr' }`(raw SQL 식) |
+| `.defaultNow()` | `DEFAULT CURRENT_TIMESTAMP` 단축 |
+| `.check(expr, { name? })` | CHECK 제약. 이름 미지정 시 `chk_<table>_<col>` |
+| `.references(model, col, { onDelete?, onUpdate?, name? })` | FK. 대상은 **모델 이름**(테이블명 아님 — 스냅샷 시 해석). `onDelete`/`onUpdate` ∈ `cascade · set null · set default · restrict · no action` |
+| `.comment(text)` | `COMMENT ON COLUMN` |
+
+- 테이블 레벨: `t.primary(['a','b'])` — **복합 PRIMARY KEY**(반환값 없음, 컬럼 맵엔 안 들어감). 단일 PK 는 컬럼 체인 `.primary()`.
+- FK 대상 모델은 **file-scan 범위 안에 있어야** 한다(없으면 fail-fast). 관계는 FK 까지만 — 조인 헬퍼/lazy load 같은 ORM 기능은 없다(ADR-009).
+
+#### 인덱스 — `static indexes = (t) => [ t.index(...) ]`
+
+```js
+static indexes = (t) => [
+  t.index(['role', 'createdAt']),                                  // 복합. 이름 자동: idx_<table>_<col…> (= idx_users_role_createdAt)
+  t.index(['email'], { unique: true }),                            // unique 인덱스
+  t.index({ expression: 'lower(email)' }, { name: 'idx_users_email_lower' }),  // 표현식 인덱스
+  t.index(['org_id'], { where: 'deleted_at IS NULL' }),            // 부분 인덱스(조건부)
+  t.index(['payload'], { using: 'gin' }),                          // 인덱스 방법(postgres USING)
+]
+```
+
+| `t.index(컬럼들|식, opts)` 인자 | 뜻 |
+| --- | --- |
+| 1번째: `'col'` / `['a','b']` / `{ expression: 'lower(x)' }` | 단일·복합 컬럼 또는 표현식 인덱스 |
+| `opts.name` | 인덱스 이름 override(기본 dialect 표준명) |
+| `opts.unique` | `true` 면 UNIQUE 인덱스 |
+| `opts.where` | **부분 인덱스** WHERE 조건(예: `'deleted_at IS NULL'`) |
+| `opts.using` | 인덱스 방법(postgres `USING` — 예: `gin`/`gist`/`hash`) |
+
+> 컬럼에 직접 `.unique()` 를 거는 것(=UNIQUE **제약**)과 `t.index([...], { unique: true })`(=UNIQUE **인덱스**)는
+> 비슷하나, 후자는 복합·표현식·부분 인덱스를 지원한다. 단일 컬럼 유일성은 `.unique()` 가 간단하다.
+
+**자동 이름 규칙**(postgres dialect, `{ name }` 미지정 시): 인덱스 `idx_<table>_<cols>` · UNIQUE 인덱스/제약
+`uniq_<table>_<cols>` · FK `fk_<table>_<col>_<reftable>` · CHECK `chk_<table>_<col>`. 63byte 초과 시 거부되니
+길면 `{ name }` 으로 짧게 지정한다.
+
 - 제외 규칙: `_` 로 시작하는 파일/폴더, `*.test.js`, `static skip = true`.
 - 식별자는 63byte(postgres 한도)를 넘으면 거부된다 — 합성 이름(`fk_…`)이 걸리면 `{name}` 으로
   짧은 이름을 명시하면 된다.

package/sample/crud/docs/guide/11-data-assembly.md

@@ -0,0 +1,174 @@
+# 11. 데이터 조립 — attachMany / attachOne / enrich / parallel
+
+여러 테이블·컬렉션을 묶은 "데이터셋"을 만들 때 쓰는 **MegaService 헬퍼 4종**입니다(ADR-230).
+
+프레임워크에는 ORM·조인이 **일부러 없습니다**(ADR-009). 쿼리는 여러분이 모델을 import 해 직접 작성하고,
+헬퍼는 **머지·캐시·동시성**의 기계적인 일만 합니다. 그래서:
+
+- 쿼리 자유도 100% (원하는 `findMany`/`query` 를 그대로 씀)
+- **dialect 무관** — 공통 CRUD `findMany` 가 배열을 SQL `IN` · mongo `$in` 양쪽으로 바꿔주므로, 부모는
+  Postgres·자식은 MongoDB 처럼 **서로 다른 저장소를 섞어도** 동작합니다(`$lookup` 으론 불가능한 조합).
+- 라우트/컨트롤러는 모델을 직접 import 할 수 없습니다(ADR-022). 이 조립은 **Service 안에서** 합니다.
+
+> 헬퍼는 `this.attachMany(...)` 처럼 **서비스 인스턴스 메서드**입니다. 서비스 밖에서 순수 함수가 필요하면
+> `import { attachMany } from 'mega-framework'` 로도 쓸 수 있지만(캐시는 직접 어댑터 주입), 보통은
+> 서비스 메서드를 씁니다.
+
+---
+
+## 어떤 걸 언제 쓰나
+
+| 상황 | 메서드 | 쿼리 수 |
+|---|---|---|
+| 부모마다 자식 **여러 개** 붙이기 (글쓴이 → 글들) | `attachMany` (1:N) | **1 + 1**(배치) |
+| 부모마다 부모(역참조) **하나** 붙이기 (글 → 글쓴이) | `attachOne` (N:1) | **1 + 1**(배치) |
+| 부모마다 **조건이 달라** 배치로 못 묶음 | `enrich` (per-row) | 1 + N ⚠ |
+| 여러 독립 작업을 **동시에** 실행 | `parallel` | 동시 |
+
+큰 배열에는 **`attachMany`/`attachOne` 를 우선** 쓰세요. `enrich` 는 편하지만 본질적으로 **N+1** 입니다
+(아래 경고 참고).
+
+---
+
+## 1) attachMany — 1:N 배치 머지
+
+`parent[parentKey='id']` ↔ `child[fk]`. 부모마다 매칭되는 자식 **배열**을 `as` 속성으로 붙입니다.
+
+```js
+// apps/main/services/users-service.js
+import { MegaService } from 'mega-framework'
+import { User } from '../models/user-model.js'
+import { Post } from '../models/post-model.js'
+
+export class UsersService extends MegaService {
+  async activeWithPosts() {
+    const users = await User.findMany({ active: true })          // 부모 1쿼리
+    await this.attachMany(users, Post, 'userId', 'posts')         // 자식 1쿼리(배치 IN)
+    return users   // [{ id, name, posts: [ {..}, {..} ] }, ...]  매칭 없으면 posts: []
+  }
+}
+```
+
+옵션 `{ where, select, orderBy, limit, parentKey, cache, fetch }`:
+
+```js
+await this.attachMany(users, Post, 'userId', 'posts', {
+  where:   { published: true },         // 자식 추가 조건
+  select:  ['id', 'title'],             // 조인 키(userId)는 자동 포함됨
+  orderBy: { createdAt: 'desc' },
+  limit:   100,                         // ⚠ 자식 "전체" 상한 (부모당 아님 — 아래 한계)
+  parentKey: 'id',                      // 부모 매칭 컬럼(기본 id)
+})
+```
+
+---
+
+## 2) attachOne — N:1 배치 머지
+
+`parent[fk]` ↔ `child[childKey='id']`. 부모마다 매칭 자식 **하나**(없으면 `null`)를 붙입니다.
+
+```js
+const posts = await Post.findMany({ published: true })
+await this.attachOne(posts, User, 'userId', 'author')   // post.userId ↔ user.id
+// posts: [{ id, title, userId, author: { id, name } | null }, ...]
+```
+
+부모 쪽 키는 위치 인자 `fk` 로 고정됩니다. 자식 쪽 컬럼이 `id` 가 아니면 `opts.childKey` 로 바꿉니다:
+
+```js
+await this.attachOne(rows, Org, 'orgCode', 'org', { childKey: 'code' })  // row.orgCode ↔ org.code
+```
+
+---
+
+## 3) 깊은 조인 — attach 를 이어 붙이기
+
+`attachMany`/`attachOne` 는 부모 배열을 제자리에서 채우고 그대로 돌려주므로, **여러 단계로 이어** 쓰면 됩니다.
+
+```js
+const users = await User.findMany({ active: true })
+await this.attachMany(users, Post, 'userId', 'posts')        // user.posts[]
+
+// posts 들을 평탄화해서 다음 단계의 부모로
+const allPosts = users.flatMap((u) => u.posts)
+await this.attachMany(allPosts, Comment, 'postId', 'comments') // post.comments[]
+// → user → posts → comments (총 3쿼리, 행 수와 무관)
+```
+
+---
+
+## 4) 캐시 — hit 시 쿼리 0
+
+`opts.cache = { key, ttl?, bucket }` 를 주면 자식 결과를 한 키로 캐시합니다. **키는 직접 지정**하세요
+(자동 해시는 stale·충돌 위험이라 채택하지 않았습니다).
+
+```js
+await this.attachMany(users, Post, 'userId', 'posts', {
+  cache: { bucket: 'demo', key: 'posts:active', ttl: 30 },   // hit 시 자식 쿼리 skip
+})
+```
+
+- 무효화는 직접: `await this.ctx.cache('demo').del('posts:active')`
+- ⚠ redis 캐시는 JSON 직렬화라 `ObjectId`/`Date` 가 **문자열**이 됩니다. HTTP 응답엔 무방하지만, **캐시된
+  값을 다시 쿼리 입력으로 쓰지 마세요**.
+
+---
+
+## 5) cross-dialect — 저장소를 섞기
+
+헬퍼는 plain object 만 다루므로 부모·자식이 다른 DB 여도 됩니다.
+
+```js
+const users = await User.findMany({ active: true })          // Postgres
+await this.attachMany(users, MongoActivity, 'userId', 'activity')  // MongoDB, 같은 코드
+```
+
+> mongo `_id` 처럼 `ObjectId` 키도 안전합니다 — 헬퍼가 비교 시 `String()` 으로 정규화합니다(인스턴스가
+> 달라도 같은 값이면 매칭).
+
+---
+
+## 6) enrich — per-row 보강 (⚠ N+1)
+
+부모마다 **조건이 달라** 배치로 못 묶을 때만 씁니다. 각 행에 콜백을 적용합니다.
+
+```js
+await this.enrich(users, async (u) => {
+  u.unread = await Notification.count({ userId: u.id, read: false })  // 행마다 1쿼리
+}, 5)   // 동시 5개까지
+```
+
+- 두 번째 인자가 숫자면 **concurrency**. 객체면 `{ concurrency: 10, settled, cache }`.
+- 콜백이 값을 반환하면 그 값으로 행을 교체하고, `undefined` 면 mutate 된 원본을 유지합니다.
+- **`concurrency` 는 동시성만 줄입니다 — 쿼리 수(N+1)는 그대로**. 큰 배열엔 `attachMany` 를 먼저 검토하세요.
+- `settled: true` 면 일부 행이 실패해도 진행하고(해당 행 원본 유지) 실패는 `log.warn` 으로 남깁니다.
+- 캐시: `{ cache: { key: (row) => `user:${row.id}`, ttl: 60, bucket: 'demo' } }` — 행별 키, hit 시 콜백 skip.
+
+---
+
+## 7) parallel — 독립 작업 동시 실행
+
+`Promise.all`/`allSettled` + 동시성 제한. thunk(`() => Promise`)의 **객체/배열**을 받습니다.
+
+```js
+const { user, orders, stats } = await this.parallel({
+  user:   () => User.findById(id),
+  orders: () => Order.findMany({ userId: id }),
+  stats:  () => this.services.metrics.summary(id),
+})
+```
+
+- 배열도 됩니다: `const [a, b] = await this.parallel([() => fa(), () => fb()])`
+- `this.parallel(specs, 4)` — 동시 4개로 제한(기본 무제한).
+- `{ settled: true }` — 결과가 `{ status, value | reason }` 로 감싸져 모두 완주합니다.
+
+---
+
+## 한계 (꼭 알아두기)
+
+- **부모당 N개(per-parent limit)는 불가**: `attachMany` 의 `limit` 은 자식 **전체** 상한이지 "부모마다 최신
+  3개"가 아닙니다. 부모별 top-N 은 window 함수가 필요해 배치 1쿼리로는 cross-dialect 가 안 됩니다. 정말
+  필요하면 `enrich` 로 부모별 쿼리(N+1)를 받아들이세요.
+- **트랜잭션**: 헬퍼는 트랜잭션을 열지 않습니다. 부모·자식 쿼리 사이의 동시 쓰기로 불일치가 생길 수 있고,
+  일관성이 필요하면 **단일 어댑터**일 때 `Model.withTransaction` 으로 감싸세요(cross-store 는 불가, ADR-010).
+- **캐시 직렬화**: 위 4) 참고 — 캐시된 값은 응답용이지 재쿼리 입력용이 아닙니다.

package/src/core/index.js

@@ -5,6 +5,8 @@ export { MegaWsPresence } from './ws-presence.js'
 export { MegaServer } from './mega-server.js'
 export { Router, MegaRouteError } from './router.js'
 export { MegaService } from './mega-service.js'
+// 데이터 조립 순수 함수 (ADR-230) — 보통은 MegaService 메서드를 쓰지만, 서비스 밖에서도 직접 호출 가능.
+export { attachMany, attachOne, enrich, parallel } from './service-helpers/index.js'
 export { MegaCluster } from './mega-cluster.js'
 export { loadRoutes } from './routes-loader.js'
 // 중앙 부팅 orchestrator (ADR-123)

package/src/core/mega-service.js

@@ -12,7 +12,19 @@
  *
  * 자동 DI(ADR-148): `apps/<app>/services/<name>-service.js` 를 부팅 시 로드해 두면 핸들러·다른 서비스가
  * `ctx.services.<name>` / `this.services.<name>` 로 요청별 인스턴스를 받는다(첫 접근 시 lazy 생성·요청 내 캐시).
+ *
+ * 데이터 조립(ADR-230): `attachMany`/`attachOne`(배치 머지) · `enrich`(per-row) · `parallel`(동시 실행)
+ * 4종 헬퍼를 제공한다. 쿼리는 사용자가 모델을 import 해 직접 작성하고(ADR-009·022), 헬퍼는 머지·캐시·
+ * 동시성의 기계적 작업만 맡는다(ORM·관계 declaration 아님). 본문은 `service-helpers/` 의 순수 함수에
+ * 위임하며 여기서는 `ctx.cache`/`log` 만 주입한다.
  */
+import {
+  attachMany as _attachMany,
+  attachOne as _attachOne,
+  enrich as _enrich,
+  parallel as _parallel,
+} from './service-helpers/index.js'
+
 export class MegaService {
   /**
    * @param {Record<string, any>} ctx - 요청 컨텍스트 (req·log·services·db·cache·bus 등)
@@ -38,4 +50,73 @@ export class MegaService {
   get services() {
     return this.ctx?.services ?? {}
   }
+
+  // ── 데이터 조립 헬퍼 (ADR-230) ────────────────────────────────────────────
+
+  /**
+   * 버킷→캐시 어댑터 resolver(헬퍼 cache 옵션 주입용). `ctx.cache(bucket)` 가 없으면 throw.
+   * @protected
+   * @param {string} bucket - `services.caches` 별명.
+   * @returns {any} MegaCacheAdapter.
+   */
+  _cacheFor(bucket) {
+    if (typeof this.ctx?.cache !== 'function') {
+      throw new Error(
+        'MegaService: ctx.cache(bucket) 접근자가 없습니다 — cache 옵션은 caches 가 설정된 요청 ctx 가 필요합니다.',
+      )
+    }
+    return this.ctx.cache(bucket)
+  }
+
+  /**
+   * 1:N 배치 머지 — `parent[parentKey='id']` ↔ `child[fk]`. 부모마다 매칭 자식 **배열**을 `as` 로 붙인다.
+   * 단일 배치 쿼리(IN/$in)라 dialect·저장소 무관(ADR-230). per-parent limit 은 불가(전체 상한만).
+   *
+   * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+   * @param {any} Model - 자식 모델(공통 CRUD `findMany`, 또는 `opts.fetch`).
+   * @param {string} fk - 자식의 외래키 컬럼.
+   * @param {string} as - 부모에 붙일 속성명.
+   * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, limit?: number, parentKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+   * @returns {Promise<any[]>} parents.
+   */
+  attachMany(parents, Model, fk, as, opts = {}) {
+    return _attachMany(parents, Model, fk, as, opts, (b) => this._cacheFor(b), this.log)
+  }
+
+  /**
+   * N:1 배치 머지 — `parent[fk]` ↔ `child[childKey='id']`. 부모마다 매칭 자식 **하나**(없으면 null)를 붙인다.
+   *
+   * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+   * @param {any} Model - 자식 모델.
+   * @param {string} fk - 부모가 들고 있는 외래키 컬럼.
+   * @param {string} as - 부모에 붙일 속성명.
+   * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, childKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+   * @returns {Promise<any[]>} parents.
+   */
+  attachOne(parents, Model, fk, as, opts = {}) {
+    return _attachOne(parents, Model, fk, as, opts, (b) => this._cacheFor(b), this.log)
+  }
+
+  /**
+   * per-row 보강 — 각 행에 `fn` 적용(N+1 본질, concurrency 는 동시성만). cache 로 행별 결과 재사용.
+   *
+   * @param {any[]} rows - 대상 배열(제자리 mutate 후 반환).
+   * @param {(row: any) => Promise<any>} fn - 행별 콜백.
+   * @param {number | { concurrency?: number, settled?: boolean, cache?: { key: (row: any) => string, ttl?: number, bucket: string } }} [opts]
+   * @returns {Promise<any[]>} rows.
+   */
+  enrich(rows, fn, opts = {}) {
+    return _enrich(rows, fn, opts, (b) => this._cacheFor(b), this.log)
+  }
+
+  /**
+   * 동시 실행 — thunk(`() => Promise`)의 객체/배열을 받아 같은 형태로 결과 반환(동시성 제한 가능).
+   *
+   * @param {Record<string, () => Promise<any>> | Array<() => Promise<any>>} specs
+   * @param {number | { concurrency?: number, settled?: boolean }} [opts]
+   * @returns {Promise<any>}
+   */
+  parallel(specs, opts = {}) {
+    return _parallel(specs, opts)
+  }
 }

package/src/core/service-helpers/attach.js

@@ -0,0 +1,197 @@
+// @ts-check
+/**
+ * 배치 머지 헬퍼 — `attachMany`(1:N) / `attachOne`(N:1) (ADR-230).
+ *
+ * 사용자가 부모 레코드를 이미 손에 들고 있을 때, 자식 모델을 **단일 배치 쿼리**(IN/$in)로 끌어와
+ * 메모리에서 머지한다. per-row 루프(N+1)를 1+1 로 압축하는 dataloader 패턴이며, 어댑터의 `findMany`
+ * 가 배열 필터를 SQL `IN` · mongo `$in` 양쪽으로 처리하므로 **dialect 무관**하다. 부모·자식이 서로
+ * 다른 저장소여도(예: pg 부모 + mongo 자식) plain object 만 다루므로 그대로 동작한다.
+ *
+ * ORM·관계 declaration 이 아니다(ADR-009) — 조인 키를 매 호출 명시하고, 결과는 plain object 이며,
+ * 인스턴스(ActiveRecord)를 만들지 않는다.
+ *
+ * # 한계
+ *   - **per-parent limit 불가**: `opts.limit` 은 자식 **전체** 상한이지 "부모당 N개"가 아니다(부모별
+ *     top-N 은 window 함수가 필요해 배치 1쿼리로 cross-dialect 불가). 부모별이 필요하면 `enrich` 로.
+ *   - **캐시 직렬화**: redis 캐시는 JSON 직렬화라 ObjectId/Date 가 문자열이 된다. 응답용은 무방하나
+ *     캐시된 값을 다시 쿼리 입력으로 쓰면 안 된다.
+ *
+ * @module core/service-helpers/attach
+ */
+
+/**
+ * 비교용 키 정규화 — mongo ObjectId 등 비-원시 키는 인스턴스끼리 `===` 가 성립하지 않으므로
+ * `String()` 로 안정화한다. null/undefined 는 그대로 보존(매칭 안 됨).
+ * @param {any} v
+ * @returns {any}
+ */
+function normKey(v) {
+  return v === null || v === undefined ? v : String(v)
+}
+
+/**
+ * 정규화 기준 중복 제거(원본 값 보존 — IN 쿼리엔 실제 ObjectId/값이 들어가야 한다).
+ * @param {any[]} arr
+ * @returns {any[]}
+ */
+function uniq(arr) {
+  const seen = new Set()
+  /** @type {any[]} */
+  const out = []
+  for (const v of arr) {
+    if (v === null || v === undefined) continue
+    const k = normKey(v)
+    if (!seen.has(k)) {
+      seen.add(k)
+      out.push(v)
+    }
+  }
+  return out
+}
+
+/**
+ * 머지 키가 select 에서 빠지면 머지가 깨진다(특히 mongo `_id` 는 기본 숨김). 자동 포함한다.
+ * @param {string[] | undefined} select
+ * @param {string} col
+ * @returns {string[] | undefined}
+ */
+function ensureKeyInSelect(select, col) {
+  if (!Array.isArray(select)) return select
+  return select.includes(col) ? select : [...select, col]
+}
+
+/**
+ * 공통 인자 검증.
+ * @param {string} name @param {any[]} parents @param {string} fk @param {string} as
+ */
+function validateArgs(name, parents, fk, as) {
+  if (!Array.isArray(parents)) throw new TypeError(`${name}: parents must be an array`)
+  if (!fk || typeof fk !== 'string') throw new TypeError(`${name}: fk(key column) must be a non-empty string`)
+  if (!as || typeof as !== 'string') throw new TypeError(`${name}: as(target property) must be a non-empty string`)
+}
+
+/**
+ * 자식 레코드 fetch — cache hit 면 쿼리 skip. `opts.fetch`(사용자 함수) 우선, 없으면 `Model.findMany`.
+ *
+ * @param {any} Model - 자식 모델(공통 CRUD `findMany` 보유. `opts.fetch` 사용 시 미사용).
+ * @param {string} matchCol - 자식에서 IN 으로 조회할 컬럼.
+ * @param {any[]} ids - 중복 제거된 부모 키(정규화 전 원본).
+ * @param {any} opts - { where, select, orderBy, limit, fetch, cache }.
+ * @param {(bucket: string) => any} [cacheFor] - 버킷→캐시 어댑터 resolver.
+ * @param {any} [logger]
+ * @returns {Promise<any[]>}
+ */
+async function fetchChildren(Model, matchCol, ids, opts, cacheFor, logger) {
+  const log = logger ?? console
+  const cacheOpt = opts.cache
+  let cache = null
+  if (cacheOpt) {
+    if (!cacheOpt.key || typeof cacheOpt.key !== 'string') {
+      throw new TypeError('attach: cache.key must be a non-empty string (auto-hash 비채택 — stale/충돌 방지)')
+    }
+    if (!cacheOpt.bucket) throw new TypeError('attach: cache.bucket is required (ctx.cache(bucket))')
+    if (typeof cacheFor !== 'function') {
+      throw new Error('attach: cache requested but no cache resolver — MegaService 를 통해 호출하세요.')
+    }
+    cache = cacheFor(cacheOpt.bucket)
+    const hit = await cache.get(cacheOpt.key)
+    if (hit !== null && hit !== undefined) return hit
+  }
+
+  /** @type {any[]} */
+  let children
+  if (typeof opts.fetch === 'function') {
+    if (opts.where || opts.select || opts.orderBy || opts.limit !== undefined) {
+      log.warn?.('attach: opts.fetch 가 지정되어 where/select/orderBy/limit 는 무시됩니다(fetch 우선).')
+    }
+    children = await opts.fetch(ids)
+  } else {
+    if (!Model || typeof Model.findMany !== 'function') {
+      throw new TypeError('attach: Model.findMany 가 없습니다 — schema 선언 모델이거나 opts.fetch 를 쓰세요.')
+    }
+    const filter = { [matchCol]: ids, ...(opts.where ?? {}) }
+    /** @type {Record<string, any>} */
+    const findOpts = {}
+    if (opts.select) findOpts.select = ensureKeyInSelect(opts.select, matchCol)
+    if (opts.orderBy) findOpts.orderBy = opts.orderBy
+    if (opts.limit !== undefined) findOpts.limit = opts.limit
+    children = await Model.findMany(filter, findOpts)
+  }
+
+  if (cache) {
+    await cache.set(cacheOpt.key, children, cacheOpt.ttl !== undefined ? { ttl: cacheOpt.ttl } : {})
+  }
+  return children
+}
+
+/**
+ * 1:N 배치 머지 — `parent[parentKey]`(기본 `id`) ↔ `child[fk]`. 부모마다 매칭 자식 **배열**을 붙인다.
+ *
+ * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+ * @param {any} Model - 자식 모델.
+ * @param {string} fk - 자식의 외래키 컬럼.
+ * @param {string} as - 부모에 붙일 속성명.
+ * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, limit?: number, parentKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+ * @param {(bucket: string) => any} [cacheFor]
+ * @param {any} [logger]
+ * @returns {Promise<any[]>} parents(동일 참조).
+ */
+export async function attachMany(parents, Model, fk, as, opts = {}, cacheFor, logger) {
+  validateArgs('attachMany', parents, fk, as)
+  if (parents.length === 0) return parents
+  const parentKey = opts.parentKey ?? 'id'
+  const ids = uniq(parents.map((p) => p[parentKey]))
+  if (ids.length === 0) {
+    for (const p of parents) p[as] = []
+    return parents
+  }
+  const children = await fetchChildren(Model, fk, ids, opts, cacheFor, logger)
+  /** @type {Map<any, any[]>} */
+  const groups = new Map()
+  for (const c of children) {
+    const k = normKey(c[fk])
+    let arr = groups.get(k)
+    if (!arr) {
+      arr = []
+      groups.set(k, arr)
+    }
+    arr.push(c)
+  }
+  for (const p of parents) p[as] = groups.get(normKey(p[parentKey])) ?? []
+  return parents
+}
+
+/**
+ * N:1 배치 머지 — `parent[fk]` ↔ `child[childKey]`(기본 `id`). 부모마다 매칭 자식 **하나**(없으면 null).
+ *
+ * 주의: 부모 쪽 매칭 컬럼은 위치 인자 `fk` 로 고정된다. 튜닝 가능한 건 자식 쪽 컬럼이라
+ * `opts.childKey`(기본 `id`)로 노출한다.
+ *
+ * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+ * @param {any} Model - 자식 모델.
+ * @param {string} fk - 부모가 들고 있는 외래키 컬럼(자식 식별자 값).
+ * @param {string} as - 부모에 붙일 속성명.
+ * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, childKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+ * @param {(bucket: string) => any} [cacheFor]
+ * @param {any} [logger]
+ * @returns {Promise<any[]>} parents(동일 참조).
+ */
+export async function attachOne(parents, Model, fk, as, opts = {}, cacheFor, logger) {
+  validateArgs('attachOne', parents, fk, as)
+  if (parents.length === 0) return parents
+  const childKey = opts.childKey ?? 'id'
+  const ids = uniq(parents.map((p) => p[fk]))
+  if (ids.length === 0) {
+    for (const p of parents) p[as] = null
+    return parents
+  }
+  const children = await fetchChildren(Model, childKey, ids, opts, cacheFor, logger)
+  /** @type {Map<any, any>} */
+  const byKey = new Map()
+  for (const c of children) {
+    const k = normKey(c[childKey])
+    if (!byKey.has(k)) byKey.set(k, c) // 1개 가정 — 첫 매치 우선.
+  }
+  for (const p of parents) p[as] = byKey.get(normKey(p[fk])) ?? null
+  return parents
+}

package/src/core/service-helpers/enrich.js

@@ -0,0 +1,79 @@
+// @ts-check
+/**
+ * per-row 보강 헬퍼 — `enrich` (ADR-230).
+ *
+ * 각 행마다 비동기 콜백을 적용한다(부모마다 조건이 달라 배치로 묶기 어려운 경우). 본질적으로 **N+1**
+ * 이며 `concurrency` 는 쿼리 수를 줄이지 않고 동시성만 제한한다 — 큰 배열엔 `attachMany` 를 우선 검토.
+ *
+ * 캐시(`opts.cache`)를 주면 행별 키로 결과를 재사용한다 — hit 시 콜백을 건너뛴다. redis 캐시는 JSON
+ * 직렬화라 ObjectId/Date 가 문자열이 된다(응답용 OK, 재쿼리 입력 금지).
+ *
+ * @module core/service-helpers/enrich
+ */
+import { runPool } from './pool.js'
+
+/**
+ * `rows` 각 항목에 `fn` 을 적용한다. `fn` 반환값이 `undefined` 가 아니면 그 값으로 교체하고,
+ * `undefined` 면 (제자리 mutate 된) 원본 행을 유지한다.
+ *
+ * @param {any[]} rows - 대상 배열(제자리 mutate 후 반환).
+ * @param {(row: any) => Promise<any>} fn - 행별 콜백.
+ * @param {number | { concurrency?: number, settled?: boolean, cache?: { key: (row: any) => string, ttl?: number, bucket: string } }} [opts]
+ *        number 면 `concurrency`. settled:true 면 일부 실패해도 진행(실패 행은 그대로 두고 경고 로그).
+ * @param {(bucket: string) => any} [cacheFor] - 버킷→캐시 어댑터 resolver(cache 옵션 쓸 때만 필요).
+ * @param {any} [logger] - settled 실패 경고용(P4/P5 — silent skip 금지).
+ * @returns {Promise<any[]>} rows(동일 참조).
+ */
+export async function enrich(rows, fn, opts = {}, cacheFor, logger) {
+  if (!Array.isArray(rows)) throw new TypeError('enrich: rows must be an array')
+  if (typeof fn !== 'function') throw new TypeError('enrich: fn must be a function (row) => Promise')
+  const o = typeof opts === 'number' ? { concurrency: opts } : (opts ?? {})
+  const concurrency = o.concurrency ?? 10
+  const settled = o.settled === true
+  const cacheOpt = o.cache
+  const log = logger ?? console
+
+  let cache = null
+  if (cacheOpt) {
+    if (typeof cacheOpt.key !== 'function') {
+      throw new TypeError('enrich: cache.key must be a function (row) => string')
+    }
+    if (!cacheOpt.bucket) throw new TypeError('enrich: cache.bucket is required (ctx.cache(bucket))')
+    if (typeof cacheFor !== 'function') {
+      throw new Error('enrich: cache requested but no cache resolver — MegaService 를 통해 호출하세요.')
+    }
+    cache = cacheFor(cacheOpt.bucket)
+  }
+
+  /** 행 i 처리 — 캐시 hit/miss 분기 후 rows[i] 갱신. @param {any} row @param {number} i */
+  const worker = async (row, i) => {
+    if (cache) {
+      const k = cacheOpt.key(row)
+      const hit = await cache.get(k)
+      if (hit !== null && hit !== undefined) {
+        rows[i] = hit
+        return
+      }
+      const r = await fn(row)
+      const finalRow = r === undefined ? row : r
+      rows[i] = finalRow
+      await cache.set(k, finalRow, cacheOpt.ttl !== undefined ? { ttl: cacheOpt.ttl } : {})
+      return
+    }
+    const r = await fn(row)
+    if (r !== undefined) rows[i] = r
+  }
+
+  const out = await runPool(rows, worker, { concurrency, settled })
+
+  // settled 모드의 개별 실패는 runPool 이 삼키므로 여기서 명시 경고(P4 — silent skip 금지).
+  if (settled) {
+    for (let i = 0; i < out.length; i++) {
+      const d = /** @type {any} */ (out[i])
+      if (d && d.status === 'rejected') {
+        log.warn?.({ err: d.reason, index: i }, 'enrich: row 콜백 실패(settled) — 해당 행은 원본 유지')
+      }
+    }
+  }
+  return rows
+}

package/src/core/service-helpers/index.js

@@ -0,0 +1,13 @@
+// @ts-check
+/**
+ * MegaService 데이터 조립 헬퍼 배럴 (ADR-230).
+ *
+ * 순수 함수들 — `MegaService` 의 동명 메서드가 `ctx.cache`/`log` 를 주입해 위임한다. 서비스 인스턴스
+ * 없이 단위 테스트 가능하도록 직접 export 한다.
+ *
+ * @module core/service-helpers
+ */
+export { attachMany, attachOne } from './attach.js'
+export { enrich } from './enrich.js'
+export { parallel } from './parallel.js'
+export { runPool } from './pool.js'

package/src/core/service-helpers/parallel.js

@@ -0,0 +1,49 @@
+// @ts-check
+/**
+ * 동시 실행 헬퍼 — `parallel` (ADR-230).
+ *
+ * `Promise.all` / `Promise.allSettled` 를 동시성 제한과 함께 추상화한다. 입력은 **thunk**(`() => Promise`)
+ * 의 객체 또는 배열이다 — 이미 시작된 promise 가 아니라 thunk 여야 `concurrency` 가 의미를 갖는다.
+ * 출력은 입력과 같은 형태(객체→객체, 배열→배열)다.
+ *
+ * @module core/service-helpers/parallel
+ */
+import { runPool } from './pool.js'
+
+/**
+ * @param {Record<string, () => Promise<any>> | Array<() => Promise<any>>} specs - thunk 의 객체/배열.
+ * @param {number | { concurrency?: number, settled?: boolean }} [opts]
+ *        number 면 `concurrency`(기본 무제한). settled:true 면 `{ status, value | reason }` 로 감싸 모두 완주.
+ * @returns {Promise<any>} specs 와 동일 형태의 결과.
+ */
+export async function parallel(specs, opts = {}) {
+  const o = typeof opts === 'number' ? { concurrency: opts } : (opts ?? {})
+  const isArray = Array.isArray(specs)
+  if (!isArray && (specs === null || typeof specs !== 'object')) {
+    throw new TypeError('parallel: specs must be an object or array of thunks (() => Promise)')
+  }
+  /** @type {string[]} */
+  const keys = isArray ? [] : Object.keys(specs)
+  /** @type {Array<() => Promise<any>>} */
+  const thunks = isArray ? /** @type {any} */ (specs) : keys.map((k) => /** @type {any} */ (specs)[k])
+
+  thunks.forEach((fn, i) => {
+    if (typeof fn !== 'function') {
+      const label = isArray ? `[${i}]` : `.${keys[i]}`
+      throw new TypeError(`parallel: spec${label} must be a function (() => Promise), got ${typeof fn}`)
+    }
+  })
+
+  const arr = await runPool(thunks, (fn) => fn(), {
+    concurrency: o.concurrency,
+    settled: o.settled,
+  })
+
+  if (isArray) return arr
+  /** @type {Record<string, any>} */
+  const out = {}
+  keys.forEach((k, i) => {
+    out[k] = arr[i]
+  })
+  return out
+}

package/src/core/service-helpers/pool.js

@@ -0,0 +1,73 @@
+// @ts-check
+/**
+ * 바운디드 동시성 실행기 — service-helpers(enrich/parallel)가 공유한다(ADR-230).
+ *
+ * 신규 dep 없이(`p-limit` 미도입) 입력 순서를 보존하며 동시 실행 수만 제한한다. 두 모드:
+ *   - `settled:false`(기본) — 첫 worker rejection 에서 전체를 reject 한다(Promise.all 의미). 이미
+ *     시작된 worker 는 자연 종료되지만 결과는 버려진다.
+ *   - `settled:true` — 각 항목을 `{ status, value | reason }` 로 감싸 **모두 완주**한다(allSettled 의미).
+ *
+ * @module core/service-helpers/pool
+ */
+
+/**
+ * @template T, R
+ * @typedef {{ status: 'fulfilled', value: R } | { status: 'rejected', reason: any }} Settled
+ */
+
+/**
+ * `items` 를 `worker` 로 매핑하되 동시 실행 수를 `concurrency` 로 제한한다. 결과 배열은 입력 순서 보존.
+ *
+ * @template T, R
+ * @param {T[]} items - 매핑 대상.
+ * @param {(item: T, index: number) => Promise<R>} worker - 각 항목 처리(반환값이 결과).
+ * @param {{ concurrency?: number, settled?: boolean }} [opts] - `concurrency` 미지정/비양수면 무제한(=항목 수).
+ * @returns {Promise<Array<R | Settled<T, R>>>} settled 면 descriptor 배열, 아니면 결과 배열.
+ */
+export async function runPool(items, worker, opts = {}) {
+  const n = items.length
+  /** @type {any[]} */
+  const results = new Array(n)
+  if (n === 0) return results
+
+  const settled = opts.settled === true
+  let limit = opts.concurrency
+  // 무제한·잘못된 값 → 항목 수(전부 동시). 그 외엔 [1, n] 으로 클램프.
+  if (limit === undefined || limit === null || !Number.isFinite(limit) || limit <= 0) {
+    limit = n
+  }
+  limit = Math.max(1, Math.min(Math.floor(limit), n))
+
+  let next = 0
+  /** @type {any} settled:false 에서 첫 에러 보관 — 완주 후 throw. */
+  let failure = null
+  let hasFailure = false
+
+  // 워커 루프 — 공유 커서(next)에서 항목을 하나씩 집어 처리. catch 내부 처리라 절대 reject 안 함.
+  async function spawn() {
+    for (;;) {
+      if (hasFailure && !settled) return // 이미 실패 — 새 작업 시작 중단(진행 중인 건 종료).
+      const i = next++
+      if (i >= n) return
+      try {
+        const r = await worker(items[i], i)
+        results[i] = settled ? { status: 'fulfilled', value: r } : r
+      } catch (e) {
+        if (settled) {
+          results[i] = { status: 'rejected', reason: e }
+        } else if (!hasFailure) {
+          hasFailure = true
+          failure = e
+          return
+        }
+      }
+    }
+  }
+
+  const workers = []
+  for (let k = 0; k < limit; k++) workers.push(spawn())
+  await Promise.all(workers)
+
+  if (hasFailure && !settled) throw failure
+  return results
+}

package/src/index.js

@@ -6,6 +6,8 @@ export { bootApp, buildBootContext } from './core/index.js'
 export { getApp, hasApp } from './core/index.js'
 export { runCli, parseArgs, runWorkerHost, runSchedulerHost, dispatchPluginCommand, USAGE } from './cli/index.js'
 export { MegaService } from './core/index.js'
+// 데이터 조립 헬퍼 순수 함수 (ADR-230) — 보통은 MegaService 메서드 사용.
+export { attachMany, attachOne, enrich, parallel } from './core/index.js'
 export { MegaCluster } from './core/index.js'
 export { wrapEnvelope, errorEnvelope, buildErrorHandler, ajvErrorToValidationError } from './core/index.js'
 // WS envelope + 컨트롤러 베이스 (ADR-015 / ADR-074)

package/templates/model/code-mongo.tpl

@@ -17,19 +17,11 @@ export class {{Name}} extends MegaModel {
   static table = '{{table}}'
 
   // 자동 마이그레이션 스키마(ADR-209) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
-  static schema = (t) => ({
+  static schema = /** @param {any} t */ (t) => ({
     name: t.varchar(100).notNull(),
     createdAt: t.timestamptz().notNull(), // 생성 시 앱에서 new Date() 로 채운다(mongo 는 default 미지원)
   })
 
   // 인덱스(선택): static indexes = (t) => [t.index(['name'], { unique: true })]
 
-  /**
-   * _id 로 1건 조회 — `this.db` 는 native mongodb `Db`(ADR-009), 도큐먼트 API 직접 사용.
-   * @param {import('mongodb').ObjectId} id
-   * @returns {Promise<object|null>}
-   */
-  static async findById(id) {
-    return this.db.collection(this.table).findOne({ _id: id })
-  }
 }

package/templates/model/code.tpl

@@ -15,7 +15,7 @@ export class {{Name}} extends MegaModel {
   static table = '{{table}}'
 
   // 자동 마이그레이션 스키마(ADR-204) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
-  static schema = (t) => ({
+  static schema = /** @param {any} t */ (t) => ({
     id: t.serial().primary(),
     name: t.varchar(100).notNull(),
     createdAt: t.timestamptz().defaultNow(),
@@ -23,13 +23,4 @@ export class {{Name}} extends MegaModel {
 
   // 인덱스(선택): static indexes = (t) => [t.index(['name'], { unique: true })]
 
-  /**
-   * id 로 1건 조회. `this.query` 는 계측된 어댑터 query 위임(ADR-138).
-   * @param {string|number} id
-   * @returns {Promise<object|null>}
-   */
-  static async findById(id) {
-    const { rows } = await this.query('select * from {{table}} where id = $1', [id])
-    return rows[0] ?? null
-  }
 }

package/templates/model/test-mongo.tpl

@@ -12,27 +12,5 @@ describe('{{Name}} model (mongodb)', () => {
 
   test('schema 빌더 선언 — 자동 마이그레이션 트랙 옵트인(ADR-209)', () => {
     expect(typeof {{Name}}.schema).toBe('function')
-  })
-
-  test('findById — native Db 의 도큐먼트 API 에 위임', async () => {
-    /** @type {any[]} */
-    const calls = []
-    const fakeDb = {
-      collection: (/** @type {string} */ name) => ({
-        findOne: async (/** @type {any} */ filter) => {
-          calls.push({ name, filter })
-          return { _id: filter._id }
-        },
-      }),
-    }
-    // MegaModel.db 는 getter 라 서브클래스 own property 로 가린다(테스트 한정).
-    Object.defineProperty({{Name}}, 'db', { value: fakeDb, configurable: true })
-    try {
-      const doc = await {{Name}}.findById(/** @type {any} */ ('id-1'))
-      expect(doc).toEqual({ _id: 'id-1' })
-      expect(calls[0].name).toBe('{{table}}')
-    } finally {
-      delete /** @type {any} */ ({{Name}}).db
-    }
-  })
+  })  
 })

package/templates/model/test.tpl

@@ -13,21 +13,4 @@ describe('{{Name}} model', () => {
   test('schema 빌더 선언 — 자동 마이그레이션 트랙 옵트인(ADR-204)', () => {
     expect(typeof {{Name}}.schema).toBe('function')
   })
-
-  test('findById — 어댑터 query 에 위임', async () => {
-    const orig = {{Name}}.query
-    /** @type {any[]} */
-    const calls = []
-    {{Name}}.query = async (/** @type {string} */ sql, /** @type {any[]} */ params) => {
-      calls.push({ sql, params })
-      return { rows: [{ id: params[0] }] }
-    }
-    try {
-      const row = await {{Name}}.findById(7)
-      expect(row).toEqual({ id: 7 })
-      expect(calls[0].params).toEqual([7])
-    } finally {
-      {{Name}}.query = orig
-    }
-  })
 })

package/types/core/index.d.ts

@@ -10,6 +10,7 @@ export { MegaWebSocketController } from "./ws-controller.js";
 export { MegaHubLink } from "./hub-link.js";
 export { createSessionCleanupSchedule } from "./session-cleanup-schedule.js";
 export { Router, MegaRouteError } from "./router.js";
+export { attachMany, attachOne, enrich, parallel } from "./service-helpers/index.js";
 export { bootApp, buildBootContext } from "./boot.js";
 export { getApp, hasApp } from "./app-registry.js";
 export { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from "./envelope.js";

package/types/core/mega-service.d.ts

@@ -1,16 +1,3 @@
-/**
- * MegaService — 도메인 비즈니스 로직 베이스.
- *
- * 라우트 핸들러(인라인 함수 또는 정적 메서드 ref)는 직접 모델을 호출하지 않고 항상 서비스를 거쳐야
- * 한다(ADR-022). ESLint custom rule `mega/no-direct-model-import`(`mega-framework/eslint-plugin`,
- * eslint.config.js 에 배선)가 lint 시점에 routes/controllers → models 직접 import 를 차단한다.
- *
- * 서비스는 요청 컨텍스트 ctx 와 함께 인스턴스화되며, this.ctx / this.app / this.log /
- * this.services 로 접근. 다른 서비스 호출은 this.services.<name> 으로 합성.
- *
- * 자동 DI(ADR-148): `apps/<app>/services/<name>-service.js` 를 부팅 시 로드해 두면 핸들러·다른 서비스가
- * `ctx.services.<name>` / `this.services.<name>` 로 요청별 인스턴스를 받는다(첫 접근 시 lazy 생성·요청 내 캐시).
- */
 export class MegaService {
     /**
      * @param {Record<string, any>} ctx - 요청 컨텍스트 (req·log·services·db·cache·bus 등)
@@ -28,4 +15,85 @@ export class MegaService {
     get log(): any;
     /** 다른 서비스 호출용. ctx.services 가 없으면 빈 객체. */
     get services(): any;
+    /**
+     * 버킷→캐시 어댑터 resolver(헬퍼 cache 옵션 주입용). `ctx.cache(bucket)` 가 없으면 throw.
+     * @protected
+     * @param {string} bucket - `services.caches` 별명.
+     * @returns {any} MegaCacheAdapter.
+     */
+    protected _cacheFor(bucket: string): any;
+    /**
+     * 1:N 배치 머지 — `parent[parentKey='id']` ↔ `child[fk]`. 부모마다 매칭 자식 **배열**을 `as` 로 붙인다.
+     * 단일 배치 쿼리(IN/$in)라 dialect·저장소 무관(ADR-230). per-parent limit 은 불가(전체 상한만).
+     *
+     * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+     * @param {any} Model - 자식 모델(공통 CRUD `findMany`, 또는 `opts.fetch`).
+     * @param {string} fk - 자식의 외래키 컬럼.
+     * @param {string} as - 부모에 붙일 속성명.
+     * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, limit?: number, parentKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+     * @returns {Promise<any[]>} parents.
+     */
+    attachMany(parents: any[], Model: any, fk: string, as: string, opts?: {
+        where?: Record<string, any>;
+        select?: string[];
+        orderBy?: any;
+        limit?: number;
+        parentKey?: string;
+        cache?: {
+            key: string;
+            ttl?: number;
+            bucket: string;
+        };
+        fetch?: (ids: any[]) => Promise<any[]>;
+    }): Promise<any[]>;
+    /**
+     * N:1 배치 머지 — `parent[fk]` ↔ `child[childKey='id']`. 부모마다 매칭 자식 **하나**(없으면 null)를 붙인다.
+     *
+     * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+     * @param {any} Model - 자식 모델.
+     * @param {string} fk - 부모가 들고 있는 외래키 컬럼.
+     * @param {string} as - 부모에 붙일 속성명.
+     * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, childKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+     * @returns {Promise<any[]>} parents.
+     */
+    attachOne(parents: any[], Model: any, fk: string, as: string, opts?: {
+        where?: Record<string, any>;
+        select?: string[];
+        orderBy?: any;
+        childKey?: string;
+        cache?: {
+            key: string;
+            ttl?: number;
+            bucket: string;
+        };
+        fetch?: (ids: any[]) => Promise<any[]>;
+    }): Promise<any[]>;
+    /**
+     * per-row 보강 — 각 행에 `fn` 적용(N+1 본질, concurrency 는 동시성만). cache 로 행별 결과 재사용.
+     *
+     * @param {any[]} rows - 대상 배열(제자리 mutate 후 반환).
+     * @param {(row: any) => Promise<any>} fn - 행별 콜백.
+     * @param {number | { concurrency?: number, settled?: boolean, cache?: { key: (row: any) => string, ttl?: number, bucket: string } }} [opts]
+     * @returns {Promise<any[]>} rows.
+     */
+    enrich(rows: any[], fn: (row: any) => Promise<any>, opts?: number | {
+        concurrency?: number;
+        settled?: boolean;
+        cache?: {
+            key: (row: any) => string;
+            ttl?: number;
+            bucket: string;
+        };
+    }): Promise<any[]>;
+    /**
+     * 동시 실행 — thunk(`() => Promise`)의 객체/배열을 받아 같은 형태로 결과 반환(동시성 제한 가능).
+     *
+     * @param {Record<string, () => Promise<any>> | Array<() => Promise<any>>} specs
+     * @param {number | { concurrency?: number, settled?: boolean }} [opts]
+     * @returns {Promise<any>}
+     */
+    parallel(specs: Record<string, () => Promise<any>> | Array<() => Promise<any>>, opts?: number | {
+        concurrency?: number;
+        settled?: boolean;
+    }): Promise<any>;
 }

package/types/core/service-helpers/attach.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 1:N 배치 머지 — `parent[parentKey]`(기본 `id`) ↔ `child[fk]`. 부모마다 매칭 자식 **배열**을 붙인다.
+ *
+ * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+ * @param {any} Model - 자식 모델.
+ * @param {string} fk - 자식의 외래키 컬럼.
+ * @param {string} as - 부모에 붙일 속성명.
+ * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, limit?: number, parentKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+ * @param {(bucket: string) => any} [cacheFor]
+ * @param {any} [logger]
+ * @returns {Promise<any[]>} parents(동일 참조).
+ */
+export function attachMany(parents: any[], Model: any, fk: string, as: string, opts?: {
+    where?: Record<string, any>;
+    select?: string[];
+    orderBy?: any;
+    limit?: number;
+    parentKey?: string;
+    cache?: {
+        key: string;
+        ttl?: number;
+        bucket: string;
+    };
+    fetch?: (ids: any[]) => Promise<any[]>;
+}, cacheFor?: (bucket: string) => any, logger?: any): Promise<any[]>;
+/**
+ * N:1 배치 머지 — `parent[fk]` ↔ `child[childKey]`(기본 `id`). 부모마다 매칭 자식 **하나**(없으면 null).
+ *
+ * 주의: 부모 쪽 매칭 컬럼은 위치 인자 `fk` 로 고정된다. 튜닝 가능한 건 자식 쪽 컬럼이라
+ * `opts.childKey`(기본 `id`)로 노출한다.
+ *
+ * @param {any[]} parents - 부모 레코드(제자리 mutate 후 반환).
+ * @param {any} Model - 자식 모델.
+ * @param {string} fk - 부모가 들고 있는 외래키 컬럼(자식 식별자 값).
+ * @param {string} as - 부모에 붙일 속성명.
+ * @param {{ where?: Record<string, any>, select?: string[], orderBy?: any, childKey?: string, cache?: { key: string, ttl?: number, bucket: string }, fetch?: (ids: any[]) => Promise<any[]> }} [opts]
+ * @param {(bucket: string) => any} [cacheFor]
+ * @param {any} [logger]
+ * @returns {Promise<any[]>} parents(동일 참조).
+ */
+export function attachOne(parents: any[], Model: any, fk: string, as: string, opts?: {
+    where?: Record<string, any>;
+    select?: string[];
+    orderBy?: any;
+    childKey?: string;
+    cache?: {
+        key: string;
+        ttl?: number;
+        bucket: string;
+    };
+    fetch?: (ids: any[]) => Promise<any[]>;
+}, cacheFor?: (bucket: string) => any, logger?: any): Promise<any[]>;

package/types/core/service-helpers/enrich.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `rows` 각 항목에 `fn` 을 적용한다. `fn` 반환값이 `undefined` 가 아니면 그 값으로 교체하고,
+ * `undefined` 면 (제자리 mutate 된) 원본 행을 유지한다.
+ *
+ * @param {any[]} rows - 대상 배열(제자리 mutate 후 반환).
+ * @param {(row: any) => Promise<any>} fn - 행별 콜백.
+ * @param {number | { concurrency?: number, settled?: boolean, cache?: { key: (row: any) => string, ttl?: number, bucket: string } }} [opts]
+ *        number 면 `concurrency`. settled:true 면 일부 실패해도 진행(실패 행은 그대로 두고 경고 로그).
+ * @param {(bucket: string) => any} [cacheFor] - 버킷→캐시 어댑터 resolver(cache 옵션 쓸 때만 필요).
+ * @param {any} [logger] - settled 실패 경고용(P4/P5 — silent skip 금지).
+ * @returns {Promise<any[]>} rows(동일 참조).
+ */
+export function enrich(rows: any[], fn: (row: any) => Promise<any>, opts?: number | {
+    concurrency?: number;
+    settled?: boolean;
+    cache?: {
+        key: (row: any) => string;
+        ttl?: number;
+        bucket: string;
+    };
+}, cacheFor?: (bucket: string) => any, logger?: any): Promise<any[]>;

package/types/core/service-helpers/index.d.ts

@@ -0,0 +1,4 @@
+export { enrich } from "./enrich.js";
+export { parallel } from "./parallel.js";
+export { runPool } from "./pool.js";
+export { attachMany, attachOne } from "./attach.js";

package/types/core/service-helpers/parallel.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {Record<string, () => Promise<any>> | Array<() => Promise<any>>} specs - thunk 의 객체/배열.
+ * @param {number | { concurrency?: number, settled?: boolean }} [opts]
+ *        number 면 `concurrency`(기본 무제한). settled:true 면 `{ status, value | reason }` 로 감싸 모두 완주.
+ * @returns {Promise<any>} specs 와 동일 형태의 결과.
+ */
+export function parallel(specs: Record<string, () => Promise<any>> | Array<() => Promise<any>>, opts?: number | {
+    concurrency?: number;
+    settled?: boolean;
+}): Promise<any>;

package/types/core/service-helpers/pool.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 바운디드 동시성 실행기 — service-helpers(enrich/parallel)가 공유한다(ADR-230).
+ *
+ * 신규 dep 없이(`p-limit` 미도입) 입력 순서를 보존하며 동시 실행 수만 제한한다. 두 모드:
+ *   - `settled:false`(기본) — 첫 worker rejection 에서 전체를 reject 한다(Promise.all 의미). 이미
+ *     시작된 worker 는 자연 종료되지만 결과는 버려진다.
+ *   - `settled:true` — 각 항목을 `{ status, value | reason }` 로 감싸 **모두 완주**한다(allSettled 의미).
+ *
+ * @module core/service-helpers/pool
+ */
+/**
+ * @template T, R
+ * @typedef {{ status: 'fulfilled', value: R } | { status: 'rejected', reason: any }} Settled
+ */
+/**
+ * `items` 를 `worker` 로 매핑하되 동시 실행 수를 `concurrency` 로 제한한다. 결과 배열은 입력 순서 보존.
+ *
+ * @template T, R
+ * @param {T[]} items - 매핑 대상.
+ * @param {(item: T, index: number) => Promise<R>} worker - 각 항목 처리(반환값이 결과).
+ * @param {{ concurrency?: number, settled?: boolean }} [opts] - `concurrency` 미지정/비양수면 무제한(=항목 수).
+ * @returns {Promise<Array<R | Settled<T, R>>>} settled 면 descriptor 배열, 아니면 결과 배열.
+ */
+export function runPool<T, R>(items: T[], worker: (item: T, index: number) => Promise<R>, opts?: {
+    concurrency?: number;
+    settled?: boolean;
+}): Promise<Array<R | Settled<T, R>>>;
+export type Settled<T, R> = {
+    status: "fulfilled";
+    value: R;
+} | {
+    status: "rejected";
+    reason: any;
+};

package/types/index.d.ts

@@ -18,7 +18,7 @@ export { registerAspPlugin } from "./lib/asp/plugin.js";
 export { MegaAspTerminator } from "./lib/asp/ws-terminator.js";
 export { normalizeAspConfig } from "./lib/asp/config.js";
 export { MegaHubLink } from "./core/hub-link.js";
-export { MegaApp, MegaServer, Router, loadAndValidateConfig, loadRoutes, bootApp, buildBootContext, getApp, hasApp, MegaService, MegaCluster, wrapEnvelope, errorEnvelope, buildErrorHandler, ajvErrorToValidationError, MegaWebSocketController, createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN, buildHttpCtx, buildAdapterAccessors, registerSession, generateSid, readSession, createSessionStore, SESSION_STORE_DRIVERS, createSessionCleanupSchedule } from "./core/index.js";
+export { MegaApp, MegaServer, Router, loadAndValidateConfig, loadRoutes, bootApp, buildBootContext, getApp, hasApp, MegaService, attachMany, attachOne, enrich, parallel, MegaCluster, wrapEnvelope, errorEnvelope, buildErrorHandler, ajvErrorToValidationError, MegaWebSocketController, createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN, buildHttpCtx, buildAdapterAccessors, registerSession, generateSid, readSession, createSessionStore, SESSION_STORE_DRIVERS, createSessionCleanupSchedule } from "./core/index.js";
 export { runCli, parseArgs, runWorkerHost, runSchedulerHost, dispatchPluginCommand, USAGE } from "./cli/index.js";
 export { MegaHttpError, MegaValidationError, MegaAuthError, MegaForbiddenError, MegaNotFoundError, MegaConflictError, MegaInternalError } from "./errors/http-errors.js";
 export { buildLogger, buildLoggerOptions, buildTargets } from "./lib/mega-logger.js";