@imolko/ultra-agent 0.1.0-beta

package/docs/adr/python/P-003-sqlalchemy-async-connection-pooling.md

@@ -0,0 +1,59 @@
+# P-003: SQLAlchemy async con connection pooling
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-018
+
+**Enriquecido desde**: Cortex ADR 018 — SQLAlchemy async session with connection pooling
+
+## Contexto
+
+Una API en Python necesita acceso asíncrono a base de datos para varias funciones: estado de sesión, seguimiento de procesos, búsqueda vectorial y CRUD. Sin una capa compartida de sesión y pool, cada feature crearía su propio engine y agotaría las conexiones.
+
+## Decisión
+
+Centralizar el acceso a base de datos en un **servicio de datos asíncrono** único, creado una sola vez en el arranque:
+
+```python
+class AsyncSqlAlchemyService:
+    def __init__(self, database_url: str):
+        self._engine = create_async_engine(
+            database_url,
+            pool_pre_ping=True,
+            pool_size=20,
+            max_overflow=10,
+        )
+        self._session_factory = async_sessionmaker(
+            bind=self._engine,
+            expire_on_commit=False,
+        )
+
+    def session(self) -> AsyncSession:
+        return self._session_factory()
+```
+
+### Decisiones de diseño
+
+- **Driver `asyncpg`**: acceso asíncrono a PostgreSQL (`postgresql+asyncpg://`).
+- **Connection pooling**: `pool_size` y `max_overflow` acotan el máximo de conexiones concurrentes.
+- **`pool_pre_ping=True`**: valida la conexión antes de usarla, para evitar conexiones obsoletas tras un reinicio de la base.
+- **`expire_on_commit=False`**: los objetos siguen siendo utilizables tras el commit, evitando errores de instancia desacoplada.
+- **Inyección por constructor**: la URL de base de datos se construye desde el contrato de settings en el arranque.
+- **Creación de tablas con `create_all`**: temporal para el MVP; producción usará migraciones Alembic.
+
+## Consecuencias
+
+### Positivas
+
+- **Pool único** para todo el acceso a datos: uso eficiente de conexiones.
+- **Sesiones acotadas por operación** mediante la factory `session()`.
+- **Creación automática de tablas** que simplifica el desarrollo del MVP.
+
+### Negativas
+
+- **`create_all` no es seguro en producción**: arranques concurrentes pueden competir en la creación de tablas.
+- **Sin historial de migraciones** hasta adoptar Alembic: los cambios de esquema requieren conciliación manual.
+- **Tamaño de pool fijo**: sin escalado dinámico según la carga.
+- **`expire_on_commit=False`**: se cambia riesgo de datos obsoletos por conveniencia de desarrollo.

package/docs/adr/python/P-004-serializer-json-custom-modelos-pydantic.md

@@ -0,0 +1,47 @@
+# P-004: Serializer JSON custom para modelos Pydantic
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-019
+
+**Enriquecido desde**: Cortex ADR 019 — MemorySaver with custom JSON serializer for Pydantic models
+
+## Contexto
+
+Un checkpointer (estado de sesión) serializa el estado a JSON. Ese estado contiene modelos Pydantic (esquemas de salida, entidades de dominio) que no se serializan de forma nativa con `json.dumps`. Sin un serializer custom, el checkpointing falla al serializar modelos.
+
+## Decisión
+
+Usar un **serializer JSON custom consciente de Pydantic**, registrado en el checkpointer:
+
+```python
+def memory_factory() -> BaseCheckpointSaver[str]:
+    serde = JsonSerializerFromCustomModels(
+        valid_namespaces=["app"]
+    )
+    return MemorySaver(serde=serde)
+```
+
+### Decisiones de diseño
+
+- **Ámbito por namespace**: `valid_namespaces` limita la serialización custom a las clases del namespace de la aplicación; el resto usa la serialización JSON por defecto.
+- **Función factory**: `memory_factory()` crea una instancia nueva en cada llamada, evitando estado compartido entre tests.
+- **Consciente de Pydantic**: el serializer usa `.model_dump()` / `.model_validate()` para los modelos del namespace declarado.
+
+El serializer se inyecta en la cadena de proveedores de dependencias ([P-001](./P-001-dependencias-por-feature-fastapi-depends.md)) y queda disponible para todos los grafos de la aplicación.
+
+## Consecuencias
+
+### Positivas
+
+- **Modelos Pydantic arbitrarios** en el estado, sin serialización manual.
+- **Checkpointing transparente**: los agentes no saben que existe la serialización.
+- **Ámbito por namespace** que evita serializar de forma custom objetos que no corresponden.
+
+### Negativas
+
+- **Estado en memoria**: el checkpointer en memoria pierde todo el estado al reiniciar el proceso.
+- **Sincronización**: el serializer debe mantenerse al día con los cambios de los modelos de la aplicación.
+- **Namespace hardcodeado**: agregar un namespace nuevo de modelos obliga a actualizar el serializer.

package/docs/adr/python/P-005-patrones-pitfalls-nicegui.md

@@ -0,0 +1,148 @@
+# P-005: Patrones y pitfalls de NiceGUI
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-026
+
+**Enriquecido desde**: Cortex ADR 026 — NiceGUI UI element patterns and pitfalls
+
+## Contexto
+
+Una UI en Python construida con NiceGUI necesita renderizar tablas de datos densas y manejar eventos de interacción (clic en una fila, apertura de un detalle). Durante el desarrollo de vistas con muchas filas surgieron problemas recurrentes que no son evidentes en la documentación de NiceGUI: tablas que se renderizan en blanco, handlers de eventos que no se invocan y gráficos que colapsan a altura cero.
+
+## Decisión
+
+Fijar patrones explícitos para el render de tablas, el manejo de eventos y el ciclo de vida de diálogos.
+
+### 1. Render de tablas: ancho fijo, nunca `flex`
+
+En las definiciones de columnas de tablas basadas en aggrid, **no usar la propiedad `flex`**: provoca que el cuerpo de la tabla se renderice en blanco (las filas existen en el DOM pero son invisibles). Usar siempre un `width` explícito por columna; el contenedor se encarga del scroll horizontal.
+
+```python
+# INCORRECTO — la tabla se renderiza en blanco
+ui.aggrid({
+    "columnDefs": [
+        {"field": "nombre", "headerName": "Nombre", "width": 200},
+        {"field": "descripcion", "headerName": "Descripción", "flex": 2},  # ← rompe la tabla
+    ],
+    "rowData": rows,
+})
+
+# CORRECTO
+ui.aggrid({
+    "columnDefs": [
+        {"field": "nombre", "headerName": "Nombre", "width": 200},
+        {"field": "descripcion", "headerName": "Descripción", "width": 300},
+    ],
+    "rowData": rows,
+    "defaultColDef": {"sortable": True, "resizable": True},
+}).classes("w-full")
+```
+
+### 2. Manejo de eventos: no apoyarse en los handlers del grid
+
+Los handlers Python de eventos del grid (`.on("rowClicked", ...)`, `.on("cellClicked", ...)`, `.on("selectionChanged", ...)`) no reciben de forma confiable los eventos JavaScript del grid: el bridging entre Vue y los handlers Python es inconsistente y los handlers pueden no invocarse nunca.
+
+Para interacción (clic para ver detalle, expandir, seleccionar) usar uno de estos patrones confiables:
+
+#### Patrón A: grid de tarjetas con botones explícitos (preferido para ≤50 items)
+
+```python
+with ui.row().classes("gap-3 flex-wrap w-full"):
+    for item in items:
+        with ui.card().classes("p-3 w-64"):
+            ui.label(item["titulo"]).classes("text-sm font-bold")
+            ui.button(
+                "Ver detalle",
+                on_click=lambda item=item: _mostrar_detalle(item),
+            ).props("flat dense size=sm")
+```
+
+Cada tarjeta tiene su propio `on_click` con una referencia capturada al item. Sin bridging de eventos, sin polling, sin condiciones de carrera.
+
+#### Patrón B: grid solo de lectura, acciones fuera
+
+Usar el grid exclusivamente como tabla ordenable y filtrable de solo lectura; mover las acciones interactivas a controles externos.
+
+```python
+grid = ui.aggrid({
+    "columnDefs": [...],
+    "rowData": items,
+    "defaultColDef": {"sortable": True, "resizable": True},
+}).classes("w-full")
+
+ui.button("Exportar CSV", on_click=exportar)
+```
+
+#### Patrón C: tabla HTML simple para datasets pequeños
+
+```python
+columns = [
+    {"name": "titulo", "label": "Título", "field": "titulo"},
+    {"name": "puntaje", "label": "Puntaje", "field": "puntaje"},
+]
+ui.table(columns=columns, rows=items, row_key="id").classes("w-full")
+```
+
+### 3. Dimensiones explícitas en gráficos
+
+Los gráficos (ECharts vía `ui.echart()`) pueden colapsar a altura cero si el contenedor no tiene dimensiones explícitas. Fijar siempre `.classes("w-full")` y una altura en `.style("height: Npx")`:
+
+```python
+ui.echart({...}).classes("w-full mb-3").style("height: 240px")
+```
+
+### 4. Contenedores intermedios para contenido dinámico
+
+NiceGUI puede perder elementos hijos al re-renderizar cuando se agregan directamente a una card o diálogo sin un contenedor intermedio. Envolver siempre el contenido dinámico en `ui.column()` o `ui.row()`:
+
+```python
+with ui.dialog() as dialog, ui.card():
+    with ui.column().classes("gap-3"):
+        ui.label("Título")
+        # ... contenido dinámico
+```
+
+### 5. Ciclo de vida de diálogos: capturar la referencia de inmediato
+
+Un diálogo creado dentro de un handler puede no ser accesible para cerrarlo programáticamente si se pierde la referencia. Capturar el diálogo en una variable del ámbito que lo encierra y abrirlo después de agregar todo el contenido:
+
+```python
+def _mostrar_modal(data: dict) -> None:
+    with ui.dialog() as dialog, ui.card():
+        ui.label(data["titulo"])
+        ui.button("Cerrar", on_click=dialog.close)
+    dialog.open()
+```
+
+### 6. Callbacks de timer: se soportan funciones async
+
+`ui.timer(intervalo, callback)` soporta callbacks `async def`: NiceGUI los agenda como tarea asyncio y `await` funciona dentro del callback:
+
+```python
+async def _consultar_estado() -> None:
+    resultado = await ui.run_javascript("...")
+    if resultado:
+        actualizar_ui(resultado)
+
+ui.timer(1.0, _consultar_estado)
+```
+
+`ui.run_javascript()` retorna una respuesta awaitable que debe consumirse de inmediato; no almacenarla ni consumirla fuera del callback.
+
+## Consecuencias
+
+### Positivas
+
+- **Tablas predecibles**: ancho fijo en todas las columnas evita el render en blanco.
+- **Interacción confiable**: las vistas de detalle usan el patrón de tarjetas con botón, sin depender de eventos del grid.
+- **Gráficos estables**: dimensiones explícitas evitan el colapso a altura cero.
+- **Onboarding más rápido**: los problemas conocidos quedan documentados en lugar de depender de ensayo y error con los internals del framework.
+
+### Negativas
+
+- **Grid limitado a solo lectura**: la interacción por fila no usa los handlers nativos del grid.
+- **Convenciones extra**: hay que mantener la disciplina de contenedores intermedios y dimensiones explícitas.
+- **Acoplamiento al framework**: estos patrones dependen del comportamiento actual de NiceGUI y pueden quedar obsoletos si el framework cambia.

package/docs/adr/python/P-006-convenciones-pytest.md

@@ -0,0 +1,96 @@
+# P-006: Convenciones de pytest
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-testing-with-python
+
+**Enriquecido desde**: Cortex doc "testing-with-python" — convenciones de pytest
+
+## Contexto
+
+Los tests en Python usan pytest. Sin convenciones compartidas, cada feature decide de forma distinta cómo marcar tests costosos, cómo listar tests sin ejecutarlos, cómo ver la salida de consola y cómo re-ejecutar tests al cambiar archivos.
+
+## Decisión
+
+Fijar las convenciones de pytest.
+
+### 1. Markers para tests que dependen de servicios externos
+
+Los tests que se conectan a un proveedor externo (por ejemplo, la evaluación de un LLM) consumen tiempo y dinero. Se marcan con un marker propio para poder incluirlos o excluirlos a discreción:
+
+```python
+@pytest.mark.llm_evaluation
+def test_evalua_respuesta():
+    ...
+```
+
+```bash
+# Solo los marcados
+poetry run pytest -m llm_evaluation
+
+# Todos menos los marcados
+poetry run pytest -m "not llm_evaluation"
+```
+
+En CI no se ejecutan los tests marcados: no evalúan el funcionamiento de la aplicación y su coste no está justificado en cada pipeline.
+
+Los markers custom se declaran en el `pyproject.toml` de cada app:
+
+```toml
+[tool.pytest.ini_options]
+markers = [
+    "only: marca un test para que sea de los únicos ejecutados",
+    "llm_evaluation: indica un test que evalúa el desempeño de un LLM",
+]
+```
+
+### 2. Listar tests sin ejecutarlos
+
+Para saber qué tests están definidos sin ejecutarlos:
+
+```bash
+poetry run pytest --collect-only
+```
+
+### 3. Ver salida de consola con `--capture=no`
+
+Por defecto pytest no muestra las salidas de consola. Para ver lo que se imprime durante la ejecución:
+
+```bash
+poetry run pytest --capture=no
+```
+
+### 4. Re-ejecución automática con pytest-watcher
+
+pytest no observa carpetas ni archivos por cambios. Para monitorear archivos y re-ejecutar tests al guardarlos se usa pytest-watcher:
+
+```bash
+poetry run pytest-watcher <path_a_observar> <path_de_tests>
+```
+
+Se puede combinar con markers, `--capture=no` e `--ignore`:
+
+```bash
+poetry run pytest-watcher ./src/ ./src/ -- --capture=no -m="not llm_evaluation" --ignore=./src/rutas/excluidas
+```
+
+### 5. Ejecutar un archivo o directorio concreto
+
+```bash
+poetry run pytest ./ruta/al/test --capture=no
+```
+
+## Consecuencias
+
+### Positivas
+
+- **Coste controlado**: los tests que consumen recursos externos se ejecutan solo cuando corresponde.
+- **Feedback rápido**: `--collect-only` y pytest-watcher aceleran la inspección y el ciclo de desarrollo.
+- **Convenciones uniformes**: markers, captura de salida y re-ejecución se resuelven igual en todas las apps.
+
+### Negativas
+
+- **Markers por app**: cada app declara sus markers en su `pyproject.toml`; hay que mantenerlos sincronizados si se comparten entre apps.
+- **Herramienta adicional**: pytest-watcher es una dependencia de desarrollo más en el flujo.

package/docs/adr/python/P-007-ci-python-alineacion-poetry-version-unica.md

@@ -0,0 +1,55 @@
+# P-007: CI Python: alineación Poetry↔lockfile y fuente única de la versión de Python
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-gitlab-ci-for-python
+
+**Enriquecido desde**: Cortex doc "gitlab-ci-for-python" — trucos para apps Python en GitLab CI
+
+## Contexto
+
+El pipeline de CI para aplicaciones Python construye imágenes y ejecuta tests. Dos valores deben coincidir entre el entorno local y el pipeline, y cuando no coinciden producen fallos oscuros:
+
+1. **La versión de Python** que usa el entorno local (devcontainer) frente a la que usa la imagen en CI.
+2. **La versión de Poetry** que genera el `poetry.lock` frente a la que se instala en la imagen que ejecuta `poetry install`.
+
+## Decisión
+
+### 1. Fuente única de la versión de Python
+
+La versión de Python se define en **un único lugar**, y tanto el devcontainer como el pipeline de CI la consumen desde esa fuente.
+
+En el entorno local, el devcontainer recibe la versión por una variable de entorno definida en el Dockerfile del devcontainer. En CI, la imagen usa la versión definida para la app. Si cada lado define la versión por su cuenta, aparecen incompatibilidades difíciles de notar porque el devcontainer se reconstruye con menos frecuencia que el pipeline (que se ejecuta en cada merge request).
+
+La regla es: **un solo valor canónico** para la versión de Python por app, del que derivan el devcontainer y el CI. Cualquier actualización se hace en esa fuente y se propaga a ambos.
+
+### 2. Alineación de la versión de Poetry con el lockfile
+
+Un error oscuro y difícil de diagnosticar ocurre cuando la versión de Poetry instalada en la imagen (`Dockerfile.poetry`) no coincide con la versión que generó `poetry.lock`.
+
+**Síntoma**: el pipeline falla en `poetry install` con un mensaje del estilo "pyproject.toml changed significantly since poetry.lock was last generated", aunque el `poetry.lock` se acabe de regenerar y publicar.
+
+**Causa raíz**: cada versión de Poetry usa su propio algoritmo para calcular el hash de contenido de `pyproject.toml` y lo guarda dentro del `poetry.lock`. Si la versión del Dockerfile es distinta de la que generó el lock, la versión más antigua recalcula el hash, obtiene otro valor y rechaza el archivo.
+
+**Detección**:
+
+- La primera línea de `poetry.lock` declara la versión que lo generó (por ejemplo `# ... @generated by Poetry 2.3.2 ...`).
+- El `Dockerfile.poetry` declara `POETRY_VERSION`.
+- Si no coinciden, esa es la causa.
+
+**Solución**: alinear `POETRY_VERSION` del `Dockerfile.poetry` con la versión que generó el `poetry.lock`. Siempre que se actualice Poetry en el entorno local, verificar que el `Dockerfile.poetry` quede alineado; idealmente, extraer el valor a una variable compartida.
+
+## Consecuencias
+
+### Positivas
+
+- **Menos fallos oscuros**: la versión de Python y la de Poetry no divergen entre local y CI.
+- **Diagnóstico rápido**: el error de Poetry↔lockfile queda documentado con su causa raíz y su verificación.
+- **Pipeline reproducible**: la imagen usa exactamente la versión de Python y Poetry que el proyecto declara.
+
+### Negativas
+
+- **Disciplina de sincronización**: actualizar Poetry o Python exige actualizar la fuente única y los consumidores.
+- **Acoplamiento al lockfile**: el `Dockerfile.poetry` debe mantenerse al día con la versión que genera el lock.

package/docs/adr/python/P-008-empaquetado-infraestructura-compartida-por-tecnologia.md

@@ -0,0 +1,38 @@
+# P-008: Empaquetado de la infraestructura compartida por tecnología en Python
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-26
+
+**originally**: imolko
+
+## Contexto
+
+[A-026](../foundational/A-026-infraestructura-compartida.md) fija la infraestructura compartida como un paquete por tecnología (`shared-infra/mongo/`, `shared-infra/postgres/`, …): cada paquete declara solo las dependencias de su tecnología y contiene los drivers que implementan los driver ports de las features. En Python, un paquete es una distribución (con su `pyproject.toml`) con un nombre de importación distinto; PEP 503 normaliza `-` y `_` en los nombres de distribución, así que la dualidad distribución↔importación es estándar (`scikit-learn` → `sklearn`).
+
+Si la infraestructura se empaqueta como una única distribución, instalar cualquier parte arrastra las dependencias de todas las tecnologías — pymongo y psycopg a la vez — el mismo problema de cierre que [A-026](../foundational/A-026-infraestructura-compartida.md) resuelve a nivel de paquete. Falta decidir cómo se distribuye e importa cada paquete por tecnología en Python.
+
+## Decisión
+
+Cada tecnología de la infraestructura compartida es una distribución independiente con un paquete de importación independiente:
+
+- Distribución `shared-infra-<tech>` (kebab) → import `shared_infra_<tech>` (snake): `shared-infra-mongo` → `shared_infra_mongo`, `shared-infra-postgres` → `shared_infra_postgres`, etc.
+- Cada distribución declara solo las dependencias de su tecnología (`pymongo`, `psycopg`, …) en su `pyproject.toml`.
+
+La feature define el driver port como un `typing.Protocol` estrecho ([A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)): DTOs tecnológicos tipados, nunca agregados de dominio, nunca `Any`. La implementación concreta vive en `shared_infra_<tech>` y satisface el protocolo por tipado estructural — la feature nunca importa la distribución.
+
+La app importa e instancia solo el driver de la tecnología que usa y lo inyecta en el wiring ([A-027](../foundational/A-027-patron-wiring-entry-point.md)). Solo esa distribución entra en su cierre de dependencias.
+
+## Consecuencias
+
+### Positivas
+
+- **Cierre tecnológico ligero**: instalar la feature arrastra solo la distribución de la tecnología elegida; pymongo y psycopg no conviven salvo que la app use ambos.
+- **Inversión de dependencia nativa**: el `Protocol` estructural expresa la costura sin importar la implementación, y el adaptador delega en él igual que en TypeScript.
+- **Feature sin dependencias tecnológicas**: el paquete de la feature solo depende del dominio y de la stdlib.
+
+### Negativas
+
+- **Una distribución por tecnología que mantener**: cada `shared_infra_<tech>` lleva su propio `pyproject.toml`, versionado y publicación.
+- **Disciplina de tipado estructural**: el `Protocol` solo protege si se declara sin `Any` ni `unknown`; aflojarlo reintroduce el acoplamiento.
+- **Nombre dual**: recordar la pareja distribución `shared-infra-<tech>` ↔ import `shared_infra_<tech>`.

package/docs/adr/python/index.md

@@ -0,0 +1,14 @@
+# ADRs de Python (P-XXX)
+
+Decisiones de arquitectura específicas del ecosistema Python (FastAPI, SQLAlchemy, Pydantic). Definen cómo implementar conceptos fundacionales en Python.
+
+| # | Título | Estado |
+|---|--------|--------|
+| P-001 | [Dependencias por feature con FastAPI Depends](./P-001-dependencias-por-feature-fastapi-depends.md) | Aceptado |
+| P-002 | [Inyección de token por request sin persistirlo](./P-002-inyeccion-token-por-request-sin-persistirlo.md) | Aceptado |
+| P-003 | [SQLAlchemy async con connection pooling](./P-003-sqlalchemy-async-connection-pooling.md) | Aceptado |
+| P-004 | [Serializer JSON custom para modelos Pydantic](./P-004-serializer-json-custom-modelos-pydantic.md) | Aceptado |
+| P-005 | [Patrones y pitfalls de NiceGUI](./P-005-patrones-pitfalls-nicegui.md) | Aceptado |
+| P-006 | [Convenciones de pytest](./P-006-convenciones-pytest.md) | Aceptado |
+| P-007 | [CI Python: alineación Poetry↔lockfile y fuente única de la versión de Python](./P-007-ci-python-alineacion-poetry-version-unica.md) | Aceptado |
+| P-008 | [Empaquetado de la infraestructura compartida por tecnología en Python](./P-008-empaquetado-infraestructura-compartida-por-tecnologia.md) | Aceptado |

package/docs/adr/typescript/T-001-ddd-artifact-validation-zod-primitives.md

@@ -0,0 +1,136 @@
+# T-001: Validación de artefactos DDD con primitivas Zod y errores built-in
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-15
+
+**originally**: imolko
+
+## Contexto
+
+La validación de artefactos DDD (value-objects, entidades y agregados) tiende a resolverse con un **validador por cada error de dominio** y un `superRefine` que evalúa manualmente cada condición. Este anti-patrón aparece tanto en código escrito a mano como en código generado; el scaffold de `ultra-generator` es solo el ejemplo más visible:
+
+- Un validador por cada error de dominio (`validate-product-id-empty-error.ts`, `validate-product-id-too-short-error.ts`, etc.)
+- Una clase `V8nCustomParseError` por cada error (`ProductIdEmptyErrorError`, `ProductIdTooShortErrorError`, etc.)
+- Un `superRefine` en `conditions/index.ts` que evalúa manualmente cada condición
+
+Ese enfoque genera **8 archivos adicionales** (~120 líneas de código) y usa `superRefine` donde las primitivas nativas de Zod (`.min()`, `.max()`, `.regex()`) son más legibles.
+
+Además, las clases custom heredan nombres redundantes (`ProductIdEmptyErrorError` con doble `Error`) y duplican comportamiento que `TooSmallError`, `TooBigError` e `InvalidStringError` de ultra-v8n ya proveen.
+
+## Decisión
+
+Para todos los artefactos DDD (value-objects, entidades, agregados), las reglas de validación estándar usan **primitivas nativas de Zod** y **errores built-in de ultra-v8n**. `superRefine` con errores custom se reserva exclusivamente para reglas cross-field que no pueden expresarse con primitivas.
+
+### Reglas de decisión
+
+| La validación es… | Usar |
+|-------------------|------|
+| Longitud mínima (incluye vacío) | `z.string().min(N, 'mensaje')` → `TooSmallError` |
+| Longitud máxima | `z.string().max(N, 'mensaje')` → `TooBigError` |
+| Patrón regex | `z.string().regex(/.../, 'mensaje')` → `InvalidStringError` |
+| Tipo | `z.string()` → `InvalidTypeError` |
+| Valor positivo | `z.number().positive('mensaje')` → `TooSmallError` |
+| Valor mínimo | `z.number().min(N, 'mensaje')` → `TooSmallError` |
+| Referencia a otro artefacto | `Artefacto.rules()` — delega en el schema Zod del artefacto referenciado |
+| Regla de dominio cross-field (ej: adjustmentReason obligatorio solo si type=ADJUSTMENT) | `superRefine` + `V8nCustomParseError` |
+
+### Value-objects
+
+```typescript
+// conditions.ts — schema directo
+export const conditions = z.string()
+  .min(3, 'Product ID must be at least 3 characters')
+  .max(50, 'Product ID must be at most 50 characters')
+  .regex(/^[A-Za-z0-9_-]+$/, 'Product ID can only contain letters, numbers, hyphens, and underscores');
+```
+
+### Entidades
+
+```typescript
+// conditions/index.ts — z.object() componiendo .rules() de otros artefactos
+export const conditions = z.object({
+  id: Uuid.rules(),
+  batchId: BatchId.rules(),
+  expirationDate: ExpirationDate.rules(),
+});
+```
+
+Las entidades componen sus condiciones desde los value-objects que las forman mediante `Artefacto.rules()`. No repiten validaciones — cada value-object es responsable de las suyas.
+
+### Agregados
+
+```typescript
+// conditions/index.ts — { build, rebuild } con transformaciones
+export const conditions = {
+  build: z.object({...}).transform(setVersionOne),
+  rebuild: z.object({...}).extend({ version: z.number().min(1) }),
+};
+```
+
+Los agregados exportan `{ build, rebuild }`:
+- `build`: schema de creación, incluye `transform(setVersionOne)` para inicializar `version = 1`
+- `rebuild`: schema de reconstrucción desde snapshot, extiende `build` con campos requeridos en el snapshot (`version`, `state`, `createdAt`, etc.)
+
+Ambos usan `Artefacto.rules()` para las propiedades y `.superRefine` solo para validaciones cross-field.
+
+### Ejemplo
+
+```typescript
+// ✅ Preferido — 7 líneas, sin archivos extra
+export const conditions = z.object({
+  value: z
+    .string()
+    .min(3, 'Product ID must be at least 3 characters')
+    .max(50, 'Product ID must be at most 50 characters')
+    .regex(/^[A-Za-z0-9_-]+$/, 'Product ID can only contain letters, numbers, hyphens, and underscores'),
+});
+
+// ❌ Evitar — ~80 líneas + 8 archivos extra
+export const conditions = z.object({
+  value: z.string().superRefine((value, ctx) => {
+    if (value.length === 0) { ctx.addIssue({ ... ProductIdEmptyErrorError.v8n(...) }); }
+    if (value.length > 0 && value.length < 3) { ctx.addIssue({ ... }); }
+    if (value.length > 50) { ctx.addIssue({ ... }); }
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) { ctx.addIssue({ ... }); }
+  }),
+});
+```
+
+### Mensajes de error
+
+Los mensajes personalizados pasados a `.min()`, `.max()` y `.regex()` son convertidos por `convertZodIssueToV8nError` (ultra-v8n) en el `detail` del error built-in. El `title` y `type` provienen de la clase built-in:
+
+```typescript
+// Producido por .min(3, 'Product ID must be at least 3 characters'):
+{
+  type: 'http://journal/v8n/too_small',
+  title: 'Too Small',
+  detail: 'Product ID must be at least 3 characters'
+}
+```
+
+### Cuándo usar `superRefine`
+
+Reservar exclusivamente para **reglas cross-field** que no pueden expresarse con primitivas Zod:
+
+- Relaciones entre campos del mismo artefacto (ej: `adjustmentReason` obligatorio solo si `type === ADJUSTMENT`)
+- Invariantes de negocio que involucran múltiples propiedades (ej: "el monto no puede superar el límite diario del almacén")
+
+Nunca usar `superRefine` para validaciones que ya cubren las primitivas (`.min()`, `.max()`, `.regex()`, `.positive()`). Usar uno u otro, no ambos.
+
+## Consecuencias
+
+### Positivas
+
+- **Menos código**: 1 archivo de condiciones (~10 LOC) vs N+1 archivos (~80-120 LOC)
+- **Más legible**: `.min(3)` expresa la intención mejor que un `if (value.length < 3)` dentro de `superRefine`
+- **Estándar de Zod**: cualquier desarrollador que conozca Zod entiende el código inmediatamente
+- **Sin nombres redundantes**: adiós a las clases `XxxErrorError`
+- **Errores con detalle contextual**: el `detail` se personaliza con mensajes descriptivos
+
+### Negativas
+
+- **Menos granularidad**: no se puede distinguir entre "vacío" y "muy corto" con `.min()` solo (ambos producen `TooSmallError`). Si el negocio requiere distinguirlos, usar `superRefine`. En la práctica, la distinción rara vez aporta valor
+- **Dependencia de mensajes**: si se cambia el idioma del mensaje de error, los tests que asertan sobre `detail` deben actualizarse
+- **`.rules()` requiere value-objects completos**: componer una entidad con `Artefacto.rules()` implica que el value-object ya existe con su propio `conditions.ts`. No se puede validar una entidad antes de que existan sus value-objects