docs: add Spanish README

Author: webbrain-one

README.es-ES.md

@@ -0,0 +1,193 @@
+
+
+# Kumi
+
+[![CI](https://github.com/amuta/kumi/workflows/CI/badge.svg)](https://github.com/amuta/kumi/actions)
+[![Gem Version](https://badge.fury.io/rb/kumi.svg)](https://badge.fury.io/rb/kumi)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**[Prueba la demostración interactiva →](https://kumi-play-web.fly.dev/)**
+
+---
+
+## ¿Qué es Kumi?
+
+Kumi es un **DSL declarativo para lógica de cálculo** — reglas fiscales, precios, puntuaciones, proyecciones financieras — que se compila a Ruby y JavaScript planos.
+
+Declaras la forma de tus datos de entrada y los valores que deseas calcular. El compilador determina el orden de evaluación, verifica tipos, detecta condiciones imposibles y emite código sin dependencias para cada destino.
+
+```ruby
+schema do
+  input do
+    array :items do
+      hash :item do
+        integer :quantity
+        decimal :unit_price
+      end
+    end
+  end
+
+  value :line_totals, input.items.item.quantity * input.items.item.unit_price
+  value :subtotal, fn(:sum, line_totals)
+end
+```
+
+Sin bucles, sin tuberías de iteración: `line_totals` se calcula por elemento porque ahí es donde viven los datos, y `fn(:sum, ...)` lo reduce de nuevo a un escalar. Esto funciona con matrices anidadas arbitrariamente.
+
+## ¿Por qué?
+
+- **Una única fuente de verdad, dos destinos.** El mismo esquema se compila a Ruby y JavaScript con semántica idéntica: escribe la lógica de precios una vez, ejecútala en tu backend y en la vista previa del navegador.
+- **Difusión según la forma de los datos.** Las operaciones se alinean automáticamente sobre matrices basándose en la estructura de entrada declarada, incluidos datos anidados e irregulares.
+- **Verificaciones estáticas en tiempo de compilación.** La verificación de tipos, la detección de ciclos de dependencias y la detección de restricciones insatisfechas ocurren cuando se define el esquema, no en producción.
+- **Código generado sencillo y predecible.** La salida es determinista, sin dependencias, código lineal con bucles explícitos. Lo que lees es lo que se ejecuta.
+
+## Casos de uso
+
+Motores fiscales, modelos de precios, proyecciones financieras, reglas de cumplimiento, suscripción de seguros, calculadoras de tarifas de envío — en cualquier lugar donde la lógica de cálculo deba ser correcta, auditable y coherente entre plataformas.
+
+---
+
+**Estado**: experimental. La API pública puede cambiar. La tipificación y algunas verificaciones estáticas aún están en evolución.
+
+**Comentarios**: ¿tienes un caso de uso o encontraste algún problema? Abre un issue o contáctanos (andremuta+kumi@gmail.com).
+
+---
+
+## Instalación
+
+```bash
+gem install kumi
+```
+
+Requiere Ruby 3.1+. Dependencias en tiempo de ejecución: `mutex_m` y `zeitwerk` (incluidas a través de Rubygems).
+
+## Inicio rápido
+
+```ruby
+require 'kumi'
+
+module Double
+  extend Kumi::Schema
+
+  schema do
+    input { integer :x }
+    value :doubled, input.x * 2
+  end
+end
+
+# Execute in Ruby
+result = Double.from(x: 5)
+result[:doubled]  # => 10
+
+# or just call the method directly
+Double._doubled(x: 5) # => 10
+
+# Export to JavaScript (same logic)
+Double.write_source("output.mjs", platform: :javascript)
+# ./output.mjs
+# export function _doubled(input) {
+#   let t1 = input["x"];
+#   let t3 = t1 * 2;
+#   return t3;
+# }
+```
+
+También puedes anular la estrategia de compilación sin modificar el código estableciendo
+`KUMI_COMPILATION_MODE` en `jit` o `aot` (por ejemplo, `export KUMI_COMPILATION_MODE=aot`).
+
+## Composición de esquemas
+
+Los esquemas pueden importar otros esquemas — y el compilador **integra todo en línea en tiempo de compilación**. El código generado no tiene ninguna dependencia en tiempo de ejecución sobre el módulo importado; la lógica importada participa en la difusión y fusión de bucles como cualquier expresión escrita localmente.
+
+```ruby
+module TaxPolicy
+  extend Kumi::Schema
+
+  schema do
+    input { decimal :amount }
+    value :tax, input.amount * 0.15
+  end
+end
+
+module Order
+  extend Kumi::Schema
+
+  schema do
+    import :tax, from: TaxPolicy
+
+    input do
+      array :items do
+        hash :item do
+          decimal :price
+        end
+      end
+    end
+
+    # TaxPolicy only knows a scalar :amount — passing a vectorized
+    # argument applies it per item automatically.
+    value :item_taxes, fn(:tax, amount: input.items.item.price)
+    value :total_tax, fn(:sum, item_taxes)
+  end
+end
+
+Order.from(items: [{ price: 100 }, { price: 200 }, { price: 300 }])[:total_tax]
+# => 90.0
+```
+
+El JavaScript generado para `total_tax` muestra lo que significa "integrar todo en línea": la regla fiscal importada **y** la reducción `sum` se fusionan en un solo bucle, sin llamadas a `TaxPolicy`, sin matrices intermedias y sin runtime que empaquetar:
+
+```js
+export function _total_tax(input) {
+  let t13 = input["items"];
+  let acc18 = 0.0;
+  for (let items_i15 = 0; items_i15 < t13.length; items_i15++) {
+    let items_el14 = t13[items_i15];
+    let t16 = items_el14["price"];
+    let t17 = 0.15;
+    let t12 = t16 * t17;
+    acc18 += t12;
+  }
+  let t6 = acc18;
+  return t6;
+}
+```
+
+Consulta [Importación de esquemas](docs/SCHEMA_IMPORTS.md) para entradas renombradas, múltiples importaciones e importaciones sobre matrices anidadas.
+
+## Rendimiento
+
+Los esquemas compilados son código lineal con bucles fusionados — no hay intérprete, motor de reglas ni llamadas a bibliotecas en el artefacto, por lo que el costo en tiempo de ejecución es lo que el lenguaje de hosting cobre por un bucle `for`.
+
+Dos ejemplos en el playground hacen esto tangible:
+
+- **[Nómina a gran escala](https://kumi-play-web.fly.dev/?example=payroll-at-scale)** — una ejecución completa de nómina (división de horas extras, bandas de retención progresiva, diez agregados) sobre **10,000 empleados en ~0,2 ms por llamada** en Chrome de escritorio. Presiona **Benchmark ×100** en la pestaña Ejecutar para medir la mediana / p95 en tu propia máquina.
+- **[Game of Life XL](https://kumi-play-web.fly.dev/?example=life-xl)** — reglas de Conway sobre una **cuadrícula de 83,000 celdas**, avanzando en vivo en un worker con las nueve lecturas de vecinos fusionadas en un solo pase — millones de actualizaciones de celdas por segundo, renderizado en tiempo real con un contador en vivo.
+
+## Ejemplos
+
+- **Calculadora de impuestos de EE. UU. (2024)** — un solo esquema calcula impuestos federales, estatales y FICA en múltiples estados de declaración. [Abrir en la demostración](https://kumi-play-web.fly.dev/?example=us-federal-tax-2024).
+- **Nómina a gran escala** — horas extras, bandas de retención y agregados sobre 10,000 empleados con medición de tiempo por ejecución. [Abrir en la demostración](https://kumi-play-web.fly.dev/?example=payroll-at-scale).
+- **Portafolio Monte Carlo** — simulaciones probabilísticas y visualizaciones tabulares. [Abrir en la demostración](https://kumi-play-web.fly.dev/?example=monte-carlo-simulation).
+- **Juego de la vida de Conway** — operaciones de matrices que impulsan una simulación basada en cuadrícula (la [versión XL](https://kumi-play-web.fly.dev/?example=life-xl) ejecuta 83k celdas en vivo). [Abrir en la demostración](https://kumi-play-web.fly.dev/?example=game-of-life).
+
+El selector de ejemplos del playground agrupa estos por tema (recorrido del lenguaje, lógica empresarial, escala y velocidad, simulaciones) — la [Introducción al lenguaje](https://kumi-play-web.fly.dev/?example=language-intro) es el mejor punto de partida.
+
+---
+
+## Documentación
+
+- **[Referencia de sintaxis](docs/SYNTAX.md)** — sintaxis del DSL, tipos, operadores, funciones
+- **[Notas de sintaxis](docs/SYNTAX_NOTES.md)** — diferencias del analizador, recetas de entradas anidadas, literales de expresión y errores posteriores al análisis
+- **[Formas de entrada](docs/INPUTS.md)** — declarar escalares, matrices, hashes y la regla de elemento
+- **[Referencia de funciones](docs/FUNCTIONS.md)** — documentación generada automáticamente para todas las funciones y kernels ([JSON legible por máquina](docs/functions-reference.json))
+- **[Semántica entre destinos](docs/CROSS_TARGET_SEMANTICS.md)** — dónde Ruby y JS divergirían (`to_string` de flotantes, conversiones de cadena, `pow`) y cómo los kernels mantienen la identidad
+- **[Importación de esquemas](docs/SCHEMA_IMPORTS.md)** — composición y reutilización de esquemas
+- **[Arquitectura](docs/ARCHITECTURE.md)** — la tubería del compilador y la pila IR
+- **[Pruebas golden](docs/GOLDEN_TESTS.md)** — el entorno de pruebas de extremo a extremo
+- **[Guía de desarrollo](docs/DEVELOPMENT.md)** — herramientas, generación de documentación, integración con IDE
+
+---
+
+## Licencia
+
+Licencia MIT. Consulta [LICENSE](LICENSE).