mega-framework 0.1.6 → 0.1.8

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/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 별명 맵 키. */
@@ -37,6 +37,9 @@ function passthroughT(key, defaultValue) {
 /** 요청당 ctx 를 캐싱하는 비열거 키. 글로벌 미들웨어와 라우트 핸들러가 같은 ctx 를 공유하도록 한다. */
 const HTTP_CTX_KEY = Symbol('mega.httpCtx')
 
+/** 요청당 lazy ctx 프록시 캐싱 키 — 미들웨어·핸들러가 같은 프록시 객체를 받도록 한다 (ADR-214). */
+const LAZY_CTX_KEY = Symbol('mega.lazyHttpCtx')
+
 /**
  * `ctx.services.<name>` lazy DI proxy (ADR-148) — 요청별 서비스 인스턴스화·캐시.
  *
@@ -94,7 +97,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) {
@@ -248,6 +255,61 @@ export function getHttpCtx({ app, req, reply }) {
   const cached = /** @type {any} */ (req)[HTTP_CTX_KEY]
   if (cached) return cached
   const ctx = buildHttpCtx({ app, req, reply })
-  Object.defineProperty(req, HTTP_CTX_KEY, { value: ctx, enumerable: false, configurable: true })
+  // 심볼 직접 대입 (G1 H-2, ADR-214) — 심볼 키는 어차피 Object.keys/spread/JSON 에 안 잡히므로
+  // 비열거 defineProperty 의 실익이 없고, defineProperty 는 hidden class 전이를 유발해 17배 비싸다(실측).
+  ;/** @type {any} */ (req)[HTTP_CTX_KEY] = ctx
   return ctx
 }
+
+/**
+ * **lazy** HTTP ctx — 실제 ctx 빌드를 첫 속성 접근 시점까지 미루는 요청당 프록시 (G1 H-1, ADR-214).
+ *
+ * hot path 단일 최대 프레임워크 비용이 "핸들러가 ctx 를 안 써도 매 요청 무조건 buildHttpCtx"
+ * (1,615 B + ≈0.7 µs/req, CPU 2.3% — audit-G1 실측)였다. 이 프록시는 생성 비용이 객체 1개 수준이고,
+ * 핸들러·미들웨어가 ctx 의 속성을 **처음 만질 때만** {@link getHttpCtx} 로 실 ctx 를 만든다(이후 캐시).
+ *
+ * 호환성: canonical 시그니처 `(req, reply, ctx)` 는 그대로 — 모든 핸들러가 여전히 3번째 인자를 받고,
+ * 참조하는 순간부터는 기존과 동일한 실 ctx 표면(ADR-134 요청당 공유 포함)이다. 프록시 자체도 요청당
+ * 1개로 캐시되어 미들웨어와 핸들러가 **동일 객체**(`===`)를 받는다. 모든 트랩이 실 ctx 로 위임되므로
+ * `in`/spread/`Object.keys`/getter·setter(`ctx.user=`) 동작이 보존된다.
+ *
+ * @param {object} args
+ * @param {import('./mega-app.js').MegaApp | null} args.app
+ * @param {import('fastify').FastifyRequest} args.req
+ * @param {import('fastify').FastifyReply} args.reply
+ * @returns {Record<string, any>}
+ */
+export function getLazyHttpCtx({ app, req, reply }) {
+  const cached = /** @type {any} */ (req)[LAZY_CTX_KEY]
+  if (cached) return cached
+  /** 첫 트랩에서 실 ctx 를 만들고 이후 재사용 (getHttpCtx 가 req 단위 캐시를 겸한다). */
+  const real = () => getHttpCtx({ app, req, reply })
+  const proxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        return Reflect.get(real(), prop)
+      },
+      set(_t, prop, value) {
+        return Reflect.set(real(), prop, value)
+      },
+      has(_t, prop) {
+        return Reflect.has(real(), prop)
+      },
+      ownKeys() {
+        return Reflect.ownKeys(real())
+      },
+      getOwnPropertyDescriptor(_t, prop) {
+        return Object.getOwnPropertyDescriptor(real(), prop)
+      },
+      defineProperty(_t, prop, desc) {
+        return Reflect.defineProperty(real(), prop, desc)
+      },
+      deleteProperty(_t, prop) {
+        return Reflect.deleteProperty(real(), prop)
+      },
+    },
+  )
+  ;/** @type {any} */ (req)[LAZY_CTX_KEY] = proxy
+  return proxy
+}

package/src/core/envelope.js

@@ -12,6 +12,33 @@
 /** 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 객체에 마킹을 부착한다.
+ *
+ * 심볼 **직접 대입** (G1 M-1, ADR-214) — `Object.defineProperty` 대비 17배 빠르고(136→8 ns/op 실측)
+ * allocation 도 작다. 심볼 키는 어차피 `JSON.stringify`/`Object.keys` 에 안 나오므로 와이어·열거
+ * 동작은 동일하다. 의미 차이는 하나 — spread 복사(`{...env}`)가 마크를 함께 복사한다. 복사본도
+ * "이미 envelope" 로 취급되는데, 이는 이중 wrap 방지(ADR-184)에 오히려 부합한다(복사 후 필드를
+ * 고쳐 재전송하는 패턴도 envelope 그대로 나간다 — 의도된 동작으로 확정, ADR-214).
+ *
+ * @template {Record<string, any>} T
+ * @param {T} env
+ * @returns {T} 같은 객체 (마킹됨).
+ */
+function markEnvelope(env) {
+  ;/** @type {any} */ (env)[ENVELOPE_MARK] = true
+  return env
+}
+
 /**
  * 자동 envelope (ADR-018). preSerialization 훅의 마지막 단계에서 호출되어
  * raw data → `{ ok:true, data, meta }`.
@@ -29,11 +56,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 +71,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 +79,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
@@ -170,7 +189,9 @@ export class MegaHubLink {
   /**
    * hub 연결 + REGISTER 핸드셰이크. register_ok 수신 시 resolve.
    *
-   * `retry` 옵션이 있으면 최초 연결도 지수 백오프로 재시도한다(ADR-098). 없으면 단발 시도.
+   * 초기 연결은 retry 유무와 무관하게 **단 1회** 시도한다. `retry` 옵션이 있으면 실패 시 백그라운드
+   * 재연결(지수 백오프)로 전환하고 reject 한다 — 성공 시 RECONNECTED, 소진 시 RECONNECT_FAILED emit.
+   * 호출부(boot)는 reject 를 warn 으로 받고 부팅을 계속한다(허브 다운이 부팅을 막지 않는 계약).
    *
    * @param {Object} [opts]
    * @param {number} [opts.connectTimeoutMs] - register_ok 대기 한도 override(M4). **이 값은 인스턴스에
@@ -184,21 +205,38 @@ 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 활성 — 초기 연결은 **단 1회**만 시도하고, 실패하면 백그라운드 재연결로 전환한 뒤 throw 한다.
+    // 예전엔 withRetry 가 최초 연결까지 백오프 전체를 await 해 호출부(boot 의 cluster-transport step)가
+    // 분 단위로 블로킹됐다(crud retry 기준 약 4.7분) — "허브 다운이어도 boot 를 막지 않는다" 는 호출부
+    // 계약과 정반대 동작. 이제 호출부는 즉시 실패를 보고(warn) 부팅을 계속하고, 백그라운드 _reconnect 가
+    // 같은 retry 백오프로 재시도한다 — 성공 시 RECONNECTED 이벤트가 presence 재동기화를 트리거하고,
+    // 소진 시 RECONNECT_FAILED 를 emit 한다. 치명 에러(인증 거부 등 fatal)는 재시도 무의미라 그대로 전파.
+    try {
+      return await this._connectOnce({ connectTimeoutMs: timeout })
+    } catch (err) {
+      // 레거시 hub 폴백(1회) — protocolVersion 필드 거부 판정 후 v1 register 로 즉시 재시도.
+      if (err instanceof Error && err.message === 'hub.legacy_register_fallback') {
+        try {
+          return await this._connectOnce({ connectTimeoutMs: timeout })
+        } catch (err2) {
+          if (retryUnlessFatal({ error: err2 })) void this._reconnect()
+          throw err2
+        }
+      }
+      if (retryUnlessFatal({ error: err })) void this._reconnect()
+      throw err
     }
-    // retry 활성 — 최초 연결도 백오프 재시도. AbortError(인증 실패 등) 는 재시도하지 않는다.
-    this._abort = new AbortController()
-    return withRetry(() => this._connectOnce({ connectTimeoutMs: timeout }), {
-      ...this._retry,
-      signal: this._abort.signal,
-      shouldRetry: retryUnlessFatal,
-      onFailedAttempt: (ctx) => {
-        this._log?.warn?.(
-          { bridgeId: this._bridgeId, attempt: ctx.attemptNumber, retriesLeft: ctx.retriesLeft },
-          'hub-link connect attempt failed — backing off',
-        )
-      },
-    })
   }
 
   /**
@@ -246,7 +284,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 +293,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 +322,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 +544,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,12 +9,14 @@ 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'
+export { buildHttpCtx, getHttpCtx, getLazyHttpCtx, buildAdapterAccessors } from './ctx-builder.js'
 // WS envelope + 컨트롤러 베이스 (ADR-015 / ADR-074)
 export {
   createWsMessage,