mega-framework 0.1.0

package/src/core/router.js

@@ -0,0 +1,388 @@
+// @ts-check
+
+/**
+ * Router — 라우트 파일이 사용하는 등록 인터페이스.
+ *
+ * 라우트 파일 형식:
+ *   export default (router) => {
+ *     router.http.get('/api/users', handler, { before: [auth] })
+ *     router.http.post('/api/users', UsersController.create, { schema, after: [logResponse] })
+ *     router.ws('/ws/chat', ChatChannel, { before: [auth] })
+ *   }
+ *
+ * 핸들러는 inline async function 또는 static method reference (ADR-074).
+ * `typeof handler !== 'function'` → 부팅 시 throw (ADR-089).
+ *
+ * 미들웨어 라이프사이클 (ADR-091):
+ *   - before:    preHandler 단계 (인증·rateLimit·검증)
+ *   - transform: preSerialization 이른 단계 (raw data 변환, envelope wrap 전)
+ *   - after:     onResponse 단계 (로깅·메트릭, side-effect만, throw → warn 로그)
+ */
+
+// 명명 import — AJV 8 은 ESM/TS 정합을 위해 `Ajv` named export 를 제공한다(default 는 TS 에서
+// construct 불가로 잡힘). `ValidateFunction` 등 타입도 같은 모듈에서 가져온다.
+import { Ajv } from 'ajv'
+import { MegaError } from '../errors/mega-error.js'
+import { MegaWebSocketController } from './ws-controller.js'
+import { getHttpCtx } from './ctx-builder.js'
+
+const HTTP_METHODS = Object.freeze(['get', 'post', 'put', 'patch', 'delete', 'head', 'options'])
+
+/**
+ * WS payload 스키마 검증용 공유 AJV 인스턴스 (M2, ADR-096).
+ * `allErrors: true` — 위반을 모두 모아 envelope details 배열(ADR-075)로 돌려준다.
+ * HTTP 검증(Fastify 네이티브 AJV)과 별개 인스턴스다 — WS 는 Fastify route 가 아니라
+ * 우리 dispatch 경로에서 payload 만 검증하므로 직접 컴파일·실행한다.
+ */
+const wsAjv = new Ajv({ allErrors: true })
+
+/**
+ * `router.ws({ schemas })` 의 type 별 JSON Schema 를 **등록(부팅) 시점에 사전 컴파일**한다
+ * (ADR-089 fail-fast). 형식 위반·컴파일 실패는 즉시 throw 해 잘못된 스키마로 부팅되지 않게 한다.
+ *
+ * @param {unknown} schemas - `{ [messageType: string]: JSONSchema }` 또는 undefined.
+ * @param {string} path - 에러 메시지용 WS 경로.
+ * @returns {Record<string, import('ajv').ValidateFunction> | null}
+ *   컴파일된 검증 함수 맵. schemas 미지정 시 null (검증 없음).
+ * @throws {MegaRouteError} schemas 가 object 아님 / 항목이 schema object 아님 / 컴파일 실패.
+ */
+function compileWsSchemas(schemas, path) {
+  if (schemas === undefined) return null
+  if (schemas === null || typeof schemas !== 'object' || Array.isArray(schemas)) {
+    throw new MegaRouteError(
+      'route.ws_invalid_schemas',
+      `router.ws('${path}'): 'schemas' must be an object mapping message type → JSON Schema. ` +
+        `Got: ${Array.isArray(schemas) ? 'array' : schemas === null ? 'null' : typeof schemas}.`,
+    )
+  }
+  /** @type {Record<string, import('ajv').ValidateFunction>} */
+  const validators = {}
+  for (const [type, schema] of Object.entries(schemas)) {
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+      throw new MegaRouteError(
+        'route.ws_invalid_schema_entry',
+        `router.ws('${path}'): schemas['${type}'] must be a JSON Schema object. ` +
+          `Got: ${Array.isArray(schema) ? 'array' : schema === null ? 'null' : typeof schema}.`,
+      )
+    }
+    try {
+      validators[type] = wsAjv.compile(schema)
+    } catch (err) {
+      // AJV 컴파일 실패 = 잘못된 스키마 정의. 부팅 시 fail-fast (우회 금지, 원인 보존).
+      throw new MegaRouteError(
+        'route.ws_schema_compile_failed',
+        `router.ws('${path}'): failed to compile JSON Schema for type '${type}': ` +
+          `${err instanceof Error ? err.message : String(err)}`,
+        { cause: err },
+      )
+    }
+  }
+  return validators
+}
+
+/**
+ * 라우트 등록 옵션 (router.http.*(path, handler, opts) / router.ws(path, Channel, opts)).
+ * @typedef {object} HttpRouteOpts
+ * @property {Function[]} [before] - preHandler 단계 미들웨어 (인증·rateLimit·검증).
+ * @property {Function[]} [transform] - preSerialization 이른 단계 변환 (HTTP 전용).
+ * @property {Function[]} [after] - onResponse 단계 side-effect (HTTP 전용).
+ * @property {Object} [schema] - Fastify schema (ADR-019).
+ * @property {{ tags?: string[], summary?: string, description?: string, deprecated?: boolean }} [openapi] -
+ *   OpenAPI 라우트 메타 (ADR-070/140). 라우트 schema 의 비검증 메타 필드로 병합돼 명세에 반영(openapi 옵트인 시).
+ */
+
+/** 라우트 등록 시 잘못된 형식 시 throw. */
+export class MegaRouteError extends MegaError {
+  // code = 'route.<reason>'
+}
+
+/**
+ * Router 인스턴스 — MegaApp 부팅 시 각 라우트 파일마다 생성·전달.
+ *
+ * HTTP 핸들러 등록 + before/transform/after 미들웨어 wiring.
+ * WS 는 hub 통합 시 등록 시그니처만 보존, 실제 핸들러는 inline /
+ * Static method ref 패턴 지원.
+ */
+export class Router {
+  /**
+   * @param {Object} ctx
+   * @param {import('fastify').FastifyInstance} ctx.fastify - 등록 대상 Fastify
+   * @param {string} ctx.appName - 디버그·에러 메시지용 앱 이름
+   * @param {string} [ctx.sourceFile] - 라우트 파일 경로 (에러 메시지용)
+   * @param {import('./mega-app.js').MegaApp} [ctx.app] - 바인딩 앱. HTTP 핸들러 ctx 의 `db/cache/bus`
+   *   접근자(ADR-102) 출처. 미지정(standalone Router)이면 ctx 에 어댑터 접근자가 빠진다.
+   */
+  constructor(ctx) {
+    if (!ctx?.fastify) throw new MegaRouteError('route.invalid_ctx', 'Router: fastify is required')
+    this._fastify = ctx.fastify
+    this._appName = ctx.appName
+    this._sourceFile = ctx.sourceFile
+    /** @type {import('./mega-app.js').MegaApp | null} */
+    this._app = ctx.app ?? null
+    this.http = this._buildHttpProxy()
+  }
+
+  /**
+   * 바인딩된 MegaApp (standalone Router 면 null).
+   *
+   * 라우트 모듈(`export default (router) => {}`)이 앱 표면에 닿는 통로다 — 특히 WS `before(req)`
+   * upgrade 인증은 Fastify 밖이라 `req.session` 이 없어, `router.app.sessionStore` 로 세션 스토어를
+   * 얻어 {@link import('./session.js').readSession} 으로 신원을 확인한다(ADR-159).
+   *
+   * @returns {import('./mega-app.js').MegaApp | null}
+   */
+  get app() {
+    return this._app
+  }
+
+  /**
+   * HTTP 프록시: router.http.get(...), router.http.post(...) 등 7개 메서드.
+   * @private
+   */
+  _buildHttpProxy() {
+    /** @type {Record<string, (path: string, handler: Function, opts?: HttpRouteOpts) => void>} */
+    const proxy = {}
+    for (const method of HTTP_METHODS) {
+      proxy[method] = (path, handler, opts = {}) => this._registerHttp(method, path, handler, opts)
+    }
+    return Object.freeze(proxy)
+  }
+
+  /**
+   * 실제 HTTP 라우트 등록 — Fastify route() + before/transform/after wiring.
+   * @param {string} method - HTTP 메서드 (소문자).
+   * @param {string} path - 라우트 경로.
+   * @param {Function} handler - 핸들러 (inline async fn 또는 static method ref).
+   * @param {HttpRouteOpts} opts
+   * @private
+   */
+  _registerHttp(method, path, handler, opts) {
+    if (typeof path !== 'string' || path.length === 0) {
+      throw new MegaRouteError(
+        'route.invalid_path',
+        `router.http.${method}: path must be a non-empty string. Got: ${typeof path}`,
+      )
+    }
+    if (typeof handler !== 'function') {
+      throw new MegaRouteError(
+        'route.invalid_handler',
+        `router.http.${method}('${path}'): handler must be a function ` +
+          `(inline async fn or static method reference like UsersController.index). ` +
+          `Got: ${typeof handler}.`,
+      )
+    }
+
+    const before = this._validateMiddlewareArray(opts.before, 'before', method, path)
+    const transform = this._validateMiddlewareArray(opts.transform, 'transform', method, path)
+    const after = this._validateMiddlewareArray(opts.after, 'after', method, path)
+
+    // 동적으로 schema/preHandler/preSerialization/onResponse 를 덧붙이므로 permissive 타입.
+    /** @type {Record<string, any>} */
+    const routeOpts = {
+      method: method.toUpperCase(),
+      url: path,
+      handler: async (
+        /** @type {import('fastify').FastifyRequest} */ req,
+        /** @type {import('fastify').FastifyReply} */ reply,
+      ) => {
+        // canonical 핸들러 시그니처 (req, res, ctx) (ADR-074, docs/03 §581). ctx 는 요청 단위로 만들어
+        // app/log/requestId/req/reply + db/cache/bus 접근자(ADR-102)를 노출. 기존 (req, reply) 핸들러는
+        // 3번째 인자를 무시하므로 하위 호환. getHttpCtx 는 요청당 1회 캐싱이라 글로벌 미들웨어가 먼저
+        // 만든 ctx 를 그대로 이어받는다(ADR-134 — 미들웨어→핸들러 ctx 공유).
+        const ctx = getHttpCtx({ app: this._app, req, reply })
+        return handler(req, reply, ctx)
+      },
+    }
+
+    // schema (ADR-019) 그대로 Fastify 에 전달
+    if (opts.schema) routeOpts.schema = opts.schema
+
+    // OpenAPI 메타(ADR-070/140) — 라우트 옵션 openapi:{tags,summary,description,deprecated} 를 Fastify
+    // 라우트 schema 의 비검증 메타 필드로 병합한다(@fastify/swagger 가 schema 에서 수집). 검증 필드(body 등)는
+    // 그대로 두고 메타만 얹으므로 검증 동작에 영향 없음. openapi 옵트인 미등록이어도 무해(수집기가 없을 뿐).
+    if (opts.openapi && typeof opts.openapi === 'object') {
+      const meta = /** @type {Record<string, any>} */ (opts.openapi)
+      routeOpts.schema = { ...(routeOpts.schema || {}) }
+      if (Array.isArray(meta.tags)) routeOpts.schema.tags = meta.tags
+      if (typeof meta.summary === 'string') routeOpts.schema.summary = meta.summary
+      if (typeof meta.description === 'string') routeOpts.schema.description = meta.description
+      if (meta.deprecated === true) routeOpts.schema.deprecated = true
+    }
+
+    // before — Fastify preHandler 체인. 각 미들웨어를 arity-2 async 래퍼로 감싼다.
+    //
+    // 왜 래핑하나: Fastify 는 async preHandler 의 arity 가 3 이상이면 3번째 인자를 콜백 `done` 으로
+    // 오해해 "Async function has too many arguments" 로 **등록을 거부**한다. 그런데 인증 가드
+    // `requireAuth`/`requireRole`(ADR-143)은 시그니처가 `(req, reply, ctx)` 로 arity 3 다 — 글로벌
+    // 미들웨어 경로(ADR-134)에서 ctx 를 받기 위함. 라우트 `before` 는 ctx 를 주입하지 않으므로(=undefined,
+    // 가드는 req.session 으로 동작) arity-2 래퍼 `(req, reply)` 로 감싸면 Fastify 계약에 맞으면서 ADR-143 이
+    // 문서화한 `{ before: [requireAuth] }` 가 실제로 동작한다. 래퍼는 각각 독립 preHandler 라 순서·reply
+    // 단락(앞 미들웨어가 응답 전송 시 이후 미들웨어·핸들러 skip) 의미는 그대로다(ADR-156).
+    if (before.length > 0) {
+      routeOpts.preHandler = before.map(
+        (fn) =>
+          /** @param {import('fastify').FastifyRequest} req @param {import('fastify').FastifyReply} reply */
+          async (req, reply) => fn(req, reply),
+      )
+    }
+
+    // transform — preSerialization 이른 단계. Fastify preSerialization 훅의 payload 를 변환.
+    if (transform.length > 0) {
+      routeOpts.preSerialization = async (
+        /** @type {import('fastify').FastifyRequest} */ req,
+        /** @type {import('fastify').FastifyReply} */ reply,
+        /** @type {any} */ payload,
+      ) => {
+        let current = payload
+        for (const fn of transform) {
+          current = await fn(req, reply, current)
+        }
+        return current
+      }
+    }
+
+    // after — onResponse 단계 (응답 전송 후). throw 시 warn 로그 + 응답 영향 없음 (ADR-091).
+    if (after.length > 0) {
+      routeOpts.onResponse = async (
+        /** @type {import('fastify').FastifyRequest} */ req,
+        /** @type {import('fastify').FastifyReply} */ reply,
+      ) => {
+        for (const fn of after) {
+          try {
+            await fn(req, reply)
+          } catch (err) {
+            // ADR-091: silent fallback 금지 — warn 로그.
+            const log = req.log ?? console
+            log.warn?.({ err, hook: 'after', method, path }, `after middleware threw — ignored (response already sent)`)
+          }
+        }
+      }
+    }
+
+    // routeOpts 는 동적 조립(method 대문자화·옵션 키 추가)이라 RouteOptions 로 캐스팅해 전달.
+    this._fastify.route(/** @type {import('fastify').RouteOptions} */ (routeOpts))
+  }
+
+  /**
+   * WebSocket 라우트 등록 (실 upgrade wiring).
+   *
+   * `ChannelClass` 가 {@link MegaWebSocketController} 를 상속하는지 **부팅 시 검증** (ADR-089 fail-fast).
+   * 등록된 라우트는 `fastify._megaWsRoutes` 에 보관되고, MegaApp 이 listen 시점에 HTTP `'upgrade'`
+   * 이벤트에 연결한다 (core/ws-upgrade.js).
+   *
+   * WS 는 `before`(upgrade 인증) 만 지원한다 — `transform`/`after` 는 HTTP 전용 (ADR-074/091).
+   *
+   * `schemas` 는 **메시지 type 별 payload JSON Schema** 맵이다 (`{ [type]: jsonSchema }`, M2).
+   * 등록 시점에 AJV 로 사전 컴파일되며, 수신 메시지의 `type` 에 해당 스키마가 있으면 dispatch
+   * 직전에 `payload` 를 검증한다. 실패 시 `ws.invalid_payload` error envelope 응답(연결 유지) —
+   * HTTP AJV 매핑(ADR-090)과 동일한 fail-closed 정책. 스키마 없는 type 은 그대로 통과.
+   *
+   * @param {string} path - WS 경로 (= ASP namespace, 예: '/ws/chat').
+   * @param {Function} ChannelClass - MegaWebSocketController 를 상속한 채널 클래스.
+   * @param {{ before?: Function[], schemas?: Object, transform?: unknown, after?: unknown }} [opts]
+   *   - schemas: `{ [messageType]: JSONSchema }` — type 별 payload 스키마 (AJV 사전 컴파일됨).
+   * @throws {MegaRouteError} path/ChannelClass 형식 위반, 상속 위반, 또는 schemas 형식·컴파일 실패.
+   */
+  ws(path, ChannelClass, opts = {}) {
+    if (typeof path !== 'string' || path.length === 0) {
+      throw new MegaRouteError(
+        'route.invalid_path',
+        `router.ws: path must be a non-empty string. Got: ${typeof path}`,
+      )
+    }
+    if (typeof ChannelClass !== 'function') {
+      throw new MegaRouteError(
+        'route.ws_channel_class_required',
+        `router.ws('${path}'): ChannelClass must be a class extending MegaWebSocketController. ` +
+          `Got: ${typeof ChannelClass}.`,
+      )
+    }
+    // 상속 검증 (ADR-089 fail-fast) — dispatch/_bind/라이프사이클 훅이 보장돼야 upgrade 가 동작.
+    if (
+      ChannelClass !== MegaWebSocketController &&
+      !(ChannelClass.prototype instanceof MegaWebSocketController)
+    ) {
+      throw new MegaRouteError(
+        'route.ws_channel_not_controller',
+        `router.ws('${path}'): ChannelClass must extend MegaWebSocketController ` +
+          `(import { MegaWebSocketController } from 'mega-framework'). Got: ${ChannelClass.name || 'anonymous'}.`,
+      )
+    }
+    // before 만 WS 에 의미 있음 (upgrade 인증). transform/after 는 HTTP 전용.
+    this._validateMiddlewareArray(opts.before, 'before', 'ws', path)
+    if (opts.transform !== undefined) {
+      throw new MegaRouteError(
+        'route.ws_no_transform',
+        `router.ws('${path}'): 'transform' is HTTP-only. WS messages dispatch by type inside the channel (ADR-074).`,
+      )
+    }
+    if (opts.after !== undefined) {
+      throw new MegaRouteError(
+        'route.ws_no_after',
+        `router.ws('${path}'): 'after' is HTTP-only. WS messages dispatch by type inside the channel (ADR-074).`,
+      )
+    }
+
+    // schemas (M2) — type 별 payload JSON Schema 사전 컴파일. 형식·컴파일 실패는 여기서 throw.
+    const schemaValidators = compileWsSchemas(opts.schemas, path)
+
+    // ns = path (코어 단위는 namespace=채널, ADR-034). MegaApp 이 ASP 활성 여부 판단에 사용.
+    // _megaWsRoutes 는 Fastify 타입에 없는 우리 전용 보관소 — 부착 시 cast.
+    const fastifyWithWs =
+      /** @type {import('fastify').FastifyInstance & { _megaWsRoutes?: Array<{ path: string, ns: string, ChannelClass: Function, opts: Object, schemaValidators: Record<string, import('ajv').ValidateFunction> | null }> }} */ (
+        this._fastify
+      )
+    if (!fastifyWithWs._megaWsRoutes) fastifyWithWs._megaWsRoutes = []
+    const existing = fastifyWithWs._megaWsRoutes.find((r) => r.path === path)
+    if (existing) {
+      throw new MegaRouteError(
+        'route.ws_duplicate_path',
+        `router.ws('${path}'): a WS route is already registered for this path.`,
+      )
+    }
+    fastifyWithWs._megaWsRoutes.push({ path, ns: path, ChannelClass, opts, schemaValidators })
+  }
+
+  /**
+   * 파일 전체 적용 미들웨어 (router.use). fastify.addHook 으로 등록.
+   * 실행 순서: 전역 → 앱 → 파일(router.use) → 라우트(before opts) → handler.
+   * @param {Function} middleware
+   */
+  use(middleware) {
+    if (typeof middleware !== 'function') {
+      throw new MegaRouteError(
+        'route.invalid_use',
+        `router.use: middleware must be a function. Got: ${typeof middleware}.`,
+      )
+    }
+    // 사용자 제공 범용 미들웨어 — Fastify preHandler 훅 시그니처로 캐스팅.
+    this._fastify.addHook('preHandler', /** @type {any} */ (middleware))
+  }
+
+  /**
+   * @param {unknown} arr - 검증 대상 (Function[] 기대).
+   * @param {string} name - 옵션 이름 (before/transform/after).
+   * @param {string} method - HTTP 메서드 또는 'ws'.
+   * @param {string} path - 라우트 경로.
+   * @returns {Function[]}
+   * @private
+   */
+  _validateMiddlewareArray(arr, name, method, path) {
+    if (arr === undefined) return []
+    if (!Array.isArray(arr)) {
+      throw new MegaRouteError(
+        `route.invalid_${name}`,
+        `router.${method === 'ws' ? 'ws' : `http.${method}`}('${path}'): '${name}' must be an array of functions. Got: ${typeof arr}.`,
+      )
+    }
+    arr.forEach((fn, i) => {
+      if (typeof fn !== 'function') {
+        throw new MegaRouteError(
+          `route.invalid_${name}_item`,
+          `router.${method === 'ws' ? 'ws' : `http.${method}`}('${path}'): '${name}[${i}]' must be a function. Got: ${typeof fn}.`,
+        )
+      }
+    })
+    return arr
+  }
+}

package/src/core/routes-loader.js

@@ -0,0 +1,57 @@
+// @ts-check
+import { readdirSync, statSync } from 'node:fs'
+import { join, resolve as pathResolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Router, MegaRouteError } from './router.js'
+
+/**
+ * 앱의 routes/ 폴더 전체 스캔 → 각 파일을 Router 와 함께 실행.
+ *
+ * @param {Object} opts
+ * @param {import('fastify').FastifyInstance} opts.fastify
+ * @param {string} opts.appName
+ * @param {string} opts.routesDir - apps/<name>/routes 절대 경로
+ * @param {import('./mega-app.js').MegaApp} [opts.app] - 바인딩 앱 (HTTP ctx 의 db/cache/bus 접근자 출처, ADR-102)
+ * @returns {Promise<{ filesLoaded: number, routes: Array<{file: string}> }>}
+ */
+export async function loadRoutes({ fastify, appName, routesDir, app }) {
+  const loaded = []
+  let routeFiles
+  try {
+    routeFiles = readdirSync(routesDir)
+      .filter((f) => f.endsWith('.js') && !f.endsWith('.test.js'))
+      .sort()
+  } catch (err) {
+    if (err.code === 'ENOENT') return { filesLoaded: 0, routes: [] }
+    throw err
+  }
+
+  for (const fileName of routeFiles) {
+    const absPath = pathResolve(join(routesDir, fileName))
+    const st = statSync(absPath)
+    if (!st.isFile()) continue
+
+    let mod
+    try {
+      mod = await import(pathToFileURL(absPath).href)
+    } catch (err) {
+      throw new MegaRouteError(
+        'route.file_load_failed',
+        `Failed to load route file '${appName}/routes/${fileName}': ${err.message}`,
+        { cause: err },
+      )
+    }
+    if (typeof mod.default !== 'function') {
+      throw new MegaRouteError(
+        'route.file_no_default',
+        `Route file '${appName}/routes/${fileName}' must export default a function (router) => { ... }.`,
+      )
+    }
+
+    const router = new Router({ fastify, appName, sourceFile: fileName, app })
+    await mod.default(router)
+    loaded.push({ file: fileName })
+  }
+
+  return { filesLoaded: loaded.length, routes: loaded }
+}

package/src/core/scope-registry.js

@@ -0,0 +1,53 @@
+// @ts-check
+/**
+ * mega.config.js (Global) / apps/<name>/app.config.js (App + Shared-Reference) 의
+ * 키 분리 규약 (ADR-061). 알 수 없는 키 + 잘못된 스코프 → 부팅 throw.
+ *
+ * @module core/scope-registry
+ */
+
+/** mega.config.js 최상위에만 허용되는 키 */
+export const GLOBAL_ONLY_KEYS = Object.freeze([
+  'services', // databases/caches/buses 그룹 정의
+  'server', // port, cluster, sessionSecret
+  'wsHub', // mega ws-hub 명령용 (ADR-068)
+  'logger', // 전역 로거 sinks
+  'apps', // 활성 앱 whitelist (ADR-066)
+  'asp', // masterSecret 등 시크릿
+  'health', // /health, /health/ready
+  'tracing', // OpenTelemetry (ADR-077)
+  'plugins', // 명시 등록 배열 (ADR-079)
+  'jobs', // MegaJob 서브클래스 배열 — mega worker 가 소비 (ADR-123)
+  'schedules', // MegaSchedule 서브클래스 배열 — mega scheduler 가 소비 (ADR-123)
+  'workers', // MegaWorker 서브클래스 배열 — CPU 워커 풀, ctx.workers.<name> 배선 (ADR-124)
+])
+
+/** apps/<name>/app.config.js 에만 허용되는 키 */
+export const APP_ONLY_KEYS = Object.freeze([
+  'name', // 폴더명 일치
+  'hosts', // 도메인 매핑
+  'cors', // 앱별 Fastify 인스턴스에만 적용
+  'helmet',
+  'rateLimit',
+  'csrf',
+  'session', // 앱별 세션 옵트인 (store/cookie/ttl/csrf 모드, ADR-129/046)
+  'bodyLimits',
+  'upload',
+  'i18n', // 앱별 locale 선호
+  'views', // 앱별 뷰 옵션
+  'asp', // 앱별 ASP 옵트인 (Global asp.masterSecret 과 별개)
+  'bridgeHub', // 어느 hub 에 연결 (ADR-065)
+  'openapi', // App-only (ADR-070)
+  'staticAssets', // App-only (ADR-071)
+  'websocket', // 앱별 WS 옵션 (compression 등)
+  // Shared-Reference 키 (전역에 정의된 키 참조만 — ADR-061)
+  'databases',
+  'caches',
+  'buses',
+])
+
+/** Shared-Reference 키 — 전역 services 의 키만 참조 가능 */
+export const SHARED_REFERENCE_KEYS = Object.freeze(['databases', 'caches', 'buses'])
+
+export const ALL_GLOBAL_KEYS = Object.freeze(GLOBAL_ONLY_KEYS)
+export const ALL_APP_KEYS = Object.freeze(APP_ONLY_KEYS)