@gravito/core 1.6.0 → 2.0.0

package/dist/ffi/index.js.map

@@ -0,0 +1,14 @@
+{
+  "version": 3,
+  "sources": ["../src/ffi/types.ts", "../src/ffi/cbor-fallback.ts", "../src/ffi/hash-fallback.ts", "../src/ffi/NativeAccelerator.ts", "../src/ffi/NativeHasher.ts"],
+  "sourcesContent": [
+    "/**\n * FFI (Foreign Function Interface) 類型定義\n * 支持 bun:ffi 的原生加速層\n */\n\n/**\n * CBOR 編碼/解碼加速器介面\n * 可由原生 C 實現或 JavaScript 回退實現\n */\nexport interface CborAccelerator {\n  /**\n   * 將任意 JavaScript 物件編碼為 CBOR 二進制格式\n   * @param data - 要編碼的物件（支援：map、string、uint、float64、bytes、null、boolean）\n   * @returns CBOR 編碼的二進制資料\n   */\n  encode(data: Record<string, unknown>): Uint8Array\n\n  /**\n   * 將 CBOR 二進制格式解碼為 JavaScript 物件\n   * @param bytes - CBOR 編碼的二進制資料\n   * @returns 解碼後的物件\n   */\n  decode(bytes: Uint8Array): Record<string, unknown>\n}\n\n/**\n * FFI 加速層狀態報告\n */\nexport interface NativeAcceleratorStatus {\n  /**\n   * 原生 FFI 加速是否可用\n   */\n  readonly available: boolean\n\n  /**\n   * 當前使用的運行時實現\n   * - 'bun-ffi': Bun C 編譯器（bun:ffi 的 cc()）\n   * - 'js-fallback': 手寫 JavaScript CBOR 實現\n   * - 'cborg': npm 的 cborg 套件（已棄用，僅用於向後相容）\n   */\n  readonly runtime: 'bun-ffi' | 'js-fallback' | 'cborg'\n\n  /**\n   * 運行時版本或詳細資訊\n   */\n  readonly version: string\n}\n\n/**\n * FFI 層配置選項\n */\nexport interface FfiConfig {\n  /**\n   * 啟用調試日誌\n   * @default false\n   */\n  readonly debug?: boolean\n\n  /**\n   * 最大 buffer 大小（位元組）\n   * @default 1048576 (1MB)\n   */\n  readonly maxBufferSize?: number\n\n  /**\n   * 強制使用特定的加速器實現\n   * - undefined: 自動選擇（優先 bun-ffi，降級到 js-fallback）\n   * - 'bun-ffi': 只使用原生 C 實現\n   * - 'js-fallback': 只使用 JavaScript 實現\n   */\n  readonly forceImplementation?: 'bun-ffi' | 'js-fallback'\n}\n\n/**\n * CBOR Major Type 常數\n * 符合 RFC 7049 規範\n */\nexport const CBOR_MAJOR_TYPES = {\n  UINT: 0, // 正整數 (0 to 2^64-1)\n  NEGINT: 1, // 負整數 (-1 to -2^64)\n  BYTES: 2, // 位元組字串\n  TEXT: 3, // 文字字串\n  ARRAY: 4, // 陣列\n  MAP: 5, // Map 物件\n  TAG: 6, // 語意 tag\n  SIMPLE: 7, // 簡單值與浮點數\n} as const\n\n/**\n * CBOR 簡單值常數\n */\nexport const CBOR_SIMPLE_VALUES = {\n  FALSE: 20, // Boolean false\n  TRUE: 21, // Boolean true\n  NULL: 22, // null\n  UNDEFINED: 23, // undefined (不常用)\n} as const\n\n/**\n * CBOR 長度編碼的附加資訊\n */\nexport const CBOR_LENGTH_ENCODING = {\n  SMALL_RANGE_END: 23, // 0-23: 直接作為值\n  UINT8: 24, // 24: 接下來 1 byte 為 uint8_t\n  UINT16: 25, // 25: 接下來 2 bytes 為 uint16_t (大端序)\n  UINT32: 26, // 26: 接下來 4 bytes 為 uint32_t (大端序)\n  UINT64: 27, // 27: 接下來 8 bytes 為 uint64_t (大端序)\n  FLOAT16: 25, // 25: IEEE 754 半精度浮點數 (special case for SIMPLE)\n  FLOAT32: 26, // 26: IEEE 754 單精度浮點數\n  FLOAT64: 27, // 27: IEEE 754 雙精度浮點數\n  INDEFINITE: 31, // 31: 無限長度編碼\n} as const\n\n/**\n * 雜湊加速器介面\n * 可由 Bun 原生實現或 Node.js 回退實現\n */\nexport interface HashAccelerator {\n  /**\n   * SHA-256 雜湊計算\n   * @param input - 輸入（字串或二進制）\n   * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）\n   */\n  sha256(input: string | Uint8Array): string\n\n  /**\n   * HMAC-SHA256 計算\n   * @param key - 密鑰\n   * @param data - 要雜湊的數據\n   * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）\n   */\n  hmacSha256(key: string, data: string): string\n}\n\n/**\n * 雜湊加速器狀態報告\n */\nexport interface NativeHasherStatus {\n  /**\n   * 雜湊加速層是否可用\n   */\n  readonly available: boolean\n\n  /**\n   * 當前使用的運行時實現\n   * - 'bun-crypto-hasher': Bun 原生 CryptoHasher（C 實現，推薦）\n   * - 'node-crypto': node:crypto 回退實現\n   */\n  readonly runtime: 'bun-crypto-hasher' | 'node-crypto'\n}\n",
+    "/**\n * JavaScript CBOR 回退實現\n * 用於非 Bun 環境或 FFI 不可用的情況\n * 符合 RFC 7049 規範\n */\n\nimport type { CborAccelerator } from './types'\nimport { CBOR_LENGTH_ENCODING, CBOR_MAJOR_TYPES, CBOR_SIMPLE_VALUES } from './types'\n\n/**\n * CBOR 編碼器\n * 將 JavaScript 物件編碼為 CBOR 二進制格式\n */\nexport class CborFallbackEncoder implements CborAccelerator {\n  private static readonly DEFAULT_BUFFER_SIZE = 4096\n  private static readonly MAX_DEPTH = 16\n  private static readonly MAX_BUFFER_SIZE = 1024 * 1024 // 1MB\n\n  private buffer: Uint8Array\n  private offset: number\n\n  constructor() {\n    this.buffer = new Uint8Array(CborFallbackEncoder.DEFAULT_BUFFER_SIZE)\n    this.offset = 0\n  }\n\n  /**\n   * 編碼 JavaScript 物件為 CBOR 格式\n   */\n  encode(data: Record<string, unknown>): Uint8Array {\n    this.buffer = new Uint8Array(CborFallbackEncoder.DEFAULT_BUFFER_SIZE)\n    this.offset = 0\n    this.encodeValue(data, 0)\n    return this.buffer.slice(0, this.offset)\n  }\n\n  /**\n   * 解碼 CBOR 二進制為 JavaScript 物件\n   */\n  decode(bytes: Uint8Array): Record<string, unknown> {\n    const decoder = new CborFallbackDecoder(bytes)\n    const value = decoder.decode()\n    if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n      throw new Error('CBOR 根值必須是物件')\n    }\n    return value as Record<string, unknown>\n  }\n\n  /**\n   * 確保 buffer 有足夠空間\n   */\n  private ensureCapacity(required: number): void {\n    let newCapacity = this.buffer.length\n    while (this.offset + required > newCapacity) {\n      newCapacity *= 2\n      if (newCapacity > CborFallbackEncoder.MAX_BUFFER_SIZE) {\n        throw new Error(\n          `CBOR 編碼超過最大 buffer 大小 ${CborFallbackEncoder.MAX_BUFFER_SIZE} 位元組`\n        )\n      }\n    }\n    if (newCapacity !== this.buffer.length) {\n      const newBuffer = new Uint8Array(newCapacity)\n      newBuffer.set(this.buffer)\n      this.buffer = newBuffer\n    }\n  }\n\n  /**\n   * 編寫一個位元組\n   */\n  private writeByte(byte: number): void {\n    this.ensureCapacity(1)\n    this.buffer[this.offset++] = byte & 0xff\n  }\n\n  /**\n   * 編寫多個位元組\n   */\n  private writeBytes(bytes: ArrayLike<number>): void {\n    this.ensureCapacity(bytes.length)\n    this.buffer.set(bytes, this.offset)\n    this.offset += bytes.length\n  }\n\n  /**\n   * 編寫 CBOR 長度（Major Type + Additional Info）\n   */\n  private writeLength(majorType: number, length: number): void {\n    const type = majorType << 5\n\n    if (length < 24) {\n      this.writeByte(type | length)\n    } else if (length <= 0xff) {\n      this.writeByte(type | CBOR_LENGTH_ENCODING.UINT8)\n      this.writeByte(length)\n    } else if (length <= 0xffff) {\n      this.writeByte(type | CBOR_LENGTH_ENCODING.UINT16)\n      this.writeByte((length >> 8) & 0xff)\n      this.writeByte(length & 0xff)\n    } else if (length <= 0xffffffff) {\n      this.writeByte(type | CBOR_LENGTH_ENCODING.UINT32)\n      this.writeByte((length >> 24) & 0xff)\n      this.writeByte((length >> 16) & 0xff)\n      this.writeByte((length >> 8) & 0xff)\n      this.writeByte(length & 0xff)\n    } else {\n      throw new Error(`CBOR 不支援 > 2^32 的長度: ${length}`)\n    }\n  }\n\n  /**\n   * 遞迴編碼值\n   */\n  private encodeValue(value: unknown, depth: number): void {\n    if (depth > CborFallbackEncoder.MAX_DEPTH) {\n      throw new Error(`CBOR 編碼深度超過限制 ${CborFallbackEncoder.MAX_DEPTH}`)\n    }\n\n    if (value === null) {\n      this.writeByte((CBOR_MAJOR_TYPES.SIMPLE << 5) | CBOR_SIMPLE_VALUES.NULL)\n    } else if (value === true) {\n      this.writeByte((CBOR_MAJOR_TYPES.SIMPLE << 5) | CBOR_SIMPLE_VALUES.TRUE)\n    } else if (value === false) {\n      this.writeByte((CBOR_MAJOR_TYPES.SIMPLE << 5) | CBOR_SIMPLE_VALUES.FALSE)\n    } else if (typeof value === 'number') {\n      this.encodeNumber(value)\n    } else if (typeof value === 'string') {\n      this.encodeString(value)\n    } else if (value instanceof Uint8Array) {\n      this.encodeBytes(value)\n    } else if (Array.isArray(value)) {\n      this.encodeArray(value, depth)\n    } else if (typeof value === 'object') {\n      this.encodeMap(value as Record<string, unknown>, depth)\n    } else {\n      throw new Error(`CBOR 不支援類型: ${typeof value}`)\n    }\n  }\n\n  /**\n   * 編碼整數或浮點數\n   * 對於超過 uint32 範圍的整數，使用 float64 編碼（JavaScript 精度限制）\n   */\n  private encodeNumber(num: number): void {\n    // 檢查是否為整數且在 uint32/negint32 範圍內\n    if (Number.isInteger(num) && !Object.is(num, -0)) {\n      if (num >= 0 && num <= 0xffffffff) {\n        this.writeLength(CBOR_MAJOR_TYPES.UINT, num)\n        return\n      }\n      if (num < 0 && -1 - num <= 0xffffffff) {\n        this.writeLength(CBOR_MAJOR_TYPES.NEGINT, -1 - num)\n        return\n      }\n      // 超過 32-bit 範圍的整數，降級為 float64\n    }\n    {\n      // 浮點數（float64）\n      const bytes = new Uint8Array(9)\n      bytes[0] = (CBOR_MAJOR_TYPES.SIMPLE << 5) | CBOR_LENGTH_ENCODING.FLOAT64\n\n      // IEEE 754 雙精度大端序\n      const view = new DataView(new ArrayBuffer(8))\n      view.setFloat64(0, num, false)\n      for (let i = 0; i < 8; i++) {\n        bytes[i + 1] = view.getUint8(i)\n      }\n      this.writeBytes(bytes)\n    }\n  }\n\n  /**\n   * 編碼字串\n   */\n  private encodeString(str: string): void {\n    const encoder = new TextEncoder()\n    const bytes = encoder.encode(str)\n    this.writeLength(CBOR_MAJOR_TYPES.TEXT, bytes.length)\n    this.writeBytes(bytes)\n  }\n\n  /**\n   * 編碼位元組陣列\n   */\n  private encodeBytes(bytes: Uint8Array): void {\n    this.writeLength(CBOR_MAJOR_TYPES.BYTES, bytes.length)\n    this.writeBytes(bytes)\n  }\n\n  /**\n   * 編碼陣列\n   */\n  private encodeArray(arr: unknown[], depth: number): void {\n    this.writeLength(CBOR_MAJOR_TYPES.ARRAY, arr.length)\n    for (const item of arr) {\n      this.encodeValue(item, depth + 1)\n    }\n  }\n\n  /**\n   * 編碼物件（Map）\n   */\n  private encodeMap(obj: Record<string, unknown>, depth: number): void {\n    const keys = Object.keys(obj)\n    this.writeLength(CBOR_MAJOR_TYPES.MAP, keys.length)\n    for (const key of keys) {\n      this.encodeString(key)\n      this.encodeValue(obj[key], depth + 1)\n    }\n  }\n}\n\n/**\n * CBOR 解碼器\n */\nexport class CborFallbackDecoder {\n  private static readonly MAX_DEPTH = 16\n  private data: Uint8Array\n  private offset: number\n\n  constructor(data: Uint8Array) {\n    this.data = data\n    this.offset = 0\n  }\n\n  /**\n   * 解碼 CBOR 資料\n   */\n  decode(): unknown {\n    return this.decodeValue(0)\n  }\n\n  /**\n   * 讀取一個位元組\n   */\n  private readByte(): number {\n    if (this.offset >= this.data.length) {\n      throw new Error('CBOR 資料不足')\n    }\n    return this.data[this.offset++]\n  }\n\n  /**\n   * 讀取固定長度的位元組\n   */\n  private readBytes(length: number): Uint8Array {\n    if (this.offset + length > this.data.length) {\n      throw new Error('CBOR 資料不足')\n    }\n    const result = this.data.slice(this.offset, this.offset + length)\n    this.offset += length\n    return result\n  }\n\n  /**\n   * 讀取 CBOR 長度\n   */\n  private readLength(additionalInfo: number): number {\n    if (additionalInfo < 24) {\n      return additionalInfo\n    }\n    if (additionalInfo === 24) {\n      return this.readByte()\n    }\n    if (additionalInfo === 25) {\n      const b1 = this.readByte()\n      const b2 = this.readByte()\n      return (b1 << 8) | b2\n    }\n    if (additionalInfo === 26) {\n      const b1 = this.readByte()\n      const b2 = this.readByte()\n      const b3 = this.readByte()\n      const b4 = this.readByte()\n      return (b1 << 24) | (b2 << 16) | (b3 << 8) | b4\n    }\n    if (additionalInfo === 27) {\n      // 64-bit，但 JavaScript 無法精確表示，只支援到 2^53\n      const high =\n        (this.readByte() << 24) | (this.readByte() << 16) | (this.readByte() << 8) | this.readByte()\n      const low =\n        (this.readByte() << 24) | (this.readByte() << 16) | (this.readByte() << 8) | this.readByte()\n      return high * 0x100000000 + low\n    }\n    throw new Error(`CBOR 無效的長度編碼: ${additionalInfo}`)\n  }\n\n  /**\n   * 遞迴解碼值\n   */\n  private decodeValue(depth: number): unknown {\n    if (depth > CborFallbackDecoder.MAX_DEPTH) {\n      throw new Error(`CBOR 解碼深度超過限制 ${CborFallbackDecoder.MAX_DEPTH}`)\n    }\n\n    const byte = this.readByte()\n    const majorType = (byte >> 5) & 0x07\n    const additionalInfo = byte & 0x1f\n\n    switch (majorType) {\n      case CBOR_MAJOR_TYPES.UINT:\n        return this.readLength(additionalInfo)\n\n      case CBOR_MAJOR_TYPES.NEGINT:\n        return -1 - this.readLength(additionalInfo)\n\n      case CBOR_MAJOR_TYPES.BYTES: {\n        const length = this.readLength(additionalInfo)\n        return this.readBytes(length)\n      }\n\n      case CBOR_MAJOR_TYPES.TEXT: {\n        const length = this.readLength(additionalInfo)\n        const bytes = this.readBytes(length)\n        const decoder = new TextDecoder()\n        return decoder.decode(bytes)\n      }\n\n      case CBOR_MAJOR_TYPES.ARRAY: {\n        const length = this.readLength(additionalInfo)\n        const result: unknown[] = []\n        for (let i = 0; i < length; i++) {\n          result.push(this.decodeValue(depth + 1))\n        }\n        return result\n      }\n\n      case CBOR_MAJOR_TYPES.MAP: {\n        const length = this.readLength(additionalInfo)\n        const result: Record<string, unknown> = {}\n        for (let i = 0; i < length; i++) {\n          const key = this.decodeValue(depth + 1)\n          if (typeof key !== 'string') {\n            throw new Error(`CBOR Map 的 key 必須是字串，得到: ${typeof key}`)\n          }\n          result[key] = this.decodeValue(depth + 1)\n        }\n        return result\n      }\n\n      case CBOR_MAJOR_TYPES.SIMPLE:\n        if (additionalInfo === CBOR_SIMPLE_VALUES.FALSE) {\n          return false\n        }\n        if (additionalInfo === CBOR_SIMPLE_VALUES.TRUE) {\n          return true\n        }\n        if (additionalInfo === CBOR_SIMPLE_VALUES.NULL) {\n          return null\n        }\n\n        // 浮點數\n        if (additionalInfo === CBOR_LENGTH_ENCODING.FLOAT32) {\n          const bytes = this.readBytes(4)\n          const view = new DataView(bytes.buffer, bytes.byteOffset)\n          return view.getFloat32(0, false)\n        }\n        if (additionalInfo === CBOR_LENGTH_ENCODING.FLOAT64) {\n          const bytes = this.readBytes(8)\n          const view = new DataView(bytes.buffer, bytes.byteOffset)\n          return view.getFloat64(0, false)\n        }\n\n        throw new Error(`CBOR 不支援的 simple value: ${additionalInfo}`)\n\n      case CBOR_MAJOR_TYPES.TAG:\n        // TAG 類型在此實現中跳過\n        return this.decodeValue(depth)\n\n      default:\n        throw new Error(`CBOR 無效的 major type: ${majorType}`)\n    }\n  }\n}\n",
+    "/**\n * 雜湊加速器 JavaScript 回退實現\n * 基於 node:crypto 標準庫\n *\n * 使用場景：\n * - 非 Bun 環境（Node.js、Deno 等）\n * - Bun CryptoHasher 不可用的情況\n *\n * 性能特性：\n * - 短 key (<100 bytes)：~1-2x 慢於 Bun.CryptoHasher（N-API 橋接開銷）\n * - 長 payload：差異較小（主要計算時間）\n * - 一致性：與 node:crypto 標準行為完全相同\n */\n\nimport { createHash, createHmac } from 'node:crypto'\nimport type { HashAccelerator } from './types'\n\n/**\n * Node.js crypto 回退實現\n * 適用於非 Bun 環境\n */\nexport class HashFallback implements HashAccelerator {\n  /**\n   * SHA-256 計算（回退實現）\n   * @param input - 輸入（字串或 Uint8Array）\n   * @returns 十六進制編碼的 SHA-256 雜湊值\n   */\n  sha256(input: string | Uint8Array): string {\n    return createHash('sha256').update(input).digest('hex')\n  }\n\n  /**\n   * HMAC-SHA256 計算（回退實現）\n   * @param key - 密鑰\n   * @param data - 要雜湊的數據\n   * @returns 十六進制編碼的 HMAC-SHA256 值\n   */\n  hmacSha256(key: string, data: string): string {\n    return createHmac('sha256', key).update(data).digest('hex')\n  }\n}\n",
+    "/**\n * 原生加速器統一入口\n * 遵循 Galaxy Architecture 的運行時自適應模式\n * 與 RuntimeAdapter 模式保持一致\n */\n\nimport { CborFallbackEncoder } from './cbor-fallback'\nimport type { CborAccelerator, NativeAcceleratorStatus } from './types'\n\n/**\n * 原生加速器類別\n * 提供運行時自適應的 CBOR 編碼/解碼加速\n * - 在 Bun 環境下優先使用 C 編譯器實現（bun:ffi）\n * - 在非 Bun 環境或 FFI 不可用時自動降級到 JavaScript 實現\n */\nexport class NativeAccelerator {\n  private static readonly DEBUG_ENV = 'GRAVITO_FFI_DEBUG'\n  private static readonly DISABLE_ENV = 'GRAVITO_FFI_DISABLE'\n\n  /**\n   * FFI 可用性緩存\n   * null: 未檢測, true: 可用, false: 不可用\n   */\n  private static available: boolean | null = null\n\n  /**\n   * 當前加速器實例緩存\n   */\n  private static cborAccelerator: CborAccelerator | null = null\n\n  /**\n   * 當前狀態\n   */\n  private static status: NativeAcceleratorStatus | null = null\n\n  /**\n   * 檢測原生 FFI 是否可用\n   * 偵測邏輯：\n   * 1. 檢查 GRAVITO_FFI_DISABLE 環境變數\n   * 2. 檢查 Bun 運行時可用性\n   * 3. 檢查 bun:ffi 的 cc() 是否可用\n   */\n  static isAvailable(): boolean {\n    if (this.available !== null) {\n      return this.available\n    }\n\n    // 檢查環境變數強制禁用\n    if (typeof process !== 'undefined' && process.env) {\n      if (process.env[this.DISABLE_ENV] === '1') {\n        this.available = false\n        return false\n      }\n    }\n\n    // 檢查 Bun 運行時\n    try {\n      if (typeof Bun === 'undefined') {\n        this.available = false\n        return false\n      }\n\n      // 嘗試載入 bun:ffi 的 cc 函數\n      const bunFfi = require('bun:ffi')\n      if (typeof bunFfi.cc !== 'function') {\n        this.available = false\n        return false\n      }\n\n      this.available = true\n      return true\n    } catch {\n      this.available = false\n      return false\n    }\n  }\n\n  /**\n   * 取得 CBOR 加速器實例\n   * 優先使用 Native，失敗則降級到 Fallback\n   */\n  static getCborAccelerator(): CborAccelerator {\n    if (this.cborAccelerator !== null) {\n      return this.cborAccelerator\n    }\n\n    // 嘗試載入原生實現\n    if (this.isAvailable()) {\n      try {\n        const native = this.loadNativeImplementation()\n        if (native !== null) {\n          this.cborAccelerator = native\n          this.updateStatus('bun-ffi')\n          return native\n        }\n      } catch (error) {\n        const debugMode = this.isDebugEnabled()\n        if (debugMode) {\n          console.warn('[GRAVITO_FFI] Native CBOR 載入失敗，降級到 JavaScript 實現:', error)\n        }\n        // 繼續降級到 Fallback\n      }\n    }\n\n    // 降級到 JavaScript 實現\n    const fallback = new CborFallbackEncoder()\n    this.cborAccelerator = fallback\n    this.updateStatus('js-fallback')\n\n    if (this.isDebugEnabled()) {\n      console.log('[GRAVITO_FFI] 使用 JavaScript 回退實現')\n    }\n\n    return fallback\n  }\n\n  /**\n   * 取得加速器狀態\n   */\n  static getStatus(): NativeAcceleratorStatus {\n    // 確保狀態已初始化\n    if (this.status === null) {\n      this.getCborAccelerator()\n    }\n    return (\n      this.status || {\n        available: false,\n        runtime: 'js-fallback',\n        version: '1.0.0',\n      }\n    )\n  }\n\n  /**\n   * 重置加速器狀態（用於測試）\n   */\n  static reset(): void {\n    this.available = null\n    this.cborAccelerator = null\n    this.status = null\n  }\n\n  /**\n   * 解析 C 原始碼路徑\n   * 支援從原始碼目錄或 npm 套件的 src/ffi/native 目錄載入\n   */\n  private static resolveCSourcePath(): string {\n    const path = require('node:path')\n    const fs = require('node:fs')\n\n    // 取得當前模組目錄（ESM 優先，CJS 回退）\n    const currentDir =\n      typeof import.meta?.dir === 'string' && import.meta.dir !== ''\n        ? import.meta.dir\n        : typeof __dirname === 'string'\n          ? __dirname\n          : process.cwd()\n\n    // 嘗試多個可能的路徑（開發時 vs 發佈後）\n    const candidates = [\n      path.resolve(currentDir, 'native', 'cbor.c'),\n      path.resolve(currentDir, '..', 'ffi', 'native', 'cbor.c'),\n      path.resolve(currentDir, '..', '..', 'src', 'ffi', 'native', 'cbor.c'),\n    ]\n\n    for (const candidate of candidates) {\n      try {\n        if (fs.existsSync(candidate)) {\n          return candidate\n        }\n      } catch {}\n    }\n\n    throw new Error(`C 原始碼檔案未找到，嘗試路徑: ${candidates.join(', ')}`)\n  }\n\n  /**\n   * 載入原生 C 實現\n   * 使用 bun:ffi 的 cc() 動態編譯 C 代碼\n   * 優先從檔案載入完整實現，避免內聯限制\n   */\n  private static loadNativeImplementation(): CborAccelerator | null {\n    try {\n      // 檢查 Bun 運行時\n      if (typeof Bun === 'undefined') {\n        return null\n      }\n\n      const bunFfi = require('bun:ffi')\n      if (typeof bunFfi.cc !== 'function') {\n        return null\n      }\n\n      // 解析 C 原始碼路徑\n      const cSourcePath = this.resolveCSourcePath()\n\n      if (this.isDebugEnabled()) {\n        console.log(`[GRAVITO_FFI] 載入 C 原始碼: ${cSourcePath}`)\n      }\n\n      // 使用 bun:ffi 的 cc() 編譯 C 代碼\n      // cc() 的 source 參數接受檔案路徑（不是源碼字串）\n      const lib = bunFfi.cc({\n        source: cSourcePath,\n        symbols: {\n          gravito_cbor_encode: {\n            args: ['ptr', 'usize', 'ptr', 'usize'],\n            returns: 'i32',\n          },\n          gravito_cbor_decode: {\n            args: ['ptr', 'usize', 'ptr', 'usize'],\n            returns: 'i32',\n          },\n        },\n      })\n\n      // cc() 返回 { close, symbols: { ... } }\n      return new NativeCborAccelerator(lib.symbols)\n    } catch (error) {\n      if (this.isDebugEnabled()) {\n        console.error('[GRAVITO_FFI] 編譯失敗:', error)\n      }\n      return null\n    }\n  }\n\n  /**\n   * 檢查是否啟用調試模式\n   */\n  private static isDebugEnabled(): boolean {\n    if (typeof process !== 'undefined' && process.env) {\n      return process.env[this.DEBUG_ENV] === '1'\n    }\n    return false\n  }\n\n  /**\n   * 更新狀態\n   */\n  private static updateStatus(runtime: 'bun-ffi' | 'js-fallback'): void {\n    this.status = {\n      available: runtime === 'bun-ffi',\n      runtime,\n      version: runtime === 'bun-ffi' ? 'native-1.0.0' : 'js-fallback-1.0.0',\n    }\n  }\n}\n\n/**\n * 原生 C CBOR 加速器包裝類\n */\nclass NativeCborAccelerator implements CborAccelerator {\n  private symbols: any\n\n  constructor(symbols: any) {\n    this.symbols = symbols\n  }\n\n  encode(data: Record<string, unknown>): Uint8Array {\n    // 將物件序列化為 JSON\n    const json = JSON.stringify(data)\n    const jsonBytes = new TextEncoder().encode(json)\n\n    // 估算 CBOR 輸出大小（CBOR 通常比 JSON 小 20-40%）\n    let outputCapacity = Math.ceil(jsonBytes.length * 1.5)\n    const maxAttempts = 3\n\n    for (let attempt = 0; attempt < maxAttempts; attempt++) {\n      const outputBuffer = new Uint8Array(outputCapacity)\n\n      // 調用 C 編碼函數\n      const result = this.symbols.gravito_cbor_encode(\n        jsonBytes,\n        jsonBytes.length,\n        outputBuffer,\n        outputCapacity\n      )\n\n      if (typeof result !== 'number') {\n        throw new Error('FFI 回傳值無效')\n      }\n\n      if (result > 0) {\n        // 成功\n        return outputBuffer.slice(0, result)\n      }\n\n      if (result === -1) {\n        // Buffer 不足，擴大重試\n        outputCapacity *= 2\n        continue\n      }\n\n      // 其他錯誤\n      throw new Error(`CBOR 編碼失敗 (error: ${result})`)\n    }\n\n    throw new Error(`CBOR 編碼失敗：超過最大重試次數，需要 > ${outputCapacity} 位元組`)\n  }\n\n  decode(bytes: Uint8Array): Record<string, unknown> {\n    // 估算 JSON 輸出大小（JSON 通常比 CBOR 大）\n    let jsonCapacity = Math.ceil(bytes.length * 3)\n    const maxAttempts = 3\n\n    for (let attempt = 0; attempt < maxAttempts; attempt++) {\n      const jsonBuffer = new Uint8Array(jsonCapacity)\n\n      // 調用 C 解碼函數\n      const result = this.symbols.gravito_cbor_decode(bytes, bytes.length, jsonBuffer, jsonCapacity)\n\n      if (typeof result !== 'number') {\n        throw new Error('FFI 回傳值無效')\n      }\n\n      if (result > 0) {\n        // 成功\n        const jsonString = new TextDecoder().decode(jsonBuffer.slice(0, result))\n        const obj = JSON.parse(jsonString)\n\n        if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {\n          throw new Error('CBOR 根值必須是物件')\n        }\n\n        return obj as Record<string, unknown>\n      }\n\n      if (result === -1) {\n        // Buffer 不足，擴大重試\n        jsonCapacity *= 2\n        continue\n      }\n\n      // 其他錯誤\n      throw new Error(`CBOR 解碼失敗 (error: ${result})`)\n    }\n\n    throw new Error(`CBOR 解碼失敗：超過最大重試次數，需要 > ${jsonCapacity} 位元組`)\n  }\n}\n",
+    "/**\n * 原生雜湊加速器\n * 運行時自適應實現，遵循 Galaxy Architecture 的設計模式\n *\n * 架構：\n * - 在 Bun 環境：使用 Bun.CryptoHasher（C 實現，高效）\n * - 其他環境：自動降級到 node:crypto\n * - 完全相同的 API 和結果保證\n *\n * 性能：\n * - Bun 環境：2-3x 快於 node:crypto（消除 N-API 開銷）\n * - 跨運行時：完全相容性\n *\n * 應用場景：\n * - FileStore.hashKey() 熱路徑\n * - Encrypter.hash() 加密雜湊\n * - 任何需要高效雜湊計算的地方\n */\n\nimport { HashFallback } from './hash-fallback'\nimport type { HashAccelerator, NativeHasherStatus } from './types'\n\n/**\n * Bun 原生 CryptoHasher 實現\n * 直接使用 Bun.CryptoHasher API\n */\nclass BunCryptoHasher implements HashAccelerator {\n  /**\n   * SHA-256 計算（Bun 原生）\n   * @param input - 輸入（字串或 Uint8Array）\n   * @returns 十六進制編碼的 SHA-256 雜湊值\n   */\n  sha256(input: string | Uint8Array): string {\n    return new Bun.CryptoHasher('sha256').update(input).digest('hex')\n  }\n\n  /**\n   * HMAC-SHA256 計算（Bun 原生）\n   * Bun.CryptoHasher 第二參數直接支援 HMAC 密鑰\n   *\n   * @param key - 密鑰\n   * @param data - 要雜湊的數據\n   * @returns 十六進制編碼的 HMAC-SHA256 值\n   */\n  hmacSha256(key: string, data: string): string {\n    return new Bun.CryptoHasher('sha256', key).update(data).digest('hex')\n  }\n}\n\n/**\n * 原生雜湊加速器統一入口\n * 提供運行時自適應的 SHA-256/HMAC-SHA256 計算\n *\n * 使用範例：\n * ```typescript\n * // SHA-256\n * const hash = NativeHasher.sha256('data')\n *\n * // HMAC-SHA256\n * const hmac = NativeHasher.hmacSha256('secret', 'message')\n *\n * // 檢查狀態\n * const status = NativeHasher.getStatus()\n * console.log(`使用: ${status.runtime}`)\n * ```\n */\nexport class NativeHasher {\n  /**\n   * 當前加速器實例緩存\n   */\n  private static accelerator: HashAccelerator | null = null\n\n  /**\n   * 當前狀態緩存\n   */\n  private static status: NativeHasherStatus | null = null\n\n  /**\n   * 取得雜湊加速器實例\n   * 優先使用 Bun.CryptoHasher，失敗則降級到 node:crypto\n   *\n   * @returns 雜湊加速器實例\n   */\n  private static getAccelerator(): HashAccelerator {\n    if (this.accelerator !== null) {\n      return this.accelerator\n    }\n\n    // 嘗試使用 Bun 原生實現\n    if (this.isBunAvailable()) {\n      try {\n        this.accelerator = new BunCryptoHasher()\n        this.updateStatus('bun-crypto-hasher')\n        return this.accelerator\n      } catch {\n        // 降級到回退實現\n      }\n    }\n\n    // 降級到 node:crypto 回退\n    this.accelerator = new HashFallback()\n    this.updateStatus('node-crypto')\n    return this.accelerator\n  }\n\n  /**\n   * 檢測 Bun 運行時和 CryptoHasher 可用性\n   *\n   * @returns Bun.CryptoHasher 是否可用\n   */\n  private static isBunAvailable(): boolean {\n    try {\n      return typeof Bun !== 'undefined' && typeof Bun.CryptoHasher === 'function'\n    } catch {\n      return false\n    }\n  }\n\n  /**\n   * 更新狀態\n   *\n   * @param runtime - 當前使用的運行時\n   */\n  private static updateStatus(runtime: 'bun-crypto-hasher' | 'node-crypto'): void {\n    this.status = {\n      available: runtime === 'bun-crypto-hasher',\n      runtime,\n    }\n  }\n\n  /**\n   * 計算 SHA-256 雜湊\n   * 支援字串和二進制輸入\n   *\n   * @param input - 要雜湊的數據（字串或 Uint8Array）\n   * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）\n   *\n   * @example\n   * ```typescript\n   * const hash = NativeHasher.sha256('hello')\n   * // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'\n   *\n   * // 支援 Uint8Array\n   * const bytes = new TextEncoder().encode('hello')\n   * const hash2 = NativeHasher.sha256(bytes)\n   * // 相同結果\n   * ```\n   */\n  static sha256(input: string | Uint8Array): string {\n    return this.getAccelerator().sha256(input)\n  }\n\n  /**\n   * 計算 HMAC-SHA256\n   * 用於認證消息完整性\n   *\n   * @param key - HMAC 密鑰\n   * @param data - 要雜湊的數據\n   * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）\n   *\n   * @example\n   * ```typescript\n   * const hmac = NativeHasher.hmacSha256('secret', 'message')\n   * // '8b1a9953c4611296aed9e132b8502cf413b1b881fed3e8d26ab'...\n   *\n   * // 適用於加密驗證\n   * const iv = Buffer.from('...').toString('base64')\n   * const encrypted = '...'\n   * const mac = NativeHasher.hmacSha256(key, iv + encrypted)\n   * ```\n   */\n  static hmacSha256(key: string, data: string): string {\n    return this.getAccelerator().hmacSha256(key, data)\n  }\n\n  /**\n   * 取得加速器狀態\n   * 用於診斷和性能監測\n   *\n   * @returns 加速器狀態報告\n   *\n   * @example\n   * ```typescript\n   * const status = NativeHasher.getStatus()\n   * console.log(`可用: ${status.available}`)\n   * console.log(`運行時: ${status.runtime}`)\n   *\n   * // 條件邏輯\n   * if (status.runtime === 'bun-crypto-hasher') {\n   *   console.log('使用 Bun 原生實現（高效）')\n   * } else {\n   *   console.log('使用 node:crypto（相容性回退）')\n   * }\n   * ```\n   */\n  static getStatus(): NativeHasherStatus {\n    // 確保狀態已初始化\n    if (this.status === null) {\n      this.getAccelerator()\n    }\n\n    return (\n      this.status || {\n        available: false,\n        runtime: 'node-crypto',\n      }\n    )\n  }\n\n  /**\n   * 重置加速器狀態\n   * 主要用於測試目的，允許重新初始化運行時檢測\n   *\n   * @internal\n   * @example\n   * ```typescript\n   * // 測試中\n   * NativeHasher.reset()\n   * // 下一次呼叫會重新偵測運行時\n   * const status = NativeHasher.getStatus()\n   * ```\n   */\n  static reset(): void {\n    this.accelerator = null\n    this.status = null\n  }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "68336483751FA4E264756E2164756E21",
+  "names": []
+}

package/dist/ffi/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * FFI (Foreign Function Interface) 類型定義
+ * 支持 bun:ffi 的原生加速層
+ */
+/**
+ * CBOR 編碼/解碼加速器介面
+ * 可由原生 C 實現或 JavaScript 回退實現
+ */
+export interface CborAccelerator {
+    /**
+     * 將任意 JavaScript 物件編碼為 CBOR 二進制格式
+     * @param data - 要編碼的物件（支援：map、string、uint、float64、bytes、null、boolean）
+     * @returns CBOR 編碼的二進制資料
+     */
+    encode(data: Record<string, unknown>): Uint8Array;
+    /**
+     * 將 CBOR 二進制格式解碼為 JavaScript 物件
+     * @param bytes - CBOR 編碼的二進制資料
+     * @returns 解碼後的物件
+     */
+    decode(bytes: Uint8Array): Record<string, unknown>;
+}
+/**
+ * FFI 加速層狀態報告
+ */
+export interface NativeAcceleratorStatus {
+    /**
+     * 原生 FFI 加速是否可用
+     */
+    readonly available: boolean;
+    /**
+     * 當前使用的運行時實現
+     * - 'bun-ffi': Bun C 編譯器（bun:ffi 的 cc()）
+     * - 'js-fallback': 手寫 JavaScript CBOR 實現
+     * - 'cborg': npm 的 cborg 套件（已棄用，僅用於向後相容）
+     */
+    readonly runtime: 'bun-ffi' | 'js-fallback' | 'cborg';
+    /**
+     * 運行時版本或詳細資訊
+     */
+    readonly version: string;
+}
+/**
+ * FFI 層配置選項
+ */
+export interface FfiConfig {
+    /**
+     * 啟用調試日誌
+     * @default false
+     */
+    readonly debug?: boolean;
+    /**
+     * 最大 buffer 大小（位元組）
+     * @default 1048576 (1MB)
+     */
+    readonly maxBufferSize?: number;
+    /**
+     * 強制使用特定的加速器實現
+     * - undefined: 自動選擇（優先 bun-ffi，降級到 js-fallback）
+     * - 'bun-ffi': 只使用原生 C 實現
+     * - 'js-fallback': 只使用 JavaScript 實現
+     */
+    readonly forceImplementation?: 'bun-ffi' | 'js-fallback';
+}
+/**
+ * CBOR Major Type 常數
+ * 符合 RFC 7049 規範
+ */
+export declare const CBOR_MAJOR_TYPES: {
+    readonly UINT: 0;
+    readonly NEGINT: 1;
+    readonly BYTES: 2;
+    readonly TEXT: 3;
+    readonly ARRAY: 4;
+    readonly MAP: 5;
+    readonly TAG: 6;
+    readonly SIMPLE: 7;
+};
+/**
+ * CBOR 簡單值常數
+ */
+export declare const CBOR_SIMPLE_VALUES: {
+    readonly FALSE: 20;
+    readonly TRUE: 21;
+    readonly NULL: 22;
+    readonly UNDEFINED: 23;
+};
+/**
+ * CBOR 長度編碼的附加資訊
+ */
+export declare const CBOR_LENGTH_ENCODING: {
+    readonly SMALL_RANGE_END: 23;
+    readonly UINT8: 24;
+    readonly UINT16: 25;
+    readonly UINT32: 26;
+    readonly UINT64: 27;
+    readonly FLOAT16: 25;
+    readonly FLOAT32: 26;
+    readonly FLOAT64: 27;
+    readonly INDEFINITE: 31;
+};
+/**
+ * 雜湊加速器介面
+ * 可由 Bun 原生實現或 Node.js 回退實現
+ */
+export interface HashAccelerator {
+    /**
+     * SHA-256 雜湊計算
+     * @param input - 輸入（字串或二進制）
+     * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）
+     */
+    sha256(input: string | Uint8Array): string;
+    /**
+     * HMAC-SHA256 計算
+     * @param key - 密鑰
+     * @param data - 要雜湊的數據
+     * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）
+     */
+    hmacSha256(key: string, data: string): string;
+}
+/**
+ * 雜湊加速器狀態報告
+ */
+export interface NativeHasherStatus {
+    /**
+     * 雜湊加速層是否可用
+     */
+    readonly available: boolean;
+    /**
+     * 當前使用的運行時實現
+     * - 'bun-crypto-hasher': Bun 原生 CryptoHasher（C 實現，推薦）
+     * - 'node-crypto': node:crypto 回退實現
+     */
+    readonly runtime: 'bun-crypto-hasher' | 'node-crypto';
+}

package/dist/health/HealthProvider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview HealthProvider - Cloud-native health checks
+ *
+ * Provides liveness and readiness probes for Kubernetes and cloud deployments
+ *
+ * @module @gravito/core/health
+ * @since 2.2.0
+ */
+import type { Container } from '../Container';
+import type { PlanetCore } from '../PlanetCore';
+import { ServiceProvider } from '../ServiceProvider';
+/**
+ * Health check result
+ * @public
+ */
+export interface HealthCheckResult {
+    /** Health status */
+    status: 'healthy' | 'unhealthy';
+    /** Optional message */
+    message?: string;
+}
+/**
+ * Health check function interface
+ * @public
+ */
+export interface HealthCheck {
+    /** Unique name for this check */
+    name: string;
+    /** Check function that returns health status */
+    check(): Promise<HealthCheckResult>;
+}
+/**
+ * HealthProvider - Provides /health/liveness and /health/readiness endpoints
+ *
+ * - Liveness: Always returns 200 OK (just checks if server is running)
+ * - Readiness: Returns 200 if all checks are healthy, 503 otherwise
+ *
+ * @public
+ */
+export declare class HealthProvider extends ServiceProvider {
+    private checks;
+    register(container: Container): void;
+    /**
+     * Register a health check
+     *
+     * @param check - The health check to register
+     *
+     * @example
+     * ```typescript
+     * const health = core.container.make<HealthProvider>('health')
+     * health.registerCheck({
+     *   name: 'database',
+     *   check: async () => {
+     *     try {
+     *       await db.ping()
+     *       return { status: 'healthy' }
+     *     } catch {
+     *       return { status: 'unhealthy', message: 'DB unreachable' }
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    registerCheck(check: HealthCheck): void;
+    boot(core: PlanetCore): void;
+}
+export default HealthProvider;

package/dist/helpers/Arr.d.ts

@@ -0,0 +1,19 @@
+import { type DataPath } from './data';
+/**
+ * Array and Collection Helpers.
+ * Provides utility methods for array manipulation and deep object access.
+ * @public
+ */
+export declare const Arr: {
+    readonly get: <TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault) => unknown | TDefault;
+    readonly has: (target: unknown, path: DataPath | null | undefined) => boolean;
+    readonly set: (target: unknown, path: DataPath, value: unknown, overwrite?: boolean) => unknown;
+    readonly wrap: <T>(value: T | T[] | null | undefined) => T[];
+    readonly first: <T>(items: readonly T[], callback?: (value: T, index: number) => boolean) => T | undefined;
+    readonly last: <T>(items: readonly T[], callback?: (value: T, index: number) => boolean) => T | undefined;
+    readonly only: <T extends Record<string, unknown>>(target: T, keys: readonly string[]) => Partial<T>;
+    readonly except: <T extends Record<string, unknown>>(target: T, keys: readonly string[]) => Partial<T>;
+    readonly flatten: (items: unknown[], depth?: number) => unknown[];
+    readonly pluck: <TItem extends Record<string, unknown>>(items: readonly TItem[], valuePath: DataPath, keyPath?: DataPath) => unknown[] | Record<string, unknown>;
+    readonly where: <T>(items: readonly T[], callback: (value: T, index: number) => boolean) => T[];
+};

package/dist/helpers/Str.d.ts

@@ -0,0 +1,38 @@
+type StartsEndsNeedle = string | readonly string[];
+/**
+ * String Helper Utilities.
+ * Provides methods for string manipulation, case conversion, and UUID generation.
+ * @public
+ */
+export declare const Str: {
+    readonly lower: (value: string) => string;
+    readonly upper: (value: string) => string;
+    readonly startsWith: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly endsWith: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly contains: (haystack: string, needles: StartsEndsNeedle) => boolean;
+    readonly snake: (value: string) => string;
+    readonly kebab: (value: string) => string;
+    readonly studly: (value: string) => string;
+    readonly camel: (value: string) => string;
+    readonly title: (value: string) => string;
+    readonly limit: (value: string, limit: number, end?: string) => string;
+    readonly slug: (value: string, separator?: string) => string;
+    readonly uuid: () => string;
+    /**
+     * 生成 UUID v7（單調遞增，內含時間戳）。
+     *
+     * Bun 環境使用原生 Bun.randomUUIDv7() (C++ 實作)。
+     * Node.js/Deno 環境使用 RFC 9562 的 JavaScript polyfill。
+     *
+     * UUID v7 的優勢：
+     * - 資料庫主鍵天然有序 → B-tree 索引性能提升 2-10x
+     * - 可從 UUID 提取毫秒級時間戳
+     * - 仍保持全域唯一性
+     *
+     * @returns UUID v7 字串
+     * @public
+     */
+    readonly uuidv7: () => string;
+    readonly random: (length?: number) => string;
+};
+export {};

package/dist/helpers/data.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Path segment (key) in a data structure.
+ * @public
+ */
+export type PathSegment = string | number;
+/**
+ * Path to a value (dot notation or array of segments).
+ * @public
+ */
+export type DataPath = string | readonly PathSegment[];
+/**
+ * Retrieve a value from a deep object using dot notation.
+ * @public
+ */
+export declare function dataGet<TDefault = undefined>(target: unknown, path: DataPath | null | undefined, defaultValue?: TDefault): unknown | TDefault;
+/**
+ * Check if a key exists in a deep object using dot notation.
+ * @public
+ */
+export declare function dataHas(target: unknown, path: DataPath | null | undefined): boolean;
+/**
+ * Set a value in a deep object using dot notation.
+ * @public
+ */
+export declare function dataSet(target: unknown, path: DataPath, setValue: unknown, overwrite?: boolean): unknown;

package/dist/helpers/errors.d.ts

@@ -0,0 +1,34 @@
+import type { GravitoContext } from '../http/types';
+/**
+ * Interface for displaying validation errors in views.
+ * @public
+ */
+export interface ErrorBag {
+    /** Check if a field has errors */
+    has(field: string): boolean;
+    /** Get the first error message for a field (or any first error if no field specified) */
+    first(field?: string): string | undefined;
+    /** Get all error messages for a field */
+    get(field: string): string[];
+    /** Get all errors for all fields */
+    all(): Record<string, string[]>;
+    /** Check if there are any errors */
+    any(): boolean;
+    /** Get total number of error messages */
+    count(): number;
+}
+/**
+ * Create a new ErrorBag instance from raw errors.
+ * @public
+ */
+export declare function createErrorBag(errors: Record<string, string[]>): ErrorBag;
+/**
+ * Helper to retrieve the ErrorBag from session flash data.
+ * @public
+ */
+export declare function errors(c: GravitoContext): ErrorBag;
+/**
+ * Helper to retrieve old input value from session flash.
+ * @public
+ */
+export declare function old(c: GravitoContext, field: string, defaultValue?: unknown): unknown;

package/dist/helpers/response.d.ts

@@ -0,0 +1,41 @@
+import type { ContentfulStatusCode, GravitoContext } from '../http/types';
+/**
+ * Standard API Success Response Structure
+ * @public
+ */
+export type ApiSuccess<T> = {
+    success: true;
+    data: T;
+};
+/**
+ * Standard API Failure Response Structure
+ * @public
+ */
+export type ApiFailure = {
+    success: false;
+    error: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+};
+/**
+ * Create a success response object.
+ * @public
+ */
+export declare function ok<T>(data: T): ApiSuccess<T>;
+/**
+ * Create a failure response object.
+ * @public
+ */
+export declare function fail(message: string, code?: string, details?: unknown): ApiFailure;
+/**
+ * Return a JSON response with standard success structure.
+ * @public
+ */
+export declare function jsonSuccess<T>(c: GravitoContext, data: T, status?: ContentfulStatusCode): Response;
+/**
+ * Return a JSON response with standard failure structure.
+ * @public
+ */
+export declare function jsonFail(c: GravitoContext, message: string, status?: ContentfulStatusCode, code?: string, details?: unknown): Response;