mega-framework 0.1.5 → 0.1.7

package/src/core/cluster-metrics.js

@@ -250,20 +250,29 @@ export function collectCluster({ timeoutMs = 2500, _cluster = cluster, _proc = p
     }
     const timer = setTimeout(() => {
       cleanup()
-      // 마스터 무응답 → 로컬 폴백(이 워커 메트릭만이라도).
+      // 마스터 무응답 → 로컬 폴백(이 워커 메트릭만이라도). 폴백마저 실패하면 빈 응답으로 강등하되
+      // 묵히지 않고 알린다 — 스크레이프가 조용히 빈 값이 되는 원인을 추적 가능하게.
       Promise.resolve(MegaMetrics.collect())
         .then(resolve)
-        .catch(() => resolve(''))
+        .catch((err) => {
+          console.warn('[mega-cluster-metrics] local metrics fallback failed (returning empty):', /** @type {any} */ (err)?.message ?? err)
+          resolve('')
+        })
     }, timeoutMs)
     timer.unref?.()
     _proc.on('message', onMsg)
     try {
       _proc.send({ type: MSG_REQUEST, id })
-    } catch {
+    } catch (sendErr) {
       cleanup()
+      // 마스터 IPC 채널 단절 — 로컬 폴백으로 강등(원인을 묵히지 않는다).
+      console.warn('[mega-cluster-metrics] request to primary failed (falling back to local):', /** @type {any} */ (sendErr)?.message ?? sendErr)
       Promise.resolve(MegaMetrics.collect())
         .then(resolve)
-        .catch(() => resolve(''))
+        .catch((err) => {
+          console.warn('[mega-cluster-metrics] local metrics fallback failed (returning empty):', /** @type {any} */ (err)?.message ?? err)
+          resolve('')
+        })
     }
   })
 }

package/src/core/config-validator.js

@@ -94,6 +94,31 @@ export function validateGlobalConfig(globalConfig) {
   //    앱에서 registerSession 이 fail-fast 로 잡으므로(여긴 server.sessionSecret 가 "정의됐을 때만"
   //    강도를 검증) — 정의됐다면 (a) 기본 placeholder 거부, (b) ≥32자 강제(부팅 fail-fast, ADR-062).
   validateSessionSecret(globalConfig.server?.sessionSecret)
+
+  // 7) server 런타임 타임아웃(ADR-181) — 정의됐다면 음 아닌 정수만(Fastify requestTimeout/keepAliveTimeout).
+  validateServerTimeouts(globalConfig.server)
+}
+
+/**
+ * `server.timeouts.requestMs` · `server.keepAliveMs` 검증(ADR-181, Fastify 인스턴스 옵션으로 매핑).
+ * 정의됐다면 음 아닌 정수(ms)만 허용 — 잘못된 값은 부팅 fail-fast. `trustProxy`/`trustedProxies` 는
+ * 타입 유연(boolean/number/string/array)이라 Fastify 에 위임(여기서 검증 안 함). 미정의는 통과(선택 키).
+ * @param {any} server - `globalConfig.server`.
+ * @throws {MegaConfigError} `server.invalid_timeout`.
+ */
+function validateServerTimeouts(server) {
+  const s = server ?? {}
+  /** @param {string} name @param {unknown} v */
+  const check = (name, v) => {
+    if (v === undefined) return
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+      throw new MegaConfigError('server.invalid_timeout', `${name} must be a non-negative integer (ms). Got ${JSON.stringify(v)}.`, {
+        details: { value: v },
+      })
+    }
+  }
+  check('server.timeouts.requestMs', s.timeouts?.requestMs)
+  check('server.keepAliveMs', s.keepAliveMs)
 }
 
 /** sessionSecret 강도 검증의 최소 길이(바이트 수가 아닌 문자 길이 — base64url 32바이트 ≈ 43자). */

package/src/core/ctx-builder.js

@@ -18,7 +18,7 @@
  */
 import { MegaConfigError } from '../errors/config-error.js'
 import * as AdapterManager from '../adapters/adapter-manager.js'
-import { contextProxy as workersContext } from './workers-manager.js'
+import { contextProxy as workersContext, PROXY_PROTOCOL_KEYS } from './workers-manager.js'
 import { tracer as megaTracer } from '../lib/mega-tracing.js'
 
 /** ctx 도메인 함수 ↔ app.config 별명 맵 키. */
@@ -94,7 +94,11 @@ function buildServicesProxy(ctx, app) {
     {},
     {
       get(_t, prop) {
-        if (typeof prop !== 'string') return undefined // Symbol(then 등) — non-thenable 유지
+        if (typeof prop !== 'string') return undefined // Symbol 키(toStringTag 등) — 해석 대상 아님.
+        // 'then'/'toJSON' 등은 await·JSON.stringify·inspect 가 **string 키**로 암묵 조회한다 — 미등록
+        // 상태에서 throw 하면 `await ctx.services` 같은 정상 코드가 not_registered 로 죽는다. 등록된
+        // 이름이면(우연히 겹쳐도) 그대로 해석한다.
+        if (!registry.has(prop) && PROXY_PROTOCOL_KEYS.has(prop)) return undefined
         return resolve(prop)
       },
       has(_t, prop) {

package/src/core/envelope.js

@@ -12,6 +12,26 @@
 /** request 시작 시간 기록용 symbol (meta.took_ms 계산). reply 객체에 부착. */
 export const REPLY_START_SYMBOL = Symbol('mega.reply.start')
 
+/**
+ * 프레임워크가 만든 envelope 임을 표시하는 비열거 마킹 symbol.
+ *
+ * 이중 wrap 방지 판별을 키 모양 추측(duck-typing)이 아니라 이 마킹으로 한다 — 핸들러가 우연히
+ * `{ ok, data }` 모양의 도메인 데이터(예: 외부 API 프록시 응답)를 반환해도 정상적으로 data 로
+ * 감싸진다. 비열거라 JSON 직렬화·spread 에는 나타나지 않는다.
+ */
+export const ENVELOPE_MARK = Symbol('mega.envelope')
+
+/**
+ * envelope 객체에 비열거 마킹을 부착한다.
+ * @template {Record<string, any>} T
+ * @param {T} env
+ * @returns {T} 같은 객체 (마킹됨).
+ */
+function markEnvelope(env) {
+  Object.defineProperty(env, ENVELOPE_MARK, { value: true, enumerable: false })
+  return env
+}
+
 /**
  * 자동 envelope (ADR-018). preSerialization 훅의 마지막 단계에서 호출되어
  * raw data → `{ ok:true, data, meta }`.
@@ -29,11 +49,11 @@ export const REPLY_START_SYMBOL = Symbol('mega.reply.start')
  */
 export function wrapEnvelope(req, reply, payload) {
   if (isEnvelope(payload)) return payload
-  return {
+  return markEnvelope({
     ok: true,
     data: payload,
     meta: buildMeta(req, reply),
-  }
+  })
 }
 
 /**
@@ -44,7 +64,7 @@ export function wrapEnvelope(req, reply, payload) {
  * @returns {{ ok: false, error: { code: string, message: string, details?: any }, meta: Object }}
  */
 export function errorEnvelope(req, reply, error) {
-  return {
+  return markEnvelope({
     ok: false,
     error: {
       code: error.code,
@@ -52,22 +72,102 @@ export function errorEnvelope(req, reply, error) {
       ...(error.details !== undefined ? { details: error.details } : {}),
     },
     meta: buildMeta(req, reply),
-  }
+  })
 }
 
 /**
- * 이미 envelope 모양인지 판별 — `ok: boolean` + (`data` | `error`) 키 보유.
+ * 이미 envelope 인지 판별.
+ *
+ * 1차 = {@link ENVELOPE_MARK} 마킹(프레임워크 산출물 — wrapEnvelope/errorEnvelope 만 부착).
+ * 2차 = **수동 error envelope 하위호환**: `before` 가드 등에서 `reply.send({ ok:false, error })` 로
+ * 직접 보낸 에러 응답만 모양으로 통과시킨다. 성공 모양(`{ ok:true, data }`)의 duck-typing 통과는
+ * 제거 — 그런 모양의 도메인 데이터(외부 API 프록시 등)는 이제 정상적으로 data 로 감싸진다(오탐 제거).
+ *
  * @param {any} payload
  * @returns {boolean}
  */
 function isEnvelope(payload) {
-  return (
-    payload != null &&
-    typeof payload === 'object' &&
-    !Array.isArray(payload) &&
-    typeof payload.ok === 'boolean' &&
-    ('data' in payload || 'error' in payload)
-  )
+  if (payload == null || typeof payload !== 'object' || Array.isArray(payload)) return false
+  if (payload[ENVELOPE_MARK] === true) return true
+  return payload.ok === false && 'error' in payload
+}
+
+/** envelope `error` 필드의 JSON Schema (ADR-014/075 — details 는 object | array 자유형). */
+const ERROR_FIELD_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: { code: { type: 'string' }, message: { type: 'string' }, details: {} },
+  additionalProperties: true,
+})
+
+/** envelope `meta` 필드의 JSON Schema (향후 meta 확장에 닫히지 않게 additionalProperties 허용). */
+const META_FIELD_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: { request_id: { type: 'string' }, took_ms: { type: 'number' } },
+  additionalProperties: true,
+})
+
+/**
+ * 라우트 `schema.response` 를 envelope 모양으로 합성한다.
+ *
+ * 배경: 자동 envelope(ADR-018)는 preSerialization 마지막에 raw data 를 `{ ok, data, meta }` 로
+ * 감싸는데, 사용자가 raw data 모양의 response schema 를 선언하면 Fastify 직렬화기가 **envelope 를
+ * 그 raw 스키마로 직렬화해 ok/data/meta 가 통째로 제거**된다(silent 데이터 소실). 그래서 등록
+ * 시점(onRoute)에 각 상태코드 스키마를 `{ ok, data: <사용자 스키마>, error, meta }` 로 재작성한다 —
+ * 사용자는 계속 raw data 모양만 선언하고(ADR-091), strict 직렬화(ADR-020: 선언 외 필드 제거)는
+ * data 안에서 그대로 동작하며, OpenAPI 명세(@fastify/swagger 가 schema 수집)도 실제 와이어 모양과
+ * 일치하게 된다.
+ *
+ * 합성 제외(원본 유지) 3종:
+ *   - `type: 'string'` 스키마 — 문자열 payload 는 Fastify 가 preSerialization(envelope wrap) 자체를
+ *     건너뛰므로(raw 전송, 예: /metrics) envelope 모양으로 바꾸면 오히려 직렬화가 깨진다.
+ *   - 이미 envelope 모양(`properties.ok` 보유) — 사용자가 envelope 전체를 직접 선언한 경우.
+ *   - 스키마가 object 가 아닌 항목 — 알 수 없는 형식은 건드리지 않는다(fail-safe).
+ *
+ * Fastify v5 의 media-type 형식(`{ content: { 'application/json': { schema } } }`)은 내부 schema
+ * 에 같은 규칙을 적용한다.
+ *
+ * @param {Record<string, any>} response - 라우트 `schema.response` (상태코드/패턴 → JSON Schema).
+ * @returns {Record<string, any>} envelope 모양으로 합성된 새 response 객체 (원본 불변).
+ */
+export function synthesizeEnvelopeResponseSchema(response) {
+  /** @type {Record<string, any>} */
+  const out = {}
+  for (const [code, entry] of Object.entries(response)) {
+    out[code] = synthesizeEntry(entry)
+  }
+  return out
+}
+
+/**
+ * response 항목 1개를 envelope 모양으로 합성 (제외 규칙은 {@link synthesizeEnvelopeResponseSchema}).
+ * @param {any} entry - 상태코드별 스키마 또는 `{ content }` media-type 형식.
+ * @returns {any}
+ */
+function synthesizeEntry(entry) {
+  if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) return entry
+  // Fastify v5 media-type 형식 — content 의 각 schema 에 동일 규칙 적용.
+  if (entry.content && typeof entry.content === 'object') {
+    /** @type {Record<string, any>} */
+    const content = {}
+    for (const [mediaType, def] of Object.entries(entry.content)) {
+      content[mediaType] =
+        def && typeof def === 'object' && 'schema' in def ? { ...def, schema: synthesizeEntry(def.schema) } : def
+    }
+    return { ...entry, content }
+  }
+  if (entry.type === 'string') return entry // 문자열 payload 는 envelope 우회(raw 전송) — 원본 유지.
+  if (entry.properties && typeof entry.properties === 'object' && 'ok' in entry.properties) return entry // 이미 envelope 모양.
+  return {
+    type: 'object',
+    properties: {
+      ok: { type: 'boolean' },
+      data: entry,
+      error: ERROR_FIELD_SCHEMA,
+      meta: META_FIELD_SCHEMA,
+    },
+    required: ['ok'],
+    additionalProperties: false,
+  }
 }
 
 /**

package/src/core/hub-link.js

@@ -28,6 +28,7 @@ import { WebSocket } from 'ws'
 import {
   HUB_MESSAGE_TYPES,
   CLOSE_CODE_DRAIN,
+  HUB_PROTOCOL_VERSION,
   createHubMessage,
   parseHubMessage,
 } from '../lib/hub-protocol.js'
@@ -84,8 +85,11 @@ export class MegaHubLink {
    *   스키마 — hub 서버와 양쪽이 협상해야 활성(RFC 7692). 디폴트 OFF. 잘못된 값은 즉시 throw.
    * @param {{ warn?: Function, debug?: Function, info?: Function, error?: Function }} [opts.logger]
    * @param {typeof import('ws').WebSocket} [opts.WebSocketCtor] - 테스트 주입용 ws 생성자.
+   * @param {number} [opts.maxBufferedBytes=16777216] - 송신 버퍼(bufferedAmount) 상한(바이트). 초과 시
+   *   백프레셔로 보고 소켓을 닫고(1013) 송신을 명시 실패시킨다 — hub 가 느릴 때 bridge 힙이 무한
+   *   적재되는 것을 막는다. 재연결(retry) 설정 시 자동 회복.
    */
-  constructor({ url, token, bridgeId, instanceId, capabilities, retry, connectTimeoutMs, compression, logger, WebSocketCtor } = {}) {
+  constructor({ url, token, bridgeId, instanceId, capabilities, retry, connectTimeoutMs, compression, logger, WebSocketCtor, maxBufferedBytes } = {}) {
     if (typeof url !== 'string' || url.length === 0) {
       throw new Error('MegaHubLink: url is required (MegaBridgeHubConfig.url).')
     }
@@ -106,6 +110,8 @@ export class MegaHubLink {
     this._retry = retry && typeof retry === 'object' ? retry : null
     /** 한 attempt 의 register_ok 대기 한도(M4). reconnect 에서도 동일 적용. @type {number} */
     this._connectTimeoutMs = Number.isFinite(connectTimeoutMs) ? Number(connectTimeoutMs) : 10_000
+    /** 송신 버퍼(bufferedAmount) 상한 — 초과 시 백프레셔로 소켓을 닫는다(기본 16 MiB). @type {number} */
+    this._maxBufferedBytes = Number.isFinite(maxBufferedBytes) && Number(maxBufferedBytes) > 0 ? Number(maxBufferedBytes) : 16 * 1024 * 1024
     // Bridge↔Hub link 압축(ADR-078). enabled=false → false. 잘못된 값은 생성자에서 즉시 throw.
     /** @type {false | Object} ws 클라이언트 perMessageDeflate 로 전달(_connectOnce). */
     this._perMessageDeflate = buildPerMessageDeflate(compression, 'wsHub.compression')
@@ -128,6 +134,14 @@ export class MegaHubLink {
     this._isReconnecting = false
     /** close() 가 진행 중인 재시도(백오프 대기)를 취소하기 위한 컨트롤러. @type {AbortController | null} */
     this._abort = null
+    /** register_ok 로 협상된 hub 프로토콜 버전(등록 전 null, 레거시 hub 면 1). @type {number | null} */
+    this._negotiatedProtocolVersion = null
+    /**
+     * 레거시 hub 모드 — REGISTER 의 `protocolVersion` 필드를 모르는 구버전 hub(strict 스키마가
+     * `hub.invalid_message` 로 거부)로 판정되면 true. 이후 register 는 필드 없이(v1) 보낸다.
+     * @type {boolean}
+     */
+    this._isLegacyHub = false
   }
 
   /** hub 가 부여한 hubId (register 전엔 null). */
@@ -140,6 +154,11 @@ export class MegaHubLink {
     return this._isRegistered
   }
 
+  /** 협상된 hub 프로토콜 버전 (register 전엔 null, 레거시 hub 면 1). */
+  get negotiatedProtocolVersion() {
+    return this._negotiatedProtocolVersion
+  }
+
   /** 소켓이 OPEN(=1) 인지. */
   get isOpen() {
     return this._ws?.readyState === 1
@@ -184,7 +203,16 @@ export class MegaHubLink {
     const timeout = Number.isFinite(connectTimeoutMs) ? Number(connectTimeoutMs) : this._connectTimeoutMs
     this._connectTimeoutMs = timeout
     if (!this._retry) {
-      return this._connectOnce({ connectTimeoutMs: timeout })
+      try {
+        return await this._connectOnce({ connectTimeoutMs: timeout })
+      } catch (err) {
+        // 레거시 hub 폴백(1회) — protocolVersion 필드 거부 판정 후 v1 register 로 즉시 재시도.
+        // retry 미설정 경로 전용(백오프 경로는 withRetry 가 non-fatal 을 자동 재시도).
+        if (err instanceof Error && err.message === 'hub.legacy_register_fallback') {
+          return this._connectOnce({ connectTimeoutMs: timeout })
+        }
+        throw err
+      }
     }
     // retry 활성 — 최초 연결도 백오프 재시도. AbortError(인증 실패 등) 는 재시도하지 않는다.
     this._abort = new AbortController()
@@ -246,7 +274,7 @@ export class MegaHubLink {
       }
 
       ws.on('open', () => {
-        this._log?.debug?.({ bridgeId: this._bridgeId, url: this._url }, 'hub-link open → REGISTER')
+        this._log?.debug?.({ bridgeId: this._bridgeId, url: this._url, legacyHub: this._isLegacyHub }, 'hub-link open → REGISTER')
         try {
           this._sendEnvelope(
             createHubMessage({
@@ -255,6 +283,9 @@ export class MegaHubLink {
                 instanceId: this._instanceId,
                 token: this._token,
                 capabilities: this._capabilities,
+                // 버전 협상 — 최대 지원 버전을 싣는다. 레거시 hub(필드를 모르는 strict 스키마)로
+                // 판정된 뒤에는 싣지 않는다(v1 고정 — 아래 hub.invalid_message 폴백 참조).
+                ...(this._isLegacyHub ? {} : { protocolVersion: HUB_PROTOCOL_VERSION }),
               },
             }),
           )
@@ -281,13 +312,32 @@ export class MegaHubLink {
             didRegister = true
             this._hubId = msg.payload.hubId
             this._heartbeatMs = msg.payload.heartbeatMs
+            // 협상 결과 — hub 가 채택한 버전(echo-on-request). 부재 = v1(레거시 hub 또는 v1 고정 register).
+            this._negotiatedProtocolVersion = msg.payload.protocolVersion ?? 1
             this._startHeartbeat()
-            this._log?.info?.({ bridgeId: this._bridgeId, hubId: this._hubId }, 'hub-link registered')
+            this._log?.info?.(
+              { bridgeId: this._bridgeId, hubId: this._hubId, protocolVersion: this._negotiatedProtocolVersion },
+              'hub-link registered',
+            )
             finish(resolve, { hubId: this._hubId, heartbeatMs: this._heartbeatMs })
             return
           }
           if (msg.type === T.ERROR) {
             const code = msg.error?.code ?? 'hub.error'
+            // 레거시 hub 폴백: protocolVersion 필드를 모르는 구버전 hub 는 strict 스키마가 register 를
+            // `hub.invalid_message` 로 거부한다(연결은 유지하지만 attempt 는 종료). 한 번만 레거시로
+            // 전환해 필드 없는 v1 register 로 재시도한다 — non-fatal reject 라 retry 경로(withRetry)가
+            // 자동 재시도하고, retry 미설정 connect() 도 1회 폴백 재시도한다.
+            if (code === 'hub.invalid_message' && !this._isLegacyHub) {
+              this._isLegacyHub = true
+              this._log?.info?.(
+                { bridgeId: this._bridgeId },
+                'hub-link register rejected as invalid — assuming legacy hub (no protocolVersion), falling back to v1 register',
+              )
+              finish(reject, new Error('hub.legacy_register_fallback'))
+              ws.close()
+              return
+            }
             this._log?.warn?.({ bridgeId: this._bridgeId, code }, 'hub-link registration rejected')
             // 인증 실패 등 등록 거부는 재시도해도 같은 결과 — fatal 마킹으로 백오프 중단(ADR-098).
             finish(reject, new HubRegistrationError(`hub registration failed: ${code}`))
@@ -484,6 +534,17 @@ export class MegaHubLink {
     if (this._ws?.readyState !== 1) {
       throw new Error('MegaHubLink: socket is not open.')
     }
+    // 백프레셔 가드: hub 가 느려 송신 버퍼가 상한을 넘으면 더 쌓지 않는다 — bridge 힙이 무한 증가해
+    // OOM 으로 가는 것을 막는다. 소켓을 닫아 재연결(retry 설정 시) 경로로 회복시키고, 이번 송신은
+    // 명시 실패로 알린다(silent drop 금지 — 호출부 broadcast/join 이 warn 으로 표면화).
+    if (this._ws.bufferedAmount > this._maxBufferedBytes) {
+      this._log?.warn?.(
+        { bufferedAmount: this._ws.bufferedAmount, max: this._maxBufferedBytes },
+        'hub-link send buffer exceeded — closing socket (backpressure)',
+      )
+      this._ws.close(1013, 'backpressure: send buffer exceeded')
+      throw new Error('MegaHubLink: send buffer exceeded (backpressure) — socket closed for recovery.')
+    }
     this._ws.send(JSON.stringify(envelope))
   }
 

package/src/core/i18n.js

@@ -34,6 +34,7 @@
  *   한 언어에만 있는 키(예: en 만 있고 ko 없음)를 나머지 언어에 **fallback 값 우선**으로 채운다 — i18next 가
  *   fallback 으로 찾아 missingKeyHandler 가 안 터지는 공백을 메운다. **자동 기입은 `NODE_ENV==='development'`
  *   에서만** — test/CI/prod/미설정에선 off 라 추적 locale 파일을 디스크 기입하지 않는다(ADR-164, 테스트 오염 방지).
+ *   production 은 명시 `autoComplete.enabled:true` 도 **강제 off + warn**(ADR-186) — dev config 복사 사고 차단.
  *
  * # 트레이싱·메트릭 (ADR-126 / ADR-131 인프라 재사용)
  *   - 트레이싱: onRequest 가 활성 HTTP span 에 `mega.i18n.lang` 기록. 옵트인 OFF 면 0 비용 no-op.
@@ -123,7 +124,10 @@ export function normalizeI18n(i18n) {
   // 자동 기입은 **명시적 개발 모드**(`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'
+  // 단 **production 은 강제 off**(ADR-186) — dev config 가 prod 로 복사돼 명시 `enabled:true` 가 남아도
+  // saveMissing 디스크 기입(ADR-163 locale 오염 함정)이 켜지지 않는다. 덮어쓴 사실은 registerI18n 이 warn.
+  const requestedAuto = ac.enabled !== undefined ? ac.enabled === true : process.env.NODE_ENV === 'development'
+  const autoEnabled = process.env.NODE_ENV === 'production' ? false : requestedAuto
   const debounceMs = Number.isInteger(ac.debounceMs) && ac.debounceMs >= 0 ? ac.debounceMs : DEFAULT_DEBOUNCE_MS
 
   // localesDir: 명시 우선, 없으면 autoComplete.dir. 디렉터리 로딩·saveMissing 쓰기의 기준 경로.
@@ -473,6 +477,12 @@ export function registerI18n(fastify, { i18n, appName = '(unknown)', logger } =
     return { enabled: false, default: 'en', fallback: 'en', available: [], cookieName: DEFAULT_I18N_COOKIE, autoComplete: false, instance: null }
   }
 
+  // prod 강제 off 표면화(ADR-186) — 명시 `autoComplete.enabled:true` 를 normalizeI18n 이 production 에서
+  // 덮어썼으면 조용히 무시하지 않고 warn 으로 드러낸다(오설정 인지 — P4 정합).
+  if (process.env.NODE_ENV === 'production' && /** @type {any} */ (i18n)?.autoComplete?.enabled === true) {
+    logger?.warn?.({ app: appName }, 'i18n.autoComplete is forced off in production — saveMissing writes locale files to disk and is dev-only (ADR-164/186). Remove autoComplete.enabled:true from the production config.')
+  }
+
   // saveMissing writer — dev + localesDir 있을 때만(쓸 디렉터리 없으면 무의미). prod/디렉터리 없으면 null.
   const writer = cfg.autoComplete.enabled && cfg.localesDir ? createMissingKeyWriter({ dir: cfg.localesDir, debounceMs: cfg.autoComplete.debounceMs, logger }) : null
 

package/src/core/index.js

@@ -1,5 +1,7 @@
 // @ts-check
 export { MegaApp } from './mega-app.js'
+// WS presence/hub 협력자 — MegaApp 이 위임하는 연결 인덱스·hub link·cluster/roster 동기화 전담
+export { MegaWsPresence } from './ws-presence.js'
 export { MegaServer } from './mega-server.js'
 export { Router, MegaRouteError } from './router.js'
 export { MegaService } from './mega-service.js'
@@ -7,9 +9,11 @@ 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 { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from './envelope.js'
+// HTTP 라이프사이클 Pipeline — before/transform/after 합성 정본 (ADR-185)
+export { buildHttpPipeline, wrapPreHandler, composeTransform, composeAfter } from './pipeline.js'
 export { buildErrorHandler } from './error-mapper.js'
-export { ajvErrorToValidationError } from './ajv-mapper.js'
+export { ajvErrorToValidationError, MAX_VALIDATION_DETAILS } from './ajv-mapper.js'
 export { loadAndValidateConfig } from './config-loader.js'
 // 요청 ctx 빌더 — db/cache/bus 접근자 배선 (ADR-102)
 export { buildHttpCtx, getHttpCtx, buildAdapterAccessors } from './ctx-builder.js'