# Auditoría y operación (T15)

## Historial

`GET /api/v1/requests/{id}/history` requiere REQUEST_API_ENABLED y JWT válido.
Aplica la misma propiedad y businessScope que GET de solicitud; FLOW_ADMIN y
EXECUTION_OPERATOR no tienen un bypass para consultar historial ajeno. Un recurso
ajeno/inexistente responde 404. La respuesta cumple HistoryPage y usa no-store.

Filtros opcionales: kind, executionId, from inclusivo y to exclusivo (UTC terminado
en Z). limit por defecto 50, rango 1–100. Orden ascendente por (createdAt,id),
mediante keyset; cursor opaco de máximo 2000 caracteres ligado a solicitud y filtros.
Se permite cambiar limit conservando los demás filtros. Al terminar se omite
nextCursor. Cursor inválido o usado con otros filtros devuelve 400.

El cursor representa posición, no autorización ni una credencial firmada. Cada
página vuelve a autorizar el recurso; modificar una posición nunca amplía su acceso.
Los inserts concurrentes pueden aparecer en páginas posteriores; no es una foto
transaccional de toda la navegación. Reiniciar desde from permite releer períodos
cuando hay transacciones que confirmaron tarde. El consumidor deduplica por id.

Proyección de detail permitida: correlationId, transitionId, acceptedRevision,
ruleIds, reasonCodes, actionIds, hitPolicy, code, actionId, delayMs, mode y resolutionId.
Se omiten datos de entrada, resultados completos, tokens y evidencia del operador.
actorSubject se entrega únicamente al propietario autorizado. Nuevas transiciones
guardan reasonCodes de resultados de acciones cuando existen; no se reconstruyen
razones para auditorías históricas que no las contenían.

Se mantienen las escrituras atómicas T06–T12 y triggers append-only V2. No hay una
segunda escritura de auditoría posterior al commit ni una migración nueva. El rol
runtime no modifica ni elimina historial. Retención/eliminación requiere una política
de datos aprobada y procedimiento privilegiado aparte; este servicio no borra
auditoría automáticamente ni interpreta un TTL como permiso de borrado.

## Métricas

`/actuator/metrics` y `/actuator/metrics/{name}` requieren EXECUTION_OPERATOR y
businessScope incluido en ADMIN_BUSINESS_SCOPES. No dependen de habilitar edición
de flujos. Actuator restante está denegado salvo las tres rutas públicas de salud.
No se agrega servidor Prometheus ni dependencia nueva; Micrometer/Actuator ya están
incluidos en el servicio.

| Nombre | Tipo/etiquetas | Significado |
| --- | --- | --- |
| orchestrator.commands | Counter: command=create/event; result=accepted/rejected/error | Respuestas HTTP de comandos, incluidos replays; accepted es 2xx, error 5xx y rejected resto |
| orchestrator.executions | Gauge: state fijo | Filas durables por estado técnico, compartidas entre réplicas |
| orchestrator.pending.oldest.seconds | Gauge sin etiquetas | Edad DB del PENDING más antiguo; cero sin pendientes |
| orchestrator.leases.expired | Gauge sin etiquetas | RUNNING con lease vencido; no implica efecto externo duplicado |
| orchestrator.queue.sample.available | Gauge sin etiquetas | 1 muestra SQL disponible; 0 fallo; demás gauges NaN al fallar |
| orchestrator.integration.duration | Timer: integration, result=completed/failed/error | Tiempo del adapter HTTP, incluido contrato/mapeo; solo claves del catálogo/rutas permitidas |

Los gauges se consultan bajo demanda y comparten una muestra SQL por proceso de
5 segundos; query timeout 3 segundos. Son estados actuales, no contadores históricos
de transiciones. RECONCILIATION_REQUIRED expone conciliaciones pendientes y RETRY_WAIT
reintentos programados. No hay etiquetas por UUID, sujeto, ámbito, URL, perfil,
excepción libre o datos de proveedor. Las claves de integración pertenecen a
configuración confiable. Contadores/timers locales se reinician con el proceso;
no son el ledger durable. Para varias réplicas no sumar gauges de la misma DB.

## Logs y correlación

El filtro genera X-Correlation-Id; no confía en uno suministrado por el cliente.
Comandos registran tipo, resultado HTTP, código de estado, correlación y duración.
Worker registra requestId, executionId, flowId, versión; acciones añaden actionId,
intento, resultado técnico y duración. `phase=committed` se emite después del commit.
Un log de acción completada puede preceder un rollback: consultar ejecución/historial
para el resultado durable. No registra payload, documento, sujeto, token, score,
evidencia ni excepción con body de proveedor. correlationId de EVENT_ACCEPTED enlaza
HTTP con executionId del historial y del worker; el adapter propaga executionId
como X-Correlation-Id estable entre intentos. Las decisiones y razones quedan en
auditoría restringida, no en logs.

## Salud y apagado

`/actuator/health/liveness` consulta disponibilidad del proceso, sin DB/proveedores.
`/actuator/health/readiness` añade PostgreSQL; falla 503 cuando DB no está disponible.
`/actuator/health` es salud agregada. Las rutas públicas omiten detalles/componentes.
No se llama a clientes/documentos/buró para determinar salud.

Spring usa server.shutdown=graceful y 30 s por fase. El worker deja de reclamar,
cierra el poller (hasta 2 s) y conserva heartbeats mientras drena trabajos durante
WORKER_SHUTDOWN_SECONDS (1–20, predeterminado 20). Al agotar, interrumpe trabajos y
espera 1 s adicional; cancela renovaciones. Los adapters deben respetar interrupción
y sus límites de tiempo. Una operación no cooperativa puede seguir hasta su timeout;
no se presume cancelación de un efecto externo. Cola/checkpoints permanecen durables
y se recuperan por lease/fencing y conciliación T12. No se liberan leases por apagar.
Compose mantiene stop_grace_period=40s para la JVM y PostgreSQL externo.

## Verificación

ObservabilityIT usa API/JWT real, esquema y rol temporales en orquestador_test:
historial/ACL/filtros/cursor/empates, métricas SQL, Actuator y logs con sentinelas.
Cierra únicamente su propio pool para demostrar readiness 503/liveness 200.
ObservabilityTest usa latches y worker real con store controlado para drenaje,
renovación e interrupción dentro del presupuesto; HTTP loopback prueba timers.
WorkerIT conserva pruebas reales de rollback de auditoría, recuperación y fencing.
No es una prueba de despliegue Docker ni de caída de PostgreSQL de producción.

Fuentes de API: [Micrometer](https://docs.micrometer.io/micrometer/reference/concepts/meters.html)
y [Actuator Health](https://docs.spring.io/spring-boot/api/rest/actuator/health.html).