schema-dsl 2.0.0 → 2.0.1

package/src/config/constants.ts

@@ -1,83 +1,83 @@
-/**
- * Global constants.
- * Fixes:
- *   CF-01 IPv4 regex too permissive → replaced with RFC-compliant standard regex
- *   CF-02 IPv6 regex did not support compressed notation → replaced with full RFC 5952 compatible regex
- */
-
-// ========== Validation config ==========
-export const VALIDATION = {
-  MAX_RECURSION_DEPTH: 100,
-  MAX_ARRAY_SIZE: 100_000,
-  MAX_STRING_LENGTH: 1_000_000,
-  MAX_OBJECT_KEYS: 10_000,
-  DEFAULT_TIMEOUT: 5_000,
-  REGEX_TIMEOUT: 100,
-  CUSTOM_VALIDATOR_TIMEOUT: 1_000,
-} as const
-
-// ========== Cache config ==========
-export const CACHE = {
-  ENABLED: true,
-  SCHEMA_CACHE: {
-    MAX_SIZE: 5_000,
-    TTL: 3_600_000,   // 1 hour
-    STRATEGY: 'LRU',
-  },
-  STATS_ENABLED: true,
-} as const
-
-// ========== Format validation regex ==========
-
-/**
- * CF-01 fix: RFC-compliant IPv4 regex.
- * Each octet 0-255, four groups, full-string match.
- * Rejects invalid addresses such as 999.999.999.999.
- */
-const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)'
-export const PATTERN_IPV4 = new RegExp(`^(?:${IPV4_OCTET}\\.){3}${IPV4_OCTET}$`)
-
-/**
- * CF-02 fix: Full IPv6 regex (RFC 5952 compatible).
- * Covers:
- *   - Fully-expanded: 8 groups of hex
- *   - :: compressed: prefix / suffix / standalone :: variants
- * No nested quantifiers (avoids ReDoS).
- */
-const HEX4 = '[0-9a-fA-F]{1,4}'
-const IPV6_FULL = `(?:${HEX4}:){7}${HEX4}`
-const IPV6_COMPRESS = [
-  `(?:${HEX4}:){1,7}:`,                         // n:...:
-  `(?:${HEX4}:){1,6}:${HEX4}`,                  // n:...:n
-  `(?:${HEX4}:){1,5}(?::${HEX4}){1,2}`,
-  `(?:${HEX4}:){1,4}(?::${HEX4}){1,3}`,
-  `(?:${HEX4}:){1,3}(?::${HEX4}){1,4}`,
-  `(?:${HEX4}:){1,2}(?::${HEX4}){1,5}`,
-  `${HEX4}:(?::${HEX4}){1,6}`,
-  `:(?::${HEX4}){1,7}`,                          // ::n...
-  `::`,                                           // standalone :: (all-zeros)
-].join('|')
-export const PATTERN_IPV6 = new RegExp(`^(?:${IPV6_FULL}|${IPV6_COMPRESS})$`)
-
-export const FORMATS = {
-  BUILT_IN: [
-    'email', 'url', 'uri', 'uuid', 'ipv4', 'ipv6',
-    'hostname', 'date', 'date-time', 'time', 'regex', 'json',
-  ] as const,
-  PATTERNS: {
-    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-    uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
-    ipv4: PATTERN_IPV4,
-    ipv6: PATTERN_IPV6,
-    hostname: /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i,
-    dateTime: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z?$/,
-    date: /^\d{4}-\d{2}-\d{2}$/,
-    time: /^\d{2}:\d{2}:\d{2}$/,
-  },
-} as const
-
-// ========== Plugin config ==========
-export const PLUGINS = {
-  MAX_PLUGINS: 50,
-  NAMING_CONVENTION: /^schema-dsl-plugin-/,
-} as const
+/**
+ * Global constants.
+ * Fixes:
+ *   CF-01 IPv4 regex too permissive → replaced with RFC-compliant standard regex
+ *   CF-02 IPv6 regex did not support compressed notation → replaced with full RFC 5952 compatible regex
+ */
+
+// ========== Validation config ==========
+export const VALIDATION = {
+  MAX_RECURSION_DEPTH: 100,
+  MAX_ARRAY_SIZE: 100_000,
+  MAX_STRING_LENGTH: 1_000_000,
+  MAX_OBJECT_KEYS: 10_000,
+  DEFAULT_TIMEOUT: 5_000,
+  REGEX_TIMEOUT: 100,
+  CUSTOM_VALIDATOR_TIMEOUT: 1_000,
+} as const
+
+// ========== Cache config ==========
+export const CACHE = {
+  ENABLED: true,
+  SCHEMA_CACHE: {
+    MAX_SIZE: 5_000,
+    TTL: 3_600_000,   // 1 hour
+    STRATEGY: 'LRU',
+  },
+  STATS_ENABLED: true,
+} as const
+
+// ========== Format validation regex ==========
+
+/**
+ * CF-01 fix: RFC-compliant IPv4 regex.
+ * Each octet 0-255, four groups, full-string match.
+ * Rejects invalid addresses such as 999.999.999.999.
+ */
+const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)'
+export const PATTERN_IPV4 = new RegExp(`^(?:${IPV4_OCTET}\\.){3}${IPV4_OCTET}$`)
+
+/**
+ * CF-02 fix: Full IPv6 regex (RFC 5952 compatible).
+ * Covers:
+ *   - Fully-expanded: 8 groups of hex
+ *   - :: compressed: prefix / suffix / standalone :: variants
+ * No nested quantifiers (avoids ReDoS).
+ */
+const HEX4 = '[0-9a-fA-F]{1,4}'
+const IPV6_FULL = `(?:${HEX4}:){7}${HEX4}`
+const IPV6_COMPRESS = [
+  `(?:${HEX4}:){1,7}:`,                         // n:...:
+  `(?:${HEX4}:){1,6}:${HEX4}`,                  // n:...:n
+  `(?:${HEX4}:){1,5}(?::${HEX4}){1,2}`,
+  `(?:${HEX4}:){1,4}(?::${HEX4}){1,3}`,
+  `(?:${HEX4}:){1,3}(?::${HEX4}){1,4}`,
+  `(?:${HEX4}:){1,2}(?::${HEX4}){1,5}`,
+  `${HEX4}:(?::${HEX4}){1,6}`,
+  `:(?::${HEX4}){1,7}`,                          // ::n...
+  `::`,                                           // standalone :: (all-zeros)
+].join('|')
+export const PATTERN_IPV6 = new RegExp(`^(?:${IPV6_FULL}|${IPV6_COMPRESS})$`)
+
+export const FORMATS = {
+  BUILT_IN: [
+    'email', 'url', 'uri', 'uuid', 'ipv4', 'ipv6',
+    'hostname', 'date', 'date-time', 'time', 'regex', 'json',
+  ] as const,
+  PATTERNS: {
+    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+    uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    ipv4: PATTERN_IPV4,
+    ipv6: PATTERN_IPV6,
+    hostname: /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i,
+    dateTime: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z?$/,
+    date: /^\d{4}-\d{2}-\d{2}$/,
+    time: /^\d{2}:\d{2}:\d{2}$/,
+  },
+} as const
+
+// ========== Plugin config ==========
+export const PLUGINS = {
+  MAX_PLUGINS: 50,
+  NAMING_CONVENTION: /^schema-dsl-plugin-/,
+} as const

package/src/config/index.ts

@@ -1,2 +1,2 @@
-export * from './constants.js'
-export * from './patterns.js'
+export * from './constants.js'
+export * from './patterns.js'

package/src/config/patterns.ts

@@ -1,77 +1,77 @@
-/**
- * Built-in regex validation patterns (migrated from v1 lib/config/patterns/ to a single TypeScript file)
- */
-
-export interface PatternConfig {
-  pattern: RegExp
-  min?: number
-  max?: number
-  key: string
-}
-
-const phone: Record<string, PatternConfig> = {
-  cn: { pattern: /^1[3-9]\d{9}$/, min: 11, max: 11, key: 'pattern.phone.cn' },
-  us: { pattern: /^\d{10}$/, min: 10, max: 10, key: 'pattern.phone.us' },
-  uk: { pattern: /^(\+44\s?)?0?\d{10}$/, min: 10, max: 15, key: 'pattern.phone.uk' },
-  hk: { pattern: /^[5-9]\d{7}$/, min: 8, max: 8, key: 'pattern.phone.hk' },
-  tw: { pattern: /^09\d{8}$/, min: 10, max: 10, key: 'pattern.phone.tw' },
-  international: { pattern: /^\+[1-9]\d{1,14}$/, min: 8, max: 15, key: 'pattern.phone.international' },
-}
-
-const idCard: Record<string, PatternConfig> = {
-  cn: {
-    pattern: /^[1-9]\d{5}(18|19|20)\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\d{3}[0-9Xx]$/,
-    min: 18, max: 18, key: 'pattern.idCard.cn',
-  },
-}
-
-const creditCard: Record<string, PatternConfig> = {
-  visa:       { pattern: /^4[0-9]{12}(?:[0-9]{3})?$/, key: 'pattern.creditCard.visa' },
-  mastercard: { pattern: /^5[1-5][0-9]{14}$/, key: 'pattern.creditCard.mastercard' },
-  amex:       { pattern: /^3[47][0-9]{13}$/, key: 'pattern.creditCard.amex' },
-  discover:   { pattern: /^6(?:011|5[0-9]{2})[0-9]{12}$/, key: 'pattern.creditCard.discover' },
-  jcb:        { pattern: /^(?:2131|1800|35\d{3})\d{11}$/, key: 'pattern.creditCard.jcb' },
-  unionpay:   { pattern: /^62[0-9]{14,17}$/, key: 'pattern.creditCard.unionpay' },
-}
-
-const licensePlate: Record<string, PatternConfig> = {
-  cn: {
-    pattern: /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4}[A-HJ-NP-Z0-9挂学警港澳]$/,
-    key: 'pattern.licensePlate.cn',
-  },
-}
-
-const postalCode: Record<string, PatternConfig> = {
-  cn: { pattern: /^[1-9]\d{5}$/, key: 'pattern.postalCode.cn' },
-  us: { pattern: /^\d{5}(-\d{4})?$/, key: 'pattern.postalCode.us' },
-}
-
-const passport: Record<string, PatternConfig> = {
-  cn: {
-    pattern: /(^[EeKkGgDdHhMQqSs][0-9]{8}$)|(^(([Ee][a-fA-F])|([DdSPp][Ee])|([Kk][Jj])|([Mm][Aa])|(1[45]))[0-9]{7}$)/,
-    key: 'pattern.passport.cn',
-  },
-}
-
-const common: Record<string, PatternConfig> = {
-  domain: {
-    pattern: /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/i,
-    key: 'pattern.domain', min: 3, max: 253,
-  },
-  ip: {
-    // Composite IPv4 + IPv6 pattern (same as v1)
-    pattern:
-      /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$|^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/,
-    key: 'pattern.ip',
-  },
-  base64: {
-    pattern: /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/,
-    key: 'pattern.base64',
-  },
-  jwt: {
-    pattern: /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$/,
-    key: 'pattern.jwt',
-  },
-}
-
-export const PATTERNS = { phone, idCard, creditCard, licensePlate, postalCode, passport, common }
+/**
+ * Built-in regex validation patterns (migrated from v1 lib/config/patterns/ to a single TypeScript file)
+ */
+
+export interface PatternConfig {
+  pattern: RegExp
+  min?: number
+  max?: number
+  key: string
+}
+
+const phone: Record<string, PatternConfig> = {
+  cn: { pattern: /^1[3-9]\d{9}$/, min: 11, max: 11, key: 'pattern.phone.cn' },
+  us: { pattern: /^\d{10}$/, min: 10, max: 10, key: 'pattern.phone.us' },
+  uk: { pattern: /^(\+44\s?)?0?\d{10}$/, min: 10, max: 15, key: 'pattern.phone.uk' },
+  hk: { pattern: /^[5-9]\d{7}$/, min: 8, max: 8, key: 'pattern.phone.hk' },
+  tw: { pattern: /^09\d{8}$/, min: 10, max: 10, key: 'pattern.phone.tw' },
+  international: { pattern: /^\+[1-9]\d{1,14}$/, min: 8, max: 15, key: 'pattern.phone.international' },
+}
+
+const idCard: Record<string, PatternConfig> = {
+  cn: {
+    pattern: /^[1-9]\d{5}(18|19|20)\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\d{3}[0-9Xx]$/,
+    min: 18, max: 18, key: 'pattern.idCard.cn',
+  },
+}
+
+const creditCard: Record<string, PatternConfig> = {
+  visa:       { pattern: /^4[0-9]{12}(?:[0-9]{3})?$/, key: 'pattern.creditCard.visa' },
+  mastercard: { pattern: /^5[1-5][0-9]{14}$/, key: 'pattern.creditCard.mastercard' },
+  amex:       { pattern: /^3[47][0-9]{13}$/, key: 'pattern.creditCard.amex' },
+  discover:   { pattern: /^6(?:011|5[0-9]{2})[0-9]{12}$/, key: 'pattern.creditCard.discover' },
+  jcb:        { pattern: /^(?:2131|1800|35\d{3})\d{11}$/, key: 'pattern.creditCard.jcb' },
+  unionpay:   { pattern: /^62[0-9]{14,17}$/, key: 'pattern.creditCard.unionpay' },
+}
+
+const licensePlate: Record<string, PatternConfig> = {
+  cn: {
+    pattern: /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-Z][A-HJ-NP-Z0-9]{4}[A-HJ-NP-Z0-9挂学警港澳]$/,
+    key: 'pattern.licensePlate.cn',
+  },
+}
+
+const postalCode: Record<string, PatternConfig> = {
+  cn: { pattern: /^[1-9]\d{5}$/, key: 'pattern.postalCode.cn' },
+  us: { pattern: /^\d{5}(-\d{4})?$/, key: 'pattern.postalCode.us' },
+}
+
+const passport: Record<string, PatternConfig> = {
+  cn: {
+    pattern: /(^[EeKkGgDdHhMQqSs][0-9]{8}$)|(^(([Ee][a-fA-F])|([DdSPp][Ee])|([Kk][Jj])|([Mm][Aa])|(1[45]))[0-9]{7}$)/,
+    key: 'pattern.passport.cn',
+  },
+}
+
+const common: Record<string, PatternConfig> = {
+  domain: {
+    pattern: /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$/i,
+    key: 'pattern.domain', min: 3, max: 253,
+  },
+  ip: {
+    // Composite IPv4 + IPv6 pattern (same as v1)
+    pattern:
+      /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$|^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/,
+    key: 'pattern.ip',
+  },
+  base64: {
+    pattern: /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/,
+    key: 'pattern.base64',
+  },
+  jwt: {
+    pattern: /^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$/,
+    key: 'pattern.jwt',
+  },
+}
+
+export const PATTERNS = { phone, idCard, creditCard, licensePlate, postalCode, passport, common }

package/src/core/CacheManager.ts

@@ -1,159 +1,169 @@
-import { MemoryCache } from 'cache-hub'
-import { CACHE } from '../config/constants.js'
-
-type CacheValue = unknown
-
-export interface CacheStats {
-  hits: number
-  misses: number
-  sets: number
-  deletes: number
-  evictions: number
-  clears: number
-  hitRate: string
-  size: number
-  maxSize: number
-  enabled: boolean
-}
-
-/**
- * CacheManager — LRU cache for compiled AJV schemas.
- *
- * v2 delegates to cache-hub's MemoryCache (fix BD-04: miss returns undefined → normalized to null).
- *
- * cache-hub MemoryCache actual API:
- *   get(key) → value | undefined
- *   set(key, value, opts?) — opts.ttl in ms
- *   del(key) → boolean           ← note: del, not delete
- *   has(key) → boolean
- *   clear() → void
- *   keys() → string[]
- *   getStats() → { hits, misses, hitRate, entries, sets, deletes, evictions, memoryUsage }
- */
-export class CacheManager {
-  private _enabled: boolean
-  private _maxSize: number
-  private _ttl: number
-  private readonly _cache: MemoryCache
-  private _statsEnabled: boolean = true
-  private _clears = 0
-
-  constructor(options: {
-    maxSize?: number
-    ttl?: number
-    enabled?: boolean
-    statsEnabled?: boolean
-  } = {}) {
-    this._maxSize = options.maxSize ?? CACHE.SCHEMA_CACHE.MAX_SIZE
-    this._ttl = options.ttl ?? CACHE.SCHEMA_CACHE.TTL
-    this._enabled = options.enabled !== false
-    this._cache = new MemoryCache({ maxEntries: this._maxSize })
-    this._statsEnabled = options.statsEnabled !== false
-  }
-
-  get options(): { maxSize: number; ttl: number; enabled: boolean; statsEnabled: boolean } {
-    return {
-      maxSize: this._maxSize,
-      ttl: this._ttl,
-      enabled: this._enabled,
-      statsEnabled: this._statsEnabled,
-    }
-  }
-
-  set options(opts: Partial<{ maxSize: number; ttl: number; enabled: boolean; statsEnabled: boolean }>) {
-    if (opts.maxSize !== undefined) this._maxSize = opts.maxSize
-    if (opts.ttl !== undefined) this._ttl = opts.ttl
-    if (opts.enabled !== undefined) this._enabled = opts.enabled
-    if (opts.statsEnabled !== undefined) this._statsEnabled = opts.statsEnabled
-  }
-
-  /**
-   * Retrieve a cached AJV compile function.
-   * @returns cached compile function, or null on miss (BD-04: undefined → null)
-   */
-  get(key: string): CacheValue | null {
-    if (!this._enabled || key == null) return null
-    try {
-      const result = this._cache.get(String(key)) as CacheValue | undefined
-      return result !== undefined ? result : null
-    } catch {
-      return null
-    }
-  }
-
-  /**
-   * Write a value to the cache.
-   */
-  set(key: string, value: CacheValue, ttl?: number): void {
-    if (!this._enabled || key == null) return
-    try {
-      this._cache.set(String(key), value, ttl ?? this._ttl)
-    } catch {
-      // Silently ignore invalid keys for v1 compat
-    }
-  }
-
-  /**
-   * Delete a single cache entry.
-   */
-  delete(key: string): boolean {
-    return this._cache.del(key)
-  }
-
-  /**
-   * Check whether a key exists in the cache.
-   */
-  has(key: string): boolean {
-    if (!this._enabled) return false
-    return this._cache.has(key)
-  }
-
-  /**
-   * Clear all cache entries.
-   */
-  clear(): void {
-    this._cache.clear()
-    this._clears++
-  }
-
-  /**
-   * Return the current number of cache entries.
-   */
-  size(): number {
-    return this._cache.keys().length
-  }
-
-  /**
-   * Return cache statistics.
-   */
-  getStats(): CacheStats {
-    if (!this._statsEnabled) {
-      return {
-        hits: 0, misses: 0, sets: 0, deletes: 0, evictions: 0,
-        clears: 0, hitRate: '0.00', size: 0, maxSize: this._maxSize, enabled: this._enabled,
-      }
-    }
-    const inner = this._cache.getStats()
-    const total = inner.hits + inner.misses
-    return {
-      hits: inner.hits,
-      misses: inner.misses,
-      sets: inner.sets,
-      deletes: inner.deletes,
-      evictions: (inner as unknown as Record<string, unknown>).evictions as number ?? 0,
-      clears: this._clears,
-      hitRate: total > 0 ? ((inner.hits / total) * 100).toFixed(2) : '0.00',
-      size: inner.entries,
-      maxSize: this._maxSize,
-      enabled: this._enabled,
-    }
-  }
-
-  /**
-   * Reset all hit/miss/eviction counters.
-   */
-  resetStats(): void {
-    this._cache.resetStats()
-    this._clears = 0
-  }
-}
+import { MemoryCache } from 'cache-hub'
+import { CACHE } from '../config/constants.js'
+
+type CacheValue = unknown
+
+export interface CacheStats {
+  hits: number
+  misses: number
+  sets: number
+  deletes: number
+  evictions: number
+  clears: number
+  hitRate: string
+  size: number
+  maxSize: number
+  enabled: boolean
+}
+
+/**
+ * CacheManager — LRU cache for compiled AJV schemas.
+ *
+ * v2 delegates to cache-hub's MemoryCache (fix BD-04: miss returns undefined → normalized to null).
+ *
+ * cache-hub MemoryCache actual API:
+ *   get(key) → value | undefined
+ *   set(key, value, opts?) — opts.ttl in ms
+ *   del(key) → boolean           ← note: del, not delete
+ *   has(key) → boolean
+ *   clear() → void
+ *   keys() → string[]
+ *   getStats() → { hits, misses, hitRate, entries, sets, deletes, evictions, memoryUsage }
+ */
+export class CacheManager {
+  private _enabled: boolean
+  private _maxSize: number
+  private _ttl: number
+  private _cache: MemoryCache
+  private _statsEnabled: boolean = true
+  private _clears = 0
+
+  constructor(options: {
+    maxSize?: number
+    ttl?: number
+    enabled?: boolean
+    statsEnabled?: boolean
+  } = {}) {
+    this._maxSize = options.maxSize ?? CACHE.SCHEMA_CACHE.MAX_SIZE
+    this._ttl = options.ttl ?? CACHE.SCHEMA_CACHE.TTL
+    this._enabled = options.enabled !== false
+    this._cache = new MemoryCache({ maxEntries: this._maxSize })
+    this._statsEnabled = options.statsEnabled !== false
+  }
+
+  get options(): { maxSize: number; ttl: number; enabled: boolean; statsEnabled: boolean } {
+    return {
+      maxSize: this._maxSize,
+      ttl: this._ttl,
+      enabled: this._enabled,
+      statsEnabled: this._statsEnabled,
+    }
+  }
+
+  set options(opts: Partial<{ maxSize: number; ttl: number; enabled: boolean; statsEnabled: boolean }>) {
+    if (opts.maxSize !== undefined && opts.maxSize !== this._maxSize) {
+      this._maxSize = opts.maxSize
+      // Rebuild MemoryCache so the new capacity actually takes effect
+      const oldKeys = this._cache.keys()
+      const newCache = new MemoryCache({ maxEntries: this._maxSize })
+      for (const key of oldKeys) {
+        const val = this._cache.get(key)
+        if (val !== undefined) newCache.set(key, val)
+      }
+      this._cache = newCache
+    }
+    if (opts.ttl !== undefined) this._ttl = opts.ttl
+    if (opts.enabled !== undefined) this._enabled = opts.enabled
+    if (opts.statsEnabled !== undefined) this._statsEnabled = opts.statsEnabled
+  }
+
+  /**
+   * Retrieve a cached AJV compile function.
+   * @returns cached compile function, or null on miss (BD-04: undefined → null)
+   */
+  get(key: string): CacheValue | null {
+    if (!this._enabled || key == null) return null
+    try {
+      const result = this._cache.get(String(key)) as CacheValue | undefined
+      return result !== undefined ? result : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Write a value to the cache.
+   */
+  set(key: string, value: CacheValue, ttl?: number): void {
+    if (!this._enabled || key == null) return
+    try {
+      this._cache.set(String(key), value, ttl ?? this._ttl)
+    } catch {
+      // Silently ignore invalid keys for v1 compat
+    }
+  }
+
+  /**
+   * Delete a single cache entry.
+   */
+  delete(key: string): boolean {
+    return this._cache.del(key)
+  }
+
+  /**
+   * Check whether a key exists in the cache.
+   */
+  has(key: string): boolean {
+    if (!this._enabled) return false
+    return this._cache.has(key)
+  }
+
+  /**
+   * Clear all cache entries.
+   */
+  clear(): void {
+    this._cache.clear()
+    this._clears++
+  }
+
+  /**
+   * Return the current number of cache entries.
+   */
+  size(): number {
+    return this._cache.keys().length
+  }
+
+  /**
+   * Return cache statistics.
+   */
+  getStats(): CacheStats {
+    if (!this._statsEnabled) {
+      return {
+        hits: 0, misses: 0, sets: 0, deletes: 0, evictions: 0,
+        clears: 0, hitRate: '0.00', size: 0, maxSize: this._maxSize, enabled: this._enabled,
+      }
+    }
+    const inner = this._cache.getStats()
+    const total = inner.hits + inner.misses
+    return {
+      hits: inner.hits,
+      misses: inner.misses,
+      sets: inner.sets,
+      deletes: inner.deletes,
+      evictions: (inner as unknown as Record<string, unknown>).evictions as number ?? 0,
+      clears: this._clears,
+      hitRate: total > 0 ? ((inner.hits / total) * 100).toFixed(2) : '0.00',
+      size: inner.entries,
+      maxSize: this._maxSize,
+      enabled: this._enabled,
+    }
+  }
+
+  /**
+   * Reset all hit/miss/eviction counters.
+   */
+  resetStats(): void {
+    this._cache.resetStats()
+    this._clears = 0
+  }
+}