orquestador/specs/IMPLEMENTATION_PLAN.md

Plan de implementación

Fecha: 2026-10-26. Fuente normativa: especificación, secciones 13–16.

El alcance actual es crear el arquetipo y dejar preparada la ejecución del plan. La implementación funcional continúa por tareas autorizadas. Una sola tarea principal IN_PROGRESS; elegir la primera pendiente con dependencias DONE. Un bloqueo externo se documenta y no equivale a una prueba aprobada.

Secuencia y criterios

ID	Tarea	Dependencias	Criterio de cierre
T01	Bootstrap y ADR de versiones	—	Wrapper reproducible, compilación y health local comprobados
T02	Contratos OpenAPI y JSON Schema del DSL	T01	OpenAPI 3.1 y schemas completos; ejemplos validados
T03	Modelo PostgreSQL y Flyway	T02	Restricciones e inmutabilidad verificadas en PostgreSQL real
T04	Modelo de dominio y puertos	T02,T03	Dominio sin HTTP/JPA y contratos tipados
T05	Evaluador de decisiones	T04	A04–A06 y errores de evaluación comprobados
T06	Validador, publicación y activación	T03,T04,T05	A16–A17; catálogo resoluble y publicación consistente
T07	Seguridad y autorización por recurso	T04	A15; rutas protegidas antes de exposición
T08	Crear y consultar solicitudes	T06,T07	Creación atómica e idempotente, versión fijada
T09	Aceptar eventos idempotentes	T08	A07–A09; aceptación durable sin HTTP
T10	Worker PostgreSQL y leases	T09	Cola durable multiinstancia; worker obsoleto no confirma
T11	Handlers e integraciones HTTP	T10	A01–A03; fallos técnicos separados del resultado de negocio
T12	Reintentos y conciliación	T11	A12–A14,A19; efectos inciertos no liberan solicitud
T13	Documentos y tareas para front	T11,T12	A11,A20; INVALID conserva tarea, error técnico no equivale a INVALID
T14	Flujos demostrativos v1/v2	T05,T06,T13	A10,A18; dos tipos de solicitud publicables
T15	Auditoría y observabilidad	T09,T10,T11,T12,T13,T14	Auditoría atómica desde T06 y operación observable
T16	Verificación integral	T15	Todos los casos obligatorios pasan en entorno reproducible
T17	Empaquetado y documentación	T16	Checkout limpio reproduce definición final de terminado

T01 — Bootstrap y ADR de versiones

Dependencias: —. Entregables: pom.xml, mvnw*, .mvn, configuración, ADR-001.

• Fijar versiones y BOM.
• Generar Wrapper oficial.
• Preparar paquetes y configuración.
• Ejecutar compilación y smoke test de salud con JDK 21/PostgreSQL.

Verificación: JDK 21; ./mvnw clean verify; arranque local y HTTP health. Cierre: Wrapper reproducible, compilación y health local comprobados.

Cerrado el 2026-10-26: clean verify -Pdeployment-smoke -Dsmoke.baseUrl=http://server02:8787 con JDK 21.0.12.1 y Maven 3.9.12, 5 pruebas aprobadas, 0 omitidas. Compilación en el equipo de desarrollo y smoke sobre el despliegue de la red local con PostgreSQL externo, conforme a ADR-004. Evidencia detallada en PROGRESS.

T02 — Contratos OpenAPI y JSON Schema del DSL

Dependencias: T01. Entregables: contracts/openapi.yaml, schemas/, ejemplos contractuales.

• Definir rutas, DTOs y errores.
• Definir schema del flujo/AST/tareas.
• Validar ejemplos y casos inválidos automáticamente.

Verificación: Validador OpenAPI/JSON Schema dentro de verify. Cierre: OpenAPI 3.1 y schemas completos; ejemplos validados.

Cerrado el 2026-10-26: clean verify con Java 21, 92 comprobaciones, 0 fallos/errores/omisiones. Contrato de 14 operaciones, DSL 2020-12, DTOs y resultados normalizados de ejemplo. Las pruebas verifican estructura/ejemplos/referencias, no comportamiento del motor; ver ADR-005 y evidencia E10.

T03 — Modelo PostgreSQL y Flyway

Dependencias: T02. Entregables: db/migration/, pruebas *IT.

• Crear tablas, FKs e índices.
• Añadir idempotencia de creación/admin_audit/reconciliation_resolution.
• Proteger inmutabilidad e historial con roles y triggers.
• Probar migraciones desde cero.

Verificación: Testcontainers PostgreSQL, rollback y migraciones. Cierre: Restricciones e inmutabilidad verificadas en PostgreSQL real.

T04 — Modelo de dominio y puertos

Dependencias: T02,T03. Entregables: flow/, request/, execution/, decision/, action/.

• Definir records y errores estables.
• Separar DTOs y entidades.
• Implementar puertos DecisionEvaluator, ActionHandler y FlowDefinitionValidator.

Verificación: Pruebas de dominio y dependencias entre capas. Cierre: Dominio sin HTTP/JPA y contratos tipados.

T05 — Evaluador de decisiones

Dependencias: T04. Entregables: decision/, pruebas de AST.

• Implementar operadores/JSON Pointer/BigDecimal.
• Distinguir null y ausente.
• Aplicar límites y cortocircuito.
• Resolver UNIQUE/FIRST y ambigüedad.

Verificación: JUnit parametrizado: 71/70/61/60, tipos y solapamientos. Cierre: A04–A06 y errores de evaluación comprobados.

T06 — Validador, publicación y activación

Dependencias: T03,T04,T05. Entregables: flow/, admin_audit, pruebas *IT.

• Validar grafo, mappings, roles y capacidades.
• Editar borradores con revision.
• Publicar checksum canónico e inmutabilidad.
• Activar/retirar con bloqueos y auditoría.

Verificación: Pruebas PostgreSQL de carreras publicación/activación/retiro. Cierre: A16–A17; catálogo resoluble y publicación consistente.

T07 — Seguridad y autorización por recurso

Dependencias: T04. Entregables: shared/infrastructure/security/, autorización por capacidad.

• Validar JWT real (firma/issuer/audience/exp).
• Mapear permisos técnicos y roles.
• Comprobar propiedad/scope en cada recurso.
• Separar rol DB de ejecución.

Verificación: Tokens firmados válidos/expirados, otro issuer/audience, scope/rol ajenos. Cierre: A15; rutas protegidas antes de exposición.

T08 — Crear y consultar solicitudes

Dependencias: T06,T07. Entregables: request/, repositorios y API.

• Resolver y fijar flujo activo.
• Validar datos iniciales.
• Idempotencia durable de creación.
• Exponer consulta y ETag con acceso por recurso.

Verificación: IT creación repetida/conflictiva y activación concurrente. Cierre: Creación atómica e idempotente, versión fijada.

T09 — Aceptar eventos idempotentes

Dependencias: T08. Entregables: execution/api, aceptación, auditoría.

• Bloquear solicitud.
• Verificar hash antes de revisión.
• Validar If-Match/rol/guardia.
• Insertar PENDING, revision y auditoría atómicamente.
• Responder 202/Location.

Verificación: IT duplicados, conflictos, concurrencia y rollback. Cierre: A07–A09; aceptación durable sin HTTP.

T10 — Worker PostgreSQL y leases

Dependencias: T09. Entregables: execution/infrastructure, worker y repositorios.

• Reclamar con SKIP LOCKED.
• Renovar lease con tiempo DB.
• Exigir owner/token en escrituras.
• Checkpoints por acción y recuperación inicial.

Verificación: IT dos workers, lease vencido y checkpoint; no @Async en memoria. Cierre: Cola durable multiinstancia; worker obsoleto no confirma.

T11 — Handlers e integraciones HTTP

Dependencias: T10. Entregables: action/, integration/, mocks, compose.yaml.

• Implementar catálogo confiable y REGISTER_DOCUMENT/INVOKE_INTEGRATION/NO_OP sólo simulación.
• Fijar contratos/perfiles.
• Mapear entradas/salidas y timeouts.
• Añadir mocks.

Verificación: Mocks de cliente encontrado/no encontrado, timeout y salida inválida. Cierre: A01–A03; fallos técnicos separados del resultado de negocio.

T12 — Reintentos y conciliación

Dependencias: T11. Entregables: execution/, endpoint resolve, pruebas *IT.

• Limitar intentos/backoff/jitter.
• Recuperar leases según clasificación de efecto.
• Tratar UNKNOWN.
• Conciliar con evidencia y autorización/idempotencia.

Verificación: Fault injection antes/después de envío, checkpoint y commit. Cierre: A12–A14,A19; efectos inciertos no liberan solicitud.

T13 — Documentos y tareas para front

Dependencias: T11,T12. Entregables: document/, request/available-events.

• Verificar pertenencia/tipo/MIME/tamaño/checksum/antimalware.
• Guardar referencias.
• Exponer schemas/UI y bloqueos.
• Impedir escritura de resultados del proveedor.

Verificación: Documento ajeno/inválido, ejecución activa y payload con score. Cierre: A11,A20; INVALID conserva tarea, error técnico no equivale a INVALID.

T14 — Flujos demostrativos v1/v2

Dependencias: T05,T06,T13. Entregables: examples/flows/, examples/http/.

• Crear crédito v1, crédito v2 con licencia y compra v1 completos.
• Publicar/activar y recorrer.
• Demostrar coexistencia de versiones sin cambios Java/columnas.

Verificación: Recorridos completos de v1/v2, licencia válida/inválida y fronteras. Cierre: A10,A18; dos tipos de solicitud publicables.

T15 — Auditoría y observabilidad

Dependencias: T09,T10,T11,T12,T13,T14. Entregables: audit/, métricas, logs, health.

• Completar consultas paginadas/filtradas.
• Métricas sin cardinalidad por solicitud.
• Logs sin PII.
• Readiness/liveness y apagado ordenado.

Verificación: Rollback/auditoría, acceso a historial, métricas y apagado. Cierre: Auditoría atómica desde T06 y operación observable.

T16 — Verificación integral

Dependencias: T15. Entregables: src/test/, CI, matriz A01–A20.

• Automatizar A01–A20.
• Reinicios y concurrencia deterministas.
• Verificar fronteras de rollback y seguridad.
• Conservar reportes.

Verificación: ./mvnw clean verify con Docker, sin skips de integración. Cierre: Todos los casos obligatorios pasan en entorno reproducible.

T17 — Empaquetado y documentación

Dependencias: T16. Entregables: Dockerfile, compose.yaml, README, RUNBOOK, examples/http, CI.

• Construir imagen y Compose completos.
• Incluir mocks e issuer local documentado.
• Ejecutar demo desde checkout limpio.
• Documentar límites, recuperación y contratos reales pendientes.

Verificación: Build de imagen, compose, verify y demo completa de sección 16. Cierre: Checkout limpio reproduce definición final de terminado.

Reglas de ejecución

Antes de codificar, revisar criterios y prueba pertinente. Al cerrar, registrar fecha, archivos, comando exacto y resultado en PROGRESS. Mantener actualizados contrato, migraciones y pruebas cuando cambie el comportamiento. Auditoría mínima acompaña cada escritura desde T06; T15 completa consultas y operación. T06 puede implementar servicios internos, pero sus endpoints no se exponen antes de T07. No modificar semántica de seguridad/idempotencia/versionado sin ADR.

Matriz de aceptación

Casos	Tarea responsable	Evidencia final
A01–A03	T11	Cliente encontrado/no encontrado/fallo técnico
A04–A06	T05	Fronteras, contratos inválidos y UNIQUE ambiguo
A07–A09	T09	Idempotencia y concurrencia de eventos
A10,A18	T14	Coexistencia v1/v2 y licencia configurable
A11,A20	T13	Documentos y protección de resultados
A12–A14,A19	T12	Recuperación, efectos inciertos y rollback
A15	T07	Autorización por rol/scope/propiedad
A16–A17	T06	Inmutabilidad y activación/retiro concurrentes

T16 vuelve a ejecutar la matriz completa; pruebas unitarias no sustituyen PostgreSQL real. La integración real con proveedores permanece pendiente si faltan contrato/credenciales, aunque los mocks pasen.