arckode-framework 1.0.0

package/kernel/framework.ts

@@ -0,0 +1,1851 @@
+// Arckode Framework — Kernel
+// SOLID. Modular. AI-oriented. ~900 líneas. La IA lo lee completo.
+// ────────────────────────────────────────────────────────────────
+// Principios:
+//   S — Cada clase hace UNA cosa
+//   O — Adapters y middlewares se agregan sin modificar el kernel
+//   L — Cualquier DbAdapter funciona con ORM, cualquier JwtAdapter con Auth
+//   I — Interfaces pequeñas: DbAdapter solo query/run, JwtAdapter solo sign/verify
+//   D — ORM depende de DbAdapter (interfaz), Auth depende de JwtAdapter (interfaz)
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// ═══════════════════════════════════════════════════════════════
+// 1. ERRORES — Tesperados con código HTTP y metadata
+// ═══════════════════════════════════════════════════════════════
+
+export abstract class ErrorContract extends Error {
+  public abstract readonly httpStatus: number
+  public abstract readonly isExpected: boolean
+  public abstract readonly canRetry: boolean
+  public abstract readonly errorCode: string
+
+  constructor(
+    message: string,
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message)
+    this.name = this.constructor.name
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      error: this.message,
+      code: this.errorCode,
+      ...(this.details ? { details: this.details } : {}),
+    }
+  }
+}
+
+export class ValidationError extends ErrorContract {
+  httpStatus = 400
+  isExpected = true
+  canRetry = false
+  errorCode = 'VALIDATION_ERROR'
+  constructor(msg: string, public fields?: Record<string, string[]>) {
+    super(msg, fields ? { fields } : undefined)
+  }
+}
+
+export class AuthError extends ErrorContract {
+  httpStatus = 401
+  isExpected = true
+  canRetry = false
+  errorCode = 'AUTH_ERROR'
+  constructor(message = 'Authentication error', details?: Record<string, unknown>) {
+    super(message, details)
+  }
+}
+
+export class ForbiddenError extends ErrorContract {
+  httpStatus = 403
+  isExpected = true
+  canRetry = false
+  errorCode = 'FORBIDDEN'
+}
+
+export class NotFoundError extends ErrorContract {
+  httpStatus = 404
+  isExpected = true
+  canRetry = false
+  errorCode = 'NOT_FOUND'
+}
+
+export class ConflictError extends ErrorContract {
+  httpStatus = 409
+  isExpected = true
+  canRetry = false
+  errorCode = 'CONFLICT'
+}
+
+export class RateLimitError extends ErrorContract {
+  httpStatus = 429
+  isExpected = true
+  canRetry = true
+  errorCode = 'RATE_LIMIT'
+}
+
+export class RepositoryError extends ErrorContract {
+  httpStatus = 500
+  isExpected = true
+  canRetry = true
+  errorCode = 'REPOSITORY_ERROR'
+}
+
+export class InternalError extends ErrorContract {
+  httpStatus = 500
+  isExpected = false
+  canRetry = false
+  errorCode = 'INTERNAL_ERROR'
+}
+
+export class ModuleRuleError extends ErrorContract {
+  httpStatus = 500
+  isExpected = false
+  canRetry = false
+  errorCode = 'MODULE_RULE_VIOLATION'
+  constructor(module: string, rule: string) {
+    super(`[${module}] Regla violada: ${rule}`, { module, rule })
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 2. LOGGER — Estructurado, por módulo, transportable
+// ═══════════════════════════════════════════════════════════════
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+export interface LoggerTransport {
+  write(entry: { timestamp: string; level: LogLevel; source: string; message: string; meta?: Record<string, unknown> }): void
+}
+
+export class Logger {
+  constructor(
+    public readonly source: string = 'app',
+    private level: LogLevel = 'info',
+    private transports: LoggerTransport[] = [new ConsoleTransport()],
+  ) {}
+
+  child(name: string): Logger {
+    return new Logger(`${this.source}.${name}`, this.level, this.transports)
+  }
+
+  debug(message: string, meta?: Record<string, unknown>): void { this.emit('debug', message, meta) }
+  info(message: string, meta?: Record<string, unknown>): void  { this.emit('info', message, meta) }
+  warn(message: string, meta?: Record<string, unknown>): void  { this.emit('warn', message, meta) }
+  error(message: string, meta?: Record<string, unknown>): void { this.emit('error', message, meta) }
+
+  private emit(level: LogLevel, message: string, meta?: Record<string, unknown>): void {
+    const weight = { debug: 0, info: 1, warn: 2, error: 3 }
+    if (weight[level] < weight[this.level]) return
+
+    const entry: Record<string, unknown> = {
+      timestamp: new Date().toISOString(),
+      level,
+      source: this.source,
+      message,
+    }
+
+    if (meta && Object.keys(meta).length > 0) {
+      entry.meta = { ...meta }
+    }
+
+    for (const t of this.transports) t.write(entry as any)
+  }
+}
+
+class ConsoleTransport implements LoggerTransport {
+  write(entry: { level: LogLevel; message: string; source: string } & Record<string, unknown>): void {
+    const line = JSON.stringify(entry)
+    if (entry.level === 'error') console.error(line)
+    else if (entry.level === 'warn') console.warn(line)
+    else console.log(line)
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 3. CONFIG — Validada al startup. Fail fast.
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Carga variables de entorno con soporte de stages (development / staging / production).
+ * Parsea archivos .env y .env.{NODE_ENV} — el stage-specific sobreescribe el base.
+ * No tiene dependencias externas.
+ *
+ * @example
+ * // En composition-root.ts — ANTES de config.load()
+ * const env = await loadEnv()
+ * config.define({ PORT: { type: 'number', default: 3000 } }).load(env)
+ *
+ * // Archivos soportados (en orden, el último tiene prioridad):
+ * //   .env               → valores base (nunca commitear secrets)
+ * //   .env.development   → sobreescribe en NODE_ENV=development
+ * //   .env.staging       → sobreescribe en NODE_ENV=staging
+ * //   .env.production    → sobreescribe en NODE_ENV=production
+ */
+export async function loadEnv(opts: { cwd?: string } = {}): Promise<Record<string, string | undefined>> {
+  const { readFile } = await import('node:fs/promises')
+  const { join } = await import('node:path')
+
+  const cwd = opts.cwd ?? process.cwd()
+  const stage = (process.env.NODE_ENV ?? 'development').toLowerCase()
+
+  const parseEnvFile = (content: string): Record<string, string> => {
+    const result: Record<string, string> = {}
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const eq = trimmed.indexOf('=')
+      if (eq === -1) continue
+      const key = trimmed.slice(0, eq).trim()
+      let val = trimmed.slice(eq + 1).trim()
+      // Quitar comillas opcionales: "valor" o 'valor'
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1)
+      }
+      result[key] = val
+    }
+    return result
+  }
+
+  const tryRead = async (path: string): Promise<Record<string, string>> => {
+    try { return parseEnvFile(await readFile(path, 'utf-8')) } catch { return {} }
+  }
+
+  const base   = await tryRead(join(cwd, '.env'))
+  const staged = await tryRead(join(cwd, `.env.${stage}`))
+
+  // process.env tiene la prioridad más alta (variables de entorno reales del SO)
+  return { ...base, ...staged, ...process.env }
+}
+
+export type ConfigType = 'string' | 'number' | 'boolean' | 'url' | 'email'
+
+export interface ConfigDefinition {
+  type: ConfigType
+  required?: boolean
+  default?: string | number | boolean
+  description?: string
+  secret?: boolean
+}
+
+export class ConfigStore {
+  private definitions = new Map<string, ConfigDefinition>()
+  private values = new Map<string, unknown>()
+  private isLoaded = false
+
+  define(schema: Record<string, ConfigDefinition>): this {
+    for (const [key, def] of Object.entries(schema)) {
+      this.definitions.set(key, def)
+    }
+    return this
+  }
+
+  load(source: Record<string, string | undefined>): this {
+    const errors: string[] = []
+
+    for (const [key, def] of this.definitions) {
+      const raw = source[key] ?? def.default
+
+      if (raw == null || raw === '') {
+        if (def.required) errors.push(`CONFIG: ${key} es requerido`)
+        continue
+      }
+
+      let parsed: unknown
+
+      switch (def.type) {
+        case 'string':
+          parsed = String(raw)
+          break
+        case 'number': {
+          const n = Number(raw)
+          if (isNaN(n)) { errors.push(`CONFIG: ${key} must be a number`); continue }
+          parsed = n
+          break
+        }
+        case 'boolean':
+          parsed = raw === 'true' || raw === '1'
+          break
+        case 'url':
+          try { new URL(String(raw)); parsed = String(raw) }
+          catch { errors.push(`CONFIG: ${key} is not a valid URL`); continue }
+          break
+        case 'email':
+          if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(raw))) {
+            errors.push(`CONFIG: ${key} is not a valid email`); continue
+          }
+          parsed = String(raw)
+          break
+      }
+
+      this.values.set(key, parsed)
+    }
+
+    if (errors.length > 0) {
+      throw new InternalError(`Invalid configuration:\n${errors.join('\n')}`)
+    }
+
+    this.isLoaded = true
+    return this
+  }
+
+  get<T = string>(key: string): T {
+    if (!this.isLoaded) throw new InternalError('Config no cargada — llamar load()')
+    if (!this.values.has(key)) throw new InternalError(`Config "${key}" no definida`)
+    return this.values.get(key) as T
+  }
+
+  getOrThrow<T = string>(key: string): T {
+    return this.get<T>(key)
+  }
+
+  toJSON(): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+    for (const [key] of this.definitions) {
+      if (this.values.has(key)) {
+        const def = this.definitions.get(key)!
+        result[key] = def.secret ? '••••••' : this.values.get(key)
+      }
+    }
+    return result
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 4. CONTAINER — DI explícito, sin magia
+// ═══════════════════════════════════════════════════════════════
+
+interface ServiceEntry<T> {
+  name: string
+  factory: () => T
+  instance?: T
+  destructor?: () => Promise<void>
+  singleton: boolean
+}
+
+export class Container {
+  private services = new Map<string, ServiceEntry<unknown>>()
+  private initialized = false
+
+  register<T>(name: string, factory: () => T, destructor?: () => Promise<void>): this {
+    if (this.initialized) throw new InternalError(`Container: "${name}" registered after init`)
+    this.services.set(name, { name, factory, destructor, singleton: true })
+    return this
+  }
+
+  resolve<T>(name: string): T {
+    const entry = this.services.get(name) as ServiceEntry<T> | undefined
+    if (!entry) throw new InternalError(`Container: "${name}" no registrado`)
+    if (entry.singleton && entry.instance) return entry.instance
+    entry.instance = entry.factory()
+    return entry.instance as T
+  }
+
+  get<T>(name: string): T {
+    return this.resolve<T>(name)
+  }
+
+  init(): void {
+    this.initialized = true
+    for (const [name] of this.services) {
+      this.resolve(name)
+    }
+  }
+
+  async destroy(): Promise<void> {
+    const entries = [...this.services.values()].reverse()
+    for (const entry of entries) {
+      if (entry.destructor) {
+        try { await entry.destructor() } catch (e) {
+          console.error(`[Container] Error al destruir "${entry.name}":`, e)
+        }
+      }
+    }
+    this.services.clear()
+    this.initialized = false
+  }
+
+  get registered(): string[] {
+    return [...this.services.keys()]
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 5. ORM — Sobre DbAdapter. SOLID: depende de interfaz, no de implementación
+// ═══════════════════════════════════════════════════════════════
+
+// ── Contrato de adaptador de base de datos ──
+export interface DbAdapter {
+  query(sql: string, params?: unknown[]): Promise<unknown[]>
+  run(sql: string, params?: unknown[]): Promise<{ changes: number; lastId?: string }>
+  close(): Promise<void>
+  /** Opcional: soporte de transacciones. Si no lo implementa, se ejecuta sin transacción. */
+  transaction?<T>(fn: (adapter: DbAdapter) => Promise<T>): Promise<T>
+}
+
+// ── Definición de campo ──
+export interface FieldDefinition {
+  type: 'string' | 'number' | 'boolean' | 'json' | 'date'
+  required?: boolean
+  default?: unknown
+  unique?: boolean
+  indexed?: boolean
+  maxLength?: number
+}
+
+// ── Definición de modelo ──
+export interface ModelDefinition {
+  table: string
+  fields: Record<string, FieldDefinition>
+  timestamps?: boolean
+  softDelete?: boolean
+}
+
+// ── Resultado de consulta ──
+export interface ModelResult {
+  id: string
+  [key: string]: unknown
+}
+
+// ── Opciones de consulta ──
+export interface OrderByClause {
+  field: string
+  dir?: 'ASC' | 'DESC'
+}
+
+export interface FindOptions {
+  limit?: number
+  offset?: number
+  orderBy?: OrderByClause | OrderByClause[]
+  /** Campos a seleccionar. Si se omite: SELECT *. Los nombres se validan contra el modelo. */
+  select?: string[]
+}
+
+export interface PageResult<T = ModelResult> {
+  data: T[]
+  total: number
+  limit: number
+  offset: number
+  pages: number
+}
+
+// ═══════════════════════════════════════════════════════════════
+// REPOSITORY ADAPTER — Interfaz genérica de capa de datos
+// ═══════════════════════════════════════════════════════════════
+//
+// Los services DEBEN depender de RepositoryAdapter<T>, NO del ORM.
+// Esto permite swapear SQLite → MongoDB → Prisma → Redis sin tocar el service.
+//
+// Implementaciones disponibles:
+//   OrmRepository<T>     → built-in SQL ORM (SQLite, Postgres)
+//   Cualquier clase que implemente esta interfaz → Mongoose, Prisma, etc.
+//
+// Ejemplo en composition-root.ts:
+//   const productos = new OrmRepository<Producto>(orm, 'Producto')
+//   // O con MongoDB:
+//   const productos = new MongoProductoRepository(mongoCollection)
+//
+// El service recibe RepositoryAdapter<Producto> — no sabe qué hay atrás.
+
+export interface RepositoryAdapter<T extends object = Record<string, unknown>> {
+  findMany(filters?: Record<string, unknown>, options?: FindOptions): Promise<T[]>
+  findById(id: string, select?: string[]): Promise<T | null>
+  findOne(filters: Record<string, unknown>): Promise<T | null>
+  create(data: Omit<T, 'id'>): Promise<T>
+  update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>
+  delete(id: string): Promise<boolean>
+  count(filters?: Record<string, unknown>): Promise<number>
+  paginate(
+    filters?: Record<string, unknown>,
+    options?: FindOptions & { limit: number },
+  ): Promise<PageResult<T>>
+}
+
+// ── ORM — SOLID: S = solo ORM, D = depende de DbAdapter ──
+export class ORM {
+  private models = new Map<string, ModelDefinition>()
+
+  constructor(private db: DbAdapter) {}
+
+  define(name: string, def: ModelDefinition): this {
+    this.models.set(name, def)
+    return this
+  }
+
+  getDefinition(name: string): ModelDefinition {
+    const def = this.models.get(name)
+    if (!def) throw new NotFoundError(`Modelo "${name}" no definido`)
+    return def
+  }
+
+  /**
+   * Ejecuta múltiples operaciones en una transacción atómica.
+   * Si el adaptador no soporta transacciones, ejecuta sin ellas.
+   *
+   * @example
+   * await orm.transaction(async (tx) => {
+   *   await tx.create('Pedido', { productoId, cantidad })
+   *   await tx.update('Producto', productoId, { stock: nuevoStock })
+   * })
+   */
+  async transaction<T>(fn: (tx: ORM) => Promise<T>): Promise<T> {
+    if (this.db.transaction) {
+      return this.db.transaction(async (txAdapter) => {
+        const txOrm = new ORM(txAdapter)
+        for (const [name, def] of this.models) txOrm.define(name, def)
+        return fn(txOrm)
+      })
+    }
+    // Fallback: sin transacción si el adaptador no lo soporta
+    return fn(this)
+  }
+
+  // ── Helpers privados ──
+
+  private getAllowedFields(def: ModelDefinition): Set<string> {
+    const allowed = new Set(['id', ...Object.keys(def.fields)])
+    if (def.timestamps) { allowed.add('createdAt'); allowed.add('updatedAt') }
+    if (def.softDelete) allowed.add('deletedAt')
+    return allowed
+  }
+
+  private buildSelect(def: ModelDefinition, fields?: string[]): string {
+    if (!fields || fields.length === 0) return '*'
+    const allowed = this.getAllowedFields(def)
+    for (const f of fields) {
+      if (!allowed.has(f)) throw new ValidationError(`Invalid select field: "${f}"`)
+    }
+    return fields.join(', ')
+  }
+
+  private buildWhere(def: ModelDefinition, filters?: Record<string, unknown>): { clause: string; params: unknown[] } {
+    const parts: string[] = []
+    const params: unknown[] = []
+
+    if (filters && Object.keys(filters).length > 0) {
+      const allowed = this.getAllowedFields(def)
+      for (const [k, v] of Object.entries(filters)) {
+        if (!allowed.has(k)) throw new ValidationError(`Invalid filter field: "${k}"`)
+        params.push(v)
+        parts.push(`${k} = ?`)
+      }
+    }
+
+    if (def.softDelete) parts.push('deletedAt IS NULL')
+
+    return {
+      clause: parts.length > 0 ? ' WHERE ' + parts.join(' AND ') : '',
+      params,
+    }
+  }
+
+  // ── CRUD ──
+
+  async findMany(name: string, filters?: Record<string, unknown>, options?: FindOptions): Promise<ModelResult[]> {
+    const def = this.getDefinition(name)
+    const { clause, params } = this.buildWhere(def, filters)
+
+    const selectClause = this.buildSelect(def, options?.select)
+    let sql = `SELECT ${selectClause} FROM ${def.table}${clause}`
+
+    if (options?.orderBy) {
+      const allowed = this.getAllowedFields(def)
+      const clauses = Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy]
+      const parts = clauses.map(({ field, dir = 'ASC' }) => {
+        if (!allowed.has(field)) throw new ValidationError(`Invalid sort field: "${field}"`)
+        return `${field} ${dir === 'DESC' ? 'DESC' : 'ASC'}`
+      })
+      sql += ` ORDER BY ${parts.join(', ')}`
+    }
+
+    if (options?.limit !== undefined) {
+      sql += ` LIMIT ${Math.max(1, Math.floor(options.limit))}`
+      if (options.offset !== undefined) {
+        sql += ` OFFSET ${Math.max(0, Math.floor(options.offset))}`
+      }
+    }
+
+    return (await this.db.query(sql, params)) as ModelResult[]
+  }
+
+  async findById(name: string, id: string, select?: string[]): Promise<ModelResult | null> {
+    const def = this.getDefinition(name)
+    const selectClause = this.buildSelect(def, select)
+    let sql = `SELECT ${selectClause} FROM ${def.table} WHERE id = ?`
+    if (def.softDelete) sql += ' AND deletedAt IS NULL'
+    const rows = await this.db.query(sql, [id])
+    return (rows as ModelResult[])[0] ?? null
+  }
+
+  async findOne(name: string, filters: Record<string, unknown>): Promise<ModelResult | null> {
+    const results = await this.findMany(name, filters, { limit: 1 })
+    return results[0] ?? null
+  }
+
+  async count(name: string, filters?: Record<string, unknown>): Promise<number> {
+    const def = this.getDefinition(name)
+    const { clause, params } = this.buildWhere(def, filters)
+    const rows = await this.db.query(`SELECT COUNT(*) as n FROM ${def.table}${clause}`, params)
+    return Number((rows as Array<{ n: number | string }>)[0]?.n ?? 0)
+  }
+
+  async paginate(
+    name: string,
+    filters?: Record<string, unknown>,
+    options: FindOptions & { limit: number } = { limit: 20 },
+  ): Promise<PageResult> {
+    const limit = Math.max(1, Math.floor(options.limit))
+    const offset = Math.max(0, Math.floor(options.offset ?? 0))
+
+    const [data, total] = await Promise.all([
+      this.findMany(name, filters, { ...options, limit, offset }),
+      this.count(name, filters),
+    ])
+
+    return { data, total, limit, offset, pages: Math.ceil(total / limit) }
+  }
+
+  async create(name: string, data: Record<string, unknown>): Promise<ModelResult> {
+    const def = this.getDefinition(name)
+    const allowedFields = new Set(Object.keys(def.fields))
+    const id = crypto.randomUUID()
+    const now = new Date().toISOString()
+
+    const record: Record<string, unknown> = { id }
+    for (const [k, v] of Object.entries(data)) {
+      if (allowedFields.has(k)) record[k] = v
+    }
+    if (def.timestamps) {
+      record.createdAt = now
+      record.updatedAt = now
+    }
+
+    const keys = Object.keys(record)
+    const values = Object.values(record)
+    const placeholders = keys.map(() => '?').join(', ')
+
+    await this.db.run(
+      `INSERT INTO ${def.table} (${keys.join(', ')}) VALUES (${placeholders})`,
+      values,
+    )
+
+    return record as ModelResult
+  }
+
+  async update(name: string, id: string, data: Record<string, unknown>): Promise<ModelResult | null> {
+    const def = this.getDefinition(name)
+    const now = new Date().toISOString()
+
+    const record = { ...data }
+    if (def.timestamps) record.updatedAt = now
+
+    const keys = Object.keys(record)
+    const values = Object.values(record)
+    const setClause = keys.map(k => `${k} = ?`).join(', ')
+
+    await this.db.run(`UPDATE ${def.table} SET ${setClause} WHERE id = ?`, [...values, id])
+    return this.findById(name, id)
+  }
+
+  async delete(name: string, id: string): Promise<boolean> {
+    const def = this.getDefinition(name)
+
+    if (def.softDelete) {
+      const result = await this.db.run(`UPDATE ${def.table} SET deletedAt = ? WHERE id = ?`, [new Date().toISOString(), id])
+      return result.changes > 0
+    }
+
+    const result = await this.db.run(`DELETE FROM ${def.table} WHERE id = ?`, [id])
+    return result.changes > 0
+  }
+
+  // ── Bulk operations ──
+
+  /**
+   * Inserta múltiples registros en una sola query + transacción.
+   * Mucho más eficiente que N llamadas a create().
+   * Retorna todos los registros creados con sus IDs generados.
+   */
+  async createMany(name: string, records: Record<string, unknown>[]): Promise<ModelResult[]> {
+    if (records.length === 0) return []
+    const def = this.getDefinition(name)
+    const allowedFields = new Set(Object.keys(def.fields))
+    const now = new Date().toISOString()
+
+    const prepared = records.map(data => {
+      const record: Record<string, unknown> = { id: crypto.randomUUID() }
+      for (const [k, v] of Object.entries(data)) {
+        if (allowedFields.has(k)) record[k] = v
+      }
+      if (def.timestamps) { record.createdAt = now; record.updatedAt = now }
+      return record
+    })
+
+    const keys = Object.keys(prepared[0] ?? {})
+    const rowPlaceholders = `(${keys.map(() => '?').join(', ')})`
+    const allPlaceholders = prepared.map(() => rowPlaceholders).join(', ')
+    const allValues = prepared.flatMap(r => Object.values(r))
+
+    await this.db.run(
+      `INSERT INTO ${def.table} (${keys.join(', ')}) VALUES ${allPlaceholders}`,
+      allValues,
+    )
+
+    return prepared as ModelResult[]
+  }
+
+  /**
+   * Actualiza todos los registros que coincidan con los filtros.
+   * Retorna la cantidad de filas afectadas.
+   */
+  async updateMany(
+    name: string,
+    filters: Record<string, unknown>,
+    changes: Record<string, unknown>,
+  ): Promise<number> {
+    const def = this.getDefinition(name)
+    const { clause, params: whereParams } = this.buildWhere(def, filters)
+    const now = new Date().toISOString()
+
+    const data = { ...changes }
+    if (def.timestamps) data.updatedAt = now
+
+    const setClause = Object.keys(data).map(k => `${k} = ?`).join(', ')
+    const result = await this.db.run(
+      `UPDATE ${def.table} SET ${setClause}${clause}`,
+      [...Object.values(data), ...whereParams],
+    )
+    return result.changes
+  }
+
+  /**
+   * Elimina (o soft-delete) todos los registros que coincidan con los filtros.
+   * Retorna la cantidad de filas afectadas.
+   */
+  async deleteMany(name: string, filters: Record<string, unknown>): Promise<number> {
+    if (Object.keys(filters).length === 0) {
+      throw new ValidationError('deleteMany requires at least one filter to avoid deleting the entire table')
+    }
+    const def = this.getDefinition(name)
+    const { clause, params } = this.buildWhere(def, filters)
+
+    if (def.softDelete) {
+      const result = await this.db.run(
+        `UPDATE ${def.table} SET deletedAt = ?${clause}`,
+        [new Date().toISOString(), ...params],
+      )
+      return result.changes
+    }
+
+    const result = await this.db.run(`DELETE FROM ${def.table}${clause}`, params)
+    return result.changes
+  }
+
+  // ── Migraciones (inicialización de schema) ──
+  // Crea tablas si no existen y altera columnas faltantes.
+  // Para migraciones complejas, usar herramientas externas (knex, drizzle).
+
+  static readonly SCHEMA_TABLE = '_arckode_schema'
+
+  private assertSafeIdentifier(value: string, context: string): void {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(value)) {
+      throw new ValidationError(`Invalid SQL identifier in ${context}: "${value}". Only letters, numbers and underscores.`)
+    }
+  }
+
+  async migrate(): Promise<void> {
+    // _arckode_migrations es propiedad exclusiva de db:migrate (migraciones SQL manuales).
+    // ORM.migrate() usa _arckode_schema para rastrear qué tablas auto-migró.
+    await this.db.run(
+      `CREATE TABLE IF NOT EXISTS _arckode_schema (table_name TEXT PRIMARY KEY, migratedAt TEXT)`
+    )
+
+    for (const [modelName, def] of this.models) {
+      // Validar nombres de tabla y campos antes de cualquier SQL
+      this.assertSafeIdentifier(def.table, `modelo "${modelName}" → table`)
+      for (const fieldName of Object.keys(def.fields)) {
+        this.assertSafeIdentifier(fieldName, `modelo "${modelName}" → campo`)
+      }
+
+      // 1. Crear tabla si no existe
+      const columns = Object.entries(def.fields).map(([name, field]) => {
+        const sqlType = this.fieldTypeToSQL(field.type)
+        const parts = [name, sqlType]
+
+        if (name === 'id') parts.push('PRIMARY KEY')
+        if (field.required) parts.push('NOT NULL')
+        if (field.unique) parts.push('UNIQUE')
+        if (field.default !== undefined) {
+          parts.push(`DEFAULT ${typeof field.default === 'string' ? `'${field.default}'` : field.default}`)
+        }
+
+        return parts.join(' ')
+      })
+
+      if (def.timestamps) {
+        columns.push('createdAt TEXT')
+        columns.push('updatedAt TEXT')
+      }
+
+      if (def.softDelete) {
+        columns.push('deletedAt TEXT')
+      }
+
+      await this.db.run(
+        `CREATE TABLE IF NOT EXISTS ${def.table} (${columns.join(', ')})`
+      )
+
+      // 2. Crear índices para campos con indexed: true
+      for (const [fieldName, field] of Object.entries(def.fields)) {
+        if (field.indexed && !field.unique) {
+          const idxName = `idx_${def.table}_${fieldName}`
+          try {
+            await this.db.run(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${def.table}(${fieldName})`)
+          } catch { /* índice ya existe o adaptador no soporta */ }
+        }
+      }
+
+      // 3. Agregar columnas nuevas que no existen en la tabla
+      // Solución portable: intentar ALTER TABLE y silenciar el error "ya existe"
+      for (const [name, field] of Object.entries(def.fields)) {
+        const sqlType = this.fieldTypeToSQL(field.type)
+        try {
+          await this.db.run(`ALTER TABLE ${def.table} ADD COLUMN ${name} ${sqlType}`)
+        } catch {
+          // Error esperado: la columna ya existe — ignorar
+        }
+      }
+
+      // 4. Detectar drift de schema: columnas en la BD que ya no están en el modelo
+      const definedCols = new Set([
+        'id',
+        ...Object.keys(def.fields),
+        ...(def.timestamps ? ['createdAt', 'updatedAt'] : []),
+        ...(def.softDelete ? ['deletedAt'] : []),
+      ])
+
+      const dbCols = await this.getTableColumns(def.table)
+
+      for (const col of dbCols) {
+        if (definedCols.has(col)) continue
+
+        // Intentar DROP COLUMN (SQLite ≥ 3.35.0 y Postgres lo soportan)
+        try {
+          await this.db.run(`ALTER TABLE ${def.table} DROP COLUMN ${col}`)
+          console.warn(
+            `[arckode/migrate] Column "${col}" dropped from "${def.table}" — no longer in model`
+          )
+        } catch {
+          console.warn(
+            `[arckode/migrate] ⚠  Orphan column "${col}" in table "${def.table}" — ` +
+            `not in model but could not be auto-dropped. ` +
+            `Create a manual migration: arckode make:migration drop_${col}_from_${def.table}`
+          )
+        }
+      }
+    }
+  }
+
+  // Introspección portable: SQLite usa PRAGMA, Postgres usa information_schema
+  private async getTableColumns(table: string): Promise<string[]> {
+    // SQLite
+    try {
+      const rows = await this.db.query(`PRAGMA table_info(${table})`)
+      if (Array.isArray(rows) && rows.length > 0 && 'name' in (rows[0] as object)) {
+        return (rows as { name: string }[]).map(r => r.name)
+      }
+    } catch { /* no es SQLite o PRAGMA no disponible */ }
+
+    // Postgres / estándar SQL
+    try {
+      const rows = await this.db.query(
+        `SELECT column_name FROM information_schema.columns WHERE table_name = '${table}'`
+      )
+      if (Array.isArray(rows) && rows.length > 0) {
+        return (rows as { column_name: string }[]).map(r => r.column_name)
+      }
+    } catch { /* adaptador no soporta introspección */ }
+
+    return []
+  }
+
+  private fieldTypeToSQL(type: FieldDefinition['type']): string {
+    const map: Record<FieldDefinition['type'], string> = {
+      string: 'TEXT',
+      number: 'REAL',
+      boolean: 'INTEGER',
+      json: 'TEXT',
+      date: 'TEXT',
+    }
+    return map[type]
+  }
+}
+
+// ── OrmRepository<T> — Adaptador SQL del ORM a RepositoryAdapter<T> ──
+//
+// Uso en composition-root.ts:
+//   const productoRepo = new OrmRepository<ProductoDTO>(orm, 'Producto')
+//   const service = new ProductoService(productoRepo)   // service depende de RepositoryAdapter, no ORM
+//
+// Para reemplazar con MongoDB, Prisma, etc.:
+//   class MongoProductoRepo implements RepositoryAdapter<ProductoDTO> { ... }
+//   const productoRepo = new MongoProductoRepo(mongoCollection)
+//   // El service NO cambia.
+
+export class OrmRepository<T extends object = Record<string, unknown>>
+  implements RepositoryAdapter<T> {
+  constructor(
+    private readonly orm: ORM,
+    private readonly modelName: string,
+  ) {}
+
+  findMany(filters?: Record<string, unknown>, options?: FindOptions): Promise<T[]> {
+    return this.orm.findMany(this.modelName, filters, options) as unknown as Promise<T[]>
+  }
+
+  findById(id: string, select?: string[]): Promise<T | null> {
+    return this.orm.findById(this.modelName, id, select) as unknown as Promise<T | null>
+  }
+
+  findOne(filters: Record<string, unknown>): Promise<T | null> {
+    return this.orm.findOne(this.modelName, filters) as unknown as Promise<T | null>
+  }
+
+  create(data: Omit<T, 'id'>): Promise<T> {
+    return this.orm.create(this.modelName, data as Record<string, unknown>) as unknown as Promise<T>
+  }
+
+  update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null> {
+    return this.orm.update(this.modelName, id, data as Record<string, unknown>) as unknown as Promise<T | null>
+  }
+
+  delete(id: string): Promise<boolean> {
+    return this.orm.delete(this.modelName, id)
+  }
+
+  count(filters?: Record<string, unknown>): Promise<number> {
+    return this.orm.count(this.modelName, filters)
+  }
+
+  paginate(
+    filters?: Record<string, unknown>,
+    options: FindOptions & { limit: number } = { limit: 20 },
+  ): Promise<PageResult<T>> {
+    return this.orm.paginate(this.modelName, filters, options) as unknown as Promise<PageResult<T>>
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 6. ROUTER + HTTP — Enrutamiento con middlewares y error handler
+// ═══════════════════════════════════════════════════════════════
+
+export interface HttpRequest {
+  id: string
+  method: string
+  path: string
+  params: Record<string, string>
+  query: Record<string, string>
+  headers: Record<string, string>
+  body: unknown
+  user?: { id: string; role: string }
+}
+
+export interface HttpResponse {
+  status: number
+  body?: unknown
+  headers?: Record<string, string>
+  /** SSE / streaming: async generator que emite chunks de texto plano */
+  stream?: AsyncGenerator<string>
+}
+
+/** Helper: crea una respuesta SSE a partir de un async generator.
+ *  Cada valor yielded se envía como `data: <valor>\n\n`.
+ *  Para eventos con tipo: yield `event: nombre\ndata: payload\n\n` */
+export function sseResponse(
+  generator: AsyncGenerator<string>,
+  headers?: Record<string, string>,
+): HttpResponse {
+  return {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      ...headers,
+    },
+    stream: generator,
+  }
+}
+
+export type RouteHandler = (req: HttpRequest) => HttpResponse | Promise<HttpResponse>
+export type MiddlewareHandler = (req: HttpRequest, next: () => Promise<HttpResponse>) => Promise<HttpResponse>
+
+interface RouteEntry {
+  method: string
+  pattern: RegExp
+  paramNames: string[]
+  handler: RouteHandler
+  middlewares: MiddlewareHandler[]
+}
+
+export class Router {
+  private routes: RouteEntry[] = []
+  private globalMiddlewares: MiddlewareHandler[] = []
+  private logger?: Logger
+
+  setLogger(logger: Logger): void { this.logger = logger }
+
+  use(middleware: MiddlewareHandler): void {
+    this.globalMiddlewares.push(middleware)
+  }
+
+  private add(method: string, path: string, handler: RouteHandler, middlewares: MiddlewareHandler[] = []): void {
+    const paramNames: string[] = []
+    const parts = path.split('/').filter(Boolean)
+    const regexParts = parts.map(part => {
+      if (part.startsWith(':')) {
+        const rawName = part.slice(1)
+        if (rawName.endsWith('(*)')) {
+          paramNames.push(rawName.slice(0, -3))
+          return '(.*)'
+        }
+        paramNames.push(rawName)
+        return '([^/]+)'
+      }
+      return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    })
+
+    this.routes.push({
+      method,
+      pattern: new RegExp(`^/${regexParts.join('/')}/?$`),
+      paramNames,
+      handler,
+      middlewares,
+    })
+  }
+
+  get(path: string, handler: RouteHandler, mw?: MiddlewareHandler[]): void { this.add('GET', path, handler, mw) }
+  post(path: string, handler: RouteHandler, mw?: MiddlewareHandler[]): void { this.add('POST', path, handler, mw) }
+  put(path: string, handler: RouteHandler, mw?: MiddlewareHandler[]): void { this.add('PUT', path, handler, mw) }
+  patch(path: string, handler: RouteHandler, mw?: MiddlewareHandler[]): void { this.add('PATCH', path, handler, mw) }
+  delete(path: string, handler: RouteHandler, mw?: MiddlewareHandler[]): void { this.add('DELETE', path, handler, mw) }
+  options(path: string, handler: RouteHandler, mw?: MiddlewareHandler[]): void { this.add('OPTIONS', path, handler, mw) }
+
+  async resolve(method: string, path: string, extras?: Partial<HttpRequest>): Promise<HttpResponse> {
+    const reqId = crypto.randomUUID().slice(0, 8)
+
+    // Helper para construir HttpRequest y ejecutar middlewares
+    const buildRequest = (route: RouteEntry, match: RegExpMatchArray): HttpRequest => {
+      const params: Record<string, string> = {}
+      route.paramNames.forEach((name, i) => { params[name] = decodeURIComponent(match[i + 1] ?? '') })
+      return {
+        id: reqId,
+        method,
+        path,
+        params,
+        query: extras?.query ?? {},
+        headers: extras?.headers ?? {},
+        body: extras?.body ?? null,
+        user: extras?.user,
+      }
+    }
+
+    const runAll = async (req: HttpRequest, routeMiddlewares: MiddlewareHandler[], routeHandler: RouteHandler): Promise<HttpResponse> => {
+      const allMiddlewares = [...this.globalMiddlewares, ...routeMiddlewares]
+      let index = 0
+      const next = async (): Promise<HttpResponse> => {
+        if (index < allMiddlewares.length) {
+          const mw = allMiddlewares[index++]!
+          return mw(req, next)
+        }
+        return routeHandler(req)
+      }
+      try {
+        return await next()
+      } catch (error) {
+        if (error instanceof ErrorContract) {
+          return { status: error.httpStatus, body: error.toJSON() }
+        }
+        if (this.logger) {
+          const stack = error instanceof Error ? error.stack : String(error)
+          this.logger.error(`Unhandled error in ${method} ${path}`, { stack, requestId: reqId })
+        }
+        return { status: 500, body: { error: 'Error interno del servidor', code: 'INTERNAL_ERROR' } }
+      }
+    }
+
+    if (method === 'OPTIONS') {
+      // CORS preflight: buscar cualquier ruta que matchee la path (ignorando método)
+      let anyMatch: { route: RouteEntry; match: RegExpMatchArray } | null = null
+      for (const route of this.routes) {
+        const m = path.match(route.pattern)
+        if (m) { anyMatch = { route, match: m }; break }
+      }
+      if (anyMatch) {
+        const req = buildRequest(anyMatch.route, anyMatch.match)
+        return runAll(req, [], () => Promise.resolve({ status: 204, body: null }))
+      }
+    }
+
+    for (const route of this.routes) {
+      if (route.method !== method) continue
+      const match = path.match(route.pattern)
+      if (!match) continue
+
+      const req = buildRequest(route, match)
+      return runAll(req, route.middlewares, route.handler)
+    }
+
+    return { status: 404, body: { error: 'Route not found', code: 'NOT_FOUND' } }
+
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 7. HTTP SERVER — Adapter de Node HTTP
+// ═══════════════════════════════════════════════════════════════
+
+import { createServer as createNodeServer, IncomingMessage, ServerResponse } from 'node:http'
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+// ── Request Context — propagación transparente del requestId ──
+// Accesible desde cualquier punto del call-stack async sin pasar props manualmente.
+// Útil en services, adapters externos, logs, y tracing distribuido.
+export const requestStorage = new AsyncLocalStorage<{ requestId: string; startTime: number }>()
+
+/** Retorna el requestId del request activo o undefined si no hay contexto HTTP activo */
+export function getRequestId(): string | undefined {
+  return requestStorage.getStore()?.requestId
+}
+
+/** Retorna el tiempo transcurrido (ms) desde que inició el request activo */
+export function getRequestElapsed(): number | undefined {
+  const store = requestStorage.getStore()
+  return store ? Date.now() - store.startTime : undefined
+}
+
+export interface ServerAdapter {
+  start(handler: (req: HttpRequest) => Promise<HttpResponse>): Promise<void>
+  stop(): Promise<void>
+}
+
+export class NodeServer implements ServerAdapter {
+  private server?: ReturnType<typeof createNodeServer>
+  private maxBodyBytes: number
+  private drainTimeoutMs: number
+  private activeRequests = 0
+
+  constructor(
+    private port: number,
+    private logger: Logger,
+    opts: { maxBodyBytes?: number; drainTimeoutMs?: number } = {},
+  ) {
+    this.maxBodyBytes = opts.maxBodyBytes ?? 10 * 1024 * 1024 // 10MB default
+    this.drainTimeoutMs = opts.drainTimeoutMs ?? 30_000
+  }
+
+  async start(handler: (req: HttpRequest) => Promise<HttpResponse>): Promise<void> {
+    return new Promise((resolve) => {
+      this.server = createNodeServer(async (nodeReq: IncomingMessage, nodeRes: ServerResponse) => {
+        this.activeRequests++
+        const requestId = crypto.randomUUID().slice(0, 8)
+
+        await requestStorage.run({ requestId, startTime: Date.now() }, async () => {
+          try {
+            const body = await this.readBody(nodeReq, this.maxBodyBytes)
+
+            const url = new URL(nodeReq.url ?? '/', `http://${nodeReq.headers.host ?? 'localhost'}`)
+            const query: Record<string, string> = {}
+            url.searchParams.forEach((value, key) => { query[key] = value })
+
+            const req: HttpRequest = {
+              id: requestId,
+              method: nodeReq.method ?? 'GET',
+              path: url.pathname,
+              params: {},
+              query,
+              headers: nodeReq.headers as Record<string, string>,
+              body,
+            }
+
+            const res = await handler(req)
+
+            // ── Streaming / SSE ──────────────────────────────
+            if (res.stream) {
+              nodeRes.writeHead(res.status, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+                'X-Request-Id': req.id,
+                ...res.headers,
+              })
+              try {
+                for await (const chunk of res.stream) {
+                  nodeRes.write(`data: ${chunk}\n\n`)
+                }
+              } finally {
+                nodeRes.end()
+              }
+              return
+            }
+
+            // ── Respuesta normal (JSON o binario comprimido) ──
+            const isBuffer = Buffer.isBuffer(res.body)
+            const responseBody = isBuffer ? res.body : JSON.stringify(res.body)
+            nodeRes.writeHead(res.status, {
+              'Content-Type': 'application/json',
+              'X-Request-Id': req.id,
+              ...res.headers,
+            })
+            nodeRes.end(responseBody)
+          } catch (error) {
+            const httpStatus = (error as any)?.httpStatus
+            if (httpStatus) {
+              nodeRes.writeHead(httpStatus, { 'Content-Type': 'application/json' })
+              nodeRes.end(JSON.stringify({ error: (error as Error).message, code: 'REQUEST_ERROR' }))
+              return
+            }
+            const stack = error instanceof Error ? error.stack : String(error)
+            this.logger.error('Error no manejado en HTTP', { error: String(error), stack })
+            nodeRes.writeHead(500, { 'Content-Type': 'application/json' })
+            nodeRes.end(JSON.stringify({ error: 'Error interno', code: 'INTERNAL_ERROR' }))
+          } finally {
+            this.activeRequests--
+          }
+        })
+      })
+
+      this.server.listen(this.port, () => {
+        this.logger.info(`Servidor HTTP escuchando en :${this.port}`)
+        resolve()
+      })
+    })
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      let resolved = false
+      const done = () => { if (!resolved) { resolved = true; resolve() } }
+
+      // Deja de aceptar conexiones nuevas; resuelve cuando todos los sockets cierran
+      this.server?.close(done)
+
+      // Espera que los requests en vuelo terminen (con deadline)
+      const deadline = Date.now() + this.drainTimeoutMs
+      const poll = setInterval(() => {
+        if (this.activeRequests === 0 || Date.now() >= deadline) {
+          clearInterval(poll)
+          if (this.activeRequests > 0) {
+            this.logger.warn(`Graceful shutdown: ${this.activeRequests} request(s) sin terminar, forzando cierre`)
+          }
+          done()
+        }
+      }, 50)
+    })
+  }
+
+  /** Retorna el puerto real asignado (útil cuando port=0 en tests) */
+  getPort(): number {
+    const addr = this.server?.address()
+    return typeof addr === 'object' && addr ? addr.port : this.port
+  }
+
+  private readBody(req: IncomingMessage, maxBytes = 10 * 1024 * 1024): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = []
+      let total = 0
+
+      req.on('data', (chunk: Buffer) => {
+        total += chunk.length
+        if (total > maxBytes) {
+          req.destroy()
+          reject(Object.assign(new Error('Payload Too Large'), { httpStatus: 413 }))
+          return
+        }
+        chunks.push(chunk)
+      })
+
+      req.on('end', () => {
+        const raw = Buffer.concat(chunks).toString()
+        if (!raw) return resolve(null)
+        try { resolve(JSON.parse(raw)) } catch { resolve(raw) }
+      })
+
+      req.on('error', reject)
+    })
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 8. VALIDADOR — Schemas planos, sin dependencias
+// ═══════════════════════════════════════════════════════════════
+
+export type ValidatorType = 'string' | 'number' | 'boolean' | 'email' | 'url' | 'date'
+
+export interface ValidationRule {
+  type: ValidatorType
+  required?: boolean
+  min?: number
+  max?: number
+  pattern?: RegExp
+  enum?: string[]
+  message?: string
+  /** true = trim + colapsar espacios. 'html' = trim + escapar caracteres HTML peligrosos */
+  sanitize?: boolean | 'html'
+}
+
+export type ValidationSchema = Record<string, ValidationRule>
+
+export function validateSchema(schema: ValidationSchema, input: unknown): Record<string, unknown> {
+  const errors: Record<string, string[]> = {}
+  const output: Record<string, unknown> = {}
+
+  if (typeof input !== 'object' || input === null) {
+    throw new ValidationError('Request body must be an object')
+  }
+
+  const data = input as Record<string, unknown>
+
+  for (const [field, rule] of Object.entries(schema)) {
+    const value = data[field]
+    const fieldErrors: string[] = []
+
+    if (value === undefined || value === null) {
+      if (rule.required) {
+        fieldErrors.push(rule.message ?? `${field} is required`)
+        errors[field] = fieldErrors
+      }
+      continue
+    }
+
+    switch (rule.type) {
+      case 'string': {
+        if (typeof value !== 'string') {
+          fieldErrors.push(`${field} must be a string`)
+        } else {
+          let sanitized = value.trim().replace(/\s+/g, ' ')
+          if (rule.sanitize === 'html') {
+            sanitized = sanitized
+              .replace(/&/g, '&amp;')
+              .replace(/</g, '&lt;')
+              .replace(/>/g, '&gt;')
+              .replace(/"/g, '&quot;')
+              .replace(/'/g, '&#x27;')
+          }
+          if (rule.min !== undefined && sanitized.length < rule.min) fieldErrors.push(`Minimum ${rule.min} characters`)
+          if (rule.max !== undefined && sanitized.length > rule.max) fieldErrors.push(`Maximum ${rule.max} characters`)
+          if (rule.pattern && !rule.pattern.test(sanitized)) fieldErrors.push(rule.message ?? `Invalid format`)
+          if (rule.enum && !rule.enum.includes(sanitized)) fieldErrors.push(`Must be one of: ${rule.enum.join(', ')}`)
+          output[field] = sanitized
+        }
+        break
+      }
+      case 'number': {
+        const num = typeof value === 'string' ? Number(value) : value
+        if (typeof num !== 'number' || isNaN(num)) {
+          fieldErrors.push(`${field} must be a number`)
+        } else {
+          if (rule.min !== undefined && num < rule.min) fieldErrors.push(`Minimum ${rule.min}`)
+          if (rule.max !== undefined && num > rule.max) fieldErrors.push(`Maximum ${rule.max}`)
+          output[field] = num
+        }
+        break
+      }
+      case 'boolean': {
+        if (typeof value !== 'boolean') {
+          fieldErrors.push(`${field} must be a boolean`)
+        } else {
+          output[field] = value
+        }
+        break
+      }
+      case 'email': {
+        if (typeof value !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
+          fieldErrors.push(rule.message ?? `${field} is not a valid email`)
+        } else {
+          output[field] = value
+        }
+        break
+      }
+      case 'url': {
+        if (typeof value !== 'string') { fieldErrors.push(`${field} must be a string`) }
+        else {
+          try { new URL(value); output[field] = value } catch { fieldErrors.push(rule.message ?? `${field} is not a valid URL`) }
+        }
+        break
+      }
+      case 'date': {
+        if (typeof value !== 'string' || isNaN(Date.parse(value))) {
+          fieldErrors.push(rule.message ?? `${field} is not a valid date`)
+        } else {
+          output[field] = value
+        }
+        break
+      }
+    }
+
+    if (fieldErrors.length > 0) {
+      errors[field] = fieldErrors
+    }
+  }
+
+  if (Object.keys(errors).length > 0) {
+    throw new ValidationError('Validation error', errors)
+  }
+
+  return output
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 9. AUTH — JWT con adapter, middleware de roles
+// ═══════════════════════════════════════════════════════════════
+
+export interface JwtAdapter {
+  sign(payload: Record<string, unknown>, secret: string, expiresIn: string): string
+  verify(token: string, secret: string): Record<string, unknown>
+}
+
+export class Auth {
+  private readonly refreshSecret: string
+
+  constructor(
+    private jwt: JwtAdapter,
+    private secret: string,
+    private logger: Logger,
+    private expiresIn: string = '24h',
+    private refreshExpiresIn: string = '30d',
+  ) {
+    // Refresh secret derivado: distinto al access secret para no reutilizar tokens
+    this.refreshSecret = secret + '__refresh__'
+  }
+
+  createToken(payload: { id: string; role: string }, expiresIn?: string): string {
+    const ttl = expiresIn ?? this.expiresIn
+    const token = this.jwt.sign({ id: payload.id, role: payload.role, type: 'access' }, this.secret, ttl)
+    this.logger.debug('Token creado', { userId: payload.id, expiresIn: ttl })
+    return token
+  }
+
+  createRefreshToken(payload: { id: string; role: string }): string {
+    const token = this.jwt.sign(
+      { id: payload.id, role: payload.role, type: 'refresh' },
+      this.refreshSecret,
+      this.refreshExpiresIn,
+    )
+    this.logger.debug('Refresh token creado', { userId: payload.id })
+    return token
+  }
+
+  /** Verifica un refresh token y devuelve un nuevo access token + nuevo refresh token */
+  refresh(refreshToken: string): { accessToken: string; refreshToken: string } {
+    try {
+      const payload = this.jwt.verify(refreshToken, this.refreshSecret)
+      if (payload.type !== 'refresh') throw new AuthError('Invalid token type')
+      const user = { id: payload.id as string, role: payload.role as string }
+      return {
+        accessToken: this.createToken(user),
+        refreshToken: this.createRefreshToken(user),
+      }
+    } catch (e) {
+      if (e instanceof AuthError) throw e
+      throw new AuthError('Invalid or expired refresh token')
+    }
+  }
+
+  verifyToken(token: string): { id: string; role: string } {
+    try {
+      const payload = this.jwt.verify(token, this.secret)
+      // Un refresh token NO puede usarse como access token
+      if (payload.type === 'refresh') throw new AuthError('Invalid token type')
+      return { id: payload.id as string, role: payload.role as string }
+    } catch (e) {
+      if (e instanceof AuthError) throw e
+      throw new AuthError('Invalid or expired token')
+    }
+  }
+
+  authenticate(...allowedRoles: string[]): MiddlewareHandler {
+    return async (req, next) => {
+      const header = req.headers['authorization']
+      if (!header?.startsWith('Bearer ')) {
+        throw new AuthError('Authentication token required')
+      }
+
+      const user = this.verifyToken(header.slice(7))
+
+      if (allowedRoles.length > 0 && !allowedRoles.includes(user.role)) {
+        throw new ForbiddenError(`Required role: ${allowedRoles.join(' or ')}`)
+      }
+
+      req.user = user
+      return next()
+    }
+  }
+
+  /**
+   * Verifica que el usuario autenticado sea el dueño del recurso.
+   * Previene IDOR (Insecure Direct Object Reference).
+   * Los admins (adminRole) pueden acceder a cualquier recurso.
+   *
+   * @example
+   * const pedido = await orm.findById('Pedido', id)
+   * if (!pedido) throw new NotFoundError('Pedido no encontrado')
+   * auth.assertOwnership(pedido.userId as string, req.user!.id, req.user!.role)
+   * // → solo el dueño o un admin puede continuar
+   */
+  assertOwnership(
+    resourceOwnerId: string,
+    requestingUserId: string,
+    requestingUserRole?: string,
+    adminRole = 'admin',
+  ): void {
+    if (requestingUserId === resourceOwnerId) return
+    if (requestingUserRole === adminRole) return
+    throw new ForbiddenError('Forbidden: resource belongs to another user')
+  }
+
+  /**
+   * Hashea una contraseña con scrypt + salt aleatorio.
+   * Usa node:crypto — cero dependencias externas.
+   * Resultado: "salt:hash" (ambos en hex).
+   *
+   * @example
+   * const hash = await auth.hashPassword('miPassword123')
+   * // Guardar hash en DB, nunca el password plano
+   */
+  async hashPassword(password: string): Promise<string> {
+    const { scrypt, randomBytes } = await import('node:crypto')
+    const salt = randomBytes(16).toString('hex')
+    const hash = await new Promise<Buffer>((resolve, reject) =>
+      scrypt(password, salt, 64, (err, key) => (err ? reject(err) : resolve(key))),
+    )
+    return `${salt}:${hash.toString('hex')}`
+  }
+
+  /**
+   * Compara un password en plano contra un hash generado por hashPassword().
+   * Usa timingSafeEqual para prevenir timing attacks.
+   *
+   * @example
+   * const ok = await auth.comparePassword('miPassword123', usuario.passwordHash)
+   * if (!ok) throw new AuthError('Invalid credentials')
+   */
+  async comparePassword(password: string, stored: string): Promise<boolean> {
+    const { scrypt, timingSafeEqual } = await import('node:crypto')
+    const [salt, hash] = stored.split(':')
+    if (!salt || !hash) return false
+    const storedBuf = Buffer.from(hash, 'hex')
+    const attempt = await new Promise<Buffer>((resolve, reject) =>
+      scrypt(password, salt, 64, (err, key) => (err ? reject(err) : resolve(key))),
+    )
+    return timingSafeEqual(storedBuf, attempt)
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 10. CACHE — En memoria, interfaz para reemplazar por Redis
+// ═══════════════════════════════════════════════════════════════
+
+export interface CacheAdapter {
+  get<T>(key: string): Promise<T | null>
+  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>
+  delete(key: string): Promise<void>
+  flush(): Promise<void>
+}
+
+export class MemoryCache implements CacheAdapter {
+  private store = new Map<string, { value: unknown; expiresAt: number }>()
+  private hits = 0
+  private misses = 0
+
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.store.get(key)
+    if (!entry) { this.misses++; return null }
+    if (Date.now() > entry.expiresAt) { this.store.delete(key); this.misses++; return null }
+    this.hits++
+    return entry.value as T
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds = 3600): Promise<void> {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 })
+  }
+
+  async delete(key: string): Promise<void> { this.store.delete(key) }
+  async flush(): Promise<void> { this.store.clear() }
+
+  get stats() {
+    const total = this.hits + this.misses
+    return { size: this.store.size, hits: this.hits, misses: this.misses, hitRate: total > 0 ? `${((this.hits / total) * 100).toFixed(1)}%` : '0%' }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 11. SISTEMA DE MÓDULOS — El corazón de la arquitectura
+// ═══════════════════════════════════════════════════════════════
+
+// ── Contrato que un módulo EXPONE hacia afuera ──
+export interface ModuleContract {
+  name: string
+  version: string
+  description: string
+  actions: string[]
+  events: string[]
+  tables: string[]
+  dependencies: string[]
+  rules: string[]
+}
+
+// ── Dependencias que un módulo RECIBE ──
+export interface ModuleDependencies {
+  logger: Logger
+  orm: ORM
+  router: Router
+  config: ConfigStore
+  cache: CacheAdapter
+  auth?: Auth
+}
+
+// ── Interfaz opcional para módulos que aceptan sockets post-init ──
+export interface SocketsAware {
+  setSockets(sockets: Record<string, unknown>): void
+}
+
+// ── Definición de un módulo ──
+export interface ModuleDefinition<TModule> {
+  name: string
+  version: string
+  description: string
+  contract: ModuleContract
+  create(deps: ModuleDependencies): TModule
+  validate?(instance: TModule): void
+  /** Hook de cierre: se llama en system.stop(). Cerrar conexiones, detener timers, etc. */
+  onStop?(instance: TModule): Promise<void>
+}
+
+// ── Crea un módulo con validación de contrato ──
+export function createModule<T>(def: ModuleDefinition<T>): ModuleDefinition<T> {
+  return def
+}
+
+// ── Tipos para conectores ──
+export interface ConnectorContext {
+  resolveModule<T>(name: string, sockets?: Record<string, unknown>): T
+  /** Los sockets se asignan al módulo ANTES de su inicialización.
+   *  Internamente el módulo recibe los sockets vía ModuleDependencies.
+   *  Para acceder a sockets después de init, el módulo debe aceptarlos
+   *  en su factory (create) y guardarlos internamente. */
+}
+
+export type ConnectorDefinition = (ctx: ConnectorContext) => void | Promise<void>
+
+// ── SISTEMA ──
+export class System {
+  public readonly logger: Logger
+  public readonly config: ConfigStore
+  public readonly container: Container
+  public readonly orm: ORM
+  public readonly router: Router
+  public readonly http: ServerAdapter
+  public readonly cache: CacheAdapter
+  public readonly auth?: Auth
+
+  private modules = new Map<string, { definition: ModuleDefinition<unknown>; instance: unknown; sockets?: Record<string, unknown> }>()
+  private connectors: { name: string; fn: ConnectorDefinition }[] = []
+  private pendingSockets = new Map<string, Record<string, unknown>>()
+  private initialized = false
+
+  constructor(params: {
+    config: ConfigStore
+    container: Container
+    logger: Logger
+    orm: ORM
+    router: Router
+    http: ServerAdapter
+    cache: CacheAdapter
+    auth?: Auth
+  }) {
+    this.config = params.config
+    this.container = params.container
+    this.logger = params.logger
+    this.orm = params.orm
+    this.router = params.router
+    this.http = params.http
+    this.cache = params.cache
+    this.auth = params.auth
+  }
+
+  addModule<T>(definition: ModuleDefinition<T>): this {
+    if (this.initialized) throw new InternalError(`Cannot add module "${definition.name}" after initialization`)
+    this.modules.set(definition.name, { definition, instance: undefined })
+    return this
+  }
+
+  addConnector(name: string, fn: ConnectorDefinition): this {
+    this.connectors.push({ name, fn })
+    return this
+  }
+
+  resolveModule<T>(name: string): T {
+    const entry = this.modules.get(name)
+    if (!entry?.instance) throw new NotFoundError(`Module "${name}" not found or not initialized`)
+    return entry.instance as T
+  }
+
+  getModule<T>(name: string): T {
+    return this.resolveModule<T>(name)
+  }
+
+  init(): void {
+    if (this.initialized) return
+    this.initialized = true
+
+    // 1. Inicializar container
+    this.container.init()
+
+    // 2. Migrar base de datos
+    // La migración se hace explícitamente desde composition-root
+
+    // 3. Inicializar módulos
+    for (const [name, entry] of this.modules) {
+      const sockets = this.pendingSockets.get(name)
+      const deps: ModuleDependencies = {
+        logger: this.logger.child(name),
+        orm: this.orm,
+        router: this.router,
+        config: this.config,
+        cache: this.cache,
+        auth: this.auth,
+      }
+
+      entry.instance = entry.definition.create(deps)
+      this.logger.info(`Module initialized: ${name} v${entry.definition.version}`)
+    }
+
+    // 4. Ejecutar conectores
+    for (const connector of this.connectors) {
+      const ctx: ConnectorContext = {
+        resolveModule: <T>(name: string, sockets?: Record<string, unknown>): T => {
+          const instance = this.resolveModule<Record<string, unknown>>(name)
+          if (sockets && typeof instance === 'object' && instance) {
+            if ('setSockets' in instance && typeof (instance as unknown as SocketsAware).setSockets === 'function') {
+              ;(instance as unknown as SocketsAware).setSockets(sockets)
+            }
+          }
+          return instance as unknown as T
+        },
+      }
+
+      connector.fn(ctx)
+      this.logger.info(`Connector executed: ${connector.name}`)
+    }
+  }
+
+  async start(): Promise<void> {
+    this.router.setLogger(this.logger)
+    this.init()
+    await this.http.start((req) => this.router.resolve(req.method, req.path, req))
+    this.logger.info('══════════════════════════════════')
+    this.logger.info('  System started successfully')
+    this.logger.info(`  Modules: ${[...this.modules.keys()].join(', ')}`)
+    this.logger.info(`  Connectors: ${this.connectors.map(c => c.name).join(', ')}`)
+    this.logger.info('══════════════════════════════════')
+  }
+
+  async stop(): Promise<void> {
+    this.logger.info('Shutting down system...')
+
+    for (const [name, entry] of this.modules) {
+      if (entry.definition.onStop && entry.instance) {
+        try {
+          await entry.definition.onStop(entry.instance)
+          this.logger.info(`Module stopped: ${name}`)
+        } catch (e) {
+          this.logger.error(`Error stopping module "${name}"`, { error: String(e) })
+        }
+      }
+    }
+
+    await this.http.stop()
+    await this.container.destroy()
+    this.logger.info('System stopped')
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 12. SEED SYSTEM — Poblar base de datos con datos de prueba
+// ═══════════════════════════════════════════════════════════════
+
+export type SeedFunction = (orm: ORM) => Promise<void>
+
+export class SeedRunner {
+  private seeds: { name: string; run: SeedFunction }[] = []
+
+  constructor(
+    private orm: ORM,
+    private logger: Logger,
+  ) {}
+
+  add(name: string, run: SeedFunction): this {
+    this.seeds.push({ name, run })
+    return this
+  }
+
+  async runAll(): Promise<void> {
+    for (const seed of this.seeds) {
+      try {
+        await seed.run(this.orm)
+        this.logger.info(`Seed executed: ${seed.name}`)
+      } catch (error) {
+        this.logger.error(`Error in seed "${seed.name}"`, { error: String(error) })
+        throw error
+      }
+    }
+  }
+
+  async runOne(name: string): Promise<void> {
+    const seed = this.seeds.find(s => s.name === name)
+    if (!seed) throw new NotFoundError(`Seed "${name}" not found`)
+
+    try {
+      await seed.run(this.orm)
+      this.logger.info(`Seed executed: ${name}`)
+    } catch (error) {
+      this.logger.error(`Error in seed "${name}"`, { error: String(error) })
+      throw error
+    }
+  }
+
+  get list(): string[] {
+    return this.seeds.map(s => s.name)
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// EXPORT
+// ═══════════════════════════════════════════════════════════════
+
+export default {
+  // Errors
+  ErrorContract, ValidationError, AuthError, ForbiddenError,
+  NotFoundError, ConflictError, RateLimitError, RepositoryError,
+  InternalError, ModuleRuleError,
+
+  // Infrastructure
+  Logger, ConsoleTransport,
+  ConfigStore, loadEnv,
+  Container,
+  ORM, OrmRepository,
+  Router, NodeServer,
+  validateSchema,
+  Auth, MemoryCache,
+
+  // Module System
+  createModule, System,
+
+  // Seeds
+  SeedRunner,
+
+  // Types (re-exported for convenience)
+  // All interfaces are exported above
+}