orquestador/specs/AVAILABLE_EVENTS.md

Eventos disponibles y tareas — T13

GET /api/v1/requests/{id}/available-events está habilitado con REQUEST_API_ENABLED=true. Retorna AvailableEvents del contrato existente: requestId, revision, events, blocked y, cuando aplica, blockedByExecutionId. Requiere JWT válido y propiedad/ámbito de la solicitud; FLOW_ADMIN no permite consultar recursos ajenos.

Cada evento incluye su inputSchema publicado y, si hay una tarea asociada, metadatos ui de FORM o DOCUMENT_UPLOAD. No se crea una interfaz gráfica, un servidor de archivos ni otro motor de tareas. La aplicación cliente puede usar estos datos para mostrar su formulario/carga documental.

Selección y consistencia

• Usa el flow_id fijado a la solicitud, incluso si está RETIRED o existe una nueva versión activa para otras solicitudes.
• Solo incluye transiciones del estado actual con un rol permitido del actor. Los eventos de otros roles se omiten, sin exponer sus schemas o guardias.
• PENDING, RUNNING, RETRY_WAIT y RECONCILIATION_REQUIRED ocultan todos los eventos y tareas; blockedByExecutionId identifica la ejecución activa.
• Una guardia evaluable con datos actuales de solicitud/actor que es falsa devuelve GUARD_NOT_SATISFIED en blocked. Un error de evaluación devuelve EVALUATION_ERROR, sin rutas, valores ni detalle interno.
• Si cualquier parte de la guardia depende de event.data, se difiere la guardia completa al POST. El evento permanece visible para capturar esos datos. Esto también aplica a EXISTS/NOT: ausencia de payload en GET no significa que el futuro evento carecerá del campo.

Una sola sentencia SQL obtiene solicitud, definición y ejecución activa con una vista MVCC consistente, sin locks de fila. No llama proveedores. La respuesta es orientativa y puede quedar desactualizada inmediatamente: POST revalida siempre roles, revisión, estado, guardia y ausencia de otra ejecución.

Cache-Control: no-store. No se emite ETag en este endpoint: disponibilidad cambia por roles y estado técnico, aunque revision no cambie. Usar revision de la respuesta para formar If-Match al enviar el evento, o volver a consultar GET de solicitud. El POST puede responder 409/412 si hubo una carrera.

Documentos

El cliente envía documentId conforme al inputSchema. No envía MIME, tamaño, checksum, resultado antimalware, score o resultado de validación como autoridad. REGISTER_DOCUMENT obtiene los metadatos del servicio documental configurado y comprueba identidad, solicitud/ámbito, tipo, MIME, tamaño, checksum SHA-256 y scanStatus=CLEAN.

DocumentMetadata centraliza la verificación pura. El worker aplica adicionalmente los límites más restrictivos del DOCUMENT_UPLOAD publicado antes de guardar referencia/checkpoint, y también al reutilizar un checkpoint. Ejemplo: si el catálogo admite 5 MiB y PNG/PDF, pero la tarea solo 1000 bytes/PDF, 1001 bytes o PNG se rechazan. La referencia y su checkpoint mantienen la transacción/fencing T11. Los registros existentes se reutilizan únicamente si todos sus metadatos coinciden.

MIME real, checksum y análisis antimalware provienen del servicio documental confiable. El orquestador no descarga bytes para recalcularlos ni ejecuta un antivirus local. INFECTED/PENDING o metadatos inválidos no generan referencia ni se convierten en un resultado de negocio VALID/INVALID. Sin proveedor configurado no se fabrica éxito; los mocks existen únicamente en las pruebas.

DOCUMENTO_VALIDA es una acción posterior independiente. INVALID técnicamente válido puede producir SUCCEEDED/DOCUMENTO_INVALIDO y mantener el mismo estado/tarea; las razones quedan en los datos de solicitud mediante mappings explícitos del flujo. GET de solicitud expone esos datos autorizados. No se agregan campos de razón libres al contrato de available-events.

Un timeout/503 del validador produce reintentos técnicos y bloquea eventos; al agotarlos de forma segura, FAILED conserva el estado previo y permite volver a intentar. No se inventa INVALID ni se sobrescribe la última validación de negocio. El checkpoint documental previo se conserva y no repite la consulta ya exitosa.

Verificación

AvailableEventPolicyTest verifica selección pura; AvailableEventsIT comprueba HTTP/JWT/PostgreSQL, versiones, roles, guardias y lectura frente a escritura concurrente. DocumentTasksIT recorre registro→validación→decisión→tarea con HTTP mock y PostgreSQL real: INVALID→nuevo evento VALID, referencias sin duplicar, documentos ajenos, MIME/tamaño de tarea, checksum/antimalware, error técnico y rechazo de payloads con datos de proveedor (A11/A20).

Ejecutar mvnw.cmd clean verify -Pmigration-tests-external con credenciales de orquestador_test solo en MIGRATION_TEST_DB_*. Sin ese perfil, verify requiere Docker/Testcontainers. No se desplegó ni se usaron documentos o proveedores reales.