mega-framework 0.1.0

package/src/core/i18n.js

@@ -0,0 +1,525 @@
+// @ts-check
+/**
+ * MegaApp i18n(국제화) 자동 등록 — `i18next` 통합.
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   웹 앱을 여러 나라 말로 보여주려면 "키 → 번역문" 사전이 필요하다. `user.not_found` 같은 키를 주면
+ *   한국어면 "사용자를 찾을 수 없습니다", 영어면 "User not found" 를 돌려준다. 본 모듈은 검증된 표준
+ *   라이브러리 `i18next`(per ADR-037) 를 앱마다 한 인스턴스 띄우고, 그 위에 **요청별 언어 결정(쿠키)**·
+ *   **scope 분리(server/client)**·**관측성(트레이싱·메트릭)**·**개발 모드 자동 키 생성(saveMissing)** 을 얹는다.
+ *
+ * # 동작 한눈에 (session.js / multipart.js 형제 패턴)
+ *   1. `registerI18n(fastify, { i18n })` — `i18n` config 가 있을 때만 옵트인 등록.
+ *   2. `locales/<scope>/<lng>.json`(디렉터리) + inline `i18n.resources` 를 i18next 인스턴스로 로드.
+ *   3. onRequest hook — **쿠키만으로 언어 결정**(ADR-038). `req.lang` + `req.t`(server scope 번역기) +
+ *      `req.setLocale(lng)`(쿠키 발급) + `req.translations(scope)`(client 번들) 를 요청에 부착.
+ *   4. ctx-builder 가 `req.lang`/`req.t` 를 `ctx.lang`/`ctx.t` 로 노출(canonical, docs/03 §632).
+ *   5. (옵션) `GET /i18n/translations` — **client scope 만** 노출(ADR-039 — 서버 키가 SPA 로 새지 않게).
+ *
+ * # scope 분리 (ADR-039)
+ *   scope 를 i18next **namespace** 로 매핑한다 — `server`(에러·검증 메시지, defaultNS)·`client`(SPA UI).
+ *   `ctx.t()` 는 server scope 자동 선택. HTTP 번역 endpoint 는 client scope 만 돌려줘 서버 전용 키가
+ *   클라 번들에 노출되지 않게 한다(보안·번들 크기).
+ *
+ * # locale 결정 = 쿠키만 (ADR-038)
+ *   query·`Accept-Language` 헤더 미사용. 언어 변경은 명시적 API(`req.setLocale`)로 서버가 쿠키 발급.
+ *   동작이 한 곳(쿠키)에서만 결정돼 예측 가능. 쿠키값이 `available` 에 없으면 fallback 으로 클램프.
+ *
+ * # saveMissing (명시적 개발 모드 한정 `NODE_ENV==='development'`, ADR-037/164 — axion 패턴)
+ *   dev 에서 코드가 새 키를 부르면 locale 파일에 자동 추가한다: 500ms 디바운스(같은 키 폭주 흡수) →
+ *   기존 키 보존 deep-merge → tmp 작성 → rename(원자적 쓰기) → `timer.unref()`(프로세스 종료 안 막음).
+ *   누락 키는 **설정된 모든 available 언어**(예: ko·en) 파일에 기입한다(ADR-164) — 키가 전 언어에 존재해야
+ *   다음 요청에서 재트리거되지 않는다(재오염 루프 차단). 기입 값은 defaultValue, 없으면 **키 이름**(모든
+ *   언어 동일 → 개발자가 이후 번역). 또한 init 시 **언어 간 키 parity 보정**(`reconcileLocaleKeys`)으로
+ *   한 언어에만 있는 키(예: en 만 있고 ko 없음)를 나머지 언어에 **fallback 값 우선**으로 채운다 — i18next 가
+ *   fallback 으로 찾아 missingKeyHandler 가 안 터지는 공백을 메운다. **자동 기입은 `NODE_ENV==='development'`
+ *   에서만** — test/CI/prod/미설정에선 off 라 추적 locale 파일을 디스크 기입하지 않는다(ADR-164, 테스트 오염 방지).
+ *
+ * # 트레이싱·메트릭 (ADR-126 / ADR-131 인프라 재사용)
+ *   - 트레이싱: onRequest 가 활성 HTTP span 에 `mega.i18n.lang` 기록. 옵트인 OFF 면 0 비용 no-op.
+ *   - 메트릭: `mega_i18n_events_total{app,lang,scope,event=request|missing}` — 요청당 1건(언어 분포) +
+ *     누락 키(dev 관측). lang/scope 는 bounded 라 카디널리티 안전.
+ *
+ * # CSRF·ASP 통합
+ *   locale 쿠키(`mega.lang`)는 보안 토큰이 아니다(httpOnly:false — SPA 가 읽을 수 있게). 번역 endpoint 는
+ *   GET 이라 CSRF(폼 mutation) 대상이 아니고, ASP enabledPaths 에 없으면 평문. **별도 보안 배선 불필요**.
+ *
+ * @module core/i18n
+ * @see ADR-037 (i18next 채택), ADR-038 (쿠키만), ADR-039 (scope 분리), ADR-135
+ * @see https://www.i18next.com/
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { writeFile, rename, mkdir } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import i18next from 'i18next'
+import { MegaValidationError } from '../errors/http-errors.js'
+import * as MegaTracing from '../lib/mega-tracing.js'
+import { recordI18n } from '../lib/mega-metrics.js'
+
+/** locale 쿠키 기본 이름 (04-data-models §394 `cookieName: 'mega.lang'`). */
+export const DEFAULT_I18N_COOKIE = 'mega.lang'
+
+/** scope 분리 고정 namespace 2종 (ADR-039). server=에러·검증, client=SPA UI. */
+export const I18N_SCOPES = Object.freeze(['server', 'client'])
+
+/** server scope = 기본 namespace — `ctx.t()` 가 자동 선택(ADR-039). */
+export const DEFAULT_SCOPE = 'server'
+
+/** saveMissing 디바운스 기본값 (ms, ADR-037 axion 패턴). */
+export const DEFAULT_DEBOUNCE_MS = 500
+
+/** locale 쿠키 기본 수명 (1년, 초). 보안 토큰 아니라 길게 — 사용자 언어 선호 유지. */
+const DEFAULT_COOKIE_MAX_AGE_SEC = 365 * 24 * 60 * 60
+
+/**
+ * i18n 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} I18nSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {string} default - 기본 언어.
+ * @property {string} fallback - fallback 언어.
+ * @property {string[]} available - 지원 언어 목록.
+ * @property {string} cookieName - locale 쿠키 이름.
+ * @property {boolean} autoComplete - saveMissing(dev 자동 키 생성) 활성 여부.
+ * @property {import('i18next').i18n | null} instance - 생성된 i18next 인스턴스(미등록 시 null).
+ */
+
+/**
+ * 정규화된 i18n 설정.
+ * @typedef {Object} NormalizedI18n
+ * @property {string} default
+ * @property {string} fallback
+ * @property {string[]} available
+ * @property {string} cookieName
+ * @property {{ enabled: boolean, dir: string|null, debounceMs: number }} autoComplete
+ * @property {string|null} localesDir
+ * @property {Record<string, any>} resources
+ * @property {boolean} exposeTranslations
+ * @property {string} translationsPath
+ */
+
+/**
+ * 앱 `i18n` config 를 정규화한다. falsy 면 미옵트인(`null`).
+ *
+ * 잘못된 형태는 **fail-fast** 로 throw 한다(silent 보정 X). `available` 이 배열이 아니거나 비었으면
+ * 부팅 에러로 드러내, locale 미설정이 런타임에 조용히 fallback 으로 뭉개지지 않게 한다.
+ *
+ * @param {unknown} i18n - `MegaI18nAppConfig`(default/available/fallback/cookieName/autoComplete/...).
+ * @returns {NormalizedI18n | null}
+ * @throws {Error} `available` 가 비-배열/빈 배열 등 명백한 오설정.
+ */
+export function normalizeI18n(i18n) {
+  if (!i18n || typeof i18n !== 'object') return null
+  const c = /** @type {Record<string, any>} */ (i18n)
+
+  const available = Array.isArray(c.available) ? c.available.filter((/** @type {unknown} */ l) => typeof l === 'string' && l.length > 0) : []
+  if (available.length === 0) {
+    throw new Error("registerI18n: i18n.available must be a non-empty string[] (e.g. ['ko', 'en']) — locale set is required (ADR-038).")
+  }
+  const def = typeof c.default === 'string' && available.includes(c.default) ? c.default : available[0]
+  const fallback = typeof c.fallback === 'string' && available.includes(c.fallback) ? c.fallback : def
+  const cookieName = typeof c.cookieName === 'string' && c.cookieName.length > 0 ? c.cookieName : DEFAULT_I18N_COOKIE
+
+  const ac = c.autoComplete && typeof c.autoComplete === 'object' ? c.autoComplete : {}
+  // 자동 기입은 **명시적 개발 모드**(`NODE_ENV==='development'`)에서만 — test/CI/미설정(undefined)에서 켜면
+  // vitest 부팅이 추적된 locale 파일을 디스크 기입해 오염시킨다(ADR-164). 샘플은 (a)로 dev=`NODE_ENV=development`,
+  // start=`production` 이라 정확히 맞물린다. 명시 `autoComplete.enabled` 가 있으면 그것을 우선.
+  const autoEnabled = ac.enabled !== undefined ? ac.enabled === true : process.env.NODE_ENV === 'development'
+  const debounceMs = Number.isInteger(ac.debounceMs) && ac.debounceMs >= 0 ? ac.debounceMs : DEFAULT_DEBOUNCE_MS
+
+  // localesDir: 명시 우선, 없으면 autoComplete.dir. 디렉터리 로딩·saveMissing 쓰기의 기준 경로.
+  const localesDir = typeof c.localesDir === 'string' && c.localesDir.length > 0 ? c.localesDir : typeof ac.dir === 'string' && ac.dir.length > 0 ? ac.dir : null
+
+  const resources = c.resources && typeof c.resources === 'object' ? c.resources : {}
+  const exposeTranslations = c.exposeTranslations !== false // 디폴트 ON(ADR-039 client endpoint).
+  const translationsPath = typeof c.translationsPath === 'string' && c.translationsPath.length > 0 ? c.translationsPath : '/i18n/translations'
+
+  return { default: def, fallback, available, cookieName, autoComplete: { enabled: autoEnabled, dir: localesDir, debounceMs }, localesDir, resources, exposeTranslations, translationsPath }
+}
+
+/**
+ * `<dir>/<scope>/<lng>.json` 디렉터리 구조에서 locale 리소스를 로드한다(ADR-039 scope 분리 레이아웃,
+ * 04-data-models §768). 파일이 없으면 건너뛴다(빈 namespace). 부팅 시 1회 동기 읽기.
+ *
+ * @param {string|null} dir - locale 루트 디렉터리. null 이면 빈 리소스.
+ * @param {object} opts
+ * @param {string[]} opts.available - 로드할 언어 목록.
+ * @param {{ warn?: Function }} [opts.logger]
+ * @returns {Record<string, Record<string, object>>} `{ <lng>: { <scope>: {...} } }` i18next resources 형태.
+ */
+export function loadLocaleResources(dir, { available, logger } = /** @type {any} */ ({})) {
+  /** @type {Record<string, Record<string, object>>} */
+  const resources = {}
+  if (!dir || !Array.isArray(available)) return resources
+  for (const lng of available) {
+    for (const scope of I18N_SCOPES) {
+      const file = join(dir, scope, `${lng}.json`)
+      if (!existsSync(file)) continue
+      try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'))
+        if (parsed && typeof parsed === 'object') {
+          resources[lng] = resources[lng] ?? {}
+          resources[lng][scope] = parsed
+        }
+      } catch (err) {
+        // 손상된 locale 파일은 부팅을 막지 않되 조용히 넘기지 않는다 — warn 으로 드러내고 빈 namespace.
+        logger?.warn?.({ file, err }, 'i18n.locale_parse_failed')
+      }
+    }
+  }
+  return resources
+}
+
+/**
+ * 두 resources 트리를 깊게 병합한다(`base` 위에 `override`). 디스크 파일(base) + inline config(override)
+ * 결합용 — inline 이 같은 키를 덮어쓴다.
+ * @param {Record<string, any>} base @param {Record<string, any>} override @returns {Record<string, any>}
+ */
+function mergeResources(base, override) {
+  /** @param {any} a @param {any} b @returns {any} */
+  const deep = (a, b) => {
+    if (b === null || typeof b !== 'object' || Array.isArray(b)) return b
+    const out = a && typeof a === 'object' && !Array.isArray(a) ? { ...a } : {}
+    for (const k of Object.keys(b)) out[k] = deep(out[k], b[k])
+    return out
+  }
+  return deep(base, override)
+}
+
+/**
+ * dot-notation 키를 중첩 객체에 set 한다(기존 키 보존). saveMissing 머지용.
+ * @param {Record<string, any>} obj @param {string} key - `a.b.c` @param {string} value @returns {void}
+ */
+function setNested(obj, key, value) {
+  const parts = key.split('.')
+  let node = obj
+  for (let i = 0; i < parts.length - 1; i++) {
+    const p = parts[i]
+    if (node[p] === null || typeof node[p] !== 'object') node[p] = {}
+    node = node[p]
+  }
+  node[parts[parts.length - 1]] = value
+}
+
+/**
+ * 중첩 locale 객체를 `dot.path → 문자열값` 맵으로 평탄화한다(leaf 문자열만; 중첩 객체는 재귀).
+ * @param {Record<string, any>} obj @param {string} [prefix] @param {Map<string,string>} [out]
+ * @returns {Map<string,string>}
+ */
+function flattenLeafKeys(obj, prefix = '', out = new Map()) {
+  if (!obj || typeof obj !== 'object') return out
+  for (const k of Object.keys(obj)) {
+    const v = obj[k]
+    const path = prefix ? `${prefix}.${k}` : k
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) flattenLeafKeys(v, path, out)
+    else if (typeof v === 'string') out.set(path, v)
+  }
+  return out
+}
+
+/**
+ * dev 언어 간 키 parity 보정 — **한 언어에만 있는 키를 나머지 모든 available 언어에 채운다**(ADR-164).
+ *
+ * i18next 는 ko 에 없고 en 에만 있는 키를 `fallbackLng` 로 찾아 en 값을 돌려주지만, 이를 "누락"으로 보지
+ * 않아 `missingKeyHandler` 가 발화하지 않는다(소스 확인) → ko.json 이 영영 안 채워진다. 그래서 init 전
+ * 병합된 resources 에서 scope 별 키 합집합을 구해, 키가 빠진 언어에 **fallback 언어 값 우선**(없으면 그 키를
+ * 가진 첫 available 언어 값)으로 채운다. in-memory 반영(즉시 `t()` 가 그 값 반환) + writer 있으면 디스크
+ * 기입(다음 부팅 idempotent). prod 는 호출 안 함(resources 원본 그대로).
+ *
+ * @param {Record<string, Record<string, any>>} resources - `{ <lng>: { <scope>: {...} } }`.
+ * @param {object} opts
+ * @param {string[]} opts.available
+ * @param {string} opts.fallback
+ * @param {readonly string[]} opts.scopes
+ * @param {ReturnType<typeof createMissingKeyWriter>|null} opts.writer
+ * @returns {Record<string, Record<string, any>>} 보정된 resources(입력 불변, 새 트리 반환).
+ */
+function reconcileLocaleKeys(resources, { available, fallback, scopes, writer }) {
+  const out = mergeResources({}, resources) // 깊은 복제(입력 불변).
+  for (const scope of scopes) {
+    /** @type {Map<string, Map<string,string>>} 언어별 평탄 맵. */
+    const flatByLng = new Map()
+    /** @type {Set<string>} 전 언어 키 합집합. */
+    const union = new Set()
+    for (const lng of available) {
+      const flat = flattenLeafKeys(out[lng]?.[scope] ?? {})
+      flatByLng.set(lng, flat)
+      for (const key of flat.keys()) union.add(key)
+    }
+    if (union.size === 0) continue
+    for (const lng of available) {
+      const flat = flatByLng.get(lng) ?? new Map()
+      for (const key of union) {
+        if (flat.has(key)) continue // 이미 있으면 보존.
+        // 값 우선순위: fallback 언어 값 → 그 키를 가진 첫 available 언어 값(union 이라 최소 1개 존재).
+        let value = flatByLng.get(fallback)?.get(key)
+        if (typeof value !== 'string') {
+          for (const other of available) {
+            const v = flatByLng.get(other)?.get(key)
+            if (typeof v === 'string') { value = v; break }
+          }
+        }
+        if (typeof value !== 'string') continue
+        out[lng] = out[lng] ?? {}
+        out[lng][scope] = out[lng][scope] ?? {}
+        setNested(out[lng][scope], key, value)
+        writer?.enqueue(lng, scope, key, value)
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * saveMissing 디바운스 writer 를 만든다 — axion 패턴(ADR-037).
+ *
+ * `(lng, scope, key, value)` 누락 키를 모아 `<dir>/<scope>/<lng>.json` 파일에 **기존 키 보존**하며
+ * 병합 저장한다. 같은 파일의 연속 호출은 `debounceMs` 동안 흡수(타이머 1개)하고, flush 시:
+ *   1. 기존 파일 읽어 base 로(없으면 {}),
+ *   2. 모아둔 누락 키를 dot-notation 으로 set(기존 키 안 건드림),
+ *   3. tmp 파일 작성 → `rename`(원자적 쓰기 — 부분 파일 노출 방지),
+ *   4. `timer.unref()` 라 보류 중 타이머가 프로세스 종료를 막지 않음.
+ *
+ * 쓰기 실패는 비치명적(dev 편의 기능) — warn 후 다음 호출에 재시도.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir - locale 루트 디렉터리.
+ * @param {number} opts.debounceMs
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger]
+ * @returns {{ enqueue: (lng: string, scope: string, key: string, value: string) => void, flushAll: () => Promise<void>, _pendingCount: () => number }}
+ */
+export function createMissingKeyWriter({ dir, debounceMs, logger }) {
+  /** 파일별(`<lng>:<scope>`) 보류 상태: 모아둔 키 + 타이머. @type {Map<string, { lng: string, scope: string, pending: Map<string, string>, timer: NodeJS.Timeout | null }>} */
+  const files = new Map()
+
+  /** @param {string} lng @param {string} scope */
+  const flush = async (lng, scope) => {
+    const fileKey = `${lng}:${scope}`
+    const entry = files.get(fileKey)
+    if (!entry || entry.pending.size === 0) return
+    const pending = entry.pending
+    entry.pending = new Map() // flush 중 들어오는 새 키는 다음 사이클로.
+    entry.timer = null
+
+    const path = join(dir, scope, `${lng}.json`)
+    try {
+      /** @type {Record<string, any>} */
+      let base = {}
+      if (existsSync(path)) {
+        try {
+          base = JSON.parse(readFileSync(path, 'utf8')) || {}
+        } catch (err) {
+          // 손상 파일을 통째로 덮어쓰면 사람이 쓴 키가 날아간다 — 머지 포기하고 재전파 없이 보류 복원.
+          logger?.warn?.({ path, err }, 'i18n.saveMissing read failed (skip merge)')
+          for (const [k, v] of pending) entry.pending.set(k, v)
+          return
+        }
+      }
+      for (const [k, v] of pending) setNested(base, k, v)
+      await mkdir(dirname(path), { recursive: true })
+      const tmp = `${path}.${process.pid}.tmp`
+      await writeFile(tmp, JSON.stringify(base, null, 2) + '\n', 'utf8')
+      await rename(tmp, path) // 원자적 교체.
+      logger?.debug?.({ path, keys: pending.size }, 'i18n.saveMissing flushed')
+    } catch (err) {
+      logger?.warn?.({ path, err }, 'i18n.saveMissing write failed (will retry)')
+      for (const [k, v] of pending) entry.pending.set(k, v) // 실패분 복원 — 다음 호출에 재시도.
+    }
+  }
+
+  return {
+    enqueue(lng, scope, key, value) {
+      const fileKey = `${lng}:${scope}`
+      let entry = files.get(fileKey)
+      if (!entry) {
+        entry = { lng, scope, pending: new Map(), timer: null }
+        files.set(fileKey, entry)
+      }
+      entry.pending.set(key, value)
+      if (entry.timer) return // 디바운스 — 이미 타이머 대기 중.
+      entry.timer = setTimeout(() => {
+        flush(lng, scope).catch((err) => logger?.warn?.({ lng, scope, err }, 'i18n.saveMissing flush error'))
+      }, debounceMs)
+      entry.timer.unref?.() // 보류 타이머가 프로세스 종료를 막지 않게(axion 패턴).
+    },
+    async flushAll() {
+      for (const { lng, scope, timer } of files.values()) {
+        if (timer) clearTimeout(timer)
+        await flush(lng, scope)
+      }
+    },
+    _pendingCount() {
+      let n = 0
+      for (const e of files.values()) n += e.pending.size
+      return n
+    },
+  }
+}
+
+/**
+ * 요청 Cookie 헤더에서 locale 쿠키를 읽어 유효 언어로 결정한다(ADR-038 — 쿠키만).
+ *
+ * 쿠키가 없거나 `available` 에 없는 값이면 `default` 로 폴백한다(조용한 클램프 — 변조·구식 쿠키 방어).
+ *
+ * @param {string|undefined} cookieHeader - `req.headers.cookie`.
+ * @param {object} opts
+ * @param {string} opts.cookieName
+ * @param {string[]} opts.available
+ * @param {string} opts.default
+ * @returns {string} 결정된 언어.
+ */
+export function detectLocale(cookieHeader, { cookieName, available, default: def }) {
+  const raw = readCookie(cookieHeader, cookieName)
+  if (raw && available.includes(raw)) return raw
+  return def
+}
+
+/**
+ * Cookie 헤더에서 특정 이름의 값을 꺼낸다(@fastify/cookie 의존 회피 — locale 쿠키 1종만 파싱, session.js 정합).
+ * @param {string|undefined} header @param {string} name @returns {string|undefined}
+ */
+function readCookie(header, name) {
+  if (!header) return undefined
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq === -1) continue
+    if (part.slice(0, eq).trim() === name) return decodeURIComponent(part.slice(eq + 1).trim())
+  }
+  return undefined
+}
+
+/**
+ * locale Set-Cookie 헤더 문자열을 만든다(session.js serializeCookie 정합, locale 전용 디폴트).
+ * @param {string} name @param {string} value @param {{ secure: boolean }} opts @returns {string}
+ */
+function serializeLocaleCookie(name, value, { secure }) {
+  // httpOnly 미설정 — SPA 가 현재 언어를 읽을 수 있게(보안 토큰 아님). SameSite=Lax, 1년 수명.
+  let str = `${name}=${encodeURIComponent(value)}; Path=/; Max-Age=${DEFAULT_COOKIE_MAX_AGE_SEC}; SameSite=Lax`
+  if (secure) str += '; Secure'
+  return str
+}
+
+/**
+ * 앱 전용 i18next 인스턴스를 만들고 init 한다(Option B — i18next 직접 통합, 추가 dep 0).
+ *
+ * scope 를 namespace 로(server=defaultNS), inline+디스크 resources 병합, dev 면 saveMissing 활성.
+ * init 은 inline resources 만 쓰면 동기적으로 완료되나, 반환 promise 는 `registerI18n` 이 onReady 에서
+ * await 해 첫 요청 전 완료를 보장한다.
+ *
+ * @param {NormalizedI18n} cfg
+ * @param {object} deps
+ * @param {string} deps.appName
+ * @param {ReturnType<typeof createMissingKeyWriter>|null} deps.writer - saveMissing writer(비활성 시 null).
+ * @param {{ debug?: Function, warn?: Function }} [deps.logger]
+ * @returns {{ instance: import('i18next').i18n, initPromise: Promise<unknown> }}
+ */
+function createI18nextInstance(cfg, { appName, writer, logger }) {
+  const fileResources = loadLocaleResources(cfg.localesDir, { available: cfg.available, logger })
+  let resources = mergeResources(fileResources, cfg.resources)
+
+  // dev: 언어 간 키 parity 보정 — 한 언어에만 있는 키(예: en 만 있고 ko 없음)를 나머지 모든 available
+  // 언어에 fallback 값 우선으로 채운다(ADR-164). i18next 가 fallback 으로 찾으면 missingKeyHandler 가
+  // 발화 안 하는 공백을 메운다. prod 는 비활성(resources 원본 그대로).
+  if (cfg.autoComplete.enabled) {
+    resources = reconcileLocaleKeys(resources, { available: cfg.available, fallback: cfg.fallback, scopes: I18N_SCOPES, writer })
+  }
+
+  const instance = i18next.createInstance()
+  const initPromise = instance.init({
+    lng: cfg.default,
+    fallbackLng: cfg.fallback,
+    supportedLngs: cfg.available,
+    ns: [...I18N_SCOPES],
+    defaultNS: DEFAULT_SCOPE,
+    resources,
+    // 서버 사이드라 HTML escape 비활성(출력 escape 는 뷰/SPA 책임). 클라 번들도 raw 로 내려 SPA 가 처리.
+    interpolation: { escapeValue: false },
+    // dev 자동 키 생성(ADR-037/164). prod 면 false 라 missingKeyHandler 미발화(0 비용).
+    saveMissing: cfg.autoComplete.enabled && writer !== null,
+    // 핸들러를 실제 요청 언어 기준 1회만 발화시킨다(기입 대상 언어는 아래에서 available 전체로 직접 결정).
+    saveMissingTo: 'current',
+    missingKeyHandler: (lngs, ns, key, fallbackValue) => {
+      const reqLng = Array.isArray(lngs) ? lngs[0] : String(lngs)
+      const scope = String(ns)
+      // 기입 값 = defaultValue(문자열)면 그대로, 없으면 키 이름(ADR-164). 모든 언어 파일에 동일 값.
+      const value = typeof fallbackValue === 'string' && fallbackValue.length > 0 ? fallbackValue : key
+      // 누락 관측(메트릭·span·로그)은 실제 요청 언어 기준 1건 — 다중 기입 중복 집계 회피.
+      recordI18n({ app: appName, lang: reqLng, scope, event: 'missing' })
+      MegaTracing.tracer.activeSpan()?.setAttributes({ 'mega.i18n.missing_key': key })
+      logger?.debug?.({ app: appName, lng: reqLng, scope, key }, 'i18n.missing_key')
+      // 설정된 **모든 available 언어** 파일에 자동 생성(ADR-164) — 키가 전 언어에 존재해야 다음 요청에서
+      // 재트리거되지 않는다(재오염 루프 차단). 값은 모든 언어 동일(defaultValue 또는 키) → 개발자가 이후 번역.
+      for (const lng of cfg.available) writer?.enqueue(lng, scope, key, value)
+    },
+  })
+  return { instance, initPromise }
+}
+
+/**
+ * Fastify 인스턴스에 i18n(`i18next`) 을 자동 등록한다 — 요청별 언어 결정·`req.t`·scope 번들·관측성.
+ *
+ * `i18n` 이 falsy 면 **미등록**(옵트인). session.js / multipart.js 형제 패턴. 호출 순서는 라우트 등록
+ * 이전 어디든 무방하다(onRequest hook + request 부착이라 라우트 순서와 무관).
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.i18n - `MegaI18nAppConfig`. falsy 면 미등록.
+ * @param {string} [opts.appName] - 앱 이름(메트릭 라벨·로그용).
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {I18nSummary}
+ */
+export function registerI18n(fastify, { i18n, appName = '(unknown)', logger } = /** @type {any} */ ({})) {
+  const cfg = normalizeI18n(i18n)
+  if (cfg === null) {
+    return { enabled: false, default: 'en', fallback: 'en', available: [], cookieName: DEFAULT_I18N_COOKIE, autoComplete: false, instance: null }
+  }
+
+  // saveMissing writer — dev + localesDir 있을 때만(쓸 디렉터리 없으면 무의미). prod/디렉터리 없으면 null.
+  const writer = cfg.autoComplete.enabled && cfg.localesDir ? createMissingKeyWriter({ dir: cfg.localesDir, debounceMs: cfg.autoComplete.debounceMs, logger }) : null
+
+  const { instance, initPromise } = createI18nextInstance(cfg, { appName, writer, logger })
+
+  // init 완료를 첫 요청 전에 보장 — inline resources 면 사실상 즉시 완료되나 promise 를 ready 에서 await.
+  fastify.addHook('onReady', async () => {
+    await initPromise
+  })
+
+  // 요청 진입 — 쿠키로 언어 결정 → req.lang/req.t/req.setLocale/req.translations 부착(길목 로그).
+  fastify.addHook('onRequest', async (req, reply) => {
+    const lang = detectLocale(req.headers.cookie, { cookieName: cfg.cookieName, available: cfg.available, default: cfg.default })
+    const r = /** @type {any} */ (req)
+    r.lang = lang
+    // req.t — server scope 고정 번역기. 시그니처 `t(key, defaultValue?, params?)`(docs/03 §632, i18next 네이티브).
+    r.t = instance.getFixedT(lang, DEFAULT_SCOPE)
+    // req.translations(scope) — 해당 언어의 scope 번들(client endpoint·SPA 푸시용). 미지정 시 client.
+    r.translations = (/** @type {string} */ scope = 'client') => instance.getResourceBundle(lang, scope) ?? {}
+    // req.setLocale(lng) — 명시 언어 변경(ADR-038). 쿠키 발급 + 현재 요청 즉시 반영. available 외면 400.
+    r.setLocale = (/** @type {string} */ lng) => {
+      if (!cfg.available.includes(lng)) {
+        throw new MegaValidationError('i18n.unsupported_locale', `Unsupported locale '${lng}'. Available: [${cfg.available.join(', ')}].`, { details: { lng, available: cfg.available } })
+      }
+      const secure = req.protocol === 'https'
+      reply.header('set-cookie', serializeLocaleCookie(cfg.cookieName, lng, { secure }))
+      r.lang = lng
+      r.t = instance.getFixedT(lng, DEFAULT_SCOPE)
+      logger?.debug?.({ app: appName, lng }, 'i18n.setLocale')
+      return lng
+    }
+    // 활성 HTTP span 에 언어 기록(ADR-126). 옵트인 OFF 면 activeSpan undefined → no-op.
+    MegaTracing.tracer.activeSpan()?.setAttributes({ 'mega.i18n.lang': lang })
+    recordI18n({ app: appName, lang, event: 'request' })
+    logger?.debug?.({ app: appName, route: req.routeOptions?.url, lang }, 'i18n.detect')
+  })
+
+  // GET /i18n/translations — client scope 번들만 노출(ADR-039 — 서버 키 비노출). 옵트인 default-on.
+  if (cfg.exposeTranslations) {
+    // 보안 면제 — locale 번들은 공개 자원(SPA 부트스트랩). CSRF 는 GET 미대상이나 명시 면제로 의도 표명.
+    fastify.get(cfg.translationsPath, { config: { skipCsrf: true } }, async (req) => {
+      const r = /** @type {any} */ (req)
+      return { lang: r.lang, scope: 'client', translations: r.translations?.('client') ?? {} }
+    })
+    logger?.debug?.({ app: appName, path: cfg.translationsPath }, 'i18n.translations endpoint registered')
+  }
+
+  logger?.debug?.({ app: appName, default: cfg.default, available: cfg.available, autoComplete: cfg.autoComplete.enabled }, 'i18n.registered')
+  return { enabled: true, default: cfg.default, fallback: cfg.fallback, available: cfg.available, cookieName: cfg.cookieName, autoComplete: cfg.autoComplete.enabled && writer !== null, instance }
+}

package/src/core/index.js

@@ -0,0 +1,63 @@
+// @ts-check
+export { MegaApp } from './mega-app.js'
+export { MegaServer } from './mega-server.js'
+export { Router, MegaRouteError } from './router.js'
+export { MegaService } from './mega-service.js'
+export { MegaCluster } from './mega-cluster.js'
+export { loadRoutes } from './routes-loader.js'
+// 중앙 부팅 orchestrator (ADR-123)
+export { bootApp, buildBootContext } from './boot.js'
+export { wrapEnvelope, errorEnvelope } from './envelope.js'
+export { buildErrorHandler } from './error-mapper.js'
+export { ajvErrorToValidationError } from './ajv-mapper.js'
+export { loadAndValidateConfig } from './config-loader.js'
+// 요청 ctx 빌더 — db/cache/bus 접근자 배선 (ADR-102)
+export { buildHttpCtx, getHttpCtx, buildAdapterAccessors } from './ctx-builder.js'
+// WS envelope + 컨트롤러 베이스 (ADR-015 / ADR-074)
+export {
+  createWsMessage,
+  validateWsMessage,
+  parseWsMessage,
+  generateMessageId,
+  WS_MESSAGE_SCHEMA,
+  WS_PROTOCOL_VERSION,
+  WS_TYPE_PATTERN,
+} from './ws-message.js'
+export { MegaWebSocketController } from './ws-controller.js'
+// WS upgrade 핸들오프 (embedded 종단, ADR-083/084)
+export {
+  MegaWsConnection,
+  driveWsConnection,
+  createPlainCodec,
+  createAspCodec,
+  rejectUpgrade,
+  CLOSE_CODE_DECRYPT_FAILED,
+  CLOSE_CODE_INTERNAL_ERROR,
+} from './ws-upgrade.js'
+// Bridge↔Hub 12-타입 프로토콜 (ADR-033/059/097)
+export { MegaHubLink } from './hub-link.js'
+// WS per-message deflate 압축 (ADR-078)
+export {
+  buildPerMessageDeflate,
+  checkCompressionConfig,
+  COMPRESSION_DEFAULTS,
+} from './ws-compression.js'
+export {
+  validateGlobalConfig,
+  validateAppConfig,
+  validateHostCollisions,
+} from './config-validator.js'
+// 보안 플러그인 자동 등록 — helmet/cors/rate-limit/csrf + ASP HTTP (ADR-127)
+export { registerSecurityPlugins, DEFAULT_RATE_LIMIT } from './security.js'
+// 세션 — 미들웨어 + 스토어 팩토리 (ADR-129/046)
+export { registerSession, generateSid, readSession } from './session.js'
+export { createSessionStore, SESSION_STORE_DRIVERS } from './session-store.js'
+export { createSessionCleanupSchedule } from './session-cleanup-schedule.js'
+// i18n — i18next 통합 + 쿠키 locale + scope 분리 (ADR-037/038/039/135)
+export { registerI18n, normalizeI18n, detectLocale, loadLocaleResources, createMissingKeyWriter, DEFAULT_I18N_COOKIE, I18N_SCOPES } from './i18n.js'
+// 템플릿 — EJS + ejs-mate 서버사이드 렌더 + reply.render/ctx.render + i18n 통합 (ADR-011/136)
+export { registerTemplate, MegaTemplate, normalizeViews, resolveViewPath, renderView, VIEW_ENGINE } from './template.js'
+// 정적 자산 — @fastify/static 옵트인 (ADR-071/139)
+export { registerStaticAssets, normalizeStaticAssets, DEFAULT_STATIC_PREFIX } from './static-assets.js'
+// OpenAPI/Swagger — @fastify/swagger + swagger-ui 옵트인 (ADR-070/140)
+export { registerOpenapi, normalizeOpenapi, DEFAULT_OPENAPI_PATH } from './openapi.js'