@imolko/ultra-agent 0.1.0-beta

package/docs/adr/typescript/T-002-test-documentation-jsdoc.md

@@ -0,0 +1,133 @@
+# T-002: Documentación de tests con JSDoc para ultra-reporter
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-15
+**originally**: imolko
+
+## Contexto
+
+[`ultra-reporter`](./T-011-ultra-reporter-herramienta-canonica-documentacion.md) escanea el código fuente y genera documentación Docusaurus para cada artefacto del dominio y cada feature (command/query). En la página de cada artefacto o feature, se muestran las reglas de dominio documentadas en `README.md` (formato canónico en [A-032](../foundational/A-032-domain-artifact-documentation-format.md)) y los casos de prueba extraídos de los archivos `*.spec.ts`.
+
+Para que ultra-reporter pueda generar documentación útil para expertos del dominio, los tests deben seguir una convención consistente de anotaciones JSDoc.
+
+## Decisión
+
+Todo test **de comportamiento** — unitarios de artefactos de dominio y de casos de uso (features) — debe incluir anotaciones JSDoc con las etiquetas `@name` y `@scenario`:
+
+```typescript
+/**
+ * Descripción larga del test que explica el comportamiento verificado.
+ * @name crear ProductId vacío
+ * @scenario Se intenta crear un ProductId con un string vacío ('').
+ *           La validación de longitud mínima (3 caracteres) lo rechaza
+ *           con un error TooSmallError.
+ */
+it('crear ProductId vacío', () => {
+  // ...
+});
+```
+
+### Reglas
+
+| Regla | Descripción |
+|-------|-------------|
+| `@name` coincide con `it()` | El texto de `@name` debe ser **idéntico** al primer argumento de `it()`. Esto asegura que el título en la documentación generada coincida con el nombre del test en el runner. |
+| `@scenario` describe el qué y por qué | Explica qué entrada se usa, qué regla se ejerce, y qué resultado se espera. Debe ser comprensible para un experto del dominio sin conocimientos técnicos. |
+| Sin "falla si…" en títulos | El título del test (`it()` y `@name`) describe **el escenario**, no el resultado. Ej: `'crear ProductId vacío'` en lugar de `'crear ProductId vacío – falla si está vacío'`. El resultado lo expresa `@scenario`. |
+| Idioma del repo | Los nombres y descripciones van en el idioma del repo (`issue_language`), fijado por [A-003](../foundational/A-003-tdd.md): en Guarura, español. |
+| Primera línea: descripción larga | La primera línea del JSDoc (antes de `@name`) contiene una descripción extendida del comportamiento verificado. |
+
+> **Ámbito**: la convención aplica a tests que documentan reglas de dominio o comportamiento de casos de uso. Los tests de contrato (validación de esquemas y tipos, por ejemplo `*.contract.spec.ts`) quedan fuera: validan estructura, no reglas de dominio, y no se convierten en casos documentados para expertos del dominio.
+
+### Ejemplo completo (value-object)
+
+```typescript
+/**
+ * Verificar que un ProductId con más caracteres de lo permitido es rechazado
+ * @name crear ProductId muy largo
+ * @scenario El valor tiene 51 caracteres, uno por encima del máximo
+ *           de 50. La validación de longitud máxima lo rechaza con
+ *           TooBigError.
+ */
+it('crear ProductId muy largo', () => {
+  const payload: Payload = { value: 'A'.repeat(51) };
+  const result = ProductId.of(payload);
+  expect(result).toBeInvalid();
+  expect(result).toHaveErrorLike({
+    type: 'http://journal/v8n/too_big',
+    title: 'Too Big',
+    detail: 'Product ID must be at most 50 characters',
+  });
+});
+```
+
+### Ejemplo completo (feature use-case)
+
+```typescript
+/**
+ * Verificar que el caso de uso retorna InvalidWarehouseError cuando
+ * el warehouseId no corresponde a un almacén existente en el sistema.
+ * @name warehouse no encontrado retorna InvalidWarehouseError
+ * @scenario Se envía warehouseId=WH-NONEXISTENT sin registrar ningún
+ *           warehouse con ese ID. El producto y variante asociados sí
+ *           existen para aislar la validación del warehouse.
+ */
+it('warehouse no encontrado retorna InvalidWarehouseError', async () => {
+  // ...
+});
+```
+
+El formato es idéntico: la única diferencia es que los tests de features validan
+el comportamiento del pipeline del caso de uso (orquestación, manejo de errores,
+persistencia) en lugar de reglas de un value-object individual.
+
+### Lo que ultra-reporter extrae
+
+En la página de documentación del artefacto o feature, ultra-reporter muestra para cada test:
+
+| Campo | Fuente |
+|-------|--------|
+| Título del caso | `@name` |
+| Descripción | Texto libre antes de `@name` |
+| Escenario | `@scenario` |
+
+Además de estas anotaciones, ultra-reporter lee el resultado de los tests en formato CTRF (ver [A-022](../foundational/A-022-formato-reporte-tests-ctrf.md)); el pipeline completo se describe en [T-011](./T-011-ultra-reporter-herramienta-canonica-documentacion.md).
+
+### Co-located tests
+
+Los archivos de test viven junto al archivo fuente que testean, usando el patrón `<subject>.spec.ts`:
+
+```
+src/domain/value-objects/product-id/
+├── ProductId.ts
+├── conditions.ts
+├── index.ts
+└── ProductId.spec.ts          ← co-located test
+```
+
+**Reglas:**
+
+| Regla | Descripción |
+|-------|-------------|
+| Mismo directorio | El `.spec.ts` reside en la misma carpeta que el sujeto de prueba |
+| Nomenclatura | `<nombre-del-archivo>.spec.ts` — ej: `ProductId.ts` → `ProductId.spec.ts` |
+| Sin árbol `__tests__/` separado | No se usan directorios `__tests__/` dedicados |
+
+Esta organización facilita el descubrimiento: al abrir cualquier archivo fuente, sus tests son inmediatamente visibles. El `testMatch` de Jest/Vitest se fija en `**/*.spec.ts` — el default de Jest ya lo cubre, así que no requiere configuración adicional salvo que se quiera excluir explícitamente un árbol `__tests__/`.
+
+## Consecuencias
+
+### Positivas
+
+- **Documentación generada automáticamente**: cada test se convierte en un caso documentado en el sitio Docusaurus
+- **Legible por expertos del dominio**: las descripciones en el idioma del repo y el formato `@scenario` permiten que stakeholders no técnicos validen las reglas implementadas
+- **Consistencia**: todas las páginas de artefactos siguen el mismo formato, facilitando la navegación
+- **Doble propósito**: el mismo texto sirve como documentación del test (para desarrolladores) y como especificación (para el negocio)
+- **Trazabilidad**: cada regla de dominio documentada en `README.md` tiene su test correspondiente
+
+### Negativas
+
+- **Disciplina**: requiere que todo el equipo siga la convención en cada test
+- **Mantenimiento dual**: si cambia el `it()`, debe cambiarse también `@name`
+- **No automatizable**: el `@scenario` requiere redacción humana con conocimiento del dominio

package/docs/adr/typescript/T-003-readme-formatting-domain-artifacts.md

@@ -0,0 +1,51 @@
+# T-003: Reconciliación del scaffold de ultra-generator con el formato canónico
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-15
+
+**originally**: imolko
+
+## Contexto
+
+El scaffold que produce `ultra-generator` (herramienta canónica: [T-019](./T-019-ultra-generator-herramienta-canonica-generacion.md)) para cada artefacto de dominio no es el `README.md` final: trae títulos en inglés y una sección `Relaciones` en bullet points, además de un archivo `.instructions.md` con instrucciones para el agente o desarrollador. El formato canónico del `README.md` es una decisión global, no específica de TypeScript, y vive en [A-032](../foundational/A-032-domain-artifact-documentation-format.md).
+
+Este ADR fija la mecánica específica del ecosistema TypeScript para reconciliar el scaffold con A-032: completar el `README.md` y eliminar el archivo de trabajo `.instructions.md`.
+
+## Decisión
+
+El scaffold de `ultra-generator` es un punto de partida, no el `README.md` final. El desarrollador o agente debe **reconciliarlo con el formato canónico** de A-032 y, solo entonces, eliminar el archivo de trabajo:
+
+1. **Completar el scaffold**: traducir las secciones a los títulos en español definidos en A-032 (`## Purpose` → `## Propósito`, etc.) y reemplazar los bullet points de `Relaciones` por un diagrama Mermaid.
+2. **Eliminar `.instructions.md`**: una vez completada la implementación del artefacto, eliminar `.instructions.md` para que no contamine la documentación generada.
+
+**Antes de eliminar `.instructions.md`**, se debe verificar que el `README.md` está completo según A-032:
+
+- El `README.md` no contiene texto placeholder (ej: `_Describe the business purpose..._`, `## Purpose`).
+- Las secciones usan los títulos en español definidos en A-032.
+- La sección `## Relaciones` contiene un diagrama Mermaid.
+- Para features, las secciones dependen del `type` declarado en el frontmatter (`command` o `query`, según A-032).
+
+Si el `README.md` no cumple estas condiciones, `.instructions.md` **no debe eliminarse** hasta que el README esté completo. Si se vuelve a ejecutar `ultra-generator` sobre el mismo artefacto, `.instructions.md` se regenera y debe eliminarse nuevamente.
+
+### Verificación
+
+| Check | Comando |
+|-------|---------|
+| Sin `.instructions.md` | `test ! -f RUTA/.instructions.md` |
+| Sin título H1 | `! grep -q '^# ' RUTA/README.md` |
+| Frontmatter presente | `head -1 RUTA/README.md \| grep -q '^---$'` |
+| Mermaid en Relaciones | `grep -q mermaid RUTA/README.md` |
+
+## Consecuencias
+
+### Positivas
+
+- **Documentación limpia**: sin checklist de desarrollo ni títulos en inglés en las páginas finales.
+- **Un solo eje**: la reconciliación (completar + eliminar) queda separada del formato (A-032) y de la procedencia del frontmatter (T-018).
+
+### Negativas
+
+- **Divergencia con el generador**: el scaffold produce títulos en inglés; el desarrollador o agente debe traducirlos siguiendo A-032.
+- **Regeneración de `.instructions.md`**: si se re-ejecuta `ultra-generator` sobre un artefacto existente, `.instructions.md` se regenera y debe eliminarse manualmente.
+- **Sin validación automática**: no hay un linter que verifique el formato; la revisión es manual o delegada al agente.

package/docs/adr/typescript/T-005-input-optionality-use-case-not-entity.md

@@ -0,0 +1,130 @@
+# T-005: Contratos de input reflejan la interfaz externa; el caso de uso resuelve la opcionalidad
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-27
+**originally**: imolko
+
+## Contexto
+
+Los casos de uso operan sobre contratos de input (`InputDto`) que provienen de la capa de infraestructura (CLI, GraphQL, REST, mensajería). Estos contratos definen la interfaz externa del sistema: qué datos debe proveer el caller para invocar una operación.
+
+La interfaz externa no siempre coincide con la forma que el dominio necesita:
+
+| Capa | Forma del dato | Ejemplo |
+|------|---------------|--------|
+| Interfaz externa (InputDto) | El caller puede no conocer el lote | `batch?: string` |
+| Dominio (Props de entidad) | Toda línea de movimiento tiene un lote | `batchId: BatchId` (requerido) |
+
+### No es una bolsa de campos opcionales
+
+Este ADR **no** autoriza DTOs con docenas de campos opcionales por conveniencia. Un `InputDto` debe ser un contrato bien definido, con la mínima cantidad de campos necesarios para la operación. Cada campo opcional debe justificarse por una razón de interfaz, no por conveniencia:
+
+| ✅ Campo opcional justificado | ❌ Campo opcional injustificado |
+|------------------------------|-------------------------------|
+| `batch?`: el caller puede no conocer el lote al registrar una entrada | `createdBy?`: "por si acaso no viene" — toda operación requiere un responsable |
+| `expirationDate?`: override explícito del shelf life por defecto | `warehouseId?`: "a veces lo mandan, a veces no" — si es requerido, que falle temprano |
+| `documents?`: documentos anexos son genuinamente opcionales | `items?`: "por si la lista viene vacía" — una entrada sin ítems no tiene sentido |
+
+Si un DTO acumula más de 3-4 campos opcionales, considerar si la operación debería dividirse en múltiples casos de uso con contratos específicos.
+
+### Ejemplo: U01 Registrar Entrada de Mercancía
+
+```typescript
+// Contrato de input — campos opcionales justificados por la interfaz
+{
+  warehouseId: string,             // requerido: siempre se sabe a qué almacén entra
+  items: [{
+    productVariantId: string,      // requerido: siempre se sabe qué producto es
+    quantity: number,              // requerido: siempre se sabe cuánto entra
+    batch?: string,                // opcional: el caller puede no conocer el lote
+    expirationDate?: string,       // opcional: override de shelf life por defecto
+  }],
+  documents?: Array<{              // opcional: puede no haber documentos anexos
+    type: string;
+    number: string;
+  }>,
+  createdBy: string                // requerido: toda operación tiene un responsable
+}
+```
+
+Los artefactos del dominio tienen invariantes que NO admiten opcionalidad por conveniencia: la opcionalidad del contrato de input se resuelve en el caso de uso antes de construir el artefacto.
+
+- Un campo que el negocio exige siempre presente es **requerido**, aunque el caller no lo provea (ej: un lote auto-generado)
+- Una colección es **siempre una colección**: requerida, vacía si no se adjuntaron elementos
+- Un autor o responsable es **requerido** en toda operación
+
+Se presentan dos opciones:
+
+**Opción A**: Debilitar las invariantes del dominio para que admitan `null`, reflejando directamente el contrato de input. Por ejemplo, hacer `batchId: BatchId | null` en `StockMovementLine`.
+
+**Opción B**: Mantener las invariantes del dominio como requeridas y resolver la opcionalidad en el caso de uso antes de construir los artefactos.
+
+## Decisión
+
+**Opción B**: El caso de uso resuelve la opcionalidad del contrato externo (InputDto, que refleja la interfaz) antes de construir el modelo de dominio (invariantes estrictas). La traducción de primitivas a tipos de dominio ocurre antes, en el controlador ([T-007](./T-007-controller-input-zod-schema.md)); esta resolución es parte natural de la capa de features que orquesta el dominio ([A-001](../foundational/A-001-clean-architecture-4-capas.md)).
+
+### Reglas
+
+1. **Los artefactos de dominio no admiten campos opcionales por conveniencia del input**. Si el dominio dice "toda línea de movimiento tiene un lote", el artefacto refleja esa invariante con `batchId: BatchId` (requerido). Esto aplica a value-objects, entities y aggregates.
+
+2. **El InputDto debe ser un contrato bien definido**, no una bolsa de campos opcionales. Cada campo (requerido u opcional) debe justificarse por la interfaz externa. Ante la duda, hacer el campo requerido y dejar que el validador falle temprano.
+
+3. **El caso de uso es responsable de resolver la opcionalidad** antes de invocar constructores del dominio:
+   - Campos opcionales con valor por defecto → el caso de uso aplica el default (ej: `documents` → `[]`)
+   - Campos opcionales que requieren inferencia → el caso de uso ejecuta la lógica de inferencia (ej: `batch?` → auto-crear `Batch` con `productVariant.defaultShelfLifeDays`)
+   - Campos opcionales que son overrides → el caso de uso resuelve la precedencia (ej: `expirationDate?` sin `batch?` → usar `expirationDate` en lugar de `defaultShelfLifeDays`; con `batch?` → ignorar)
+
+4. **El dominio nunca recibe `null` o `undefined`** en campos que el dominio considera invariantes. El caso de uso resuelve la opcionalidad: interfaz externa (flexible) → dominio (estricto).
+
+La validación de forma (longitud, formato, tipo) usa las primitivas Zod de [T-001](./T-001-ddd-artifact-validation-zod-primitives.md); la opcionalidad (presencia o ausencia) se refleja en el contrato de input y se resuelve en el caso de uso.
+
+### Ejemplo
+
+```typescript
+// ❌ INCORRECTO: debilitar el dominio para acomodar el input
+interface StockMovementLineProps {
+  batchId: BatchId | null;  // ← NO: toda línea tiene lote
+}
+```
+
+```typescript
+// ✅ CORRECTO: resolver en el caso de uso
+async execute(input: RegisterInboundCommand): Promise<Validation<Errors, void>> {
+  // Resolver opcionalidad antes de tocar el dominio
+  const documents = input.documents ?? [];
+  
+  const lines = await Promise.all(input.items.map(async (item) => {
+    const batch = item.batch ?? await this.createAutoBatch(item);
+    return StockMovementLine.create({ batchId: batch.id, ... });
+  }));
+  
+  const movement = StockMovement.create({ lines, documents, ... });
+  // ...
+}
+```
+
+### Cuándo SÍ usar opcionalidad en el dominio
+
+La opcionalidad en artefactos de dominio solo se justifica cuando el **dominio mismo** la requiere:
+
+- `StockMovement.originWarehouseId: WarehouseId | null` — en una entrada (Inbound), el origen es externo, no un almacén del sistema. El dominio define esta opcionalidad, no el input.
+- `StockMovement.destinationWarehouseId: WarehouseId | null` — en una salida (Outbound), el destino es externo.
+
+En estos casos, la opcionalidad es una regla de negocio, no una consecuencia de la forma del input.
+
+## Consecuencias
+
+### Positivas
+
+- **Invariantes fuertes**: los artefactos del dominio reflejan fielmente las reglas del negocio, sin concesiones por la forma del input
+- **Opcionalidad resuelta en el caso de uso**: el caso de uso tiene una responsabilidad clara y acotada: resolver la opcionalidad del contrato externo antes de construir el dominio
+- **Reutilización**: si otro caso de uso construye `StockMovementLine` con reglas diferentes, el artefacto no necesita cambiar — cada caso de uso aplica su propia lógica de resolución
+- **Testabilidad**: la lógica de resolución (auto-creación de lotes, defaults) se prueba en el caso de uso, y las invariantes del dominio se prueban de forma aislada
+- **Contratos explícitos**: cada InputDto documenta exactamente qué espera la interfaz externa, sin campos sorpresa que "a veces se usan"
+
+### Negativas
+
+- **Duplicación potencial**: si múltiples casos de uso necesitan la misma lógica de resolución (ej: auto-creación de lotes), ésta podría duplicarse. Se mitiga extrayendo un servicio de dominio (ej: `BatchFactory`) cuando el patrón se repita 3+ veces
+- **Más código en el caso de uso**: la resolución de opcionalidad agrega lógica al caso de uso que de otra forma estaría implícita en validadores de schema. Es un tradeoff deliberado: código explícito en el caso de uso vs invariantes implícitas en el schema
+- **Disciplina en el DTO**: requiere que el desarrollador justifique cada campo opcional. Sin esta disciplina, el DTO degenera en una bolsa de campos opcionales

package/docs/adr/typescript/T-006-small-enums-inlined-zod-regex.md

@@ -0,0 +1,77 @@
+# T-006: Enums pequeños y estables se inlinean con Zod regex
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-27
+**originally**: imolko
+
+## Contexto
+
+Un dominio modelado con DDD contiene múltiples tipos enumerados que modelan clasificaciones del negocio (tipos de movimiento, estados, estados de reserva, etc.). Extraer cada uno a un value-object separado exige un sub-árbol completo de artefactos — definición, condiciones, errores, tests, documentación y el propio enum — con independencia de si el código se escribe a mano, lo genera un agente o lo produce un scaffold. Ese coste no aporta valor cuando el enum es pequeño y estable — por ejemplo, un `type` con cuatro valores posibles que solo clasifica, sin comportamiento, relaciones ni ciclo de vida propios.
+
+## Decisión
+
+Cuando un tipo enumerado cumple **todas** las siguientes condiciones, se representa como un campo `string` con validación `z.string().regex()` inline (la primitiva Zod de [T-001](./T-001-ddd-artifact-validation-zod-primitives.md)), en lugar de extraerlo a un value-object separado:
+
+### Criterios para inlinear
+
+| Criterio | Justificación |
+|----------|---------------|
+| ≤5 valores estables | Pocos valores = baja probabilidad de cambio. Si el enum crece más allá de 5, considerar extraerlo. |
+| Sin comportamiento propio | El tipo solo se usa para clasificar, no tiene métodos como `isExpired()`, `canTransitionTo()`, etc. |
+| Sin ciclo de vida independiente | No se persiste, consulta, o referencia de forma autónoma. Solo existe como propiedad de otro artefacto. |
+| Sin referencias externas | Ningún otro artefacto lo importa como tipo independiente. Si múltiples artefactos lo referencian, merece su propio archivo. |
+
+### Criterios para extraer a value-object separado
+
+| Criterio | Justificación |
+|----------|---------------|
+| ≥6 valores o historial de crecimiento | Más valores = más probabilidad de cambio. Un VO separado centraliza las modificaciones. |
+| Comportamiento propio | Métodos como `isTerminal()`, `canTransitionTo()`, `requiresConfirmation()` justifican el VO. |
+| Referenciado por múltiples artefactos | Si 3+ artefactos importan el tipo, extraerlo evita duplicación de constantes y validación. |
+| Usado en proyecciones o read models | Si el enum aparece en consultas, eventos, o representaciones externas, tener un tipo canónico previene divergencia. |
+
+### Ejemplo: DocumentRef.type (inlineado)
+
+```typescript
+// domain/src/document-ref/conditions.ts
+export const conditions = z.object({
+  type: z
+    .string()
+    .regex(
+      /^(SADA_GUIDE|INVOICE|DELIVERY_ORDER|OTHER)$/,
+      'Document type must be one of: SADA_GUIDE, INVOICE, DELIVERY_ORDER, OTHER',
+    ),
+  reference: z.string().min(1).max(100),
+  issuer: z.string().min(1).max(200),
+});
+```
+
+### Ejemplo: StockMovementType (extraído — CORRECTO)
+
+`StockMovementType` fue extraído como value-object separado porque:
+
+- Supera el umbral de 5 valores
+- Es referenciado por `StockMovement`, `StockMovementLine`, y eventos como `StockMovementCreated`
+- Aparece en el snapshot del agregado (persistencia vía Event Sourcing)
+- Podría necesitar comportamiento en el futuro (ej: `requiresDestinationWarehouse(): boolean`)
+
+### Cómo evaluar un enum existente
+
+Para determinar si un enum existente debe extraerse o inlinearse, aplicar los criterios definidos en las tablas anteriores. Inlinear es aceptable cuando el dominio no otorga identidad propia al concepto: el enum es utilidad de validación sin lógica de dominio, del tipo que [A-008](../foundational/A-008-bounded-context-decomposition.md) agrupa en el contexto compartido. No mantener una lista hardcodeada de enums en este ADR — los criterios son la fuente canónica.
+
+## Consecuencias
+
+### Positivas
+
+- **Menos boilerplate**: un campo inlineado ocupa ~4 líneas (la línea `.regex()`) frente a un sub-árbol completo de archivos para un VO separado
+- **Navegabilidad**: el tipo y sus valores válidos son visibles en el mismo archivo de condiciones, sin tener que abrir otro directorio
+- **Sin decisión prematura**: si un enum inlineado crece más allá de 5 valores, se puede extraer a VO sin romper la API pública (el cambio es interno a `conditions.ts`)
+- **Fricción reducida**: modelar un campo clasificatorio no requiere generar un sub-árbol completo de archivos
+
+### Negativas
+
+- **Duplicación potencial**: si dos artefactos inlinean el mismo enum (ej: `SADA_GUIDE|INVOICE|...`), la regex y el mensaje de error se duplican. Se mitiga extrayendo a VO cuando ocurra la primera duplicación.
+- **Sin tipo TypeScript**: `z.string().regex()` produce `string` en el tipo inferido, no un union type `'SADA_GUIDE' | 'INVOICE' | ...`. El type narrowing en el caso de uso requiere casts o type guards manuales.
+- **Inconsistencia visual**: algunos enums son VOs completos, otros son strings con regex. El criterio de 5 valores es un umbral arbitrario que podría generar debate.
+- **Descubribilidad**: los valores válidos de un enum inlineado solo son visibles leyendo el archivo de condiciones. Un VO separado con `enum.ts` es más fácil de descubrir con `grep` o navegación de IDE.

package/docs/adr/typescript/T-007-controller-input-zod-schema.md

@@ -0,0 +1,79 @@
+# T-007: Todo controlador de feature expone un esquema Zod para su InputDto
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-28
+**originally**: imolko
+
+## Contexto
+
+Cada caso de uso define un contrato de entrada (`InputDto`) que especifica los campos que recibe del exterior. Este contrato es una interfaz TypeScript — desaparece en tiempo de ejecución. Sin embargo, múltiples consumidores necesitan validar y/o inspeccionar este contrato en runtime:
+
+- Un controlador de transporte (HTTP, CLI, mensajería) necesita validar el input externo antes de pasarlo al caso de uso
+- Un consumidor puede introspectar los campos del contrato en runtime para generar prompts o formularios dinámicos
+- Cualquier aplicación que exponga los casos de uso (REST, GraphQL, CLI, tests) necesita conocer la forma exacta del input
+
+Sin un esquema runtime, cada consumidor debe duplicar la definición del contrato, con el riesgo de desincronización.
+
+## Decisión
+
+**Todo controlador de feature debe exportar un esquema Zod para el InputDto.** El controlador vive en `adapters/controller/` dentro de la capa `features/` ([A-001](../foundational/A-001-clean-architecture-4-capas.md), [A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)).
+
+El archivo `adapters/controller/input.dto.ts` es la ubicación canónica. Esto es intencional:
+
+- El controlador recibe representaciones externas (JSON, strings, números) y las valida con Zod.
+- Luego **traduce** esas representaciones a conceptos del dominio (`WarehouseId`, `Quantity`, etc.) antes de invocar el caso de uso.
+- El caso de uso recibe un contrato con tipos de dominio, no primitivas. La traducción de primitivas a tipos de dominio es responsabilidad del controlador.
+
+El esquema y el tipo inferido (`z.infer`) viven en el controlador:
+
+```typescript
+import * as z from 'zod';
+
+export const InputSchema = z.object({
+  // campos requeridos con validaciones mínimas
+  campo: z.string().min(1, 'campo es requerido'),
+  // campos opcionales
+  opcional: z.string().optional(),
+  // arreglos anidados
+  items: z.array(z.object({
+    subcampo: z.string().min(1, 'subcampo es requerido'),
+  })).min(1, 'items debe tener al menos un elemento'),
+});
+
+export type InputDto = z.infer<typeof InputSchema>;
+```
+
+### Reglas
+
+1. **El esquema Zod vive en el controlador.** El archivo `adapters/controller/input.dto.ts` contiene el `InputSchema` con tipos primitivos (`z.string()`, `z.number()`). El tipo `InputDto` se infiere con `z.infer<typeof InputSchema>`. No se permite definir el tipo manualmente — el esquema es la fuente única de verdad.
+
+2. **El controlador traduce primitivas → dominio.** El `adapter.ts` usa el `InputSchema` para validar, luego mapea `string` → `WarehouseId`, `number` → `Quantity`, etc. Al construir el tipo de dominio se aplican sus invariantes ([A-007](../foundational/A-007-data-contract-fail-fast.md)): un valor externo inválido se rechaza en la frontera y nunca llega al caso de uso. El caso de uso recibe **tipos de dominio**: value objects donde el dominio los modela, y primitivos tipados por el dominio donde el dominio modela el concepto como primitivo ([A-050](../foundational/A-050-el-caso-de-uso-pide-al-dominio-no-lee-su-representacion.md)); la resolución de opcionalidad y defaults sigue en el caso de uso ([T-005](./T-005-input-optionality-use-case-not-entity.md)).
+
+   El controlador **retorna `TaskExecution`** (lazy, [A-044](../foundational/A-044-composicion-funcional-procesos-operaciones.md)) y compone la invocación del caso de uso con `TE.chain`/`TE.map`; la ejecución ocurre cuando el transporte invoca la tarea. Al construir los value objects del input con `Xxx.of(...)`, un VO que rechaza el valor **propaga su error por el canal** (`TE.fromError`/`E.fromValidation`), nunca lanza: `Xxx.of(...).getValue()` sobre un `Validation` inválido lanza una excepción, así que la construcción se verifica (`isValid()`/`isInvalid()`) o se compone — no se asume válida.
+
+3. **Validaciones mínimas; las invariantes viven en el artefacto del dominio.** El esquema Zod del controlador valida solo la forma de la representación externa (tipos, presencia, arrays no vacíos) y no duplica las reglas del concepto. Las invariantes — formato, longitud, charset — viven en el `rules()` del artefacto del dominio ([T-001](./T-001-ddd-artifact-validation-zod-primitives.md)). Ejemplo: `.min(1)` descarta el string vacío, `WarehouseId.rules()` descarta un `warehouseId` mal formado, y que exista el almacén lo resuelve el caso de uso.
+
+4. **Campos opcionales usan `.optional()`.** Siguiendo [T-005](./T-005-input-optionality-use-case-not-entity.md), la opcionalidad del input se refleja en Zod con `.optional()`. El caso de uso es responsable de resolver defaults e inferencias.
+
+5. **Esquemas anidados para objetos compuestos.** Si el InputDto contiene arrays de objetos o discriminated unions, se definen esquemas intermedios (`ItemSchema`, `DocumentSchema`) para mantener legibilidad.
+
+6. **Mensajes de error en español.** Los mensajes de las validaciones Zod van en español, consistentes con el resto de la base de código.
+
+### InputDto vacío o trivial
+
+- El InputDto es vacío (`{}`) o solo tiene un campo trivial — en este caso el esquema es `z.object({})` y el tipo es `{}`. Sigue siendo válido exportarlo para mantener la convención.
+
+## Consecuencias
+
+### Positivas
+
+- **Fuente única de verdad**: el esquema Zod define tanto la validación runtime como el tipo TypeScript. No hay duplicación.
+- **Consumidores homogéneos**: el CLI, NestJS, tests y cualquier otro consumidor importan el mismo esquema.
+- **Introspección**: `InputSchema.shape` permite que el CLI genere prompts dinámicos sin conocer los casos de uso de antemano.
+- **Documentación viva**: el esquema Zod es más legible que una interfaz TypeScript para describir la forma del input.
+
+### Negativas
+
+- **Dependencia de Zod**: los controladores de feature ahora dependen de `zod`. Zod ya es dependencia del proyecto ([T-001](./T-001-ddd-artifact-validation-zod-primitives.md)), por lo que no introduce un nuevo paquete.
+- **Posible divergencia**: si el esquema Zod y el `InputDto` manual se definen por separado, pueden divergir. Se mitiga usando `z.infer` como fuente del tipo.